@emulates/docker 0.0.0-stage → 1.0.0

package/package.json

@@ -1,6 +1,123 @@
 {
   "name": "@emulates/docker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Stateful Docker Engine API v1.52 emulator with portable controls and Node transport.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "API_EVIDENCE.md",
+    "SUPPORT.md",
+    "ORACLE.md",
+    "evidence",
+    "scripts",
+    "DISCOVERY.md",
+    "openapi.yaml"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    }
+  },
+  "bin": {
+    "emulates-docker": "./dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crvouga/emulates.git",
+    "directory": "packages/service/docker"
+  },
+  "homepage": "https://github.com/crvouga/emulates/tree/main/packages/service/docker#readme",
+  "keywords": [
+    "emulates",
+    "service",
+    "docker",
+    "containers"
+  ],
+  "emulates": {
+    "runtime": "portable",
+    "entries": {
+      "server": "node",
+      "cli": "node"
+    },
+    "layer": "service",
+    "category": "infrastructure",
+    "displayName": "Docker Engine",
+    "vendor": {
+      "website": "https://www.docker.com",
+      "docs": "https://docs.docker.com/reference/api/engine/version/v1.52/",
+      "description": "Docker Engine provides a public API for container lifecycle and attached streams.",
+      "name": "Docker",
+      "icon": "docker"
+    },
+    "status": "wip",
+    "playground": {
+      "operation": "SystemVersion"
+    },
+    "parity": "Docker Engine container lifecycle, logs and streams",
+    "discovery": {
+      "guide": "DISCOVERY.md",
+      "behavior": "README.md",
+      "capabilities": "SUPPORT.md",
+      "contract": "openapi.yaml",
+      "types": "dist/index.d.ts",
+      "oracle": {
+        "kind": "Live vendor API or sandbox",
+        "command": "bun run parity:service -- docker",
+        "note": "Run from an Emulates checkout; credentials come only from .env.local or GitHub Actions secrets. Missing credentials exit 2."
+      },
+      "introspection": [
+        "GET /__admin/health",
+        "GET /__admin",
+        "GET /__admin/state",
+        "GET /__admin/requests",
+        "GET /__admin/metrics",
+        "GET /__admin/faults/presets",
+        "GET /__admin/ui"
+      ],
+      "reporting": "https://github.com/crvouga/emulates/blob/main/docs/REPORTING_ISSUES.md"
+    }
+  },
+  "scripts": {
+    "generate": "bun ../../openapi/codegen/dist/cli.js",
+    "generate:check": "bun ../../openapi/codegen/dist/cli.js --check",
+    "openapi:check": "bun ../../openapi/codegen/dist/cli.js --validate",
+    "build": "bun ../../../scripts/bundle-service.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "biome check .",
+    "test": "bun test",
+    "portability": "bun ../../../scripts/portability.ts",
+    "pack:check": "bun ../../../scripts/pack-check.ts"
+  },
+  "dependencies": {
+    "@emulates/sqlite": "3.0.0",
+    "hono": "4.11.9"
+  },
+  "devDependencies": {
+    "fast-check": "4.9.0",
+    "@emulates/testing": "0.1.0",
+    "@emulates/sqlite": "0.0.0-development",
+    "@emulates/parity": "0.0.0-development",
+    "@emulates/openapi-codegen": "0.1.0",
+    "@emulates/openapi-metadata": "0.0.0-development",
+    "@emulates/core": "0.0.0-development",
+    "@emulates/sqlite-client": "0.0.0-development",
+    "@emulates/openapi": "0.0.0-development",
+    "@emulates/service": "0.0.0-development",
+    "@emulates/adapter-node": "0.0.0-development"
+  }
+}

package/scripts/docker-oracle.mjs

