Giter Site home page Giter Site logo

hyper's Introduction

Hyper

Straightforward, full-featured Web client that composes with Dream.


Lwt_main.run begin
  let%lwt response = Hyper.get "http://google.com" in
  print_string response;
  Lwt.return_unit
end

Note: the client is not actually full-featured yet :) This README is also an extremely rough sketch :) This repository is a work in progress

Hyper is the client counterpart to Dream, the Web server framework. Hyper uses the same types and the same programming model. Like Dream, Hyper offers one module, which features a bunch of easy-to-use functions. Also like Dream, Hyper still exposes the underlying highly composable functions, for full customization.


Documentation

At the moment, Hyper offers only three main "stable" values:

Hyper.get : string -> string promise
Hyper.post : string -> string -> string promise
Hyper.websocket : string -> websocket promise

These support all the same Web protocols as Dream: HTTP/1, HTTP/2, TLS, and WebSocket, and they follow redirects. The protocols are selected using URI schemes:

Hyper.get "http://google.com"
Hyper.post "https://some.app/endpoint" "{}"
Hyper.websocket "ws://some.site/socket"

You can see early usage in the examples.

These are actually wrappers around a "stack" of request -> response promise handlers and client-side middlewares, but the elements of that stack are not mature enough to expose yet. They will eventually be exposed to quickly build custom clients with any desired behavior.

For testing WebSockets, Hyper offers an interface similar to the one in Dream:

Hyper.send : websocket -> string -> unit promise
Hyper.receive : websocket -> string option promise
Hyper.close_websocket : websocket -> unit promise

Composability

A Hyper client and a Dream server have exactly the same type, request -> response promise.

This means that the client's lowest layer can be implemented by swapping out connecting over the network by a direct call to an in-process Dream server, which can be useful for no-network testing.

Conversely, a Dream server can pass the requests it receives to a Hyper client, thus acting as a proxy. Responses received from the proxy client can be directly returned by the server to its client.

In all cases, all body streams and WebSockets get forwarded automatically as a side effect of the conventions followed by Hyper and Dream.


Roadmap

  • Restore connection pooling and multiplexing.
  • ๐Ÿ›‘ Server certificate validation.
  • File uploads (multipart streams).
  • Cookie store.
  • Redirect cache.
  • Automatic decompression.
  • wss:// (WebSockets over TLS).
  • Many miscellania.

Contact

Open an issue, or visit...

Highlight @antron to poke @aantron specifically.


Contributing

To work on Hyper, clone Dream and Hyper into a single Dune workspace:

mkdir my-directory
cd my-directory
touch dune-workspace
git clone --recursive https://github.com/aantron/dream.git
git clone https://github.com/aantron/hyper.git
cd hyper

Acknowledgements

As with Dream, Hyper makes extensive use of the http/af-like Web protocol stack by Antonio Nuno Monteiro.

hyper's People

Contributors

aantron avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar

hyper's Issues

MirageOS compatibility

Again ๐Ÿ™‚ . However, for the client part of the HTTP protocol, the MirageOS is slightly more complex. Indeed, a connect function which allocates a resource (such as a socket) is an anti-pattern for MirageOS due to one fact: the connect function depends inherently to the implementation. For the MirageOS perspective, an application should not depend on a specific implementation and we mostly want to play with interfaces instead of their implementations (which depends on the target chosen by the user).

This is the reason of the conduit existence and/or the mimic existence. They want to hide the implementation-related connect function into a Conduit.resolve/Mimic.resolve. Then, a ceremony is needed to explain to conduit/mimic which implementation you to use to connect this kind of connection.

In the case of conduit, you express that you want TCP 80 or TLS (TCP 443)) for instance regardless the implementation used then to give to your a Mirage_flow.S - it can be lwt_ssl + lwt.unix, ocaml-tls + lwt.unix or ocaml-tls + mirage-tcpip (or something else). However, we got many troubles to extend conduit to some others protocols such as Git.

mimic wants to replace conduit by the extensible ability depending on what the user want. It's why it exists a Git client with mimic and an HTTP client (with paf-cohttp) with mimic. But for more details about mimic, please read the documentation: https://dinosaure.github.io/mimic/mimic/index.html

