Architecture

Sandcut is built around a simple rule: do control at the edge, do execution in a sandbox.

Request flow

Client
  ↓
Worker API
  ↓
Input size probe
  ↓
Durable Object lease scheduler
  ↓
Warm container session
  ↓
FFmpeg execution
  ↓
Stream response into R2
  ↓
Return CDN URL

Control plane responsibilities

The Worker handles:

• bearer token validation
• request JSON validation
• SSRF-aware input URL validation
• structured seek normalization
• preflight input size probing
• container session lease acquisition and release
• R2 upload orchestration

This keeps the Worker deterministic and small.

Execution plane responsibilities

The container handles:

• FFmpeg command planning
• actual media transformation
• streamed output file delivery

This keeps user-supplied media work inside the sandbox boundary.

Seek model

FFmpeg users care about both speed and accuracy. Sandcut surfaces that trade-off directly:

• fast: places -ss before -i
• accurate: places -ss after -i
• hybrid: combines a coarse pre-input seek with a short post-input correction

The API exposes a structured seek object instead of allowing raw -ss passthrough.

Streaming path

The current pipeline avoids the earlier memory-heavy pattern:

• container reads output via fs.createReadStream()
• Worker uses response.body directly in OUTPUT_BUCKET.put()

That means the Worker no longer needs to buffer the full processed video before upload.

Scheduler design

The Durable Object scheduler uses expiring leases and prefers:

1. the session with the fewest active jobs
2. the least recently used session when active-job counts tie

This is materially better than KV-only round-robin for overlapping requests.

Known trade-off

Preflight size probing is strong when the origin exposes Content-Length or supports ranged responses. If an origin hides both, a fully byte-enforced cutoff still requires a controlled downloader layer in front of FFmpeg.