@takodotid/circuit 0.43.1 → 1.0.0-rc.2

package/src/config/switching.ts

@@ -0,0 +1,84 @@
+// Layer 2 shared by ports: `switching.vlans`, `.stp`, `.lldp`, `.acls`.
+
+import type { Family, Named, OneOrMore, Ordered, Prefix, Rate } from "./common";
+import type { Ports, Protocol } from "./firewall";
+
+/**
+ * A VLAN. Its key in `switching.vlans` is its name. `Untrusted` is whether the network turns on the check `untrusted_vlans`, which
+ * `untrusted` needs.
+ */
+export type Vlan<Untrusted extends boolean = true> = {
+    /** The VLAN's number on the wire, 1 to 4094. Two VLANs on a device never share one. */
+    id: number;
+    /** What the VLAN is for. Dropped on a platform where a VLAN is only its number (Raisecom, FortiOS), so a device takes a VLAN whole wherever it runs. */
+    description?: string;
+    /**
+     * The VLAN carries traffic straight from outside: a transit, an exchange, an ISP handoff, or such a one's native VLAN. Only Circuit
+     * reads it, for the check `untrusted_vlans`; the device never sees it. Write it on every device that declares the VLAN. Allowed only
+     * when the network's `circuit()` turns on `untrusted_vlans`: an error in the editor, and `circuit validate` stops.
+     */
+    untrusted?: Untrusted extends true ? true : "allowed only when circuit.ts turns on the check untrusted_vlans";
+};
+
+/**
+ * Which packets an ACL rule applies to. All must be true.
+ *
+ * `vlan`, `src` and `dst` each take a list. Where the platform has no list, Circuit writes one rule per combination: the VLAN
+ * outermost, then `src`, then `dst`.
+ */
+export type AclMatch<V extends string> = {
+    /** Only packets of this family. */
+    family?: Family;
+    /** IP protocol. */
+    protocol?: Protocol;
+    /** Source prefix, or any of several. */
+    src?: OneOrMore<Prefix>;
+    /** Destination prefix, or any of several. */
+    dst?: OneOrMore<Prefix>;
+    /** Source port, or any of several. */
+    src_port?: Ports;
+    /** Destination port, or any of several. */
+    dst_port?: Ports;
+    /** One of `switching.vlans`, or any of several: only packets in this VLAN. */
+    vlan?: OneOrMore<V>;
+};
+
+/**
+ * A stateless rule evaluated in hardware where traffic arrives, before routing, the condition first:
+ * `{ if: { vlan: "ix", src: "10.0.0.0/8" }, then: "drop" }`. No `if`: every packet.
+ */
+export type AclRule<V extends string> = {
+    /** Shown beside the rule on the device. */
+    description?: string;
+    /** Which packets the rule applies to. Every packet when absent. */
+    if?: AclMatch<V>;
+    /** What happens to a matching packet. */
+    then: "accept" | "drop";
+    /** Accepted traffic above this rate is dropped. On RouterOS it did not limit traffic the CPU routes; see its TRAPS.md. */
+    rate?: Rate;
+};
+
+/** Spanning tree on every switched port. A port may override it. */
+export type Stp = {
+    /** Which variant runs. RSTP when absent. */
+    mode?: "stp" | "rstp" | "mstp";
+    /** Bridge priority, 0 to 61440 in steps of 4096. Lower wins the root election. */
+    priority?: number;
+};
+
+/** Layer 2 that the ports share. `V` is the device's VLAN names, `A` its ACL names, `I` its ports and interfaces. `Untrusted` is whether the network turns on `untrusted_vlans`. */
+export type Switching<V extends string, A extends string, I extends string, Untrusted extends boolean = true> = {
+    /** VLANs, keyed by name. A port, a LAG or a VLAN interface names one of these. */
+    vlans?: Named<V, Vlan<Untrusted>>;
+    /** Spanning tree on every switched port. A port may override it. */
+    stp?: Stp;
+    /** Advertise and learn neighbors with LLDP on every port (`true`), or only on the interfaces listed. A port may override it. */
+    lldp?:
+        | true
+        | {
+              /** Some of the device's ports and interfaces. */
+              interfaces: readonly I[];
+          };
+    /** Hardware ACLs, keyed by name, applied to a port with `ingress_acl`. Each is rules in order, written whole in one place: the first runs first. */
+    acls?: Named<A, Ordered<AclRule<NoInfer<V>>>>;
+};

