@takodotid/circuit 0.15.0 → 0.16.0

package/dist/presets/index.js

@@ -160,22 +160,15 @@ function communityScheme(scheme) {
   const community = (fn, parameter) => `${asn}:${fn}:${parameter}`;
   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 requests = [
-    { functions: [scheme.do_not_announce?.function], trusted: scheme.do_not_announce?.trusted },
-    { functions: PREPENDS.map(([name]) => scheme.prepend?.[name]), trusted: scheme.prepend?.trusted },
-    { functions: [scheme.blackhole?.function], trusted: scheme.blackhole?.trusted }
-  ].map(({ functions, trusted }) => ({ functions: functions.filter((fn) => fn !== undefined), trusted: trusted ?? [] }));
   const tag = (neighborClass, neighborAs, options = {}) => {
-    const { site } = options;
-    const untrusted = requests.filter((request) => !request.trusted.includes(neighborClass)).flatMap((request) => request.functions);
-    const trustedForAny = requests.some((request) => request.functions.length && request.trusted.includes(neighborClass));
+    const { site, trusted = false } = options;
     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: trustedForAny ? [...information, ...untrusted].map((fn) => community(fn, "*")) : ours.large,
+        remove_large_communities: trusted ? 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)] : [],
@@ -184,67 +177,69 @@ function communityScheme(scheme) {
       }
     };
   };
