@sockethub/logger 1.0.0-alpha.11

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@sockethub/logger",
+  "description": "Winston-based logger for Sockethub packages",
+  "version": "1.0.0-alpha.11",
+  "type": "module",
+  "private": false,
+  "author": "Nick Jennings <nick@silverbucket.net>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "src/",
+    "dist/"
+  ],
+  "engines": {
+    "bun": ">=1.2"
+  },
+  "keywords": [
+    "sockethub",
+    "logging",
+    "winston"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sockethub/sockethub.git",
+    "directory": "packages/logger"
+  },
+  "homepage": "https://github.com/sockethub/sockethub/tree/master/packages/logger",
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target node --format esm --sourcemap=external",
+    "clean": "rm -rf dist",
+    "clean:deps": "rm -rf node_modules",
+    "test": "bun test src/"
+  },
+  "dependencies": {
+    "winston": "^3.19.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "gitHead": "c243fa9e76c688ce5ffcf524400b1dd27dcce615"
+}

package/src/index.test.ts

@@ -0,0 +1,245 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import {
+    type Logger,
+    type LoggerOptions,
+    createLogger,
+    getLoggerContext,
+    getLoggerNamespace,
+    initLogger,
+    resetLoggerContext,
+    resetLoggerForTesting,
+    setLoggerContext,
+} from "./index.js";
+
+describe("Logger Package", () => {
+    beforeEach(() => {
+        resetLoggerForTesting();
+        delete process.env.LOG_LEVEL;
+        delete process.env.LOG_FILE_LEVEL;
+        delete process.env.LOG_FILE;
+    });
+
+    afterEach(() => {
+        resetLoggerForTesting();
+    });
+
+    describe("createLogger", () => {
+        it("creates a logger with namespace", () => {
+            const log = createLogger("test:namespace");
+            expect(log).toBeDefined();
+            expect(log.info).toBeFunction();
+            expect(log.warn).toBeFunction();
+            expect(log.error).toBeFunction();
+            expect(log.debug).toBeFunction();
+        });
+
+        it("uses default level info when no config provided", () => {
+            const log = createLogger("test:namespace");
+            expect(log).toBeDefined();
+            // Winston loggers have transports array
+            expect(log.transports).toBeArray();
+            expect(log.transports.length).toBeGreaterThan(0);
+        });
+
+        it("respects explicit options over defaults", () => {
+            const log = createLogger("test:namespace", { level: "error" });
+            expect(log).toBeDefined();
+            const consoleTransport = log.transports[0];
+            expect(consoleTransport.level).toBe("error");
+        });
+
+        it("respects environment variables when no global config", () => {
+            process.env.LOG_LEVEL = "warn";
+            const log = createLogger("test:namespace");
+            const consoleTransport = log.transports[0];
+            expect(consoleTransport.level).toBe("warn");
+        });
+
+        it("creates file transport when file path provided", () => {
+            const log = createLogger("test:namespace", {
+                file: "/tmp/test.log",
+            });
+            expect(log.transports.length).toBe(2); // console + file
+        });
+
+        it("does not create file transport when file is empty string", () => {
+            const log = createLogger("test:namespace", { file: "" });
+            expect(log.transports.length).toBe(1); // console only
+        });
+    });
+
+    describe("getLoggerNamespace", () => {
+        it("returns namespace from logger instance", () => {
+            const log = createLogger("test:namespace");
+            const namespace = getLoggerNamespace(log);
+            expect(namespace).toBe("test:namespace");
+        });
+
+        it("returns namespace with context when set", () => {
+            setLoggerContext("myapp");
+            const log = createLogger("test:namespace");
+            const namespace = getLoggerNamespace(log);
+            expect(namespace).toBe("myapp:test:namespace");
+        });
+
+        it("returns empty string for logger without namespace", () => {
+            const log = createLogger("");
+            const namespace = getLoggerNamespace(log);
+            expect(namespace).toBe("");
+        });
+    });
+
+    describe("initLogger", () => {
+        it("sets global config for subsequent createLogger calls", () => {
+            initLogger({
+                level: "debug",
+                fileLevel: "info",
+                file: "/tmp/global.log",
+            });
+
+            const log = createLogger("test:namespace");
+            expect(log.transports.length).toBe(2); // console + file
+            const consoleTransport = log.transports[0];
+            expect(consoleTransport.level).toBe("debug");
+        });
+
+        it("allows explicit options to override global config", () => {
+            initLogger({ level: "info" });
+
+            const log = createLogger("test:namespace", { level: "error" });
+            const consoleTransport = log.transports[0];
+            expect(consoleTransport.level).toBe("error");
+        });
+
+        it("global config takes precedence over ENV vars", () => {
+            process.env.LOG_LEVEL = "warn";
+            initLogger({ level: "debug" });
+
+            const log = createLogger("test:namespace");
+            const consoleTransport = log.transports[0];
+            expect(consoleTransport.level).toBe("debug");
+        });
+    });
+
+    describe("configuration priority", () => {
+        it("follows priority: explicit > global > env > default", () => {
+            // Set up all sources
+            process.env.LOG_LEVEL = "warn";
+            initLogger({ level: "info" });
+
+            // Explicit wins
+            const log1 = createLogger("test:1", { level: "error" });
+            expect(log1.transports[0].level).toBe("error");
+
+            // Global wins over env
+            const log2 = createLogger("test:2");
+            expect(log2.transports[0].level).toBe("info");
+        });
+
+        it("falls back to env when no global config", () => {
+            process.env.LOG_LEVEL = "warn";
+            const log = createLogger("test:namespace");
+            expect(log.transports[0].level).toBe("warn");
+        });
+
+        it("falls back to default when no config at all", () => {
+            const log = createLogger("test:namespace");
+            expect(log.transports[0].level).toBe("info");
+        });
+    });
+
+    describe("edge cases", () => {
+        it("handles createLogger before initLogger", () => {
+            // This happens during early bootstrap
+            const earlyLog = createLogger("bootstrap", { level: "info" });
+            expect(earlyLog).toBeDefined();
+
+            // Later, initLogger is called
+            initLogger({ level: "debug" });
+
+            // New loggers get global config
+            const laterLog = createLogger("later");
+            expect(laterLog.transports[0].level).toBe("debug");
+
+            // But early logger keeps its config
+            expect(earlyLog.transports[0].level).toBe("info");
+        });
+
+        it("handles file: undefined vs file: empty string", () => {
+            initLogger({ file: "/tmp/test.log" });
+
+            // Explicit empty string disables file
+            const log1 = createLogger("test:1", { file: "" });
+            expect(log1.transports.length).toBe(1);
+
+            // No explicit option uses global
+            const log2 = createLogger("test:2");
+            expect(log2.transports.length).toBe(2);
+        });
+    });
+
+    describe("logger context", () => {
+        it("createLogger without context uses namespace as-is", () => {
+            const log = createLogger("test:namespace");
+            expect(log.defaultMeta.namespace).toBe("test:namespace");
+        });
+
+        it("createLogger with context prepends context to namespace", () => {
+            setLoggerContext("myapp");
+            const log = createLogger("test:namespace");
+            expect(log.defaultMeta.namespace).toBe("myapp:test:namespace");
+        });
+
+        it("getLoggerContext returns empty string by default", () => {
+            expect(getLoggerContext()).toBe("");
+        });
+
+        it("getLoggerContext returns the set context", () => {
+            setLoggerContext("myapp:process");
+            expect(getLoggerContext()).toBe("myapp:process");
+        });
+
+        it("resetLoggerContext clears the context", () => {
+            setLoggerContext("myapp");
+            expect(getLoggerContext()).toBe("myapp");
+
+            resetLoggerContext();
+            expect(getLoggerContext()).toBe("");
+
+            const log = createLogger("test");
+            expect(log.defaultMeta.namespace).toBe("test");
+        });
+
+        it("context works with nested namespaces", () => {
+            setLoggerContext("sockethub:platform:irc:abc123");
+            const log = createLogger("data-layer:worker");
+            expect(log.defaultMeta.namespace).toBe(
+                "sockethub:platform:irc:abc123:data-layer:worker",
+            );
+        });
+
+        it("context is process-wide, affects all subsequent loggers", () => {
+            setLoggerContext("process-context");
+
+            const log1 = createLogger("module1");
+            const log2 = createLogger("module2");
+            const log3 = createLogger("module3");
+
+            expect(log1.defaultMeta.namespace).toBe("process-context:module1");
+            expect(log2.defaultMeta.namespace).toBe("process-context:module2");
+            expect(log3.defaultMeta.namespace).toBe("process-context:module3");
+        });
+
+        it("resetLoggerForTesting also resets context", () => {
+            setLoggerContext("myapp");
+            initLogger({ level: "debug" });
+
+            resetLoggerForTesting();
+
+            expect(getLoggerContext()).toBe("");
+            const log = createLogger("test");
+            expect(log.defaultMeta.namespace).toBe("test");
+            expect(log.transports[0].level).toBe("info"); // back to default
+        });
+    });
+});

