Connection

The connection layer owns an HTTP/2 connection's lifecycle: the preface handshake, SETTINGS exchange, GOAWAY, and dispatch of incoming frames to the appropriate state-machine handlers. An HTTP2Connection holds the local and remote ConnectionSettings, the set of active streams, the HPACK encoder/decoder pair, the FlowController, and the current ConnectionState.

Role signalling

The connection layer is currently server-role only. Specifically:

process_preface processes the client connection preface received over the wire from a client — i.e., the server side of the handshake.
The process_*_frame! family is exercised exclusively by server-side code paths in the current test suite.
The outbound send_* APIs (send_headers, send_data, send_goaway, etc.) are role-neutral in their signatures, but the documented exercised paths build them in server-role contexts.

Milestone 6 adds client-role connection setup — sending the preface, processing the server's SETTINGS, and verifying the outbound send_* APIs work from a client context.

State enum

PureHTTP2.ConnectionState — Module

ConnectionState

HTTP/2 connection state.

States

PREFACE: Waiting for connection preface
OPEN: Connection is active
CLOSING: Sent GOAWAY, finishing pending streams
CLOSED: Connection terminated

Error type

PureHTTP2.ConnectionError — Type

ConnectionError <: Exception

Error related to HTTP/2 connection.

Fields

error_code::UInt32: HTTP/2 error code
message::String: Error description

Connection and settings

PureHTTP2.HTTP2Connection — Type

HTTP2Connection()

Manages an HTTP/2 server-role connection. Freshly constructed connections start in the PREFACE state and transition to OPEN after process_preface successfully processes the client connection preface.

Client-role connection setup is scheduled for Milestone 6.

Fields

state::ConnectionState.T: Connection state
local_settings::ConnectionSettings: Our settings
remote_settings::ConnectionSettings: Peer's settings
streams::Dict{UInt32, HTTP2Stream}: Active streams
hpack_encoder::HPACKEncoder: HPACK encoder
hpack_decoder::HPACKDecoder: HPACK decoder
flow_controller::FlowController: Flow control manager
next_stream_id::UInt32: Next server-initiated stream ID
last_client_stream_id::UInt32: Highest client stream ID seen
goaway_sent::Bool: Whether GOAWAY has been sent
goaway_received::Bool: Whether GOAWAY has been received
pending_settings_ack::Bool: Whether we're waiting for SETTINGS ACK
lock::ReentrantLock: Thread-safe access

Example

julia> using PureHTTP2

julia> conn = HTTP2Connection();

julia> conn.state == ConnectionState.PREFACE
true

julia> success, frames = process_preface(conn, Vector{UInt8}(CONNECTION_PREFACE));

julia> success
true

julia> conn.state == ConnectionState.OPEN
true

PureHTTP2.ConnectionSettings — Type

ConnectionSettings

HTTP/2 connection settings.

Fields

header_table_size::Int: HPACK dynamic table size
enable_push::Bool: Server push enabled
max_concurrent_streams::Int: Maximum concurrent streams
initial_window_size::Int: Initial stream window size
max_frame_size::Int: Maximum frame payload size
max_header_list_size::Int: Maximum header list size

PureHTTP2.apply_settings! — Function

apply_settings!(settings::ConnectionSettings, params::Vector{Tuple{UInt16, UInt32}})

Apply received SETTINGS parameters.

PureHTTP2.to_frame — Function

to_frame(settings::ConnectionSettings) -> Frame

Create a SETTINGS frame from connection settings.

Stream lifecycle

PureHTTP2.get_stream — Function

get_stream(conn::HTTP2Connection, stream_id::UInt32) -> Union{HTTP2Stream, Nothing}

Get a stream by ID.

PureHTTP2.can_send_on_stream — Function

can_send_on_stream(conn::HTTP2Connection, stream_id::UInt32) -> Bool

Check if data can be sent on a stream. Returns false if stream doesn't exist or is not in a sendable state.

PureHTTP2.create_stream — Function

create_stream(conn::HTTP2Connection, stream_id::UInt32) -> HTTP2Stream

Create a new stream.

PureHTTP2.remove_stream — Function

remove_stream(conn::HTTP2Connection, stream_id::UInt32)

Remove a closed stream.

PureHTTP2.active_stream_count — Function

active_stream_count(conn::HTTP2Connection) -> Int

Get the number of active streams.

Preface (server role)

PureHTTP2.process_preface — Function

process_preface(conn::HTTP2Connection, data::Vector{UInt8}) -> Tuple{Bool, Vector{Frame}}

Process the client connection preface. Returns (success, response_frames).

Frame processing (server role)

PureHTTP2.process_frame — Function

process_frame(conn::HTTP2Connection, frame::Frame) -> Vector{Frame}

Process a received frame and return response frames.

PureHTTP2.process_settings_frame! — Function

process_settings_frame!(conn::HTTP2Connection, frame::Frame) -> Vector{Frame}

Process a SETTINGS frame.

PureHTTP2.process_ping_frame! — Function

process_ping_frame!(conn::HTTP2Connection, frame::Frame) -> Vector{Frame}

Process a PING frame.

PureHTTP2.process_goaway_frame! — Function

process_goaway_frame!(conn::HTTP2Connection, frame::Frame)

Process a GOAWAY frame.

PureHTTP2.process_window_update_frame! — Function

process_window_update_frame!(conn::HTTP2Connection, frame::Frame)

Process a WINDOW_UPDATE frame.

PureHTTP2.process_headers_frame! — Function

process_headers_frame!(conn::HTTP2Connection, frame::Frame) -> Vector{Frame}

Process a HEADERS frame.

PureHTTP2.process_continuation_frame! — Function

process_continuation_frame!(conn::HTTP2Connection, frame::Frame) -> Vector{Frame}

Process a CONTINUATION frame.

PureHTTP2.process_data_frame! — Function

process_data_frame!(conn::HTTP2Connection, frame::Frame) -> Vector{Frame}

Process a DATA frame.

PureHTTP2.process_rst_stream_frame! — Function

process_rst_stream_frame!(conn::HTTP2Connection, frame::Frame)

Process a RST_STREAM frame.

Outbound APIs

PureHTTP2.send_headers — Function

send_headers(conn::HTTP2Connection, stream_id::UInt32, headers::Vector{Tuple{String, String}};
             end_stream::Bool=false) -> Vector{Frame}

Create HEADERS frames for a response.

PureHTTP2.send_data — Function

send_data(conn::HTTP2Connection, stream_id::UInt32, data::Vector{UInt8};
          end_stream::Bool=false) -> Vector{Frame}

Create DATA frames for response data.

PureHTTP2.send_trailers — Function

send_trailers(conn::HTTP2Connection, stream_id::UInt32,
              trailers::Vector{Tuple{String, String}}) -> Vector{Frame}

Create HEADERS frames for trailers (with END_STREAM).

PureHTTP2.send_rst_stream — Function

send_rst_stream(conn::HTTP2Connection, stream_id::UInt32, error_code::Integer) -> Frame

Create a RST_STREAM frame.

PureHTTP2.send_goaway — Function

send_goaway(conn::HTTP2Connection, error_code::Integer, debug_data::Vector{UInt8}=UInt8[]) -> Frame

Create a GOAWAY frame.

State predicates

PureHTTP2.is_open — Function

is_open(conn::HTTP2Connection) -> Bool

Check if the connection is open.

is_closed is also defined for HTTP2Connection and shares its name with the stream-layer method — see Streams for the shared export.