Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions controller/jobs.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import path from "node:path";
import { fileURLToPath } from "node:url";
import { JOBS_NODE, VALID_JOB } from "../core/boxery-core.mjs";
import { closeMaster } from "../core/profile.mjs";
import { CliError, die, duration, needVm, note, num, quit, say, usage, vmSsh, vmSshCapture, WAIT_LOST, WAIT_TIMEOUT, warn } from "./lib.mjs";
import { BOXERY, CliError, USAGE, die, duration, needVm, note, num, quit, say, usage, vmSsh, vmSshCapture, WAIT_LOST, WAIT_TIMEOUT, warn } from "./lib.mjs";
/** @import { Selected } from "./lib.mjs" */


Expand All @@ -34,7 +34,7 @@ const jobsVmCapture = (s, name, args, o) => vmSshCapture(s, helper(name, args),
const exit = (rc) => { if (rc) throw new CliError("", rc); };

/** @param {string | undefined} id */
const needJob = (id) => (VALID_JOB.test(id ?? "") ? /** @type {string} */ (id) : die(`invalid job id: ${id ?? ""} (see: boxery jobs NAME)`));
const needJob = (id) => (VALID_JOB.test(id ?? "") ? /** @type {string} */ (id) : id ? die(`invalid job id: ${id} (see: ${BOXERY} jobs NAME)`) : die(`missing job id (see: ${BOXERY} jobs NAME)`, USAGE));

/** run --bg: start ARGV (each word's bytes) in the VM as a job, in CWD (bytes, or null: ~/project); its id.
* @param {Selected} s @param {string} name @param {Buffer[]} argv @param {Buffer | null} cwd */
Expand Down Expand Up @@ -108,7 +108,7 @@ export async function waitJob(s, [vm, job, ...rest]) {
// waiting doesn't affect the job (tmux in the VM): reconnect and keep waiting, within --timeout.
if (!reached) die(`cannot reach ${name}`);
if (deadline != null && Date.now() / 1000 >= deadline) { warn(`cannot reach ${name}; --timeout passed (the job may still be running)`); quit(WAIT_TIMEOUT); }
if (++drops > 60) die(`cannot reach ${name}; giving up (the job may still be running: boxery jobs ${name})`);
if (++drops > 60) die(`cannot reach ${name}; giving up (the job may still be running: ${BOXERY} jobs ${name})`);
warn(`lost the connection to ${name}; reconnecting (the job keeps running)`);
await closeMaster(name);
await new Promise((res) => setTimeout(res, 5000));
Expand Down
21 changes: 16 additions & 5 deletions core/boxery-core.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -417,8 +417,19 @@ export async function sshOk(vm, script, opts = {}) {

// ---------------------------------------------------------------- why a VM can't be reached

/** A boxery command for a hint about the current host's VMs: `boxery --host NAME COMMAND` when the person named a
* host (BOXERY_CLI: controller/lib.mjs invokedAs) or this isn't the default host (another host's VM in cp, an
* agent's host session), else `boxery COMMAND`, as host/util.mjs hint does for the host's own messages.
* @param {string} command e.g. "ls" */
export function cliHint(command) {
let name = null, def = null;
try { name = currentHost().name; } catch { /* no host selected (formatting alone): plain boxery */ }
try { def = defaultHost(); } catch { /* a malformed default-host file must not replace the message */ }
return `boxery${name && (/^boxery --host /.test(process.env.BOXERY_CLI ?? "") || name !== def) ? ` --host ${name}` : ""} ${command}`;
}

/** What the host says of a VM it doesn't have, and where to look. @param {string} vm */
export const noSuchVm = (vm) => `no such vm: ${vm} on host ${currentHost().name} (boxery ls lists them)`;
export const noSuchVm = (vm) => `no such vm: ${vm} on host ${currentHost().name} (${cliHint("ls")} lists them)`;

/** A VM's problem, for a person or an agent. known: the host's records explain it (no such VM, not running, a
* pool VM without a lease); otherwise message is what ssh said. missing: the host has no such VM, so whatever
Expand Down Expand Up @@ -457,11 +468,11 @@ export async function vmProblem(vm, { env, signal } = {}) {
const v = vms.find((r) => r.name === vm);
if (!v) return { message: noSuchVm(vm), known: true, missing: true };
if (v.state && !["running", "idle"].includes(v.state))
return { message: /ing$/.test(v.state) ? `VM ${vm} is ${v.state}; try again when it's running (boxery ls shows its state)` : `VM ${vm} is ${v.state}; start it: boxery start ${vm}`, known: true };
return { message: /ing$/.test(v.state) ? `VM ${vm} is ${v.state}; try again when it's running (${cliHint("ls")} shows its state)` : `VM ${vm} is ${v.state}; start it: ${cliHint(`start ${vm}`)}`, known: true };
if (v.lease) {
const mine = findLease(vm);
if (!mine) return { message: `VM ${vm} is in the host's shared pool: only the holder of a lease on it can reach it, and this machine holds none (boxery acquire leases a pool VM; boxery leases lists yours)`, known: true };
if (mine.expires * 1000 < Date.now()) return { message: `your lease on VM ${vm} has expired, so it no longer lets you in (boxery leases lists yours; boxery acquire leases a pool VM again)`, known: true };
if (!mine) return { message: `VM ${vm} is in the host's shared pool: only the holder of a lease on it can reach it, and this machine holds none (${cliHint("acquire")} leases a pool VM; ${cliHint("leases")} lists yours)`, known: true };
if (mine.expires * 1000 < Date.now()) return { message: `your lease on VM ${vm} has expired, so it no longer lets you in (${cliHint("leases")} lists yours; ${cliHint("acquire")} leases a pool VM again)`, known: true };
}
return { message: `VM "${vm}" unreachable over ssh: ${said || (probe.code == null ? "timed out" : "connection failed")}`, known: false };
}
Expand Down Expand Up @@ -1181,7 +1192,7 @@ export function formatVms(vms) {
const outdated = vms.filter((v) => v.guest?.status === "outdated");
if (!outdated.length) return table;
// Patching restarts VMs and is the user's call: agents only point it out.
return `${table}\noutdated guest software: ${outdated.map((v) => `${v.name} (${(v.guest?.reasons ?? []).join(", ")})`).join("; ")}. Tell the user; they can update it with: boxery patch NAME`;
return `${table}\noutdated guest software: ${outdated.map((v) => `${v.name} (${(v.guest?.reasons ?? []).join(", ")})`).join("; ")}. Tell the user; they can update it with: ${cliHint("patch NAME")}`;
}

/** VM's grants (listGrants: this machine's records). With none recorded, the host is asked whether VM exists, so
Expand Down
8 changes: 4 additions & 4 deletions core/desktop.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
// previous session's for new logins; connections already open stay.
import { spawn } from "node:child_process";
import net from "node:net";
import { assertName, currentHost, sshRun } from "./boxery-core.mjs";
import { assertName, cliHint, currentHost, sshRun } from "./boxery-core.mjs";
import { profileConfig } from "./profile.mjs";

const SETUP = 'if test -e /etc/boxery/headless; then echo headless\nelif command -v boxery-vnc-password >/dev/null; then p=$(boxery-vnc-password --new) && echo "password $p"\nelse echo nopassword; fi';
Expand All @@ -32,8 +32,8 @@ export async function prepareDesktop(name, { terminal = false } = {}) {
let pw = "", warning = null;
if (out === "headless") throw new Error(`${name} is headless (boxery new --headless): it has no desktop`);
else if (out.startsWith("password ")) { pw = out.slice(9); if (!/^[A-Za-z0-9]+$/.test(pw)) throw new Error(`unexpected VNC password from ${name}`); }
else if (out === "nopassword") warning = `${name}'s desktop has no VNC password: its image predates it, so while this tunnel is open any process on this machine (or a web page) can use it. Rebuild the desktop base (boxery build-base) and create the VM again.`;
else throw new Error(`couldn't set up the desktop of ${name} (is it running? boxery ls)${why ? `: ${why}` : ""}`);
else if (out === "nopassword") warning = `${name}'s desktop has no VNC password: its image predates it, so while this tunnel is open any process on this machine (or a web page) can use it. Rebuild the desktop base (${cliHint("build-base")}) and create the VM again.`;
else throw new Error(`couldn't set up the desktop of ${name} (is it running? ${cliHint("ls")})${why ? `: ${why}` : ""}`);
const port = await freePort(16080);
return { url: `http://127.0.0.1:${port}/vnc.html?autoconnect=1&resize=remote&reconnect=1${pw ? `#password=${pw}` : ""}`, port, warning };
}
Expand Down Expand Up @@ -72,7 +72,7 @@ export async function openDesktop(name, { open = true } = {}) {
if (!(await freePortAt(port))) { await new Promise((r) => setTimeout(r, 200)); up = alive(); }
else await new Promise((r) => setTimeout(r, 100));
}
if (!up) { child.kill(); throw new Error(`the tunnel to ${name}'s desktop didn't come up (is it running? boxery ls)`); }
if (!up) { child.kill(); throw new Error(`the tunnel to ${name}'s desktop didn't come up (is it running? ${cliHint("ls")})`); }
const opened = open ? await openUrl(url) : false;
return { url, warning, opened, close: () => { child.kill(); }, ended };
}
Expand Down
4 changes: 2 additions & 2 deletions core/leases.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import { spawn } from "node:child_process";
import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync } from "node:fs";
import { hostname } from "node:os";
import path from "node:path";
import { currentHost, VALID_NAME } from "./boxery-core.mjs";
import { cliHint, currentHost, VALID_NAME } from "./boxery-core.mjs";
import { reapplyPushed } from "./grant-operations.mjs";
import { writeAtomic } from "./fsutil.mjs";
import { closeMaster, hostLeaseJson, hostRun, writeSshConfig } from "./profile.mjs";
Expand Down Expand Up @@ -66,7 +66,7 @@ export function findLease(ref) {
/** @param {string} ref */
function needLease(ref) {
const r = typeof ref === "string" && ref ? findLease(ref) : null;
if (!r) throw new Error(`no local lease for '${ref ?? ""}' (boxery leases)`);
if (!r) throw new Error(`no local lease for '${ref ?? ""}' (${cliHint("leases")})`);
return r;
}

Expand Down
2 changes: 1 addition & 1 deletion docs/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -430,7 +430,7 @@ Generated from the help `boxery help --all` shows (`controller/cli.mjs`); edit i

`boxery-host help` lists every command; `boxery-host COMMAND --help` shows one. Generated from the same help (`host/help.mjs`); edit it there, then `npm run docs:cli`. `--profile NAME` before any command runs it in a second profile on this host (`~/.config/boxery-NAME`: its own backend, state, proxy port and services); `--profile NAME init --backend B` creates it with a free proxy port. `upgrade` keeps the code and each profile's state from before in `$BOXERY_CONF/pre-upgrade/` after a success too.

Commands in messages name what you typed. The follow-up commands `boxery` prints (`run --bg`'s logs and wait, `prompt`, `acquire`, `ls`) keep your `--host NAME`; and when `boxery` runs a host command for you, it passes `BOXERY_CLI` (`boxery`, or `boxery --host NAME` if you gave one), so a host error suggests `boxery --host lab snap-rm demo s1` rather than `boxery-host snap-rm demo s1`. Commands only boxery-host has (`init`, …) keep its name. Called directly, boxery-host names itself.
Commands in messages name what you typed. The follow-up commands `boxery` prints (`run --bg`'s logs and wait, `prompt`, `acquire`, `ls`) keep your `--host NAME`; and when `boxery` runs a host command for you, it passes `BOXERY_CLI` (`boxery`, or `boxery --host NAME` if you gave one), so a host error suggests `boxery --host lab snap-rm demo s1` rather than `boxery-host snap-rm demo s1`. Commands only boxery-host has (`init`, …) keep its name. Called directly, boxery-host names itself. Messages about a VM that can't be reached (`no such vm`, not running, a pool VM without a lease) name `--host NAME` when you gave one or when the VM's host isn't the default (another host's VM in `cp`, an agent's host session), since a bare `boxery start NAME` would go to the default host.

<!-- BEGIN generated: boxery-host commands (npm run docs:cli) -->

Expand Down
4 changes: 2 additions & 2 deletions host/capabilities.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
import { accessSync, constants } from "node:fs";
import path from "node:path";
import { BACKENDS, backendMetadata, capabilityStatus, declared, matchesPlatform, platformStatus } from "../backends/index.mjs";
import { fail, log, print } from "./util.mjs";
import { fail, hint, log, print } from "./util.mjs";
import { hostUsage } from "./help.mjs";
/** @import { Configuration, Requirement } from "../backends/index.mjs" */
/** @import { Runtime } from "./runtime.mjs" */
Expand Down Expand Up @@ -88,5 +88,5 @@ export function checkOperation(backend, command, args) {
?? (command === "pool" && args[0] === "add" ? "pools" : null);
if (!feature) return;
const c = metadata.capabilities[feature];
if (c.status === "unsupported") fail(`${backend}: ${feature} is unavailable. ${c.note}. Discover alternatives with boxery backends --json.`);
if (c.status === "unsupported") fail(`${backend}: ${feature} is unavailable. ${c.note}. Discover alternatives with ${hint("backends --json")}.`);
}
2 changes: 1 addition & 1 deletion host/patch.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ export async function patchVm(rt, args) {
/** @type {GuestEndpoint} */
let ep;
try { ep = await rt.vms.sshEndpoint(name, { quiet: true }); } catch { return fail(`${name} is not running (start it first)`); }
const t0 = Date.now(), secs = () => Math.floor((Date.now() - t0) / 1000);
const t0 = performance.now(), secs = () => Math.floor((performance.now() - t0) / 1000); // monotonic: a wall clock can step back
// A crash from here on leaves a pool VM between clean images: recovery puts it back to one (recovery.mjs).
const action = row ? rt.intent("pool-patch", name) : "";
if (await rt.guest.run(ep, "sudo bash -s", { input: await pushScript(rt) }) !== 0) fail(`could not install this host's image layers in ${name}`);
Expand Down
4 changes: 2 additions & 2 deletions host/setup.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ import { checkBackend } from "./capabilities.mjs";
import { defaultConf, HOST_ENV } from "./config.mjs";
import { ensureHostKey, hasHostKey } from "./hostkeys.mjs";
import { baseUserdata } from "./seed.mjs";
import { fail, jsonArray, log, print, readFd, sleep, table } from "./util.mjs";
import { fail, hint, jsonArray, log, print, readFd, sleep, table } from "./util.mjs";
import { hostUsage } from "./help.mjs";
/** @import { Config } from "./config.mjs" */
/** @import { Runtime } from "./runtime.mjs" */
Expand Down Expand Up @@ -324,7 +324,7 @@ async function pinExisting(rt) {
if (await ensureHostKey(rt, vm.name, await rt.vms.sshEndpoint(vm.name, { quiet: true }))) left.push(vm.name);
} catch { left.push(vm.name); }
}
if (left.length) log(`${left.length} VM(s) have no pinned ssh host key yet (${left.join(", ")}): boxery start pins a stopped one; for a running one run boxery pin NAME`);
if (left.length) log(`${left.length} VM(s) have no pinned ssh host key yet (${left.join(", ")}): ${hint("start NAME")} pins a stopped one; for a running one run ${hint("pin NAME")}`);
}

// ---------------------------------------------------------------- commands
Expand Down
14 changes: 7 additions & 7 deletions host/vms.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -136,7 +136,7 @@ export async function createVm(rt, { name, shape, cpus, mem, disk, from, headles
} else if (!await rt.vms.hasBase()) {
fail(`no base image; run: ${hint("build-base")} (or: new ${name} --headless, which needs none)`);
}
const t0 = Date.now(), secs = () => Math.floor((Date.now() - t0) / 1000);
const t0 = performance.now(), secs = () => Math.floor((performance.now() - t0) / 1000); // monotonic: a wall clock can step back
// Opt-in diagnostics stay on stderr and never include seed contents, tokens or SSH commands.
/** @template T @param {string} stage @param {() => Promise<T>} fn @returns {Promise<T>} */
const step = async (stage, fn) => {
Expand Down Expand Up @@ -195,8 +195,8 @@ export async function createVm(rt, { name, shape, cpus, mem, disk, from, headles
function warnOutdated(rt, name, rec, source) {
const { status, reasons } = guestChecker(rt)(rec, { image: true }); // what it was built with; a reboot is the guest's own
if (status !== "outdated" || !source) return;
const fix = source === "the desktop base" ? "; to make new desktop VMs current, rebuild the base (boxery build-base) once no VM depends on it" : "";
log(`warning: ${name} is an outdated guest (${reasons.join(", ")}), as ${source} is; update it with: boxery patch ${name}${fix}`);
const fix = source === "the desktop base" ? `; to make new desktop VMs current, rebuild the base (${hint("build-base")}) once no VM depends on it` : "";
log(`warning: ${name} is an outdated guest (${reasons.join(", ")}), as ${source} is; update it with: ${hint(`patch ${name}`)}${fix}`);
}

/** @param {Runtime} rt @param {string[]} args */
Expand Down Expand Up @@ -247,7 +247,7 @@ export async function fork(rt, args) {
}
const image = `${src}@fork-${stamp()}-${randomBytes(3).toString("hex")}`;
const cleanup = rt.intent("fork-image", image);
const t0 = Date.now(), secs = () => Math.floor((Date.now() - t0) / 1000);
const t0 = performance.now(), secs = () => Math.floor((performance.now() - t0) / 1000);
await captureVm(rt, src, image);
log(`captured ${src} in ${secs()}s; booting ${dsts.length} fork(s)`);
// Boot the forks in parallel under this operation's locks; print results in argument order. A failed
Expand All @@ -266,7 +266,7 @@ export async function fork(rt, args) {
await rt.vms.call("backend_image_rm", [image]);
// Once for all the forks, naming SRC: patching it first gives current forks (#215).
const { status, reasons } = guestChecker(rt)(buildRecord(rt.conf, image), { image: true });
if (status === "outdated" && results.some((r) => r.status === "fulfilled")) log(`warning: ${src} is an outdated guest (${reasons.join(", ")}), and so are its forks; update them with: boxery patch NAME (patch ${src} first to fork current copies)`);
if (status === "outdated" && results.some((r) => r.status === "fulfilled")) log(`warning: ${src} is an outdated guest (${reasons.join(", ")}), and so are its forks; update them with: ${hint("patch NAME")} (patch ${src} first to fork current copies)`);
deleteBuildRecord(rt.conf, image);
rt.done(cleanup);
log(`forked ${src} → ${dsts.join(" ")} in ${secs()}s`);
Expand Down Expand Up @@ -335,13 +335,13 @@ export async function stop(rt, [name]) {
const was = stoppedAs(rt, vm?.state ?? "");
if (was && (!vm?.tunnel || vm.tunnel === "down")) { log(`${name} is already ${was}`); return; }
await rt.vms.call("backend_stop", [name]);
const wait = Number(rt.env?.BOXERY_STOP_WAIT) > 0 ? Number(rt.env?.BOXERY_STOP_WAIT) : 120, t0 = Date.now();
const wait = Number(rt.env?.BOXERY_STOP_WAIT) > 0 ? Number(rt.env?.BOXERY_STOP_WAIT) : 120, t0 = performance.now();
for (let announced = false; ;) {
const now = await inventoryEntry(rt, name);
if (!now) { log(`${name} shutting down`); return; } // can't tell: as before
const as = stoppedAs(rt, now.state);
if (as) { log(`${name} ${as}`); return; }
if (Date.now() - t0 >= wait * 1000) fail(`${name} is still ${now.state || "running"} ${wait}s after it was asked to shut down; run stop again, or look at the guest's console`);
if (performance.now() - t0 >= wait * 1000) fail(`${name} is still ${now.state || "running"} ${wait}s after it was asked to shut down; run stop again, or look at the guest's console`);
if (!announced) { log(`${name} shutting down`); announced = true; }
await sleep(1000);
}
Expand Down
3 changes: 2 additions & 1 deletion test/cli-families.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,8 @@ test("malformed actions say what the family has, before any host, ssh or saved s
[["access", "apply", "demo", "--json"], 2, /usage: boxery access apply NAME/],
[["access", "apply", "demo", "--quiet", "x"], 2, /usage: boxery access apply NAME/],
[["access", "ls", "Demo"], 1, /invalid VM name: Demo/],
[["job", "kill", "demo"], 1, /invalid job id/],
[["job", "kill", "demo"], 2, /^boxery: missing job id \(see: boxery jobs NAME\)\n$/],
[["job", "kill", "demo", "nope"], 1, /^boxery: invalid job id: nope \(see: boxery jobs NAME\)\n$/],
[["job", "ls", "demo", "--frob"], 2, /^boxery: usage: boxery job ls NAME \[--json\]\n {7}boxery job ls NAME --prune/],
[["lease", "ls", "--frob"], 2, /^boxery: usage: boxery lease ls \[--json\]\n$/],
[["snapshot", "rm", "demo"], 2, /^boxery: usage: boxery snapshot rm NAME SNAP\n$/],
Expand Down
Loading
Loading