@rune-kit/rune 2.8.0 → 2.11.0

package/extensions/backend/skills/background-jobs.md

@@ -1,133 +1,133 @@
----
-name: "background-jobs"
-pack: "@rune/backend"
-description: "Queue-based async processing — BullMQ (Node.js), job patterns, retry strategies, idempotency, dead letter queues, monitoring."
-model: sonnet
-tools: [Read, Edit, Write, Grep, Glob, Bash]
----
-
-# background-jobs
-
-Queue-based async processing — BullMQ (Node.js), job patterns, retry strategies, idempotency, dead letter queues, monitoring.
-
-#### Workflow
-
-**Step 1 — Identify async operations**
-Scan route handlers and service functions for operations that: (a) take > 200ms (PDF generation, image resizing, report aggregation), (b) are non-user-facing (email sending, webhook delivery, analytics events), (c) can tolerate eventual consistency (data sync, cache warming, notification dispatch). Flag these as candidates for background jobs. Output a classification: fire-and-forget vs delayed vs scheduled (cron) vs fan-out.
-
-**Step 2 — Choose queue system**
-Node.js: BullMQ (Redis-backed, TypeScript-native, built-in retry/delay/priority/rate-limiting — recommended). Python: Celery + Redis/RabbitMQ broker (mature, distributed workers, beat scheduler for cron). For very simple use cases (single server, low volume): `node-cron` + in-process worker. Avoid in-process queues in production — they die with the process and lose jobs.
-
-**Step 3 — Implement job with retry strategy**
-Emit job producer (enqueue) and worker (processor) as separate files. Retry strategy: exponential backoff with jitter (`attempts: 5, backoff: { type: 'exponential', delay: 1000 }`). Idempotency: every job MUST have an idempotency key — use a deterministic ID from the operation (e.g., `email:welcome:${userId}` not a random UUID). This ensures duplicate enqueues (from retries, double-clicks) process exactly once. Dead letter queue: after max retries, move job to a `{queue-name}:failed` queue for inspection and manual replay — never silently drop.
-
-**Step 4 — Add monitoring and alerting**
-BullMQ Board or Bull Dashboard for visual queue monitoring. Emit metrics: queue depth (jobs waiting), processing rate (jobs/sec), failure rate (failed/total). Alert when: queue depth > threshold (workers not keeping up), failure rate > 5% (systematic error in processor), job age > expected TTL (stuck job). Use BullMQ events (`queue.on('failed', ...)`) to push metrics to Prometheus or Datadog.
-
-**Step 5 — Handle dead letters**
-Emit dead letter inspection endpoint: list failed jobs with error reason, retry count, and last error. Emit replay endpoint: re-enqueue a specific failed job with a fresh retry budget. Purge endpoint: clear dead letter queue after investigation. Add alerting on dead letter queue depth > 0 for critical job types (payment processing, compliance logging).
-
-#### Example
-
-```typescript
-// BullMQ setup with TypeScript — producer + worker
-import { Queue, Worker, Job } from 'bullmq';
-
-const connection = { host: REDIS_HOST, port: 6379 };
-
-// Job type definitions
-interface EmailJob { to: string; template: string; data: Record<string, unknown> }
-interface PdfJob { reportId: string; userId: string; format: 'pdf' | 'xlsx' }
-
-// Producers
-export const emailQueue = new Queue<EmailJob>('email', { connection });
-export const pdfQueue = new Queue<PdfJob>('pdf', { connection });
-
-// Enqueue with idempotency key (jobId = idempotent identifier)
-export const sendWelcomeEmail = (userId: string, email: string) =>
-  emailQueue.add('welcome', { to: email, template: 'welcome', data: { userId } }, {
-    jobId: `email:welcome:${userId}`, // prevents duplicate welcome emails
-    attempts: 3,
-    backoff: { type: 'exponential', delay: 2_000 },
-    removeOnComplete: { count: 1000 }, // keep last 1000 completed for audit
-    removeOnFail: false, // keep all failed for dead letter review
-  });
-
-// Scheduled/delayed job
-export const sendReminderEmail = (userId: string, delayMs: number) =>
-  emailQueue.add('reminder', { to: userId, template: 'reminder', data: {} }, {
-    delay: delayMs,
-    attempts: 5,
-    backoff: { type: 'exponential', delay: 5_000 },
-  });
-
-// Worker processor with error handling
-const emailWorker = new Worker<EmailJob>('email', async (job: Job<EmailJob>) => {
-  const { to, template, data } = job.data;
-  // Validate job data — serialized payload may be stale
-  if (!to || !template) throw new Error(`Invalid job payload: ${JSON.stringify(job.data)}`);
-  await emailService.send({ to, template, data });
-  // Return value is stored in job.returnvalue for audit
-  return { sentAt: new Date().toISOString() };
-}, {
-  connection,
-  concurrency: 10,           // process up to 10 emails in parallel
-  limiter: { max: 100, duration: 60_000 }, // rate limit: 100/min
-});
-
-emailWorker.on('failed', async (job, err) => {
-  logger.error({ jobId: job?.id, queue: 'email', error: err.message, attempts: job?.attemptsMade });
-  if (job?.attemptsMade >= job?.opts.attempts!) {
-    // max retries exhausted → alert
-    await alerting.notify(`Dead letter: email job ${job.id} failed after ${job.attemptsMade} attempts`);
-  }
-});
-
-// Fan-out pattern: one job enqueues many children
-const fanOutNotification = async (eventId: string, userIds: string[]) => {
-  const jobs = userIds.map(userId => ({
-    name: 'notify',
-    data: { userId, eventId },
-    opts: {
-      jobId: `notify:${eventId}:${userId}`,
-      attempts: 3,
-      backoff: { type: 'exponential', delay: 1_000 },
-    },
-  }));
-  await notificationQueue.addBulk(jobs);
-};
-
-// Dead letter inspection API
-app.get('/admin/jobs/failed', authenticate, authorize('admin'), async (req, res) => {
-  const failed = await emailQueue.getFailed(0, 50);
-  res.json({ count: failed.length, jobs: failed.map(j => ({ id: j.id, data: j.data, reason: j.failedReason, attempts: j.attemptsMade })) });
-});
-
-app.post('/admin/jobs/:id/retry', authenticate, authorize('admin'), async (req, res) => {
-  const job = await emailQueue.getJob(req.params.id);
-  if (!job) return res.status(404).json({ error: { code: 'NOT_FOUND' } });
-  await job.retry();
-  res.json({ status: 'retried' });
-});
-
-// Celery equivalent (Python) — minimal pattern
-# tasks.py
-from celery import Celery
-from celery.utils.log import get_task_logger
-
-app = Celery('tasks', broker=REDIS_URL, backend=REDIS_URL)
-app.conf.task_acks_late = True  # at-least-once delivery
-app.conf.task_reject_on_worker_lost = True  # requeue on worker crash
-logger = get_task_logger(__name__)
-
-@app.task(bind=True, max_retries=5, default_retry_delay=60)
-def send_email(self, to: str, template: str, data: dict) -> dict:
-    try:
-        result = email_service.send(to=to, template=template, data=data)
-        return {'sent_at': result.timestamp.isoformat()}
-    except TransientError as exc:
-        raise self.retry(exc=exc, countdown=2 ** self.request.retries * 60)
-    except PermanentError as exc:
-        logger.error(f"Permanent failure for {to}: {exc}")
-        raise  # no retry — goes to dead letter
-```
+---
+name: "background-jobs"
+pack: "@rune/backend"
+description: "Queue-based async processing — BullMQ (Node.js), job patterns, retry strategies, idempotency, dead letter queues, monitoring."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# background-jobs
+
+Queue-based async processing — BullMQ (Node.js), job patterns, retry strategies, idempotency, dead letter queues, monitoring.
+
+#### Workflow
+
+**Step 1 — Identify async operations**
+Scan route handlers and service functions for operations that: (a) take > 200ms (PDF generation, image resizing, report aggregation), (b) are non-user-facing (email sending, webhook delivery, analytics events), (c) can tolerate eventual consistency (data sync, cache warming, notification dispatch). Flag these as candidates for background jobs. Output a classification: fire-and-forget vs delayed vs scheduled (cron) vs fan-out.
+
+**Step 2 — Choose queue system**
+Node.js: BullMQ (Redis-backed, TypeScript-native, built-in retry/delay/priority/rate-limiting — recommended). Python: Celery + Redis/RabbitMQ broker (mature, distributed workers, beat scheduler for cron). For very simple use cases (single server, low volume): `node-cron` + in-process worker. Avoid in-process queues in production — they die with the process and lose jobs.
+
+**Step 3 — Implement job with retry strategy**
+Emit job producer (enqueue) and worker (processor) as separate files. Retry strategy: exponential backoff with jitter (`attempts: 5, backoff: { type: 'exponential', delay: 1000 }`). Idempotency: every job MUST have an idempotency key — use a deterministic ID from the operation (e.g., `email:welcome:${userId}` not a random UUID). This ensures duplicate enqueues (from retries, double-clicks) process exactly once. Dead letter queue: after max retries, move job to a `{queue-name}:failed` queue for inspection and manual replay — never silently drop.
+
+**Step 4 — Add monitoring and alerting**
+BullMQ Board or Bull Dashboard for visual queue monitoring. Emit metrics: queue depth (jobs waiting), processing rate (jobs/sec), failure rate (failed/total). Alert when: queue depth > threshold (workers not keeping up), failure rate > 5% (systematic error in processor), job age > expected TTL (stuck job). Use BullMQ events (`queue.on('failed', ...)`) to push metrics to Prometheus or Datadog.
+
+**Step 5 — Handle dead letters**
+Emit dead letter inspection endpoint: list failed jobs with error reason, retry count, and last error. Emit replay endpoint: re-enqueue a specific failed job with a fresh retry budget. Purge endpoint: clear dead letter queue after investigation. Add alerting on dead letter queue depth > 0 for critical job types (payment processing, compliance logging).
+
+#### Example
+
+```typescript
+// BullMQ setup with TypeScript — producer + worker
+import { Queue, Worker, Job } from 'bullmq';
+
+const connection = { host: REDIS_HOST, port: 6379 };
+
+// Job type definitions
+interface EmailJob { to: string; template: string; data: Record<string, unknown> }
+interface PdfJob { reportId: string; userId: string; format: 'pdf' | 'xlsx' }
+
+// Producers
+export const emailQueue = new Queue<EmailJob>('email', { connection });
+export const pdfQueue = new Queue<PdfJob>('pdf', { connection });
+
+// Enqueue with idempotency key (jobId = idempotent identifier)
+export const sendWelcomeEmail = (userId: string, email: string) =>
+  emailQueue.add('welcome', { to: email, template: 'welcome', data: { userId } }, {
+    jobId: `email:welcome:${userId}`, // prevents duplicate welcome emails
+    attempts: 3,
+    backoff: { type: 'exponential', delay: 2_000 },
+    removeOnComplete: { count: 1000 }, // keep last 1000 completed for audit
+    removeOnFail: false, // keep all failed for dead letter review
+  });
+
+// Scheduled/delayed job
+export const sendReminderEmail = (userId: string, delayMs: number) =>
+  emailQueue.add('reminder', { to: userId, template: 'reminder', data: {} }, {
+    delay: delayMs,
+    attempts: 5,
+    backoff: { type: 'exponential', delay: 5_000 },
+  });
+
+// Worker processor with error handling
+const emailWorker = new Worker<EmailJob>('email', async (job: Job<EmailJob>) => {
+  const { to, template, data } = job.data;
+  // Validate job data — serialized payload may be stale
+  if (!to || !template) throw new Error(`Invalid job payload: ${JSON.stringify(job.data)}`);
+  await emailService.send({ to, template, data });
+  // Return value is stored in job.returnvalue for audit
+  return { sentAt: new Date().toISOString() };
+}, {
+  connection,
+  concurrency: 10,           // process up to 10 emails in parallel
+  limiter: { max: 100, duration: 60_000 }, // rate limit: 100/min
+});
+
+emailWorker.on('failed', async (job, err) => {
+  logger.error({ jobId: job?.id, queue: 'email', error: err.message, attempts: job?.attemptsMade });
+  if (job?.attemptsMade >= job?.opts.attempts!) {
+    // max retries exhausted → alert
+    await alerting.notify(`Dead letter: email job ${job.id} failed after ${job.attemptsMade} attempts`);
+  }
+});
+
+// Fan-out pattern: one job enqueues many children
+const fanOutNotification = async (eventId: string, userIds: string[]) => {
+  const jobs = userIds.map(userId => ({
+    name: 'notify',
+    data: { userId, eventId },
+    opts: {
+      jobId: `notify:${eventId}:${userId}`,
+      attempts: 3,
+      backoff: { type: 'exponential', delay: 1_000 },
+    },
+  }));
+  await notificationQueue.addBulk(jobs);
+};
+
+// Dead letter inspection API
+app.get('/admin/jobs/failed', authenticate, authorize('admin'), async (req, res) => {
+  const failed = await emailQueue.getFailed(0, 50);
+  res.json({ count: failed.length, jobs: failed.map(j => ({ id: j.id, data: j.data, reason: j.failedReason, attempts: j.attemptsMade })) });
+});
+
+app.post('/admin/jobs/:id/retry', authenticate, authorize('admin'), async (req, res) => {
+  const job = await emailQueue.getJob(req.params.id);
+  if (!job) return res.status(404).json({ error: { code: 'NOT_FOUND' } });
+  await job.retry();
+  res.json({ status: 'retried' });
+});
+
+// Celery equivalent (Python) — minimal pattern
+# tasks.py
+from celery import Celery
+from celery.utils.log import get_task_logger
+
+app = Celery('tasks', broker=REDIS_URL, backend=REDIS_URL)
+app.conf.task_acks_late = True  # at-least-once delivery
+app.conf.task_reject_on_worker_lost = True  # requeue on worker crash
+logger = get_task_logger(__name__)
+
+@app.task(bind=True, max_retries=5, default_retry_delay=60)
+def send_email(self, to: str, template: str, data: dict) -> dict:
+    try:
+        result = email_service.send(to=to, template=template, data=data)
+        return {'sent_at': result.timestamp.isoformat()}
+    except TransientError as exc:
+        raise self.retry(exc=exc, countdown=2 ** self.request.retries * 60)
+    except PermanentError as exc:
+        logger.error(f"Permanent failure for {to}: {exc}")
+        raise  # no retry — goes to dead letter
+```

