@takodotid/circuit 0.37.0 → 0.39.0

package/src/platforms/bgp-wait.ts

@@ -1,4 +1,4 @@
-// Waiting for BGP sessions to be established: `circuit bgp --wait`, and the check after an apply.
+// BGP sessions as `circuit bgp` and the check after an apply read them: waiting for them to be established, and spotting limits that closed several at once.
 
 import { setTimeout as sleep } from "node:timers/promises";
 import type { BgpSession } from "./platform";
@@ -38,4 +38,27 @@ export class BgpWait {
     static upCount(sessions: readonly BgpSession[]): number {
         return sessions.filter((session) => session.established).length;
     }
+
+    /** Sessions closed on their limit within this many minutes of each other are one burst. */
+    static readonly BURST_MINUTES = 5;
+
+    /**
+     * Groups of two or more sessions closed on their limit within `BURST_MINUTES` of each other, earliest first. Several limits at once is usually a leak upstream, not growth, so raising them is the wrong fix.
+     */
+    static limitBursts(sessions: readonly BgpSession[]): BgpSession[][] {
+        const closed = sessions
+            .filter((session) => session.limit?.stoppedAt !== undefined && !Number.isNaN(session.limit.stoppedAt))
+            .sort((a, b) => a.limit!.stoppedAt! - b.limit!.stoppedAt!);
+
+        const bursts: BgpSession[][] = [];
+        for (const session of closed) {
+            const last = bursts.at(-1);
+            const previous = last?.at(-1);
+            if (last && previous && session.limit!.stoppedAt! - previous.limit!.stoppedAt! <= BgpWait.BURST_MINUTES * 60_000)
+                last.push(session);
+            else bursts.push([session]);
+        }
+
+        return bursts.filter((burst) => burst.length > 1);
+    }
 }

package/src/platforms/platform.ts

@@ -58,8 +58,15 @@ export type BgpSession = {
     prefixes: string;
     /** How long it has been up, as the device prints it, or `no session`. */
     uptime: string;
+    /** Why it is down, when the device says: `limit exceeded`, `admin down`, `connecting`. */
+    reason?: string;
+    /** It closed because the neighbor sent more prefixes than its limit, and stays closed until cleared. */
+    limit?: BgpLimit;
 };
 
+/** A session closed on its prefix limit: the limit, and when it closed, as the device prints it and in milliseconds, to compare. */
+export type BgpLimit = { max?: number; stopped?: string; stoppedAt?: number };
+
 /** One BGP log line: when, as the device printed it, such as `2026-10-24 03:12:44`, and the rest of the line. */
 export type BgpLogLine = { at: string; message: string };
 
