88 lines
4.3 KiB
TypeScript
88 lines
4.3 KiB
TypeScript
/**
|
|
* backups/backup-script.ts — pure builder for the ONE backup session-container
|
|
* script. No I/O, so it is unit-testable directly.
|
|
*
|
|
* The whole backup runs in a single helper container: it writes the restore
|
|
* metadata (and any small stack files) into an in-container /metadata directory,
|
|
* then runs `restic backup /volumes /metadata`. There is no throwaway metadata
|
|
* volume and no mid-run Docker interaction — one container, one restic call.
|
|
*
|
|
* The script does NOT use `set -e` around the restic step, and it prints restic's
|
|
* real exit code via the shared exit marker (see ./restic-script), so a partial
|
|
* backup (restic exit 3) is reported as a warning rather than a hard failure.
|
|
*/
|
|
import { shellQuote, finishScript } from './restic-script';
|
|
|
|
/** A small file to materialise inside the container before the backup runs
|
|
* (metadata.json, and for stacks the compose/.env files). `path` is relative to
|
|
* /metadata; `contentBase64` is the base64 of the file bytes. */
|
|
export interface MetadataFile {
|
|
path: string;
|
|
contentBase64: string;
|
|
}
|
|
|
|
/**
|
|
* Build the backup session script.
|
|
*
|
|
* The metadata files (metadata.json, and for stacks the compose/.env and the
|
|
* whole stackfiles/ tree) are NOT written by this script — they are streamed into
|
|
* the container's /metadata directory via the Docker put-archive API BEFORE the
|
|
* container starts (see restic.ts runInHelper). Embedding their base64 inline in
|
|
* the Cmd used to blow the kernel ARG_MAX for large stack files ("argument list
|
|
* too long"); put-archive has no such limit.
|
|
*
|
|
* So the script only:
|
|
* 1. ensures /metadata exists (put-archive already created it, but be defensive
|
|
* for the no-files case), and
|
|
* 2. runs `restic backup /volumes/ /metadata/ ...` with the given args.
|
|
* The restic step's exit code is captured via the marker (finishScript), so the
|
|
* caller reads the real code and never mistakes a partial backup for a failure.
|
|
*
|
|
* @param resticArgs the full restic argv (starting with 'backup') — already
|
|
* tag/exclude/flag-assembled by the caller.
|
|
*/
|
|
export function buildBackupScript(resticArgs: string[]): string {
|
|
// restic runs backgrounded so the SIGINT-forwarding trap can reach it on cancel
|
|
// (SIGINT lets restic release its repo lock; a SIGKILL orphans it and hangs the
|
|
// next backup on --retry-lock). The kill-0 re-wait loop only fires when a signal
|
|
// interrupted the first `wait` early; a normal exit skips it, keeping restic's
|
|
// real code (0/3) for the marker.
|
|
const restic = `restic ${resticArgs.map(shellQuote).join(' ')}`;
|
|
const step = `${restic} & __rpid=$!; trap 'kill -INT $__rpid 2>/dev/null' INT TERM; wait $__rpid; __rc=$?; while kill -0 $__rpid 2>/dev/null; do wait $__rpid; __rc=$?; done; ( exit $__rc )`;
|
|
return `mkdir -p /metadata; set +e; ${finishScript(step)}`;
|
|
}
|
|
|
|
/**
|
|
* Build the restic `backup` argv. Volumes are mounted read-only under /volumes
|
|
* and metadata under /metadata, so both paths are backed up. The swap artifacts
|
|
* are always excluded so a backup taken while a restore was interrupted never
|
|
* captures the transient staging dirs.
|
|
*
|
|
* When the target has NO volumes/binds (`hasVolumes: false`) we back up ONLY
|
|
* /metadata — a config-only snapshot. Passing `/volumes/` in that case would make
|
|
* restic exit 3 ("path does not exist") since no volume is mounted; omitting it
|
|
* gives a clean exit 0 metadata-only snapshot.
|
|
*/
|
|
export function buildBackupArgs(input: {
|
|
host: string;
|
|
tags: string[];
|
|
hasVolumes: boolean;
|
|
excludePatterns?: string[];
|
|
excludeCaches?: boolean;
|
|
compression?: string;
|
|
limitUpload?: number;
|
|
limitDownload?: number;
|
|
swapArtifacts: readonly string[];
|
|
}): string[] {
|
|
const paths = input.hasVolumes ? ['/volumes/', '/metadata/'] : ['/metadata/'];
|
|
const args = ['backup', '--json', '--retry-lock', '5m', '--host', input.host, ...paths];
|
|
for (const t of input.tags) args.push('--tag', t);
|
|
for (const a of input.swapArtifacts) args.push('--exclude', a);
|
|
for (const p of input.excludePatterns ?? []) if (p.trim()) args.push('--exclude', p.trim());
|
|
if (input.excludeCaches !== false) args.push('--exclude-caches');
|
|
if (input.compression) args.push('--compression', input.compression);
|
|
if (input.limitUpload) args.push('--limit-upload', String(input.limitUpload));
|
|
if (input.limitDownload) args.push('--limit-download', String(input.limitDownload));
|
|
return args;
|
|
}
|