endia 0.0.0-stage → 0.0.2

package/dist/errors.d.ts

@@ -0,0 +1,81 @@
+import type { ApiError } from "./contract/common.js";
+import type { MachineSummary } from "./contract/machines.js";
+import type { Operation } from "./contract/operations.js";
+/**
+ * The service answered and refused: a request it would not carry out, or an operation it started that ended without succeeding.
+ * Without this type a caller would match message text; with it, the caller reads `code`, the API's error code, such as `NOT_FOUND`
+ * or `BUILD_FAILED`.
+ */
+export declare class EastIndiaApiError extends Error {
+    /** The HTTP status of the refusal, such as 404; undefined when an operation ended without succeeding. */
+    readonly status: number | undefined;
+    /** The service's error, or null when a refusal came without a readable body. */
+    readonly error: ApiError | null;
+    /** The operation that ended without succeeding; undefined for a refused request. */
+    readonly operation: Operation | undefined;
+    /**
+     * Describes a refusal or an unsuccessful operation.
+     *
+     * @param status - The HTTP status of a refusal; undefined for an operation.
+     * @param error - The service's error, or null when none could be read.
+     * @param operation - The operation that ended without succeeding, for an operation.
+     */
+    constructor(status: number | undefined, error: ApiError | null, operation?: Operation);
+    /** The API's error code, such as `NOT_FOUND`, or undefined when the refusal carried no readable error. */
+    get code(): string | undefined;
+    /** The field at fault, such as `reference` or `services.web.ports[0]`, or undefined when no one field is at fault. */
+    get fieldPath(): string | undefined;
+    /**
+     * Describes an operation that ended without succeeding, from the error the operation records.
+     *
+     * @param operation - The finished operation, in the state `failed`, `cancelled` or `interrupted`.
+     * @returns The error, which carries the operation.
+     */
+    static fromOperation(operation: Operation): EastIndiaApiError;
+    private static describe;
+}
+/**
+ * Why a request got no answer from the service.
+ *
+ * - `unreachable`: nothing answered at the address, or the connection broke before an answer arrived.
+ * - `certificateRefused`: the service refused the client certificate, because another authority issued it, it has expired or it
+ *   was revoked.
+ * - `serverNotTrusted`: the server's certificate does not chain to EastIndia's authority in `ca.pem`, or does not name the address.
+ * - `pipeRefused`: Windows refused to open the service's named pipe for this account.
+ * - `timedOut`: the request had no answer within the client's request time limit.
+ */
+export type ConnectionFailure = "unreachable" | "certificateRefused" | "serverNotTrusted" | "pipeRefused" | "timedOut";
+/**
+ * No answer came from the service. Without this type a caller could not tell a stopped service from a refused certificate, because
+ * Node reports each of them as a socket or TLS error; `failure` says which it was, and `cause` holds Node's own error.
+ */
+export declare class EastIndiaConnectionError extends Error {
+    /** Why no answer came. */
+    readonly failure: ConnectionFailure;
+    /** The address as messages name it: the host and port, or the named pipe's path. */
+    readonly address: string;
+    /**
+     * Describes a request that got no answer.
+     *
+     * @param address - The host and port, or the named pipe's path.
+     * @param failure - Why no answer came.
+     * @param cause - The error Node reported.
+     */
+    constructor(address: string, failure: ConnectionFailure, cause: unknown);
+    private static describe;
+}
+/**
+ * A machine exited or became unhealthy while `FleetsClient.wait` waited for its fleet, as `endia compose up --wait` then exits
+ * with 1. Without this type a caller could not tell a failed machine from a refused request; `machine` is the machine as the wait
+ * last read it.
+ */
+export declare class MachineFailedError extends Error {
+    /** The machine as the wait last read it. */
+    readonly machine: MachineSummary;
+    /**
+     * Describes a machine that ended a wait.
+     *
+     * @param machine - The machine, exited or unhealthy.
+     */
+    constructor(machine: MachineSummary);
+}

package/dist/errors.js

