Skip to content

feat(runtime): serve queries and sockets from the caller's region - #394

Merged
prisis merged 4 commits into
alphafrom
feat/region-local-reads
Aug 10, 2026
Merged

prisis merged 4 commits into
alphafrom
feat/region-local-reads

Conversation

@prisis

@prisis prisis commented Aug 9, 2026 •

Copy link
Copy Markdown
Member

A shard lives in exactly one place. That is what makes its writes serialized and its reads consistent — and it is why a reader on the other side of the world pays the round trip on every query, and holds a socket that terminates wherever the shard happens to live.

This adds three opt-in controls that move work closer to the reader. All are off by default; a single-region app is unaffected.

Placement

Shard resolution now carries an advisory region through the ShardDirectory contract, and shardRegion pins a shard by key:

createWorker({ shardDO: env.SHARD, shardRegion: (key) => tenantRegions[key] });

The platform already creates a shard near its first request, so this exists for the cases where that request is the wrong signal: a cron fire, a migration fan-out, a seeding run, the Studio. Those all land wherever they happened to run, and stay there for the shard's life.

Read replicas (replicaReads: true)

A …::replica::<region> Durable Object follows the owner's existing __cdc_log and answers one-shot queries locally. The changelog, its epoch, and applyCdcChanges were already there for point-in-time recovery and streaming export, which is why the follow loop is small.

Writes, streams, subscriptions, fan-out and admin stay on the owner. A replica also:

  • refuses anything the runtime did not explicitly mark as a read, so it never classifies a function path and never applies a write;
  • serves no subscriptions — its rows advance only when a read triggers a catch-up, so a live query from a replica would mostly not be live;
  • runs no background work. This one is not theoretical: an external-source pull resolves its tenant from the DO's own name, so on a replica a full pull would match nothing and diff every replicated row into a delete.

CDC is opt-in, so a shard without a changelog cannot be followed at all — the owner refuses the control channel rather than handing back a synthetic timeline a follower would agree with forever. A forked epoch, a compacted log, or a snapshot too large for one response likewise report unavailable, and reads fall back to the owner. Correct throughout; just not local.

Consistency

Read-your-writes is preserved per client, automatically. The server already echoed the cursor each write committed at; the client now remembers it per shard — including across a batched offline replay — and sends it back, and a replica that has not caught up sends the read to the owner instead of answering from an older copy. Catch-up is single-flighted, so a cold region bootstraps once rather than once per concurrent reader, and it stops at the first empty page so an unreachable cursor cannot amplify one read into ten cross-region round trips.

What you trade away is freshness for other people's writes: a read carrying no cursor may be up to LUNORA_REPLICA_MAX_STALENESS_MS (default 1000) behind.

Sockets near the client

A promoted shard now hints the client's region on the relay it routes to, so each relay is created where its traffic is. The spread across relays stays random deliberately — routing a whole region to one relay would pile a single-region app's entire connection load onto one DO, which is the fan-out wall promotion exists to escape.

Two pre-existing bugs found on the way

  • No Access-Control-Expose-Headers anywhere, while the client reads x-d1-bookmark off every mutation response. A browser hides non-safelisted response headers, so D1 read-your-writes has been silently inoperative for every cross-origin app. Fixed, along with three request headers the SDK sends that were missing from the allowlist.
  • The Cloudflare host dropped the placement argument while the capability matrix advertised shardPlacement: native — the contract/implementation drift the platform-parity rule exists to catch.

Not included

Collapsing a client's per-shard sockets onto one connection. That needs a relay role bound to many owners plus a client protocol change; it is called out as a gap in the docs.

A deliberate limitation

Placement does not compose with residency. Pairing a location hint with a jurisdiction type-checks, and it is unreachable on every runtime available: workerd implements no jurisdictions at all, so the combination cannot be exercised in dev, in CI, or in a test, and would first execute in production on the deployments that chose residency precisely because correctness matters most to them. A pinned deployment therefore sends no region hint and logs once. placement.workerd.test.ts asserts jurisdictions are unimplemented, so this fails the day that changes and the trade can be revisited.

Review

Both thermo-nuclear passes ran against the first commit; the second commit is the fixes. The one they agreed on was real: coercing "this shard has no changelog" to a sentinel let a replica bootstrap once and then agree with every empty page forever — serving a frozen snapshot while reporting itself fresh, on the default (CDC-off) shard shape.

