@takodotid/circuit 0.40.0 → 0.41.0

package/src/helpers/bgp.ts

@@ -32,8 +32,8 @@ export type LearnOptions<P extends string> = {
     sources?: readonly IP[];
     /** Preference for the routes learned. Higher wins. */
     local_pref?: number;
-    /** Where the route came from: a community to add, or a rule, such as `communityScheme(...).tag(...)`. */
-    tag?: StandardCommunity | LargeCommunity | PolicyRule<never, never>;
+    /** Where the route came from: `{ standard: "64500:100" }` or `{ large: "64500:1:1" }` adds that community, and a rule, such as `communityScheme(...).tag(...)`, is used as it is. */
+    tag?: { standard: StandardCommunity } | { large: LargeCommunity } | PolicyRule<never, never>;
 };
 
 /** What `Bgp.defaultOnly` sets on the default routes it takes. */
@@ -44,6 +44,14 @@ export type DefaultOnlyOptions = {
     description?: string;
     /** The source address for the default of its family, one per family. */
     sources?: readonly IP[];
+    /** End with `{ description: "Nothing else", action: "reject" }`, so the policy takes the default route only. Off by default: any other route goes on to the rules after these. */
+    reject?: boolean;
+};
+
+/** What `Bgp.announce` writes after the accepts. */
+export type AnnounceOptions = {
+    /** End with `{ description: "Nothing else", action: "reject" }`, so nothing else leaves. On by default: it stops a route leak when the reject is forgotten. Turn it off for an export that adds rules after these. */
+    reject?: boolean;
 };
 
 /** Kinds of neighbor and the number each is tagged with, such as `{ transit: 1, customer: 3 }`. */
@@ -126,22 +134,42 @@ export class Bgp {
         ];
     }
 
