All predicatesShow sourcehttp_session.pl -- HTTP Session management

This library defines session management based on HTTP cookies. Session management is enabled simply by loading this module. Details can be modified using http_set_session_options/1. By default, this module creates a session whenever a request is processes that is inside the hierarchy defined for session handling (see path option in http_set_session_options/1). Automatic creation of a session can be stopped using the option create(noauto). The predicate http_open_session/2 must be used to create a session if noauto is enabled. Sessions can be closed using http_close_session/1.

If a session is active, http_in_session/1 returns the current session and http_session_assert/1 and friends maintain data about the session. If the session is reclaimed, all associated data is reclaimed too.

Begin and end of sessions can be monitored using library(broadcast). The broadcasted messages are:

http_session(begin(SessionID, Peer))
Broadcasted if a session is started
http_session(end(SessionId, Peer))
Broadcasted if a session is ended. See http_close_session/1.

For example, the following calls end_session(SessionId) whenever a session terminates. Please note that sessions ends are not scheduled to happen at the actual timeout moment of the session. Instead, creating a new session scans the active list for timed-out sessions. This may change in future versions of this library.

:- listen(http_session(end(SessionId, Peer)),
          end_session(SessionId)).
Source http_set_session_options(+Options) is det
Set options for the session library. Provided options are:
timeout(+Seconds)
Session timeout in seconds. Default is 600 (10 min). A timeout of 0 (zero) disables timeout.
cookie(+Cookiekname)
Name to use for the cookie to identify the session. Default swipl_session.
path(+Path)
Path to which the cookie is associated. Default is /. Cookies are only sent if the HTTP request path is a refinement of Path.
route(+Route)
Set the route name. Default is the unqualified hostname. To cancel adding a route, use the empty atom. See route/1.
enabled(+Boolean)
Enable/disable session management. Sesion management is enabled by default after loading this file.
create(+Atom)
Defines when a session is created. This is one of auto (default), which creates a session if there is a request whose path matches the defined session path or noauto, in which cases sessions are only created by calling http_open_session/2 explicitely.
proxy_enabled(+Boolean)
Enable/disable proxy session management. Proxy session management associates the originating IP address of the client to the session rather than the proxy IP address. Default is false.
gc(+When)
When is one of active, which starts a thread that performs session cleanup at close to the moment of the timeout or passive, which runs session GC when a new session is created.
samesite(+Restriction)
One of none, lax (default), or strict - The SameSite attribute prevents the CSRF vulnerability. strict has best security, but prevents links from external sites from operating properly. lax stops most CSRF attacks against REST endpoints but rarely interferes with legitimage operations. none removes the samesite attribute entirely. Caution: The value none exposes the entire site to CSRF attacks.

In addition, extension libraries can define session_option/2 to make this predicate support more options. In particular, library(http/http_redis_plugin) defines the following additional options:

redis_db(+DB)
Alias name of the redis database to access. See redis_server/2.
redis_prefix(+Atom)
Prefix to use for all HTTP session related keys. Default is 'swipl:http:session'
Source http_session_option(?Option) is nondet
True if Option is a current option of the session system.
Source session_setting(+SessionID, ?Setting) is semidet[private]
Find setting for SessionID. It is possible to overrule some session settings using http_session_set(Setting).
Source http_set_session(Setting) is det
Source http_set_session(SessionId, Setting) is det
Overrule a setting for the current or specified session. Currently, the only setting that can be overruled is timeout.
Errors
- permission_error(set, http_session, Setting) if setting a setting that is not supported on per-session basis.
Source http_session_id(-SessionId) is det
True if SessionId is an identifier for the current session.
Arguments:
SessionId- is an atom.
Errors
- existence_error(http_session, _)
See also
- http_in_session/1 for a version that fails if there is no session.
Source http_in_session(-SessionId) is semidet
True if SessionId is an identifier for the current session. The current session is extracted from session(ID) from the current HTTP request (see http_current_request/1). The value is cached in a backtrackable global variable http_session_id. Using a backtrackable global variable is safe because continuous worker threads use a failure driven loop and spawned threads start without any global variables. This variable can be set from the commandline to fake running a goal from the commandline in the context of a session.
See also
- http_session_id/1
Source http_session(+RequestIn, -RequestOut, -SessionID) is semidet[private]
Maintain the notion of a session using a client-side cookie. This must be called first when handling a request that wishes to do session management, after which the possibly modified request must be used for further processing.

This predicate creates a session if the setting create is auto. If create is noauto, the application must call http_open_session/1 to create a session.

