@takodotid/circuit 0.19.0 → 0.20.0

package/src/studio/data.ts

@@ -0,0 +1,255 @@
+// What Studio shows, gathered from the config in one pass: the graph with its findings and drift, each device as the config holds it, what each would run, the address plan, every BGP session and cable, and the schema's descriptions of each field.
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { portsOf } from "../adapters/devices/catalog";
+import { familyOf, host } from "../core/addr";
+import { type AddressReport, addressesOf } from "../core/addresses";
+import { type Annotated, type Holder, holdersOf, keyOf } from "../core/graph";
+import { SCHEMA_FILES, schemaTypes } from "../core/schema-docs";
+import type { Device } from "../schema";
+
+/** One BGP session, with its group's settings filled in, and what is at its far end. */
+export type Session = {
+    device: string;
+    name: string;
+    address: string;
+    group?: string;
+    remoteAs?: number;
+    role?: string;
+    import?: string;
+    export?: string;
+    description?: string;
+    /** One of our devices, by name, or another network, as `AS64501`. */
+    far?: string;
+    /** The far device has no session back. */
+    oneSided?: true;
+};
+
+/** One cable, from the end that names it first. */
+export type Cable = {
+    device: string;
+    port: string;
+    farDevice: string;
+    farPort: string;
+    /** The LAG each end's port is in. */
+    lag?: string;
+    farLag?: string;
+    description?: string;
+    /** VLANs carried, as `name (id)`, from the port or its LAG. */
+    vlans: string[];
+    /** The far end does not name this cable back. */
+    oneSided?: true;
+};
+
+/** A schema type's description and its fields' descriptions, by field path. */
+export type TypeDocs = {
+    description: string;
+    includes: string[];
+    fields: Record<string, { type: string; description: string }>;
+};
+
+export type StudioData = {
+    graph: Annotated;
+    devices: readonly Device[];
+    /** Every port each device's model has, in order, so Studio can show the ones the config leaves shut. */
+    ports: Record<string, string[]>;
+    /** What each device would run, as `circuit build` prints it, or why it cannot be rendered. */
+    rendered: Record<string, string>;
+    /** What each device ran when Circuit last read it, secrets removed, for the devices with a snapshot. */
+    snapshots: Record<string, string>;
+    /** Each device's file and snapshot, relative to the config, for its history. */
+    files: Record<string, DeviceFiles>;
+    addresses: AddressReport;
+    sessions: Session[];
+    cables: Cable[];
+    /** By type name. */
+    docs: Record<string, TypeDocs>;
+};
+
+function sessionsOf(devices: readonly Device[], owners: Map<string, Holder>): Session[] {
+    const all = devices.flatMap((device) => {
+        const bgp = device.routing?.bgp;
+
+        return Object.entries(bgp?.neighbors ?? {}).map(([name, neighbor]): Session & { deviceObject: Device } => {
+            const group = neighbor.group ? bgp?.groups?.[neighbor.group] : undefined;
+            const settings = { ...group, ...neighbor };
+
+            return {
+                deviceObject: device,
+                device: device.name,
+                name,
+                address: neighbor.address,
+                group: neighbor.group,
+                remoteAs: settings.remote_as,
+                role: settings.role,
+                import: settings.import,
+                export: settings.export,
+                description: settings.description,
+            };
+        });
+    });
+
+    const ownerOf = (address: string) => owners.get(keyOf(address) ?? "")?.device;
+
+    return all.map(({ deviceObject, ...session }) => {
+        const far = ownerOf(session.address);
+
+        if (far && far !== deviceObject) {
+            // The session back is one of the same family: a v4 session back does not answer a v6 session.
+            const back = all.some(
+                (other) =>
+                    other.deviceObject === far &&
+                    ownerOf(other.address) === deviceObject &&
+                    familyOf(other.address) === familyOf(session.address)
+            );
+            return { ...session, far: far.name, ...(back ? {} : { oneSided: true as const }) };
+        }
+
+        return { ...session, ...(session.remoteAs ? { far: `AS${session.remoteAs}` } : {}) };
+    });
+}
+
+function cablesOf(devices: readonly Device[]): Cable[] {
+    const byName = new Map(devices.map((device) => [device.name, device]));
+    const drawn = new Set<string>();
+    const cables: Cable[] = [];
+
+    const vlansOf = (device: Device, portName: string) => {
+        const port = device.ports?.[portName];
+        const lag = port?.lag ? device.interfaces?.[port.lag] : undefined;
+        const carrier = lag?.type === "lag" ? lag : port;
+        const names = [carrier?.access_vlan, carrier?.native_vlan, ...(carrier?.trunk_vlans ?? [])].filter((name) => name !== undefined);
+
+        return [...new Set(names)].map((name) => `${name} (${device.vlans?.[name]?.id ?? "?"})`);
+    };
+
+    for (const device of devices) {
+        for (const [portName, port] of Object.entries(device.ports ?? {})) {
+            const link = port?.link;
+            if (!port || !link) continue;
+
+            const here = `${device.name} ${portName}`;
+            const there = `${link.device} ${link.port}`;
+            if (drawn.has(`${there}|${here}`)) continue;
+            drawn.add(`${here}|${there}`);
+
+            const farPort = byName.get(link.device)?.ports?.[link.port];
+            const linksBack = farPort?.link?.device === device.name && farPort.link.port === portName;
+
+            cables.push({
+                device: device.name,
+                port: portName,
+                farDevice: link.device,
+                farPort: link.port,
+                ...(port.lag ? { lag: port.lag } : {}),
+                ...(farPort?.lag ? { farLag: farPort.lag } : {}),
+                ...(port.description ? { description: port.description } : {}),
+                vlans: vlansOf(device, portName),
+                ...(linksBack ? {} : { oneSided: true as const }),
+            });
+        }
+    }
+
+    return cables;
+}
+
+/** The directory Circuit is installed in: the nearest one up with its package.json. Its sources ship with it, in src: the schema, and the files of Studio's page. */
+export function packageRoot(): string | undefined {
+    let directory = dirname(fileURLToPath(import.meta.url));
+
+    while (true) {
+        const manifest = join(directory, "package.json");
+        if (existsSync(manifest) && JSON.parse(readFileSync(manifest, "utf8")).name === "@takodotid/circuit") return directory;
+
+        const parent = dirname(directory);
+        if (parent === directory) return undefined;
+        directory = parent;
+    }
+}
+
+/** The schema's descriptions, or none when its sources cannot be found. */
+function schemaDocs(): Record<string, TypeDocs> {
+    const root = packageRoot();
+    if (!root) return {};
+
+    const sources = SCHEMA_FILES.map(([file]) => readFileSync(join(root, "src", "schema", file), "utf8"));
+    const docs: Record<string, TypeDocs> = {};
+
+    for (const type of schemaTypes(sources).flat()) {
+        docs[type.name] = {
+            description: type.description,
+            includes: (type.includes ?? []).map((name) => name.replace(/<.*$/, "")),
+            fields: Object.fromEntries(
+                type.fields.map((field) => [field.path.replace(/\?$/, ""), { type: field.type, description: field.description }])
+            ),
+        };
+    }
+
+    return docs;
+}
+
+/** Where a device is kept, relative to the config: the file that declares it, and its snapshot. Either is absent when it cannot be found. */
+export type DeviceFiles = { source?: string; snapshot?: string };
+
+/** How Studio learns what a device would run and what it ran, from the caller, which knows the adapters and the state directory. */
+export type DeviceTexts = {
+    /** What the device would run, as `circuit build` prints it. */
+    render: (device: Device) => string;
+    /** Its last snapshot, or undefined when it has none. */
+    snapshot: (device: Device) => string | undefined;
+    /** Its file and its snapshot's file. */
+    files: (device: Device) => DeviceFiles;
+};
+
+/** Everything Studio shows. `graph` comes ready from the caller, with each device compared with its snapshot. */
+export function studioData(devices: readonly Device[], graph: Annotated, texts: DeviceTexts): StudioData {
+    const owners = new Map<string, Holder>();
+    for (const holder of holdersOf(devices)) {
+        const key = keyOf(host(holder.address))!;
+        if (!owners.has(key)) owners.set(key, holder);
+    }
+
+    const attempt = <T>(work: () => T, otherwise: (error: Error) => T) => {
+        try {
+            return work();
+        } catch (error) {
+            return otherwise(error as Error);
+        }
+    };
+
+    return {
+        graph,
+        devices,
+        ports: Object.fromEntries(
+            devices.map((device) => [
+                device.name,
+                attempt(
+                    () => portsOf(device.platform, device.model),
+                    () => []
+                ),
+            ])
+        ),
+        rendered: Object.fromEntries(
+            devices.map((device) => [
+                device.name,
+                attempt(
+                    () => texts.render(device),
+                    (error) => `Cannot be rendered: ${error.message}`
+                ),
+            ])
+        ),
+        snapshots: Object.fromEntries(
+            devices.flatMap((device) => {
+                const text = texts.snapshot(device);
+                return text === undefined ? [] : [[device.name, text]];
+            })
+        ),
+        files: Object.fromEntries(devices.map((device) => [device.name, texts.files(device)])),
+        addresses: addressesOf(devices),
+        sessions: sessionsOf(devices, owners),
+        cables: cablesOf(devices),
+        docs: schemaDocs(),
+    };
+}

