--- name: "Eliom_state.server" section: "3o" platform: "linux" package: "libeliom-ocaml-doc" version: "4.0.0-2" release: "Debian 8 (Jessie)" platforms: ["linux"] url: "https://new.carta.tech/Eliom_state.server" --- # Eliom\_state.server(3o) Storing server-side values for your applications or sessions. ## NAME Eliom\_state - Storing server-side values for your applications or sessions. ## Module Module Eliom\_state ## Documentation Module **Eliom\_state**\ : **sig end** Storing server-side values for your applications or sessions. **=== Please read the** **{% \<\\> %}** **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:\[\< \`Client\_process of Eliom\_common.scope\_hierarchy** **\| \`Request** **\| \`Session of Eliom\_common.scope\_hierarchy** **\| \`Session\_group of Eliom\_common.scope\_hierarchy \] -\>** **?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 **Eliom\_common.session** ). Closing a group of sessions will close all sessions in the group. By default will remove both secure and unsecure data and services, but if **~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:\[\< \`Client\_process of Eliom\_common.scope\_hierarchy** **\| \`Request** **\| \`Session of Eliom\_common.scope\_hierarchy** **\| \`Session\_group of Eliom\_common.scope\_hierarchy \] -\>** **?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:\[\< Eliom\_common.user\_scope \] -\> ?secure:bool -\> unit -\> unit** Remove all services registered for the given scope (the default beeing **\`Session** ). **===** **State status** **===** *type state\_status* =\ \| Alive\_state\ \| Empty\_state\ \| Expired\_state 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** . *val service\_state\_status* : **scope:\[\< Eliom\_common.user\_scope \] -\>** **?secure:bool -\> unit -\> state\_status** *val volatile\_data\_state\_status* : **scope:\[\< Eliom\_common.user\_scope \] -\>** **?secure:bool -\> unit -\> state\_status** *val persistent\_data\_state\_status* : **scope:\[\< Eliom\_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.** **If the parameter is not set,** **the expiration date will be when the browser is closed.** **Secure cookies are sent by the browser only with HTTPS (default: false). ===** *val set\_cookie* : **?cookie\_level:Eliom\_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:Eliom\_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:Eliom\_common.session\_scope -\> ?secure:bool -\> string -\> unit** sets the group to which belong the service session. If the optional **?set\_max** parameter is present, 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* : **?set\_max:int -\>** **?scope:Eliom\_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:Eliom\_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:Eliom\_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:Eliom\_common.session\_scope -\> ?secure:bool -\> string -\> unit** sets the group to which belong the volatile data session. If the optional **?set\_max** parameter is present, 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. *val unset\_volatile\_data\_session\_group* : **?set\_max:int -\>** **?scope:Eliom\_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:Eliom\_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:Eliom\_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:Eliom\_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, 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:Eliom\_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:Eliom\_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 following functions of this section set the maximum number of** **sessions in a session group, for the different kinds of session.** **This won't modify existing groups.** **That value will be used only as default value if you do not specify the** **optional parameter ?set\_max of function** **Eliom\_state.set\_volatile\_data\_session\_group.** **If there is no group, the number of sessions is limitated by sub network** **(which can be a problem for example if the server is behind a** **reverse proxy).** **It is highly recommended to use session groups!** **- Default number of sessions in a group: 5** **- Default number of sessions in a sub network: 1000000** **- Default IPV4 sub network: /16** **- Default IPV6 sub network: /56** **These default can be changed from configuration file and/or** **using these functions.** **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\_per\_subnet* : **?override\_configfile:bool -\> int -\> unit** Sets the maximum number of service sessions in a subnet (see above). *val set\_default\_max\_volatile\_data\_sessions\_per\_subnet* : **?override\_configfile:bool -\> int -\> unit** Sets the maximum number of volatile data sessions in a subnet (see above). *val set\_default\_max\_volatile\_sessions\_per\_subnet* : **?override\_configfile:bool -\> int -\> unit** Sets the maximum number of volatile sessions (data and service) in a subnet (see above). *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\_ipv4\_subnet\_mask* : **?override\_configfile:bool -\> int -\> unit** Sets the mask for subnet (IPV4). *val set\_ipv6\_subnet\_mask* : **?override\_configfile:bool -\> int -\> unit** Sets the mask for subnet (IPV6). *val set\_max\_service\_states\_for\_group\_or\_subnet* : **scope:Eliom\_common.user\_scope -\> ?secure:bool -\> int -\> unit** Sets the maximum number of service sessions in the current session group (or for the client sub network, if there is no group). *val set\_max\_volatile\_data\_states\_for\_group\_or\_subnet* : **scope:Eliom\_common.user\_scope -\> ?secure:bool -\> int -\> unit** Sets the maximum number of volatile data sessions in the current session group (or for the client sub network, if there is no group). *val set\_max\_volatile\_states\_for\_group\_or\_subnet* : **scope:Eliom\_common.user\_scope -\> ?secure:bool -\> int -\> unit** Sets the maximum number of volatile sessions (both data and service sessions) in the current group (or for the client sub network, if there is no group). **===** **Expiration of cookies and timeouts** **===** **===** **Cookie expiration** **===** **=== 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. Note: there is no way to set cookies** **for an infinite time on browsers.** **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:Eliom\_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:Eliom\_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:Eliom\_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** **Eliom\_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:\[\< Eliom\_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\_default\_global\_service\_state\_timeout* : **cookie\_level:\[\< Eliom\_common.cookie\_level \] -\>** **?override\_configfile:bool -\> float option -\> unit** *val set\_global\_service\_state\_timeout* : **cookie\_scope:\[\< Eliom\_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:\[\< Eliom\_common.cookie\_level \] -\>** **?override\_configfile:bool -\> float option -\> unit** *val set\_global\_volatile\_data\_state\_timeout* : **cookie\_scope:\[\< Eliom\_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:\[\< Eliom\_common.cookie\_level \] -\>** **?override\_configfile:bool -\> float option -\> unit** *val set\_global\_persistent\_data\_state\_timeout* : **cookie\_scope:\[\< Eliom\_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:\[\< Eliom\_common.cookie\_level \] -\>** **?override\_configfile:bool -\> float option -\> unit** *val get\_global\_service\_state\_timeout* : **?secure:bool -\>** **cookie\_scope:\[\< Eliom\_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:\[\< Eliom\_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:\[\< Eliom\_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:Eliom\_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:\[\< Eliom\_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:\[\< Eliom\_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:\[\< Eliom\_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:\[\< Eliom\_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:\[\< Eliom\_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:\[\< Eliom\_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:\[\< Eliom\_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:\[\< Eliom\_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** **Eliom\_common.Eliom\_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** **Eliom\_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:Eliom\_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:Eliom\_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:Eliom\_common.user\_scope -\> ?secure:bool -\> unit -\> unit Lwt.t** Remove all services registered for clients for the given scope. *module Ext :* **sig end**