@takodotid/circuit 0.37.0 → 0.39.0

package/dist/cli/index.js

@@ -3748,6 +3748,28 @@ class Cabling {
     }
     return findings;
   }
+  static describeLinks(devices) {
+    const byName = new Map(devices.map((device) => [device.name, device]));
+    return devices.map((device) => {
+      const ports = Object.entries(device.ports ?? {});
+      if (!ports.some(([, port]) => port?.link && port.description === undefined))
+        return device;
+      const described = ports.map(([name, port]) => {
+        const far = port?.link ? byName.get(port.link.device) : undefined;
+        if (!port?.link || port.description !== undefined || !far)
+          return [name, port];
+        return [name, { ...port, description: `${far.name} ${Cabling.labelOf(far, port.link.port)}` }];
+      });
+      return { ...device, ports: Object.fromEntries(described) };
+    });
+  }
+  static labelOf(device, port) {
+    try {
+      return Catalog.spell(device.platform, device.model, port);
+    } catch {
+      return port;
+    }
+  }
   static isDevice(system, name) {
     return system === name || system.startsWith(`${name}.`);
   }
@@ -6596,6 +6618,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 +8417,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 +8620,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 +8757,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();
@@ -11520,10 +11589,14 @@ class Cli {
     return new Cli(configPath, network, options);
   }
   static async load(path) {
-    if (process.versions.bun)
-      return (await import(path)).default;
-    const { createJiti } = await import("jiti");
-    return createJiti(import.meta.url).import(path, { default: true });
+    let network;
+    if (process.versions.bun) {
+      network = (await import(path)).default;
+    } else {
+      const { createJiti } = await import("jiti");
+      network = await createJiti(import.meta.url).import(path, { default: true });
+    }
+    return { ...network, devices: Cabling.describeLinks(network.devices) };
   }
   static fail(message) {
     console.error(message);
@@ -11567,7 +11640,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 +11870,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 +11890,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 +11905,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 +11939,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));

package/dist/helpers/index.js

@@ -9,6 +9,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 +40,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 +228,37 @@ 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.device, spec.b.port) },
+      b: { [spec.b.port]: Cables.end(spec, spec.a.device, 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.device, far), lag: spec.a.lag }]));
+    const b = Object.fromEntries(pairs.map(([near, far]) => [far, { ...Cables.end(spec, spec.a.device, near), lag: spec.b.lag }]));
+    return {
+      a,
+      b
+    };
+  }
+  static end(shared, device, port) {
+    return {
+      link: { device, port, ...shared.through ? { through: shared.through } : {} },
+      ...shared.describe ? { description: shared.describe({ device, port }) } : {}
+    };
+  }
+}
 // src/helpers/checks.ts
 class Checks {
   static exportsEndInReject = (devices) => {
@@ -585,10 +663,200 @@ class Filters {
     }));
   }
 }
