import { normalizeRailwayClientConfig, resolveEnvironmentId, type NormalizedRailwayClientConfig, type RailwayClientConfig, } from "../core/config.js"; import { requestGraphQL } from "../core/graphql-client.js"; import { RailwaySandboxCreateDocument, RailwaySandboxExecDocument, RailwaySandboxSessionsDocument, RailwaySandboxDestroyDocument, RailwaySandboxHeartbeatDocument, RailwaySandboxDocument, RailwaySandboxesDocument, RailwaySandboxCheckpointCreateDocument, RailwaySandboxCheckpointDeleteDocument, RailwaySandboxCheckpointRenameDocument, RailwaySandboxCheckpointsDocument, RailwaySandboxTemplateBuildDocument, RailwaySandboxTemplateBuildStatusDocument, type RailwaySandboxCheckpointCreateMutation, type RailwaySandboxCheckpointCreateMutationVariables, type RailwaySandboxCheckpointDeleteMutation, type RailwaySandboxCheckpointDeleteMutationVariables, type RailwaySandboxCheckpointRenameMutation, type RailwaySandboxCheckpointRenameMutationVariables, type RailwaySandboxCheckpointsQuery, type RailwaySandboxCheckpointsQueryVariables, type RailwaySandboxCreateMutation, type RailwaySandboxCreateMutationVariables, type RailwaySandboxDestroyMutation, type RailwaySandboxDestroyMutationVariables, type RailwaySandboxHeartbeatMutation, type RailwaySandboxHeartbeatMutationVariables, type RailwaySandboxSessionFieldsFragment, type RailwaySandboxExecMutation, type RailwaySandboxExecMutationVariables, type RailwaySandboxSessionsQuery, type RailwaySandboxSessionsQueryVariables, type RailwaySandboxesQuery, type RailwaySandboxesQueryVariables, type RailwaySandboxQuery, type RailwaySandboxQueryVariables, type RailwaySandboxTemplateBuildMutation, type RailwaySandboxTemplateBuildMutationVariables, type RailwaySandboxTemplateBuildStatusQuery, type RailwaySandboxTemplateBuildStatusQueryVariables, type SandboxTemplateInput, } from "../generated/graphql.js"; import { SandboxFailedError, SandboxNotFoundError, SandboxTemplateBuildError, SandboxTimeoutError, } from "./errors.js"; import { startExec, type ExecContext, type ExecHandle } from "./exec.js"; import { createSandboxFiles, type SandboxFiles } from "./files.js"; import type { CompiledTemplate, CreateOptions, ExecOptions, ExecTarget, ForkOptions, ListOptions, ExecHttpOptions, ExecHttpResult, SandboxCheckpointInfo, SandboxCreationOptions, SandboxInfo, SandboxResources, SandboxSessionInfo, SandboxTemplateBuildInfo, TemplateSource, } from "./types.js"; const READINESS_TIMEOUT_MS = 5 * 60_000; /** Upper bound on `sessions()` paging; a sandbox holds far fewer sessions. */ const MAX_SESSION_PAGES = 20; const POLL_INITIAL_DELAY_MS = 500; const POLL_MAX_DELAY_MS = 5_000; const sleep = (ms: number): Promise => new Promise(resolve => setTimeout(resolve, ms)); interface SandboxEngineConfig extends NormalizedRailwayClientConfig { environmentId: string; } export interface SandboxOptions extends RailwayClientConfig { environmentId?: string; } /** * Binds resolved credentials and environment to sandbox GraphQL operations. */ export class SandboxEngine { readonly #config: SandboxEngineConfig; constructor(config: SandboxEngineConfig) { this.#config = config; } get environmentId(): string { return this.#config.environmentId; } async create( options: CreateOptions = {}, template?: TemplateSource, ): Promise { const input: RailwaySandboxCreateMutationVariables["input"] = { environmentId: this.#config.environmentId, }; if (template !== undefined) { // For a compiled recipe, echo its build-time variables so the backend // hash matches the built snapshot and forks from it. input.template = toTemplateInput(template); } return this.#createAndWait(input, options); } async fork( sourceSandboxId: string, options: ForkOptions = {}, ): Promise { return this.#createAndWait( { environmentId: this.#config.environmentId, sourceSandboxId }, options, ); } /** Applies the shared creation knobs, runs the create mutation, and waits for RUNNING. */ async #createAndWait( input: RailwaySandboxCreateMutationVariables["input"], options: SandboxCreationOptions, ): Promise { if (options.idleTimeoutMinutes !== undefined) { input.idleTimeoutMinutes = options.idleTimeoutMinutes; } if (options.networkIsolation !== undefined) { input.networkIsolation = options.networkIsolation; } if (options.resources !== undefined) { input.resources = validResources(options.resources); } if (options.domains !== undefined) { input.publicDomains = options.domains; } if (options.region !== undefined) { input.region = options.region; } if (options.env !== undefined) { input.variables = options.env; } this.#config.log(creationLine(input)); const data = await requestGraphQL< RailwaySandboxCreateMutation, RailwaySandboxCreateMutationVariables >(this.#config, RailwaySandboxCreateDocument, { input }); this.#config.log( `created sandbox ${data.sandboxCreate.id} status=${data.sandboxCreate.status}`, ); return this.#waitForRunning(data.sandboxCreate); } async buildTemplate( template: CompiledTemplate, region?: string, ): Promise { const variables: RailwaySandboxTemplateBuildMutationVariables = { environmentId: this.#config.environmentId, input: { ...toTemplateInput(template), ...(region && { region }) }, }; const data = await requestGraphQL< RailwaySandboxTemplateBuildMutation, RailwaySandboxTemplateBuildMutationVariables >(this.#config, RailwaySandboxTemplateBuildDocument, variables); return data.sandboxTemplateBuild; } async getTemplateBuild(id: string): Promise { const variables: RailwaySandboxTemplateBuildStatusQueryVariables = { id, environmentId: this.#config.environmentId, }; const data = await requestGraphQL< RailwaySandboxTemplateBuildStatusQuery, RailwaySandboxTemplateBuildStatusQueryVariables >(this.#config, RailwaySandboxTemplateBuildStatusDocument, variables); return data.sandboxTemplateBuild; } async buildTemplateUntilReady( template: CompiledTemplate, region?: string, ): Promise { const varCount = template.variables ? Object.keys(template.variables).length : 0; this.#config.log( `build template (${template.instructions.length} steps, vars=${varCount})`, ); return this.#waitForBuildReady(await this.buildTemplate(template, region)); } /** * Capture a running sandbox's disk into a named checkpoint. Synchronous on * the backend: the checkpoint is bootable when this resolves. */ async checkpoint( sandboxId: string, name: string, ): Promise { this.#config.log(`checkpoint sandbox ${sandboxId} -> "${name}"`); const variables: RailwaySandboxCheckpointCreateMutationVariables = { environmentId: this.#config.environmentId, name, sandboxId, }; const data = await requestGraphQL< RailwaySandboxCheckpointCreateMutation, RailwaySandboxCheckpointCreateMutationVariables >(this.#config, RailwaySandboxCheckpointCreateDocument, variables); this.#config.log(`checkpoint ${data.sandboxCheckpointCreate.id} ready`); return data.sandboxCheckpointCreate; } async listCheckpoints(): Promise { const data = await requestGraphQL< RailwaySandboxCheckpointsQuery, RailwaySandboxCheckpointsQueryVariables >(this.#config, RailwaySandboxCheckpointsDocument, { environmentId: this.#config.environmentId, }); return data.sandboxCheckpoints; } async renameCheckpoint( id: string, name: string, ): Promise { this.#config.log(`rename checkpoint ${id} -> "${name}"`); const data = await requestGraphQL< RailwaySandboxCheckpointRenameMutation, RailwaySandboxCheckpointRenameMutationVariables >(this.#config, RailwaySandboxCheckpointRenameDocument, { environmentId: this.#config.environmentId, id, name, }); return data.sandboxCheckpointRename; } /** * Every session in the sandbox (all pages), or null when its runtime cannot * list them. A sandbox holds few sessions, so callers get the whole set. */ async sessions(sandboxId: string): Promise { const sessions: SandboxSessionInfo[] = []; let after: string | undefined; for (let page = 0; page < MAX_SESSION_PAGES; page++) { const variables: RailwaySandboxSessionsQueryVariables = { environmentId: this.#config.environmentId, id: sandboxId, ...(after !== undefined ? { after } : {}), }; const data = await requestGraphQL< RailwaySandboxSessionsQuery, RailwaySandboxSessionsQueryVariables >(this.#config, RailwaySandboxSessionsDocument, variables); if (data.sandboxSessions == null) return null; for (const { node } of data.sandboxSessions.edges) sessions.push(toSessionInfo(node)); const { hasNextPage, endCursor } = data.sandboxSessions.pageInfo; if (!hasNextPage || !endCursor) return sessions; after = endCursor; } this.#config.log(`sessions: stopped after ${MAX_SESSION_PAGES} pages in sandbox ${sandboxId}`); return sessions; } /** One-request exec over HTTPS: no streaming, stdin, or cancellation. */ async execHttp( sandboxId: string, command: string, options: ExecHttpOptions = {}, ): Promise { if ( options.timeoutSec !== undefined && !(Number.isInteger(options.timeoutSec) && options.timeoutSec > 0) ) { // The HTTPS exec takes whole seconds, unlike the streaming exec's timer. throw new TypeError("`timeoutSec` must be a positive whole number of seconds."); } this.#config.log(`execHttp in sandbox ${sandboxId}`); const data = await requestGraphQL< RailwaySandboxExecMutation, RailwaySandboxExecMutationVariables >(this.#config, RailwaySandboxExecDocument, { environmentId: this.#config.environmentId, id: sandboxId, command, ...(options.timeoutSec !== undefined ? { timeoutSec: options.timeoutSec } : {}), }); return { ...data.sandboxExec }; } async deleteCheckpoint(id: string): Promise { this.#config.log(`delete checkpoint ${id}`); await requestGraphQL< RailwaySandboxCheckpointDeleteMutation, RailwaySandboxCheckpointDeleteMutationVariables >(this.#config, RailwaySandboxCheckpointDeleteDocument, { environmentId: this.#config.environmentId, id, }); } /** * Resolves once the build is READY (its checkpoint exists). PENDING (no * workflow yet) and BUILDING keep polling; only FAILED is terminal. */ async #waitForBuildReady( build: SandboxTemplateBuildInfo, ): Promise { if (build.status === "READY") { this.#config.log(`template build ${build.id} ready (cached)`); return build; } if (build.status === "FAILED") { throw new SandboxTemplateBuildError({ templateId: build.id, environmentId: this.environmentId, }); } return this.#pollUntilReady({ poll: () => this.getTemplateBuild(build.id), isReady: build => build.status === "READY", isTerminal: build => build.status === "FAILED", describe: build => `template build ${build.id} status=${build.status}`, onTerminal: build => { throw new SandboxTemplateBuildError({ templateId: build.id, environmentId: this.environmentId, }); }, onTimeout: build => { throw new SandboxTimeoutError({ resource: "template", id: build.id, lastStatus: build.status, timeoutMs: READINESS_TIMEOUT_MS, }); }, }); } async #waitForRunning(created: SandboxInfo): Promise { if (created.status === "RUNNING") return created; if (isSandboxTerminal(created.status)) { throw new SandboxFailedError({ id: created.id, status: created.status }); } return this.#pollUntilReady({ poll: () => this.#getOrThrow(created.id), isReady: info => info.status === "RUNNING", isTerminal: info => isSandboxTerminal(info.status), describe: info => `sandbox ${info.id} status=${info.status}`, onTerminal: info => { throw new SandboxFailedError({ id: info.id, status: info.status }); }, onTimeout: info => { throw new SandboxTimeoutError({ resource: "sandbox", id: info.id, lastStatus: info.status, timeoutMs: READINESS_TIMEOUT_MS, }); }, }); } async #getOrThrow(id: string): Promise { const info = await this.get(id); if (!info) { throw new SandboxNotFoundError({ id, environmentId: this.environmentId }); } return info; } async #pollUntilReady(args: { poll: () => Promise; isReady: (value: T) => boolean; isTerminal: (value: T) => boolean; onTerminal: (value: T) => never; onTimeout: (value: T) => never; describe?: (value: T) => string; }): Promise { const start = Date.now(); const describe = args.describe; let delay = POLL_INITIAL_DELAY_MS; let last: T; do { await sleep(delay); last = await args.poll(); const elapsedSec = ((Date.now() - start) / 1000).toFixed(1); if (args.isReady(last)) { if (describe) this.#config.log(`${describe(last)} ready after ${elapsedSec}s`); return last; } if (args.isTerminal(last)) { if (describe) this.#config.log(`${describe(last)} hit terminal state`); return args.onTerminal(last); } delay = Math.min(delay * 2, POLL_MAX_DELAY_MS); if (describe) { this.#config.log( `waiting on ${describe(last)}, retry in ${delay}ms (elapsed ${elapsedSec}s)`, ); } } while (Date.now() - start < READINESS_TIMEOUT_MS); if (describe) { const elapsedSec = ((Date.now() - start) / 1000).toFixed(1); this.#config.log(`${describe(last)} timed out after ${elapsedSec}s`); } return args.onTimeout(last); } exec(id: string, target: ExecTarget, options: ExecOptions = {}): ExecHandle { const context: ExecContext = { config: this.#config, environmentId: this.#config.environmentId, sandboxId: id, }; return startExec(context, target, options); } files(id: string): SandboxFiles { return createSandboxFiles({ config: this.#config, environmentId: this.#config.environmentId, sandboxId: id, }); } async destroy(id: string): Promise { const variables: RailwaySandboxDestroyMutationVariables = { id, environmentId: this.#config.environmentId, }; this.#config.log(`destroy sandbox ${id}`); await requestGraphQL< RailwaySandboxDestroyMutation, RailwaySandboxDestroyMutationVariables >(this.#config, RailwaySandboxDestroyDocument, variables); } async heartbeat(id: string): Promise { const variables: RailwaySandboxHeartbeatMutationVariables = { id, environmentId: this.#config.environmentId, }; this.#config.log(`heartbeat sandbox ${id}`); const data = await requestGraphQL< RailwaySandboxHeartbeatMutation, RailwaySandboxHeartbeatMutationVariables >(this.#config, RailwaySandboxHeartbeatDocument, variables); if (!data.sandboxHeartbeat) { throw new SandboxNotFoundError({ id, environmentId: this.environmentId }); } return data.sandboxHeartbeat; } async get(id: string): Promise { const variables: RailwaySandboxQueryVariables = { id, environmentId: this.#config.environmentId, }; const data = await requestGraphQL< RailwaySandboxQuery, RailwaySandboxQueryVariables >(this.#config, RailwaySandboxDocument, variables); const info = data.sandbox ?? null; if (!info) { this.#config.log(`sandbox ${id} not found (env=${this.environmentId})`); } return info; } async list(options: ListOptions = {}): Promise { const variables: RailwaySandboxesQueryVariables = { environmentId: this.#config.environmentId, }; if (options.first !== undefined) variables.first = options.first; if (options.after !== undefined) variables.after = options.after; const data = await requestGraphQL< RailwaySandboxesQuery, RailwaySandboxesQueryVariables >(this.#config, RailwaySandboxesDocument, variables); return data.sandboxes.edges.map(edge => edge.node); } } function isSandboxTerminal(status: SandboxInfo["status"]): boolean { return status === "FAILED" || status === "DESTROYED" || status === "DESTROYING"; } function toTemplateInput(template: TemplateSource): SandboxTemplateInput { if ("name" in template) { return { name: template.name }; } return { instructions: [...template.instructions], ...(template.variables && { variables: template.variables }), }; } function creationKind( input: RailwaySandboxCreateMutationVariables["input"], ): string { if (input.sourceSandboxId) return "fork"; if (input.template?.name) return "create-from-checkpoint"; if (input.template) return "create-from-template"; return "create"; } /** Verbose line for a create/fork/template create. Logs env key names, never values. */ function creationLine( input: RailwaySandboxCreateMutationVariables["input"], ): string { const kind = creationKind(input); const envKeys = input.variables ? Object.keys(input.variables) : []; const domains = (input.publicDomains ?? []).map(domain => domain.prefix ? `${domain.prefix}:${domain.port}` : String(domain.port), ); const parts = [ kind, `env=${input.environmentId}`, `idleTimeout=${input.idleTimeoutMinutes ?? "none"}`, `network=${input.networkIsolation ?? "default"}`, `region=${input.region ?? "default"}`, `envKeys=[${envKeys.join(",")}]`, `domains=[${domains.join(",")}]`, ]; if (input.resources) { parts.push(`resources=cpu:${input.resources.cpu ?? "default"},memGB:${input.resources.memoryGB ?? "default"}`); } if (input.sourceSandboxId) parts.push(`source=${input.sourceSandboxId}`); if (input.template?.name) parts.push(`checkpoint="${input.template.name}"`); return parts.join(" "); } export function engineFromOptions(options: SandboxOptions = {}): SandboxEngine { const base = normalizeRailwayClientConfig(options); const environmentId = resolveEnvironmentId(options.environmentId); return new SandboxEngine({ ...base, environmentId }); } /** * The platform validates sizes, but NaN and Infinity serialize to JSON `null`, * which it would silently read as "use the default". Reject them here. */ function validResources(resources: SandboxResources): SandboxResources { for (const key of ["cpu", "memoryGB"] as const) { const value = resources[key]; if (value !== undefined && !(Number.isFinite(value) && value > 0)) { throw new TypeError(`\`resources.${key}\` must be a positive finite number.`); } } return { ...(resources.cpu !== undefined ? { cpu: resources.cpu } : {}), ...(resources.memoryGB !== undefined ? { memoryGB: resources.memoryGB } : {}), }; } /** * Flattens the run state. The schema reports `exitCode: 0` while a session is * still running, so a running session reports `null` instead. */ function toSessionInfo(node: RailwaySandboxSessionFieldsFragment): SandboxSessionInfo { return { name: node.name, kind: node.kind, running: node.runState.running, exitCode: node.runState.running ? null : node.runState.exitCode, exitedAt: node.runState.exitedAt ?? null, attached: node.attached, command: node.command, foregroundActive: node.foregroundActive ?? null, createdAt: node.createdAt ?? null, }; }