Repository navigation
Conversation
✅ Deploy Preview for lunorash ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Thank you for confirming the Contributor License Agreement! 🙏 |
|
Thank you for following the naming conventions! 🙏 |
WalkthroughThe PR adds advisor support for detecting unbounded ChangesAdvisor query linting
Subscription frame delivery
Estimated code review effort: 4 (Complex) | ~60 minutes Sequence Diagram(s)sequenceDiagram
participant ShardDO
participant subscriptionFrames
participant trySendFrame
participant SubscriptionBaseline
ShardDO->>subscriptionFrames: provide previous baseline and current result
subscriptionFrames-->>ShardDO: return delta or snapshot frames
loop every frame
ShardDO->>trySendFrame: deliver frame
end
trySendFrame-->>ShardDO: report delivery status
ShardDO->>SubscriptionBaseline: advance baseline after all frames succeed
Possibly related PRs
🚥 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 |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
packages/shard-engine/src/subscription-delivery.ts (1)
345-347: 🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick winConsider stopping frame rendering once the deltas exceed the snapshot.
deltasis fully materialized before the size comparison. For the near-total-change case every row allocates an envelope string that is then discarded. Accumulate the running length during the render and abort as soon as it reachessnapshot.length. The chosen frame set stays identical, because the current rule already rejects deltas at that point.♻️ Proposed early-abort render
- const deltas = framed.map(({ frame }) => `{"type":"delta","id":${idJson},"delta":${frame}${suffix}}`); - - return deltas.reduce((total, frame) => total + frame.length, 0) < snapshot.length ? deltas : [snapshot]; + const deltas: string[] = []; + let total = 0; + + for (const { frame } of framed) { + const delta = `{"type":"delta","id":${idJson},"delta":${frame}${suffix}}`; + + total += delta.length; + + // Deltas can only grow from here, so the snapshot has already won. + if (total >= snapshot.length) { + return [snapshot]; + } + + deltas.push(delta); + } + + return deltas;🤖 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/subscription-delivery.ts` around lines 345 - 347, Update the frame-rendering logic around the deltas construction to accumulate rendered frame lengths while iterating and stop once the running total reaches snapshot.length. Preserve the existing selection rule and output: return all deltas only when their total length is strictly less than snapshot.length; otherwise return [snapshot], while avoiding materializing or retaining subsequent frames.
🤖 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 `@packages/shard-engine/__bench__/subscription-frames.bench.ts`:
- Around line 78-80: Hoist the reordered snapshot payload construction out of
the benchmark callback: precompute snapshotJson alongside the other benchmark
fixtures before the affected bench, then pass that variable to
subscriptionFrames. Keep the rejected-survivors benchmark focused on the
rejection path and preserve the existing snapshotJson setup for the other cases.
---
Nitpick comments:
In `@packages/shard-engine/src/subscription-delivery.ts`:
- Around line 345-347: Update the frame-rendering logic around the deltas
construction to accumulate rendered frame lengths while iterating and stop once
the running total reaches snapshot.length. Preserve the existing selection rule
and output: return all deltas only when their total length is strictly less than
snapshot.length; otherwise return [snapshot], while avoiding materializing or
retaining subsequent frames.
🪄 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: fda0376e-6d28-4ea5-a1cc-a65a2934c0e6
⛔ Files ignored due to path filters (10)
api-snapshots/advisor.api.mdis excluded by none and included by noneapi-snapshots/codegen.api.mdis excluded by none and included by noneapi-snapshots/shard-engine.api.mdis excluded by none and included by noneexamples/chess/lunora/_generated/shard.tsis excluded by!**/_generated/**and included by noneexamples/feedback-board/lunora/_generated/shard.tsis excluded by!**/_generated/**and included by nonepackages/advisor/__tests__/unbounded-collect.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/codegen/__tests__/discover-queries.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/do/__tests__/shard-do.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/do/__tests__/subscription-data-watermark.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/shard-engine/__tests__/subscription-frames.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**
📒 Files selected for processing (13)
packages/advisor/docs/index.mdxpackages/advisor/src/index.tspackages/advisor/src/lints/helpers.tspackages/advisor/src/lints/static/filter-on-primary-key.tspackages/advisor/src/lints/static/filter-without-index.tspackages/advisor/src/lints/static/unbounded-collect.tspackages/advisor/src/queries.tspackages/codegen/src/discover-queries.tspackages/codegen/src/ir.tspackages/do/src/shard-do.tspackages/shard-engine/__bench__/subscription-frames.bench.tspackages/shard-engine/src/index.tspackages/shard-engine/src/subscription-delivery.ts
A live subscription's refresh went out as one `{type:"delta"}` frame per
changed row whenever the diff was expressible, capped only by "no more
deltas than rows". That cap is a row-count proxy for wire cost, and it is
blind in both directions.
Every delta frame re-pays the whole `{"type":"delta","id":…}` + `"table":…`
+ cursor/epoch/watermark envelope around ONE row body, which the snapshot
pays once for the entire list. So the deltas stop being the cheaper encoding
well before they stop being a valid one. Measured on a 100-row list of
~290-byte rows where every row changed: 43,970 bytes across 100 frames
against 29,060 bytes in a single frame — 1.5x the payload and 100 sends
instead of 1, on the shard's write-flush fan-out path. The cap also misses
the opposite case, where a single delta into a short list of small rows
already costs more than re-sending the list.
Render both candidates and send the smaller one. `subscriptionFrames` now
owns the frame layout and the choice together, so the sizing cannot drift
from the format — it IS the format. `subscriptionListDeltas` keeps only the
four expressibility conditions; cost is no longer its call.
BREAKING CHANGE: `sendDeltaFrames` is removed from `@lunora/shard-engine` in
favour of `subscriptionFrames`, which returns the frames to send rather than
sending them. `subscriptionListDeltas` no longer returns `undefined` for a
near-total change — it decomposes any expressible diff.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AyG8dyPFieGYzRd7y1MMme
`filter_without_index` gates on `hasFilter`, so the widest read of all —
`ctx.db.query("t").collect()`, no index and no filter — fell straight
through it. The codegen feeder made that structural: it discarded every
discovered read that did not call `.filter()`, so no lint could have seen
one.
The cost is not only the scan. A query's result is what a live subscription
pushes over the WebSocket, and the shard's refresh gate can only skip a
subscription whose reads were confined to index slices. An unindexed
`.collect()` records a whole-table dependency instead, so every write to
the table re-runs the query and re-sends the entire table to every
subscribed socket, individually.
The feeder now reports every read plus the materializing call the chain
ends in, matched against a known terminal set rather than taken as the last
chained method — `.collect().then(...)` keeps the chain walk going, so the
literal last call is a promise combinator, not the terminal.
Also adds `withGeoIndex` to the narrowing methods. It was missing while only
filtered reads were reported, where nothing could observe it; once unfiltered
reads are reported it would flag the idiomatic `withGeoIndex(...).collect()`
as an unbounded scan — the exact chain `geo_index_unused` tells authors to
write.
Two examples trip the new lint on live-subscribed list queries; their
regenerated advisories are included.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AyG8dyPFieGYzRd7y1MMme
Two review follow-ups on the frame sizing. `subscriptionFrames` materialized every delta frame before comparing the total against the snapshot, so a near-total change — the case the comparison exists to catch — allocated an envelope per row only to discard the lot. The running total only grows, so the answer is known the moment it reaches the snapshot's length. Same comparison, same chosen frames, decided as early as it can be. The bench's reordered-survivors case also encoded its snapshot payload inside the timed body while every other case precomputed it, folding a full 200-row encode plus stringify into a number that is meant to measure the early-out. The production caller builds that payload once before calling in. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AyG8dyPFieGYzRd7y1MMme
038fdb5 to
491d00a
Compare
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## alpha #406 +/- ##
==========================================
- Coverage 87.09% 87.01% -0.09%
==========================================
Files 1172 1201 +29
Lines 63383 65291 +1908
Branches 15447 16109 +662
==========================================
+ Hits 55202 56810 +1608
- Misses 7654 7938 +284
- Partials 527 543 +16
🚀 New features to boost your workflow:
|
Merging this PR will degrade performance by 5.99%
|
| Benchmark | BASE |
HEAD |
Efficiency | |
|---|---|---|---|---|
| ❌ | broadcastWhisper to 1024 members |
1 ms | 1.4 ms | -24.58% |
| ❌ | in-batch: single IN(...) query + id->doc re-projection |
795.2 µs | 951.7 µs | -16.44% |
| ⚡ | flat 3 primitives (the notify.send attribute shape) |
62.6 µs | 55.6 µs | +12.6% |
| ⚡ | 1 after-insert no-op trigger |
444.4 µs | 403.8 µs | +10.04% |
| 🆕 | 1 of 200 rows changed |
N/A | 3.9 ms | N/A |
| 🆕 | 100 of 200 rows changed |
N/A | 4.1 ms | N/A |
| 🆕 | 200 of 200 rows changed |
N/A | 4.3 ms | N/A |
| 🆕 | 200 rows, survivors reordered → rejected |
N/A | 1.1 ms | N/A |
| 🆕 | paginated { page, isDone, continueCursor } → rejected (not an array) |
N/A | 683.7 µs | N/A |
Tip
Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.
Comparing perf/ws-subscription-frame-sizing (491d00a) with alpha (ccc68a3)2
Footnotes
-
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. ↩
-
No successful run was found on
alpha(1b03cea) during the generation of this report, so ccc68a3 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩
|
Folding this into #407 rather than merging separately. #407 was stacked on this branch, so it already contained every commit here; it is now rebased onto
Reviewing them as one unit is more honest anyway: the last commit fixes an insert-ordering desync that this PR's delta path introduced the exposure for, and the two are hard to judge apart. The review feedback here was applied — the bench Note for anyone comparing CI: the CodSpeed red on this branch flagged Closing in favour of #407. |
|
Tip For best results, initiate chat on the files or code changes.
The measured-size selection, early-abort rendering, paginated-query handling, and insert-ordering snapshot fallback should be reviewed together there. The prior 🐇 You are interacting with an AI system. |
|
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. |
Summary
Live-query fan-out (
@lunora/shard-engine,@lunora/do) was sending morebytes than it needed to, in two distinct ways. Both are fixed here, plus an
advisor lint (
@lunora/advisor,@lunora/codegen) for the third — the oneonly the app author can fix.
1. Delta-vs-snapshot was decided by row count
A refresh went out as one
{type:"delta"}frame per changed row wheneverthe diff was expressible, capped only by "no more deltas than rows".
Every delta frame re-pays the whole
{"type":"delta","id":…}+"table":…snapshot pays once for the entire list. So the deltas stop being the cheaper
encoding well before they stop being a valid one, and a row count cannot see
where. Measured, 100-row list of ~290-byte rows:
The cap was blind in the other direction too: a single delta into a short
list of small rows already costs more than re-sending the list, and it
allowed that as well.
Now both candidates are rendered and the smaller one is sent — stopping the
render as soon as the running delta total reaches the snapshot, so a
near-total change does not allocate envelopes that lose.
subscriptionFramesowns the frame layout and the choice together, so the sizing cannot drift
from the format — it is the format. Ties go to the snapshot, since one
frame is also one
ws.sendand one client apply.subscriptionListDeltaskeeps only its four expressibility conditions.Whether sending the diff is worth it was never something a function with no
view of the wire could answer.
2.
unbounded_collect(new advisor lint)filter_without_indexgates onhasFilter, so the widest read of all —ctx.db.query("t").collect()with no index and no filter — fell straightthrough it. The codegen feeder made that structural: it discarded every
discovered read without a
.filter(), so no lint could have seen one.An unindexed read records a whole-table dependency, so the refresh gate can
never skip it: every write to the table re-runs the query and re-sends the
whole table to every subscribed socket. Two of this repo's own examples trip
it, both on live-subscribed list queries.
The feeder now reports every read plus the materializing terminal, matched
against a known terminal set rather than the last chained method —
.collect().then(...)keeps the chain walk going, so the literal last callis a combinator.
withGeoIndexalso joins the narrowing methods: it wasmissing while only filtered reads were reported (a geo query is normally
written without one), and would otherwise have flagged the exact chain
geo_index_unusedtells authors to write.Linked issues
None — found by a WebSocket payload audit of the subscription fan-out path.
Test plan
pnpm run lint:affected:types— 73 projects, 0 errorspnpm run lint:eslint—@lunora/do,@lunora/shard-engine,@lunora/advisor,@lunora/codegenpnpm exec prettier --writeon every touched file@lunora/do537 tests,@lunora/shard-engine1123 (+8 new),@lunora/codegen1202,@lunora/advisor482pnpm run api:check— 47/47 snapshots match (3 updated in this PR:sendDeltaFrames→subscriptionFrames, plus the newterminalfield onQueryReadIR/AdvisorQueryRead)@lunora/dosuite is the one above, all greenexamples/*andapps/playgroundregenerated; only the two expected advisory diffs (examples/chess,examples/feedback-board), and nothing further after the rebase ontoalphapnpm --filter @lunora/shard-engine exec vitest bench— the new bench runs cleanReviewers should re-run
pnpm run api:checkand the@lunora/dosuite.Checklist
feat(scope): subject)apps/docs(orREADME.mdfor package-local docs) —packages/advisor/docs/index.mdxgained theunbounded_collectrow; theapps/docscopy is generated from it bycopy-package-docs.jsand is gitignoredpackage.jsonfiles inpackages/*modified outside the touched packageNotes for reviewers
Start with
packages/shard-engine/src/subscription-delivery.ts— thewhole delta-vs-snapshot decision lives in
subscriptionFrames, andpushSubscriptionDatanow just sends what it is handed.Breaking (pre-1.0,
alpha):sendDeltaFramesis removed from@lunora/shard-enginein favour ofsubscriptionFrames, which returns theframes rather than sending them.
subscriptionListDeltasno longer returnsundefinedfor a near-total change — it decomposes any expressible diff.Both are internal to the shard/engine boundary; no app code imports them.
Frame-type flips are one-directional. The new predicate is a strict
subset of the old one, so no socket that previously got a snapshot can now
get deltas — only the reverse. That is what keeps the seven non-JS SDKs
under
sdks/safe: they handle"data"and"delta"in one arm and replacewholesale, so this strictly reduces their exposure to that pre-existing
limitation.
Deferred: paginated queries never diff
.paginate()returns{ page, isDone, continueCursor }— an object, so bothsubscriptionListDeltasand the client'sapplyDeltareject it. A one-rowedit re-sends the entire page (measured 7,279 B for a ~290 B change, 25x),
and
usePaginatedQueryholds one subscription per loaded page.Not fixed here because it cannot be done safely without protocol work: a
client whose
applyDeltabails replaces the whole query value with the rawdelta object, so page-deltas need a capability announced on the
connectframe and honoured by all seven SDKs. It is the largest remaining over-send
and worth doing, but as its own change. The new bench keeps a case measuring
what the rejection costs today.
Measured, not changed
subscriptionFramescost scales with list length, not with how muchchanged: ~0.74 ms for a one-row edit to a 200-row list, paid per
(socket, subscription). At 100 subscribers that is ~74 ms ofsingle-threaded shard time per write. Inherent to the current design
(identity-dependent queries cannot share a result under RLS); the bench pins
it so a regression shows up.
Contributor License Agreement
🤖 Generated with Claude Code
https://claude.ai/code/session_01AyG8dyPFieGYzRd7y1MMme