kaya/packages/kaya-session/README.md

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 SessionMiddleware, InMemorySessionStore

app = KayaApp()
session_app = SessionMiddleware(app, InMemorySessionStore())

@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.

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 middleware 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 tracking
• SessionStore: abstract store interface
• InMemorySessionStore: simple in-memory store for development/single-process
• SessionMiddleware: ASGI middleware managing session cookies and persistence
• Session ID regeneration (session.regenerate_id()) and invalidation (session.invalidate()) for future authentication layers

Notes

• This release supports HTTP requests only; WebSocket and RSGI propagation is planned for future releases.
• InMemorySessionStore does not survive process restarts and is not shared across processes. Production deployments should use a store backed by a shared storage system (planned).