From 55704bb5981529e4baa05011c31dd73300e38a6b Mon Sep 17 00:00:00 2001
From: perhapzz <perhapzz@users.noreply.github.com>
Date: Fri, 20 Mar 2026 12:04:48 +0000
Subject: [PATCH] feat(sdk/js): add OSSFS volume backend support

Add Alibaba Cloud OSSFS mount backend to the JavaScript/TypeScript
sandbox SDK, aligning it with the Python SDK implementation.

Changes:
- Add OSSFS interface to models/sandboxes.ts with full type definitions
  (bucket, endpoint, version, options, accessKeyId, accessKeySecret)
- Update Volume interface to include ossfs as a third backend option
- Update volume validation in sandbox.ts to check [host, pvc, ossfs]
- Export OSSFS type from index.ts
- Add 3 tests: OSSFS volume creation, no-backend rejection,
  multi-backend rejection

Partially addresses #476 (SDK parity gaps - OSSFS support)
---
 sdks/sandbox/javascript/src/index.ts          |  1 +
 .../javascript/src/models/sandboxes.ts        | 49 ++++++++++++-
 sdks/sandbox/javascript/src/sandbox.ts        |  6 +-
 .../javascript/tests/sandbox.create.test.mjs  | 73 +++++++++++++++++++
 4 files changed, 123 insertions(+), 6 deletions(-)

