@takodotid/circuit 0.43.1 → 1.0.0-rc.2

package/src/helpers/bgp.ts

@@ -1,473 +0,0 @@
-import { Address } from "../core/address";
-import type { Community } from "../core/define";
-import type {
-    Device,
-    IP,
-    LargeCommunity,
-    LargeCommunityPattern,
-    PolicyRule,
-    Prefix,
-    StandardCommunity,
-    StandardCommunityPattern,
-} from "../schema";
-
-/** The prefix lengths a BGP import accepts. */
-export type SanityLengths = {
-    /** Shortest and longest IPv4 prefix accepted. /8 to /24 when absent. */
-    ipv4?: { min: number; max: number };
-    /** Shortest and longest IPv6 prefix accepted. /16 to /48 when absent. */
-    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: `{ standard: "64500:100" }` or `{ large: "64500:1:1" }` adds that community, and a rule, such as `communityScheme(...).tag(...)`, is used as it is. */
-    tag?: { standard: StandardCommunity } | { large: 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[];
-    /** End with `{ description: "Nothing else", action: "reject" }`, so the policy takes the default route only. Off by default: any other route goes on to the rules after these. */
-    reject?: boolean;
-};
-
-/** What `Bgp.announce` writes after the accepts. */
-export type AnnounceOptions = {
-    /** End with `{ description: "Nothing else", action: "reject" }`, so nothing else leaves. On by default: it stops a route leak when the reject is forgotten. Turn it off for an export that adds rules after these. */
-    reject?: boolean;
-};
-
-/** Kinds of neighbor and the number each is tagged with, such as `{ transit: 1, customer: 3 }`. */
-export type CommunityClasses = Readonly<Record<string, number>>;
-
-/**
- * A BGP community scheme of large communities, `asn:function:parameter`, in the style of RFC 8195. Each field names the function number your network uses for it; leave out what your network does not offer.
- *
- * The type parameters keep the exact numbers you write, so the communities `Bgp.communityScheme` gives back show them in the editor: Asn your AS, LearnedFrom the function of `learned_from`, Classes its classes.
- */
-export type CommunityScheme<
-    Asn extends number = number,
-    LearnedFrom extends number = number,
-    Classes extends CommunityClasses = CommunityClasses,
-> = {
-    /** Your AS. It is the first part of every community. */
-    asn: Asn;
-    /** Set on import: the kind of neighbor a route came from, `asn:function:class`. */
-    learned_from?: { function: LearnedFrom; classes: Classes };
-    /** Set on import: the site a route was learned at, `asn:function:site`. `sites` names the sites, for the catalogue. */
-    learned_at?: { function: number; sites?: Readonly<Record<number, string>> };
-    /** Set on import: the AS a route was learned from, `asn:function:asn`. */
-    learned_from_as?: number;
-    /** A neighbor asks: do not announce the route to an AS, `asn:function:asn`, or to anyone, `asn:function:0`. */
-    do_not_announce?: number;
-    /** A neighbor asks: prepend toward an AS once, twice or three times, `asn:function:asn`. */
-    prepend?: { once?: number; twice?: number; three_times?: number };
-    /**
-     * A neighbor asks: drop all traffic to this route, `asn:function:0`, usually one address under attack. Your router drops it. An upstream whose own blackhole community you know (`communities.blackhole` on the neighbor you pass to `actions`) receives the route with it and drops the traffic too; any other never receives the route.
-     */
-    blackhole?: { function: number };
-};
-
-/** The communities another network offers us, as its NOC gives them: what it does with a route we send it. */
-export type NeighborCommunities = {
-    /** It drops traffic to a route we send it with this community. */
-    blackhole?: StandardCommunity | LargeCommunity;
-    /** It does not pass a route we send it with this community to the AS given, such as an exchange's route servers' `rs-asn:0:peer-asn`. */
-    do_not_announce_to?: (asn: number) => StandardCommunity | LargeCommunity;
-};
-
-/** A neighbor an export goes to: its AS, or its AS and the communities it offers. */
-export type ExportNeighbor = number | { asn: number; communities?: NeighborCommunities };
-
-/** 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, 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],
-        ["twice", 2],
-        ["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 };
-        const ipv6 = lengths.ipv6 ?? { min: 16, max: 48 };
-
-        return [
-            {
-                description: `IPv4 shorter than /${ipv4.min}`,
-                match: { family: "ipv4", prefix_length: { max: ipv4.min - 1 } },
-                action: "reject",
-            },
-            {
-                description: `IPv4 longer than /${ipv4.max}`,
-                match: { family: "ipv4", prefix_length: { min: ipv4.max + 1 } },
-                action: "reject",
-            },
-            {
-                description: `IPv6 shorter than /${ipv6.min}`,
-                match: { family: "ipv6", prefix_length: { max: ipv6.min - 1 } },
-                action: "reject",
-            },
-            {
-                description: `IPv6 longer than /${ipv6.max}`,
-                match: { family: "ipv6", prefix_length: { min: ipv6.max + 1 } },
-                action: "reject",
-            },
-            { description: "RPKI invalid", match: { rpki: "invalid" }, action: "reject" },
-        ];
-    }
-
-    /**
-     * An export that announces each prefix, at exactly its length. It returns, in order:
-     *
-     * 1. `{ description, match: { prefix }, action: "accept" }` for each prefix;
-     * 2. `{ description: "Nothing else", action: "reject" }`, the unconditional reject `Checks.exportsEndInReject` looks for.
-     *
-     * The reject is there by default, so a forgotten one can't leak routes. `{ reject: false }` leaves it out, for an export that adds rules after these and ends in a reject of its own.
-     */
-    static announce(prefixes: readonly Announced[], options: AnnounceOptions = {}): PolicyRule<never, never>[] {
-        return [
-            ...prefixes.map(({ prefix, description }) => ({
-                ...(description ? { description } : {}),
-                match: { prefix },
-                action: "accept" as const,
-            })),
-            ...(options.reject === false ? [] : [Bgp.NOTHING_ELSE]),
-        ];
-    }
-
-    /** The reject that ends a policy: nothing else gets through. */
-    private static readonly NOTHING_ELSE: PolicyRule<never, never> = { description: "Nothing else", action: "reject" };
-
-    /**
-     * An import policy that takes a neighbor's routes. It returns these rules, in order, each only when its option is given:
-     *
-     * 1. the `before` rules, as written;
-     * 2. `{ call: sanity }`, or the rules of `Bgp.sanity()` written in when `sanity` is left out;
-     * 3. `{ set: { preferred_source: source } }` for each of `sources`, one per family;
-     * 4. `{ set: { local_pref } }`;
-     * 5. the tag: `{ description: "Tag 64500:1:1", set: { add_large_communities: ["64500:1:1"] } }` for `{ large: "64500:1:1" }`, `add_communities` for `{ standard }`, or the rule given;
-     * 6. `{ action: "accept" }`.
-     *
-     * So `Bgp.learn({ sanity: "SANITY", local_pref: 200, tag: { large: "64500:1:1" } })` is
-     * `[{ call: "SANITY" }, { set: { local_pref: 200 } }, { description: "Tag 64500:1:1", set: { add_large_communities: ["64500:1:1"] } }, { action: "accept" }]`.
-     *
-     * FortiOS refuses it: a route map stops at the first rule that matches, so it can't hold rules 3 to 5, which change a route and go on; and its sanity rules match RPKI, which FortiOS doesn't have. `validate` names each such rule. On FortiOS, write the import by hand with what rules 3 to 5 set in the rule that accepts.
-     */
-    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 ? [] : ["standard" in tag ? Bgp.adding(tag.standard) : "large" in tag ? Bgp.adding(tag.large) : tag]),
-            { action: "accept" },
-        ];
-    }
-
-    /**
-     * Import rules that take the default route from a transit. They are, in order:
-     *
-     * 1. `{ description, match: { prefix: "0.0.0.0/0" }, set: { local_pref, preferred_source }, action: "accept" }`;
-     * 2. the same for `::/0`;
-     * 3. with `{ reject: true }` only, `{ description: "Nothing else", action: "reject" }`.
-     *
-     * Without `reject`, any other route goes on to the rules after these, so `[...Bgp.defaultOnly(), ...Bgp.learn()]` takes both. Each of `sources` is the source address for the default of its own family; `set` holds only what is given.
-     */
-    static defaultOnly(options: DefaultOnlyOptions = {}): PolicyRule<never, never>[] {
-        const defaults = 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,
-            };
-        });
-
-        return options.reject ? [...defaults, Bgp.NOTHING_ELSE] : defaults;
-    }
-
-    /** 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;
-
-        return Object.entries(bgp?.neighbors ?? {}).map(([name, neighbor]) => {
-            const group = neighbor.group ? bgp?.groups?.[neighbor.group] : undefined;
-
-            return {
-                name,
-                address: neighbor.address,
-                role: neighbor.role ?? group?.role,
-                import: neighbor.import ?? group?.import,
-                export: neighbor.export ?? group?.export,
-            };
-        });
-    }
-
-    /** The prefixes an export policy accepts by name. */
-    static offered(device: Device, policy: string | undefined): Prefix[] {
-        const rules = policy ? (device.policies?.[policy] ?? []) : [];
-        return rules.filter((rule) => rule.action === "accept" && rule.match?.prefix).map((rule) => rule.match!.prefix!);
-    }
-
-    /**
-     * Policy rules and a catalogue from one community scheme, so the communities your routers set, the ones they act on, and the ones you publish never disagree.
-     *
-     * - `tag(neighborClass, neighborAs, { site, trusted })`: one rule for an import policy, `{ description: "Learned from AS<n>", set }`. Its `set` removes your standard communities and your large ones (a `trusted` neighbor loses only the "where it came from" functions, so it keeps its requests: do not announce, prepend, blackhole), then adds `learned_from`, `learned_at` and `learned_from_as` where the scheme has them. `site` is needed when the scheme has `learned_at`.
-     * Each export helper takes the neighbor: its AS, or `{ asn, communities }` with the communities it offers, such as an `Upstreams.catalog` entry.
-     *
-     * - `actions(neighbor)`: the rules for an export policy toward one neighbor, before the rules that accept. They are `[...blackholeExport(n), ...rejectDoNotAnnounce(n), ...prepends(n), stripOurs()]`; toward a neighbor that takes blackholes (`communities.blackhole`), `rejectDoNotAnnounce(n)` comes first, so a route asked not to go there is never passed on as a blackhole.
-     * - `blackholeExport(neighbor)`: a blackholed route goes no further, `Blackholed here, never announced`, unless the neighbor has `communities.blackhole`: then it is passed on with it, so the neighbor drops the traffic too. Nothing without `blackhole` in the scheme.
-     * - `rejectDoNotAnnounce(neighbor)`: rejects a route asked not to be announced anywhere, then one asked not to be announced to this neighbor. Nothing without `do_not_announce`.
-     * - `prepends(neighbor)`: prepends once, twice or three times toward this neighbor, where a route asks. Nothing without `prepend`.
-     * - `stripOurs()`: one rule removing every community of yours, `Our communities stay inside our network`.
-     * - `blackhole(prefixSets)`: rules for the import policy of a neighbor you trust with blackholes, before anything that rejects long prefixes. They take a route the neighbor asked to blackhole, but only inside `prefixSets`, its own space, and drop traffic to it here. One rule per set, so one call covers both families.
-     * - `catalogue`: every community, for `communities` in `defineNetwork`.
-     * - `community(fn, parameter)`: one community of yours, for a rule of your own.
-     * - `learned_from`: the community each class is tagged with, by class name, such as `learned_from.customer`.
-     */
-    static communityScheme<
-        const Asn extends number,
-        const LearnedFrom extends number = number,
-        const Classes extends CommunityClasses = {},
-    >(scheme: CommunityScheme<Asn, LearnedFrom, Classes>) {
-        type Class = ClassName<Classes>;
-
-        const { asn } = scheme;
-
-        /** One community of yours, `asn:fn:parameter`. */
-        const community = <const Fn extends number, const Parameter extends number>(fn: Fn, parameter: Parameter) =>
-            `${asn}:${fn}:${parameter}` as `${Asn}:${Fn}:${Parameter}`;
-
-        /** Every value of one of your functions, `asn:fn:*`, for a list of communities to remove. */
-        const anyOf = (fn: number): LargeCommunityPattern => `${asn}:${fn}:*`;
-
-        /** A line of the catalogue, where `nnn` stands for any number. */
-        const written = (fn: number, parameter: number | string) => `${asn}:${fn}:${parameter}`;
-
-        const ours = {
-            standard: [`${asn}:*`] as StandardCommunityPattern[],
-            large: [`${asn}:*:*`] as LargeCommunityPattern[],
-        };
-
-        const learnedFrom = Object.fromEntries(
-            Object.entries<number>(scheme.learned_from?.classes ?? {}).map(([name, value]) => [
-                name,
-                community(scheme.learned_from!.function, value),
-            ])
-        ) as { readonly [Name in keyof Classes]: `${Asn}:${LearnedFrom}:${Classes[Name]}` };
-
-        const information = [scheme.learned_from?.function, scheme.learned_at?.function, scheme.learned_from_as].filter(
-            (fn): fn is number => fn !== undefined
-        );
-
-        const tag = (
-            neighborClass: Class,
-            neighborAs: number,
-            options: { site?: number; trusted?: boolean } = {}
-        ): PolicyRule<never, never> => {
-            const { site, trusted = false } = options;
-            if (scheme.learned_at && site === undefined)
-                throw new Error(`Bgp.communityScheme: tag for AS${neighborAs} needs a site, for learned_at`);
-
-            return {
-                description: `Learned from AS${neighborAs}`,
-                set: {
-                    remove_communities: ours.standard,
-                    // A trusted neighbor keeps its requests and loses only the "where it came from" tags, which are ours to set. Anyone else loses every community of ours.
-                    remove_large_communities: trusted ? information.map(anyOf) : ours.large,
-                    add_large_communities: [
-                        ...(scheme.learned_from
-                            ? [community(scheme.learned_from.function, scheme.learned_from.classes[neighborClass])]
-                            : []),
-                        ...(scheme.learned_at ? [community(scheme.learned_at.function, site!)] : []),
-                        ...(scheme.learned_from_as !== undefined ? [community(scheme.learned_from_as, neighborAs)] : []),
-                    ],
-                },
-            };
-        };
-
-        const blackhole = <S extends string>(prefixSets: readonly S[]): PolicyRule<never, S>[] => {
-            const fn = scheme.blackhole?.function;
-            if (fn === undefined) throw new Error("Bgp.communityScheme: blackhole needs a function number in the scheme");
-
-            return prefixSets.map((prefixSet) => ({
-                description: "Blackhole, asked by the neighbor",
-                match: { large_community: community(fn, 0), prefix_set: prefixSet },
-                set: { blackhole: true },
-                action: "accept",
-            }));
-        };
-
-        /** The neighbor's AS. */
-        const asnOf = (neighbor: ExportNeighbor) => (typeof neighbor === "number" ? neighbor : neighbor.asn);
-
-        /** The neighbor's own blackhole community, when it takes blackholes from us. */
-        const passOnTo = (neighbor: ExportNeighbor) => (typeof neighbor === "number" ? undefined : neighbor.communities?.blackhole);
-
-        const blackholeExport = (neighbor: ExportNeighbor): PolicyRule<never, never>[] => {
-            if (scheme.blackhole === undefined) return [];
-
-            const passOn = passOnTo(neighbor);
-            const match = { large_community: community(scheme.blackhole.function, 0) };
-            if (!passOn) return [{ description: "Blackholed here, never announced", match, action: "reject" }];
-
-            const large = passOn.split(":").length === 3;
-            return [
-                {
-                    description: `Blackhole passed on to AS${asnOf(neighbor)}`,
-                    match,
-                    set: {
-                        remove_communities: ours.standard,
-                        remove_large_communities: ours.large,
-                        ...(large
-                            ? { add_large_communities: [passOn as LargeCommunity] }
-                            : { add_communities: [passOn as StandardCommunity] }),
-                    },
-                    action: "accept",
-                },
-            ];
-        };
-
-        const rejectDoNotAnnounce = (neighbor: ExportNeighbor): PolicyRule<never, never>[] => {
-            const neighborAs = asnOf(neighbor);
-            const fn = scheme.do_not_announce;
-            if (fn === undefined) return [];
-
-            return [
-                { description: "Asked not to be announced anywhere", match: { large_community: community(fn, 0) }, action: "reject" },
-                {
-                    description: `Asked not to be announced to AS${neighborAs}`,
-                    match: { large_community: community(fn, neighborAs) },
-                    action: "reject",
-                },
-            ];
-        };
-
-        const prepends = (neighbor: ExportNeighbor): PolicyRule<never, never>[] =>
-            Bgp.PREPENDS.flatMap(([name, times]) => {
-                const neighborAs = asnOf(neighbor);
-                const fn = scheme.prepend?.[name];
-                if (fn === undefined) return [];
-
-                return [
-                    {
-                        description: `Asked to prepend ${name.replace("_", " ")} to AS${neighborAs}`,
-                        match: { large_community: community(fn, neighborAs) },
-                        set: { prepend: times },
-                    },
-                ];
-            });
-
-        const stripOurs = (): PolicyRule<never, never> => ({
-            description: "Our communities stay inside our network",
-            set: { remove_communities: ours.standard, remove_large_communities: ours.large },
-        });
-
-        // A route asked not to be announced to a neighbor is never passed on to it as a blackhole either; where nothing is passed on, both only reject.
-        const actions = (neighbor: ExportNeighbor): PolicyRule<never, never>[] =>
-            passOnTo(neighbor)
-                ? [...rejectDoNotAnnounce(neighbor), ...blackholeExport(neighbor), ...prepends(neighbor), stripOurs()]
-                : [...blackholeExport(neighbor), ...rejectDoNotAnnounce(neighbor), ...prepends(neighbor), stripOurs()];
-
-        const catalogue: Community[] = [
-            ...Object.entries<number>(scheme.learned_from?.classes ?? {}).map(([name, value]) => ({
-                community: written(scheme.learned_from!.function, value),
-                description: `Learned from ${Bgp.article(name)}`,
-            })),
-            ...(scheme.learned_at
-                ? [
-                      ...Object.entries(scheme.learned_at.sites ?? {}).map(([site, name]) => ({
-                          community: written(scheme.learned_at!.function, site),
-                          description: `Learned in ${name}`,
-                      })),
-                      { community: written(scheme.learned_at.function, "nnn"), description: "Learned at site $0" },
-                  ]
-                : []),
-            ...(scheme.learned_from_as !== undefined
-                ? [{ community: written(scheme.learned_from_as, "nnn"), description: "Learned from AS$0" }]
-                : []),
-            ...(scheme.do_not_announce !== undefined
-                ? [
-                      { community: written(scheme.do_not_announce, 0), description: "Do not announce to anyone" },
-                      { community: written(scheme.do_not_announce, "nnn"), description: "Do not announce to AS$0" },
-                  ]
-                : []),
-            ...Bgp.PREPENDS.flatMap(([name]) => {
-                const fn = scheme.prepend?.[name];
-                return fn === undefined
-                    ? []
-                    : [{ community: written(fn, "nnn"), description: `Prepend ${name.replace("_", " ")} to AS$0` }];
-            }),
-            ...(scheme.blackhole !== undefined
-                ? [
-                      {
-                          community: written(scheme.blackhole.function, 0),
-                          description: `Blackhole: dropped in AS${asn}, and by the upstreams that take it`,
-                      },
-                  ]
-                : []),
-        ];
-
-        return {
-            community,
-            learned_from: learnedFrom,
-            tag,
-            actions,
-            blackholeExport,
-            rejectDoNotAnnounce,
-            prepends,
-            stripOurs,
-            blackhole,
-            catalogue,
-        };
-    }
-
-    /** A word with its article: "a customer", "an upstream". */
-    private static article(word: string): string {
-        return /^[aeiou]/i.test(word) ? `an ${word}` : `a ${word}`;
-    }
-}

