Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

refactor(machines): one connection per machine, and the alias is the target (#597)

Myriad-Dreamin466979a85b06
diff --git a/changelog/unreleased/2026-09-01-machines-connection.md b/changelog/unreleased/2026-09-01-machines-connection.md
new file mode 100644
index 00000000..9cb69ab6
--- /dev/null
+++ b/changelog/unreleased/2026-09-01-machines-connection.md
@@ -0,0 +1,32 @@
+# One connection to a machine, and the alias is the target
+
+- **Date:** 2026-09-01
+- **Type:** refactor
+- **Scope:** `server`
+- **PR:** [#597](https://github.com/Prism-Shadow/penguin-harness/pull/597)
+
+[中文版](2026-09-01-machines-connection.zh.md)
+
+Behind the door the previous change put in front of `machines/` there is now **one connection per machine**, and everything this server says to a machine rides it.
+
+## The connection
+
+`ssh -T -D <port> <alias> sh`, held open — the shape VS Code Remote-SSH holds a host with. Commands go down its stdin and come back on its stdout, framed by a per-session random mark so a command that prints anything cannot forge its own terminator. A script or a tarball goes down the **same stdin** as a base64 heredoc, whose terminator cannot occur in the body. And `-D` makes the session a SOCKS server on a loopback port of ours, so any TCP connection to the machine is a channel inside the same ssh session.
+
+An install is therefore: one command to ask what the machine is, the installer on stdin, the store on stdin, one command to ask what it ended up with — four exchanges on one connection, where before each was its own ssh with its own handshake, plus an `scp`.
+
+That last exchange is the one that decides. An install counts only if the machine reports back **both halves of what would be recorded** — the base release, and the pushed state streamed after it. A step exiting 0 says the step ran, not that the thing on disk over there changed; and a success recorded for a version the machine is not running would leave it out of the very sweep that would have pushed again.
+
+This is **structure, not a budget**: nothing can open a second connection to a machine, however many callers ask and however often, because there is nothing that could; a second ask queues behind the first. Win32 OpenSSH has no ControlMaster, so one connection cannot be had by sharing a socket between ssh processes — it is had by never starting a second one.
+
+**The exception is a Windows remote.** Its sshd hands commands to cmd.exe, and there is no `sh` to hold a session on, so its PowerShell installer keeps a connection of its own (`oneShot`/`copyTo`, serialised per machine). That is stated where the code is, not left to be discovered.
+
+## The alias is the target
+
+`ssh -G` used to run before an install to resolve the alias. Its only consumed output was the user, handed straight back to ssh as `-o User=…` — and ssh reads the same config, so the round trip asked ssh a question to answer ssh with. Host, port, identity files and jump host were parsed and never read. It also cannot tell an unknown alias from a known one (it prints defaults for any name), so the refusal it fed only ever fired on a broken config or a missing ssh binary.
+
+Gone, with the settings parser behind it. An alias is handed to ssh as written, and what it means is ssh's to apply from its own config every time — nothing here can go stale against a file a person edits. Listing the aliases in the config stays; that is the only thing this app takes from it.
+
+## Compatibility
+
+`POST …/machines/:id/install` no longer answers `502 unresolvable_host`. A config ssh cannot use is reported in ssh's own words, when the connection is opened.
diff --git a/changelog/unreleased/2026-09-01-machines-connection.zh.md b/changelog/unreleased/2026-09-01-machines-connection.zh.md
new file mode 100644
index 00000000..0d8755cd
--- /dev/null
+++ b/changelog/unreleased/2026-09-01-machines-connection.zh.md
@@ -0,0 +1,32 @@
+# 通往一台机器的一条连接,以及「别名就是目标」
+
+- **Date:** 2026-09-01
+- **Type:** refactor
+- **Scope:** `server`
+- **PR:** [#597](https://github.com/Prism-Shadow/penguin-harness/pull/597)
+
+[English](2026-09-01-machines-connection.md)
+
+在上一处改动立在 `machines/` 前面的那道门之后,现在**每台机器只有一条连接**,本服务端对一台机器说的一切都走它。
+
+## 这条连接
+
+`ssh -T -D <端口> <alias> sh`,常驻——VS Code Remote-SSH 持有主机用的就是这个形状。命令从它的 stdin 进去、stdout 回来,由每个会话各自随机的标记定帧,因此命令无论打印什么都伪造不出自己的终止符。脚本或 tar 包以 base64 heredoc 的形式走**同一个 stdin**,其终止符不可能出现在正文里。而 `-D` 让这个会话同时是我们某个 loopback 端口上的 SOCKS 服务器,于是通往机器的任何 TCP 连接都成了同一个 ssh 会话内部的一个 channel。
+
+于是一次安装就是:问一句这是什么机器、安装器走 stdin、store 走 stdin、再问一句它最后成了什么——一条连接上的四次往返;而在此之前,每一步都是各自的一次 ssh、各自的一次握手,外加一次 `scp`。
+
+最后那一次往返才是做决定的一次。只有当机器把**将被记下来的两半都报回来**——基础发行版,以及随后推过去的那份推送态——这次安装才算数。某一步退出码为 0,说明的是那一步跑过了,而不是对面磁盘上的东西真的变了;把机器记成一个它并没有在跑的版本,会让它被排除在本该再推一次的那轮扫描之外。
+
+这是**结构,不是配额**:不管多少调用者要、要多少次,都开不出对同一台机器的第二条连接,因为根本没有能开出它的东西;第二个请求排在第一个后面。Win32 OpenSSH 没有 ControlMaster,所以「一条连接」不能靠多个 ssh 进程共享套接字得到——靠的是从不启动第二个进程。
+
+**例外是 Windows 远端。** 它的 sshd 把命令交给 cmd.exe,没有 `sh` 可以用来持有会话,因此它的 PowerShell 安装器自带一条连接(`oneShot`/`copyTo`,按机器串行)。这一点写在代码所在处,而不是留给人去发现。
+
+## 别名就是目标
+
+过去安装前会跑一次 `ssh -G` 来解析别名。它唯一被用到的输出是 user,而这个值又被原样以 `-o User=…` 交回给 ssh——ssh 读的是同一份配置,于是这一趟等于问了 ssh 一个问题,再用它的答案回答 ssh。主机、端口、身份文件、跳板机被解析出来,从来没有人读。它也分辨不出别名是否存在(对任何名字都会打印一份默认配置),所以由它喂出的那个拒绝码,实际上只在配置写坏或 ssh 不在 PATH 上时才会触发。
+
+它和它背后的设置解析器一起删掉了。别名原样交给 ssh,它的含义由 ssh 每次按自己的配置重新决定——这里不会有任何东西对着一个人随时在改的文件过期。列出配置里的别名保留;那是本应用从这份文件里拿走的唯一东西。
+
+## 兼容性
+
+`POST …/machines/:id/install` 不再返回 `502 unresolvable_host`。ssh 用不了的配置,会在连接打开时以 ssh 自己的话报出来。
diff --git a/packages/server/src/http/routes/machines.ts b/packages/server/src/http/routes/machines.ts
index 5b5a9a75..c4bce8e7 100644
--- a/packages/server/src/http/routes/machines.ts
+++ b/packages/server/src/http/routes/machines.ts
@@ -70,17 +70,10 @@ export function machinesRoutes(deps: AppDeps): Hono<AppEnv> {
if (started.why === "unknown-machine") {
throw new HttpError(404, "unknown_machine", "No such host in this server's ssh config.");
}
- if (started.why === "no-image") {
- throw new HttpError(
- 409,
- "no_install_image",
- "This server has no install image to push. A packaged or installed server carries one; a development checkout gets one from its first hot push.",
- );
- }
throw new HttpError(
- 502,
- "unresolvable_host",
- "ssh could not resolve that host. Check ~/.ssh/config, or that ssh is on PATH.",
+ 409,
+ "no_install_image",
+ "This server has no install image to push. A packaged or installed server carries one; a development checkout gets one from its first hot push.",
);
}
return c.json(state(c), 202);
diff --git a/packages/server/src/machines/commands.ts b/packages/server/src/machines/commands.ts
index c2e5178e..9d6f4691 100644
--- a/packages/server/src/machines/commands.ts
+++ b/packages/server/src/machines/commands.ts
@@ -9,11 +9,12 @@
* itself is the ordinary one (install.sh, install.ps1), downloading the pinned release from
* the remote's own network.
*
- * COUNT THE HANDSHAKES. Every one of these is a separate ssh connection, and a handshake to
- * a distant or loaded host costs tens of seconds — so a step that can ride an existing
- * connection must. A POSIX install is one call: the installer goes in on ssh's stdin, the
- * same shape as the documented `curl … | sh`, which is what lets the scratch directory, the
- * scp and the cleanup disappear entirely.
+ * COUNT THE HANDSHAKES. A handshake to a distant or loaded host costs tens of seconds — so
+ * everything rides the ONE connection ssh-session.ts holds per machine: commands, the
+ * installer and the store on its stdin, every TCP connection through its SOCKS port. A POSIX
+ * install is therefore the installer going in on that stdin, the same shape as the documented
+ * `curl … | sh`, which is what lets the scratch directory, the scp and the cleanup disappear
+ * entirely.
*
* Two further rules encoded here:
* - **BatchMode.** A GUI app has no terminal: an ssh that decides to ask for a password or a
@@ -107,15 +108,52 @@ export function runInstallScriptCommand(
/**
* Unpacks the replicated hmr state (harness.json + store/), streamed to ssh's stdin as one
- * tar.gz, into the remote's default data root — where a server this page installed will look
- * for it on boot (hmr/host.ts's restore). `tar` reads stdin with `-f -` on both sides;
+ * tar.gz, into the remote's HMR DIRECTORY. `tar` reads stdin with `-f -` on both sides;
* Windows 10+ ships bsdtar.
+ *
+ * `<data root>/hmr`, not the data root itself: the members are named relative to the sending
+ * side's own hmr directory (install-server.ts tars `-C <root>/hmr harness.json store`), so
+ * the two `-C` arguments have to name the same layer. Extracting one directory too high
+ * writes a `harness.json` and a `store/` that nothing reads — hmr/host.ts fixes the layout at
+ * `<root>/hmr` — and the machine goes on answering with whatever it held before, so the
+ * replication reports success and achieves nothing.
*/
export function unpackStoreCommand(platform: RemotePlatform): string {
if (platform === "win32") {
- const root = "%USERPROFILE%\\.penguin\\data";
+ const root = "%USERPROFILE%\\.penguin\\data\\hmr";
return `(if not exist ${cmdQuote(root)} mkdir ${cmdQuote(root)}) & tar -xzf - -C ${cmdQuote(root)}`;
}
- const root = "$HOME/.penguin/data";
+ const root = "$HOME/.penguin/data/hmr";
return `mkdir -p "${root}" && tar -xzf - -C "${root}"`;
}
+
+// --- tunnelling to that server ---------------------------------------------------------------
+
+/**
+ * `ssh -T -D 127.0.0.1:<port> <alias> sh` — the ONE connection to a machine (transport/
+ * ssh-session.ts). `-T` because it is a command channel, not a terminal; `sh` rather than a
+ * login shell, so a profile's banner cannot land in the first command's output; `-D` so the
+ * session doubles as a SOCKS server on a loopback port of ours, through which every TCP
+ * connection to the machine is a channel inside this same session. ExitOnForwardFailure turns
+ * "local port taken" into an exit instead of a session that silently cannot dial, and the
+ * keepalives surface a dead link within a minute.
+ */
+export function sessionArgs(target: RemoteTarget, socksPort: number): string[] {
+ if (!Number.isInteger(socksPort) || socksPort < 1 || socksPort > 65535) {
+ throw new Error(`bad port ${socksPort}`);
+ }
+ return [
+ ...connectionOptions(target),
+ "-T",
+ "-o",
+ "ExitOnForwardFailure=yes",
+ "-o",
+ "ServerAliveInterval=15",
+ "-o",
+ "ServerAliveCountMax=4",
+ "-D",
+ `127.0.0.1:${socksPort}`,
+ target.alias,
+ "sh",
+ ];
+}
diff --git a/packages/server/src/machines/install-server.ts b/packages/server/src/machines/install-server.ts
index 5470b0ec..edcb0bef 100644
--- a/packages/server/src/machines/install-server.ts
+++ b/packages/server/src/machines/install-server.ts
@@ -22,11 +22,12 @@ import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";
-import { runInstallScriptCommand, scpArgs, sshArgs, unpackStoreCommand } from "./commands.js";
+import { runInstallScriptCommand, unpackStoreCommand } from "./commands.js";
import type { RemoteTarget } from "./commands.js";
import { parseProbeOutput, POSIX_PROBE, WINDOWS_PROBE } from "./detect.js";
import type { RemoteIdentity, RemotePlatform } from "./detect.js";
-import { looksLikeAuthFailure, run, runPiped, runWithInput } from "./transport/index.js";
+import { connectionTo, looksLikeAuthFailure, runBytes } from "./transport/index.js";
+import type { MachineChannel } from "./transport/index.js";
/** Which installer runs the far side; also the asset keys deploy.mjs pushes. */
const installerFileFor = (platform: RemotePlatform): string =>
@@ -141,33 +142,39 @@ function baseReleaseVersion(argv1: string | undefined): string | null {
}
/**
- * Asks the machine what it is. POSIX first; a cmd.exe host answers that with an error, which
- * parses as "not a machine I recognize", and the Windows form is tried next. Two round trips
- * at worst, once per connect.
+ * Asks the machine what it is. POSIX first, over the session — the only round trip a POSIX
+ * host ever costs. A cmd.exe host has no `sh` to hold a session on, so the session dies
+ * unopened and the Windows form is asked on a connection of its own. Two round trips at
+ * worst, once per connect.
*/
export async function detectRemote(
target: RemoteTarget,
+ channel?: MachineChannel,
): Promise<{ identity: RemoteIdentity } | { error: string }> {
- for (const probe of [POSIX_PROBE, WINDOWS_PROBE]) {
- const result = await run("ssh", sshArgs(target, probe), { timeoutMs: 30_000 });
- const identity = parseProbeOutput(result.stdout);
- if (identity) return { identity };
- if (result.code !== 0 && looksLikeAuthFailure(result)) {
- return {
- error: `${result.stderr.trim()}\n\nConnections use BatchMode: set up key or agent authentication for that host first.`,
- };
- }
- // A connection-level failure is fatal for both probes; only an unrecognized ANSWER is
- // worth retrying in the other shell's dialect.
- if (result.code !== 0 && result.stdout.trim() === "" && result.stderr.trim() !== "") {
- const stderr = result.stderr.trim();
- if (!/not recognized|command not found|is not recognized/i.test(stderr)) {
- return { error: stderr };
- }
- }
+ const conn = channel ?? connectionTo(target);
+ const posix = await conn.exec(POSIX_PROBE);
+ const identity = parseProbeOutput(posix.stdout);
+ if (identity) return { identity };
+ // The session's output is merged, so ssh's own words arrive as stdout.
+ const said = posix.stdout.trim();
+ if (posix.code !== 0 && looksLikeAuthFailure({ ...posix, stderr: said })) {
+ return {
+ error: `${said}\n\nConnections use BatchMode: set up key or agent authentication for that host first.`,
+ };
}
+ const windows = await conn.oneShot(WINDOWS_PROBE, { timeoutMs: 30_000 });
+ const identityWin = parseProbeOutput(windows.stdout);
+ if (identityWin) return { identity: identityWin };
+ if (windows.code !== 0 && looksLikeAuthFailure(windows)) {
+ return {
+ error: `${windows.stderr.trim()}\n\nConnections use BatchMode: set up key or agent authentication for that host first.`,
+ };
+ }
+ const words = said || windows.stderr.trim();
return {
- error: "Could not tell what that machine is: neither the POSIX nor the Windows probe answered.",
+ error:
+ "Could not tell what that machine is: neither the POSIX nor the Windows probe answered." +
+ (words === "" ? "" : ` It said: ${words}`),
};
}
@@ -189,14 +196,17 @@ export async function installOnRemote(opts: {
identity?: RemoteIdentity;
/** The hmr capability's assetsDir accessor: where a pushed bundle's assets were unpacked. */
assets?: () => string | null;
+ /** The channel to the machine; a test hands in a scripted one. */
+ channel?: MachineChannel;
}): Promise<RemoteInstallOutcome> {
const { target, plan } = opts;
+ const conn = opts.channel ?? connectionTo(target);
const say = opts.onProgress ?? (() => {});
let identity = opts.identity;
if (identity === undefined) {
say("Asking what that machine is…");
- const detected = await detectRemote(target);
+ const detected = await detectRemote(target, conn);
if ("error" in detected) return { kind: "failed", step: "connect", detail: detected.error };
identity = detected.identity;
say(`${identity.platform}-${identity.arch}.`);
@@ -251,7 +261,7 @@ export async function installOnRemote(opts: {
const local = path.join(os.tmpdir(), name);
fs.writeFileSync(local, installer);
windowsTmp = { local, remote: `%USERPROFILE%\\${name}` };
- const copy = await run("scp", scpArgs(target, [local], "."));
+ const copy = await conn.copyTo([local], ".");
if (copy.code !== 0) {
return { kind: "failed", step: "copy", detail: copy.stderr.trim() || "scp failed" };
}
@@ -260,14 +270,12 @@ export async function installOnRemote(opts: {
where = { platform: identity.platform };
}
const step = runInstallScriptCommand(`v${plan.baseVersion}`, where);
- // One connection when the script rides stdin, and the far side's own progress is
- // relayed as it arrives rather than after the minutes an install can take.
+ // The script rides the session's stdin as a heredoc, and the far side's own progress
+ // is relayed as it arrives rather than after the minutes an install can take. A Windows
+ // host runs its copied script on a connection of its own (no session to ride).
const install = step.scriptOnStdin
- ? await runWithInput("ssh", sshArgs(target, step.command), {
- input: installer,
- onLine: say,
- })
- : await run("ssh", sshArgs(target, step.command));
+ ? await conn.stream(step.command, { input: installer, onLine: say })
+ : await conn.oneShot(step.command);
if (install.code !== 0) {
return {
kind: "failed",
@@ -280,22 +288,84 @@ export async function installOnRemote(opts: {
if (plan.hmrDir !== null && identity.harness !== plan.harness) {
say("Replicating the pushed version…");
- // harness.json and store/ only: uploads/ is this machine's scratch, not state.
- const sync = await runPiped(
- { file: "tar", args: ["-czf", "-", "-C", plan.hmrDir, "harness.json", "store"] },
- { file: "ssh", args: sshArgs(target, unpackStoreCommand(identity.platform)) },
- );
+ // harness.json and store/ only: uploads/ is this machine's scratch, not state. Packed
+ // here, then handed to the machine's tar on the session's stdin.
+ const packed = await runBytes("tar", [
+ "-czf",
+ "-",
+ "-C",
+ plan.hmrDir,
+ "harness.json",
+ "store",
+ ]);
+ if (packed.code !== 0) {
+ return {
+ kind: "failed",
+ step: "replicate the pushed version",
+ detail: packed.stderr.trim() || `tar exited ${packed.code}`,
+ };
+ }
+ const unpack = unpackStoreCommand(identity.platform);
+ const sync =
+ identity.platform === "win32"
+ ? await conn.oneShot(unpack, { input: packed.stdout })
+ : await conn.stream(unpack, { input: packed.stdout });
if (sync.code !== 0) {
return {
kind: "failed",
step: "replicate the pushed version",
- detail: sync.stderr.trim() || `tar | ssh exited ${sync.code}`,
+ detail:
+ `${sync.stdout.trim()}\n${sync.stderr.trim()}`.trim() || `tar exited ${sync.code}`,
};
}
output.push(`Pushed version replicated (${plan.version}).`);
}
- return { kind: "installed", output: output.join("\n").trim(), identity };
+ // ASK THE MACHINE what it now has, rather than reporting what we meant to put there.
+ // Every step above answers for itself — the installer exited 0, the store unpacked — and
+ // none of them answers the only question that matters, which is whether the thing on
+ // disk over there is now this version. An install that ran cleanly and changed nothing
+ // (wrong home, a package manager that declined, a path the installer did not own) would
+ // otherwise be recorded as a success at OUR version, and that record is what
+ // syncOutOfDate filters on: the machine is then excluded from the very sweep that would
+ // have tried again. A false success here does not just mislead, it seals itself in.
+ say("Checking what it ended up with…");
+ const after = await detectRemote(target, conn);
+ if ("error" in after) {
+ return {
+ kind: "failed",
+ step: "verify the install",
+ detail: `the install ran, but the machine could not be asked what it now has: ${after.error}`,
+ };
+ }
+ if (after.identity.installedVersion !== plan.baseVersion) {
+ return {
+ kind: "failed",
+ step: "verify the install",
+ detail:
+ `the install reported success, but the machine still has ` +
+ `${after.identity.installedVersion ?? "no install"} where ${plan.baseVersion} was expected.`,
+ };
+ }
+ // The base is only half of what gets recorded. A plan carrying a pushed state is recorded
+ // at `plan.version`, which is the base plus that state's content sha — so a store whose
+ // unpack exited 0 without landing (a partial tarball, a data root somewhere else, a
+ // harness.json the far side could not replace) would seal the machine in at a version it
+ // is not running. This is the comparison the entry gate above already makes; the machine
+ // has to still make it true afterwards. Scoped to a plan that HAD a pushed state: a
+ // base-only install neither carries nor removes one, and must not be failed for a remote
+ // hmr directory it was never asked to touch.
+ if (plan.hmrDir !== null && after.identity.harness !== plan.harness) {
+ return {
+ kind: "failed",
+ step: "verify the install",
+ detail:
+ "the install reported success, but the pushed version is not what the machine ended " +
+ `up with: it reports ${after.identity.harness === null ? "no pushed state" : "a different one"}.`,
+ };
+ }
+
+ return { kind: "installed", output: output.join("\n").trim(), identity: after.identity };
} finally {
// Nothing to clean on a POSIX remote: the installer was never a file there. A Windows
// one deletes its own copy as part of the install command; this is the local original.
diff --git a/packages/server/src/machines/service.ts b/packages/server/src/machines/service.ts
index b7dd1dc9..48d164ca 100644
--- a/packages/server/src/machines/service.ts
+++ b/packages/server/src/machines/service.ts
@@ -26,12 +26,12 @@
* 30 MB transfer to reach the same place.
*/
import type { MachineInfo, MachineInstallJob } from "../api/types.js";
-import { listHostAliases, resolveTarget } from "./transport/index.js";
+import { listHostAliases } from "./transport/index.js";
import { installOnRemote, resolvePushPlan } from "./install-server.js";
import type { MachinesRepo } from "../db/repos/machines.js";
/** Why a start was refused before any ssh ran. */
-export type InstallRefusal = "busy" | "unknown-machine" | "unresolvable" | "no-image";
+export type InstallRefusal = "busy" | "unknown-machine" | "no-image";
/**
* The three things this service does to the world, injectable as a set. Production passes
@@ -42,7 +42,6 @@ export type InstallRefusal = "busy" | "unknown-machine" | "unresolvable" | "no-i
*/
export interface MachinesEffects {
listAliases: typeof listHostAliases;
- resolveTarget: typeof resolveTarget;
resolvePlan: typeof resolvePushPlan;
install: typeof installOnRemote;
/** Injected so a test can pin the recorded timestamp instead of asserting around the clock. */
@@ -66,7 +65,6 @@ export class MachinesService {
this.#assets = assets;
this.#effects = {
listAliases: listHostAliases,
- resolveTarget,
resolvePlan: resolvePushPlan,
install: installOnRemote,
now: () => new Date(),
@@ -159,9 +157,6 @@ export class MachinesService {
const plan = this.#effects.resolvePlan(this.dataRoot);
if (plan === null) return { ok: false, why: "no-image" };
- const resolved = await this.#effects.resolveTarget(alias);
- if (resolved === null) return { ok: false, why: "unresolvable" };
-
const job: MachineInstallJob = {
machineId,
alias,
@@ -179,11 +174,13 @@ export class MachinesService {
// path does not turn into a `failed` outcome itself.
void (async () => {
try {
- say(`Installing ${plan.version} on ${resolved.machine}…`);
+ say(`Installing ${plan.version} on ${alias}…`);
// No identity passed: installOnRemote runs the probe itself as its first step and
// narrates it, so the page shows what the machine turned out to be.
const outcome = await this.#effects.install({
- target: { alias, user: resolved.settings.user },
+ // The alias IS the target: what it means — user, host, port, key, jump host — is
+ // ssh's to resolve, from its own config, every time it is handed the alias.
+ target: { alias, user: "" },
plan,
onProgress: say,
assets: this.#assets,
diff --git a/packages/server/src/machines/ssh-config.ts b/packages/server/src/machines/ssh-config.ts
index c3e0cbf7..ca108195 100644
--- a/packages/server/src/machines/ssh-config.ts
+++ b/packages/server/src/machines/ssh-config.ts
@@ -1,20 +1,16 @@
/**
- * Reading `~/.ssh/config` — the only source of remote targets. We never write it, never
- * keep a host list of our own, and never re-implement OpenSSH's matching rules: this module
- * does exactly two things, both pure so they unit-test without a filesystem or an ssh binary.
+ * Reading `~/.ssh/config` for its host aliases — the only thing this app takes from it. We
+ * never write it, never keep a host list of our own, and never resolve it: what an alias
+ * means (user, host, port, key, jump host) is ssh's business, applied by ssh itself every
+ * time it is handed the alias, so nothing here can go stale against a config a person edits.
*
- * 1. `parseHostAliases` scans the config text for candidate aliases, following `Include`
- * through a caller-supplied reader. It exists only because OpenSSH has no "list hosts"
- * command and the UI needs something to show. Pattern entries (`*`, `?`, `!`) are skipped:
- * they configure other hosts rather than name one.
- * 2. `parseSshSettings` reads the output of `ssh -G <alias>`, which is OpenSSH's own answer
- * to "what does this alias actually resolve to" — Match blocks, Include, wildcard
- * inheritance and defaults all already applied.
+ * `parseHostAliases` scans the config text for candidate aliases, following `Include`
+ * through a caller-supplied reader. It exists only because OpenSSH has no "list hosts"
+ * command and the UI needs something to show. Pattern entries (`*`, `?`, `!`) are skipped:
+ * they configure other hosts rather than name one. Pure, so it unit-tests without a
+ * filesystem.
*/
-/** One line of `ssh -G` output: a lowercase keyword, a space, the value. */
-const SSH_G_LINE = /^([a-z0-9_]+)\s+(.*)$/;
-
/** Config keywords that introduce host blocks; matched case-insensitively, as ssh does. */
const HOST_KEYWORD = /^host\s+(.*)$/i;
const INCLUDE_KEYWORD = /^include\s+(.*)$/i;
@@ -57,46 +53,6 @@ export function parseHostAliases(
return [...new Set(out)];
}
-/** The parts of `ssh -G` output this app uses; everything else in that output is ignored. */
-export interface SshSettings {
- /** The login user ssh would use — part of a target's identity, not a detail. */
- user: string;
- hostname: string;
- port: number;
- /** May be empty: an agent-only setup declares no identity file. */
- identityFiles: string[];
- /** `none` in ssh's output becomes null. */
- proxyJump: string | null;
-}
-
-/**
- * Parses `ssh -G <alias>`. Absent or malformed fields fall back to ssh's own defaults
- * rather than throwing: this feeds a host picker, and a config we cannot fully read should
- * degrade to "looks like the alias itself on port 22", not to an error dialog.
- */
-export function parseSshSettings(output: string, alias: string): SshSettings {
- const values = new Map<string, string[]>();
- for (const raw of output.split("\n")) {
- const match = SSH_G_LINE.exec(raw.trim());
- if (!match) continue;
- const key = match[1]!;
- const value = match[2]!.trim();
- const existing = values.get(key);
- if (existing) existing.push(value);
- else values.set(key, [value]);
- }
- const first = (key: string): string | null => values.get(key)?.[0] ?? null;
- const port = Number(first("port"));
- const proxyJump = first("proxyjump");
- return {
- user: first("user") ?? "",
- hostname: first("hostname") ?? alias,
- port: Number.isInteger(port) && port > 0 && port <= 65535 ? port : 22,
- identityFiles: values.get("identityfile") ?? [],
- proxyJump: proxyJump === null || proxyJump.toLowerCase() === "none" ? null : proxyJump,
- };
-}
-
/**
* A remote target's stable name: the SSH identity, `<user>@<alias>`. The Linux account is
* part of it because each account has its own `~/.penguin` — hence its own server, its own
diff --git a/packages/server/src/machines/transport/connection.ts b/packages/server/src/machines/transport/connection.ts
new file mode 100644
index 00000000..e146e67d
--- /dev/null
+++ b/packages/server/src/machines/transport/connection.ts
@@ -0,0 +1,125 @@
+/**
+ * One mouth per machine, and behind it ONE CONNECTION: every word this server speaks to a
+ * machine leaves through the MachineConnection for that machine's address, and everything
+ * it carries rides the single `ssh -T -D` session ssh-session.ts holds — a probe as a
+ * command on its stdin, an installer or a tarball as a heredoc on the same stdin, the
+ * machine's API as a channel dialled through the session's SOCKS port (socks.ts). There is
+ * no forward process, no one-shot ssh per step, no scp: nothing opens a second connection
+ * to a machine, however many callers ask and however often, because there is nothing that
+ * could.
+ *
+ * The guarantee is AUTHORITY first — nothing outside machines/transport/ may open ssh, and
+ * machines-transport-boundary.test.ts pins that — and then STRUCTURE: the connection is one,
+ * and a second ask queues behind the first. The incident behind this seam (#561) grew where
+ * it was absent — four call sites each opened their own channel, each judged the machine's
+ * liveness from its own channel's state, and the judgements disagreed.
+ *
+ * THE ONE EXCEPTION is a Windows remote: sshd there hands commands to cmd.exe, and there is no
+ * `sh` to hold a session on. `oneShot` and `copyTo` exist for that host alone — an install
+ * runs the PowerShell installer on its own connection — and a Windows machine cannot be
+ * connected (no session, no SOCKS, no API) until it has a shell to hold. Serialised per
+ * machine all the same (lane.ts).
+ *
+ * The handle is stateless on purpose: per-machine state stays in ssh-session.ts, keyed by
+ * address, so holding a MachineConnection costs nothing and dropping one leaks nothing. The
+ * address is always `ssh:<alias>` — the one spelling every registry in machines/ uses.
+ */
+import { run, runWithInput } from "./exec.js";
+import { closeShell, openShell, runOnShell, sessionOf } from "./ssh-session.js";
+import type { ShellSession } from "./ssh-session.js";
+import { inLane } from "./lane.js";
+import { scpArgs, sshArgs } from "../commands.js";
+import type { ExecResult } from "./exec.js";
+import type { RemoteTarget } from "../commands.js";
+
+/**
+ * The verbs a caller speaks to a machine with — what install-server.ts is written against,
+ * so a test can hand it a scripted channel instead of a real one.
+ */
+export interface MachineChannel {
+ exec(command: string): Promise<ExecResult>;
+ stream(
+ command: string,
+ opts: { input: Buffer; onLine?: (line: string) => void; timeoutMs?: number },
+ ): Promise<ExecResult>;
+ oneShot(command: string, opts?: { timeoutMs?: number; input?: Buffer }): Promise<ExecResult>;
+ copyTo(localFiles: string[], remoteDir: string): Promise<ExecResult>;
+}
+
+/** Enough for an installer to download a release, or a store to cross a slow link. */
+const BULK_TIMEOUT_MS = 10 * 60_000;
+
+export class MachineConnection implements MachineChannel {
+ readonly address: string;
+
+ constructor(readonly target: RemoteTarget) {
+ this.address = `ssh:${target.alias}`;
+ }
+
+ /** A command over the session — queued, output merged (ssh-session.ts), in ExecResult shape. */
+ async exec(command: string): Promise<ExecResult> {
+ const result = await runOnShell(this.address, this.target, command);
+ return { code: result.code, stdout: result.output, stderr: "", timedOut: false };
+ }
+
+ /**
+ * A command that reads `input` from its stdin — an installer script, a tarball — over the
+ * same session, as a heredoc. `onLine` relays the far side's progress as it arrives.
+ */
+ async stream(
+ command: string,
+ opts: { input: Buffer; onLine?: (line: string) => void; timeoutMs?: number },
+ ): Promise<ExecResult> {
+ const result = await runOnShell(this.address, this.target, command, {
+ input: opts.input,
+ ...(opts.onLine === undefined ? {} : { onLine: opts.onLine }),
+ timeoutMs: opts.timeoutMs ?? BULK_TIMEOUT_MS,
+ });
+ return { code: result.code, stdout: result.output, stderr: "", timedOut: false };
+ }
+
+ /** Brings the session up, or says why it cannot be. */
+ open(): Promise<{ ok: true; session: ShellSession } | { ok: false; detail: string }> {
+ return openShell(this.address, this.target);
+ }
+
+ /** The session while it is up. */
+ session(): ShellSession | null {
+ return sessionOf(this.address);
+ }
+
+ /**
+ * WINDOWS REMOTES ONLY (see the module doc): a command on its own ssh connection, with an
+ * optional stdin payload. Serialised per machine.
+ */
+ oneShot(command: string, opts: { timeoutMs?: number; input?: Buffer } = {}): Promise<ExecResult> {
+ const args = sshArgs(this.target, command);
+ return inLane(this.address, () =>
+ opts.input !== undefined
+ ? runWithInput("ssh", args, {
+ input: opts.input,
+ ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
+ })
+ : run("ssh", args, opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
+ );
+ }
+
+ /** WINDOWS REMOTES ONLY: local files copied into a remote directory over scp. Serialised per machine. */
+ copyTo(localFiles: string[], remoteDir: string): Promise<ExecResult> {
+ return inLane(this.address, () => run("scp", scpArgs(this.target, localFiles, remoteDir)));
+ }
+}
+
+/** The machine's connection handle. Cheap: state lives in the per-address registry. */
+export function connectionTo(target: RemoteTarget): MachineConnection {
+ return new MachineConnection(target);
+}
+
+/**
+ * Lets go of the connection to a machine. By address rather than on the handle: a disconnect
+ * can outlive the resolvability of its target (an alias removed from the ssh config still
+ * has a session to close).
+ */
+export function closeConnectionTo(address: string): void {
+ closeShell(address);
+}
diff --git a/packages/server/src/machines/transport/exec.ts b/packages/server/src/machines/transport/exec.ts
index 38811690..556e6a84 100644
--- a/packages/server/src/machines/transport/exec.ts
+++ b/packages/server/src/machines/transport/exec.ts
@@ -16,6 +16,13 @@ export interface ExecResult {
code: number;
stdout: string;
stderr: string;
+ /**
+ * True when we killed it for running past its budget. Worth its own flag because a
+ * timeout is otherwise INDISTINGUISHABLE from a refusal: the child is killed before it
+ * says anything, so the result is a non-zero code with empty stderr — which reads as
+ * "the remote said no" when the truth is "the remote never answered in time".
+ */
+ timedOut: boolean;
}
/** Enough for a payload transfer over a slow link, short enough to not hang a menu forever. */
@@ -38,7 +45,15 @@ export function run(
: error
? 1
: 0;
- resolve({ code, stdout: String(stdout), stderr: String(stderr) });
+ // execFile signals a timeout by killing the child: `killed` is set and there is no
+ // numeric exit code of its own.
+ const killed = (error as (Error & { killed?: boolean }) | null)?.killed === true;
+ resolve({
+ code,
+ stdout: String(stdout),
+ stderr: String(stderr),
+ timedOut: killed && error !== null,
+ });
},
);
});
@@ -66,9 +81,17 @@ export function runWithInput(
let stdout = "";
let stderr = "";
let pending = "";
- const timer = setTimeout(() => child.kill(), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
- child.stdout.on("data", (chunk: Buffer) => {
- const text = chunk.toString("utf8");
+ let timedOut = false;
+ const timer = setTimeout(() => {
+ timedOut = true;
+ child.kill();
+ }, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+ // Decoding is the stream's, not each chunk's: a multibyte character whose bytes land in
+ // two `data` events would otherwise become two replacement characters. This path carries
+ // the Windows installer's own output, which is where a localized far side puts non-ASCII.
+ child.stdout.setEncoding("utf8");
+ child.stderr.setEncoding("utf8");
+ child.stdout.on("data", (text: string) => {
stdout += text;
if (opts.onLine === undefined) return;
pending += text;
@@ -79,16 +102,16 @@ export function runWithInput(
if (trimmed !== "") opts.onLine(trimmed);
}
});
- child.stderr.on("data", (chunk: Buffer) => (stderr += chunk.toString("utf8")));
+ child.stderr.on("data", (chunk: string) => (stderr += chunk));
child.on("close", (code) => {
clearTimeout(timer);
// Whatever the last chunk left without a newline is still a line the far side wrote.
if (pending.trim() !== "") opts.onLine?.(pending.trim());
- resolve({ code: code ?? 1, stdout, stderr });
+ resolve({ code: code ?? 1, stdout, stderr, timedOut });
});
child.on("error", (err) => {
clearTimeout(timer);
- resolve({ code: 1, stdout, stderr: `${stderr}${err.message}\n` });
+ resolve({ code: 1, stdout, stderr: `${stderr}${err.message}\n`, timedOut });
});
// A remote that never reads stdin (a refused connection) closes the pipe under us.
child.stdin.on("error", () => {});
@@ -96,64 +119,35 @@ export function runWithInput(
});
}
-/**
- * `producer | consumer`, without a shell: the producer's stdout is piped straight into the
- * consumer's stdin — how the hmr store crosses to the remote (local tar → ssh). Failure of
- * EITHER side fails the pair, with both stderr streams in the result; a broken pipe from a
- * dead consumer must not read as a successful transfer.
- */
-export function runPiped(
- producer: { file: string; args: string[] },
- consumer: { file: string; args: string[] },
- opts: { timeoutMs?: number } = {},
-): Promise<ExecResult> {
+/** A local helper's stdout as bytes — a tarball to hand to a machine as a heredoc. */
+export function runBytes(
+ file: string,
+ args: string[],
+): Promise<{ code: number; stdout: Buffer; stderr: string }> {
return new Promise((resolve) => {
- const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
- const a = spawn(producer.file, producer.args, { stdio: ["ignore", "pipe", "pipe"] });
- const b = spawn(consumer.file, consumer.args, { stdio: ["pipe", "pipe", "pipe"] });
- a.stdout.pipe(b.stdin);
- // A consumer that dies mid-stream closes the pipe; without this the producer's EPIPE
- // would surface as an unhandled stream error instead of the consumer's own exit below.
- b.stdin.on("error", () => a.kill());
- let stdout = "";
- let stderr = "";
- b.stdout.on("data", (chunk: Buffer) => (stdout += chunk.toString("utf8")));
- a.stderr.on("data", (chunk: Buffer) => (stderr += chunk.toString("utf8")));
- b.stderr.on("data", (chunk: Buffer) => (stderr += chunk.toString("utf8")));
- let aCode: number | null = null;
- let bCode: number | null = null;
- let settled = false;
- const timer = setTimeout(() => {
- a.kill();
- b.kill();
- }, timeoutMs);
- const finish = () => {
- if (settled || aCode === null || bCode === null) return;
- settled = true;
- clearTimeout(timer);
- resolve({ code: aCode !== 0 ? aCode : bCode, stdout, stderr });
- };
- a.on("close", (code) => {
- aCode = code ?? 1;
- finish();
- });
- b.on("close", (code) => {
- bCode = code ?? 1;
- finish();
- });
- a.on("error", (err) => {
- aCode = 1;
- stderr += `${err.message}\n`;
- finish();
- });
- b.on("error", (err) => {
- bCode = 1;
- stderr += `${err.message}\n`;
- finish();
- });
+ execFile(
+ file,
+ args,
+ { encoding: "buffer", timeout: DEFAULT_TIMEOUT_MS, maxBuffer: 256 * 1024 * 1024 },
+ (error, stdout, stderr) => {
+ const code =
+ error && typeof (error as NodeJS.ErrnoException & { code?: number }).code === "number"
+ ? ((error as NodeJS.ErrnoException & { code: number }).code as number)
+ : error
+ ? 1
+ : 0;
+ resolve({ code, stdout: Buffer.from(stdout), stderr: String(stderr) });
+ },
+ );
});
}
+/** What a failed ExecResult says, in the transport's words; `whenSilent` when it said nothing. */
+export function execFailureText(result: ExecResult, whenSilent: string): string {
+ if (result.timedOut) return "the machine did not answer in time";
+ return result.stderr.trim() || whenSilent;
+}
+
/** True when the failure is "ssh could not authenticate without asking" — the BatchMode wall. */
export function looksLikeAuthFailure(result: ExecResult): boolean {
return /permission denied|no supported authentication|host key verification failed/i.test(
diff --git a/packages/server/src/machines/transport/index.ts b/packages/server/src/machines/transport/index.ts
index 4e245821..4cc9950e 100644
--- a/packages/server/src/machines/transport/index.ts
+++ b/packages/server/src/machines/transport/index.ts
@@ -1,21 +1,19 @@
/**
- * The transport directory's one door: everything machines/ needs in order to reach another
- * machine comes through here, and the modules behind it (exec.ts, targets.ts) are private.
+ * The transport directory's one door. Everything machines/ needs from the transport layer
+ * — the connection handle, target listing, and the result vocabulary — comes through here;
+ * the modules behind it (exec.ts, ssh-session.ts, socks.ts, lane.ts, targets.ts) are
+ * private, pinned by machines-transport-boundary.test.ts. See connection.ts for why.
*
- * The rule is about AUTHORITY, not about sockets. Opening ssh is how this server acts on a
- * machine at all — installing a program directory, reading what is there, later holding a
- * shell and a tunnel open — so it is worth one place that owns it rather than a spawn at
- * every call site. A caller that opens its own channel also judges the machine by that
- * channel, and "my ssh worked" is not the same fact as "that machine is healthy"; keeping
- * the door single is what lets those facts be told apart later.
- *
- * machines-transport-boundary.test.ts pins it by scanning the source, so the rule survives
- * a new call site added in a hurry.
- *
- * What sits behind the door is expected to change: the raw runners below are what the
- * install path needs today, and they narrow to a per-machine connection handle once one
- * exists. A caller importing only from here does not notice that.
+ * THE STRUCTURE. Per machine ONE connection: an `ssh -T -D` session whose stdin carries the
+ * commands, the scripts and the tarballs, and whose SOCKS port carries every TCP connection
+ * to the machine as a channel inside it. Not a budget: there is no count of open connections
+ * and no number to tune, because there is nothing that could open a second one; a second ask
+ * waits for the first.
*/
-export { looksLikeAuthFailure, run, runPiped, runWithInput } from "./exec.js";
+export { MachineConnection, closeConnectionTo, connectionTo } from "./connection.js";
+export type { MachineChannel } from "./connection.js";
+export { openShell, sessionOf } from "./ssh-session.js";
+export type { ShellSession } from "./ssh-session.js";
+export { execFailureText, looksLikeAuthFailure, runBytes } from "./exec.js";
export type { ExecResult } from "./exec.js";
-export { listHostAliases, resolveTarget } from "./targets.js";
+export { listHostAliases } from "./targets.js";
diff --git a/packages/server/src/machines/transport/lane.ts b/packages/server/src/machines/transport/lane.ts
new file mode 100644
index 00000000..1c02540f
--- /dev/null
+++ b/packages/server/src/machines/transport/lane.ts
@@ -0,0 +1,25 @@
+/**
+ * One thing at a time per machine.
+ *
+ * The rule this directory keeps is structural, not a budget: a machine has one connection
+ * for small commands, one forward, and one bulk transfer at a time, and everything else
+ * queues behind them. There is no count of how many may be open and no number to tune —
+ * a caller cannot open a second one however many times it asks, because the second ask
+ * waits for the first. The incident behind it was a machine taken down by hundreds of
+ * connections from one controller, each trigger arriving with its own idea of "a few".
+ *
+ * Keyed by the machine's address, module-level, so every caller in the process shares the
+ * same lane whichever App it lives in.
+ */
+const lanes = new Map<string, Promise<unknown>>();
+
+/** Runs `work` after everything already queued for that machine has finished. */
+export function inLane<T>(address: string, work: () => Promise<T>): Promise<T> {
+ const next = (lanes.get(address) ?? Promise.resolve()).then(work);
+ // The lane must survive a rejection, or one failure would stall every later command.
+ lanes.set(
+ address,
+ next.catch(() => undefined),
+ );
+ return next;
+}
diff --git a/packages/server/src/machines/transport/socks.ts b/packages/server/src/machines/transport/socks.ts
new file mode 100644
index 00000000..435c923a
--- /dev/null
+++ b/packages/server/src/machines/transport/socks.ts
@@ -0,0 +1,77 @@
+/**
+ * A SOCKS5 CONNECT, the way this server reaches any TCP port on a machine.
+ *
+ * The one ssh session per machine is opened with `-D <local port>` (ssh-session.ts): ssh
+ * listens on that loopback port as a SOCKS server, and every connection accepted there
+ * becomes a `direct-tcpip` channel inside the session — the SSH protocol's own
+ * multiplexing, over the one TCP connection already up. Reaching the machine's API, its
+ * update endpoint, anything: dial here, and nothing new is opened on the far side.
+ *
+ * This is what VS Code Remote-SSH does, and for the same reason: Win32 OpenSSH has no
+ * ControlMaster, so "one connection" cannot be had by sharing a socket between ssh
+ * processes; it can be had by never starting a second one.
+ *
+ * Only the CONNECT command, no authentication (the listener is loopback and ssh's), and the
+ * target is always an IPv4 loopback address on the far side. Small enough to own.
+ */
+import net from "node:net";
+
+/** How long the SOCKS handshake itself may take; the request behind it sets its own after. */
+const HANDSHAKE_TIMEOUT_MS = 20_000;
+
+/** Dials `host:port` as seen from the machine, through the session's SOCKS port. */
+export function dialThroughSocks(
+ socksPort: number,
+ host: string,
+ port: number,
+): Promise<net.Socket> {
+ const parts = host.split(".").map((p) => Number.parseInt(p, 10));
+ if (parts.length !== 4 || parts.some((p) => !Number.isInteger(p) || p < 0 || p > 255)) {
+ return Promise.reject(new Error(`not an IPv4 address: ${host}`));
+ }
+ if (!Number.isInteger(port) || port < 1 || port > 65535) {
+ return Promise.reject(new Error(`bad port ${port}`));
+ }
+ return new Promise((resolve, reject) => {
+ const socket = net.connect({ host: "127.0.0.1", port: socksPort });
+ // A handshake that stalls — a session half-dead, a far side that never answers the
+ // channel open — must fail rather than hang the request that wanted it; the request's own
+ // timeout only starts once it has a socket.
+ socket.setTimeout(HANDSHAKE_TIMEOUT_MS, () => fail("the session's SOCKS handshake timed out"));
+ let buffer = Buffer.alloc(0);
+ let stage: "greet" | "connect" = "greet";
+ const fail = (message: string) => {
+ socket.removeListener("data", onData);
+ socket.destroy();
+ reject(new Error(message));
+ };
+ const onData = (chunk: Buffer) => {
+ buffer = Buffer.concat([buffer, chunk]);
+ if (stage === "greet") {
+ if (buffer.length < 2) return;
+ if (buffer[0] !== 5 || buffer[1] !== 0) return fail("the session's SOCKS listener refused");
+ buffer = buffer.subarray(2);
+ stage = "connect";
+ socket.write(Buffer.from([5, 1, 0, 1, ...parts, port >> 8, port & 0xff]));
+ }
+ if (stage === "connect") {
+ if (buffer.length < 4) return;
+ if (buffer[1] !== 0)
+ return fail(`the machine refused ${host}:${port} (SOCKS reply ${buffer[1]})`);
+ const addrLen = buffer[3] === 1 ? 4 : buffer[3] === 4 ? 16 : 1 + (buffer[4] ?? 0);
+ const total = 4 + addrLen + 2;
+ if (buffer.length < total) return;
+ const rest = buffer.subarray(total);
+ socket.removeListener("data", onData);
+ socket.removeListener("error", onError);
+ socket.setTimeout(0);
+ if (rest.length > 0) socket.unshift(rest);
+ resolve(socket);
+ }
+ };
+ const onError = (err: Error) => fail(`the session's SOCKS port did not answer: ${err.message}`);
+ socket.once("connect", () => socket.write(Buffer.from([5, 1, 0]))); // no authentication
+ socket.on("data", onData);
+ socket.once("error", onError);
+ });
+}
diff --git a/packages/server/src/machines/transport/ssh-session.ts b/packages/server/src/machines/transport/ssh-session.ts
new file mode 100644
index 00000000..e5b502b3
--- /dev/null
+++ b/packages/server/src/machines/transport/ssh-session.ts
@@ -0,0 +1,331 @@
+/**
+ * ONE connection per machine: `ssh -T -D <port> <alias> sh`, held open.
+ *
+ * Everything this server does to a machine goes over it. Commands are fed to the shell's
+ * stdin and answered on its stdout; a script or a tarball rides the same stdin as a heredoc;
+ * every TCP connection to the machine — its API, its update endpoint — is dialled through
+ * the `-D` SOCKS port as a channel inside this same session (socks.ts). Nothing else opens
+ * ssh to a machine while this is up, and a second ask for anything queues behind the first.
+ * VS Code Remote-SSH is built the same way, for the same reason: Win32 OpenSSH has no
+ * ControlMaster, so one connection means never starting a second process.
+ *
+ * FRAMING. Each command is wrapped so its end is unambiguous:
+ *
+ * ( <command> ) 2>&1 ; printf '\n<mark> %s\n' "$?"
+ *
+ * A SUBSHELL, so a command containing `exit` cannot end the shell and a `cd` cannot leak. The
+ * mark is random per session, so nothing a command prints can forge it. Output and errors are
+ * MERGED — separating them over one pipe needs temp files — and that is in the type: the
+ * result is `output`, not `stdout`/`stderr`. With an input, the command reads it from stdin:
+ *
+ * ( <decode> | ( <command> ) ) <<'EOF_<mark>' 2>&1 ; printf …
+ * <base64 of the input>
+ * EOF_<mark>
+ *
+ * base64 because a heredoc carries text, and the terminator cannot occur in its alphabet.
+ * <decode> is DECODE below, which settles the flag on the far side rather than here.
+ *
+ * UNSUPERVISED: a session that dies is dropped and the next command opens a new one.
+ */
+import { spawn } from "node:child_process";
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import net from "node:net";
+import { sessionArgs } from "../commands.js";
+import type { RemoteTarget } from "../commands.js";
+
+/**
+ * What a command in the session produced. `output` is stdout and stderr merged, with the
+ * command's own trailing newline kept — the same shape execFile hands back, so a caller
+ * parses one channel identically whichever way the command reached the machine.
+ */
+export interface ShellResult {
+ code: number;
+ output: string;
+}
+
+export interface ShellRunOptions {
+ /** Bytes the command reads from its stdin, carried as a heredoc. */
+ input?: Buffer;
+ /** Each complete line of output as it arrives — an install takes minutes. */
+ onLine?: (line: string) => void;
+ /** A command that has not finished in this long is treated as a hung session. */
+ timeoutMs?: number;
+}
+
+/** The held session: the ssh child, and the loopback port its SOCKS listener is on. */
+export interface ShellSession {
+ pid: number;
+ socksPort: number;
+}
+
+/** How long an idle session is kept before it is let go. */
+const IDLE_MS = 10 * 60_000;
+
+/** The default: enough for a probe, a directory listing, a token mint. */
+const COMMAND_TIMEOUT_MS = 60_000;
+
+/** Opening is a handshake to a host that may be far away or loaded. */
+const OPEN_TIMEOUT_MS = 30_000;
+
+/**
+ * Decoding the heredoc, on either base64 there is. GNU coreutils spells decode `-d` and
+ * rejects `-D`; the BSD base64 macOS ships spells it `-D`, and releases before Ventura reject
+ * `-d`. There is no flag both accept, so the far side picks: the candidate is tried on an
+ * empty input of its own — a pipe from printf — which leaves the heredoc on stdin untouched
+ * for whichever invocation wins. No round trip, and nothing here has to know the platform.
+ */
+const DECODE = "if printf '' | base64 -d >/dev/null 2>&1; then base64 -d; else base64 -D; fi";
+
+/** A local port nothing is on: the kernel's answer, bound and released rather than guessed. */
+function freeLocalPort(): Promise<number | null> {
+ return new Promise((resolve) => {
+ const probe = net.createServer();
+ probe.once("error", () => resolve(null));
+ probe.listen(0, "127.0.0.1", () => {
+ const address = probe.address();
+ const port = typeof address === "object" && address !== null ? address.port : null;
+ probe.close(() => resolve(port));
+ });
+ });
+}
+
+interface Pending {
+ resolve: (r: ShellResult) => void;
+ timer: NodeJS.Timeout;
+ onLine: ((line: string) => void) | undefined;
+}
+
+class MachineShell {
+ #child: ChildProcessWithoutNullStreams | null = null;
+ #socksPort: number | null = null;
+ #buffer = "";
+ /** How far into #buffer lines have been handed to the pending command's onLine. */
+ #emitted = 0;
+ #mark = "";
+ #stderr = "";
+ #pending: Pending | null = null;
+ #queue: Promise<unknown> = Promise.resolve();
+ #idle: NodeJS.Timeout | null = null;
+
+ constructor(private readonly target: RemoteTarget) {}
+
+ /** Runs one command, opening the session if needed. Never throws; a dead session is a failure. */
+ run(command: string, opts: ShellRunOptions = {}): Promise<ShellResult> {
+ const next = this.#queue.then(() => this.#runExclusive(command, opts));
+ // The queue must survive a rejection, or one failure would stall every later command.
+ this.#queue = next.catch(() => undefined);
+ return next;
+ }
+
+ /** The session while it is up — pid and SOCKS port — or null. */
+ session(): ShellSession | null {
+ const pid = this.#child?.pid;
+ return pid !== undefined && this.#socksPort !== null
+ ? { pid, socksPort: this.#socksPort }
+ : null;
+ }
+
+ close(): void {
+ if (this.#idle !== null) clearTimeout(this.#idle);
+ this.#idle = null;
+ this.#child?.kill();
+ this.#drop();
+ }
+
+ #drop(): void {
+ this.#child = null;
+ this.#socksPort = null;
+ this.#buffer = "";
+ this.#emitted = 0;
+ const pending = this.#pending;
+ this.#pending = null;
+ if (pending !== null) {
+ clearTimeout(pending.timer);
+ // ssh's own last words — a refused key, an unknown host — are the diagnosis.
+ const said = this.#stderr.trim().split("\n").pop() ?? "";
+ pending.resolve({
+ code: 255,
+ output:
+ said === ""
+ ? "the connection to this machine ended"
+ : `the connection to this machine ended: ${said}`,
+ });
+ }
+ this.#stderr = "";
+ }
+
+ async #open(): Promise<ChildProcessWithoutNullStreams> {
+ if (this.#child !== null) return this.#child;
+ const port = await freeLocalPort();
+ if (port === null) throw new Error("no free local port for the session's SOCKS listener");
+ this.#mark = `--penguin-${randomBytes(9).toString("hex")}--`;
+ const child = spawn("ssh", sessionArgs(this.target, port), { stdio: ["pipe", "pipe", "pipe"] });
+ // setEncoding, not String(chunk): a multibyte character whose bytes land in two `data`
+ // events would otherwise decode to two replacement characters. The stream's decoder holds
+ // an incomplete sequence back until the rest of it arrives.
+ child.stdout.setEncoding("utf8");
+ child.stdout.on("data", (chunk: string) => this.#onData(chunk));
+ // A write to a session that already died raises EPIPE on this stream ASYNCHRONOUSLY,
+ // after the write returned — with no listener that is an unhandled error event, which
+ // takes the process down. The command it belonged to is answered by #drop() on exit.
+ child.stdin.on("error", () => {});
+ // ssh's own stderr is not a command's output (those carry theirs on stdout via 2>&1);
+ // it is kept for the moment the session dies, when it is the diagnosis. Decoded by the
+ // stream for the same reason stdout is: a banner or a remote MOTD is where non-ASCII
+ // reaches this channel, and this text is read by a person when the connection fails.
+ child.stderr.setEncoding("utf8");
+ child.stderr.on("data", (chunk: string) => {
+ this.#stderr = (this.#stderr + chunk).slice(-4096);
+ });
+ // "close", not "exit": stderr's last words arrive before close, and they are the diagnosis.
+ //
+ // Guarded by identity, because a dead child's close event can arrive after its successor is
+ // already up: close() kills and drops synchronously, the queue then opens a new session, and
+ // the kill's own close lands afterwards. Unguarded, that stale event would drop the
+ // replacement and answer ITS command as a connection that ended.
+ child.on("close", () => {
+ if (this.#child === child) this.#drop();
+ });
+ child.on("error", () => {
+ if (this.#child === child) this.#drop();
+ });
+ this.#child = child;
+ this.#socksPort = port;
+ return child;
+ }
+
+ #onData(text: string): void {
+ this.#buffer += text;
+ const at = this.#buffer.indexOf(this.#mark);
+ const region = at === -1 ? this.#buffer : this.#buffer.slice(0, at);
+ // Complete lines are relayed as they arrive; the framing's own trailing newline is not a line.
+ for (
+ let nl = region.indexOf("\n", this.#emitted);
+ nl !== -1;
+ nl = region.indexOf("\n", this.#emitted)
+ ) {
+ const line = region.slice(this.#emitted, nl);
+ this.#emitted = nl + 1;
+ if (!(at !== -1 && line === "" && this.#emitted === region.length))
+ this.#pending?.onLine?.(line);
+ }
+ if (at === -1) return;
+ const rest = this.#buffer.slice(at + this.#mark.length);
+ const end = rest.indexOf("\n");
+ if (end === -1) return; // The exit code has not arrived yet.
+ const output = region.replace(/\n$/, "");
+ const code = Number.parseInt(rest.slice(0, end).trim(), 10);
+ this.#buffer = rest.slice(end + 1);
+ this.#emitted = 0;
+ const pending = this.#pending;
+ this.#pending = null;
+ if (pending !== null) {
+ clearTimeout(pending.timer);
+ pending.resolve({ code: Number.isFinite(code) ? code : 0, output });
+ }
+ }
+
+ async #runExclusive(command: string, opts: ShellRunOptions): Promise<ShellResult> {
+ if (this.#idle !== null) clearTimeout(this.#idle);
+ let child: ChildProcessWithoutNullStreams;
+ try {
+ child = await this.#open();
+ } catch (err) {
+ return {
+ code: 255,
+ output: `could not start ssh: ${err instanceof Error ? err.message : String(err)}`,
+ };
+ }
+ return new Promise<ShellResult>((resolve) => {
+ const timer = setTimeout(() => {
+ // A session that stopped answering is not one to keep: drop it so the next command
+ // opens a fresh connection rather than queueing behind a corpse.
+ //
+ // The pending command is detached FIRST. close() answers whatever is pending with the
+ // connection's last words, and a promise settles once — so leaving it attached would
+ // spend this command's one answer on "the connection ended", losing the more precise
+ // fact that the machine simply never replied.
+ this.#pending = null;
+ this.close();
+ resolve({ code: 255, output: "the machine did not answer in time" });
+ }, opts.timeoutMs ?? COMMAND_TIMEOUT_MS);
+ this.#pending = { resolve, timer, onLine: opts.onLine };
+ const mark = `printf '\\n${this.#mark} %s\\n' "$?"`;
+ if (opts.input === undefined) {
+ child.stdin.write(`( ${command} ) 2>&1 ; ${mark}\n`);
+ return;
+ }
+ const end = `EOF_${this.#mark.replaceAll("-", "")}`;
+ const body = opts.input.toString("base64").replace(/.{76}/g, "$&\n");
+ child.stdin.write(
+ `( ${DECODE} | ( ${command} ) ) <<'${end}' 2>&1 ; ${mark}\n${body}\n${end}\n`,
+ );
+ }).finally(() => {
+ this.#idle = setTimeout(() => this.close(), IDLE_MS);
+ this.#idle.unref?.();
+ });
+ }
+}
+
+/**
+ * The sessions, by machine address. Module-level rather than per App, so ordinary work does
+ * not reopen a connection it already has.
+ *
+ * A hot push DOES lose them: the platform bundle is re-imported cache-busted (hmr/host.ts),
+ * so this map starts empty in the successor and the previous generation's ssh children have
+ * nothing holding them. What collects them is the idle timer — a scheduled timeout belongs
+ * to the process, not to the module that scheduled it, so it still fires and still closes the
+ * child it was created for. The cost of a push is one reconnect per machine, within IDLE_MS,
+ * and never a child nobody ever kills.
+ */
+const sessions = new Map<string, MachineShell>();
+
+function shellFor(machineAddress: string, target: RemoteTarget): MachineShell {
+ let shell = sessions.get(machineAddress);
+ if (shell === undefined) {
+ shell = new MachineShell(target);
+ sessions.set(machineAddress, shell);
+ }
+ return shell;
+}
+
+/** Runs a command on a machine over its session. */
+export function runOnShell(
+ machineAddress: string,
+ target: RemoteTarget,
+ command: string,
+ opts: ShellRunOptions = {},
+): Promise<ShellResult> {
+ return shellFor(machineAddress, target).run(command, opts);
+}
+
+/**
+ * Brings the session up, or reports why it could not be: the first thing a connect does,
+ * and what any TCP dial needs. Idempotent — a session already up is answered from memory.
+ */
+export async function openShell(
+ machineAddress: string,
+ target: RemoteTarget,
+): Promise<{ ok: true; session: ShellSession } | { ok: false; detail: string }> {
+ const shell = shellFor(machineAddress, target);
+ const up = shell.session();
+ if (up !== null) return { ok: true, session: up };
+ const result = await shell.run(":", { timeoutMs: OPEN_TIMEOUT_MS });
+ const session = shell.session();
+ if (result.code !== 0 || session === null) {
+ return { ok: false, detail: result.output.trim() || "the session did not come up" };
+ }
+ return { ok: true, session };
+}
+
+/** The session held to a machine, while it is up. */
+export function sessionOf(machineAddress: string): ShellSession | null {
+ return sessions.get(machineAddress)?.session() ?? null;
+}
+
+/** Lets go of a machine's session — for a disconnect, or a machine that went away. */
+export function closeShell(machineAddress: string): void {
+ sessions.get(machineAddress)?.close();
+ sessions.delete(machineAddress);
+}
diff --git a/packages/server/src/machines/transport/targets.ts b/packages/server/src/machines/transport/targets.ts
index e5e01c8c..6b0341ee 100644
--- a/packages/server/src/machines/transport/targets.ts
+++ b/packages/server/src/machines/transport/targets.ts
@@ -1,18 +1,16 @@
/**
- * Turning `~/.ssh/config` into a list of targets the menu can show, and one target into what
- * ssh actually resolved. The parsing is in ssh-config.ts; this file owns the I/O — reading
- * files, expanding `Include` globs, and asking ssh itself with `ssh -G`.
+ * Turning `~/.ssh/config` into the list of aliases the menu can show. The parsing is in
+ * ssh-config.ts; this file owns the I/O — reading files and expanding `Include` globs.
*
- * An unreadable config, a missing config or an ssh that will not answer all degrade to "no
- * targets" rather than to an error: this list is a convenience, and a user with no ssh setup
- * should simply not see the feature offer them anything.
+ * Nothing here resolves an alias: what it means is ssh's business, applied by ssh itself
+ * every time it is handed one. An unreadable or missing config degrades to "no targets"
+ * rather than to an error: this list is a convenience, and a user with no ssh setup should
+ * simply not see the feature offer them anything.
*/
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
-import { run } from "./exec.js";
-import { machineIdentity, parseHostAliases, parseSshSettings } from "../ssh-config.js";
-import type { SshSettings } from "../ssh-config.js";
+import { parseHostAliases } from "../ssh-config.js";
const SSH_DIR = () => path.join(os.homedir(), ".ssh");
@@ -58,17 +56,3 @@ export function listHostAliases(): string[] {
return [];
}
}
-
-/**
- * What ssh resolves an alias to, via `ssh -G` — Match blocks, Include and wildcard
- * inheritance included, because ssh does the resolving, not us. Null when ssh cannot be run
- * or refuses the alias.
- */
-export async function resolveTarget(
- alias: string,
-): Promise<{ alias: string; settings: SshSettings; machine: string } | null> {
- const result = await run("ssh", ["-G", alias], { timeoutMs: 15_000 });
- if (result.code !== 0 && result.stdout.trim() === "") return null;
- const settings = parseSshSettings(result.stdout, alias);
- return { alias, settings, machine: machineIdentity(alias, settings.user) };
-}
diff --git a/packages/server/test/machines-api.test.ts b/packages/server/test/machines-api.test.ts
index 0a72663a..7735698a 100644
--- a/packages/server/test/machines-api.test.ts
+++ b/packages/server/test/machines-api.test.ts
@@ -43,17 +43,6 @@ const IDENTITY: RemoteIdentity = {
function effects(over: Partial<MachinesEffects> = {}): Partial<MachinesEffects> {
return {
listAliases: () => ["build-box", "nas"],
- resolveTarget: async (alias) => ({
- alias,
- settings: {
- user: "deploy",
- hostname: `${alias}.example`,
- port: 22,
- identityFiles: [],
- proxyJump: null,
- },
- machine: `deploy@${alias}`,
- }),
resolvePlan: () => ({ baseVersion: "9.9.9", harness: null, hmrDir: null, version: "9.9.9" }),
now: () => new Date("2026-08-24T12:00:00.000Z"),
install: async (opts): Promise<RemoteInstallOutcome> => {
@@ -185,7 +174,7 @@ describe("machines API", () => {
).json()) as MachinesResponse;
expect(body.job?.result).toEqual({ ok: true, kind: "installed", version: "9.9.9" });
// The first line is this server's own, the rest are the push's.
- expect(body.job?.log[0]).toBe("Installing 9.9.9 on deploy@nas…");
+ expect(body.job?.log[0]).toBe("Installing 9.9.9 on nas…");
expect(body.job?.log).toContain("Pushing…");
});
@@ -399,14 +388,5 @@ describe("machines API", () => {
"no_install_image",
);
});
-
- it("502s a host ssh itself cannot resolve", async () => {
- await boot({ resolveTarget: async () => null });
- const res = await admin.post(`/api/projects/${PROJECT}/machines/ssh:nas/install`);
- expect(res.status).toBe(502);
- expect(((await res.json()) as { error: { code: string } }).error.code).toBe(
- "unresolvable_host",
- );
- });
});
});
diff --git a/packages/server/test/machines-push.test.ts b/packages/server/test/machines-push.test.ts
index aa267296..e7ff5a00 100644
--- a/packages/server/test/machines-push.test.ts
+++ b/packages/server/test/machines-push.test.ts
@@ -1,12 +1,11 @@
/**
- * installOnRemote's orchestration, driven against stub `ssh`, `scp` and `tar` binaries on
- * PATH: which dialect it probes in, that the release installer runs pinned to the base, that
- * the hmr store streams over a pipe, the scratch directory being cleared even on failure,
- * and each outcome the page renders. Real processes are spawned — only the far side is fake —
- * so the argv this app hands to ssh is exercised rather than described.
- *
- * POSIX-only: the stubs are shell scripts. The Windows command forms are asserted as pure
- * strings in machines.test.ts.
+ * installOnRemote's orchestration, driven against a scripted channel: which dialect it probes
+ * in and over what, that the release installer rides the session's stdin pinned to the base,
+ * that the hmr store rides the same stdin as a tarball, that a Windows host gets its own
+ * connection and a copied script, and each outcome the page renders. The channel is what a
+ * real MachineConnection speaks (transport/connection.ts); here every verb is recorded and
+ * answered as the scenario dictates, so what is exercised is what the install asks of a
+ * machine, not the far side.
*/
import fs from "node:fs";
import os from "node:os";
@@ -14,18 +13,84 @@ import path from "node:path";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { installOnRemote } from "../src/machines/install-server.js";
import type { PushPlan } from "../src/machines/install-server.js";
+import type { ExecResult, MachineChannel } from "../src/machines/transport/index.js";
-const posixOnly = process.platform === "win32" ? describe.skip : describe;
+interface Call {
+ verb: "exec" | "stream" | "oneShot" | "copyTo";
+ command: string;
+ input?: Buffer;
+}
-posixOnly("installOnRemote", () => {
- let work: string;
- let stubBin: string;
- let logFile: string;
- let originalPath: string | undefined;
+/** How a scripted machine answers. */
+interface Script {
+ probe: string;
+ /**
+ * What the probe answers ONCE the installer has run. The install path asks twice, and the
+ * second answer is the machine reporting what it ended up with — a script that said the
+ * same both times could not tell an install that took from one that ran cleanly and
+ * changed nothing, which is the case the second ask exists for.
+ */
+ afterInstall?: string;
+ /** A cmd.exe host: no `sh` to hold a session on, so the session dies unopened. */
+ windows?: boolean;
+ installExit?: number;
+}
+
+const ok = (stdout: string): ExecResult => ({ code: 0, stdout, stderr: "", timedOut: false });
+function scripted(script: Script): MachineChannel & { calls: Call[] } {
+ const calls: Call[] = [];
+ let ran = false;
+ const identity = () =>
+ (ran ? (script.afterInstall ?? script.probe) : script.probe).replaceAll("\\n", "\n");
+ const answer = (call: Call, onLine?: (line: string) => void): ExecResult => {
+ calls.push(call);
+ const { command } = call;
+ if (command.includes("uname")) {
+ return script.windows
+ ? {
+ code: 255,
+ stdout:
+ "the connection to this machine ended: 'sh' is not recognized as an internal or external command",
+ stderr: "",
+ timedOut: false,
+ }
+ : ok(identity());
+ }
+ if (command.includes("PROCESSOR_ARCHITECTURE")) return ok(identity());
+ if (command.includes("sh -s") || command.includes("powershell")) {
+ ran = true;
+ onLine?.("PenguinHarness 0.2.4 installed");
+ return { ...ok("PenguinHarness 0.2.4 installed\n"), code: script.installExit ?? 0 };
+ }
+ return ok("");
+ };
+ return {
+ calls,
+ exec: async (command) => answer({ verb: "exec", command }),
+ stream: async (command, opts) =>
+ answer({ verb: "stream", command, input: opts.input }, opts.onLine),
+ oneShot: async (command, opts = {}) =>
+ answer(
+ opts.input === undefined
+ ? { verb: "oneShot", command }
+ : { verb: "oneShot", command, input: opts.input },
+ ),
+ copyTo: async (localFiles, remoteDir) => {
+ calls.push({
+ verb: "copyTo",
+ command: `${localFiles.map((f) => path.basename(f)).join(" ")} -> ${remoteDir}`,
+ });
+ return ok("");
+ },
+ };
+}
+
+describe("installOnRemote", () => {
+ let work: string;
const HARNESS = '{"platform":{"bundle":"store/platform/cafe0123456789ab.mjs"}}';
- /** A plan the way resolvePushPlan builds one, with a real hmr dir to stream. */
+ /** A plan the way resolvePushPlan builds one, with a real hmr dir to pack. */
const plan = (over: Partial<PushPlan> = {}): PushPlan => {
const hmrDir = path.join(work, "hmr");
fs.mkdirSync(path.join(hmrDir, "store"), { recursive: true });
@@ -43,154 +108,168 @@ posixOnly("installOnRemote", () => {
/** Where the push finds install.sh / install.ps1 — the repo root, in a source checkout. */
const assets = () => path.resolve(__dirname, "..", "..", "..");
- /** Stub ssh/scp that log every invocation and answer as the scenario dictates. */
- const writeStubs = (opts: { probe: string; posixUnknown?: boolean; installExit?: number }) => {
- fs.writeFileSync(
- path.join(stubBin, "ssh"),
- [
- "#!/bin/sh",
- `printf 'ssh %s\\n' "$*" >> ${JSON.stringify(logFile)}`,
- // NOT the `eval echo` idiom: some of these commands carry `&&`-joined mktemp/tar,
- // which eval would EXECUTE on the test machine instead of merely naming.
- 'for a in "$@"; do last=$a; done',
- 'case "$last" in',
- opts.posixUnknown
- ? ` *uname*) echo "'uname' is not recognized as an internal or external command" 1>&2; exit 1 ;;`
- : ` *uname*) printf '%b' ${JSON.stringify(opts.probe)} ;;`,
- ` *PROCESSOR_ARCHITECTURE*) printf '%b' ${JSON.stringify(opts.probe)} ;;`,
- " *mktemp*) echo /tmp/remote-scratch ;;",
- // Single-quoted: sh's echo would otherwise eat the backslashes.
- " *%TEMP%*) echo 'C:\\Temp\\penguin-scratch' ;;",
- ` *sh\\ -s*) cat > /dev/null; echo "PenguinHarness 0.2.4 installed"; exit ${opts.installExit ?? 0} ;;`,
- ` *install.ps1*) echo "PenguinHarness 0.2.4 installed"; exit ${opts.installExit ?? 0} ;;`,
- // The store stream: swallow stdin so the local tar does not die on a broken pipe.
- " *'tar -xzf -'*) cat > /dev/null ;;",
- " *) : ;;",
- "esac",
- "exit 0",
- ].join("\n"),
- { mode: 0o755 },
- );
- fs.writeFileSync(
- path.join(stubBin, "scp"),
- ["#!/bin/sh", `printf 'scp %s\\n' "$*" >> ${JSON.stringify(logFile)}`, "exit 0"].join("\n"),
- { mode: 0o755 },
- );
- };
-
- const calls = (): string[] =>
- fs.existsSync(logFile) ? fs.readFileSync(logFile, "utf8").trim().split("\n") : [];
-
beforeEach(() => {
work = fs.mkdtempSync(path.join(os.tmpdir(), "penguin-push-test-"));
- stubBin = path.join(work, "bin");
- fs.mkdirSync(stubBin);
- logFile = path.join(work, "calls.log");
- originalPath = process.env.PATH;
- process.env.PATH = `${stubBin}:${process.env.PATH ?? ""}`;
});
afterEach(() => {
- process.env.PATH = originalPath;
fs.rmSync(work, { recursive: true, force: true });
});
const target = { alias: "build-box", user: "deploy" };
- it("probes, installs over ONE ssh call, then streams the store", async () => {
- writeStubs({ probe: "Linux x86_64\\n---penguin---\\n---penguin---\\n" });
+ it("probes, installs and replicates over the ONE session, then asks what the machine now has", async () => {
+ const channel = scripted({
+ probe: "Linux x86_64\\n---penguin---\\n---penguin---\\n",
+ afterInstall: `Linux x86_64\\n---penguin---\\n{"version":"0.2.4"}\\n---penguin---\\n${HARNESS}`,
+ });
const progress: string[] = [];
const outcome = await installOnRemote({
target,
plan: plan(),
assets,
+ channel,
onProgress: (line) => progress.push(line),
});
expect(outcome).toMatchObject({ kind: "installed" });
- const log = calls();
- // Three handshakes, and no scp, mktemp or rm anywhere: the installer went in on stdin.
- expect(log).toHaveLength(3);
- expect(log[0]).toContain("uname -s -m"); // identity first
- // The release is downloaded ON THE REMOTE, pinned to this server's own base.
- expect(log[1]).toContain("PENGUIN_VERSION='v0.2.4' sh -s");
- // The hmr state crosses as a stream into the default data root.
- expect(log[2]).toContain('tar -xzf - -C "$HOME/.penguin/data"');
- expect(log.some((line) => line.startsWith("scp"))).toBe(false);
- expect(log.some((line) => line.includes("mktemp") || line.includes("rm -rf"))).toBe(false);
- expect(log.every((line) => line.includes("User=deploy"))).toBe(true);
- expect(log.every((line) => line.includes("BatchMode=yes"))).toBe(true);
+ const { calls } = channel;
+ // Four commands, all on the session: no one-shot connection, no scp, no scratch dir.
+ expect(calls.map((c) => c.verb)).toEqual(["exec", "stream", "stream", "exec"]);
+ expect(calls[0]!.command).toContain("uname -s -m"); // identity first
+ // The release is downloaded ON THE REMOTE, pinned to this server's own base, the
+ // installer riding the session's stdin.
+ expect(calls[1]!.command).toContain("PENGUIN_VERSION='v0.2.4' sh -s");
+ expect(calls[1]!.input?.toString("utf8").startsWith("#!/")).toBe(true);
+ // The hmr state crosses the same stdin as a tarball, into the hmr directory it was
+ // tarred from.
+ expect(calls[2]!.command).toContain('tar -xzf - -C "$HOME/.penguin/data/hmr"');
+ expect(calls[2]!.input?.subarray(0, 2)).toEqual(Buffer.from([0x1f, 0x8b])); // gzip
+ // And the machine is asked what it ended up with, which is the only step that can tell
+ // an install that took from one that ran cleanly and changed nothing.
+ expect(calls[3]!.command).toContain("uname -s -m");
expect(progress).toContain("linux-x64.");
// The far side's own output is relayed as it arrives, not withheld until exit.
expect(progress).toContain("PenguinHarness 0.2.4 installed");
});
- it("falls back to the Windows probe when the POSIX one is not understood", async () => {
- writeStubs({
- probe: "Windows_NT AMD64\\n---penguin---\\n---penguin---\\n",
- posixUnknown: true,
+ it("calls an install that ran cleanly and changed nothing a failure", async () => {
+ // The installer exits 0 and says it installed; the machine still has nothing. Every step
+ // answers for itself and none of them answers whether the thing on disk over there is now
+ // this version — so without asking afterwards this is a success recorded at OUR version,
+ // and syncOutOfDate filters on exactly that: the machine is excluded from the sweep that
+ // would have tried again. A false success here seals itself in.
+ const channel = scripted({ probe: "Linux x86_64\\n---penguin---\\n---penguin---\\n" });
+ const outcome = await installOnRemote({ target, plan: plan(), assets, channel });
+
+ expect(outcome).toMatchObject({ kind: "failed", step: "verify the install" });
+ expect((outcome as { detail: string }).detail).toContain("still has no install");
+ });
+
+ it("calls a base that took without the pushed state a failure", async () => {
+ // The store's unpack exited 0 and the base is exactly right, so every step answered for
+ // itself; only the second probe can tell that the pushed half never landed. Blessing this
+ // would record the machine at plan.version — the base plus that state's sha — and
+ // syncOutOfDate filters on that record, so the machine would be left out of the very
+ // sweep that would have pushed again.
+ const channel = scripted({
+ probe: "Linux x86_64\\n---penguin---\\n---penguin---\\n",
+ afterInstall: 'Linux x86_64\\n---penguin---\\n{"version":"0.2.4"}\\n---penguin---\\n',
});
- const outcome = await installOnRemote({ target, plan: plan(), assets });
+ const outcome = await installOnRemote({ target, plan: plan(), assets, channel });
- expect(outcome).toMatchObject({ kind: "installed" });
- const log = calls();
- expect(log[0]).toContain("uname -s -m");
- expect(log[1]).toContain("%PROCESSOR_ARCHITECTURE%");
- // PowerShell cannot take the script on stdin, so a Windows remote gets a copy — scp'd to
- // the home directory, with the delete chained onto the command that runs it.
- expect(log[2]).toMatch(/^scp .*\.ps1 build-box:\.$/);
- expect(log[3]).toContain('-File "%USERPROFILE%\\penguin-');
- expect(log[3]).toContain('-Version "v0.2.4"');
- expect(log[3]).toContain("& del /q");
- expect(log.some((line) => line.includes('mkdir "%TEMP%'))).toBe(false);
+ expect(outcome).toMatchObject({ kind: "failed", step: "verify the install" });
+ expect((outcome as { detail: string }).detail).toContain("no pushed state");
});
- it("a matching base skips the installer and only streams the store", async () => {
- writeStubs({
- probe: 'Linux x86_64\\n---penguin---\\n{"version":"0.2.4"}\\n---penguin---\\n',
+ it("a Windows host has no session to hold: the probe, a copied script and the store each get their own connection", async () => {
+ const channel = scripted({
+ probe: "Windows_NT AMD64\\n---penguin---\\n---penguin---\\n",
+ afterInstall: `Windows_NT AMD64\\n---penguin---\\n{"version":"0.2.4"}\\n---penguin---\\n${HARNESS}`,
+ windows: true,
});
- const outcome = await installOnRemote({ target, plan: plan(), assets });
+ const outcome = await installOnRemote({ target, plan: plan(), assets, channel });
+
expect(outcome).toMatchObject({ kind: "installed" });
- const log = calls();
- expect(log.some((line) => line.includes("install.sh"))).toBe(false);
- expect(log.some((line) => line.includes("tar -xzf -"))).toBe(true);
+ const { calls } = channel;
+ // The session is tried first and dies unopened (cmd.exe has no sh); the Windows probe
+ // then goes on a connection of its own.
+ expect(calls[0]).toMatchObject({ verb: "exec" });
+ expect(calls[0]!.command).toContain("uname -s -m");
+ expect(calls[1]).toMatchObject({ verb: "oneShot" });
+ expect(calls[1]!.command).toContain("%PROCESSOR_ARCHITECTURE%");
+ // PowerShell cannot take the script on stdin, so a Windows remote gets a copy — scp'd to
+ // the home directory, with the delete chained onto the command that runs it.
+ expect(calls[2]!.verb).toBe("copyTo");
+ expect(calls[2]!.command).toMatch(/^penguin-[0-9a-f]+\.ps1 -> \.$/);
+ expect(calls[3]!.verb).toBe("oneShot");
+ expect(calls[3]!.command).toContain('-File "%USERPROFILE%\\penguin-');
+ expect(calls[3]!.command).toContain('-Version "v0.2.4"');
+ expect(calls[3]!.command).toContain("& del /q");
+ // The store, as stdin to a one-shot tar.
+ expect(calls[4]).toMatchObject({ verb: "oneShot" });
+ expect(calls[4]!.command).toContain("tar -xzf -");
+ expect(calls[4]!.input?.subarray(0, 2)).toEqual(Buffer.from([0x1f, 0x8b]));
});
it("does nothing when the remote already matches base AND pushed state", async () => {
- writeStubs({
+ const channel = scripted({
probe: `Linux x86_64\\n---penguin---\\n{"version":"0.2.4"}\\n---penguin---\\n${HARNESS}\\n`,
});
- const outcome = await installOnRemote({ target, plan: plan(), assets });
+ const outcome = await installOnRemote({ target, plan: plan(), assets, channel });
expect(outcome).toMatchObject({ kind: "already-installed", version: "0.2.4+hmr.cafe01234567" });
- expect(calls()).toHaveLength(1); // the probe, and nothing else
+ expect(channel.calls).toHaveLength(1); // the probe, and nothing else
});
it("a bare release plan streams nothing", async () => {
- writeStubs({ probe: "Linux x86_64\\n---penguin---\\n---penguin---\\n" });
+ const channel = scripted({
+ probe: "Linux x86_64\\n---penguin---\\n---penguin---\\n",
+ afterInstall: 'Linux x86_64\\n---penguin---\\n{"version":"0.2.4"}\\n---penguin---\\n',
+ });
const outcome = await installOnRemote({
target,
plan: plan({ harness: null, hmrDir: null, version: "0.2.4" }),
assets,
+ channel,
});
expect(outcome).toMatchObject({ kind: "installed" });
- expect(calls().some((line) => line.includes("tar -xzf -"))).toBe(false);
+ expect(channel.calls.some((c) => c.command.includes("tar -xzf -"))).toBe(false);
});
it("reports the installer's own output on failure", async () => {
- writeStubs({
+ const channel = scripted({
probe: 'Linux x86_64\\n---penguin---\\n{"version":"0.0.1"}\\n---penguin---\\n',
installExit: 3,
});
- const outcome = await installOnRemote({ target, plan: plan(), assets });
+ const outcome = await installOnRemote({ target, plan: plan(), assets, channel });
expect(outcome).toMatchObject({ kind: "failed", step: "install" });
expect((outcome as { detail: string }).detail).toContain("PenguinHarness 0.2.4 installed");
});
+ it("reports ssh's own words when the session cannot be opened", async () => {
+ const channel = scripted({ probe: "" });
+ channel.exec = async () => ({
+ code: 255,
+ stdout:
+ "the connection to this machine ended: deploy@build-box: Permission denied (publickey).",
+ stderr: "",
+ timedOut: false,
+ });
+ const outcome = await installOnRemote({ target, plan: plan(), assets, channel });
+ expect(outcome).toMatchObject({ kind: "failed", step: "connect" });
+ expect((outcome as { detail: string }).detail).toContain("Permission denied");
+ expect((outcome as { detail: string }).detail).toContain("BatchMode");
+ });
+
it("refuses a base that cannot name a release", async () => {
- writeStubs({ probe: "Linux x86_64\\n---penguin---\\n---penguin---\\n" });
+ const channel = scripted({
+ probe: "Linux x86_64\\n---penguin---\\n---penguin---\\n",
+ afterInstall: 'Linux x86_64\\n---penguin---\\n{"version":"0.2.4"}\\n---penguin---\\n',
+ });
const outcome = await installOnRemote({
target,
plan: plan({ baseVersion: "0.0.0-hmr.cafe", version: "0.0.0-hmr.cafe" }),
assets,
+ channel,
});
expect(outcome).toMatchObject({ kind: "failed", step: "resolve the release" });
});
diff --git a/packages/server/test/machines-transport-boundary.test.ts b/packages/server/test/machines-transport-boundary.test.ts
index 9bb59c34..afe6b87e 100644
--- a/packages/server/test/machines-transport-boundary.test.ts
+++ b/packages/server/test/machines-transport-boundary.test.ts
@@ -1,13 +1,12 @@
/**
- * One door per machine: nothing outside machines/transport/ may open ssh or reach around
- * the directory's index. The rule is worth pinning rather than agreeing to, because the
- * failure it prevents is quiet — a call site that opens its own channel goes on to judge
- * the machine by that channel, and "my ssh worked" is not the same fact as "that machine
- * is healthy".
+ * One mouth per machine: nothing outside machines/transport/ may open ssh or reach around
+ * the MachineConnection seam (transport/connection.ts). The incident behind the rule
+ * (#561) grew exactly where a call site opened its own channel and judged the machine's
+ * liveness from that channel's state.
*
- * A source scan rather than a lint rule: it runs with the suite everywhere, and its failure
- * message names the offending file. Tests are exempt — a unit test of a private module
- * imports it by nature.
+ * A source scan rather than a lint rule: it runs with the suite everywhere, and its
+ * failure message names the offending file. Tests are exempt — a unit test of a private
+ * module imports it by nature.
*/
import fs from "node:fs";
import path from "node:path";
@@ -49,7 +48,12 @@ describe("the transport boundary", () => {
// Each relative specifier is resolved against the importing file rather than matched by
// shape, so a caller anywhere under src/ reaching for `../machines/exec.js` is caught,
// not only a sibling writing `./exec.js`.
- const gone = new Set(["machines/exec.js", "machines/targets.js"]);
+ const gone = new Set([
+ "machines/exec.js",
+ "machines/targets.js",
+ "machines/ssh-session.js",
+ "machines/forward.js",
+ ]);
const specifiers = /from\s+["'](\.{1,2}\/[^"']+)["']/g;
const stragglers = outside
.filter((f) => {
diff --git a/packages/server/test/machines-transport-lane.test.ts b/packages/server/test/machines-transport-lane.test.ts
new file mode 100644
index 00000000..4f184930
--- /dev/null
+++ b/packages/server/test/machines-transport-lane.test.ts
@@ -0,0 +1,49 @@
+/**
+ * One thing at a time per machine, by structure: two commands to the same machine run one
+ * after the other, two to different machines together. Measured against a stub `ssh` on
+ * PATH that only sleeps.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { run } from "../src/machines/transport/exec.js";
+import { inLane } from "../src/machines/transport/lane.js";
+
+const posixOnly = process.platform === "win32" ? describe.skip : describe;
+
+posixOnly("the per-machine lane", () => {
+ let stubBin: string;
+ let originalPath: string | undefined;
+ beforeEach(() => {
+ stubBin = fs.mkdtempSync(path.join(os.tmpdir(), "penguin-lane-"));
+ fs.writeFileSync(path.join(stubBin, "ssh"), "#!/bin/sh\nsleep 0.2\n");
+ fs.chmodSync(path.join(stubBin, "ssh"), 0o755);
+ originalPath = process.env.PATH;
+ process.env.PATH = `${stubBin}:${process.env.PATH ?? ""}`;
+ });
+ afterEach(() => {
+ process.env.PATH = originalPath;
+ fs.rmSync(stubBin, { recursive: true, force: true });
+ });
+
+ it("serialises commands to one machine and lets different machines proceed together", async () => {
+ const ssh = (address: string) => inLane(address, () => run("ssh", ["host", "true"]));
+ let started = Date.now();
+ await Promise.all([ssh("ssh:nas"), ssh("ssh:nas")]);
+ expect(Date.now() - started).toBeGreaterThanOrEqual(380);
+
+ started = Date.now();
+ await Promise.all([ssh("ssh:nas"), ssh("ssh:build-box")]);
+ expect(Date.now() - started).toBeLessThan(380);
+ });
+
+ it("a failure does not stall the lane behind it", async () => {
+ await expect(
+ inLane("ssh:nas", async () => {
+ throw new Error("boom");
+ }),
+ ).rejects.toThrow("boom");
+ expect(await inLane("ssh:nas", async () => "next")).toBe("next");
+ });
+});
diff --git a/packages/server/test/machines-transport-session.test.ts b/packages/server/test/machines-transport-session.test.ts
new file mode 100644
index 00000000..e31b7f48
--- /dev/null
+++ b/packages/server/test/machines-transport-session.test.ts
@@ -0,0 +1,115 @@
+/**
+ * The one connection per machine, against a stub `ssh` on PATH that becomes a real `sh` when
+ * asked for one: the framing, the heredoc input, progress relayed as it arrives, one session
+ * however many ask, and what a session that dies says.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { closeConnectionTo, connectionTo, sessionOf } from "../src/machines/transport/index.js";
+
+const posixOnly = process.platform === "win32" ? describe.skip : describe;
+
+posixOnly("the session", () => {
+ let stubBin: string;
+ let logFile: string;
+ let originalPath: string | undefined;
+ beforeEach(() => {
+ stubBin = fs.mkdtempSync(path.join(os.tmpdir(), "penguin-session-"));
+ logFile = path.join(stubBin, "calls.log");
+ // Every invocation is logged; an alias containing "refused" dies the way a wrong key
+ // does; anything else asked for `sh` becomes one — commands run locally, harmlessly.
+ fs.writeFileSync(
+ path.join(stubBin, "ssh"),
+ `#!/bin/sh
+echo "$*" >> ${JSON.stringify(logFile)}
+case "$*" in *refused*) echo "deploy@refused: Permission denied (publickey)." >&2; exit 255 ;; esac
+for a in "$@"; do last=$a; done
+[ "$last" = sh ] && exec /bin/sh
+exit 1
+`,
+ );
+ fs.chmodSync(path.join(stubBin, "ssh"), 0o755);
+ originalPath = process.env.PATH;
+ process.env.PATH = `${stubBin}:${process.env.PATH ?? ""}`;
+ });
+ afterEach(() => {
+ for (const address of ["ssh:nas", "ssh:build-box", "ssh:refused"]) closeConnectionTo(address);
+ process.env.PATH = originalPath;
+ fs.rmSync(stubBin, { recursive: true, force: true });
+ });
+ const spawns = () => fs.readFileSync(logFile, "utf8").trim().split("\n");
+
+ it("runs commands with their exit code, and an `exit` cannot end the session", async () => {
+ const conn = connectionTo({ alias: "nas", user: "deploy" });
+ // The command's own trailing newline is kept, as execFile would keep it.
+ expect(await conn.exec("echo hi")).toMatchObject({ code: 0, stdout: "hi\n" });
+ expect((await conn.exec("exit 3")).code).toBe(3);
+ expect(await conn.exec("echo still here")).toMatchObject({ code: 0, stdout: "still here\n" });
+ expect(spawns()).toHaveLength(1);
+ });
+
+ it("hands a command its stdin as a heredoc, bytes intact, and relays lines as they arrive", async () => {
+ const conn = connectionTo({ alias: "nas", user: "deploy" });
+ const input = Buffer.from("héllo\nEOF\nworld\n", "utf8");
+ const lines: string[] = [];
+ const result = await conn.stream("cat", { input, onLine: (line) => lines.push(line) });
+ expect(result).toMatchObject({ code: 0, stdout: "héllo\nEOF\nworld\n" });
+ expect(lines).toEqual(["héllo", "EOF", "world"]);
+ // Binary survives too: the tarball case.
+ const bytes = Buffer.from([0x1f, 0x8b, 0x00, 0xff, 0x0a, 0x0d, 0x00]);
+ const echoed = await conn.stream("od -An -tx1 | tr -d ' \\n'", { input: bytes });
+ expect(echoed.stdout).toBe("1f8b00ff0a0d00");
+ });
+
+ it("is one session however many ask: commands queue, and two opens spawn once", async () => {
+ const conn = connectionTo({ alias: "nas", user: "deploy" });
+ const [a, b] = await Promise.all([conn.open(), conn.open()]);
+ expect(a.ok && b.ok && a.session.pid === b.session.pid).toBe(true);
+ expect(spawns()).toHaveLength(1);
+ expect(sessionOf("ssh:nas")?.pid).toBe(a.ok ? a.session.pid : -1);
+
+ let started = Date.now();
+ await Promise.all([conn.exec("sleep 0.2"), conn.exec("sleep 0.2")]);
+ expect(Date.now() - started).toBeGreaterThanOrEqual(380);
+ // A different machine is a different session: those run side by side.
+ const other = connectionTo({ alias: "build-box", user: "deploy" });
+ started = Date.now();
+ await Promise.all([conn.exec("sleep 0.2"), other.exec("sleep 0.2")]);
+ expect(Date.now() - started).toBeLessThan(380);
+ expect(spawns()).toHaveLength(2);
+ });
+
+ it("a session that dies says why, in ssh's own words, and is not kept", async () => {
+ const conn = connectionTo({ alias: "refused", user: "deploy" });
+ const opened = await conn.open();
+ expect(opened.ok).toBe(false);
+ if (!opened.ok) expect(opened.detail).toContain("Permission denied");
+ expect(sessionOf("ssh:refused")).toBeNull();
+ });
+
+ it("answers a command that outlasts its timeout with the timeout, and hands the next one a live session", async () => {
+ const conn = connectionTo({ alias: "nas", user: "deploy" });
+ // The timeout is this command's own answer. Dropping the session also answers whatever is
+ // pending — with the connection's last words — so the two race for the one resolution a
+ // promise has, and the precise diagnosis has to win.
+ const timedOut = await conn.stream("sleep 5", { input: Buffer.alloc(0), timeoutMs: 150 });
+ expect(timedOut).toMatchObject({ code: 255, stdout: "the machine did not answer in time" });
+
+ // The killed session's close event lands while its replacement is already coming up. It
+ // belongs to a child nobody holds any more, and must not take the replacement — or the
+ // command riding it — down with it.
+ expect(await conn.exec("echo after")).toMatchObject({ code: 0, stdout: "after\n" });
+ expect(spawns()).toHaveLength(2);
+ });
+
+ it("closing lets go of the session; the next ask opens a new one", async () => {
+ const conn = connectionTo({ alias: "nas", user: "deploy" });
+ await conn.exec("true");
+ closeConnectionTo("ssh:nas");
+ expect(sessionOf("ssh:nas")).toBeNull();
+ await conn.exec("true");
+ expect(spawns()).toHaveLength(2);
+ });
+});
diff --git a/packages/server/test/machines-transport-socks.test.ts b/packages/server/test/machines-transport-socks.test.ts
new file mode 100644
index 00000000..5640190d
--- /dev/null
+++ b/packages/server/test/machines-transport-socks.test.ts
@@ -0,0 +1,112 @@
+/**
+ * The SOCKS5 dial: a CONNECT through the session's `-D` port, answered by a small SOCKS
+ * server of this test's own, reaching an HTTP server behind it.
+ */
+import http from "node:http";
+import net from "node:net";
+import { afterEach, describe, expect, it } from "vitest";
+import { dialThroughSocks } from "../src/machines/transport/socks.js";
+
+/** Just enough SOCKS5 to answer a CONNECT: greet, connect, pipe. */
+function socksServer(): Promise<{ port: number; close: () => void; requests: number[] }> {
+ const requests: number[] = [];
+ const server = net.createServer((client) => {
+ let stage = 0;
+ // Each stage waits for its whole frame before reading it. A `data` event is a piece of a
+ // byte stream, not a message: taking one as a complete greeting or CONNECT would read the
+ // port from bytes that had not arrived, and reading past the end throws inside this
+ // handler — an uncaught exception, which takes the worker down rather than failing a test.
+ let buffer = Buffer.alloc(0);
+ client.on("data", (chunk: Buffer) => {
+ buffer = Buffer.concat([buffer, chunk]);
+ // The greeting: version, one method count, that many methods.
+ if (stage === 0) {
+ if (buffer.length < 2) return;
+ const greeting = 2 + buffer[1]!;
+ if (buffer.length < greeting) return;
+ buffer = buffer.subarray(greeting);
+ stage = 1;
+ client.write(Buffer.from([5, 0]));
+ }
+ // CONNECT to an IPv4 address: 4 header bytes, 4 of address, 2 of port.
+ if (stage === 1) {
+ if (buffer.length < 10) return;
+ stage = 2;
+ const port = buffer.readUInt16BE(8);
+ buffer = buffer.subarray(10);
+ requests.push(port);
+ const upstream = net.connect({ host: "127.0.0.1", port }, () => {
+ client.write(Buffer.from([5, 0, 0, 1, 0, 0, 0, 0, 0, 0]));
+ // Anything already read past the request belongs to the tunnel, not to us.
+ if (buffer.length > 0) upstream.write(buffer);
+ client.pipe(upstream).pipe(client);
+ });
+ upstream.on("error", () => {
+ client.end(Buffer.from([5, 5, 0, 1, 0, 0, 0, 0, 0, 0]));
+ });
+ }
+ });
+ });
+ return new Promise((resolve) =>
+ server.listen(0, "127.0.0.1", () =>
+ resolve({
+ port: (server.address() as net.AddressInfo).port,
+ close: () => server.close(),
+ requests,
+ }),
+ ),
+ );
+}
+
+describe("dialThroughSocks", () => {
+ const cleanups: Array<() => void> = [];
+ afterEach(() => {
+ for (const c of cleanups.splice(0)) c();
+ });
+
+ it("reaches a port behind the SOCKS server and carries HTTP over it", async () => {
+ const web = http.createServer((_req, res) => res.end("ok from behind"));
+ await new Promise<void>((resolve) => web.listen(0, "127.0.0.1", resolve));
+ cleanups.push(() => web.close());
+ const webPort = (web.address() as net.AddressInfo).port;
+ const socks = await socksServer();
+ cleanups.push(socks.close);
+
+ const socket = await dialThroughSocks(socks.port, "127.0.0.1", webPort);
+ const answer = await new Promise<string>((resolve) => {
+ let text = "";
+ socket.on("data", (chunk: Buffer) => (text += String(chunk)));
+ socket.on("end", () => resolve(text));
+ socket.write("GET / HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n");
+ });
+ expect(answer).toContain("ok from behind");
+ expect(socks.requests).toEqual([webPort]);
+ });
+
+ it("fails in the SOCKS server's words when the port behind it refuses", async () => {
+ const socks = await socksServer();
+ cleanups.push(socks.close);
+ // A port nothing listens on: taken from the kernel and released.
+ const probe = net.createServer();
+ const free = await new Promise<number>((resolve) =>
+ probe.listen(0, "127.0.0.1", () => {
+ const port = (probe.address() as net.AddressInfo).port;
+ probe.close(() => resolve(port));
+ }),
+ );
+ await expect(dialThroughSocks(socks.port, "127.0.0.1", free)).rejects.toThrow(
+ /refused .*SOCKS reply 5/,
+ );
+ });
+
+ it("fails when there is no SOCKS listener at all", async () => {
+ const probe = net.createServer();
+ const free = await new Promise<number>((resolve) =>
+ probe.listen(0, "127.0.0.1", () => {
+ const port = (probe.address() as net.AddressInfo).port;
+ probe.close(() => resolve(port));
+ }),
+ );
+ await expect(dialThroughSocks(free, "127.0.0.1", 7364)).rejects.toThrow(/did not answer/);
+ });
+});
diff --git a/packages/server/test/machines.test.ts b/packages/server/test/machines.test.ts
index d07a0719..4a7ffab6 100644
--- a/packages/server/test/machines.test.ts
+++ b/packages/server/test/machines.test.ts
@@ -11,13 +11,14 @@ import os from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { describe, expect, it } from "vitest";
-import { machineIdentity, parseHostAliases, parseSshSettings } from "../src/machines/ssh-config.js";
+import { machineIdentity, parseHostAliases } from "../src/machines/ssh-config.js";
import { parseProbeOutput, POSIX_PROBE, WINDOWS_PROBE } from "../src/machines/detect.js";
import {
cmdQuote,
runInstallScriptCommand,
unpackStoreCommand,
scpArgs,
+ sessionArgs,
shQuote,
sshArgs,
} from "../src/machines/commands.js";
@@ -70,37 +71,6 @@ describe("parseHostAliases", () => {
});
});
-describe("parseSshSettings", () => {
- it("reads what ssh resolved, keeping every identityfile", () => {
- const settings = parseSshSettings(
- [
- "user deploy",
- "hostname 10.0.0.4",
- "port 2222",
- "identityfile ~/.ssh/id_ed25519",
- "identityfile ~/.ssh/id_rsa",
- "proxyjump bastion",
- ].join("\n"),
- "build-box",
- );
- expect(settings).toEqual({
- user: "deploy",
- hostname: "10.0.0.4",
- port: 2222,
- identityFiles: ["~/.ssh/id_ed25519", "~/.ssh/id_rsa"],
- proxyJump: "bastion",
- });
- });
-
- it("falls back to ssh's own defaults rather than throwing on a config it cannot read", () => {
- const settings = parseSshSettings("garbage\nport not-a-number\nproxyjump none", "gpu-1");
- expect(settings.hostname).toBe("gpu-1"); // the alias stands in
- expect(settings.port).toBe(22);
- expect(settings.user).toBe("");
- expect(settings.proxyJump).toBeNull();
- });
-});
-
describe("machineIdentity", () => {
it("is <user>@<alias>: the Linux account is part of the machine, the alias is the name", () => {
// Two accounts on one host are two machines — each has its own ~/.penguin, hence its
@@ -189,6 +159,23 @@ describe("ssh / scp invocations", () => {
expect(scpArgs(target, ["/tmp/a"], "/tmp/dir")).toContain("BatchMode=yes");
});
+ it("holds ONE session per machine: no tty, a SOCKS listener on loopback, keepalives, sh", () => {
+ const args = sessionArgs(target, 49152).join(" ");
+ expect(args).toContain("-T");
+ expect(args).toContain("-D 127.0.0.1:49152");
+ expect(args).toContain("ExitOnForwardFailure=yes");
+ expect(args).toContain("ServerAliveInterval=15");
+ expect(args).toContain("BatchMode=yes");
+ expect(args.endsWith("build-box sh")).toBe(true);
+ // Nothing is forwarded by name: any port on the machine is a channel through -D.
+ expect(args).not.toContain("-L ");
+ });
+
+ it("refuses a SOCKS port that is not one", () => {
+ expect(() => sessionArgs(target, 0)).toThrow(/bad port/);
+ expect(() => sessionArgs(target, 70000)).toThrow(/bad port/);
+ });
+
it("selects the account on the command line, never by writing the ssh config", () => {
expect(sshArgs(target, "true")).toContain("User=deploy");
expect(sshArgs({ alias: "build-box", user: "" }, "true").join(" ")).not.toContain("User=");
@@ -232,12 +219,15 @@ describe("ssh / scp invocations", () => {
});
});
- it("unpacks the streamed store into the default data root", () => {
+ it("unpacks the streamed store into the hmr directory it was tarred from", () => {
+ // The members are named relative to the sending side's own hmr directory, so the two
+ // `-C` arguments have to name the same layer: one level too high writes a harness.json
+ // and a store/ nothing reads, and the machine goes on answering with what it held.
expect(unpackStoreCommand("linux")).toBe(
- 'mkdir -p "$HOME/.penguin/data" && tar -xzf - -C "$HOME/.penguin/data"',
+ 'mkdir -p "$HOME/.penguin/data/hmr" && tar -xzf - -C "$HOME/.penguin/data/hmr"',
);
expect(unpackStoreCommand("win32")).toBe(
- '(if not exist "%USERPROFILE%\\.penguin\\data" mkdir "%USERPROFILE%\\.penguin\\data") & tar -xzf - -C "%USERPROFILE%\\.penguin\\data"',
+ '(if not exist "%USERPROFILE%\\.penguin\\data\\hmr" mkdir "%USERPROFILE%\\.penguin\\data\\hmr") & tar -xzf - -C "%USERPROFILE%\\.penguin\\data\\hmr"',
);
});
});