Verification

  • New: 18 engine tests (CDC-off, single-flight, import errors, compaction, empty-page exit, end-to-end serve), 5 DO-role tests, 3 real-workerd placement tests, plus runtime and client coverage.
  • 3,178 tests pass across the touched packages, types clean, lint clean, API snapshots updated.
  • Full-suite runs show one @lunora/studio React Testing Library timeout, a different test each run, each passing in isolation — load-dependent flakiness in a package this branch does not touch.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features

    • Added region-aware shard placement and automatic relay placement for improved locality.
    • Added read replicas with CDC-based synchronization, bounded staleness, read-your-writes consistency, and owner fallback.
    • Added configuration options for replica reads and shard-region selection.
    • Added platform capability reporting for shard placement and read replicas.
    • Improved CORS support for sequencing and shard-related headers.
  • Documentation

    • Added comprehensive read-replica and shard-placement guidance, including costs, limitations, consistency, and configuration.
    • Documented replica modules and replication behavior.

prisis and others added 2 commits August 10, 2026 00:05
A shard lives in one place, so a distant reader pays the round trip on
every query and holds a socket that terminates wherever the shard happens
to live. Three opt-in controls close that gap.

Placement. Shard resolution carries an advisory region through the
`ShardDirectory` contract, and `shardRegion` pins a shard by key. The
platform already creates a shard near its first request, so this exists
for the cases where that request is the wrong signal: a cron fire, a
migration fan-out, a seeding run, the Studio.

Read replicas (`replicaReads: true`). A `…::replica::<region>` DO follows
the owner's `__cdc_log` and answers one-shot queries locally. Writes,
streams, subscriptions, fan-out and admin stay on the owner, and a
replica refuses anything the runtime did not mark as a read, so it never
classifies a function path and never applies a write. It also serves no
subscriptions and runs no background work: the owner's alarm tiers would
otherwise fire against a copy, and an external-source pull resolves its
tenant from the DO's own name — a full pull would diff every replicated
row into a delete.

CDC is opt-in, so a shard without a changelog cannot be followed at all;
the owner refuses the control channel rather than handing back a
synthetic timeline a follower would agree with forever. A forked epoch, a
compacted log, or a snapshot too large for one response likewise report
unavailable, and reads fall back to the owner.

Read-your-writes rides the `commitCursor` the server already echoed: the
client remembers it per shard — including across a batched offline replay
— and sends `x-lunora-min-seq`, which one shared parser defines for both
ends. A replica behind that cursor answers 421 and the runtime retries the
owner once. Catch-up is single-flighted, so a cold region bootstraps once
rather than once per concurrent reader, and it stops at the first empty
page so an unreachable cursor cannot amplify one read into ten
cross-region round trips.

Sockets. A promoted shard hints the client's region on the relay it
routes to, so each relay is created where its traffic is. The spread
across relays stays random: routing a whole region to one relay would
pile a single-region app's entire connection load onto one DO, which is
the fan-out wall promotion exists to escape.

Not included: collapsing a client's per-shard sockets onto one
connection. That needs a relay role bound to many owners plus a client
protocol change, and it is called out as a gap in the docs.

The DO-to-DO control channel's namespace resolution, HMAC and
constant-time verify move to `sibling-channel.ts` and both tiers route
through it, so the replica hop reuses the relay's authentication instead
of carrying a second copy of it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KBeSX2o4sTCPjVDRDWkVQG
Three related gaps, all of which failed silently.

A browser hides every non-safelisted response header unless the server
names it in `access-control-expose-headers`, and there was no such header
at all — so `x-d1-bookmark`, which the client reads back on every
mutation, has been unreadable cross-origin, and D1 read-your-writes has
been quietly inoperative for any app on a separate frontend domain. The
exposed list now names the headers the SDK actually consumes.

That unblocks the correct fix for the replica bookmark's shard key. A
caller that omits `shardKey` and one that spells out the worker's
configured default reach the same shard, but only the worker knows they
are the same — so it stamps the key it resolved, and the client files one
cursor for that shard instead of two. A cursor recorded before the name
was known is folded in rather than stranded.

Placement no longer composes with residency. Pairing a location hint with
a jurisdiction type-checks, and it is unreachable on every runtime we can
run: workerd implements no jurisdictions at all, so the combination
cannot be exercised in dev, in CI, or in a test, and would first execute
in production on the deployments that chose residency precisely because
correctness matters most to them. A pinned deployment therefore sends no
region hint and lets the jurisdiction decide, and says so once rather
than leaving an operator to wonder why `shardRegion` reads as ignored.

The new workerd suite pins what a mock cannot: that the real runtime
accepts a hint, that a hinted resolution addresses the same object as an
unhinted one, and that jurisdictions are unimplemented there — the last
so the trade above can be revisited the day that changes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KBeSX2o4sTCPjVDRDWkVQG
@netlify

netlify Bot commented Aug 9, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for lunorash ready!

Name Link
🔨 Latest commit 1710140
🔍 Latest deploy log https://app.netlify.com/projects/lunorash/deploys/6a790a1b60eba400087d046f
😎 Deploy Preview https://deploy-preview-394--lunorash.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Thank you for following the naming conventions! 🙏

@coderabbitai

