@yixinshuke/node-log 0.0.0-stage → 0.0.1

package/src/writer.ts

@@ -0,0 +1,239 @@
+/**
+ * 文件写入器（阶段二）：节流后的批量追加写 —— AGENTS.md §2.3。
+ *
+ * 强制约束：
+ * - **只追加**：一律 `open(path,'a')`，绝不 truncate / `'w'` / 删除；
+ * - **写完即关**：fd 不常驻；
+ * - **按路径串行**：同一文件同一时刻只有一个写入者（进程内）；
+ * - **跨进程互斥**：可选分布式锁，busy 时不写、返回 'busy'（调用方保留缓冲下轮写）；
+ * - **写超时**：目标目录若是网络挂载，异常可能表现为长时间 hang，必须超时放弃；
+ * - **部分写补全**：单次 write 可能只写一部分，必须循环写完，否则日志被静默截断；
+ * - **绝不抛错**：所有异常转成状态码 + 告警。
+ */
+import { open, mkdir, stat } from 'fs/promises';
+import { dirname, join } from 'path';
+import type { FileHandle } from 'fs/promises';
+import type { WriteLocker } from './lock.js';
+
+export interface FileWriterOptions {
+  baseDir: string;
+  /** 单次 open/write 超时（毫秒） */
+  writeTimeoutMs?: number;
+  /** 文件权限位 */
+  fileMode?: number;
+  /** 单文件尺寸上限（字节），默认 1MB；达到即滚动到 `<stem>.N.log`；≤0 关闭分割 */
+  maxFileSizeBytes?: number;
+  onWarn?: (msg: string) => void;
+}
+
+/** ok = 已写入；busy = 锁繁忙（未写入，保留缓冲）；error = 写入失败（保留缓冲） */
+export type WriteStatus = 'ok' | 'busy' | 'error';
+
+async function withTimeout<T>(p: Promise<T>, ms: number, label: string): Promise<T> {
+  if (!ms || ms <= 0) return p;
+  let timer: NodeJS.Timeout | undefined;
+  try {
+    return await Promise.race([
+      p,
+      new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error(`${label}超时（${ms}ms）`)), ms);
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/** 循环补全：网络文件系统单次 write 可能只写一部分 */
+async function writeAll(fh: FileHandle, chunk: string, timeoutMs: number): Promise<void> {
+  const buf = Buffer.from(chunk, 'utf8');
+  let off = 0;
+  while (off < buf.length) {
+    const { bytesWritten } = await withTimeout(fh.write(buf, off), timeoutMs, 'write');
+    if (!bytesWritten || bytesWritten <= 0) throw new Error('write 返回 0 字节，放弃本批');
+    off += bytesWritten;
+  }
+}
+
+export class FileWriter {
+  private baseDir: string;
+  private writeTimeoutMs: number;
+  private readonly fileMode: number;
+  private readonly onWarn?: (msg: string) => void;
+  /** 单文件尺寸上限（字节）；≤0 关闭分割 */
+  private maxFileSizeBytes: number;
+
+  /** 按相对路径的串行链（同一文件绝不并发写） */
+  private readonly chains = new Map<string, Promise<unknown>>();
+  /** 已成功创建的目录（挂载层 mkdir/stat 很慢，必须缓存） */
+  private readonly dirs = new Set<string>();
+
+  private locker: WriteLocker | null = null;
+  private lockerTtlMs: number;
+
+  /** 滚动文件序号上限（防止极端情况下无限循环） */
+  private static readonly MAX_ROTATE = 999;
+
+  constructor(options: FileWriterOptions) {
+    this.baseDir = options.baseDir;
+    this.writeTimeoutMs = options.writeTimeoutMs ?? 5000;
+    this.fileMode = options.fileMode ?? 0o600;
+    this.onWarn = options.onWarn;
+    this.maxFileSizeBytes = options.maxFileSizeBytes ?? 1024 * 1024;
+    this.lockerTtlMs = 10000;
+  }
+
+  setBaseDir(baseDir: string): void {
+    if (baseDir === this.baseDir) return;
+    this.baseDir = baseDir;
+    this.dirs.clear();
+  }
+
+  setWriteTimeoutMs(ms: number): void {
+    if (ms > 0) this.writeTimeoutMs = ms;
+  }
+
+  /** 设置单文件尺寸上限（字节）；≤0 关闭分割 */
+  setMaxFileSizeBytes(bytes: number): void {
+    if (bytes > 0) this.maxFileSizeBytes = bytes;
+  }
+
+  /** 挂载/卸载分布式锁（Redis 就绪后由 logger 注入） */
+  setLocker(locker: WriteLocker | null, ttlMs: number): void {
+    this.locker = locker ?? null;
+    if (ttlMs > 0) this.lockerTtlMs = ttlMs;
+  }
+
+  /** 追加写入；同一路径串行执行 */
+  async write(rel: string, chunk: string): Promise<WriteStatus> {
+    const prev = this.chains.get(rel) ?? Promise.resolve();
+    const cur = prev.then(
+      () => this.doWrite(rel, chunk),
+      () => this.doWrite(rel, chunk)
+    );
+    // 链上只保留「永不 reject」的版本，避免前一个任务失败污染后续任务
+    this.chains.set(
+      rel,
+      cur.catch(() => undefined)
+    );
+    return cur;
+  }
+
+  /** 等待所有在途写完成（shutdown / flush 用） */
+  async drain(): Promise<void> {
+    const pending = Array.from(this.chains.values());
+    for (const p of pending) {
+      await p.catch(() => undefined);
+    }
+  }
+
+  private async doWrite(rel: string, chunk: string): Promise<WriteStatus> {
+    const abs = join(this.baseDir, rel);
+    try {
+      await this.ensureDir(dirname(abs));
+    } catch (err: any) {
+      this.warn(`创建目录失败：${err?.message ?? err}`);
+      return 'error';
+    }
+
+    const write = async (): Promise<void> => {
+      // 按尺寸滚动：在互斥锁内（或单进程）解析实际落盘的相对路径，
+      // 避免跨进程/跨批对同一 bizKey 落到不同文件造成内容撕裂。
+      const targetRel = await this.resolveRotatedRel(rel, Buffer.byteLength(chunk, 'utf8'));
+      const targetAbs = join(this.baseDir, targetRel);
+      const fh = await withTimeout(open(targetAbs, 'a', this.fileMode), this.writeTimeoutMs, 'open');
+      try {
+        await writeAll(fh, chunk, this.writeTimeoutMs);
+      } finally {
+        await fh.close().catch(() => undefined);
+      }
+    };
+
+    if (!this.locker) {
+      try {
+        await write();
+        return 'ok';
+      } catch (err: any) {
+        this.warn(`写入失败：${err?.message ?? err}`);
+        return 'error';
+      }
+    }
+
+    // 标记 fn 是否已执行：node-lock 会把 fn 的异常向上抛，此时不能「直写重试」造成重复写入
+    let executed = false;
+    const guarded = async (): Promise<void> => {
+      executed = true;
+      await write();
+    };
+
+    let ran = false;
+    try {
+      ran = await this.locker(rel, guarded, this.lockerTtlMs);
+    } catch (err: any) {
+      if (executed) {
+        this.warn(`写入失败：${err?.message ?? err}`);
+        return 'error';
+      }
+      // 锁组件不可用 → 直写（日志不能因为锁挂了就不写）
+      try {
+        await write();
+        return 'ok';
+      } catch (err2: any) {
+        this.warn(`写入失败：${err2?.message ?? err2}`);
+        return 'error';
+      }
+    }
+
+    if (!ran) return 'busy'; // 锁繁忙：保留缓冲，下轮再写
+    return 'ok';
+  }
+
+  private async ensureDir(dir: string): Promise<void> {
+    if (this.dirs.has(dir)) return;
+    try {
+      await mkdir(dir, { recursive: true });
+      this.dirs.add(dir);
+    } catch (err: any) {
+      if (err?.code === 'EEXIST') {
+        this.dirs.add(dir); // 多进程并发创建同一目录 → 视为成功
+        return;
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * 解析实际落盘的相对路径：当前文件达到 `maxFileSizeBytes` 时滚动到 `<stem>.N.log`。
+   *
+   * - 仅追加、不 rename：已写满的 `xxx.log` 冻结为归档，新内容追加到首个未超限的 `xxx.N.log`；
+   * - 自 base 起依次 stat，命中「不存在」或「现有大小 + 本批字节 ≤ 上限」即采用；
+   * - stat 非 ENOENT 异常（如权限）保守回退原 `rel`，绝不丢日志；
+   * - `maxFileSizeBytes ≤ 0` 直接返回原 `rel`（关闭分割）。
+   */
+  private async resolveRotatedRel(rel: string, chunkLen: number): Promise<string> {
+    const max = this.maxFileSizeBytes;
+    if (!max || max <= 0) return rel;
+    const stem = rel.endsWith('.log') ? rel.slice(0, -4) : rel;
+    for (let i = 0; i <= FileWriter.MAX_ROTATE; i++) {
+      const cand = i === 0 ? rel : `${stem}.${i}.log`;
+      let size: number;
+      try {
+        const st = await stat(join(this.baseDir, cand));
+        size = st.size;
+      } catch (err: any) {
+        if (err?.code === 'ENOENT') return cand; // 该序号文件尚不存在 → 用它
+        return rel; // 其他异常保守回退，避免丢日志
+      }
+      if (size + chunkLen <= max) return cand;
+    }
+    return `${stem}.${FileWriter.MAX_ROTATE}.log`;
+  }
+
+  private warn(msg: string): void {
+    try {
+      this.onWarn?.(msg);
+    } catch {
+      /* 告警本身绝不能抛错 */
+    }
+  }
+}