@takodotid/circuit 0.42.1 → 0.43.0

package/dist/chunks/{index-20kcjxjg.js → index-3b343xva.js}

@@ -11,6 +11,9 @@ class Utils2 {
     }
     return result;
   }
+  static otherTable(table) {
+    return table === "main" ? undefined : table;
+  }
   static timeZoneOffset(zone) {
     const name = new Intl.DateTimeFormat("en-US", {
       timeZone: zone,

package/dist/cli/index.js

@@ -2,7 +2,7 @@
 import {
   Utils2,
   Secrets2
-} from "../chunks/index-20kcjxjg.js";
+} from "../chunks/index-3b343xva.js";
 import {
   Topology,
   AddressSpace,
@@ -549,7 +549,7 @@ class Derive {
     for (const route of routing?.static ?? []) {
       if (route.bfd && !has("static-route-bfd"))
         found.push(`routing.static ${route.prefix} bfd, BFD on a static route is ${unproved}`);
-      if (route.table && !has("routing-tables"))
+      if (Utils2.otherTable(route.table) && !has("routing-tables"))
         found.push(`routing.static ${route.prefix} table, a routing table beside the main one is ${unproved}`);
     }
     if (!has("routing-tables")) {
@@ -560,11 +560,11 @@ class Derive {
     }
     const bgp = routing?.bgp;
     for (const [name, group] of Object.entries(bgp?.groups ?? {})) {
-      if (group.table && !has("routing-tables"))
+      if (Utils2.otherTable(group.table) && !has("routing-tables"))
         found.push(`routing.bgp.groups.${name}.table, a routing table beside the main one is ${unproved}`);
     }
     for (const [name, neighbor] of Object.entries(bgp?.neighbors ?? {})) {
-      if (neighbor.table && !has("routing-tables"))
+      if (Utils2.otherTable(neighbor.table) && !has("routing-tables"))
         found.push(`routing.bgp.neighbors.${name}.table, a routing table beside the main one is ${unproved}`);
       const group = neighbor.group ? bgp?.groups?.[neighbor.group] : undefined;
       const bfd = neighbor.bfd ?? group?.bfd;
@@ -8343,7 +8343,7 @@ class RouterOsRender {
         distance: route.distance,
         "dst-address": route.prefix,
         gateway,
-        "routing-table": route.vrf ?? route.table
+        "routing-table": route.vrf ?? Utils2.otherTable(route.table)
       });
     }
   }
@@ -8464,7 +8464,7 @@ class RouterOsRender {
         "output.network": originates ? RouterOsRender.NETWORKS[family] : undefined,
         "remote.address": `${neighbor.address}/${addressFamily === "ipv4" ? 32 : 128}`,
         "remote.as": settings.remote_as,
-        "routing-table": settings.table,
+        "routing-table": Utils2.otherTable(settings.table),
         "tcp-md5-key": settings.password && Secrets2.marker(settings.password),
         "use-bfd": settings.bfd ? "yes" : undefined
       });
@@ -8732,19 +8732,22 @@ class RouterOs extends Platform {
     const findings = [];
     for (const [name, neighbor] of Object.entries(bgp?.neighbors ?? {})) {
       const group = neighbor.group ? bgp?.groups?.[neighbor.group] : undefined;
-      const table = neighbor.table ?? group?.table;
+      const table = Utils2.otherTable(neighbor.table ?? group?.table);
       if (!table)
         continue;
       const families = neighbor.families ?? group?.families ?? [Address2.family(neighbor.address)];
       const networks = (bgp?.networks ?? []).filter((prefix) => families.includes(Address2.family(Address2.host(prefix))));
       const inTable = (prefix) => statics.some((route) => route.table === table && Address2.canonical(route.prefix) === Address2.canonical(prefix));
-      const missing = networks.filter((prefix) => !inTable(prefix));
+      const exportPolicy = neighbor.export ?? group?.export;
+      const accepted = (exportPolicy ? device.policies?.[exportPolicy] ?? [] : []).filter((rule) => rule.action === "accept" && rule.match?.prefix).map((rule) => Address2.canonical(rule.match.prefix));
+      const announced = accepted.length ? networks.filter((prefix) => accepted.includes(Address2.canonical(prefix))) : networks;
+      const missing = announced.filter((prefix) => !inTable(prefix));
       if (!missing.length)
         continue;
       const where = `routing.bgp.neighbors.${name}`;
       const route = (prefix) => `{ prefix: "${prefix}", blackhole: true, table: "${table}" }`;
       const fix = `On RouterOS a session announces from its own table, ${table}`;
-      if (missing.length === networks.length) {
+      if (missing.length === announced.length) {
         findings.push({
           level: "error",
           device: device.name,
@@ -11555,8 +11558,8 @@ class Validator {
         report(`static route ${route.prefix} has bfd without via, the address BFD watches`);
       names.expectInterface(`static route ${route.prefix} interface`, route.interface);
       names.expect(`static route ${route.prefix} VRF`, route.vrf, route.vrf !== undefined && route.vrf in (device.vrfs ?? {}));
-      names.expect(`static route ${route.prefix} table`, route.table, route.table !== undefined && route.table in (routing?.tables ?? {}));
-      if (route.vrf && route.table)
+      names.expect(`static route ${route.prefix} table`, route.table, route.table !== undefined && (route.table === "main" || (route.table in (routing?.tables ?? {}))));
+      if (route.vrf && Utils2.otherTable(route.table))
         report(`static route ${route.prefix} has both vrf and table; a route is in one of them`);
     }
     Validator.checkTables(device, names, report, cidr);
@@ -11564,7 +11567,7 @@ class Validator {
     const isPolicy = (policy) => policy !== undefined && (policy in policies);
     for (const prefix of bgp?.networks ?? [])
       cidr("BGP network", prefix);
-    const isTable = (table) => table !== undefined && (table in (routing?.tables ?? {}));
+    const isTable = (table) => table !== undefined && (table === "main" || (table in (routing?.tables ?? {})));
     for (const [name, group] of Object.entries(bgp?.groups ?? {})) {
       for (const policy of [group.import, group.export]) {
         names.expect(`BGP group ${name} policy`, policy, isPolicy(policy));
@@ -11597,11 +11600,13 @@ class Validator {
     const tables = routing?.tables ?? {};
     const bgp = routing?.bgp;
     const installed = new Set;
-    for (const route of routing?.static ?? [])
-      if (route.table)
-        installed.add(route.table);
+    for (const route of routing?.static ?? []) {
+      const table = Utils2.otherTable(route.table);
+      if (table)
+        installed.add(table);
+    }
     for (const neighbor of Object.values(bgp?.neighbors ?? {})) {
-      const table = neighbor.table ?? (neighbor.group ? bgp?.groups?.[neighbor.group]?.table : undefined);
+      const table = Utils2.otherTable(neighbor.table ?? (neighbor.group ? bgp?.groups?.[neighbor.group]?.table : undefined));
       if (table)
         installed.add(table);
     }

package/dist/helpers/index.js

@@ -147,22 +147,31 @@ class Bgp {
         action: "accept"
       }));
     };
-    const passOnTo = (neighborAs) => scheme.blackhole?.upstreams?.[neighborAs];
-    const blackholeExport = (neighborAs) => {
+    const asnOf = (neighbor) => typeof neighbor === "number" ? neighbor : neighbor.asn;
+    const passOnTo = (neighbor) => typeof neighbor === "number" ? undefined : neighbor.communities?.blackhole;
+    const blackholeExport = (neighbor) => {
       if (scheme.blackhole === undefined)
         return [];
-      const passOn = passOnTo(neighborAs);
+      const passOn = passOnTo(neighbor);
       const match = { large_community: community(scheme.blackhole.function, 0) };
-      return passOn ? [
+      if (!passOn)
+        return [{ description: "Blackholed here, never announced", match, action: "reject" }];
+      const large = passOn.split(":").length === 3;
+      return [
         {
-          description: `Blackhole passed on to AS${neighborAs}`,
+          description: `Blackhole passed on to AS${asnOf(neighbor)}`,
           match,
-          set: { remove_communities: ours.standard, remove_large_communities: ours.large, add_communities: [passOn] },
+          set: {
+            remove_communities: ours.standard,
+            remove_large_communities: ours.large,
+            ...large ? { add_large_communities: [passOn] } : { add_communities: [passOn] }
+          },
           action: "accept"
         }
-      ] : [{ description: "Blackholed here, never announced", match, action: "reject" }];
+      ];
     };
-    const rejectDoNotAnnounce = (neighborAs) => {
+    const rejectDoNotAnnounce = (neighbor) => {
+      const neighborAs = asnOf(neighbor);
       const fn = scheme.do_not_announce;
       if (fn === undefined)
         return [];
@@ -175,7 +184,8 @@ class Bgp {
         }
       ];
     };
-    const prepends = (neighborAs) => Bgp.PREPENDS.flatMap(([name, times]) => {
+    const prepends = (neighbor) => Bgp.PREPENDS.flatMap(([name, times]) => {
+      const neighborAs = asnOf(neighbor);
       const fn = scheme.prepend?.[name];
       if (fn === undefined)
         return [];
@@ -191,7 +201,7 @@ class Bgp {
       description: "Our communities stay inside our network",
       set: { remove_communities: ours.standard, remove_large_communities: ours.large }
     });
-    const actions = (neighborAs) => passOnTo(neighborAs) ? [...rejectDoNotAnnounce(neighborAs), ...blackholeExport(neighborAs), ...prepends(neighborAs), stripOurs()] : [...blackholeExport(neighborAs), ...rejectDoNotAnnounce(neighborAs), ...prepends(neighborAs), stripOurs()];
+    const actions = (neighbor) => passOnTo(neighbor) ? [...rejectDoNotAnnounce(neighbor), ...blackholeExport(neighbor), ...prepends(neighbor), stripOurs()] : [...blackholeExport(neighbor), ...rejectDoNotAnnounce(neighbor), ...prepends(neighbor), stripOurs()];
     const catalogue = [
       ...Object.entries(scheme.learned_from?.classes ?? {}).map(([name, value]) => ({
         community: written(scheme.learned_from.function, value),
@@ -216,7 +226,7 @@ class Bgp {
       ...scheme.blackhole !== undefined ? [
         {
           community: written(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`
+          description: `Blackhole: dropped in AS${asn}, and by the upstreams that take it`
         }
       ] : []
     ];
@@ -691,6 +701,28 @@ class Filters {
 }
 // src/helpers/upstreams.ts
 class Upstreams {
+  static catalog(catalog) {
+    return catalog;
+  }
+  static doNotAnnounceTo(upstream, asns, description) {
+    if (!asns.length)
+      return [];
+    const community = upstream.communities?.do_not_announce_to;
+    if (!community)
+      throw new Error(`Upstreams: ${upstream.name ?? `AS${upstream.asn}`} has no communities.do_not_announce_to, so it can't be asked to keep our routes from AS${asns.join(", AS")}`);
+    const communities = asns.map(community);
+    const large = communities.filter((value) => value.split(":").length === 3);
+    const standard = communities.filter((value) => value.split(":").length === 2);
+    return [
+      {
+        description,
+        set: {
+          ...standard.length ? { add_communities: standard } : {},
+          ...large.length ? { add_large_communities: large } : {}
+        }
+      }
+    ];
+  }
   static define(catalog, options = {}) {
     const all = Object.entries(catalog);
     const nameOf = (key, upstream) => upstream.name ?? key;

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   Utils2,
   Secrets2
-} from "./chunks/index-20kcjxjg.js";
+} from "./chunks/index-3b343xva.js";
 import {
   Address2
 } from "./chunks/index-n7w3tg5y.js";

package/dist/types/core/utils.d.ts

@@ -2,6 +2,8 @@ type Merged<T extends readonly object[]> = T extends readonly [infer Head, ...in
 export declare class Utils {
     /** Combine records into one, such as a device's own interfaces and those a module derives for it. Unlike spreading them, a name two of them hold is an error rather than one silently replacing the other. */
     static merge<const T extends readonly Record<string, unknown>[]>(...records: T): Merged<T>;
+    /** The table a route or a BGP session is in, beside the main one: `undefined` for the main table, written `main` or left out. */
+    static otherTable(table: string | undefined): string | undefined;
     /** Minutes east of UTC an IANA zone is at now, for platforms that take an offset rather than a zone. */
     static timeZoneOffset(zone: string): number;
 }

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

@@ -82,15 +82,24 @@ export type CommunityScheme<Asn extends number = number, LearnedFrom extends num
         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.
+     * A neighbor asks: drop all traffic to this route, `asn:function:0`, usually one address under attack. Your router drops it. An upstream whose own blackhole community you know (`communities.blackhole` on the neighbor you pass to `actions`) receives the route with it and drops the traffic too; any other never receives the route.
      */
     blackhole?: {
         function: number;
-        upstreams?: Readonly<Record<number, StandardCommunity>>;
     };
 };
+/** The communities another network offers us, as its NOC gives them: what it does with a route we send it. */
+export type NeighborCommunities = {
+    /** It drops traffic to a route we send it with this community. */
+    blackhole?: StandardCommunity | LargeCommunity;
+    /** It does not pass a route we send it with this community to the AS given, such as an exchange's route servers' `rs-asn:0:peer-asn`. */
+    do_not_announce_to?: (asn: number) => StandardCommunity | LargeCommunity;
+};
+/** A neighbor an export goes to: its AS, or its AS and the communities it offers. */
+export type ExportNeighbor = number | {
+    asn: number;
+    communities?: NeighborCommunities;
+};
 /** The class names a scheme declares, or any name when it declares none. */
 type ClassName<Classes extends CommunityClasses> = {} extends Classes ? string : Extract<keyof Classes, string>;
 /** BGP policy: an import sanity policy, the shapes most imports and exports take, a community scheme, and helpers that read a device's BGP neighbors. */
@@ -153,10 +162,12 @@ export declare 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 })`: 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`.
+     * Each export helper takes the neighbor: its AS, or `{ asn, communities }` with the communities it offers, such as an `Upstreams.catalog` entry.
+     *
+     * - `actions(neighbor)`: 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 (`communities.blackhole`), `rejectDoNotAnnounce(n)` comes first, so a route asked not to go there is never passed on as a blackhole.
+     * - `blackholeExport(neighbor)`: a blackholed route goes no further, `Blackholed here, never announced`, unless the neighbor has `communities.blackhole`: then it is passed on with it, so the neighbor drops the traffic too. Nothing without `blackhole` in the scheme.
+     * - `rejectDoNotAnnounce(neighbor)`: 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(neighbor)`: 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`.
@@ -170,10 +181,10 @@ export declare class Bgp {
             site?: number;
             trusted?: boolean;
         }) => PolicyRule<never, never>;
-        actions: (neighborAs: number) => PolicyRule<never, never>[];
-        blackholeExport: (neighborAs: number) => PolicyRule<never, never>[];
-        rejectDoNotAnnounce: (neighborAs: number) => PolicyRule<never, never>[];
-        prepends: (neighborAs: number) => PolicyRule<never, never>[];
+        actions: (neighbor: ExportNeighbor) => PolicyRule<never, never>[];
+        blackholeExport: (neighbor: ExportNeighbor) => PolicyRule<never, never>[];
+        rejectDoNotAnnounce: (neighbor: ExportNeighbor) => PolicyRule<never, never>[];
+        prepends: (neighbor: ExportNeighbor) => PolicyRule<never, never>[];
         stripOurs: () => PolicyRule<never, never>;
         blackhole: <S extends string>(prefixSets: readonly S[]) => PolicyRule<never, S>[];
         catalogue: Community[];

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

@@ -1,5 +1,5 @@
 export { Bgp } from "./bgp.js";
-export type { AnnounceOptions, Announced, CommunityScheme, DefaultOnlyOptions, LearnOptions, SanityLengths } from "./bgp.js";
+export type { AnnounceOptions, Announced, CommunityScheme, DefaultOnlyOptions, ExportNeighbor, LearnOptions, NeighborCommunities, SanityLengths, } from "./bgp.js";
 export { Cables } from "./cables.js";
 export type { FarEnd } from "./cables.js";
 export { Checks } from "./checks.js";

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

@@ -1,4 +1,5 @@
 import type { Exchange as ExchangeLan, Family, FilterRule, Gre, InterfaceAddress, IP, Neighbor, NeighborSettings, PolicyRule, Port, Secret, Vlan, VlanInterface } from "../schema/index.js";
+import type { NeighborCommunities } from "./bgp.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. */
@@ -67,7 +68,7 @@ export type Upstream = {
         families?: readonly Family[];
         password?: Secret;
     };
-    /** The routing table its sessions install the routes they learn in, one of the router's `routing.tables`: a transit that carries only one block's traffic out. The main table when absent. On RouterOS the sessions also announce from that table, so what they announce needs a route there too. */
+    /** The routing table its sessions install the routes they learn in: `main`, or one of the router's `routing.tables`, for a transit that carries only one block's traffic out. The main table when absent; write `main` to say so. On RouterOS the sessions also announce from that table, so what they announce needs a route there too. */
     table?: string;
     /** The most prefixes a session may send, by its family: about twice what it sends. Over it, the session closes until it is cleared. */
     limits?: {
@@ -80,6 +81,8 @@ export type Upstream = {
     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;
+    /** The communities it offers, as its NOC gives them: its blackhole community, and how to keep a route from one AS. `communityScheme().actions(upstream)` passes blackholes on with it, and `Upstreams.doNotAnnounceTo` uses the other. */
+    communities?: NeighborCommunities;
 };
 /** Upstreams by key. */
 export type UpstreamCatalog = Readonly<Record<string, Upstream>>;
@@ -145,14 +148,22 @@ type GroupName<C> = Values<{
         group: infer N extends string;
     } ? N : never;
 }>;
-/** Each routing table name. */
-type TableName<C> = Values<{
+/** Each routing table name, other than main. */
+type TableName<C> = Exclude<Values<{
     [K in keyof C]: C[K] extends {
         table: infer N extends string;
     } ? N : never;
-}>;
+}>, "main">;
 /** A network's upstreams written once, and each device's part built from them. */
 export declare class Upstreams {
+    /**
+     * A catalog of upstreams, by key, written once and checked: a key the shape doesn't have is refused by its name. It gives the catalog back as written, so its keys and entries can be read, and is what `define` takes.
+     */
+    static catalog<const C extends UpstreamCatalog>(catalog: C & UpstreamCatalog): C;
+    /**
+     * Export rules asking an upstream not to pass our routes to these ASes, with its own `communities.do_not_announce_to`: one rule, `description`, adding one community per AS. Nothing for no AS. An upstream without `do_not_announce_to` is an error, since it can't be asked.
+     */
+    static doNotAnnounceTo(upstream: Upstream, asns: readonly number[], description: string): PolicyRule<never, never>[];
     /**
      * 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:
      *

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

@@ -15,8 +15,8 @@ export type StaticRoute<I extends string, F extends string, T extends string = n
     distance?: number;
     /** The VRF the route is in. The main table when absent. */
     vrf?: F;
-    /** The table the route is in, one of `routing.tables`. The main table when absent. A route has a `vrf` or a `table`, not both. */
-    table?: T;
+    /** The table the route is in: `main`, or one of `routing.tables`. The main table when absent; write `main` to say so. A route has a `vrf` or a `table`, not both. */
+    table?: T | "main";
     /** Why the route exists. */
     description?: string;
 };
@@ -54,8 +54,8 @@ export type NeighborSettings<P extends string, T extends string = never> = {
     passive?: boolean;
     /** Detect a dead link in under a second with BFD. */
     bfd?: boolean;
-    /** The table the routes learned are installed in, one of `routing.tables`. The main table when absent. On RouterOS the session also announces from that table, so each prefix of `networks` it announces needs a route in the table too, and a running session takes a new table only when it restarts. */
-    table?: T;
+    /** The table the routes learned are installed in: `main`, or one of `routing.tables`. The main table when absent; write `main` to say so. On RouterOS the session also announces from that table, so each prefix of `networks` it announces needs a route in the table too, and a running session takes a new table only when it restarts. */
+    table?: T | "main";
 };
 /** One BGP session. Settings it does not set come from its group. */
 export type Neighbor<P extends string, G extends string, T extends string = never> = NeighborSettings<P, T> & {

package/package.json

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

package/src/core/utils.ts

@@ -19,6 +19,11 @@ export class Utils {
         return result as Merged<T>;
     }
 
+    /** The table a route or a BGP session is in, beside the main one: `undefined` for the main table, written `main` or left out. */
+    static otherTable(table: string | undefined): string | undefined {
+        return table === "main" ? undefined : table;
+    }
+
     /** Minutes east of UTC an IANA zone is at now, for platforms that take an offset rather than a zone. */
     static timeZoneOffset(zone: string): number {
         const name = new Intl.DateTimeFormat("en-US", {

package/src/core/validator.ts

@@ -1,6 +1,7 @@
 // Rules every network has to satisfy, whatever its design. Types catch most of this at compile time; these run again at load, because config is data and may not come from TypeScript.
 
 import { X509Certificate } from "node:crypto";
+import { Utils } from "./utils";
 import { Platforms } from "../platforms";
 import { Catalog } from "../platforms/catalog";
 import type { Device, Switched } from "../schema";
@@ -297,9 +298,10 @@ export class Validator {
             names.expect(
                 `static route ${route.prefix} table`,
                 route.table,
-                route.table !== undefined && route.table in (routing?.tables ?? {})
+                route.table !== undefined && (route.table === "main" || route.table in (routing?.tables ?? {}))
             );
-            if (route.vrf && route.table) report(`static route ${route.prefix} has both vrf and table; a route is in one of them`);
+            if (route.vrf && Utils.otherTable(route.table))
+                report(`static route ${route.prefix} has both vrf and table; a route is in one of them`);
         }
 
         Validator.checkTables(device, names, report, cidr);
@@ -309,7 +311,7 @@ export class Validator {
 
         for (const prefix of bgp?.networks ?? []) cidr("BGP network", prefix);
 
-        const isTable = (table: string | undefined) => table !== undefined && table in (routing?.tables ?? {});
+        const isTable = (table: string | undefined) => table !== undefined && (table === "main" || table in (routing?.tables ?? {}));
 
         for (const [name, group] of Object.entries(bgp?.groups ?? {})) {
             for (const policy of [group.import, group.export]) {
@@ -351,9 +353,12 @@ export class Validator {
         const bgp = routing?.bgp;
 
         const installed = new Set<string>();
-        for (const route of routing?.static ?? []) if (route.table) installed.add(route.table);
+        for (const route of routing?.static ?? []) {
+            const table = Utils.otherTable(route.table);
+            if (table) installed.add(table);
+        }
         for (const neighbor of Object.values(bgp?.neighbors ?? {})) {
-            const table = neighbor.table ?? (neighbor.group ? bgp?.groups?.[neighbor.group]?.table : undefined);
+            const table = Utils.otherTable(neighbor.table ?? (neighbor.group ? bgp?.groups?.[neighbor.group]?.table : undefined));
             if (table) installed.add(table);
         }
 

package/src/helpers/bgp.ts

@@ -80,13 +80,22 @@ export type CommunityScheme<
     /** A neighbor asks: prepend toward an AS once, twice or three times, `asn:function:asn`. */
     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.
+     * A neighbor asks: drop all traffic to this route, `asn:function:0`, usually one address under attack. Your router drops it. An upstream whose own blackhole community you know (`communities.blackhole` on the neighbor you pass to `actions`) receives the route with it and drops the traffic too; any other never receives the route.
      */
-    blackhole?: { function: number; upstreams?: Readonly<Record<number, StandardCommunity>> };
+    blackhole?: { function: number };
+};
+
+/** The communities another network offers us, as its NOC gives them: what it does with a route we send it. */
+export type NeighborCommunities = {
+    /** It drops traffic to a route we send it with this community. */
+    blackhole?: StandardCommunity | LargeCommunity;
+    /** It does not pass a route we send it with this community to the AS given, such as an exchange's route servers' `rs-asn:0:peer-asn`. */
+    do_not_announce_to?: (asn: number) => StandardCommunity | LargeCommunity;
 };
 
+/** A neighbor an export goes to: its AS, or its AS and the communities it offers. */
+export type ExportNeighbor = number | { asn: number; communities?: NeighborCommunities };
+
 /** The class names a scheme declares, or any name when it declares none. */
 type ClassName<Classes extends CommunityClasses> = {} extends Classes ? string : Extract<keyof Classes, string>;
 
@@ -248,10 +257,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 })`: 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`.
+     * Each export helper takes the neighbor: its AS, or `{ asn, communities }` with the communities it offers, such as an `Upstreams.catalog` entry.
+     *
+     * - `actions(neighbor)`: 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 (`communities.blackhole`), `rejectDoNotAnnounce(n)` comes first, so a route asked not to go there is never passed on as a blackhole.
+     * - `blackholeExport(neighbor)`: a blackholed route goes no further, `Blackholed here, never announced`, unless the neighbor has `communities.blackhole`: then it is passed on with it, so the neighbor drops the traffic too. Nothing without `blackhole` in the scheme.
+     * - `rejectDoNotAnnounce(neighbor)`: 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(neighbor)`: 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`.
@@ -331,28 +342,38 @@ export class Bgp {
             }));
         };
 
+        /** The neighbor's AS. */
+        const asnOf = (neighbor: ExportNeighbor) => (typeof neighbor === "number" ? neighbor : neighbor.asn);
+
         /** The neighbor's own blackhole community, when it takes blackholes from us. */
-        const passOnTo = (neighborAs: number) => scheme.blackhole?.upstreams?.[neighborAs];
+        const passOnTo = (neighbor: ExportNeighbor) => (typeof neighbor === "number" ? undefined : neighbor.communities?.blackhole);
 
-        const blackholeExport = (neighborAs: number): PolicyRule<never, never>[] => {
+        const blackholeExport = (neighbor: ExportNeighbor): PolicyRule<never, never>[] => {
             if (scheme.blackhole === undefined) return [];
 
-            const passOn = passOnTo(neighborAs);
+            const passOn = passOnTo(neighbor);
             const match = { large_community: community(scheme.blackhole.function, 0) };
+            if (!passOn) return [{ description: "Blackholed here, never announced", match, action: "reject" }];
 
-            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 large = passOn.split(":").length === 3;
+            return [
+                {
+                    description: `Blackhole passed on to AS${asnOf(neighbor)}`,
+                    match,
+                    set: {
+                        remove_communities: ours.standard,
+                        remove_large_communities: ours.large,
+                        ...(large
+                            ? { add_large_communities: [passOn as LargeCommunity] }
+                            : { add_communities: [passOn as StandardCommunity] }),
+                    },
+                    action: "accept",
+                },
+            ];
         };
 
-        const rejectDoNotAnnounce = (neighborAs: number): PolicyRule<never, never>[] => {
+        const rejectDoNotAnnounce = (neighbor: ExportNeighbor): PolicyRule<never, never>[] => {
+            const neighborAs = asnOf(neighbor);
             const fn = scheme.do_not_announce;
             if (fn === undefined) return [];
 
@@ -366,8 +387,9 @@ export class Bgp {
             ];
         };
 
-        const prepends = (neighborAs: number): PolicyRule<never, never>[] =>
+        const prepends = (neighbor: ExportNeighbor): PolicyRule<never, never>[] =>
             Bgp.PREPENDS.flatMap(([name, times]) => {
+                const neighborAs = asnOf(neighbor);
                 const fn = scheme.prepend?.[name];
                 if (fn === undefined) return [];
 
@@ -386,10 +408,10 @@ export class Bgp {
         });
 
         // 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 actions = (neighbor: ExportNeighbor): PolicyRule<never, never>[] =>
+            passOnTo(neighbor)
+                ? [...rejectDoNotAnnounce(neighbor), ...blackholeExport(neighbor), ...prepends(neighbor), stripOurs()]
+                : [...blackholeExport(neighbor), ...rejectDoNotAnnounce(neighbor), ...prepends(neighbor), stripOurs()];
 
         const catalogue: Community[] = [
             ...Object.entries<number>(scheme.learned_from?.classes ?? {}).map(([name, value]) => ({
@@ -424,9 +446,7 @@ export class Bgp {
                 ? [
                       {
                           community: written(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`,
+                          description: `Blackhole: dropped in AS${asn}, and by the upstreams that take it`,
                       },
                   ]
                 : []),

package/src/helpers/index.ts

@@ -1,7 +1,16 @@
 // 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 { AnnounceOptions, Announced, CommunityScheme, DefaultOnlyOptions, LearnOptions, SanityLengths } from "./bgp";
+export type {
+    AnnounceOptions,
+    Announced,
+    CommunityScheme,
+    DefaultOnlyOptions,
+    ExportNeighbor,
+    LearnOptions,
+    NeighborCommunities,
+    SanityLengths,
+} from "./bgp";
 export { Cables } from "./cables";
 export type { FarEnd } from "./cables";
 export { Checks } from "./checks";

package/src/helpers/upstreams.ts

@@ -5,6 +5,8 @@ import type {
     FilterRule,
     Gre,
     InterfaceAddress,
+    StandardCommunity,
+    LargeCommunity,
     IP,
     Neighbor,
     NeighborSettings,
@@ -15,6 +17,7 @@ import type {
     Vlan,
     VlanInterface,
 } from "../schema";
+import type { NeighborCommunities } from "./bgp";
 
 /** A route policy an upstream's sessions use: its name on the device, and its rules, in order. */
 export type UpstreamPolicy = {
@@ -67,7 +70,7 @@ export type Upstream = {
     group?: string;
     /** The sessions are more than one hop away, from this address of ours. */
     multihop?: { local_address: IP; families?: readonly Family[]; password?: Secret };
-    /** The routing table its sessions install the routes they learn in, one of the router's `routing.tables`: a transit that carries only one block's traffic out. The main table when absent. On RouterOS the sessions also announce from that table, so what they announce needs a route there too. */
+    /** The routing table its sessions install the routes they learn in: `main`, or one of the router's `routing.tables`, for a transit that carries only one block's traffic out. The main table when absent; write `main` to say so. On RouterOS the sessions also announce from that table, so what they announce needs a route there too. */
     table?: string;
     /** The most prefixes a session may send, by its family: about twice what it sends. Over it, the session closes until it is cleared. */
     limits?: { ipv4?: number; ipv6?: number };
@@ -77,6 +80,8 @@ export type Upstream = {
     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;
+    /** The communities it offers, as its NOC gives them: its blackhole community, and how to keep a route from one AS. `communityScheme().actions(upstream)` passes blackholes on with it, and `Upstreams.doNotAnnounceTo` uses the other. */
+    communities?: NeighborCommunities;
 };
 
 /** Upstreams by key. */
@@ -107,11 +112,45 @@ type PolicyName<C> = Values<{
 }>;
 /** Each BGP group name. */
 type GroupName<C> = Values<{ [K in keyof C]: C[K] extends { group: infer N extends string } ? N : never }>;
-/** Each routing table name. */
-type TableName<C> = Values<{ [K in keyof C]: C[K] extends { table: infer N extends string } ? N : never }>;
+/** Each routing table name, other than main. */
+type TableName<C> = Exclude<Values<{ [K in keyof C]: C[K] extends { table: infer N extends string } ? N : never }>, "main">;
 
 /** A network's upstreams written once, and each device's part built from them. */
 export class Upstreams {
+    /**
+     * A catalog of upstreams, by key, written once and checked: a key the shape doesn't have is refused by its name. It gives the catalog back as written, so its keys and entries can be read, and is what `define` takes.
+     */
+    static catalog<const C extends UpstreamCatalog>(catalog: C & UpstreamCatalog): C {
+        return catalog;
+    }
+
+    /**
+     * Export rules asking an upstream not to pass our routes to these ASes, with its own `communities.do_not_announce_to`: one rule, `description`, adding one community per AS. Nothing for no AS. An upstream without `do_not_announce_to` is an error, since it can't be asked.
+     */
+    static doNotAnnounceTo(upstream: Upstream, asns: readonly number[], description: string): PolicyRule<never, never>[] {
+        if (!asns.length) return [];
+
+        const community = upstream.communities?.do_not_announce_to;
+        if (!community)
+            throw new Error(
+                `Upstreams: ${upstream.name ?? `AS${upstream.asn}`} has no communities.do_not_announce_to, so it can't be asked to keep our routes from AS${asns.join(", AS")}`
+            );
+
+        const communities = asns.map(community);
+        const large = communities.filter((value) => value.split(":").length === 3) as LargeCommunity[];
+        const standard = communities.filter((value) => value.split(":").length === 2) as StandardCommunity[];
+
+        return [
+            {
+                description,
+                set: {
+                    ...(standard.length ? { add_communities: standard } : {}),
+                    ...(large.length ? { add_large_communities: large } : {}),
+                },
+            },
+        ];
+    }
+
     /**
      * 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:
      *
@@ -229,7 +268,7 @@ export class Upstreams {
                 role: upstream.role,
                 ...(upstream.import ? { import: upstream.import.name as PolicyName<C> } : {}),
                 export: upstream.export.name as PolicyName<C>,
-                ...(upstream.table ? { table: upstream.table as TableName<C> } : {}),
+                ...(upstream.table ? { table: upstream.table as TableName<C> | "main" } : {}),
                 ...(multihop
                     ? {
                           local_address: multihop.local_address,

package/src/platforms/derive.ts

@@ -1,6 +1,7 @@
 // Values more than one adapter derives from a device in the same way.
 
 import { Address } from "../core/address";
+import { Utils } from "../core/utils";
 import type { Device } from "../schema";
 
 /** A feature a platform renders once proved on one of its devices. */
@@ -54,7 +55,7 @@ export class Derive {
         for (const route of routing?.static ?? []) {
             if (route.bfd && !has("static-route-bfd"))
                 found.push(`routing.static ${route.prefix} bfd, BFD on a static route is ${unproved}`);
-            if (route.table && !has("routing-tables"))
+            if (Utils.otherTable(route.table) && !has("routing-tables"))
                 found.push(`routing.static ${route.prefix} table, a routing table beside the main one is ${unproved}`);
         }
 
@@ -66,12 +67,12 @@ export class Derive {
         const bgp = routing?.bgp;
 
         for (const [name, group] of Object.entries(bgp?.groups ?? {})) {
-            if (group.table && !has("routing-tables"))
+            if (Utils.otherTable(group.table) && !has("routing-tables"))
                 found.push(`routing.bgp.groups.${name}.table, a routing table beside the main one is ${unproved}`);
         }
 
         for (const [name, neighbor] of Object.entries(bgp?.neighbors ?? {})) {
-            if (neighbor.table && !has("routing-tables"))
+            if (Utils.otherTable(neighbor.table) && !has("routing-tables"))
                 found.push(`routing.bgp.neighbors.${name}.table, a routing table beside the main one is ${unproved}`);
 
             const group = neighbor.group ? bgp?.groups?.[neighbor.group] : undefined;

package/src/platforms/routeros/index.ts

@@ -3,6 +3,7 @@
 // The platform applies every command the moment it arrives and has no candidate configuration, so a run is guarded three ways. Every command is first compiled on the device without running, so a syntax error or an unknown property costs nothing. A backup is saved and a scheduler armed to restore it, and the run must log in again in a fresh session before the scheduler is removed. A command the device refuses restores the backup at once, rather than leaving the device half applied.
 
 import type { Client } from "ssh2";
+import { Utils } from "../../core/utils";
 import { Address } from "../../core/address";
 import type { Neighbor } from "../../core/cabling";
 import type { Finding } from "../../core/define";
@@ -152,21 +153,28 @@ export class RouterOs extends Platform {
 
         for (const [name, neighbor] of Object.entries(bgp?.neighbors ?? {})) {
             const group = neighbor.group ? bgp?.groups?.[neighbor.group] : undefined;
-            const table = neighbor.table ?? group?.table;
+            const table = Utils.otherTable(neighbor.table ?? group?.table);
             if (!table) continue;
 
             const families = neighbor.families ?? group?.families ?? [Address.family(neighbor.address)];
             const networks = (bgp?.networks ?? []).filter((prefix) => families.includes(Address.family(Address.host(prefix))));
             const inTable = (prefix: string) =>
                 statics.some((route) => route.table === table && Address.canonical(route.prefix) === Address.canonical(prefix));
-            const missing = networks.filter((prefix) => !inTable(prefix));
+            // What its export accepts by prefix: a network it would reject anyway needs no route in the table. Every network when the export names none.
+            const exportPolicy = neighbor.export ?? group?.export;
+            const accepted = (exportPolicy ? (device.policies?.[exportPolicy] ?? []) : [])
+                .filter((rule) => rule.action === "accept" && rule.match?.prefix)
+                .map((rule) => Address.canonical(rule.match!.prefix!));
+            const announced = accepted.length ? networks.filter((prefix) => accepted.includes(Address.canonical(prefix))) : networks;
+
+            const missing = announced.filter((prefix) => !inTable(prefix));
             if (!missing.length) continue;
 
             const where = `routing.bgp.neighbors.${name}`;
             const route = (prefix: string) => `{ prefix: "${prefix}", blackhole: true, table: "${table}" }`;
             const fix = `On RouterOS a session announces from its own table, ${table}`;
 
-            if (missing.length === networks.length) {
+            if (missing.length === announced.length) {
                 findings.push({
                     level: "error",
                     device: device.name,

package/src/platforms/routeros/render.ts

@@ -1,6 +1,7 @@
 // The neutral model as a RouterOS 7 export, written in the form `/export` prints so the two compare line for line.
 
 import { X509Certificate } from "node:crypto";
+import { Utils } from "../../core/utils";
 import { Address } from "../../core/address";
 import { Secrets } from "../../core/secrets";
 import type {
@@ -1147,7 +1148,7 @@ export class RouterOsRender {
                 distance: route.distance,
                 "dst-address": route.prefix,
                 gateway,
-                "routing-table": route.vrf ?? route.table,
+                "routing-table": route.vrf ?? Utils.otherTable(route.table),
             });
         }
     }
@@ -1292,7 +1293,7 @@ export class RouterOsRender {
                 "output.network": originates ? RouterOsRender.NETWORKS[family] : undefined,
                 "remote.address": `${neighbor.address}/${addressFamily === "ipv4" ? 32 : 128}`,
                 "remote.as": settings.remote_as,
-                "routing-table": settings.table,
+                "routing-table": Utils.otherTable(settings.table),
                 "tcp-md5-key": settings.password && Secrets.marker(settings.password),
                 "use-bfd": settings.bfd ? "yes" : undefined,
             });

package/src/schema/routing.ts

@@ -16,8 +16,8 @@ export type StaticRoute<I extends string, F extends string, T extends string = n
     distance?: number;
     /** The VRF the route is in. The main table when absent. */
     vrf?: F;
-    /** The table the route is in, one of `routing.tables`. The main table when absent. A route has a `vrf` or a `table`, not both. */
-    table?: T;
+    /** The table the route is in: `main`, or one of `routing.tables`. The main table when absent; write `main` to say so. A route has a `vrf` or a `table`, not both. */
+    table?: T | "main";
     /** Why the route exists. */
     description?: string;
 };
@@ -57,8 +57,8 @@ export type NeighborSettings<P extends string, T extends string = never> = {
     passive?: boolean;
     /** Detect a dead link in under a second with BFD. */
     bfd?: boolean;
-    /** The table the routes learned are installed in, one of `routing.tables`. The main table when absent. On RouterOS the session also announces from that table, so each prefix of `networks` it announces needs a route in the table too, and a running session takes a new table only when it restarts. */
-    table?: T;
+    /** The table the routes learned are installed in: `main`, or one of `routing.tables`. The main table when absent; write `main` to say so. On RouterOS the session also announces from that table, so each prefix of `networks` it announces needs a route in the table too, and a running session takes a new table only when it restarts. */
+    table?: T | "main";
 };
 
 /** One BGP session. Settings it does not set come from its group. */