@lakutata/containerd 0.0.0-stage → 3.0.0-beta.1

package/dist/cjs/containerd/lib/ContainerdContainer.d.ts

@@ -0,0 +1,292 @@
+import { Provider } from '@lakutata/core';
+import { Time } from '@lakutata/utils/Time';
+import type { Readable } from 'node:stream';
+import { type Message } from '@lakutata/grpc';
+import { ContainerStore } from '../../client/ContainerStore.js';
+import type { ContainerdClient } from '../../client/ContainerdClient.js';
+import { type Containerd } from '../Containerd.js';
+import { type ContainerdImage } from './ContainerdImage.js';
+import type { ContainerdContainerState } from '../types/ContainerdContainerState.js';
+import type { ContainerdRestartPolicy } from '../types/ContainerdRestartPolicy.js';
+import type { ContainerdExecResult } from '../types/ContainerdExecResult.js';
+import type { ContainerdContainerNetwork } from '../types/ContainerdContainerNetwork.js';
+import type { ContainerdContainerPort } from '../types/ContainerdContainerPort.js';
+import { ContainerStopOptions } from '../options/container/ContainerStopOptions.js';
+import { ContainerKillOptions } from '../options/container/ContainerKillOptions.js';
+import { ContainerRemoveOptions } from '../options/container/ContainerRemoveOptions.js';
+import { ContainerExecOptions } from '../options/container/ContainerExecOptions.js';
+import { ContainerLogsOptions } from '../options/container/ContainerLogsOptions.js';
+import { ContainerdContainerTTY } from './ContainerdContainerTTY.js';
+import { ContainerTTYOptions } from '../options/container/ContainerTTYOptions.js';
+import { ContainerCommitOptions } from '../options/container/ContainerCommitOptions.js';
+import { ContainerExportDirectoryOptions } from '../options/container/ContainerExportDirectoryOptions.js';
+import type { ContainerCreateOptions } from '../options/container/ContainerCreateOptions.js';
+import type { ContainerdContainerStats } from '../types/ContainerdContainerStats.js';
+/**
+ * A container of the {@link Containerd} component's namespace, with the operations of a Docker container: start, stop,
+ * kill, pause, exec, terminals, logs, stats, live updates or updates by recreation, commit and file export. Get it from
+ * {@link Containerd.getContainer}, {@link Containerd.listContainers} or {@link Containerd.createContainer}; do not create
+ * it yourself. Each call returns a new object (transient).
+ *
+ * Its properties are a snapshot taken when it was obtained: the operations changing the container (`start()`, `stop()`,
+ * `kill()`, `pause()`, `wait()`, `update()`…) take a new one when they end, and {@link ContainerdContainer.syncContainerInfo}
+ * takes one on demand. The state the container is in decides what works: `exec()`, `createTTY()` and `stats()` need it
+ * running, and `remove()` refuses a running container unless forced.
+ * @example
+ * ```typescript
+ * import {Containerd, type ContainerdContainer, type ContainerdContainerStats} from 'lakutata/com/containerd'
+ *
+ * declare const containerd: Containerd
+ *
+ * const container: ContainerdContainer = await containerd.getContainer('worker')
+ * if (!container.state.running) await container.start()
+ * //The last 100 lines, without following the output
+ * for await (const chunk of await container.logs({tail: 100, follow: false})) process.stdout.write(chunk)
+ * const stats: ContainerdContainerStats = await container.stats()
+ * console.log(stats.cpu.percent, stats.memory.usage)
+ * //Live, without a restart
+ * await container.update({memoryLimit: 256 * 1024 * 1024})
+ * //Its stop signal, then SIGKILL after 5 seconds
+ * await container.stop({timeout: 5})
+ * await container.remove()
+ * ```
+ */
+export declare class ContainerdContainer extends Provider {
+    #private;
+    /**
+     * Gives the component's container store; set by the component.
+     */
+    protected readonly getStore: () => ContainerStore;
+    /**
+     * Gives the component's containerd client; set by the component.
+     */
+    protected readonly getClient: () => ContainerdClient;
+    /**
+     * Gives the component that created the object.
+     */
+    protected readonly getContainerd: () => Containerd;
+    /**
+     * The container's identifier (64 hexadecimal characters). The name or identifier prefix the object was asked with is
+     * resolved to it; it changes when {@link ContainerdContainer.update} creates the container again.
+     */
+    id: string;
+    /**
+     * The container's name (nerdctl's `nerdctl/name` label); its identifier when it has none.
+     */
+    name: string;
+    /**
+     * The container's hostname; empty for the containers created without nerdctl's labels.
+     */
+    hostname: string;
+    /**
+     * The name of the container's image (`docker.io/library/alpine:3.20`).
+     */
+    imageName: string;
+    /**
+     * The platform of the image the container runs (`linux/arm64/v8`); empty when unknown.
+     */
+    platform: string;
+    /**
+     * The container's labels: the ones given at its creation, its image's, and nerdctl's (`nerdctl/*`).
+     */
+    labels: Record<string, string>;
+    /**
+     * The container's restart policy, applied by containerd's restart monitor; `'no'` when it has none.
+     */
+    restartPolicy: ContainerdRestartPolicy;
+    /**
+     * The container's state when the snapshot was taken: its status, its process identifier, its last exit code, and
+     * when it started and finished.
+     */
+    state: ContainerdContainerState;
+    /**
+     * The networks the container joins: `['host']`, `['none']`, or the names of its CNI networks.
+     */
+    networkNames: string[];
+    /**
+     * The container's interfaces on its CNI networks (`eth0`, `eth1`…), with their addresses while it runs.
+     */
+    networks: ContainerdContainerNetwork[];
+    /**
+     * The container's ports published on the host, through its first CNI network.
+     */
+    ports: ContainerdContainerPort[];
+    /**
+     * The names of the named volumes the container mounts.
+     */
+    volumes: string[];
+    /**
+     * When the container was created.
+     */
+    createdAt: Time;
+    /**
+     * The container's record in containerd, as last read.
+     * @protected
+     */
+    protected record: Message;
+    /**
+     * Read the container's information.
+     * @throws {ContainerdContainerNotFoundException} No container matches the identifier or name.
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * End the log streams followed and the waits of the object.
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * Read the container's information and state again from containerd into the object's properties.
+     * @throws {ContainerdContainerNotFoundException} The container no longer exists.
+     */
+    syncContainerInfo(): Promise<void>;
+    /**
+     * Run an operation on the container, then read its information again (also when the operation fails).
+     * @param operation The operation, given the container's record.
+     * @returns What the operation returns.
+     * @throws {ContainerdContainerStateException} The container is not in the state the operation needs.
+     * @protected
+     */
+    protected operate<T>(operation: (record: Message) => Promise<T>): Promise<T>;
+    /**
+     * Get the container's image.
+     * @returns The image.
+     * @throws {ContainerdImageNotFoundException} The image was removed since the container was created.
+     */
+    image(): Promise<ContainerdImage>;
+    /**
+     * Start the container: a new task of its root file system, its output appended to its log file (rotated first beyond
+     * the component's `logMaxSize`), its CNI networks set up. Its restart policy applies from now on. A running container
+     * is left as it is.
+     * @throws {ContainerdContainerStateException} The container is paused: unpause it.
+     * @throws {Error} The task cannot be created or started (the command is not found, seccomp refuses it…).
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the container: send its stop signal (the one of `options`, else its `stopSignal`, else `SIGTERM`), wait for it
+     * to exit, then kill all its processes with `SIGKILL` when the timeout ends. Its exit code is kept, and the restart
+     * monitor no longer restarts it. A paused container is resumed first; a stopped one is left as it is.
+     * @param options The time to wait in seconds (10 by default) and the signal.
+     */
+    stop(options?: ContainerStopOptions): Promise<void>;
+    /**
+     * Restart the container: stop it as {@link ContainerdContainer.stop} does, then start it.
+     * @param options How it is stopped: the time to wait in seconds (10 by default) and the signal.
+     * @throws {Error} The task cannot be started again.
+     */
+    restart(options?: ContainerStopOptions): Promise<void>;
+    /**
+     * Send a signal to the container's main process, or to all its processes. `SIGKILL` also tells the restart monitor
+     * not to restart it; other signals do not.
+     * @param options The signal (`SIGKILL` by default; a name or a number) and `all`.
+     * @throws {ContainerdContainerStateException} The container is not running.
+     */
+    kill(options?: ContainerKillOptions): Promise<void>;
+    /**
+     * Pause all the processes of the running container (cgroup freezer).
+     * @throws {ContainerdContainerStateException} The container is not running.
+     */
+    pause(): Promise<void>;
+    /**
+     * Resume the processes of the paused container.
+     * @throws {ContainerdContainerStateException} The container is not running.
+     */
+    unpause(): Promise<void>;
+    /**
+     * Wait for the container's main process to exit, as `docker wait` does. A container that is not running resolves at
+     * once: with the exit code of its last run when it exited or was stopped by {@link ContainerdContainer.stop}, with
+     * `0` when it was never started (or when the component did not keep its exit code: a container created by nerdctl
+     * or by another `dataRoot`). The wait ends with an error when the object is destroyed.
+     * @returns The exit code.
+     * @throws {GRPCError} The wait was aborted (from `@lakutata/grpc`, its `code` is `CANCELLED`).
+     */
+    wait(): Promise<number>;
+    /**
+     * Remove the container: its task, its CNI network interfaces, its record, its snapshot and its state directory (its
+     * logs included). The named volumes it mounts are kept. With `force`, a running or paused container is killed first.
+     * @param options `force` (false by default).
+     * @throws {ContainerdContainerStateException} The container is running and `force` is not set.
+     */
+    remove(options?: ContainerRemoveOptions): Promise<void>;
+    /**
+     * Run a command in the running container and wait for it to exit, its outputs captured in memory. The process gets
+     * the container's environment (with `env` added), working directory and user unless given. Its standard output and
+     * error are kept apart through FIFOs (`mkfifo` of the host); without `mkfifo`, both are in `stdout`.
+     * @param options The command (a string is run by `/bin/sh -c`, an array as is), `env`, `workingDir`, `user` (`name`,
+     * `uid`, `name:group`), `stdin` (written then closed) and `timeout` (milliseconds, then the process is killed with
+     * `SIGKILL`).
+     * @returns The exit code and the outputs; a command killed by its timeout resolves with exit code `137`.
+     * @throws {ContainerdContainerStateException} The container is not running (stopped or paused).
+     * @throws {Error} `stdin` is given and the host has no `mkfifo`; the user is not found in the container.
+     */
+    exec(options: ContainerExecOptions): Promise<ContainerdExecResult>;
+    /**
+     * Read the container's logs: its standard output and error interleaved in one stream, without timestamps, from its
+     * log file (and the previous rotated file). By default the stream follows the new output while the container runs
+     * (or is being restarted by the restart monitor), and ends once it stopped or when the object is destroyed.
+     * @param options `tail`, the number of last lines to start with (all by default), and `follow` (true by default).
+     * @returns A readable stream of buffers.
+     */
+    logs(options?: ContainerLogsOptions): Promise<Readable>;
+    /**
+     * Read the resources the running or paused container uses: its cgroup counters and its network interface counters,
+     * sampled twice to compute its CPU use over the interval.
+     * @param interval The time between the two samples, in milliseconds; `0` takes one sample and reports a CPU use of
+     * 0. 1000 by default.
+     * @returns The counters of the last sample, with the CPU use over the interval.
+     * @throws {ContainerdContainerStateException} The container is not running.
+     */
+    stats(interval?: number): Promise<ContainerdContainerStats>;
+    /**
+     * Open an interactive terminal in the running container: a process with a pseudo terminal (`TERM=xterm`), its input
+     * and output through FIFOs (`mkfifo` of the host). Close it with {@link ContainerdContainerTTY.close} when done.
+     * @param options The command (a string is run by `/bin/sh -c` as {@link ContainerdContainer.exec} runs it, an array
+     * as is; `['/bin/sh']` by default, so the image needs a shell), the initial console size, `env`, `workingDir` and
+     * `user`.
+     * @returns The terminal, its process started.
+     * @throws {ContainerdContainerStateException} The container is not running.
+     * @throws {Error} The host has no `mkfifo`; the user is not found in the container.
+     */
+    createTTY(options?: ContainerTTYOptions): Promise<ContainerdContainerTTY>;
+    /**
+     * Update the container's settings. When only resources and the restart policy change (`memoryLimit`, `memorySwap`,
+     * `cpus`, `cpuShares`, `cpuSet`, `pidsLimit`, `OOMKillDisable`, `restartPolicy`), they are applied live, without a
+     * restart, as `docker update` does: `0` (`[]` for `cpuSet`) removes a limit, from the running container too, and from
+     * the settings it is created again with ({@link ContainerResourceOptions}). Any other setting creates the container
+     * again with its creation settings and the changes: a new container with the same name (and a new identifier, which
+     * this object follows), started when the old one was running; the old one is removed. The recreation only works for
+     * the containers created by the component, whose settings it kept.
+     * @param options The settings to change, as {@link Containerd.createContainer} takes them.
+     * @throws {InvalidValueException} A live update gives a `memorySwap` (positive) to a container without a memory
+     * limit, or leaves its `memorySwap` below its `memoryLimit` (from `@lakutata/core`).
+     * @throws {ContainerdContainerStateException} The container must be created again but was not created by the
+     * component (nerdctl's, or created by another `dataRoot`).
+     * @throws {ContainerdImageNotFoundException} From the recreation, as {@link Containerd.createContainer} throws.
+     */
+    update(options: Partial<ContainerCreateOptions>): Promise<void>;
+    /**
+     * Commit the container: save the changes of its root file system (not its mounts) as a new layer on its image,
+     * with configuration changes, as `docker commit` does. A running container is paused meanwhile by default.
+     * @param options The name of the new image (`<registry>/<repository>:commit-<milliseconds>` of the container's image
+     * by default), `pauseBeforeCommitting` (true by default), the configuration `changes`, `comment` and `author`.
+     * @returns The new image.
+     * @throws {ContainerdImageNotFoundException} The container's image was removed.
+     */
+    commit(options?: ContainerCommitOptions): Promise<ContainerdImage>;
+    /**
+     * Copy a file or directory of the container out as a tar archive, as `docker cp` does: from the running process's
+     * file system (its mounts included), or from its root file system when it is not running (without its mounts). The
+     * symbolic links of the path are resolved inside the container; the devices, sockets and pipes are not archived.
+     * @param options The absolute path in the container, and the destination (a file path, created or replaced, or a
+     * writable stream).
+     * @throws {ContainerdPathNotFoundException} The path does not exist in the container.
+     * @throws {Error} The archive cannot be written.
+     */
+    exportDirectory(options: ContainerExportDirectoryOptions): Promise<void>;
+    /**
+     * List the processes of the running container.
+     * @returns Their process identifiers on the host.
+     * @throws {ContainerdContainerStateException} The container is not running.
+     */
+    processes(): Promise<number[]>;
+}