socketduct 0.1.15

package/test/unit/client/virtual-socket.test.js

@@ -0,0 +1,98 @@
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-param-type, jsdoc/require-returns */
+import assert from "node:assert/strict"
+import test from "node:test"
+
+import {VirtualSocket} from "../../../src/client/virtual-socket.js"
+
+/**
+ *
+ */
+function fakeConnection() {
+  const calls = {destroyed: 0, ended: 0, resumed: 0, refs: 0, unrefs: 0}
+  return {
+    calls,
+    connection: /** @type {import('../../../src/client/multiplexed-connection.js').MultiplexedSocketductConnection} */ (/** @type {unknown} */ ({
+      /**
+       * @param {number} _id @param {Buffer} _data @param {(error?: Error | null) => void} callback
+       * @param _data
+       * @param callback
+       */
+      _writeStream: (_id, _data, callback) => setImmediate(callback),
+      /**
+       * @param {number} _id @param {(error?: Error | null) => void} callback
+       * @param callback
+       */
+      _endStream: (_id, callback) => { calls.ended += 1; callback() },
+      _destroyStream: () => { calls.destroyed += 1 },
+      _resumeReadable: () => { calls.resumed += 1 },
+      physicalAddress: () => ({address: "127.0.0.1", port: 43210}),
+      ref: () => { calls.refs += 1 },
+      unref: () => { calls.unrefs += 1 }
+    }))
+  }
+}
+
+test("VirtualSocket exposes normal connect metadata and compatibility methods", async () => {
+  const fake = fakeConnection()
+  const socket = new VirtualSocket(fake.connection, 1, {host: "target.internal", port: 443})
+  /** @type {string[]} */
+  const events = []
+  socket.on("connect", () => events.push("connect"))
+  socket.on("ready", () => events.push("ready"))
+  socket._markConnected()
+
+  assert.deepEqual(events, ["connect", "ready"])
+  assert.equal(socket.connecting, false)
+  assert.equal(socket.pending, false)
+  assert.equal(socket.remoteAddress, "target.internal")
+  assert.equal(socket.remotePort, 443)
+  assert.deepEqual(socket.address(), {address: "127.0.0.1", family: "IPv4", port: 43210})
+  assert.equal(socket.setNoDelay(), socket)
+  assert.equal(socket.setKeepAlive(), socket)
+  assert.equal(socket.ref(), socket)
+  assert.equal(socket.unref(), socket)
+  assert.equal(fake.calls.refs, 1)
+  assert.equal(fake.calls.unrefs, 1)
+  socket.destroy()
+  await new Promise((resolve) => socket.once("close", resolve))
+})
+
+test("VirtualSocket write backpressure emits drain and end emits finish", async () => {
+  const fake = fakeConnection()
+  const socket = new VirtualSocket(fake.connection, 3, {
+    host: "127.0.0.1",
+    port: 80,
+    writableHighWaterMark: 1,
+    allowHalfOpen: true
+  })
+  socket._markConnected()
+  const drained = new Promise((resolve) => socket.once("drain", resolve))
+  assert.equal(socket.write("payload"), false)
+  await drained
+  assert.equal(socket.bytesWritten, 7)
+  const finished = new Promise((resolve) => socket.once("finish", resolve))
+  socket.end()
+  await finished
+  assert.equal(fake.calls.ended, 1)
+  socket.destroy()
+})
+
+test("VirtualSocket pause/resume, timeout, data and half-close remain stream-local", async () => {
+  const fake = fakeConnection()
+  const socket = new VirtualSocket(fake.connection, 5, {host: "127.0.0.1", port: 80, allowHalfOpen: true})
+  socket._markConnected()
+  socket.pause()
+  const timeout = new Promise((resolve) => socket.setTimeout(10, () => resolve(undefined)))
+  await timeout
+  socket.setTimeout(0)
+  const data = new Promise((resolve) => socket.once("data", (chunk) => resolve(chunk.toString())))
+  socket._receive(Buffer.from("hello"))
+  socket.resume()
+  assert.equal(await data, "hello")
+  assert.equal(socket.bytesRead, 5)
+  const ended = new Promise((resolve) => socket.once("end", resolve))
+  socket._receiveEnd()
+  await ended
+  assert(fake.calls.resumed > 0)
+  socket.destroy()
+})

package/test/unit/config/docker-gateway-files.test.js

