@takodotid/circuit 0.18.5 → 0.20.0

package/src/core/across.ts

@@ -0,0 +1,322 @@
+// Rules that span devices: what one device declares about another has to agree with what the other declares.
+
+import type { Device, Gre, Port, Routed, Switched, Vxlan } from "../schema";
+import { contains, familyOf, host, isCidr, network as prefixOf } from "./addr";
+import type { Finding } from "./define";
+import { type Holder, holdersOf, keyOf } from "./graph";
+
+/** Every rule across devices. */
+export function checkAcross(devices: readonly Device[]): Finding[] {
+    const holders = holdersOf(devices);
+
+    // Who holds each address. The first holder wins; a second is reported by checkAddresses.
+    const owners = new Map<string, Holder>();
+    for (const holder of holders) {
+        const key = keyOf(host(holder.address))!;
+        if (!owners.has(key)) owners.set(key, holder);
+    }
+
+    return [
+        ...checkLinks(devices),
+        ...checkAddresses(holders),
+        ...checkSessions(devices, owners),
+        ...checkVrrp(holders),
+        ...checkTunnels(devices, owners),
+    ];
+}
+
+/** The VLAN ids a port carries, by how it carries them, so two ends can be compared across devices. */
+function carried(device: Device, port: Port<string, string, string, string>) {
+    const id = (vlan: string | undefined) => (vlan ? device.vlans?.[vlan]?.id : undefined);
+    return {
+        access: id(port.access_vlan),
+        native: id(port.native_vlan),
+        trunk: (port.trunk_vlans ?? []).map(id).sort((a, b) => (a ?? 0) - (b ?? 0)),
+    };
+}
+
+/** VLAN names by id, for the VLANs a port or LAG carries. */
+function vlanNames(device: Device, settings: Switched<string>): Map<number, string> {
+    const names = [settings.access_vlan, settings.native_vlan, ...(settings.trunk_vlans ?? [])].filter((name) => name !== undefined);
+
+    return new Map(names.flatMap((name) => (device.vlans?.[name] ? [[device.vlans[name].id, name] as const] : [])));
+}
+
+/** What a port's settings are kept on: the LAG when the port is a member of one, otherwise the port. */
+function carrierOf(device: Device, portName: string, port: Port<string, string, string, string>) {
+    const lag = port.lag ? device.interfaces?.[port.lag] : undefined;
+    if (port.lag && lag?.type === "lag") return { name: port.lag, settings: lag };
+
+    return { name: portName, settings: port };
+}
+
+/** The plain addresses of one family on an interface, leaving out point-to-point ones. */
+const plainAddresses = (settings: Routed<string>, family: string) =>
+    (settings.addresses ?? []).filter((entry): entry is string => typeof entry === "string" && isCidr(entry) && familyOf(entry) === family);
+
+/** Why the two ends of a cable cannot reach each other by address, or undefined when they can. */
+function addressDisagreement(here: Routed<string>, there: Routed<string>, far: Device, farName: string): string | undefined {
+    for (const family of ["ipv4", "ipv6"]) {
+        const ours = plainAddresses(here, family);
+        const theirs = plainAddresses(there, family);
+        if (!ours.length || !theirs.length) continue;
+
+        // A prefix includes its length, so 10.0.0.0/24 and 10.0.0.0/25 are not one.
+        const theirPrefixes = new Set(theirs.map(prefixOf));
+        if (!ours.some((address) => theirPrefixes.has(prefixOf(address)))) {
+            return `has ${ours.join(", ")}, and ${far.name} ${farName} has ${theirs.join(", ")}: not one prefix of one length`;
+        }
+    }
+
+    // A point-to-point address names the far end's own address as its peer.
+    const farHosts = new Set((there.addresses ?? []).map((entry) => keyOf(host(typeof entry === "string" ? entry : entry.address))));
+
+    for (const entry of here.addresses ?? []) {
+        if (typeof entry === "string" || !keyOf(entry.peer) || farHosts.has(keyOf(entry.peer))) continue;
+        return `${entry.address} names peer ${entry.peer}, which ${far.name} ${farName} does not hold`;
+    }
+
+    return undefined;
+}
+
+/** A link names a device and port that exist, the far end links back, and both ends carry the same VLANs the same way, with the same MTU, speed and addresses. */
+function checkLinks(devices: readonly Device[]): Finding[] {
+    const findings: Finding[] = [];
+    const byName = new Map(devices.map((device) => [device.name, device]));
+
+    for (const device of devices) {
+        for (const [portName, port] of Object.entries(device.ports ?? {})) {
+            const link = port?.link;
+            if (!port || !link) continue;
+
+            const report = (message: string, level: Finding["level"] = "error") =>
+                findings.push({
+                    level,
+                    device: device.name,
+                    message: `port ${portName} link: ${message}`,
+                });
+
+            const far = byName.get(link.device);
+            if (!far) {
+                report(`device ${link.device} is not in the network`);
+                continue;
+            }
+
+            const farPort = far.ports?.[link.port];
+            if (!farPort) {
+                report(`${link.device} does not declare port ${link.port}`);
+                continue;
+            }
+
+            const linksBack = farPort.link?.device === device.name && farPort.link.port === portName;
+            if (!linksBack) {
+                report(`${link.device} ${link.port} does not link back to it`);
+                continue;
+            }
+
+            const here = JSON.stringify(carried(device, port));
+            const there = JSON.stringify(carried(far, farPort));
+            if (here !== there) report(`carries ${here}, and ${link.device} ${link.port} carries ${there}`);
+
+            if (port.speed && farPort.speed && port.speed !== farPort.speed) {
+                report(`speed ${port.speed}, and ${link.device} ${link.port} is ${farPort.speed}`);
+            }
+
+            const near = carrierOf(device, portName, port);
+            const away = carrierOf(far, link.port, farPort);
+
+            const mtu = near.settings.mtu ?? 1500;
+            const farMtu = away.settings.mtu ?? 1500;
+            if (mtu !== farMtu) report(`MTU ${mtu} on ${near.name}, and ${link.device} ${away.name} has ${farMtu}`);
+
+            const disagreement = addressDisagreement(near.settings, away.settings, far, away.name);
+            if (disagreement) report(`${near.name} ${disagreement}`);
+
+            // One VLAN under two names works, but reads as two VLANs.
+            const farNames = vlanNames(far, away.settings);
+            for (const [id, name] of vlanNames(device, near.settings)) {
+                const farName = farNames.get(id);
+                if (farName && farName !== name) report(`VLAN ${id} is ${name} here and ${farName} on ${link.device}`, "warning");
+            }
+        }
+    }
+
+    return findings;
+}
+
+/** No address is held by two devices. Two loopbacks may hold one on purpose, for anycast, so that is a warning. */
+function checkAddresses(holders: Holder[]): Finding[] {
+    const findings: Finding[] = [];
+    const first = new Map<string, Holder>();
+
+    const isLoopback = (holder: Holder) => holder.device.interfaces?.[holder.name]?.type === "loopback";
+
+    for (const holder of holders) {
+        const key = keyOf(host(holder.address))!;
+        const earlier = first.get(key);
+
+        if (!earlier) {
+            first.set(key, holder);
+            continue;
+        }
+
+        // Two on one device are reported by the device's own checks.
+        if (earlier.device === holder.device) continue;
+
+        const anycast = isLoopback(earlier) && isLoopback(holder);
+
+        findings.push({
+            level: anycast ? "warning" : "error",
+            device: holder.device.name,
+            message: `${host(holder.address)} on ${holder.name} is also on ${earlier.device.name} ${earlier.name}${anycast ? ", which is right only for anycast" : ""}`,
+        });
+    }
+
+    return findings;
+}
+
+/** A BGP session to an address another of our devices holds needs that device's session back, in the AS it expects, from the address it names. */
+function checkSessions(devices: readonly Device[], owners: Map<string, Holder>): Finding[] {
+    const findings: Finding[] = [];
+
+    const sessionsOf = (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,
+                remoteAs: neighbor.remote_as ?? group?.remote_as,
+                localAddress: neighbor.local_address ?? group?.local_address,
+            };
+        });
+    };
+
+    for (const device of devices) {
+        for (const session of sessionsOf(device)) {
+            const far = owners.get(keyOf(session.address) ?? "")?.device;
+            if (!far || far === device) continue;
+
+            const report = (message: string) =>
+                findings.push({ level: "error", device: device.name, message: `neighbor ${session.name}: ${message}` });
+
+            const farBgp = far.routing?.bgp;
+            if (!farBgp) {
+                report(`${session.address} is ${far.name}'s, which runs no BGP`);
+                continue;
+            }
+
+            if (session.remoteAs !== undefined && session.remoteAs !== farBgp.asn) {
+                report(`expects AS${session.remoteAs}, and ${far.name} is AS${farBgp.asn}`);
+            }
+
+            // Two routers often hold one session per family, and a session of the other family does not answer this one.
+            const back = sessionsOf(far).find(
+                (other) =>
+                    owners.get(keyOf(other.address) ?? "")?.device === device && familyOf(other.address) === familyOf(session.address)
+            );
+            if (!back) {
+                report(`${far.name} has no session back to ${device.name}`);
+                continue;
+            }
+
+            // The far end only accepts the session from the address it names.
+            if (session.localAddress && keyOf(session.localAddress) !== keyOf(back.address)) {
+                report(`starts from ${session.localAddress}, and ${far.name}'s session ${back.name} expects ${back.address}`);
+            }
+        }
+    }
+
+    return findings;
+}
+
+/** On one segment, a VRRP id has one address and an address has one id, on every device. */
+function checkVrrp(holders: Holder[]): Finding[] {
+    const findings: Finding[] = [];
+    const bySegment = new Map<string, { holder: Holder; id: number; address: string }[]>();
+
+    for (const holder of holders) {
+        const segment = prefixOf(holder.address);
+
+        for (const group of holder.vrrp) {
+            if (!keyOf(group.address) || familyOf(group.address) !== familyOf(holder.address)) continue;
+            if (!contains(segment, group.address)) continue;
+
+            bySegment.set(segment, [...(bySegment.get(segment) ?? []), { holder, id: group.id, address: group.address }]);
+        }
+    }
+
+    for (const members of bySegment.values()) {
+        for (const member of members) {
+            const where = `${member.holder.device.name} ${member.holder.name}`;
+            const others = members.filter((other) => other.holder.device !== member.holder.device);
+
+            const sameId = others.find((other) => other.id === member.id && keyOf(other.address) !== keyOf(member.address));
+            if (sameId) {
+                findings.push({
+                    level: "error",
+                    device: member.holder.device.name,
+                    message: `VRRP ${member.id} on ${member.holder.name} is ${member.address}, and on ${sameId.holder.device.name} ${sameId.holder.name} it is ${sameId.address}`,
+                });
+            }
+
+            const sameAddress = others.find((other) => keyOf(other.address) === keyOf(member.address) && other.id !== member.id);
+            if (sameAddress) {
+                findings.push({
+                    level: "error",
+                    device: member.holder.device.name,
+                    message: `VRRP address ${member.address} is id ${member.id} on ${where}, and id ${sameAddress.id} on ${sameAddress.holder.device.name} ${sameAddress.holder.name}`,
+                });
+            }
+        }
+    }
+
+    return findings;
+}
+
+/** A GRE or VXLAN tunnel to another of our devices has a tunnel back there, with the endpoints mirrored and, for VXLAN, the same VNI and port. */
+function checkTunnels(devices: readonly Device[], owners: Map<string, Holder>): Finding[] {
+    const findings: Finding[] = [];
+
+    const ends = devices.flatMap((device) =>
+        Object.entries(device.interfaces ?? {}).flatMap(([name, iface]) =>
+            iface.type === "gre" || iface.type === "vxlan" ? [{ device, name, iface: iface as Gre<string> | Vxlan<string> }] : []
+        )
+    );
+
+    const same = (a: string, b: string) => keyOf(a) !== undefined && keyOf(a) === keyOf(b);
+
+    for (const end of ends) {
+        const far = owners.get(keyOf(end.iface.remote) ?? "")?.device;
+        if (!far || far === end.device) continue;
+
+        const report = (message: string) =>
+            findings.push({ level: "error", device: end.device.name, message: `interface ${end.name}: ${message}` });
+        const kind = end.iface.type === "gre" ? "GRE" : "VXLAN";
+
+        const mirror = ends.find(
+            (other) =>
+                other.device === far &&
+                other.iface.type === end.iface.type &&
+                same(other.iface.local, end.iface.remote) &&
+                same(other.iface.remote, end.iface.local)
+        );
+
+        if (!mirror) {
+            report(`${end.iface.remote} is ${far.name}'s, which has no ${kind} tunnel from there back to ${end.iface.local}`);
+            continue;
+        }
+
+        if (end.iface.type !== "vxlan" || mirror.iface.type !== "vxlan") continue;
+
+        if (end.iface.vni !== mirror.iface.vni) report(`VNI ${end.iface.vni}, and ${far.name} ${mirror.name} has ${mirror.iface.vni}`);
+
+        const port = end.iface.port ?? 4789;
+        const farPort = mirror.iface.port ?? 4789;
+        if (port !== farPort) report(`UDP port ${port}, and ${far.name} ${mirror.name} has ${farPort}`);
+    }
+
+    return findings;
+}

