@lakutata/docker 3.0.0-beta.0

package/dist/cjs/client/DockerClient.js

@@ -0,0 +1,312 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DockerClient = void 0;
+exports.dockerException = dockerException;
+const DockerConnection_js_1 = require("./DockerConnection.js");
+const DockerRequestError_js_1 = require("./DockerRequestError.js");
+const DockerContainerNotFoundException_js_1 = require("../docker/exceptions/DockerContainerNotFoundException.js");
+const DockerImageNotFoundException_js_1 = require("../docker/exceptions/DockerImageNotFoundException.js");
+const DockerNetworkNotFoundException_js_1 = require("../docker/exceptions/DockerNetworkNotFoundException.js");
+const DockerRequestException_js_1 = require("../docker/exceptions/DockerRequestException.js");
+/**
+ * The status codes of the requests: the successes, and the reasons of the failures
+ */
+const SERVER_ERROR = { 500: 'server error' };
+const OK = { 200: true, 204: true };
+const NO_SUCH_IMAGE = { 404: 'no such image' };
+const NO_SUCH_CONTAINER = { 404: 'no such container' };
+const NO_SUCH_EXEC = { 404: 'no such exec' };
+const NO_SUCH_NETWORK = { 404: 'no such network' };
+/**
+ * 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
+ */
+function dockerException(error) {
+    if (!(error instanceof DockerRequestError_js_1.DockerRequestError))
+        return error;
+    if (error.statusCode === 404) {
+        //"No such container: x", "No such image: x", "network x not found" (also in the failure of a start)
+        const kind = /no such container/i.test(error.detail) ? 'container'
+            : /no such image/i.test(error.detail) ? 'image'
+                : /no such network|network \S+ not found/i.test(error.detail) ? 'network'
+                    : error.reason.replace(/^no such /, '');
+        if (kind === 'container')
+            return new DockerContainerNotFoundException_js_1.DockerContainerNotFoundException(error.detail);
+        if (kind === 'image')
+            return new DockerImageNotFoundException_js_1.DockerImageNotFoundException(error.detail);
+        if (kind === 'network')
+            return new DockerNetworkNotFoundException_js_1.DockerNetworkNotFoundException(error.detail);
+    }
+    return new DockerRequestException_js_1.DockerRequestException(error.statusCode, error.detail || error.message);
+}
+/**
+ * The client of the Docker Engine API
+ */
+class DockerClient {
+    constructor(options = {}) {
+        this.connection = new DockerConnection_js_1.DockerConnection(options);
+    }
+    /**
+     * A request whose response is JSON, its failure as the exception of the component
+     * @param request
+     */
+    async #request(request) {
+        try {
+            return await this.connection.request(request);
+        }
+        catch (e) {
+            throw dockerException(e);
+        }
+    }
+    /**
+     * A request whose response is a stream, its failure as the exception of the component
+     * @param request
+     */
+    async #stream(request) {
+        try {
+            return await this.connection.stream(request);
+        }
+        catch (e) {
+            throw dockerException(e);
+        }
+    }
+    /**
+     * A request upgraded to a raw stream, its failure as the exception of the component
+     * @param request
+     */
+    async #hijack(request) {
+        try {
+            return await this.connection.hijack(request);
+        }
+        catch (e) {
+            throw dockerException(e);
+        }
+    }
+    /**
+     * Whether the daemon answers
+     * @param signal
+     */
+    async ping(signal) {
+        return await this.#request({ method: 'GET', path: '/_ping', statusCodes: { 200: true, ...SERVER_ERROR }, signal: signal });
+    }
+    /**
+     * The versions of the daemon
+     */
+    async version() {
+        return await this.#request({ method: 'GET', path: '/version', statusCodes: { 200: true, ...SERVER_ERROR } });
+    }
+    /**
+     * Check registry credentials (docker login)
+     * @param auth
+     */
+    async checkAuth(auth) {
+        return await this.#request({ method: 'POST', path: '/auth', body: auth, statusCodes: { ...OK, ...SERVER_ERROR } });
+    }
+    /** Images **/
+    async listImages(query, signal) {
+        return await this.#request({ method: 'GET', path: '/images/json', query: query, statusCodes: { 200: true, 400: 'bad parameter', ...SERVER_ERROR }, signal: signal });
+    }
+    async inspectImage(name, signal) {
+        return await this.#request({ method: 'GET', path: `/images/${name}/json`, statusCodes: { 200: true, ...NO_SUCH_IMAGE, ...SERVER_ERROR }, signal: signal });
+    }
+    /**
+     * Pull an image: the stream of the progress (docker pull)
+     * @param query fromImage, tag, platform
+     * @param auth
+     * @param signal
+     */
+    async pullImage(query, auth, signal) {
+        return await this.#stream({ method: 'POST', path: '/images/create', query: query, auth: auth, statusCodes: { 200: true, ...SERVER_ERROR }, signal: signal });
+    }
+    /**
+     * 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
+     */
+    async buildImage(context, query, registryConfig, signal) {
+        return await this.#stream({ method: 'POST', path: '/build', query: query, body: context, registryConfig: registryConfig, statusCodes: { 200: true, ...SERVER_ERROR }, signal: signal });
+    }
+    /**
+     * Load the images of a tar archive (docker load): the stream of the progress
+     * @param archive
+     * @param query quiet
+     */
+    async loadImage(archive, query) {
+        return await this.#stream({ method: 'POST', path: '/images/load', query: query, body: archive, statusCodes: { 200: true, ...SERVER_ERROR } });
+    }
+    /**
+     * The tar archive of an image (docker save)
+     * @param name
+     */
+    async exportImage(name) {
+        return await this.#stream({ method: 'GET', path: `/images/${name}/get`, statusCodes: { 200: true, ...SERVER_ERROR } });
+    }
+    async tagImage(name, query) {
+        await this.#request({ method: 'POST', path: `/images/${name}/tag`, query: query, statusCodes: { 200: true, 201: true, 400: 'bad parameter', ...NO_SUCH_IMAGE, 409: 'conflict', ...SERVER_ERROR } });
+    }
+    /**
+     * Push an image: the stream of the progress
+     * @param name
+     * @param query tag, platform
+     * @param auth
+     */
+    async pushImage(name, query, auth) {
+        return await this.#stream({ method: 'POST', path: `/images/${name}/push`, query: query, auth: (auth ?? {}), statusCodes: { 200: true, ...NO_SUCH_IMAGE, ...SERVER_ERROR } });
+    }
+    async removeImage(name, query) {
+        return await this.#request({ method: 'DELETE', path: `/images/${name}`, query: query, statusCodes: { 200: true, ...NO_SUCH_IMAGE, 409: 'conflict', ...SERVER_ERROR } });
+    }
+    async pruneImages(query) {
+        return await this.#request({ method: 'POST', path: '/images/prune', query: query, statusCodes: { 200: true, ...SERVER_ERROR } });
+    }
+    /** Containers **/
+    async listContainers(query, signal) {
+        return await this.#request({ method: 'GET', path: '/containers/json', query: query, statusCodes: { 200: true, 400: 'bad parameter', ...SERVER_ERROR }, signal: signal });
+    }
+    /**
+     * Create a container
+     * @param body its configuration
+     * @param query name, platform
+     */
+    async createContainer(body, query) {
+        return await this.#request({ method: 'POST', path: '/containers/create', query: query, body: body, statusCodes: { 200: true, 201: true, 400: 'bad parameter', ...NO_SUCH_IMAGE, 409: 'conflict', ...SERVER_ERROR } });
+    }
+    async inspectContainer(id, signal) {
+        return await this.#request({ method: 'GET', path: `/containers/${id}/json`, statusCodes: { 200: true, ...NO_SUCH_CONTAINER, ...SERVER_ERROR }, signal: signal });
+    }
+    /**
+     * Start a container: one already started is done (HTTP 304), as the Docker CLI does
+     * @param id
+     * @param signal
+     */
+    async startContainer(id, signal) {
+        await this.#request({ method: 'POST', path: `/containers/${id}/start`, statusCodes: { ...OK, 304: true, ...NO_SUCH_CONTAINER, ...SERVER_ERROR }, signal: signal });
+    }
+    /**
+     * Stop a container: one already stopped is done (HTTP 304), as the Docker CLI does
+     * @param id
+     * @param query
+     * @param signal
+     */
+    async stopContainer(id, query, signal) {
+        await this.#request({ method: 'POST', path: `/containers/${id}/stop`, query: query, statusCodes: { ...OK, 304: true, ...NO_SUCH_CONTAINER, ...SERVER_ERROR }, signal: signal });
+    }
+    async restartContainer(id, query, signal) {
+        await this.#request({ method: 'POST', path: `/containers/${id}/restart`, query: query, statusCodes: { ...OK, ...NO_SUCH_CONTAINER, ...SERVER_ERROR }, signal: signal });
+    }
+    async pauseContainer(id) {
+        await this.#request({ method: 'POST', path: `/containers/${id}/pause`, statusCodes: { ...OK, ...NO_SUCH_CONTAINER, ...SERVER_ERROR } });
+    }
+    async unpauseContainer(id) {
+        await this.#request({ method: 'POST', path: `/containers/${id}/unpause`, statusCodes: { ...OK, ...NO_SUCH_CONTAINER, ...SERVER_ERROR } });
+    }
+    async killContainer(id, query) {
+        await this.#request({ method: 'POST', path: `/containers/${id}/kill`, query: query, statusCodes: { ...OK, ...NO_SUCH_CONTAINER, ...SERVER_ERROR } });
+    }
+    async removeContainer(id, query) {
+        await this.#request({ method: 'DELETE', path: `/containers/${id}`, query: query, statusCodes: { ...OK, 400: 'bad parameter', ...NO_SUCH_CONTAINER, ...SERVER_ERROR } });
+    }
+    /**
+     * Rename a container
+     * @param id
+     * @param name
+     */
+    async renameContainer(id, name) {
+        await this.#request({ method: 'POST', path: `/containers/${id}/rename`, query: { name: name }, statusCodes: { ...OK, ...NO_SUCH_CONTAINER, 409: 'name already in use', ...SERVER_ERROR } });
+    }
+    /**
+     * Update the resources and the restart policy of a container, live (docker update)
+     * @param id
+     * @param body
+     */
+    async updateContainer(id, body) {
+        return await this.#request({ method: 'POST', path: `/containers/${id}/update`, body: body, statusCodes: { ...OK, 400: 'bad parameter', ...NO_SUCH_CONTAINER, ...SERVER_ERROR } });
+    }
+    /**
+     * Create an image of a container (docker commit)
+     * @param id
+     * @param query repo, tag, comment, author, pause, changes
+     */
+    async commitContainer(id, query) {
+        return await this.#request({ method: 'POST', path: '/commit', query: { ...query, container: id }, statusCodes: { 200: true, 201: true, ...NO_SUCH_CONTAINER, ...SERVER_ERROR } });
+    }
+    /**
+     * The logs of a container: multiplexed when it has no TTY
+     * @param id
+     * @param query follow, stdout, stderr, since, until, timestamps, tail
+     */
+    async containerLogs(id, query) {
+        return await this.#stream({ method: 'GET', path: `/containers/${id}/logs`, query: query, statusCodes: { 200: true, ...NO_SUCH_CONTAINER, ...SERVER_ERROR } });
+    }
+    /**
+     * The statistics of a container, once
+     * @param id
+     */
+    async containerStats(id) {
+        return await this.#request({ method: 'GET', path: `/containers/${id}/stats`, query: { 'stream': false, 'one-shot': true }, statusCodes: { 200: true, ...NO_SUCH_CONTAINER, ...SERVER_ERROR } });
+    }
+    /**
+     * The tar archive of a path of a container
+     * @param id
+     * @param query path
+     */
+    async getArchive(id, query) {
+        return await this.#stream({ method: 'GET', path: `/containers/${id}/archive`, query: query, statusCodes: { 200: true, 400: 'client error, bad parameters', ...NO_SUCH_CONTAINER, ...SERVER_ERROR } });
+    }
+    /**
+     * Create an execution in a container
+     * @param id
+     * @param body Cmd, AttachStdin, AttachStdout, AttachStderr, Tty, ConsoleSize...
+     */
+    async createExec(id, body) {
+        return await this.#request({ method: 'POST', path: `/containers/${id}/exec`, body: body, statusCodes: { 200: true, 201: true, ...NO_SUCH_CONTAINER, 409: 'container stopped/paused', ...SERVER_ERROR } });
+    }
+    /**
+     * Start an execution, attached: its stream, read (its output, multiplexed without TTY) and written (its input)
+     * @param execId
+     * @param body Detach, Tty
+     */
+    async startExec(execId, body) {
+        return await this.#hijack({ method: 'POST', path: `/exec/${execId}/start`, body: body, statusCodes: { ...OK, ...NO_SUCH_EXEC, 409: 'container stopped/paused', 500: 'container not running' } });
+    }
+    async resizeExec(execId, query) {
+        await this.#request({ method: 'POST', path: `/exec/${execId}/resize`, query: query, statusCodes: { ...OK, ...NO_SUCH_EXEC, 500: 'container not running' } });
+    }
+    async inspectExec(execId) {
+        return await this.#request({ method: 'GET', path: `/exec/${execId}/json`, statusCodes: { 200: true, ...NO_SUCH_EXEC, ...SERVER_ERROR } });
+    }
+    async pruneContainers(query) {
+        return await this.#request({ method: 'POST', path: '/containers/prune', query: query, statusCodes: { 200: true, ...SERVER_ERROR } });
+    }
+    /** Networks **/
+    async listNetworks(query, signal) {
+        return await this.#request({ method: 'GET', path: '/networks', query: query, statusCodes: { 200: true, 400: 'bad parameter', ...SERVER_ERROR }, signal: signal });
+    }
+    async createNetwork(body) {
+        return await this.#request({ method: 'POST', path: '/networks/create', body: body, statusCodes: { 200: true, 201: true, 404: 'driver not found', ...SERVER_ERROR } });
+    }
+    async inspectNetwork(id) {
+        return await this.#request({ method: 'GET', path: `/networks/${id}`, statusCodes: { 200: true, ...NO_SUCH_NETWORK, ...SERVER_ERROR } });
+    }
+    async removeNetwork(id) {
+        await this.#request({ method: 'DELETE', path: `/networks/${id}`, statusCodes: { ...OK, ...NO_SUCH_NETWORK, 409: 'conflict', ...SERVER_ERROR } });
+    }
+    async pruneNetworks(query) {
+        return await this.#request({ method: 'POST', path: '/networks/prune', query: query, statusCodes: { 200: true, ...SERVER_ERROR } });
+    }
+    /** Volumes **/
+    async pruneVolumes(query) {
+        return await this.#request({ method: 'POST', path: '/volumes/prune', query: query, statusCodes: { 200: true, ...SERVER_ERROR } });
+    }
+    /**
+     * Close the connections kept alive
+     */
+    close() {
+        this.connection.close();
+    }
+}
+exports.DockerClient = DockerClient;

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

