@starci/hfs 4.11.21 → 4.12.0

package/stack/age-install.d.mts

@@ -0,0 +1,13 @@
+import type { RunResult } from './context.mjs';
+/** Runs a shell command on the manager (see remote.mjs). */
+type Run = (command: string) => RunResult;
+/** The progress sink of a verb: notes and failures. */
+interface Report {
+    note(text: string): void;
+    bad(text: string): void;
+}
+/** The install command of each package manager installAge detects; a refusal names them for a host it cannot install on. */
+export declare const AGE_INSTALL: Record<string, string>;
+/** Installs age when it is missing; reports through `report`. */
+export declare function installAge(run: Run, report: Report): void;
+export {};

package/stack/age-install.mjs

@@ -1,27 +1,24 @@
 // age-install.mjs - installs `age` (the backup encryptor) on the manager over passwordless sudo: the host's own package manager first
 // (dnf, yum, apk or apt-get, detected, never assumed), then the official static binary with its sha256 verified before anything is installed.
 import { firstLine } from './context.mjs';
-
 const AGE_VERSION = 'v1.2.1';
 const AGE_URL = `https://github.com/FiloSottile/age/releases/download/${AGE_VERSION}/age-${AGE_VERSION}-linux-amd64.tar.gz`;
 /** sha256 of the official linux/amd64 archive of AGE_VERSION. */
 const AGE_SHA256 = '7df45a6cc87d4da11cc03a539a7470c15b1041ab2b396af088fe9990f7c79d50';
 /** The install command of each package manager installAge detects; a refusal names them for a host it cannot install on. */
 export const AGE_INSTALL = { dnf: 'sudo -n dnf install -y age', yum: 'sudo -n yum install -y age', apk: 'sudo -n apk add age', 'apt-get': 'sudo -n apt-get install -y age' };
-
 const STATIC_INSTALL = [
-  'set -e',
-  'tmp="$(mktemp -d)"',
-  'trap \'rm -rf "$tmp"\' EXIT',
-  `curl -fsSL -o "$tmp/age.tgz" ${AGE_URL}`,
-  `echo "${AGE_SHA256}  $tmp/age.tgz" | sha256sum -c -`,
-  'tar -xzf "$tmp/age.tgz" -C "$tmp"',
-  'sudo -n install -m 0755 "$tmp/age/age" "$tmp/age/age-keygen" /usr/local/bin/',
-  // sudo's secure_path (AlmaLinux 10, RHEL) leaves /usr/local/bin out: a link in /usr/bin makes both tools visible to the deploy
-  // user and to root alike; an existing /usr/bin tool (a packaged age) is kept.
-  'for b in age age-keygen; do if [ ! -e "/usr/bin/$b" ]; then sudo -n ln -s "/usr/local/bin/$b" "/usr/bin/$b"; fi; done',
+    'set -e',
+    'tmp="$(mktemp -d)"',
+    'trap \'rm -rf "$tmp"\' EXIT',
+    `curl -fsSL -o "$tmp/age.tgz" ${AGE_URL}`,
+    `echo "${AGE_SHA256}  $tmp/age.tgz" | sha256sum -c -`,
+    'tar -xzf "$tmp/age.tgz" -C "$tmp"',
+    'sudo -n install -m 0755 "$tmp/age/age" "$tmp/age/age-keygen" /usr/local/bin/',
+    // sudo's secure_path (AlmaLinux 10, RHEL) leaves /usr/local/bin out: a link in /usr/bin makes both tools visible to the deploy
+    // user and to root alike; an existing /usr/bin tool (a packaged age) is kept.
+    'for b in age age-keygen; do if [ ! -e "/usr/bin/$b" ]; then sudo -n ln -s "/usr/local/bin/$b" "/usr/bin/$b"; fi; done',
 ].join('; ');
-
 const packageManager = (run) => run('for m in dnf yum apk apt-get; do command -v $m >/dev/null 2>&1 && echo $m && break; done').stdout.trim();
 /**
  * Both tools, as the deploy user and, where passwordless sudo exists, as root: an install the root PATH cannot see is not taken
@@ -29,18 +26,24 @@ const packageManager = (run) => run('for m in dnf yum apk apt-get; do command -v
  */
 const PRESENT = 'command -v age >/dev/null 2>&1 && command -v age-keygen >/dev/null 2>&1 && { [ "$(id -u)" -eq 0 ] || ! sudo -n true 2>/dev/null || sudo -n sh -c \'command -v age >/dev/null 2>&1 && command -v age-keygen >/dev/null 2>&1\'; }';
 const present = (run) => run(PRESENT).status === 0;
