kotadb 2.0.0

package/src/instrument.ts

@@ -0,0 +1,88 @@
+/**
+ * Sentry SDK Instrumentation
+ * IMPORTANT: This file must be imported first in index.ts before all other imports
+ * to ensure proper tracing and error capture.
+ */
+
+import * as Sentry from "@sentry/node";
+import { expressErrorHandler } from "@sentry/node";
+
+// Test environment guard: disable Sentry in tests to prevent test errors from polluting dashboard
+if (process.env.NODE_ENV !== "test") {
+	// Determine environment from Vercel or Node environment
+	const environment = process.env.VERCEL_ENV || process.env.NODE_ENV || "development";
+
+	// Environment-specific sampling rates
+	const isDevelopment = environment === "development";
+	const tracesSampleRate = isDevelopment ? 1.0 : 0.1;
+
+	// Initialize Sentry SDK
+	try {
+		Sentry.init({
+			dsn: process.env.SENTRY_DSN,
+			environment,
+			tracesSampleRate,
+
+			// Privacy compliance: don't send IP addresses or user agents automatically
+			sendDefaultPii: false,
+
+			// Enable debug mode in development
+			debug: isDevelopment,
+
+			// Scrub sensitive headers before sending to Sentry
+			beforeSend(event, hint) {
+				// Remove sensitive headers
+				if (event.request?.headers) {
+					const headers = event.request.headers;
+					if (headers.authorization) headers.authorization = "[REDACTED]";
+					if (headers["x-api-key"]) headers["x-api-key"] = "[REDACTED]";
+				}
+
+				// Add request_id from Express request for correlation with structured logs
+				const originalException = hint.originalException as Error & { req?: { requestId?: string } };
+				if (originalException?.req?.requestId) {
+					event.tags = {
+						...event.tags,
+						request_id: originalException.req.requestId,
+					};
+				}
+
+				return event;
+			},
+
+			// Filter out health check endpoints from transaction tracking
+			beforeSendTransaction(event) {
+				// Exclude /health endpoint from performance tracking
+				if (event.transaction === "GET /health") {
+					return null;
+				}
+				return event;
+			},
+		});
+
+		if (isDevelopment && process.env.SENTRY_DSN) {
+			process.stdout.write(
+				JSON.stringify({
+					timestamp: new Date().toISOString(),
+					level: "info",
+					message: "Sentry SDK initialized",
+					environment,
+					tracesSampleRate,
+				}) + "\n",
+			);
+		}
+	} catch (error) {
+		// Log warning but don't crash - observability failures should not cause outages
+		process.stderr.write(
+			JSON.stringify({
+				timestamp: new Date().toISOString(),
+				level: "warn",
+				message: "Failed to initialize Sentry SDK",
+				error: error instanceof Error ? error.message : String(error),
+			}) + "\n",
+		);
+	}
+}
+
+// Export Sentry instance and Express error handler for use in other modules
+export { Sentry, expressErrorHandler };

package/src/logging/context.ts

@@ -0,0 +1,46 @@
+/**
+ * Correlation context utilities for tracking requests across async boundaries
+ */
+
+import { randomUUID } from "node:crypto";
+import type { LogContext } from "./logger";
+
+/**
+ * Generate a unique request ID for correlation
+ */
+export function generateRequestId(): string {
+	return randomUUID();
+}
+
+/**
+ * Generate a unique job ID for queue job correlation
+ */
+export function generateJobId(): string {
+	return randomUUID();
+}
+
+/**
+ * Create a correlation context from request metadata
+ */
+export function createRequestContext(requestId: string, userId?: string, keyId?: string): LogContext {
+	const context: LogContext = { request_id: requestId };
+	if (userId) context.user_id = userId;
+	if (keyId) context.key_id = keyId;
+	return context;
+}
+
+/**
+ * Create a correlation context for queue jobs
+ */
+export function createJobContext(jobId: string, userId?: string): LogContext {
+	const context: LogContext = { job_id: jobId };
+	if (userId) context.user_id = userId;
+	return context;
+}
+
+/**
+ * Extend existing context with additional fields
+ */
+export function extendContext(base: LogContext, additional: LogContext): LogContext {
+	return { ...base, ...additional };
+}

package/src/logging/logger.ts

