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.

HTTP/2 in cleartext (h2c)

versions => [http2] without tls serves HTTP/2 over plain TCP with prior knowledge (RFC 9113 §3.3). The client sends the HTTP/2 connection preface first, as curl --http2-prior-knowledge and gRPC clients do. Upgrade: h2c is not supported. Requests carry the :scheme that the client sends.

{ok, Pid} = nhttp:start_link(my_srv, #{
    port     => 8080,
    handler  => my_handler,
    versions => [http2]
}).

versions => [http1_1, http2] without tls serves both on one port. Each connection gets HTTP/2 when its first 14 bytes are PRI * HTTP/2.0, the start of the connection preface (RFC 9113 §3.4), and HTTP/1.1 from the first byte that differs. A connection that sends no deciding bytes before the request timeout, or the idle timeout when it is shorter, is closed without a response.

Use cleartext HTTP/2 only behind a TLS terminator or inside a trusted network. http3 always needs tls.

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.

Response compression

A reply body of a type in compress_mime_types and at least compression_threshold bytes is gzip or deflate compressed when Accept-Encoding allows it. Each such response gets vary: accept-encoding, merged with any vary from the handler.

The body is sent unchanged when the handler set content-encoding, when cache-control holds no-transform, or when the status is 1xx, 204, 206 or 304. Streamed bodies are never compressed. HEAD gets the same headers as GET.

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).