Sandbox SDK 1.0 migration — R2 connectivity report & migration prompt
On this page
Status: completed. The SDK 1.0 preview (
@cloudflare/sandbox@0.13.0-next.776.1, PR #306) is merged intodevelop, and the release and client-docs R2 bridges now run on it: the pinned stable reference was uncommented andSandbox.outboundByHostis registered insrc/index.ts. The canonicalstatic outboundByHostAPI is unchanged in the preview, so no handler code changed. The R2 S3 credential stays deprecated for the container. Validated with the Worker (1528) and client (44) suites and the local E2E gateway-boot smoke.
1. Complete report — what exists and what it uses
1.1 The stable API
@cloudflare/sandbox’s Sandbox extends Container from
@cloudflare/containers, which declares (stable 0.3.7):
type OutboundHandler<E = Cloudflare.Env, P = unknown> = (
req: Request,
env: E,
ctx: { containerId: string; className: string },
) => Promise<Response> | Response;
class Container {
static get/set outboundByHost: Record<string, OutboundHandler>;
static get/set outboundHandlers: Record<string, OutboundHandler>;
static get/set outbound: OutboundHandler; // catch-all
}
A sandbox makes a plain HTTP request to a virtual hostname
(http://<host>/<path>); the matching outboundByHost handler runs in the
Workers runtime where env bindings (R2, KV, D1, DOs) are available. Handlers
are selected by exact hostname; anything unmatched falls through to the
catch-all outbound. This is the canonical API described by
https://developers.cloudflare.com/sandbox/guides/workers-connections/ and is
unchanged in the 1.0 preview.
1.2 What was implemented (this feature)
apps/fouria/src/sandbox-r2-bridge.ts—handleReleasesR2Requestmaps HTTP onto the tenantBACKUP_BUCKETunder a fixedreleases/prefix:GET /(list),GET/HEAD/PUT/DELETE /<key>. Keys are sanitized against traversal;PUTusesFixedLengthStream(bounded memory) whencontent-lengthis advertised. Missing binding →503.apps/fouria/src/index.ts— registers both bridges:Sandbox.outboundByHost = { [RELEASES_R2_HOST]: (request, env) => handleReleasesR2Request(request, env), [DOCS_R2_HOST]: (request, env, ctx) => handleDocsR2Request(request, env, ctx), }; Sandbox.outbound = async (request) => fetch(request); // catch-allapps/fouria/src/sandbox-docs-bridge.ts—handleDocsR2Requestmapshttp://docs.r2.internal/...ontocustomers/<slug>/docs/viaR2ClientDocsStore(list/get/head/put/delete). The tenant slug is derived fromctx.containerId(customer-<slug>) and validated withsanitizeCustomerSlug.GET/HEAD /<name>,PUT /<name>,DELETE /<name>,GET /(list);503without a binding,400when the slug cannot be resolved.- R2 credentials deprecated for the container —
gateway/env.tsno longer forwardsR2_ACCESS_KEY_ID/R2_SECRET_ACCESS_KEYinto the sandbox (they remain Worker bindings for the SDK presigned-URL backup path). Seeapps/fouria/src/gateway/env.test.ts. - Tests —
apps/fouria/src/sandbox-r2-bridge.test.ts,apps/fouria/src/sandbox-docs-bridge.test.ts,apps/fouria/src/index.test.ts,apps/fouria/src/gateway/env.test.ts. - Docs —
apps/fouria/docs/WORKER-DEVELOPMENT.md§“Sandbox → R2 Connectivity”.
Storage layout (in the tenant bucket, which lerma provisions as
fouria-backup-<slug> — already tenant-isolated):
releases/<key> e.g. releases/v0.1.0/tarjetero.bundle1.3 Current R2 access inventory (migration surface)
| Flow | Access path today | Container sees R2 creds? | Migration target |
|---|---|---|---|
| Backups / restore | SDK createBackup/restoreBackup presigned URLs + Worker F4E1 | S3 creds injected as secret_text bindings | Keep — snapshots are purpose-built (COW/FUSE); do not port to outboundByHost |
Client docs (fouria-docs) | docs.r2.internal bridge (on-demand) + optional materializeClientDocsIfDev | No | Done (stable) — migration carries it over and retires materialization |
Secrets (R2SecretsStore) | Worker-side F4E1 in BACKUP_BUCKET | No | Optional follow-up |
| Release bundles (this feature) | outboundByHost → releases/ | No | Done (stable) |
1.4 Migration constraints to preserve
outboundByHostis host-keyed and per-class. Keep the same virtual host (releases.r2.internal, and a newdocs.r2.internalfor docs) and the same handler signatures.- Unmatched traffic must still passthrough via the catch-all
outbound. Do not replace it with an allowlist-only handler. - Tenant scoping lives in the handler (path sanitization + the per-tenant bucket binding). Never trust the sandbox-requested path.
- Memory-bounded uploads — keep the
FixedLengthStream+content-lengthpattern forPUT. - Backups stay on the SDK presigned path. Only the docs/release flows move
to
outboundByHost.
2. Ready-to-use prompt — carry the R2 bridges onto SDK 1.0
Copy the block below verbatim into the Sandbox SDK 1.0 migration agent (the agent working PR #306).
You are completing the fouria Sandbox SDK 1.0 migration (PR #306,
`feat/sandbox-sdk-1.0`, `@cloudflare/sandbox@0.13.0-next`).
TASK: carry the already-implemented stable-SDK R2 bridges (release +
client-docs) and the R2-credential deprecation onto `@cloudflare/sandbox@next`,
and retire Worker-side docs materialization now that the sandbox fetches docs
on demand.
REFERENCE IMPLEMENTATION (read first, do not break it):
- apps/fouria/src/sandbox-r2-bridge.ts (release bridge: GET/HEAD/PUT/DELETE +
`GET /` list, path sanitization, FixedLengthStream uploads, 503 when unbound)
- apps/fouria/src/sandbox-docs-bridge.ts (client-docs bridge: list/get/head/put/
delete over R2ClientDocsStore, slug derived from ctx.containerId)
- apps/fouria/src/index.ts (Sandbox.outboundByHost registration + catch-all
Sandbox.outbound passthrough)
- apps/fouria/src/sandbox-r2-bridge.test.ts, sandbox-docs-bridge.test.ts,
index.test.ts, gateway/env.test.ts
- apps/fouria/src/gateway/env.ts (R2 S3 credential NOT forwarded to container)
- apps/fouria/docs/WORKER-DEVELOPMENT.md §"Sandbox → R2 Connectivity"
- docs/plans/sandbox-sdk-1.0-r2-migration.md (this report)
CONTEXT — current docs flow:
- apps/fouria/src/services/fouria-docs/R2ClientDocsStore.ts stores docs at
`customers/<slug>/docs/<path>` in the tenant BACKUP_BUCKET (plaintext).
- apps/fouria/src/services/fouria-docs/materialize.ts
(materializeClientDocsIfDev) currently READS R2 in the Worker and WRITES the
files into `/home/openclaw/clawd/client-docs/` via sandbox.writeFile/exec.
- The dev-only admin API is /api/admin/fouria-docs (routes/api/fouria-docs.ts).
REQUIRED WORK:
1. Confirm `static outboundByHost` is unchanged in `@cloudflare/sandbox@next`
(0.13.0-next) and that the reference bridge still compiles/behaves. If the
API changed, record the exact diff in this file and adapt.
2. Carry over the `docs.r2.internal` handler from
`apps/fouria/src/sandbox-docs-bridge.ts` and the release bridge from
`sandbox-r2-bridge.ts`; verify both compile/behave under `@next`.
3. Confirm the tenant-slug derivation (`ctx.containerId` -> `customer-<slug>`)
is unchanged in `@next`; keep the cross-tenant isolation tests.
4. Retire Worker-side `materializeClientDocsIfDev` (or keep it behind a flag):
the sandbox fetches docs on demand via `docs.r2.internal`. Update the Fouria
Builder workspace persona/docs paths. Do NOT remove the admin API write path.
5. Preserve security posture: keep the R2 S3 credential out of the container env
(deprecated in `gateway/env.ts`), traversal sanitization, bounded-memory
uploads, catch-all passthrough intact.
6. Tests: keep the bridge unit tests green (mock R2 bucket: list/get/put/delete,
traversal rejection, 503) and the index.test.ts host-registration assertions.
Keep coverage ≥ 80%.
7. Docs: update apps/fouria/docs/WORKER-DEVELOPMENT.md, docs/ENV-VARIABLES.md
and this report's status. Run
`bun run format:check && bun run lint && bun run typecheck && bun run test`
plus `cctr apps/fouria/test/business-rules/`.
DO NOT MIGRATE:
- Backups/restore (keep the SDK `createBackup`/`restoreBackup` presigned path).
- Anything that would place R2 credentials inside the container.
ACCEPTANCE:
- Both bridges registered; sandbox reads/writes docs and release bundles with no
credentials; container env carries no R2 credentials; release + docs bridges
green; full test suite green; docs updated.
- Report back with: the `@cloudflare/sandbox@next` version, any API diff vs the
stable reference, files changed, and test output.
3. Issue linkage
Track this hand-off in issue #309,
which links the SDK 1.0 migration
PR #306 to the stable
outboundByHost implementation added here.