@zukhruf/docker 0.3.33 → 0.3.35

package/README.md

@@ -1,8 +1,8 @@
 # @zukhruf/docker
 
-> **Status: design for review.** This README is the API on paper. No code exists yet. The decisions are in the [ADRs](./docs/adr/). The package leads, and the repositories that use Docker change to fit it ([ADR 0003](./docs/adr/0003-the-package-leads-and-the-repositories-change.md)).
+> **Status: implemented.** Each call of the `## API` block works, and the tests run it on Docker Desktop (API 1.56) and on an SSH engine (API 1.51). A Windows named pipe is not proved yet (backlog #2753). The decisions are in the [ADRs](./docs/adr/). The package leads, and the repositories that use Docker change to fit it ([ADR 0003](./docs/adr/0003-the-package-leads-and-the-repositories-change.md)).
 
-A client for the Docker Engine API on Node.js. It selects the engine that the Docker CLI selects, and it sends HTTP requests to that engine with `node:http`: through a Unix socket, a Windows named pipe, or SSH. It needs no Docker CLI on the `PATH`, and it has no dependencies. Thus a desktop app that starts from the macOS Dock can use it, and so can a test, a sandbox or a deploy tool.
+A client for the Docker Engine API on Node.js. It selects the engine that the Docker CLI selects, and it sends HTTP requests to that engine with `node:http`: through a Unix socket, a Windows named pipe, or SSH. It needs no Docker CLI on the `PATH`, and it has no third-party dependencies; it uses `@zukhruf/async`. Thus a desktop app that starts from the macOS Dock can use it, and so can a test, a sandbox or a deploy tool.
 
 The package covers the containers of one engine and the resources around them: their images, volumes, networks, files, processes, output and events.
 
@@ -19,7 +19,7 @@ The words in these documents have one meaning each. See the glossary in [CONTEXT
 
 The package does not read `process.env`. The host program gives its environment as `environment`, and the package reads `DOCKER_HOST`, `DOCKER_CONTEXT` and `DOCKER_CONFIG` from it. Without `environment`, no variable applies, and the selection reads only the context store.
 
-Then `connect()` sends `GET /_ping` and negotiates the API version. Dispose the client to close its connections. An idle connection does not keep the process running.
+Then `connect()` sends `GET /_ping` and negotiates the API version. Dispose the client to close its connections. After the disposal starts, a request in flight and each new request reject with a `DockerError` that says that the client was disposed. An idle connection does not keep the process running.
 
 ```ts
 import { Docker } from '@zukhruf/docker';
@@ -72,19 +72,20 @@ An error has its own class when a caller does something different after it: star
 | `ContextNotFoundError`     | `Docker.connect({ context })` names a context that the context store does not have                                                            | Pick another context from `Docker.contexts()`      |
 | `ContainerNotFoundError`   | A request about a container gets 404                                                                                                          | Create the container again                         |
 | `ContainerNotRunningError` | An exec or a kill gets 409, or an attach finds the container exited or paused. `state` comes from an inspect: `created`, `exited`, `paused` … | Start or unpause it, then try again                |
+| `ContainerRunningError`    | A removal without `force` gets 409, and an inspect shows that the container runs                                                              | Stop it first, or remove it with `force`           |
 | `NameConflictError`        | A create of a container, network or volume finds the name taken                                                                               | Use `createOrGet()`, or another name               |
-| `ImageNotFoundError`       | A create gets 404 and the image is not on the engine; a pull or a push gets 404                                                               | Pull or build the image; check the name or `auth`  |
-| `NetworkNotFoundError`     | A create gets 404 and the image is on the engine; a request about a network gets 404                                                          | Create the network first                           |
+| `ImageNotFoundError`       | A create, a pull or a tag gets 404, or a push reports an error in its progress and an inspect does not find the image                         | Pull or build the image; check the name or `auth`  |
+| `NetworkNotFoundError`     | A start or a connect gets 404 (500 on an engine in swarm mode), and a lookup finds the network missing; a request about a network gets 404    | Create the network first                           |
 | `VolumeNotFoundError`      | A request about a volume gets 404                                                                                                             | Create the volume again                            |
 | `BindSourceNotFoundError`  | A create or a start refuses a bind mount whose `source` does not exist on the engine's host                                                   | Tell the user which host path is missing           |
 | `VolumeInUseError`         | A volume removal gets 409                                                                                                                     | Remove its containers first, or wait and try again |
-| `NetworkInUseError`        | A network removal gets 403 while containers are connected                                                                                     | Disconnect them first                              |
+| `NetworkInUseError`        | A network removal gets 403 while running containers are connected                                                                             | Disconnect them first                              |
 | `ImageInUseError`          | An image removal gets 409                                                                                                                     | Remove its containers first, or use `force`        |
 | `PathNotFoundError`        | A file request gets 404 and the container exists                                                                                              | Use a default, or create the file                  |
 | `NotAFileError`            | `readFile()` finds a directory, a link or another kind of entry. `kind` names it                                                              | Use `getArchive()` for the tree                    |
 | `ReadOnlyPathError`        | The engine refuses an extraction, and an inspect shows that the directory is on a read-only root filesystem or in a read-only mount           | Write under a writable mount, or use `exec()`      |
 
-Each class extends a base class, so a broad catch still works. `DockerError` is the base of every error of the package. `DockerEngineError` is the base of every answer of the engine that is an error. It has `status`, `method` and `path`, and its `message` is the message of the engine. An error with no class of its own, such as an error in the progress of a pull, is a `DockerEngineError`.
+Each class extends a base class, so a broad catch still works. `DockerError` is the base of every error of the package. `DockerEngineError` is the base of every answer of the engine that is an error. It has `status` and `request` (the `method` and `path` of the request), and its `message` is the message of the engine. The base keeps the request apart in `request`, so `path` on `PathNotFoundError`, `NotAFileError` and `ReadOnlyPathError` is the path in the container. An error with no class of its own, such as an error in the progress of a pull, is a `DockerEngineError`.
 
 ```ts
 import {
@@ -129,7 +130,7 @@ Some answers of the engine are not errors here:
 | `container.start()` of a running container, `container.stop()` of a stopped one | 304           | resolves    |
 | `remove()` of a missing container, volume, network or image                     | 404           | resolves    |
 
-A removal of a container whose removal is already in progress (409) waits until the container is gone, and then resolves.
+A removal of a container whose removal is already in progress (409) inspects the container until it is gone, and then resolves. When the other removal fails and the container stays, it sends a forced removal again. The signal stops the wait.
 
 ## Create a container that you own
 
@@ -245,6 +246,8 @@ await postgres.exec(
 );
 ```
 
+A command can end before it reads all of its input, such as `head -c1`. The result of the command then stands: the input that the command did not read is not an error.
+
 `container.spawn()` gives the container process while the command runs. With `stdin: true`, the container process has a writable `stdin`. Only `stdin.close()` ends the input. The package drops an empty write, so an empty write never ends the input.
 
 ```ts
@@ -358,6 +361,11 @@ await network.connect(postgres, { Aliases: ['db'] });
 await network.disconnect(postgres);
 ```
 
+- From API 1.44, the engine refuses a create with a taken name. Thus `networks.create()` rejects with `NameConflictError`, and `networks.createOrGet()` gives `{ created: false, network }` with the network that exists.
+- Only a running container has an endpoint on a network. Thus only a running container keeps a network from its removal, and `NetworkInUseError` gives the IDs of the running containers.
+- The engine keeps the network of a created container for its start. Thus a connect of a created container to a missing network resolves, and `start()` then rejects with `NetworkNotFoundError`.
+- `remove()` of `bridge`, `host` or `none` rejects with `DockerEngineError` and 403: the engine never removes a pre-defined network.
+
 ## Images
 
 Images have no owner: an image is a cache that each container on the engine shares, so no handle removes one on disposal.
@@ -384,7 +392,9 @@ await docker.images.load(Readable.toWeb(createReadStream('alpine.tar')));
 await docker.images.remove('alpine:3');
 ```
 
-`pull()`, `push()` and `load()` read the progress of the engine until the end. They reject with `DockerEngineError` when the engine reports an error in the progress. Then `status` is `undefined`, because the HTTP status was 200. `auth` holds explicit credentials. The package runs no credential helper, because a helper is a program on the `PATH`.
+`pull()`, `push()` and `load()` read the progress of the engine until the end. They reject with `DockerEngineError` when the engine reports an error in the progress. Then `status` is `undefined`, because the HTTP status was 200. The engine answers a push of an image that it does not have with 200 too, and reports the error in the progress. Thus `push()` inspects the image after an error in the progress: when the engine does not have the image, `push()` rejects with `ImageNotFoundError`.
+
+`images.remove()` of one name of an image that has more names removes only that name. A removal of an image that a container uses, or a removal by ID of an image with more than one name, rejects with `ImageInUseError`. `auth` holds explicit credentials. The package runs no credential helper, because a helper is a program on the `PATH`.
 
 ## Events
 
@@ -788,8 +798,8 @@ export class UnsupportedEngineError extends DockerError {
 export class DockerEngineError extends DockerError {
   /** The HTTP status; undefined for an error in the progress of a pull, a push or a load. */
   readonly status: number | undefined;
-  readonly method: string;
-  readonly path: string;
+  /** The request that got the error. */
+  readonly request: { readonly method: string; readonly path: string };
 }
 
 export class ContainerNotFoundError extends DockerEngineError {
@@ -800,9 +810,13 @@ export class ContainerNotRunningError extends DockerEngineError {
   /** From an inspect after the 409: 'created', 'exited', 'paused', 'restarting', 'removing' or 'dead'. */
   readonly state: string;
 }
+export class ContainerRunningError extends DockerEngineError {
+  readonly container: string;
+}
 export class NameConflictError extends DockerEngineError {
   readonly kind: 'container' | 'network' | 'volume';
-  readonly name: string;
+  /** The name that another resource has. Not `name`: that is the name of the error class. */
+  readonly takenName: string;
 }
 export class ImageNotFoundError extends DockerEngineError {
   readonly image: string;

package/dist/container-process.d.ts

@@ -0,0 +1,35 @@
+import type { HijackedConnection } from './engine-client.ts';
+import { type OutputChunk } from './multiplexed-stream.ts';
+import { type ExecResult } from './output.ts';
+export interface ContainerProcessOptions {
+    /** Gives the process a writable `stdin`. */
+    stdin: boolean;
+    /** An abort rejects the iteration with the reason of the signal. It does not stop the command. */
+    signal?: AbortSignal | undefined;
+    /**
+     * Gives the exit code. `outputEnded` resolves when the output ends, and
+     * rejects when the iteration ends first.
+     */
+    exitCode: (outputEnded: Promise<void>) => Promise<number>;
+}
+/**
+ * An exec or an attached container: one stream of output chunks in the order
+ * of the engine, given once, a writable `stdin` when it has one, and the exit
+ * code when it ends.
+ */
+export declare class ContainerProcess implements AsyncIterable<OutputChunk> {
+    #private;
+    /** Present with { stdin: true }. Only close() ends the input; an empty write is dropped. */
+    readonly stdin: WritableStream<Uint8Array> | undefined;
+    constructor(connection: HijackedConnection, options: ContainerProcessOptions);
+    /**
+     * The exit code. For an exec, it comes after the output ends. It rejects
+     * when the iteration ends before the output ends.
+     */
+    get exitCode(): Promise<number>;
+    /** The chunks, once. A second iteration rejects. */
+    [Symbol.asyncIterator](): AsyncIterator<OutputChunk>;
+    /** Reads each chunk and gives the result. */
+    collect(): Promise<ExecResult>;
+}
+//# sourceMappingURL=container-process.d.ts.map

package/dist/container-process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-process.d.ts","sourceRoot":"","sources":["../src/container-process.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,OAAO,EAAE,KAAK,WAAW,EAAgB,MAAM,yBAAyB,CAAC;AACzE,OAAO,EAAE,KAAK,UAAU,EAAc,MAAM,aAAa,CAAC;AAE1D,MAAM,WAAW,uBAAuB;IACtC,4CAA4C;IAC5C,KAAK,EAAE,OAAO,CAAC;IACf,kGAAkG;IAClG,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACjC;;;OAGG;IACH,QAAQ,EAAE,CAAC,WAAW,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3D;AAmBD;;;;GAIG;AACH,qBAAa,gBAAiB,YAAW,aAAa,CAAC,WAAW,CAAC;;IACjE,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,SAAS,CAAC;gBAMrD,UAAU,EAAE,kBAAkB,EAC9B,OAAO,EAAE,uBAAuB;IA6ClC;;;OAGG;IACH,IAAI,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAE9B;IAED,oDAAoD;IACpD,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,WAAW,CAAC;IASpD,6CAA6C;IACvC,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC;CAIrC"}

package/dist/container-process.js

@@ -0,0 +1,91 @@
+import { DockerError } from "./errors.js";
+import { outputChunks } from "./multiplexed-stream.js";
+import { readOutput } from "./output.js";
+async function* withHead(head, socket) {
+    if (head.byteLength > 0)
+        yield head;
+    for await (const chunk of socket) {
+        if (chunk instanceof Uint8Array)
+            yield chunk;
+    }
+}
+/** Writes to the socket and resolves when the socket took the bytes. */
+async function write(socket, chunk) {
+    const { promise, resolve, reject } = Promise.withResolvers();
+    socket.write(chunk, (error) => (error ? reject(error) : resolve()));
+    return promise;
+}
+/**
+ * An exec or an attached container: one stream of output chunks in the order
+ * of the engine, given once, a writable `stdin` when it has one, and the exit
+ * code when it ends.
+ */
+export class ContainerProcess {
+    /** Present with { stdin: true }. Only close() ends the input; an empty write is dropped. */
+    stdin;
+    /** Holds the chunks until the first iteration takes them. */
+    #unread;
+    #exitCode;
+    constructor(connection, options) {
+        const { socket, head, contentType } = connection;
+        const { signal } = options;
+        // An error before the first read waits for the iteration, which rejects with it.
+        socket.on('error', () => undefined);
+        const abort = () => socket.destroy(signal?.reason);
+        signal?.addEventListener('abort', abort, { once: true });
+        socket.once('close', () => signal?.removeEventListener('abort', abort));
+        const outputEnded = Promise.withResolvers();
+        outputEnded.promise.catch(() => undefined);
+        async function* read() {
+            try {
+                signal?.throwIfAborted();
+                yield* outputChunks(withHead(head, socket), contentType);
+                outputEnded.resolve();
+            }
+            catch (error) {
+                outputEnded.reject(error);
+                throw error;
+            }
+            finally {
+                outputEnded.reject(new DockerError('The iteration ended before the output ended.'));
+                socket.destroy();
+            }
+        }
+        this.#unread = [read()];
+        const exitCode = options.exitCode(outputEnded.promise);
+        // A caller that never reads the exit code gets no unhandled rejection.
+        exitCode.catch(() => undefined);
+        this.#exitCode = () => exitCode;
+        this.stdin = options.stdin
+            ? new WritableStream({
+                write: async (chunk) => {
+                    if (chunk.byteLength > 0)
+                        await write(socket, chunk);
+                },
+                close: () => connection.endInput(),
+                abort: () => connection.endInput(),
+            })
+            : undefined;
+    }
+    /**
+     * The exit code. For an exec, it comes after the output ends. It rejects
+     * when the iteration ends before the output ends.
+     */
+    get exitCode() {
+        return this.#exitCode();
+    }
+    /** The chunks, once. A second iteration rejects. */
+    [Symbol.asyncIterator]() {
+        const chunks = this.#unread.pop();
+        if (chunks !== undefined)
+            return chunks;
+        const error = new DockerError('A container process gives its output once, and an iteration already read it.');
+        return { next: async () => Promise.reject(error) };
+    }
+    /** Reads each chunk and gives the result. */
+    async collect() {
+        const output = await readOutput(this);
+        return { exitCode: await this.exitCode, ...output };
+    }
+}
+//# sourceMappingURL=container-process.js.map

package/dist/container-process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-process.js","sourceRoot":"","sources":["../src/container-process.ts"],"names":[],"mappings":"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"}

package/dist/containers.d.ts

@@ -0,0 +1,160 @@
+import { ContainerProcess } from './container-process.ts';
+import type * as EngineApi from './engine-api.ts';
+import { type EngineClient } from './engine-client.ts';
+import type { Images } from './images.ts';
+import { type OutputChunk } from './multiplexed-stream.ts';
+import type { CancelOptions, Filters } from './options.ts';
+import { type ExecResult, type Output } from './output.ts';
+/** A file or a directory for writeFiles(). It belongs to uid:gid, or to 0:0. */
+export type ContainerFile = {
+    path: string;
+    data: string | Uint8Array;
+    mode?: number;
+    uid?: number;
+    gid?: number;
+} | {
+    path: string;
+    directory: true;
+    mode?: number;
+    uid?: number;
+    gid?: number;
+};
+/** The query of the logs, as the Engine API takes it. */
+export interface LogQuery {
+    tail?: number | 'all';
+    /** Seconds since the Unix epoch. */
+    since?: number;
+    timestamps?: boolean;
+}
+/** The result of createOrGet(): an owned handle when this call created the resource. */
+export type Created<Key extends string, Owned, Found> = ({
+    created: true;
+} & Record<Key, Owned>) | ({
+    created: false;
+} & Record<Key, Found>);
+/** A container, by the ID that the engine gave it. It has no disposal. */
+export declare class Container {
+    #private;
+    readonly id: string;
+    constructor(client: EngineClient, id: string);
+    inspect(options?: CancelOptions): Promise<EngineApi.ContainerInspectResponse>;
+    /**
+     * Resolves for 304 (already running). A 404 is a missing container or a
+     * missing network: an inspect of the container tells which, and a lookup of
+     * each of its networks names the missing one. An engine in swarm mode
+     * answers a missing network with 500 ("Could not attach to network", probed
+     * at API 1.51), so a 500 gets the same lookup.
+     */
+    start(options?: CancelOptions): Promise<void>;
+    /** Resolves for 304 (already stopped). t: seconds before the engine kills the main process. */
+    stop(options?: CancelOptions & {
+        t?: number;
+    }): Promise<void>;
+    restart(options?: CancelOptions & {
+        t?: number;
+    }): Promise<void>;
+    /** A 409 means that the container does not run: an inspect gives its state. */
+    kill(processSignal?: string, options?: CancelOptions): Promise<void>;
+    pause(options?: CancelOptions): Promise<void>;
+    unpause(options?: CancelOptions): Promise<void>;
+    wait(options?: CancelOptions & {
+        condition?: 'not-running' | 'next-exit' | 'removed';
+    }): Promise<EngineApi.ContainerWaitResponse>;
+    /**
+     * Resolves for 404. A 409 is a removal that is already in progress, or,
+     * without `force`, a container that runs: an inspect tells which. For a
+     * removal in progress, it inspects the container until it is gone, and
+     * when the other removal ends and leaves the container, it sends a forced
+     * removal again. A container
+     * that runs or is paused rejects with ContainerRunningError. The engine
+     * gives the state 'running' while it kills the container for a forced
+     * removal, so with `force` the state alone does not tell: it waits.
+     */
+    remove(options?: CancelOptions & {
+        force?: boolean;
+        v?: boolean;
+    }): Promise<void>;
+    /** The published binding of a port of the container; undefined when it is not published. The IPv4 binding comes first. */
+    port(containerPort: number, protocol?: 'tcp' | 'udp', options?: CancelOptions): Promise<{
+        host: string;
+        port: number;
+    } | undefined>;
+    /** The logs until now. */
+    logs(options?: CancelOptions & LogQuery): Promise<Output>;
+    /** The logs as the container writes them. The iteration ends when the container stops. */
+    followLogs(options?: CancelOptions & LogQuery): AsyncIterable<OutputChunk>;
+    /** Runs a command in the container and reads its output to the end. stdin is sent, and then the input ends. */
+    exec(body: EngineApi.ExecConfig, options?: CancelOptions & {
+        stdin?: string | Uint8Array;
+    }): Promise<ExecResult>;
+    /** Runs a command in the container and gives its container process while it runs. */
+    spawn(body: EngineApi.ExecConfig, options?: CancelOptions & {
+        stdin?: boolean;
+    }): Promise<ContainerProcess>;
+    /**
+     * Attaches to the output of the container. For a created container, the
+     * exit code is the code of its next exit, so attach before start(). For a
+     * running container, it is the code when the container stops. An exited or
+     * a paused container rejects with ContainerNotRunningError: Moby gives no
+     * 409 for an attach to an exited container, so the state of an inspect
+     * decides.
+     */
+    attach(options?: CancelOptions & {
+        stdin?: boolean;
+    }): Promise<ContainerProcess>;
+    /** The path stat of a path in the container: HEAD of the archive. undefined for 404 when the container exists. */
+    stat(path: string, options?: CancelOptions): Promise<EngineApi.ContainerPathStat | undefined>;
+    /** The bytes of one regular file. A directory, a link and each other kind of entry reject with NotAFileError. */
+    readFile(path: string, options?: CancelOptions): Promise<Uint8Array>;
+    /**
+     * Sends one archive of the files. It extracts the archive in the deepest
+     * directory that holds each entry and that exists, which stat() finds. The
+     * engine creates each parent directory that an entry implies below it.
+     */
+    writeFiles(files: ContainerFile[], options?: CancelOptions): Promise<void>;
+    /** The tar stream of a path in the container: a file, or a directory with its tree. */
+    getArchive(path: string, options?: CancelOptions): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Extracts a tar archive in a directory of the container. With copyUIDGID,
+     * each entry belongs to the user of the container (Config.User), not to
+     * the owner in the archive.
+     */
+    putArchive(directory: string, archive: ReadableStream<Uint8Array> | Uint8Array, options?: CancelOptions & {
+        copyUIDGID?: boolean;
+    }): Promise<void>;
+}
+/** A container that this handle created. Disposal removes it with its anonymous volumes. */
+export declare class OwnedContainer extends Container implements AsyncDisposable {
+    /** remove({ force: true, v: true }) */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/** The containers of one engine. */
+export declare class Containers {
+    #private;
+    constructor(client: EngineClient, images: Images);
+    create(body: EngineApi.ContainerCreateRequest, options?: CancelOptions & {
+        name?: string;
+        platform?: string;
+    }): Promise<OwnedContainer>;
+    /**
+     * Creates the container, attaches to its output, starts it, waits for its
+     * end, and removes it. A non-zero exit code is data. A failure and a cancel
+     * also remove the container.
+     */
+    run(body: EngineApi.ContainerCreateRequest, options?: CancelOptions & {
+        name?: string;
+        platform?: string;
+    }): Promise<ExecResult>;
+    /** Creates the container, or gives the one that has the name. The container that exists wins. */
+    createOrGet(body: EngineApi.ContainerCreateRequest, options: CancelOptions & {
+        name: string;
+        platform?: string;
+    }): Promise<Created<'container', OwnedContainer, Container>>;
+    /** One inspect: a handle with the ID of the engine, or undefined for 404. */
+    find(nameOrId: string, options?: CancelOptions): Promise<Container | undefined>;
+    list(options?: CancelOptions & {
+        all?: boolean;
+        filters?: Filters;
+    }): Promise<EngineApi.ContainerSummary[]>;
+}
+//# sourceMappingURL=containers.d.ts.map

package/dist/containers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"containers.d.ts","sourceRoot":"","sources":["../src/containers.ts"],"names":[],"mappings":"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"}