coderabbitai Bot commented Aug 9, 2026 •

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@prisis, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 44 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 29ad3562-3a56-42e2-94c5-4fd52351cdb3

📥 Commits

Reviewing files that changed from the base of the PR and between 6f92397 and 1710140.

⛔ Files ignored due to path filters (5)
  • api-snapshots/errors.api.md is excluded by none and included by none
  • api-snapshots/shard-engine.api.md is excluded by none and included by none
  • packages/client/__tests__/replica-bookmark.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
  • packages/runtime/__tests__/create-worker.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
  • packages/shard-engine/__tests__/replica.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
📒 Files selected for processing (6)
  • apps/docs/src/content/docs/concepts/read-replicas.mdx
  • packages/client/src/lunora-client.ts
  • packages/do/src/shard-do.ts
  • packages/errors/src/catalog.ts
  • packages/shard-engine/src/env-int.ts
  • packages/shard-engine/src/replica.ts

Walkthrough

Adds region-aware shard placement and CDC-backed read replicas. Replica routing supports freshness checks, read-your-writes cursors, owner fallback, authenticated replication, and relay placement.

Changes

Regional replica flow

Layer / File(s) Summary
Placement contracts and resolution
packages/platform/..., packages/platform-cloudflare/..., packages/runtime/src/resolve-shard.ts, packages/runtime/src/create-worker.ts
Adds ShardRegionHint, capability declarations, region-aware shard lookup, jurisdiction handling, and relay placement hints.
Shared sibling channel
packages/shard-engine/src/sibling-channel.ts, packages/shard-engine/src/relay-hub.ts, packages/shard-engine/src/env-int.ts, packages/shard-engine/docs/index.mdx
Centralizes sibling lookup, HMAC signing, signature verification, and positive-integer environment parsing.
CDC replica lifecycle
packages/shard-engine/src/replica.ts, packages/shard-engine/src/index.ts, packages/do/src/shard-do.ts
Adds owner and follower replication, bootstrap, CDC catch-up, durable replica state, divergence detection, freshness gating, control requests, and replica-specific DO behavior.
Replica routing and client sequencing
packages/runtime/src/create-worker.ts, packages/client/src/lunora-client.ts, packages/runtime/src/security-headers.ts
Routes eligible queries to replicas, forwards minimum CDC sequences, falls back on 421, records commit cursors, and exposes required CORS headers.
Replica documentation
apps/docs/src/content/docs/concepts/read-replicas.mdx, apps/docs/src/content/docs/meta.json
Documents placement, replica reads, consistency behavior, relay placement, limitations, and related concepts.

Estimated code review effort: 5 (Critical) | ~120 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant Worker
  participant Replica
  participant Owner
  Client->>Worker: Query with x-lunora-min-seq
  Worker->>Replica: Route eligible regional read
  Replica->>Owner: Catch up through authenticated CDC control channel
  Owner-->>Replica: Return CDC changes and cursor
  Replica-->>Worker: Return fresh response or 421
  Worker-->>Owner: Fallback query when replica is unavailable
  Worker-->>Client: Return response with shard key
Loading

Possibly related PRs

  • anolilab/lunora#37: Extends the same client and shard paths with replica-aware reads and CDC cursor propagation.
  • anolilab/lunora#78: Shares relay, ShardDO, and runtime routing infrastructure with this replica work.
  • anolilab/lunora#328: Shares shard resolution and worker routing changes.

Suggested labels: package: replica

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly describes the main regional query and socket routing changes.
Description check ✅ Passed The description gives a detailed summary, design constraints, review notes, verification results, and test coverage for the requested changes.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/region-local-reads

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Thank you for confirming the Contributor License Agreement! 🙏

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 5

🧹 Nitpick comments (2)
packages/shard-engine/src/replica.ts (2)

36-40: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Remove the ponytail: markers from the published doc comments.

Lines 36 and 72 begin with ponytail:, which reads as an internal annotation rather than documentation. These comments ship in the package source. Rewrite them as plain prose, or track them as TODOs.

Do you want me to open an issue for the two follow-ups they describe (a reset/re-bootstrap path, and a paginated bootstrap)?

