Sessions and server side state


Different scopes for data and services

The server-side state of an application refers to server-side data that can be shared by all clients, or that can be specific to a limited scope, such as:

  • the site,
  • a session,
  • a group of sessions (for example all sessions of the same user),
  • a client-side process (when programming an Eliom app), or
  • the current request.

For a given scope, server-side state consists of:

  • services registered with this specific scope, and
  • data encapsulated within an Eliom reference created with this specific scope.
  • Bus, channels, etc. (actually implemented using services and Eliom references)

States disappear either when the associated scope is explicitely discarded, or after a timeout.

Scope and cookies

From a technical point of view, sessions and groups of sessions are implemented automatically within Eliom by asking the browser to send a session identifier in a cookie. Client-side processes also send an identifier with each request, using a kind of "client-side process-cookie".

It is possible to create different scopes of the same level if you want several states for the same application (advanced use). Each scope uses its own cookies, and you can discard data for a single scope.

Secure cookies

States can be secure or not. Secure means that the state data or service will be associated to a secure cookie, that is a cookie that is sent by the browser only if the protocol is HTTPS. Use secure states to access confidential data, that you do not want to send through HTTP.

Three kind of states

In the current implementation, because of a limitation in OCaml's serialization mechanism, there are three kinds of states (for each scope):

  • volatile data states,
  • volatile service states,
  • persistent data states.

Volatile states will not survive after relaunching the server. There is no persistent service state. Be very careful if you use both persistent state data and service state, as your session may become inconsistent. (Use service states only for volatile services, like coservices with timeouts.)

We hope to simplify this when OCaml's serialization mechanism evolves. In the meantime, be very careful where you store your data. To avoid shutting down the server, note that it is possible to ask the server to dynamically load new versions of your site (see command reload ).

Scopes, cookies and sessions


Eliom uses a notion of scopes to restrict the visibility of server-side data to a set of clients. Together with Eliom references, this is a very convenient way to implement a session mechanism for your Web site.

There are two categories of scopes:

Within the user scopes, Eliom distinguishes three scopes that differ with respect to how Eliom associates clients and data.

User scopes are organised in a hierarchy: client processes belong to a session, and sessions belong to a group of sessions.

Data and dynamic services with a user scope can be discarded explicitely or via a timeout. See sections Closing session and Timeouts and session duration for more information.

If you want to handle multiple sessions for the same site —~ e.g. several different data sessions that could be created and discarded independently — you can create new users scopes that will use different cookies. See section Hierarchies of scopes for more information.

Creating sessions and scopes

Automatic session creation

Eliom automatically creates a session — and sets the corresponding cookie on the client — when you first modify an Eliom reference of scope session, when you register a service with this scope or when you enter a session group.

By default, Eliom is using three cookies for sessions (and session groups):

  • one for session services,
  • one for volatile session data,
  • one for persistent session data.

For client side processes, it uses the same three kinds of client side process cookies.

Hierarchies of scopes and multiple sessions (advanced use)

If you want to handle multiple sessions for the same site that can be created and discarded independently, you can create a new hierarchy of users scope that will use different cookies, with the function Eliom_common.​create_scope_hierarchy.