@zukhruf/testing 0.0.0-stage → 0.3.3

package/dist/docker/docker.d.ts

@@ -0,0 +1,74 @@
+import { Container, type DockerCommand, ServiceContainer } from './container.ts';
+import { DockerDirectory } from './directory.ts';
+import type { TestRun } from './test-run.ts';
+import { DockerVolume } from './volume.ts';
+/** Marks a server that `reuse()` shares across processes and runs. */
+export declare const SHARED_SERVER_LABEL = "dev.zukhruf.testing.shared";
+/** A volume or a path on the engine's host, mounted into a container. */
+export interface Mount {
+    /** A volume's name, or an absolute path on the engine's host. */
+    source: string;
+    target: string;
+    readOnly?: boolean;
+}
+export interface ContainerOptions {
+    image: string;
+    /** Replaces the image's command. */
+    command?: string[];
+    /** A dedicated container gets a generated name; a reused server's name comes from its configuration. */
+    name?: string;
+    hostname?: string;
+    env?: Record<string, string>;
+    labels?: Record<string, string> | undefined;
+    mounts?: Mount[];
+    tmpfs?: string[];
+    ipcHost?: boolean;
+    memory?: string;
+    cpus?: number;
+    memorySwappiness?: number;
+}
+export interface ServiceOptions extends ContainerOptions {
+    /** The container's port that answers on 127.0.0.1 of this machine. */
+    internalPort: number;
+    /** Runs on every acquisition. Throw until ready, using timebox for polling. */
+    healthy?: (container: ServiceContainer) => unknown;
+}
+export interface DockerOptions {
+    /** The supervised run that owns what this process creates: `TestRun.fromEnvironment(process.env)`. */
+    testRun?: TestRun | undefined;
+}
+/** The engine the Docker CLI selects. Docker owns cross-process coordination; this instance holds no server cache. */
+export declare class Docker {
+    #private;
+    constructor({ testRun }?: DockerOptions);
+    /** Defaults for disposable test containers, including external launchers. */
+    get defaults(): {
+        resources: {
+            memory: string;
+            cpus: number;
+        };
+        labels: Record<string, string>;
+    };
+    info(): Promise<{
+        architecture: string;
+        endpoint: string;
+    }>;
+    directory(): Promise<DockerDirectory>;
+    /** Creates a named volume. The supervisor removes it with its run if this process dies first. */
+    volume(): Promise<DockerVolume>;
+    readonly command: DockerCommand;
+    isAvailable(): Promise<boolean>;
+    /** Starts a container this process owns. It stays after it stops, until disposal removes it. */
+    start(options: ContainerOptions): Promise<Container>;
+    /** Starts a dedicated server. Failure or disposal stops it, and a stopped server is removed. */
+    serve(options: ServiceOptions): Promise<ServiceContainer>;
+    /**
+     * Reuse one server per configuration on this daemon, across processes/runs.
+     * Docker reserves the name atomically. Readiness failure leaves it running.
+     * Only explicitly dispose the returned container after all its users finish.
+     */
+    reuse(options: ServiceOptions): Promise<ServiceContainer>;
+    /** Runs a container to completion and returns its standard output. The container is removed afterwards. */
+    run(options: ContainerOptions): Promise<string>;
+}
+//# sourceMappingURL=docker.d.ts.map

