Module

middleware.sessions

Session middleware — signed cookie and Redis-backed sessions.

Session data is stored via a pluggableSessionStore. Default is CookieSessionStore(signed cookie with itsdangerous). For horizontal scaling, useRedisSessionStore.

The session object is stored in a ContextVar, accessible via get_session()from any handler or middleware.

itsdangerous is required for cookie store. redisis required for RedisSessionStore (pip install chirp[redis]).

5Classes2Functions

Classes

SessionStore 2 ▼
Protocol for session storage backends.

Protocol for session storage backends.

Methods

load 1 dict[str, Any] ▼
Load session data from the store. Returns empty dict if none.
async
async def load(self, request: Request) -> dict[str, Any]
Parameters
Name Type Description
request —
Returns
dict[str, Any]
save 3 AnyResponse ▼
Persist session and return response with cookie/headers. When regenerate_old_i…
async
async def save(self, response: AnyResponse, session: dict[str, Any], *, regenerate_old_id: str | None = None) -> AnyResponse

Persist session and return response with cookie/headers.

When regenerate_old_id is set, the store should create a new session and delete the old one (for Redis).

Parameters
Name Type Description
response —
session —
regenerate_old_id — Default:None
Returns
AnyResponse
SessionConfig 13 ▼
Session middleware configuration. ``secret_key`` is required for cookie signing. When using ``Redi…

Session middleware configuration.

secret_keyis required for cookie signing. When using RedisSessionStore, the cookie stores only the session ID.

Attributes

Name Type Description
secret_key str —
cookie_name str —
max_age int —
path str —
domain str | None —
secure bool —
httponly bool —
samesite str —
idle_timeout_seconds int | None —
absolute_timeout_seconds int | None —
created_at_key str —
last_seen_at_key str —
store SessionStore | None —
CookieSessionStore 3 ▼
Signed cookie session store. Session data stored in cookie.

Signed cookie session store. Session data stored in cookie.

Methods

load 1 dict[str, Any] ▼
async
async def load(self, request: Request) -> dict[str, Any]
Parameters
Name Type Description
request —
Returns
dict[str, Any]
save 3 AnyResponse ▼
async
async def save(self, response: AnyResponse, session: dict[str, Any], *, regenerate_old_id: str | None = None) -> AnyResponse
Parameters
Name Type Description
response —
session —
regenerate_old_id — Default:None
Returns
AnyResponse
Internal Methods 1 ▼
__init__ 1 ▼
def __init__(self, config: SessionConfig) -> None
Parameters
Name Type Description
config —
RedisSessionStore 3 ▼
Redis-backed session store. Cookie stores session ID only.

Redis-backed session store. Cookie stores session ID only.

Methods

load 1 dict[str, Any] ▼
async
async def load(self, request: Request) -> dict[str, Any]
Parameters
Name Type Description
request —
Returns
dict[str, Any]
save 3 AnyResponse ▼
async
async def save(self, response: AnyResponse, session: dict[str, Any], *, regenerate_old_id: str | None = None) -> AnyResponse
Parameters
Name Type Description
response —
session —
regenerate_old_id — Default:None
Returns
AnyResponse
Internal Methods 1 ▼
__init__ 3 ▼
def __init__(self, config: SessionConfig, redis_url: str, key_prefix: str = 'chirp:session:') -> None
Parameters
Name Type Description
config —
redis_url —
key_prefix — Default:'chirp:session:'
SessionMiddleware 2 ▼
Session middleware with pluggable store (cookie or Redis). Uses ``CookieSessionStore`` by default.…

Session middleware with pluggable store (cookie or Redis).

UsesCookieSessionStoreby default. For horizontal scaling, passRedisSessionStore via SessionConfig.store.

Usage::

from chirp.middleware.sessions import SessionConfig, SessionMiddleware

app.add_middleware(SessionMiddleware(SessionConfig(
    secret_key="my-secret-key",
)))

# Redis-backed (pip install chirp[redis]):
from chirp.middleware.sessions import RedisSessionStore, SessionConfig

app.add_middleware(SessionMiddleware(SessionConfig(
    secret_key="my-secret-key",
    store=RedisSessionStore(SessionConfig(secret_key="x"), "redis://localhost"),
)))

Methods

Internal Methods 2 ▼
__init__ 1 ▼
def __init__(self, config: SessionConfig) -> None
Parameters
Name Type Description
config —
__call__ 2 AnyResponse ▼
Load session, dispatch, then save session to response.
async
async def __call__(self, request: Request, next: Next) -> AnyResponse
Parameters
Name Type Description
request —
next —
Returns
AnyResponse

Functions

get_session 0 dict[str, Any] ▼
Return the current session dict. Raises ``LookupError`` if called outside a re…
def get_session() -> dict[str, Any]

Return the current session dict.

RaisesLookupErrorif called outside a request with SessionMiddlewareactive.

Returns
dict[str, Any]
regenerate_session 0 dict[str, Any] ▼
Clear the session and return a fresh empty dict. Prevents session fixation by …
def regenerate_session() -> dict[str, Any]

Clear the session and return a fresh empty dict.

Prevents session fixation by discarding all data from the previous session. For cookie store, re-signs empty dict. For Redis store, creates new session ID and deletes old.

Called automatically bylogin() and logout(). Can also be called directly when you need to rotate the session::

from chirp.middleware.sessions import regenerate_session

regenerate_session()  # old data gone, new cookie on response

RaisesLookupErrorif called outside a request with SessionMiddlewareactive.

Returns
dict[str, Any]