@tumbaland/backend-core 1.19.0 → 1.21.0

package/dist/database/connection.d.ts

@@ -1,3 +1,14 @@
-export declare const connectDB: (serviceName?: string, uri?: string) => Promise<void>;
+export interface ConnectDBOptions {
+    /**
+     * How many times to try before giving up. Defaults to Infinity: a service that
+     * boots before the host's network is up must keep trying, not die once.
+     */
+    maxAttempts?: number;
+    /** Backoff delay for the first retry. Doubles per attempt up to maxDelayMs. */
+    initialDelayMs?: number;
+    /** Ceiling for the backoff delay. */
+    maxDelayMs?: number;
+}
+export declare const connectDB: (serviceName?: string, uri?: string, options?: ConnectDBOptions) => Promise<void>;
 export declare const disconnectDB: (serviceName?: string) => Promise<void>;
 //# sourceMappingURL=connection.d.ts.map

package/dist/database/connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/database/connection.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,SAAS,GAAU,cAAc,MAAM,EAAE,MAAM,MAAM,KAAG,OAAO,CAAC,IAAI,CA6BhF,CAAC;AAEF,eAAO,MAAM,YAAY,GAAU,cAAc,MAAM,KAAG,OAAO,CAAC,IAAI,CASrE,CAAC"}
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/database/connection.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAeD,eAAO,MAAM,SAAS,GACpB,cAAc,MAAM,EACpB,MAAM,MAAM,EACZ,UAAS,gBAAqB,KAC7B,OAAO,CAAC,IAAI,CAgBd,CAAC;AAoEF,eAAO,MAAM,YAAY,GAAU,cAAc,MAAM,KAAG,OAAO,CAAC,IAAI,CASrE,CAAC"}

package/dist/database/connection.js

@@ -6,34 +6,88 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.disconnectDB = exports.connectDB = void 0;
 const mongoose_1 = __importDefault(require("mongoose"));
 const logger_1 = __importDefault(require("../logging/logger"));
+const DEFAULT_INITIAL_DELAY_MS = 1000;
+const DEFAULT_MAX_DELAY_MS = 30000;
 let connected = false;
