@namzu/sandbox 24.0.0 → 26.0.0

package/src/local-virtual-computer/detached-process.ts

@@ -0,0 +1,133 @@
+import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import type { SandboxDetachedProcess, SandboxSpawnOptions } from '@namzu/sdk'
+import type { DetachedWorkerConfiguration } from './detached-worker.js'
+
+export interface DetachedProcessOptions {
+	readonly executionUrl: string
+	readonly token: string
+	readonly retire: () => Promise<void>
+	/** Tests using source modules select the already built worker entry. */
+	readonly workerPath?: string
+}
+
+export interface OwnedDetachedProcess extends SandboxDetachedProcess {
+	readonly closed: Promise<void>
+	terminate(signal?: NodeJS.Signals): Promise<void>
+}
+
+/** Credentials and command payload travel over private IPC, never argv. */
+export function startDetachedGuestProcess(
+	options: DetachedProcessOptions,
+	command: string,
+	args: readonly string[] = [],
+	spawnOptions?: SandboxSpawnOptions,
+): OwnedDetachedProcess {
+	const child = spawn(
+		process.execPath,
+		[options.workerPath ?? fileURLToPath(new URL('./detached-worker.js', import.meta.url))],
+		{
+			windowsHide: true,
+			stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+			env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' },
+		},
+	)
+	let physicallyClosed = false
+	let confirmed = false
+	let recoveryRequired = false
+	let retirement: Promise<void> | undefined
+	const waiters = new Set<{
+		resolve: () => void
+		reject: (error: Error) => void
+	}>()
+	const closed = new Promise<void>((resolve) =>
+		child.once('close', () => {
+			physicallyClosed = true
+			resolve()
+			if (!confirmed) void retire().catch(() => {})
+		}),
+	)
+	const acceptConfirmation = () => {
+		confirmed = true
+		recoveryRequired = false
+		void closed.then(() => {
+			for (const waiter of waiters) waiter.resolve()
+			waiters.clear()
+		})
+	}
+	const retire = (): Promise<void> => {
+		if (retirement) return retirement
+		const attempt = Promise.resolve()
+			.then(() => options.retire())
+			.then(
+				() => {
+					acceptConfirmation()
+					if (child.connected) child.send({ type: 'retired', confirmed: true }, () => {})
+				},
+				() => {
+					recoveryRequired = true
+					const error = new Error(
+						'Guest termination and computer retirement could not be confirmed; operator recovery or a termination retry is required',
+					)
+					for (const waiter of waiters) waiter.reject(error)
+					waiters.clear()
+					if (child.connected) child.send({ type: 'retired', confirmed: false }, () => {})
+					throw error
+				},
+			)
+			.finally(() => {
+				retirement = undefined
+			})
+		retirement = attempt
+		return attempt
+	}
+	const requestCancellation = (signal: NodeJS.Signals) => {
+		if (confirmed) return
+		if (recoveryRequired || physicallyClosed) {
+			void retire().catch(() => {})
+			return
+		}
+		if (child.connected)
+			child.send({ type: 'cancel', signal }, (error) => {
+				if (error) void retire().catch(() => {})
+			})
+	}
+	child.once('spawn', () => {
+		const config: DetachedWorkerConfiguration = {
+			type: 'start',
+			executionUrl: options.executionUrl,
+			token: options.token,
+			command,
+			args: [...args],
+			...(spawnOptions?.cwd ? { cwd: spawnOptions.cwd } : {}),
+			...(spawnOptions?.env ? { env: spawnOptions.env } : {}),
+		}
+		if (child.connected)
+			child.send(config, (error) => {
+				if (error)
+					child.emit('error', new Error('The guest background bridge could not be initialized'))
+			})
+	})
+	child.on('message', (raw: unknown) => {
+		if (!raw || typeof raw !== 'object' || !('type' in raw)) return
+		if (raw.type === 'terminal-confirmed') acceptConfirmation()
+		if (raw.type === 'retire-computer') void retire().catch(() => {})
+	})
+	return {
+		child,
+		closed,
+		kill(signal) {
+			// Both TERM and escalation request confirmed guest cancellation.
+			// SIGKILL must never merely kill this host bridge and leave its
+			// remote shell running after the registry believes the job stopped.
+			requestCancellation(signal)
+		},
+		terminate(signal = 'SIGTERM') {
+			if (confirmed) return closed
+			return new Promise<void>((resolve, reject) => {
+				waiters.add({ resolve, reject })
+				requestCancellation(signal)
+			})
+		},
+	}
+}

