Skip to content

feat(racer): hold warmed pages on each page's primary owner - #954

Merged
Jordan Olshevski (jveski) merged 20 commits into
mainfrom
racer-warm-peer-holds
Oct 21, 2026
Merged

Jordan Olshevski (jveski) merged 20 commits into
mainfrom
racer-warm-peer-holds

Conversation

@jveski

Copy link
Copy Markdown
Contributor

Cache warming now stores and hard-holds each warmed page on its primary owner in the peer mesh, instead of forcing every page onto the requesting node's disk. Pages whose primary owner is the requester stay local as before. A HEAD warm reserves holds on every involved owner up front through new peer Warm hold, fill, and release operations, and is refused if any owner declines. Reads still wait on the warm frontier, then use the normal fill path to reach the owner's held copy. Holds are leased per requester and job, are not re-homed when membership changes, and require all nodes to run a version that understands the new peer operations.

Add a Warm peer operation with hold, fill, and release actions plus
held, warmed, and released acknowledgements. A hold carries the object
page count and a wall-clock expiry instead of a page list; the owner
derives its own primary pages. Acknowledgements are destination-only
and must match the requested action, and a held expiry may never exceed
the request. Receivers reject warm operations until they are served.
A warm HEAD now plans each page's primary owner under the admission
membership. Pages this node owns are held and filled locally as before;
every remote primary owner must accept a lease-scoped hold before the
HEAD succeeds, and the warm job asks that owner to fill each page and
acknowledge publication without sending the payload. Any refused hold
or persistently failed fill releases the job's leases. Reads still wait
on the warm frontier and then read remote pages through normal Fill.

Owners serve warm requests only for pages they are the primary owner
of, track leases per requester and job, and release unused capacity
only after the last live lease is gone.
Add requester tests for remote-only placement, all-or-nothing refusal
with releases to every owner, and a failing owner fill that fails the
job and releases its hold. Add an owner test for non-primary refusal,
lease-gated fills, and capacity shared across two requester leases.
Rewrite the warm section for primary-owner holds, all-or-nothing
admission, acknowledgement-only remote fills, leases, and the limits on
membership drift, clock skew, and mixed versions. List the new remote
and owner warm counters and note owner placement in the SDK Warm doc.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

Unresolved retention accounting, release synchronization, read-ordering, and lease-growth issues affect correctness and resource bounds.

4 open issues
What changed in this PR

Moves Racer cache warming from requester-local storage to each page’s primary owner.

Changes:

  • Adds peer hold, fill, and release operations with requester-scoped leases.
  • Routes warming through primary owners while retaining read-progress gating.
  • Adds protocol tests, telemetry, and documentation.
File Description
pkg/​racersdk/​client.go Documents primary-owner warming.
docs/​content/​reference/​racer.md Explains admission, leases, limits, and metrics.
cmd/​racer-dataplane/​src/​telemetry.rs Adds owner and remote warm metrics.
cmd/​racer-dataplane/​src/​read/​warm.rs Implements distributed warming and leases.
cmd/​racer-dataplane/​src/​read/​tests/​warming.rs Tests remote warming and owner holds.
cmd/​racer-dataplane/​src/​read/​tests.rs Updates timeout fixtures for warm operations.
cmd/​racer-dataplane/​src/​read/​metadata.rs Rejects warm acknowledgements as metadata responses.
cmd/​racer-dataplane/​src/​read/​dispatch.rs Dispatches owner operations and reservations.
cmd/​racer-dataplane/​src/​read/​candidates.rs Handles warm operations in routing.
cmd/​racer-dataplane/​src/​read.rs Connects authenticated requests to warm handling.
cmd/​racer-dataplane/​src/​peer/​protocol.rs Defines warm wire operations and responses.
cmd/​racer-dataplane/​src/​peer/​forwarding.rs Validates acknowledgement binding and adds protocol tests.

Review effort: Balanced

