Added LICENSE
This commit is contained in:
142
README.md
142
README.md
@@ -1,90 +1,122 @@
|
||||
# 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.
|
||||
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.
|
||||
|
||||
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).
|
||||
```python
|
||||
from mizan import client, ReactContext
|
||||
|
||||
---
|
||||
UserContext = ReactContext('user')
|
||||
|
||||
## Backend Adapter Parity
|
||||
# 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]
|
||||
|
||||
**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).
|
||||
# Mutation — invalidation scoped automatically by matching param name
|
||||
@client(affects=UserContext)
|
||||
def update_profile(request, user_id: int, name: str) -> dict:
|
||||
...
|
||||
```
|
||||
|
||||
Legend: ✅ full · ◑ partial · ❌ absent · — not applicable to this transport
|
||||
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 — `X-Mizan-Invalidate` header | ✅ | ❌ | ❌ | — ¹ | ✅ |
|
||||
| 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 | ✅ | ❌ | ❌ | ❌ | ✅ |
|
||||
| WebSocket channels | ✅ | ❌ | ◑ ² | ❌ | ❌ |
|
||||
| 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) ⁴ | ✅ | — | — | — | — |
|
||||
| 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.
|
||||
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.
|
||||
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*
|
||||
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.
|
||||
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; real CSRF is Django-only.
|
||||
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.
|
||||
|
||||
### Reading the columns
|
||||
## Conformance
|
||||
|
||||
- **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.
|
||||
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.
|
||||
|
||||
### Keeping this honest
|
||||
## License
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user