@@ -0,0 +1,193 @@
+/**
+ * Structured logging with JSON format, correlation IDs, and sensitive data masking
+ */
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export interface LogContext {
+	request_id?: string;
+	user_id?: string;
+	key_id?: string;
+	job_id?: string;
+	[key: string]: unknown;
+}
+
+export interface LogEntry {
+	timestamp: string;
+	level: LogLevel;
+	message: string;
+	context?: LogContext;
+	error?: {
+		message: string;
+		stack?: string;
+		code?: string;
+	};
+}
+
+export interface Logger {
+	debug(message: string, context?: LogContext): void;
+	info(message: string, context?: LogContext): void;
+	warn(message: string, context?: LogContext): void;
+	error(message: string, errorOrContext?: Error | LogContext, context?: LogContext): void;
+	child(childContext: LogContext): Logger;
+}
+
+// Sensitive keys that should be masked in logs
+const SENSITIVE_KEYS = [
+	"apiKey",
+	"api_key",
+	"apikey",
+	"token",
+	"password",
+	"secret",
+	"authorization",
+	"bearer",
+	"key",
+	"private_key",
+	"privateKey",
+	"client_secret",
+	"clientSecret",
+	"access_token",
+	"accessToken",
+	"refresh_token",
+	"refreshToken",
+	"session",
+	"cookie",
+];
+
+const LOG_LEVELS: Record<LogLevel, number> = {
+	debug: 0,
+	info: 1,
+	warn: 2,
+	error: 3,
+};
+
+/**
+ * Get configured log level from environment (default: info)
+ */
+function getLogLevel(): LogLevel {
+	const level = process.env.LOG_LEVEL?.toLowerCase();
+	if (level === "debug" || level === "info" || level === "warn" || level === "error") {
+		return level;
+	}
+	return "info";
+}
+
+/**
+ * Check if a log level should be output based on configured level
+ */
+function shouldLog(level: LogLevel): boolean {
+	const configuredLevel = getLogLevel();
+	return LOG_LEVELS[level] >= LOG_LEVELS[configuredLevel];
+}
+
+/**
+ * Mask sensitive data in context objects
+ */
+function maskSensitiveData(context: LogContext): LogContext {
+	const masked: LogContext = {};
+	for (const [key, value] of Object.entries(context)) {
+		if (SENSITIVE_KEYS.some((sensitiveKey) => key.toLowerCase().includes(sensitiveKey))) {
+			masked[key] = "[REDACTED]";
+		} else if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+			masked[key] = maskSensitiveData(value as LogContext);
+		} else {
+			masked[key] = value;
+		}
+	}
+	return masked;
+}
+
+/**
+ * Format and write log entry to stdout (info/debug/warn) or stderr (error)
+ */
+function writeLog(entry: LogEntry): void {
+	const json = JSON.stringify(entry);
+	const output = `${json}\n`;
+
+	if (entry.level === "error") {
+		process.stderr.write(output);
+	} else {
+		process.stdout.write(output);
+	}
+}
+
+/**
+ * Create a logger instance with optional correlation context
+ */
+export function createLogger(baseContext?: LogContext): Logger {
+	const context = baseContext ? maskSensitiveData(baseContext) : {};
+
+	return {
+		debug(message: string, additionalContext?: LogContext): void {
+			if (!shouldLog("debug")) return;
+
+			const entry: LogEntry = {
+				timestamp: new Date().toISOString(),
+				level: "debug",
+				message,
+				context: additionalContext ? { ...context, ...maskSensitiveData(additionalContext) } : Object.keys(context).length > 0 ? context : undefined,
+			};
+			writeLog(entry);
+		},
+
+		info(message: string, additionalContext?: LogContext): void {
+			if (!shouldLog("info")) return;
+
+			const entry: LogEntry = {
+				timestamp: new Date().toISOString(),
+				level: "info",
+				message,
+				context: additionalContext ? { ...context, ...maskSensitiveData(additionalContext) } : Object.keys(context).length > 0 ? context : undefined,
+			};
+			writeLog(entry);
+		},
+
+		warn(message: string, additionalContext?: LogContext): void {
+			if (!shouldLog("warn")) return;
+
+			const entry: LogEntry = {
+				timestamp: new Date().toISOString(),
+				level: "warn",
+				message,
+				context: additionalContext ? { ...context, ...maskSensitiveData(additionalContext) } : Object.keys(context).length > 0 ? context : undefined,
+			};
+			writeLog(entry);
+		},
+
+		error(message: string, errorOrContext?: Error | LogContext, additionalContext?: LogContext): void {
+			if (!shouldLog("error")) return;
+
+			const entry: LogEntry = {
+				timestamp: new Date().toISOString(),
+				level: "error",
+				message,
+			};
+
+			// Handle error as second parameter
+			if (errorOrContext instanceof Error) {
+				entry.error = {
+					message: errorOrContext.message,
+					stack: errorOrContext.stack,
+					code: (errorOrContext as Error & { code?: string }).code,
+				};
+				if (additionalContext) {
+					entry.context = { ...context, ...maskSensitiveData(additionalContext) };
+				} else if (Object.keys(context).length > 0) {
+					entry.context = context;
+				}
+			} else if (errorOrContext) {
+				// Handle context as second parameter
+				entry.context = { ...context, ...maskSensitiveData(errorOrContext) };
+			} else if (Object.keys(context).length > 0) {
+				entry.context = context;
+			}
+
+			writeLog(entry);
+		},
+
+		child(childContext: LogContext): Logger {
+			return createLogger({ ...context, ...childContext });
+		},
+	};
+}

