@tikoci/centrs 0.1.0 → 0.1.2

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,

package/src/protocols/adapter.ts

@@ -106,6 +106,54 @@ export interface ProtocolExecuteResult {
 	ret?: string;
 }
 
+/**
+ * RouterOS verb the `api` orchestrator resolved from the HTTP method (the gh-api
+ * `-X` map: `GET`→print, `PUT`→add, `PATCH`→set, `DELETE`→remove, `POST`→run).
+ * `print` covers list, get-singleton, and get-one (disambiguated by `id`).
+ */
+export type ApiVerb = "print" | "add" | "set" | "remove" | "run";
+
+/**
+ * A normalized `api` request the orchestrator hands to a transport. It is
+ * transport-agnostic: the REST adapter maps the verb to an HTTP method + URL
+ * (id-in-path, `.query`/`.proplist` body), the native adapter maps it to a
+ * tagged `talk` (`=.id=`, `?`-prefixed queries, `=.proplist=`). The orchestrator
+ * owns method→verb, validation, and the write gate; the adapter only executes.
+ */
+export interface ProtocolApiRequest {
+	verb: ApiVerb;
+	/** Slash path without id, e.g. `/ip/address`. For `run`, the command target (`/interface/monitor-traffic`); ignored when `script` is set. */
+	path: string;
+	/** Object id (`*1`) for get-one/set/remove — REST puts it in the URL, native in `=.id=`. */
+	id?: string;
+	/** Body fields (string values), the JSON object for add/set or the args for a `run` command. */
+	attributes?: Record<string, string>;
+	/** Row filter in REST `.query` form (no leading `?`), e.g. `["type=ether", "#!"]`; native prefixes each with `?`. */
+	query?: readonly string[];
+	/** Property projection → REST `.proplist` / native `=.proplist=`. */
+	proplist?: readonly string[];
+	/** Raw console line for the `/execute` script form (`run`); when set, `path`/`attributes` are ignored. */
+	script?: string;
+}
+
+/** Result of an `apiRequest` round-trip: the response body shaped for the envelope. */
+export interface ProtocolApiResult {
+	/** REST returns the body verbatim (array / object / scalar); native re-maps `!re` records to the same rest-style shape. */
+	data: unknown;
+}
+
+/** Options for an open-ended `listen` follow. */
+export interface ProtocolListenOptions {
+	/** Abort the listen (sends `/cancel`); the generator then ends cleanly. */
+	signal?: AbortSignal;
+	/**
+	 * Fired once the subscription is on the wire (connection up, listen sentence
+	 * written) — a real "listening" barrier for callers/tests that must act only
+	 * after the follow is established, instead of a blind timer.
+	 */
+	onListening?: () => void;
+}
+
 /**
  * Runtime transport seam. The orchestrator drives validation and data fetch
  * through these operations so REST and native-api share the same pipeline and
@@ -124,6 +172,18 @@ export interface ProtocolAdapter {
 	list(path: string, options: RetrieveListOptions): Promise<unknown[]>;
 	/** Run a CLI-shaped command (WP-1c write surface). */
 	execute(request: ProtocolExecuteRequest): Promise<ProtocolExecuteResult>;
+	/** Run a normalized structured `api` request (the gh-api passthrough surface). */
+	apiRequest(request: ProtocolApiRequest): Promise<ProtocolApiResult>;
+	/**
+	 * Open-ended `/listen` follow (native-api only). Yields one rest-style change
+	 * record per `!re` frame (deletions carry `.dead`), until cancelled via
+	 * `options.signal` or the consumer stopping. REST and console transports
+	 * reject with `transport/capability-unsupported`.
+	 */
+	listen(
+		request: ProtocolApiRequest,
+		options: ProtocolListenOptions,
+	): AsyncIterable<Record<string, unknown>>;
 	/** Release any underlying connection. Safe to call when never connected. */
 	close(): Promise<void>;
 }
@@ -207,10 +267,105 @@ class RestAdapter implements ProtocolAdapter {
 		return normalizeRestExecute(data);
 	}
 
