@takodotid/circuit 0.37.0 → 0.38.0

package/dist/chunks/index-6wb41q67.js

@@ -0,0 +1,62 @@
+// src/platforms/fortios/models.ts
+var models = {
+  "FG-3700D": {
+    ports: { "40g": 4, "10g": 28, "1g": 2 },
+    spelling: { "40g": "port{n}", "10g": "port{n+4}", "1g": "mgmt{n}" }
+  }
+};
+
+// src/platforms/junos/models.ts
+var models2 = {
+  "QFX5100-48S-6Q": {
+    ports: { "40g": 6, "10g": 48, "1g": 2 },
+    spelling: { "40g": "et-0/0/{n+47}", "10g": "xe-0/0/{n-1}", "1g": "em{n-1}" }
+  }
+};
+
+// src/platforms/raisecom-ros/models.ts
+var models3 = {
+  "RAX721-C-6C48": {
+    ports: { "100g": 6, "25g": 24, "10g": 24 },
+    spelling: { "100g": "hundredgige 1/1/{n}", "25g": "twenty-fivegige 1/2/{n}", "10g": "tengigabitethernet 1/3/{n}" }
+  }
+};
+
+// src/platforms/routeros/models.ts
+var models4 = {
+  "CCR2216-1G-12XS-2XQ": {
+    ports: { "100g": 2, "25g": 12, "1g": 1 },
+    spelling: { "100g": "qsfp28-{n}-1", "25g": "sfp28-{n}", "1g": "ether{n}" },
+    limits: { lag_members: 8, switch_port_ranges: 5 }
+  }
+};
+
+// src/platforms/vrp/models.ts
+var models5 = {
+  "CE6855-48S6Q-HI": { ports: { "10g": 48, "40g": 6 }, spelling: { "10g": "10GE1/0/{n}", "40g": "40GE1/0/{n}" } }
+};
+
+// src/platforms/catalog.ts
+class Catalog {
+  static MODELS = { routeros: models4, vrp: models5, "raisecom-ros": models3, junos: models2, fortios: models };
+  static ports(platform, model) {
+    const spec = Catalog.MODELS[platform]?.[model];
+    if (!spec)
+      throw new Error(`${platform} has no model ${model}`);
+    return Object.entries(spec.ports).flatMap(([speed, count]) => Array.from({ length: count }, (_, i) => `${speed}-${i + 1}`));
+  }
+  static limits(platform, model) {
+    const spec = Catalog.MODELS[platform]?.[model];
+    return spec?.limits ?? {};
+  }
+  static spell(platform, model, port) {
+    const spec = Catalog.MODELS[platform]?.[model];
+    const parts = /^(\d+[gm])-(\d+)$/.exec(port);
+    const template = parts && spec?.spelling[parts[1]];
+    if (!template)
+      throw new Error(`${model} has no port ${port}`);
+    return template.replace(/\{n([+-]\d+)?\}/, (_, shift) => String(Number(parts[2]) + Number(shift ?? 0)));
+  }
+}
+
+export { Catalog };

package/dist/chunks/{index-k38bby43.js → index-yzw86rc8.js}

@@ -1,68 +1,10 @@
+import {
+  Catalog
+} from "./index-6wb41q67.js";
 import {
   Address2
 } from "./index-n7w3tg5y.js";
 
