@rune-kit/rune 2.2.0 → 2.2.1

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

@@ -0,0 +1,84 @@
+---
+name: "api-patterns"
+pack: "@rune/backend"
+description: "RESTful and GraphQL API design patterns — resource naming, pagination, filtering, error responses, versioning, rate limiting, OpenAPI generation."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# api-patterns
+
+RESTful and GraphQL API design patterns — resource naming, pagination, filtering, error responses, versioning, rate limiting, OpenAPI generation.
+
+#### Workflow
+
+**Step 1 — Detect API surface**
+Use Grep to find route definitions (`app.get`, `app.post`, `router.`, `@Get()`, `@Post()`, `@Query`, `@Mutation`). Read each route file to inventory: endpoint paths, HTTP methods, response shapes, error handling approach.
+
+**Step 2 — Audit naming and structure**
+Check each endpoint against REST conventions: plural nouns for collections (`/users` not `/getUsers`), nested resources for relationships (`/users/:id/posts`), query params for filtering (`?status=active`), consistent error envelope. Flag violations with specific fix for each.
+
+**Step 3 — Add missing pagination and filtering**
+For list endpoints returning unbounded arrays, emit cursor-based or offset pagination. For endpoints with no filtering, add query param parsing with Zod/Joi validation. Emit the middleware or decorator that enforces the pattern.
+
+**Step 4 — API versioning strategy**
+Choose versioning approach based on project context: URL path (`/v2/users`) for public APIs with long deprecation windows; `Accept-Version: 2` header for internal APIs needing cleaner URLs; query param (`?version=2`) for simple cases. Emit version routing middleware and a deprecation warning header (`Deprecation: true, Sunset: <date>`) on v1 routes. Document migration path in the route file as a comment.
+
+**Step 5 — OpenAPI/Swagger and GraphQL patterns**
+For REST: emit OpenAPI 3.1 schema from route definitions using tsoa decorators (TypeScript), Fastify's built-in JSON Schema (`schema: { body, querystring, response }`), or NestJS `@ApiProperty`. For GraphQL: if schema-first, validate resolvers match schema types; if code-first (NestJS), check `@ObjectType` / `@Field` decorators. Add DataLoader to any resolver with a per-request DB call to prevent N+1 at the GraphQL layer. Emit subscription pattern (WebSocket transport) for real-time fields.
+
+#### Example
+
+```typescript
+// BEFORE: inconsistent naming, no pagination, bare error
+app.get('/getUsers', async (req, res) => {
+  const users = await db.query('SELECT * FROM users');
+  res.json(users);
+});
+
+// AFTER: REST naming, cursor pagination, error envelope, Zod validation
+const paginationSchema = z.object({
+  query: z.object({
+    cursor: z.string().optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(20),
+    status: z.enum(['active', 'inactive']).optional(),
+  }),
+});
+
+app.get('/users', validate(paginationSchema), async (req, res) => {
+  const { cursor, limit, status } = req.query;
+  const users = await userRepo.findMany({ cursor, limit: limit + 1, status });
+  const hasNext = users.length > limit;
+  res.json({
+    data: users.slice(0, limit),
+    pagination: { next_cursor: hasNext ? users[limit - 1].id : null, has_more: hasNext },
+  });
+});
+
+// Rate limiting: sliding window with Redis (atomic, no race condition)
+const rateLimitMiddleware = async (req, res, next) => {
+  const key = `rl:${req.ip}:${Math.floor(Date.now() / 60_000)}`; // 1-minute window
+  const multi = redis.multi();
+  multi.incr(key);
+  multi.expire(key, 60);
+  const [count] = await multi.exec();
+  if (count > 100) return res.status(429).json({ error: { code: 'RATE_LIMITED', message: 'Too many requests' } });
+  res.setHeader('X-RateLimit-Remaining', 100 - count);
+  next();
+};
+
+// Fastify: built-in schema validation + OpenAPI generation
+fastify.get('/users/:id', {
+  schema: {
+    params: { type: 'object', properties: { id: { type: 'string', format: 'uuid' } }, required: ['id'] },
+    response: { 200: UserSchema, 404: ErrorSchema },
+  },
+}, async (req, reply) => { /* handler */ });
+
+// GraphQL: DataLoader prevents N+1 in resolvers
+const userLoader = new DataLoader(async (userIds: string[]) => {
+  const users = await prisma.user.findMany({ where: { id: { in: userIds } } });
+  return userIds.map(id => users.find(u => u.id === id) ?? new Error(`User ${id} not found`));
+});
+// In resolver: return userLoader.load(post.authorId) — batches all loads per request
+```

