# 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 Tree organized by role. Per-framework adapters wrap a single shared kernel; codegen targets the adapter. ``` backends/ server protocol adapters mizan-django/ Django adapter mizan-fastapi/ FastAPI adapter (RPC + context + invalidation; AFI-common scope) mizan-ts/ TypeScript adapter (proves the protocol is language-agnostic) mizan-rust-axum/ Rust/Axum adapter (server-side substrate; three-way parity) mizan-tauri/ Tauri-as-Mizan-backend substrate frontends/ client kernel + per-framework adapters + transports mizan-base/ framework-agnostic kernel; owns data, status, error; adapters subscribe mizan-react/ React contexts + hooks over the kernel mizan-vue/ Vue composables over the kernel (codegen target; runtime package unimplemented) mizan-svelte/ Svelte stores over the kernel (codegen target; runtime package unimplemented) mizan-rust/ Rust kernel (PyO3 bridge; consumed by the Rust codegen's python target) mizan-tauri-transport/ Tauri IPC transport for the kernel mizan-webview-transport/ VSCode-webview transport for the kernel mizan-webview-channels/ webview channel transport cores/ shared language-level primitives mizan-python/ @client decorator, registry, MWT, HMAC cache keys; consumed by both Python backends mizan-rust/ shared Rust primitives (IR, KDL, registry, graph-check) mizan-rust-macros/ proc-macros for the Rust backend/kernel protocol/ protocol-level tooling mizan-codegen/ the codegen — a Rust binary; reads KDL IR, emits typed clients per target mizan-generate/ thin npm launcher around the compiled mizan-codegen binary workers/ runtime workers / bridges mizan-ssr/ Bun subprocess used by the Django template backend ``` --- ## 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, 'components/Hello.tsx', props)` — the template name is a `.tsx`/`.jsx` **file path** (resolved against `DIRS`), not a component name — 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. The worker `import()`s the file and renders it (no component registry): ``` → {"id": 1, "method": "render", "params": {"file": "/abs/path/Hello.tsx", "props": {"name": "World"}}} ← {"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', 'DIRS': [BASE_DIR / 'frontend'], 'OPTIONS': { 'worker': 'path/to/mizan-ssr/src/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, 'components/Profile.tsx', {'profile': profile}) ``` `render()` calls `MizanTemplates.get_template('components/Profile.tsx')` — the name is a file path resolved to an absolute path against `DIRS` — which returns a `MizanTemplate`. The template's `render(context)` sends JSON-RPC (`{file, props}`) 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 - Resolves the component by **file path** — `import(file)` (cached) — no registry - Calls `renderToString(createElement(Component, props))` on the imported default export - 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")), ] ``` --- ## Codegen — Current State The codegen is a **Rust binary**, `protocol/mizan-codegen/` (crate `mizan-codegen`). `protocol/mizan-generate/` is a thin npm launcher (`bin/launcher.mjs`) that shells out to the compiled binary. The IR is **KDL** — each backend emits KDL describing its functions/contexts; the binary reads it (`src/fetch.rs`, `src/ir.rs`) and emits per-target output from Askama templates (`templates/`, dispatched in `src/emit/`). Two layers, same as before: a framework-agnostic protocol layer (`callXxx` for mutations, `fetchXxx` for context bundles, types) and a per-framework adapter layer that subscribes to the `mizan-base` kernel. **Targets** (`src/emit/`, each byte-checked by a `*_parity.rs` test): - `react` — function/context hooks over `useSyncExternalStore`, plus the full wrapper layer: the `MizanContext` root provider (calls `configure()`, mounts the global context), `useMizan()` imperative escape hatch, and `useMutation`-backed hooks exposing `{ mutate, isPending, error }`. - `vue`, `svelte` — composables / `readable` stores. Byte-parity-tested, but no runtime adapter package or live-backend example exercises them yet (the `mizan-vue`/`mizan-svelte` packages are unimplemented stubs). - `channels` — WebSocket transport hooks. - `stage1` — the framework-agnostic protocol files. - `python`, `rust` — typed clients for the Python (PyO3) and Rust frontends. The pre-kernel `MizanProvider` in `mizan-react/src/context.tsx` (~750 lines) still ships and is imported by the desktop example; it coexists with the generated `MizanContext`. Forms (`mizan-react/src/forms.ts`) are hand-written and consume the pre-kernel provider — a form codegen target wired to `mizanCall` is still owed. See `ISSUES.md`. The SSR pipeline is independent of the codegen — the Bun worker resolves a component by **file path** (`import(file)` + `renderToString`), not via a registry.