Non-breaking option to fix preview URLs (#213)

Hostnames are case-insensitive at the DNS level, so the URL class
automatically converts the hostname to lowercase. But as a result,
preview URLs for sandbox IDs with uppercase characters was being routed
to incorrect DO instances.

Add opt-in notmalizeId option that normalizes IDs to lowercase. This is
done in order to prevent existing services from not being able to access
sandbox instances started by an older version. We instead raise warnings
in logs and errors right now so there is no breaking change for anyone,
but giving developers sufficient time to transition to the new behaviour
before we make this the default.

Author: ghostwriternr

.changeset/fix-sandbox-id-case-sensitivity.md

@@ -0,0 +1,15 @@
+---
+'@cloudflare/sandbox': minor
+---
+
+Add opt-in `normalizeId` option to `getSandbox()` for preview URL compatibility.
+
+Sandbox IDs with uppercase letters cause preview URL requests to route to different Durable Object instances (hostnames are case-insensitive). Use `{ normalizeId: true }` to lowercase IDs for preview URL support:
+
+```typescript
+getSandbox(ns, 'MyProject-123', { normalizeId: true }); // Creates DO with key "myproject-123"
+```
+
+**Important:** Different `normalizeId` values create different DO instances. If you have an existing sandbox with uppercase letters, create a new one with `normalizeId: true`.
+
+**Deprecation warning:** IDs with uppercase letters will trigger a warning. In a future version, `normalizeId` will default to `true`.

packages/sandbox/src/request-handler.ts

@@ -36,7 +36,8 @@ export async function proxyToSandbox<E extends SandboxEnv>(
     }
 
     const { sandboxId, port, path, token } = routeInfo;
-    const sandbox = getSandbox(env.Sandbox, sandboxId);
+    // Preview URLs always use normalized (lowercase) IDs
+    const sandbox = getSandbox(env.Sandbox, sandboxId, { normalizeId: true });
 
     // Critical security check: Validate token (mandatory for all user ports)
     // Skip check for control plane port 3000

packages/sandbox/src/sandbox.ts

@@ -37,10 +37,24 @@ export function getSandbox(
   id: string,
   options?: SandboxOptions
 ): Sandbox {
-  const stub = getContainer(ns, id) as unknown as Sandbox;
+  const sanitizedId = sanitizeSandboxId(id);
+  const effectiveId = options?.normalizeId
+    ? sanitizedId.toLowerCase()
+    : sanitizedId;
+
+  const hasUppercase = /[A-Z]/.test(sanitizedId);
+  if (!options?.normalizeId && hasUppercase) {
+    const logger = createLogger({ component: 'sandbox-do' });
+    logger.warn(
+      `Sandbox ID "${sanitizedId}" contains uppercase letters, which causes issues with preview URLs (hostnames are case-insensitive). ` +
+        `normalizeId will default to true in a future version to prevent this. ` +
+        `Use lowercase IDs or pass { normalizeId: true } to prepare.`
+    );
+  }
 
-  // Store the name on first access
-  stub.setSandboxName?.(id);
+  const stub = getContainer(ns, effectiveId) as unknown as Sandbox;
+
+  stub.setSandboxName?.(effectiveId, options?.normalizeId);
 
   if (options?.baseUrl) {
     stub.setBaseUrl(options.baseUrl);
@@ -63,7 +77,6 @@ export function connect(stub: {
   fetch: (request: Request) => Promise<Response>;
 }) {
   return async (request: Request, port: number) => {
-    // Validate port before routing
     if (!validatePort(port)) {
       throw new SecurityError(
         `Invalid or restricted port: ${port}. Ports must be in range 1024-65535 and not reserved.`
@@ -81,6 +94,7 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
   client: SandboxClient;
   private codeInterpreter: CodeInterpreter;
   private sandboxName: string | null = null;
+  private normalizeId: boolean = false;
   private baseUrl: string | null = null;
   private portTokens: Map<number, string> = new Map();
   private defaultSession: string | null = null;
@@ -115,10 +129,11 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
     // The CodeInterpreter extracts client.interpreter from the sandbox
     this.codeInterpreter = new CodeInterpreter(this);
 
-    // Load the sandbox name, port tokens, and default session from storage on initialization
     this.ctx.blockConcurrencyWhile(async () => {
       this.sandboxName =
         (await this.ctx.storage.get<string>('sandboxName')) || null;
+      this.normalizeId =
+        (await this.ctx.storage.get<boolean>('normalizeId')) || false;
       this.defaultSession =
         (await this.ctx.storage.get<string>('defaultSession')) || null;
       const storedTokens =
@@ -133,11 +148,12 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
     });
   }
 
-  // RPC method to set the sandbox name
-  async setSandboxName(name: string): Promise<void> {
+  async setSandboxName(name: string, normalizeId?: boolean): Promise<void> {
     if (!this.sandboxName) {
       this.sandboxName = name;
+      this.normalizeId = normalizeId || false;
       await this.ctx.storage.put('sandboxName', name);
+      await this.ctx.storage.put('normalizeId', this.normalizeId);
     }
   }
 
@@ -1031,20 +1047,29 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
       );
     }
 
-    // Validate sandbox ID (will throw SecurityError if invalid)
-    const sanitizedSandboxId = sanitizeSandboxId(sandboxId);
+    // Hostnames are case-insensitive, routing requests to wrong DO instance when keys contain uppercase letters
+    const effectiveId = this.sandboxName || sandboxId;
+    const hasUppercase = /[A-Z]/.test(effectiveId);
+    if (!this.normalizeId && hasUppercase) {
+      throw new SecurityError(
+        `Preview URLs require lowercase sandbox IDs. Your ID "${effectiveId}" contains uppercase letters.\n\n` +
+          `To fix this:\n` +
+          `1. Create a new sandbox with: getSandbox(ns, "${effectiveId}", { normalizeId: true })\n` +
+          `2. This will create a sandbox with ID: "${effectiveId.toLowerCase()}"\n\n` +
+          `Note: Due to DNS case-insensitivity, IDs with uppercase letters cannot be used with preview URLs.`
+      );
+    }
+
+    const sanitizedSandboxId = sanitizeSandboxId(sandboxId).toLowerCase();
 
     const isLocalhost = isLocalhostPattern(hostname);
 
     if (isLocalhost) {
-      // Unified subdomain approach for localhost (RFC 6761)
       const [host, portStr] = hostname.split(':');
       const mainPort = portStr || '80';
 
-      // Use URL constructor for safe URL building
       try {
         const baseUrl = new URL(`http://${host}:${mainPort}`);
-        // Construct subdomain safely with mandatory token
         const subdomainHost = `${port}-${sanitizedSandboxId}-${token}.${host}`;
         baseUrl.hostname = subdomainHost;
 
@@ -1058,13 +1083,8 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
       }
     }
 
-    // Production subdomain logic - enforce HTTPS
     try {
-      // Always use HTTPS for production (non-localhost)
-      const protocol = 'https';
-      const baseUrl = new URL(`${protocol}://${hostname}`);
-
-      // Construct subdomain safely with mandatory token
+      const baseUrl = new URL(`https://${hostname}`);
       const subdomainHost = `${port}-${sanitizedSandboxId}-${token}.${hostname}`;
       baseUrl.hostname = subdomainHost;
 

packages/sandbox/tests/get-sandbox.test.ts

@@ -44,7 +44,10 @@ describe('getSandbox', () => {
     const sandbox = getSandbox(mockNamespace, 'test-sandbox');
 
     expect(sandbox).toBeDefined();
-    expect(sandbox.setSandboxName).toHaveBeenCalledWith('test-sandbox');
+    expect(sandbox.setSandboxName).toHaveBeenCalledWith(
+      'test-sandbox',
+      undefined
+    );
   });
 
   it('should apply sleepAfter option when provided as string', () => {
@@ -146,4 +149,24 @@ describe('getSandbox', () => {
     expect(sandbox.setBaseUrl).toHaveBeenCalledWith('https://example.com');
     expect(sandbox.setKeepAlive).toHaveBeenCalledWith(true);
   });
+
+  it('should preserve sandbox ID case by default', () => {
+    const mockNamespace = {} as any;
+    getSandbox(mockNamespace, 'MyProject-ABC123');
+
+    expect(mockGetContainer).toHaveBeenCalledWith(
+      mockNamespace,
+      'MyProject-ABC123'
+    );
+  });
+
+  it('should normalize sandbox ID to lowercase when normalizeId option is true', () => {
+    const mockNamespace = {} as any;
+    getSandbox(mockNamespace, 'MyProject-ABC123', { normalizeId: true });
+
+    expect(mockGetContainer).toHaveBeenCalledWith(
+      mockNamespace,
+      'myproject-abc123'
+    );
+  });
 });

packages/sandbox/tests/sandbox.test.ts

@@ -736,4 +736,90 @@ describe('Sandbox - Automatic Session Management', () => {
       expect(result.sessionId).toBe('custom-session');
     });
   });
+
+  describe('constructPreviewUrl validation', () => {
+    it('should throw clear error for ID with uppercase letters without normalizeId', async () => {
+      await sandbox.setSandboxName('MyProject-123', false);
+
+      vi.spyOn(sandbox.client.ports, 'exposePort').mockResolvedValue({
+        port: 8080,
+        token: 'test-token-1234',
+        previewUrl: ''
+      });
+
+      await expect(
+        sandbox.exposePort(8080, { hostname: 'example.com' })
+      ).rejects.toThrow(/Preview URLs require lowercase sandbox IDs/);
+    });
+
+    it('should construct valid URL for lowercase ID', async () => {
+      await sandbox.setSandboxName('my-project', false);
+
+      vi.spyOn(sandbox.client.ports, 'exposePort').mockResolvedValue({
+        port: 8080,
+        token: 'mock-token',
+        previewUrl: ''
+      });
+
+      const result = await sandbox.exposePort(8080, {
+        hostname: 'example.com'
+      });
+
+      expect(result.url).toMatch(
+        /^https:\/\/8080-my-project-[a-z0-9_-]{16}\.example\.com\/?$/
+      );
+      expect(result.port).toBe(8080);
+    });
+
+    it('should construct valid URL with normalized ID', async () => {
+      await sandbox.setSandboxName('myproject-123', true);
+
+      vi.spyOn(sandbox.client.ports, 'exposePort').mockResolvedValue({
+        port: 4000,
+        token: 'mock-token',
+        previewUrl: ''
+      });
+
+      const result = await sandbox.exposePort(4000, { hostname: 'my-app.dev' });
+
+      expect(result.url).toMatch(
+        /^https:\/\/4000-myproject-123-[a-z0-9_-]{16}\.my-app\.dev\/?$/
+      );
+      expect(result.port).toBe(4000);
+    });
+
+    it('should construct valid localhost URL', async () => {
+      await sandbox.setSandboxName('test-sandbox', false);
+
+      vi.spyOn(sandbox.client.ports, 'exposePort').mockResolvedValue({
+        port: 8080,
+        token: 'mock-token',
+        previewUrl: ''
+      });
+
+      const result = await sandbox.exposePort(8080, {
+        hostname: 'localhost:3000'
+      });
+
+      expect(result.url).toMatch(
+        /^http:\/\/8080-test-sandbox-[a-z0-9_-]{16}\.localhost:3000\/?$/
+      );
+    });
+
+    it('should include helpful guidance in error message', async () => {
+      await sandbox.setSandboxName('MyProject-ABC', false);
+
+      vi.spyOn(sandbox.client.ports, 'exposePort').mockResolvedValue({
+        port: 8080,
+        token: 'test-token-1234',
+        previewUrl: ''
+      });
+
+      await expect(
+        sandbox.exposePort(8080, { hostname: 'example.com' })
+      ).rejects.toThrow(
+        /getSandbox\(ns, "MyProject-ABC", \{ normalizeId: true \}\)/
+      );
+    });
+  });
 });

packages/shared/src/types.ts

@@ -286,6 +286,28 @@ export interface SandboxOptions {
    * Default: false
    */
   keepAlive?: boolean;
+
+  /**
+   * Normalize sandbox ID to lowercase for preview URL compatibility
+   *
+   * Required for preview URLs because hostnames are case-insensitive (RFC 3986), which
+   * would route requests to a different Durable Object instance with IDs containing uppercase letters.
+   *
+   * **Important:** Different normalizeId values create different Durable Object instances:
+   * - `getSandbox(ns, "MyProject")` → DO key: "MyProject"
+   * - `getSandbox(ns, "MyProject", {normalizeId: true})` → DO key: "myproject"
+   *
+   * **Future change:** In a future version, this will default to `true` (automatically lowercase all IDs).
+   * IDs with uppercase letters will trigger a warning. To prepare, use lowercase IDs or explicitly
+   * pass `normalizeId: true`.
+   *
+   * @example
+   * getSandbox(ns, "my-project")  // Works with preview URLs (lowercase)
+   * getSandbox(ns, "MyProject", {normalizeId: true})  // Normalized to "myproject"
+   *
+   * @default false
+   */
+  normalizeId?: boolean;
 }
 
 /**