Server public API for nhttp.

This module provides convenience functions for starting HTTP servers. For production use, embed nhttp_listener in your supervision tree.

Quick Start

{ok, Pid} = nhttp:start_link(#{
    port => 8080,
    handler => my_handler
}),

nhttp:stop(Pid).

Production Usage

For production, add the listener to your supervision tree:

ChildSpec = nhttp_listener:child_spec(my_http_listener, #{
    port => 8080,
    handler => my_handler
}),
{ok, {SupFlags, [ChildSpec | OtherChildren]}}.

TLS and SNI

A single TCP/TLS listener can serve several virtual hosts by attaching SNI options to the tls map (see tls/0). Both shapes are passed through to the underlying ssl server options unchanged.

Static lookup with sni_hosts:

{ok, _} = nhttp:start_link(my_server, #{
    port => 8443,
    handler => my_handler,
    versions => [http1_1, http2],
    tls => #{
        certfile  => "default.pem",
        keyfile   => "default.key",
        sni_hosts => [
            {"a.example.com",
                [{certfile, "vhost_a.pem"}, {keyfile, "vhost_a.key"}]},
            {"b.example.com",
                [{certfile, "vhost_b.pem"}, {keyfile, "vhost_b.key"}]}
        ]
    }
}).

Dynamic resolution with sni_fun (return undefined to fall back to the listener's default certfile/keyfile):

SniFun = fun(ServerName) ->
    case my_cert_store:lookup(ServerName) of
        {ok, CertOpts} -> CertOpts;
        not_found      -> undefined
    end
end,
{ok, _} = nhttp:start_link(my_server, #{
    port => 8443,
    handler => my_handler,
    versions => [http1_1, http2],
    tls => #{
        certfile => "default.pem",
        keyfile  => "default.key",
        sni_fun  => SniFun
    }
}).

sni_hosts and sni_fun may be combined and are TCP/TLS only. HTTP/3 listeners ignore them.

Mixed h1/h2/h3 listeners

versions => [http1_1, http2, http3] serves all three from one call. h1 and h2 share a single TCP/TLS listener (ALPN-negotiated). h3 runs over a separate UDP/QUIC listener bound, by convention, on the same port number.

{ok, Pid} = nhttp:start_link(my_srv, #{
    port     => 443,
    handler  => my_handler,
    versions => [http1_1, http2, http3],
    tls      => #{certfile => "cert.pem", keyfile => "key.pem"}
}),
{ok, TcpPort}  = nhttp:get_port(Pid),         % h1/h2 (TCP)
{ok, QuicPort} = nhttp:get_port(Pid, quic).   % h3 (UDP)

max_connections applies per transport: a mixed listener admits up to max_connections TCP connections and up to max_connections QUIC connections, each with its own counter. The two never share a budget.

With port => 0 the TCP and UDP transports bind different ephemeral ports. get_port/1 returns the TCP port. Read the UDP port with get_port(Pid, quic) or get_ports/1. Never assume the two are equal.

Alt-Svc advertisement

A mixed listener auto-emits Alt-Svc: h3=":<quic_port>"; ma=86400 on every HTTP/1.1 and HTTP/2 response so clients discover and upgrade to h3 (RFC 7838 §3, RFC 9114 §3.1). With port => 0 the advertised port is the QUIC ephemeral port. Tune the freshness lifetime with alt_svc => #{ma => Seconds}, or disable advertisement with alt_svc => false. A handler overrides the header by setting its own alt-svc on the response, and suppresses it by setting alt-svc to an empty value.

Advertisement tracks live QUIC readiness, not static config (RFC 7838 §2.1). h3 is advertised only while the QUIC transport is accepting. Once it drains or goes down the response carries Alt-Svc: clear instead, so clients drop the cached alternative rather than waste a UDP attempt and fall back (RFC 7838 §4). Draining a mixed listener stops advertising before it stops accepting.

0-RTT

QUIC 0-RTT (early data) is not enabled: nquic refuses early data unless a replay-protection module is configured, which this server never sets. No application bytes are processed before the handshake completes, so a replayed non-idempotent method cannot reach the handler (RFC 8470, RFC 9001 §9.2).