ankh v0.1.1 Ankh.Connection

Genserver implementing HTTP/2 connection management

Ankh.Connection establishes the underlying TLS connection and provides connection and stream management, it also does frame (de)serialization and reassembly as needed.

After starting the connection, received frames are sent back to the caller, or the process specified in the receiver startup option, as messages. Separate messages are sent for HEADERS, PUSH_PROMISE and DATA frames.

Headers are always reassembled and sent back in one message to the receiver. For data frames, the stream startup otion toggles streaming mode:

If true (streaming mode) a stream_data msg is sent for each received DATA frame, and it is the receiver responsibility to reassemble incoming data.

If false (full mode), DATA frames are accumulated until a complete response is received and then the complete data is sent to the receiver as data msg.

See typespecs below for message types and formats.

Summary

Types

Ankh Connection process

Ankh DATA message (full mode)

Ankh HEADERS message

Startup options:

  • receiver: pid of the process to send response messages to. Messages are shipped to the calling process if nil.
  • stream: if true, stream received data frames back to the receiver, else reassemble and send complete responses.
  • ssl_options: SSL connection options, for the Erlang :ssl module

Ankh PUSH_PROMISE message

Ankh DATA frame (streaming mode)

Functions

Closes the connection

Connects to a server via the specified URI

Sends a frame over the connection

Start the connection process for the specified URI

Types

connection()

Ankh Connection process

data_msg()
data_msg :: {:ankh, :data, Integer.t, binary}

Ankh DATA message (full mode)

{:ankh, :data, stream_id, data}

headers_msg()
headers_msg :: {:ankh, :headers, Integer.t, Keyword.t}

Ankh HEADERS message

{:ankh, :headers, stream_id, headers}

options()
options :: [receiver: pid | nil, stream: boolean, ssl_options: Keyword.t]

Startup options:

  • receiver: pid of the process to send response messages to. Messages are shipped to the calling process if nil.
  • stream: if true, stream received data frames back to the receiver, else reassemble and send complete responses.
  • ssl_options: SSL connection options, for the Erlang :ssl module
push_promise_msg()
push_promise_msg :: {:ankh, :push_promise, Integer.t, Integer.t, Keyword.t}

Ankh PUSH_PROMISE message

{:ankh, :headers, stream_id, promised_stream_id, headers}

streaming_data_msg()
streaming_data_msg :: {:ankh, :stream_data, Integer.t, binary}

Ankh DATA frame (streaming mode)

{:ankh, :stream_data, stream_id, data}

Functions

close(connection)
close(connection) :: :closed

Closes the connection

Before closing the TLS connection a GOAWAY frame is sent to the peer.

Parameters:

  • connection: connection process
connect(connection, uri)
connect(connection, URI.t) :: :ok | {:error, atom}

Connects to a server via the specified URI

Parameters:

  • connection: connection process
  • uri: The server to connect to, scheme and authority are used
send(connection, frame)
send(connection, Ankh.Frame.t) :: :ok | {:error, atom}

Sends a frame over the connection

Parameters:

  • connection: connection process
  • frame: Ankh.Frame structure
start_link(list, options \\ [])
start_link([receiver: pid | nil, stream: boolean, ssl_options: Keyword.t], GenServer.option) :: GenServer.on_start

Start the connection process for the specified URI.

Parameters:

  • args: startup options
  • options: GenServer startup options