feat(billing): add graceful timeout on /api/billing with cooperative abort and 504 [b#030]

src/config/env.ts

@@ -151,6 +151,9 @@ export const envSchema = z
     CREDITS_RATE_LIMIT_CAPACITY: z.coerce.number().int().positive().default(10),
     CREDITS_RATE_LIMIT_REFILL_RATE: z.coerce.number().positive().default(1),
 
+    // Billing per-request graceful timeout
+    BILLING_TIMEOUT_MS: z.coerce.number().int().positive().default(30_000),
+
     // Billing endpoint per-user rate limiting (fixed-window)
     BILLING_RATE_LIMIT_WINDOW_MS: z.coerce
       .number()

src/config/index.ts

@@ -229,6 +229,8 @@ export const config = {
   bcrypt: {
     costFactor: env.BCRYPT_COST_FACTOR,
   },
+  billingTimeoutMs: env.BILLING_TIMEOUT_MS,
+
   billingConcurrency: {
     maxPerDeveloper: env.BILLING_MAX_CONCURRENCY_PER_DEV,
     semaphoreTtlMs: env.BILLING_SEMAPHORE_TTL_MS,

src/middleware/__tests__/timeout.test.ts

@@ -21,7 +21,7 @@ describe('createTimeoutMiddleware', () => {
       success: false,
       error: {
         code: 'GATEWAY_TIMEOUT',
-        message: 'Request timed out',
+        message: 'Request timed out after 10ms',
       },
     });
     expect(res.body.requestId).toBeDefined();
@@ -41,10 +41,10 @@ describe('createTimeoutMiddleware', () => {
     expect(res.body).toEqual({ success: true, data: { ok: true } });
   });
 
-  it('should use custom timeout message', async () => {
+  it('should use configured timeout message', async () => {
     const app = express();
 
-    app.use(createTimeoutMiddleware({ durationMs: 10, message: 'Custom timeout message' }));
+    app.use(createTimeoutMiddleware({ durationMs: 10 }));
     app.get('/test', (_req, res) => {
       setTimeout(() => {
         if (!res.writableEnded) {
@@ -55,7 +55,8 @@ describe('createTimeoutMiddleware', () => {
 
     const res = await request(app).get('/test');
     expect(res.status).toBe(504);
-    expect(res.body.error.message).toBe('Custom timeout message');
+    expect(res.body.error.code).toBe('GATEWAY_TIMEOUT');
+    expect(res.body.error.message).toMatch(/timed out/);
   });
 
   it('should not call abort if response already ended', async () => {

src/middleware/timeout.ts

@@ -1,5 +1,6 @@
 import type { Request, Response, NextFunction } from 'express';
 import { logger } from '../logger.js';
+import { buildErrorEnvelope } from './envelope.js';
 
 export interface TimeoutMiddlewareOptions {
   timeoutMs?: number;
@@ -37,11 +38,13 @@ export function createTimeoutMiddleware(
           timeoutMs,
         });
 
-        res.status(504).json({
-          code: 'GATEWAY_TIMEOUT',
-          message: `Request timed out after ${timeoutMs}ms`,
-          requestId,
-        });
+        res.status(504).json(
+          buildErrorEnvelope(
+            'GATEWAY_TIMEOUT',
+            `Request timed out after ${timeoutMs}ms`,
+            requestId,
+          ),
+        );
       }
     }, timeoutMs);
 

src/routes/billing.ts

@@ -35,10 +35,13 @@ import refundRouter from "./billing/refund.js";
 import { createFeeAbstractionRouter } from "./billing/feeAbstraction.js";
 import { createBillingForecastRouter } from "./billing/forecast.js";
 import { etagMiddleware } from "../middleware/etag.js";
+import { createTimeoutMiddleware } from "../middleware/timeout.js";
+import { config } from "../config/index.js";
 
 const router = Router();
 
 router.use(billingAccessLogMiddleware);
+router.use(createTimeoutMiddleware({ timeoutMs: config.billingTimeoutMs }));
 
 router.use("/credits", creditsRouter);
 router.use("/disputes", disputesRouter);