+// src/helpers/upstreams.ts
+var DEFAULTS = {
+  vlan: "{key}",
+  native: "{key}-native",
+  interface: "{key}",
+  import: "{KEY}-IN",
+  export: "{KEY}-OUT",
+  group: "{key}"
+};
+
+class Upstreams {
+  static define(catalog, options = {}) {
+    const names = options.names ?? {};
+    const all = Object.entries(catalog);
+    const nameOf = (key, upstream) => upstream.name ?? key;
+    const grouped = (upstream) => upstream.role === "rs" || Boolean(upstream.multihop);
+    const named = (field, key, upstream) => {
+      const given = names[field];
+      const pattern = given === undefined || typeof given === "string" ? given ?? DEFAULTS[field] : (upstream.tunnel && "tunnel" in given ? given.tunnel : given[upstream.role]) ?? DEFAULTS[field];
+      return pattern.replaceAll("{key}", key).replaceAll("{KEY}", key.toUpperCase()).replaceAll("{number}", () => {
+        const number = upstream.handoff?.number ?? upstream.tunnel?.number;
+        if (number === undefined)
+          throw new Error(`Upstreams: ${key} needs a number for ${field} name ${pattern}`);
+        return String(number);
+      });
+    };
+    for (const field of Object.keys(DEFAULTS)) {
+      const taken = new Map;
+      for (const [key, upstream] of all) {
+        if (field === "native" && upstream.handoff?.native === undefined)
+          continue;
+        if (field === "import" && !upstream.import)
+          continue;
+        if (field === "group" && !grouped(upstream))
+          continue;
+        if (field === "vlan" && !upstream.handoff || field === "interface" && !upstream.handoff && !upstream.tunnel)
+          continue;
+        const name = named(field, key, upstream);
+        const other = taken.get(name);
+        if (other)
+          throw new Error(`Upstreams: ${other} and ${key} both have the ${field} name ${name}`);
+        taken.set(name, key);
+      }
+    }
+    const vlan = (key, upstream) => named("vlan", key, upstream);
+    const native = (key, upstream) => named("native", key, upstream);
+    const policy = (direction, key, upstream) => named(direction, key, upstream);
+    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[vlan(key, upstream)] = { id: handoff.vlan, description: nameOf(key, upstream) };
+        if (device !== undefined && handoff.native !== undefined) {
+          result[native(key, upstream)] = {
+            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, upstream]) => vlan(key, upstream));
+    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: names.port ? names.port(key, upstream) : nameOf(key, upstream),
+          ...handoff.native !== undefined ? { trunk_vlans: [vlan(key, upstream)], native_vlan: native(key, upstream) } : { access_vlan: vlan(key, upstream) },
+          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);
+        const name = named("interface", key, upstream);
+        if (upstream.tunnel) {
+          const { local, remote, addresses, mtu } = upstream.tunnel;
+          result[name] = { type: "gre", description, local, remote, addresses, ...mtu ? { mtu } : {} };
+        } else if (upstream.handoff) {
+          const { addresses, exchange } = upstream.handoff;
+          result[name] = { type: "vlan", vlan: vlan(key, upstream), description, addresses, ...exchange ? { exchange } : {} };
+        }
+      }
+      return result;
+    };
+    const uplinks = () => all.filter(([, upstream]) => upstream.handoff).map(([key, upstream]) => named("interface", key, upstream));
+    const settings = (key, upstream) => ({
+      remote_as: upstream.asn,
+      description: nameOf(key, upstream),
+      role: upstream.role,
+      ...upstream.import ? { import: policy("import", key, upstream) } : {},
+      export: policy("export", key, upstream)
+    });
+    const groups = () => Object.fromEntries(all.filter(([, upstream]) => grouped(upstream)).map(([key, upstream]) => {
+      const multihop = upstream.multihop;
+      return [
+        named("group", key, upstream),
+        {
+          ...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: named("group", key, upstream) } : settings(key, upstream),
+          ...limit ? { max_prefixes: limit } : {}
+        }
+      ];
+    })));
+    const policies = (options = {}) => {
+      const result = {};
+      for (const [key, upstream] of all) {
+        result[policy("export", key, upstream)] = [
+          ...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("import", key, upstream)] = [
+          ...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, upstream]) => vlan(key, upstream)),
+      ...natives()
+    ];
+    const natives = () => all.filter(([, upstream]) => upstream.handoff?.native !== undefined).map(([key, upstream]) => native(key, upstream));
+    const privateDrops = () => all.filter(([, upstream]) => upstream.handoff && upstream.drop_private).map(([key, upstream]) => vlan(key, upstream));
+    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,
+      uplinks,
+      groups,
+      neighbors,
+      policies,
+      untrusted,
+      natives,
+      privateDrops,
+      tunnelRules,
+      addresses
+    };
+  }
+}
 export {
   Bgp,
+  Cables,
   Checks,
   Exchange,
   Filters,
-  RouteServerConfig
+  RouteServerConfig,
+  Upstreams
 };

package/dist/types/core/cabling.d.ts

