API Reference

Read one chunk from a TLS connection: either the initial client connection preface (24 bytes) and a following frame, or a single HTTP/2 frame (9-byte header + variable payload).

Callbacks()

Create a new nghttp2 callbacks object. Resources are automatically freed when the object is garbage collected, or when close() is called.

Internal context passed as user_data to nghttp2 callbacks.

ConnectionPool(; max_per_host=6, idle_timeout=60.0)

A pool of HTTP/2 client connections with automatic reuse and keep-alive.

Examples

pool = ConnectionPool()
response = pool_get(pool, "https://nghttp2.org/")
close(pool)

HTTP2Client(host; port=443, max_concurrent_streams=100,
            initial_window_size=65535, header_table_size=4096,
            verify_peer=true)

Create an HTTP/2 client connected to the given host over TLS. The connection is established immediately with ALPN negotiation for h2.

HTTP2Server(handler, port; host="0.0.0.0", certfile="", keyfile="")

Create an HTTP/2 server listening on the given port. If certfile and keyfile are provided, the server uses TLS with ALPN h2. Otherwise it uses cleartext HTTP/2 (h2c).

The handler function receives a ServerRequest and returns a ServerResponse.

Examples

Cleartext (h2c):

server = HTTP2Server(8080) do req
    ServerResponse(200, "Hello HTTP/2!")
end

TLS (h2):

server = HTTP2Server(8443; certfile="cert.pem", keyfile="key.pem") do req
    ServerResponse(200, "Hello HTTPS/2!")
end

HpackDeflater(max_table_size::Integer=4096)

Create a new HPACK compressor.

HpackInflater()

Create a new HPACK decompressor.

NVPair(name, value)

An HTTP header name-value pair. Owns copies of the name and value as byte vectors, ensuring memory safety when passed to C functions.

Examples

nv = NVPair(":method", "GET")
nv = NVPair(":path", "/index.html")

Layout-compatible representation of nghttp2's nghttp2_data_provider:

typedef union {
    int fd;
    void *ptr;
} nghttp2_data_source;

typedef struct {
    nghttp2_data_source source;
    nghttp2_data_source_read_callback read_callback;
} nghttp2_data_provider;

We only use the ptr variant of the union, so a single Ptr{Cvoid} for source matches the 8-byte union width on 64-bit platforms.

Nghttp2Error <: Exception

Exception thrown when an nghttp2 C function returns an error code.

Fields

• code::Cint — the nghttp2 error code
• msg::String — human-readable error description
• fatal::Bool — true if the error is fatal (unrecoverable)

Nghttp2Error(code::Integer)

Construct an Nghttp2Error from an error code, automatically filling the message and fatal flag.

Option()

Create a new nghttp2 option object for session configuration.

PrioritySpec(; dep_stream=0, weight=16, exclusive=false)

HTTP/2 stream priority specification.

Fields

• dep_stream::Int32 — dependent stream ID (0 = root)
• weight::Int32 — priority weight (1-256, default 16)
• exclusive::Bool — exclusive dependency flag

Request(method, path; headers=NVPair[], body=UInt8[])

Represents an outgoing HTTP/2 request.

Fields

• method::String — HTTP method (GET, POST, etc.)
• path::String — Request path (e.g., "/index.html")
• headers::Vector{NVPair} — Custom request headers
• body::Vector{UInt8} — Request body

Response(status, headers, body)

Represents an HTTP/2 response.

Fields

• status::Int — HTTP status code (e.g., 200, 404)
• headers::Vector{NVPair} — Response headers
• body::Vector{UInt8} — Response body

Response body source passed to nghttp2 via nghttp2_data_provider.

data holds the full response body bytes; offset is the next byte to read. The data source read callback copies up to len bytes into nghttp2's buffer on each invocation, advances offset, and signals NGHTTP2_DATA_FLAG_EOF when offset reaches length(data).

The struct is kept alive across the C boundary by storing it in the owning ServerContext's response_bodies dict (so GC does not reclaim it while nghttp2 still holds a pointer). The dict entry is removed when the callback signals EOF.

Internal context for server-side nghttp2 callbacks.

ServerRequest(method, path, headers, body, stream_id)

Represents an incoming HTTP/2 request as received by a server handler.

ServerResponse(status; headers=NVPair[], body=UInt8[])
ServerResponse(status, body::AbstractString)
ServerResponse(status, headers, body)

Represents an HTTP/2 response to be sent by a server handler.

Internal state for a server-side HTTP/2 stream (accumulating a request).

Session(callbacks::Callbacks; server::Bool=false)

Create a new HTTP/2 session (client by default, server if server=true). The session holds a reference to the callbacks to prevent premature GC.

Internal stream state tracking for an active HTTP/2 stream.

get(client, path; headers=NVPair[]) → Response

Send an HTTP/2 GET request.

Check that a wrapper object is still open; throw ArgumentError if closed.

Read one chunk from a plain TCP socket: at least one byte, then drain whatever else is immediately available.

nghttp2 data source read callback.

Copies up to len bytes from the ResponseBodySource (whose Julia pointer is carried in the source union) into the output buffer that nghttp2 provides. Advances the source's offset, and sets NGHTTP2_DATA_FLAG_EOF in data_flags once the whole body has been consumed.

Matches the C signature:

ssize_t (*nghttp2_data_source_read_callback)(
    nghttp2_session *session, int32_t stream_id, uint8_t *buf,
    size_t length, uint32_t *data_flags, nghttp2_data_source *source,
    void *user_data);

onframerecv callback: dispatches handler when ENDSTREAM is received. The nghttp2frame struct layout: nghttp2framehd (length:sizet, streamid:int32, type:uint8, flags:uint8, ...)

Send all pending data from the session.

acquire(pool, host; port=443, verify_peer=true) → HTTP2Client

Get a client from the pool. Reuses an idle connection if available, otherwise creates a new one.

check_error(rv::Integer)

Check an nghttp2 return value. If negative, throw Nghttp2Error. Otherwise return rv.

deflate(d::HpackDeflater, headers::Vector{NVPair}) → Vector{UInt8}

Compress headers using HPACK. Returns the compressed bytes.

delete(client, path; headers=NVPair[]) → Response

dynamic_table_size(d::HpackDeflater) → Int

Return the configured maximum dynamic table size for this deflater.

forward_request(client::HTTP2Client, req::ServerRequest) → ServerResponse

Forward a server request to an upstream HTTP/2 server via the client, and return the upstream response as a ServerResponse. Useful for building HTTP/2 proxies.

head(client, path; headers=NVPair[]) → Response

inflate(i::HpackInflater, data::Vector{UInt8}) → Vector{NVPair}

Decompress HPACK-encoded headers. Returns a vector of NVPairs.

inspect_dynamic_table(d::HpackDeflater) → Vector{NVPair}

Return the entries currently in the HPACK dynamic table. Note: This is an approximation — nghttp2 doesn't expose direct dynamic table iteration, so we return the max_size as context information.

listener_port(server::HTTP2Server) -> Int

Return the TCP port the server's listening socket is bound to. Works for both plaintext (h2c) and TLS (h2) listeners.

nghttp2_check_authority(authority) → Bool

Check if authority is a valid HTTP/2 authority component.

nghttp2_check_header_name(name) → Bool

Check if name is a valid HTTP header field name.

nghttp2_check_header_value(value) → Bool

Check if value is a valid HTTP header field value.

nghttp2_check_method(method) → Bool

Check if method is a valid HTTP method.

nghttp2_check_path(path) → Bool

Check if path is a valid HTTP/2 path.

nghttp2_hd_deflate_del(deflater)

Free an HPACK deflater.

nghttp2_hd_deflate_hd2(deflater, buf, buflen, nva, nvlen) → Cssize_t

Compress headers into buf. Returns the number of bytes written, or a negative error code.

nghttp2_hd_deflate_new(max_deflate_dynamic_table_size=4096) → (Cint, Ptr{Cvoid})

Create a new HPACK deflater (compressor).

nghttp2_hd_inflate_del(inflater)

Free an HPACK inflater.

nghttp2_hd_inflate_hd2(inflater, nv_out, inflate_flags, data, datalen, in_final) → Cssize_t

Decompress headers from data. On each call, check inflate_flags for NGHTTP2_HD_INFLATE_EMIT (header available in nv_out) and NGHTTP2_HD_INFLATE_FINAL (decompression complete).

nghttp2_hd_inflate_new() → (Cint, Ptr{Cvoid})

Create a new HPACK inflater (decompressor).

nghttp2_is_fatal(lib_error_code) → Bool

