nhttp_lib (nhttp_lib v1.0.0)

View Source

Core HTTP types for the nhttp library.

This module is the umbrella for the type vocabulary used across the nhttp HTTP framework. Types defined elsewhere are re-exported here as thin aliases so consumers only ever import from one upstream module.

Core Types

  • method/0 - HTTP request methods (GET, POST, etc.)

  • version/0 - HTTP version (http1_0 | http1_1 | http2 | http3)

  • scheme/0 - URI / wire scheme (http | https | ws | wss)

  • authority/0 - Authority component (host[:port])
  • peer/0 - Remote socket address
  • header_name/0 / header_value/0 - Header field name/value (binary)
  • headers/0 - HTTP headers as a list of name/value pairs
  • status/0 - HTTP response status codes (100-599)
  • stream_id/0 - Transport-level stream identifier (HTTP/2, HTTP/3, QPACK)
  • fin/0 - End-of-stream marker shared by HTTP/2 and HTTP/3
  • role/0 - Connection role (client or server)
  • error_code/0 - Open peer error code: an RFC-defined atom or the raw integer
  • action/0 - Caller-executed I/O action emitted by H2 / H3 codecs
  • error/0 - Unified error shape across H2 and H3
  • event_common/0 - Shape-shared events emitted by both H2 and H3 codecs
  • event_h2/0 - Alias for nhttp_h2:event/0
  • event_h3/0 - Alias for nhttp_h3:event/0
  • event/0 - Cross-protocol union; prefer event_h2/0 or event_h3/0
  • request/0 - Canonical HTTP request shape across H1, H2, and H3
  • response/0 - Canonical HTTP response shape across H1, H2, and H3

The version field on request/0 and response/0 records the HTTP version (http1_0 | http1_1 | http2 | http3) and is filled by every server parser. The scheme field is http or https on the wire; ws/wss only appear when a client preserved the URI scheme as parsed from a URL. WebSocket upgrades ride on http/https with Upgrade: websocket (H1) or :protocol = websocket (H2/H3 Extended CONNECT, RFC 8441 §4 / RFC 9220 §3).

The connect_protocol field on request/0 carries the RFC 8441 / 9220 :protocol pseudo-header sent on Extended CONNECT requests (<<"websocket">> for the WS upgrade case). It is independent of the wire version field above and is only present when the peer sent :protocol.

The body field is for the convenience case where the whole payload is already in memory. The streaming atom signals that the body is being fed chunk-by-chunk through the streaming-body callback (see nhttp_h1:parse_request_headers/2 and parse_request_body/2).

The trailers field is the symmetric convenience for trailing header fields (RFC 9110 §6.5) when sent alongside an in-memory body. For streaming, emit trailers separately after the body. H1 emits trailer fields between encode_last_chunk/0 and the closing CRLF; H2 / H3 emit them via a final send_headers/4 call with fin.

WebSocket umbrella re-exports

WS frame, message, and option types live in nhttp_ws / nhttp_ws_frame and are re-exported here as aliases (ws_message/0, ws_frame/0, close_code/0, ws_send_opts/0, ws_session_opts/0, ws_runtime_opts/0, ws_close_opts/0).

Summary

Types

action()
authority()
close_code()
error()
error_code()
event()
event_common()
event_h2()
event_h3()
fin()
header_name()
header_value()
headers()
method()
peer()
request()
response()
role()
scheme()
status()
stream_id()
version()
ws_close_opts()
ws_frame()
ws_message()
ws_runtime_opts()
ws_send_opts()
ws_session_opts()

Functions

decode_method/1

Decode an HTTP method from its wire binary form. Known methods become the corresponding atom (get, post, ...); unknown methods stay as the input binary.

decode_scheme/1

Decode a scheme from its binary form. Strict: crashes with function_clause on unknown values. The closed scheme/0 union is enforced here, so callers must validate untrusted input first (or wrap the call in try/catch).

encode_method/1

Encode an HTTP method to its wire binary form (get -> <<"GET">>).

encode_scheme/1

Encode a URI / wire scheme to its binary form.

request_to_pseudo_headers/1

