@lakutata/docker 3.0.0-beta.0

package/dist/cjs/client/BuildContext.js

@@ -0,0 +1,76 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packBuildContext = packBuildContext;
+/*
+ * The context of a build: the files of a directory packed into a gzipped tar archive, as dockerode prepares it (with
+ * tar-fs and @balena/dockerignore, see THIRD_PARTY_NOTICES.md), modified: an error of the packing fails the archive
+ * (instead of ending it), and each file is packed once
+ */
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const promises_2 = require("node:stream/promises");
+const node_zlib_1 = require("node:zlib");
+const tar_stream_1 = require("tar-stream");
+const DockerIgnore_js_1 = require("./DockerIgnore.js");
+/**
+ * The path of an entry of the archive ("/" separated, relative)
+ * @param entry
+ */
+function entryName(entry) {
+    return node_path_1.default.posix.normalize(entry.split(node_path_1.default.sep).join('/')).replace(/^(\.\/)+/, '').replace(/\/+$/, '');
+}
+/**
+ * Pack the context of a build: a gzipped tar stream; the files excluded by the .dockerignore of the directory are
+ * skipped. An error of the packing (a file which cannot be read, or changes while it is read) is an error of the stream
+ * @param options
+ */
+function packBuildContext(options) {
+    const archive = (0, tar_stream_1.pack)();
+    const gzip = (0, node_zlib_1.createGzip)();
+    archive.once('error', (error) => gzip.destroy(error));
+    archive.pipe(gzip);
+    (async () => {
+        const root = node_path_1.default.resolve(options.directory);
+        let ignore = new DockerIgnore_js_1.DockerIgnore();
+        try {
+            ignore = new DockerIgnore_js_1.DockerIgnore(await (0, promises_1.readFile)(node_path_1.default.join(root, '.dockerignore'), 'utf8'));
+        }
+        catch {
+            //No .dockerignore
+        }
+        const always = new Set((options.always ?? []).map(entryName));
+        const packed = new Set();
+        const add = async (name) => {
+            if (!name || name === '.' || name.startsWith('../') || packed.has(name))
+                return;
+            if (!always.has(name) && ignore.ignores(name))
+                return;
+            packed.add(name);
+            const file = node_path_1.default.join(root, name);
+            const stats = await (0, promises_1.lstat)(file);
+            const header = { name: name, mode: stats.mode & 0o7777, mtime: stats.mtime, uid: stats.uid, gid: stats.gid };
+            if (stats.isDirectory()) {
+                await new Promise((resolve, reject) => archive.entry({ ...header, type: 'directory' }, (error) => error ? reject(error) : resolve()));
+                for (const child of (await (0, promises_1.readdir)(file)).sort())
+                    await add(`${name}/${child}`);
+            }
+            else if (stats.isSymbolicLink()) {
+                //The links of the images are the ones of Linux: "/" separated (readlink gives backslashes on Windows)
+                const target = (await (0, promises_1.readlink)(file)).split(node_path_1.default.sep).join('/');
+                await new Promise((resolve, reject) => archive.entry({ ...header, type: 'symlink', linkname: target }, (error) => error ? reject(error) : resolve()));
+            }
+            else if (stats.isFile()) {
+                await (0, promises_2.pipeline)((0, node_fs_1.createReadStream)(file), archive.entry({ ...header, type: 'file', size: stats.size }));
+            }
+            //The sockets and the pipes are not packed
+        };
+        for (const entry of options.entries)
+            await add(entryName(entry));
+        archive.finalize();
+    })().catch((error) => gzip.destroy(error));
+    return gzip;
+}

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