package/extensions/backend/skills/caching-patterns.md

@@ -1,108 +1,108 @@
----
-name: "caching-patterns"
-pack: "@rune/backend"
-description: "Caching strategies for backend applications — in-memory LRU, Redis distributed cache, CDN/edge cache, browser cache headers, invalidation, and stampede prevention."
-model: sonnet
-tools: [Read, Edit, Write, Grep, Glob, Bash]
----
-
-# caching-patterns
-
-Caching strategies for backend applications — in-memory LRU, Redis distributed cache, CDN/edge cache, browser cache headers, invalidation, and stampede prevention.
-
-#### Workflow
-
-**Step 1 — Identify cacheable endpoints**
-Scan routes for: (a) read-heavy endpoints called frequently with the same inputs (user profile, product catalog, config lookups), (b) expensive computations (aggregations, report generation), (c) external API calls that are rate-limited or slow. Flag endpoints that mutate state as NOT cacheable at the response level (cache the data layer instead). Output a cacheable/non-cacheable classification per endpoint.
-
-**Step 2 — Select cache layer**
-Choose layer based on access pattern: in-memory (node-cache, LRU-cache) for single-process data with sub-millisecond access and low cardinality; Redis for distributed cache shared across multiple server instances or processes; CDN (Cloudflare, Fastly) for public, user-agnostic responses (marketing pages, public API responses); browser cache (`Cache-Control` headers) for static assets and safe GET responses. Hybrid: in-memory L1 + Redis L2 for hot-path data that justifies two-layer lookup.
-
-**Step 3 — Implement cache pattern**
-Cache-aside (most common): application checks cache first, on miss fetches from DB, writes to cache. Write-through: write to cache and DB together on every write (cache always warm, higher write latency). Write-behind (write-back): write to cache immediately, flush to DB asynchronously (lowest write latency, risk of data loss on crash). Read-through: cache sits in front of DB, handles miss transparently (simpler app code, less control). For most web APIs: cache-aside for reads + TTL-based expiry is the correct default.
-
-**Step 4 — Add invalidation strategy**
-TTL-based: set appropriate TTL per data type (user session: match auth token TTL; product catalog: 5–15min; config: 1hr). Event-driven: on mutation, publish event to Redis pub/sub, cache subscribers delete affected keys. Versioned keys: `cache:user:v3:{id}` — bump version in config to invalidate all users atomically. Tag-based: associate keys with tags (`tag:user:123`), delete all keys for a tag on mutation. Stale-while-revalidate: serve stale data immediately, refresh in background — valid for data where slight staleness is acceptable (leaderboards, stats). Emit invalidation hook alongside every write operation.
-
-**Step 5 — Monitor hit/miss ratio**
-Instrument cache calls to emit metrics: hit count, miss count, eviction count, cache size. Redis provides `INFO stats` — parse `keyspace_hits` and `keyspace_misses`. Target hit ratio > 80% for hot-path caches; < 50% indicates wrong key granularity or TTL too short. Alert on sudden hit ratio drop (invalidation bug) or memory > 80% of `maxmemory` (eviction risk).
-
-#### Example
-
-```typescript
-// Redis cache-aside middleware for Express/Fastify
-import { Redis } from 'ioredis';
-const redis = new Redis(REDIS_URL);
-
-const cacheMiddleware = (ttlSeconds: number, keyFn?: (req) => string) =>
-  async (req, res, next) => {
-    const key = keyFn ? keyFn(req) : `cache:${req.method}:${req.originalUrl}`;
-    const cached = await redis.get(key);
-    if (cached) {
-      res.setHeader('X-Cache', 'HIT');
-      return res.json(JSON.parse(cached));
-    }
-    const originalJson = res.json.bind(res);
-    res.json = (data) => {
-      // Only cache successful responses
-      if (res.statusCode < 400) redis.setex(key, ttlSeconds, JSON.stringify(data));
-      res.setHeader('X-Cache', 'MISS');
-      return originalJson(data);
-    };
-    next();
-  };
-
-// Usage: cache product list for 5 minutes
-app.get('/products', cacheMiddleware(300), async (req, res) => { /* handler */ });
-
-// Cache stampede prevention: mutex lock on cache miss
-const getWithLock = async <T>(key: string, fetchFn: () => Promise<T>, ttl: number): Promise<T> => {
-  const cached = await redis.get(key);
-  if (cached) return JSON.parse(cached);
-
-  const lockKey = `lock:${key}`;
-  const lock = await redis.set(lockKey, '1', 'EX', 10, 'NX'); // 10s lock
-  if (!lock) {
-    // Another process is fetching — wait briefly and retry
-    await new Promise(r => setTimeout(r, 100));
-    return getWithLock(key, fetchFn, ttl); // retry (max ~10 cycles within 10s lock)
-  }
-
-  try {
-    const data = await fetchFn();
-    await redis.setex(key, ttl, JSON.stringify(data));
-    return data;
-  } finally {
-    await redis.del(lockKey);
-  }
-};
-
-// Event-driven invalidation with Redis pub/sub
-const invalidateOnMutation = async (userId: string) => {
-  await redis.del(`cache:user:${userId}`);
-  await redis.publish('cache:invalidate', JSON.stringify({ type: 'user', id: userId }));
-};
-
-// Cache-Control headers for browser/CDN caching
-app.get('/products', (req, res) => {
-  res.setHeader('Cache-Control', 'public, max-age=300, stale-while-revalidate=60');
-  // ^ CDN caches 5min, serves stale for extra 60s while revalidating in background
-  res.json(products);
-});
-
-app.get('/user/profile', authenticate, (req, res) => {
-  res.setHeader('Cache-Control', 'private, max-age=60'); // user-specific, browser only
-  res.json(profile);
-});
-
-// In-memory LRU cache for single-process hot data
-import LRU from 'lru-cache';
-const configCache = new LRU<string, unknown>({ max: 500, ttl: 60_000 }); // 500 entries, 1min TTL
-
-const getConfig = async (key: string) => {
-  if (configCache.has(key)) return configCache.get(key);
-  const value = await db.config.findUnique({ where: { key } });
-  configCache.set(key, value);
-  return value;
-};
-```
+---
+name: "caching-patterns"
+pack: "@rune/backend"
+description: "Caching strategies for backend applications — in-memory LRU, Redis distributed cache, CDN/edge cache, browser cache headers, invalidation, and stampede prevention."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# caching-patterns
+
+Caching strategies for backend applications — in-memory LRU, Redis distributed cache, CDN/edge cache, browser cache headers, invalidation, and stampede prevention.
+
+#### Workflow
+
+**Step 1 — Identify cacheable endpoints**
+Scan routes for: (a) read-heavy endpoints called frequently with the same inputs (user profile, product catalog, config lookups), (b) expensive computations (aggregations, report generation), (c) external API calls that are rate-limited or slow. Flag endpoints that mutate state as NOT cacheable at the response level (cache the data layer instead). Output a cacheable/non-cacheable classification per endpoint.
+
+**Step 2 — Select cache layer**
+Choose layer based on access pattern: in-memory (node-cache, LRU-cache) for single-process data with sub-millisecond access and low cardinality; Redis for distributed cache shared across multiple server instances or processes; CDN (Cloudflare, Fastly) for public, user-agnostic responses (marketing pages, public API responses); browser cache (`Cache-Control` headers) for static assets and safe GET responses. Hybrid: in-memory L1 + Redis L2 for hot-path data that justifies two-layer lookup.
+
+**Step 3 — Implement cache pattern**
+Cache-aside (most common): application checks cache first, on miss fetches from DB, writes to cache. Write-through: write to cache and DB together on every write (cache always warm, higher write latency). Write-behind (write-back): write to cache immediately, flush to DB asynchronously (lowest write latency, risk of data loss on crash). Read-through: cache sits in front of DB, handles miss transparently (simpler app code, less control). For most web APIs: cache-aside for reads + TTL-based expiry is the correct default.
+
+**Step 4 — Add invalidation strategy**
+TTL-based: set appropriate TTL per data type (user session: match auth token TTL; product catalog: 5–15min; config: 1hr). Event-driven: on mutation, publish event to Redis pub/sub, cache subscribers delete affected keys. Versioned keys: `cache:user:v3:{id}` — bump version in config to invalidate all users atomically. Tag-based: associate keys with tags (`tag:user:123`), delete all keys for a tag on mutation. Stale-while-revalidate: serve stale data immediately, refresh in background — valid for data where slight staleness is acceptable (leaderboards, stats). Emit invalidation hook alongside every write operation.
+
+**Step 5 — Monitor hit/miss ratio**
+Instrument cache calls to emit metrics: hit count, miss count, eviction count, cache size. Redis provides `INFO stats` — parse `keyspace_hits` and `keyspace_misses`. Target hit ratio > 80% for hot-path caches; < 50% indicates wrong key granularity or TTL too short. Alert on sudden hit ratio drop (invalidation bug) or memory > 80% of `maxmemory` (eviction risk).
+
+#### Example
+
+```typescript
+// Redis cache-aside middleware for Express/Fastify
+import { Redis } from 'ioredis';
+const redis = new Redis(REDIS_URL);
+
+const cacheMiddleware = (ttlSeconds: number, keyFn?: (req) => string) =>
+  async (req, res, next) => {
+    const key = keyFn ? keyFn(req) : `cache:${req.method}:${req.originalUrl}`;
+    const cached = await redis.get(key);
+    if (cached) {
+      res.setHeader('X-Cache', 'HIT');
+      return res.json(JSON.parse(cached));
+    }
+    const originalJson = res.json.bind(res);
+    res.json = (data) => {
+      // Only cache successful responses
+      if (res.statusCode < 400) redis.setex(key, ttlSeconds, JSON.stringify(data));
+      res.setHeader('X-Cache', 'MISS');
+      return originalJson(data);
+    };
+    next();
+  };
+
+// Usage: cache product list for 5 minutes
+app.get('/products', cacheMiddleware(300), async (req, res) => { /* handler */ });
+
+// Cache stampede prevention: mutex lock on cache miss
+const getWithLock = async <T>(key: string, fetchFn: () => Promise<T>, ttl: number): Promise<T> => {
+  const cached = await redis.get(key);
+  if (cached) return JSON.parse(cached);
+
+  const lockKey = `lock:${key}`;
+  const lock = await redis.set(lockKey, '1', 'EX', 10, 'NX'); // 10s lock
+  if (!lock) {
+    // Another process is fetching — wait briefly and retry
+    await new Promise(r => setTimeout(r, 100));
+    return getWithLock(key, fetchFn, ttl); // retry (max ~10 cycles within 10s lock)
+  }
+
+  try {
+    const data = await fetchFn();
+    await redis.setex(key, ttl, JSON.stringify(data));
+    return data;
+  } finally {
+    await redis.del(lockKey);
+  }
+};
+
+// Event-driven invalidation with Redis pub/sub
+const invalidateOnMutation = async (userId: string) => {
+  await redis.del(`cache:user:${userId}`);
+  await redis.publish('cache:invalidate', JSON.stringify({ type: 'user', id: userId }));
+};
+
+// Cache-Control headers for browser/CDN caching
+app.get('/products', (req, res) => {
+  res.setHeader('Cache-Control', 'public, max-age=300, stale-while-revalidate=60');
+  // ^ CDN caches 5min, serves stale for extra 60s while revalidating in background
+  res.json(products);
+});
+
+app.get('/user/profile', authenticate, (req, res) => {
+  res.setHeader('Cache-Control', 'private, max-age=60'); // user-specific, browser only
+  res.json(profile);
+});
+
+// In-memory LRU cache for single-process hot data
+import LRU from 'lru-cache';
+const configCache = new LRU<string, unknown>({ max: 500, ttl: 60_000 }); // 500 entries, 1min TTL
+
+const getConfig = async (key: string) => {
+  if (configCache.has(key)) return configCache.get(key);
+  const value = await db.config.findUnique({ where: { key } });
+  configCache.set(key, value);
+  return value;
+};
+```