@takodotid/circuit 0.43.1 → 1.0.0-rc.2

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

@@ -1,27 +0,0 @@
-import { Client, type ClientChannel } from "ssh2";
-import type { Device } from "../schema/index.js";
-export type Login = {
-    host: string;
-    port?: number;
-    user: string;
-    password: string;
-    /** Host key algorithms to accept, for a device that negotiates one it then signs wrongly. */
-    hostKeys?: string[];
-};
-export declare class Ssh {
-    /** The address SSH reaches a device at. A device without one is reached only through its console. */
-    static hostOf(device: Device): string;
-    /** Open a session. */
-    static connect(login: Login): Promise<Client>;
-    /** Run one command and return what it printed, stderr included. */
-    static exec(client: Client, command: string, timeout?: number): Promise<string>;
-    /** An interactive shell, for platforms that take configuration only there. */
-    static shell(client: Client, columns?: number, rows?: number): Promise<ClientChannel>;
-    /** Collect output until `done` holds, then wait `settle` for stragglers, or give up at `timeout`. */
-    static readUntil(channel: ClientChannel, done: (output: string) => boolean, timeout: number, settle?: number): Promise<string>;
-    /** Send one line into an interactive shell and collect output until it goes quiet for `settle`. */
-    static send(channel: ClientChannel, line: string, timeout?: number, settle?: number): Promise<string>;
-    static sleep(milliseconds: number): Promise<unknown>;
-    /** Write a file to the device over SFTP. */
-    static upload(client: Client, path: string, content: string | Buffer): Promise<void>;
-}

package/src/cli/graph-format.ts

