.. index:: single: http_cookie_jar .. _http_cookie_jar/0:

.. rst-class:: right

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 :ref:`http_text_helpers <http_text_helpers/0>` | public :ref:`http_origin_site_helpers <http_origin_site_helpers/0>` | public :ref:`options <options/0>` | Uses: | :ref:`date <date/0>` | :ref:`http_cookies(Representation) <http_cookies/1>` | :ref:`list <list/0>` | :ref:`os <os/0>` | :ref:`url(Representation) <url/1>` | :ref:`user <user/0>`

| Remarks: | (none)

| Inherited public predicates: |  :ref:`options_protocol/0::check_option/1`  :ref:`options_protocol/0::check_options/1`  :ref:`options_protocol/0::default_option/1`  :ref:`options_protocol/0::default_options/1`  :ref:`options_protocol/0::option/2`  :ref:`options_protocol/0::option/3`  :ref:`options_protocol/0::valid_option/1`  :ref:`options_protocol/0::valid_options/1`  

.. contents:: :local: :backlinks: top

Public predicates

.. index:: open/1 .. _http_cookie_jar/0::open/1:

open/1 ^^^^^^^^^^

Opens a new empty cookie jar.

| Compilation flags: | static

| Template: | open(Jar) | Mode and number of proofs: | open(-compound) - one

---

.. index:: open/2 .. _http_cookie_jar/0::open/2:

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)

---

.. index:: close/1 .. _http_cookie_jar/0::close/1:

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))

---

.. index:: clear/1 .. _http_cookie_jar/0::clear/1:

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))

---

.. index:: store_set_cookies/3 .. _http_cookie_jar/0::store_set_cookies/3:

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)

---

.. index:: request_cookies/3 .. _http_cookie_jar/0::request_cookies/3:

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)

---

.. index:: request_cookies/4 .. _http_cookie_jar/0::request_cookies/4:

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)

---

.. index:: cookies/2 .. _http_cookie_jar/0::cookies/2:

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))

---

.. index:: cookie_count/2 .. _http_cookie_jar/0::cookie_count/2:

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))

---

.. index:: save/2 .. _http_cookie_jar/0::save/2:

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)

---

.. index:: load/2 .. _http_cookie_jar/0::load/2:

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

.. index:: jar_seed_/1 .. _http_cookie_jar/0::jar_seed_/1:

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

---

.. index:: jar_state_/2 .. _http_cookie_jar/0::jar_state_/2:

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

---

.. index:: jar_cookie_/11 .. _http_cookie_jar/0::jar_cookie_/11:

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)