package/src/config/system.ts

@@ -0,0 +1,103 @@
+// The box itself: `system.timezone`, `.banner`, `.release_channel`, `.ip_stack`, `.alarms`, `.dns`, `.ntp`, `.logging`, `.hardware_offload`, `.users`, `.certificates`, `.vdoms`.
+
+import type { IP, Named, Secret, Severity } from "./common";
+import type { StaticRoute } from "./routing";
+import type { TimeZone } from "./time-zones";
+
+/** A software release track, as RouterOS names them. `long-term` changes least; `development` is the newest and least tested. */
+export type ReleaseChannel = "long-term" | "stable" | "testing" | "development";
+
+/** How bad an alarm is, most severe first, as ITU-T X.733 ranks them. */
+export type AlarmSeverity = "critical" | "major" | "minor" | "warning";
+
+/** A login on the device. */
+export type User = {
+    /** What the user may do. */
+    role: "admin" | "operator" | "read-only";
+    /** The login password. */
+    password: Secret;
+    /** Who the account is for. */
+    description?: string;
+    /** Public keys accepted instead of the password over SSH. */
+    ssh_keys?: readonly string[];
+};
+
+/** A certificate the device presents or trusts. */
+export type Certificate = {
+    /** The certificate, a PEM file (`.pem` or `.crt`): a path from the project root. Public, so it is kept in the repository. */
+    certificate_file: string;
+    /** Its private key: a PEM file through `secretFile`, or PEM base64-encoded as one line through `secret`. A certificate the device only trusts, such as a CA, has none. */
+    private_key?: Secret;
+};
+
+/**
+ * Virtual domains, on FortiOS: the device's own traffic kept apart from the traffic it routes. Everything is in `root` when absent.
+ *
+ * Multi-VDOM mode is turned on by hand, not by a plan: it moves the whole configuration into `root` and ends every session.
+ */
+export type Vdoms<I extends string> = {
+    /** A VDOM for the device's own traffic: FortiGuard, NTP, DNS and logging leave from it, by its own routes, so they never follow the routed traffic's default route. Everything not listed here stays in `root`. */
+    management: {
+        /** Its name, such as `mgmt`. Not `root`. */
+        name: string;
+        /** Some of the device's ports and interfaces: the ones in it. A LAG's member ports go with the LAG. */
+        interfaces: readonly I[];
+        /** Its static routes, such as its own default route. */
+        static_routes?: readonly StaticRoute<I, never, never>[];
+    };
+};
+
+/** Device-wide settings: the box itself. `U` is the device's user names, `C` its certificate names, `I` its ports and interfaces. */
+export type System<U extends string, C extends string, I extends string> = {
+    /** IANA zone, for example `Asia/Jakarta`. The editor suggests every name. UTC when absent. */
+    timezone?: TimeZone;
+    /** Shown at login. */
+    banner?: string;
+    /** Software release track the device updates from. `stable` when absent. */
+    release_channel?: ReleaseChannel;
+    /** Host behaviour of the IP stack. */
+    ip_stack?: {
+        /** Send ICMP redirects. Off when absent. */
+        icmp_redirects?: boolean;
+        /** Answer a TCP SYN flood with SYN cookies. Off when absent. */
+        syn_cookies?: boolean;
+    };
+    /** Alarms raised at another severity than the platform's own, keyed by the alarm's name as the platform spells it, such as `hwOpticalUnAuthorized` on VRP. */
+    alarms?: Record<
+        string,
+        {
+            /** The severity it is raised at. */
+            severity: AlarmSeverity;
+        }
+    >;
+    /** Resolvers the device uses. Answering others is `services.dns_server`. */
+    dns?: {
+        /** Resolvers, in order of preference. */
+        servers: readonly IP[];
+    };
+    /** How the device keeps time. Answering others is `services.ntp_server`. */
+    ntp?: {
+        /** Time sources, by address (alone or with its length) or name, in order of preference. */
+        servers: readonly string[];
+    };
+    /** Log messages kept on the device itself. Sending them to collectors is `monitoring.syslog`. */
+    logging?: {
+        /** Kept on the device's own storage, from `level` up. */
+        local?: {
+            /** The least severe message kept. */
+            level: Severity;
+            /** How many rotated files to keep. */
+            files?: number;
+            /** Lines in each file before it rotates. */
+            lines_per_file?: number;
+        };
+    };
+    /** Forward in hardware where the platform can. An interface may override it. */
+    hardware_offload?: boolean;
+    /** Logins, keyed by user name. Users not listed are removed. */
+    users?: Named<U, User>;
+    /** Certificates the device presents or trusts, keyed by name. `management.https` and `management.api_tls` name one. */
+    certificates?: Named<C, Certificate>;
+    /** Virtual domains, on FortiOS only: a management VDOM apart from the routed traffic. */
+    vdoms?: Vdoms<I>;
+};

