@sylphx/lens-server 2.3.2 → 2.4.1

package/src/logging/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @sylphx/lens-server - Logging Module
+ */
+
+export {
+	createStructuredLogger,
+	type ErrorContext,
+	jsonOutput,
+	type LogContext,
+	type LogEntry,
+	type LogLevel,
+	type LogOutput,
+	type PerformanceContext,
+	prettyOutput,
+	type RequestContext,
+	type StructuredLogger,
+	type StructuredLoggerOptions,
+	toBasicLogger,
+	type WebSocketContext,
+} from "./structured-logger.js";

package/src/logging/structured-logger.test.ts

@@ -0,0 +1,367 @@
+/**
+ * @sylphx/lens-server - Structured Logger Tests
+ */
+
+import { describe, expect, it, spyOn } from "bun:test";
+import {
+	createStructuredLogger,
+	jsonOutput,
+	type LogEntry,
+	type LogOutput,
+	prettyOutput,
+	toBasicLogger,
+} from "./structured-logger.js";
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe("createStructuredLogger", () => {
+	describe("basic logging", () => {
+		it("creates a logger with all log methods", () => {
+			const logger = createStructuredLogger();
+
+			expect(typeof logger.debug).toBe("function");
+			expect(typeof logger.info).toBe("function");
+			expect(typeof logger.warn).toBe("function");
+			expect(typeof logger.error).toBe("function");
+			expect(typeof logger.fatal).toBe("function");
+		});
+
+		it("logs messages with correct structure", () => {
+			const entries: LogEntry[] = [];
+			const testOutput: LogOutput = {
+				write(entry) {
+					entries.push(entry);
+				},
+			};
+
+			const logger = createStructuredLogger({
+				output: testOutput,
+				service: "test-service",
+			});
+
+			logger.info("Test message");
+
+			expect(entries.length).toBe(1);
+			expect(entries[0].level).toBe("info");
+			expect(entries[0].message).toBe("Test message");
+			expect(entries[0].service).toBe("test-service");
+			expect(entries[0].timestamp).toBeDefined();
+		});
+
+		it("includes context in log entries", () => {
+			const entries: LogEntry[] = [];
+			const testOutput: LogOutput = {
+				write(entry) {
+					entries.push(entry);
+				},
+			};
+
+			const logger = createStructuredLogger({ output: testOutput });
+
+			logger.info("User action", { userId: "123", action: "login" });
+
+			expect(entries[0].userId).toBe("123");
+			expect(entries[0].action).toBe("login");
+		});
+	});
+
+	describe("log levels", () => {
+		it("respects minimum log level", () => {
+			const entries: LogEntry[] = [];
+			const testOutput: LogOutput = {
+				write(entry) {
+					entries.push(entry);
+				},
+			};
+
+			const logger = createStructuredLogger({
+				output: testOutput,
+				level: "warn",
+			});
+
+			logger.debug("Debug message");
+			logger.info("Info message");
+			logger.warn("Warn message");
+			logger.error("Error message");
+
+			expect(entries.length).toBe(2);
+			expect(entries[0].level).toBe("warn");
+			expect(entries[1].level).toBe("error");
+		});
+
+		it("logs all levels when set to debug", () => {
+			const entries: LogEntry[] = [];
+			const testOutput: LogOutput = {
+				write(entry) {
+					entries.push(entry);
+				},
+			};
+
+			const logger = createStructuredLogger({
+				output: testOutput,
+				level: "debug",
+			});
+
+			logger.debug("Debug");
+			logger.info("Info");
+			logger.warn("Warn");
+			logger.error("Error");
+			logger.fatal("Fatal");
+
+			expect(entries.length).toBe(5);
+		});
+	});
+
+	describe("error handling", () => {
+		it("extracts error properties from Error objects", () => {
+			const entries: LogEntry[] = [];
+			const testOutput: LogOutput = {
+				write(entry) {
+					entries.push(entry);
+				},
+			};
+
+			const logger = createStructuredLogger({ output: testOutput });
+			const error = new Error("Something went wrong");
+			error.name = "ValidationError";
+
+			logger.error("Operation failed", { error });
+
+			expect(entries[0].errorType).toBe("ValidationError");
+			expect(entries[0].errorMessage).toBe("Something went wrong");
+			expect(entries[0].error).toBeUndefined(); // Original error object removed
+		});
+
+		it("includes stack trace when configured", () => {
+			const entries: LogEntry[] = [];
+			const testOutput: LogOutput = {
+				write(entry) {
+					entries.push(entry);
+				},
+			};
+
+			const logger = createStructuredLogger({
+				output: testOutput,
+				includeStackTrace: true,
+			});
+
+			const error = new Error("With stack");
+			logger.error("Error with stack", { error });
+
+			expect(entries[0].stack).toBeDefined();
+			expect(entries[0].stack).toContain("Error: With stack");
+		});
+
+		it("excludes stack trace by default", () => {
+			const entries: LogEntry[] = [];
+			const testOutput: LogOutput = {
+				write(entry) {
+					entries.push(entry);
+				},
+			};
+
+			const logger = createStructuredLogger({ output: testOutput });
+
+			const error = new Error("Without stack");
+			logger.error("Error without stack", { error });
+
+			expect(entries[0].stack).toBeUndefined();
+		});
+	});
+
+	describe("child logger", () => {
+		it("creates child logger with inherited context", () => {
+			const entries: LogEntry[] = [];
+			const testOutput: LogOutput = {
+				write(entry) {
+					entries.push(entry);
+				},
+			};
+
+			const parent = createStructuredLogger({
+				output: testOutput,
+				defaultContext: { app: "test-app" },
+			});
+
+			const child = parent.child({ requestId: "req-123" });
+
+			child.info("Child message");
+
+			expect(entries[0].app).toBe("test-app");
+			expect(entries[0].requestId).toBe("req-123");
+		});
+
+		it("child context overrides parent context", () => {
+			const entries: LogEntry[] = [];
+			const testOutput: LogOutput = {
+				write(entry) {
+					entries.push(entry);
+				},
+			};
+
+			const parent = createStructuredLogger({
+				output: testOutput,
+				defaultContext: { version: "1.0" },
+			});
+
+			const child = parent.child({ version: "2.0" });
+
+			child.info("Override test");
+
+			expect(entries[0].version).toBe("2.0");
+		});
+	});
+
+	describe("request logging", () => {
+		it("logs with request ID", () => {
+			const entries: LogEntry[] = [];
+			const testOutput: LogOutput = {
+				write(entry) {
+					entries.push(entry);
+				},
+			};
+
+			const logger = createStructuredLogger({ output: testOutput });
+
+			logger.request("req-456", "Request started", { path: "/api/users" });
+
+			expect(entries[0].requestId).toBe("req-456");
+			expect(entries[0].path).toBe("/api/users");
+		});
+	});
+
+	describe("operation tracking", () => {
+		it("tracks operation duration on success", async () => {
+			const entries: LogEntry[] = [];
+			const testOutput: LogOutput = {
+				write(entry) {
+					entries.push(entry);
+				},
+			};
+
+			const logger = createStructuredLogger({
+				output: testOutput,
+				level: "debug",
+			});
+
+			const done = logger.startOperation("getUser", { requestId: "req-789" });
+
+			// Simulate some work
+			await new Promise((r) => setTimeout(r, 10));
+
+			done();
+
+			// Should have start and completion logs
+			expect(entries.length).toBe(2);
+			expect(entries[0].message).toContain("started");
+			expect(entries[1].message).toContain("completed");
+			// Check duration is tracked (avoid exact timing assertions for CI stability)
+			expect(typeof entries[1].durationMs).toBe("number");
+			expect(entries[1].durationMs).toBeGreaterThanOrEqual(0);
+			expect(entries[1].operation).toBe("getUser");
+		});
+
+		it("tracks operation duration on error", async () => {
+			const entries: LogEntry[] = [];
+			const testOutput: LogOutput = {
+				write(entry) {
+					entries.push(entry);
+				},
+			};
+
+			const logger = createStructuredLogger({
+				output: testOutput,
+				level: "debug",
+			});
+
+			const done = logger.startOperation("createUser");
+
+			done({ error: new Error("Validation failed") });
+
+			expect(entries.length).toBe(2);
+			expect(entries[1].message).toContain("failed");
+			expect(entries[1].errorMessage).toBe("Validation failed");
+		});
+	});
+});
+
+describe("outputs", () => {
+	describe("jsonOutput", () => {
+		it("outputs JSON to console", () => {
+			const consoleSpy = spyOn(console, "log").mockImplementation(() => {});
+
+			jsonOutput.write({
+				timestamp: "2024-01-01T00:00:00.000Z",
+				level: "info",
+				message: "Test",
+			});
+
+			expect(consoleSpy).toHaveBeenCalledWith(
+				'{"timestamp":"2024-01-01T00:00:00.000Z","level":"info","message":"Test"}',
+			);
+
+			consoleSpy.mockRestore();
+		});
+	});
+
+	describe("prettyOutput", () => {
+		it("outputs formatted message to console", () => {
+			const consoleSpy = spyOn(console, "log").mockImplementation(() => {});
+
+			prettyOutput.write({
+				timestamp: "2024-01-01T00:00:00.000Z",
+				level: "info",
+				message: "Test message",
+			});
+
+			expect(consoleSpy).toHaveBeenCalled();
+			const output = consoleSpy.mock.calls[0][0] as string;
+			expect(output).toContain("INFO");
+			expect(output).toContain("Test message");
+
+			consoleSpy.mockRestore();
+		});
+	});
+});
+
+describe("toBasicLogger", () => {
+	it("adapts structured logger to basic interface", () => {
+		const entries: LogEntry[] = [];
+		const testOutput: LogOutput = {
+			write(entry) {
+				entries.push(entry);
+			},
+		};
+
+		const structuredLogger = createStructuredLogger({ output: testOutput });
+		const basicLogger = toBasicLogger(structuredLogger);
+
+		basicLogger.info("Info message");
+		basicLogger.warn("Warn message");
+		basicLogger.error("Error message");
+
+		expect(entries.length).toBe(3);
+		expect(entries[0].level).toBe("info");
+		expect(entries[1].level).toBe("warn");
+		expect(entries[2].level).toBe("error");
+	});
+
+	it("handles error arguments in basic logger", () => {
+		const entries: LogEntry[] = [];
+		const testOutput: LogOutput = {
+			write(entry) {
+				entries.push(entry);
+			},
+		};
+
+		const structuredLogger = createStructuredLogger({ output: testOutput });
+		const basicLogger = toBasicLogger(structuredLogger);
+
+		const error = new Error("Test error");
+		basicLogger.error("Failed:", error);
+
+		expect(entries[0].errorMessage).toBe("Test error");
+	});
+});

