@takodotid/circuit 0.42.0 → 0.42.1

package/dist/cli/index.js

@@ -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;
@@ -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,42 @@ 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 = 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));
+      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) {
+        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 +8999,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 +9010,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 +9081,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 +11340,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 ?? [])

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

@@ -67,7 +67,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, 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. */
     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?: {

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

@@ -54,7 +54,7 @@ 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. */
+    /** 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;
 };
 /** One BGP session. Settings it does not set come from its group. */

package/package.json

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

package/src/core/validator.ts

@@ -63,7 +63,10 @@ export class Validator {
 
             const adapter = Platforms.find(device.platform);
             if (!adapter) report(`no adapter for platform ${device.platform}`);
-            else for (const field of adapter.unsupported(device)) report(`${device.platform} cannot express ${field}`);
+            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));

package/src/helpers/upstreams.ts

@@ -67,7 +67,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. */
+    /** 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. */
     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 };

package/src/platforms/bgp-wait.ts

@@ -15,23 +15,23 @@ export class BgpWait {
      */
     static readonly AFTER_APPLY: WaitLimits = { seconds: 180, every: 10 };
 
-    /** 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 async until(
-        read: () => Promise<BgpSession[]>,
-        enough: (sessions: BgpSession[]) => boolean,
+    /** 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 async until<T>(
+        read: () => Promise<T>,
+        enough: (value: T) => boolean,
         limits: WaitLimits,
-        waiting: (sessions: BgpSession[]) => void = () => {}
-    ): Promise<BgpSession[]> {
+        waiting: (value: T) => void = () => {}
+    ): Promise<T> {
         const deadline = Date.now() + limits.seconds * 1000;
-        let sessions = await read();
+        let value = await read();
 
-        while (!enough(sessions) && Date.now() < deadline) {
-            waiting(sessions);
+        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;
     }
 
     /** How many of these sessions are established. */

package/src/platforms/platform.ts

@@ -1,4 +1,5 @@
 import type { Neighbor } from "../core/cabling";
+import type { Finding } from "../core/define";
 import type { Device, Family } from "../schema";
 import type { ConsoleDialect } from "../transport/console";
 import type { WaitLimits } from "./bgp-wait";
@@ -100,6 +101,8 @@ export abstract class Platform {
     readonly console: ConsoleDialect | undefined = 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/src/platforms/routeros/TRAPS.md

@@ -64,6 +64,8 @@ Behaviour that looks like something else. Each one has been hit on a real device
 - No MAC learning limit on 7.23.5: `/interface bridge port` has `learn` but no limit, and `/interface ethernet switch port` has none (CCR2216). `mac_limit` stays refused.
 - A switch rule matches a kind of frame with `mac-protocol` (`ip`, `ipv6`, `arp` among 23 kinds), but cannot match "not" one. An ethertype filter is a rule that lets each kind through and a last one with an empty `new-dst-ports` for the rest, after the port's ACL rules, which match only `ip` or `ipv6`. Four such rules on a free port took the router to 70 switch rules, none invalid (CCR2216, 7.23.5).
 - A routing table holds no routes the router forwards by unless it has `fib`: `/routing table add fib name=...`. The export prints the flag between the properties, `add comment=... fib name=...`.
-- A BGP connection's `routing-table` installs what it learns in that table and not in main; the next hop still resolves through main. Proved on a CCR2216 on 7.23.5 with a session to a test speaker: its routes showed `routing-table=<table>`, active, and main kept only its own static route. The export prints `routing-table` only when it is not `main`.
+- A BGP connection's `routing-table` is where the session installs what it learns and also where it announces from: an `output.network` prefix is announced only while that table has a route for it, and a route in main alone is not enough. On a CCR2216 on 7.23.5, a fresh session with `routing-table=<table>` installed its routes there, active, with the next hop resolved through main, and announced nothing until the table had the prefix too; then it did. Circuit's validate refuses a session in a table that holds none of `networks`, and warns for each it lacks. Routing filters cannot move a route to a table: `set routing-table` and `set table` are `invalid argument`.
+- A running session takes a new `routing-table` only when it restarts, but its announcements stop at once: set from main to a table, it withdrew everything within seconds, kept its learned routes in main, and announced nothing even once the table had the prefix; set back to main, it still announced nothing until it restarted. `/routing bgp session resend afi=ipv6` did not help either, on the router where this was found (#157). Disabling and enabling the connection restarted it in the new table. The plan does exactly that, written on the plan's line, and after an apply Circuit checks that every session still announces what it announced of `networks` before (CCR2216, 7.23.5).
+- A passive connection without `local.address` listens only on its default local address, `local.default-address`, which may be a public one: a peer connecting to another address of the router gets a TCP reset (CCR2216, 7.23.5).
 - `/routing rule` is an ordered list without names, like a filter chain, and the plan rewrites it whole in the config's order. `lookup-only-in-table` drops a packet its table has no route for (a ping printed `no route`); `lookup` routes it by main instead (the ping left). An interface to match is `interface=`. A `drop` or `unreachable` rule is printed with `!realm`, which Circuit does not write (CCR2216, 7.23.5).
 - An eBGP connection to an address on no connected network, without `multihop=yes`, takes the TCP connection, logs `connection <local> from <remote>`, and closes it with no OPEN and nothing else in the log, even with `bgp,debug` logging on (CCR2216, 7.23.5).

package/src/platforms/routeros/index.ts

@@ -5,6 +5,7 @@
 import type { Client } from "ssh2";
 import { Address } from "../../core/address";
 import type { Neighbor } from "../../core/cabling";
+import type { Finding } from "../../core/define";
 import { Secrets } from "../../core/secrets";
 import type { Device, Family } from "../../schema";
 import { SerialConsole, type ConsoleDialect, ConsoleShell } from "../../transport/console";
@@ -84,6 +85,12 @@ export class RouterOs extends Platform {
     ].join(" ");
 
     /** 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(prefixes: readonly string[]): string {
+        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")) }`;
+    }
+
     private static clearLimit(address: string): string {
         return `/routing bgp session clear [find remote.address=${address} and limit-exceeded] flag=limit-exceeded`;
     }
@@ -135,6 +142,51 @@ export class RouterOs extends Platform {
 
     override readonly console = RouterOs.CONSOLE;
 
+    /**
+     * 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[] {
+        const bgp = device.routing?.bgp;
+        const statics = device.routing?.static ?? [];
+        const findings: Finding[] = [];
+
+        for (const [name, neighbor] of Object.entries(bgp?.neighbors ?? {})) {
+            const group = neighbor.group ? bgp?.groups?.[neighbor.group] : undefined;
+            const table = 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));
+            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) {
+                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: Device): string[] {
         const found: string[] = [];
 
@@ -427,13 +479,14 @@ export class RouterOs extends Platform {
     }
 
     /**
-     * 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.
      */
     async health(device: Device, plan: Plan, options: HealthOptions = {}): Promise<HealthCheck> {
         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 () => {
@@ -447,7 +500,8 @@ export class RouterOs extends Platform {
                 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();
                 }
@@ -563,6 +617,72 @@ export class RouterOs extends Platform {
         );
     }
 
+    /** What each session announces of the device's own `networks`, as `neighbor prefix`. None, without logging in, on a device without networks. */
+    private async announcedNow(device: Device, options: ReadOptions): Promise<string[]> {
+        if (!device.routing?.bgp?.networks?.length) return [];
+
+        const session = await this.session(device, options);
+
+        try {
+            return await this.announced(device, session);
+        } finally {
+            session.close();
+        }
+    }
+
+    /** 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 async announced(device: Device, session: ReadSession): Promise<string[]> {
+        const bgp = device.routing?.bgp;
+        const networks = bgp?.networks ?? [];
+        if (!networks.length) return [];
+
+        const sessions = (await session.run(RouterOs.LIST_BGP_SESSIONS, 60_000))
+            .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: string) => {
+            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), 60_000);
+        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();
+    }
+
+    /** 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 async announcedBack(device: Device, session: ReadSession, before: readonly string[], limits: WaitLimits): Promise<string[]> {
+        if (!before.length) return [];
+
+        const missing = (now: string[]) => 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'`;
+        });
+    }
+
     /** A problem when any switch rule is invalid, saying what to do. */
     private static async invalidSwitchRules(session: ReadSession, device: Device): Promise<string[]> {
         const answer = (await session.run(RouterOs.COUNT_INVALID_SWITCH_RULES)).trim();

package/src/platforms/routeros/plan.ts

@@ -83,6 +83,11 @@ export class RouterOsPlan {
     /** 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 = new Set(["/interface vlan"]);
 
+    /**
+     * 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: Record<string, string[]> = { "/routing bgp connection": ["routing-table"] };
+
     /** 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 = "frameworkOldRules";
 
@@ -314,8 +319,19 @@ export 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)));

package/src/schema/routing.ts

@@ -57,7 +57,7 @@ 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. */
+    /** 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;
 };