@w3cj/fwd 0.0.0-stage → 0.1.0

package/src/help.js

@@ -0,0 +1,45 @@
+import { readFileSync } from 'node:fs';
+import { commands, helpOption, hostOption, optionsFor } from './commands/index.js';
+
+/** @typedef {import('./commands/common.js').Command} Command */
+/** @typedef {import('./commands/common.js').Option} Option */
+
+export const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+/** @param {[string, string][]} rows */
+function table(rows) {
+  const width = Math.max(...rows.map(([left]) => left.length));
+  return rows.map(([left, right]) => `  ${left.padEnd(width)}  ${right}`).join('\n');
+}
+
+/**
+ * @param {Record<string, Option>} options
+ * @returns {[string, string][]}
+ */
+function optionRows(options) {
+  return Object.entries(options).map(([name, opt]) => [
+    `${opt.short ? `-${opt.short}, ` : ''}--${name}${opt.type === 'string' ? ` <${opt.value ?? name}>` : ''}`,
+    opt.help,
+  ]);
+}
+
+export function mainHelp() {
+  return `fwd ${version}: manage SSH port forwards over a single ControlMaster connection
+
+Usage: fwd <command> [options]
+
+Commands:
+${table(commands.filter((c) => !c.hidden).map((c) => [c.name, c.summary]))}
+
+Options:
+${table([...optionRows({ ...hostOption, ...helpOption }), ['-v, --version', 'Show the version']])}
+
+Run \`fwd help <command>\` for details. Start with \`fwd config set host <host>\`.`;
+}
+
+/** @param {Command} cmd */
+export function commandHelp(cmd) {
+  const usage = cmd.usage.map((line, i) => `${i === 0 ? 'Usage: ' : '       '}${line}`).join('\n');
+  const description = cmd.description ? `\n\n${cmd.description}` : '';
+  return `${usage}\n\n${cmd.summary}.${description}\n\nOptions:\n${table(optionRows(optionsFor(cmd)))}`;
+}

package/src/lock.js

@@ -0,0 +1,76 @@
+import { link, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { FwdError } from './errors.js';
+import { configDir } from './paths.js';
+
+const TIMEOUT_MS = 60_000;
+
+function lockPath() {
+  return join(configDir(), 'lock');
+}
+
+/** @param {number} pid */
+function isRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return /** @type {NodeJS.ErrnoException} */ (err).code === 'EPERM';
+  }
+}
+
+/**
+ * Create the lock file atomically with our pid already in it: write a temp
+ * file, then hard-link it into place (link fails if the lock exists).
+ * @returns {Promise<boolean>}
+ */
+async function tryAcquire() {
+  const file = lockPath();
+  const tmp = `${file}.${process.pid}`;
+  await writeFile(tmp, String(process.pid));
+  try {
+    await link(tmp, file);
+    return true;
+  } catch (err) {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code === 'EEXIST') return false;
+    throw err;
+  } finally {
+    await rm(tmp, { force: true });
+  }
+}
+
+/**
+ * Run fn while holding an exclusive lock, so concurrent fwd commands can't
+ * lose each other's state updates or start two masters for one host. A lock
+ * left by a process that no longer exists is taken over.
+ * @template T
+ * @param {() => Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+export async function withLock(fn) {
+  await mkdir(configDir(), { recursive: true });
+  const started = Date.now();
+  let waiting = false;
+
+  while (!(await tryAcquire())) {
+    const holder = Number(await readFile(lockPath(), 'utf8').catch(() => ''));
+    if (holder && !isRunning(holder)) {
+      await rm(lockPath(), { force: true });
+      continue;
+    }
+    if (Date.now() - started > TIMEOUT_MS) {
+      throw new FwdError(`Another fwd command (pid ${holder}) is still running. If it's stuck, stop it and try again.`);
+    }
+    if (!waiting && Date.now() - started > 1000) {
+      console.error(`fwd: waiting for another fwd command (pid ${holder}) to finish...`);
+      waiting = true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+
+  try {
+    return await fn();
+  } finally {
+    await rm(lockPath(), { force: true });
+  }
+}

package/src/paths.js

@@ -0,0 +1,10 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// State, sockets and logs live in $XDG_CONFIG_HOME/fwd (~/.config/fwd by
+// default). FWD_CONFIG_DIR is an override so tests don't touch the real one.
+export function configDir() {
+  if (process.env.FWD_CONFIG_DIR) return process.env.FWD_CONFIG_DIR;
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+  return join(base, 'fwd');
+}

package/src/ports.js

@@ -0,0 +1,45 @@
+import net from 'node:net';
+
+/**
+ * True if something accepts TCP connections on 127.0.0.1:<port>.
+ * @param {number} port
+ * @param {number} [timeoutMs]
+ * @returns {Promise<boolean>}
+ */
+export function isPortListening(port, timeoutMs = 500) {
+  return new Promise((resolve) => {
+    const socket = net.connect({ port, host: '127.0.0.1' });
+    /** @param {boolean} result */
+    const done = (result) => {
+      socket.destroy();
+      resolve(result);
+    };
+    socket.setTimeout(timeoutMs, () => done(false));
+    socket.once('connect', () => done(true));
+    socket.once('error', () => done(false));
+  });
+}
+
+/**
+ * @param {number} port
+ * @returns {Promise<boolean>}
+ */
+function canBind(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', () => resolve(false));
+    server.listen({ port, host: '127.0.0.1', exclusive: true }, () => {
+      server.close(() => resolve(true));
+    });
+  });
+}
+
+/**
+ * True if ssh should be able to listen on localhost:<port>. Both checks are
+ * needed: on macOS a wildcard listener doesn't always block a 127.0.0.1 bind.
+ * @param {number} port
+ * @returns {Promise<boolean>}
+ */
+export async function isPortFree(port) {
+  return !(await isPortListening(port)) && (await canBind(port));
+}

