Add experimental option to sandbox create (#232)

* Add experimental option to sandbox create

* Add comment about mocking

* Run formatter

* Update comments

* Update interace with map[string]any

* Use a more generic experimental options type

Author: thomasjpfan

CHANGELOG.md

@@ -7,6 +7,7 @@ Both client libraries are pre-1.0, and they have separate versioning.
 - Align parameter defaults to be consistent with the Python SDK:
   - Set default Sandbox timeout to 5 minutes (was previously 10 minutes in the JS SDK).
   - Leave the Sandbox entrypoint args empty by default in the JS SDK (was previously `["sleep", "48h"]`).
+- Adds `enable_docker` experimental option to `Sandbox.Create` to Go and `Sandbox.create` to JS.
 
 ## modal-js/v0.5.6, modal-go/v0.5.6
 

modal-go/sandbox.go

@@ -30,30 +30,31 @@ type sandboxServiceImpl struct{ client *Client }
 
 // SandboxCreateParams are options for creating a Modal Sandbox.
 type SandboxCreateParams struct {
-	CPU               float64                      // CPU request in fractional, physical cores.
-	CPULimit          float64                      // Hard limit in fractional, physical CPU cores. Zero means no limit.
-	MemoryMiB         int                          // Memory request in MiB.
-	MemoryLimitMiB    int                          // Hard memory limit in MiB. Zero means no limit.
-	GPU               string                       // GPU reservation for the Sandbox (e.g. "A100", "T4:2", "A100-80GB:4").
-	Timeout           time.Duration                // Maximum lifetime of the Sandbox. Defaults to 5 minutes. If you pass zero you get the default 5 minutes.
-	IdleTimeout       time.Duration                // The amount of time that a Sandbox can be idle before being terminated.
-	Workdir           string                       // Working directory of the Sandbox.
-	Command           []string                     // Command to run in the Sandbox on startup.
-	Env               map[string]string            // Environment variables to set in the Sandbox.
-	Secrets           []*Secret                    // Secrets to inject into the Sandbox as environment variables.
-	Volumes           map[string]*Volume           // Mount points for Volumes.
-	CloudBucketMounts map[string]*CloudBucketMount // Mount points for cloud buckets.
-	PTY               bool                         // Enable a PTY for the Sandbox.
-	EncryptedPorts    []int                        // List of encrypted ports to tunnel into the Sandbox, with TLS encryption.
-	H2Ports           []int                        // List of encrypted ports to tunnel into the Sandbox, using HTTP/2.
-	UnencryptedPorts  []int                        // List of ports to tunnel into the Sandbox without encryption.
-	BlockNetwork      bool                         // Whether to block all network access from the Sandbox.
-	CIDRAllowlist     []string                     // List of CIDRs the Sandbox is allowed to access. Cannot be used with BlockNetwork.
-	Cloud             string                       // Cloud provider to run the Sandbox on.
-	Regions           []string                     // Region(s) to run the Sandbox on.
-	Verbose           bool                         // Enable verbose logging.
-	Proxy             *Proxy                       // Reference to a Modal Proxy to use in front of this Sandbox.
-	Name              string                       // Optional name for the Sandbox. Unique within an App.
+	CPU                 float64                      // CPU request in fractional, physical cores.
+	CPULimit            float64                      // Hard limit in fractional, physical CPU cores. Zero means no limit.
+	MemoryMiB           int                          // Memory request in MiB.
+	MemoryLimitMiB      int                          // Hard memory limit in MiB. Zero means no limit.
+	GPU                 string                       // GPU reservation for the Sandbox (e.g. "A100", "T4:2", "A100-80GB:4").
+	Timeout             time.Duration                // Maximum lifetime of the Sandbox. Defaults to 5 minutes. If you pass zero you get the default 5 minutes.
+	IdleTimeout         time.Duration                // The amount of time that a Sandbox can be idle before being terminated.
+	Workdir             string                       // Working directory of the Sandbox.
+	Command             []string                     // Command to run in the Sandbox on startup.
+	Env                 map[string]string            // Environment variables to set in the Sandbox.
+	Secrets             []*Secret                    // Secrets to inject into the Sandbox as environment variables.
+	Volumes             map[string]*Volume           // Mount points for Volumes.
+	CloudBucketMounts   map[string]*CloudBucketMount // Mount points for cloud buckets.
+	PTY                 bool                         // Enable a PTY for the Sandbox.
+	EncryptedPorts      []int                        // List of encrypted ports to tunnel into the Sandbox, with TLS encryption.
+	H2Ports             []int                        // List of encrypted ports to tunnel into the Sandbox, using HTTP/2.
+	UnencryptedPorts    []int                        // List of ports to tunnel into the Sandbox without encryption.
+	BlockNetwork        bool                         // Whether to block all network access from the Sandbox.
+	CIDRAllowlist       []string                     // List of CIDRs the Sandbox is allowed to access. Cannot be used with BlockNetwork.
+	Cloud               string                       // Cloud provider to run the Sandbox on.
+	Regions             []string                     // Region(s) to run the Sandbox on.
+	Verbose             bool                         // Enable verbose logging.
+	Proxy               *Proxy                       // Reference to a Modal Proxy to use in front of this Sandbox.
+	Name                string                       // Optional name for the Sandbox. Unique within an App.
+	ExperimentalOptions map[string]any               // Experimental options
 }
 
 // buildSandboxCreateRequestProto builds a SandboxCreateRequest proto from options.
@@ -244,26 +245,39 @@ func buildSandboxCreateRequestProto(appID, imageID string, params SandboxCreateP
 		resourcesBuilder.MemoryMbMax = memoryMbMax
 	}
 
+	// The public interface uses map[string]any so that we can add support for any experimental
+	// option type in the future. Currently, the proto only supports map[string]bool so we validate
+	// the input here.
+	protoExperimentalOptions := map[string]bool{}
+	for name, value := range params.ExperimentalOptions {
+		boolValue, ok := value.(bool)
+		if !ok {
+			return nil, fmt.Errorf("experimental option '%s' must be a bool, got %T", name, value)
+		}
+		protoExperimentalOptions[name] = boolValue
+	}
+
 	return pb.SandboxCreateRequest_builder{
 		AppId: appID,
 		Definition: pb.Sandbox_builder{
-			EntrypointArgs:     params.Command,
-			ImageId:            imageID,
-			SecretIds:          secretIds,
-			TimeoutSecs:        timeoutSecs,
-			IdleTimeoutSecs:    idleTimeoutSecs,
-			Workdir:            workdir,
-			NetworkAccess:      networkAccess,
-			Resources:          resourcesBuilder.Build(),
-			VolumeMounts:       volumeMounts,
-			CloudBucketMounts:  cloudBucketMounts,
-			PtyInfo:            ptyInfo,
-			OpenPorts:          portSpecs,
-			CloudProviderStr:   params.Cloud,
-			SchedulerPlacement: schedulerPlacement,
-			Verbose:            params.Verbose,
-			ProxyId:            proxyID,
-			Name:               &params.Name,
+			EntrypointArgs:      params.Command,
+			ImageId:             imageID,
+			SecretIds:           secretIds,
+			TimeoutSecs:         timeoutSecs,
+			IdleTimeoutSecs:     idleTimeoutSecs,
+			Workdir:             workdir,
+			NetworkAccess:       networkAccess,
+			Resources:           resourcesBuilder.Build(),
+			VolumeMounts:        volumeMounts,
+			CloudBucketMounts:   cloudBucketMounts,
+			PtyInfo:             ptyInfo,
+			OpenPorts:           portSpecs,
+			CloudProviderStr:    params.Cloud,
+			SchedulerPlacement:  schedulerPlacement,
+			Verbose:             params.Verbose,
+			ProxyId:             proxyID,
+			Name:                &params.Name,
+			ExperimentalOptions: protoExperimentalOptions,
 		}.Build(),
 	}.Build(), nil
 }

