@lakutata/docker 3.0.0-beta.0

package/dist/types/client/types/PortBinding.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A binding of a port of a container to a port of the host in the Docker Engine API (PortBinding)
+ */
+export type PortBinding = {
+    /**
+     * The host address the port is bound on, all of them when empty
+     */
+    HostIp?: string;
+    HostPort: string;
+};

package/dist/types/docker/ConnectionOptionsBuilder.d.ts

@@ -0,0 +1,128 @@
+import { IDockerConnectionOptions } from './interfaces/IDockerConnectionOptions.js';
+import { IDockerHttpConnectionOptions } from './interfaces/IDockerHttpConnectionOptions.js';
+import { IDockerHttpsConnectionOptions } from './interfaces/IDockerHttpsConnectionOptions.js';
+import { IDockerSSHConnectionOptions } from './interfaces/IDockerSSHConnectionOptions.js';
+import { ComponentOptionsBuilder } from '@lakutata/core';
+/**
+ * Build the component options of a {@link Docker} connected as the options say, to register it in the `components` of
+ * an application under the name of your choice. Without `socketPath` nor `host`, it connects to the Docker of the
+ * environment (`DOCKER_HOST`, else the local socket). The options are validated when the component is created, not
+ * here.
+ * @param options The connection options: a socket (`socketPath`), or a `host` and `port` reached with `protocol`
+ * (`'http'`, `'https'` or `'ssh'`), with their TLS, SSH, timeout and API version options.
+ * @returns The component options (`{class: Docker, ...options}`).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildDockerConnectionOptions} from 'lakutata/com/docker'
+ *
+ * Application.run(() => ({
+ *     id: 'docker.app',
+ *     name: 'Docker',
+ *     components: {
+ *         //The Docker of the environment (DOCKER_HOST, else the local socket), with the API version 1.47
+ *         docker: buildDockerConnectionOptions({version: '1.47'})
+ *     }
+ * }))
+ * ```
+ */
+export declare const buildDockerConnectionOptions: ComponentOptionsBuilder<IDockerConnectionOptions>;
+/**
+ * Build the component options of a {@link Docker} connected to the Unix socket of a daemon (or its named pipe on
+ * Windows), to register it in the `components` of an application. The options are validated when the component is
+ * created, not here.
+ * @param options The path of the socket (`socketPath`), with the timeout and the API version. Without `socketPath`, the
+ * Docker of the environment is used, with the other options applied over it.
+ * @returns The component options (`{class: Docker, ...options}`).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildDockerSocketConnectionOptions} from 'lakutata/com/docker'
+ *
+ * Application.run(() => ({
+ *     id: 'docker.app',
+ *     name: 'Docker',
+ *     components: {
+ *         docker: buildDockerSocketConnectionOptions({socketPath: '/var/run/docker.sock', timeout: 60000})
+ *     }
+ * }))
+ * ```
+ */
+export declare const buildDockerSocketConnectionOptions: ComponentOptionsBuilder<IDockerConnectionOptions>;
+/**
+ * Build the component options of a {@link Docker} connected to a daemon over plain HTTP (`dockerd -H tcp://0.0.0.0:2375`),
+ * to register it in the `components` of an application. The connection is neither encrypted nor authenticated: keep it
+ * to trusted networks. The options are validated when the component is created, not here.
+ * @param options The `host` and `port` of the daemon, with the headers, the timeout and the API version; the `protocol`
+ * is set to `'http'`.
+ * @returns The component options (`{class: Docker, protocol: 'http', ...options}`).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildDockerHttpConnectionOptions} from 'lakutata/com/docker'
+ *
+ * Application.run(() => ({
+ *     id: 'docker.app',
+ *     name: 'Docker',
+ *     components: {
+ *         docker: buildDockerHttpConnectionOptions({host: '192.168.1.10', port: 2375})
+ *     }
+ * }))
+ * ```
+ */
+export declare const buildDockerHttpConnectionOptions: ComponentOptionsBuilder<IDockerHttpConnectionOptions>;
+/**
+ * Build the component options of a {@link Docker} connected to a daemon over HTTPS (`dockerd --tlsverify -H
+ * tcp://0.0.0.0:2376`), to register it in the `components` of an application. The options are validated when the
+ * component is created, not here.
+ * @param options The `host` and `port` of the daemon, with the PEM contents of the authority (`ca`), the client
+ * certificate (`cert`) and its key (`key`), the headers, the timeout and the API version; the `protocol` is set to
+ * `'https'`.
+ * @returns The component options (`{class: Docker, protocol: 'https', ...options}`).
+ * @example
+ * ```typescript
+ * import {readFileSync} from 'node:fs'
+ * import {Application} from 'lakutata'
+ * import {buildDockerHttpsConnectionOptions} from 'lakutata/com/docker'
+ *
+ * Application.run(() => ({
+ *     id: 'docker.app',
+ *     name: 'Docker',
+ *     components: {
+ *         //The PEM contents, not the file paths
+ *         docker: buildDockerHttpsConnectionOptions({
+ *             host: 'docker.example.com',
+ *             port: 2376,
+ *             ca: readFileSync('/etc/docker/certs/ca.pem'),
+ *             cert: readFileSync('/etc/docker/certs/cert.pem'),
+ *             key: readFileSync('/etc/docker/certs/key.pem')
+ *         })
+ *     }
+ * }))
+ * ```
+ */
+export declare const buildDockerHttpsConnectionOptions: ComponentOptionsBuilder<IDockerHttpsConnectionOptions>;
+/**
+ * Build the component options of a {@link Docker} connected to a remote daemon over SSH, as `DOCKER_HOST=ssh://user@host`
+ * does, to register it in the `components` of an application. The requests go through `docker system dial-stdio` run on
+ * the remote host, which needs the Docker CLI; locally, the optional package `ssh2` must be installed. The SSH connection
+ * authenticates through the SSH agent (no password). The options are validated when the component is created, not here.
+ * @param options The `host` and `port` (the SSH port, usually 22) of the remote host, the `username`, the SSH agent's
+ * socket (`sshAuthAgent`; `SSH_AUTH_SOCK` by default), the timeout and the API version; the `protocol` is set to
+ * `'ssh'`.
+ * @returns The component options (`{class: Docker, protocol: 'ssh', ...options}`).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildDockerSSHConnectionOptions} from 'lakutata/com/docker'
+ *
+ * Application.run(() => ({
+ *     id: 'docker.app',
+ *     name: 'Docker',
+ *     components: {
+ *         docker: buildDockerSSHConnectionOptions({host: 'docker.example.com', port: 22, username: 'deploy'})
+ *     }
+ * }))
+ * ```
+ */
+export declare const buildDockerSSHConnectionOptions: ComponentOptionsBuilder<IDockerSSHConnectionOptions>;

