.. 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

.. 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

.. 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

.. 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

.. 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)