package/src/studio/git.ts

@@ -0,0 +1,119 @@
+// Git, for Studio's history and comparisons: the commits that changed a device, and the network as it was at another commit or branch.
+
+import { execFile } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+
+/** One commit, as Studio lists it. */
+export type Commit = {
+    commit: string;
+    short: string;
+    author: string;
+    /** ISO 8601, with the author's time zone. */
+    date: string;
+    subject: string;
+};
+
+/** The environment without git's own variables, such as GIT_DIR in a hook, which would point git at another repository than the directory's. */
+const environment = () => Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith("GIT_")));
+
+/** Run git in a directory, and give what it printed, or fail with what it said. */
+function git(cwd: string, args: string[]): Promise<string> {
+    return new Promise((done, fail) => {
+        execFile("git", args, { cwd, env: environment(), maxBuffer: 64 * 1024 * 1024 }, (error, stdout, stderr) => {
+            if (error) fail(new Error((stderr || error.message).trim()));
+            else done(stdout);
+        });
+    });
+}
+
+const FORMAT = "--format=%H%x1f%h%x1f%an%x1f%aI%x1f%s";
+
+function commitsOf(text: string): Commit[] {
+    return text
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => {
+            const [commit = "", short = "", author = "", date = "", subject = ""] = line.split("\x1f");
+            return { commit, short, author, date, subject };
+        });
+}
+
+/** The top of the git repository the directory is in, or undefined when it is in none, or git is missing. */
+export async function gitTop(directory: string): Promise<string | undefined> {
+    try {
+        return (await git(directory, ["rev-parse", "--show-toplevel"])).trim();
+    } catch {
+        return undefined;
+    }
+}
+
+/** The latest commits that changed any of these files, relative to the directory, newest first. */
+export async function history(directory: string, files: string[], limit = 50): Promise<Commit[]> {
+    if (!files.length) return [];
+    return commitsOf(await git(directory, ["log", `-n${limit}`, FORMAT, "--", ...files]));
+}
+
+/** Branches and tags to compare with, and the latest commits. */
+export async function references(directory: string): Promise<{ names: string[]; commits: Commit[] }> {
+    const names = (
+        await git(directory, [
+            "for-each-ref",
+            "--count=100",
+            "--sort=-committerdate",
+            "--format=%(refname:short)",
+            "refs/heads",
+            "refs/remotes",
+            "refs/tags",
+        ])
+    )
+        .split("\n")
+        .filter((name) => name && !name.endsWith("/HEAD"));
+
+    return { names, commits: commitsOf(await git(directory, ["log", "-n30", FORMAT])) };
+}
+
+/** A branch, tag or commit, as the commit it names, or undefined when it names none. Only the characters a git name can hold are accepted. */
+export async function commitOf(directory: string, name: string): Promise<Commit | undefined> {
+    if (!/^[A-Za-z0-9][\w./@^~-]*$/.test(name)) return undefined;
+
+    try {
+        const [commit] = commitsOf(await git(directory, ["log", "-n1", FORMAT, `${name}^{commit}`, "--"]));
+        return commit;
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * Read the network as it was at a commit: check that commit out beside the project, in `.circuit/cache/`, which git ignores, gather it there with `gather`, then remove the checkout. The config is the file of that name in the same directory, `configDirectory`.
+ *
+ * The checkout sits inside the project, so its imports of Circuit resolve to the version installed now.
+ */
+export async function networkAt(
+    configDirectory: string,
+    configPath: string,
+    commit: string,
+    gather: (configPath: string) => Promise<string>
+): Promise<string> {
+    const top = await gitTop(configDirectory);
+    if (!top) throw new Error("the config is not in a git repository");
+
+    const cache = join(configDirectory, ".circuit", "cache");
+    mkdirSync(cache, { recursive: true });
+    writeFileSync(join(cache, ".gitignore"), "# Written by Circuit Studio: checkouts of other commits, removed once read.\n*\n");
+
+    // A checkout left behind by a run that stopped is forgotten first.
+    await git(top, ["worktree", "prune"]);
+
+    const checkout = join(cache, commit.slice(0, 12));
+    await git(top, ["worktree", "add", "--detach", "--force", checkout, commit]);
+
+    try {
+        // Where the config sits inside the repository, as git says: comparing paths would trip on two spellings of one directory, such as Windows' short names.
+        const prefix = (await git(configDirectory, ["rev-parse", "--show-prefix"])).trim();
+        return await gather(join(checkout, prefix, basename(configPath)));
+    } finally {
+        await git(top, ["worktree", "remove", "--force", checkout]).catch(() => {});
+    }
+}

package/src/studio/public/app.js

@@ -0,0 +1,147 @@
+// @ts-check
+/// <reference lib="dom" />
+// Studio's page: loads what the server gathered from the config, shows the place the address names, and loads again whenever the server says the config changed.
+
+import { byId, go } from "./dom.js";
+import { currentLayer, isLayer, setGraph, showLayer } from "./graph.js";
+import { problemCount, showTables } from "./tables.js";
+import { showTools } from "./tools.js";
+import { showCompare } from "./compare.js";
+
+/** @typedef {import("../data").StudioData} StudioData */
+
+const views = byId("views");
+const search = /** @type {HTMLInputElement} */ (byId("search"));
+const summary = byId("summary");
+const live = byId("live");
+const banner = byId("banner");
+const graphView = byId("graph-view");
+const tablesView = byId("tables-view");
+const tables = byId("tables");
+const problems = byId("problem-count");
+
+/** What the server gathered last. @type {StudioData | undefined} */
+let studio;
+/** The address last shown, so drawing the same place again keeps where the reader had scrolled to. */
+let shownRoute = "";
+
+for (const button of views.querySelectorAll("button")) {
+    const view = button.dataset.view ?? "graph";
+    button.addEventListener("click", () => go(view === "graph" ? `graph/${currentLayer()}` : view));
+}
+
+function showSummary() {
+    if (!studio) return;
+
+    const { graph } = studio;
+    const devices = studio.devices.length;
+    const errors = graph.findings.filter((finding) => finding.level === "error").length;
+    const warnings = graph.findings.length - errors;
+    const drifted = Object.values(graph.drift).filter((drift) => drift.status === "differs").length;
+
+    const count = problemCount(studio);
+    problems.textContent = count ? String(count) : "";
+
+    summary.textContent = [
+        `${devices} ${devices === 1 ? "device" : "devices"}`,
+        `${errors} ${errors === 1 ? "error" : "errors"}`,
+        `${warnings} ${warnings === 1 ? "warning" : "warnings"}`,
+        `${drifted} unlike the snapshot`,
+    ].join(" · ");
+}
+
+/** Show the place the address names, such as `#graph/bgp` or `#devices/edge-01/ports`. */
+function route() {
+    if (!studio) return;
+
+    const parts = location.hash.slice(1).split("/").map(decodeURIComponent).filter(Boolean);
+    const [view] = parts;
+
+    // An address from before the tables, such as `#bgp`, still opens that layer.
+    const isGraph = !view || view === "graph" || isLayer(view);
+    const asked = view === "graph" ? parts[1] : view;
+
+    const moved = location.hash !== shownRoute;
+    shownRoute = location.hash;
+
+    for (const button of views.querySelectorAll("button")) {
+        const pressed = isGraph ? button.dataset.view === "graph" : button.dataset.view === view;
+        button.setAttribute("aria-pressed", String(pressed));
+    }
+
+    graphView.hidden = !isGraph;
+    tablesView.hidden = isGraph;
+
+    if (view === "search") {
+        if (search.value !== (parts[1] ?? "")) search.value = parts[1] ?? "";
+    } else if (document.activeElement !== search) {
+        search.value = "";
+    }
+
+    showSummary();
+
+    if (isGraph) {
+        showLayer(isLayer(asked) ? asked : currentLayer());
+        return;
+    }
+
+    const scrolled = tables.scrollTop;
+    if (view === "tools") showTools(parts, tables, studio);
+    else if (view === "compare") showCompare(parts, tables, studio);
+    else showTables(parts, tables, studio);
+    tables.scrollTop = moved ? 0 : scrolled;
+}
+
+window.addEventListener("hashchange", route);
+
+/** @type {ReturnType<typeof setTimeout> | undefined} */
+let searching;
+
+search.addEventListener("input", () => {
+    clearTimeout(searching);
+
+    const query = search.value.trim();
+    searching = setTimeout(() => go(query ? `search/${encodeURIComponent(query)}` : "devices"), 200);
+});
+
+/** Load what Studio shows, at the start and whenever the server says the config changed. */
+async function load() {
+    /** @type {(StudioData & { error?: undefined }) | { error: string }} */
+    let next;
+
+    try {
+        next = await (await fetch("data", { cache: "no-store" })).json();
+    } catch (error) {
+        next = { error: `could not reach circuit studio: ${error instanceof Error ? error.message : String(error)}` };
+    }
+
+    if (next.error !== undefined) {
+        banner.textContent = `The config could not be read, so what is shown is the last that could:\n${next.error}`;
+        banner.hidden = false;
+        return;
+    }
+
+    banner.hidden = true;
+    studio = next;
+    setGraph(next.graph);
+    route();
+}
+
+const events = new EventSource("events");
+
+events.addEventListener("open", () => {
+    live.textContent = "live";
+    live.title = "Watching the config: a saved change shows here at once.";
+    live.classList.add("on");
+});
+
+events.addEventListener("error", () => {
+    live.textContent = "not connected";
+    live.title = "Circuit Studio is not answering. Is circuit studio still running?";
+    live.classList.remove("on");
+});
+
+// The config changed: load it again. The page itself changed, while working on Circuit: load the page again.
+events.addEventListener("message", (event) => (event.data === "page" ? location.reload() : void load()));
+
+void load();