object

# `http_cookie_jar`

HTTP cookie jar implementing explicit storage and request matching on top of the http_cookies parsing and generation predicates, with explicit save and load operations for persisting jar contents.

Availability:
`logtalk_load(http_session(loader))`
Author: Paulo Moura
Version: 1:0:0
Date: 2026-06-26
Compilation flags:
`static, context_switching_calls`
Imports:
`public` http_text_helpers
`public` http_origin_site_helpers
`public` options
Uses:
date
http_cookies(Representation)
list
os
url(Representation)
user
Remarks:
(none)
Inherited public predicates:
check_option/1 check_options/1 default_option/1 default_options/1 option/2 option/3 valid_option/1 valid_options/1

## Public predicates

### `open/1`

Opens a new empty cookie jar.

Compilation flags:
`static`
Template:
`open(Jar)`
Mode and number of proofs:
`open(-compound)` - `one`

### `open/2`

Opens a new cookie jar using the given options list. Supported options include `cookies_file(File)` for preloading previously persisted cookies from disk.

Compilation flags:
`static`
Template:
`open(Jar,Options)`
Mode and number of proofs:
`open(-compound,+list(compound))` - `one_or_error`
Exceptions:
`Options` is a variable or a partial list:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(option,Option)`
The cookies file option is a variable:
`instantiation_error`
The cookies file option is neither a variable nor an atom:
`type_error(atom,File)`
The persisted cookie data is malformed:
`domain_error(http_cookie_jar_persisted_cookies,PersistedCookies)`
A persisted cookie is malformed:
`domain_error(http_cookie_jar_persisted_cookie,PersistedCookie)`

### `close/1`

Closes a cookie jar and removes all stored cookies.

Compilation flags:
`static`
Template:
`close(Jar)`
Mode and number of proofs:
`close(+compound)` - `one_or_error`
Exceptions:
`Jar` is a variable:
`instantiation_error`
`Jar` is neither a variable nor an open cookie-jar handle:
`domain_error(http_cookie_jar,Jar)`
`Jar` refers to a closed cookie-jar handle:
`existence_error(http_cookie_jar,cookie_jar(JarId))`

### `clear/1`

Removes all currently stored cookies from a cookie jar while keeping the jar handle valid.

Compilation flags:
`static`
Template:
`clear(Jar)`
Mode and number of proofs:
`clear(+compound)` - `one_or_error`
Exceptions:
`Jar` is a variable:
`instantiation_error`
`Jar` is neither a variable nor an open cookie-jar handle:
`domain_error(http_cookie_jar,Jar)`
`Jar` refers to a closed cookie-jar handle:
`existence_error(http_cookie_jar,cookie_jar(JarId))`

### `store_set_cookies/3`

Stores normalized Set-Cookie terms for the given absolute URL, replacing existing cookies with the same name, domain, and path.

Compilation flags:
`static`
Template:
`store_set_cookies(Jar,URL,SetCookies)`
Mode and number of proofs:
`store_set_cookies(+compound,+atom,+list(compound))` - `one_or_error`
Exceptions:
`Jar` is a variable:
`instantiation_error`
`Jar` is neither a variable nor an open cookie-jar handle:
`domain_error(http_cookie_jar,Jar)`
`Jar` refers to a closed cookie-jar handle:
`existence_error(http_cookie_jar,cookie_jar(JarId))`
`URL` is a variable:
`instantiation_error`
`URL` is not a supported absolute cookie-jar URL:
`domain_error(http_cookie_jar_url,URL)`
`URL` uses an unsupported cookie-jar URL scheme:
`domain_error(http_cookie_jar_url_scheme,Scheme)`
`SetCookies` is a variable or a partial list:
`instantiation_error`
`SetCookies` is not a valid set-cookie list:
`domain_error(http_cookie_jar_set_cookies,SetCookies)`
An element `SetCookie` of `SetCookies` is not a valid normalized Set-Cookie term:
`domain_error(http_cookie_jar_set_cookie,SetCookie)`

### `request_cookies/3`

Returns the cookie name-value pairs currently applicable to the given absolute URL using the convenience default `request_context(get, source_url(URL), false)`.

Compilation flags:
`static`
Template:
`request_cookies(Jar,URL,Cookies)`
Mode and number of proofs:
`request_cookies(+compound,+atom,-list(compound))` - `one_or_error`
Exceptions:
`Jar` is a variable:
`instantiation_error`
`Jar` is neither a variable nor an open cookie-jar handle:
`domain_error(http_cookie_jar,Jar)`
`Jar` refers to a closed cookie-jar handle:
`existence_error(http_cookie_jar,cookie_jar(JarId))`
`URL` is a variable:
`instantiation_error`
`URL` is not a supported absolute cookie-jar URL:
`domain_error(http_cookie_jar_url,URL)`
`URL` uses an unsupported cookie-jar URL scheme:
`domain_error(http_cookie_jar_url_scheme,Scheme)`

### `request_cookies/4`

Returns the cookie name-value pairs currently applicable to the given absolute URL for an explicit request context represented as `request_context(Method, Source, TopLevelNavigation)` where `Source` is either `source_url(URL)` for an absolute HTTP or HTTPS URL or `source_origin(Origin)` for a bare Origin header value.

Compilation flags:
`static`
Template:
`request_cookies(Jar,URL,RequestContext,Cookies)`
Mode and number of proofs:
`request_cookies(+compound,+atom,+compound,-list(compound))` - `one_or_error`
Exceptions:
`Jar` is a variable:
`instantiation_error`
`Jar` is neither a variable nor an open cookie-jar handle:
`domain_error(http_cookie_jar,Jar)`
`Jar` refers to a closed cookie-jar handle:
`existence_error(http_cookie_jar,cookie_jar(JarId))`
`URL` is a variable:
`instantiation_error`
`URL` is not a supported absolute cookie-jar URL:
`domain_error(http_cookie_jar_url,URL)`
`URL` uses an unsupported cookie-jar URL scheme:
`domain_error(http_cookie_jar_url_scheme,Scheme)`
`RequestContext` is not a valid cookie-jar request context:
`domain_error(http_cookie_jar_request_context,RequestContext)`
`RequestContext` contains an invalid method:
`type_error(atom,Method)`
`RequestContext` contains an invalid source:
`domain_error(http_cookie_jar_request_source,Source)`
`RequestContext` contains an invalid top-level-navigation flag:
`domain_error(boolean,TopLevelNavigation)`

### `cookies/2`

Returns the currently stored cookies as cookie(Name, Value, Attributes) terms.

Compilation flags:
`static`
Template:
`cookies(Jar,Cookies)`
Mode and number of proofs:
`cookies(+compound,-list(compound))` - `one_or_error`
Exceptions:
`Jar` is a variable:
`instantiation_error`
`Jar` is neither a variable nor an open cookie-jar handle:
`domain_error(http_cookie_jar,Jar)`
`Jar` refers to a closed cookie-jar handle:
`existence_error(http_cookie_jar,cookie_jar(JarId))`

### `cookie_count/2`

Returns the number of currently stored cookies.

Compilation flags:
`static`
Template:
`cookie_count(Jar,Count)`
Mode and number of proofs:
`cookie_count(+compound,-integer)` - `one_or_error`
Exceptions:
`Jar` is a variable:
`instantiation_error`
`Jar` is neither a variable nor an open cookie-jar handle:
`domain_error(http_cookie_jar,Jar)`
`Jar` refers to a closed cookie-jar handle:
`existence_error(http_cookie_jar,cookie_jar(JarId))`

### `save/2`

Persists the currently stored cookies to a file using a canonical Logtalk term representation.

Compilation flags:
`static`
Template:
`save(Jar,File)`
Mode and number of proofs:
`save(+compound,+atom)` - `one_or_error`
Exceptions:
`Jar` is a variable:
`instantiation_error`
`Jar` is neither a variable nor an open cookie-jar handle:
`domain_error(http_cookie_jar,Jar)`
`Jar` refers to a closed cookie-jar handle:
`existence_error(http_cookie_jar,cookie_jar(JarId))`
`File` is a variable:
`instantiation_error`
`File` is neither a variable nor an atom:
`type_error(atom,File)`

### `load/2`

Loads previously persisted cookies from a file, replacing the current jar contents.

Compilation flags:
`static`
Template:
`load(Jar,File)`
Mode and number of proofs:
`load(+compound,+atom)` - `one_or_error`
Exceptions:
`Jar` is a variable:
`instantiation_error`
`Jar` is neither a variable nor an open cookie-jar handle:
`domain_error(http_cookie_jar,Jar)`
`Jar` refers to a closed cookie-jar handle:
`existence_error(http_cookie_jar,cookie_jar(JarId))`
`File` is a variable:
`instantiation_error`
`File` is neither a variable nor an atom:
`type_error(atom,File)`
The persisted cookie data is malformed:
`domain_error(http_cookie_jar_persisted_cookies,PersistedCookies)`
A persisted cookie is malformed:
`domain_error(http_cookie_jar_persisted_cookie,PersistedCookie)`

## Protected predicates

(no local declarations; see entity ancestors if any)

## Private predicates

### `jar_seed_/1`

Last allocated cookie jar identifier.

Compilation flags:
`dynamic`
Template:
`jar_seed_(JarId)`
Mode and number of proofs:
`jar_seed_(?positive_integer)` - `zero_or_one`

### `jar_state_/2`

Per-jar creation index counter state.

Compilation flags:
`dynamic`
Template:
`jar_state_(JarId,CreationIndex)`
Mode and number of proofs:
`jar_state_(?positive_integer,?non_negative_integer)` - `zero_or_more`

### `jar_cookie_/11`

Stored cookie entries indexed by jar identifier.

Compilation flags:
`dynamic`
Template:
`jar_cookie_(JarId,Name,Domain,Path,Value,HostOnly,Secure,HttpOnly,SameSite,Expiry,CreationIndex)`
Mode and number of proofs:
`jar_cookie_(?positive_integer,?atom,?atom,?atom,?atom,?boolean,?boolean,?boolean,?nonvar,?nonvar,?positive_integer)` - `zero_or_more`

## Operators

(none)