@takodotid/circuit 0.42.0 → 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;
@@ -6822,13 +6822,13 @@ class BgpWait {
   static AFTER_APPLY = { seconds: 180, every: 10 };
   static async until(read, enough, limits, waiting = () => {}) {
     const deadline = Date.now() + limits.seconds * 1000;
-    let sessions = await read();
-    while (!enough(sessions) && Date.now() < deadline) {
-      waiting(sessions);
+    let value = await read();
+    while (!enough(value) && Date.now() < deadline) {
+      waiting(value);
       await sleep(Math.min(limits.every * 1000, Math.max(0, deadline - Date.now())));
-      sessions = await read();
+      value = await read();
     }
-    return sessions;
+    return value;
   }
   static upCount(sessions) {
     return sessions.filter((session) => session.established).length;
@@ -7176,6 +7176,7 @@ class RouterOsPlan {
     "/interface bridge vlan"
   ]);
   static CHANGED_IN_PLACE = new Set(["/interface vlan"]);
+  static RESTART_ON = { "/routing bgp connection": ["routing-table"] };
   static OLD_RULES = "frameworkOldRules";
   problems = [];
   constructor(sendSecrets) {
@@ -7346,8 +7347,16 @@ class RouterOsPlan {
       const update = this.changes(entry, current, `${menu} ${entryKey}`);
       if (!Object.keys(update).length)
         continue;
+      const selector = RouterOsPlan.find(menu, RouterOsExport.identity(current));
+      const restartsOn = (RouterOsPlan.RESTART_ON[menu] ?? []).filter((property) => (property in update));
+      if (restartsOn.length) {
+        changeStep.show.push(`~ ${entryKey} ${RouterOsPlan.describe(update)}, restarting the session: it takes a new ${restartsOn.join(" and ")} only when it restarts`);
+        changeStep.send.push(RouterOsPlan.line(menu, "set", selector, [], { disabled: "yes", ...update }));
+        changeStep.send.push(RouterOsPlan.line(menu, "set", selector, [], { disabled: "no" }));
+        continue;
+      }
       changeStep.show.push(`~ ${entryKey} ${RouterOsPlan.describe(update)}`);
-      changeStep.send.push(RouterOsPlan.line(menu, "set", RouterOsPlan.find(menu, RouterOsExport.identity(current)), [], update));
+      changeStep.send.push(RouterOsPlan.line(menu, "set", selector, [], update));
     }
     const removed = existingEntries.filter((entry) => !kept.has(key(entry)));
     const wholeLists = new Set;
@@ -8334,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)
       });
     }
   }
@@ -8455,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
       });
@@ -8687,6 +8696,10 @@ class RouterOs extends Platform {
     ':put ("disabled|" . [/routing bgp connection get $c name] . "|" . [/routing bgp connection get $c remote.address])',
     "}"
   ].join(" ");
+  static listAdvertisements(prefixes) {
+    const where = prefixes.map((prefix) => `dst=${prefix}`).join(" or ");
+    return `:foreach a in=[/routing bgp advertisements print as-value where ${where}] do={ :put ("ADV|" . ($a->"peer") . "|" . ($a->"dst")) }`;
+  }
   static clearLimit(address) {
     return `/routing bgp session clear [find remote.address=${address} and limit-exceeded] flag=limit-exceeded`;
   }
@@ -8713,6 +8726,45 @@ class RouterOs extends Platform {
   };
   extension = ".rsc";
   console = RouterOs.CONSOLE;