diff --git a/sdks/sandbox/javascript/src/index.ts b/sdks/sandbox/javascript/src/index.ts
index e0f98223..185e0bf5 100644
--- a/sdks/sandbox/javascript/src/index.ts
+++ b/sdks/sandbox/javascript/src/index.ts
@@ -39,6 +39,7 @@ export type {
   NetworkPolicy,
   NetworkRule,
   NetworkRuleAction,
+  OSSFS,
   PVC,
   RenewSandboxExpirationRequest,
   RenewSandboxExpirationResponse,
diff --git a/sdks/sandbox/javascript/src/models/sandboxes.ts b/sdks/sandbox/javascript/src/models/sandboxes.ts
index 52c74cbb..a8b80b49 100644
--- a/sdks/sandbox/javascript/src/models/sandboxes.ts
+++ b/sdks/sandbox/javascript/src/models/sandboxes.ts
@@ -92,12 +92,51 @@ export interface PVC extends Record<string, unknown> {
   claimName: string;
 }
 
+/**
+ * Alibaba Cloud OSS mount backend via ossfs.
+ *
+ * The runtime mounts a host-side OSS path under `storage.ossfs_mount_root`
+ * so the container sees the bucket contents at the specified mount path.
+ *
+ * In Docker runtime, OSSFS backend requires OpenSandbox Server to run on a Linux host with FUSE support.
+ */
+export interface OSSFS extends Record<string, unknown> {
+  /**
+   * OSS bucket name.
+   */
+  bucket: string;
+  /**
+   * OSS endpoint (e.g., "oss-cn-hangzhou.aliyuncs.com").
+   */
+  endpoint: string;
+  /**
+   * ossfs major version used by runtime mount integration.
+   * @default "2.0"
+   */
+  version?: "1.0" | "2.0";
+  /**
+   * Additional ossfs mount options.
+   *
+   * - `1.0`: mounts with `ossfs ... -o <option>`
+   * - `2.0`: mounts with `ossfs2 mount ... -c <config-file>` and encodes options as `--<option>` lines in the config file
+   */
+  options?: string[];
+  /**
+   * OSS access key ID for inline credentials mode.
+   */
+  accessKeyId: string;
+  /**
+   * OSS access key secret for inline credentials mode.
+   */
+  accessKeySecret: string;
+}
+
 /**
  * Storage mount definition for a sandbox.
  *
  * Each volume entry contains:
  * - A unique name identifier
- * - Exactly one backend (host, pvc) with backend-specific fields
+ * - Exactly one backend (host, pvc, ossfs) with backend-specific fields
  * - Common mount settings (mountPath, readOnly, subPath)
  */
 export interface Volume extends Record<string, unknown> {
@@ -106,13 +145,17 @@ export interface Volume extends Record<string, unknown> {
    */
   name: string;
   /**
-   * Host path bind mount backend (mutually exclusive with pvc).
+   * Host path bind mount backend (mutually exclusive with pvc, ossfs).
    */
   host?: Host;
   /**
-   * Kubernetes PVC mount backend (mutually exclusive with host).
+   * Kubernetes PVC mount backend (mutually exclusive with host, ossfs).
    */
   pvc?: PVC;
+  /**
+   * Alibaba Cloud OSSFS mount backend (mutually exclusive with host, pvc).
+   */
+  ossfs?: OSSFS;
   /**
    * Absolute path inside the container where the volume is mounted.
    */
diff --git a/sdks/sandbox/javascript/src/sandbox.ts b/sdks/sandbox/javascript/src/sandbox.ts
index 0cb8302a..0587a0d3 100644
--- a/sdks/sandbox/javascript/src/sandbox.ts
+++ b/sdks/sandbox/javascript/src/sandbox.ts
@@ -246,15 +246,15 @@ export class Sandbox {
     // Validate volumes: exactly one backend must be specified per volume
     if (opts.volumes) {
       for (const vol of opts.volumes) {
-        const backendsSpecified = [vol.host, vol.pvc].filter((b) => b !== undefined).length;
+        const backendsSpecified = [vol.host, vol.pvc, vol.ossfs].filter((b) => b !== undefined).length;
         if (backendsSpecified === 0) {
           throw new Error(
-            `Volume '${vol.name}' must specify exactly one backend (host, pvc), but none was provided.`
+            `Volume '${vol.name}' must specify exactly one backend (host, pvc, ossfs), but none was provided.`
           );
         }
         if (backendsSpecified > 1) {
           throw new Error(
-            `Volume '${vol.name}' must specify exactly one backend (host, pvc), but multiple were provided.`
+            `Volume '${vol.name}' must specify exactly one backend (host, pvc, ossfs), but multiple were provided.`
           );
         }
       }
diff --git a/sdks/sandbox/javascript/tests/sandbox.create.test.mjs b/sdks/sandbox/javascript/tests/sandbox.create.test.mjs
index c11b891a..1ae2f3f5 100644
--- a/sdks/sandbox/javascript/tests/sandbox.create.test.mjs
+++ b/sdks/sandbox/javascript/tests/sandbox.create.test.mjs
@@ -143,3 +143,76 @@ test("Sandbox creates and reuses egress service during sandbox lifecycle", async
   assert.equal(egressStackCalls[0].egressBaseUrl, `http://127.0.0.1:${DEFAULT_EGRESS_PORT}`);
   assert.deepEqual(egressStackCalls[0].endpointHeaders, { "x-port": String(DEFAULT_EGRESS_PORT) });
 });
+
+test("Sandbox.create passes OSSFS volume to request", async () => {
+  const { adapterFactory, recordedRequests } = createAdapterFactory();
+
+  await Sandbox.create({
+    adapterFactory,
+    connectionConfig: { domain: "http://127.0.0.1:8080" },
+    image: "python:3.12",
+    skipHealthCheck: true,
+    volumes: [
+      {
+        name: "oss-data",
+        ossfs: {
+          bucket: "my-bucket",
+          endpoint: "oss-cn-hangzhou.aliyuncs.com",
+          version: "2.0",
+          accessKeyId: "ak-id",
+          accessKeySecret: "ak-secret",
+        },
+        mountPath: "/data",
+        readOnly: false,
+      },
+    ],
+  });
+
+  assert.equal(recordedRequests.length, 1);
+  assert.equal(recordedRequests[0].volumes.length, 1);
+  assert.equal(recordedRequests[0].volumes[0].name, "oss-data");
+  assert.equal(recordedRequests[0].volumes[0].ossfs.bucket, "my-bucket");
+  assert.equal(recordedRequests[0].volumes[0].ossfs.endpoint, "oss-cn-hangzhou.aliyuncs.com");
+});
+
+test("Sandbox.create rejects volume with no backend", async () => {
+  const { adapterFactory } = createAdapterFactory();
+
+  await assert.rejects(
+    Sandbox.create({
+      adapterFactory,
+      connectionConfig: { domain: "http://127.0.0.1:8080" },
+      image: "python:3.12",
+      skipHealthCheck: true,
+      volumes: [{ name: "empty", mountPath: "/mnt" }],
+    }),
+    /must specify exactly one backend \(host, pvc, ossfs\)/
+  );
+});
+
+test("Sandbox.create rejects volume with multiple backends", async () => {
+  const { adapterFactory } = createAdapterFactory();
+
+  await assert.rejects(
+    Sandbox.create({
+      adapterFactory,
+      connectionConfig: { domain: "http://127.0.0.1:8080" },
+      image: "python:3.12",
+      skipHealthCheck: true,
+      volumes: [
+        {
+          name: "conflicting",
+          host: { path: "/tmp" },
+          ossfs: {
+            bucket: "b",
+            endpoint: "e",
+            accessKeyId: "id",
+            accessKeySecret: "secret",
+          },
+          mountPath: "/mnt",
+        },
+      ],
+    }),
+    /must specify exactly one backend \(host, pvc, ossfs\)/
+  );
+});