@@ -0,0 +1,108 @@
+/**
+ * The service answered and refused: a request it would not carry out, or an operation it started that ended without succeeding.
+ * Without this type a caller would match message text; with it, the caller reads `code`, the API's error code, such as `NOT_FOUND`
+ * or `BUILD_FAILED`.
+ */
+export class EastIndiaApiError extends Error {
+    /** The HTTP status of the refusal, such as 404; undefined when an operation ended without succeeding. */
+    status;
+    /** The service's error, or null when a refusal came without a readable body. */
+    error;
+    /** The operation that ended without succeeding; undefined for a refused request. */
+    operation;
+    /**
+     * Describes a refusal or an unsuccessful operation.
+     *
+     * @param status - The HTTP status of a refusal; undefined for an operation.
+     * @param error - The service's error, or null when none could be read.
+     * @param operation - The operation that ended without succeeding, for an operation.
+     */
+    constructor(status, error, operation) {
+        super(EastIndiaApiError.describe(status, error, operation));
+        this.name = "EastIndiaApiError";
+        this.status = status;
+        this.error = error;
+        this.operation = operation;
+    }
+    /** The API's error code, such as `NOT_FOUND`, or undefined when the refusal carried no readable error. */
+    get code() {
+        return this.error?.code;
+    }
+    /** The field at fault, such as `reference` or `services.web.ports[0]`, or undefined when no one field is at fault. */
+    get fieldPath() {
+        return this.error?.fieldPath ?? undefined;
+    }
+    /**
+     * Describes an operation that ended without succeeding, from the error the operation records.
+     *
+     * @param operation - The finished operation, in the state `failed`, `cancelled` or `interrupted`.
+     * @returns The error, which carries the operation.
+     */
+    static fromOperation(operation) {
+        return new EastIndiaApiError(undefined, operation.error ?? null, operation);
+    }
+    static describe(status, error, operation) {
+        const subject = operation === undefined ? `The service answered ${String(status)}` : `Operation ${operation.id} (${operation.kind}) ended ${operation.state}`;
+        if (error === null) {
+            return `${subject}.`;
+        }
+        const field = error.fieldPath ? ` [${error.fieldPath}]` : "";
+        return `${subject} (${error.code}): ${error.message}${field}`;
+    }
+}
+/**
+ * No answer came from the service. Without this type a caller could not tell a stopped service from a refused certificate, because
+ * Node reports each of them as a socket or TLS error; `failure` says which it was, and `cause` holds Node's own error.
+ */
+export class EastIndiaConnectionError extends Error {
+    /** Why no answer came. */
+    failure;
+    /** The address as messages name it: the host and port, or the named pipe's path. */
+    address;
+    /**
+     * Describes a request that got no answer.
+     *
+     * @param address - The host and port, or the named pipe's path.
+     * @param failure - Why no answer came.
+     * @param cause - The error Node reported.
+     */
+    constructor(address, failure, cause) {
+        super(EastIndiaConnectionError.describe(address, failure), { cause });
+        this.name = "EastIndiaConnectionError";
+        this.failure = failure;
+        this.address = address;
+    }
+    static describe(address, failure) {
+        switch (failure) {
+            case "certificateRefused":
+                return `The EastIndia service at ${address} refused the client certificate.`;
+            case "serverNotTrusted":
+                return `The server at ${address} did not present a certificate from the EastIndia authority in ca.pem.`;
+            case "pipeRefused":
+                return `Windows refused access to the EastIndia service at ${address}: add your account to the eastindia-users group, then sign out and in again.`;
+            case "timedOut":
+                return `The EastIndia service at ${address} did not answer within the client's request time limit.`;
+            case "unreachable":
+                return `Cannot connect to the EastIndia service at ${address}. Is the service running?`;
+        }
+    }
+}
+/**
+ * A machine exited or became unhealthy while `FleetsClient.wait` waited for its fleet, as `endia compose up --wait` then exits
+ * with 1. Without this type a caller could not tell a failed machine from a refused request; `machine` is the machine as the wait
+ * last read it.
+ */
+export class MachineFailedError extends Error {
+    /** The machine as the wait last read it. */
+    machine;
+    /**
+     * Describes a machine that ended a wait.
+     *
+     * @param machine - The machine, exited or unhealthy.
+     */
+    constructor(machine) {
+        super(`machine ${machine.name} is ${machine.state === "exited" ? `exited (${String(machine.exitCode)})` : "unhealthy"}`);
+        this.name = "MachineFailedError";
+        this.machine = machine;
+    }
+}

