@lakutata/docker 3.0.0-beta.0

package/dist/cjs/docker/exceptions/DockerConnectionException.d.ts

@@ -0,0 +1,9 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown when the {@link Docker} component is created and cannot connect to its daemon: the socket or the host cannot be
+ * reached, the daemon does not answer its ping or its version, the TLS handshake fails, or an SSH connection is
+ * configured without the package `ssh2`. Its message is the cause's. Its `errno` is `E_DOCKER_CONNECTION`.
+ */
+export declare class DockerConnectionException extends Exception {
+    errno: string | number;
+}

package/dist/cjs/docker/exceptions/DockerConnectionException.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DockerConnectionException = void 0;
+const core_1 = require("@lakutata/core");
+/**
+ * Thrown when the {@link Docker} component is created and cannot connect to its daemon: the socket or the host cannot be
+ * reached, the daemon does not answer its ping or its version, the TLS handshake fails, or an SSH connection is
+ * configured without the package `ssh2`. Its message is the cause's. Its `errno` is `E_DOCKER_CONNECTION`.
+ */
+class DockerConnectionException extends core_1.Exception {
+    constructor() {
+        super(...arguments);
+        this.errno = 'E_DOCKER_CONNECTION';
+    }
+}
+exports.DockerConnectionException = DockerConnectionException;

package/dist/cjs/docker/exceptions/DockerContainerNotFoundException.d.ts

@@ -0,0 +1,9 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown when the daemon has no container with the ID, short ID or name given: by {@link Docker.getContainer}, and by
+ * the operations of a {@link DockerContainer} whose container was removed (HTTP 404 from the daemon). Its message is
+ * the daemon's ("No such container: web"). Its `errno` is `E_DOCKER_CONTAINER_NOT_FOUND`.
+ */
+export declare class DockerContainerNotFoundException extends Exception {
+    errno: string | number;
+}

package/dist/cjs/docker/exceptions/DockerContainerNotFoundException.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DockerContainerNotFoundException = void 0;
+const core_1 = require("@lakutata/core");
+/**
+ * Thrown when the daemon has no container with the ID, short ID or name given: by {@link Docker.getContainer}, and by
+ * the operations of a {@link DockerContainer} whose container was removed (HTTP 404 from the daemon). Its message is
+ * the daemon's ("No such container: web"). Its `errno` is `E_DOCKER_CONTAINER_NOT_FOUND`.
+ */
+class DockerContainerNotFoundException extends core_1.Exception {
+    constructor() {
+        super(...arguments);
+        this.errno = 'E_DOCKER_CONTAINER_NOT_FOUND';
+    }
+}
+exports.DockerContainerNotFoundException = DockerContainerNotFoundException;

package/dist/cjs/docker/exceptions/DockerImageBuildException.d.ts

@@ -0,0 +1,9 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown by {@link Docker.buildImage} when the build fails: a step of the Dockerfile failing (its message is BuildKit's
+ * error), the Dockerfile or a file of the context missing, a base image which cannot be pulled with the credentials
+ * given, the daemon unreachable, or the component destroyed during the build. Its `errno` is `E_DOCKER_IMAGE_BUILD`.
+ */
+export declare class DockerImageBuildException extends Exception {
+    errno: string | number;
+}

package/dist/cjs/docker/exceptions/DockerImageBuildException.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DockerImageBuildException = void 0;
+const core_1 = require("@lakutata/core");
+/**
+ * Thrown by {@link Docker.buildImage} when the build fails: a step of the Dockerfile failing (its message is BuildKit's
+ * error), the Dockerfile or a file of the context missing, a base image which cannot be pulled with the credentials
+ * given, the daemon unreachable, or the component destroyed during the build. Its `errno` is `E_DOCKER_IMAGE_BUILD`.
+ */
+class DockerImageBuildException extends core_1.Exception {
+    constructor() {
+        super(...arguments);
+        this.errno = 'E_DOCKER_IMAGE_BUILD';
+    }
+}
+exports.DockerImageBuildException = DockerImageBuildException;

package/dist/cjs/docker/exceptions/DockerImageImportException.d.ts