package/extensions/backend/skills/async-pipeline.md

@@ -0,0 +1,193 @@
+---
+name: "async-pipeline"
+pack: "@rune/backend"
+description: "Multi-stage async processing pipelines with waterfall engine selection, progress streaming, and credit-based billing. Patterns for building services that process data through multiple fallback strategies with real-time status updates."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# async-pipeline
+
+Multi-stage async processing pipelines with waterfall engine selection, progress streaming, and credit-based billing. Patterns for building services that process data through multiple fallback strategies with real-time status updates.
+
+#### Workflow
+
+**Step 1 — Design engine waterfall**
+Multiple processing engines ranked by quality and cost:
+```typescript
+interface ProcessingEngine {
+  name: string;
+  quality: number;       // higher = preferred
+  costMultiplier: number; // credit cost factor
+  execute: (input: Input) => Promise<Result>;
+  canHandle: (input: Input) => boolean;
+}
+
+// Engines race with staggered delays — first valid result wins
+async function waterfallExecute(
+  engines: ProcessingEngine[],
+  input: Input,
+  staggerDelayMs: number = 500
+): Promise<{ result: Result; engine: string }> {
+  const sorted = engines
+    .filter(e => e.canHandle(input))
+    .sort((a, b) => b.quality - a.quality);
+
+  const controller = new AbortController();
+
+  const races = sorted.map((engine, i) =>
+    new Promise<{ result: Result; engine: string }>(async (resolve, reject) => {
+      // Stagger start: engine 0 starts immediately, engine 1 after 500ms, etc.
+      if (i > 0) await delay(i * staggerDelayMs);
+      if (controller.signal.aborted) return reject(new Error('aborted'));
+
+      try {
+        const result = await engine.execute(input);
+        if (isValid(result)) {
+          controller.abort();  // cancel slower engines
+          resolve({ result, engine: engine.name });
+        } else {
+          reject(new Error(`${engine.name}: invalid result`));
+        }
+      } catch (err) {
+        reject(err);
+      }
+    })
+  );
+
+  return Promise.any(races);
+}
+```
+
+**Step 2 — Implement transform pipeline**
+Chain transforms that process data sequentially:
+```typescript
+type Transformer<T> = (data: T, context: PipelineContext) => Promise<T>;
+
+async function runPipeline<T>(
+  data: T,
+  transformers: Transformer<T>[],
+  onProgress: (stage: string, pct: number) => void
+): Promise<T> {
+  let current = data;
+  for (let i = 0; i < transformers.length; i++) {
+    onProgress(transformers[i].name, (i / transformers.length) * 100);
+    current = await transformers[i](current, context);
+  }
+  onProgress('complete', 100);
+  return current;
+}
+```
+
+**Step 3 — Stream progress via SSE**
+Real-time progress from worker to client:
+```typescript
+// Worker side: publish progress to Redis pub/sub
+async function publishProgress(jobId: string, stage: string, pct: number) {
+  await redis.publish(`job:${jobId}:progress`, JSON.stringify({ stage, pct, ts: Date.now() }));
+}
+
+// API side: SSE endpoint
+app.get('/jobs/:id/progress', async (req, res) => {
+  res.setHeader('Content-Type', 'text/event-stream');
+  res.setHeader('Cache-Control', 'no-cache');
+  res.setHeader('Connection', 'keep-alive');
+
+  const subscriber = redis.duplicate();
+  await subscriber.subscribe(`job:${req.params.id}:progress`);
+
+  subscriber.on('message', (_channel, message) => {
+    res.write(`data: ${message}\n\n`);
+  });
+
+  req.on('close', () => subscriber.unsubscribe());
+});
+```
+
+**Step 4 — Two-tier concurrency control**
+```typescript
+// Team-level: limit concurrent jobs per team
+async function canEnqueue(teamId: string): Promise<boolean> {
+  const active = await redis.zcard(`team:${teamId}:active`);
+  const limit = await getTeamConcurrencyLimit(teamId);
+  return active < limit;
+}
+
+// Job-level: track active jobs with TTL (auto-cleanup on crash)
+async function markActive(teamId: string, jobId: string) {
+  await redis.zadd(`team:${teamId}:active`, Date.now(), jobId);
+  await redis.expire(`team:${teamId}:active`, 3600);  // 1h TTL safety net
+}
+
+async function markComplete(teamId: string, jobId: string) {
+  await redis.zrem(`team:${teamId}:active`, jobId);
+}
+```
+
+**Step 5 — Dynamic credit billing**
+```typescript
+interface CreditCost {
+  base: number;
+  engineMultiplier: number;   // stealth proxy = 4x
+  formatMultiplier: number;   // JSON extraction = 5x
+  extras: number;             // per-page for PDFs, per-territory for pricing
+}
+
+function calculateCredits(job: CompletedJob): number {
+  let cost = job.cost.base;
+  cost *= job.cost.engineMultiplier;
+  cost *= job.cost.formatMultiplier;
+  cost += job.cost.extras;
+  return Math.ceil(cost);
+}
+```
+
+**Step 6 — Dead letter queue with retry classification**
+```typescript
+interface FailedJob {
+  id: string;
+  error: string;
+  errorCode: 'TRANSIENT' | 'PERMANENT' | 'TIMEOUT' | 'RATE_LIMITED';
+  attempts: number;
+  stageTiming: Record<string, number>;  // per-stage perf data
+}
+
+// Retry only transient failures; permanent goes to dead letter
+function shouldRetry(job: FailedJob): boolean {
+  if (job.errorCode === 'PERMANENT') return false;
+  if (job.attempts >= 3) return false;
+  return true;
+}
+```
+
+#### Example
+
+```typescript
+// Complete async pipeline for document processing
+const docPipeline = createPipeline({
+  engines: [
+    { name: 'native-parser', quality: 100, costMultiplier: 1, execute: nativeParse },
+    { name: 'llm-extraction', quality: 80, costMultiplier: 5, execute: llmExtract },
+    { name: 'ocr-fallback', quality: 50, costMultiplier: 3, execute: ocrExtract },
+  ],
+  transforms: [
+    cleanHTML,
+    extractMetadata,
+    convertToMarkdown,
+    generateSummary,
+    indexForSearch,
+  ],
+  concurrency: { perTeam: 10, perJob: 3 },
+  billing: { base: 1, jsonFormat: 5 },
+  deadLetter: { maxRetries: 3, alertThreshold: 10 },
+});
+
+// Enqueue
+const jobId = await docPipeline.enqueue(teamId, { url, format: 'json' });
+
+// Stream progress
+const progress = docPipeline.streamProgress(jobId);
+for await (const update of progress) {
+  console.log(`${update.stage}: ${update.pct}%`);
+}
+```

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

