@lakutata/docker 3.0.0-beta.0

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

@@ -0,0 +1,99 @@
+import { Provider } from '@lakutata/core';
+import stream from 'stream';
+import type { DockerClient } from '../../client/DockerClient.js';
+import { ContainerTTYConsoleSizeOptions } from '../options/container/ContainerTTYConsoleSizeOptions.js';
+/**
+ * An interactive command running with a TTY in a container, as `docker exec -it`: what is written to it is the
+ * command's input, its output (stdout and stderr together, with the terminal's control sequences) is read from it. It is
+ * not created with `new`: {@link DockerContainer.createTTY} returns it, its command started.
+ *
+ * The command runs until it exits (`exit` written to a shell), or until the stream is closed (`tty.raw.end()`,
+ * `tty.raw.destroy()`); the stream then ends. A command which cannot be started (not found in the image) does not fail
+ * the creation: its error message is the output, then the stream ends. The write failures are logged by the
+ * application's `log` component, else by the console.
+ * @example
+ * ```typescript
+ * import {type DockerContainer, type DockerContainerTTY} from 'lakutata/com/docker'
+ *
+ * declare const container: DockerContainer
+ *
+ * //A shell: /bin/sh by default
+ * const tty: DockerContainerTTY = await container.createTTY({consoleSize: {cols: 120, rows: 40}})
+ * tty.onData((chunk: Buffer): void => {
+ *     process.stdout.write(chunk)
+ * })
+ * tty.raw.once('end', (): void => console.log('The shell exited'))
+ * tty.write('ls -l /\n')
+ * await tty.resize({cols: 160, rows: 50})
+ * tty.write('exit\n')
+ * ```
+ */
+export declare class DockerContainerTTY extends Provider {
+    #private;
+    /**
+     * Give the client of the Engine API: set by the {@link DockerContainer} creating the object.
+     */
+    protected readonly getClient: () => DockerClient;
+    /**
+     * The full ID of the container running the command.
+     */
+    protected readonly containerId: string;
+    /**
+     * The command run: the program and its arguments (a program name alone as a string).
+     */
+    protected readonly cmd: string | string[];
+    /**
+     * The size of the console when the command starts.
+     * @default undefined (chosen by the daemon)
+     */
+    protected readonly initialConsoleSize?: ContainerTTYConsoleSizeOptions;
+    /**
+     * Create the execution of the command and start it, attached to its TTY.
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     * @throws {DockerRequestException} When the container is not running (HTTP 409).
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * Close the stream of the TTY, which ends the command's input.
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * The stream of the TTY, both ways: written, the command's input; read, its output. Its `end` event tells that the
+     * command exited, once its output is read (with {@link DockerContainerTTY.onData} or a `data` listener).
+     */
+    get raw(): stream.Duplex;
+    /**
+     * The stream of the TTY, typed as its writable side: the command's input.
+     */
+    get writable(): stream.Writable;
+    /**
+     * The stream of the TTY, typed as its readable side: the command's output.
+     */
+    get readable(): stream.Readable;
+    /**
+     * Change the size of the TTY's console, as a terminal window resized does (the command gets `SIGWINCH`).
+     * @param options The number of columns (`cols`) and rows (`rows`).
+     * @throws {DockerRequestException} When the command has exited (HTTP 404, no such exec; HTTP 500).
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     */
+    resize(options: ContainerTTYConsoleSizeOptions): Promise<void>;
+    /**
+     * Receive the command's output as it comes. Each call adds a handler.
+     * @param handler Called with each chunk of the output: raw bytes, the terminal's control sequences included.
+     */
+    onData(handler: (chunk: Buffer) => void): void;
+    /**
+     * Write text to the command's input, as typed on its terminal (`'ls\n'` runs `ls` in a shell). A write failure is
+     * not thrown: it is logged as a warning by the `log` component (by the console without it).
+     * @param data The text written, UTF-8 encoded.
+     */
+    write(data: string): void;
+    /**
+     * Write bytes to the command's input, as typed on its terminal. A write failure is not thrown: it is logged as a
+     * warning by the `log` component (by the console without it).
+     * @param data The bytes written.
+     */
+    write(data: Buffer): void;
+}

package/dist/cjs/docker/lib/DockerContainerTTY.js

