@tumbaland/backend-core 1.16.0

package/src/config/env.test.ts

@@ -0,0 +1,28 @@
+import { requireEnv } from './env';
+
+describe('requireEnv', () => {
+  const ORIGINAL_ENV = process.env;
+
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+  });
+
+  afterAll(() => {
+    process.env = ORIGINAL_ENV;
+  });
+
+  it('returns the value when the variable is set', () => {
+    process.env.MY_VAR = 'hello';
+    expect(requireEnv('MY_VAR')).toBe('hello');
+  });
+
+  it('throws when the variable is missing', () => {
+    delete process.env.MY_VAR;
+    expect(() => requireEnv('MY_VAR')).toThrow('Missing required environment variable: MY_VAR');
+  });
+
+  it('throws when the variable is an empty string', () => {
+    process.env.MY_VAR = '';
+    expect(() => requireEnv('MY_VAR')).toThrow('Missing required environment variable: MY_VAR');
+  });
+});

package/src/config/env.ts

@@ -0,0 +1,13 @@
+/**
+ * Returns the value of a required environment variable.
+ * Throws if the variable is missing or empty — call at service startup
+ * (after dotenv.config()) so misconfigured services fail fast instead of
+ * running with insecure defaults.
+ */
+export function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${name}`);
+  }
+  return value;
+}

package/src/database/connection.test.ts

@@ -0,0 +1,142 @@
+jest.mock('../logging/logger', () => ({
+  __esModule: true,
+  default: { info: jest.fn(), error: jest.fn(), warn: jest.fn(), debug: jest.fn(), http: jest.fn() }
+}));
+
+const connectionHandlers: Record<string, (...args: any[]) => void> = {};
+
+jest.mock('mongoose', () => ({
+  __esModule: true,
+  default: {
+    connect: jest.fn(),
+    connection: {
+      on: jest.fn((event: string, handler: (...args: any[]) => void) => {
+        connectionHandlers[event] = handler;
+      }),
+      close: jest.fn()
+    }
+  }
+}));
+
+import mongoose from 'mongoose';
+import logger from '../logging/logger';
+import { disconnectDB } from './connection';
+
+/**
+ * `connection.ts` keeps a module-level `connected` flag, so each connectDB
+ * scenario needs its own fresh copy of the module (and of its mongoose/logger
+ * mocks) — isolateModulesAsync sandboxes that without leaking into other
+ * tests in this file the way a blanket jest.resetModules() would.
+ */
+async function freshConnectDB() {
+  let connectDBFn!: typeof import('./connection').connectDB;
+  let mongooseMock!: typeof mongoose;
+  let loggerMock!: typeof logger;
+
+  await jest.isolateModulesAsync(async () => {
+    mongooseMock = (await import('mongoose')).default as unknown as typeof mongoose;
+    loggerMock = (await import('../logging/logger')).default as unknown as typeof logger;
+    connectDBFn = (await import('./connection')).connectDB;
+  });
+
+  return { connectDB: connectDBFn, mongoose: mongooseMock, logger: loggerMock };
+}
+
+describe('connectDB', () => {
+  const ORIGINAL_ENV = process.env;
+
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+    delete process.env.MONGODB_URI;
+    for (const key of Object.keys(connectionHandlers)) delete connectionHandlers[key];
+  });
+
+  afterAll(() => {
+    process.env = ORIGINAL_ENV;
+  });
+
+  it('throws when no MongoDB URI is available', async () => {
+    const { connectDB } = await freshConnectDB();
+    await expect(connectDB('my-service')).rejects.toThrow('MONGODB_URI environment variable is not set');
+  });
+
+  it('connects using the explicit uri argument over the env var', async () => {
+    process.env.MONGODB_URI = 'mongodb://env-uri';
+    const { connectDB, mongoose, logger } = await freshConnectDB();
+
+    await connectDB('my-service', 'mongodb://explicit-uri');
+
+    expect(mongoose.connect).toHaveBeenCalledWith('mongodb://explicit-uri');
+    expect(logger.info).toHaveBeenCalledWith('MongoDB connected', { service: 'my-service' });
+  });
+
+  it('falls back to MONGODB_URI when no explicit uri is given', async () => {
+    process.env.MONGODB_URI = 'mongodb://env-uri';
+    const { connectDB, mongoose } = await freshConnectDB();
+
+    await connectDB('my-service');
+
+    expect(mongoose.connect).toHaveBeenCalledWith('mongodb://env-uri');
+  });
+
+  it('is a no-op on a second call once already connected', async () => {
+    process.env.MONGODB_URI = 'mongodb://env-uri';
+    const { connectDB, mongoose } = await freshConnectDB();
+
+    await connectDB('my-service');
+    await connectDB('my-service');
+
+    expect(mongoose.connect).toHaveBeenCalledTimes(1);
+  });
+
+  it('logs and rethrows when mongoose.connect fails', 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', {
+      service: 'my-service',
+      error: 'ECONNREFUSED'
+    });
+  });
+
+  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();
+
+    await connectDB('my-service');
+
+    connectionHandlers.error(new Error('boom'));
+    expect(logger.error).toHaveBeenCalledWith('MongoDB connection error', { service: 'my-service', error: 'boom' });
+
+    connectionHandlers.disconnected();
+    expect(logger.warn).toHaveBeenCalledWith('MongoDB disconnected', { service: 'my-service' });
+
+    connectionHandlers.reconnected();
+    expect(logger.info).toHaveBeenCalledWith('MongoDB reconnected', { service: 'my-service' });
+  });
+});
+
+describe('disconnectDB', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('closes the connection and logs success', async () => {
+    await disconnectDB('my-service');
+
+    expect(mongoose.connection.close).toHaveBeenCalled();
+    expect(logger.info).toHaveBeenCalledWith('MongoDB connection closed', { service: 'my-service' });
+  });
+
+  it('logs and rethrows when closing fails', async () => {
+    (mongoose.connection.close as jest.Mock).mockRejectedValueOnce(new Error('close failed'));
+
+    await expect(disconnectDB('my-service')).rejects.toThrow('close failed');
+    expect(logger.error).toHaveBeenCalledWith('Error closing MongoDB connection', {
+      service: 'my-service',
+      error: 'close failed'
+    });
+  });
+});

package/src/database/connection.ts

@@ -0,0 +1,46 @@
+import mongoose from 'mongoose';
+import logger from '../logging/logger';
+
+let connected = false;
+
+export const connectDB = async (serviceName?: string, uri?: string): Promise<void> => {
+  if (connected) return;
+
+  const mongoUri = uri || process.env.MONGODB_URI;
+  if (!mongoUri) {
+    throw new Error('MONGODB_URI environment variable is not set');
+  }
+
+  try {
+    await mongoose.connect(mongoUri);
+    connected = true;
+
+    logger.info('MongoDB connected', { service: serviceName });
+
+    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 });
+    });
+  } catch (error) {
+    logger.error('Failed to connect to MongoDB', { service: serviceName, error: (error as Error).message });
+    throw error;
+  }
+};
+
+export const disconnectDB = async (serviceName?: string): Promise<void> => {
+  try {
+    await mongoose.connection.close();
+    connected = false;
+    logger.info('MongoDB connection closed', { service: serviceName });
+  } catch (error) {
+    logger.error('Error closing MongoDB connection', { service: serviceName, error: (error as Error).message });
+    throw error;
+  }
+};

package/src/errors/HttpError.test.ts

@@ -0,0 +1,38 @@
+import { HttpError, BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, TooManyRequestsError } from './HttpError';
+
+describe('HttpError', () => {
+  it('carries the given status code and message', () => {
+    const error = new HttpError(418, "I'm a teapot");
+    expect(error.statusCode).toBe(418);
+    expect(error.message).toBe("I'm a teapot");
+    expect(error).toBeInstanceOf(Error);
+  });
+
+  it('sets name to the concrete subclass name', () => {
+    expect(new HttpError(400, 'x').name).toBe('HttpError');
+  });
+});
+
+describe.each([
+  [BadRequestError, 400, 'Bad request'],
+  [UnauthorizedError, 401, 'Unauthorized'],
+  [ForbiddenError, 403, 'Access denied'],
+  [NotFoundError, 404, 'Not found'],
+  [ConflictError, 409, 'Conflict'],
+  [TooManyRequestsError, 429, 'Too many requests']
+] as const)('%p', (ErrorClass, expectedStatus, defaultMessage) => {
+  it(`defaults to status ${expectedStatus} and a sensible message`, () => {
+    const error = new ErrorClass();
+    expect(error.statusCode).toBe(expectedStatus);
+    expect(error.message).toBe(defaultMessage);
+    expect(error).toBeInstanceOf(HttpError);
+    expect(error).toBeInstanceOf(Error);
+    expect(error.name).toBe(ErrorClass.name);
+  });
+
+  it('accepts a custom message', () => {
+    const error = new ErrorClass('custom message');
+    expect(error.statusCode).toBe(expectedStatus);
+    expect(error.message).toBe('custom message');
+  });
+});

package/src/errors/HttpError.ts

@@ -0,0 +1,57 @@
+/**
+ * Base class for errors that should be turned into a specific HTTP response
+ * by the shared errorHandler, instead of every controller hand-rolling
+ * try/catch + string-matching on error.message to pick a status code.
+ *
+ * Express 5 forwards rejected promises from async route handlers to the
+ * mounted error handler automatically, so controllers can just
+ * `throw new NotFoundError(...)` and stop wrapping in try/catch.
+ */
+export class HttpError extends Error {
+  statusCode: number;
+
+  constructor(statusCode: number, message: string) {
+    super(message);
+    this.name = new.target.name;
+    this.statusCode = statusCode;
+    // Restore the prototype chain (needed when compiling to ES2018 targets
+    // where `extends Error` doesn't preserve instanceof checks correctly).
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class BadRequestError extends HttpError {
+  constructor(message = 'Bad request') {
+    super(400, message);
+  }
+}
+
+export class UnauthorizedError extends HttpError {
+  constructor(message = 'Unauthorized') {
+    super(401, message);
+  }
+}
+
+export class ForbiddenError extends HttpError {
+  constructor(message = 'Access denied') {
+    super(403, message);
+  }
+}
+
+export class NotFoundError extends HttpError {
+  constructor(message = 'Not found') {
+    super(404, message);
+  }
+}
+
+export class ConflictError extends HttpError {
+  constructor(message = 'Conflict') {
+    super(409, message);
+  }
+}
+
+export class TooManyRequestsError extends HttpError {
+  constructor(message = 'Too many requests') {
+    super(429, message);
+  }
+}

package/src/health/healthController.test.ts

@@ -0,0 +1,91 @@
+import { Request, Response } from 'express';
+import mongoose from 'mongoose';
+import { healthCheck, healthLive } from './healthController';
+
+function mockRes(): Response {
+  const res: Partial<Response> = {};
+  res.status = jest.fn().mockReturnValue(res);
+  res.json = jest.fn().mockReturnValue(res);
+  return res as Response;
+}
+
+describe('healthLive', () => {
+  it('always responds 200 ok, independent of any dependency state', () => {
+    const res = mockRes();
+    healthLive({} as Request, res);
+
+    expect(res.status).toHaveBeenCalledWith(200);
+    expect(res.json).toHaveBeenCalledWith({ status: 'ok' });
+  });
+});
+
+describe('healthCheck', () => {
+  const ORIGINAL_ENV = process.env;
+
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+  });
+
+  afterAll(() => {
+    process.env = ORIGINAL_ENV;
+  });
+
+  it('responds 200 with dependencies.mongodb "connected" when Mongo readyState is 1', async () => {
+    jest.spyOn(mongoose, 'connection', 'get').mockReturnValue({ readyState: 1 } as any);
+    process.env.SERVICE_NAME = 'album-service';
+    const res = mockRes();
+
+    await healthCheck({} as Request, res);
+
+    expect(res.status).toHaveBeenCalledWith(200);
+    expect(res.json).toHaveBeenCalledWith(
+      expect.objectContaining({
+        status: 'ok',
+        service: 'album-service',
+        dependencies: { mongodb: 'connected' }
+      })
+    );
+  });
+
+  it('responds 503 with dependencies.mongodb "disconnected" when Mongo readyState is not 1', async () => {
+    jest.spyOn(mongoose, 'connection', 'get').mockReturnValue({ readyState: 0 } as any);
+    const res = mockRes();
+
+    await healthCheck({} as Request, res);
+
+    expect(res.status).toHaveBeenCalledWith(503);
+    expect(res.json).toHaveBeenCalledWith(
+      expect.objectContaining({ status: 'error', dependencies: { mongodb: 'disconnected' } })
+    );
+  });
+
+  it('falls back to default service/version/description when env vars are unset', async () => {
+    delete process.env.SERVICE_NAME;
+    delete process.env.npm_package_version;
+    delete process.env.SERVICE_DESCRIPTION;
+    jest.spyOn(mongoose, 'connection', 'get').mockReturnValue({ readyState: 1 } as any);
+    const res = mockRes();
+
+    await healthCheck({} as Request, res);
+
+    expect(res.json).toHaveBeenCalledWith(
+      expect.objectContaining({
+        service: 'unknown-service',
+        version: '1.0.0',
+        description: 'Backend service'
+      })
+    );
+  });
+
+  it('responds 503 with a generic error body when reading connection state throws', async () => {
+    jest.spyOn(mongoose, 'connection', 'get').mockImplementation(() => {
+      throw new Error('boom');
+    });
+    const res = mockRes();
+
+    await healthCheck({} as Request, res);
+
+    expect(res.status).toHaveBeenCalledWith(503);
+    expect(res.json).toHaveBeenCalledWith(expect.objectContaining({ status: 'error', error: 'Health check failed' }));
+  });
+});

package/src/health/healthController.ts

@@ -0,0 +1,56 @@
+import { Request, Response } from 'express';
+import mongoose from 'mongoose';
+import { metricsHandler } from '../metrics';
+
+/**
+ * Health check endpoint with database connectivity
+ * Returns comprehensive health status for monitoring
+ */
+export const healthCheck = async (req: Request, res: Response) => {
+  try {
+    // Check MongoDB connection
+    const mongoState = mongoose.connection.readyState;
+    const isMongoHealthy = mongoState === 1; // 1 = connected
+
+    const healthResponse = {
+      status: isMongoHealthy ? 'ok' : 'error',
+      service: process.env.SERVICE_NAME || 'unknown-service',
+      type: 'backend',
+      timestamp: new Date().toISOString(),
+      version: process.env.npm_package_version || '1.0.0',
+      description: process.env.SERVICE_DESCRIPTION || 'Backend service',
+      dependencies: {
+        mongodb: isMongoHealthy ? 'connected' : 'disconnected'
+      }
+    };
+
+    res.status(isMongoHealthy ? 200 : 503).json(healthResponse);
+  } catch (error) {
+    res.status(503).json({
+      status: 'error',
+      service: process.env.SERVICE_NAME || 'unknown-service',
+      type: 'backend',
+      timestamp: new Date().toISOString(),
+      version: process.env.npm_package_version || '1.0.0',
+      description: process.env.SERVICE_DESCRIPTION || 'Backend service',
+      error: 'Health check failed'
+    });
+  }
+};
+
+/**
+ * Liveness check: confirms the process is up and serving HTTP, without
+ * touching MongoDB or any other dependency. Used by the Docker-level
+ * HEALTHCHECK so a transient DB outage doesn't get reported as the
+ * container itself being unhealthy — `/health` (above) is the DB-aware
+ * readiness check for dashboards/monitoring.
+ */
+export const healthLive = (req: Request, res: Response) => {
+  res.status(200).json({ status: 'ok' });
+};
+
+/**
+ * Prometheus metrics endpoint
+ * Exposes application metrics for monitoring
+ */
+export { metricsHandler };

package/src/index.ts

@@ -0,0 +1,60 @@
+// @tumbaland/backend-core - Core shared functionality for Tumbaland backend services
+
+// App bootstrap
+export { createBaseApp } from './app/createBaseApp';
+export type { CreateBaseAppOptions } from './app/createBaseApp';
+
+// Logging
+export { default as logger } from './logging/logger';
+
+// Health checks
+export { healthCheck, healthLive, metricsHandler } from './health/healthController';
+
+// Database
+export { connectDB, disconnectDB } from './database/connection';
+
+// Config
+export { requireEnv } from './config/env';
+
+// Errors
+export { HttpError, BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, TooManyRequestsError } from './errors/HttpError';
+
+// Middleware
+export { authenticateToken } from './middleware/authMiddleware';
+export { createCorsMiddleware } from './middleware/corsMiddleware';
+export { errorHandler } from './middleware/errorHandler';
+export { requestLogger, requestLoggerWithMetrics, simpleRequestLogger } from './middleware/requestLogger';
+export { securityHeaders, createRateLimiter, standardRateLimiter, strictRateLimiter } from './middleware/security';
+export { validate } from './middleware/validate';
+
+// Types
+export type { UserPayload } from './types/auth';
+
+// Utils
+export { generateCorrelationId, correlationMiddleware } from './utils/correlation';
+export { createApiResponse, sendSuccess, sendError } from './utils/response';
+export type { ApiResponse } from './utils/response';
+
+// Metrics
+export {
+  metricsMiddleware,
+  httpRequestDuration,
+  httpRequestsTotal,
+  databaseQueryDuration,
+  databaseQueriesTotal,
+  businessMetrics,
+  register
+} from './metrics';
+
+// Tracing
+export {
+  initTracer,
+  getTracer,
+  startSpan,
+  tracingMiddleware,
+  createChildSpan,
+  logToSpan,
+  setSpanTag,
+  injectHeaders,
+  extractSpanContext
+} from './tracing';

package/src/logging/logger.test.ts

@@ -0,0 +1,76 @@
+import fs from 'fs';
+
+/**
+ * logger.ts builds its transport list at module-load time based on
+ * NODE_ENV/LOG_TO_FILE, so each scenario needs a fresh module load via
+ * isolateModulesAsync rather than a single shared import.
+ */
+async function loadLogger(env: Record<string, string | undefined>) {
+  const ORIGINAL_ENV = process.env;
+  process.env = { ...ORIGINAL_ENV, ...env };
+
+  let loggerModule!: typeof import('./logger').default;
+  await jest.isolateModulesAsync(async () => {
+    loggerModule = (await import('./logger')).default;
+  });
+
+  process.env = ORIGINAL_ENV;
+  return loggerModule;
+}
+
+// winston's `.transports` also holds the wrapped exception/rejection-handler
+// transports (always present), so assert on named regular transports only.
+function namedTransports(logger: import('winston').Logger, name: string) {
+  return logger.transports.filter((t) => (t as unknown as { name?: string }).name === name);
+}
+
+describe('logger', () => {
+  it('logs at debug level in development', async () => {
+    const logger = await loadLogger({ NODE_ENV: 'development', LOG_TO_FILE: undefined });
+    expect(logger.level).toBe('debug');
+  });
+
+  it('logs at info level in production', async () => {
+    const logger = await loadLogger({ NODE_ENV: 'production' });
+    expect(logger.level).toBe('info');
+  });
+
+  it('does not create a file transport when LOG_TO_FILE is unset', async () => {
+    const logger = await loadLogger({ NODE_ENV: 'development', LOG_TO_FILE: undefined });
+    expect(namedTransports(logger, 'file')).toHaveLength(0);
+    expect(namedTransports(logger, 'console')).toHaveLength(1);
+  });
+
+  it('does not create a file transport in production, even if LOG_TO_FILE is true', async () => {
+    const logger = await loadLogger({ NODE_ENV: 'production', LOG_TO_FILE: 'true' });
+    expect(namedTransports(logger, 'file')).toHaveLength(0);
+  });
+
+  describe('with LOG_TO_FILE=true in development', () => {
+    it('creates the logs directory when it does not exist and adds a file transport', async () => {
+      const existsSpy = jest.spyOn(fs, 'existsSync').mockReturnValue(false);
+      const mkdirSpy = jest.spyOn(fs, 'mkdirSync').mockImplementation(() => undefined as any);
+
+      const logger = await loadLogger({ NODE_ENV: 'development', LOG_TO_FILE: 'true' });
+
+      expect(mkdirSpy).toHaveBeenCalledWith(expect.stringContaining('logs'), { recursive: true });
+      expect(namedTransports(logger, 'file')).toHaveLength(1);
+
+      existsSpy.mockRestore();
+      mkdirSpy.mockRestore();
+    });
+
+    it('does not recreate the logs directory when it already exists', async () => {
+      const existsSpy = jest.spyOn(fs, 'existsSync').mockReturnValue(true);
+      const mkdirSpy = jest.spyOn(fs, 'mkdirSync').mockImplementation(() => undefined as any);
+
+      const logger = await loadLogger({ NODE_ENV: 'development', LOG_TO_FILE: 'true' });
+
+      expect(mkdirSpy).not.toHaveBeenCalled();
+      expect(namedTransports(logger, 'file')).toHaveLength(1);
+
+      existsSpy.mockRestore();
+      mkdirSpy.mockRestore();
+    });
+  });
+});