@takodotid/circuit 0.43.1 → 1.0.0-rc.2

package/src/core/cross-checks.ts

@@ -1,369 +0,0 @@
-// 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 through the same carrier, 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;
-                }
-
-                if (link.through !== farPort.link?.through) {
-                    const say = (through: string | undefined) => (through ? `through ${through}` : "direct");
-                    report(`${say(link.through)} here, and ${say(farPort.link?.through)} on ${link.device} ${link.port}`);
-                }
-
-                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,124 +0,0 @@
-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. */
-export const secret = (name: string): Secret => ({ secret: name });
-
-/** A value read from a file when a device is applied, such as a private key in PEM. The path is relative to the config file; keep the file out of git. */
-export const secretFile = (path: string): Secret => {
-    if (!/^[A-Za-z0-9_./-]+$/.test(path)) throw new Error(`secret file path ${path} may hold only letters, digits, _ . / and -`);
-    return { secret_file: path };
-};
-
-/**
- * Declare one device.
- *
- * The names it declares (VLANs, interfaces, policies and the rest) are the only names its other fields accept, and the editor suggests them. The port names come from the model.
- */
-export function defineDevice<
-    const Platform extends PlatformName,
-    const Model extends ModelName<Platform>,
-    const Vlans extends string = never,
-    const Interfaces extends string = never,
-    const Policies extends string = never,
-    const PrefixSets extends string = never,
-    const BgpGroups extends string = never,
-    const Acls extends string = never,
-    const AddressSets extends string = never,
-    const Users extends string = never,
-    const Vrfs extends string = never,
-    const Certificates extends string = never,
-    const Tables extends string = never,
->(
-    device: Device<
-        Platform,
-        Model,
-        PortName<Platform, Model>,
-        Vlans,
-        Interfaces,
-        Policies,
-        PrefixSets,
-        BgpGroups,
-        Acls,
-        AddressSets,
-        Users,
-        Vrfs,
-        Certificates,
-        Tables
-    >
-): Device {
-    return device as unknown as Device;
-}
-
-/** Something a check found. */
-export type Finding = {
-    /** An error stops `diff` and `apply`; a warning is reported only. */
-    level: "error" | "warning";
-    /** The device it is about, when it is about one. */
-    device?: string;
-    /** What is wrong, in a sentence. */
-    message: string;
-};
-
-/** A rule of your own design, run by `validate` beside the framework's. */
-export type Check = (devices: readonly Device[]) => readonly Finding[];
-
-/**
- * One BGP community the network defines, in the community description format of the NLNOG Ring looking glass, which bgp.tools also reads.
- *
- * `community` takes `nnn` for any number, `x` for one digit and `a-b` for a range, such as `65535:0:nnn`. `description` refers to what each wildcard matched as `$0`, `$1` and so on, such as `do not announce to AS$0`.
- */
-export type Community = {
-    community: string;
-    description: string;
-};
-
-/** The whole network. */
-export type Network = {
-    /** Every device the framework manages. */
-    devices: readonly Device[];
-    /** Rules of your own design. */
-    checks?: readonly Check[];
-    /** The AS the network operates, for what is published about it. */
-    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, 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 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`. */
-export const defineNetwork = (network: Network): Network => network;

package/src/core/project-files.ts

@@ -1,35 +0,0 @@
-// 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));
-    }
-}