-
 /** Installs age when it is missing; reports through `report`. */
 export function installAge(run, report) {
-  if (present(run)) return;
-  const manager = packageManager(run);
-  let failure = 'no package manager (dnf, yum, apk, apt-get) found';
-  if (Object.hasOwn(AGE_INSTALL, manager)) {
-    const packaged = run(AGE_INSTALL[manager]);
-    if (packaged.status === 0 && present(run)) { report.note(`installed age with ${manager}`); return; }
-    failure = `${manager} could not install age: ${firstLine(packaged.stderr)}`;
-  }
-  const fetched = run(STATIC_INSTALL);
-  if (fetched.status === 0 && present(run)) report.note(`installed the official static age ${AGE_VERSION} (sha256 verified) into /usr/local/bin, linked from /usr/bin; ${failure}`);
-  else report.bad(`cannot install age (${failure}); the static install failed too: ${firstLine(fetched.stderr)} (needs passwordless sudo once, or install age by hand)`);
+    if (present(run))
+        return;
+    const manager = packageManager(run);
+    let failure = 'no package manager (dnf, yum, apk, apt-get) found';
+    const installCommand = Object.hasOwn(AGE_INSTALL, manager) ? AGE_INSTALL[manager] : undefined;
+    if (installCommand !== undefined) {
+        const packaged = run(installCommand);
+        if (packaged.status === 0 && present(run)) {
+            report.note(`installed age with ${manager}`);
+            return;
+        }
+        failure = `${manager} could not install age: ${firstLine(packaged.stderr)}`;
+    }
+    const fetched = run(STATIC_INSTALL);
+    if (fetched.status === 0 && present(run))
+        report.note(`installed the official static age ${AGE_VERSION} (sha256 verified) into /usr/local/bin, linked from /usr/bin; ${failure}`);
+    else
+        report.bad(`cannot install age (${failure}); the static install failed too: ${firstLine(fetched.stderr)} (needs passwordless sudo once, or install age by hand)`);
 }

package/stack/backup.d.mts

@@ -0,0 +1,11 @@
+import type { DeployConfig } from './config.mjs';
+import type { StackContext } from './context.mjs';
+import type { ActionResult, RunnerDeps } from './remote.mjs';
+/** What `backup` takes besides the SSH command. */
+export interface BackupOptions {
+    swarmState?: boolean;
+    execute?: boolean;
+    sshCmd?: string | null;
+}
+/** backup: the plan without execute; with execute the encrypted archives, then the retention sweep. */
+export declare function backupVolumes(ctx: StackContext, config: DeployConfig, { swarmState, execute, sshCmd }?: BackupOptions, deps?: RunnerDeps): Promise<ActionResult>;

package/stack/backup.mjs

@@ -10,91 +10,98 @@ import { firstLine } from './context.mjs';
 import { failure, refusal } from './errors.mjs';
 import { shellQuote, withRunner } from './remote.mjs';
 import { parseYaml } from '../runtime/engine/yaml.mjs';
-
 const RECIPIENT = /age1[0-9a-z]{50,}/u;
-
+const declaresBackup = (config) => Boolean(config.backup);
 /** The first age recipient of the creation_rules of <repoRoot>/.sops.yaml. */
 function readRecipient(repoRoot) {
-  let rules;
-  try { rules = parseYaml(fs.readFileSync(path.join(repoRoot, '.sops.yaml'), 'utf8'))?.creation_rules; } catch { rules = null; }
-  const found = RECIPIENT.exec(JSON.stringify(rules ?? null));
-  if (!found) throw refusal('STACK_BACKUP_NO_RECIPIENT', 'no age recipient found in the creation_rules of .sops.yaml');
-  return found[0];
+    let rules;
+    try {
+        rules = parseYaml(fs.readFileSync(path.join(repoRoot, '.sops.yaml'), 'utf8'))?.creation_rules;
+    }
+    catch {
+        rules = null;
+    }
+    const found = RECIPIENT.exec(JSON.stringify(rules ?? null));
+    if (!found)
+        throw refusal('STACK_BACKUP_NO_RECIPIENT', 'no age recipient found in the creation_rules of .sops.yaml');
+    return found[0];
 }
-
 /** YYYYMMDD-HHMMSS in UTC. */
 const stampOf = (epochMs) => new Date(epochMs).toISOString().slice(0, 19).replaceAll('-', '').replaceAll(':', '').replace('T', '-');
