livery_h3 (livery v0.13.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. quic_h3 runs the handler fun in a process of its own for every request. In that process the adapter, as livery_h1 and livery_h2 do:

  1. Builds a #livery_req{} from the method, path, and headers delivered by quic_h3.
  2. Registers the process as the stream handler (quic_h3:set_stream_handler/4), so the stream's body and trailer events, and any that arrived earlier, come to it. A stream already gone gets no worker.
  3. Hands over to livery_translator, which starts the livery_req_proc worker and turns the {quic_h3, Conn, _} events into the {livery_body, Ref, _} messages the worker reads via livery_body, until the worker exits.

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_informational/3
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(),
            ip => inet:ip_address(),
            inet6 => boolean(),
            cert := binary(),
            key := term(),
            cacerts => [binary()],
            verify => verify_none | verify_peer,
            sni_callback =>
                fun((binary() | undefined) ->
                        {ok, #{cert := binary(), key := term(), cert_chain => [binary()]}} |
                        {error, term()}),
            settings => map(),
            quic_opts => map(),
            stream_type_handler => fun(),
            h3_datagram_enabled => boolean(),
            connection_handler => fun(),
            stream_reset_final_size => boolean(),
            defer_requests_until_settings => boolean(),
            notify_streams_available => boolean(),
            pool_size => pos_integer(),
            max_body => non_neg_integer() | infinity,
            config => term(),
            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(stream(), 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_informational/3

-spec send_informational(stream(), 100..199, [{binary(), binary()}]) -> 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.