@tikoci/centrs 0.1.6 → 0.1.8-next.0

package/src/core/query.ts

@@ -0,0 +1,508 @@
+/**
+ * `--query` predicates: the inside of a RouterOS `print where …`, compiled to
+ * the API query stack (native `?` words, REST `.query` — the same words minus
+ * the `?`, `commands/api/AGENTS.md`).
+ *
+ * One grammar serves `retrieve --query`, `api --query` and, later, `--until`
+ * (#397, #364). It reads like `where`: `interface=ether1 and !disabled`,
+ * `(type=ether or type=vlan) and mtu>=1500`. The device evaluates the compiled
+ * stack, so comparisons keep RouterOS's per-property typing.
+ *
+ * Words are emitted in postfix order; `#!`, `#&`, `#|` pop their operands, and
+ * whatever remains is AND-ed by RouterOS. Mapping, grounded by the CHR
+ * `find where` vs `.query` differential (`test/integration/retrieve-query.test.ts`):
+ *
+ * | where          | words                         |
+ * | -------------- | ----------------------------- |
+ * | `a=v`          | `a=v`                         |
+ * | `a!=v`         | `a=v` `#!`                    |
+ * | `a<v`          | `<a=v` `-a` `#|`              |
+ * | `a>v`          | `>a=v`                        |
+ * | `a<=v`         | `>a=v` `#!`                   |
+ * | `a>=v`         | `<a=v` `-a` `#|` `#!`         |
+ * | bare `a`       | `a=yes` for a boolean, else `a` (is set) |
+ * | `!x`           | x `#!`                        |
+ * | `x and y`      | x y `#&`                      |
+ * | `x or y`       | x y `#|`                      |
+ *
+ * Ordering follows `where`, where a row without the property is smaller than
+ * any value: `timeout<1d` includes static address-list entries, `timeout>1h`
+ * does not. API `<`/`>` skip such rows, hence the `-a` (absent) word.
+ *
+ * A bare name means what it means after `where`, which depends on the
+ * property: `where disabled` is `disabled=yes`, `where comment` is "comment is
+ * set" (an empty comment is stored as absent). The caller asks the device
+ * which names are booleans (`inspectWhereBooleans`) before emitting.
+ *
+ * Refused rather than approximated: `~` (regex) and `in` (prefix membership)
+ * have no API query word; `$`/`[`/`{` values need a script evaluator;
+ * `!a=v` is `(!a)=v` to RouterOS, which matches by accident, so it must be
+ * written `!(a=v)` or `a!=v`; `not` is not a RouterOS operator; and
+ * space-separated conditions must be joined with `and`/`or`.
+ *
+ * The device decides comparisons with the API's per-property typing, which is
+ * not always the CLI's: on CHR 7.23.7/7.24.5, `where dst-port=80` matches
+ * nothing, while the query matches the `"80"` that `retrieve` shows. On CHR
+ * 7.25beta3/7.25rc1/7.26beta1 the CLI agrees with the query; ordering
+ * on a text property (`dst-port`, address-list `address`) is text order.
+ */
+
+import { CentrsError } from "../errors.ts";
+
+export type QueryComparison = "=" | "!=" | "<" | ">" | "<=" | ">=";
+
+export type QueryNode =
+	| { kind: "compare"; name: string; op: QueryComparison; value: string }
+	| { kind: "truthy"; name: string }
+	| { kind: "not"; operand: QueryNode }
+	| { kind: "and" | "or"; left: QueryNode; right: QueryNode };
+
+export interface ParsedQuery {
+	/** One tree per `--query`; several are AND-ed. */
+	nodes: QueryNode[];
+	/** Every property the predicate reads, for inspect validation. */
+	names: string[];
+	/** Properties used bare (`disabled`, `!comment`), whose type decides the word. */
+	bareNames: string[];
+}
+
+type Token =
+	| { kind: "name"; text: string; at: number }
+	| { kind: "op"; text: QueryComparison | "~" | "in"; at: number }
+	| { kind: "value"; text: string; at: number }
+	| { kind: "and" | "or" | "not" | "(" | ")"; at: number };
+
+const NAME = /^\.?[A-Za-z][A-Za-z0-9.-]*/;
+const BARE_VALUE_STOP = new Set([" ", "\t", "\r", "\n", "(", ")", '"']);
+/**
+ * RouterOS string escapes, the device's set (`src/explain/quoted-string.ts`
+ * has the sweep). Hex is two UPPERCASE digits: `\ff` is `\f` then `f`.
+ */
+const ESCAPES: Record<string, string> = {
+	'"': '"',
+	"\\": "\\",
+	$: "$",
+	"?": "?",
+	_: " ",
+	a: "\x07",
+	b: "\b",
+	f: "\f",
+	n: "\n",
+	r: "\r",
+	t: "\t",
+	v: "\v",
+};
+const HEX_ESCAPE = /^[0-9A-F]{2}$/;
+
+/** Parse one or more `--query` expressions offline. */
+export function parseQueries(
+	expressions: readonly string[],
+	flag: "--query" | "--until" = "--query",
+): ParsedQuery {
+	let nodes: QueryNode[];
+	try {
+		nodes = expressions.map(parseQuery);
+	} catch (error) {
+		if (flag === "--until" && error instanceof CentrsError)
+			throw queryErrorForFlag(error, flag);
+		throw error;
+	}
+	const names = new Set<string>();
+	const bareNames = new Set<string>();
+	const visit = (node: QueryNode): void => {
+		switch (node.kind) {
+			case "truthy":
+				names.add(node.name);
+				bareNames.add(node.name);
+				return;
+			case "compare":
+				names.add(node.name);
+				return;
+			case "not":
+				visit(node.operand);
+				return;
+			default:
+				visit(node.left);
+				visit(node.right);
+		}
+	};
+	nodes.forEach(visit);
+	return { nodes, names: [...names], bareNames: [...bareNames] };
+}
+
+/** Keep shared grammar diagnostics attached to the caller's predicate flag. */
+export function queryErrorForFlag(
+	error: CentrsError,
+	flag: "--until",
+): CentrsError {
+	return new CentrsError({
+		code: error.code,
+		summary: error.summary.replace("--query", flag),
+		remediation: error.remediation?.replace("--query", flag),
+		context: { ...error.context, flag },
+		position: error.position,
+		cause: error.cause,
+		causeData: error.causeData,
+	});
+}
+
+/**
+ * Query words (no `?` prefix) in stack order. `booleans` names the bare
+ * properties the device reports as booleans; any other bare name means "is set".
+ */
+export function compileQueryWords(
+	parsed: ParsedQuery,
+	booleans: ReadonlySet<string>,
+): string[] {
+	const words: string[] = [];
+	parsed.nodes.forEach((node, index) => {
+		emit(node, words, booleans);
+		if (index > 0) words.push("#&");
+	});
+	return words;
+}
+
+export function parseQuery(expression: string): QueryNode {
+	const tokens = tokenize(expression);
+	let position = 0;
+	const peek = () => tokens[position];
+
+	const fail = (summary: string, at: number): never => {
+		throw invalidQuery(expression, summary, at);
+	};
+
+	const parseOr = (): QueryNode => {
+		let left = parseAnd();
+		while (peek()?.kind === "or") {
+			position++;
+			left = { kind: "or", left, right: parseAnd() };
+		}
+		return left;
+	};
+
+	const parseAnd = (): QueryNode => {
+		let left = parseUnary();
+		while (peek()?.kind === "and") {
+			position++;
+			left = { kind: "and", left, right: parseUnary() };
+		}
+		return left;
+	};
+
+	const parseUnary = (): QueryNode => {
+		const token = peek();
+		if (token === undefined) {
+			return fail(
+				"The expression ends where a condition was expected.",
+				expression.length,
+			);
+		}
+		if (token.kind === "not") {
+			position++;
+			const next = tokens[position];
+			if (next?.kind === "name" && tokens[position + 1]?.kind === "op") {
+				return fail(
+					`RouterOS reads \`!${next.text}…\` as \`(!${next.text})…\`; write \`!(${next.text}…)\` or use \`!=\`.`,
+					token.at,
+				);
+			}
+			return { kind: "not", operand: parseUnary() };
+		}
+		if (token.kind === "(") {
+			position++;
+			const inner = parseOr();
+			const close = peek();
+			if (close?.kind !== ")") {
+				return fail("A `(` is never closed.", token.at);
+			}
+			position++;
+			return inner;
+		}
+		if (token.kind !== "name") {
+			return fail("Expected a property name.", token.at);
+		}
+		if (token.text === "not") {
+			return fail("RouterOS has no `not` operator; use `!`.", token.at);
+		}
+		position++;
+		const op = peek();
+		if (op?.kind !== "op") {
+			return { kind: "truthy", name: token.text };
+		}
+		position++;
+		if (op.text === "~" || op.text === "in") {
+			throw unsupportedOperator(expression, op.text, op.at);
+		}
+		const value = peek();
+		if (value?.kind !== "value") {
+			return fail(`\`${op.text}\` needs a value after it.`, op.at);
+		}
+		position++;
+		return {
+			kind: "compare",
+			name: token.text,
+			op: op.text,
+			value: value.text,
+		};
+	};
+
+	const node = parseOr();
+	const rest = peek();
+	if (rest !== undefined) {
+		fail(
+			rest.kind === ")"
+				? "A `)` has no matching `(`."
+				: "Join conditions with `and` or `or`.",
+			rest.at,
+		);
+	}
+	return node;
+}
+
+function emit(
+	node: QueryNode,
+	words: string[],
+	booleans: ReadonlySet<string>,
+): void {
+	switch (node.kind) {
+		case "truthy":
+			words.push(booleans.has(node.name) ? `${node.name}=yes` : node.name);
+			return;
+		case "compare": {
+			const { name, value } = node;
+			switch (node.op) {
+				case "=":
+					words.push(`${name}=${value}`);
+					return;
+				case "!=":
+					words.push(`${name}=${value}`, "#!");
+					return;
+				// `where` counts a row without the property as smaller than any
+				// value; API `<`/`>` skip such rows, so `<` adds them back (`-a`).
+				case "<":
+					words.push(`<${name}=${value}`, `-${name}`, "#|");
+					return;
+				case ">":
+					words.push(`>${name}=${value}`);
+					return;
+				case "<=":
+					words.push(`>${name}=${value}`, "#!");
+					return;
+				case ">=":
+					words.push(`<${name}=${value}`, `-${name}`, "#|", "#!");
+					return;
+			}
+			return;
+		}
+		case "not":
+			emit(node.operand, words, booleans);
+			words.push("#!");
+			return;
+		case "and":
+		case "or":
+			emit(node.left, words, booleans);
+			emit(node.right, words, booleans);
+			words.push(node.kind === "and" ? "#&" : "#|");
+			return;
+	}
+}
+
+function tokenize(expression: string): Token[] {
+	const tokens: Token[] = [];
+	let index = 0;
+	// After a comparison operator the next token is a value, never a name.
+	let wantValue = false;
+	while (index < expression.length) {
+		const char = expression[index] as string;
+		if (/\s/.test(char)) {
+			// RouterOS: `comment= x` is "expected comment value". `in` is a word,
+			// so a space follows it.
+			const last = tokens.at(-1);
+			if (wantValue && !(last?.kind === "op" && last.text === "in")) {
+				throw invalidQuery(
+					expression,
+					"A value must follow its operator without a space; quote a value that starts with one.",
+					index,
+				);
+			}
+			index++;
+			continue;
+		}
+		const at = index;
+		if (wantValue) {
+			wantValue = false;
+			if (char === '"') {
+				const { text, end } = readQuoted(expression, index);
+				tokens.push({ kind: "value", text, at });
+				index = end;
+				continue;
+			}
+			let end = index;
+			while (
+				end < expression.length &&
+				!BARE_VALUE_STOP.has(expression[end] as string)
+			) {
+				end++;
+			}
+			const text = expression.slice(index, end);
+			if (text.length === 0) {
+				break;
+			}
+			rejectScriptValue(expression, text, at);
+			// RouterOS chains it: `comment=x=yes` is `(comment=x)=yes`, and
+			// `comment=x!=y` (or `<=`, `>=`) matches nothing.
+			const chained = text.indexOf("=");
+			if (chained >= 0) {
+				throw invalidQuery(
+					expression,
+					`RouterOS reads a second \`=\` as another comparison; quote the value: ${expression.slice(tokens.at(-2)?.at ?? 0, at)}"${text}".`,
+					at + chained,
+				);
+			}
+			tokens.push({ kind: "value", text, at });
+			index = end;
+			continue;
+		}
+		const two = expression.slice(index, index + 2);
+		if (two === "&&" || two === "||") {
+			tokens.push({ kind: two === "&&" ? "and" : "or", at });
+			index += 2;
+			continue;
+		}
+		if (two === "!=" || two === "<=" || two === ">=") {
+			tokens.push({ kind: "op", text: two, at });
+			index += 2;
+			wantValue = true;
+			continue;
+		}
+		if (char === "=" || char === "<" || char === ">" || char === "~") {
+			tokens.push({ kind: "op", text: char, at });
+			index++;
+			wantValue = true;
+			continue;
+		}
+		if (char === "!" || char === "(" || char === ")") {
+			tokens.push({ kind: char === "!" ? "not" : char, at });
+			index++;
+			continue;
+		}
+		const name = NAME.exec(expression.slice(index))?.[0];
+		if (name === undefined) {
+			throw invalidQuery(
+				expression,
+				`Unexpected \`${char}\`; expected a property name, \`!\` or \`(\`.`,
+				at,
+			);
+		}
+		if (name === "and" || name === "or") {
+			tokens.push({ kind: name, at });
+		} else if (name === "in") {
+			tokens.push({ kind: "op", text: "in", at });
+			wantValue = true;
+		} else {
+			tokens.push({ kind: "name", text: name, at });
+		}
+		index += name.length;
+	}
+	return tokens;
+}
+
+function readQuoted(
+	expression: string,
+	start: number,
+): { text: string; end: number } {
+	let text = "";
+	let index = start + 1;
+	while (index < expression.length) {
+		const char = expression[index] as string;
+		if (char === '"') {
+			return { text, end: index + 1 };
+		}
+		if (char === "$") {
+			throw scriptValue(expression, start);
+		}
+		if (char !== "\\") {
+			text += char;
+			index++;
+			continue;
+		}
+		const next = expression[index + 1] ?? "";
+		const hex = expression.slice(index + 1, index + 3);
+		if (next in ESCAPES) {
+			text += ESCAPES[next];
+			index += 2;
+		} else if (/[ \t\r\n]/.test(next)) {
+			// A backslash before whitespace joins the lines: it and the whole
+			// whitespace run after it are dropped (`"x\<LF>  y"` is `xy`).
+			index++;
+			while (/[ \t\r\n]/.test(expression[index] ?? "")) index++;
+		} else if (HEX_ESCAPE.test(hex)) {
+			const byte = Number.parseInt(hex, 16);
+			if (byte > 0x7f) {
+				// RouterOS stores the raw byte; centrs sends values as UTF-8.
+				throw invalidQuery(
+					expression,
+					`\`\\${hex}\` is a byte above 7F, which a query value cannot carry; write the character itself.`,
+					index,
+				);
+			}
+			text += String.fromCharCode(byte);
+			index += 3;
+		} else {
+			throw invalidQuery(
+				expression,
+				`\`\\${next}\` is not a RouterOS string escape.`,
+				index,
+			);
+		}
+	}
+	throw invalidQuery(expression, "A quoted value is never closed.", start);
+}
+
+function rejectScriptValue(expression: string, text: string, at: number): void {
+	if (text.startsWith("$") || text.startsWith("[") || text.startsWith("{")) {
+		throw scriptValue(expression, at);
+	}
+}
+
+function invalidQuery(
+	expression: string,
+	summary: string,
+	at: number,
+): CentrsError {
+	return new CentrsError({
+		code: "input/invalid-query",
+		summary: `Invalid --query: ${summary}`,
+		remediation:
+			'Write the query as you would after `print where`: `name=ether1`, `mtu>=1500 and !disabled`, `(type=ether or type=vlan)`. Quote values with spaces: `comment="uplink a"`.',
+		context: { query: expression, offset: at },
+	});
+}
+
+function unsupportedOperator(
+	expression: string,
+	operator: "~" | "in",
+	at: number,
+): CentrsError {
+	return new CentrsError({
+		code: "input/unsupported-query",
+		summary:
+			operator === "~"
+				? "`~` (regex) has no RouterOS API query word, so --query cannot run it on the router."
+				: "`in` (prefix membership) has no RouterOS API query word, so --query cannot run it on the router.",
+		remediation:
+			"Read the rows without the condition and filter them yourself, or run the console form with `centrs execute <router> '<menu>/print where …'` (console text, not rows).",
+		context: { query: expression, operator, offset: at },
+	});
+}
+
+function scriptValue(expression: string, at: number): CentrsError {
+	return new CentrsError({
+		code: "input/unsupported-query",
+		summary:
+			"--query values are literal: `$variables`, `[commands]` and `{arrays}` need RouterOS's script evaluator.",
+		remediation:
+			"Put the literal value in the query (escape a `$` inside quotes as `\\$`), or run the console form with `centrs execute`.",
+		context: { query: expression, offset: at },
+	});
+}

package/src/core/routeros-errors.ts

@@ -88,6 +88,12 @@ export interface RouterOsErrorRule {
 	description: string;
 	/** Pattern matched against the trimmed RouterOS string. */
 	test: RegExp;
+	/**
+	 * Anchored form safe for classifying a successful transport's returned text.
+	 * Unlike an HTTP error body / native trap, `/execute as-string` also carries
+	 * ordinary stdout, so substring matches would turn user output into failures.
+	 */
+	resultTest?: RegExp;
 	/** Builds the normalized error fields from the regex match and raw string. */
 	build: (match: RegExpMatchArray, raw: string) => RouterOsErrorRuleResult;
 }
@@ -106,6 +112,8 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 		description:
 			"RouterOS did not recognize the command path or menu item ('no such ...').",
 		test: /no such command prefix|no such item|no such entry/i,
+		resultTest:
+			/^(?:failure:\s*)?(?:no such command prefix|no such item|no such entry)\b.*$/i,
 		build: (_match, raw) => ({
 			summary: `RouterOS does not recognize the path: ${raw.trim()}`,
 			remediation:
@@ -119,6 +127,7 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 		// (mac-telnet) says "bad parameter <name> (line N column M)" for the same
 		// fault. Grounded on CHR 7.23.1.
 		test: /(?:unknown|bad) parameter\s+(\S+)/i,
+		resultTest: /^(?:failure:\s*)?(?:unknown|bad) parameter\s+\S+.*$/i,
 		build: (match) => {
 			const parameter = cleanToken(match[1] ?? "");
 			return {
@@ -135,6 +144,7 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 			"RouterOS console rejected the command word ('bad command name …').",
 		// Console form (mac-telnet) of an unrecognized command/path word.
 		test: /bad command name/i,
+		resultTest: /^(?:failure:\s*)?(?:\(<%%\s*)?bad command name\b.*$/i,
 		build: (_match, raw) => ({
 			summary: `RouterOS does not recognize the command: ${raw.trim()}`,
 			remediation:
@@ -145,6 +155,7 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 		code: "routeros/invalid-value",
 		description: "RouterOS rejected the value supplied for an argument.",
 		test: /invalid value (?:for argument|of)\s+(\S+)/i,
+		resultTest: /^(?:failure:\s*)?invalid value (?:for argument|of)\s+\S+.*$/i,
 		build: (match) => {
 			const argument = cleanToken(match[1] ?? "");
 			return {
@@ -155,11 +166,24 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 			};
 		},
 	},
+	{
+		code: "routeros/invalid-value",
+		description:
+			"RouterOS rejected a value because it does not match the accepted domain.",
+		test: /input does not match/i,
+		resultTest: /^(?:failure:\s*)?input does not match\b.*$/i,
+		build: (_match, raw) => ({
+			summary: `RouterOS rejected the supplied value: ${raw.trim()}`,
+			remediation:
+				"Check the accepted values for this command on the target RouterOS version, then retry with a matching value.",
+		}),
+	},
 	{
 		code: "routeros/session-closed",
 		description:
 			"RouterOS closed the REST session before the request completed (60-second cap).",
 		test: /session closed/i,
+		resultTest: /^(?:failure:\s*)?session closed\b.*$/i,
 		build: () => ({
 			summary: "RouterOS closed the session before the request completed.",
 			remediation:
@@ -171,6 +195,7 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 		description:
 			"Generic RouterOS command failure carrying a `failure: <msg>` string.",
 		test: /^\s*failure:\s*(.+?)\s*$/i,
+		resultTest: /^\s*failure:\s*.+?\s*$/i,
 		build: (match) => {
 			const failure = (match[1] ?? "").trim();
 			return {
@@ -181,11 +206,27 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 			};
 		},
 	},
+	{
+		code: "routeros/command-failed",
+		description: "Generic RouterOS command failure carrying an error prefix.",
+		test: /^\s*error:\s*(.+?)\s*$/i,
+		resultTest: /^\s*error:\s*.+?\s*$/i,
+		build: (match) => {
+			const failure = (match[1] ?? "").trim();
+			return {
+				summary: `RouterOS command failed: ${failure}`,
+				remediation:
+					"Inspect the RouterOS error message, then adjust the script or request shape accordingly.",
+				context: { failure },
+			};
+		},
+	},
 	{
 		code: "routeros/command-failed",
 		description:
 			"RouterOS /execute as-string returned a script :error value with source location.",
 		test: /^\s*(.+?)\s*\(:error; line \d+\)\s*$/i,
+		resultTest: /^\s*.+?\s*\(:error; line \d+\)\s*$/i,
 		build: (match) => {
 			const failure = (match[1] ?? "").trim();
 			return {
@@ -203,6 +244,7 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 		code: "routeros/unknown-path",
 		description: "RouterOS reported a path-shaped 'not found'.",
 		test: /not found/i,
+		resultTest: /^\s*\/\S+\s+not found\s*$/i,
 		build: (_match, raw) => ({
 			summary: `RouterOS does not recognize the path: ${raw.trim()}`,
 			remediation:
@@ -211,6 +253,30 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 	},
 ];
 
+/**
+ * Grounded result shapes that intentionally use the transport-specific
+ * catch-all mapping. They are errors, but do not carry enough information for a
+ * more specific normalized code.
+ */
+const ROUTEROS_RESULT_CATCH_ALL =
+	/^(?:syntax error|expected (?:end of command|command name|input value))\b[^\n]*$/i;
+
+/**
+ * Map text returned by a successful transport only when it matches a grounded,
+ * stdout-safe result shape. Returns `undefined` for ordinary script output.
+ */
+export function mapRouterOsResultError(
+	raw: string,
+	opts: MapRouterOsErrorOptions = {},
+): CentrsError | undefined {
+	const trimmed = raw.trim();
+	if (trimmed.length === 0) return undefined;
+	const matched =
+		ROUTEROS_RESULT_CATCH_ALL.test(trimmed) ||
+		routerOsErrorRules.some((rule) => rule.resultTest?.test(trimmed));
+	return matched ? mapRouterOsError(raw, opts) : undefined;
+}
+
 /**
  * Maps a raw RouterOS error string to a normalized {@link CentrsError}.
  *
@@ -260,7 +326,7 @@ export function mapRouterOsError(
 			? `RouterOS reported an error: ${trimmed}`
 			: "RouterOS reported an unspecified error.",
 		remediation:
-			"Inspect the original RouterOS message; the command word, path, or an attribute is likely invalid.",
+			"RouterOS refused the request, and its message is the reason. If the message names part of the input (a path, parameter or value), fix that; otherwise the router may be busy or the operation unavailable right now.",
 		context: { ...baseContext, ...opts.context },
 		...(position ? { position } : {}),
 		causeData: raw,