@tikoci/centrs 0.1.6 → 0.1.8-next.0

package/src/retrieve-sample.ts

@@ -0,0 +1,244 @@
+/**
+ * `retrieve --sample <interval>`: read a menu again every interval, one line
+ * per complete read. The contract is `commands/retrieve/README.md` → Sample.
+ *
+ * Each sample is an ordinary one-shot read (`print` or `get`), so its end is
+ * the read's own `!done` (native) or HTTP response (REST). RouterOS's
+ * `print interval=` was measured and not used: it has no end-of-tick marker,
+ * so a tick is only known complete when the next one starts, and a tick
+ * heavier than its interval saturates the connection (CHR 7.24.5, 2026-10-08).
+ */
+
+import type { EnvelopeValidationMeta } from "./core/envelope.ts";
+import { CentrsError } from "./errors.ts";
+import { createProtocolAdapter } from "./protocols/adapter.ts";
+import {
+	buildRetrieveErrorEnvelope,
+	buildRetrieveErrorEnvelopeFromResolved,
+	executeRetrieve,
+	type ResolvedRetrieveRequest,
+	type RetrieveEnvelope,
+	type RetrieveRequest,
+	type RetrieveSampleStopReason,
+	type RetrieveSampleSummary,
+	type RetrieveSuccessEnvelope,
+	resolveRetrieveRequest,
+	validateRetrieveRead,
+} from "./retrieve.ts";
+import { failedStreamEnvelope, streamEnvelope } from "./retrieve-stream.ts";
+
+export interface RetrieveSampleOptions {
+	/** Ctrl-C: ends the sample with `stopReason: "interrupted"`. */
+	signal?: AbortSignal;
+}
+
+/**
+ * Sample one menu: yields a `sample` line per complete read, then exactly one
+ * summary (successful, or an error envelope carrying the partial count).
+ * Errors before the first read (resolution, validation) yield one error
+ * envelope without a summary.
+ */
+export async function* retrieveSample(
+	request: RetrieveRequest,
+	env: Record<string, string | undefined> = Bun.env,
+	options: RetrieveSampleOptions = {},
+): AsyncGenerator<RetrieveEnvelope, void, void> {
+	if (request.wait !== undefined) {
+		yield buildRetrieveErrorEnvelope(
+			request,
+			new CentrsError({
+				code: "input/invalid-command",
+				summary:
+					"`--sample` with a `--wait` deadline is a bounded waiter, not a sample stream.",
+				remediation:
+					"Consume the final result with `retrieveWait()` or `centrs retrieve … --wait <deadline> --sample <interval>`.",
+			}),
+		);
+		return;
+	}
+	if (request.sample === undefined) {
+		yield buildRetrieveErrorEnvelope(
+			request,
+			new CentrsError({
+				code: "input/invalid-command",
+				summary: "`retrieveSample()` needs `sample`, the time between reads.",
+				remediation:
+					"Set `sample` on the request, e.g. `{ path: '/interface', sample: '5s' }`.",
+				context: { capability: "sample" },
+			}),
+		);
+		return;
+	}
+	let resolved: ResolvedRetrieveRequest;
+	try {
+		resolved = await resolveRetrieveRequest(request, env);
+	} catch (error) {
+		yield buildRetrieveErrorEnvelope(request, error);
+		return;
+	}
+	const startedAt = Date.now();
+	if (options.signal?.aborted) {
+		yield summaryEnvelope(
+			resolved,
+			{ enabled: resolved.validate.value, result: "skipped" },
+			{ stopReason: "interrupted", samples: 0 },
+			startedAt,
+		);
+		return;
+	}
+	const backend = createProtocolAdapter({
+		protocol: resolved.via.value,
+		host: resolved.target.host,
+		port: resolved.target.port,
+		tls: resolved.target.tls,
+		baseUrl: resolved.target.baseUrl,
+		username: resolved.auth.username,
+		password: resolved.auth.password,
+		timeoutMs: resolved.timeoutMs.value,
+		insecure: resolved.insecure?.value,
+	});
+	const sample = resolved.sample ?? { intervalMs: 0 };
+	let samples = 0;
+	let stopReason: RetrieveSampleStopReason | undefined;
+	// Every stop source aborts this signal. It abandons the read in flight
+	// (REST aborts its request; a native read ends when the session closes
+	// below) and ends the wait between reads.
+	const abandon = new AbortController();
+	const stop = (reason: RetrieveSampleStopReason): void => {
+		stopReason ??= reason;
+		abandon.abort();
+	};
+	const onAbort = (): void => stop("interrupted");
+	options.signal?.addEventListener("abort", onAbort);
+	let durationTimer: ReturnType<typeof setTimeout> | undefined;
+	try {
+		let prepared: Awaited<ReturnType<typeof validateRetrieveRead>>;
+		try {
+			prepared = await validateRetrieveRead(resolved, backend);
+		} catch (error) {
+			yield buildRetrieveErrorEnvelopeFromResolved(resolved, error);
+			return;
+		}
+		const { validation, ...plan } = prepared;
+		if (sample.durationMs !== undefined) {
+			durationTimer = setTimeout(
+				() => stop("duration-elapsed"),
+				sample.durationMs,
+			);
+		}
+		try {
+			while (stopReason === undefined) {
+				const sentAt = Date.now();
+				const read = executeRetrieve(
+					resolved,
+					backend,
+					plan,
+					abandon.signal,
+				).then((data) => ({ data }));
+				// A read abandoned by a stop may still fail later; nobody awaits it.
+				read.catch(() => {});
+				const result = await unlessAborted(read, abandon.signal);
+				// A read still in flight at the stop is not a complete sample.
+				if (result === undefined) break;
+				samples += 1;
+				yield streamEnvelope(resolved, validation, result.data, {
+					kind: "sample",
+					index: samples,
+					at: new Date(sentAt).toISOString(),
+					readMs: Date.now() - sentAt,
+				});
+				if (sample.count !== undefined && samples >= sample.count) {
+					stopReason ??= "count-reached";
+					break;
+				}
+				// Start to start; a read slower than the interval delays the next
+				// one instead of overlapping it or bursting to catch up.
+				const waitMs = sentAt + sample.intervalMs - Date.now();
+				if (waitMs > 0) {
+					let timer: ReturnType<typeof setTimeout> | undefined;
+					await unlessAborted(
+						new Promise<void>((resolve) => {
+							timer = setTimeout(resolve, waitMs);
+						}),
+						abandon.signal,
+					);
+					clearTimeout(timer);
+				}
+			}
+		} catch (error) {
+			yield failedStreamEnvelope(
+				resolved,
+				validation,
+				error,
+				(failure) => ({
+					kind: "summary",
+					stopReason: failure,
+					samples,
+					durationMs: Date.now() - startedAt,
+				}),
+				samples,
+			);
+			return;
+		}
+		yield summaryEnvelope(
+			resolved,
+			validation,
+			{ stopReason: stopReason ?? "interrupted", samples },
+			startedAt,
+		);
+	} finally {
+		// A consumer that stopped reading early lands here directly.
+		abandon.abort();
+		clearTimeout(durationTimer);
+		options.signal?.removeEventListener("abort", onAbort);
+		await backend.close();
+	}
+}
+
+/**
+ * `work`'s value, or `undefined` as soon as `signal` aborts. The abort
+ * listener is removed when `work` settles: racing every sample against one
+ * long-lived promise would keep a reaction per sample for the whole run
+ * (#411 review: about 5,300 retained after 3,000 samples).
+ */
+function unlessAborted<T>(
+	work: Promise<T>,
+	signal: AbortSignal,
+): Promise<T | undefined> {
+	if (signal.aborted) return Promise.resolve(undefined);
+	return new Promise<T | undefined>((resolve, reject) => {
+		const onAbort = (): void => resolve(undefined);
+		signal.addEventListener("abort", onAbort, { once: true });
+		work.then(
+			(value) => {
+				signal.removeEventListener("abort", onAbort);
+				resolve(value);
+			},
+			(error: unknown) => {
+				signal.removeEventListener("abort", onAbort);
+				reject(error);
+			},
+		);
+	});
+}
+
+function summaryEnvelope(
+	resolved: ResolvedRetrieveRequest,
+	validation: EnvelopeValidationMeta,
+	counts: Omit<RetrieveSampleSummary, "durationMs">,
+	startedAt: number,
+): RetrieveSuccessEnvelope {
+	const summary: RetrieveSampleSummary = {
+		...counts,
+		durationMs: Date.now() - startedAt,
+	};
+	const envelope = streamEnvelope(resolved, validation, summary, {
+		kind: "summary",
+		...summary,
+	});
+	if (envelope.meta.operation) {
+		envelope.meta.operation.objectCount = counts.samples;
+	}
+	envelope.warnings = [...resolved.warnings];
+	return envelope;
+}

