@tumbaland/backend-core 1.44.0 → 1.45.0

package/src/tracing/index.test.ts

@@ -1,272 +0,0 @@
-/**
- * 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.
- */
-// A partial span: only the members these tests exercise are stubbed, cast to
-// the full Span type so it satisfies the now-typed tracing helpers. The jest
-// mocks remain reachable at runtime for the assertions below.
-const mockSpan = () =>
-  ({
-    setAttribute: jest.fn(),
-    addEvent: jest.fn(),
-    end: jest.fn(),
-    spanContext: jest.fn(() => ({ traceId: 't', spanId: 's', traceFlags: 1 }))
-  }) as unknown as Span;
-
-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, Span } from '@opentelemetry/api';
-import { ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
-
-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('falls back to version 1.0.0 and environment "development" when their env vars are unset', async () => {
-    const merged: Record<string, string | undefined> = { ...process.env };
-    delete merged.npm_package_version;
-    delete merged.NODE_ENV;
-    process.env = merged as NodeJS.ProcessEnv;
-
-    const { initTracer } = await loadTracing();
-    initTracer('album-service');
-
-    expect(resourceFromAttributesMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        [ATTR_SERVICE_VERSION]: '1.0.0',
-        'deployment.environment': 'development'
-      })
-    );
-  });
-
-  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);
-  });
-});

package/src/tracing/index.ts

@@ -1,110 +0,0 @@
-import {
-  context,
-  propagation,
-  trace,
-  SpanKind,
-  Tracer,
-  Span,
-  Context,
-  Attributes,
-  AttributeValue,
-} from '@opentelemetry/api';
-import { Request, Response, NextFunction } from 'express';
-import { NodeTracerProvider, BatchSpanProcessor } from '@opentelemetry/sdk-trace-node';
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
-import { resourceFromAttributes } from '@opentelemetry/resources';
-import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
-
-// Initialize OpenTelemetry tracer provider, exporting via OTLP/HTTP.
-// Endpoint resolution: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT > JAEGER_ENDPOINT > in-cluster collector default.
-export const initTracer = (serviceName: string): Tracer => {
-  const url =
-    process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ||
-    process.env.JAEGER_ENDPOINT ||
-    'http://jaeger-collector:4318/v1/traces';
-
-  const provider = new NodeTracerProvider({
-    resource: resourceFromAttributes({
-      [ATTR_SERVICE_NAME]: serviceName,
-      [ATTR_SERVICE_VERSION]: process.env.npm_package_version || '1.0.0',
-      'deployment.environment': process.env.NODE_ENV || 'development',
-    }),
-    spanProcessors: [new BatchSpanProcessor(new OTLPTraceExporter({ url }))],
-  });
-  provider.register();
-
-  return provider.getTracer(serviceName);
-};
-
-// Global tracer instance
-let tracer: Tracer | null = null;
-
-export const getTracer = (): Tracer => {
-  if (!tracer) {
-    tracer = initTracer(process.env.SERVICE_NAME || 'unknown-service');
-  }
-  return tracer;
-};
-
-// Start a new span. `parent` may be a Span or a Context (e.g. from extractSpanContext).
-export const startSpan = (operationName: string, parent?: Span | Context) => {
-  if (!parent) {
-    return getTracer().startSpan(operationName);
-  }
-  // A Span exposes `spanContext()`; a Context does not — use that to decide
-  // whether we need to wrap the parent span into an active context first.
-  const parentContext =
-    'spanContext' in parent ? trace.setSpan(context.active(), parent) : parent;
-  return getTracer().startSpan(operationName, undefined, parentContext);
-};
-
-// Middleware for Express to create spans for requests
-export const tracingMiddleware = (req: Request, res: Response, next: NextFunction) => {
-  const parentContext = propagation.extract(context.active(), req.headers);
-  const span = getTracer().startSpan(
-    `${req.method} ${req.path}`,
-    { kind: SpanKind.SERVER },
-    parentContext
-  );
-  span.setAttribute('http.method', req.method);
-  span.setAttribute('http.url', req.url);
-
-  // Add span to request for use in handlers
-  req.span = span;
-
-  res.on('finish', () => {
-    span.setAttribute('http.status_code', res.statusCode);
-    span.end();
-  });
-
-  next();
-};
-
-// Helper to create child spans
-export const createChildSpan = (operationName: string, parent: Span | Context) => {
-  return startSpan(operationName, parent);
-};
-
-// Helper to log events to spans
-export const logToSpan = (span: Span, event: string, data?: Attributes) => {
-  span.addEvent(event, data);
-};
-
-// Helper to set tags on spans
-export const setSpanTag = (span: Span, key: string, value: AttributeValue) => {
-  span.setAttribute(key, value);
-};
-
-// Helper to inject tracing headers (W3C traceparent) for downstream calls
-export const injectHeaders = (span: Span) => {
-  const headers: { [key: string]: string } = {};
-  propagation.inject(trace.setSpan(context.active(), span), headers);
-  return headers;
-};
-
-// Helper to extract span context from incoming headers; pass the result to startSpan as parent
-export const extractSpanContext = (
-  headers: Record<string, string | string[] | undefined>
-): Context => {
-  return propagation.extract(context.active(), headers);
-};