package/src/local-virtual-computer/detached-worker.ts

@@ -0,0 +1,124 @@
+/** Host-side stream bridge. No command is executed on this host process. */
+import { HttpWorkerClient } from '../backends/http-worker-client.js'
+import { RemoteCancellationUnknownError } from '../backends/remote-execution-controller.js'
+
+export const LOCAL_BACKGROUND_TIMEOUT_MS = 2_147_000_000
+
+export interface DetachedWorkerConfiguration {
+	readonly type: 'start'
+	readonly executionUrl: string
+	readonly token: string
+	readonly command: string
+	readonly args: string[]
+	readonly cwd?: string
+	readonly env?: Record<string, string>
+}
+
+const controller = new AbortController()
+let started = false
+let disconnected = false
+let cancellation: NodeJS.Signals | undefined
+let retirement: ((confirmed: boolean) => void) | undefined
+
+function cancel(signal: NodeJS.Signals = 'SIGTERM'): void {
+	cancellation ??= signal
+	controller.abort(new Error('Guest background command cancelled'))
+}
+
+process.on('SIGTERM', () => cancel())
+process.on('SIGINT', () => cancel('SIGINT'))
+process.on('disconnect', () => {
+	disconnected = true
+	cancel()
+	retirement?.(false)
+})
+
+async function finish(code: number, confirmed = true): Promise<never> {
+	// Drain Node's own pipe buffers before reporting terminal state.
+	await Promise.all([
+		new Promise<void>((resolve) => process.stdout.write('', () => resolve())),
+		new Promise<void>((resolve) => process.stderr.write('', () => resolve())),
+	])
+	if (confirmed && process.connected)
+		await new Promise<void>((resolve) =>
+			process.send?.({ type: 'terminal-confirmed' }, () => resolve()),
+		)
+	process.exit(code)
+}
+
+async function requireRetirement(): Promise<never> {
+	let confirmed = disconnected
+		? false
+		: await new Promise<boolean>((resolve) => {
+				retirement = resolve
+				process.send?.({ type: 'retire-computer' }, (error) => {
+					if (error) resolve(false)
+				})
+			})
+	while (!confirmed && !disconnected) {
+		process.stderr.write(
+			'\n[Guest cancellation could not be confirmed; the computer requires operator recovery.]\n',
+		)
+		// Keep the bridge and ownership alive. The provider's next termination
+		// attempt retries retirement, never the command or its guest signals.
+		confirmed = await new Promise<boolean>((resolve) => {
+			retirement = resolve
+		})
+	}
+	return await finish(1, confirmed)
+}
+
+async function execute(config: DetachedWorkerConfiguration): Promise<void> {
+	try {
+		const result = await new HttpWorkerClient(config.executionUrl, config.token).exec(
+			config.command,
+			config.args,
+			{
+				timeout: LOCAL_BACKGROUND_TIMEOUT_MS,
+				cwd: config.cwd,
+				env: config.env,
+				signal: controller.signal,
+				onOutput: (chunk) =>
+					(chunk.stream === 'stdout' ? process.stdout : process.stderr).write(chunk.data),
+			},
+		)
+		if (result.stdoutTruncated || result.stderrTruncated)
+			process.stderr.write(
+				'\n[Guest worker output exceeded its capture cap; the omitted bytes are unavailable.]\n',
+			)
+		if (result.timedOut)
+			process.stderr.write('\n[Guest background command reached its maximum lifetime.]\n')
+		await finish(result.exitCode)
+	} catch (error) {
+		if (error instanceof RemoteCancellationUnknownError) {
+			// Closing a host pipe cannot prove a guest tree stopped. Ask the
+			// owning provider to retire the actual computer before exiting.
+			await requireRetirement()
+		}
+		if (controller.signal.aborted) await finish(128 + (cancellation === 'SIGINT' ? 2 : 15))
+		process.stderr.write('\n[Guest background command could not be completed.]\n')
+		// A transport failure may happen after admission. Retire the computer
+		// rather than report a host bridge failure as a guest process exit.
+		await requireRetirement()
+	}
+}
+
+process.on('message', (raw: unknown) => {
+	if (!raw || typeof raw !== 'object' || !('type' in raw)) return
+	const message = raw as {
+		type: string
+		signal?: NodeJS.Signals
+		confirmed?: boolean
+	}
+	if (message.type === 'cancel') {
+		cancel(message.signal)
+		return
+	}
+	if (message.type === 'retired') {
+		retirement?.(message.confirmed === true)
+		return
+	}
+	if (message.type !== 'start' || started) return
+	started = true
+	void execute(raw as DetachedWorkerConfiguration)
+})

