@lakutata/docker 3.0.0-beta.0

package/dist/esm/client/DockerIgnore.js

@@ -0,0 +1,179 @@
+/*
+ * The rules of the .dockerignore files, rewritten from @balena/dockerignore (Copyright 2020 Balena Ltd., Apache License
+ * 2.0, and Copyright 2018 Zeit, Inc., MIT License, see THIRD_PARTY_NOTICES.md), which follows the implementation of
+ * Docker (moby/moby builder/dockerignore and pkg/fileutils)
+ */
+import path from 'node:path';
+/**
+ * The separators of the paths of the platform: on Windows, "/" and "\" separate the paths and "\" does not escape
+ */
+const SEPARATOR = path.sep;
+/**
+ * filepath.Clean of Go
+ * @param file
+ */
+function cleanPath(file) {
+    return path.normalize(file).replace(SEPARATOR === '\\' ? /(?<=.)\\$/ : /(?<=.)\/$/, '');
+}
+/**
+ * filepath.ToSlash of Go
+ * @param file
+ */
+function toSlash(file) {
+    return SEPARATOR === '/' ? file : file.replace(/\\/g, '/');
+}
+/**
+ * filepath.FromSlash of Go
+ * @param file
+ */
+function fromSlash(file) {
+    return SEPARATOR === '/' ? file : file.replace(/\//g, SEPARATOR);
+}
+/**
+ * The rules of a .dockerignore file: the files of a build context they exclude
+ */
+export class DockerIgnore {
+    #rules = [];
+    #cache = new Map();
+    /**
+     * @param content the content of a .dockerignore file
+     * @param ignoreCase match the case-insensitively, as Docker does not (false by default)
+     */
+    constructor(content = '', ignoreCase = false) {
+        this.ignoreCase = ignoreCase;
+        this.add(content);
+    }
+    /**
+     * Add the rules of a content
+     * @param content
+     */
+    add(content) {
+        for (const line of content.split(/\r?\n/)) {
+            if (!line.trim() || line.startsWith('#'))
+                continue;
+            const rule = this.rule(line.trim());
+            if (rule)
+                this.#rules.push(rule);
+        }
+        this.#cache.clear();
+        return this;
+    }
+    /**
+     * A rule of a line (moby/moby builder/dockerignore/dockerignore.go and pkg/fileutils/fileutils.go)
+     * @param line
+     */
+    rule(line) {
+        let pattern = line;
+        let negative = false;
+        if (pattern.startsWith('!')) {
+            negative = true;
+            pattern = pattern.substring(1).trim();
+        }
+        if (pattern.length > 0) {
+            pattern = toSlash(cleanPath(pattern));
+            if (pattern.length > 1 && pattern.startsWith('/'))
+                pattern = pattern.slice(1);
+        }
+        if (negative)
+            pattern = `!${pattern}`;
+        pattern = pattern.trim();
+        if (!pattern)
+            return undefined;
+        pattern = cleanPath(pattern);
+        if (pattern.startsWith('!')) {
+            if (pattern.length === 1)
+                return undefined;
+            negative = true;
+            pattern = pattern.substring(1);
+        }
+        else {
+            negative = false;
+        }
+        return { pattern: pattern, directories: pattern.split(SEPARATOR), negative: negative };
+    }
+    /**
+     * The regular expression of a rule (fileutils.go regexpMatch)
+     * @param rule
+     */
+    expression(rule) {
+        if (rule.expression)
+            return rule.expression;
+        const separator = SEPARATOR === '\\' ? '\\\\' : SEPARATOR;
+        let source = '^';
+        const pattern = rule.pattern;
+        for (let index = 0; index < pattern.length; index++) {
+            const character = pattern[index];
+            if (character === '*') {
+                if (pattern[index + 1] === '*') {
+                    index++;
+                    //"**/" is "**"
+                    if (pattern[index + 1] === SEPARATOR)
+                        index++;
+                    source += pattern[index + 1] === undefined ? '.*' : `(.*${separator})?`;
+                }
+                else {
+                    source += `[^${separator}]*`;
+                }
+            }
+            else if (character === '?') {
+                source += `[^${separator}]`;
+            }
+            else if (character === '.' || character === '$') {
+                source += `\\${character}`;
+            }
+            else if (character === '\\') {
+                if (SEPARATOR === '\\') {
+                    source += separator;
+                }
+                else if (pattern[index + 1] !== undefined) {
+                    source += `\\${pattern[++index]}`;
+                }
+                else {
+                    source += '\\';
+                }
+            }
+            else {
+                source += character;
+            }
+        }
+        return rule.expression = new RegExp(`${source}$`, this.ignoreCase ? 'i' : '');
+    }
+    /**
+     * Whether a file of the context is excluded by the rules (its path relative to the context, "/" separated)
+     * @param file
+     */
+    ignores(file) {
+        if (!file)
+            return true;
+        let ignored = this.#cache.get(file);
+        if (ignored === undefined)
+            this.#cache.set(file, ignored = this.test(file));
+        return ignored;
+    }
+    /**
+     * Whether a file is excluded: the last rule matching it or one of its parent directories decides
+     * @param file
+     */
+    test(file) {
+        const local = fromSlash(file);
+        const parent = cleanPath(path.dirname(local));
+        const parentDirectories = parent.split(SEPARATOR);
+        let matched = false;
+        for (const rule of this.#rules) {
+            let match = this.expression(rule).test(local);
+            if (!match && parent !== '.') {
+                if (rule.directories.includes('**')) {
+                    for (let index = rule.directories.filter((directory) => directory !== '**').length; index <= parentDirectories.length; index++) {
+                        match = match || this.expression(rule).test(parentDirectories.slice(0, index).join(SEPARATOR));
+                    }
+                }
+                else if (rule.directories.length <= parentDirectories.length) {
+                    match = this.expression(rule).test(parentDirectories.slice(0, rule.directories.length).join(SEPARATOR));
+                }
+            }
+            if (match)
+                matched = !rule.negative;
+        }
+        return matched;
+    }
+}

package/dist/esm/client/DockerRequestError.js

@@ -0,0 +1,20 @@
+/**
+ * A request to the Docker Engine API which failed: its message is the one of docker-modem, "(HTTP code 404) no such
+ * container - No such container: x", the status and the body of the response are given
+ */
+export class DockerRequestError extends Error {
+    /**
+     * @param statusCode the status of the response
+     * @param reason the meaning of the status for the request
+     * @param detail the message of the daemon
+     * @param json the body of the response
+     */
+    constructor(statusCode, reason, detail, json) {
+        super(`(HTTP code ${statusCode}) ${reason} - ${detail} `);
+        this.statusCode = statusCode;
+        this.reason = reason;
+        this.detail = detail;
+        this.json = json;
+        this.name = 'DockerRequestError';
+    }
+}

package/dist/esm/client/DockerStreams.js

@@ -0,0 +1,111 @@
+/*
+ * 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
+ */
+import { Transform } from 'node:stream';
+/**
+ * The stream of a frame of a multiplexed output
+ */
+export var DockerStreamType;
+(function (DockerStreamType) {
+    DockerStreamType[DockerStreamType["STDIN"] = 0] = "STDIN";
+    DockerStreamType[DockerStreamType["STDOUT"] = 1] = "STDOUT";
+    DockerStreamType[DockerStreamType["STDERR"] = 2] = "STDERR";
+})(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
+ */
+export class DockerStreamDecoder extends 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();
+    }
+}
+/**
+ * The output of a multiplexed stream (or buffer), and its outputs by stream
+ * @param input
+ */
+export 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
+ */
+export 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/esm/client/types/ContainerCreateResponse.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

package/dist/esm/docker/ConnectionOptionsBuilder.js

@@ -0,0 +1,142 @@
+import { Docker } from './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'})
+ *     }
+ * }))
+ * ```
+ */
+export const buildDockerConnectionOptions = (options) => ({
+    ...options,
+    class: Docker
+});
+/**
+ * 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 const buildDockerSocketConnectionOptions = (options) => ({
+    ...options,
+    class: Docker
+});
+/**
+ * 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 const buildDockerHttpConnectionOptions = (options) => ({
+    ...options,
+    protocol: 'http',
+    class: Docker
+});
+/**
+ * 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 const buildDockerHttpsConnectionOptions = (options) => ({
+    ...options,
+    protocol: 'https',
+    class: Docker
+});
+/**
+ * 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 const buildDockerSSHConnectionOptions = (options) => ({
+    ...options,
+    protocol: 'ssh',
+    class: Docker
+});