The Pieces Runtime: Architecture Deep Dive

Design Principles

The pieces runtime was designed around three constraints: security, latency, and density. Each piece must be isolated from every other piece. Each piece must respond in under five seconds. A single server must host hundreds of pieces.

Process Isolation

Each piece runs in its own Deno process. Deno provides built-in security through permission flags — no need for containers or VMs.

┌──────────────────────────────┐
│        Host Machine           │
│  ┌──────────┐ ┌──────────┐   │
│  │ Piece A  │ │ Piece B  │   │
│  │ (Deno)   │ │ (Deno)   │   │
│  │ :9001    │ │ :9002    │   │
│  └──────────┘ └──────────┘   │
│  ┌──────────┐ ┌──────────┐   │
│  │ Piece C  │ │ Piece D  │   │
│  │ (Deno)   │ │ (Deno)   │   │
│  │ :9003    │ │ :9004    │   │
│  └──────────┘ └──────────┘   │
└──────────────────────────────┘

The Router Layer

A lightweight HTTP router sits in front of all piece processes. It receives incoming requests, looks up the target piece by hostname or path, and proxies the request to the correct process.

Cold Starts

When a piece hasn't been used recently, its process is shut down to conserve memory. On the next request, the router detects the missing process and spawns a new one. Cold start latency averages 120 milliseconds.

Resource Limits

Each piece process is constrained:

• Memory: 128MB hard limit
• CPU: Proportional fair scheduling
• Execution time: 30 seconds maximum
• Concurrent requests: 10 per process

Health Monitoring

The runtime pings every piece process every five seconds. If a process doesn't respond, it is killed and restarted. Failed health checks are reported to the piece author.

The Future

We are working on WebAssembly backend targets for pieces. WASM would provide even stronger isolation guarantees and faster cold starts, at the cost of some API compatibility.