@adobe/aio-lib-sandbox 0.1.0-alpha.3

package/src/Sandbox.js

@@ -0,0 +1,467 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+const crypto = require('node:crypto')
+const {
+  SandboxClientError,
+  SandboxTimeoutError,
+  SandboxWebSocketError
+} = require('./errors')
+const {
+  buildWebSocketEndpoint,
+  resolveCredentials,
+  normalizeSize,
+  apiRequest
+} = require('./utils')
+const { SANDBOX_SIZES } = require('./constants')
+const { SandboxSocket } = require('./ws')
+
+/**
+ * Connected compute sandbox session.
+ *
+ * Use `Sandbox.create()` or `Sandbox.get()`
+ */
+class Sandbox {
+  /**
+   * @param {object} options sandbox options
+   * @private
+   */
+  constructor (options) {
+    this.id = options.id
+    this.endpoint = options.endpoint
+    this.status = options.status
+    this.cluster = options.cluster
+    this.region = options.region
+    this.maxLifetime = options.maxLifetime
+
+    this.namespace = options.namespace
+    this.apiHost = options.apiHost
+    this.apiKey = options.apiKey
+    this.token = options.token
+    this.publicUrlTemplate = options.publicUrlTemplate || null
+    this.managementEndpoint = options.managementEndpoint || null
+    this.ws = null
+  }
+
+  /**
+   * Creates a new compute sandbox and opens its WebSocket session.
+   *
+   * Credentials are read from the environment automatically when running inside
+   * a Runtime action (`__OW_API_HOST`, `__OW_NAMESPACE`, `__OW_API_KEY`).
+   * Any value passed explicitly in `options` overrides the environment.
+   *
+   * Commands run inside the sandbox start in the `/workspace` directory by default.
+   *
+   * @param {object} [options] creation options
+   * @param {string} [options.apiHost] Runtime API host (overrides `__OW_API_HOST`)
+   * @param {string} [options.namespace] Runtime namespace (overrides `__OW_NAMESPACE`)
+   * @param {string} [options.auth] Runtime API key (overrides `__OW_API_KEY`)
+   * @param {string} [options.name] sandbox display name
+   * @param {string} [options.type] sandbox type (default: `'cpu:default'`)
+   * @param {string|object} [options.size] sandbox size tier (name or spec object)
+   * @param {number} [options.maxLifetime] maximum lifetime in seconds
+   * @param {object} [options.envs] environment variables to inject into the sandbox
+   * @param {object} [options.policy] network policy (e.g. egress allowlist)
+   * @returns {Promise<Sandbox>} connected sandbox instance
+   */
+  static async create (options = {}) {
+    console.warn('[aio-lib-sandbox] alpha — APIs may change without notice')
+    const creds = resolveCredentials(options)
+
+    const body = {
+      name: options.name,
+      size: normalizeSize(options.size),
+      type: options.type || 'cpu:default',
+      maxLifetime: options.maxLifetime || 3600
+    }
+
+    if (options.cluster !== undefined) body.cluster = options.cluster
+    if (options.region !== undefined) body.region = options.region
+    if (options.envs !== undefined) body.envs = options.envs
+    if (options.policy !== undefined) body.policy = options.policy
+
+    const url = `${creds.apiHost}/api/v1/namespaces/${creds.namespace}/sandbox`
+    const payload = await apiRequest('POST', url, creds.apiKey, body)
+
+    const sandboxId = payload.sandboxId
+    const endpoint = payload.wsEndpoint || buildWebSocketEndpoint(creds.apiHost, creds.namespace, sandboxId)
+
+    const sandbox = new Sandbox({
+      id: sandboxId,
+      endpoint,
+      status: payload.status,
+      cluster: payload.cluster,
+      region: payload.region,
+      maxLifetime: payload.maxLifetime,
+      publicUrlTemplate: payload.publicUrlTemplate || null,
+      managementEndpoint: payload.managementEndpoint || null,
+      namespace: creds.namespace,
+      apiHost: creds.apiHost,
+      apiKey: creds.apiKey,
+      token: payload.token
+    })
+
+    await sandbox.connect()
+    return sandbox
+  }
+
+  /**
+   * Fetches an existing sandbox.
+   *
+   * Credentials are read from the environment automatically.
+   * Any value passed explicitly in `options` overrides the environment.
+   *
+   * @param {string} sandboxId the sandbox ID to look up
+   * @param {object} [options] credential overrides
+   * @param {string} [options.apiHost] Runtime API host
+   * @param {string} [options.namespace] Runtime namespace
+   * @param {string} [options.auth] Runtime API key
+   * @returns {Promise<Sandbox>} sandbox instance with `status` populated (not WebSocket-connected)
+   */
+  static async get (sandboxId, options = {}) {
+    console.warn('[aio-lib-sandbox] alpha — APIs may change without notice')
+    const creds = resolveCredentials(options)
+    const url = `${creds.apiHost}/api/v1/namespaces/${creds.namespace}/sandbox/${sandboxId}`
+    const payload = await apiRequest('GET', url, creds.apiKey)
+
+    return new Sandbox({
+      id: payload.sandboxId || sandboxId,
+      endpoint: null,
+      status: payload.status,
+      cluster: payload.cluster,
+      region: payload.region,
+      maxLifetime: payload.maxLifetime,
+      namespace: creds.namespace,
+      apiHost: creds.apiHost,
+      apiKey: creds.apiKey,
+      token: null
+    })
+  }
+
+  /**
+   * Named sandbox size tiers.
+   *
+   * @type {object}
+   */
+  static get sizes () {
+    return SANDBOX_SIZES
+  }
+
+  /**
+   * Exposes `resolveCredentials` as a static helper (useful for testing).
+   *
+   * @param {object} overrides credential overrides
+   * @returns {{ apiHost: string, namespace: string, apiKey: string }}
+   */
+  static resolveCredentials (overrides = {}) {
+    return resolveCredentials(overrides)
+  }
+
+  /**
+   * Exposes `normalizeSize` as a static helper (useful for testing).
+   *
+   * @param {string|object|undefined} size
+   * @returns {string}
+   */
+  static normalizeSize (size) {
+    return normalizeSize(size)
+  }
+
+  // ------------------------------------------------------------------
+  // WebSocket connection
+  // ------------------------------------------------------------------
+
+  /**
+   * Opens the sandbox WebSocket connection (called automatically by `create()`).
+   *
+   * @returns {Promise<void>}
+   */
+  connect () {
+    if (!this.ws) {
+      this.ws = new SandboxSocket({
+        id: this.id,
+        endpoint: this.endpoint,
+        token: this.token
+      })
+    }
+    return this.ws.connect()
+  }
+
+  // ------------------------------------------------------------------
+  // Exec
+  // ------------------------------------------------------------------
+
+  /**
+   * Executes a command inside the sandbox.
+   *
+   * Returns a Promise (with an `execId` property) that resolves to
+   * `{ execId, stdout, stderr, exitCode }` when the command completes.
+   *
+   * @param {string} command command to run
+   * @param {object} [options] execution options
+   * @param {number} [options.timeout] timeout in milliseconds
+   * @param {string|Buffer} [options.stdin] data to send to stdin at startup
+   * @param {function} [options.onOutput] callback called with `(data, stream)` for each output chunk
+   * @returns {Promise<{execId: string, stdout: string, stderr: string, exitCode: number}>}
+   */
+  exec (command, options = {}) {
+    try {
+      this.ensureOpen()
+    } catch (error) {
+      return Promise.reject(error)
+    }
+
+    const execId = `exec-${crypto.randomBytes(12).toString('hex')}`
+    let timeoutHandle
+
+    const execPromise = new Promise((resolve, reject) => {
+      this.ws.pendingExecs.set(execId, {
+        resolve,
+        reject,
+        stdout: '',
+        stderr: '',
+        onOutput: options.onOutput,
+        timeout: undefined
+      })
+
+      if (options.timeout) {
+        timeoutHandle = setTimeout(() => {
+          try { this.kill(execId) } catch (_) {}
+          this.ws.rejectExec(execId, new SandboxTimeoutError(
+            `Command '${command}' exceeded timeout of ${options.timeout}ms`
+          ))
+        }, options.timeout)
+        this.ws.pendingExecs.get(execId).timeout = timeoutHandle
+      }
+    })
+
+    execPromise.execId = execId
+
+    try {
+      this.sendFrame({ type: 'exec.run', execId, command })
+      if (options.stdin !== undefined) {
+        this.writeStdin(execId, options.stdin)
+        this.closeStdin(execId)
+      }
+    } catch (error) {
+      this.ws.rejectExec(execId, new SandboxWebSocketError(
+        `Could not send exec frame: ${error.message}`
+      ))
+    }
+
+    return execPromise
+  }
+
+  /**
+   * Sends a signal to a running command.
+   *
+   * @param {string} execId execution id
+   * @param {string} [signal] signal to deliver (default: `'SIGTERM'`)
+   */
+  kill (execId, signal = 'SIGTERM') {
+    this.ensureOpen()
+    this.sendFrame({ type: 'exec.kill', execId, signal })
+  }
+
+  /**
+   * Writes data to the stdin of a running command.
+   * Fire-and-forget — there is no response on success.
+   *
+   * @param {string} execId execution id from `exec()`
+   * @param {string|Buffer} data data to write
+   */
+  writeStdin (execId, data) {
+    this.ensureOpen()
+    const frame = { type: 'exec.input', execId }
+    if (Buffer.isBuffer(data)) {
+      frame.data = data.toString('base64')
+      frame.encoding = 'base64'
+    } else {
+      frame.data = data
+    }
+    this.sendFrame(frame)
+  }
+
+  /**
+   * Closes stdin for a running command, signalling EOF.
+   * Fire-and-forget — there is no response on success.
+   *
+   * @param {string} execId execution id from `exec()`
+   */
+  closeStdin (execId) {
+    this.ensureOpen()
+    this.sendFrame({ type: 'exec.endInput', execId })
+  }
+
+  // ------------------------------------------------------------------
+  // File operations
+  // ------------------------------------------------------------------
+
+  /**
+   * Reads a file from the sandbox filesystem.
+   *
+   * @param {string} path path inside the sandbox
+   * @returns {Promise<string>} file contents as a UTF-8 string
+   */
+  readFile (path) {
+    try {
+      this.ensureOpen()
+    } catch (error) {
+      return Promise.reject(error)
+    }
+
+    const execId = `file-${crypto.randomBytes(12).toString('hex')}`
+    const opPromise = new Promise((resolve, reject) => {
+      this.ws.pendingFileOps.set(execId, { resolve, reject })
+    })
+
+    try {
+      this.sendFrame({ type: 'file.read', execId, path })
+    } catch (error) {
+      this.ws.rejectFileOp(execId, new SandboxWebSocketError(
+        `Could not send file.read frame: ${error.message}`
+      ))
+    }
+
+    return opPromise
+  }
+
+  /**
+   * Writes a file to the sandbox filesystem. Parent directories are created automatically.
+   *
+   * @param {string} path path inside the sandbox
+   * @param {string|Buffer} content file contents
+   * @returns {Promise<{path: string, size: number, ok: boolean}>} write confirmation
+   */
+  writeFile (path, content) {
+    try {
+      this.ensureOpen()
+    } catch (error) {
+      return Promise.reject(error)
+    }
+
+    const execId = `file-${crypto.randomBytes(12).toString('hex')}`
+    const encoded = Buffer.isBuffer(content)
+      ? content.toString('base64')
+      : Buffer.from(content).toString('base64')
+
+    const opPromise = new Promise((resolve, reject) => {
+      this.ws.pendingFileOps.set(execId, { resolve, reject })
+    })
+
+    try {
+      this.sendFrame({ type: 'file.write', execId, path, content: encoded, encoding: 'base64' })
+    } catch (error) {
+      this.ws.rejectFileOp(execId, new SandboxWebSocketError(
+        `Could not send file.write frame: ${error.message}`
+      ))
+    }
+
+    return opPromise
+  }
+
+  /**
+   * Lists the contents of a directory inside the sandbox.
+   *
+   * @param {string} path directory path inside the sandbox
+   * @returns {Promise<Array<{name: string, type: string, size?: number}>>} directory entries
+   */
+  listFiles (path) {
+    try {
+      this.ensureOpen()
+    } catch (error) {
+      return Promise.reject(error)
+    }
+
+    const execId = `file-${crypto.randomBytes(12).toString('hex')}`
+    const opPromise = new Promise((resolve, reject) => {
+      this.ws.pendingFileOps.set(execId, { resolve, reject })
+    })
+
+    try {
+      this.sendFrame({ type: 'file.list', execId, path })
+    } catch (error) {
+      this.ws.rejectFileOp(execId, new SandboxWebSocketError(
+        `Could not send file.list frame: ${error.message}`
+      ))
+    }
+
+    return opPromise
+  }
+
+  // ------------------------------------------------------------------
+  // Lifecycle
+  // ------------------------------------------------------------------
+
+  /**
+   * Returns the public preview URL for a given port on this sandbox.
+   *
+   * @param {object} options URL options
+   * @param {number} options.port port number (1–65535)
+   * @param {string} [options.protocol] override the URL scheme (e.g. `'wss'`)
+   * @returns {Promise<string>} public preview URL
+   */
+  async getUrl ({ port, protocol } = {}) {
+    if (!this.publicUrlTemplate) {
+      throw new SandboxClientError(
+        `Cannot get URL for sandbox '${this.id}': publicUrlTemplate is not available`
+      )
+    }
+
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      throw new SandboxClientError(
+        `Invalid port '${port}': must be an integer between 1 and 65535`
+      )
+    }
+
+    let url = this.publicUrlTemplate
+      .replace('{sandboxId}', this.id)
+      .replace('{port}', String(port))
+
+    if (protocol) {
+      url = url.replace(/^https?:\/\//, `${protocol}://`)
+    }
+
+    return url
+  }
+
+  /**
+   * Destroys the sandbox and closes its WebSocket connection.
+   *
+   * @returns {Promise<object>} destroy response payload
+   */
+  async destroy () {
+    const base = this.managementEndpoint || this.apiHost
+    const url = `${base}/api/v1/namespaces/${this.namespace}/sandbox/${this.id}`
+    const payload = await apiRequest('DELETE', url, this.apiKey)
+
+    this.status = payload.status || this.status
+    this.ws?.close()
+    return payload
+  }
+
+  // ------------------------------------------------------------------
+  // Private helpers
+  // ------------------------------------------------------------------
+
+  ensureOpen () {
+    if (!this.ws) {
+      throw new SandboxWebSocketError(`Sandbox '${this.id}' is not connected`)
+    }
+    this.ws.ensureOpen()
+  }
+
+  sendFrame (frame) {
+    this.ws.send(frame)
+  }
+}
+
+module.exports = Sandbox

