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

package/dist/cjs/containerd/types/ContainerdContainerPort.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A container port published on the host ({@link ContainerdContainer.ports}), with every host port forwarding to it.
+ * It is read from the container's nerdctl labels, so the containers created by nerdctl report theirs too.
+ */
+export type ContainerdContainerPort = {
+    /**
+     * The host address the ports listen on; `'0.0.0.0'` for all of them.
+     */
+    host: string;
+    /**
+     * The port in the container.
+     */
+    port: number;
+    /**
+     * The protocol of the port.
+     */
+    type: 'tcp' | 'udp' | 'sctp';
+    /**
+     * The host ports forwarding to it.
+     */
+    hostPorts: number[];
+};

package/dist/cjs/containerd/types/ContainerdContainerPort.js

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

package/dist/cjs/containerd/types/ContainerdContainerState.d.ts

@@ -0,0 +1,42 @@
+import type { Time } from '@lakutata/utils/Time';
+/**
+ * The state of a container ({@link ContainerdContainer.state}): the one of its task (its main process in containerd)
+ * and of its last run. It is read when the container object is obtained and after each of its operations;
+ * `syncContainerInfo()` reads it again.
+ */
+export type ContainerdContainerState = {
+    /**
+     * Its status: `'created'` never started; `'running'`; `'paused'`, or `'pausing'` while it is being paused;
+     * `'restarting'` stopped while containerd's restart monitor is to start it again (its restart policy);
+     * `'exited'` its process ended; `'unknown'` a task status containerd reports and the component does not know.
+     */
+    status: 'created' | 'running' | 'paused' | 'pausing' | 'restarting' | 'exited' | 'unknown';
+    /**
+     * Whether its process runs (`status` is `'running'`); `false` while it is paused.
+     */
+    running: boolean;
+    /**
+     * Whether it is paused (`status` is `'paused'`).
+     */
+    paused: boolean;
+    /**
+     * Whether its restart monitor is restarting it (`status` is `'restarting'`).
+     */
+    restarting: boolean;
+    /**
+     * The host process ID of its main process, `0` when it has no task.
+     */
+    pid: number;
+    /**
+     * The exit code of its last run, `0` before its first exit.
+     */
+    exitCode: number;
+    /**
+     * When it was last started, `null` when it never was.
+     */
+    startedAt: Time | null;
+    /**
+     * When its last run ended, `null` while it runs after a start and when it never ended.
+     */
+    finishedAt: Time | null;
+};

package/dist/cjs/containerd/types/ContainerdContainerState.js

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

package/dist/cjs/containerd/types/ContainerdContainerStats.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The resources a running (or paused) container uses ({@link ContainerdContainer.stats}): its cgroup counters (cgroup
+ * v1 or v2), read twice an interval apart to compute its CPU use, and its network interface counters. The counters are
+ * cumulative since the container started, except `cpu.percent`.
+ */
+export type ContainerdContainerStats = {
+    /**
+     * When the last sample was read.
+     */
+    read: Date;
+    /**
+     * Its processes: `current`, the processes (and threads) it has; `limit`, the most it may have, `0` when it has no
+     * limit.
+     */
+    pids: {
+        current: number;
+        limit: number;
+    };
+    /**
+     * Its CPU use; the times are in nanoseconds.
+     */
+    cpu: {
+        /**
+         * Its total CPU time in nanoseconds, in user mode and in kernel mode.
+         */
+        usage: number;
+        /**
+         * Its CPU time in user mode, in nanoseconds.
+         */
+        user: number;
+        /**
+         * Its CPU time in kernel mode, in nanoseconds.
+         */
+        system: number;
+        /**
+         * The CFS periods it was throttled in (by its `cpus` limit).
+         */
+        throttledPeriods: number;
+        /**
+         * The time it was throttled, in nanoseconds.
+         */
+        throttledTime: number;
+        /**
+         * The CPUs of the host (on cgroup v1, the ones its cgroup reports).
+         */
+        onlineCpus: number;
+        /**
+         * Its CPU use during the sampling interval, in percent of one CPU: `100` is one CPU used all the time, `200`
+         * two of them. `0` when the interval is `0`.
+         */
+        percent: number;
+    };
+    /**
+     * Its memory use, in bytes.
+     */
+    memory: {
+        /**
+         * The memory it uses, page cache included, in bytes.
+         */
+        usage: number;
+        /**
+         * Its usage without the inactive page cache the kernel can reclaim, in bytes (the figure `docker stats`
+         * shows).
+         */
+        workingSet: number;
+        /**
+         * Its memory limit in bytes; the host's total memory when it has none.
+         */
+        limit: number;
+        /**
+         * Its page cache (file-backed memory), in bytes.
+         */
+        cache: number;
+        /**
+         * The swap it uses, in bytes.
+         */
+        swap: number;
+        /**
+         * How many times the kernel's OOM killer killed one of its processes.
+         */
+        oomKills: number;
+    };
+    /**
+     * Its block device I/O, summed over the devices: the bytes read and written, the read and write operations.
+     */
+    blkio: {
+        readBytes: number;
+        writeBytes: number;
+        readOps: number;
+        writeOps: number;
+    };
+    /**
+     * The counters of its network interfaces by name (`eth0`), loopback excluded: the bytes, packets, errors and
+     * dropped packets received (`rx…`) and sent (`tx…`). On the host network, they are the host's interfaces; empty
+     * when its process is gone.
+     */
+    networks: Record<string, {
+        rxBytes: number;
+        rxPackets: number;
+        rxErrors: number;
+        rxDropped: number;
+        txBytes: number;
+        txPackets: number;
+        txErrors: number;
+        txDropped: number;
+    }>;
+};