Also applies to: 72-72

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/shard-engine/src/replica.ts` around lines 36 - 40, Remove the
“ponytail:” prefixes from the doc comments around the replica behavior and
bootstrap follow-up notes, rewriting each marker as plain prose while preserving
the existing meaning; do not add TODO markers unless the project’s established
convention requires them.

183-216: 🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick win

Run the replica-state migration once per DO, not per read.

readReplicaState and writeReplicaState both call migrateReplicaState, so every freshness check issues a CREATE TABLE IF NOT EXISTS before its SELECT. ensureFresh calls isCaughtUp on the fast path of every replica-routed read, and appliedSeq() adds more calls. Memoize the migration per SQL handle so the hot read path runs one statement.

♻️ Proposed fix: memoize the DDL per handle
+const migratedHandles = new WeakSet<object>();
+
 const migrateReplicaState = (sql: SqlExec): void => {
+    if (migratedHandles.has(sql as unknown as object)) {
+        return;
+    }
+
     sql.exec(
         `CREATE TABLE IF NOT EXISTS ${REPLICA_STATE_TABLE} (
             id INTEGER PRIMARY KEY CHECK (id = 1),
             epoch TEXT NOT NULL,
             applied_seq INTEGER NOT NULL,
             synced_at REAL NOT NULL
         )`,
     );
+
+    migratedHandles.add(sql as unknown as object);
 };

Note: ShardDO.sql returns a fresh Proxy per access during a dispatch, so key the memo on the raw handle the host supplies, or hold the flag on the replica/owner host instead.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/shard-engine/src/replica.ts` around lines 183 - 216, Memoize
replica-state schema migration once per underlying SQL handle instead of
invoking migrateReplicaState from every readReplicaState and writeReplicaState
call. Update the migration state near migrateReplicaState to key by the raw
host-provided handle, not the fresh Proxy returned by ShardDO.sql, and skip
CREATE TABLE execution after that handle has been initialized.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/docs/src/content/docs/concepts/read-replicas.mdx`:
- Around line 47-57: Update the replicaReads example and surrounding
documentation to include a registered query function in the worker’s functions
configuration, and state that requests must provide a region hint for replica
routing. Clarify that replicaReads alone does not select a replica and that
unregistered/non-query functions or regionless requests fall back to the shard
owner.

In `@packages/client/src/lunora-client.ts`:
- Around line 4188-4205: Update batch() to carry each entry’s resolved shard key
and minimum cursor rather than relying on one request-level x-lunora-min-seq
value. Return the canonical shard key in every result slot alongside id/body,
and record each successful mutation’s cursor in shardCursors using that resolved
key. Reuse rpcRequestHeaders and cursorKeyFor for consistent cursor handling.

In `@packages/shard-engine/src/env-int.ts`:
- Around line 15-21: Update the parsing logic in the environment-value helper
around the raw string and parsed validation so string inputs must be entirely
decimal integer text before conversion, rejecting values such as “10ms” and
“1.5”; then require the resulting value to be a safe positive integer and return
fallback otherwise. Preserve direct numeric handling while applying the same
safe-positive-integer validation.

In `@packages/shard-engine/src/replica.ts`:
- Around line 267-280: Update the ReplicaOwnerHost contract and the
replica_bootstrap branch to perform a bounded row-count or capped export using
maxBootstrapRows(host.env()) before materializing the full snapshot. Refuse
over-cap shards with the existing truncated response, and only call the full
export path when the pre-check confirms the snapshot fits within the limit.
- Around line 245-256: Make replica control fail closed when LUNORA_RELAY_SECRET
is absent: update verifySiblingBody or the handleReplicaControl path so missing
configuration rejects requests rather than treating them as valid. Preserve
signed-request verification and ensure unsigned replica_bootstrap and
replica_pull frames cannot be accepted.

---

Nitpick comments:
In `@packages/shard-engine/src/replica.ts`:
- Around line 36-40: Remove the “ponytail:” prefixes from the doc comments
around the replica behavior and bootstrap follow-up notes, rewriting each marker
as plain prose while preserving the existing meaning; do not add TODO markers
unless the project’s established convention requires them.
- Around line 183-216: Memoize replica-state schema migration once per
underlying SQL handle instead of invoking migrateReplicaState from every
readReplicaState and writeReplicaState call. Update the migration state near
migrateReplicaState to key by the raw host-provided handle, not the fresh Proxy
returned by ShardDO.sql, and skip CREATE TABLE execution after that handle has
been initialized.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 83818e0b-b754-45f8-8ed3-38cfeb1f17ec

📥 Commits

Reviewing files that changed from the base of the PR and between e4fea4d and 6f92397.

⛔ Files ignored due to path filters (14)
  • api-snapshots/lunora.api.md is excluded by none and included by none
  • api-snapshots/platform.api.md is excluded by none and included by none
  • api-snapshots/runtime.api.md is excluded by none and included by none
  • api-snapshots/shard-engine.api.md is excluded by none and included by none
  • packages/client/__tests__/replica-bookmark.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
  • packages/do/__tests__/shard-do.replica-role.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
  • packages/runtime/__tests__/create-worker.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
  • packages/runtime/__tests__/region-hint.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
  • packages/runtime/__tests__/resolve-shard.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
  • packages/runtime/__tests__/security-headers.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
  • packages/runtime/__tests__/workerd/placement.workerd.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
  • packages/shard-engine/__tests__/replica.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
  • shared/region-hint.ts is excluded by none and included by none
  • shared/replica-name.ts is excluded by none and included by none
📒 Files selected for processing (17)
  • apps/docs/src/content/docs/concepts/read-replicas.mdx
  • apps/docs/src/content/docs/meta.json
  • packages/client/src/lunora-client.ts
  • packages/do/src/shard-do.ts
  • packages/platform-cloudflare/src/cloudflare-host.ts
  • packages/platform/src/capabilities.ts
  • packages/platform/src/index.ts
  • packages/platform/src/shard-directory.ts
  • packages/runtime/src/create-worker.ts
  • packages/runtime/src/resolve-shard.ts
  • packages/runtime/src/security-headers.ts
  • packages/shard-engine/docs/index.mdx
  • packages/shard-engine/src/env-int.ts
  • packages/shard-engine/src/index.ts
  • packages/shard-engine/src/relay-hub.ts
  • packages/shard-engine/src/replica.ts
  • packages/shard-engine/src/sibling-channel.ts

Comment on lines +4188 to +4205
private rpcRequestHeaders(
flags: { attachBookmark?: boolean; clientId?: string; clientSeq?: number; mutationId?: string },
shardKey?: string,
): Record<string, string> {
const headers: Record<string, string> = { "content-type": "application/json" };

// Read-your-writes across region-local read replicas: the cursor this
// client's last write to this shard committed at. A worker with
// `replicaReads` on will only answer from a replica that has caught up
// to it; everywhere else the header is inert. Sent on every call rather
// than only on reads — a write is routed to the owner regardless, so
// there is no branch here that could get the two out of step.
const shardCursor = this.shardCursors.get(this.cursorKeyFor(shardKey));

if (shardCursor !== undefined) {
headers["x-lunora-min-seq"] = shardCursor.toString();
}

@coderabbitai coderabbitai Bot Aug 9, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

ast-grep outline packages/runtime/src/create-worker.ts --items all
rg -n -C 5 'rpc-batch|commitCursor|x-lunora-min-seq|x-lunora-shard-key|shardKey' \
  packages/client/src/lunora-client.ts \
  packages/runtime/src/create-worker.ts

Repository: anolilab/lunora

Length of output: 50372


🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf 'Relevant outlines\n'
ast-grep outline packages/client/src/lunora-client.ts --match LunoraClient --view expanded || true
ast-grep outline packages/runtime/src/batch.ts --items all || true

printf '\nBatch wire type\n'
fd -a 'batch-wire|batch' shared packages | sed 's#^\./##' | head -80

printf '\nSearch focused symbols\n'
rg -n -C 6 'rpcRequestHeaders|commitCursor|x-lunora-min-seq|rpc-batch|RPC_BATCH_PATH|groupBatchCallsByShard|BatchEntry|shardKey' \
  packages/client/src/lunora-client.ts \
  packages/client/src \
  packages/shared/shared/batch-wire.ts \
  shared/batch-wire.ts \
  packages/runtime/src/create-worker.ts \
  packages/runtime/src/batch.ts \
  2>/dev/null || true

printf '\nClient relevant line ranges\n'
sed -n '720,800p' packages/client/src/lunora-client.ts
sed -n '4140,4235p' packages/client/src/lunora-client.ts
sed -n '4235,4335p' packages/client/src/lunora-client.ts

printf '\nRuntime batch/worker relevant line ranges\n'
sed -n '1,220p' packages/runtime/src/batch.ts
sed -n '2310,2380p' packages/runtime/src/create-worker.ts
sed -n '3550,3680p' packages/runtime/src/create-worker.ts

Repository: anolilab/lunora

Length of output: 50374


🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf 'Client batch/rpc ranges\n'
sed -n '1838,1910p' packages/client/src/lunora-client.ts
sed -n '600,695p' packages/client/src/lunora-client.ts
sed -n '4160,4320p' packages/client/src/lunora-client.ts

printf '\nBatch wire\n'
fd -a 'batch-wire\.ts' . | sed 's#^\./##'
for f in $(fd -a 'batch-wire\.ts' .); do
  echo "--- $f"
  wc -l "$f"
  sed -n '1,240p' "$f"
done

printf '\nRuntime batch grouping and dispatch ranges\n'
sed -n '1,180p' packages/runtime/src/batch.ts
sed -n '2316,2365p' packages/runtime/src/create-worker.ts
sed -n '3585,3675p' packages/runtime/src/create-worker.ts

printf '\nFocused min-seq usage in runtime\n'
rg -n -C 5 'x-lunora-min-seq|minSeq|min-seq|replicaReads|replica' packages/runtime/src/shared packages/runtime/src create-worker.ts runtime 2>/dev/null | head -200 || true

Repository: anolilab/lunora

Length of output: 44726


🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf 'Runtime handleBatchRpc range\n'
rg -n 'handleBatchRpc|handleRpc|returnRpc|forwardRpcToShard|lastMutationId|commitCursor' packages/runtime/src/create-worker.ts
sed -n '3700,3756p' packages/runtime/src/create-worker.ts

printf '\nRead-only client batch behavior probe\n'
python3 - <<'PY'
from pathlib import Path
import re

path = Path("packages/client/src/lunora-client.ts")
text = path.read_text()

def extract_range(label, pat):
    m = re.search(pat, text, re.S)
    return text[m.start():m.start()+len(m.group(0))] if m else None

batch = extract_range("batch", r'public async batch\(calls:[\s\S]*?return demuxBatchResults\(body\.results \?\? \[\], calls\.length\);')
rpc = extract_range("rpc", r'private async rpc\([\s\S]*?this\.recordShardCursor\(shardKey, body\.commitCursor\);')

print("batch has rpcRequestHeaders:", bool(re.search(r'rpcRequestHeaders', batch)))
print("rpc has recordShardCursor:", bool(re.search(r'recordShardCursor', rpc)))
print("batch records shard cursors:", bool(re.search(r'recordShardCursor|shardCursors|commitCursor', batch)))
print("batch uses response commitCursor:", bool(re.search(r'commitCursor', batch)))
print("demux ignores commitCursor:", bool(re.search(r'commitCursor', extract_range("demux", r'const demuxBatchResults[\s\S]*?return slots\.map'))))
PY

Repository: anolilab/lunora

Length of output: 5213


Preserve replica freshness for batch().

batch() sends one x-lunora-min-seq and returns only id/body per slot. Entries sent to different shards can also carry different resolved shard keys, so the next request can miss the per-shard cursor state needed to satisfy replica reads.

Extend the batch request with per-entry minimum cursors/shard keys, return canonical shard keys in each result slot, and record successful mutation cursors per entry keyed by its resolved shard.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/client/src/lunora-client.ts` around lines 4188 - 4205, Update
batch() to carry each entry’s resolved shard key and minimum cursor rather than
relying on one request-level x-lunora-min-seq value. Return the canonical shard
key in every result slot alongside id/body, and record each successful
mutation’s cursor in shardCursors using that resolved key. Reuse
rpcRequestHeaders and cursorKeyFor for consistent cursor handling.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Half fixed, half declined — and the declined half is the wire change, so worth being explicit.

