ace v0.14.2 Ace.HTTP2.Client View Source

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("")
# OR
{:ok, client} = Client.start_link({"", 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, ["", [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} =
request = Raxx.request(:GET, "/")
|> Raxx.set_header("accept", "application/json")
:ok = Ace.HTTP2.send(stream, request)

{:ok, stream} =
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)
fragment = Raxx.fragment("Hello, World!", true)
{:ok, _} = Ace.HTTP2.send(stream, fragment)

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}} ->
receive do
  {^stream, %Raxx.Fragment{data: "Hello, World!", end_stream: end_stream}} ->

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)


See the client tests for more examples.

Link to this section Summary


Collect all the parts streamed to a client as a single response

Send a complete request and wait for a complete response

Start a new client to establish connection with server

Start a new stream within a running connection

Link to this section Functions

Link to this function collect_response(stream) View Source

Collect all the parts streamed to a client as a single response.

Link to this function send_sync(connection, request) View Source

Send a complete request and wait for a complete response.

NOTE the request must have have body as a binary or false.

Link to this function start_link(authority, options \\ []) View Source

Start a new client to establish connection with server.

Authority consists of the combination of {host, port}

Start a new stream within a running connection.

Stream will start in idle state.