@@ -0,0 +1,276 @@
+import { pathToFileURL } from "node:url"
+import { isDeepStrictEqual } from "node:util"
+import { createServer } from "../dist/server.js"
+import {
+  attach,
+  execution,
+  imageDefaults,
+  jsonRequest,
+  owned,
+  parseOptions,
+  supportsApi,
+} from "./oracle-client.mjs"
+
+export const runOracle = async (options) => {
+  const report = {
+    oracle: "Docker Engine",
+    expectedVersion: options.engineVersion,
+    comparisonApi: "1.52",
+    runId: options.runId,
+    image: options.image,
+    comparisons: [],
+    cleanup: [],
+    gaps: [
+      "No daemon restart or live-restore scenario executed",
+      "Transport response-loss evidence is synthetic and recorded separately in US-008/US-012",
+      "No host enforcement, SDK or external consumer policy verification",
+    ],
+    passed: false,
+  }
+  // No default Docker context, environment variable, CLI or host socket is consulted.
+  const real = options.endpoint
+  const read = (endpoint, path) => jsonRequest(endpoint, "GET", path)
+  const compare = (label, actual, modeled) => {
+    const equal = isDeepStrictEqual(actual, modeled)
+    report.comparisons.push({ label, actual, modeled, equal })
+    if (!equal) throw new Error(`Comparison failed: ${label}`)
+  }
+  const requireStatus = (response, expected, label) => {
+    if (response.status !== expected)
+      throw new Error(`${label}: expected ${expected}, received ${response.status}`)
+    return response.body
+  }
+  const intents = []
+  let server
+  const attachments = []
+  try {
+    const version = requireStatus(await read(real, "/version"), 200, "Engine version")
+    report.version = {
+      version: version.Version,
+      api: version.ApiVersion,
+      minimumApi: version.MinAPIVersion,
+      os: version.Os,
+      arch: version.Arch,
+      gitCommit: version.GitCommit,
+    }
+    if (
+      version.Version !== options.engineVersion ||
+      !supportsApi(version) ||
+      version.Os !== "linux"
+    )
+      throw new Error(
+        "Oracle requires the explicitly selected Linux Engine version and API 1.52 support",
+      )
+    const image = requireStatus(
+      await read(real, `/v1.52/images/${options.image}/json`),
+      200,
+      "Existing image",
+    )
+    if (image.Id !== options.image || image.Os !== "linux")
+      throw new Error("Oracle image identity or OS mismatch")
+    const defaults = imageDefaults(image)
+    report.omittedImageMetadata = defaults.omitted
+    report.imagePlatform = { os: image.Os, architecture: image.Architecture }
+    // Reject collisions before any real mutation; never adopt preexisting resources.
+    for (const scenario of ["attach", "stop", "kill"]) {
+      const name = `${options.runId}-${scenario}`
+      requireStatus(await read(real, `/v1.52/containers/${name}/json`), 404, "Ownership preflight")
+    }
+    server = await createServer()
+    const mock = { host: server.host, port: server.port }
+    requireStatus(
+      await jsonRequest(mock, "POST", "/__admin/docker/seed", {
+        images: [
+          {
+            id: image.Id,
+            tags: [],
+            config: defaults.config,
+            platform: `${image.Os}/${image.Architecture ?? "amd64"}`,
+          },
+        ],
+      }),
+      201,
+      "Mock image seed",
+    )
+    for (const scenario of ["attach", "stop", "kill"]) {
+      const name = `${options.runId}-${scenario}`
+      const intent = { name }
+      // Track the unique create intent before I/O so an accepted-but-lost create is recoverable.
+      intents.push(intent)
+      const body = {
+        Image: options.image,
+        Cmd: [
+          "/bin/sh",
+          "-c",
+          scenario === "attach"
+            ? "read line; printf '%s\\n' \"$line\"; printf 'oracle-stderr\\n' >&2; exit 7"
+            : "while :; do sleep 1; done",
+        ],
+        Entrypoint: [""],
+        WorkingDir: "/",
+        OpenStdin: true,
+        Tty: false,
+        Labels: { "emulates.oracle": options.runId },
+        HostConfig: { NetworkMode: "none" },
+      }
+      const created = await jsonRequest(real, "POST", `/v1.52/containers/create?name=${name}`, body)
+      if (created.status === 201 && /^[a-f0-9]{64}$/.test(created.body?.Id ?? ""))
+        intent.id = created.body.Id
+      if (created.status !== 201) intents.pop() // A definitive rejected create conveys no ownership.
+      requireStatus(created, 201, "Real create")
+      if (!intent.id) throw new Error("Real create returned invalid container ID")
+      const modeled = await jsonRequest(mock, "POST", `/v1.52/containers/create?name=${name}`, body)
+      compare(`${scenario}: create status`, created.status, modeled.status)
+      const mockId = requireStatus(modeled, 201, "Mock create").Id
+      const realPath = `/v1.52/containers/${intent.id}`
+      const mockPath = `/v1.52/containers/${mockId}`
+      const inspect = async () => {
+        const actual = requireStatus(await read(real, `${realPath}/json`), 200, "Real inspect")
+        if (!owned(actual, intent, options)) throw new Error("Container ownership changed")
+        const simulated = requireStatus(await read(mock, `${mockPath}/json`), 200, "Mock inspect")
+        compare(`${scenario}: execution`, execution(actual), execution(simulated))
+      }
+      await inspect()
+      const started = await jsonRequest(real, "POST", `${realPath}/start`)
+      const modeledStart = await jsonRequest(mock, "POST", `${mockPath}/start`)
+      compare(`${scenario}: start status`, started.status, modeledStart.status)
+      requireStatus(started, 204, "Real start")
+      requireStatus(modeledStart, 204, "Mock start")
+      await inspect()
+      if (scenario === "attach") {
+        const actual = await attach(real, intent.id)
+        attachments.push(actual)
+        const simulated = await attach(mock, mockId)
+        attachments.push(simulated)
+        compare("attach: upgrade", actual.headers, simulated.headers)
+        actual.socket.write("oracle-probe\n")
+        simulated.socket.write("oracle-probe\n")
+        const [handle] = server.attachments()
+        if (!handle) throw new Error("Missing synthetic attachment")
+        let input = Buffer.alloc(0)
+        const deadline = performance.now() + 2000
+        while (!input.includes("\n")) {
+          input = Buffer.concat([input, Buffer.from(handle.takeStdin())])
+          if (performance.now() > deadline) throw new Error("Synthetic stdin timeout")
+          await new Promise((resolve) => setImmediate(resolve))
+        }
+        compare("attach: stdin", "oracle-probe\n", input.toString())
+        await handle.write("stdout", Buffer.from("oracle-probe\n"))
+        await handle.write("stderr", Buffer.from("oracle-stderr\n"))
+        requireStatus(
+          await jsonRequest(mock, "POST", `/__admin/docker/containers/${mockId}/complete`, {
+            exitCode: 7,
+          }),
+          200,
+          "Mock completion",
+        )
+        compare(
+          "attach: normalized channel bytes (base64)",
+          await actual.done,
+          await simulated.done,
+        )
+      } else {
+        const suffix = scenario === "stop" ? "/stop?t=0" : "/kill?signal=KILL"
+        const simulated = jsonRequest(mock, "POST", `${mockPath}${suffix}`)
+        void simulated.catch(() => {})
+        const deadline = performance.now() + 2000
+        while (server.runtime.instance().lifecycle.pending === 0) {
+          if (performance.now() > deadline)
+            throw new Error("Synthetic termination was not accepted")
+          await new Promise((resolve) => setImmediate(resolve))
+        }
+        const actual = await jsonRequest(real, "POST", `${realPath}${suffix}`)
+        requireStatus(actual, 204, "Real termination")
+        requireStatus(
+          await jsonRequest(mock, "POST", `/__admin/docker/containers/${mockId}/complete`, {
+            exitCode: 137,
+          }),
+          200,
+          "Mock termination",
+        )
+        compare(`${scenario}: termination status`, actual.status, (await simulated).status)
+      }
+      const actualWait = requireStatus(
+        await jsonRequest(real, "POST", `${realPath}/wait`),
+        200,
+        "Real wait",
+      )
+      const mockWait = requireStatus(
+        await jsonRequest(mock, "POST", `${mockPath}/wait`),
+        200,
+        "Mock wait",
+      )
+      compare(`${scenario}: wait status code`, actualWait.StatusCode, mockWait.StatusCode)
+      await inspect()
+      // Recheck exact identity immediately before deleting this run's known stopped container.
+      const beforeRemove = requireStatus(
+        await read(real, `${realPath}/json`),
+        200,
+        "Removal ownership",
+      )
+      if (!owned(beforeRemove, intent, options)) throw new Error("Removal ownership mismatch")
+      const removed = await jsonRequest(real, "DELETE", realPath)
+      const modeledRemove = await jsonRequest(mock, "DELETE", mockPath)
+      compare(`${scenario}: remove status`, removed.status, modeledRemove.status)
+      requireStatus(removed, 204, "Real remove")
+      requireStatus(modeledRemove, 204, "Mock remove")
+      const absent = await read(real, `${realPath}/json`)
+      const modeledAbsent = await read(mock, `${mockPath}/json`)
+      compare(`${scenario}: removed inspection`, absent.status, modeledAbsent.status)
+      requireStatus(absent, 404, "Real removed inspection")
+      requireStatus(modeledAbsent, 404, "Mock removed inspection")
+    }
+    report.passed = true
+  } catch (error) {
+    // Record our own diagnostics; remote response bodies and credentials are never logged.
+    report.error = error instanceof Error ? error.message : "Oracle execution failed"
+  } finally {
+    for (const attachment of attachments) attachment.socket.destroy()
+    for (const intent of intents) {
+      try {
+        const found = await read(real, `/v1.52/containers/${intent.id ?? intent.name}/json`)
+        if (found.status === 404) {
+          report.cleanup.push({ name: intent.name, status: "absent" })
+          continue
+        }
+        if (found.status !== 200 || !owned(found.body, intent, options)) {
+          report.passed = false
+          report.cleanup.push({
+            name: intent.name,
+            status: "failed",
+            reason: "Ownership not proven; cleanup refused",
+          })
+          continue
+        }
+        const removed = await jsonRequest(
+          real,
+          "DELETE",
+          `/v1.52/containers/${found.body.Id}?force=true`,
+        )
+        requireStatus(removed, 204, "Owned cleanup")
+        report.cleanup.push({ name: intent.name, status: "removed" })
+      } catch (error) {
+        report.passed = false
+        report.cleanup.push({
+          name: intent.name,
+          status: "failed",
+          reason: error instanceof Error ? error.message : "Cleanup failed",
+        })
+      }
+    }
+    await server?.close()
+  }
+  return report
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const options = parseOptions(process.argv.slice(2))
+    const report = await runOracle(options)
+    console.log(JSON.stringify(report, null, 2))
+    process.exitCode = report.passed ? 0 : 1
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : "Invalid oracle invocation")
+    process.exitCode = 1
+  }
+}

