@yixinshuke/node-log 0.0.0-stage → 0.0.1

package/src/buffer.ts

@@ -0,0 +1,108 @@
+/**
+ * 环形内存缓冲（阶段一：写日志先进这里，同步入队后**立即返回**）。
+ *
+ * 设计要点：
+ * - **按文件（等价于按 bizKey）分队列**：某个文件写失败时只回填该队列，不影响其他文件；
+ * - **全局容量固定**：写满时覆盖**最老的一条**（按各队列队首的时间比较），
+ *   绝不无限增长（OOM），也绝不抛错阻断业务（AGENTS.md §0.2 / §2.1）；
+ * - `drainByKey(limit)` 是「取出并移除」；写失败用 `pushBack()` 回填到**队首**，保持原有顺序。
+ */
+import type { LogContext } from './logger.js';
+import type { LogLevel } from './config.js';
+
+export interface LogEntry {
+  level: LogLevel;
+  context: LogContext;
+  message: string;
+  timestamp: Date;
+  metadata?: Record<string, any>;
+}
+
+export class RingBuffer {
+  /** key = 相对文件路径；Map 保持插入顺序，天然轮转、不会饿死后来的 key */
+  private readonly queues = new Map<string, LogEntry[]>();
+  private readonly capacity: number;
+  private total = 0;
+  private dropped = 0;
+
+  constructor(capacity: number = 10000) {
+    this.capacity = Math.max(1, Math.floor(capacity));
+  }
+
+  get size(): number {
+    return this.total;
+  }
+
+  /** 因缓冲满而被覆盖丢弃的条数（监控用） */
+  get droppedCount(): number {
+    return this.dropped;
+  }
+
+  push(key: string, entry: LogEntry): void {
+    const queue = this.queues.get(key);
+    if (queue) queue.push(entry);
+    else this.queues.set(key, [entry]);
+    this.total += 1;
+    this.evictIfOverflow();
+  }
+
+  /** 取出并移除最多 limit 条，按 key 聚合（保持每个 key 内部的 FIFO 顺序） */
+  drainByKey(limit: number): Map<string, LogEntry[]> {
+    const drained = new Map<string, LogEntry[]>();
+    if (limit <= 0) return drained;
+
+    let remaining = limit;
+    for (const [key, queue] of this.queues) {
+      if (remaining <= 0) break;
+      const take = queue.splice(0, remaining);
+      if (take.length === 0) continue;
+      drained.set(key, take);
+      this.total -= take.length;
+      remaining -= take.length;
+      if (queue.length === 0) this.queues.delete(key);
+    }
+    return drained;
+  }
+
+  /** 写失败回填：放回该 key 的**队首**并保持原有顺序（下轮优先重试） */
+  pushBack(key: string, entries: LogEntry[]): void {
+    if (!entries || entries.length === 0) return;
+    const queue = this.queues.get(key);
+    if (queue) queue.unshift(...entries);
+    else this.queues.set(key, [...entries]);
+    this.total += entries.length;
+    this.evictIfOverflow();
+  }
+
+  clear(): void {
+    this.queues.clear();
+    this.total = 0;
+  }
+
+  /** 缓冲满 → 覆盖最老的一条（比较各队列队首的时间戳） */
+  private evictIfOverflow(): void {
+    while (this.total > this.capacity) {
+      let oldestKey: string | null = null;
+      let oldestTime = Infinity;
+      for (const [key, queue] of this.queues) {
+        const head = queue[0];
+        if (!head) continue;
+        const t = head.timestamp?.getTime?.() ?? 0;
+        if (t < oldestTime) {
+          oldestTime = t;
+          oldestKey = key;
+        }
+      }
+      if (!oldestKey) {
+        // 理论上不可达（total>0 必有非空队列）；兜底防死循环
+        this.total = 0;
+        return;
+      }
+      const queue = this.queues.get(oldestKey)!;
+      queue.shift();
+      this.total -= 1;
+      this.dropped += 1;
+      if (queue.length === 0) this.queues.delete(oldestKey);
+    }
+  }
+}

package/src/config.ts