+	async apiRequest(request: ProtocolApiRequest): Promise<ProtocolApiResult> {
+		const base = request.path.replace(/\/$/, "");
+		switch (request.verb) {
+			case "print": {
+				const hasQuery = (request.query?.length ?? 0) > 0;
+				const hasProplist = (request.proplist?.length ?? 0) > 0;
+				if (request.id && !hasQuery && !hasProplist) {
+					// GET one by id: RouterOS REST addresses a single object in the URL.
+					return {
+						data: await this.requestRest("GET", `${base}/${request.id}`),
+					};
+				}
+				if (request.id || hasQuery || hasProplist) {
+					// A GET cannot carry a body, so `.query`/`.proplist` projection (and an
+					// id, folded into `.query` as `.id=`) rides a POST to the `/print`
+					// sub-endpoint — the documented REST idiom, matching native's `?`-words.
+					const data = await this.requestRest(
+						"POST",
+						`${base}/print`,
+						restQueryBody(request),
+					);
+					// An id addresses one row → unwrap to a single object, matching the
+					// GET-by-id shape and native's `?.id=` read.
+					if (request.id && Array.isArray(data)) {
+						return { data: data[0] ?? null };
+					}
+					return { data };
+				}
+				return { data: await this.requestRest("GET", base) };
+			}
+			case "add":
+				return {
+					data: await this.requestRest("PUT", base, request.attributes ?? {}),
+				};
+			case "set":
+				return {
+					data: await this.requestRest(
+						"PATCH",
+						`${base}/${request.id}`,
+						request.attributes ?? {},
+					),
+				};
+			case "remove":
+				return {
+					data: await this.requestRest("DELETE", `${base}/${request.id}`),
+				};
+			case "run": {
+				if (request.script !== undefined) {
+					// Sync script run: `as-string` makes `/rest/execute` block and return the
+					// captured output rather than scheduling an async job (CHR-grounded).
+					const body = await this.requestRest("POST", "/execute", {
+						script: request.script,
+						"as-string": "",
+					});
+					const result = normalizeRestExecute(body);
+					return { data: result.ret ?? result.records };
+				}
+				return {
+					data: await this.requestRest("POST", base, request.attributes ?? {}),
+				};
+			}
+			default:
+				return exhaustiveApiVerb(request.verb);
+		}
+	}
+
+	// REST cannot hold an open-ended follow (the 60s cap); listen is native-only.
+	// biome-ignore lint/correctness/useYield: a throw-only async generator yields nothing.
+	async *listen(): AsyncGenerator<Record<string, unknown>> {
+		throw new CentrsError({
+			code: "transport/capability-unsupported",
+			summary: "REST cannot follow an open-ended `--stream` (60s cap).",
+			remediation:
+				"Open-ended follow is native-api only: use `--via native-api`, or drop `--stream` for a bounded one-shot.",
+			context: { protocol: this.protocol, capability: "listen" },
+		});
+	}
+
 	async close(): Promise<void> {
 		// REST is stateless; nothing to release.
 	}
 
