@takodotid/circuit 0.23.0 → 0.24.0

package/README.md

@@ -25,6 +25,15 @@ Documentation: [circuit.tako.id](https://circuit.tako.id)
     <img src="docs/public/screenshots/studio-light.png" alt="Studio's VLAN graph with devices that differ from their snapshots marked by orange dashed borders, beside the layer details and legend.">
 </picture>
 
+## Circuit Academy
+
+New to networking? [Circuit Academy](https://circuit.tako.id/academy/) teaches it from the very start, in lessons you try in the browser rather than only read: packets, addresses, switches and routers first, then VLANs, DHCP, NAT and firewalls written down in Circuit, up to BGP and an edge router of your own. A certification is coming.
+
+<picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/public/screenshots/academy-dark.png">
+    <img src="docs/public/screenshots/academy-light.png" alt="A Circuit Academy lesson on switches: a frame from a laptop to a printer has just been flooded out of every port, and the switch has learned which port the laptop is behind.">
+</picture>
+
 ## Start
 
 You need [Node.js](https://nodejs.org) 20.12 or newer, or [Bun](https://bun.sh). Then:

package/dist/cli/index.js

@@ -3256,6 +3256,8 @@ function unsupported3(device) {
       found.push(`interfaces.${name}.addresses, LAGs are switched`);
     if (iface.mtu !== undefined)
       found.push(`interfaces.${name}.mtu`);
+    if (iface.ipv6_ra)
+      found.push(`interfaces.${name}.ipv6_ra`);
     for (const group of iface.vrrp ?? [])
       if (familyOf2(group.address) === "ipv6")
         found.push(`interfaces.${name}.vrrp for IPv6`);
@@ -3271,6 +3273,10 @@ function unsupported3(device) {
     found.push("routing.rpki");
   if (routing?.ospf?.families?.includes("ipv6"))
     found.push("routing.ospf for IPv6");
+  for (const [index, route] of (routing?.static ?? []).entries()) {
+    if (route.description && familyOf2(split(route.prefix).addr) === "ipv6")
+      found.push(`routing.static[${index}].description for IPv6`);
+  }
   for (const field of ["firewall", "dhcp", "acls", "policies", "prefix_sets", "hardware_offload", "certificates"]) {
     if (device[field] !== undefined)
       found.push(field);
@@ -3629,14 +3635,25 @@ function checkAcross(devices) {
     ...checkTunnels(devices, owners)
   ];
 }
-function carried(device, port) {
+function carried(device, settings) {
   const id = (vlan) => 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))
+    access: id(settings.access_vlan),
+    native: id(settings.native_vlan),
+    trunk: (settings.trunk_vlans ?? []).map(id).sort((a, b) => (a ?? 0) - (b ?? 0))
   };
 }
+function describeCarried({ access, native, trunk }) {
+  const parts = [];
+  const tagged = trunk.filter((id) => id !== undefined);
+  if (access !== undefined)
+    parts.push(`VLAN ${access} untagged`);
+  if (tagged.length)
+    parts.push(`${tagged.length === 1 ? "VLAN" : "VLANs"} ${tagged.join(", ")} tagged`);
+  if (native !== undefined)
+    parts.push(`VLAN ${native} untagged as native`);
+  return parts.length ? parts.join(" and ") : "no VLANs";
+}
 function vlanNames(device, settings) {
   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]] : []));
