From 62551e004e380bc67729e7af075f9b3b8b032d5d Mon Sep 17 00:00:00 2001 From: iris Date: Fri, 20 Nov 2026 04:05:25 +0100 Subject: [PATCH] swarm ui: an agent's named ssh connections show in its ssh popover, with add, replace and remove The ssh popover of an opened agent card gets a folded connections section: a table of the agent's named connections (name, user@host:port) with edit and remove, and a form that saves one. The list is read on the first open; a save is a PUT that replaces a connection of the same name, so the button reads replace and a line names the connection when the name exists; remove asks first. The controller's refusal shows under the form as it comes, and the section says the connections are inactive while ssh is off. The request building is in ssh-connections.ts with a test; swarm-ui.md describes the section. --- docs/4-implementation/web-ui/swarm-ui.md | 14 + .../swarm-ui/src/agent/detail/AgentSsh.tsx | 7 +- .../src/agent/detail/AgentSshConnections.css | 31 ++ .../src/agent/detail/AgentSshConnections.tsx | 276 ++++++++++++++++++ .../src/agent/detail/ssh-connections.ts | 61 ++++ .../swarm-ui/test/ssh-connections.test.mjs | 75 +++++ 6 files changed, 462 insertions(+), 2 deletions(-) create mode 100644 frontend/packages/swarm-ui/src/agent/detail/AgentSshConnections.css create mode 100644 frontend/packages/swarm-ui/src/agent/detail/AgentSshConnections.tsx create mode 100644 frontend/packages/swarm-ui/src/agent/detail/ssh-connections.ts create mode 100644 frontend/packages/swarm-ui/test/ssh-connections.test.mjs diff --git a/docs/4-implementation/web-ui/swarm-ui.md b/docs/4-implementation/web-ui/swarm-ui.md index 613cbdecd..546babe9e 100644 --- a/docs/4-implementation/web-ui/swarm-ui.md +++ b/docs/4-implementation/web-ui/swarm-ui.md @@ -925,6 +925,20 @@ when the field changes and the agent signs on its next `ssh`. A `PUT` that leaves `ssh` out, and the `DELETE` of **use the default**, keep it. The controller attaches the signing policy to the agent's login role at once; see [the SSH CA](../swarm/ssh-ca.md#the-switch-and-the-signing-policy). +Below the checkbox, a folded **connections** section holds the agent's named SSH +connections. Each is a `name; user; host; port` entry that becomes `ssh ` in +the agent's ssh config, and its hive lets the agent reach that host and port. A +connection only takes effect while **ssh** is on, and the section says so when the +switch is off. The first time you open the section, it reads `GET +/api/agents/{agent}/ssh-connections`. A table lists the connections as +`user@host:port`, with **edit**, which fills the form, and **remove**, which asks +first and then sends a `DELETE`. The form saves one connection with a `PUT`, which +replaces a connection of the same name, so the button reads **replace** and a line +names the connection when you type a name that one already has. The controller +checks every field, and the form shows its refusal as it arrives. [The SSH CA +page](../swarm/ssh-ca.md) has the rules. The card builds the requests in +`frontend/packages/swarm-ui/src/agent/detail/ssh-connections.ts`. + A saved change isn't instant. The hive reads the grant about every 30 seconds and the agent takes it at its next turn. A change to `manage_root_agent` restarts the agent after its current turn. The card reads diff --git a/frontend/packages/swarm-ui/src/agent/detail/AgentSsh.tsx b/frontend/packages/swarm-ui/src/agent/detail/AgentSsh.tsx index 474854ff2..54305445c 100644 --- a/frontend/packages/swarm-ui/src/agent/detail/AgentSsh.tsx +++ b/frontend/packages/swarm-ui/src/agent/detail/AgentSsh.tsx @@ -1,6 +1,7 @@ // — one agent's SSH access in an opened agent card: a badge that -// opens an explainer, the switch, and a folded "on the target" section with the -// text a machine needs to trust the agent's certificates. +// opens an explainer, the switch, a folded "on the target" section with the text +// a machine needs to trust the agent's certificates, and a folded "connections" +// section for the agent's named connections (`AgentSshConnections`). // // The switch is the `ssh` field of `GET/PUT /api/agents/{name}/permissions`, // shared with the other grant controls through `useGrant`. The CA key comes @@ -17,6 +18,7 @@ import { Button } from "../../ui/button/Button.js"; import { CheckboxField } from "../../ui/checkbox-field/CheckboxField.js"; import { Hint } from "../../ui/hint/Hint.js"; import { Preformatted } from "../../ui/preformatted/Preformatted.js"; +import { AgentSshConnections } from "./AgentSshConnections.js"; import type { GrantState } from "./AgentPermissions.js"; import { forgetHostKeyCommand, @@ -160,6 +162,7 @@ export function AgentSsh({ agent, g }: { agent: string; g: GrantState }) { )} + ); diff --git a/frontend/packages/swarm-ui/src/agent/detail/AgentSshConnections.css b/frontend/packages/swarm-ui/src/agent/detail/AgentSshConnections.css new file mode 100644 index 000000000..3c293c0ce --- /dev/null +++ b/frontend/packages/swarm-ui/src/agent/detail/AgentSshConnections.css @@ -0,0 +1,31 @@ +/* The named SSH connections of an agent card: a table that scrolls on its own on + a narrow screen rather than breaking the popover. */ +.ui-agent-ssh-connections { + display: flex; + flex-direction: column; + gap: 0.75em; + margin-block-start: 0.5em; +} +.ui-agent-ssh-connections-scroll { + overflow-x: auto; +} +.ui-agent-ssh-connections-table { + width: 100%; + border-collapse: collapse; +} +.ui-agent-ssh-connections-table th, +.ui-agent-ssh-connections-table td { + padding: 0.25em 0.75em 0.25em 0; + text-align: start; + white-space: nowrap; +} +.ui-agent-ssh-connections-table thead th { + color: var(--muted); + font-weight: normal; +} +.ui-agent-ssh-connections-table tbody th { + font-weight: 600; +} +.ui-agent-ssh-connections-actions { + text-align: end; +} diff --git a/frontend/packages/swarm-ui/src/agent/detail/AgentSshConnections.tsx b/frontend/packages/swarm-ui/src/agent/detail/AgentSshConnections.tsx new file mode 100644 index 000000000..928a0c940 --- /dev/null +++ b/frontend/packages/swarm-ui/src/agent/detail/AgentSshConnections.tsx @@ -0,0 +1,276 @@ +// — the named SSH connections of one agent, a folded +// section of its SSH popover: a table of them with a remove button each, and a +// form to add one. +// +// A connection is `name; user; host; port`. It becomes an `ssh ` entry in +// the agent's ssh config, and the agent's hive lets it reach that host and port. +// It only takes effect while the agent's ssh switch is on, so the section says +// so when it is off, and stays usable then: the list is what the operator set. +// +// Reads `GET /api/agents/{name}/ssh-connections` when the section is first +// opened. A save is a `PUT` of one connection, which replaces one of the same +// name, so the form says "replace" and names it when the name is taken. A save +// answers the whole list; a remove is a `DELETE`. The controller does all the +// checking, and the form shows its refusal as it arrives. +// +// Its state belongs to one agent: callers key it by agent name. +import { useEffect, useState } from "preact/hooks"; +import { ApiErrorPanel } from "@hive/shared/api-error-panel.js"; +import { readApiError, type ProblemDetails } from "@hive/shared/api-error.js"; +import { Badge } from "@hive/shared/badge.js"; +import { ActionRow } from "../../ui/action-row/ActionRow.js"; +import { Button } from "../../ui/button/Button.js"; +import { useConfirm } from "../../ui/confirm-dialog/useConfirm.js"; +import { FormStack } from "../../ui/form-stack/FormStack.js"; +import { Hint } from "../../ui/hint/Hint.js"; +import { TextField } from "../../ui/text-field/TextField.js"; +import { + connectionBody, + connectionUrl, + connectionsUrl, + replaces, + sortedConnections, + type SshConnection, + type SshConnections, +} from "./ssh-connections.js"; +import "./AgentSshConnections.css"; + +export function AgentSshConnections({ + agent, + on, +}: { + agent: string; + on: boolean; +}) { + // Read on the first open, so a card nobody asks about reads nothing. + const [opened, setOpened] = useState(false); + return ( +
{ + if ((e.currentTarget as HTMLDetailsElement).open) setOpened(true); + }} + > + connections + {opened ? : null} +
+ ); +} + +function Connections({ agent, on }: { agent: string; on: boolean }) { + const [list, setList] = useState(null); + const [loadError, setLoadError] = useState(null); + const [name, setName] = useState(""); + const [user, setUser] = useState(""); + const [host, setHost] = useState(""); + const [port, setPort] = useState("22"); + const [busy, setBusy] = useState(false); + const [problem, setProblem] = useState(null); + const [confirm, confirmDialog] = useConfirm(); + + async function load() { + setLoadError(null); + try { + const r = await fetch(connectionsUrl(agent)); + if (!r.ok) { + setLoadError(await readApiError(r)); + return; + } + setList(((await r.json()) as SshConnections).connections); + } catch (e: unknown) { + setLoadError({ detail: String(e) }); + } + } + useEffect(() => { + void load(); + }, [agent]); + + async function save(e: Event) { + e.preventDefault(); + const body = connectionBody(user, host, port); + if (body === null || name.trim() === "") return; + setBusy(true); + setProblem(null); + try { + const r = await fetch(connectionUrl(agent, name.trim()), { + method: "PUT", + headers: { "content-type": "application/json" }, + body: JSON.stringify(body), + }); + if (!r.ok) { + // The form stays as typed, so the operator can fix it and save again. + setProblem(await readApiError(r)); + return; + } + setList(((await r.json()) as SshConnections).connections); + setName(""); + setUser(""); + setHost(""); + setPort("22"); + } catch (err: unknown) { + setProblem({ detail: String(err) }); + } finally { + setBusy(false); + } + } + + async function remove(c: SshConnection) { + if ( + !(await confirm({ + label: `remove the connection ${c.name}`, + confirmLabel: "remove", + danger: true, + body: ( +

+ Remove {c.name} ({c.user}@{c.host}:{c.port})? {agent}{" "} + can no longer ssh {c.name}, and its hive stops letting + it reach that host. +

+ ), + })) + ) { + return; + } + setBusy(true); + setProblem(null); + try { + const r = await fetch(connectionUrl(agent, c.name), { method: "DELETE" }); + if (!r.ok) { + setProblem(await readApiError(r)); + return; + } + setList((l) => (l ?? []).filter((x) => x.name !== c.name)); + } catch (err: unknown) { + setProblem({ detail: String(err) }); + } finally { + setBusy(false); + } + } + + function edit(c: SshConnection) { + setName(c.name); + setUser(c.user); + setHost(c.host); + setPort(String(c.port)); + setProblem(null); + } + + const replacing = list !== null && replaces(list, name); + const complete = + name.trim() !== "" && connectionBody(user, host, port) !== null; + return ( +
+

+ A named connection is an ssh <name> entry in {agent} + 's ssh config, and its hive lets {agent} reach that host and port. + {on ? null : " Inactive while ssh is off."} +

+ {loadError ? ( + <> + + + + ) : list === null ? ( + reading the connections… + ) : list.length === 0 ? ( + no connections + ) : ( +
+ + + + + + + + + + {sortedConnections(list).map((c) => ( + + + + + + ))} + +
nameconnects to + actions +
{c.name} + {c.user}@{c.host}:{c.port} + + edit(c)} + />{" "} + void remove(c)} + /> +
+
+ )} + void save(e)}> + + + + + {replacing ? ( + + There is already a connection named {name.trim()}; + saving replaces it. + + ) : null} + {problem ? ( + + ) : null} + + + + + {confirmDialog} +
+ ); +} diff --git a/frontend/packages/swarm-ui/src/agent/detail/ssh-connections.ts b/frontend/packages/swarm-ui/src/agent/detail/ssh-connections.ts new file mode 100644 index 000000000..bc80b71a0 --- /dev/null +++ b/frontend/packages/swarm-ui/src/agent/detail/ssh-connections.ts @@ -0,0 +1,61 @@ +// The named SSH connections of an opened agent card: the routes, the body a +// save sends and what the add form says about a name that is already there. +// Kept out of the component so `npm test` can run it. The controller checks +// every field (the name, user and host rules, the ports it refuses, the limit of +// 32), so nothing here repeats those rules: a refusal shows as the controller +// words it. + +/** One connection as `GET /api/agents/{agent}/ssh-connections` carries it. */ +export interface SshConnection { + name: string; + user: string; + host: string; + port: number; +} + +/** The answer of the list route and of a save: the agent's whole list. */ +export interface SshConnections { + connections: SshConnection[]; +} + +export function connectionsUrl(agent: string): string { + return `/api/agents/${encodeURIComponent(agent)}/ssh-connections`; +} + +export function connectionUrl(agent: string, name: string): string { + return `${connectionsUrl(agent)}/${encodeURIComponent(name)}`; +} + +/** The connections in name order, as the table lists them. */ +export function sortedConnections(list: SshConnection[]): SshConnection[] { + return [...list].sort((a, b) => a.name.localeCompare(b.name)); +} + +/** Whether saving `name` replaces a connection the list already has. */ +export function replaces(list: SshConnection[], name: string): boolean { + const wanted = name.trim(); + return list.some((c) => c.name === wanted); +} + +/** + * The port as a whole number from what was typed, or null when it is not one. + * The range and the ports the swarm refuses are the controller's to judge. + */ +export function parsePort(text: string): number | null { + const t = text.trim(); + return /^\d+$/.test(t) ? Number(t) : null; +} + +/** + * The body of a save, or null while a field is empty or the port is not a + * number. The name goes in the URL. + */ +export function connectionBody( + user: string, + host: string, + port: string, +): { user: string; host: string; port: number } | null { + const n = parsePort(port); + if (user.trim() === "" || host.trim() === "" || n === null) return null; + return { user: user.trim(), host: host.trim(), port: n }; +} diff --git a/frontend/packages/swarm-ui/test/ssh-connections.test.mjs b/frontend/packages/swarm-ui/test/ssh-connections.test.mjs new file mode 100644 index 000000000..1b7c163f8 --- /dev/null +++ b/frontend/packages/swarm-ui/test/ssh-connections.test.mjs @@ -0,0 +1,75 @@ +// The named SSH connections of an agent card: URLs, the save body and the +// replace check. Run by `npm test`. +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { + connectionBody, + connectionUrl, + connectionsUrl, + parsePort, + replaces, + sortedConnections, +} from "../src/agent/detail/ssh-connections.ts"; + +const conn = (name, host = "box", port = 22, user = "root") => ({ + name, + user, + host, + port, +}); + +test("the routes carry the agent and the connection name", () => { + assert.equal(connectionsUrl("iris"), "/api/agents/iris/ssh-connections"); + assert.equal( + connectionUrl("iris", "k8s-lab-vm"), + "/api/agents/iris/ssh-connections/k8s-lab-vm", + ); +}); + +test("a name is escaped in the URL", () => { + assert.equal( + connectionUrl("iris", "a/b c"), + "/api/agents/iris/ssh-connections/a%2Fb%20c", + ); +}); + +test("the table lists connections by name", () => { + const list = [conn("zeta"), conn("alpha"), conn("mid")]; + assert.deepEqual( + sortedConnections(list).map((c) => c.name), + ["alpha", "mid", "zeta"], + ); + assert.deepEqual( + list.map((c) => c.name), + ["zeta", "alpha", "mid"], + "the list given is not reordered", + ); +}); + +test("a save replaces a connection with the same name, ignoring spaces typed", () => { + const list = [conn("lab"), conn("prod")]; + assert.equal(replaces(list, "lab"), true); + assert.equal(replaces(list, " lab "), true); + assert.equal(replaces(list, "other"), false); + assert.equal(replaces([], "lab"), false); +}); + +test("a port is a whole number or nothing", () => { + assert.equal(parsePort("2222"), 2222); + assert.equal(parsePort(" 22 "), 22); + assert.equal(parsePort(""), null); + assert.equal(parsePort("22a"), null); + assert.equal(parsePort("-1"), null); + assert.equal(parsePort("2.5"), null); +}); + +test("the body trims the fields and needs all of them", () => { + assert.deepEqual(connectionBody(" root ", " muede-pc2 ", "2222"), { + user: "root", + host: "muede-pc2", + port: 2222, + }); + assert.equal(connectionBody("", "host", "22"), null); + assert.equal(connectionBody("root", " ", "22"), null); + assert.equal(connectionBody("root", "host", "ssh"), null); +});