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` options
`public` http_text_helpers
Uses:
http_cookie_jar
http_cookies(Representation)
http_core
http_digest
http_multipart
list
url(Representation)
user
uuid(Representation)
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:
check_option/1 check_options/1 default_option/1 default_options/1 option/2 option/3 valid_option/1 valid_options/1

## Public predicates

### `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:

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

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

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

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

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

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

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

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

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

### `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

### `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`

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