@lakutata/docker 3.0.0-beta.0

package/dist/cjs/client/DockerStreams.d.ts

@@ -0,0 +1,35 @@
+import { Transform, type TransformCallback } from 'node:stream';
+/**
+ * The stream of a frame of a multiplexed output
+ */
+export declare enum DockerStreamType {
+    STDIN = 0,
+    STDOUT = 1,
+    STDERR = 2
+}
+/**
+ * The output of a container without TTY is multiplexed: each frame is a header of 8 bytes (the stream, 3 zeros, the
+ * size as a big endian uint32) and its content. The decoder gives the contents, in their order; its "frame" event
+ * gives each content with its stream
+ */
+export declare class DockerStreamDecoder extends Transform {
+    #private;
+    _transform(chunk: Buffer, _encoding: BufferEncoding, callback: TransformCallback): void;
+    _flush(callback: TransformCallback): void;
+}
+/**
+ * The output of a multiplexed stream (or buffer), and its outputs by stream
+ * @param input
+ */
+export declare function readMultiplexed(input: NodeJS.ReadableStream | Buffer): Promise<{
+    output: string;
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * Read the JSON lines of a progress (a pull, a push, a build, a load): each object is given to the callback, all of them
+ * are given back once the stream ends. The lines which are not JSON are skipped
+ * @param input
+ * @param onProgress
+ */
+export declare function followProgress<T = Record<string, any>>(input: NodeJS.ReadableStream, onProgress?: (progress: T) => void): Promise<T[]>;

package/dist/cjs/client/DockerStreams.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DockerStreamDecoder = exports.DockerStreamType = void 0;
+exports.readMultiplexed = readMultiplexed;
+exports.followProgress = followProgress;
+/*
+ * The streams of the Docker Engine API, rewritten from docker-modem (Copyright Pedro Dias, Apache License 2.0, see
+ * THIRD_PARTY_NOTICES.md): the multiplexed output of the containers without TTY, and the JSON lines of the progresses
+ */
+const node_stream_1 = require("node:stream");
+/**
+ * The stream of a frame of a multiplexed output
+ */
+var DockerStreamType;
+(function (DockerStreamType) {
+    DockerStreamType[DockerStreamType["STDIN"] = 0] = "STDIN";
+    DockerStreamType[DockerStreamType["STDOUT"] = 1] = "STDOUT";
+    DockerStreamType[DockerStreamType["STDERR"] = 2] = "STDERR";
+})(DockerStreamType || (exports.DockerStreamType = DockerStreamType = {}));
+/**
+ * The output of a container without TTY is multiplexed: each frame is a header of 8 bytes (the stream, 3 zeros, the
+ * size as a big endian uint32) and its content. The decoder gives the contents, in their order; its "frame" event
+ * gives each content with its stream
+ */
+class DockerStreamDecoder extends node_stream_1.Transform {
+    #pending = Buffer.alloc(0);
+    _transform(chunk, _encoding, callback) {
+        this.#pending = this.#pending.length ? Buffer.concat([this.#pending, chunk]) : chunk;
+        while (this.#pending.length >= 8) {
+            const size = this.#pending.readUInt32BE(4);
+            if (this.#pending.length < 8 + size)
+                break;
+            const type = this.#pending.readUInt8(0);
+            const content = this.#pending.subarray(8, 8 + size);
+            this.#pending = this.#pending.subarray(8 + size);
+            if (content.length) {
+                this.emit('frame', type, content);
+                this.push(content);
+            }
+        }
+        callback();
+    }
+    _flush(callback) {
+        //A truncated frame is given as it is
+        if (this.#pending.length)
+            this.push(this.#pending);
+        callback();
+    }
+}
+exports.DockerStreamDecoder = DockerStreamDecoder;
+/**
+ * The output of a multiplexed stream (or buffer), and its outputs by stream
+ * @param input
+ */
+async function readMultiplexed(input) {
+    const decoder = new DockerStreamDecoder();
+    const output = [];
+    const streams = { [DockerStreamType.STDOUT]: [], [DockerStreamType.STDERR]: [] };
+    decoder.on('frame', (type, content) => (streams[type] ??= []).push(content));
+    decoder.on('data', (content) => output.push(content));
+    await new Promise((resolve, reject) => {
+        decoder.once('end', resolve).once('error', reject);
+        if (Buffer.isBuffer(input)) {
+            decoder.end(input);
+        }
+        else {
+            input.once('error', (error) => decoder.destroy(error));
+            input.pipe(decoder);
+        }
+    });
+    return {
+        output: Buffer.concat(output).toString(),
+        stdout: Buffer.concat(streams[DockerStreamType.STDOUT]).toString(),
+        stderr: Buffer.concat(streams[DockerStreamType.STDERR]).toString()
+    };
+}
+/**
+ * Read the JSON lines of a progress (a pull, a push, a build, a load): each object is given to the callback, all of them
+ * are given back once the stream ends. The lines which are not JSON are skipped
+ * @param input
+ * @param onProgress
+ */
+async function followProgress(input, onProgress) {
+    const objects = [];
+    let pending = '';
+    const line = (text) => {
+        const trimmed = text.trim();
+        if (!trimmed)
+            return;
+        let object;
+        try {
+            object = JSON.parse(trimmed);
+        }
+        catch {
+            return;
+        }
+        objects.push(object);
+        onProgress?.(object);
+    };
+    await new Promise((resolve, reject) => {
+        input.on('data', (chunk) => {
+            pending += chunk.toString();
+            let position;
+            while ((position = pending.indexOf('\n')) >= 0) {
+                line(pending.slice(0, position));
+                pending = pending.slice(position + 1);
+            }
+        });
+        input.once('end', () => {
+            line(pending);
+            resolve();
+        });
+        input.once('close', resolve);
+        input.once('error', reject);
+    });
+    return objects;
+}

package/dist/cjs/client/types/ContainerCreateResponse.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The response of the Docker Engine API to the creation of a container (ContainerCreateResponse)
+ */
+export type ContainerCreateResponse = {
+    Id: string;
+    Warnings?: string[];
+};

package/dist/cjs/client/types/ContainerCreateResponse.js

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

package/dist/cjs/client/types/ContainerStopQuery.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The query of stopping or restarting a container in the Docker Engine API
+ */
+export type ContainerStopQuery = {
+    /**
+     * The number of seconds to wait before killing the container
+     */
+    t?: number;
+    /**
+     * The signal to send to the container
+     */
+    signal?: string;
+};

package/dist/cjs/client/types/ContainerStopQuery.js

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

package/dist/cjs/client/types/DeviceMapping.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A device of the host mapped into a container in the Docker Engine API (DeviceMapping)
+ */
+export type DeviceMapping = {
+    PathOnHost: string;
+    PathInContainer: string;
+    CgroupPermissions: string;
+};

package/dist/cjs/client/types/DeviceMapping.js

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

package/dist/cjs/client/types/IdResponse.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The response of the Docker Engine API giving the id of an object it created (IdResponse)
+ */
+export type IdResponse = {
+    Id: string;
+};

package/dist/cjs/client/types/IdResponse.js

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

package/dist/cjs/client/types/NetworkCreateResponse.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The response of the Docker Engine API to the creation of a network (NetworkCreateResponse)
+ */
+export type NetworkCreateResponse = {
+    Id: string;
+    Warning?: string;
+};

package/dist/cjs/client/types/NetworkCreateResponse.js

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

package/dist/cjs/client/types/PortBinding.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A binding of a port of a container to a port of the host in the Docker Engine API (PortBinding)
+ */
+export type PortBinding = {
+    /**
+     * The host address the port is bound on, all of them when empty
+     */
+    HostIp?: string;
+    HostPort: string;
+};

package/dist/cjs/client/types/PortBinding.js

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

package/dist/cjs/docker/ConnectionOptionsBuilder.d.ts

@@ -0,0 +1,128 @@
+import { IDockerConnectionOptions } from './interfaces/IDockerConnectionOptions.js';
+import { IDockerHttpConnectionOptions } from './interfaces/IDockerHttpConnectionOptions.js';
+import { IDockerHttpsConnectionOptions } from './interfaces/IDockerHttpsConnectionOptions.js';
+import { IDockerSSHConnectionOptions } from './interfaces/IDockerSSHConnectionOptions.js';
+import { ComponentOptionsBuilder } from '@lakutata/core';
+/**
+ * Build the component options of a {@link Docker} connected as the options say, to register it in the `components` of
+ * an application under the name of your choice. Without `socketPath` nor `host`, it connects to the Docker of the
+ * environment (`DOCKER_HOST`, else the local socket). The options are validated when the component is created, not
+ * here.
+ * @param options The connection options: a socket (`socketPath`), or a `host` and `port` reached with `protocol`
+ * (`'http'`, `'https'` or `'ssh'`), with their TLS, SSH, timeout and API version options.
+ * @returns The component options (`{class: Docker, ...options}`).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildDockerConnectionOptions} from 'lakutata/com/docker'
+ *
+ * Application.run(() => ({
+ *     id: 'docker.app',
+ *     name: 'Docker',
+ *     components: {
+ *         //The Docker of the environment (DOCKER_HOST, else the local socket), with the API version 1.47
+ *         docker: buildDockerConnectionOptions({version: '1.47'})
+ *     }
+ * }))
+ * ```
+ */
+export declare const buildDockerConnectionOptions: ComponentOptionsBuilder<IDockerConnectionOptions>;
+/**
+ * Build the component options of a {@link Docker} connected to the Unix socket of a daemon (or its named pipe on
+ * Windows), to register it in the `components` of an application. The options are validated when the component is
+ * created, not here.
+ * @param options The path of the socket (`socketPath`), with the timeout and the API version. Without `socketPath`, the
+ * Docker of the environment is used, with the other options applied over it.
+ * @returns The component options (`{class: Docker, ...options}`).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildDockerSocketConnectionOptions} from 'lakutata/com/docker'
+ *
+ * Application.run(() => ({
+ *     id: 'docker.app',
+ *     name: 'Docker',
+ *     components: {
+ *         docker: buildDockerSocketConnectionOptions({socketPath: '/var/run/docker.sock', timeout: 60000})
+ *     }
+ * }))
+ * ```
+ */
+export declare const buildDockerSocketConnectionOptions: ComponentOptionsBuilder<IDockerConnectionOptions>;
+/**
+ * Build the component options of a {@link Docker} connected to a daemon over plain HTTP (`dockerd -H tcp://0.0.0.0:2375`),
+ * to register it in the `components` of an application. The connection is neither encrypted nor authenticated: keep it
+ * to trusted networks. The options are validated when the component is created, not here.
+ * @param options The `host` and `port` of the daemon, with the headers, the timeout and the API version; the `protocol`
+ * is set to `'http'`.
+ * @returns The component options (`{class: Docker, protocol: 'http', ...options}`).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildDockerHttpConnectionOptions} from 'lakutata/com/docker'
+ *
+ * Application.run(() => ({
+ *     id: 'docker.app',
+ *     name: 'Docker',
+ *     components: {
+ *         docker: buildDockerHttpConnectionOptions({host: '192.168.1.10', port: 2375})
+ *     }
+ * }))
+ * ```
+ */
+export declare const buildDockerHttpConnectionOptions: ComponentOptionsBuilder<IDockerHttpConnectionOptions>;
+/**
+ * Build the component options of a {@link Docker} connected to a daemon over HTTPS (`dockerd --tlsverify -H
+ * tcp://0.0.0.0:2376`), to register it in the `components` of an application. The options are validated when the
+ * component is created, not here.
+ * @param options The `host` and `port` of the daemon, with the PEM contents of the authority (`ca`), the client
+ * certificate (`cert`) and its key (`key`), the headers, the timeout and the API version; the `protocol` is set to
+ * `'https'`.
+ * @returns The component options (`{class: Docker, protocol: 'https', ...options}`).
+ * @example
+ * ```typescript
+ * import {readFileSync} from 'node:fs'
+ * import {Application} from 'lakutata'
+ * import {buildDockerHttpsConnectionOptions} from 'lakutata/com/docker'
+ *
+ * Application.run(() => ({
+ *     id: 'docker.app',
+ *     name: 'Docker',
+ *     components: {
+ *         //The PEM contents, not the file paths
+ *         docker: buildDockerHttpsConnectionOptions({
+ *             host: 'docker.example.com',
+ *             port: 2376,
+ *             ca: readFileSync('/etc/docker/certs/ca.pem'),
+ *             cert: readFileSync('/etc/docker/certs/cert.pem'),
+ *             key: readFileSync('/etc/docker/certs/key.pem')
+ *         })
+ *     }
+ * }))
+ * ```
+ */
+export declare const buildDockerHttpsConnectionOptions: ComponentOptionsBuilder<IDockerHttpsConnectionOptions>;
+/**
+ * Build the component options of a {@link Docker} connected to a remote daemon over SSH, as `DOCKER_HOST=ssh://user@host`
+ * does, to register it in the `components` of an application. The requests go through `docker system dial-stdio` run on
+ * the remote host, which needs the Docker CLI; locally, the optional package `ssh2` must be installed. The SSH connection
+ * authenticates through the SSH agent (no password). The options are validated when the component is created, not here.
+ * @param options The `host` and `port` (the SSH port, usually 22) of the remote host, the `username`, the SSH agent's
+ * socket (`sshAuthAgent`; `SSH_AUTH_SOCK` by default), the timeout and the API version; the `protocol` is set to
+ * `'ssh'`.
+ * @returns The component options (`{class: Docker, protocol: 'ssh', ...options}`).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildDockerSSHConnectionOptions} from 'lakutata/com/docker'
+ *
+ * Application.run(() => ({
+ *     id: 'docker.app',
+ *     name: 'Docker',
+ *     components: {
+ *         docker: buildDockerSSHConnectionOptions({host: 'docker.example.com', port: 22, username: 'deploy'})
+ *     }
+ * }))
+ * ```
+ */
+export declare const buildDockerSSHConnectionOptions: ComponentOptionsBuilder<IDockerSSHConnectionOptions>;

package/dist/cjs/docker/ConnectionOptionsBuilder.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDockerSSHConnectionOptions = exports.buildDockerHttpsConnectionOptions = exports.buildDockerHttpConnectionOptions = exports.buildDockerSocketConnectionOptions = exports.buildDockerConnectionOptions = void 0;
+const Docker_js_1 = require("./Docker.js");
+/**
+ * Build the component options of a {@link Docker} connected as the options say, to register it in the `components` of
+ * an application under the name of your choice. Without `socketPath` nor `host`, it connects to the Docker of the
+ * environment (`DOCKER_HOST`, else the local socket). The options are validated when the component is created, not
+ * here.
+ * @param options The connection options: a socket (`socketPath`), or a `host` and `port` reached with `protocol`
+ * (`'http'`, `'https'` or `'ssh'`), with their TLS, SSH, timeout and API version options.
+ * @returns The component options (`{class: Docker, ...options}`).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildDockerConnectionOptions} from 'lakutata/com/docker'
+ *
+ * Application.run(() => ({
+ *     id: 'docker.app',
+ *     name: 'Docker',
+ *     components: {
+ *         //The Docker of the environment (DOCKER_HOST, else the local socket), with the API version 1.47
+ *         docker: buildDockerConnectionOptions({version: '1.47'})
+ *     }
+ * }))
+ * ```
+ */
+const buildDockerConnectionOptions = (options) => ({
+    ...options,
+    class: Docker_js_1.Docker
+});
+exports.buildDockerConnectionOptions = buildDockerConnectionOptions;
+/**
+ * Build the component options of a {@link Docker} connected to the Unix socket of a daemon (or its named pipe on
+ * Windows), to register it in the `components` of an application. The options are validated when the component is
+ * created, not here.
+ * @param options The path of the socket (`socketPath`), with the timeout and the API version. Without `socketPath`, the
+ * Docker of the environment is used, with the other options applied over it.
+ * @returns The component options (`{class: Docker, ...options}`).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildDockerSocketConnectionOptions} from 'lakutata/com/docker'
+ *
+ * Application.run(() => ({
+ *     id: 'docker.app',
+ *     name: 'Docker',
+ *     components: {
+ *         docker: buildDockerSocketConnectionOptions({socketPath: '/var/run/docker.sock', timeout: 60000})
+ *     }
+ * }))
+ * ```
+ */
+const buildDockerSocketConnectionOptions = (options) => ({
+    ...options,
+    class: Docker_js_1.Docker
+});
+exports.buildDockerSocketConnectionOptions = buildDockerSocketConnectionOptions;
+/**
+ * Build the component options of a {@link Docker} connected to a daemon over plain HTTP (`dockerd -H tcp://0.0.0.0:2375`),
+ * to register it in the `components` of an application. The connection is neither encrypted nor authenticated: keep it
+ * to trusted networks. The options are validated when the component is created, not here.
+ * @param options The `host` and `port` of the daemon, with the headers, the timeout and the API version; the `protocol`
+ * is set to `'http'`.
+ * @returns The component options (`{class: Docker, protocol: 'http', ...options}`).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildDockerHttpConnectionOptions} from 'lakutata/com/docker'
+ *
+ * Application.run(() => ({
+ *     id: 'docker.app',
+ *     name: 'Docker',
+ *     components: {
+ *         docker: buildDockerHttpConnectionOptions({host: '192.168.1.10', port: 2375})
+ *     }
+ * }))
+ * ```
+ */
+const buildDockerHttpConnectionOptions = (options) => ({
+    ...options,
+    protocol: 'http',
+    class: Docker_js_1.Docker
+});
+exports.buildDockerHttpConnectionOptions = buildDockerHttpConnectionOptions;
+/**
+ * Build the component options of a {@link Docker} connected to a daemon over HTTPS (`dockerd --tlsverify -H
+ * tcp://0.0.0.0:2376`), to register it in the `components` of an application. The options are validated when the
+ * component is created, not here.
+ * @param options The `host` and `port` of the daemon, with the PEM contents of the authority (`ca`), the client
+ * certificate (`cert`) and its key (`key`), the headers, the timeout and the API version; the `protocol` is set to
+ * `'https'`.
+ * @returns The component options (`{class: Docker, protocol: 'https', ...options}`).
+ * @example
+ * ```typescript
+ * import {readFileSync} from 'node:fs'
+ * import {Application} from 'lakutata'
+ * import {buildDockerHttpsConnectionOptions} from 'lakutata/com/docker'
+ *
+ * Application.run(() => ({
+ *     id: 'docker.app',
+ *     name: 'Docker',
+ *     components: {
+ *         //The PEM contents, not the file paths
+ *         docker: buildDockerHttpsConnectionOptions({
+ *             host: 'docker.example.com',
+ *             port: 2376,
+ *             ca: readFileSync('/etc/docker/certs/ca.pem'),
+ *             cert: readFileSync('/etc/docker/certs/cert.pem'),
+ *             key: readFileSync('/etc/docker/certs/key.pem')
+ *         })
+ *     }
+ * }))
+ * ```
+ */
+const buildDockerHttpsConnectionOptions = (options) => ({
+    ...options,
+    protocol: 'https',
+    class: Docker_js_1.Docker
+});
+exports.buildDockerHttpsConnectionOptions = buildDockerHttpsConnectionOptions;
+/**
+ * Build the component options of a {@link Docker} connected to a remote daemon over SSH, as `DOCKER_HOST=ssh://user@host`
+ * does, to register it in the `components` of an application. The requests go through `docker system dial-stdio` run on
+ * the remote host, which needs the Docker CLI; locally, the optional package `ssh2` must be installed. The SSH connection
+ * authenticates through the SSH agent (no password). The options are validated when the component is created, not here.
+ * @param options The `host` and `port` (the SSH port, usually 22) of the remote host, the `username`, the SSH agent's
+ * socket (`sshAuthAgent`; `SSH_AUTH_SOCK` by default), the timeout and the API version; the `protocol` is set to
+ * `'ssh'`.
+ * @returns The component options (`{class: Docker, protocol: 'ssh', ...options}`).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildDockerSSHConnectionOptions} from 'lakutata/com/docker'
+ *
+ * Application.run(() => ({
+ *     id: 'docker.app',
+ *     name: 'Docker',
+ *     components: {
+ *         docker: buildDockerSSHConnectionOptions({host: 'docker.example.com', port: 22, username: 'deploy'})
+ *     }
+ * }))
+ * ```
+ */
+const buildDockerSSHConnectionOptions = (options) => ({
+    ...options,
+    protocol: 'ssh',
+    class: Docker_js_1.Docker
+});
+exports.buildDockerSSHConnectionOptions = buildDockerSSHConnectionOptions;