Merge pull request #119 from zeekman/feat/redis-bullmq

feat(redis-bullmq): Redis module, BullMQ queues, cache helpers, metrics

Author: jhayniffy

.env.example

@@ -0,0 +1,14 @@
+# Copy this file to .env and fill in values.
+# .env is gitignored — never commit secrets.
+
+# ── Redis ─────────────────────────────────────────────────────────────────────
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+# Minimum 32 random characters in production
+REDIS_PASSWORD=devpassword
+# Set to "true" and configure TLS certs for production managed Redis
+REDIS_TLS=false
+
+# ── Application ───────────────────────────────────────────────────────────────
+NODE_ENV=development
+PORT=3000

.github/workflows/ci.yml

@@ -54,16 +54,32 @@ jobs:
     defaults:
       run:
         working-directory: backend
+
+    services:
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 5s
+          --health-timeout 3s
+          --health-retries 5
+          --health-start-period 5s
+
+    env:
+      REDIS_HOST: 127.0.0.1
+      REDIS_PORT: 6379
+      NODE_ENV: test
+
     steps:
       - uses: actions/checkout@v4
 
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-          cache: npm
-          cache-dependency-path: backend/package-lock.json
 
-      - run: npm ci
+      - run: npm install
       - run: npm run lint
       - run: npm run build
       - run: npm test

backend/REDIS.md

@@ -0,0 +1,154 @@
+# Redis Architecture — NiffyInsure Backend
+
+## Overview
+
+Redis underpins three operational concerns:
+
+| Concern | Implementation | Fail behaviour |
+|---------|---------------|----------------|
+| Job queues | BullMQ (`claim-events`, `claim-payouts`) | **Fail closed** — job not enqueued returns error |
+| Wallet-auth nonces | `setNonce` / `consumeNonce` in `cache.ts` | **Fail closed** — auth rejected if Redis is down |
+| Rate limiting | `incrementRateLimit` in `cache.ts` | **Fail open** — request allowed, warning logged |
+| Response caching | `cacheGet` / `cacheSet` in `cache.ts` | **Degrade gracefully** — cache miss falls through to DB |
+
+**Redis is never the authoritative store for financial data. Postgres is.**
+
+---
+
+## Key Naming Conventions
+
+All keys are prefixed with `{NODE_ENV}:niffyinsure:` (set as `keyPrefix` in ioredis).
+
+```
+{env}:niffyinsure:cache:policy:{holder}:{policy_id}   — policy read cache (30 s TTL)
+{env}:niffyinsure:cache:claim:{claim_id}               — claim read cache (10 s TTL)
+{env}:niffyinsure:nonce:{address}                      — wallet-auth nonce (5 min TTL)
+{env}:niffyinsure:ratelimit:{identifier}               — rate-limit counter (60 s TTL)
+{env}:niffyinsure:bull:claim-events:*                  — BullMQ internal keys
+{env}:niffyinsure:bull:claim-payouts:*                 — BullMQ internal keys
+```
+
+Segments:
+- `{env}` — `NODE_ENV` value (`development` | `staging` | `production`)
+- `niffyinsure` — service constant; prevents collisions in shared Redis
+- `{area}` — `cache` | `nonce` | `ratelimit` | `bull`
+- `{id}` — resource-specific identifier
+
+---
+
+## TTL Conventions
+
+Defined in `src/redis/config.ts` as `TTL` — single source of truth.
+
+| Key area | TTL | Rationale |
+|----------|-----|-----------|
+| Nonce | 5 min | Challenge must be used before wallet session expires |
+| Rate limit | 60 s | Sliding window; resets each minute |
+| Policy cache | 30 s | Stale-while-revalidate acceptable; policies change infrequently |
+| Claim cache | 10 s | Lower TTL; claim status changes on every vote |
+
+---
+
+## Queue Configuration
+
+### `claim-events`
+
+Processes Soroban contract events (ClaimFiled, VoteLogged, ClaimSettled) and writes to Postgres.
+
+| Setting | Value | Rationale |
+|---------|-------|-----------|
+| `attempts` | 5 | Retry transient failures (network, DB lock) |
+| `backoff` | exponential, 1 s base | Avoid thundering herd on DB recovery |
+| `concurrency` | 5 per worker | Balance throughput vs DB connection pool |
+| `stalledInterval` | 30 s | Redeliver if worker crashes mid-job |
+| `maxStalledCount` | 2 | Move to failed after 2 stall cycles |
+| `removeOnComplete` | last 100 | Keep for debugging without unbounded growth |
+| `removeOnFail` | last 500 | Keep for alerting and manual replay |
+
+**Idempotency requirement**: The Postgres writer must use `INSERT … ON CONFLICT DO NOTHING` keyed on `(ledger, event_index)` — stalled jobs will be redelivered.
+
+### `claim-payouts`
+
+Triggers token transfer for approved claims. Not yet implemented — queue name reserved.
+
+---
+
+## Outage Behaviour
+
+### Redis completely unavailable
+
+| Feature | Behaviour | User impact |
+|---------|-----------|-------------|
+| Wallet auth (nonce) | **Rejected** — `RedisUnavailableError` thrown | User cannot log in; must retry when Redis recovers |
+| Rate limiting | **Allowed** — warning logged | Temporary rate-limit bypass; acceptable short-term risk |
+| Policy/claim reads | **DB fallback** — cache miss | Slightly higher DB load; no user-visible impact |
+| Job enqueue | **Error returned** — caller must handle | Async processing delayed; no data loss if caller retries |
+| `/health/ready` | Returns `503 { redis: "down" }` | Load balancer can route away from degraded instance |
+
+### Redis slow (high latency)
+
+- `checkRedisHealth` has a 2 s timeout — returns `false` if exceeded.
+- Cache operations have no explicit timeout; they will block the request. Consider adding per-operation timeouts in production if Redis latency is a concern.
+
+---
+
+## Metrics and Alerting
+
+`GET /metrics/redis` returns:
+
+```json
+{
+  "connected": true,
+  "memory_used_bytes": 1234567,
+  "memory_used_mb": 1,
+  "queues": {
+    "claim-events": {
+      "waiting": 0,
+      "active": 1,
+      "completed": 42,
+      "failed": 0,
+      "delayed": 0,
+      "depth": 1
+    }
+  }
+}
+```
+
+Recommended alert thresholds:
+
+| Metric | Threshold | Action |
+|--------|-----------|--------|
+| `queues["claim-events"].depth` | > 1000 | Scale worker replicas |
+| `queues["claim-events"].failed` | > 10 | Investigate; replay failed jobs |
+| `memory_used_mb` | > 200 (of 256 limit) | Increase `maxmemory` or scale Redis |
+| `connected: false` | any | Page on-call; wallet auth is down |
+
+---
+
+## Local Development
+
+```bash
+# Start Redis
+docker compose up -d redis
+
+# Set env vars (copy from .env.example)
+cp .env.example .env
+
+# Run backend
+npm run build && npm start
+
+# Run tests (Redis must be running)
+REDIS_HOST=127.0.0.1 npm test
+```
+
+---
+
+## Production Security Checklist
+
+- [ ] `REDIS_PASSWORD` set to ≥ 32 random characters
+- [ ] `REDIS_TLS=true` with valid CA cert for managed Redis (e.g. AWS ElastiCache, Upstash)
+- [ ] Redis not exposed on public network interface
+- [ ] `maxmemory` and `maxmemory-policy` configured (`allkeys-lru` recommended)
+- [ ] Separate Redis instance (or logical DB) per environment
+- [ ] Alerts wired on queue depth and memory usage
+- [ ] Redis password rotated on any suspected compromise

