@namzu/sandbox 6.1.0 → 7.1.0

package/src/backends/http-worker-client.ts

@@ -0,0 +1,230 @@
+import { type SandboxExecOptions, type SandboxExecResult, withHint } from '@namzu/sdk'
+
+import {
+	RemoteCancellationUnsupportedError,
+	RemoteCommandError,
+	type RemoteExecutionAdapter,
+	RemoteExecutionController,
+	RemoteProtocolError,
+} from './remote-execution-controller.js'
+
+type WorkerEvent =
+	| { readonly type: 'stdout_delta'; readonly data: string }
+	| { readonly type: 'stderr_delta'; readonly data: string }
+	| {
+			readonly type: 'result'
+			readonly exitCode: number
+			readonly timedOut: boolean
+			readonly durationMs: number
+			readonly signal?: string
+			readonly stdoutTruncated?: boolean
+			readonly stderrTruncated?: boolean
+	  }
+	| { readonly type: 'error'; readonly error: string }
+
+function parseWorkerEvent(line: string): WorkerEvent {
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(line)
+	} catch (error) {
+		throw new RemoteProtocolError(
+			`worker emitted malformed NDJSON: ${error instanceof Error ? error.message : String(error)}`,
+		)
+	}
+	if (!parsed || typeof parsed !== 'object') {
+		throw new RemoteProtocolError('worker emitted an event without an object body')
+	}
+	const event = parsed as Record<string, unknown>
+	if (
+		(event.type === 'stdout_delta' || event.type === 'stderr_delta') &&
+		typeof event.data === 'string'
+	) {
+		return event as WorkerEvent
+	}
+	if (event.type === 'error' && typeof event.error === 'string') return event as WorkerEvent
+	if (
+		event.type === 'result' &&
+		Number.isFinite(event.exitCode) &&
+		typeof event.timedOut === 'boolean' &&
+		Number.isFinite(event.durationMs) &&
+		(event.signal === undefined || typeof event.signal === 'string') &&
+		(event.stdoutTruncated === undefined || typeof event.stdoutTruncated === 'boolean') &&
+		(event.stderrTruncated === undefined || typeof event.stderrTruncated === 'boolean')
+	) {
+		return event as WorkerEvent
+	}
+	throw new RemoteProtocolError(`worker emitted an invalid ${String(event.type)} event`)
+}
+
+async function readExecution(
+	baseUrl: string,
+	executionId: string | undefined,
+	command: string,
+	argv: string[] | undefined,
+	opts: SandboxExecOptions | undefined,
+	transportSignal: AbortSignal,
+): Promise<SandboxExecResult> {
+	let response: Response
+	try {
+		response = await fetch(`${baseUrl}/execute`, {
+			method: 'POST',
+			headers: { 'content-type': 'application/json' },
+			signal: transportSignal,
+			body: JSON.stringify({
+				...(executionId ? { executionId } : {}),
+				command,
+				args: argv ?? [],
+				cwd: opts?.cwd,
+				env: opts?.env,
+				timeoutMs: opts?.timeout,
+			}),
+		})
+	} catch (error) {
+		const cause = error instanceof Error ? error.cause : undefined
+		const causeMessage =
+			cause instanceof Error
+				? `${cause.message}${(cause as Error & { code?: string }).code ? ` (${(cause as Error & { code?: string }).code})` : ''}`
+				: cause
+					? String(cause)
+					: 'unknown'
+		throw withHint(
+			new Error(
+				`namzu-sandbox /execute fetch failed (baseUrl=${baseUrl}): ${error instanceof Error ? error.message : String(error)} — cause: ${causeMessage}`,
+				{ cause: error },
+			),
+			'The worker was reachable when the sandbox started, so it has most likely exited, been killed, or become unreachable since. Check the container logs and runtime exit state.',
+		)
+	}
+	if (!response.ok || !response.body) {
+		throw new Error(`execute failed: HTTP ${response.status} ${await response.text()}`)
+	}
+
+	const decoder = new TextDecoder()
+	const reader = response.body.getReader()
+	let buffered = ''
+	let stdout = ''
+	let stderr = ''
+	let terminal: Extract<WorkerEvent, { type: 'result' }> | undefined
+	let terminalCount = 0
+
+	const consume = (rawLine: string): void => {
+		if (!rawLine.trim()) return
+		const event = parseWorkerEvent(rawLine)
+		if (terminalCount > 0) {
+			throw new RemoteProtocolError('worker emitted data after its terminal event')
+		}
+		if (event.type === 'stdout_delta') {
+			stdout += event.data
+			opts?.onOutput?.({ stream: 'stdout', data: event.data })
+			return
+		}
+		if (event.type === 'stderr_delta') {
+			stderr += event.data
+			opts?.onOutput?.({ stream: 'stderr', data: event.data })
+			return
+		}
+		terminalCount += 1
+		if (event.type === 'error') throw new RemoteCommandError(event.error)
+		terminal = event
+	}
+
+	for (;;) {
+		const { value, done } = await reader.read()
+		if (done) break
+		buffered += decoder.decode(value, { stream: true })
+		let newline = buffered.indexOf('\n')
+		while (newline !== -1) {
+			consume(buffered.slice(0, newline))
+			buffered = buffered.slice(newline + 1)
+			newline = buffered.indexOf('\n')
+		}
+	}
+	buffered += decoder.decode()
+	if (buffered.trim()) consume(buffered)
+	if (terminalCount !== 1 || !terminal) {
+		throw new RemoteProtocolError('worker response ended without exactly one result event')
+	}
+
+	return {
+		exitCode: terminal.exitCode,
+		stdout,
+		stderr,
+		...(terminal.signal ? { signal: terminal.signal } : {}),
+		timedOut: terminal.timedOut,
+		durationMs: terminal.durationMs,
+		...(terminal.stdoutTruncated !== undefined
+			? { stdoutTruncated: terminal.stdoutTruncated }
+			: {}),
+		...(terminal.stderrTruncated !== undefined
+			? { stderrTruncated: terminal.stderrTruncated }
+			: {}),
+	}
+}
+
+/**
+ * A per-sandbox HTTP worker client. The controller caches protocol support for
+ * that worker and gives every v2 command an identity before it can be admitted.
+ */
+export class HttpWorkerClient {
+	private readonly controller: RemoteExecutionController
+
+	constructor(baseUrl: string) {
+		const adapter: RemoteExecutionAdapter = {
+			label: 'HTTP worker',
+			reserve: async (signal) => {
+				const response = await fetch(`${baseUrl}/executions/reserve`, {
+					method: 'POST',
+					signal,
+				})
+				if (response.status === 404) {
+					throw new RemoteCancellationUnsupportedError(
+						'This sandbox worker does not support the execution-cancellation lease protocol. Rebuild the worker image or standby-pool profile before passing SandboxExecOptions.signal; refusing rather than pretending cancellation is active.',
+					)
+				}
+				if (!response.ok) {
+					throw new Error(
+						`execution reservation failed: HTTP ${response.status} ${await response.text()}`,
+					)
+				}
+				return await response.json()
+			},
+			cancel: async (executionId, signal) => {
+				const response = await fetch(`${baseUrl}/cancel`, {
+					method: 'POST',
+					headers: { 'content-type': 'application/json' },
+					body: JSON.stringify({ executionId }),
+					signal,
+				})
+				if (!response.ok) {
+					throw new Error(`cancel failed: HTTP ${response.status} ${await response.text()}`)
+				}
+				return await response.json()
+			},
+			execute: async (executionId, command, argv, opts, signal) =>
+				await readExecution(baseUrl, executionId, command, argv, opts, signal),
+		}
+		this.controller = new RemoteExecutionController(adapter)
+	}
+
+	async exec(
+		command: string,
+		argv: string[] | undefined,
+		opts: SandboxExecOptions | undefined,
+	): Promise<SandboxExecResult> {
+		return await this.controller.exec(command, argv, opts)
+	}
+}
+
+/**
+ * Compatibility entry point for focused consumers. Sandbox backends keep one
+ * {@link HttpWorkerClient} per remote sandbox so capability state is not shared
+ * across peers and is not re-probed for every command.
+ */
+export async function execViaHttpWorker(
+	baseUrl: string,
+	command: string,
+	argv: string[] | undefined,
+	opts: SandboxExecOptions | undefined,
+): Promise<SandboxExecResult> {
+	return await new HttpWorkerClient(baseUrl).exec(command, argv, opts)
+}

