livery_ext (livery v0.2.0)
View SourceRequest extractors.
Axum-style helpers that pull typed values out of a request. Each
extractor either returns the value directly or a
{ok, _} | {error, _} result. Extractors are pure functions over
#livery_req{}; they never block on the wire. Body-shaped
extractors require the body to have been read into a buffer first
(the per-request process does that before invoking the handler
when the route is configured for buffered intake).
Summary
Functions
Extract a bearer token from the Authorization header.
Return the value of a request cookie by name.
Decode an application/x-www-form-urlencoded body into a list of
key/value pairs.
Look up a header by name. Names are matched case-insensitively.
Decode the request body as JSON using the OTP json module.
Look up a path parameter (e.g. :name in /users/:name).
Look up a single query string parameter.
Decode an application/x-www-form-urlencoded body, draining the stream.
read_form/1 with #{max_size => Bytes, timeout => Ms} options.
Return the session map stored on the request.
session/1 with a fallback default.
Return the authenticated principal stored on the request.
user/1 with a fallback default.
Types
-type form_error() :: no_body | not_buffered.
-type json_error() :: no_body | invalid_json | not_buffered.
-type read_form_error() :: not_form | no_body | {limit, max_size} | {client_reset, term()} | timeout.
Functions
-spec bearer_token(livery_req:req()) -> binary() | undefined.
Extract a bearer token from the Authorization header.
Accepts Bearer, bearer, and BEARER prefixes (RFC 6750
§2.1 makes the scheme case-insensitive).
-spec cookie(binary(), livery_req:req()) -> binary() | undefined.
Return the value of a request cookie by name.
Parses the Cookie header (RFC 6265 name=value pairs separated
by ;). Returns undefined when the header or the named cookie
is absent.
-spec form(livery_req:req()) -> {ok, [{binary(), binary()}]} | {error, form_error()}.
Decode an application/x-www-form-urlencoded body into a list of
key/value pairs.
-spec header(binary(), livery_req:req()) -> binary() | undefined.
Look up a header by name. Names are matched case-insensitively.
-spec json(livery_req:req()) -> {ok, term()} | {error, json_error()}.
Decode the request body as JSON using the OTP json module.
The body must have been buffered. Streaming bodies must be drained
via livery_body:read_all/1 before calling this.
-spec path_param(binary(), livery_req:req()) -> binary() | undefined.
Look up a path parameter (e.g. :name in /users/:name).
-spec query(binary(), livery_req:req()) -> binary() | undefined.
Look up a single query string parameter.
Returns the first value if the key appears more than once.
-spec read_form(livery_req:req()) -> {ok, [{binary(), binary()}]} | {error, read_form_error()}.
Decode an application/x-www-form-urlencoded body, draining the stream.
Unlike form/1 (which requires an already-buffered body), this reads a
streaming body to completion (bounded by max_size, default 1 MiB) and
decodes it. A buffered body is decoded directly. The Content-Type check
is case-insensitive and parameter-tolerant. Malformed percent escapes
are preserved verbatim (same decoder as form/1).
-spec read_form(livery_req:req(), map()) -> {ok, [{binary(), binary()}]} | {error, read_form_error()}.
read_form/1 with #{max_size => Bytes, timeout => Ms} options.
-spec session(livery_req:req()) -> term() | undefined.
Return the session map stored on the request.
livery_auth_session places the verified session payload under
meta(session, _). Returns undefined when no session middleware
ran or no valid session cookie was present.
-spec session(livery_req:req(), Default) -> term() | Default.
session/1 with a fallback default.
-spec user(livery_req:req()) -> term() | undefined.
Return the authenticated principal stored on the request.
livery_auth_bearer (and other auth middlewares) place the
verified claims under meta(user, _). Returns undefined when no
auth middleware ran or authentication was optional and absent.
-spec user(livery_req:req(), Default) -> term() | Default.
user/1 with a fallback default.