ace v0.12.0 Ace.HTTP2.Client View Source

Send requests via HTTP/2 to a web service.

NB: all examples have this module, Ace.Request and Ace.Response aliased

alias Ace.HTTP2.Client
alias Ace.Request
alias Ace.Response

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

request = Request.new(:GET, "/", [{"accept", "application/json"}], false)
{:ok, stream} = Client.stream(client)
:ok = Client.send_request(stream, request)

request = Request.new(:POST, "/", [{"content-length", "13"}], "Hello, World!")
{:ok, stream} = Client.stream(client)
:ok = Client.send_request(stream, request)

request = Request.new(:POST, "/", [{"content-length", "13"}], true)
{:ok, stream} = Client.stream(client)
:ok = Client.send_request(stream, request)
{:ok, _} = Client.send_data(stream, "Hello, World!", end_stream: true)

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, %Response{body: true}} ->
    :ok
end
receive do
  {^stream, %{data: "Hello, World!", end_stream: end_stream}} ->
    :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, %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.

Link to this section Summary

Functions

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

Send information over a stream

Send a complete request and wait for a complete response

End a stream with trailers

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_data(stream, data, end_stream \\ false) View Source

Add data to an open stream.

Link to this function send_request(stream, request) View Source

Send information over a stream.

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 send_trailers(stream, trailers) View Source

End a stream with trailers

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.