package/src/index.ts

@@ -0,0 +1,263 @@
+import winston from "winston";
+
+export type Logger = winston.Logger;
+
+export interface LoggerOptions {
+    level?: string;
+    fileLevel?: string;
+    file?: string;
+}
+
+// Global configuration state (set once at bootstrap via initLogger)
+let globalConfig: LoggerOptions | null = null;
+let hasLoggedInit = false;
+
+// Process-wide logger context (set once at process startup)
+let loggerContext = "";
+let loggerNamespaceStore = new WeakMap<Logger, string>();
+
+/**
+ * Initialize the logger system with global configuration.
+ *
+ * Called once at server bootstrap with config settings. All subsequent
+ * createLogger() calls will use these settings as defaults unless explicitly
+ * overridden.
+ *
+ * @param options - Global logger configuration
+ *
+ * @example
+ * ```typescript
+ * // In server bootstrap
+ * initLogger({
+ *   level: config.get("logging:level"),
+ *   fileLevel: config.get("logging:fileLevel"),
+ *   file: config.get("logging:file"),
+ * });
+ * ```
+ */
+export function initLogger(options: LoggerOptions): void {
+    globalConfig = options;
+
+    if (!hasLoggedInit) {
+        hasLoggedInit = true;
+        const initLog = createLogger("sockethub:logger");
+        initLog.debug("logger system initialized");
+        if (options.file) {
+            initLog.info(`log file path: ${options.file}`);
+            initLog.info(`file log level: ${options.fileLevel || "debug"}`);
+        }
+        initLog.info(`console log level: ${options.level || "info"}`);
+    }
+}
+
+/**
+ * Set the logger context for this process.
+ *
+ * All subsequent createLogger() calls will prepend this context to their namespace.
+ * This is typically set once at process startup to identify the process (e.g., "sockethub"
+ * for the main server, or "sockethub:platform:irc:abc123" for a platform child process).
+ *
+ * @param context - The context string to prepend to all logger namespaces in this process
+ *
+ * @example
+ * ```typescript
+ * // In main server process
+ * setLoggerContext('sockethub');
+ * const log = createLogger('server:listener');
+ * // Output namespace: "sockethub:server:listener"
+ *
+ * // In platform child process
+ * setLoggerContext('sockethub:platform:irc:abc123');
+ * const log = createLogger('main');
+ * // Output namespace: "sockethub:platform:irc:abc123:main"
+ * ```
+ */
+export function setLoggerContext(context: string): void {
+    loggerContext = context;
+}
+
+/**
+ * Get the current logger context for this process.
+ *
+ * @returns The current logger context string, or empty string if not set
+ *
+ * @example
+ * ```typescript
+ * const context = getLoggerContext();
+ * if (context.includes(':platform:')) {
+ *   // We're in a platform child process
+ * }
+ * ```
+ */
+export function getLoggerContext(): string {
+    return loggerContext;
+}
+
+/**
+ * Reset the logger context.
+ *
+ * Primarily used for testing to reset state between test cases.
+ *
+ * @example
+ * ```typescript
+ * afterEach(() => {
+ *   resetLoggerContext();
+ * });
+ * ```
+ */
+export function resetLoggerContext(): void {
+    loggerContext = "";
+}
+
+/**
+ * Creates a Winston logger instance with console and optional file transports.
+ *
+ * Configuration priority (highest to lowest):
+ * 1. Explicit options parameter
+ * 2. Global config (set via initLogger)
+ * 3. Environment variables (LOG_LEVEL, LOG_FILE_LEVEL, LOG_FILE)
+ * 4. Defaults (info for console, debug for file)
+ *
+ * Log levels: error, warn, info, debug
+ *
+ * NODE_ENV=production disables console timestamps (for systemd)
+ *
+ * @param namespace - Logger namespace (e.g., "sockethub:data-layer:queue:...")
+ * @param options - Optional logger configuration overrides
+ * @returns Winston logger instance
+ *
+ * @example
+ * ```typescript
+ * // Uses global config if initLogger() was called
+ * const log = createLogger("sockethub:data-layer:queue:irc-123");
+ *
+ * // Override for specific use case (e.g., early bootstrap logging)
+ * const earlyLog = createLogger("sockethub:bootstrap", { level: "info" });
+ * ```
+ */
+export function createLogger(
+    namespace: string,
+    options: LoggerOptions = {},
+): Logger {
+    // Prepend logger context if set
+    const fullNamespace = loggerContext
+        ? `${loggerContext}:${namespace}`
+        : namespace;
+
+    // Priority: explicit options > global config > ENV > defaults
+    const cfg: LoggerOptions = {
+        level:
+            options.level ??
+            globalConfig?.level ??
+            process.env.LOG_LEVEL ??
+            "info",
+        fileLevel:
+            options.fileLevel ??
+            globalConfig?.fileLevel ??
+            process.env.LOG_FILE_LEVEL ??
+            "debug",
+        file:
+            options.file !== undefined
+                ? options.file
+                : globalConfig?.file !== undefined
+                  ? globalConfig.file
+                  : (process.env.LOG_FILE ?? ""),
+    };
+
+    const isProduction = process.env.NODE_ENV === "production";
+
+    const consoleFormat = isProduction
+        ? winston.format.combine(
+              winston.format.colorize(),
+              winston.format.printf(
+                  ({ level, message, namespace, ...meta }) => {
+                      const ns = namespace ? `${namespace} ` : "";
+                      const metaStr =
+                          Object.keys(meta).length > 0
+                              ? ` ${JSON.stringify(meta)}`
+                              : "";
+                      return `${level}: ${ns}${message}${metaStr}`;
+                  },
+              ),
+          )
+        : winston.format.combine(
+              winston.format.timestamp({ format: "YYYY-MM-DD HH:mm:ss" }),
+              winston.format.colorize(),
+              winston.format.printf(
+                  ({ level, message, timestamp, namespace, ...meta }) => {
+                      const ns = namespace ? `${namespace} ` : "";
+                      const metaStr =
+                          Object.keys(meta).length > 0
+                              ? ` ${JSON.stringify(meta)}`
+                              : "";
+                      return `${timestamp} ${level}: ${ns}${message}${metaStr}`;
+                  },
+              ),
+          );
+
+    const transports: winston.transport[] = [
+        new winston.transports.Console({
+            level: cfg.level,
+            format: consoleFormat,
+        }),
+    ];
+
+    if (cfg.file) {
+        transports.push(
+            new winston.transports.File({
+                level: cfg.fileLevel,
+                filename: cfg.file,
+                format: winston.format.combine(
+                    winston.format.timestamp(),
+                    winston.format.json(),
+                ),
+            }),
+        );
+    }
+
+    const logger = winston.createLogger({
+        level: "debug", // Set to lowest level, let transports filter
+        defaultMeta: { namespace: fullNamespace },
+        transports,
+    });
+    loggerNamespaceStore.set(logger, fullNamespace);
+    return logger;
+}
+
+/**
+ * Get the namespace from a logger instance.
+ *
+ * Extracts the full namespace (including context) that was set when the logger was created.
+ * Useful for reusing the namespace in other systems like Redis connection names.
+ *
+ * @param logger - Logger instance created by createLogger()
+ * @returns The full namespace string, or empty string if not found
+ *
+ * @example
+ * ```typescript
+ * const log = createLogger('data-layer:queue');
+ * const namespace = getLoggerNamespace(log);
+ * // Returns: "sockethub:data-layer:queue" (if context is "sockethub")
+ *
+ * // Use for Redis connection name
+ * redisConfig.connectionName = namespace;
+ * ```
+ */
+export function getLoggerNamespace(logger: Logger): string {
+    return (
+        loggerNamespaceStore.get(logger) ??
+        (logger.defaultMeta as { namespace?: string })?.namespace ??
+        ""
+    );
+}
+
+/**
+ * Reset logger state. Used primarily for testing.
+ * @internal
+ */
+export function resetLoggerForTesting(): void {
+    globalConfig = null;
+    hasLoggedInit = false;
+    loggerContext = "";
+    loggerNamespaceStore = new WeakMap<Logger, string>();
+}