livery_req (livery v0.1.0)

Request accessors and builders.

Requests flow as immutable #livery_req{} values. Adapters build the initial value from protocol-specific events; middleware and handlers read it via the helpers in this module and can derive a new value for the next stage using the setters.

Summary

Types

header_name()

header_value()

req()

Functions

adapter/1

Adapter module that produced this request.

append_header/3

Append a header even if one with this name exists.

authority/1

Authority (host:port), as the client sent it.

binding(Name, Req)

Look up a binding, or undefined.

binding/3

Look up a binding, falling back to Default.

bindings/1

Map of path parameters captured by the router.

body/1

Body shape: empty, {buffered, IoData}, or {stream, Reader}.

delete_header/2

Remove every header with this name.

disconnect_tag()

The tag of the disconnect message delivered to a request worker.

engine_pid/1

Engine pid for this connection (adapter-specific).

has_header/2

True if the header is present at least once.

header(Name, Req)

First value for a header, or undefined.

header/3

First value for a header, falling back to Default.

headers/1

All request headers in wire order, names lowercased.

headers_all/2

Return all values associated with a header name.

meta/1

Full meta map.

meta(Key, Req)

Look up a meta key, or undefined.

meta/3

Look up a meta key, falling back to Default.

method/1

HTTP method, uppercase binary (e.g. <<"GET">>).

new(Fields)

Construct a request from a map of fields.

on_disconnect/2

path/1

Decoded path portion of the request URI.

peer/1

Peer address and port if the adapter knows it.

protocol/1

Wire protocol of the request: h1, h2, or h3.

query/1

Raw query string (everything after ?, no leading ?).

req_id/1

Request id set by livery_request_id or user code.

scheme/1

URL scheme: typically <<"http">> or <<"https">>.

set_bindings(Bs, Req)

Replace the bindings map (used by the router).

set_body(Body, Req)

Replace the body field on the request.

set_header/3

Replace (or insert) a header.

set_meta/3

Set a meta key. Used by middleware to thread state to handlers.

set_req_id(Id, Req)

Set the request id field. Used by livery_request_id.

started_at/1

Monotonic-time timestamp set by livery_req_proc on entry.

stream/1

Adapter-specific stream handle.

tls/1

TLS info map for HTTPS requests; undefined for plain HTTP.

Types

header_name()

-type header_name() :: binary().

header_value()

-type header_value() :: binary().

req()

-type req() ::
          #livery_req{protocol :: h1 | h2 | h3,
                      method :: binary(),
                      scheme :: binary(),
                      authority :: binary(),
                      path :: binary(),
                      raw_query :: binary(),
                      bindings :: #{binary() => binary()},
                      headers :: [{binary(), binary()}],
                      peer :: {inet:ip_address(), inet:port_number()} | undefined,
                      tls :: undefined | map(),
                      body :: empty | {buffered, iodata()} | {stream, term()},
                      adapter :: module() | undefined,
                      stream :: term(),
                      engine_pid :: pid() | undefined,
                      notifier_pid :: pid() | undefined,
                      disc_ref :: reference() | undefined,
                      req_id :: binary(),
                      started_at :: integer() | undefined,
                      meta :: map()}.

Functions

adapter/1

-spec adapter(req()) -> module() | undefined.

Adapter module that produced this request.

append_header/3

-spec append_header(header_name(), header_value(), req()) -> req().

Append a header even if one with this name exists.

authority/1

-spec authority(req()) -> binary().

Authority (host:port), as the client sent it.

binding(Name, Req)

-spec binding(binary(), req()) -> binary() | undefined.

Look up a binding, or undefined.

binding/3

-spec binding(binary(), req(), Default) -> binary() | Default.

Look up a binding, falling back to Default.

bindings/1

-spec bindings(req()) -> #{binary() => binary()}.

Map of path parameters captured by the router.

body/1

-spec body(req()) -> empty | {buffered, iodata()} | {stream, term()}.

Body shape: empty, {buffered, IoData}, or {stream, Reader}.

The Reader is opaque; drain it with livery_body:read/2.

delete_header/2

-spec delete_header(header_name(), req()) -> req().

Remove every header with this name.

disconnect_tag()

-spec disconnect_tag() -> livery_disconnect.

The tag of the disconnect message delivered to a request worker.

A handler in a receive loop matches {livery_disconnect, _Ref, _Reason}. This helper returns the tag atom (livery_disconnect) for guard-style matching.

engine_pid/1

-spec engine_pid(req()) -> pid() | undefined.

Engine pid for this connection (adapter-specific).

has_header/2

-spec has_header(header_name(), req()) -> boolean().

True if the header is present at least once.

headers/1

-spec headers(req()) -> [{header_name(), header_value()}].

All request headers in wire order, names lowercased.

headers_all/2

-spec headers_all(header_name(), req()) -> [header_value()].

Return all values associated with a header name.

HTTP header names may appear more than once in H1 and H2; this returns them in wire order.

meta/1

-spec meta(req()) -> map().

Full meta map.

meta(Key, Req)

-spec meta(term(), req()) -> term() | undefined.

Look up a meta key, or undefined.

meta/3

-spec meta(term(), req(), Default) -> term() | Default.

Look up a meta key, falling back to Default.

method/1

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

HTTP method, uppercase binary (e.g. <<"GET">>).

new(Fields)

-spec new(map()) -> req().

Construct a request from a map of fields.

Intended for adapters. Unspecified fields fall back to defaults on the record.

on_disconnect/2

-spec on_disconnect(req(), fun(() -> term())) -> ok.

Fun is a 0-arity function (e.g. fun() -> my_llm:cancel(Ref) end). If the client resets the stream or closes the connection before the request finishes, Fun is run exactly once in a fresh process, even if the handler is blocked in a NIF. It never runs on normal completion. Returns ok immediately; a no-op on adapters without a real connection (e.g. the test adapter).

A handler that runs its own receive loop can instead match the {livery_disconnect, _Ref, _Reason} message delivered to it; see disconnect_tag/0.

path/1

-spec path(req()) -> binary().

Decoded path portion of the request URI.

peer/1

-spec peer(req()) -> {inet:ip_address(), inet:port_number()} | undefined.

Peer address and port if the adapter knows it.

protocol/1

-spec protocol(req()) -> h1 | h2 | h3.

Wire protocol of the request: h1, h2, or h3.

query/1

-spec query(req()) -> binary().

Raw query string (everything after ?, no leading ?).

req_id/1

-spec req_id(req()) -> binary().

Request id set by livery_request_id or user code.

scheme/1

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

URL scheme: typically <<"http">> or <<"https">>.

set_bindings(Bs, Req)

-spec set_bindings(#{binary() => binary()}, req()) -> req().

Replace the bindings map (used by the router).

set_body(Body, Req)

-spec set_body(empty | {buffered, iodata()} | {stream, term()}, req()) -> req().

Replace the body field on the request.

set_header/3

-spec set_header(header_name(), header_value(), req()) -> req().

Replace (or insert) a header.

set_meta/3

-spec set_meta(term(), term(), req()) -> req().

Set a meta key. Used by middleware to thread state to handlers.

set_req_id(Id, Req)

-spec set_req_id(binary(), req()) -> req().

Set the request id field. Used by livery_request_id.

started_at/1

-spec started_at(req()) -> integer() | undefined.

Monotonic-time timestamp set by livery_req_proc on entry.

stream/1

-spec stream(req()) -> term().

Adapter-specific stream handle.

tls/1

-spec tls(req()) -> undefined | map().

TLS info map for HTTPS requests; undefined for plain HTTP.