@takodotid/circuit 0.18.4 → 0.19.0

package/dist/types/core/graph.d.ts

@@ -0,0 +1,44 @@
+import type { Device } from "../schema";
+/** One view of the network. Every edge belongs to one. */
+export type Layer = "l1" | "l2" | "l3" | "bgp" | "ospf" | "tunnels";
+export declare const LAYERS: readonly Layer[];
+/** One of our devices, a segment several of them share, or something outside the network. */
+export type GraphNode = {
+    /** Unique among the nodes, such as `device:edge-01` or `as:64501`. */
+    id: string;
+    kind: "device" | "segment" | "outside";
+    /** A word or two, drawn on the node. */
+    label: string;
+    /** One fact per line, for a closer look. */
+    detail: string[];
+};
+/** A VLAN a cable carries. */
+export type CarriedVlan = {
+    name: string;
+    id: number;
+    /** Carried without a tag: the access VLAN, or a trunk's native VLAN. */
+    untagged: boolean;
+};
+export type GraphEdge = {
+    layer: Layer;
+    /** Node ids. */
+    from: string;
+    to: string;
+    /** A few words, drawn on the edge. */
+    label: string;
+    /** One fact per line, for a closer look. */
+    detail: string[];
+    /** Only one end declares it: the far device does not declare the cable, session or tunnel back. */
+    oneSided?: true;
+    /** On `l2`, the VLANs the cable carries. */
+    vlans?: CarriedVlan[];
+};
+export type Graph = {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+};
+export declare const deviceId: (name: string) => string;
+/** The network as a graph. It reads the config only, never a device, and works on a config that does not validate. */
+export declare function graphOf(devices: readonly Device[]): Graph;
+/** Only the edges on these layers, and among those only the ones that touch these devices when any are named. Every device named stays. */
+export declare function only(graph: Graph, layers: readonly Layer[], deviceNames?: readonly string[]): Graph;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.18.4",
+    "version": "0.19.0",
     "description": "Declarative, vendor-neutral network configuration: describe each device in TypeScript, and Circuit makes the device match. Alpha.",
     "keywords": [
         "network",

package/src/adapters/devices/routeros/TRAPS.md

@@ -15,6 +15,7 @@ Behaviour that looks like something else. Each one has been hit on a real device
 - Incoming GRE is subject to the input chain. Accept it before testing the tunnel.
 - A WireGuard peer's name is unique on the device, and a new key under the same name is refused as a new peer, `entry with this name already exists`. The plan finds a peer by name, so a new key is a `set`.
 - `monitor-traffic` on a VLAN interface counts only what the CPU handles, and not consistently: during a flood a VLAN showed 14 Mbps leaving while its physical port sent 0.45 Mbps. Measure on the physical port, `/interface ethernet print stats`, which the switch chip counts.
+- A VLAN interface on the bridge adds a dynamic bridge VLAN entry for its VLAN, "added by vlan on bridge", beside the static one. A selector by `vlan-ids` then finds both, and a `set` on the pair fails with `no such item`. Selectors on bridge VLANs skip dynamic entries.
 - Switch-chip rules have no address lists and no connection state. A drop is an empty `new-dst-ports`.
 - A switch-chip rule's `rate` did not limit traffic the CPU routes. On a CCR2216 on 7.23.5, under a 12 Gbps flood, a rule at `2G` and then at `100M` changed nothing that reached the CPU, while a drop with the same match left 3 Mbps. Drop what you can recognise instead of limiting it.
 - The switch chip reads a UDP fragment after the first as port 0. `src-port=0` drops the rest of a fragmented flood whose first fragments another rule dropped by port; without it they reach the CPU, which holds them waiting for a first fragment that never comes.

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

@@ -80,6 +80,7 @@ const DYNAMIC = new Set([
     "/ip firewall raw",
     "/ipv6 firewall raw",
     "/ip dhcp-server lease",
+    "/interface bridge vlan",
 ]);
 
 /** Quote a value for a command. */

package/src/cli/graph.ts

@@ -0,0 +1,103 @@
+// What `circuit graph` prints: the graph of the network with what `validate` found and how each device compares with its last snapshot, as Mermaid, DOT or JSON.
+
+import type { Finding } from "../core/define";
+import { deviceId, type Graph, type GraphNode } from "../core/graph";
+
+/** How a device compares with its last snapshot, found offline as `diff` finds it. */
+export type Drift = {
+    status: "matches" | "differs" | "no snapshot" | "cannot plan";
+    /** The plan `diff` would show, when it differs. */
+    lines: string[];
+};
+
+export type Annotated = Graph & {
+    findings: Finding[];
+    /** By device name. */
+    drift: Record<string, Drift>;
+};
+
+/** `error` when validate found an error on the device, `warning` for a warning or a difference from its snapshot. */
+export function markOf(graph: Annotated, node: GraphNode): "error" | "warning" | undefined {
+    if (node.kind !== "device") return undefined;
+
+    const findings = graph.findings.filter((finding) => finding.device && deviceId(finding.device) === node.id);
+    if (findings.some((finding) => finding.level === "error")) return "error";
+
+    const drift = graph.drift[node.label]?.status;
+    if (findings.length || drift === "differs" || drift === "cannot plan") return "warning";
+
+    return undefined;
+}
+
+/** Mermaid, which GitHub draws wherever Markdown is shown. */
+export function mermaid(graph: Annotated): string {
+    const ids = new Map(graph.nodes.map((node, index) => [node.id, `n${index}`]));
+    // Lines of text, each escaped, as one quoted label.
+    const text = (...lines: string[]) =>
+        `"${lines.map((line) => line.replace(/"/g, "#quot;").replace(/</g, "#lt;").replace(/>/g, "#gt;")).join("<br/>")}"`;
+
+    const shapes: Record<GraphNode["kind"], (label: string) => string> = {
+        device: (label) => `[${label}]`,
+        segment: (label) => `([${label}])`,
+        outside: (label) => `{{${label}}}`,
+    };
+
+    const lines = ["graph LR"];
+
+    for (const node of graph.nodes) {
+        const label = node.kind === "device" ? text(node.label, node.detail[0] ?? "") : text(node.label);
+        lines.push(`    ${ids.get(node.id)}${shapes[node.kind](label)}`);
+    }
+
+    for (const edge of graph.edges) {
+        const arrow = edge.oneSided ? "-.-" : "---";
+        lines.push(`    ${ids.get(edge.from)} ${arrow}|${text(edge.label)}| ${ids.get(edge.to)}`);
+    }
+
+    lines.push(
+        "    classDef error stroke:#d1242f,stroke-width:3px",
+        "    classDef warning stroke:#bf8700,stroke-width:3px",
+        "    classDef outside stroke-dasharray:4 3"
+    );
+
+    for (const node of graph.nodes) {
+        const mark = markOf(graph, node) ?? (node.kind === "outside" ? "outside" : undefined);
+        if (mark) lines.push(`    class ${ids.get(node.id)} ${mark}`);
+    }
+
+    return lines.join("\n") + "\n";
+}
+
+/** DOT, which Graphviz turns into an image: `circuit graph --format=dot | dot -Tsvg > network.svg`. */
+export function dot(graph: Annotated): string {
+    const text = (value: string) => `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+    const colors = { error: "#d1242f", warning: "#bf8700" };
+
+    const shapes: Record<GraphNode["kind"], string> = {
+        device: "shape=box, style=rounded",
+        segment: "shape=ellipse",
+        outside: "shape=box, style=dashed",
+    };
+
+    const lines = [
+        "graph network {",
+        "    rankdir=LR;",
+        '    node [fontname="Helvetica"];',
+        '    edge [fontname="Helvetica", fontsize=10];',
+    ];
+
+    for (const node of graph.nodes) {
+        const label = node.kind === "device" ? `${node.label}\n${node.detail[0] ?? ""}` : node.label;
+        const mark = markOf(graph, node);
+        const color = mark ? `, color=${text(colors[mark])}, penwidth=2` : "";
+        lines.push(`    ${text(node.id)} [label=${text(label)}, ${shapes[node.kind]}${color}];`);
+    }
+
+    for (const edge of graph.edges) {
+        const style = edge.oneSided ? ", style=dashed" : "";
+        lines.push(`    ${text(edge.from)} -- ${text(edge.to)} [label=${text(edge.label)}${style}];`);
+    }
+
+    lines.push("}");
+    return lines.join("\n") + "\n";
+}

package/src/cli/index.ts

@@ -12,9 +12,11 @@ import { planPeeringDb, sendPeeringDb } from "../adapters/registries/peeringdb";
 import { prometheusTargets, snmpExporterAuths } from "../adapters/registries/prometheus";
 import { network as prefixOf } from "../core/addr";
 import type { Network } from "../core/define";
+import { graphOf, LAYERS, only, type Layer } from "../core/graph";
 import { isSecret, referenceOf, resolve as reveal, sourceOf, useRoot } from "../core/secrets";
 import { validate } from "../core/validate";
 import type { Device } from "../schema";
+import { type Annotated, dot, type Drift, mermaid } from "./graph";
 
 const HELP = `usage: circuit <command> [device...] [options]
 
@@ -35,6 +37,12 @@ const HELP = `usage: circuit <command> [device...] [options]
   prometheus            every device with SNMP, as Prometheus targets for snmp_exporter
                           --auths        snmp_exporter's auths for them instead, with secrets as \${NAME}
   secrets               every secret the config uses, and whether each can be read
+  graph [device...]     the network as a graph, from the config alone, without contacting a device
+                          --layer=l1     l1, l2, l3, bgp, ospf or tunnels, several with commas, or all
+                          --format=mermaid  mermaid, dot or json
+  studio                the graph in the browser, drawn again whenever the config changes
+                          --port=4600    the port it listens on, on this machine only
+                          --no-open      do not open the browser
 
   --config <path>       the network's config file, circuit.config.ts in the working directory by default`;
 
@@ -395,6 +403,65 @@ ${references.length} secret(s), ${missing} missing.`);
     process.exit(missing ? 1 : 0);
 }
 
+/** The value of `--name=value`, or undefined when it is not given. */
+const flagValue = (name: string) => flags.find((flag) => flag.startsWith(`--${name}=`))?.slice(name.length + 3);
+
+/** How a device compares with its last snapshot, offline, as `diff` plans it. */
+function driftOf(device: Device): Drift {
+    const path = statePath(device);
+    if (!existsSync(path)) return { status: "no snapshot", lines: [] };
+
+    try {
+        const adapter = adapterOf(device);
+        const plan = adapter.plan(adapter.render(device), readFileSync(path, "utf8"), options);
+
+        const lines = [
+            ...plan.steps.flatMap((step) => [step.title, ...step.show.map((line) => `  ${line}`)]),
+            ...plan.problems.map((problem) => `PROBLEM ${problem}`),
+        ];
+
+        return { status: lines.length ? "differs" : "matches", lines };
+    } catch (error) {
+        return { status: "cannot plan", lines: [(error as Error).message] };
+    }
+}
+
+function graphCommand(): void {
+    const requested = (flagValue("layer") ?? "l1").split(",");
+    const layers = requested.includes("all") ? [...LAYERS] : (requested as Layer[]);
+
+    const unknown = layers.filter((layer) => !LAYERS.includes(layer));
+    if (unknown.length) fail(`no layer ${unknown.join(", ")}; known: ${LAYERS.join(", ")}, all`);
+
+    const format = flagValue("format") ?? "mermaid";
+    const devices = selected(true);
+
+    const graph = only(graphOf(network.devices), layers, names.length ? devices.map((device) => device.name) : []);
+    const shown = new Set(graph.nodes.map((node) => node.label));
+
+    // Each device drawn is compared with its snapshot; findings are kept for those, and for the network as a whole.
+    const annotated: Annotated = {
+        ...graph,
+        findings: validate(network).filter((finding) => !finding.device || shown.has(finding.device)),
+        drift: Object.fromEntries(
+            network.devices.filter((device) => shown.has(device.name)).map((device) => [device.name, driftOf(device)])
+        ),
+    };
+
+    if (format === "mermaid") process.stdout.write(mermaid(annotated));
+    else if (format === "dot") process.stdout.write(dot(annotated));
+    else if (format === "json") console.log(JSON.stringify(annotated, null, 4));
+    else fail(`no format ${format}; known: mermaid, dot, json`);
+}
+
+async function studioCommand(): Promise<void> {
+    const port = Number(flagValue("port") ?? 4600);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) fail("--port takes a number from 1 to 65535");
+
+    const { studio } = await import("./studio");
+    await studio({ configPath, root, port, open: !flags.includes("--no-open") });
+}
+
 const commands: Record<string, () => void | Promise<void>> = {
     validate: validateCommand,
     build: buildCommand,
@@ -408,6 +475,8 @@ const commands: Record<string, () => void | Promise<void>> = {
     librenms: librenmsCommand,
     prometheus: prometheusCommand,
     secrets: secretsCommand,
+    graph: graphCommand,
+    studio: studioCommand,
 };
 
 const run = commands[command];