@tikoci/centrs 0.1.1 → 0.1.2

package/src/protocols/native-api.ts

@@ -348,6 +348,32 @@ interface PendingCommand {
 	reject: (error: CentrsError) => void;
 }
 
+/**
+ * A long-lived `/listen` subscription. Unlike {@link PendingCommand} it never
+ * buffers to a single resolve — each `!re` is pushed to the consumer as it
+ * arrives, and the stream ends on `!done` (after a `/cancel`'s `interrupted`
+ * trap) or fails on `!fatal`/transport closure.
+ */
+interface StreamingSubscription {
+	command: string;
+	/** An `!re` change frame arrived. */
+	push: (reply: ApiReply) => void;
+	/** An `!trap` arrived (an `interrupted` trap is the normal `/cancel` path). */
+	trap: (reply: ApiReply) => void;
+	/** `!done` arrived — the listen closed. */
+	settle: () => void;
+	/** `!fatal` or transport closure — the stream cannot continue. */
+	fail: (error: CentrsError) => void;
+}
+
+/** A `/cancel`'s `interrupted` trap (category 2) is the expected end of a listen, not an error. */
+function isInterruptedTrap(trap: ApiReply): boolean {
+	const message = readAttribute(trap, "message") ?? "";
+	return (
+		/interrupted/i.test(message) || readAttribute(trap, "category") === "2"
+	);
+}
+
 export interface NativeApiSessionOptions {
 	sink: NativeApiByteSink;
 	/** Host/port label used in error envelopes. */
@@ -366,6 +392,7 @@ export class NativeApiSession {
 	private readonly endpoint: string;
 	private readonly reader = new SentenceReader();
 	private readonly pending = new Map<string, PendingCommand>();
+	private readonly subscriptions = new Map<string, StreamingSubscription>();
 	private tagCounter = 0;
 	private closed = false;
 	private closeError: CentrsError | undefined;
@@ -439,33 +466,51 @@ export class NativeApiSession {
 			return; // untagged async/system notice — no waiter to route to
 		}
 		const waiter = this.pending.get(tag);
-		if (waiter === undefined) {
-			return;
+		if (waiter !== undefined) {
+			switch (reply.type) {
+				case "!re":
+					waiter.records.push(reply);
+					return;
+				case "!trap":
+					waiter.trap = reply;
+					return;
+				case "!empty":
+					return;
+				case "!done": {
+					this.pending.delete(tag);
+					if (waiter.trap) {
+						waiter.reject(this.trapToError(waiter.command, waiter.trap));
+						return;
+					}
+					if (Object.keys(reply.attributes).length > 0) {
+						waiter.records.push(reply);
+					}
+					waiter.resolve(waiter.records);
+					return;
+				}
+				default:
+					return;
+			}
 		}
 
-		switch (reply.type) {
-			case "!re":
-				waiter.records.push(reply);
-				return;
-			case "!trap":
-				waiter.trap = reply;
-				return;
-			case "!empty":
-				return;
-			case "!done": {
-				this.pending.delete(tag);
-				if (waiter.trap) {
-					waiter.reject(this.trapToError(waiter.command, waiter.trap));
+		const subscription = this.subscriptions.get(tag);
+		if (subscription !== undefined) {
+			switch (reply.type) {
+				case "!re":
+					subscription.push(reply);
+					return;
+				case "!trap":
+					subscription.trap(reply);
+					return;
+				case "!empty":
+					return;
+				case "!done":
+					this.subscriptions.delete(tag);
+					subscription.settle();
+					return;
+				default:
 					return;
-				}
-				if (Object.keys(reply.attributes).length > 0) {
-					waiter.records.push(reply);
-				}
-				waiter.resolve(waiter.records);
-				return;
 			}
-			default:
-				return;
 		}
 	}
 
@@ -503,6 +548,11 @@ export class NativeApiSession {
 		for (const waiter of waiters) {
 			waiter.reject(error);
 		}
+		const subscriptions = [...this.subscriptions.values()];
+		this.subscriptions.clear();
+		for (const subscription of subscriptions) {
+			subscription.fail(error);
+		}
 	}
 
 	private nextTag(): string {
@@ -573,6 +623,145 @@ export class NativeApiSession {
 		});
 	}
 
+	/**
+	 * Open a `/listen` subscription and yield each `!re` change frame as it
+	 * arrives (the open-ended follow path; the listen command never sends `!done`
+	 * on its own). The generator ends cleanly when the listen is cancelled:
+	 * - via `options.signal` aborting — the subscription stays registered, so the
+	 *   resulting `interrupted` trap + `!done` are drained and the loop ends
+	 *   without throwing;
+	 * - via the consumer breaking out of the `for await` — `finally` sends
+	 *   `/cancel` best-effort (the subscription is already torn down, so the
+	 *   trap/`!done` are not awaited) and the generator returns.
+	 * A non-`interrupted` trap (e.g. a bad path) or `!fatal`/transport closure
+	 * throws. CHR-grounded (7.23.1): see `commands/api/AGENTS.md`.
+	 */
+	async *listen(
+		command: NativeApiCommand,
+		options: { signal?: AbortSignal; onListening?: () => void } = {},
+	): AsyncGenerator<ApiReply, void, void> {
+		if (this.closed) {
+			throw (
+				this.closeError ??
+				new CentrsError({
+					code: "transport/connection-closed",
+					summary: `The RouterOS API session to ${this.endpoint} is closed.`,
+					remediation: "Open a new connection before listening.",
+				})
+			);
+		}
+		const tag = this.nextTag();
+		const words = this.buildWords(command, tag);
+
+		const queue: ApiReply[] = [];
+		let wake: (() => void) | undefined;
+		let ended = false;
+		let failure: CentrsError | undefined;
+		let trap: ApiReply | undefined;
+		const signalWake = (): void => {
+			const resume = wake;
+			wake = undefined;
+			resume?.();
+		};
+
+		this.subscriptions.set(tag, {
+			command: command.command,
+			push: (reply) => {
+				queue.push(reply);
+				signalWake();
+			},
+			trap: (reply) => {
+				trap = reply;
+			},
+			settle: () => {
+				ended = true;
+				signalWake();
+			},
+			fail: (error) => {
+				failure = error;
+				ended = true;
+				signalWake();
+			},
+		});
+
+		try {
+			this.sink.write(encodeSentence(words));
+		} catch (error) {
+			this.subscriptions.delete(tag);
+			throw error instanceof CentrsError
+				? error
+				: new CentrsError({
+						code: "transport/network",
+						summary: `Failed to open a listen on the RouterOS API connection to ${this.endpoint}.`,
+						remediation: "Retry; confirm the connection is still open.",
+						cause: error,
+					});
+		}
+
+		// The subscription is on the wire — signal "listening established" so callers
+		// can act on a real barrier rather than a blind timer.
+		options.onListening?.();
+
+		const onAbort = (): void => this.cancel(tag);
+		if (options.signal) {
+			if (options.signal.aborted) {
+				this.cancel(tag);
+			} else {
+				options.signal.addEventListener("abort", onAbort, { once: true });
+			}
+		}
+
+		try {
+			for (;;) {
+				if (queue.length > 0) {
+					// Drain the whole batch at once: repeated `shift()` is O(n) per frame
+					// (it shifts every remaining element), so a high-volume listen would
+					// be O(n²). New
+					// frames pushed while we yield land in the freshly emptied queue and
+					// drain on the next pass.
+					const batch = queue.splice(0, queue.length);
+					for (const reply of batch) {
+						yield reply;
+					}
+				} else if (ended) {
+					break;
+				} else {
+					await new Promise<void>((resolve) => {
+						wake = resolve;
+					});
+				}
+			}
+			if (failure) {
+				throw failure;
+			}
+			if (trap && !isInterruptedTrap(trap)) {
+				throw this.trapToError(command.command, trap);
+			}
+		} finally {
+			options.signal?.removeEventListener("abort", onAbort);
+			this.subscriptions.delete(tag);
+			// Consumer broke out early (e.g. --count reached): tell the router to stop.
+			if (!ended && !this.closed) {
+				this.cancel(tag);
+			}
+		}
+	}
+
+	/** Cancel an in-flight `/listen` by its tag (`/cancel =tag=<tag> .tag=<new>`). */
+	private cancel(tag: string): void {
+		if (this.closed) {
+			return;
+		}
+		const cancelTag = this.nextTag();
+		try {
+			this.sink.write(
+				encodeSentence(["/cancel", `=tag=${tag}`, `.tag=${cancelTag}`]),
+			);
+		} catch {
+			// Best effort — the connection may already be gone.
+		}
+	}
+
 	/**
 	 * Authenticate. Uses the combined approach: send name+password; if the
 	 * router answers with a legacy `=ret=` challenge, compute the MD5 response
@@ -607,16 +796,20 @@ export class NativeApiSession {
 		try {
 			this.sink.close();
 		} finally {
+			const closeError = new CentrsError({
+				code: "transport/connection-closed",
+				summary: `The RouterOS API session to ${this.endpoint} was closed by the caller.`,
+				remediation: "Open a new connection before sending more commands.",
+			});
 			const waiters = [...this.pending.values()];
 			this.pending.clear();
 			for (const waiter of waiters) {
-				waiter.reject(
-					new CentrsError({
-						code: "transport/connection-closed",
-						summary: `The RouterOS API session to ${this.endpoint} was closed by the caller.`,
-						remediation: "Open a new connection before sending more commands.",
-					}),
-				);
+				waiter.reject(closeError);
+			}
+			const subscriptions = [...this.subscriptions.values()];
+			this.subscriptions.clear();
+			for (const subscription of subscriptions) {
+				subscription.fail(closeError);
 			}
 		}
 	}

package/src/retrieve-fanout.ts

@@ -32,6 +32,13 @@ import type {
 	FanoutData,
 	FanoutSummary,
 } from "./core/envelope.ts";
+import {
+	defaultFanoutSleep,
+	resolveFanoutConcurrency,
+	runBoundedPool,
+	runWithRetry,
+	summarizeFanout,
+} from "./core/fanout.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
@@ -57,27 +64,6 @@ import {
 	validateRetrieveRequestShape,
 } from "./retrieve.ts";
 
-/** Transport-aware default worker-pool size (REST drops parallel POSTs above ~8). */
-export const RETRIEVE_FANOUT_CONCURRENCY_DEFAULTS: Record<
-	"rest-api" | "native-api",
-	number
-> = {
-	"rest-api": 8,
-	"native-api": 4,
-};
-
-/** Extra attempts after the first try (jittered backoff between them). */
-export const RETRIEVE_FANOUT_MAX_RETRIES = 2;
-
-/** Base backoff in milliseconds; doubled per attempt with up to +base jitter. */
-export const RETRIEVE_FANOUT_BACKOFF_BASE_MS = 200;
-
-/** RouterOS-style codes that are safe to retry under fanout. */
-export const RETRIEVE_FANOUT_RETRYABLE_CODES = [
-	"transport/network",
-	"transport/connection-closed",
-] as const;
-
 export interface RetrieveFanoutOperationMeta {
 	kind: "fanout";
 	group: string;
@@ -176,7 +162,7 @@ export async function retrieveGroup(
 	}
 
 	const execute = internals.execute ?? runResolvedRetrieve;
-	const sleep = internals.sleep ?? defaultSleep;
+	const sleep = internals.sleep ?? defaultFanoutSleep;
 
 	const targets = await runBoundedPool(
 		expansion.targets,
@@ -199,7 +185,11 @@ export async function retrieveGroup(
 			} catch (error) {
 				return buildResolveFailureEnvelope(member.resolution, error);
 			}
-			return runTargetWithRetry(resolved, member.recordIndex, execute, sleep);
+			return runWithRetry<RetrieveEnvelope>(
+				() => execute(resolved, member.recordIndex),
+				(error) => buildRetrieveErrorEnvelopeFromResolved(resolved, error),
+				{ sleep },
+			);
 		},
 	);
 
@@ -251,28 +241,6 @@ export function buildRetrieveFanoutErrorEnvelope(
 	};
 }
 
-/** Resolve and validate the worker-pool size. */
-export function resolveFanoutConcurrency(
-	requested: number | undefined,
-	via: RouterOsProtocol,
-): number {
-	if (requested !== undefined) {
-		if (!Number.isInteger(requested) || requested < 1) {
-			throw new CentrsError({
-				code: "usage/invalid-concurrency",
-				summary: `--concurrency must be an integer >= 1. Received: ${requested}`,
-				remediation: "Pass a positive integer, e.g. `--concurrency 4`.",
-				context: { concurrency: requested },
-			});
-		}
-		return requested;
-	}
-	if (via === "native-api") {
-		return RETRIEVE_FANOUT_CONCURRENCY_DEFAULTS["native-api"];
-	}
-	return RETRIEVE_FANOUT_CONCURRENCY_DEFAULTS["rest-api"];
-}
-
 function resolveFanoutConcurrencyProtocol(
 	request: RetrieveRequest,
 	env: Record<string, string | undefined>,
@@ -292,93 +260,6 @@ function resolveFanoutConcurrencyProtocol(
 	return globalVia;
 }
 
-/**
- * Classify a per-target failure as retryable. Only the locked allowlist
- * retries: generic transport/network failures and dropped/closed connections
- * (including REST 5xx mapped to `transport/connection-closed`). Router-side
- * (`routeros/*`), validation, auth, cdb, target, input, usage, timeout, TLS,
- * connection-refused, and DNS failures are deterministic and never retried.
- */
-export function isRetryableFanoutError(error: unknown): boolean {
-	if (!(error instanceof CentrsError)) {
-		return false;
-	}
-	return (RETRIEVE_FANOUT_RETRYABLE_CODES as readonly string[]).includes(
-		error.code,
-	);
-}
-
-export function summarizeFanout(
-	targets: readonly RetrieveEnvelope[],
-): FanoutSummary {
-	let ok = 0;
-	let failed = 0;
-	for (const target of targets) {
-		if (target.ok) {
-			ok += 1;
-		} else {
-			failed += 1;
-		}
-	}
-	return { total: targets.length, ok, failed };
-}
-
-async function runTargetWithRetry(
-	resolved: ResolvedRetrieveRequest,
-	recordIndex: number,
-	execute: (
-		resolved: ResolvedRetrieveRequest,
-		recordIndex: number,
-	) => Promise<RetrieveSuccessEnvelope>,
-	sleep: (ms: number) => Promise<void>,
-): Promise<RetrieveEnvelope> {
-	let attempt = 0;
-	for (;;) {
-		try {
-			return await execute(resolved, recordIndex);
-		} catch (error) {
-			if (
-				attempt < RETRIEVE_FANOUT_MAX_RETRIES &&
-				isRetryableFanoutError(error)
-			) {
-				attempt += 1;
-				await sleep(backoffMs(attempt));
-				continue;
-			}
-			return buildRetrieveErrorEnvelopeFromResolved(resolved, error);
-		}
-	}
-}
-
-/**
- * Ordered bounded worker pool. Runs `worker` over `items` with at most
- * `concurrency` in flight, returning results in INPUT order regardless of
- * completion order.
- */
-export async function runBoundedPool<I, O>(
-	items: readonly I[],
-	concurrency: number,
-	worker: (item: I, index: number) => Promise<O>,
-): Promise<O[]> {
-	const results = new Array<O>(items.length);
-	let next = 0;
-	const width = Math.max(1, Math.min(concurrency, items.length));
-
-	async function drain(): Promise<void> {
-		for (;;) {
-			const index = next;
-			next += 1;
-			if (index >= items.length) {
-				return;
-			}
-			results[index] = await worker(items[index] as I, index);
-		}
-	}
-
-	await Promise.all(Array.from({ length: width }, () => drain()));
-	return results;
-}
-
 function buildResolveFailureEnvelope(
 	resolution: CdbResolution,
 	error: unknown,
@@ -460,15 +341,6 @@ function commonVia(
 	return via ?? null;
 }
 
-function backoffMs(attempt: number): number {
-	const base = RETRIEVE_FANOUT_BACKOFF_BASE_MS * 2 ** (attempt - 1);
-	return base + Math.floor(Math.random() * RETRIEVE_FANOUT_BACKOFF_BASE_MS);
-}
-
-function defaultSleep(ms: number): Promise<void> {
-	return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
 /**
  * Render a fanout envelope. `json`/`yaml` serialize the whole envelope (lossless
  * against the JSON shape); `text` renders a fanout summary line plus one line

package/src/retrieve.ts

@@ -6,6 +6,15 @@ import type {
 	SettingSource as CoreSettingSource,
 	EnvelopeValidationMeta,
 } from "./core/envelope.ts";
+import {
+	extractCompletionNames,
+	inspectChildren,
+	inspectChildrenOrEmpty,
+	inspectCompletions,
+	isArgumentNode,
+	isCommandNode,
+	pathTokens,
+} from "./core/inspect.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
 import {
 	createProtocolAdapter,
@@ -101,20 +110,6 @@ export type RetrieveSuccessEnvelope = CentrsSuccessEnvelope<
 >;
 export type RetrieveErrorEnvelope = CentrsErrorEnvelope<RetrieveOperationMeta>;
 
-interface InspectChildItem {
-	type?: string;
-	name?: string;
-	"node-type"?: string;
-}
-
-interface InspectCompletionItem {
-	type?: string;
-	name?: string;
-	completion?: string;
-	value?: string;
-	text?: string;
-}
-
 interface RetrieveInspection {
 	command: "get" | "print";
 }
@@ -876,41 +871,19 @@ function resolveFormat(
 }
 
 /**
- * Path-existence probe. An invalid path raises a native trap that
- * {@link mapRouterOsError} normalizes to `routeros/unknown-path` (REST instead
- * returns an empty child list). Both the legacy `routeros/api-trap` catch-all
- * and the grounded `routeros/unknown-path` classification are flattened to an
- * empty list so the orchestrator surfaces a single `validation/unknown-path`.
- * Traps during attribute/completion discovery do NOT use this probe — they
- * surface as-is.
+ * Resolve the read command (`print` vs `get`) for a path via a `request=child`
+ * existence probe. Uses {@link inspectChildrenOrEmpty} so an invalid path (a
+ * native trap, or REST's empty child list) flattens to no children and surfaces
+ * as a single `validation/unknown-path` here rather than leaking a transport
+ * trap. Attribute/completion discovery does NOT use the swallowing probe — traps
+ * there surface as-is.
  */
-async function inspectChildrenForProbe(
-	backend: ProtocolAdapter,
-	path: string,
-): Promise<unknown[]> {
-	try {
-		return await backend.inspect("child", path);
-	} catch (error) {
-		if (
-			error instanceof CentrsError &&
-			(error.code === "routeros/api-trap" ||
-				error.code === "routeros/unknown-path")
-		) {
-			return [];
-		}
-		throw error;
-	}
-}
-
 async function inspectRetrievePath(
 	resolved: ResolvedRetrieveRequest,
 	backend: ProtocolAdapter,
 ): Promise<RetrieveInspection> {
-	const pathTokens = pathTokensForInspect(resolved.path);
-	const rootChildren = (await inspectChildrenForProbe(
-		backend,
-		pathToInspectString(pathTokens),
-	)) as InspectChildItem[];
+	const tokens = pathTokens(resolved.path);
+	const rootChildren = await inspectChildrenOrEmpty(backend, tokens);
 
 	const supportsPrint = rootChildren.some((child) =>
 		isCommandNode(child, "print"),
@@ -943,21 +916,24 @@ async function inspectAttributes(
 	inspection: RetrieveInspection,
 	backend: ProtocolAdapter,
 ): Promise<string[]> {
-	const pathTokens = pathTokensForInspect(resolved.path);
+	const tokens = pathTokens(resolved.path);
 	const argument = inspection.command === "get" ? "value-name" : "proplist";
-	const completionRows = (await backend.inspect(
-		"completion",
-		pathToInspectString([...pathTokens, inspection.command, argument]),
-	)) as InspectCompletionItem[];
-	const completions = extractCompletionNames(completionRows);
+	const completionRows = await inspectCompletions(backend, [
+		...tokens,
+		inspection.command,
+		argument,
+	]);
+	const completions = [
+		...new Set(extractCompletionNames(completionRows)),
+	].sort();
 	if (completions.length > 0) {
 		return completions;
 	}
 
-	const commandChildren = (await backend.inspect(
-		"child",
-		pathToInspectString([...pathTokens, inspection.command]),
-	)) as InspectChildItem[];
+	const commandChildren = await inspectChildren(backend, [
+		...tokens,
+		inspection.command,
+	]);
 	return commandChildren
 		.filter(isArgumentNode)
 		.map((child) => child.name)
@@ -985,35 +961,6 @@ async function executeRetrieve(
 	});
 }
 
-function pathTokensForInspect(path: string): string[] {
-	return path.split("/").filter(Boolean);
-}
-
-function isCommandNode(
-	child: InspectChildItem,
-	name: "get" | "print",
-): boolean {
-	return (
-		child.name === name &&
-		(child.type === "cmd" || child["node-type"] === "cmd")
-	);
-}
-
-function isArgumentNode(child: InspectChildItem): boolean {
-	return child.type === "arg" || child["node-type"] === "arg";
-}
-
-function extractCompletionNames(
-	rows: readonly InspectCompletionItem[],
-): string[] {
-	const names = rows
-		.flatMap((row) => [row.completion, row.name, row.value, row.text])
-		.filter((value): value is string => typeof value === "string")
-		.map((value) => value.replace(/=.*$/, "").trim())
-		.filter((value) => value.length > 0);
-	return [...new Set(names)].sort();
-}
-
 function isKnownSingletonPath(path: string): boolean {
 	return ["/system/resource", "/system/identity"].includes(
 		path.replace(/\/$/, ""),
@@ -1122,10 +1069,6 @@ function parseOutputFormat(value: string): RetrieveOutputFormat {
 	});
 }
 
-function pathToInspectString(path: readonly string[]): string {
-	return path.join(",");
-}
-
 function countResultObjects(data: unknown): number {
 	if (Array.isArray(data)) {
 		return data.length;