modal-go/test/sandbox_test.go

@@ -9,6 +9,9 @@ import (
 	"time"
 
 	"github.com/modal-labs/libmodal/modal-go"
+	"github.com/modal-labs/libmodal/modal-go/internal/grpcmock"
+
+	pb "github.com/modal-labs/libmodal/modal-go/proto/modal_proto"
 	"github.com/onsi/gomega"
 )
 
@@ -725,3 +728,107 @@ func TestSandboxInvalidTimeouts(t *testing.T) {
 	g.Expect(err).Should(gomega.HaveOccurred())
 	g.Expect(err.Error()).Should(gomega.ContainSubstring("whole number of seconds"))
 }
+
+func TestSandboxExperimentalDocker(t *testing.T) {
+	t.Parallel()
+	g := gomega.NewWithT(t)
+	ctx := context.Background()
+	tc := newTestClient(t)
+
+	app, err := tc.Apps.FromName(ctx, "libmodal-test", &modal.AppFromNameParams{CreateIfMissing: true})
+	g.Expect(err).ShouldNot(gomega.HaveOccurred())
+
+	image := tc.Images.FromRegistry("alpine:3.21", nil)
+
+	// With experimental option should include /var/lib/docker
+	options := map[string]any{"enable_docker": true}
+	sb, err := tc.Sandboxes.Create(ctx, app, image, &modal.SandboxCreateParams{ExperimentalOptions: options})
+	g.Expect(err).ShouldNot(gomega.HaveOccurred())
+	defer terminateSandbox(g, sb)
+
+	p, err := sb.Exec(ctx, []string{"test", "-d", "/var/lib/docker"}, nil)
+	g.Expect(err).ShouldNot(gomega.HaveOccurred())
+
+	exitCode, err := p.Wait(ctx)
+	g.Expect(err).ShouldNot(gomega.HaveOccurred())
+	g.Expect(exitCode).Should(gomega.Equal(0))
+
+	// Without experimental option should **not** include /var/lib/docker
+	sbDefault, err := tc.Sandboxes.Create(ctx, app, image, nil)
+	g.Expect(err).ShouldNot(gomega.HaveOccurred())
+	defer terminateSandbox(g, sbDefault)
+	p, err = sbDefault.Exec(ctx, []string{"test", "-d", "/var/lib/docker"}, nil)
+	g.Expect(err).ShouldNot(gomega.HaveOccurred())
+
+	exitCode, err = p.Wait(ctx)
+	g.Expect(err).ShouldNot(gomega.HaveOccurred())
+	g.Expect(exitCode).Should(gomega.Equal(1))
+}
+
+func TestSandboxExperimentalDockerNotBool(t *testing.T) {
+	t.Parallel()
+	g := gomega.NewWithT(t)
+	ctx := context.Background()
+	tc := newTestClient(t)
+
+	app, err := tc.Apps.FromName(ctx, "libmodal-test", &modal.AppFromNameParams{CreateIfMissing: true})
+	g.Expect(err).ShouldNot(gomega.HaveOccurred())
+
+	image := tc.Images.FromRegistry("alpine:3.21", nil)
+
+	options := map[string]any{"enable_docker": "not-a-bool"}
+	_, err = tc.Sandboxes.Create(ctx, app, image, &modal.SandboxCreateParams{ExperimentalOptions: options})
+	g.Expect(err).Should(gomega.HaveOccurred())
+	g.Expect(err.Error()).Should(gomega.ContainSubstring("must be a bool"))
+}
+
+func TestSandboxExperimentalDockerMock(t *testing.T) {
+	t.Parallel()
+	g := gomega.NewWithT(t)
+
+	options := map[string]any{"enable_docker": true}
+	expectedOptoins := map[string]bool{"enable_docker": true}
+	mock := newGRPCMockClient(t)
+
+	grpcmock.HandleUnary(
+		mock, "SandboxCreate",
+		func(req *pb.SandboxCreateRequest) (*pb.SandboxCreateResponse, error) {
+			g.Expect(req.GetDefinition().GetExperimentalOptions()).Should(gomega.Equal(expectedOptoins))
+			return pb.SandboxCreateResponse_builder{
+				SandboxId: "sb-123",
+			}.Build(), nil
+		},
+	)
+	grpcmock.HandleUnary(
+		mock, "AppGetOrCreate",
+		func(req *pb.AppGetOrCreateRequest) (*pb.AppGetOrCreateResponse, error) {
+			return pb.AppGetOrCreateResponse_builder{
+				AppId: "ap-1234",
+			}.Build(), nil
+		},
+	)
+
+	grpcmock.HandleUnary(
+		mock, "ImageGetOrCreate",
+		func(req *pb.ImageGetOrCreateRequest) (*pb.ImageGetOrCreateResponse, error) {
+			return pb.ImageGetOrCreateResponse_builder{
+				ImageId: "im-123",
+				Result: pb.GenericResult_builder{
+					Status: pb.GenericResult_GENERIC_STATUS_SUCCESS,
+				}.Build(),
+			}.Build(), nil
+		},
+	)
+
+	ctx := context.Background()
+	app, err := mock.Apps.FromName(ctx, "libmodal-test", &modal.AppFromNameParams{CreateIfMissing: true})
+	g.Expect(err).ShouldNot(gomega.HaveOccurred())
+
+	image := mock.Images.FromRegistry("alpine:3.21", nil)
+	sb, err := mock.Sandboxes.Create(ctx, app, image, &modal.SandboxCreateParams{ExperimentalOptions: options})
+	g.Expect(err).ShouldNot(gomega.HaveOccurred())
+
+	g.Expect(sb.SandboxID).Should(gomega.Equal("sb-123"))
+
+	g.Expect(mock.AssertExhausted()).ShouldNot(gomega.HaveOccurred())
+}

