QUIC transport library for Erlang/OTP, implementing RFC 9000 (transport), RFC 9001 (TLS binding), RFC 9002 (loss detection and congestion control), and RFC 9221 (unreliable datagrams).

This module is the umbrella API: client connect, server listen and accept, and listener lifecycle and metrics. connect/3 and accept/1,2 return an opaque ctx/0 connection handle; all post-handshake traffic (streams, datagrams, close, timers) is driven through nquic_lib, which threads the updated context through each call. Closed-form error values are defined in nquic_error.

Connection model

nquic owns exactly one process per connection: the handshake driver. When the handshake completes the connection (a ctx/0 value) is handed to the caller of connect/3 or accept/1,2 and the driver exits. From that point the owning process is the connection: it drives the protocol core directly through nquic_lib by function call against the context, with no message hop and no nquic-owned process. The owner pulls data when ready (nquic_lib:recv/2, nquic_lib:recv_pending/1); there is no pushed-message envelope and no ownership-reassignment call. To serve a connection from a dedicated worker, call accept/1,2 (or connect/3) from that worker. This is the only connection model; read the owner-liveness contract below before writing one.

Owner-liveness contract

There is no per-connection nquic process after the handshake, so nothing services the connection unless the owner's loop does. ACKs, PTO, loss detection, and the idle timer all fire only when the owner calls back into nquic_lib. An owner that blocks, or that reads streams without also draining inbound packets and timer expiries, will silently stall the connection: the peer times it out while the owner waits forever.

The contract the owner MUST satisfy, in one loop:

1. ingest every inbound packet: nquic_lib:handle_packet/3 for the dispatched server path ({packet, Source, Bin} messages from the listener's receiver) or nquic_lib:recv_direct/1 for a connected or client-owned socket;
2. service every {quic_timeout, Type} message via nquic_lib:timeout/2 (this is what drives ACK/PTO/idle);
3. nquic_lib:flush/1 after each of the above so queued frames reach the wire;
4. observe {quic_drain, Listener} (the listener cascade-stop signal) and close.

   owner_loop(Ctx) ->
    Socket = nquic_lib:ctx_socket(Ctx),
    receive
        {'$socket', Socket, select, _Info} ->
            after_io(nquic_lib:recv_direct(Ctx));
        {packet, Source, Bin} ->
            after_io(nquic_lib:handle_packet(Ctx, Source, Bin));
        {quic_timeout, Type} ->
            after_io(nquic_lib:timeout(Ctx, Type));
        {quic_drain, _Listener} ->
            {ok, _Ctx1} = nquic_lib:close(Ctx)
    end.
   
   after_io({ok, Events, Ctx1}) ->
    {ok, Ctx2} = nquic_lib:flush(Ctx1),
    owner_loop(handle_events(Events, Ctx2));
   after_io({error, _Reason, _Ctx1}) ->
    ok.

nquic_lib:recv_direct/1 folds packet ingest and timer servicing into a single blocking call (it handles {packet, _}, {quic_timeout, _}, and the connected-socket select cycle internally), so a connected/client owner can collapse steps 1-2 to recv_direct/1; it still does not observe {quic_drain, _}, which the owner handles itself.

Quick start: client

{ok, Ctx0} = nquic:connect("example.com", 443,
                            #{tls => #{alpn => [<<"h3">>]}}),
{ok, Sid, Ctx1}       = nquic_lib:open_stream(Ctx0, #{type => bidi}),
{ok, Ctx2}            = nquic_lib:send_fin(Ctx1, Sid,
                                           <<"GET / HTTP/1.1\\r\\n\\r\\n">>),
{ok, Body, fin, Ctx3} = nquic_lib:recv(Ctx2, Sid),
{ok, _Ctx4}           = nquic_lib:close(Ctx3).

connect/3 blocks until the handshake completes (or timeout elapses) and returns {ok, Ctx}. The context cannot exist before the handshake, so nowait => true is rejected with {error, {opts, ctx_requires_wait}}.

Quick start: server

{ok, Listener} = nquic:listen(4433, #{
    tls => #{certfile => "server.pem",
             keyfile  => "server.key",
             alpn     => [<<"h3">>]}
}),
{ok, Ctx0}         = nquic:accept(Listener),
{ok, Ctx1}         = nquic_lib:takeover(Ctx0),
{ok, Events, Ctx2} = nquic_lib:recv_pending(Ctx1).

The listener owns one or more UDP sockets (set receivers => N to fan packets across schedulers with SO_REUSEPORT) and a striped dispatch table that routes datagrams to existing connections without spawning a process per packet. An accepted context stays on the listener's dispatch path; the owner calls nquic_lib:takeover/1 to re-target the connection's CIDs to itself and then drives it through nquic_lib. Listener-wide observability is exported through metrics/1.

Listener lifecycle

listen/2 starts a supervision tree with supervisor:start_link/2, so the listener is linked to the calling process. If that process dies, the listener tree comes down with it; if the listener tree crashes abnormally, the link propagates to the owner. This is the intended contract: tie listener lifetime to an owning process.

Stop a listener explicitly with stop_listener/1,2. It is synchronous, idempotent, and exits the listener supervisor with reason normal, so the owner link never turns into a kill. cascade (the default) stops accepting, signals every owner-held established connection to close (a {quic_drain, Listener} message the owner loop observes), then tears down the listener tree and frees the port; detach stops accepting and frees the port but sends no drain signal, leaving established connections to run until their own idle timeout. A blocked accept/1,2 on a stopped listener returns {error, closed}.

Send and backpressure

A stream send is bounded by two windows: the connection's MAX_DATA and the stream's MAX_STREAM_DATA credit, both granted by the peer. nquic_lib:send/3 / nquic_lib:send_fin/3 admit as much as the windows allow and return the updated context; the owner's recv loop processes inbound MAX_DATA / MAX_STREAM_DATA frames that reopen the window and resumes parked stream writes. nquic_lib:is_writable/2 is a point-in-time probe the owner can check between recv turns: a false does not guarantee the next send fails, and a true can be stale before the owner acts on it.

Datagrams

RFC 9221 unreliable datagrams are supported when both peers negotiate max_datagram_frame_size. Datagrams are not retransmitted and are not flow-controlled. Send via nquic_lib:send_datagram/2; receive via nquic_lib:recv_datagram/1.

Session caching and 0-RTT

The optional session_cache and token_cache options on connect/3 opt into TLS 1.3 session resumption and address validation tokens. The server exposes the same surface via the replay_protection and new_token listen options. See nquic_session_cache for the cache contract and nquic_zero_rtt for early-data handling on the server.

Error handling

Every public function returns {ok, _} | {error, t:error_reason/0}. error_reason/0 is the closed taxonomy defined in nquic_error, covering closed, {timeout, Phase}, {transport, _}, {tls, _}, {application, Code, Reason}, {protocol, _}, {flow_control, _}, {opts, _}, {connect, _}, and {listen, _}. Use nquic_error:category/1, nquic_error:is_retryable/1, and nquic_error:format/1 to interrogate values without pattern-matching on the inner shape.