package/src/constants.js

@@ -0,0 +1,19 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+const SANDBOX_SIZES = Object.freeze({
+  SMALL: { cpu: '500m', memory: '512Mi', gpu: 0 },
+  MEDIUM: { cpu: '2000m', memory: '4Gi', gpu: 0 },
+  LARGE: { cpu: '4000m', memory: '16Gi', gpu: 0 },
+  XLARGE: { cpu: '8000m', memory: '32Gi', gpu: 1 }
+})
+
+module.exports = { SANDBOX_SIZES }

package/src/errors.js

@@ -0,0 +1,37 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+class SandboxSDKError extends Error {
+  constructor (message) {
+    super(message)
+    this.name = this.constructor.name
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor)
+    }
+  }
+}
+
+class SandboxInitializationError extends SandboxSDKError {}
+class SandboxClientError extends SandboxSDKError {}
+class SandboxNotFoundError extends SandboxSDKError {}
+class SandboxUnauthorizedError extends SandboxSDKError {}
+class SandboxTimeoutError extends SandboxSDKError {}
+class SandboxWebSocketError extends SandboxSDKError {}
+
+module.exports = {
+  SandboxSDKError,
+  SandboxInitializationError,
+  SandboxClientError,
+  SandboxNotFoundError,
+  SandboxUnauthorizedError,
+  SandboxTimeoutError,
+  SandboxWebSocketError
+}

