@tumbaland/backend-core 1.16.0

package/src/tracing/index.ts

@@ -0,0 +1,97 @@
+import { context, propagation, trace, SpanKind, Tracer } from '@opentelemetry/api';
+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, parentSpan?: any) => {
+  if (!parentSpan) {
+    return getTracer().startSpan(operationName);
+  }
+  const parentContext =
+    typeof parentSpan.spanContext === 'function'
+      ? trace.setSpan(context.active(), parentSpan)
+      : parentSpan;
+  return getTracer().startSpan(operationName, undefined, parentContext);
+};
+
+// Middleware for Express to create spans for requests
+export const tracingMiddleware = (req: any, res: any, next: any) => {
+  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, parentSpan: any) => {
+  return startSpan(operationName, parentSpan);
+};
+
+// Helper to log events to spans
+export const logToSpan = (span: any, event: string, data?: any) => {
+  span.addEvent(event, data);
+};
+
+// Helper to set tags on spans
+export const setSpanTag = (span: any, key: string, value: any) => {
+  span.setAttribute(key, value);
+};
+
+// Helper to inject tracing headers (W3C traceparent) for downstream calls
+export const injectHeaders = (span: any) => {
+  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: any) => {
+  return propagation.extract(context.active(), headers);
+};

package/src/types/auth.ts

@@ -0,0 +1,33 @@
+export interface UserPayload {
+  id: string;
+  email: string;
+  name: string;
+  picture?: string;
+  groups?: 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.
+ */
+declare global {
+  namespace Express {
+    interface Request {
+      user?: UserPayload;
+      userGroups?: string[];
+    }
+  }
+}
+
+export interface ServiceHealth {
+  status: 'ok' | 'error';
+  service: string;
+  type: 'backend' | 'frontend';
+  timestamp: string;
+  version: string;
+  description: string;
+  dependencies?: Record<string, any>;
+}

package/src/utils/correlation.test.ts

@@ -0,0 +1,47 @@
+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

@@ -0,0 +1,22 @@
+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 as any).correlationId = correlationId;
+  res.setHeader('x-correlation-id', correlationId);
+
+  next();
+};

package/src/utils/response.test.ts

@@ -0,0 +1,64 @@
+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' });
+  });
+});

package/src/utils/response.ts

@@ -0,0 +1,60 @@
+import { Response } from 'express';
+
+/**
+ * Standard API response format
+ */
+export interface ApiResponse<T = any> {
+  success: boolean;
+  data?: T;
+  message?: string;
+  error?: string;
+  correlationId?: string;
+}
+
+/**
+ * Create a standardized API response
+ */
+export function createApiResponse<T = any>(
+  success: boolean,
+  data?: T,
+  message?: string,
+  error?: string,
+  correlationId?: string
+): ApiResponse<T> {
+  const response: ApiResponse<T> = { success };
+
+  if (data !== undefined) response.data = data;
+  if (message) response.message = message;
+  if (error) response.error = error;
+  if (correlationId) response.correlationId = correlationId;
+
+  return response;
+}
+
+/**
+ * Send a success response
+ */
+export function sendSuccess<T = any>(
+  res: Response,
+  data?: T,
+  message?: string,
+  statusCode: number = 200,
+  correlationId?: string
+) {
+  const response = createApiResponse(true, data, message, undefined, correlationId);
+  res.status(statusCode).json(response);
+}
+
+/**
+ * Send an error response
+ */
+export function sendError(
+  res: Response,
+  message: string,
+  statusCode: number = 500,
+  error?: string,
+  correlationId?: string
+) {
+  const response = createApiResponse(false, undefined, message, error, correlationId);
+  res.status(statusCode).json(response);
+}

package/tsconfig.build.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "es2023",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "types": ["jest", "node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}