@rawnodes/logger 2.9.0 → 2.10.0

package/README.md

@@ -422,6 +422,39 @@ cloudwatch: {
 }
 ```
 
+### Relay (remote live-tail)
+
+The relay transport runs in a worker thread, polls a config endpoint you control, and — when that endpoint returns `enabled: true` — opens a WebSocket and streams logs to it in real time. Lets you flip on live-tail debugging for a running prod service from a dashboard, without redeploying.
+
+```typescript
+Logger.create({
+  level: 'info',
+  console: { format: 'json' },
+  relay: {
+    apiUrl: 'https://relay.internal.company.com',
+    token: process.env.RELAY_TOKEN!,
+    maskSecrets: true,                      // mask before forwarding (recommended)
+    allowedWsHosts: ['ws.internal.company.com'], // only needed if WS host ≠ apiUrl host
+  },
+});
+```
+
+Server contract (`GET /api/relay/config` with `Authorization: Bearer <token>`):
+
+```jsonc
+{
+  "enabled": true,                 // false = stop streaming, drop logs cheaply
+  "wsUrl":   "wss://...",          // WebSocket gateway to stream to
+  "rules":   [{ "level": "debug", "context": "auth" }]  // optional filters
+}
+```
+
+**Security defaults to know about:**
+
+- **`wsUrl` is pinned to `apiUrl`'s origin by default.** A compromised config endpoint cannot redirect your logs to an arbitrary host. Use `allowedWsHosts` to authorize alternates explicitly.
+- **`maskSecrets` does NOT inherit from the parent logger** — the relay runs in a worker thread and gets only the options you pass to its config. Pass it again here if you want forwarded logs masked. Off by default.
+- The relay writes one stderr line on first successful WS open (`[RelayTransport] streaming logs to ...`) so the fact of streaming is auditable in your normal log output.
+
 ### Transport Options
 
 All external transports support:
@@ -668,26 +701,62 @@ getOrGenerateRequestId(req.headers);          // always returns string
 
 ### Secret Masking
 
-Automatically masks sensitive fields in logs:
+Two ways to use it: a **global flag** that masks every log automatically, or **manual utilities** when you want fine-grained control.
 
-```typescript
-import { maskSecrets, createMasker } from '@rawnodes/logger';
+#### Global flag (recommended)
 
