Merge branch 'main' into feat/circuit-breaker-apis

Author: Tybravo

.env.example

@@ -12,6 +12,10 @@ CORS_ORIGIN=http://localhost:3000,http://localhost:5173
 RATE_LIMIT_WINDOW_MS=900000
 RATE_LIMIT_MAX_REQUESTS=100
 
+# Max milliseconds to wait for in-flight HTTP, Socket.IO, and DB work
+# before forcing process exit on SIGTERM/SIGINT (default: 30000).
+SHUTDOWN_TIMEOUT_MS=30000
+
 # ─── Stellar / Soroban ─────────────────────────────────────────────────────────
 # Soroban RPC endpoint.
 # Testnet  : https://soroban-testnet.stellar.org

package-lock.json

@@ -24,6 +24,7 @@
     "express-rate-limit": "6.11.0",
     "helmet": "7.1.0",
     "http-status-codes": "2.3.0",
+    "ioredis": "^5.3.2",
     "jsonwebtoken": "9.0.2",
     "mongoose": "^7.6.3",
     "multer": "^2.2.0",
@@ -43,6 +44,7 @@
     "@types/compression": "1.7.5",
     "@types/cors": "^2.8.17",
     "@types/express": "^4.17.21",
+    "@types/ioredis": "^4.28.10",
     "@types/jest": "^30.0.0",
     "@types/jsonwebtoken": "9.0.5",
     "@types/mongodb-memory-server": "^1.8.0",

package.json

@@ -13,6 +13,7 @@ import logger from './config/logger';
 import { connectDatabase } from './config/database';
 import errorHandler from './middleware/errorHandler';
 import requestLogger from './middleware/requestLogger';
+import { requestTracker } from './middleware/requestTracker';
 import env from './config/env';
 import swaggerSpec from './docs/swagger';
 
@@ -26,6 +27,8 @@ app.set('trust proxy', 1);
 
 app.use(helmet());
 app.use(compression());
+// Track in-flight requests and reject new ones during graceful shutdown.
+app.use(requestTracker);
 app.use(requestLogger);
 
 // Swagger UI needs inline <script>/<style>, which the default Helmet CSP

src/app.ts

@@ -1,7 +1,70 @@
-import mongoose from 'mongoose';
+import mongoose, { ClientSession } from 'mongoose';
 import logger from './logger';
 import env from './env';
 
+/** Active multi-document sessions started via `startTrackedSession`. */
+const activeSessions = new Set<ClientSession>();
+
+export const getActiveTransactionCount = (): number => activeSessions.size;
+
+/**
+ * Start a mongoose session that is registered for graceful-shutdown
+ * draining. Prefer this over `mongoose.startSession()` for any work that
+ * must finish (or be waited on) before the process exits.
+ */
+export const startTrackedSession = async (): Promise<ClientSession> => {
+  const session = await mongoose.startSession();
+  activeSessions.add(session);
+
+  const originalEndSession = session.endSession.bind(session);
+  session.endSession = (async (
+    ...args: Parameters<ClientSession['endSession']>
+  ): Promise<void> => {
+    activeSessions.delete(session);
+    await originalEndSession(...args);
+  }) as ClientSession['endSession'];
+
+  return session;
+};
+
+/**
+ * Poll until all tracked sessions have ended, or until `timeoutMs` elapses.
+ * Does not abort sessions — callers should finish or abort their own work.
+ */
+export const waitForActiveTransactions = async (timeoutMs: number): Promise<void> => {
+  const deadline = Date.now() + timeoutMs;
+  const pollMs = 100;
+
+  while (activeSessions.size > 0 && Date.now() < deadline) {
+    logger.info(
+      `[Database] Waiting for ${activeSessions.size} active transaction session(s)...`,
+    );
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+
+  if (activeSessions.size > 0) {
+    logger.warn(
+      `[Database] Proceeding with ${activeSessions.size} active session(s) still open`,
+    );
+  } else {
+    logger.info('[Database] Active transaction sessions drained');
+  }
+};
+
+/**
+ * Close the mongoose connection after outstanding buffered operations
+ * complete (`force = false`). Safe to call when already disconnected.
+ */
+export const disconnectDatabase = async (): Promise<void> => {
+  if (mongoose.connection.readyState === 0) {
+    logger.info('[Database] MongoDB already disconnected');
+    return;
+  }
+
+  await mongoose.connection.close(false);
+  logger.info('[Database] MongoDB connection closed');
+};
+
 export const connectDatabase = async (): Promise<void> => {
   try {
     const mongoUri = env.MONGODB_URI;
@@ -31,11 +94,8 @@ export const connectDatabase = async (): Promise<void> => {
       logger.info(`MongoDB connected to ${mongoose.connection.host}`);
     });
 
-    process.on('SIGINT', async () => {
-      await mongoose.connection.close();
-      logger.info('MongoDB connection closed through app termination');
-      process.exit(0);
-    });
+    // SIGINT / SIGTERM are handled centrally by GracefulShutdownService so
+    // we do not register a competing process.exit handler here.
   } catch (error) {
     logger.error('❌ Failed to connect to MongoDB:', error);
     process.exit(1);

src/config/database.ts

@@ -0,0 +1,42 @@
+import Redis from 'ioredis';
+import env from './env';
+import logger from './logger';
+
+/**
+ * Lazily-created Redis client singleton.
+ *
+ * The client is only instantiated when REDIS_URL is present in the
+ * environment.  When absent, `redisClient` is `null` and the idempotency
+ * service falls back to the MongoDB-backed store automatically.
+ *
+ * Connection errors are logged but never crash the process — the fallback
+ * path ensures the API keeps running even if Redis is temporarily unavailable.
+ */
+let redisClient: Redis | null = null;
+
+if (env.REDIS_URL) {
+  redisClient = new Redis(env.REDIS_URL, {
+    // Retry with exponential back-off, capped at 10 s, up to 10 attempts.
+    retryStrategy: (times: number): number | null => {
+      if (times > 10) {
+        logger.error('[Redis] Max reconnection attempts reached — giving up');
+        return null; // stop retrying
+      }
+      return Math.min(times * 200, 10_000);
+    },
+    // Surface connection errors rather than swallowing them silently.
+    enableOfflineQueue: false,
+    lazyConnect: false,
+    maxRetriesPerRequest: 3,
+  });
+
+  redisClient.on('connect', () => logger.info('[Redis] Connected'));
+  redisClient.on('ready', () => logger.info('[Redis] Ready'));
+  redisClient.on('error', (err: Error) => logger.error('[Redis] Error:', err.message));
+  redisClient.on('close', () => logger.warn('[Redis] Connection closed'));
+  redisClient.on('reconnecting', () => logger.info('[Redis] Reconnecting…'));
+} else {
+  logger.info('[Redis] REDIS_URL not set — idempotency will use MongoDB fallback store');
+}
+
+export default redisClient;