debug.controller.ts

debug.controller.tsapps/api/src/modules/forms/debug.controller.tsraw ← forms3,157 B← Back to the app
1/**
2 * TASK-0109 §Backend — the test-only debug events endpoint.
3 *
4 * `GET /api/v1/debug/events?name=form.submitted` returns the most recent
5 * matching envelopes from the Redis stream `factory:events`, so the E2E
6 * suite can assert stream events end-to-end (the ROADMAP exit criterion)
7 * without standing up a worker.
8 *
9 * Compile/runtime gates (spec §Security — "compiled behind NODE_ENV=test,
10 * not merely guarded at runtime"):
11 *   1. `NODE_ENV !== "test"` → the route returns 404 for EVERY caller
12 *      (production builds never expose the stream);
13 *   2. `X-Debug-Token` must equal the env `TEST_DEBUG_TOKEN` (a random
14 *      per-run secret in the integration app; empty in production — an
15 *      empty expected token NEVER matches, so the endpoint is closed).
16 * The path is auth-guard-whitelisted (it is not a public product surface —
17 * it only ever resolves to 404/401 in non-test builds).
18 */
19import { Controller, Get, Inject, Query, Req } from "@nestjs/common";
20import type { Request } from "express";
21import { ApiError } from "../../common/errors.js";
22import { RedisService } from "../../common/redis.service.js";
23import { loadEnv } from "../../config/env.js";
24import { EVENTS_STREAM } from "../../constants.js";
25 
26@Controller()
27export class DebugController {
28  constructor(@Inject(RedisService) private readonly redis: RedisService) {}
29 
30  @Get("debug/events")
31  async events(
32    @Query("name") name: string | undefined,
33    @Query("limit") limit: string | undefined,
34    @Req() req: Request
35  ) {
36    // Gate 1: test builds only (404 elsewhere — no existence leak).
37    if (process.env.NODE_ENV !== "test") throw ApiError.notFound("Not found.");
38    // Gate 2: the debug token (empty expected token never matches).
39    const expected = loadEnv().TEST_DEBUG_TOKEN;
40    const given = String(req.headers["x-debug-token"] ?? "");
41    if (!expected || given !== expected) {
42      throw ApiError.unauthorized("Invalid debug token.", [{ reason: "debug_token_invalid" }]);
43    }
44 
45    const count = Math.min(Math.max(Number(limit ?? 50) || 50, 1), 200);
46    // ioredis signature: xrange(key, start, end, "COUNT", n) — COUNT is
47    // POSITIONAL (not the { COUNT } object of node-redis v4). It returns
48    // flat [id, [k, v, k, v, …]] pairs (NOT a per-entry map), so each entry
49    // is folded into a map first (mirrors the worker's readLoop conversion).
50    const raw = await this.redis
51      .getRedis()
52      .xrange(EVENTS_STREAM, "-", "+", "COUNT", 1000)
53      .catch((): [string, string[]][] => []);
54    const out: { event: string; payload: unknown; ts: string }[] = [];
55    for (const [, fields] of raw) {
56      const map: Record<string, string> = {};
57      for (let i = 0; i < fields.length; i += 2) map[fields[i]!] = fields[i + 1]!;
58      if (name && map["event"] !== name) continue;
59      let payload: unknown = {};
60      try {
61        payload = map["payload"] ? JSON.parse(map["payload"]) : {};
62      } catch {
63        payload = map["payload"] ?? {};
64      }
65      out.push({ event: map["event"] ?? "", payload, ts: map["ts"] ?? "" });
66      if (out.length >= count) break;
67    }
68    return { items: out };
69  }
70}
71