withruntime 0.11.0 → 0.11.2

package/dist/sandbox.js

@@ -1,10 +1,13 @@
-import { KEEP_ALIVE_MARGIN_SECONDS, STREAMED_EXEC_TIMEOUT_MS, WAIT_FOR_TIMEOUT_SECONDS, } from "./api-defaults.js";
-import { CommandError, ConnectionError, NotFoundError, RuntimeError } from "./errors.js";
-import { Page } from "./page.js";
+import { STREAMED_EXEC_TIMEOUT_MS } from "./api-defaults.js";
+import { CommandError, ConnectionError, DELIBERATE, errorFor, NotFoundError, RateLimitError, RuntimeError, ServiceUnavailableError, } from "./errors.js";
 import { sandboxWatches, watchDirectory, } from "./products/watch.js";
 import { Transport } from "./transport.js";
 import { sandboxFactories } from "./products/index.js";
 import { Tunnel } from "./tunnel.js";
+import { pause } from "./wait.js";
+import { Machine, machinePage, requestOnly } from "./machine.js";
+/** Sandboxes, as a product of the machine engine (machine.ts). */
+export const SANDBOXES = { plural: "sandboxes", noun: "Sandbox" };
 const CHUNK = 1_048_576;
 /** Chunks of a large write in flight at once. Each chunk's reply waits on the
  * API and the guest, and the link idles while every chunk in flight waits:
@@ -56,15 +59,6 @@ function requestScope(options) {
     };
     return { request, check, wait };
 }
-/** DELETE /v1/sandboxes/{id}, for `sandbox.delete()` and
- * `runtime.sandboxes.delete(id)`. */
-export function deleteSandbox(t, id, options = {}) {
-    return t.json({
-        method: "DELETE",
-        path: `/v1/sandboxes/${enc(id)}`,
-        ...options,
-    });
-}
 /* Web APIs only, so the sandbox's commands, processes and files work in a
    browser with a session token (Sandbox.fromSession): no Buffer, no
    node:crypto. */
@@ -94,26 +88,21 @@ function commandBody(command, options) {
     };
 }
 // eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
