.. index:: single: http_client_digest_session(HTTPTransport)
.. _http_client_digest_session/1:

.. rst-class:: right

**object**

``http_client_digest_session(HTTPTransport)``
=============================================

Stateful HTTP Digest client sessions that add cookie persistence and one-round-trip Digest challenge retry on top of the normalized HTTP client and socket libraries.

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

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

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


| **Imports:**
|    ``public`` :ref:`options <options/0>`
|    ``public`` :ref:`http_text_helpers <http_text_helpers/0>`
| **Uses:**
|    :ref:`http_cookie_jar <http_cookie_jar/0>`
|    :ref:`http_cookies(Representation) <http_cookies/1>`
|    :ref:`http_core <http_core/0>`
|    :ref:`http_digest <http_digest/0>`
|    :ref:`http_multipart <http_multipart/0>`
|    :ref:`list <list/0>`
|    :ref:`url(Representation) <url/1>`
|    :ref:`user <user/0>`
|    :ref:`uuid(Representation) <uuid/1>`

| **Remarks:**

   - Option precedence: When the same session default, Digest default, or per-request option is given multiple times, the first occurrence is used.
   - Reactive authentication: Requests are sent once without credentials and retried automatically only when the response carries a ``401`` Digest challenge accepted by the core ``http_digest`` object.

| **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/3
.. _http_client_digest_session/1::open/3:

``open/3``
^^^^^^^^^^

Opens a new Digest client session with the given username and password and a freshly created owned cookie jar.

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

| **Template:**
|    ``open(Session,Username,Password)``
| **Mode and number of proofs:**
|    ``open(-compound,++text,++text)`` - ``one_or_error``

| **Exceptions:**


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

.. index:: open/4
.. _http_client_digest_session/1::open/4:

``open/4``
^^^^^^^^^^

Opens a new Digest client session using the given credentials plus cookie-jar, request-default, and default Digest authorization options.

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

| **Template:**
|    ``open(Session,Username,Password,Options)``
| **Mode and number of proofs:**
|    ``open(-compound,++text,++text,+list(compound))`` - ``one_or_error``

| **Exceptions:**
|    ``Username`` or ``Password`` is neither a variable nor text:
|        ``type_error(text,Text)``
|    ``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 Digest client session option:
|        ``domain_error(http_client_digest_session_option,Option)``
|    ``Options`` contains an invalid Digest client session option combination:
|        ``domain_error(http_client_digest_session_options,Options)``
|    ``Options`` contains invalid persisted cookie data:
|        ``domain_error(http_cookie_jar_persisted_cookies,PersistedCookies)``


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

.. index:: close/1
.. _http_client_digest_session/1::close/1:

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

Closes a Digest client 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 Digest client session handle:
|        ``domain_error(http_client_digest_session,Session)``
|    ``Session`` refers to a closed Digest client session handle:
|        ``existence_error(http_client_digest_session,http_client_digest_session(SessionId))``


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

.. index:: cookie_jar/2
.. _http_client_digest_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 Digest client session handle:
|        ``domain_error(http_client_digest_session,Session)``
|    ``Session`` refers to a closed Digest client session handle:
|        ``existence_error(http_client_digest_session,http_client_digest_session(SessionId))``


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

.. index:: request/5
.. _http_client_digest_session/1::request/5:

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

Performs one HTTP request using session defaults, cookie replay/storage, and automatic retry when the server replies with a Digest challenge.

| **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 Digest client session handle:
|        ``domain_error(http_client_digest_session,Session)``
|    ``Session`` refers to a closed Digest client session handle:
|        ``existence_error(http_client_digest_session,http_client_digest_session(SessionId))``
|    ``URL`` is a variable:
|        ``instantiation_error``
|    ``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)``
|    ``Options`` is a variable or a partial list:
|        ``instantiation_error``
|    ``Options`` contains invalid Digest client session request options:
|        ``domain_error(http_client_digest_session_request_options,Options)``
|    ``Options`` contains an invalid Digest client session request option:
|        ``domain_error(http_client_digest_session_request_option,Option)``
|    ``Options`` contains invalid form-data headers:
|        ``domain_error(http_client_form_data_headers,Headers)``
|    ``Options`` contains invalid form-data properties:
|        ``domain_error(http_client_form_data_properties,Properties)``
|    The Digest challenge contains an unsupported algorithm:
|        ``domain_error(http_digest_algorithm,Algorithm)``
|    The Digest challenge contains an unsupported qop value:
|        ``domain_error(http_digest_qop,Qop)``


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

.. index:: get/4
.. _http_client_digest_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 Digest client session handle:
|        ``domain_error(http_client_digest_session,Session)``
|    ``URL`` is not a supported absolute HTTP URL:
|        ``domain_error(http_client_url,URL)``
|    ``Options`` contains invalid Digest client session request options:
|        ``domain_error(http_client_digest_session_request_options,Options)``


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

.. index:: head/4
.. _http_client_digest_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 Digest client session handle:
|        ``domain_error(http_client_digest_session,Session)``
|    ``URL`` is not a supported absolute HTTP URL:
|        ``domain_error(http_client_url,URL)``
|    ``Options`` contains invalid Digest client session request options:
|        ``domain_error(http_client_digest_session_request_options,Options)``


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

.. index:: delete/4
.. _http_client_digest_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 Digest client session handle:
|        ``domain_error(http_client_digest_session,Session)``
|    ``URL`` is not a supported absolute HTTP URL:
|        ``domain_error(http_client_url,URL)``
|    ``Options`` contains invalid Digest client session request options:
|        ``domain_error(http_client_digest_session_request_options,Options)``


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

.. index:: post/5
.. _http_client_digest_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 Digest client session handle:
|        ``domain_error(http_client_digest_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 Digest client session request options:
|        ``domain_error(http_client_digest_session_request_options,Options)``


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

.. index:: put/5
.. _http_client_digest_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 Digest client session handle:
|        ``domain_error(http_client_digest_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 Digest client session request options:
|        ``domain_error(http_client_digest_session_request_options,Options)``


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

.. index:: patch/5
.. _http_client_digest_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 Digest client session handle:
|        ``domain_error(http_client_digest_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 Digest client session request options:
|        ``domain_error(http_client_digest_session_request_options,Options)``


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

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

(no local declarations; see entity ancestors if any)

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

.. index:: session_seed_/1
.. _http_client_digest_session/1::session_seed_/1:

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

Last allocated Digest client 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_digest_session/1::session_state_/2:

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

Per-session stored cookie jar ownership, credentials, default request state, and default Digest authorization options.

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

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


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

Operators
---------

(none)