Module Simple_httpd.SessionSource

Module to handle session data

This module allows to manage sessions which are common to several clients and can survive a deconnection of the clients. This does not provide any form of authentication, but it is easy to use them to implement authentication.

It is recommended to create session only for authenticated connection: sessions require some memory (around 100 bytes) on the server, and if you have a session life time of one hour, an attaquant could exhaust available memory. Unauthenticated session with a short life comparable to the connection timeout could be acceseptable, as clients also uses some memory.

Sourcetype t

type for session

Sourcetype data
Sourcetype 'a key

session can hold several values of arbitrary type associated to a key The type of key is an extensible variant that you can extend to hold some data which resides in the server memory. These data will be lost if the server reboots.

Possible uses are

  • data that you do not want to be on the client but that do not need to persist server reboot, like a session private key.
  • Io.t sockets shared among multiple clients, for instance for a database connection
  • Mutex.t to protect the above.
Sourceval new_key : ?cleanup_delete:('a -> unit) -> ?cleanup_no_client:('a -> bool) -> ?save:(out_channel -> 'a -> unit) -> ?load:(in_channel -> 'a) -> string -> 'a key

new_key () creates a new key, to associate data.

The optional argument cleanup_delete is called when the session is deleted.

The optional argument cleanup_no_client is clalled when no more client are connected to that session or when the session is deleted. If it returns false, the data is deleted, otherwise, it is kept.

cleanup_delete is called if and only if cleanup_no_client returns true.

element of this type control the managment of cookies

value is { path = "/" ; base = "Session"; ; life = 3600.0 ; filter = fun _ -> None }

Sourceval start_check : ?create:bool -> ?check:(t -> bool) -> ?cookie_policy:cookie_policy -> ?nosession:exn -> ?error:(Response_code.t * Headers.t) -> 'a Request.t -> Cookies.t * t

Check or create a new session and add the session cookies to the cookie of the request. This can fail if

  • the session cookie is changed
  • the ip address changes
  • the function check returns false

If it fails, all cookies in the request are expired by the resposne sent.

  • parameter initial

    value for the session data (default: NoData)

  • parameter finalise

    function called on the session data when it is detroyed.

  • parameter create

    if false no session is created if there was none

  • parameter exception

    raised when the is no session. If no given, it results in an error (managed by the error parameter below).

  • parameter check

    some extra check, the session will be destroy if it fails.

  • parameter filter

    this parameter is called on all request cookies. If the filter return None, the cookie is expired. The default is to keep all cookies unchanged. The session cookies named "SESSION_KEY" and "SESSION_ADDR" are not passed to the filter.

  • parameter error

    status code and hadears to send in case of error. Can be used to redirect to a login or error page.

Sourceval filter : ?check:(t -> bool) -> ?cookie_policy:cookie_policy -> ?error:(Response_code.t * Headers.t) -> 'a Filter.t

Same as above as a filter. The cookies are added to the response.

Sourceval get_session : ?cookie_policy:cookie_policy -> 'a Request.t -> t option

get the client session is any. No check is performed on the session cookie

Sourceval get_session_data : t -> 'a key -> 'a option

get the session data associated to the given key from a session. raises Not_found if the key is not present

Sourceval set_session_data : t -> 'a key -> 'a -> unit

update or add the session data associated to the givent key

Sourceval remove_session_data : t -> 'a key -> unit

remove the session data associated to the givent key

Sourceval delete_session : ?cookie_policy:cookie_policy -> 'a Request.t -> Cookies.t

remove all server side and client side session data by expiring the session cookies.

Sourceval get_session_key : t -> string

For debugging