@takodotid/circuit 0.10.0 → 0.12.0

package/dist/presets/index.js

@@ -47,7 +47,13 @@ function neighborPolicies(device) {
   const bgp = device.routing?.bgp;
   return Object.entries(bgp?.neighbors ?? {}).map(([name, neighbor]) => {
     const group = neighbor.group ? bgp?.groups?.[neighbor.group] : undefined;
-    return { name, address: neighbor.address, import: neighbor.import ?? group?.import, export: neighbor.export ?? group?.export };
+    return {
+      name,
+      address: neighbor.address,
+      role: neighbor.role ?? group?.role,
+      import: neighbor.import ?? group?.import,
+      export: neighbor.export ?? group?.export
+    };
   });
 }
 function offered(device, policy) {
@@ -58,6 +64,8 @@ var exportsEndInReject = (devices) => {
   const findings = [];
   for (const device of devices) {
     for (const neighbor of neighborPolicies(device)) {
+      if (neighbor.role === "customer")
+        continue;
       const last = neighbor.export ? device.policies?.[neighbor.export]?.at(-1) : undefined;
       if (neighbor.export && (last?.action !== "reject" || last.match)) {
         findings.push({
@@ -153,14 +161,15 @@ function communityScheme(scheme) {
   const ours = { standard: [`${asn}:*`], large: [`${asn}:*:*`] };
   const information = [scheme.learned_from?.function, scheme.learned_at?.function, scheme.learned_from_as].filter((fn) => fn !== undefined);
   const tag = (neighborClass, neighborAs, options = {}) => {
-    const { site, keepActions = false } = options;
+    const { site } = options;
+    const mayAsk = scheme.requests_from?.includes(neighborClass) ?? false;
     if (scheme.learned_at && site === undefined)
       throw new Error(`communityScheme: tag for AS${neighborAs} needs a site, for learned_at`);
     return {
       description: `Learned from AS${neighborAs}`,
       set: {
         remove_communities: ours.standard,
-        remove_large_communities: keepActions ? information.map((fn) => community(fn, "*")) : ours.large,
+        remove_large_communities: mayAsk ? information.map((fn) => community(fn, "*")) : ours.large,
         add_large_communities: [
           ...scheme.learned_from ? [community(scheme.learned_from.function, scheme.learned_from.classes[neighborClass])] : [],
           ...scheme.learned_at ? [community(scheme.learned_at.function, site)] : [],
@@ -179,8 +188,8 @@ function communityScheme(scheme) {
       action: "accept"
     };
   };
-  const actions = (neighborAs) => [
-    ...scheme.blackhole !== undefined ? [
+  const actions = (neighborAs, options = {}) => [
+    ...scheme.blackhole !== undefined && !options.blackhole ? [
       {
         description: "Blackholed here, never announced",
         match: { large_community: community(scheme.blackhole, 0) },
@@ -199,6 +208,18 @@ function communityScheme(scheme) {
         action: "reject"
       }
     ] : [],
+    ...scheme.blackhole !== undefined && options.blackhole ? [
+      {
+        description: `Blackhole passed on to AS${neighborAs}`,
+        match: { large_community: community(scheme.blackhole, 0) },
+        set: {
+          remove_communities: ours.standard,
+          remove_large_communities: ours.large,
+          add_communities: [options.blackhole]
+        },
+        action: "accept"
+      }
+    ] : [],
     ...PREPENDS.flatMap(([name, times]) => {
       const fn = scheme.prepend?.[name];
       if (fn === undefined)
@@ -241,12 +262,68 @@ function communityScheme(scheme) {
   ];
   return { community, tag, actions, blackhole, catalogue };
 }
+function internetExchange(exchange, members) {
+  const percent = exchange.storm_percent ?? 1;
+  const ports = (device) => {
+    const result = {};
+    for (const member of members) {
+      const port = member.ports[device];
+      if (!port)
+        continue;
+      result[port] = {
+        description: `${member.name}, AS${member.asn}`,
+        access_vlan: exchange.vlan,
+        stp: false,
+        lldp: false,
+        storm_control: { broadcast: { percent }, multicast: { percent }, unknown_unicast: { percent } }
+      };
+    }
+    return result;
+  };
+  const check = (devices) => {
+    const findings = [];
+    const error = (message, device) => findings.push({ level: "error", ...device ? { device } : {}, message });
+    const taken = new Map((exchange.reserved ?? []).map((address) => [address, "reserved"]));
+    members.forEach((member, index) => {
+      for (const other of members.slice(index + 1)) {
+        if (other.name === member.name)
+          error(`member ${member.name} is declared twice`);
+        if (other.asn === member.asn)
+          error(`members ${member.name} and ${other.name} share AS${member.asn}`);
+      }
+      for (const [address, lan] of [
+        [member.ipv4, exchange.lan.ipv4],
+        [member.ipv6, exchange.lan.ipv6]
+      ]) {
+        if (!address)
+          continue;
+        if (!lan || !contains(lan, address))
+          error(`${address} of ${member.name} is outside the peering LAN`);
+        const holder = taken.get(address);
+        if (holder)
+          error(`${address} of ${member.name} is already ${holder === "reserved" ? "reserved" : `${holder}'s`}`);
+        taken.set(address, member.name);
+      }
+      for (const [deviceName, portName] of Object.entries(member.ports)) {
+        const device = devices.find((candidate) => candidate.name === deviceName);
+        const port = device?.ports?.[portName];
+        const carried = port ? vlansOf(port) : [];
+        if (carried.length !== 1 || carried[0] !== exchange.vlan) {
+          error(`port ${portName} of ${member.name} does not carry the peering VLAN alone`, deviceName);
+        }
+      }
+    });
+    return findings;
+  };
+  return { ports, check };
+}
 export {
   vlansOf,
   tunnelsOutsideOffered,
   trustBoundary,
   offered,
   neighborPolicies,
+  internetExchange,
   exportsEndInReject,
   communityScheme,
   bgpSanity,

package/dist/types/presets/index.d.ts

@@ -1,5 +1,5 @@
 import type { Check, Community } from "../core/define";
-import type { AclRule, Device, FilterRule, PolicyRule, Prefix } from "../schema";
+import type { AclRule, Device, FilterRule, IP, PolicyRule, Port, Prefix } from "../schema";
 /** IPv4 sources that never arrive from the internet: loopback, link-local and "this network", after RFC 6890. */
 export declare const MARTIANS: readonly ["127.0.0.0/8", "169.254.0.0/16", "0.0.0.0/8"];
 /** IPv4 private space, RFC 1918. */
@@ -23,16 +23,19 @@ export type SanityLengths = {
 };
 /** Route policy rules rejecting what no neighbor should send: prefixes too short or too long for the global table, and RPKI invalid. Place it first in an import, or as a policy other imports call. */
 export declare function bgpSanity(lengths?: SanityLengths): PolicyRule<never, never>[];
-/** Each BGP neighbor's own policies, or its group's. */
+/** Each BGP neighbor's own policies and role, or its group's. */
 export declare function neighborPolicies(device: Device): {
     name: string;
     address: string;
+    role: import("..").BgpRole | undefined;
     import: string | undefined;
     export: string | undefined;
 }[];
 /** The prefixes an export policy accepts by name. */
 export declare function offered(device: Device, policy: string | undefined): string[];
-/** Every BGP export ends in a reject that matches everything, so nothing leaves by accident. */
+/**
+ * Every BGP export ends in a reject that matches everything, so nothing leaves by accident. An export to a neighbor whose `role` is `customer` is left out: sending a customer everything you know is what it pays for, and cannot leak a route to the rest of the internet.
+ */
 export declare const exportsEndInReject: Check;
 /** The VLANs a port carries, untagged or tagged. */
 export declare const vlansOf: (port: {
@@ -61,6 +64,8 @@ export type CommunityScheme<Class extends string = string> = {
         function: number;
         classes: Readonly<Record<Class, number>>;
     };
+    /** The kinds of neighbor allowed to ask you for something, usually your customers: the requests below that they set on their routes stay. From anyone else, they are removed on import. */
+    requests_from?: readonly NoInfer<Class>[];
     /** Set on import: the site a route was learned at, `asn:function:site`. `sites` names the sites, for the catalogue. */
     learned_at?: {
         function: number;
@@ -82,8 +87,8 @@ export type CommunityScheme<Class extends string = string> = {
 /**
  * Policy rules and a catalogue from one community scheme, so the communities your routers set, the ones they act on, and the ones you publish never disagree.
  *
- * - `tag(neighborClass, neighborAs, { site, keepActions })`: a rule for an import policy. It removes your communities a neighbor set, then adds where the route was learned. `site` is needed when the scheme has `learned_at`. With `keepActions`, for a customer, its action communities stay.
- * - `actions(neighborAs)`: rules for an export policy toward one neighbor. They act on a customer's action communities, then remove all of yours. Place them before the rules that accept.
+ * - `tag(neighborClass, neighborAs, { site })`: a rule for an import policy. It removes your communities a neighbor set, then adds where the route was learned. A neighbor of a class in `requests_from` keeps its requests. `site` is needed when the scheme has `learned_at`.
+ * - `actions(neighborAs, { blackhole })`: rules for an export policy toward one neighbor. They act on a customer's action communities, then remove all of yours. Place them before the rules that accept. A blackholed route goes no further, unless `blackhole` names the neighbor's own blackhole community: then it is passed on with it, so the neighbor drops the traffic too.
  * - `blackhole(prefixSet)`: a rule for a customer's import policy, before anything that rejects long prefixes. It takes a route the customer asked to blackhole, but only inside `prefixSet`, its own space, and drops traffic to it here.
  * - `catalogue`: every community, for `communities` in `defineNetwork`.
  */
@@ -91,9 +96,45 @@ export declare function communityScheme<const Class extends string>(scheme: Comm
     community: (fn: number, parameter: number | string) => string;
     tag: (neighborClass: Class, neighborAs: number, options?: {
         site?: number;
-        keepActions?: boolean;
     }) => PolicyRule<never, never>;
-    actions: (neighborAs: number) => PolicyRule<never, never>[];
+    actions: (neighborAs: number, options?: {
+        blackhole?: string;
+    }) => PolicyRule<never, never>[];
     blackhole: <S extends string>(prefixSet: S) => PolicyRule<never, S>;
     catalogue: Community[];
 };
+/** A member of an internet exchange: a network with a port on the fabric and an address on the peering LAN. */
+export type ExchangeMember = {
+    /** Lowercase, and never reused. */
+    name: string;
+    asn: number;
+    /** The member's port on each fabric switch, by switch name. */
+    ports: Readonly<Record<string, string>>;
+    /** Its addresses on the peering LAN. The route servers peer with these. */
+    ipv4?: IP;
+    ipv6?: IP;
+};
+/** An internet exchange's peering LAN, as its fabric carries it. */
+export type InternetExchange<V extends string> = {
+    /** The peering VLAN, by the name the fabric switches give it. */
+    vlan: V;
+    /** The peering LAN's subnets. */
+    lan: {
+        ipv4?: Prefix;
+        ipv6?: Prefix;
+    };
+    /** Addresses on the peering LAN no member may take, such as the route servers'. */
+    reserved?: readonly IP[];
+    /** How much broadcast, multicast and unknown unicast a member port lets through, in percent of its speed. 1 when absent. */
+    storm_percent?: number;
+};
+/**
+ * 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.
+ * - `check`: members never share a name, an AS or an address; every address is inside the peering LAN and not reserved; every member port carries the peering VLAN alone.
+ */
+export declare function internetExchange<const V extends string>(exchange: InternetExchange<V>, members: readonly ExchangeMember[]): {
+    ports: (device: string) => Record<string, Port<V, string, string, string>>;
+    check: Check;
+};

package/package.json

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

package/src/presets/index.ts

@@ -2,7 +2,7 @@
 
 import { contains } from "../core/addr";
 import type { Check, Community, Finding } from "../core/define";
-import type { AclRule, Device, FilterRule, PolicyRule, Prefix, TcpFlag } from "../schema";
+import type { AclRule, Device, FilterRule, IP, PolicyRule, Port, Prefix, TcpFlag } from "../schema";
 
 /** IPv4 sources that never arrive from the internet: loopback, link-local and "this network", after RFC 6890. */
 export const MARTIANS = ["127.0.0.0/8", "169.254.0.0/16", "0.0.0.0/8"] as const satisfies readonly Prefix[];
@@ -66,13 +66,20 @@ export function bgpSanity(lengths: SanityLengths = {}): PolicyRule<never, never>
     ];
 }
 
-/** Each BGP neighbor's own policies, or its group's. */
+/** Each BGP neighbor's own policies and role, or its group's. */
 export function neighborPolicies(device: Device) {
     const bgp = device.routing?.bgp;
 
     return Object.entries(bgp?.neighbors ?? {}).map(([name, neighbor]) => {
         const group = neighbor.group ? bgp?.groups?.[neighbor.group] : undefined;
-        return { name, address: neighbor.address, import: neighbor.import ?? group?.import, export: neighbor.export ?? group?.export };
+
+        return {
+            name,
+            address: neighbor.address,
+            role: neighbor.role ?? group?.role,
+            import: neighbor.import ?? group?.import,
+            export: neighbor.export ?? group?.export,
+        };
     });
 }
 
@@ -82,12 +89,16 @@ export function offered(device: Device, policy: string | undefined): string[] {
     return rules.filter((rule) => rule.action === "accept" && rule.match?.prefix).map((rule) => rule.match!.prefix!);
 }
 
-/** Every BGP export ends in a reject that matches everything, so nothing leaves by accident. */
+/**
+ * Every BGP export ends in a reject that matches everything, so nothing leaves by accident. An export to a neighbor whose `role` is `customer` is left out: sending a customer everything you know is what it pays for, and cannot leak a route to the rest of the internet.
+ */
 export const exportsEndInReject: Check = (devices) => {
     const findings: Finding[] = [];
 
     for (const device of devices) {
         for (const neighbor of neighborPolicies(device)) {
+            if (neighbor.role === "customer") continue;
+
             const last = neighbor.export ? device.policies?.[neighbor.export]?.at(-1) : undefined;
 
             if (neighbor.export && (last?.action !== "reject" || last.match)) {
@@ -215,6 +226,8 @@ export type CommunityScheme<Class extends string = string> = {
     asn: number;
     /** Set on import: the kind of neighbor a route came from, `asn:function:class`. */
     learned_from?: { function: number; classes: Readonly<Record<Class, number>> };
+    /** The kinds of neighbor allowed to ask you for something, usually your customers: the requests below that they set on their routes stay. From anyone else, they are removed on import. */
+    requests_from?: readonly NoInfer<Class>[];
     /** Set on import: the site a route was learned at, `asn:function:site`. `sites` names the sites, for the catalogue. */
     learned_at?: { function: number; sites?: Readonly<Record<number, string>> };
     /** Set on import: the AS a route was learned from, `asn:function:asn`. */
@@ -238,8 +251,8 @@ const article = (word: string) => (/^[aeiou]/i.test(word) ? `an ${word}` : `a ${
 /**
  * Policy rules and a catalogue from one community scheme, so the communities your routers set, the ones they act on, and the ones you publish never disagree.
  *
- * - `tag(neighborClass, neighborAs, { site, keepActions })`: a rule for an import policy. It removes your communities a neighbor set, then adds where the route was learned. `site` is needed when the scheme has `learned_at`. With `keepActions`, for a customer, its action communities stay.
- * - `actions(neighborAs)`: rules for an export policy toward one neighbor. They act on a customer's action communities, then remove all of yours. Place them before the rules that accept.
+ * - `tag(neighborClass, neighborAs, { site })`: a rule for an import policy. It removes your communities a neighbor set, then adds where the route was learned. A neighbor of a class in `requests_from` keeps its requests. `site` is needed when the scheme has `learned_at`.
+ * - `actions(neighborAs, { blackhole })`: rules for an export policy toward one neighbor. They act on a customer's action communities, then remove all of yours. Place them before the rules that accept. A blackholed route goes no further, unless `blackhole` names the neighbor's own blackhole community: then it is passed on with it, so the neighbor drops the traffic too.
  * - `blackhole(prefixSet)`: a rule for a customer's import policy, before anything that rejects long prefixes. It takes a route the customer asked to blackhole, but only inside `prefixSet`, its own space, and drops traffic to it here.
  * - `catalogue`: every community, for `communities` in `defineNetwork`.
  */
@@ -252,12 +265,9 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
         (fn): fn is number => fn !== undefined
     );
 
-    const tag = (
-        neighborClass: Class,
-        neighborAs: number,
-        options: { site?: number; keepActions?: boolean } = {}
-    ): PolicyRule<never, never> => {
-        const { site, keepActions = false } = options;
+    const tag = (neighborClass: Class, neighborAs: number, options: { site?: number } = {}): PolicyRule<never, never> => {
+        const { site } = options;
+        const mayAsk = scheme.requests_from?.includes(neighborClass) ?? false;
         if (scheme.learned_at && site === undefined)
             throw new Error(`communityScheme: tag for AS${neighborAs} needs a site, for learned_at`);
 
@@ -265,7 +275,7 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
             description: `Learned from AS${neighborAs}`,
             set: {
                 remove_communities: ours.standard,
-                remove_large_communities: keepActions ? information.map((fn) => community(fn, "*")) : ours.large,
+                remove_large_communities: mayAsk ? information.map((fn) => community(fn, "*")) : ours.large,
                 add_large_communities: [
                     ...(scheme.learned_from ? [community(scheme.learned_from.function, scheme.learned_from.classes[neighborClass])] : []),
                     ...(scheme.learned_at ? [community(scheme.learned_at.function, site!)] : []),
@@ -286,8 +296,8 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
         };
     };
 
-    const actions = (neighborAs: number): PolicyRule<never, never>[] => [
-        ...(scheme.blackhole !== undefined
+    const actions = (neighborAs: number, options: { blackhole?: string } = {}): PolicyRule<never, never>[] => [
+        ...(scheme.blackhole !== undefined && !options.blackhole
             ? [
                   {
                       description: "Blackholed here, never announced",
@@ -310,6 +320,20 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
                   },
               ]
             : []),
+        ...(scheme.blackhole !== undefined && options.blackhole
+            ? [
+                  {
+                      description: `Blackhole passed on to AS${neighborAs}`,
+                      match: { large_community: community(scheme.blackhole, 0) },
+                      set: {
+                          remove_communities: ours.standard,
+                          remove_large_communities: ours.large,
+                          add_communities: [options.blackhole],
+                      },
+                      action: "accept" as const,
+                  },
+              ]
+            : []),
         ...PREPENDS.flatMap(([name, times]) => {
             const fn = scheme.prepend?.[name];
             if (fn === undefined) return [];
@@ -362,3 +386,95 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
 
     return { community, tag, actions, blackhole, catalogue };
 }
+
+/** A member of an internet exchange: a network with a port on the fabric and an address on the peering LAN. */
+export type ExchangeMember = {
+    /** Lowercase, and never reused. */
+    name: string;
+    asn: number;
+    /** The member's port on each fabric switch, by switch name. */
+    ports: Readonly<Record<string, string>>;
+    /** Its addresses on the peering LAN. The route servers peer with these. */
+    ipv4?: IP;
+    ipv6?: IP;
+};
+
+/** An internet exchange's peering LAN, as its fabric carries it. */
+export type InternetExchange<V extends string> = {
+    /** The peering VLAN, by the name the fabric switches give it. */
+    vlan: V;
+    /** The peering LAN's subnets. */
+    lan: { ipv4?: Prefix; ipv6?: Prefix };
+    /** Addresses on the peering LAN no member may take, such as the route servers'. */
+    reserved?: readonly IP[];
+    /** How much broadcast, multicast and unknown unicast a member port lets through, in percent of its speed. 1 when absent. */
+    storm_percent?: number;
+};
+
+/**
+ * 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.
+ * - `check`: members never share a name, an AS or an address; every address is inside the peering LAN and not reserved; every member port carries the peering VLAN alone.
+ */
+export function internetExchange<const V extends string>(exchange: InternetExchange<V>, members: readonly ExchangeMember[]) {
+    const percent = exchange.storm_percent ?? 1;
+
+    const ports = (device: string) => {
+        const result: Record<string, Port<V, string, string, string>> = {};
+
+        for (const member of members) {
+            const port = member.ports[device];
+            if (!port) continue;
+
+            result[port] = {
+                description: `${member.name}, AS${member.asn}`,
+                access_vlan: exchange.vlan,
+                stp: false,
+                lldp: false,
+                storm_control: { broadcast: { percent }, multicast: { percent }, unknown_unicast: { percent } },
+            };
+        }
+
+        return result;
+    };
+
+    const check: Check = (devices) => {
+        const findings: Finding[] = [];
+        const error = (message: string, device?: string) => findings.push({ level: "error", ...(device ? { device } : {}), message });
+        const taken = new Map<string, string>((exchange.reserved ?? []).map((address) => [address, "reserved"]));
+
+        members.forEach((member, index) => {
+            for (const other of members.slice(index + 1)) {
+                if (other.name === member.name) error(`member ${member.name} is declared twice`);
+                if (other.asn === member.asn) error(`members ${member.name} and ${other.name} share AS${member.asn}`);
+            }
+
+            for (const [address, lan] of [
+                [member.ipv4, exchange.lan.ipv4],
+                [member.ipv6, exchange.lan.ipv6],
+            ] as const) {
+                if (!address) continue;
+                if (!lan || !contains(lan, address)) error(`${address} of ${member.name} is outside the peering LAN`);
+
+                const holder = taken.get(address);
+                if (holder) error(`${address} of ${member.name} is already ${holder === "reserved" ? "reserved" : `${holder}'s`}`);
+                taken.set(address, member.name);
+            }
+
+            for (const [deviceName, portName] of Object.entries(member.ports)) {
+                const device = devices.find((candidate) => candidate.name === deviceName);
+                const port = device?.ports?.[portName as keyof typeof device.ports];
+                const carried = port ? vlansOf(port) : [];
+
+                if (carried.length !== 1 || carried[0] !== exchange.vlan) {
+                    error(`port ${portName} of ${member.name} does not carry the peering VLAN alone`, deviceName);
+                }
+            }
+        });
+
+        return findings;
+    };
+
+    return { ports, check };
+}