@takodotid/circuit 0.41.0 → 0.42.0

package/dist/types/helpers/upstreams.d.ts

@@ -59,7 +59,7 @@ export type Upstream = {
         address: IP;
         local_address?: IP;
     }>>;
-    /** A BGP group its sessions share, by this name: the group holds the AS, role, policies and multihop settings, and each session names it. Each session holds them itself when absent. */
+    /** A BGP group its sessions share, by this name: the group holds the AS, role, policies, table and multihop settings, and each session names it. Each session holds them itself when absent. */
     group?: string;
     /** The sessions are more than one hop away, from this address of ours. */
     multihop?: {
@@ -67,6 +67,8 @@ export type Upstream = {
         families?: readonly Family[];
         password?: Secret;
     };
+    /** The routing table its sessions install the routes they learn in, one of the router's `routing.tables`: a transit that carries only one block's traffic out. The main table when absent. */
+    table?: string;
     /** The most prefixes a session may send, by its family: about twice what it sends. Over it, the session closes until it is cleared. */
     limits?: {
         ipv4?: number;
@@ -143,6 +145,12 @@ type GroupName<C> = Values<{
         group: infer N extends string;
     } ? N : never;
 }>;
+/** Each routing table name. */
+type TableName<C> = Values<{
+    [K in keyof C]: C[K] extends {
+        table: infer N extends string;
+    } ? N : never;
+}>;
 /** A network's upstreams written once, and each device's part built from them. */
 export declare class Upstreams {
     /**
@@ -160,8 +168,8 @@ export declare class Upstreams {
         ports: (device: string) => Record<string, Port<NativeName<C> | VlanName<C>, never, never, never>>;
         interfaces: () => { [K in HandoffInterface<C>]: VlanInterface<VlanName<C>, never>; } & { [K in TunnelInterface<C>]: Gre<never>; };
         uplinks: () => HandoffInterface<C>[];
-        groups: () => Record<GroupName<C>, NeighborSettings<PolicyName<C>>>;
-        neighbors: () => Record<string, Neighbor<PolicyName<C>, GroupName<C>>>;
+        groups: () => Record<GroupName<C>, NeighborSettings<PolicyName<C>, TableName<C>>>;
+        neighbors: () => Record<string, Neighbor<PolicyName<C>, GroupName<C>, TableName<C>>>;
         policies: () => Record<PolicyName<C>, PolicyRule<never, never>[]>;
         untrusted: () => (NativeName<C> | VlanName<C>)[];
         natives: () => NativeName<C>[];

package/dist/types/platforms/derive.d.ts

@@ -1,6 +1,6 @@
 import type { Device } from "../schema/index.js";
 /** A feature a platform renders once proved on one of its devices. */
-export type ProvedFeature = "bfd-timers" | "static-route-bfd" | "multihop-bfd" | "alarm-severity" | "mac-limit" | "ethertype-filter" | "management-vdom";
+export type ProvedFeature = "bfd-timers" | "static-route-bfd" | "multihop-bfd" | "alarm-severity" | "mac-limit" | "ethertype-filter" | "management-vdom" | "routing-tables";
 export declare class Derive {
     /** Each LAG's number: its own `id`, or its position among the device's LAGs. */
     static lagIds(device: Device): Map<string, number>;

package/dist/types/platforms/fortios/routing.d.ts

@@ -1,7 +1,7 @@
 import type { Device, Family, Neighbor, NeighborSettings, PolicyRule } from "../../schema/index.js";
 import { FortiOsBlock } from "./tree.js";
 type AnyRule = PolicyRule<string, string>;
-type AnyNeighbor = Neighbor<string, string>;
+type AnyNeighbor = Neighbor<string, string, string>;
 /** The lengths a prefix list's rule takes within its prefix. */
 type Lengths = {
     ge?: number;
@@ -23,7 +23,7 @@ export declare class FortiOsRouting {
         readonly ipv6: 128;
     };
     /** A neighbor's settings with its group's beneath them. */
-    static neighborSettings(device: Device, neighbor: AnyNeighbor): NeighborSettings<string>;
+    static neighborSettings(device: Device, neighbor: AnyNeighbor): NeighborSettings<string, string>;
     /** The families a session carries: its own, or the family of its address. */
     static familiesOfNeighbor(device: Device, neighbor: AnyNeighbor): Family[];
     /** Whether a static route, OSPF or BGP detects a dead neighbor with BFD, which the device then runs. */

package/dist/types/platforms/junos/bgp.d.ts

@@ -1,6 +1,6 @@
 import type { Device, Neighbor, NeighborSettings } from "../../schema/index.js";
 import { type JunosStatements } from "./render.js";
-type AnyNeighbor = Neighbor<string, string>;
+type AnyNeighbor = Neighbor<string, string, string>;
 /** BGP sessions, the policies they use, prefix sets and RPKI servers, added to one device's statements. */
 export declare class JunosBgp {
     private readonly out;
@@ -19,7 +19,7 @@ export declare class JunosBgp {
     /** Add the device's prefix sets, RPKI servers, BGP sessions and the policies they use. */
     static render(out: JunosStatements, device: Device): void;
     /** A neighbor's settings with its group's beneath them. */
-    static settingsOf(device: Device, neighbor: AnyNeighbor): NeighborSettings<string>;
+    static settingsOf(device: Device, neighbor: AnyNeighbor): NeighborSettings<string, string>;
     /** A name made of a value's words, for a community or a path-length list: `64500:*` becomes `64500-any`. */
     private static slug;
     /** A community as the platform writes a member: a large community carries the `large:` prefix. */

package/dist/types/platforms/routeros/render.d.ts

@@ -199,6 +199,10 @@ export declare class RouterOsRender {
     /** Every switch rule the device's hardware ACLs make, in order: one for each port with an ACL, each rule of it, and each source and destination port or range of the rule. */
     static switchRules(device: Device): SwitchRule[];
     private routing;
+    /** A table beside the main one. `fib` puts its routes in the forwarding table, so traffic can be routed by them. */
+    private routingTables;
+    /** Rules in the order written. `lookup-only-in-table` drops what the table has no route for, and `lookup` falls back to the main table. */
+    private routingRules;
     private staticRoutes;
     private rpki;
     /** The default instance exists on every device; it is stated in the form the export prints it. */

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

@@ -65,9 +65,9 @@ export type Vrf = {
 /**
  * Everything one device runs. What is not written here is removed from the device or returned to its default.
  *
- * Type parameters are the names the device declares, so a reference to a name that does not exist fails to compile: N ports, V VLANs, I interfaces, P policies, S prefix sets, G BGP groups, A ACLs, AS address sets, U users, F VRFs, C certificates.
+ * Type parameters are the names the device declares, so a reference to a name that does not exist fails to compile: N ports, V VLANs, I interfaces, P policies, S prefix sets, G BGP groups, A ACLs, AS address sets, U users, F VRFs, C certificates, T routing tables.
  */
-export type Device<Pl extends string = string, M extends string = string, N extends string = string, V extends string = string, I extends string = string, P extends string = string, S extends string = string, G extends string = string, A extends string = string, AS extends string = string, U extends string = string, F extends string = string, C extends string = string> = {
+export type Device<Pl extends string = string, M extends string = string, N extends string = string, V extends string = string, I extends string = string, P extends string = string, S extends string = string, G extends string = string, A extends string = string, AS extends string = string, U extends string = string, F extends string = string, C extends string = string, T extends string = string> = {
     /** Hostname. */
     name: string;
     /** Operating system. It decides which adapter renders and applies the device. */
@@ -92,8 +92,8 @@ export type Device<Pl extends string = string, M extends string = string, N exte
     interfaces?: Record<I, Interface<NoInfer<V>, NoInfer<F>>>;
     /** Separate routing tables, keyed by name. */
     vrfs?: Record<F, Vrf>;
-    /** Static routes, BGP, OSPF and route validation. */
-    routing?: Routing<NoInfer<P>, G, NoInfer<I | N>, NoInfer<F>>;
+    /** Routing tables and rules, static routes, BGP, OSPF and route validation. */
+    routing?: Routing<NoInfer<P>, G, NoInfer<I | N>, NoInfer<F>, T>;
     /** Route policies, keyed by name. */
     policies?: Record<P, RoutePolicy<NoInfer<P>, NoInfer<S>>>;
     /** Prefix sets that policies match on, keyed by name. */

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. 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`. */
+    /** Another of our devices at the other end of the cable. */
     link?: Link;
 };
 /** Settings every interface that is not a physical port shares. */

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.41.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,6 +341,52 @@ 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 ?? {};

package/src/helpers/cables.ts

@@ -1,11 +1,16 @@
-/** 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 };
+import { Catalog } from "../platforms/catalog";
+
+/** The far end of a port, for a description of your own: the device, its port by Circuit's name, and the port as printed on the device when that end names its platform and model. */
+export type FarEnd = { device: string; port: string; label?: string };
+
+/** One end of a cable entry: the device, and its platform and model if a description should name its ports as printed on it. */
+type End = { device: string; platform?: string; model?: 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. 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. */
+    /** A port's description from its far end, such as `(far) => \`${far.device} ${far.label}\``. No description when absent. */
     describe?: (far: FarEnd) => string;
 };
 
@@ -26,12 +31,10 @@ export class Cables {
      * // router-1: ports: { ...uplink.a }
      * ```
      */
-    static link<const NA extends string, const NB extends string>(
-        spec: Shared & { a: { device: string; port: NA }; b: { device: string; port: NB } }
-    ) {
+    static link<const NA extends string, const NB extends string>(spec: Shared & { a: End & { port: NA }; b: End & { port: NB } }) {
         return {
-            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>>,
+            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>>,
         };
     }
 
@@ -39,7 +42,7 @@ export class Cables {
      * 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 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 }
+        spec: Shared & { a: End & { lag: LA }; b: End & { lag: LB }; cables: C }
     ) {
         const pairs = Object.entries(spec.cables);
 
@@ -50,8 +53,8 @@ export class Cables {
             taken.set(far, near);
         }
 
-        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 }]));
+        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 }]));
 
         return {
             a: a as Record<keyof C & string, CablePort<LA>>,
@@ -59,11 +62,13 @@ export class Cables {
         };
     }
 
-    /** A port facing `port` on the far device. */
-    private static end(shared: Shared, device: string, port: string): CablePort<never> {
+    /** A port facing `port` on the far end. */
+    private static end(shared: Shared, far: End, port: string): CablePort<never> {
+        const label = far.platform && far.model ? Catalog.spell(far.platform, far.model, port) : undefined;
+
         return {
-            link: { device, port, ...(shared.through ? { through: shared.through } : {}) },
-            ...(shared.describe ? { description: shared.describe({ device, port }) } : {}),
+            link: { device: far.device, port, ...(shared.through ? { through: shared.through } : {}) },
+            ...(shared.describe ? { description: shared.describe({ device: far.device, port, ...(label ? { label } : {}) }) } : {}),
         };
     }
 }

package/src/helpers/exchange.ts

@@ -30,6 +30,10 @@ export type InternetExchange<V extends string> = {
     mac_limit?: number;
     /** The only kinds of frame a member port takes in, usually `ipv4`, `ipv6` and `arp`. Every kind when absent. No platform renders it yet, so `validate` refuses it. */
     ethertypes?: readonly Ethertype[];
+    /** LLDP on member ports. Off when absent: a member's router has no business learning the fabric. */
+    lldp?: boolean;
+    /** Spanning tree on member ports. Off when absent: a member's port faces a router, which must not join the fabric's spanning tree. */
+    stp?: boolean;
 };
 
 /** An internet exchange's fabric: its member ports, a check of its members, and its route servers' config. */
@@ -37,7 +41,9 @@ export class Exchange {
     /**
      * Member ports and a check for an internet exchange's fabric.
      *
-     * - `ports(device)`: every member's port on one switch. A member port is in the peering VLAN and nothing else, takes no part in spanning tree or LLDP, and lets only a trickle of broadcast, multicast and unknown unicast through. With `mac_limit` and `ethertypes`, it also learns that many MAC addresses at most and takes in only those kinds of frame.
+     * - `ports(device)`: every member's port on one switch, each written as
+     *   `{ description: "<name>, AS<asn>", access_vlan: vlan, stp: false, lldp: false, storm_control: { broadcast, multicast, unknown_unicast: { percent: storm_percent } } }`,
+     *   plus `mac_limit` and `ethertypes` when the exchange sets them. `stp` and `lldp` are the exchange's own when it sets them, and storm control is 1 % when `storm_percent` is absent.
      * - `check`: members never share a name, an AS, an address or a port; every address is inside the peering LAN and not reserved; every member port carries the peering VLAN alone.
      * - `bird(server)`: one route server's BIRD 2 config, with a session to every member. Write it to a file for the server; Circuit never logs in to a route server.
      * - `openbgpd(server)`: the same route server's config for OpenBGPD, its `bgpd.conf`, with the same sessions and the same rules.
@@ -55,8 +61,8 @@ export class Exchange {
                 result[port] = {
                     description: `${member.name}, AS${member.asn}`,
                     access_vlan: exchange.vlan,
-                    stp: false,
-                    lldp: false,
+                    stp: exchange.stp ?? false,
+                    lldp: exchange.lldp ?? false,
                     storm_control: { broadcast: { percent }, multicast: { percent }, unknown_unicast: { percent } },
                     ...(exchange.mac_limit !== undefined ? { mac_limit: exchange.mac_limit } : {}),
                     ...(exchange.ethertypes ? { ethertypes: exchange.ethertypes } : {}),