lograil 0.1.0

package/dist/esm/transport/file.js

@@ -0,0 +1,662 @@
+import { mkdir, open, rename, rm, stat, readdir } from '../shims/index.js';
+import { basename, dirname, join } from '../shims/index.js';
+import { tmpdir } from '../shims/index.js';
+import { createJsonFormatter } from '../pipeline/formatter.js';
+function timeStamp(d, unit) {
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, '0');
+    const day = String(d.getDate()).padStart(2, '0');
+    if (unit === 'day')
+        return `${y}-${m}-${day}`;
+    const h = String(d.getHours()).padStart(2, '0');
+    return `${y}-${m}-${day}-${h}`;
+}
+// ---- shared helpers -------------------------------------------------------
+/** Best-effort cap: delete the oldest bucket/generation files beyond `maxFiles`.
+ * Only touches files the transport has explicitly created (tracked in `owned`).
+ * When `exclude` is provided, files matching its basename are also kept (used
+ * to protect the just-rotated-away file so it survives until the next bucket). */
+async function trimRing(dir, appName, ext, maxFiles, owned, exclude) {
+    // maxFiles<=1 → no cap configured; skip trimming.
+    if (maxFiles <= 1)
+        return;
+    const keep = maxFiles - 1;
+    const excludeName = exclude ? basename(exclude) : undefined;
+    try {
+        const backups = (await readdir(dir))
+            .filter((f) => owned.has(f) &&
+            f !== `${appName}.${ext}` &&
+            (excludeName === undefined || f !== excludeName))
+            .sort();
+        const excess = backups.length - keep;
+        for (let i = 0; i < excess; i++) {
+            const toDelete = backups[i];
+            await rm(join(dir, toDelete), { force: true }).catch(() => { });
+            owned.delete(toDelete);
+        }
+    }
+    catch {
+        /* ignore */
+    }
+}
+/** Best-effort cap that counts by **time buckets** (stamps) rather than files.
+ * Groups owned files by their timestamp stamp, then deletes the oldest
+ * complete bucket(s) when the number of distinct stamps exceeds `maxFiles`.
+ * This is the correct trimming strategy for `rotate-time` with `maxSize`,
+ * where a single bucket may produce multiple seq-numbered files. */
+async function trimTimeRing(dir, appName, ext, maxFiles, owned) {
+    if (maxFiles <= 1)
+        return;
+    const prefix = `${appName}.`;
+    const suffix = `.${ext}`;
+    const stampRe = /^\d{4}-\d{2}-\d{2}(?:-\d{2})?/;
+    try {
+        // Group owned files by stamp.
+        const groups = new Map();
+        for (const f of owned) {
+            if (f === `${appName}.${ext}`)
+                continue;
+            if (!f.startsWith(prefix) || !f.endsWith(suffix))
+                continue;
+            const body = f.slice(prefix.length, -suffix.length);
+            const m = body.match(stampRe);
+            if (m) {
+                const stamp = m[0];
+                let arr = groups.get(stamp);
+                if (!arr) {
+                    arr = [];
+                    groups.set(stamp, arr);
+                }
+                arr.push(f);
+            }
+        }
+        const stamps = [...groups.keys()].sort();
+        const excess = stamps.length - maxFiles;
+        if (excess <= 0)
+            return;
+        for (let i = 0; i < excess; i++) {
+            const files = groups.get(stamps[i]);
+            for (const f of files) {
+                await rm(join(dir, f), { force: true }).catch(() => { });
+                owned.delete(f);
+            }
+        }
+    }
+    catch {
+        /* ignore */
+    }
+}
+/** Best-effort cap on the number of seq files **within one time bucket**.
+ * Deletes the oldest seq files of `stamp` when the bucket holds more than
+ * `maxPerBucket` files, so a bucket forms an inner ring. The active file
+ * (highest seq) is never deleted. Iterates the `owned` set (not the
+ * directory) so the just-rotated-to active file — which may not exist on
+ * disk yet — is still counted. Best-effort: any fs error is swallowed. */
+async function trimBucketSeq(dir, appName, ext, stamp, maxPerBucket, owned) {
+    if (maxPerBucket <= 0)
+        return;
+    const prefix = `${appName}.${stamp}.`;
+    const suffix = `.${ext}`;
+    try {
+        const files = [...owned].filter((f) => f.startsWith(prefix) && f.endsWith(suffix)).sort();
+        const excess = files.length - maxPerBucket;
+        for (let i = 0; i < excess; i++) {
+            await rm(join(dir, files[i]), { force: true }).catch(() => { });
+            owned.delete(files[i]);
+        }
+    }
+    catch {
+        /* ignore */
+    }
+}
+/**
+ * Global capacity guard: alongside (and independent of) per-mode `maxFiles`,
+ * delete the **oldest** owned files when either a total-size cap or an age cap
+ * is exceeded. "Oldest" is judged by modification time so it works uniformly
+ * across every mode. The active file is never deleted, even if it is the
+ * oldest. Best-effort: any fs error is swallowed.
+ */
+async function enforceGlobalCaps(params) {
+    const { dir, activePath, maxTotalSize, maxAge, now, owned } = params;
+    if (!Number.isFinite(maxTotalSize) && maxAge < 0)
+        return;
+    try {
+        const names = (await readdir(dir)).filter((f) => owned.has(f) && join(dir, f) !== activePath);
+        const files = await Promise.all(names.map(async (f) => {
+            try {
+                const s = await stat(join(dir, f));
+                return { name: f, size: s.size, mtimeMs: s.mtimeMs };
+            }
+            catch {
+                return null; // skip unstatable files — no infinite delete loop
+            }
+        }));
+        const valid = files.filter((f) => f !== null);
+        valid.sort((a, b) => a.mtimeMs - b.mtimeMs);
+        let activeSize = 0;
+        try {
+            activeSize = (await stat(activePath)).size;
+        }
+        catch {
+            /* active file not created yet */
+        }
+        const toDelete = [];
+        // Age cap: drop anything older than the threshold (0 = delete all).
+        if (maxAge >= 0) {
+            for (const f of valid) {
+                if (maxAge === 0 || now - f.mtimeMs > maxAge)
+                    toDelete.push(f.name);
+            }
+        }
+        // Size cap: drop oldest history files until active + history is under the limit.
+        if (Number.isFinite(maxTotalSize)) {
+            let total = activeSize;
+            for (const f of valid)
+                total += f.size;
+            for (const f of valid) {
+                if (total <= maxTotalSize)
+                    break;
+                if (!toDelete.includes(f.name)) {
+                    toDelete.push(f.name);
+                    total -= f.size;
+                }
+            }
+        }
+        for (const f of toDelete) {
+            await rm(join(dir, f), { force: true }).catch(() => { });
+            owned.delete(f);
+        }
+    }
+    catch {
+        /* ignore */
+    }
+}
+// ---- 1.1 single -----------------------------------------------------------
+class SingleRotator {
+    constructor(opts, dir, ext) {
+        this.path = join(dir, `${opts.appName}.${ext}`);
+    }
+    activePath() {
+        return this.path;
+    }
+    async prepare(_bytes, _entry, _now, io) {
+        io.owned.add(basename(this.path));
+        return false;
+    }
+    reset() {
+        /* no transient state */
+    }
+}
+// ---- 1.2 single-truncate --------------------------------------------------
+class TruncateRotator {
+    constructor(opts, dir, ext) {
+        this.path = join(dir, `${opts.appName}.${ext}`);
+        this.backup = join(dir, opts.backupName ?? `${opts.appName}.bak`);
+        this.maxSize = opts.maxSize;
+    }
+    activePath() {
+        return this.path;
+    }
+    async prepare(bytes, _entry, _now, io) {
+        io.owned.add(basename(this.path));
+        io.owned.add(basename(this.backup));
+        let size = 0;
+        try {
+            size = (await stat(this.path)).size;
+        }
+        catch {
+            /* file not written yet */
+        }
+        if (size + bytes > this.maxSize) {
+            await io.closeHandle();
+            // Remove any previous backup first: on Windows `rename` refuses to
+            // overwrite an existing target, which would otherwise block truncation.
+            await rm(this.backup, { force: true }).catch(() => { });
+            io.owned.delete(basename(this.backup));
+            try {
+                await rename(this.path, this.backup);
+                io.owned.delete(basename(this.path));
+                io.owned.add(basename(this.backup));
+                return true; // truncated → a new active file was started
+            }
+            catch {
+                /* nothing to back up yet */
+            }
+        }
+        return false;
+    }
+    reset() {
+        /* no transient state */
+    }
+}
+// ---- 2.1 rotate-size -----------------------------------------------------
+class SizeRotator {
+    constructor(opts, dir, ext) {
+        this.active = join(dir, `${opts.appName}.${ext}`);
+        this.maxSize = opts.maxSize;
+        this.maxFiles = opts.maxFiles;
+    }
+    activePath() {
+        return this.active;
+    }
+    genPath(seq, io) {
+        return join(io.dir, `${io.appName}.${seq}.${io.ext}`);
+    }
+    async prepare(bytes, _entry, _now, io) {
+        io.owned.add(basename(this.active));
+        let size = 0;
+        try {
+            size = (await stat(this.active)).size;
+        }
+        catch {
+            /* file not written yet */
+        }
+        if (size + bytes > this.maxSize) {
+            await io.closeHandle();
+            const gens = this.maxFiles - 1;
+            for (let k = gens; k >= 2; k--) {
+                try {
+                    const from = this.genPath(k - 1, io);
+                    const to = this.genPath(k, io);
+                    await rename(from, to);
+                    io.owned.delete(basename(from));
+                    io.owned.add(basename(to));
+                }
+                catch {
+                    /* missing generation — skip */
+                }
+            }
+            try {
+                await rename(this.active, this.genPath(1, io));
+                io.owned.delete(basename(this.active));
+                io.owned.add(basename(this.genPath(1, io)));
+            }
+            catch {
+                /* nothing to rotate yet */
+            }
+            // Generations are capped by the rename chain above; no extra trim needed.
+            return true;
+        }
+        return false;
+    }
+    reset() {
+        /* no transient state */
+    }
+}
+// ---- 2.2 rotate-time -----------------------------------------------------
+class TimeRotator {
+    constructor(opts, dir, ext) {
+        this.seq = 0;
+        this.dir = dir;
+        this.ext = ext;
+        this.appName = opts.appName;
+        this.unit = opts.unit;
+        this.maxFiles = opts.maxFiles;
+        this.maxSize = opts.maxSize;
+        this.maxFilesPerBucket = opts.maxFilesPerBucket;
+        this.path = join(dir, `${opts.appName}.${ext}`);
+    }
+    activePath() {
+        return this.path;
+    }
+    stampPath(stamp, seq) {
+        return join(this.dir, `${this.appName}.${stamp}.${seq}.${this.ext}`);
+    }
+    /** Most recent existing bucket at or before `upTo`, so a restart continues
+     * the ring instead of orphaning yesterday's file. */
+    async latestExistingStamp(upTo) {
+        try {
+            const files = (await readdir(this.dir)).filter((f) => f.startsWith(`${this.appName}.`) && f.endsWith(`.${this.ext}`));
+            const stampRe = this.unit === 'hour' ? /^\d{4}-\d{2}-\d{2}-\d{2}/ : /^\d{4}-\d{2}-\d{2}/;
+            const prefix = `${this.appName}.`;
+            const suffix = `.${this.ext}`;
+            files.sort();
+            for (let i = files.length - 1; i >= 0; i--) {
+                const body = files[i].slice(prefix.length, -suffix.length);
+                // body is either `${stamp}` or `${stamp}.${seq}` — extract stamp
+                const dotIdx = body.lastIndexOf('.');
+                const stamp = dotIdx > 0 ? body.slice(0, dotIdx) : body;
+                if (stampRe.test(stamp) && stamp <= upTo)
+                    return stamp;
+            }
+        }
+        catch {
+            /* directory not readable yet — start fresh */
+        }
+        return undefined;
+    }
+    /** Find the highest seq number among files in the given time bucket. */
+    async latestExistingSeq(stamp) {
+        if (!this.maxSize)
+            return 0;
+        try {
+            const prefix = `${this.appName}.${stamp}.`;
+            const suffix = `.${this.ext}`;
+            const files = (await readdir(this.dir)).filter((f) => f.startsWith(prefix) && f.endsWith(suffix));
+            let maxSeq = 0;
+            for (const f of files) {
+                const body = f.slice(this.appName.length + 1, -this.ext.length - 1);
+                // body is `${stamp}.${seq}`
+                const parts = body.split('.');
+                const seq = Number(parts[parts.length - 1]);
+                if (Number.isFinite(seq) && seq > maxSeq)
+                    maxSeq = seq;
+            }
+            return maxSeq;
+        }
+        catch {
+            return 0;
+        }
+    }
+    async prepare(bytes, _entry, now, io) {
+        const stamp = timeStamp(now, this.unit);
+        if (this.currentStamp === undefined) {
+            const existing = await this.latestExistingStamp(stamp);
+            this.currentStamp = existing ?? stamp;
+            this.seq = await this.latestExistingSeq(this.currentStamp);
+            this.path = this.stampPath(this.currentStamp, this.seq);
+            io.owned.add(basename(this.path));
+            if (existing && existing !== stamp) {
+                // Bucket already rolled over; open the new one and drop stale files.
+                this.currentStamp = stamp;
+                this.seq = 0;
+                await io.closeHandle();
+                this.path = this.stampPath(stamp, 0);
+                io.owned.add(basename(this.path));
+                await trimTimeRing(io.dir, io.appName, io.ext, this.maxFiles ?? 0, io.owned);
+                return true;
+            }
+            await trimTimeRing(io.dir, io.appName, io.ext, this.maxFiles ?? 0, io.owned);
+            return false;
+        }
+        if (stamp !== this.currentStamp) {
+            // Time bucket changed — archive the previous file and open a new one.
+            this.currentStamp = stamp;
+            this.seq = 0;
+            await io.closeHandle();
+            this.path = this.stampPath(stamp, 0);
+            io.owned.add(basename(this.path));
+            await trimTimeRing(io.dir, io.appName, io.ext, this.maxFiles ?? 0, io.owned);
+            return true;
+        }
+        // Same time bucket — check size-based splitting within the bucket.
+        if (this.maxSize !== undefined) {
+            let size = 0;
+            try {
+                size = (await stat(this.path)).size;
+            }
+            catch {
+                /* file not written yet */
+            }
+            if (size + bytes > this.maxSize) {
+                this.seq += 1;
+                await io.closeHandle();
+                this.path = this.stampPath(this.currentStamp, this.seq);
+                io.owned.add(basename(this.path));
+                await trimTimeRing(io.dir, io.appName, io.ext, this.maxFiles ?? 0, io.owned);
+                // Cap the seq count inside the current bucket (inner ring).
+                await trimBucketSeq(io.dir, io.appName, io.ext, this.currentStamp, this.maxFilesPerBucket ?? 0, io.owned);
+                return true;
+            }
+        }
+        return false;
+    }
+    reset() {
+        this.currentStamp = undefined;
+        this.seq = 0;
+        this.path = join(this.dir, `${this.appName}.${this.ext}`);
+    }
+}
+// ---- 2.3 rotate-custom ---------------------------------------------------
+class CustomRotator {
+    constructor(opts, dir, ext) {
+        this.seq = 0;
+        this.dir = dir;
+        this.ext = ext;
+        this.appName = opts.appName;
+        this.maxFiles = opts.maxFiles;
+        this.shouldRotate = opts.shouldRotate;
+        this.fileName = opts.fileName;
+        this.path = join(dir, this.fileName(opts.appName, 0, ext));
+    }
+    activePath() {
+        return this.path;
+    }
+    async prepare(_bytes, entry, now, io) {
+        const ctx = {
+            entry,
+            size: 0,
+            time: now.toISOString(),
+        };
+        if (this.shouldRotate(entry, ctx)) {
+            this.seq += 1;
+            await io.closeHandle();
+            this.path = join(io.dir, this.fileName(io.appName, this.seq, io.ext));
+            io.owned.add(basename(this.path));
+            await trimRing(io.dir, io.appName, io.ext, this.maxFiles ?? 0, io.owned);
+            return true;
+        }
+        return false;
+    }
+    reset() {
+        this.seq = 0;
+        this.path = join(this.dir, this.fileName(this.appName, 0, this.ext));
+    }
+}
+/**
+ * Single file transport covering every file-output strategy. Each strategy is
+ * an isolated `Rotator` (see above); this class only performs the shared
+ * filesystem plumbing on a serialized queue.
+ *
+ * Modes:
+ *  - `single` (1.1): one fixed file, append forever.
+ *  - `single-truncate` (1.2): back up + truncate when `maxSize` would be exceeded.
+ *  - `rotate-size` (2.1): roll by size into N generations.
+ *  - `rotate-time` (2.2): roll by hour/day into timestamped files.
+ *  - `rotate-custom` (2.3): roll whenever a user predicate says so.
+ *
+ * `appName` is required and is embedded in every file name.
+ */
+export class FileTransport {
+    /** Effective capacity limits, for diagnostics (e.g. "why was my log file
+     * deleted?"). `maxSize`/`maxFiles` reflect the active rotation mode;
+     * `maxTotalSize`/`maxAge` are the global caps (`Infinity`/`-1` = unset). */
+    get caps() {
+        const o = this.options;
+        return {
+            maxSize: 'maxSize' in o ? o.maxSize : undefined,
+            maxFiles: 'maxFiles' in o ? o.maxFiles : undefined,
+            maxFilesPerBucket: 'maxFilesPerBucket' in o ? o.maxFilesPerBucket : undefined,
+            maxTotalSize: this.maxTotalSize,
+            maxAge: this.maxAge,
+        };
+    }
+    constructor(options) {
+        this.owned = new Set();
+        this.closed = false;
+        this.reportedFirstError = false;
+        this.handle = null;
+        this.queue = Promise.resolve();
+        this.ownedScanned = false;
+        this.writeCount = 0;
+        this.lastCheckMs = 0;
+        if (!options.appName) {
+            throw new Error('FileTransport requires an "appName"');
+        }
+        this.options = options;
+        this.dir = options.dir ?? tmpdir();
+        this.ext = options.ext ?? 'log';
+        this.name = options.name ?? `file:${options.appName}`;
+        this.formatter = options.formatter ?? createJsonFormatter();
+        this.filter = options.filter;
+        this.maxTotalSize = options.maxTotalSize ?? Infinity;
+        this.maxAge = options.maxAge ?? -1;
+        this.createdAt = Date.now();
+        switch (options.mode) {
+            case 'single':
+                this.rotator = new SingleRotator(options, this.dir, this.ext);
+                break;
+            case 'single-truncate':
+                this.rotator = new TruncateRotator(options, this.dir, this.ext);
+                break;
+            case 'rotate-size':
+                this.rotator = new SizeRotator(options, this.dir, this.ext);
+                break;
+            case 'rotate-time':
+                this.rotator = new TimeRotator(options, this.dir, this.ext);
+                break;
+            case 'rotate-custom':
+                this.rotator = new CustomRotator(options, this.dir, this.ext);
+                break;
+        }
+        // Capture the clock synchronously at write time so a rotate-time transport
+        // uses the timestamp of the call, not a later microtask.
+        this.clock = options.mode === 'rotate-time' && options.now ? options.now : () => new Date();
+        this.io = {
+            dir: this.dir,
+            ext: this.ext,
+            appName: options.appName,
+            closeHandle: () => this.closeHandle(),
+            owned: this.owned,
+        };
+    }
+    /** Absolute path of the log directory. */
+    getDir() {
+        return this.dir;
+    }
+    /** Absolute path of the file currently being written to. */
+    getActiveFile() {
+        return this.rotator.activePath();
+    }
+    /** List all log files managed by this transport.
+     *
+     *  By default returns every file the transport knows about, including
+     *  files left over from previous runs (discovered via `scanOwned`). Pass
+     *  `{ currentSessionOnly: true }` to restrict the result to files created
+     *  by the current transport instance. */
+    async getFiles(options) {
+        await this.scanOwned();
+        const activePath = this.rotator.activePath();
+        const results = [];
+        for (const name of this.owned) {
+            const filePath = join(this.dir, name);
+            try {
+                const s = await stat(filePath);
+                if (options?.currentSessionOnly && s.mtimeMs < this.createdAt)
+                    continue;
+                results.push({
+                    name,
+                    path: filePath,
+                    size: s.size,
+                    mtime: s.mtimeMs,
+                    active: filePath === activePath,
+                });
+            }
+            catch {
+                // file disappeared between readdir and stat — skip
+            }
+        }
+        return results;
+    }
+    async ensureHandle() {
+        if (!this.handle) {
+            await this.scanOwned();
+            await mkdir(dirname(this.rotator.activePath()), { recursive: true });
+            this.handle = await open(this.rotator.activePath(), 'a');
+            this.io.owned.add(basename(this.rotator.activePath()));
+        }
+        return this.handle;
+    }
+    async scanOwned() {
+        if (this.ownedScanned)
+            return;
+        this.ownedScanned = true;
+        try {
+            const files = await readdir(this.dir);
+            const prefix = `${this.io.appName}.`;
+            const suffix = `.${this.io.ext}`;
+            for (const f of files) {
+                if (f.startsWith(prefix) && f.endsWith(suffix)) {
+                    this.io.owned.add(f);
+                }
+            }
+        }
+        catch {
+            /* ignore scan failures */
+        }
+    }
+    async closeHandle() {
+        if (this.handle) {
+            await this.handle.close();
+            this.handle = null;
+        }
+    }
+    write(entry, formatted) {
+        if (this.closed || (this.filter && !this.filter(entry)))
+            return;
+        const line = formatted + '\n';
+        const bytes = Buffer.byteLength(line, 'utf8');
+        const now = this.clock();
+        const nowMs = now.getTime();
+        const task = this.queue
+            .then(async () => {
+            const rotated = await this.rotator.prepare(bytes, entry, now, this.io);
+            // Run the global cap check only when a rotation just happened (a new
+            // file landed) — that is when stale files can exceed the caps. Non-
+            // rotating modes (e.g. `single`) rely on the throttled periodic check
+            // below, so we never scan the directory on every hot-path write.
+            if (rotated) {
+                await enforceGlobalCaps({
+                    dir: this.dir,
+                    activePath: this.rotator.activePath(),
+                    maxTotalSize: this.maxTotalSize,
+                    maxAge: this.maxAge,
+                    now: nowMs,
+                    owned: this.io.owned,
+                });
+            }
+            // Throttled periodic check so caps are still honored between rotations
+            // (or when a mode never rotates). At most once per PERIODIC_EVERY writes
+            // and once per PERIODIC_INTERVAL_MS.
+            this.writeCount++;
+            const due = this.writeCount % FileTransport.PERIODIC_EVERY === 0 &&
+                nowMs - this.lastCheckMs >= FileTransport.PERIODIC_INTERVAL_MS;
+            if (due) {
+                this.lastCheckMs = nowMs;
+                await enforceGlobalCaps({
+                    dir: this.dir,
+                    activePath: this.rotator.activePath(),
+                    maxTotalSize: this.maxTotalSize,
+                    maxAge: this.maxAge,
+                    now: nowMs,
+                    owned: this.io.owned,
+                });
+            }
+            const handle = await this.ensureHandle();
+            await handle.write(line);
+        })
+            .catch((err) => {
+            if (!this.reportedFirstError) {
+                this.reportedFirstError = true;
+                console.error('[lograil] FileTransport write error (subsequent errors suppressed):', err);
+            }
+        });
+        this.queue = task;
+        return task;
+    }
+    async flush() {
+        await this.queue;
+    }
+    async close() {
+        await this.queue;
+        await this.closeHandle();
+        this.rotator.reset();
+        this.closed = true;
+    }
+}
+// Throttled periodic capacity check (in addition to the mandatory check that
+// runs after every rotation): inspect at most once per `PERIODIC_EVERY`
+// writes and at most once per `PERIODIC_INTERVAL_MS`.
+FileTransport.PERIODIC_EVERY = 256;
+FileTransport.PERIODIC_INTERVAL_MS = 60000;
+//# sourceMappingURL=file.js.map