livery_h3 (livery v0.1.0)

View Source

HTTP/3 adapter on top of the quic library's quic_h3 subsystem.

Starts a quic_h3 server bound to a Livery middleware stack and handler. For every inbound request the adapter mirrors livery_h2's pattern:

  1. Builds a #livery_req{} from the method, path, and headers delivered by quic_h3.
  2. Spawns a livery_req_proc worker under livery_req_sup.
  3. Spawns a translator process that turns {quic_h3, Conn, _} body and trailer events into the {livery_body, Ref, _} shape the worker reads via livery_body.
  4. Registers the translator as the stream handler via quic_h3:set_stream_handler/3.

Response emission goes through livery:emit/3 and lands on the adapter callbacks, which call into quic_h3:send_response/4, quic_h3:send_data/3,4, and quic_h3:send_trailers/3.

Summary

Types

listen_opts()
listener()
stream()

Functions

accept_ws/4

Accept a WebSocket session on an extended-CONNECT H3 stream.

accept_wt/4

Hand an extended-CONNECT stream to the webtransport library with transport => h3.

capabilities(Listener)
peer_info/1
reset/2
send_data/3
send_headers/4
send_trailers/2
start(Opts)

Start a listener with the given options.

start/3
stop(Name)

Types

listen_opts()

-type listen_opts() ::
          #{name => atom(),
            port => inet:port_number(),
            cert := binary(),
            key := term(),
            settings => map(),
            quic_opts => map(),
            max_body => non_neg_integer() | infinity,
            stack := livery_middleware:stack(),
            handler := livery_middleware:handler()}.

listener()

-type listener() :: atom().

stream()

-type stream() :: {pid(), non_neg_integer()}.

Functions

accept_ws/4

-spec accept_ws(stream(), livery_req:req(), module(), term()) -> {ok, pid()} | {error, term()}.

Accept a WebSocket session on an extended-CONNECT H3 stream.

Validates the RFC 9220 handshake, replies 200, then hands the stream to the ws library driven by the livery_ws_h3 transport.

accept_wt/4

-spec accept_wt(h3, livery_req:req(), module(), term()) -> {ok, pid()} | {error, term()}.

Hand an extended-CONNECT stream to the webtransport library with transport => h3.

capabilities(Listener)

-spec capabilities(listener()) -> livery_adapter:capabilities().

peer_info/1

-spec peer_info(stream()) -> livery_adapter:peer_info().

reset/2

-spec reset(stream(), term()) -> ok.

send_data/3

-spec send_data(stream(), iodata(), livery_adapter:send_opts()) -> livery_adapter:send_result().

send_headers/4

-spec send_headers(stream(), 100..599, [{binary(), binary()}], livery_adapter:send_opts()) ->
                      livery_adapter:send_result().

send_trailers/2

-spec send_trailers(stream(), [{binary(), binary()}]) -> livery_adapter:send_result().

start(Opts)

-spec start(listen_opts()) -> {ok, listener()} | {error, term()}.

Start a listener with the given options.

Opts must include cert, key, stack, and handler. port defaults to 0 (random port). name defaults to a unique atom. Returns the listener atom (passable to stop/1 and quic:get_server_port/1).

Pass an explicit, stable name if you start and stop listeners repeatedly: quic_h3 registers under an atom name, and an auto-generated name mints a fresh atom per start (atoms are never garbage-collected). livery_service derives a stable name from the port for this reason.

start/3

-spec start(atom() | undefined, listen_opts(), map()) -> {ok, pid()} | {error, term()}.

stop(Name)

-spec stop(listener()) -> ok.