mizan/CLAUDE.md

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)
frontends/        client kernel + per-framework adapters
    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
    mizan-svelte/    Svelte stores/runes over the kernel
cores/            shared language-level primitives
    mizan-python/    @client decorator, registry, MWT, HMAC cache keys; consumed by both Python backends
protocol/         protocol-level tooling
    mizan-generate/  codegen — fetches schema from any backend, emits typed React/Vue/Svelte client
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&param2=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):

{"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": "<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

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

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

{
    "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

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

derive_cache_key(secret, context, params, user_id=None, rev=0) -> str

Canonical form (the HMAC message):

{"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

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.

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

# 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

# settings.py
TEMPLATES = [
    {
        'BACKEND': 'mizan.ssr.MizanTemplates',
        'OPTIONS': {
            'worker_path': 'frontend/ssr-worker.tsx',
            'timeout': 5,
        },
    },
]

Usage in Views

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

{
    "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

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

urlpatterns = [
    path("api/mizan/", include("mizan.urls")),
]

---

Codegen — Current State

The codegen is protocol/mizan-generate/ — framework-agnostic, two-stage. Stage 1 emits the protocol layer (callXxx for mutations, fetchXxx for context bundles, types). Stage 2 emits per-framework hooks/composables/stores that subscribe to the mizan-base kernel.

What's in place:

• Function hooks (useEcho, useUserProfile, etc.) in the React adapter, subscribing to kernel state via useSyncExternalStore
• Context hooks for named contexts and global
• Channel hooks for WebSocket transport
• Vue and Svelte equivalents (Stage 2 templates compile, but no live-backend example exercises them — see ISSUES.md A4)

What's not yet emitted (the wrapper layer):

• <MizanContext> provider component for React (calls configure() and mounts the kernel into the component tree)
• useMizan() hook for accessing the kernel from React
• Framework-named error class (e.g. DjangoError) wrapping MizanError from the kernel
• Vue and Svelte equivalents

The legacy MizanProvider in mizan-react/src/context.tsx (~750 lines) and the forms.ts consumer (~1163 lines) still depend on the pre-kernel API. They're tracked as ISSUES.md A1 and A3. Removing them is gated on the wrapper layer above being emitted.

The SSR pipeline is independent of the codegen — it renders whatever components are registered in the Bun worker.