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)).
0
(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.timeout.
permission_error(set, http_session, Setting) if setting a
setting that is not supported on per-session basis.| SessionId | is an atom. |
existence_error(http_session, _)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.
noauto. 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.permission_error(open, http_session, CGI) if this call is
used after closing the CGI header.create option. existence_error(http_session,_)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.
type_error(atom, SessionID)