backend/eslint.config.mjs

@@ -2,4 +2,24 @@
 import eslint from "@eslint/js";
 import tseslint from "typescript-eslint";
 
-export default tseslint.config(eslint.configs.recommended, ...tseslint.configs.recommended);
+export default tseslint.config(
+  // Global ignores
+  {
+    ignores: ["dist/**", "dist-test/**", "node_modules/**"],
+  },
+  // JS recommended for all files
+  eslint.configs.recommended,
+  // TypeScript rules — type-unaware (no parserOptions.project needed)
+  // Using recommendedTypeChecked requires a tsconfig; skip for now to keep
+  // CI fast. Switch to recommendedTypeChecked once tsconfig paths are stable.
+  ...tseslint.configs.recommended,
+  // Override rules that are noisy during early development
+  {
+    rules: {
+      // Allow void-returning async handlers in express routes
+      "@typescript-eslint/no-floating-promises": "off",
+      // Allow empty catch blocks with a comment
+      "no-empty": ["error", { allowEmptyCatch: true }],
+    },
+  }
+);

backend/src/__tests__/claimEvents.queue.test.ts

@@ -0,0 +1,107 @@
+/**
+ * claim-events queue end-to-end test.
+ *
+ * Verifies that a job enqueued by the producer is picked up and processed
+ * by the worker. Requires a running Redis instance.
+ */
+
+import { enqueueClaimEvent, ClaimEventJobData, closeClaimEventsQueue } from "../queues/claimEvents.queue";
+import { startClaimEventsWorker } from "../queues/claimEvents.worker";
+import { closeRedisClient, getBullMQConnection } from "../redis/client";
+import { Queue, Worker } from "bullmq";
+
+const REDIS_AVAILABLE = process.env.REDIS_HOST !== undefined || process.env.CI === "true";
+const describeIfRedis = REDIS_AVAILABLE ? describe : describe.skip;
+
+describeIfRedis("claim-events queue end-to-end", () => {
+  let worker: Worker<ClaimEventJobData>;
+  let processedJobs: ClaimEventJobData[];
+
+  beforeEach(() => {
+    processedJobs = [];
+    worker = startClaimEventsWorker(async (job) => {
+      processedJobs.push(job.data);
+    });
+  });
+
+  afterEach(async () => {
+    await worker.close();
+    // Drain the queue between tests
+    const conn = getBullMQConnection();
+    const q = new Queue("claim-events", { connection: conn });
+    await q.obliterate({ force: true });
+    await q.close();
+    await conn.quit();
+  });
+
+  afterAll(async () => {
+    await closeClaimEventsQueue();
+    await closeRedisClient();
+  });
+
+  test("enqueued job is processed by worker", async () => {
+    const data: ClaimEventJobData = {
+      eventType: "claim:filed",
+      ledger: 12345,
+      payload: JSON.stringify({ claim_id: 1, amount: 100_000 }),
+    };
+
+    const jobId = await enqueueClaimEvent(data);
+    expect(jobId).toBeTruthy();
+
+    // Wait for worker to process
+    await new Promise<void>((resolve, reject) => {
+      const timeout = setTimeout(() => reject(new Error("job not processed in time")), 10_000);
+      worker.on("completed", () => {
+        clearTimeout(timeout);
+        resolve();
+      });
+      worker.on("failed", (_job: unknown, err: Error) => {
+        clearTimeout(timeout);
+        reject(err);
+      });
+    });
+
+    expect(processedJobs).toHaveLength(1);
+    expect(processedJobs[0].eventType).toBe("claim:filed");
+    expect(processedJobs[0].ledger).toBe(12345);
+  });
+
+  test("failed job is retried", async () => {
+    let attempts = 0;
+    const failingWorker = startClaimEventsWorker(async () => {
+      attempts++;
+      if (attempts < 2) throw new Error("transient failure");
+    });
+
+    const data: ClaimEventJobData = {
+      eventType: "vote:logged",
+      ledger: 99,
+      payload: "{}",
+    };
+
+    await enqueueClaimEvent(data);
+
+    await new Promise<void>((resolve, reject) => {
+      const timeout = setTimeout(() => reject(new Error("retry not observed")), 15_000);
+      failingWorker.on("completed", () => {
+        clearTimeout(timeout);
+        resolve();
+      });
+    });
+
+    expect(attempts).toBeGreaterThanOrEqual(2);
+    await failingWorker.close();
+  });
+});
+
+describe("queue module (unit — no Redis)", () => {
+  test("ClaimEventJobData shape is correct", () => {
+    const data: ClaimEventJobData = {
+      eventType: "claim:settled",
+      ledger: 1,
+      payload: "{}",
+    };
+    expect(data.eventType).toBe("claim:settled");
+  });
+});

backend/src/__tests__/health.test.ts

@@ -0,0 +1,35 @@
+/**
+ * Health endpoint tests — no Redis required.
+ * These run in every CI environment without any service containers.
+ */
+
+import request from "supertest";
+import app from "../index";
+
+describe("GET /health", () => {
+  test("returns 200 with status ok", async () => {
+    const res = await request(app).get("/health");
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ status: "ok" });
+  });
+});
+
+describe("GET /health/ready", () => {
+  test("returns a status field", async () => {
+    // Redis may or may not be available in unit test context.
+    // We only assert the response shape, not the specific status code.
+    const res = await request(app).get("/health/ready");
+    expect(res.body).toHaveProperty("status");
+    expect(res.body).toHaveProperty("redis");
+    expect(["ok", "degraded"]).toContain(res.body.status);
+  });
+});
+
+describe("GET /metrics/redis", () => {
+  test("returns metrics shape", async () => {
+    const res = await request(app).get("/metrics/redis");
+    expect(res.status).toBe(200);
+    expect(res.body).toHaveProperty("connected");
+    expect(res.body).toHaveProperty("queues");
+  });
+});