@@ -0,0 +1,9 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown by {@link Docker.importImage} when the daemon rejects the archive (not an archive of `docker save`, a corrupted
+ * archive), or when the image loaded cannot be known from the daemon's answer nor the archive's manifest. Its `errno` is
+ * `E_DOCKER_IMAGE_IMPORT`.
+ */
+export declare class DockerImageImportException extends Exception {
+    errno: string | number;
+}

package/dist/cjs/docker/exceptions/DockerImageImportException.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DockerImageImportException = void 0;
+const core_1 = require("@lakutata/core");
+/**
+ * Thrown by {@link Docker.importImage} when the daemon rejects the archive (not an archive of `docker save`, a corrupted
+ * archive), or when the image loaded cannot be known from the daemon's answer nor the archive's manifest. Its `errno` is
+ * `E_DOCKER_IMAGE_IMPORT`.
+ */
+class DockerImageImportException extends core_1.Exception {
+    constructor() {
+        super(...arguments);
+        this.errno = 'E_DOCKER_IMAGE_IMPORT';
+    }
+}
+exports.DockerImageImportException = DockerImageImportException;

package/dist/cjs/docker/exceptions/DockerImageNotFoundException.d.ts

@@ -0,0 +1,10 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown when the daemon has no image with the ID or the name given: by {@link Docker.getImage}, by
+ * {@link Docker.createContainer} and `DockerContainer.update()` (recreating a container whose image was removed), and by
+ * the operations of a {@link DockerImage} which was removed (HTTP 404 from the daemon). Its `errno` is
+ * `E_DOCKER_IMAGE_NOT_FOUND`.
+ */
+export declare class DockerImageNotFoundException extends Exception {
+    errno: string | number;
+}

package/dist/cjs/docker/exceptions/DockerImageNotFoundException.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DockerImageNotFoundException = void 0;
+const core_1 = require("@lakutata/core");
+/**
+ * Thrown when the daemon has no image with the ID or the name given: by {@link Docker.getImage}, by
+ * {@link Docker.createContainer} and `DockerContainer.update()` (recreating a container whose image was removed), and by
+ * the operations of a {@link DockerImage} which was removed (HTTP 404 from the daemon). Its `errno` is
+ * `E_DOCKER_IMAGE_NOT_FOUND`.
+ */
+class DockerImageNotFoundException extends core_1.Exception {
+    constructor() {
+        super(...arguments);
+        this.errno = 'E_DOCKER_IMAGE_NOT_FOUND';
+    }
+}
+exports.DockerImageNotFoundException = DockerImageNotFoundException;

package/dist/cjs/docker/exceptions/DockerImagePullException.d.ts

@@ -0,0 +1,9 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown by {@link Docker.pullImage} when the pull fails: the image or the registry not found, refused credentials, the
+ * daemon unreachable, or the component destroyed during the pull. Its message is the registry's or the daemon's. Its
+ * `errno` is `E_DOCKER_IMAGE_PULL`.
+ */
+export declare class DockerImagePullException extends Exception {
+    errno: string | number;
+}

package/dist/cjs/docker/exceptions/DockerImagePullException.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DockerImagePullException = void 0;
+const core_1 = require("@lakutata/core");
+/**
+ * Thrown by {@link Docker.pullImage} when the pull fails: the image or the registry not found, refused credentials, the
+ * daemon unreachable, or the component destroyed during the pull. Its message is the registry's or the daemon's. Its
+ * `errno` is `E_DOCKER_IMAGE_PULL`.
+ */
+class DockerImagePullException extends core_1.Exception {
+    constructor() {
+        super(...arguments);
+        this.errno = 'E_DOCKER_IMAGE_PULL';
+    }
+}
+exports.DockerImagePullException = DockerImagePullException;

package/dist/cjs/docker/exceptions/DockerImagePushException.d.ts

@@ -0,0 +1,8 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown by {@link DockerImage.push} when the registry refuses the push (refused credentials, a repository not found or
+ * not writable); its message is the registry's. Its `errno` is `E_DOCKER_IMAGE_PUSH`.
+ */
+export declare class DockerImagePushException extends Exception {
+    errno: string | number;
+}

