http_session.pl

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.

http_session_option(?Option) is nondet

True if Option is a current option of the session system.

session_setting(+SessionID, ?Setting) is semidet

Find setting for SessionID. It is possible to overrule some session settings using http_session_set(Setting).

http_set_session(Setting) is det

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.

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.

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

http_session(+RequestIn, -RequestOut, -SessionID) is semidet

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.

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.

peer(+Request, -Peer) is det

Find peer for current request. If unknown we leave it unbound. Alternatively we should treat this as an error.

open_session(+SessionID, +Peer)

Open a new session. Uses broadcast/1 with the term http_session(begin(SessionID, Peer)).

valid_session_id(+SessionID, +Peer) is semidet

Check if this sessionID is known. If so, check the idle time and update the last_used for this session.

set_last_used(+SessionID, +Now, +TimeOut)

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.

http_session_asserta(+Data) is det

http_session_assert(+Data) is det

http_session_retract(?Data) is nondet

http_session_retractall(?Data) is det

Versions of assert/1, retract/1 and retractall/1 that associate data with the current HTTP session.

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,_)

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.

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

expire_session_cookie(+SessionId) is det

Emit a request to delete a session cookie. This is only done if http_close_session/1 is still in `header mode'.

http_gc_sessions is det

http_gc_sessions(+TimeOut) is det

Delete dead sessions. Currently runs session GC if a new session is opened and the last session GC was more than a TimeOut ago.

start_session_gc_thread is det

stop_session_gc_thread is det

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.

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.

route(-RouteID) is semidet

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.

urandom(-Handle) is semidet

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.

random_4(-R1, -R2, -R3, -R4) is det

Generate 4 2-byte random numbers. Uses /dev/urandom when available to make prediction of the session IDs hard.

HTTP Session management