-// src/platforms/fortios/models.ts
-var models = {
-  "FG-3700D": {
-    ports: { "40g": 4, "10g": 28, "1g": 2 },
-    spelling: { "40g": "port{n}", "10g": "port{n+4}", "1g": "mgmt{n}" }
-  }
-};
-
-// src/platforms/junos/models.ts
-var models2 = {
-  "QFX5100-48S-6Q": {
-    ports: { "40g": 6, "10g": 48, "1g": 2 },
-    spelling: { "40g": "et-0/0/{n+47}", "10g": "xe-0/0/{n-1}", "1g": "em{n-1}" }
-  }
-};
-
-// src/platforms/raisecom-ros/models.ts
-var models3 = {
-  "RAX721-C-6C48": {
-    ports: { "100g": 6, "25g": 24, "10g": 24 },
-    spelling: { "100g": "hundredgige 1/1/{n}", "25g": "twenty-fivegige 1/2/{n}", "10g": "tengigabitethernet 1/3/{n}" }
-  }
-};
-
-// src/platforms/routeros/models.ts
-var models4 = {
-  "CCR2216-1G-12XS-2XQ": {
-    ports: { "100g": 2, "25g": 12, "1g": 1 },
-    spelling: { "100g": "qsfp28-{n}-1", "25g": "sfp28-{n}", "1g": "ether{n}" },
-    limits: { lag_members: 8, switch_port_ranges: 5 }
-  }
-};
-
-// src/platforms/vrp/models.ts
-var models5 = {
-  "CE6855-48S6Q-HI": { ports: { "10g": 48, "40g": 6 }, spelling: { "10g": "10GE1/0/{n}", "40g": "40GE1/0/{n}" } }
-};
-
-// src/platforms/catalog.ts
-class Catalog {
-  static MODELS = { routeros: models4, vrp: models5, "raisecom-ros": models3, junos: models2, fortios: models };
-  static ports(platform, model) {
-    const spec = Catalog.MODELS[platform]?.[model];
-    if (!spec)
-      throw new Error(`${platform} has no model ${model}`);
-    return Object.entries(spec.ports).flatMap(([speed, count]) => Array.from({ length: count }, (_, i) => `${speed}-${i + 1}`));
-  }
-  static limits(platform, model) {
-    const spec = Catalog.MODELS[platform]?.[model];
-    return spec?.limits ?? {};
-  }
-  static spell(platform, model, port) {
-    const spec = Catalog.MODELS[platform]?.[model];
-    const parts = /^(\d+[gm])-(\d+)$/.exec(port);
-    const template = parts && spec?.spelling[parts[1]];
-    if (!template)
-      throw new Error(`${model} has no port ${port}`);
-    return template.replace(/\{n([+-]\d+)?\}/, (_, shift) => String(Number(parts[2]) + Number(shift ?? 0)));
-  }
-}
-
 // src/core/topology.ts
 class Builder {
   nodes = new Map;
@@ -976,4 +918,4 @@ class StudioModel {
   }
 }
 
-export { Catalog, Topology, AddressSpace, StudioModel };
+export { Topology, AddressSpace, StudioModel };

package/dist/chunks/{server-ggertnce.js → server-cxr9ynxc.js}

@@ -1,6 +1,6 @@
 import {
   StudioModel
-} from "./index-k38bby43.js";
+} from "./index-yzw86rc8.js";
 
 // src/studio/server.ts
 import { execFile as execFile2, spawn } from "node:child_process";

package/dist/cli/index.js

@@ -4,11 +4,13 @@ import {
   Secrets2
 } from "../chunks/index-20kcjxjg.js";
 import {
-  Catalog,
   Topology,
   AddressSpace,
   StudioModel
-} from "../chunks/index-k38bby43.js";
+} from "../chunks/index-yzw86rc8.js";
+import {
+  Catalog
+} from "../chunks/index-6wb41q67.js";
 import {
   Address2
 } from "../chunks/index-n7w3tg5y.js";
@@ -6596,6 +6598,20 @@ class BgpWait {
   static upCount(sessions) {
     return sessions.filter((session) => session.established).length;
   }
+  static BURST_MINUTES = 5;
+  static limitBursts(sessions) {
+    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 = [];
+    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 * 60000)
+        last.push(session);
+      else
+        bursts.push([session]);
+    }
+    return bursts.filter((burst) => burst.length > 1);
+  }
 }
 
 // src/platforms/routeros/export.ts