More concretely, a MirageOS compatibility expects, at least, one thing, an interface (like what provides hyper) which should let the user to pass a ctx (the conduit context or the mimic context). An high-level explanation about this context is available here: https://github.com/mmaker/ocaml-letsencrypt/blob/c07348604bb94eaab9522fe87e455bb729e5d1d8/src/hTTP_client.ml#L2-L24. Then, if we are able to initiate a connection via mimic:

  1. we can provide a default mechanism (as git-unix does for instance) which permits to instantiate a Mirage_flow.S used by the runtime loop then (for h2 or http/af)
  2. let the mirage to provide its own context depending on implementation chosen by the user

Handshake error when querying medium over HTTPS

When running the following request:

let () =
  let _ =
    Lwt_main.run @@ Hyper.get "https://medium.com:443/feed/ahrefs/tagged/ocaml"
  in
  ()

I'm seeing the following error:

Fatal error: exception SSL connection() error: error:0A000410:SSL routines::sslv3 alert handshake failure

I don't reproduce this error in any other domain and RSS feeds I've tried to query.

Openssl EOF error

I am using dream to call hyper to make requests to Turso over http. When I send get or post requests, I get this:

27.02.24 05:51:45.557       dream.log  INFO REQ 1 GET /turso/get 127.0.0.1:46574 Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTM6
27.02.24 05:51:45.635       dream.log  WARN REQ 1 Aborted by: SSL connection() error: error:14:000126:SSL routines::unexpected eof while reading
27.02.24 05:51:45.635       dream.log  WARN Raised by primitive operation at Ssl in file "src/ssl.ml", line 785, characters 14-33
27.02.24 05:51:45.635       dream.log  WARN Called from Lwt_ssl.wrap_call in file "src/lwt_ssl.ml", line 47, characters 4-8
27.02.24 05:51:45.635       dream.log  WARN Re-raised at Lwt_ssl.wrap_call in file "src/lwt_ssl.ml", line 57, characters 7-14
27.02.24 05:51:45.635       dream.log  WARN Called from Lwt_unix.retry_syscall in file "src/unix/lwt_unix.cppo.ml", line 509, characters 13-24
27.02.24 05:51:45.635       dream.log  WARN Re-raised at Hyper__http__Connect.alpn_https_tcp.(fun) in file "src/http/connect.ml", line 90, characte0
27.02.24 05:51:45.635       dream.log  WARN Re-raised at Hyper__http__Connect.no_pool.(fun) in file "src/http/connect.ml", line 165, characters 2-85
27.02.24 05:51:45.635       dream.log  WARN Re-raised at Hyper__logic__Redirect.follow_redirect.redirect_loop.(fun) in file "src/logic/redirect.ml"3
27.02.24 05:51:45.635       dream.log  WARN Re-raised at Dune__exe__Turso.promise_get.(fun) in file "src/turso.ml", line 28, characters 4-325
27.02.24 05:51:45.635       dream.log  WARN Re-raised at Dune__exe__Main.(fun) in file "src/main.ml", line 51, characters 12-114
27.02.24 05:51:45.635      dream.http ERROR REQ 1 SSL connection() error: error:14:000126:SSL routines::unexpected eof while reading
27.02.24 05:51:45.635      dream.http ERROR REQ 1 Raised at Stdlib__Map.Make.find in file "map.ml", line 141, characters 10-25
27.02.24 05:51:45.635      dream.http ERROR REQ 1 Called from Logs.Tag.find in file "src/logs.ml", line 154, characters 14-32

My router code looks like this:

 let () = 
    run ~port:3000
    @@ logger
    @@ router [
        get "/turso/get" (fun _ -> 
            let%lwt str = Turso.hrana_support in
            str |> Dream.html
        );
    ]
;; 

Where my Turso module looks like this:

let url =
    match Sys.getenv_opt "TURSO_URL" with
    | Some value -> value
    | None -> failwith "TURSO_URL environment variable must be set."
;;

let hrana_support =
    let request =
        Hyper.request ~method_:`GET @@ url ^ "/v2"
    in
    let%lwt response = Hyper.run request in
    if Dream_pure.Message.status response = `OK then
        Hyper.body response
    else
        let%lwt () = Dream_pure.Message.close (Dream_pure.Message.client_stream response) in
        Lwt.fail (Hyper.Response response)
;;

The versions of my environment are:
Ocaml compiler: 5.1.1
openssl: 3.2.1
dune: 3.14

Let me know what more information is required. Thanks!

Only 200 Ok is considered successfull

I saw that successfull is defined in dream like

type successful = [
  | `OK
  | `Created
  | `Accepted
  | `Non_Authoritative_Information
  | `No_Content
  | `Reset_Content
  | `Partial_Content
]

for the simple get/post these should be considered as ok. right now 204 No_Content raises an error.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.