Merge pull request #173 from shogun444/feat/db-query-timeout-config

Feat/db query timeout config

Author: Chucks1093

.env.example

@@ -5,6 +5,7 @@ FRONTEND_URL=http://localhost:5173
 
 # Docker Postgres defaults
 DATABASE_URL=postgresql://postgres:postgres@localhost:5432/accesslayer
+DB_QUERY_TIMEOUT_MS=5000
 APP_SECRET=your_32_character_long_secret_string_here
 
 GOOGLE_CLIENT_ID=

src/app.ts

@@ -14,13 +14,15 @@ import { responseTimingMiddleware } from './middlewares/response-timing.middlewa
 import { apiVersionMiddleware } from './middlewares/api-version.middleware';
 import { schemaVersionMiddleware } from './middlewares/schema-version.middleware';
 import { requestLoggerMiddleware } from './middlewares/request-logger.middleware';
+import { requestContextMiddleware } from './middlewares/request-context.middleware';
 import { envConfig } from './config';
 
 const app: Express = express();
 
 // Middleware setup
 app.set('trust proxy', 1);
 app.use(responseTimingMiddleware);
+app.use(requestContextMiddleware);
 app.use(apiVersionMiddleware);
 app.use(schemaVersionMiddleware);
 app.use(requestIdMiddleware);

src/config.schema.ts

@@ -15,6 +15,20 @@ import { z } from 'zod';
  * See docs/configuration.md for complete documentation.
  * See docs/CONFIG_SOURCE_PRECEDENCE.md for visual reference.
  */