Fixed in 46afac9: batch() now records each entry's commit cursor under that entry's own shard key. Previously it recorded nothing at all, so a batched write left no read-your-writes requirement behind — the gap you identified is real, and this is where it actually bit.

for (const entry of body.results ?? []) {
    const commitCursor = (entry.body as { commitCursor?: unknown } | undefined)?.commitCursor;

    if (typeof entry.id === "number" && typeof commitCursor === "number") {
        this.recordShardCursor(calls[entry.id]?.shardKey, commitCursor);
    }
}

Read off the raw envelopes because demuxBatchResults keeps only the result value.

Declined: per-entry x-lunora-min-seq and canonical shard keys in the result slots. Batch dispatch is never replica-served. handleBatchRpc forwards through forwardToShard (create-worker.ts), not the replica-aware forwardRpcToShard, so every entry — read or write — goes to the owner shard. A per-entry freshness requirement would constrain a hop that is already strongly consistent, and canonical keys in the slots would be paid for on every batch to fix a mismatch that cannot occur there.

What the recorded cursors do constrain is the single reads that follow, which are the ones eligible for a replica. That path already resolves its key through cursorKeyFor, and the canonical-key round trip lives on the single-call response (x-lunora-shard-key).

If batch dispatch ever becomes replica-eligible, the per-entry wire fields become necessary and this reasoning stops holding — noted in a comment at the call site so it is not re-derived from scratch.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '== Current revision =='
git rev-parse --short HEAD