package/src/logging/structured-logger.ts

@@ -0,0 +1,335 @@
+/**
+ * @sylphx/lens-server - Structured Logging
+ *
+ * Production-ready structured logging with JSON output.
+ * Compatible with log aggregators (DataDog, Splunk, ELK, etc.)
+ */
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Log levels (RFC 5424 severity)
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error" | "fatal";
+
+/**
+ * Base log context - always included
+ */
+export interface LogContext {
+	/** Timestamp in ISO format */
+	timestamp: string;
+	/** Log level */
+	level: LogLevel;
+	/** Log message */
+	message: string;
+	/** Service/component name */
+	service?: string;
+}
+
+/**
+ * Request context for API operations
+ */
+export interface RequestContext {
+	/** Unique request/correlation ID */
+	requestId?: string;
+	/** Operation being executed */
+	operation?: string;
+	/** Client identifier */
+	clientId?: string;
+	/** Request duration in milliseconds */
+	durationMs?: number;
+}
+
+/**
+ * Error context for error logs
+ */
+export interface ErrorContext {
+	/** Error name/type */
+	errorType?: string;
+	/** Error message */
+	errorMessage?: string;
+	/** Stack trace (only in development) */
+	stack?: string;
+	/** Error code */
+	errorCode?: string;
+}
+
+/**
+ * WebSocket context
+ */
+export interface WebSocketContext {
+	/** Message type */
+	messageType?: string;
+	/** Subscription ID */
+	subscriptionId?: string;
+	/** Entity type */
+	entity?: string;
+	/** Entity ID */
+	entityId?: string;
+	/** Connection count */
+	connectionCount?: number;
+	/** Subscription count */
+	subscriptionCount?: number;
+}
+
+/**
+ * Performance context
+ */
+export interface PerformanceContext {
+	/** Memory usage in bytes */
+	memoryUsed?: number;
+	/** CPU usage percentage */
+	cpuPercent?: number;
+	/** Active connections */
+	activeConnections?: number;
+	/** Active subscriptions */
+	activeSubscriptions?: number;
+	/** Messages per second */
+	messagesPerSecond?: number;
+}
+
+/**
+ * Full log entry type
+ */
+export type LogEntry = LogContext &
+	Partial<RequestContext> &
+	Partial<ErrorContext> &
+	Partial<WebSocketContext> &
+	Partial<PerformanceContext> & {
+		[key: string]: unknown;
+	};
+
+/**
+ * Logger output destination
+ */
+export interface LogOutput {
+	write(entry: LogEntry): void;
+}
+
+/**
+ * Structured logger configuration
+ */
+export interface StructuredLoggerOptions {
+	/** Service name for log entries */
+	service?: string;
+	/** Minimum log level to output */
+	level?: LogLevel;
+	/** Include stack traces in error logs */
+	includeStackTrace?: boolean;
+	/** Custom output destination */
+	output?: LogOutput;
+	/** Additional context to include in all logs */
+	defaultContext?: Record<string, unknown>;
+}
+
+// =============================================================================
+// Log Level Priority
+// =============================================================================
+
+const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
+	debug: 0,
+	info: 1,
+	warn: 2,
+	error: 3,
+	fatal: 4,
+};
+
+// =============================================================================
+// Default Outputs
+// =============================================================================
+
+/**
+ * JSON console output (production)
+ */
+export const jsonOutput: LogOutput = {
+	write(entry: LogEntry): void {
+		console.log(JSON.stringify(entry));
+	},
+};
+
+/**
+ * Pretty console output (development)
+ */
+export const prettyOutput: LogOutput = {
+	write(entry: LogEntry): void {
+		const { timestamp, level, message, ...rest } = entry;
+		const color = {
+			debug: "\x1b[36m", // cyan
+			info: "\x1b[32m", // green
+			warn: "\x1b[33m", // yellow
+			error: "\x1b[31m", // red
+			fatal: "\x1b[35m", // magenta
+		}[level];
+		const reset = "\x1b[0m";
+
+		const contextStr = Object.keys(rest).length > 0 ? ` ${JSON.stringify(rest)}` : "";
+
+		console.log(`${timestamp} ${color}[${level.toUpperCase()}]${reset} ${message}${contextStr}`);
+	},
+};
+
+// =============================================================================
+// Structured Logger
+// =============================================================================
+
+/**
+ * Structured logger interface
+ */
+export interface StructuredLogger {
+	debug: (message: string, context?: Record<string, unknown>) => void;
+	info: (message: string, context?: Record<string, unknown>) => void;
+	warn: (message: string, context?: Record<string, unknown>) => void;
+	error: (message: string, context?: Record<string, unknown>) => void;
+	fatal: (message: string, context?: Record<string, unknown>) => void;
+	child: (childContext: Record<string, unknown>) => StructuredLogger;
+	request: (requestId: string, message: string, context?: Record<string, unknown>) => void;
+	startOperation: (
+		operation: string,
+		context?: Record<string, unknown>,
+	) => (result?: { error?: Error; data?: unknown }) => void;
+}
+
+/**
+ * Create a structured logger instance.
+ *
+ * @example
+ * ```typescript
+ * const logger = createStructuredLogger({
+ *   service: 'lens-server',
+ *   level: 'info',
+ * });
+ *
+ * logger.info('Request started', { requestId: 'abc', operation: 'getUser' });
+ * logger.error('Request failed', { requestId: 'abc', error: err });
+ * ```
+ */
+export function createStructuredLogger(options: StructuredLoggerOptions = {}): StructuredLogger {
+	const {
+		service = "lens",
+		level: minLevel = "info",
+		includeStackTrace = false,
+		output = jsonOutput,
+		defaultContext = {},
+	} = options;
+
+	const minPriority = LOG_LEVEL_PRIORITY[minLevel];
+
+	function shouldLog(level: LogLevel): boolean {
+		return LOG_LEVEL_PRIORITY[level] >= minPriority;
+	}
+
+	function log(level: LogLevel, message: string, context: Record<string, unknown> = {}): void {
+		if (!shouldLog(level)) return;
+
+		// Extract error if present
+		const error = context.error instanceof Error ? context.error : undefined;
+		const errorContext: Partial<ErrorContext> = {};
+
+		if (error) {
+			errorContext.errorType = error.name;
+			errorContext.errorMessage = error.message;
+			if (includeStackTrace && error.stack) {
+				errorContext.stack = error.stack;
+			}
+		}
+
+		// Build log entry
+		const entry: LogEntry = {
+			timestamp: new Date().toISOString(),
+			level,
+			message,
+			service,
+			...defaultContext,
+			...context,
+			...errorContext,
+		};
+
+		// Remove the original error object from context
+		if ("error" in entry && entry.error instanceof Error) {
+			delete entry.error;
+		}
+
+		output.write(entry);
+	}
+
+	return {
+		debug: (message: string, context?: Record<string, unknown>) => log("debug", message, context),
+		info: (message: string, context?: Record<string, unknown>) => log("info", message, context),
+		warn: (message: string, context?: Record<string, unknown>) => log("warn", message, context),
+		error: (message: string, context?: Record<string, unknown>) => log("error", message, context),
+		fatal: (message: string, context?: Record<string, unknown>) => log("fatal", message, context),
+
+		/**
+		 * Create a child logger with additional default context.
+		 */
+		child: (childContext: Record<string, unknown>) => {
+			return createStructuredLogger({
+				...options,
+				defaultContext: { ...defaultContext, ...childContext },
+			});
+		},
+
+		/**
+		 * Log with request context (for tracking request lifecycle).
+		 */
+		request: (requestId: string, message: string, context?: Record<string, unknown>) => {
+			log("info", message, { requestId, ...context });
+		},
+
+		/**
+		 * Log operation start (returns a function to log completion).
+		 */
+		startOperation: (
+			operation: string,
+			context?: Record<string, unknown>,
+		): ((result?: { error?: Error; data?: unknown }) => void) => {
+			const startTime = Date.now();
+			const requestId = context?.requestId as string | undefined;
+
+			log("debug", `Operation started: ${operation}`, { operation, ...context });
+
+			return (result?: { error?: Error; data?: unknown }) => {
+				const durationMs = Date.now() - startTime;
+
+				if (result?.error) {
+					log("error", `Operation failed: ${operation}`, {
+						operation,
+						requestId,
+						durationMs,
+						error: result.error,
+					});
+				} else {
+					log("info", `Operation completed: ${operation}`, {
+						operation,
+						requestId,
+						durationMs,
+					});
+				}
+			};
+		},
+	};
+}
+
+/**
+ * Adapter to make structured logger compatible with basic logger interface.
+ */
+export function toBasicLogger(structuredLogger: StructuredLogger): {
+	info: (message: string, ...args: unknown[]) => void;
+	warn: (message: string, ...args: unknown[]) => void;
+	error: (message: string, ...args: unknown[]) => void;
+} {
+	return {
+		info: (message: string, ...args: unknown[]) => {
+			structuredLogger.info(message, args.length > 0 ? { args } : undefined);
+		},
+		warn: (message: string, ...args: unknown[]) => {
+			structuredLogger.warn(message, args.length > 0 ? { args } : undefined);
+		},
+		error: (message: string, ...args: unknown[]) => {
+			const error = args.find((arg) => arg instanceof Error) as Error | undefined;
+			structuredLogger.error(message, error ? { error } : args.length > 0 ? { args } : undefined);
+		},
+	};
+}