KV-only hot path — no D1 reads in interactive requests
ADR-004: KV-only hot path — no D1 reads in interactive requests
Section titled “ADR-004: KV-only hot path — no D1 reads in interactive requests”Status: Accepted Date: 2026-04-06 Deciders: Mishaal Murawala
Context
Section titled “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
Section titled “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
Section titled “Consequences”Positive
Section titled “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
Section titled “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
- 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
Section titled “Alternatives Considered”D1 for everything
Section titled “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
Section titled “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.