config.ts · Source

config.tsapps/realtime/src/config.tsraw ← src4,134 B← Back to the app
1/**
2 * Runtime configuration for the realtime gateway.
3 *
4 * All values come from environment variables (see ../.env.example).
5 * This module is pure: it parses and validates only — no I/O, no side
6 * effects — so it can be unit-tested by passing an explicit env object.
7 */
8 
9export interface RealtimeConfig {
10  /** WebSocket gateway port (ws). */
11  port: number
12  /** HTTP health/metrics port. */
13  healthPort: number
14  /** Shared JWT secret (HS256) used to verify client tokens. Required. */
15  jwtSecret: string
16  /** Redis connection URL (cross-node fan-out, presence). */
17  redisUrl: string
18  /** API base URL (token/session verification fallback). */
19  apiUrl: string
20  /** Pino log level: fatal | error | warn | info | debug | trace. */
21  logLevel: string
22  /** Rate-limit window in milliseconds per client. */
23  rateLimitWindowMs: number
24  /** Max messages per client per window. */
25  rateLimitMax: number
26  /** Maximum sockets per document room. */
27  maxRoomSize: number
28  /** Use the Redis update log + presence (REALTIME_REDIS=0 → in-memory, dev). */
29  useRedis: boolean
30  /** Use the Prisma doc store + resolvers (REALTIME_DB=0 → in-memory/fail-closed, dev). */
31  useDatabase: boolean
32  /**
33   * The shared service token for the API's internal endpoints
34   * (`INTERNAL_SERVICE_TOKEN`, TASK-0092 slice 2). Non-empty → the doc
35   * store talks to the API over HTTP (`HttpDocStore`); empty → the
36   * in-process Prisma store (single-node dev) — the fail-closed contract
37   * (an empty token never opens the internal surface).
38   */
39  internalServiceToken: string
40  /** Trust the X-Forwarded-For client IP (server behind a proxy). */
41  trustProxy: boolean
42}
43 
44/** Parse an integer env var; throws a descriptive error on bad values. */
45function parseIntEnv(name: string, value: string | undefined, fallback: number): number {
46  if (value === undefined || value === '') return fallback
47  const parsed = Number.parseInt(value, 10)
48  if (!Number.isInteger(parsed) || parsed <= 0) {
49    throw new Error(`Invalid value for ${name}: "${value}" (expected a positive integer)`)
50  }
51  return parsed
52}
53 
54/** Parse a boolean env var; treats "0"/"false" (case-insensitive) as false. */
55function parseBoolEnv(name: string, value: string | undefined, fallback: boolean): boolean {
56  if (value === undefined || value === '') return fallback
57  return !/^(0|false|no|off)$/i.test(value.trim())
58}
59 
60/**
61 * Load and validate the realtime configuration.
62 *
63 * Reads `env` (defaults to `process.env`). Throws when `JWT_SECRET` is
64 * missing or empty — the gateway cannot securely accept connections
65 * without a signing secret.
66 */
67export function loadConfig(env: NodeJS.ProcessEnv = process.env): RealtimeConfig {
68  const jwtSecret = env.JWT_SECRET?.trim() ?? ''
69  if (jwtSecret.length === 0) {
70    throw new Error('Missing required environment variable: JWT_SECRET')
71  }
72 
73  return {
74    // `REALTIME_PORT` is the documented gateway port (docs/development/
75    // development-guide.md); it must NOT fall back to the shared `PORT` env,
76    // which in the dev stack is the API's 4000 (that collision was a latent
77    // bug: the gateway tried to bind :4000 and died with EADDRINUSE).
78    // `PORT` is kept as an explicit fallback for standalone runs.
79    port: parseIntEnv('REALTIME_PORT', env.REALTIME_PORT ?? env.PORT, 4001),
80    healthPort: parseIntEnv('REALTIME_HEALTH_PORT', env.REALTIME_HEALTH_PORT ?? env.HEALTH_PORT, 4002),
81    jwtSecret,
82    redisUrl: env.REDIS_URL ?? 'redis://localhost:6379',
83    apiUrl: env.API_URL ?? 'http://localhost:4000',
84    logLevel: env.LOG_LEVEL ?? 'info',
85    rateLimitWindowMs: parseIntEnv('RATE_LIMIT_WINDOW_MS', env.RATE_LIMIT_WINDOW_MS, 60000),
86    rateLimitMax: parseIntEnv('RATE_LIMIT_MAX', env.RATE_LIMIT_MAX, 300),
87    maxRoomSize: parseIntEnv('MAX_ROOM_SIZE', env.MAX_ROOM_SIZE, 200),
88    useRedis: parseBoolEnv('REALTIME_REDIS', env.REALTIME_REDIS, true),
89    useDatabase: parseBoolEnv('REALTIME_DB', env.REALTIME_DB, true),
90    internalServiceToken: env.INTERNAL_SERVICE_TOKEN?.trim() ?? '',
91    trustProxy: parseBoolEnv('REALTIME_TRUST_PROXY', env.REALTIME_TRUST_PROXY, false),
92  }
93}
94