+	private async requestRest(
+		method: string,
+		path: string,
+		body?: Record<string, unknown>,
+	): Promise<unknown> {
+		const init: RequestInit =
+			body === undefined
+				? { method }
+				: {
+						method,
+						body: JSON.stringify(body),
+						headers: { "Content-Type": "application/json" },
+					};
+		const response = await this.fetchRest(path, init);
+		return response.data;
+	}
+
 	private async restGet(path: string): Promise<unknown> {
 		const response = await this.fetchRest(path, { method: "GET" });
 		return response.data;
@@ -472,6 +627,110 @@ class NativeApiAdapter implements ProtocolAdapter {
 		return { records: repliesToRecords(replies) };
 	}
 
+	async apiRequest(request: ProtocolApiRequest): Promise<ProtocolApiResult> {
+		const base = request.path.replace(/\/$/, "");
+		switch (request.verb) {
+			case "print": {
+				const command: NativeApiCommand = { command: `${base}/print` };
+				const queries: string[] = [];
+				// REST `.query` words map 1:1 to native `?`-prefixed words (CHR-grounded).
+				for (const word of request.query ?? []) {
+					queries.push(`?${word}`);
+				}
+				// No native get-one-by-id shorthand: address a single row with `?.id=`.
+				if (request.id) {
+					queries.push(`?.id=${request.id}`);
+				}
+				if (queries.length > 0) {
+					command.queries = queries;
+				}
+				if (request.proplist && request.proplist.length > 0) {
+					command.proplist = request.proplist;
+				}
+				const records = repliesToRecords(await this.talk(command));
+				return { data: request.id ? (records[0] ?? null) : records };
+			}
+			case "add": {
+				const records = repliesToRecords(
+					await this.talk({
+						command: `${base}/add`,
+						attributes: request.attributes ?? {},
+					}),
+				);
+				return { data: restStyleMutationData(records) };
+			}
+			case "set": {
+				const records = repliesToRecords(
+					await this.talk({
+						command: `${base}/set`,
+						attributes: {
+							...(request.attributes ?? {}),
+							".id": request.id ?? "",
+						},
+					}),
+				);
+				return { data: restStyleMutationData(records) };
+			}
+			case "remove": {
+				const records = repliesToRecords(
+					await this.talk({
+						command: `${base}/remove`,
+						attributes: { ".id": request.id ?? "" },
+					}),
+				);
+				return { data: restStyleMutationData(records) };
+			}
+			case "run": {
+				if (request.script !== undefined) {
+					// `as-string` makes `/execute` run synchronously and return the captured
+					// output; without it the native API schedules a job and returns its id
+					// (CHR-grounded — mirrors REST `/rest/execute`).
+					const records = repliesToRecords(
+						await this.talk({
+							command: "/execute",
+							attributes: { script: request.script, "as-string": "" },
+						}),
+					);
+					return { data: restStyleRunData(records) };
+				}
+				const command: NativeApiCommand = { command: base };
+				if (request.attributes && Object.keys(request.attributes).length > 0) {
+					command.attributes = request.attributes;
+				}
+				return { data: repliesToRecords(await this.talk(command)) };
+			}
+			default:
+				return exhaustiveApiVerb(request.verb);
+		}
+	}
+
+	async *listen(
+		request: ProtocolApiRequest,
+		options: ProtocolListenOptions,
+	): AsyncGenerator<Record<string, unknown>> {
+		const base = request.path.replace(/\/$/, "");
+		const command: NativeApiCommand = { command: `${base}/listen` };
+		// A listen can filter which changes it follows with the same `?`-words /
+		// `=.proplist=` as print (REST `.query` word == native `?`-word minus `?`).
+		const queries = (request.query ?? []).map((word) => `?${word}`);
+		// An addressed row (`ip/address/*1 --stream`) follows just that row, the
+		// same `?.id=` mapping one-shot native reads use.
+		if (request.id) {
+			queries.push(`?.id=${request.id}`);
+		}
+		if (queries.length > 0) {
+			command.queries = queries;
+		}
+		if (request.proplist && request.proplist.length > 0) {
+			command.proplist = request.proplist;
+		}
+		const session = await this.connect();
+		for await (const reply of session.listen(command, options)) {
+			// Each `!re` becomes a rest-style record (string values; `.dead` preserved).
+			yield { ...reply.attributes };
+		}
+	}
+
 	async close(): Promise<void> {
 		this.session?.close();
 		this.session = undefined;
@@ -614,6 +873,15 @@ class MacTelnetAdapter implements ProtocolAdapter {
 		return { records: [], ret: output };
 	}
 
+	apiRequest(): Promise<ProtocolApiResult> {
+		return Promise.reject(this.unsupported("structured api requests"));
+	}
+
+	// biome-ignore lint/correctness/useYield: a reject-only async generator yields nothing.
+	async *listen(): AsyncGenerator<Record<string, unknown>> {
+		throw this.unsupported("open-ended listen streaming");
+	}
+
 	async close(): Promise<void> {
 		this.console?.close();
 		this.transport?.close();
@@ -756,11 +1024,71 @@ class SshExecAdapter implements ProtocolAdapter {
 		return { records: [], ret: output };
 	}
 
+	apiRequest(): Promise<ProtocolApiResult> {
+		return Promise.reject(this.unsupported("structured api requests"));
+	}
+
+	// biome-ignore lint/correctness/useYield: a reject-only async generator yields nothing.
+	async *listen(): AsyncGenerator<Record<string, unknown>> {
+		throw this.unsupported("open-ended listen streaming");
+	}
+
 	close(): Promise<void> {
 		return Promise.resolve();
 	}
 }
 
+/** REST `.query` / `.proplist` projection body for a POST `/print`. */
+function restQueryBody(request: ProtocolApiRequest): Record<string, unknown> {
+	const body: Record<string, unknown> = {};
+	// Fold an id into `.query` as `.id=<id>` so id+query/proplist reads work over
+	// REST exactly as they do over native (`?.id=` plus the `?`-words).
+	const query = [
+		...(request.id ? [`.id=${request.id}`] : []),
+		...(request.query ?? []),
+	];
+	if (query.length > 0) {
+		body[".query"] = query;
+	}
+	if (request.proplist && request.proplist.length > 0) {
+		body[".proplist"] = request.proplist;
+	}
+	return body;
+}
+
+/**
+ * Re-map a native add/set/remove reply to the rest-style shape. `add` returns the
+ * new id in `=ret=`; surface it as `{".id": ret}` (REST returns the created
+ * object with `.id`). `set`/`remove` reply with a bare `!done` (no records) → no
+ * meaningful body, mirrored as `null`.
+ */
+function restStyleMutationData(
+	records: readonly Record<string, string>[],
+): unknown {
+	if (records.length === 0) {
+		return null;
+	}
+	const record = records[0] ?? {};
+	const ret = record["ret"];
+	if (typeof ret === "string" && /^\*[0-9A-F]+$/i.test(ret)) {
+		return { ".id": ret };
+	}
+	return records.length === 1 ? record : records;
+}
+
+/** Re-map a native `/execute` reply: prefer the captured `ret` string, else the records. */
+function restStyleRunData(records: readonly Record<string, string>[]): unknown {
+	const ret = records.length === 1 ? records[0]?.["ret"] : undefined;
+	if (typeof ret === "string") {
+		return ret;
+	}
+	return records.length === 1 ? records[0] : records;
+}
+
+function exhaustiveApiVerb(verb: never): never {
+	throw new Error(`Unhandled api verb: ${String(verb)}`);
+}
+
 function normalizeRestExecute(data: unknown): ProtocolExecuteResult {
 	if (Array.isArray(data)) {
 		return { records: data.filter(isPlainObject) as Record<string, string>[] };