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