class litestar.middleware.session.server_side.ServerSideSessionBackend#

Bases: BaseSessionBackend[ServerSideSessionConfig]

Base class for server-side backends.

Implements BaseSessionBackend and defines and interface which subclasses can implement to facilitate the storage of session data.

__init__(config: ServerSideSessionConfig) None#

Initialize ServerSideSessionBackend


config – A subclass of ServerSideSessionConfig

async get(session_id: str, store: Store) bytes | None#

Retrieve data associated with session_id.

  • session_id – The session-ID

  • store – Store to retrieve the session data from


The session data, if existing, otherwise None.

async set(session_id: str, data: bytes, store: Store) None#

Store data under the session_id for later retrieval.

If there is already data associated with session_id, replace it with data and reset its expiry time

  • session_id – The session-ID

  • data – Serialized session data

  • store – Store to save the session data in



async delete(session_id: str, store: Store) None#

Delete the data associated with session_id. Fails silently if no such session-ID exists.

  • session_id – The session-ID

  • store – Store to delete the session data from



get_session_id(connection: ASGIConnection) str#

Try to fetch session id from the connection. If one does not exist, generate one.

If a session ID already exists in the cookies, it is returned. If there is no ID in the cookies but one in the connection state, then the session exists but has not yet been returned to the user. Otherwise, a new session must be created.


connection – Originating ASGIConnection containing the scope


Session id str or None if the concept of a session id does not apply.

generate_session_id() str#

Generate a new session-ID, with n=:attr:session_id_bytes <ServerSideSessionConfig.session_id_bytes> random bytes.


A session-ID

async store_in_message(scope_session: ScopeSession, message: Message, connection: ASGIConnection) None#

Store the necessary information in the outgoing Message by setting a cookie containing the session-ID.

If the session is empty, a null-cookie will be set. Otherwise, the serialised data will be stored using set, under the current session-id. If no session-ID exists, a new ID will be generated using generate_session_id.

  • scope_session – Current session to store

  • message – Outgoing send-message

  • connection – Originating ASGIConnection containing the scope



async load_from_connection(connection: ASGIConnection) dict[str, Any]#

Load session data from a connection and return it as a dictionary to be used in the current application scope.

The session-ID will be gathered from a cookie with the key set in BaseBackendConfig.key. If a cookie is found, its value will be used as the session-ID and data associated with this ID will be loaded using get. If no cookie was found or no data was loaded from the store, this will return an empty dictionary.


connection – An ASGIConnection instance


The current session data

class litestar.middleware.session.server_side.ServerSideSessionConfig#

Bases: BaseBackendConfig[ServerSideSessionBackend]

Base configuration for server side backends.

session_id_bytes: int = 32#

Number of bytes used to generate a random session-ID.

renew_on_access: bool = False#

Renew expiry times of sessions when they’re being accessed

key: str = 'session'#

Key to use for the cookie inside the header, e.g. session=<data> where session is the cookie key and <data> is the session data.


  • If a session cookie exceeds 4KB in size it is split. In this case the key will be of the format session-{segment number}.

max_age: int = 1209600#

Maximal age of the cookie before its invalidated.

path: str = '/'#

Path fragment that must exist in the request url for the cookie to be valid.

Defaults to '/'.

domain: str | None = None#

Domain for which the cookie is valid.

__init__(session_id_bytes: int = 32, renew_on_access: bool = False, key: str = 'session', max_age: int = 1209600, scopes: set[typing.Literal[<ScopeType.HTTP: 'http'>, <ScopeType.WEBSOCKET: 'websocket'>]] = <factory>, path: str = '/', domain: str | None = None, secure: bool = False, httponly: bool = True, samesite: ~typing.Literal['lax', 'strict', 'none'] = 'lax', exclude: str | list[str] | None = None, exclude_opt_key: str = 'skip_session', store: str = 'sessions') None#
secure: bool = False#

Https is required for the cookie.

httponly: bool = True#

Forbids javascript to access the cookie via ‘Document.cookie’.

samesite: Literal['lax', 'strict', 'none'] = 'lax'#

Controls whether or not a cookie is sent with cross-site requests. Defaults to lax.

exclude: str | list[str] | None = None#

A pattern or list of patterns to skip in the session middleware.

exclude_opt_key: str = 'skip_session'#

An identifier to use on routes to disable the session middleware for a particular route.

store: str = 'sessions'#

Name of the Store to use

get_store_from_app(app: Litestar) Store#

Get the store defined in store from an Litestar instance