feat(sdks): ossfs support (opensandbox-group#563)

Author: ninan-nn

sdks/sandbox/csharp/src/OpenSandbox/Models/Sandboxes.cs

@@ -137,9 +137,51 @@ public class PVC
     public required string ClaimName { get; set; }
 }
 
+/// <summary>
+/// Alibaba Cloud OSS mount backend via ossfs.
+/// </summary>
+public class OSSFS
+{
+    /// <summary>
+    /// Gets or sets the OSS bucket name.
+    /// </summary>
+    [JsonPropertyName("bucket")]
+    public required string Bucket { get; set; }
+
+    /// <summary>
+    /// Gets or sets the OSS endpoint.
+    /// </summary>
+    [JsonPropertyName("endpoint")]
+    public required string Endpoint { get; set; }
+
+    /// <summary>
+    /// Gets or sets the OSS access key ID for inline credentials mode.
+    /// </summary>
+    [JsonPropertyName("accessKeyId")]
+    public required string AccessKeyId { get; set; }
+
+    /// <summary>
+    /// Gets or sets the OSS access key secret for inline credentials mode.
+    /// </summary>
+    [JsonPropertyName("accessKeySecret")]
+    public required string AccessKeySecret { get; set; }
+
+    /// <summary>
+    /// Gets or sets the ossfs major version used by runtime mount integration. Defaults to "2.0".
+    /// </summary>
+    [JsonPropertyName("version")]
+    public string Version { get; set; } = "2.0";
+
+    /// <summary>
+    /// Gets or sets additional ossfs mount options.
+    /// </summary>
+    [JsonPropertyName("options")]
+    public IReadOnlyList<string>? Options { get; set; }
+}
+
 /// <summary>
 /// Storage mount definition for sandbox creation.
-/// Exactly one backend (Host or PVC) should be provided per volume.
+/// Exactly one backend (Host, PVC, or OSSFS) should be provided per volume.
 /// </summary>
 public class Volume
 {
@@ -161,6 +203,12 @@ public class Volume
     [JsonPropertyName("pvc")]
     public PVC? Pvc { get; set; }
 
+    /// <summary>
+    /// Gets or sets the OSSFS backend configuration.
+    /// </summary>
+    [JsonPropertyName("ossfs")]
+    public OSSFS? Ossfs { get; set; }
+
     /// <summary>
     /// Gets or sets the absolute mount path inside the container.
     /// </summary>

sdks/sandbox/csharp/tests/OpenSandbox.Tests/ModelsTests.cs

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+using System.Text.Json;
 using FluentAssertions;
 using OpenSandbox.Models;
 using Xunit;
@@ -208,6 +209,43 @@ public void NetworkPolicy_ShouldStoreRules()
         policy.Egress[0].Target.Should().Be("example.com");
     }
 
+    [Fact]
+    public void Volume_WithOssfs_ShouldSerializeExpectedPayload()
+    {
+        var request = new CreateSandboxRequest
+        {
+            Image = new ImageSpec { Uri = "python:3.11" },
+            ResourceLimits = new Dictionary<string, string>(),
+            Entrypoint = new List<string> { "python" },
+            Volumes = new List<Volume>
+            {
+                new()
+                {
+                    Name = "oss-data",
+                    MountPath = "/mnt/oss",
+                    SubPath = "prefix",
+                    Ossfs = new OSSFS
+                    {
+                        Bucket = "bucket-a",
+                        Endpoint = "oss-cn-hangzhou.aliyuncs.com",
+                        AccessKeyId = "ak",
+                        AccessKeySecret = "sk",
+                        Options = new List<string> { "allow_other" }
+                    }
+                }
+            }
+        };
+
+        string json = JsonSerializer.Serialize(request);
+
+        json.Should().Contain("\"ossfs\":");
+        json.Should().Contain("\"bucket\":\"bucket-a\"");
+        json.Should().Contain("\"endpoint\":\"oss-cn-hangzhou.aliyuncs.com\"");
+        json.Should().Contain("\"accessKeyId\":\"ak\"");
+        json.Should().Contain("\"accessKeySecret\":\"sk\"");
+        json.Should().Contain("\"version\":\"2.0\"");
+    }
+
     [Fact]
     public void SandboxMetrics_ShouldStoreProperties()
     {

sdks/sandbox/javascript/README.md

@@ -165,7 +165,32 @@ const { endpoint } = await sandbox.getEndpoint(44772);
 const url = await sandbox.getEndpointUrl(44772);
 ```
 
-### 6. Sandbox Management (Admin)
+### 6. Volume Mounts
+
+`volumes` supports `host`, `pvc`, and `ossfs` backends. Each volume must specify exactly one backend.
+
+```ts
+const sandbox = await Sandbox.create({
+  connectionConfig: config,
+  image: "ubuntu",
+  volumes: [
+    {
+      name: "oss-data",
+      ossfs: {
+        bucket: "bucket-a",
+        endpoint: "oss-cn-hangzhou.aliyuncs.com",
+        accessKeyId: process.env.OSS_ACCESS_KEY_ID!,
+        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET!,
+        version: "2.0",
+      },
+      mountPath: "/mnt/oss",
+      subPath: "prefix",
+    },
+  ],
+});
+```
+
+### 7. Sandbox Management (Admin)
 
 Use `SandboxManager` for administrative tasks and finding existing sandboxes.
 

sdks/sandbox/javascript/README_zh.md

@@ -166,7 +166,32 @@ const { endpoint } = await sandbox.getEndpoint(44772);
 const url = await sandbox.getEndpointUrl(44772);
 ```
 
-### 6. 沙箱管理（Admin）
+### 6. Volume 挂载
+
+`volumes` 现在支持 `host`、`pvc` 和 `ossfs` 三种 backend。每个 volume 必须且只能指定其中一种。
+
+```ts
+const sandbox = await Sandbox.create({
+  connectionConfig: config,
+  image: "ubuntu",
+  volumes: [
+    {
+      name: "oss-data",
+      ossfs: {
+        bucket: "bucket-a",
+        endpoint: "oss-cn-hangzhou.aliyuncs.com",
+        accessKeyId: process.env.OSS_ACCESS_KEY_ID!,
+        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET!,
+        version: "2.0",
+      },
+      mountPath: "/mnt/oss",
+      subPath: "prefix",
+    },
+  ],
+});
+```
+
+### 7. 沙箱管理（Admin）
 
 使用 `SandboxManager` 进行管理操作，如查询现有沙箱列表。
 

sdks/sandbox/javascript/src/sandbox.ts

@@ -79,7 +79,7 @@ export interface SandboxCreateOptions {
   networkPolicy?: NetworkPolicy;
   /**
    * Optional list of volume mounts for persistent storage.
-   * Each volume specifies a backend (host path or PVC) and mount configuration.
+   * Each volume specifies a backend (host path, PVC, or OSSFS) and mount configuration.
    */
   volumes?: Volume[];
   /**

sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/models/sandboxes/SandboxModels.kt

@@ -386,12 +386,106 @@ class PVC private constructor(
     }
 }
 
+/**
+ * Alibaba Cloud OSS mount backend via ossfs.
+ *
+ * @property bucket OSS bucket name
+ * @property endpoint OSS endpoint (for example, `oss-cn-hangzhou.aliyuncs.com`)
+ * @property accessKeyId OSS access key ID for inline credentials mode
+ * @property accessKeySecret OSS access key secret for inline credentials mode
+ * @property version ossfs major version used by runtime mount integration
+ * @property options Additional ossfs mount options
+ */
+class OSSFS private constructor(
+    val bucket: String,
+    val endpoint: String,
+    val accessKeyId: String,
+    val accessKeySecret: String,
+    val version: String,
+    val options: List<String>?,
+) {
+    companion object {
+        const val VERSION_1_0 = "1.0"
+        const val VERSION_2_0 = "2.0"
+
+        @JvmStatic
+        fun builder(): Builder = Builder()
+    }
+
+    class Builder {
+        private var bucket: String? = null
+        private var endpoint: String? = null
+        private var accessKeyId: String? = null
+        private var accessKeySecret: String? = null
+        private var version: String = VERSION_2_0
+        private var options: List<String>? = null
+
+        fun bucket(bucket: String): Builder {
+            require(bucket.isNotBlank()) { "Bucket cannot be blank" }
+            this.bucket = bucket
+            return this
+        }
+
+        fun endpoint(endpoint: String): Builder {
+            require(endpoint.isNotBlank()) { "Endpoint cannot be blank" }
+            this.endpoint = endpoint
+            return this
+        }
+
+        fun accessKeyId(accessKeyId: String): Builder {
+            require(accessKeyId.isNotBlank()) { "Access key ID cannot be blank" }
+            this.accessKeyId = accessKeyId
+            return this
+        }
+
+        fun accessKeySecret(accessKeySecret: String): Builder {
+            require(accessKeySecret.isNotBlank()) { "Access key secret cannot be blank" }
+            this.accessKeySecret = accessKeySecret
+            return this
+        }
+
+        fun version(version: String): Builder {
+            require(version == VERSION_1_0 || version == VERSION_2_0) {
+                "OSSFS version must be one of: 1.0, 2.0"
+            }
+            this.version = version
+            return this
+        }
+
+        fun options(options: List<String>?): Builder {
+            this.options = options
+            return this
+        }
+
+        fun options(vararg options: String): Builder {
+            this.options = options.toList()
+            return this
+        }
+
+        fun build(): OSSFS {
+            val bucketValue = bucket ?: throw IllegalArgumentException("Bucket must be specified")
+            val endpointValue = endpoint ?: throw IllegalArgumentException("Endpoint must be specified")
+            val accessKeyIdValue = accessKeyId ?: throw IllegalArgumentException("Access key ID must be specified")
+            val accessKeySecretValue =
+                accessKeySecret ?: throw IllegalArgumentException("Access key secret must be specified")
+            return OSSFS(
+                bucket = bucketValue,
+                endpoint = endpointValue,
+                accessKeyId = accessKeyIdValue,
+                accessKeySecret = accessKeySecretValue,
+                version = version,
+                options = options,
+            )
+        }
+    }
+}
+
 /**
  * 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)
  *
  * Example usage:
@@ -413,8 +507,9 @@ class PVC private constructor(
  * ```
  *
  * @property name Unique identifier for the volume within the sandbox
- * @property host Host path bind mount backend (mutually exclusive with pvc)
- * @property pvc Kubernetes PVC mount backend (mutually exclusive with host)
+ * @property host Host path bind mount backend (mutually exclusive with pvc/ossfs)
+ * @property pvc Kubernetes PVC mount backend (mutually exclusive with host/ossfs)
+ * @property ossfs OSSFS mount backend (mutually exclusive with host/pvc)
  * @property mountPath Absolute path inside the container where the volume is mounted
  * @property readOnly If true, the volume is mounted as read-only. Defaults to false (read-write).
  * @property subPath Optional subdirectory under the backend path to mount
@@ -423,6 +518,7 @@ class Volume private constructor(
     val name: String,
     val host: Host?,
     val pvc: PVC?,
+    val ossfs: OSSFS?,
     val mountPath: String,
     val readOnly: Boolean,
     val subPath: String?,
@@ -436,6 +532,7 @@ class Volume private constructor(
         private var name: String? = null
         private var host: Host? = null
         private var pvc: PVC? = null
+        private var ossfs: OSSFS? = null
         private var mountPath: String? = null
         private var readOnly: Boolean = false
         private var subPath: String? = null
@@ -456,6 +553,11 @@ class Volume private constructor(
             return this
         }
 
+        fun ossfs(ossfs: OSSFS): Builder {
+            this.ossfs = ossfs
+            return this
+        }
+
         fun mountPath(mountPath: String): Builder {
             require(mountPath.startsWith("/")) { "Mount path must be an absolute path starting with '/'" }
             this.mountPath = mountPath
@@ -477,18 +579,23 @@ class Volume private constructor(
             val mountPathValue = mountPath ?: throw IllegalArgumentException("Mount path must be specified")
 
             // Validate exactly one backend is specified
-            val backendsSpecified = listOfNotNull(host, pvc).size
+            val backendsSpecified = listOfNotNull(host, pvc, ossfs).size
             if (backendsSpecified == 0) {
-                throw IllegalArgumentException("Exactly one backend (host, pvc) must be specified, but none was provided")
+                throw IllegalArgumentException(
+                    "Exactly one backend (host, pvc, ossfs) must be specified, but none was provided",
+                )
             }
             if (backendsSpecified > 1) {
-                throw IllegalArgumentException("Exactly one backend (host, pvc) must be specified, but multiple were provided")
+                throw IllegalArgumentException(
+                    "Exactly one backend (host, pvc, ossfs) must be specified, but multiple were provided",
+                )
             }
 
             return Volume(
                 name = nameValue,
                 host = host,
                 pvc = pvc,
+                ossfs = ossfs,
                 mountPath = mountPathValue,
                 readOnly = readOnly,
                 subPath = subPath,