package/dist/docker/docker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker.d.ts","sourceRoot":"","sources":["../../src/docker/docker.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,SAAS,EACT,KAAK,aAAa,EAClB,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,sEAAsE;AACtE,eAAO,MAAM,mBAAmB,+BAA+B,CAAC;AAGhE,yEAAyE;AACzE,MAAM,WAAW,KAAK;IACpB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,wGAAwG;IACxG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAC5C,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,gBAAgB,KAAK,OAAO,CAAC;CACpD;AAED,MAAM,WAAW,aAAa;IAC5B,sGAAsG;IACtG,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/B;AA2BD,sHAAsH;AACtH,qBAAa,MAAM;;gBAaL,EAAE,OAAO,EAAE,GAAE,aAAkB;IAI3C,6EAA6E;IAC7E,IAAI,QAAQ,IAAI;QACd,SAAS,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;QAC5C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAChC,CAKA;IAEK,IAAI,IAAI,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAU3D,SAAS,IAAI,OAAO,CAAC,eAAe,CAAC;IAI3C,iGAAiG;IAC3F,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAYrC,QAAQ,CAAC,OAAO,EAAE,aAAa,CACY;IAErC,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAarC,gGAAgG;IAC1F,KAAK,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC;IAK1D,gGAAgG;IAC1F,KAAK,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAe/D;;;;OAIG;IACG,KAAK,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAqB/D,2GAA2G;IACrG,GAAG,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;CAgLtD"}

package/dist/docker/docker.js

