@takodotid/circuit 0.37.0 → 0.38.0

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;

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

@@ -0,0 +1,70 @@
+import { type ModelName, type PlatformName, type PortName } from "../platforms/catalog.js";
+/** One end of a cable: the device, and its platform and model, which name its ports. */
+export type CableEnd<P extends PlatformName, M extends ModelName<P>> = {
+    device: string;
+    platform: P;
+    model: M;
+};
+/** The far end of a port, for its description: the device, the port by Circuit's name, and by the name printed on the device. */
+export type FarEnd = {
+    device: string;
+    port: string;
+    label: string;
+};
+/** What every cable of one entry shares. */
+type Shared = {
+    /** What is between the two ends, such as a carrier's local loop. Both ends get it on their `link`. */
+    through?: string;
+    /** A port's description from its far end. The far device and the far port's label when absent, such as `firewall-1 port6`. */
+    describe?: (far: FarEnd) => string;
+};
+/** A port a cable builds: what it is, the LAG it is in, and the other end. */
+type CablePort<L extends string> = {
+    description: string;
+    link: {
+        device: string;
+        port: string;
+        through?: string;
+    };
+    lag?: L;
+};
+/** Ports for both ends of the cables between two of our devices, each cable written once. */
+export declare class Cables {
+    /**
+     * One cable, both ends. Spread each end into its device's `ports`:
+     *
+     * ```ts
+     * const uplink = Cables.link({ a: { device: "router-1", platform: "routeros", model: "CCR2216-1G-12XS-2XQ", port: "25g-1" }, b: { ... } });
+     * // router-1: ports: { ...uplink.a }
+     * ```
+     */
+    static link<const PA extends PlatformName, const MA extends ModelName<PA>, const NA extends PortName<PA, MA>, const PB extends PlatformName, const MB extends ModelName<PB>, const NB extends PortName<PB, MB>>(spec: Shared & {
+        a: CableEnd<PA, MA> & {
+            port: NA;
+        };
+        b: CableEnd<PB, MB> & {
+            port: NB;
+        };
+    }): {
+        a: Record<NA, CablePort<never>>;
+        b: Record<NB, CablePort<never>>;
+    };
+    /**
+     * The cables of a LAG, both ends, from one list read from end A: `{ "25g-1": "10g-2" }` is a cable from A's 25g-1 to B's 10g-2. Each port is a member of its end's LAG. Spread each end into its device's `ports`; the LAG itself stays on each device.
+     */
+    static lag<const PA extends PlatformName, const MA extends ModelName<PA>, const LA extends string, const PB extends PlatformName, const MB extends ModelName<PB>, const LB extends string, const C extends Partial<Record<PortName<PA, MA>, PortName<PB, MB>>>>(spec: Shared & {
+        a: CableEnd<PA, MA> & {
+            lag: LA;
+        };
+        b: CableEnd<PB, MB> & {
+            lag: LB;
+        };
+        cables: C;
+    }): {
+        a: Record<keyof C & string, CablePort<LA>>;
+        b: Record<NonNullable<C[keyof C]> & string, CablePort<LB>>;
+    };
+    /** A port facing `port` on the far device. */
+    private static end;
+}
+export {};

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

@@ -1,10 +1,14 @@
 export { Bgp } from "./bgp.js";
-export type { CommunityScheme, SanityLengths } from "./bgp.js";
+export type { Announced, CommunityScheme, DefaultOnlyOptions, LearnOptions, SanityLengths } from "./bgp.js";
+export { Cables } from "./cables.js";
+export type { CableEnd, FarEnd } from "./cables.js";
 export { Checks } from "./checks.js";
 export type { TrustBoundary } from "./checks.js";
 export { Exchange } from "./exchange.js";
 export type { ExchangeMember, InternetExchange } from "./exchange.js";
 export { Filters } from "./filters.js";
 export { RouteServerConfig } from "./route-server.js";
+export { Upstreams } from "./upstreams.js";
+export type { Upstream, UpstreamCatalog, UpstreamPolicies } from "./upstreams.js";
 export type { RouteServer } from "./route-server.js";
 export type { AntiAmplificationOptions } from "./filters.js";

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

