Client public API for nhttpc.

HTTP/1.1, HTTP/2, HTTP/3 and WebSocket requests share one opts map, one async envelope and one error taxonomy. Request and response maps, header lists and version atoms are the nhttp_lib types: nhttp_lib:request/0, nhttp_lib:response/0, nhttp_lib:version/0.

Quick start

%% One-shot GET
{ok, #{status := 200, body := Body}} =
    nhttpc:get(<<"https://api.example.com/users/42">>).

%% POST with headers
{ok, Resp} = nhttpc:post(
    <<"https://api.example.com/users">>,
    <<"{\"name\":\"alice\"}">>,
    #{headers => [{<<"content-type">>, <<"application/json">>}]}).

%% Build the canonical request manually
{ok, Req} = nhttpc:url(get, <<"https://api.example.com/users/42">>),
{ok, Resp} = nhttpc:request(Req#{headers => [{<<"accept">>, <<"application/json">>}]}).

Responses are plain maps:

#{status := 200, headers := Headers, body := Body} = Resp.

Request options

The options of nhttpc:opts/0 that the sections below do not cover:

Dispatch modes (via)

A single tagged value selects how the request gets to the wire. The default is oneshot; pass via => … to change it.

%% 1. one-shot (default): connect → send → recv → close
{ok, Resp} = nhttpc:get(Url).

%% 2. pooled: borrow a persistent connection
{ok, Resp} = nhttpc:get(Url, #{via => {pool, api_pool}}).

%% 3. on-connection: caller owns the multiplexed transport
{ok, Conn} = nhttpc:open(#{host => <<"api.example.com">>, port => 443},
                         #{versions => [http2]}),
{ok, Resp1} = nhttpc:get(<<"https://api.example.com/v1/a">>,
                         #{via => {conn, Conn}}),
{ok, Resp2} = nhttpc:get(<<"https://api.example.com/v1/b">>,
                         #{via => {conn, Conn}}),
ok = nhttpc:close(Conn).

Illegal combinations like "pool and conn at the same time" are unrepresentable. Dialyzer enforces it.

Connection pools

%% Start (usually under your supervisor)
{ok, _} = nhttpc:start_link(api_pool, #{
    host       => <<"api.example.com">>,
    port       => 443,
    size       => 4,
    versions   => [http2, http1_1],
    tls        => #{verify => verify_peer},
    timeouts   => #{connect => 5_000, request => 30_000}
}).

%% Use the pool
{ok, Resp} = nhttpc:get(<<"https://api.example.com/users">>,
                        #{via => {pool, api_pool}}).

%% Stop
ok = nhttpc:stop(api_pool).
%% or with draining
ok = nhttpc:stop(api_pool, #{drain => true, drain_timeout => 5_000}).

The pool ref accepts the registered atom, the supervisor pid, or the manager pid uniformly. One pool serves one host:port target; spin up a pool per backend.

Pool options

A multiplexed connection takes a request only when it has a free stream slot and the HTTP/2 send credit for the body. The pool grows on whichever runs short first, up to size + max_overflow. An origin that credits the connection window on processing bounds each connection to half_window / credit_latency octets a second. Size the pool from offered_rate * body_size * credit_latency / half_window, multiplied by two for headroom, where half_window is the credit the peer returns at a time and credit_latency is its response latency. The [nhttpc, connection, credit] event reports both inputs: the peer's credit rate and the interval between its WINDOW_UPDATE frames. APNs returns 32830 octets at a time, 270 milliseconds after the body at the median, so 10000 requests a second of 134-octet bodies need 11 connections at zero headroom: size => 22, max_overflow => 11. The defaults fit an origin that credits on receipt.

A pool sized above that product keeps every checkout on the lock-free path. A pool sized below it serves at the ceiling of its connections and queues the rest at the manager, which then sees every checkout and every checkin as a message.

An HTTP/2 connection has 2^30 stream identifiers. A connection that opens max_streams_per_connection streams tells the pool it is draining, serves what is in flight, and exits. The pool opens the replacement when the drain starts, for a rotation and for a peer GOAWAY alike, so the pool is never a connection short while the old one finishes. The default of 2^29 gives 4.3 days for each connection at 1430 streams a second. Each rotation pays a TLS handshake and a cold HPACK table. size + max_overflow bounds the connections that take requests. The live process count is that bound plus the connections draining at the moment, which the request timeout bounds. The [nhttpc, connection, rotated] event fires when a drain starts.

Send-side flow control

An HTTP/2 peer bounds what the client can send with two windows: one for the connection and one for each stream, 65535 octets each at the start. The peer grows them with WINDOW_UPDATE frames on its own schedule. APNs credits the connection window on processing, 32830 octets at a time, about 270 milliseconds after the body, and never credits a stream window.

The client admits a body only against credit it holds. Checkout reserves the body size from the connection's credit slot with one atomic operation, next to the stream slot. A connection whose credit is short takes no body, so the connection never writes a frame the peer cannot receive, never blocks on the socket, and keeps reading the peer while its callers wait. The credit returns when the peer's WINDOW_UPDATE arrives, and the connection publishes it to the pool at once.

What a caller sees at the bound:

• When no connection has the credit, the pool opens one, up to size + max_overflow. The [nhttpc, pool, credit_starved] event fires, rate-limited to one a second, when a checkout finds every connection short of credit. That event is the sizing signal.
• Past the bound the request waits for credit as a pool waiter and gets {timeout, checkout} at the checkout deadline. Nothing was sent, so the request is safe to retry. The [nhttpc, pool, occupancy] event reports the waiters and the connections as a level, once a second while a waiter is queued.
• A body that fits a fresh stream window, and that reaches a connection whose credit an earlier batch spent, is refused before a stream opens. The pool re-dispatches it up to two more times on another connection and then answers {stream_error, {protocol, refused_stream}}. The peer never saw the request. The [nhttpc, connection, send_credit_refused] event counts those refusals.
• A body above the initial window, 65535 octets, or above the stream window the peer advertises, opens its stream and sends what the windows take. The rest waits in the connection's send queue and leaves as the peer credits. max_send_buffer bounds the octets one connection holds this way, 128 KiB by default, and max_queued_streams the streams, a quarter of the peer's stream cap by default. A body that meets either bound is refused and re-dispatched like a body without credit. A request with octets still queued at its deadline gets the retryable refusal too: its END_STREAM never left, so the peer never processed it. While the queued octets leave, every grant from the peer pays for them, so the connection takes no other body until its queue is empty. A caller with a body waits at the manager or goes to another connection. A pool whose every connection holds a queued body against a peer that credits nothing answers each caller with {timeout, checkout} at its deadline and opens no connection. The [nhttpc, connection, send_blocked] and [nhttpc, connection, send_resumed] events mark the queue going non-empty and empty, and [nhttpc, connection, send_queue] samples its occupancy once a second while it holds octets.
• A GOAWAY refuses the streams above its last stream id with {protocol_error, http2, {h2, Code, DebugData}}. The peer never processed them. The streams at or below it complete on the draining connection.

Size the pool from the bandwidth-delay product of the peer's credit, as described under Pool options.

TLS

tls => Map is tls_opts/0, the client side of the nhttp server TLS map. Verify-peer is the default; system CAs come from public_key:cacerts_get/0.

%% Custom CA file
#{tls => #{cacertfile => <<"/etc/ssl/internal-ca.crt">>}}

%% Pinned CA list
#{tls => #{cacerts => Derlist}}

%% Disabled verification (avoid in production)
#{tls => #{verify => verify_none}}

%% Versions, ALPN, SNI
#{tls => #{versions => ['tlsv1.2', 'tlsv1.3'],
           alpn_advertised_protocols => [<<"h2">>, <<"http/1.1">>],
           server_name_indication => "api.example.com"}}

%% Key exchange groups, in order of preference
#{tls => #{supported_groups => [x25519, secp256r1]}}

There is no transport option. The wire transport is derived from URL scheme + presence of tls + chosen versions:

HTTP/3

%% Poolless
{ok, Resp} = nhttpc:get(<<"https://example.com/path">>,
                        #{versions => [http3]}).

%% Pooled
{ok, _} = nhttpc:start_link(h3_pool, #{
    host => <<"api.example.com">>,
    port => 443,
    versions => [http3]
}),
{ok, Resp} = nhttpc:get(<<"https://api.example.com/v1/users">>,
                        #{via => {pool, h3_pool}}).

nquic is in nhttpc.app.src's applications list, so H3 is available from a release boot.

WebSocket

WebSocket folds into the unified async protocol:

{ok, H} = nhttpc:ws_open(<<"wss://example.com/socket">>, #{}),
ok = nhttpc:ws_send(H, {text, <<"hello">>}),

receive
    {nhttpc, H, {ws_ready, _Info}}              -> ok;
    {nhttpc, H, {ws, {text, Msg}}}              -> handle_text(Msg);
    {nhttpc, H, {ws, {binary, Bin}}}            -> handle_bin(Bin);
    {nhttpc, H, {done, {remote_closed, Code}}}  -> server_closed(Code);
    {nhttpc, H, {done, normal}}                 -> ok
end,

ok = nhttpc:cancel(H).

WS-only options ride under ws => …:

nhttpc:ws_open(Url, #{
    ws => #{subprotocols => [<<"chat">>],
            ping_interval => 30_000}
}).

Async requests

{ok, H} = nhttpc:send(Req, #{}),
{ok, Resp} = nhttpc:await(H, 5_000),
%% or cancel without waiting:
ok = nhttpc:cancel(H).

Cancellation drains the owner's mailbox of {nhttpc, H, _} before returning, so no events leak.

Streaming downloads

For sync calls, body_to discriminates the sink:

%% Buffer to file
{ok, #{body := {file, Path, BytesWritten}}} =
    nhttpc:get(Url, #{body_to => {file, "/tmp/big.bin"}}).

%% Fold each chunk
{ok, #{body := {fold, Sum}}} =
    nhttpc:get(Url, #{body_to   => {fold, fun(Chunk, Acc) ->
                                        {continue, Acc + byte_size(Chunk)}
                                    end},
                      fold_init => 0}).

For event-driven streaming use stream/2 and pace the producer with consume/2:

{ok, H} = nhttpc:stream(Req, #{consume_initial => 64 * 1024,
                                consume_low_water => 16 * 1024}),
receive {nhttpc, H, {headers, _S, _Hs}} -> ok end,
loop(H, 0).

loop(H, Total) ->
    receive
        {nhttpc, H, {data, Chunk, more}} ->
            handle_chunk(Chunk),
            ok = nhttpc:consume(H, byte_size(Chunk)),
            loop(H, Total + byte_size(Chunk));
        {nhttpc, H, {data, Chunk, fin}} ->
            handle_chunk(Chunk),
            {ok, Total + byte_size(Chunk)};
        {nhttpc, H, {pause, _Buffered}}  -> loop(H, Total);
        {nhttpc, H, {resume, _Buffered}} -> loop(H, Total);
        {nhttpc, H, {done, normal}}      -> {ok, Total};
        {nhttpc, H, {error, R}}          -> {error, R}
    end.

Streaming uploads

%% From a file
{ok, Resp} = nhttpc:post(Url, <<>>,
                         #{body_from => {file, "/path/to/big.bin"}}).

%% From a custom iterator
Iter = fun() ->
    case ... of
        eof -> fin;
        Chunk -> {ok, Chunk, Iter}
    end
end,
{ok, Resp} = nhttpc:post(Url, <<>>, #{body_from => {iter, Iter}}).

%% Progress
nhttpc:post(Url, <<>>,
            #{body_from => {file, Path},
              on_upload_progress => fun(Sent, _Total) ->
                  io:format("uploaded ~p~n", [Sent])
              end}).

%% Read size of a file source, 65536 octets by default
nhttpc:post(Url, {stream, {file, Path}, #{chunk_size => 262144}}, #{}).

A file source is read chunk_size octets at a time. On HTTP/2 the codec splits every chunk at the peer's frame size and holds what the peer's windows cannot take yet, at most 128 KiB, so chunk_size is a read size and not a frame size. The uploader reads the socket while it waits for credit, and on_upload_progress reports the octets written to the socket. An upload that reaches its request timeout with octets still held sends RST_STREAM and answers {stream_error, {protocol, refused_stream}}.

Cookie jar

{ok, Jar} = nhttpc_cookie_jar:start_link(),
{ok, _} = nhttpc:get(<<"https://example.com/login">>,
                     #{cookie_jar => Jar}),
{ok, _} = nhttpc:get(<<"https://example.com/dashboard">>,
                     #{cookie_jar => Jar}),
ok = nhttpc_cookie_jar:stop(Jar).

jar() is an opaque reference(). The pid + ETS table are held under persistent_term keyed on the ref; the cookie API is the only thing the caller ever touches.

Retries

%% Up to 3 attempts (retries are off by default)
nhttpc:get(Url, #{retry => 3}).

%% Full control
nhttpc:get(Url, #{retry => #{
    max_attempts => 5,
    base_delay   => 100,
    max_delay    => 5_000,
    backoff      => exponential,   %% exponential | linear | constant
    jitter       => true,
    retry_on     => [timeout, connection_error, 503, 429]
}}).

Without retry no request is retried. Once enabled, the default condition set depends on the method. An idempotent method retries on timeout, connection_error, connection_refused, connection_reset, and 502/503/504. A POST or a PATCH retries on connection_refused alone, the one condition that proves the request never reached the server.

retry_on => [auto] delegates the decision to the protocol layer, subject to the same method gate. For an idempotent method auto retries a closed connection, a GOAWAY, and a refused stream. For a non-idempotent method auto shrinks to connection_refused. Status codes listed next to auto are explicit and apply to every method. A caller that wants at-least-once delivery on a POST must list the conditions or supply a should_retry callback.

Redirects

follow_redirects => true (default) follows 301/302/303/307/308. The max_redirects cap defaults to 5. redirect_policy => fun/4 lets you inspect each hop and either continue, stop, or supply updated opts.

Cross-origin hops strip Authorization, Cookie, and other credential-bearing headers by default.

Error taxonomy

-type nhttpc:error() ::
      {invalid_request,   atom()}
    | {invalid_opts,      atom()}
    | {connect_error,     inet:posix() | term()}    %% term() only for QUIC
    | {tls_error,         tls_reason()}
    | {timeout,           connect | request | checkout | idle | body}
    | {protocol_error,    nhttp_lib:version(), protocol_detail()}
    | {http_error,        nhttp_lib:status(), nhttp_lib:headers()}
    | {redirect_error,    redirect_reason()}
    | {retries_exhausted, pos_integer(), nhttpc:error()}
    | {stream_error,      stream_reason()}
    | {body_error,        body_reason()}
    | {cookie_jar_error,  cookie_jar_reason()}
    | {file_error,        file:posix() | badarg | terminated | system_limit}
    | pool_full
    | pool_closed.

Every public spec returns {error, nhttpc:error()}; no upstream term() leaks except the documented connect_error arm.

An HTTP/2 GOAWAY reaches the caller as {protocol_error, http2, {h2, Code}}. When the frame carries debug data, the detail is {h2, Code, DebugData} with the raw binary from the frame. APNs puts a JSON reason there. The client does not parse it.

Telemetry

Instrumentation is opt-in through the otel request / pool option and is off by default. When it is unset the request path reads one map key and takes an uninstrumented branch: no clock read, no metadata map, no pool lookup, no telemetry:execute/3.

otel => #{events => true, metrics => true, traces => true}
otel => true    %% shorthand for all three
otel => false   %% default

The map form enables only the flags it lists: #{metrics => true} records instruments but publishes no telemetry events. traces is accepted and reserved; no spans are emitted yet.

Events

Published when events is enabled. Request events also carry method, url, scheme, host, port, path and pool.

The body length measurements are omitted when the size cannot be known up front, as for a streaming source, rather than reported as zero.

The queue_time of the [nhttpc, pool, checkout] event is in milliseconds. The nhttpc.http.pool.queue_time metric records the same wait in microseconds.

The version atom in events is nhttp_lib:version/0 (http1_1 | http2 | http3).

The send queue gauges describe one HTTP/2 connection. send_window is the connection send window of the codec, send_buffer_bytes the octets the send queue holds, queued_streams the streams with an entry in it, and send_blocked_ms the time the connection held a non-empty send queue since it connected. send_blocked_ms accumulates. It counts the period that is open when the event fires, and it never resets, so a collector takes the rate from it.

send_blocked fires when the send queue goes from empty to non-empty and send_resumed when it empties, with blocked_ms the length of the period that ended. The pair marks transitions. It does not bracket every starvation period: against a peer that credits every few hundred milliseconds, one large upload keeps the queue non-empty for its whole life, and the pair degenerates to one send_blocked event and a growing send_blocked_ms. send_queue is the sample for that case. It fires once a second at most while the queue is non-empty, and once with every credit report. The events are about the codec send queue. The credit_starved and send_credit_refused events are about pool admission, which keeps a small body off the queue, so a unary workload sees those two and not these.

max_streams_changed fires when a SETTINGS frame moves the concurrent stream cap of a connection, with the cap before and after the frame. A frame that repeats the cap fires nothing.

occupancy reports the level of a pool. waiter_count is the checkouts parked at the manager for a connection with a free stream slot and the send credit for the body. connections is the connections that take requests, ready or connecting, which size + max_overflow bounds. A draining connection is not counted. The manager samples the level once a second at most while it holds a waiter, and once more when the last waiter leaves, so the level returns to zero. A pool that never queues a waiter emits nothing. A pool at the bound with a non-zero waiter_count is saturated.

Metrics

Recorded when metrics is enabled, against the nhttpc meter. Attributes follow the OpenTelemetry HTTP client semantic conventions.

Coverage

request/2 and send/2 are instrumented. stream/2 is instrumented on HTTP/3 only; the HTTP/1.1 and HTTP/2 streaming path goes through nhttpc_stream_recv and does not emit request events yet.

Production notes

• One pool per host:port. A pool with host => <<"a">> will not serve requests targeted at <<"b">> even if the URL says otherwise.
• Pools are long-lived. The persistent_term lookup pays a global scan cost once at start_link; rapid pool churn defeats the optimisation.
• A cookie jar holds a persistent_term entry too, and stopping it pays the same global cost. Start a jar per session or per user, not per request.
• verify_none disables certificate validation. Use it only for development; production should keep verify_peer and supply a pinned CA if the default trust store isn't sufficient.
• Idle connections are evicted by timeouts.idle. Servers that send Connection: close mid-pool cause one extra reconnect on the next checkout. Servers that send GOAWAY (H2) trigger graceful drain, and the pool opens the replacement connection when the drain starts.
• HTTP/3 is over connected UDP. Networks that drop UDP between reconnects (corporate proxies, some load balancers) require an H2 fallback in versions => [http3, http2, http1_1].

Supervision

init([]) ->
    Pool = nhttpc:child_spec(api_pool, #{
        host => <<"api.example.com">>,
        port => 443,
        size => 8,
        tls  => #{verify => verify_peer}
    }),
    {ok, {#{strategy => one_for_one, intensity => 5, period => 10},
          [Pool]}}.