printf '%s\n' '== Client batch and cursor handling =='
ast-grep outline packages/client/src/lunora-client.ts --match LunoraClient --view expanded
rg -n -C 8 'public async batch\(|recordShardCursor\(|cursorKeyFor\(|rpcRequestHeaders\(' packages/client/src/lunora-client.ts

printf '%s\n' '== Runtime batch routing =='
ast-grep outline packages/runtime/src/create-worker.ts --items all --match 'handleBatchRpc|forwardRpcToShard|forwardToShard'
rg -n -C 12 'handleBatchRpc|forwardRpcToShard|forwardToShard|replicaReads|x-lunora-min-seq' packages/runtime/src/create-worker.ts packages/runtime/src/batch.ts 2>/dev/null || true

Length of output: 80003


🏁 Script executed:

#!/bin/bash
set -euo pipefail

sed -n '4070,4190p' packages/runtime/src/create-worker.ts

printf '%s\n' '== Canonical shard-key response handling =='
rg -n -C 6 'x-lunora-shard-key|defaultShardKey|learnDefaultShardKey|responseHeaders' \
  packages/runtime/src/create-worker.ts \
  packages/client/src/lunora-client.ts \
  shared \
  packages 2>/dev/null | head -300

Length of output: 31624


@prisis, the per-entry freshness-header part does not apply. handleBatchRpc routes each sub-batch through forwardToShard, so batch entries are owner-served. The per-entry cursor recording in batch() fixes the missing write cursor.