package/dist/exec/exec-frame.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The stream a frame carries bytes for; the value is the frame's first byte.
+ */
+export declare const FrameStream: {
+    readonly stdin: 0;
+    readonly stdout: 1;
+    readonly stderr: 2;
+};
+/** One of the three streams a frame can carry. */
+export type FrameStream = (typeof FrameStream)[keyof typeof FrameStream];
+/** One message of an attached exec without a console: which stream the bytes belong to, and the bytes. */
+export interface ExecFrame {
+    readonly stream: FrameStream;
+    readonly payload: Buffer;
+}
+/**
+ * Writes one frame in Docker's multiplexed format, the form in which an attached exec without a console carries its streams over
+ * one WebSocket. The frame is an eight-byte header followed by the payload:
+ *
+ * - byte 0 is the stream: 0 standard input, 1 standard output, 2 standard error;
+ * - bytes 1 to 3 are zero;
+ * - bytes 4 to 7 are the payload's length as a big-endian unsigned integer.
+ *
+ * When the client sends a standard-input frame with an empty payload, the service closes the program's standard input.
+ *
+ * @param stream - The stream the payload belongs to.
+ * @param payload - The bytes.
+ * @returns The header followed by the payload.
+ */
+export declare function encodeFrame(stream: FrameStream, payload: Uint8Array): Buffer;
+/**
+ * Reads one whole WebSocket message as one frame, the reverse of `encodeFrame`.
+ *
+ * @param message - One whole binary message.
+ * @returns The frame; undefined when the message is not exactly one frame with a header naming a known stream, bytes 1 to 3 zero,
+ * and as many payload bytes as the header gives.
+ */
+export declare function decodeFrame(message: Buffer): ExecFrame | undefined;

package/dist/exec/exec-frame.js

@@ -0,0 +1,50 @@
+/**
+ * The stream a frame carries bytes for; the value is the frame's first byte.
+ */
+export const FrameStream = {
+    stdin: 0,
+    stdout: 1,
+    stderr: 2,
+};
+/** The length of a frame's header, in bytes. */
+const HeaderLength = 8;
+/** Where the payload's length starts in the header. */
+const LengthOffset = 4;
+/**
+ * Writes one frame in Docker's multiplexed format, the form in which an attached exec without a console carries its streams over
+ * one WebSocket. The frame is an eight-byte header followed by the payload:
+ *
+ * - byte 0 is the stream: 0 standard input, 1 standard output, 2 standard error;
+ * - bytes 1 to 3 are zero;
+ * - bytes 4 to 7 are the payload's length as a big-endian unsigned integer.
+ *
+ * When the client sends a standard-input frame with an empty payload, the service closes the program's standard input.
+ *
+ * @param stream - The stream the payload belongs to.
+ * @param payload - The bytes.
+ * @returns The header followed by the payload.
+ */
+export function encodeFrame(stream, payload) {
+    const frame = Buffer.alloc(HeaderLength + payload.byteLength);
+    frame[0] = stream;
+    frame.writeUInt32BE(payload.byteLength, LengthOffset);
+    frame.set(payload, HeaderLength);
+    return frame;
+}
+/**
+ * Reads one whole WebSocket message as one frame, the reverse of `encodeFrame`.
+ *
+ * @param message - One whole binary message.
+ * @returns The frame; undefined when the message is not exactly one frame with a header naming a known stream, bytes 1 to 3 zero,
+ * and as many payload bytes as the header gives.
+ */
+export function decodeFrame(message) {
+    if (message.length < HeaderLength || message[1] !== 0 || message[2] !== 0 || message[3] !== 0) {
+        return undefined;
+    }
+    const stream = message[0];
+    if (stream !== FrameStream.stdin && stream !== FrameStream.stdout && stream !== FrameStream.stderr) {
+        return undefined;
+    }
+    return message.readUInt32BE(LengthOffset) === message.length - HeaderLength ? { stream, payload: message.subarray(HeaderLength) } : undefined;
+}

