@takodotid/circuit 0.40.0 → 0.42.0

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

@@ -78,15 +78,22 @@ export type Sets = {
     blackhole?: true;
 };
 /**
- * One step of a route policy. Evaluated in this order: `call`, then `match`, then `set`, then `action`.
- *
- * A rule without `action` changes the route and moves on to the next rule.
+ * Run another policy at this point. A route it accepts or rejects stops there; any other route goes on to the next rule. A call holds nothing else: to call a policy for some routes only, put the match inside that policy.
  */
-export type PolicyRule<P extends string, S extends string> = {
+export type CallRule<P extends string> = {
     /** Shown beside the rule on the device. */
     description?: string;
-    /** Evaluate another policy first. A route it accepts or rejects stops there. */
-    call?: P;
+    /** The policy to run. */
+    call: P;
+    match?: never;
+    set?: never;
+    action?: never;
+};
+/** Change and decide on the routes that match. A rule without `action` changes the route and moves on to the next rule. */
+export type MatchRule<S extends string> = {
+    /** Shown beside the rule on the device. */
+    description?: string;
+    call?: never;
     /** Which routes the rule applies to. Every route when absent. */
     match?: Match<S>;
     /** What to change on a matching route. */
@@ -94,5 +101,7 @@ export type PolicyRule<P extends string, S extends string> = {
     /** Accept or reject a matching route, ending the policy for it. */
     action?: "accept" | "reject";
 };
+/** One step of a route policy: a call to another policy, or a rule that matches routes, changes them and may decide on them. */
+export type PolicyRule<P extends string, S extends string> = CallRule<P> | MatchRule<S>;
 /** Rules evaluated in order, first decision wins. A route no rule accepts is rejected. */
 export type RoutePolicy<P extends string, S extends string> = readonly PolicyRule<P, S>[];

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

@@ -1,6 +1,6 @@
 import type { Family, IP, Prefix, Secret } from "./common.js";
 /** A route the device has without learning it. */
-export type StaticRoute<I extends string, F extends string> = {
+export type StaticRoute<I extends string, F extends string, T extends string = never> = {
     /** Destination. */
     prefix: Prefix;
     /** Next-hop address. */
@@ -13,8 +13,10 @@ export type StaticRoute<I extends string, F extends string> = {
     bfd?: true;
     /** Preference against other routes to the same prefix. Lower wins. 1 when absent. */
     distance?: number;
-    /** The VRF the route is in. The default table when absent. */
+    /** The VRF the route is in. The main table when absent. */
     vrf?: F;
+    /** The table the route is in, one of `routing.tables`. The main table when absent. A route has a `vrf` or a `table`, not both. */
+    table?: T;
     /** Why the route exists. */
     description?: string;
 };
@@ -23,7 +25,7 @@ export type StaticRoute<I extends string, F extends string> = {
  */
 export type BgpRole = "provider" | "customer" | "peer" | "rs" | "rs-client";
 /** Settings a BGP neighbor can set itself or take from its group. */
-export type NeighborSettings<P extends string> = {
+export type NeighborSettings<P extends string, T extends string = never> = {
     /** The neighbor's AS. Our own AS makes the session internal. */
     remote_as?: number;
     /** Who the neighbor is. */
@@ -52,24 +54,26 @@ export type NeighborSettings<P extends string> = {
     passive?: boolean;
     /** Detect a dead link in under a second with BFD. */
     bfd?: boolean;
+    /** The table the routes learned are installed in, one of `routing.tables`. The main table when absent. What is announced still comes from `networks` and the main table. */
+    table?: T;
 };
 /** One BGP session. Settings it does not set come from its group. */
-export type Neighbor<P extends string, G extends string> = NeighborSettings<P> & {
+export type Neighbor<P extends string, G extends string, T extends string = never> = NeighborSettings<P, T> & {
     /** The neighbor's address. */
     address: IP;
     /** The group this neighbor takes a setting from when it does not set that setting itself. */
     group?: NoInfer<G>;
 };
 /** BGP on this device. */
-export type Bgp<P extends string, G extends string> = {
+export type Bgp<P extends string, G extends string, T extends string = never> = {
     /** Our AS number. */
     asn: number;
     /** Prefixes this device originates. Each needs a route, for example a static blackhole. Export policy still decides who receives them. */
     networks?: readonly Prefix[];
     /** Settings shared by several neighbors, keyed by group name. */
-    groups?: Record<G, NeighborSettings<P>>;
+    groups?: Record<G, NeighborSettings<P, T>>;
     /** Sessions keyed by name. */
-    neighbors?: Record<string, Neighbor<P, G>>;
+    neighbors?: Record<string, Neighbor<P, G, T>>;
 };
 /** How fast BFD notices a dead neighbor: after `multiplier` packets in a row are missed, so in `interval` times `multiplier` milliseconds. */
 export type Bfd = {
@@ -111,14 +115,43 @@ export type Ospf<I extends string> = {
     /** Routes from other sources announced into OSPF. */
     redistribute?: readonly ("connected" | "static")[];
 };
+/** A routing table beside the main one. It holds no interfaces: routes go in from static routes and BGP neighbors that name it in `table`, and `routing.rules` send traffic to it. */
+export type RoutingTable = {
+    /** What the table is for. */
+    description?: string;
+};
+/** Traffic a routing rule matches: all of what is given. Every packet when absent. */
+export type RoutingRuleMatch<I extends string> = {
+    /** Source prefix. */
+    src?: Prefix;
+    /** Destination prefix. */
+    dst?: Prefix;
+    /** The interface the traffic arrives on. */
+    in_interface?: I;
+};
+/** One routing rule: traffic it matches is routed by `table` instead of the main table. */
+export type RoutingRule<I extends string, T extends string> = {
+    /** Why the rule exists. */
+    description?: string;
+    /** What the traffic must match. Every packet when absent, so such a rule is the last one. */
+    match?: RoutingRuleMatch<I>;
+    /** The table that routes the traffic: one of `routing.tables`, or `main`. */
+    table: T | "main";
+    /** When `table` has no route for a packet: `none` drops it as unroutable, `main` routes it by the main table instead. `none` when absent. Not for a rule whose table is `main`. */
+    fallback?: "none" | "main";
+};
 /** Routing on this device. */
-export type Routing<P extends string, G extends string, I extends string, F extends string> = {
+export type Routing<P extends string, G extends string, I extends string, F extends string, T extends string = never> = {
     /** Identifies this router to its neighbors. */
     router_id?: IP;
+    /** Routing tables beside the main one, keyed by name. Not `main`, and not the name of a VRF. */
+    tables?: Record<T, RoutingTable>;
+    /** Rules that route matching traffic by another table, such as traffic from one block by its own transits' default. In order: the first that matches decides, and traffic no rule matches is routed by the main table. */
+    rules?: readonly RoutingRule<I, NoInfer<T>>[];
     /** Routes the device has without learning them. */
-    static?: readonly StaticRoute<I, F>[];
+    static?: readonly StaticRoute<I, F, NoInfer<T>>[];
     /** BGP sessions and what they exchange. */
-    bgp?: Bgp<P, G>;
+    bgp?: Bgp<P, G, NoInfer<T>>;
     /** OSPF areas and interfaces. */
     ospf?: Ospf<I>;
     /** Validators answering route origin validation. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.40.0",
+    "version": "0.42.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,20 +103,12 @@ 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. A linked port without a description is given one from its far end.
-     */
+    /** The config, a TypeScript file. Bun imports it as it is; Node needs jiti, which also resolves imports written without an extension. */
     private static async load(path: string): Promise<Network> {
-        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 });
-        }
+        if (process.versions.bun) return (await import(path)).default;
 
-        return { ...network, devices: Cabling.describeLinks(network.devices) };
+        const { createJiti } = await import("jiti");
+        return createJiti(import.meta.url).import(path, { default: true });
     }
 
     private static fail(message: string): never {
@@ -238,7 +230,9 @@ class Cli {
             .command("bgp")
             .description("each BGP neighbor in the config next to its live session: up or down and why, prefixes, uptime")
             .argument("[device]", "may be left out when only one device has BGP neighbors")
-            .argument("[name-regex]", "only the neighbors whose name matches")
+            // A second argument was the name filter before 0.42; it is refused below with the way to write it now.
+            .allowExcessArguments()
+            .option("--neighbors <regex>", "only the neighbors whose name matches")
             .option(
                 "--wait [count]",
                 `read again every ${BgpWait.COMMAND.every} seconds until every neighbor shown, or this many, is up`,
@@ -248,7 +242,14 @@ class Cli {
             .option("--log [minutes]", "also print the device's BGP log lines from the last minutes, 5 by default", Cli.minutes)
             .option("--clear-limit", "open again the neighbors shown that closed on their prefix limit; any other is left alone")
             .option(Cli.CONFIG_FLAGS, Cli.CONFIG_HELP)
-            .action(async (first, second, flags) => (await Cli.open(flags.config)).bgp(first, second, flags));
+            .action(async (device, flags, command) => {
+                const [, filter] = command.args;
+                if (filter !== undefined)
+                    Cli.fail(
+                        `circuit bgp takes one device; filter the neighbors with --neighbors: circuit bgp ${device} --neighbors '${filter}'`
+                    );
+                (await Cli.open(flags.config)).bgp(device, flags);
+            });
 
         program
             .command("console")
@@ -613,14 +614,14 @@ class Cli {
     }
 
     /**
-     * Each BGP neighbor in the config next to its live session. `first` is the device, or, when it names none and only one device has BGP neighbors, the name pattern. With `wait`, reads again until every neighbor shown, or that many, is up, and fails when time runs out. With `clearLimit`, opens again the neighbors shown that closed on their prefix limit, and fails when none did.
+     * Each BGP neighbor in the config next to its live session, on the device named or the only one with BGP neighbors, and only those whose name matches `neighbors` when given. With `wait`, reads again until every neighbor shown, or that many, is up, and fails when time runs out. With `clearLimit`, opens again the neighbors shown that closed on their prefix limit, and fails when none did.
      */
     private async bgp(
-        first: string | undefined,
-        second: string | undefined,
-        flags: { wait?: true | number; max: number; log?: true | number; clearLimit?: true }
+        deviceName: string | undefined,
+        flags: { neighbors?: string; wait?: true | number; max: number; log?: true | number; clearLimit?: true }
     ): Promise<void> {
-        const { device, pattern } = this.bgpTarget(first, second);
+        const device = this.bgpDevice(deviceName);
+        const pattern = flags.neighbors;
         const adapter = this.adapterOf(device);
 
         const supported = Platforms.all()
@@ -697,19 +698,15 @@ class Cli {
         Cli.printBgp(await read());
     }
 
-    /** The device `circuit bgp` reads, and the name pattern, from its two optional arguments. */
-    private bgpTarget(first: string | undefined, second: string | undefined): { device: Device; pattern: string | undefined } {
-        if (second !== undefined || (first && this.network.devices.some((device) => device.name === first))) {
-            return { device: this.one(first!), pattern: second };
-        }
+    /** The device `circuit bgp` reads: the one named, or the only device with BGP neighbors. */
+    private bgpDevice(name: string | undefined): Device {
+        if (name !== undefined) return this.one(name);
 
         const withBgp = this.network.devices.filter((device) => Object.keys(device.routing?.bgp?.neighbors ?? {}).length);
-        const named = first ? `no device ${first}, and ` : "";
-
-        if (withBgp.length === 1) return { device: withBgp[0]!, pattern: first };
-        if (!withBgp.length) Cli.fail(`${named}no device has BGP neighbors`);
+        if (withBgp.length === 1) return withBgp[0]!;
+        if (!withBgp.length) Cli.fail("no device has BGP neighbors");
 
-        return Cli.fail(`${named}several devices have BGP neighbors, so name one: ${withBgp.map((device) => device.name).join(", ")}`);
+        return Cli.fail(`several devices have BGP neighbors, so name one: ${withBgp.map((device) => device.name).join(", ")}`);
     }
 
     /** One line per neighbor: name, up or down, prefixes received, uptime, remote address. Then how many are up. */

package/src/core/cabling.ts

@@ -121,36 +121,6 @@ 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/define.ts

@@ -28,6 +28,7 @@ export function defineDevice<
     const Users extends string = never,
     const Vrfs extends string = never,
     const Certificates extends string = never,
+    const Tables extends string = never,
 >(
     device: Device<
         Platform,
@@ -42,7 +43,8 @@ export function defineDevice<
         AddressSets,
         Users,
         Vrfs,
-        Certificates
+        Certificates,
+        Tables
     >
 ): Device {
     return device as unknown as Device;

package/src/core/validator.ts

@@ -291,17 +291,29 @@ export class Validator {
             if (route.bfd && !route.via) report(`static route ${route.prefix} has bfd without via, the address BFD watches`);
             names.expectInterface(`static route ${route.prefix} interface`, route.interface);
             names.expect(`static route ${route.prefix} VRF`, route.vrf, route.vrf !== undefined && route.vrf in (device.vrfs ?? {}));
+            names.expect(
+                `static route ${route.prefix} table`,
+                route.table,
+                route.table !== undefined && route.table in (routing?.tables ?? {})
+            );
+            if (route.vrf && route.table) report(`static route ${route.prefix} has both vrf and table; a route is in one of them`);
         }
 
+        Validator.checkTables(device, names, report, cidr);
+
         const bgp = routing?.bgp;
         const isPolicy = (policy: string | undefined) => policy !== undefined && policy in policies;
 
         for (const prefix of bgp?.networks ?? []) cidr("BGP network", prefix);
 
+        const isTable = (table: string | undefined) => table !== undefined && table in (routing?.tables ?? {});
+
         for (const [name, group] of Object.entries(bgp?.groups ?? {})) {
             for (const policy of [group.import, group.export]) {
                 names.expect(`BGP group ${name} policy`, policy, isPolicy(policy));
             }
+
+            names.expect(`BGP group ${name} table`, group.table, isTable(group.table));
         }
 
         for (const [name, neighbor] of Object.entries(bgp?.neighbors ?? {})) {
@@ -316,6 +328,8 @@ export class Validator {
                 names.expect(`neighbor ${name} policy`, policy, isPolicy(policy));
             }
 
+            names.expect(`neighbor ${name} table`, neighbor.table, isTable(neighbor.table));
+
             const local = neighbor.local_address ?? group?.local_address;
             if (local && Address.family(local) !== Address.family(neighbor.address))
                 report(`neighbor ${name} local_address and address differ in family`);
@@ -327,17 +341,71 @@ export class Validator {
         }
     }
 
+    /** Routing tables have names of their own and something installing routes in them, and rules name a table and can each be reached. */
+    private static checkTables(device: Device, names: Names, report: Report, cidr: Checker): void {
+        const routing = device.routing;
+        const tables = routing?.tables ?? {};
+        const bgp = routing?.bgp;
+
+        const installed = new Set<string>();
+        for (const route of routing?.static ?? []) if (route.table) installed.add(route.table);
+        for (const neighbor of Object.values(bgp?.neighbors ?? {})) {
+            const table = neighbor.table ?? (neighbor.group ? bgp?.groups?.[neighbor.group]?.table : undefined);
+            if (table) installed.add(table);
+        }
+
+        for (const name of Object.keys(tables)) {
+            if (name === "main") report("routing.tables has main, the main table every device has; give the table another name");
+            if (name in (device.vrfs ?? {})) report(`routing.tables ${name} has the name of a VRF; give the table another name`);
+            if (name !== "main" && !installed.has(name))
+                report(
+                    `routing.tables ${name}: nothing installs routes in it; give a static route or a BGP neighbor table: "${name}", or remove the table`
+                );
+        }
+
+        const rules = routing?.rules ?? [];
+        rules.forEach((rule, index) => {
+            const where = `routing.rules ${index + 1}${rule.description ? ` (${rule.description})` : ""}`;
+            const match = rule.match ?? {};
+
+            names.expect(`${where} table`, rule.table, rule.table === "main" || rule.table in tables);
+            names.expectInterface(`${where} in_interface`, match.in_interface);
+            if (match.src) cidr(where, match.src);
+            if (match.dst) cidr(where, match.dst);
+
+            if (match.src && match.dst && Address.isCidr(match.src) && Address.isCidr(match.dst)) {
+                if (Address.family(Address.host(match.src)) !== Address.family(Address.host(match.dst)))
+                    report(`${where}: src and dst differ in family, so no packet matches both`);
+            }
+
+            if (rule.table === "main" && rule.fallback)
+                report(`${where} looks up main and has fallback; fallback is for another table, so remove it`);
+
+            const matchesAll = !match.src && !match.dst && !match.in_interface;
+            if (matchesAll && index < rules.length - 1)
+                report(`${where} matches every packet, so the rules after it never run; give it a match, or move it last`);
+        });
+    }
+
     private static checkPolicies(device: Device, names: Names, report: Report, cidr: Checker): void {
         const policies = device.policies ?? {};
         const sets = device.prefix_sets ?? {};
 
         for (const [name, rules] of Object.entries(policies)) {
-            for (const rule of rules) {
+            rules.forEach((rule, index) => {
+                // A device runs a call for every route, so a match beside it would read as a condition it isn't.
+                const beside = (["match", "set", "action"] as const).filter((key) => rule.call !== undefined && rule[key] !== undefined);
+                if (beside.length) {
+                    report(
+                        `policy ${name} rule ${index + 1} has call and ${beside.join(", ")}: a call is a rule of its own, run for every route. Put ${beside.join(", ")} in the next rule, or the match inside ${rule.call}`
+                    );
+                }
+
                 names.expect(`policy ${name} call`, rule.call, rule.call !== undefined && rule.call in policies);
                 const set = rule.match?.prefix_set;
                 names.expect(`policy ${name} prefix set`, set, set !== undefined && set in sets);
                 if (rule.match?.prefix) cidr(`policy ${name}`, rule.match.prefix);
-            }
+            });
         }
 
         // A policy that calls itself, directly or not, never finishes.