The canonical-key part still applies.

handleBatchRpc returns only content-type and an optional x-d1-bookmark. It does not return x-lunora-shard-key or an equivalent per-entry canonical key. LunoraClient learns defaultShardKey only from a single-RPC response.

This sequence still loses the cursor requirement:

  1. A batch writes with shardKey: undefined.
  2. batch() records the cursor under "".
  3. The next replica-eligible query() uses the configured default shard name explicitly.
  4. cursorKeyFor() uses that explicit name, not "".
  5. The query omits x-lunora-min-seq.

The reverse spelling has the same issue. A batch write with the explicit default name followed by an implicit single query also misses the cursor until a single RPC supplies x-lunora-shard-key.

The requested wire change can stay limited to canonical shard-key propagation. Per-entry minimum cursors are not needed while batches remain owner-served. The current comment remains unresolved for that aliasing case.

🐇🔍


✏️ Learnings added
Learnt from: prisis
Repo: anolilab/lunora PR: 394
File: packages/client/src/lunora-client.ts:4206-4223
Timestamp: 2026-08-10T06:20:11.946Z
Learning: In `packages/runtime/src/create-worker.ts`, `handleBatchRpc` routes batch sub-requests through `forwardToShard`, so the current `/_lunora/rpc-batch` transport is owner-served and does not use replica-read routing. The replica-aware `forwardRpcToShard` path applies to single RPC dispatch.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

You are interacting with an AI system.

Comment thread packages/shard-engine/src/env-int.ts Resolved
Comment thread packages/shard-engine/src/replica.ts Resolved
Comment thread packages/shard-engine/src/replica.ts Resolved
@codspeed

codspeed Bot commented Aug 9, 2026 •

Copy link
Copy Markdown

Merging this PR will not alter performance

✅ 253 untouched benchmarks
⏩ 10 skipped benchmarks1


Comparing feat/region-local-reads (1710140) with alpha (6b0aba4)2

Open in CodSpeed

Footnotes

  1. 10 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

  2. No successful run was found on alpha (e4fea4d) during the generation of this report, so 6b0aba4 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

Review follow-ups, each of which made a guard weaker than it read.

The control channel now requires `LUNORA_RELAY_SECRET`. The relay channel
treats a missing secret as legacy network-trust because tightening it
would break deployments that predate it; replica reads have no such
history, and the prize differs in kind — a forged relay frame delivers a
bogus poke, a forged frame here returns every row of the shard. An
unconfigured deployment now gets no replication rather than an
unauthenticated snapshot endpoint.

The bootstrap cap is decided from a row count instead of from an
already-materialized snapshot. The cap exists to protect the owner's
memory budget, and measuring after `exportRows()` protected nothing: a
shard past the cap exhausted that budget producing rows nobody was
allowed to receive.

`envPositiveInt` requires the whole string to be an integer.
`Number.parseInt` stops at the first character it cannot use, so it read
`"1500ms"` as `1500` and `"1.5"` as `1` — silently accepting a value the
operator wrote wrong, at a number nobody chose.

`batch()` records each entry's commit cursor under its own shard. Batched
writes previously left no read-your-writes requirement behind at all. No
per-entry `x-lunora-min-seq`: the batch route forwards straight to the
owner and is never replica-served, so a per-entry freshness requirement
would constrain nothing.

The replica-state DDL runs once per handle rather than before every read,
which is the one path the tier exists to keep short.

The test harness now forwards the follower's real body and headers to the
owner instead of re-serializing the frame — it was dropping the signature,
which is why an authenticated channel exposed it.

Docs state the four conditions a read must satisfy to reach a replica.
`replicaReads: true` alone selects nothing: without `functions` the
registry cannot say which calls are queries, and every read stays on the
owner.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KBeSX2o4sTCPjVDRDWkVQG
@prisis

prisis commented Aug 9, 2026

Copy link
Copy Markdown
Member Author

Thanks — five of the seven were real, and two of those were guards that read stronger than they were. All fixed in 46afac9.

Fail closed when LUNORA_RELAY_SECRET is absent — fixed, and agreed on the reasoning: the relay channel's tolerance is back-compat for deployments predating the secret, and replica reads have no such history. An unconfigured deployment now gets no replication instead of an unauthenticated snapshot endpoint. Fixing this also exposed that the test harness was dropping the signature header entirely (it re-serialized the frame), so the channel is now exercised with the follower's real bytes.

