Ryth Azhur
ae684a36cb
Roll the working tree back to the last approved shape, before the post-LICENSE span that false-greened the AFI parity matrix with symbol-presence probes and smuggled an unauthorized SQLAlchemy dependency into FastAPI's Shapes binding.
Forward commit, not a history rewrite — the six commits since 4effcc7 stay in the log as the record of what happened.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
123 lines
5.6 KiB
Markdown
123 lines
5.6 KiB
Markdown
# 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.
|
|
|
|
```python
|
|
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/`](docs/) — architecture references: AFI, SSR, cache keying, MWT, PSR vs. Edge
|
|
- [`ROADMAP.md`](ROADMAP.md) · [`ISSUES.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) | ✅ | ✅ | ✅ ⁶ | ✅ ⁶ | — ⁸ |
|
|
|
|
### 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.
|
|
|
|
### 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, session validation) | ✅ | ❌ | ❌ | ❌ | ❌ |
|
|
| 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. TypeScript is an edge/protocol-reference adapter (HMAC cache, manifest, PSR), not a
|
|
codegen source — it demonstrates the cache + invalidation protocol is
|
|
language-agnostic.
|
|
|
|
## Conformance
|
|
|
|
Adapter parity is gated by the AFI conformance suite in [`tests/afi/`](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](LICENSE) (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.
|