@foss.global/forgefixtures 0.2.0

package/ts/classes.certificateauthority.ts

@@ -0,0 +1,117 @@
+import * as plugins from './plugins.js';
+
+export interface IForgeFixtureServerCertificate {
+  certificatePem: string;
+  privateKeyPem: string;
+}
+
+export interface IForgeFixtureServerCertificateRequest {
+  ipAddresses: string[];
+  dnsNames: string[];
+}
+
+const certificateBackdateMs = 5 * 60 * 1000;
+const signingAlgorithm = { name: 'ECDSA', hash: 'SHA-256' };
+
+const generateP256KeyPair = async (): Promise<CryptoKeyPair> =>
+  globalThis.crypto.subtle.generateKey({ name: 'ECDSA', namedCurve: 'P-256' }, true, ['sign', 'verify']);
+
+const exportPrivateKeyPem = async (privateKeyArg: CryptoKey): Promise<string> => {
+  const der = await globalThis.crypto.subtle.exportKey('pkcs8', privateKeyArg);
+  return plugins.crypto.createPrivateKey({ key: Buffer.from(der), format: 'der', type: 'pkcs8' })
+    .export({ format: 'pem', type: 'pkcs8' }).toString();
+};
+
+/**
+ * A certificate authority that exists only in the memory of one fixture
+ * lifecycle. Its private key is never exported; callers receive the public CA
+ * certificate to trust and freshly issued server leaves.
+ */
+export class ForgeFixtureCertificateAuthority {
+  public static async create(
+    lifecycleIdArg: string,
+    validityMsArg: number,
+  ): Promise<ForgeFixtureCertificateAuthority> {
+    if (!lifecycleIdArg || /[,=+<>#;"\\]/.test(lifecycleIdArg)) {
+      throw new TypeError('The certificate authority lifecycle id is malformed.');
+    }
+    if (!Number.isSafeInteger(validityMsArg) || validityMsArg < 60_000) {
+      throw new TypeError('The certificate authority validity must be an integer of at least 60000 ms.');
+    }
+    const keys = await generateP256KeyPair();
+    const now = Date.now();
+    const certificate = await plugins.x509.X509CertificateGenerator.createSelfSigned({
+      serialNumber: plugins.crypto.randomBytes(16).toString('hex'),
+      name: `CN=forgefixtures ${lifecycleIdArg}`,
+      notBefore: new Date(now - certificateBackdateMs),
+      notAfter: new Date(now + validityMsArg),
+      signingAlgorithm,
+      keys,
+      extensions: [
+        new plugins.x509.BasicConstraintsExtension(true, 0, true),
+        new plugins.x509.KeyUsagesExtension(
+          plugins.x509.KeyUsageFlags.keyCertSign | plugins.x509.KeyUsageFlags.cRLSign,
+          true,
+        ),
+        await plugins.x509.SubjectKeyIdentifierExtension.create(keys.publicKey),
+        await plugins.x509.AuthorityKeyIdentifierExtension.create(keys.publicKey),
+      ],
+    });
+    return new ForgeFixtureCertificateAuthority(certificate, keys.privateKey);
+  }
+
+  readonly #certificate: plugins.x509.X509Certificate;
+  readonly #signingKey: CryptoKey;
+
+  private constructor(certificateArg: plugins.x509.X509Certificate, signingKeyArg: CryptoKey) {
+    this.#certificate = certificateArg;
+    this.#signingKey = signingKeyArg;
+  }
+
+  /** Public CA certificate for scoped trust by fixture clients. */
+  public get certificatePem(): string {
+    return this.#certificate.toString('pem');
+  }
+
+  /** Issues a server leaf within the CA validity for exactly the requested names. */
+  public async issueServerCertificate(
+    requestArg: IForgeFixtureServerCertificateRequest,
+  ): Promise<IForgeFixtureServerCertificate> {
+    const names = [
+      ...requestArg.ipAddresses.map((ipArg) => {
+        if (plugins.net.isIP(ipArg) === 0) throw new TypeError(`"${ipArg}" is not an IP address.`);
+        return { type: 'ip' as const, value: ipArg };
+      }),
+      ...requestArg.dnsNames.map((dnsNameArg) => {
+        if (!/^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/.test(dnsNameArg)) {
+          throw new TypeError(`"${dnsNameArg}" is not an exact lowercase DNS name.`);
+        }
+        return { type: 'dns' as const, value: dnsNameArg };
+      }),
+    ];
+    if (names.length === 0) throw new TypeError('A server certificate needs at least one name.');
+    const keys = await generateP256KeyPair();
+    const certificate = await plugins.x509.X509CertificateGenerator.create({
+      serialNumber: plugins.crypto.randomBytes(16).toString('hex'),
+      subject: `CN=${names[0]!.value}`,
+      issuer: this.#certificate.subjectName,
+      notBefore: this.#certificate.notBefore,
+      notAfter: this.#certificate.notAfter,
+      signingAlgorithm,
+      publicKey: keys.publicKey,
+      signingKey: this.#signingKey,
+      extensions: [
+        new plugins.x509.BasicConstraintsExtension(false, undefined, true),
+        new plugins.x509.KeyUsagesExtension(plugins.x509.KeyUsageFlags.digitalSignature, true),
+        new plugins.x509.ExtendedKeyUsageExtension([plugins.x509.ExtendedKeyUsage.serverAuth]),
+        new plugins.x509.SubjectAlternativeNameExtension(names),
+        await plugins.x509.SubjectKeyIdentifierExtension.create(keys.publicKey),
+        await plugins.x509.AuthorityKeyIdentifierExtension.create(this.#certificate.publicKey),
+      ],
+    });
+    return {
+      certificatePem: certificate.toString('pem'),
+      privateKeyPem: await exportPrivateKeyPem(keys.privateKey),
+    };
+  }
+}

package/ts/classes.containerlifecycle.ts

@@ -0,0 +1,432 @@
+import * as plugins from './plugins.js';
+import { defaultMaxLifetimeMs, defaultPullTimeoutMs } from './constants.js';
+import { ForgeFixtureCertificateAuthority } from './classes.certificateauthority.js';
+import { ForgeFixtureHttpClient } from './classes.httpclient.js';
+import { createForgeFixtureDockerHost, reapStaleForgeFixtures } from './classes.reaper.js';
+import { ForgeFixtureTlsTerminator } from './classes.tlsterminator.js';
+import { createForgeFixtureOwner, forgeFixtureOwnerLabels } from './ownership.js';
+import type {
+  IForgeFixtureEndpoint,
+  IForgeFixtureImage,
+  IForgeFixtureLifecycleOptions,
+  IForgeFixtureOwner,
+  IForgeFixtureReapReport,
+  TForgeFixtureKind,
+} from './interfaces.js';
+
+/** What a forge driver asks the lifecycle to run. */
+export interface IForgeFixtureContainerSpec {
+  image: IForgeFixtureImage;
+  /** Explicit container user. Root requires `allowRootOnRootless` and a verified rootless daemon. */
+  user: string;
+  allowRootOnRootless?: true;
+  command: plugins.docker.TContainerCommand;
+  env: Record<string, string>;
+  /** Plain-HTTP port inside the container that the TLS terminator forwards to. */
+  httpPort: number;
+  tmpfsMounts?: plugins.docker.IContainerTmpfsMount[];
+  /** Named volumes created and removed by this lifecycle, mounted at `target`. */
+  volumes?: Array<{ purpose: string; target: string }>;
+  memoryBytes: number;
+  nanoCpus: number;
+  pidsLimit: number;
+  shmSizeBytes?: number;
+  stopTimeoutSeconds: number;
+  healthcheck?: plugins.docker.IContainerHealthcheck;
+}
+
+export type TForgeFixtureContainerHealth = 'none' | 'starting' | 'healthy' | 'unhealthy';
+
+export type TForgeFixtureLifecycleState = 'idle' | 'preparing' | 'prepared' | 'starting' | 'running' | 'stopping' | 'stopped';
+
+const maxPortAttempts = 5;
+
+/** Asks the kernel for a currently free loopback port. The caller must tolerate losing a race for it. */
+const reserveLoopbackPort = async (): Promise<number> => {
+  const server = plugins.net.createServer();
+  await new Promise<void>((resolveArg, rejectArg) => {
+    server.once('error', rejectArg);
+    server.listen({ host: '127.0.0.1', port: 0, exclusive: true }, () => resolveArg());
+  });
+  const address = server.address();
+  await new Promise<void>((resolveArg) => server.close(() => resolveArg()));
+  if (address === null || typeof address === 'string') throw new Error('The loopback port probe has no TCP address.');
+  return address.port;
+};
+
+const isPortConflict = (errorArg: unknown): boolean =>
+  errorArg instanceof Error && /address already in use|port is already allocated/.test(errorArg.message);
+
+/** Raised by lifecycle steps that observe a stop request. */
+export class ForgeFixtureStoppedError extends Error {
+  constructor(kindArg: TForgeFixtureKind, optionsArg?: ErrorOptions) {
+    super(`The ${kindArg} fixture was stopped.`, optionsArg);
+    this.name = 'ForgeFixtureStoppedError';
+  }
+}
+
+/**
+ * Owns one fixture's Docker resources, local CA, TLS terminator and scoped
+ * HTTPS client. Every resource carries ownership labels, so resources left by a
+ * crashed process are removed by the next lifecycle's reaper run.
+ */
+export class ForgeFixtureContainerLifecycle {
+  readonly #kind: TForgeFixtureKind;
+  readonly #options: Required<Omit<IForgeFixtureLifecycleOptions, 'dockerSocketPath'>> & { dockerSocketPath?: string };
+  #state: TForgeFixtureLifecycleState = 'idle';
+  #dockerHost: plugins.docker.DockerHost | undefined;
+  #owner: IForgeFixtureOwner | undefined;
+  #terminator: ForgeFixtureTlsTerminator | undefined;
+  #http: ForgeFixtureHttpClient | undefined;
+  #endpoint: IForgeFixtureEndpoint | undefined;
+  #container: plugins.docker.DockerContainer | undefined;
+  #network: plugins.docker.DockerNetwork | undefined;
+  readonly #volumes: plugins.docker.DockerVolume[] = [];
+  #lastReapReport: IForgeFixtureReapReport | undefined;
+  readonly #stopController = new AbortController();
+  /** The prepare or container start currently running; `stop()` waits for it before cleaning up. */
+  #inflight: Promise<unknown> | undefined;
+  /** Serialises cleanup runs so concurrent stops never remove the same resource twice. */
+  #cleanupQueue: Promise<void> = Promise.resolve();
+
+  constructor(kindArg: TForgeFixtureKind, optionsArg: IForgeFixtureLifecycleOptions, startupTimeoutMsArg: number) {
+    this.#kind = kindArg;
+    this.#options = {
+      ...(optionsArg.dockerSocketPath === undefined ? {} : { dockerSocketPath: optionsArg.dockerSocketPath }),
+      maxLifetimeMs: optionsArg.maxLifetimeMs ?? defaultMaxLifetimeMs,
+      pullTimeoutMs: optionsArg.pullTimeoutMs ?? defaultPullTimeoutMs,
+      startupTimeoutMs: optionsArg.startupTimeoutMs ?? startupTimeoutMsArg,
+    };
+    for (const [name, value] of Object.entries(this.#options)) {
+      if (name !== 'dockerSocketPath' && (!Number.isSafeInteger(value) || (value as number) < 1)) {
+        throw new TypeError(`${name} must be a positive integer.`);
+      }
+    }
+  }
+
+  public get state(): TForgeFixtureLifecycleState {
+    return this.#state;
+  }
+
+  public get startupTimeoutMs(): number {
+    return this.#options.startupTimeoutMs;
+  }
+
+  public get lifecycleId(): string {
+    return this.#require(this.#owner, 'lifecycle owner').lifecycleId;
+  }
+
+  public get endpoint(): IForgeFixtureEndpoint {
+    return this.#require(this.#endpoint, 'endpoint');
+  }
+
+  public get http(): ForgeFixtureHttpClient {
+    return this.#require(this.#http, 'HTTPS client');
+  }
+
+  public get dockerHost(): plugins.docker.DockerHost {
+    return this.#require(this.#dockerHost, 'Docker host');
+  }
+
+  /** Aborted once `stop()` or `requestStop()` was called. */
+  public get stopSignal(): AbortSignal {
+    return this.#stopController.signal;
+  }
+
+  /** Throws {@link ForgeFixtureStoppedError} once a stop was requested. */
+  public assertNotStopping(): void {
+    if (this.#stopController.signal.aborted) throw new ForgeFixtureStoppedError(this.#kind);
+  }
+
+  /**
+   * Once a stop was requested, any failure it provoked (an aborted pull, a
+   * refused request) is reported as {@link ForgeFixtureStoppedError} with the
+   * original failure as its cause.
+   */
+  public stopAwareError(errorArg: unknown): unknown {
+    if (!this.#stopController.signal.aborted || errorArg instanceof ForgeFixtureStoppedError) return errorArg;
+    return new ForgeFixtureStoppedError(this.#kind, { cause: errorArg });
+  }
+
+  /**
+   * Marks the lifecycle as stopping without waiting. Running steps observe it
+   * at their next checkpoint, an image pull is cancelled, and the lifecycle can
+   * no longer be prepared or started.
+   */
+  public requestStop(): void {
+    if (!this.#stopController.signal.aborted) this.#stopController.abort(new ForgeFixtureStoppedError(this.#kind));
+  }
+
+  /** Report of the reaper run that preceded this lifecycle. */
+  public get lastReapReport(): IForgeFixtureReapReport | undefined {
+    return this.#lastReapReport;
+  }
+
+  /**
+   * Reaps stale fixtures, creates ownership, CA and TLS terminator. The
+   * returned endpoint is final: its port is bound before the forge starts.
+   */
+  public async prepare(): Promise<IForgeFixtureEndpoint> {
+    this.assertNotStopping();
+    if (this.#state !== 'idle') throw new Error(`Cannot prepare a ${this.#state} lifecycle.`);
+    this.#state = 'preparing';
+    return this.#track(this.#prepare());
+  }
+
+  async #prepare(): Promise<IForgeFixtureEndpoint> {
+    try {
+      this.#dockerHost = createForgeFixtureDockerHost(this.#options.dockerSocketPath);
+      this.#lastReapReport = await reapStaleForgeFixtures(this.#dockerHost);
+      this.assertNotStopping();
+      this.#owner = await createForgeFixtureOwner(this.#kind, this.#options.maxLifetimeMs);
+      const authority = await ForgeFixtureCertificateAuthority.create(
+        this.#owner.lifecycleId, this.#options.maxLifetimeMs + 24 * 60 * 60 * 1000,
+      );
+      const certificate = await authority.issueServerCertificate({ ipAddresses: ['127.0.0.1'], dnsNames: ['localhost'] });
+      this.assertNotStopping();
+      this.#terminator = new ForgeFixtureTlsTerminator(certificate);
+      const port = await this.#terminator.listen();
+      this.assertNotStopping();
+      this.#endpoint = { baseUrl: `https://127.0.0.1:${port}`, caCertificatePem: authority.certificatePem };
+      this.#http = new ForgeFixtureHttpClient({ baseUrl: this.#endpoint.baseUrl, caCertificatePem: authority.certificatePem });
+      this.#state = 'prepared';
+      return this.#endpoint;
+    } catch (error) {
+      const reported = this.stopAwareError(error);
+      await this.#failAndCleanup(reported);
+      throw reported;
+    }
+  }
+
+  /** Pulls the pinned image, creates the owned network and container, starts it and wires the terminator. */
+  public async startContainer(specArg: IForgeFixtureContainerSpec): Promise<void> {
+    this.assertNotStopping();
+    if (this.#state !== 'prepared') throw new Error(`Cannot start a container in a ${this.#state} lifecycle.`);
+    this.#state = 'starting';
+    return this.#track(this.#startContainer(specArg));
+  }
+
+  async #startContainer(specArg: IForgeFixtureContainerSpec): Promise<void> {
+    const dockerHost = this.dockerHost;
+    const owner = this.#require(this.#owner, 'lifecycle owner');
+    const labels = forgeFixtureOwnerLabels(owner);
+    const name = `forgefixtures-${owner.kind}-${owner.lifecycleId}`;
+    try {
+      const image = await dockerHost.pullImage({
+        reference: specArg.image.repoDigest,
+        expectedRepoDigest: specArg.image.repoDigest,
+        signal: AbortSignal.any([AbortSignal.timeout(this.#options.pullTimeoutMs), this.#stopController.signal]),
+      });
+      this.assertNotStopping();
+      this.#network = await dockerHost.createNetwork({ Name: name, Driver: 'bridge', Labels: labels });
+      this.assertNotStopping();
+      for (const volume of specArg.volumes ?? []) {
+        if (!/^[a-z][a-z0-9-]{0,30}$/.test(volume.purpose)) throw new TypeError(`Volume purpose "${volume.purpose}" is malformed.`);
+        this.#volumes.push(await dockerHost.createVolume({ name: `${name}-${volume.purpose}`, labels }));
+        this.assertNotStopping();
+      }
+      // The host port is chosen here rather than by Docker: a rootless daemon allocates
+      // "ephemeral" ports inside its own namespace, blind to host listeners, and then
+      // fails to bind them on the host. A conflict recreates the container on a new port.
+      for (let attempt = 1; ; attempt++) {
+        const hostPort = await reserveLoopbackPort();
+        this.#container = await dockerHost.createContainer({
+          name,
+          imageId: image.Id,
+          imageReference: specArg.image.repoDigest,
+          user: specArg.user,
+          ...(specArg.allowRootOnRootless ? { allowRootOnRootless: true as const } : {}),
+          command: specArg.command,
+          env: specArg.env,
+          labels,
+          stopTimeout: specArg.stopTimeoutSeconds,
+          memoryBytes: specArg.memoryBytes,
+          memorySwapBytes: specArg.memoryBytes,
+          nanoCpus: specArg.nanoCpus,
+          pidsLimit: specArg.pidsLimit,
+          ...(specArg.shmSizeBytes === undefined ? {} : { shmSize: specArg.shmSizeBytes }),
+          ...(specArg.tmpfsMounts === undefined ? {} : { tmpfsMounts: specArg.tmpfsMounts }),
+          ...(specArg.healthcheck === undefined ? {} : { healthcheck: specArg.healthcheck }),
+          namedVolumeMounts: (specArg.volumes ?? []).map((volumeArg, indexArg) => ({
+            source: this.#volumes[indexArg]!.Name, target: volumeArg.target,
+          })),
+          networkEndpoints: [{ networkId: this.#network.Id }],
+          portBindings: [{ containerPort: specArg.httpPort, hostPort, hostIp: '127.0.0.1', protocol: 'tcp' }],
+        });
+        this.assertNotStopping();
+        try {
+          await this.#container.start();
+          break;
+        } catch (error) {
+          if (attempt >= maxPortAttempts || !isPortConflict(error)) throw error;
+          await this.#container.remove({ force: true, removeAnonymousVolumes: true });
+          this.#container = undefined;
+        }
+      }
+      this.assertNotStopping();
+      const publishedPort = await this.#publishedPort(this.#container, specArg.httpPort);
+      this.assertNotStopping();
+      this.#require(this.#terminator, 'TLS terminator').setUpstreamPort(publishedPort);
+      this.#state = 'running';
+    } catch (error) {
+      const reported = this.stopAwareError(error);
+      await this.#failAndCleanup(reported);
+      throw reported;
+    }
+  }
+
+  /** Runs argv in the container as its configured user. Never logs stdin or output. */
+  public async exec(
+    commandArg: plugins.docker.TContainerCommand,
+    optionsArg: plugins.docker.IContainerExecOptions = {},
+  ): Promise<plugins.docker.IContainerExecResult> {
+    if (this.#state !== 'running') throw new Error(`Cannot exec in a ${this.#state} lifecycle.`);
+    return this.#require(this.#container, 'container').exec(commandArg, optionsArg);
+  }
+
+  /** Fails with the container's exit state and recent logs when it stopped running. */
+  public async assertContainerRunning(): Promise<void> {
+    const container = this.#require(this.#container, 'container');
+    const state = await container.inspectState();
+    if (state.Running) return;
+    const logs = await container.logs({ tail: 40 });
+    throw new Error(
+      `The ${this.#kind} fixture container is ${state.Status} (exit ${state.ExitCode}, OOM ${state.OOMKilled}). Last logs:\n${logs}`,
+    );
+  }
+
+  /** Docker's view of the container healthcheck (`none` without a healthcheck). */
+  public async containerHealth(): Promise<TForgeFixtureContainerHealth> {
+    const inspection = await this.#require(this.#container, 'container').inspect();
+    const state = inspection.State;
+    const health: unknown = typeof state === 'object' && state !== null ? Reflect.get(state, 'Health') : undefined;
+    if (health === undefined || health === null) return 'none';
+    const status: unknown = typeof health === 'object' ? Reflect.get(health, 'Status') : undefined;
+    if (status === 'starting' || status === 'healthy' || status === 'unhealthy') return status;
+    throw new Error('Docker reported a malformed container health status.');
+  }
+
+  /** Recent container logs, for diagnostics after a failed readiness wait. */
+  public async logsTail(linesArg: number): Promise<string> {
+    return this.#require(this.#container, 'container').logs({ tail: linesArg });
+  }
+
+  /**
+   * Requests a stop, waits for a running prepare or container start to observe
+   * it, then removes every owned resource in dependency order, including those
+   * that step created. Idempotent. When a removal fails, the remaining
+   * resources stay recorded and a later call retries them; the failures are
+   * thrown together.
+   */
+  public async stop(): Promise<void> {
+    this.requestStop();
+    const inflight = this.#inflight;
+    if (inflight) await inflight.catch(() => undefined);
+    await this.#cleanup();
+  }
+
+  async #track<T>(operationArg: Promise<T>): Promise<T> {
+    this.#inflight = operationArg;
+    try {
+      return await operationArg;
+    } finally {
+      if (this.#inflight === operationArg) this.#inflight = undefined;
+    }
+  }
+
+  #cleanup(): Promise<void> {
+    const run = this.#cleanupQueue.catch(() => undefined).then(() => this.#removeResources());
+    this.#cleanupQueue = run;
+    return run;
+  }
+
+  async #removeResources(): Promise<void> {
+    if (!this.#hasResources()) {
+      this.#http = undefined;
+      this.#endpoint = undefined;
+      this.#state = 'stopped';
+      return;
+    }
+    this.#state = 'stopping';
+    const failures: unknown[] = [];
+    const attempt = async (operationArg: () => Promise<void>) => {
+      try {
+        await operationArg();
+      } catch (error) {
+        failures.push(error);
+      }
+    };
+    this.#http?.close();
+    this.#http = undefined;
+    await attempt(async () => {
+      await this.#terminator?.close();
+      this.#terminator = undefined;
+    });
+    await attempt(async () => {
+      await this.#container?.remove({ force: true, removeAnonymousVolumes: true });
+      this.#container = undefined;
+    });
+    await attempt(async () => {
+      if (this.#container) return;
+      await this.#network?.remove();
+      this.#network = undefined;
+    });
+    while (this.#volumes.length > 0 && !this.#container) {
+      const volume = this.#volumes[0]!;
+      try {
+        await volume.remove({ force: true });
+        this.#volumes.shift();
+      } catch (error) {
+        failures.push(error);
+        break;
+      }
+    }
+    if (!this.#hasResources()) {
+      await attempt(async () => {
+        await this.#dockerHost?.stop();
+        this.#dockerHost = undefined;
+      });
+    }
+    this.#endpoint = undefined;
+    this.#state = this.#hasResources() ? 'stopping' : 'stopped';
+    if (failures.length > 0) {
+      throw new AggregateError(failures, `The ${this.#kind} fixture ${this.#owner?.lifecycleId ?? ''} did not clean up completely.`);
+    }
+  }
+
+  #hasResources(): boolean {
+    return this.#terminator !== undefined || this.#container !== undefined
+      || this.#network !== undefined || this.#volumes.length > 0 || this.#dockerHost !== undefined;
+  }
+
+  async #failAndCleanup(errorArg: unknown): Promise<void> {
+    try {
+      await this.#cleanup();
+    } catch (cleanupError) {
+      throw new AggregateError([errorArg, cleanupError], `The ${this.#kind} fixture failed to start and to clean up.`);
+    }
+  }
+
+  async #publishedPort(containerArg: plugins.docker.DockerContainer, containerPortArg: number): Promise<number> {
+    const inspection = await containerArg.inspect();
+    const settings = inspection.NetworkSettings;
+    const ports = typeof settings === 'object' && settings !== null ? Reflect.get(settings, 'Ports') : undefined;
+    const bindings: unknown = typeof ports === 'object' && ports !== null ? Reflect.get(ports, `${containerPortArg}/tcp`) : undefined;
+    if (Array.isArray(bindings)) {
+      for (const binding of bindings) {
+        if (typeof binding !== 'object' || binding === null) continue;
+        const hostIp: unknown = Reflect.get(binding, 'HostIp');
+        const hostPort: unknown = Reflect.get(binding, 'HostPort');
+        if (hostIp === '127.0.0.1' && typeof hostPort === 'string' && /^[0-9]{1,5}$/.test(hostPort)) {
+          return Number(hostPort);
+        }
+      }
+    }
+    throw new Error(`Docker did not publish container port ${containerPortArg} on 127.0.0.1.`);
+  }
+
+  #require<T>(valueArg: T | undefined, nameArg: string): T {
+    if (valueArg === undefined) throw new Error(`The ${this.#kind} fixture has no ${nameArg} in state ${this.#state}.`);
+    return valueArg;
+  }
+}