@@ -115,6 +122,8 @@ export abstract class Platform {
     bgpSessions?(device: Device, session: ReadSession): Promise<BgpSession[]>;
     /** The device's BGP log lines from the last `minutes`, by the device's own clock, read over a `session()`. */
     bgpLog?(session: ReadSession, minutes: number): Promise<BgpLogLine[]>;
+    /** Open again these sessions, each closed on its prefix limit, read by `bgpSessions`. Only a session still closed on its limit is touched. */
+    bgpClearLimit?(session: ReadSession, sessions: readonly BgpSession[]): Promise<void>;
     /**
      * Checks that the device is healthy after an apply, not only that it took the commands. Called before the plan is sent, to read what the checks compare against; the CLI runs them after the apply and the snapshot. Absent on a platform with no checks yet.
      */

package/src/platforms/routeros/TRAPS.md

@@ -12,6 +12,7 @@ Behaviour that looks like something else. Each one has been hit on a real device
 - A session edited repeatedly can stick: SYN both ways, no RST, no log. Remove the connection and add it again.
 - A session that never established is missing from `/routing bgp session print`; look at `/routing bgp connection print`. One that is trying prints `established` empty, not `false`, and no uptime (7.23.5).
 - A BGP session is named `<connection>-<n>`, and a renamed connection keeps its session's old name until the session restarts. `circuit bgp` matches a session by the neighbor's address first.
+- A session closed on its limit keeps its entry with `limit-exceeded=true`, its `input.limit-process-routes` and `last-stopped`, and the notification it sent ends in `0601` (cease, maximum prefixes). Its `prefix-count` is back to 0, so the count that tripped it is gone. `/routing bgp session clear <id> flag=limit-exceeded` opens it again; a misspelled flag is a `syntax error`, and a `find` that matches nothing does nothing (CCR2216, 7.23.5).
 - `time>` in a `/log print` filter does not filter. `circuit bgp --log` keeps the lines of the last minutes itself, against the device's clock.
 - `tcp-md5-key` set from the CLI has been seen discarded without an error, and a mismatch logs nothing. Confirm with `/tool sniffer quick port=179`.
 - Incoming GRE is subject to the input chain. Accept it before testing the tunnel.

package/src/platforms/routeros/index.ts

@@ -70,14 +70,24 @@ export class RouterOs extends Platform {
         "}",
     ].join(" ");
 
-    /** Every BGP session, one line each: name, remote address, established, prefixes received, uptime. One line, because a script sent over exec runs as one. */
+    /**
+     * Every BGP session, one line each: name, remote address, established, prefixes received, uptime, closed on its limit, the limit, when it last closed. Then each disabled connection, `disabled|<name>|<address>`. One line, because a script sent over exec runs as one.
+     */
     private static readonly LIST_BGP_SESSIONS = [
         ":foreach s in=[/routing bgp session find] do={",
         ":local g [/routing bgp session get $s];",
-        ':put (($g->"name") . "|" . ($g->"remote.address") . "|" . ($g->"established") . "|" . ($g->"prefix-count") . "|" . ($g->"uptime"))',
+        ':put (($g->"name") . "|" . ($g->"remote.address") . "|" . ($g->"established") . "|" . ($g->"prefix-count") . "|" . ($g->"uptime") . "|" . ($g->"limit-exceeded") . "|" . ($g->"input.limit-process-routes") . "|" . ($g->"last-stopped"))',
+        "};",
+        ":foreach c in=[/routing bgp connection find disabled] do={",
+        ':put ("disabled|" . [/routing bgp connection get $c name] . "|" . [/routing bgp connection get $c remote.address])',
         "}",
     ].join(" ");
 
+    /** Open again the session from one address, only while it is closed on its limit. */
+    private static clearLimit(address: string): string {
+        return `/routing bgp session clear [find remote.address=${address} and limit-exceeded] flag=limit-exceeded`;
+    }
+
     /**
      * 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.
      */
@@ -325,32 +335,68 @@ export class RouterOs extends Platform {
 
     /**
      * A session is named `<connection>-<n>`, but a renamed connection keeps its session's old name until the session restarts. So a neighbor is matched by its address first, then by name.
+     *
+     * A session that is down says why: closed on its limit, or still connecting. A neighbor with no session and a disabled connection is admin down.
      */
     async bgpSessions(device: Device, session: ReadSession): Promise<BgpSession[]> {
         const output = await session.run(RouterOs.LIST_BGP_SESSIONS, 60_000);
-        const live = output
+        const lines = output
             .split(/\r?\n/)
             .filter((line) => line.includes("|"))
             .map((line) => line.trim().split("|"));
+        const live = lines.filter(([first]) => first !== "disabled");
+        // A connection's address carries its length, `10.0.0.1/32`.
+        const disabled = lines
+            .filter(([first]) => first === "disabled")
+            .map(([, name, address]) => ({ name, address: address?.split("/")[0] }));
 
-        return Object.entries(device.routing?.bgp?.neighbors ?? {}).map(([name, neighbor]) => {
+        return Object.entries(device.routing?.bgp?.neighbors ?? {}).map(([name, neighbor]): BgpSession => {
             const found =
                 live.find(([, remote]) => remote === neighbor.address) ??
                 live.find(([sessionName]) => sessionName === name || sessionName?.replace(/-\d+$/, "") === name);
 
-            if (!found) return { neighbor: name, remote: "-", established: false, prefixes: "-", uptime: "no session" };
+            if (!found) {
+                const off = disabled.some((connection) => connection.address === neighbor.address || connection.name === name);
+                return {
+                    neighbor: name,
+                    remote: "-",
+                    established: false,
+                    prefixes: "-",
+                    uptime: "no session",
+                    ...(off ? { reason: "admin down" } : {}),
+                };
+            }
+
+            const [, remote, established, prefixes, uptime, limitExceeded, max, stopped] = found;
+            const up = established === "true";
+            const limited = limitExceeded === "true";
 
-            const [, remote, established, prefixes, uptime] = found;
             return {
                 neighbor: name,
                 remote: remote || "-",
-                established: established === "true",
+                established: up,
                 prefixes: prefixes || "-",
                 uptime: uptime || "-",
+                ...(up ? {} : { reason: limited ? "limit exceeded" : "connecting" }),
+                ...(limited
+                    ? {
+                          limit: {
+                              ...(max && /^\d+$/.test(max) ? { max: Number(max) } : {}),
+                              ...(stopped ? { stopped, stoppedAt: RouterOs.logTime(stopped) } : {}),
+                          },
+                      }
+                    : {}),
             };
         });
     }
 
+    async bgpClearLimit(session: ReadSession, sessions: readonly BgpSession[]): Promise<void> {
+        for (const bgp of sessions) {
+            const answer = (await session.run(RouterOs.clearLimit(bgp.remote))).trim();
+            if (answer) throw new Error(`could not clear ${bgp.neighbor}: ${answer.slice(0, 200)}`);
+        }
+    }
+
     /** 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. */
     async bgpLog(session: ReadSession, minutes: number): Promise<BgpLogLine[]> {
         const now = (await session.run(RouterOs.CLOCK)).trim();
@@ -501,9 +547,10 @@ export class RouterOs extends Platform {
             return [];
         }
 
-        return down.map(
-            (bgp) =>
-                `BGP session ${bgp.neighbor} was established before the apply and is not ${limits.seconds} s after it (${bgp.uptime === "no session" ? "no session" : "not established"}). Look with: circuit bgp ${device.name} --log`
+        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} ${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`
         );
     }
 

package/src/schema/interfaces.ts

@@ -113,7 +113,7 @@ export type Port<V extends string, A extends string, L extends string, F extends
         acl?: A;
         /** The LAG this port is in. Every other setting goes on the LAG. */
         lag?: L;
-        /** Another of our devices at the other end of the cable. */
+        /** Another of our devices at the other end of the cable. Without a `description`, the port is described from it: the far device and the far port as printed on it, such as `firewall-1 port6`. */
         link?: Link;
     };