diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..cbaf2e2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,439 @@ +# Mizan — Technical Reference + +## What Mizan Is + +Mizan is an Application Framework Interface (AFI). One decorator on a server function. Typed client generated. Invalidation automatic. Caching protocol-driven. SSR via subprocess. + +Django + React ships first. The protocol is language-agnostic (proven by mizan-ts). + +--- + +## Package Layout + +``` +packages/ + mizan-django/ Python backend adapter (323+ tests) + mizan-react/ React frontend adapter (33 tests) + mizan-ts/ TypeScript backend adapter (22+ tests, proves AFI) + mizan-ssr/ Bun SSR worker subprocess +``` + +--- + +## The Three Protocols + +### 1. RPC Protocol (Anti-REST) + +No resources. No CRUD. Functions in, results out. + +**Context fetch (reads):** +``` +GET /api/mizan/ctx//?param1=val1¶m2=val2 + +200 OK +Cache-Control: no-store +Content-Type: application/json + +{ + "user_profile": {"name": "Ryth", "email": "ryth@example.com"}, + "user_orders": [{"id": 1, "total": 100}] +} +``` + +All functions sharing a context name are bundled into one response. Keys are function names. Values are return values. + +**Mutation call (writes):** +``` +POST /api/mizan/call/ +Content-Type: application/json + +{"fn": "update_profile", "args": {"user_id": 5, "name": "Ryth"}} + +200 OK +Cache-Control: no-store +X-Mizan-Invalidate: user;user_id=5 + +{ + "result": {"ok": true}, + "invalidate": [{"context": "user", "params": {"user_id": 5}}] +} +``` + +### 2. Invalidation-on-Mutation Protocol + +Two transports for the same signal. Both are first-class. + +**Transport 1 — JSON body** (for RPC/SPA clients): +```json +{"result": {...}, "invalidate": ["user"]} +{"result": {...}, "invalidate": [{"context": "user", "params": {"user_id": 5}}]} +``` + +**Transport 2 — HTTP header** (for Edge, htmx, view-path functions): +``` +X-Mizan-Invalidate: user +X-Mizan-Invalidate: user;user_id=5 +X-Mizan-Invalidate: user;user_id=5, notifications +``` + +Format: comma-separated contexts, semicolon-separated URL-encoded params per context. + +**Three-tier auto-scoping** (no developer annotation needed): +1. **Argument name matching:** mutation has `user_id` param, context has `user_id` param → scoped automatically +2. **Auth inference:** Edge-side concern (reads JWT/MWT to extract user identity) +3. **Broad fallback:** invalidate all instances of the context + +**Return-type branching** determines which transport: +- Function returns data (dict, BaseModel) → RPC path → JSON body + header +- Function returns HttpResponse (redirect, HTML) → View path → header only + +### 3. Frontend-Agnostic Rendering (SSR + PSR) + +**SSR** — Django template backend integration. `render(request, 'ProfilePage', props)` calls a persistent Bun subprocess that runs `renderToString`. + +**PSR** (Preemptive Static Rendering) — pages re-rendered on mutation, not on request. Edge caches the result. Controlled by the manifest's `render_strategy` field. + +**The Bun worker protocol** — JSON-RPC over stdin/stdout: +``` +→ {"id": 1, "method": "render", "params": {"component": "ProfilePage", "props": {"userId": 5}}} +← {"id": 1, "html": "
...
"} +``` + +Worker stays alive across requests. Django's `SSRBridge` manages the subprocess lifecycle with thread-safe request correlation via message IDs. + +--- + +## The @client Decorator — Full API + +```python +from mizan import client, ReactContext, GlobalContext + +UserContext = ReactContext('user') +``` + +### Parameters + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `context` | `ReactContext \| str \| False` | `False` | Named context for grouping. `False` = standalone function. | +| `affects` | `ReactContext \| str \| list` | `None` | What this mutation invalidates. Mutually exclusive with `context`. | +| `private` | `bool` | `False` | Not client-callable. No RPC endpoint. No codegen. Still in invalidation graph. | +| `route` | `str \| None` | `None` | Mizan-owned URL pattern for view-path functions. | +| `methods` | `list[str] \| None` | `None` | HTTP methods for route. Default: `['GET']` for context, `['POST']` for mutation. | +| `auth` | `bool \| str \| callable \| None` | `None` | Auth requirement: `True`, `'staff'`, `'superuser'`, or `callable(request) -> bool`. | +| `websocket` | `bool` | `False` | Enable WebSocket RPC transport. | +| `rev` | `int` | `0` | Cache revision. Increment to bust cached entries on deploy. | +| `cache` | `int \| False` | (default) | Cache TTL hint. `False` = never cache. Integer = TTL seconds. | + +### Usage Patterns + +```python +# Global context — auto-mounted at root, SSR-hydrated +@client(context=GlobalContext) +def current_user(request) -> UserShape: + return UserShape.query(lambda qs: qs.filter(pk=request.user.pk))[0] + +# Named context — bundled GET, generates typed hooks +@client(context=UserContext) +def user_profile(request, user_id: int) -> UserShape: + return UserShape.query(lambda qs: qs.filter(pk=user_id))[0] + +@client(context=UserContext) +def user_orders(request, user_id: int) -> list[OrderShape]: + return OrderShape.query(lambda qs: qs.filter(user_id=user_id)) + +# Mutation — auto-scoped invalidation (user_id matches) +@client(affects=UserContext) +def update_profile(request, user_id: int, name: str) -> dict: + request.user.name = name + request.user.save() + return {"ok": True} + +# Function-level affects — only user_profile refetches +@client(affects='user_profile') +def update_name(request, user_id: int, name: str) -> dict: + ... + +# View-path context — registered in invalidation graph, no codegen +@client(context=UserContext, route='/profile//') +def profile_page(request, user_id: int) -> HttpResponse: + return render(request, 'profile.html', {...}) + +# View-path mutation — invalidation via header on the redirect +@client(affects=UserContext, route='/profile//update/', methods=['POST']) +def update_profile_view(request, user_id: int) -> HttpResponse: + form = ProfileForm(request.POST) + if form.is_valid(): + form.save() + return redirect(f'/profile/{user_id}/') + +# Private webhook — not client-callable, emits invalidation +@client(affects='subscription', private=True, route='/webhooks/stripe/', methods=['POST']) +def stripe_webhook(request) -> HttpResponse: + event = json.loads(request.body) + process_stripe_event(event) + return HttpResponse(status=200) + +# Auth guards +@client(auth=True) +def secret(request) -> dict: ... + +@client(auth='staff') +def admin_action(request) -> dict: ... + +@client(auth=lambda req: req.user.email.endswith('@company.com')) +def internal_tool(request) -> dict: ... +``` + +### _meta Dict Structure + +After decoration, the function class has `_meta` with these possible keys: + +```python +{ + "context": "user", # context name string (if context=) + "affects": [ # normalized affects targets (if affects=) + {"type": "context", "name": "user"}, + {"type": "function", "name": "user_profile", "context": "user"}, + ], + "private": True, # if private=True + "route": "/webhooks/stripe/", # if route= + "methods": ["POST"], # if route= (defaults applied) + "view_path": True, # if return type is HttpResponse + "websocket": True, # if websocket=True + "auth": "required", # "required" | "staff" | "superuser" | callable + "rev": 3, # if rev= + "cache": 60, # if cache= + "form": True, # if form function + "form_name": "contact", # form name + "form_role": "schema", # "schema" | "validate" | "submit" +} +``` + +--- + +## Cache System + +### Required Settings + +```python +# settings.py +MIZAN_CACHE_SECRET = "your-32-byte-hmac-signing-key" # Required for cache +MIZAN_CACHE_REDIS_URL = "redis://localhost:6379/0" # Required for cache +``` + +Both must be set. If either is missing, caching is disabled with a warning. + +### HMAC Key Derivation + +Cache keys are derived from HMAC-SHA256 over a JSON-canonical form: + +```python +derive_cache_key(secret, context, params, user_id=None, rev=0) -> str +``` + +**Canonical form** (the HMAC message): +```json +{"c":"user","p":{"user_id":"5"},"r":0} +``` +With optional `"u":"5"` for user-scoped entries. + +- `c` = context name +- `p` = sorted params dict (all values stringified) +- `r` = revision number +- `u` = user ID (for auth-scoped cache entries) + +**Key format:** `ctx:{context}:{hmac_hex}` +- Example: `ctx:user:605a1ca5ad5994e9b765c8d1b330474c2a0d51a7b8fbbdc402f992da7ba902f6` + +**Cross-language conformance:** The TypeScript adapter (`mizan-ts/src/cache/keys.ts`) produces identical keys for identical inputs. Pin tests verify this. + +### Cache Operations + +```python +from mizan.cache import cache_get, cache_put, cache_purge + +# Store +cache_put(secret, backend, "user", {"user_id": "5"}, b'{"name":"Ryth"}') + +# Retrieve +data = cache_get(secret, backend, "user", {"user_id": "5"}) + +# Scoped purge (recomputes HMAC, deletes one key) +cache_purge(backend, "user", params={"user_id": "5"}, secret=secret) + +# Broad purge (SCAN by prefix "ctx:user:*") +cache_purge(backend, "user") +``` + +### Backends + +**MemoryCache** — dict-based, for testing. No persistence. + +**RedisCache** — production backend. +- Connection pooling (50 max connections) +- 24h default TTL safety net +- Key prefix: `mizan:` (configurable) +- `delete_by_prefix` uses Redis SCAN (1000 keys per batch) +- `delete` uses UNLINK (non-blocking) + +### Cache Integration in Dispatch + +`context_fetch_view` checks origin-side cache before executing functions. On cache miss, executes functions and stores the result. On mutation, purges affected cache entries based on the invalidation targets. + +All HTTP responses emit `Cache-Control: no-store`. Origin-side caching is internal — the HTTP layer never caches at the CDN. Edge caching is managed by Mizan Edge (closed-source Cloudflare Workers) which uses the manifest and MWT tokens. + +--- + +## MWT (Mizan Web Token) and JWT + +### Two Token Systems + +**JWT** — standard user authentication tokens. Access + refresh pair. Session-tied for revocation. + +```python +# settings.py +JWT_PRIVATE_KEY = "your-secret-key" # Required +JWT_ALGORITHM = "HS256" # Default, or RS256 for asymmetric +JWT_ACCESS_TOKEN_EXPIRES_IN = 300 # 5 minutes +JWT_REFRESH_TOKEN_EXPIRES_IN = 604800 # 7 days +JWT_VALIDATE_SESSION = True # Check session exists on use +``` + +JWT claims: `sub` (user ID), `sid` (session key), `staff`, `super`, `type` (access/refresh), `iat`, `exp`. + +Session validation: on every JWT use, checks that the session still exists. Logging out destroys the session → immediately revokes all tokens tied to it. + +**MWT** — Mizan Web Token. Protocol-owned identity for Edge cache keying. Separate secret from JWT and cache. + +```python +# settings.py +MIZAN_MWT_SECRET = "your-mwt-signing-key" # Separate from JWT_PRIVATE_KEY +MIZAN_MWT_TTL = 300 # 5 minutes +``` + +MWT is used by Mizan Edge to derive user-scoped cache keys without exposing the cache secret to the client. The MWT carries claims that Edge needs (user identity, permissions) in a short-lived token that travels on a custom header (`X-Mizan-Token`). + +### Secret Separation + +Three independent secrets, each with its own blast radius: + +| Secret | Setting | Purpose | Compromise Impact | +|--------|---------|---------|-------------------| +| JWT secret | `JWT_PRIVATE_KEY` | User auth tokens | Auth bypass | +| Cache secret | `MIZAN_CACHE_SECRET` | HMAC cache keys | Cache poisoning | +| MWT secret | `MIZAN_MWT_SECRET` | Edge identity tokens | Cache key spoofing | + +--- + +## SSR Implementation + +### Django Template Backend + +```python +# settings.py +TEMPLATES = [ + { + 'BACKEND': 'mizan.ssr.MizanTemplates', + 'OPTIONS': { + 'worker_path': 'frontend/ssr-worker.tsx', + 'timeout': 5, + }, + }, +] +``` + +### Usage in Views + +```python +from django.shortcuts import render + +def profile_page(request, user_id): + profile = get_user_profile(user_id) + return render(request, 'ProfilePage', {'profile': profile}) +``` + +`render()` calls `MizanTemplates.get_template('ProfilePage')` which returns a `MizanTemplate`. The template's `render(context)` sends JSON-RPC to the Bun worker. + +### SSR Bridge (bridge.py) + +- Spawns `bun run ` on first render +- Persistent subprocess — stays alive across requests +- JSON-RPC over stdin/stdout with message ID correlation +- Thread-safe: multiple Django workers can call `render()` concurrently +- Auto-restarts on crash +- Waits for `{"id": 0, "ready": true}` before accepting requests + +### Bun Worker (worker.tsx) + +- Reads newline-delimited JSON from stdin +- Component registry: `registerComponent('ProfilePage', ProfilePage)` +- Calls `renderToString(createElement(Component, props))` +- Returns `{"id": N, "html": "..."}` or `{"id": N, "error": "..."}` +- Health check: `{"method": "ping"}` → `{"pong": true}` + +--- + +## Edge Manifest + +Generated by `generate_edge_manifest()` or `python manage.py export_edge_manifest`. + +```json +{ + "contexts": { + "user": { + "functions": [ + {"name": "user_profile", "path": "rpc"}, + {"name": "profile_page", "path": "view", "route": "/profile//"} + ], + "endpoints": ["/api/mizan/ctx/user/"], + "params": ["user_id"], + "user_scoped": true, + "render_strategy": "dynamic_cached", + "page_routes": ["/profile//"] + } + }, + "mutations": { + "update_profile": { + "affects": ["user"], + "auto_scoped_params": ["user_id"] + }, + "stripe_webhook": { + "affects": ["subscription"], + "private": true, + "route": "/webhooks/stripe/", + "methods": ["POST"] + } + } +} +``` + +**render_strategy**: `"psr"` (no user-scoped params) or `"dynamic_cached"` (user-scoped). Derived automatically from whether params overlap with `{user_id, user, owner_id, account_id}`. + +--- + +## URL Patterns + +```python +# mizan/urls.py +urlpatterns = [ + path("session/", session_init_view), # GET — CSRF cookie + path("call/", function_call_view), # POST — RPC dispatch + path("ctx//", context_fetch_view), # GET — bundled context fetch +] +``` + +Mounted at `/api/mizan/` by convention: +```python +urlpatterns = [ + path("api/mizan/", include("mizan.urls")), +] +``` + +--- + +## What the Codegen Currently Produces (STALE) + +The codegen in `mizan-django/generate/` still produces the **old pattern** that wraps `MizanProvider`. This needs rewriting to use the runtime (`mizanFetch`/`mizanCall`/`registerContext`) directly. See the `mizan-react/src/runtime/index.ts` for the target API. + +The SSR pipeline works independently of the codegen — it renders whatever components are registered in the Bun worker. The codegen gap only affects the client-side hooks and context providers.