@takodotid/circuit 0.41.0 → 0.42.0

package/templates/colocation/tenancy.ts

@@ -1,94 +1,73 @@
-// What a tenant is, and what each device carries for it. A tenant's file says what is the tenant's own; its VLANs and names follow from its name and number.
+// What a tenant is, and what each device carries for it. A tenant's file writes everything its devices carry: its VLANs, the router's addresses for it, its ports. These functions only gather them for one device.
 
-import type { AclRule, Interface, IP, Port, Prefix, Vlan } from "@takodotid/circuit";
+import type { AclRule, Interface, InterfaceAddress, Port, Prefix, Vlan } from "@takodotid/circuit";
 import { Address } from "@takodotid/circuit";
 
-/** A tenant's networks. `internet` carries its servers' public addresses and reaches the router. `private` connects its own servers to each other and stays on the switches. */
-type TenantNetwork = "internet" | "private";
-
-export type Tenant<N extends string = string> = {
-    /** Lowercase, and never reused. Names everything the tenant has. */
-    name: N;
-    /** A number no other tenant has. Its internet VLAN is 1000 + number, its private VLAN 2000 + number. */
-    number: number;
-    /** Public blocks routed to the tenant. `gateway` is the router's address inside the block, which the tenant's servers use as their gateway. */
-    blocks: readonly { prefix: Prefix; gateway: IP }[];
+/** A VLAN with its name. */
+export type NamedVlan = Vlan & { name: string };
+
+export type Tenant = {
+    /** Lowercase, and never reused. */
+    name: string;
+    /** The tenant's VLAN to the internet. The router has it, with the tenant's gateways, and so does every switch, to carry it up to the router. */
+    internet: {
+        vlan: NamedVlan;
+        /** The router's addresses on it, each the gateway the tenant's servers use inside one of its blocks, such as `198.51.100.9/29`. */
+        gateways: readonly InterfaceAddress[];
+    };
+    /** A VLAN between the tenant's own servers. It is only on a switch where one of the tenant's ports uses it, and never on the router. */
+    private?: { vlan: NamedVlan };
     /** Rules for traffic toward the tenant's IPv4 blocks from the transit and the exchange, such as a cap on UDP. Everything reaches the tenant when absent. */
     acl?: readonly (Omit<AclRule<never>, "match"> & { match?: Omit<NonNullable<AclRule<never>["match"]>, "vlan" | "dst"> })[];
-    /** The tenant's ports, by switch, then by port. A port in `private` gives the tenant a private network on that switch. */
-    ports: Readonly<
-        Record<string, Readonly<Record<string, { description: string; access?: TenantNetwork; trunk?: readonly TenantNetwork[] }>>>
-    >;
+    /** The tenant's ports, by switch, then by port, written as any port is. */
+    ports: Readonly<Record<string, Readonly<Record<string, Port<string, string, string, string>>>>>;
 };
 
-/** Declare a tenant. */
-export const tenant = <const N extends string>(spec: Tenant<N>): Tenant<N> => spec;
-
-const internetVlan = <N extends string>(t: Tenant<N>) => `${t.name}-internet` as const;
-const privateVlan = <N extends string>(t: Tenant<N>) => `${t.name}-private` as const;
+/** A VLAN as `vlans` takes it, keyed by its name. */
+const entry = ({ name, ...vlan }: NamedVlan): [string, Vlan] => [name, vlan];
 
-/** Every tenant's internet VLAN. The router has them all, and so does each switch, to carry them up to the router. */
-export const internetVlans = <N extends string>(tenants: readonly Tenant<N>[]) =>
-    Object.fromEntries(tenants.map((t) => [internetVlan(t), { id: 1000 + t.number, description: `Tenant ${t.name} internet` }])) as Record<
-        `${N}-internet`,
-        Vlan
-    >;
+/** The tenant's blocks: the network of each gateway. */
+export const blocksOf = (t: Tenant): Prefix[] => t.internet.gateways.map((gateway) => Address.prefixOf(gateway));
 
-/** The names of every tenant's internet VLAN, for a trunk toward the router. */
-export const internetVlanNames = <N extends string>(tenants: readonly Tenant<N>[]) => tenants.map(internetVlan);
+/** Every tenant's internet VLAN, for the router. */
+export const routerVlans = (tenants: readonly Tenant[]): Record<string, Vlan> =>
+    Object.fromEntries(tenants.map((t) => entry(t.internet.vlan)));
 
-/** The private VLANs one switch has: those of tenants with a port on it in their private network. */
-export const privateVlans = <N extends string>(tenants: readonly Tenant<N>[], device: string) =>
+/** The VLANs one switch carries: every tenant's internet VLAN, and the private VLAN of each tenant with a port on it that uses it. */
+export const switchVlans = (tenants: readonly Tenant[], device: string): Record<string, Vlan> =>
     Object.fromEntries(
-        tenants
-            .filter((t) =>
-                Object.values(t.ports[device] ?? {}).some((port) => port.access === "private" || port.trunk?.includes("private"))
-            )
-            .map((t) => [privateVlan(t), { id: 2000 + t.number, description: `Tenant ${t.name} private` }])
-    ) as Record<`${N}-private`, Vlan>;
-
-/** The tenants' ports on one switch. */
-export function portsOn<N extends string>(tenants: readonly Tenant<N>[], device: string) {
-    const ports: Record<string, Port<`${N}-internet` | `${N}-private`, string, string, string>> = {};
-
-    for (const t of tenants) {
-        const vlanOf = (network: TenantNetwork) => (network === "internet" ? internetVlan(t) : privateVlan(t));
+        tenants.flatMap((t) => {
+            const ports = Object.values(t.ports[device] ?? {});
+            const usesPrivate =
+                t.private &&
+                ports.some((port) => port.access_vlan === t.private!.vlan.name || port.trunk_vlans?.includes(t.private!.vlan.name));
+            return [entry(t.internet.vlan), ...(usesPrivate ? [entry(t.private!.vlan)] : [])];
+        })
+    );
 
-        for (const [name, { access, trunk, description }] of Object.entries(t.ports[device] ?? {})) {
-            ports[name] = {
-                description,
-                ...(access ? { access_vlan: vlanOf(access) } : {}),
-                ...(trunk ? { trunk_vlans: trunk.map(vlanOf) } : {}),
-            };
-        }
-    }
+/** The names of every tenant's internet VLAN, for a trunk toward the router. */
+export const internetVlanNames = (tenants: readonly Tenant[]) => tenants.map((t) => t.internet.vlan.name);
 
-    return ports;
-}
+/** The tenants' ports on one switch. */
+export const portsOn = (tenants: readonly Tenant[], device: string): Record<string, Port<string, string, string, string>> =>
+    Object.assign({}, ...tenants.map((t) => t.ports[device] ?? {}));
 
 /** The router's interface on each tenant's internet VLAN, holding the tenant's gateways. */
