KV-only hot path — no D1 reads in interactive requests
ADR-004: KV-only hot path — no D1 reads in interactive requests
Status: Accepted Date: 2026-04-06 Deciders: Mishaal Murawala
Context
The V5 gateway needs a data store for tokens, tenant config, API config, and scheduling policy. Cloudflare offers KV (eventually consistent, sub-ms reads) and D1 (SQLite, consistent, ~5ms reads). The gateway’s target is ≤10ms overhead per request.
Decision
We will use KV as the sole data source for all interactive (hot path) requests. D1 is restricted to cold-path writes only: error_ledger and kv_audit.
Consequences
Positive
- Sub-millisecond reads (KV is edge-cached)
- Gateway overhead stays under 10ms (auth ≤5ms + token ≤2ms + route ≤3ms)
- No connection pooling, no query planning, no SQL parsing in the hot path
Negative
- KV is eventually consistent (~60s propagation) — token writes from Durable Objects may take up to 60s to be visible. Acceptable because DO alarm fires 10min before token expiry.
- No relational queries — can’t JOIN tenant config with token data. Must denormalize.
- 25MB value limit per key
Risks
- If a KV write fails silently, the hot path serves stale data with no error signal. Mitigated by
kv_auditin D1 logging every admin write.
Alternatives Considered
D1 for everything
- Rejected because: 5ms reads blow the 10ms overhead budget. D1 is overkill for key-value lookups.
D1 for config, KV for tokens
- Rejected because: splitting reads across two stores adds complexity and latency without benefit. Config changes are rare enough that KV’s eventual consistency is fine.