@@ -0,0 +1,157 @@
+"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.DockerContainerTTY = void 0;
+const core_1 = require("@lakutata/core");
+const di_1 = require("@lakutata/core/decorator/di");
+const ContainerTTYConsoleSizeOptions_js_1 = require("../options/container/ContainerTTYConsoleSizeOptions.js");
+const dto_1 = require("@lakutata/core/decorator/dto");
+/**
+ * An interactive command running with a TTY in a container, as `docker exec -it`: what is written to it is the
+ * command's input, its output (stdout and stderr together, with the terminal's control sequences) is read from it. It is
+ * not created with `new`: {@link DockerContainer.createTTY} returns it, its command started.
+ *
+ * The command runs until it exits (`exit` written to a shell), or until the stream is closed (`tty.raw.end()`,
+ * `tty.raw.destroy()`); the stream then ends. A command which cannot be started (not found in the image) does not fail
+ * the creation: its error message is the output, then the stream ends. The write failures are logged by the
+ * application's `log` component, else by the console.
+ * @example
+ * ```typescript
+ * import {type DockerContainer, type DockerContainerTTY} from 'lakutata/com/docker'
+ *
+ * declare const container: DockerContainer
+ *
+ * //A shell: /bin/sh by default
+ * const tty: DockerContainerTTY = await container.createTTY({consoleSize: {cols: 120, rows: 40}})
+ * tty.onData((chunk: Buffer): void => {
+ *     process.stdout.write(chunk)
+ * })
+ * tty.raw.once('end', (): void => console.log('The shell exited'))
+ * tty.write('ls -l /\n')
+ * await tty.resize({cols: 160, rows: 50})
+ * tty.write('exit\n')
+ * ```
+ */
+let DockerContainerTTY = class DockerContainerTTY extends core_1.Provider {
+    #execId;
+    #duplexStream;
+    /**
+     * The logger of the write failures: the application's log component, else the console
+     */
+    #log;
+    /**
+     * Create the execution of the command and start it, attached to its TTY.
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     * @throws {DockerRequestException} When the container is not running (HTTP 409).
+     * @protected
+     */
+    async init() {
+        try {
+            this.#log = await this.getObject('log');
+        }
+        catch {
+            //An application without a log component
+            this.#log = console;
+        }
+        const exec = await this.getClient().createExec(this.containerId, {
+            AttachStderr: true,
+            AttachStdin: true,
+            AttachStdout: true,
+            Cmd: this.cmd ? Array.isArray(this.cmd) ? this.cmd : [this.cmd] : undefined,
+            Tty: true,
+            ConsoleSize: [this.initialConsoleSize?.rows ? this.initialConsoleSize.rows : 0, this.initialConsoleSize?.cols ? this.initialConsoleSize.cols : 0]
+        });
+        this.#execId = exec.Id;
+        //Started with its TTY: its output is not multiplexed
+        this.#duplexStream = await this.getClient().startExec(this.#execId, { Detach: false, Tty: true });
+    }
+    /**
+     * Close the stream of the TTY, which ends the command's input.
+     * @protected
+     */
+    async destroy() {
+        //Not created when its execution failed to start
+        if (this.#duplexStream && !this.#duplexStream.destroyed) {
+            this.#duplexStream.removeAllListeners();
+            this.#duplexStream.destroy();
+        }
+    }
+    /**
+     * The stream of the TTY, both ways: written, the command's input; read, its output. Its `end` event tells that the
+     * command exited, once its output is read (with {@link DockerContainerTTY.onData} or a `data` listener).
+     */
+    get raw() {
+        return this.#duplexStream;
+    }
+    /**
+     * The stream of the TTY, typed as its writable side: the command's input.
+     */
+    get writable() {
+        return this.#duplexStream;
+    }
+    /**
+     * The stream of the TTY, typed as its readable side: the command's output.
+     */
+    get readable() {
+        return this.#duplexStream;
+    }
+    /**
+     * Change the size of the TTY's console, as a terminal window resized does (the command gets `SIGWINCH`).
+     * @param options The number of columns (`cols`) and rows (`rows`).
+     * @throws {DockerRequestException} When the command has exited (HTTP 404, no such exec; HTTP 500).
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     */
+    async resize(options) {
+        await this.getClient().resizeExec(this.#execId, {
+            w: options.cols,
+            h: options.rows
+        });
+    }
+    /**
+     * Receive the command's output as it comes. Each call adds a handler.
+     * @param handler Called with each chunk of the output: raw bytes, the terminal's control sequences included.
+     */
+    onData(handler) {
+        this.#duplexStream.on('data', handler);
+    }
+    write(data) {
+        this.#duplexStream.write(data, (error) => {
+            if (error)
+                this.#log.warn('Write data to duplex stream error: %s', error.message);
+        });
+    }
+};
+exports.DockerContainerTTY = DockerContainerTTY;
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Function()),
+    __metadata("design:type", Function)
+], DockerContainerTTY.prototype, "getClient", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.String()),
+    __metadata("design:type", String)
+], DockerContainerTTY.prototype, "containerId", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Alternatives(core_1.DTO.String(), core_1.DTO.Array(core_1.DTO.String()).min(1))),
+    __metadata("design:type", Object)
+], DockerContainerTTY.prototype, "cmd", void 0);
+__decorate([
+    (0, di_1.Configurable)(ContainerTTYConsoleSizeOptions_js_1.ContainerTTYConsoleSizeOptions.optional()),
+    __metadata("design:type", ContainerTTYConsoleSizeOptions_js_1.ContainerTTYConsoleSizeOptions)
+], DockerContainerTTY.prototype, "initialConsoleSize", void 0);
+__decorate([
+    (0, dto_1.Accept)(ContainerTTYConsoleSizeOptions_js_1.ContainerTTYConsoleSizeOptions.required()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [ContainerTTYConsoleSizeOptions_js_1.ContainerTTYConsoleSizeOptions]),
+    __metadata("design:returntype", Promise)
+], DockerContainerTTY.prototype, "resize", null);
+exports.DockerContainerTTY = DockerContainerTTY = __decorate([
+    (0, di_1.Transient)()
+], DockerContainerTTY);

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

