.. index:: single: http_session
.. _http_session/0:

.. rst-class:: right

**object**

``http_session``
================

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-05-23

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


| **Imports:**
|    ``public`` :ref:`options <options/0>`
| **Uses:**
|    :ref:`http <http/0>`
|    :ref:`http_client <http_client/0>`
|    :ref:`http_cookie_jar <http_cookie_jar/0>`
|    :ref:`http_cookies(Representation) <http_cookies/1>`
|    :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.

| **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_session/0::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``


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

.. index:: open/2
.. _http_session/0::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.

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

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


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

.. index:: close/1
.. _http_session/0::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_session/0::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_session/0::request/5:

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

Performs one HTTP request using session defaults and automatic cookie replay/storage.

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


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

.. index:: get/4
.. _http_session/0::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``


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

.. index:: head/4
.. _http_session/0::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_session/0::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_session/0::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``


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

.. index:: put/5
.. _http_session/0::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``


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

.. index:: patch/5
.. _http_session/0::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``


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

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

(no local declarations; see entity ancestors if any)

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

.. index:: session_seed_/1
.. _http_session/0::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_session/0::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)