@@ -0,0 +1,274 @@
+import assert from "node:assert/strict"
+import {spawnSync} from "node:child_process"
+import {copyFile, mkdtemp, readFile, readdir, rm} from "node:fs/promises"
+import {tmpdir} from "node:os"
+import {delimiter, join} from "node:path"
+import test from "node:test"
+
+const composePath = new URL("../../../docker-compose.yml", import.meta.url)
+const developmentComposePath = new URL("../../../docker-compose.dev.yml", import.meta.url)
+const reverseComposePath = new URL("../../../docker-compose.reverse-gateway.yml", import.meta.url)
+const envExamplePath = new URL("../../../.env.example", import.meta.url)
+const githubWorkflowsPath = new URL("../../../.github/workflows/", import.meta.url)
+const docsPath = new URL("../../../docs/docker.md", import.meta.url)
+const packagePath = new URL("../../../package.json", import.meta.url)
+const runningDocsPath = new URL("../../../docs/running.md", import.meta.url)
+const scriptPath = new URL("../../../scripts/deploy-gateway.js", import.meta.url)
+const securityDocsPath = new URL("../../../docs/security.md", import.meta.url)
+const tensorbuzzPath = new URL("../../../tensorbuzz.yml", import.meta.url)
+
+/** @returns {Promise<string[]>} GitHub Actions workflow filenames, if the directory exists. */
+async function githubWorkflowNames() {
+  try {
+    return await readdir(githubWorkflowsPath)
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return []
+    throw error
+  }
+}
+
+test("TensorBuzz exclusively owns verification and container build validation", async () => {
+  const [packageJson, tensorbuzz, workflowNames] = await Promise.all([
+    readFile(packagePath, "utf8"),
+    readFile(tensorbuzzPath, "utf8"),
+    githubWorkflowNames()
+  ])
+  const packageMetadata = JSON.parse(packageJson)
+
+  assert.deepEqual(workflowNames, [])
+  assert.match(tensorbuzz, /DOCKER_HOST: "tcp:\/\/docker_server:2375"/)
+  assert.match(tensorbuzz, /docker_server:\n\s+image: "docker:[^"]+-dind"/)
+  assert.match(tensorbuzz, /privileged: true/)
+  assert.match(tensorbuzz, /docker build --tag socketduct-ci \./)
+  assert.doesNotMatch(tensorbuzz, /docker (?:login|push)/)
+  assert.equal(packageMetadata.private, true)
+  assert.equal(packageMetadata.license, "UNLICENSED")
+})
+
+test("Docker gateway files define a private Docker socket shim target", async () => {
+  const [compose, envExample, docs] = await Promise.all([
+    readFile(composePath, "utf8"),
+    readFile(envExamplePath, "utf8"),
+    readFile(docsPath, "utf8")
+  ])
+
+  assert.match(compose, /docker-socket-shim:/)
+  assert.match(compose, /profiles:\n\s+- docker-host/)
+  assert.match(compose, /\/var\/run\/docker\.sock:\/var\/run\/docker\.sock/)
+  assert.match(compose, /expose:\n\s+- "2375"/)
+  assert.doesNotMatch(compose, /2375:2375/)
+  assert.match(envExample, /SOCKETDUCT_TARGET_ALLOWLIST=docker-socket-shim:2375/)
+  assert.match(docs, /Docker socket shim/)
+})
+
+test("native reverse gateway Compose has outbound-only private Docker access", async () => {
+  const compose = await readFile(reverseComposePath, "utf8")
+  assert.match(compose, /SOCKETDUCT_MODE: reverse-gateway/)
+  assert.match(compose, /SOCKETDUCT_TARGET_ALLOWLIST: docker-server:2375/)
+  assert.match(compose, /docker-control:/)
+  assert.match(compose, /wan-egress:/)
+  assert.doesNotMatch(compose, /\bports:/)
+  assert.doesNotMatch(compose, /socat|socket-shim|2375:2375/)
+})
+
+test("production Compose roles expose the opt-in persistent log mount contract", async () => {
+  const [compose, reverseCompose, envExample, docs] = await Promise.all([
+    readFile(composePath, "utf8"),
+    readFile(reverseComposePath, "utf8"),
+    readFile(envExamplePath, "utf8"),
+    readFile(docsPath, "utf8")
+  ])
+
+  for (const model of [compose, reverseCompose]) {
+    assert.match(model, /\$\{SOCKETDUCT_LOG_HOST_DIRECTORY:-\.\/logs\}:\/var\/log\/socketduct/)
+  }
+  assert.match(envExample, /SOCKETDUCT_LOG_DIRECTORY=\/var\/log\/socketduct/)
+  assert.match(envExample, /SOCKETDUCT_LOG_HOST_DIRECTORY=\/srv\/socketduct\/logs/)
+  assert.match(docs, /SOCKETDUCT_LOG_HOST_DIRECTORY/)
+  assert.match(docs, /\/var\/log\/socketduct/)
+})
+
+test("production gateway Compose requires an immutable Socketduct GHCR image", async () => {
+  const [compose, developmentCompose, envExample] = await Promise.all([
+    readFile(composePath, "utf8"),
+    readFile(developmentComposePath, "utf8"),
+    readFile(envExamplePath, "utf8")
+  ])
+
+  assert.match(compose, /image: \$\{SOCKETDUCT_IMAGE:\?[^}]+\}/)
+  assert.doesNotMatch(compose, /\bbuild:/)
+  assert.doesNotMatch(compose, /socketduct:latest/)
+  assert.match(developmentCompose, /\bbuild:/)
+  assert.match(envExample, /SOCKETDUCT_IMAGE=ghcr\.io\/kaspernj\/socketduct@sha256:/)
+})
+
+test("gateway deployment rejects mutable images before running Docker", async () => {
+  const {deployGateway} = await import("../../../scripts/deploy-gateway.js")
+  /** @type {Array<[string, string[]]>} */
+  const calls = []
+
+  for (const image of [
+    undefined,
+    "",
+    "socketduct:latest",
+    "ghcr.io/kaspernj/socketduct:latest",
+    "ghcr.io/kaspernj/socketduct:main",
+    "ghcr.io/kaspernj/socketduct:40cc261",
+    `ghcr.io/kaspernj/socketduct:release@sha256:${"a".repeat(64)}`,
+    `ghcr.io/kaspernj/socketduct@sha256:${"A".repeat(64)}`
+  ]) {
+    await assert.rejects(
+      deployGateway({image, run: (command, args) => { calls.push([command, args]); return "" }}),
+      /immutable GHCR image/
+    )
+  }
+  assert.deepEqual(calls, [])
+})
+
+test("gateway deployment fixes Compose inputs, neutralizes ambient selectors, then verifies and applies", async () => {
+  const {deployGateway} = await import("../../../scripts/deploy-gateway.js")
+  /** @type {Array<[string, string[], {captureStdout?: boolean, env: Record<string, string | undefined>}]>} */
+  const calls = []
+  const digest = "a".repeat(64)
+  const image = `ghcr.io/kaspernj/socketduct@sha256:${digest}`
+  const environment = {
+    PATH: "/usr/bin",
+    DOCKER_HOST: "ssh://gateway.example.test",
+    DOCKER_CONTEXT: "production-gateway",
+    COMPOSE_FILE: "/tmp/mutable-compose.yml",
+    COMPOSE_ENV_FILES: "/tmp/mutable.env",
+    COMPOSE_DISABLE_ENV_FILE: "1",
+    COMPOSE_IGNORE_ORPHANS: "1",
+    COMPOSE_REMOVE_ORPHANS: "1",
+    COMPOSE_PATH_SEPARATOR: ";",
+    COMPOSE_PROFILES: "docker-host",
+    COMPOSE_PROJECT_NAME: "ambient-project"
+  }
+
+  await deployGateway({
+    environment,
+    image,
+    projectDirectory: "/srv/socketduct release #1",
+    run: (command, args, options) => {
+      calls.push([command, args, options])
+      return args.includes("config")
+        ? JSON.stringify({services: {"socketduct-relay": {image}}})
+        : ""
+    }
+  })
+
+  const compose = [
+    "compose",
+    "--file", "/srv/socketduct release #1/docker-compose.yml",
+    "--env-file", "/srv/socketduct release #1/.env",
+    "--project-directory", "/srv/socketduct release #1",
+    "--project-name", "socketduct-gateway"
+  ]
+  assert.deepEqual(calls.map(([command, args, options]) => [command, args, options.captureStdout]), [
+    ["docker", [...compose, "config", "--format", "json"], true],
+    ["docker", [...compose, "pull"], undefined],
+    ["docker", [...compose, "up", "-d", "--wait", "--no-build"], undefined]
+  ])
+  for (const [, , options] of calls) {
+    assert.equal(options.env.DOCKER_HOST, environment.DOCKER_HOST)
+    assert.equal(options.env.DOCKER_CONTEXT, environment.DOCKER_CONTEXT)
+    assert.equal(options.env.COMPOSE_FILE, "/srv/socketduct release #1/docker-compose.yml")
+    assert.equal(options.env.COMPOSE_ENV_FILES, "/srv/socketduct release #1/.env")
+    assert.equal(options.env.COMPOSE_PATH_SEPARATOR, delimiter)
+    assert.equal(options.env.COMPOSE_DISABLE_ENV_FILE, "false")
+    assert.equal(options.env.COMPOSE_IGNORE_ORPHANS, "false")
+    assert.equal(options.env.COMPOSE_REMOVE_ORPHANS, "false")
+    assert.equal(options.env.COMPOSE_PROFILES, "")
+    assert.equal(options.env.COMPOSE_PROJECT_NAME, "socketduct-gateway")
+    assert.equal(options.env.SOCKETDUCT_IMAGE, image)
+  }
+})
+
+test("gateway deployment enables only the explicit docker-host profile", async () => {
+  const {deployGateway} = await import("../../../scripts/deploy-gateway.js")
+  /** @type {Array<{args: string[], environment: Record<string, string | undefined>}>} */
+  const calls = []
+  const image = `ghcr.io/kaspernj/socketduct@sha256:${"b".repeat(64)}`
+
+  await deployGateway({
+    dockerHost: true,
+    environment: {COMPOSE_PROFILES: "unexpected"},
+    image,
+    projectDirectory: "/srv/socketduct",
+    run: (_command, args, options) => {
+      calls.push({args, environment: options.env})
+      return args.includes("config")
+        ? JSON.stringify({services: {"socketduct-relay": {image}}})
+        : ""
+    }
+  })
+
+  assert.equal(calls.length, 3)
+  for (const {args, environment: childEnvironment} of calls) {
+    assert.equal(args.filter((argument) => argument === "--profile").length, 1)
+    assert.equal(args[args.indexOf("--profile") + 1], "docker-host")
+    assert.equal(childEnvironment.COMPOSE_PROFILES, "")
+  }
+})
+
+test("gateway deployment fails closed on a rendered image mismatch or build source", async () => {
+  const {deployGateway} = await import("../../../scripts/deploy-gateway.js")
+  const image = `ghcr.io/kaspernj/socketduct@sha256:${"c".repeat(64)}`
+  const renderedModels = [
+    {services: {"socketduct-relay": {image: "ghcr.io/kaspernj/socketduct:latest"}}},
+    {services: {"socketduct-relay": {build: {context: "."}, image}}},
+    {services: {}}
+  ]
+
+  for (const rendered of renderedModels) {
+    let calls = 0
+    await assert.rejects(deployGateway({
+      environment: {},
+      image,
+      projectDirectory: "/srv/socketduct",
+      run: () => {
+        calls += 1
+        return JSON.stringify(rendered)
+      }
+    }), /rendered.*socketduct-relay|build source/i)
+    assert.equal(calls, 1)
+  }
+})
+
+test("gateway deployment CLI runs from paths containing spaces and hash characters", async () => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct gateway #"))
+  const escapedScriptPath = join(root, "deploy gateway #.mjs")
+  try {
+    await copyFile(scriptPath, escapedScriptPath)
+    const result = spawnSync(process.execPath, [escapedScriptPath], {
+      encoding: "utf8",
+      env: {...process.env, SOCKETDUCT_IMAGE: "ghcr.io/kaspernj/socketduct:latest"}
+    })
+
+    assert.equal(result.status, 1)
+    assert.match(result.stderr, /immutable GHCR image/)
+  } finally {
+    await rm(root, {recursive: true, force: true})
+  }
+})
+
+test("gateway documentation describes pinning, private GHCR login, and digest rollback", async () => {
+  const [dockerDocs, packageJson, runningDocs, securityDocs] = await Promise.all([
+    readFile(docsPath, "utf8"),
+    readFile(packagePath, "utf8"),
+    readFile(runningDocsPath, "utf8"),
+    readFile(securityDocsPath, "utf8")
+  ])
+  const publicDocs = `${dockerDocs}\n${runningDocs}\n${securityDocs}`
+
+  assert.equal(JSON.parse(packageJson).scripts["gateway:deploy"], "node scripts/deploy-gateway.js")
+  assert.match(dockerDocs, /Node\.js 24/i)
+  assert.match(dockerDocs, /node --version/)
+  assert.match(dockerDocs, /npm --version/)
+  assert.match(dockerDocs, /npm run gateway:deploy/)
+  assert.match(dockerDocs, /--project-name socketduct-gateway/)
+  assert.match(dockerDocs, /docker login ghcr\.io/)
+  assert.match(dockerDocs, /rollback/i)
+  assert.match(dockerDocs, /change.*digest/i)
+  assert.doesNotMatch(publicDocs, /docker compose[^\n]*up[^\n]*--build/)
+})