package/src/retrieve-stream.ts

@@ -0,0 +1,115 @@
+/**
+ * Line helpers shared by the two streaming forms of `retrieve`: `--follow`
+ * (`src/retrieve-follow.ts`) and `--sample` (`src/retrieve-sample.ts`). Each
+ * line is one envelope whose `meta.operation.stream` says what it is
+ * (`commands/retrieve/README.md` → Follow, Sample).
+ */
+
+import type { EnvelopeValidationMeta, Tip } from "./core/envelope.ts";
+import { formatCentrsErrorLine } from "./errors.ts";
+import {
+	buildRetrieveErrorEnvelopeFromResolved,
+	metaFromResolved,
+	type ResolvedRetrieveRequest,
+	type RetrieveEnvelope,
+	type RetrieveErrorEnvelope,
+	type RetrieveOutputFormat,
+	type RetrieveStreamMeta,
+	type RetrieveSuccessEnvelope,
+	retrieveRequestSummary,
+} from "./retrieve.ts";
+
+/** One stream line's envelope: `data` plus its `meta.operation.stream` marker. */
+export function streamEnvelope(
+	resolved: ResolvedRetrieveRequest,
+	validation: EnvelopeValidationMeta,
+	data: unknown,
+	stream: RetrieveStreamMeta,
+	tips: Tip[] = [],
+): RetrieveSuccessEnvelope {
+	return {
+		ok: true,
+		data,
+		warnings: [],
+		tips,
+		meta: metaFromResolved(resolved, validation, {
+			kind: "data",
+			objectCount: data === null ? 0 : Array.isArray(data) ? data.length : 1,
+			request: retrieveRequestSummary(resolved),
+			auth: {
+				username: resolved.auth.username,
+				passwordProvided: resolved.auth.passwordProvided,
+			},
+			stream,
+		}),
+	};
+}
+
+/**
+ * The failed summary that ends a stream after it started: the error, plus the
+ * partial counts as a `summary` marker. `stopReason` is `routeros-error` when
+ * RouterOS answered with an error and `transport-error` for anything else
+ * (the same split as `api --stream`); `error.code` names the cause.
+ */
+export function failedStreamEnvelope(
+	resolved: ResolvedRetrieveRequest,
+	validation: EnvelopeValidationMeta,
+	error: unknown,
+	summary: (
+		stopReason: "routeros-error" | "transport-error",
+	) => Extract<RetrieveStreamMeta, { kind: "summary" }>,
+	objectCount: number,
+): RetrieveErrorEnvelope {
+	const envelope = buildRetrieveErrorEnvelopeFromResolved(resolved, error);
+	envelope.meta.validation = validation;
+	if (envelope.meta.operation) {
+		envelope.meta.operation.objectCount = objectCount;
+		envelope.meta.operation.stream = summary(
+			envelope.error.code.startsWith("routeros/")
+				? "routeros-error"
+				: "transport-error",
+		);
+	}
+	return envelope;
+}
+
+/**
+ * One stream envelope as one line: compact NDJSON for every structured format
+ * (a multi-line YAML document cannot be a stream line), and a short row for
+ * `text`. Router text is JSON-escaped so it cannot carry terminal control
+ * bytes.
+ */
+export function renderRetrieveStreamLine(
+	envelope: RetrieveEnvelope,
+	format: RetrieveOutputFormat,
+): string {
+	if (format !== "text") return JSON.stringify(envelope);
+	if (!envelope.ok) return formatCentrsErrorLine(envelope.error);
+	const stream = envelope.meta.operation?.stream;
+	switch (stream?.kind) {
+		case "notice":
+			return envelope.tips
+				.map((tip) => `tip: ${tip.message}${tip.fix ? ` ${tip.fix}` : ""}`)
+				.join("\n");
+		case "frame": {
+			const head = `${stream.index}\t${stream.phase}\t${stream.change}\t${escaped(stream.id)}`;
+			return stream.change === "removed"
+				? `${head}\t(${stream.source})`
+				: `${head}\t${JSON.stringify(envelope.data)}`;
+		}
+		case "synced":
+			return `— synced: ${stream.rows} row(s)`;
+		case "sample":
+			return `${stream.index}\t${stream.at}\t${JSON.stringify(envelope.data)}`;
+		case "summary":
+			return "samples" in stream
+				? `— ${stream.stopReason}: ${stream.samples} sample(s) in ${stream.durationMs}ms`
+				: `— ${stream.stopReason}: ${stream.snapshot} snapshot, ${stream.changes} change(s), ${stream.sweeps} sweep(s) in ${stream.durationMs}ms`;
+		default:
+			return JSON.stringify(envelope.data);
+	}
+}
+
+function escaped(text: string): string {
+	return JSON.stringify(text).slice(1, -1);
+}