package/src/{schema → config}/time-zones.ts

@@ -1,4 +1,4 @@
-// Generated by `bun scripts/time-zones.ts` from the time zones the runtime knows. Do not edit by hand: run the script again to update it.
+// Every IANA time zone name Circuit knows, copied from Circuit 0.43 (`src/schema/time-zones.ts`, generated from the runtime).
 
 /** An IANA time zone name, such as `Asia/Jakarta`, or `UTC`. */
 export type TimeZone =

package/src/core/address.ts

@@ -1,6 +1,6 @@
 // Address arithmetic for both families. Addresses are parsed to bigint so v4 and v6 share one code path.
 
-import type { Family, IP, IPv4, IPv6, Prefix } from "../schema";
+import type { Family, IP, IPv4, IPv6, Prefix } from "../model";
 
 /** Address helpers, for checks of your own. */
 export class Address {

package/src/core/cabling.ts

@@ -1,10 +1,8 @@
-// The cabling as LLDP sees it, compared with what `link` says. `snapshot` saves each device's LLDP neighbors beside its config; `validate` warns where they disagree.
+// The cabling as LLDP sees it, compared with what `link` says. `diff` and `apply` read a device's LLDP neighbors while they are connected, and warn where they disagree.
 
-import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
 import { Catalog } from "../platforms/catalog";
-import type { Device } from "../schema";
-import type { Finding } from "./define";
+import type { Device } from "../model";
+import type { Finding } from "../platforms/finding";
 
 /** A device one of our ports sees at the far end of its cable, over LLDP. */
 export type Neighbor = {
@@ -17,50 +15,17 @@ export type Neighbor = {
 };
 
 export class Cabling {
-    /** The end of a state file that holds a device's LLDP neighbors, beside its config. */
-    static readonly SUFFIX = ".lldp.json";
-
-    /** The file a device's neighbors are saved in. */
-    static path(stateDirectory: string, device: string): string {
-        return join(stateDirectory, device + Cabling.SUFFIX);
-    }
-
-    /** Save what a device sees, sorted, so a file changes only when a neighbor does. */
-    static save(stateDirectory: string, device: string, neighbors: readonly Neighbor[]): void {
-        const sorted = [...neighbors].sort((a, b) => Cabling.order(a).localeCompare(Cabling.order(b)));
-        const tidy = sorted.map(({ port, system, remote_port }) => ({ port, system, remote_port }));
-
-        writeFileSync(Cabling.path(stateDirectory, device), JSON.stringify(tidy, null, 4) + "\n");
-    }
-
-    /** Forget what a device saw, when its neighbors could not be read this time. */
-    static forget(stateDirectory: string, device: string): void {
-        rmSync(Cabling.path(stateDirectory, device), { force: true });
-    }
-
-    /** What a device saw at its last snapshot, or undefined when its neighbors were never read. */
-    static load(stateDirectory: string, device: string): Neighbor[] | undefined {
-        const path = Cabling.path(stateDirectory, device);
-        if (!existsSync(path)) return undefined;
-
-        return JSON.parse(readFileSync(path, "utf8")) as Neighbor[];
-    }
-
-    private static order(neighbor: Neighbor): string {
-        return `${neighbor.port} ${neighbor.system} ${neighbor.remote_port}`;
-    }
-
     /** The device runs LLDP somewhere: on every port, on the interfaces it lists, or on a port that turns it on. */
     static runsAnywhere(device: Device): boolean {
-        return Boolean(device.lldp) || Object.values(device.ports ?? {}).some((port) => port?.lldp === true);
+        return Boolean(device.switching?.lldp) || Object.values(device.interfaces?.ethernet ?? {}).some((port) => port?.lldp === true);
     }
 
     /** The port runs LLDP, by the port's own `lldp`, or else the device's. */
     static runsOn(device: Device, port: string): boolean {
-        const own = device.ports?.[port as keyof typeof device.ports]?.lldp;
+        const own = device.interfaces?.ethernet?.[port]?.lldp;
         if (own !== undefined) return own;
 
-        const lldp = device.lldp;
+        const lldp = device.switching?.lldp;
         return lldp === true || (typeof lldp === "object" && (lldp.interfaces as readonly string[]).includes(port));
     }
 
@@ -77,14 +42,14 @@ export class Cabling {
             if (!seen) continue;
 
             const warn = (message: string) => findings.push({ level: "warning", device: device.name, message });
-            const linked = Object.entries(device.ports ?? {}).filter(([, port]) => port?.link);
+            const linked = Object.entries(device.interfaces?.ethernet ?? {}).filter(([, port]) => port?.link);
             const ports = new Set([...linked.map(([name]) => name), ...seen.map((neighbor) => neighbor.port)]);
 
             for (const port of ports) {
                 if (!Cabling.runsOn(device, port)) continue;
 
                 const here = seen.filter((neighbor) => neighbor.port === port);
-                const link = device.ports?.[port as keyof typeof device.ports]?.link;
+                const link = device.interfaces?.ethernet?.[port]?.link;
 
                 if (!link) {
                     for (const neighbor of here) {

package/src/core/graph.ts

@@ -0,0 +1,40 @@
+// The network as a graph: the shapes `Topology` draws, without its code, so Studio's page can share them.
+
+/** One view of the network. Every edge belongs to one. */
+export type Layer = "l1" | "l2" | "l3" | "bgp" | "ospf" | "tunnels";
+
+/** One of our devices, a segment several of them share, or something outside the network. */
+export type GraphNode = {
+    /** Unique among the nodes, such as `device:edge-01` or `as:64501`. */
+    id: string;
+    kind: "device" | "segment" | "outside";
+    /** A word or two, drawn on the node. */
+    label: string;
+    /** One fact per line, for a closer look. */
+    detail: string[];
+};
+
+/** A VLAN a cable carries. */
+export type CarriedVlan = {
+    name: string;
+    id: number;
+    /** Carried without a tag: the access VLAN, or a trunk's native VLAN. */
+    untagged: boolean;
+};
+
+export type GraphEdge = {
+    layer: Layer;
+    /** Node ids. */
+    from: string;
+    to: string;
+    /** A few words, drawn on the edge. */
+    label: string;
+    /** One fact per line, for a closer look. */
+    detail: string[];
+    /** Only one end declares it: the far device does not declare the cable, session or tunnel back. */
+    oneSided?: true;
+    /** On `l2`, the VLANs the cable carries. */
+    vlans?: CarriedVlan[];
+};
+
+export type Graph = { nodes: GraphNode[]; edges: GraphEdge[] };

package/src/{integrations → core}/registries.ts

@@ -1,7 +1,9 @@
-// Registries the framework reads prefix sets from. PeeringDB, which it publishes to, is in ./peeringdb.ts.
+// Registries Circuit reads prefix sets from.
 
-import type { Family } from "../schema";
-import type { Registry } from "../schema/policy";
+import type { Family } from "../model";
+
+/** A registry Circuit fetches prefixes from. */
+export type Registry = "ripe-stat";
 
 export class Registries {
     /** The prefixes of one family a registry gives for a query. */