@tikoci/centrs 0.1.1 → 0.1.2

package/src/cli.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 
+import { apiCommand, runApiCli } from "./cli/api.ts";
 import { btestCommand, runBtestCli } from "./cli/btest.ts";
 import { devicesCommand, runDevicesCli } from "./cli/devices.ts";
 import { discoverCommand, runDiscoverCli } from "./cli/discover.ts";
@@ -14,6 +15,7 @@ import { describeCentrs, plannedProtocols, plannedSurfaces } from "./index.ts";
 const commandSummaries: ReadonlyArray<{ name: string; summary: string }> = [
 	retrieveCommand,
 	executeCommand,
+	apiCommand,
 	transferCommand,
 	terminalCommand,
 	devicesCommand,
@@ -54,6 +56,9 @@ export async function runCli(
 		if (command === "execute") {
 			return await runExecuteCli(rest);
 		}
+		if (command === "api") {
+			return await runApiCli(rest);
+		}
 		if (command === "transfer") {
 			return await runTransferCli(rest);
 		}
@@ -80,6 +85,23 @@ export async function runCli(
 		if (command === "mcp") {
 			return await runMcpCli(rest);
 		}
+		// `stream` (and the `tail` shorthand) folded into `api --stream`.
+		if (command === "stream" || command === "tail") {
+			console.error(
+				formatCentrsErrorText(
+					asCentrsError(
+						new Error(`\`centrs ${command}\` has been folded into \`api\`.`),
+						{
+							code: "input/invalid-command",
+							summary: `\`centrs ${command}\` is no longer a command — open-ended follow is now \`api … --stream\`.`,
+							remediation:
+								"Use `centrs api <router> <endpoint> --stream` (native-api only), e.g. `centrs api edge1 ip/address --stream`.",
+						},
+					),
+				),
+			);
+			return 1;
+		}
 
 		console.error(
 			formatCentrsErrorText(

package/src/core/error-catalog.ts

@@ -218,6 +218,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		summary:
 			"The RouterOS native API returned a !trap with no more specific mapping.",
 	},
+	{
+		code: "routeros/btest-connection-count-single-stream",
+		summary:
+			"Fewer TCP data connections were opened than --connection-count requested (e.g. authenticated multi-connection is not yet supported), so throughput will not scale to the full count.",
+	},
 	{
 		code: "routeros/btest-protocol",
 		summary: "A bandwidth-test (btest) packet could not be decoded.",
@@ -227,6 +232,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		summary:
 			"The btest server refused a client because max-sessions is reached.",
 	},
+	{
+		code: "routeros/btest-udp-tx-size-ignored",
+		summary:
+			"For UDP --direction both, the btest wire protocol carries a single tx-size; --remote-udp-tx-size is ignored and --local-udp-tx-size is used for both directions.",
+	},
 	{
 		code: "routeros/command-failed",
 		summary: "RouterOS reported a command failure.",
@@ -415,6 +425,10 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "usage/invalid-concurrency",
 		summary: "The --concurrency value must be an integer >= 1.",
 	},
+	{
+		code: "usage/invalid-method",
+		summary: "The -X/--method value is not a supported HTTP method.",
+	},
 	{
 		code: "usage/missing-group",
 		summary: "The operation requires a non-empty --group value.",

package/src/core/fanout.ts

@@ -0,0 +1,160 @@
+/**
+ * Transport-agnostic fan-out engine.
+ *
+ * `retrieve` group fan-out (`src/retrieve-fanout.ts`) grew the reusable
+ * machinery: a bounded worker pool, transport-aware concurrency defaults, a
+ * retry allowlist with jittered backoff, and the ok/failed summary. `api` — and
+ * any later fan-out command — needs the identical behavior, so it lives here as
+ * one vocabulary. The command-specific orchestration (CDB group expansion,
+ * per-target resolve, envelope shaping, text rendering) stays in each command's
+ * fan-out module; this core only knows about generic items, concurrency, retry,
+ * and counting.
+ */
+
+import { CentrsError } from "../errors.ts";
+import type { RouterOsProtocol } from "../protocols/index.ts";
+import type { FanoutSummary } from "./envelope.ts";
+
+/** Transport-aware default worker-pool size (REST drops parallel POSTs above ~8). */
+export const 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 FANOUT_MAX_RETRIES = 2;
+
+/** Base backoff in milliseconds; doubled per attempt with up to +base jitter. */
+export const FANOUT_BACKOFF_BASE_MS = 200;
+
+/** RouterOS-style codes that are safe to retry under fan-out. */
+export const FANOUT_RETRYABLE_CODES = [
+	"transport/network",
+	"transport/connection-closed",
+] as const;
+
+/** 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 FANOUT_CONCURRENCY_DEFAULTS["native-api"];
+	}
+	return FANOUT_CONCURRENCY_DEFAULTS["rest-api"];
+}
+
+/**
+ * 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 (FANOUT_RETRYABLE_CODES as readonly string[]).includes(error.code);
+}
+
+/** Count inner `ok`/`failed` across a completed target set. */
+export function summarizeFanout(
+	targets: readonly { ok: boolean }[],
+): 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 };
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Run `run`, retrying only {@link isRetryableFanoutError} failures up to
+ * `maxRetries` times with jittered backoff. A non-retryable error, or the final
+ * exhausted attempt, is converted to a value via `recover` (so a fan-out target
+ * yields an inner error envelope instead of throwing out of the batch).
+ */
+export async function runWithRetry<T>(
+	run: () => Promise<T>,
+	recover: (error: unknown) => T,
+	options: {
+		sleep?: (ms: number) => Promise<void>;
+		maxRetries?: number;
+	} = {},
+): Promise<T> {
+	const sleep = options.sleep ?? defaultFanoutSleep;
+	const maxRetries = options.maxRetries ?? FANOUT_MAX_RETRIES;
+	let attempt = 0;
+	for (;;) {
+		try {
+			return await run();
+		} catch (error) {
+			if (attempt < maxRetries && isRetryableFanoutError(error)) {
+				attempt += 1;
+				await sleep(fanoutBackoffMs(attempt));
+				continue;
+			}
+			return recover(error);
+		}
+	}
+}
+
+/** Backoff for attempt N: base·2^(N-1) plus up to +base jitter. */
+export function fanoutBackoffMs(attempt: number): number {
+	const base = FANOUT_BACKOFF_BASE_MS * 2 ** (attempt - 1);
+	return base + Math.floor(Math.random() * FANOUT_BACKOFF_BASE_MS);
+}
+
+/** Real timer sleep; tests inject a no-op. */
+export function defaultFanoutSleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/core/inspect.ts

@@ -0,0 +1,170 @@
+/**
+ * Shared `/console/inspect` client primitives.
+ *
+ * `retrieve` and `execute` each grew their own private copy of these helpers
+ * (path tokenizing, the comma-path join, node-type predicates, completion-name
+ * extraction). This module is the single home so a third consumer — `api`, and a
+ * future `explain`/`check` — reuses one grounded implementation instead of
+ * forking a fourth. It deliberately holds only the transport-agnostic
+ * *primitives*; each command composes its own discovery strategy on top (their
+ * strategies differ: `retrieve` probes print/get support, `execute` unions
+ * child-args with completions), so the strategy stays in the command.
+ *
+ * Grounding: the request modes mirror `tikoci/lsp-routeros-ts`
+ * (`server/src/routeros.ts` `InspectRequest`). The behavioral facts (the array-
+ * typed `path`, completion shapes) are confirmed on CHR 7.23.1 in
+ * `commands/api/AGENTS.md` — read that before changing wire behavior here.
+ */
+
+import { CentrsError } from "../errors.ts";
+
+/**
+ * The transport seam this module needs. A {@link ProtocolAdapter} satisfies it
+ * structurally; depending on the narrow shape keeps `core/` decoupled from the
+ * protocol layer (no import cycle).
+ */
+export interface InspectBackend {
+	inspect(request: "child" | "completion", path: string): Promise<unknown[]>;
+}
+
+/**
+ * The `/console/inspect` request modes (lsp's `InspectRequest`). Only `child`
+ * and `completion` are wired today (the two the {@link InspectBackend} seam
+ * exposes); `highlight` (token-level error detection) and `syntax` (parse tree),
+ * plus the `input`/`.query`/`.proplist` request fields, are the documented
+ * Phase-2 extension point for value-level validation — widen the adapter seam
+ * when adding them.
+ */
+export type InspectRequestKind =
+	| "child"
+	| "completion"
+	| "highlight"
+	| "syntax";
+
+/** A row from `request=child`: a menu/argument node under a path. */
+export interface InspectChildItem {
+	type?: string;
+	name?: string;
+	"node-type"?: string;
+}
+
+/** A row from `request=completion`: a candidate token for a path/argument. */
+export interface InspectCompletionItem {
+	type?: string;
+	name?: string;
+	completion?: string;
+	value?: string;
+	text?: string;
+}
+
+/**
+ * Split a slash RouterOS path into menu tokens, dropping the leading slash and
+ * empties: `"/ip/address"` → `["ip", "address"]`.
+ */
+export function pathTokens(path: string): string[] {
+	return path.split("/").filter(Boolean);
+}
+
+/**
+ * Join menu tokens into the COMMA form `/console/inspect` expects for its `path`
+ * argument: `["ip", "address"]` → `"ip,address"`.
+ *
+ * The inspect `path` argument is internally a RouterOS *array*: a comma string
+ * is `:toarray`-split into the menu-walk tokens, whereas a `/`-prefixed command
+ * string is not split and matches no menu (confirmed on CHR 7.23.1 — slash forms
+ * return nothing; see `commands/api/AGENTS.md`). So callers must pass tokens
+ * joined by comma, never a slash command.
+ */
+export function inspectPath(tokens: readonly string[]): string {
+	return tokens.join(",");
+}
+
+/** True for an argument (`arg`) node from `request=child`. */
+export function isArgumentNode(child: InspectChildItem): boolean {
+	return child.type === "arg" || child["node-type"] === "arg";
+}
+
+/** True for a command (`cmd`) node with the given name (e.g. `print`, `get`). */
+export function isCommandNode(child: InspectChildItem, name: string): boolean {
+	return (
+		child.name === name &&
+		(child.type === "cmd" || child["node-type"] === "cmd")
+	);
+}
+
+/**
+ * Flatten completion rows into attribute names. Reads every name-like field a
+ * RouterOS build might populate (`completion`/`name`/`value`/`text`), strips
+ * everything from the first `=` onward (the `name=value` completion form), and
+ * drops blanks. Returns the names in row order **without** de-duplication or
+ * sorting — callers that need a stable set wrap with `[...new Set(names)].sort()`
+ * (both current callers do).
+ */
+export function extractCompletionNames(
+	rows: readonly InspectCompletionItem[],
+): string[] {
+	return rows
+		.flatMap((row) => [row.completion, row.name, row.value, row.text])
+		.filter((value): value is string => typeof value === "string")
+		.map((value) => nameBeforeEquals(value).trim())
+		.filter((value) => value.length > 0);
+}
+
+/**
+ * The token before the first `=` in a RouterOS completion row. Plain string
+ * slicing (no regex) — `value.replace(/=.*$/, "")` triggers a CodeQL
+ * polynomial-ReDoS flag on this exported function's caller-supplied input.
+ */
+function nameBeforeEquals(value: string): string {
+	const eq = value.indexOf("=");
+	return eq === -1 ? value : value.slice(0, eq);
+}
+
+/** `request=child` for a token path. */
+export async function inspectChildren(
+	backend: InspectBackend,
+	tokens: readonly string[],
+): Promise<InspectChildItem[]> {
+	return (await backend.inspect(
+		"child",
+		inspectPath(tokens),
+	)) as InspectChildItem[];
+}
+
+/** `request=completion` for a token path. */
+export async function inspectCompletions(
+	backend: InspectBackend,
+	tokens: readonly string[],
+): Promise<InspectCompletionItem[]> {
+	return (await backend.inspect(
+		"completion",
+		inspectPath(tokens),
+	)) as InspectCompletionItem[];
+}
+
+/**
+ * {@link inspectChildren} that swallows a "path not found" trap to an empty
+ * list, so the caller can classify the absence itself (REST returns an empty
+ * child list; native traps). Only the two grounded not-found codes are
+ * swallowed — `routeros/unknown-path` (the classified form) and the legacy
+ * `routeros/api-trap` catch-all; every other error propagates. Use this for the
+ * existence probe, not for attribute/value discovery (where a trap is a real
+ * failure).
+ */
+export async function inspectChildrenOrEmpty(
+	backend: InspectBackend,
+	tokens: readonly string[],
+): Promise<InspectChildItem[]> {
+	try {
+		return await inspectChildren(backend, tokens);
+	} catch (error) {
+		if (
+			error instanceof CentrsError &&
+			(error.code === "routeros/api-trap" ||
+				error.code === "routeros/unknown-path")
+		) {
+			return [];
+		}
+		throw error;
+	}
+}

package/src/execute.ts

@@ -9,6 +9,13 @@ import type {
 	Warning,
 } from "./core/envelope.ts";
 import { buildTip } from "./core/envelope.ts";
+import {
+	extractCompletionNames,
+	inspectChildren,
+	inspectCompletions,
+	isArgumentNode,
+	pathTokens,
+} from "./core/inspect.ts";
 import { mapRouterOsError } from "./core/routeros-errors.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
 import {
@@ -132,20 +139,6 @@ export interface ResolvedExecuteRequest {
 	warnings: readonly Warning[];
 }
 
-interface InspectChildItem {
-	type?: string;
-	name?: string;
-	"node-type"?: string;
-}
-
-interface InspectCompletionItem {
-	type?: string;
-	name?: string;
-	completion?: string;
-	value?: string;
-	text?: string;
-}
-
 export async function execute(
 	request: ExecuteRequest,
 	env: Record<string, string | undefined> = Bun.env,
@@ -735,24 +728,18 @@ async function inspectExecuteAttributes(
 	resolved: ResolvedExecuteRequest,
 	backend: ProtocolAdapter,
 ): Promise<string[]> {
-	const commandPath = inspectPath([
+	const commandTokens = [
 		...pathTokens(resolved.canonical.path),
 		resolved.canonical.verb,
-	]);
-	const children = (await backend.inspect(
-		"child",
-		commandPath,
-	)) as InspectChildItem[];
+	];
+	const children = await inspectChildren(backend, commandTokens);
 	const childAttributes = children
 		.filter(isArgumentNode)
 		.map((child) => child.name)
 		.filter(
 			(name): name is string => typeof name === "string" && name.length > 0,
 		);
-	const completionRows = (await backend.inspect(
-		"completion",
-		commandPath,
-	)) as InspectCompletionItem[];
+	const completionRows = await inspectCompletions(backend, commandTokens);
 	return [
 		...new Set([...childAttributes, ...extractCompletionNames(completionRows)]),
 	].sort();
@@ -819,7 +806,9 @@ async function assertWriteConfirmed(
 	});
 }
 
-async function promptForWriteConfirmation(prompt: string): Promise<boolean> {
+export async function promptForWriteConfirmation(
+	prompt: string,
+): Promise<boolean> {
 	process.stderr.write(prompt);
 	for await (const chunk of Bun.stdin.stream()) {
 		const answer = new TextDecoder().decode(chunk).trim().toLowerCase();
@@ -1299,28 +1288,6 @@ function syntaxCause(error: unknown): unknown {
 	return error;
 }
 
-function pathTokens(path: string): string[] {
-	return path.split("/").filter(Boolean);
-}
-
-function inspectPath(tokens: readonly string[]): string {
-	return tokens.join(",");
-}
-
-function isArgumentNode(child: InspectChildItem): boolean {
-	return child.type === "arg" || child["node-type"] === "arg";
-}
-
-function extractCompletionNames(
-	rows: readonly InspectCompletionItem[],
-): string[] {
-	return 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);
-}
-
 function parseOutputFormat(value: string): ExecuteOutputFormat {
 	if (executeOutputFormats.includes(value as ExecuteOutputFormat)) {
 		return value as ExecuteOutputFormat;

package/src/index.ts

@@ -1,5 +1,38 @@
 export const centrsVersion = "0.1.0";
 
+export {
+	type ApiEnvelope,
+	type ApiErrorEnvelope,
+	type ApiMethod,
+	type ApiOperationMeta,
+	type ApiOutputFormat,
+	type ApiRequest,
+	type ApiRequestSummary,
+	type ApiStreamMeta,
+	type ApiStreamStopReason,
+	type ApiStreamSummary,
+	type ApiSuccessEnvelope,
+	api,
+	apiEnvelope,
+	apiListen,
+	apiMethods,
+	apiOutputFormats,
+	buildApiBody,
+	buildApiErrorEnvelope,
+	buildApiErrorEnvelopeFromResolved,
+	buildApiQuery,
+	buildProtocolApiRequest,
+	isApiMutating,
+	mapMethodToVerb,
+	type NormalizedApiEndpoint,
+	normalizeApiEndpoint,
+	type ResolvedApiRequest,
+	renderApiEnvelope,
+	renderApiStreamLine,
+	resolveApiRequest,
+	runResolvedApi,
+	validateApiRequestShape,
+} from "./api.ts";
 export {
 	BTEST_CLIENT_CSV_HEADER,
 	BTEST_SERVER_CSV_HEADER,
@@ -41,6 +74,31 @@ export {
 	type SettingSourceKind,
 	type Warning,
 } from "./core/envelope.ts";
+export {
+	FANOUT_BACKOFF_BASE_MS,
+	FANOUT_CONCURRENCY_DEFAULTS,
+	FANOUT_MAX_RETRIES,
+	FANOUT_RETRYABLE_CODES,
+	isRetryableFanoutError,
+	resolveFanoutConcurrency,
+	runBoundedPool,
+	runWithRetry,
+	summarizeFanout,
+} from "./core/fanout.ts";
+export {
+	extractCompletionNames,
+	type InspectBackend,
+	type InspectChildItem,
+	type InspectCompletionItem,
+	type InspectRequestKind,
+	inspectChildren,
+	inspectChildrenOrEmpty,
+	inspectCompletions,
+	inspectPath,
+	isArgumentNode,
+	isCommandNode,
+	pathTokens,
+} from "./core/inspect.ts";
 export {
 	encodeMndpPacket,
 	MNDP_BROADCAST_ADDRESS,
@@ -185,11 +243,14 @@ export {
 	validateExecuteRequestShape,
 } from "./execute.ts";
 export {
+	type ApiVerb,
 	createProtocolAdapter,
 	getProtocolPlan,
 	type ProtocolAdapter,
 	type ProtocolAdapterCapabilities,
 	type ProtocolAdapterConfig,
+	type ProtocolApiRequest,
+	type ProtocolApiResult,
 	type ProtocolCapability,
 	type ProtocolExecuteRequest,
 	type ProtocolExecuteResult,
@@ -262,21 +323,13 @@ export {
 } from "./retrieve.ts";
 export {
 	buildRetrieveFanoutErrorEnvelope,
-	isRetryableFanoutError,
-	RETRIEVE_FANOUT_BACKOFF_BASE_MS,
-	RETRIEVE_FANOUT_CONCURRENCY_DEFAULTS,
-	RETRIEVE_FANOUT_MAX_RETRIES,
-	RETRIEVE_FANOUT_RETRYABLE_CODES,
 	type RetrieveFanoutData,
 	type RetrieveFanoutEnvelope,
 	type RetrieveFanoutErrorEnvelope,
 	type RetrieveFanoutOperationMeta,
 	type RetrieveGroupInternals,
 	renderRetrieveFanoutEnvelope,
-	resolveFanoutConcurrency,
 	retrieveGroup,
-	runBoundedPool,
-	summarizeFanout,
 } from "./retrieve-fanout.ts";
 export {
 	buildSshTerminalArgv,