feat: support for creating sessions

openapi.json

@@ -599,6 +599,91 @@
         ],
         "title": "TokenUpdateResponse"
       },
+      "VMCreateSessionRequest": {
+        "properties": {
+          "permission": {
+            "description": "Permission level for the session",
+            "enum": ["read", "write"],
+            "example": "write",
+            "type": "string"
+          },
+          "session_id": {
+            "description": "Unique identifier for the session",
+            "example": "my-session-1",
+            "type": "string"
+          }
+        },
+        "required": ["session_id", "permission"],
+        "title": "VMCreateSessionRequest",
+        "type": "object"
+      },
+      "VMCreateSessionResponse": {
+        "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": {
+                  "capabilities": {
+                    "description": "List of capabilities granted to this session",
+                    "items": { "type": "string" },
+                    "type": "array"
+                  },
+                  "permissions": {
+                    "description": "Detailed permissions for this session",
+                    "type": "object"
+                  },
+                  "pitcher_token": {
+                    "description": "Token to authenticate with Pitcher",
+                    "type": "string"
+                  },
+                  "pitcher_url": {
+                    "description": "WebSocket URL to connect to Pitcher",
+                    "type": "string"
+                  },
+                  "user_workspace_path": {
+                    "description": "Path to the user's workspace in the VM",
+                    "type": "string"
+                  },
+                  "username": {
+                    "description": "The Linux username created for this session",
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "username",
+                  "pitcher_token",
+                  "user_workspace_path",
+                  "capabilities",
+                  "permissions",
+                  "pitcher_url"
+                ],
+                "type": "object"
+              }
+            },
+            "type": "object"
+          }
+        ],
+        "title": "VMCreateSessionResponse"
+      },
       "VMHibernateRequest": { "properties": {}, "title": "VMHibernateRequest" },
       "VMHibernateResponse": {
         "allOf": [
@@ -1275,6 +1360,49 @@
         "tags": ["vm"]
       }
     },
