@takodotid/circuit 0.34.3 → 0.35.0

package/src/core/cross-checks.ts

@@ -0,0 +1,364 @@
+// Rules that span devices: what one device declares about another has to agree with what the other declares.
+
+import type { Device, Gre, Port, Prefix, Routed, Switched, Vxlan } from "../schema";
+import { Address } from "./address";
+import type { Finding } from "./define";
+import { type Holder, Topology } from "./topology";
+
+export class CrossChecks {
+    /** Every rule across devices. */
+    static run(devices: readonly Device[]): Finding[] {
+        const holders = Topology.holders(devices);
+
+        // Who holds each address. The first holder wins; a second is reported by checkAddresses.
+        const owners = new Map<string, Holder>();
+        for (const holder of holders) {
+            const key = Topology.keyOf(Address.host(holder.address))!;
+            if (!owners.has(key)) owners.set(key, holder);
+        }
+
+        return [
+            ...CrossChecks.checkLinks(devices),
+            ...CrossChecks.checkAddresses(holders),
+            ...CrossChecks.checkSessions(devices, owners),
+            ...CrossChecks.checkVrrp(holders),
+            ...CrossChecks.checkTunnels(devices, owners),
+        ];
+    }
+
+    /** The VLAN ids a port or LAG carries, by how it carries them, so two ends can be compared across devices. */
+    private static carried(device: Device, settings: Switched<string>) {
+        const id = (vlan: string | undefined) => (vlan ? device.vlans?.[vlan]?.id : undefined);
+        return {
+            access: id(settings.access_vlan),
+            native: id(settings.native_vlan),
+            trunk: (settings.trunk_vlans ?? []).map(id).sort((a, b) => (a ?? 0) - (b ?? 0)),
+        };
+    }
+
+    /** How a port carries its VLANs, in words: "VLANs 10, 20 tagged and VLAN 30 untagged as native". */
+    private static describeCarried({ access, native, trunk }: ReturnType<typeof CrossChecks.carried>): string {
+        const parts: string[] = [];
+        const tagged = trunk.filter((id) => id !== undefined);
+
+        if (access !== undefined) parts.push(`VLAN ${access} untagged`);
+        if (tagged.length) parts.push(`${tagged.length === 1 ? "VLAN" : "VLANs"} ${tagged.join(", ")} tagged`);
+        if (native !== undefined) parts.push(`VLAN ${native} untagged as native`);
+
+        return parts.length ? parts.join(" and ") : "no VLANs";
+    }
+
+    /** VLAN names by id, for the VLANs a port or LAG carries. */
+    private static vlanNames(device: Device, settings: Switched<string>): Map<number, string> {
+        const names = [settings.access_vlan, settings.native_vlan, ...(settings.trunk_vlans ?? [])].filter((name) => name !== undefined);
+
+        return new Map(names.flatMap((name) => (device.vlans?.[name] ? [[device.vlans[name].id, name] as const] : [])));
+    }
+
+    /** What a port's settings are kept on: the LAG when the port is a member of one, otherwise the port. */
+    private static carrierOf(device: Device, portName: string, port: Port<string, string, string, string>) {
+        const lag = port.lag ? device.interfaces?.[port.lag] : undefined;
+        if (port.lag && lag?.type === "lag") return { name: port.lag, settings: lag };
+
+        return { name: portName, settings: port };
+    }
+
+    /** The plain addresses of one family on an interface, leaving out point-to-point ones. */
+    private static plainAddresses(settings: Routed<string>, family: string): string[] {
+        return (settings.addresses ?? []).filter(
+            (entry): entry is Prefix => typeof entry === "string" && Address.isCidr(entry) && Address.family(entry) === family
+        );
+    }
+
+    /** Why the two ends of a cable cannot reach each other by address, or undefined when they can. */
+    private static addressDisagreement(here: Routed<string>, there: Routed<string>, far: Device, farName: string): string | undefined {
+        for (const family of ["ipv4", "ipv6"]) {
+            const ours = CrossChecks.plainAddresses(here, family);
+            const theirs = CrossChecks.plainAddresses(there, family);
+            if (!ours.length || !theirs.length) continue;
+
+            // A prefix includes its length, so 10.0.0.0/24 and 10.0.0.0/25 are not one.
+            const theirPrefixes = new Set(theirs.map(Address.prefixOf));
+            if (!ours.some((address) => theirPrefixes.has(Address.prefixOf(address)))) {
+                return `has ${ours.join(", ")}, and ${far.name} ${farName} has ${theirs.join(", ")}: not one prefix of one length`;
+            }
+        }
+
+        // A point-to-point address names the far end's own address as its peer.
+        const farHosts = new Set(
+            (there.addresses ?? []).map((entry) => Topology.keyOf(Address.host(typeof entry === "string" ? entry : entry.address)))
+        );
+
+        for (const entry of here.addresses ?? []) {
+            if (typeof entry === "string" || !Topology.keyOf(entry.peer) || farHosts.has(Topology.keyOf(entry.peer))) continue;
+            return `${entry.address} names peer ${entry.peer}, which ${far.name} ${farName} does not hold`;
+        }
+
+        return undefined;
+    }
+
+    /** A link names a device and port that exist, the far end links back, and both ends carry the same VLANs the same way, with the same MTU, speed and addresses. */
+    private static checkLinks(devices: readonly Device[]): Finding[] {
+        const findings: Finding[] = [];
+        const byName = new Map(devices.map((device) => [device.name, device]));
+
+        for (const device of devices) {
+            for (const [portName, port] of Object.entries(device.ports ?? {})) {
+                const link = port?.link;
+                if (!port || !link) continue;
+
+                const report = (message: string, level: Finding["level"] = "error") =>
+                    findings.push({
+                        level,
+                        device: device.name,
+                        message: `port ${portName} link: ${message}`,
+                    });
+
+                const far = byName.get(link.device);
+                if (!far) {
+                    report(`device ${link.device} is not in the network`);
+                    continue;
+                }
+
+                const farPort = far.ports?.[link.port];
+                if (!farPort) {
+                    report(`${link.device} does not declare port ${link.port}`);
+                    continue;
+                }
+
+                const linksBack = farPort.link?.device === device.name && farPort.link.port === portName;
+                if (!linksBack) {
+                    report(`${link.device} ${link.port} does not link back to it`);
+                    continue;
+                }
+
+                const near = CrossChecks.carrierOf(device, portName, port);
+                const away = CrossChecks.carrierOf(far, link.port, farPort);
+
+                // A LAG's VLANs are on the LAG, so its member ports are compared by what their LAGs carry.
+                const inLag = near.name !== portName;
+                const farInLag = away.name !== link.port;
+                if (inLag !== farInLag) {
+                    report(
+                        inLag
+                            ? `${portName} is in ${near.name}, and ${link.device} ${link.port} is in no LAG`
+                            : `${portName} is in no LAG, and ${link.device} ${link.port} is in ${away.name}`
+                    );
+                }
+
+                const here = CrossChecks.carried(device, near.settings);
+                const there = CrossChecks.carried(far, away.settings);
+                if (JSON.stringify(here) !== JSON.stringify(there)) {
+                    report(
+                        `${near.name} carries ${CrossChecks.describeCarried(here)}, and ${link.device} ${away.name} carries ${CrossChecks.describeCarried(there)}`
+                    );
+                }
+
+                if (port.speed && farPort.speed && port.speed !== farPort.speed) {
+                    report(`speed ${port.speed}, and ${link.device} ${link.port} is ${farPort.speed}`);
+                }
+
+                const mtu = near.settings.mtu ?? 1500;
+                const farMtu = away.settings.mtu ?? 1500;
+                if (mtu !== farMtu) report(`MTU ${mtu} on ${near.name}, and ${link.device} ${away.name} has ${farMtu}`);
+
+                const disagreement = CrossChecks.addressDisagreement(near.settings, away.settings, far, away.name);
+                if (disagreement) report(`${near.name} ${disagreement}`);
+
+                // One VLAN under two names works, but reads as two VLANs.
+                const farNames = CrossChecks.vlanNames(far, away.settings);
+                for (const [id, name] of CrossChecks.vlanNames(device, near.settings)) {
+                    const farName = farNames.get(id);
+                    if (farName && farName !== name) report(`VLAN ${id} is ${name} here and ${farName} on ${link.device}`, "warning");
+                }
+            }
+        }
+
+        return findings;
+    }
+
+    /** No address is held by two devices in one VRF. Two loopbacks may hold one on purpose, for anycast, so that is a warning. */
+    private static checkAddresses(holders: Holder[]): Finding[] {
+        const findings: Finding[] = [];
+        const first = new Map<string, Holder>();
+
+        const isLoopback = (holder: Holder) => holder.device.interfaces?.[holder.name]?.type === "loopback";
+
+        for (const holder of holders) {
+            const key = `${holder.vrf ?? ""} ${Topology.keyOf(Address.host(holder.address))!}`;
+            const earlier = first.get(key);
+
+            if (!earlier) {
+                first.set(key, holder);
+                continue;
+            }
+
+            // Two on one device are reported by the device's own checks.
+            if (earlier.device === holder.device) continue;
+
+            const anycast = isLoopback(earlier) && isLoopback(holder);
+
+            findings.push({
+                level: anycast ? "warning" : "error",
+                device: holder.device.name,
+                message: `${Address.host(holder.address)} on ${holder.name} is also on ${earlier.device.name} ${earlier.name}${anycast ? ", which is right only for anycast" : ""}`,
+            });
+        }
+
+        return findings;
+    }
+
+    /** A BGP session to an address another of our devices holds needs that device's session back, in the AS it expects, from the address it names. */
+    private static checkSessions(devices: readonly Device[], owners: Map<string, Holder>): Finding[] {
+        const findings: Finding[] = [];
+
+        const sessionsOf = (device: Device) => {
+            const bgp = device.routing?.bgp;
+
+            return Object.entries(bgp?.neighbors ?? {}).map(([name, neighbor]) => {
+                const group = neighbor.group ? bgp?.groups?.[neighbor.group] : undefined;
+
+                return {
+                    name,
+                    address: neighbor.address,
+                    remoteAs: neighbor.remote_as ?? group?.remote_as,
+                    localAddress: neighbor.local_address ?? group?.local_address,
+                };
+            });
+        };
+
+        for (const device of devices) {
+            for (const session of sessionsOf(device)) {
+                const far = owners.get(Topology.keyOf(session.address) ?? "")?.device;
+                if (!far || far === device) continue;
+
+                const report = (message: string) =>
+                    findings.push({ level: "error", device: device.name, message: `neighbor ${session.name}: ${message}` });
+
+                const farBgp = far.routing?.bgp;
+                if (!farBgp) {
+                    report(`${session.address} is ${far.name}'s, which runs no BGP`);
+                    continue;
+                }
+
+                if (session.remoteAs !== undefined && session.remoteAs !== farBgp.asn) {
+                    report(`expects AS${session.remoteAs}, and ${far.name} is AS${farBgp.asn}`);
+                }
+
+                // Two routers often hold one session per family, and a session of the other family does not answer this one.
+                const back = sessionsOf(far).find(
+                    (other) =>
+                        owners.get(Topology.keyOf(other.address) ?? "")?.device === device &&
+                        Address.family(other.address) === Address.family(session.address)
+                );
+                if (!back) {
+                    report(`${far.name} has no session back to ${device.name}`);
+                    continue;
+                }
+
+                // The far end only accepts the session from the address it names.
+                if (session.localAddress && Topology.keyOf(session.localAddress) !== Topology.keyOf(back.address)) {
+                    report(`starts from ${session.localAddress}, and ${far.name}'s session ${back.name} expects ${back.address}`);
+                }
+            }
+        }
+
+        return findings;
+    }
+
+    /** On one segment, a VRRP id has one address and an address has one id, on every device. */
+    private static checkVrrp(holders: Holder[]): Finding[] {
+        const findings: Finding[] = [];
+        const bySegment = new Map<string, { holder: Holder; id: number; address: string }[]>();
+
+        for (const holder of holders) {
+            const segment = Address.prefixOf(holder.address);
+
+            for (const group of holder.vrrp) {
+                if (!Topology.keyOf(group.address) || Address.family(group.address) !== Address.family(holder.address)) continue;
+                if (!Address.contains(segment, group.address)) continue;
+
+                bySegment.set(segment, [...(bySegment.get(segment) ?? []), { holder, id: group.id, address: group.address }]);
+            }
+        }
+
+        for (const members of bySegment.values()) {
+            for (const member of members) {
+                const where = `${member.holder.device.name} ${member.holder.name}`;
+                const others = members.filter((other) => other.holder.device !== member.holder.device);
+
+                const sameId = others.find(
+                    (other) => other.id === member.id && Topology.keyOf(other.address) !== Topology.keyOf(member.address)
+                );
+                if (sameId) {
+                    findings.push({
+                        level: "error",
+                        device: member.holder.device.name,
+                        message: `VRRP ${member.id} on ${member.holder.name} is ${member.address}, and on ${sameId.holder.device.name} ${sameId.holder.name} it is ${sameId.address}`,
+                    });
+                }
+
+                const sameAddress = others.find(
+                    (other) => Topology.keyOf(other.address) === Topology.keyOf(member.address) && other.id !== member.id
+                );
+                if (sameAddress) {
+                    findings.push({
+                        level: "error",
+                        device: member.holder.device.name,
+                        message: `VRRP address ${member.address} is id ${member.id} on ${where}, and id ${sameAddress.id} on ${sameAddress.holder.device.name} ${sameAddress.holder.name}`,
+                    });
+                }
+            }
+        }
+
+        return findings;
+    }
+
+    /** A GRE or VXLAN tunnel to another of our devices has a tunnel back there, with the endpoints mirrored and, for VXLAN, the same VNI and port. */
+    private static checkTunnels(devices: readonly Device[], owners: Map<string, Holder>): Finding[] {
+        const findings: Finding[] = [];
+
+        const ends = devices.flatMap((device) =>
+            Object.entries(device.interfaces ?? {}).flatMap(([name, iface]) =>
+                iface.type === "gre" || iface.type === "vxlan" ? [{ device, name, iface: iface as Gre<string> | Vxlan<string> }] : []
+            )
+        );
+
+        const same = (a: string, b: string) => Topology.keyOf(a) !== undefined && Topology.keyOf(a) === Topology.keyOf(b);
+
+        for (const end of ends) {
+            const far = owners.get(Topology.keyOf(end.iface.remote) ?? "")?.device;
+            if (!far || far === end.device) continue;
+
+            const report = (message: string) =>
+                findings.push({ level: "error", device: end.device.name, message: `interface ${end.name}: ${message}` });
+            const kind = end.iface.type === "gre" ? "GRE" : "VXLAN";
+
+            // Two routers may run several VXLAN tunnels between them, one for each VNI, so a tunnel pairs with the one of its own VNI first.
+            const back = ends.filter(
+                (other) =>
+                    other.device === far &&
+                    other.iface.type === end.iface.type &&
+                    same(other.iface.local, end.iface.remote) &&
+                    same(other.iface.remote, end.iface.local)
+            );
+            const vniOf = (iface: Gre<string> | Vxlan<string>) => (iface.type === "vxlan" ? iface.vni : undefined);
+            const mirror = back.find((other) => vniOf(other.iface) === vniOf(end.iface)) ?? back[0];
+
+            if (!mirror) {
+                report(`${end.iface.remote} is ${far.name}'s, which has no ${kind} tunnel from there back to ${end.iface.local}`);
+                continue;
+            }
+
+            if (end.iface.type !== "vxlan" || mirror.iface.type !== "vxlan") continue;
+
+            if (end.iface.vni !== mirror.iface.vni) report(`VNI ${end.iface.vni}, and ${far.name} ${mirror.name} has ${mirror.iface.vni}`);
+
+            const port = end.iface.port ?? 4789;
+            const farPort = mirror.iface.port ?? 4789;
+            if (port !== farPort) report(`UDP port ${port}, and ${far.name} ${mirror.name} has ${farPort}`);
+        }
+
+        return findings;
+    }
+}