@@ -0,0 +1,156 @@
+import type { Exchange as ExchangeLan, Family, FilterRule, Gre, InterfaceAddress, IP, LargeCommunity, Neighbor, NeighborSettings, PolicyRule, Port, Secret, StandardCommunity, Vlan, VlanInterface } from "../schema/index.js";
+import { type Announced } from "./bgp.js";
+/** One network we exchange routes with: a transit we buy, an exchange's route servers, or a peer. */
+export type Upstream = {
+    /** Its name as people write it, for descriptions: `Transit A`. The key when absent. */
+    name?: string;
+    asn: number;
+    /** What it is to us: `provider` for a transit, `rs` for an exchange's route servers, `peer` for a direct session. */
+    role: "provider" | "rs" | "peer";
+    /** Where it lands on our side: a VLAN, our addresses on it, and the switch port it arrives on. A peer over a tunnel, or over an exchange's VLAN, has none. */
+    handoff?: {
+        /** The VLAN's ID. */
+        vlan: number;
+        /** It sends its VLAN tagged: its port gets a native VLAN of its own with this ID, which nothing else is in. Untagged when absent. */
+        native?: number;
+        /** Our addresses on it. `{ address, peer }` for a point-to-point address whose far end is outside its own prefix. */
+        addresses: readonly (InterfaceAddress | {
+            address: InterfaceAddress;
+            peer: IP;
+        })[];
+        /** The switch port it arrives on. */
+        port?: {
+            device: string;
+            port: string;
+            storm_control?: Port<string, string, string, string>["storm_control"];
+        };
+        /** An exchange's LAN, for `circuit peeringdb`. */
+        exchange?: ExchangeLan;
+    };
+    /** A GRE tunnel to it. */
+    tunnel?: {
+        local: IP;
+        remote: IP;
+        addresses: readonly InterfaceAddress[];
+        mtu?: number;
+    };
+    /** Our BGP sessions with it, by name: its address, and ours when it is not the interface's. */
+    sessions: Readonly<Record<string, {
+        address: IP;
+        local_address?: IP;
+    }>>;
+    /** The sessions are more than one hop away, from this address of ours. They share a group. */
+    multihop?: {
+        local_address: IP;
+        families?: readonly Family[];
+        password?: Secret;
+    };
+    /** The most prefixes a session may send, by its family: about twice what it sends. Over it, the session closes until it is cleared. */
+    limits?: {
+        ipv4?: number;
+        ipv6?: number;
+    };
+    /** What we take. Nothing when absent. */
+    import?: {
+        /** Its default route, at this preference. */
+        default?: {
+            local_pref?: number;
+            description?: string;
+        };
+        /** Its routes, through `Bgp.learn`: the `before` rules, sanity, this preference, the tag. Only the default when absent. */
+        learn?: {
+            local_pref?: number;
+            before?: readonly PolicyRule<never, never>[];
+        };
+    };
+    /** Rules of yours in its export, between the community actions and what we announce, such as a prepend. */
+    export?: readonly PolicyRule<never, never>[];
+    /** What we announce to it. Everything else is rejected. */
+    announce: readonly Announced[];
+    /** Drop RFC 1918 sources arriving from it. `privateDrops()` lists the VLANs. */
+    drop_private?: true;
+};
+/** Upstreams by key. The key names everything built from it. */
+export type UpstreamCatalog = Readonly<Record<string, Upstream>>;
+/** How each upstream's policies are written: shared by every upstream of a catalog. */
+export type UpstreamPolicies<P extends string> = {
+    /** A policy holding `Bgp.sanity()` that each import calls. The sanity rules are written in each import when absent. */
+    sanity?: P;
+    /** Where a route came from, by upstream: a community or a rule, such as `communityScheme(...).tag(...)`. Nothing is tagged when absent. */
+    tag?: (key: string, upstream: Upstream) => StandardCommunity | LargeCommunity | PolicyRule<never, never>;
+    /** Rules first in each export, such as `communityScheme(...).actions(upstream.asn)`. */
+    actions?: (key: string, upstream: Upstream) => readonly PolicyRule<never, never>[];
+    /** The source address for routes of its family, one per family. */
+    sources?: readonly IP[];
+};
+type Key<C> = keyof C & string;
+/** The upstreams that land on a VLAN of ours. */
+type Landed<C> = {
+    [K in Key<C>]: C[K] extends {
+        handoff: object;
+    } ? K : never;
+}[Key<C>];
+/** The upstreams that send their VLAN tagged. */
+type Tagged<C> = {
+    [K in Key<C>]: C[K] extends {
+        handoff: {
+            native: number;
+        };
+    } ? K : never;
+}[Key<C>];
+/** The upstreams reached over a tunnel. */
+type Tunneled<C> = {
+    [K in Key<C>]: C[K] extends {
+        tunnel: object;
+    } ? K : never;
+}[Key<C>];
+/** The upstreams whose sessions share a group: an exchange's route servers, or multihop sessions. */
+type Grouped<C> = {
+    [K in Key<C>]: C[K] extends {
+        role: "rs";
+    } | {
+        multihop: object;
+    } ? K : never;
+}[Key<C>];
+/** The upstreams we take routes from. */
+type Importing<C> = {
+    [K in Key<C>]: C[K] extends {
+        import: object;
+    } ? K : never;
+}[Key<C>];
+/** A native VLAN's name. */
+type Native<K extends string> = `${K}-native`;
+/** Each upstream's policies: `TRANSIT_A-IN` and `TRANSIT_A-OUT`. */
+type PolicyName<C> = `${Uppercase<Importing<C>>}-IN` | `${Uppercase<Key<C>>}-OUT`;
+/** The catalog as written, with any key the shape does not have refused, at every level. */
+type Exact<S, T> = T extends readonly unknown[] | string | number | boolean | Secret ? T : {
+    [K in keyof T]: K extends keyof S ? Exact<NonNullable<S[K]>, T[K]> : never;
+};
+/** A network's upstreams written once, and each device's part built from them. */
+export declare class Upstreams {
+    /**
+     * Each upstream written once: its AS, where it lands, its sessions, limits and policy. Everything a device needs is built from it, under names made from each key, so a device that names one is checked:
+     *
+     * - VLAN `<key>`, and `<key>-native` for one that sends its VLAN tagged. The router's interface is `<key>` too, a VLAN interface or a GRE tunnel.
+     * - Policies `<KEY>-IN` and `<KEY>-OUT`; a BGP group `<key>` for an exchange's route servers or multihop sessions.
+     *
+     * On the router: `vlans()`, `interfaces()`, `groups()`, `neighbors()`, `policies({ ... })`, `tunnelRules()`, `addresses()`. On a switch: `vlans(device)`, `ports(device)`, `vlansOn(device)`. For checks and ACLs: `untrusted()`, `natives()`, `privateDrops()`. Lists follow the catalog's order, where order counts on a device.
+     */
+    static define<const C extends UpstreamCatalog>(catalog: C & {
+        [K in keyof C]: Exact<Upstream, C[K]>;
+    }): {
+        vlans: <const D extends string | undefined = undefined>(device?: D) => D extends string ? { [K in Landed<C>]: Vlan; } & { [K in Tagged<C> as Native<K>]: Vlan; } : { [K in Landed<C>]: Vlan; };
+        vlansOn: (device: string) => Landed<C>[];
+        ports: (device: string) => Record<string, Port<`${Tagged<C>}-native` | Landed<C>, never, never, never>>;
+        interfaces: () => { [K in Landed<C>]: VlanInterface<Landed<C>, never>; } & { [K in Tunneled<C>]: Gre<never>; };
+        groups: () => Record<Grouped<C>, NeighborSettings<PolicyName<C>>>;
+        neighbors: () => Record<string, Neighbor<PolicyName<C>, Grouped<C>>>;
+        policies: <const P extends string = never>(options?: UpstreamPolicies<P>) => Record<PolicyName<C>, PolicyRule<P, never>[]>;
+        untrusted: () => (`${Tagged<C>}-native` | Landed<C>)[];
+        natives: () => `${Tagged<C>}-native`[];
+        privateDrops: () => Landed<C>[];
+        tunnelRules: () => FilterRule<never, never>[];
+        addresses: () => IP[];
+    };
+}
+export {};

package/dist/types/platforms/bgp-wait.d.ts

@@ -15,4 +15,10 @@ export declare class BgpWait {
     static until(read: () => Promise<BgpSession[]>, enough: (sessions: BgpSession[]) => boolean, limits: WaitLimits, waiting?: (sessions: BgpSession[]) => void): Promise<BgpSession[]>;
     /** How many of these sessions are established. */
     static upCount(sessions: readonly BgpSession[]): number;
+    /** Sessions closed on their limit within this many minutes of each other are one burst. */
+    static readonly BURST_MINUTES = 5;
+    /**
+     * Groups of two or more sessions closed on their limit within `BURST_MINUTES` of each other, earliest first. Several limits at once is usually a leak upstream, not growth, so raising them is the wrong fix.
+     */
+    static limitBursts(sessions: readonly BgpSession[]): BgpSession[][];
 }

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

@@ -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/routeros/index.d.ts

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.37.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",

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/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;