Repository navigation
EN Cache and Performance
English · Türkçe · Languages / Diller
Scope: JSON API Forge 0.5.1 · Source review: 17 September 2026 · Language: English
Forge supports memory, Redis and tiered caching. Memory is process-local; Redis uses shared infrastructure; tiered caching combines local L1 and shared L2. These choices do not imply identical database consistency guarantees.
{
"cache": {
"enabled": true, "backend": "redis", "default_ttl_seconds": 30,
"stale_ttl_seconds": 0, "max_entries": 10000, "fail_open": true
}
}Configure process-level REDIS_URL for Redis. fail_open=true lets work fall back to the underlying data source if caching fails; the database must be able to absorb that load. Rate-limiter failure policy is configured separately.
| Surface | Control |
|---|---|
| SQL/Mongo lists and reads | Project cache and resource overrides |
| Read-only GET operation |
OperationCacheConfig; disabled by default |
| Data sources | TTL and stale settings |
| API-key metadata | Separate security TTL |
| JWKS | Separate security cache lifetime |
Mutations invalidate their resource namespace. Custom RPCs must declare the relevant resource/operation invalidation lists. External SQL writes and arbitrary hooks do not automatically refresh every Forge cache.
Cache keys must retain tenant/owner/principal and query context. vary_by_principal is an authorization boundary when an operation returns caller-dependent data. Caching under the wrong identity can leak data.
Short TTLs favor freshness; longer TTLs favor cache hits. A stale window deliberately permits old results, so it should not be the authority for balances or critical state checks. Single-flight reduces concurrent expensive loads but does not replace transactions or locks.
- Query plans, indexes and bounded result sizes.
- Connection pools, workers and total database capacity.
- Endpoint timeouts and concurrency budgets.
- Cache hit/miss rates, invalidation and memory limits.
- p50/p95/p99 latency and error rates under representative load.
A laptop benchmark is not a universal RPS guarantee. scripts/load_test.py is a small diagnostic probe. Compare results only with traffic shape, payload, tenant count, cache warmth and upstream latency documented.
This page describes the behavior at the pinned commits below. Recheck these contracts when upgrading.