@cortexkit/common-auth 0.3.0 → 0.4.0

package/dist/dump/index.js

@@ -1,9 +1,161 @@
-import { createHash } from 'node:crypto';
-import { chmod, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { createHash, randomBytes } from 'node:crypto';
+import { chmod, lstat, mkdir, readdir, readFile, rename, unlink, writeFile, } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
 import { createRedactor } from '../logger/redact.js';
 const PREVIOUS_BODY_LIMIT = 100;
 const UNKNOWN_SESSION = 'session-unknown';
+const DEFAULT_SWEEP_INTERVAL_MS = 5 * 60 * 1000;
+const DEFAULT_SWEEP_MIN_AGE_MS = 60 * 1000;
+const DEFAULT_PARTIAL_STALE_MS = 10 * 60 * 1000;
+/**
+ * The suffixes of the files one dump writes. A dump's files share the name
+ * before the suffix, which is how the sweep groups them.
+ */
+const ARTIFACT_SUFFIX = /\.(body|meta|request|response)\.json$/;
+/**
+ * A dump id: the ISO time with `:` and `.` replaced, the pid, a counter of
+ * at least six digits, then the sanitised session, channel and phase. Only
+ * names of this shape are swept, so a plugin may point dumps at a directory
+ * that also holds other files.
+ */
+const ARTIFACT_ID = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z-\d+-\d{6,}-[a-zA-Z0-9._-]+$/;
+/** A response staging file: the final name, a random nonce, `.partial`. */
+const PARTIAL_SUFFIX = /\.[a-f0-9]{24}\.partial$/;
+function artifactGroup(name) {
+    const stem = name.replace(ARTIFACT_SUFFIX, '');
+    if (stem === name || !ARTIFACT_ID.test(stem))
+        return undefined;
+    return stem;
+}
+function isPartialName(name) {
+    const finalName = name.replace(PARTIAL_SUFFIX, '');
+    return finalName !== name && artifactGroup(finalName) !== undefined;
+}
+/**
+ * Hold the dump artifacts in `dir` to `maxBytes`. Only file names a dumper
+ * writes are counted or removed, so unrelated files in a directory the user
+ * chose survive. A dump's files are evicted together, oldest dump first by
+ * its newest file, because a body without its metadata (or the reverse) is no
+ * use to anyone. Dumps younger than `minAgeMs`, protected paths and symlinks
+ * are kept, and a symlinked directory is refused outright. Response staging
+ * files left by a crash are reclaimed once stale, even under the cap.
+ * Best-effort: a failure removes less, and never throws.
+ */
+export async function sweepDumpDirectory(options) {
+    const { dir, maxBytes } = options;
+    const now = options.now ?? Date.now();
+    const minAgeMs = options.minAgeMs ?? DEFAULT_SWEEP_MIN_AGE_MS;
+    const partialStaleMs = options.partialStaleMs ?? DEFAULT_PARTIAL_STALE_MS;
+    const empty = { removed: 0, freedBytes: 0 };
+    if (!(maxBytes > 0))
+        return empty;
+    try {
+        if ((await lstat(dir)).isSymbolicLink())
+            return empty;
+        const protectedPaths = new Set((options.protectedPaths ?? []).map((path) => resolve(path)));
+        const entries = await readdir(dir, { withFileTypes: true });
+        const files = [];
+        await Promise.all(entries.map(async (entry) => {
+            if (!entry.isFile())
+                return;
+            const partial = isPartialName(entry.name);
+            const group = partial ? undefined : artifactGroup(entry.name);
+            if (!partial && group === undefined)
+                return;
+            const path = join(dir, entry.name);
+            try {
+                const stats = await lstat(path);
+                if (!stats.isFile())
+                    return;
+                files.push({ path, size: stats.size, mtimeMs: stats.mtimeMs, group });
+            }
+            catch {
+                // Another process removed it between the listing and the stat.
+            }
+        }));
+        let total = files.reduce((sum, file) => sum + file.size, 0);
+        let removed = 0;
+        let freedBytes = 0;
+        const remove = async (file) => {
+            try {
+                await unlink(file.path);
+                total -= file.size;
+                freedBytes += file.size;
+                removed += 1;
+            }
+            catch {
+                // Best-effort: what cannot be removed now is tried again next sweep.
+            }
+        };
+        // A staging file is never a usable dump, so a stale one goes whatever
+        // the total; a fresh one may still be renamed into place.
+        for (const file of files) {
+            if (file.group !== undefined)
+                continue;
+            if (protectedPaths.has(resolve(file.path)))
+                continue;
+            if (now - file.mtimeMs < partialStaleMs)
+                continue;
+            await remove(file);
+        }
+        const groups = new Map();
+        for (const file of files) {
+            if (file.group === undefined)
+                continue;
+            const group = groups.get(file.group) ?? { files: [], newest: 0 };
+            group.files.push(file);
+            group.newest = Math.max(group.newest, file.mtimeMs);
+            groups.set(file.group, group);
+        }
+        const oldestFirst = [...groups.entries()].sort(([leftName, left], [rightName, right]) => left.newest - right.newest || leftName.localeCompare(rightName));
+        for (const [, group] of oldestFirst) {
+            if (total <= maxBytes)
+                break;
+            if (now - group.newest < minAgeMs)
+                continue;
+            if (group.files.some((file) => protectedPaths.has(resolve(file.path))))
+                continue;
+            for (const file of group.files)
+                await remove(file);
+        }
+        if (removed > 0) {
+            options.logger?.debug('removed old dump files', { removed, freedBytes });
+        }
+        return { removed, freedBytes };
+    }
+    catch {
+        return empty;
+    }
+}
+/**
+ * Replace `path` through a staging file created exclusively next to it, so a
+ * reader never sees half a file and a symlink planted at a predictable
+ * staging name is never followed.
+ */
+async function replaceFile(path, text) {
+    for (let attempt = 0;; attempt += 1) {
+        const staging = `${path}.${randomBytes(12).toString('hex')}.partial`;
+        let created = false;
+        try {
+            await writeFile(staging, text, {
+                encoding: 'utf8',
+                mode: 0o600,
+                flag: 'wx',
+            });
+            created = true;
+            await rename(staging, path);
+            return;
+        }
+        catch (error) {
+            if (created)
+                await unlink(staging).catch(() => { });
+            const code = error.code;
+            if (code === 'EEXIST' && attempt === 0)
+                continue;
+            throw error;
+        }
+    }
+}
 function shortSession(session) {
     return session.length <= 16 ? session : `${session.slice(0, 12)}…`;
 }
@@ -265,18 +417,28 @@ export function createDumper(options) {
             });
             // `wx`: a name collision fails loudly instead of overwriting a dump.
             const write = (path, text) => writeFile(path, text, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
-            await Promise.all([
-                write(files.body, body.text),
-                write(files.metadata, `${JSON.stringify(metadata, null, 2)}\n`),
-                write(files.request, `${JSON.stringify(request, null, 2)}\n`),
-            ]);
+            const writes = [
+                [files.body, body.text],
+                [files.metadata, `${JSON.stringify(metadata, null, 2)}\n`],
+                [files.request, `${JSON.stringify(request, null, 2)}\n`],
+            ];
+            // Settle every write before judging the group, so a cleanup never
+            // races a write that is still in flight.
+            const settled = await Promise.allSettled(writes.map(([path, text]) => write(path, text)));
+            const failed = settled.find((result) => result.status === 'rejected');
+            if (failed) {
+                if (options.cleanupFailedDumps)
+                    await removeGroup(writes, settled);
+                throw failed.reason;
+            }
             remember(baselineKey, body.text);
             log?.debug('dumped request', {
                 id,
                 session: shortSession(session),
                 body: files.body,
             });
-            return { id, files };
+            scheduleSweep(dir, Object.values(files));
+            return { id, files, responseFile: `${prefix}.response.json` };
         }
         catch (error) {
             log?.warn('request dump failed', {
@@ -286,11 +448,76 @@ export function createDumper(options) {
             return undefined;
         }
     }
+    /**
+     * Remove what a failed dump wrote. A write that failed with EEXIST found
+     * someone else's file at that name and must leave it; any other failure
+     * either created nothing or left a partial file of this dump.
+     */
+    async function removeGroup(writes, settled) {
+        await Promise.all(writes.map(async ([path], index) => {
+            const result = settled[index];
+            if (result?.status === 'rejected' &&
+                result.reason?.code === 'EEXIST') {
+                return;
+            }
+            await unlink(path).catch(() => { });
+        }));
+    }
+    const maxBytes = options.maxBytes ?? 0;
+    const sweepIntervalMs = options.sweepIntervalMs ?? DEFAULT_SWEEP_INTERVAL_MS;
+    // Zero, so the first dump of a process sweeps whatever earlier processes
+    // left behind.
+    let lastSweepAt = 0;
+    function sweepOptions(dir, protectedPaths) {
+        return {
+            dir,
+            maxBytes,
+            protectedPaths,
+            now: now(),
+            minAgeMs: options.sweepMinAgeMs,
+            partialStaleMs: options.partialStaleMs,
+            logger: log,
+        };
+    }
+    /** Sweep in the background, off the request path, at most once per interval. */
+    function scheduleSweep(dir, protectedPaths) {
+        if (!(maxBytes > 0))
+            return;
+        const at = now();
+        if (at - lastSweepAt < sweepIntervalMs)
+            return;
+        lastSweepAt = at;
+        void sweepDumpDirectory(sweepOptions(dir, protectedPaths));
+    }
+    async function dumpResponse(result, input) {
+        if (!result)
+            return undefined;
+        const artifact = scrub({
+            status: input.status,
+            requestId: input.requestId,
+            usage: input.usage,
+            ...input.fields,
+            complete: input.complete ?? true,
+        });
+        try {
+            await replaceFile(result.responseFile, `${JSON.stringify(artifact, null, 2)}\n`);
+            return result.responseFile;
+        }
+        catch (error) {
+            log?.warn('response dump failed', {
+                id: result.id,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return undefined;
+        }
+    }
     return {
         isEnabled: () => enabled,
         setEnabled: (value) => {
             enabled = value;
         },
         dump,
+        dumpResponse,
+        sweep: (protectedPaths) => sweepDumpDirectory(sweepOptions(resolveDir(), protectedPaths)),
     };
 }

package/dist/logger/engine.d.ts

@@ -15,30 +15,65 @@ export interface InitLoggerOptions extends RedactionOptions {
     /** Level floor applied when no `setLogLevel` call has overridden it. */
     level?: Level | (() => Level | undefined);
 }
+export interface ChannelLogger {
+    error(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    debug(message: string, data?: unknown): void;
+    trace(message: string, data?: unknown): void;
+}
+/**
+ * A logger with its own file, level, redaction, capture sink and buffer.
+ * Two instances in one process never touch each other's settings or lines,
+ * so two plugins that load one shared copy of this module each keep their own
+ * log by holding their own instance.
+ */
+export interface LoggerInstance {
+    /** A logger whose lines carry `channel` and go to this instance's file. */
+    createLogger(channel: string): ChannelLogger;
+    /**
+     * Point this instance at a host's file and level. Idempotent: calling it
+     * again replaces both. A runtime level installed by `setLogLevel` is left
+     * alone, because it is the operator's explicit choice and outranks the
+     * floor a host computed at start-up.
+     */
+    configure(options: InitLoggerOptions): void;
+    /** Operator override of the level floor; undefined removes it. */
+    setLogLevel(level: Level | undefined): void;
+    /**
+     * Write whatever is buffered. Safe to call synchronously from a
+     * process-exit handler, which is how each host drains the buffer on
+     * shutdown.
+     */
+    flushLogs(): void;
+}
+/**
+ * A logger instance of its own, configured with `options`. A plugin whose
+ * copy of this module may be shared with another plugin in the same process
+ * uses this instead of `initLogger`, so neither replaces the other's file,
+ * level, redaction or capture sink.
+ */
+export declare function createLoggerInstance(options: InitLoggerOptions): LoggerInstance;
 /**
- * Point the logger at a host's file and level. Idempotent: calling it again
- * replaces both. A runtime level installed by `setLogLevel` is deliberately
- * left alone, because it is the operator's explicit choice and outranks the
- * floor a host computed at start-up.
+ * Point the module's default logger at a host's file and level, and return
+ * it. Idempotent: calling it again replaces both. A runtime level installed
+ * by `setLogLevel` is deliberately left alone, because it is the operator's
+ * explicit choice and outranks the floor a host computed at start-up.
  */
-export declare function initLogger(options: InitLoggerOptions): void;
+export declare function initLogger(options: InitLoggerOptions): LoggerInstance;
 export declare function setLogLevel(l: Level | undefined): void;
 /**
- * Write whatever is buffered. Safe to call synchronously from a process-exit
- * handler, which is how each host drains the buffer on shutdown.
+ * Write whatever the default logger has buffered. Safe to call synchronously
+ * from a process-exit handler, which is how each host drains the buffer on
+ * shutdown.
  */
 export declare function flushLogs(): void;
-export declare function createLogger(channel: string): {
-    error: (m: string, d?: unknown) => void;
-    warn: (m: string, d?: unknown) => void;
-    info: (m: string, d?: unknown) => void;
-    debug: (m: string, d?: unknown) => void;
-    trace: (m: string, d?: unknown) => void;
-};
+export declare function createLogger(channel: string): ChannelLogger;
 export declare function flushForTest(): Promise<void>;
 /**
- * Return the logger to its uninitialised state. Only a test needs this: a
- * single process runs every test file, so a file path left over from one test
- * would keep a later "logger was never initialised" case writing lines.
+ * Return the default logger to its uninitialised state. Only a test needs
+ * this: a single process runs every test file, so a file path left over from
+ * one test would keep a later "logger was never initialised" case writing
+ * lines.
  */
 export declare function resetLoggerForTest(): void;