@@ -0,0 +1,81 @@
+/**
+ * The progress of the builds of BuildKit: the "aux" of the messages "moby.buildkit.trace" of a build is a StatusResponse
+ * of BuildKit (github.com/moby/buildkit, api/services/control/control.proto), encoded by protobuf then base64. Only the
+ * fields read are decoded, by their numbers in control.proto:
+ *
+ *   StatusResponse: 1 vertexes (Vertex), 2 statuses (VertexStatus), 3 logs (VertexLog), 4 warnings (VertexWarning)
+ *   Vertex: 1 digest, 3 name, 4 cached, 5 started (Timestamp), 6 completed (Timestamp), 7 error
+ *   VertexStatus: 1 ID, 2 vertex, 3 name, 4 current, 5 total, 8 completed (Timestamp)
+ *   VertexLog: 1 vertex, 3 stream, 4 msg
+ *   VertexWarning: 1 vertex, 2 level, 3 short
+ *   Timestamp (google.protobuf): 1 seconds, 2 nanos
+ */
+export type BuildKitVertex = {
+    digest: string;
+    name: string;
+    cached: boolean;
+    /**
+     * The start and the end of the step, in milliseconds since the epoch
+     */
+    started?: number;
+    completed?: number;
+    error?: string;
+};
+export type BuildKitVertexStatus = {
+    id: string;
+    vertex: string;
+    name: string;
+    current: number;
+    total: number;
+    completed?: number;
+};
+export type BuildKitVertexLog = {
+    vertex: string;
+    /**
+     * 1 stdout, 2 stderr
+     */
+    stream: number;
+    message: Buffer;
+};
+export type BuildKitVertexWarning = {
+    vertex: string;
+    level: number;
+    short: string;
+};
+export type BuildKitStatus = {
+    vertexes: BuildKitVertex[];
+    statuses: BuildKitVertexStatus[];
+    logs: BuildKitVertexLog[];
+    warnings: BuildKitVertexWarning[];
+};
+/**
+ * Decode the progress of a build: the "aux" of a message "moby.buildkit.trace"
+ * @param aux the base64 of a StatusResponse
+ */
+export declare function decodeBuildKitStatus(aux: string): BuildKitStatus;
+/**
+ * The lines of the progress of a build, as "docker build --progress=plain" shows them: the steps are numbered in their
+ * order ("#3 [2/2] RUN npm ci"), with their output, and whether they are cached, done ("#3 DONE 1.2s") or failed
+ */
+export declare class BuildKitProgress {
+    #private;
+    /**
+     * The number of a step, given when it is first seen
+     * @param digest
+     */
+    protected step(digest: string): {
+        number: number;
+        started: boolean;
+        ended: boolean;
+    };
+    /**
+     * The lines of a status of the build
+     * @param status
+     */
+    lines(status: BuildKitStatus): string[];
+    /**
+     * The incomplete last line of the output of a step
+     * @param digest
+     */
+    protected flush(digest: string): string[];
+}