package/scripts/oracle-client.mjs

@@ -0,0 +1,229 @@
+import { request } from "node:http"
+
+export const parseOptions = (args) => {
+  const options = {}
+  const names = new Set(["endpoint", "engine-version", "image", "run-id"])
+  for (let i = 0; i < args.length; i++) {
+    const key = args[i].replace(/^--/, "")
+    if (args[i] === "--allow-lifecycle") {
+      if (options.allowLifecycle) throw new Error("Duplicate lifecycle authorization")
+      options.allowLifecycle = true
+    } else {
+      if (!args[i].startsWith("--") || !names.has(key) || options[key] !== undefined)
+        throw new Error("Unknown or duplicate oracle option")
+      const value = args[++i]
+      if (!value || value.startsWith("--")) throw new Error(`Missing ${key}`)
+      options[key] = value
+    }
+  }
+  if (!options.allowLifecycle) throw new Error("Explicit --allow-lifecycle is required")
+  if (!/^\d+\.\d+\.\d+$/.test(options["engine-version"] ?? ""))
+    throw new Error("Explicit numeric --engine-version is required")
+  if (!/^sha256:[a-f0-9]{64}$/.test(options.image ?? ""))
+    throw new Error("Existing immutable --image sha256 ID is required")
+  if (!/^mb-oracle-[a-f0-9]{32}$/.test(options["run-id"] ?? ""))
+    throw new Error("Unique --run-id mb-oracle-<32 lowercase hex characters> is required")
+  return {
+    endpoint: parseEndpoint(options.endpoint),
+    engineVersion: options["engine-version"],
+    image: options.image,
+    runId: options["run-id"],
+  }
+}
+
+export const parseEndpoint = (value) => {
+  if (typeof value !== "string" || !value)
+    throw new Error("Explicit --endpoint is required; no default daemon is used")
+  let url
+  try {
+    url = new URL(value)
+  } catch {
+    throw new Error("Invalid oracle endpoint")
+  }
+  if (url.username || url.password || url.search || url.hash)
+    throw new Error("Endpoint credentials, query and fragment are not supported")
+  if (url.protocol === "unix:" && !url.host && url.pathname.startsWith("/") && url.pathname !== "/")
+    return { socketPath: decodeURIComponent(url.pathname) }
+  if (
+    url.protocol === "http:" &&
+    ["127.0.0.1", "[::1]", "localhost"].includes(url.hostname) &&
+    url.pathname === "/"
+  )
+    return { host: url.hostname.replace(/^\[|\]$/g, ""), port: Number(url.port || 80) }
+  throw new Error("Use an explicit unix:///absolute/socket or loopback http://host:port endpoint")
+}
+
+export const jsonRequest = (endpoint, method, path, body) =>
+  new Promise((resolve, reject) => {
+    const bytes = body === undefined ? Buffer.alloc(0) : Buffer.from(JSON.stringify(body))
+    const req = request(
+      {
+        ...endpoint,
+        method,
+        path,
+        agent: false,
+        headers: {
+          "content-type": "application/json",
+          "content-length": bytes.length,
+        },
+      },
+      (res) => {
+        const chunks = []
+        let size = 0
+        res.on("data", (chunk) => {
+          size += chunk.length
+          if (size > 1024 * 1024) res.destroy(new Error("Oracle response exceeds 1 MiB"))
+          else chunks.push(chunk)
+        })
+        res.once("error", reject)
+        res.once("aborted", () => reject(new Error("Oracle response aborted")))
+        res.once("end", () => {
+          try {
+            const text = Buffer.concat(chunks).toString()
+            resolve({ status: res.statusCode, body: text ? JSON.parse(text) : null })
+          } catch {
+            reject(new Error("Oracle response is not JSON"))
+          }
+        })
+      },
+    )
+    req.once("error", reject)
+    req.setTimeout(10_000, () => req.destroy(new Error("Oracle HTTP timeout")))
+    req.end(bytes)
+  })
+
+export const attach = (endpoint, id) =>
+  new Promise((resolve, reject) => {
+    const req = request({
+      ...endpoint,
+      method: "POST",
+      agent: false,
+      path: `/v1.52/containers/${id}/attach?stream=1&stdin=1&stdout=1&stderr=1`,
+      headers: { connection: "Upgrade", upgrade: "tcp", "content-length": "0" },
+    })
+    req.once("error", reject)
+    req.setTimeout(10_000, () => req.destroy(new Error("Oracle upgrade timeout")))
+    req.once("response", (res) => {
+      res.resume()
+      reject(new Error(`Attach did not upgrade: ${res.statusCode}`))
+    })
+    req.once("upgrade", (res, socket, head) => {
+      let pending = Buffer.alloc(0)
+      const output = { stdout: [], stderr: [] }
+      let total = 0
+      const done = new Promise((finish, fail) => {
+        let ended = false
+        const receive = (bytes) => {
+          total += bytes.length
+          if (total > 1024 * 1024) {
+            socket.destroy(new Error("Oracle stream exceeds 1 MiB"))
+            return
+          }
+          pending = Buffer.concat([pending, bytes])
+          while (pending.length >= 8) {
+            const channel = pending[0]
+            const size = pending.readUInt32BE(4)
+            if (
+              ![1, 2].includes(channel) ||
+              pending.subarray(1, 4).some((byte) => byte !== 0) ||
+              size > 1024 * 1024
+            ) {
+              socket.destroy(new Error("Invalid Docker multiplexed frame"))
+              return
+            }
+            if (pending.length < 8 + size) return
+            output[channel === 1 ? "stdout" : "stderr"].push(pending.subarray(8, 8 + size))
+            pending = pending.subarray(8 + size)
+          }
+        }
+        socket.on("data", receive)
+        socket.once("error", fail)
+        socket.once("end", () => {
+          ended = true
+          socket.end()
+          if (pending.length) fail(new Error("Truncated Docker frame"))
+          else
+            finish({
+              stdout: Buffer.concat(output.stdout).toString("base64"),
+              stderr: Buffer.concat(output.stderr).toString("base64"),
+            })
+        })
+        socket.once("close", () => {
+          if (!ended) fail(new Error("Attach closed without EOF"))
+        })
+        socket.setTimeout(10_000, () => socket.destroy(new Error("Oracle stream timeout")))
+        if (head.length) receive(head)
+      })
+      // Attach may fail before the caller reaches its comparison; retain rejection for await.
+      void done.catch(() => {})
+      resolve({
+        socket,
+        done,
+        headers: {
+          status: res.statusCode,
+          type: res.headers["content-type"],
+          upgrade: res.headers.upgrade,
+        },
+      })
+    })
+    req.end()
+  })
+
+export const owned = (record, intent, options) =>
+  record?.Name === `/${intent.name}` &&
+  record.Image === options.image &&
+  record.Config?.Labels?.["emulates.oracle"] === options.runId &&
+  /^[a-f0-9]{64}$/.test(record.Id ?? "") &&
+  (!intent.id || record.Id === intent.id)
+
+export const execution = (record) => ({
+  status: record.State.Status,
+  running: record.State.Running,
+  exitCode: record.State.ExitCode,
+})
+
+export const supportsApi = (version, target = "1.52") => {
+  const parse = (value) =>
+    typeof value === "string" && /^\d+\.\d+$/.test(value) ? value.split(".").map(Number) : null
+  const min = parse(version.MinAPIVersion),
+    max = parse(version.ApiVersion),
+    selected = parse(target)
+  const compare = (a, b) => a[0] - b[0] || a[1] - b[1]
+  return Boolean(
+    min && max && selected && compare(min, selected) <= 0 && compare(selected, max) <= 0,
+  )
+}
+
+export const imageDefaults = (image) => {
+  const config = image.Config ?? {}
+  if (Object.keys(config.Volumes ?? {}).length)
+    throw new Error("Oracle image must not declare volumes")
+  if (config.Healthcheck?.Test?.length && config.Healthcheck.Test[0] !== "NONE")
+    throw new Error("Oracle image must not declare an active healthcheck")
+  const fields = [
+    "Cmd",
+    "Entrypoint",
+    "Env",
+    "WorkingDir",
+    "User",
+    "Labels",
+    "StopSignal",
+    "StopTimeout",
+    "AttachStdin",
+    "AttachStdout",
+    "AttachStderr",
+    "OpenStdin",
+    "StdinOnce",
+    "Tty",
+    "NetworkDisabled",
+    "Hostname",
+    "Domainname",
+    "Image",
+  ]
+  return {
+    config: Object.fromEntries(Object.entries(config).filter(([key]) => fields.includes(key))),
+    omitted: Object.keys(config)
+      .filter((key) => !fields.includes(key))
+      .sort(),
+  }
+}