roadrunner_http (roadrunner v0.2.3)

Protocol-version-agnostic HTTP semantics shared by HTTP/1.1 (roadrunner_http1) and HTTP/2 (roadrunner_http2_*) modules.

What lives here is RFC 9110 semantics — types and helpers whose meaning doesn't depend on wire framing — not RFC 9112 syntax. The HTTP/1.1 wire codec (request-line / header / chunked parsers, status-line + CRLF response encoder) stays in roadrunner_http1. HTTP/2 frame codec + HPACK live in their own modules.

Items here:

Header list shape: [{binary(), binary()}].
HTTP status codes: 100..599 and the redirect subset.
Protocol version tuple: {Major, Minor}.
IMF-fixdate formatter (http_date_now/0 for the current time, format_http_date/1 for an arbitrary posix timestamp) for the Date response header per RFC 9110 §5.6.7 and the Last-Modified response header used by the static handler.

roadrunner_http1 and roadrunner_req re-export the primitive types as aliases so existing callers keep compiling unchanged. The request map shape lives in roadrunner_req alongside the accessors that operate on it.

Summary

Types

headers()

redirect_status()

status()

version()

Functions

auto_headers(Headers, ProtoOpts)

Inject the framework's automatic response headers for an HTTP/1 or HTTP/2 (TCP) response: Date always (RFC 9110 §6.6.1) plus Alt-Svc advertising the listener's HTTP/3 endpoint (RFC 7838) when it co-serves h3 on a fixed port (proto_opts carries the precomputed value only then). HTTP/3 responses use with_date/1 directly — a client already on h3 needs no Alt-Svc.

format_http_date(Posix)

Format a posix timestamp (seconds since epoch) as an IMF-fixdate per RFC 9110 §5.6.7. Same shape as http_date_now/0 but for an explicit timestamp — used by the static file handler to emit the Last-Modified header for a file's mtime.

http_date_now()

Format the current UTC time as an IMF-fixdate per RFC 9110 §5.6.7 — the canonical HTTP Date header format, e.g. Sun, 06 Nov 1994 08:49:37 GMT. Used by the dispatch layer to auto-inject the Date response header per RFC 9110 §6.6.1.

with_date(Headers)

Inject a Date response header (RFC 9110 §6.6.1) unless the handler already set one. Shared by the HTTP/1, HTTP/2, and HTTP/3 response paths so every response carries Date from the one cached clock (http_date_now/0). RFC 9110 makes Date a MUST on 2xx/3xx/4xx and a MAY on 1xx/5xx, so injecting it unconditionally is conformant.

Types

headers()

-type headers() :: [{Name :: binary(), Value :: binary()}].

redirect_status()

-type redirect_status() :: 300..399.

status()

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

version()

-type version() :: {1, 0} | {1, 1} | {2, 0} | {3, 0}.

Functions

auto_headers(Headers, ProtoOpts)

-spec auto_headers(headers(), map()) -> headers().

format_http_date(Posix)

-spec format_http_date(integer()) -> binary().

http_date_now()

-spec http_date_now() -> binary().

Built via direct bit-syntax binary construction rather than io_lib:format/2 because the shape is fixed (RFC 9110 mandates exact widths and the day/month abbreviations) and this function runs on the response hot path.

Cached via persistent_term keyed by the current Posix second: the formatted binary is identical for every request that lands in the same second, so we recompute it only when the second ticks over. Updates are racy on the second boundary (multiple processes may put the same value), but each put writes the same binary so the race is benign.

with_date(Headers)

-spec with_date(headers()) -> headers().