package/src/types/auth.ts

@@ -1,45 +0,0 @@
-import type { Span } from '@opentelemetry/api';
-
-export interface UserPayload {
-  id: string;
-  email: string;
-  name: string;
-  picture?: string;
-  groups?: string[];
-  roles?: string[];
-  tokenVersion?: number;
-  /** The auth-service session (user_sessions) this token belongs to; absent on pre-sessions tokens. */
-  sid?: string;
-}
-
-/**
- * Attaches `user`/`userGroups` to every Express `Request` across all
- * services, replacing the ad-hoc `(req as any).user` casts and each
- * service's own divergent local augmentation. Individual services may still
- * carry additional request-scoped fields (e.g. auth-service's `dbUser`) —
- * those stay local since they aren't meaningful outside that service.
- *
- * `correlationId` is set by `correlationMiddleware`, `span` by
- * `tracingMiddleware`; both are declared here so the observability middleware
- * and downstream handlers can read them without a `(req as any)` cast.
- */
-declare global {
-  namespace Express {
-    interface Request {
-      user?: UserPayload;
-      userGroups?: string[];
-      correlationId?: string;
-      span?: Span;
-    }
-  }
-}
-
-export interface ServiceHealth {
-  status: 'ok' | 'error';
-  service: string;
-  type: 'backend' | 'frontend';
-  timestamp: string;
-  version: string;
-  description: string;
-  dependencies?: Record<string, unknown>;
-}

package/src/utils/correlation.test.ts

@@ -1,47 +0,0 @@
-import { Request, Response } from 'express';
-import { generateCorrelationId, correlationMiddleware } from './correlation';
-
-function mockReq(headers: Record<string, string> = {}): Request {
-  return { headers } as unknown as Request;
-}
-
-function mockRes(): Response {
-  const res: Partial<Response> = {};
-  res.setHeader = jest.fn().mockReturnValue(res);
-  return res as Response;
-}
-
-describe('generateCorrelationId', () => {
-  it('returns a unique UUID each call', () => {
-    const a = generateCorrelationId();
-    const b = generateCorrelationId();
-    expect(a).not.toBe(b);
-    expect(a).toMatch(/^[0-9a-f-]{36}$/i);
-  });
-});
-
-describe('correlationMiddleware', () => {
-  it('generates a new correlation id when none is provided', () => {
-    const req = mockReq();
-    const res = mockRes();
-    const next = jest.fn();
-
-    correlationMiddleware(req, res, next);
-
-    expect((req as any).correlationId).toMatch(/^[0-9a-f-]{36}$/i);
-    expect(res.setHeader).toHaveBeenCalledWith('x-correlation-id', (req as any).correlationId);
-    expect(next).toHaveBeenCalledTimes(1);
-  });
-
-  it('reuses an incoming x-correlation-id header', () => {
-    const req = mockReq({ 'x-correlation-id': 'existing-id' });
-    const res = mockRes();
-    const next = jest.fn();
-
-    correlationMiddleware(req, res, next);
-
-    expect((req as any).correlationId).toBe('existing-id');
-    expect(res.setHeader).toHaveBeenCalledWith('x-correlation-id', 'existing-id');
-    expect(next).toHaveBeenCalledTimes(1);
-  });
-});

