@tumbaland/backend-core 1.16.0

package/src/middleware/errorHandler.ts

@@ -0,0 +1,98 @@
+import { Request, Response, NextFunction, ErrorRequestHandler } from 'express';
+import logger from '../logging/logger';
+import { HttpError } from '../errors/HttpError';
+
+interface KnownError {
+  statusCode: number;
+  name: string;
+  message: string;
+}
+
+/**
+ * Recognizes error shapes that map to an obvious HTTP status without a
+ * controller having to catch and re-throw them: our own typed HttpError
+ * hierarchy, plus Mongoose's ValidationError (failed schema validation,
+ * e.g. a missing required field) and CastError (e.g. an invalid ObjectId
+ * string) — both of which are client mistakes, not server bugs, but throw
+ * as plain Mongoose error classes rather than anything of ours.
+ */
+function classifyError(error: Error): KnownError | null {
+  if (error instanceof HttpError) {
+    return { statusCode: error.statusCode, name: error.name, message: error.message };
+  }
+  if (error.name === 'ValidationError' || error.name === 'CastError') {
+    return { statusCode: 400, name: error.name, message: error.message };
+  }
+  return null;
+}
+
+/**
+ * Global error handler middleware.
+ *
+ * Controllers throw a typed `HttpError` (BadRequestError, NotFoundError,
+ * ForbiddenError, ...) instead of hand-rolling try/catch + string-matching
+ * on `error.message` to pick a status code — Express 5 forwards rejected
+ * promises from async route handlers here automatically. Anything that
+ * isn't a recognized error type is treated as an unexpected bug: logged
+ * with its full stack and returned as a generic 500 (no message leak
+ * outside development), same as before this file knew about HttpError.
+ */
+export const errorHandler: ErrorRequestHandler = (
+  error: Error,
+  req: Request,
+  res: Response,
+  _next: NextFunction
+): void => {
+  const known = classifyError(error);
+
+  if (known) {
+    // Client errors (4xx) are routine, expected control flow — log without
+    // a stack trace at warn level, not as if the service were broken.
+    logger.warn('Request failed:', {
+      error: known.message,
+      statusCode: known.statusCode,
+      url: req.url,
+      method: req.method,
+      correlationId: (req as any).correlationId
+    });
+  } else {
+    logger.error('Unhandled error:', {
+      error: error.message,
+      stack: error.stack,
+      url: req.url,
+      method: req.method,
+      ip: req.ip,
+      userAgent: req.get('User-Agent'),
+      correlationId: (req as any).correlationId
+    });
+  }
+
+  // Add CORS headers to error responses
+  const origin = req.headers.origin;
+  if (origin && (origin.includes('localhost') || origin.includes('tumbaland.eu'))) {
+    res.header('Access-Control-Allow-Origin', origin);
+    res.header('Access-Control-Allow-Credentials', 'true');
+    res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+    res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Requested-With, x-correlation-id, x-session-id');
+  }
+
+  if (known) {
+    res.status(known.statusCode).json({
+      success: false,
+      error: known.name,
+      message: known.message
+    });
+    return;
+  }
+
+  // Don't leak error details in production for unexpected errors
+  const isDevelopment = process.env.NODE_ENV === 'development';
+  const errorMessage = isDevelopment ? error.message : 'Something went wrong';
+
+  res.status(500).json({
+    success: false,
+    error: 'Internal server error',
+    message: errorMessage,
+    ...(isDevelopment && { stack: error.stack })
+  });
+};

package/src/middleware/requestLogger.test.ts

