woggioni
c8c8c6052a
- Move src/kaya/session_memcache/ → src/kaya/session/memcache/ - Add pkgutil.extend_path to kaya.session for subpackage namespace support - Update pyproject.toml version_file path - Update all import references (tests, READMEs, root README)
kaya-session
Session management for the Kaya web framework.
Provides server-side, identity-agnostic HTTP sessions via a session cookie. The
session data is accessible from request handlers as ctx.session.
Usage
from kaya.core import KayaApp, HttpContext
from kaya.session import SessionMixin, InMemorySessionStore
session = SessionMixin(InMemorySessionStore())
app = KayaApp(mixins=[session])
@app.GET('/')
async def home(ctx: HttpContext):
n = ctx.session.get('visits', 0) + 1
ctx.session['visits'] = n
await ctx.send_str(200, f'visits: {n}')
Sessions are created lazily: a cookie is only set when the handler modifies the session.
SessionMixin is a KayaMixin, so the app stays a KayaApp and both ASGI and
RSGI keep working.
WebSocket sessions
The same session is available in websocket handlers as ws.session:
@app.websocket('/ws/visits')
async def ws_visits(ws: WebSocket):
await ws.accept()
visits = ws.session.get('visits', 0)
await ws.send_text(f'visits: {visits}')
The session is loaded from the cookie when the connection is opened and persisted when the connection closes, if it was modified.
Important: although the ASGI spec allows custom headers on the WebSocket
handshake response (websocket.accept headers, spec 2.1+), most ASGI servers
in practice — including Granian and Daphne — do not forward them into
the HTTP 101 response. RSGI websocket handshakes cannot carry response headers
at all. Therefore, in real deployments a session cookie can only be set or
refreshed by an HTTP response. Use an HTTP endpoint to establish or update the
session before opening the WebSocket, and read the existing session in the
WebSocket handler.
Session expiry
The cookie sent to the browser has a Max-Age (default 14 days), but that is
only a client-side hint. The real boundary is the store's server-side TTL,
which the mixin keeps in sync with the cookie Max-Age.
For InMemorySessionStore, a session expires if it is idle for longer than
max_age. Active sessions have their expiry slid forward on every access, so
a user that keeps visiting stays logged in. If the client ignores the cookie's
Max-Age and replays an old cookie value, the store rejects the expired
session and creates a fresh empty one.
Set max_age=None to disable server-side expiry (and the Max-Age cookie
attribute) entirely.
Features
Session: dict-like session object with modification trackingSessionStore: abstract store interfaceInMemorySessionStore: simple in-memory store for development/single-processSessionMixin: composable Kaya mixin managing session cookies and persistence- Session ID regeneration (
session.regenerate_id()) and invalidation (session.invalidate()) for authentication layers - WebSocket support: the session is exposed as
ws.sessionin websocket handlers, loaded at connect time and persisted on close
Notes
InMemorySessionStoredoes not survive process restarts and is not shared across processes. Production deployments should use a store backed by a shared storage system (planned).