View source with raw comments or as raw
    1/*  Part of SWI-Prolog
    2
    3    Author:        Jan Wielemaker, Matt Lilley
    4    E-mail:        J.Wielemaker@cs.vu.nl
    5    WWW:           http://www.swi-prolog.org
    6    Copyright (c)  2006-2024, University of Amsterdam
    7                              VU University Amsterdam
    8                              CWI, Amsterdam
    9                              SWI-Prolog Solutions b.v.
   10    All rights reserved.
   11
   12    Redistribution and use in source and binary forms, with or without
   13    modification, are permitted provided that the following conditions
   14    are met:
   15
   16    1. Redistributions of source code must retain the above copyright
   17       notice, this list of conditions and the following disclaimer.
   18
   19    2. Redistributions in binary form must reproduce the above copyright
   20       notice, this list of conditions and the following disclaimer in
   21       the documentation and/or other materials provided with the
   22       distribution.
   23
   24    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   25    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   26    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
   27    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
   28    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
   29    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
   30    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
   31    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
   32    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   33    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
   34    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
   35    POSSIBILITY OF SUCH DAMAGE.
   36*/
   37
   38:- module(http_session,
   39          [ http_set_session_options/1, % +Options
   40            http_set_session/1,         % +Option
   41            http_set_session/2,         % +SessionId, +Option
   42            http_session_option/1,      % ?Option
   43
   44            http_session_id/1,          % -SessionId
   45            http_in_session/1,          % -SessionId
   46            http_current_session/2,     % ?SessionId, ?Data
   47            http_close_session/1,       % +SessionId
   48            http_open_session/2,        % -SessionId, +Options
   49
   50            http_session_cookie/1,      % -Cookie
   51
   52            http_session_asserta/1,     % +Data
   53            http_session_assert/1,      % +Data
   54            http_session_retract/1,     % ?Data
   55            http_session_retractall/1,  % +Data
   56            http_session_data/1,        % ?Data
   57
   58            http_session_asserta/2,     % +Data, +SessionId
   59            http_session_assert/2,      % +Data, +SessionId
   60            http_session_retract/2,     % ?Data, +SessionId
   61            http_session_retractall/2,  % +Data, +SessionId
   62            http_session_data/2         % ?Data, +SessionId
   63          ]).   64:- use_module(http_wrapper).   65:- use_module(http_stream).   66:- use_module(library(error)).   67:- use_module(library(debug)).   68:- use_module(library(socket)).   69:- use_module(library(broadcast)).   70:- use_module(library(lists)).   71:- use_module(library(time)).   72:- use_module(library(option)).   73
   74:- predicate_options(http_open_session/2, 2, [renew(boolean)]).

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)).

*/

  112:- dynamic
  113    session_setting/1,              % Name(Value)
  114    current_session/2,              % SessionId, Peer
  115    last_used/2,                    % SessionId, Time
  116    session_data/2.                 % SessionId, Data
  117
  118:- multifile
  119    hooked/0,
  120    hook/1,                         % +Term
  121    session_setting/1,
  122    session_option/2.  123
  124session_setting(timeout(600)).      % timeout in seconds
  125session_setting(granularity(60)).   % granularity for timeout
  126session_setting(cookie('swipl_session')).
  127session_setting(path(/)).
  128session_setting(enabled(true)).
  129session_setting(create(auto)).
  130session_setting(proxy_enabled(false)).
  131session_setting(gc(passive)).
  132session_setting(samesite(lax)).
  133
  134session_option(timeout, integer).
  135session_option(granularity, integer).
  136session_option(cookie, atom).
  137session_option(path, atom).
  138session_option(create, oneof([auto,noauto])).
  139session_option(route, atom).
  140session_option(enabled, boolean).
  141session_option(proxy_enabled, boolean).
  142session_option(gc, oneof([active,passive])).
  143session_option(samesite, oneof([none,lax,strict])).
 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.
