Module `Webs_kit.Session`

Sessions.

Sessions maintain state across request/response cycles. This module provides a basic infrastructure to abstract the mecanism handling sessions.

One built-in mecanism is ofered for client-side sessions via Authenticated_cookies.

TODO.

Error paths. In particular on load.
Expiry.
Provide a reasonably efficient and convenient (Tpf ?) binary solution for state codec.
Authenticated cookie, fix the None path. Use expiration, option to refresh on each request. Understand caching issues. Global salty invalidation ?
Add session handler init hooks and expiry cleanup
Should state be as a heterogenous dict with serialisation ? That makes state composable, but implicitely composable. We should rather go for explicit compositionality and state design.

Session state

type 'a state: The type for session state of type 'a. Values of this type describe how to test 'a for equality and codec it with bytes.

val state : eq:('a -> 'a -> bool) -> encode:('a -> string) -> decode:(string -> ('a, string) Stdlib.result) -> unit -> 'a state: state ~eq ~encode ~decode () tests state for equality with eq, encodes it with encode and decodes it with decode.

module State : sig ... end: Built-in state values. TODO. Call Tpf to the rescue.

type 'a handler: The type for session handler of state of type 'a. Values of this type are in charge of loading and saving the state.

val handler : load:('a state -> Webs.Req.t -> 'a option) -> save:('a state -> 'a option -> Webs.Resp.t -> Webs.Resp.t) -> unit -> 'a handler

handler ~load ~save () is a session handler using load to setup the session state and save to save before responding.

TODO do we want to give the original Req.t to save aswell ?

val setup : 'a state -> 'a handler -> (Webs.Req.t -> 'a option -> 'a option * Webs.Resp.t) -> Webs.service: setup st handler service handles loading and saving state st with handler handler for service service which gets current state as argument and should tuple the new state with the request.

val setup' : 'a state -> 'a handler -> (Webs.Req.t -> 'a option -> 'a option * (Webs.Resp.t, Webs.Resp.t) Stdlib.result) -> Webs.Req.t -> (Webs.Resp.t, Webs.Resp.t) Stdlib.result: TODO. Add that for now until we settle on something.

val with_authenticated_cookie : ?⁠atts:Webs.Http.Cookie.atts -> ?⁠name:string -> ?⁠key:Authenticatable.key -> unit -> 'a handler: with_authenticated_cookie ~key stores state on the client with an Authenticated_cookie that can be authenticated with the private key key (defaults to Authenticatable.random_key). name is the name of the cookie, it defaults to "webss". atts are the attributes of the cookie, they default to Webs.Http.Cookie.atts_default.