package/dist/cjs/containerd/types/ContainerdContainerStats.js

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

package/dist/cjs/containerd/types/ContainerdDevice.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A host device given to a container ({@link ContainerCreateOptions.devices}): its device node created in the
+ * container, and its access allowed by the container's device cgroup. Unlike the Docker component's device,
+ * `containerPath` is optional and `hostPath` may be a directory.
+ */
+export type ContainerdDevice = {
+    /**
+     * The device node on the host (`/dev/ttyUSB0`), or a directory whose device nodes are all given (`/dev/snd`), the
+     * subdirectories included and the other files skipped. A path which is neither fails the creation of the
+     * container. The devices are read when the container is created: a device plugged later needs
+     * {@link ContainerCreateOptions.deviceCgroupRules} and a bind mount of its directory.
+     */
+    hostPath: string;
+    /**
+     * The path of the device node in the container (for a directory, the directory its nodes are created in).
+     * @default hostPath
+     */
+    containerPath?: string;
+    /**
+     * The access the cgroup allows: one to three of `r` (read), `w` (write) and `m` (mknod), each at most once, in any
+     * order: `"rwm"`, `"rw"`, `"r"`.
+     * @default 'rwm'
+     */
+    cgroupPermissions?: string;
+};

package/dist/cjs/containerd/types/ContainerdDevice.js

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

package/dist/cjs/containerd/types/ContainerdExecResult.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The result of a command executed in a running container ({@link ContainerdContainer.exec}). The outputs are decoded
+ * as UTF-8 and held in memory.
+ */
+export type ContainerdExecResult = {
+    /**
+     * The exit code of the command (`137` when it was killed by its `timeout`).
+     */
+    exitCode: number;
+    /**
+     * Its standard output. Without `mkfifo` on the host, its standard error is in it too.
+     */
+    stdout: string;
+    /**
+     * Its standard error; `''` without `mkfifo` on the host (it is in `stdout`).
+     */
+    stderr: string;
+};

package/dist/cjs/containerd/types/ContainerdExecResult.js

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

package/dist/cjs/containerd/types/ContainerdImageConfig.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The configuration an image gives its containers ({@link ContainerdImage.config}), read from the OCI image
+ * configuration of the platform the image object describes. A {@link ContainerCreateOptions} overrides its fields.
+ */
+export type ContainerdImageConfig = {
+    /**
+     * Its environment variables by name (`{PATH: '/usr/local/sbin:…'}`).
+     */
+    env: Record<string, string>;
+    /**
+     * Its default command (`CMD`), `[]` when it has none.
+     */
+    cmd: string[];
+    /**
+     * Its entry point (`ENTRYPOINT`), `[]` when it has none.
+     */
+    entrypoint: string[];
+    /**
+     * The working directory of its process (`WORKDIR`), `''` when it has none (`/` is used).
+     */
+    workingDir: string;
+    /**
+     * The user of its process (`USER`: `user`, `user:group`, `uid`, `uid:gid`), `''` when it has none (root).
+     */
+    user: string;
+    /**
+     * The ports it declares (`EXPOSE`), the protocol `'tcp'` when the image gives none. They are not published by
+     * themselves: see {@link ContainerCreateOptions.ports}.
+     */
+    exposedPorts: {
+        port: number;
+        type: 'tcp' | 'udp' | 'sctp';
+    }[];
+    /**
+     * The paths it declares as volumes (`VOLUME`). The component mounts no volume for them by itself.
+     */
+    volumes: string[];
+    /**
+     * The labels of its configuration (`LABEL`), copied to its containers.
+     */
+    labels: Record<string, string>;
+    /**
+     * The signal stopping its containers (`STOPSIGNAL`: `'SIGQUIT'`), undefined when it has none (`SIGTERM` is used).
+     */
+    stopSignal?: string;
+};

