@takodotid/circuit 0.42.1 → 0.43.1

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;
@@ -1611,7 +1611,9 @@ class FortiOsPlan {
     "Fortinet_SSL_ED25519",
     "Fortinet_SSL_ED448"
   ];
-  static ORDERED = { ordered: true };
+  static BY_COMMENTS = { keys: [["comments"]] };
+  static ORDERED = { ordered: true, numbered: FortiOsPlan.BY_COMMENTS };
+  static ROUTES = { numbered: { keys: [["comment"]] }, distinct: true };
   static TABLES = {
     "system interface": {
       factory: ["modem", "ssl.root"],
@@ -1636,8 +1638,11 @@ class FortiOsPlan {
     "firewall local-in-policy": FortiOsPlan.ORDERED,
     "firewall local-in-policy6": FortiOsPlan.ORDERED,
     "firewall central-snat-map": FortiOsPlan.ORDERED,
-    "router static": { distinct: true },
-    "router static6": { distinct: true }
+    "firewall acl": { numbered: FortiOsPlan.BY_COMMENTS },
+    "firewall acl6": { numbered: FortiOsPlan.BY_COMMENTS },
+    "firewall vip": { numbered: { keys: [["comment"], ["extintf", "extip", "protocol", "extport"]], prefix: "dnat-" } },
+    "router static": FortiOsPlan.ROUTES,
+    "router static6": FortiOsPlan.ROUTES
   };
   static IGNORED = new Set(["uuid", "snmp-index"]);
   static IGNORED_IN = {
@@ -1798,7 +1803,7 @@ class FortiOsPlan {
     }
     for (const [header, child] of want.blocks)
       nested(header, child, have.blocks.get(header) ?? new FortiOsBlock);
-    const entries = table?.byContent ? FortiOsPlan.byContent(path, want, have) : table?.distinct ? FortiOsPlan.distinctById(path, want, have, table, context) : FortiOsPlan.byId(path, want, have, table, context);
+    const entries = table?.byContent ? FortiOsPlan.byContent(path, want, have) : table?.numbered ? FortiOsPlan.numbered(path, want, have, table, table.numbered, context) : FortiOsPlan.byId(path, want, have, table, context);
     send.push(...entries.send);
     show.push(...entries.show);
     if (top) {
@@ -1840,55 +1845,100 @@ class FortiOsPlan {
       removals.push(`delete ${entry.id}`);
       removed.push(...FortiOsPlan.shown("-", [...path, FortiOsTree.bare(entry.id)], entry.block));
     }
-    if (table?.ordered) {
-      const moved = FortiOsPlan.moves(want, have);
-      send.push(...moved);
-      show.push(...moved.map((line) => `+ ${FortiOsPlan.labelOf(path)}${line}`));
-    }
     return { send, show, removals, removed };
   }
-  static distinctById(path, want, have, table, context) {
-    const deletes = [];
-    const creates = [];
+  static numbered(path, want, have, table, numbered, context) {
+    const send = [];
     const show = [];
+    const pattern = new RegExp(`^${numbered.prefix ?? ""}(\\d+)$`);
+    const numberOf = (entry) => Number(pattern.exec(FortiOsTree.bare(entry.id))?.[1] ?? NaN);
+    const held = [...have.entries.values()].filter((entry) => !FortiOsPlan.isFactory(table, entry));
+    const kept = new Map;
+    const unmatched = new Set(held.filter((entry) => Number.isInteger(numberOf(entry))));
+    const keep = (key, old) => {
+      kept.set(key, old);
+      unmatched.delete(old);
+    };
+    const alike = Map.groupBy(unmatched, (old) => FortiOsPlan.signature(old.block, context.section));
+    const same = (entry, old) => !FortiOsPlan.compare([], entry.block, old.block, undefined, false, context).send.length;
     for (const [key, entry] of want.entries) {
-      const old = have.entries.get(key);
-      const where = [...path, FortiOsTree.bare(entry.id)];
-      if (old) {
-        if (!FortiOsPlan.compare(where, entry.block, old.block, undefined, false, context).send.length)
-          continue;
-        deletes.push(`delete ${old.id}`);
-        show.push(...FortiOsPlan.shown("-", where, old.block));
+      const candidates = alike.get(FortiOsPlan.signature(entry.block, context.section)) ?? [];
+      const index = candidates.findIndex((old) => same(entry, old));
+      if (index >= 0)
+        keep(key, candidates.splice(index, 1)[0]);
+    }
+    for (const settings of numbered.keys) {
+      const valueOf = (entry) => {
+        const parts = settings.map((setting) => FortiOsPlan.canonical(setting, entry.block.settings.get(setting) ?? ""));
+        return parts.some(Boolean) ? parts.join(`
+`) : undefined;
+      };
+      const changed = Map.groupBy([...want.entries].filter(([key]) => !kept.has(key)), ([, entry]) => valueOf(entry));
+      const left = Map.groupBy(unmatched, valueOf);
+      for (const [value, entries] of changed) {
+        const old = left.get(value);
+        if (value !== undefined && entries.length === 1 && old?.length === 1)
+          keep(entries[0][0], old[0]);
       }
-      creates.push(...FortiOsPlan.creation(entry, table));
-      show.push(...FortiOsPlan.shown("+", where, entry.block));
     }
-    for (const [key, entry] of have.entries) {
-      if (want.entries.has(key) || FortiOsPlan.isFactory(table, entry))
+    let next = Math.max(0, ...[...have.entries.values()].map(numberOf).filter(Number.isInteger)) + 1;
+    const wanted = [];
+    const replaced = [];
+    for (const [key, entry] of want.entries) {
+      const old = kept.get(key);
+      if (!old) {
+        const name = `${numbered.prefix ?? ""}${next++}`;
+        const id = numbered.prefix ? FortiOsTree.quote(name) : name;
+        wanted.push(id);
+        send.push(...FortiOsPlan.creation(entry, table, id));
+        show.push(...FortiOsPlan.shown("+", [...path, name], entry.block));
         continue;
-      deletes.push(`delete ${entry.id}`);
-      show.push(...FortiOsPlan.shown("-", [...path, FortiOsTree.bare(entry.id)], entry.block));
+      }
+      wanted.push(old.id);
+      const where = [...path, FortiOsTree.bare(old.id)];
+      const diff = FortiOsPlan.compare(where, entry.block, old.block, undefined, false, context);
+      if (!diff.send.length)
+        continue;
+      if (table.distinct) {
+        replaced.push(`delete ${old.id}`);
+        send.push(...FortiOsPlan.creation(entry, table, old.id));
+        show.push(...FortiOsPlan.shown("-", where, old.block), ...FortiOsPlan.shown("+", where, entry.block));
+        continue;
+      }
+      send.push(`edit ${old.id}`, ...diff.send, "next");
+      show.push(...diff.show);
     }
-    return { send: [...deletes, ...creates], show, removals: [], removed: [] };
+    const keptEntries = new Set(kept.values());
+    if (table.ordered) {
+      const order = held.filter((entry) => keptEntries.has(entry)).map((entry) => entry.id);
+      const moved = FortiOsPlan.moves(wanted, order);
+      send.push(...moved);
+      show.push(...moved.map((line) => `+ ${FortiOsPlan.labelOf(path)}${line}`));
+    }
+    const gone = held.filter((entry) => !keptEntries.has(entry));
+    const removals = gone.map((entry) => `delete ${entry.id}`);
+    const removed = gone.flatMap((entry) => FortiOsPlan.shown("-", [...path, FortiOsTree.bare(entry.id)], entry.block));
+    if (table.distinct)
+      return { send: [...replaced, ...removals, ...send], show: [...removed, ...show], removals: [], removed: [] };
+    return { send, show, removals, removed };
   }
-  static moves(want, have) {
-    const wanted = [...want.entries.keys()];
-    const order = [...have.entries.keys()].filter((key) => want.entries.has(key));
-    order.push(...wanted.filter((key) => !have.entries.has(key)));
+  static moves(wanted, held) {
+    const order = [...held, ...wanted.filter((id) => !held.includes(id))];
     const send = [];
-    const idOf = (key) => want.entries.get(key).id;
     for (let index = 0;index < wanted.length; index++) {
-      if (order[index] === wanted[index])
+      const id = wanted[index];
+      if (order[index] === id)
         continue;
-      const key = wanted[index];
-      send.push(index === 0 ? `move ${idOf(key)} before ${idOf(order[0])}` : `move ${idOf(key)} after ${idOf(wanted[index - 1])}`);
-      order.splice(order.indexOf(key), 1);
-      order.splice(index, 0, key);
+      send.push(index === 0 ? `move ${id} before ${order[0]}` : `move ${id} after ${wanted[index - 1]}`);
+      order.splice(order.indexOf(id), 1);
+      order.splice(index, 0, id);
     }
     return send;
   }
-  static signature(block) {
-    return [...block.settings].map(([key, value]) => `${key} ${FortiOsPlan.canonical(key, value)}`).sort().join(`
+  static signature(block, section = "") {
+    const defaults = FortiOsPlan.DEFAULTS[section] ?? {};
+    const isDefault = (key, value) => defaults[key] !== undefined && FortiOsPlan.canonical(key, defaults[key]) === FortiOsPlan.canonical(key, value);
+    return [...block.settings].filter(([key, value]) => !isDefault(key, value)).map(([key, value]) => `${key} ${FortiOsPlan.canonical(key, value)}`).sort().join(`
 `);
   }
   static byContent(path, want, have) {
@@ -8343,7 +8393,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 +8514,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 +8782,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 +11608,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 +11617,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 +11650,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/platforms/fortios/plan.d.ts

@@ -5,7 +5,11 @@ export declare class FortiOsPlan {
     private static readonly FACTORY_SERVICES;
     /** The device's own certificates, which the factory makes for each device. */
     private static readonly FACTORY_CERTIFICATES;
+    /** An entry known by what it holds, or else by its description. */
+    private static readonly BY_COMMENTS;
     private static readonly ORDERED;
+    /** A static route known by what it holds, or else by its description. Many routes share a destination, so that is no key. */
+    private static readonly ROUTES;
     /** Tables whose entries need more than a plain comparison, by section. */
     private static readonly TABLES;
     /** Settings the device keeps for itself: an object's UUID and an interface's SNMP index. */
@@ -61,13 +65,19 @@ export declare class FortiOsPlan {
      * What goes is undone before what comes is set, since a setting can hide another: `send-deny-packet` exists only while a policy denies. A nested list that goes is deleted before the settings, since one can hide the list and keep its entries hidden, such as `secondary-IP`; NTP refuses to delete its last server while it synchronises, so `ntpsync` goes before its list.
      */
     private static compare;
-    /** Entries matched by name: new ones created, changed ones edited, gone ones deleted, and an ordered table put in order. */
+    /** Entries matched by name: new ones created, changed ones edited, gone ones deleted. */
     private static byId;
-    /** Entries matched by name in a table that refuses two alike: every entry that changes or goes is deleted before any is created, so none is ever briefly the same as another. */
-    private static distinctById;
-    /** The `move` commands that put a table's entries in the render's order. Kept entries hold their place on the device and new ones are added at the end. */
+    /**
+     * Entries the render numbers by their place, while on the device each keeps the number it was created with, so they are matched by what they are.
+     *
+     * An entry that holds the same as one on the device is kept. One that changes is found by the first of the table's keys that no other entry left to match shares, such as its description, and edited under its own number. Any other is new and takes a number the device does not use; in a table the device keeps in order, it is created at the end and moved into place. An entry on the device that nothing matched is deleted last, so every entry the render keeps stays on the device through the whole change.
+     *
+     * In a `distinct` table, an entry that changes is deleted and created again under its own number, and every deletion comes before any creation.
+     */
+    private static numbered;
+    /** The `move` commands that put a table's entries in the render's order, by the device's numbers: `wanted` in the render's order, `held` the kept ones in the device's. Kept entries hold their place on the device and new ones are added at the end. */
     private static moves;
-    /** An entry's settings in the form two entries compare in, whatever their numbers. */
+    /** An entry's settings in the form two entries compare in, whatever their numbers. A setting at its section's default is left out, as the device does not print it. */
     private static signature;
     /** Entries matched by what they hold. One the device holds and the render does not is deleted; one the render adds takes a number the device does not use. */
     private static byContent;

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.1",
     "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", {