@@ -0,0 +1,97 @@
+---
+name: "auth-patterns"
+pack: "@rune/backend"
+description: "Authentication and authorization patterns — JWT, OAuth 2.0 / OIDC, passkeys/WebAuthn, session management, RBAC, API key management, MFA flows."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# auth-patterns
+
+Authentication and authorization patterns — JWT, OAuth 2.0 / OIDC, passkeys/WebAuthn, session management, RBAC, API key management, MFA flows.
+
+#### Workflow
+
+**Step 1 — Detect auth implementation**
+Use Grep to find auth-related code: `jwt.sign`, `jwt.verify`, `bcrypt`, `passport`, `next-auth`, `lucia`, `cookie`, `session`, `Bearer`, `x-api-key`, `WebAuthn`, `passkey`. Read auth middleware and login/register handlers to understand the current approach.
+
+**Step 2 — Audit security posture**
+Check for: tokens stored in localStorage (XSS risk → use httpOnly cookies), missing refresh token rotation, JWT without expiry, password hashing without salt rounds check, missing CSRF protection on cookie-based auth, hardcoded secrets. Flag each with severity and specific fix.
+
+**Step 3 — Emit secure auth flow**
+Based on detected framework (Express, Fastify, Next.js, etc.), emit the corrected auth flow: access token (short-lived, 15min) + refresh token (httpOnly cookie, 7d, rotation on use), proper password hashing (bcrypt rounds ≥ 12), RBAC middleware with role hierarchy.
+
+**Step 4 — OAuth 2.0 / OIDC integration**
+Emit OAuth 2.0 authorization code flow with PKCE (required for public clients). Support Google, GitHub, or custom OIDC provider. Key points: validate `state` parameter to prevent CSRF, validate `id_token` signature and `aud`/`iss` claims, exchange code server-side (never client-side), store provider `sub` as stable user identifier. Use `openid-client` (Node.js) or `authlib` (Python) — never hand-roll token exchange.
+
+**Step 5 — API key management and passkeys**
+For API keys: generate with `crypto.randomBytes(32).toString('base64url')`, store hashed (`sha256` is sufficient — no need for bcrypt, keys are long), never store plaintext after initial display. Add scopes (read-only vs read-write), per-key rate limits, and rotation endpoint. For passkeys/WebAuthn: emit registration and authentication ceremonies using `@simplewebauthn/server`. WebAuthn is the correct long-term replacement for passwords — emit as opt-in upgrade path. Stateless vs stateful tradeoff: JWT = stateless, easy to scale horizontally, hard to revoke; sessions = stateful, easy to revoke, requires sticky sessions or shared store (Redis). Recommend JWT + token blacklist on logout for most cases; sessions for admin panels where immediate revocation matters.
+
+#### Example
+
+```typescript
+// BEFORE: JWT in localStorage, no refresh, no expiry
+const token = jwt.sign({ userId: user.id }, SECRET);
+res.json({ token });
+
+// AFTER: short-lived access + httpOnly refresh cookie with rotation
+const accessToken = jwt.sign(
+  { sub: user.id, role: user.role },
+  ACCESS_SECRET,
+  { expiresIn: '15m' }
+);
+const refreshToken = jwt.sign(
+  { sub: user.id, jti: crypto.randomUUID() },
+  REFRESH_SECRET,
+  { expiresIn: '7d' }
+);
+await tokenStore.save(refreshToken, user.id); // rotation tracking — invalidate old on reuse
+
+res.cookie('refresh_token', refreshToken, {
+  httpOnly: true, secure: true, sameSite: 'strict',
+  maxAge: 7 * 24 * 60 * 60 * 1000,
+});
+res.json({ access_token: accessToken, expires_in: 900 });
+
+// API key management
+const generateApiKey = async (userId: string, scopes: string[]): Promise<{ key: string; keyId: string }> => {
+  const rawKey = `rk_${crypto.randomBytes(32).toString('base64url')}`;
+  const keyHash = crypto.createHash('sha256').update(rawKey).digest('hex');
+  const keyId = crypto.randomUUID();
+  await db.apiKey.create({ data: { id: keyId, userId, keyHash, scopes, createdAt: new Date() } });
+  return { key: rawKey, keyId }; // rawKey shown ONCE — never stored plaintext
+};
+
+const authenticateApiKey = async (req, res, next) => {
+  const raw = req.headers['x-api-key'];
+  if (!raw) return next(); // fallback to JWT auth
+  const hash = crypto.createHash('sha256').update(raw).digest('hex');
+  const apiKey = await db.apiKey.findUnique({ where: { keyHash: hash } });
+  if (!apiKey || apiKey.revokedAt) return res.status(401).json({ error: { code: 'INVALID_API_KEY' } });
+  req.user = { id: apiKey.userId, scopes: apiKey.scopes };
+  next();
+};
+
+// OAuth 2.0 with PKCE (using openid-client)
+import { generators, Issuer } from 'openid-client';
+
+const googleIssuer = await Issuer.discover('https://accounts.google.com');
+const client = new googleIssuer.Client({ client_id: GOOGLE_CLIENT_ID, redirect_uris: [CALLBACK_URL], response_types: ['code'] });
+
+app.get('/auth/google', (req, res) => {
+  const codeVerifier = generators.codeVerifier();
+  const codeChallenge = generators.codeChallenge(codeVerifier);
+  const state = generators.state();
+  req.session.codeVerifier = codeVerifier;
+  req.session.state = state;
+  res.redirect(client.authorizationUrl({ scope: 'openid email profile', code_challenge: codeChallenge, code_challenge_method: 'S256', state }));
+});
+
+app.get('/auth/google/callback', async (req, res) => {
+  const params = client.callbackParams(req);
+  const tokens = await client.callback(CALLBACK_URL, params, { code_verifier: req.session.codeVerifier, state: req.session.state });
+  const claims = tokens.claims(); // validated: iss, aud, exp
+  const user = await userRepo.upsertByProvider('google', claims.sub, claims.email);
+  // issue internal JWT...
+});
+```

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

@@ -0,0 +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
+```

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

@@ -0,0 +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;
+};
+```