-
 function archiveJob(name, producer, { dir, stamp, recipient }) {
-  const final = `${dir}/${name}-${stamp}.tgz.age`;
-  const partial = `${final}.partial`;
-  const script = [
-    'set -o pipefail', 'umask 077', `mkdir -p ${shellQuote(dir)}`,
-    `${producer} | age -r ${shellQuote(recipient)} -o ${shellQuote(partial)} && mv ${shellQuote(partial)} ${shellQuote(final)} || { rm -f ${shellQuote(partial)}; exit 1; }`,
-  ].join('; ');
-  return { name: `${name}-${stamp}.tgz.age`, command: `bash -c ${shellQuote(script)}` };
+    const final = `${dir}/${name}-${stamp}.tgz.age`;
+    const partial = `${final}.partial`;
+    const script = [
+        'set -o pipefail', 'umask 077', `mkdir -p ${shellQuote(dir)}`,
+        `${producer} | age -r ${shellQuote(recipient)} -o ${shellQuote(partial)} && mv ${shellQuote(partial)} ${shellQuote(final)} || { rm -f ${shellQuote(partial)}; exit 1; }`,
+    ].join('; ');
+    return { name: `${name}-${stamp}.tgz.age`, command: `bash -c ${shellQuote(script)}` };
 }
-
 function planJobs(config, { swarmState, stamp, recipient }) {
-  const dir = config.backup.dir ?? `/var/backups/${config.stack}`;
-  const shared = { dir, stamp, recipient };
-  const jobs = config.backup.volumes.map((entry) => {
-    const mount = shellQuote(`${entry.volume}:/src:ro`);
-    return archiveJob(entry.name, `docker run --rm -v ${mount} ${shellQuote(config.backup.image)} tar czf - -C /src .`, shared);
-  });
-  if (swarmState) jobs.push(archiveJob('swarm-state', 'sudo tar czf - -C /var/lib/docker swarm', shared));
-  return { dir, jobs };
+    const dir = config.backup.dir ?? `/var/backups/${config.stack}`;
+    const shared = { dir, stamp, recipient };
+    const jobs = config.backup.volumes.map((entry) => {
+        const mount = shellQuote(`${entry.volume}:/src:ro`);
+        return archiveJob(entry.name, `docker run --rm -v ${mount} ${shellQuote(config.backup.image)} tar czf - -C /src .`, shared);
+    });
+    if (swarmState)
+        jobs.push(archiveJob('swarm-state', 'sudo tar czf - -C /var/lib/docker swarm', shared));
+    return { dir, jobs };
 }
-
-const pruneCommand = (dir, keepDays) => String.raw`find ${shellQuote(dir)} -type f \( -name '*.age' -o -name '*.age.partial' \) -mtime +${Number(keepDays)} -delete`;
-
+const pruneCommand = (dir, keepDays) => String.raw `find ${shellQuote(dir)} -type f \( -name '*.age' -o -name '*.age.partial' \) -mtime +${Number(keepDays)} -delete`;
 function describePlan(config, plan, recipient, swarmState) {
-  const names = config.backup.volumes.map((entry) => entry.name);
-  return [
-    `volumes: ${names.join(', ')}${swarmState ? ' and the swarm state' : ''}`,
-    `target on the manager: ${plan.dir} (keep ${config.backup.keepDays} days)`,
-    `age recipient: ${recipient.slice(0, 12)}... (public recipient of .sops.yaml)`,
-    `files: ${plan.jobs.map((job) => job.name).join(', ')}`,
-  ];
+    const names = config.backup.volumes.map((entry) => entry.name);
+    return [
+        `volumes: ${names.join(', ')}${swarmState ? ' and the swarm state' : ''}`,
+        `target on the manager: ${plan.dir} (keep ${config.backup.keepDays} days)`,
+        `age recipient: ${recipient.slice(0, 12)}... (public recipient of .sops.yaml)`,
+        `files: ${plan.jobs.map((job) => job.name).join(', ')}`,
+    ];
 }
-
 const REMINDERS = [
-  'the files are encrypted but still on the manager: copy them to storage in another failure domain',
-  'a restore proof on an isolated host (age -d with the owner identity) is the job of the owner',
+    'the files are encrypted but still on the manager: copy them to storage in another failure domain',
+    'a restore proof on an isolated host (age -d with the owner identity) is the job of the owner',
 ];