Build the pseudo-header prefix plus regular headers for an HTTP/2 or HTTP/3 request, ready to feed into nhttp_h2:send_headers/4 or nhttp_h3:send_headers/4. Pseudo-header order is :method, :scheme, :authority, :path, the conventional order; HTTP/2 (RFC 9113 §8.3) and HTTP/3 (RFC 9114 §4.3) require only that pseudo-headers precede regular fields. The Host header is filtered out of the regular set because its value already lives in :authority (which is required on request/0). Other headers are passed through in their original order. Extended CONNECT (RFC 8441 / 9220) is supported by leaving any caller-supplied {<<\":protocol\">>, _} entry in the request's headers list. The helper does not touch entries other than Host.

Types

action()

-type action() ::
          {send, stream_id() | connection, iodata()} |
          {send_fin, stream_id(), iodata()} |
          {close, error_code(), binary()}.

authority()

-type authority() :: binary().

close_code()

-type close_code() :: nhttp_ws:close_code().

error()

-type error() ::
          {connection_error, error_code(), binary()} |
          {stream_error, stream_id(), error_code(), binary()} |
          {protocol_violation, atom(), binary()}.

error_code()

-type error_code() :: atom() | non_neg_integer().

event()

-type event() :: event_h2() | event_h3().

event_common()

-type event_common() ::
          {request, stream_id(), request(), fin()} |
          {response, stream_id(), response(), fin()} |
          {data, stream_id(), binary(), fin()} |
          {trailers, stream_id(), headers()} |
          {stream_reset, stream_id(), error_code()} |
          {goaway, stream_id(), error_code(), binary()}.

event_h2()

-type event_h2() :: nhttp_h2:event().

event_h3()

-type event_h3() :: nhttp_h3:event().

fin()

-type fin() :: fin | nofin.

header_name()

-type header_name() :: binary().

header_value()

-type header_value() :: binary().

headers()

-type headers() :: [{header_name(), header_value()}].

method()

-type method() :: get | head | post | put | delete | connect | options | trace | patch | binary().

peer()

-type peer() :: {inet:ip_address(), inet:port_number()}.

request()

-type request() ::
          #{method := method(),
            path := binary(),
            scheme := scheme(),
            authority := authority(),
            headers := headers(),
            peer => peer(),
            version => version(),
            body => iodata() | streaming,
            trailers => headers(),
            connect_protocol => binary()}.

response()

-type response() ::
          #{status := status(),
            version => version(),
            reason => binary(),
            headers := headers(),
            body => iodata(),
            trailers => headers()}.

role()

-type role() :: client | server.

scheme()

-type scheme() :: http | https | ws | wss.

status()

-type status() :: 100..599.

stream_id()

-type stream_id() :: non_neg_integer().

version()

-type version() :: http1_0 | http1_1 | http2 | http3.

ws_close_opts()

-type ws_close_opts() :: nhttp_ws:ws_close_opts().

ws_frame()

-type ws_frame() :: nhttp_ws:ws_frame().

ws_message()

-type ws_message() :: nhttp_ws:ws_message().

ws_runtime_opts()

-type ws_runtime_opts() :: nhttp_ws:ws_runtime_opts().

ws_send_opts()

-type ws_send_opts() :: nhttp_ws:ws_send_opts().

ws_session_opts()

-type ws_session_opts() :: nhttp_ws:ws_session_opts().

Functions

decode_method/1

-spec decode_method(binary()) -> method().

Decode an HTTP method from its wire binary form. Known methods become the corresponding atom (get, post, ...); unknown methods stay as the input binary.

decode_scheme/1

-spec decode_scheme(binary()) -> scheme().

Decode a scheme from its binary form. Strict: crashes with function_clause on unknown values. The closed scheme/0 union is enforced here, so callers must validate untrusted input first (or wrap the call in try/catch).

encode_method/1

-spec encode_method(method()) -> binary().

Encode an HTTP method to its wire binary form (get -> <<"GET">>).

encode_scheme/1

-spec encode_scheme(scheme()) -> binary().

Encode a URI / wire scheme to its binary form.

request_to_pseudo_headers/1

-spec request_to_pseudo_headers(request()) -> headers().

Build the pseudo-header prefix plus regular headers for an HTTP/2 or HTTP/3 request, ready to feed into nhttp_h2:send_headers/4 or nhttp_h3:send_headers/4. Pseudo-header order is :method, :scheme, :authority, :path, the conventional order; HTTP/2 (RFC 9113 §8.3) and HTTP/3 (RFC 9114 §4.3) require only that pseudo-headers precede regular fields. The Host header is filtered out of the regular set because its value already lives in :authority (which is required on request/0). Other headers are passed through in their original order. Extended CONNECT (RFC 8441 / 9220) is supported by leaving any caller-supplied {<<\":protocol\">>, _} entry in the request's headers list. The helper does not touch entries other than Host.