@takodotid/circuit 0.36.0 → 0.38.0

package/dist/types/platforms/line-diff.d.ts

@@ -1,4 +1,4 @@
-import type { Plan } from "./platform";
+import type { Plan } from "./platform.js";
 export type Dialect = {
     /** A line at the margin that opens a block, for platforms that do not indent a block's lines. */
     block: RegExp;

package/dist/types/platforms/platform.d.ts

@@ -1,8 +1,8 @@
-import type { Neighbor } from "../core/cabling";
-import type { Device, Family } from "../schema";
-import type { ConsoleDialect } from "../transport/console";
-import type { WaitLimits } from "./bgp-wait";
-import type { PlatformName } from "./catalog";
+import type { Neighbor } from "../core/cabling.js";
+import type { Device, Family } from "../schema/index.js";
+import type { ConsoleDialect } from "../transport/console.js";
+import type { WaitLimits } from "./bgp-wait.js";
+import type { PlatformName } from "./catalog.js";
 /** One part of a plan: what a reviewer reads, and what is sent. */
 export type Step = {
     title: string;
@@ -57,6 +57,16 @@ 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 = {
@@ -113,6 +123,8 @@ export declare 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/dist/types/platforms/raisecom-ros/index.d.ts

@@ -1,8 +1,8 @@
 import type { ClientChannel } from "ssh2";
-import type { Neighbor } from "../../core/cabling";
-import type { Device } from "../../schema";
-import { type ConsoleDialect } from "../../transport/console";
-import { type ApplyOptions, type OsSupport, type Plan, type ReadOptions, type ReadSession, Platform } from "../platform";
+import type { Neighbor } from "../../core/cabling.js";
+import type { Device } from "../../schema/index.js";
+import { type ConsoleDialect } from "../../transport/console.js";
+import { type ApplyOptions, type OsSupport, type Plan, type ReadOptions, type ReadSession, Platform } from "../platform.js";
 /** A session, and how to prove access in a fresh login: a new SSH session, or logging out and in again on the console. */
 export type Session = {
     channel: ClientChannel;

package/dist/types/platforms/raisecom-ros/render.d.ts

@@ -1,4 +1,4 @@
-import type { Device, SnmpUser } from "../../schema";
+import type { Device, SnmpUser } from "../../schema/index.js";
 /** The configuration a Raisecom ROS device should run. */
 export declare class RaisecomRosRender {
     /** The access-list that guards every management service. */

package/dist/types/platforms/routeros/index.d.ts

@@ -1,7 +1,7 @@
-import type { Neighbor } from "../../core/cabling";
-import type { Device, Family } from "../../schema";
-import { type ConsoleDialect } from "../../transport/console";
-import { type ApplyOptions, type BgpLogLine, type BgpSession, type HealthCheck, type HealthOptions, type OsSupport, type Plan, type ReadOptions, type ReadSession, type SwitchRules, Platform } from "../platform";
+import type { Neighbor } from "../../core/cabling.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";
 export declare class RouterOs extends Platform {
     /** How the RouterOS console asks for a login. The flags after the user turn off colours and terminal detection, without which the console redraws every line. */
     static readonly CONSOLE: ConsoleDialect;
@@ -13,8 +13,12 @@ export declare class RouterOs extends Platform {
     private static readonly EXPORT_TIMESTAMP;
     /** Lists certificates in the form the renderer writes them, since an export does not include them. One line, because a script sent over exec runs as one. */
     private static readonly LIST_CERTIFICATES;
-    /** 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;
+    /** Open again the session from one address, only while it is closed on its limit. */
+    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.
      */
@@ -51,8 +55,11 @@ export declare class RouterOs extends Platform {
     session(device: Device, options?: ReadOptions): Promise<ReadSession>;
     /**
      * 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.
      */
     bgpSessions(device: Device, session: ReadSession): Promise<BgpSession[]>;
+    bgpClearLimit(session: ReadSession, sessions: readonly BgpSession[]): Promise<void>;
     /** 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[]>;
     /**

package/dist/types/platforms/routeros/plan.d.ts

@@ -1,4 +1,4 @@
-import type { ApplyOptions, Plan } from "../platform";
+import type { ApplyOptions, Plan } from "../platform.js";
 export declare class RouterOsPlan {
     private readonly sendSecrets;
     /** A plan line the apply handles itself: upload a certificate and its key, and import them. */

package/dist/types/platforms/routeros/render.d.ts

@@ -1,4 +1,4 @@
-import type { AclRule, Device, Ethertype, Interface, Port } from "../../schema";
+import type { AclRule, Device, Ethertype, Interface, Port } from "../../schema/index.js";
 /** A property value as a command takes it. `undefined` and `false` leave the property out. */
 export type Value = string | number | undefined | false;
 export type AnyPort = Port<string, string, string, string>;

package/dist/types/platforms/vrp/index.d.ts

@@ -1,7 +1,7 @@
-import type { Neighbor } from "../../core/cabling";
-import type { Device } from "../../schema";
-import { type ConsoleDialect } from "../../transport/console";
-import { type ApplyOptions, type OsSupport, type Plan, type ReadOptions, type ReadSession, Platform } from "../platform";
+import type { Neighbor } from "../../core/cabling.js";
+import type { Device } from "../../schema/index.js";
+import { type ConsoleDialect } from "../../transport/console.js";
+import { type ApplyOptions, type OsSupport, type Plan, type ReadOptions, type ReadSession, Platform } from "../platform.js";
 export declare class Vrp extends Platform {
     /** How the console asks for a login: the same question to change the password, always answered no, a system view left with `return`, and the line's banner after a logout or a refused password answered with Enter. Not yet proved on a device. */
     static readonly CONSOLE: ConsoleDialect;

package/dist/types/platforms/vrp/render.d.ts

@@ -1,4 +1,4 @@
-import type { Device } from "../../schema";
+import type { Device } from "../../schema/index.js";
 /** Builds the configuration as blocks: a header line, its indented lines, then `#`. */
 export declare class VrpRender {
     private readonly device;

package/dist/types/schema/device.d.ts

@@ -1,9 +1,9 @@
-import type { IP, Secret } from "./common";
-import type { AclRule, Firewall } from "./firewall";
-import type { Interface, Port, Vlan } from "./interfaces";
-import type { PrefixSet, RoutePolicy } from "./policy";
-import type { Routing } from "./routing";
-import type { Certificate, DhcpRelay, DhcpServer, FlowExport, Management, System, User } from "./system";
+import type { IP, Secret } from "./common.js";
+import type { AclRule, Firewall } from "./firewall.js";
+import type { Interface, Port, Vlan } from "./interfaces.js";
+import type { PrefixSet, RoutePolicy } from "./policy.js";
+import type { Routing } from "./routing.js";
+import type { Certificate, DhcpRelay, DhcpServer, FlowExport, Management, System, User } from "./system.js";
 /** How the framework reaches the device. */
 export type Connection<U extends string> = {
     /** Management address. Absent for a device reached only through its console, `console`. */

package/dist/types/schema/firewall.d.ts

@@ -1,4 +1,4 @@
-import type { Family, IP, Prefix, Rate } from "./common";
+import type { Family, IP, Prefix, Rate } from "./common.js";
 /** An IP protocol. `icmp` means ICMPv6 in an IPv6 rule. */
 export type Protocol = "tcp" | "udp" | "icmp" | "gre" | "esp" | "ah" | "ospf" | "vrrp";
 /** The state connection tracking assigns a packet. */

package/dist/types/schema/index.d.ts

@@ -1,8 +1,8 @@
-export type * from "./common";
-export type * from "./device";
-export type * from "./firewall";
-export type * from "./interfaces";
-export type * from "./policy";
-export type * from "./routing";
-export type * from "./system";
-export type * from "./time-zones";
+export type * from "./common.js";
+export type * from "./device.js";
+export type * from "./firewall.js";
+export type * from "./interfaces.js";
+export type * from "./policy.js";
+export type * from "./routing.js";
+export type * from "./system.js";
+export type * from "./time-zones.js";

package/dist/types/schema/interfaces.d.ts

@@ -1,4 +1,4 @@
-import type { InterfaceAddress, IP, MacAddress, Prefix, Secret } from "./common";
+import type { InterfaceAddress, IP, MacAddress, Prefix, Secret } from "./common.js";
 /** A VLAN. Its key in `vlans` is its name. */
 export type Vlan = {
     /** The VLAN's number on the wire, 1 to 4094. */
@@ -90,6 +90,10 @@ export type Link = {
     device: string;
     /** The port on that device. */
     port: string;
+    /**
+     * What is between the two ends when the cable is not direct, such as a carrier's local loop or L2 transport: `"Carrier A local loop"`. LLDP then sees the carrier's switches, not the far end, so `validate` does not compare LLDP on this port. Both ends name the same carrier.
+     */
+    through?: string;
 };
 /** A physical port. Ports a device does not declare are shut down. */
 export type Port<V extends string, A extends string, L extends string, F extends string> = Routed<F> & Switched<V> & {

package/dist/types/schema/policy.d.ts

@@ -1,4 +1,4 @@
-import type { Family, IP, Prefix } from "./common";
+import type { Family, IP, Prefix } from "./common.js";
 /** A standard BGP community, `asn:value`, for example `64500:100`. Each part is 0 to 65535. */
 export type StandardCommunity = `${number}:${number}`;
 /** A large BGP community, `asn:function:parameter`, for example `64500:1:6939`. Each part is 0 to 4294967295. */

package/dist/types/schema/routing.d.ts

@@ -1,4 +1,4 @@
-import type { Family, IP, Prefix, Secret } from "./common";
+import type { Family, IP, Prefix, Secret } from "./common.js";
 /** A route the device has without learning it. */
 export type StaticRoute<I extends string, F extends string> = {
     /** Destination. */

package/dist/types/schema/system.d.ts

@@ -1,5 +1,5 @@
-import type { IP, MacAddress, Prefix, Secret, Severity } from "./common";
-import type { TimeZone } from "./time-zones";
+import type { IP, MacAddress, Prefix, Secret, Severity } from "./common.js";
+import type { TimeZone } from "./time-zones.js";
 /** A software release track, as RouterOS names them. `long-term` changes least; `development` is the newest and least tested. */
 export type ReleaseChannel = "long-term" | "stable" | "testing" | "development";
 /** How bad an alarm is, most severe first, as ITU-T X.733 ranks them. */

package/dist/types/transport/console.d.ts

@@ -1,5 +1,5 @@
 import { type ClientChannel } from "ssh2";
-import type { Console, Device } from "../schema";
+import type { Console, Device } from "../schema/index.js";
 /** An open console: the stream to the device's CLI, and how to let it go. `close` waits for the console to go quiet, then lets the port go. */
 export type ConsoleSession = {
     channel: ClientChannel;

package/dist/types/transport/ssh.d.ts

@@ -1,5 +1,5 @@
 import { Client, type ClientChannel } from "ssh2";
-import type { Device } from "../schema";
+import type { Device } from "../schema/index.js";
 export type Login = {
     host: string;
     port?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.36.0",
+    "version": "0.38.0",
     "description": "Declarative, vendor-neutral network configuration: describe each device in TypeScript, and Circuit makes the device match. Alpha.",
     "keywords": [
         "network",
@@ -89,7 +89,7 @@
         "release": "bun scripts/release.ts",
         "prepare": "husky || true",
         "prepack": "bun run build",
-        "check": "bun run typecheck && bun run test && bun run format:check && bun run docs:build && bun run build && node dist/cli/index.js validate --config templates/single-site/circuit.config.ts && node dist/cli/index.js validate --config templates/edge-router/circuit.config.ts && node dist/cli/index.js validate --config templates/colocation/circuit.config.ts",
+        "check": "bun run typecheck && bun run test && bun run format:check && bun run docs:build && bun run build && bunx tsc -p test/package && node dist/cli/index.js validate --config templates/single-site/circuit.config.ts && node dist/cli/index.js validate --config templates/edge-router/circuit.config.ts && node dist/cli/index.js validate --config templates/colocation/circuit.config.ts",
         "agents:setup": "npx -y skills experimental_install"
     },
     "dependencies": {

package/src/cli/index.ts

@@ -228,7 +228,7 @@ class Cli {
 
         program
             .command("bgp")
-            .description("each BGP neighbor in the config next to its live session: up or down, prefixes, uptime")
+            .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(
@@ -238,6 +238,7 @@ class Cli {
             )
             .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));
 
@@ -604,12 +605,12 @@ class Cli {
     }
 
     /**
-     * Each BGP neighbor in the config next to its live session. `first` is the device, or, when it names none and only one device has BGP neighbors, the name pattern. With `wait`, reads again until every neighbor shown, or that many, is up, and fails when time runs out.
+     * Each BGP neighbor in the config next to its live session. `first` is the device, or, when it names none and only one device has BGP neighbors, the name pattern. With `wait`, reads again until every neighbor shown, or that many, is up, and fails when time runs out. With `clearLimit`, opens again the neighbors shown that closed on their prefix limit, and fails when none did.
      */
     private async bgp(
         first: string | undefined,
         second: string | undefined,
-        flags: { wait?: true | number; max: number; log?: true | number }
+        flags: { wait?: true | number; max: number; log?: true | number; clearLimit?: true }
     ): Promise<void> {
         const { device, pattern } = this.bgpTarget(first, second);
         const adapter = this.adapterOf(device);
@@ -620,6 +621,8 @@ class Cli {
             .join(", ");
         if (!adapter.bgpSessions) 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: RegExp;
         try {
@@ -640,6 +643,11 @@ class Cli {
         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,
@@ -660,6 +668,27 @@ class Cli {
         }
     }
 
+    /** Open again the sessions closed on their limit, say which others were left alone, and show them all after. */
+    private static async clearLimits(adapter: Platform, session: ReadSession, read: () => Promise<BgpSession[]>): Promise<void> {
+        const sessions = await read();
+        const closed = sessions.filter((bgp) => bgp.limit);
+
+        if (!closed.length) {
+            Cli.printBgp(sessions);
+            console.error("\nno 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\n`
+        );
+
+        Cli.printBgp(await read());
+    }
+
     /** The device `circuit bgp` reads, and the name pattern, from its two optional arguments. */
     private bgpTarget(first: string | undefined, second: string | undefined): { device: Device; pattern: string | undefined } {
         if (second !== undefined || (first && this.network.devices.some((device) => device.name === first))) {
@@ -681,12 +710,34 @@ class Cli {
 
         for (const session of sessions) {
             const state = session.established ? "up  " : "DOWN";
+            const why = session.reason ? `  ${Cli.downReason(session)}` : "";
             console.log(
-                `${session.neighbor.padEnd(width)}  ${state}  ${session.prefixes.padStart(7)}  ${session.uptime.padEnd(12)}  ${session.remote}`
+                `${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.`
+            );
+        }
+    }
+
+    /** Why a session is down, with its limit and when it closed when that is why. */
+    private static downReason(session: BgpSession): string {
+        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}`;
     }
 
     /** The device's BGP log lines from the last `minutes`, a message repeated folded into one line, secrets hidden. */

package/src/core/cabling.ts

@@ -67,7 +67,7 @@ export class Cabling {
     /**
      * Warnings where LLDP and `link` disagree, from each device's own view: a cable in another port than `link` names, a cable `link` names that LLDP does not see, and another of our devices on a port without `link`.
      *
-     * Only ports where both ends run LLDP, by the config, are compared, and only on devices whose neighbors were read. LLDP can be off at the far end, so each is a warning.
+     * 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[] {
         const findings: Finding[] = [];
@@ -97,6 +97,9 @@ export class Cabling {
                     continue;
                 }
 
+                // Through a carrier, LLDP sees the carrier's switches, not the far end.
+                if (link.through) continue;
+
                 const far = devices.find((candidate) => candidate.name === link.device);
                 if (!far || !Cabling.runsOn(far, link.port)) continue;
 

package/src/core/cross-checks.ts

@@ -97,7 +97,7 @@ export class CrossChecks {
         return undefined;
     }
 
-    /** A link names a device and port that exist, the far end links back, and both ends carry the same VLANs the same way, with the same MTU, speed and addresses. */
+    /** A link names a device and port that exist, the far end links back through the same carrier, and both ends carry the same VLANs the same way, with the same MTU, speed and addresses. */
     private static checkLinks(devices: readonly Device[]): Finding[] {
         const findings: Finding[] = [];
         const byName = new Map(devices.map((device) => [device.name, device]));
@@ -132,6 +132,11 @@ export class CrossChecks {
                     continue;
                 }
 
+                if (link.through !== farPort.link?.through) {
+                    const say = (through: string | undefined) => (through ? `through ${through}` : "direct");
+                    report(`${say(link.through)} here, and ${say(farPort.link?.through)} on ${link.device} ${link.port}`);
+                }
+
                 const near = CrossChecks.carrierOf(device, portName, port);
                 const away = CrossChecks.carrierOf(far, link.port, farPort);
 

package/src/core/topology.ts

@@ -203,7 +203,8 @@ export class Topology {
                     ? Topology.deviceId(far.name)
                     : graph.node(`missing:${link.device}`, "outside", link.device, ["named by a link, and not in the network"]);
 
-                const cableLine = `${here} to ${there}`;
+                const through = link.through ? `, through ${link.through}` : "";
+                const cableLine = `${here} to ${there}${through}`;
 
                 // A LAG's member cables to one LAG on the far side are one edge.
                 const lag = port.lag;
@@ -214,7 +215,7 @@ export class Topology {
                 if (bundle) {
                     bundle.members++;
                     bundle.cable.detail.push(cableLine);
-                    bundle.cable.label = `${lag} to ${farLag}, ${bundle.members} cables`;
+                    bundle.cable.label = `${lag} to ${farLag}, ${bundle.members} cables${through}`;
                     continue;
                 }
 
@@ -224,7 +225,7 @@ export class Topology {
                     layer: "l1",
                     from: Topology.deviceId(device.name),
                     to,
-                    label: isBundle ? `${lag} to ${farLag}` : `${portName} to ${link.port}`,
+                    label: `${isBundle ? `${lag} to ${farLag}` : `${portName} to ${link.port}`}${through}`,
                     detail: [cableLine],
                     ...(linksBack ? {} : { oneSided: true as const }),
                 });

package/src/helpers/bgp.ts

@@ -1,5 +1,15 @@
+import { Address } from "../core/address";
 import type { Community } from "../core/define";
-import type { Device, LargeCommunityPattern, PolicyRule, Prefix, StandardCommunity, StandardCommunityPattern } from "../schema";
+import type {
+    Device,
+    IP,
+    LargeCommunity,
+    LargeCommunityPattern,
+    PolicyRule,
+    Prefix,
+    StandardCommunity,
+    StandardCommunityPattern,
+} from "../schema";
 
 /** The prefix lengths a BGP import accepts. */
 export type SanityLengths = {
@@ -9,6 +19,33 @@ export type SanityLengths = {
     ipv6?: { min: number; 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>>;
 
@@ -45,7 +82,7 @@ export type CommunityScheme<
 /** 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 class Bgp {
     private static readonly PREPENDS = [
         ["once", 1],
@@ -53,6 +90,12 @@ export class Bgp {
         ["three_times", 3],
     ] as const;
 
+    /** The default route of each family. */
+    private static readonly DEFAULTS = [
+        { family: "ipv4", prefix: "0.0.0.0/0" },
+        { family: "ipv6", prefix: "::/0" },
+    ] as const;
+
     /** 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>[] {
         const ipv4 = lengths.ipv4 ?? { min: 8, max: 24 };
@@ -83,6 +126,65 @@ export class Bgp {
         ];
     }
 
+    /** 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>[] {
+        return [
+            ...prefixes.map(({ prefix, description }) => ({
+                ...(description ? { description } : {}),
+                match: { prefix },
+                action: "accept" as const,
+            })),
+            { description: "Nothing else", action: "reject" },
+        ];
+    }
+
+    /**
+     * 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>[] {
+        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" },
+        ];
+    }
+
+    /**
+     * 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>[] {
+        return Bgp.DEFAULTS.map(({ family, prefix }) => {
+            const source = options.sources?.find((address) => Address.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" as const,
+            };
+        });
+    }
+
+    /** A rule adding one community, standard or large. */
+    private static adding(community: StandardCommunity | LargeCommunity): PolicyRule<never, never> {
+        const large = community.split(":").length === 3;
+        return {
+            description: `Tag ${community}`,
+            set: large ? { add_large_communities: [community as LargeCommunity] } : { add_communities: [community as StandardCommunity] },
+        };
+    }
+
     /** Each BGP neighbor's own policies and role, or its group's. */
     static neighborPolicies(device: Device) {
         const bgp = device.routing?.bgp;