@takodotid/circuit 0.38.0 → 0.40.0

package/dist/types/schema/device.d.ts

@@ -2,7 +2,7 @@ import type { IP, Secret } from "./common.js";
 import type { AclRule, Firewall } from "./firewall.js";
 import type { Interface, Port, Vlan } from "./interfaces.js";
 import type { PrefixSet, RoutePolicy } from "./policy.js";
-import type { Routing } from "./routing.js";
+import type { Routing, StaticRoute } from "./routing.js";
 import type { Certificate, DhcpRelay, DhcpServer, FlowExport, Management, System, User } from "./system.js";
 /** How the framework reaches the device. */
 export type Connection<U extends string> = {
@@ -39,6 +39,24 @@ export type Console = {
     /** The console asks only for a password, with no name first. Circuit then types no name; `connection.user` still picks the password. */
     passwordOnly?: true;
 };
+/**
+ * Virtual domains, on FortiOS: the device's own traffic kept apart from the traffic it routes. Everything is in `root` when absent.
+ *
+ * Multi-VDOM mode is turned on by hand, not by a plan: it moves the whole configuration into `root` and ends every session.
+ */
+export type Vdoms<I extends string> = {
+    /**
+     * A VDOM for the device's own traffic: FortiGuard, NTP, DNS and logging leave from it, by its own routes, so they never follow the routed traffic's default route. Everything not listed here stays in `root`.
+     */
+    management: {
+        /** Its name, such as `mgmt`. Not `root`. */
+        name: string;
+        /** The ports and interfaces in it, by name. A LAG's member ports go with the LAG. */
+        interfaces: readonly I[];
+        /** Its static routes, such as its own default route. */
+        static?: readonly StaticRoute<I, never>[];
+    };
+};
 /** A separate routing table, with the interfaces that route in it. */
 export type Vrf = {
     /** What the VRF is for. */
@@ -103,4 +121,6 @@ export type Device<Pl extends string = string, M extends string = string, N exte
     };
     /** Forward in hardware where the platform can. An interface may override it. */
     hardware_offload?: boolean;
+    /** Virtual domains, on FortiOS only: a management VDOM apart from the routed traffic. */
+    vdoms?: Vdoms<NoInfer<I | N>>;
 };

package/dist/types/schema/firewall.d.ts

@@ -96,7 +96,7 @@ export type Firewall<I extends string, AS extends string> = {
     };
     /** Helpers that run. None when absent. */
     helpers?: readonly Helper[];
-    /** Traffic to and from these prefixes passes without connection tracking. A flood toward them cannot fill the connection table, and rules see its packets in the state `untracked`. Everything is tracked when absent. */
+    /** Traffic to and from these prefixes passes without connection tracking. A flood toward them cannot fill the connection table, and rules see its packets in the state `untracked`. An address NAT uses inside one stays tracked, or its replies would never be translated back. Everything is tracked when absent. */
     untracked?: readonly Prefix[];
 };
 /** A stateless rule evaluated in hardware where traffic arrives, before routing. */

package/dist/types/schema/interfaces.d.ts

@@ -109,7 +109,7 @@ export type Port<V extends string, A extends string, L extends string, F extends
     acl?: A;
     /** The LAG this port is in. Every other setting goes on the LAG. */
     lag?: L;
