-spec cookie_value(binary() | undefined, binary()) -> binary() | undefined.

Extracts the value of the named cookie from a raw Cookie header binary, or undefined if the header is absent/empty or the cookie is not present.

Used by both adapters instead of the framework's own cookie parser (Cowboy's raises on malformed input; Elli has none). Total and fail-soft: a malformed name=value pair is skipped. Two distinct anti-DoS caps apply (the same stance as erli18n_negotiate):

• the byte cap (> 8 KiB, ?MAX_COOKIE_BYTES) treats the whole header as empty — the result is undefined without scanning any pair;
• the pair cap (?MAX_COOKIE_PAIRS = 64) bounds the ;-split and DROPS the unscanned tail past the 64th pair (take_segments/2); it does NOT empty the cookie — pairs within the cap are still parsed and returned, so a named cookie appearing among the first 64 pairs is found normally.

1> erli18n_http:cookie_value(<<"sid=abc; locale=pt_BR; theme=dark">>, <<"locale">>).
<<"pt_BR">>
2> erli18n_http:cookie_value(undefined, <<"locale">>).
undefined

-spec negotiate_locale(candidates(), [erli18n_negotiate:locale()], erli18n_negotiate:locale()) ->
                          {erli18n_negotiate:locale(), source() | default}.

Resolves the request locale from Candidates (highest precedence first) against the Available locale set, falling back to Default.

Each candidate is tried in order. A candidate whose value is undefined or empty is skipped. A header value is parsed with erli18n_negotiate:parse_accept_language/1; any other source's value is erli18n_negotiate:canonicalize/1-d. The candidate's preference is matched against Available with erli18n_negotiate:negotiate/2; the first {ok, Locale} wins. If every candidate misses, {Default, default} is returned.

Returns {Locale, Source} — the chosen locale plus which source produced it (default on total miss), so callers can log/emit which signal won. Callers that only need the locale take element(1, _).

Total and fail-soft: it never raises on arbitrary Candidates values (the delegated erli18n_negotiate functions are themselves total), and on a total miss it falls back to Default rather than raising — the returned locale is always a member of Available or equal to Default.

1> erli18n_http:negotiate_locale(
..     [{query, undefined}, {cookie, <<"pt-BR">>}, {header, <<"fr;q=0.9">>}],
..     [<<"pt_BR">>, <<"fr">>], <<"en">>).
{<<"pt_BR">>, cookie}
2> erli18n_http:negotiate_locale([{header, <<"de">>}], [<<"fr">>], <<"en">>).
{<<"en">>, default}

-spec negotiate_locale_lazy([source()],
                            extract_fun(),
                            thunk([erli18n_negotiate:locale()]),
                            thunk(erli18n_negotiate:locale())) ->
                               {erli18n_negotiate:locale(), source() | default}.

Lazy, short-circuiting variant of negotiate_locale/3 for the per-request hot path.

Walks Sources in order and, for each, calls Extract(Source) to obtain that source's raw value ONLY when the source is reached — so once an earlier-precedence source yields a supported locale, the later sources are never extracted (no cookie split, no header parse for a request a query already answered). AvailableThunk is forced at most once, on the first source that yields a non-empty value (the available index is then built once and reused for every remaining candidate); DefaultThunk is forced at most once, only when every source misses. So an adapter that already holds available/default passes fun() -> Value end and pays nothing extra.

Returns {Locale, Source} exactly like negotiate_locale/3 (default on total miss). Pure apart from the supplied Extract callback (no setlocale, no logger, no framework calls). Total and fail-soft: a non-binary or empty extracted value is skipped, the delegated erli18n_negotiate functions never raise, and the result is always a member of the available set or equal to the default.

negotiate_locale/3 is negotiate_locale_lazy/4 with an eager candidate list: the list form stays the supported API for callers that already have all values.

-spec query_value(binary() | undefined, binary()) -> binary() | undefined.

Extracts the value of the named query parameter from a raw query-string binary (the part after ?, without the leading ?), or undefined if the raw query is absent/empty, the parameter is not present, or the parameter has no value.

Used by both adapters instead of the framework's own query decoder (Cowboy's cowboy_req:parse_qs/1 and Elli's decoded accessor both raise on a malformed percent-escape). The adapters feed the raw query binary from the framework's total accessor (cowboy_req:qs/1, elli_request:query_str/1). This parser is total and fail-soft, sharing the cookie parser's anti-DoS posture: a byte cap (> 8 KiB raw query yields undefined) and a bounded &-split that drops the unscanned tail past the pair cap.

Percent (%XX) escapes and the application/x-www-form-urlencoded +-as-space rule are decoded in-module by a total percent_decode/1. An invalid, odd, or truncated escape (%ZZ, a lone %, a truncated %E0%) is fail-soft: the matched value decodes to undefined (the source is skipped) rather than raising. A value-less key (?locale, no =) and an absent key both yield undefined.

1> erli18n_http:query_value(<<"foo=1&locale=pt-BR&bar=2">>, <<"locale">>).
<<"pt-BR">>
2> erli18n_http:query_value(<<"locale=%ZZ">>, <<"locale">>).
undefined
3> erli18n_http:query_value(undefined, <<"locale">>).
undefined