package/src/index.js

@@ -0,0 +1,32 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+const Sandbox = require('./Sandbox')
+const {
+  SandboxSDKError,
+  SandboxInitializationError,
+  SandboxClientError,
+  SandboxNotFoundError,
+  SandboxUnauthorizedError,
+  SandboxTimeoutError,
+  SandboxWebSocketError
+} = require('./errors')
+
+module.exports = {
+  Sandbox,
+  SandboxSDKError,
+  SandboxInitializationError,
+  SandboxClientError,
+  SandboxNotFoundError,
+  SandboxUnauthorizedError,
+  SandboxTimeoutError,
+  SandboxWebSocketError
+}

package/src/utils.js

@@ -0,0 +1,143 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+const {
+  SandboxClientError,
+  SandboxInitializationError,
+  SandboxNotFoundError,
+  SandboxUnauthorizedError,
+  SandboxTimeoutError
+} = require('./errors')
+const { SANDBOX_SIZES } = require('./constants')
+
+function buildAuthorizationHeader (apiKey) {
+  return `Basic ${Buffer.from(apiKey).toString('base64')}`
+}
+
+function createSandboxHttpError (status, message) {
+  if (status === 401 || status === 403) {
+    return new SandboxUnauthorizedError(message)
+  }
+  if (status === 404) {
+    return new SandboxNotFoundError(message)
+  }
+  if (status === 504) {
+    return new SandboxTimeoutError(message)
+  }
+  return new SandboxClientError(message)
+}
+
+function normalizeApiHost (host) {
+  if (!host.match(/^https?:\/\//)) {
+    return `https://${host}`
+  }
+  return host
+}
+
+function buildWebSocketEndpoint (apiHost, namespace, sandboxId) {
+  const url = new URL(apiHost)
+  url.protocol = url.protocol === 'http:' ? 'ws:' : 'wss:'
+  url.pathname = `/ws/v1/namespaces/${namespace}/sandbox/${sandboxId}/exec`
+  url.search = ''
+  return url.toString()
+}
+
+/**
+ * Reads Runtime credentials from environment variables, merged with any
+ * explicit overrides. Throws `SandboxInitializationError` for missing values.
+ *
+ * @param {object} overrides explicit credential overrides
+ * @returns {{ apiHost: string, namespace: string, apiKey: string }}
+ */
+function resolveCredentials (overrides = {}) {
+  const apiHost = overrides.apiHost || process.env.__OW_API_HOST
+  const namespace = overrides.namespace || process.env.__OW_NAMESPACE
+  const apiKey = overrides.auth || process.env.__OW_API_KEY
+
+  const missing = []
+  if (!apiHost) missing.push('apiHost')
+  if (!namespace) missing.push('namespace')
+  if (!apiKey) missing.push('auth')
+
+  if (missing.length > 0) {
+    throw new SandboxInitializationError(
+      `Missing required credentials: ${missing.join(', ')}. ` +
+      'Pass them explicitly or set __OW_API_HOST, __OW_NAMESPACE, __OW_API_KEY in the environment.'
+    )
+  }
+
+  return { apiHost: normalizeApiHost(apiHost), namespace, apiKey }
+}
+
+/**
+ * @param {string|object|undefined} size size name or spec object
+ * @returns {string} normalised size name
+ */
+function normalizeSize (size) {
+  if (!size) return 'MEDIUM'
+
+  if (typeof size === 'string' && SANDBOX_SIZES[size]) return size
+
+  if (typeof size === 'object') {
+    const entry = Object.entries(SANDBOX_SIZES).find(
+      ([, v]) => v.cpu === size.cpu && v.memory === size.memory && v.gpu === size.gpu
+    )
+    if (entry) return entry[0]
+  }
+
+  throw new SandboxClientError('Invalid sandbox size provided')
+}
+
+/**
+ * Thin fetch wrapper around the management REST API.
+ *
+ * Uses the Node.js global `fetch` (available since Node 18).
+ *
+ * @param {string} method HTTP method
+ * @param {string} url full request URL
+ * @param {string} apiKey API key for Basic auth
+ * @param {object|undefined} body request body (JSON-encoded when present)
+ * @returns {Promise<object>} parsed response JSON
+ */
+async function apiRequest (method, url, apiKey, body) {
+  const headers = { Authorization: buildAuthorizationHeader(apiKey) }
+  const init = { method, headers }
+
+  if (body !== undefined) {
+    headers['Content-Type'] = 'application/json'
+    init.body = JSON.stringify(body)
+  }
+
+  let response
+  try {
+    response = await fetch(url, init)
+  } catch (error) {
+    throw new SandboxClientError(`Sandbox API request failed: ${error.message}`)
+  }
+
+  if (!response.ok) {
+    const text = await response.text()
+    const detail = `${response.status}${text ? ` ${text}` : ''}`
+    throw createSandboxHttpError(response.status, detail)
+  }
+
+  return response.json()
+}
+
+module.exports = {
+  buildAuthorizationHeader,
+  createSandboxHttpError,
+  normalizeApiHost,
+  buildWebSocketEndpoint,
+  resolveCredentials,
+  normalizeSize,
+  apiRequest
+}