// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. // SPDX-License-Identifier: Apache-2.0 // The OpenShell gateway client: a thin, idiomatic ergonomics layer over the // protobuf-generated gRPC stubs (src/gen/). Resource operations live on scoped // clients (`SandboxClient`, mirroring the Python SDK) that OpenShellClient // composes as `client.sandbox.*`, mirroring the CLI's noun-verb model; each // scoped client is also usable standalone via its own `connect()`. Gateway- // scoped calls (`health`) stay top-level. A scoped client owns proto request // assembly, the curated public types, the ExecSandbox server-stream drain, and // the waitReady/waitDeleted poll loops. Transport and auth live in // transport.ts; the error taxonomy in errors.ts. import type { AddressInfo } from 'node:net'; import * as net from 'node:net'; import type { MessageInitShape } from '@bufbuild/protobuf'; import { durationFromMs } from '@bufbuild/protobuf/wkt'; import { type CallOptions, type Client, Code, createClient, type Transport } from '@connectrpc/connect'; import { errorCode, fromConnect, SdkError } from './errors.js'; import type { Provider, WorkspaceSelectorSchema } from './gen/datamodel_pb.js'; import type { Sandbox, SandboxLogLine, SandboxStreamEvent, SandboxWorkloadTemplate, UpdateConfigResponse, PlatformEvent as WirePlatformEvent, } from './gen/openshell_pb.js'; import { type ExecSandboxInputSchema, OpenShell, ServiceAuthorizationMode as ProtoServiceAuthorizationMode, SandboxPhase, SandboxRestartPolicy, type SandboxSpecSchema, type SandboxWorkloadTemplateSchema, ServiceStatus, type TcpForwardFrameSchema, } from './gen/openshell_pb.js'; import type { EffectiveSetting, GetSandboxConfigResponse, SandboxPolicy, SettingValue } from './gen/sandbox_pb.js'; import { PolicySource, type SandboxPolicySchema, SettingScope, type SettingValueSchema } from './gen/sandbox_pb.js'; import { ProviderClient } from './providers.js'; import { heldUntilReady, OWNER_REPLICA_HEADER, OWNER_REQUEST_HEADER, routedStream } from './routing.js'; import { validateSshResponse } from './ssh-validate.js'; import { buildTransport, type ConnectOptions } from './transport.js'; function durationFromSeconds(seconds: number) { if (!Number.isFinite(seconds) || seconds < 0) { throw new RangeError('timeoutSecs must be a finite, non-negative number'); } return seconds === 0 ? undefined : durationFromMs(seconds * 1000); } // Distinct from timestampMillis(): LogLine/PlatformEvent timestamps are // always-present numbers that default to 0 when absent or unrepresentable, // not an optional string field like expiresAtMs. function eventTimeMillis(timestamp: { seconds: bigint; nanos: number } | undefined): number { if (!timestamp) return 0; return Number(timestamp.seconds * 1000n + BigInt(Math.trunc(timestamp.nanos / 1_000_000))); } function timestampMillis(timestamp: { seconds: bigint; nanos: number } | undefined): string | undefined { if (!timestamp) return undefined; const millis = timestamp.seconds * 1000n + BigInt(Math.trunc(timestamp.nanos / 1_000_000)); return millis === 0n ? undefined : millis.toString(); } function timestampEpochMs(timestamp: { seconds: bigint; nanos: number } | undefined): number | undefined { const millis = timestampMillis(timestamp); return millis ? Number(millis) : undefined; } // Generated protobuf message shapes that callers need to populate or round-trip // directly. Re-export these rather than re-curating parallel surfaces. export type { SandboxResources, SandboxServiceLevel, SandboxStartup, SandboxWorkloadConfig, SandboxWorkloadTemplate, SandboxWorkloadTemplateSpec, } from './gen/openshell_pb.js'; export type { SandboxPolicy, SettingValue } from './gen/sandbox_pb.js'; export type { ConnectOptions }; export { errorCode }; // ---- Curated public types -------------------------------------------------- // The gateway enums (SandboxPhase, ServiceStatus, SettingScope, PolicySource) // arrive as protoc-gen-es numeric enums. The lowercase literal unions below are // a hand-maintained mirror of them so consumers get exhaustive, typo-proof // switches instead of a bare `string`. They are deliberately duplicated by // hand, not generated, and are expected to stay stable. If a proto enum ever // gains, removes, or renames a member, update the matching union AND its // `*_NAMES` map below: the exhaustive `Record` stops compiling, and the // 'enum name maps' drift test in client.test.ts fails until both sides agree. /** Lowercase mirror of the generated `SandboxPhase` enum. Hand-maintained. */ export type SandboxPhaseName = | 'unspecified' | 'provisioning' | 'ready' | 'error' | 'deleting' | 'unknown' | 'stopping' | 'stopped' | 'starting' | 'completed' | 'suspending' | 'suspended'; /** Restart behavior after the canonical main process exits. */ export type SandboxRestartPolicyName = 'never' | 'on-failure' | 'always'; /** Lowercase mirror of the generated `ServiceStatus` enum. Hand-maintained. */ export type HealthStatus = 'unspecified' | 'healthy' | 'degraded' | 'unhealthy'; /** Lowercase mirror of the generated `SettingScope` enum. Hand-maintained. */ export type SettingScopeName = 'unspecified' | 'sandbox' | 'global'; /** Lowercase mirror of the generated `PolicySource` enum. Hand-maintained. */ export type PolicySourceName = 'unspecified' | 'sandbox' | 'global'; export interface Health { status: HealthStatus; version: string; } export type DeletionOutcome = 'unspecified' | 'completed' | 'accepted' | 'already_absent' | 'unknown'; export interface DeletionResult { outcome: DeletionOutcome; /** Original enum number, including values introduced by a newer gateway. */ rawOutcome: number; /** Original sandbox UUID; absent if no target existed or this is not a sandbox deletion. */ sandboxId?: string; } export interface DeleteOptions extends SandboxWorkspaceOptions { allowMissing?: boolean; } function deletionResult(response: { outcome: number; sandboxId?: string }): DeletionResult { const names: Record = { 0: 'unspecified', 1: 'completed', 2: 'accepted', 3: 'already_absent', }; return { outcome: names[response.outcome] ?? 'unknown', rawOutcome: response.outcome, ...(response.sandboxId ? { sandboxId: response.sandboxId } : {}), }; } export interface SandboxSpec { name?: string; /** Workspace name. Omit for `default`; empty strings are invalid. */ workspace?: string; image?: string; labels?: Record; environment?: Record; providers?: string[]; gpu?: boolean; /** Exact canonical command. Empty selects the gateway scratch shell. */ command?: string[]; /** Allocate a retained pseudo-terminal for the canonical command. */ tty?: boolean; /** Loopback HTTP services to expose when the sandbox is created. */ serviceExposures?: ServiceExposure[]; /** Restart behavior after the canonical main process exits. */ restartPolicy?: SandboxRestartPolicyName; /** * Create-time sandbox policy (the safety boundary). Sandbox-scoped * `setPolicy` cannot introduce static fields later, so express filesystem, * landlock, process, and initial network policy here. */ policy?: MessageInitShape; /** * Advanced escape hatch: the full generated proto spec. Curated fields build * the base spec, then `rawSpec` shallow-overrides at the top spec level, so * any field it sets wins. Use it to reach proto spec fields the curated shape * does not surface (template runtime class, resource limits, log level, and * future additions) without an SDK change. */ rawSpec?: MessageInitShape; } export interface ServiceExposure { /** Service name. Empty or omitted selects the unnamed endpoint. */ service?: string; /** Loopback TCP port inside the sandbox. */ targetPort: number; /** Handling for an incoming application Authorization header. */ authorizationMode?: ServiceAuthorizationMode; } export enum ServiceAuthorizationMode { Strip = 'strip', BearerPassthrough = 'bearer_passthrough', } function serviceAuthorizationModeToProto(mode: ServiceAuthorizationMode | undefined): ProtoServiceAuthorizationMode { switch (mode) { case ServiceAuthorizationMode.BearerPassthrough: return ProtoServiceAuthorizationMode.BEARER_PASSTHROUGH; case ServiceAuthorizationMode.Strip: case undefined: return ProtoServiceAuthorizationMode.STRIP; } } export interface SandboxFromTemplateSpec { name?: string; /** Workspace name. Omit for `default`; empty strings are invalid. */ workspace?: string; workloadTemplate: string; labels?: Record; providers?: string[]; /** Exact canonical command. Empty selects the gateway scratch shell. */ command?: string[]; /** Allocate a retained pseudo-terminal for the canonical command. */ tty?: boolean; /** Loopback HTTP services to expose when the sandbox is created. */ serviceExposures?: ServiceExposure[]; /** * Create-time sandbox policy (the safety boundary). The named workload * template supplies runtime workload fields. */ policy?: MessageInitShape; } export interface SandboxRef { id: string; name: string; workspace: string; phase: SandboxPhaseName; labels: Record; /** u64 rendered as a string — JS numbers can't hold it safely. */ resourceVersion: string; /** Stable SSH host identity; absent on older runtimes. */ hostKeyFingerprint?: string; mainProcessInstanceId?: string; exitCode?: number; createdFromWorkloadTemplate?: SandboxWorkloadTemplateProvenance; /** Service URLs returned by creation, keyed by service name. */ serviceUrls: Record; restartCount: number; /** Creation time in epoch milliseconds; absent when the gateway omits it. */ createdAtMs?: number; nextRestartAtMs?: number; mainProcessStartedAtMs?: number; } export interface SandboxWorkloadTemplateProvenance { name: string; resourceVersion: string; } interface PaginationOptions { /** Maximum resources requested per page. */ pageSize?: number; /** Opaque token from a previous page. Omit to start at the beginning. */ pageToken?: string; labelSelector?: string; } /** Mutually exclusive named/default or all-workspaces list scope. */ export type WorkspaceListScope = | { workspace?: string; allWorkspaces?: false | undefined } | { workspace?: never; allWorkspaces: true }; export type ListOptions = PaginationOptions & WorkspaceListScope; export interface SandboxWorkspaceOptions { /** Workspace name. Omit for `default`; empty strings are invalid. */ workspace?: string; } /** Pagination and workspace scope for providers attached to one sandbox. */ export type SandboxProviderListOptions = SandboxWorkspaceOptions & { /** Maximum providers requested per page. */ pageSize?: number; /** Opaque token from a previous page. Omit to start at the beginning. */ pageToken?: string; }; export type SandboxCallOptions = CallOptions & SandboxWorkspaceOptions; export interface SandboxTemplateWorkspaceOptions { /** Workspace name. Omit for `default`; empty strings are invalid. */ workspace?: string; } export type SandboxTemplateListOptions = WorkspaceListScope & { /** Maximum templates requested per page. */ pageSize?: number; /** Opaque token from a previous page. Omit to start at the beginning. */ pageToken?: string; /** Optional label selector in key=value comma-separated form. */ labelSelector?: string; }; export interface ExecOptions extends SandboxWorkspaceOptions { workdir?: string; environment?: Record; timeoutSecs?: number; stdin?: Buffer; /** * Skip sourcing shell login/profile startup files before the command. * Defaults to `false`, which preserves login-shell behavior. Set `true` for * automation and managed checks that need predictable startup behavior. */ noLoginShell?: boolean; /** Abort the exec (and the in-flight stream RPC) early. */ signal?: AbortSignal; } export interface ExecResult { exitCode: number; stdout: Buffer; stderr: Buffer; } /** One stdout/stderr chunk yielded by `execStream`/`execInteractive`. */ export interface ExecStreamChunk { stream: 'stdout' | 'stderr'; data: Buffer; } // The terminal event of an exec stream, carrying the command exit code. It is // yielded in-band (not returned) so `for await` consumers cannot discard it. // Discriminate against ExecStreamChunk with `'type' in event`. export interface ExecExitEvent { type: 'exit'; exitCode: number; } /** An exec stream item: a stdout/stderr chunk or the terminal exit event. */ export type ExecStreamEvent = ExecStreamChunk | ExecExitEvent; export interface ExecInteractiveOptions extends SandboxWorkspaceOptions { workdir?: string; environment?: Record; timeoutSecs?: number; /** Request a pseudo-terminal (default true). */ tty?: boolean; /** Initial terminal columns (0 = server default). */ cols?: number; /** Initial terminal rows (0 = server default). */ rows?: number; /** * Skip sourcing shell login/profile startup files before the command. * Defaults to `false`, which preserves login-shell behavior. */ noLoginShell?: boolean; /** Abort the interactive exec (and the in-flight stream RPC) early. */ signal?: AbortSignal; } // The transport half of an interactive exec: raw stdin/stdout/stderr plus // resize, with no terminal glue. Drive it by consuming `output`, which yields // chunks then a terminal exit event; `done` resolves only after an exit event // and successful RPC completion. Consume output concurrently with awaiting done. export interface ExecInteractiveSession { output: AsyncIterable; write(data: Buffer): void; resize(cols: number, rows: number): void; /** Close stdin and resize input while preserving output. */ close(): void; done: Promise; } /** Lifecycle controls available on SDK-created sessions. The base interface * retains its original members for existing custom sessions and wrappers. */ export interface ExecInteractiveSessionControl extends ExecInteractiveSession { /** Close stdin and resize input, preserving output until completion. */ closeInput(): void; /** Cancel the RPC and stop receiving output. */ cancel(): void; /** Observed process exit, retained even if final RPC completion fails. */ readonly exitCode: number | undefined; } // ---- watchLogs -------------------------------------------------------- /** A curated log line delivered by `watchLogs`. */ export interface LogLine { sandboxId: string; /** Milliseconds since epoch. 0 if the wire timestamp was absent or unrepresentable. */ timestampMs: number; level: string; target: string; message: string; /** Log source (e.g. `'gateway'`, `'sandbox'`). An empty wire value is normalized to `'gateway'`. */ source: string; fields: Record; } /** A curated platform (compute-backend) event delivered by `watchLogs`. */ export interface PlatformEvent { /** Milliseconds since epoch. 0 if the wire timestamp was absent or unrepresentable. */ timestampMs: number; source: string; type: string; reason: string; message: string; metadata: Record; } // WatchLogEvent and WatchPlatformEvent both carry `cursor`, so — unlike // ExecStreamEvent's distinctly-named-field trick — discrimination needs an // explicit `kind` tag. export interface WatchLogEvent { kind: 'log'; line: LogLine; /** Opaque high-water-mark cursor. Feed back as `WatchOptions.resumeAfterCursor` to resume. */ cursor: string; } export interface WatchPlatformEvent { kind: 'event'; event: PlatformEvent; /** Opaque high-water-mark cursor. Feed back as `WatchOptions.resumeAfterCursor` to resume. */ cursor: string; } /** Recoverable server-side loss notice. The stream continues; never advances the cursor. */ export interface WatchWarningEvent { kind: 'warning'; message: string; } /** One item from `watchLogs`. Discriminate on `kind`. */ export type WatchEvent = WatchLogEvent | WatchPlatformEvent | WatchWarningEvent; export interface WatchOptions extends SandboxWorkspaceOptions { /** Stream server/supervisor log lines. Defaults to `true` when neither this nor `followEvents` is set. */ followLogs?: boolean; /** Stream platform (compute-backend) events. */ followEvents?: boolean; /** Restrict to these log sources (e.g. `'gateway'`, `'sandbox'`). Omit or empty for no filter. */ logSources?: string[]; /** Minimum log level to include (e.g. `'INFO'`, `'WARN'`, `'ERROR'`). Omit for no filter. */ logMinLevel?: string; /** * Opaque cursor to resume after, taken from a previous `WatchEvent`'s `cursor`. * Omit or leave empty to start from the tail. Do not construct or parse one. */ resumeAfterCursor?: string; /** Replay the last N log lines (best-effort) before following. */ logTailLines?: number; /** Replay the last N platform events (best-effort) before following. */ eventTail?: number; /** Abort the watch (including any pending reconnect backoff) early. */ signal?: AbortSignal; } /** Cancellation for the poll-based wait helpers. */ export interface WaitOptions extends SandboxWorkspaceOptions { /** Abort the wait (and the in-flight poll RPC) early. */ signal?: AbortSignal; } export interface WaitDeletedOptions extends WaitOptions { /** Original ID from delete(). Complete on absence or a different ID; omit to wait for name absence. */ expectedSandboxId?: string; } export interface ForwardOptions extends SandboxWorkspaceOptions { /** Loopback TCP port inside the sandbox to dial. */ targetPort: number; /** Target host inside the sandbox (loopback only). Default 127.0.0.1. */ targetHost?: string; /** Local port to bind. Default 0 (ephemeral). */ localPort?: number; /** Local address to bind. Default 127.0.0.1. */ localHost?: string; /** Abort forward setup and tear down the local listener early. */ signal?: AbortSignal; /** Receives failures from individual accepted connections. */ onConnectionError?: (error: SdkError) => void; } // A process-lifetime local listener that tunnels each accepted connection into // the sandbox. Call `close()` on teardown; `closed` resolves once the listener // is fully torn down. An in-process forward cannot outlive the Node process. export interface ForwardHandle { localHost: string; localPort: number; targetHost: string; targetPort: number; close(): Promise; closed: Promise; } export interface SshSession { sandboxId: string; token: string; gatewayHost: string; gatewayPort: number; gatewayScheme: string; hostKeyFingerprint?: string; /** int64 ms-since-epoch rendered as a string; omitted when 0 (no expiry). */ expiresAtMs?: string; } export interface ProviderRef { id: string; name: string; type: string; labels: Record; /** u64 rendered as a string. */ resourceVersion: string; } export interface ProviderChange { sandbox: SandboxRef; /** True when the attach/detach actually changed the attachment set. */ changed: boolean; } export interface ProviderChangeOptions extends SandboxWorkspaceOptions { /** Pin the sandbox resource version for optimistic concurrency (u64 as string). */ expectedResourceVersion?: string; } /** Effective value of one setting plus the scope it resolved from. */ export interface EffectiveSettingView { value?: SettingValue; /** 'unspecified' | 'sandbox' | 'global'. */ scope: SettingScopeName; } export interface SandboxConfig { policy?: SandboxPolicy; version: number; policyHash: string; settings: Record; /** u64 rendered as a string. */ configRevision: string; /** 'unspecified' | 'sandbox' | 'global'. */ policySource: PolicySourceName; globalPolicyVersion: number; /** u64 rendered as a string. */ providerEnvRevision: string; } export interface SetPolicyOptions extends SandboxWorkspaceOptions { /** Pin the sandbox resource version for optimistic concurrency (u64 as string). */ expectedResourceVersion?: string; /** Poll getConfig until the applied policy hash is observed. */ wait?: boolean; /** Bound the `wait` poll (seconds). Default 60. */ waitTimeoutSecs?: number; } export interface UpdateConfigResult { version: number; policyHash: string; /** u64 rendered as a string. */ settingsRevision: string; deleted: boolean; } // ---- enum → lowercase string ----------------------------------------------- // Exported for the enum-name drift test only; not re-exported from index.ts, so // they are not part of the public package API. export const PHASE_NAMES: Record = { [SandboxPhase.UNSPECIFIED]: 'unspecified', [SandboxPhase.PROVISIONING]: 'provisioning', [SandboxPhase.READY]: 'ready', [SandboxPhase.ERROR]: 'error', [SandboxPhase.DELETING]: 'deleting', [SandboxPhase.UNKNOWN]: 'unknown', [SandboxPhase.STOPPING]: 'stopping', [SandboxPhase.STOPPED]: 'stopped', [SandboxPhase.STARTING]: 'starting', [SandboxPhase.COMPLETED]: 'completed', [SandboxPhase.SUSPENDING]: 'suspending', [SandboxPhase.SUSPENDED]: 'suspended', }; export const STATUS_NAMES: Record = { [ServiceStatus.UNSPECIFIED]: 'unspecified', [ServiceStatus.HEALTHY]: 'healthy', [ServiceStatus.DEGRADED]: 'degraded', [ServiceStatus.UNHEALTHY]: 'unhealthy', }; export const SCOPE_NAMES: Record = { [SettingScope.UNSPECIFIED]: 'unspecified', [SettingScope.SANDBOX]: 'sandbox', [SettingScope.GLOBAL]: 'global', }; export const POLICY_SOURCE_NAMES: Record = { [PolicySource.UNSPECIFIED]: 'unspecified', [PolicySource.SANDBOX]: 'sandbox', [PolicySource.GLOBAL]: 'global', }; function phaseName(p: SandboxPhase): SandboxPhaseName { return PHASE_NAMES[p] ?? 'unspecified'; } function restartPolicyValue(policy: SandboxRestartPolicyName | undefined): SandboxRestartPolicy { switch (policy) { case 'on-failure': return SandboxRestartPolicy.ON_FAILURE; case 'always': return SandboxRestartPolicy.ALWAYS; default: return SandboxRestartPolicy.NEVER; } } function statusName(s: ServiceStatus): HealthStatus { return STATUS_NAMES[s] ?? 'unspecified'; } function scopeName(s: SettingScope): SettingScopeName { return SCOPE_NAMES[s] ?? 'unspecified'; } function policySourceName(s: PolicySource): PolicySourceName { return POLICY_SOURCE_NAMES[s] ?? 'unspecified'; } function sandboxRef(sandbox: Sandbox | undefined, serviceUrls: Record = {}): SandboxRef { if (!sandbox) throw new SdkError('invalid_config', 'sandbox missing from gateway response'); const meta = sandbox.metadata; if (!meta?.id || !meta.name) { throw new SdkError('invalid_config', 'sandbox metadata.id and metadata.name are required in gateway responses'); } return { id: meta.id, name: meta.name, workspace: meta.workspace, phase: phaseName(sandbox.status?.phase ?? SandboxPhase.UNSPECIFIED), labels: meta?.labels ?? {}, resourceVersion: (meta?.resourceVersion ?? 0n).toString(), hostKeyFingerprint: sandbox.hostKeyFingerprint || undefined, mainProcessInstanceId: sandbox.status?.mainProcessInstanceId || undefined, exitCode: sandbox.status?.exitCode, createdFromWorkloadTemplate: sandbox.createdFromWorkloadTemplate ? { name: sandbox.createdFromWorkloadTemplate.name, resourceVersion: sandbox.createdFromWorkloadTemplate.resourceVersion, } : undefined, serviceUrls, restartCount: sandbox.status?.restartCount ?? 0, createdAtMs: timestampEpochMs(meta.createdTime), nextRestartAtMs: timestampEpochMs(sandbox.status?.nextRestartTime), mainProcessStartedAtMs: timestampEpochMs(sandbox.status?.mainProcessStartedTime), }; } function sandboxTemplate(template: SandboxWorkloadTemplate | undefined): SandboxWorkloadTemplate { if (!template) throw new SdkError('invalid_config', 'sandbox template missing from gateway response'); return template; } function providerRef(provider: Provider): ProviderRef { const meta = provider.metadata; return { id: meta?.id ?? '', name: meta?.name ?? '', type: provider.type, labels: meta?.labels ?? {}, resourceVersion: (meta?.resourceVersion ?? 0n).toString(), }; } function sandboxConfig(resp: GetSandboxConfigResponse): SandboxConfig { const settings: Record = {}; for (const [key, setting] of Object.entries(resp.settings)) { settings[key] = effectiveSetting(setting); } return { ...(resp.policy ? { policy: resp.policy } : {}), version: resp.version, policyHash: resp.policyHash, settings, configRevision: resp.configRevision.toString(), policySource: policySourceName(resp.policySource), globalPolicyVersion: resp.globalPolicyVersion, providerEnvRevision: resp.providerEnvRevision.toString(), }; } function effectiveSetting(setting: EffectiveSetting): EffectiveSettingView { return { ...(setting.value ? { value: setting.value } : {}), scope: scopeName(setting.scope), }; } function updateConfigResult(resp: UpdateConfigResponse): UpdateConfigResult { return { version: resp.version, policyHash: resp.policyHash, settingsRevision: resp.settingsRevision.toString(), deleted: resp.deleted, }; } // Optimistic-concurrency version pin: absent/empty means 0n (server uses the // current version, backward-compatible). A mismatch surfaces as Aborted → // SdkError code 'aborted'. function versionPin(value: string | undefined): bigint { if (!value) return 0n; let pin: bigint; try { pin = BigInt(value); } catch { // BigInt() throws a raw SyntaxError on non-integer input; keep the SdkError // taxonomy intact so callers' errorCode() checks still match. throw new SdkError('invalid_config', `expectedResourceVersion is not a u64: '${value}'`); } if (pin < 0n) { throw new SdkError('invalid_config', `expectedResourceVersion is not a u64: '${value}'`); } return pin; } const FORWARD_CHUNK = 64 * 1024; function workspaceName(options?: SandboxWorkspaceOptions | null): string { const workspace = options?.workspace ?? 'default'; if (workspace.trim() === '') throw new SdkError('invalid_config', 'workspace must be non-empty'); return workspace; } function workspaceScope(options?: SandboxWorkspaceOptions | null): MessageInitShape { return { selection: { case: 'workspace', value: workspaceName(options) } }; } function listWorkspaceScope(options?: WorkspaceListScope | null): MessageInitShape { return options?.allWorkspaces ? { selection: { case: 'allWorkspaces', value: {} } } : workspaceScope(options); } function sandboxTarget(name: string, options?: SandboxWorkspaceOptions | null) { return { sandbox: name, workspaceScope: workspaceScope(options) }; } function namedTarget(name: string, options?: SandboxWorkspaceOptions | null) { return { name, workspaceScope: workspaceScope(options) }; } function requestCallOptions(options?: SandboxCallOptions | null): CallOptions | undefined { if (!options) return undefined; const { workspace: _workspace, ...callOptions } = options; return callOptions; } // Build CallOptions that bound one poll RPC by the remaining wall-clock budget // and honor caller cancellation, so a stalled RPC cannot outlive the deadline. function deadlineOptions(remainingMs: number, signal?: AbortSignal): CallOptions { const timeout = AbortSignal.timeout(Math.max(0, remainingMs)); return { signal: signal ? AbortSignal.any([signal, timeout]) : timeout, }; } // Translate a poll failure at the wait boundary: caller cancellation and the // poll's deadline signal both become explicit SdkErrors; anything else propagates. function mapWaitError( err: unknown, name: string, deadline: number, signal?: AbortSignal, pollSignal?: AbortSignal, ): SdkError { if (signal?.aborted) return new SdkError('connect', `wait for sandbox '${name}' aborted`); if (pollSignal?.aborted || Date.now() >= deadline) return new SdkError('connect', `timed out waiting for sandbox '${name}'`); return err instanceof SdkError ? err : fromConnect(err); } // Sleep between polls, bounded by the remaining deadline and interruptible by // the caller signal so the returned promise stays within its timeout budget. function waitSleep(delayMs: number, deadline: number, signal?: AbortSignal): Promise { const bounded = Math.min(delayMs, Math.max(0, deadline - Date.now())); return new Promise((resolve, reject) => { const timer = setTimeout(() => { signal?.removeEventListener('abort', onAbort); resolve(); }, bounded); const onAbort = (): void => { clearTimeout(timer); reject(new SdkError('connect', 'wait aborted')); }; if (signal) signal.addEventListener('abort', onAbort, { once: true }); }); } // Reconnect backoff for watchLogs: uncapped deadline, just a capped delay // interruptible by the caller signal. Distinct from waitSleep, which is // deadline-bounded for poll loops. function defaultWatchLogsBackoffSleep(delayMs: number, signal?: AbortSignal): Promise { return new Promise((resolve, reject) => { const timer = setTimeout(() => { signal?.removeEventListener('abort', onAbort); resolve(); }, delayMs); const onAbort = (): void => { clearTimeout(timer); reject(new SdkError('canceled', 'watchLogs aborted')); }; if (signal) signal.addEventListener('abort', onAbort, { once: true }); }); } let watchLogsBackoffSleep: (delayMs: number, signal?: AbortSignal) => Promise = defaultWatchLogsBackoffSleep; /** * Test-only seam for the `watchLogs` reconnect backoff delay. Not part of the * public API surface — not re-exported from index.ts. Call with no argument * to restore the real timer-based sleep. */ export function __setWatchLogsBackoffSleepForTests( fn?: (delayMs: number, signal?: AbortSignal) => Promise, ): void { watchLogsBackoffSleep = fn ?? defaultWatchLogsBackoffSleep; } // Only Unavailable (connection drop, gateway restart) is retryable. Every // other status — including OUT_OF_RANGE — is terminal so the caller sees it // instead of the loop silently restarting from an empty cursor and hiding a gap. function isRetryableWatchLogsError(err: SdkError): boolean { return err.connectCode === Code.Unavailable; } function toLogLine(value: SandboxLogLine): LogLine { return { sandboxId: value.sandboxId, timestampMs: eventTimeMillis(value.eventTime), level: value.level, target: value.target, message: value.message, source: value.source || 'gateway', fields: { ...value.fields }, }; } function toPlatformEvent(value: WirePlatformEvent): PlatformEvent { return { timestampMs: eventTimeMillis(value.eventTime), source: value.source, type: value.type, reason: value.reason, message: value.message, metadata: { ...value.metadata }, }; } // Converts one wire watch event into a curated WatchEvent, returning the // (possibly advanced) cursor alongside it. `cursor` is a high-water mark, not // "last seen": the gateway reads the log and platform sources independently // during live delivery, so arrival order can differ from cursor order. Taking // the max keeps the resume point monotonic; assigning directly would let a // later lower-cursor event rewind it and replay already-delivered events after // a reconnect. The comparison is a plain byte-wise string compare on an opaque // token — well defined only because both cursors come from the same stream. function convertWatchEvent(wireEvent: SandboxStreamEvent, cursor: string): { event?: WatchEvent; cursor: string } { switch (wireEvent.payload.case) { case 'log': { const next = wireEvent.cursor > cursor ? wireEvent.cursor : cursor; return { event: { kind: 'log', line: toLogLine(wireEvent.payload.value), cursor: wireEvent.cursor }, cursor: next, }; } case 'event': { const next = wireEvent.cursor > cursor ? wireEvent.cursor : cursor; return { event: { kind: 'event', event: toPlatformEvent(wireEvent.payload.value), cursor: wireEvent.cursor }, cursor: next, }; } case 'warning': return { event: { kind: 'warning', message: wireEvent.payload.value.message }, cursor }; default: // Sandbox snapshots and draft-policy updates are not part of this // curated log/event stream. return { cursor }; } } // Wait for a socket to drain before writing more. Resolves on 'drain', and // also on 'close'/'error' so a pending await never leaks when the socket is // torn down mid-backpressure; short-circuits if it is already gone. function waitForDrain(socket: net.Socket): Promise { if (socket.writableEnded || socket.destroyed) return Promise.resolve(); return new Promise((resolve) => { const done = (): void => { socket.removeListener('drain', done); socket.removeListener('close', done); socket.removeListener('error', done); resolve(); }; socket.once('drain', done); socket.once('close', done); socket.once('error', done); }); } // An async-iterable queue for the client-send half of bidi streams. Producers // `push()` frames; the connect transport consumes them as it drains the send // side. `end()` closes the stream (optionally with an error). `onDrain` fires // when the buffered queue empties via consumption, so callers can relieve TCP // backpressure. export class Pushable implements AsyncIterable { private readonly queue: T[] = []; private readonly waiting: Array<{ resolve: (result: IteratorResult) => void; reject: (error: unknown) => void; }> = []; private ended = false; private error: unknown; onDrain?: () => void; get size(): number { return this.queue.length; } push(value: T): void { if (this.ended) return; const waiter = this.waiting.shift(); if (waiter) { waiter.resolve({ value, done: false }); } else { this.queue.push(value); } } end(error?: unknown): void { if (this.ended) return; this.ended = true; this.error = error; let waiter = this.waiting.shift(); while (waiter) { if (error !== undefined) waiter.reject(error); else waiter.resolve({ value: undefined as never, done: true }); waiter = this.waiting.shift(); } } async *[Symbol.asyncIterator](): AsyncIterator { for (;;) { if (this.queue.length > 0) { const value = this.queue.shift() as T; if (this.queue.length === 0) this.onDrain?.(); yield value; continue; } if (this.ended) { if (this.error !== undefined) throw this.error; return; } const next = await new Promise>((resolve, reject) => { this.waiting.push({ resolve, reject }); }); if (next.done) { if (this.error !== undefined) throw this.error; return; } yield next.value; } } } // Single producer/consumer queue. Closing wakes both directions, including a // producer blocked by backpressure. Successful completion drains queued values. class ExecOutputQueue { private readonly values: ExecStreamEvent[] = []; private ended = false; private error: unknown; private reader?: () => void; private writer?: () => void; async push(value: ExecStreamEvent): Promise { // The terminal exit carries no output bytes and must never block cleanup // after done has already settled and its cancellation listener is removed. while (!('type' in value) && this.values.length >= 16 && !this.ended) { await new Promise((resolve) => { this.writer = resolve; }); } if (this.ended) throw this.error ?? new SdkError('canceled', 'exec output closed'); this.values.push(value); this.reader?.(); this.reader = undefined; } end(error?: unknown, discard = false): void { if (discard) this.values.length = 0; if (!this.ended) { this.ended = true; this.error = error; } this.reader?.(); this.writer?.(); this.reader = undefined; this.writer = undefined; } async *[Symbol.asyncIterator](): AsyncGenerator { for (;;) { const value = this.values.shift(); if (value !== undefined) { this.writer?.(); this.writer = undefined; yield value; } else if (this.ended) { if (this.error !== undefined) throw this.error; return; } else { await new Promise((resolve) => { this.reader = resolve; }); } } } } /** One response page from a list operation. */ export interface Page { readonly items: T[]; readonly nextPageToken: string; } const maxConsumedPageTokens = 10_000; const maxConsumedPageTokenBytes = 1 << 20; /** Lazy, single-pass iterator that fetches one RPC page per advance. */ export class Pager implements AsyncIterable> { private nextToken: string | undefined; private readonly consumedTokens = new Set(); private consumedTokenBytes = 0; constructor( private readonly fetch: (pageToken: string) => Promise>, pageToken = '', private readonly maxConsumedTokens = maxConsumedPageTokens, private readonly maxConsumedTokenBytes = maxConsumedPageTokenBytes, ) { this.nextToken = pageToken; } private validateCurrentTokenBudget(pageToken: string): number { if (pageToken === '') return 0; const tokenBytes = new TextEncoder().encode(pageToken).byteLength; if ( this.consumedTokens.size >= this.maxConsumedTokens || tokenBytes > this.maxConsumedTokenBytes - this.consumedTokenBytes ) { throw new Error('pager continuation token history limit exceeded'); } return tokenBytes; } /** Fetch the next page, or return undefined after the final page. */ async nextPage(): Promise | undefined> { if (this.nextToken === undefined) return undefined; const pageToken = this.nextToken; const tokenBytes = this.validateCurrentTokenBudget(pageToken); const page = await this.fetch(pageToken); if (pageToken !== '') { this.consumedTokens.add(pageToken); this.consumedTokenBytes += tokenBytes; } if (page.nextPageToken !== '' && this.consumedTokens.has(page.nextPageToken)) { throw new Error('pager received a repeated continuation token'); } this.nextToken = page.nextPageToken === '' ? undefined : page.nextPageToken; return page; } /** Consume the pager and collect every remaining item. */ async all(): Promise { const items: T[] = []; for await (const page of this) items.push(...page.items); return items; } async *[Symbol.asyncIterator](): AsyncIterator> { for (;;) { const page = await this.nextPage(); if (page === undefined) return; yield page; } } } // ---- sandbox template client ---------------------------------------------- // Reusable sandbox workload template lifecycle. Templates intentionally return // generated proto messages because the resource owns portable workload fields // plus driver-specific config that should not be lossy in the curated layer. export class SandboxTemplateClient { private readonly grpc: Client; readonly raw: Client; readonly transport: Transport; constructor(transport: Transport, grpc = createClient(OpenShell, transport)) { this.transport = transport; this.grpc = grpc; this.raw = this.grpc; } static async connect(options: ConnectOptions): Promise { return new SandboxTemplateClient(buildTransport(options)); } async create( template: MessageInitShape, options?: SandboxTemplateWorkspaceOptions | null, ): Promise { try { const resp = await this.grpc.createSandboxTemplate({ workspaceScope: workspaceScope(options), template, }); return sandboxTemplate(resp.template); } catch (e) { throw e instanceof SdkError ? e : fromConnect(e); } } async get(name: string, options?: SandboxTemplateWorkspaceOptions | null): Promise { if (name.trim() === '') throw new SdkError('invalid_config', 'template name is required'); try { const resp = await this.grpc.getSandboxTemplate({ workspaceScope: workspaceScope(options), name, }); return sandboxTemplate(resp.template); } catch (e) { throw e instanceof SdkError ? e : fromConnect(e); } } list(options?: SandboxTemplateListOptions | null): Pager { return new Pager(async (pageToken) => { try { const resp = await this.grpc.listSandboxTemplates({ pageSize: options?.pageSize ?? 0, pageToken, labelSelector: options?.labelSelector ?? '', workspaceScope: listWorkspaceScope(options), }); return { items: resp.templates, nextPageToken: resp.nextPageToken }; } catch (e) { throw fromConnect(e); } }, options?.pageToken ?? ''); } /** List and collect every sandbox template in this scope. */ async listAll(options?: SandboxTemplateListOptions | null): Promise { return this.list(options).all(); } async delete(name: string, options?: DeleteOptions | null): Promise { if (name.trim() === '') throw new SdkError('invalid_config', 'template name is required'); try { const resp = await this.grpc.deleteSandboxTemplate({ workspaceScope: workspaceScope(options), allowMissing: options?.allowMissing ?? false, name, }); return deletionResult(resp); } catch (e) { throw fromConnect(e); } } } // ---- sandbox client -------------------------------------------------------- // Sandbox lifecycle + exec. Usable standalone via `SandboxClient.connect()`, // or reached as `client.sandbox` on an OpenShellClient, which shares one // transport (one connection) across all of its scoped clients. export class SandboxClient { private readonly grpc: Client; /** * Advanced escape hatch: a generated client for every gateway RPC, including * surface the curated methods do not wrap yet. Request/response types are the * generated wire messages (import them from '@nvidia/openshell-sdk/raw'). */ readonly raw: Client; /** The shared Connect transport, for building extra clients over the same connection. */ readonly transport: Transport; // Takes a transport rather than options so OpenShellClient can compose // several scoped clients over a single connection. For standalone use, // prefer the SandboxClient.connect() factory below. constructor(transport: Transport, grpc = createClient(OpenShell, transport)) { this.transport = transport; this.grpc = grpc; this.raw = this.grpc; } /** * Constructs a lazy Connect client. No network request is made until the * first RPC; call get() or another operation to verify reachability. */ static async connect(options: ConnectOptions): Promise { return new SandboxClient(buildTransport(options)); } async create(spec: SandboxSpec): Promise { try { // Curated fields build the base spec; rawSpec then shallow-overrides at // the top spec level (Object.assign, so any field it sets wins). The // runtime assign avoids the generated $typeName upgrading the literal and // rejecting the curated `template: { image }` init shorthand. const specInit: MessageInitShape = { environment: spec.environment ?? {}, providers: spec.providers ?? [], template: spec.image ? { image: spec.image } : undefined, resourceRequirements: spec.gpu ? { gpu: {} } : undefined, policy: spec.policy, command: spec.command ?? [], tty: spec.tty ?? false, restartPolicy: restartPolicyValue(spec.restartPolicy), }; if (spec.rawSpec) Object.assign(specInit, spec.rawSpec); const resp = await this.grpc.createSandbox({ workspaceScope: workspaceScope(spec), name: spec.name ?? '', labels: spec.labels ?? {}, spec: specInit, serviceExposures: spec.serviceExposures?.map((exposure) => ({ service: exposure.service ?? '', targetPort: exposure.targetPort, authorizationMode: serviceAuthorizationModeToProto(exposure.authorizationMode), })) ?? [], }); return sandboxRef(resp.sandbox, resp.serviceUrls); } catch (e) { throw fromConnect(e); } } async createFromTemplate(spec: SandboxFromTemplateSpec): Promise { if (spec.workloadTemplate.trim() === '') throw new SdkError('invalid_config', 'workloadTemplate is required'); try { const resp = await this.grpc.createSandbox({ workspaceScope: workspaceScope(spec), name: spec.name ?? '', labels: spec.labels ?? {}, spec: { providers: spec.providers ?? [], command: spec.command ?? [], tty: spec.tty ?? false, policy: spec.policy, }, workloadTemplate: spec.workloadTemplate, serviceExposures: spec.serviceExposures?.map((exposure) => ({ service: exposure.service ?? '', targetPort: exposure.targetPort, authorizationMode: serviceAuthorizationModeToProto(exposure.authorizationMode), })) ?? [], }); return sandboxRef(resp.sandbox, resp.serviceUrls); } catch (e) { throw fromConnect(e); } } async get(name: string, options?: SandboxCallOptions | null): Promise { return this.getSandbox(name, options); } // get() that also asks the gateway which replica owns the supervisor session. private async getWithOwner( name: string, options?: SandboxCallOptions | null, ): Promise<{ ref: SandboxRef; owner?: string }> { let owner: string | undefined; const ref = await this.getSandbox(name, options, { headers: { [OWNER_REQUEST_HEADER]: '1' }, onHeader: (header) => { owner = header.get(OWNER_REPLICA_HEADER) || undefined; }, }); return { ref, owner }; } private async getSandbox(name: string, options?: SandboxCallOptions | null, call?: CallOptions): Promise { try { const resp = await this.grpc.getSandbox( { ...namedTarget(name, options) }, { ...requestCallOptions(options), ...call }, ); return sandboxRef(resp.sandbox); } catch (e) { throw fromConnect(e); } } list(options?: ListOptions | null): Pager { return new Pager(async (pageToken) => { try { const resp = await this.grpc.listSandboxes({ pageSize: options?.pageSize ?? 0, pageToken, labelSelector: options?.labelSelector ?? '', workspaceScope: listWorkspaceScope(options), }); return { items: resp.sandboxes.map((sandbox) => sandboxRef(sandbox)), nextPageToken: resp.nextPageToken, }; } catch (e) { throw fromConnect(e); } }, options?.pageToken ?? ''); } /** List and collect every sandbox in this scope. */ async listAll(options?: ListOptions | null): Promise { return this.list(options).all(); } async delete(name: string, options?: DeleteOptions | null): Promise { try { const resp = await this.grpc.deleteSandbox({ ...namedTarget(name, options), allowMissing: options?.allowMissing ?? false, }); return deletionResult(resp); } catch (e) { throw fromConnect(e); } } // Poll until the sandbox is ready. The timeout bounds the returned promise, // not just the sleep loop: each poll RPC carries the remaining deadline (and // any caller signal), so a stalled get() is aborted rather than hanging. async waitReady(name: string, timeoutSecs: number, options?: WaitOptions | null): Promise { const deadline = Date.now() + timeoutSecs * 1000; const signal = options?.signal; let delay = 250; for (;;) { if (signal?.aborted) throw new SdkError('connect', `wait for sandbox '${name}' aborted`); if (Date.now() >= deadline) throw new SdkError('connect', `timed out waiting for sandbox '${name}'`); let ref: SandboxRef; const pollOptions = deadlineOptions(deadline - Date.now(), signal); try { ref = await this.get(name, { ...pollOptions, workspace: options?.workspace, }); } catch (e) { throw mapWaitError(e, name, deadline, signal, pollOptions.signal); } if (ref.phase === 'ready' || ref.phase === 'completed') return ref; if (ref.phase === 'stopped') throw new SdkError('connect', `sandbox '${name}' stopped before becoming ready`); if (ref.phase === 'error') throw new SdkError('connect', `sandbox '${name}' entered error phase`); if (ref.phase === 'suspending' || ref.phase === 'suspended') { throw new SdkError('connect', `sandbox '${name}' is suspended; resume it before waiting for ready`); } if (Date.now() >= deadline) throw new SdkError('connect', `timed out waiting for sandbox '${name}'`); await waitSleep(delay, deadline, signal); delay = Math.min(delay * 2, 2000); } } // Poll until the sandbox is gone, or its name resolves to a different ID when // expectedSandboxId is supplied. Timeout and cancellation work as in waitReady. async waitDeleted(name: string, timeoutSecs: number, options?: WaitDeletedOptions | null): Promise { const deadline = Date.now() + timeoutSecs * 1000; const signal = options?.signal; let delay = 250; for (;;) { if (signal?.aborted) throw new SdkError('connect', `wait for sandbox '${name}' aborted`); if (Date.now() >= deadline) throw new SdkError('connect', `timed out waiting for sandbox '${name}' to delete`); const pollOptions = deadlineOptions(deadline - Date.now(), signal); try { const ref = await this.get(name, { ...pollOptions, workspace: options?.workspace }); if (options?.expectedSandboxId !== undefined && ref.id !== options.expectedSandboxId) return; } catch (e) { if (e instanceof SdkError && e.code === 'not_found') return; throw mapWaitError(e, name, deadline, signal, pollOptions.signal); } if (Date.now() >= deadline) throw new SdkError('connect', `timed out waiting for sandbox '${name}' to delete`); await waitSleep(delay, deadline, signal); delay = Math.min(delay * 2, 2000); } } // Stream stdout/stderr as they arrive, then a terminal exit event. The exit // is yielded in-band (not returned) so `for await` consumers cannot silently // discard it: a failing command is impossible to miss. If the gateway closes // the stream without an exit event, this throws. `exec()` drains this same // path to reconstruct the buffered result. async *execStream( name: string, command: string[], options?: ExecOptions | null, ): AsyncGenerator { try { // Preserve the existing preflight so lookup failures surface before the stream starts. const { owner } = await this.getWithOwner(name, { workspace: options?.workspace, ...(options?.signal ? { signal: options.signal } : {}), }); const request = { ...sandboxTarget(name, options), command, workdir: options?.workdir ?? '', environment: options?.environment ?? {}, executionTimeout: durationFromSeconds(options?.timeoutSecs ?? 0), stdin: options?.stdin ? new Uint8Array(options.stdin) : new Uint8Array(), tty: false, noLoginShell: options?.noLoginShell ?? false, }; const stream = routedStream(owner, ({ headers, onHeader }) => this.grpc.execSandbox(request, { signal: options?.signal, headers, onHeader }), ); let sawExit = false; for await (const event of stream) { switch (event.payload.case) { case 'stdout': yield { stream: 'stdout', data: Buffer.from(event.payload.value.data), }; break; case 'stderr': yield { stream: 'stderr', data: Buffer.from(event.payload.value.data), }; break; case 'exit': sawExit = true; yield { type: 'exit', exitCode: event.payload.value.exitCode }; break; } } if (!sawExit) throw new SdkError('rpc', 'ExecSandbox stream ended without an exit event'); } catch (e) { throw e instanceof SdkError ? e : fromConnect(e); } } async exec(name: string, command: string[], options?: ExecOptions | null): Promise { const stdout: Buffer[] = []; const stderr: Buffer[] = []; let exitCode: number | undefined; for await (const event of this.execStream(name, command, options)) { if ('type' in event) { exitCode = event.exitCode; } else if (event.stream === 'stdout') { stdout.push(event.data); } else { stderr.push(event.data); } } if (exitCode === undefined) throw new SdkError('rpc', 'ExecSandbox stream ended without an exit event'); return { exitCode, stdout: Buffer.concat(stdout), stderr: Buffer.concat(stderr), }; } /** * Watch a sandbox's log lines and platform events with loss-aware resume. * * Reconnects transparently on a transient stream drop, resuming from the * highest cursor already delivered. A recoverable server-side lag surfaces * as a `{ kind: 'warning' }` item and the stream continues. * * An `SdkError` with `connectCode === Code.OutOfRange` is terminal and not * retried: the resume point is gone (trimmed from the buffer, or issued by a * cursor space the gateway no longer has), so events between it and now are * unrecoverable. Auto-restarting from scratch would hide that loss, which is * exactly what this method exists to surface. Callers who accept the gap can * start a new watch with an empty `resumeAfterCursor`; retrying the same * cursor fails identically. */ async *watchLogs(name: string, options?: WatchOptions | null): AsyncGenerator { let ref: SandboxRef; try { ref = await this.get(name, { workspace: options?.workspace, ...(options?.signal ? { signal: options.signal } : {}), }); } catch (e) { throw e instanceof SdkError ? e : fromConnect(e); } const signal = options?.signal; let followLogs = options?.followLogs ?? false; const followEvents = options?.followEvents ?? false; // With both resolved false — whether from an explicit `false` or from // omitting both options — the request would stream nothing and never // complete or error. Mirror the Go SDK's guard and default to logs, since // that footgun is worse than this one-line divergence from Rust's bare // pass-through default. if (!followLogs && !followEvents) followLogs = true; let cursor = options?.resumeAfterCursor ?? ''; let backoffMs = 100; for (;;) { if (signal?.aborted) throw new SdkError('canceled', 'watchLogs aborted'); // connect-es returns this AsyncIterable synchronously and unconditionally; // the stream only opens on first iteration, so "dial" and "drain" failures // both land in the single catch below (unlike tonic's separate Result). const stream = this.grpc.watchSandbox( { ...sandboxTarget(ref.name, options), followStatus: false, followLogs, followEvents, logTailLines: options?.logTailLines ?? 0, eventTail: options?.eventTail ?? 0, logSources: options?.logSources ?? [], logMinLevel: options?.logMinLevel ?? '', resumeAfterCursor: cursor, }, { signal }, ); let cleanEof = true; try { for await (const wireEvent of stream) { // A delivered event means the connection is healthy again; reset the // backoff so a later drop retries promptly instead of at the cap. backoffMs = 100; const converted = convertWatchEvent(wireEvent, cursor); cursor = converted.cursor; if (converted.event) yield converted.event; } } catch (e) { cleanEof = false; const err = e instanceof SdkError ? e : fromConnect(e); if (!isRetryableWatchLogsError(err)) throw err; await watchLogsBackoffSleep(backoffMs, signal); backoffMs = Math.min(backoffMs * 2, 2000); } if (cleanEof) break; } } // TTY + stdin transport half of an interactive exec. The first client frame // is the `start` variant carrying the exec request; subsequent frames are // `stdin`/`resize`. No terminal glue: raw mode, signal forwarding, and // SIGWINCH stay with the caller. async execInteractive( name: string, command: string[], options?: ExecInteractiveOptions | null, ): Promise { let owner: string | undefined; try { ({ owner } = await this.getWithOwner(name, { workspace: options?.workspace, ...(options?.signal ? { signal: options.signal } : {}), })); } catch (e) { throw e instanceof SdkError ? e : fromConnect(e); } const input = new Pushable>(); const start: MessageInitShape = { payload: { case: 'start', value: { ...sandboxTarget(name, options), command, workdir: options?.workdir ?? '', environment: options?.environment ?? {}, executionTimeout: durationFromSeconds(options?.timeoutSecs ?? 0), stdin: new Uint8Array(), tty: options?.tty ?? true, cols: options?.cols ?? 0, rows: options?.rows ?? 0, noLoginShell: options?.noLoginShell ?? false, }, }, }; const controller = new AbortController(); const signal = options?.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal; const grpc = this.grpc; const queue = new ExecOutputQueue(); let inputClosed = false; let exitCode: number | undefined; const closeInput = (): void => { inputClosed = true; input.end(); }; const assertInputOpen = (): void => { if (inputClosed || signal.aborted) throw new SdkError('io', 'exec input is closed'); }; let resolveDone!: (code: number) => void; let rejectDone!: (err: unknown) => void; const done = new Promise((resolve, reject) => { resolveDone = resolve; rejectDone = reject; }); // `done` may settle before (or without) anyone awaiting it. A lone handler // keeps an unobserved rejection from surfacing as an unhandledRejection; // real awaiters still receive it through their own handler. void done.catch(() => {}); // The process exit and the terminal transport status are separate outcomes. let settled = false; const settleExit = (code: number): void => { if (settled) return; settled = true; signal.removeEventListener('abort', onAbort); resolveDone(code); }; const settleError = (err: unknown): void => { if (settled) return; settled = true; signal.removeEventListener('abort', onAbort); rejectDone(err); }; const onAbort = (): void => { closeInput(); const error = new SdkError('canceled', 'exec cancelled'); queue.end(error, true); settleError(error); }; signal.addEventListener('abort', onAbort, { once: true }); if (signal.aborted) onAbort(); async function receive(): Promise { try { if (signal.aborted) throw new SdkError('canceled', 'exec cancelled'); // Start and observe the transport immediately, independently of output // consumption. Backpressure bounds the queue to 16 chunks of 64 KiB. const stream = routedStream(owner, ({ headers, onHeader, ready }) => grpc.execSandboxInteractive(heldUntilReady(start, input, ready), { signal, headers, onHeader }), ); for await (const event of stream) { if (signal.aborted) throw new SdkError('canceled', 'exec cancelled'); if (exitCode !== undefined) { throw new SdkError('rpc', 'ExecSandboxInteractive received an event after exit'); } switch (event.payload.case) { case 'stdout': case 'stderr': for (let offset = 0; offset < event.payload.value.data.length; offset += 64 * 1024) { await queue.push({ stream: event.payload.case, data: Buffer.from(event.payload.value.data.subarray(offset, offset + 64 * 1024)), }); } break; case 'exit': exitCode = event.payload.value.exitCode; closeInput(); break; default: throw new SdkError('rpc', 'ExecSandboxInteractive received an empty or unknown event'); } } if (exitCode === undefined) { throw new SdkError('rpc', 'ExecSandboxInteractive stream ended without an exit event'); } if (signal.aborted) throw new SdkError('canceled', 'exec cancelled before completion'); // Delay the public exit event until trailers have been consumed. A // caller can still break on exit without losing the terminal status. settleExit(exitCode); await queue.push({ type: 'exit', exitCode }); queue.end(); } catch (e) { const err = e instanceof SdkError ? e : fromConnect(e); settleError(err); queue.end(err); } finally { closeInput(); controller.abort(); } } // receive catches transport failures even when nobody consumes output/done. const receiving = receive(); async function* output(): AsyncGenerator { try { yield* queue; } finally { const error = new SdkError('rpc', 'exec output abandoned before completion'); settleError(error); queue.end(error, true); closeInput(); controller.abort(); await receiving; } } return { output: output(), write(data: Buffer): void { assertInputOpen(); input.push({ payload: { case: 'stdin', value: new Uint8Array(data) } }); }, resize(cols: number, rows: number): void { assertInputOpen(); input.push({ payload: { case: 'resize', value: { cols, rows } } }); }, closeInput, close: closeInput, cancel(): void { closeInput(); queue.end(new SdkError('canceled', 'exec cancelled'), true); controller.abort(); settleError(new SdkError('canceled', 'exec cancelled')); }, get exitCode(): number | undefined { return exitCode; }, done, }; } // Bind a local TCP listener that tunnels each accepted connection into the // sandbox. Mirrors the CLI service forward: READY check, then per socket mint // a short-lived SSH session token, open a forwardTcp bidi whose first frame is // the `init` (TCP target + token), relay bytes both ways in ~64 KiB chunks, // and revoke the token on close. Process-lifetime only. async forward(name: string, opts: ForwardOptions): Promise { const targetHost = opts.targetHost ?? '127.0.0.1'; const targetPort = opts.targetPort; const localHost = opts.localHost ?? '127.0.0.1'; const localPort = opts.localPort ?? 0; let sandboxId: string; let owner: string | undefined; try { const found = await this.getWithOwner(name, { workspace: opts.workspace, ...(opts.signal ? { signal: opts.signal } : {}), }); const ref = found.ref; if (ref.phase !== 'ready') { throw new SdkError('connect', `sandbox '${name}' is not ready (phase: ${ref.phase})`); } sandboxId = ref.id; owner = found.owner; } catch (e) { throw e instanceof SdkError ? e : fromConnect(e); } const sockets = new Set(); const controllers = new Set(); const connectionTasks = new Set>(); let closing = false; const server = net.createServer((socket) => { sockets.add(socket); socket.on('close', () => sockets.delete(socket)); // Guard the window before forwardConnection attaches its own handlers // (it first awaits createSshSession). Without a synchronous 'error' // listener a peer reset here emits an unhandled 'error' and crashes the // process; forwardConnection's catch still tears the socket down. socket.on('error', () => {}); const controller = new AbortController(); controllers.add(controller); const task = this.forwardConnection( socket, sandboxId, name, opts.workspace, targetHost, targetPort, owner, controller.signal, ) .catch((error: unknown) => { if (!closing) { try { opts.onConnectionError?.(error instanceof SdkError ? error : fromConnect(error)); } catch { // Consumer callbacks must not turn a handled connection failure // into an unhandled rejection or prevent forward cleanup. } } }) .finally(() => { controllers.delete(controller); connectionTasks.delete(task); }); connectionTasks.add(task); }); let resolveClosed!: () => void; const closed = new Promise((resolve) => { resolveClosed = resolve; }); await new Promise((resolve, reject) => { const onError = (err: unknown): void => { reject( new SdkError( 'io', `failed to bind local forward on ${localHost}:${localPort}: ${err instanceof Error ? err.message : String(err)}`, ), ); }; server.once('error', onError); server.listen(localPort, localHost, () => { server.removeListener('error', onError); resolve(); }); }); let teardownPromise: Promise | undefined; const onAbort = (): void => { void teardown(); }; const teardown = (): Promise => { if (teardownPromise) return teardownPromise; closing = true; opts.signal?.removeEventListener('abort', onAbort); teardownPromise = (async () => { for (const controller of controllers) controller.abort(); for (const socket of sockets) socket.destroy(); if (server.listening) { await new Promise((resolve) => server.close(() => resolve())); } await Promise.allSettled([...connectionTasks]); resolveClosed(); })(); return teardownPromise; }; // Caller cancellation tears the local listener down the same way close() does. if (opts.signal) { if (opts.signal.aborted) void teardown(); else opts.signal.addEventListener('abort', onAbort, { once: true }); } const addr = server.address() as AddressInfo | null; return { localHost, localPort: addr ? addr.port : localPort, targetHost, targetPort, close: teardown, closed, }; } private async forwardConnection( socket: net.Socket, sandboxId: string, name: string, workspace: string | undefined, targetHost: string, targetPort: number, owner: string | undefined, signal: AbortSignal, ): Promise { let token: string | undefined; const input = new Pushable>(); input.onDrain = () => socket.resume(); try { const session = await this.grpc.createSshSession({ ...sandboxTarget(name, { workspace }) }, { signal }); // Defense-in-depth: the token feeds forwardTcp authorization, so hold it // to the same trust-boundary contract as createSshSession. A violation // tears down this one socket via the catch below. validateSshResponse(session, sandboxId); token = session.token; const init: MessageInitShape = { payload: { case: 'init', value: { ...sandboxTarget(name, { workspace }), serviceId: `service-forward:${name}:${targetHost}:${targetPort}`, target: { case: 'tcp', value: { host: targetHost, port: targetPort }, }, authorizationToken: token, }, }, }; socket.on('data', (chunk: Buffer) => { for (let off = 0; off < chunk.length; off += FORWARD_CHUNK) { const slice = chunk.subarray(off, Math.min(off + FORWARD_CHUNK, chunk.length)); input.push({ payload: { case: 'data', value: new Uint8Array(slice) }, }); } if (input.size >= 64) socket.pause(); }); socket.on('end', () => input.end()); socket.on('error', (error) => input.end(error)); socket.on('close', () => input.end()); const onAbort = (): void => { input.end(new SdkError('canceled', 'forward connection closed')); socket.destroy(); }; signal.addEventListener('abort', onAbort, { once: true }); try { const frames = routedStream(owner, ({ headers, onHeader, ready }) => this.grpc.forwardTcp(heldUntilReady(init, input, ready), { signal, headers, onHeader }), ); for await (const frame of frames) { if (frame.payload.case !== 'data') continue; const data = frame.payload.value; if (data.length === 0) continue; // Respect backpressure: if the local socket buffer is full, stop // pulling sandbox data until it drains so memory stays bounded. if (!socket.write(Buffer.from(data))) await waitForDrain(socket); } } finally { signal.removeEventListener('abort', onAbort); } socket.end(); } catch (e) { socket.destroy(); throw e instanceof SdkError ? e : fromConnect(e); } finally { input.end(); if (token !== undefined) { try { await this.grpc.revokeSshSession({ token, allowMissing: true }, { signal }); } catch { // Best-effort revoke; the token expires on its own regardless. } } } } // Mint a short-lived SSH session token for the sandbox — the input side of // ssh-config / ProxyCommand and forwardTcp authorization. async createSshSession(name: string, options?: SandboxWorkspaceOptions | null): Promise { try { const sandbox = await this.get(name, options); const resp = await this.grpc.createSshSession({ ...sandboxTarget(name, options) }); // Reject any response outside the proto trust-boundary contract before // handing these values to the caller (they feed OpenSSH ProxyCommand). validateSshResponse(resp, sandbox.id); return { sandboxId: resp.sandboxId, token: resp.token, gatewayHost: resp.gatewayHost, gatewayPort: resp.gatewayPort, gatewayScheme: resp.gatewayScheme, ...(resp.hostKeyFingerprint ? { hostKeyFingerprint: resp.hostKeyFingerprint } : {}), ...(timestampMillis(resp.expirationTime) ? { expiresAtMs: timestampMillis(resp.expirationTime) } : {}), }; } catch (e) { throw e instanceof SdkError ? e : fromConnect(e); } } async revokeSshSession(token: string, options?: Pick): Promise { try { const resp = await this.grpc.revokeSshSession({ token, allowMissing: options?.allowMissing ?? false }); return deletionResult(resp); } catch (e) { throw fromConnect(e); } } async attachProvider( name: string, provider: string, options?: ProviderChangeOptions | null, ): Promise { try { const resp = await this.grpc.attachSandboxProvider({ ...sandboxTarget(name, options), provider, expectedResourceVersion: versionPin(options?.expectedResourceVersion), }); return { sandbox: sandboxRef(resp.sandbox), changed: resp.attached }; } catch (e) { throw fromConnect(e); } } async detachProvider( name: string, provider: string, options?: ProviderChangeOptions | null, ): Promise { try { const resp = await this.grpc.detachSandboxProvider({ ...sandboxTarget(name, options), provider, expectedResourceVersion: versionPin(options?.expectedResourceVersion), }); return { sandbox: sandboxRef(resp.sandbox), changed: resp.detached }; } catch (e) { throw fromConnect(e); } } listProviders(name: string, options?: SandboxProviderListOptions | null): Pager { return new Pager(async (pageToken) => { try { const resp = await this.grpc.listSandboxProviders({ ...sandboxTarget(name, options), pageSize: options?.pageSize ?? 0, pageToken, }); return { items: resp.providers.map((provider) => providerRef(provider)), nextPageToken: resp.nextPageToken, }; } catch (e) { throw fromConnect(e); } }, options?.pageToken ?? ''); } /** List and collect every provider attached to this sandbox. */ async listAllProviders(name: string, options?: SandboxProviderListOptions | null): Promise { return this.listProviders(name, options).all(); } async getConfig(name: string, options?: SandboxCallOptions | null): Promise { try { await this.get(name, options); const resp = await this.grpc.getSandboxConfig({ ...namedTarget(name, options) }, requestCallOptions(options)); return sandboxConfig(resp); } catch (e) { throw e instanceof SdkError ? e : fromConnect(e); } } // Update the sandbox-scoped policy. Sandbox scope (global=false) may only // change network_policies; static fields must match the create-time policy or // the gateway rejects the update. With `wait`, poll getConfig until the // applied policy hash is observed. async setPolicy( name: string, policy: MessageInitShape, options?: SetPolicyOptions | null, ): Promise { try { const resp = await this.grpc.updateConfig({ ...sandboxTarget(name, options), policy, global: false, expectedResourceVersion: versionPin(options?.expectedResourceVersion), }); const result = updateConfigResult(resp); if (options?.wait) await this.waitForPolicyHash(name, result.policyHash, options.waitTimeoutSecs, options.workspace); return result; } catch (e) { throw e instanceof SdkError ? e : fromConnect(e); } } // Upsert a single sandbox-scoped setting. Sandbox-scoped deletes are rejected // by the gateway, so there is no sandbox-scoped delete on this surface. async setSetting( name: string, key: string, value: MessageInitShape, options?: SandboxWorkspaceOptions | null, ): Promise { try { const resp = await this.grpc.updateConfig({ ...sandboxTarget(name, options), settingKey: key, settingValue: value, global: false, }); return updateConfigResult(resp); } catch (e) { throw fromConnect(e); } } // Poll getConfig until the applied policy hash is observed. Each poll RPC is // bounded by the remaining deadline (deadlineOptions), so a stalled getConfig // cannot make the returned promise outlive timeoutSecs. private async waitForPolicyHash( name: string, policyHash: string, timeoutSecs = 60, workspace?: string, ): Promise { const deadline = Date.now() + timeoutSecs * 1000; let delay = 100; for (;;) { let config: SandboxConfig; const pollOptions = deadlineOptions(deadline - Date.now()); try { config = await this.getConfig(name, { ...pollOptions, workspace }); } catch (e) { if (pollOptions.signal?.aborted || Date.now() >= deadline) { throw new SdkError('connect', `timed out waiting for policy '${policyHash}' on sandbox '${name}'`); } throw e instanceof SdkError ? e : fromConnect(e); } if (config.policyHash === policyHash) return; if (Date.now() >= deadline) { throw new SdkError('connect', `timed out waiting for policy '${policyHash}' on sandbox '${name}'`); } await waitSleep(delay, deadline); delay = Math.min(delay * 2, 2000); } } } // ---- The client ------------------------------------------------------------ export class OpenShellClient { /** Sandbox lifecycle + exec: create/get/list/delete, waitReady/waitDeleted, exec. */ readonly sandbox: SandboxClient; /** Reusable sandbox workload template lifecycle. */ readonly sandboxTemplates: SandboxTemplateClient; /** Privileged provider credential retrieval; requires direct operator mTLS. */ readonly providers: ProviderClient; /** * Advanced escape hatch: a generated client for every gateway RPC, including * surface the curated sub-clients do not wrap yet (gateway config, provider * CRUD, policy status, watch, logs, and the full observed Sandbox). See * '@nvidia/openshell-sdk/raw' for the generated request/response types. */ readonly raw: Client; /** The shared Connect transport, for building extra clients over the same connection. */ readonly transport: Transport; private readonly grpc: Client; private constructor(transport: Transport) { // One transport (one connection) shared across every scoped client. this.transport = transport; this.grpc = createClient(OpenShell, transport); this.raw = this.grpc; this.sandbox = new SandboxClient(transport, this.grpc); this.sandboxTemplates = new SandboxTemplateClient(transport, this.grpc); this.providers = new ProviderClient(transport); } /** * Constructs a lazy Connect client. No network request is made until the * first RPC; call health() when startup must verify gateway reachability. */ static async connect(options: ConnectOptions): Promise { return new OpenShellClient(buildTransport(options)); } // Gateway-scoped, so it stays top-level rather than under a namespace. async health(): Promise { try { const resp = await this.grpc.health({}); return { status: statusName(resp.status), version: resp.version }; } catch (e) { throw fromConnect(e); } } }