@takodotid/circuit 0.43.1 → 1.0.0-rc.2

package/src/core/topology.ts

@@ -1,64 +1,11 @@
-// The network as a graph, read from the config alone: cables, the VLANs they carry, shared segments, BGP sessions, OSPF adjacencies and tunnels. `circuit graph` prints it and `circuit studio` draws it.
+// The network as a graph, read from the project alone: cables, the VLANs they carry, shared segments, BGP sessions, OSPF adjacencies and tunnels. `circuit studio` draws it.
 
-import type { Device, Gre, Routed, Switched, Vxlan, WireGuardPeer } from "../schema";
-import type { Finding } from "./define";
+import type { Device, Gre, Port, Routed, Switched, Vrrp, Vxlan, WireGuardPeer } from "../model";
+import { Derive } from "../platforms/derive";
 import { Address } from "./address";
+import type { CarriedVlan, Graph, GraphEdge, GraphNode, Layer } from "./graph";
 
-/** One view of the network. Every edge belongs to one. */
-export type Layer = "l1" | "l2" | "l3" | "bgp" | "ospf" | "tunnels";
-
-/** One of our devices, a segment several of them share, or something outside the network. */
-export type GraphNode = {
-    /** Unique among the nodes, such as `device:edge-01` or `as:64501`. */
-    id: string;
-    kind: "device" | "segment" | "outside";
-    /** A word or two, drawn on the node. */
-    label: string;
-    /** One fact per line, for a closer look. */
-    detail: string[];
-};
-
-/** A VLAN a cable carries. */
-export type CarriedVlan = {
-    name: string;
-    id: number;
-    /** Carried without a tag: the access VLAN, or a trunk's native VLAN. */
-    untagged: boolean;
-};
-
-export type GraphEdge = {
-    layer: Layer;
-    /** Node ids. */
-    from: string;
-    to: string;
-    /** A few words, drawn on the edge. */
-    label: string;
-    /** One fact per line, for a closer look. */
-    detail: string[];
-    /** Only one end declares it: the far device does not declare the cable, session or tunnel back. */
-    oneSided?: true;
-    /** On `l2`, the VLANs the cable carries. */
-    vlans?: CarriedVlan[];
-};
-
-export type Graph = {
-    nodes: GraphNode[];
-    edges: GraphEdge[];
-};
-
-/** 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[];
-};
-
-/** The graph with what `validate` found and how each device drawn compares with its snapshot. */
-export type Annotated = Graph & {
-    findings: Finding[];
-    /** By device name. */
-    drift: Record<string, Drift>;
-};
+export type { CarriedVlan, Graph, GraphEdge, GraphNode, Layer } from "./graph";
 
 /** An address one of the devices holds on a port or interface. */
 export type Holder = {
@@ -69,8 +16,8 @@ export type Holder = {
     address: string;
     /** The far end of a point-to-point address. */
     peer?: string;
-    vrrp: NonNullable<Routed<string>["vrrp"]>;
-    /** The VRF the address is in. The default table when absent. */
+    vrrp: readonly Vrrp[];
+    /** The VRF the address is in. The main table when absent. */
     vrf?: string;
 };
 
@@ -112,14 +59,12 @@ export class Topology {
         return len === Address.bits(family);
     }
 
-    /** Ports, then interfaces, that can hold an address. */
-    static routedOf(device: Device): [string, Routed<string>][] {
-        const ports = Object.entries(device.ports ?? {}).flatMap(([name, port]) =>
-            port ? [[name, port] as [string, Routed<string>]] : []
-        );
-        const interfaces = Object.entries(device.interfaces ?? {}) as [string, Routed<string>][];
-
-        return [...ports, ...interfaces];
+    /** Ports, then every other interface, that can hold an address. */
+    static routedOf(device: Device): [string, Routed][] {
+        return [
+            ...Derive.ports(device).map(([name, port]) => [name, port] as [string, Routed]),
+            ...Derive.interfaces(device).map(({ name, settings }) => [name, settings as Routed] as [string, Routed]),
+        ];
     }
 
     /** Every valid address the devices hold. An invalid one is left for `validate` to report. */
@@ -130,19 +75,38 @@ export class Topology {
                     const address = typeof entry === "string" ? entry : entry.address;
                     if (!Address.isCidr(address)) return [];
 
-                    const peer = typeof entry === "string" ? undefined : entry.peer;
-                    return [{ device, name, address, peer, vrrp: settings.vrrp ?? [], vrf: settings.vrf }];
+                    const peer = typeof entry === "string" ? undefined : entry.peer_address;
+                    return [
+                        {
+                            device,
+                            name,
+                            address,
+                            vrrp: settings.vrrp ?? [],
+                            ...(peer ? { peer } : {}),
+                            ...(settings.vrf ? { vrf: settings.vrf } : {}),
+                        },
+                    ];
                 })
             )
         );
     }
 