modal-js/src/sandbox.ts

@@ -142,6 +142,9 @@ export type SandboxCreateParams = {
 
   /** Optional name for the Sandbox. Unique within an App. */
   name?: string;
+
+  /** Optional experimental options. */
+  experimentalOptions?: Record<string, any>;
 };
 
 export async function buildSandboxCreateRequestProto(
@@ -311,6 +314,25 @@ export async function buildSandboxCreateRequestProto(
     }
   }
 
+  // The public interface uses Record<string, any> so that we can add support for any experimental
+  // option type in the future. Currently, the proto only supports Record<string, boolean> so we validate
+  // the input here.
+  const protoExperimentalOptions: Record<string, boolean> =
+    params.experimentalOptions
+      ? Object.entries(params.experimentalOptions).reduce(
+          (acc, [name, value]) => {
+            if (typeof value !== "boolean") {
+              throw new Error(
+                `experimental option '${name}' must be a boolean, got ${value}`,
+              );
+            }
+            acc[name] = Boolean(value);
+            return acc;
+          },
+          {} as Record<string, boolean>,
+        )
+      : {};
+
   return SandboxCreateRequest.create({
     appId,
     definition: {
@@ -341,6 +363,7 @@ export async function buildSandboxCreateRequestProto(
       verbose: params.verbose ?? false,
       proxyId: params.proxy?.proxyId,
       name: params.name,
+      experimentalOptions: protoExperimentalOptions,
     },
   });
 }