Return true if the given error code is fatal.

nghttp2_option_del(option)

Free an option object.

nghttp2_option_new() → (Cint, Ptr{Cvoid})

Create a new option object. Returns (error_code, option_ptr).

nghttp2_option_set_no_auto_window_update(option, val)

Set the no-auto-window-update option.

nghttp2_option_set_peer_max_concurrent_streams(option, val)

Set the peer max concurrent streams option.

nghttp2_session_callbacks_del(callbacks)

Free a callbacks object.

nghttp2_session_callbacks_new() → (Cint, Ptr{Cvoid})

Allocate a new callbacks object. Returns (error_code, callbacks_ptr).

nghttp2_session_callbacks_set_before_frame_send_callback(callbacks, cb)

Set the callback invoked before a frame is sent.

nghttp2_session_callbacks_set_error_callback2(callbacks, cb)

Set the error callback (v2 variant).

nghttp2_session_callbacks_set_on_begin_headers_callback(callbacks, cb)

Set the callback invoked when reception of a header block begins.

nghttp2_session_callbacks_set_on_data_chunk_recv_callback(callbacks, cb)

Set the callback invoked when a DATA frame chunk is received.

nghttp2_session_callbacks_set_on_frame_not_send_callback(callbacks, cb)

Set the callback invoked when a frame cannot be sent.

nghttp2_session_callbacks_set_on_frame_recv_callback(callbacks, cb)

Set the callback invoked when a frame is received.

nghttp2_session_callbacks_set_on_frame_send_callback(callbacks, cb)

Set the callback invoked after a frame is sent.

nghttp2_session_callbacks_set_on_header_callback(callbacks, cb)

Set the callback invoked when a header name/value pair is received.

nghttp2_session_callbacks_set_on_stream_close_callback(callbacks, cb)

Set the callback invoked when a stream is closed.

nghttp2_session_callbacks_set_recv_callback2(callbacks, cb)

Set the recv callback (v2 variant using nghttp2_ssize).

nghttp2_session_callbacks_set_send_callback2(callbacks, cb)

Set the send callback (v2 variant using nghttp2_ssize).

nghttp2_session_client_new(callbacks, user_data=C_NULL) → (Cint, Ptr{Cvoid})

Create a new client session. Returns (error_code, session_ptr).

nghttp2_session_del(session)

Delete a session and free all associated resources.

nghttp2_session_find_stream(session, stream_id) → Ptr{Cvoid}

Find a stream by its ID. Returns a stream pointer or C_NULL.

nghttp2_session_get_stream_effective_local_window_size(session, stream_id) → Int32

Get the effective local window size for a stream.

nghttp2_session_get_stream_effective_recv_data_length(session, stream_id) → Int32

Get the effective recv data length for a stream.

nghttp2_session_get_stream_user_data(session, stream_id) → Ptr{Cvoid}

Get the user data associated with a stream.

nghttp2_session_mem_recv2(session, data::Vector{UInt8}) → Cssize_t

Process incoming data. Returns the number of bytes processed.

nghttp2_session_mem_send2(session) → (Cssize_t, Ptr{UInt8})

Serialize outgoing data from the session into memory. Returns (nbytes, data_ptr) where nbytes is the number of bytes serialized and data_ptr points to the serialized data.

nghttp2_session_server_new(callbacks, user_data=C_NULL) → (Cint, Ptr{Cvoid})

Create a new server session. Returns (error_code, session_ptr).

nghttp2_session_set_stream_user_data(session, stream_id, user_data) → Cint

Set the user data associated with a stream.

nghttp2_session_want_read(session) → Bool

Return true if the session wants to receive data from the remote peer.

nghttp2_session_want_write(session) → Bool

Return true if the session wants to send data to the remote peer.

nghttp2_strerror(lib_error_code) → String

Return a human-readable string describing the given nghttp2 error code.

nghttp2_submit_goaway(session, flags, last_stream_id, error_code, opaque_data, opaque_data_len) → Cint

Submit a GOAWAY frame.

nghttp2_submit_headers(session, flags, stream_id, pri_spec, nva, nvlen, stream_user_data) → Int32

Submit a HEADERS frame.

nghttp2_submit_ping(session, flags, opaque_data) → Cint

Submit a PING frame. opaque_data must be a pointer to 8 bytes or C_NULL.

