Repository navigation
feat(runtime): serve queries and sockets from the caller's region - #394
Conversation
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
✅ Deploy Preview for lunorash ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Thank you for following the naming conventions! 🙏 |
|
Warning Review limit reached
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 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 configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: ⛔ Files ignored due to path filters (5)
📒 Files selected for processing (6)
WalkthroughAdds 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. ChangesRegional replica flow
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
Possibly related PRs
Suggested labels: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
|
Thank you for confirming the Contributor License Agreement! 🙏 |
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (2)
packages/shard-engine/src/replica.ts (2)
36-40: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueRemove 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 winRun the replica-state migration once per DO, not per read.
readReplicaStateandwriteReplicaStateboth callmigrateReplicaState, so every freshness check issues aCREATE TABLE IF NOT EXISTSbefore itsSELECT.ensureFreshcallsisCaughtUpon the fast path of every replica-routed read, andappliedSeq()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.sqlreturns a freshProxyper 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
⛔ Files ignored due to path filters (14)
api-snapshots/lunora.api.mdis excluded by none and included by noneapi-snapshots/platform.api.mdis excluded by none and included by noneapi-snapshots/runtime.api.mdis excluded by none and included by noneapi-snapshots/shard-engine.api.mdis excluded by none and included by nonepackages/client/__tests__/replica-bookmark.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/do/__tests__/shard-do.replica-role.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/runtime/__tests__/create-worker.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/runtime/__tests__/region-hint.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/runtime/__tests__/resolve-shard.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/runtime/__tests__/security-headers.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/runtime/__tests__/workerd/placement.workerd.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/shard-engine/__tests__/replica.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**shared/region-hint.tsis excluded by none and included by noneshared/replica-name.tsis excluded by none and included by none
📒 Files selected for processing (17)
apps/docs/src/content/docs/concepts/read-replicas.mdxapps/docs/src/content/docs/meta.jsonpackages/client/src/lunora-client.tspackages/do/src/shard-do.tspackages/platform-cloudflare/src/cloudflare-host.tspackages/platform/src/capabilities.tspackages/platform/src/index.tspackages/platform/src/shard-directory.tspackages/runtime/src/create-worker.tspackages/runtime/src/resolve-shard.tspackages/runtime/src/security-headers.tspackages/shard-engine/docs/index.mdxpackages/shard-engine/src/env-int.tspackages/shard-engine/src/index.tspackages/shard-engine/src/relay-hub.tspackages/shard-engine/src/replica.tspackages/shard-engine/src/sibling-channel.ts
| 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(); | ||
| } | ||
|
|
There was a problem hiding this comment.
🗄️ 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.tsRepository: 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.tsRepository: 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 || trueRepository: 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'))))
PYRepository: 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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
🧩 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 || trueLength 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 -300Length 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:
- A batch writes with
shardKey: undefined. batch()records the cursor under"".- The next replica-eligible
query()uses the configured default shard name explicitly. cursorKeyFor()uses that explicit name, not"".- 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.
Merging this PR will not alter performance
Comparing Footnotes
|
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
|
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 Bootstrap cap applied after materializing — fixed. Partially numeric env values — fixed; the whole string must be an integer. Note this also tightens the relay knobs, which shared the helper.
Docs prerequisites — fixed; the page now lists all four conditions and points out that Memoize the replica-state DDL — fixed, per handle via a
Verification: 3,134 tests across the touched packages, types and lint clean, API snapshot updated for the |
`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 Report❌ Patch coverage is 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
🚀 New features to boost your workflow:
|
|
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. |
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
ShardDirectorycontract, andshardRegionpins 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. 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_logand answers one-shot queries locally. The changelog, its epoch, andapplyCdcChangeswere 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:
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
Access-Control-Expose-Headersanywhere, while the client readsx-d1-bookmarkoff 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.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.tsasserts 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
@lunora/studioReact 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
Documentation