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