@lakutata/docker 3.0.0-beta.0

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