-export class Sandbox {
-    #info;
-    #keepAlive;
+export class Sandbox extends Machine {
     #t;
     files;
     processes;
     /** Short-lived tokens that let a browser reach this sandbox directly. */
     sessions;
     constructor(transport, info) {
+        super(SANDBOXES, transport, info);
         this.#t = transport;
-        this.#info = info;
         this.files = new Files(transport, info.id);
         this.processes = new Processes(transport, info.id);
         this.sessions = new SandboxSessions(transport, info.id);
         for (const [name, make] of sandboxFactories())
             Object.defineProperty(this, name, { value: make(transport, this), enumerable: false });
     }
-    get id() {
-        return this.#info.id;
-    }
     /** A sandbox reached with a session token instead of an API key, for code in
      * a browser: commands and their streams, processes, files and previews of
      * this one sandbox. Makes no call; `info` holds only the id until
@@ -138,41 +127,6 @@ export class Sandbox {
         });
         return new Sandbox(transport, { id: session.sandboxId });
     }
-    /** The API's latest answer. `start`, the report of an image's start
-     * command, is the create's alone: the API keeps no record of it, so a
-     * later read of this sandbox keeps it here. */
-    #keep(info) {
-        const start = this.#info?.start;
-        this.#info = info.start === undefined && start !== undefined ? { ...info, start } : info;
-    }
-    /** What the API last said about this sandbox. `refresh()` asks again. */
-    get info() {
-        return this.#info;
-    }
-    get state() {
-        return this.#info.state;
-    }
-    async refresh(options = {}) {
-        this.#keep(await this.#t.json({
-            method: "GET",
-            path: `/v1/sandboxes/${enc(this.id)}`,
-            ...options,
-        }));
-        return this;
-    }
-    /** Waits (server-side, no polling) until the sandbox reaches `state`. */
-    async waitFor(state, options = {}) {
-        this.#keep(await this.#t.json({
-            method: "GET",
-            path: `/v1/sandboxes/${enc(this.id)}`,
-            query: {
-                waitFor: state,
-                timeoutSeconds: options.timeoutSeconds ?? WAIT_FOR_TIMEOUT_SECONDS,
-            },
-            ...options,
-        }));
-        return this;
-    }
     /** Runs a command and returns its exit code and output. A string runs under
      * `bash -c`; an array runs without a shell. With onStdout/onStderr the output
      * streams as it happens. A timeout is a result (timedOut: true, the output so
@@ -365,251 +319,6 @@ export class Sandbox {
             throw error;
         }
     }
-    async stop(options = {}) {
-        this.#keepAlive?.();
-        return this.#lifecycle("stop", options);
-    }
-    async pause(options = {}) {
-        return this.#lifecycle("pause", options);
-    }
-    /** Deletes it for good: stops it if it runs or is paused, deletes its disk
-     * and paused memory, revokes its previews and ports, and removes it from
-     * lists. Its snapshots, usage and audit entries stay. Deleting it again
-     * answers the same. */
-    async delete(options = {}) {
-        this.#keepAlive?.();
-        return deleteSandbox(this.#t, this.id, options);
-    }
-    /** Carries on a paused sandbox; `timeoutSeconds` is its new lease. */
-    async wake(options = {}) {
-        const { timeoutSeconds, ...rest } = options;
-        try {
-            return await this.#lifecycle("wake", rest, timeoutSeconds === undefined ? {} : { timeoutSeconds });
-        }
-        catch (error) {
-            // Waking one that is already awake is done, not a mistake. With a new
-            // lease asked for, the refusal stands: it was not given.
-            if (!(error instanceof RuntimeError) || error.code !== "not_paused" || timeoutSeconds)
-                throw error;
-            await this.refresh(pick(rest));
-            if (this.state !== "running" && this.state !== "starting")
-                throw error;
-            return this;
-        }
-    }
-    /** More time before the lease ends (at most an hour ahead of now). */
-    async extend(seconds, options = {}) {
-        return this.#lifecycle("extend", { ...options, wait: false }, { seconds });
-    }
-    /** Changes its name, labels, automatic wake, idle pause or persistence;
-     * fields left out stay as they are. `persistent: true` keeps it running
-     * while credit lasts (paid only). */
-    async update(settings, options = {}) {
-        return this.#lifecycle("update", { ...options, wait: false }, { ...settings });
-    }
-    /** Moves it to another image (id, name, name:tag or name@version), keeping
-     * its id, /workspace (its home: dotfiles, pip --user and npm -g installs),
-     * volumes, environment, name and previews. Its processes restart, and
-     * everything else on its old disk (sudo installs, apt packages, /etc) is
-     * lost, which `keep: "workspace"` says you know; snapshot it first to keep
-     * everything. A running sandbox is paused first. A switch that fails is
-     * undone (`switch_undone`), the sandbox on its old image with nothing lost.
-     * Charged as a wake. */
-    async switchImage(image, options) {
-        const { keep, ...rest } = options;
-        this.#keep(await this.#t.json({
-            method: "POST",
-            path: `/v1/sandboxes/${enc(this.id)}:switch-image`,
-            body: { image, keep },
-            // A pause, two boots and the copy between them.
-            wait: 120,
-            ...pick(rest),
-        }));
-        return this;
-    }
-    /** Gives it more or fewer vCPUs or more or less memory by a restart: its id,
-     * whole disk, volumes, environment, name and previews stay, and its
-     * programs stop, which `restart: true` says you know (snapshot it first to
-     * keep its memory too). A running sandbox is paused, or stopped if it is
-     * persistent, and comes back running at the new size on the same server; a
-     * paused or stopped one is started. Memory bills on the new size from then.
-     * Refused, with nothing changed, when the server has no room
-     * (`no_capacity`), above your quota or the trial's 2 vCPU and 4 GiB, or
-     * while a snapshot or fork of it is being taken. */
-    async resize(size, options) {
-        const { restart, ...rest } = options;
-        this.#keep(await this.#t.json({
-            method: "POST",
-            path: `/v1/sandboxes/${enc(this.id)}:resize`,
-            body: { ...size, restart },
-            // A pause or stop and a cold boot.
-            wait: 120,
-            ...pick(rest),
-        }));
-        return this;
-    }
-    /** Keeps a running sandbox's lease ahead of now, in the background, until
-     * stop() or the returned function ends it: every `everySeconds` (60) it
-     * extends the lease so that `marginSeconds` (600) remain, never more than
-     * the hour ahead the API allows. Running time is billed as it is used, as
-     * for any extension. A paused sandbox is left paused (a request wakes it,
-     * unless autoWake is off); a stopped one ends the loop. It does not keep a
-     * Node or Bun process alive by itself. */
-    keepAlive(options = {}) {
-        this.#keepAlive?.();
-        const every = Math.max(10, options.everySeconds ?? 60) * 1000;
-        const margin = Math.min(3600, Math.max(60, options.marginSeconds ?? KEEP_ALIVE_MARGIN_SECONDS));
-        let ended = false;
-        let timer;
-        const end = () => {
-            ended = true;
-            if (timer)
-                clearTimeout(timer);
-            if (this.#keepAlive === end)
-                this.#keepAlive = undefined;
-        };
-        const tick = async () => {
-            if (ended)
-                return;
-            try {
-                await this.refresh();
-                if (this.state === "stopped" || this.state === "stopping")
-                    return end();
-                if (this.state === "running") {
-                    const left = (Date.parse(this.info.expiresAt) - Date.now()) / 1000;
-                    const need = Math.ceil(margin - left);
-                    if (need >= 1)
-                        await this.extend(Math.min(3600, need));
-                }
-            }
-            catch (error) {
-                options.onError?.(error);
-            }
-            if (ended)
-                return;
-            timer = setTimeout(() => void tick(), every);
-            timer.unref?.();
-        };
-        this.#keepAlive = end;
-        void tick();
-        return end;
-    }
-    /** Days a paused sandbox is kept before deletion (1 to 365). */
-    async setRetention(days, options = {}) {
-        return this.#lifecycle("retention", { ...options, wait: false }, { days });
-    }
-    /** Keeps this sandbox's whole machine (files, memory, running processes) as
-     * a snapshot to start new sandboxes from. A running sandbox is paused for
-     * the moment it takes, then woken; a paused one stays paused. */
-    async snapshot(options = {}) {
-        const { idempotencyKey, signal, timeoutMs, ...body } = options;
-        if (body.mode !== undefined && body.mode !== "memory" && body.mode !== "disk")
-            throw new TypeError("Snapshot mode must be memory or disk.");
-        signal?.throwIfAborted();
-        const until = performance.now() + Math.min(timeoutMs && timeoutMs > 0 ? timeoutMs : 60_000, 60_000);
-        const request = () => {
-            signal?.throwIfAborted();
-            const left = Math.ceil(until - performance.now());
-            if (left <= 0)
-                throw new RuntimeError({
-                    code: "snapshot_timeout",
-                    status: 0,
-                    message: "Snapshot capture ran past its deadline.",
-                });
-            return { ...(signal ? { signal } : {}), timeoutMs: left };
-        };
-        await this.refresh(request());
-        // Straight after a fork or a wake the sandbox is still `resuming`, and
-        // after a pause still `pausing`: wait for where it is going, or a
-        // snapshot of it is refused as not paused (user lane, 23 September 2026).
-        if (this.state === "resuming" || this.state === "starting")
-            await this.waitFor("running", request());
-        else if (this.state === "pausing")
-            await this.waitFor("paused", request());
-        const running = this.state === "running";
-        // Check before entering cleanup: an abort during refresh must not pause or wake.
-        const pauseOptions = running ? request() : undefined;
-        let captured;
-        let primary;
-        let failed = false;
-        try {
-            if (running)
-                await this.pause(pauseOptions);
-            let snapshot = await this.#t.json({
-                method: "POST",
-                path: `/v1/sandboxes/${enc(this.id)}:snapshot`,
-                body,
-                wait: 10,
-                ...(idempotencyKey ? { idempotencyKey } : {}),
-                ...request(),
-            });
-            captured = snapshot;
-            // Prefer: wait is bounded on the server. A capture still in progress
-            // must keep its source paused, or the worker refuses it after we wake.
-            while (snapshot.state === "capturing") {
-                signal?.throwIfAborted();
-                if (performance.now() >= until)
-                    throw new RuntimeError({
-                        code: "snapshot_timeout",
-                        status: 0,
-                        message: "Snapshot capture did not finish within one minute.",
-                        details: { snapshotId: snapshot.id },
-                    });
-                await new Promise((resolve) => setTimeout(resolve, 200));
-                snapshot = await this.#t.json({
-                    method: "GET",
-                    path: `/v1/snapshots/${enc(snapshot.id)}`,
-                    ...request(),
-                });
-            }
-            if (snapshot.state !== "ready")
-                throw new RuntimeError({
-                    code: "snapshot_failed",
-                    status: 409,
-                    message: snapshot.error ?? `Snapshot capture ended in state ${snapshot.state}.`,
-                    details: { snapshotId: snapshot.id },
-                });
-            if (body.mode === "disk" && snapshot.mode !== "disk")
-                throw new RuntimeError({
-                    code: "snapshot_mode_mismatch",
-                    status: 409,
-                    message: "The server did not confirm a disk-only snapshot.",
-                    details: { snapshotId: snapshot.id },
-                });
-            captured = snapshot;
-        }
-        catch (error) {
-            failed = true;
-            primary = error;
-        }
-        if (running) {
-            try {
-                await this.wake();
-            }
-            catch (wakeError) {
-                const recovery = {
-                    ...(captured ? { snapshotId: captured.id } : {}),
-                    sourceSandboxId: this.id,
-                    sourceWakeError: {
-                        ...(wakeError instanceof RuntimeError ? { code: wakeError.code } : {}),
-                        message: wakeError instanceof Error ? wakeError.message : String(wakeError),
-                    },
-                };
-                const reported = failed ? primary : wakeError;
-                if (reported instanceof Error && Object.isExtensible(reported)) {
-                    if (reported instanceof RuntimeError)
-                        Object.assign(reported, { details: { ...reported.details, ...recovery } });
-                    else
-                        Object.assign(reported, recovery);
-                }
-                if (!failed)
-                    throw wakeError;
-            }
-        }
-        if (failed)
-            throw primary;
-        return captured;
-    }
     async fork(options = {}) {
         const { idempotencyKey, signal, timeoutMs, ...body } = options;
         const reply = await this.#t.json({
@@ -617,38 +326,11 @@ export class Sandbox {
             path: `/v1/sandboxes/${enc(this.id)}:fork`,
             body,
             wait: 60,
-            ...pick({
-                ...(idempotencyKey ? { idempotencyKey } : {}),
-                ...(signal ? { signal } : {}),
-                ...(timeoutMs ? { timeoutMs } : {}),
-            }),
+            ...requestOnly({ idempotencyKey, signal, timeoutMs }),
         });
         const sandboxes = reply.sandboxes.map((info) => new Sandbox(this.#t, info));
         return options.count === undefined ? sandboxes[0] : sandboxes;
     }
-    /** Starts a stopped persistent sandbox again from its disk (memory is not kept). */
-    async restart(options = {}) {
-        return this.#lifecycle("restart", options);
-    }
-    async #lifecycle(verb, options, body = {}) {
-        this.#keep(await this.#t.json({
-            method: "POST",
-            path: `/v1/sandboxes/${enc(this.id)}:${verb}`,
-            body,
-            wait: options.wait === false ? 0 : 60,
-            ...pick(options),
-        }));
-        return this;
-    }
-    async [Symbol.asyncDispose]() {
-        this.#keepAlive?.();
-        if (this.#info.state === "stopped")
-            return;
-        await this.stop({ wait: false }).catch(() => undefined);
-    }
-    toJSON() {
-        return this.#info;
-    }
 }
 /** Where a reader of a process's output is, in bytes of stdout and stderr
  * together. Output it did not receive, named by the server or not, becomes a
@@ -660,13 +342,10 @@ class OutputCursor {
         this.cursor = cursor;
     }
     *pass(event) {
+        // As the status the API would have answered it, so a passing failure (a
+        // host restarting) is followed again rather than ending the read.
         if (event.type === "error")
-            throw new RuntimeError({
-                message: event.error.message,
-                code: event.error.code,
-                status: 0,
-                ...(event.error.requestId ? { requestId: event.error.requestId } : {}),
-            });
+            throw errorFor(event.error.status ?? 0, event);
         if (event.type === "truncated")
             this.cursor = Math.max(this.cursor, event.resumeAt);
         if (event.type === "stdout" || event.type === "stderr") {
@@ -697,11 +376,20 @@ function processBytes(encoded) {
         });
     }
 }
-/** A stream cut off by the network rather than refused by Runtime: worth
- * reconnecting to from the cursor. */
+/** A stream cut off by the network, or refused by a failure that passes by
+ * itself (a busy API, a 429, a host restarting), rather than refused for good:
+ * worth reconnecting to from the cursor. */
 function cutOff(error) {
-    return !(error instanceof RuntimeError) || error instanceof ConnectionError;
+    return (!(error instanceof RuntimeError) ||
+        error instanceof ConnectionError ||
+        ((error instanceof RateLimitError || error instanceof ServiceUnavailableError) &&
+            [429, 502, 503, 504].includes(error.status) &&
+            !DELIBERATE.has(error.code)));
 }