package/src/core/define.ts

@@ -1,4 +1,4 @@
-import type { ModelName, PlatformName, PortName } from "../adapters/devices/catalog";
+import type { ModelName, PlatformName, PortName } from "../platforms/catalog";
 import type { Device, Secret } from "../schema";
 
 /** A value resolved by name when a device is applied, from the environment or `.env` beside the config, and through 1Password when that value is an `op://` reference. Never the value itself. */
@@ -81,18 +81,41 @@ export type Network = {
     asn?: number;
     /** The BGP communities the network defines, printed by `circuit communities` for a looking glass or bgp.tools. */
     communities?: readonly Community[];
+    /**
+     * The site each device is at, such as a data centre or an office, by name. Devices ignore it.
+     *
+     * `circuit netbox` puts the device on the NetBox site of that name, and `circuit librenms` puts it in a LibreNMS device group of that name.
+     */
+    site?: (device: Device) => string;
     /** Keeps the network's PeeringDB record in step with the config: `circuit peeringdb`. Needs `asn`. */
     peeringdb?: {
         /** An API key with write access to the network's record. */
         api_key: Secret;
     };
-    /** Keeps LibreNMS monitoring every device: `circuit librenms`. */
+    /** Keeps LibreNMS monitoring every device, under its name, with its SNMP credentials and location, and in a group for its `site`: `circuit librenms`. */
     librenms?: {
         /** Where LibreNMS is, such as `https://librenms.example.com`. */
         url: string;
-        /** An API token that can add devices. */
+        /** An API token that can add and change devices and device groups. */
         api_token: Secret;
     };
+    /** Keeps NetBox in step with the config: `circuit netbox`. Needs `site`. */
+    netbox?: {
+        /** Where NetBox is, such as `https://netbox.example.com`. */
+        url: string;
+        /** An API token that can write. */
+        api_token: Secret;
+        /** What NetBox needs to know about a device that its config does not say. */
+        device: (device: Device) => NetBoxDevice;
+    };
+};
+
+/** What NetBox needs to know about a device that its config does not say. */
+export type NetBoxDevice = {
+    /** The device role's name in NetBox, such as `Core switch`. Circuit makes the role when NetBox has none of that name. */
+    role: string;
+    /** The device type's model name in NetBox, made by the platform's vendor. The device's `model` when absent. */
+    device_type?: string;
 };
 
 /** Declare the network, in `circuit.config.ts`. */