package/dist/cjs/containerd/types/ContainerdImageConfig.js

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

package/dist/cjs/containerd/types/ContainerdNetworkInfo.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A network containers can join ({@link Containerd.listNetworks}, {@link Containerd.getNetwork}): `host` and `none`,
+ * and the CNI networks of the component's CNI configuration directory (the nerdctl ones, as `nerdctl network ls` lists
+ * them, and the other configuration lists there).
+ */
+export type ContainerdNetworkInfo = {
+    /**
+     * Its ID: `'host'` and `'none'` for those, the 64 hexadecimal digits nerdctl gives a CNI network.
+     */
+    id: string;
+    /**
+     * Its name, the one the containers give in {@link ContainerCreateOptions.networks}.
+     */
+    name: string;
+    /**
+     * Its main CNI plugin (`'bridge'`, `'macvlan'`, `'ipvlan'`…); `'host'` and `'none'` for those networks.
+     */
+    driver: string;
+    /**
+     * Whether the component cannot remove it: `host`, `none`, the default nerdctl network (`bridge`), and the CNI
+     * configurations not written by nerdctl or the component (their files not named `nerdctl-*.conflist`).
+     */
+    reserved: boolean;
+    /**
+     * Whether it is cut from the outside: a bridge network without the host's gateway and masquerading, and `none`.
+     */
+    internal: boolean;
+    /**
+     * Whether it has an IPv6 subnet.
+     */
+    enableIPv6: boolean;
+    /**
+     * Its subnets in CIDR notation (`'10.4.1.0/24'`, `'fd00:4:10::/64'`), `[]` for `host` and `none`.
+     */
+    subnets: string[];
+    /**
+     * The gateways of its subnets (`'10.4.1.1'`).
+     */
+    gateways: string[];
+    /**
+     * Its labels (the ones given to {@link NetworkCreateOptions.labels}, and the `nerdctl/…` ones).
+     */
+    labels: Record<string, string>;
+    /**
+     * The path of its CNI configuration list (`/etc/cni/net.d/nerdctl-backend.conflist`); undefined for `host` and
+     * `none`.
+     */
+    file?: string;
+};

package/dist/cjs/containerd/types/ContainerdNetworkInfo.js

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

package/dist/cjs/containerd/types/ContainerdProgressCallback.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The progress of a blob transfer (a layer, a configuration, a manifest) during a pull or a push, given to a
+ * {@link ContainerdProgressCallback}.
+ */
+export type ContainerdProgress = {
+    /**
+     * The digest of the blob (`'sha256:…'`).
+     */
+    digest: string;
+    /**
+     * Its media type (`'application/vnd.oci.image.layer.v1.tar+gzip'`).
+     */
+    mediaType: string;
+    /**
+     * The bytes transferred so far.
+     */
+    current: number;
+    /**
+     * The size of the blob in bytes; `current` equals it once it is transferred.
+     */
+    total: number;
+};
+/**
+ * Receive the progress of a pull ({@link ImagePullOptions.progressCallback}) or a push
+ * ({@link ImagePushOptions.progressCallback}). A pull calls it as each blob's bytes arrive, and once with `current`
+ * equal to `total` for a blob the content store has already; a push calls it once per blob, after its upload, with
+ * `current` equal to `total`.
+ */
+export type ContainerdProgressCallback = (progress: ContainerdProgress) => void;

package/dist/cjs/containerd/types/ContainerdProgressCallback.js

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

package/dist/cjs/containerd/types/ContainerdPruneResult.d.ts