Source http_open_session(-SessionID, +Options) is det
Establish a new session. This is normally used if the create option is set to noauto. Options:
renew(+Boolean)
If true (default false) and the current request is part of a session, generate a new session-id. By default, this predicate returns the current session as obtained with http_in_session/1.
Errors
- permission_error(open, http_session, CGI) if this call is used after closing the CGI header.
See also
- http_set_session_options/1 to control the create option.
- http_close_session/1 for closing the session.
Source peer(+Request, -Peer) is det[private]
Find peer for current request. If unknown we leave it unbound. Alternatively we should treat this as an error.
Source open_session(+SessionID, +Peer)[private]
Open a new session. Uses broadcast/1 with the term http_session(begin(SessionID, Peer)).
Source valid_session_id(+SessionID, +Peer) is semidet[private]
Check if this sessionID is known. If so, check the idle time and update the last_used for this session.
Source set_last_used(+SessionID, +Now, +TimeOut)[private]
Set the last-used notion for SessionID from the current time stamp. The time is rounded down to 10 second intervals to avoid many updates and simplify the scheduling of session GC.
Source http_session_asserta(+Data) is det
Source http_session_assert(+Data) is det
Source http_session_retract(?Data) is nondet
Source http_session_retractall(?Data) is det
Versions of assert/1, retract/1 and retractall/1 that associate data with the current HTTP session.
Source http_session_data(?Data) is nondet
True if Data is associated using http_session_assert/1 to the current HTTP session.
Errors
- existence_error(http_session,_)
Source http_session_asserta(+Data, +SessionID) is det
Source http_session_assert(+Data, +SessionID) is det
Source http_session_retract(?Data, +SessionID) is nondet
Source http_session_retractall(@Data, +SessionID) is det
Source http_session_data(?Data, +SessionID) is det
Versions of assert/1, retract/1 and retractall/1 that associate data with an explicit HTTP session.
See also
- http_current_session/2.
Source http_current_session(?SessionID, ?Data) is nondet
Enumerate the current sessions and associated data. There are two pseudo data elements:
idle(Seconds)
Session has been idle for Seconds.
peer(Peer)
Peer of the connection.
Source http_close_session(+SessionID) is det
Closes an HTTP session. This predicate can be called from any thread to terminate a session. It uses the broadcast/1 service with the message below.
http_session(end(SessionId, Peer))

The broadcast is done before the session data is destroyed and the listen-handlers are executed in context of the session that is being closed. Here is an example that destroys a Prolog thread that is associated to a thread:

:- listen(http_session(end(SessionId, _Peer)),
          kill_session_thread(SessionID)).

kill_session_thread(SessionID) :-
        http_session_data(thread(ThreadID)),
        thread_signal(ThreadID, throw(session_closed)).

Succeed without any effect if SessionID does not refer to an active session.

If http_close_session/1 is called from a handler operating in the current session and the CGI stream is still in state header, this predicate emits a Set-Cookie to expire the cookie.

Errors
- type_error(atom, SessionID)
See also
- listen/2 for acting upon closed sessions
Source expire_session_cookie(+Expire) is det[private]
Emit a request to delete a session cookie. This is only done if http_close_session/1 is still in `header mode'.
Source http_gc_sessions is det[private]
Source http_gc_sessions(+TimeOut) is det[private]
Delete dead sessions. Currently runs session GC if a new session is opened and the last session GC was more than a TimeOut ago.
Source start_session_gc_thread is det[private]
Source stop_session_gc_thread is det[private]
Create/stop a thread that listens for timeout-at timing and wakes up to run http_gc_sessions/1 shortly after a session is scheduled to timeout.
Source http_session_cookie(-Cookie) is det
Generate a random cookie that can be used by a browser to identify the current session. The cookie has the format XXXX-XXXX-XXXX-XXXX[.<route>], where XXXX are random hexadecimal numbers and [.<route>] is the optionally added routing information.
Source route(-RouteID) is semidet[private]
Fetch the route identifier. This value is added as .<route> to the session cookie and used by -for example- the apache load balanching module. The default route is the local name of the host. Alternatives may be provided using http_set_session_options/1.
Source urandom(-Handle) is semidet[private]
Handle is a stream-handle for /dev/urandom. Originally, this simply tried to open /dev/urandom, failing if this device does not exist. It turns out that trying to open /dev/urandom can block indefinitely on some Windows installations, so we no longer try this on Windows.
Source random_4(-R1, -R2, -R3, -R4) is det[private]
Generate 4 2-byte random numbers. Uses /dev/urandom when available to make prediction of the session IDs hard.

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

Source http_set_session(Arg1, Arg2)
Source http_session_data(Arg1, Arg2)
Source http_session_retractall(Arg1, Arg2)
Source http_session_assert(Arg1, Arg2)
Source http_session_retract(Arg1, Arg2)
Source http_session_assert(Arg1)
Source http_session_retract(Arg1)
Source http_session_retractall(Arg1)