package/src/local-virtual-computer/dialect.ts

@@ -0,0 +1,83 @@
+import type { EngineDialect, LocalEngine } from './engine.js'
+
+/**
+ * The engines speak nearly the same command line. Every place they differ is
+ * here, so the lifecycle in index.ts reads the same for all of them.
+ */
+
+export type PublishedPorts = Record<string, { HostIp?: string; HostPort?: string }[]>
+
+/** Podman machines on WSL can lack delegated cgroup controllers. */
+export function resourceFlags(dialect: EngineDialect): string[] {
+	return dialect === 'podman' ? ['--cgroups=disabled'] : []
+}
+
+/**
+ * The container boundary. wslc has no flag for any of these; its boundary is
+ * the per-user virtual machine, the unprivileged guest user and the image.
+ */
+export function hardeningFlags(dialect: EngineDialect): string[] {
+	if (dialect === 'wslc') return []
+	return ['--cap-drop=ALL', '--security-opt=no-new-privileges', '--read-only', '--ipc=private']
+}
+
+/** Command line that prints full container ids, one per line, for a filter. */
+export function containerIdQuery(
+	dialect: EngineDialect,
+	filter: string,
+	options: { readonly full: boolean },
+): string[] {
+	// wslc has no Go templates and truncates -q ids to 12 characters.
+	if (dialect === 'wslc') return ['ps', '-a', '--filter', filter, '-q', '--no-trunc']
+	return [
+		'ps',
+		'--all',
+		'--filter',
+		filter,
+		...(options.full ? ['--no-trunc'] : []),
+		'--format',
+		'{{.ID}}',
+	]
+}
+
+export function portsQuery(dialect: EngineDialect, name: string): string[] {
+	if (dialect === 'wslc') return ['inspect', '-f', 'json', name]
+	return ['inspect', '--format', '{{json .NetworkSettings.Ports}}', name]
+}
+
+/** Read published ports from what `portsQuery` printed. */
+export function parsePublishedPorts(dialect: EngineDialect, output: string): PublishedPorts {
+	const parsed: unknown = JSON.parse(output)
+	if (dialect !== 'wslc') return parsed as PublishedPorts
+	const first = (Array.isArray(parsed) ? parsed[0] : undefined) as
+		| { Ports?: PublishedPorts; NetworkSettings?: { Ports?: PublishedPorts } }
+		| undefined
+	return first?.Ports ?? first?.NetworkSettings?.Ports ?? {}
+}
+
+/** Make sure the labelled volume exists, creating it only when absent. */
+export async function ensureVolume(
+	engine: LocalEngine,
+	dialect: EngineDialect,
+	volume: string,
+	label: string,
+	signal?: AbortSignal,
+): Promise<void> {
+	if (dialect !== 'wslc') {
+		await engine.run(
+			['volume', 'create', ...(dialect === 'podman' ? ['--ignore'] : []), '--label', label, volume],
+			{ signal },
+		)
+		return
+	}
+	// wslc has no --ignore. A missing volume is either a failed command or an
+	// empty list, depending on how the output was captured.
+	let present = false
+	try {
+		const found: unknown = JSON.parse(await engine.run(['volume', 'inspect', volume], { signal }))
+		present = Array.isArray(found) && found.length > 0
+	} catch {
+		signal?.throwIfAborted()
+	}
+	if (!present) await engine.run(['volume', 'create', '--label', label, volume], { signal })
+}