package/src/utils/correlation.ts

@@ -1,22 +0,0 @@
-import { Request, Response, NextFunction, RequestHandler } from 'express';
-import { v4 as uuidv4 } from 'uuid';
-
-/**
- * Generate a unique correlation ID for request tracing
- */
-export function generateCorrelationId(): string {
-  return uuidv4();
-}
-
-/**
- * Middleware to add correlation ID to requests
- * Adds correlation ID to request object and response headers
- */
-export const correlationMiddleware: RequestHandler = (req: Request, res: Response, next: NextFunction) => {
-  const correlationId = req.headers['x-correlation-id'] as string || generateCorrelationId();
-
-  req.correlationId = correlationId;
-  res.setHeader('x-correlation-id', correlationId);
-
-  next();
-};

package/src/utils/permissionUtils.test.ts

@@ -1,47 +0,0 @@
-import { buildAccessQuery, canAccessResource } from './permissionUtils';
-
-describe('buildAccessQuery', () => {
-  it('always includes the user\'s own resources', () => {
-    expect(buildAccessQuery('user-1')).toEqual({ $or: [{ userId: 'user-1' }] });
-  });
-
-  it('adds a group-membership condition when groupIds are provided', () => {
-    expect(buildAccessQuery('user-1', ['g1', 'g2'])).toEqual({
-      $or: [{ userId: 'user-1' }, { groupId: { $in: ['g1', 'g2'] } }]
-    });
-  });
-
-  it('adds a public-resource condition when includePublic is true', () => {
-    expect(buildAccessQuery('user-1', [], true)).toEqual({
-      $or: [{ userId: 'user-1' }, { isPublic: true }]
-    });
-  });
-
-  it('combines group and public conditions', () => {
-    expect(buildAccessQuery('user-1', ['g1'], true)).toEqual({
-      $or: [{ userId: 'user-1' }, { groupId: { $in: ['g1'] } }, { isPublic: true }]
-    });
-  });
-});
-
-describe('canAccessResource', () => {
-  it('allows the owner', () => {
-    expect(canAccessResource('user-1', 'user-1')).toBe(true);
-  });
-
-  it('allows anyone when the resource is public', () => {
-    expect(canAccessResource('user-1', 'user-2', undefined, [], true)).toBe(true);
-  });
-
-  it('allows a member of the resource\'s group', () => {
-    expect(canAccessResource('user-1', 'user-2', 'g1', ['g1'])).toBe(true);
-  });
-
-  it('denies a non-member with no public flag', () => {
-    expect(canAccessResource('user-1', 'user-2', 'g1', ['g2'])).toBe(false);
-  });
-
-  it('denies when the resource has no group and belongs to someone else', () => {
-    expect(canAccessResource('user-1', 'user-2')).toBe(false);
-  });
-});

package/src/utils/permissionUtils.ts

@@ -1,68 +0,0 @@
-/**
- * Simple permission helper that builds query filters for group-based access
- * This avoids external API calls and can be used in database queries directly
- */
-
-/**
- * Build a MongoDB query for resources accessible by a user
- * @param userId - The user's ID
- * @param groupIds - Array of group IDs the user belongs to (optional)
- * @param includePublic - Whether to include public resources
- */
-export function buildAccessQuery(
-  userId: string,
-  groupIds: string[] = [],
-  includePublic: boolean = false
-) {
-  const conditions: Array<
-    { userId: string } | { groupId: { $in: string[] } } | { isPublic: boolean }
-  > = [
-    { userId } // User's own resources
-  ];
-
-  // Add group-based access
-  if (groupIds.length > 0) {
-    conditions.push({ groupId: { $in: groupIds } });
-  }
-
-  // Add public resources if requested
-  if (includePublic) {
-    conditions.push({ isPublic: true });
-  }
-
-  return { $or: conditions };
-}
-
-/**
- * Check if a user can access a specific resource
- * @param userId - The requesting user's ID
- * @param resourceUserId - The resource owner's ID
- * @param resourceGroupId - The resource's group ID (if any)
- * @param userGroupIds - Array of group IDs the user belongs to
- * @param isResourcePublic - Whether the resource is public
- */
-export function canAccessResource(
-  userId: string,
-  resourceUserId: string,
-  resourceGroupId?: string,
-  userGroupIds: string[] = [],
-  isResourcePublic: boolean = false
-): boolean {
-  // Owner can always access their own resources
-  if (userId === resourceUserId) {
-    return true;
-  }
-
-  // Public resources are accessible to anyone
-  if (isResourcePublic) {
-    return true;
-  }
-
-  // If resource is associated with a group, check if user is in that group
-  if (resourceGroupId && userGroupIds.includes(resourceGroupId)) {
-    return true;
-  }
-
-  // No access
-  return false;
-}

package/src/utils/response.test.ts

@@ -1,64 +0,0 @@
-import { Response } from 'express';
-import { createApiResponse, sendSuccess, sendError } from './response';
-
-function mockRes(): Response {
-  const res: Partial<Response> = {};
-  res.status = jest.fn().mockReturnValue(res);
-  res.json = jest.fn().mockReturnValue(res);
-  return res as Response;
-}
-
-describe('createApiResponse', () => {
-  it('omits undefined optional fields', () => {
-    expect(createApiResponse(true)).toEqual({ success: true });
-  });
-
-  it('includes provided fields', () => {
-    expect(createApiResponse(true, { id: 1 }, 'ok', undefined, 'corr-1')).toEqual({
-      success: true,
-      data: { id: 1 },
-      message: 'ok',
-      correlationId: 'corr-1'
-    });
-  });
-
-  it('keeps data even when falsy but defined (e.g. 0 or empty array)', () => {
-    expect(createApiResponse(true, 0)).toEqual({ success: true, data: 0 });
-    expect(createApiResponse(true, [])).toEqual({ success: true, data: [] });
-  });
-});
-
-describe('sendSuccess', () => {
-  it('defaults to status 200 with a success envelope', () => {
-    const res = mockRes();
-    sendSuccess(res, { id: 1 }, 'created');
-
-    expect(res.status).toHaveBeenCalledWith(200);
-    expect(res.json).toHaveBeenCalledWith({ success: true, data: { id: 1 }, message: 'created' });
-  });
-
-  it('honors a custom status code', () => {
-    const res = mockRes();
-    sendSuccess(res, { id: 1 }, 'created', 201);
-
-    expect(res.status).toHaveBeenCalledWith(201);
-  });
-});
-
-describe('sendError', () => {
-  it('defaults to status 500 with an error envelope', () => {
-    const res = mockRes();
-    sendError(res, 'Something broke');
-
-    expect(res.status).toHaveBeenCalledWith(500);
-    expect(res.json).toHaveBeenCalledWith({ success: false, message: 'Something broke' });
-  });
-
-  it('honors a custom status code and error code', () => {
-    const res = mockRes();
-    sendError(res, 'Not found', 404, 'NOT_FOUND');
-
-    expect(res.status).toHaveBeenCalledWith(404);
-    expect(res.json).toHaveBeenCalledWith({ success: false, message: 'Not found', error: 'NOT_FOUND' });
-  });
-});