Did you know ... Search Documentation:
Pack logtalk -- logtalk-3.101.0/docs/handbook/_sources/libraries/http_session.rst.txt

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