package/src/local-virtual-computer/engine.ts

@@ -0,0 +1,197 @@
+import { spawn } from 'node:child_process'
+
+/** Stable reasons a caller can branch on without parsing prose. */
+export type LocalComputerSetupCode =
+	| 'engine-missing'
+	| 'engine-too-old'
+	| 'virtualization-off'
+	| 'blocked-by-policy'
+	| 'image-missing'
+	| 'sdk-mismatch'
+
+/** Safe operator-facing diagnosis, without daemon output or credentials. */
+export class LocalComputerSetupError extends Error {
+	override readonly name = 'LocalComputerSetupError'
+	readonly code?: LocalComputerSetupCode
+	constructor(message: string, code?: LocalComputerSetupCode, options?: { cause?: unknown }) {
+		super(message, options)
+		this.code = code
+	}
+}
+
+/**
+ * A failed engine command. The message never carries engine output; only
+ * recognised machine-readable codes (HRESULTs, WSLC_E_* names, spawn errno
+ * names) survive, so a typed diagnosis can be made without leaking text.
+ */
+export class LocalCommandError extends Error {
+	override readonly name = 'LocalCommandError'
+	readonly errorCodes: readonly string[]
+	/** The process exit status, when the command ran and failed. */
+	readonly exitCode?: number
+	constructor(message: string, errorCodes: readonly string[] = [], exitCode?: number) {
+		super(message)
+		this.errorCodes = errorCodes
+		if (exitCode !== undefined) this.exitCode = exitCode
+	}
+}
+
+const ERROR_CODE_PATTERN = /WSLC_E_[A-Z0-9_]+|HCS_E_[A-Z0-9_]+|0x[0-9A-Fa-f]{8}/g
+
+/** Extract the codes worth keeping from a command's stderr. */
+export function extractErrorCodes(text: string): string[] {
+	const found = new Set<string>()
+	for (const match of text.match(ERROR_CODE_PATTERN) ?? []) {
+		found.add(match.startsWith('0x') ? `0x${match.slice(2).toUpperCase()}` : match)
+	}
+	return [...found]
+}
+
+/** Which command-line dialect an engine speaks. */
+export type EngineDialect = 'docker' | 'podman' | 'wslc'
+
+/** A host-controlled transport. Never pass this or its environment to an agent. */
+export interface LocalComputerCommandRunner {
+	run(
+		binary: string,
+		args: readonly string[],
+		options?: {
+			readonly signal?: AbortSignal
+			readonly env?: NodeJS.ProcessEnv
+			readonly cwd?: string
+		},
+	): Promise<string>
+}
+
+export const nodeCommandRunner: LocalComputerCommandRunner = {
+	run(binary, args, options) {
+		options?.signal?.throwIfAborted()
+		return new Promise((resolve, reject) => {
+			const child = spawn(binary, [...args], {
+				env: options?.env ?? process.env,
+				cwd: options?.cwd,
+				signal: options?.signal,
+				windowsHide: true,
+				stdio: ['ignore', 'pipe', 'pipe'],
+			})
+			const output: Buffer[] = []
+			const diagnostics: Buffer[] = []
+			let diagnosticBytes = 0
+			let outputBytes = 0
+			let failed = false
+			child.stdout.on('data', (chunk: Buffer) => {
+				output.push(chunk)
+				outputBytes += chunk.byteLength
+				if (outputBytes > 1024 * 1024) {
+					failed = true
+					child.kill()
+				}
+			})
+			// Docker's error text can echo worker configuration. Preserve the exit
+			// code, never stdout/stderr or the environment in a failure message.
+			child.stderr.on('data', (chunk: Buffer) => {
+				if (diagnosticBytes >= 64 * 1024) return
+				diagnostics.push(chunk)
+				diagnosticBytes += chunk.byteLength
+			})
+			child.once('error', (error: NodeJS.ErrnoException) =>
+				reject(
+					new LocalCommandError(
+						'The local container engine could not be started',
+						error.code ? [error.code] : [],
+					),
+				),
+			)
+			child.once('close', (code) => {
+				if (failed) reject(new Error('The local container engine response exceeded its size limit'))
+				else if (code !== 0)
+					reject(
+						new LocalCommandError(
+							`The local container engine command failed (${code})`,
+							extractErrorCodes(Buffer.concat(diagnostics).toString('utf8')),
+							code ?? undefined,
+						),
+					)
+				else {
+					const bytes = Buffer.concat(output)
+					// Native wsl.exe emits UTF-16LE through a redirected pipe.
+					const utf16 = bytes[1] === 0 || (bytes[0] === 0xff && bytes[1] === 0xfe)
+					resolve(bytes.toString(utf16 ? 'utf16le' : 'utf8').replace(/^\uFEFF/, ''))
+				}
+			})
+		})
+	},
+}
+
+/** TCP, SSH and remote named pipes cannot establish a local-device boundary. */
+export function assertLocalEngineEndpoint(endpoint: string): void {
+	if (/^unix:\/\/\/[\S]+$/.test(endpoint)) return
+	if (/^npipe:\/\/\/\/\.\/pipe\/[a-zA-Z0-9_.-]+$/.test(endpoint)) return
+	throw new LocalComputerSetupError(
+		'Pals require a local Docker Unix socket or Windows named pipe; remote engines are refused',
+	)
+}
+
+export interface LocalEngineOptions {
+	readonly dockerBinary?: string
+	readonly engineEndpoint?: string
+	readonly runner?: LocalComputerCommandRunner
+}
+
+export interface LocalEngine {
+	readonly endpoint: string
+	/** Command-line dialect. Absent means the engine was selected as Docker. */
+	readonly dialect?: EngineDialect
+	forwardPorts?(
+		ports: readonly number[],
+		options: { readonly signal?: AbortSignal; readonly onLost: () => void },
+	): Promise<LocalPortForward>
+	run(
+		args: readonly string[],
+		options?: { readonly signal?: AbortSignal; readonly env?: NodeJS.ProcessEnv },
+	): Promise<string>
+}
+
+export interface LocalPortForward {
+	readonly ports: readonly number[]
+	assertAlive(): void
+	close(): Promise<void>
+}
+
+/** Resolve once, then pin every operation to the verified endpoint. */
+export async function resolveLocalEngine(
+	options: LocalEngineOptions,
+	signal?: AbortSignal,
+): Promise<LocalEngine> {
+	const binary = options.dockerBinary ?? 'docker'
+	const runner = options.runner ?? nodeCommandRunner
+	let endpoint = options.engineEndpoint
+	if (endpoint === undefined) {
+		const current = (await runner.run(binary, ['context', 'show'], { signal })).trim()
+		if (!current)
+			throw new LocalComputerSetupError('The current Docker context could not be determined')
+		const contexts = JSON.parse(
+			await runner.run(binary, ['context', 'inspect', current], { signal }),
+		) as { Endpoints?: { docker?: { Host?: string } } }[]
+		endpoint = contexts[0]?.Endpoints?.docker?.Host
+		// DOCKER_HOST overrides a context in normal Docker invocations. Honor
+		// its actual destination and validate it rather than checking one
+		// endpoint while accidentally provisioning on another.
+		if (!process.env.DOCKER_CONTEXT && process.env.DOCKER_HOST) endpoint = process.env.DOCKER_HOST
+	}
+	if (!endpoint) throw new LocalComputerSetupError('Docker did not provide a local engine endpoint')
+	assertLocalEngineEndpoint(endpoint)
+	const host = endpoint
+	const run: LocalEngine['run'] = (args, call) => {
+		const env = { ...process.env, ...call?.env }
+		env.DOCKER_CONTEXT = undefined
+		env.DOCKER_HOST = undefined
+		return runner.run(binary, ['--host', host, ...args], { ...call, env })
+	}
+	const info = JSON.parse(await run(['info', '--format', '{{json .}}'], { signal })) as {
+		OSType?: string
+	}
+	if (info.OSType !== 'linux')
+		throw new LocalComputerSetupError('The local Docker engine must run Linux containers')
+	return { endpoint: host, run }
+}