+/** How long a follow keeps reconnecting while every attempt fails. A command
+ * runs for hours whether or not anyone reads it; a few minutes of a deploy, a
+ * network blip or a busy API must not end the read of it. */
+const FOLLOW_OUTAGE_MS = 300_000;
 /** A streamed command keeps all its output unless the reader fell more than the
  * process's output buffer behind, which the server marks with a "truncated"
  * event. That event does not say which stream lost bytes, so both flags carry
@@ -709,6 +397,8 @@ function cutOff(error) {
 function truncation(dropped) {
     return { stdoutTruncated: dropped, stderrTruncated: dropped };
 }
+/** A command's request options: its `timeoutMs` is the command's own limit
+ * in the guest, so the call is given a minute more for the answer. */
 function pick(options) {
     return {
         ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
@@ -804,12 +494,19 @@ export class Processes {
     /** Output events from `cursor` until the process exits, across stream slices. */
     async *follow(processId, options = {}) {
         const read = new OutputCursor(options.cursor ?? 0);
-        // Reconnections in a row that brought nothing: a stream that keeps
-        // closing without output or an exit is given up, not followed forever.
+        // Reconnections in a row that closed cleanly with nothing: a stream that
+        // keeps closing without output or an exit is given up, not followed
+        // forever.
         let idle = 0;
+        // Since when every reconnection has failed (a cut, a busy API, a host
+        // restarting). The command runs on regardless, so these are waited out
+        // for FOLLOW_OUTAGE_MS, with backoff, before the follow gives up.
+        let failingSince;
+        let failures = 0;
         for (;;) {
             const before = read.cursor;
             let resumed = false;
+            let failure;
             try {
                 for await (const event of this.t.events({
                     method: "GET",
@@ -831,8 +528,28 @@ export class Processes {
             catch (error) {
                 if (options.signal?.aborted || !cutOff(error))
                     throw error;
+                failure = error;
+            }
+            if (resumed || read.cursor > before) {
+                idle = failures = 0;
+                failingSince = undefined;
+                continue;
+            }
+            if (failure === undefined)
+                idle++;
+            else {
+                failingSince ??= performance.now();
+                if (performance.now() - failingSince >= FOLLOW_OUTAGE_MS)
+                    throw new ConnectionError({
+                        message: `Lost the output stream of process ${processId} for ${FOLLOW_OUTAGE_MS / 60_000} minutes; the command may still be running.`,
+                        code: "connection_error",
+                        status: 0,
+                        hint: `Follow it again: runtime sandbox logs ${this.sandboxId} ${processId} -f`,
+                        details: { sandboxId: this.sandboxId, processId },
+                        cause: failure,
+                    });
+                await pause(Math.min(5000, 50 * 2 ** failures++), options.signal);
             }
-            idle = resumed || read.cursor > before ? 0 : idle + 1;
             if (idle > 3)
                 throw new ConnectionError({
                     message: `The output stream of process ${processId} keeps closing before it ends.`,
@@ -1685,11 +1402,7 @@ export class Files {
         }
     }
 }
+/** One page of `runtime.sandboxes.list()`, and the pages after it. */
 export function sandboxPage(t, body, query, options = {}) {
-    return new Page(body.data.map((info) => new Sandbox(t, info)), body.nextCursor, async (cursor) => sandboxPage(t, await t.json({
-        method: "GET",
-        path: "/v1/sandboxes",
-        query: Object.assign({}, query, { cursor }),
-        ...options,
-    }), query, options));
+    return machinePage(SANDBOXES, t, (transport, info) => new Sandbox(transport, info), body, query, options);
 }

package/dist/tar.d.ts

@@ -1,3 +1,5 @@
+/** One entry's header: the ustar block, after the long-name and long-link
+ * entries it needs. A whole number of 512-byte blocks. */
 export declare function tarHeader(name: string, size: number, mode: number, type: "0" | "5" | "2", link?: string, mtime?: number): Uint8Array;
 export declare function packDirectory(root: string): Promise<Uint8Array>;
 /** Unpacks a gzipped tar that arrives as a stream into `target`, refusing any

package/dist/tar.js

@@ -1,25 +1,35 @@
-import { chmod, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, realpath, rename, rm, symlink, unlink, } from "node:fs/promises";
+import { chmod, copyFile, link as hardLink, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, realpath, rename, rm, symlink, unlink, } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { Readable } from "node:stream";
 import { createGunzip, gzipSync } from "node:zlib";
 import { RuntimeError } from "./errors.js";
-/* A small ustar writer and reader for directory uploads and downloads, so the
-   SDK needs no dependency. Regular files, directories and symbolic links;
-   names up to 255 bytes through the ustar prefix field. */
-export function tarHeader(name, size, mode, type, link = "", mtime = 0) {
-    const block = new Uint8Array(512);
-    const bytes = new TextEncoder().encode(name);
-    let prefix = new Uint8Array();
-    let short = bytes;
-    if (bytes.length > 100) {
-        const split = name.lastIndexOf("/", 155);
-        if (split <= 0 || new TextEncoder().encode(name.slice(split + 1)).length > 100)
-            throw new Error(`Path too long for a tar archive: ${name}`);
-        prefix = new TextEncoder().encode(name.slice(0, split));
-        short = new TextEncoder().encode(name.slice(split + 1));
+/* A small tar writer and reader for directory uploads and downloads, so the
+   SDK needs no dependency. Regular files, directories, symbolic links and,
+   reading, hard links. A name that does not fit the ustar name and prefix
+   fields, or a link target longer than 100 bytes, travels in a GNU long-name
+   or long-link entry, which GNU tar, BusyBox tar and every SDK's reader
+   take; nothing is cut short. */
+const encode = (value) => new TextEncoder().encode(value);
+/** The ustar prefix and name of `name`, split at a slash so that each fits
+ * its field in bytes, or null when no split fits. */
+function ustarName(name) {
+    const bytes = encode(name);
+    if (bytes.length <= 100)
+        return { prefix: new Uint8Array(), short: bytes };
+    for (let split = name.lastIndexOf("/"); split > 0; split = name.lastIndexOf("/", split - 1)) {
+        const prefix = encode(name.slice(0, split));
+        const short = encode(name.slice(split + 1));
+        if (short.length > 100)
+            return null;
+        if (prefix.length <= 155)
+            return { prefix, short };
     }
+    return null;
+}
+function headerBlock(short, prefix, size, mode, type, link, mtime) {
+    const block = new Uint8Array(512);
     const put = (offset, value, length) => {
-        const data = typeof value === "string" ? new TextEncoder().encode(value) : value;
+        const data = typeof value === "string" ? encode(value) : value;
         block.set(data.subarray(0, length), offset);
     };
     const octal = (value, length) => value.toString(8).padStart(length - 1, "0") + "\0";
@@ -40,6 +50,29 @@ export function tarHeader(name, size, mode, type, link = "", mtime = 0) {
     put(148, sum.toString(8).padStart(6, "0") + "\0 ", 8);
     return block;
 }
+/** A GNU long-name ("L") or long-link ("K") entry carrying `value`. */
+function longEntry(type, value) {
+    const size = value.length + 1;
+    const out = new Uint8Array(512 + Math.ceil(size / 512) * 512);
+    out.set(headerBlock(encode("././@LongLink"), new Uint8Array(), size, 0o644, type, new Uint8Array(), 0));
+    out.set(value, 512);
+    return out;
+}
+/** One entry's header: the ustar block, after the long-name and long-link
+ * entries it needs. A whole number of 512-byte blocks. */
+export function tarHeader(name, size, mode, type, link = "", mtime = 0) {
+    const parts = [];
+    let fitted = ustarName(name);
+    if (!fitted) {
+        parts.push(longEntry("L", encode(name)));
+        fitted = { prefix: new Uint8Array(), short: encode(name).subarray(0, 100) };
+    }
+    const target = encode(link);
+    if (target.length > 100)
+        parts.push(longEntry("K", target));
+    parts.push(headerBlock(fitted.short, fitted.prefix, size, mode, type, target, mtime));
+    return parts.length === 1 ? parts[0] : new Uint8Array(Buffer.concat(parts));
+}
 export async function packDirectory(root) {
     const parts = [];
     const base = resolve(root);
@@ -352,8 +385,15 @@ async function unpackEntries(bytes, root, signal) {
             links.push({ destination, link, name });
             await skip();
         }
+        else if (type === "1") {
+            await hardLinkEntry(root, destination, link, name);
+            await skip();
+        }
         else if (type === "0" || type === "\0" || type === "7") {
             await mkdir(dirname(destination), { recursive: true });
+            // A name already unpacked may share its file with a hard link; writing
+            // through it would change the link's copy too.
+            await unlink(destination).catch(() => undefined);
             const file = await open(destination, "w");
             try {
                 for await (const part of bytes.take(size)) {
@@ -378,6 +418,24 @@ async function unpackEntries(bytes, root, signal) {
             await skip();
     }
 }
+/** A second name for a file the archive already carried: tar writes the
+ * first name as a file and every other as a hard link to it. The link names
+ * a plain file unpacked earlier in this archive, or the unpack fails; it
+ * never reaches outside, through a link or ahead. */
+async function hardLinkEntry(root, destination, link, name) {
+    const named = link.replace(/^(\.\/)+/, "");
+    const source = resolve(root, named);
+    if (!named || isAbsolute(named) || source === root || !source.startsWith(root + sep))
+        throw new Error(`Refusing an archive hard link that leads outside the target: ${name} -> ${link}`);
+    await assertPlain(root, source, named);
+    if (!(await lstat(source).catch(() => undefined))?.isFile())
+        throw new Error(`Refusing an archive hard link to a file it does not carry: ${name} -> ${link}`);
+    if (source === destination)
+        return;
+    await mkdir(dirname(destination), { recursive: true });
+    await unlink(destination).catch(() => undefined);
+    await hardLink(source, destination).catch(() => copyFile(source, destination));
+}
 /** Moves what was unpacked in `from` into `to`, merging with what is there
  * and replacing files of the same name, never through a link in `to`. */
 async function merge(from, to, root, signal) {