@zukhruf/docker 0.3.33 → 0.3.34

package/dist/containers.js

@@ -0,0 +1,700 @@
+import { posix } from 'node:path';
+import { setTimeout } from 'node:timers/promises';
+import { poll } from '@zukhruf/async';
+import { ContainerProcess } from "./container-process.js";
+import { isSuccess, parseBody, } from "./engine-client.js";
+import { BindSourceNotFoundError, ContainerNotFoundError, ContainerNotRunningError, ContainerRunningError, DockerEngineError, DockerError, ImageNotFoundError, NameConflictError, NetworkNotFoundError, NotAFileError, PathNotFoundError, ReadOnlyPathError, } from "./errors.js";
+import { outputChunks } from "./multiplexed-stream.js";
+import { readOutput } from "./output.js";
+import { tarEntries } from "./tar-reader.js";
+import { tarArchive } from "./tar-writer.js";
+/** The path stat in the header of an archive answer: base64 of JSON. */
+function pathStat(headers) {
+    const header = headers['x-docker-container-path-stat'];
+    if (typeof header !== 'string')
+        return undefined;
+    const stat = JSON.parse(Buffer.from(header, 'base64').toString('utf8'));
+    return stat;
+}
+/** The deepest directory that holds each of the paths. */
+function commonDirectory(paths) {
+    const [first = [], ...rest] = paths.map((path) => path.split('/').filter(Boolean));
+    const common = [];
+    for (const [index, part] of first.entries()) {
+        if (!rest.every((other) => other[index] === part))
+            break;
+        common.push(part);
+    }
+    return `/${common.join('/')}`;
+}
+/** True when the directory is in a read-only mount, or on a read-only root filesystem outside each mount. */
+function isReadOnly(container, directory) {
+    const holding = (container.Mounts ?? [])
+        .filter(({ Destination }) => {
+        if (Destination === undefined)
+            return false;
+        return (directory === Destination ||
+            directory.startsWith(Destination.endsWith('/') ? Destination : `${Destination}/`));
+    })
+        .toSorted((left, right) => (right.Destination?.length ?? 0) - (left.Destination?.length ?? 0))[0];
+    if (holding !== undefined)
+        return holding.RW === false;
+    return container.HostConfig?.ReadonlyRootfs === true;
+}
+async function* bytesOf(response) {
+    for await (const chunk of response) {
+        if (chunk instanceof Uint8Array)
+            yield chunk;
+    }
+}
+/** The time between two inspects of an exec whose output ended while the engine still reports it running. */
+const EXEC_EXIT_DELAY_MS = 10;
+/** The time between two inspects of a container whose removal is in progress. */
+const REMOVAL_POLL_MS = 50;
+/** The time between two tries of createOrGet() while the name is taken but an inspect does not find it. */
+const NAME_RACE_DELAY_MS = 20;
+/** The fixed text of Moby for a missing bind source: errBindSourceDoesNotExist in daemon/volume/mounts/validate.go. */
+const BIND_SOURCE_NOT_FOUND = /bind source path does not exist: (.+)$/;
+/**
+ * The BindSourceNotFoundError of an answer, or the DockerEngineError. The
+ * engine gives a missing bind source the status of each bad parameter, so
+ * only its text tells it apart.
+ */
+function bindSourceOr(error) {
+    const source = BIND_SOURCE_NOT_FOUND.exec(error.message)?.[1];
+    if (source === undefined)
+        return error;
+    return new BindSourceNotFoundError(error.message, error, source, {
+        cause: error,
+    });
+}
+/** The address of the loopback interface of the same family, for an address that binds each interface. */
+function reachableHost(hostIp) {
+    if (hostIp === undefined || hostIp === '' || hostIp === '0.0.0.0') {
+        return '127.0.0.1';
+    }
+    if (hostIp === '::')
+        return '::1';
+    return hostIp;
+}
+/** The network modes that name no network of the caller. */
+const PREDEFINED_NETWORK_MODES = new Set(['default', 'bridge', 'host', 'none']);
+/**
+ * The names of the networks of a container: its network mode, when it names a
+ * network, and each network of its endpoints.
+ */
+function networksOf(container) {
+    const mode = container.HostConfig?.NetworkMode;
+    const networks = new Set();
+    if (mode !== undefined &&
+        mode !== '' &&
+        !PREDEFINED_NETWORK_MODES.has(mode) &&
+        !mode.startsWith('container:')) {
+        networks.add(mode);
+    }
+    for (const name of Object.keys(container.NetworkSettings?.Networks ?? {})) {
+        networks.add(name);
+    }
+    return [...networks];
+}
+/** A container, by the ID that the engine gave it. It has no disposal. */
+export class Container {
+    id;
+    #client;
+    constructor(client, id) {
+        this.#client = client;
+        this.id = id;
+    }
+    get #path() {
+        return `/containers/${encodeURIComponent(this.id)}`;
+    }
+    async inspect(options = {}) {
+        const method = 'GET';
+        const path = `${this.#path}/json`;
+        const response = await this.#client.exchange(method, path, options);
+        this.#throwUnless(response, method, path);
+        return parseBody(response);
+    }
+    /**
+     * Resolves for 304 (already running). A 404 is a missing container or a
+     * missing network: an inspect of the container tells which, and a lookup of
+     * each of its networks names the missing one. An engine in swarm mode
+     * answers a missing network with 500 ("Could not attach to network", probed
+     * at API 1.51), so a 500 gets the same lookup.
+     */
+    async start(options = {}) {
+        const { signal } = options;
+        const method = 'POST';
+        const path = `${this.#path}/start`;
+        const response = await this.#client.exchange(method, path, { signal });
+        if (response.status === 304 || isSuccess(response))
+            return;
+        const error = this.#client.error(response, method, path);
+        if (response.status !== 404 && response.status !== 500) {
+            throw bindSourceOr(error);
+        }
+        const inspect = await this.#client.exchange('GET', `${this.#path}/json`, {
+            signal,
+        });
+        if (inspect.status === 404 && response.status === 404) {
+            this.#throwUnless(response, method, path);
+        }
+        if (!isSuccess(inspect))
+            throw bindSourceOr(error);
+        const container = parseBody(inspect);
+        for (const network of networksOf(container)) {
+            const lookup = await this.#client.exchange('GET', `/networks/${encodeURIComponent(network)}`, { signal });
+            if (lookup.status === 404) {
+                throw new NetworkNotFoundError(error.message, { status: response.status, request: { method, path } }, network, { cause: error });
+            }
+        }
+        throw bindSourceOr(error);
+    }
+    /** Resolves for 304 (already stopped). t: seconds before the engine kills the main process. */
+    async stop(options = {}) {
+        const method = 'POST';
+        const path = `${this.#path}/stop`;
+        const response = await this.#client.exchange(method, path, {
+            query: { t: options.t },
+            signal: options.signal,
+        });
+        if (response.status === 304)
+            return;
+        this.#throwUnless(response, method, path);
+    }
+    async restart(options = {}) {
+        await this.#post('restart', { t: options.t }, options);
+    }
+    /** A 409 means that the container does not run: an inspect gives its state. */
+    async kill(processSignal = 'SIGKILL', options = {}) {
+        const method = 'POST';
+        const path = `${this.#path}/kill`;
+        const response = await this.#client.exchange(method, path, {
+            query: { signal: processSignal },
+            signal: options.signal,
+        });
+        if (response.status === 409) {
+            throw await this.#notRunning(this.#client.error(response, method, path), options);
+        }
+        this.#throwUnless(response, method, path);
+    }
+    async pause(options = {}) {
+        await this.#post('pause', {}, options);
+    }
+    async unpause(options = {}) {
+        await this.#post('unpause', {}, options);
+    }
+    async wait(options = {}) {
+        const method = 'POST';
+        const path = `${this.#path}/wait`;
+        const response = await this.#client.exchange(method, path, {
+            query: { condition: options.condition },
+            signal: options.signal,
+        });
+        this.#throwUnless(response, method, path);
+        return parseBody(response);
+    }
+    /**
+     * Resolves for 404. A 409 is a removal that is already in progress, or,
+     * without `force`, a container that runs: an inspect tells which. For a
+     * removal in progress, it inspects the container until it is gone, and
+     * when the other removal ends and leaves the container, it sends a forced
+     * removal again. A container
+     * that runs or is paused rejects with ContainerRunningError. The engine
+     * gives the state 'running' while it kills the container for a forced
+     * removal, so with `force` the state alone does not tell: it waits.
+     */
+    async remove(options = {}) {
+        const { force, signal } = options;
+        const method = 'DELETE';
+        const path = this.#path;
+        const response = await this.#client.exchange(method, path, {
+            query: { force, v: options.v },
+            signal,
+        });
+        if (isSuccess(response) || response.status === 404)
+            return;
+        const error = this.#client.error(response, method, path);
+        if (response.status !== 409)
+            throw error;
+        const inspect = await this.#client.exchange('GET', `${path}/json`, {
+            signal,
+        });
+        if (inspect.status === 404)
+            return;
+        const state = parseBody(inspect).State;
+        const runs = state?.Running === true || state?.Paused === true;
+        if (force !== true && runs) {
+            throw new ContainerRunningError(error.message, { status: 409, request: { method, path } }, this.id, { cause: error });
+        }
+        // A wait for 'removed' never returns when the other removal fails and
+        // leaves the container dead, so inspects tell when the container is gone.
+        await poll(async () => {
+            const current = await this.#client.exchange('GET', `${path}/json`, {
+                signal,
+            });
+            if (current.status === 404)
+                return true;
+            if (!isSuccess(current)) {
+                throw this.#client.error(current, 'GET', `${path}/json`);
+            }
+            const status = parseBody(current).State?.Status;
+            if (status === 'removing')
+                return undefined;
+            // The other removal ended and the container stays: remove it again.
+            const again = await this.#client.exchange(method, path, {
+                query: { force: true, v: options.v },
+                signal,
+            });
+            if (isSuccess(again) || again.status === 404)
+                return true;
+            if (again.status === 409)
+                return undefined;
+            throw this.#client.error(again, method, path);
+        }, { interval: REMOVAL_POLL_MS, signal });
+    }
+    /** The published binding of a port of the container; undefined when it is not published. The IPv4 binding comes first. */
+    async port(containerPort, protocol = 'tcp', options = {}) {
+        const { NetworkSettings } = await this.inspect(options);
+        const bindings = (NetworkSettings?.Ports?.[`${containerPort}/${protocol}`] ?? []).filter((binding) => binding.HostPort);
+        const binding = bindings.find((each) => !each.HostIp?.includes(':')) ?? bindings[0];
+        if (binding === undefined)
+            return undefined;
+        return {
+            host: reachableHost(binding.HostIp),
+            port: Number(binding.HostPort),
+        };
+    }
+    /** The logs until now. */
+    async logs(options = {}) {
+        return readOutput(this.#logs(false, options));
+    }
+    /** The logs as the container writes them. The iteration ends when the container stops. */
+    followLogs(options = {}) {
+        return this.#logs(true, options);
+    }
+    async *#logs(follow, options) {
+        const { signal, tail, since, timestamps } = options;
+        const method = 'GET';
+        const path = `${this.#path}/logs`;
+        const response = await this.#client
+            .stream(method, path, {
+            query: {
+                stdout: 1,
+                stderr: 1,
+                follow: follow ? 1 : 0,
+                tail,
+                since,
+                timestamps,
+            },
+            signal,
+        })
+            .catch((error) => {
+            throw this.#notFoundOr(error, method, path);
+        });
+        yield* outputChunks(response, response.headers['content-type'] ?? '');
+    }
+    /** Runs a command in the container and reads its output to the end. stdin is sent, and then the input ends. */
+    async exec(body, options = {}) {
+        const { stdin, signal } = options;
+        const process = await this.spawn(body, {
+            ...options,
+            stdin: stdin !== undefined,
+        });
+        const input = process.stdin;
+        if (input === undefined || stdin === undefined)
+            return process.collect();
+        const bytes = typeof stdin === 'string' ? new TextEncoder().encode(stdin) : stdin;
+        const writing = (async () => {
+            const writer = input.getWriter();
+            await writer.write(bytes);
+            await writer.close();
+        })();
+        // A command can end before it reads all of its input, such as `true` or
+        // `head -c1`. The write then fails, but the output and the exit code are
+        // complete: the result stands.
+        const [result] = await Promise.allSettled([process.collect(), writing]);
+        if (result.status === 'rejected')
+            throw result.reason;
+        return result.value;
+    }
+    /** Runs a command in the container and gives its container process while it runs. */
+    async spawn(body, options = {}) {
+        const { signal } = options;
+        const stdin = options.stdin === true;
+        const method = 'POST';
+        const path = `${this.#path}/exec`;
+        const created = await this.#client.exchange(method, path, {
+            body: {
+                ...body,
+                AttachStdin: stdin,
+                AttachStdout: true,
+                AttachStderr: true,
+            },
+            signal,
+        });
+        if (created.status === 409) {
+            throw await this.#notRunning(this.#client.error(created, method, path), options);
+        }
+        this.#throwUnless(created, method, path);
+        const { Id } = parseBody(created);
+        const exec = `/exec/${encodeURIComponent(Id)}`;
+        // The container can stop between the create and the start of the exec: the start then gets 409.
+        const connection = await this.#client
+            .hijack('POST', `${exec}/start`, {
+            body: { Detach: false, Tty: body.Tty ?? false },
+            signal,
+        })
+            .catch(async (error) => {
+            if (error instanceof DockerEngineError && error.status === 409) {
+                throw await this.#notRunning(error, options);
+            }
+            throw error;
+        });
+        return new ContainerProcess(connection, {
+            stdin,
+            signal,
+            exitCode: async (outputEnded) => {
+                await outputEnded;
+                for (;;) {
+                    const inspect = await this.#client.json('GET', `${exec}/json`, { signal });
+                    if (!inspect.Running && inspect.ExitCode !== null) {
+                        return inspect.ExitCode;
+                    }
+                    await setTimeout(EXEC_EXIT_DELAY_MS, undefined, { signal });
+                }
+            },
+        });
+    }
+    /**
+     * Attaches to the output of the container. For a created container, the
+     * exit code is the code of its next exit, so attach before start(). For a
+     * running container, it is the code when the container stops. An exited or
+     * a paused container rejects with ContainerNotRunningError: Moby gives no
+     * 409 for an attach to an exited container, so the state of an inspect
+     * decides.
+     */
+    async attach(options = {}) {
+        const { signal } = options;
+        const stdin = options.stdin === true;
+        const method = 'POST';
+        const path = `${this.#path}/attach`;
+        const state = (await this.inspect(options)).State?.Status ?? '';
+        if (state !== 'created' && state !== 'running') {
+            throw new ContainerNotRunningError(`The container ${this.id} is ${state}.`, { status: undefined, request: { method, path } }, this.id, state);
+        }
+        // The engine sends the headers of a wait when the wait is in place, so a
+        // start() after attach() resolves cannot pass before it.
+        const waiting = await this.#client
+            .stream('POST', `${this.#path}/wait`, {
+            query: { condition: state === 'created' ? 'next-exit' : 'not-running' },
+            signal,
+        })
+            .catch((error) => {
+            throw this.#notFoundOr(error, 'POST', `${this.#path}/wait`);
+        });
+        const connection = await this.#client
+            .hijack(method, path, {
+            query: { stream: 1, stdout: 1, stderr: 1, stdin: stdin ? 1 : 0 },
+            signal,
+        })
+            .catch(async (error) => {
+            waiting.destroy();
+            if (error instanceof DockerEngineError && error.status === 409) {
+                throw await this.#notRunning(error, options);
+            }
+            throw this.#notFoundOr(error, method, path);
+        });
+        return new ContainerProcess(connection, {
+            stdin,
+            signal,
+            exitCode: async (outputEnded) => {
+                outputEnded.catch(() => waiting.destroy());
+                const chunks = [];
+                for await (const chunk of waiting)
+                    chunks.push(Buffer.from(chunk));
+                const answer = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+                return answer.StatusCode;
+            },
+        });
+    }
+    /** The path stat of a path in the container: HEAD of the archive. undefined for 404 when the container exists. */
+    async stat(path, options = {}) {
+        const method = 'HEAD';
+        const requestPath = `${this.#path}/archive`;
+        const response = await this.#client.exchange(method, requestPath, {
+            query: { path },
+            signal: options.signal,
+        });
+        const answer = {
+            status: response.status,
+            request: { method, path: requestPath },
+        };
+        // An answer to HEAD has no body, so the message is written here.
+        const message = `The engine answered ${response.status} to the stat of ${path} in the container ${this.id}.`;
+        if (response.status === 404) {
+            const error = await this.#fileNotFound(new DockerEngineError(message, answer), path, options);
+            if (error instanceof PathNotFoundError)
+                return undefined;
+            throw error;
+        }
+        const stat = isSuccess(response) ? pathStat(response.headers) : undefined;
+        if (stat === undefined)
+            throw new DockerEngineError(message, answer);
+        return stat;
+    }
+    /** The bytes of one regular file. A directory, a link and each other kind of entry reject with NotAFileError. */
+    async readFile(path, options = {}) {
+        const method = 'GET';
+        const requestPath = `${this.#path}/archive`;
+        const response = await this.#archive(path, options);
+        // The first entry of the archive is the path itself, so a directory fails before its tree comes.
+        for await (const entry of tarEntries(bytesOf(response))) {
+            if (entry.type === 'file')
+                return entry.data;
+            throw new NotAFileError(`${path} in the container ${this.id} is a ${entry.type}, not a regular file.`, { status: response.statusCode, request: { method, path: requestPath } }, this.id, path, entry.type);
+        }
+        throw new DockerError(`The archive of ${path} in the container ${this.id} has no entry.`);
+    }
+    /**
+     * Sends one archive of the files. It extracts the archive in the deepest
+     * directory that holds each entry and that exists, which stat() finds. The
+     * engine creates each parent directory that an entry implies below it.
+     */
+    async writeFiles(files, options = {}) {
+        if (files.length === 0)
+            return;
+        const mtime = Math.floor(Date.now() / 1000);
+        const absolute = files.map((file) => ({
+            file,
+            path: posix.resolve('/', file.path),
+        }));
+        let directory = commonDirectory(absolute.map(({ path }) => posix.dirname(path)));
+        while (directory !== '/' &&
+            (await this.stat(directory, options)) === undefined) {
+            directory = posix.dirname(directory);
+        }
+        const entries = absolute.map(({ file, path }) => {
+            const isDirectory = 'directory' in file;
+            return {
+                path: posix.relative(directory, path),
+                type: isDirectory ? 'directory' : 'file',
+                data: isDirectory
+                    ? new Uint8Array(0)
+                    : typeof file.data === 'string'
+                        ? new TextEncoder().encode(file.data)
+                        : file.data,
+                mode: file.mode ?? (isDirectory ? 0o755 : 0o644),
+                uid: file.uid ?? 0,
+                gid: file.gid ?? 0,
+                mtime,
+            };
+        });
+        await this.putArchive(directory, tarArchive(entries), options);
+    }
+    /** The tar stream of a path in the container: a file, or a directory with its tree. */
+    async getArchive(path, options = {}) {
+        return ReadableStream.from(bytesOf(await this.#archive(path, options)));
+    }
+    /**
+     * Extracts a tar archive in a directory of the container. With copyUIDGID,
+     * each entry belongs to the user of the container (Config.User), not to
+     * the owner in the archive.
+     */
+    async putArchive(directory, archive, options = {}) {
+        const { signal } = options;
+        const method = 'PUT';
+        const requestPath = `${this.#path}/archive`;
+        const response = await this.#client.exchange(method, requestPath, {
+            query: {
+                path: directory,
+                copyUIDGID: options.copyUIDGID === true ? 1 : undefined,
+            },
+            content: { type: 'application/x-tar', data: archive },
+            signal,
+        });
+        if (isSuccess(response))
+            return;
+        const error = this.#client.error(response, method, requestPath);
+        if (response.status === 404) {
+            throw await this.#fileNotFound(error, directory, options);
+        }
+        // Moby answers a refused extraction with 400; the reference says 403.
+        if (response.status !== 400 && response.status !== 403)
+            throw error;
+        const inspect = await this.#client.exchange('GET', `${this.#path}/json`, {
+            signal,
+        });
+        if (inspect.status === 404) {
+            throw new ContainerNotFoundError(error.message, error, this.id, {
+                cause: error,
+            });
+        }
+        if (isSuccess(inspect) &&
+            isReadOnly(parseBody(inspect), directory)) {
+            throw new ReadOnlyPathError(error.message, error, this.id, directory, {
+                cause: error,
+            });
+        }
+        throw error;
+    }
+    /** The answer of GET of the archive of a path, with 404 as ContainerNotFoundError or PathNotFoundError. */
+    async #archive(path, options) {
+        try {
+            return await this.#client.stream('GET', `${this.#path}/archive`, {
+                query: { path },
+                signal: options.signal,
+            });
+        }
+        catch (error) {
+            if (error instanceof DockerEngineError && error.status === 404) {
+                throw await this.#fileNotFound(error, path, options);
+            }
+            throw error;
+        }
+    }
+    /** A 404 of a file request: an inspect tells a missing container from a missing path. */
+    async #fileNotFound(error, path, options) {
+        const inspect = await this.#client.exchange('GET', `${this.#path}/json`, {
+            signal: options.signal,
+        });
+        if (inspect.status === 404) {
+            return new ContainerNotFoundError(error.message, error, this.id, {
+                cause: error,
+            });
+        }
+        return new PathNotFoundError(error.message, error, this.id, path, {
+            cause: error,
+        });
+    }
+    /** A DockerEngineError with 404 as a ContainerNotFoundError; each other error as it is. */
+    #notFoundOr(error, method, path) {
+        if (!(error instanceof DockerEngineError) || error.status !== 404) {
+            return error;
+        }
+        return new ContainerNotFoundError(error.message, { status: 404, request: { method, path } }, this.id, { cause: error });
+    }
+    /** The ContainerNotRunningError of a 409, with the state of an inspect. */
+    async #notRunning(error, options) {
+        const state = (await this.inspect(options)).State?.Status ?? '';
+        return new ContainerNotRunningError(error.message, { status: 409, request: error.request }, this.id, state, { cause: error });
+    }
+    async #post(action, query, options) {
+        const method = 'POST';
+        const path = `${this.#path}/${action}`;
+        const response = await this.#client.exchange(method, path, {
+            query,
+            signal: options.signal,
+        });
+        this.#throwUnless(response, method, path);
+    }
+    /** A 2xx passes; a 404 is a ContainerNotFoundError; each other status is a DockerEngineError. */
+    #throwUnless(response, method, path) {
+        if (isSuccess(response))
+            return;
+        const error = this.#client.error(response, method, path);
+        if (response.status === 404) {
+            throw new ContainerNotFoundError(error.message, { status: 404, request: { method, path } }, this.id, { cause: error });
+        }
+        throw error;
+    }
+}
+/** A container that this handle created. Disposal removes it with its anonymous volumes. */
+export class OwnedContainer extends Container {
+    /** remove({ force: true, v: true }) */
+    async [Symbol.asyncDispose]() {
+        await this.remove({ force: true, v: true });
+    }
+}
+/** The containers of one engine. */
+export class Containers {
+    #client;
+    #images;
+    constructor(client, images) {
+        this.#client = client;
+        this.#images = images;
+    }
+    async create(body, options = {}) {
+        const { name, platform, signal } = options;
+        const method = 'POST';
+        const path = '/containers/create';
+        const response = await this.#client.exchange(method, path, {
+            query: { name, platform },
+            body,
+            signal,
+        });
+        if (isSuccess(response)) {
+            const { Id } = parseBody(response);
+            return new OwnedContainer(this.#client, Id);
+        }
+        const error = this.#client.error(response, method, path);
+        const answer = { status: response.status, request: { method, path } };
+        if (response.status === 409 && name !== undefined) {
+            throw new NameConflictError(error.message, answer, 'container', name, {
+                cause: error,
+            });
+        }
+        if (response.status === 404 && body.Image !== undefined) {
+            const image = await this.#images.inspect(body.Image, options);
+            if (image === undefined) {
+                throw new ImageNotFoundError(error.message, answer, body.Image, {
+                    cause: error,
+                });
+            }
+        }
+        throw bindSourceOr(error);
+    }
+    /**
+     * Creates the container, attaches to its output, starts it, waits for its
+     * end, and removes it. A non-zero exit code is data. A failure and a cancel
+     * also remove the container.
+     */
+    async run(body, options = {}) {
+        const container = await this.create(body, options);
+        try {
+            const process = await container.attach(options);
+            await container.start(options);
+            return await process.collect();
+        }
+        finally {
+            await container.remove({ force: true, v: true });
+        }
+    }
+    /** Creates the container, or gives the one that has the name. The container that exists wins. */
+    async createOrGet(body, options) {
+        const { signal } = options;
+        for (;;) {
+            try {
+                return { created: true, container: await this.create(body, options) };
+            }
+            catch (error) {
+                if (!(error instanceof NameConflictError))
+                    throw error;
+            }
+            // A competing create reserves the name before an inspect finds it.
+            const container = await this.find(options.name, options);
+            if (container)
+                return { created: false, container };
+            await setTimeout(NAME_RACE_DELAY_MS, undefined, { signal });
+        }
+    }
+    /** One inspect: a handle with the ID of the engine, or undefined for 404. */
+    async find(nameOrId, options = {}) {
+        const method = 'GET';
+        const path = `/containers/${encodeURIComponent(nameOrId)}/json`;
+        const response = await this.#client.exchange(method, path, options);
+        if (response.status === 404)
+            return undefined;
+        if (!isSuccess(response))
+            throw this.#client.error(response, method, path);
+        const { Id } = parseBody(response);
+        return new Container(this.#client, Id);
+    }
+    async list(options = {}) {
+        return this.#client.json('GET', '/containers/json', {
+            query: { all: options.all, filters: options.filters },
+            signal: options.signal,
+        });
+    }
+}
+//# sourceMappingURL=containers.js.map