package/src/helpers/cables.ts

@@ -1,74 +0,0 @@
-import { Catalog } from "../platforms/catalog";
-
-/** The far end of a port, for a description of your own: the device, its port by Circuit's name, and the port as printed on the device when that end names its platform and model. */
-export type FarEnd = { device: string; port: string; label?: string };
-
-/** One end of a cable entry: the device, and its platform and model if a description should name its ports as printed on it. */
-type End = { device: string; platform?: string; model?: 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, such as `(far) => \`${far.device} ${far.label}\``. No description when absent. */
-    describe?: (far: FarEnd) => string;
-};
-
-/** A port a cable builds: the other end, the LAG it is in, and a description when `describe` gives one. */
-type CablePort<L extends string> = {
-    link: { device: string; port: string; through?: string };
-    lag?: L;
-    description?: string;
-};
-
-/** Ports for both ends of the cables between two of our devices, each cable written once. */
-export class Cables {
-    /**
-     * One cable, both ends. Spread each end into its device's `ports`:
-     *
-     * ```ts
-     * const uplink = Cables.link({ a: { device: "router-1", port: "25g-1" }, b: { device: "switch-1", port: "10g-48" } });
-     * // router-1: ports: { ...uplink.a }
-     * ```
-     */
-    static link<const NA extends string, const NB extends string>(spec: Shared & { a: End & { port: NA }; b: End & { port: NB } }) {
-        return {
-            a: { [spec.a.port]: Cables.end(spec, spec.b, spec.b.port) } as Record<NA, CablePort<never>>,
-            b: { [spec.b.port]: Cables.end(spec, spec.a, spec.a.port) } as 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 LA extends string, const LB extends string, const C extends Readonly<Record<string, string>>>(
-        spec: Shared & { a: End & { lag: LA }; b: End & { lag: LB }; cables: C }
-    ) {
-        const pairs = Object.entries(spec.cables);
-
-        const taken = new Map<string, string>();
-        for (const [near, far] of pairs) {
-            const other = taken.get(far);
-            if (other) throw new Error(`Cables.lag: ${spec.b.device} ${far} is cabled to both ${other} and ${near} on ${spec.a.device}`);
-            taken.set(far, near);
-        }
-
-        const a = Object.fromEntries(pairs.map(([near, far]) => [near, { ...Cables.end(spec, spec.b, far), lag: spec.a.lag }]));
-        const b = Object.fromEntries(pairs.map(([near, far]) => [far, { ...Cables.end(spec, spec.a, near), lag: spec.b.lag }]));
-
-        return {
-            a: a as Record<keyof C & string, CablePort<LA>>,
-            b: b as Record<C[keyof C], CablePort<LB>>,
-        };
-    }
-
-    /** A port facing `port` on the far end. */
-    private static end(shared: Shared, far: End, port: string): CablePort<never> {
-        const label = far.platform && far.model ? Catalog.spell(far.platform, far.model, port) : undefined;
-
-        return {
-            link: { device: far.device, port, ...(shared.through ? { through: shared.through } : {}) },
-            ...(shared.describe ? { description: shared.describe({ device: far.device, port, ...(label ? { label } : {}) }) } : {}),
-        };
-    }
-}