@@ -0,0 +1,81 @@
+jest.mock('../logging/logger', () => ({
+  __esModule: true,
+  default: { info: jest.fn(), error: jest.fn(), warn: jest.fn(), debug: jest.fn(), http: jest.fn() }
+}));
+
+import logger from '../logging/logger';
+import { requestLogger, requestLoggerWithMetrics, simpleRequestLogger } from './requestLogger';
+
+function mockReqRes() {
+  const req: any = {
+    method: 'GET',
+    url: '/albums/123',
+    correlationId: 'corr-1',
+    ip: '127.0.0.1',
+    get: jest.fn().mockReturnValue('test-agent')
+  };
+  const res: any = { statusCode: 200, on: jest.fn() };
+  return { req, res };
+}
+
+describe('simpleRequestLogger', () => {
+  beforeEach(() => jest.clearAllMocks());
+
+  it('logs an inbound request line with correlation id, ip, and user agent', () => {
+    const { req, res } = mockReqRes();
+    const next = jest.fn();
+
+    simpleRequestLogger(req, res, next);
+
+    expect(logger.info).toHaveBeenCalledWith('→ GET /albums/123', {
+      correlationId: 'corr-1',
+      ip: '127.0.0.1',
+      userAgent: 'test-agent'
+    });
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it('falls back to "unknown" correlation id when none was set on the request', () => {
+    const { req, res } = mockReqRes();
+    delete req.correlationId;
+    const next = jest.fn();
+
+    simpleRequestLogger(req, res, next);
+
+    expect(logger.info).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({ correlationId: 'unknown' })
+    );
+  });
+
+  it('logs the outbound response line with status and duration once the response finishes', () => {
+    const { req, res } = mockReqRes();
+    const next = jest.fn();
+
+    simpleRequestLogger(req, res, next);
+
+    expect(res.on).toHaveBeenCalledWith('finish', expect.any(Function));
+    const finishHandler = res.on.mock.calls.find((c: any[]) => c[0] === 'finish')[1];
+    res.statusCode = 200;
+    finishHandler();
+
+    expect(logger.info).toHaveBeenCalledWith(
+      expect.stringMatching(/^← GET \/albums\/123 200 \d+ms$/),
+      expect.objectContaining({ correlationId: 'corr-1', statusCode: 200 })
+    );
+  });
+});
+
+describe('requestLogger', () => {
+  it('is a Morgan middleware function', () => {
+    expect(typeof requestLogger).toBe('function');
+  });
+});
+
+describe('requestLoggerWithMetrics', () => {
+  it('bundles requestLogger and metricsMiddleware as a two-item array', () => {
+    expect(requestLoggerWithMetrics).toHaveLength(2);
+    expect(requestLoggerWithMetrics[0]).toBe(requestLogger);
+    expect(typeof requestLoggerWithMetrics[1]).toBe('function');
+  });
+});

package/src/middleware/requestLogger.ts

@@ -0,0 +1,47 @@
+import morgan from 'morgan';
+import logger from '../logging/logger';
+import { metricsMiddleware } from '../metrics';
+
+/**
+ * Morgan middleware configured to use Winston logger
+ * Logs HTTP requests in structured format
+ */
+export const requestLogger = morgan('combined', {
+  stream: {
+    write: (message: string) => {
+      logger.http(message.trim());
+    }
+  }
+});
+
+/**
+ * Combined middleware that includes both logging and metrics
+ * Use this instead of separate requestLogger and metricsMiddleware
+ */
+export const requestLoggerWithMetrics = [requestLogger, metricsMiddleware];
+
+/**
+ * Simple request logger for development
+ * Logs basic request info with correlation ID
+ */
+export const simpleRequestLogger = (req: any, res: any, next: any) => {
+  const start = Date.now();
+  const correlationId = req.correlationId || 'unknown';
+
+  logger.info(`→ ${req.method} ${req.url}`, {
+    correlationId,
+    ip: req.ip,
+    userAgent: req.get('User-Agent')
+  });
+
+  res.on('finish', () => {
+    const duration = Date.now() - start;
+    logger.info(`← ${req.method} ${req.url} ${res.statusCode} ${duration}ms`, {
+      correlationId,
+      statusCode: res.statusCode,
+      duration
+    });
+  });
+
+  next();
+};

package/src/middleware/security.test.ts

@@ -0,0 +1,45 @@
+import express from 'express';
+import request from 'supertest';
+import { securityHeaders, createRateLimiter } from './security';
+
+describe('securityHeaders', () => {
+  const app = express();
+  app.use(securityHeaders);
+  app.get('/ping', (_req, res) => res.json({ ok: true }));
+
+  it('sets standard helmet protections', async () => {
+    const res = await request(app).get('/ping');
+
+    expect(res.headers['x-content-type-options']).toBe('nosniff');
+    expect(res.headers['x-frame-options']).toBe('SAMEORIGIN');
+  });
+
+  it('relaxes cross-origin-resource-policy so other-origin frontends can read the response', async () => {
+    const res = await request(app).get('/ping');
+
+    expect(res.headers['cross-origin-resource-policy']).toBe('cross-origin');
+  });
+
+  it('does not set a Content-Security-Policy header (JSON API, not HTML)', async () => {
+    const res = await request(app).get('/ping');
+
+    expect(res.headers['content-security-policy']).toBeUndefined();
+  });
+});
+
+describe('createRateLimiter', () => {
+  it('allows requests under the limit and blocks once the limit is exceeded', async () => {
+    const app = express();
+    app.use(createRateLimiter({ windowMs: 60_000, max: 2 }));
+    app.get('/ping', (_req, res) => res.json({ ok: true }));
+
+    const first = await request(app).get('/ping');
+    const second = await request(app).get('/ping');
+    const third = await request(app).get('/ping');
+
+    expect(first.status).toBe(200);
+    expect(second.status).toBe(200);
+    expect(third.status).toBe(429);
+    expect(third.body).toEqual({ success: false, message: 'Too many requests, please try again later' });
+  });
+});

package/src/middleware/security.ts

@@ -0,0 +1,43 @@
+import helmet from 'helmet';
+import rateLimit, { Options as RateLimitOptions } from 'express-rate-limit';
+
+/**
+ * Standard security headers (helmet) for all services.
+ *
+ * - `contentSecurityPolicy` is off: these are JSON APIs, not HTML apps, and a
+ *   couple of services serve a static Swagger docs page under `/api/docs`
+ *   whose inline scripts a default CSP would break.
+ * - `crossOriginResourcePolicy` is relaxed to `cross-origin`: helmet's default
+ *   (`same-origin`) makes browsers refuse to read the response from a
+ *   different origin — which every frontend is, since each front and backend
+ *   service runs on its own port. CORS (see `createCorsMiddleware`) already
+ *   does origin enforcement; this header must not fight it.
+ */
+export const securityHeaders = helmet({
+  contentSecurityPolicy: false,
+  crossOriginResourcePolicy: { policy: 'cross-origin' },
+  crossOriginEmbedderPolicy: false
+});
+
+/**
+ * Build a rate limiter with sane JSON error output. Counts per client IP.
+ */
+export function createRateLimiter(options: Partial<RateLimitOptions> = {}) {
+  return rateLimit({
+    windowMs: 15 * 60 * 1000,
+    max: 300,
+    standardHeaders: true,
+    legacyHeaders: false,
+    message: { success: false, message: 'Too many requests, please try again later' },
+    ...options
+  });
+}
+
+/** Baseline limiter for authenticated/general routes. */
+export const standardRateLimiter = createRateLimiter();
+
+/**
+ * Tighter limiter for brute-force-prone unauthenticated routes (token
+ * issuance, public endpoints with no auth in front of them).
+ */
+export const strictRateLimiter = createRateLimiter({ max: 20 });

package/src/middleware/validate.test.ts

@@ -0,0 +1,60 @@
+import express from 'express';
+import request from 'supertest';
+import { z } from 'zod';
+import { validate } from './validate';
+import { errorHandler } from './errorHandler';
+
+function buildApp(schema: z.ZodType) {
+  const app = express();
+  app.use(express.json());
+  app.post('/things', validate(schema), (req, res) => {
+    res.json({ success: true, data: req.body });
+  });
+  app.use(errorHandler);
+  return app;
+}
+
+describe('validate', () => {
+  const schema = z.object({
+    name: z.string().min(1),
+    age: z.number().int().positive().optional()
+  });
+
+  it('calls the handler with the parsed body when validation passes', async () => {
+    const app = buildApp(schema);
+
+    const res = await request(app).post('/things').send({ name: 'Alice', age: 30 });
+
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ success: true, data: { name: 'Alice', age: 30 } });
+  });
+
+  it('responds 400 via the shared errorHandler when a required field is missing', async () => {
+    const app = buildApp(schema);
+
+    const res = await request(app).post('/things').send({});
+
+    expect(res.status).toBe(400);
+    expect(res.body.success).toBe(false);
+    expect(res.body.error).toBe('BadRequestError');
+    expect(res.body.message).toContain('name');
+  });
+
+  it('responds 400 when a field has the wrong type', async () => {
+    const app = buildApp(schema);
+
+    const res = await request(app).post('/things').send({ name: 'Bob', age: 'not-a-number' });
+
+    expect(res.status).toBe(400);
+    expect(res.body.error).toBe('BadRequestError');
+  });
+
+  it('strips unknown fields not declared in the schema (zod default behavior)', async () => {
+    const app = buildApp(schema);
+
+    const res = await request(app).post('/things').send({ name: 'Carol', extra: 'nope' });
+
+    expect(res.status).toBe(200);
+    expect(res.body.data).toEqual({ name: 'Carol' });
+  });
+});

