New best practices release (#191)

* fix: Default to public-hosts privacy. Unlisted is a security concern. Will not break default behavior as end users should never open Sandboxes in workspace of SDK user

* fix: Warn about creating sandboxes from sandboxes

* chore: deprecate automatic lifecycle management related config

* fix: make user (session) creation optional and deprecate it

* fix: properly handle optional id when getting session

* fix: ignore files should be part of template

* fix: deprecate hibernation timeout

* feat: delete method to delete Sandboxes

* chore: remove deprecation indications, we'll rely on docs for now

Author: christianalfoni

openapi.json

@@ -1062,6 +1062,16 @@
             "enum": ["browser", "vm"],
             "type": "string"
           },
+          "settings": {
+            "description": "Sandbox settings.",
+            "properties": {
+              "use_pint": {
+                "description": "Whether to use Pint for the sandbox.",
+                "type": "boolean"
+              }
+            },
+            "type": "object"
+          },
           "tags": {
             "default": [],
             "description": "List of string tags to apply to the sandbox. Only the first ten will be used. Defaults to no tags.",
@@ -1217,6 +1227,33 @@
         "title": "TokenCreateResponse",
         "type": "object"
       },
+      "VMDeleteResponse": {
+        "allOf": [
+          {
+            "properties": {
+              "errors": {
+                "items": {
+                  "oneOf": [
+                    { "type": "string" },
+                    { "additionalProperties": true, "type": "object" }
+                  ],
+                  "title": "Error"
+                },
+                "type": "array"
+              },
+              "success": { "type": "boolean" }
+            },
+            "title": "Response",
+            "type": "object"
+          },
+          {
+            "properties": { "data": { "properties": {}, "type": "object" } },
+            "type": "object"
+          }
+        ],
+        "title": "VMDeleteResponse",
+        "type": "object"
+      },
       "TemplateCreateResponse": {
         "allOf": [
           {
@@ -2234,6 +2271,36 @@
         "tags": ["vm"]
       }
     },
+    "/vm/{id}": {
+      "delete": {
+        "callbacks": {},
+        "description": "Deletes a VM, permanently removing it from the system.\n\nThis endpoint can only be used on VMs that belong to your team's workspace.\nDeleting a VM is irreversible and will permanently delete all data associated with it.\n",
+        "operationId": "vm/delete",
+        "parameters": [
+          {
+            "description": "Sandbox ID",
+            "example": "new",
+            "in": "path",
+            "name": "id",
+            "required": true,
+            "schema": { "type": "string" }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/VMDeleteResponse" }
+              }
+            },
+            "description": "VM Delete Response"
+          }
+        },
+        "security": [{ "authorization": ["vm:manage"] }],
+        "summary": "Delete a VM",
+        "tags": ["vm"]
+      }
+    },
     "/vm/{id}/hibernate": {
       "post": {
         "callbacks": {},
@@ -2604,6 +2671,6 @@
     }
   },
   "security": [],
-  "servers": [{ "url": "https://api.codesandbox.io", "variables": {} }],
+  "servers": [{ "url": "https://api.codesandbox.stream", "variables": {} }],
   "tags": []
 }

src/API.ts