granularity(+Integer)
Granularity for updating that the session is active. Default is 60 (seconds). Smaller values lead to more precise session timeout at the cost of more database updates. This may notably a problem when using Redis.

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/3.
redis_ro(+DB)
Alias name of the redis database for read-only access. See redis_server/3.
redis_prefix(+Atom)
Prefix to use for all HTTP session related keys. Default is 'swipl:http:session'
  219http_set_session_options([]) => true.
  220http_set_session_options([H|T]) =>
  221    http_set_session_option(H),
  222    http_set_session_options(T).
  223
  224http_set_session_option(Option), Option =.. [Name,Value] =>
  225    (   session_option(Name, Type)
  226    ->  must_be(Type, Value)
  227    ;   domain_error(http_session_option, Option)
  228    ),
  229    functor(Free, Name, 1),
  230    (   clause(session_setting(Free), _, Ref)
  231    ->  (   Free \== Value
  232        ->  asserta(session_setting(Option)),
  233            erase(Ref),
  234            updated_session_setting(Name, Free, Value)
  235        ;   true
  236        )
  237    ;   asserta(session_setting(Option))
  238    ).
 http_session_option(?Option) is nondet
True if Option is a current option of the session system.
  244http_session_option(Option) :-
  245    session_setting(Option).
 session_setting(+SessionID, ?Setting) is semidet
Find setting for SessionID. It is possible to overrule some session settings using http_session_set(Setting).
  252:- public session_setting/2.  253
  254session_setting(SessionID, Setting) :-
  255    nonvar(Setting),
  256    get_session_option(SessionID, Setting),
  257    !.
  258session_setting(_, Setting) :-
  259    session_setting(Setting).
  260
  261get_session_option(SessionID, Setting) :-
  262    hooked,
  263    !,
  264    hook(get_session_option(SessionID, Setting)).
  265get_session_option(SessionID, Setting) :-
  266    functor(Setting, Name, 1),
  267    local_option(Name, Value, Term),
  268    session_data(SessionID, '$setting'(Term)),
  269    !,
  270    arg(1, Setting, Value).
  271
  272
  273updated_session_setting(gc, _, passive) :-
  274    stop_session_gc_thread, !.
  275updated_session_setting(_, _, _).               % broadcast?
 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.
  287http_set_session(Setting) :-
  288    http_session_id(SessionId),
  289    http_set_session(SessionId, Setting).
  290
  291http_set_session(SessionId, Setting) :-
  292    functor(Setting, Name, _),
  293    (   local_option(Name, _, _)
  294    ->  true
  295    ;   permission_error(set, http_session, Setting)
  296    ),
  297    arg(1, Setting, Value),
  298    (   session_option(Name, Type)
  299    ->  must_be(Type, Value)
  300    ;   domain_error(http_session_option, Setting)
  301    ),
  302    set_session_option(SessionId, Setting).
  303
  304set_session_option(SessionId, Setting) :-
  305    hooked,
  306    !,
  307    hook(set_session_option(SessionId, Setting)).
  308set_session_option(SessionId, Setting) :-
  309    functor(Setting, Name, Arity),
  310    functor(Free, Name, Arity),
  311    retractall(session_data(SessionId, '$setting'(Free))),
  312    assert(session_data(SessionId, '$setting'(Setting))).
  313
  314local_option(timeout, X, timeout(X)).
 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.
  325http_session_id(SessionID) :-
  326    (   http_in_session(ID)
  327    ->  SessionID = ID
  328    ;   throw(error(existence_error(http_session, _), _))
  329    ).
 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
  345http_in_session(SessionID) :-
  346    nb_current(http_session_id, ID),
  347    ID \== [],
  348    !,
  349    debug(http_session, 'Session id from global variable: ~q', [ID]),
  350    ID \== no_session,
  351    SessionID = ID.
  352http_in_session(SessionID) :-
  353    http_current_request(Request),
  354    http_in_session(Request, SessionID).
  355
  356http_in_session(Request, SessionID) :-
  357    memberchk(session(ID), Request),
  358    !,
  359    debug(http_session, 'Session id from request: ~q', [ID]),
  360    b_setval(http_session_id, ID),
  361    SessionID = ID.
  362http_in_session(Request, SessionID) :-
  363    memberchk(cookie(Cookies), Request),
  364    session_setting(cookie(Cookie)),
  365    member(Cookie=SessionID0, Cookies),
  366    debug(http_session, 'Session id from cookie: ~q', [SessionID0]),
  367    peer(Request, Peer),
  368    valid_session_id(SessionID0, Peer),
  369    !,
  370    b_setval(http_session_id, SessionID0),
  371    SessionID = SessionID0.
 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.

  385http_session(Request, Request, SessionID) :-
  386    memberchk(session(SessionID0), Request),
  387    !,
  388    SessionID = SessionID0.
  389http_session(Request0, Request, SessionID) :-
  390    memberchk(cookie(Cookies), Request0),
  391    session_setting(cookie(Cookie)),
  392    member(Cookie=SessionID0, Cookies),
  393    peer(Request0, Peer),
  394    valid_session_id(SessionID0, Peer),
  395    !,
  396    SessionID = SessionID0,
  397    Request = [session(SessionID)|Request0],
  398    b_setval(http_session_id, SessionID).
  399http_session(Request0, Request, SessionID) :-
  400    session_setting(create(auto)),
  401    session_setting(path(Path)),
  402    memberchk(path(ReqPath), Request0),
  403    sub_atom(ReqPath, 0, _, _, Path),
  404    !,
  405    create_session(Request0, Request, SessionID).
  406
  407create_session(Request0, Request, SessionID) :-
  408    http_gc_sessions,
  409    http_session_cookie(SessionID),
  410    session_setting(cookie(Cookie)),
  411    session_setting(path(Path)),
  412    session_setting(samesite(SameSite)),
  413    debug(http_session, 'Created session ~q at path=~q', [SessionID, Path]),
  414    (   SameSite == none
  415    ->  format('Set-Cookie: ~w=~w; Path=~w; Version=1\r\n',
  416               [Cookie, SessionID, Path])
  417    ;   format('Set-Cookie: ~w=~w; Path=~w; Version=1; SameSite=~w\r\n',
  418               [Cookie, SessionID, Path, SameSite])
  419    ),
  420    Request = [session(SessionID)|Request0],
  421    peer(Request0, Peer),
  422    open_session(SessionID, Peer).
 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.
  441http_open_session(SessionID, Options) :-
  442    http_in_session(SessionID0),
  443    \+ option(renew(true), Options, false),
  444    !,
  445    SessionID = SessionID0.
  446http_open_session(SessionID, _Options) :-
  447    (   in_header_state
  448    ->  true
  449    ;   current_output(CGI),
  450        permission_error(open, http_session, CGI)
  451    ),
  452    (   http_in_session(ActiveSession)
  453    ->  http_close_session(ActiveSession, false)
  454    ;   true
  455    ),
  456    http_current_request(Request),
  457    create_session(Request, _, SessionID).
  458
  459
  460:- multifile
  461    http:request_expansion/2.  462
  463http:request_expansion(Request0, Request) :-
  464    session_setting(enabled(true)),
  465    http_session(Request0, Request, _SessionID).
 peer(+Request, -Peer) is det
