.. _library_http_session:

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

This library provides explicit client-side and server-side HTTP session
support on top of the normalized HTTP stack.

The library provides these public entities:

- ``http_cookie_jar`` explicit in-memory cookie storage and request
  matching for client-side use
- ``http_client_session`` reusable HTTP client sessions that
  automatically replay and store cookies
- ``http_server_core_session`` server-side session manager over
  normalized request and response terms
- ``http_server_core_session_handler(_, _)`` portable handler wrapper
  that applies server-session begin and finish logic
- ``http_router_server_session(_)`` router middleware helpers for
  request annotation and response finalization

The design keeps the current ``http_client`` API stateless. Automatic
cookie persistence is scoped to explicit client-session handles, while
server-side session state stays in an explicit in-memory manager keyed
by opaque cookie identifiers.

By default, ``http_client_session`` uses the ``http_socket_transport``
transport through the default ``http_client`` facade. The parametric
``http_client_session(_HTTPSocket_)`` object can also be parameterized
with alternative ``http_transport_protocol`` implementations such as
``http_process_transport``, which supports TLS-backed client transport.

This library can be used with backend Prolog systems that support
unbound integer arithmetic and the ``sockets`` library: ECLiPSe, SICStus
Prolog, SWI-Prolog, Trealla Prolog, and XVM.

API documentation
-----------------

Open the
`../../apis/library_index.html#http_session <../../apis/library_index.html#http_session>`__
link in a web browser.

Loading
-------

To load the library, load the ``loader.lgt`` file:

::

   | ?- logtalk_load(http_session(loader)).

Testing
-------

To test this library, load the ``tester.lgt`` file:

::

   | ?- logtalk_load(http_session(tester)).

Usage overview
--------------

Use ``http_client`` for one-shot stateless calls:

::

   | ?- http_client::get('http://127.0.0.1:8080/resource', Response, []).

Use ``http_client_session`` when you need cookie persistence across
requests:

::

   | ?- http_client_session::open(Session),
        http_client_session::get(Session, 'http://127.0.0.1:8080/visits', First, []),
        http_client_session::get(Session, 'http://127.0.0.1:8080/visits', Second, []),
        http_client_session::close(Session).

Per-request client-session options can also carry explicit SameSite
replay context when cookie replay depends on the request initiator or
whether the request is a top-level navigation:

::

   | ?- http_client_session::get(Session, 'http://app.example.com/data', Response,
        [source_origin('https://other.example.net'), top_level_navigation(true)]).

Sessions can also reopen a saved cookie jar directly:

::

   | ?- http_client_session::open(Session, [cookies_file('cookies.state')]),
        http_client_session::get(Session, 'http://127.0.0.1:8080/visits', Response, []),
        http_client_session::close(Session).

Use ``http_server_core_session`` when you need explicit server-side
session state over normalized request and response terms:

::

   | ?- http_server_core_session::open(Manager),
        http_core::request(get, origin('/visits'), http(1, 1), [], empty, [], Request0),
        http_server_core_session::begin(Manager, Request0, Request),
        http_server_core_session::current(Request, Session),
        http_server_core_session::set(Session, visits, 1),
        http_core::response(http(1, 1), status(200, 'OK'), [], empty, [], Response0),
        http_server_core_session::finish(Request, Response0, Response),
        http_server_core_session::close(Manager).

You can also work directly with the cookie jar:

::

   | ?- http_cookie_jar::open(Jar),
        http_cookie_jar::store_set_cookies(Jar, 'http://example.com/login', [set_cookie(session, '1', [path-('/')])]),
        http_cookie_jar::request_cookies(Jar, 'http://example.com/dashboard', Cookies).

When you need explicit SameSite replay control, use the primary
context-bearing cookie-jar API:

::

   | ?- http_cookie_jar::request_cookies(Jar, 'https://app.example.com/data',
        request_context(get, source_url('https://other.example.net/start'), true), Cookies).

Cookie jars can also be explicitly saved and restored:

::

   | ?- http_cookie_jar::open(Jar),
        http_cookie_jar::store_set_cookies(Jar, 'http://example.com/login', [set_cookie(session, '1', [path-('/')])]),
        http_cookie_jar::save(Jar, 'cookies.state'),
        http_cookie_jar::close(Jar),
        http_cookie_jar::open(RestoredJar, [cookies_file('cookies.state')]).

When these SameSite request-context controls are omitted, both
``http_client_session`` and ``http_cookie_jar::request_cookies/3``
default to ``request_context(get, source_url(URL), false)``, modeling a
same-site direct request to the target URL. Use ``source_url/1`` for a
full initiating URL and ``source_origin/1`` for a bare ``Origin`` header
value.

The ``cookies_file/1`` session option is a convenience for opening a
fresh owned cookie jar from disk. It is mutually exclusive with the
``cookie_jar/1`` session option.

Current scope
-------------

- in-memory cookie storage with explicit save and load support
- automatic cookie replay for explicit client-session handles
- context-bearing cookie replay using
  ``request_context(Method, Source, TopLevelNavigation)`` and the
  matching ``http_client_session`` request options ``source_url/1``,
  ``source_origin/1``, and ``top_level_navigation/1``
- in-memory server-side session storage keyed by opaque cookie
  identifiers
- direct server-session request begin/finish operations plus
  plain-handler and router adapters
- client-session transport via the existing parameterized
  ``http_client`` facade; with the default ``http_socket_transport``
  parameterization this means absolute ``http://`` URLs, while
  parameterizations such as ``http_process_transport`` also support
  ``https://`` URLs; cookie storage and SameSite source parsing accept
  both ``http://`` and ``https://`` URLs plus bare ``Origin`` values
- core handling for host-only and domain cookies, default path
  computation, secure filtering, ``Max-Age``, normalized ``Expires``
  HTTP-date values, and ``SameSite`` values
- schemeful SameSite replay semantics using the shared origin/site
  helper in ``http_core``, with cookies that omit ``SameSite`` treated
  as Lax-by-default
- server-session cookie emission with a default ``same_site-lax``
  template and validation that explicit ``same_site-none`` also requires
  ``secure-true``

Current limitations
-------------------

- HTTPS transport is not available with the default
  ``http_socket_transport`` parameterization; use a TLS-capable
  parameterization such as ``http_process_transport`` when
  client-session transport must support ``https://``
- automatic synchronization with the full Mozilla Public Suffix List
  snapshot
- browser-specific temporary Lax-allowing-unsafe grace windows
- full browser document lifecycle semantics for cookie replay decisions
- persistent or distributed server-session stores
- session-owned connection-pool management
