Document process readiness feature

Adds documentation for waitForLog() and waitForPort() methods that allow
waiting for processes to be ready before proceeding. Updates examples
throughout the docs to use these new simpler patterns instead of manual
delays or streaming logs.

Changes:
- API reference: Document waitForLog() and waitForPort() on Process interface
- Background processes guide: Show new readiness methods as primary pattern
- Expose services guide: Update all examples to use waitForPort()

Synced from cloudflare/sandbox-sdk#273

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: github-actions[bot]

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

@@ -87,7 +87,7 @@ for await (const event of parseSSEStream<ExecEvent>(stream)) {
 Start a long-running background process.
 
 ```ts
-const process = await sandbox.startProcess(command: string, options?: ProcessOptions): Promise<ProcessInfo>
+const process = await sandbox.startProcess(command: string, options?: ProcessOptions): Promise<Process>
 ```
 
 **Parameters**:
@@ -96,7 +96,7 @@ const process = await sandbox.startProcess(command: string, options?: ProcessOpt
   - `cwd` - Working directory
   - `env` - Environment variables
 
-**Returns**: `Promise<ProcessInfo>` with `id`, `pid`, `command`, `status`
+**Returns**: `Promise<Process>` with properties `id`, `pid`, `command`, `status` and methods `waitForLog()`, `waitForPort()`, `kill()`, `getStatus()`, `getLogs()`
 
 <TypeScriptExample>
 ```
@@ -111,6 +111,74 @@ const app = await sandbox.startProcess('node app.js', {
 ```
 </TypeScriptExample>
 
+## Process Readiness Methods
+
+Methods available on the `Process` object returned by `startProcess()`.
+
+### `waitForLog()`
+
+Wait for a process to output a specific log message or pattern.
+
+```ts
+const result = await process.waitForLog(pattern: string | RegExp, timeout?: number): Promise<WaitForLogResult>
+```
+
+**Parameters**:
+- `pattern` - String to match or regular expression pattern
+- `timeout` - Maximum time to wait in milliseconds (default: 30000)
+
+**Returns**: `Promise<WaitForLogResult>` with `line` (matched log line) and `match` (regex capture groups if pattern was RegExp)
+
+**Throws**:
+- `ProcessReadyTimeoutError` - Pattern not found within timeout
+- `ProcessExitedBeforeReadyError` - Process exited before pattern appeared
+
+<TypeScriptExample>
+```
+const proc = await sandbox.startProcess('npm start');
+
+// Wait for string match
+await proc.waitForLog('Server listening on port 3000');
+
+// Wait for regex pattern and extract values
+const result = await proc.waitForLog(/listening on port (\d+)/);
+console.log('Port:', result.match[1]); // Access captured group
+
+// Custom timeout
+await proc.waitForLog('Database connected', 60000); // 60 seconds
+```
+</TypeScriptExample>
+
+### `waitForPort()`
+
+Wait for a process to start accepting connections on a specific port.
+
+```ts
+await process.waitForPort(port: number, timeout?: number): Promise<void>
+```
+
+**Parameters**:
+- `port` - Port number to check
+- `timeout` - Maximum time to wait in milliseconds (default: 30000)
+
+**Throws**:
+- `ProcessReadyTimeoutError` - Port not available within timeout
+- `ProcessExitedBeforeReadyError` - Process exited before port became available
+
+<TypeScriptExample>
+```
+const proc = await sandbox.startProcess('bun run server.js');
+
+// Wait for port to accept connections
+await proc.waitForPort(8080);
+
+// Now safe to make requests or expose the port
+const { url } = await sandbox.exposePort(8080, {
+  hostname: request.url
+});
+```
+</TypeScriptExample>
+
 ### `listProcesses()`
 
 List all running processes.

src/content/docs/sandbox/guides/background-processes.mdx

@@ -83,9 +83,39 @@ const isRunning = processes.some(p => p.id === processId && p.status === 'runnin
 ```
 </TypeScriptExample>
 
-## Monitor process logs
+## Wait for process readiness
 
-Stream logs in real-time to detect when a service is ready:
+Use `waitForLog()` to wait for a specific log message:
+
+<TypeScriptExample>
+```
+const server = await sandbox.startProcess('node server.js');
+
+// Wait for readiness message
+await server.waitForLog('Server listening on port 3000');
+console.log('Server is ready!');
+
+// Wait with regex and extract values
+const result = await server.waitForLog(/listening on port (\d+)/);
+console.log('Started on port:', result.match[1]);
+```
+</TypeScriptExample>
+
+Or use `waitForPort()` to wait for a port to accept connections:
+
+<TypeScriptExample>
+```
+const server = await sandbox.startProcess('bun run server.js');
+
+// Wait for port to be ready
+await server.waitForPort(8080);
+console.log('Server is accepting connections on port 8080');
+```
+</TypeScriptExample>
+
+### Monitor process logs
+
+You can also stream logs in real-time for debugging:
 
 <TypeScriptExample>
 ```
@@ -137,24 +167,20 @@ Start services in sequence, waiting for dependencies:
 
 <TypeScriptExample>
 ```
-import { parseSSEStream, type LogEvent } from '@cloudflare/sandbox';
-
 // Start database first
 const db = await sandbox.startProcess('redis-server');
 
 // Wait for database to be ready
-const dbLogs = await sandbox.streamProcessLogs(db.id);
-for await (const log of parseSSEStream<LogEvent>(dbLogs)) {
-  if (log.data.includes('Ready to accept connections')) {
-    break;
-  }
-}
+await db.waitForLog('Ready to accept connections');
 
 // Now start API server (depends on database)
 const api = await sandbox.startProcess('node api-server.js', {
   env: { DATABASE_URL: 'redis://localhost:6379' }
 });
 
+// Wait for API to be ready
+await api.waitForPort(3000);
+
 console.log('All services running');
 ```
 </TypeScriptExample>
@@ -207,7 +233,7 @@ When using `keepAlive: true`, containers will not automatically timeout. You **m
 
 ## Best practices
 
-- **Wait for readiness** - Stream logs to detect when services are ready
+- **Wait for readiness** - Use `waitForLog()` or `waitForPort()` to ensure services are ready before proceeding
 - **Clean up** - Always stop processes when done
 - **Handle failures** - Monitor logs for errors and restart if needed
 - **Use try/finally** - Ensure cleanup happens even on errors

src/content/docs/sandbox/guides/expose-services.mdx

@@ -45,10 +45,10 @@ export default {
     const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
 
     // 1. Start a web server
-    await sandbox.startProcess('python -m http.server 8000');
+    const proc = await sandbox.startProcess('python -m http.server 8000');
 
-    // 2. Wait for service to start
-    await new Promise(resolve => setTimeout(resolve, 2000));
+    // 2. Wait for port to be ready
+    await proc.waitForPort(8000);
 
     // 3. Expose the port
     const exposed = await sandbox.exposePort(8000, { hostname });
@@ -97,14 +97,14 @@ When exposing multiple ports, use names to stay organized:
 // Extract hostname from request
 const { hostname } = new URL(request.url);
 
-// Start and expose API server
-await sandbox.startProcess('node api.js', { env: { PORT: '8080' } });
-await new Promise(resolve => setTimeout(resolve, 2000));
+// Start API and wait for readiness
+const apiProc = await sandbox.startProcess('node api.js', { env: { PORT: '8080' } });
+await apiProc.waitForPort(8080);
 const api = await sandbox.exposePort(8080, { hostname, name: 'api' });
 
-// Start and expose frontend
-await sandbox.startProcess('npm run dev', { env: { PORT: '5173' } });
-await new Promise(resolve => setTimeout(resolve, 2000));
+// Start frontend and wait for readiness
+const frontendProc = await sandbox.startProcess('npm run dev', { env: { PORT: '5173' } });
+await frontendProc.waitForPort(5173);
 const frontend = await sandbox.exposePort(5173, { hostname, name: 'frontend' });
 
 console.log('Services:');
@@ -115,42 +115,33 @@ console.log('- Frontend:', frontend.exposedAt);
 
 ## Wait for service readiness
 
-Always verify a service is ready before exposing. Use a simple delay for most cases:
+Always verify a service is ready before exposing. Use `waitForPort()` to wait for the port to accept connections:
 
 <TypeScriptExample>
 ```
 // Extract hostname from request
 const { hostname } = new URL(request.url);
 
-// Start service
-await sandbox.startProcess('npm run dev', { env: { PORT: '8080' } });
+// Start service and wait for port
+const proc = await sandbox.startProcess('npm run dev', { env: { PORT: '8080' } });
+await proc.waitForPort(8080);
 
-// Wait 2-3 seconds
-await new Promise(resolve => setTimeout(resolve, 2000));
-
-// Now expose
+// Now safe to expose
 await sandbox.exposePort(8080, { hostname });
 ```
 </TypeScriptExample>
 
-For critical services, poll the health endpoint:
+Or use `waitForLog()` to wait for a specific readiness message:
 
 <TypeScriptExample>
 ```
 // Extract hostname from request
 const { hostname } = new URL(request.url);
 
-await sandbox.startProcess('node api-server.js', { env: { PORT: '8080' } });
-
-// Wait for health check
-for (let i = 0; i < 10; i++) {
-  await new Promise(resolve => setTimeout(resolve, 1000));
+const proc = await sandbox.startProcess('node api-server.js', { env: { PORT: '8080' } });
 
-  const check = await sandbox.exec('curl -f http://localhost:8080/health || echo "not ready"');
-  if (check.stdout.includes('ok')) {
-    break;
-  }
-}
+// Wait for readiness log
+await proc.waitForLog('Server listening on port 8080');
 
 await sandbox.exposePort(8080, { hostname });
 ```
@@ -165,26 +156,26 @@ Expose multiple ports for full-stack applications:
 // Extract hostname from request
 const { hostname } = new URL(request.url);
 
-// Start backend
-await sandbox.startProcess('node api/server.js', {
+// Start backend and wait for readiness
+const backend = await sandbox.startProcess('node api/server.js', {
   env: { PORT: '8080' }
 });
-await new Promise(resolve => setTimeout(resolve, 2000));
+await backend.waitForPort(8080);
 
-// Start frontend
-await sandbox.startProcess('npm run dev', {
+// Start frontend and wait for readiness
+const frontend = await sandbox.startProcess('npm run dev', {
   cwd: '/workspace/frontend',
   env: { PORT: '5173', API_URL: 'http://localhost:8080' }
 });
-await new Promise(resolve => setTimeout(resolve, 3000));
+await frontend.waitForPort(5173);
 
 // Expose both
 const api = await sandbox.exposePort(8080, { hostname, name: 'api' });
-const frontend = await sandbox.exposePort(5173, { hostname, name: 'frontend' });
+const frontendUrl = await sandbox.exposePort(5173, { hostname, name: 'frontend' });
 
 return Response.json({
   api: api.exposedAt,
-  frontend: frontend.exposedAt
+  frontend: frontendUrl.exposedAt
 });
 ```
 </TypeScriptExample>
@@ -224,7 +215,7 @@ for (const port of [3000, 5173, 8080]) {
 
 ## Best practices
 
-- **Wait for readiness** - Don't expose ports immediately after starting processes
+- **Wait for readiness** - Use `waitForPort()` or `waitForLog()` before exposing ports
 - **Use named ports** - Easier to track when exposing multiple ports
 - **Clean up** - Unexpose ports when done to prevent abandoned URLs
 - **Add authentication** - Preview URLs are public; protect sensitive services