@takodotid/circuit 0.40.0 → 0.41.0

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

@@ -1,48 +1,67 @@
-import type { Exchange as ExchangeLan, Family, FilterRule, Gre, InterfaceAddress, IP, LargeCommunity, Neighbor, NeighborSettings, PolicyRule, Port, Secret, StandardCommunity, Vlan, VlanInterface } from "../schema/index.js";
-import { type Announced } from "./bgp.js";
-/** One network we exchange routes with: a transit we buy, an exchange's route servers, or a peer. */
+import type { Exchange as ExchangeLan, Family, FilterRule, Gre, InterfaceAddress, IP, Neighbor, NeighborSettings, PolicyRule, Port, Secret, Vlan, VlanInterface } from "../schema/index.js";
+/** A route policy an upstream's sessions use: its name on the device, and its rules, in order. */
+export type UpstreamPolicy = {
+    /** The policy's name, as the device carries it. */
+    name: string;
+    /** Its rules, in order. Nothing is added to them unless `mapImports` or `mapExports` adds it. */
+    rules: readonly PolicyRule<string, string>[];
+};
+/** A VLAN by its name and its ID. */
+export type NamedVlan = {
+    name: string;
+    id: number;
+};
+/** One network we exchange routes with: a transit we buy, an exchange's route servers, or a peer. Every name it puts on a device is written here. */
 export type Upstream = {
     /** Its name as people write it, for descriptions: `Transit A`. The key when absent. */
     name?: string;
     asn: number;
     /** What it is to us: `provider` for a transit, `rs` for an exchange's route servers, `peer` for a direct session. */
     role: "provider" | "rs" | "peer";
-    /** Where it lands on our side: a VLAN, our addresses on it, and the switch port it arrives on. A peer over a tunnel, or over an exchange's VLAN, has none. */
+    /** Where it lands on our side: a VLAN, the router's interface on it, and the switch port it arrives on. A peer over a tunnel, or over an exchange's VLAN, has none. */
     handoff?: {
-        /** The VLAN's ID. */
-        vlan: number;
-        /** It sends its VLAN tagged: its port gets a native VLAN of its own with this ID, which nothing else is in. Untagged when absent. */
-        native?: number;
-        /** Its number in names with `{number}`, such as `core-ipt01-transita`. Written here, so removing another upstream renumbers nothing. */
-        number?: number;
+        /** The VLAN it arrives on. */
+        vlan: NamedVlan;
+        /** It sends its VLAN tagged: its switch port gets this native VLAN, which nothing else is in. Untagged when absent. */
+        native?: NamedVlan;
+        /** The router's VLAN interface on it. */
+        interface: string;
         /** Our addresses on it. `{ address, peer }` for a point-to-point address whose far end is outside its own prefix. */
         addresses: readonly (InterfaceAddress | {
             address: InterfaceAddress;
             peer: IP;
         })[];
-        /** The switch port it arrives on. */
+        /**
+         * The switch port it arrives on. LLDP and spanning tree are off there unless `lldp` or `stp` says otherwise: an upstream's port faces someone else's network, which should neither learn ours nor join our spanning tree.
+         */
         port?: {
             device: string;
             port: string;
             storm_control?: Port<string, string, string, string>["storm_control"];
+            /** LLDP on the port. Off when absent. */
+            lldp?: boolean;
+            /** Spanning tree on the port. Off when absent. */
+            stp?: boolean;
         };
         /** An exchange's LAN, for `circuit peeringdb`. */
         exchange?: ExchangeLan;
     };
-    /** A GRE tunnel to it. `number` is its number in names with `{number}`. */
+    /** A GRE tunnel to it, and the router's interface for it. */
     tunnel?: {
+        interface: string;
         local: IP;
         remote: IP;
         addresses: readonly InterfaceAddress[];
         mtu?: number;
-        number?: number;
     };
     /** Our BGP sessions with it, by name: its address, and ours when it is not the interface's. */
     sessions: Readonly<Record<string, {
         address: IP;
         local_address?: IP;
     }>>;
-    /** The sessions are more than one hop away, from this address of ours. They share a group. */
+    /** 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. */
+    group?: string;
+    /** The sessions are more than one hop away, from this address of ours. */
     multihop?: {
         local_address: IP;
         families?: readonly Family[];
@@ -53,185 +72,100 @@ export type Upstream = {
         ipv4?: number;
         ipv6?: number;
     };
-    /** What we take. Nothing when absent. */
-    import?: {
-        /** Its default route, at this preference. */
-        default?: {
-            local_pref?: number;
-            description?: string;
-        };
-        /** Its routes, through `Bgp.learn`: the `before` rules, sanity, this preference, the tag. Only the default when absent. */
-        learn?: {
-            local_pref?: number;
-            before?: readonly PolicyRule<never, never>[];
-        };
-    };
-    /** Rules of yours in its export, between the community actions and what we announce, such as a prepend. */
-    export?: readonly PolicyRule<never, never>[];
-    /** What we announce to it. Everything else is rejected. */
-    announce: readonly Announced[];
-    /** Drop RFC 1918 sources arriving from it. `privateDrops()` lists the VLANs. */
+    /** What we take, as its policy. Nothing when absent. */
+    import?: UpstreamPolicy;
+    /** What we send it, as its policy. */
+    export: UpstreamPolicy;
+    /** Its VLAN is listed by `privateDrops()`, for an ACL that drops RFC 1918 sources arriving from it. Nothing else is done with it. */
     drop_private?: true;
 };
-/** Upstreams by key. The key names everything built from it. */
+/** Upstreams by key. */
 export type UpstreamCatalog = Readonly<Record<string, Upstream>>;
-/** A name made from an upstream: `{key}` is its key, `{KEY}` the key in capitals, `{number}` its `handoff.number` or `tunnel.number`. */
-type Pattern = string;
-/** A pattern for every upstream, or one per role. A role left out takes the default. */
-type ByRole = Pattern | {
-    readonly provider?: Pattern;
-    readonly rs?: Pattern;
-    readonly peer?: Pattern;
+/** What every upstream's policies share, written once: plain functions over each policy's rules. */
+export type UpstreamOptions = {
+    /** Each import's rules as the device gets them, from the rules the upstream writes. The rules as written when absent. */
+    mapImports?: (rules: readonly PolicyRule<string, string>[], key: string, upstream: Upstream) => readonly PolicyRule<string, string>[];
+    /** Each export's rules as the device gets them, from the rules the upstream writes. The rules as written when absent. */
+    mapExports?: (rules: readonly PolicyRule<string, string>[], key: string, upstream: Upstream) => readonly PolicyRule<string, string>[];
 };
-/** How the names built from each upstream are made. Each one left out takes its default. */
-export type UpstreamNames = {
-    /** The VLAN a handoff is on. `{key}` when absent. */
-    vlan?: ByRole;
-    /** The native VLAN of a handoff sent tagged. `{key}-native` when absent. */
-    native?: Pattern;
-    /** The router's interface: per role, and `tunnel` for one reached over a tunnel. `{key}` when absent. */
-    interface?: Pattern | {
-        readonly provider?: Pattern;
-        readonly rs?: Pattern;
-        readonly peer?: Pattern;
-        readonly tunnel?: Pattern;
-    };
-    /** The import policy. `{KEY}-IN` when absent. */
-    import?: Pattern;
-    /** The export policy. `{KEY}-OUT` when absent. */
-    export?: Pattern;
-    /** The BGP group of an exchange's route servers or of multihop sessions. `{key}` when absent. */
-    group?: Pattern;
-    /** The description of a handoff's switch port. Its `name` when absent. No device names it, so it may be any function. */
-    port?: (key: string, upstream: Upstream) => string;
-};
-/** How each upstream's policies are written: shared by every upstream of a catalog. */
-export type UpstreamPolicies<P extends string> = {
-    /** A policy holding `Bgp.sanity()` that each import calls. The sanity rules are written in each import when absent. */
-    sanity?: P;
-    /** Where a route came from, by upstream: a community or a rule, such as `communityScheme(...).tag(...)`. Nothing is tagged when absent. */
-    tag?: (key: string, upstream: Upstream) => StandardCommunity | LargeCommunity | PolicyRule<never, never>;
-    /** Rules first in each export, such as `communityScheme(...).actions(upstream.asn)`. */
-    actions?: (key: string, upstream: Upstream) => readonly PolicyRule<never, never>[];
-    /** The source address for routes of its family, one per family. */
-    sources?: readonly IP[];
-};
-/** The names a device can refer to, and their patterns when the project gives none. */
-declare const DEFAULTS: {
-    readonly vlan: "{key}";
-    readonly native: "{key}-native";
-    readonly interface: "{key}";
-    readonly import: "{KEY}-IN";
-    readonly export: "{KEY}-OUT";
-    readonly group: "{key}";
-};
-type Defaults = typeof DEFAULTS;
-type Field = keyof Defaults;
-type Key<C> = keyof C & string;
-/** The upstreams that land on a VLAN of ours. */
-type Landed<C> = {
-    [K in Key<C>]: C[K] extends {
-        handoff: object;
-    } ? K : never;
-}[Key<C>];
-/** The upstreams that send their VLAN tagged. */
-type Tagged<C> = {
-    [K in Key<C>]: C[K] extends {
+type Values<T> = T[keyof T];
+/** Each VLAN name the catalog writes. */
+type VlanName<C> = Values<{
+    [K in keyof C]: C[K] extends {
         handoff: {
-            native: number;
+            vlan: {
+                name: infer N extends string;
+            };
         };
-    } ? K : never;
-}[Key<C>];
-/** The upstreams reached over a tunnel. */
-type Tunneled<C> = {
-    [K in Key<C>]: C[K] extends {
-        tunnel: object;
-    } ? K : never;
-}[Key<C>];
-/** The upstreams whose sessions share a group: an exchange's route servers, or multihop sessions. */
-type Grouped<C> = {
-    [K in Key<C>]: C[K] extends {
-        role: "rs";
-    } | {
-        multihop: object;
-    } ? K : never;
-}[Key<C>];
-/** The upstreams we take routes from. */
-type Importing<C> = {
-    [K in Key<C>]: C[K] extends {
-        import: object;
-    } ? K : never;
-}[Key<C>];
-/** The project's pattern for a name, or the default. */
-type PatternOf<N, F extends Field> = N extends {
-    [X in F]: infer P;
-} ? P : Defaults[F];
-/** The pattern an upstream takes: the only one, its tunnel's, its role's, or the default. */
-type Chosen<P, U, F extends Field> = P extends string ? P : U extends {
-    tunnel: object;
-} ? P extends {
-    tunnel: infer T extends string;
-} ? T : Defaults[F] : U extends {
-    role: infer R extends string;
-} ? P extends {
-    [X in R]: infer T extends string;
-} ? T : Defaults[F] : Defaults[F];
-/** Every `From` in `S` replaced. */
-type Replace<S extends string, From extends string, To extends string> = S extends `${infer A}${From}${infer B}` ? `${A}${To}${Replace<B, From, To>}` : S;
-/** An upstream's `handoff.number` or `tunnel.number`. */
-type NumberOf<U> = U extends {
-    handoff: {
-        number: infer N extends number;
-    };
-} ? N : U extends {
-    tunnel: {
-        number: infer N extends number;
-    };
-} ? N : number;
-/** The name built for upstream `K`: its pattern with the key, the key in capitals and its number filled in. */
-type Named<C, N, F extends Field, K extends Key<C>> = Replace<Replace<Replace<Chosen<PatternOf<N, F>, C[K], F>, "{key}", K>, "{KEY}", Uppercase<K>>, "{number}", `${NumberOf<C[K]>}`>;
-/** Each of these upstreams' names. */
-type Names<C, N, F extends Field, Ks extends Key<C>> = {
-    [K in Ks]: Named<C, N, F, K>;
-}[Ks];
-/** The catalog as written, with any key the shape does not have refused, at every level. */
-type Exact<S, T> = T extends readonly unknown[] | string | number | boolean | Secret | ((...args: never[]) => unknown) ? T : S extends unknown ? {
-    [K in keyof T]: K extends keyof S ? Exact<NonNullable<S[K]>, T[K]> : never;
-} : never;
-/** The names as written, with a name or a role Upstreams does not make refused. */
-type ExactNames<N> = {
-    [F in keyof N]: F extends keyof UpstreamNames ? N[F] extends string | ((...args: never[]) => unknown) ? N[F] : {
-        [R in keyof N[F]]: R extends "provider" | "rs" | "peer" | "tunnel" ? N[F][R] : never;
-    } : never;
-};
+    } ? N : never;
+}>;
+/** Each native VLAN name. */
+type NativeName<C> = Values<{
+    [K in keyof C]: C[K] extends {
+        handoff: {
+            native: {
+                name: infer N extends string;
+            };
+        };
+    } ? N : never;
+}>;
+/** Each router interface on a handoff. */
+type HandoffInterface<C> = Values<{
+    [K in keyof C]: C[K] extends {
+        handoff: {
+            interface: infer N extends string;
+        };
+    } ? N : never;
+}>;
+/** Each router interface for a tunnel. */
+type TunnelInterface<C> = Values<{
+    [K in keyof C]: C[K] extends {
+        tunnel: {
+            interface: infer N extends string;
+        };
+    } ? N : never;
+}>;
+/** Each policy name. */
+type PolicyName<C> = Values<{
+    [K in keyof C]: (C[K] extends {
+        import: {
+            name: infer N extends string;
+        };
+    } ? N : never) | (C[K] extends {
+        export: {
+            name: infer N extends string;
+        };
+    } ? N : never);
+}>;
+/** Each BGP group name. */
+type GroupName<C> = Values<{
+    [K in keyof C]: C[K] extends {
+        group: infer N extends string;
+    } ? N : never;
+}>;
 /** A network's upstreams written once, and each device's part built from them. */
 export declare class Upstreams {
     /**
-     * Each upstream written once: its AS, where it lands, its sessions, limits and policy. Everything a device needs is built from it, under names made from each key, so a device that names one is checked. By default:
-     *
-     * - VLAN `<key>`, and `<key>-native` for one that sends its VLAN tagged. The router's interface is `<key>` too, a VLAN interface or a GRE tunnel.
-     * - Policies `<KEY>-IN` and `<KEY>-OUT`; a BGP group `<key>` for an exchange's route servers or multihop sessions.
+     * Each upstream written once: its AS, where it lands, its sessions, limits and policies, and every name it puts on a device. Everything a device needs is built from it:
      *
-     * `names` gives patterns of your own, such as `{ interface: { provider: "core-ipt0{number}-{key}" } }`; see `UpstreamNames`.
+     * - On the router: `vlans()`, `interfaces()`, `uplinks()`, `groups()`, `neighbors()`, `policies()`, `tunnelRules()`, `addresses()`.
+     * - On a switch: `vlans(device)`, `ports(device)`, `vlansOn(device)`.
+     * - For checks and ACLs: `untrusted()`, `natives()`, `privateDrops()`.
      *
-     * On the router: `vlans()`, `interfaces()`, `uplinks()`, `groups()`, `neighbors()`, `policies({ ... })`, `tunnelRules()`, `addresses()`. On a switch: `vlans(device)`, `ports(device)`, `vlansOn(device)`. For checks and ACLs: `untrusted()`, `natives()`, `privateDrops()`. Lists follow the catalog's order, where order counts on a device.
+     * An import or export is the rules the upstream writes, in order, passed through `mapImports` or `mapExports` when given: what every upstream shares, such as a call to a sanity policy or the community actions, goes there. Nothing else is added. Lists follow the catalog's order, where order counts on a device. A key the shape doesn't have is refused by the type, by its name.
      */
-    static define<const C extends UpstreamCatalog, const N extends UpstreamNames = {}>(catalog: C & {
-        [K in keyof C]: Exact<Upstream, C[K]>;
-    }, options?: {
-        names?: N & ExactNames<N>;
-    }): {
-        vlans: <const D extends string | undefined = undefined>(device?: D) => D extends string ? { [K in Names<C, N, "vlan", Landed<C>>]: Vlan; } & { [K in Names<C, N, "native", Tagged<C>>]: Vlan; } : { [K in Names<C, N, "vlan", Landed<C>>]: Vlan; };
-        vlansOn: (device: string) => Names<C, N, "vlan", Landed<C>>[];
-        ports: (device: string) => Record<string, Port<Names<C, N, "native", Tagged<C>> | Names<C, N, "vlan", Landed<C>>, never, never, never>>;
-        interfaces: () => { [K in Names<C, N, "interface", Landed<C>>]: VlanInterface<Names<C, N, "vlan", Landed<C>>, never>; } & { [K in Names<C, N, "interface", Tunneled<C>>]: Gre<never>; };
-        uplinks: () => Names<C, N, "interface", Landed<C>>[];
-        groups: () => Record<Names<C, N, "group", Grouped<C>>, NeighborSettings<Names<C, N, "export", Key<C>> | Names<C, N, "import", Importing<C>>>>;
-        neighbors: () => Record<string, Neighbor<Names<C, N, "export", Key<C>> | Names<C, N, "import", Importing<C>>, Names<C, N, "group", Grouped<C>>>>;
-        policies: <const P extends string = never>(options?: UpstreamPolicies<P>) => Record<Names<C, N, "export", Key<C>> | Names<C, N, "import", Importing<C>>, PolicyRule<P, never>[]>;
-        untrusted: () => (Names<C, N, "native", Tagged<C>> | Names<C, N, "vlan", Landed<C>>)[];
-        natives: () => Names<C, N, "native", Tagged<C>>[];
-        privateDrops: () => Names<C, N, "vlan", Landed<C>>[];
+    static define<const C extends UpstreamCatalog>(catalog: C & UpstreamCatalog, options?: UpstreamOptions): {
+        vlans: (device?: string) => { [K in VlanName<C> | NativeName<C>]: Vlan; };
+        vlansOn: (device: string) => VlanName<C>[];
+        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>>>;
+        policies: () => Record<PolicyName<C>, PolicyRule<never, never>[]>;
+        untrusted: () => (NativeName<C> | VlanName<C>)[];
+        natives: () => NativeName<C>[];
+        privateDrops: () => VlanName<C>[];
         tunnelRules: () => FilterRule<never, never>[];
         addresses: () => IP[];
     };

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

@@ -96,7 +96,11 @@ 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`. An address NAT uses inside one stays tracked, or its replies would never be translated back. 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`. Everything is tracked when absent.
+     *
+     * Each address NAT uses inside one of these prefixes (a source translation's `to`, a destination translation's `to` or matched `dst`) stays tracked: Circuit writes two accept rules for it, one for traffic to it and one for traffic from it, before the untracked rules. Without them, a reply to that address would skip tracking and never be translated back.
+     */
     untracked?: readonly Prefix[];
 };
 /** A stateless rule evaluated in hardware where traffic arrives, before routing. */

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/package.json

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

package/src/core/validator.ts

@@ -332,12 +332,20 @@ export class Validator {
         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.