TLS & transport

serve_connection!(conn::HTTP2Connection, io::IO; max_frame_size::Int = DEFAULT_MAX_FRAME_SIZE) -> Nothing

Drive an HTTP2Connection over an arbitrary Base.IO transport.

This is PureHTTP2.jl's primary server-side entry point for real traffic. The function:

1. Reads the 24-byte client connection preface and validates it via process_preface. On short read or invalid preface, throws ConnectionError with PROTOCOL_ERROR.
2. Writes the server preface (SETTINGS frame) to io.
3. Enters a read loop: read a 9-byte frame header via decode_frame_header, enforce header.length ≤ max_frame_size (else throws ConnectionError with FRAME_SIZE_ERROR), read the payload, dispatch via process_frame, and write any response frames back to io.
4. Exits cleanly when the transport reports EOF (read returns fewer bytes than requested) or when the connection enters the CLOSED state (e.g., after a GOAWAY with a non-zero error code).

The caller owns io and is responsible for closing it after this function returns.

max_frame_size defaults to DEFAULT_MAX_FRAME_SIZE (16 KiB, the RFC 9113 §6.5.2 default). Peers may negotiate a larger value via SETTINGS; pass the negotiated value if known.

Transport contract

See specs/006-tls-alpn-support/contracts/README.md for the full contract. The minimum: Base.read(io, n::Int), Base.write(io, bytes), Base.close(io).

Example

using PureHTTP2, Sockets

server = listen(8080)
while true
    sock = accept(server)
    @async begin
        conn = HTTP2Connection()
        try
            serve_connection!(conn, sock)
        finally
            close(sock)
        end
    end
end

set_alpn_h2!(ctx, protocols=["h2"])

Register the HTTP/2 ALPN protocol identifier on a TLS context.

This is a generic function whose methods are provided by the PureHTTP2OpenSSLExt package extension. The extension loads automatically via Base.get_extension when OpenSSL.jl is present in the same environment as PureHTTP2.jl.

Without OpenSSL.jl loaded, this function has zero methods and calling it throws MethodError — by design. PureHTTP2.jl's runtime dependency graph stays empty (constitution Principle I); OpenSSL is a weak dependency activated only when you using OpenSSL.

With OpenSSL.jl loaded, a method for OpenSSL.SSLContext becomes available:

using PureHTTP2, OpenSSL
ctx = OpenSSL.SSLContext(OpenSSL.TLSClientMethod())
PureHTTP2.set_alpn_h2!(ctx)              # register "h2"
PureHTTP2.set_alpn_h2!(ctx, ["h2", "http/1.1"])  # register with fallback

The method converts the user-facing Vector{String} into the RFC 7301 §3.1 wire format (length-prefixed concatenation) before handing off to OpenSSL.

Current limitations

At Milestone 5, PureHTTP2.jl is server-role only and OpenSSL.jl does not yet export SSL_CTX_set_alpn_select_cb (the server-side selection callback). set_alpn_h2! is therefore scaffolded for forward compatibility with Milestone 6's client-role work and is not yet live-tested end-to-end against a real TLS peer. See docs/src/tls.md for the full story and upstream-bugs.md for the upstream tracking entry.

PureHTTP2.reseau_h2_server_config(; cert_file, key_file, kwargs...) -> Reseau.TLS.Config

Build a Reseau.jl server-side TLS config with alpn_protocols=["h2"] pre-populated. Requires cert_file::AbstractString and key_file::AbstractString as keyword arguments; forwards every other keyword argument to Reseau.TLS.Config. If the caller passes an explicit alpn_protocols= kwarg, that value overrides the default ALPN_H2_PROTOCOLS.

This generic function is a stub in the main module — a method for Reseau.TLS.Config is provided by the PureHTTP2ReseauExt package extension, which loads automatically when Reseau.jl is in the environment. Without Reseau loaded, calling this function throws MethodError.

Example

using PureHTTP2, Reseau

cfg = PureHTTP2.reseau_h2_server_config(;
    cert_file = "server.crt",
    key_file  = "server.key",
)

listener = Reseau.TLS.listen("tcp", "0.0.0.0:443", cfg)
conn = Reseau.TLS.accept(listener)
Reseau.TLS.handshake!(conn)
# At this point Reseau.TLS.connection_state(conn).alpn_protocol
# is "h2" (client advertised it) or nothing (client did not).
PureHTTP2.serve_connection!(PureHTTP2.HTTP2Connection(), conn)

Why not set_alpn_h2!?

Milestone 5 shipped PureHTTP2.set_alpn_h2!(ctx::OpenSSL.SSLContext) as a mutator on a mutable C-backed context. Reseau.TLS.Config is an immutable Julia struct whose alpn_protocols field is defensively copied at construction, so an analogous mutator is structurally impossible. The reseau_h2_* helpers are constructor-style instead. See specs/009-reseau-tls-backend/contracts/README.md Section 2 for the full symmetry-break rationale.

PureHTTP2.reseau_h2_client_config(; kwargs...) -> Reseau.TLS.Config

Build a Reseau.jl client-side TLS config with alpn_protocols=["h2"] pre-populated. Thin convenience wrapper around Reseau.TLS.Config — forwards all keyword arguments. If the caller passes an explicit alpn_protocols= kwarg, that value overrides the default ALPN_H2_PROTOCOLS.

This generic function is a stub in the main module — a method for the Reseau config type is provided by the PureHTTP2ReseauExt package extension, which loads automatically when Reseau.jl is in the environment. Without Reseau loaded, calling this function throws MethodError.

See also: reseau_h2_server_config, reseau_h2_connect, ALPN_H2_PROTOCOLS.

PureHTTP2.reseau_h2_connect(address::AbstractString; kwargs...) -> Reseau.TLS.Conn

One-shot client helper: calls Reseau.TLS.connect(address; ...) with alpn_protocols=["h2"] merged into the keyword arguments. Returns a fully-handshaken Reseau.TLS.Conn ready to hand to open_connection!.

If the caller passes an explicit alpn_protocols= kwarg, that value overrides the default ALPN_H2_PROTOCOLS. Other Reseau.jl connect keywords such as server_name, verify_peer, and handshake_timeout_ns are forwarded unchanged.

This generic function is a stub in the main module — a method is provided by the PureHTTP2ReseauExt package extension, which loads automatically when Reseau.jl is in the environment. Without Reseau loaded, calling this function throws MethodError.

Example

using PureHTTP2, Reseau

client = PureHTTP2.reseau_h2_connect("tcp", "example.com:443";
    server_name = "example.com")

conn = HTTP2Connection()
result = PureHTTP2.open_connection!(conn, client;
    request_headers = Tuple{String,String}[
        (":method",    "GET"),
        (":path",      "/"),
        (":scheme",    "https"),
        (":authority", "example.com"),
    ])

close(client)

PureHTTP2.ALPN_H2_PROTOCOLS :: Vector{String}

The canonical ALPN protocol list for HTTP/2 (["h2"], per RFC 7301 §3.1 and RFC 9113 §3.3). Reusable by any TLS backend — PureHTTP2.jl ships two optional TLS backend extensions that both consume this list:

• PureHTTP2OpenSSLExt uses it as the default in set_alpn_h2!(::OpenSSL.SSLContext) when the caller passes no explicit list.
• PureHTTP2ReseauExt uses it as the default in the reseau_h2_* constructor helpers (reseau_h2_server_config, reseau_h2_client_config, reseau_h2_connect) when the caller passes no explicit list.

Callers should treat this constant as read-only; callers who want a different list pass one explicitly via the alpn_protocols keyword argument.