91 lines
4.7 KiB
Markdown
91 lines
4.7 KiB
Markdown
# Mizan
|
|
|
|
An **Application Framework Interface (AFI)** — one decorator on a server function, a
|
|
typed client generated, invalidation automatic, caching protocol-driven. Any backend,
|
|
any frontend, one wire protocol.
|
|
|
|
For the wire protocol, package layout, and codegen state, see [`CLAUDE.md`](CLAUDE.md).
|
|
Architecture deep-dives live in [`docs/`](docs/). Open work is tracked in
|
|
[`ROADMAP.md`](ROADMAP.md) and [`ISSUES.md`](ISSUES.md).
|
|
|
|
---
|
|
|
|
## Backend Adapter Parity
|
|
|
|
**Django is the maximal rubric** — it implements the full AFI surface. Every other
|
|
adapter is measured against it. A cell is marked supported only when *that adapter*
|
|
wires the capability into its own dispatch surface (not merely that a shared core
|
|
primitive exists).
|
|
|
|
Legend: ✅ full · ◑ partial · ❌ absent · — not applicable to this transport
|
|
|
|
| Capability | Django | FastAPI | Rust / Axum | Tauri | TypeScript |
|
|
|---|:---:|:---:|:---:|:---:|:---:|
|
|
| RPC call dispatch (`{result, invalidate}`) | ✅ | ✅ | ✅ | ✅ ¹ | ✅ |
|
|
| Named-context bundle fetch | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
| Invalidation — JSON body | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
| Invalidation — `X-Mizan-Invalidate` header | ✅ | ❌ | ❌ | — ¹ | ✅ |
|
|
| Invalidation auto-scoping (three-tier) | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
| Origin-side HMAC cache | ✅ | ❌ | ❌ | ❌ | ✅ |
|
|
| WebSocket channels | ✅ | ❌ | ◑ ² | ❌ | ❌ |
|
|
| Forms (schema / validate / submit) | ✅ | ❌ | ◑ ³ | ❌ | ❌ |
|
|
| Formsets | ✅ | ❌ | ❌ | ❌ | ❌ |
|
|
| API shapes (ORM query projection) ⁴ | ✅ | — | — | — | — |
|
|
| Auth guards (`auth=True/'staff'/'superuser'/callable`) | ✅ | ✅ | ❌ | ◑ ⁵ | ❌ |
|
|
| JWT auth (access / refresh, session validation) | ✅ | ❌ | ❌ | ❌ | ❌ |
|
|
| MWT (edge identity token) | ✅ | ❌ | ❌ | — | ❌ |
|
|
| SSR bridge | ✅ | ❌ | ❌ | — | ❌ |
|
|
| PSR (`render_strategy` in manifest) | ✅ | ❌ | ❌ | — | ✅ |
|
|
| Edge manifest export | ✅ | ❌ | ❌ | — | ✅ |
|
|
| Codegen IR export (KDL) | ✅ | ✅ | ✅ ⁶ | ✅ ⁶ | ❌ |
|
|
| Session / CSRF init endpoint | ✅ | ◑ ⁷ | ◑ ⁷ | — | ❌ |
|
|
| Function discovery / registration | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
| 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, so the
|
|
header row is N/A.
|
|
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, but the dispatch path does
|
|
not enforce them.
|
|
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; real CSRF is Django-only.
|
|
|
|
### Reading the columns
|
|
|
|
- **FastAPI** — the AFI-common HTTP subset: dispatch, contexts, body invalidation,
|
|
auth guards, IR export. Channels / forms / SSR / cache are deliberately delegated to
|
|
native FastAPI equivalents.
|
|
- **Rust / Axum** — core dispatch + context bundling + compile-time registry, and the
|
|
*server-side* IR authority. No HTTP-layer cache, auth enforcement, or edge surface
|
|
yet.
|
|
- **Tauri** — the same Rust core over IPC for desktop/mobile. Edge, SSR, MWT, and CSRF
|
|
are structurally inapplicable to a local app.
|
|
- **TypeScript** — the edge/protocol reference: HMAC cache, edge manifest, and PSR
|
|
strategy, proving the cache + invalidation protocol is language-agnostic. It is not a
|
|
codegen IR source.
|
|
|
|
### Keeping this honest
|
|
|
|
This table is a **snapshot**, and a hand-maintained snapshot drifts the moment an
|
|
adapter gains or loses a target. The enforcing layer is the AFI conformance suite at
|
|
[`tests/afi/`](tests/afi/), which today gates **IR-shape parity** — the same fixture
|
|
through Django, FastAPI, and the Rust adapter must emit byte-identical KDL
|
|
(`test_codegen_parity.py`). It does **not yet** assert *runtime capability* parity
|
|
(e.g. "every adapter that claims the header transport actually emits
|
|
`X-Mizan-Invalidate`," "every adapter that claims `auth=` actually rejects an
|
|
unauthorized call"). Extending `tests/afi/` with per-capability assertions — one row of
|
|
this table per asserted behavior — is what turns the table from documentation into a
|
|
red-on-regression contract.
|