mcp-server-framework 1.0.0

package/build/logger/logger.d.ts

@@ -0,0 +1,278 @@
+/**
+ * Logger Facade Module
+ *
+ * Provides a unified logging interface that delegates to specialized components:
+ * - Context management via core/context.ts
+ * - Formatting via formatters/ (Text/JSON)
+ * - Output via writers/ (Console/File/MCP)
+ * - Security via scrubbing/ (SecretScrubber/InjectionGuard)
+ * - Resource management via factory.ts (DI-enabled)
+ *
+ * This facade follows the Single Responsibility Principle by coordinating
+ * the logging pipeline without implementing the details itself.
+ *
+ * @module logger
+ */
+import type { LogLevel, TransportMode, LogContext, LoggerInterface } from "./core/types.js";
+import { LoggerResources, initializeLoggerResources, resetLoggerResources } from "./factory.js";
+export type { LoggerSystemConfig, LoggerDependencies } from "./factory.js";
+export { LoggerResources, initializeLoggerResources, resetLoggerResources };
+/**
+ * Global logger configuration.
+ * Must be set before creating logger instances.
+ */
+export interface GlobalLoggerConfig {
+    /** Log level */
+    LOG_LEVEL: LogLevel;
+    /** Log format */
+    LOG_FORMAT: "text" | "json";
+    /** Transport mode */
+    MCP_TRANSPORT: TransportMode;
+    /** Node environment */
+    NODE_ENV: "development" | "production" | "test";
+    /** Log directory (optional) */
+    LOG_DIR?: string | undefined;
+    /** Maximum log file size in bytes before rotation */
+    LOG_MAX_FILE_SIZE?: number | undefined;
+    /** Number of rotated log files to keep */
+    LOG_MAX_FILES?: number | undefined;
+    /** Log file retention in days (0 = disabled) */
+    LOG_RETENTION_DAYS?: number | undefined;
+    /** Include timestamps in text log output */
+    LOG_TIMESTAMP?: boolean | undefined;
+    /** Include component name in text log output */
+    LOG_COMPONENT?: boolean | undefined;
+    /** Server name */
+    SERVER_NAME: string;
+    /** Server version */
+    SERVER_VERSION: string;
+}
+/**
+ * Configure the global logger settings.
+ * Should be called once at application startup before creating loggers.
+ *
+ * @param config - Logger configuration options
+ *
+ * @example
+ * ```typescript
+ * // In app initialization
+ * configureLogger({
+ *   LOG_LEVEL: config.LOG_LEVEL,
+ *   LOG_FORMAT: config.LOG_FORMAT,
+ *   MCP_TRANSPORT: config.MCP_TRANSPORT,
+ *   NODE_ENV: config.NODE_ENV,
+ *   LOG_DIR: config.LOG_DIR,
+ *   SERVER_NAME: 'mcp-server',
+ *   SERVER_VERSION: '1.0.0',
+ * });
+ * ```
+ */
+export declare function configureLogger(config: Partial<GlobalLoggerConfig>): void;
+/**
+ * Get the current global logger configuration.
+ */
+export declare function getLoggerConfig(): GlobalLoggerConfig;
+/**
+ * Reset the global logger configuration to defaults.
+ * Primarily for testing.
+ */
+export declare function resetLoggerConfig(): void;
+/**
+ * Logger configuration options.
+ */
+export interface LoggerOptions {
+    /** Component name for log categorization */
+    component?: string;
+    /** Override log level (uses config.LOG_LEVEL by default) */
+    level?: LogLevel;
+    /** Optional resources instance (for testing/DI) */
+    resources?: LoggerResources;
+}
+/**
+ * Centralized Logger Facade
+ *
+ * Coordinates the logging pipeline:
+ * 1. Level filtering
+ * 2. Message formatting (printf-style)
+ * 3. Metadata extraction
+ * 4. Secret scrubbing
+ * 5. Formatting (Text/JSON)
+ * 6. Injection prevention
+ * 7. Output to writers (Console/File/MCP)
+ *
+ * Now uses LoggerResources for DI-enabled resource management,
+ * eliminating the static state anti-pattern while maintaining
+ * backward compatibility through lazy global initialization.
+ *
+ * @example
+ * ```typescript
+ * // Simple usage (global resources)
+ * const logger = new Logger('api');
+ * logger.info('Request received', { method: 'GET', path: '/health' });
+ *
+ * // DI usage (custom resources for testing)
+ * const resources = new LoggerResources(config, mockDeps);
+ * const testLogger = new Logger({ component: 'test', resources });
+ * ```
+ */
+export declare class Logger implements LoggerInterface {
+    /** Override log level (if set in options, otherwise uses global config) */
+    private readonly levelOverride;
+    /** Component name for this logger instance */
+    private readonly component;
+    /** Explicitly injected resources (DI/testing only) — `null` means use global */
+    private readonly _injectedResources;
+    /** Resolve the active resources: injected for DI, otherwise global (dynamic). */
+    private get resources();
+    /**
+     * Get the effective log level (numeric for fast comparison).
+     * Uses override if set, otherwise reads from global config dynamically.
+     */
+    private get level();
+    /**
+     * Create a new Logger instance.
+     *
+     * @param componentOrOptions - Component name string or options object
+     */
+    constructor(componentOrOptions?: string | LoggerOptions);
+    /**
+     * Get or initialize global resources lazily.
+     * Provides backward compatibility with existing code.
+     */
+    private static getOrInitializeResources;
+    /**
+     * Close all writers gracefully.
+     * Should be called during application shutdown.
+     *
+     * @returns Promise that resolves when all writers are closed
+     */
+    static closeStreams(): Promise<void>;
+    /**
+     * Clear the child logger cache.
+     * Useful for testing or when configuration changes.
+     */
+    static clearChildLoggerCache(): void;
+    /**
+     * Reset static state (for testing purposes).
+     * Fully resets all resources.
+     */
+    static resetState(): Promise<void>;
+    /**
+     * Create a child logger with a specific component context.
+     * Uses LRU caching to avoid creating new instances while preventing memory leaks.
+     *
+     * @param context - The component context for the child logger
+     * @returns A cached or new Logger instance
+     */
+    child(context: {
+        component: string;
+    }): Logger;
+    /**
+     * Run a function within a logging context.
+     * All logs within the function will include the context.
+     *
+     * @param context - The context to use for logging
+     * @param fn - The function to execute
+     * @returns The result of the function
+     */
+    runWithContext<T>(context: LogContext, fn: () => T): T;
+    /**
+     * Get the current logging context.
+     *
+     * @returns The current context or undefined
+     */
+    getContext(): LogContext | undefined;
+    /**
+     * Merge additional context with the current context.
+     *
+     * @param additionalContext - Context values to add/override
+     * @returns A new merged context
+     */
+    mergeContext(additionalContext: Partial<LogContext>): LogContext;
+    /**
+     * Create a child context that inherits from the current context.
+     * Component names are automatically concatenated.
+     *
+     * @param childContext - Context values for the child
+     * @returns A new child context
+     */
+    createChildContext(childContext: Partial<LogContext>): LogContext;
+    /**
+     * Execute a function with an extended context.
+     *
+     * @param additionalContext - Context values to add
+     * @param fn - The function to execute
+     * @returns The result of the function
+     */
+    withExtendedContext<T>(additionalContext: Partial<LogContext>, fn: () => T): T;
+    /**
+     * Execute a function with a child context.
+     *
+     * @param childContext - Context values for the child scope
+     * @param fn - The function to execute
+     * @returns The result of the function
+     */
+    withChildContext<T>(childContext: Partial<LogContext>, fn: () => T): T;
+    /**
+     * Get the current context nesting depth.
+     *
+     * @returns The current depth
+     */
+    getContextDepth(): number;
+    /**
+     * Log a message at TRACE level.
+     */
+    trace(message: string, ...args: unknown[]): void;
+    /**
+     * Log a message at DEBUG level.
+     */
+    debug(message: string, ...args: unknown[]): void;
+    /**
+     * Log a message at INFO level.
+     */
+    info(message: string, ...args: unknown[]): void;
+    /**
+     * Log a message at WARN level.
+     */
+    warn(message: string, ...args: unknown[]): void;
+    /**
+     * Log a message at ERROR level.
+     */
+    error(message: string, ...args: unknown[]): void;
+    /**
+     * Internal log handler implementing the logging pipeline.
+     *
+     * Pipeline steps:
+     * 1. Level filtering
+     * 2. Metadata extraction
+     * 3. Printf-style formatting
+     * 4. Message truncation (if exceeds MAX_MESSAGE_LENGTH)
+     * 5. Context retrieval
+     * 6. Secret scrubbing
+     * 7. Format generation (Text/JSON)
+     * 8. Injection prevention
+     * 9. Output to writers
+     * 10. MCP notification (if context has sendMcpLog)
+     */
+    private log;
+    /**
+     * Extract metadata object from log arguments.
+     * The last argument is treated as metadata if it's a plain object (not an Error).
+     */
+    private extractMetadata;
+    /**
+     * Apply injection guard and secret scrubbing to formatted log output.
+     */
+    private sanitizeOutput;
+    /**
+     * Write formatted output to all configured writers.
+     */
+    private writeToOutputs;
+}
+/**
+ * Default logger instance for the application.
+ * Uses dynamic log level from global config, so configureLogger()
+ * can be called at any time to change the effective log level.
+ */
+export declare const logger: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/build/logger/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logger/logger.ts"],"names":[],"mappings":"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"}