- Documentation
- Reference manual
- Packages
- SWI-Prolog HTTP support
- The HTTP server libraries
- The `Body'
- library(http/http_dispatch): Dispatch requests in the HTTP server
- library(http/http_dirindex): HTTP directory listings
- library(http/http_files): Serve plain files from a hierarchy
- library(http/http_session): HTTP Session management
- http_set_session_options/1
- http_session_option/1
- http_set_session/1
- http_set_session/2
- http_session_id/1
- http_in_session/1
- http_open_session/2
- http_session_asserta/1
- http_session_assert/1
- http_session_retract/1
- http_session_retractall/1
- http_session_data/1
- http_current_session/2
- http_close_session/1
- http_session_cookie/1
- library(http/http_cors): Enable CORS: Cross-Origin Resource Sharing
- library(http/http_authenticate): Authenticate HTTP connections using 401 headers
- library(http/http_digest): HTTP Digest authentication
- Custom Error Pages
- library(http/http_openid): OpenID consumer and server library
- Get parameters from HTML forms
- Request format
- Running the server
- The wrapper library
- library(http/http_host): Obtain public server location
- library(http/http_log): HTTP Logging module
- Debugging HTTP servers
- library(http/http_header): Handling HTTP headers
- The library(http/html_write) library
- library(http/js_write): Utilities for including JavaScript
- library(http/http_path): Abstract specification of HTTP server locations
- library(http/html_head): Automatic inclusion of CSS and scripts links
- library(http/http_pwp): Serve PWP pages through the HTTP server
- The HTTP server libraries
- SWI-Prolog HTTP support
3.5 library(http/http_session): 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)).
- [det]http_set_session_options(+Options)
- 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 ornoauto
, 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.
- [nondet]http_session_option(?Option)
- True if Option is a current option of the session system.
- [det]http_set_session(Setting)
- [det]http_set_session(SessionId, Setting)
- 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.
- [det]http_session_id(-SessionId)
- True if SessionId is an identifier for the current session.
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.
- [semidet]http_in_session(-SessionId)
- 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 variablehttp_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
- [det]http_open_session(-SessionID, +Options)
- Establish a new session. This is normally used if the create option is
set to
noauto
. Options:- renew(+Boolean)
- If
true
(defaultfalse
) 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.
- [det]http_session_asserta(+Data)
- [det]http_session_assert(+Data)
- [nondet]http_session_retract(?Data)
- [det]http_session_retractall(?Data)
- Versions of assert/1, retract/1 and retractall/1 that associate data with the current HTTP session.
- [nondet]http_session_data(?Data)
- True if Data is associated using http_session_assert/1
to the current HTTP session.
- Errors
existence_error(http_session,_)
- [nondet]http_current_session(?SessionID, ?Data)
- 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.
- [det]http_close_session(+SessionID)
- 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 aSet-Cookie
to expire the cookie.- Errors
type_error(atom, SessionID)
- See also
- listen/2 for acting upon closed sessions
- [det]http_session_cookie(-Cookie)
- 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.