@lakutata/docker 3.0.0-beta.0

package/dist/cjs/docker/lib/DockerContainer.d.ts

@@ -0,0 +1,315 @@
+import { Provider } from '@lakutata/core';
+import type { DockerClient } from '../../client/DockerClient.js';
+import { Time } from '@lakutata/utils/Time';
+import { ContainerState } from '../types/ContainerState.js';
+import { type Docker } from '../Docker.js';
+import { type DockerImage } from './DockerImage.js';
+import { ContainerNetwork } from '../types/ContainerNetwork.js';
+import { ContainerPort } from '../types/ContainerPort.js';
+import { ContainerBind } from '../types/ContainerBind.js';
+import { ContainerDevice } from '../types/ContainerDevice.js';
+import { ContainerStopOptions } from '../options/container/ContainerStopOptions.js';
+import { ContainerRemoveOptions } from '../options/container/ContainerRemoveOptions.js';
+import { ContainerSettingOptions } from '../options/container/ContainerSettingOptions.js';
+import { ContainerRestartPolicy } from '../types/ContainerRestartPolicy.js';
+import { type ContainerExecResult } from '../types/ContainerExecResult.js';
+import { ContainerKillOptions } from '../options/container/ContainerKillOptions.js';
+import { ContainerCommitOptions } from '../options/container/ContainerCommitOptions.js';
+import { ContainerCapability } from '../types/ContainerCapability.js';
+import { DockerContainerTTY } from './DockerContainerTTY.js';
+import { ContainerCreateTTYOptions } from '../options/container/ContainerCreateTTYOptions.js';
+import { ContainerLogsOptions } from '../options/container/ContainerLogsOptions.js';
+import { ContainerStats } from '../types/ContainerStats.js';
+import { ContainerExecOptions } from '../options/container/ContainerExecOptions.js';
+import { ContainerExportDirectoryOptions } from '../options/container/ContainerExportDirectoryOptions.js';
+/**
+ * A container of the Docker daemon, with its settings and its state as inspected, and its operations: start, stop,
+ * restart, pause, kill, remove, update, commit, exec, TTYs, logs, stats and the export of its files. It is not created
+ * with `new`: {@link Docker.getContainer}, {@link Docker.listContainers}, {@link Docker.createContainer} and
+ * {@link DockerImage.run} return it.
+ *
+ * Its properties are a snapshot, taken when it is obtained and refreshed by its own operations (`start()`, `stop()`,
+ * `restart()`, `pause()`, `unpause()`, `kill()`, `update()`): the changes made by others (the container exiting,
+ * `docker stop`) are seen by getting it again. Its operations reject with {@link DockerContainerNotFoundException} when
+ * the container was removed, with {@link DockerRequestException} when the daemon refuses them otherwise (not running:
+ * HTTP 409), and with the network error of Node.js when the daemon cannot be reached.
+ * @example
+ * ```typescript
+ * import {type Docker, type DockerContainer, type DockerImage} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const image: DockerImage = await docker.getImage('alpine:3.20')
+ * const container: DockerContainer = await docker.createContainer(image.id, {
+ *     name: 'worker',
+ *     cmd: ['sh', '-c', 'echo started; sleep 3600'],
+ *     env: {MODE: 'production'},
+ *     ports: [{port: 8080, type: 'tcp', hostPorts: [18080]}],
+ *     binds: [{hostPath: '/srv/data', containerPath: '/data', rw: true}],
+ *     restartPolicy: 'unless-stopped'
+ * })
+ * await container.start()
+ * console.log(container.state.status, container.ports)
+ * //The exit code, stdout and stderr
+ * const {exitCode, stdout} = await container.exec({cmd: ['ls', '/data']})
+ * console.log(exitCode, stdout)
+ * await container.stop({timeout: 10})
+ * await container.remove()
+ * ```
+ */
+export declare class DockerContainer extends Provider {
+    #private;
+    /**
+     * Give the client of the Engine API: set by the {@link Docker} component creating the object.
+     */
+    protected readonly getClient: () => DockerClient;
+    /**
+     * Give the {@link Docker} component which created the object.
+     */
+    protected readonly getDocker: () => Docker;
+    /**
+     * The full ID of the container (64 hexadecimal characters). It changes when {@link DockerContainer.update}
+     * recreates the container.
+     */
+    id: string;
+    /**
+     * The name of the container, without the leading `/` of the Engine API.
+     */
+    name: string;
+    /**
+     * The host name of the container (its short ID unless set when it was created).
+     */
+    hostname: string;
+    /**
+     * The image the container was created from; `undefined` when it no longer exists (removed with force while the
+     * container was stopped).
+     */
+    image: DockerImage | undefined;
+    /**
+     * How many times the daemon restarted the container, by its restart policy.
+     */
+    restartCount: number;
+    /**
+     * Whether the container has full access to the host (`--privileged`).
+     */
+    privileged: boolean;
+    /**
+     * Whether the container's main process has a TTY: its logs are then raw, not split into stdout and stderr.
+     */
+    tty: boolean;
+    /**
+     * The environment variables of the container, the image's included, by name.
+     */
+    env: Record<string, string>;
+    /**
+     * The memory limit of the container, in bytes; `0` for no limit.
+     */
+    memoryLimit: number;
+    /**
+     * The indexes of the CPUs the container may run on, sorted; empty for all of them.
+     */
+    cpuSet: number[];
+    /**
+     * When the daemon restarts the container after it exits (`'no'` by default; `'on-failure:3'` for 3 retries at
+     * most).
+     */
+    restartPolicy: ContainerRestartPolicy;
+    /**
+     * Whether the OOM killer is disabled for the container.
+     */
+    OOMKillDisable: boolean;
+    /**
+     * The kernel capabilities added to the container (`--cap-add`).
+     */
+    capabilities: ContainerCapability[];
+    /**
+     * The state of the container: its status (`'created'`, `'running'`, `'exited'`…), its process ID, its exit code
+     * and its start and finish times.
+     */
+    state: ContainerState;
+    /**
+     * The ports of the container, exposed by its image or published: one entry per IP address of the container, port
+     * and protocol, with the ports of the host published to it, each one once (empty when not published).
+     */
+    ports: ContainerPort[];
+    /**
+     * The directories and files of the host mounted in the container (the bind mounts; not the volumes).
+     */
+    binds: ContainerBind[];
+    /**
+     * The devices of the host added to the container.
+     */
+    devices: ContainerDevice[];
+    /**
+     * The networks the container is connected to, with its addresses in each.
+     */
+    networks: ContainerNetwork[];
+    /**
+     * The cgroup the container joins (`container:<name|id>`), as the daemon reports it (an empty string by default).
+     */
+    cgroup: string | undefined;
+    /**
+     * The parent cgroup under which the container's cgroup is created (an empty string by default).
+     */
+    cgroupParent: string | undefined;
+    /**
+     * The PID namespace mode of the container: `'host'`, `'container:<name|id>'`, or an empty string for its own.
+     */
+    pidMode: string | undefined;
+    /**
+     * When the container was created.
+     */
+    createdAt: Time;
+    /**
+     * Inspect the container.
+     * @throws {DockerContainerNotFoundException} When the container does not exist.
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * Abort the requests in progress of the object (the container itself is left as it is).
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * Refresh the properties from the daemon's inspection of the container, and its image (`undefined` when it no longer
+     * exists).
+     * @throws {DockerContainerNotFoundException} When the container does not exist.
+     * @protected
+     */
+    protected syncContainerInfo(): Promise<void>;
+    /**
+     * Start the container, as `docker start`, then refresh its properties. A container already running is left as it is
+     * (as the Docker CLI does).
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     * @throws {DockerRequestException} When it fails to start (HTTP 500: a command not found, a port already used).
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the container, as `docker stop`: send its stop signal, wait for it to exit, kill it after the timeout; then
+     * refresh its properties.
+     * @param options The signal sent (the container's stop signal, `SIGTERM` by default) and the timeout before the kill,
+     * in seconds (the container's, 10 by default). A container already stopped is left as it is (as the Docker CLI does).
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     */
+    stop(options?: ContainerStopOptions): Promise<void>;
+    /**
+     * Suspend the processes of the container, as `docker pause`, then refresh its properties.
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     * @throws {DockerRequestException} When it is not running or already paused (HTTP 409).
+     */
+    pause(): Promise<void>;
+    /**
+     * Resume the processes of a paused container, as `docker unpause`, then refresh its properties.
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     * @throws {DockerRequestException} When it is not paused (HTTP 409).
+     */
+    unpause(): Promise<void>;
+    /**
+     * Restart the container, as `docker restart`: stop it as {@link DockerContainer.stop} does (when it runs), then start
+     * it; then refresh its properties.
+     * @param options The signal sent (the container's stop signal, `SIGTERM` by default) and the timeout before the kill,
+     * in seconds (the container's, 10 by default).
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     * @throws {DockerRequestException} When it fails to start (HTTP 500).
+     */
+    restart(options?: ContainerStopOptions): Promise<void>;
+    /**
+     * Remove the container, as `docker rm -v`: its anonymous volumes are removed with it. The object is not refreshed:
+     * its other operations then fail with {@link DockerContainerNotFoundException}.
+     * @param options `force` kills a running container first (`false` by default).
+     * @throws {DockerContainerNotFoundException} When the container was already removed.
+     * @throws {DockerRequestException} When it is running and `force` is not set (HTTP 409).
+     */
+    remove(options?: ContainerRemoveOptions): Promise<void>;
+    /**
+     * Change the settings of the container, keeping the others. The memory limit, the CPUs and the restart policy are
+     * changed live, as `docker update` does, and the name by renaming it, the container running on. The other
+     * settings (and removing the memory limit or the CPU set, which Docker cannot do live) recreate the container: a new
+     * one is created from the old one's whole configuration (its image, command, entrypoint, environment, mounts,
+     * networks and their static addresses, the addresses Docker assigned being assigned again), with the settings
+     * changed, under a temporary name. Once created (and, when the old one was running, the old one stopped and the new
+     * one started), the old one is removed without its volumes and the new one takes its name (and its anonymous
+     * volumes, mounted again). The object follows the new container: its `id` changes.
+     * @remarks The old container is kept when the creation or the start of the new one fails (invalid settings, the
+     * image removed, a network missing): the new one is removed, the old one started again when it was running, and the
+     * call rejects. Its files outside the volumes are not kept by a recreation (commit them first, see
+     * {@link DockerContainer.commit}). A container removed by Docker when it stops (`AutoRemove`) cannot be kept.
+     * @param options The settings changed: `memoryLimit`, `cpuSet` and `restartPolicy` live (the swap limit set to
+     * Docker's default with the memory), `name` by a renaming; `hostname`, `env` (replacing the container's variables;
+     * the image's are added again), `cmd`, `entrypoint`, `tty`, `privileged`, `ports`, `binds` (replacing the bind
+     * mounts, the volumes kept), `devices`, `networks` (replacing the networks), `capabilities`, `OOMKillDisable`,
+     * `cgroup`, `cgroupParent` and `pidMode` by a recreation. The settings absent are kept.
+     * @throws {InvalidMethodAcceptException} When the settings are invalid.
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     * @throws {DockerImageNotFoundException} When the container must be recreated and its image no longer exists.
+     * @throws {DockerNetworkNotFoundException} When a network of the settings is not found.
+     * @throws {DockerRequestException} When the daemon refuses the changes: a limit refused (HTTP 400), the name
+     * already used (HTTP 409), the new container failing to start (HTTP 500).
+     */
+    update(options: ContainerSettingOptions): Promise<void>;
+    /**
+     * Create an image from the container's current files, as `docker commit`.
+     * @param options The name of the image (`repoTag`, `repo:tag`; none by default) and whether the container is paused
+     * while it is committed (`pauseBeforeCommitting`, `true` by default).
+     * @returns The image created.
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     */
+    commit(options?: ContainerCommitOptions): Promise<DockerImage>;
+    /**
+     * Start an interactive command with a TTY in the running container, as `docker exec -it`. The command runs until it
+     * exits (or its stream is closed): see {@link DockerContainerTTY}.
+     * @param options The command (`['/bin/sh']` by default; the program and its arguments, run as they are, or a command
+     * line, run by `/bin/sh -c`) and the initial console size.
+     * @returns The TTY, its command started.
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     * @throws {DockerRequestException} When the container is not running (HTTP 409).
+     */
+    createTTY(options?: ContainerCreateTTYOptions): Promise<DockerContainerTTY>;
+    /**
+     * Read the logs of the container's main process, as `docker logs`: stdout and stderr in one stream, in their order
+     * (split from Docker's multiplexed format unless the container has a TTY).
+     * @remarks The logs are followed by default: the stream does not end while the container runs. Pass `follow: false`
+     * for the logs written so far.
+     * @param options `follow` (`true` by default), `since` and `until` (UNIX timestamps in seconds; `0`, no bound, by
+     * default), `timestamps` (`false` by default) and `tail` (a number of lines from the end; all by default).
+     * @returns The readable stream of the logs.
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     */
+    logs(options?: ContainerLogsOptions): Promise<NodeJS.ReadableStream>;
+    /**
+     * Read the resource usage of the container once, as `docker stats --no-stream`: CPU, memory, network, block I/O and
+     * processes, as the Engine API reports them.
+     * @returns The statistics.
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     */
+    stats(): Promise<ContainerStats>;
+    /**
+     * Run a command in the running container, as `docker exec` (no TTY, no stdin), and wait for it to exit. As the
+     * containerd component's, a command exiting with a non-zero code resolves too: check its `exitCode`.
+     * @param options The command: a program and its arguments (`['ls', '-l']`), run as they are, or a command line
+     * (`'ls /data | wc -l'`), run by `/bin/sh -c`.
+     * @returns The exit code of the command, its stdout and its stderr (a program not found: exit code `127` or `126`,
+     * the error in the output).
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     * @throws {DockerRequestException} When the container is not running or paused (HTTP 409).
+     */
+    exec(options: ContainerExecOptions): Promise<ContainerExecResult>;
+    /**
+     * Send a signal to the container's main process, as `docker kill` (`SIGKILL` by default), then refresh its properties.
+     * @param options The signal sent: a name (`'SIGHUP'`) or a number (`1`); `SIGKILL` by default.
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     * @throws {DockerRequestException} When the container is not running (HTTP 409), or the signal is unknown.
+     */
+    kill(options?: ContainerKillOptions): Promise<void>;
+    /**
+     * Copy a file or a directory out of the container as a tar archive, as `docker cp container:path -`. The container
+     * may be stopped.
+     * @param options The path in the container, and the `destination` of the archive: a file path (created or
+     * overwritten) or a writable stream (ended after the archive).
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     * @throws {DockerRequestException} When the path is not found in the container (HTTP 404).
+     * @throws {Error} The error of the destination.
+     */
+    exportDirectory(options: ContainerExportDirectoryOptions): Promise<void>;
+}