nhttp_cookie (nhttp_lib v1.0.0)

View Source

Cookie parsing and encoding utilities (RFC 6265).

This module provides symmetrical encode/decode functions for both Cookie and Set-Cookie headers.

The Cookie header contains simple name=value pairs separated by semicolons.

%% Decode incoming Cookie header
{ok, Cookies} = nhttp_cookie:decode_cookie(<<"session=abc123; user=john">>),
%% Cookies = [#{name => <<"session">>, value => <<"abc123">>},
%%            #{name => <<"user">>, value => <<"john">>}]

{ok, CookieHeader} = nhttp_cookie:encode_cookie([
    #{name => <<"session">>, value => <<"abc123">>},
    #{name => <<"user">>, value => <<"john">>}
]),
%% <<"session=abc123; user=john">>

The Set-Cookie header contains a single cookie with optional attributes.

%% Decode incoming Set-Cookie header
{ok, SetCookie} = nhttp_cookie:decode_set_cookie(
    <<"session=abc123; Path=/; HttpOnly; Secure">>
),
%% SetCookie = #{name => <<"session">>, value => <<"abc123">>,
%%               path => <<"/">>, http_only => true, secure => true, ...}

%% Encode Set-Cookie header for responses
{ok, SetCookieHeader} = nhttp_cookie:encode_set_cookie(#{
    name => <<"session">>,
    value => <<"abc123">>,
    path => <<"/">>,
    max_age => 3600,
    http_only => true,
    secure => true,
    same_site => strict
}),
%% <<"session=abc123; Path=/; Max-Age=3600; HttpOnly; Secure; SameSite=Strict">>

Roundtrip Support

The decode output can be fed directly to encode:

{ok, SetCookie} = nhttp_cookie:decode_set_cookie(Header),
%% Modify and re-encode
{ok, NewHeader} = nhttp_cookie:encode_set_cookie(SetCookie#{max_age => 7200}).

Summary

Types

cookie_error()
set_cookie()
set_cookie_error()
t()

Functions

decode_cookie/1

Decode a Cookie header value into a list of cookies.

decode_set_cookie(SetCookieHeader)

Decode a Set-Cookie header value into a set-cookie map. Parses a Set-Cookie header with attributes and returns a map containing the cookie name, value, and any parsed attributes.

encode_cookie/1

Encode a list of cookies into a Cookie header value. Takes a list of cookie maps and produces a semicolon-separated string suitable for the Cookie header.

encode_set_cookie/1

Encode a set-cookie map into a Set-Cookie header value. Takes a map with name and value (required) plus optional attributes, and produces a Set-Cookie header string.

Types

cookie_error()

-type cookie_error() :: empty_name | invalid_format.

set_cookie()

-type set_cookie() ::
          #{name := binary(),
            value := binary(),
            path => binary(),
            domain => binary(),
            expires => calendar:datetime(),
            max_age => integer(),
            secure => boolean(),
            http_only => boolean(),
            same_site => strict | lax | none}.

t()

-type t() :: #{name := binary(), value := binary()}.

Functions

decode_cookie/1

-spec decode_cookie(binary()) -> {ok, [t()]} | {error, cookie_error()}.

Decode a Cookie header value into a list of cookies.

Parses a semicolon-separated Cookie header and returns a list of cookie maps. Empty names are rejected with an error.

{ok, Cookies} = nhttp_cookie:decode_cookie(<<"session=abc; user=john">>).
%% Cookies = [#{name => <<"session">>, value => <<"abc">>},
%%            #{name => <<"user">>, value => <<"john">>}]

decode_set_cookie(SetCookieHeader)

-spec decode_set_cookie(binary()) -> {ok, set_cookie()} | {error, set_cookie_error()}.

Decode a Set-Cookie header value into a set-cookie map. Parses a Set-Cookie header with attributes and returns a map containing the cookie name, value, and any parsed attributes.

{ok, SetCookie} = nhttp_cookie:decode_set_cookie(
    <<"session=abc; Path=/; Secure; HttpOnly">>
).
%% SetCookie = #{name => <<"session">>, value => <<"abc">>,
%%               path => <<"/">>, secure => true, http_only => true, ...}

Invalid attributes are silently ignored (per RFC 6265 recommendations).

encode_cookie/1

-spec encode_cookie([t()]) -> {ok, binary()}.

Encode a list of cookies into a Cookie header value. Takes a list of cookie maps and produces a semicolon-separated string suitable for the Cookie header.

{ok, Header} = nhttp_cookie:encode_cookie([
    #{name => <<"session">>, value => <<"abc">>},
    #{name => <<"user">>, value => <<"john">>}
]).
%% Header = <<"session=abc; user=john">>

encode_set_cookie/1

-spec encode_set_cookie(set_cookie()) -> {ok, binary()}.

Encode a set-cookie map into a Set-Cookie header value. Takes a map with name and value (required) plus optional attributes, and produces a Set-Cookie header string.

{ok, Header} = nhttp_cookie:encode_set_cookie(#{
    name => <<"session">>,
    value => <<"abc123">>,
    path => <<"/">>,
    max_age => 3600,
    secure => true
}).
%% Header = <<"session=abc123; Path=/; Max-Age=3600; Secure">>

Supported attributes: path, domain, expires, max_age, secure, http_only, same_site.