Add kaya-session package for server-side HTTP session management

2026-07-18 00:30:41 +00:00
parent 4ce95d8365
commit 705771b681
16 changed files with 756 additions and 5 deletions
@@ -0,0 +1,42 @@
+# 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
+
+```python
+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.
+
+## 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).