process readiness

.changeset/mighty-squids-count.md

@@ -0,0 +1,15 @@
+---
+'@cloudflare/sandbox': patch
+---
+
+Add process readiness detection with port and log pattern waiting
+The `Process` object returned by `startProcess()` now includes readiness methods:
+
+- `process.waitForPort(port, options?)`: Wait for process to listen on a port
+  - Supports HTTP mode (default): checks endpoint returns expected status (200-399)
+  - Supports TCP mode: checks port accepts connections
+  - Configurable timeout, interval, path, and expected status
+
+- `process.waitForLog(pattern, options?)`: Wait for pattern in process output
+  - Supports string or RegExp patterns
+  - Returns matching line and capture groups

packages/sandbox-container/src/handlers/port-handler.ts

@@ -1,6 +1,7 @@
 // Port Handler
 import type {
   Logger,
+  PortCheckRequest,
   PortCloseResult,
   PortExposeResult,
   PortListResult
@@ -25,6 +26,8 @@ export class PortHandler extends BaseHandler<Request, Response> {
 
     if (pathname === '/api/expose-port') {
       return await this.handleExpose(request, context);
+    } else if (pathname === '/api/port-check') {
+      return await this.handlePortCheck(request, context);
     } else if (pathname === '/api/exposed-ports') {
       return await this.handleList(request, context);
     } else if (pathname.startsWith('/api/exposed-ports/')) {
@@ -51,6 +54,23 @@ export class PortHandler extends BaseHandler<Request, Response> {
     );
   }
 
+  private async handlePortCheck(
+    request: Request,
+    context: RequestContext
+  ): Promise<Response> {
+    const body = await this.parseRequestBody<PortCheckRequest>(request);
+
+    const result = await this.portService.checkPortReady(body);
+
+    return new Response(JSON.stringify(result), {
+      status: 200,
+      headers: {
+        'Content-Type': 'application/json',
+        ...context.corsHeaders
+      }
+    });
+  }
+
   private async handleExpose(
     request: Request,
     context: RequestContext