-
 function runArchives(run, plan) {
-  const lines = [];
-  const files = [];
-  for (const job of plan.jobs) {
-    const result = run(job.command);
-    if (result.status === 0) {
-      files.push(job.name);
-      lines.push(`ok    ${job.name}`);
-    } else lines.push(`FAIL  ${job.name}: ${firstLine(result.stderr)}`);
-  }
-  return { lines, files };
+    const lines = [];
+    const files = [];
+    for (const job of plan.jobs) {
+        const result = run(job.command);
+        if (result.status === 0) {
+            files.push(job.name);
+            lines.push(`ok    ${job.name}`);
+        }
+        else
+            lines.push(`FAIL  ${job.name}: ${firstLine(result.stderr)}`);
+    }
+    return { lines, files };
 }
-
 /** backup: the plan without execute; with execute the encrypted archives, then the retention sweep. */
 export async function backupVolumes(ctx, config, { swarmState = false, execute = false, sshCmd = null } = {}, deps = {}) {
-  if (!config.backup) throw refusal('STACK_BACKUP_UNDECLARED', 'the environment declares no deploy.backup block');
-  const recipient = readRecipient(config.repoRoot);
-  const plan = planJobs(config, { swarmState, stamp: stampOf(ctx.now()), recipient });
-  const summary = describePlan(config, plan, recipient, swarmState);
-  if (!execute) return { ok: true, lines: ['dry run: nothing was backed up', ...summary], data: { files: [], planned: plan.jobs.map((job) => job.name) } };
-  return withRunner(ctx, config, { sshCmd }, deps, (run, notes) => {
-    if (run('command -v age >/dev/null 2>&1').status !== 0) throw refusal('STACK_BACKUP_NO_AGE', 'age is not installed on the manager (apt install age)');
-    const done = runArchives(run, plan);
-    const lines = [...notes, ...summary, ...done.lines];
-    const complete = done.files.length === plan.jobs.length;
-    if (complete) {
-      const pruned = run(pruneCommand(plan.dir, config.backup.keepDays));
-      if (pruned.status !== 0) throw failure('STACK_BACKUP_PRUNE', `deleting backups older than ${config.backup.keepDays} days failed: ${firstLine(pruned.stderr)}`);
-      lines.push(`ok    removed backups older than ${config.backup.keepDays} days`);
-    } else lines.push('old backups were kept because this run did not finish');
-    lines.push(...REMINDERS);
-    if (swarmState) lines.push('the swarm state archive is orchestration state, not a database backup');
-    return { ok: complete, lines, data: { files: done.files } };
-  });
+    if (!declaresBackup(config))
+        throw refusal('STACK_BACKUP_UNDECLARED', 'the environment declares no deploy.backup block');
+    const recipient = readRecipient(config.repoRoot);
+    const plan = planJobs(config, { swarmState, stamp: stampOf(ctx.now()), recipient });
+    const summary = describePlan(config, plan, recipient, swarmState);
+    if (!execute)
+        return { ok: true, lines: ['dry run: nothing was backed up', ...summary], data: { files: [], planned: plan.jobs.map((job) => job.name) } };
+    return withRunner(ctx, config, { sshCmd }, deps, (run, notes) => {
+        if (run('command -v age >/dev/null 2>&1').status !== 0)
+            throw refusal('STACK_BACKUP_NO_AGE', 'age is not installed on the manager (apt install age)');
+        const done = runArchives(run, plan);
+        const lines = [...notes, ...summary, ...done.lines];
+        const complete = done.files.length === plan.jobs.length;
+        if (complete) {
+            const pruned = run(pruneCommand(plan.dir, config.backup.keepDays));
+            if (pruned.status !== 0)
+                throw failure('STACK_BACKUP_PRUNE', `deleting backups older than ${config.backup.keepDays} days failed: ${firstLine(pruned.stderr)}`);
+            lines.push(`ok    removed backups older than ${config.backup.keepDays} days`);
+        }
+        else
+            lines.push('old backups were kept because this run did not finish');
+        lines.push(...REMINDERS);
+        if (swarmState)
+            lines.push('the swarm state archive is orchestration state, not a database backup');
+        return { ok: complete, lines, data: { files: done.files } };
+    });
 }

package/stack/build-args.d.mts

@@ -0,0 +1,7 @@
+import type { DeployConfig } from './config.mjs';
+import type { StackContext } from './context.mjs';
+import type { ActionResult } from './remote.mjs';
+/** The build values of the image whose `app` is `options.app`. */
+export declare function buildArgs(ctx: StackContext, config: DeployConfig, options: {
+    app: string | undefined;
+}): Promise<ActionResult>;