Find peer for current request. If unknown we leave it unbound. Alternatively we should treat this as an error.
  472peer(Request, Peer) :-
  473    (   session_setting(proxy_enabled(true)),
  474        http_peer(Request, Peer)
  475    ->  true
  476    ;   memberchk(peer(Peer), Request)
  477    ->  true
  478    ;   true
  479    ).
 open_session(+SessionID, +Peer)
Open a new session. Uses broadcast/1 with the term http_session(begin(SessionID, Peer)).
  486open_session(SessionID, Peer) :-
  487    assert_session(SessionID, Peer),
  488    b_setval(http_session_id, SessionID),
  489    broadcast(http_session(begin(SessionID, Peer))).
  490
  491assert_session(SessionID, Peer) :-
  492    hooked,
  493    !,
  494    hook(assert_session(SessionID, Peer)).
  495assert_session(SessionID, Peer) :-
  496    get_time(Now),
  497    assert(current_session(SessionID, Peer)),
  498    assert(last_used(SessionID, Now)).
 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.
  505valid_session_id(SessionID, Peer) :-
  506    active_session(SessionID, SessionPeer, LastUsed),
  507    get_time(Now),
  508    (   session_setting(SessionID, timeout(Timeout)),
  509        Timeout > 0
  510    ->  Idle is Now - LastUsed,
  511        (   Idle =< Timeout
  512        ->  true
  513        ;   http_close_session(SessionID),
  514            fail
  515        )
  516    ;   Peer \== SessionPeer
  517    ->  http_close_session(SessionID),
  518        fail
  519    ;   true
  520    ),
  521    set_last_used(SessionID, Now, Timeout).
  522
  523active_session(SessionID, Peer, LastUsed) :-
  524    hooked,
  525    !,
  526    hook(active_session(SessionID, Peer, LastUsed)).
  527active_session(SessionID, Peer, LastUsed) :-
  528    current_session(SessionID, Peer),
  529    get_last_used(SessionID, LastUsed).
  530
  531get_last_used(SessionID, Last) :-
  532    atom(SessionID),
  533    !,
  534    once(last_used(SessionID, Last)).
  535get_last_used(SessionID, Last) :-
  536    last_used(SessionID, Last).
 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.
  544set_last_used(SessionID, Now, TimeOut) :-
  545    hooked,
  546    !,
  547    hook(set_last_used(SessionID, Now, TimeOut)).
  548set_last_used(SessionID, Now, TimeOut) :-
  549    session_setting(granularity(TimeGranularity)),
  550    LastUsed is floor(Now/TimeGranularity)*TimeGranularity,
  551    (   clause(last_used(SessionID, CurrentLast), _, Ref)
  552    ->  (   CurrentLast == LastUsed
  553        ->  true
  554        ;   asserta(last_used(SessionID, LastUsed)),
  555            erase(Ref),
  556            schedule_gc(LastUsed, TimeOut)
  557        )
  558    ;   asserta(last_used(SessionID, LastUsed)),
  559        schedule_gc(LastUsed, TimeOut)
  560    ).
  561
  562
  563                 /*******************************
  564                 *         SESSION DATA         *
  565                 *******************************/
 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.
  575http_session_asserta(Data) :-
  576    http_session_id(SessionId),
  577    (   hooked
  578    ->  hook(asserta(session_data(SessionId, Data)))
  579    ;   asserta(session_data(SessionId, Data))
  580    ).
  581
  582http_session_assert(Data) :-
  583    http_session_id(SessionId),
  584    (   hooked
  585    ->  hook(assertz(session_data(SessionId, Data)))
  586    ;   assertz(session_data(SessionId, Data))
  587    ).
  588
  589http_session_retract(Data) :-
  590    http_session_id(SessionId),
  591    (   hooked
  592    ->  hook(retract(session_data(SessionId, Data)))
  593    ;   retract(session_data(SessionId, Data))
  594    ).
  595
  596http_session_retractall(Data) :-
  597    http_session_id(SessionId),
  598    (   hooked
  599    ->  hook(retractall(session_data(SessionId, Data)))
  600    ;   retractall(session_data(SessionId, Data))
  601    ).
 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,_)
  610http_session_data(Data) :-
  611    http_session_id(SessionId),
  612    (   hooked
  613    ->  hook(session_data(SessionId, Data))
  614    ;   session_data(SessionId, Data)
  615    ).
 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
