F FourIA latest 2026.10.29 GitHub ↗

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 into develop, and the release and client-docs R2 bridges now run on it: the pinned stable reference was uncommented and Sandbox.outboundByHost is registered in src/index.ts. The canonical static outboundByHost API 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 — handleReleasesR2Request maps HTTP onto the tenant BACKUP_BUCKET under a fixed releases/ prefix: GET / (list), GET/HEAD/PUT/DELETE /<key>. Keys are sanitized against traversal; PUT uses FixedLengthStream (bounded memory) when content-length is 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-all
  • apps/fouria/src/sandbox-docs-bridge.ts — handleDocsR2Request maps http://docs.r2.internal/... onto customers/<slug>/docs/ via R2ClientDocsStore (list/get/head/put/delete). The tenant slug is derived from ctx.containerId (customer-<slug>) and validated with sanitizeCustomerSlug. GET/HEAD /<name>, PUT /<name>, DELETE /<name>, GET / (list); 503 without a binding, 400 when the slug cannot be resolved.
  • R2 credentials deprecated for the container — gateway/env.ts no longer forwards R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY into the sandbox (they remain Worker bindings for the SDK presigned-URL backup path). See apps/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.bundle

1.3 Current R2 access inventory (migration surface)

FlowAccess path todayContainer sees R2 creds?Migration target
Backups / restoreSDK createBackup/restoreBackup presigned URLs + Worker F4E1S3 creds injected as secret_text bindingsKeep — snapshots are purpose-built (COW/FUSE); do not port to outboundByHost
Client docs (fouria-docs)docs.r2.internal bridge (on-demand) + optional materializeClientDocsIfDevNoDone (stable) — migration carries it over and retires materialization
Secrets (R2SecretsStore)Worker-side F4E1 in BACKUP_BUCKETNoOptional follow-up
Release bundles (this feature)outboundByHost → releases/NoDone (stable)

1.4 Migration constraints to preserve

  1. outboundByHost is host-keyed and per-class. Keep the same virtual host (releases.r2.internal, and a new docs.r2.internal for docs) and the same handler signatures.
  2. Unmatched traffic must still passthrough via the catch-all outbound. Do not replace it with an allowlist-only handler.
  3. Tenant scoping lives in the handler (path sanitization + the per-tenant bucket binding). Never trust the sandbox-requested path.
  4. Memory-bounded uploads — keep the FixedLengthStream + content-length pattern for PUT.
  5. 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.