package/src/core/addr.ts

@@ -113,6 +113,35 @@ export function contains(outer: string, inner: string): boolean {
     return (parse(innerAddress!)! & outerMask) === (parse(outerParts.addr)! & outerMask);
 }
 
+/** A number back to the address it stands for. */
+export const formatAddress = (value: bigint, family: Family) => format(value, family);
+
+/** The first and last address of a prefix, as numbers. */
+export function rangeOf(cidr: string): { first: bigint; last: bigint; family: Family } {
+    const { addr, len, family } = split(cidr);
+    const hostBits = mask(len, family) ^ ((1n << BigInt(bitsOf(family))) - 1n);
+    const first = parse(addr)! & mask(len, family);
+
+    return { first, last: first | hostBits, family };
+}
+
+/** The fewest prefixes that cover every address from `first` to `last` and nothing else. */
+export function prefixesBetween(first: bigint, last: bigint, family: Family): string[] {
+    const bits = bitsOf(family);
+    const prefixes: string[] = [];
+
+    for (let start = first; start <= last;) {
+        // The largest block that starts here on its own boundary and does not pass `last`.
+        let size = 0;
+        while (size < bits && start % (1n << BigInt(size + 1)) === 0n && start + (1n << BigInt(size + 1)) - 1n <= last) size++;
+
+        prefixes.push(`${format(start, family)}/${bits - size}`);
+        start += 1n << BigInt(size);
+    }
+
+    return prefixes;
+}
+
 /** `/25` to `255.255.255.128`. */
 export const netmask = (length: number) => format(mask(length, "ipv4"), "ipv4");
 