package/dist/exec/exec-session.d.ts

@@ -0,0 +1,64 @@
+import { Readable, Writable } from "node:stream";
+import type { ExecDetail } from "../contract/execs.js";
+/** What a session needs from the exec routes once its WebSocket is open: the exec's state at the end, and its console's size. */
+export interface ExecRoutes {
+    inspect(id: string, signal?: AbortSignal): Promise<ExecDetail>;
+    resize(id: string, rows: number, columns: number, signal?: AbortSignal): Promise<void>;
+}
+/** How an attached exec was created, which decides how its WebSocket messages are read and written. */
+export interface ExecSessionShape {
+    /**
+     * Whether the program has a console. With a console, each WebSocket message carries raw bytes in both directions; without one,
+     * each WebSocket message is one frame.
+     */
+    readonly tty: boolean;
+    /** Whether the program's standard input stays open for what the caller sends. */
+    readonly attachStdin: boolean;
+}
+/**
+ * A program running in a machine with the caller attached: its standard output and standard error as readable streams, its standard
+ * input as a writable stream, and its exit code once it has ended. `ExecsClient.spawn` starts one; `ExecsClient.run` starts one and
+ * collects its output.
+ *
+ * The output streams are fed from the exec's WebSocket. While a stream's reader falls behind, the session stops reading the WebSocket.
+ * The caller must therefore read both streams: an unread stream stops the program's output, and `wait` never resolves. When the
+ * program has ended and its output has been sent, the service closes the WebSocket, both streams end, and `wait` reads the exec's
+ * exit code.
+ */
+export declare class ExecSession {
+    private readonly socket;
+    private readonly routes;
+    private readonly closed;
+    /** The exec ID: 32 lower-case hexadecimal digits. */
+    readonly id: string;
+    /** The program's standard output; with a console, all of its output. */
+    readonly stdout: Readable;
+    /** The program's standard error; with a console it stays empty, because the console carries both. */
+    readonly stderr: Readable;
+    /** The program's standard input when the exec attaches it, otherwise null. Ending it closes the program's standard input. */
+    readonly stdin: Writable | null;
+    /**
+     * Waits until the program has ended and its output has been sent, then reads the exec.
+     *
+     * @param signal - Cancels the read of the exec; the program keeps running.
+     * @returns The exec, with the program's exit code in full, such as 3010; null when Windows restarted before the program ended.
+     * A program that was not found ends with 127, and one that was found but could not start ends with 126 and a `startError`.
+     */
+    wait(signal?: AbortSignal): Promise<ExecDetail>;
+    /**
+     * Changes the size of the program's console.
+     *
+     * @param rows - The number of rows.
+     * @param columns - The number of columns.
+     * @param signal - Cancels the request.
+     * @returns When the service has resized the console.
+     */
+    resize(rows: number, columns: number, signal?: AbortSignal): Promise<void>;
+    /**
+     * Leaves the program running and stops relaying its streams: the WebSocket is closed and both output streams end. As in Docker,
+     * a program keeps running when its caller disconnects.
+     */
+    detach(): void;
+    private relayOutput;
+    private createInput;
+}

package/dist/exec/exec-session.js