@@ -19,6 +19,7 @@ import {
   vmListClusters,
   vmListRunningVms,
   vmCreateTag,
+  vmDelete,
   vmHibernate,
   vmUpdateHibernationTimeout,
   vmCreateSession,
@@ -42,6 +43,7 @@ import type {
   TemplatesCreateData,
   VmAssignTagAliasData,
   VmCreateTagData,
+  VmDeleteData,
   VmHibernateData,
   VmUpdateHibernationTimeoutData,
   VmCreateSessionData,
@@ -247,6 +249,14 @@ export class API {
     return handleResponse(response, "Failed to create VM tag");
   }
 
+  async deleteVm(id: string) {
+    const response = await vmDelete({
+      client: this.client,
+      path: { id },
+    });
+    return handleResponse(response, `Failed to delete VM ${id}`);
+  }
+
   async hibernate(id: string, data?: VmHibernateData["body"]) {
     return retryWithDelay(
       async () => {

src/Sandbox.ts

@@ -178,10 +178,11 @@ export class Sandbox {
     pitcherManagerResponse: PitcherManagerResponse,
     customSession?: SessionCreateOptions
   ): Promise<SandboxSession> {
-    if (!customSession) {
+    if (!customSession || !customSession.id) {
       return {
         sandboxId: this.id,
         bootupType: this.bootupType,
+        hostToken: customSession?.hostToken,
         cluster: this.cluster,
         latestPitcherVersion: pitcherManagerResponse.latestPitcherVersion,
         pitcherManagerVersion: pitcherManagerResponse.pitcherManagerVersion,

src/Sandboxes.ts

@@ -60,40 +60,6 @@ export class Sandboxes {
     );
   }
 
-  private async createTemplateSandbox(
-    opts?: CreateSandboxOpts & StartSandboxOpts
-  ) {
-    const templateId = opts?.id || this.defaultTemplateId;
-    const privacy = opts?.privacy || "unlisted";
-    const tags = opts?.tags || ["sdk"];
-    let path = opts?.path || "/SDK";
-
-    if (!path.startsWith("/")) {
-      path = "/" + path;
-    }
-
-    // Always add the "sdk" tag to the sandbox, this is used to identify sandboxes created by the SDK.
-    const tagsWithSdk = tags.includes("sdk") ? tags : [...tags, "sdk"];
-
-    const { mappedPrivacy, privatePreview } = mapPrivacyForApi(privacy);
-
-    const sandbox = await this.api.forkSandbox(templateId, {
-      privacy: mappedPrivacy,
-      title: opts?.title,
-      description: opts?.description,
-      tags: tagsWithSdk,
-      path,
-      private_preview: privatePreview,
-    });
-
-    const startResponse = await this.api.startVm(
-      sandbox.id,
-      { ...getStartOptions(opts), retryDelay: 200 } // Keep 200ms delay for creation
-    );
-
-    return new Sandbox(sandbox.id, this.api, startResponse, this.tracer);
-  }
-
   /**
    * Resume a sandbox.
    *
@@ -129,6 +95,20 @@ export class Sandboxes {
     );
   }
 
+  /**
+   * Permanently deletes a sandbox. This action is irreversible and will delete all data associated with the sandbox.
+   * The sandbox must belong to your team's workspace to be deleted.
+   */
+  async delete(sandboxId: string): Promise<void> {
+    return this.withSpan(
+      "sandboxes.delete",
+      { "sandbox.id": sandboxId },
+      async () => {
+        await this.api.deleteVm(sandboxId);
+      }
+    );
+  }
+
   /**
    * Forks a sandbox. This will create a new sandbox from the given sandbox.
    * @deprecated This will be removed shortly to avoid having multiple ways of doing the same thing
@@ -198,10 +178,38 @@ export class Sandboxes {
       "sandboxes.create",
       {
         "template.id": opts?.id || this.defaultTemplateId,
-        "sandbox.privacy": opts?.privacy || "unlisted",
+        "sandbox.privacy": opts?.privacy || "public-hosts",
       },
       async () => {
-        return this.createTemplateSandbox(opts);
+        const templateId = opts?.id || this.defaultTemplateId;
+        const privacy = opts?.privacy || "public-hosts";
+        const tags = opts?.tags || ["sdk"];
+        let path = opts?.path || "/SDK";
+
+        if (!path.startsWith("/")) {
+          path = "/" + path;
+        }
+
+        // Always add the "sdk" tag to the sandbox, this is used to identify sandboxes created by the SDK.
+        const tagsWithSdk = tags.includes("sdk") ? tags : [...tags, "sdk"];
+
+        const { mappedPrivacy, privatePreview } = mapPrivacyForApi(privacy);
+
+        const sandbox = await this.api.forkSandbox(templateId, {
+          privacy: mappedPrivacy,
+          title: opts?.title,
+          description: opts?.description,
+          tags: tagsWithSdk,
+          path,
+          private_preview: privatePreview,
+        });
+
+        const startResponse = await this.api.startVm(
+          sandbox.id,
+          { ...getStartOptions(opts), retryDelay: 200 } // Keep 200ms delay for creation
+        );
+
+        return new Sandbox(sandbox.id, this.api, startResponse, this.tracer);
       }
     );
   }

src/api-clients/client-rest-container/client.gen.ts

@@ -1,5 +1,5 @@
 // This file is auto-generated by @hey-api/openapi-ts
 
-import { createClient, createConfig } from "@hey-api/client-fetch";
+import { createClient, createConfig } from '@hey-api/client-fetch';
 
-export const client = createClient(createConfig());
+export const client = createClient(createConfig());

src/api-clients/client-rest-container/index.ts

@@ -1,3 +1,3 @@
 // This file is auto-generated by @hey-api/openapi-ts
-export * from "./types.gen";
-export * from "./sdk.gen";
+export * from './types.gen';
+export * from './sdk.gen';

src/api-clients/client-rest-container/sdk.gen.ts

@@ -1,46 +1,29 @@
 // This file is auto-generated by @hey-api/openapi-ts
 
-import type {
-  Options as ClientOptions,
-  TDataShape,
-  Client,
-} from "@hey-api/client-fetch";
-import type {
-  ContainerSetupData,
-  ContainerSetupResponse,
-  ContainerSetupError,
-} from "./types.gen";
-import { client as _heyApiClient } from "./client.gen";
+import type { Options as ClientOptions, TDataShape, Client } from '@hey-api/client-fetch';
+import type { ContainerSetupData, ContainerSetupResponse, ContainerSetupError } from './types.gen';
+import { client as _heyApiClient } from './client.gen';
 
-export type Options<
-  TData extends TDataShape = TDataShape,
-  ThrowOnError extends boolean = boolean
-> = ClientOptions<TData, ThrowOnError> & {
-  /**
-   * You can provide a client instance returned by `createClient()` instead of
-   * individual options. This might be also useful if you want to implement a
-   * custom client.
-   */
-  client?: Client;
+export type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean> = ClientOptions<TData, ThrowOnError> & {
+    /**
+     * You can provide a client instance returned by `createClient()` instead of
+     * individual options. This might be also useful if you want to implement a
+     * custom client.
+     */
+    client?: Client;
 };
 
 /**
  * Setup container
  * Set up a new container based on a template
  */
-export const containerSetup = <ThrowOnError extends boolean = false>(
-  options: Options<ContainerSetupData, ThrowOnError>
-) => {
-  return (options.client ?? _heyApiClient).post<
-    ContainerSetupResponse,
-    ContainerSetupError,
-    ThrowOnError
-  >({
-    url: "/container/setup",
-    ...options,
-    headers: {
-      "Content-Type": "application/json",
-      ...options?.headers,
-    },
-  });
-};
+export const containerSetup = <ThrowOnError extends boolean = false>(options: Options<ContainerSetupData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).post<ContainerSetupResponse, ContainerSetupError, ThrowOnError>({
+        url: '/container/setup',
+        ...options,
+        headers: {
+            'Content-Type': 'application/json',
+            ...options?.headers
+        }
+    });
+};