jskelet 0.6.1 → 0.6.3

package/src/server/logs/access-middleware.js

@@ -1,66 +1,66 @@
-/**
- * HTTP access log middleware.
- *
- * Admin ve prewarm yolları atlanır. Kayıt `log.http` ile stdout'a (console
- * açıksa) ve `acceptLogEntry` ile sink'lere gider. `emitHttp` kapalı olduğu
- * için `log.http` abonelere ikinci kez yazmaz.
- */
-import * as log from "../../log.mjs";
-import { getConfig } from "../../config/index.js";
-import { acceptLogEntry } from "./pipeline.js";
-
-/**
- * @param {{ basePath?: string }} [options]
- * @returns {import('express').RequestHandler}
- */
-export function accessLogMiddleware(options = {}) {
-  const config = getConfig();
-  const brand = config.brand;
-  const basePath =
-    options.basePath ??
-    (config.admin.enabled ? config.admin.basePath : null);
-
-  /** @type {import('express').RequestHandler} */
-  return (req, res, next) => {
-    const pathname = req.path || "";
-    if (basePath && (pathname === basePath || pathname.startsWith(`${basePath}/`))) {
-      return next();
-    }
-
-    if (req.headers["user-agent"] === brand.prewarmUserAgent) {
-      return next();
-    }
-
-    const started = process.hrtime.bigint();
-
-    res.on("finish", () => {
-      const ms = Number(process.hrtime.bigint() - started) / 1e6;
-      const cache = /** @type {string | null} */ (
-        res.getHeader(brand.cacheHeader) ?? null
-      );
-
-      const info = {
-        method: req.method,
-        url: req.originalUrl,
-        status: res.statusCode,
-        ms,
-        cache,
-      };
-
-      // Stdout (console açıksa). emitHttp kapalı → subscribe çiftlemez.
-      log.http(info);
-
-      acceptLogEntry({
-        kind: "http",
-        method: info.method,
-        url: info.url,
-        path: req.path,
-        status: info.status,
-        ms: info.ms,
-        cache: info.cache,
-      });
-    });
-
-    next();
-  };
-}
+/**
+ * HTTP access log middleware.
+ *
+ * Admin ve prewarm yolları atlanır. Kayıt `log.http` ile stdout'a (console
+ * açıksa) ve `acceptLogEntry` ile sink'lere gider. `emitHttp` kapalı olduğu
+ * için `log.http` abonelere ikinci kez yazmaz.
+ */
+import * as log from "../../log.mjs";
+import { getConfig } from "../../config/index.js";
+import { acceptLogEntry } from "./pipeline.js";
+
+/**
+ * @param {{ basePath?: string }} [options]
+ * @returns {import('express').RequestHandler}
+ */
+export function accessLogMiddleware(options = {}) {
+  const config = getConfig();
+  const brand = config.brand;
+  const basePath =
+    options.basePath ??
+    (config.admin.enabled ? config.admin.basePath : null);
+
+  /** @type {import('express').RequestHandler} */
+  return (req, res, next) => {
+    const pathname = req.path || "";
+    if (basePath && (pathname === basePath || pathname.startsWith(`${basePath}/`))) {
+      return next();
+    }
+
+    if (req.headers["user-agent"] === brand.prewarmUserAgent) {
+      return next();
+    }
+
+    const started = process.hrtime.bigint();
+
+    res.on("finish", () => {
+      const ms = Number(process.hrtime.bigint() - started) / 1e6;
+      const cache = /** @type {string | null} */ (
+        res.getHeader(brand.cacheHeader) ?? null
+      );
+
+      const info = {
+        method: req.method,
+        url: req.originalUrl,
+        status: res.statusCode,
+        ms,
+        cache,
+      };
+
+      // Stdout (console açıksa). emitHttp kapalı → subscribe çiftlemez.
+      log.http(info);
+
+      acceptLogEntry({
+        kind: "http",
+        method: info.method,
+        url: info.url,
+        path: req.path,
+        status: info.status,
+        ms: info.ms,
+        cache: info.cache,
+      });
+    });
+
+    next();
+  };
+}

