Caching & Rate Limiting

Redis is the backend's shared coordination layer. @repo/runtime owns the client (packages/runtime/src/redis.ts) and cacheConfig (packages/config/src/cache.ts) centralizes every TTL, window, and limit. cacheConfig is a named export of @repo/config, not a config.* feature flag, so it is set once and every surface behaves identically.

Choosing a provider

You pick the provider at init; the CLI writes the matching env vars and swaps the redis/mutex source. The redis API and cacheConfig are identical either way, so application code never changes - the choice is about hosting.

Redis client

@repo/runtime exports a redis object. Four helpers cover the calls whose signatures differ between backends; everything else (zadd, hset, pub/sub) is the native SDK surface, used directly.

import { redis } from "@repo/runtime";

await redis.cacheSet("geo:1.2.3.4", body, { ttlSeconds: 300 });
const cached = await redis.cacheGet("geo:1.2.3.4");
for await (const key of redis.cacheScan({ match: "upload:rate:*" })) {
  // every native SDK method (zadd, hset, …) is also available on `redis`
}

cacheConfig entries

Every TTL, window, and limit lives in one object. Public endpoints and feature-gated counters get their own keyed entries.

• Feature-gated keys are inert when their flag is off - upload keys need config.storage.enabled (see Storage), view-tracking keys need config.content.defaults.viewTracking.enabled (see Content sections).
• Disable response caching: set responseCache.enabled to false and both cache() and cdnCache() become passthroughs.
• Invalidate on deploy: bump the version suffix in responseCache.keyPrefix (e.g. cache:v2) to drop all cached responses.

Distributed mutex

For work that must run exactly once across instances (credit grants, webhook handling), @repo/runtime exports withMutex(key, fn, options?) (packages/runtime/src/mutex.ts). It acquires a distributed lock, runs fn, and always releases - throwing MutexTimeoutError if the lock can't be acquired. The lock library matches the provider (redis-semaphore or @upstash/lock); both release with an atomic Lua compare-and-delete.

import { withMutex } from "@repo/runtime";

// options: { lockTimeout?: number; acquireTimeout?: number } - default lockTimeout 10000ms
await withMutex(`credits:grant:${userId}`, async () => {
  // exactly-once work
});

Frequently asked questions

Do I need Redis for local development? Yes - the backend won't boot without a reachable Redis. Self-hosted needs REDIS_URL (run a local container via pnpm infra); Upstash needs UPSTASH_REDIS_REST_URL + UPSTASH_REDIS_REST_TOKEN.

When do I use the cache* helpers vs the native SDK? Use the helpers for SET/GET/SCAN/EVAL, whose signatures differ between ioredis and Upstash. Everything else is available directly on redis with native syntax.

How do I change a rate limit or TTL? Edit the entry in cacheConfig (packages/config/src/cache.ts). It is plain configuration, not a feature flag, so the new value applies on the next restart.