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

package/dist/cjs/containerd/lib/ContainerdContainer.js

@@ -0,0 +1,536 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContainerdContainer = void 0;
+const core_1 = require("@lakutata/core");
+const di_1 = require("@lakutata/core/decorator/di");
+const dto_1 = require("@lakutata/core/decorator/dto");
+const Time_1 = require("@lakutata/utils/Time");
+const node_fs_1 = require("node:fs");
+const ContainerStore_js_1 = require("../../client/ContainerStore.js");
+const ContainerStopOptions_js_1 = require("../options/container/ContainerStopOptions.js");
+const ContainerKillOptions_js_1 = require("../options/container/ContainerKillOptions.js");
+const ContainerRemoveOptions_js_1 = require("../options/container/ContainerRemoveOptions.js");
+const ContainerExecOptions_js_1 = require("../options/container/ContainerExecOptions.js");
+const ContainerLogsOptions_js_1 = require("../options/container/ContainerLogsOptions.js");
+const ContainerdContainerNotFoundException_js_1 = require("../exceptions/ContainerdContainerNotFoundException.js");
+const ContainerdErrors_js_1 = require("./ContainerdErrors.js");
+const ContainerdContainerTTY_js_1 = require("./ContainerdContainerTTY.js");
+const ContainerTTYOptions_js_1 = require("../options/container/ContainerTTYOptions.js");
+const ContainerResourceOptions_js_1 = require("../options/container/ContainerResourceOptions.js");
+const ContainerCommitOptions_js_1 = require("../options/container/ContainerCommitOptions.js");
+const ContainerExportDirectoryOptions_js_1 = require("../options/container/ContainerExportDirectoryOptions.js");
+const ContainerdContainerStateException_js_1 = require("../exceptions/ContainerdContainerStateException.js");
+const Reference_js_1 = require("../../client/Reference.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()
+ * ```
+ */
+let ContainerdContainer = class ContainerdContainer extends core_1.Provider {
+    #abortController = new AbortController();
+    /**
+     * Read the container's information.
+     * @throws {ContainerdContainerNotFoundException} No container matches the identifier or name.
+     * @protected
+     */
+    async init() {
+        await this.syncContainerInfo();
+    }
+    /**
+     * End the log streams followed and the waits of the object.
+     * @protected
+     */
+    async destroy() {
+        this.#abortController.abort();
+    }
+    /**
+     * Read the container's information and state again from containerd into the object's properties.
+     * @throws {ContainerdContainerNotFoundException} The container no longer exists.
+     */
+    async syncContainerInfo() {
+        const record = await this.getStore().find(this.id);
+        if (!record)
+            throw new ContainerdContainerNotFoundException_js_1.ContainerdContainerNotFoundException(`The container ${this.id} does not exist`);
+        this.record = record;
+        this.id = record.id;
+        this.labels = record.labels ?? {};
+        this.name = ContainerStore_js_1.ContainerStore.Name(record);
+        this.hostname = this.labels[ContainerStore_js_1.ContainerLabels.HOSTNAME] ?? '';
+        this.imageName = record.image ?? '';
+        this.platform = this.labels[ContainerStore_js_1.ContainerLabels.PLATFORM] ?? '';
+        this.restartPolicy = (this.labels[ContainerStore_js_1.ContainerLabels.RESTART_POLICY] ?? 'no');
+        this.createdAt = new Time_1.Time(record.createdAt ? Number(record.createdAt.seconds ?? 0) * 1000 : Date.now());
+        try {
+            this.networkNames = JSON.parse(this.labels[ContainerStore_js_1.ContainerLabels.NETWORKS] ?? '[]');
+        }
+        catch {
+            this.networkNames = [];
+        }
+        this.networks = (await this.getStore().interfaces(record)).map((item) => ({
+            networkName: item.network,
+            interface: item.interface,
+            mac: item.mac ?? '',
+            ip: item.ip ?? '',
+            gateway: item.gateway ?? '',
+            ipPrefixLen: item.prefixLength ?? 0,
+            ipv6: item.ipv6 ?? '',
+            ipv6Gateway: item.ipv6Gateway ?? ''
+        }));
+        const ports = new Map();
+        try {
+            for (const port of JSON.parse(this.labels[ContainerStore_js_1.ContainerLabels.PORTS] ?? '[]')) {
+                const key = `${port.HostIP}/${port.ContainerPort}/${port.Protocol}`;
+                const known = ports.get(key) ?? { host: port.HostIP, port: port.ContainerPort, type: port.Protocol, hostPorts: [] };
+                known.hostPorts.push(port.HostPort);
+                ports.set(key, known);
+            }
+        }
+        catch {
+            //Not the labels of nerdctl
+        }
+        this.ports = [...ports.values()];
+        this.volumes = ContainerStore_js_1.ContainerStore.Volumes(record);
+        const state = await this.getStore().state(record);
+        this.state = {
+            status: state.status,
+            running: state.running,
+            paused: state.paused,
+            restarting: state.status === 'restarting',
+            pid: state.pid,
+            exitCode: state.exitCode,
+            startedAt: state.startedAt ? new Time_1.Time(state.startedAt) : null,
+            finishedAt: state.finishedAt ? new Time_1.Time(state.finishedAt) : null
+        };
+    }
+    /**
+     * 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
+     */
+    async operate(operation) {
+        try {
+            return await operation(this.record);
+        }
+        catch (error) {
+            throw (0, ContainerdErrors_js_1.containerdError)(error);
+        }
+        finally {
+            await this.syncContainerInfo().catch(() => undefined);
+        }
+    }
+    /**
+     * Get the container's image.
+     * @returns The image.
+     * @throws {ContainerdImageNotFoundException} The image was removed since the container was created.
+     */
+    async image() {
+        return await this.getContainerd().getImage(this.imageName);
+    }
+    /**
+     * 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…).
+     */
+    async start() {
+        await this.operate((record) => this.getStore().start(record));
+    }
+    /**
+     * 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.
+     */
+    async stop(options) {
+        if (!options)
+            return await this.stop({});
+        await this.operate((record) => this.getStore().stop(record, { timeout: options.timeout, signal: options.signal }));
+    }
+    /**
+     * 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.
+     */
+    async restart(options) {
+        if (!options)
+            return await this.restart({});
+        await this.stop(options);
+        await this.start();
+    }
+    /**
+     * 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.
+     */
+    async kill(options) {
+        if (!options)
+            return await this.kill({});
+        await this.operate((record) => this.getStore().kill(record, options.signal, options.all));
+    }
+    /**
+     * Pause all the processes of the running container (cgroup freezer).
+     * @throws {ContainerdContainerStateException} The container is not running.
+     */
+    async pause() {
+        await this.operate((record) => this.getStore().pause(record));
+    }
+    /**
+     * Resume the processes of the paused container.
+     * @throws {ContainerdContainerStateException} The container is not running.
+     */
+    async unpause() {
+        await this.operate((record) => this.getStore().resume(record));
+    }
+    /**
+     * 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`).
+     */
+    async wait() {
+        try {
+            return await this.getStore().wait(this.record, this.#abortController.signal);
+        }
+        catch (error) {
+            throw (0, ContainerdErrors_js_1.containerdError)(error);
+        }
+        finally {
+            await this.syncContainerInfo().catch(() => undefined);
+        }
+    }
+    /**
+     * 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.
+     */
+    async remove(options) {
+        if (!options)
+            return await this.remove({});
+        try {
+            await this.getStore().remove(this.record, !!options.force);
+        }
+        catch (error) {
+            throw (0, ContainerdErrors_js_1.containerdError)(error);
+        }
+    }
+    /**
+     * 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.
+     */
+    async exec(options) {
+        try {
+            return await this.getStore().exec(this.record, {
+                cmd: typeof options.cmd === 'string' ? ['/bin/sh', '-c', options.cmd] : options.cmd,
+                env: options.env,
+                workingDir: options.workingDir,
+                user: options.user,
+                stdin: options.stdin,
+                timeout: options.timeout
+            });
+        }
+        catch (error) {
+            throw (0, ContainerdErrors_js_1.containerdError)(error);
+        }
+    }
+    /**
+     * 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.
+     */
+    async logs(options) {
+        if (!options)
+            return await this.logs({});
+        return this.getStore().logs(this.record, { tail: options.tail, follow: options.follow, signal: this.#abortController.signal });
+    }
+    /**
+     * 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.
+     */
+    async stats(interval = 1000) {
+        try {
+            return await this.getStore().stats(this.record, interval);
+        }
+        catch (error) {
+            throw (0, ContainerdErrors_js_1.containerdError)(error);
+        }
+    }
+    /**
+     * 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.
+     */
+    async createTTY(options) {
+        return await this.getObject(ContainerdContainerTTY_js_1.ContainerdContainerTTY, {
+            getStore: this.getStore,
+            getRecord: () => this.record,
+            cmd: options?.cmd ?? ['/bin/sh'],
+            initialConsoleSize: options?.consoleSize,
+            env: options?.env,
+            workingDir: options?.workingDir,
+            user: options?.user
+        });
+    }
+    /**
+     * 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.
+     */
+    async update(options) {
+        const keys = Object.keys(options).filter((key) => options[key] !== undefined);
+        const resourceKeys = ['memoryLimit', 'memorySwap', 'cpus', 'cpuShares', 'cpuSet', 'pidsLimit', 'OOMKillDisable', 'restartPolicy'];
+        if (keys.every((key) => resourceKeys.includes(key))) {
+            const resources = ContainerResourceOptions_js_1.ContainerResourceOptions.validate(options);
+            await this.operate((record) => this.getStore().updateResources(record, {
+                memory: resources.memoryLimit,
+                memorySwap: resources.memorySwap,
+                cpus: resources.cpus,
+                cpuShares: resources.cpuShares,
+                cpuset: resources.cpuSet?.join(','),
+                pidsLimit: resources.pidsLimit,
+                oomKillDisable: resources.OOMKillDisable,
+                restart: resources.restartPolicy
+            }));
+            //Kept by its settings: the ones it is created again with, a limit removed (0, []) not kept
+            const current = await this.getStore().readSettings(this.id);
+            if (!current)
+                return;
+            const settings = { ...current, ...Object.fromEntries(keys.map((key) => [key, options[key]])) };
+            if (!settings.memoryLimit)
+                delete settings.memoryLimit;
+            //No swap limit: unlimited swap with a memory limit (twice the memory without memorySwap)
+            if (!settings.memoryLimit)
+                delete settings.memorySwap;
+            else if (settings.memorySwap === 0)
+                settings.memorySwap = -1;
+            for (const key of ['cpus', 'cpuShares', 'pidsLimit'])
+                if (!settings[key])
+                    delete settings[key];
+            if (!settings.cpuSet?.length)
+                delete settings.cpuSet;
+            await this.getStore().writeSettings(this.id, settings);
+            return;
+        }
+        const settings = await this.getStore().readSettings(this.id);
+        if (!settings)
+            throw new ContainerdContainerStateException_js_1.ContainerdContainerStateException(`The container ${this.name} was not created by the component (its settings are unknown): create it again`);
+        this.id = (await this.getContainerd().recreateContainer(this.record, { ...settings, ...options, name: options.name ?? this.name })).id;
+        await this.syncContainerInfo();
+    }
+    /**
+     * 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.
+     */
+    async commit(options) {
+        if (!options)
+            return await this.commit({});
+        let name;
+        if (options.repoTag) {
+            name = options.repoTag;
+        }
+        else {
+            const reference = (0, Reference_js_1.parseReference)(this.imageName);
+            name = `${reference.registry}/${reference.repository}:commit-${Date.now()}`;
+        }
+        try {
+            name = await this.getStore().commit(this.record, {
+                name: name,
+                pause: options.pauseBeforeCommitting,
+                changes: options.changes ? { ...options.changes, env: options.changes.env ? Object.entries(options.changes.env).map(([key, value]) => `${key}=${value}`) : undefined } : undefined,
+                comment: options.comment,
+                author: options.author
+            });
+        }
+        catch (error) {
+            throw (0, ContainerdErrors_js_1.containerdError)(error);
+        }
+        return await this.getContainerd().getImage(name);
+    }
+    /**
+     * 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.
+     */
+    async exportDirectory(options) {
+        try {
+            await this.getStore().archive(this.record, options.path, typeof options.destination === 'string' ? (0, node_fs_1.createWriteStream)(options.destination) : options.destination);
+        }
+        catch (error) {
+            throw (0, ContainerdErrors_js_1.containerdError)(error);
+        }
+    }
+    /**
+     * List the processes of the running container.
+     * @returns Their process identifiers on the host.
+     * @throws {ContainerdContainerStateException} The container is not running.
+     */
+    async processes() {
+        try {
+            return await this.getStore().processes(this.record);
+        }
+        catch (error) {
+            throw (0, ContainerdErrors_js_1.containerdError)(error);
+        }
+    }
+};
+exports.ContainerdContainer = ContainerdContainer;
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Function()),
+    __metadata("design:type", Function)
+], ContainerdContainer.prototype, "getStore", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Function()),
+    __metadata("design:type", Function)
+], ContainerdContainer.prototype, "getClient", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Function()),
+    __metadata("design:type", Function)
+], ContainerdContainer.prototype, "getContainerd", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.String()),
+    __metadata("design:type", String)
+], ContainerdContainer.prototype, "id", void 0);
+__decorate([
+    (0, dto_1.Accept)(ContainerStopOptions_js_1.ContainerStopOptions.optional()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [ContainerStopOptions_js_1.ContainerStopOptions]),
+    __metadata("design:returntype", Promise)
+], ContainerdContainer.prototype, "stop", null);
+__decorate([
+    (0, dto_1.Accept)(ContainerStopOptions_js_1.ContainerStopOptions.optional()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [ContainerStopOptions_js_1.ContainerStopOptions]),
+    __metadata("design:returntype", Promise)
+], ContainerdContainer.prototype, "restart", null);
+__decorate([
+    (0, dto_1.Accept)(ContainerKillOptions_js_1.ContainerKillOptions.optional()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [ContainerKillOptions_js_1.ContainerKillOptions]),
+    __metadata("design:returntype", Promise)
+], ContainerdContainer.prototype, "kill", null);
+__decorate([
+    (0, dto_1.Accept)(ContainerRemoveOptions_js_1.ContainerRemoveOptions.optional()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [ContainerRemoveOptions_js_1.ContainerRemoveOptions]),
+    __metadata("design:returntype", Promise)
+], ContainerdContainer.prototype, "remove", null);
+__decorate([
+    (0, dto_1.Accept)(ContainerExecOptions_js_1.ContainerExecOptions.required()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [ContainerExecOptions_js_1.ContainerExecOptions]),
+    __metadata("design:returntype", Promise)
+], ContainerdContainer.prototype, "exec", null);
+__decorate([
+    (0, dto_1.Accept)(ContainerLogsOptions_js_1.ContainerLogsOptions.optional()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [ContainerLogsOptions_js_1.ContainerLogsOptions]),
+    __metadata("design:returntype", Promise)
+], ContainerdContainer.prototype, "logs", null);
+__decorate([
+    (0, dto_1.Accept)(core_1.DTO.Number().integer().min(0).optional()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number]),
+    __metadata("design:returntype", Promise)
+], ContainerdContainer.prototype, "stats", null);
+__decorate([
+    (0, dto_1.Accept)(ContainerTTYOptions_js_1.ContainerTTYOptions.optional()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [ContainerTTYOptions_js_1.ContainerTTYOptions]),
+    __metadata("design:returntype", Promise)
+], ContainerdContainer.prototype, "createTTY", null);
+__decorate([
+    (0, dto_1.Accept)(core_1.DTO.Object().required()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], ContainerdContainer.prototype, "update", null);
+__decorate([
+    (0, dto_1.Accept)(ContainerCommitOptions_js_1.ContainerCommitOptions.optional()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [ContainerCommitOptions_js_1.ContainerCommitOptions]),
+    __metadata("design:returntype", Promise)
+], ContainerdContainer.prototype, "commit", null);
+__decorate([
+    (0, dto_1.Accept)(ContainerExportDirectoryOptions_js_1.ContainerExportDirectoryOptions.required()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [ContainerExportDirectoryOptions_js_1.ContainerExportDirectoryOptions]),
+    __metadata("design:returntype", Promise)
+], ContainerdContainer.prototype, "exportDirectory", null);
+exports.ContainerdContainer = ContainerdContainer = __decorate([
+    (0, di_1.Transient)()
+], ContainerdContainer);

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

@@ -0,0 +1,116 @@
+import { Provider } from '@lakutata/core';
+import { Duplex, type Readable, type Writable } from 'node:stream';
+import { type Message } from '@lakutata/grpc';
+import type { ContainerStore } from '../../client/ContainerStore.js';
+import { ContainerTTYConsoleSizeOptions } from '../options/container/ContainerTTYConsoleSizeOptions.js';
+/**
+ * An interactive terminal in a running container: a process (a shell by default) run with a pseudo terminal, as
+ * `docker exec -it` does. Get it from {@link ContainerdContainer.createTTY}; do not create it yourself. Write its input
+ * with {@link ContainerdContainerTTY.write} (or {@link ContainerdContainerTTY.writable}), read its output with
+ * {@link ContainerdContainerTTY.onData} (or {@link ContainerdContainerTTY.readable}), or pipe a socket into
+ * {@link ContainerdContainerTTY.raw}. The terminal ends when its process exits or when it is closed; it is closed when
+ * the object is destroyed.
+ * @example
+ * ```typescript
+ * import {type Containerd, type ContainerdContainer, type ContainerdContainerTTY} from 'lakutata/com/containerd'
+ *
+ * declare const containerd: Containerd
+ *
+ * const container: ContainerdContainer = await containerd.getContainer('worker')
+ * const tty: ContainerdContainerTTY = await container.createTTY({cmd: ['/bin/sh', '-l'], consoleSize: {cols: 120, rows: 40}})
+ * tty.onData((chunk: Buffer): void => {
+ *     process.stdout.write(chunk)
+ * })
+ * tty.write('ls -la\n')
+ * await tty.resize({cols: 100, rows: 30})
+ * tty.write('exit\n')
+ * //The exit code of the shell
+ * console.log(await tty.wait())
+ * ```
+ */
+export declare class ContainerdContainerTTY extends Provider {
+    #private;
+    /**
+     * Gives the component's container store; set by the container.
+     */
+    protected readonly getStore: () => ContainerStore;
+    /**
+     * Gives the container's record in containerd; set by the container.
+     */
+    protected readonly getRecord: () => Message;
+    /**
+     * The command run in the terminal: a command line run by `/bin/sh -c`, or an executable and its arguments.
+     */
+    protected readonly cmd: string | string[];
+    /**
+     * The console size the terminal starts with, in columns and rows.
+     * @default the runtime's default size
+     */
+    protected readonly initialConsoleSize?: ContainerTTYConsoleSizeOptions;
+    /**
+     * The environment variables added to the container's (`TERM` is `xterm` unless given).
+     * @default none
+     */
+    protected readonly env?: Record<string, string>;
+    /**
+     * The working directory of the process.
+     * @default the container's working directory
+     */
+    protected readonly workingDir?: string;
+    /**
+     * The user running the process (`name`, `uid`, `name:group`), looked up in the container's `/etc/passwd`.
+     * @default the container's user
+     */
+    protected readonly user?: string;
+    /**
+     * Start the terminal's process in the container.
+     * @throws {ContainerdContainerStateException} The container is not running.
+     * @throws {Error} The host has no `mkfifo`; the user is not found in the container.
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * Close the terminal, as {@link ContainerdContainerTTY.close} does.
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * The terminal as one duplex stream: writing sends input to the process, reading gives its output (to pipe a
+     * WebSocket or a socket into it). It is created at the first access and consumes the output from then on.
+     */
+    get raw(): Duplex;
+    /**
+     * The terminal's input: what is written is sent to the process, as typed on a keyboard (`\x03` for Ctrl+C).
+     */
+    get writable(): Writable;
+    /**
+     * The terminal's output: what the process prints, its standard error included; it ends when the process exits.
+     */
+    get readable(): Readable;
+    /**
+     * Resize the terminal's console; the process receives `SIGWINCH`.
+     * @param options The new size, in columns and rows (positive integers).
+     * @throws {GRPCError} The process has exited (from `@lakutata/grpc`).
+     */
+    resize(options: ContainerTTYConsoleSizeOptions): Promise<void>;
+    /**
+     * Listen to the terminal's output. Each call adds a listener.
+     * @param handler Called with each chunk of output.
+     */
+    onData(handler: (chunk: Buffer) => void): void;
+    /**
+     * Send input to the terminal's process.
+     * @param data The input, as text or bytes (`'ls\n'`, a newline to submit a line).
+     */
+    write(data: string | Buffer): void;
+    /**
+     * Wait for the terminal's process to exit; the terminal is then closed.
+     * @returns Its exit code (`137` when it was closed by {@link ContainerdContainerTTY.close}).
+     */
+    wait(): Promise<number>;
+    /**
+     * Close the terminal: kill its process with `SIGKILL` and release its FIFOs. Nothing happens when it is already
+     * closed.
+     */
+    close(): Promise<void>;
+}