package/src/middleware/validate.ts

@@ -0,0 +1,23 @@
+import { Request, Response, NextFunction, RequestHandler } from 'express';
+import { ZodType } from 'zod';
+import { BadRequestError } from '../errors/HttpError';
+
+/**
+ * Validates `req.body` against a zod schema before the route handler runs.
+ * On failure, throws a `BadRequestError` (caught by the shared errorHandler)
+ * instead of letting controllers hand-roll their own field checks. On
+ * success, `req.body` is replaced with the parsed result so handlers get
+ * zod's inferred, coerced types rather than raw untyped input.
+ */
+export function validate(schema: ZodType): RequestHandler {
+  return (req: Request, _res: Response, next: NextFunction): void => {
+    const result = schema.safeParse(req.body);
+    if (!result.success) {
+      const issue = result.error.issues[0];
+      const field = issue.path.length ? `${issue.path.join('.')}: ` : '';
+      throw new BadRequestError(`${field}${issue.message}`);
+    }
+    req.body = result.data;
+    next();
+  };
+}

package/src/tracing/index.test.ts

@@ -0,0 +1,250 @@
+/**
+ * The real OpenTelemetry SDK/exporter/provider are mocked out — they're
+ * network- and global-registry-heavy, and createBaseApp.test.ts already
+ * exercises the real tracingMiddleware happy path end-to-end via supertest.
+ * This file focuses on this module's own branching logic (env-var
+ * resolution, parent-span-vs-context handling, the helper wrappers), using
+ * the real (side-effect-free) @opentelemetry/api for trace/context/propagation.
+ */
+const mockSpan = () => ({
+  setAttribute: jest.fn(),
+  addEvent: jest.fn(),
+  end: jest.fn(),
+  spanContext: jest.fn(() => ({ traceId: 't', spanId: 's', traceFlags: 1 }))
+});
+
+const mockTracer = { startSpan: jest.fn(() => mockSpan()) };
+const registerMock = jest.fn();
+const getTracerMock = jest.fn(() => mockTracer);
+const providerCtorMock = jest.fn().mockImplementation((opts: unknown) => ({
+  __opts: opts,
+  register: registerMock,
+  getTracer: getTracerMock
+}));
+const exporterCtorMock = jest.fn().mockImplementation((opts: unknown) => ({ __opts: opts }));
+const spanProcessorCtorMock = jest.fn();
+const resourceFromAttributesMock = jest.fn((attrs: unknown) => attrs);
+
+jest.mock('@opentelemetry/sdk-trace-node', () => ({
+  NodeTracerProvider: providerCtorMock,
+  BatchSpanProcessor: spanProcessorCtorMock
+}));
+
+jest.mock('@opentelemetry/exporter-trace-otlp-http', () => ({
+  OTLPTraceExporter: exporterCtorMock
+}));
+
+jest.mock('@opentelemetry/resources', () => ({
+  resourceFromAttributes: resourceFromAttributesMock
+}));
+
+import { context } from '@opentelemetry/api';
+
+async function loadTracing() {
+  let tracing!: typeof import('./index');
+  await jest.isolateModulesAsync(async () => {
+    tracing = await import('./index');
+  });
+  return tracing;
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+describe('initTracer', () => {
+  const ORIGINAL_ENV = process.env;
+
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+    delete process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT;
+    delete process.env.JAEGER_ENDPOINT;
+  });
+
+  afterAll(() => {
+    process.env = ORIGINAL_ENV;
+  });
+
+  it('defaults to the in-cluster collector endpoint when no env var is set', async () => {
+    const { initTracer } = await loadTracing();
+
+    initTracer('album-service');
+
+    expect(exporterCtorMock).toHaveBeenCalledWith({ url: 'http://jaeger-collector:4318/v1/traces' });
+  });
+
+  it('prefers OTEL_EXPORTER_OTLP_TRACES_ENDPOINT over JAEGER_ENDPOINT', async () => {
+    process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT = 'http://otel-endpoint/v1/traces';
+    process.env.JAEGER_ENDPOINT = 'http://jaeger-endpoint/v1/traces';
+    const { initTracer } = await loadTracing();
+
+    initTracer('album-service');
+
+    expect(exporterCtorMock).toHaveBeenCalledWith({ url: 'http://otel-endpoint/v1/traces' });
+  });
+
+  it('falls back to JAEGER_ENDPOINT when OTEL_EXPORTER_OTLP_TRACES_ENDPOINT is unset', async () => {
+    process.env.JAEGER_ENDPOINT = 'http://jaeger-endpoint/v1/traces';
+    const { initTracer } = await loadTracing();
+
+    initTracer('album-service');
+
+    expect(exporterCtorMock).toHaveBeenCalledWith({ url: 'http://jaeger-endpoint/v1/traces' });
+  });
+
+  it('registers the provider and returns a tracer scoped to the given service name', async () => {
+    const { initTracer } = await loadTracing();
+
+    const tracer = initTracer('album-service');
+
+    expect(registerMock).toHaveBeenCalledTimes(1);
+    expect(getTracerMock).toHaveBeenCalledWith('album-service');
+    expect(tracer).toBe(mockTracer);
+  });
+});
+
+describe('getTracer', () => {
+  it('lazily initializes on first call using SERVICE_NAME (or "unknown-service")', async () => {
+    const { getTracer } = await loadTracing();
+
+    getTracer();
+
+    expect(getTracerMock).toHaveBeenCalledWith('unknown-service');
+  });
+
+  it('caches the tracer across calls instead of re-initializing', async () => {
+    const { getTracer } = await loadTracing();
+
+    getTracer();
+    getTracer();
+
+    expect(providerCtorMock).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('startSpan', () => {
+  it('starts a root span when no parent is given', async () => {
+    const { startSpan } = await loadTracing();
+
+    startSpan('op');
+
+    expect(mockTracer.startSpan).toHaveBeenCalledWith('op');
+  });
+
+  it('starts a child span from a real Span parent (has spanContext()), deriving a parent context from it', async () => {
+    const { startSpan } = await loadTracing();
+    const parentSpan = mockSpan();
+
+    startSpan('op', parentSpan);
+
+    const [name, undef, parentContext] = mockTracer.startSpan.mock.calls[0] as unknown as [string, undefined, any];
+    expect(name).toBe('op');
+    expect(undef).toBeUndefined();
+    // trace.setSpan(context.active(), parentSpan) returns a real Context, not the bare parentSpan.
+    expect(parentContext).not.toBe(parentSpan);
+    expect(typeof parentContext.getValue).toBe('function');
+  });
+
+  it('starts a span from a bare Context parent (no spanContext())', async () => {
+    const { startSpan } = await loadTracing();
+    const parentContext = context.active();
+
+    startSpan('op', parentContext);
+
+    expect(mockTracer.startSpan).toHaveBeenCalledWith('op', undefined, parentContext);
+  });
+});
+
+describe('createChildSpan', () => {
+  it('delegates to startSpan with the given parent', async () => {
+    const { createChildSpan } = await loadTracing();
+    const parentSpan = mockSpan();
+
+    createChildSpan('child-op', parentSpan);
+
+    expect(mockTracer.startSpan).toHaveBeenCalledWith('child-op', undefined, expect.anything());
+  });
+});
+
+describe('logToSpan', () => {
+  it('adds an event with data to the given span', async () => {
+    const { logToSpan } = await loadTracing();
+    const span = mockSpan();
+
+    logToSpan(span, 'cache-miss', { key: 'abc' });
+
+    expect(span.addEvent).toHaveBeenCalledWith('cache-miss', { key: 'abc' });
+  });
+});
+
+describe('setSpanTag', () => {
+  it('sets an attribute on the given span', async () => {
+    const { setSpanTag } = await loadTracing();
+    const span = mockSpan();
+
+    setSpanTag(span, 'user.id', '42');
+
+    expect(span.setAttribute).toHaveBeenCalledWith('user.id', '42');
+  });
+});
+
+describe('injectHeaders', () => {
+  it('returns a headers object without throwing', async () => {
+    const { injectHeaders } = await loadTracing();
+    const span = mockSpan();
+
+    const headers = injectHeaders(span);
+
+    expect(typeof headers).toBe('object');
+  });
+});
+
+describe('extractSpanContext', () => {
+  it('returns a Context derived from the given headers', async () => {
+    const { extractSpanContext } = await loadTracing();
+
+    const extracted = extractSpanContext({ traceparent: '00-abc-def-01' });
+
+    expect(typeof (extracted as any).getValue).toBe('function');
+  });
+});
+
+describe('tracingMiddleware', () => {
+  function mockReqRes() {
+    const req: any = { method: 'GET', path: '/albums', url: '/albums?x=1', headers: {} };
+    const handlers: Record<string, () => void> = {};
+    const res: any = {
+      statusCode: 200,
+      on: jest.fn((event: string, handler: () => void) => {
+        handlers[event] = handler;
+      })
+    };
+    return { req, res, handlers };
+  }
+
+  it('starts a server span, attaches it to the request, and calls next', async () => {
+    const { tracingMiddleware } = await loadTracing();
+    const { req, res } = mockReqRes();
+    const next = jest.fn();
+
+    tracingMiddleware(req, res, next);
+
+    expect(req.span).toBeDefined();
+    expect(req.span.setAttribute).toHaveBeenCalledWith('http.method', 'GET');
+    expect(req.span.setAttribute).toHaveBeenCalledWith('http.url', '/albums?x=1');
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it('records the response status code and ends the span on finish', async () => {
+    const { tracingMiddleware } = await loadTracing();
+    const { req, res, handlers } = mockReqRes();
+    const next = jest.fn();
+
+    tracingMiddleware(req, res, next);
+    res.statusCode = 404;
+    handlers.finish();
+
+    expect(req.span.setAttribute).toHaveBeenCalledWith('http.status_code', 404);
+    expect(req.span.end).toHaveBeenCalledTimes(1);
+  });
+});