@camstack/system 1.2.456 → 1.2.458

package/dist/log-file-read-protocol-D0WcLbIV.js

@@ -0,0 +1,817 @@
+const require_chunk = require("./chunk-Cek0wNdY.js");
+const require_log_read_filter = require("./log-read-filter-Bi066jwU.js");
+let zod = require("zod");
+let node_fs_promises = require("node:fs/promises");
+node_fs_promises = require_chunk.__toESM(node_fs_promises);
+let node_path = require("node:path");
+node_path = require_chunk.__toESM(node_path);
+//#region src/builtins/winston-logging/log-file-cursor.ts
+/**
+* The rotated-file cursor (D898): a byte position in one daily file.
+*
+* Files are append-only, so a position never moves while the file grows —
+* that is the whole reason a cursor can be a byte offset. It is opaque to
+* every caller (`w1.` + base64url JSON) and validated on the way back in: a
+* cursor is client input, and its file name reaches `path.join`.
+*/
+/** `camstack-YYYY-MM-DD.log`, as `winston-daily-rotate-file` names them. */
+var LOG_FILE_NAME_RE = /^camstack-\d{4}-\d{2}-\d{2}\.log$/;
+var CURSOR_PREFIX = "w1.";
+var FileCursorSchema = zod.z.object({
+	/** The daily file's name (never a path). */
+	f: zod.z.string().regex(LOG_FILE_NAME_RE),
+	/** A line-start byte offset in that file. */
+	o: zod.z.number().int().nonnegative()
+});
+function encodeFileCursor(cursor) {
+	return `${CURSOR_PREFIX}${Buffer.from(JSON.stringify(cursor)).toString("base64url")}`;
+}
+/** Null for anything this provider did not mint. */
+function decodeFileCursor(raw) {
+	if (!raw.startsWith(CURSOR_PREFIX)) return null;
+	try {
+		const json = JSON.parse(Buffer.from(raw.slice(3), "base64url").toString("utf8"));
+		const parsed = FileCursorSchema.safeParse(json);
+		return parsed.success ? parsed.data : null;
+	} catch {
+		return null;
+	}
+}
+var BLOCK_BYTES = 1024 * 1024;
+/** Chunk size for reading the file while indexing. */
+var READ_CHUNK = 4 * 1024 * 1024;
+var LEVEL_RANK = {
+	debug: 0,
+	info: 1,
+	warn: 2,
+	error: 3
+};
+var IndexHeaderSchema = zod.z.object({
+	v: zod.z.literal(1),
+	ino: zod.z.number(),
+	block: zod.z.number().int().positive()
+});
+var IndexBlockSchema = zod.z.object({
+	/** Byte range [s, e), e on a line boundary. */
+	s: zod.z.number().int().nonnegative(),
+	e: zod.z.number().int().positive(),
+	n: zod.z.number().int().nonnegative(),
+	/** Epoch ms range; null when a line's timestamp could not be read. */
+	t0: zod.z.number().nullable(),
+	t1: zod.z.number().nullable(),
+	d: zod.z.array(zod.z.number()).nullable(),
+	a: zod.z.array(zod.z.string()).nullable(),
+	o: zod.z.array(zod.z.string()).nullable(),
+	/** Highest level rank in the block. */
+	l: zod.z.number().int().min(0).max(3)
+});
+var RE_LEVEL = /"level":"(debug|info|warn|error)"/;
+var RE_TS = /"timestamp":"([^"\\]{10,40})"\}$/;
+var RE_DEVICE = /"deviceId":(\d{1,15})(?=[,}])/g;
+var RE_ADDON = /"addonId":"([^"\\]{1,200})"/g;
+var RE_AGENT = /"agentId":"([^"\\]{1,200})"/g;
+var RE_NODE = /"nodeId":"([^"\\/]{1,200})/g;
+function bare(addonId) {
+	let out = addonId.split("@")[0] ?? addonId;
+	const colon = out.indexOf("::");
+	if (colon >= 0) out = out.slice(0, colon);
+	return out;
+}
+/** Facts off the raw text — no JSON.parse. */
+function extractLineFacts(line) {
+	const level = RE_LEVEL.exec(line);
+	const ts = RE_TS.exec(line);
+	const parsedTs = ts?.[1] !== void 0 ? Date.parse(ts[1]) : NaN;
+	const deviceIds = [];
+	for (const m of line.matchAll(RE_DEVICE)) deviceIds.push(Number(m[1]));
+	const addonIds = [];
+	for (const m of line.matchAll(RE_ADDON)) if (m[1] !== void 0) addonIds.push(bare(m[1]));
+	const nodes = [];
+	for (const m of line.matchAll(RE_AGENT)) if (m[1] !== void 0) nodes.push(m[1]);
+	for (const m of line.matchAll(RE_NODE)) if (m[1] !== void 0) nodes.push(m[1]);
+	return {
+		ts: Number.isFinite(parsedTs) ? parsedTs : null,
+		level: level?.[1] !== void 0 ? LEVEL_RANK[level[1]] ?? 3 : 3,
+		deviceIds,
+		addonIds,
+		nodes
+	};
+}
+var GrowingSet = class {
+	values = /* @__PURE__ */ new Set();
+	add(value) {
+		if (this.values === null) return;
+		this.values.add(value);
+		if (this.values.size > 256) this.values = null;
+	}
+	poison() {
+		this.values = null;
+	}
+	toArray() {
+		return this.values === null ? null : [...this.values];
+	}
+};
+/** Accumulates lines into one block. */
+var BlockBuilder = class {
+	start;
+	n = 0;
+	t0 = Number.POSITIVE_INFINITY;
+	t1 = Number.NEGATIVE_INFINITY;
+	tsUnknown = false;
+	d = new GrowingSet();
+	a = new GrowingSet();
+	o = new GrowingSet();
+	l = 0;
+	constructor(start) {
+		this.start = start;
+	}
+	add(facts) {
+		this.n += 1;
+		if (facts.ts === null) this.tsUnknown = true;
+		else {
+			if (this.t0 !== null && facts.ts < this.t0) this.t0 = facts.ts;
+			if (this.t1 !== null && facts.ts > this.t1) this.t1 = facts.ts;
+		}
+		for (const id of facts.deviceIds) this.d.add(id);
+		for (const id of facts.addonIds) this.a.add(id);
+		for (const id of facts.nodes) this.o.add(id);
+		if (facts.level > this.l) this.l = facts.level;
+	}
+	/** A line whose facts could not be read: the block may hold anything. */
+	addUnknown() {
+		this.n += 1;
+		this.tsUnknown = true;
+		this.d.poison();
+		this.a.poison();
+		this.o.poison();
+		this.l = 3;
+	}
+	get lines() {
+		return this.n;
+	}
+	finish(end) {
+		const known = !this.tsUnknown && this.n > 0;
+		return {
+			s: this.start,
+			e: end,
+			n: this.n,
+			t0: known ? this.t0 : null,
+			t1: known ? this.t1 : null,
+			d: this.d.toArray(),
+			a: this.a.toArray(),
+			o: this.o.toArray(),
+			l: this.l
+		};
+	}
+};
+function indexEnd(index) {
+	return index.blocks.at(-1)?.e ?? 0;
+}
+function indexPathOf(logPath) {
+	return `${logPath}.idx`;
+}
+/**
+* Load `<file>.idx`. Returns an empty index (to be rebuilt) when the sidecar
+* is missing, belongs to another inode, or is not a contiguous tiling; keeps
+* the valid prefix when only its tail is torn.
+*/
+async function loadFileIndex(logPath, ino, size) {
+	let raw;
+	try {
+		raw = await node_fs_promises.readFile(indexPathOf(logPath), "utf8");
+	} catch {
+		return {
+			index: {
+				ino,
+				blocks: []
+			},
+			rewrite: true
+		};
+	}
+	const lines = raw.split("\n");
+	const header = safeJson(lines[0] ?? "");
+	const parsedHeader = IndexHeaderSchema.safeParse(header);
+	if (!parsedHeader.success || parsedHeader.data.ino !== ino) return {
+		index: {
+			ino,
+			blocks: []
+		},
+		rewrite: true
+	};
+	const blocks = [];
+	let expected = 0;
+	let torn = false;
+	for (const line of lines.slice(1)) {
+		if (line.length === 0) continue;
+		const block = IndexBlockSchema.safeParse(safeJson(line));
+		if (!block.success || block.data.s !== expected || block.data.e <= block.data.s || block.data.e > size) {
+			torn = true;
+			break;
+		}
+		blocks.push(block.data);
+		expected = block.data.e;
+	}
+	return {
+		index: {
+			ino,
+			blocks
+		},
+		rewrite: torn
+	};
+}
+function safeJson(text) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+}
+async function rewriteSidecar(logPath, index) {
+	const header = JSON.stringify({
+		v: 1,
+		ino: index.ino,
+		block: BLOCK_BYTES
+	});
+	const body = index.blocks.map((b) => JSON.stringify(b)).join("\n");
+	const tmp = `${indexPathOf(logPath)}.tmp`;
+	await node_fs_promises.writeFile(tmp, body.length > 0 ? `${header}\n${body}\n` : `${header}\n`);
+	await node_fs_promises.rename(tmp, indexPathOf(logPath));
+}
+/**
+* Extend `index` over whatever complete lines were appended to the file since
+* its last completed block, persisting each block as it completes. Returns
+* the number of bytes read.
+*/
+async function catchUpFileIndex(logPath, index, opts) {
+	if (opts.rewrite) await rewriteSidecar(logPath, index);
+	const handle = await node_fs_promises.open(logPath, "r");
+	try {
+		const size = (await handle.stat()).size;
+		let pos = indexEnd(index);
+		let builder = new BlockBuilder(pos);
+		let readBytes = 0;
+		const buf = Buffer.allocUnsafe(READ_CHUNK);
+		while (pos < size) {
+			if (opts.shouldStop?.() === true) break;
+			const { bytesRead } = await handle.read(buf, 0, Math.min(READ_CHUNK, size - pos), pos);
+			if (bytesRead === 0) break;
+			readBytes += bytesRead;
+			const completed = [];
+			let lineStart = 0;
+			for (;;) {
+				const nl = buf.indexOf(10, lineStart);
+				if (nl === -1 || nl >= bytesRead) break;
+				builder.add(extractLineFacts(buf.toString("utf8", lineStart, nl)));
+				lineStart = nl + 1;
+				const absolute = pos + lineStart;
+				if (absolute - builder.start >= 1048576) {
+					const block = builder.finish(absolute);
+					index.blocks.push(block);
+					completed.push(block);
+					builder = new BlockBuilder(absolute);
+				}
+			}
+			if (completed.length > 0) await node_fs_promises.appendFile(indexPathOf(logPath), `${completed.map((b) => JSON.stringify(b)).join("\n")}\n`);
+			if (lineStart === 0) {
+				if (bytesRead < READ_CHUNK) break;
+				builder.addUnknown();
+				pos += bytesRead;
+				continue;
+			}
+			pos += lineStart;
+			await opts.yieldFn?.();
+		}
+		return readBytes;
+	} finally {
+		await handle.close();
+	}
+}
+//#endregion
+//#region src/builtins/winston-logging/log-file-index-store.ts
+/**
+* The indexes of every daily file in one logs directory (D898), kept by the
+* reader thread.
+*
+* - `indexOf(file)` brings that file's index up to the bytes written so far
+*   (cheap for the live file: only the bytes since the last call) and returns
+*   it. A file whose index is still being built answers with the part that
+*   exists; the reader scans the rest without skipping.
+* - `backgroundPass()` indexes every file, newest first, yielding between
+*   chunks so a read is never queued behind it, and removes sidecars whose
+*   log file the rotation deleted.
+*/
+/** Unindexed bytes a read waits for before scanning; more is indexed behind it. */
+var SYNC_CATCH_UP_BYTES = 8 * 1024 * 1024;
+var yieldToEventLoop = () => new Promise((resolve) => setImmediate(resolve));
+var LogFileIndexStore = class {
+	logsDir;
+	files = /* @__PURE__ */ new Map();
+	constructor(logsDir) {
+		this.logsDir = logsDir;
+	}
+	async indexOf(fileName, opts = {}) {
+		if (!LOG_FILE_NAME_RE.test(fileName)) return null;
+		const logPath = node_path.join(this.logsDir, fileName);
+		let stat;
+		try {
+			stat = await node_fs_promises.stat(logPath);
+		} catch {
+			this.files.delete(fileName);
+			return null;
+		}
+		let entry = this.files.get(fileName);
+		if (entry === void 0 || entry.index.ino !== stat.ino) {
+			const loaded = await loadFileIndex(logPath, stat.ino, stat.size);
+			entry = {
+				index: loaded.index,
+				rewrite: loaded.rewrite,
+				busy: Promise.resolve(),
+				running: false
+			};
+			this.files.set(fileName, entry);
+		}
+		const current = entry;
+		if (current.running) return current.index;
+		const run = current.busy.then(async () => {
+			current.running = true;
+			const rewrite = current.rewrite;
+			current.rewrite = false;
+			try {
+				await catchUpFileIndex(logPath, current.index, {
+					rewrite,
+					yieldFn: yieldToEventLoop
+				});
+			} catch {
+				current.rewrite = true;
+			} finally {
+				current.running = false;
+			}
+		});
+		current.busy = run;
+		if (opts.wait === true || stat.size - indexEnd(current.index) <= SYNC_CATCH_UP_BYTES) await run;
+		return current.index;
+	}
+	/** Index everything, newest first; drop orphaned sidecars. */
+	async backgroundPass(shouldStop) {
+		let names;
+		try {
+			names = await node_fs_promises.readdir(this.logsDir);
+		} catch {
+			return;
+		}
+		const logs = new Set(names.filter((n) => LOG_FILE_NAME_RE.test(n)));
+		for (const name of names) {
+			if (!name.endsWith(".log.idx")) continue;
+			const log = name.slice(0, -4);
+			if (!logs.has(log)) await node_fs_promises.rm(node_path.join(this.logsDir, name), { force: true });
+		}
+		for (const name of [...logs].toSorted().toReversed()) {
+			if (shouldStop()) return;
+			await this.indexOf(name, { wait: true });
+		}
+	}
+};
+var MAX_BUDGET_MS = 5e3;
+/** Read granularity of a backward scan. */
+var SCAN_CHUNK = 1024 * 1024;
+/** What a reader can rule out from a block alone. */
+function blockMayMatch(block, filter) {
+	if (block.l < filter.levelFloor) return false;
+	if (filter.until !== null && block.t0 !== null && block.t0 > filter.until) return false;
+	if (filter.since !== null && block.t1 !== null && block.t1 < filter.since) return false;
+	if (filter.deviceId !== null && block.d !== null && !block.d.includes(filter.deviceId)) return false;
+	if (filter.addonId !== null && block.a !== null && !block.a.includes(filter.addonId)) return false;
+	if (filter.nodeId !== null && block.o !== null && !block.o.includes(filter.nodeId)) return false;
+	return true;
+}
+/** The byte strings a matching raw line MUST contain (superset tests). */
+function requiredNeedles(filter) {
+	const needles = [];
+	if (filter.deviceId !== null) needles.push(Buffer.from(`"deviceId":${String(filter.deviceId)}`));
+	if (filter.addonId !== null) needles.push(Buffer.from(`"addonId":"${filter.addonId}`));
+	return needles;
+}
+/** A text needle that survives JSON escaping unchanged can pre-filter the raw line. */
+function rawTextNeedle(filter) {
+	const text = filter.textLower;
+	if (text === null) return null;
+	return /["\\\u0000-\u001f]/.test(text) ? null : text;
+}
+/** Sorted occurrence positions of `needle` in `data`. */
+function occurrences(data, needle, from) {
+	const out = [];
+	let at = data.indexOf(needle, from);
+	while (at !== -1) {
+		out.push(at);
+		at = data.indexOf(needle, at + 1);
+	}
+	return out;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** One JSON row → a read entry, or null for a line that is not one of ours. */
+function parseLogRow(text) {
+	let raw;
+	try {
+		raw = JSON.parse(text);
+	} catch {
+		return null;
+	}
+	if (!isRecord(raw)) return null;
+	const { level, message, timestamp, scope, id, tags, meta } = raw;
+	if (level !== "debug" && level !== "info" && level !== "warn" && level !== "error") return null;
+	if (typeof message !== "string" || typeof timestamp !== "string") return null;
+	const ts = Date.parse(timestamp);
+	if (!Number.isFinite(ts)) return null;
+	const cleanTags = {};
+	if (isRecord(tags)) {
+		for (const [key, value] of Object.entries(tags)) if (typeof value === "string" || typeof value === "number") cleanTags[key] = value;
+	}
+	const hasTags = Object.keys(cleanTags).length > 0;
+	const scopeText = typeof scope === "string" ? scope : void 0;
+	const metaRecord = isRecord(meta) ? meta : void 0;
+	return {
+		entry: {
+			...typeof id === "string" ? { id } : {},
+			timestamp: ts,
+			level,
+			...scopeText !== void 0 ? { scope: scopeText } : {},
+			message,
+			...hasTags ? { tags: cleanTags } : {},
+			...metaRecord !== void 0 ? { meta: metaRecord } : {}
+		},
+		line: {
+			timestamp: ts,
+			level,
+			message,
+			scope: scopeText,
+			tags: hasTags ? cleanTags : void 0,
+			meta: metaRecord
+		}
+	};
+}
+/** Daily files, newest first. */
+async function listLogFiles(logsDir) {
+	let names;
+	try {
+		names = await node_fs_promises.readdir(logsDir);
+	} catch {
+		return [];
+	}
+	return names.filter((n) => LOG_FILE_NAME_RE.test(n)).toSorted((a, b) => a < b ? 1 : a > b ? -1 : 0);
+}
+/** Regions of [0, end), newest first: the unindexed tail, then the blocks. */
+function regionsBackward(index, end) {
+	const out = [];
+	const indexed = index === null ? 0 : Math.min(indexEnd(index), end);
+	if (end > indexed) out.push({
+		start: indexed,
+		end,
+		block: null
+	});
+	if (index !== null) for (let i = index.blocks.length - 1; i >= 0; i -= 1) {
+		const block = index.blocks[i];
+		if (block === void 0 || block.s >= end) continue;
+		out.push({
+			start: block.s,
+			end: Math.min(block.e, end),
+			block
+		});
+	}
+	return out;
+}
+function overBudget(s) {
+	return s.ctx.isCancelled() || (s.ctx.now ?? Date.now)() >= s.deadline;
+}
+/**
+* Scan [start, end) backward, calling `onLine` newest first with each line's
+* text and start offset. `end` must be a line start (or the end of the
+* complete data); a trailing partial line is ignored. Returns the start
+* offset of the oldest line examined, or `start` when the region is done.
+*/
+async function scanBackward(handle, start, end, s, onLine) {
+	let hi = end;
+	let pending = Buffer.alloc(0);
+	let first = true;
+	while (hi > start) {
+		const lo = Math.max(start, hi - SCAN_CHUNK);
+		const chunk = Buffer.allocUnsafe(hi - lo);
+		const { bytesRead } = await handle.read(chunk, 0, hi - lo, lo);
+		s.scannedBytes += bytesRead;
+		let data = pending.length > 0 ? Buffer.concat([chunk.subarray(0, bytesRead), pending]) : chunk.subarray(0, bytesRead);
+		if (first) {
+			first = false;
+			const lastNl = data.lastIndexOf(10);
+			data = data.subarray(0, lastNl + 1);
+			if (data.length === 0 && lo === start) return {
+				reached: start,
+				stopped: false
+			};
+		}
+		let firstStart = 0;
+		if (lo !== start) {
+			const nl = data.indexOf(10);
+			if (nl === -1 || nl === data.length - 1) {
+				pending = Buffer.from(data);
+				hi = lo;
+				continue;
+			}
+			firstStart = nl + 1;
+		}
+		const starts = [];
+		for (let p = firstStart; p < data.length;) {
+			starts.push(p);
+			const nl = data.indexOf(10, p);
+			if (nl === -1) break;
+			p = nl + 1;
+		}
+		const occ = s.needles.map((needle) => occurrences(data, needle, firstStart));
+		const occPtr = occ.map((o) => o.length - 1);
+		for (let k = starts.length - 1; k >= 0; k -= 1) {
+			const ls = starts[k] ?? 0;
+			const le = (starts[k + 1] ?? data.length) - 1;
+			let candidate = true;
+			for (let n = 0; n < occ.length; n += 1) {
+				const positions = occ[n] ?? [];
+				let ptr = occPtr[n] ?? -1;
+				while (ptr >= 0 && (positions[ptr] ?? 0) >= le) ptr -= 1;
+				occPtr[n] = ptr;
+				if (ptr < 0 || (positions[ptr] ?? -1) < ls) candidate = false;
+			}
+			if (!candidate) continue;
+			const text = data.toString("utf8", ls, le);
+			if (s.textNeedle !== null && !text.toLowerCase().includes(s.textNeedle)) continue;
+			if (onLine(text, lo + ls) === "stop") return {
+				reached: lo + ls,
+				stopped: true
+			};
+		}
+		pending = Buffer.from(data.subarray(0, firstStart));
+		hi = lo;
+		const reached = lo + firstStart;
+		if (hi > start && overBudget(s)) return {
+			reached,
+			stopped: true
+		};
+	}
+	return {
+		reached: start,
+		stopped: false
+	};
+}
+/**
+* One backward slice. `entries` newest first; `nextBefore` resumes exactly
+* where this slice stopped.
+*/
+async function readLogFilesBackward(ctx, query) {
+	const filter = require_log_read_filter.compileLogFilter(query);
+	const limit = query.limit ?? 200;
+	const budget = Math.min(query.budgetMs ?? 1e3, MAX_BUDGET_MS);
+	const s = {
+		filter,
+		needles: requiredNeedles(filter),
+		textNeedle: rawTextNeedle(filter),
+		stats: {
+			blocksSkipped: 0,
+			regionsRead: 0,
+			blocksRead: 0,
+			linesParsed: 0
+		},
+		scannedBytes: 0,
+		deadline: (ctx.now ?? Date.now)() + budget,
+		ctx
+	};
+	const from = query.before !== void 0 ? decodeFileCursor(query.before) : null;
+	const files = (await listLogFiles(ctx.logsDir)).filter((f) => from === null || f <= from.f);
+	const entries = [];
+	let newestEnd = null;
+	const finish = (nextBefore, done) => ({
+		result: {
+			entries,
+			nextBefore: nextBefore === null ? null : encodeFileCursor(nextBefore),
+			nextAfter: newestEnd === null ? null : encodeFileCursor(newestEnd),
+			scannedBytes: s.scannedBytes,
+			done,
+			...ctx.isCancelled() ? { cancelled: true } : {}
+		},
+		stats: s.stats
+	});
+	for (const file of files) {
+		const filePath = node_path.join(ctx.logsDir, file);
+		let size;
+		try {
+			size = (await node_fs_promises.stat(filePath)).size;
+		} catch {
+			continue;
+		}
+		const end = from !== null && file === from.f ? Math.min(from.o, size) : size;
+		const index = await ctx.indexOf(file);
+		const handle = await node_fs_promises.open(filePath, "r");
+		try {
+			for (const region of regionsBackward(index, end)) {
+				const block = region.block;
+				if (block !== null) {
+					if (filter.since !== null && block.t1 !== null && block.t1 < filter.since) return finish(null, true);
+					if (!blockMayMatch(block, filter)) {
+						s.stats.blocksSkipped += 1;
+						continue;
+					}
+				}
+				s.stats.regionsRead += 1;
+				if (block !== null) s.stats.blocksRead += 1;
+				let reachedSince = false;
+				const outcome = await scanBackward(handle, region.start, region.end, s, (text, lineStart) => {
+					s.stats.linesParsed += 1;
+					const row = parseLogRow(text);
+					if (row === null) return "continue";
+					if (filter.since !== null && row.line.timestamp < filter.since) {
+						reachedSince = true;
+						return "stop";
+					}
+					if (!require_log_read_filter.lineMatches(row.line, filter)) return "continue";
+					if (newestEnd === null) newestEnd = {
+						f: file,
+						o: lineStart + Buffer.byteLength(text, "utf8") + 1
+					};
+					entries.push(row.entry);
+					return entries.length >= limit ? "stop" : "continue";
+				});
+				if (reachedSince) return finish(null, true);
+				if (outcome.stopped) return finish({
+					f: file,
+					o: outcome.reached
+				}, false);
+				if (overBudget(s)) return finish({
+					f: file,
+					o: region.start
+				}, false);
+			}
+		} finally {
+			await handle.close();
+		}
+	}
+	return finish(null, true);
+}
+/**
+* One forward slice: lines strictly after `after`, scanned oldest first and
+* returned newest first like every page. `nextAfter` is where the next poll
+* starts; `done` means the scan reached the end of the newest file.
+*/
+async function readLogFilesForward(ctx, query) {
+	const filter = require_log_read_filter.compileLogFilter(query);
+	const limit = query.limit ?? 200;
+	const from = decodeFileCursor(query.after);
+	const stats = {
+		blocksSkipped: 0,
+		regionsRead: 0,
+		blocksRead: 0,
+		linesParsed: 0
+	};
+	const files = (await listLogFiles(ctx.logsDir)).filter((f) => from === null || f >= from.f).toReversed();
+	const collected = [];
+	let scannedBytes = 0;
+	let oldestStart = null;
+	let reached = from;
+	let stoppedEarly = false;
+	const now = ctx.now ?? Date.now;
+	const deadline = now() + Math.min(query.budgetMs ?? 1e3, MAX_BUDGET_MS);
+	outer: for (const file of files) {
+		const filePath = node_path.join(ctx.logsDir, file);
+		let handle;
+		try {
+			handle = await node_fs_promises.open(filePath, "r");
+		} catch {
+			continue;
+		}
+		try {
+			const size = (await handle.stat()).size;
+			let pos = from !== null && file === from.f ? Math.min(from.o, size) : 0;
+			stats.regionsRead += 1;
+			const buf = Buffer.allocUnsafe(SCAN_CHUNK);
+			while (pos < size) {
+				const { bytesRead } = await handle.read(buf, 0, Math.min(SCAN_CHUNK, size - pos), pos);
+				if (bytesRead === 0) break;
+				scannedBytes += bytesRead;
+				let lineStart = 0;
+				for (;;) {
+					const nl = buf.indexOf(10, lineStart);
+					if (nl === -1 || nl >= bytesRead) break;
+					const text = buf.toString("utf8", lineStart, nl);
+					const absStart = pos + lineStart;
+					lineStart = nl + 1;
+					reached = {
+						f: file,
+						o: pos + lineStart
+					};
+					stats.linesParsed += 1;
+					const row = parseLogRow(text);
+					if (row === null || !require_log_read_filter.lineMatches(row.line, filter)) continue;
+					if (oldestStart === null) oldestStart = {
+						f: file,
+						o: absStart
+					};
+					collected.push(row.entry);
+					if (collected.length >= limit) {
+						stoppedEarly = true;
+						break outer;
+					}
+				}
+				if (lineStart === 0) break;
+				pos += lineStart;
+				if (ctx.isCancelled() || now() >= deadline) {
+					stoppedEarly = true;
+					break outer;
+				}
+			}
+		} finally {
+			await handle.close();
+		}
+	}
+	return {
+		result: {
+			entries: collected.toReversed(),
+			nextBefore: oldestStart === null ? null : encodeFileCursor(oldestStart),
+			nextAfter: reached === null ? null : encodeFileCursor(reached),
+			scannedBytes,
+			done: !stoppedEarly,
+			...ctx.isCancelled() ? { cancelled: true } : {}
+		},
+		stats
+	};
+}
+//#endregion
+//#region src/builtins/winston-logging/log-file-read-protocol.ts
+function isObject(value) {
+	return typeof value === "object" && value !== null;
+}
+function isFromReader(value) {
+	return isObject(value) && (value["type"] === "result" || value["type"] === "error") && typeof value["id"] === "number";
+}
+function isToReader(value) {
+	if (!isObject(value)) return false;
+	if (value["type"] === "stop") return true;
+	if (value["type"] === "cancel") return typeof value["requestId"] === "string";
+	return value["type"] === "read" && typeof value["id"] === "number" && isObject(value["query"]);
+}
+/** Requests cancelled before or while they run, with when, so the set cannot grow. */
+var CancelBook = class {
+	at = /* @__PURE__ */ new Map();
+	cancel(requestId, now = Date.now()) {
+		this.at.set(requestId, now);
+		for (const [id, when] of this.at) if (now - when > 6e4) this.at.delete(id);
+	}
+	isCancelled(requestId) {
+		return requestId !== void 0 && this.at.has(requestId);
+	}
+	settle(requestId) {
+		if (requestId !== void 0) this.at.delete(requestId);
+	}
+};
+async function serveRead(logsDir, store, cancels, query) {
+	const ctx = {
+		logsDir,
+		indexOf: (file) => store.indexOf(file),
+		isCancelled: () => cancels.isCancelled(query.requestId)
+	};
+	try {
+		const after = query.after;
+		return after !== void 0 ? await readLogFilesForward(ctx, {
+			...query,
+			after
+		}) : await readLogFilesBackward(ctx, query);
+	} finally {
+		cancels.settle(query.requestId);
+	}
+}
+//#endregion
+Object.defineProperty(exports, "CancelBook", {
+	enumerable: true,
+	get: function() {
+		return CancelBook;
+	}
+});
+Object.defineProperty(exports, "LogFileIndexStore", {
+	enumerable: true,
+	get: function() {
+		return LogFileIndexStore;
+	}
+});
+Object.defineProperty(exports, "isFromReader", {
+	enumerable: true,
+	get: function() {
+		return isFromReader;
+	}
+});
+Object.defineProperty(exports, "isToReader", {
+	enumerable: true,
+	get: function() {
+		return isToReader;
+	}
+});
+Object.defineProperty(exports, "serveRead", {
+	enumerable: true,
+	get: function() {
+		return serveRead;
+	}
+});