Send requests via HTTP/2 to a web service.

NB: all examples have this module aliased

alias Ace.HTTP2.Client

Establish connection

To make requests, a client must have an open connection to the server. A client process is started to manage this connection.

{:ok, client} = Client.start_link("http2.golang.org")
# OR
{:ok, client} = Client.start_link({"http2.golang.org", 443})

Ace.HTTP2 only supports communication over TLS. It will attempt open a TLS connection for all port values.

Reliable connections

When a connection is lost the client process terminates. A reliable connection can be achieved by supervising the client process.

children = [
  worker(Client, ["http2.golang.org", [name: MyApp.Client]])
]

A supervised client should be referenced by name.

Opening a stream

Sending a request will automatically open a new stream. The request consists of the headers to send and if it has a body. If the body is false or included in the request as a binary, the stream will be half_closed(local) once request is sent.

A client will accept a request with a binary value for the body. In this case the body is assumed complete with no further data to stream

{:ok, stream} = Client.stream(client)
request = Raxx.request(:GET, "/")
|> Raxx.set_header("accept", "application/json")
:ok = Ace.HTTP2.send(stream, request)

{:ok, stream} = Client.stream(client)
request = Raxx.request(:POST, "/")
|> Raxx.set_header("content-length", "13")
|> Raxx.set_body("Hello, World!")
:ok = Ace.HTTP2.send(stream, request)

request = Raxx.request(:POST, "/")
|> Raxx.set_header("content-length", "13")
|> Raxx.set_body(true)
:ok = Ace.HTTP2.send(stream, request)
data = Raxx.data("Hello, World!")
{:ok, _} = Ace.HTTP2.send(stream, data)

Receiving a response

All data sent from the server if forwarded to the stream owner. The owner is the process that initiated the stream.

receive do
  {^stream, %Raxx.Response{body: true}} ->
    :ok
end
receive do
  {^stream, %Raxx.Data{data: "Hello, World!"}} ->
    :ok
end

Response bodies will always be sent as separate messages to the stream owner.

A complete response may be built using the collect_response/1

{:ok, %Raxx.Response{status: 200, body: "Hello, World!"}} = Client.collect_response(stream)

Simple request response

The Ace.Client aims to make the asynchronous stream of data easy. If this is not needed a synchronous interface is provided.

{:ok, response} = Client.send_sync(connection, request)

Examples

See the client tests for more examples.