@@ -0,0 +1,21 @@
+/**
+ * What {@link Containerd.prune} removed. A resource whose removal failed is not listed.
+ */
+export type ContainerdPruneResult = {
+    /**
+     * The IDs of the containers removed.
+     */
+    containers: string[];
+    /**
+     * The names of the images removed (`'docker.io/library/alpine:3.20'`, or a digest reference for a dangling one).
+     */
+    images: string[];
+    /**
+     * The names of the networks removed.
+     */
+    networks: string[];
+    /**
+     * The names of the volumes removed, their data deleted.
+     */
+    volumes: string[];
+};

package/dist/cjs/containerd/types/ContainerdPruneResult.js

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

package/dist/cjs/containerd/types/ContainerdRestartPolicy.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The restart policy of a container ({@link ContainerCreateOptions.restartPolicy}), applied by containerd's restart
+ * monitor (its `io.containerd.internal.v1.restart` plugin, which checks the containers periodically, every 10 seconds
+ * by default), so it works without the application running:
+ * - `''` or `'no'`: never restart it;
+ * - `'always'`: restart it whenever it stops, until it is stopped through the component (`stop()`, `kill()` with
+ *   `SIGKILL`, `remove()`);
+ * - `'unless-stopped'`: the same as `'always'` with this component, which stops a container the same way for both;
+ * - `'on-failure'`: restart it when it exits with a non-zero code; `'on-failure:N'` at most N times.
+ *
+ * Unlike the Docker component's policy, `'on-failure:N'` is accepted.
+ */
+export type ContainerdRestartPolicy = '' | 'no' | 'always' | 'unless-stopped' | 'on-failure' | `on-failure:${number}`;

package/dist/cjs/containerd/types/ContainerdRestartPolicy.js

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

package/dist/cjs/containerd/types/ContainerdTmpfs.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A tmpfs (a file system in memory, lost when the container stops) mounted into a container
+ * ({@link ContainerCreateOptions.tmpfs}), with the mount options `nosuid`, `nodev` and `noexec`.
+ */
+export type ContainerdTmpfs = {
+    /**
+     * The absolute path in the container where it is mounted.
+     */
+    containerPath: string;
+    /**
+     * Its maximum size in bytes, a positive integer; the kernel's default (half of the host memory) when not given.
+     * Its pages count in the container's memory use.
+     */
+    size?: number;
+    /**
+     * The permissions of its root directory, three or four octal digits (`'1777'`, `'755'`); the kernel's default
+     * (`1777`) when not given.
+     */
+    mode?: string;
+};

package/dist/cjs/containerd/types/ContainerdTmpfs.js

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

package/dist/cjs/containerd/types/ContainerdVolume.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A named volume mounted into a container ({@link ContainerCreateOptions.volumes}): a directory the component keeps in
+ * its data root, which outlives the container. It is not a nerdctl volume.
+ */
+export type ContainerdVolume = {
+    /**
+     * The name of the volume (`[a-zA-Z0-9][a-zA-Z0-9_.-]*`), created empty when it does not exist.
+     */
+    volumeName: string;
+    /**
+     * The absolute path in the container where it is mounted.
+     */
+    containerPath: string;
+    /**
+     * Whether it is mounted read only.
+     * @default false
+     */
+    readonly?: boolean;
+};

package/dist/cjs/containerd/types/ContainerdVolume.js

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

package/dist/cjs/containerd/types/ContainerdVolumeInfo.d.ts

@@ -0,0 +1,26 @@
+import type { Time } from '@lakutata/utils/Time';
+/**
+ * A named volume of the component ({@link Containerd.listVolumes}, {@link Containerd.getVolume},
+ * {@link Containerd.createVolume}): a directory of the host in the component's data root, kept per containerd
+ * namespace.
+ */
+export type ContainerdVolumeInfo = {
+    /**
+     * Its name.
+     */
+    name: string;
+    /**
+     * The host directory holding its data and mounted into the containers:
+     * `<dataRoot>/volumes/<namespace>/<name>/_data` (`/var/lib/lakutata/containerd/volumes/default/<name>/_data`
+     * by default).
+     */
+    mountpoint: string;
+    /**
+     * The labels it was created with.
+     */
+    labels: Record<string, string>;
+    /**
+     * When it was created.
+     */
+    createdAt: Time;
+};

