http_session.pl -- HTTP Session managementhttp_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:
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)).
http_set_session_options(+Options) is det0 (zero) disables timeout.swipl_session./. Cookies are only sent if the HTTP request path
is a refinement of Path.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.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.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:
'swipl:http:session' http_session_option(?Option) is nondet session_setting(+SessionID, ?Setting) is semidethttp_session_set(Setting). http_set_session(Setting) is det http_set_session(SessionId, Setting) is dettimeout.
http_session_id(-SessionId) is det http_in_session(-SessionId) is semidetsession(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.
http_session(+RequestIn, -RequestOut, -SessionID) is semidet[private]
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.
http_open_session(-SessionID, +Options) is detnoauto. Options:
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. peer(+Request, -Peer) is det[private] open_session(+SessionID, +Peer)[private]http_session(begin(SessionID, Peer)). valid_session_id(+SessionID, +Peer) is semidet[private] set_last_used(+SessionID, +Now, +TimeOut)[private] http_session_asserta(+Data) is det http_session_assert(+Data) is det http_session_retract(?Data) is nondet http_session_retractall(?Data) is det http_session_data(?Data) is nondet http_session_asserta(+Data, +SessionID) is det http_session_assert(+Data, +SessionID) is det http_session_retract(?Data, +SessionID) is nondet http_session_retractall(@Data, +SessionID) is det http_session_data(?Data, +SessionID) is det http_current_session(?SessionID, ?Data) is nondet http_close_session(+SessionID) is dethttp_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.
expire_session_cookie(+Expire) is det[private] http_gc_sessions is det[private] http_gc_sessions(+TimeOut) is det[private] start_session_gc_thread is det[private] stop_session_gc_thread is det[private] http_session_cookie(-Cookie) is det route(-RouteID) is semidet[private] urandom(-Handle) is semidet[private] random_4(-R1, -R2, -R3, -R4) is det[private]/dev/urandom when
available to make prediction of the session IDs hard.The following predicates are exported, but not or incorrectly documented.
http_session_data(Arg1, Arg2) http_session_retractall(Arg1, Arg2) http_session_assert(Arg1, Arg2) http_session_retract(Arg1, Arg2) http_session_assert(Arg1) http_session_retract(Arg1) http_session_retractall(Arg1) http_set_session(Arg1, Arg2)