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); +});