@@ -0,0 +1,117 @@
+import { Readable, Writable } from "node:stream";
+import { decodeFrame, encodeFrame, FrameStream } from "./exec-frame.js";
+/**
+ * A program running in a machine with the caller attached: its standard output and standard error as readable streams, its standard
+ * input as a writable stream, and its exit code once it has ended. `ExecsClient.spawn` starts one; `ExecsClient.run` starts one and
+ * collects its output.
+ *
+ * The output streams are fed from the exec's WebSocket. While a stream's reader falls behind, the session stops reading the WebSocket.
+ * The caller must therefore read both streams: an unread stream stops the program's output, and `wait` never resolves. When the
+ * program has ended and its output has been sent, the service closes the WebSocket, both streams end, and `wait` reads the exec's
+ * exit code.
+ */
+export class ExecSession {
+    socket;
+    routes;
+    closed;
+    /** The exec ID: 32 lower-case hexadecimal digits. */
+    id;
+    /** The program's standard output; with a console, all of its output. */
+    stdout;
+    /** The program's standard error; with a console it stays empty, because the console carries both. */
+    stderr;
+    /** The program's standard input when the exec attaches it, otherwise null. Ending it closes the program's standard input. */
+    stdin;
+    /** @internal */
+    constructor(id, socket, shape, routes) {
+        this.id = id;
+        this.socket = socket;
+        this.routes = routes;
+        const resume = () => {
+            socket.resume();
+        };
+        this.stdout = new Readable({ read: resume });
+        this.stderr = new Readable({ read: resume });
+        this.stdin = shape.attachStdin ? this.createInput(shape.tty) : null;
+        this.closed = this.relayOutput(shape.tty);
+    }
+    /**
+     * Waits until the program has ended and its output has been sent, then reads the exec.
+     *
+     * @param signal - Cancels the read of the exec; the program keeps running.
+     * @returns The exec, with the program's exit code in full, such as 3010; null when Windows restarted before the program ended.
+     * A program that was not found ends with 127, and one that was found but could not start ends with 126 and a `startError`.
+     */
+    async wait(signal) {
+        await this.closed;
+        return this.routes.inspect(this.id, signal);
+    }
+    /**
+     * Changes the size of the program's console.
+     *
+     * @param rows - The number of rows.
+     * @param columns - The number of columns.
+     * @param signal - Cancels the request.
+     * @returns When the service has resized the console.
+     */
+    resize(rows, columns, signal) {
+        return this.routes.resize(this.id, rows, columns, signal);
+    }
+    /**
+     * Leaves the program running and stops relaying its streams: the WebSocket is closed and both output streams end. As in Docker,
+     * a program keeps running when its caller disconnects.
+     */
+    detach() {
+        this.socket.close();
+    }
+    // Feeds each message to its stream until the service closes the WebSocket. A message that is not a well-formed frame carries no
+    // stream to feed, so it is skipped, as the eastindia CLI skips it. The promise rejects when the WebSocket fails before the service
+    // closes it.
+    relayOutput(tty) {
+        return new Promise((resolve, reject) => {
+            let failure;
+            this.socket.on("message", (data) => {
+                const frame = tty ? { stream: FrameStream.stdout, payload: data } : decodeFrame(data);
+                if (frame === undefined || frame.stream === FrameStream.stdin) {
+                    return;
+                }
+                const target = frame.stream === FrameStream.stderr ? this.stderr : this.stdout;
+                if (!target.push(frame.payload)) {
+                    this.socket.pause();
+                }
+            });
+            this.socket.once("error", (error) => {
+                failure = error;
+            });
+            this.socket.once("close", () => {
+                this.stdout.push(null);
+                this.stderr.push(null);
+                if (failure === undefined) {
+                    resolve();
+                }
+                else {
+                    this.stdout.destroy(failure);
+                    this.stderr.destroy(failure);
+                    reject(failure);
+                }
+            });
+        });
+    }
+    // Without a console each write goes as one standard-input frame, and the end of the stream as an empty one, which closes the
+    // program's standard input. With a console the bytes go as they are, and the end of the stream sends nothing.
+    createInput(tty) {
+        return new Writable({
+            write: (chunk, _encoding, done) => {
+                this.socket.send(tty ? chunk : encodeFrame(FrameStream.stdin, chunk), { binary: true }, done);
+            },
+            final: (done) => {
+                if (tty) {
+                    done();
+                }
+                else {
+                    this.socket.send(encodeFrame(FrameStream.stdin, Buffer.alloc(0)), { binary: true }, done);
+                }
+            },
+        });
+    }
+}

