@gpzhang2001/sharpkit-sandbox 0.2.1

package/src/spec.ts

@@ -0,0 +1,263 @@
+/**
+ * Pure spec→argv builders for the docker CLI sandbox (decision D1: argv
+ * constructed directly, no dockerode/docker SDK). Every function here is a
+ * total pure function over its inputs — no I/O, no clock, no environment —
+ * so the docker contract is exhaustively unit-testable (M1 DoD: 100%
+ * branch coverage on this module). Behavioral parity references are the
+ * strix runtime sources: session_manager.py env/port handling and
+ * docker_client.py `_create_container` (caps, extra_hosts, resource/log
+ * limits, 127.0.0.1-ephemeral port publishing, network mode).
+ * @module @gpzhang2001/sharpkit-sandbox/spec
+ */
+
+/** One host→container bind mount (`docker create -v source:target[:ro]`). */
+export interface SandboxBindMount {
+  readonly source: string
+  readonly target: string
+  readonly readOnly: boolean
+}
+
+/** Opt-in resource limits (strix: STRIX_SANDBOX_{MEM_LIMIT,SHM_SIZE,CPUS,PIDS_LIMIT}). */
+export interface SandboxResourceLimits {
+  /** Docker memory string, e.g. `"2g"`. */
+  readonly memLimit?: string | undefined
+  /** Docker shm size string, e.g. `"512m"`. */
+  readonly shmSize?: string | undefined
+  /** CPU count as a decimal fraction/multiple, e.g. `1.5`. */
+  readonly cpus?: number | undefined
+  /** Process-id limit inside the container. */
+  readonly pidsLimit?: number | undefined
+}
+
+/** Everything `docker create` needs; assembled by the service layer. */
+export interface SandboxCreateSpec {
+  /** Image reference, e.g. `ghcr.io/gpzhang2001/sharpkit-sandbox:1.0.0-fork2`. */
+  readonly image: string
+  /** Keep-alive command after the image (`["tail","-f","/dev/null"]` in strix). */
+  readonly command: readonly string[]
+  /** Container environment (`-e k=v` per entry; insertion order preserved). */
+  readonly env: Readonly<Record<string, string>>
+  /** Bind mounts, already sorted shallowest-target-first (strix ordering). */
+  readonly bindMounts: readonly SandboxBindMount[]
+  /** Container-side Caido port; published to `127.0.0.1` ephemeral unless network is set. */
+  readonly caidoPort: number
+  /** Attach to an existing docker network and publish no ports (strix sandbox-network mode). */
+  readonly network?: string | undefined
+  /** Linux capabilities appended after any defaults (`--cap-add`). */
+  readonly caps?: readonly string[]
+  /** Extra /etc/hosts entries (`--add-host k=v`). */
+  readonly extraHosts?: Readonly<Record<string, string>>
+  /** Optional resource limits. */
+  readonly resourceLimits?: SandboxResourceLimits
+  /** Log rotation max-size; disables log opts when one of 0/off/none/unlimited (strix default "50m"). */
+  readonly logMaxSize?: string
+  /** Log rotation file count (strix default 3). */
+  readonly logMaxFile?: number
+  /** Container labels (`--label k=v`; strix: sharpkit-run-id / sharpkit-run-type). */
+  readonly labels?: Readonly<Record<string, string>>
+}
+
+/** Values that disable the json-file log rotation opts (strix `_apply_log_limits`). */
+const LOG_DISABLED_SIZES = new Set(['0', 'off', 'none', 'unlimited'])
+
+/**
+ * Build the `docker create` argv for a sandbox spec. Env/hosts/labels are
+ * emitted in sorted-key order for deterministic tests; mounts keep their
+ * (pre-sorted) order.
+ * @param spec - the assembled create spec.
+ * @returns the full argv, `["docker","create",…flags,image,…command]`.
+ */
+export function buildCreateArgv(spec: SandboxCreateSpec): string[] {
+  const argv: string[] = ['docker', 'create']
+  for (const cap of spec.caps ?? []) argv.push('--cap-add', cap)
+  for (const key of Object.keys(spec.extraHosts ?? {}).sort()) argv.push('--add-host', `${key}=${spec.extraHosts?.[key]}`)
+  for (const key of Object.keys(spec.env).sort()) argv.push('-e', `${key}=${spec.env[key]}`)
+  for (const mount of spec.bindMounts) argv.push('-v', mount.readOnly ? `${mount.source}:${mount.target}:ro` : `${mount.source}:${mount.target}`)
+  if (spec.network !== undefined && spec.network !== '') {
+    // Sandbox-network mode: no published ports; consumers dial the container IP.
+    argv.push('--network', spec.network)
+  } else {
+    argv.push('-p', `127.0.0.1::${spec.caidoPort}`)
+  }
+  const limits = spec.resourceLimits
+  if (limits?.memLimit !== undefined && limits.memLimit !== '') argv.push('--memory', limits.memLimit)
+  if (limits?.shmSize !== undefined && limits.shmSize !== '') argv.push('--shm-size', limits.shmSize)
+  if (limits?.cpus !== undefined && limits.cpus > 0) argv.push('--cpus', String(limits.cpus))
+  if (limits?.pidsLimit !== undefined && Number.isInteger(limits.pidsLimit) && limits.pidsLimit > 0) argv.push('--pids-limit', String(limits.pidsLimit))
+  if (logRotationEnabled(spec.logMaxSize)) {
+    argv.push('--log-driver', 'json-file', '--log-opt', `max-size=${spec.logMaxSize}`, '--log-opt', `max-file=${spec.logMaxFile ?? 3}`)
+  }
+  for (const key of Object.keys(spec.labels ?? {}).sort()) argv.push('--label', `${key}=${spec.labels?.[key]}`)
+  argv.push(spec.image, ...spec.command)
+  return argv
+}
+
+/**
+ * Whether json-file rotation opts should be emitted for a max-size value.
+ * @param logMaxSize - the configured max-size; absent disables (docker default, unbounded).
+ * @returns true when rotation opts must be emitted.
+ */
+export function logRotationEnabled(logMaxSize: string | undefined): boolean {
+  return logMaxSize !== undefined && logMaxSize !== '' && !LOG_DISABLED_SIZES.has(logMaxSize.toLowerCase())
+}
+
+/**
+ * Build the container environment (strix session_manager.py:316-329 parity).
+ * Proxy vars point at the in-container Caido so all container HTTP traffic is
+ * interceptable; NO_PROXY keeps CDP/localhost traffic out of the proxy.
+ * @param options - ports/identity inputs; uid/gid only on Linux (ownership remap).
+ * @returns the env record in stable insertion order.
+ */
+export function buildContainerEnv(options: {
+  readonly caidoPort: number
+  readonly platform: NodeJS.Platform
+  readonly uid?: number | undefined
+  readonly gid?: number | undefined
+}): Record<string, string> {
+  const proxy = `http://127.0.0.1:${options.caidoPort}`
+  const env: Record<string, string> = {
+    PYTHONUNBUFFERED: '1',
+    HOST_GATEWAY: 'host.docker.internal',
+    http_proxy: proxy,
+    https_proxy: proxy,
+    ALL_PROXY: proxy,
+    NO_PROXY: 'localhost,127.0.0.1',
+  }
+  if (options.platform === 'linux' && options.uid !== undefined && options.uid > 0) {
+    env.SHARPKIT_HOST_UID = String(options.uid)
+    env.SHARPKIT_HOST_GID = String(options.gid ?? options.uid)
+  }
+  return env
+}
+
+/** Options for a non-interactive `docker exec` argv. */
+export interface SandboxExecArgvOptions {
+  readonly containerId: string
+  readonly command: string
+  /** Working directory inside the container (`-w`), typically under /workspace. */
+  readonly cwd?: string | undefined
+}
+
+/**
+ * Build the non-interactive exec argv: a fresh login shell per call
+ * (`bash -lc`), matching the S1 spike and the image's login-shell PATH fixups.
+ */
+export function buildExecArgv(options: SandboxExecArgvOptions): string[] {
+  const argv = ['docker', 'exec', '-i']
+  if (options.cwd !== undefined) argv.push('-w', options.cwd)
+  argv.push(options.containerId, 'bash', '-lc', options.command)
+  return argv
+}
+
+/** Options for a PTY-backed interactive `docker exec` argv. */
+export interface SandboxTtyArgvOptions {
+  readonly containerId: string
+  readonly command: string
+  readonly cwd?: string | undefined
+}
+
+/**
+ * Build the PTY exec argv (`docker exec -it`); the host-side PTY is provided
+ * by `ctx.subprocess.spawnTerminal` and Ctrl-C is delivered as `\x03`
+ * (spike finding D1.1).
+ */
+export function buildExecTtyArgv(options: SandboxTtyArgvOptions): string[] {
+  const argv = ['docker', 'exec', '-it']
+  if (options.cwd !== undefined) argv.push('-w', options.cwd)
+  argv.push(options.containerId, 'bash', '-lc', options.command)
+  return argv
+}
+
+/** A resolved host-side endpoint of a published container port. */
+export interface SandboxHostEndpoint {
+  readonly host: string
+  readonly port: number
+}
+
+/**
+ * Build the argv resolving a published port's host endpoint (`docker port`).
+ */
+export function buildPortArgv(containerId: string, port: number): string[] {
+  return ['docker', 'port', containerId, String(port)]
+}
+
+/**
+ * Parse `docker port` output into endpoints, preferring IPv4 (strix publishes
+ * to 127.0.0.1). IPv6 literals arrive bracketed and are returned bracket-free
+ * with `bracketedIPv6` only when the raw host contains `:`.
+ * @param output - the raw `docker port` stdout (zero or more lines).
+ * @returns endpoints, IPv4 entries first; empty when nothing is published.
+ */
+export function parsePortOutput(output: string): SandboxHostEndpoint[] {
+  const endpoints: SandboxHostEndpoint[] = []
+  for (const rawLine of output.split('\n')) {
+    const line = rawLine.trim()
+    if (line === '') continue
+    // Form: "127.0.0.1:49153" or "[::1]:49153".
+    const lastColon = line.lastIndexOf(':')
+    if (lastColon === -1) continue
+    const port = Number.parseInt(line.slice(lastColon + 1), 10)
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) continue
+    let host = line.slice(0, lastColon)
+    if (host.startsWith('[') && host.endsWith(']')) host = host.slice(1, -1)
+    if (host === '') continue
+    endpoints.push({ host, port })
+  }
+  const preferred = endpoints.filter(endpoint => !endpoint.host.includes(':'))
+  const ipv6 = endpoints.filter(endpoint => endpoint.host.includes(':'))
+  return [...preferred, ...ipv6]
+}
+
+/**
+ * Build the argv resolving the container's IP on a sandbox network (strix
+ * `StrixDockerSandboxSession._resolve_exposed_port`, network mode).
+ */
+export function buildNetworkIpArgv(containerId: string, network: string): string[] {
+  return ['docker', 'inspect', '--format', `{{.NetworkSettings.Networks.${network}.IPAddress}}`, containerId]
+}
+
+/** Container-side path reference for `docker cp` (`<id>:<path>`). */
+export function containerRef(containerId: string, containerPath: string): string {
+  return `${containerId}:${containerPath}`
+}
+
+/** Build the `docker cp` argv copying a host file into the container. */
+export function buildPutFileArgv(hostPath: string, containerId: string, containerPath: string): string[] {
+  return ['docker', 'cp', hostPath, containerRef(containerId, containerPath)]
+}
+
+/** Build the `docker cp` argv copying a container file out to a host path. */
+export function buildGetFileArgv(containerId: string, containerPath: string, hostPath: string): string[] {
+  return ['docker', 'cp', containerRef(containerId, containerPath), hostPath]
+}
+
+/** Build the graceful stop argv (`docker stop -t <seconds>`). */
+export function buildStopArgv(containerId: string, graceMs: number): string[] {
+  const seconds = Math.max(0, Math.round(graceMs / 1000))
+  return ['docker', 'stop', '-t', String(seconds), containerId]
+}
+
+/** Build the plain remove argv; the caller escalates to force-remove on failure. */
+export function buildRmArgv(containerId: string): string[] {
+  return ['docker', 'rm', containerId]
+}
+
+/** Build the force-remove argv (fallback path and failure cleanup). */
+export function buildRmForceArgv(containerId: string): string[] {
+  return ['docker', 'rm', '-f', containerId]
+}
+
+/** Build the argv checking whether an image is present locally. */
+export function buildImageInspectArgv(image: string): string[] {
+  return ['docker', 'image', 'inspect', image]
+}
+
+/** Build the pull argv (strix pulls only when the image is missing). */
+export function buildPullArgv(image: string): string[] {
+  return ['docker', 'pull', image]
+}
+
+/** Build the start argv. */
+export function buildStartArgv(containerId: string): string[] {
+  return ['docker', 'start', containerId]
+}