-maskSecrets({
-  user: 'admin',
-  password: 'secret123',
-  apiKey: 'key_abc123',
+Set `maskSecrets: true` in `Logger.create` to mask all output across console / file / CloudWatch / Discord / Telegram / Zoho Cliq. Backwards compatible — masking is **off by default**.
+
+```typescript
+const logger = Logger.create({
+  level: 'info',
+  console: { format: 'json' },
+  file: { format: 'json', dirname: './logs', filename: 'app.log' },
+  maskSecrets: true,
 });
-// { user: 'admin', password: '***', apiKey: '***' }
 
-// Custom masker
-const masker = createMasker({
-  patterns: ['ssn', 'creditCard'],
-  mask: '[REDACTED]'
+logger.info('login', { user: 'alice', password: 'hunter2' });
+// {"level":"info","message":"login","user":"alice","password":"***",...}
+
+logger.info('connect', { url: 'https://u:p@db.example.com/foo' });
+// URL credentials masked: "https://***:***@db.example.com/foo"
+```
+
+Custom patterns / mask string:
+
+```typescript
+Logger.create({
+  ...,
+  maskSecrets: {
+    patterns: ['ssn', 'creditCard'],   // adds to defaults? NO — replaces them
+    mask: '[REDACTED]',
+  },
 });
 ```
 
-**Default masked patterns:** `password`, `secret`, `token`, `apikey`, `api_key`, `api-key`, `auth`, `credential`, `private`
+**Default masked patterns:** `password`, `secret`, `token`, `apikey`, `api_key`, `api-key`, `auth`, `credential`, `private` (case-insensitive substring match on key names).
+
+**Performance:** ~+2.5 µs per log call on a typical payload. Implemented via a `JSON.stringify` replacer for json/CloudWatch (zero clone) and a one-shot clone for HTTP transports that build markdown/embed payloads (Discord/Telegram/Zoho). For most services (< 10k logs/sec) the cost is invisible.
+
+#### Manual utilities
+
+If you only want to mask specific calls — or need a `JSON.stringify` replacer for your own serialization — three helpers are exported:
+
+```typescript
+import { maskSecrets, createMasker, maskReplacer } from '@rawnodes/logger';
+
+// One-shot: returns a deep-cloned masked object
+maskSecrets({ user: 'admin', password: 'secret' });
+// { user: 'admin', password: '***' }
+
+// Reusable: pre-resolves options, slightly faster for repeated calls
+const masker = createMasker({ patterns: ['ssn'], mask: '[REDACTED]' });
+masker({ ssn: '123-45-6789' }); // { ssn: '[REDACTED]' }
+
+// JSON.stringify replacer: zero allocations, masks during serialization
+JSON.stringify(payload, maskReplacer());
+JSON.stringify(payload, maskReplacer({ patterns: ['ssn'] }), 2);
+```
 
 ## Error logging
 

package/dist/index.d.mts

@@ -1,244 +1,7 @@
+import { L as LoggerContext, a as LoggerConfig, b as LevelOverrideMatch, c as LogLevel, d as LevelOverride, M as Meta, D as DiscordConfig, T as TelegramConfig, C as CloudWatchConfig, e as MaskReplacer, Z as ZohoCliqConfig, f as CallerConfig, g as CallerInfo, h as LogFormat, i as LevelRule, j as ConsoleConfig, F as FileConfig, H as HttpTransportBaseConfig, k as LevelConfigObject, l as LevelConfig, R as RelayConfig, A as AutoShutdownConfig, m as LogStreamPattern, n as LogStreamPatternConfig, o as LogStreamTemplateConfig, p as LogStreamName } from './types-lfJLhC8J.mjs';
+export { q as LOG_LEVELS, x as MaskSecretsOptions, t as ZohoCliqBotConfig, s as assertLogLevel, v as createMasker, r as isValidLogLevel, w as maskReplacer, u as maskSecrets } from './types-lfJLhC8J.mjs';
 import { z } from 'zod';
 
-declare const LOG_LEVELS: {
-    readonly off: -1;
-    readonly error: 0;
-    readonly warn: 1;
-    readonly info: 2;
-    readonly http: 3;
-    readonly verbose: 4;
-    readonly debug: 5;
-    readonly silly: 6;
-};
-type LogLevel = keyof typeof LOG_LEVELS;
-declare function isValidLogLevel(level: string): level is LogLevel;
-declare function assertLogLevel(level: string): asserts level is LogLevel;
-type LogFormat = 'json' | 'plain' | 'logfmt' | 'simple';
-interface LevelRule {
-    match: Record<string, unknown> & {
-        context?: string;
-    };
-    level: LogLevel;
-}
-/**
- * Controls whether a transport respects runtime level overrides registered via
- * `setLevelOverride(...)` (or the top-level `level.rules` in the logger config).
- *
- * When `true` (the default for observability transports — console/file/cloudwatch/relay):
- * a matching override bypasses the transport's own `level`/`rules` so that
- * targeted troubleshooting actually surfaces logs in the viewing channels.
- *
- * When `false` (the default for alert-style transports — discord/telegram/zohoCliq):
- * the transport filters strictly by its own `level`/`rules` and ignores runtime
- * overrides, which prevents ad-hoc debug overrides from flooding user-facing
- * notification channels.
- *
- * Every transport config accepts this flag; the only time it needs to be set
- * explicitly is when overriding the default for the transport kind.
- */
-type RespectRuntimeOverrides = boolean;
-interface ConsoleConfig {
-    format: LogFormat;
-    level?: LogLevel;
-    rules?: LevelRule[];
-    respectRuntimeOverrides?: RespectRuntimeOverrides;
-}
-interface FileConfig {
-    format: LogFormat;
-    level?: LogLevel;
-    rules?: LevelRule[];
-    respectRuntimeOverrides?: RespectRuntimeOverrides;
-    dirname: string;
-    filename: string;
-    datePattern?: string;
-    interval?: string;
-    zippedArchive?: boolean;
-    maxSize?: string;
-    maxFiles?: string;
-}
-interface HttpTransportBaseConfig {
-    level?: LogLevel;
-    rules?: LevelRule[];
-    respectRuntimeOverrides?: RespectRuntimeOverrides;
-    batchSize?: number;
-    flushInterval?: number;
-    maxRetries?: number;
-    retryDelay?: number;
-    /**
-     * Maximum number of messages the in-memory queue will hold before dropping.
-     * Provides a hard upper bound on memory usage when a transport is degraded
-     * or offline — without this, a failing transport + steady log volume grows
-     * the queue until OOM. Default: unbounded.
-     *
-     * Recommended for production: `10_000` — enough to absorb transient blips,
-     * small enough to avoid runaway memory.
-     */
-    maxQueueSize?: number;
-    /**
-     * Policy applied when the queue is full.
-     * - `'drop-oldest'` (default): prefers keeping recent events — during an
-     *   outage old logs are usually stale.
-     * - `'drop-newest'`: prefers preserving historical context — useful if you
-     *   care more about the events leading up to the outage than the noise
-     *   happening during it.
-     */
-    dropPolicy?: 'drop-oldest' | 'drop-newest';
-    /**
-     * Called when messages are dropped due to queue overflow. Receives only the
-     * messages that were discarded. If not provided, drops are silent.
-     *
-     * Callback MUST NOT throw; if it does, the exception is swallowed.
-     */
-    onDrop?: (droppedMessages: unknown[]) => void;
-    /**
-     * Called when a batch fails after all retries and messages are dropped.
-     * If not provided, the error is logged to stderr.
-     *
-     * The callback MUST NOT throw; if it does, the failure is swallowed and a
-     * stderr fallback is used. This is intentional — a logger must never
-     * propagate its own transport errors back into the host application.
-     */
-    onError?: (error: Error, droppedMessages: unknown[]) => void;
-    /**
-     * Timeout in milliseconds for a single outbound HTTP request. Default:
-     * `10_000`. Applies to Discord/Telegram `fetch`. CloudWatch uses the AWS
-     * SDK's own timeout configuration.
-     */
-    requestTimeout?: number;
-}
-interface DiscordConfig extends HttpTransportBaseConfig {
-    webhookUrl: string;
-    format?: 'embed' | 'markdown';
-    username?: string;
-    avatarUrl?: string;
-    embedColors?: Partial<Record<LogLevel, number>>;
-    includeTimestamp?: boolean;
-    includeMeta?: boolean;
-    maxEmbedFields?: number;
-}
-interface TelegramConfig extends HttpTransportBaseConfig {
-    botToken: string;
-    chatId: string | number;
-    parseMode?: 'Markdown' | 'MarkdownV2' | 'HTML';
-    disableNotification?: boolean;
-    threadId?: number;
-    replyToMessageId?: number;
-}
-interface ZohoCliqBotConfig {
-    /** Bot display name (shown in the channel). */
-    name: string;
-    /** Optional bot avatar URL. */
-    image?: string;
-}
-interface ZohoCliqConfig extends HttpTransportBaseConfig {
-    /**
-     * Incoming webhook URL. If provided, `companyId`/`channel`/`region` are
-     * ignored and this URL is used as-is (with `zapikey` appended as query).
-     */
-    webhookUrl?: string;
-    /** Zoho Cliq company/org ID. Required unless `webhookUrl` is set. */
-    companyId?: string;
-    /** Target channel name (the `channelsbyname` API segment). Required unless `webhookUrl` is set. */
-    channel?: string;
-    /** Zoho region/TLD: 'eu' | 'com' | 'in' | etc. Default: 'eu'. */
-    region?: string;
-    /** Zoho API key (zapikey). Required. */
-    apiKey: string;
-    /** If true (default), message is posted as a broadcast so all members are notified. */
-    broadcast?: boolean;
-    /** Post as a custom bot instead of the default user. */
-    bot?: ZohoCliqBotConfig;
-    /** Include ISO timestamp in each formatted message. Default: true. */
-    includeTimestamp?: boolean;
-    /** Include meta as a fenced code block. Default: true. */
-    includeMeta?: boolean;
-}
-type LogStreamPattern = 'hostname' | 'hostname-date' | 'hostname-uuid' | 'date' | 'uuid';
-interface LogStreamPatternConfig {
-    pattern: LogStreamPattern;
-}
-interface LogStreamTemplateConfig {
-    /** Custom template with variables: {hostname}, {date}, {datetime}, {uuid}, {pid}, {env} */
-    template: string;
-}
-type LogStreamName = string | LogStreamPatternConfig | LogStreamTemplateConfig;
-interface RelayConfig {
-    /** URL of the relay API (e.g., https://relay.example.com) */
-    apiUrl: string;
-    /** Authentication token for the relay server */
-    token: string;
-    /** Polling interval in ms (default: 30000) */
-    pollInterval?: number;
-    /** Ring buffer capacity - max logs held during reconnect (default: 1000) */
-    bufferSize?: number;
-    /** WebSocket reconnect base delay in ms (default: 1000) */
-    reconnectDelay?: number;
-    /** Max reconnect delay in ms (default: 30000) */
-    maxReconnectDelay?: number;
-    /** See RespectRuntimeOverrides. Default: true (relay is an observability transport). */
-    respectRuntimeOverrides?: RespectRuntimeOverrides;
-}
-interface CloudWatchConfig extends HttpTransportBaseConfig {
-    logGroupName: string;
-    /** Log stream name - string, pattern config, or template config. Defaults to hostname pattern */
-    logStreamName?: LogStreamName;
-    region: string;
-    accessKeyId: string;
-    secretAccessKey: string;
-    createLogGroup?: boolean;
-    createLogStream?: boolean;
-}
-interface LevelConfigObject {
-    default: LogLevel;
-    rules?: LevelRule[];
-}
-type LevelConfig = LogLevel | LevelConfigObject;
-interface CallerConfig {
-    /** Stack depth to capture (default: 1). Higher values trace further up the call stack */
-    depth?: number;
-    /** Include full file path (default: false). If false, shows relative or basename only */
-    fullPath?: boolean;
-}
-interface CallerInfo {
-    file: string;
-    line: number;
-    column?: number;
-    function?: string;
-}
-interface AutoShutdownConfig {
-    /** Timeout in ms before forcing exit (default: 5000) */
-    timeout?: number;
-    /** Custom signals to handle (default: ['SIGTERM', 'SIGINT']) */
-    signals?: NodeJS.Signals[];
-}
-interface LoggerConfig {
-    level: LevelConfig;
-    console: ConsoleConfig;
-    file?: FileConfig;
-    discord?: DiscordConfig | DiscordConfig[];
-    telegram?: TelegramConfig | TelegramConfig[];
-    cloudwatch?: CloudWatchConfig | CloudWatchConfig[];
-    zohoCliq?: ZohoCliqConfig | ZohoCliqConfig[];
-    /** Relay transport config — streams logs to a remote server via WebSocket (runs in worker thread) */
-    relay?: RelayConfig;
-    /** Enable caller info (file:line) in logs. Pass true for defaults or CallerConfig for options */
-    caller?: boolean | CallerConfig;
-    /** Hostname to include in all log entries. Defaults to os.hostname() if not specified */
-    hostname?: string;
-    /** Auto-register graceful shutdown handlers. Pass true for defaults or config object */
-    autoShutdown?: boolean | AutoShutdownConfig;
-}
-type LoggerContext = Record<string, unknown>;
-type LevelOverrideMatch<TContext extends LoggerContext> = Partial<TContext> & {
-    context?: string;
-};
-interface LevelOverride<TContext extends LoggerContext> {
-    match: LevelOverrideMatch<TContext>;
-    level: LogLevel;
-    readonly?: boolean;
-}
-type Meta = object | (() => object);
-
 declare class LoggerStore<TContext extends LoggerContext = LoggerContext> {
     private storage;
     getStore(): TContext | undefined;
@@ -387,10 +150,19 @@ interface BaseHttpTransportOptions {
      * back into the host application.
      */
     onError?: (error: Error, droppedMessages: BufferedMessage[]) => void;
+    /**
+     * If provided, applied to `meta` once per message in `transformMessage`. Used
+     * by transports that build payloads via `Object.entries(meta)` iteration
+     * (Discord/Telegram/Zoho), where a JSON.stringify replacer can't reach the
+     * top-level key. CloudWatch passes `undefined` here and uses a replacer in
+     * its own `sendBatch` instead.
+     */
+    masker?: (value: unknown) => unknown;
 }
 declare abstract class BaseHttpTransport {
     protected buffer: MessageBuffer;
     private onErrorCallback?;
+    private masker?;
     constructor(opts?: BaseHttpTransportOptions);
     log(info: Record<string, unknown>, callback: () => void): void;
     /**
@@ -416,7 +188,7 @@ declare function matchesContext(storeContext: LoggerContext | undefined, loggerC
 declare class DiscordTransport extends BaseHttpTransport {
     private config;
     private requestTimeout;
-    constructor(config: DiscordConfig);
+    constructor(config: DiscordConfig, masker?: (value: unknown) => unknown);
     protected sendBatch(messages: BufferedMessage[]): Promise<void>;
     private sendEmbedBatch;
     private sendMarkdownBatch;
@@ -432,7 +204,7 @@ declare class TelegramTransport extends BaseHttpTransport {
     private config;
     private apiUrl;
     private requestTimeout;
-    constructor(config: TelegramConfig);
+    constructor(config: TelegramConfig, masker?: (value: unknown) => unknown);
     protected sendBatch(messages: BufferedMessage[]): Promise<void>;
     private formatBatchMessage;
     private formatMarkdown;
@@ -450,7 +222,8 @@ declare class CloudWatchTransport extends BaseHttpTransport {
     private initialized;
     private initPromise;
     private resolvedLogStreamName;
-    constructor(config: CloudWatchConfig, configHostname?: string);
+    private maskReplacer;
+    constructor(config: CloudWatchConfig, configHostname?: string, maskReplacerFn?: MaskReplacer);
     protected sendBatch(messages: BufferedMessage[]): Promise<void>;
     private ensureInitialized;
     private initialize;
@@ -465,7 +238,7 @@ declare class ZohoCliqTransport extends BaseHttpTransport {
     private config;
     private endpoint;
     private requestTimeout;
-    constructor(config: ZohoCliqConfig);
+    constructor(config: ZohoCliqConfig, masker?: (value: unknown) => unknown);
     private buildEndpoint;
     protected sendBatch(messages: BufferedMessage[]): Promise<void>;
     private formatMessage;
@@ -495,14 +268,6 @@ declare function generateRequestId(options?: RequestIdOptions): string;
 declare function extractRequestId(headers: Record<string, string | string[] | undefined>): string | undefined;
 declare function getOrGenerateRequestId(headers: Record<string, string | string[] | undefined>, options?: RequestIdOptions): string;
 
-interface MaskSecretsOptions {
-    patterns?: string[];
-    mask?: string;
-    deep?: boolean;
-}
-declare function maskSecrets(obj: unknown, options?: MaskSecretsOptions): unknown;
-declare function createMasker(options?: MaskSecretsOptions): (obj: unknown) => unknown;
-
 declare function getCallerInfo(config: CallerConfig, additionalOffset?: number): CallerInfo | undefined;
 declare function formatCallerInfo(info: CallerInfo): string;
 
@@ -701,6 +466,11 @@ declare const LoggerConfigSchema: z.ZodObject<{
     caller: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodType<CallerConfig, unknown, z.core.$ZodTypeInternals<CallerConfig, unknown>>]>>;
     hostname: z.ZodOptional<z.ZodString>;
     autoShutdown: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodType<AutoShutdownConfig, unknown, z.core.$ZodTypeInternals<AutoShutdownConfig, unknown>>]>>;
+    maskSecrets: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        patterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        mask: z.ZodOptional<z.ZodString>;
+        deep: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>]>>;
 }, z.core.$strip>;
 declare function validateConfig(config: unknown): z.infer<typeof LoggerConfigSchema>;
 declare function safeValidateConfig(config: unknown): z.ZodSafeParseResult<{
@@ -765,6 +535,11 @@ declare function safeValidateConfig(config: unknown): z.ZodSafeParseResult<{
     caller?: boolean | CallerConfig | undefined;
     hostname?: string | undefined;
     autoShutdown?: boolean | AutoShutdownConfig | undefined;
+    maskSecrets?: boolean | {
+        patterns?: string[] | undefined;
+        mask?: string | undefined;
+        deep?: boolean | undefined;
+    } | undefined;
 }>;
 
-export { type AutoShutdownConfig, AutoShutdownConfigSchema, BaseHttpTransport, type BaseHttpTransportOptions, type BufferOptions, type BufferedMessage, type CallerConfig, CallerConfigSchema, type CallerInfo, type CloudWatchConfig, CloudWatchConfigSchema, CloudWatchTransport, type ConsoleConfig, ConsoleConfigSchema, type DiscordConfig, DiscordConfigSchema, DiscordTransport, type FileConfig, FileConfigSchema, type GracefulShutdownOptions, type HttpErrorData, type HttpTransportBaseConfig, HttpTransportBaseConfigSchema, LOG_LEVELS, type LevelConfig, type LevelConfigObject, LevelConfigObjectSchema, LevelConfigSchema, type LevelOverride, type LevelOverrideMatch, type LevelRule, LevelRuleSchema, type LogFormat, LogFormatSchema, type LogLevel, LogLevelSchema, type LogStreamName, LogStreamNameSchema, type LogStreamPattern, type LogStreamPatternConfig, LogStreamPatternConfigSchema, LogStreamPatternSchema, type LogStreamTemplateConfig, LogStreamTemplateConfigSchema, Logger, type LoggerConfig, LoggerConfigSchema, type LoggerContext, LoggerStore, type MaskSecretsOptions, MessageBuffer, type Meta, type RelayConfig, RelayConfigSchema, type RequestIdOptions, type SerializedError, type SingletonLogger, type TelegramConfig, TelegramConfigSchema, TelegramTransport, type TimingResult, type ZohoCliqBotConfig, type ZohoCliqConfig, ZohoCliqConfigSchema, ZohoCliqTransport, assertLogLevel, createMasker, createSingletonLogger, extractRequestId, flattenObject, formatCallerInfo, formatLogfmt, formatLogfmtValue, generateRequestId, getCallerInfo, getOrGenerateRequestId, isValidLogLevel, maskSecrets, matchesContext, measureAsync, measureSync, registerShutdown, safeValidateConfig, serializeError, validateConfig };
+export { AutoShutdownConfig, AutoShutdownConfigSchema, BaseHttpTransport, type BaseHttpTransportOptions, type BufferOptions, type BufferedMessage, CallerConfig, CallerConfigSchema, CallerInfo, CloudWatchConfig, CloudWatchConfigSchema, CloudWatchTransport, ConsoleConfig, ConsoleConfigSchema, DiscordConfig, DiscordConfigSchema, DiscordTransport, FileConfig, FileConfigSchema, type GracefulShutdownOptions, type HttpErrorData, HttpTransportBaseConfig, HttpTransportBaseConfigSchema, LevelConfig, LevelConfigObject, LevelConfigObjectSchema, LevelConfigSchema, LevelOverride, LevelOverrideMatch, LevelRule, LevelRuleSchema, LogFormat, LogFormatSchema, LogLevel, LogLevelSchema, LogStreamName, LogStreamNameSchema, LogStreamPattern, LogStreamPatternConfig, LogStreamPatternConfigSchema, LogStreamPatternSchema, LogStreamTemplateConfig, LogStreamTemplateConfigSchema, Logger, LoggerConfig, LoggerConfigSchema, LoggerContext, LoggerStore, MaskReplacer, MessageBuffer, Meta, RelayConfig, RelayConfigSchema, type RequestIdOptions, type SerializedError, type SingletonLogger, TelegramConfig, TelegramConfigSchema, TelegramTransport, type TimingResult, ZohoCliqConfig, ZohoCliqConfigSchema, ZohoCliqTransport, createSingletonLogger, extractRequestId, flattenObject, formatCallerInfo, formatLogfmt, formatLogfmtValue, generateRequestId, getCallerInfo, getOrGenerateRequestId, matchesContext, measureAsync, measureSync, registerShutdown, safeValidateConfig, serializeError, validateConfig };