middleware.sessions

Protocol for session storage backends.

Return the current session dict.

RaisesLookupErrorif called outside a request with SessionMiddlewareactive.

Return the current session for templates — never raises.

Template-friendly counterpart toget_session(). Returns the live session dict whenSessionMiddlewareis active, or an empty read-only mapping otherwise (mirroringcurrent_user()'s never-raise contract, so a template rendered without a session does not blow up)::

{% if session().get("flash") %}
    <div class="flash">{{ session()["flash"] }}</div>
{% endif %}

Use the imperativeget_session() (which raises LookupErrorwithout SessionMiddleware) from handlers where the session is required.

Mutable request-local state shared with sync handler context copies.

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.

Session middleware configuration.

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

Resolve a (possibly"auto") SessionConfig.secureto a concrete bool.

An explicitboolis returned unchanged — the app author opted in or out deliberately."auto" returns True iff envis a secure-origin deployment environment ("production" / "staging") and False otherwise (notably local development), so a default-config app over HTTPS in production shipsSecuresession cookies without the author touching the field.

envis the sole posture signal: this resolver deliberately does NOT key offssl_certfileor request scheme, because local HTTPS dev sets ssl_certfile yet must keep secure=Falseto avoid logging dev users out.

Narrow a (resolved)secure to bool for with_cookie.

resolve_secure runs at freeze, so by request time secureis always a concretebool. This guard makes that invariant statically true at the with_cookie call site (which is typed bool) and fails safe to False— the non-secure / development posture — for the impossible case where resolution did not run, rather than emitting a stringly"auto".

Signed cookie session store. Session data stored in cookie.

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

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"),
)))