package/dist/cjs/containerd/types/ContainerdVolumeInfo.js

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

package/dist/cjs/exports/Containerd.d.ts

@@ -0,0 +1,69 @@
+export * from '../containerd/Containerd.js';
+/**
+ * Lib
+ */
+export * from '../containerd/lib/ContainerdContainer.js';
+export * from '../containerd/lib/ContainerdContainerTTY.js';
+export * from '../containerd/lib/ContainerdImage.js';
+/**
+ * Types
+ */
+export * from '../containerd/types/ContainerdBind.js';
+export * from '../containerd/types/ContainerdBuildOutputCallback.js';
+export * from '../containerd/types/ContainerdContainerNetwork.js';
+export * from '../containerd/types/ContainerdContainerPort.js';
+export * from '../containerd/types/ContainerdContainerState.js';
+export * from '../containerd/types/ContainerdContainerStats.js';
+export * from '../containerd/types/ContainerdDevice.js';
+export * from '../containerd/types/ContainerdExecResult.js';
+export * from '../containerd/types/ContainerdImageConfig.js';
+export * from '../containerd/types/ContainerdNetworkInfo.js';
+export * from '../containerd/types/ContainerdPruneResult.js';
+export * from '../containerd/types/ContainerdVolume.js';
+export * from '../containerd/types/ContainerdVolumeInfo.js';
+export * from '../containerd/types/ContainerdProgressCallback.js';
+export * from '../containerd/types/ContainerdRestartPolicy.js';
+export * from '../containerd/types/ContainerdTmpfs.js';
+export type { ContainerdEvent } from '../client/ContainerdClient.js';
+/**
+ * Options
+ */
+export * from '../containerd/options/ContainerdPruneOptions.js';
+export * from '../containerd/options/ContainerdRegistryAuthOptions.js';
+export * from '../containerd/options/container/ContainerCommitOptions.js';
+export * from '../containerd/options/container/ContainerCreateOptions.js';
+export * from '../containerd/options/container/ContainerExecOptions.js';
+export * from '../containerd/options/container/ContainerKillOptions.js';
+export * from '../containerd/options/container/ContainerLogsOptions.js';
+export * from '../containerd/options/container/ContainerRemoveOptions.js';
+export * from '../containerd/options/container/ContainerExportDirectoryOptions.js';
+export * from '../containerd/options/container/ContainerResourceOptions.js';
+export * from '../containerd/options/container/ContainerTTYConsoleSizeOptions.js';
+export * from '../containerd/options/container/ContainerTTYOptions.js';
+export * from '../containerd/options/container/ContainerStopOptions.js';
+export * from '../containerd/options/image/ImageBuildOptions.js';
+export * from '../containerd/options/image/ImageExportOptions.js';
+export * from '../containerd/options/image/ImageImportOptions.js';
+export * from '../containerd/options/image/ImagePullOptions.js';
+export * from '../containerd/options/image/ImagePushOptions.js';
+export * from '../containerd/options/network/NetworkCreateOptions.js';
+export * from '../containerd/options/volume/VolumeCreateOptions.js';
+/**
+ * Exceptions
+ */
+export * from '../containerd/exceptions/ContainerdConnectionException.js';
+export * from '../containerd/exceptions/ContainerdContainerNameConflictException.js';
+export * from '../containerd/exceptions/ContainerdContainerNotFoundException.js';
+export * from '../containerd/exceptions/ContainerdContainerStateException.js';
+export * from '../containerd/exceptions/ContainerdImageBuildException.js';
+export * from '../containerd/exceptions/ContainerdImageExportException.js';
+export * from '../containerd/exceptions/ContainerdImageImportException.js';
+export * from '../containerd/exceptions/ContainerdImageNotFoundException.js';
+export * from '../containerd/exceptions/ContainerdImagePullException.js';
+export * from '../containerd/exceptions/ContainerdImagePushException.js';
+export * from '../containerd/exceptions/ContainerdNetworkConflictException.js';
+export * from '../containerd/exceptions/ContainerdNetworkNotFoundException.js';
+export * from '../containerd/exceptions/ContainerdPathNotFoundException.js';
+export * from '../containerd/exceptions/ContainerdPlatformException.js';
+export * from '../containerd/exceptions/ContainerdVolumeInUseException.js';
+export * from '../containerd/exceptions/ContainerdVolumeNotFoundException.js';