+    /** Who holds each address: the first holder of it. */
+    static owners(holders: readonly Holder[]): Map<string, Holder> {
+        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 owners;
+    }
+
     private static describeDevice(device: Device): string[] {
         const addresses = Topology.routedOf(device)
             .filter(([, settings]) => settings.addresses?.length)
             .map(([name, settings]) => {
                 const list = (settings.addresses ?? []).map((entry) =>
-                    typeof entry === "string" ? entry : `${entry.address} to ${entry.peer}`
+                    typeof entry === "string" ? entry : `${entry.address} to ${entry.peer_address}`
                 );
                 const vrf = settings.vrf ? `, VRF ${settings.vrf}` : "";
                 return `${name}: ${list.join(", ")}${vrf}`;
@@ -155,10 +119,10 @@ export class Topology {
         ];
     }
 
-    /** The VLANs a port or LAG carries, by id. */
-    private static carriedBy(device: Device, settings: Switched<string> | undefined): CarriedVlan[] {
+    /** The VLANs a port or LAG carries, by ID. */
+    static carriedBy(device: Device, settings: Switched | undefined): CarriedVlan[] {
         const vlan = (name: string | undefined, untagged: boolean): CarriedVlan[] => {
-            const id = name ? device.vlans?.[name]?.id : undefined;
+            const id = name ? device.switching?.vlans?.[name]?.id : undefined;
             return name && id !== undefined ? [{ name, id, untagged }] : [];
         };
 
@@ -171,6 +135,11 @@ export class Topology {
         ].sort((a, b) => a.id - b.id);
     }
 
+    /** What carries a port's VLANs: the LAG it is in, or the port itself. */
+    static carrierOf(device: Device, port: Port): Switched | undefined {
+        return port.in_lag ? device.interfaces?.lag?.[port.in_lag] : port;
+    }
+
     private static vlanLabel(vlans: CarriedVlan[]): string {
         if (vlans.length === 1) return `${vlans[0]!.name}${vlans[0]!.untagged ? ", untagged" : ""}`;
         if (vlans.length <= 3) return vlans.map((vlan) => vlan.name).join(", ");
@@ -185,9 +154,9 @@ export class Topology {
         const bundles = new Map<string, { cable: GraphEdge; members: number }>();
 
         for (const device of devices) {
-            for (const [portName, port] of Object.entries(device.ports ?? {})) {
-                const link = port?.link;
-                if (!port || !link) continue;
+            for (const [portName, port] of Derive.ports(device)) {
+                const link = port.link;
+                if (!link) continue;
 
                 // The far end drew this cable already when both ends name each other.
                 const here = `${device.name} ${portName}`;
@@ -196,7 +165,7 @@ export class Topology {
                 drawn.add(`${here}|${there}`);
 
                 const far = byName.get(link.device);
-                const farPort = far?.ports?.[link.port];
+                const farPort = far?.interfaces?.ethernet?.[link.port];
                 const linksBack = farPort?.link?.device === device.name && farPort.link.port === portName;
 
                 const to = far
@@ -207,8 +176,8 @@ export class Topology {
                 const cableLine = `${here} to ${there}${through}`;
 
                 // A LAG's member cables to one LAG on the far side are one edge.
-                const lag = port.lag;
-                const farLag = farPort?.lag;
+                const lag = port.in_lag;
+                const farLag = farPort?.in_lag;
                 const bundleKey = `${device.name} ${lag}|${link.device} ${farLag}`;
                 const bundle = lag && farLag && linksBack ? bundles.get(bundleKey) : undefined;
 
@@ -232,10 +201,7 @@ export class Topology {
 
                 if (isBundle) bundles.set(bundleKey, { cable, members: 1 });
 
-                // What carries the VLANs is the LAG when the port is in one.
-                const lagSettings = lag ? device.interfaces?.[lag] : undefined;
-                const carrier = lagSettings?.type === "lag" ? lagSettings : lag ? undefined : port;
-                const vlans = Topology.carriedBy(device, carrier);
+                const vlans = Topology.carriedBy(device, Topology.carrierOf(device, port));
                 if (!vlans.length) continue;
 
                 graph.edge({
@@ -321,28 +287,37 @@ export class Topology {
         }
     }
 
-    /** `bgp`: sessions between our devices, matched by the address each names, and to every AS outside. */
-    private static sessions(devices: readonly Device[], owners: Map<string, Holder>, graph: Builder): void {
-        const all = devices.flatMap((device) => {
+    /** Every BGP session of every device, with what it takes from its neighbor group. */
+    static sessionsOf(devices: readonly Device[]) {
+        return devices.flatMap((device) => {
             const bgp = device.routing?.bgp;
 
-            return Object.entries(bgp?.neighbors ?? {}).map(([name, neighbor]) => {
-                const group = neighbor.group ? bgp?.groups?.[neighbor.group] : undefined;
-
-                return {
-                    device,
-                    name,
-                    address: neighbor.address,
-                    ownAs: bgp!.asn,
-                    remoteAs: neighbor.remote_as ?? group?.remote_as,
-                    role: neighbor.role ?? group?.role,
-                    description: neighbor.description ?? group?.description,
-                    import: neighbor.import ?? group?.import,
-                    export: neighbor.export ?? group?.export,
-                };
+            return Object.entries(bgp?.neighbors ?? {}).flatMap(([name, neighbor]) => {
+                if (!neighbor) return [];
+                const group = neighbor.neighbor_group ? bgp?.neighbor_groups?.[neighbor.neighbor_group] : undefined;
+                const settings = { ...group, ...neighbor };
+
+                return [
+                    {
+                        device,
+                        name,
+                        address: neighbor.address,
+                        ownAs: bgp?.asn,
+                        group: neighbor.neighbor_group,
+                        remoteAs: settings.remote_as,
+                        role: settings.role,
+                        description: settings.description,
+                        import: settings.import_policy,
+                        export: settings.export_policy,
+                    },
+                ];
             });
         });
+    }
 
+    /** `bgp`: sessions between our devices, matched by the address each names, and to every AS outside. */
+    private static sessions(devices: readonly Device[], owners: Map<string, Holder>, graph: Builder): void {
+        const all = Topology.sessionsOf(devices);
         type Session = (typeof all)[number];
 
         const describe = (session: Session) => {
@@ -411,10 +386,10 @@ export class Topology {
 
         for (const device of devices) {
             for (const [area, { interfaces }] of Object.entries(device.routing?.ospf?.areas ?? {})) {
-                for (const [name, settings] of Object.entries(interfaces)) {
+                for (const [name, settings] of Object.entries(interfaces ?? {})) {
                     if (settings?.passive) continue;
 
-                    const routed = (device.ports?.[name] ?? device.interfaces?.[name]) as Routed<string> | undefined;
+                    const routed = Derive.settings(device, name) as Routed | undefined;
                     const cost = settings?.cost ? `, cost ${settings.cost}` : "";
 
                     for (const entry of routed?.addresses ?? []) {
@@ -455,25 +430,29 @@ export class Topology {
 
     /** `tunnels`: GRE and VXLAN tunnels matched by their endpoints, and WireGuard peers matched to the device at the far end. */
     private static tunnels(devices: readonly Device[], owners: Map<string, Holder>, graph: Builder): void {
-        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> }] : []
-            )
-        );
+        type End = { device: Device; name: string; kind: "GRE" | "VXLAN"; iface: Gre | Vxlan; vni?: number };
 
-        type End = (typeof ends)[number];
+        const ends: End[] = devices.flatMap((device) => [
+            ...Object.entries(device.interfaces?.gre ?? {}).flatMap(([name, iface]) =>
+                iface ? [{ device, name, kind: "GRE" as const, iface }] : []
+            ),
+            ...Object.entries(device.interfaces?.vxlan ?? {}).flatMap(([name, iface]) =>
+                iface ? [{ device, name, kind: "VXLAN" as const, iface, vni: iface.vni }] : []
+            ),
+        ]);
 
         const same = (a: string, b: string) => Topology.keyOf(a) !== undefined && Topology.keyOf(a) === Topology.keyOf(b);
+        const local = (end: End) => Address.host(end.iface.local_address);
         const mirrors = (a: End, b: End) =>
             a.device !== b.device &&
-            a.iface.type === b.iface.type &&
-            same(a.iface.local, b.iface.remote) &&
-            same(a.iface.remote, b.iface.local) &&
-            (a.iface.type !== "vxlan" || (b.iface.type === "vxlan" && a.iface.vni === b.iface.vni));
+            a.kind === b.kind &&
+            same(local(a), b.iface.remote_address) &&
+            same(a.iface.remote_address, local(b)) &&
+            a.vni === b.vni;
 
         const describe = (end: End) => {
-            const vni = end.iface.type === "vxlan" ? `, VNI ${end.iface.vni}` : "";
-            return `${end.device.name} ${end.name}: ${end.iface.local} to ${end.iface.remote}${vni}`;
+            const vni = end.vni !== undefined ? `, VNI ${end.vni}` : "";
+            return `${end.device.name} ${end.name}: ${local(end)} to ${end.iface.remote_address}${vni}`;
         };
 
         const paired = new Set<End>();
@@ -481,7 +460,6 @@ export class Topology {
         for (const end of ends) {
             if (paired.has(end)) continue;
 
-            const kind = end.iface.type === "gre" ? "GRE" : "VXLAN";
             const mirror = ends.find((other) => !paired.has(other) && mirrors(end, other));
 
             if (mirror) {
@@ -491,21 +469,21 @@ export class Topology {
                     layer: "tunnels",
                     from: Topology.deviceId(end.device.name),
                     to: Topology.deviceId(mirror.device.name),
-                    label: `${kind} ${end.name} to ${mirror.name}`,
+                    label: `${end.kind} ${end.name} to ${mirror.name}`,
                     detail: [describe(end), describe(mirror)],
                 });
                 continue;
             }
 
             // The far endpoint is one of our devices, which declares no tunnel back.
-            const owner = owners.get(Topology.keyOf(end.iface.remote) ?? "")?.device;
+            const owner = owners.get(Topology.keyOf(end.iface.remote_address) ?? "")?.device;
 
             if (owner && owner !== end.device) {
                 graph.edge({
                     layer: "tunnels",
                     from: Topology.deviceId(end.device.name),
                     to: Topology.deviceId(owner.name),
-                    label: `${kind} ${end.name}`,
+                    label: `${end.kind} ${end.name}`,
                     detail: [describe(end), `${owner.name} declares no tunnel back`],
                     oneSided: true,
                 });
@@ -513,9 +491,9 @@ export class Topology {
             }
 
             const outside = graph.node(
-                `address:${end.iface.remote}`,
+                `address:${end.iface.remote_address}`,
                 "outside",
-                end.iface.remote,
+                end.iface.remote_address,
                 end.iface.description ? [end.iface.description] : []
             );
 
@@ -523,7 +501,7 @@ export class Topology {
                 layer: "tunnels",
                 from: Topology.deviceId(end.device.name),
                 to: outside,
-                label: `${kind} ${end.name}`,
+                label: `${end.kind} ${end.name}`,
                 detail: [describe(end)],
             });
         }
@@ -533,9 +511,7 @@ export class Topology {
 
     private static wireguard(devices: readonly Device[], owners: Map<string, Holder>, graph: Builder): void {
         const interfaces = devices.flatMap((device) =>
-            Object.entries(device.interfaces ?? {}).flatMap(([name, iface]) =>
-                iface.type === "wireguard" ? [{ device, name, iface }] : []
-            )
+            Object.entries(device.interfaces?.wireguard ?? {}).flatMap(([name, iface]) => (iface ? [{ device, name, iface }] : []))
         );
 
         // A peer is another of our devices when it may send from that device's tunnel address, or when its endpoint is that device's.
@@ -618,20 +594,14 @@ export class Topology {
         }
     }
 
-    /** The network as a graph. It reads the config only, never a device, and works on a config that does not validate. */
+    /** The network as a graph. It reads the project only, never a device, and works on a project that does not validate. */
     static of(devices: readonly Device[]): Graph {
         const graph = new Builder();
 
         for (const device of devices) graph.node(Topology.deviceId(device.name), "device", device.name, Topology.describeDevice(device));
 
         const holders = Topology.holders(devices);
-
-        // Who holds each address, for matching a session or tunnel to the device at its far end. The first holder wins.
-        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);
-        }
+        const owners = Topology.owners(holders);
 
         Topology.cables(devices, graph);
         Topology.segments(holders, owners, graph);
@@ -641,17 +611,4 @@ export class Topology {
 
         return { nodes: [...graph.nodes.values()], edges: graph.edges };
     }
-
-    /** Only the edges on these layers, and among those only the ones that touch these devices when any are named. Every device named stays. */
-    static only(graph: Graph, layers: readonly Layer[], deviceNames: readonly string[] = []): Graph {
-        const named = new Set(deviceNames.map(Topology.deviceId));
-        const touches = (edge: GraphEdge) => !named.size || named.has(edge.from) || named.has(edge.to);
-
-        const edges = graph.edges.filter((edge) => layers.includes(edge.layer) && touches(edge));
-        const ends = new Set(edges.flatMap((edge) => [edge.from, edge.to]));
-
-        const nodes = graph.nodes.filter((node) => (named.size ? named.has(node.id) : node.kind === "device") || ends.has(node.id));
-
-        return { nodes, edges };
-    }
 }

package/src/core/utils.ts

@@ -1,10 +1,21 @@
-// Small helpers that stand alone: combining records from several sources, and reading a time zone's offset.
+// Small helpers that stand alone: combining records from several sources, reading a time zone's offset, and reading a file of the project.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 
 type Merged<T extends readonly object[]> = T extends readonly [infer Head, ...infer Tail extends readonly object[]]
     ? Head & Merged<Tail>
     : unknown;
 
 export class Utils {
+    /** The project's folder. A path in the config, such as a certificate's `certificate_file`, is from here. Circuit sets it when it reads a project. */
+    static root = process.cwd();
+
+    /** The text of a file of the project, by its path from the project's folder. */
+    static projectFile(path: string): string {
+        return readFileSync(join(Utils.root, path), "utf8");
+    }
+
     /** Combine records into one, such as a device's own interfaces and those a module derives for it. Unlike spreading them, a name two of them hold is an error rather than one silently replacing the other. */
     static merge<const T extends readonly Record<string, unknown>[]>(...records: T): Merged<T> {
         const result: Record<string, unknown> = {};

package/src/model.ts

@@ -0,0 +1,83 @@
+// The model as Circuit's own code reads it: a device as its project wrote it, after `src/project/project.ts` turned what the language adds into
+// plain values (a list in a match is one rule per value, an interface set its interfaces, `management.allow` its addresses). Each name is plain text
+// here: the project's types already checked it. The fields and their docs are those of `src/config/`, which a project writes.
+
+import type * as C from "./config/index";
+
+export type {
+    Certificate,
+    Ethertype,
+    Exchange,
+    Family,
+    Helper,
+    IP,
+    IPv4,
+    IPv6,
+    Link,
+    MacAddress,
+    PortRange,
+    Ports,
+    Prefix,
+    Protocol,
+    Rate,
+} from "./config/index";
+export type {
+    Secret,
+    Severity,
+    SnmpUser,
+    Stp,
+    Threshold,
+    Vrrp,
+    WireGuardPeer,
+    Bfd,
+    RpkiServer,
+    OspfInterface,
+    PrefixSet,
+    RouteSet,
+    User,
+    Vlan,
+} from "./config/index";
+
+/** A device: name, site, platform, model, connection and its groups. */
+export type Device = C.AnyDevice;
+
+/** A physical port, in `interfaces.ethernet`. */
+export type Port = C.AnyPort;
+
+export type Lag = C.Lag<string, string>;
+export type VlanInterface = C.VlanInterface<string, string>;
+export type Loopback = C.Loopback<string>;
+export type Gre = C.Gre<string>;
+export type Vxlan = C.Vxlan<string>;
+export type WireGuard = C.WireGuard<string>;
+export type Bridge = C.Bridge<string, string>;
+
+/** Any interface that is not a port: what `interfaces` holds besides `ethernet`. */
+export type Interface = Lag | VlanInterface | Loopback | Gre | Vxlan | WireGuard | Bridge;
+
+/** The kinds of interface `interfaces` groups by, besides `ethernet`. */
+export type InterfaceKind = "lag" | "vlan_interface" | "loopback" | "gre" | "vxlan" | "wireguard" | "bridge";
+
+export type Switched = C.Switched<string>;
+export type Routed = C.Routed<string>;
+export type Address = C.Address;
+
+export type FilterMatch = C.FilterMatch<string, string, string>;
+export type FilterRule = C.FilterRule<string, string, string>;
+export type NatRule = C.NatRule<string, string, string>;
+export type AclRule = C.AclRule<string>;
+export type PolicyRule = C.PolicyRule<string, string>;
+export type RouteRule = C.RouteRule<string>;
+export type CallRule = C.CallRule<string>;
+export type RoutingRule = C.RoutingRule<string, string>;
+export type StaticRoute = C.StaticRoute<string, string, string>;
+export type NeighborSettings = C.NeighborSettings<string, string>;
+export type Neighbor = C.Neighbor<string, string, string>;
+export type Service = C.Service;
+export type Console = C.Console;
+export type Jump = C.Jump;
+export type DhcpServer = C.DhcpServer<string>;
+export type DhcpRelay = C.DhcpRelay<string>;
+export type FlowExport = C.FlowExport<string>;
+export type SyslogServer = C.SyslogServer;
+export type Ospf = C.Ospf<string>;