@@ -0,0 +1,153 @@
+import { Provider } from '@lakutata/core';
+import type { DockerClient } from '../../client/DockerClient.js';
+import { Time } from '@lakutata/utils/Time';
+import { ImageConfig } from '../types/ImageConfig.js';
+import { ImageTagOptions } from '../options/image/ImageTagOptions.js';
+import { ImageExportOptions } from '../options/image/ImageExportOptions.js';
+import { ImageRemoveOptions } from '../options/image/ImageRemoveOptions.js';
+import { ImagePushOptions } from '../options/image/ImagePushOptions.js';
+import type { Docker } from '../Docker.js';
+import { ContainerSettingOptions } from '../options/container/ContainerSettingOptions.js';
+import { type DockerContainer } from './DockerContainer.js';
+/**
+ * An image of the Docker daemon, with its tags, platform, size and configuration as inspected, and its operations: tag,
+ * export, push, remove, and run a container. It is not created with `new`: {@link Docker.getImage},
+ * {@link Docker.listImages}, {@link Docker.pullImage}, {@link Docker.buildImage}, {@link Docker.importImage} and
+ * {@link DockerContainer.commit} return it.
+ *
+ * Its properties are a snapshot, taken when it is obtained and refreshed by `tag()` and `push()`. Its operations reject
+ * with {@link DockerImageNotFoundException} when the image was removed, with {@link DockerRequestException} when the
+ * daemon refuses them otherwise (used by a container: 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.buildImage({workdir: '/srv/app', files: ['Dockerfile', 'src', 'package.json'], repoTag: 'app:1.0.0'})
+ * console.log(image.id, image.platform, image.size, image.config.ports)
+ * await image.tag({repo: 'registry.example.com/team/app', tag: '1.0.0'})
+ * await image.push({
+ *     repo: 'registry.example.com/team/app',
+ *     tag: '1.0.0',
+ *     auth: {serverAddress: 'registry.example.com', username: 'ci', password: 'secret'}
+ * })
+ * await image.export({destination: '/tmp/app-1.0.0.tar', repoTag: 'app:1.0.0'})
+ * const container: DockerContainer = await image.run({name: 'app', ports: [{port: 3000, type: 'tcp', hostPorts: [3000]}]})
+ * console.log(container.state.status)
+ * ```
+ */
+export declare class DockerImage 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 image (`sha256:…`).
+     */
+    id: string;
+    /**
+     * The tags of the image (`['alpine:3.20', 'alpine:latest']`); empty for an untagged image.
+     */
+    repoTags: string[];
+    /**
+     * When the image was built.
+     */
+    createdAt: Time;
+    /**
+     * The CPU architecture of the image (`amd64`, `arm64`).
+     */
+    arch: string;
+    /**
+     * The operating system of the image (`linux`).
+     */
+    os: string;
+    /**
+     * The platform of the image, `os/arch` (`linux/arm64`): the one its containers are created for by
+     * {@link DockerImage.run}.
+     */
+    platform: string;
+    /**
+     * The size of the image, in bytes.
+     */
+    size: number;
+    /**
+     * The configuration of the image: its default host name, user, environment, command, entrypoint, volumes and exposed
+     * ports.
+     */
+    config: ImageConfig;
+    /**
+     * Inspect the image.
+     * @throws {DockerImageNotFoundException} When the image does not exist.
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * Abort the export in progress of the object (the image itself is left as it is).
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * Refresh the properties from the daemon's inspection of the image.
+     * @throws {DockerImageNotFoundException} When the image does not exist.
+     * @protected
+     */
+    protected syncImageInfo(): Promise<void>;
+    /**
+     * Add a tag to the image, as `docker tag`, then refresh its properties. A tag already given to another image moves to
+     * this one.
+     * @param options The repository (`registry.example.com/team/app`) and the tag (`latest` by default).
+     * @throws {DockerImageNotFoundException} When the image was removed.
+     * @throws {DockerRequestException} When the name is invalid (HTTP 400).
+     */
+    tag(options: ImageTagOptions): Promise<void>;
+    /**
+     * Save the image as a tar archive, as `docker save`, which {@link Docker.importImage} loads. With `repoTag`, the
+     * archive holds that tag (restored when it is loaded); without it, the image is saved by ID, without its tags.
+     * @param options The `destination` (a file path, created or overwritten, or a writable stream, ended after the
+     * archive), the tag saved (`repoTag`), and `createRepoTagIfNotExists` (`true` by default) to add that tag to the image
+     * when it does not have it.
+     * @throws {DockerImageRepoTagNotFoundException} When the image does not have `repoTag` and
+     * `createRepoTagIfNotExists` is `false`.
+     * @throws {DockerImageNotFoundException} When the image was removed.
+     * @throws {Error} The error of the destination.
+     */
+    export(options: ImageExportOptions): Promise<void>;
+    /**
+     * Push the image to its registry, as `docker push`, and wait for its end. The image is first tagged `repo:tag` (the
+     * tag is kept afterwards).
+     * @param options The repository, with its registry (`registry.example.com/team/app`); the tag (`latest` by default);
+     * the registry credentials; and a callback receiving each progress message.
+     * @throws {DockerImagePushException} When the registry refuses the push (refused credentials, a repository not
+     * found).
+     * @throws {DockerImageNotFoundException} When the image was removed.
+     * @throws {DockerRequestException} When the daemon refuses to push it.
+     */
+    push(options: ImagePushOptions): Promise<void>;
+    /**
+     * Remove the image, as `docker rmi -f` by default: forced, it is removed with all its tags, even when a stopped
+     * container uses it.
+     * @param options `force` (`true` by default; `false` refuses an image with several tags or used by a container) and
+     * `noprune` (keeps its untagged parent images; `false` by default).
+     * @throws {DockerImageNotFoundException} When the image was already removed.
+     * @throws {DockerRequestException} When it is used by a running container or, without `force`, by any container or
+     * with several tags (HTTP 409).
+     */
+    remove(options?: ImageRemoveOptions): Promise<void>;
+    /**
+     * Create a container from the image, for its platform, then start it, as `docker run -d`.
+     * @param options The container's settings: name, command, environment, ports, binds, devices, networks, limits…
+     * @returns The container, started.
+     * @throws {DockerRequestException} When the name is already used (HTTP 409), or the start fails (HTTP 500: a command
+     * not found, a port already used); the container then stays created.
+     * @throws {DockerNetworkNotFoundException} When a network of the settings is not found.
+     * @throws {InvalidMethodAcceptException} When the settings are invalid.
+     */
+    run(options: ContainerSettingOptions): Promise<DockerContainer>;
+}