@takodotid/circuit 0.18.5 → 0.20.0

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();

package/src/studio/public/compare.js

@@ -0,0 +1,243 @@
+// @ts-check
+/// <reference lib="dom" />
+// Comparing the network now with another branch, tag or commit: which devices changed and how their config differs, what the graph gains and loses, and what validate finds newly or no longer.
+
+import { go, h, link } from "./dom.js";
+import { compareNetworks } from "./evaluate.js";
+import { LAYER_NAMES, setComparison } from "./graph.js";
+import { deviceLink, empty, heading, lineDiff, prose, table } from "./tables.js";
+
+/** @typedef {import("../data").StudioData} StudioData */
+/** @typedef {import("../git").Commit} Commit */
+/** @typedef {{ commit: Commit, network: StudioData & { error?: undefined }, error?: undefined } | { error: string }} Comparison */
+
+/** Comparisons asked for, by the name asked for, kept while the page is open. @type {Map<string, Promise<Comparison>>} */
+const asked = new Map();
+
+/** @type {Promise<{ names: string[], commits: Commit[] } | { error: string }> | undefined} */
+let references;
+
+/**
+ * Read JSON from the server, or what went wrong.
+ *
+ * @template T
+ * @param {string} path
+ * @returns {Promise<T | { error: string }>}
+ */
+export async function fetchJson(path) {
+    try {
+        return await (await fetch(path, { cache: "no-store" })).json();
+    } catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+
+/**
+ * A commit in a line: its short name, subject, author and day.
+ *
+ * @param {Commit} commit
+ */
+export const describeCommit = (commit) =>
+    `${commit.short}, ${commit.subject}, by ${commit.author} on ${new Date(commit.date).toLocaleDateString()}`;
+
+/**
+ * The picker: a branch, tag or recent commit, or any name typed.
+ *
+ * @param {string | undefined} current
+ */
+function picker(current) {
+    const input = h("input", { type: "text", value: current ?? "", placeholder: "main, a tag, or a commit", spellcheck: "false" });
+    const list = h("select", {}, h("option", { value: "" }, "Pick one…"));
+    list.addEventListener("change", () => {
+        if (list.value) go(`compare/${encodeURIComponent(list.value)}`);
+    });
+
+    references ??= fetchJson("refs");
+    void references.then((found) => {
+        if ("error" in found) return list.replaceChildren(h("option", { value: "" }, "No git history here"));
+        const names = found.names.map((name) => h("option", { value: name }, name));
+        const commits = found.commits.map((commit) => h("option", { value: commit.commit }, describeCommit(commit)));
+        list.append(h("optgroup", { label: "Branches and tags" }, ...names), h("optgroup", { label: "Latest commits" }, ...commits));
+    });
+
+    const compare = h("button", { type: "submit", class: "primary" }, "Compare");
+    compare.addEventListener("click", (event) => {
+        event.preventDefault();
+        if (input.value.trim()) go(`compare/${encodeURIComponent(input.value.trim())}`);
+    });
+
+    return h(
+        "form",
+        { class: "tool-form" },
+        h("label", { class: "field" }, h("span", {}, "Branch, tag or commit"), list),
+        h("label", { class: "field" }, h("span", {}, "Or a name"), input),
+        compare
+    );
+}
+
+/**
+ * @param {HTMLElement} area
+ * @param {string} name
+ * @param {Commit} commit
+ * @param {StudioData} before
+ * @param {StudioData} after
+ */
+function showDifferences(area, name, commit, before, after) {
+    const found = compareNetworks(before, after);
+    const { devices, edges, findings } = found;
+    const nothing =
+        !devices.added.length && !devices.removed.length && !devices.changed.length && !edges.added.length && !edges.removed.length;
+
+    const layers = [...new Set([...edges.added, ...edges.removed].map((edge) => edge.layer))];
+    const showGraph = link("Show the changes in the graph", () => {
+        setComparison({ name, added: edges.added, removed: edges.removed });
+        go(`graph/${layers[0] ?? "l1"}`);
+    });
+
+    area.append(
+        h("p", {}, "Your files now, beside ", h("strong", {}, name), `: ${describeCommit(commit)}.`),
+        nothing
+            ? empty("Nothing differs: every device would run the same, and the graph is the same.")
+            : h(
+                  "p",
+                  {},
+                  `${devices.changed.length} changed, ${devices.added.length} added and ${devices.removed.length} removed ${devices.changed.length + devices.added.length + devices.removed.length === 1 ? "device" : "devices"}; ${edges.added.length} ${edges.added.length === 1 ? "line" : "lines"} of the graph added and ${edges.removed.length} gone. `,
+                  layers.length ? showGraph : undefined
+              )
+    );
+
+    if (devices.added.length || devices.removed.length) {
+        area.append(
+            heading("Devices added and removed"),
+            table({
+                head: ["Device", "Change"].map((label) => ({ label })),
+                rows: [
+                    ...devices.added.map((device) => ({ cells: [deviceLink(device), "added"] })),
+                    ...devices.removed.map((device) => ({ cells: [device, "removed"] })),
+                ],
+            })
+        );
+    }
+
+    if (devices.changed.length) {
+        area.append(
+            heading("Config that changes"),
+            prose(
+                "What each device would run, ",
+                h("span", { class: "removed" }, "then -"),
+                " and ",
+                h("span", { class: "added" }, "now +"),
+                "."
+            )
+        );
+
+        for (const device of devices.changed) {
+            area.append(
+                h(
+                    "details",
+                    { class: "change" },
+                    h("summary", {}, device),
+                    lineDiff(before.rendered[device] ?? "", after.rendered[device] ?? "")
+                )
+            );
+        }
+    }
+
+    if (edges.added.length || edges.removed.length) {
+        const nameOf = (/** @type {string} */ id) =>
+            [...after.graph.nodes, ...before.graph.nodes].find((node) => node.id === id)?.label ?? id;
+
+        area.append(
+            heading("The graph"),
+            table({
+                csv: `compare-${name}-graph`,
+                head: ["Layer", "Change", "What", "From", "To"].map((label) => ({ label })),
+                rows: [
+                    ...edges.added.map((edge) => ({
+                        cells: [
+                            LAYER_NAMES[edge.layer],
+                            h("span", { class: "added" }, "added"),
+                            edge.label,
+                            nameOf(edge.from),
+                            nameOf(edge.to),
+                        ],
+                    })),
+                    ...edges.removed.map((edge) => ({
+                        cells: [
+                            LAYER_NAMES[edge.layer],
+                            h("span", { class: "removed" }, "gone"),
+                            edge.label,
+                            nameOf(edge.from),
+                            nameOf(edge.to),
+                        ],
+                    })),
+                ],
+            })
+        );
+    }
+
+    if (findings.added.length || findings.resolved.length) {
+        area.append(
+            h("h3", {}, "Found by ", h("code", {}, "circuit validate")),
+            table({
+                head: ["", "Device", "Message"].map((label) => ({ label })),
+                rows: [
+                    ...findings.added.map((one) => ({
+                        cells: [h("span", { class: "removed" }, `new ${one.level}`), one.device ?? "the network", one.message],
+                    })),
+                    ...findings.resolved.map((one) => ({
+                        cells: [h("span", { class: "added" }, `no longer`), one.device ?? "the network", one.message],
+                    })),
+                ],
+            })
+        );
+    }
+}
+
+/**
+ * Draw the comparison the address names, such as `["compare", "main"]`, into a container.
+ *
+ * @param {string[]} route
+ * @param {HTMLElement} container
+ * @param {StudioData} now
+ */
+export function showCompare(route, container, now) {
+    container.replaceChildren();
+    const [, name] = route;
+
+    container.append(
+        heading("Compare", "h2"),
+        prose(
+            "Your files now, beside another branch, tag or commit: which devices change and how, what the graph gains and loses, and what ",
+            h("code", {}, "circuit validate"),
+            " finds newly or no longer. Studio reads the other commit with the Circuit installed now."
+        ),
+        picker(name)
+    );
+
+    if (!name) return;
+
+    const area = h("div", {}, empty(`Reading the network at ${name}…`));
+    container.append(area);
+
+    if (!asked.has(name)) asked.set(name, /** @type {Promise<Comparison>} */ (fetchJson(`compare?ref=${encodeURIComponent(name)}`)));
+    const shown = location.hash;
+
+    void asked.get(name)?.then((result) => {
+        // The reader may have gone elsewhere while it was read.
+        if (location.hash !== shown) return;
+        area.replaceChildren();
+
+        if (result.error !== undefined) {
+            asked.delete(name);
+            return area.append(empty(`It could not be read: ${result.error}`));
+        }
+
+        if (result.network.error !== undefined) {
+            asked.delete(name);
+            return area.append(empty(`Its config could not be read: ${result.network.error}`));
+        }
+
+        showDifferences(area, name, result.commit, result.network, now);
+    });
+}

package/src/studio/public/diff.js

@@ -0,0 +1,97 @@
+// @ts-check
+// A line diff, after Myers' "An O(ND) Difference Algorithm": the fewest lines added and removed that turn one text into another.
+
+/** @typedef {{ kind: "same" | "removed" | "added", text: string }} DiffLine */
+
+/** Past this many differences, two texts are too far apart to show line by line. */
+const MOST_DIFFERENCES = 4000;
+
+/**
+ * The lines of `before` and `after` in order, each marked as kept, removed or added. Undefined when they differ in more than a few thousand lines.
+ *
+ * @param {readonly string[]} before
+ * @param {readonly string[]} after
+ * @returns {DiffLine[] | undefined}
+ */
+export function diffLines(before, after) {
+    const n = before.length;
+    const m = after.length;
+    const limit = Math.min(n + m, MOST_DIFFERENCES);
+    const offset = limit + 1;
+
+    // How far along `before` each diagonal reaches, and a copy of that for each number of differences, to walk back through.
+    const reach = new Int32Array(2 * offset + 1);
+    /** @type {Int32Array[]} */
+    const trace = [];
+
+    /**
+     * Where diagonal k reached after d differences.
+     *
+     * @param {number} d
+     * @param {number} k
+     */
+    const reached = (d, k) => /** @type {Int32Array} */ (trace[d])[k + d] ?? 0;
+
+    for (let d = 0; d <= limit; d++) {
+        for (let k = -d; k <= d; k += 2) {
+            const down = k === -d || (k !== d && (reach[k - 1 + offset] ?? 0) < (reach[k + 1 + offset] ?? 0));
+            let x = down ? (reach[k + 1 + offset] ?? 0) : (reach[k - 1 + offset] ?? 0) + 1;
+            let y = x - k;
+
+            while (x < n && y < m && before[x] === after[y]) {
+                x++;
+                y++;
+            }
+
+            reach[k + offset] = x;
+
+            if (x >= n && y >= m) {
+                trace.push(reach.slice(offset - d, offset + d + 1));
+                return walkBack(before, after, trace, reached);
+            }
+        }
+
+        trace.push(reach.slice(offset - d, offset + d + 1));
+    }
+
+    return undefined;
+}
+
+/**
+ * The edits, found by walking back from the end through what each step reached.
+ *
+ * @param {readonly string[]} before
+ * @param {readonly string[]} after
+ * @param {Int32Array[]} trace
+ * @param {(d: number, k: number) => number} reached
+ * @returns {DiffLine[]}
+ */
+function walkBack(before, after, trace, reached) {
+    /** @type {DiffLine[]} */
+    const lines = [];
+    let x = before.length;
+    let y = after.length;
+
+    for (let d = trace.length - 1; d > 0; d--) {
+        const k = x - y;
+        const down = k === -d || (k !== d && reached(d - 1, k - 1) < reached(d - 1, k + 1));
+        const previousK = down ? k + 1 : k - 1;
+        const previousX = reached(d - 1, previousK);
+        const previousY = previousX - previousK;
+
+        while (x > previousX && y > previousY) {
+            lines.push({ kind: "same", text: before[--x] ?? "" });
+            y--;
+        }
+
+        if (down) lines.push({ kind: "added", text: after[--y] ?? "" });
+        else lines.push({ kind: "removed", text: before[--x] ?? "" });
+    }
+
+    while (x > 0 && y > 0) {
+        lines.push({ kind: "same", text: before[--x] ?? "" });
+        y--;
+    }
+
+    return lines.reverse();
+}

package/src/studio/public/dom.js

@@ -0,0 +1,108 @@
+// @ts-check
+/// <reference lib="dom" />
+// Small helpers every part of Studio's page uses: making elements, links that act, and browser storage that may be missing.
+
+const SVG = "http://www.w3.org/2000/svg";
+
+/** @typedef {Node | string | undefined | false} Child */
+
+/**
+ * An element with attributes and children. Text is always set as text, never parsed as HTML.
+ *
+ * @template {keyof HTMLElementTagNameMap} K
+ * @param {K} tag
+ * @param {Record<string, string>} [attributes]
+ * @param {...Child} children
+ * @returns {HTMLElementTagNameMap[K]}
+ */
+export function h(tag, attributes = {}, ...children) {
+    const element = document.createElement(tag);
+    for (const [name, value] of Object.entries(attributes)) element.setAttribute(name, value);
+    for (const child of children) if (child !== undefined && child !== false) element.append(child);
+    return element;
+}
+
+/**
+ * An SVG element with attributes.
+ *
+ * @template {keyof SVGElementTagNameMap} K
+ * @param {K} tag
+ * @param {Record<string, string | number>} [attributes]
+ * @returns {SVGElementTagNameMap[K]}
+ */
+export function s(tag, attributes = {}) {
+    const element = document.createElementNS(SVG, tag);
+    for (const [name, value] of Object.entries(attributes)) element.setAttribute(name, String(value));
+    return element;
+}
+
+/**
+ * A link that runs an action, by mouse or keyboard.
+ *
+ * @param {string} text
+ * @param {() => void} action
+ */
+export function link(text, action) {
+    const anchor = h("a", { role: "button", tabindex: "0" }, text);
+    anchor.addEventListener("click", action);
+    anchor.addEventListener("keydown", (event) => event.key === "Enter" && action());
+    return anchor;
+}
+
+/**
+ * The element with this id, which index.html always has.
+ *
+ * @param {string} id
+ */
+export function byId(id) {
+    const element = document.getElementById(id);
+    if (!(element instanceof HTMLElement)) throw new Error(`index.html has no element ${id}`);
+    return element;
+}
+
+/**
+ * The SVG element with this id, which index.html always has.
+ *
+ * @param {string} id
+ */
+export function svgById(id) {
+    const element = document.getElementById(id);
+    if (!(element instanceof SVGElement)) throw new Error(`index.html has no SVG element ${id}`);
+    return element;
+}
+
+/** Browser storage can be missing or refuse, in a private window for example. The page works without it. */
+export const store = {
+    /**
+     * @template T
+     * @param {string} key
+     * @returns {T | undefined}
+     */
+    get(key) {
+        try {
+            const value = localStorage.getItem(`circuit-studio:${key}`);
+            return value === null ? undefined : /** @type {T} */ (JSON.parse(value));
+        } catch {
+            return undefined;
+        }
+    },
+
+    /**
+     * @param {string} key
+     * @param {unknown} value
+     */
+    set(key, value) {
+        try {
+            localStorage.setItem(`circuit-studio:${key}`, JSON.stringify(value));
+        } catch {}
+    },
+};
+
+/**
+ * Go to a place in Studio, such as `graph/bgp` or `devices/edge-01/ports`. The place is the address's fragment, so the back button and a bookmark work.
+ *
+ * @param {string} route
+ */
+export function go(route) {
+    location.hash = route;
+}