+    "/vm/{id}/sessions": {
+      "post": {
+        "callbacks": {},
+        "description": "Creates a new session on a running VM. A session represents an isolated Linux user, with their own container\nwhile their API token has specific permissions (currently, read or write).\nThe session is identified by a unique session ID, and the username is based on the session ID.\n\nThis endpoint requires the VM to be running. If the VM is not running, it will return a 404 error.\n",
+        "operationId": "vm/create_session",
+        "parameters": [
+          {
+            "description": "Sandbox ID",
+            "example": "new",
+            "in": "path",
+            "name": "id",
+            "required": true,
+            "schema": { "type": "string" }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/VMCreateSessionRequest"
+              }
+            }
+          },
+          "description": "VM Create Session Request",
+          "required": false
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/VMCreateSessionResponse"
+                }
+              }
+            },
+            "description": "VM Create Session Response"
+          }
+        },
+        "security": [{ "authorization": ["sandbox:read", "vm:manage"] }],
+        "summary": "Create a new session on a VM",
+        "tags": ["vm"]
+      }
+    },
     "/vm/{id}/shutdown": {
       "post": {
         "callbacks": {},

src/browser.ts

@@ -1,10 +1,20 @@
-import { initPitcherClient } from "@codesandbox/pitcher-client";
+import {
+  initPitcherClient,
+  PitcherManagerResponse,
+} from "@codesandbox/pitcher-client";
 
-import { SandboxWithoutClient } from "./sandbox";
+import { SandboxSession } from "./sandbox";
 import { DEFAULT_SUBSCRIPTIONS, type SandboxStartData } from "./sandbox-client";
+import { SessionConnectInfo } from "./sessions";
 
 export { SandboxStartData };
 
+function isStartData(
+  data: SandboxStartData | SessionConnectInfo
+): data is SandboxStartData {
+  return "bootup_type" in data;
+}
+
 /**
  * With this function you can connect to a sandbox from the browser.
  *
@@ -41,38 +51,59 @@ export { SandboxStartData };
  * ```
  */
 export async function connectToSandbox(
-  startInfo: SandboxStartData,
-): Promise<SandboxWithoutClient> {
+  startInfo: SandboxStartData | SessionConnectInfo
+): Promise<SandboxSession> {
+  const useStartData = isStartData(startInfo);
+
+  let requestPitcherInstance: () => Promise<PitcherManagerResponse>;
+  if (useStartData) {
+    requestPitcherInstance = async () => {
+      const data = startInfo;
+
+      return {
+        bootupType: data.bootup_type as "RUNNING" | "CLEAN" | "RESUME" | "FORK",
+        pitcherURL: data.pitcher_url,
+        workspacePath: data.workspace_path,
+        userWorkspacePath: data.user_workspace_path,
+        pitcherManagerVersion: data.pitcher_manager_version,
+        pitcherVersion: data.pitcher_version,
+        latestPitcherVersion: data.latest_pitcher_version,
+        pitcherToken: data.pitcher_token,
+        cluster: data.cluster,
+      };
+    };
+  } else {
+    requestPitcherInstance = async () => {
+      const data = startInfo;
+
+      return {
+        bootupType: "RESUME",
+        cluster: "session",
+        id: data.id,
+        latestPitcherVersion: "1.0.0-session",
+        pitcherManagerVersion: "1.0.0-session",
+        pitcherToken: data.pitcher_token,
+        pitcherURL: data.pitcher_url,
+        pitcherVersion: "1.0.0-session",
+        reconnectToken: "",
+        userWorkspacePath: data.user_workspace_path,
+        workspacePath: data.user_workspace_path,
+      };
+    };
+  }
+
   const pitcherClient = await initPitcherClient(
     {
       appId: "sdk",
       instanceId: startInfo.id,
       onFocusChange() {
         return () => {};
       },
-      requestPitcherInstance: async () => {
-        const data = startInfo;
-
-        return {
-          bootupType: data.bootup_type as
-            | "RUNNING"
-            | "CLEAN"
-            | "RESUME"
-            | "FORK",
-          pitcherURL: data.pitcher_url,
-          workspacePath: data.workspace_path,
-          userWorkspacePath: data.user_workspace_path,
-          pitcherManagerVersion: data.pitcher_manager_version,
-          pitcherVersion: data.pitcher_version,
-          latestPitcherVersion: data.latest_pitcher_version,
-          pitcherToken: data.pitcher_token,
-          cluster: data.cluster,
-        };
-      },
+      requestPitcherInstance,
       subscriptions: DEFAULT_SUBSCRIPTIONS,
     },
-    () => {},
+    () => {}
   );
 
-  return new SandboxWithoutClient(pitcherClient);
+  return new SandboxSession(pitcherClient);
 }

src/client/sdk.gen.ts

@@ -1,7 +1,7 @@
 // This file is auto-generated by @hey-api/openapi-ts
 
 import { createClient, createConfig, type OptionsLegacyParser } from '@hey-api/client-fetch';
-import type { MetaInfoError, MetaInfoResponse, WorkspaceCreateData, WorkspaceCreateError, WorkspaceCreateResponse2, TokenCreateData, TokenCreateError, TokenCreateResponse2, TokenUpdateData, TokenUpdateError, TokenUpdateResponse2, SandboxListData, SandboxListError, SandboxListResponse2, SandboxCreateData, SandboxCreateError, SandboxCreateResponse2, SandboxGetData, SandboxGetError, SandboxGetResponse2, SandboxForkData, SandboxForkError, SandboxForkResponse2, VmHibernateData, VmHibernateError, VmHibernateResponse, VmUpdateHibernationTimeoutData, VmUpdateHibernationTimeoutError, VmUpdateHibernationTimeoutResponse, VmShutdownData, VmShutdownError, VmShutdownResponse, VmUpdateSpecsData, VmUpdateSpecsError, VmUpdateSpecsResponse, VmStartData, VmStartError, VmStartResponse, VmUpdateSpecs2Data, VmUpdateSpecs2Error, VmUpdateSpecs2Response } from './types.gen';
+import type { MetaInfoError, MetaInfoResponse, WorkspaceCreateData, WorkspaceCreateError, WorkspaceCreateResponse2, TokenCreateData, TokenCreateError, TokenCreateResponse2, TokenUpdateData, TokenUpdateError, TokenUpdateResponse2, SandboxListData, SandboxListError, SandboxListResponse2, SandboxCreateData, SandboxCreateError, SandboxCreateResponse2, SandboxGetData, SandboxGetError, SandboxGetResponse2, SandboxForkData, SandboxForkError, SandboxForkResponse2, VmHibernateData, VmHibernateError, VmHibernateResponse, VmUpdateHibernationTimeoutData, VmUpdateHibernationTimeoutError, VmUpdateHibernationTimeoutResponse, VmCreateSessionData, VmCreateSessionError, VmCreateSessionResponse, VmShutdownData, VmShutdownError, VmShutdownResponse, VmUpdateSpecsData, VmUpdateSpecsError, VmUpdateSpecsResponse, VmStartData, VmStartError, VmStartResponse, VmUpdateSpecs2Data, VmUpdateSpecs2Error, VmUpdateSpecs2Response } from './types.gen';
 
 export const client = createClient(createConfig());
 
@@ -133,6 +133,22 @@ export const vmUpdateHibernationTimeout = <ThrowOnError extends boolean = false>
     });
 };
 