Versions of assert/1, retract/1 and retractall/1 that associate data with an explicit HTTP session.
See also
- http_current_session/2.
  628http_session_asserta(Data, SessionId) :-
  629    must_be(atom, SessionId),
  630    (   hooked
  631    ->  hook(asserta(session_data(SessionId, Data)))
  632    ;   asserta(session_data(SessionId, Data))
  633    ).
  634
  635http_session_assert(Data, SessionId) :-
  636    must_be(atom, SessionId),
  637    (   hooked
  638    ->  hook(assertz(session_data(SessionId, Data)))
  639    ;   assertz(session_data(SessionId, Data))
  640    ).
  641
  642http_session_retract(Data, SessionId) :-
  643    must_be(atom, SessionId),
  644    (   hooked
  645    ->  hook(retract(session_data(SessionId, Data)))
  646    ;   retract(session_data(SessionId, Data))
  647    ).
  648
  649http_session_retractall(Data, SessionId) :-
  650    must_be(atom, SessionId),
  651    (   hooked
  652    ->  hook(retractall(session_data(SessionId, Data)))
  653    ;   retractall(session_data(SessionId, Data))
  654    ).
  655
  656http_session_data(Data, SessionId) :-
  657    must_be(atom, SessionId),
  658    (   hooked
  659    ->  hook(session_data(SessionId, Data))
  660    ;   session_data(SessionId, Data)
  661    ).
  662
  663
  664                 /*******************************
  665                 *           ENUMERATE          *
  666                 *******************************/
 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.
  679http_current_session(SessionID, Data) :-
  680    hooked,
  681    !,
  682    hook(current_session(SessionID, Data)).
  683http_current_session(SessionID, Data) :-
  684    get_time(Now),
  685    get_last_used(SessionID, Last), % binds SessionID
  686    Idle is Now - Last,
  687    (   session_setting(SessionID, timeout(Timeout)),
  688        Timeout > 0
  689    ->  Idle =< Timeout
  690    ;   true
  691    ),
  692    (   Data = idle(Idle)
  693    ;   Data = peer(Peer),
  694        current_session(SessionID, Peer)
  695    ;   session_data(SessionID, Data)
  696    ).
  697
  698
  699                 /*******************************
  700                 *          GC SESSIONS         *
  701                 *******************************/
 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
  736http_close_session(SessionId) :-
  737    http_close_session(SessionId, true).
  738
  739http_close_session(SessionId, Expire) :-
  740    hooked,
  741    !,
  742    forall(hook(close_session(SessionId)),
  743           expire_session_cookie(Expire)).
  744http_close_session(SessionId, Expire) :-
  745    must_be(atom, SessionId),
  746    (   current_session(SessionId, Peer),
  747        (   b_setval(http_session_id, SessionId),
  748            broadcast(http_session(end(SessionId, Peer))),
  749            fail
  750        ;   true
  751        ),
  752        expire_session_cookie(Expire),
  753        retractall(current_session(SessionId, _)),
  754        retractall(last_used(SessionId, _)),
  755        retractall(session_data(SessionId, _)),
  756        fail
  757    ;   true
  758    ).
 expire_session_cookie(+Expire) is det