-  const blackhole = (neighborClass, prefixSet) => {
-    if (scheme.blackhole === undefined)
+  const blackhole = (prefixSets) => {
+    const fn = scheme.blackhole?.function;
+    if (fn === undefined)
       throw new Error("communityScheme: blackhole needs a function number in the scheme");
-    if (!scheme.blackhole.trusted.includes(neighborClass))
-      throw new Error(`communityScheme: ${neighborClass} is not trusted to ask for a blackhole`);
-    return {
+    return prefixSets.map((prefixSet) => ({
       description: "Blackhole, asked by the neighbor",
-      match: { large_community: community(scheme.blackhole.function, 0), prefix_set: prefixSet },
+      match: { large_community: community(fn, 0), prefix_set: prefixSet },
       set: { blackhole: true },
       action: "accept"
-    };
+    }));
   };
-  const actions = (neighborAs, options = {}) => [
-    ...scheme.blackhole !== undefined && !options.blackhole ? [
-      {
-        description: "Blackholed here, never announced",
-        match: { large_community: community(scheme.blackhole.function, 0) },
-        action: "reject"
-      }
-    ] : [],
-    ...scheme.do_not_announce !== undefined ? [
-      {
-        description: "Asked not to be announced anywhere",
-        match: { large_community: community(scheme.do_not_announce.function, 0) },
-        action: "reject"
-      },
-      {
-        description: `Asked not to be announced to AS${neighborAs}`,
-        match: { large_community: community(scheme.do_not_announce.function, neighborAs) },
-        action: "reject"
-      }
-    ] : [],
-    ...scheme.blackhole !== undefined && options.blackhole ? [
-      {
-        description: `Blackhole passed on to AS${neighborAs}`,
-        match: { large_community: community(scheme.blackhole.function, 0) },
-        set: {
-          remove_communities: ours.standard,
-          remove_large_communities: ours.large,
-          add_communities: [options.blackhole]
+  const actions = (neighborAs) => {
+    const passOn = scheme.blackhole?.upstreams?.[neighborAs];
+    return [
+      ...scheme.blackhole !== undefined && !passOn ? [
+        {
+          description: "Blackholed here, never announced",
+          match: { large_community: community(scheme.blackhole.function, 0) },
+          action: "reject"
+        }
+      ] : [],
+      ...scheme.do_not_announce !== undefined ? [
+        {
+          description: "Asked not to be announced anywhere",
+          match: { large_community: community(scheme.do_not_announce, 0) },
+          action: "reject"
         },
-        action: "accept"
-      }
-    ] : [],
-    ...PREPENDS.flatMap(([name, times]) => {
-      const fn = scheme.prepend?.[name];
-      if (fn === undefined)
-        return [];
-      return [
         {
-          description: `Asked to prepend ${name.replace("_", " ")} to AS${neighborAs}`,
-          match: { large_community: community(fn, neighborAs) },
-          set: { prepend: times }
+          description: `Asked not to be announced to AS${neighborAs}`,
+          match: { large_community: community(scheme.do_not_announce, neighborAs) },
+          action: "reject"
         }
-      ];
-    }),
-    {
-      description: "Our communities stay inside our network",
-      set: { remove_communities: ours.standard, remove_large_communities: ours.large }
-    }
-  ];
+      ] : [],
+      ...scheme.blackhole !== undefined && passOn ? [
+        {
+          description: `Blackhole passed on to AS${neighborAs}`,
+          match: { large_community: community(scheme.blackhole.function, 0) },
+          set: {
+            remove_communities: ours.standard,
+            remove_large_communities: ours.large,
+            add_communities: [passOn]
+          },
+          action: "accept"
+        }
+      ] : [],
+      ...PREPENDS.flatMap(([name, times]) => {
+        const fn = scheme.prepend?.[name];
+        if (fn === undefined)
+          return [];
+        return [
+          {
+            description: `Asked to prepend ${name.replace("_", " ")} to AS${neighborAs}`,
+            match: { large_community: community(fn, neighborAs) },
+            set: { prepend: times }
+          }
+        ];
+      }),
+      {
+        description: "Our communities stay inside our network",
+        set: { remove_communities: ours.standard, remove_large_communities: ours.large }
+      }
+    ];
+  };
   const catalogue = [
     ...Object.entries(scheme.learned_from?.classes ?? {}).map(([name, value]) => ({
       community: community(scheme.learned_from.function, value),
@@ -259,14 +254,19 @@ function communityScheme(scheme) {
     ] : [],
     ...scheme.learned_from_as !== undefined ? [{ community: community(scheme.learned_from_as, "nnn"), description: "Learned from AS$0" }] : [],
     ...scheme.do_not_announce !== undefined ? [
-      { community: community(scheme.do_not_announce.function, 0), description: "Do not announce to anyone" },
-      { community: community(scheme.do_not_announce.function, "nnn"), description: "Do not announce to AS$0" }
+      { community: community(scheme.do_not_announce, 0), description: "Do not announce to anyone" },
+      { community: community(scheme.do_not_announce, "nnn"), description: "Do not announce to AS$0" }
     ] : [],
     ...PREPENDS.flatMap(([name]) => {
       const fn = scheme.prepend?.[name];
       return fn === undefined ? [] : [{ community: community(fn, "nnn"), description: `Prepend ${name.replace("_", " ")} to AS$0` }];
     }),
-    ...scheme.blackhole !== undefined ? [{ community: community(scheme.blackhole.function, 0), description: `Blackhole: dropped in AS${asn}, not announced further` }] : []
+    ...scheme.blackhole !== undefined ? [
+      {
+        community: community(scheme.blackhole.function, 0),
+        description: Object.keys(scheme.blackhole.upstreams ?? {}).length ? `Blackhole: dropped in AS${asn} and by its upstreams that take it` : `Blackhole: dropped in AS${asn}, not announced further`
+      }
+    ] : []
   ];
   return { community, tag, actions, blackhole, catalogue };
 }

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

@@ -72,42 +72,39 @@ export type CommunityScheme<Class extends string = string> = {
     /** Set on import: the AS a route was learned from, `asn:function:asn`. */
     learned_from_as?: number;
     /** A neighbor asks: do not announce the route to an AS, `asn:function:asn`, or to anyone, `asn:function:0`. */
-    do_not_announce?: Request<Class> & {
-        function: number;
-    };
+    do_not_announce?: number;
     /** A neighbor asks: prepend toward an AS once, twice or three times, `asn:function:asn`. */
-    prepend?: Request<Class> & {
+    prepend?: {
         once?: number;
         twice?: number;
         three_times?: number;
     };
-    /** A neighbor asks: drop traffic to the route in your network, before it reaches them, `asn:function:0`. */
-    blackhole?: Request<Class> & {
+    /**
+     * A neighbor asks: drop all traffic to this route, `asn:function:0`, usually one address under attack. Your router drops it, and so does every upstream in `upstreams`.
+     *
+     * `upstreams` maps an upstream's AS to its own blackhole community, as its NOC gives it. The route is passed to that upstream with it, so the traffic stops before it reaches your links. An upstream not listed never receives the route.
+     */
+    blackhole?: {
         function: number;
+        upstreams?: Readonly<Record<number, string>>;
     };
 };
-/** Something a neighbor can ask you for, and who may. */
-type Request<Class extends string> = {
-    /** The classes allowed to ask for it, from `learned_from.classes`. From anyone else, the request is removed when the route comes in. */
-    trusted: readonly NoInfer<Class>[];
-};
 /**
  * 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 })`: a rule for an import policy. It removes your communities a neighbor set, then adds where the route was learned. A neighbor keeps the requests its class is trusted with. `site` is needed when the scheme has `learned_at`.
+ * - `tag(neighborClass, neighborAs, { site, trusted })`: a rule for an import policy. It removes your communities a neighbor set, then adds where the route was learned. A `trusted` neighbor keeps its requests: do not announce, prepend, blackhole. `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(neighborClass, prefixSet)`: a rule for the import policy of a neighbor trusted with blackholes, before anything that rejects long prefixes. It takes a route the neighbor asked to blackhole, but only inside `prefixSet`, its own space, and drops traffic to it here.
+ * - `blackhole(prefixSets)`: rules for the import policy of a neighbor you trust with blackholes, before anything that rejects long prefixes. They take a route the neighbor asked to blackhole, but only inside `prefixSets`, its own space, and drop traffic to it here. One rule per set, so one call covers both families.
  * - `catalogue`: every community, for `communities` in `defineNetwork`.
  */
 export declare function communityScheme<const Class extends string>(scheme: CommunityScheme<Class>): {
     community: (fn: number, parameter: number | string) => string;
     tag: (neighborClass: Class, neighborAs: number, options?: {
         site?: number;
+        trusted?: boolean;
     }) => PolicyRule<never, never>;
-    actions: (neighborAs: number, options?: {
-        blackhole?: string;
-    }) => PolicyRule<never, never>[];
-    blackhole: <S extends string>(neighborClass: Class, prefixSet: S) => PolicyRule<never, S>;
+    actions: (neighborAs: number) => PolicyRule<never, never>[];
+    blackhole: <S extends string>(prefixSets: readonly 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. */
@@ -145,4 +142,3 @@ export declare function internetExchange<const V extends string>(exchange: Inter
     ports: (device: string) => Record<string, Port<V, string, string, string>>;
     check: Check;
 };
-export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.15.0",
+    "version": "0.16.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

@@ -231,17 +231,15 @@ export type CommunityScheme<Class extends string = string> = {
     /** Set on import: the AS a route was learned from, `asn:function:asn`. */
     learned_from_as?: number;
     /** A neighbor asks: do not announce the route to an AS, `asn:function:asn`, or to anyone, `asn:function:0`. */
-    do_not_announce?: Request<Class> & { function: number };
+    do_not_announce?: number;
     /** A neighbor asks: prepend toward an AS once, twice or three times, `asn:function:asn`. */
-    prepend?: Request<Class> & { once?: number; twice?: number; three_times?: number };
-    /** A neighbor asks: drop traffic to the route in your network, before it reaches them, `asn:function:0`. */
-    blackhole?: Request<Class> & { function: number };
-};
-
-/** Something a neighbor can ask you for, and who may. */
-type Request<Class extends string> = {
-    /** The classes allowed to ask for it, from `learned_from.classes`. From anyone else, the request is removed when the route comes in. */
-    trusted: readonly NoInfer<Class>[];
+    prepend?: { once?: number; twice?: number; three_times?: number };
+    /**
+     * A neighbor asks: drop all traffic to this route, `asn:function:0`, usually one address under attack. Your router drops it, and so does every upstream in `upstreams`.
+     *
+     * `upstreams` maps an upstream's AS to its own blackhole community, as its NOC gives it. The route is passed to that upstream with it, so the traffic stops before it reaches your links. An upstream not listed never receives the route.
+     */
+    blackhole?: { function: number; upstreams?: Readonly<Record<number, string>> };
 };
 
 const PREPENDS = [
@@ -255,9 +253,9 @@ 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 })`: a rule for an import policy. It removes your communities a neighbor set, then adds where the route was learned. A neighbor keeps the requests its class is trusted with. `site` is needed when the scheme has `learned_at`.
+ * - `tag(neighborClass, neighborAs, { site, trusted })`: a rule for an import policy. It removes your communities a neighbor set, then adds where the route was learned. A `trusted` neighbor keeps its requests: do not announce, prepend, blackhole. `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(neighborClass, prefixSet)`: a rule for the import policy of a neighbor trusted with blackholes, before anything that rejects long prefixes. It takes a route the neighbor asked to blackhole, but only inside `prefixSet`, its own space, and drops traffic to it here.
+ * - `blackhole(prefixSets)`: rules for the import policy of a neighbor you trust with blackholes, before anything that rejects long prefixes. They take a route the neighbor asked to blackhole, but only inside `prefixSets`, its own space, and drop traffic to it here. One rule per set, so one call covers both families.
  * - `catalogue`: every community, for `communities` in `defineNetwork`.
  */
 export function communityScheme<const Class extends string>(scheme: CommunityScheme<Class>) {
@@ -269,17 +267,12 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
         (fn): fn is number => fn !== undefined
     );
 
-    // Each request's function numbers, and who may make it.
-    const requests = [
-        { functions: [scheme.do_not_announce?.function], trusted: scheme.do_not_announce?.trusted },
-        { functions: PREPENDS.map(([name]) => scheme.prepend?.[name]), trusted: scheme.prepend?.trusted },
-        { functions: [scheme.blackhole?.function], trusted: scheme.blackhole?.trusted },
-    ].map(({ functions, trusted }) => ({ functions: functions.filter((fn): fn is number => fn !== undefined), trusted: trusted ?? [] }));
-
-    const tag = (neighborClass: Class, neighborAs: number, options: { site?: number } = {}): PolicyRule<never, never> => {
-        const { site } = options;
-        const untrusted = requests.filter((request) => !request.trusted.includes(neighborClass)).flatMap((request) => request.functions);
-        const trustedForAny = requests.some((request) => request.functions.length && request.trusted.includes(neighborClass));
+    const tag = (
+        neighborClass: Class,
+        neighborAs: number,
+        options: { site?: number; trusted?: boolean } = {}
+    ): PolicyRule<never, never> => {
+        const { site, trusted = false } = options;
         if (scheme.learned_at && site === undefined)
             throw new Error(`communityScheme: tag for AS${neighborAs} needs a site, for learned_at`);
 
@@ -287,8 +280,8 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
             description: `Learned from AS${neighborAs}`,
             set: {
                 remove_communities: ours.standard,
-                // A neighbor trusted with nothing loses every community of ours it set. One trusted with some requests keeps those, and loses the rest.
-                remove_large_communities: trustedForAny ? [...information, ...untrusted].map((fn) => community(fn, "*")) : ours.large,
+                // A trusted neighbor keeps its requests and loses only the "where it came from" tags, which are ours to set. Anyone else loses every community of ours.
+                remove_large_communities: trusted ? 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!)] : []),
@@ -298,74 +291,78 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
         };
     };
 
-    const blackhole = <S extends string>(neighborClass: Class, prefixSet: S): PolicyRule<never, S> => {
-        if (scheme.blackhole === undefined) throw new Error("communityScheme: blackhole needs a function number in the scheme");
-        if (!scheme.blackhole.trusted.includes(neighborClass))
-            throw new Error(`communityScheme: ${neighborClass} is not trusted to ask for a blackhole`);
+    const blackhole = <S extends string>(prefixSets: readonly S[]): PolicyRule<never, S>[] => {
+        const fn = scheme.blackhole?.function;
+        if (fn === undefined) throw new Error("communityScheme: blackhole needs a function number in the scheme");
 
-        return {
+        return prefixSets.map((prefixSet) => ({
             description: "Blackhole, asked by the neighbor",
-            match: { large_community: community(scheme.blackhole.function, 0), prefix_set: prefixSet },
+            match: { large_community: community(fn, 0), prefix_set: prefixSet },
             set: { blackhole: true },
             action: "accept",
-        };
+        }));
     };
 
-    const actions = (neighborAs: number, options: { blackhole?: string } = {}): PolicyRule<never, never>[] => [
-        ...(scheme.blackhole !== undefined && !options.blackhole
-            ? [
-                  {
-                      description: "Blackholed here, never announced",
-                      match: { large_community: community(scheme.blackhole.function, 0) },
-                      action: "reject" as const,
-                  },
-              ]
-            : []),
-        ...(scheme.do_not_announce !== undefined
-            ? [
-                  {
-                      description: "Asked not to be announced anywhere",
-                      match: { large_community: community(scheme.do_not_announce.function, 0) },
-                      action: "reject" as const,
-                  },
-                  {
-                      description: `Asked not to be announced to AS${neighborAs}`,
-                      match: { large_community: community(scheme.do_not_announce.function, neighborAs) },
-                      action: "reject" as const,
-                  },
-              ]
-            : []),
-        ...(scheme.blackhole !== undefined && options.blackhole
-            ? [
-                  {
-                      description: `Blackhole passed on to AS${neighborAs}`,
-                      match: { large_community: community(scheme.blackhole.function, 0) },
-                      set: {
-                          remove_communities: ours.standard,
-                          remove_large_communities: ours.large,
-                          add_communities: [options.blackhole],
+    const actions = (neighborAs: number): PolicyRule<never, never>[] => {
+        // The upstream's own blackhole community, when it takes blackholes from us.
+        const passOn = scheme.blackhole?.upstreams?.[neighborAs];
+
+        return [
+            ...(scheme.blackhole !== undefined && !passOn
+                ? [
+                      {
+                          description: "Blackholed here, never announced",
+                          match: { large_community: community(scheme.blackhole.function, 0) },
+                          action: "reject" as const,
                       },
-                      action: "accept" as const,
-                  },
-              ]
-            : []),
-        ...PREPENDS.flatMap(([name, times]) => {
-            const fn = scheme.prepend?.[name];
-            if (fn === undefined) return [];
-
-            return [
-                {
-                    description: `Asked to prepend ${name.replace("_", " ")} to AS${neighborAs}`,
-                    match: { large_community: community(fn, neighborAs) },
-                    set: { prepend: times },
-                },
-            ];
-        }),
-        {
-            description: "Our communities stay inside our network",
-            set: { remove_communities: ours.standard, remove_large_communities: ours.large },
-        },
-    ];
+                  ]
+                : []),
+            ...(scheme.do_not_announce !== undefined
+                ? [
+                      {
+                          description: "Asked not to be announced anywhere",
+                          match: { large_community: community(scheme.do_not_announce, 0) },
+                          action: "reject" as const,
+                      },
+                      {
+                          description: `Asked not to be announced to AS${neighborAs}`,
+                          match: { large_community: community(scheme.do_not_announce, neighborAs) },
+                          action: "reject" as const,
+                      },
+                  ]
+                : []),
+            ...(scheme.blackhole !== undefined && passOn
+                ? [
+                      {
+                          description: `Blackhole passed on to AS${neighborAs}`,
+                          match: { large_community: community(scheme.blackhole.function, 0) },
+                          set: {
+                              remove_communities: ours.standard,
+                              remove_large_communities: ours.large,
+                              add_communities: [passOn],
+                          },
+                          action: "accept" as const,
+                      },
+                  ]
+                : []),
+            ...PREPENDS.flatMap(([name, times]) => {
+                const fn = scheme.prepend?.[name];
+                if (fn === undefined) return [];
+
+                return [
+                    {
+                        description: `Asked to prepend ${name.replace("_", " ")} to AS${neighborAs}`,
+                        match: { large_community: community(fn, neighborAs) },
+                        set: { prepend: times },
+                    },
+                ];
+            }),
+            {
+                description: "Our communities stay inside our network",
+                set: { remove_communities: ours.standard, remove_large_communities: ours.large },
+            },
+        ];
+    };
 
     const catalogue: Community[] = [
         ...Object.entries<number>(scheme.learned_from?.classes ?? {}).map(([name, value]) => ({
@@ -386,8 +383,8 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
             : []),
         ...(scheme.do_not_announce !== undefined
             ? [
-                  { community: community(scheme.do_not_announce.function, 0), description: "Do not announce to anyone" },
-                  { community: community(scheme.do_not_announce.function, "nnn"), description: "Do not announce to AS$0" },
+                  { community: community(scheme.do_not_announce, 0), description: "Do not announce to anyone" },
+                  { community: community(scheme.do_not_announce, "nnn"), description: "Do not announce to AS$0" },
               ]
             : []),
         ...PREPENDS.flatMap(([name]) => {
@@ -395,7 +392,14 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
             return fn === undefined ? [] : [{ community: community(fn, "nnn"), description: `Prepend ${name.replace("_", " ")} to AS$0` }];
         }),
         ...(scheme.blackhole !== undefined
-            ? [{ community: community(scheme.blackhole.function, 0), description: `Blackhole: dropped in AS${asn}, not announced further` }]
+            ? [
+                  {
+                      community: community(scheme.blackhole.function, 0),
+                      description: Object.keys(scheme.blackhole.upstreams ?? {}).length
+                          ? `Blackhole: dropped in AS${asn} and by its upstreams that take it`
+                          : `Blackhole: dropped in AS${asn}, not announced further`,
+                  },
+              ]
             : []),
     ];