mizan/README.md

Mizan

Mizan is an Application Framework Interface (AFI). A single @client decorator on a server function generates a typed frontend client; cache invalidation and caching are handled by the protocol.

from mizan import client, ReactContext

UserContext = ReactContext('user')

# Context function — bundled into GET /api/mizan/ctx/user/
@client(context=UserContext)
def user_profile(request, user_id: int) -> UserShape:
    return UserShape.query(lambda qs: qs.filter(pk=user_id))[0]

# Mutation — invalidation scoped automatically by matching param name
@client(affects=UserContext)
def update_profile(request, user_id: int, name: str) -> dict:
    ...

Adapters exist for Django, FastAPI, Rust/Axum, Tauri, and TypeScript. Django is the reference implementation; per-adapter support is inventoried below.

Status: Mizan is not production-tested. It passes its own test suites but has not been run in a production deployment. Treat it as pre-release.

Documentation

• docs/ — architecture references: AFI, SSR, cache keying, MWT, PSR vs. Edge
• ROADMAP.md · ISSUES.md — planned work and known gaps

Backend adapters

Every adapter implements the same AFI wire protocol. The matrix below inventories support per adapter, grouped to separate protocol guarantees from Django-specific features (forms, ORM projection, auth providers, SSR). A cell counts as supported only when that adapter wires the capability into its own dispatch surface, not merely that a shared core primitive exists.

Legend: ✅ supported · ◑ partial · ❌ not implemented · — not applicable to this transport

Protocol core

The surface every Mizan adapter implements.

Capability	Django	FastAPI	Rust / Axum	Tauri	TypeScript
RPC call dispatch ({result, invalidate})	✅	✅	✅	✅ ¹	✅
Named-context bundle fetch	✅	✅	✅	✅	✅
Invalidation — JSON body	✅	✅	✅	✅	✅
Invalidation auto-scoping (three-tier)	✅	✅	✅	✅	✅
Function discovery / registration	✅	✅	✅	✅	✅
Codegen IR export (KDL)	✅	✅	✅ ⁶	✅ ⁶	❌ ⁸
File uploads (multipart, Upload type)	✅	✅	❌ ⁹	❌ ⁹	— ¹⁰

Edge, cache & enforcement

Protocol transports and guarantees co-equal with the body channel in the spec.

Capability	Django	FastAPI	Rust / Axum	Tauri	TypeScript
Invalidation — X-Mizan-Invalidate header	✅	✅	❌	— ¹	✅
Auth-guard enforcement (auth=… rejects)	✅	✅	❌ ⁵	◑ ⁵	✅ ¹¹
Origin-side HMAC cache	✅	✅	❌	❌	✅
Edge manifest export	✅	❌	❌	—	✅
PSR (render_strategy in manifest)	✅	❌	❌	—	✅
Session / CSRF init endpoint	✅	◑ ⁷	◑ ⁷	—	❌

Caveat: Rust/Axum and Tauri accept auth= on a function but do not yet enforce it — do not rely on auth= for access control on those adapters.

Django, FastAPI, and TypeScript share one auth/invalidation/cache implementation (mizan_core for the Python adapters; the same spec, pinned cross-language, for TS).

Stack extensions (Django)

Django ecosystem features Mizan wraps. Other adapters provide these only where the target stack calls for them.

Capability	Django	FastAPI	Rust / Axum	Tauri	TypeScript
WebSocket channels (declared transport)	✅	❌	◑ ²	❌	❌
Forms (schema / validate / submit)	✅	❌	◑ ³	❌	❌
Formsets	✅	❌	❌	❌	❌
API shapes (ORM query projection) ⁴	✅	—	—	—	—
JWT auth (access / refresh) ¹²	✅	✅	❌	❌	◑ ¹³
MWT (edge identity token)	✅	✅	❌	—	◑ ¹³
SSR bridge	✅	❌	❌	—	❌
Auth-provider integration (allauth)	✅	❌	❌	❌	❌

Notes

1. Tauri's transport is Tauri IPC (a single #[tauri::command] envelope), not HTTP. Invalidation rides in the JSON response body; there is no header channel.
2. Rust/Axum declares Transport::Websocket in the IR/macro but routes no Axum WebSocket handler yet.
3. Rust/Axum carries is_form/form_role trait stubs but no validate/submit endpoint.
4. "API shapes" is Django's django-readers queryset projection — ORM-coupled. Every adapter carries typed input/output through the KDL IR; the projection primitive itself is Django-only.
5. Tauri's FunctionSpec carries auth/private fields; the dispatch path does not enforce them. Rust/Axum has no enforcement either.
6. Rust/Axum and Tauri are the IR authority via the #[mizan::client] macro + linkme registry; the codegen links the crate directly (build_ir() / the export-ir bin) rather than fetching over HTTP.
7. FastAPI and Rust/Axum expose GET /session/ returning a null CSRF token for wire parity; CSRF is Django-only.
8. mizan-ts emits the Edge manifest (JSON) but has no KDL IR emitter, so it can't yet feed the codegen — an unbuilt gap. A TypeScript backend still needs the generated client (types + callXxx/fetchXxx + framework hooks); same language doesn't remove the need for it.
9. The mizan-codegen crate parses the upload KDL node and emits the field across targets (the Rust target lowers it to Vec<u8>). Multipart dispatch binding is wired for Django and FastAPI only; the Rust/Axum and Tauri adapters have no upload concept at dispatch yet.
10. The TypeScript column is the mizan-ts backend adapter, which has no upload dispatch. The matching client side lives in the kernel (@mizan/base): mizanCall auto-switches to multipart/form-data when any argument is a File.
11. mizan-ts dispatch now enforces auth= (true/'staff'/'superuser'/predicate) against a host-supplied Identity, byte-matching the Python guard's denial messages.
12. JWT/MWT token logic is single-sourced in mizan_core.auth; Django and FastAPI ride it. Session-validation (immediate-logout revocation) is Django-only — FastAPI mints from its own credential check.
13. mizan-ts ships an optional decodeMwt/decodeJwtBearer/identityFromMwt helper (HS256 via Node crypto, cross-language pin-tested against a Python-minted MWT) so a TS edge worker can derive Identity from a Python-issued token. Identity source stays host-supplied; mizan-ts does not mint from a session.

Conformance

Adapter parity is gated by the AFI conformance suite in tests/afi/. It currently asserts IR-shape parity — the same fixture through Django, FastAPI, and the Rust adapter emits byte-identical KDL (test_codegen_parity.py). Per-capability runtime assertions (header transport, auth= enforcement, cache behavior) are planned.

License

Mizan is licensed under the Elastic License 2.0 (SPDX: Elastic-2.0). You may use, copy, modify, and distribute it freely, including in commercial products you build on top of it. You may not provide Mizan to third parties as a hosted or managed service that exposes a substantial set of its features.