feat: add preview URLs and dynamic port forwarding (#20)

* feat: add Preview URLs & Port Management feature

Implements a new feature that allows exposing container ports and accessing them via public preview URLs.

Key changes:
- Add container-side HTTP endpoints for port exposure management
- Add SDK methods: exposePort(), unexposePort(), getExposedPorts()
- Implement automatic hostname detection from first request
- Add Worker routing for both subdomain (production) and path-based (localhost) patterns
- Support for any domain (workers.dev, custom domains, localhost)
- Add comprehensive documentation and examples

The feature supports:
- Explicit port exposure with optional friendly names
- Public access to exposed ports (no authentication)
- Different URL patterns for production vs localhost development
- Automatic cleanup when ports are unexposed

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

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

* fix: resolve preview URL issues for localhost development

Key fixes:
- Use path-based routing for localhost (/preview/{port}/{sandbox-id}) instead of subdomain-based
- Replace Python examples with Bun servers (Python not available in containers)
- Fix sandbox ID mismatch between friendly names and Durable Object IDs
- Use 127.0.0.1 instead of localhost for container networking reliability
- Add debug endpoints for troubleshooting
- Update all documentation to use Bun examples

The preview URLs now work correctly in both localhost and production environments.

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

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

* refactor: clean up preview URL documentation and remove PR-specific files

- Remove dedicated PREVIEW_URLS.md documentation
- Integrate preview URL docs into main README as standard API methods
- Remove planning and reference documents (PLAN.md, improvements.md, daytona.md, containers.md)
- Remove redundant preview-example.ts file
- Add explanatory comments to the main example about preview URL routing
- Treat preview URLs as just another SDK feature rather than giving it special emphasis

The functionality remains the same, but the documentation is now more integrated and maintainable.

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

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

* Format

* feat: simplify port forwarding with automatic preview URL routing

- Add handleSandboxRequest() to automatically route preview URLs
- Support all localhost patterns (127.0.0.1, ::1, etc.)
- Reduce user code from 40+ lines to just 3-5 lines
- Move Sandbox class to separate file for better organization
- Export client response types for TypeScript support
- Add comprehensive port forwarding documentation to README

BREAKING CHANGE: Refactored exports - Sandbox class now imported from main package

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

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

* feat: add background process execution support

Add support for running processes in the background via exec() options.
This allows long-running servers to start without blocking execution.

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

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

* feat: upgrade Docker base image with development tools

- Replace minimal oven/bun image with Ubuntu 22.04 base
- Add Python 3.11, Node.js 22 LTS, and Bun
- Include development tools (curl, wget, git, build-essential, ps)
- Add package managers (npm, yarn, pnpm)
- Configure non-root sandbox user with proper permissions
- Set working directory to /app with correct ownership

This provides a complete development environment for sandbox users
while maintaining security with non-root execution.

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

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

* feat: implement multi-port support with dynamic routing

- Remove hardcoded defaultPort from Sandbox class
- Add dynamic port routing based on request URL
- Route port 3000 requests to control plane, others to user services
- Update request handler to route directly to target ports
- Add multi-port example with API and web servers
- Fix containerFetch calls to specify port parameter
- Document implementation plan and architecture

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

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

* fix: ensure sandbox name consistency and document local dev port exposure

- Add setSandboxName RPC method to persist sandbox names in DO storage
- Pass sandbox name via X-Sandbox-Name header in request handler
- Use stored sandbox name (not DO hex ID) in preview URLs
- Add EXPOSE directives to example Dockerfile for local development
- Document local dev port exposure requirements in README
- Note: EXPOSE is only needed for local dev, not production

This fixes the issue where different containers were created when accessing
preview URLs due to hex IDs being treated as names by getContainer().

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

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

* refactor: remove createSandboxWorker helper API

Remove the createSandboxWorker convenience wrapper to reduce API surface area.
Users can achieve the same functionality with handleSandboxRequest directly.

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

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

* Revert local dev changes

* refactor: rename handleSandboxRequest to proxyToSandbox

Rename the request handler method to better convey its purpose of proxying
requests to exposed container ports via their preview URLs.

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

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

* Fix usage of background param

* Add changeset

* Clean up unused code

---------

Co-authored-by: Claude <[email protected]>

Author: ghostwriternr

.changeset/gold-suits-allow.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/sandbox": patch
+---
+
+add preview URLs and dynamic port forwarding