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

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.8",
   "description": "JavaScript SDK for Adobe Runtime Sandboxes",
   "main": "src/index.js",
   "license": "Apache-2.0",

package/src/Sandbox.js

@@ -42,6 +42,7 @@ class Sandbox {
     this.status = options.status
     this.cluster = options.cluster
     this.region = options.region
+    this.idleTimeout = options.idleTimeout
     this.maxLifetime = options.maxLifetime
 
     this.namespace = options.namespace
@@ -70,7 +71,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 +88,7 @@ class Sandbox {
       name: options.name,
       size: normalizeSize(options.size),
       type: options.type || 'cpu:default',
+      idleTimeout: options.idleTimeout || 900,
       maxLifetime: options.maxLifetime || 3600
     }
 
@@ -105,6 +110,7 @@ class Sandbox {
       status: payload.status,
       cluster: payload.cluster,
       region: payload.region,
+      idleTimeout: payload.idleTimeout,
       maxLifetime: payload.maxLifetime,
       previewUrls: parsePreviewUrls(payload.previewUrls),
       managementEndpoint: payload.managementEndpoint || null,
@@ -124,17 +130,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/v1/namespaces/${creds.namespace}/sandboxes/${sandboxId}`
     const payload = await apiRequest('GET', url, creds.apiKey)
 
     return new Sandbox({
@@ -143,7 +155,9 @@ class Sandbox {
       status: payload.status,
       cluster: payload.cluster,
       region: payload.region,
+      idleTimeout: payload.idleTimeout,
       maxLifetime: payload.maxLifetime,
+      managementEndpoint: payload.managementEndpoint || options.managementEndpoint || null,
       previewUrls: parsePreviewUrls(payload.previewUrls),
       namespace: creds.namespace,
       apiHost: creds.apiHost,

package/test/Sandbox.test.js

@@ -342,6 +342,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,
@@ -394,6 +486,26 @@ describe('Sandbox', () => {
       expect(sandbox.cluster).toBe('cluster-b')
     })
 
+    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 () => {
       global.fetch = jest.fn().mockResolvedValue({
         ok: false,