[miniflare] Share local storage across processes via a single owner (experimental)

[penalosa]

What this does

Adds an experimental option to Miniflare that makes a single process own local storage for a given persist root, so multiple Miniflare instances (e.g. several wrangler dev / vite dev sessions) no longer each open the same SQLite/blob files — the root cause of cross-process SQLITE_BUSY errors under concurrent access.

When enabled:

• The first instance to find no published owner elects itself (via a per-persist-root spawn lock) and launches a detached "owner" process — a headless Miniflare that opens the files and hosts the storage services.
• Every instance then routes its storage operations to the owner over the remote-bindings boundary and skips standing up its own local storage. Only the owner performs storage I/O.
• The owner publishes its address to the persist root, heartbeats it, and self-terminates once no instances remain (startup grace + idle debounce). Crashed owners are reclaimed on the next election.

Transport

Routing reuses the existing remote-bindings boundary rather than a bespoke channel:

• fetch for KV, R2, D1 and Images.
• capnweb JSRPC for Streams and Secrets Store (these have no fetch entrypoint).

Bindings are repointed by id (type:id) against the owner server, so the owner avoids binding-name collisions across instances and resolves dynamic ids via an MF-Storage-Owner-Namespace request header. This replaces an earlier workerd-debug-port prototype and drops the previous unsafeDevRegistryPath requirement.

The owner-side server logic is shared with Wrangler's remote-bindings proxy server — both are thin adapters over one parameterised remote-bindings-proxy-server module (JSRPC-vs-fetch dispatch and the MF-Binding / MF-URL / MF-Header-* wire protocol), each supplying its own binding-resolution strategy.

What is and isn't shared

• Routed to the owner: KV, R2, D1, Images, Streams, Secrets Store.
• Kept per-instance (via isolateLocalStorage): Cache, Durable Objects, Workflows — when the feature is on and no explicit *Persist path is set, these use a per-instance temp path.
• An explicit *Persist path for a given type always takes precedence and excludes that type from routing.

This also lands a supporting refactor: storage and remote (mixed-mode) bindings now carry their per-resource config (namespace/bucket/database id, remote connection string) via ctx.props against a single shared object-entry / proxy service, instead of one workerd service per resource.

Validation

A high-concurrency oracle runs multiple instances against one persist root and asserts cross-instance sharing with exactly-correct results under contention:

• KV / R2 / D1 round-trips through the owner, including a D1 SQL round-trip and concurrent-write stress (60 concurrent D1 writes across 3 instances, exact final count).
• Streams (upload on A, listed on B), Secrets Store (created via A's admin API, read by a worker in B), and Images (binding usable in every instance).
• The full oracle (70 tests) is green under both direct Vitest and Turbo, with MINIFLARE_TEST_SHARED_OWNER added to turbo.json globalPassThroughEnv so it gates CI. The same tests also pass in baseline (feature-off) mode, where sharing is provided by the persist root.

Status — draft

Known follow-ups before this is review-ready:

• Liveness should be pid-authoritative; a busy-but-alive owner whose heartbeat goes stale could currently be treated as absent and double-spawned. Intend to convert the spawn lock into a lifetime-held exclusive lease.
• Register client presence before resolving routing (close a narrow teardown race).
• Exclude the Workers Sites KV binding from rewriting.
• Wrangler opt-in wiring; Windows validation.

---

• Tests
  • Tests included/updated
  • Automated tests not possible - manual testing has been completed as follows:
  • Additional testing not necessary because:
• Public documentation
  • Cloudflare docs PR(s):
  • Documentation not necessary because: the option is an internal/experimental unsafe* flag not intended for general use yet; user-facing docs will follow once the design stabilises and it is opted into by Wrangler.

[changeset-bot]

🦋 Changeset detected

Latest commit: ae287f4

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages

Name	Type
miniflare	Minor
@cloudflare/deploy-helpers	Patch
@cloudflare/pages-shared	Patch
@cloudflare/vite-plugin	Patch
@cloudflare/vitest-pool-workers	Patch
wrangler	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[ask-bonk]

UnknownError: ProviderInitError

github run

[ask-bonk]

@penalosa Bonk workflow failed. Check the logs for details.

View workflow run · To retry, trigger Bonk again.

[github-actions]

✅ All changesets look good

[pkg-pr-new]

@cloudflare/autoconfig

npm i https://pkg.pr.new/@cloudflare/autoconfig@14449

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@14449

@cloudflare/deploy-helpers

npm i https://pkg.pr.new/@cloudflare/deploy-helpers@14449

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@14449

miniflare

npm i https://pkg.pr.new/miniflare@14449

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@14449

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@14449

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@14449

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@14449

@cloudflare/workers-auth

npm i https://pkg.pr.new/@cloudflare/workers-auth@14449

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@14449

@cloudflare/workers-utils

npm i https://pkg.pr.new/@cloudflare/workers-utils@14449

wrangler

npm i https://pkg.pr.new/wrangler@14449

commit: ae287f4