+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| src | +
+
+ |
+ 92.53% | +62/67 | +77.77% | +14/18 | +88.88% | +8/9 | +92.42% | +61/66 | +
| src/lib | +
+
+ |
+ 100% | +10/10 | +100% | +4/4 | +100% | +5/5 | +100% | +10/10 | +
| src/middleware | +
+
+ |
+ 93.54% | +116/124 | +60.97% | +25/41 | +85.71% | +18/21 | +93.44% | +114/122 | +
| src/routes | +
+
+ |
+ 98.3% | +116/118 | +87.03% | +47/54 | +100% | +10/10 | +99.09% | +110/111 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 | 4x + +4x +4x +4x +4x +4x +4x +4x + + + + + + + + + + + + +4x +16x + + +16x +35x +35x +35x +35x + + +16x +16x +16x +16x +16x + +16x +16x + +16x +1x + + + + + + +16x + + + + + +16x +16x + +16x + + +4x + | import express from 'express';
+import type { Request, Response } from 'express';
+import { streamsRouter } from './routes/streams.js';
+import { healthRouter } from './routes/health.js';
+import { correlationIdMiddleware } from './middleware/correlationId.js';
+import { requestLoggerMiddleware } from './middleware/requestLogger.js';
+import { createRateLimiter } from './middleware/rateLimit.js';
+import { idempotencyMiddleware } from './middleware/idempotency.js';
+import {
+ requestIdMiddleware,
+ notFoundHandler,
+ errorHandler,
+} from './errors.js';
+
+export interface AppOptions {
+ /** When true, mounts a /__test/error route that throws unconditionally. */
+ includeTestRoutes?: boolean;
+ /** Override payload limit in bytes (default 256 KiB). */
+ payloadLimitBytes?: number;
+}
+
+export function createApp(options: AppOptions = {}): express.Express {
+ const application = express();
+
+ // Security headers — applied before any route handler
+ application.use((_req: Request, res: Response, next) => {
+ res.setHeader('X-Content-Type-Options', 'nosniff');
+ res.setHeader('X-Frame-Options', 'DENY');
+ res.setHeader('X-XSS-Protection', '0'); // modern browsers ignore this; CSP is the right control
+ next();
+ });
+
+ const payloadLimit = options.payloadLimitBytes ?? 256 * 1024;
+ application.use(express.json({ limit: payloadLimit }));
+ application.use(requestIdMiddleware);
+ application.use(correlationIdMiddleware);
+ application.use(requestLoggerMiddleware);
+
+ application.use('/health', healthRouter);
+ application.use('/api/streams', createRateLimiter({ max: 100, windowSeconds: 60 }), idempotencyMiddleware, streamsRouter);
+
+ application.get('/', (_req: Request, res: Response) => {
+ res.json({
+ name: 'Fluxora API',
+ version: '0.1.0',
+ docs: 'Programmable treasury streaming on Stellar.',
+ });
+ });
+
+ Iif (options.includeTestRoutes === true) {
+ application.get('/__test/error', () => {
+ throw new Error('forced test error');
+ });
+ }
+
+ application.use(notFoundHandler);
+ application.use(errorHandler);
+
+ return application;
+}
+
+export const app = createApp();
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| redis.ts | +
+
+ |
+ 40.2% | +39/97 | +19.04% | +4/21 | +60.6% | +20/33 | +41.57% | +37/89 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 | + + + + + + + + + + + + + + + + + + + + + +8x + + + + + + + + + + + + + + + + +8x + + + + +8x + + + + + + + + + + + +8x +26x +30x + + + + + +8x + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +8x +12x + + + +19x + + + + + + + +8x +42x + + +46x +46x +22x +1x +1x + +21x +21x + + + + + + +41x + + + + + + +11x + + + + +2x +2x +4x + + + +1x +41x + + +4x + + +2x + + + + + + +8x + +8x +29x + + +8x +65x + +34x + +31x + + +8x +34x + + | /**
+ * Redis cache client for Fluxora Backend.
+ *
+ * Provides a thin, testable wrapper around a Redis connection.
+ * The client degrades gracefully when Redis is unavailable — callers
+ * receive null on cache misses and errors are logged rather than thrown,
+ * so the service continues to function without caching.
+ *
+ * Trust boundaries
+ * ----------------
+ * - Internal only: never exposed to public clients.
+ * - Cache keys are namespaced to prevent collisions.
+ *
+ * Failure modes
+ * -------------
+ * - Redis unavailable → get() returns null, set/del are no-ops; service continues
+ * - Serialization error → logged, null returned
+ * - Connection timeout → logged, null returned
+ *
+ * @module cache/redis
+ */
+
+import { logger } from '../lib/logger.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type RedisClientInstance = any;
+
+export interface CacheClient {
+ get<T>(key: string): Promise<T | null>;
+ set(key: string, value: unknown, ttlSeconds: number): Promise<void>;
+ del(key: string): Promise<void>;
+ delPattern(pattern: string): Promise<void>;
+ ping(): Promise<boolean>;
+ quit(): Promise<void>;
+}
+
+/**
+ * Namespace prefix for all Fluxora cache keys.
+ */
+export const CACHE_NS = 'fluxora:';
+
+/**
+ * TTL constants (seconds).
+ */
+export const TTL = {
+ /** Individual stream — short TTL so mutations propagate quickly. */
+ STREAM: 30,
+ /** Stream list — slightly longer; invalidated on write. */
+ STREAM_LIST: 60,
+ /** Health check result — very short. */
+ HEALTH: 5,
+} as const;
+
+/**
+ * Cache key builders — centralised so tests and callers share the same keys.
+ */
+export const CacheKey = {
+ stream: (id: string) => `${CACHE_NS}stream:${id}`,
+ streamList: () => `${CACHE_NS}streams:list`,
+} as const;
+
+/**
+ * Production Redis cache client backed by `redis` npm package.
+ */
+export class RedisCacheClient implements CacheClient {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ private client: RedisClientInstance;
+ private connected = false;
+
+ constructor(url: string) {
+ // Use a lazy-loaded client — actual connection happens in connect()
+ // We store the URL and create the client lazily to avoid import issues
+ this._url = url;
+ this.client = null;
+ }
+
+ private _url: string;
+
+ private async ensureClient(): Promise<RedisClientInstance> {
+ Iif (this.client === null) {
+ // Dynamic import for ESM/CJS compatibility
+ const redis = await import('redis');
+ this.client = redis.createClient({ url: this._url });
+
+ this.client.on('error', (err: Error) => {
+ logger.error('Redis client error', undefined, { error: err.message });
+ });
+
+ this.client.on('connect', () => {
+ this.connected = true;
+ logger.info('Redis connected');
+ });
+
+ this.client.on('end', () => {
+ this.connected = false;
+ logger.warn('Redis connection closed');
+ });
+ }
+ return this.client;
+ }
+
+ async connect(): Promise<void> {
+ const client = await this.ensureClient();
+ await client.connect();
+ }
+
+ async get<T>(key: string): Promise<T | null> {
+ Iif (!this.connected) return null;
+ try {
+ const client = await this.ensureClient();
+ const raw = await client.get(key);
+ Iif (raw === null) return null;
+ return JSON.parse(raw) as T;
+ } catch (err) {
+ logger.error('Redis get error', undefined, {
+ key,
+ error: err instanceof Error ? err.message : String(err),
+ });
+ return null;
+ }
+ }
+
+ async set(key: string, value: unknown, ttlSeconds: number): Promise<void> {
+ Iif (!this.connected) return;
+ try {
+ const client = await this.ensureClient();
+ await client.set(key, JSON.stringify(value), { EX: ttlSeconds });
+ } catch (err) {
+ logger.error('Redis set error', undefined, {
+ key,
+ error: err instanceof Error ? err.message : String(err),
+ });
+ }
+ }
+
+ async del(key: string): Promise<void> {
+ Iif (!this.connected) return;
+ try {
+ const client = await this.ensureClient();
+ await client.del(key);
+ } catch (err) {
+ logger.error('Redis del error', undefined, {
+ key,
+ error: err instanceof Error ? err.message : String(err),
+ });
+ }
+ }
+
+ async delPattern(pattern: string): Promise<void> {
+ Iif (!this.connected) return;
+ try {
+ const client = await this.ensureClient();
+ const keys = await client.keys(pattern);
+ Iif (keys.length > 0) {
+ await client.del(keys);
+ }
+ } catch (err) {
+ logger.error('Redis delPattern error', undefined, {
+ pattern,
+ error: err instanceof Error ? err.message : String(err),
+ });
+ }
+ }
+
+ async ping(): Promise<boolean> {
+ Iif (!this.connected) return false;
+ try {
+ const client = await this.ensureClient();
+ const result = await client.ping();
+ return result === 'PONG';
+ } catch {
+ return false;
+ }
+ }
+
+ async quit(): Promise<void> {
+ Iif (this.connected) {
+ const client = await this.ensureClient();
+ await client.quit();
+ }
+ }
+}
+
+/**
+ * No-op cache client used when Redis is disabled or unavailable.
+ * All reads return null; writes are silently dropped.
+ */
+export class NullCacheClient implements CacheClient {
+ async get<T>(_key: string): Promise<T | null> { return null; }
+ async set(_key: string, _value: unknown, _ttl: number): Promise<void> { /* no-op */ }
+ async del(_key: string): Promise<void> { /* no-op */ }
+ async delPattern(_pattern: string): Promise<void> { /* no-op */ }
+ async ping(): Promise<boolean> { return false; }
+ async quit(): Promise<void> { /* no-op */ }
+}
+
+/**
+ * In-memory cache client for testing.
+ * Supports TTL expiry and pattern deletion.
+ */
+export class InMemoryCacheClient implements CacheClient {
+ private store = new Map<string, { value: string; expiresAt: number }>();
+
+ async get<T>(key: string): Promise<T | null> {
+ const entry = this.store.get(key);
+ if (!entry) return null;
+ if (Date.now() > entry.expiresAt) {
+ this.store.delete(key);
+ return null;
+ }
+ try {
+ return JSON.parse(entry.value) as T;
+ } catch {
+ return null;
+ }
+ }
+
+ async set(key: string, value: unknown, ttlSeconds: number): Promise<void> {
+ this.store.set(key, {
+ value: JSON.stringify(value),
+ expiresAt: Date.now() + ttlSeconds * 1000,
+ });
+ }
+
+ async del(key: string): Promise<void> {
+ this.store.delete(key);
+ }
+
+ async delPattern(pattern: string): Promise<void> {
+ // Convert glob pattern to regex: replace * with .*
+ const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$');
+ for (const key of this.store.keys()) {
+ if (regex.test(key)) this.store.delete(key);
+ }
+ }
+
+ async ping(): Promise<boolean> { return true; }
+ async quit(): Promise<void> { this.store.clear(); }
+
+ /** Test helper: inspect raw store size. */
+ size(): number { return this.store.size; }
+
+ /** Test helper: clear all entries. */
+ clear(): void { this.store.clear(); }
+}
+
+// ---------------------------------------------------------------------------
+// Singleton management
+// ---------------------------------------------------------------------------
+
+let cacheInstance: CacheClient | null = null;
+
+export function setCacheClient(client: CacheClient): void {
+ cacheInstance = client;
+}
+
+export function getCacheClient(): CacheClient {
+ if (!cacheInstance) {
+ // Degrade gracefully — return no-op client rather than crashing
+ return new NullCacheClient();
+ }
+ return cacheInstance;
+}
+
+export function resetCacheClient(): void {
+ cacheInstance = null;
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +15x +15x + + + + + + + +75x + +9x +9x +2x + + +7x +2x + + +5x +1x + + +4x + + + + + + +64x +2x + + + + + + +31x +31x +3x + +28x + + + + + + +72x +72x +69x + +3x + + + + + + + + +30x + + +30x + +30x + + + +27x +27x + + + + + + + +26x + + + +25x +3x +2x + + +1x + + + +23x +1x + + +22x + +22x + + + + + + + + + + + + + + + + + + + + + + + + + + +16x + + + + + +1x + + + + + + +2x +1x + +1x + + + + + + + +4x +1x + + +3x +2x + + + + + + +63x + + | /**
+ * Environment configuration module for Fluxora Backend
+ *
+ * Responsibilities:
+ * - Load and validate environment variables at startup
+ * - Provide typed, immutable configuration object
+ * - Fail fast on invalid configuration
+ * - Support multiple environments (dev, staging, production)
+ *
+ * Trust boundaries:
+ * - Public: PORT, API_VERSION
+ * - Authenticated: DATABASE_URL, REDIS_URL
+ * - Admin-only: JWT_SECRET, HORIZON_SECRET_KEY
+ */
+
+export interface Config {
+ // Server
+ port: number;
+ nodeEnv: 'development' | 'staging' | 'production';
+ apiVersion: string;
+
+ // Database
+ databaseUrl: string;
+ databasePoolSize: number;
+ databaseConnectionTimeout: number;
+
+ // Cache
+ redisUrl: string;
+ redisEnabled: boolean;
+
+ // Stellar
+ horizonUrl: string;
+ horizonNetworkPassphrase: string;
+
+ // Security
+ jwtSecret: string;
+ jwtExpiresIn: string;
+
+ // Observability
+ logLevel: 'debug' | 'info' | 'warn' | 'error';
+ metricsEnabled: boolean;
+
+ // Feature flags
+ enableStreamValidation: boolean;
+ enableRateLimit: boolean;
+
+ // Request limits
+ /** Maximum request body size in bytes (default 256 KiB). */
+ payloadLimitBytes: number;
+}
+
+/**
+ * Validation error for configuration issues
+ */
+export class ConfigError extends Error {
+ constructor(message: string) {
+ super(`Configuration Error: ${message}`);
+ this.name = 'ConfigError';
+ }
+}
+
+/**
+ * Parse and validate integer environment variable
+ */
+function parseIntEnv(value: string | undefined, defaultValue: number, min?: number, max?: number): number {
+ if (value === undefined) return defaultValue;
+
+ const parsed = parseInt(value, 10);
+ if (isNaN(parsed)) {
+ throw new ConfigError(`Expected integer, got "${value}"`);
+ }
+
+ if (min !== undefined && parsed < min) {
+ throw new ConfigError(`Value ${parsed} is below minimum ${min}`);
+ }
+
+ if (max !== undefined && parsed > max) {
+ throw new ConfigError(`Value ${parsed} exceeds maximum ${max}`);
+ }
+
+ return parsed;
+}
+
+/**
+ * Parse and validate boolean environment variable
+ */
+function parseBoolEnv(value: string | undefined, defaultValue: boolean): boolean {
+ if (value === undefined) return defaultValue;
+ return value.toLowerCase() === 'true' || value === '1';
+}
+
+/**
+ * Validate required environment variable
+ */
+function requireEnv(name: string): string {
+ const value = process.env[name];
+ if (!value) {
+ throw new ConfigError(`Required environment variable missing: ${name}`);
+ }
+ return value;
+}
+
+/**
+ * Validate URL format
+ */
+function validateUrl(url: string, name: string): string {
+ try {
+ new URL(url);
+ return url;
+ } catch {
+ throw new ConfigError(`Invalid URL for ${name}: ${url}`);
+ }
+}
+
+/**
+ * Load and validate configuration from environment
+ * Throws ConfigError if validation fails
+ */
+export function loadConfig(): Config {
+ const nodeEnv = (process.env.NODE_ENV ?? 'development') as 'development' | 'staging' | 'production';
+
+ // In production, enforce required secrets
+ const isProduction = nodeEnv === 'production';
+
+ const databaseUrl = isProduction
+ ? validateUrl(requireEnv('DATABASE_URL'), 'DATABASE_URL')
+ : validateUrl(process.env.DATABASE_URL ?? 'postgresql://localhost/fluxora', 'DATABASE_URL');
+
+ const redisUrl = process.env.REDIS_URL ?? 'redis://localhost:6379';
+ const horizonUrl = validateUrl(
+ process.env.HORIZON_URL ?? 'https://horizon.stellar.org',
+ 'HORIZON_URL'
+ );
+
+ // JWT_SECRET must always be explicitly set — no hardcoded fallback.
+ // In development a short/weak value is tolerated but warned about.
+ // In production the variable is required and must be ≥32 chars.
+ const jwtSecret = isProduction
+ ? requireEnv('JWT_SECRET')
+ : requireEnv('JWT_SECRET');
+
+ if (jwtSecret.length < 32) {
+ if (isProduction) {
+ throw new ConfigError('JWT_SECRET must be at least 32 characters in production');
+ }
+ // Warn in non-production so developers notice without hard-failing CI
+ console.warn('[fluxora] WARNING: JWT_SECRET is shorter than 32 characters — use a strong secret in production');
+ }
+
+ // Reject the placeholder value from .env.example in all environments
+ if (jwtSecret.startsWith('CHANGE_ME')) {
+ throw new ConfigError('JWT_SECRET is still set to the placeholder value — replace it with a real secret');
+ }
+
+ const horizonNetworkPassphrase = process.env.HORIZON_NETWORK_PASSPHRASE ?? 'Test SDF Network ; September 2015';
+
+ const config: Config = {
+ port: parseIntEnv(process.env.PORT, 3000, 1, 65535),
+ nodeEnv,
+ apiVersion: '0.1.0',
+
+ databaseUrl,
+ databasePoolSize: parseIntEnv(process.env.DATABASE_POOL_SIZE, 10, 1, 100),
+ databaseConnectionTimeout: parseIntEnv(process.env.DATABASE_CONNECTION_TIMEOUT, 5000, 1000, 60000),
+
+ redisUrl: validateUrl(redisUrl, 'REDIS_URL'),
+ redisEnabled: parseBoolEnv(process.env.REDIS_ENABLED, true),
+
+ horizonUrl,
+ horizonNetworkPassphrase,
+
+ jwtSecret,
+ jwtExpiresIn: process.env.JWT_EXPIRES_IN ?? '24h',
+
+ logLevel: (process.env.LOG_LEVEL ?? 'info') as 'debug' | 'info' | 'warn' | 'error',
+ metricsEnabled: parseBoolEnv(process.env.METRICS_ENABLED, true),
+
+ enableStreamValidation: parseBoolEnv(process.env.ENABLE_STREAM_VALIDATION, true),
+ enableRateLimit: parseBoolEnv(process.env.ENABLE_RATE_LIMIT, !isProduction),
+
+ payloadLimitBytes: parseIntEnv(process.env.PAYLOAD_LIMIT_BYTES, 256 * 1024, 1024, 10 * 1024 * 1024),
+ };
+
+ return config;
+}
+
+/**
+ * Singleton instance - loaded once at startup
+ */
+let configInstance: Config | null = null;
+
+/**
+ * Get the loaded configuration
+ * Must call initialize() first
+ */
+export function getConfig(): Config {
+ if (!configInstance) {
+ throw new ConfigError('Configuration not initialized. Call initialize() first.');
+ }
+ return configInstance;
+}
+
+/**
+ * Initialize configuration at application startup
+ * Throws ConfigError if validation fails
+ */
+export function initializeConfig(): Config {
+ if (configInstance) {
+ return configInstance;
+ }
+
+ configInstance = loadConfig();
+ return configInstance;
+}
+
+/**
+ * Reset configuration (for testing)
+ */
+export function resetConfig(): void {
+ configInstance = null;
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +23x +23x +23x + + + + + +18x +18x + + + + + + + + + + +12x +14x + + +12x +12x +12x + +12x + + + + + + + + + + + + +14x +14x +14x +12x + +12x + + + + + + + +12x +12x + +2x +2x + +2x + + + + + + + +2x +2x + + + + + + + +19x + +16x +5x + + +11x + + + +11x + + + + + + +4x +4x +4x + +4x + + + + + + + + + + + + + +1x + + + + +1x + + + + + + + + +5x + + +5x +5x +5x +5x +3x + + + +2x + + + + + + + + + + + + +2x + + +2x +2x +2x +2x + +2x +2x + + + +1x + +1x + + + + + + +1x + +2x + + +1x + + + + + + + + | /**
+ * Health check module for Fluxora Backend
+ *
+ * Provides dependency health status and diagnostic information
+ * for operators to diagnose incidents without tribal knowledge.
+ *
+ * Failure modes handled:
+ * - Database connection timeout/failure
+ * - Redis unavailable
+ * - Horizon RPC unreachable
+ * - Invalid configuration
+ */
+
+export type HealthStatus = 'healthy' | 'degraded' | 'unhealthy';
+
+export interface DependencyHealth {
+ name: string;
+ status: HealthStatus;
+ latency?: number; // milliseconds
+ error?: string | undefined;
+ lastChecked: string; // ISO timestamp
+}
+
+export interface HealthReport {
+ status: HealthStatus;
+ timestamp: string;
+ uptime: number; // seconds
+ dependencies: DependencyHealth[];
+ version: string;
+}
+
+/**
+ * Health checker for a single dependency
+ */
+export interface HealthChecker {
+ name: string;
+ check(): Promise<{ latency: number; error?: string }>;
+}
+
+/**
+ * Manages health checks for all dependencies
+ */
+export class HealthCheckManager {
+ private checkers: Map<string, HealthChecker> = new Map();
+ private lastResults: Map<string, DependencyHealth> = new Map();
+ private startTime: number = Date.now();
+
+ /**
+ * Register a health checker for a dependency
+ */
+ registerChecker(checker: HealthChecker): void {
+ this.checkers.set(checker.name, checker);
+ this.lastResults.set(checker.name, {
+ name: checker.name,
+ status: 'healthy',
+ lastChecked: new Date().toISOString(),
+ });
+ }
+
+ /**
+ * Run all health checks
+ */
+ async checkAll(): Promise<HealthReport> {
+ const results = await Promise.all(
+ Array.from(this.checkers.values()).map((checker) => this.checkOne(checker))
+ );
+
+ const dependencies = results;
+ const status = this.aggregateStatus(dependencies);
+ const uptime = Math.floor((Date.now() - this.startTime) / 1000);
+
+ return {
+ status,
+ timestamp: new Date().toISOString(),
+ uptime,
+ dependencies,
+ version: '0.1.0',
+ };
+ }
+
+ /**
+ * Run a single health check
+ */
+ private async checkOne(checker: HealthChecker): Promise<DependencyHealth> {
+ const startTime = Date.now();
+ try {
+ const result = await checker.check();
+ const latency = Date.now() - startTime;
+
+ const health: DependencyHealth = {
+ name: checker.name,
+ status: result.error ? 'unhealthy' : 'healthy',
+ latency,
+ error: result.error,
+ lastChecked: new Date().toISOString(),
+ };
+
+ this.lastResults.set(checker.name, health);
+ return health;
+ } catch (err) {
+ const latency = Date.now() - startTime;
+ const error = err instanceof Error ? err.message : String(err);
+
+ const health: DependencyHealth = {
+ name: checker.name,
+ status: 'unhealthy',
+ latency,
+ error,
+ lastChecked: new Date().toISOString(),
+ };
+
+ this.lastResults.set(checker.name, health);
+ return health;
+ }
+ }
+
+ /**
+ * Aggregate dependency statuses into overall health
+ */
+ private aggregateStatus(dependencies: DependencyHealth[]): HealthStatus {
+ const statuses = dependencies.map((d) => d.status);
+
+ if (statuses.includes('unhealthy')) {
+ return 'unhealthy';
+ }
+
+ Iif (statuses.includes('degraded')) {
+ return 'degraded';
+ }
+
+ return 'healthy';
+ }
+
+ /**
+ * Get last known health status (cached)
+ */
+ getLastReport(version: string): HealthReport {
+ const dependencies = Array.from(this.lastResults.values());
+ const status = this.aggregateStatus(dependencies);
+ const uptime = Math.floor((Date.now() - this.startTime) / 1000);
+
+ return {
+ status,
+ timestamp: new Date().toISOString(),
+ uptime,
+ dependencies,
+ version,
+ };
+ }
+}
+
+/**
+ * Create a health checker for database connections
+ */
+export function createDatabaseHealthChecker(): HealthChecker {
+ return {
+ name: 'database',
+ async check() {
+ // TODO: Implement actual database connection check
+ // For now, return healthy (will be implemented with actual DB)
+ return { latency: 5 };
+ },
+ };
+}
+
+/**
+ * Create a health checker for Redis
+ */
+export function createRedisHealthChecker(pingFn?: () => Promise<boolean>): HealthChecker {
+ return {
+ name: 'redis',
+ async check() {
+ const startTime = Date.now();
+ try {
+ const ping = pingFn ?? (async () => false);
+ const ok = await ping();
+ return ok
+ ? { latency: Date.now() - startTime }
+ : { latency: Date.now() - startTime, error: 'Redis ping failed' };
+ } catch (err) {
+ return {
+ latency: Date.now() - startTime,
+ error: err instanceof Error ? err.message : 'Unknown error',
+ };
+ }
+ },
+ };
+}
+
+/**
+ * Create a health checker for Horizon RPC
+ */
+export function createHorizonHealthChecker(horizonUrl: string): HealthChecker {
+ return {
+ name: 'horizon',
+ async check() {
+ const startTime = Date.now();
+ try {
+ const controller = new AbortController();
+ const timeoutId = setTimeout(() => controller.abort(), 5000);
+
+ try {
+ const response = await fetch(`${horizonUrl}/health`, {
+ signal: controller.signal,
+ });
+
+ clearTimeout(timeoutId);
+
+ Iif (!response.ok) {
+ return {
+ latency: Date.now() - startTime,
+ error: `HTTP ${response.status}`,
+ };
+ }
+
+ return { latency: Date.now() - startTime };
+ } finally {
+ clearTimeout(timeoutId);
+ }
+ } catch (err) {
+ return {
+ latency: Date.now() - startTime,
+ error: err instanceof Error ? err.message : 'Unknown error',
+ };
+ }
+ },
+ };
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| env.ts | +
+
+ |
+ 100% | +47/47 | +97.14% | +34/35 | +100% | +9/9 | +100% | +45/45 | +
| health.ts | +
+
+ |
+ 94.82% | +55/58 | +80% | +12/15 | +93.75% | +15/16 | +96.36% | +53/55 | +
| logger.ts | +
+
+ |
+ 93.33% | +28/30 | +82.6% | +19/23 | +88.23% | +15/17 | +93.33% | +28/30 | +
| validation.ts | +
+
+ |
+ 98.27% | +57/58 | +84.61% | +33/39 | +100% | +7/7 | +98.27% | +57/58 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +24x + + + + + + + +24x + + + + + + +19x + + + + + + +19x +3x + + +16x + + + + + +16x +16x + + + + + + +4x + + + + + + +9x + + + + + + +2x + + + + + + +4x + + + + + + + +4x + + + + + + + + + + + + +5x + + + + + + +1x + + + + + + + + +5x +5x + + + + + + + +3x + + + + + + + +1x + + + + + + +1x + + + + + +5x +1x + + +4x +4x + + + + + + +3x +2x + +3x + + + + + + +48x + + | /**
+ * Logger module for Fluxora Backend
+ *
+ * Provides structured logging for operational observability.
+ * Operators can diagnose incidents by reviewing logs without tribal knowledge.
+ *
+ * Log levels:
+ * - debug: Development and detailed diagnostics
+ * - info: Normal operational events
+ * - warn: Degraded conditions, recoverable errors
+ * - error: Failures requiring operator attention
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export interface LogEntry {
+ timestamp: string;
+ level: LogLevel;
+ message: string;
+ context?: Record<string, unknown> | undefined;
+ error?: {
+ name: string;
+ message: string;
+ stack?: string | undefined;
+ } | undefined;
+}
+
+/**
+ * Logger instance for structured logging
+ */
+export class Logger {
+ private minLevel: LogLevel;
+ private levelOrder: Record<LogLevel, number> = {
+ debug: 0,
+ info: 1,
+ warn: 2,
+ error: 3,
+ };
+
+ constructor(minLevel: LogLevel = 'info') {
+ this.minLevel = minLevel;
+ }
+
+ /**
+ * Check if a log level should be emitted
+ */
+ private shouldLog(level: LogLevel): boolean {
+ return this.levelOrder[level] >= this.levelOrder[this.minLevel];
+ }
+
+ /**
+ * Format and emit a log entry
+ */
+ private emit(entry: LogEntry): void {
+ if (!this.shouldLog(entry.level)) {
+ return;
+ }
+
+ const output = {
+ ...entry,
+ timestamp: new Date().toISOString(),
+ };
+
+ // Use appropriate console method
+ const method = entry.level === 'error' ? 'error' : entry.level === 'warn' ? 'warn' : 'log';
+ console[method](JSON.stringify(output));
+ }
+
+ /**
+ * Log debug message
+ */
+ debug(message: string, context?: Record<string, unknown>): void {
+ this.emit({ timestamp: '', level: 'debug', message, ...(context !== undefined ? { context } : {}) });
+ }
+
+ /**
+ * Log info message
+ */
+ info(message: string, context?: Record<string, unknown>): void {
+ this.emit({ timestamp: '', level: 'info', message, ...(context !== undefined ? { context } : {}) });
+ }
+
+ /**
+ * Log warning message
+ */
+ warn(message: string, context?: Record<string, unknown>): void {
+ this.emit({ timestamp: '', level: 'warn', message, ...(context !== undefined ? { context } : {}) });
+ }
+
+ /**
+ * Log error message
+ */
+ error(message: string, error?: Error, context?: Record<string, unknown>): void {
+ const errorInfo: LogEntry['error'] = error
+ ? {
+ name: error.name,
+ message: error.message,
+ ...(error.stack !== undefined ? { stack: error.stack } : {}),
+ }
+ : undefined;
+
+ this.emit({
+ timestamp: '',
+ level: 'error',
+ message,
+ ...(context !== undefined ? { context } : {}),
+ ...(errorInfo !== undefined ? { error: errorInfo } : {}),
+ });
+ }
+
+ /**
+ * Create a child logger with additional context
+ */
+ child(context: Record<string, unknown>): ContextualLogger {
+ return new ContextualLogger(this, context);
+ }
+
+ /**
+ * Set minimum log level
+ */
+ setLevel(level: LogLevel): void {
+ this.minLevel = level;
+ }
+}
+
+/**
+ * Logger with persistent context (e.g., request ID, user ID)
+ */
+export class ContextualLogger {
+ constructor(
+ private logger: Logger,
+ private context: Record<string, unknown>
+ ) { }
+
+ debug(message: string, context?: Record<string, unknown>): void {
+ this.logger.debug(message, { ...this.context, ...context });
+ }
+
+ info(message: string, context?: Record<string, unknown>): void {
+ this.logger.info(message, { ...this.context, ...context });
+ }
+
+ warn(message: string, context?: Record<string, unknown>): void {
+ this.logger.warn(message, { ...this.context, ...context });
+ }
+
+ error(message: string, error?: Error, context?: Record<string, unknown>): void {
+ this.logger.error(message, error, { ...this.context, ...context });
+ }
+}
+
+/**
+ * Global logger instance
+ */
+let globalLogger: Logger | null = null;
+
+/**
+ * Initialize global logger
+ */
+export function initializeLogger(level: LogLevel = 'info'): Logger {
+ if (globalLogger) {
+ return globalLogger;
+ }
+
+ globalLogger = new Logger(level);
+ return globalLogger;
+}
+
+/**
+ * Get global logger instance
+ */
+export function getLogger(): Logger {
+ if (!globalLogger) {
+ globalLogger = new Logger('info');
+ }
+ return globalLogger;
+}
+
+/**
+ * Reset logger (for testing)
+ */
+export function resetLogger(): void {
+ globalLogger = null;
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 | + + + + + + + + + + + + + + +21x +21x + +21x +21x + + + + + + + +14x +2x + + + +12x +3x + + + + + + +9x + + + + + + +11x + +11x +1x + + + +10x +2x + + + + + + +8x + + +8x +1x + + + +7x +7x +1x + + + + + + +6x + + + + + + +7x + +7x + + + +7x +2x + + + + + + +5x + +5x +1x + + +4x + + + + + + +8x + +8x +1x + + + +7x +7x + +7x +1x + + + + + + +6x + + + + + + + + + + + + + + +5x +1x + + +4x + +4x +4x + +4x +1x + + +3x +3x +3x + + +3x +3x + +3x +1x + + + + +2x + + + + + + + + + + + + +4x +1x + + +3x +2x + + + + + + +1x + + | /**
+ * Validation module for Fluxora Backend
+ *
+ * Provides validation for stream data and other inputs.
+ * Ensures amounts and identities remain unambiguous for clients and auditors.
+ *
+ * Failure modes:
+ * - Invalid input (malformed addresses, negative amounts)
+ * - Missing required fields
+ * - Type mismatches
+ */
+
+export class ValidationError extends Error {
+ constructor(
+ message: string,
+ public field?: string,
+ public value?: unknown
+ ) {
+ super(message);
+ this.name = 'ValidationError';
+ }
+}
+
+/**
+ * Validate Stellar account address format
+ */
+export function validateStellarAddress(address: string, fieldName: string = 'address'): string {
+ if (!address || typeof address !== 'string') {
+ throw new ValidationError(`${fieldName} must be a non-empty string`, fieldName, address);
+ }
+
+ // Stellar public keys start with 'G' and are 56 characters
+ if (!/^G[A-Z2-7]{55}$/.test(address)) {
+ throw new ValidationError(
+ `${fieldName} must be a valid Stellar public key (starts with G, 56 chars)`,
+ fieldName,
+ address
+ );
+ }
+
+ return address;
+}
+
+/**
+ * Validate amount as a positive integer string (stroops)
+ */
+export function validateAmount(amount: string | number, fieldName: string = 'amount'): string {
+ const amountStr = String(amount).trim();
+
+ if (!amountStr) {
+ throw new ValidationError(`${fieldName} is required`, fieldName, amount);
+ }
+
+ // Must be a valid integer
+ if (!/^\d+$/.test(amountStr)) {
+ throw new ValidationError(
+ `${fieldName} must be a non-negative integer (stroops)`,
+ fieldName,
+ amount
+ );
+ }
+
+ const parsed = BigInt(amountStr);
+
+ // Must be positive
+ if (parsed <= 0n) {
+ throw new ValidationError(`${fieldName} must be greater than 0`, fieldName, amount);
+ }
+
+ // Stellar max amount: 922337203685.4775807 XLM = 9223372036854775807 stroops
+ const maxAmount = BigInt('9223372036854775807');
+ if (parsed > maxAmount) {
+ throw new ValidationError(
+ `${fieldName} exceeds maximum Stellar amount`,
+ fieldName,
+ amount
+ );
+ }
+
+ return amountStr;
+}
+
+/**
+ * Validate rate per second as a positive integer string (stroops/second)
+ */
+export function validateRatePerSecond(rate: string | number, fieldName: string = 'ratePerSecond'): string {
+ const rateStr = String(rate).trim();
+
+ Iif (!rateStr) {
+ throw new ValidationError(`${fieldName} is required`, fieldName, rate);
+ }
+
+ if (!/^\d+$/.test(rateStr)) {
+ throw new ValidationError(
+ `${fieldName} must be a non-negative integer (stroops/second)`,
+ fieldName,
+ rate
+ );
+ }
+
+ const parsed = BigInt(rateStr);
+
+ if (parsed <= 0n) {
+ throw new ValidationError(`${fieldName} must be greater than 0`, fieldName, rate);
+ }
+
+ return rateStr;
+}
+
+/**
+ * Validate Unix timestamp (seconds)
+ */
+export function validateTimestamp(timestamp: number | string, fieldName: string = 'timestamp'): number {
+ const ts = typeof timestamp === 'string' ? parseInt(timestamp, 10) : timestamp;
+
+ if (isNaN(ts)) {
+ throw new ValidationError(`${fieldName} must be a valid Unix timestamp`, fieldName, timestamp);
+ }
+
+ // Timestamp must be in the future or very recent (within 1 hour)
+ const now = Math.floor(Date.now() / 1000);
+ const oneHourAgo = now - 3600;
+
+ if (ts < oneHourAgo) {
+ throw new ValidationError(
+ `${fieldName} must be in the future or within the last hour`,
+ fieldName,
+ timestamp
+ );
+ }
+
+ return ts;
+}
+
+/**
+ * Validate stream creation request
+ */
+export interface CreateStreamRequest {
+ sender: string;
+ recipient: string;
+ depositAmount: string;
+ ratePerSecond: string;
+ startTime: number;
+}
+
+export function validateCreateStreamRequest(data: unknown): CreateStreamRequest {
+ if (!data || typeof data !== 'object') {
+ throw new ValidationError('Request body must be a JSON object');
+ }
+
+ const obj = data as Record<string, unknown>;
+
+ const sender = validateStellarAddress(String(obj.sender ?? ''), 'sender');
+ const recipient = validateStellarAddress(String(obj.recipient ?? ''), 'recipient');
+
+ if (sender === recipient) {
+ throw new ValidationError('sender and recipient must be different addresses');
+ }
+
+ const depositAmount = validateAmount(String(obj.depositAmount ?? ''), 'depositAmount');
+ const ratePerSecond = validateRatePerSecond(String(obj.ratePerSecond ?? ''), 'ratePerSecond');
+ const startTime = validateTimestamp(Number(obj.startTime ?? 0), 'startTime');
+
+ // Validate that deposit amount is sufficient for at least 1 second of streaming
+ const depositBig = BigInt(depositAmount);
+ const rateBig = BigInt(ratePerSecond);
+
+ if (depositBig < rateBig) {
+ throw new ValidationError(
+ 'depositAmount must be at least equal to ratePerSecond (minimum 1 second of streaming)'
+ );
+ }
+
+ return {
+ sender,
+ recipient,
+ depositAmount,
+ ratePerSecond,
+ startTime,
+ };
+}
+
+/**
+ * Validate stream ID format
+ */
+export function validateStreamId(id: string, fieldName: string = 'id'): string {
+ if (!id || typeof id !== 'string') {
+ throw new ValidationError(`${fieldName} must be a non-empty string`, fieldName, id);
+ }
+
+ if (!/^stream-\d+$/.test(id)) {
+ throw new ValidationError(
+ `${fieldName} must match format "stream-{timestamp}"`,
+ fieldName,
+ id
+ );
+ }
+
+ return id;
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 | 6x + +6x + +6x + + + + + + + + + + + + +14x +14x +14x +14x +14x + + + +6x +159x +159x +159x +159x + + +6x +5x + + + +14x + +14x +2x + +12x +2x + +10x + + +5x +5x + + + + + +6x + + + + + +14x +14x + +14x + + + + + + + + + +14x + + +14x + + +14x + + + + + +14x + + + +14x + + | import { randomUUID } from 'node:crypto';
+import type { Request, Response, NextFunction } from 'express';
+import { ApiError as MiddlewareApiError } from './middleware/errorHandler.js';
+
+export class ApiError extends Error {
+ status: number;
+ code: string;
+ details: Record<string, unknown> | undefined;
+ expose: boolean;
+
+ constructor(
+ status: number,
+ code: string,
+ message: string,
+ details?: Record<string, unknown>,
+ expose = true,
+ ) {
+ super(message);
+ this.status = status;
+ this.code = code;
+ this.details = details;
+ this.expose = expose;
+ }
+}
+
+export function requestIdMiddleware(req: Request, res: Response, next: NextFunction): void {
+ const requestId = req.header('x-request-id') ?? randomUUID();
+ res.locals['requestId'] = requestId;
+ res.setHeader('x-request-id', requestId);
+ next();
+}
+
+export function notFoundHandler(req: Request, _res: Response, next: NextFunction): void {
+ next(new ApiError(404, 'not_found', `No route matches ${req.method} ${req.originalUrl}`));
+}
+
+function normalizeExpressError(error: unknown): ApiError {
+ const candidate = error as { status?: number; type?: string };
+
+ if (candidate?.type === 'entity.parse.failed') {
+ return new ApiError(400, 'invalid_json', 'Request body must be valid JSON');
+ }
+ if (candidate?.type === 'entity.too.large' || candidate?.status === 413) {
+ return new ApiError(413, 'payload_too_large', 'Request body exceeds the 256 KiB limit');
+ }
+ if (error instanceof ApiError) return error;
+
+ // Also handle ApiError from middleware/errorHandler (streams route)
+ if (error instanceof MiddlewareApiError) {
+ return new ApiError(error.statusCode, error.code, error.message, undefined, true);
+ }
+
+ return new ApiError(500, 'internal_error', 'Internal server error', undefined, false);
+}
+
+export function errorHandler(
+ error: unknown,
+ req: Request,
+ res: Response,
+ _next: NextFunction,
+): void {
+ const normalized = normalizeExpressError(error);
+ const requestId = res.locals['requestId'] as string | undefined;
+
+ const log = {
+ requestId,
+ status: normalized.status,
+ code: normalized.code,
+ method: req.method,
+ path: req.originalUrl,
+ message: error instanceof Error ? error.message : normalized.message,
+ details: normalized.details,
+ };
+
+ Iif (normalized.status >= 500) {
+ console.error('API error', log);
+ } else {
+ console.warn('API error', log);
+ }
+
+ const errorBody: Record<string, unknown> = {
+ code: normalized.code,
+ message: normalized.message,
+ status: normalized.status,
+ requestId,
+ };
+ Iif (normalized.details !== undefined) {
+ errorBody['details'] = normalized.details;
+ }
+
+ res.status(normalized.status).json({ error: errorBody });
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ ++ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| stall.ts | +
+
+ |
+ 26.08% | +6/23 | +23.52% | +4/17 | +50% | +1/2 | +28.57% | +6/21 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 | 3x + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +3x + + +18x +18x + +18x +18x + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | export const DEFAULT_INDEXER_STALL_THRESHOLD_MS = 5 * 60 * 1000;
+
+export type IndexerHealthStatus =
+ | 'not_configured'
+ | 'starting'
+ | 'healthy'
+ | 'stalled';
+
+export type AssessIndexerHealthInput = {
+ enabled?: boolean;
+ lastSuccessfulSyncAt?: string | number | Date | null;
+ now?: string | number | Date;
+ stallThresholdMs?: number;
+};
+
+export type IndexerHealth = {
+ status: IndexerHealthStatus;
+ stalled: boolean;
+ thresholdMs: number;
+ lastSuccessfulSyncAt: string | null;
+ lagMs: number | null;
+ summary: string;
+ clientImpact: 'none' | 'stale_chain_state';
+ operatorAction: 'none' | 'observe' | 'page';
+};
+
+function toTimestamp(value: string | number | Date) {
+ Iif (value instanceof Date) return value.getTime();
+ Iif (typeof value === 'number') return value;
+
+ const parsed = Date.parse(value);
+ return Number.isNaN(parsed) ? null : parsed;
+}
+
+export function assessIndexerHealth(
+ input: AssessIndexerHealthInput = {},
+): IndexerHealth {
+ const thresholdMs = input.stallThresholdMs ?? DEFAULT_INDEXER_STALL_THRESHOLD_MS;
+ const enabled = input.enabled ?? false;
+
+ if (!enabled) {
+ return {
+ status: 'not_configured',
+ stalled: false,
+ thresholdMs,
+ lastSuccessfulSyncAt: null,
+ lagMs: null,
+ summary: 'Indexer is not configured in this environment',
+ clientImpact: 'none',
+ operatorAction: 'none',
+ };
+ }
+
+ Iif (!input.lastSuccessfulSyncAt) {
+ return {
+ status: 'starting',
+ stalled: false,
+ thresholdMs,
+ lastSuccessfulSyncAt: null,
+ lagMs: null,
+ summary: 'Indexer is enabled but no successful sync has been recorded yet',
+ clientImpact: 'stale_chain_state',
+ operatorAction: 'observe',
+ };
+ }
+
+ const lastSuccessfulSyncAtMs = toTimestamp(input.lastSuccessfulSyncAt);
+ const nowMs = toTimestamp(input.now ?? Date.now()) ?? Date.now();
+
+ Iif (lastSuccessfulSyncAtMs === null) {
+ return {
+ status: 'starting',
+ stalled: false,
+ thresholdMs,
+ lastSuccessfulSyncAt: null,
+ lagMs: null,
+ summary: 'Indexer checkpoint is unreadable; treat the worker as not yet healthy',
+ clientImpact: 'stale_chain_state',
+ operatorAction: 'observe',
+ };
+ }
+
+ const lagMs = Math.max(0, nowMs - lastSuccessfulSyncAtMs);
+ const lastSuccessfulSyncAtIso = new Date(lastSuccessfulSyncAtMs).toISOString();
+
+ Iif (lagMs > thresholdMs) {
+ return {
+ status: 'stalled',
+ stalled: true,
+ thresholdMs,
+ lastSuccessfulSyncAt: lastSuccessfulSyncAtIso,
+ lagMs,
+ summary: 'Indexer checkpoint is older than the allowed freshness threshold',
+ clientImpact: 'stale_chain_state',
+ operatorAction: 'page',
+ };
+ }
+
+ return {
+ status: 'healthy',
+ stalled: false,
+ thresholdMs,
+ lastSuccessfulSyncAt: lastSuccessfulSyncAtIso,
+ lagMs,
+ summary: 'Indexer checkpoint is within the allowed freshness threshold',
+ clientImpact: 'none',
+ operatorAction: 'none',
+ };
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| logger.ts | +
+
+ |
+ 100% | +10/10 | +100% | +4/4 | +100% | +5/5 | +100% | +10/10 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 | + + + + + + + + + + + + + + + + + + + + + + + +72x + + + + + + +72x +72x +1x + +71x + + + +10x + +1x + + +60x + + +10x + + +1x + + + | /**
+ * Structured JSON logger.
+ *
+ * Every log record is a single-line JSON object containing at minimum:
+ * { timestamp, level, message }
+ * plus an optional `correlationId` and any extra `meta` fields.
+ *
+ * Output goes to stdout for info/warn/debug and stderr for error so that
+ * log-shipping agents and shell pipelines can separate severity streams.
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export interface LogRecord {
+ timestamp: string;
+ level: LogLevel;
+ message: string;
+ correlationId?: string;
+ [key: string]: unknown;
+}
+
+function write(level: LogLevel, message: string, correlationId?: string, meta?: Record<string, unknown>): void {
+ // meta is spread first so core fields (timestamp, level, message, correlationId)
+ // always take precedence and cannot be overwritten by callers.
+ const record: LogRecord = {
+ ...meta,
+ timestamp: new Date().toISOString(),
+ level,
+ message,
+ ...(correlationId !== undefined ? { correlationId } : {}),
+ };
+ const line = JSON.stringify(record) + '\n';
+ if (level === 'error') {
+ process.stderr.write(line);
+ } else {
+ process.stdout.write(line);
+ }
+}
+
+export const logger = {
+ debug(message: string, correlationId?: string, meta?: Record<string, unknown>): void {
+ write('debug', message, correlationId, meta);
+ },
+ info(message: string, correlationId?: string, meta?: Record<string, unknown>): void {
+ write('info', message, correlationId, meta);
+ },
+ warn(message: string, correlationId?: string, meta?: Record<string, unknown>): void {
+ write('warn', message, correlationId, meta);
+ },
+ error(message: string, correlationId?: string, meta?: Record<string, unknown>): void {
+ write('error', message, correlationId, meta);
+ },
+};
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 | + + + + + + + + + + + + + + + + +6x + + + +6x + +6x +159x + +159x + + + +159x +159x +159x + + | /**
+ * Correlation-ID middleware.
+ *
+ * Attaches a correlation ID to every request so that all log lines emitted
+ * during that request can be linked together.
+ *
+ * Behaviour:
+ * - If the incoming request carries an `x-correlation-id` header with a
+ * non-empty string value, that value is reused.
+ * - Otherwise a new UUID v4 is generated via `crypto.randomUUID()`.
+ *
+ * The resolved ID is written to `req.correlationId` and echoed back in the
+ * `x-correlation-id` response header.
+ *
+ * Trust boundary: accepted as-is for tracing only — never used for auth.
+ */
+
+import { randomUUID } from 'crypto';
+import type { Request, Response, NextFunction } from 'express';
+
+/** Canonical header name used for correlation IDs throughout the service. */
+export const CORRELATION_ID_HEADER = 'x-correlation-id';
+
+export function correlationIdMiddleware(req: Request, res: Response, next: NextFunction): void {
+ const incoming = req.headers[CORRELATION_ID_HEADER];
+ const correlationId =
+ typeof incoming === 'string' && incoming.trim().length > 0
+ ? incoming.trim()
+ : randomUUID();
+
+ req.correlationId = correlationId;
+ res.setHeader(CORRELATION_ID_HEADER, correlationId);
+ next();
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 | +6x +6x + + + + + +6x +6x +6x +6x +6x +6x +6x +6x + + +6x + +59x + +59x +59x + +59x +59x + + + +6x +55x +55x + + + + +55x +54x +54x +54x + +1x +1x +1x + + +6x +124x + + +6x +7x + + +6x +33x + + +6x + + + +6x + + + | import type { Request, Response, NextFunction } from 'express';
+import { DecimalSerializationError, DecimalErrorCode } from '../serialization/decimal.js';
+import { SerializationLogger, error as logError } from '../utils/logger.js';
+
+export interface ApiErrorResponse {
+ error: { code: string; message: string; details?: unknown; requestId?: string };
+}
+
+export enum ApiErrorCode {
+ VALIDATION_ERROR = 'VALIDATION_ERROR',
+ DECIMAL_ERROR = 'DECIMAL_ERROR',
+ NOT_FOUND = 'NOT_FOUND',
+ CONFLICT = 'CONFLICT',
+ METHOD_NOT_ALLOWED = 'METHOD_NOT_ALLOWED',
+ INTERNAL_ERROR = 'INTERNAL_ERROR',
+ SERVICE_UNAVAILABLE = 'SERVICE_UNAVAILABLE',
+}
+
+export class ApiError extends Error {
+ constructor(
+ public readonly code: ApiErrorCode,
+ message: string,
+ public readonly statusCode: number = 500,
+ public readonly details?: unknown,
+ ) {
+ super(message);
+ this.name = 'ApiError';
+ }
+}
+
+export function errorHandler(err: unknown, req: Request, res: Response, _next: NextFunction): void {
+ const requestId: string | undefined = req.correlationId;
+ Iif (err instanceof DecimalSerializationError) {
+ SerializationLogger.validationFailed(err.field ?? 'unknown', err.rawValue, err.code, requestId);
+ res.status(400).json({ error: { code: ApiErrorCode.DECIMAL_ERROR, message: err.message, details: { decimalErrorCode: err.code, field: err.field }, requestId } });
+ return;
+ }
+ if (err instanceof ApiError) {
+ logError(`API error: ${err.message}`, { code: err.code, statusCode: err.statusCode, details: err.details, requestId });
+ res.status(err.statusCode).json({ error: { code: err.code, message: err.message, details: err.details, requestId } });
+ return;
+ }
+ const e = err instanceof Error ? err : new Error(String(err));
+ logError('Unexpected error', { errorName: e.name, errorMessage: e.message, stack: e.stack, requestId });
+ res.status(500).json({ error: { code: ApiErrorCode.INTERNAL_ERROR, message: 'An unexpected error occurred.', requestId } });
+}
+
+export function asyncHandler(fn: (req: Request, res: Response, next: NextFunction) => Promise<void>): (req: Request, res: Response, next: NextFunction) => void {
+ return (req, res, next) => { fn(req, res, next).catch(next); };
+}
+
+export function notFound(resource: string, id?: string): ApiError {
+ return new ApiError(ApiErrorCode.NOT_FOUND, id !== undefined ? `${resource} '${id}' not found` : `${resource} not found`, 404);
+}
+
+export function validationError(message: string, details?: unknown): ApiError {
+ return new ApiError(ApiErrorCode.VALIDATION_ERROR, message, 400, details);
+}
+
+export function conflictError(message: string, details?: unknown): ApiError {
+ return new ApiError(ApiErrorCode.CONFLICT, message, 409, details);
+}
+
+export function serviceUnavailable(message: string): ApiError {
+ return new ApiError(ApiErrorCode.SERVICE_UNAVAILABLE, message, 503);
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 | + + + + + + + + + + + + + + + + + + + + + + + +5x +5x + +5x +5x +5x + + + + + + + +13x + + + + + + + +5x + + + + +26x + + +26x +8x +8x + + +18x + +18x +5x + + + + + + + +5x + + +13x +13x + + +13x +13x +13x + +13x +2x + + + +2x +2x +2x + + + + + + + + + +11x +11x + +11x +7x + + + + + + + +11x + + +11x + + + | /**
+ * Idempotency middleware for Fluxora Backend.
+ *
+ * Clients may supply an `Idempotency-Key` header on mutating requests (POST).
+ * If the same key is seen within the TTL window, the cached response is
+ * replayed instead of re-executing the handler — preventing duplicate stream
+ * creation on network retries.
+ *
+ * Trust boundaries
+ * ----------------
+ * - Idempotency keys are scoped per HTTP method + path + key value.
+ * - Keys are accepted from any client; they are not authenticated.
+ * - Keys must be 8–128 printable ASCII characters.
+ *
+ * Failure modes
+ * -------------
+ * - Cache unavailable → request proceeds normally (fail-open).
+ * - Invalid key format → 400 Bad Request.
+ * - Duplicate key → 200 with cached response body + `Idempotent-Replayed: true` header.
+ *
+ * @module middleware/idempotency
+ */
+
+import type { Request, Response, NextFunction } from 'express';
+import { getCacheClient } from '../cache/redis.js';
+import { logger } from '../lib/logger.js';
+
+export const IDEMPOTENCY_HEADER = 'idempotency-key';
+const IDEMPOTENCY_TTL_SECONDS = 86_400; // 24 hours
+const KEY_PATTERN = /^[\x20-\x7E]{8,128}$/;
+
+interface CachedResponse {
+ status: number;
+ body: unknown;
+}
+
+function buildIdempotencyKey(method: string, path: string, key: string): string {
+ return `fluxora:idempotency:${method}:${path}:${key}`;
+}
+
+/**
+ * Idempotency middleware — attach to POST routes that create resources.
+ *
+ * If no `Idempotency-Key` header is present the request proceeds normally.
+ */
+export function idempotencyMiddleware(
+ req: Request,
+ res: Response,
+ next: NextFunction,
+): void {
+ const rawKey = req.headers[IDEMPOTENCY_HEADER];
+
+ // No key supplied — pass through
+ if (rawKey === undefined) {
+ next();
+ return;
+ }
+
+ const key = Array.isArray(rawKey) ? rawKey[0] : rawKey;
+
+ if (key === undefined || !KEY_PATTERN.test(key)) {
+ res.status(400).json({
+ error: {
+ code: 'invalid_idempotency_key',
+ message:
+ 'Idempotency-Key must be 8–128 printable ASCII characters.',
+ status: 400,
+ },
+ });
+ return;
+ }
+
+ const cacheKey = buildIdempotencyKey(req.method, req.path, key);
+ const cache = getCacheClient();
+
+ // Async check — we need to intercept the response to cache it
+ void (async () => {
+ try {
+ const cached = await cache.get<CachedResponse>(cacheKey);
+
+ if (cached !== null) {
+ logger.info('Idempotent replay', req.correlationId, {
+ idempotencyKey: key,
+ cachedStatus: cached.status,
+ });
+ res.setHeader('Idempotent-Replayed', 'true');
+ res.status(cached.status).json(cached.body);
+ return;
+ }
+ } catch (err) {
+ // Fail-open
+ logger.warn('Idempotency cache read error — proceeding', req.correlationId, {
+ error: err instanceof Error ? err.message : String(err),
+ });
+ }
+
+ // Intercept res.json to cache the response
+ const originalJson = res.json.bind(res);
+ res.json = function (body: unknown) {
+ // Only cache successful responses
+ if (res.statusCode >= 200 && res.statusCode < 300) {
+ void cache
+ .set(cacheKey, { status: res.statusCode, body }, IDEMPOTENCY_TTL_SECONDS)
+ .catch((err: unknown) => {
+ logger.warn('Idempotency cache write error', req.correlationId, {
+ error: err instanceof Error ? err.message : String(err),
+ });
+ });
+ }
+ return originalJson(body);
+ };
+
+ next();
+ })();
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| correlationId.ts | +
+
+ |
+ 100% | +8/8 | +100% | +4/4 | +100% | +1/1 | +100% | +8/8 | +
| errorHandler.ts | +
+
+ |
+ 87.5% | +35/40 | +45.45% | +5/11 | +77.77% | +7/9 | +87.17% | +34/39 | +
| idempotency.ts | +
+
+ |
+ 93.93% | +31/33 | +64.28% | +9/14 | +80% | +4/5 | +93.93% | +31/33 | +
| rateLimit.ts | +
+
+ |
+ 97.14% | +34/35 | +58.33% | +7/12 | +100% | +4/4 | +97.05% | +33/34 | +
| requestLogger.ts | +
+
+ |
+ 100% | +8/8 | +100% | +0/0 | +100% | +2/2 | +100% | +8/8 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 | + + + + + + + + + + + + + + + + + + + + +5x +5x + + + + + + + + + + +5x + + + + + + + + + +46x +46x +8x +8x + +38x + + + + + + +46x +46x + + + + + + + + +5x +38x + +38x + + + + +46x +46x +46x + +46x +46x +46x + +46x +9x +9x +9x +9x +9x + +9x + +9x + + + + + + + +9x + + + +37x + +37x +37x +37x + + + + + + + +37x + + + | /**
+ * Rate limiting middleware for Fluxora Backend.
+ *
+ * Uses a sliding-window counter stored in the cache layer (Redis in production,
+ * in-memory in tests). Falls back to allowing requests when the cache is
+ * unavailable so a Redis outage never takes down the API.
+ *
+ * Trust boundaries
+ * ----------------
+ * - Applied per IP address (X-Forwarded-For respected when behind a proxy).
+ * - Administrators can configure limits per route via RateLimitOptions.
+ *
+ * Failure modes
+ * -------------
+ * - Cache unavailable → requests are allowed (fail-open); logged as warn.
+ * - Limit exceeded → 429 Too Many Requests with Retry-After header.
+ *
+ * @module middleware/rateLimit
+ */
+
+import type { Request, Response, NextFunction } from 'express';
+import { getCacheClient } from '../cache/redis.js';
+import { logger } from '../lib/logger.js';
+
+export interface RateLimitOptions {
+ /** Maximum requests allowed in the window. */
+ max: number;
+ /** Window duration in seconds. */
+ windowSeconds: number;
+ /** Cache key prefix to namespace different limiters. */
+ keyPrefix?: string;
+}
+
+const DEFAULT_OPTIONS: RateLimitOptions = {
+ max: 100,
+ windowSeconds: 60,
+ keyPrefix: 'rl',
+};
+
+/**
+ * Extract the client IP, respecting X-Forwarded-For when set.
+ */
+function getClientIp(req: Request): string {
+ const forwarded = req.headers['x-forwarded-for'];
+ if (typeof forwarded === 'string') {
+ const first = forwarded.split(',')[0];
+ if (first !== undefined) return first.trim();
+ }
+ return req.ip ?? 'unknown';
+}
+
+/**
+ * Build the cache key for a given IP and window bucket.
+ */
+function buildKey(prefix: string, ip: string, windowSeconds: number): string {
+ const bucket = Math.floor(Date.now() / (windowSeconds * 1000));
+ return `fluxora:${prefix}:${ip}:${bucket}`;
+}
+
+/**
+ * Create a rate-limiting middleware with the given options.
+ *
+ * @example
+ * app.use('/api/streams', createRateLimiter({ max: 50, windowSeconds: 60 }));
+ */
+export function createRateLimiter(options: Partial<RateLimitOptions> = {}) {
+ const opts: RateLimitOptions = { ...DEFAULT_OPTIONS, ...options };
+
+ return async function rateLimitMiddleware(
+ req: Request,
+ res: Response,
+ next: NextFunction,
+ ): Promise<void> {
+ const cache = getCacheClient();
+ const ip = getClientIp(req);
+ const key = buildKey(opts.keyPrefix ?? 'rl', ip, opts.windowSeconds);
+
+ try {
+ const current = await cache.get<number>(key);
+ const count = (current ?? 0) + 1;
+
+ if (count > opts.max) {
+ const retryAfter = opts.windowSeconds;
+ res.setHeader('Retry-After', String(retryAfter));
+ res.setHeader('X-RateLimit-Limit', String(opts.max));
+ res.setHeader('X-RateLimit-Remaining', '0');
+ res.setHeader('X-RateLimit-Reset', String(Math.ceil(Date.now() / 1000) + retryAfter));
+
+ logger.warn('Rate limit exceeded', req.correlationId, { ip, count, max: opts.max });
+
+ res.status(429).json({
+ error: {
+ code: 'rate_limit_exceeded',
+ message: `Too many requests. Limit is ${opts.max} per ${opts.windowSeconds}s window.`,
+ status: 429,
+ retryAfter,
+ },
+ });
+ return;
+ }
+
+ // Increment counter; set TTL on first write
+ await cache.set(key, count, opts.windowSeconds);
+
+ res.setHeader('X-RateLimit-Limit', String(opts.max));
+ res.setHeader('X-RateLimit-Remaining', String(Math.max(0, opts.max - count)));
+ res.setHeader('X-RateLimit-Reset', String(Math.ceil(Date.now() / 1000) + opts.windowSeconds));
+ } catch (err) {
+ // Fail-open: log and continue
+ logger.warn('Rate limiter cache error — allowing request', req.correlationId, {
+ error: err instanceof Error ? err.message : String(err),
+ });
+ }
+
+ next();
+ };
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 | + + + + + + + + + + +4x + +4x +31x +31x + +31x + + + + + +31x +31x + + + + + + + +31x + + | /**
+ * Request / response logger middleware.
+ *
+ * Logs two structured records per request:
+ * 1. "request received" — on the way in (method, path, ip).
+ * 2. "request completed" — after the response is flushed (statusCode, durationMs).
+ *
+ * Both records carry `correlationId`. Must be registered after `correlationIdMiddleware`.
+ */
+
+import type { Request, Response, NextFunction } from 'express';
+import { logger } from '../lib/logger.js';
+
+export function requestLoggerMiddleware(req: Request, res: Response, next: NextFunction): void {
+ const { correlationId } = req;
+ const startMs = Date.now();
+
+ logger.info('request received', correlationId, {
+ method: req.method,
+ path: req.path,
+ ip: req.ip,
+ });
+
+ res.on('finish', () => {
+ logger.info('request completed', correlationId, {
+ method: req.method,
+ path: req.path,
+ statusCode: res.statusCode,
+ durationMs: Date.now() - startMs,
+ });
+ });
+
+ next();
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 | 4x + +4x +4x + +4x + + + + + + + + + + +4x +18x +18x + + +18x +18x +18x + +18x + +18x + + + + + + + + + + | import express from 'express';
+import type { Request, Response } from 'express';
+import { assessIndexerHealth } from '../indexer/stall.js';
+import { getCacheClient } from '../cache/redis.js';
+
+export const healthRouter = express.Router();
+
+/**
+ * GET /health
+ *
+ * Liveness probe — always 200 so load-balancers know the process is alive.
+ * `status` reflects indexer freshness and dependency health so operators
+ * can distinguish running-but-degraded from dead.
+ *
+ * Trust boundary: public, read-only — no authentication required.
+ */
+healthRouter.get('/', async (_req: Request, res: Response) => {
+ const indexer = assessIndexerHealth({ enabled: false });
+ const indexerDegraded = indexer.status === 'stalled' || indexer.status === 'starting';
+
+ // Check Redis health
+ const cache = getCacheClient();
+ const redisPing = await cache.ping();
+ const redisStatus = redisPing ? 'healthy' : 'unavailable';
+
+ const status = indexerDegraded ? 'degraded' : 'ok';
+
+ res.json({
+ status,
+ service: 'fluxora-backend',
+ timestamp: new Date().toISOString(),
+ indexer,
+ dependencies: {
+ redis: { status: redisStatus },
+ },
+ });
+});
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| health.ts | +
+
+ |
+ 100% | +12/12 | +66.66% | +4/6 | +100% | +1/1 | +100% | +12/12 | +
| streams.ts | +
+
+ |
+ 98.11% | +104/106 | +89.58% | +43/48 | +100% | +9/9 | +98.98% | +98/99 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 | 6x + +6x +6x +6x +6x + +6x + +6x + + + + + + + + + + + + +6x + +6x + + +6x +158x + + + +70x + + +6x + + +25x +25x +25x +25x +6x +6x +6x +6x + +19x +19x +19x +19x +19x + + + +6x + + +13x +13x +13x +13x +13x +6x +6x +6x +6x + +7x +40x +7x +2x +2x +2x + + + +6x + + +73x +73x +73x +73x +73x +16x + +57x +4x + +53x + + + +53x +15x +18x + +15x + + + +18x + + +38x +38x +38x +37x + +35x +35x +35x +34x + +33x +33x +7x +5x + +2x + +28x +28x +4x +3x + +1x + +25x +25x + + + + +25x +25x +25x +25x +25x +25x + + + +6x + + +13x +13x +77x +13x +11x +11x +11x +4x + +7x + + +7x +7x +7x +7x +7x + + + | import express from 'express';
+import type { Request, Response } from 'express';
+import { validateDecimalString, validateAmountFields } from '../serialization/decimal.js';
+import { ApiError, ApiErrorCode, notFound, validationError, asyncHandler } from '../middleware/errorHandler.js';
+import { SerializationLogger, info, debug } from '../utils/logger.js';
+import { type CacheClient, getCacheClient, CacheKey, TTL } from '../cache/redis.js';
+
+export const streamsRouter = express.Router();
+
+const AMOUNT_FIELDS = ['depositAmount', 'ratePerSecond'] as const;
+
+interface Stream {
+ id: string;
+ sender: string;
+ recipient: string;
+ depositAmount: string;
+ ratePerSecond: string;
+ startTime: number;
+ endTime: number;
+ status: string;
+}
+
+const streams: Stream[] = [];
+
+let _cacheOverride: CacheClient | null = null;
+
+/** @internal for testing only */
+export function setStreamsCache(client: CacheClient | null): void {
+ _cacheOverride = client;
+}
+
+function getCache(): CacheClient {
+ return _cacheOverride ?? getCacheClient();
+}
+
+streamsRouter.get(
+ '/',
+ asyncHandler(async (_req: Request, res: Response) => {
+ const cache = getCache();
+ const cacheKey = CacheKey.streamList();
+ const cached = await cache.get<{ streams: Stream[]; total: number }>(cacheKey);
+ if (cached !== null) {
+ debug('Stream list cache hit', { cacheKey });
+ res.setHeader('X-Cache', 'HIT');
+ res.json(cached);
+ return;
+ }
+ info('Listing all streams', { count: streams.length });
+ const payload = { streams, total: streams.length };
+ await cache.set(cacheKey, payload, TTL.STREAM_LIST);
+ res.setHeader('X-Cache', 'MISS');
+ res.json(payload);
+ }),
+);
+
+streamsRouter.get(
+ '/:id',
+ asyncHandler(async (req: Request, res: Response) => {
+ const { id } = req.params;
+ const cache = getCache();
+ const cacheKey = CacheKey.stream(id ?? '');
+ const cached = await cache.get<Stream>(cacheKey);
+ if (cached !== null) {
+ debug('Stream cache hit', { id, cacheKey });
+ res.setHeader('X-Cache', 'HIT');
+ res.json(cached);
+ return;
+ }
+ debug('Fetching stream', { id, correlationId: req.correlationId });
+ const stream = streams.find((s) => s.id === id);
+ if (!stream) throw notFound('Stream', id);
+ await cache.set(cacheKey, stream, TTL.STREAM);
+ res.setHeader('X-Cache', 'MISS');
+ res.json(stream);
+ }),
+);
+
+streamsRouter.post(
+ '/',
+ asyncHandler(async (req: Request, res: Response) => {
+ const body = req.body as Record<string, unknown>;
+ const { sender, recipient, depositAmount, ratePerSecond, startTime, endTime } = body;
+ const correlationId = req.correlationId;
+ info('Creating new stream', { correlationId });
+ if (typeof sender !== 'string' || sender.trim() === '') {
+ throw validationError('sender must be a non-empty string');
+ }
+ if (typeof recipient !== 'string' || recipient.trim() === '') {
+ throw validationError('recipient must be a non-empty string');
+ }
+ const amountValidation = validateAmountFields(
+ { depositAmount, ratePerSecond } as Record<string, unknown>,
+ AMOUNT_FIELDS as unknown as string[],
+ );
+ if (!amountValidation.valid) {
+ for (const err of amountValidation.errors) {
+ SerializationLogger.validationFailed(err.field ?? 'unknown', err.rawValue, err.code, correlationId);
+ }
+ throw new ApiError(
+ ApiErrorCode.VALIDATION_ERROR,
+ 'Invalid decimal string format for amount fields',
+ 400,
+ { errors: amountValidation.errors.map((e) => ({ field: e.field, code: e.code, message: e.message })) },
+ );
+ }
+ const depositResult = validateDecimalString(depositAmount, 'depositAmount');
+ const validatedDepositAmount = depositResult.valid && depositResult.value != null ? depositResult.value : '0';
+ if (depositAmount !== undefined && depositAmount !== null) {
+ if (parseFloat(validatedDepositAmount) <= 0) throw validationError('depositAmount must be greater than zero');
+ }
+ const rateResult = validateDecimalString(ratePerSecond, 'ratePerSecond');
+ const validatedRatePerSecond = rateResult.valid && rateResult.value != null ? rateResult.value : '0';
+ if (ratePerSecond !== undefined && ratePerSecond !== null) {
+ if (parseFloat(validatedRatePerSecond) < 0) throw validationError('ratePerSecond cannot be negative');
+ }
+ let validatedStartTime = Math.floor(Date.now() / 1000);
+ if (startTime !== undefined) {
+ if (typeof startTime !== 'number' || !Number.isInteger(startTime) || startTime < 0) {
+ throw validationError('startTime must be a non-negative integer');
+ }
+ validatedStartTime = startTime;
+ }
+ let validatedEndTime = 0;
+ if (endTime !== undefined) {
+ if (typeof endTime !== 'number' || !Number.isInteger(endTime) || endTime < 0) {
+ throw validationError('endTime must be a non-negative integer');
+ }
+ validatedEndTime = endTime;
+ }
+ const id = `stream-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+ const stream: Stream = {
+ id, sender: sender.trim(), recipient: recipient.trim(),
+ depositAmount: validatedDepositAmount, ratePerSecond: validatedRatePerSecond,
+ startTime: validatedStartTime, endTime: validatedEndTime, status: 'active',
+ };
+ streams.push(stream);
+ SerializationLogger.amountSerialized(2, correlationId);
+ info('Stream created', { id, correlationId });
+ const cache = getCache();
+ await Promise.all([cache.set(CacheKey.stream(id), stream, TTL.STREAM), cache.del(CacheKey.streamList())]);
+ res.status(201).json(stream);
+ }),
+);
+
+streamsRouter.delete(
+ '/:id',
+ asyncHandler(async (req: Request, res: Response) => {
+ const { id } = req.params;
+ debug('Cancelling stream', { id, correlationId: req.correlationId });
+ const index = streams.findIndex((s) => s.id === id);
+ if (index === -1) throw notFound('Stream', id);
+ const stream = streams[index];
+ Iif (stream === undefined) throw notFound('Stream', id);
+ if (stream.status === 'cancelled') {
+ throw new ApiError(ApiErrorCode.CONFLICT, 'Stream is already cancelled', 409, { streamId: id });
+ }
+ Iif (stream.status === 'completed') {
+ throw new ApiError(ApiErrorCode.CONFLICT, 'Cannot cancel a completed stream', 409, { streamId: id });
+ }
+ streams[index] = { ...stream, status: 'cancelled' };
+ info('Stream cancelled', { id, correlationId: req.correlationId });
+ const cache = getCache();
+ await Promise.all([cache.del(CacheKey.stream(id ?? '')), cache.del(CacheKey.streamList())]);
+ res.json({ message: 'Stream cancelled', id });
+ }),
+);
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 | + + + + + + + + + + + + + + + + + + + + + + + + + +6x + + + + + +6x + + + + +6x +6x +6x +6x +6x +6x + + + + + +6x + +40x + +40x +40x + +40x +40x + + + + + + + + + + + + + + + + + + + + + + + + + +6x + +130x +5x + + + + + + + + + + + +125x +7x + + + + + + + + + + + +118x +3x + + + + + + + + + + + +115x +17x + + + + + + + + + + + +98x +98x +98x + + +98x +4x + + + + + + + + + + + + + + +94x + + + + + + + + + + + + + + +6x + +15x +2x + + + + + + + + +13x +4x +4x +2x + +2x + + + +9x +6x +2x + + + + + + + +4x + + +2x + + +2x + + + + + + + + +2x + + + +2x + + + +3x +3x + + + + + + + + + + + + + + + + + + + + + + + +6x +7x + +7x +4x + + +3x + +3x + + + + + + + + +3x + + + + + +6x +3x +3x + +2x + + + + + + + + + + + + + + +6x +8x + +8x +1x + + +7x +7x +7x +7x + + +7x + + +7x +1x + + + +6x + + + +6x + + + + + + + + + + + + + + + + + + + + + + + + +6x + + + +3x + +3x +7x +7x + + +7x +2x + + + +5x +4x + + + +2x + + + + + + + + + +6x + + + +27x + +27x +54x +54x + + +54x +4x + + +50x +50x +10x + + + + +27x + + + + + | /**
+ * Decimal String Serialization Policy for Fluxora Backend
+ *
+ * Purpose: Ensure amounts, identities, and stream states crossing the chain/API boundary
+ * remain unambiguous for integrators and finance reviewers.
+ *
+ * Trust Boundaries:
+ * - Public internet clients: Can only send valid decimal strings, receive serialized responses
+ * - Authenticated partners: Same as public, with additional API key validation (future)
+ * - Administrators: Can configure serialization policy (future)
+ * - Internal workers: Can process chain data with full precision
+ *
+ * Invariants:
+ * - All amount fields in JSON responses MUST be strings
+ * - Input validation rejects any non-string or malformed decimal input
+ * - Zero values serialize to "0", never omitted or null
+ * - Very large values preserve full precision (up to safe integer limits)
+ *
+ * @module serialization/decimal
+ */
+
+/**
+ * Regular expression for validating decimal string format.
+ * Allows: optional sign, digits, optional decimal point with digits
+ * Examples: "100", "-50", "0.0000001", "+1.5"
+ */
+export const DECIMAL_STRING_PATTERN = /^[+-]?\d+(\.\d+)?$/;
+
+/**
+ * Maximum safe integer for JavaScript (2^53 - 1)
+ * Used for validation before any numeric operations
+ */
+export const MAX_SAFE_INTEGER = BigInt(Number.MAX_SAFE_INTEGER);
+
+/**
+ * Error codes for decimal serialization failures
+ */
+export enum DecimalErrorCode {
+ INVALID_TYPE = 'DECIMAL_INVALID_TYPE',
+ INVALID_FORMAT = 'DECIMAL_INVALID_FORMAT',
+ OUT_OF_RANGE = 'DECIMAL_OUT_OF_RANGE',
+ PRECISION_LOSS = 'DECIMAL_PRECISION_LOSS',
+ EMPTY_VALUE = 'DECIMAL_EMPTY_VALUE',
+}
+
+/**
+ * Custom error class for decimal serialization errors
+ */
+export class DecimalSerializationError extends Error {
+ constructor(
+ public readonly code: DecimalErrorCode,
+ message: string,
+ public readonly field?: string,
+ public readonly rawValue?: unknown
+ ) {
+ super(message);
+ this.name = 'DecimalSerializationError';
+ }
+}
+
+/**
+ * Result type for validation operations
+ */
+export interface ValidationResult {
+ valid: boolean;
+ value?: string;
+ error?: DecimalSerializationError;
+}
+
+/**
+ * Validate that a value is a valid decimal string representation
+ *
+ * @param value - The value to validate
+ * @param fieldName - Optional field name for error context
+ * @returns ValidationResult with either valid value or error details
+ *
+ * @example
+ * const result = validateDecimalString(100);
+ * if (!result.valid) {
+ * console.error(result.error.code);
+ * }
+ */
+export function validateDecimalString(value: unknown, fieldName?: string): ValidationResult {
+ // Check for null/undefined
+ if (value === null || value === undefined) {
+ return {
+ valid: false,
+ error: new DecimalSerializationError(
+ DecimalErrorCode.EMPTY_VALUE,
+ `Field '${fieldName ?? 'value'}' cannot be null or undefined`,
+ fieldName,
+ value
+ ),
+ };
+ }
+
+ // Check for string type
+ if (typeof value !== 'string') {
+ return {
+ valid: false,
+ error: new DecimalSerializationError(
+ DecimalErrorCode.INVALID_TYPE,
+ `Field '${fieldName ?? 'value'}' must be a string, received ${typeof value}`,
+ fieldName,
+ value
+ ),
+ };
+ }
+
+ // Check for empty string
+ if (value.trim() === '') {
+ return {
+ valid: false,
+ error: new DecimalSerializationError(
+ DecimalErrorCode.EMPTY_VALUE,
+ `Field '${fieldName ?? 'value'}' cannot be empty`,
+ fieldName,
+ value
+ ),
+ };
+ }
+
+ // Validate format using regex
+ if (!DECIMAL_STRING_PATTERN.test(value)) {
+ return {
+ valid: false,
+ error: new DecimalSerializationError(
+ DecimalErrorCode.INVALID_FORMAT,
+ `Field '${fieldName ?? 'value'}' must be a valid decimal string (e.g., "100", "-50", "0.0000001")`,
+ fieldName,
+ value
+ ),
+ };
+ }
+
+ // Check for out of range (would cause precision loss in JSON)
+ try {
+ const bigIntValue = BigInt(value.replace('.', ''));
+ const absBigIntValue = bigIntValue < 0n ? -bigIntValue : bigIntValue;
+
+ // Allow values up to 10^20 (more than enough for any financial amount)
+ if (absBigIntValue > 10_000_000_000_000_000_000n) {
+ return {
+ valid: false,
+ error: new DecimalSerializationError(
+ DecimalErrorCode.OUT_OF_RANGE,
+ `Field '${fieldName ?? 'value'}' exceeds maximum supported value`,
+ fieldName,
+ value
+ ),
+ };
+ }
+ } catch {
+ // If BigInt conversion fails for any reason, still allow the value
+ // as it's already validated by the regex
+ }
+
+ return { valid: true, value };
+}
+
+/**
+ * Serialize a numeric value to a decimal string
+ *
+ * @param value - The value to serialize (number, string, or BigInt)
+ * @param fieldName - Optional field name for error context
+ * @returns The decimal string representation
+ * @throws DecimalSerializationError if the value cannot be safely serialized
+ *
+ * @example
+ * const serialized = serializeToDecimalString(100.50);
+ * // Returns: "100.5"
+ */
+export function serializeToDecimalString(value: unknown, fieldName?: string): string {
+ // Handle null/undefined
+ if (value === null || value === undefined) {
+ throw new DecimalSerializationError(
+ DecimalErrorCode.EMPTY_VALUE,
+ `Field '${fieldName ?? 'value'}' cannot be null or undefined`,
+ fieldName,
+ value
+ );
+ }
+
+ // Handle strings - validate and return as-is if valid
+ if (typeof value === 'string') {
+ const result = validateDecimalString(value, fieldName);
+ if (!result.valid) {
+ throw result.error;
+ }
+ return value;
+ }
+
+ // Handle numbers
+ if (typeof value === 'number') {
+ if (!Number.isFinite(value)) {
+ throw new DecimalSerializationError(
+ DecimalErrorCode.INVALID_FORMAT,
+ `Field '${fieldName ?? 'value'}' must be a finite number`,
+ fieldName,
+ value
+ );
+ }
+
+ if (!Number.isInteger(value)) {
+ // For floating point numbers, convert to string and validate
+ // Using toString() which may produce scientific notation for very small/large numbers
+ const strValue = value.toString();
+
+ // Check if toString produced scientific notation (not allowed)
+ Iif (strValue.includes('e')) {
+ throw new DecimalSerializationError(
+ DecimalErrorCode.PRECISION_LOSS,
+ `Field '${fieldName ?? 'value'}' would lose precision with floating point serialization`,
+ fieldName,
+ value
+ );
+ }
+
+ return strValue;
+ }
+
+ // Integer - return as string
+ return value.toString();
+ }
+
+ // Handle BigInt
+ if (typeof value === 'bigint') {
+ return value.toString();
+ }
+
+ // Unknown type
+ throw new DecimalSerializationError(
+ DecimalErrorCode.INVALID_TYPE,
+ `Field '${fieldName ?? 'value'}' must be a string, number, or BigInt`,
+ fieldName,
+ value
+ );
+}
+
+/**
+ * Deserialize a decimal string to a number (use with caution)
+ *
+ * @param value - The decimal string to deserialize
+ * @param fieldName - Optional field name for error context
+ * @returns The numeric representation
+ * @throws DecimalSerializationError if deserialization would lose precision
+ *
+ * @example
+ * const num = deserializeToNumber("100.50");
+ * // Returns: 100.5
+ */
+export function deserializeToNumber(value: unknown, fieldName?: string): number {
+ const validated = validateDecimalString(value, fieldName);
+
+ if (!validated.valid) {
+ throw validated.error;
+ }
+
+ const numValue = Number(validated.value);
+
+ Iif (!Number.isFinite(numValue)) {
+ throw new DecimalSerializationError(
+ DecimalErrorCode.OUT_OF_RANGE,
+ `Field '${fieldName ?? 'value'}' cannot be represented as a finite number`,
+ fieldName,
+ value
+ );
+ }
+
+ return numValue;
+}
+
+/**
+ * Safe version of deserializeToNumber that returns null instead of throwing
+ */
+export function tryDeserializeToNumber(value: unknown, fieldName?: string): number | null {
+ try {
+ return deserializeToNumber(value, fieldName);
+ } catch {
+ return null;
+ }
+}
+
+/**
+ * Format a decimal string for display (adds thousands separators)
+ *
+ * @param value - The decimal string to format
+ * @param decimals - Number of decimal places to show
+ * @returns Formatted string
+ *
+ * @example
+ * const formatted = formatDecimalForDisplay("1000000.50", 2);
+ * // Returns: "1,000,000.50"
+ */
+export function formatDecimalForDisplay(value: string, decimals: number = 7): string {
+ const validated = validateDecimalString(value);
+
+ if (!validated.valid) {
+ return value; // Return original if invalid
+ }
+
+ const [intPart, decPart] = validated.value!.split('.');
+ Iif (intPart === undefined) return value;
+ const sign = intPart.startsWith('-') ? '-' : '';
+ const absIntPart = intPart.replace(/^[+-]/, '');
+
+ // Add thousands separators
+ const formattedInt = sign + absIntPart.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+
+ // If no decimals requested, return integer part
+ if (decimals === 0) {
+ return formattedInt;
+ }
+
+ // Format decimal part
+ const paddedDec = decPart
+ ? decPart.padEnd(decimals, '0').slice(0, decimals)
+ : '0'.repeat(decimals);
+
+ return `${formattedInt}.${paddedDec}`;
+}
+
+/**
+ * Create a safe amount object for API responses
+ * All amount fields are guaranteed to be strings
+ */
+export interface AmountFields {
+ amount?: string;
+ balance?: string;
+ ratePerSecond?: string;
+ depositAmount?: string;
+ totalAmount?: string;
+ withdrawnAmount?: string;
+ [key: string]: string | undefined;
+}
+
+/**
+ * Validate and serialize an object with amount fields
+ *
+ * @param obj - Object containing potential amount fields
+ * @param fieldNames - Array of field names to treat as amounts
+ * @returns New object with validated amount fields as strings
+ * @throws DecimalSerializationError if any amount field fails validation
+ */
+export function serializeAmountFields<T extends Record<string, unknown>>(
+ obj: T,
+ fieldNames: (keyof T)[]
+): T {
+ const result = { ...obj };
+
+ for (const fieldName of fieldNames) {
+ if (fieldName in result) {
+ const value = result[fieldName];
+
+ // Skip null/undefined (field might not exist)
+ if (value === null || value === undefined) {
+ continue;
+ }
+
+ // Validate and serialize
+ const serialized = serializeToDecimalString(value, String(fieldName));
+ (result as Record<string, unknown>)[String(fieldName)] = serialized;
+ }
+ }
+
+ return result;
+}
+
+/**
+ * Validate amount fields in an incoming request
+ *
+ * @param obj - Object containing potential amount fields
+ * @param fieldNames - Array of field names to validate as amounts
+ * @returns ValidationResult with all errors or validated values
+ */
+export function validateAmountFields<T extends Record<string, unknown>>(
+ obj: T,
+ fieldNames: (keyof T)[]
+): { valid: boolean; errors: DecimalSerializationError[] } {
+ const errors: DecimalSerializationError[] = [];
+
+ for (const fieldName of fieldNames) {
+ if (fieldName in obj) {
+ const value = obj[fieldName];
+
+ // Skip null/undefined (field might not exist)
+ if (value === null || value === undefined) {
+ continue;
+ }
+
+ const result = validateDecimalString(value, String(fieldName));
+ if (!result.valid && result.error) {
+ errors.push(result.error);
+ }
+ }
+ }
+
+ return {
+ valid: errors.length === 0,
+ errors,
+ };
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| decimal.ts | +
+
+ |
+ 95.83% | +92/96 | +85.48% | +53/62 | +100% | +9/9 | +96.84% | +92/95 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | /**
+ * Augments the Express Request type to include `correlationId`.
+ * Populated by `correlationIdMiddleware` before any route handler runs.
+ *
+ * Also re-opens the NextFunction interface to restore its call signature,
+ * which TypeScript 5.x drops when the interface is declared as an empty
+ * extension of core.NextFunction.
+ */
+import * as core from 'express-serve-static-core';
+
+declare module 'express-serve-static-core' {
+ interface Request {
+ correlationId: string;
+ }
+}
+
+declare module 'express' {
+ // Restore call signatures lost by the empty interface extension in @types/express
+ interface NextFunction {
+ (err?: unknown): void;
+ (deferToNext: 'router'): void;
+ (deferToNext: 'route'): void;
+ }
+
+ // Restore Response methods that are missing from the re-exported interface
+ interface Response<
+ ResBody = unknown,
+ Locals extends Record<string, unknown> = Record<string, unknown>,
+ > extends core.Response<ResBody, Locals> {}
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| express.d.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| logger.ts | +
+
+ |
+ 69.49% | +41/59 | +41.17% | +14/34 | +68.75% | +11/16 | +71.42% | +40/56 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 | + + + + + + + + + + +5x +5x +5x +5x +5x + + + + + + + + + + + + + + + + +5x +5x +5x + + + + +5x + + + +5x + + + + +79x +79x + + +79x + + + + + + + + +79x + + + + + + +79x +79x + + +79x + + + + + + + + + +79x + + + + + + + + + +108x + +79x +79x + +79x +26x +53x + + +53x + + + +5x +26x + + +5x + + + +5x +53x + + +5x +29x + + +5x +5x + + + + + +8x + + + + + + + + +5x +13x + + + + + +5x + + + + + + + + + + + +5x + + + + + + + + + + + + + + + + +5x + + + + + + + + | /**
+ * Fluxora Backend Logging Utility
+ *
+ * Provides structured logging for operators to observe health and diagnose
+ * incidents without relying on tribal knowledge.
+ *
+ * @module utils/logger
+ */
+
+import type { Request, Response, NextFunction } from 'express';
+
+export enum LogLevel {
+ ERROR = 0,
+ WARN = 1,
+ INFO = 2,
+ DEBUG = 3,
+}
+
+export interface LogEntry {
+ timestamp: string;
+ level: string;
+ service: string;
+ message: string;
+ context?: Record<string, unknown> | undefined;
+ error?: {
+ name: string;
+ message: string;
+ code?: string | undefined;
+ stack?: string | undefined;
+ } | undefined;
+}
+
+let currentLogLevel = (() => {
+ const envLevel = process.env['LOG_LEVEL']?.toUpperCase();
+ switch (envLevel) {
+ case 'ERROR': return LogLevel.ERROR;
+ case 'WARN': return LogLevel.WARN;
+ case 'INFO': return LogLevel.INFO;
+ case 'DEBUG': return LogLevel.DEBUG;
+ default: return LogLevel.INFO;
+ }
+})();
+
+export function setLogLevel(level: LogLevel): void {
+ currentLogLevel = level;
+}
+
+function formatLogEntry(entry: LogEntry): string {
+ const contextStr = entry.context !== undefined ? ` ${JSON.stringify(entry.context)}` : '';
+ const errorStr = entry.error !== undefined
+ ? ` [ERROR: ${entry.error.name}: ${entry.error.message}]`
+ : '';
+ return `[${entry.timestamp}] ${entry.level}: ${entry.service} - ${entry.message}${contextStr}${errorStr}`;
+}
+
+function createLogEntry(
+ level: string,
+ message: string,
+ context?: Record<string, unknown>,
+ err?: Error & { code?: string },
+): LogEntry {
+ const entry: LogEntry = {
+ timestamp: new Date().toISOString(),
+ level,
+ service: 'fluxora-backend',
+ message,
+ };
+
+ if (context !== undefined) {
+ entry.context = context;
+ }
+
+ Iif (err !== undefined) {
+ const errorEntry: LogEntry['error'] = {
+ name: err.name,
+ message: err.message,
+ };
+ Iif (err.code !== undefined) errorEntry!.code = err.code;
+ Iif (err.stack !== undefined) errorEntry!.stack = err.stack;
+ entry.error = errorEntry;
+ }
+
+ return entry;
+}
+
+function log(
+ level: LogLevel,
+ levelStr: string,
+ message: string,
+ context?: Record<string, unknown>,
+ err?: Error,
+): void {
+ if (level > currentLogLevel) return;
+
+ const entry = createLogEntry(levelStr, message, context, err);
+ const formatted = formatLogEntry(entry);
+
+ if (level === LogLevel.ERROR) {
+ console.error(formatted);
+ } else Iif (level === LogLevel.WARN) {
+ console.warn(formatted);
+ } else {
+ console.log(formatted);
+ }
+}
+
+export function error(message: string, context?: Record<string, unknown>, err?: Error): void {
+ log(LogLevel.ERROR, 'ERROR', message, context, err);
+}
+
+export function warn(message: string, context?: Record<string, unknown>): void {
+ log(LogLevel.WARN, 'WARN', message, context);
+}
+
+export function info(message: string, context?: Record<string, unknown>): void {
+ log(LogLevel.INFO, 'INFO', message, context);
+}
+
+export function debug(message: string, context?: Record<string, unknown>): void {
+ log(LogLevel.DEBUG, 'DEBUG', message, context);
+}
+
+export namespace SerializationLogger {
+ export function validationFailed(
+ fieldName: string,
+ receivedValue: unknown,
+ errorCode: string,
+ requestId?: string,
+ ): void {
+ error('Decimal validation failed', {
+ field: fieldName,
+ receivedType: typeof receivedValue,
+ receivedValue: String(receivedValue).slice(0, 100),
+ errorCode,
+ ...(requestId !== undefined ? { requestId } : {}),
+ });
+ }
+
+ export function amountSerialized(fieldCount: number, requestId?: string): void {
+ debug('Amount fields serialized', {
+ fieldCount,
+ ...(requestId !== undefined ? { requestId } : {}),
+ });
+ }
+
+ export function precisionLossPrevented(
+ fieldName: string,
+ originalValue: unknown,
+ requestId?: string,
+ ): void {
+ warn('Precision loss prevented during serialization', {
+ field: fieldName,
+ originalValue: String(originalValue).slice(0, 100),
+ ...(requestId !== undefined ? { requestId } : {}),
+ });
+ }
+
+ export function outOfRangeRejected(
+ fieldName: string,
+ value: unknown,
+ requestId?: string,
+ ): void {
+ warn('Out-of-range decimal value rejected', {
+ field: fieldName,
+ value: String(value).slice(0, 100),
+ ...(requestId !== undefined ? { requestId } : {}),
+ });
+ }
+}
+
+/**
+ * Express middleware to attach a request ID from the x-request-id header.
+ * @deprecated Prefer requestIdMiddleware from errors.ts for new code.
+ */
+export function requestIdMiddleware(req: Request, _res: Response, next: NextFunction): void {
+ const incoming = req.headers['x-request-id'];
+ (req as Request & { id?: string }).id =
+ typeof incoming === 'string' && incoming.length > 0
+ ? incoming
+ : `req-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+ next();
+}
+ |