Document prefix option for mounting bucket subdirectories (#27459)

* Document prefix option for mounting bucket subdirectories

Add documentation for the new prefix option in mountBucket() that allows
mounting specific subdirectories within S3-compatible buckets.

Changes:
- Add prefix field to MountBucketOptions type documentation
- Add example of mounting bucket subdirectory in API reference
- Add dedicated section in mount-buckets guide with multiple examples
- Document prefix format requirements (must start and end with /)

Related: cloudflare/sandbox-sdk#335

* Add documentation for mountBucket prefix option

Documents the new prefix parameter that allows mounting S3 bucket
subdirectories. Updates both the API reference and mount-buckets guide
with examples and validation requirements.

Syncs cloudflare-docs with sandbox-sdk PR #335

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Matt Silverlock <msilverlock@cloudflare.com>

Author: 3 people

src/content/docs/sandbox/api/storage.mdx

@@ -59,7 +59,7 @@ await sandbox.mountBucket('datasets', '/datasets', {
 // Mount a subdirectory within the bucket
 await sandbox.mountBucket('shared-bucket', '/user-data', {
   endpoint: 'https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com',
-  prefix: '/users/user-123'
+  prefix: '/users/user-123/'
 });
 ```
 </TypeScriptExample>
@@ -115,7 +115,7 @@ interface MountBucketOptions {
 	credentials?: BucketCredentials;
 	readOnly?: boolean;
 	prefix?: string;
-	s3fsOptions?: string[];
+	s3fsOptions?: Record<string, string>;
 }
 ```
 
@@ -137,12 +137,13 @@ interface MountBucketOptions {
 - `readOnly` (optional) - Mount in read-only mode
   - Default: `false`
 
-- `prefix` (optional) - Mount a subdirectory within the bucket
-  - Must start with `/` (e.g., `'/sessions/user123'` or `'/data/uploads/'`)
-  - Enables multi-tenant isolation within a single bucket
+- `prefix` (optional) - Subdirectory within the bucket to mount
+  - When specified, only contents under this prefix are visible at the mount point
+  - Must start and end with `/` (e.g., `/data/uploads/`)
+  - Default: Mount entire bucket
 
-- `s3fsOptions` (optional) - Advanced s3fs mount flags as string array
-  - Example: `['use_cache=/tmp/cache']`
+- `s3fsOptions` (optional) - Advanced s3fs mount flags
+  - Example: `{ 'use_cache': '/tmp/cache' }`
 
 ### `BucketProvider`
 

src/content/docs/sandbox/guides/mount-buckets.mdx

@@ -93,6 +93,44 @@ await sandbox.mountBucket('my-r2-bucket', '/data', {
 ```
 </TypeScriptExample>
 
+## Mount bucket subdirectories
+
+Mount a specific subdirectory within a bucket using the `prefix` option. Only contents under the prefix are visible at the mount point:
+
+<TypeScriptExample>
+```typescript
+// Mount only the /uploads/images/ subdirectory
+await sandbox.mountBucket('my-bucket', '/images', {
+	endpoint: 'https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com',
+	prefix: '/uploads/images/'
+});
+
+// Files appear at mount point without the prefix
+// Bucket: my-bucket/uploads/images/photo.jpg
+// Mounted path: /images/photo.jpg
+await sandbox.exec('ls', { args: ['/images'] });
+
+// Write to subdirectory
+await sandbox.writeFile('/images/photo.jpg', imageData);
+// Creates my-bucket:/uploads/images/photo.jpg
+
+// Mount different prefixes to different paths
+await sandbox.mountBucket('datasets', '/training-data', {
+	endpoint: 'https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com',
+	prefix: '/ml/training/'
+});
+
+await sandbox.mountBucket('datasets', '/test-data', {
+	endpoint: 'https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com',
+	prefix: '/ml/testing/'
+});
+```
+</TypeScriptExample>
+
+:::note[Prefix format]
+The `prefix` must start and end with `/` (e.g., `/data/`, `/logs/2024/`). This is required by the underlying s3fs tool.
+:::
+
 ## Read-only mounts
 
 Protect data by mounting buckets in read-only mode:
@@ -264,6 +302,7 @@ await sandbox.exec('cp', { args: ['/workspace/results.json', '/data/results/outp
 - **Use R2 for Cloudflare** - Zero egress fees and optimized configuration
 - **Secure credentials** - Always use Worker secrets, never hardcode
 - **Read-only when possible** - Protect data with read-only mounts
+- **Use prefixes for isolation** - Mount subdirectories when working with specific datasets
 - **Mount paths** - Use `/data`, `/storage`, or `/mnt/*` (avoid `/workspace`, `/tmp`)
 - **Handle errors** - Wrap mount operations in try/catch blocks
 - **Optimize access** - Copy frequently accessed files locally