package/stack/build-args.mjs

@@ -4,39 +4,38 @@
 import fs from 'node:fs';
 import { refusal } from './errors.mjs';
 import { openMember } from './sealed.mjs';
-
 const OUTPUT_DELIMITER = 'BUILD_ARGS_OUTPUT_END';
 const ONE_LINE = /^[^\r\n]+$/u;
-
 function imageOf(config, app) {
-  const found = Object.entries(config.images).find(([, entry]) => entry.app === app);
-  if (!found) throw refusal('STACK_APP_UNKNOWN', `no image of the deploy block builds the app ${app}`);
-  return { service: found[0], buildArgs: found[1].buildArgs };
+    const found = Object.entries(config.images).find(([, entry]) => entry.app === app);
+    if (!found)
+        throw refusal('STACK_APP_UNKNOWN', `no image of the deploy block builds the app ${app}`);
+    return { service: found[0], buildArgs: found[1].buildArgs };
 }
-
 function checkedValue(key, value) {
-  if (typeof value !== 'string' || !ONE_LINE.test(value)) throw refusal('STACK_BUILD_ARG_INVALID', `${key} must be present and one line`);
-  return value;
+    if (typeof value !== 'string' || !ONE_LINE.test(value))
+        throw refusal('STACK_BUILD_ARG_INVALID', `${key} must be present and one line`);
+    return value;
 }
-
 function sealedValues(ctx, config, sealed) {
-  if (sealed === null) return {};
-  const map = openMember(ctx, config, sealed.member);
-  return Object.fromEntries(sealed.keys.map((key) => [key, checkedValue(key, map[key])]));
+    if (sealed === null)
+        return {};
+    const map = openMember(ctx, config, sealed.member);
+    return Object.fromEntries(sealed.keys.map((key) => [key, checkedValue(key, map[key])]));
 }
-
 function publish(ctx, sealed, lines) {
-  if (ctx.env.GITHUB_ACTIONS !== 'true') return [];
-  if (ctx.env.GITHUB_OUTPUT) fs.appendFileSync(ctx.env.GITHUB_OUTPUT, `args<<${OUTPUT_DELIMITER}\n${lines.join('\n')}\n${OUTPUT_DELIMITER}\n`);
-  return Object.values(sealed).map((value) => `::add-mask::${value}`);
+    if (ctx.env.GITHUB_ACTIONS !== 'true')
+        return [];
+    if (ctx.env.GITHUB_OUTPUT)
+        fs.appendFileSync(ctx.env.GITHUB_OUTPUT, `args<<${OUTPUT_DELIMITER}\n${lines.join('\n')}\n${OUTPUT_DELIMITER}\n`);
+    return Object.values(sealed).map((value) => `::add-mask::${value}`);
 }
-
 /** The build values of the image whose `app` is `options.app`. */
 export async function buildArgs(ctx, config, options) {
-  const { service, buildArgs: declared } = imageOf(config, options.app);
-  const literal = Object.fromEntries(Object.entries(declared.values).map(([key, value]) => [key, checkedValue(key, value)]));
-  const sealed = sealedValues(ctx, config, declared.sealed);
-  const pairs = Object.entries({ ...literal, ...sealed }).map(([key, value]) => `${key}=${value}`);
-  const masks = publish(ctx, sealed, pairs);
-  return { ok: true, lines: [...masks, ...pairs], data: { app: options.app, service, keys: Object.keys({ ...literal, ...sealed }) } };
+    const { service, buildArgs: declared } = imageOf(config, options.app);
+    const literal = Object.fromEntries(Object.entries(declared.values).map(([key, value]) => [key, checkedValue(key, value)]));
+    const sealed = sealedValues(ctx, config, declared.sealed);
+    const pairs = Object.entries({ ...literal, ...sealed }).map(([key, value]) => `${key}=${value}`);
+    const masks = publish(ctx, sealed, pairs);
+    return { ok: true, lines: [...masks, ...pairs], data: { app: options.app, service, keys: Object.keys({ ...literal, ...sealed }) } };
 }

package/stack/build.d.mts

@@ -0,0 +1,8 @@
+import type { DeployConfig } from './config.mjs';
+import type { StackContext } from './context.mjs';
+import type { ActionResult } from './remote.mjs';
+/** `build`: dry run unless execute; pushing needs --push as well. */
+export declare function buildImages(ctx: StackContext, config: DeployConfig, { push, execute }?: {
+    push?: boolean;
+    execute?: boolean;
+}): Promise<ActionResult>;