@tikoci/centrs 0.1.8 → 0.1.9-next.0

package/src/execute-fanout.ts

@@ -33,6 +33,7 @@ import {
 	buildFanoutResolveFailure,
 	commonVia,
 	defaultFanoutSleep,
+	mayRetryUnsentWrite,
 	resolveFanoutConcurrency,
 	runFanout,
 	summarizeFanout,
@@ -105,6 +106,7 @@ export interface ExecuteFanoutInternals {
 	) => Promise<SelectionExpansion>;
 	execute?: (
 		resolved: ResolvedExecuteRequest,
+		trace: ValidationTrace,
 	) => Promise<ExecuteSuccessEnvelope>;
 	sleep?: (ms: number) => Promise<void>;
 }
@@ -308,6 +310,8 @@ export async function executeFanout(
 				),
 				member,
 			),
+		mayRetry: (resolved) =>
+			mayRetryUnsentWrite(global.summary.write, traces.get(resolved)),
 		sleep,
 	});
 

package/src/execute.ts

@@ -1,3 +1,9 @@
+import {
+	assertNotCmrDashboardIl,
+	assertNotCmrDashboardPath,
+	cmrRunScriptWarnings,
+	cmrScriptWarnings,
+} from "./core/cmr.ts";
 import type {
 	CentrsEnvelope,
 	CentrsErrorEnvelope,
@@ -16,6 +22,7 @@ import {
 	canonicalizeExecuteCommand,
 	isWriteShaped,
 } from "./core/execute-command.ts";
+import { sentWriteWarnings } from "./core/fanout.ts";
 import { inspectArgumentNames, pathTokens } from "./core/inspect.ts";
 import { mapRouterOsResultError } from "./core/routeros-errors.ts";
 import { routerOsStringLiteral } from "./core/routeros-string.ts";
@@ -37,6 +44,7 @@ import {
 	getProtocolPlan,
 	type ProtocolAdapter,
 	type ProtocolExecuteResult,
+	type ProtocolSendOptions,
 	plannedProtocols,
 	type RouterOsProtocol,
 } from "./protocols/index.ts";
@@ -288,7 +296,11 @@ export async function runResolvedExecute(
 		// reports the gate that actually passed rather than a guess.
 		trace.validation = validation;
 
-		const result = await runCommand(resolved, backend);
+		const result = await runCommand(resolved, backend, {
+			onSent: () => {
+				trace.dispatched = true;
+			},
+		});
 		const routerOsFailure = routerOsFailureFromResult(
 			result,
 			resolved.via.value,
@@ -319,6 +331,7 @@ export async function resolveExecuteRequest(
 ): Promise<ResolvedExecuteRequest> {
 	validateExecuteRequestShape(request);
 	const canonical = canonicalizeExecuteCommand(request.command);
+	assertNotStructuredDashboard(canonical);
 	const config = options.config ?? (await loadEnvFileDefaults(env));
 	// A quickchr target is a named-live-provider: it supplies host/port/auth from
 	// the live descriptor and bypasses CDB/env resolution for those fields
@@ -450,9 +463,12 @@ export async function resolveExecuteRequest(
 		maxResultsBytes,
 		yes: request.yes ?? false,
 		verbose: request.verbose ?? false,
-		warnings: connection
-			? [...connection.warnings]
-			: (cdbResolution?.warnings ?? []),
+		warnings: [
+			...(connection ? connection.warnings : (cdbResolution?.warnings ?? [])),
+			...(canonical.mode === "structured"
+				? cmrRunScriptWarnings(`${canonical.path}/${canonical.verb}`)
+				: cmrScriptWarnings(canonical.input)),
+		],
 	};
 }
 
@@ -477,6 +493,7 @@ export function resolveExecuteGlobalContext(
 ): ExecuteGlobalContext {
 	validateExecuteRequestShape(request);
 	const canonical = canonicalizeExecuteCommand(request.command);
+	assertNotStructuredDashboard(canonical);
 	const via = resolveExecuteProtocol(request, env, undefined, config);
 	const format = resolveFormat(request, env, config);
 	const validate = resolveBooleanSetting(
@@ -599,7 +616,14 @@ export function buildExecuteErrorEnvelopeFromResolved(
 	return {
 		ok: false,
 		error: serializeCentrsError(centrsError),
-		warnings: [...resolved.warnings],
+		warnings: [
+			...resolved.warnings,
+			...sentWriteWarnings(
+				isWriteShaped(resolved.canonical),
+				centrsError,
+				trace,
+			),
+		],
 		tips: resolvedExecuteTips(resolved),
 		meta: metaFromResolved(
 			resolved,
@@ -729,7 +753,7 @@ function deviceStageSource(resolved: ResolvedExecuteRequest): string {
  * judge. An absent verdict means the caller did not thread a trace, so say
  * nothing extra rather than invent the reason.
  */
-function offlineStagePassed(
+export function offlineStagePassed(
 	verdict: ValidationTrace["offlineVerdict"],
 ): EnvelopeValidationStage {
 	return {
@@ -748,7 +772,7 @@ function offlineStagePassed(
  * a consumer reading `stages` never has to special-case the disabled shape.
  * `reason` is left off — `enabled: false` already says why.
  */
-function disabledValidationMeta(): EnvelopeValidationMeta {
+export function disabledValidationMeta(): EnvelopeValidationMeta {
 	return {
 		enabled: false,
 		source: "disabled",
@@ -888,6 +912,7 @@ async function validateConsoleParseCommand(
 	});
 	// Throws validation/syntax or validation/unknown-attribute on a bad parse.
 	classifyParseResult(result.ret ?? "", resolved.command, resolved.via.value);
+	assertNotCmrDashboardIl(result.ret ?? "", resolved.command);
 	return {
 		enabled: true,
 		source: `:put [:parse ...] over ${resolved.via.value}`,
@@ -908,7 +933,7 @@ async function validateConsoleParseCommand(
  * `warn` is an abstention, and saying so is the difference between "the analyzer
  * read all of this" and "it declined to judge part of it".
  */
-function passedStages(
+export function passedStages(
 	offline: OfflineGateResult,
 	deviceSource: string,
 ): EnvelopeValidationStage[] {
@@ -939,6 +964,7 @@ export async function validateRouterOsScript(
 	via: RouterOsProtocol,
 ): Promise<void> {
 	const script = `:put [:parse ${routerOsStringLiteral(command)}]`;
+	let il: string;
 	try {
 		// GH#230: `:parse` never throws (CHR 7.23.3). The diagnostic rides the
 		// success value's text — over REST/native the `ret` field (HTTP 200 /
@@ -947,7 +973,8 @@ export async function validateRouterOsScript(
 		// Read the return and classify it: one `:parse` covers syntax and the
 		// unknown-attribute (name-level) gate.
 		const result = await backend.execute({ path: "", command: "", script });
-		classifyParseResult(result.ret ?? "", command, via);
+		il = result.ret ?? "";
+		classifyParseResult(il, command, via);
 	} catch (error) {
 		// The preflight is a syntax gate, but `backend.execute` also surfaces
 		// connection and authentication failures (login happens lazily here).
@@ -984,6 +1011,20 @@ export async function validateRouterOsScript(
 			causeData: syntaxCause(error),
 		});
 	}
+	assertNotCmrDashboardIl(il, command);
+}
+
+/**
+ * The plain spellings of the dashboard are refused before anything is dialed.
+ * Every other spelling (a relative menu change, a block, a substitution) is
+ * found in the `:parse` return, so it is refused by validation.
+ */
+function assertNotStructuredDashboard(
+	canonical: CanonicalExecuteCommand,
+): void {
+	if (canonical.mode === "structured") {
+		assertNotCmrDashboardPath(`${canonical.path}/${canonical.verb}`);
+	}
 }
 
 /**
@@ -998,22 +1039,32 @@ function isPreflightTransportError(error: CentrsError): boolean {
 async function runCommand(
 	resolved: ResolvedExecuteRequest,
 	backend: ProtocolAdapter,
+	options: ProtocolSendOptions,
 ): Promise<ProtocolExecuteResult> {
 	if (resolved.via.value === "mac-telnet" || resolved.via.value === "ssh") {
 		// Console transports: run the raw CLI line and capture the console output
 		// (structured path-POST / tagged talk do not apply). ssh runs it as a
 		// single `ssh host "<command>"`; mac-telnet drives the L2 console.
-		return backend.execute({ path: "", command: "", script: resolved.command });
+		return backend.execute(
+			{ path: "", command: "", script: resolved.command },
+			options,
+		);
 	}
 	if (resolved.canonical.mode === "script") {
-		return backend.execute({ path: "", command: "", script: resolved.command });
+		return backend.execute(
+			{ path: "", command: "", script: resolved.command },
+			options,
+		);
 	}
-	return backend.execute({
-		path: resolved.canonical.path,
-		command: resolved.canonical.verb,
-		attributes: resolved.canonical.attributes,
-		queries: resolved.canonical.queries,
-	});
+	return backend.execute(
+		{
+			path: resolved.canonical.path,
+			command: resolved.canonical.verb,
+			attributes: resolved.canonical.attributes,
+			queries: resolved.canonical.queries,
+		},
+		options,
+	);
 }
 
 async function assertWriteConfirmed(

package/src/index.ts

@@ -286,6 +286,23 @@ export {
 	runResolvedExecute,
 	validateExecuteRequestShape,
 } from "./execute.ts";
+export {
+	buildExecuteCmrErrorEnvelope,
+	CMR_VALIDATION_SOURCE,
+	type CmrController,
+	type CmrDevice,
+	type CmrScriptCall,
+	type CmrScriptOutcome,
+	type CmrScriptRow,
+	type ExecuteCmrData,
+	type ExecuteCmrEnvelope,
+	type ExecuteCmrErrorEnvelope,
+	type ExecuteCmrInternals,
+	type ExecuteCmrOperationMeta,
+	type ExecuteCmrRequest,
+	executeCmr,
+	renderExecuteCmrEnvelope,
+} from "./execute-cmr.ts";
 export {
 	buildExecuteFanoutErrorEnvelope,
 	type ExecuteFanoutData,

package/src/protocols/adapter.ts

@@ -180,6 +180,16 @@ export interface ProtocolApiResult {
 	data: unknown;
 }
 
+/**
+ * Options for a single `execute`/`apiRequest` call. `onSent` fires once the
+ * command itself is about to leave for the router: after a native or console
+ * login, never during it. A failure before it fired cannot have run the
+ * command (#448).
+ */
+export interface ProtocolSendOptions {
+	onSent?: () => void;
+}
+
 /** Options for incremental native command replies. */
 export interface ProtocolListenOptions {
 	/** Abort the listen (sends `/cancel`); the generator then ends cleanly. */
@@ -237,9 +247,15 @@ export interface ProtocolAdapter {
 	/** Read a menu as an array of records, optionally projected/detailed. */
 	list(path: string, options: RetrieveListOptions): Promise<unknown[]>;
 	/** Run a CLI-shaped command (WP-1c write surface). */
-	execute(request: ProtocolExecuteRequest): Promise<ProtocolExecuteResult>;
+	execute(
+		request: ProtocolExecuteRequest,
+		options?: ProtocolSendOptions,
+	): Promise<ProtocolExecuteResult>;
 	/** Run a normalized structured `api` request (the gh-api passthrough surface). */
-	apiRequest(request: ProtocolApiRequest): Promise<ProtocolApiResult>;
+	apiRequest(
+		request: ProtocolApiRequest,
+		options?: ProtocolSendOptions,
+	): Promise<ProtocolApiResult>;
 	/**
 	 * Incremental native replies to the literal command (the same mapping as
 	 * `apiRequest`; never rewritten into a `listen`). Yields each `!re` and
@@ -341,7 +357,10 @@ class RestAdapter implements ProtocolAdapter {
 
 	async execute(
 		request: ProtocolExecuteRequest,
+		options?: ProtocolSendOptions,
 	): Promise<ProtocolExecuteResult> {
+		// REST has no session to open first: the request is the command.
+		options?.onSent?.();
 		if (request.script !== undefined) {
 			const data = await this.restPost<unknown>("/execute", {
 				script: request.script,
@@ -369,7 +388,11 @@ class RestAdapter implements ProtocolAdapter {
 		return normalizeRestExecute(data);
 	}
 
-	async apiRequest(request: ProtocolApiRequest): Promise<ProtocolApiResult> {
+	async apiRequest(
+		request: ProtocolApiRequest,
+		options?: ProtocolSendOptions,
+	): Promise<ProtocolApiResult> {
+		options?.onSent?.();
 		const base = request.path.replace(/\/$/, "");
 		switch (request.verb) {
 			case "print": {
@@ -765,9 +788,12 @@ class NativeApiAdapter implements ProtocolAdapter {
 
 	async execute(
 		request: ProtocolExecuteRequest,
+		options?: ProtocolSendOptions,
 	): Promise<ProtocolExecuteResult> {
 		if (request.script !== undefined) {
-			return normalizeNativeExecute(await this.executeScript(request.script));
+			return normalizeNativeExecute(
+				await this.executeScript(request.script, options),
+			);
 		}
 		const command: NativeApiCommand = {
 			command: `${request.path.replace(/\/$/, "")}/${request.command}`,
@@ -781,7 +807,7 @@ class NativeApiAdapter implements ProtocolAdapter {
 		if (request.binary) {
 			command.binary = true;
 		}
-		const replies = await this.talk(command);
+		const replies = await this.talk(command, options);
 		return { records: repliesToRecords(replies) };
 	}
 
@@ -794,17 +820,24 @@ class NativeApiAdapter implements ProtocolAdapter {
 	 */
 	private async executeScript(
 		script: string,
+		options?: ProtocolSendOptions,
 	): Promise<Record<string, string>[]> {
-		const replies = await this.talk({
-			command: "/execute",
-			attributes: { script, "as-string": "" },
-		});
+		const replies = await this.talk(
+			{
+				command: "/execute",
+				attributes: { script, "as-string": "" },
+			},
+			options,
+		);
 		return repliesToRecords(replies);
 	}
 
-	async apiRequest(request: ProtocolApiRequest): Promise<ProtocolApiResult> {
+	async apiRequest(
+		request: ProtocolApiRequest,
+		options?: ProtocolSendOptions,
+	): Promise<ProtocolApiResult> {
 		const records = repliesToRecords(
-			await this.talk(nativeCommandFor(request)),
+			await this.talk(nativeCommandFor(request), options),
 		);
 		switch (request.verb) {
 			case "print":
@@ -880,8 +913,13 @@ class NativeApiAdapter implements ProtocolAdapter {
 		return session;
 	}
 
-	private async talk(command: NativeApiCommand): Promise<ApiReply[]> {
+	private async talk(
+		command: NativeApiCommand,
+		options?: ProtocolSendOptions,
+	): Promise<ApiReply[]> {
+		// Connecting logs in lazily; only the sentence after `/login` is the command.
 		const session = await this.connect();
+		options?.onSent?.();
 		return this.withTimeout(session.talk(command));
 	}
 
@@ -982,6 +1020,7 @@ class MacTelnetAdapter implements ProtocolAdapter {
 
 	async execute(
 		request: ProtocolExecuteRequest,
+		options?: ProtocolSendOptions,
 	): Promise<ProtocolExecuteResult> {
 		const cli = request.script;
 		if (cli === undefined) {
@@ -994,6 +1033,7 @@ class MacTelnetAdapter implements ProtocolAdapter {
 			});
 		}
 		const console = await this.open();
+		options?.onSent?.();
 		const { output } = await console.run(cli);
 		return { records: [], ret: output };
 	}
@@ -1134,6 +1174,7 @@ class SshExecAdapter implements ProtocolAdapter {
 
 	async execute(
 		request: ProtocolExecuteRequest,
+		options?: ProtocolSendOptions,
 	): Promise<ProtocolExecuteResult> {
 		const cli = request.script;
 		if (cli === undefined) {
@@ -1145,6 +1186,7 @@ class SshExecAdapter implements ProtocolAdapter {
 					"Report this bug; runCommand must pass the raw command as `script` for ssh.",
 			});
 		}
+		options?.onSent?.();
 		const output = await this.client.exec(cli);
 		return { records: [], ret: output };
 	}