package/src/core/addresses.ts

@@ -0,0 +1,316 @@
+// 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, Family } from "../schema";
+import {
+    contains,
+    familyOf,
+    formatAddress,
+    host,
+    isAddress,
+    isCidr,
+    network as prefixOf,
+    parse,
+    prefixesBetween,
+    rangeOf,
+    split,
+} from "./addr";
+import { holdersOf } from "./graph";
+
+/** 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 };
+
+const bits = (family: Family) => (family === "ipv4" ? 32 : 128);
+const isHostRoute = (cidr: string) => split(cidr).len === bits(split(cidr).family);
+const numberOf = (address: string) => parse(address)!;
+
+/** Addresses a segment can give out: IPv4 leaves out the network and broadcast addresses below /31, and IPv6 the subnet-router anycast address. */
+function usable(prefix: string): Taken {
+    const { first, last, family } = rangeOf(prefix);
+    const { len } = 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. */
+function 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. */
+function gaps(within: Taken, taken: Taken[]): Taken[] {
+    const result: Taken[] = [];
+    let cursor = within.first;
+
+    for (const range of 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. */
+function 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}`;
+}
+
+const byAddress = (a: Use, b: Use) => {
+    const first = (use: Use) => numberOf(use.address.split("-")[0]!);
+    return first(a) < first(b) ? -1 : first(a) > first(b) ? 1 : 0;
+};
+
+/** IPv4 before IPv6, then by first address. */
+function comparePrefixes(a: string, b: string): number {
+    const [ra, rb] = [rangeOf(a), rangeOf(b)];
+    if (ra.family !== rb.family) return ra.family === "ipv4" ? -1 : 1;
+    return ra.first < rb.first ? -1 : ra.first > rb.first ? 1 : 0;
+}
+
+const byPrefix = (a: { prefix: string }, b: { prefix: string }) => 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. */
+export function addressesOf(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) => 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 holdersOf(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 (isHostRoute(holder.address) || holder.peer) {
+            blocks.push({ prefix: `${host(holder.address)}/${bits(familyOf(holder.address))}`, what });
+            continue;
+        }
+
+        const prefix = prefixOf(holder.address);
+        const segment = segments.get(prefix) ?? { uses: [], taken: [] };
+        const value = numberOf(host(holder.address));
+
+        segment.uses.push({ address: host(holder.address), what });
+        segment.taken.push({ first: value, last: value });
+        segments.set(prefix, segment);
+
+        for (const group of holder.vrrp) {
+            if (!isAddress(group.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: numberOf(group.address), last: 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: numberOf(first), last: numberOf(last) });
+        return true;
+    };
+
+    for (const device of devices) {
+        for (const [name, server] of Object.entries(device.dhcp ?? {})) {
+            const [start, end] = server.pool;
+            if (isAddress(start) && isAddress(end)) take(`${start}-${end}`, `DHCP pool ${name} on ${device.name}`, start, end);
+
+            for (const reservation of server.reservations ?? []) {
+                if (isAddress(reservation.address))
+                    take(reservation.address, `reserved for ${reservation.description ?? reservation.mac} by ${device.name}`);
+            }
+        }
+
+        for (const route of device.routing?.static ?? []) {
+            if (route.via && isAddress(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 (isAddress(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 (!isCidr(allowed)) continue;
+
+                    const what = `WireGuard peer ${peer.name} on ${device.name} ${name}`;
+                    if (isHostRoute(allowed) && take(host(allowed), what)) continue;
+                    if (!segmentOf(host(allowed))) blocks.push({ prefix: 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 (!isCidr(prefix)) continue;
+            owners.set(prefixOf(prefix), [...(owners.get(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 (!isCidr(route.prefix) || split(route.prefix).len === 0) continue;
+
+            const overlapsSegment = [...segments.keys()].some((prefix) => contains(route.prefix, prefix) || contains(prefix, route.prefix));
+            const coversOwned = [...owners.keys()].some((owned) => 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: prefixOf(route.prefix), what: `${how} by ${device.name}` });
+        }
+    }
+
+    const asked = within ? 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) => contains(space, prefix)).sort((a, b) => split(b).len - split(a).len)[0];
+
+    const toSegment = (prefix: string): Segment => {
+        const { uses, taken } = segments.get(prefix)!;
+        const free = gaps(usable(prefix), taken);
+        const total = free.reduce((sum, range) => sum + range.last - range.first + 1n, 0n);
+        const family = familyOf(prefix);
+
+        return {
+            prefix,
+            uses: uses.sort(byAddress),
+            free: count(total),
+            ...(free[0] ? { next: formatAddress(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(comparePrefixes).map((space) => {
+        const inside = (prefix: string) => spaceOf(prefix) === space;
+        const spaceSegments = [...segments.keys()].filter(inside).sort(comparePrefixes);
+        const spaceBlocks = uniqueBlocks.filter((block) => inside(block.prefix)).sort(byPrefix);
+
+        // Smaller spaces inside this one are in use too.
+        const nested = spacePrefixes.filter((other) => other !== space && contains(space, other));
+        const taken = [...spaceSegments, ...spaceBlocks.map((block) => block.prefix), ...nested].map((prefix) => rangeOf(prefix));
+        const family = familyOf(space);
+
+        return {
+            prefix: space,
+            owner: asked && !owners.has(space) ? "asked for" : `originated by ${(owners.get(space) ?? []).join(", ")}`,
+            segments: spaceSegments.map(toSegment),
+            blocks: spaceBlocks,
+            free: gaps(rangeOf(space), taken).flatMap((range) => prefixesBetween(range.first, range.last, family)),
+        };
+    });
+
+    const outside = (prefix: string) => !spaceOf(prefix);
+
+    return {
+        spaces,
+        elsewhere: asked
+            ? { segments: [], blocks: [] }
+            : {
+                  segments: [...segments.keys()].filter(outside).sort(comparePrefixes).map(toSegment),
+                  blocks: uniqueBlocks.filter((block) => outside(block.prefix)).sort(byPrefix),
+              },
+    };
+}
+
+/** Free prefixes of one length inside the free space, up to `limit`, and how many there are in all. */
+export function 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 } = split(prefix);
+        if (len > length || length > bits(family)) continue;
+
+        const { first } = rangeOf(prefix);
+        const step = 1n << BigInt(bits(family) - length);
+        const fits = 1n << BigInt(length - len);
+        total += fits;
+
+        for (let index = 0n; index < fits && prefixes.length < limit; index++) {
+            prefixes.push(`${formatAddress(first + index * step, family)}/${length}`);
+        }
+    }
+
+    return { prefixes, total };
+}