Bootstrap cap applied after materializing — fixed. ReplicaOwnerHost gained rowCount() (a COUNT(*) per table) and the refusal happens before exportRows(). The new test asserts the snapshot was never built, not merely that the read was refused.

Partially numeric env values — fixed; the whole string must be an integer. Note this also tightens the relay knobs, which shared the helper.

batch() cursors — fixed on the recording side: each entry's cursor is now filed under its own shard, so batched writes stop leaving no requirement behind. I did not add per-entry x-lunora-min-seq to the wire: the batch route forwards straight to the owner shard (forwardToShard, not the replica-aware forwardRpcToShard), so batch dispatch is never replica-served and a per-entry freshness requirement would constrain nothing.

Docs prerequisites — fixed; the page now lists all four conditions and points out that functions is what makes anything eligible.

Memoize the replica-state DDL — fixed, per handle via a WeakSet.

ponytail: markers — keeping these. They are an existing convention in this repo, not new here: packages/notify/src/providers.ts, packages/shard-engine/src/sql-projection.ts and packages/shard-engine/src/reprojection-backfill.ts all carry them on alpha today. Removing them from these two lines would make this file the inconsistent one.

Verification: 3,134 tests across the touched packages, types and lint clean, API snapshot updated for the rowCount addition.

`REPLICA_READ_ONLY` and `REPLICA_NOT_READY` were minted in the replica
tier without catalog entries, which the registration gate rejects: an
unregistered code carries no status or title, so every surface that
renders one — the CLI, the Vite overlay, the Studio — falls back to a
bare string.

Both map to `421`, the honest status for what they are: routing verdicts
the runtime turns into one retry against the owner, never something a
caller sees.

Also reformats two test files that eslint's autofix rewrote after
Prettier had already passed over them.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KBeSX2o4sTCPjVDRDWkVQG
@codecov-commenter

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 90.76923% with 30 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.14%. Comparing base (95d33d6) to head (1710140).
⚠️ Report is 132 commits behind head on alpha.

Files with missing lines Patch % Lines
packages/do/src/shard-do.ts 60.71% 11 Missing ⚠️
packages/runtime/src/create-worker.ts 89.79% 5 Missing ⚠️
packages/shard-engine/src/replica.ts 96.83% 5 Missing ⚠️
packages/client/src/lunora-client.ts 93.10% 2 Missing ⚠️
packages/shard-engine/src/relay-hub.ts 77.77% 2 Missing ⚠️
packages/shard-engine/src/sibling-channel.ts 93.10% 2 Missing ⚠️
...ackages/platform-cloudflare/src/cloudflare-host.ts 66.66% 1 Missing ⚠️
packages/runtime/src/resolve-shard.ts 80.00% 1 Missing ⚠️
packages/shard-engine/src/env-int.ts 88.88% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##            alpha     #394      +/-   ##
==========================================
+ Coverage   87.09%   87.14%   +0.04%     
==========================================
  Files        1172     1181       +9     
  Lines       63383    64007     +624     
  Branches    15447    15635     +188     
==========================================
+ Hits        55202    55776     +574     
- Misses       7654     7697      +43     
- Partials      527      534       +7     
Files with missing lines Coverage Δ
packages/errors/src/catalog.ts 98.50% <ø> (ø)
packages/platform/src/capabilities.ts 100.00% <ø> (ø)
packages/platform/src/shard-directory.ts 100.00% <100.00%> (ø)
packages/runtime/src/security-headers.ts 95.65% <100.00%> (+0.04%) ⬆️
...ackages/platform-cloudflare/src/cloudflare-host.ts 77.70% <66.66%> (+0.15%) ⬆️
packages/runtime/src/resolve-shard.ts 82.14% <80.00%> (+0.66%) ⬆️
packages/shard-engine/src/env-int.ts 88.88% <88.88%> (ø)
packages/client/src/lunora-client.ts 81.13% <93.10%> (+0.17%) ⬆️
packages/shard-engine/src/relay-hub.ts 65.61% <77.77%> (+0.38%) ⬆️
packages/shard-engine/src/sibling-channel.ts 93.10% <93.10%> (ø)
... and 3 more

... and 3 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@prisis
prisis merged commit 9be6dc9 into alpha Aug 10, 2026
48 checks passed
@prisis
prisis deleted the feat/region-local-reads branch August 10, 2026 06:20
@github-actions

github-actions Bot commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.
Please note this issue tracker is not a help forum. We recommend using our GitHub Discussions tab for questions.

@github-actions github-actions Bot locked as resolved and limited conversation to collaborators Sep 9, 2026

This branch was previously deployed

1 inactive deployment
benchmarks — 1710140c Deployed Aug 9, 2026 by prisis via Benchmarks #1628
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants