Module `Eliom.State`

Storing server-side values for your applications or sessions.

Please read the Eliom manual before this page to learn how server side state works.

Managing the state of an application

Closing sessions, removing state data and services

val discard : 
  scope:[< Common.user_scope | Common.request_scope ] ->
  ?secure:bool ->
  unit ->
  unit Lwt.t

Delete server-side (volatile and persistent) state data and services for a session, a group of sessions, a client process or a request.

Use that function to close a session (using scope Common.default_session_scope).

Closing a group of sessions will close all sessions in the group.

By default will remove both secure and unsecure data and services, unless ~secure is present.

Warning: you may also want to unset some request-scoped Eliom references when discarding a state.

val discard_all_scopes : ?secure:bool -> unit -> unit Lwt.t

val discard_data : 
  ?persistent:bool ->
  scope:[< Common.user_scope | Common.request_scope ] ->
  ?secure:bool ->
  unit ->
  unit Lwt.t

Remove current state data.

If the optional parameter ?persistent is not present, will remove both volatile and persistent data. Otherwise only volatile or persistent data.

val discard_services : 
  scope:[< Common.user_scope ] ->
  ?secure:bool ->
  unit ->
  unit

Remove all services registered for the given scope (the default being `Session).

State status

The following functions return the current state of the state for a given scope:

Alive_state means that data has been recorded for this scope
Empty_state means that there is no data for this scope
Expired_state means that data for this scope has been removed because the timeout has been reached.

The default scope is `Session.

type state_status =

| Alive_state
| Empty_state
| Expired_state

val service_state_status : 
  scope:[< Common.user_scope ] ->
  ?secure:bool ->
  unit ->
  state_status

val volatile_data_state_status : 
  scope:[< Common.user_scope ] ->
  ?secure:bool ->
  unit ->
  state_status

val persistent_data_state_status : 
  scope:[< Common.user_scope ] ->
  ?secure:bool ->
  unit ->
  state_status Lwt.t

User cookies

If you want to store a client-side state, and ask the browser to send it back with each request, you can set manually your own cookies. Usual cookies correspond to scope `Session (that is, one browser). The browser send them with each request to the same Web site. But Eliom also implements client-side process cookies (scope `Client_process), that behave in the same way, but for one instance of the client-side Eliom program (if there is one).

Cookies can be limited to a subsite using the ?path optional parameter. This path is relative to the main path of your Web site. (It is not possible to set a cookie for a subsite larger than your current Web site).

Cookies can have an expiration date, specified (in seconds since the 1st of January 1970) in the optional parameter ?exp (see how to set default expiration dates below).

Secure cookies are sent by the browser only with HTTPS (default: false).

val set_cookie : 
  ?cookie_level:Common.cookie_level ->
  ?path:string list ->
  ?exp:float ->
  ?secure:bool ->
  name:string ->
  value:string ->
  unit ->
  unit

Ask the browser to record a cookie.

val unset_cookie : 
  ?cookie_level:Common.cookie_level ->
  ?path:string list ->
  name:string ->
  unit ->
  unit

Ask the browser to remove a cookie.

Session groups

If your Web site has users, it is a good idea to group together all the sessions for one user. Otherwise, you may want to group sessions according to another criterion.

Session groups may be used for example to limit the number of sessions one user can open at the same time, or to implement a "close all your sessions" feature. Usually, the group is the user name.

Putting a session in a group, removing a session from a group

val set_service_session_group : 
  ?set_max:int ->
  ?scope:Common.session_scope ->
  ?secure:bool ->
  string ->
  unit

sets the group to which belong the service session.

If the optional ?set_max parameter is present (a positive number), also sets the maximum number of sessions in the group. Default: follow current configuration for the group or default configuration if the group does not exist.

If ~secure is true, it will affect the secure session (secure cookies), otherwise (default), the unsecure one (behavior change in Eliom 4).

val unset_service_session_group : 
  ?scope:Common.session_scope ->
  ?secure:bool ->
  unit ->
  unit

Remove the session from its group. Will not close the session if it contains data.

val get_service_session_group : 
  ?scope:Common.session_scope ->
  ?secure:bool ->
  unit ->
  string option

returns the group to which belong the service session. If the session does not belong to any group, or if no session is opened, return None.

val get_service_session_group_size : 
  ?scope:Common.session_scope ->
  ?secure:bool ->
  unit ->
  int option

returns the number of sessions in the group. If he session does not belong to any group or if no session is opened, returns None

val set_volatile_data_session_group : 
  ?set_max:int ->
  ?scope:Common.session_scope ->
  ?secure:bool ->
  string ->
  unit

sets the group to which belong the volatile data session.

val unset_volatile_data_session_group : 
  ?scope:Common.session_scope ->
  ?secure:bool ->
  unit ->
  unit

Remove the session from its group. Will not close the session if it contains data.

val get_volatile_data_session_group : 
  ?scope:Common.session_scope ->
  ?secure:bool ->
  unit ->
  string option

returns the group to which belong the data session. If the session does not belong to any group, or if no session is opened, return None.

val get_volatile_data_session_group_size : 
  ?scope:Common.session_scope ->
  ?secure:bool ->
  unit ->
  int option

returns the number of sessions in the group. If he session does not belong to any group or if no session is opened, returns None

val set_persistent_data_session_group : 
  ?set_max:int option ->
  ?scope:Common.session_scope ->
  ?secure:bool ->
  string ->
  unit Lwt.t

sets the group to which belong the persistent session.

If the optional ?set_max parameter is present (a positive number), also sets the maximum number of sessions in the group. When ~set_max:None is present, the number of session is unlimited. Default: follow current configuration for the group or default configuration if the group does not exist.

val unset_persistent_data_session_group : 
  ?scope:Common.session_scope ->
  ?secure:bool ->
  unit ->
  unit Lwt.t

Remove the session from its group. Will not close the session if it contains data.

val get_persistent_data_session_group : 
  ?scope:Common.session_scope ->
  ?secure:bool ->
  unit ->
  string option Lwt.t

returns the group to which belong the persistent session. If the session does not belong to any group, or if no session is opened, return None.

Maximum group size

The functions of this section set the default maximum number of sessions in a session group, for the different kinds of session. When a group is full, opening a session in it closes the session of the group that has been used least recently. The value is not used for a group whose size has been set with the optional parameter ?set_max of set_volatile_data_session_group (and of the other functions that put a session in a group) or with set_max_volatile_states_in_parent. Otherwise, a volatile group keeps the value it was created with, while a persistent group follows the current value. The limit of the sessions without a group applies at once.

This limit bounds the memory that one user can take by opening sessions, and a user who floods the server with sessions only closes their own: put every session of a user in a group, usually named after the user. Sessions without a group are counted together, for the whole site, with a much larger limit: a flood of such sessions closes the sessions without a group used least recently, those of the other anonymous users included. The number of persistent sessions without a group is not limited. Each browser session may also hold tab sessions, with their own limit: the memory they take must be counted too.

Default number of sessions in a group: 50
Default number of tab sessions in a browser session: 100
Default number of sessions without a group in a site: 1000000

These defaults can be changed from the configuration file and/or using these functions. A maximum number must be positive: the functions raise Invalid_argument otherwise, and the configuration file is rejected.