@@ -31,6 +31,12 @@ export declare class Cabling {
      * Only ports where both ends run LLDP, by the config, are compared, and only on devices whose neighbors were read. A link `through` a carrier is not compared. LLDP can be off at the far end, so each is a warning.
      */
     static compare(devices: readonly Device[], neighbors: ReadonlyMap<string, readonly Neighbor[]>): Finding[];
+    /**
+     * Each linked port without a description gets one from its far end: the far device and the far port as printed on it, such as `firewall-1 port6`. The far device's own file has its platform and model, so the label is never written twice. A port whose far device is not in the network keeps none.
+     */
+    static describeLinks(devices: readonly Device[]): Device[];
+    /** A port as printed on the device, or Circuit's name for it when the model has no spelling for it. */
+    private static labelOf;
     /** A system name is the device's name, alone or with a domain after it. */
     private static isDevice;
     private static deviceOf;

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

@@ -1,5 +1,5 @@
 import type { Community } from "../core/define.js";
-import type { Device, PolicyRule, Prefix, StandardCommunity } from "../schema/index.js";
+import type { Device, IP, LargeCommunity, PolicyRule, Prefix, StandardCommunity } from "../schema/index.js";
 /** The prefix lengths a BGP import accepts. */
 export type SanityLengths = {
     /** Shortest and longest IPv4 prefix accepted. /8 to /24 when absent. */
@@ -13,6 +13,33 @@ export type SanityLengths = {
         max: number;
     };
 };
+/** A prefix we announce, and what it is. */
+export type Announced = {
+    prefix: Prefix;
+    description?: string;
+};
+/** What `Bgp.learn` builds an import from. */
+export type LearnOptions<P extends string> = {
+    /** Rules of your own, first. */
+    before?: readonly PolicyRule<P, never>[];
+    /** A policy holding `Bgp.sanity()` to call. The sanity rules are written in the import itself when absent. */
+    sanity?: P;
+    /** The source address for routes of its family, one per family. */
+    sources?: readonly IP[];
+    /** Preference for the routes learned. Higher wins. */
+    local_pref?: number;
+    /** Where the route came from: a community to add, or a rule, such as `communityScheme(...).tag(...)`. */
+    tag?: StandardCommunity | LargeCommunity | PolicyRule<never, never>;
+};
+/** What `Bgp.defaultOnly` sets on the default routes it takes. */
+export type DefaultOnlyOptions = {
+    /** Preference for the default route. Higher wins. */
+    local_pref?: number;
+    /** Shown beside each rule. `Default route, ipv4` and `Default route, ipv6` when absent. */
+    description?: string;
+    /** The source address for the default of its family, one per family. */
+    sources?: readonly IP[];
+};
 /** Kinds of neighbor and the number each is tagged with, such as `{ transit: 1, customer: 3 }`. */
 export type CommunityClasses = Readonly<Record<string, number>>;
 /**
@@ -55,15 +82,31 @@ export type CommunityScheme<Asn extends number = number, LearnedFrom extends num
 };
 /** 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, a community scheme, and helpers that read a device's BGP neighbors. */
+/** 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. */
 export declare class Bgp {
     private static readonly PREPENDS;
+    /** The default route of each family. */
+    private static readonly DEFAULTS;
     /** Route policy rules rejecting what no neighbor should send: prefixes too short or too long for the global table, and RPKI invalid. Place it first in an import, or as a policy other imports call. */
     static sanity(lengths?: SanityLengths): PolicyRule<never, never>[];
+    /** An export policy that announces each prefix, at exactly its length, then rejects everything else. The last rule is the unconditional reject `Checks.exportsEndInReject` looks for. */
+    static announce(prefixes: readonly Announced[]): PolicyRule<never, never>[];
+    /**
+     * An import policy that takes a neighbor's routes: `before` first, then the sanity rules, then each source address and the local preference, then the tag, then accept.
+     *
+     * `sanity` names a policy holding `Bgp.sanity()` to call, so several imports share one; without it, the sanity rules are written here. `tag` is a community to add, or a rule such as `communityScheme(...).tag(...)`. Each of `sources` is the source address for routes of its own family.
+     */
+    static learn<const P extends string = never>(options?: LearnOptions<P>): PolicyRule<P, never>[];
+    /**
+     * Import rules that take the default route, `0.0.0.0/0` and `::/0`, from a transit. Any other route reaches the next rule, or is rejected when there is none. Each of `sources` is the source address for the default of its own family.
+     */
+    static defaultOnly(options?: DefaultOnlyOptions): PolicyRule<never, never>[];
+    /** A rule adding one community, standard or large. */
+    private static adding;
     /** Each BGP neighbor's own policies and role, or its group's. */
     static neighborPolicies(device: Device): {
         name: string;
-        address: import("../index.js").IP;
+        address: IP;
         role: import("../index.js").BgpRole | undefined;
         import: string | undefined;
         export: string | undefined;