package/dist/groups/archives.d.ts

@@ -0,0 +1,78 @@
+import type { IncomingMessage } from "node:http";
+import { Readable } from "node:stream";
+import type { PathStat } from "../contract/archives.js";
+/** A path in a machine read as a tar archive: its description, and the archive as it arrives. */
+export interface MachineArchive {
+    readonly stat: PathStat;
+    /** The tar archive; the caller reads it to its end or destroys it. */
+    readonly archive: IncomingMessage;
+}
+/**
+ * The archive routes of `endia cp`, which copy files into and out of a running machine as tar archives. Paths in a machine are
+ * absolute Windows paths, such as `C:\data` or `C:/data`; a relative path is relative to `C:\`.
+ *
+ * `copyIn` and `copyOut` copy between a local path and a machine folder. They place the copy inside an existing folder under the
+ * source's own name, which is one of the placements `docker cp` makes. `stat`, `read`, `write` and `delete` are the single routes,
+ * for a caller that applies the other placements or packs its own archives.
+ */
+export declare class ArchivesClient {
+    private readonly connection;
+    /**
+     * Copies a local file or folder into a folder in the machine, under its own name. A link is copied as a link.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param source - The local file or folder.
+     * @param folder - The machine folder, which must exist.
+     * @param signal - Cancels the request.
+     * @returns When the service has written every file. When a file to be replaced is in use in the machine, the service stops the
+     * copy at that file and refuses it with `FILES_LOCKED`; the files written before it stay written.
+     */
+    copyIn(machine: string, source: string, folder: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Copies a file or folder out of the machine into a local folder, under its own name.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param source - The path in the machine.
+     * @param folder - The local folder, created when it does not exist.
+     * @param signal - Cancels the request.
+     * @returns The source's description. An archive entry whose path would lead outside the local folder is refused.
+     */
+    copyOut(machine: string, source: string, folder: string, signal?: AbortSignal): Promise<PathStat>;
+    /**
+     * Describes a path in the machine: `HEAD /v1/machines/{name}/archive`.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param target - The path in the machine.
+     * @param signal - Cancels the request.
+     * @returns The path's name, size, kind and modification time; null when nothing is at the path.
+     */
+    stat(machine: string, target: string, signal?: AbortSignal): Promise<PathStat | null>;
+    /**
+     * Reads a path in the machine as a tar archive: `GET /v1/machines/{name}/archive`.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param source - The path in the machine; a folder path ending in `\.` asks for the folder's contents without the folder.
+     * @param signal - Ends the request.
+     * @returns The path's description and the archive.
+     */
+    read(machine: string, source: string, signal?: AbortSignal): Promise<MachineArchive>;
+    /**
+     * Extracts a tar archive into a folder in the machine: `PUT /v1/machines/{name}/archive`.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param folder - The machine folder, which must exist.
+     * @param archive - The archive: its bytes, or a function that opens it afresh, so that a retried request sends the same bytes.
+     * @param signal - Cancels the request.
+     * @returns When the service has written every file.
+     */
+    write(machine: string, folder: string, archive: Uint8Array | (() => Readable), signal?: AbortSignal): Promise<void>;
+    /**
+     * Deletes a file or folder in the machine: `DELETE /v1/machines/{name}/archive`.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param target - The path in the machine.
+     * @param signal - Cancels the request.
+     * @returns When the service has deleted it.
+     */
+    delete(machine: string, target: string, signal?: AbortSignal): Promise<void>;
+}

package/dist/groups/archives.js

@@ -0,0 +1,117 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { create, extract } from "tar";
+import { EastIndiaApiError } from "../errors.js";
+import { Headers, Routes } from "../routes.js";
+import { readHeaderJson, tarBody } from "../transport/api-connection.js";
+/** The query parameter that carries the path on the archive routes. A refusal for a missing path names it as the field at fault. */
+const PathParameter = "path";
+/**
+ * The archive routes of `endia cp`, which copy files into and out of a running machine as tar archives. Paths in a machine are
+ * absolute Windows paths, such as `C:\data` or `C:/data`; a relative path is relative to `C:\`.
+ *
+ * `copyIn` and `copyOut` copy between a local path and a machine folder. They place the copy inside an existing folder under the
+ * source's own name, which is one of the placements `docker cp` makes. `stat`, `read`, `write` and `delete` are the single routes,
+ * for a caller that applies the other placements or packs its own archives.
+ */
+export class ArchivesClient {
+    connection;
+    /** @internal */
+    constructor(connection) {
+        this.connection = connection;
+    }
+    /**
+     * Copies a local file or folder into a folder in the machine, under its own name. A link is copied as a link.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param source - The local file or folder.
+     * @param folder - The machine folder, which must exist.
+     * @param signal - Cancels the request.
+     * @returns When the service has written every file. When a file to be replaced is in use in the machine, the service stops the
+     * copy at that file and refuses it with `FILES_LOCKED`; the files written before it stay written.
+     */
+    copyIn(machine, source, folder, signal) {
+        const resolved = path.resolve(source);
+        const open = () => Readable.from(create({ cwd: path.dirname(resolved), follow: false }, [path.basename(resolved)]));
+        return this.write(machine, folder, open, signal);
+    }
+    /**
+     * Copies a file or folder out of the machine into a local folder, under its own name.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param source - The path in the machine.
+     * @param folder - The local folder, created when it does not exist.
+     * @param signal - Cancels the request.
+     * @returns The source's description. An archive entry whose path would lead outside the local folder is refused.
+     */
+    async copyOut(machine, source, folder, signal) {
+        await mkdir(folder, { recursive: true });
+        const read = await this.read(machine, source, signal);
+        await pipeline(read.archive, extract({ cwd: folder }), signal === undefined ? {} : { signal });
+        return read.stat;
+    }
+    /**
+     * Describes a path in the machine: `HEAD /v1/machines/{name}/archive`.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param target - The path in the machine.
+     * @param signal - Cancels the request.
+     * @returns The path's name, size, kind and modification time; null when nothing is at the path.
+     */
+    async stat(machine, target, signal) {
+        try {
+            return statOf(await this.connection.head(Routes.machineArchive(machine, target), signal));
+        }
+        catch (error) {
+            if (error instanceof EastIndiaApiError && error.status === 404 && error.fieldPath === PathParameter) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Reads a path in the machine as a tar archive: `GET /v1/machines/{name}/archive`.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param source - The path in the machine; a folder path ending in `\.` asks for the folder's contents without the folder.
+     * @param signal - Ends the request.
+     * @returns The path's description and the archive.
+     */
+    async read(machine, source, signal) {
+        const archive = await this.connection.openStream({ method: "GET", path: Routes.machineArchive(machine, source), signal });
+        return { stat: statOf(archive.headers), archive };
+    }
+    /**
+     * Extracts a tar archive into a folder in the machine: `PUT /v1/machines/{name}/archive`.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param folder - The machine folder, which must exist.
+     * @param archive - The archive: its bytes, or a function that opens it afresh, so that a retried request sends the same bytes.
+     * @param signal - Cancels the request.
+     * @returns When the service has written every file.
+     */
+    write(machine, folder, archive, signal) {
+        const body = tarBody(archive);
+        return this.connection.changeWithoutAnswer({ method: "PUT", path: Routes.machineArchive(machine, folder), body, signal });
+    }
+    /**
+     * Deletes a file or folder in the machine: `DELETE /v1/machines/{name}/archive`.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param target - The path in the machine.
+     * @param signal - Cancels the request.
+     * @returns When the service has deleted it.
+     */
+    delete(machine, target, signal) {
+        return this.connection.changeWithoutAnswer({ method: "DELETE", path: Routes.machineArchive(machine, target), signal });
+    }
+}
+function statOf(headers) {
+    const stat = readHeaderJson(headers, Headers.pathStat);
+    if (stat === undefined) {
+        throw new Error(`The service answered without a readable ${Headers.pathStat} header.`);
+    }
+    return stat;
+}