-const connectDB = async (serviceName, uri) => {
+/**
+ * Set while a retry loop is running so concurrent callers await that loop
+ * instead of starting a second one against the same mongoose singleton.
+ */
+let pending = null;
+let listenersRegistered = false;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const connectDB = async (serviceName, uri, options = {}) => {
     if (connected)
         return;
+    if (pending)
+        return pending;
     const mongoUri = uri || process.env.MONGODB_URI;
+    // A missing URI is a config error, not a transient one — retrying can never
+    // fix it, so fail immediately rather than looping forever on a typo.
     if (!mongoUri) {
         throw new Error('MONGODB_URI environment variable is not set');
     }
-    try {
-        await mongoose_1.default.connect(mongoUri);
-        connected = true;
-        logger_1.default.info('MongoDB connected', { service: serviceName });
-        mongoose_1.default.connection.on('error', (err) => {
-            logger_1.default.error('MongoDB connection error', { service: serviceName, error: err.message });
-        });
-        mongoose_1.default.connection.on('disconnected', () => {
-            logger_1.default.warn('MongoDB disconnected', { service: serviceName });
-        });
-        mongoose_1.default.connection.on('reconnected', () => {
-            logger_1.default.info('MongoDB reconnected', { service: serviceName });
-        });
-    }
-    catch (error) {
-        logger_1.default.error('Failed to connect to MongoDB', { service: serviceName, error: error.message });
-        throw error;
-    }
+    pending = connectWithRetry(mongoUri, serviceName, options).finally(() => {
+        pending = null;
+    });
+    return pending;
 };
 exports.connectDB = connectDB;
+async function connectWithRetry(mongoUri, serviceName, options) {
+    const maxAttempts = options.maxAttempts ?? Infinity;
+    const initialDelayMs = options.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS;
+    const maxDelayMs = options.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+    for (let attempt = 1;; attempt++) {
+        try {
+            await mongoose_1.default.connect(mongoUri);
+            connected = true;
+            registerConnectionListeners(serviceName);
+            logger_1.default.info('MongoDB connected', { service: serviceName });
+            return;
+        }
+        catch (error) {
+            const message = error.message;
+            if (attempt >= maxAttempts) {
+                logger_1.default.error('Failed to connect to MongoDB, giving up', {
+                    service: serviceName,
+                    attempt,
+                    error: message
+                });
+                throw error;
+            }
+            // Exponential backoff, capped: a Mongo outage lasting hours shouldn't
+            // grow the gap past maxDelayMs and leave the service down long after
+            // the database comes back.
+            const delayMs = Math.min(initialDelayMs * 2 ** (attempt - 1), maxDelayMs);
+            logger_1.default.warn('Failed to connect to MongoDB, retrying', {
+                service: serviceName,
+                attempt,
+                delayMs,
+                error: message
+            });
+            await sleep(delayMs);
+        }
+    }
+}
+/**
+ * Mongoose reconnects on its own once an initial connection has succeeded, so
+ * these only report state — but without them a drop is silent and the only
+ * symptom is the health endpoint flipping to "disconnected".
+ */
+function registerConnectionListeners(serviceName) {
+    if (listenersRegistered)
+        return;
+    listenersRegistered = true;
+    mongoose_1.default.connection.on('error', (err) => {
+        logger_1.default.error('MongoDB connection error', { service: serviceName, error: err.message });
+    });
+    mongoose_1.default.connection.on('disconnected', () => {
+        logger_1.default.warn('MongoDB disconnected', { service: serviceName });
+    });
+    mongoose_1.default.connection.on('reconnected', () => {
+        logger_1.default.info('MongoDB reconnected', { service: serviceName });
+    });
+}
 const disconnectDB = async (serviceName) => {
     try {
         await mongoose_1.default.connection.close();

package/dist/database/connection.js.map

@@ -1 +1 @@
-{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/database/connection.ts"],"names":[],"mappings":";;;;;;AAAA,wDAAgC;AAChC,+DAAuC;AAEvC,IAAI,SAAS,GAAG,KAAK,CAAC;AAEf,MAAM,SAAS,GAAG,KAAK,EAAE,WAAoB,EAAE,GAAY,EAAiB,EAAE;IACnF,IAAI,SAAS;QAAE,OAAO;IAEtB,MAAM,QAAQ,GAAG,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;IAChD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACjE,CAAC;IAED,IAAI,CAAC;QACH,MAAM,kBAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACjC,SAAS,GAAG,IAAI,CAAC;QAEjB,gBAAM,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;QAE3D,kBAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAU,EAAE,EAAE;YAC7C,gBAAM,CAAC,KAAK,CAAC,0BAA0B,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACzF,CAAC,CAAC,CAAC;QAEH,kBAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,cAAc,EAAE,GAAG,EAAE;YAC1C,gBAAM,CAAC,IAAI,CAAC,sBAAsB,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;QAChE,CAAC,CAAC,CAAC;QAEH,kBAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,aAAa,EAAE,GAAG,EAAE;YACzC,gBAAM,CAAC,IAAI,CAAC,qBAAqB,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;QAC/D,CAAC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,gBAAM,CAAC,KAAK,CAAC,8BAA8B,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAG,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QACxG,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC,CAAC;AA7BW,QAAA,SAAS,aA6BpB;AAEK,MAAM,YAAY,GAAG,KAAK,EAAE,WAAoB,EAAiB,EAAE;IACxE,IAAI,CAAC;QACH,MAAM,kBAAQ,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QAClC,SAAS,GAAG,KAAK,CAAC;QAClB,gBAAM,CAAC,IAAI,CAAC,2BAA2B,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;IACrE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,gBAAM,CAAC,KAAK,CAAC,kCAAkC,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAG,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QAC5G,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC,CAAC;AATW,QAAA,YAAY,gBASvB"}
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/database/connection.ts"],"names":[],"mappings":"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"}

package/dist/middleware/security.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../src/middleware/security.ts"],"names":[],"mappings":"AACA,OAAkB,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE5E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,gGA4Bi/H,CAAC,2BAxB5gI,CAAC;AAEH;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,OAAO,CAAC,gBAAgB,CAAM,wDASxE;AAED,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,sDAAsB,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,sDAAiC,CAAC"}
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../src/middleware/security.ts"],"names":[],"mappings":"AACA,OAAkB,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE5E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,gGA4BshH,CAAC,2BAxBjjH,CAAC;AAEH;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,OAAO,CAAC,gBAAgB,CAAM,wDASxE;AAED,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,sDAAsB,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,sDAAiC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tumbaland/backend-core",
-  "version": "1.19.0",
+  "version": "1.21.0",
   "description": "Core shared functionality for Tumbaland backend services",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,8 +9,8 @@
     "dev": "tsc --watch",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run clean && npm run build",
-    "release": "standard-version && npm run build && npm publish --access public",
-    "release:beta": "standard-version --prerelease beta && npm run build && npm publish --access public --tag beta",
+    "release": "commit-and-tag-version && npm run build && npm publish --access public && node ../../scripts/sync-lib-versions.mjs",
+    "release:beta": "commit-and-tag-version --prerelease beta && npm run build && npm publish --access public --tag beta",
     "test": "jest",
     "test:coverage": "jest --coverage",
     "lint": "eslint .",
@@ -25,7 +25,7 @@
   ],
   "author": "Tumbaland Team",
   "license": "MIT",
-  "standard-version": {
+  "commit-and-tag-version": {
     "tagPrefix": "backend-core-v"
   },
   "devDependencies": {
@@ -35,7 +35,7 @@
     "@types/jsonwebtoken": "^9.0.10",
     "@types/morgan": "^1.9.10",
     "@types/node": "^26.1.0",
-    "standard-version": "^9.5.0",
+    "commit-and-tag-version": "^13.1.2",
     "typescript": "^6.0.3"
   },
   "dependencies": {

package/src/database/connection.test.ts

@@ -89,18 +89,72 @@ describe('connectDB', () => {
     expect(mongoose.connect).toHaveBeenCalledTimes(1);
   });
 
-  it('logs and rethrows when mongoose.connect fails', async () => {
+  it('logs and rethrows when mongoose.connect fails on the last allowed attempt', async () => {
     process.env.MONGODB_URI = 'mongodb://env-uri';
     const { connectDB, mongoose, logger } = await freshConnectDB();
     (mongoose.connect as jest.Mock).mockRejectedValueOnce(new Error('ECONNREFUSED'));
 
-    await expect(connectDB('my-service')).rejects.toThrow('ECONNREFUSED');
-    expect(logger.error).toHaveBeenCalledWith('Failed to connect to MongoDB', {
+    await expect(connectDB('my-service', undefined, { maxAttempts: 1 })).rejects.toThrow('ECONNREFUSED');
+    expect(logger.error).toHaveBeenCalledWith('Failed to connect to MongoDB, giving up', {
       service: 'my-service',
+      attempt: 1,
       error: 'ECONNREFUSED'
     });
   });
 
+  it('retries a failing connection until it succeeds', async () => {
+    process.env.MONGODB_URI = 'mongodb://env-uri';
+    const { connectDB, mongoose, logger } = await freshConnectDB();
+    (mongoose.connect as jest.Mock)
+      .mockRejectedValueOnce(new Error('getaddrinfo EAI_AGAIN'))
+      .mockRejectedValueOnce(new Error('getaddrinfo EAI_AGAIN'));
+
+    await connectDB('my-service', undefined, { initialDelayMs: 0 });
+
+    expect(mongoose.connect).toHaveBeenCalledTimes(3);
+    expect(logger.warn).toHaveBeenCalledTimes(2);
+    expect(logger.info).toHaveBeenCalledWith('MongoDB connected', { service: 'my-service' });
+  });
+
+  it('gives up after maxAttempts', async () => {
+    process.env.MONGODB_URI = 'mongodb://env-uri';
+    const { connectDB, mongoose } = await freshConnectDB();
+    (mongoose.connect as jest.Mock).mockRejectedValue(new Error('auth failed'));
+
+    await expect(
+      connectDB('my-service', undefined, { maxAttempts: 3, initialDelayMs: 0 })
+    ).rejects.toThrow('auth failed');
+
+    expect(mongoose.connect).toHaveBeenCalledTimes(3);
+  });
+
+  it('caps the backoff delay at maxDelayMs', async () => {
+    process.env.MONGODB_URI = 'mongodb://env-uri';
+    const { connectDB, mongoose, logger } = await freshConnectDB();
+    (mongoose.connect as jest.Mock)
+      .mockRejectedValueOnce(new Error('down'))
+      .mockRejectedValueOnce(new Error('down'))
+      .mockRejectedValueOnce(new Error('down'));
+
+    await connectDB('my-service', undefined, { initialDelayMs: 1, maxDelayMs: 2 });
+
+    const delays = (logger.warn as jest.Mock).mock.calls.map((call) => call[1].delayMs);
+    expect(delays).toEqual([1, 2, 2]);
+  });
+
+  it('lets concurrent callers share one retry loop', async () => {
+    process.env.MONGODB_URI = 'mongodb://env-uri';
+    const { connectDB, mongoose } = await freshConnectDB();
+    (mongoose.connect as jest.Mock).mockRejectedValueOnce(new Error('not ready'));
+
+    await Promise.all([
+      connectDB('my-service', undefined, { initialDelayMs: 0 }),
+      connectDB('my-service', undefined, { initialDelayMs: 0 })
+    ]);
+
+    expect(mongoose.connect).toHaveBeenCalledTimes(2);
+  });
+
   it('registers error/disconnected/reconnected handlers that log through the shared logger', async () => {
     process.env.MONGODB_URI = 'mongodb://env-uri';
     const { connectDB, logger } = await freshConnectDB();

package/src/database/connection.ts

@@ -1,38 +1,118 @@
 import mongoose from 'mongoose';
 import logger from '../logging/logger';
 
+export interface ConnectDBOptions {
+  /**
+   * How many times to try before giving up. Defaults to Infinity: a service that
+   * boots before the host's network is up must keep trying, not die once.
+   */
+  maxAttempts?: number;
+  /** Backoff delay for the first retry. Doubles per attempt up to maxDelayMs. */
+  initialDelayMs?: number;
+  /** Ceiling for the backoff delay. */
+  maxDelayMs?: number;
+}
+
+const DEFAULT_INITIAL_DELAY_MS = 1000;
+const DEFAULT_MAX_DELAY_MS = 30000;
+
 let connected = false;
+/**
+ * Set while a retry loop is running so concurrent callers await that loop
+ * instead of starting a second one against the same mongoose singleton.
+ */
+let pending: Promise<void> | null = null;
+let listenersRegistered = false;
 
-export const connectDB = async (serviceName?: string, uri?: string): Promise<void> => {
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+export const connectDB = async (
+  serviceName?: string,
+  uri?: string,
+  options: ConnectDBOptions = {}
+): Promise<void> => {
   if (connected) return;
+  if (pending) return pending;
 
   const mongoUri = uri || process.env.MONGODB_URI;
+  // A missing URI is a config error, not a transient one — retrying can never
+  // fix it, so fail immediately rather than looping forever on a typo.
   if (!mongoUri) {
     throw new Error('MONGODB_URI environment variable is not set');
   }
 
-  try {
-    await mongoose.connect(mongoUri);
-    connected = true;
+  pending = connectWithRetry(mongoUri, serviceName, options).finally(() => {
+    pending = null;
+  });
 
-    logger.info('MongoDB connected', { service: serviceName });
+  return pending;
+};
 
-    mongoose.connection.on('error', (err: Error) => {
-      logger.error('MongoDB connection error', { service: serviceName, error: err.message });
-    });
+async function connectWithRetry(
+  mongoUri: string,
+  serviceName: string | undefined,
+  options: ConnectDBOptions
+): Promise<void> {
+  const maxAttempts = options.maxAttempts ?? Infinity;
+  const initialDelayMs = options.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS;
+  const maxDelayMs = options.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
 
-    mongoose.connection.on('disconnected', () => {
-      logger.warn('MongoDB disconnected', { service: serviceName });
-    });
+  for (let attempt = 1; ; attempt++) {
+    try {
+      await mongoose.connect(mongoUri);
+      connected = true;
 
-    mongoose.connection.on('reconnected', () => {
-      logger.info('MongoDB reconnected', { service: serviceName });
-    });
-  } catch (error) {
-    logger.error('Failed to connect to MongoDB', { service: serviceName, error: (error as Error).message });
-    throw error;
+      registerConnectionListeners(serviceName);
+      logger.info('MongoDB connected', { service: serviceName });
+      return;
+    } catch (error) {
+      const message = (error as Error).message;
+
+      if (attempt >= maxAttempts) {
+        logger.error('Failed to connect to MongoDB, giving up', {
+          service: serviceName,
+          attempt,
+          error: message
+        });
+        throw error;
+      }
+
+      // Exponential backoff, capped: a Mongo outage lasting hours shouldn't
+      // grow the gap past maxDelayMs and leave the service down long after
+      // the database comes back.
+      const delayMs = Math.min(initialDelayMs * 2 ** (attempt - 1), maxDelayMs);
+      logger.warn('Failed to connect to MongoDB, retrying', {
+        service: serviceName,
+        attempt,
+        delayMs,
+        error: message
+      });
+      await sleep(delayMs);
+    }
   }
-};
+}
+
+/**
+ * Mongoose reconnects on its own once an initial connection has succeeded, so
+ * these only report state — but without them a drop is silent and the only
+ * symptom is the health endpoint flipping to "disconnected".
+ */
+function registerConnectionListeners(serviceName?: string): void {
+  if (listenersRegistered) return;
+  listenersRegistered = true;
+
+  mongoose.connection.on('error', (err: Error) => {
+    logger.error('MongoDB connection error', { service: serviceName, error: err.message });
+  });
+
+  mongoose.connection.on('disconnected', () => {
+    logger.warn('MongoDB disconnected', { service: serviceName });
+  });
+
+  mongoose.connection.on('reconnected', () => {
+    logger.info('MongoDB reconnected', { service: serviceName });
+  });
+}
 
 export const disconnectDB = async (serviceName?: string): Promise<void> => {
   try {