Expand description
Session management for Pavex.
§Why do we need sessions?
The HTTP protocol, at a first glance, is stateless: the client sends a request, the server parses its content, performs some processing and returns a response. The outcome is only influenced by the provided inputs (i.e. the request content) and whatever state the server queries while performing its processing.
Stateless systems are easier to reason about, but they are not quite as powerful as we need them to be - e.g. how do you authenticate a user? The user would be forced to authenticate for every single request. That is, for example, how ‘Basic’ Authentication works. While it may work for a machine user (i.e. an API client), it is impractical for a person—you do not want a login prompt on every single page you navigate to!
Sessions are the solution. They allow the server to attach state to a set of requests coming
from the same client. They are built on top of cookies: the server sets a
cookie in the HTTP response (Set-Cookie
header), the client (e.g. the browser) stores the
cookie and sends it back to the server whenever it issues new requests (using the Cookie
header).
§Anatomy of a session
A session cookie contains:
- A unique identifier for the session, called session ID.
- Application-specific data attached to the session, called client-side session state.
The session ID is used by the server to attach server-side state to the session. Server-side state is stored away from the client, inside a session storage backend—a SQL database (e.g. PostgreSQL), a cache (e.g. Redis), or any other persistent storage system.
§References
Further reading on sessions:
Modules§
- config
- Types related to
SessionConfig
. - state
- Types to manipulate either the client-side or the server-side session state.
- store
- Types and traits related to
SessionStore
.
Structs§
- Incoming
Session - The session information attached to the incoming request.
- Session
- The current HTTP session.
- Session
Config - Configure how sessions are managed.
- Session
Id - The identifier for a session.
- Session
Store - Where server-side session records are stored.
Functions§
- finalize_
session - A post-processing middleware to attach a session cookie to the outgoing response, if needed.