Emit a request to delete a session cookie. This is only done if http_close_session/1 is still in `header mode'.
  766expire_session_cookie(true) :-
  767    !,
  768    expire_session_cookie.
  769expire_session_cookie(_).
  770
  771expire_session_cookie :-
  772    in_header_state,
  773    session_setting(cookie(Cookie)),
  774    session_setting(path(Path)),
  775    !,
  776    format('Set-Cookie: ~w=; \c
  777                expires=Tue, 01-Jan-1970 00:00:00 GMT; \c
  778                path=~w\r\n',
  779           [Cookie, Path]).
  780expire_session_cookie.
  781
  782in_header_state :-
  783    current_output(CGI),
  784    is_cgi_stream(CGI),
  785    cgi_property(CGI, state(header)),
  786    !.
 http_gc_sessions is det
 http_gc_sessions(+TimeOut) is det
Delete dead sessions. There are two modes. if gc(passive) is active (default), session GC is executed if a new session is created and if the last GC was more than granularity ago. If gc(active) is on, a thread is created that runs the session GC every granularity seconds.

http_gc_sessions/0 is called each time when a session is created.

  800:- dynamic
  801    last_gc/1.  802
  803http_gc_sessions :-
  804    session_setting(gc(active)),
  805    !,
  806    start_session_gc_thread.
  807http_gc_sessions :-
  808    session_setting(granularity(TimeGranularity)),
  809    http_gc_sessions(TimeGranularity).
  810
  811http_gc_sessions(TimeOut) :-
  812    (   with_mutex(http_session_gc, need_sesion_gc(TimeOut))
  813    ->  do_http_gc_sessions
  814    ;   true
  815    ).
  816
  817need_sesion_gc(TimeOut) :-
  818    get_time(Now),
  819    (   last_gc(LastGC),
  820        Now-LastGC < TimeOut
  821    ->  fail
  822    ;   retractall(last_gc(_)),
  823        asserta(last_gc(Now))
  824    ).
  825
  826do_http_gc_sessions :-
  827    hooked,
  828    !,
  829    hook(gc_sessions).
  830do_http_gc_sessions :-
  831    debug(http_session(gc), 'Running HTTP session GC', []),
  832    get_time(Now),
  833    (   session_setting(SessionID, timeout(Timeout)),
  834        last_used(SessionID, Last),
  835        Timeout > 0,
  836        Idle is Now - Last,
  837        Idle > Timeout,
  838        http_close_session(SessionID, false),
  839        fail
  840    ;   true
  841    ).
 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.
  850:- dynamic
  851    session_gc_queue/1.  852
  853start_session_gc_thread :-
  854    session_gc_queue(_),
  855    !.
  856start_session_gc_thread :-
  857    session_setting(gc(active)),
  858    !,
  859    catch(thread_create(session_gc_loop, _,
  860                        [ alias('__http_session_gc'),
  861                          at_exit(retractall(session_gc_queue(_))),
  862                          inherit_from(main)
  863                        ]),
  864          error(permission_error(create, thread, _),_),
  865          true).
  866start_session_gc_thread.
  867
  868stop_session_gc_thread :-
  869    retract(session_gc_queue(Id)),
  870    !,
  871    thread_send_message(Id, done),
  872    thread_join(Id, _).
  873stop_session_gc_thread.
  874
  875session_gc_loop :-
  876    thread_self(GcQueue),
  877    asserta(session_gc_queue(GcQueue)),
  878    session_gc_loop_.
  879
  880session_gc_loop_ :-
  881    session_setting(gc(active)),
  882    session_setting(granularity(TimeGranularity)),
  883    get_time(Now),
  884    At is Now+TimeGranularity,
  885    thread_self(GcQueue),
  886    repeat,
  887    (   thread_get_message(GcQueue, Message, [deadline(At)])
  888    ->  (   Message == done
  889        ->  !
  890        ;   fail
  891        )
  892    ;   !,
  893        http_gc_sessions(10),       % short time, so it runs
  894        session_gc_loop_
  895    ).
  896
  897
  898                 /*******************************
  899                 *             UTIL             *
  900                 *******************************/
 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.
  910http_session_cookie(Cookie) :-
  911    route(Route),
  912    !,
  913    random_4(R1,R2,R3,R4),
  914    format(atom(Cookie),
  915            '~`0t~16r~4|-~`0t~16r~9|-~`0t~16r~14|-~`0t~16r~19|.~w',
  916            [R1,R2,R3,R4,Route]).
  917http_session_cookie(Cookie) :-
  918    random_4(R1,R2,R3,R4),
  919    format(atom(Cookie),
  920            '~`0t~16r~4|-~`0t~16r~9|-~`0t~16r~14|-~`0t~16r~19|',
  921            [R1,R2,R3,R4]).
  922
  923:- thread_local
  924    route_cache/1.
 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.
  934route(Route) :-
  935    route_cache(Route),
  936    !,
  937    Route \== ''.
  938route(Route) :-
  939    route_no_cache(Route),
  940    assert(route_cache(Route)),
  941    Route \== ''.
  942
  943route_no_cache(Route) :-
  944    session_setting(route(Route)),
  945    !.
  946route_no_cache(Route) :-
  947    gethostname(Host),
  948    (   sub_atom(Host, Before, _, _, '.')
  949    ->  sub_atom(Host, 0, Before, _, Route)
  950    ;   Route = Host
  951    ).
  952
  953:- if(\+current_prolog_flag(windows, true)).
 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.
  962:- dynamic
  963    urandom_handle/1.  964
  965urandom(Handle) :-
  966    urandom_handle(Handle),
  967    !,
  968    Handle \== [].
  969urandom(Handle) :-
  970    catch(open('/dev/urandom', read, In, [type(binary)]), _, fail),
  971    !,
  972    assert(urandom_handle(In)),
  973    Handle = In.
  974urandom(_) :-
  975    assert(urandom_handle([])),
  976    fail.
  977
  978get_pair(In, Value) :-
  979    get_byte(In, B1),
  980    get_byte(In, B2),
  981    Value is B1<<8+B2.
  982:- endif.
 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.
  989:- if(current_predicate(urandom/1)).  990random_4(R1,R2,R3,R4) :-
  991    urandom(In),
  992    !,
  993    get_pair(In, R1),
  994    get_pair(In, R2),
  995    get_pair(In, R3),
  996    get_pair(In, R4).
  997:- endif.  998random_4(R1,R2,R3,R4) :-
  999    R1 is random(65536),
 1000    R2 is random(65536),
 1001    R3 is random(65536),
 1002    R4 is random(65536).
 hooked is semidet
 hook(+Goal)
These multifile predicates may be used to hook the data storage of this library. An example is implemented by library(http/http_redis_plugin), storing all session data in a redis database.