@@ -0,0 +1,112 @@
+/**
+ * 日志配置 —— AGENTS.md §6。
+ *
+ * 说明：`baseDir` 就是普通本地目录，底层是本地磁盘、OSS 挂载还是 NAS 挂载，
+ * 组件不感知也不做特殊处理（挂载方式属于部署事项）。
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+/** 复用锁库的类型契约（避免 config 反向依赖 lock 模块造成循环） */
+export interface LockLike {
+  runDedupe<T>(key: string, fn: () => Promise<T>, options?: { ttlMs?: number }): Promise<boolean>;
+}
+
+/** 文件粒度：shared = 多机多进程写同一文件；host = 每台机器各写各的 */
+export type FileScope = 'shared' | 'host';
+
+export interface LoggerConfig {
+  /** 日志根目录，默认 ./logs */
+  baseDir: string;
+  /** 最低记录级别，默认 info */
+  minLevel?: LogLevel;
+  /** 环形缓冲容量（条），满则覆盖最老，默认 10000 */
+  maxBufferSize?: number;
+  /** 节流刷盘间隔（毫秒），默认 3000 */
+  flushIntervalMs?: number;
+  /** 定时器随机抖动（毫秒），默认 500；避免多进程同相位抢锁 */
+  flushJitterMs?: number;
+  /** 单批最大条数，默认 100 */
+  flushBatchSize?: number;
+  /** 单批字节上限，达到即提前刷盘，默认 64KB */
+  maxFlushBytes?: number;
+  /** ≥ 该级别的日志立即触发刷盘，默认 error */
+  immediateLevel?: LogLevel;
+  /** 单次 open/write 超时（毫秒），默认 5000；挂载异常可能表现为 hang */
+  writeTimeoutMs?: number;
+  /**
+   * 分布式写入锁：**由使用方注入 `@yixinshuke/node-lock` 的 `RedisLock` 实例**。
+   * 组件不自建 Redis 连接、不感知 Redis 配置；不传 = 无锁直写（单进程或不介意时使用）。
+   */
+  lock?: LockLike | null;
+  /** 写入锁 TTL（毫秒），默认 10000；必须大于 writeTimeoutMs */
+  lockTtlMs?: number;
+  /** 文件粒度，默认 shared */
+  fileScope?: FileScope;
+  /** 写失败退避基数（毫秒），默认 3000 */
+  retryBackoffMs?: number;
+  /** 主机名字段值；缺省取 NODE_LOG_HOST / POD_NAME / os.hostname() */
+  host?: string;
+  /**
+   * 单文件尺寸上限（字节）；达到即滚动到新文件（`<stem>.1.log` / `<stem>.2.log` …），
+   * 默认 1MB（1048576）。超出后旧文件只读保留，由外部滚动删除清理（见 AGENTS.md §8）。
+   * 设为 ≤0 关闭分割（单 bizKey 单文件，旧行为）。
+   * 注意：滚动基于追加前 stat 当前文件大小 + 本批字节，不依赖 rename（避免网络挂载下 rename 风险）。
+   */
+  maxFileSizeBytes?: number;
+}
+
+export const DEFAULT_CONFIG: Required<LoggerConfig> = {
+  baseDir: './logs',
+  minLevel: 'info',
+  maxBufferSize: 10000,
+  flushIntervalMs: 3000,
+  flushJitterMs: 500,
+  flushBatchSize: 100,
+  maxFlushBytes: 65536,
+  immediateLevel: 'error',
+  writeTimeoutMs: 5000,
+  lock: null,
+  lockTtlMs: 10000,
+  fileScope: 'shared',
+  retryBackoffMs: 3000,
+  host: '',
+  maxFileSizeBytes: 1048576,
+};
+
+/** 缓冲容量下限（配置 ≤0 时兜底） */
+const MIN_BUFFER_SIZE = 1000;
+
+export function resolveMaxBufferSize(config: Required<LoggerConfig>): number {
+  const configured = Number(config.maxBufferSize);
+  return Number.isFinite(configured) && configured > 0
+    ? Math.floor(configured)
+    : MIN_BUFFER_SIZE;
+}
+
+export function mergeConfig(overrides: LoggerConfig): Required<LoggerConfig> {
+  return {
+    ...DEFAULT_CONFIG,
+    ...overrides,
+    lock: overrides.lock ?? null,
+  };
+}
+
+/**
+ * 配置校验：**仅 init()/updateConfig() 允许抛错**（启动期暴露配置问题优于运行期静默降级）。
+ * 运行期一切写路径都不抛错（AGENTS.md §0.2）。
+ */
+export function validateConfig(config: Required<LoggerConfig>): void {
+  if (!config.baseDir || !String(config.baseDir).trim()) {
+    throw new Error('[node-log] baseDir 不能为空');
+  }
+  if (config.flushIntervalMs < 50) {
+    throw new Error(`[node-log] flushIntervalMs 不能小于 50（当前 ${config.flushIntervalMs}）`);
+  }
+  if (config.lock && config.lockTtlMs <= config.writeTimeoutMs) {
+    throw new Error(
+      `[node-log] lockTtlMs(${config.lockTtlMs}) 必须大于 writeTimeoutMs(${config.writeTimeoutMs})，` +
+        `否则锁会先于写入超时失效，可能造成并发追加写`
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export { GlobalLogger } from './logger.js';
+export type { LogContext, WriteOptions, LoggerStats } from './logger.js';
+
+export type { LogLevel, LoggerConfig, LockLike, FileScope } from './config.js';
+export { DEFAULT_CONFIG, mergeConfig, validateConfig } from './config.js';
+
+// 内部模块（进阶用法 / 测试）
+export { RingBuffer } from './buffer.js';
+export type { LogEntry } from './buffer.js';
+export { FileWriter } from './writer.js';
+export type { FileWriterOptions, WriteStatus } from './writer.js';
+export { beijingTimestamp, beijingDateKey, beijingDateParts } from './time.js';
+export { buildRelPath, resolveBizDate, sanitizeBizKey, sanitizeCategory, sanitizeId, sanitizeSystem } from './path.js';
+export type { PathInput } from './path.js';
+export { createLocker, writeLockKey, LOCK_KEY_PREFIX } from './lock.js';
+export type { WriteLocker } from './lock.js';

package/src/lock.ts

@@ -0,0 +1,69 @@
+/**
+ * 写入互斥（AGENTS.md §5）。
+ *
+ * **组件不自建 Redis 连接**：初始化时由使用方直接把 `@yixinshuke/node-lock` 的
+ * `RedisLock` 实例传进来，组件只负责用它抢锁 —— Redis 怎么连、用什么库，是宿主项目的事。
+ *
+ * 语义（与「日志绝不阻塞业务」一致）：
+ * - 抢到锁 → 执行写入，返回 true；
+ * - 抢不到（busy，`runDedupe` 返回 false）→ 返回 false，**调用方保留缓冲下轮再写**，绝不排队等待；
+ * - 锁不可用（Redis 挂等异常）→ **降级为无锁直写**并告警一次
+ *   （不写 = 真丢日志，比并发 append 更糟）；
+ * - 未注入锁实例 → 无锁直写（不告警，属于预期用法）。
+ */
+
+/** 最小依赖契约：与 `@yixinshuke/node-lock` 的 `RedisLock` 一致 */
+export interface LockLike {
+  runDedupe<T>(key: string, fn: () => Promise<T>, options?: { ttlMs?: number }): Promise<boolean>;
+}
+
+/**
+ * 写入互斥钩子。
+ * @returns true = 已持锁执行；false = 锁繁忙，未执行（调用方应保留缓冲）
+ */
+export type WriteLocker = (rel: string, fn: () => Promise<void>, ttlMs: number) => Promise<boolean>;
+
+/** 锁键前缀：node-log:write:<相对路径> */
+export const LOCK_KEY_PREFIX = 'node-log:';
+
+export function writeLockKey(rel: string, prefix: string = LOCK_KEY_PREFIX): string {
+  return `${prefix}write:${rel}`;
+}
+
+/** 是否「锁繁忙」（区别于锁组件不可用） */
+function isBusy(err: any): boolean {
+  return err?.kind === 'busy' || /busy/i.test(String(err?.message ?? ''));
+}
+
+/**
+ * 把注入的锁实例包装成写入互斥钩子。
+ *
+ * @param lock 使用方传入的 node-lock 实例；不传 → 返回 null（无锁直写）
+ * @returns WriteLocker；可为 null，调用方据此判定「无互斥」
+ */
+export function createLocker(
+  lock: LockLike | null | undefined,
+  defaultTtlMs: number,
+  onWarn?: (msg: string) => void
+): WriteLocker | null {
+  if (!lock || typeof lock.runDedupe !== 'function') return null;
+
+  return async (rel, fn, ttlMs) => {
+    try {
+      // runDedupe：抢不到锁立即返回 false，不排队（绝不阻塞业务）
+      return await lock.runDedupe(writeLockKey(rel), () => fn(), { ttlMs: ttlMs || defaultTtlMs });
+    } catch (err: any) {
+      if (isBusy(err)) return false; // 理论上不会走到（runDedupe 已吞 busy），兜底
+      // 锁组件不可用 ≠ 不写日志：降级为无锁直写并告警一次
+      try {
+        onWarn?.(
+          `[node-log] 锁不可用，已降级为无锁直写（不阻断业务）：${err?.message ?? err}`
+        );
+      } catch {
+        /* 告警本身绝不抛错 */
+      }
+      await fn();
+      return true;
+    }
+  };
+}