package/dist/cjs/client/BuildKitProgress.js

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * The progress of the builds of BuildKit: the "aux" of the messages "moby.buildkit.trace" of a build is a StatusResponse
+ * of BuildKit (github.com/moby/buildkit, api/services/control/control.proto), encoded by protobuf then base64. Only the
+ * fields read are decoded, by their numbers in control.proto:
+ *
+ *   StatusResponse: 1 vertexes (Vertex), 2 statuses (VertexStatus), 3 logs (VertexLog), 4 warnings (VertexWarning)
+ *   Vertex: 1 digest, 3 name, 4 cached, 5 started (Timestamp), 6 completed (Timestamp), 7 error
+ *   VertexStatus: 1 ID, 2 vertex, 3 name, 4 current, 5 total, 8 completed (Timestamp)
+ *   VertexLog: 1 vertex, 3 stream, 4 msg
+ *   VertexWarning: 1 vertex, 2 level, 3 short
+ *   Timestamp (google.protobuf): 1 seconds, 2 nanos
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BuildKitProgress = void 0;
+exports.decodeBuildKitStatus = decodeBuildKitStatus;
+/**
+ * The fields of a protobuf message (the wire format: varints, 64 and 32 bits values, length-delimited values)
+ * @param buffer
+ */
+function protobufFields(buffer) {
+    const fields = [];
+    let offset = 0;
+    const varint = () => {
+        let result = 0n;
+        let shift = 0n;
+        while (offset < buffer.length) {
+            const byte = buffer[offset++];
+            result |= BigInt(byte & 0x7f) << shift;
+            if (!(byte & 0x80))
+                return result;
+            shift += 7n;
+        }
+        throw new Error('Truncated protobuf varint');
+    };
+    while (offset < buffer.length) {
+        const key = Number(varint());
+        const number = key >>> 3;
+        switch (key & 0x07) {
+            case 0:
+                fields.push({ number: number, value: varint() });
+                break;
+            case 1:
+                fields.push({ number: number, value: buffer.readBigUInt64LE(offset) });
+                offset += 8;
+                break;
+            case 2: {
+                const length = Number(varint());
+                if (offset + length > buffer.length)
+                    throw new Error('Truncated protobuf value');
+                fields.push({ number: number, value: buffer.subarray(offset, offset + length) });
+                offset += length;
+                break;
+            }
+            case 5:
+                fields.push({ number: number, value: BigInt(buffer.readUInt32LE(offset)) });
+                offset += 4;
+                break;
+            default:
+                throw new Error(`Unsupported protobuf wire type ${key & 0x07}`);
+        }
+    }
+    return fields;
+}
+const text = (value) => Buffer.isBuffer(value) ? value.toString() : '';
+const bytes = (value) => Buffer.isBuffer(value) ? value : Buffer.alloc(0);
+const integer = (value) => Buffer.isBuffer(value) ? 0 : Number(BigInt.asIntN(64, value));
+/**
+ * A google.protobuf.Timestamp, in milliseconds since the epoch
+ * @param value
+ */
+function timestamp(value) {
+    if (!Buffer.isBuffer(value))
+        return undefined;
+    let seconds = 0;
+    let nanos = 0;
+    for (const field of protobufFields(value)) {
+        if (field.number === 1)
+            seconds = integer(field.value);
+        if (field.number === 2)
+            nanos = integer(field.value);
+    }
+    //The zero timestamp is not set
+    return seconds || nanos ? seconds * 1000 + Math.floor(nanos / 1e6) : undefined;
+}
+/**
+ * Decode the progress of a build: the "aux" of a message "moby.buildkit.trace"
+ * @param aux the base64 of a StatusResponse
+ */
+function decodeBuildKitStatus(aux) {
+    const status = { vertexes: [], statuses: [], logs: [], warnings: [] };
+    for (const field of protobufFields(Buffer.from(aux, 'base64'))) {
+        const message = protobufFields(bytes(field.value));
+        const get = (number) => message.find((candidate) => candidate.number === number)?.value;
+        switch (field.number) {
+            case 1:
+                status.vertexes.push({
+                    digest: text(get(1) ?? 0n),
+                    name: text(get(3) ?? 0n),
+                    cached: integer(get(4) ?? 0n) === 1,
+                    started: timestamp(get(5) ?? 0n),
+                    completed: timestamp(get(6) ?? 0n),
+                    error: text(get(7) ?? 0n) || undefined
+                });
+                break;
+            case 2:
+                status.statuses.push({
+                    id: text(get(1) ?? 0n),
+                    vertex: text(get(2) ?? 0n),
+                    name: text(get(3) ?? 0n),
+                    current: integer(get(4) ?? 0n),
+                    total: integer(get(5) ?? 0n),
+                    completed: timestamp(get(8) ?? 0n)
+                });
+                break;
+            case 3:
+                status.logs.push({ vertex: text(get(1) ?? 0n), stream: integer(get(3) ?? 0n), message: bytes(get(4) ?? 0n) });
+                break;
+            case 4:
+                status.warnings.push({ vertex: text(get(1) ?? 0n), level: integer(get(2) ?? 0n), short: text(get(3) ?? 0n) });
+                break;
+        }
+    }
+    return status;
+}
+/**
+ * The lines of the progress of a build, as "docker build --progress=plain" shows them: the steps are numbered in their
+ * order ("#3 [2/2] RUN npm ci"), with their output, and whether they are cached, done ("#3 DONE 1.2s") or failed
+ */
+class BuildKitProgress {
+    #steps = new Map();
+    /**
+     * The incomplete last line of the output of each step
+     */
+    #pending = new Map();
+    /**
+     * The number of a step, given when it is first seen
+     * @param digest
+     */
+    step(digest) {
+        let step = this.#steps.get(digest);
+        if (!step)
+            this.#steps.set(digest, step = { number: this.#steps.size + 1, started: false, ended: false });
+        return step;
+    }
+    /**
+     * The lines of a status of the build
+     * @param status
+     */
+    lines(status) {
+        const lines = [];
+        for (const vertex of status.vertexes) {
+            const step = this.step(vertex.digest);
+            if (!step.started && (vertex.started || vertex.cached)) {
+                step.started = true;
+                lines.push(`#${step.number} ${vertex.name}`);
+            }
+            if (step.ended)
+                continue;
+            if (vertex.cached) {
+                step.ended = true;
+                lines.push(`#${step.number} CACHED`);
+            }
+            else if (vertex.error) {
+                step.ended = true;
+                lines.push(...this.flush(vertex.digest), `#${step.number} ERROR: ${vertex.error}`);
+            }
+            else if (vertex.completed) {
+                step.ended = true;
+                const seconds = vertex.started ? ` ${((vertex.completed - vertex.started) / 1000).toFixed(1)}s` : '';
+                lines.push(...this.flush(vertex.digest), `#${step.number} DONE${seconds}`);
+            }
+        }
+        for (const log of status.logs) {
+            const output = (this.#pending.get(log.vertex) ?? '') + log.message.toString();
+            const parts = output.split(/\r?\n/);
+            this.#pending.set(log.vertex, parts.pop());
+            const number = this.step(log.vertex).number;
+            parts.forEach((part) => lines.push(`#${number} ${part}`));
+        }
+        for (const warning of status.warnings)
+            lines.push(`#${this.step(warning.vertex).number} WARN: ${warning.short}`);
+        return lines;
+    }
+    /**
+     * The incomplete last line of the output of a step
+     * @param digest
+     */
+    flush(digest) {
+        const pending = this.#pending.get(digest);
+        this.#pending.delete(digest);
+        return pending ? [`#${this.step(digest).number} ${pending}`] : [];
+    }
+}
+exports.BuildKitProgress = BuildKitProgress;

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

@@ -0,0 +1,196 @@
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { DockerConnection, type DockerConnectionOptions } from './DockerConnection.js';
+import { type ContainerCreateResponse } from './types/ContainerCreateResponse.js';
+import { type ContainerStopQuery } from './types/ContainerStopQuery.js';
+import { type IdResponse } from './types/IdResponse.js';
+import { type NetworkCreateResponse } from './types/NetworkCreateResponse.js';
+import { type RepositoryTag } from '../docker/types/RepositoryTag.js';
+/**
+ * The exception of a request the daemon refused: the not found exception of the resource missing (told by the daemon's
+ * message, else by the meaning of the status for the request), a DockerRequestException otherwise. The other errors
+ * (the network errors, the aborts) are given as they are
+ * @param error
+ */
+export declare function dockerException(error: unknown): unknown;
+/**
+ * The registry credentials of a request
+ */
+export type DockerRegistryAuth = {
+    username?: string;
+    password?: string;
+    serveraddress?: string;
+    email?: string;
+    identitytoken?: string;
+    registrytoken?: string;
+};
+/**
+ * The client of the Docker Engine API
+ */
+export declare class DockerClient {
+    #private;
+    readonly connection: DockerConnection;
+    constructor(options?: DockerConnectionOptions);
+    /**
+     * Whether the daemon answers
+     * @param signal
+     */
+    ping(signal?: AbortSignal): Promise<string>;
+    /**
+     * The versions of the daemon
+     */
+    version(): Promise<Record<string, any>>;
+    /**
+     * Check registry credentials (docker login)
+     * @param auth
+     */
+    checkAuth(auth: DockerRegistryAuth): Promise<Record<string, any>>;
+    /** Images **/
+    listImages(query?: Record<string, unknown>, signal?: AbortSignal): Promise<Record<string, any>[]>;
+    inspectImage(name: string, signal?: AbortSignal): Promise<Record<string, any>>;
+    /**
+     * Pull an image: the stream of the progress (docker pull)
+     * @param query fromImage, tag, platform
+     * @param auth
+     * @param signal
+     */
+    pullImage(query: Record<string, unknown>, auth?: DockerRegistryAuth, signal?: AbortSignal): Promise<IncomingMessage>;
+    /**
+     * Build an image: the stream of the progress
+     * @param context the gzipped tar archive of the context
+     * @param query dockerfile, t, platform, version...
+     * @param registryConfig the credentials of the registries, by server
+     * @param signal
+     */
+    buildImage(context: NodeJS.ReadableStream, query: Record<string, unknown>, registryConfig?: Record<string, DockerRegistryAuth>, signal?: AbortSignal): Promise<IncomingMessage>;
+    /**
+     * Load the images of a tar archive (docker load): the stream of the progress
+     * @param archive
+     * @param query quiet
+     */
+    loadImage(archive: NodeJS.ReadableStream, query?: Record<string, unknown>): Promise<IncomingMessage>;
+    /**
+     * The tar archive of an image (docker save)
+     * @param name
+     */
+    exportImage(name: string): Promise<IncomingMessage>;
+    tagImage(name: string, query: RepositoryTag): Promise<void>;
+    /**
+     * Push an image: the stream of the progress
+     * @param name
+     * @param query tag, platform
+     * @param auth
+     */
+    pushImage(name: string, query: Record<string, unknown>, auth?: DockerRegistryAuth): Promise<IncomingMessage>;
+    removeImage(name: string, query?: {
+        force?: boolean;
+        noprune?: boolean;
+    }): Promise<Record<string, any>[]>;
+    pruneImages(query?: Record<string, unknown>): Promise<Record<string, any>>;
+    /** Containers **/
+    listContainers(query?: Record<string, unknown>, signal?: AbortSignal): Promise<Record<string, any>[]>;
+    /**
+     * Create a container
+     * @param body its configuration
+     * @param query name, platform
+     */
+    createContainer(body: Record<string, unknown>, query?: {
+        name?: string;
+        platform?: string;
+    }): Promise<ContainerCreateResponse>;
+    inspectContainer(id: string, signal?: AbortSignal): Promise<Record<string, any>>;
+    /**
+     * Start a container: one already started is done (HTTP 304), as the Docker CLI does
+     * @param id
+     * @param signal
+     */
+    startContainer(id: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Stop a container: one already stopped is done (HTTP 304), as the Docker CLI does
+     * @param id
+     * @param query
+     * @param signal
+     */
+    stopContainer(id: string, query?: ContainerStopQuery, signal?: AbortSignal): Promise<void>;
+    restartContainer(id: string, query?: ContainerStopQuery, signal?: AbortSignal): Promise<void>;
+    pauseContainer(id: string): Promise<void>;
+    unpauseContainer(id: string): Promise<void>;
+    killContainer(id: string, query?: {
+        signal?: string;
+    }): Promise<void>;
+    removeContainer(id: string, query?: {
+        v?: boolean;
+        force?: boolean;
+        link?: boolean;
+    }): Promise<void>;
+    /**
+     * Rename a container
+     * @param id
+     * @param name
+     */
+    renameContainer(id: string, name: string): Promise<void>;
+    /**
+     * Update the resources and the restart policy of a container, live (docker update)
+     * @param id
+     * @param body
+     */
+    updateContainer(id: string, body: Record<string, unknown>): Promise<Record<string, any>>;
+    /**
+     * Create an image of a container (docker commit)
+     * @param id
+     * @param query repo, tag, comment, author, pause, changes
+     */
+    commitContainer(id: string, query?: Record<string, unknown>): Promise<IdResponse>;
+    /**
+     * The logs of a container: multiplexed when it has no TTY
+     * @param id
+     * @param query follow, stdout, stderr, since, until, timestamps, tail
+     */
+    containerLogs(id: string, query: Record<string, unknown>): Promise<IncomingMessage>;
+    /**
+     * The statistics of a container, once
+     * @param id
+     */
+    containerStats(id: string): Promise<Record<string, any>>;
+    /**
+     * The tar archive of a path of a container
+     * @param id
+     * @param query path
+     */
+    getArchive(id: string, query: {
+        path: string;
+    }): Promise<IncomingMessage>;
+    /**
+     * Create an execution in a container
+     * @param id
+     * @param body Cmd, AttachStdin, AttachStdout, AttachStderr, Tty, ConsoleSize...
+     */
+    createExec(id: string, body: Record<string, unknown>): Promise<IdResponse>;
+    /**
+     * Start an execution, attached: its stream, read (its output, multiplexed without TTY) and written (its input)
+     * @param execId
+     * @param body Detach, Tty
+     */
+    startExec(execId: string, body: {
+        Detach?: boolean;
+        Tty?: boolean;
+    }): Promise<Duplex>;
+    resizeExec(execId: string, query: {
+        h: number;
+        w: number;
+    }): Promise<void>;
+    inspectExec(execId: string): Promise<Record<string, any>>;
+    pruneContainers(query?: Record<string, unknown>): Promise<Record<string, any>>;
+    /** Networks **/
+    listNetworks(query?: Record<string, unknown>, signal?: AbortSignal): Promise<Record<string, any>[]>;
+    createNetwork(body: Record<string, unknown>): Promise<NetworkCreateResponse>;
+    inspectNetwork(id: string): Promise<Record<string, any>>;
+    removeNetwork(id: string): Promise<void>;
+    pruneNetworks(query?: Record<string, unknown>): Promise<Record<string, any>>;
+    /** Volumes **/
+    pruneVolumes(query?: Record<string, unknown>): Promise<Record<string, any>>;
+    /**
+     * Close the connections kept alive
+     */
+    close(): void;
+}