+/**
+ * Create a new session on a VM
+ * Creates a new session on a running VM. A session represents an isolated Linux user, with their own container
+ * while their API token has specific permissions (currently, read or write).
+ * The session is identified by a unique session ID, and the username is based on the session ID.
+ *
+ * This endpoint requires the VM to be running. If the VM is not running, it will return a 404 error.
+ *
+ */
+export const vmCreateSession = <ThrowOnError extends boolean = false>(options: OptionsLegacyParser<VmCreateSessionData, ThrowOnError>) => {
+    return (options?.client ?? client).post<VmCreateSessionResponse, VmCreateSessionError, ThrowOnError>({
+        ...options,
+        url: '/vm/{id}/sessions'
+    });
+};
+
 /**
  * Shutdown a VM
  * Stops a running VM, ending all currently running processes

src/client/types.gen.ts

@@ -316,6 +316,58 @@ export type TokenUpdateResponse = {
     };
 };
 
+export type VMCreateSessionRequest = {
+    /**
+     * Permission level for the session
+     */
+    permission: 'read' | 'write';
+    /**
+     * Unique identifier for the session
+     */
+    session_id: string;
+};
+
+/**
+ * Permission level for the session
+ */
+export type permission = 'read' | 'write';
+
+export type VMCreateSessionResponse = {
+    errors?: Array<((string | {
+    [key: string]: unknown;
+}))>;
+    success?: boolean;
+} & {
+    data?: {
+        /**
+         * List of capabilities granted to this session
+         */
+        capabilities: Array<(string)>;
+        /**
+         * Detailed permissions for this session
+         */
+        permissions: {
+            [key: string]: unknown;
+        };
+        /**
+         * Token to authenticate with Pitcher
+         */
+        pitcher_token: string;
+        /**
+         * WebSocket URL to connect to Pitcher
+         */
+        pitcher_url: string;
+        /**
+         * Path to the user's workspace in the VM
+         */
+        user_workspace_path: string;
+        /**
+         * The Linux username created for this session
+         */
+        username: string;
+    };
+};
+
 export type VMHibernateRequest = {
     [key: string]: unknown;
 };
@@ -594,6 +646,23 @@ export type VmUpdateHibernationTimeoutResponse = (VMUpdateHibernationTimeoutResp
 
 export type VmUpdateHibernationTimeoutError = unknown;
 
+export type VmCreateSessionData = {
+    /**
+     * VM Create Session Request
+     */
+    body?: VMCreateSessionRequest;
+    path: {
+        /**
+         * Sandbox ID
+         */
+        id: string;
+    };
+};
+
+export type VmCreateSessionResponse = (VMCreateSessionResponse);
+
+export type VmCreateSessionError = unknown;
+
 export type VmShutdownData = {
     /**
      * VM Shutdown Request