package/src/core/project-files.ts

@@ -0,0 +1,35 @@
+// A project's own TypeScript files, and which of them declares a device: for renaming a device everywhere, and for a device's history.
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+
+export class ProjectFiles {
+    /** Directories that hold no config of the project's own. */
+    private static readonly SKIPPED = new Set(["node_modules", ".git", ".circuit", "dist"]);
+
+    /** The first name written out after a call to defineDevice: the device's own, not that of another device a link, a peer or a tunnel names further on. */
+    private static readonly FIRST_NAME = /^[\s\S]*?\bname\s*:\s*(["'`])(.*?)\1/;
+
+    /** Every TypeScript file of the project, relative to its root, in name order. */
+    static sources(root: string, directory = root): string[] {
+        const entries = readdirSync(directory, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+        return entries.flatMap((entry) => {
+            if (entry.isDirectory())
+                return ProjectFiles.SKIPPED.has(entry.name) ? [] : ProjectFiles.sources(root, join(directory, entry.name));
+            return /\.(ts|mts|cts)$/.test(entry.name) ? [relative(root, join(directory, entry.name))] : [];
+        });
+    }
+
+    /** Whether a file's text declares the device: it calls defineDevice and gives it the name, written out whole. */
+    static declaresDevice(text: string, name: string): boolean {
+        return [...text.matchAll(/\bdefineDevice\s*\(/g)].some(
+            (call) => ProjectFiles.FIRST_NAME.exec(text.slice(call.index + call[0].length))?.[2] === name
+        );
+    }
+
+    /** The project files that declare the device, relative to the root. */
+    static deviceFiles(root: string, name: string, sources = ProjectFiles.sources(root)): string[] {
+        return sources.filter((file) => ProjectFiles.declaresDevice(readFileSync(join(root, file), "utf8"), name));
+    }
+}