@takodotid/circuit 0.27.0 → 0.28.0

package/src/adapters/devices/routeros/index.ts

@@ -6,8 +6,9 @@ import type { Client } from "ssh2";
 import { familyOf } from "../../../core/addr";
 import { resolve, substitute } from "../../../core/secrets";
 import type { Device, Family } from "../../../schema";
+import { type ConsoleDialect, consoleLogin, consoleOf, ConsoleShell, openConsole } from "../../../transport/console";
 import { connect, exec, upload } from "../../../transport/ssh";
-import type { ApplyOptions, DeviceAdapter, Plan } from "../types";
+import type { ApplyOptions, DeviceAdapter, Plan, ReadOptions } from "../types";
 import { INSTALL_CERTIFICATE, plan } from "./plan";
 import { spell } from "../catalog";
 import { mediumOf, render } from "./render";
@@ -27,9 +28,77 @@ export async function login(device: Device): Promise<Client> {
     });
 }
 
+/** How the RouterOS console asks for a login. The flags after the user turn off colours and terminal detection, without which the console redraws every line. */
+export const ROUTEROS_CONSOLE: ConsoleDialect = {
+    login: /Login: $/,
+    password: /Password: $/,
+    prompt: /\] > $/,
+    logout: "/quit",
+    others: [
+        [/-- \[Q quit\|D dump\|(?:C-z pause\|)?down\]$/, "D"],
+        [/\[Y\/n\]:? ?$/, "n"],
+    ],
+    user: (user) => `${user}+cwt`,
+};
+
+/** Where commands run, one at a time, each returning what it printed: an SSH session, or the console. */
+type Session = {
+    run(command: string, timeout?: number): Promise<string>;
+    /** Write a file to the device. Only SSH can. */
+    upload?(path: string, content: string): Promise<void>;
+    /** A fresh login, which proves access survived: this session ends and a new SSH session opens, or the console logs out and in again. */
+    fresh(): Promise<Session>;
+    end(): void;
+};
+
+function sshSession(client: Client, device: Device): Session {
+    return {
+        run: (command, timeout) => exec(client, command, timeout),
+        upload: (path, content) => upload(client, path, content),
+        fresh: async () => {
+            client.end();
+            return sshSession(await login(device), device);
+        },
+        end: () => client.end(),
+    };
+}
+
+async function consoleSession(device: Device): Promise<Session> {
+    const { console, user, password } = consoleOf(device);
+    const opened = await openConsole(console);
+
+    try {
+        await consoleLogin(opened.channel, ROUTEROS_CONSOLE, user, password);
+    } catch (error) {
+        opened.close();
+        throw error;
+    }
+
+    const shell = new ConsoleShell(opened.channel, ROUTEROS_CONSOLE);
+
+    const session: Session = {
+        run: (command, timeout) => shell.run(command, timeout),
+        fresh: async () => {
+            await consoleLogin(opened.channel, ROUTEROS_CONSOLE, user, password);
+            return session;
+        },
+        end: () => {
+            shell.logout();
+            opened.close();
+        },
+    };
+
+    return session;
+}
+
+/** Log in over SSH, or on the console when asked. */
+async function open(device: Device, options: ReadOptions = {}): Promise<Session> {
+    return options.console ? consoleSession(device) : sshSession(await login(device), device);
+}
+
 /** Refuse a device on a version this adapter does not render for, before anything is read or sent. */
-export async function checkVersion(client: Client, device: Device): Promise<void> {
-    const version = (await exec(client, ":put [/system resource get version]")).trim();
+export async function checkVersion(session: Session, device: Device): Promise<void> {
+    const version = (await session.run(":put [/system resource get version]")).trim();
     const major = Number(version.split(".")[0]);
 
     if (major !== SUPPORTED_MAJOR) {
@@ -54,15 +123,15 @@ const LIST_CERTIFICATES = [
 /**
  * What the device runs: its export, its users, and its certificates. Secrets are not part of an export.
  */
-export async function read(device: Device): Promise<string> {
-    const client = await login(device);
+export async function read(device: Device, _network: readonly Device[] = [], options: ReadOptions = {}): Promise<string> {
+    const session = await open(device, options);
 
     try {
-        await checkVersion(client, device);
+        await checkVersion(session, device);
 
-        const config = await exec(client, "/export", 300_000);
-        const users = await exec(client, "/user export");
-        const certificates = (await exec(client, LIST_CERTIFICATES)).trim();
+        const config = await session.run("/export", 300_000);
+        const users = await session.run("/user export");
+        const certificates = (await session.run(LIST_CERTIFICATES)).trim();
 
         const listed = certificates.split("\n").every((line) => line.trim().startsWith("add fingerprint="));
         if (certificates && !listed) {
@@ -75,7 +144,7 @@ export async function read(device: Device): Promise<string> {
         const text = [config.trim(), userMenu, certificateMenu].filter(Boolean).join("\n");
         return withoutTimestamp(text) + "\n";
     } finally {
-        client.end();
+        session.end();
     }
 }
 
@@ -145,44 +214,46 @@ const ROLLBACK_SCHEDULER = "apply-rollback";
 const escapeForString = (text: string) => text.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\$/g, "\\$");
 
 /** Compile a command on the device without running it. Returns why it was refused, or undefined. */
-async function refusal(client: Client, command: string): Promise<string | undefined> {
-    const compiled = (await exec(client, `:put [:parse "${escapeForString(command)}"]`)).trim();
+async function refusal(session: Session, command: string): Promise<string | undefined> {
+    const compiled = (await session.run(`:put [:parse "${escapeForString(command)}"]`)).trim();
     const refused = !compiled.startsWith("(") || /syntax error|bad parameter|no such|expected/.test(compiled);
     return refused ? compiled.slice(0, 200) : undefined;
 }
 
 /** Upload a certificate and its key, import both under one name, and delete the files. */
-async function installCertificate(client: Client, device: Device, name: string): Promise<void> {
+async function installCertificate(session: Session, device: Device, name: string): Promise<void> {
     const certificate = device.certificates?.[name];
     if (!certificate) throw new Error(`certificate ${name} is not declared`);
+    if (!session.upload)
+        throw new Error(`certificate ${name} is installed from a file, which only SSH can write; apply it without --console`);
 
-    await upload(client, `${name}.crt`, certificate.certificate);
-    await exec(client, `/certificate import file-name=${name}.crt name=${name} passphrase=""`);
+    await session.upload(`${name}.crt`, certificate.certificate);
+    await session.run(`/certificate import file-name=${name}.crt name=${name} passphrase=""`);
 
     if (certificate.private_key) {
         // A key from a file is PEM as it is; one from a variable is PEM encoded as one line of base64.
         const value = resolve(certificate.private_key);
         const privateKey = value.includes("-----BEGIN") ? `${value}\n` : Buffer.from(value, "base64").toString("utf8");
 
-        await upload(client, `${name}.key`, privateKey);
-        await exec(client, `/certificate import file-name=${name}.key name=${name} passphrase=""`);
+        await session.upload(`${name}.key`, privateKey);
+        await session.run(`/certificate import file-name=${name}.key name=${name} passphrase=""`);
     }
 
-    await exec(client, `/file remove [find name="${name}.crt" or name="${name}.key"]`);
+    await session.run(`/file remove [find name="${name}.crt" or name="${name}.key"]`);
 }
 
 export async function apply(device: Device, _network: readonly Device[], changes: Plan, options: ApplyOptions): Promise<void> {
-    const client = await login(device);
-    await checkVersion(client, device);
+    const session = await open(device, options);
+    await checkVersion(session, device);
 
     const commands = changes.steps.flatMap((step) => step.send.map((command) => ({ title: step.title, command })));
 
     for (const { title, command } of commands) {
         if (command.startsWith(INSTALL_CERTIFICATE)) continue;
 
-        const reason = await refusal(client, substitute(command));
+        const reason = await refusal(session, substitute(command));
         if (reason) {
-            client.end();
+            session.end();
             throw new Error(`${title}: the device will not parse ${command.slice(0, 200)}\n    ${reason}`);
         }
     }
@@ -201,38 +272,36 @@ export async function apply(device: Device, _network: readonly Device[], changes
     try {
         console.log(`  saving ${backup}, arming a ${options.rollback} minute rollback`);
 
-        await exec(client, `/system backup save name=${backup} dont-encrypt=yes`, 120_000);
-        await exec(client, `/system scheduler remove [find name="${ROLLBACK_SCHEDULER}"]`);
-        await exec(client, armRollback);
+        await session.run(`/system backup save name=${backup} dont-encrypt=yes`, 120_000);
+        await session.run(`/system scheduler remove [find name="${ROLLBACK_SCHEDULER}"]`);
+        await session.run(armRollback);
 
         for (const { title, command } of commands) {
             if (command.startsWith(INSTALL_CERTIFICATE)) {
                 const certificateName = command.slice(INSTALL_CERTIFICATE.length).trim();
-                await installCertificate(client, device, certificateName);
+                await installCertificate(session, device, certificateName);
                 continue;
             }
 
-            const answer = (await exec(client, substitute(command), 120_000)).trim();
+            const answer = (await session.run(substitute(command), 120_000)).trim();
             if (answer) throw new Error(`${title}: ${command.slice(0, 160)}\n    device said: ${answer.slice(0, 300)}`);
         }
     } catch (error) {
         console.log(`  FAILED: ${(error as Error).message}`);
         console.log(`  restoring ${backup} now; the rollback stays armed in case this does not get through`);
 
-        await exec(client, `/system backup load name=${backup} password=""`, 30_000).catch(() => undefined);
-        client.end();
+        await session.run(`/system backup load name=${backup} password=""`, 30_000).catch(() => undefined);
+        session.end();
 
         throw new Error("apply failed and the backup is being restored");
     }
 
-    client.end();
-
-    // A fresh session is the proof that access survived. Only then is the rollback removed, with the backup, which holds every credential.
-    const proof = await login(device).catch(() => undefined);
+    // A fresh login is the proof that access survived. Only then is the rollback removed, with the backup, which holds every credential.
+    const proof = await session.fresh().catch(() => undefined);
     if (!proof) throw new Error(`could not log in again; the device restores ${backup} within ${options.rollback} minutes`);
 
-    await exec(proof, `/system scheduler remove [find name="${ROLLBACK_SCHEDULER}"]`);
-    await exec(proof, `/file remove [find name="${backup}.backup"]`);
+    await proof.run(`/system scheduler remove [find name="${ROLLBACK_SCHEDULER}"]`);
+    await proof.run(`/file remove [find name="${backup}.backup"]`);
     proof.end();
     console.log("  logged in again, rollback disarmed");
 }
@@ -262,6 +331,7 @@ export async function fill(device: Device, _network: readonly Device[], set: str
 
 export const routeros: DeviceAdapter = {
     extension: ".rsc",
+    console: true,
     unsupported,
     render,
     read,

package/src/adapters/devices/vrp/index.ts

@@ -7,11 +7,12 @@ import { familyOf, host, netmask, split, wildcard } from "../../../core/addr";
 import { marker, resolve, substitute, valueOfReference } from "../../../core/secrets";
 import { offset } from "../../../core/time";
 import type { Device, Interface, Port, Vrrp } from "../../../schema";
+import { type ConsoleDialect, consoleLogin, consoleOf, openConsole } from "../../../transport/console";
 import { connect, readUntil, send, shell } from "../../../transport/ssh";
 import { portsOf, spell } from "../catalog";
 import { ipv4Networks, lagIds, switchUnsupported } from "../derive";
 import { compare, type Dialect, scrub, steps, vlanListChange } from "../lines";
-import type { DeviceAdapter, Plan } from "../types";
+import type { ApplyOptions, DeviceAdapter, Plan, ReadOptions } from "../types";
 
 /** Lines the device prints whatever is configured, or that describe the hardware rather than its configuration. */
 const DEVICE_FACTS = [
@@ -570,8 +571,46 @@ export async function openShell(client: Client): Promise<ClientChannel> {
     return channel;
 }
 
+/** How the console asks for a login: the same question to change the password, always answered no, and a system view left with `return`. Not yet proved on a device. */
+export const VRP_CONSOLE: ConsoleDialect = {
+    login: /Username:\s*$/i,
+    password: /Password:\s*$/i,
+    prompt: /<[^>\n]+>\s*$/,
+    logout: "quit",
+    others: [
+        [/Change now\? ?\[Y\/N\]:?\s*$/i, "N\n"],
+        [/\[~?\*?[^\]\n]+\]\s*$/, "return\n"],
+    ],
+};
+
+/** Log in on the console with paging off, run `work` with a way to log in afresh, and log out. */
+async function onConsole<T>(device: Device, work: (channel: ClientChannel, relogin: () => Promise<void>) => Promise<T>): Promise<T> {
+    const { console, user, password } = consoleOf(device);
+    const opened = await openConsole(console);
+
+    const login = async () => {
+        await consoleLogin(opened.channel, VRP_CONSOLE, user, password);
+        await send(opened.channel, "screen-length 0 temporary", 10_000, 1500);
+    };
+
+    try {
+        await login();
+        const result = await work(opened.channel, login);
+        opened.channel.write(`${VRP_CONSOLE.logout}\n`);
+        return result;
+    } finally {
+        opened.close();
+    }
+}
+
 /** What the device runs, credentials scrubbed. */
-export async function read(device: Device): Promise<string> {
+export async function read(device: Device, _network: readonly Device[] = [], options: ReadOptions = {}): Promise<string> {
+    if (options.console) {
+        return onConsole(device, async (channel) =>
+            configurationOf(device, await send(channel, "display current-configuration", 120_000, 3000))
+        );
+    }
+
     const client = await login(device);
 
     try {
@@ -579,17 +618,22 @@ export async function read(device: Device): Promise<string> {
         const dump = await send(channel, "display current-configuration", 120_000, 3000);
         channel.end();
 
-        const lines = dump.replace(/\r/g, "").split("\n");
-        const start = lines.findIndex((line) => line.startsWith("!Software Version"));
-        if (start < 0) throw new Error(`${device.name} returned no configuration`);
-        // The prompt, and the stamp of the last change, are not configuration.
-        const body = lines.slice(start).filter((line) => !/^<.*>$/.test(line.trim()) && !line.startsWith("!Last configuration"));
-        return scrub(body.join("\n").trim() + "\n");
+        return configurationOf(device, dump);
     } finally {
         client.end();
     }
 }
 
+/** The configuration in a dump, without the prompt or the stamp of the last change. */
+function configurationOf(device: Device, dump: string): string {
+    const lines = dump.replace(/\r/g, "").split("\n");
+    const start = lines.findIndex((line) => line.startsWith("!Software Version"));
+    if (start < 0) throw new Error(`${device.name} returned no configuration`);
+
+    const body = lines.slice(start).filter((line) => !/^<.*>$/.test(line.trim()) && !line.startsWith("!Last configuration"));
+    return scrub(body.join("\n").trim() + "\n");
+}
+
 export function unsupported(device: Device): string[] {
     const found: string[] = [];
 
@@ -693,10 +737,8 @@ async function sendLine(channel: ClientChannel, line: string): Promise<string> {
     return answer;
 }
 
-export async function apply(device: Device, _network: readonly Device[], plan: Plan): Promise<void> {
-    const client = await login(device);
-    const channel = await openShell(client);
-
+/** Send a plan into the candidate and commit it. A refused line clears the candidate, which leaves the device as it was. */
+async function commitPlan(channel: ClientChannel, plan: Plan): Promise<void> {
     try {
         await send(channel, "system-view", 10_000, 1500);
 
@@ -711,28 +753,50 @@ export async function apply(device: Device, _network: readonly Device[], plan: P
         if (REFUSED.test(committed)) throw new Error(`commit refused: ${committed.trim().slice(0, 300)}`);
         await send(channel, "quit", 10_000);
     } catch (error) {
-        // Nothing is committed yet. Clearing the candidate leaves the device as it was.
         await send(channel, "clear configuration candidate", 10_000).catch(() => undefined);
-        channel.end();
-        client.end();
         throw error;
     }
+}
+
+/** Save what runs, so a reboot keeps it. */
+async function save(channel: ClientChannel): Promise<void> {
+    const saving = await send(channel, "save", 20_000, 2000);
+    if (/\[Y\/N\]/i.test(saving)) await send(channel, "Y", 60_000, 5000);
+}
+
+const NOT_SAVED = "Not saved: a reboot restores the previous configuration.";
+
+export async function apply(device: Device, _network: readonly Device[], plan: Plan, options: ApplyOptions): Promise<void> {
+    // On the console, a fresh login on the same console is the proof, and the save is sent in it.
+    if (options.console) {
+        await onConsole(device, async (channel, relogin) => {
+            await commitPlan(channel, plan);
+            await relogin().catch((error: Error) => {
+                throw new Error(`committed, but a fresh login on the console failed: ${error.message}. ${NOT_SAVED}`);
+            });
+            await save(channel);
+        });
+
+        console.log("  committed, login proved, saved");
+        return;
+    }
+
+    const client = await login(device);
+    const channel = await openShell(client);
+
+    try {
+        await commitPlan(channel, plan);
+
+        const proof = await login(device).catch(() => undefined);
+        if (!proof) throw new Error(`committed, but a fresh login failed. ${NOT_SAVED} Recover over the open session or the console.`);
+        proof.end();
 
-    const proof = await login(device).catch(() => undefined);
-    if (!proof) {
+        await save(channel);
+    } finally {
         channel.end();
         client.end();
-        throw new Error(
-            "committed, but a fresh login failed. Not saved: a reboot restores the previous configuration. Recover over the open session or the console."
-        );
     }
 
-    proof.end();
-
-    const saving = await send(channel, "save", 20_000, 2000);
-    if (/\[Y\/N\]/i.test(saving)) await send(channel, "Y", 60_000, 5000);
-    channel.end();
-    client.end();
     console.log("  committed, login proved, saved");
 }
 
@@ -779,6 +843,7 @@ function plan(desired: string, current: string): Plan {
 
 export const vrp: DeviceAdapter = {
     extension: ".cfg",
+    console: true,
     unsupported,
     render,
     read,

package/src/schema/device.ts

@@ -31,11 +31,11 @@ export type Jump = {
     cloudflared?: true;
 };
 
-/** A serial console, reached through a jump host. */
+/** A serial console, on a jump host or on the computer Circuit runs on. */
 export type Console = {
-    /** The jump host the console cable is plugged into. */
-    jump: Jump;
-    /** The serial port on the jump host. A path under `/dev/serial/by-path/` stays the same when two adapters swap names. */
+    /** The jump host the console cable is plugged into. When absent, the cable is plugged into the computer Circuit runs on. */
+    jump?: Jump;
+    /** The serial port: on Linux or macOS a path under `/dev`, where a path under `/dev/serial/by-path/` stays the same when two adapters swap names; on Windows a COM port, such as `COM3`. */
     port: string;
     /** Line speed in bits per second, such as 9600 or 115200. */
     baud: number;