@takodotid/circuit 0.34.2 → 0.35.0

package/src/platforms/line-diff.ts

@@ -0,0 +1,244 @@
+// Convergence for platforms whose configuration is a list of lines in nested blocks, such as `interface X` holding its settings. A line the render does not hold is undone, so the device ends up holding exactly the render.
+
+import type { Plan, Step } from "./platform";
+
+export type Dialect = {
+    /** A line at the margin that opens a block, for platforms that do not indent a block's lines. */
+    block: RegExp;
+    /** Whether a block's lines are indented under it. When they are, any line followed by deeper lines opens a block. */
+    indented: boolean;
+    /** A line at the margin that closes every open block. */
+    terminator: string;
+    /** Lines that describe the device rather than configure it, or that the platform prints whatever is set. */
+    ignore: (line: string) => boolean;
+    /** The command that removes a line. */
+    undo: (line: string) => string;
+    /** Leaves one level of block. */
+    leave: string;
+    /** Lines sent before the undos of their block, because the platform refuses an undo until they are in place. */
+    first?: RegExp;
+    /** A line in the form both sides compare in, for example a secret the device prints as a cipher. */
+    canon?: (line: string) => string;
+    /** Where a block is sent among the others, lowest first, so that nothing is referenced before it exists. In the order they differ when absent. */
+    order?: (path: string[]) => number;
+};
+
+/** One line, with the blocks it sits in, outermost first. */
+export type Entry = { path: string[]; line: string };
+
+/** What changes inside one block. */
+export type Group = { path: string[]; remove: string[]; add: string[] };
+
+/** Commands a platform needs around one group, such as releasing a binding before a change and restoring it after. */
+export type Around = (group: Group) => { before: string[]; after: string[] };
+
+export class LineDiff {
+    /** What a switch prints in place of a secret: the cipher of a password, a community or an SNMPv3 key, and a Raisecom community in clear. Never an algorithm list such as `ssh server cipher`. */
+    private static readonly STORED_CREDENTIAL =
+        /((?:password|community read|-mode \S+) (?:irreversible-)?cipher|^snmp-server community)( +)\S+/gm;
+
+    /** How deep a line is indented. */
+    private static indentOf(raw: string): number {
+        return raw.length - raw.trimStart().length;
+    }
+
+    static entries(text: string, dialect: Dialect): Entry[] {
+        const lines = text
+            .replace(/\r/g, "")
+            .split("\n")
+            .filter((raw) => raw.trim() !== "");
+        const result: Entry[] = [];
+        const open: { indent: number; header: string }[] = [];
+
+        for (let i = 0; i < lines.length; i++) {
+            const raw = lines[i]!;
+            const indent = LineDiff.indentOf(raw);
+            const line = raw.trim().replace(/\s+/g, " ");
+
+            if (line === dialect.terminator) {
+                if (indent === 0) open.length = 0;
+                continue;
+            }
+
+            if (dialect.ignore(line)) continue;
+
+            if (dialect.indented) {
+                while (open.length && open.at(-1)!.indent >= indent) open.pop();
+            } else if (indent === 0 && dialect.block.test(line)) {
+                open.length = 0;
+            }
+
+            result.push({ path: open.map((block) => block.header), line });
+
+            const isContent = (candidate: string) => candidate.trim() !== dialect.terminator && !dialect.ignore(candidate.trim());
+            const nextLine = lines.slice(i + 1).find(isContent);
+
+            const opensBlock = dialect.indented
+                ? nextLine !== undefined && LineDiff.indentOf(nextLine) > indent
+                : indent === 0 && dialect.block.test(line);
+
+            if (opensBlock) open.push({ indent, header: line });
+        }
+
+        return result;
+    }
+
+    /** The part of a line that names what it sets: `rule 5`, a free-text keyword, or the line up to its value. Two lines with one head are one setting with two values. */
+    static head(line: string): string {
+        const rule = /^rule \d+/.exec(line);
+        if (rule) return rule[0];
+
+        if (/^(description|name) /.test(line)) return line.split(" ")[0]!;
+
+        const words = line.split(" ");
+        return words.slice(0, Math.max(1, words.length - 1)).join(" ");
+    }
+
+    /**
+     * What differs, by block.
+     *
+     * A device line replaced by a desired line with the same head is not undone; sending the new one is enough. A block the render does not hold goes with its header, and its lines with it.
+     */
+    static compare(desired: string, current: string, dialect: Dialect): Group[] {
+        const canon = dialect.canon ?? ((line: string) => line);
+        const keyOf = (entry: Entry) => [...entry.path, canon(entry.line)].join("\u0000");
+        const pathKey = (path: string[]) => path.join("\u0000");
+
+        const wanted = LineDiff.entries(desired, dialect);
+        const existing = LineDiff.entries(current, dialect);
+        const wantedKeys = new Set(wanted.map(keyOf));
+        const existingKeys = new Set(existing.map(keyOf));
+        const wantedBlocks = new Set(wanted.map((entry) => pathKey([...entry.path, entry.line])));
+
+        const groups = new Map<string, Group>();
+        const groupFor = (path: string[]) => {
+            const key = pathKey(path);
+            if (!groups.has(key)) groups.set(key, { path, remove: [], add: [] });
+            return groups.get(key)!;
+        };
+
+        for (const entry of wanted) {
+            if (existingKeys.has(keyOf(entry))) continue;
+
+            // A header goes with its block's own step, never on its own.
+            const ownBlock = pathKey([...entry.path, entry.line]);
+            const opensBlock = wanted.some((other) => {
+                const deeper = other.path.length > entry.path.length;
+                return deeper && pathKey(other.path.slice(0, entry.path.length + 1)) === ownBlock;
+            });
+            if (opensBlock) continue;
+
+            groupFor(entry.path).add.push(entry.line);
+        }
+
+        // Undone in reverse order, so a line is undone before the line it depends on.
+        for (const entry of [...existing].reverse()) {
+            if (wantedKeys.has(keyOf(entry))) continue;
+
+            // Inside a block the render does not hold: undoing the header removes it.
+            const insideRemovedBlock = entry.path.some((_, depth) => {
+                const enclosing = pathKey(entry.path.slice(0, depth + 1));
+                return !wantedBlocks.has(enclosing);
+            });
+            if (insideRemovedBlock) continue;
+
+            const replaced = wanted.some((other) => {
+                const sameBlock = pathKey(other.path) === pathKey(entry.path);
+                const isNew = !existingKeys.has(keyOf(other));
+                return sameBlock && isNew && LineDiff.head(other.line) === LineDiff.head(entry.line);
+            });
+            if (!replaced) groupFor(entry.path).remove.push(entry.line);
+        }
+
+        return [...groups.values()].filter((group) => group.add.length || group.remove.length);
+    }
+
+    /**
+     * Send every line that holds a secret again, for `apply --secrets`. A device prints a secret as a cipher, so a line whose secret changed compares equal and is otherwise never sent.
+     */
+    static withSecrets(groups: Group[], desired: string, dialect: Dialect): Group[] {
+        const pathKey = (path: string[]) => path.join("\u0000");
+        const result = groups.map((group) => ({ ...group, add: [...group.add] }));
+
+        for (const entry of LineDiff.entries(desired, dialect)) {
+            if (!entry.line.includes("<secret:")) continue;
+
+            let group = result.find((candidate) => pathKey(candidate.path) === pathKey(entry.path));
+            if (!group) {
+                group = { path: entry.path, remove: [], add: [] };
+                result.push(group);
+            }
+
+            if (!group.add.includes(entry.line)) group.add.push(entry.line);
+        }
+
+        return result;
+    }
+
+    /**
+     * Replace a changed VLAN list line with only what changed.
+     *
+     * A platform keeps its VLANs as one line, such as `vlan batch 10 20 to 30`. Undoing the old line would delete VLANs still in use, so the plan adds the new IDs and removes the gone ones instead.
+     */
+    static vlanListChange(
+        groups: Group[],
+        prefix: string,
+        parse: (line: string) => number[],
+        format: (ids: number[]) => string[],
+        removal: (ids: number[]) => string[]
+    ): void {
+        const top = groups.find((group) => group.path.length === 0);
+        if (!top) return;
+
+        const old = top.remove.find((line) => line.startsWith(prefix));
+        const fresh = top.add.find((line) => line.startsWith(prefix));
+        if (!old && !fresh) return;
+
+        const before = old ? parse(old) : [];
+        const after = fresh ? parse(fresh) : [];
+
+        top.remove = top.remove.filter((line) => line !== old);
+        top.add = top.add.filter((line) => line !== fresh);
+
+        const added = after.filter((id) => !before.includes(id));
+        const removed = before.filter((id) => !after.includes(id));
+
+        // New VLANs exist before anything uses them; gone ones go after.
+        if (added.length) top.add.unshift(...format(added));
+        if (removed.length) top.remove.push(...removal(removed));
+    }
+
+    private static nothingAround(): ReturnType<Around> {
+        return { before: [], after: [] };
+    }
+
+    /** The steps for the groups: enter each block of the path, undo, add, then leave each level. */
+    static steps(groups: Group[], dialect: Dialect, around: Around = LineDiff.nothingAround): Plan["steps"] {
+        const rank = dialect.order ?? (() => 0);
+        const ordered = [...groups].sort((a, b) => rank(a.path) - rank(b.path));
+
+        return ordered.map((group): Step => {
+            const { before, after } = around(group);
+
+            const early = group.add.filter((line) => dialect.first?.test(line));
+            const late = group.add.filter((line) => !early.includes(line));
+
+            // A block header sent on its own, such as an empty `bfd`, enters its view; it is left at once so the next line is not sent into it.
+            const added = late.flatMap((line) => (dialect.block.test(line) ? [line, dialect.leave] : [line]));
+
+            const inner = [...early, ...group.remove.map(dialect.undo), ...added];
+            const leave = group.path.map(() => dialect.leave);
+
+            return {
+                title: group.path.join(" > ") || "(top level)",
+                show: [...group.remove.map((line) => `- ${line}`), ...group.add.map((line) => `+ ${line}`)],
+                send: [...before, ...group.path, ...inner, ...leave, ...after],
+            };
+        });
+    }
+
+    /** A device prints stored credentials as ciphers. They never leave the read. */
+    static scrub(text: string): string {
+        return text.replace(LineDiff.STORED_CREDENTIAL, "$1$2<redacted>");
+    }
+}

