Handler behaviour for nhttp server.

Implement this behaviour to handle HTTP requests. Your handler module is called synchronously for each request.

Example Handler (Simple)

-module(my_handler).
-behaviour(nhttp_handler).
-export([init/1, handle_request/2]).

init(_Args) ->
    {ok, #{}}.

handle_request(#{method := get, path := <<"/">>}, State) ->
    {reply, nhttp_resp:ok(<<"Hello, World!">>), State};
handle_request(_Req, State) ->
    {reply, nhttp_resp:not_found(), State}.

Lifecycle and terminate/2

terminate/2 is connection-scoped on every protocol, not request-scoped. On HTTP/1.1 a connection serves one request at a time, so the boundaries coincide. On HTTP/2 and HTTP/3 a single connection multiplexes many requests through per-stream workers, and terminate/2 fires once when the whole connection ends, not after each request.

This has practical consequences:

• Resources opened inside handle_request/2 or handle_request_body/3 must be released before that callback returns (or, for streaming responses, before the producer fun returns). nhttp_stream:producer/3 has try/after semantics for exactly this.
• Do not rely on terminate/2 to close per-request files, DB cursors, or external sockets opened during request handling on H2/H3. Those resources will leak across the rest of the connection's lifetime.
• terminate/2 is the right place for connection-scoped cleanup (deregistration, connection-wide state shutdown), not per-request cleanup.

init/1 runs once per connection process, symmetric with terminate/2.

Streaming responses

For streaming responses, return {stream, Spec, State} where Spec is built with nhttp_stream:producer/3 (push-based fun in a dedicated worker). See nhttp_stream for examples.

Streaming request bodies

To consume a request body chunk-by-chunk instead of buffering, return {accept_body, BodyState, State} from handle_request/2 and implement handle_request_body/3. The connection forwards each body_event/0 ({data, _} | {fin, Trailers} | {abort, Reason}) to your callback, threading BodyState between calls. Returning {accept_body, _, _} again continues consuming. Any other tag (reply, stream, upgrade, abort) terminates the body phase and proceeds to the response.

The connection applies end-to-end backpressure: TCP receive on HTTP/1.1, WINDOW_UPDATE on HTTP/2, and QUIC stream flow control on HTTP/3 are all gated on handler acknowledgement of the previous chunk. The configured max_body_size remains a hard upper bound regardless of handler willingness.

Example Handler (WebSocket, async)

The WebSocket surface is split across four optional callbacks:

• handle_ws_open/2 fires once after the upgrade response is on the wire. Use it to register the session for external pushes (pubsub, gproc, ...).
• handle_ws_frame/3 receives text and binary data frames. PING/PONG frames are handled automatically. Opt in via ws_runtime_opts to also observe them. CLOSE frames are NOT delivered here. See handle_ws_closed/3.
• handle_ws_info/3 receives arbitrary Erlang messages, just like a gen_server handle_info/2 callback.
• handle_ws_closed/3 fires once at session termination with an RFC-grounded reason ({peer | local | fail, Code, Reason}, {transport, _}, {h2_reset | h3_reset, ErrorCode}, timeout, shutdown, {handler_stop, _}, {handler_crash, _}).

External processes push frames via nhttp_ws:send/2,3 and nhttp_ws:send_async/2. See nhttp_ws for the full session API.

-module(ws_handler).
-behaviour(nhttp_handler).
-export([init/1, handle_request/2,
         handle_ws_open/2, handle_ws_frame/3,
         handle_ws_info/3, handle_ws_closed/3]).

init(_Args) -> {ok, #{}}.

handle_request(#{path := <<"/ws">>}, State) ->
    {upgrade, websocket, State};
handle_request(_Req, State) ->
    {reply, nhttp_resp:not_found(), State}.

handle_ws_open(Session, _State) ->
    chat_room:join(Session),
    {ok, #{session => Session}}.

handle_ws_frame({text, Data}, _Session, State) ->
    {reply, {text, Data}, State}.

handle_ws_info({chat, From, Msg}, _Session, State) ->
    {reply, {text, format(From, Msg)}, State}.

handle_ws_closed(_Reason, Session, _State) ->
    chat_room:leave(Session),
    ok.

See also: nhttp_resp, nhttp_ws.