.. index:: single: http_client_session(HTTPTransport)
.. _http_client_session/1:

.. rst-class:: right

**object**

``http_client_session(HTTPTransport)``
======================================

* ``HTTPTransport`` - The object implementing ``http_transport_protocol``.


Stateful HTTP client sessions that add cookie persistence on top of the stateless ``http_client`` facade.

| **Availability:** 
|    ``logtalk_load(http_session(loader))``

| **Author:** Paulo Moura
| **Version:** 1:0:0
| **Date:** 2026-07-12

| **Compilation flags:**
|    ``static, context_switching_calls``


| **Imports:**
|    ``public`` :ref:`options <options/0>`
|    ``public`` :ref:`http_origin_site_helpers <http_origin_site_helpers/0>`
| **Uses:**
|    :ref:`http_client <http_client/0>`
|    :ref:`http_cookie_jar <http_cookie_jar/0>`
|    :ref:`http_cookies(Representation) <http_cookies/1>`
|    :ref:`http_core <http_core/0>`
|    :ref:`list <list/0>`

| **Remarks:**

   - Option precedence: When the same session default or per-request option is given multiple times, the first occurrence is used.
   - Transport options: The ``connection_options(Options)`` session default and request option forwards one-shot transport configuration to the underlying ``http_client`` facade.

| **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_client_session/1::open/1:

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

Opens a new HTTP session with a freshly created owned cookie jar.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``open(Session)``
| **Mode and number of proofs:**
|    ``open(-compound)`` - ``one_or_error``

| **Exceptions:**


------------

.. index:: open/2
.. _http_client_session/1::open/2:

``open/2``
^^^^^^^^^^

Opens a new HTTP session using the given defaults and cookie-jar options, including ``cookies_file(File)`` for reopening a saved owned cookie jar and ``connection_options(Options)`` for one-shot transport configuration.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``open(Session,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)``
|    ``Options`` contains an invalid HTTP client session option:
|        ``domain_error(http_client_session_option,Option)``
|    ``Options`` contains an invalid HTTP client session option combination:
|        ``domain_error(http_client_session_options,Options)``
|    ``Options`` contains invalid persisted cookie data:
|        ``domain_error(http_cookie_jar_persisted_cookies,PersistedCookies)``


------------

.. index:: close/1
.. _http_client_session/1::close/1:

``close/1``
^^^^^^^^^^^

