object

# `http_server_core_session`

Server-side HTTP session manager over normalized request and response terms using opaque cookie identifiers and an in-memory session store.

Availability:
`logtalk_load(http_session(loader))`
Author: Paulo Moura
Version: 1:0:0
Date: 2026-07-09
Compilation flags:
`static, context_switching_calls`
Imports:
`public` options
Uses:
date
http_cookies(Representation)
http_core
ids
list
os
Remarks:
(none)
Inherited public predicates:
check_option/1 check_options/1 default_option/1 default_options/1 option/2 option/3 valid_option/1 valid_options/1

## Public predicates

### `open/1`

Opens a new server-session manager using the default cookie and timeout options.

Compilation flags:
`static`
Template:
`open(Manager)`
Mode and number of proofs:
`open(-compound)` - `one_or_error`
Exceptions:

### `open/2`

Opens a new server-session manager using the given cookie, timeout, and store options.

Compilation flags:
`static`
Template:
`open(Manager,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)`

### `close/1`

Closes a server-session manager and discards all in-memory request contexts and stored sessions owned by it.

Compilation flags:
`static`
Template:
`close(Manager)`
Mode and number of proofs:
`close(+compound)` - `one_or_error`
Exceptions:
`Manager` is a variable:
`instantiation_error`
`Manager` is neither a variable nor an open server-session manager handle:
`domain_error(http_server_core_session,Manager)`

### `begin/3`

Begins server-session processing for a normalized request, annotating it with a per-request session handle and the current session state.

Compilation flags:
`static`
Template:
`begin(Manager,Request,AnnotatedRequest)`
Mode and number of proofs:
`begin(+compound,+compound,-compound)` - `one_or_error`
Exceptions:
`Manager` is a variable:
`instantiation_error`
`Manager` is neither a variable nor an open server-session manager handle:
`domain_error(http_server_core_session,Manager)`
`Request` is not a valid normalized HTTP request:
`domain_error(http_server_core_session_request,Request)`

### `finish/3`

Finishes server-session processing for an annotated normalized request and a normalized response, adding any needed Set-Cookie lifecycle properties.

Compilation flags:
`static`
Template:
`finish(Request,Response0,Response)`
Mode and number of proofs:
`finish(+compound,+compound,-compound)` - `one_or_error`
Exceptions:
`Request` is not a valid annotated server-session request:
`domain_error(http_server_core_session_request,Request)`
`Response0` is not a valid normalized HTTP response:
`domain_error(http_server_core_session_response,Response0)`
The decorated response violates normalized HTTP response semantics:
`domain_error(http_header_semantics,Header)`

### `current/2`

Returns the request-bound current server-session handle from an annotated normalized request.

Compilation flags:
`static`
Template:
`current(Request,Session)`
Mode and number of proofs:
`current(+compound,-compound)` - `one_or_error`
Exceptions:
`Request` is not a valid annotated server-session request:
`domain_error(http_server_core_session_request,Request)`

### `ensure/2`

Ensures that the annotated request has a backing stored server session and returns its request-bound handle.

Compilation flags:
`static`
Template:
`ensure(Request,Session)`
Mode and number of proofs:
`ensure(+compound,-compound)` - `one_or_error`
Exceptions:
`Request` is not a valid annotated server-session request:
`domain_error(http_server_core_session_request,Request)`

### `data/2`

Returns the current session key-value data pairs for a request-bound server-session handle or `[]` when no backing session exists yet.

Compilation flags:
`static`
Template:
`data(Session,Data)`
Mode and number of proofs:
`data(+compound,-list(compound))` - `one_or_error`
Exceptions:
`Session` is a variable:
`instantiation_error`
`Session` is not a valid request-bound server-session handle:
`domain_error(http_server_core_session_handle,Session)`

### `get/3`

Returns the current value for a session data key from a request-bound server-session handle.

Compilation flags:
`static`
Template:
`get(Session,Key,Value)`
Mode and number of proofs:
`get(+compound,+term,-term)` - `zero_or_one`

### `set/3`

Sets or replaces a session data key-value pair, creating a backing stored session when needed.

