Redis Caching

Cache Key Patterns

// Consistent key naming
const KEYS = {
  poll: (id: string) => `poll:${id}`,
  placement: (id: string) => `placement:${id}`,
  orgPolls: (orgId: string, page: number) => `org:${orgId}:polls:page:${page}`,
  searchResult: (queryHash: string) => `search:${queryHash}`,
  synthesis: (queryHash: string) => `synthesis:${queryHash}`,
  rateLimit: (ip: string, endpoint: string) => `rl:${endpoint}:${ip}`,
  freqCap: (profileId: string, campaignId: string) =>
    `fc:${campaignId}:${profileId}`,
  session: (sessionId: string) => `session:${sessionId}`,
};

Rate Limiting

async function checkRateLimit(
  key: string,
  limit: number,
  windowSeconds: number,
): Promise<{ allowed: boolean; remaining: number }> {
  try {
    const current = await redis.incr(key);
    if (current === 1) {
      await redis.expire(key, windowSeconds);
    }
    return {
      allowed: current <= limit,
      remaining: Math.max(0, limit - current),
    };
  } catch {
    // Fail open — if Redis is down, allow the request
    return { allowed: true, remaining: limit };
  }
}

// Middleware
export const rateLimiter = (limit: number, windowSeconds: number) =>
  createMiddleware(async (c, next) => {
    const ip = c.req.header("x-forwarded-for") ?? "unknown";
    const key = KEYS.rateLimit(ip, c.req.path);
    const { allowed, remaining } = await checkRateLimit(
      key,
      limit,
      windowSeconds,
    );

    c.header("X-RateLimit-Limit", String(limit));
    c.header("X-RateLimit-Remaining", String(remaining));

    if (!allowed) return c.json({ error: "Rate limit exceeded" }, 429);
    await next();
  });

Frequency Capping

// Campaign-level: default 3/day, range 1-20/day
async function checkFrequencyCap(
  profileId: string,
  campaignId: string,
  dailyLimit: number = 3,
): Promise<boolean> {
  const key = KEYS.freqCap(profileId, campaignId);

  try {
    const count = await redis.incr(key);
    if (count === 1) {
      // Set expiry to end of day UTC
      const now = new Date();
      const endOfDay = new Date(now);
      endOfDay.setUTCHours(23, 59, 59, 999);
      const ttl = Math.ceil((endOfDay.getTime() - now.getTime()) / 1000);
      await redis.expire(key, ttl);
    }
    return count <= dailyLimit;
  } catch {
    // Fail open — show the campaign if Redis is down
    return true;
  }
}

Cache Invalidation

// Invalidate on write
async function updatePoll(pollId: string, data: Partial<Poll>) {
  await db.update(polls).set(data).where(eq(polls.id, pollId));

  // Invalidate specific poll cache
  await redis.del(KEYS.poll(pollId));

  // Invalidate list caches for this org (pattern delete via SCAN)
  for await (const key of redis.scanIterator({
    MATCH: `org:${data.organizationId}:polls:*`,
    COUNT: 100,
  })) {
    await redis.del(key);
  }
}

// Invalidate search cache when polls change
async function invalidateSearchCache(pollId: string) {
  // Can't easily know which search queries included this poll
  // Option 1: Short TTL (5 min) so cache expires naturally
  // Option 2: Tag-based invalidation (more complex)
}

TTL Strategy

Common Mistakes

1. Always fail open — if Redis is down, serve from DB, don't error
2. Don't cache user-specific data with shared keys — include userId/orgId in key
3. Set TTL on everything — orphaned keys waste memory
4. Don't use KEYS in production — it scans all keys. Use SCAN for pattern matching.
5. Watch memory — know your instance limits. Monitor with INFO memory
6. Serialize consistently — always JSON.stringify/JSON.parse, don't mix formats