Closes a session and, when applicable, the owned cookie jar created for it.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``close(Session)``
| **Mode and number of proofs:**
|    ``close(+compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Session`` is a variable:
|        ``instantiation_error``
|    ``Session`` is neither a variable nor an open HTTP client session handle:
|        ``domain_error(http_client_session,Session)``
|    ``Session`` refers to a closed HTTP client session handle:
|        ``existence_error(http_client_session,http_client_session(SessionId))``


------------

.. index:: cookie_jar/2
.. _http_client_session/1::cookie_jar/2:

``cookie_jar/2``
^^^^^^^^^^^^^^^^

Returns the configured cookie jar handle or the atom ``none`` when the session does not persist cookies.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``cookie_jar(Session,Jar)``
| **Mode and number of proofs:**
|    ``cookie_jar(+compound,-term)`` - ``one_or_error``

| **Exceptions:**
|    ``Session`` is a variable:
|        ``instantiation_error``
|    ``Session`` is neither a variable nor an open HTTP client session handle:
|        ``domain_error(http_client_session,Session)``
|    ``Session`` refers to a closed HTTP client session handle:
|        ``existence_error(http_client_session,http_client_session(SessionId))``


------------

.. index:: request/5
.. _http_client_session/1::request/5:

``request/5``
^^^^^^^^^^^^^

Performs one HTTP request using session defaults and automatic cookie replay/storage. Per-request options can include ``connection_options(Options)`` for one-shot transport configuration, ``source_url(URL)`` for an absolute HTTP or HTTPS URL, ``source_origin(Origin)`` for a bare Origin header value, and ``top_level_navigation(Boolean)`` to drive SameSite-aware cookie replay. When omitted, SameSite replay defaults to ``source_url(URL)`` and ``top_level_navigation(false)``.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``request(Session,Method,URL,Response,Options)``
| **Mode and number of proofs:**
|    ``request(+compound,+atom,+atom,-compound,+list(compound))`` - ``one_or_error``

| **Exceptions:**
|    ``Session`` is a variable:
|        ``instantiation_error``
|    ``Session`` is neither a variable nor an open HTTP client session handle:
|        ``domain_error(http_client_session,Session)``
|    ``Session`` refers to a closed HTTP client session handle:
|        ``existence_error(http_client_session,http_client_session(SessionId))``
|    ``Options`` is a variable or a partial list:
|        ``instantiation_error``
|    ``Options`` contains invalid HTTP client session request options:
|        ``domain_error(http_client_session_request_options,Options)``
|    ``Options`` contains an invalid HTTP client session request option:
|        ``domain_error(http_client_session_request_option,Option)``
|    ``URL`` is not a supported absolute HTTP URL:
|        ``domain_error(http_client_url,URL)``
|    ``URL`` uses an unsupported HTTP scheme:
|        ``domain_error(http_client_scheme,Scheme)``
|    Cookie replay uses an invalid request context:
|        ``domain_error(http_cookie_jar_request_context,RequestContext)``
|    The stateless HTTP client rejects the request option:
|        ``domain_error(http_client_request_option,Option)``


------------

.. index:: get/4
.. _http_client_session/1::get/4:

``get/4``
^^^^^^^^^

Convenience wrapper over request/5 using the ``get`` method.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``get(Session,URL,Response,Options)``
| **Mode and number of proofs:**
|    ``get(+compound,+atom,-compound,+list(compound))`` - ``one_or_error``

| **Exceptions:**
|    ``Session`` is not an open HTTP client session handle:
|        ``domain_error(http_client_session,Session)``
|    ``URL`` is not a supported absolute HTTP URL:
|        ``domain_error(http_client_url,URL)``
|    ``Options`` contains invalid HTTP client session request options:
|        ``domain_error(http_client_session_request_options,Options)``


------------

.. index:: head/4
.. _http_client_session/1::head/4:

``head/4``
^^^^^^^^^^

Convenience wrapper over request/5 using the ``head`` method.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``head(Session,URL,Response,Options)``
| **Mode and number of proofs:**
|    ``head(+compound,+atom,-compound,+list(compound))`` - ``one_or_error``

| **Exceptions:**
|    ``Session`` is not an open HTTP client session handle:
|        ``domain_error(http_client_session,Session)``
|    ``URL`` is not a supported absolute HTTP URL:
|        ``domain_error(http_client_url,URL)``
|    ``Options`` contains invalid HTTP client session request options:
|        ``domain_error(http_client_session_request_options,Options)``


------------

.. index:: delete/4
.. _http_client_session/1::delete/4:

``delete/4``
^^^^^^^^^^^^

Convenience wrapper over request/5 using the ``delete`` method.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``delete(Session,URL,Response,Options)``
| **Mode and number of proofs:**
|    ``delete(+compound,+atom,-compound,+list(compound))`` - ``one_or_error``

| **Exceptions:**
|    ``Session`` is not an open HTTP client session handle:
|        ``domain_error(http_client_session,Session)``
|    ``URL`` is not a supported absolute HTTP URL:
|        ``domain_error(http_client_url,URL)``
|    ``Options`` contains invalid HTTP client session request options:
|        ``domain_error(http_client_session_request_options,Options)``


------------

.. index:: post/5
.. _http_client_session/1::post/5:

``post/5``
^^^^^^^^^^

Convenience wrapper over request/5 using the ``post`` method and the given body.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``post(Session,URL,Body,Response,Options)``
| **Mode and number of proofs:**
|    ``post(+compound,+atom,+compound,-compound,+list(compound))`` - ``one_or_error``

| **Exceptions:**
|    ``Session`` is not an open HTTP client session handle:
|        ``domain_error(http_client_session,Session)``
|    ``URL`` is not a supported absolute HTTP URL:
|        ``domain_error(http_client_url,URL)``
|    ``Body`` is invalid for the generated normalized HTTP request:
|        ``domain_error(http_body,Body)``
|    ``Options`` contains invalid HTTP client session request options:
|        ``domain_error(http_client_session_request_options,Options)``


------------

.. index:: put/5
.. _http_client_session/1::put/5:

``put/5``
^^^^^^^^^

Convenience wrapper over request/5 using the ``put`` method and the given body.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``put(Session,URL,Body,Response,Options)``
| **Mode and number of proofs:**
|    ``put(+compound,+atom,+compound,-compound,+list(compound))`` - ``one_or_error``

| **Exceptions:**
|    ``Session`` is not an open HTTP client session handle:
|        ``domain_error(http_client_session,Session)``
|    ``URL`` is not a supported absolute HTTP URL:
|        ``domain_error(http_client_url,URL)``
|    ``Body`` is invalid for the generated normalized HTTP request:
|        ``domain_error(http_body,Body)``
|    ``Options`` contains invalid HTTP client session request options:
|        ``domain_error(http_client_session_request_options,Options)``


------------

.. index:: patch/5
.. _http_client_session/1::patch/5:

``patch/5``
^^^^^^^^^^^

Convenience wrapper over request/5 using the ``patch`` method and the given body.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``patch(Session,URL,Body,Response,Options)``
| **Mode and number of proofs:**
|    ``patch(+compound,+atom,+compound,-compound,+list(compound))`` - ``one_or_error``

| **Exceptions:**
|    ``Session`` is not an open HTTP client session handle:
|        ``domain_error(http_client_session,Session)``
|    ``URL`` is not a supported absolute HTTP URL:
|        ``domain_error(http_client_url,URL)``
|    ``Body`` is invalid for the generated normalized HTTP request:
|        ``domain_error(http_body,Body)``
|    ``Options`` contains invalid HTTP client session request options:
|        ``domain_error(http_client_session_request_options,Options)``


------------

Protected predicates
--------------------

(no local declarations; see entity ancestors if any)

Private predicates
------------------

.. index:: session_seed_/1
.. _http_client_session/1::session_seed_/1:

``session_seed_/1``
^^^^^^^^^^^^^^^^^^^

Last allocated session identifier.

| **Compilation flags:**
|    ``dynamic``

| **Template:**
|    ``session_seed_(SessionId)``
| **Mode and number of proofs:**
|    ``session_seed_(?positive_integer)`` - ``zero_or_one``


------------

.. index:: session_state_/2
.. _http_client_session/1::session_state_/2:

``session_state_/2``
^^^^^^^^^^^^^^^^^^^^

Per-session stored cookie jar ownership and default request state.

| **Compilation flags:**
|    ``dynamic``

| **Template:**
|    ``session_state_(SessionId,State)``
| **Mode and number of proofs:**
|    ``session_state_(?positive_integer,?compound)`` - ``zero_or_more``


------------

Operators
---------

(none)