package/src/spec.js

@@ -0,0 +1,145 @@
+import { FwdError } from './errors.js';
+
+/**
+ * 'local' listens on this machine and connects from the host (ssh -L).
+ * 'remote' listens on the host and connects from this machine (ssh -R).
+ * @typedef {'local' | 'remote'} Direction
+ */
+
+/**
+ * @typedef {object} Forward
+ * @property {Direction} direction
+ * @property {number} local Port on this machine.
+ * @property {number} remote Port on the host.
+ * @property {string} to Address dialled by the connecting side: from the host
+ *   for local forwards, from this machine for remote ones.
+ * @property {string} [addedAt]
+ */
+
+const DEFAULT_TO = '127.0.0.1';
+
+/**
+ * @param {string} value
+ * @param {string} label
+ * @returns {number}
+ */
+export function parsePort(value, label) {
+  if (!/^\d+$/.test(value)) {
+    throw new FwdError(`Invalid ${label} "${value}": expected a number.`);
+  }
+  const port = Number(value);
+  if (port < 1 || port > 65535) {
+    throw new FwdError(`Invalid ${label} ${port}: must be between 1 and 65535.`);
+  }
+  return port;
+}
+
+/**
+ * Parse "5173" or "8080:3000" (<local>:<remote> in both directions).
+ * @param {string} input
+ * @param {{ to?: string, reverse?: boolean }} [options]
+ * @returns {Forward}
+ */
+export function parseSpec(input, { to, reverse = false } = {}) {
+  const parts = input.split(':');
+  if (parts.length > 2) {
+    throw new FwdError(
+      `Invalid forward "${input}". Use <local> or <local>:<remote>, and --to <addr> for a different address.`,
+    );
+  }
+  const local = parsePort(parts[0], 'local port');
+  const remote = parts.length === 2 ? parsePort(parts[1], 'remote port') : local;
+  /** @type {Forward} */
+  const fwd = { direction: reverse ? 'remote' : 'local', local, remote, to: parseAddress(to) };
+
+  const listen = listenPort(fwd);
+  if (listen < 1024) {
+    const suggestion = reverse ? `${local}:${remote + 8000} --reverse` : `${local + 8000}:${remote}`;
+    throw new FwdError(
+      `${reverse ? 'Remote' : 'Local'} port ${listen} is privileged (below 1024). Listen on a higher port, e.g. \`fwd add ${suggestion}\`.`,
+    );
+  }
+  return fwd;
+}
+
+/**
+ * @param {string | undefined} to
+ * @returns {string}
+ */
+function parseAddress(to) {
+  if (to === undefined) return DEFAULT_TO;
+  // Accept "[::1]" as well as "::1"; brackets are added back when talking to ssh.
+  const address = to.replace(/^\[(.*)\]$/, '$1');
+  if (!address || /[\s[\]/]/.test(address)) {
+    throw new FwdError(`Invalid --to address "${to}".`);
+  }
+  return address;
+}
+
+/**
+ * The port that is listened on: on this machine for local forwards, on the
+ * host for remote ones.
+ * @param {Forward} fwd
+ */
+export function listenPort(fwd) {
+  return fwd.direction === 'local' ? fwd.local : fwd.remote;
+}
+
+/**
+ * Identifies a forward within a host: two forwards with the same key would
+ * listen on the same port.
+ * @param {Direction} direction
+ * @param {number} port The listen port.
+ */
+export function forwardKey(direction, port) {
+  return `${direction}:${port}`;
+}
+
+/** @param {Forward} fwd */
+export function keyOf(fwd) {
+  return forwardKey(fwd.direction, listenPort(fwd));
+}
+
+/** @param {string} address */
+function bracket(address) {
+  return address.includes(':') ? `[${address}]` : address;
+}
+
+/**
+ * The -L/-R arguments for ssh. `-O cancel` must receive exactly the same
+ * spec that `-O forward` did.
+ * @param {Forward} fwd
+ * @returns {[string, string]}
+ */
+export function toSshArgs(fwd) {
+  return fwd.direction === 'local'
+    ? ['-L', `${fwd.local}:${bracket(fwd.to)}:${fwd.remote}`]
+    : ['-R', `${fwd.remote}:${bracket(fwd.to)}:${fwd.local}`];
+}
+
+/**
+ * @param {Forward} a
+ * @param {Forward} b
+ */
+export function sameTarget(a, b) {
+  return a.direction === b.direction && a.local === b.local && a.remote === b.remote && a.to === b.to;
+}
+
+/** @param {string} address */
+function isLoopback(address) {
+  return address === DEFAULT_TO || address === 'localhost';
+}
+
+/**
+ * Human-readable forward, e.g. "localhost:5173 -> vm:5173",
+ * "localhost:5432 -> db:5432 (via vm)" or "vm:3000 -> localhost:3000".
+ * @param {Forward} fwd
+ * @param {string} host
+ */
+export function describe(fwd, host) {
+  if (fwd.direction === 'remote') {
+    return `${host}:${fwd.remote} -> ${isLoopback(fwd.to) ? 'localhost' : bracket(fwd.to)}:${fwd.local}`;
+  }
+  const target = isLoopback(fwd.to) ? `${host}:${fwd.remote}` : `${bracket(fwd.to)}:${fwd.remote} (via ${host})`;
+  return `localhost:${fwd.local} -> ${target}`;
+}