Compilation flags:
`static`
Template:
`set(Session,Key,Value)`
Mode and number of proofs:
`set(+compound,+term,+term)` - `one_or_error`
Exceptions:
`Session` is a variable:
`instantiation_error`
`Session` is not a valid request-bound server-session handle:
`domain_error(http_server_core_session_handle,Session)`

### `remove/3`

Removes a session data key-value pair and returns its previous value.

Compilation flags:
`static`
Template:
`remove(Session,Key,Value)`
Mode and number of proofs:
`remove(+compound,+term,-term)` - `zero_or_one`

### `destroy/1`

Destroys the backing stored session, causing finish/3 to emit a deletion cookie when applicable.

Compilation flags:
`static`
Template:
`destroy(Session)`
Mode and number of proofs:
`destroy(+compound)` - `one_or_error`
Exceptions:
`Session` is a variable:
`instantiation_error`
`Session` is not a valid request-bound server-session handle:
`domain_error(http_server_core_session_handle,Session)`

### `renew/2`

Renews the backing stored session identifier and returns the new opaque cookie identifier.

Compilation flags:
`static`
Template:
`renew(Session,NewIdentifier)`
Mode and number of proofs:
`renew(+compound,-atom)` - `one_or_error`
Exceptions:
`Session` is a variable:
`instantiation_error`
`Session` is not a valid request-bound server-session handle:
`domain_error(http_server_core_session_handle,Session)`

### `gc/2`

Performs opportunistic garbage collection of expired stored sessions for the given manager and returns the number collected.

Compilation flags:
`static`
Template:
`gc(Manager,Collected)`
Mode and number of proofs:
`gc(+compound,-integer)` - `one_or_error`
Exceptions:
`Manager` is a variable:
`instantiation_error`
`Manager` is neither a variable nor an open server-session manager handle:
`domain_error(http_server_core_session,Manager)`

### `count/2`

Returns the number of currently stored sessions owned by the given manager.

Compilation flags:
`static`
Template:
`count(Manager,Count)`
Mode and number of proofs:
`count(+compound,-integer)` - `one_or_error`
Exceptions:
`Manager` is a variable:
`instantiation_error`
`Manager` is neither a variable nor an open server-session manager handle:
`domain_error(http_server_core_session,Manager)`

## Protected predicates

### `http_server_core_session_event/2`

Optional overridable hook predicate called with server-session lifecycle events.

Compilation flags:
`static`
Template:
`http_server_core_session_event(Manager,Event)`
Mode and number of proofs:
`http_server_core_session_event(+compound,+compound)` - `zero_or_one`

## Private predicates

### `manager_seed_/1`

Last allocated server-session manager identifier.

Compilation flags:
`dynamic`
Template:
`manager_seed_(ManagerId)`
Mode and number of proofs:
`manager_seed_(?positive_integer)` - `zero_or_one`

### `manager_state_/2`

Per-manager cookie, timeout, and garbage-collection state.

Compilation flags:
`dynamic`
Template:
`manager_state_(ManagerId,State)`
Mode and number of proofs:
`manager_state_(?positive_integer,?compound)` - `zero_or_more`

### `context_seed_/1`

Last allocated request context identifier.

Compilation flags:
`dynamic`
Template:
`context_seed_(ContextId)`
Mode and number of proofs:
`context_seed_(?positive_integer)` - `zero_or_one`

### `context_state_/2`

Per-request server-session context state.

Compilation flags:
`dynamic`
Template:
`context_state_(ContextId,Context)`
Mode and number of proofs:
`context_state_(?positive_integer,?compound)` - `zero_or_more`

### `stored_session_/6`

Stored server-session data entries owned by a manager.

Compilation flags:
`dynamic`
Template:
`stored_session_(ManagerId,SessionId,Data,CreatedAt,LastSeenAt,AbsoluteExpiryAt)`
Mode and number of proofs:
`stored_session_(?positive_integer,?atom,?list(compound),?non_negative_integer,?non_negative_integer,?nonvar)` - `zero_or_more`

## Operators

(none)