package/src/retrieve-wait.ts

@@ -0,0 +1,286 @@
+/** Bounded readiness/condition reads; the router evaluates the shared predicate. */
+import { parseQueries, queryErrorForFlag } from "./core/query.ts";
+import { CentrsError } from "./errors.ts";
+import {
+	createProtocolAdapter,
+	type ProtocolAdapter,
+} from "./protocols/adapter.ts";
+import {
+	applyMaxResultsBudget,
+	buildRetrieveErrorEnvelope,
+	buildRetrieveErrorEnvelopeFromResolved,
+	buildSuccessEnvelope,
+	executeRetrieve,
+	isKnownSingletonPath,
+	type ResolvedRetrieveRequest,
+	type RetrieveEnvelope,
+	type RetrieveRequest,
+	type RetrieveWaitMeta,
+	resolveRetrieveRequest,
+	validateRetrieveRead,
+} from "./retrieve.ts";
+
+export interface RetrieveWaitOptions {
+	signal?: AbortSignal;
+}
+
+/** One final envelope, including attempts/observations on failure. No watch frames. */
+export async function retrieveWait(
+	request: RetrieveRequest,
+	env: Record<string, string | undefined> = Bun.env,
+	options: RetrieveWaitOptions = {},
+): Promise<RetrieveEnvelope> {
+	let resolved: ResolvedRetrieveRequest;
+	try {
+		resolved = await resolveRetrieveRequest(request, env);
+		if (!resolved.wait)
+			throw new CentrsError({
+				code: "usage/conflicting-flags",
+				summary: "`retrieveWait()` needs a `wait` deadline.",
+				remediation:
+					"Set `wait` to an overall duration, e.g. `{ path: '/system/resource', wait: '30s' }`.",
+			});
+	} catch (error) {
+		return buildRetrieveErrorEnvelope(request, error);
+	}
+	const settings = resolved.wait;
+	const startedAt = performance.now();
+	const deadline = startedAt + settings.deadlineMs;
+	const controller = new AbortController();
+	let stopped: "deadline-elapsed" | "interrupted" | undefined;
+	const stop = (reason: typeof stopped) => {
+		stopped ??= reason;
+		controller.abort();
+	};
+	const onAbort = () => stop("interrupted");
+	if (options.signal?.aborted) onAbort();
+	else options.signal?.addEventListener("abort", onAbort, { once: true });
+	// Long waits avoid setTimeout's 32-bit overflow; the loop also checks time
+	// before dispatch and after each completed observation.
+	let deadlineTimer: ReturnType<typeof setTimeout> | undefined;
+	const armDeadline = () => {
+		const remaining = deadline - performance.now();
+		if (remaining <= 0) stop("deadline-elapsed");
+		else
+			deadlineTimer = setTimeout(
+				armDeadline,
+				Math.min(remaining, 2_147_483_647),
+			);
+	};
+	armDeadline();
+	let attempts = 0;
+	let observations = 0;
+	let backend: ProtocolAdapter | undefined;
+	let prepared: Awaited<ReturnType<typeof validateRetrieveRead>> | undefined;
+	let lastError: unknown;
+	const meta = (
+		stopReason: RetrieveWaitMeta["stopReason"],
+	): RetrieveWaitMeta => ({
+		stopReason,
+		elapsedMs: Math.round(performance.now() - startedAt),
+		attempts,
+		observations,
+	});
+	const failure = (
+		error: unknown,
+		reason: RetrieveWaitMeta["stopReason"],
+	): RetrieveEnvelope => {
+		// The combined device predicate retains selection semantics, but a
+		// diagnostic must identify the option that supplied the bad property.
+		if (
+			error instanceof CentrsError &&
+			(error.context?.["flag"] === "--query" ||
+				(error.code === "input/invalid-query" &&
+					Array.isArray(error.context?.["bareNames"]))) &&
+			settings.until.length > 0 &&
+			(!resolved.query ||
+				(error.context?.["parameter"] !== undefined &&
+					!resolved.query.parsed.names.includes(
+						String(error.context["parameter"]),
+					)) ||
+				(Array.isArray(error.context?.["bareNames"]) &&
+					error.context["bareNames"].every(
+						(name) => !resolved.query?.parsed.bareNames.includes(String(name)),
+					)))
+		)
+			error = queryErrorForFlag(error, "--until");
+		const envelope = buildRetrieveErrorEnvelopeFromResolved(resolved, error);
+		if (prepared) envelope.meta.validation = prepared.validation;
+		else if (attempts === 0)
+			envelope.meta.validation = {
+				enabled: resolved.validate.value,
+				result: "skipped",
+			};
+		if (envelope.meta.operation) envelope.meta.operation.wait = meta(reason);
+		return envelope;
+	};
+	const condition = settings.until.length > 0 || settings.untilEmpty;
+	const expressions = [
+		...(resolved.query?.expressions ?? []),
+		...settings.until,
+	];
+	const observationRequest =
+		settings.until.length > 0
+			? {
+					...resolved,
+					query: { expressions, parsed: parseQueries(expressions) },
+				}
+			: resolved;
+	try {
+		while (!stopped) {
+			if (performance.now() >= deadline) {
+				stop("deadline-elapsed");
+				break;
+			}
+			const sentAt = performance.now();
+			attempts++;
+			try {
+				backend ??= createProtocolAdapter({
+					protocol: resolved.via.value,
+					host: resolved.target.host,
+					port: resolved.target.port,
+					tls: resolved.target.tls,
+					baseUrl: resolved.target.baseUrl,
+					username: resolved.auth.username,
+					password: resolved.auth.password,
+					timeoutMs: Math.max(
+						1,
+						Math.min(resolved.timeoutMs.value, Math.ceil(deadline - sentAt)),
+					),
+					insecure: resolved.insecure?.value,
+					signal: controller.signal,
+				});
+				prepared ??= await validateRetrieveRead(observationRequest, backend);
+				if (
+					settings.untilEmpty &&
+					(prepared.inspection?.singleton ??
+						isKnownSingletonPath(observationRequest.path))
+				)
+					throw new CentrsError({
+						code: "usage/conflicting-flags",
+						summary: "`--until-empty` needs a list menu, not a singleton.",
+						remediation:
+							"Use `--wait` alone for singleton readiness, or select a list menu for a zero-row condition.",
+					});
+				if (stopped) break;
+				const data = await executeRetrieve(
+					observationRequest,
+					backend,
+					prepared,
+					controller.signal,
+				);
+				if (performance.now() >= deadline) stop("deadline-elapsed");
+				if (stopped) break;
+				observations++;
+				lastError = undefined;
+				const met =
+					!condition ||
+					(Array.isArray(data) &&
+						(settings.untilEmpty ? data.length === 0 : data.length > 0));
+				if (met) {
+					const envelope = buildSuccessEnvelope(
+						resolved,
+						{ kind: "data", data },
+						prepared.validation,
+						resolved.warnings,
+					);
+					if (envelope.meta.operation)
+						envelope.meta.operation.wait = meta(
+							condition ? "condition-met" : "ready",
+						);
+					return applyMaxResultsBudget(envelope);
+				}
+			} catch (error) {
+				if (stopped) break;
+				if (!isRetryableWaitError(error)) return failure(error, "failed");
+				lastError = error;
+				await backend?.close();
+				backend = undefined;
+				prepared = undefined;
+			}
+			await delay(
+				Math.max(0, sentAt + settings.intervalMs - performance.now()),
+				controller.signal,
+			);
+		}
+		if (stopped === "interrupted")
+			return failure(
+				new CentrsError({
+					code: "wait/interrupted",
+					summary:
+						"The wait was cancelled before readiness or its condition was established.",
+					remediation:
+						"Run the wait again when you want to continue; cancellation is not evidence that the condition holds.",
+				}),
+				"interrupted",
+			);
+		return failure(
+			lastError ??
+				new CentrsError({
+					code: "wait/deadline-exceeded",
+					summary: condition
+						? "The wait deadline passed without a completed observation satisfying the condition."
+						: "The wait deadline passed before a read completed successfully.",
+					remediation:
+						"Check the router's current state and the predicate, or choose a longer `--wait` deadline.",
+					context: { deadlineMs: settings.deadlineMs },
+				}),
+			"deadline-elapsed",
+		);
+	} finally {
+		controller.abort();
+		clearTimeout(deadlineTimer);
+		options.signal?.removeEventListener("abort", onAbort);
+		await backend?.close();
+	}
+}
+
+const TRANSIENT_CAUSES = new Set([
+	"ECONNRESET",
+	"ConnectionReset",
+	"EHOSTDOWN",
+	"EHOSTUNREACH",
+	"ENETDOWN",
+	"ENETUNREACH",
+	"FailedToOpenSocket",
+]);
+
+/** Narrow transient taxonomy; authentication, DNS, TLS and validation fail fast. */
+export function isRetryableWaitError(error: unknown): boolean {
+	if (!(error instanceof CentrsError)) return false;
+	if (
+		[
+			"transport/connection-refused",
+			"transport/connection-closed",
+			"transport/timeout",
+		].includes(error.code)
+	)
+		return true;
+	// Both adapters retain the OS cause when a reset or an absent host maps to
+	// the generic network code. Retry those causes, never all network failures.
+	// A router rebooting on the local LAN fails ARP, and macOS then answers
+	// later connects with "host down": Bun fetch reports that `FailedToOpenSocket`.
+	if (error.code !== "transport/network") return false;
+	const seen = new Set<unknown>();
+	let cause: unknown = error.cause;
+	while (cause && typeof cause === "object" && !seen.has(cause)) {
+		seen.add(cause);
+		if ("code" in cause && TRANSIENT_CAUSES.has(String(cause.code)))
+			return true;
+		cause = "cause" in cause ? cause.cause : undefined;
+	}
+	return false;
+}
+
+function delay(ms: number, signal: AbortSignal): Promise<void> {
+	if (signal.aborted || ms <= 0) return Promise.resolve();
+	return new Promise((resolve) => {
+		const done = () => {
+			clearTimeout(timer);
+			signal.removeEventListener("abort", done);
+			resolve();
+		};
+		const timer = setTimeout(done, ms);
+		signal.addEventListener("abort", done, { once: true });
+	});
+}