@adobe/aio-lib-sandbox 0.1.0-alpha.7 → 0.1.0-alpha.9

package/README.md

@@ -74,12 +74,19 @@ const { Sandbox } = require('@adobe/aio-lib-sandbox')
 const sandbox = await Sandbox.create({
   name:        'my-sandbox',
   type:        'cpu:default',
+  idleTimeout: 900,
   maxLifetime: 3600,
   ports:       [3000, 8080],
   envs:        { API_KEY: 'your-api-key' }
 })
 ```
 
+#### Sandbox lifetime model
+
+A sandbox is always deleted when `maxLifetime` has elapsed. It will also be deleted after the `idleTimeout` has elapsed, if there has been no activity.
+
+To keep a sandbox alive, send at least one command or check the status every `idleTimeout` seconds.
+
 ### Get Status
 
 ```js

package/package.json

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

package/src/Sandbox.js

@@ -23,7 +23,7 @@ const {
   normalizeSize,
   apiRequest
 } = require('./utils')
-const { SANDBOX_SIZES } = require('./constants')
+const { SANDBOX_SIZES, PROTOCOL_VERSION, API_PREFIX } = require('./constants')
 const { SandboxSocket } = require('./ws')
 
 /**
@@ -42,7 +42,9 @@ class Sandbox {
     this.status = options.status
     this.cluster = options.cluster
     this.region = options.region
+    this.idleTimeout = options.idleTimeout
     this.maxLifetime = options.maxLifetime
+    this.protocolVersion = options.protocolVersion || PROTOCOL_VERSION
 
     this.namespace = options.namespace
     this.apiHost = options.apiHost
@@ -70,7 +72,10 @@ class Sandbox {
    * @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 {number} [options.idleTimeout] seconds of inactivity before the sandbox is terminated
+   *   (default: 900, max: 10800). The idle timer resets on every WebSocket message or status-check
+   *   request.
+   * @param {number} [options.maxLifetime] maximum lifetime in seconds (default: 3600, max: 10800)
    * @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)
@@ -84,6 +89,7 @@ class Sandbox {
       name: options.name,
       size: normalizeSize(options.size),
       type: options.type || 'cpu:default',
+      idleTimeout: options.idleTimeout || 900,
       maxLifetime: options.maxLifetime || 3600
     }
 
@@ -93,7 +99,7 @@ class Sandbox {
     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}/sandboxes`
+    const url = `${creds.apiHost}${API_PREFIX}/namespaces/${creds.namespace}/sandboxes`
     const payload = await apiRequest('POST', url, creds.apiKey, body)
 
     const sandboxId = payload.sandboxId
@@ -105,7 +111,9 @@ class Sandbox {
       status: payload.status,
       cluster: payload.cluster,
       region: payload.region,
+      idleTimeout: payload.idleTimeout,
       maxLifetime: payload.maxLifetime,
+      protocolVersion: payload.protocolVersion || PROTOCOL_VERSION,
       previewUrls: parsePreviewUrls(payload.previewUrls),
       managementEndpoint: payload.managementEndpoint || null,
       namespace: creds.namespace,
@@ -124,17 +132,23 @@ class Sandbox {
    * Credentials are read from the environment automatically.
    * Any value passed explicitly in `options` overrides the environment.
    *
+   * Pass the management endpoint so the request is sent to the correct host;
+   * falls back to `options.apiHost` when omitted.
+   *
    * @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
+   * @param {string} [options.managementEndpoint] per-sandbox management endpoint returned by
+   *   `Sandbox.create()`. Falls back to `apiHost` otherwise.
    * @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}/sandboxes/${sandboxId}`
+    const base = options.managementEndpoint || creds.apiHost
+    const url = `${base}${API_PREFIX}/namespaces/${creds.namespace}/sandboxes/${sandboxId}`
     const payload = await apiRequest('GET', url, creds.apiKey)
 
     return new Sandbox({
@@ -143,7 +157,10 @@ class Sandbox {
       status: payload.status,
       cluster: payload.cluster,
       region: payload.region,
+      idleTimeout: payload.idleTimeout,
       maxLifetime: payload.maxLifetime,
+      protocolVersion: payload.protocolVersion || PROTOCOL_VERSION,
+      managementEndpoint: payload.managementEndpoint || options.managementEndpoint || null,
       previewUrls: parsePreviewUrls(payload.previewUrls),
       namespace: creds.namespace,
       apiHost: creds.apiHost,
@@ -161,6 +178,15 @@ class Sandbox {
     return SANDBOX_SIZES
   }
 
+  /**
+   * Sandbox wire protocol major bundled with this SDK.
+   *
+   * @type {string}
+   */
+  static get protocolVersion () {
+    return PROTOCOL_VERSION
+  }
+
   /**
    * Exposes `resolveCredentials` as a static helper (useful for testing).
    *
@@ -493,7 +519,7 @@ class Sandbox {
    */
   async destroy () {
     const base = this.managementEndpoint || this.apiHost
-    const url = `${base}/api/v1/namespaces/${this.namespace}/sandboxes/${this.id}`
+    const url = `${base}${API_PREFIX}/namespaces/${this.namespace}/sandboxes/${this.id}`
     this.ws?.beginIntentionalClose()
 
     let payload

package/src/constants.js

@@ -16,4 +16,7 @@ const SANDBOX_SIZES = Object.freeze({
   XLARGE: { cpu: '8000m', memory: '32Gi', gpu: 1 }
 })
 
-module.exports = { SANDBOX_SIZES }
+const PROTOCOL_VERSION = '1'
+const API_PREFIX = `/api/v${PROTOCOL_VERSION}`
+
+module.exports = { SANDBOX_SIZES, PROTOCOL_VERSION, API_PREFIX }

package/src/errors.js

@@ -28,6 +28,8 @@ class SandboxWebSocketError extends SandboxSDKError {}
 class SandboxCommandNotFoundError extends SandboxSDKError {}
 class SandboxPortNotProvisionedError extends SandboxSDKError {}
 class SandboxInvalidPortError extends SandboxClientError {}
+class ProtocolVersionMismatchError extends SandboxClientError {}
+class SandboxMalformedFrameError extends SandboxClientError {}
 
 module.exports = {
   SandboxSDKError,
@@ -39,5 +41,7 @@ module.exports = {
   SandboxWebSocketError,
   SandboxCommandNotFoundError,
   SandboxPortNotProvisionedError,
-  SandboxInvalidPortError
+  SandboxInvalidPortError,
+  ProtocolVersionMismatchError,
+  SandboxMalformedFrameError
 }

package/src/index.js

@@ -10,6 +10,7 @@ governing permissions and limitations under the License.
 */
 
 const Sandbox = require('./Sandbox')
+const { PROTOCOL_VERSION } = require('./constants')
 const {
   SandboxSDKError,
   SandboxInitializationError,
@@ -20,11 +21,14 @@ const {
   SandboxWebSocketError,
   SandboxCommandNotFoundError,
   SandboxPortNotProvisionedError,
-  SandboxInvalidPortError
+  SandboxInvalidPortError,
+  ProtocolVersionMismatchError,
+  SandboxMalformedFrameError
 } = require('./errors')
 
 module.exports = {
   Sandbox,
+  SANDBOX_PROTOCOL_VERSION: PROTOCOL_VERSION,
   SandboxSDKError,
   SandboxInitializationError,
   SandboxClientError,
@@ -34,5 +38,7 @@ module.exports = {
   SandboxWebSocketError,
   SandboxCommandNotFoundError,
   SandboxPortNotProvisionedError,
-  SandboxInvalidPortError
+  SandboxInvalidPortError,
+  ProtocolVersionMismatchError,
+  SandboxMalformedFrameError
 }

package/src/utils.js

@@ -16,7 +16,7 @@ const {
   SandboxUnauthorizedError,
   SandboxTimeoutError
 } = require('./errors')
-const { SANDBOX_SIZES } = require('./constants')
+const { SANDBOX_SIZES, API_PREFIX } = require('./constants')
 
 /**
  * Builds a Basic authorization header from a Runtime API key.
@@ -72,7 +72,7 @@ function normalizeApiHost (host) {
 function buildWebSocketEndpoint (apiHost, namespace, sandboxId) {
   const url = new URL(apiHost)
   url.protocol = url.protocol === 'http:' ? 'ws:' : 'wss:'
-  url.pathname = `/api/v1/namespaces/${namespace}/sandboxes/${sandboxId}/exec`
+  url.pathname = `${API_PREFIX}/namespaces/${namespace}/sandboxes/${sandboxId}/exec`
   url.search = ''
   return url.toString()
 }

package/src/ws.js

@@ -13,6 +13,8 @@ const WebSocket = require('ws')
 const {
   SandboxClientError,
   SandboxCommandNotFoundError,
+  ProtocolVersionMismatchError,
+  SandboxMalformedFrameError,
   SandboxUnauthorizedError,
   SandboxWebSocketError
 } = require('./errors')
@@ -355,6 +357,16 @@ class SandboxSocket {
         `Sandbox '${this.id}' rejected the WebSocket authentication token`
       )
     }
+    if (code === 4003) {
+      return new ProtocolVersionMismatchError(
+        `Sandbox '${this.id}' WebSocket protocol version does not match this SDK`
+      )
+    }
+    if (code === 4004) {
+      return new SandboxMalformedFrameError(
+        `Sandbox '${this.id}' rejected a malformed WebSocket frame`
+      )
+    }
     return new SandboxWebSocketError(
       `Sandbox '${this.id}' WebSocket closed with code ${code}`
     )

package/test/Sandbox.test.js

@@ -17,11 +17,13 @@ const {
   SandboxCommandNotFoundError,
   SandboxInitializationError,
   SandboxNotFoundError,
+  ProtocolVersionMismatchError,
   SandboxPortNotProvisionedError,
   SandboxInvalidPortError,
   SandboxTimeoutError,
   SandboxUnauthorizedError,
-  SandboxWebSocketError
+  SandboxWebSocketError,
+  SandboxMalformedFrameError
 } = require('../src/errors')
 
 jest.mock('ws')
@@ -199,6 +201,12 @@ describe('Sandbox', () => {
     })
   })
 
+  describe('protocolVersion', () => {
+    test('exposes the bundled sandbox protocol major', () => {
+      expect(Sandbox.protocolVersion).toBe('1')
+    })
+  })
+
   // -------------------------------------------------------------------------
   // Static factories
   // -------------------------------------------------------------------------
@@ -213,6 +221,7 @@ describe('Sandbox', () => {
           status: 'ready',
           token: 'tok-new',
           maxLifetime: 3600,
+          protocolVersion: '1',
           previewUrls: {
             3000: 'https://sb-new-3000.preview.example.net'
           }
@@ -236,6 +245,7 @@ describe('Sandbox', () => {
 
       expect(sandbox.id).toBe('sb-new')
       expect(sandbox.status).toBe('ready')
+      expect(sandbox.protocolVersion).toBe('1')
       expect(sandbox.previewUrls).toEqual(new Map([
         [3000, 'https://sb-new-3000.preview.example.net']
       ]))
@@ -342,6 +352,98 @@ describe('Sandbox', () => {
       await expect(Sandbox.create({ name: 'no-creds' })).rejects.toThrow(SandboxInitializationError)
     })
 
+    test('sends default idleTimeout 900 and maxLifetime 3600 when not specified', async () => {
+      const mockFetch = jest.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({
+          sandboxId: 'sb-defaults',
+          wsEndpoint: 'wss://runtime.example.net/api/v1/namespaces/ns/sandboxes/sb-defaults/exec',
+          status: 'ready',
+          token: 'tok-defaults',
+          idleTimeout: 900,
+          maxLifetime: 3600
+        })
+      })
+      global.fetch = mockFetch
+
+      const createPromise = Sandbox.create({
+        name: 'defaults-sandbox',
+        apiHost: 'https://runtime.example.net',
+        namespace: 'ns',
+        auth: 'uuid:key'
+      })
+
+      await new Promise(resolve => setImmediate(resolve))
+      sockets[0].open()
+      sockets[0].message({ type: 'auth.ok', sandboxId: 'sb-defaults' })
+      await createPromise
+
+      const body = JSON.parse(mockFetch.mock.calls[0][1].body)
+      expect(body.idleTimeout).toBe(900)
+      expect(body.maxLifetime).toBe(3600)
+    })
+
+    test('forwards explicit idleTimeout in the request body', async () => {
+      const mockFetch = jest.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({
+          sandboxId: 'sb-idle',
+          wsEndpoint: 'wss://runtime.example.net/api/v1/namespaces/ns/sandboxes/sb-idle/exec',
+          status: 'ready',
+          token: 'tok-idle',
+          idleTimeout: 1800,
+          maxLifetime: 3600
+        })
+      })
+      global.fetch = mockFetch
+
+      const createPromise = Sandbox.create({
+        name: 'idle-sandbox',
+        apiHost: 'https://runtime.example.net',
+        namespace: 'ns',
+        auth: 'uuid:key',
+        idleTimeout: 1800
+      })
+
+      await new Promise(resolve => setImmediate(resolve))
+      sockets[0].open()
+      sockets[0].message({ type: 'auth.ok', sandboxId: 'sb-idle' })
+      await createPromise
+
+      const body = JSON.parse(mockFetch.mock.calls[0][1].body)
+      expect(body.idleTimeout).toBe(1800)
+    })
+
+    test('stores idleTimeout from the create response on the instance', async () => {
+      const mockFetch = jest.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({
+          sandboxId: 'sb-store',
+          wsEndpoint: 'wss://runtime.example.net/api/v1/namespaces/ns/sandboxes/sb-store/exec',
+          status: 'ready',
+          token: 'tok-store',
+          idleTimeout: 1800,
+          maxLifetime: 3600
+        })
+      })
+      global.fetch = mockFetch
+
+      const createPromise = Sandbox.create({
+        name: 'store-sandbox',
+        apiHost: 'https://runtime.example.net',
+        namespace: 'ns',
+        auth: 'uuid:key',
+        idleTimeout: 1800
+      })
+
+      await new Promise(resolve => setImmediate(resolve))
+      sockets[0].open()
+      sockets[0].message({ type: 'auth.ok', sandboxId: 'sb-store' })
+      const sandbox = await createPromise
+
+      expect(sandbox.idleTimeout).toBe(1800)
+    })
+
     test('falls back to buildWebSocketEndpoint when wsEndpoint absent', async () => {
       const mockFetch = jest.fn().mockResolvedValue({
         ok: true,
@@ -379,7 +481,8 @@ describe('Sandbox', () => {
           sandboxId: 'sb-get',
           status: 'running',
           cluster: 'cluster-b',
-          region: 'va6'
+          region: 'va6',
+          protocolVersion: '1'
         })
       })
 
@@ -392,6 +495,27 @@ describe('Sandbox', () => {
       expect(sandbox.id).toBe('sb-get')
       expect(sandbox.status).toBe('running')
       expect(sandbox.cluster).toBe('cluster-b')
+      expect(sandbox.protocolVersion).toBe('1')
+    })
+
+    test('stores idleTimeout from the get response on the instance', async () => {
+      global.fetch = jest.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({
+          sandboxId: 'sb-get-idle',
+          status: 'running',
+          idleTimeout: 1200,
+          maxLifetime: 3600
+        })
+      })
+
+      const sandbox = await Sandbox.get('sb-get-idle', {
+        apiHost: 'https://runtime.example.net',
+        namespace: 'ns',
+        auth: 'uuid:key'
+      })
+
+      expect(sandbox.idleTimeout).toBe(1200)
     })
 
     test('throws SandboxNotFoundError on 404', async () => {
@@ -490,6 +614,22 @@ describe('Sandbox', () => {
       await expect(p).rejects.toThrow(SandboxUnauthorizedError)
     })
 
+    test('rejects on protocol mismatch close code 4003 with ProtocolVersionMismatchError', async () => {
+      const sandbox = new Sandbox(BASE_OPTIONS)
+      const p = sandbox.connect()
+      sockets[0].open()
+      sockets[0].closeWith(4003)
+      await expect(p).rejects.toThrow(ProtocolVersionMismatchError)
+    })
+
+    test('rejects on malformed frame close code 4004 with SandboxMalformedFrameError', async () => {
+      const sandbox = new Sandbox(BASE_OPTIONS)
+      const p = sandbox.connect()
+      sockets[0].open()
+      sockets[0].closeWith(4004)
+      await expect(p).rejects.toThrow(SandboxMalformedFrameError)
+    })
+
     test('rejects on unexpected socket close', async () => {
       const sandbox = new Sandbox(BASE_OPTIONS)
       const p = sandbox.connect()