@takodotid/circuit 0.18.5 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.18.5",
+    "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/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];