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` options
`public` http_origin_site_helpers
Uses:
http_client
http_cookie_jar
http_cookies(Representation)
http_core
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:
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/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:

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

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

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

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

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

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

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

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

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

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

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

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