+/**
+ * Helper to correctly coerce boolean strings from environment variables.
+ * Zod's default z.coerce.boolean() returns true for any non-empty string,
+ * including "false" and "0", which is usually not what we want for .env files.
+ */
+const booleanCoerce = z.preprocess((val) => {
+   if (typeof val === 'string') {
+      const lower = val.toLowerCase();
+      if (lower === 'true' || lower === '1') return true;
+      if (lower === 'false' || lower === '0') return false;
+   }
+   return val;
+}, z.coerce.boolean());
+
 export const envSchema = z
    .object({
       PORT: z.coerce.number().default(3000),
@@ -60,11 +74,12 @@ export const envSchema = z
          .string()
          .min(1, 'PAYSTACK_PUBLIC_KEY is required for payment processing')
          .optional(),
-      ENABLE_RESPONSE_TIMING: z.coerce.boolean().default(true),
+      ENABLE_RESPONSE_TIMING: booleanCoerce.default(true),
       API_VERSION: z.string().default('1.0.0'),
-      ENABLE_API_VERSION_HEADER: z.coerce.boolean().default(true),
-      ENABLE_SCHEMA_VERSION_HEADER: z.coerce.boolean().default(true),
-      ENABLE_REQUEST_LOGGING: z.coerce.boolean().default(true),
+      ENABLE_API_VERSION_HEADER: booleanCoerce.default(true),
+      ENABLE_SCHEMA_VERSION_HEADER: booleanCoerce.default(true),
+      ENABLE_REQUEST_LOGGING: booleanCoerce.default(true),
+      DB_QUERY_TIMEOUT_MS: z.coerce.number().default(5000),
 
       APP_SECRET: z
          .string()
@@ -78,9 +93,9 @@ export const envSchema = z
       INDEXER_HEARTBEAT_STALE_THRESHOLD_MS: z.coerce.number().positive().default(300000),
 
       // Indexer feature flags
-      ENABLE_INDEXER_DEDUPE: z.coerce.boolean().default(true),
-      ENABLE_INDEXER_DLQ: z.coerce.boolean().default(true),
-      ENABLE_INDEXER_CURSOR_STALENESS_WARNING: z.coerce.boolean().default(true),
+      ENABLE_INDEXER_DEDUPE: booleanCoerce.default(true),
+      ENABLE_INDEXER_DLQ: booleanCoerce.default(true),
+      ENABLE_INDEXER_CURSOR_STALENESS_WARNING: booleanCoerce.default(true),
 
       // Stellar network
       STELLAR_NETWORK: z

src/config.test.ts

@@ -1,12 +1,23 @@
-/// <reference types="node" />
-import { strict as assert } from 'assert';
-import { envSchema } from './config.schema';
+// src/config.test.ts
+// Tests for configuration source precedence and validation behavior.
+
 import { z } from 'zod';
+import { envSchema } from './config.schema';
 
 /**
- * Minimal valid env fixture — satisfies every required field in envSchema
- * so individual tests can override only the values they care about.
+ * Test configuration schema behavior without affecting actual config.
+ * These tests validate the documented source precedence rules and Stellar-specific logic.
  */
+
+const booleanCoerce = z.preprocess((val) => {
+   if (typeof val === 'string') {
+      const lower = val.toLowerCase();
+      if (lower === 'true' || lower === '1') return true;
+      if (lower === 'false' || lower === '0') return false;
+   }
+   return val;
+}, z.coerce.boolean());
+
 const BASE_ENV = {
    PORT: '3000',
    MODE: 'development',
@@ -21,85 +32,102 @@ const BASE_ENV = {
    CLOUDINARY_API_KEY: 'api-key',
    CLOUDINARY_API_SECRET: 'api-secret',
    PAYSTACK_SECRET_KEY: 'pk-secret',
+   APP_SECRET: 'accesslayer_default_development_secret_key_32_bytes_long',
 };
 
-function run() {
-   console.log('Running configuration validation tests...');
+describe('Config Validation and Source Precedence', () => {
+   
+   describe('Stellar & General Schema Validation', () => {
+      it('Defaults are applied correctly', () => {
+         const defaults = envSchema.parse(BASE_ENV);
+         expect(defaults.STELLAR_NETWORK).toBe('testnet');
+         expect(defaults.STELLAR_HORIZON_URL).toBe('https://horizon-testnet.stellar.org');
+         expect(defaults.API_VERSION).toBe('1.0.0');
+         expect(defaults.ENABLE_INDEXER_DEDUPE).toBe(true);
+      });
 
-   // ── SECTION 1: Project Schema Validation (Stellar & General) ──
+      it('Valid explicit config is accepted', () => {
+         const valid = envSchema.safeParse({
+            ...BASE_ENV,
+            STELLAR_NETWORK: 'mainnet',
+            STELLAR_HORIZON_URL: 'https://horizon.stellar.org',
+         });
+         expect(valid.success).toBe(true);
+      });
 
-   // 1.1 Defaults are applied correctly
-   const defaults = envSchema.parse(BASE_ENV);
-   assert.equal(defaults.STELLAR_NETWORK, 'testnet');
-   assert.equal(defaults.STELLAR_HORIZON_URL, 'https://horizon-testnet.stellar.org');
-   assert.equal(defaults.API_VERSION, '1.0.0');
-   assert.equal(defaults.ENABLE_INDEXER_DEDUPE, true);
+      it('Invalid STELLAR_NETWORK value is rejected', () => {
+         const badNetwork = envSchema.safeParse({
+            ...BASE_ENV,
+            STELLAR_NETWORK: 'devnet',
+         });
+         expect(badNetwork.success).toBe(false);
+      });
 
-   // 1.2 Valid explicit config is accepted
-   const valid = envSchema.safeParse({
-      ...BASE_ENV,
-      STELLAR_NETWORK: 'mainnet',
-      STELLAR_HORIZON_URL: 'https://horizon.stellar.org',
+      it('production MODE with testnet STELLAR_NETWORK should fail', () => {
+         const mismatch = envSchema.safeParse({
+            ...BASE_ENV,
+            MODE: 'production',
+            STELLAR_NETWORK: 'testnet',
+         });
+         expect(mismatch.success).toBe(false);
+         if (!mismatch.success) {
+            const issue = mismatch.error.issues.find((i: z.ZodIssue) => 
+               i.path.includes('STELLAR_NETWORK') && i.message.includes('mainnet')
+            );
+            expect(issue).toBeDefined();
+         }
+      });
    });
-   assert.equal(valid.success, true, 'Valid Stellar config should parse');
 
-   // 1.3 Invalid STELLAR_NETWORK value is rejected
-   const badNetwork = envSchema.safeParse({
-      ...BASE_ENV,
-      STELLAR_NETWORK: 'devnet',
-   });
-   assert.equal(badNetwork.success, false, 'Invalid STELLAR_NETWORK should fail');
+   describe('Source Precedence & Zod Behavior', () => {
+      it('Environment variable takes precedence over default', () => {
+         const schema = z.object({
+            PORT: z.coerce.number().default(3000),
+         });
 
-   // 1.4 Cross-field: production + testnet raises an issue
-   const mismatch = envSchema.safeParse({
-      ...BASE_ENV,
-      MODE: 'production',
-      STELLAR_NETWORK: 'testnet',
-   });
-   assert.equal(mismatch.success, false, 'production MODE with testnet STELLAR_NETWORK should fail');
-   if (!mismatch.success) {
-      const issue = mismatch.error.issues.find((i: z.ZodIssue) => 
-         i.path.includes('STELLAR_NETWORK') && i.message.includes('mainnet')
-      );
-      assert.ok(issue, 'Error should warn about STELLAR_NETWORK mismatch in production');
-   }
+         const result = schema.parse({ PORT: '4000' });
+         expect(result.PORT).toBe(4000);
+      });
 
-   // ── SECTION 2: Source Precedence & Zod Behavior (from main branch) ──
-   console.log('Running source precedence and Zod behavior checks...');
+      it('Default used when environment variable not provided', () => {
+         const schema = z.object({
+            PORT: z.coerce.number().default(3000),
+         });
 
-   // 2.1 Environment variable takes precedence over default
-   {
-      const schema = z.object({ PORT: z.coerce.number().default(3000) });
-      const result = schema.parse({ PORT: '4000' });
-      assert.equal(result.PORT, 4000);
-   }
+         const result = schema.parse({});
+         expect(result.PORT).toBe(3000);
+      });
+
+      it('Type coercion for numbers', () => {
+         const schema = z.object({
+            PORT: z.coerce.number(),
+         });
 
-   // 2.2 Type coercion for numbers and booleans
-   {
-      const schema = z.object({
-         PORT: z.coerce.number(),
-         ENABLED: z.coerce.boolean(),
+         const result = schema.parse({ PORT: '4000' });
+         expect(result.PORT).toBe(4000);
+         expect(typeof result.PORT).toBe('number');
       });
-      const result = schema.parse({ PORT: '4000', ENABLED: 'true' });
-      assert.equal(typeof result.PORT, 'number');
-      assert.equal(result.ENABLED, true);
-      
-      // Note: z.coerce.boolean() uses Boolean(), so any non-empty string is true.
-      // If we want 'false' or '0' to be false, we'd need a custom preprocessor.
-      assert.equal(schema.parse({ PORT: '3000', ENABLED: 'false' }).ENABLED, true);
-   }
 
-   // 2.3 Number range validation
-   {
-      const schema = z.object({
-         JITTER: z.coerce.number().min(0).max(1).default(0.1),
+      it('Type coercion for booleans', () => {
+         const schema = z.object({
+            ENABLED: booleanCoerce,
+         });
+
+         expect(schema.parse({ ENABLED: 'true' }).ENABLED).toBe(true);
+         expect(schema.parse({ ENABLED: 'false' }).ENABLED).toBe(false);
+         expect(schema.parse({ ENABLED: '1' }).ENABLED).toBe(true);
+         expect(schema.parse({ ENABLED: '0' }).ENABLED).toBe(false);
       });
-      assert.equal(schema.parse({}).JITTER, 0.1);
-      assert.ok(!schema.safeParse({ JITTER: '2' }).success);
-      assert.ok(!schema.safeParse({ JITTER: '-1' }).success);
-   }
 
-   console.log('✓ All configuration tests passed');
-}
+      it('Number range validation', () => {
+         const schema = z.object({
+            JITTER: z.coerce.number().min(0).max(1).default(0.1),
+         });
 
-run();
+         expect(schema.parse({ JITTER: '0.5' }).JITTER).toBe(0.5);
+         expect(schema.parse({}).JITTER).toBe(0.1);
+         expect(schema.safeParse({ JITTER: '2' }).success).toBe(false);
+         expect(schema.safeParse({ JITTER: '-1' }).success).toBe(false);
+      });
+   });
+});

src/config.ts

@@ -19,12 +19,11 @@ dotenv.config();
  * const port = envConfig.PORT;
  * const isProduction = envConfig.MODE === 'production';
  */
-
 export const envConfig = envSchema.parse(process.env);
 
 /**
  * Derived application configuration.
- * 
+ *
  * These values are computed from envConfig at startup.
  */
 export const appConfig = {

src/middlewares/request-context.middleware.ts

@@ -0,0 +1,18 @@
+import { Request, Response, NextFunction } from 'express';
+import { requestContextStorage } from '../utils/als.utils';
+
+export const requestContextMiddleware = (
+  req: Request,
+  _res: Response,
+  next: NextFunction
+): void => {
+  const context = {
+    path: req.originalUrl || req.url,
+    method: req.method,
+    requestId: req.requestId as string | undefined,
+  };
+
+  requestContextStorage.run(context, () => {
+    next();
+  });
+};

src/utils/als.utils.ts

@@ -0,0 +1,9 @@
+import { AsyncLocalStorage } from 'async_hooks';
+
+export interface RequestContext {
+  path: string;
+  method: string;
+  requestId?: string;
+}
+
+export const requestContextStorage = new AsyncLocalStorage<RequestContext>();

src/utils/prisma.utils.ts

@@ -1,23 +1,52 @@
 import { PrismaClient } from '@prisma/client';
 import { envConfig } from '../config';
+import { requestContextStorage } from './als.utils';
+import { logger } from './logger.utils';
 
 // Use global variable to prevent multiple instances in development
-// See: https://www.prisma.io/docs/guides/performance-and-optimization/connection-management
-
 declare global {
-   var prisma: PrismaClient | undefined;
+   var prisma: any | undefined;
 }
 
-// Export a singleton PrismaClient instance
-export const prisma =
-   global.prisma ||
-   new PrismaClient({
-      log:
-         envConfig.MODE === 'development'
-            ? ['query', 'error', 'warn']
-            : ['error'],
-      datasourceUrl: envConfig.DATABASE_URL,
-   });
+const basePrisma = new PrismaClient({
+   log:
+      envConfig.MODE === 'development'
+         ? ['query', 'error', 'warn']
+         : ['error'],
+   datasourceUrl: envConfig.DATABASE_URL,
+});
+
+// Extend Prisma with query timeout
+export const prisma = basePrisma.$extends({
+   query: {
+      $allOperations({ operation, model, args, query }) {
+         const timeoutMs = envConfig.DB_QUERY_TIMEOUT_MS;
+         const context = requestContextStorage.getStore();
+
+         let timeoutId: NodeJS.Timeout;
+         const timeoutPromise = new Promise((_, reject) => {
+            timeoutId = setTimeout(() => {
+               const logContext = {
+                  type: 'database_timeout',
+                  operation,
+                  model,
+                  timeoutMs,
+                  path: context?.path,
+                  method: context?.method,
+                  requestId: context?.requestId,
+               };
+               logger.error(logContext, `Database query timed out after ${timeoutMs}ms`);
+               reject(new Error(`Database query timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+         });
+
+         return Promise.race([
+            query(args).finally(() => clearTimeout(timeoutId)),
+            timeoutPromise,
+         ]);
+      },
+   },
+});
 
 // Prevent multiple instances in development environment
 if (envConfig.MODE !== 'production') {