@@ -0,0 +1,257 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { SubprocessError } from 'nano-spawn';
+import pMemoize from 'p-memoize';
+import { timebox } from "../async/timebox.js";
+import { Container, ServiceContainer, } from "./container.js";
+import { DockerDirectory } from "./directory.js";
+import { DockerHost } from "./host.js";
+import { DockerVolume } from "./volume.js";
+/** Marks a server that `reuse()` shares across processes and runs. */
+export const SHARED_SERVER_LABEL = 'dev.zukhruf.testing.shared';
+const CONFIG_LABEL = 'dev.zukhruf.testing.config';
+const labelArgs = (labels) => Object.entries(labels).flatMap(([key, value]) => [
+    '--label',
+    `${key}=${value}`,
+]);
+const publish = (internalPort) => [
+    '-p',
+    `127.0.0.1::${internalPort}`,
+];
+const byKey = ([a], [b]) => {
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+};
+/** The engine the Docker CLI selects. Docker owns cross-process coordination; this instance holds no server cache. */
+export class Docker {
+    #testRun;
+    // The first resolution pins the engine: handles keep the engine they were made on.
+    #connection = pMemoize(() => DockerHost.resolve());
+    #probe = pMemoize(async () => {
+        try {
+            await this.command(['info']);
+            return { available: true };
+        }
+        catch (cause) {
+            return { available: false, cause };
+        }
+    });
+    constructor({ testRun } = {}) {
+        this.#testRun = testRun;
+    }
+    /** Defaults for disposable test containers, including external launchers. */
+    get defaults() {
+        return {
+            resources: { memory: '1g', cpus: 1 },
+            labels: this.#testRun?.labels ?? {},
+        };
+    }
+    async info() {
+        const host = await this.#connection();
+        const { stdout } = await host.command([
+            'info',
+            '--format',
+            '{{.Architecture}}',
+        ]);
+        return { architecture: stdout.trim(), endpoint: host.endpoint };
+    }
+    async directory() {
+        return DockerDirectory.create(await this.#connection(), this.#testRun);
+    }
+    /** Creates a named volume. The supervisor removes it with its run if this process dies first. */
+    async volume() {
+        const host = await this.#require();
+        const name = `zukhruf-testing-${randomUUID()}`;
+        await host.command([
+            'volume',
+            'create',
+            ...labelArgs(this.defaults.labels),
+            name,
+        ]);
+        return new DockerVolume(name, host.command);
+    }
+    command = async (args) => (await this.#connection()).command(args);
+    async isAvailable() {
+        return (await this.#probe()).available;
+    }
+    async #require() {
+        const probe = await this.#probe();
+        if (!probe.available)
+            throw new Error('Docker is required for container-backed tests', {
+                cause: probe.cause,
+            });
+        return this.#connection();
+    }
+    /** Starts a container this process owns. It stays after it stops, until disposal removes it. */
+    async start(options) {
+        const host = await this.#require();
+        return new Container(await this.#detach(host, [], options), host.command);
+    }
+    /** Starts a dedicated server. Failure or disposal stops it, and a stopped server is removed. */
+    async serve(options) {
+        const host = await this.#require();
+        const id = await this.#detach(host, ['--rm', ...publish(options.internalPort)], options);
+        try {
+            return await this.#ready(host, id, options);
+        }
+        catch (error) {
+            await host.command(['stop', id]).catch(() => { });
+            throw error;
+        }
+    }
+    /**
+     * Reuse one server per configuration on this daemon, across processes/runs.
+     * Docker reserves the name atomically. Readiness failure leaves it running.
+     * Only explicitly dispose the returned container after all its users finish.
+     */
+    async reuse(options) {
+        const host = await this.#require();
+        const fingerprint = this.#fingerprint(options);
+        const name = options.name ?? `zukhruf-testing-${fingerprint}`;
+        const inspected = (await this.#inspect(host, name)) ??
+            (await this.#create(host, name, fingerprint, options));
+        if (inspected.Config.Labels?.[SHARED_SERVER_LABEL] !== '1' ||
+            inspected.Config.Labels[CONFIG_LABEL] !== fingerprint) {
+            throw new Error(`Container ${name} does not match the shared test configuration`);
+        }
+        if (inspected.State.Status !== 'running') {
+            await host.command(['start', inspected.Id]);
+        }
+        return this.#ready(host, inspected.Id, options);
+    }
+    /** Runs a container to completion and returns its standard output. The container is removed afterwards. */
+    async run(options) {
+        const host = await this.#require();
+        return this.#launch(host, ['run', '--rm'], options);
+    }
+    async #create(host, name, fingerprint, options) {
+        try {
+            await host.command([
+                'create',
+                '--rm',
+                ...publish(options.internalPort),
+                ...this.#args({
+                    ...options,
+                    name,
+                    labels: {
+                        ...options.labels,
+                        [SHARED_SERVER_LABEL]: '1',
+                        [CONFIG_LABEL]: fingerprint,
+                    },
+                }),
+                options.image,
+                ...(options.command ?? []),
+            ]);
+        }
+        catch (error) {
+            if (!(error instanceof SubprocessError) ||
+                !error.stderr.includes('is already in use by container'))
+                throw error;
+        }
+        // A competing create reserves the name before Docker registers it for
+        // inspection. Retry only that absence, not daemon or permission errors.
+        const pending = new Error(`Container ${name} is not visible yet`);
+        return timebox(async () => {
+            const container = await this.#inspect(host, name);
+            if (!container)
+                throw pending;
+            return container;
+        }, { shouldRetry: ({ error }) => error === pending });
+    }
+    async #detach(host, flags, options) {
+        const id = (await this.#launch(host, ['run', '--detach', ...flags], options)).trim();
+        if (!id)
+            throw new Error(`Docker started no container from ${options.image}`);
+        return id;
+    }
+    async #launch(host, verb, options) {
+        const name = options.name ??
+            `test-${options.image.replace(/[^a-zA-Z0-9_.-]/g, '-')}-${randomUUID()}`;
+        const labels = { ...options.labels, ...this.defaults.labels };
+        const { stdout } = await host.command([
+            ...verb,
+            ...this.#args({ ...options, name, labels }),
+            options.image,
+            ...(options.command ?? []),
+        ]);
+        return stdout;
+    }
+    #fingerprint(options) {
+        const { resources } = this.defaults;
+        return createHash('sha256')
+            .update(JSON.stringify({
+            transportVersion: 2,
+            memory: options.memory ?? resources.memory,
+            cpus: options.cpus ?? resources.cpus,
+            image: options.image,
+            command: options.command ?? [],
+            hostname: options.hostname,
+            internalPort: options.internalPort,
+            env: Object.entries(options.env ?? {}).sort(byKey),
+            labels: Object.entries(options.labels ?? {}).sort(byKey),
+            mounts: options.mounts ?? [],
+            tmpfs: options.tmpfs ?? [],
+            ipcHost: Boolean(options.ipcHost),
+            memorySwappiness: options.memorySwappiness,
+        }))
+            .digest('hex');
+    }
+    #args(options) {
+        const { resources } = this.defaults;
+        return [
+            '--name',
+            options.name,
+            ...(options.hostname ? ['--hostname', options.hostname] : []),
+            ...labelArgs(options.labels ?? {}),
+            ...Object.entries(options.env ?? {}).flatMap(([key, value]) => [
+                '-e',
+                `${key}=${value}`,
+            ]),
+            ...(options.mounts ?? []).flatMap(({ source, target, readOnly }) => [
+                '--volume',
+                `${source}:${target}${readOnly ? ':ro' : ''}`,
+            ]),
+            ...(options.tmpfs ?? []).flatMap((spec) => ['--tmpfs', spec]),
+            ...(options.ipcHost ? ['--ipc=host'] : []),
+            ...(options.memorySwappiness === undefined
+                ? []
+                : [`--memory-swappiness=${options.memorySwappiness}`]),
+            '--memory',
+            options.memory ?? resources.memory,
+            '--cpus',
+            String(options.cpus ?? resources.cpus),
+        ];
+    }
+    async #inspect(host, name) {
+        try {
+            const { stdout } = await host.command(['container', 'inspect', name]);
+            const [container] = JSON.parse(stdout);
+            return container;
+        }
+        catch (error) {
+            if (error instanceof SubprocessError &&
+                /No such (object|container):/i.test(error.stderr))
+                return undefined;
+            throw error;
+        }
+    }
+    async #ready(host, id, { internalPort, healthy }) {
+        const { stdout } = await host.command(['port', id, String(internalPort)]);
+        const port = /:(\d+)$/.exec(stdout.trim())?.[1];
+        if (!port)
+            throw new Error(`Failed to get mapped port for container ${id}: ${stdout}`);
+        const connection = await host.forward(Number.parseInt(port, 10), this.#testRun);
+        const container = new ServiceContainer(id, connection.port, host.command, connection.close);
+        try {
+            await healthy?.(container);
+            return container;
+        }
+        catch (error) {
+            await container.disconnect();
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=docker.js.map

package/dist/docker/docker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker.js","sourceRoot":"","sources":["../../src/docker/docker.ts"],"names":[],"mappings":"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"}

package/dist/docker/host.d.ts

@@ -0,0 +1,17 @@
+import { type TestRun } from './test-run.ts';
+export declare const quote: (value: string) => string;
+/** Resolve with the Docker CLI so its native context/environment precedence wins. */
+export declare class DockerHost {
+    readonly endpoint: string;
+    private constructor();
+    static resolve(): Promise<DockerHost>;
+    get remote(): boolean;
+    readonly command: (args: string[]) => import("nano-spawn").Subprocess;
+    sshArgs(options?: string[]): string[];
+    shell(script: string, input?: string): import("nano-spawn").Subprocess;
+    forward(port: number, run: TestRun | undefined): Promise<{
+        port: number;
+        close: () => Promise<void>;
+    }>;
+}
+//# sourceMappingURL=host.d.ts.map

package/dist/docker/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/docker/host.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,KAAK,OAAO,EAAiB,MAAM,eAAe,CAAC;AAE5D,eAAO,MAAM,KAAK,GAAI,OAAO,MAAM,KAAG,MACC,CAAC;AAKxC,qFAAqF;AACrF,qBAAa,UAAU;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,OAAO;WAIM,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC;IAgB3C,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,QAAQ,CAAC,OAAO,GAAI,MAAM,MAAM,EAAE,qCAI7B;IAEL,OAAO,CAAC,OAAO,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE;IAqBzC,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;IAO9B,OAAO,CACX,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,OAAO,GAAG,SAAS,GACvB,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;CAuHzD"}

package/dist/docker/host.js

@@ -0,0 +1,172 @@
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { mkdtempDisposable, stat } from 'node:fs/promises';
+import { connect, createServer } from 'node:net';
+import { join } from 'node:path';
+import command from 'nano-spawn';
+import { timebox } from "../async/timebox.js";
+import { forwardPrefix } from "./test-run.js";
+export const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+/** Local Unix sockets, Docker Desktop's named pipe on Windows, and SSH engines. A `tcp://` engine may be on another machine. */
+const supportedEndpoints = ['unix://', 'npipe://', 'ssh://'];
+/** Resolve with the Docker CLI so its native context/environment precedence wins. */
+export class DockerHost {
+    endpoint;
+    constructor(endpoint) {
+        this.endpoint = endpoint;
+    }
+    static async resolve() {
+        const { stdout } = await command('docker', [
+            'context',
+            'inspect',
+            '--format',
+            '{{.Endpoints.docker.Host}}',
+        ]);
+        const endpoint = stdout.trim();
+        if (!supportedEndpoints.some((scheme) => endpoint.startsWith(scheme))) {
+            throw new Error(`Unsupported Docker endpoint ${endpoint}; tests support ${supportedEndpoints.join(', ')}`);
+        }
+        return new DockerHost(endpoint);
+    }
+    get remote() {
+        return this.endpoint.startsWith('ssh://');
+    }
+    command = (args) => command('docker', args, {
+        env: { DOCKER_CONTEXT: undefined, DOCKER_HOST: this.endpoint },
+        timeout: 240_000,
+    });
+    sshArgs(options = []) {
+        const url = new URL(this.endpoint);
+        // Pass the original hostname to OpenSSH: ~/.ssh/config, jump hosts, keys,
+        // agents and host-key policy continue to work exactly as for Docker.
+        return [
+            '-T',
+            '-o',
+            'BatchMode=yes',
+            '-o',
+            'ConnectTimeout=10',
+            '-o',
+            'ServerAliveInterval=10',
+            '-o',
+            'ServerAliveCountMax=2',
+            ...(url.port ? ['-p', url.port] : []),
+            ...(url.username ? ['-l', decodeURIComponent(url.username)] : []),
+            ...options,
+            url.hostname,
+        ];
+    }
+    shell(script, input) {
+        return command('ssh', [...this.sshArgs(), script], {
+            stdin: input === undefined ? 'ignore' : { string: input },
+            timeout: 30_000,
+        });
+    }
+    async forward(port, run) {
+        if (!this.remote)
+            return { port, close: async () => { } };
+        const resources = new AsyncDisposableStack();
+        const close = () => resources.disposeAsync();
+        try {
+            // Keep the Unix socket path below macOS's 104-byte limit. The private
+            // directory and ownership record also cover workers killed mid-test.
+            const directory = resources.use(await mkdtempDisposable(forwardPrefix(run)));
+            if (run)
+                resources.use(await run.record('forward', directory.path));
+            const path = join(directory.path, 's');
+            const sockets = new Set();
+            const server = createServer((socket) => {
+                const channel = connect(path);
+                const pairs = [
+                    [socket, channel],
+                    [channel, socket],
+                ];
+                for (const [stream, peer] of pairs) {
+                    sockets.add(stream);
+                    stream.on('error', () => peer.destroy());
+                    stream.once('close', () => {
+                        sockets.delete(stream);
+                        peer.destroy();
+                    });
+                }
+                socket.pipe(channel).pipe(socket);
+            });
+            // OpenSSH multiplexes client streams over one authenticated connection.
+            // Node owns the ephemeral TCP listener, so no port-reservation race or
+            // fresh SSH login is added to each database client's connect timeout.
+            const child = spawn('ssh', this.sshArgs([
+                '-N',
+                '-S',
+                'none',
+                '-o',
+                'ControlMaster=no',
+                '-o',
+                'ControlPersist=no',
+                '-o',
+                'ExitOnForwardFailure=yes',
+                '-L',
+                `${path}:127.0.0.1:${port}`,
+            ]), { stdio: ['ignore', 'ignore', 'pipe'] });
+            let errorOutput = '';
+            let spawnError;
+            child.stderr.on('data', (data) => {
+                errorOutput += data;
+            });
+            child.once('error', (error) => {
+                spawnError = error;
+            });
+            const exited = new Promise((resolve) => child.once('close', (code) => {
+                if (code && errorOutput)
+                    process.stderr.write(`Docker SSH forwarding: ${errorOutput}`);
+                for (const socket of sockets)
+                    socket.destroy();
+                if (server.listening)
+                    server.close();
+                resolve();
+            }));
+            resources.defer(async () => {
+                child.kill('SIGTERM');
+                const deadline = setTimeout(() => child.kill('SIGKILL'), 1_000);
+                try {
+                    await exited;
+                }
+                finally {
+                    clearTimeout(deadline);
+                }
+            });
+            resources.defer(async () => {
+                const closed = new Promise((resolve, reject) => server.close((error) => error &&
+                    !('code' in error && error.code === 'ERR_SERVER_NOT_RUNNING')
+                    ? reject(error)
+                    : resolve()));
+                for (const socket of sockets)
+                    socket.destroy();
+                await closed;
+            });
+            // OpenSSH binds local forwards after authentication. Wait for that
+            // listener before publishing the TCP port to a database client.
+            await timebox(async () => {
+                if (spawnError)
+                    throw spawnError;
+                if (child.exitCode !== null || child.signalCode !== null)
+                    throw new Error(`Docker SSH forwarding exited: ${errorOutput.trim()}`);
+                if (!(await stat(path)).isSocket())
+                    throw new Error('Docker SSH forwarding did not create a Unix socket');
+            }, {
+                maxRetryTime: 15_000,
+                shouldRetry: ({ error }) => !spawnError && 'code' in error && error.code === 'ENOENT',
+            });
+            server.listen(0, '127.0.0.1');
+            await once(server, 'listening');
+            server.unref();
+            const address = server.address();
+            if (!address || typeof address === 'string')
+                throw new Error('Docker forwarding did not acquire a TCP port');
+            return { port: address.port, close };
+        }
+        catch (error) {
+            await close();
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=host.js.map

package/dist/docker/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../../src/docker/host.ts"],"names":[],"mappings":"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"}

package/dist/docker/index.d.ts

@@ -0,0 +1,7 @@
+export { Container, type DockerCommand, ServiceContainer, } from './container.ts';
+export { DockerDirectory } from './directory.ts';
+export { type ContainerOptions, Docker, type DockerOptions, type Mount, type ServiceOptions, } from './docker.ts';
+export { DOCKER_TESTS, skipWithoutDocker } from './skip-without-docker.ts';
+export { TestRun } from './test-run.ts';
+export { DockerVolume } from './volume.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/docker/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/docker/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,KAAK,aAAa,EAClB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EACL,KAAK,gBAAgB,EACrB,MAAM,EACN,KAAK,aAAa,EAClB,KAAK,KAAK,EACV,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/docker/index.js

@@ -0,0 +1,7 @@
+export { Container, ServiceContainer, } from "./container.js";
+export { DockerDirectory } from "./directory.js";
+export { Docker, } from "./docker.js";
+export { DOCKER_TESTS, skipWithoutDocker } from "./skip-without-docker.js";
+export { TestRun } from "./test-run.js";
+export { DockerVolume } from "./volume.js";
+//# sourceMappingURL=index.js.map

package/dist/docker/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/docker/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EAET,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAEL,MAAM,GAIP,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/docker/skip-without-docker.d.ts

@@ -0,0 +1,12 @@
+import type { Docker } from './docker.ts';
+/** How tests treat Docker: `required`, `skip`, or unset to run when Docker answers. */
+export declare const DOCKER_TESTS = "ZUKHRUF_TESTING_DOCKER";
+/**
+ * The `skip` option of a test that needs Docker, read from the environment the
+ * host passes (`process.env`). With `ZUKHRUF_TESTING_DOCKER=required` it
+ * throws when Docker does not answer, so a machine that must run the tests
+ * fails instead of skipping them. With `skip` it always skips. Unset, it skips
+ * only when Docker does not answer.
+ */
+export declare function skipWithoutDocker(docker: Docker, environment: Readonly<Record<string, string | undefined>>): Promise<string | false>;
+//# sourceMappingURL=skip-without-docker.d.ts.map

package/dist/docker/skip-without-docker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skip-without-docker.d.ts","sourceRoot":"","sources":["../../src/docker/skip-without-docker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,uFAAuF;AACvF,eAAO,MAAM,YAAY,2BAA2B,CAAC;AAErD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GACxD,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC,CAuBzB"}

package/dist/docker/skip-without-docker.js

@@ -0,0 +1,31 @@
+/** How tests treat Docker: `required`, `skip`, or unset to run when Docker answers. */
+export const DOCKER_TESTS = 'ZUKHRUF_TESTING_DOCKER';
+/**
+ * The `skip` option of a test that needs Docker, read from the environment the
+ * host passes (`process.env`). With `ZUKHRUF_TESTING_DOCKER=required` it
+ * throws when Docker does not answer, so a machine that must run the tests
+ * fails instead of skipping them. With `skip` it always skips. Unset, it skips
+ * only when Docker does not answer.
+ */
+export async function skipWithoutDocker(docker, environment) {
+    const mode = environment[DOCKER_TESTS];
+    switch (mode) {
+        case 'skip':
+            return `${DOCKER_TESTS}=skip`;
+        case 'required':
+            await docker.command(['info']).catch((cause) => {
+                throw new Error(`${DOCKER_TESTS}=required, but Docker does not answer`, {
+                    cause,
+                });
+            });
+            return false;
+        case undefined:
+        case '':
+            return (await docker.isAvailable())
+                ? false
+                : `needs Docker; set ${DOCKER_TESTS}=required to fail instead of skipping`;
+        default:
+            throw new Error(`${DOCKER_TESTS} is "required" or "skip", not "${mode}"`);
+    }
+}
+//# sourceMappingURL=skip-without-docker.js.map

package/dist/docker/skip-without-docker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skip-without-docker.js","sourceRoot":"","sources":["../../src/docker/skip-without-docker.ts"],"names":[],"mappings":"AAEA,uFAAuF;AACvF,MAAM,CAAC,MAAM,YAAY,GAAG,wBAAwB,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAc,EACd,WAAyD;IAEzD,MAAM,IAAI,GAAG,WAAW,CAAC,YAAY,CAAC,CAAC;IACvC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,MAAM;YACT,OAAO,GAAG,YAAY,OAAO,CAAC;QAChC,KAAK,UAAU;YACb,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;gBACtD,MAAM,IAAI,KAAK,CACb,GAAG,YAAY,uCAAuC,EACtD;oBACE,KAAK;iBACN,CACF,CAAC;YACJ,CAAC,CAAC,CAAC;YACH,OAAO,KAAK,CAAC;QACf,KAAK,SAAS,CAAC;QACf,KAAK,EAAE;YACL,OAAO,CAAC,MAAM,MAAM,CAAC,WAAW,EAAE,CAAC;gBACjC,CAAC,CAAC,KAAK;gBACP,CAAC,CAAC,qBAAqB,YAAY,uCAAuC,CAAC;QAC/E;YACE,MAAM,IAAI,KAAK,CAAC,GAAG,YAAY,kCAAkC,IAAI,GAAG,CAAC,CAAC;IAC9E,CAAC;AACH,CAAC"}