class litestar.middleware.session.client_side.ClientSideSessionBackend#

Bases: BaseSessionBackend[CookieBackendConfig]

Cookie backend for SessionMiddleware.

__init__(config: CookieBackendConfig) None#

Initialize ClientSideSessionBackend.


config – SessionCookieConfig instance.

dump_data(data: Any, scope: Scope | None = None) list[bytes]#

Given serializable data, including pydantic models and numpy types, dump it into a bytes string, encrypt, encode and split it into chunks of the desirable size.

  • data – Data to serialize, encrypt, encode and chunk.

  • scope – The ASGI connection scope.


  • The returned list is composed of a chunks of a single base64 encoded string that is encrypted using AES-CGM.


List of encoded bytes string of a maximum length equal to the CHUNK_SIZE constant.

load_data(data: list[bytes]) dict[str, Any]#

Given a list of strings, decodes them into the session object.


data – A list of strings derived from the request’s session cookie(s).


A deserialized session value.

Return a list of cookie-keys from the connection if they match the session-cookie pattern.


connection – An ASGIConnection instance


A list of session-cookie keys

Return a set of cookie-keys from the connection if they match the session-cookie pattern.

New in version 2.8.3.


connection – An ASGIConnection instance


A set of session-cookie keys

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

Store data from scope_session in Message in the form of cookies. If the contents of scope_session are too large to fit a single cookie, it will be split across several cookies, following the naming scheme of <cookie key>-<n>. If the session is empty or shrinks, cookies will be cleared by setting their value to "null"

  • 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’s session-cookies and return it as a dictionary.


connection – Originating ASGIConnection


The session data

get_session_id(connection: ASGIConnection) str | None#

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


connection – Originating ASGIConnection containing the scope


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

class litestar.middleware.session.client_side.CookieBackendConfig#

Bases: BaseBackendConfig[ClientSideSessionBackend]

Configuration for [SessionMiddleware] middleware.

secret: bytes#

A secret key to use for generating an encryption key.

Must have a length of 16 (128 bits), 24 (192 bits) or 32 (256 bits) characters.

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__(secret: bytes, 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') 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.