modal-js/test/sandbox.test.ts

@@ -7,7 +7,12 @@ import {
   GPUConfig,
   PTYInfo_PTYType,
   NetworkAccess_NetworkAccessType,
+  GenericResult_GenericStatus,
+  ImageGetOrCreateResponse,
+  AppGetOrCreateResponse,
+  SandboxCreateResponse,
 } from "../proto/modal_proto/api";
+import { createMockModalClients } from "../test-support/grpc_mock";
 
 test("CreateOneSandbox", async () => {
   const app = await tc.apps.fromName("libmodal-test", {
@@ -724,3 +729,88 @@ test("sandboxInvalidTimeouts", async () => {
     sandbox.exec(["echo", "test"], { timeoutMs: 1500 }),
   ).rejects.toThrow(/timeoutMs must be a multiple of 1000ms/);
 });
+
+test("testSandboxExperimentalDocker", async () => {
+  const app = await tc.apps.fromName("libmodal-test", {
+    createIfMissing: true,
+  });
+  const image = tc.images.fromRegistry("alpine:3.21");
+
+  // With experimental option should include /var/lib/docker
+  const sb = await tc.sandboxes.create(app, image, {
+    experimentalOptions: { enable_docker: true },
+  });
+  onTestFinished(async () => {
+    await sb.terminate();
+  });
+
+  const p = await sb.exec(["test", "-d", "/var/lib/docker"]);
+  expect(await p.wait()).toBe(0);
+
+  // Without experimental option should **not** include /var/lib/docker
+  const sbDefault = await tc.sandboxes.create(app, image);
+  onTestFinished(async () => {
+    await sbDefault.terminate();
+  });
+  const pDefault = await sbDefault.exec(["test", "-d", "/var/lib/docker"]);
+  expect(await pDefault.wait()).toBe(1);
+});
+
+test("testSandboxExperimentalDockerNotBool", async () => {
+  const app = await tc.apps.fromName("libmodal-test", {
+    createIfMissing: true,
+  });
+  const image = tc.images.fromRegistry("alpine:3.21");
+
+  await expect(
+    tc.sandboxes.create(app, image, {
+      experimentalOptions: { enable_docker: "not-a-bool" },
+    }),
+  ).rejects.toThrow("must be a bool");
+});
+
+// Skipping because creating a sandbox starts a log stream through `SandoxGetLogs`.
+// Enable this test when we adjust sandbox.create to start the stream on
+// `read`, which would match the implementation in `modal-go`.
+test.skip("testSandboxExperimentalDockerMock", async () => {
+  const { mockClient: mc, mockCpClient: mock } = createMockModalClients();
+
+  const options = { enable_docker: true };
+  mock.handleUnary("/SandboxCreate", (req: any): SandboxCreateResponse => {
+    expect(req.definition?.experimentalOptions).toMatchObject(options);
+    return { sandboxId: "sb-1234" };
+  });
+
+  mock.handleUnary("/AppGetOrCreate", (_: any): AppGetOrCreateResponse => {
+    return { appId: "ap-1234" };
+  });
+
+  const app = await mc.apps.fromName("libmodal-test", {
+    createIfMissing: true,
+  });
+
+  mock.handleUnary("ImageGetOrCreate", (_: any): ImageGetOrCreateResponse => {
+    return {
+      imageId: "im-123",
+      result: {
+        status: GenericResult_GenericStatus.GENERIC_STATUS_SUCCESS,
+        exception: "",
+        exitcode: 0,
+        traceback: "",
+        serializedTb: new Uint8Array(0),
+        tbLineCache: new Uint8Array(0),
+        propagationReason: "",
+      },
+      metadata: undefined,
+    };
+  });
+
+  const image = mc.images.fromRegistry("alpine:3.21");
+
+  const sb = await mc.sandboxes.create(app, image, {
+    experimentalOptions: options,
+  });
+  expect(sb.sandboxId).toEqual("sb-1234");
+
+  mock.assertExhausted();
+});