package/dist/cjs/docker/exceptions/DockerImagePushException.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DockerImagePushException = void 0;
+const core_1 = require("@lakutata/core");
+/**
+ * Thrown by {@link DockerImage.push} when the registry refuses the push (refused credentials, a repository not found or
+ * not writable); its message is the registry's. Its `errno` is `E_DOCKER_IMAGE_PUSH`.
+ */
+class DockerImagePushException extends core_1.Exception {
+    constructor() {
+        super(...arguments);
+        this.errno = 'E_DOCKER_IMAGE_PUSH';
+    }
+}
+exports.DockerImagePushException = DockerImagePushException;

package/dist/cjs/docker/exceptions/DockerImageRepoTagNotFoundException.d.ts

@@ -0,0 +1,8 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown by {@link DockerImage.export} when the image does not have the `repoTag` to export and
+ * `createRepoTagIfNotExists` is `false`. Its `errno` is `E_DOCKER_IMAGE_REPO_TAG_NOT_FOUND`.
+ */
+export declare class DockerImageRepoTagNotFoundException extends Exception {
+    errno: string | number;
+}

package/dist/cjs/docker/exceptions/DockerImageRepoTagNotFoundException.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DockerImageRepoTagNotFoundException = void 0;
+const core_1 = require("@lakutata/core");
+/**
+ * Thrown by {@link DockerImage.export} when the image does not have the `repoTag` to export and
+ * `createRepoTagIfNotExists` is `false`. Its `errno` is `E_DOCKER_IMAGE_REPO_TAG_NOT_FOUND`.
+ */
+class DockerImageRepoTagNotFoundException extends core_1.Exception {
+    constructor() {
+        super(...arguments);
+        this.errno = 'E_DOCKER_IMAGE_REPO_TAG_NOT_FOUND';
+    }
+}
+exports.DockerImageRepoTagNotFoundException = DockerImageRepoTagNotFoundException;

package/dist/cjs/docker/exceptions/DockerNetworkNotFoundException.d.ts

@@ -0,0 +1,9 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown when the daemon has no network with the ID, short ID or name given: by {@link Docker.getNetwork} and
+ * {@link Docker.removeNetwork}, and by the creation of a container connected to a missing network (HTTP 404 from the
+ * daemon). Its `errno` is `E_DOCKER_NETWORK_NOT_FOUND`.
+ */
+export declare class DockerNetworkNotFoundException extends Exception {
+    errno: string | number;
+}

package/dist/cjs/docker/exceptions/DockerNetworkNotFoundException.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DockerNetworkNotFoundException = void 0;
+const core_1 = require("@lakutata/core");
+/**
+ * Thrown when the daemon has no network with the ID, short ID or name given: by {@link Docker.getNetwork} and
+ * {@link Docker.removeNetwork}, and by the creation of a container connected to a missing network (HTTP 404 from the
+ * daemon). Its `errno` is `E_DOCKER_NETWORK_NOT_FOUND`.
+ */
+class DockerNetworkNotFoundException extends core_1.Exception {
+    constructor() {
+        super(...arguments);
+        this.errno = 'E_DOCKER_NETWORK_NOT_FOUND';
+    }
+}
+exports.DockerNetworkNotFoundException = DockerNetworkNotFoundException;

package/dist/cjs/docker/exceptions/DockerRequestException.d.ts

@@ -0,0 +1,22 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown when the daemon refuses a request and no other exception of the component fits: a container name already used
+ * (HTTP 409), a container not running (HTTP 409), credentials refused by a registry ({@link Docker.loginRepository}),
+ * a network with containers connected, an image used by a container, an invalid parameter (HTTP 400), a failure of the
+ * daemon (HTTP 500). Its message is the daemon's, its `statusCode` the HTTP status of the daemon's answer. Its `errno`
+ * is `E_DOCKER_REQUEST`.
+ */
+export declare class DockerRequestException extends Exception {
+    errno: string | number;
+    /**
+     * The HTTP status of the daemon's answer (`409`, `500`…); the HTTP entrypoints reply with it when the exception
+     * fails a request.
+     */
+    readonly statusCode: number;
+    /**
+     * Create the exception of a refused request: the component creates it, an application does not.
+     * @param statusCode The HTTP status of the daemon's answer.
+     * @param message The daemon's message.
+     */
+    constructor(statusCode: number, message: string);
+}

