livery_ext (livery v0.13.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. json/1,2 and read_form/1,2 read a
streamed body to the end (bounded in size and time) before decoding it;
form/1 decodes only a body that is already buffered.
Summary
Functions
Return the access token from the Authorization header with the scheme
it was sent under: {bearer, Token} (RFC 6750) or {dpop, Token}
(RFC 9449). The scheme name is matched without case (RFC 9110 11.1).
Returns undefined for no header, another scheme, or an empty token.
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.
json/1 with #{max_size => Bytes, timeout => Ms} options.
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 | read_error().
-type read_error() :: {limit, max_size} | {client_reset, term()} | timeout.
-type read_form_error() :: not_form | no_body | read_error().
Functions
-spec auth_token(livery_req:req()) -> {bearer | dpop, binary()} | undefined.
Return the access token from the Authorization header with the scheme
it was sent under: {bearer, Token} (RFC 6750) or {dpop, Token}
(RFC 9449). The scheme name is matched without case (RFC 9110 11.1).
Returns undefined for no header, another scheme, or an empty token.
-spec bearer_token(livery_req:req()) -> binary() | undefined.
Extract a bearer token from the Authorization header.
The scheme name is matched in any case (Bearer, bearer, bEaReR),
as RFC 9110 section 11.1 says. Returns undefined for no header,
another scheme, or an empty token.
-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.
A streamed body, which is what the H1, H2 and H3 adapters hand over, is
read to the end first: at most max_size bytes (default 1 MiB), waiting
at most timeout ms (default 5000) for each chunk. Use json/2 to
change either.
-spec json(livery_req:req(), map()) -> {ok, term()} | {error, json_error()}.
json/1 with #{max_size => Bytes, timeout => Ms} options.
-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.