@@ -1,91 +0,0 @@
-// What `circuit graph` prints: the graph of the network with what `validate` found and how each device compares with its last snapshot, as Mermaid, DOT or JSON.
-
-import { Topology, type Annotated, type GraphNode } from "../core/topology";
-
-export class GraphFormat {
-    /** `error` when validate found an error on the device, `warning` for a warning or a difference from its snapshot. */
-    static mark(graph: Annotated, node: GraphNode): "error" | "warning" | undefined {
-        if (node.kind !== "device") return undefined;
-
-        const findings = graph.findings.filter((finding) => finding.device && Topology.deviceId(finding.device) === node.id);
-        if (findings.some((finding) => finding.level === "error")) return "error";
-
-        const drift = graph.drift[node.label]?.status;
-        if (findings.length || drift === "differs" || drift === "cannot plan") return "warning";
-
-        return undefined;
-    }
-
-    /** Mermaid, which GitHub draws wherever Markdown is shown. */
-    static mermaid(graph: Annotated): string {
-        const ids = new Map(graph.nodes.map((node, index) => [node.id, `n${index}`]));
-        // Lines of text, each escaped, as one quoted label.
-        const text = (...lines: string[]) =>
-            `"${lines.map((line) => line.replace(/"/g, "#quot;").replace(/</g, "#lt;").replace(/>/g, "#gt;")).join("<br/>")}"`;
-
-        const shapes: Record<GraphNode["kind"], (label: string) => string> = {
-            device: (label) => `[${label}]`,
-            segment: (label) => `([${label}])`,
-            outside: (label) => `{{${label}}}`,
-        };
-
-        const lines = ["graph LR"];
-
-        for (const node of graph.nodes) {
-            const label = node.kind === "device" ? text(node.label, node.detail[0] ?? "") : text(node.label);
-            lines.push(`    ${ids.get(node.id)}${shapes[node.kind](label)}`);
-        }
-
-        for (const edge of graph.edges) {
-            const arrow = edge.oneSided ? "-.-" : "---";
-            lines.push(`    ${ids.get(edge.from)} ${arrow}|${text(edge.label)}| ${ids.get(edge.to)}`);
-        }
-
-        lines.push(
-            "    classDef error stroke:#d1242f,stroke-width:3px",
-            "    classDef warning stroke:#bf8700,stroke-width:3px",
-            "    classDef outside stroke-dasharray:4 3"
-        );
-
-        for (const node of graph.nodes) {
-            const mark = GraphFormat.mark(graph, node) ?? (node.kind === "outside" ? "outside" : undefined);
-            if (mark) lines.push(`    class ${ids.get(node.id)} ${mark}`);
-        }
-
-        return lines.join("\n") + "\n";
-    }
-
-    /** DOT, which Graphviz turns into an image: `circuit graph --format=dot | dot -Tsvg > network.svg`. */
-    static dot(graph: Annotated): string {
-        const text = (value: string) => `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-        const colors = { error: "#d1242f", warning: "#bf8700" };
-
-        const shapes: Record<GraphNode["kind"], string> = {
-            device: "shape=box, style=rounded",
-            segment: "shape=ellipse",
-            outside: "shape=box, style=dashed",
-        };
-
-        const lines = [
-            "graph network {",
-            "    rankdir=LR;",
-            '    node [fontname="Helvetica"];',
-            '    edge [fontname="Helvetica", fontsize=10];',
-        ];
-
-        for (const node of graph.nodes) {
-            const label = node.kind === "device" ? `${node.label}\n${node.detail[0] ?? ""}` : node.label;
-            const mark = GraphFormat.mark(graph, node);
-            const color = mark ? `, color=${text(colors[mark])}, penwidth=2` : "";
-            lines.push(`    ${text(node.id)} [label=${text(label)}, ${shapes[node.kind]}${color}];`);
-        }
-
-        for (const edge of graph.edges) {
-            const style = edge.oneSided ? ", style=dashed" : "";
-            lines.push(`    ${text(edge.from)} -- ${text(edge.to)} [label=${text(edge.label)}${style}];`);
-        }
-
-        lines.push("}");
-        return lines.join("\n") + "\n";
-    }
-}

package/src/cli/new.ts

@@ -1,234 +0,0 @@
-// `circuit new`: start a project from one of the patterns in templates/. In a terminal it asks what it needs; the same answers can be given as options, for a script or an AI agent.
-
-import { spawnSync } from "node:child_process";
-import { cpSync, existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, relative, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import * as prompts from "@clack/prompts";
-
-type Manager = keyof typeof Scaffold.MANAGERS;
-
-type Pattern = keyof typeof Scaffold.PATTERNS;
-
-/** The answers given as options. A question is asked only for an answer missing here. */
-export type ScaffoldOptions = {
-    pattern?: string;
-    asn?: string;
-    onePassword?: boolean;
-    use?: string;
-    install: boolean;
-};
-
-export class Scaffold {
-    private static readonly ROOT = Scaffold.packageRoot();
-    private static readonly TEMPLATES = join(Scaffold.ROOT, "templates");
-    private static readonly CIRCUIT = JSON.parse(readFileSync(join(Scaffold.ROOT, "package.json"), "utf8"));
-
-    /** How each package manager installs and runs. The templates are written for npm; the others are swapped in. */
-    static readonly MANAGERS = {
-        npm: { install: "npm install", run: "npx circuit", types: "node" },
-        pnpm: { install: "pnpm install", run: "pnpm circuit", types: "node" },
-        bun: { install: "bun install", run: "bun circuit", types: "bun" },
-    } as const;
-
-    static readonly PATTERNS = {
-        "single-site": {
-            title: "A single site",
-            fits: "a home, an office or an internal network: a router and a switch, no BGP",
-            asn: false,
-        },
-        "edge-router": { title: "An edge router", fits: "your own AS number, with an IP transit and an internet exchange", asn: true },
-        colocation: {
-            title: "Colocation with tenants",
-            fits: "a provider whose customers each get their own VLANs, addresses and ports",
-            asn: true,
-        },
-    } as const;
-
-    /** The AS number the templates use, reserved for documentation by RFC 5398. */
-    private static readonly EXAMPLE_ASN = "64500";
-
-    /** Circuit's own directory: this file runs from src/cli/ in Bun, and from dist/ once built. */
-    private static packageRoot(): string {
-        let directory = dirname(fileURLToPath(import.meta.url));
-
-        while (!existsSync(join(directory, "templates"))) {
-            const parent = dirname(directory);
-            if (parent === directory) throw new Error("Circuit's templates are missing from its package");
-            directory = parent;
-        }
-
-        return directory;
-    }
-
-    /** The package manager that started this, from what it says about itself, such as `pnpm/9.1.0 npm/? node/v22`. */
-    private static detectManager(): Manager {
-        const agent = process.env.npm_config_user_agent ?? "";
-        if (agent.startsWith("pnpm/")) return "pnpm";
-        if (agent.startsWith("bun/") || process.versions.bun) return "bun";
-        return "npm";
-    }
-
-    private static fail(message: string): never {
-        console.error(message);
-        process.exit(1);
-    }
-
-    /** Every file under a directory, relative to it. */
-    private static filesIn(directory: string): string[] {
-        return readdirSync(directory, { recursive: true, withFileTypes: true })
-            .filter((entry) => entry.isFile())
-            .map((entry) => relative(directory, join(entry.parentPath, entry.name)));
-    }
-
-    /** Why a project cannot be created in this directory, or undefined when it can. */
-    private static notEmpty(directory: string): string | undefined {
-        const target = resolve(process.cwd(), directory);
-        return existsSync(target) && readdirSync(target).length ? `${target} is not empty` : undefined;
-    }
-
-    /** The answer to a question in a terminal, or the fallback when nobody is there to answer. Cancelling a question ends the run. */
-    private static async ask<T>(question: () => Promise<NoInfer<T> | symbol>, fallback: T): Promise<T> {
-        if (process.stdin.isTTY !== true) return fallback;
-
-        const answer = await question();
-        if (prompts.isCancel(answer)) {
-            prompts.cancel("Nothing created.");
-            process.exit(1);
-        }
-
-        return answer as T;
-    }
-
-    static async create(directoryArgument: string | undefined, options: ScaffoldOptions): Promise<void> {
-        const directory =
-            directoryArgument ??
-            (await Scaffold.ask(
-                () =>
-                    prompts.text({
-                        message: "Directory for the project",
-                        placeholder: "my-network",
-                        defaultValue: "my-network",
-                        validate: (value) => Scaffold.notEmpty(value || "my-network"),
-                    }),
-                "my-network"
-            ));
-
-        const notEmpty = Scaffold.notEmpty(directory);
-        if (notEmpty) Scaffold.fail(notEmpty);
-        const target = resolve(process.cwd(), directory);
-
-        const names = Object.keys(Scaffold.PATTERNS) as Pattern[];
-        const pattern =
-            options.pattern ??
-            (await Scaffold.ask(
-                () =>
-                    prompts.select({
-                        message: "Which is closest to your network?",
-                        options: names.map((name) => ({
-                            value: name,
-                            label: Scaffold.PATTERNS[name].title,
-                            hint: Scaffold.PATTERNS[name].fits,
-                        })),
-                    }),
-                names[0]!
-            ));
-        if (!Object.hasOwn(Scaffold.PATTERNS, pattern)) Scaffold.fail(`no pattern ${pattern}; there are ${names.join(", ")}`);
-        const chosen = Scaffold.PATTERNS[pattern as Pattern];
-
-        let asn = options.asn;
-        if (!asn && chosen.asn) {
-            asn = await Scaffold.ask(
-                () =>
-                    prompts.text({
-                        message: "Your AS number, or press enter to keep the documentation example",
-                        placeholder: Scaffold.EXAMPLE_ASN,
-                        defaultValue: Scaffold.EXAMPLE_ASN,
-                        validate: (value) => (!value || /^\d+$/.test(value) ? undefined : `${value} is not an AS number`),
-                    }),
-                Scaffold.EXAMPLE_ASN
-            );
-        }
-        if (asn && !/^\d+$/.test(asn)) Scaffold.fail(`${asn} is not an AS number`);
-
-        const manager = options.use ?? Scaffold.detectManager();
-        if (!Object.hasOwn(Scaffold.MANAGERS, manager)) {
-            Scaffold.fail(`no package manager ${manager}; there are ${Object.keys(Scaffold.MANAGERS).join(", ")}`);
-        }
-        const { install, run, types } = Scaffold.MANAGERS[manager as Manager];
-
-        const onePassword =
-            options.onePassword ||
-            (await Scaffold.ask(() => prompts.confirm({ message: "Keep the secrets in 1Password?", initialValue: false }), false));
-
-        // The pattern's files, then what every project has. npm leaves out a file named .gitignore, so it travels without the dot.
-        cpSync(join(Scaffold.TEMPLATES, pattern), target, { recursive: true });
-        cpSync(join(Scaffold.TEMPLATES, "project"), target, { recursive: true });
-        renameSync(join(target, "gitignore"), join(target, ".gitignore"));
-
-        // What the templates say about npm, said for the package manager in use.
-        for (const file of ["AGENTS.md", "README.md", "tsconfig.json"]) {
-            const path = join(target, file);
-            const text = readFileSync(path, "utf8")
-                .replaceAll("npx circuit", run)
-                .replaceAll("npm install", install)
-                .replaceAll('"types": ["node"]', `"types": ["${types}"]`);
-            writeFileSync(path, text);
-        }
-
-        const sources = Scaffold.filesIn(target).filter((file) => file.endsWith(".ts"));
-        const secrets = new Set<string>();
-
-        for (const file of sources) {
-            const path = join(target, file);
-            let text = readFileSync(path, "utf8");
-
-            if (asn && asn !== Scaffold.EXAMPLE_ASN) text = text.replaceAll(new RegExp(`\\b${Scaffold.EXAMPLE_ASN}\\b`, "g"), asn);
-            for (const [, name] of text.matchAll(/secret\("([A-Z0-9_]+)"\)/g)) secrets.add(name!);
-
-            writeFileSync(path, text);
-        }
-
-        const env = [
-            "# Secrets for Circuit. Never commit this file.",
-            "# A value is the secret itself, or a 1Password reference, op://vault/item/field, read with the 1Password CLI.",
-            "# Put quotes around a value that has a # in it: without them, # starts a comment.",
-            ...[...secrets].sort().map((name) => (onePassword ? `${name}=op://Network/${name}/password` : `${name}=`)),
-            "",
-        ];
-        writeFileSync(join(target, ".env"), env.join("\n"));
-
-        const name = basename(target)
-            .toLowerCase()
-            .replace(/[^a-z0-9-]+/g, "-");
-        const packageJson = {
-            name,
-            private: true,
-            type: "module",
-            dependencies: { "@takodotid/circuit": Scaffold.CIRCUIT.version },
-            devDependencies: { [`@types/${types}`]: Scaffold.CIRCUIT.devDependencies[`@types/${types}`] },
-        };
-        writeFileSync(join(target, "package.json"), JSON.stringify(packageJson, null, 4) + "\n");
-
-        if (options.install) {
-            // npm and pnpm are scripts on Windows, which only a shell runs.
-            const result = spawnSync(install, { cwd: target, stdio: "inherit", shell: true });
-            if (result.status !== 0) console.log(`${install} failed; run it again in the project.`);
-        }
-
-        const steps = [
-            `cd ${directory}`,
-            onePassword
-                ? `Point each line of .env at the item that holds it in 1Password, then run: ${run} secrets`
-                : `Fill in each password in .env, then run: ${run} secrets`,
-            "Change the names, addresses and ports in the device files to your own.",
-            ...(chosen.asn && (!asn || asn === Scaffold.EXAMPLE_ASN) ? ["Put your own AS number in routing.ts."] : []),
-            `${run} validate`,
-            `${run} snapshot, then ${run} diff, to see what would change on each device`,
-        ];
-
-        console.log(`\nCreated ${directory} from the pattern "${chosen.title}".\n\nNext:`);
-        steps.forEach((step, index) => console.log(`  ${index + 1}. ${step}`));
-        console.log(`\nWhat each file does: https://circuit.tako.id/patterns/${pattern}`);
-    }
-}