If ~override_configfile is true (default (false), then the function will set the value even if it has been modified in the configuration file. It means that by default, these functions have no effect if there is a value in the configuration file. This gives the ability to override the values chosen by the module in the configuration file. Use ~override_configfile:true for example if your Eliom module wants to change the values afterwards (for example in the site configuration Web interface).

val set_default_max_service_sessions_per_group : 
  ?override_configfile:bool ->
  int ->
  unit

Sets the maximum number of service sessions in a session group (see above).

val set_default_max_volatile_data_sessions_per_group : 
  ?override_configfile:bool ->
  int ->
  unit

Sets the maximum number of volatile data sessions in a session group (see above).

val set_default_max_persistent_data_sessions_per_group : 
  ?override_configfile:bool ->
  int option ->
  unit

Sets the maximum number of persistent data sessions in a session group (see above). None means "no limitation".

val set_default_max_volatile_sessions_per_group : 
  ?override_configfile:bool ->
  int ->
  unit

Sets the maximum number of volatile sessions (data and service) in a session group (see above).

val set_default_max_service_sessions_without_group : 
  ?override_configfile:bool ->
  int ->
  unit

Sets the maximum number of service sessions without a group in the site (see above). It applies at once: beyond it, the sessions used least recently are closed.

raises Invalid_argument
if the number is not positive.

val set_default_max_volatile_data_sessions_without_group : 
  ?override_configfile:bool ->
  int ->
  unit

Like set_default_max_service_sessions_without_group, for volatile data sessions.

val set_default_max_volatile_sessions_without_group : 
  ?override_configfile:bool ->
  int ->
  unit

Like set_default_max_service_sessions_without_group, for both service and volatile data sessions.

val set_default_max_service_tab_sessions_per_group : 
  ?override_configfile:bool ->
  int ->
  unit

Sets the maximum number of tab service sessions in a session group (see above).

val set_default_max_volatile_data_tab_sessions_per_group : 
  ?override_configfile:bool ->
  int ->
  unit

Sets the maximum number of volatile data tab sessions in a session group (see above).

val set_default_max_persistent_data_tab_sessions_per_group : 
  ?override_configfile:bool ->
  int option ->
  unit

Sets the maximum number of persistent data tab sessions in a session group (see above).

val set_default_max_volatile_tab_sessions_per_group : 
  ?override_configfile:bool ->
  int ->
  unit

Sets the maximum number of volatile tab sessions (data and service) in a session group (see above).

val set_default_max_anonymous_services_per_site : 
  ?override_configfile:bool ->
  int ->
  unit

Sets the maximum number of anonymous coservices of the global table of the site created during requests (500000 by default). It applies at once: beyond it, the coservices used least recently are removed. The anonymous coservices created during the initialisation of the site are not counted.

raises Invalid_argument
if the number is not positive.

val set_max_service_states_in_parent : 
  scope:Common.user_scope ->
  ?secure:bool ->
  int ->
  unit

set_max_service_states_in_parent ~scope n sets to n the maximum number of service states of the level of scope in the state that contains the current one:

with a client process scope, the number of tab sessions in the current browser session;
with a session scope, the number of browser sessions in the current session group; if the session is not in a group, nothing is changed and a warning is logged (the limit of the sessions without a group of the site is set by set_default_max_service_sessions_without_group);
with a session group scope, the number of session groups of the site, whether the current session is in a group or not. This limit is shared by service and data states: a group with both counts twice.

If there are more, the ones used least recently are closed.

val set_max_volatile_data_states_in_parent : 
  scope:Common.user_scope ->
  ?secure:bool ->
  int ->
  unit

Like set_max_service_states_in_parent, for volatile data states.

val set_max_volatile_states_in_parent : 
  scope:Common.user_scope ->
  ?secure:bool ->
  int ->
  unit

Like set_max_service_states_in_parent, for both service and volatile data states.

Expiration of cookies and timeouts

The functions in this section ask the browser to set the state cookie expiration date, for the different kinds of session, in seconds, since the 1st of January 1970. None means the cookie will expire when the browser is closed. There is no way to set cookies for an infinite time on browsers. By default, Eliom sets default expiration date to 10 years after opening the session.

By default, it will affect regular browser cookies (sessions). But if you set ~cookie_level:`Client_process, it will only affect the client-side Eliom process (if there is one), which simulates some kind of "tab cookies".

val set_service_cookie_exp_date : 
  cookie_scope:Common.cookie_scope ->
  ?secure:bool ->
  float option ->
  unit

Sets the cookie expiration date for the current service state (see above).

val set_volatile_data_cookie_exp_date : 
  cookie_scope:Common.cookie_scope ->
  ?secure:bool ->
  float option ->
  unit

Sets the cookie expiration date for the current data state (see above).

val set_persistent_data_cookie_exp_date : 
  cookie_scope:Common.cookie_scope ->
  ?secure:bool ->
  float option ->
  unit Lwt.t

Sets the cookie expiration date for the persistent state (see above).

Global configuration of state timeouts

The following functions set the timeout for states, for the different kinds of states. States will be closed after this amount of time of inactivity from the user. None means no timeout.

The optional parameter ?recompute_expdates is false by default. If you set it to true, the expiration dates for all states in the table will be recomputed with the new timeout. That is, the difference between the new timeout and the old one will be added to their expiration dates (asynchronously, by another Lwt thread, as this can take a long time). States whose timeout has been set individually with functions like State.set_volatile_data_state_timeout won't be affected.

If ~scope_hierarchy is not present, it is the default for all scope hierarchies, and in that case recompute_expdates is ignored. ~scope_hierarchy:None means the default scope hierarchy.

If ~override_configfile is true (default (false), then the function will set the timeout even if it has been modified in the configuration file. It means that by default, these functions have no effect if there is a value in the configuration file. This gives the ability to override the values chosen by the module in the configuration file. Use ~override_configfile:true for example if your Eliom module wants to change the values afterwards (for example in the site configuration Web interface).

val set_global_volatile_state_timeout : 
  cookie_scope:[< Common.cookie_scope ] ->
  ?secure:bool ->
  ?recompute_expdates:bool ->
  ?override_configfile:bool ->
  float option ->
  unit

Sets the (server side) timeout for volatile (= "in memory") sessions (both service session and volatile data session).

val set_global_service_state_timeout : 
  cookie_scope:[< Common.cookie_scope ] ->
  ?secure:bool ->
  ?recompute_expdates:bool ->
  ?override_configfile:bool ->
  float option ->
  unit

Sets the (server side) timeout for service states.

val set_default_global_service_state_timeout : 
  cookie_level:[< Common.cookie_level ] ->
  ?override_configfile:bool ->
  float option ->
  unit

val set_global_volatile_data_state_timeout : 
  cookie_scope:[< Common.cookie_scope ] ->
  ?secure:bool ->
  ?recompute_expdates:bool ->
  ?override_configfile:bool ->
  float option ->
  unit

Sets the (server side) timeout for volatile (= "in memory") data states.

val set_default_global_volatile_data_state_timeout : 
  cookie_level:[< Common.cookie_level ] ->
  ?override_configfile:bool ->
  float option ->
  unit

val set_global_persistent_data_state_timeout : 
  cookie_scope:[< Common.cookie_scope ] ->
  ?secure:bool ->
  ?recompute_expdates:bool ->
  ?override_configfile:bool ->
  float option ->
  unit

Sets the (server side) timeout for persistent states.

val set_default_global_persistent_data_state_timeout : 
  cookie_level:[< Common.cookie_level ] ->
  ?override_configfile:bool ->
  float option ->
  unit

val get_global_service_state_timeout : 
  ?secure:bool ->
  cookie_scope:[< Common.cookie_scope ] ->
  unit ->
  float option

Returns the (server side) timeout for service states.

val get_global_volatile_data_state_timeout : 
  ?secure:bool ->
  cookie_scope:[< Common.cookie_scope ] ->
  unit ->
  float option

Returns the (server side) timeout for "volatile data" states.

val get_global_persistent_data_state_timeout : 
  ?secure:bool ->
  cookie_scope:[< Common.cookie_scope ] ->
  unit ->
  float option

Returns the (server side) timeout for persistent states.

Personalizing timeouts for current state

val set_service_state_timeout : 
  cookie_scope:Common.cookie_scope ->
  ?secure:bool ->
  float option ->
  unit

sets the timeout for service state (server side) for current user, in seconds. None = no timeout

val unset_service_state_timeout : 
  cookie_scope:[< Common.cookie_scope ] ->
  ?secure:bool ->
  unit ->
  unit

remove the service state timeout for current user (and turn back to the default).

val get_service_state_timeout : 
  cookie_scope:[< Common.cookie_scope ] ->
  ?secure:bool ->
  unit ->
  float option

returns the timeout for current service state. None = no timeout

val set_volatile_data_state_timeout : 
  cookie_scope:[< Common.cookie_scope ] ->
  ?secure:bool ->
  float option ->
  unit

sets the (server side) timeout for volatile data state for current user, in seconds. None = no timeout

val unset_volatile_data_state_timeout : 
  cookie_scope:[< Common.cookie_scope ] ->
  ?secure:bool ->
  unit ->
  unit

remove the "volatile data" state timeout for current user (and turn back to the default).

val get_volatile_data_state_timeout : 
  cookie_scope:[< Common.cookie_scope ] ->
  ?secure:bool ->
  unit ->
  float option

returns the timeout for current volatile data state. None = no timeout

val set_persistent_data_state_timeout : 
  cookie_scope:[< Common.cookie_scope ] ->
  ?secure:bool ->
  float option ->
  unit Lwt.t

sets the (server side) timeout for persistent state for current user, in seconds. None = no timeout

val unset_persistent_data_state_timeout : 
  cookie_scope:[< Common.cookie_scope ] ->
  ?secure:bool ->
  unit ->
  unit Lwt.t

remove the persistent state timeout for current user (and turn back to the default).

val get_persistent_data_state_timeout : 
  cookie_scope:[< Common.cookie_scope ] ->
  ?secure:bool ->
  unit ->
  float option Lwt.t

returns the persistent state timeout for current user. None = no timeout

Administrating server side state

Warning: Most these functions must be called when the site information is available, that is, either during a request or during the initialisation phase of the site. Otherwise, it will raise the exception Common.Site_information_not_available. If you are using static linking, you must delay the call to this function until the configuration file is read, using Service.register_eliom_module. Otherwise you will also get this exception.

type 'a volatile_table

The type of (volatile) state data tables.

type 'a persistent_table

The type of persistent state data tables.

val discard_everything : unit -> unit Lwt.t

Discard all services and persistent and volatile data for every scopes.

val discard_all : scope:Common.user_scope -> ?secure:bool -> unit -> unit Lwt.t

Discard all services and persistent and volatile data for one scope.

val discard_all_data : 
  ?persistent:bool ->
  scope:Common.user_scope ->
  ?secure:bool ->
  unit ->
  unit Lwt.t

Discard server side data for all clients, for the given scope.

If the optional parameter ?persistent is not present, both the persistent and volatile data will be removed.

val discard_all_services : 
  scope:Common.user_scope ->
  ?secure:bool ->
  unit ->
  unit Lwt.t

Remove all services registered for clients for the given scope.

module Ext : sig ... end

Managing the state of an application

Closing sessions, removing state data and services

State status

User cookies

Session groups

Putting a session in a group, removing a session from a group

Maximum group size

Expiration of cookies and timeouts

Cookie expiration

Global configuration of state timeouts

Personalizing timeouts for current state

Administrating server side state