package/src/server/logs/file-sink.js

@@ -1,66 +1,193 @@
-/**
- * Günlük rotasyonlu NDJSON dosya sink'i.
- *
- * Yol `path.resolve(root, dir)` ile bulunur — `getConfig().dirs` şişirilmez;
- * log dizini opsiyonel bir yüzey ve çoğu kurulumda hiç açılmaz.
- */
-import fs from "node:fs/promises";
-import path from "node:path";
-
-/**
- * @typedef {{ write: (entry: Record<string, unknown>) => Promise<void>,
- *   flush: () => Promise<void>, close: () => Promise<void> }} LogSink
- */
-
-/**
- * @param {{ root: string, dir: string }} options
- * @returns {LogSink}
- */
-export function createFileSink(options) {
-  const baseDir = path.resolve(options.root, options.dir);
-  /** @type {string | null} */
-  let currentDay = null;
-  /** @type {string | null} */
-  let currentPath = null;
-  let ready = false;
-
-  /** @returns {string} */
-  function dayStamp(date = new Date()) {
-    const y = date.getUTCFullYear();
-    const m = String(date.getUTCMonth() + 1).padStart(2, "0");
-    const d = String(date.getUTCDate()).padStart(2, "0");
-    return `${y}-${m}-${d}`;
-  }
-
-  /**
-   * @param {string} day
-   * @returns {Promise<string>}
-   */
-  async function ensureFile(day) {
-    if (!ready) {
-      await fs.mkdir(baseDir, { recursive: true });
-      ready = true;
-    }
-    if (currentDay === day && currentPath) return currentPath;
-    currentDay = day;
-    currentPath = path.join(baseDir, `jskelet-${day}.log`);
-    return currentPath;
-  }
-
-  return {
-    async write(entry) {
-      const day = dayStamp(
-        typeof entry.at === "number" ? new Date(entry.at) : new Date(),
-      );
-      const file = await ensureFile(day);
-      await fs.appendFile(file, `${JSON.stringify(entry)}\n`, "utf8");
-    },
-    async flush() {
-      // appendFile senkron flush eder; ekstra iş yok.
-    },
-    async close() {
-      currentDay = null;
-      currentPath = null;
-    },
-  };
-}
+/**
+ * Kısa ömürlü dosya logu.
+ *
+ * Satırlar ~1 sn veya 32 satırda bir zstd NDJSON parçası olur. Diskte en
+ * fazla 5 dakika kalır; süresi dolan en eski parça silinir. `drainLog`
+ * her mühürlenen parçayı alır — hook hata verse de site düşmez, dosya
+ * süresi dolana kadar durur.
+ *
+ * Yol `path.resolve(root, dir)` ile bulunur. `getConfig().dirs` şişirilmez;
+ * log dizini opsiyoneldir ve çoğu kurulumda hiç açılmaz.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import zlib from "node:zlib";
+
+/**
+ * @typedef {{ body: Buffer, encoding: "zstd", bytes: number, lines: number,
+ *   at: number }} LogChunk
+ * @typedef {{ write: (entry: Record<string, unknown>) => Promise<void>,
+ *   flush: () => Promise<void>, close: () => Promise<void> }} LogSink
+ * @typedef {(chunk: LogChunk) => void | Promise<void>} DrainLog
+ */
+
+/** Satır satır yazmak yerine kısa tampon. */
+const FLUSH_INTERVAL_MS = 1000;
+const FLUSH_MAX_LINES = 32;
+
+/** Diskteki parçaların ömrü. Config yükseltemez. */
+export const FILE_LOG_RETENTION_MS = 5 * 60 * 1000;
+
+/**
+ * @param {{ root: string, dir: string, persist?: boolean,
+ *   retentionMs?: number, drainLog?: DrainLog | null }} options
+ *   `persist: false` diske yazmaz; yalnız `drainLog` çağrılır.
+ * @returns {LogSink}
+ */
+export function createFileSink(options) {
+  const persist = options.persist !== false;
+  const retentionMs = options.retentionMs ?? FILE_LOG_RETENTION_MS;
+  const drainLog = typeof options.drainLog === "function" ? options.drainLog : null;
+  const baseDir = path.resolve(options.root, options.dir);
+  /** @type {string[]} */
+  let pending = [];
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let timer = null;
+  /** @type {Promise<void>} */
+  let chain = Promise.resolve();
+  let seq = 0;
+  let ready = false;
+  let drainWarned = false;
+
+  /**
+   * @param {string} message
+   * @param {unknown} [error]
+   */
+  function warnDrain(message, error) {
+    if (drainWarned) return;
+    drainWarned = true;
+    console.warn(`[logs] ${message}`, error ?? "");
+  }
+
+  /**
+   * @returns {Promise<void>}
+   */
+  async function ensureDir() {
+    if (ready) return;
+    await fs.mkdir(baseDir, { recursive: true });
+    ready = true;
+  }
+
+  /**
+   * Süresi dolmuş `jskelet-*` parçalarını eskiden yeniye siler. Başka
+   * dosyalara dokunulmaz. Eski günlük `.log` dosyaları da bu ada uyar.
+   *
+   * @returns {Promise<void>}
+   */
+  async function prune() {
+    if (!persist) return;
+    let names;
+    try {
+      names = await fs.readdir(baseDir);
+    } catch {
+      return;
+    }
+
+    const now = Date.now();
+    /** @type {{ file: string, mtimeMs: number }[]} */
+    const doomed = [];
+
+    for (const name of names) {
+      if (!name.startsWith("jskelet-")) continue;
+      const file = path.join(baseDir, name);
+      try {
+        const stat = await fs.stat(file);
+        if (!stat.isFile()) continue;
+        if (now - stat.mtimeMs < retentionMs) continue;
+        doomed.push({ file, mtimeMs: stat.mtimeMs });
+      } catch {
+        // Silinmiş veya okunamayan girdi turu bozmasın.
+      }
+    }
+
+    doomed.sort((a, b) => a.mtimeMs - b.mtimeMs);
+    for (const item of doomed) {
+      await fs.rm(item.file, { force: true });
+    }
+  }
+
+  /**
+   * @param {string} text
+   * @param {number} lines
+   * @returns {Promise<void>}
+   */
+  async function seal(text, lines) {
+    const body = zlib.zstdCompressSync(Buffer.from(text, "utf8"));
+    const at = Date.now();
+
+    if (persist) {
+      await ensureDir();
+      seq += 1;
+      const file = path.join(baseDir, `jskelet-${at}-${seq}.ndjson.zst`);
+      await fs.writeFile(file, body);
+      await prune();
+    }
+
+    if (!drainLog) return;
+
+    try {
+      await drainLog({
+        body,
+        encoding: "zstd",
+        bytes: body.length,
+        lines,
+        at,
+      });
+    } catch (error) {
+      warnDrain(
+        persist
+          ? "drainLog failed; the chunk stays on disk until it expires"
+          : "drainLog failed; the chunk was not stored",
+        error,
+      );
+    }
+  }
+
+  /**
+   * @returns {Promise<void>}
+   */
+  async function flushPending() {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (!pending.length) return;
+
+    const lines = pending;
+    pending = [];
+    await seal(lines.join(""), lines.length);
+  }
+
+  /** @returns {void} */
+  function schedule() {
+    if (timer || !pending.length) return;
+    timer = setTimeout(() => {
+      timer = null;
+      chain = chain.then(() => flushPending());
+    }, FLUSH_INTERVAL_MS);
+    timer.unref?.();
+  }
+
+  return {
+    async write(entry) {
+      pending.push(`${JSON.stringify(entry)}\n`);
+
+      if (pending.length >= FLUSH_MAX_LINES) {
+        chain = chain.then(() => flushPending());
+        await chain;
+        return;
+      }
+
+      schedule();
+    },
+    async flush() {
+      chain = chain.then(() => flushPending());
+      await chain;
+    },
+    async close() {
+      chain = chain.then(() => flushPending());
+      await chain;
+      if (persist) await prune();
+    },
+  };
+}