@adobe/aio-lib-sandbox 0.1.0-alpha.4 → 0.1.0-alpha.5

package/README.md

@@ -1,7 +1,10 @@
 # App Builder Sandbox SDK
 
 [![Version](https://img.shields.io/npm/v/@adobe/aio-lib-sandbox.svg)](https://npmjs.org/package/@adobe/aio-lib-sandbox)
+[![Downloads/week](https://img.shields.io/npm/dw/@adobe/aio-lib-sandbox.svg)](https://npmjs.org/package/@adobe/aio-lib-sandbox)
+![Node.js CI](https://github.com/adobe/aio-lib-sandbox/workflows/Node.js%20CI/badge.svg)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Codecov Coverage](https://img.shields.io/codecov/c/github/adobe/aio-lib-sandbox/main.svg?style=flat-square)](https://codecov.io/gh/adobe/aio-lib-sandbox/)
 ![Status](https://img.shields.io/badge/status-alpha-orange.svg)
 
 JavaScript SDK for Adobe Runtime Sandboxes.
@@ -23,7 +26,7 @@ npm install @adobe/aio-lib-sandbox@alpha
 
 ## Quickstart
 
-Inside a Runtime action, credentials are read automatically from the environment.
+Inside a Runtime action, no configuration is needed to use the SDK as credentials are read automatically from the environment.
 
 ```js
 const { Sandbox } = require('@adobe/aio-lib-sandbox')
@@ -72,6 +75,7 @@ const sandbox = await Sandbox.create({
   name:        'my-sandbox',
   type:        'cpu:default',
   maxLifetime: 3600,
+  ports:       [3000, 8080],
   envs:        { API_KEY: 'your-api-key' }
 })
 ```
@@ -93,6 +97,31 @@ console.log('exit code:', result.exitCode)
 
 > Note: Commands run in the `/workspace` directory by default, this is not configurable
 
+### Detached Commands
+
+Pass `detached: true` to run a long-lived background process.
+
+```js
+// Start a background server
+const command = await sandbox.exec('node server.js', { detached: true })
+
+// Wait for it to exit (e.g. after you stop it)
+const result = await command.wait()
+console.log('exit code:', result.exitCode)
+
+// Send a signal to stop it
+await command.kill()
+```
+
+If the process is still running and you need a handle to it from a different context, use `getCommand()` to re-attach by `execId`:
+
+```js
+const command = await sandbox.getCommand(execId, { onOutput: (data, stream) => process.stdout.write(data) })
+await command.wait()
+```
+
+> Note: Only 5 background processes are allowed to run at once currently.
+
 ### File Management
 
 ```js
@@ -146,11 +175,20 @@ await sandbox.destroy()
 
 ### Preview URLs
 
-Use preview URLs to get access to servers or web services running in a sandbox on a particular port: 
+Ports that should be publicly accessible must be declared at creation time via the `ports` array.
 
 ```js
-const url = await sandbox.getUrl({port: 3000})
-console.log("preview:", url)
+const sandbox = await Sandbox.create({
+  name:  'web-sandbox',
+  ports: [3000, 8080]
+})
+
+// Start a server inside the sandbox on the declared port
+await sandbox.exec('node server.js &', { timeout: 50_000 })
+
+// Retrieve the pre-provisioned preview URL — synchronous, no network call
+const url = sandbox.getUrl(3000)
+console.log('preview:', url)
 // https://sb-abc123-va6-0-xK3mPq2nAeB-3000.sandbox-adobeioruntime.net
 ```
 

package/RELEASING.md

@@ -0,0 +1,36 @@
+# Releasing
+
+Releases are managed with [`np`](https://github.com/sindresorhus/np)
+
+## Prerequisites
+
+Install `np`:
+
+```bash
+npm install --global np
+```
+
+Ensure your working tree is clean and you are on the `main` branch with the latest changes pulled:
+
+```bash
+git checkout main && git pull
+```
+
+## Steps
+
+1. **Run `np` with `--no-publish`** and the target version to bump the version, generate the changelog, create the git tag, and push without publishing to npm:
+
+   ```bash
+   np 0.1.0-alpha.5 --no-publish 
+   ```
+
+   Replace `0.1.0-alpha.5` with the appropriate next version.
+
+2. In the popup GitHub browser window, add the release version as the title and create the new release.
+
+3. Actual publishing should be handled by the `on-push-publish-to-npm.yml` workflow automatically.
+
+## Notes
+
+- This package is in **alpha**. Prefer pre-release version increments (`alpha.x`) until the API is stable.
+- If `np` complains about a dirty working tree or unpushed commits, resolve those before proceeding.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/aio-lib-sandbox",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.5",
   "description": "JavaScript SDK for Adobe Runtime Sandboxes",
   "main": "src/index.js",
   "license": "Apache-2.0",

package/src/Sandbox.js

@@ -13,7 +13,9 @@ const crypto = require('node:crypto')
 const {
   SandboxClientError,
   SandboxTimeoutError,
-  SandboxWebSocketError
+  SandboxWebSocketError,
+  SandboxPortNotProvisionedError,
+  SandboxInvalidPortError
 } = require('./errors')
 const {
   buildWebSocketEndpoint,
@@ -34,7 +36,7 @@ class Sandbox {
    * @param {object} options sandbox options
    * @private
    */
-  constructor (options) {
+  constructor(options) {
     this.id = options.id
     this.endpoint = options.endpoint
     this.status = options.status
@@ -46,7 +48,8 @@ class Sandbox {
     this.apiHost = options.apiHost
     this.apiKey = options.apiKey
     this.token = options.token
-    this.publicUrlTemplate = options.publicUrlTemplate || null
+    // previewUrls is a Map<number, string> of (port → URL) returned by the server.
+    this.previewUrls = options.previewUrls || new Map()
     this.managementEndpoint = options.managementEndpoint || null
     this.ws = null
   }
@@ -68,11 +71,12 @@ class Sandbox {
    * @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 {number[]} [options.ports] TCP ports to expose via preview URLs (default: `[]`)
    * @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 = {}) {
+  static async create(options = {}) {
     console.warn('[aio-lib-sandbox] alpha — APIs may change without notice')
     const creds = resolveCredentials(options)
 
@@ -87,6 +91,7 @@ class Sandbox {
     if (options.region !== undefined) body.region = options.region
     if (options.envs !== undefined) body.envs = options.envs
     if (options.policy !== undefined) body.policy = options.policy
+    if (options.ports !== undefined) body.ports = options.ports
 
     const url = `${creds.apiHost}/api/v1/namespaces/${creds.namespace}/sandbox`
     const payload = await apiRequest('POST', url, creds.apiKey, body)
@@ -101,7 +106,7 @@ class Sandbox {
       cluster: payload.cluster,
       region: payload.region,
       maxLifetime: payload.maxLifetime,
-      publicUrlTemplate: payload.publicUrlTemplate || null,
+      previewUrls: parsePreviewUrls(payload.previewUrls),
       managementEndpoint: payload.managementEndpoint || null,
       namespace: creds.namespace,
       apiHost: creds.apiHost,
@@ -126,7 +131,7 @@ class Sandbox {
    * @param {string} [options.auth] Runtime API key
    * @returns {Promise<Sandbox>} sandbox instance with `status` populated (not WebSocket-connected)
    */
-  static async get (sandboxId, options = {}) {
+  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}`
@@ -139,6 +144,7 @@ class Sandbox {
       cluster: payload.cluster,
       region: payload.region,
       maxLifetime: payload.maxLifetime,
+      previewUrls: parsePreviewUrls(payload.previewUrls),
       namespace: creds.namespace,
       apiHost: creds.apiHost,
       apiKey: creds.apiKey,
@@ -151,7 +157,7 @@ class Sandbox {
    *
    * @type {object}
    */
-  static get sizes () {
+  static get sizes() {
     return SANDBOX_SIZES
   }
 
@@ -161,7 +167,7 @@ class Sandbox {
    * @param {object} overrides credential overrides
    * @returns {{ apiHost: string, namespace: string, apiKey: string }}
    */
-  static resolveCredentials (overrides = {}) {
+  static resolveCredentials(overrides = {}) {
     return resolveCredentials(overrides)
   }
 
@@ -171,7 +177,7 @@ class Sandbox {
    * @param {string|object|undefined} size
    * @returns {string}
    */
-  static normalizeSize (size) {
+  static normalizeSize(size) {
     return normalizeSize(size)
   }
 
@@ -184,7 +190,7 @@ class Sandbox {
    *
    * @returns {Promise<void>}
    */
-  connect () {
+  connect() {
     if (!this.ws) {
       this.ws = new SandboxSocket({
         id: this.id,
@@ -202,62 +208,110 @@ class Sandbox {
   /**
    * Executes a command inside the sandbox.
    *
-   * Returns a Promise (with an `execId` property) that resolves to
-   * `{ execId, stdout, stderr, exitCode }` when the command completes.
+   * `options.timeout` is not supported with `options.detached: true`.
    *
    * @param {string} command command to run
    * @param {object} [options] execution options
-   * @param {number} [options.timeout] timeout in milliseconds
+   * @param {number} [options.timeout] timeout in milliseconds (foreground only)
+   * @param {boolean} [options.detached] when true, run as a detached background process
    * @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}>}
+   * @returns {Promise}
    */
-  exec (command, options = {}) {
+  exec(command, options = {}) {
     try {
       this.ensureOpen()
     } catch (error) {
       return Promise.reject(error)
     }
 
+    if (options.detached && options.timeout) {
+      return Promise.reject(new SandboxClientError(
+        'cannot set a timeout for a detached command'
+      ))
+    }
+
     const execId = `exec-${crypto.randomBytes(12).toString('hex')}`
-    let timeoutHandle
+    const promise = this.sendExecFrameAndAwaitResponse(execId, command, options)
+    promise.execId = execId
+    return promise
+  }
+
+  /**
+   * @param {string} execId
+   * @param {string} command
+   * @param {object} options
+   * @private
+   */
+  async sendExecFrameAndAwaitResponse(execId, command, options) {
+    const detached = !!options.detached
+    const frame = { type: 'exec.run', execId, command, ...(detached && { detached: true }) }
+
+    const { ackPromise, waitPromise } = this.ws.sendExec(execId, frame, {
+      detached,
+      onOutput: options.onOutput
+    })
+
+    if (options.timeout) {
+      this.ws.setExecTimeout(execId, this.scheduleTimeout(execId, command, options.timeout))
+    }
+
+    if (options.stdin !== undefined) {
+      this.writeStdin(execId, options.stdin)
+      this.closeStdin(execId)
+    }
+
+    const result = await ackPromise
 
-    const execPromise = new Promise((resolve, reject) => {
-      this.ws.pendingExecs.set(execId, {
+    if (!detached) return result
+
+    const { pid, startedAt } = result
+    return {
+      execId,
+      pid,
+      startedAt,
+      detached: true,
+      wait: () => waitPromise,
+      writeStdin: (data) => this.writeStdin(execId, data),
+      closeStdin: () => this.closeStdin(execId),
+      kill: (signal) => this.kill(execId, signal)
+    }
+  }
+
+  /**
+   * Re-attaches to a detached command that is still running in the sandbox.
+   *
+   * @param {string} execId the execId returned by the original `exec()` call
+   * @param {object} [options] re-attach options
+   * @param {function} [options.onOutput] callback called with `(data, stream)` for live output
+   * @returns {Promise<{execId, command, pid, startedAt, detached, wait, kill, writeStdin, closeStdin}>}
+   */
+  getCommand(execId, options = {}) {
+    try {
+      this.ensureOpen()
+    } catch (error) {
+      return Promise.reject(error)
+    }
+
+    const getPromise = new Promise((resolve, reject) => {
+      this.ws.pendingGetOps.set(execId, {
         resolve,
         reject,
-        stdout: '',
-        stderr: '',
-        onOutput: options.onOutput,
-        timeout: undefined
+        onOutput: options.onOutput || null,
+        sandbox: this
       })
-
-      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)
-      }
+      this.sendFrame({ type: 'exec.get', execId })
     } catch (error) {
-      this.ws.rejectExec(execId, new SandboxWebSocketError(
-        `Could not send exec frame: ${error.message}`
+      this.ws.pendingGetOps.delete(execId)
+      return Promise.reject(new SandboxWebSocketError(
+        `Could not send exec.get frame: ${error.message}`
       ))
     }
 
-    return execPromise
+    return getPromise
   }
 
   /**
@@ -266,7 +320,7 @@ class Sandbox {
    * @param {string} execId execution id
    * @param {string} [signal] signal to deliver (default: `'SIGTERM'`)
    */
-  kill (execId, signal = 'SIGTERM') {
+  kill(execId, signal = 'SIGTERM') {
     this.ensureOpen()
     this.sendFrame({ type: 'exec.kill', execId, signal })
   }
@@ -278,7 +332,7 @@ class Sandbox {
    * @param {string} execId execution id from `exec()`
    * @param {string|Buffer} data data to write
    */
-  writeStdin (execId, data) {
+  writeStdin(execId, data) {
     this.ensureOpen()
     const frame = { type: 'exec.input', execId }
     if (Buffer.isBuffer(data)) {
@@ -296,7 +350,7 @@ class Sandbox {
    *
    * @param {string} execId execution id from `exec()`
    */
-  closeStdin (execId) {
+  closeStdin(execId) {
     this.ensureOpen()
     this.sendFrame({ type: 'exec.endInput', execId })
   }
@@ -311,7 +365,7 @@ class Sandbox {
    * @param {string} path path inside the sandbox
    * @returns {Promise<string>} file contents as a UTF-8 string
    */
-  readFile (path) {
+  readFile(path) {
     try {
       this.ensureOpen()
     } catch (error) {
@@ -341,7 +395,7 @@ class Sandbox {
    * @param {string|Buffer} content file contents
    * @returns {Promise<{path: string, size: number, ok: boolean}>} write confirmation
    */
-  writeFile (path, content) {
+  writeFile(path, content) {
     try {
       this.ensureOpen()
     } catch (error) {
@@ -374,7 +428,7 @@ class Sandbox {
    * @param {string} path directory path inside the sandbox
    * @returns {Promise<Array<{name: string, type: string, size?: number}>>} directory entries
    */
-  listFiles (path) {
+  listFiles(path) {
     try {
       this.ensureOpen()
     } catch (error) {
@@ -404,30 +458,29 @@ class Sandbox {
   /**
    * 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
+   * This is a synchronous local lookup against the `previewUrls` map returned
+   * by the server at create time. The URL is opaque — do not parse or reconstruct it.
+   *
+   * @param {number} port port number (1–65535)
+   * @returns {string} public preview URL
+   * @throws {SandboxInvalidPortError} when `port` is not an integer in the
+   *   range 1–65535
+   * @throws {SandboxPortNotProvisionedError} when `port` is valid but was not
+   *   declared in `create({ ports })`
    */
-  async getUrl ({ port, protocol } = {}) {
-    if (!this.publicUrlTemplate) {
-      throw new SandboxClientError(
-        `Cannot get URL for sandbox '${this.id}': publicUrlTemplate is not available`
-      )
-    }
-
+  getUrl (port) {
     if (!Number.isInteger(port) || port < 1 || port > 65535) {
-      throw new SandboxClientError(
+      throw new SandboxInvalidPortError(
         `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}://`)
+    const url = this.previewUrls.get(port)
+    if (url === undefined) {
+      throw new SandboxPortNotProvisionedError(
+        `Port ${port} was not provisioned for sandbox '${this.id}'. ` +
+        "Declare it in create({ ports: [...] }) to get a preview URL."
+      )
     }
 
     return url
@@ -438,10 +491,18 @@ class Sandbox {
    *
    * @returns {Promise<object>} destroy response payload
    */
-  async destroy () {
+  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.ws?.beginIntentionalClose()
+
+    let payload
+    try {
+      payload = await apiRequest('DELETE', url, this.apiKey)
+    } catch (error) {
+      this.ws?.cancelIntentionalClose()
+      throw error
+    }
 
     this.status = payload.status || this.status
     this.ws?.close()
@@ -452,16 +513,63 @@ class Sandbox {
   // Private helpers
   // ------------------------------------------------------------------
 
-  ensureOpen () {
+  /**
+   * Schedules a timeout that kills `execId` and rejects its pending entry.
+   *
+   * @param {string} execId
+   * @param {string} command human-readable command string (for the error message)
+   * @param {number} ms timeout in milliseconds
+   * @returns {ReturnType<setTimeout>} the timer handle (stored on the entry for cancellation)
+   */
+  scheduleTimeout(execId, command, ms) {
+    return setTimeout(() => {
+      try {
+        this.kill(execId)
+      } catch (_) {
+        // ignore errors
+      }
+      
+      this.ws.rejectExec(execId, new SandboxTimeoutError(
+        `Command '${command}' exceeded timeout of ${ms}ms`
+      ))
+    }, ms)
+  }
+
+  ensureOpen() {
     if (!this.ws) {
       throw new SandboxWebSocketError(`Sandbox '${this.id}' is not connected`)
     }
     this.ws.ensureOpen()
   }
 
-  sendFrame (frame) {
+  sendFrame(frame) {
     this.ws.send(frame)
   }
 }
 
+/**
+ * Parses the `previewUrls` JSON object returned by the server into a
+ * `Map<number, string>`. String keys (port numbers) are converted to integers.
+ * The URL values are treated as opaque — not parsed or reconstructed.
+ *
+ * Returns an empty Map when the server response omits `previewUrls` (fail-closed:
+ * every `getUrl()` call will throw `SandboxPortNotProvisionedError`).
+ *
+ * @param {object|null|undefined} raw the `previewUrls` field from the API response
+ * @returns {Map<number, string>}
+ */
+function parsePreviewUrls (raw) {
+  if (!raw || typeof raw !== 'object') {
+    return new Map()
+  }
+  const map = new Map()
+  for (const [key, value] of Object.entries(raw)) {
+    const port = Number(key)
+    if (Number.isInteger(port) && port >= 1 && port <= 65535 && typeof value === 'string') {
+      map.set(port, value)
+    }
+  }
+  return map
+}
+
 module.exports = Sandbox

package/src/errors.js

@@ -25,6 +25,9 @@ class SandboxNotFoundError extends SandboxSDKError {}
 class SandboxUnauthorizedError extends SandboxSDKError {}
 class SandboxTimeoutError extends SandboxSDKError {}
 class SandboxWebSocketError extends SandboxSDKError {}
+class SandboxCommandNotFoundError extends SandboxSDKError {}
+class SandboxPortNotProvisionedError extends SandboxSDKError {}
+class SandboxInvalidPortError extends SandboxClientError {}
 
 module.exports = {
   SandboxSDKError,
@@ -33,5 +36,8 @@ module.exports = {
   SandboxNotFoundError,
   SandboxUnauthorizedError,
   SandboxTimeoutError,
-  SandboxWebSocketError
+  SandboxWebSocketError,
+  SandboxCommandNotFoundError,
+  SandboxPortNotProvisionedError,
+  SandboxInvalidPortError
 }

package/src/index.js

@@ -17,7 +17,10 @@ const {
   SandboxNotFoundError,
   SandboxUnauthorizedError,
   SandboxTimeoutError,
-  SandboxWebSocketError
+  SandboxWebSocketError,
+  SandboxCommandNotFoundError,
+  SandboxPortNotProvisionedError,
+  SandboxInvalidPortError
 } = require('./errors')
 
 module.exports = {
@@ -28,5 +31,8 @@ module.exports = {
   SandboxNotFoundError,
   SandboxUnauthorizedError,
   SandboxTimeoutError,
-  SandboxWebSocketError
+  SandboxWebSocketError,
+  SandboxCommandNotFoundError,
+  SandboxPortNotProvisionedError,
+  SandboxInvalidPortError
 }