package/src/core/address-space.ts

@@ -1,320 +0,0 @@
-// Every address the config uses, by prefix, and what is still free: what `circuit addresses` prints. It reads the config only, so an address a device gave out by itself, such as a DHCP lease, is not known.
-
-import type { Device } from "../schema";
-import { Address } from "./address";
-import { Topology } from "./topology";
-
-/** One address or range in a segment, and what holds it. */
-export type Use = {
-    /** An address, or `first-last` for a range. */
-    address: string;
-    what: string;
-};
-
-/** A prefix our devices have addresses in. */
-export type Segment = {
-    prefix: string;
-    uses: Use[];
-    /** How many addresses no one uses, as a number written out, since an IPv6 count does not fit a JavaScript number. */
-    free: string;
-    /** The lowest free address, when there is one. */
-    next?: string;
-};
-
-/** A prefix in use without being a segment: a loopback's address, or a block routed elsewhere. */
-export type Block = {
-    prefix: string;
-    what: string;
-};
-
-/** Space the network owns: a prefix it originates in BGP, or one asked for. Everything in use inside it, and what is free. */
-export type Space = {
-    prefix: string;
-    /** Why it is listed, such as `originated by edge-01`. */
-    owner: string;
-    segments: Segment[];
-    blocks: Block[];
-    /** The fewest prefixes that cover what nothing uses. */
-    free: string[];
-};
-
-export type AddressReport = {
-    spaces: Space[];
-    /** What is in use outside every space. Left out when a prefix is asked for. */
-    elsewhere: { segments: Segment[]; blocks: Block[] };
-};
-
-/** A use as a range of numbers, for counting. */
-type Taken = { first: bigint; last: bigint };
-
-export class AddressSpace {
-    private static isHostRoute(cidr: string): boolean {
-        return Address.split(cidr).len === Address.bits(Address.split(cidr).family);
-    }
-
-    private static numberOf(address: string): bigint {
-        return Address.toNumber(address)!;
-    }
-
-    /** Addresses a segment can give out: IPv4 leaves out the network and broadcast addresses below /31, and IPv6 the subnet-router anycast address. */
-    private static usable(prefix: string): Taken {
-        const { first, last, family } = Address.range(prefix);
-        const { len } = Address.split(prefix);
-
-        if (family === "ipv4" && len <= 30) return { first: first + 1n, last: last - 1n };
-        if (family === "ipv6" && len < 127) return { first: first + 1n, last };
-
-        return { first, last };
-    }
-
-    /** Ranges merged, so overlapping ones count once. */
-    private static merged(ranges: Taken[]): Taken[] {
-        const sorted = [...ranges].sort((a, b) => (a.first < b.first ? -1 : a.first > b.first ? 1 : 0));
-        const result: Taken[] = [];
-
-        for (const range of sorted) {
-            const previous = result.at(-1);
-            if (previous && range.first <= previous.last + 1n) previous.last = range.last > previous.last ? range.last : previous.last;
-            else result.push({ ...range });
-        }
-
-        return result;
-    }
-
-    /** What is inside `within` and not in any of the ranges. */
-    private static gaps(within: Taken, taken: Taken[]): Taken[] {
-        const result: Taken[] = [];
-        let cursor = within.first;
-
-        for (const range of AddressSpace.merged(taken)) {
-            if (range.last < within.first || range.first > within.last) continue;
-            if (range.first > cursor) result.push({ first: cursor, last: range.first - 1n });
-            if (range.last + 1n > cursor) cursor = range.last + 1n;
-        }
-
-        if (cursor <= within.last) result.push({ first: cursor, last: within.last });
-        return result;
-    }
-
-    /** `12` or, for a count too long to read, `about 2^64`, to the nearest power of two. */
-    private static count(value: bigint): string {
-        if (value <= 1n << 20n) return String(value);
-
-        const power = value.toString(2).length - 1;
-        const nearer = value - (1n << BigInt(power)) >= 1n << BigInt(power - 1) ? power + 1 : power;
-        return `about 2^${nearer}`;
-    }
-
-    private static byAddress(a: Use, b: Use): number {
-        const first = (use: Use) => AddressSpace.numberOf(use.address.split("-")[0]!);
-        return first(a) < first(b) ? -1 : first(a) > first(b) ? 1 : 0;
-    }
-
-    /** IPv4 before IPv6, then by first address. */
-    private static comparePrefixes(a: string, b: string): number {
-        const [ra, rb] = [Address.range(a), Address.range(b)];
-        if (ra.family !== rb.family) return ra.family === "ipv4" ? -1 : 1;
-        return ra.first < rb.first ? -1 : ra.first > rb.first ? 1 : 0;
-    }
-
-    private static byPrefix(a: { prefix: string }, b: { prefix: string }): number {
-        return AddressSpace.comparePrefixes(a.prefix, b.prefix);
-    }
-
-    /** Every address in use, by segment, under the space the network owns. With `within`, only what falls inside that prefix, as the one space. */
-    static report(devices: readonly Device[], within?: string): AddressReport {
-        const segments = new Map<string, { uses: Use[]; taken: Taken[] }>();
-        const blocks: Block[] = [];
-
-        const segmentOf = (address: string) => [...segments.keys()].find((prefix) => Address.contains(prefix, address));
-
-        // Segments come from the addresses on interfaces; a host route, such as a loopback's, is a block of its own.
-        for (const holder of Topology.holders(devices)) {
-            const vrf = holder.device.ports?.[holder.name]?.vrf ?? holder.device.interfaces?.[holder.name]?.vrf;
-            const what = `${holder.device.name} ${holder.name}${vrf ? `, VRF ${vrf}` : ""}`;
-
-            if (AddressSpace.isHostRoute(holder.address) || holder.peer) {
-                blocks.push({ prefix: `${Address.host(holder.address)}/${Address.bits(Address.family(holder.address))}`, what });
-                continue;
-            }
-
-            const prefix = Address.prefixOf(holder.address);
-            const segment = segments.get(prefix) ?? { uses: [], taken: [] };
-            const value = AddressSpace.numberOf(Address.host(holder.address));
-
-            segment.uses.push({ address: Address.host(holder.address), what });
-            segment.taken.push({ first: value, last: value });
-            segments.set(prefix, segment);
-
-            for (const group of holder.vrrp) {
-                if (!Address.isValid(group.address) || !Address.contains(prefix, group.address)) continue;
-                if (segment.uses.some((use) => use.address === group.address)) continue;
-
-                const holders = devices.filter((device) =>
-                    Object.values({ ...device.ports, ...device.interfaces }).some((settings) =>
-                        settings?.vrrp?.some((other) => other.id === group.id && other.address === group.address)
-                    )
-                );
-
-                segment.uses.push({
-                    address: group.address,
-                    what: `VRRP ${group.id} on ${holders.map((device) => device.name).join(", ")}`,
-                });
-                segment.taken.push({ first: AddressSpace.numberOf(group.address), last: AddressSpace.numberOf(group.address) });
-            }
-        }
-
-        // A use inside a segment is an address taken; outside every segment, a block of its own. An address one of our interfaces holds is listed once, as that interface.
-        const take = (address: string, what: string, first = address, last = address) => {
-            const prefix = segmentOf(first);
-            if (!prefix) return false;
-
-            const segment = segments.get(prefix)!;
-            if (segment.uses.some((use) => use.address === address)) return true;
-
-            segment.uses.push({ address, what });
-            segment.taken.push({ first: AddressSpace.numberOf(first), last: AddressSpace.numberOf(last) });
-            return true;
-        };
-
-        for (const device of devices) {
-            for (const [name, server] of Object.entries(device.dhcp ?? {})) {
-                const [start, end] = server.pool;
-                if (Address.isValid(start) && Address.isValid(end))
-                    take(`${start}-${end}`, `DHCP pool ${name} on ${device.name}`, start, end);
-
-                for (const reservation of server.reservations ?? []) {
-                    if (Address.isValid(reservation.address))
-                        take(reservation.address, `reserved for ${reservation.description ?? reservation.mac} by ${device.name}`);
-                }
-            }
-
-            for (const route of device.routing?.static ?? []) {
-                if (route.via && Address.isValid(route.via)) take(route.via, `next hop for ${route.prefix} on ${device.name}`);
-            }
-
-            for (const [name, neighbor] of Object.entries(device.routing?.bgp?.neighbors ?? {})) {
-                if (Address.isValid(neighbor.address)) take(neighbor.address, `BGP neighbor ${name} of ${device.name}`);
-            }
-
-            for (const [name, iface] of Object.entries(device.interfaces ?? {})) {
-                if (iface.type !== "wireguard") continue;
-
-                for (const peer of iface.peers ?? []) {
-                    for (const allowed of peer.allowed_addresses) {
-                        if (!Address.isCidr(allowed)) continue;
-
-                        const what = `WireGuard peer ${peer.name} on ${device.name} ${name}`;
-                        if (AddressSpace.isHostRoute(allowed) && take(Address.host(allowed), what)) continue;
-                        if (!segmentOf(Address.host(allowed))) blocks.push({ prefix: Address.prefixOf(allowed), what });
-                    }
-                }
-            }
-        }
-
-        // Space the network owns: what it originates in BGP, or the prefix asked for.
-        const owners = new Map<string, string[]>();
-        for (const device of devices) {
-            for (const prefix of device.routing?.bgp?.networks ?? []) {
-                if (!Address.isCidr(prefix)) continue;
-                owners.set(Address.prefixOf(prefix), [...(owners.get(Address.prefixOf(prefix)) ?? []), device.name]);
-            }
-        }
-
-        // A static route to a prefix no segment is in hands that block to whoever is at the next hop. A route covering segments or owned space, such as an aggregate, is not a use.
-        for (const device of devices) {
-            for (const route of device.routing?.static ?? []) {
-                if (!Address.isCidr(route.prefix) || Address.split(route.prefix).len === 0) continue;
-
-                const overlapsSegment = [...segments.keys()].some(
-                    (prefix) => Address.contains(route.prefix, prefix) || Address.contains(prefix, route.prefix)
-                );
-                const coversOwned = [...owners.keys()].some((owned) => Address.contains(route.prefix, owned));
-                if (overlapsSegment || coversOwned) continue;
-
-                const how = route.blackhole ? "discarded" : route.via ? `routed via ${route.via}` : `routed out ${route.interface}`;
-                blocks.push({ prefix: Address.prefixOf(route.prefix), what: `${how} by ${device.name}` });
-            }
-        }
-
-        const asked = within ? Address.prefixOf(within) : undefined;
-        const spacePrefixes = asked ? [asked] : [...owners.keys()];
-
-        // A segment or block belongs to the smallest space it is inside.
-        const spaceOf = (prefix: string) =>
-            spacePrefixes.filter((space) => Address.contains(space, prefix)).sort((a, b) => Address.split(b).len - Address.split(a).len)[0];
-
-        const toSegment = (prefix: string): Segment => {
-            const { uses, taken } = segments.get(prefix)!;
-            const free = AddressSpace.gaps(AddressSpace.usable(prefix), taken);
-            const total = free.reduce((sum, range) => sum + range.last - range.first + 1n, 0n);
-            const family = Address.family(prefix);
-
-            return {
-                prefix,
-                uses: uses.sort(AddressSpace.byAddress),
-                free: AddressSpace.count(total),
-                ...(free[0] ? { next: Address.fromNumber(free[0].first, family) } : {}),
-            };
-        };
-
-        const uniqueBlocks = blocks.filter(
-            (block, index) => blocks.findIndex((other) => other.prefix === block.prefix && other.what === block.what) === index
-        );
-
-        const spaces: Space[] = spacePrefixes.sort(AddressSpace.comparePrefixes).map((space) => {
-            const inside = (prefix: string) => spaceOf(prefix) === space;
-            const spaceSegments = [...segments.keys()].filter(inside).sort(AddressSpace.comparePrefixes);
-            const spaceBlocks = uniqueBlocks.filter((block) => inside(block.prefix)).sort(AddressSpace.byPrefix);
-
-            // Smaller spaces inside this one are in use too.
-            const nested = spacePrefixes.filter((other) => other !== space && Address.contains(space, other));
-            const taken = [...spaceSegments, ...spaceBlocks.map((block) => block.prefix), ...nested].map((prefix) => Address.range(prefix));
-            const family = Address.family(space);
-
-            return {
-                prefix: space,
-                owner: asked && !owners.has(space) ? "asked for" : `originated by ${(owners.get(space) ?? []).join(", ")}`,
-                segments: spaceSegments.map(toSegment),
-                blocks: spaceBlocks,
-                free: AddressSpace.gaps(Address.range(space), taken).flatMap((range) =>
-                    Address.prefixesBetween(range.first, range.last, family)
-                ),
-            };
-        });
-
-        const outside = (prefix: string) => !spaceOf(prefix);
-
-        return {
-            spaces,
-            elsewhere: asked
-                ? { segments: [], blocks: [] }
-                : {
-                      segments: [...segments.keys()].filter(outside).sort(AddressSpace.comparePrefixes).map(toSegment),
-                      blocks: uniqueBlocks.filter((block) => outside(block.prefix)).sort(AddressSpace.byPrefix),
-                  },
-        };
-    }
-
-    /** Free prefixes of one length inside the free space, up to `limit`, and how many there are in all. */
-    static freeOfLength(free: readonly string[], length: number, limit: number): { prefixes: string[]; total: bigint } {
-        const prefixes: string[] = [];
-        let total = 0n;
-
-        for (const prefix of free) {
-            const { len, family } = Address.split(prefix);
-            if (len > length || length > Address.bits(family)) continue;
-
-            const { first } = Address.range(prefix);
-            const step = 1n << BigInt(Address.bits(family) - length);
-            const fits = 1n << BigInt(length - len);
-            total += fits;
-
-            for (let index = 0n; index < fits && prefixes.length < limit; index++) {
-                prefixes.push(`${Address.fromNumber(first + index * step, family)}/${length}`);
-            }
-        }
-
-        return { prefixes, total };
-    }
-}