Merge pull request #921 from zpzjzj/feat/go-sdk-platform-spec

feat(sdks/go): add PlatformSpec to CreateSandboxRequest

Author: Pangjiping

sdks/sandbox/go/opensandbox_test.go

@@ -263,6 +263,68 @@ func TestCreateSandbox_FromSnapshot(t *testing.T) {
 	require.NoErrorf(t, err, "CreateSandbox from snapshot")
 }
 
+func TestCreateSandbox_Platform(t *testing.T) {
+	_, client := newLifecycleServer(t, func(w http.ResponseWriter, r *http.Request) {
+		var req CreateSandboxRequest
+		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+			assert.Fail(t, fmt.Sprintf("decode request: %v", err))
+			return
+		}
+		require.NotNil(t, req.Platform, "expected Platform to be sent in the request")
+		require.Equal(t, OSWindows, req.Platform.OS, "Platform.OS")
+		require.Equal(t, ArchAMD64, req.Platform.Arch, "Platform.Arch")
+
+		jsonResponse(w, http.StatusCreated, SandboxInfo{
+			ID:        "sbx-windows",
+			Status:    SandboxStatus{State: StatePending},
+			Platform:  &PlatformSpec{OS: OSWindows, Arch: ArchAMD64},
+			CreatedAt: time.Now().UTC().Truncate(time.Second),
+		})
+	})
+
+	info, err := client.CreateSandbox(context.Background(), CreateSandboxRequest{
+		Image:          &ImageSpec{URI: "dockurr/windows:latest"},
+		Entrypoint:     []string{"cmd", "/c", "echo hi"},
+		ResourceLimits: ResourceLimits{"cpu": "2", "memory": "4G", "disk": "64G"},
+		Platform:       &PlatformSpec{OS: OSWindows, Arch: ArchAMD64},
+	})
+	require.NoErrorf(t, err, "CreateSandbox with Platform")
+	require.NotNil(t, info.Platform, "response should echo Platform")
+	require.Equal(t, OSWindows, info.Platform.OS, "echoed Platform.OS")
+	require.Equal(t, ArchAMD64, info.Platform.Arch, "echoed Platform.Arch")
+}
+
+func TestCreateSandbox_PlatformOmittedWhenNil(t *testing.T) {
+	_, client := newLifecycleServer(t, func(w http.ResponseWriter, r *http.Request) {
+		body, err := io.ReadAll(r.Body)
+		if err != nil {
+			assert.Fail(t, fmt.Sprintf("read request body: %v", err))
+			return
+		}
+		var raw map[string]json.RawMessage
+		if err := json.Unmarshal(body, &raw); err != nil {
+			assert.Fail(t, fmt.Sprintf("unmarshal request body: %v", err))
+			return
+		}
+		if _, present := raw["platform"]; present {
+			assert.Fail(t, "platform should be omitted from JSON when nil")
+		}
+
+		jsonResponse(w, http.StatusCreated, SandboxInfo{
+			ID:        "sbx-no-platform",
+			Status:    SandboxStatus{State: StatePending},
+			CreatedAt: time.Now().UTC().Truncate(time.Second),
+		})
+	})
+
+	_, err := client.CreateSandbox(context.Background(), CreateSandboxRequest{
+		Image:          &ImageSpec{URI: "python:3.12"},
+		Entrypoint:     []string{"/bin/sh"},
+		ResourceLimits: ResourceLimits{"cpu": "500m"},
+	})
+	require.NoErrorf(t, err, "CreateSandbox without Platform")
+}
+
 func TestGetSandbox(t *testing.T) {
 	want := SandboxInfo{
 		ID: "sbx-456",

sdks/sandbox/go/sandbox.go

@@ -66,6 +66,10 @@ type SandboxCreateOptions struct {
 	// Extensions for provider-specific parameters.
 	Extensions map[string]string
 
+	// Platform selects the target OS/arch for the sandbox (e.g. {"os":
+	// "windows", "arch": "amd64"}). When nil the server applies its default.
+	Platform *PlatformSpec
+
 	// SkipHealthCheck skips the WaitUntilReady call after creation.
 	SkipHealthCheck bool
 
@@ -132,6 +136,7 @@ func CreateSandbox(ctx context.Context, config ConnectionConfig, opts SandboxCre
 		NetworkPolicy:  opts.NetworkPolicy,
 		Volumes:        opts.Volumes,
 		Extensions:     opts.Extensions,
+		Platform:       opts.Platform,
 	}
 	if opts.Image != "" {
 		req.Image = &ImageSpec{URI: opts.Image, Auth: opts.ImageAuth}

sdks/sandbox/go/types.go

@@ -55,6 +55,39 @@ type ImageAuth struct {
 	Password string `json:"password"`
 }
 
+// PlatformOS is the target operating system of a sandbox platform constraint.
+// The wire-level enum is enforced server-side; the constants below mirror the
+// spec so Go callers can avoid stringly-typed typos.
+type PlatformOS string
+
+const (
+	OSLinux   PlatformOS = "linux"
+	OSWindows PlatformOS = "windows"
+)
+
+// PlatformArch is the target CPU architecture of a sandbox platform
+// constraint.
+type PlatformArch string
+
+const (
+	ArchAMD64 PlatformArch = "amd64"
+	ArchARM64 PlatformArch = "arm64"
+)
+
+// PlatformSpec is a runtime platform constraint used for scheduling and
+// provisioning. It is independent from Image and expresses the expected
+// target OS and CPU architecture for sandbox execution.
+//
+// When omitted, the server applies its own default platform selection
+// behavior. When provided, the runtime must satisfy the constraint or the
+// request fails.
+//
+// See specs/sandbox-lifecycle.yml#/components/schemas/PlatformSpec.
+type PlatformSpec struct {
+	OS   PlatformOS   `json:"os"`
+	Arch PlatformArch `json:"arch"`
+}
+
 // ResourceLimits defines runtime resource constraints as key-value pairs.
 // Common keys: "cpu" (e.g. "500m"), "memory" (e.g. "512Mi"), "gpu" (e.g. "1").
 type ResourceLimits map[string]string
@@ -120,6 +153,7 @@ type CreateSandboxRequest struct {
 	NetworkPolicy  *NetworkPolicy    `json:"networkPolicy,omitempty"`
 	Volumes        []Volume          `json:"volumes,omitempty"`
 	Extensions     map[string]string `json:"extensions,omitempty"`
+	Platform       *PlatformSpec     `json:"platform,omitempty"`
 }
 
 // SandboxInfo represents a runtime execution environment provisioned from a
@@ -133,6 +167,7 @@ type SandboxInfo struct {
 	Entrypoint []string          `json:"entrypoint"`
 	ExpiresAt  *time.Time        `json:"expiresAt,omitempty"`
 	CreatedAt  time.Time         `json:"createdAt"`
+	Platform   *PlatformSpec     `json:"platform,omitempty"`
 }
 
 type SnapshotState string