package/dist/cjs/docker/exceptions/DockerRequestException.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DockerRequestException = void 0;
+const core_1 = require("@lakutata/core");
+/**
+ * Thrown when the daemon refuses a request and no other exception of the component fits: a container name already used
+ * (HTTP 409), a container not running (HTTP 409), credentials refused by a registry ({@link Docker.loginRepository}),
+ * a network with containers connected, an image used by a container, an invalid parameter (HTTP 400), a failure of the
+ * daemon (HTTP 500). Its message is the daemon's, its `statusCode` the HTTP status of the daemon's answer. Its `errno`
+ * is `E_DOCKER_REQUEST`.
+ */
+class DockerRequestException extends core_1.Exception {
+    /**
+     * Create the exception of a refused request: the component creates it, an application does not.
+     * @param statusCode The HTTP status of the daemon's answer.
+     * @param message The daemon's message.
+     */
+    constructor(statusCode, message) {
+        super(message);
+        this.errno = 'E_DOCKER_REQUEST';
+        this.statusCode = statusCode;
+    }
+}
+exports.DockerRequestException = DockerRequestException;

package/dist/cjs/docker/interfaces/IDockerConnectionOptions.d.ts

@@ -0,0 +1,75 @@
+import { IDockerKeyObject } from './IDockerKeyObject.js';
+/**
+ * The connection options of the {@link Docker} component, as {@link buildDockerConnectionOptions} takes them: a socket
+ * (`socketPath`), or a `host` and `port` reached over HTTP, HTTPS or SSH. Without `socketPath` nor `host`, the component
+ * connects to the Docker of the environment (`DOCKER_HOST`, else the local socket), with the other options given
+ * (`timeout`, `headers`, `version`…) applied over the environment's.
+ */
+export interface IDockerConnectionOptions {
+    /**
+     * The path of the daemon's Unix socket (`/var/run/docker.sock`), or of its named pipe on Windows
+     * (`//./pipe/docker_engine`). When set, `host` and `port` are ignored.
+     * @default undefined (the Docker of the environment)
+     */
+    socketPath?: string | undefined;
+    /**
+     * The host name or IP address of the daemon, reached with `protocol`.
+     * @default undefined (the Docker of the environment)
+     */
+    host?: string | undefined;
+    /**
+     * The port of the daemon on `host`: by convention 2375 over HTTP and 2376 over HTTPS; the SSH port for `'ssh'`.
+     * @default undefined (80 over HTTP, 443 over HTTPS, 22 over SSH)
+     */
+    port?: number | string | undefined;
+    /**
+     * The user of the SSH connections.
+     * @default undefined
+     */
+    username?: string | undefined;
+    /**
+     * The HTTP headers added to every request sent to the daemon.
+     * @default undefined
+     */
+    headers?: {
+        [name: string]: string;
+    };
+    /**
+     * The certificates of the authorities trusted for the daemon's HTTPS certificate: their PEM contents, not their file
+     * paths.
+     * @default undefined (the authorities of Node.js)
+     */
+    ca?: string | string[] | Buffer | Buffer[] | undefined;
+    /**
+     * The client certificate of the HTTPS connections (its PEM contents).
+     * @default undefined
+     */
+    cert?: string | string[] | Buffer | Buffer[] | undefined;
+    /**
+     * The private key of `cert` (its PEM contents), or keys with their passphrases.
+     * @default undefined
+     */
+    key?: string | string[] | Buffer | Buffer[] | IDockerKeyObject[] | undefined;
+    /**
+     * How `host` is reached: `'http'`, `'https'`, or `'ssh'` (which needs the optional package `ssh2`, and the Docker
+     * CLI on the remote host). Ignored with `socketPath`.
+     * @default 'https' when `ca`, `cert` and `key` are all given, 'http' otherwise
+     */
+    protocol?: 'https' | 'http' | 'ssh' | undefined;
+    /**
+     * How long a request may stay idle (no data received), in milliseconds, before it fails; the streams (followed
+     * logs) included.
+     * @default undefined (no timeout)
+     */
+    timeout?: number | undefined;
+    /**
+     * The version of the Docker Engine API used by the requests (`'1.47'` or `'v1.47'`).
+     * @default undefined (negotiated with the daemon)
+     */
+    version?: string | undefined;
+    /**
+     * The path of the SSH agent's socket, which authenticates the SSH connections.
+     * @default undefined (the `SSH_AUTH_SOCK` environment variable)
+     */
+    sshAuthAgent?: string | undefined;
+}