-export function gateways<N extends string>(tenants: readonly Tenant<N>[]) {
-    const interfaces = {} as Record<`${N}-internet`, Interface<`${N}-internet`, never>>;
-
-    for (const t of tenants) {
-        interfaces[internetVlan(t)] = {
-            type: "vlan",
-            vlan: internetVlan(t),
-            description: `Tenant ${t.name}`,
-            addresses: t.blocks.map(({ prefix, gateway }): Prefix => `${gateway}/${Address.split(prefix).len}`),
-        };
-    }
-
-    return interfaces;
-}
+export const gateways = (tenants: readonly Tenant[]): Record<string, Interface<string, never>> =>
+    Object.fromEntries(
+        tenants.map((t) => [
+            t.internet.vlan.name,
+            { type: "vlan", vlan: t.internet.vlan.name, description: `Tenant ${t.name}`, addresses: t.internet.gateways },
+        ])
+    );
 
 /** Each tenant's `acl` rules on one VLAN from outside, one per rule and IPv4 block, each limited to traffic toward that block. */
 export const edgeRules = <V extends string>(tenants: readonly Tenant[], vlan: V): AclRule<V>[] =>
     tenants.flatMap((t) =>
         (t.acl ?? []).flatMap((rule) =>
-            t.blocks
-                .filter(({ prefix }) => Address.family(prefix) === "ipv4")
-                .map(({ prefix }) => ({
+            blocksOf(t)
+                .filter((prefix) => Address.family(prefix) === "ipv4")
+                .map((prefix) => ({
                     ...rule,
                     ...(rule.description ? { description: `${vlan}: ${rule.description}` } : {}),
                     match: { ...rule.match, vlan, dst: prefix },

package/templates/colocation/tenants/acme.ts

@@ -1,19 +1,19 @@
 // An example tenant. Copy this file for each new tenant, and add it to index.ts.
 
-import { tenant } from "../tenancy";
+import type { Tenant } from "../tenancy";
 
-export default tenant({
+export default {
     name: "acme",
-    number: 1,
-    blocks: [
-        { prefix: "198.51.100.8/29", gateway: "198.51.100.9" },
-        { prefix: "2001:db8:100:1::/64", gateway: "2001:db8:100:1::1" },
-    ],
+    internet: {
+        vlan: { name: "acme-internet", id: 1001, description: "Tenant acme internet" },
+        gateways: ["198.51.100.9/29", "2001:db8:100:1::1/64"],
+    },
+    private: { vlan: { name: "acme-private", id: 2001, description: "Tenant acme private" } },
     acl: [{ description: "UDP to acme above 1G", match: { protocol: "udp" }, action: "accept", rate: "1G" }],
     ports: {
         "tor-01": {
-            "10g-1": { description: "acme server 1", trunk: ["internet", "private"] },
-            "10g-2": { description: "acme server 2", trunk: ["internet", "private"] },
+            "10g-1": { description: "acme server 1", trunk_vlans: ["acme-internet", "acme-private"] },
+            "10g-2": { description: "acme server 2", trunk_vlans: ["acme-internet", "acme-private"] },
         },
     },
-});
+} satisfies Tenant;

package/templates/colocation/tenants/index.ts

@@ -1,5 +1,6 @@
 // Every tenant. A tenant joins by being added here, and leaves by being removed: the next apply takes away everything it had.
 
+import type { Tenant } from "../tenancy";
 import acme from "./acme";
 
-export const TENANTS = [acme] as const;
+export const TENANTS: readonly Tenant[] = [acme];

package/templates/colocation/tor-01.ts

@@ -1,7 +1,7 @@
 // The top-of-rack switch: the tenants' servers, and one uplink to the router.
 
 import { defineDevice, secret, Utils } from "@takodotid/circuit";
-import { internetVlanNames, internetVlans, portsOn, privateVlans } from "./tenancy";
+import { internetVlanNames, portsOn, switchVlans } from "./tenancy";
 import { TENANTS } from "./tenants";
 
 export default defineDevice({
@@ -17,7 +17,7 @@ export default defineDevice({
     lldp: true,
     stp: {},
 
-    vlans: Utils.merge({ mgmt: { id: 99, description: "Management" } }, internetVlans(TENANTS), privateVlans(TENANTS, "tor-01")),
+    vlans: Utils.merge({ mgmt: { id: 99, description: "Management" } }, switchVlans(TENANTS, "tor-01")),
 
     // Every tenant's ports, from its file in tenants/, beside the switch's own.
     ports: Utils.merge(portsOn(TENANTS, "tor-01"), {

package/templates/project/AGENTS.md

@@ -16,21 +16,21 @@ What each field means is written as a comment on the field, in `node_modules/@ta
 
 ## Commands
 
-| Command                                       | What it does                                                                  | Changes a device |
-| --------------------------------------------- | ----------------------------------------------------------------------------- | ---------------- |
-| `npx circuit validate`                        | Checks every file and every rule in the checks                                | no               |
-| `npx circuit diff [device]`                   | Shows what would change, compared with the last snapshot                      | no               |
-| `npx circuit build <device>`                  | Prints the full configuration the device should run                           | no               |
-| `npx circuit snapshot [device]`               | Reads what each device runs now into `.circuit/state/`                        | no, only reads   |
-| `npx circuit show <device> '<command>'`       | Runs commands that only read on the device, secrets hidden                    | no, only reads   |
-| `npx circuit bgp [device] [name-regex]`       | Each BGP neighbor in the config next to its live session: up or down          | no, only reads   |
-| `npx circuit console <device> '<line>'`       | Sends lines to the device's serial console, unchecked                         | **can**          |
-| `npx circuit apply <device>`                  | Reads the device, then shows what would change on it                          | no               |
-| `npx circuit apply <device> --confirm`        | Sends the change to the device                                                | **yes**          |
-| `npx circuit secrets`                         | Lists every secret the config uses, and whether each one can be read          | no               |
-| `npx circuit rename <device> <new-name>`      | Shows every line a new device name changes; `--confirm` writes them           | no               |
-| `npx circuit addresses`                       | Every address the config uses, by prefix, and what is still free              | no               |
-| `npx circuit graph --layer=all --format=json` | The whole network as a graph: cables, VLANs, addresses, BGP, OSPF and tunnels | no               |
+| Command                                        | What it does                                                                  | Changes a device |
+| ---------------------------------------------- | ----------------------------------------------------------------------------- | ---------------- |
+| `npx circuit validate`                         | Checks every file and every rule in the checks                                | no               |
+| `npx circuit diff [device]`                    | Shows what would change, compared with the last snapshot                      | no               |
+| `npx circuit build <device>`                   | Prints the full configuration the device should run                           | no               |
+| `npx circuit snapshot [device]`                | Reads what each device runs now into `.circuit/state/`                        | no, only reads   |
+| `npx circuit show <device> '<command>'`        | Runs commands that only read on the device, secrets hidden                    | no, only reads   |
+| `npx circuit bgp [device] --neighbors <regex>` | Each BGP neighbor in the config next to its live session: up or down          | no, only reads   |
+| `npx circuit console <device> '<line>'`        | Sends lines to the device's serial console, unchecked                         | **can**          |
+| `npx circuit apply <device>`                   | Reads the device, then shows what would change on it                          | no               |
+| `npx circuit apply <device> --confirm`         | Sends the change to the device                                                | **yes**          |
+| `npx circuit secrets`                          | Lists every secret the config uses, and whether each one can be read          | no               |
+| `npx circuit rename <device> <new-name>`       | Shows every line a new device name changes; `--confirm` writes them           | no               |
+| `npx circuit addresses`                        | Every address the config uses, by prefix, and what is still free              | no               |
+| `npx circuit graph --layer=all --format=json`  | The whole network as a graph: cables, VLANs, addresses, BGP, OSPF and tunnels | no               |
 
 ## Making a change