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

## 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).