Comment thread cmd/racer-dataplane/src/read/dispatch.rs Outdated
Comment thread cmd/racer-dataplane/src/read/dispatch.rs Outdated
Comment thread cmd/racer-dataplane/src/read/warm.rs Outdated
Comment thread cmd/racer-dataplane/src/read/warm.rs Outdated

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

Lease renewal and expiration can exhaust admission capacity, and socket failures bypass the intended retries.

3 open issues
4 resolved since last review

Review effort: Balanced

Comment thread cmd/racer-dataplane/src/read/warm.rs Outdated
Comment thread cmd/racer-dataplane/src/read/warm.rs
Comment thread cmd/racer-dataplane/src/read/warm.rs Outdated

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

Lease identity and expiration mismatches can invalidate accepted warm jobs before their promised retention deadline.

2 open issues
3 resolved since last review

Review effort: Balanced

Comment thread cmd/racer-dataplane/src/read/warm.rs
Comment thread cmd/racer-dataplane/src/read/warm.rs Outdated

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

Recovery accounting, job-placement races, and missing remote metadata validation leave correctness issues unresolved.

2 open issues
1 previously missed issue

In code that hasn't changed since last review

Medium severity Preserve the completing job when determining return placement

cmd/​racer-dataplane/​src/​read/​dispatch.rs:537

Return placement from the same job that satisfied wait. The wait retains one Job (warm.rs:591-606), but this locality check looks up the current job again (warm.rs:319-322). Another worker can replace a completed remote job with a new job whose plan is still None, or remove an expired job, between these calls. The lookup then defaults to local, so a read can fail with Unavailable when only the remote owner has the page (fill.rs:115-125). Carry the retained job's local/remote outcome through the wait result and add a replacement-race regression test.

2 resolved since last review

Review effort: Balanced

Comment thread cmd/racer-dataplane/src/read/warm.rs
Comment thread cmd/racer-dataplane/src/store/catalog.rs

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🔵 Needs a closer look

Reservation cleanup can race with pending holds, and hold recovery introduces quadratic work.

No open issues 🎉

2 previously missed issues

In code that hasn't changed since last review

Medium severity Fence hold reservations against concurrent release cleanup

cmd/​racer-dataplane/​src/​read/​warm.rs:1493

Fence reservation against a concurrent Release of the same lease. After Hold grants the lease and awaits worker reservations, Release can remove the last lease and queue cleanup. Workers process cleanup before queued Hold work (read/dispatch.rs:853-860), so cleanup can finish before Hold recreates the reservation. The owner can then acknowledge Hold with no live lease, leaving unused capacity reserved until the hold expires. Coordinate pending reservations with release, or recheck lease state after reservation and queue generation-fenced cleanup when needed. Cover this ordering with a test.

Medium severity Avoid quadratic held-page reconstruction during recovery

cmd/​racer-dataplane/​src/​store/​catalog.rs:494

Recovery visits pages in hash order (alloc/src/index.rs:60-61), but each out-of-order HoldPages::insert shifts a vector suffix (store/holds.rs:43-47). Rebuilding a large held version therefore takes quadratic work on the synchronous recovery path, slowing restarts. Collect the locations first, then construct each page set once with FromIterator, which sorts once.

2 resolved since last review

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🔵 Needs a closer look

The previously reported persistence-ordering issue allows owner acquisition to persist incompatible metadata before validation in read/warm.rs:1578.

No open issues 🎉

Review effort: Balanced

@jveski
Jordan Olshevski (jveski) marked this pull request as ready for review October 21, 2026 16:36
@jveski
Jordan Olshevski (jveski) requested a review from a team October 21, 2026 16:36
@jveski
Jordan Olshevski (jveski) added this pull request to the merge queue Oct 21, 2026
Merged via the queue into main with commit 62f0106 Oct 21, 2026
36 checks passed
@jveski
Jordan Olshevski (jveski) deleted the racer-warm-peer-holds branch October 21, 2026 16:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants