Deleted hallucination docs
This commit is contained in:
473
CLAUDE.md
473
CLAUDE.md
@@ -1,473 +0,0 @@
|
||||
# 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/<context_name>/?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": "<div>...</div>"}
|
||||
```
|
||||
|
||||
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/<user_id>/')
|
||||
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/<user_id>/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 <worker>` 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/<user_id>/"}
|
||||
],
|
||||
"endpoints": ["/api/mizan/ctx/user/"],
|
||||
"params": ["user_id"],
|
||||
"user_scoped": true,
|
||||
"render_strategy": "dynamic_cached",
|
||||
"page_routes": ["/profile/<user_id>/"]
|
||||
}
|
||||
},
|
||||
"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/<str:context_name>/", 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.
|
||||
Reference in New Issue
Block a user