package/src/backends/readiness.ts

@@ -0,0 +1,173 @@
+/**
+ * One owner for backend readiness clocks.
+ *
+ * A timestamp checked between retries is not a deadline when the thing inside
+ * a retry can remain pending. This owner races every foreign promise against
+ * the remaining operation budget and supplies a private signal so cooperative
+ * transports can release their sockets too.
+ */
+
+const MAX_NODE_TIMER_MS = 2_147_483_647
+
+/**
+ * Readiness failure teardown is deliberately a second, short budget. The
+ * health deadline has already expired, so pretending cleanup fits inside it
+ * either skips cleanup entirely or keeps `create()` pending without a bound.
+ */
+export const FAILURE_CLEANUP_GRACE_MS = 1_000
+
+export interface ReadinessOptions {
+	readonly timeoutMs: number
+	readonly pollIntervalMs: number
+}
+
+export class OperationDeadlineExpired extends Error {
+	constructor(readonly label: string) {
+		super(`${label} deadline expired`)
+		this.name = 'OperationDeadlineExpired'
+	}
+}
+
+function assertTimerValue(field: string, value: number): void {
+	if (!Number.isSafeInteger(value) || value <= 0 || value > MAX_NODE_TIMER_MS) {
+		throw new RangeError(
+			`${field} must be a positive safe integer no greater than ${MAX_NODE_TIMER_MS}; received ${String(value)}`,
+		)
+	}
+}
+
+export function resolveReadinessOptions(
+	owner: string,
+	timeoutMs: number | undefined,
+	pollIntervalMs: number | undefined,
+	defaults: ReadinessOptions,
+): ReadinessOptions {
+	const resolved = {
+		timeoutMs: timeoutMs ?? defaults.timeoutMs,
+		pollIntervalMs: pollIntervalMs ?? defaults.pollIntervalMs,
+	}
+	assertTimerValue(`${owner}.readyTimeoutMs`, resolved.timeoutMs)
+	assertTimerValue(`${owner}.readyPollIntervalMs`, resolved.pollIntervalMs)
+	return resolved
+}
+
+export class OperationDeadline {
+	private readonly expiresAt: number
+
+	constructor(
+		timeoutMs: number,
+		readonly label: string,
+		private readonly callerSignal?: AbortSignal,
+	) {
+		assertTimerValue(`${label} timeout`, timeoutMs)
+		this.expiresAt = performance.now() + timeoutMs
+	}
+
+	remainingMs(): number {
+		return Math.max(0, this.expiresAt - performance.now())
+	}
+
+	async run<T>(operation: (signal: AbortSignal) => Promise<T>): Promise<T> {
+		this.callerSignal?.throwIfAborted()
+		const remaining = this.remainingMs()
+		if (remaining <= 0) throw new OperationDeadlineExpired(this.label)
+
+		const controller = new AbortController()
+		const expired = new OperationDeadlineExpired(this.label)
+		let timer: ReturnType<typeof setTimeout> | undefined
+		let onCallerAbort: (() => void) | undefined
+		const cancelled = this.callerSignal
+			? new Promise<never>((_resolve, reject) => {
+					onCallerAbort = () => {
+						const reason = this.callerSignal?.reason
+						controller.abort(reason)
+						reject(reason)
+					}
+					this.callerSignal?.addEventListener('abort', onCallerAbort, {
+						once: true,
+					})
+				})
+			: undefined
+		const expiry = new Promise<never>((_resolve, reject) => {
+			timer = setTimeout(() => {
+				controller.abort(expired)
+				reject(expired)
+			}, remaining)
+		})
+		const pending = Promise.resolve().then(() => operation(controller.signal))
+
+		try {
+			const value = await Promise.race(cancelled ? [pending, expiry, cancelled] : [pending, expiry])
+			// Publication fence: a foreign promise that settles at the boundary
+			// does not get to turn an already-expired attempt into readiness.
+			if (this.callerSignal?.aborted) throw this.callerSignal.reason
+			if (controller.signal.aborted || this.remainingMs() <= 0) {
+				controller.abort(expired)
+				throw expired
+			}
+			return value
+		} finally {
+			if (timer !== undefined) clearTimeout(timer)
+			if (onCallerAbort) this.callerSignal?.removeEventListener('abort', onCallerAbort)
+		}
+	}
+
+	async delay(maximumMs: number): Promise<void> {
+		await this.run(
+			(signal) =>
+				new Promise<void>((resolve, reject) => {
+					if (signal.aborted) {
+						reject(signal.reason)
+						return
+					}
+					const finish = (err?: unknown) => {
+						clearTimeout(timer)
+						signal.removeEventListener('abort', abort)
+						if (err === undefined) resolve()
+						else reject(err)
+					}
+					const abort = () => {
+						finish(signal.reason)
+					}
+					const timer = setTimeout(() => finish(), maximumMs)
+					signal.addEventListener('abort', abort, { once: true })
+				}),
+		)
+	}
+}
+
+export async function probeHttpHealth(
+	url: string,
+	signal: AbortSignal,
+): Promise<{ readonly ok: boolean; readonly status: number }> {
+	signal.throwIfAborted()
+	const response = await fetch(url, { signal })
+	const result = { ok: response.ok, status: response.status }
+	try {
+		await response.body?.cancel()
+	} catch {
+		// The status is already known. A body cancellation failure must not
+		// hide it; the owning deadline still aborts the transport if needed.
+	}
+	signal.throwIfAborted()
+	return result
+}
+
+/**
+ * Failure cleanup must never replace or indefinitely delay the primary
+ * readiness error. Cooperative cleanup observes the signal; an implementation
+ * that ignores it is still detached from the caller by the independent race.
+ */
+export async function runFailureCleanup(
+	cleanup: (signal: AbortSignal) => Promise<void>,
+	graceMs = FAILURE_CLEANUP_GRACE_MS,
+): Promise<void> {
+	const deadline = new OperationDeadline(graceMs, 'sandbox failure cleanup')
+	try {
+		await deadline.run(cleanup)
+	} catch {
+		// The readiness failure remains primary. Promise.race installed a
+		// rejection observer on the losing cleanup promise, so a late failure
+		// cannot become an unhandled rejection.
+	}
+}