ankh v0.4.2 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 controlling_process 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 controlling_process. 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 controlling_process 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 controlling_process as data msg.

See typespecs below for message types and formats.

Link to this section Summary

Types

Startup options:

  • controlling_process: pid of the process to send received frames to. Messages are shipped to the calling process if nil.
  • ssl_options: SSL connection options, for the Erlang :ssl module

Connection process

Ankh DATA message (full mode)

Ankh HEADERS message

Ankh PUSH_PROMISE message

Ankh DATA frame (streaming mode)

Functions

Returns a specification to start this module under a supervisor

Closes the connection

Connects to a server

Sends a frame over the connection

Updates send settings for the connection

Start the connection process for the specified URI

Starts a new stream on the connection

Updates the connection window_size with the provided increment

Link to this section Types

Link to this type args()
args() :: [
  uri: URI.t(),
  controlling_process: pid() | nil,
  ssl_options: Keyword.t()
]

Startup options:

  • controlling_process: pid of the process to send received frames to. Messages are shipped to the calling process if nil.
  • ssl_options: SSL connection options, for the Erlang :ssl module
Link to this type connection()
connection() :: GenServer.server()

Connection process

Link to this type data_msg()
data_msg() :: {:ankh, :data, Integer.t(), binary()}

Ankh DATA message (full mode)

{:ankh, :data, stream_id, data}

Link to this type headers_msg()
headers_msg() :: {:ankh, :headers, Integer.t(), Keyword.t()}

Ankh HEADERS message

{:ankh, :headers, stream_id, headers}

Link to this type 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}

Link to this type streaming_data_msg()
streaming_data_msg() :: {:ankh, :stream_data, Integer.t(), binary()}

Ankh DATA frame (streaming mode)

{:ankh, :stream_data, stream_id, data}

Link to this section Functions

Link to this function child_spec(arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function close(connection)
close(connection()) :: :closed

Closes the connection

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

Link to this function connect(connection)
connect(connection()) :: GenServer.on_call()

Connects to a server

Link to this function send(connection, frame)

Sends a frame over the connection

Link to this function send_settings(connection, settings)
send_settings(connection(), Ankh.Frame.Settings.Payload.t()) ::
  GenServer.on_call()

Updates send settings for the connection

Link to this function start_link(args, options \\ [])
start_link(args(), GenServer.options()) :: GenServer.on_start()

Start the connection process for the specified URI.

Parameters:

  • args: startup options
  • options: GenServer startup options
Link to this function start_stream(connection, mode)

Starts a new stream on the connection

Link to this function window_update(connection, increment)
window_update(connection(), Integer.t()) :: GenServer.on_call()

Updates the connection window_size with the provided increment