rythazhur/mizan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add X-Mizan-Invalidate header (second invalidation transport)

Browse Source 
Mutation responses now carry invalidation via two transports:

1. JSON body: {"result": ..., "invalidate": ["user"]}
2. HTTP header: X-Mizan-Invalidate: user, notifications

Both are set on every mutation response. The JSON body is consumed
by the client runtime (mizanCall). The header is consumed by Edge
for CDN cache purging and by XHR responses for htmx-style apps.

Header format: comma-separated contexts, semicolon-separated params.
  X-Mizan-Invalidate: user;user_id=5, notifications

Also: _resolve_invalidation and _format_invalidate_header extracted
as reusable helpers for when return-type branching adds HttpResponse
support (view-path mutations will only use the header transport).

Updated ROADMAP.md with full v1 plan including both transports,
return-type branching, affects_params, and Edge manifest.

270 Django tests pass.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ryth Azhur
2026-04-02 18:53:23 -04:00
parent f4d7c64e3c
commit 8aa20111b4
3 changed files with 233 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

116
ROADMAP.md
View File

@@ -8,7 +8,7 @@
- **ReactContext class** — type-safe context/affects references with linting
- **Named contexts** — functions sharing a context name are grouped into one provider and one fetch
- **Context bundling endpoint** — `GET /api/mizan/ctx/<name>/` returns all functions in one response
- **Server-driven invalidation** — mutation responses carry `invalidate` from `affects=` metadata
- **Server-driven invalidation (JSON body)** — mutation responses carry `{"result": ..., "invalidate": [...]}`
- **Scoped invalidation** — runtime supports `invalidate: [{context: "user", params: {user_id: 5}}]`
- **Param elevation** — shared params become required provider props, non-shared become optional
- **Schema export** — `x-mizan-functions` + `x-mizan-contexts` for codegen
@@ -17,20 +17,62 @@
- **Shapes** — Pydantic + django-readers for typed query projections
- **WebSocket channels** — real-time bidirectional communication
- **Codegen** — generates typed React providers, hooks, mutations from schema
- **CDN-ready headers** — `Cache-Control`, `Vary`, deterministic JSON on context GETs, `no-store` on mutations
### Next: CDN-Ready Headers
### Next: X-Mizan-Invalidate Header
Context GETs must be cacheable by a CDN sitting in front of Django.
Second invalidation transport. For view responses (redirects, HTML), invalidation goes in an HTTP header instead of the JSON body. Both transports are first-class AFI spec.
- `Cache-Control` headers on `GET /api/mizan/ctx/<name>/` responses
- `Vary` headers for auth-dependent responses
- Deterministic JSON output (sorted keys)
- Mutation POSTs must return `Cache-Control: no-store`
- Context error responses must not be cached
- Header format: `X-Mizan-Invalidate: user;user_id=5, notifications`
- Comma-separated contexts, semicolon-separated params per context
- Decorator auto-adds header to any HttpResponse with `affects=`
- Edge reads this header to purge cached pages
- Runtime also reads it on XHR/fetch responses (htmx path)
### Next: Fold mizan-runtime into mizan-react
### Next: Return-Type Branching
The runtime (~150 lines: context registry, invalidation batcher, fetch primitives) merges into mizan-react. Framework-agnostic split is deferred until a second frontend adapter exists.
`@client` serves both RPC developers (React/SPA) and view developers (htmx/templates). Return type determines behavior:
- **Data return** (dict, Shape, BaseModel) → RPC path. Generates typed hooks. Invalidation in JSON body.
- **HttpResponse return** (render, redirect) → View path. No codegen. Invalidation in `X-Mizan-Invalidate` header.
Same decorator. Same `affects=`. Same invalidation graph. Two paths.
### Next: affects_params
Scoped invalidation with a lambda that extracts which params were affected:
```python
@client(affects='user', affects_params=lambda req: {'user_id': req.user.pk})
def update_name(request, name: str) -> dict:
...
```
Produces `invalidate: [{context: "user", params: {user_id: 5}}]` in JSON body or `X-Mizan-Invalidate: user;user_id=5` in header.
### Next: Edge Manifest
`mizan-generate --manifest` compiles the decorator registry + Django URL conf into static JSON for Edge:
```json
{
"contexts": {
"user": {
"endpoints": ["/api/mizan/ctx/user/"],
"views": ["/profile/:user_id/"],
"params": ["user_id"]
}
}
}
```
Edge reads the manifest at deploy time. When it receives `X-Mizan-Invalidate: user;user_id=5`, it resolves URL patterns with params and purges `/profile/5/` and `/api/mizan/ctx/user/?user_id=5`.
Generated alongside React code. Covers both RPC and view-path functions.
### Next: Codegen Rewrite
Generated code uses the runtime directly (`mizanFetch`, `mizanCall`, `registerContext`) instead of the legacy `MizanProvider` pattern. Mutations have zero invalidation knowledge — the runtime reads the server response.
### Next: SSR Bridge
@@ -42,10 +84,6 @@ Django renders React components server-side via a persistent Bun subprocess.
- Hydration: `window.__MIZAN_SSR_DATA__` consumed by generated providers
- Generated contexts check SSR data before first fetch
### Next: Codegen Rewrite
Generated code uses the runtime directly (`mizanFetch`, `mizanCall`, `registerContext`) instead of the legacy `MizanProvider` pattern. Mutations have zero invalidation knowledge — the runtime reads the server response.
---
## Mizan Cloud (closed-source)
@@ -54,10 +92,12 @@ Generated code uses the runtime directly (`mizanFetch`, `mizanCall`, `registerCo
Cloudflare Workers for automatic edge caching.
- Reads the Mizan schema to configure cache rules
- Context GETs cached at the edge, keyed by context name + params
- Mutation POSTs trigger cache purges from the `invalidate` response key
- Zero configuration — the schema IS the cache policy
- Reads the Edge manifest to configure cache rules
- Context GETs cached at edge, keyed by context name + params
- Reads `X-Mizan-Invalidate` header from mutation responses to purge caches
- Reads JSON `invalidate` key from RPC responses for the same purpose
- Resolves URL patterns from manifest to purge view pages
- Zero configuration — the manifest IS the cache policy
### Mizan Render
@@ -78,9 +118,9 @@ One-command deployment for Django + React apps.
---
## Protocol Spec
## Protocol Spec (AFI)
The protocol is the product. Every endpoint is designed for a CDN.
The protocol is the product. Two invalidation transports. Every endpoint CDN-ready.
### Context fetch
@@ -88,7 +128,7 @@ The protocol is the product. Every endpoint is designed for a CDN.
GET /api/mizan/ctx/<name>/?param=value
200 OK
Cache-Control: public, max-age=60, stale-while-revalidate=300
Cache-Control: public, max-age=0, stale-while-revalidate=300
Vary: Authorization, Cookie
{
@@ -97,7 +137,7 @@ Vary: Authorization, Cookie
}
```
### Mutation call
### Mutation call (RPC path — JSON body transport)
```
POST /api/mizan/call/
@@ -109,9 +149,19 @@ Cache-Control: no-store
}
```
### Scoped invalidation
### Mutation call (View path — header transport)
```
POST /profile/update/
302 Found
Location: /profile/5/
Cache-Control: no-store
X-Mizan-Invalidate: user;user_id=5, notifications
```
### Scoped invalidation (JSON)
```json
{
"result": { ... },
"invalidate": [
@@ -120,3 +170,23 @@ Cache-Control: no-store
]
}
```
### Scoped invalidation (Header)
```
X-Mizan-Invalidate: user;user_id=5, notifications
```
### Edge manifest
```json
{
"contexts": {
"user": {
"endpoints": ["/api/mizan/ctx/user/"],
"views": ["/profile/:user_id/"],
"params": ["user_id"]
}
}
}
```