-    /** An export policy that announces each prefix, at exactly its length, then rejects everything else. The last rule is the unconditional reject `Checks.exportsEndInReject` looks for. */
-    static announce(prefixes: readonly Announced[]): PolicyRule<never, never>[] {
+    /**
+     * An export that announces each prefix, at exactly its length. It returns, in order:
+     *
+     * 1. `{ description, match: { prefix }, action: "accept" }` for each prefix;
+     * 2. `{ description: "Nothing else", action: "reject" }`, the unconditional reject `Checks.exportsEndInReject` looks for.
+     *
+     * The reject is there by default, so a forgotten one can't leak routes. `{ reject: false }` leaves it out, for an export that adds rules after these and ends in a reject of its own.
+     */
+    static announce(prefixes: readonly Announced[], options: AnnounceOptions = {}): PolicyRule<never, never>[] {
         return [
             ...prefixes.map(({ prefix, description }) => ({
                 ...(description ? { description } : {}),
                 match: { prefix },
                 action: "accept" as const,
             })),
-            { description: "Nothing else", action: "reject" },
+            ...(options.reject === false ? [] : [Bgp.NOTHING_ELSE]),
         ];
     }
 
+    /** The reject that ends a policy: nothing else gets through. */
+    private static readonly NOTHING_ELSE: PolicyRule<never, never> = { description: "Nothing else", action: "reject" };
+
     /**
-     * An import policy that takes a neighbor's routes: `before` first, then the sanity rules, then each source address and the local preference, then the tag, then accept.
+     * An import policy that takes a neighbor's routes. It returns these rules, in order, each only when its option is given:
      *
-     * `sanity` names a policy holding `Bgp.sanity()` to call, so several imports share one; without it, the sanity rules are written here. `tag` is a community to add, or a rule such as `communityScheme(...).tag(...)`. Each of `sources` is the source address for routes of its own family.
+     * 1. the `before` rules, as written;
+     * 2. `{ call: sanity }`, or the rules of `Bgp.sanity()` written in when `sanity` is left out;
+     * 3. `{ set: { preferred_source: source } }` for each of `sources`, one per family;
+     * 4. `{ set: { local_pref } }`;
+     * 5. the tag: `{ description: "Tag 64500:1:1", set: { add_large_communities: ["64500:1:1"] } }` for `{ large: "64500:1:1" }`, `add_communities` for `{ standard }`, or the rule given;
+     * 6. `{ action: "accept" }`.
+     *
+     * So `Bgp.learn({ sanity: "SANITY", local_pref: 200, tag: { large: "64500:1:1" } })` is
+     * `[{ call: "SANITY" }, { set: { local_pref: 200 } }, { description: "Tag 64500:1:1", set: { add_large_communities: ["64500:1:1"] } }, { action: "accept" }]`.
+     *
+     * FortiOS refuses it: a route map stops at the first rule that matches, so it can't hold rules 3 to 5, which change a route and go on; and its sanity rules match RPKI, which FortiOS doesn't have. `validate` names each such rule. On FortiOS, write the import by hand with what rules 3 to 5 set in the rule that accepts.
      */
     static learn<const P extends string = never>(options: LearnOptions<P> = {}): PolicyRule<P, never>[] {
         const { tag } = options;
@@ -151,16 +179,22 @@ export class Bgp {
             ...(options.sanity ? [{ call: options.sanity }] : Bgp.sanity()),
             ...(options.sources ?? []).map((source) => ({ set: { preferred_source: source } })),
             ...(options.local_pref !== undefined ? [{ set: { local_pref: options.local_pref } }] : []),
-            ...(tag === undefined ? [] : [typeof tag === "object" ? tag : Bgp.adding(tag)]),
+            ...(tag === undefined ? [] : ["standard" in tag ? Bgp.adding(tag.standard) : "large" in tag ? Bgp.adding(tag.large) : tag]),
             { action: "accept" },
         ];
     }
 
     /**
-     * Import rules that take the default route, `0.0.0.0/0` and `::/0`, from a transit. Any other route reaches the next rule, or is rejected when there is none. Each of `sources` is the source address for the default of its own family.
+     * Import rules that take the default route from a transit. They are, in order:
+     *
+     * 1. `{ description, match: { prefix: "0.0.0.0/0" }, set: { local_pref, preferred_source }, action: "accept" }`;
+     * 2. the same for `::/0`;
+     * 3. with `{ reject: true }` only, `{ description: "Nothing else", action: "reject" }`.
+     *
+     * Without `reject`, any other route goes on to the rules after these, so `[...Bgp.defaultOnly(), ...Bgp.learn()]` takes both. Each of `sources` is the source address for the default of its own family; `set` holds only what is given.
      */
     static defaultOnly(options: DefaultOnlyOptions = {}): PolicyRule<never, never>[] {
-        return Bgp.DEFAULTS.map(({ family, prefix }) => {
+        const defaults = Bgp.DEFAULTS.map(({ family, prefix }) => {
             const source = options.sources?.find((address) => Address.family(address) === family);
             const set = {
                 ...(options.local_pref !== undefined ? { local_pref: options.local_pref } : {}),
@@ -174,6 +208,8 @@ export class Bgp {
                 action: "accept" as const,
             };
         });
+
+        return options.reject ? [...defaults, Bgp.NOTHING_ELSE] : defaults;
     }
 
     /** A rule adding one community, standard or large. */
@@ -211,8 +247,12 @@ export class Bgp {
     /**
      * 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, 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.
+     * - `tag(neighborClass, neighborAs, { site, trusted })`: one rule for an import policy, `{ description: "Learned from AS<n>", set }`. Its `set` removes your standard communities and your large ones (a `trusted` neighbor loses only the "where it came from" functions, so it keeps its requests: do not announce, prepend, blackhole), then adds `learned_from`, `learned_at` and `learned_from_as` where the scheme has them. `site` is needed when the scheme has `learned_at`.
+     * - `actions(neighborAs)`: the rules for an export policy toward one neighbor, before the rules that accept. They are `[...blackholeExport(n), ...rejectDoNotAnnounce(n), ...prepends(n), stripOurs()]`; toward a neighbor that takes blackholes (`blackhole.upstreams`), `rejectDoNotAnnounce(n)` comes first, so a route asked not to go there is never passed on as a blackhole.
+     * - `blackholeExport(neighborAs)`: a blackholed route goes no further, `Blackholed here, never announced`, unless `blackhole.upstreams` names the neighbor's own blackhole community: then it is passed on with it, so the neighbor drops the traffic too. Nothing without `blackhole`.
+     * - `rejectDoNotAnnounce(neighborAs)`: rejects a route asked not to be announced anywhere, then one asked not to be announced to this neighbor. Nothing without `do_not_announce`.
+     * - `prepends(neighborAs)`: prepends once, twice or three times toward this neighbor, where a route asks. Nothing without `prepend`.
+     * - `stripOurs()`: one rule removing every community of yours, `Our communities stay inside our network`.
      * - `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`.
      * - `community(fn, parameter)`: one community of yours, for a rule of your own.
@@ -291,67 +331,66 @@ export class Bgp {
             }));
         };
 
-        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];
+        /** The neighbor's own blackhole community, when it takes blackholes from us. */
+        const passOnTo = (neighborAs: number) => scheme.blackhole?.upstreams?.[neighborAs];
+
+        const blackholeExport = (neighborAs: number): PolicyRule<never, never>[] => {
+            if (scheme.blackhole === undefined) return [];
+
+            const passOn = passOnTo(neighborAs);
+            const match = { large_community: community(scheme.blackhole.function, 0) };
+
+            return passOn
+                ? [
+                      {
+                          description: `Blackhole passed on to AS${neighborAs}`,
+                          match,
+                          set: { remove_communities: ours.standard, remove_large_communities: ours.large, add_communities: [passOn] },
+                          action: "accept",
+                      },
+                  ]
+                : [{ description: "Blackholed here, never announced", match, action: "reject" }];
+        };
+
+        const rejectDoNotAnnounce = (neighborAs: number): PolicyRule<never, never>[] => {
+            const fn = scheme.do_not_announce;
+            if (fn === undefined) return [];
 
             return [
-                ...(scheme.blackhole !== undefined && !passOn
-                    ? [
-                          {
-                              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, 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,
-                          },
-                      ]
-                    : []),
-                ...Bgp.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 anywhere", match: { large_community: community(fn, 0) }, action: "reject" },
                 {
-                    description: "Our communities stay inside our network",
-                    set: { remove_communities: ours.standard, remove_large_communities: ours.large },
+                    description: `Asked not to be announced to AS${neighborAs}`,
+                    match: { large_community: community(fn, neighborAs) },
+                    action: "reject",
                 },
             ];
         };
 
+        const prepends = (neighborAs: number): PolicyRule<never, never>[] =>
+            Bgp.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 },
+                    },
+                ];
+            });
+
+        const stripOurs = (): PolicyRule<never, never> => ({
+            description: "Our communities stay inside our network",
+            set: { remove_communities: ours.standard, remove_large_communities: ours.large },
+        });
+
+        // A route asked not to be announced to a neighbor is never passed on to it as a blackhole either; where nothing is passed on, both only reject.
+        const actions = (neighborAs: number): PolicyRule<never, never>[] =>
+            passOnTo(neighborAs)
+                ? [...rejectDoNotAnnounce(neighborAs), ...blackholeExport(neighborAs), ...prepends(neighborAs), stripOurs()]
+                : [...blackholeExport(neighborAs), ...rejectDoNotAnnounce(neighborAs), ...prepends(neighborAs), stripOurs()];
+
         const catalogue: Community[] = [
             ...Object.entries<number>(scheme.learned_from?.classes ?? {}).map(([name, value]) => ({
                 community: written(scheme.learned_from!.function, value),
@@ -393,7 +432,18 @@ export class Bgp {
                 : []),
         ];
 
-        return { community, learned_from: learnedFrom, tag, actions, blackhole, catalogue };
+        return {
+            community,
+            learned_from: learnedFrom,
+            tag,
+            actions,
+            blackholeExport,
+            rejectDoNotAnnounce,
+            prepends,
+            stripOurs,
+            blackhole,
+            catalogue,
+        };
     }
 
     /** A word with its article: "a customer", "an upstream". */

package/src/helpers/checks.ts

@@ -41,6 +41,29 @@ export class Checks {
         return findings;
     };
 
+    /**
+     * Every BGP import ends in a rule that decides for every route, an accept or a reject without a match, so what the import takes is written in it and not left to the platform's default.
+     */
+    static readonly importsEndInAcceptOrReject: Check = (devices) => {
+        const findings: Finding[] = [];
+
+        for (const device of devices) {
+            for (const neighbor of Bgp.neighborPolicies(device)) {
+                const last = neighbor.import ? device.policies?.[neighbor.import]?.at(-1) : undefined;
+
+                if (neighbor.import && (!last?.action || last.match)) {
+                    findings.push({
+                        level: "error",
+                        device: device.name,
+                        message: `${neighbor.name}: import ${neighbor.import} does not end in an unconditional accept or reject`,
+                    });
+                }
+            }
+        }
+
+        return findings;
+    };
+
     /** A GRE or VXLAN tunnel's local address is outside what the neighbors over it are offered, or their replies route back into the tunnel. */
     static readonly tunnelsOutsideOffered: Check = (devices) => {
         const findings: Finding[] = [];

package/src/helpers/index.ts

@@ -1,7 +1,7 @@
 // Building blocks most networks write the same way: address lists, cables written once for both ends, edge filters, a BGP import sanity policy, an exchange's member ports and route servers, upstreams written once, checks, and helpers for checks of your own. Each returns plain config to place where it belongs, so nothing here applies itself.
 
 export { Bgp } from "./bgp";
-export type { Announced, CommunityScheme, DefaultOnlyOptions, LearnOptions, SanityLengths } from "./bgp";
+export type { AnnounceOptions, Announced, CommunityScheme, DefaultOnlyOptions, LearnOptions, SanityLengths } from "./bgp";
 export { Cables } from "./cables";
 export type { FarEnd } from "./cables";
 export { Checks } from "./checks";
@@ -11,6 +11,6 @@ export type { ExchangeMember, InternetExchange } from "./exchange";
 export { Filters } from "./filters";
 export { RouteServerConfig } from "./route-server";
 export { Upstreams } from "./upstreams";
-export type { Upstream, UpstreamCatalog, UpstreamPolicies } from "./upstreams";
+export type { NamedVlan, Upstream, UpstreamCatalog, UpstreamOptions, UpstreamPolicy } from "./upstreams";
 export type { RouteServer } from "./route-server";
 export type { AntiAmplificationOptions } from "./filters";