@@ -3695,15 +3712,21 @@ function checkLinks(devices) {
         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}`);
+      const near = carrierOf(device, portName, port);
+      const away = carrierOf(far, link.port, farPort);
+      const inLag = near.name !== portName;
+      const farInLag = away.name !== link.port;
+      if (inLag !== farInLag) {
+        report(inLag ? `${portName} is in ${near.name}, and ${link.device} ${link.port} is in no LAG` : `${portName} is in no LAG, and ${link.device} ${link.port} is in ${away.name}`);
+      }
+      const here = carried(device, near.settings);
+      const there = carried(far, away.settings);
+      if (JSON.stringify(here) !== JSON.stringify(there)) {
+        report(`${near.name} carries ${describeCarried(here)}, and ${link.device} ${away.name} carries ${describeCarried(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)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.23.0",
+    "version": "0.24.0",
     "description": "Declarative, vendor-neutral network configuration: describe each device in TypeScript, and Circuit makes the device match. Alpha.",
     "keywords": [
         "network",

package/src/adapters/devices/vrp/index.ts

@@ -609,6 +609,7 @@ export function unsupported(device: Device): string[] {
         if (iface.type !== "vlan" && iface.type !== "lag") found.push(`interfaces.${name}, a ${iface.type}`);
         if (iface.type === "lag" && iface.addresses?.length) found.push(`interfaces.${name}.addresses, LAGs are switched`);
         if (iface.mtu !== undefined) found.push(`interfaces.${name}.mtu`);
+        if (iface.ipv6_ra) found.push(`interfaces.${name}.ipv6_ra`);
         for (const group of iface.vrrp ?? []) if (familyOf(group.address) === "ipv6") found.push(`interfaces.${name}.vrrp for IPv6`);
     }
 
@@ -621,6 +622,10 @@ export function unsupported(device: Device): string[] {
     if (routing?.rpki) found.push("routing.rpki");
     if (routing?.ospf?.families?.includes("ipv6")) found.push("routing.ospf for IPv6");
 
+    for (const [index, route] of (routing?.static ?? []).entries()) {
+        if (route.description && familyOf(split(route.prefix).addr) === "ipv6") found.push(`routing.static[${index}].description for IPv6`);
+    }
+
     for (const field of ["firewall", "dhcp", "acls", "policies", "prefix_sets", "hardware_offload", "certificates"] as const) {
         if (device[field] !== undefined) found.push(field);
     }

package/src/core/across.ts

@@ -25,16 +25,28 @@ export function checkAcross(devices: readonly Device[]): Finding[] {
     ];
 }
 
-/** 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>) {
+/** The VLAN ids a port or LAG carries, by how it carries them, so two ends can be compared across devices. */
+function carried(device: Device, settings: Switched<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)),
+        access: id(settings.access_vlan),
+        native: id(settings.native_vlan),
+        trunk: (settings.trunk_vlans ?? []).map(id).sort((a, b) => (a ?? 0) - (b ?? 0)),
     };
 }
 
+/** How a port carries its VLANs, in words: "VLANs 10, 20 tagged and VLAN 30 untagged as native". */
+function describeCarried({ access, native, trunk }: ReturnType<typeof carried>): string {
+    const parts: string[] = [];
+    const tagged = trunk.filter((id) => id !== undefined);
+
+    if (access !== undefined) parts.push(`VLAN ${access} untagged`);
+    if (tagged.length) parts.push(`${tagged.length === 1 ? "VLAN" : "VLANs"} ${tagged.join(", ")} tagged`);
+    if (native !== undefined) parts.push(`VLAN ${native} untagged as native`);
+
+    return parts.length ? parts.join(" and ") : "no VLANs";
+}
+
 /** 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);
@@ -114,17 +126,30 @@ function checkLinks(devices: readonly Device[]): Finding[] {
                 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}`);
+            const near = carrierOf(device, portName, port);
+            const away = carrierOf(far, link.port, farPort);
+
+            // A LAG's VLANs are on the LAG, so its member ports are compared by what their LAGs carry.
+            const inLag = near.name !== portName;
+            const farInLag = away.name !== link.port;
+            if (inLag !== farInLag) {
+                report(
+                    inLag
+                        ? `${portName} is in ${near.name}, and ${link.device} ${link.port} is in no LAG`
+                        : `${portName} is in no LAG, and ${link.device} ${link.port} is in ${away.name}`
+                );
+            }
+
+            const here = carried(device, near.settings);
+            const there = carried(far, away.settings);
+            if (JSON.stringify(here) !== JSON.stringify(there)) {
+                report(`${near.name} carries ${describeCarried(here)}, and ${link.device} ${away.name} carries ${describeCarried(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}`);

package/templates/single-site/router.ts

@@ -69,16 +69,13 @@ export default defineDevice({
                     { description: "DNS from guests", match: { in_interface: "guests", protocol: "udp", dst_port: 53 }, action: "accept" },
                 ],
             },
-            // Traffic passing through the router.
+            // Traffic passing through the router: home and guests reach the internet, and nothing else gets through.
             forward: {
+                default: "drop",
                 rules: [
                     { description: "Replies", match: { state: ["established", "related"] }, action: "accept", offload: true },
-                    {
-                        description: "Guests stay off the home network",
-                        match: { in_interface: "guests", out_interface: "home" },
-                        action: "drop",
-                    },
-                    { description: "Guests stay off management", match: { in_interface: "guests", out_interface: "mgmt" }, action: "drop" },
+                    { description: "Home to the internet", match: { in_interface: "home", out_interface: "1g-1" }, action: "accept" },
+                    { description: "Guests to the internet", match: { in_interface: "guests", out_interface: "1g-1" }, action: "accept" },
                 ],
             },
         },