+  checks(device) {
+    const bgp = device.routing?.bgp;
+    const statics = device.routing?.static ?? [];
+    const findings = [];
+    for (const [name, neighbor] of Object.entries(bgp?.neighbors ?? {})) {
+      const group = neighbor.group ? bgp?.groups?.[neighbor.group] : undefined;
+      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 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 === announced.length) {
+        findings.push({
+          level: "error",
+          device: device.name,
+          message: `${where} would announce nothing: ${fix}, which has no route for any of networks. Add the routes it announces to ${table} too, such as ${route(missing[0])} in routing.static`
+        });
+        continue;
+      }
+      for (const prefix of missing) {
+        findings.push({
+          level: "warning",
+          device: device.name,
+          message: `${where} does not announce ${prefix}: ${fix}, which has no route for it. If its export should announce it, add ${route(prefix)} to routing.static`
+        });
+      }
+    }
+    return findings;
+  }
   unsupported(device) {
     const found = [];
     for (const [name, iface] of Object.entries(device.interfaces ?? {})) {
@@ -8950,6 +9002,7 @@ ${certificates}` : "";
     const switchRules = plan.steps.some((step) => step.send.some((command) => command.startsWith(RouterOs.SWITCH_RULES)));
     const limits = options.bgp ?? BgpWait.AFTER_APPLY;
     const establishedBefore = await this.establishedSessions(device, options);
+    const announcedBefore = establishedBefore.length ? await this.announcedNow(device, options) : [];
     return {
       run: async () => {
         if (!switchRules && !establishedBefore.length) {
@@ -8960,7 +9013,8 @@ ${certificates}` : "";
         try {
           const switchProblems = switchRules ? await RouterOs.invalidSwitchRules(session, device) : [];
           const bgpProblems = await this.bgpBack(device, session, establishedBefore, limits);
-          return [...switchProblems, ...bgpProblems];
+          const announceProblems = await this.announcedBack(device, session, announcedBefore, limits);
+          return [...switchProblems, ...bgpProblems, ...announceProblems];
         } finally {
           session.close();
         }
@@ -9030,6 +9084,50 @@ ${certificates}` : "";
     }
     return down.map((bgp) => bgp.limit ? `BGP session ${bgp.neighbor} was established before the apply and closed on its limit${bgp.limit.max !== undefined ? ` of ${bgp.limit.max} prefixes` : ""}: the neighbor sends more than it may. Find out why, then: circuit bgp ${device.name} --neighbors '^${bgp.neighbor}$' --clear-limit` : `BGP session ${bgp.neighbor} was established before the apply and is not ${limits.seconds} s after it (${bgp.reason ?? (bgp.uptime === "no session" ? "no session" : "not established")}). Look with: circuit bgp ${device.name} --log`);
   }
+  async announcedNow(device, options) {
+    if (!device.routing?.bgp?.networks?.length)
+      return [];
+    const session = await this.session(device, options);
+    try {
+      return await this.announced(device, session);
+    } finally {
+      session.close();
+    }
+  }
+  async announced(device, session) {
+    const bgp = device.routing?.bgp;
+    const networks = bgp?.networks ?? [];
+    if (!networks.length)
+      return [];
+    const sessions = (await session.run(RouterOs.LIST_BGP_SESSIONS, 60000)).split(/\r?\n/).map((line) => line.trim().split("|")).filter((fields) => fields.length > 1 && fields[0] !== "disabled");
+    const neighbors = Object.entries(bgp?.neighbors ?? {});
+    const neighborOf = (sessionName) => {
+      const remote = sessions.find(([name]) => name === sessionName)?.[1];
+      const byAddress = neighbors.find(([, neighbor]) => neighbor.address === remote);
+      const byName = neighbors.find(([name]) => name === sessionName.replace(/-\d+$/, ""));
+      return (byAddress ?? byName)?.[0];
+    };
+    const output = await session.run(RouterOs.listAdvertisements(networks), 60000);
+    return output.split(/\r?\n/).map((line) => line.trim().split("|")).flatMap(([marker, peer, prefix]) => {
+      const neighbor = marker === "ADV" && peer ? neighborOf(peer) : undefined;
+      return neighbor && prefix ? [`${neighbor} ${prefix}`] : [];
+    }).sort();
+  }
+  async announcedBack(device, session, before, limits) {
+    if (!before.length)
+      return [];
+    const missing = (now) => before.filter((pair) => !now.includes(pair));
+    const after = await BgpWait.until(() => this.announced(device, session), (now) => !missing(now).length, limits, (now) => console.log(`  BGP: ${missing(now).length} announcement(s) not back yet, checking again in ${limits.every} s`));
+    const gone = missing(after);
+    if (!gone.length) {
+      console.log(`  BGP: every session announces what it announced before`);
+      return [];
+    }
+    return gone.map((pair) => {
+      const [neighbor, prefix] = pair.split(" ");
+      return `BGP session ${neighbor} announced ${prefix} before the apply and does not ${limits.seconds} s after it, though it may still be established. A RouterOS session announces from its routing table: that table needs a route for ${prefix}, and a session whose table changed must restart. Look with: circuit show ${device.name} '/routing bgp advertisements print'`;
+    });
+  }
   static async invalidSwitchRules(session, device) {
     const answer = (await session.run(RouterOs.COUNT_INVALID_SWITCH_RULES)).trim();
     if (!/^\d+$/.test(answer))
@@ -11245,9 +11343,11 @@ class Validator {
       const adapter = Platforms.find(device.platform);
       if (!adapter)
         report(`no adapter for platform ${device.platform}`);
-      else
+      else {
         for (const field of adapter.unsupported(device))
           report(`${device.platform} cannot express ${field}`);
+        findings.push(...adapter.checks?.(device) ?? []);
+      }
     }
     findings.push(...CrossChecks.run(network.devices));
     for (const check of network.checks ?? [])
@@ -11458,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);
@@ -11467,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));
@@ -11500,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. */
+    /** 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/platforms/bgp-wait.d.ts

@@ -11,8 +11,8 @@ export declare class BgpWait {
      * After an apply, the sessions established before have 180 seconds to be established again, read every 10 seconds. A session reset by a change opens again when one side retries; three minutes leaves room for a slow peer without holding the apply up for long. A session that never went down is seen at the first read, so a healthy apply does not wait.
      */
     static readonly AFTER_APPLY: WaitLimits;
-    /** Read the sessions until `enough` holds or time runs out, and give the last read. `waiting` is told of each read that fell short, before the pause. */
-    static until(read: () => Promise<BgpSession[]>, enough: (sessions: BgpSession[]) => boolean, limits: WaitLimits, waiting?: (sessions: BgpSession[]) => void): Promise<BgpSession[]>;
+    /** Read until `enough` holds or time runs out, and give the last read: the sessions, or what they announce. `waiting` is told of each read that fell short, before the pause. */
+    static until<T>(read: () => Promise<T>, enough: (value: T) => boolean, limits: WaitLimits, waiting?: (value: T) => void): Promise<T>;
     /** How many of these sessions are established. */
     static upCount(sessions: readonly BgpSession[]): number;
     /** Sessions closed on their limit within this many minutes of each other are one burst. */

package/dist/types/platforms/platform.d.ts

@@ -1,4 +1,5 @@
 import type { Neighbor } from "../core/cabling.js";
+import type { Finding } from "../core/define.js";
 import type { Device, Family } from "../schema/index.js";
 import type { ConsoleDialect } from "../transport/console.js";
 import type { WaitLimits } from "./bgp-wait.js";
@@ -101,6 +102,8 @@ export declare abstract class Platform {
     readonly console: ConsoleDialect | undefined;
     /** Fields this platform cannot express. Validation fails on any of them, so nothing is skipped silently. */
     abstract unsupported(device: Device): string[];
+    /** What the platform does with a config that it may not do elsewhere, each as `validate` reports it: an error stops `diff` and `apply`, a warning is reported only. Absent on a platform with none. */
+    checks?(device: Device): Finding[];
     /** The switch rules the render makes from the device's hardware ACLs, so `validate` can hold them to the model's limits. Absent on a platform whose rules are not counted. */
     switchRules?(device: Device): SwitchRules;
     /** The whole configuration the device should run. Secrets appear as markers, never values. */

package/dist/types/platforms/routeros/index.d.ts

@@ -1,4 +1,5 @@
 import type { Neighbor } from "../../core/cabling.js";
+import type { Finding } from "../../core/define.js";
 import type { Device, Family } from "../../schema/index.js";
 import { type ConsoleDialect } from "../../transport/console.js";
 import { type ApplyOptions, type BgpLogLine, type BgpSession, type HealthCheck, type HealthOptions, type OsSupport, type Plan, type ReadOptions, type ReadSession, type SwitchRules, Platform } from "../platform.js";
@@ -18,6 +19,8 @@ export declare class RouterOs extends Platform {
      */
     private static readonly LIST_BGP_SESSIONS;
     /** Open again the session from one address, only while it is closed on its limit. */
+    /** Each advertisement of these prefixes, one line each: `ADV|<session>|<prefix>`. One line, because a script sent over exec runs as one. */
+    private static listAdvertisements;
     private static clearLimit;
     /**
      * Every LLDP neighbor, one line each: our interfaces, the port first and then the LAG and bridge it is in, the far system name, and the far port as LLDP reports it. `:tostr` keeps the interface list one value; joined to a string as it is, a list repeats the whole line for each of its items. One line, because a script sent over exec runs as one.
@@ -41,6 +44,10 @@ export declare class RouterOs extends Platform {
     readonly os: OsSupport;
     readonly extension = ".rsc";
     readonly console: ConsoleDialect;
+    /**
+     * A BGP session with a `table` announces from that table, not from main: each prefix of `networks` it announces needs a route in the table too, or it is not announced (TRAPS.md). A session left with nothing to announce is an error; a prefix missing from its table is a warning, since its export may not announce it anyway.
+     */
+    checks(device: Device): Finding[];
     unsupported(device: Device): string[];
     render(device: Device): string;
     switchRules(device: Device): SwitchRules;
@@ -63,7 +70,7 @@ export declare class RouterOs extends Platform {
     /** A `time>` filter in `/log print` does not filter, so the lines are kept here by comparing each one's time with the device's clock. */
     bgpLog(session: ReadSession, minutes: number): Promise<BgpLogLine[]>;
     /**
-     * Two checks after an apply. When the plan touched switch rules, none may be invalid. BGP sessions established before the apply must be established again, within `BgpWait.AFTER_APPLY`.
+     * Three checks after an apply. When the plan touched switch rules, none may be invalid. BGP sessions established before the apply must be established again, and announce again each of the device's `networks` they announced before, within `BgpWait.AFTER_APPLY`. A session can stay up and stop announcing (TRAPS.md), which the session check alone would not see.
      */
     health(device: Device, plan: Plan, options?: HealthOptions): Promise<HealthCheck>;
     /** The LLDP neighbors the device sees, by Circuit's port names. */
@@ -80,6 +87,12 @@ export declare class RouterOs extends Platform {
     private establishedSessions;
     /** Wait until every one of these neighbors is established again, and give a problem for each that is not when time runs out. */
     private bgpBack;
+    /** What each session announces of the device's own `networks`, as `neighbor prefix`. None, without logging in, on a device without networks. */
+    private announcedNow;
+    /** The `networks` each session announces, as `neighbor prefix`, sorted. An advertisement names its session, which is matched to its neighbor by address first, as in `bgpSessions`. */
+    private announced;
+    /** Wait until each session announces again what it announced before, and give a problem for each prefix a session no longer announces when time runs out. */
+    private announcedBack;
     /** A problem when any switch rule is invalid, saying what to do. */
     private static invalidSwitchRules;
     /** Log in over SSH. `flags` go after the user, as RouterOS reads them: `+ct300w`. */

package/dist/types/platforms/routeros/plan.d.ts

@@ -9,6 +9,10 @@ export declare class RouterOsPlan {
     private static readonly DYNAMIC;
     /** Menus where an entry that keeps its name but changes what it is known by is changed with a `set`, so what points at it by name, such as an address on a VLAN interface, stays attached. In every other menu it is removed and added again. */
     private static readonly CHANGED_IN_PLACE;
+    /**
+     * Properties a running entry takes only when it restarts. A BGP session given a new `routing-table` stops announcing at once and keeps its routes in the old table until it restarts (TRAPS.md), so the plan disables the connection, changes it and enables it again: one restart, written in the plan.
+     */
+    private static readonly RESTART_ON;
     /** The variable holding the old rules of an ordered menu while the new ones are added. Removed when the rewrite ends. */
     private static readonly OLD_RULES;
     /** What blocks an apply: something this plan cannot converge. */

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. What is announced still comes from `networks` and the main table. */
-    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> & {