nhttpc_cookie_jar (nhttpc v1.0.0)

View Source

Cookie jar with ETS-based storage (RFC 6265).

An ETS-based cookie jar designed for high-performance concurrent access. All read/write operations go directly to ETS — no gen_server bottleneck. A minimal owner process handles table ownership, periodic cleanup, and optional file persistence.

Opacity (1.0)

jar() is an opaque reference(). The owner pid and ETS table are held under persistent_term keyed on the reference. Internal state is not destructurable from outside this module; users handle only the reference returned by start_link/0,1.

Quick Start

%% Start a cookie jar
{ok, Jar} = nhttpc_cookie_jar:start_link().

%% Use with requests
{ok, Resp} = nhttpc:get(Url, #{cookie_jar => Jar}).

%% Manual cookie operations
ok = nhttpc_cookie_jar:set_from_headers(Jar, Uri, ResponseHeaders).
{ok, Cookies} = nhttpc_cookie_jar:get(Jar, Uri).

Summary

Types

jar()
uri()

Functions

all(Jar)

Get all cookies in the jar as a list.

clear(Jar)

Clear all cookies from the jar.

clear(Jar, Domain)

Clear all cookies for a specific domain.

get(Jar, Uri)

Get cookies matching the given URI. Returns {ok, [{Name, Value}]} sorted by path length (longest first).

get_header(Jar, Uri)

Get the Cookie header value for a URI. Returns {ok, binary()} when at least one cookie matches, or {ok, undefined} when none match.

persist(Jar)

Trigger persistence (if configured).

set(Jar, Uri, Cookie)

Set a cookie from a parsed cookie map. Cookie map should have: name, value, and optionally domain, path, expires, max_age, secure, http_only, same_site.

set_from_headers(Jar, Uri, Headers)

Process Set-Cookie headers from a response. Parses each Set-Cookie header and stores valid cookies.

start_link()

Start a cookie jar with default options.

start_link(Opts)

Start a cookie jar with options. Options

stop(Jar)

Stop the cookie jar and cleanup resources.

Types

jar()

-opaque jar()

uri()

-type uri() ::
          #{scheme := http | https | binary(),
            host := binary(),
            path := binary(),
            port => inet:port_number()}.

Functions

all(Jar)

-spec all(jar()) -> {ok, [map()]} | {error, nhttpc:error()}.

Get all cookies in the jar as a list.

clear(Jar)

-spec clear(jar()) -> ok | {error, nhttpc:error()}.

Clear all cookies from the jar.

clear(Jar, Domain)

-spec clear(jar(), binary()) -> ok | {error, nhttpc:error()}.

Clear all cookies for a specific domain.

get(Jar, Uri)

-spec get(jar(), uri()) -> {ok, [{binary(), binary()}]} | {error, nhttpc:error()}.

Get cookies matching the given URI. Returns {ok, [{Name, Value}]} sorted by path length (longest first).

get_header(Jar, Uri)

-spec get_header(jar(), uri()) -> {ok, binary() | undefined} | {error, nhttpc:error()}.

Get the Cookie header value for a URI. Returns {ok, binary()} when at least one cookie matches, or {ok, undefined} when none match.

persist(Jar)

-spec persist(jar()) -> ok | {error, nhttpc:error()}.

Trigger persistence (if configured).

set(Jar, Uri, Cookie)

-spec set(jar(), uri(), map()) -> ok | {error, nhttpc:error()}.

Set a cookie from a parsed cookie map. Cookie map should have: name, value, and optionally domain, path, expires, max_age, secure, http_only, same_site.

set_from_headers(Jar, Uri, Headers)

-spec set_from_headers(jar(), uri(), [{binary(), binary()}]) -> ok | {error, nhttpc:error()}.

Process Set-Cookie headers from a response. Parses each Set-Cookie header and stores valid cookies.

start_link()

-spec start_link() -> {ok, jar()}.

Start a cookie jar with default options.

start_link(Opts)

-spec start_link(map()) -> {ok, jar()}.

Start a cookie jar with options. Options:

  • persist => memory | file (default: memory)

  • file => Path (required if persist => file)
  • cleanup_interval => Ms (default: 60000)

stop(Jar)

-spec stop(jar()) -> ok | {error, nhttpc:error()}.

Stop the cookie jar and cleanup resources.