@leera.io/qa-runner 1.0.0

package/dist/src/appium/server.js

@@ -0,0 +1,237 @@
+import { spawn } from 'node:child_process';
+import { closeSync, mkdirSync, openSync, readSync, statSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { bundledDrivers, resolvePackage } from './drivers.js';
+import { seedAppiumHome } from './home.js';
+/** The Appium package bundled with the runner, or null when optional dependencies were omitted. */
+export function bundledAppium() {
+    return resolvePackage('appium');
+}
+/**
+ * The argv that starts Appium bound to loopback. Never passes `--allow-insecure` or
+ * `--relaxed-security`: sessions cannot run shell commands or other insecure features.
+ */
+export function appiumServerArgv(options) {
+    if (!Number.isInteger(options.port) || options.port <= 0 || options.port > 65_535)
+        throw new Error(`invalid port ${options.port}`);
+    return [
+        options.node,
+        join(options.appiumDir, 'index.js'),
+        'server',
+        '--address',
+        '127.0.0.1',
+        '--port',
+        String(options.port),
+        '--base-path',
+        '/',
+        '--use-drivers',
+        options.drivers.join(','),
+        '--log',
+        options.logFile,
+        '--log-level',
+        'error:debug',
+        '--log-no-colors',
+        '--log-timestamp',
+        '--local-timezone',
+    ];
+}
+/** A free TCP port on loopback, chosen by the OS. */
+export function freePort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once('error', reject);
+        server.listen({ port: 0, host: '127.0.0.1' }, () => {
+            const address = server.address();
+            const port = typeof address === 'object' && address ? address.port : 0;
+            server.close(() => resolve(port));
+        });
+    });
+}
+function portFree(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once('error', () => resolve(false));
+        server.listen({ port, host: '127.0.0.1', exclusive: true }, () => server.close(() => resolve(true)));
+    });
+}
+/**
+ * Hands out ports from a fixed range, one holder at a time (UiAutomator2 `systemPort`
+ * 8200–8299, `mjpegServerPort` 7810–7909), skipping ports something else listens on.
+ */
+export class PortRange {
+    min;
+    max;
+    isFree;
+    used = new Set();
+    constructor(min, max, isFree = portFree) {
+        this.min = min;
+        this.max = max;
+        this.isFree = isFree;
+    }
+    async take() {
+        for (let port = this.min; port <= this.max; port += 1) {
+            if (this.used.has(port))
+                continue;
+            this.used.add(port);
+            if (await this.isFree(port))
+                return port;
+            this.used.delete(port);
+        }
+        throw new Error(`no free port between ${this.min} and ${this.max}`);
+    }
+    release(port) {
+        this.used.delete(port);
+    }
+}
+export const SYSTEM_PORTS = new PortRange(8200, 8299);
+export const MJPEG_PORTS = new PortRange(7810, 7909);
+export class AppiumUnavailable extends Error {
+}
+/**
+ * One Appium server per runner process: started lazily on the first non-web job, bound to
+ * 127.0.0.1 on a free port, health-checked via `/status`, restarted when it has died.
+ */
+export class AppiumServer {
+    options;
+    child = null;
+    starting = null;
+    port = 0;
+    exited = null;
+    logFile;
+    constructor(options) {
+        this.options = options;
+        this.logFile = options.logFile ?? join(options.home, 'appium.log');
+    }
+    get url() {
+        return this.child && !this.exited ? `http://127.0.0.1:${this.port}` : null;
+    }
+    /** Starts the server when needed and returns its base URL. */
+    async ensure() {
+        if (this.child && !this.exited && (await this.healthy()))
+            return `http://127.0.0.1:${this.port}`;
+        this.starting ??= this.start().finally(() => {
+            this.starting = null;
+        });
+        return this.starting;
+    }
+    async start() {
+        await this.stop();
+        const appium = bundledAppium();
+        if (!appium) {
+            throw new AppiumUnavailable('Appium is not installed with this runner: reinstall it with its optional dependencies (npm install without --omit=optional)');
+        }
+        const drivers = bundledDrivers();
+        if (drivers.length === 0)
+            throw new AppiumUnavailable('no Appium drivers are installed with this runner');
+        seedAppiumHome(this.options.home, appium, drivers);
+        mkdirSync(this.options.home, { recursive: true, mode: 0o700 });
+        this.port = await freePort();
+        const argv = appiumServerArgv({
+            node: this.options.nodePath ?? process.execPath,
+            appiumDir: appium.dir,
+            port: this.port,
+            drivers: drivers.map((d) => d.name),
+            logFile: this.logFile,
+        });
+        this.exited = null;
+        const child = spawn(argv[0], argv.slice(1), {
+            cwd: this.options.home,
+            env: { ...(this.options.env ?? process.env), APPIUM_HOME: this.options.home },
+            stdio: ['ignore', 'ignore', 'pipe'],
+            windowsHide: true,
+        });
+        let stderr = '';
+        child.stderr?.on('data', (chunk) => {
+            stderr = (stderr + chunk.toString('utf8')).slice(-4_000);
+        });
+        child.once('exit', (code, signal) => {
+            this.exited = `Appium exited (${signal ?? `code ${code}`})${stderr.trim() ? `: ${stderr.trim().split('\n').slice(-3).join(' ')}` : ''}`;
+        });
+        child.once('error', (error) => {
+            this.exited = `Appium could not start: ${error.message}`;
+        });
+        this.child = child;
+        // Never leave Appium behind when the runner exits without stopping it.
+        const killOnExit = () => child.kill('SIGTERM');
+        process.once('exit', killOnExit);
+        child.once('exit', () => process.removeListener('exit', killOnExit));
+        const deadline = Date.now() + (this.options.startTimeoutMs ?? 60_000);
+        for (;;) {
+            if (this.exited)
+                throw new Error(`${this.exited}; see ${this.logFile}`);
+            if (await this.healthy())
+                return `http://127.0.0.1:${this.port}`;
+            if (Date.now() > deadline) {
+                await this.stop();
+                throw new Error(`Appium did not answer /status within ${Math.round((this.options.startTimeoutMs ?? 60_000) / 1000)} s; see ${this.logFile}`);
+            }
+            await sleep(250);
+        }
+    }
+    async healthy() {
+        if (!this.port)
+            return false;
+        try {
+            const response = await fetch(`http://127.0.0.1:${this.port}/status`, { signal: AbortSignal.timeout(2_000) });
+            if (!response.ok)
+                return false;
+            const body = (await response.json());
+            return body.value?.ready !== false;
+        }
+        catch {
+            return false;
+        }
+    }
+    async stop() {
+        const child = this.child;
+        this.child = null;
+        if (!child || child.exitCode !== null || this.exited)
+            return;
+        const done = new Promise((resolve) => child.once('exit', () => resolve()));
+        child.kill('SIGTERM');
+        const timer = sleep(5_000).then(() => {
+            if (child.exitCode === null)
+                child.kill('SIGKILL');
+        });
+        await Promise.race([done, timer]);
+    }
+    /** The log file's current size: pass it to `logSince` to get what was logged afterwards. */
+    logOffset() {
+        try {
+            return statSync(this.logFile).size;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /** What Appium logged since `offset` (up to `end` when given), the last `maxBytes` of it (attached to failed steps). */
+    logSince(offset, maxBytes = 16_000, end) {
+        return readLogSlice(this.logFile, offset, maxBytes, end);
+    }
+}
+export function readLogSlice(file, offset, maxBytes, end) {
+    let fd = null;
+    try {
+        const size = Math.min(statSync(file).size, end ?? Number.POSITIVE_INFINITY);
+        const start = Math.max(offset, size - maxBytes, 0);
+        const length = size - start;
+        if (length <= 0)
+            return '';
+        fd = openSync(file, 'r');
+        const buffer = Buffer.alloc(length);
+        readSync(fd, buffer, 0, length, start);
+        let text = buffer.toString('utf8');
+        if (start > offset)
+            text = text.slice(text.indexOf('\n') + 1);
+        return text;
+    }
+    catch {
+        return '';
+    }
+    finally {
+        if (fd !== null)
+            closeSync(fd);
+    }
+}

package/dist/src/builds/cache.js

@@ -0,0 +1,133 @@
+import { createHash } from 'node:crypto';
+import { createReadStream, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+/** 10 GB of builds are kept by default; least recently used ones go first. */
+export const DEFAULT_CACHE_BYTES = 10 * 1024 * 1024 * 1024;
+export const SHA256_RE = /^[0-9a-f]{64}$/;
+/** Keeps a file name usable on every OS and inside the cache directory. */
+export function safeFileName(name) {
+    const base = basename(name.replace(/\\/g, '/'))
+        .replace(/[^A-Za-z0-9._-]+/g, '_')
+        .replace(/^\.+/, '')
+        .slice(0, 120);
+    return base || 'build';
+}
+export function sha256File(path) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash('sha256');
+        createReadStream(path)
+            .on('data', (chunk) => hash.update(chunk))
+            .on('error', reject)
+            .on('end', () => resolve(hash.digest('hex')));
+    });
+}
+/**
+ * Builds on disk under `cache/builds/<sha256>/<file name>` with a `meta.json`. Entries in
+ * use by a running job are pinned and never evicted.
+ */
+export class BuildCache {
+    dir;
+    maxBytes;
+    now;
+    pins = new Map();
+    constructor(dir, maxBytes = DEFAULT_CACHE_BYTES, now = Date.now) {
+        this.dir = dir;
+        this.maxBytes = maxBytes;
+        this.now = now;
+    }
+    entryDir(sha256) {
+        if (!SHA256_RE.test(sha256))
+            throw new Error(`'${sha256}' is not a sha256 digest`);
+        return join(this.dir, sha256);
+    }
+    readMeta(sha256) {
+        try {
+            const meta = JSON.parse(readFileSync(join(this.entryDir(sha256), 'meta.json'), 'utf8'));
+            return meta.sha256 === sha256 ? meta : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    writeMeta(entry) {
+        writeFileSync(join(this.entryDir(entry.sha256), 'meta.json'), `${JSON.stringify(entry)}\n`, { mode: 0o600 });
+    }
+    /** The cached file, or null. A file whose size no longer matches is dropped. */
+    get(sha256) {
+        const meta = this.readMeta(sha256);
+        if (!meta)
+            return null;
+        const file = join(this.entryDir(sha256), meta.file_name);
+        try {
+            if (statSync(file).size !== meta.size_bytes)
+                throw new Error('size changed');
+        }
+        catch {
+            this.remove(sha256);
+            return null;
+        }
+        this.writeMeta({ ...meta, last_used: this.now() });
+        return file;
+    }
+    /** A temp path inside the cache directory (same filesystem, so `put` is a rename). */
+    tempPath(label) {
+        mkdirSync(join(this.dir, '.tmp'), { recursive: true, mode: 0o700 });
+        return join(this.dir, '.tmp', `${safeFileName(label)}.${process.pid}.${this.now()}.part`);
+    }
+    /** Moves a verified file into the cache and returns its final path. */
+    put(sha256, fileName, source) {
+        const dir = this.entryDir(sha256);
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const name = safeFileName(fileName);
+        const target = join(dir, name);
+        renameSync(source, target);
+        this.writeMeta({ sha256, file_name: name, size_bytes: statSync(target).size, last_used: this.now() });
+        return target;
+    }
+    remove(sha256) {
+        rmSync(this.entryDir(sha256), { recursive: true, force: true });
+    }
+    list() {
+        if (!existsSync(this.dir))
+            return [];
+        const entries = [];
+        for (const name of readdirSync(this.dir)) {
+            if (!SHA256_RE.test(name))
+                continue;
+            const meta = this.readMeta(name);
+            if (meta)
+                entries.push(meta);
+        }
+        return entries;
+    }
+    pin(sha256) {
+        this.pins.set(sha256, (this.pins.get(sha256) ?? 0) + 1);
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            const left = (this.pins.get(sha256) ?? 1) - 1;
+            if (left <= 0)
+                this.pins.delete(sha256);
+            else
+                this.pins.set(sha256, left);
+        };
+    }
+    /** Evicts least recently used, unpinned entries until the cache fits `maxBytes`. Returns the evicted digests. */
+    prune() {
+        const entries = this.list().sort((a, b) => a.last_used - b.last_used);
+        let total = entries.reduce((sum, e) => sum + e.size_bytes, 0);
+        const evicted = [];
+        for (const entry of entries) {
+            if (total <= this.maxBytes)
+                break;
+            if (this.pins.has(entry.sha256))
+                continue;
+            this.remove(entry.sha256);
+            total -= entry.size_bytes;
+            evicted.push(entry.sha256);
+        }
+        return evicted;
+    }
+}

package/dist/src/builds/cleanup.js

@@ -0,0 +1,208 @@
+import { spawnSync } from 'node:child_process';
+import { realpathSync, rmSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+/**
+ * Ending the processes that hold a runner-created folder and removing it, without ever failing
+ * the job. On Windows a folder cannot be deleted while a process runs an executable from it,
+ * has it on its command line (Electron helpers get `--user-data-dir` and friends) or is scanned
+ * by antivirus; the delete then fails with EBUSY or EPERM for a while.
+ */
+/** Bounded wait for processes to go away after they were killed. */
+export const PROCESS_WAIT_MS = 15_000;
+/** Bounded time spent retrying the delete itself. */
+export const REMOVE_BUDGET_MS = 10_000;
+/** `taskkill` argv that ends a Windows process and its children. */
+export function taskkillArgv(pid) {
+    return ['/pid', String(pid), '/T', '/F'];
+}
+/**
+ * PowerShell argv listing `pid<TAB>name<TAB>path` of every process whose executable lies under
+ * one of the folders in QA_APP_DIRS (`|`-separated; `|` cannot occur in a Windows path) or, with
+ * QA_MATCH_COMMAND_LINE=1, whose command line names one of them. The folders travel in the
+ * environment, never spliced into the command. The query itself and QA_EXCLUDE_PID are skipped.
+ */
+export function windowsProcessesUnderArgv() {
+    return [
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        "$dirs = @($env:QA_APP_DIRS -split '\\|' | Where-Object { $_ } | ForEach-Object { [IO.Path]::GetFullPath($_).TrimEnd('\\') } | Where-Object { $_.Length -gt 3 }); " +
+            "$cmd = $env:QA_MATCH_COMMAND_LINE -eq '1'; " +
+            '$skip = @($PID, [int]("0" + $env:QA_EXCLUDE_PID)); ' +
+            'Get-CimInstance Win32_Process | Where-Object { ' +
+            '$p = $_; if ($skip -contains $p.ProcessId) { return $false }; ' +
+            "@($dirs | Where-Object { ($p.ExecutablePath -and $p.ExecutablePath.StartsWith($_ + '\\', [StringComparison]::OrdinalIgnoreCase)) -or " +
+            '($cmd -and $p.CommandLine -and $p.CommandLine.IndexOf($_, [StringComparison]::OrdinalIgnoreCase) -ge 0) }).Count -gt 0 } | ' +
+            'ForEach-Object { "$($_.ProcessId)`t$($_.Name)`t$($_.ExecutablePath)" }',
+    ];
+}
+/** Parses the output of `windowsProcessesUnderArgv`. */
+export function parseWindowsProcesses(stdout) {
+    const out = [];
+    for (const line of stdout.split(/\r?\n/)) {
+        const [pid, name, path] = line.trim().split('\t');
+        const id = Number(pid);
+        if (Number.isInteger(id) && id > 0 && name)
+            out.push({ pid: id, name, path: path ?? '' });
+    }
+    return out;
+}
+/**
+ * The spellings a folder may appear under: as given, absolute, and with 8.3 short names expanded
+ * (the hosted runner's temp dir is `C:\Users\RUNNER~1\...`, while processes report
+ * `C:\Users\runneradmin\...`, so a prefix match on one spelling alone finds nothing).
+ */
+export function dirSpellings(dir, realpath = (p) => realpathSync.native(p)) {
+    const out = [dir, resolve(dir)];
+    try {
+        out.push(realpath(dir));
+    }
+    catch {
+        // Already gone, or not accessible: the given spellings are all there is.
+    }
+    return [...new Set(out.filter(Boolean))];
+}
+/** Processes running from (or, with `commandLine`, naming) `dir`. Windows only; empty elsewhere or when the query fails. */
+export function windowsProcessesUnder(dir, platform = process.platform, options = {}) {
+    if (platform !== 'win32' || !dir)
+        return [];
+    const result = spawnSync('powershell.exe', windowsProcessesUnderArgv(), {
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            QA_APP_DIRS: dirSpellings(dir).join('|'),
+            QA_MATCH_COMMAND_LINE: options.commandLine ? '1' : '0',
+            QA_EXCLUDE_PID: String(process.pid),
+        },
+        windowsHide: true,
+        timeout: 30_000,
+    });
+    return result.status === 0 ? parseWindowsProcesses(result.stdout ?? '') : [];
+}
+function killTreeWindows(pid) {
+    spawnSync('taskkill', taskkillArgv(pid), { stdio: 'ignore', windowsHide: true, timeout: 15_000 });
+}
+/**
+ * Windows: ends every process still running from the folder and waits (bounded) until none is
+ * left. `taskkill /T` only reaches children of a live parent; once Electron's main process has
+ * quit, helpers such as crashpad_handler are orphans that keep the folder's files open. Returns
+ * what had to be killed and what was still running at the deadline.
+ */
+export async function endWindowsProcessesUnder(dir, options = {}) {
+    if ((options.platform ?? process.platform) !== 'win32')
+        return { killed: [], remaining: [] };
+    const list = options.list ?? ((d) => windowsProcessesUnder(d, 'win32', { commandLine: options.commandLine }));
+    const kill = options.kill ?? killTreeWindows;
+    const sleep = options.sleep ?? delay;
+    const now = options.now ?? Date.now;
+    const deadline = now() + (options.timeoutMs ?? PROCESS_WAIT_MS);
+    const killed = new Map();
+    for (;;) {
+        const running = list(dir);
+        if (running.length === 0)
+            return { killed: [...killed.values()], remaining: [] };
+        if (now() > deadline)
+            return { killed: [...killed.values()], remaining: running };
+        for (const proc of running) {
+            killed.set(proc.pid, proc);
+            kill(proc.pid);
+        }
+        await sleep(500);
+    }
+}
+/** Errors a delete may recover from after a moment (a handle closing, an antivirus scan ending). */
+export function isRetryableRemoveError(error) {
+    const code = error?.code;
+    return code === 'EBUSY' || code === 'EPERM' || code === 'ENOTEMPTY' || code === 'EACCES' || code === 'EMFILE';
+}
+/**
+ * Removes `dir`, retrying retryable errors with backoff (100 ms doubling, capped at 2 s) until
+ * `budgetMs` has passed. Never throws; returns the last error when the folder could not go.
+ */
+export async function removeDirWithRetries(dir, options = {}) {
+    const remove = options.remove ?? ((d) => rmSync(d, { recursive: true, force: true }));
+    const sleep = options.sleep ?? delay;
+    const now = options.now ?? Date.now;
+    const deadline = now() + (options.budgetMs ?? REMOVE_BUDGET_MS);
+    let wait = 100;
+    for (let attempts = 1;; attempts++) {
+        try {
+            remove(dir);
+            return { removed: true, attempts };
+        }
+        catch (error) {
+            const left = deadline - now();
+            if (!isRetryableRemoveError(error) || left <= 0)
+                return { removed: false, attempts, error };
+            await sleep(Math.min(wait, left));
+            wait = Math.min(wait * 2, 2_000);
+        }
+    }
+}
+/**
+ * Cleans up a folder the runner created (an unpacked build, a job's scratch folder). On Windows:
+ * ends every process whose executable or command line references it (tree kill), waits up to
+ * 15 s for them to go, then deletes with retries for up to 10 s. When the folder still cannot be
+ * deleted, logs a warning naming it and the processes left, and returns: a job's result never
+ * depends on temp cleanup. Never throws.
+ */
+export async function cleanupRunnerDir(dir, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const commandLine = options.commandLine ?? true;
+    const query = options.list ?? ((d) => windowsProcessesUnder(d, 'win32', { commandLine }));
+    // A failing process query must not stop the delete from being tried.
+    const list = (d) => safeList(query, d);
+    let killed = [];
+    let remaining = [];
+    try {
+        if (platform === 'win32')
+            ({ killed, remaining } = await endWindowsProcessesUnder(dir, { ...options, platform, commandLine, list }));
+        if (killed.length > 0)
+            options.log?.warn('ended processes still using a runner folder', { dir, processes: killed.map(describe) });
+        const outcome = await removeDirWithRetries(dir, { budgetMs: options.removeBudgetMs, remove: options.remove, sleep: options.sleep, now: options.now });
+        if (outcome.removed)
+            return { removed: true, killed, remaining };
+        if (platform === 'win32' && remaining.length === 0) {
+            // Something may have started using the folder while the delete was retried: name it.
+            remaining = list(dir);
+        }
+        const error = firstLineOf(outcome.error);
+        options.log?.warn('could not remove a runner folder; leaving it behind', { dir, error, processes: remaining.map(describe) });
+        return { removed: false, killed, remaining, error };
+    }
+    catch (unexpected) {
+        const error = firstLineOf(unexpected);
+        options.log?.warn('could not remove a runner folder; leaving it behind', { dir, error, processes: remaining.map(describe) });
+        return { removed: false, killed, remaining, error };
+    }
+}
+function safeList(list, dir) {
+    try {
+        return list(dir);
+    }
+    catch {
+        return [];
+    }
+}
+function describe(proc) {
+    return `${proc.pid} ${proc.name}${proc.path ? ` (${proc.path})` : ''}`;
+}
+function firstLineOf(error) {
+    return (error instanceof Error ? error.message : String(error)).split('\n')[0] ?? '';
+}
+/** Removes an unpacked build's private folder through `cleanupRunnerDir` (never throws). */
+export async function disposeUnpacked(unpacked, log) {
+    if (!unpacked)
+        return;
+    if (unpacked.tempDir) {
+        await cleanupRunnerDir(unpacked.tempDir, { log });
+        return;
+    }
+    try {
+        unpacked.cleanup();
+    }
+    catch (error) {
+        log?.warn('could not clean up the unpacked build; leaving it behind', { error: firstLineOf(error) });
+    }
+}

package/dist/src/builds/download.js

@@ -0,0 +1,64 @@
+import { createHash } from 'node:crypto';
+import { rmSync } from 'node:fs';
+import { writeResponseBody } from '../download.js';
+import { SHA256_RE } from './cache.js';
+export class BuildIntegrityError extends Error {
+}
+/**
+ * Returns a local copy of a build, downloading it into the digest-keyed cache on a miss.
+ * The download is hashed while streaming and must match both the job's and the server's
+ * digest and size before it enters the cache.
+ */
+export async function obtainBuild(options) {
+    const { cache, build } = options;
+    const expected = build.sha256.toLowerCase();
+    if (!SHA256_RE.test(expected))
+        throw new BuildIntegrityError(`build ${build.id} has no valid sha256`);
+    const release = cache.pin(expected);
+    try {
+        const cached = cache.get(expected);
+        if (cached)
+            return { path: cached, sha256: expected, fromCache: true, release };
+        const info = await options.getUrl();
+        if (info.sha256.toLowerCase() !== expected) {
+            throw new BuildIntegrityError(`the server offered build ${build.id} with digest ${info.sha256}, not ${expected}`);
+        }
+        const url = new URL(info.url);
+        if (url.protocol !== 'https:' && url.protocol !== 'http:')
+            throw new Error(`refusing to download a build from ${url.protocol} URL`);
+        const temp = cache.tempPath(info.file_name);
+        try {
+            const response = await (options.fetchImpl ?? fetch)(url, {
+                redirect: 'follow',
+                signal: AbortSignal.timeout(options.timeoutMs ?? 30 * 60_000),
+            });
+            if (!response.ok || !response.body)
+                throw new Error(`the build download failed with HTTP ${response.status}`);
+            const hash = createHash('sha256');
+            let received = 0;
+            const limit = info.size_bytes;
+            await writeResponseBody(response.body, temp, (chunk) => {
+                received += chunk.length;
+                if (received > limit)
+                    throw new BuildIntegrityError(`the build download is larger than the expected ${limit} bytes`);
+                hash.update(chunk);
+                options.onProgress?.(received, limit);
+            });
+            if (received !== limit)
+                throw new BuildIntegrityError(`the build download has ${received} bytes, expected ${limit}`);
+            const digest = hash.digest('hex');
+            if (digest !== expected)
+                throw new BuildIntegrityError(`the downloaded build's sha256 ${digest} does not match ${expected}`);
+            const path = cache.put(expected, info.file_name || build.file_name, temp);
+            cache.prune();
+            return { path, sha256: expected, fromCache: false, release };
+        }
+        finally {
+            rmSync(temp, { force: true });
+        }
+    }
+    catch (error) {
+        release();
+        throw error;
+    }
+}