package/dist/cjs/docker/interfaces/IDockerConnectionOptions.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/docker/interfaces/IDockerHttpConnectionOptions.d.ts

@@ -0,0 +1,16 @@
+import { IDockerConnectionOptions } from './IDockerConnectionOptions.js';
+/**
+ * The options of {@link buildDockerHttpConnectionOptions}: a daemon reached over plain HTTP at `host` and `port`, with the
+ * headers, the timeout and the API version of {@link IDockerConnectionOptions} (its `protocol` is replaced by
+ * `'http'`).
+ */
+export interface IDockerHttpConnectionOptions extends Omit<IDockerConnectionOptions, 'socketPath' | 'sshAuthAgent'> {
+    /**
+     * The host name or IP address of the daemon.
+     */
+    host: string;
+    /**
+     * The TCP port of the daemon (2375 by convention).
+     */
+    port: number | string;
+}

package/dist/cjs/docker/interfaces/IDockerHttpConnectionOptions.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/docker/interfaces/IDockerHttpsConnectionOptions.d.ts

@@ -0,0 +1,16 @@
+import { IDockerConnectionOptions } from './IDockerConnectionOptions.js';
+/**
+ * The options of {@link buildDockerHttpsConnectionOptions}: a daemon reached over HTTPS at `host` and `port`, with the
+ * `ca`, `cert` and `key` (PEM contents), the headers, the timeout and the API version of
+ * {@link IDockerConnectionOptions} (its `protocol` is replaced by `'https'`).
+ */
+export interface IDockerHttpsConnectionOptions extends Omit<IDockerConnectionOptions, 'socketPath' | 'sshAuthAgent'> {
+    /**
+     * The host name or IP address of the daemon, as its certificate names it.
+     */
+    host: string;
+    /**
+     * The TCP port of the daemon (2376 by convention).
+     */
+    port: number | string;
+}

package/dist/cjs/docker/interfaces/IDockerHttpsConnectionOptions.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/docker/interfaces/IDockerKeyObject.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A private key of the HTTPS connections to the daemon, with its passphrase (the `key` option of {@link Docker}).
+ */
+export interface IDockerKeyObject {
+    /**
+     * The private key: its PEM contents, not its file path.
+     */
+    pem: string | Buffer;
+    /**
+     * The passphrase decrypting the key.
+     * @default undefined (an unencrypted key)
+     */
+    passphrase?: string | undefined;
+}

package/dist/cjs/docker/interfaces/IDockerKeyObject.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/docker/interfaces/IDockerSSHConnectionOptions.d.ts

@@ -0,0 +1,16 @@
+import { IDockerConnectionOptions } from './IDockerConnectionOptions.js';
+/**
+ * The options of {@link buildDockerSSHConnectionOptions}: a remote host reached over SSH at `host` and `port`, as
+ * `username`, authenticated by the SSH agent (`sshAuthAgent`), with the timeout and the API version of
+ * {@link IDockerConnectionOptions} (its `protocol` is replaced by `'ssh'`).
+ */
+export interface IDockerSSHConnectionOptions extends Omit<IDockerConnectionOptions, 'socketPath'> {
+    /**
+     * The host name or IP address of the remote host running the daemon.
+     */
+    host: string;
+    /**
+     * The SSH port of the remote host (usually 22).
+     */
+    port: number | string;
+}

package/dist/cjs/docker/interfaces/IDockerSSHConnectionOptions.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/docker/interfaces/IDockerSocketConnectionOptions.d.ts

@@ -0,0 +1,7 @@
+import { IDockerConnectionOptions } from './IDockerConnectionOptions.js';
+/**
+ * The options of {@link buildDockerSocketConnectionOptions}: the daemon's Unix socket or named pipe (`socketPath`), with
+ * the authorities (`ca`), the timeout and the API version of {@link IDockerConnectionOptions}.
+ */
+export interface IDockerSocketConnectionOptions extends Omit<IDockerConnectionOptions, 'sshAuthAgent' | 'key' | 'protocol' | 'cert' | 'headers' | 'username' | 'port' | 'host'> {
+}

package/dist/cjs/docker/interfaces/IDockerSocketConnectionOptions.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });