86 lines
2.7 KiB
Markdown
86 lines
2.7 KiB
Markdown
# Cache Keying
|
|
|
|
*Discovered 2026-04-06.*
|
|
|
|
## The gap
|
|
|
|
Mizan specified invalidation but never specified cache keying.
|
|
Without correct cache keying, Edge caching is a **security
|
|
vulnerability** — it serves User A's content to User B.
|
|
|
|
## Why Vary doesn't work
|
|
|
|
All major CDNs ignore `Vary` for personalized content. No
|
|
standardized replacement exists.
|
|
|
|
## Resolution: HMAC cache key (JSON-canonical form)
|
|
|
|
```
|
|
ctx:{context}:HMAC-SHA256(secret, json.dumps({
|
|
"c": context,
|
|
"p": sorted_params, // values normalized to JSON-native strings
|
|
"r": rev,
|
|
"u": user_id // omitted for public content
|
|
}, sort_keys=True, separators=(",", ":")))
|
|
```
|
|
|
|
`derive_cache_key(secret, context, params, user_id=None, rev=0)` →
|
|
`"ctx:{context}:{hmac_hex}"`. The `ctx:{context}:` prefix lets broad
|
|
purge SCAN by prefix. Param values are normalized for cross-language
|
|
consistency (`True`→`"true"`, `None`→`"null"`) before stringification.
|
|
Implemented in `cores/mizan-python/src/mizan_core/cache/keys.py` and
|
|
`backends/mizan-ts/src/cache/keys.ts` (`deriveCacheKey`); pin tests
|
|
verify identical output.
|
|
|
|
### Key derivation rules
|
|
|
|
- **Public content** — URL path + query params (standard CDN).
|
|
- **User-scoped content** — HMAC key derivation above.
|
|
- **`@client(auth=...)`** determines whether content is user-scoped.
|
|
- **`rev` parameter** on `@client` for deploy-time logic
|
|
invalidation. Bumped by the developer when function logic changes.
|
|
|
|
## Identity layer
|
|
|
|
MWT (Mizan Web Token) — see [MWT_SPEC.md](MWT_SPEC.md). JWT with
|
|
Mizan claims on `X-Mizan-Token` header. Replaces the old
|
|
`JWTUser` + permission key metadata approach.
|
|
|
|
## Cache architecture
|
|
|
|
*Decided 2026-04-06.*
|
|
|
|
**Not a compiled binary ABI. Not a pluggable Python protocol.**
|
|
|
|
Each backend adapter (Python, TypeScript, future PHP/C#/Go)
|
|
implements the cache protocol in its own language.
|
|
**Conformance verified by a shared test suite.**
|
|
|
|
### Required operations
|
|
|
|
- `cache_get`
|
|
- `cache_put`
|
|
- `cache_purge` (scoped recomputes the key; broad SCANs the
|
|
`ctx:{context}:*` prefix)
|
|
|
|
### Storage
|
|
|
|
Two backends behind a `CacheBackend` protocol
|
|
(`mizan_core/cache/backend.py`):
|
|
|
|
- `MemoryCache` — dict-based, for testing.
|
|
- `RedisCache` — production; persistence, cross-worker sharing, crash
|
|
recovery. Broad purge via SCAN, delete via UNLINK.
|
|
|
|
## Deploy invalidation
|
|
|
|
No full context flush. The `rev` parameter on `@client` is part of
|
|
the HMAC key. When the developer bumps `rev`, old cache entries
|
|
become **unreachable orphans**. No purge needed; no thundering herd.
|
|
|
|
## Invariant
|
|
|
|
All cache-related code must implement *identical* HMAC key
|
|
derivation. Cross-language conformance tests enforce this. Any
|
|
divergence is a security vulnerability.
|