@@ -0,0 +1,154 @@
+import { type Agent, type ClientRequest, type IncomingMessage, type RequestOptions } from 'node:http';
+import { Duplex } from 'node:stream';
+import { DockerRequestError } from './DockerRequestError.js';
+/**
+ * A key of a TLS connection with its passphrase
+ */
+export type DockerKeyObject = {
+    pem: string | Buffer;
+    passphrase?: string;
+};
+export type DockerConnectionOptions = {
+    /**
+     * The socket of the Docker daemon (a Unix socket, or a named pipe on Windows)
+     */
+    socketPath?: string;
+    /**
+     * The host of the Docker daemon (tcp, https, ssh)
+     */
+    host?: string;
+    port?: number | string;
+    protocol?: 'http' | 'https' | 'ssh';
+    /**
+     * The user of the SSH connection
+     */
+    username?: string;
+    password?: string;
+    /**
+     * The SSH agent socket, the one of SSH_AUTH_SOCK by default
+     */
+    sshAuthAgent?: string;
+    headers?: Record<string, string>;
+    ca?: string | string[] | Buffer | Buffer[];
+    cert?: string | string[] | Buffer | Buffer[];
+    key?: string | string[] | Buffer | Buffer[] | DockerKeyObject[];
+    /**
+     * The timeout of the requests, in milliseconds
+     */
+    timeout?: number;
+    /**
+     * The API version ("1.47", or "v1.47"), negotiated with the daemon by default
+     */
+    version?: string;
+};
+/**
+ * A request to the Engine API
+ */
+export type DockerRequest = {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD';
+    path: string;
+    /**
+     * The query parameters: the objects are JSON encoded, the arrays repeat their parameter, the undefined ones are omitted
+     */
+    query?: Record<string, unknown>;
+    /**
+     * A JSON body, or a stream sent as it is (a tar archive)
+     */
+    body?: unknown;
+    headers?: Record<string, string>;
+    /**
+     * The registry credentials of the request (X-Registry-Auth)
+     */
+    auth?: Record<string, unknown>;
+    /**
+     * The registry credentials of a build (X-Registry-Config)
+     */
+    registryConfig?: Record<string, unknown>;
+    /**
+     * The meanings of the status codes: true for a success, the reason of the failure otherwise
+     */
+    statusCodes: Record<number, true | string>;
+    signal?: AbortSignal;
+};
+/**
+ * The newest API version this client is tested with (Docker 29.8): the one negotiated when the daemon supports it, so that
+ * a newer daemon answers as the tested one. An older daemon answers with its version: the fields a version does not have
+ * are missing or null
+ */
+export declare const DOCKER_API_VERSION: string;
+/**
+ * The oldest API version this client works with
+ */
+export declare const DOCKER_MIN_API_VERSION: string;
+/**
+ * Compare two API versions
+ * @param a
+ * @param b
+ */
+export declare function compareAPIVersions(a: string, b: string): number;
+/**
+ * The connection options given by the environment (DOCKER_HOST, DOCKER_TLS_VERIFY, DOCKER_CERT_PATH,
+ * DOCKER_CLIENT_TIMEOUT), else the socket of the platform: the named pipe on Windows, the socket of the user (Docker
+ * Desktop) or /var/run/docker.sock
+ */
+export declare function defaultConnectionOptions(): DockerConnectionOptions;
+/**
+ * The connection to a Docker daemon
+ */
+export declare class DockerConnection {
+    #private;
+    constructor(options?: DockerConnectionOptions);
+    /**
+     * The API version of the requests, once negotiated
+     */
+    get version(): string | undefined;
+    /**
+     * Negotiate the API version with the daemon: the newest one both support
+     */
+    negotiate(): Promise<string>;
+    /**
+     * The agent of an SSH connection: the requests are sent to "docker system dial-stdio" (ssh2, an optional dependency)
+     */
+    protected sshAgent(): Promise<Agent>;
+    /**
+     * The options of a request
+     * @param request
+     * @param streamingBody
+     */
+    protected requestOptions(request: DockerRequest, streamingBody: boolean): Promise<RequestOptions>;
+    /**
+     * Send a request: the response, once its status is known
+     * @param request
+     * @param hijack upgrade the connection to a raw stream (the TTYs, the attached executions)
+     */
+    protected send(request: DockerRequest, hijack?: boolean): Promise<{
+        response?: IncomingMessage;
+        socket?: Duplex;
+        request: ClientRequest;
+    }>;
+    /**
+     * The error of a failed response
+     * @param request
+     * @param response
+     */
+    protected failure(request: DockerRequest, response: IncomingMessage): Promise<DockerRequestError>;
+    /**
+     * A request whose response is JSON (or nothing)
+     * @param request
+     */
+    request<T = any>(request: DockerRequest): Promise<T>;
+    /**
+     * A request whose response is a stream (the progress of a pull, the logs, an archive)
+     * @param request
+     */
+    stream(request: DockerRequest): Promise<IncomingMessage>;
+    /**
+     * A request upgraded to a raw stream, read and written (the TTYs, the attached executions)
+     * @param request
+     */
+    hijack(request: DockerRequest): Promise<Duplex>;
+    /**
+     * Close the kept alive connections
+     */
+    close(): void;
+}