package/src/ssh.js

@@ -0,0 +1,180 @@
+// The only module that knows ssh's command-line syntax.
+import { execFile, spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { FwdError } from './errors.js';
+import { configDir } from './paths.js';
+import { describe, toSshArgs } from './spec.js';
+
+/** @typedef {import('./spec.js').Forward} Forward */
+
+// FWD_SSH lets tests (or users) point at a wrapper, e.g. one that adds -F.
+function sshBin() {
+  return process.env.FWD_SSH || 'ssh';
+}
+
+function sockDir() {
+  return join(configDir(), 'sock');
+}
+
+/**
+ * macOS caps Unix socket paths at 104 bytes, so use a short hash rather than
+ * the raw host string.
+ * @param {string} host
+ */
+export function socketPath(host) {
+  const hash = createHash('sha256').update(host).digest('hex').slice(0, 16);
+  return join(sockDir(), hash);
+}
+
+/** @param {string} host */
+export function logPath(host) {
+  return `${socketPath(host)}.log`;
+}
+
+/**
+ * @param {string[]} args
+ * @returns {Promise<{ code: number, stderr: string }>}
+ */
+function run(args) {
+  return new Promise((resolve, reject) => {
+    execFile(sshBin(), args, { timeout: 15_000 }, (err, _stdout, stderr) => {
+      if (err && /** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') {
+        reject(notFound());
+        return;
+      }
+      const code = err ? (typeof err.code === 'number' ? err.code : 1) : 0;
+      resolve({ code, stderr: stderr.replace(/\r/g, '').trim() });
+    });
+  });
+}
+
+function notFound() {
+  return new FwdError(`Could not run "${sshBin()}". Is OpenSSH installed and on your PATH?`);
+}
+
+/**
+ * Control commands only talk to the master's socket, so they skip the ssh
+ * config: otherwise `-O forward` would also send every LocalForward in it.
+ * @param {string} host
+ * @param {string} op
+ * @param {string[]} [extra]
+ */
+function control(host, op, extra = []) {
+  return run(['-F', 'none', '-S', socketPath(host), '-O', op, ...extra, '--', host]);
+}
+
+/**
+ * Turn ssh's stderr from a failed control command into a readable error.
+ * @param {string} host
+ * @param {string} action
+ * @param {string} stderr
+ */
+function controlError(host, action, stderr) {
+  if (/control socket connect|no such file|connection refused/i.test(stderr)) {
+    return new FwdError(`Could not ${action}: the SSH master for ${host} is not running.`);
+  }
+  const detail = stderr.replace(/^mux_?client\w*: /gm, '');
+  return new FwdError(`Could not ${action}: ${detail || 'ssh exited with an error'}`);
+}
+
+/**
+ * @param {string} host
+ * @returns {Promise<{ alive: true, pid: number | null } | { alive: false }>}
+ */
+export async function checkMaster(host) {
+  const { code, stderr } = await control(host, 'check');
+  if (code !== 0) return { alive: false };
+  const match = /pid=(\d+)/.exec(stderr);
+  return { alive: true, pid: match ? Number(match[1]) : null };
+}
+
+/**
+ * Start a ControlMaster in the background. stdin is inherited and ssh uses
+ * /dev/tty for passphrase and host-key prompts. stdout/stderr are not
+ * inherited because the backgrounded master would hold them open forever
+ * (breaking `fwd up | cat`); ssh logs to a file instead and we show that on
+ * failure.
+ *
+ * ClearAllForwardings drops LocalForward/RemoteForward lines from the user's
+ * ssh config: fwd's state is the only source of forwards, and with
+ * ExitOnForwardFailure a busy config port would stop the master starting.
+ * @param {string} host
+ */
+export async function startMaster(host) {
+  await mkdir(sockDir(), { recursive: true, mode: 0o700 });
+  const log = logPath(host);
+  await writeFile(log, '');
+  const args = [
+    '-M',
+    '-S', socketPath(host),
+    '-fN',
+    '-E', log,
+    '-o', 'ControlPersist=no',
+    '-o', 'ExitOnForwardFailure=yes',
+    '-o', 'ClearAllForwardings=yes',
+    '-o', 'ConnectTimeout=10',
+    '-o', 'ServerAliveInterval=15',
+    '-o', 'ServerAliveCountMax=3',
+    '--', host,
+  ];
+  /** @type {number} */
+  const code = await new Promise((resolve, reject) => {
+    const child = spawn(sshBin(), args, { stdio: ['inherit', 'ignore', 'ignore'] });
+    child.once('error', (err) => {
+      reject(/** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT' ? notFound() : err);
+    });
+    child.once('exit', (exitCode) => resolve(exitCode ?? 1));
+  });
+  if (code !== 0) {
+    const output = (await readFile(log, 'utf8').catch(() => '')).trim();
+    const detail = output ? `\n${output.replace(/^/gm, '  ')}` : '';
+    throw new FwdError(`Could not connect to ${host} (ssh exited with code ${code}).${detail}`);
+  }
+}
+
+/**
+ * @param {string} host
+ */
+export async function stopMaster(host) {
+  const { code, stderr } = await control(host, 'exit');
+  if (code !== 0) throw controlError(host, 'stop the SSH master', stderr);
+}
+
+/**
+ * Remove a socket file left behind by a master that died uncleanly.
+ * @param {string} host
+ */
+export async function removeSocket(host) {
+  await rm(socketPath(host), { force: true });
+}
+
+/**
+ * ssh can exit 0 even when the master rejected the request (e.g. cancelling a
+ * forward it doesn't have), so check stderr as well.
+ * @param {string} host
+ * @param {'forward' | 'cancel'} op
+ * @param {Forward} fwd
+ * @param {string} action
+ */
+async function forwardRequest(host, op, fwd, action) {
+  const { code, stderr } = await control(host, op, toSshArgs(fwd));
+  if (code !== 0 || /request failed/i.test(stderr)) throw controlError(host, action, stderr);
+}
+
+/**
+ * @param {string} host
+ * @param {Forward} fwd
+ */
+export function addForward(host, fwd) {
+  return forwardRequest(host, 'forward', fwd, `forward ${describe(fwd, host)}`);
+}
+
+/**
+ * @param {string} host
+ * @param {Forward} fwd
+ */
+export function cancelForward(host, fwd) {
+  return forwardRequest(host, 'cancel', fwd, `cancel ${describe(fwd, host)}`);
+}

package/src/state.js

@@ -0,0 +1,130 @@
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { FwdError } from './errors.js';
+import { configDir } from './paths.js';
+import { keyOf, listenPort } from './spec.js';
+
+/** @typedef {import('./spec.js').Forward} Forward */
+
+/**
+ * @typedef {object} State
+ * @property {string | null} defaultHost
+ * @property {Record<string, { forwards: Forward[] }>} hosts
+ */
+
+// Bump when the file format changes, and migrate older versions in loadState.
+const STATE_VERSION = 2;
+
+/**
+ * Version 1 (and unversioned 0.1.0 files) only had local forwards, with the
+ * dialled address in `remoteHost`.
+ * @param {{ local: number, remote: number, remoteHost: string, addedAt?: string }} fwd
+ * @returns {Forward}
+ */
+function migrateV1Forward({ local, remote, remoteHost, addedAt }) {
+  return { direction: 'local', local, remote, to: remoteHost, ...(addedAt && { addedAt }) };
+}
+
+export function statePath() {
+  return join(configDir(), 'state.json');
+}
+
+/** @returns {Promise<State>} */
+export async function loadState() {
+  let raw;
+  try {
+    raw = await readFile(statePath(), 'utf8');
+  } catch (err) {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') {
+      return { defaultHost: null, hosts: {} };
+    }
+    throw err;
+  }
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (err) {
+    throw new FwdError(`State file ${statePath()} is not valid JSON: ${/** @type {Error} */ (err).message}`);
+  }
+  // Files written by 0.1.0 have no version; they're the same format as 1.
+  const version = data.version ?? 1;
+  if (version > STATE_VERSION) {
+    throw new FwdError(`State file ${statePath()} was written by a newer version of fwd. Upgrade fwd to use it.`);
+  }
+  const hosts = data.hosts ?? {};
+  if (version < 2) {
+    for (const entry of Object.values(hosts)) entry.forwards = entry.forwards.map(migrateV1Forward);
+  }
+  return { defaultHost: data.defaultHost ?? null, hosts };
+}
+
+/**
+ * Write to a temp file and rename it into place so a crash can't leave a
+ * half-written state file.
+ * @param {State} state
+ */
+export async function saveState(state) {
+  const file = statePath();
+  await mkdir(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  try {
+    await writeFile(tmp, `${JSON.stringify({ version: STATE_VERSION, ...state }, null, 2)}\n`);
+    await rename(tmp, file);
+  } catch (err) {
+    await rm(tmp, { force: true });
+    throw err;
+  }
+}
+
+/**
+ * @param {State} state
+ * @param {string} host
+ * @returns {Forward[]}
+ */
+export function getForwards(state, host) {
+  return state.hosts[host]?.forwards ?? [];
+}
+
+/**
+ * @param {State} state
+ * @param {string} host
+ * @param {string} key From forwardKey/keyOf.
+ * @returns {Forward | undefined}
+ */
+export function findForward(state, host, key) {
+  return getForwards(state, host).find((f) => keyOf(f) === key);
+}
+
+/**
+ * Store forwards sorted by direction then listen port, dropping the host once
+ * it has none.
+ * @param {State} state
+ * @param {string} host
+ * @param {Forward[]} forwards
+ */
+function setForwards(state, host, forwards) {
+  if (forwards.length) {
+    state.hosts[host] = { ...state.hosts[host], forwards: forwards.sort((a, b) => a.direction.localeCompare(b.direction) || listenPort(a) - listenPort(b)) };
+  } else {
+    delete state.hosts[host];
+  }
+}
+
+/**
+ * Add or replace the forward that listens on the same port.
+ * @param {State} state
+ * @param {string} host
+ * @param {Forward} fwd
+ */
+export function putForward(state, host, fwd) {
+  setForwards(state, host, [...getForwards(state, host).filter((f) => keyOf(f) !== keyOf(fwd)), fwd]);
+}
+
+/**
+ * @param {State} state
+ * @param {string} host
+ * @param {string} key From forwardKey/keyOf.
+ */
+export function removeForward(state, host, key) {
+  setForwards(state, host, getForwards(state, host).filter((f) => keyOf(f) !== key));
+}