-    /** Another of our devices at the other end of the cable. */
+    /** Another of our devices at the other end of the cable. Without a `description`, the port is described from it: the far device and the far port as printed on it, such as `firewall-1 port6`. */
     link?: Link;
 };
 /** Settings every interface that is not a physical port shares. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.38.0",
+    "version": "0.40.0",
     "description": "Declarative, vendor-neutral network configuration: describe each device in TypeScript, and Circuit makes the device match. Alpha.",
     "keywords": [
         "network",

package/src/cli/index.ts

@@ -103,12 +103,20 @@ class Cli {
         return new Cli(configPath, network, options);
     }
 
-    /** The config, a TypeScript file. Bun imports it as it is; Node needs jiti, which also resolves imports written without an extension. */
+    /**
+     * The config, a TypeScript file. Bun imports it as it is; Node needs jiti, which also resolves imports written without an extension. A linked port without a description is given one from its far end.
+     */
     private static async load(path: string): Promise<Network> {
-        if (process.versions.bun) return (await import(path)).default;
+        let network: Network;
+
+        if (process.versions.bun) {
+            network = (await import(path)).default;
+        } else {
+            const { createJiti } = await import("jiti");
+            network = await createJiti(import.meta.url).import<Network>(path, { default: true });
+        }
 
-        const { createJiti } = await import("jiti");
-        return createJiti(import.meta.url).import(path, { default: true });
+        return { ...network, devices: Cabling.describeLinks(network.devices) };
     }
 
     private static fail(message: string): never {

package/src/core/cabling.ts

@@ -121,6 +121,36 @@ export class Cabling {
         return findings;
     }
 
+    /**
+     * Each linked port without a description gets one from its far end: the far device and the far port as printed on it, such as `firewall-1 port6`. The far device's own file has its platform and model, so the label is never written twice. A port whose far device is not in the network keeps none.
+     */
+    static describeLinks(devices: readonly Device[]): Device[] {
+        const byName = new Map(devices.map((device) => [device.name, device]));
+
+        return devices.map((device) => {
+            const ports = Object.entries(device.ports ?? {});
+            if (!ports.some(([, port]) => port?.link && port.description === undefined)) return device;
+
+            const described = ports.map(([name, port]) => {
+                const far = port?.link ? byName.get(port.link.device) : undefined;
+                if (!port?.link || port.description !== undefined || !far) return [name, port];
+
+                return [name, { ...port, description: `${far.name} ${Cabling.labelOf(far, port.link.port)}` }];
+            });
+
+            return { ...device, ports: Object.fromEntries(described) } as Device;
+        });
+    }
+
+    /** A port as printed on the device, or Circuit's name for it when the model has no spelling for it. */
+    private static labelOf(device: Device, port: string): string {
+        try {
+            return Catalog.spell(device.platform, device.model, port);
+        } catch {
+            return port;
+        }
+    }
+
     /** A system name is the device's name, alone or with a domain after it. */
     private static isDevice(system: string, name: string): boolean {
         return system === name || system.startsWith(`${name}.`);

package/src/core/validator.ts

@@ -93,6 +93,31 @@ export class Validator {
         Validator.checkFirewall(device, names, cidr);
         Validator.checkServices(device, names, report, cidr);
         Validator.checkCertificates(device, names, report);
+        Validator.checkVdoms(device, names, report, cidr, ip);
+    }
+
+    /** A management VDOM: FortiOS only, not `root`, with declared interfaces, and routes that leave through its own. */
+    private static checkVdoms(device: Device, names: Names, report: Report, cidr: Checker, ip: Checker): void {
+        const management = device.vdoms?.management;
+        if (!management) return;
+
+        if (device.platform !== "fortios") report("vdoms are a FortiOS setting");
+        if (management.name === "root") report("vdoms.management.name is root, the VDOM everything else is in; give it a name of its own");
+
+        for (const name of management.interfaces) {
+            names.expectInterface("vdoms.management interface", name);
+            const port = device.ports?.[name as keyof typeof device.ports];
+            if (port?.lag) report(`vdoms.management interface ${name} is in LAG ${port.lag}; list the LAG`);
+        }
+
+        for (const route of management.static ?? []) {
+            const where = `vdoms.management static route ${route.prefix}`;
+            cidr(where, route.prefix);
+            if (route.via) ip(where, route.via);
+            if (!route.via && !route.interface && !route.blackhole) report(`${where} has no next hop`);
+            if (route.interface && !management.interfaces.includes(route.interface))
+                report(`${where} leaves through ${route.interface}, which is not in the VDOM`);
+        }
     }
 
     /** What the model's hardware holds, from the catalog. A LAG with too many members is an error; too many switch rules is a warning, since the limit is only roughly known. */

package/src/helpers/cables.ts

@@ -1,28 +1,19 @@
-import { Catalog, type ModelName, type PlatformName, type PortName } from "../platforms/catalog";
-
-/** One end of a cable: the device, and its platform and model, which name its ports. */
-export type CableEnd<P extends PlatformName, M extends ModelName<P>> = {
-    device: string;
-    platform: P;
-    model: M;
-};
-
-/** The far end of a port, for its description: the device, the port by Circuit's name, and by the name printed on the device. */
-export type FarEnd = { device: string; port: string; label: string };
+/** The far end of a port, for a description of your own: the device and its port by Circuit's name. */
+export type FarEnd = { device: string; port: string };
 
 /** What every cable of one entry shares. */
 type Shared = {
     /** What is between the two ends, such as a carrier's local loop. Both ends get it on their `link`. */
     through?: string;
-    /** A port's description from its far end. The far device and the far port's label when absent, such as `firewall-1 port6`. */
+    /** A port's description from its far end. When absent, Circuit writes the far device and the far port as printed on it, such as `firewall-1 port6`, from the far device's own file. */
     describe?: (far: FarEnd) => string;
 };
 
-/** A port a cable builds: what it is, the LAG it is in, and the other end. */
+/** A port a cable builds: the other end, the LAG it is in, and a description when `describe` gives one. */
 type CablePort<L extends string> = {
-    description: string;
     link: { device: string; port: string; through?: string };
     lag?: L;
+    description?: string;
 };
 
 /** Ports for both ends of the cables between two of our devices, each cable written once. */
@@ -31,37 +22,26 @@ export class Cables {
      * One cable, both ends. Spread each end into its device's `ports`:
      *
      * ```ts
-     * const uplink = Cables.link({ a: { device: "router-1", platform: "routeros", model: "CCR2216-1G-12XS-2XQ", port: "25g-1" }, b: { ... } });
+     * const uplink = Cables.link({ a: { device: "router-1", port: "25g-1" }, b: { device: "switch-1", port: "10g-48" } });
      * // router-1: ports: { ...uplink.a }
      * ```
      */
-    static link<
-        const PA extends PlatformName,
-        const MA extends ModelName<PA>,
-        const NA extends PortName<PA, MA>,
-        const PB extends PlatformName,
-        const MB extends ModelName<PB>,
-        const NB extends PortName<PB, MB>,
-    >(spec: Shared & { a: CableEnd<PA, MA> & { port: NA }; b: CableEnd<PB, MB> & { port: NB } }) {
+    static link<const NA extends string, const NB extends string>(
+        spec: Shared & { a: { device: string; port: NA }; b: { device: string; port: NB } }
+    ) {
         return {
-            a: { [spec.a.port]: Cables.end(spec, spec.b, spec.b.port) } as Record<NA, CablePort<never>>,
-            b: { [spec.b.port]: Cables.end(spec, spec.a, spec.a.port) } as Record<NB, CablePort<never>>,
+            a: { [spec.a.port]: Cables.end(spec, spec.b.device, spec.b.port) } as Record<NA, CablePort<never>>,
+            b: { [spec.b.port]: Cables.end(spec, spec.a.device, spec.a.port) } as Record<NB, CablePort<never>>,
         };
     }
 
     /**
      * The cables of a LAG, both ends, from one list read from end A: `{ "25g-1": "10g-2" }` is a cable from A's 25g-1 to B's 10g-2. Each port is a member of its end's LAG. Spread each end into its device's `ports`; the LAG itself stays on each device.
      */
-    static lag<
-        const PA extends PlatformName,
-        const MA extends ModelName<PA>,
-        const LA extends string,
-        const PB extends PlatformName,
-        const MB extends ModelName<PB>,
-        const LB extends string,
-        const C extends Partial<Record<PortName<PA, MA>, PortName<PB, MB>>>,
-    >(spec: Shared & { a: CableEnd<PA, MA> & { lag: LA }; b: CableEnd<PB, MB> & { lag: LB }; cables: C }) {
-        const pairs = Object.entries(spec.cables) as [string, string][];
+    static lag<const LA extends string, const LB extends string, const C extends Readonly<Record<string, string>>>(
+        spec: Shared & { a: { device: string; lag: LA }; b: { device: string; lag: LB }; cables: C }
+    ) {
+        const pairs = Object.entries(spec.cables);
 
         const taken = new Map<string, string>();
         for (const [near, far] of pairs) {
@@ -70,22 +50,20 @@ export class Cables {
             taken.set(far, near);
         }
 
-        const a = Object.fromEntries(pairs.map(([near, far]) => [near, { ...Cables.end(spec, spec.b, far), lag: spec.a.lag }]));
-        const b = Object.fromEntries(pairs.map(([near, far]) => [far, { ...Cables.end(spec, spec.a, near), lag: spec.b.lag }]));
+        const a = Object.fromEntries(pairs.map(([near, far]) => [near, { ...Cables.end(spec, spec.b.device, far), lag: spec.a.lag }]));
+        const b = Object.fromEntries(pairs.map(([near, far]) => [far, { ...Cables.end(spec, spec.a.device, near), lag: spec.b.lag }]));
 
         return {
             a: a as Record<keyof C & string, CablePort<LA>>,
-            b: b as Record<NonNullable<C[keyof C]> & string, CablePort<LB>>,
+            b: b as Record<C[keyof C], CablePort<LB>>,
         };
     }
 
     /** A port facing `port` on the far device. */
-    private static end(shared: Shared, far: { device: string; platform: string; model: string }, port: string): CablePort<never> {
-        const farEnd = { device: far.device, port, label: Catalog.spell(far.platform, far.model, port) };
-
+    private static end(shared: Shared, device: string, port: string): CablePort<never> {
         return {
-            description: shared.describe ? shared.describe(farEnd) : `${farEnd.device} ${farEnd.label}`,
-            link: { device: far.device, port, ...(shared.through ? { through: shared.through } : {}) },
+            link: { device, port, ...(shared.through ? { through: shared.through } : {}) },
+            ...(shared.describe ? { description: shared.describe({ device, port }) } : {}),
         };
     }
 }

package/src/helpers/index.ts

@@ -3,7 +3,7 @@
 export { Bgp } from "./bgp";
 export type { Announced, CommunityScheme, DefaultOnlyOptions, LearnOptions, SanityLengths } from "./bgp";
 export { Cables } from "./cables";
-export type { CableEnd, FarEnd } from "./cables";
+export type { FarEnd } from "./cables";
 export { Checks } from "./checks";
 export type { TrustBoundary } from "./checks";
 export { Exchange } from "./exchange";