@takodotid/circuit 0.28.1 → 0.29.0

package/dist/chunks/{index-22sbskdx.js → index-47debt16.js}

@@ -117,7 +117,11 @@ function describeDevice(device) {
     const vrf = settings.vrf ? `, VRF ${settings.vrf}` : "";
     return `${name}: ${list.join(", ")}${vrf}`;
   });
-  return [`${device.platform} ${device.model}`, `reached at ${device.connection.host}`, ...addresses];
+  return [
+    `${device.platform} ${device.model}`,
+    device.connection.host ? `reached at ${device.connection.host}` : "reached through its console",
+    ...addresses
+  ];
 }
 function carriedBy(device, settings) {
   const vlan = (name, untagged) => {

package/dist/chunks/{server-1ftkqkx5.js → server-tjbb3rqc.js}

@@ -1,6 +1,6 @@
 import {
   packageRoot
-} from "./index-22sbskdx.js";
+} from "./index-47debt16.js";
 
 // src/studio/server.ts
 import { execFile as execFile2, spawn } from "node:child_process";

package/dist/cli/index.js

@@ -11,7 +11,7 @@ import {
   addressesOf,
   freeOfLength,
   studioData
-} from "../chunks/index-22sbskdx.js";
+} from "../chunks/index-47debt16.js";
 import {
   familyOf2,
   split,
@@ -118,6 +118,11 @@ import { Client as Client2 } from "ssh2";
 
 // src/transport/ssh.ts
 import { Client } from "ssh2";
+function managementHost(device) {
+  if (!device.connection.host)
+    throw new Error(`${device.name} has no management address; it is reached through its console`);
+  return device.connection.host;
+}
 function connect(login) {
   return new Promise((resolve, reject) => {
     const client = new Client;
@@ -2703,7 +2708,7 @@ async function login(device) {
   if (!user)
     throw new Error(`${device.name}: connection user ${device.connection.user} is not one of its users`);
   return connect({
-    host: device.connection.host,
+    host: managementHost(device),
     port: device.connection.port,
     user: device.connection.user,
     password: resolve(user.password)
@@ -3947,7 +3952,8 @@ function sflow(out, device, names) {
   const flow = device.flow_export;
   if (flow?.protocol !== "sflow")
     return;
-  out.set("protocols sflow agent-id", device.connection.host);
+  if (device.connection.host)
+    out.set("protocols sflow agent-id", device.connection.host);
   if (flow.sampling !== undefined)
     out.set("protocols sflow sample-rate ingress", flow.sampling);
   for (const collector of flow.collectors) {
@@ -4521,7 +4527,7 @@ async function login2(device) {
   if (!user)
     throw new Error(`${device.name}: connection user ${device.connection.user} is not one of its users`);
   return connect({
-    host: device.connection.host,
+    host: managementHost(device),
     port: device.connection.port,
     user: device.connection.user,
     password: resolve(user.password)
@@ -5420,7 +5426,7 @@ async function sshShell(device) {
   if (!user)
     throw new Error(`${device.name}: connection user ${device.connection.user} is not one of its users`);
   const client = await connect({
-    host: device.connection.host,
+    host: managementHost(device),
     port: device.connection.port,
     user: device.connection.user,
     password: resolve(user.password),
@@ -7346,7 +7352,7 @@ async function login3(device) {
   if (!user)
     throw new Error(`${device.name}: connection user ${device.connection.user} is not one of its users`);
   return connect({
-    host: device.connection.host,
+    host: managementHost(device),
     port: device.connection.port,
     user: device.connection.user,
     password: resolve(user.password)
@@ -7985,7 +7991,8 @@ function flowExport3(config, device) {
   const flow = device.flow_export;
   if (flow?.protocol !== "sflow")
     return;
-  config.line(`sflow agent ip ${device.connection.host}`);
+  if (device.connection.host)
+    config.line(`sflow agent ip ${device.connection.host}`);
   flow.collectors.forEach((collector, index) => {
     const number = FIRST_COLLECTOR + index;
     config.line(`sflow collector ${number} ip ${collector.address} udp-port ${collector.port ?? 6343}`);
@@ -8051,7 +8058,7 @@ async function login4(device) {
   if (!user)
     throw new Error(`${device.name}: connection user ${device.connection.user} is not one of its users`);
   return connect({
-    host: device.connection.host,
+    host: managementHost(device),
     port: device.connection.port,
     user: device.connection.user,
     password: resolve(user.password),
@@ -8357,8 +8364,9 @@ async function planLibreNms(network) {
   if (!response.ok)
     throw new Error(`LibreNMS answered ${response.status} to the device list`);
   const monitored = new Set((await response.json()).devices.map((device) => device.hostname));
-  const ours = new Set(network.devices.map((device) => device.connection.host));
-  const missing = network.devices.filter((device) => !monitored.has(device.connection.host));
+  const polled = network.devices.filter((device) => device.connection.host);
+  const ours = new Set(polled.map((device) => device.connection.host));
+  const missing = polled.filter((device) => !monitored.has(device.connection.host));
   return {
     additions: missing.filter((device) => device.management?.snmp),
     withoutSnmp: missing.filter((device) => !device.management?.snmp),
@@ -8481,7 +8489,7 @@ var AUTH2 = { sha1: "SHA", sha256: "SHA256" };
 var PRIVACY2 = { aes128: "AES", des: "DES" };
 function prometheusTargets(network) {
   return {
-    targets: network.devices.filter((device) => device.management?.snmp).map((device) => ({
+    targets: network.devices.filter((device) => device.management?.snmp && device.connection.host).map((device) => ({
       targets: [device.connection.host],
       labels: { device: device.name, platform: device.platform, model: device.model, __param_auth: device.name }
     })),
@@ -8838,6 +8846,8 @@ function checkDevice(device, report) {
   };
   if (!device.users?.[device.connection.user])
     report(`connection user '${device.connection.user}' is not one of its users`);
+  if (!device.connection.host && !device.connection.console)
+    report("connection has neither a host nor a console to reach the device through");
   checkVlans(device, report);
   checkAddresses2(device, report, cidr, ip);
   checkPorts(device, names, report);
@@ -9343,9 +9353,12 @@ function one() {
   const [device] = selected(false);
   return device ?? fail("name a device");
 }
+function optionsFor(device) {
+  return options.console || !device.connection.host ? { ...options, console: true } : options;
+}
 function adapterOf(device) {
   const adapter = adapters[device.platform] ?? fail(`no adapter for ${device.platform}`);
-  if (!options.console)
+  if (!optionsFor(device).console)
     return adapter;
   if (!adapter.console)
     fail(`${device.name}: ${device.platform} cannot be reached through a console yet`);
@@ -9419,7 +9432,7 @@ function diffCommand() {
 }
 async function snapshotCommand() {
   for (const device of selected(true)) {
-    const text = await adapterOf(device).read(device, network3.devices, options);
+    const text = await adapterOf(device).read(device, network3.devices, optionsFor(device));
     writeState(device, text);
     console.log(`${device.name}: ${text.split(`
 `).length} lines`);
@@ -9438,7 +9451,7 @@ async function applyCommand() {
   const device = one();
   guard([device]);
   const adapter = adapterOf(device);
-  const live = await adapter.read(device, network3.devices, options);
+  const live = await adapter.read(device, network3.devices, optionsFor(device));
   writeState(device, live);
   const plan = adapter.plan(adapter.render(device), live, options);
   if (!show(device, plan))
@@ -9451,8 +9464,8 @@ Not sent: resolve the problems first.`);
 Nothing sent. Re-run with --confirm.`);
     return;
   }
-  await adapter.apply(device, network3.devices, plan, options);
-  writeState(device, await adapter.read(device, network3.devices, options));
+  await adapter.apply(device, network3.devices, plan, optionsFor(device));
+  writeState(device, await adapter.read(device, network3.devices, optionsFor(device)));
   console.log("snapshot updated");
 }
 async function refreshCommand() {
@@ -9741,7 +9754,7 @@ async function studioCommand() {
   const port = Number(flagValue("port") ?? 4600);
   if (!Number.isInteger(port) || port < 1 || port > 65535)
     fail("--port takes a number from 1 to 65535");
-  const { isLoopback, studio } = await import("../chunks/server-1ftkqkx5.js");
+  const { isLoopback, studio } = await import("../chunks/server-tjbb3rqc.js");
   const host = flagValue("host") ?? "127.0.0.1";
   const allowHosts = (flagValue("allow-host") ?? "").split(",").filter(Boolean);
   if (!isLoopback(host) && !allowHosts.length) {

package/dist/types/schema/device.d.ts

@@ -6,8 +6,8 @@ import type { Routing } from "./routing";
 import type { Certificate, DhcpRelay, DhcpServer, FlowExport, Management, System, User } from "./system";
 /** How the framework reaches the device. */
 export type Connection<U extends string> = {
-    /** Management address. */
-    host: IP;
+    /** Management address. Absent for a device reached only through its console, `console`. */
+    host?: IP;
     /** One of the device's `users`. Its password is the login. */
     user: U;
     /** SSH port. 22 when absent. */

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

@@ -1,4 +1,5 @@
 import { Client, type ClientChannel } from "ssh2";
+import type { Device } from "../schema";
 export type Login = {
     host: string;
     port?: number;
@@ -7,6 +8,8 @@ export type Login = {
     /** Host key algorithms to accept, for a device that negotiates one it then signs wrongly. */
     hostKeys?: string[];
 };
+/** The address SSH reaches a device at. A device without one is reached only through its console. */
+export declare function managementHost(device: Device): string;
 /** Open a session. */
 export declare function connect(login: Login): Promise<Client>;
 /** Run one command and return what it printed, stderr included. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.28.1",
+    "version": "0.29.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/fortios/index.ts

@@ -7,7 +7,7 @@ import { familyOf, host, split } from "../../../core/addr";
 import { MARKER, resolve, valueOfReference } from "../../../core/secrets";
 import type { AclRule, Device, Family, FilterRule } from "../../../schema";
 import { type ConsoleDialect, consoleLogin, consoleOf, openConsole } from "../../../transport/console";
-import { connect, shell } from "../../../transport/ssh";
+import { connect, managementHost, shell } from "../../../transport/ssh";
 import { portsOf, spell } from "../catalog";
 import type { ApplyOptions, DeviceAdapter, Plan, ReadOptions } from "../types";
 import { acceptsBeforeDrop, familiesOf, isImplied, serviceOf } from "./firewall";
@@ -141,7 +141,7 @@ export async function login(device: Device): Promise<Client> {
     if (!user) throw new Error(`${device.name}: connection user ${device.connection.user} is not one of its users`);
 
     return connect({
-        host: device.connection.host,
+        host: managementHost(device),
         port: device.connection.port,
         user: device.connection.user,
         password: resolve(user.password),

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

@@ -7,7 +7,7 @@ import { familyOf, host, isAddress, split } from "../../../core/addr";
 import { resolve, substitute } from "../../../core/secrets";
 import type { Device, Family } from "../../../schema";
 import { type ConsoleDialect, consoleLogin, consoleOf, openConsole } from "../../../transport/console";
-import { connect, exec, readUntil, shell } from "../../../transport/ssh";
+import { connect, exec, managementHost, readUntil, shell } from "../../../transport/ssh";
 import { lagIds } from "../derive";
 import type { ApplyOptions, DeviceAdapter, Plan, ReadOptions, Step } from "../types";
 import { GENERATED, settingsOf } from "./bgp";
@@ -296,7 +296,7 @@ export async function login(device: Device): Promise<Client> {
     if (!user) throw new Error(`${device.name}: connection user ${device.connection.user} is not one of its users`);
 
     return connect({
-        host: device.connection.host,
+        host: managementHost(device),
         port: device.connection.port,
         user: device.connection.user,
         password: resolve(user.password),

package/src/adapters/devices/junos/render.ts

@@ -675,7 +675,7 @@ function sflow(out: Statements, device: Device, names: Names): void {
     const flow = device.flow_export;
     if (flow?.protocol !== "sflow") return;
 
-    out.set("protocols sflow agent-id", device.connection.host);
+    if (device.connection.host) out.set("protocols sflow agent-id", device.connection.host);
     if (flow.sampling !== undefined) out.set("protocols sflow sample-rate ingress", flow.sampling);
 
     for (const collector of flow.collectors) {

package/src/adapters/devices/raisecom-ros/index.ts

@@ -8,7 +8,7 @@ import { marker, resolve, substitute } from "../../../core/secrets";
 import { offset } from "../../../core/time";
 import type { Device, Port, SnmpUser, Switched, Vrrp } from "../../../schema";
 import { type ConsoleDialect, consoleLogin, consoleOf, openConsole } from "../../../transport/console";
-import { connect, readUntil, send, shell } from "../../../transport/ssh";
+import { connect, managementHost, readUntil, send, shell } from "../../../transport/ssh";
 import { portsOf, spell } from "../catalog";
 import { ipv4Networks, lagIds, switchUnsupported } from "../derive";
 import { compare, type Dialect, entries, type Group, scrub, steps, vlanListChange } from "../lines";
@@ -338,7 +338,7 @@ async function sshShell(device: Device): Promise<Session> {
     if (!user) throw new Error(`${device.name}: connection user ${device.connection.user} is not one of its users`);
 
     const client = await connect({
-        host: device.connection.host,
+        host: managementHost(device),
         port: device.connection.port,
         user: device.connection.user,
         password: resolve(user.password),

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

@@ -7,7 +7,7 @@ import { familyOf } from "../../../core/addr";
 import { resolve, substitute } from "../../../core/secrets";
 import type { Device, Family } from "../../../schema";
 import { type ConsoleDialect, consoleLogin, consoleOf, ConsoleShell, openConsole } from "../../../transport/console";
-import { connect, exec, upload } from "../../../transport/ssh";
+import { connect, exec, managementHost, upload } from "../../../transport/ssh";
 import type { ApplyOptions, DeviceAdapter, Plan, ReadOptions } from "../types";
 import { INSTALL_CERTIFICATE, plan } from "./plan";
 import { spell } from "../catalog";
@@ -21,7 +21,7 @@ export async function login(device: Device): Promise<Client> {
     if (!user) throw new Error(`${device.name}: connection user ${device.connection.user} is not one of its users`);
 
     return connect({
-        host: device.connection.host,
+        host: managementHost(device),
         port: device.connection.port,
         user: device.connection.user,
         password: resolve(user.password),

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

@@ -8,7 +8,7 @@ import { marker, resolve, substitute, valueOfReference } from "../../../core/sec
 import { offset } from "../../../core/time";
 import type { Device, Interface, Port, Vrrp } from "../../../schema";
 import { type ConsoleDialect, consoleLogin, consoleOf, openConsole } from "../../../transport/console";
-import { connect, readUntil, send, shell } from "../../../transport/ssh";
+import { connect, managementHost, readUntil, send, shell } from "../../../transport/ssh";
 import { portsOf, spell } from "../catalog";
 import { ipv4Networks, lagIds, switchUnsupported } from "../derive";
 import { compare, type Dialect, scrub, steps, vlanListChange } from "../lines";
@@ -465,7 +465,7 @@ function flowExport(config: Config, device: Device): void {
     const flow = device.flow_export;
     if (flow?.protocol !== "sflow") return;
 
-    config.line(`sflow agent ip ${device.connection.host}`);
+    if (device.connection.host) config.line(`sflow agent ip ${device.connection.host}`);
 
     flow.collectors.forEach((collector, index) => {
         const number = FIRST_COLLECTOR + index;
@@ -550,7 +550,7 @@ export async function login(device: Device): Promise<Client> {
     const user = device.users?.[device.connection.user];
     if (!user) throw new Error(`${device.name}: connection user ${device.connection.user} is not one of its users`);
     return connect({
-        host: device.connection.host,
+        host: managementHost(device),
         port: device.connection.port,
         user: device.connection.user,
         password: resolve(user.password),

package/src/adapters/registries/librenms.ts

@@ -57,8 +57,10 @@ export async function planLibreNms(network: Network): Promise<LibreNmsPlan> {
     if (!response.ok) throw new Error(`LibreNMS answered ${response.status} to the device list`);
 
     const monitored = new Set(((await response.json()) as { devices: { hostname: string }[] }).devices.map((device) => device.hostname));
-    const ours = new Set(network.devices.map((device) => device.connection.host));
-    const missing = network.devices.filter((device) => !monitored.has(device.connection.host));
+    // A device reached only through its console has no address to poll.
+    const polled = network.devices.filter((device) => device.connection.host);
+    const ours = new Set(polled.map((device) => device.connection.host));
+    const missing = polled.filter((device) => !monitored.has(device.connection.host!));
 
     return {
         additions: missing.filter((device) => device.management?.snmp),

package/src/adapters/registries/prometheus.ts

@@ -15,9 +15,9 @@ const PRIVACY = { aes128: "AES", des: "DES" } as const;
 export function prometheusTargets(network: Network): { targets: PrometheusTarget[]; withoutSnmp: Device[] } {
     return {
         targets: network.devices
-            .filter((device) => device.management?.snmp)
+            .filter((device) => device.management?.snmp && device.connection.host)
             .map((device) => ({
-                targets: [device.connection.host],
+                targets: [device.connection.host!],
                 // `__param_auth` picks the device's own auth in snmp_exporter.
                 labels: { device: device.name, platform: device.platform, model: device.model, __param_auth: device.name },
             })),

package/src/cli/index.ts

@@ -133,10 +133,15 @@ function one(): Device {
     return device ?? fail("name a device");
 }
 
-/** The adapter of a device, which must be able to use its console when `--console` asks for it. */
+/** How a device is reached: through its console when `--console` asks, or when it has no management address. */
+function optionsFor(device: Device): ApplyOptions {
+    return options.console || !device.connection.host ? { ...options, console: true } : options;
+}
+
+/** The adapter of a device, which must be able to use its console when the device is reached through it. */
 function adapterOf(device: Device): DeviceAdapter {
     const adapter = adapters[device.platform] ?? fail(`no adapter for ${device.platform}`);
-    if (!options.console) return adapter;
+    if (!optionsFor(device).console) return adapter;
 
     if (!adapter.console) fail(`${device.name}: ${device.platform} cannot be reached through a console yet`);
     if (!device.connection.console) fail(`${device.name}: --console needs connection.console`);
@@ -225,7 +230,7 @@ function diffCommand(): void {
 
 async function snapshotCommand(): Promise<void> {
     for (const device of selected(true)) {
-        const text = await adapterOf(device).read(device, network.devices, options);
+        const text = await adapterOf(device).read(device, network.devices, optionsFor(device));
         writeState(device, text);
         console.log(`${device.name}: ${text.split("\n").length} lines`);
     }
@@ -248,7 +253,7 @@ async function applyCommand(): Promise<void> {
     const adapter = adapterOf(device);
 
     // The plan is made against what the device runs now, never against an old snapshot.
-    const live = await adapter.read(device, network.devices, options);
+    const live = await adapter.read(device, network.devices, optionsFor(device));
     writeState(device, live);
 
     const plan = adapter.plan(adapter.render(device), live, options);
@@ -261,9 +266,9 @@ async function applyCommand(): Promise<void> {
         return;
     }
 
-    await adapter.apply(device, network.devices, plan, options);
+    await adapter.apply(device, network.devices, plan, optionsFor(device));
 
-    writeState(device, await adapter.read(device, network.devices, options));
+    writeState(device, await adapter.read(device, network.devices, optionsFor(device)));
     console.log("snapshot updated");
 }
 

package/src/core/graph.ts

@@ -143,7 +143,11 @@ function describeDevice(device: Device): string[] {
             return `${name}: ${list.join(", ")}${vrf}`;
         });
 
-    return [`${device.platform} ${device.model}`, `reached at ${device.connection.host}`, ...addresses];
+    return [
+        `${device.platform} ${device.model}`,
+        device.connection.host ? `reached at ${device.connection.host}` : "reached through its console",
+        ...addresses,
+    ];
 }
 
 /** The VLANs a port or LAG carries, by id. */

package/src/core/validate.ts

@@ -79,6 +79,8 @@ function checkDevice(device: Device, report: Report): void {
     };
 
     if (!device.users?.[device.connection.user]) report(`connection user '${device.connection.user}' is not one of its users`);
+    if (!device.connection.host && !device.connection.console)
+        report("connection has neither a host nor a console to reach the device through");
 
     checkVlans(device, report);
     checkAddresses(device, report, cidr, ip);

package/src/schema/device.ts

@@ -7,8 +7,8 @@ import type { Certificate, DhcpRelay, DhcpServer, FlowExport, Management, System
 
 /** How the framework reaches the device. */
 export type Connection<U extends string> = {
-    /** Management address. */
-    host: IP;
+    /** Management address. Absent for a device reached only through its console, `console`. */
+    host?: IP;
     /** One of the device's `users`. Its password is the login. */
     user: U;
     /** SSH port. 22 when absent. */

package/src/transport/ssh.ts

@@ -1,6 +1,7 @@
 // SSH sessions to devices. Adapters choose how to talk to their platform; this holds what they share.
 
 import { Client, type ClientChannel } from "ssh2";
+import type { Device } from "../schema";
 
 export type Login = {
     host: string;
@@ -11,6 +12,12 @@ export type Login = {
     hostKeys?: string[];
 };
 
+/** The address SSH reaches a device at. A device without one is reached only through its console. */
+export function managementHost(device: Device): string {
+    if (!device.connection.host) throw new Error(`${device.name} has no management address; it is reached through its console`);
+    return device.connection.host;
+}
+
 /** Open a session. */
 export function connect(login: Login): Promise<Client> {
     return new Promise((resolve, reject) => {