@@ -8381,9 +8397,15 @@ class RouterOs extends Platform {
   static 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(" ");
+  static clearLimit(address) {
+    return `/routing bgp session clear [find remote.address=${address} and limit-exceeded] flag=limit-exceeded`;
+  }
   static LIST_NEIGHBORS = [
     ':foreach n in=[/ip neighbor find where discovered-by~"lldp"] do={',
     ":local g [/ip neighbor get $n];",
@@ -8578,21 +8600,48 @@ ${certificates}` : "";
   }
   async bgpSessions(device, session) {
     const output = await session.run(RouterOs.LIST_BGP_SESSIONS, 60000);
-    const live = output.split(/\r?\n/).filter((line) => line.includes("|")).map((line) => line.trim().split("|"));
+    const lines = output.split(/\r?\n/).filter((line) => line.includes("|")).map((line) => line.trim().split("|"));
+    const live = lines.filter(([first]) => first !== "disabled");
+    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]) => {
       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" };
-      const [, remote, established, prefixes, uptime] = found;
+      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";
       return {
         neighbor: name,
         remote: remote || "-",
-        established: established === "true",
+        established: up,
         prefixes: prefixes || "-",
-        uptime: uptime || "-"
+        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, sessions) {
+    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)}`);
+    }
+  }
   async bgpLog(session, minutes) {
     const now = (await session.run(RouterOs.CLOCK)).trim();
     const nowTime = RouterOs.logTime(now);
@@ -8688,7 +8737,7 @@ ${certificates}` : "";
       console.log(`  BGP: all ${neighbors.length} established again`);
       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`);
   }
   static async invalidSwitchRules(session, device) {
     const answer = (await session.run(RouterOs.COUNT_INVALID_SWITCH_RULES)).trim();
@@ -11567,7 +11616,7 @@ class Cli {
     program.command("snapshot").description("read what each device runs into the state directory").argument("[device...]", "every device when none is named").option("--console", "through the device's serial console on its jump host, instead of SSH").option(Cli.CONFIG_FLAGS, Cli.CONFIG_HELP).action(async (devices, flags) => (await Cli.open(flags.config, flags)).snapshot(devices));
     program.command("apply").description("read the device, plan against what it runs, and send with --confirm").argument("<device>").option("--confirm", "send the plan; without it, nothing is sent").option("--secrets", "also send every secret, to rotate one").option("--rollback <minutes>", "minutes before a device that can restore itself does", Cli.minutes, 10).option("--console", "through the device's serial console on its jump host, instead of SSH").option("--force", "send even when the pings before --confirm find a path that loses too much or is too slow").option(Cli.CONFIG_FLAGS, Cli.CONFIG_HELP).action(async (device, flags) => (await Cli.open(flags.config, flags)).apply(device, flags.confirm ?? false, flags.force ?? false));
     program.command("show").description("run commands that only read on a device and print what it answers, secrets hidden").argument("<device>").argument("[command...]", "each command in quotes, such as '/ip route print'").option("--file <path>", "also each line of this file; blank lines and lines starting with # are skipped").option("--timeout <seconds>", "how long each command may take", Cli.seconds, 90).option("--console", "through the device's serial console, instead of SSH").option(Cli.CONFIG_FLAGS, Cli.CONFIG_HELP).action(async (device, commands, flags) => (await Cli.open(flags.config, flags)).show(device, commands, flags.file, flags.timeout));
-    program.command("bgp").description("each BGP neighbor in the config next to its live session: up or down, prefixes, uptime").argument("[device]", "may be left out when only one device has BGP neighbors").argument("[name-regex]", "only the neighbors whose name matches").option("--wait [count]", `read again every ${BgpWait.COMMAND.every} seconds until every neighbor shown, or this many, is up`, Cli.count).option("--max <seconds>", "how long --wait waits at most", Cli.seconds, BgpWait.COMMAND.seconds).option("--log [minutes]", "also print the device's BGP log lines from the last minutes, 5 by default", Cli.minutes).option(Cli.CONFIG_FLAGS, Cli.CONFIG_HELP).action(async (first, second, flags) => (await Cli.open(flags.config)).bgp(first, second, flags));
+    program.command("bgp").description("each BGP neighbor in the config next to its live session: up or down and why, prefixes, uptime").argument("[device]", "may be left out when only one device has BGP neighbors").argument("[name-regex]", "only the neighbors whose name matches").option("--wait [count]", `read again every ${BgpWait.COMMAND.every} seconds until every neighbor shown, or this many, is up`, Cli.count).option("--max <seconds>", "how long --wait waits at most", Cli.seconds, BgpWait.COMMAND.seconds).option("--log [minutes]", "also print the device's BGP log lines from the last minutes, 5 by default", Cli.minutes).option("--clear-limit", "open again the neighbors shown that closed on their prefix limit; any other is left alone").option(Cli.CONFIG_FLAGS, Cli.CONFIG_HELP).action(async (first, second, flags) => (await Cli.open(flags.config)).bgp(first, second, flags));
     program.command("console").description("open a device's serial console here, logged in; or send it lines and print what it answers").argument("<device>").argument("[line...]", "lines to send, each in quotes; none joins the console to this terminal, Ctrl-] leaves").option("--raw", "do not log in or out: only join the console, or send the lines").option(Cli.CONFIG_FLAGS, Cli.CONFIG_HELP).action(async (device, lines, flags) => (await Cli.open(flags.config)).console(device, lines, flags.raw ?? false));
     program.command("refresh").description("fetch prefix sets that come from a registry onto the device, with --confirm").argument("<device>").option("--confirm", "put them on the device; without it, nothing is sent").option(Cli.CONFIG_FLAGS, Cli.CONFIG_HELP).action(async (device, flags) => (await Cli.open(flags.config)).refresh(device, flags.confirm ?? false));
     program.command("wireguard").description("a client config for one peer, its private key left for the peer to fill").argument("<device>").argument("<interface>").argument("<peer>").option(Cli.CONFIG_FLAGS, Cli.CONFIG_HELP).action(async (device, iface, peer, flags) => (await Cli.open(flags.config)).wireguard(device, iface, peer));
@@ -11797,6 +11846,10 @@ ${output.replace(/\r/g, "").trimEnd()}${stoppedAtLimit}
       Cli.fail(`circuit bgp does not support ${device.platform} yet, only ${supported}`);
     if (flags.log && !adapter.bgpLog)
       Cli.fail(`circuit bgp --log does not support ${device.platform} yet`);
+    if (flags.clearLimit && !adapter.bgpClearLimit)
+      Cli.fail(`circuit bgp --clear-limit does not support ${device.platform} yet`);
+    if (flags.clearLimit && flags.wait !== undefined)
+      Cli.fail("--clear-limit and --wait go in two runs: clear first, then wait");
     let matcher;
     try {
       matcher = new RegExp(pattern ?? ".");
@@ -11813,6 +11866,10 @@ ${output.replace(/\r/g, "").trimEnd()}${stoppedAtLimit}
     const session = await adapter.session(device, this.optionsFor(device));
     try {
       const read = async () => (await adapter.bgpSessions(device, session)).filter((neighbor) => shown.includes(neighbor.neighbor));
+      if (flags.clearLimit) {
+        await Cli.clearLimits(adapter, session, read);
+        return;
+      }
       const limits = { seconds: flags.max, every: BgpWait.COMMAND.every };
       const sessions = await BgpWait.until(read, (sessions) => BgpWait.upCount(sessions) >= want, limits, (sessions) => console.log(`${new Date().toLocaleTimeString()}: ${BgpWait.upCount(sessions)}/${want} up, checking again in ${limits.every}s`));
       Cli.printBgp(sessions);
@@ -11824,6 +11881,24 @@ ${output.replace(/\r/g, "").trimEnd()}${stoppedAtLimit}
       session.close();
     }
   }
+  static async clearLimits(adapter, session, read) {
+    const sessions = await read();
+    const closed = sessions.filter((bgp) => bgp.limit);
+    if (!closed.length) {
+      Cli.printBgp(sessions);
+      console.error(`
+no neighbor shown is closed on its prefix limit, so nothing was cleared`);
+      process.exitCode = 1;
+      return;
+    }
+    for (const bgp of sessions)
+      if (!bgp.limit)
+        console.log(`${bgp.neighbor}: left alone, not closed on its limit`);
+    await adapter.bgpClearLimit(session, closed);
+    console.log(`cleared ${closed.map((bgp) => bgp.neighbor).join(", ")}: each connects again, and closes again if it still sends too much
+`);
+    Cli.printBgp(await read());
+  }
   bgpTarget(first, second) {
     if (second !== undefined || first && this.network.devices.some((device) => device.name === first)) {
       return { device: this.one(first), pattern: second };
@@ -11840,9 +11915,25 @@ ${output.replace(/\r/g, "").trimEnd()}${stoppedAtLimit}
     const width = Math.max(...sessions.map((session) => session.neighbor.length));
     for (const session of sessions) {
       const state = session.established ? "up  " : "DOWN";
-      console.log(`${session.neighbor.padEnd(width)}  ${state}  ${session.prefixes.padStart(7)}  ${session.uptime.padEnd(12)}  ${session.remote}`);
+      const why = session.reason ? `  ${Cli.downReason(session)}` : "";
+      console.log(`${session.neighbor.padEnd(width)}  ${state}  ${session.prefixes.padStart(7)}  ${session.uptime.padEnd(12)}  ${session.remote}${why}`);
     }
     console.log(`${BgpWait.upCount(sessions)}/${sessions.length} up`);
+    for (const burst of BgpWait.limitBursts(sessions)) {
+      const names = burst.map((session) => session.neighbor);
+      const listed = names.length > 1 ? `${names.slice(0, -1).join(", ")} and ${names.at(-1)}` : names[0];
+      const seconds = Math.round((burst.at(-1).limit.stoppedAt - burst[0].limit.stoppedAt) / 1000);
+      console.log(`
+${listed} closed on their prefix limit within ${seconds} s of each other, from ${burst[0].limit.stopped}. Several limits at once is usually a leak upstream, not growth: find the leak before raising a limit, then clear them with --clear-limit.`);
+    }
+  }
+  static downReason(session) {
+    const { limit } = session;
+    if (!limit)
+      return session.reason ?? "";
+    const over = limit.max !== undefined ? `: over ${limit.max} prefixes` : "";
+    const when = limit.stopped ? `, closed ${limit.stopped}` : "";
+    return `${session.reason}${over}${when}`;
   }
   async printBgpLog(adapter, session, minutes) {
     const lines = Cli.foldLog(await adapter.bgpLog(session, minutes));
@@ -12286,7 +12377,7 @@ Renamed. Run circuit validate, then circuit apply ${to}: the device keeps its ol
     const port = Number(flags.port);
     if (!Number.isInteger(port) || port < 1 || port > 65535)
       Cli.fail("--port takes a number from 1 to 65535");
-    const { StudioServer } = await import("../chunks/server-ggertnce.js");
+    const { StudioServer } = await import("../chunks/server-cxr9ynxc.js");
     const host = flags.host;
     const allowHosts = (flags.allowHost ?? "").split(",").filter(Boolean);
     if (!StudioServer.isLoopback(host) && !allowHosts.length) {

package/dist/helpers/index.js

@@ -1,3 +1,6 @@
+import {
+  Catalog
+} from "../chunks/index-6wb41q67.js";
 import {
   Address2
 } from "../chunks/index-n7w3tg5y.js";
@@ -9,6 +12,10 @@ class Bgp {
     ["twice", 2],
     ["three_times", 3]
   ];
+  static DEFAULTS = [
+    { family: "ipv4", prefix: "0.0.0.0/0" },
+    { family: "ipv6", prefix: "::/0" }
+  ];
   static sanity(lengths = {}) {
     const ipv4 = lengths.ipv4 ?? { min: 8, max: 24 };
     const ipv6 = lengths.ipv6 ?? { min: 16, max: 48 };
@@ -36,6 +43,49 @@ class Bgp {
       { description: "RPKI invalid", match: { rpki: "invalid" }, action: "reject" }
     ];
   }
+  static announce(prefixes) {
+    return [
+      ...prefixes.map(({ prefix, description }) => ({
+        ...description ? { description } : {},
+        match: { prefix },
+        action: "accept"
+      })),
+      { description: "Nothing else", action: "reject" }
+    ];
+  }
+  static learn(options = {}) {
+    const { tag } = options;
+    return [
+      ...options.before ?? [],
+      ...options.sanity ? [{ call: options.sanity }] : Bgp.sanity(),
+      ...(options.sources ?? []).map((source) => ({ set: { preferred_source: source } })),
+      ...options.local_pref !== undefined ? [{ set: { local_pref: options.local_pref } }] : [],
+      ...tag === undefined ? [] : [typeof tag === "object" ? tag : Bgp.adding(tag)],
+      { action: "accept" }
+    ];
+  }
+  static defaultOnly(options = {}) {
+    return Bgp.DEFAULTS.map(({ family, prefix }) => {
+      const source = options.sources?.find((address) => Address2.family(address) === family);
+      const set = {
+        ...options.local_pref !== undefined ? { local_pref: options.local_pref } : {},
+        ...source ? { preferred_source: source } : {}
+      };
+      return {
+        description: options.description ?? `Default route, ${family}`,
+        match: { prefix },
+        ...Object.keys(set).length ? { set } : {},
+        action: "accept"
+      };
+    });
+  }
+  static adding(community) {
+    const large = community.split(":").length === 3;
+    return {
+      description: `Tag ${community}`,
+      set: large ? { add_large_communities: [community] } : { add_communities: [community] }
+    };
+  }
   static neighborPolicies(device) {
     const bgp = device.routing?.bgp;
     return Object.entries(bgp?.neighbors ?? {}).map(([name, neighbor]) => {
@@ -181,6 +231,38 @@ class Bgp {
     return /^[aeiou]/i.test(word) ? `an ${word}` : `a ${word}`;
   }
 }
+// src/helpers/cables.ts
+class Cables {
+  static link(spec) {
+    return {
+      a: { [spec.a.port]: Cables.end(spec, spec.b, spec.b.port) },
+      b: { [spec.b.port]: Cables.end(spec, spec.a, spec.a.port) }
+    };
+  }
+  static lag(spec) {
+    const pairs = Object.entries(spec.cables);
+    const taken = new Map;
+    for (const [near, far] of pairs) {
+      const other = taken.get(far);
+      if (other)
+        throw new Error(`Cables.lag: ${spec.b.device} ${far} is cabled to both ${other} and ${near} on ${spec.a.device}`);
+      taken.set(far, near);
+    }
+    const a = Object.fromEntries(pairs.map(([near, far]) => [near, { ...Cables.end(spec, spec.b, far), lag: spec.a.lag }]));
+    const b = Object.fromEntries(pairs.map(([near, far]) => [far, { ...Cables.end(spec, spec.a, near), lag: spec.b.lag }]));
+    return {
+      a,
+      b
+    };
+  }
+  static end(shared, far, port) {
+    const farEnd = { device: far.device, port, label: Catalog.spell(far.platform, far.model, port) };
+    return {
+      description: shared.describe ? shared.describe(farEnd) : `${farEnd.device} ${farEnd.label}`,
+      link: { device: far.device, port, ...shared.through ? { through: shared.through } : {} }
+    };
+  }
+}
 // src/helpers/checks.ts
 class Checks {
   static exportsEndInReject = (devices) => {
@@ -585,10 +667,154 @@ class Filters {
     }));
   }
 }
+// src/helpers/upstreams.ts
+class Upstreams {
+  static define(catalog) {
+    const all = Object.entries(catalog);
+    const nameOf = (key, upstream) => upstream.name ?? key;
+    const policy = (key) => key.toUpperCase();
+    const grouped = (upstream) => upstream.role === "rs" || Boolean(upstream.multihop);
+    const vlans = (device) => {
+      const result = {};
+      for (const [key, upstream] of all) {
+        const handoff = upstream.handoff;
+        if (!handoff || device !== undefined && handoff.port?.device !== device)
+          continue;
+        result[key] = { id: handoff.vlan, description: nameOf(key, upstream) };
+        if (device !== undefined && handoff.native !== undefined) {
+          result[`${key}-native`] = {
+            id: handoff.native,
+            description: `Native toward ${nameOf(key, upstream)}, nothing else in it`
+          };
+        }
+      }
+      return result;
+    };
+    const vlansOn = (device) => all.filter(([, upstream]) => upstream.handoff?.port?.device === device).map(([key]) => key);
+    const ports = (device) => {
+      const result = {};
+      for (const [key, upstream] of all) {
+        const handoff = upstream.handoff;
+        if (!handoff?.port || handoff.port.device !== device)
+          continue;
+        result[handoff.port.port] = {
+          description: nameOf(key, upstream),
+          ...handoff.native !== undefined ? { trunk_vlans: [key], native_vlan: `${key}-native` } : { access_vlan: key },
+          lldp: false,
+          stp: false,
+          ...handoff.port.storm_control ? { storm_control: handoff.port.storm_control } : {}
+        };
+      }
+      return result;
+    };
+    const interfaces = () => {
+      const result = {};
+      for (const [key, upstream] of all) {
+        const description = nameOf(key, upstream);
+        if (upstream.tunnel) {
+          const { local, remote, addresses, mtu } = upstream.tunnel;
+          result[key] = { type: "gre", description, local, remote, addresses, ...mtu ? { mtu } : {} };
+        } else if (upstream.handoff) {
+          const { addresses, exchange } = upstream.handoff;
+          result[key] = { type: "vlan", vlan: key, description, addresses, ...exchange ? { exchange } : {} };
+        }
+      }
+      return result;
+    };
+    const settings = (key, upstream) => ({
+      remote_as: upstream.asn,
+      description: nameOf(key, upstream),
+      role: upstream.role,
+      ...upstream.import ? { import: `${policy(key)}-IN` } : {},
+      export: `${policy(key)}-OUT`
+    });
+    const groups = () => Object.fromEntries(all.filter(([, upstream]) => grouped(upstream)).map(([key, upstream]) => {
+      const multihop = upstream.multihop;
+      return [
+        key,
+        {
+          ...settings(key, upstream),
+          ...multihop ? {
+            local_address: multihop.local_address,
+            multihop: true,
+            ...multihop.families ? { families: multihop.families } : {},
+            ...multihop.password ? { password: multihop.password } : {}
+          } : {}
+        }
+      ];
+    }));
+    const neighbors = () => Object.fromEntries(all.flatMap(([key, upstream]) => Object.entries(upstream.sessions).map(([name, session]) => {
+      const limit = upstream.limits?.[Address2.family(session.address)];
+      return [
+        name,
+        {
+          ...session,
+          ...grouped(upstream) ? { group: key } : settings(key, upstream),
+          ...limit ? { max_prefixes: limit } : {}
+        }
+      ];
+    })));
+    const policies = (options = {}) => {
+      const result = {};
+      for (const [key, upstream] of all) {
+        result[`${policy(key)}-OUT`] = [
+          ...options.actions?.(key, upstream) ?? [],
+          ...upstream.export ?? [],
+          ...Bgp.announce(upstream.announce)
+        ];
+        const taken = upstream.import;
+        if (!taken)
+          continue;
+        const tag = options.tag?.(key, upstream);
+        result[`${policy(key)}-IN`] = [
+          ...taken.default ? Bgp.defaultOnly({ ...taken.default, ...options.sources ? { sources: options.sources } : {} }) : [],
+          ...taken.learn ? Bgp.learn({
+            ...taken.learn.before ? { before: taken.learn.before } : {},
+            ...options.sanity ? { sanity: options.sanity } : {},
+            ...options.sources ? { sources: options.sources } : {},
+            ...taken.learn.local_pref !== undefined ? { local_pref: taken.learn.local_pref } : {},
+            ...tag !== undefined ? { tag } : {}
+          }) : [{ description: "Nothing else", action: "reject" }]
+        ];
+      }
+      return result;
+    };
+    const untrusted = () => [...all.filter(([, upstream]) => upstream.handoff).map(([key]) => key), ...natives()];
+    const natives = () => all.filter(([, upstream]) => upstream.handoff?.native !== undefined).map(([key]) => `${key}-native`);
+    const privateDrops = () => all.filter(([, upstream]) => upstream.handoff && upstream.drop_private).map(([key]) => key);
+    const tunnelRules = () => all.flatMap(([key, upstream]) => upstream.tunnel ? [
+      {
+        description: `GRE from ${nameOf(key, upstream)}`,
+        match: {
+          protocol: "gre",
+          src: `${upstream.tunnel.remote}/${Address2.bits(Address2.family(upstream.tunnel.remote))}`
+        },
+        action: "accept"
+      }
+    ] : []);
+    const addresses = () => all.flatMap(([, upstream]) => Object.values(upstream.sessions).map((session) => session.address));
+    return {
+      vlans,
+      vlansOn,
+      ports,
+      interfaces,
+      groups,
+      neighbors,
+      policies,
+      untrusted,
+      natives,
+      privateDrops,
+      tunnelRules,
+      addresses
+    };
+  }
+}
 export {
   Bgp,
+  Cables,
   Checks,
   Exchange,
   Filters,
-  RouteServerConfig
+  RouteServerConfig,
+  Upstreams
 };