nghttp2_submit_push_promise(session, flags, stream_id, nva, nvlen, stream_user_data) → Int32

Submit a PUSH_PROMISE frame. Returns the promised stream ID.

nghttp2_submit_request2(session, pri_spec, nva, nvlen, data_prd, stream_user_data) → Int32

Submit a request. Returns the stream ID on success, or a negative error code.

nghttp2_submit_response2(session, stream_id, nva, nvlen, data_prd) → Cint

Submit a response on the given stream.

nghttp2_submit_rst_stream(session, flags, stream_id, error_code) → Cint

Submit a RST_STREAM frame.

nghttp2_submit_settings(session, flags, iv, niv) → Cint

Submit a SETTINGS frame. iv is a pointer to an array of Nghttp2SettingsEntry and niv is the number of entries.

nghttp2_submit_window_update(session, flags, stream_id, window_size_increment) → Cint

Submit a WINDOW_UPDATE frame.

nghttp2_version(least_version=0) → Ptr{Nghttp2Info}

Return a pointer to the nghttp2 library version information. If least_version is not 0, returns C_NULL if the library version is less than the specified version.

options(client, path; headers=NVPair[]) → Response

patch(client, path; headers=NVPair[], body=UInt8[]) → Response

pool_get(pool, url; headers=NVPair[]) → Response

Make a GET request using a pooled connection.

pool_post(pool, url; headers=NVPair[], body=UInt8[]) → Response

Make a POST request using a pooled connection.

pool_request(pool, method, url; headers=NVPair[], body=UInt8[]) → Response

Make a request using a pooled connection. The URL is parsed to extract host, port, and path. The connection is automatically acquired and released.

post(client, path; headers=NVPair[], body=UInt8[]) → Response

Send an HTTP/2 POST request.

put(client, path; headers=NVPair[], body=UInt8[]) → Response

recv!(session::Session, data::Vector{UInt8}) → Int

Process incoming data. Returns the number of bytes consumed.

release(pool, client) → Nothing

Return a client to the pool for reuse.

request(client, method, path; headers=NVPair[], body=UInt8[]) → Response

Send an HTTP/2 request and wait for the response. Pseudo-headers (:method, :path, :scheme, :authority) are automatically constructed.

request_stream(client, method, path; headers=NVPair[], body=UInt8[]) → (Channel{Response}, Channel{Vector{UInt8}})

Send an HTTP/2 request with streaming response body. Returns a done channel and a body chunks channel.

send!(session::Session) → Vector{UInt8}

Serialize all pending outgoing data from the session into a byte vector.

set_no_auto_window_update!(opt::Option, val::Bool)

Set the no-auto-window-update option.

set_peer_max_concurrent_streams!(opt::Option, val::Integer)

Set the peer max concurrent streams option.

shutdown!(client::HTTP2Client)

Initiate graceful shutdown by sending a GOAWAY frame and waiting for all pending streams to complete.

shutdown!(server::HTTP2Server)

Gracefully shut down the server: stop accepting new connections, wait for in-flight requests to complete.

submit_goaway!(session::Session, last_stream_id::Integer, error_code::Integer)

Submit a GOAWAY frame.

submit_ping!(session::Session)

Submit a PING frame.

submit_settings!(session::Session)
submit_settings!(session::Session, settings::Vector{Nghttp2SettingsEntry})

Submit a SETTINGS frame.

to_nghttp2_nv(nv::NVPair) → Nghttp2Nv

Convert an NVPair to the C-compatible Nghttp2Nv struct. The caller MUST ensure the NVPair remains alive (GC.@preserve) for the duration of any C call using the returned struct.

want_read(session::Session) → Bool

Return true if the session wants to receive data.

want_write(session::Session) → Bool

Return true if the session wants to send data.

websocket_connect(client, path; headers=NVPair[]) → Int32

Initiate a WebSocket connection over HTTP/2 (RFC 8441) by sending a CONNECT request with the :protocol pseudo-header set to websocket.

Returns the stream ID for the WebSocket tunnel.

Note: Requires server support for RFC 8441 (Extended CONNECT).

with_nva(f, pairs::Vector{NVPair})

Convert a vector of NVPairs to a C-compatible array of Nghttp2Nv structs, call f(nva_ptr, nvlen), and return the result. The NVPair data is GC-preserved for the duration of the call.