package/src/logging/middleware.ts

@@ -0,0 +1,107 @@
+/**
+ * Express middleware for request/response logging with correlation IDs
+ */
+
+import type { Request, Response, NextFunction } from "express";
+import { createLogger } from "./logger";
+import { generateRequestId, createRequestContext } from "./context";
+import type { Logger } from "./logger";
+
+// Extend Express Request to include logger
+declare global {
+	namespace Express {
+		interface Request {
+			logger: Logger;
+			requestId: string;
+		}
+	}
+}
+
+/**
+ * Express middleware that:
+ * - Generates unique request_id for each request
+ * - Attaches logger instance to req.logger with correlation context
+ * - Logs incoming requests and outgoing responses
+ * - Captures errors with stack traces
+ */
+export function requestLoggingMiddleware(req: Request, res: Response, next: NextFunction): void {
+	const startTime = Date.now();
+	const requestId = generateRequestId();
+
+	// Attach request ID to request object
+	req.requestId = requestId;
+
+	// Create base logger with request_id
+	const baseContext = createRequestContext(requestId);
+	req.logger = createLogger(baseContext);
+
+	// Log incoming request
+	req.logger.info("Incoming request", {
+		method: req.method,
+		url: req.url,
+		path: req.path,
+		ip: req.ip,
+		userAgent: req.get("user-agent"),
+	});
+
+	// Capture response finish event for logging
+	const originalSend = res.send;
+	res.send = function (body) {
+		// Log response
+		const duration = Date.now() - startTime;
+		const level = res.statusCode >= 400 ? "warn" : "info";
+
+		if (level === "warn") {
+			req.logger.warn("Request completed with error", {
+				method: req.method,
+				url: req.url,
+				status: res.statusCode,
+				duration_ms: duration,
+			});
+		} else {
+			req.logger.info("Request completed", {
+				method: req.method,
+				url: req.url,
+				status: res.statusCode,
+				duration_ms: duration,
+			});
+		}
+
+		return originalSend.call(this, body);
+	};
+
+	// Capture errors
+	const originalNext = next;
+	next = function (error?: unknown) {
+		if (error instanceof Error) {
+			req.logger.error("Request error", error);
+		}
+		return originalNext(error);
+	};
+
+	next();
+}
+
+/**
+ * Error handling middleware to log unhandled errors
+ */
+export function errorLoggingMiddleware(error: Error, req: Request, res: Response, next: NextFunction): void {
+	// Log error with full stack trace
+	if (req.logger) {
+		req.logger.error("Unhandled error", error, {
+			method: req.method,
+			url: req.url,
+			path: req.path,
+		});
+	} else {
+		// Fallback if logger not attached
+		const logger = createLogger({ request_id: req.requestId || "unknown" });
+		logger.error("Unhandled error (no logger attached)", error, {
+			method: req.method,
+			url: req.url,
+			path: req.path,
+		});
+	}
+
+	next(error);
+}