.. 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 ` | ``public`` :ref:`http_origin_site_helpers ` | **Uses:** | :ref:`http_client ` | :ref:`http_cookie_jar ` | :ref:`http_cookies(Representation) ` | :ref:`http_core ` | :ref:`list ` | **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)