package/dist/types/docker/Docker.d.ts

@@ -0,0 +1,301 @@
+import { Component } from '@lakutata/core';
+import { DockerImage } from './lib/DockerImage.js';
+import { DockerContainer } from './lib/DockerContainer.js';
+import { ImagePullOptions } from './options/image/ImagePullOptions.js';
+import { ImageBuildOptions } from './options/image/ImageBuildOptions.js';
+import { IDockerKeyObject } from './interfaces/IDockerKeyObject.js';
+import { ImageImportOptions } from './options/image/ImageImportOptions.js';
+import { NetworkCreateOptions } from './options/network/NetworkCreateOptions.js';
+import { NetworkInfo } from './types/NetworkInfo.js';
+import { ContainerSettingOptions } from './options/container/ContainerSettingOptions.js';
+import { DockerPruneOptions } from './options/DockerPruneOptions.js';
+import { DockerAuthOptions } from './options/auth/DockerAuthOptions.js';
+/**
+ * The Docker component: drives a Docker daemon over the Docker Engine API, to pull, build, import, export, tag and push
+ * images, to create, run and manage containers (exec, TTYs, logs, stats, commit, archives) and to manage networks.
+ * Register it in the `components` of an application (`{class: Docker}`, or the result of one of the
+ * `BuildDocker*ConnectionOptions` functions) and get it with `getObject()` or `@Inject`; it is a singleton.
+ *
+ * Without `socketPath` nor `host`, it connects to the Docker of the environment: `DOCKER_HOST` (with
+ * `DOCKER_TLS_VERIFY`, `DOCKER_CERT_PATH` and `DOCKER_CLIENT_TIMEOUT`), else the named pipe `//./pipe/docker_engine` on
+ * Windows, the socket of Docker Desktop (`~/.docker/run/docker.sock`) when it exists, or `/var/run/docker.sock`; the
+ * other options given (`timeout`, `headers`, `version`…) apply over the environment's. No Docker CLI is needed locally
+ * (the SSH connections need it on the remote host).
+ *
+ * When it is created, the component pings the daemon and negotiates the API version (the newest one supported by both,
+ * from 1.41 to 1.56): a daemon which cannot be reached fails its creation with {@link DockerConnectionException}.
+ * Afterwards, a daemon which cannot be reached rejects the calls with the network error of Node.js (`ECONNREFUSED`,
+ * `ENOENT`…). A request the daemon refuses rejects with the exception of what is missing
+ * ({@link DockerContainerNotFoundException}, {@link DockerImageNotFoundException},
+ * {@link DockerNetworkNotFoundException}), else with a {@link DockerRequestException}, whose `statusCode` is the HTTP
+ * status and whose message is the daemon's. The pulls, builds, imports and pushes wrap their failures in their own
+ * exceptions ({@link DockerImagePullException}…).
+ *
+ * When the component is destroyed (the application stopping), the pulls and builds in progress are aborted (they reject
+ * with their exception), the listings in progress resolve with an empty list, and its connections are closed.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {Docker, type DockerContainer, type DockerImage} from 'lakutata/com/docker'
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'docker.app',
+ *         name: 'Docker',
+ *         components: {
+ *             //The Docker of the environment: DOCKER_HOST, else the local socket
+ *             docker: {class: Docker}
+ *         }
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const docker: Docker = await app.getObject('docker')
+ *         const image: DockerImage = await docker.pullImage({repo: 'alpine', tag: '3.20'})
+ *         //Created, then started
+ *         const container: DockerContainer = await image.run({name: 'hello', cmd: ['sleep', '60']})
+ *         console.log((await container.exec({cmd: ['echo', 'hello']})).stdout)
+ *         await container.remove({force: true})
+ *     })
+ * ```
+ */
+export declare class Docker extends Component {
+    #private;
+    /**
+     * 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, see {@link Docker})
+     */
+    protected readonly socketPath?: string | undefined;
+    /**
+     * The host name or IP address of the daemon, reached over TCP (`protocol` `'http'` or `'https'`) or SSH
+     * (`'ssh'`).
+     * @default undefined (the Docker of the environment, see {@link Docker})
+     */
+    protected readonly 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)
+     */
+    protected readonly port?: number | string | undefined;
+    /**
+     * The user of the SSH connections. There is no password: the SSH connection authenticates through the SSH agent
+     * (see `sshAuthAgent`).
+     * @default undefined
+     */
+    protected readonly username?: string | undefined;
+    /**
+     * The HTTP headers added to every request sent to the daemon (a proxy's credentials…), the Docker of the
+     * environment's included.
+     * @default undefined
+     */
+    protected readonly 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)
+     */
+    protected readonly ca?: string | string[] | Buffer | Buffer[] | undefined;
+    /**
+     * The client certificate of the HTTPS connections (its PEM contents), for a daemon verifying its clients
+     * (`--tlsverify`).
+     * @default undefined
+     */
+    protected readonly cert?: string | string[] | Buffer | Buffer[] | undefined;
+    /**
+     * The private key of `cert` (its PEM contents), or keys with their passphrases ({@link IDockerKeyObject}).
+     * @default undefined
+     */
+    protected readonly key?: string | string[] | Buffer | Buffer[] | IDockerKeyObject[] | undefined;
+    /**
+     * How `host` is reached: `'http'`, `'https'` (with `ca`, `cert` and `key`), or `'ssh'`. Over SSH, the requests
+     * go through `docker system dial-stdio` run on the remote host (which needs the Docker CLI), and the optional package
+     * `ssh2` must be installed, otherwise the component's creation fails with {@link DockerConnectionException}.
+     * Ignored with `socketPath`.
+     * @default 'https' when `ca`, `cert` and `key` are all given, 'http' otherwise
+     */
+    protected readonly protocol?: 'https' | 'http' | 'ssh' | undefined;
+    /**
+     * How long a request may stay idle (no data received), in milliseconds; the request then fails with the error
+     * "Timeout of … ms exceeded". It also applies to the streams (a followed log with no output for that long fails),
+     * and to the Docker of the environment (over its `DOCKER_CLIENT_TIMEOUT`).
+     * @default undefined (no timeout, or the environment's `DOCKER_CLIENT_TIMEOUT`)
+     */
+    protected readonly 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: the newest version both support)
+     */
+    protected readonly version?: string | undefined;
+    /**
+     * The path of the SSH agent's socket, which authenticates the SSH connections.
+     * @default undefined (the `SSH_AUTH_SOCK` environment variable)
+     */
+    protected readonly sshAuthAgent?: string | undefined;
+    /**
+     * Connect to the daemon: ping it, then negotiate the API version.
+     * @throws {DockerConnectionException} When the daemon cannot be reached or does not answer, or when an SSH
+     * connection is configured without the package `ssh2`.
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * Abort the pulls, builds and listings in progress (the pulls and builds then reject), then close the connections
+     * to the daemon.
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /** Docker Common Operations **/
+    /**
+     * Remove the daemon's unused resources, as `docker <kind> prune` does without options: the stopped containers, then
+     * the dangling images (untagged and unused), the unused networks and the unused anonymous volumes. Without
+     * options, the containers and the images are pruned; the networks and the volumes only when asked.
+     * @param options The kinds of resources pruned: `containers` and `images` default to `true`, `networks` and
+     * `volumes` to `false`.
+     * @throws {InvalidMethodAcceptException} When the options are invalid.
+     * @throws {DockerRequestException} When the daemon refuses a prune (one already running: HTTP 409).
+     */
+    prune(options?: DockerPruneOptions): Promise<void>;
+    /**
+     * Check credentials against a registry, as `docker login` does. The credentials are not kept: each pull, build or
+     * push which needs them is given its own `auth`.
+     * @param options The registry (`serverAddress`, a host name without protocol: `registry.example.com:5000`) and its
+     * credentials (a password, or a token).
+     * @throws {DockerRequestException} When the registry refuses the credentials or cannot be reached (the daemon's
+     * status: HTTP 401, 500).
+     */
+    loginRepository(options: DockerAuthOptions): Promise<void>;
+    /**
+     * Whether a registry accepts credentials ({@link Docker.loginRepository} without its error).
+     * @param options The registry (`serverAddress`, a host name without protocol) and its credentials.
+     * @returns `true` when they are accepted; `false` on any failure, the daemon unreachable included.
+     */
+    checkRepositoryAuth(options: DockerAuthOptions): Promise<boolean>;
+    /** Docker Image Operations **/
+    /**
+     * List the daemon's images (as `docker images`, without the intermediate ones). Each image is inspected with a request
+     * of its own, so the call costs one request per image; an image removed during the listing is not listed.
+     * @returns The images, in the daemon's order.
+     */
+    listImages(): Promise<DockerImage[]>;
+    /**
+     * Pull an image from its registry, as `docker pull`, and wait for its end.
+     * @param options The repository (`alpine`, `registry.example.com:5000/team/app`), the tag (`'latest'` by default),
+     * the platform (`linux/arm64`, the daemon's by default), the registry credentials, and a callback receiving each
+     * progress message.
+     * @returns The image pulled, found as `repo:tag` the way the daemon names it (`docker.io/library/alpine` is
+     * `alpine`).
+     * @throws {DockerImagePullException} 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 then says it was aborted).
+     */
+    pullImage(options: ImagePullOptions): Promise<DockerImage>;
+    /**
+     * Build an image with BuildKit, as `docker build`, and wait for its end. The build context is made of the `files`
+     * of the `workdir` (relative paths; a directory with its content), without the ones its `.dockerignore` excludes,
+     * and always with the Dockerfile. The progress is given to the output callback as the lines of
+     * `docker build --progress=plain` (`{id: 'moby.buildkit.trace', stream: '#2 [1/2] FROM alpine'}`).
+     *
+     * With `auth`, the base images of the Dockerfile (its `FROM` lines) are pulled first with these credentials, as
+     * BuildKit is not given them.
+     * @param options The context (`workdir`, `files`), the Dockerfile, the name of the image (`repoTag`; a generated
+     * `unnamed_img_…` name by default), the platform, the target stage, the build arguments, the registry credentials
+     * and the output callback.
+     * @returns The image built.
+     * @throws {DockerImageBuildException} When the build fails: a step failing, the Dockerfile or a file of the context
+     * missing, a base image which cannot be pulled, the daemon unreachable, or the component destroyed during the build
+     * (its message then says it was aborted).
+     */
+    buildImage(options: ImageBuildOptions): Promise<DockerImage>;
+    /**
+     * Load an image from a tar archive written by `docker save` (or {@link DockerImage.export}), as `docker load`. The
+     * tags saved in the archive are restored.
+     * @param options The archive (`source`, a file path or a readable stream) and `quiet` (`false` by default).
+     * @returns The image loaded.
+     * @throws {DockerImageImportException} When the daemon rejects the archive, or when the loaded image is unknown.
+     * @throws {Error} The error of the source when it cannot be read (`ENOENT` for a missing file), or the network
+     * error when the archive cannot be sent.
+     * @throws {DockerRequestException} When the daemon refuses the request.
+     */
+    importImage(options: ImageImportOptions): Promise<DockerImage>;
+    /**
+     * Get an image by its ID or its name, resolved by the daemon as `docker image inspect` does: the full ID
+     * (`sha256:…`), a unique prefix of it (`d9e853e8`), a tag (`alpine:3.20`), a name without its tag for `:latest`
+     * (`alpine`), a name with its registry (`docker.io/library/alpine:3.20`) or a digest (`alpine@sha256:…`).
+     * @param repoTagOrId The ID, the short ID, the name or the digest of the image.
+     * @returns The image.
+     * @throws {DockerImageNotFoundException} When the daemon finds no image with this ID or name.
+     */
+    getImage(repoTagOrId: string): Promise<DockerImage>;
+    /** Docker Container Operations **/
+    /**
+     * List the daemon's containers, the stopped ones included (as `docker ps -a`). Each container is inspected, with its
+     * image (see {@link Docker.getContainer}); a container removed during the listing is not listed.
+     * @returns The containers; an empty list when the component is destroyed during the call.
+     */
+    listContainers(): Promise<DockerContainer[]>;
+    /**
+     * Get a container by its ID, short ID or name, inspected with its image (`image` is `undefined` when its image no
+     * longer exists, removed with force). The object is a snapshot: its properties are refreshed by its own operations
+     * (`start()`, `stop()`…), not by the changes made by others.
+     * @param id The ID, a unique prefix of it, or the name of the container.
+     * @returns The container.
+     * @throws {DockerContainerNotFoundException} When the daemon has no such container.
+     */
+    getContainer(id: string): Promise<DockerContainer>;
+    /**
+     * Create a container from an image, as `docker create`: it is not started (see {@link DockerContainer.start}, or
+     * {@link DockerImage.run} to create and start it).
+     * @param imageId The ID or the name (`alpine:3.20`) of a local image: it is not pulled.
+     * @param options The container's settings: name, command, environment, ports, binds, devices, networks, limits…
+     * @returns The container created.
+     * @throws {DockerImageNotFoundException} When the image is not found.
+     * @throws {DockerNetworkNotFoundException} When a network of the settings is not found.
+     * @throws {DockerRequestException} When the daemon refuses the settings: the name already used (HTTP 409), an
+     * invalid setting (HTTP 400).
+     * @throws {InvalidMethodAcceptException} When the settings are invalid.
+     */
+    createContainer(imageId: string, options: ContainerSettingOptions): Promise<DockerContainer>;
+    /**
+     * Create a container from an image for a platform, as `docker create --platform`: it is not started.
+     * @param imageId The ID or the name (`alpine:3.20`) of a local image: it is not pulled.
+     * @param platform The platform of the image used (`linux/arm64`), for an image having several.
+     * @param options The container's settings: name, command, environment, ports, binds, devices, networks, limits…
+     * @returns The container created.
+     * @throws {DockerImageNotFoundException} When the image is not found for the platform.
+     * @throws {DockerNetworkNotFoundException} When a network of the settings is not found.
+     * @throws {DockerRequestException} When the daemon refuses the settings: the name already used (HTTP 409), an
+     * invalid setting (HTTP 400).
+     * @throws {InvalidMethodAcceptException} When the settings are invalid.
+     */
+    createContainer(imageId: string, platform: string, options: ContainerSettingOptions): Promise<DockerContainer>;
+    /** Docker Network Operations **/
+    /**
+     * Create a network, as `docker network create`.
+     * @param options The name, the driver (`'bridge'` by default, `'ipvlan'`, `'macvlan'`), its options, the subnets
+     * (`NetworkIPAMConfigs`; chosen by the daemon when empty or absent), `internal` and `enableIPv6`.
+     * @returns The network created.
+     * @throws {DockerRequestException} When the daemon refuses the network: the name already used (HTTP 409), a subnet
+     * overlapping another network's (HTTP 400).
+     */
+    createNetwork(options: NetworkCreateOptions): Promise<NetworkInfo>;
+    /**
+     * Remove a network, as `docker network rm`.
+     * @param id The ID, a unique prefix of it, or the name of the network.
+     * @throws {DockerNetworkNotFoundException} When the daemon has no such network.
+     * @throws {DockerRequestException} When the network has containers connected (HTTP 409), or is reserved (`bridge`,
+     * `host`, `none`: HTTP 403).
+     */
+    removeNetwork(id: string): Promise<void>;
+    /**
+     * List the daemon's networks, the reserved ones (`bridge`, `host`, `none`) included.
+     * @returns The networks; an empty list when the component is destroyed during the call.
+     */
+    listNetworks(): Promise<NetworkInfo[]>;
+    /**
+     * Get a network by its ID, a unique prefix of it, or its name, as `docker network inspect`.
+     * @param id The ID, a unique prefix of it, or the name of the network.
+     * @returns The network.
+     * @throws {DockerNetworkNotFoundException} When the daemon has no such network.
+     */
+    getNetwork(id: string): Promise<NetworkInfo>;
+}

package/dist/types/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/types/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/types/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/types/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/types/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/types/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/types/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/types/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/types/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/types/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/types/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/types/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;
+}