package/src/platforms/platform.ts

@@ -0,0 +1,122 @@
+import type { Neighbor } from "../core/cabling";
+import type { Device, Family } from "../schema";
+import type { ConsoleDialect } from "../transport/console";
+import type { WaitLimits } from "./bgp-wait";
+import type { PlatformName } from "./catalog";
+
+/** One part of a plan: what a reviewer reads, and what is sent. */
+export type Step = { title: string; show: string[]; send: string[] };
+
+/** The commands that turn what a device runs into what its config says. `problems` blocks an apply: something the adapter cannot converge. */
+export type Plan = { steps: Step[]; problems: string[] };
+
+export type ApplyOptions = {
+    /** Also send every secret, so a rotated value reaches the device. Secrets cannot be read back, so they are otherwise only sent when the object holding them is new. */
+    secrets: boolean;
+    /** Minutes before a platform that can restore itself does so, if the run does not prove access survived. */
+    rollback: number;
+    /** Reach the device through its serial console, `connection.console`, instead of SSH to its management address. */
+    console?: boolean;
+};
+
+/** How a device is read. */
+export type ReadOptions = Pick<ApplyOptions, "console">;
+
+/** A login on a device for commands that only read, as `circuit show` runs them. */
+export type ReadSession = {
+    /**
+     * Run one command and return what it printed, without its echo or the prompt.
+     *
+     * At `timeout` milliseconds, a command run on its own over SSH is left, and what it printed so far is returned. In a shell or on a console, where it would hold up every command after it, the run fails instead.
+     */
+    run(command: string, timeout?: number): Promise<string>;
+    /** Log out. */
+    close(): void;
+};
+
+/** How the checks after an apply reach the device, and how long they wait. */
+export type HealthOptions = ReadOptions & {
+    /** How long BGP sessions established before the apply have to be established again. `BgpWait.AFTER_APPLY` when absent. */
+    bgp?: WaitLimits;
+};
+
+/** The checks after an apply, holding what they compare against, which was read before the plan was sent. */
+export type HealthCheck = {
+    /** Run the checks. Gives one line per problem, each saying what to do; none when the device is healthy. */
+    run(): Promise<string[]>;
+};
+
+/** A BGP neighbor in the config and its live session, as `circuit bgp` shows it. A neighbor with no session is not established. */
+export type BgpSession = {
+    /** The neighbor's name in the config. */
+    neighbor: string;
+    /** The session's remote address, or `-` when there is no session. */
+    remote: string;
+    /** Whether the session is established. */
+    established: boolean;
+    /** How many prefixes it received, as the device prints it, or `-`. */
+    prefixes: string;
+    /** How long it has been up, as the device prints it, or `no session`. */
+    uptime: string;
+};
+
+/** One BGP log line: when, as the device printed it, such as `2026-10-24 03:12:44`, and the rest of the line. */
+export type BgpLogLine = { at: string; message: string };
+
+/** The operating system a platform runs, and the versions it is proved on. */
+export type OsSupport = {
+    /** Its name in full, such as `MikroTik RouterOS`. */
+    name: string;
+    /** The versions the adapter renders for, such as `7`. */
+    versions: string;
+    /** The device and version it was proved on, such as `CCR2216-1G-12XS-2XQ, RouterOS 7.23`. */
+    provedOn: string;
+    /** Whether a read or an apply refuses a device on another version. */
+    checked: boolean;
+};
+
+/** The switch rules a render makes from a device's hardware ACLs, counted. */
+export type SwitchRules = {
+    /** How many rules there are. */
+    count: number;
+    /** How many distinct port ranges they use, such as `0-1023`. */
+    ranges: number;
+};
+
+export abstract class Platform {
+    /** The name a device's `platform` field takes. */
+    abstract readonly name: PlatformName;
+    abstract readonly os: OsSupport;
+    /** File extension of a saved snapshot, for syntax highlighting. */
+    abstract readonly extension: string;
+    /** How the platform's serial console asks for a login and shows its prompt. Present when the platform can be read and applied through a console, `--console`, and opened with `circuit console`. */
+    readonly console: ConsoleDialect | undefined = undefined;
+    /** Fields this platform cannot express. Validation fails on any of them, so nothing is skipped silently. */
+    abstract unsupported(device: Device): string[];
+    /** The switch rules the render makes from the device's hardware ACLs, so `validate` can hold them to the model's limits. Absent on a platform whose rules are not counted. */
+    switchRules?(device: Device): SwitchRules;
+    /** The whole configuration the device should run. Secrets appear as markers, never values. */
+    abstract render(device: Device): string;
+    /** What the device runs now, secrets removed, in the form `render` produces where the platform allows. */
+    abstract read(device: Device, network: readonly Device[], options?: ReadOptions): Promise<string>;
+    /** The LLDP neighbors the device sees, by Circuit's port names, for `snapshot` to save. Absent on a platform whose LLDP command and its output are not proved on a device yet. */
+    neighbors?(device: Device, network: readonly Device[], options?: ReadOptions): Promise<Neighbor[]>;
+    /** What it takes to go from `current` to `desired`. */
+    abstract plan(desired: string, current: string, options: ApplyOptions): Plan;
+    /** Replace the contents of a prefix set fetched from a registry. Absent on a platform that cannot hold one. */
+    fill?(device: Device, network: readonly Device[], set: string, family: Family, prefixes: string[]): Promise<void>;
+    /** Send a plan, keeping the device reachable or restoring it. */
+    abstract apply(device: Device, network: readonly Device[], plan: Plan, options: ApplyOptions): Promise<void>;
+    /** Whether a command only reads on this platform, so `circuit show` may send it. Anything not known to only read is refused. */
+    abstract readOnly(command: string): boolean;
+    /** Log in for commands that only read, over SSH or on the console, the way the platform's read logs in. */
+    abstract session(device: Device, options?: ReadOptions): Promise<ReadSession>;
+    /** Each BGP neighbor in the config, in its order, with its live session, read over a `session()`. Absent on a platform `circuit bgp` does not support yet. */
+    bgpSessions?(device: Device, session: ReadSession): Promise<BgpSession[]>;
+    /** The device's BGP log lines from the last `minutes`, by the device's own clock, read over a `session()`. */
+    bgpLog?(session: ReadSession, minutes: number): Promise<BgpLogLine[]>;
+    /**
+     * Checks that the device is healthy after an apply, not only that it took the commands. Called before the plan is sent, to read what the checks compare against; the CLI runs them after the apply and the snapshot. Absent on a platform with no checks yet.
+     */
+    health?(device: Device, plan: Plan, options?: HealthOptions): Promise<HealthCheck>;
+}

package/src/platforms/raisecom-ros/TRAPS.md

@@ -0,0 +1,40 @@
+# Raisecom ROS traps
+
+Behaviour that looks like something else. Each one has been hit on a RAX721 running ROS 6.5.2.
+
+- Commands apply as they arrive and persist only on `write`.
+- The SSH server offers only an `ssh-rsa` host key. The adapter allows it for this platform alone; key exchange, cipher and MAC still negotiate modern ones.
+- `show running-config` stops about halfway with no error unless `terminal page-break disable` is sent first and the read waits several seconds of silence.
+- A `?` sent by a script is executed. Once it applied an address with a /8 mask.
+- An access-list cannot change while any service uses it: `ACL 1000 is in use`. Every service that uses it is unbound first and bound again after. `no ssh2 access-list` needs the list number.
+- `portswitch`, `switchport trunk allowed vlan` and `switchport mode` ask for `y` and do nothing without it, except when they need no confirming: `switchport mode trunk` on a port leaving access mode answers `Set successfully` at once, and a `y` sent after it is refused, `Error input`.
+- A VLAN is removed with `no vlan <id>`, not `no create vlan`.
+- `no storm-control mode` is refused with `Error input`. The modes are `kbps`, the default, which prints nothing, and `pps`; leaving `pps` is setting `kbps`.
+- A port's speed or duplex set to something else and back to auto prints `speed auto` and `duplex auto` from then on, though auto is the default. `no duplex auto` is refused with `Error input`.
+- Tab after a word the CLI does not know answers `Error input`, as if the line were sent. Like `?`, it is not a safe way to explore.
+- The factory account `raisecom` cannot be removed and its service type cannot change. Only its password is ours.
+- Factory SNMP communities survive hardening, and `private` can write. The render removes both.
+- Several commands are not the usual spelling: `terminal page-break disable`, `telnet-server disable`, `ip rarp server disable`.
+- An access-list description takes one word. A space is refused with `Error input`.
+- The out-of-band port `fastethernet 1/0/1` cannot be shut down and is not in the catalog.
+- A LAG is `interface port-channel N`. LACP is its default and prints nothing; a static LAG prints `mode manual`. The LAG takes layer 2 settings only after `portswitch`, and a port joins with `portswitch` then `port-channel N`.
+- An SNMPv3 user prints as localized keys, `authkey sha <hex> privkey  aes128 <hex>`, which authenticate as well as the passphrase. The read redacts them. An access group prints a `notify internet` it was not given. A user's group is removed with `no snmp-server group user <user> usm`.
+- A VRRP group is enabled once it has an address and preempts unless `no vrrp N preempt`. `no vrrp N ip <address>` removes the whole group.
+- OSPF settings for an interface sit on the interface, `ip ospf cost`, `ip ospf network ptp`, `ip ospf passive-interface enable`; passive is undone with `... disable`, not `no`.
+- `create vlan <list> active` has every VLAN on one line. A change creates only the new VLANs and removes each one that is gone with `no vlan <id>`.
+- An access-list rule is not replaced by one with the same number: the device answers `Set unsuccessfully.` and keeps the old rule. The old one is removed first. `no rule N` answers slowly, after a second or more.
+- `show running-config` can stop partway even with paging off and six seconds of silence, with no error: on 2026-10-23 three reads of an RAX721 in a row gave plans of 62, 0 and 158 commands against an unchanged switch. A dump that does not end at the prompt is read again, and after three the read fails rather than planning against a part.
+- On a lossy path a TCP retransmit can stall `show running-config` for several seconds mid-dump, and a read that stopped at the first long silence gave up after three tries (seen with 5 to 25% loss, #86). The read now waits for the dump to end at the prompt, up to 30 seconds of silence and 150 seconds in all.
+- `show lldp remote` shortens port names (`TGE1/3/3`, `100GE1/1/4`) and pads its columns, so a system name with a space cannot be told apart. The read uses `show lldp remote detail`, which spells each port in full; a long value there wraps mid-word onto a line that starts with spaces.
+- `hostname <name>` is refused in configuration mode (`Error input`) and taken only at the `#` prompt; the plan leaves configuration mode to send it. It prints as `hostname <name>` among the `enable_mode` lines. An unset hostname prints nothing, and the switch then sends `Raisecom` as its LLDP system name.
+- A Junos neighbor sends its port as a number (`PortIdSubtype: local`, `PortId: 520`), its SNMP index, and its description as `PortDesc`. The read keeps the number; matching it to a `link` needs the Junos side to send the port's name.
+- `snmp-server access-list 1001` adds a list beside `1000` rather than replacing it, and SNMP then holds both. The plan binds the new list first and then sends `no snmp-server access-list 1000`, so SNMP is never left without one. SNMP's own sources are access-list 1001.
+- `logging host <ip>` takes a level by name (`warnings`) or number and a port as `udpport <n>`, level first: `logging host <ip> udpport <n> warnings` is refused with `Error input`, `port` and `udp-port` too. It prints the level as a number and leaves out level 6 and port 514: `logging host 192.0.2.50 4 udpport 5140`. A second `logging host` for the same address changes it in place; `no logging host <ip>` removes it whatever its level and port.
+- Port security takes only a switched port: `switchport port-security` on a port without `portswitch` is refused with `Error input`. It takes a maximum of 1 to 1024; 1024 is its default and prints nothing. Its action at the limit is `protect`, drop, and learned addresses age out after 5 minutes. `no switchport port-security maximum` takes no number.
+- A MAC access-list is `access-list 3000` and up. A rule's ethertype is hex without `0x` (`0x86DD` is refused with `The EtherType is INVALID!`, and `2054` is 0x2054, not ARP); `0800` and `0806` print as `ip` and `arp`, any other as `86dd ffff`. A port binds it with `filter ingress access-list N`, which answers nothing, also on a port without `portswitch`.
+- A MAC access-list a port filters with cannot change: `ACL 3000 is in use, and it can not be modified or destroyed`. Each port has its own list, 3001 and up by its place in the catalog, and the plan unbinds the port, changes the list and binds it again.
+- `no portswitch` asks for `y` like `portswitch`; a port the plan switched stays switched when it goes back to unused, which the read cannot see.
+- OSPF BFD is `ip ospf bfd` on the VLAN interface, printed as sent and undone with `no ip ospf bfd`.
+- A static route is watched by a BFD session: `bfd N bind peer-ip <next hop> interface vlan <V>` opens the session's view, where `session enable` starts it. It prints under `!command in bfd_template_mode`, with `session enable` indented, and goes with `no bfd N`. The route takes it as `ip route <prefix> <mask> <next hop> track bfd N` and prints `track bfd-session N`; `no ip route <prefix> <mask> <next hop>` removes the route whatever it tracks. A route takes a session number that does not exist yet. Only one session binds to a peer: a second one's `session enable` answers `Error input`, so the old session goes before the new one is made. Proved on tako-mmr-01, 2026-10-24.
+- BFD timers are global, `bfd detect-multiplier N`, `bfd send-interval N` and `bfd receive-interval N`, but `send-interval` took 10 and refused 300 and 99999, so its unit and range are not known and Circuit refuses `routing.bfd` here.
+- The caret under `Error input` marks how far the CLI took a line, so sending a whole line with a made-up ending shows whether a keyword exists, without the `?` or Tab that run the line.