Skip to content

refactor(delegations): share delegations between threads - #12101

Draft
pierugo-dfinity wants to merge 3 commits into
masterfrom
pierugo/delegations/snapshot
Draft

pierugo-dfinity wants to merge 3 commits into
masterfrom
pierugo/delegations/snapshot

Conversation

@pierugo-dfinity

Copy link
Copy Markdown
Contributor

This PR prepares the work to return 503 errors on state-delegation mismatches in queries (#12064).

To verify the delegation against the state in the query handler, we unfortunately can't send it the already-built delegation but instead need to send it an NNSDelegationBuilder (which knows how to verify a delegation against a state). It needs to be owned because the query handler runs in a separate task/thread.

We cannot afford to copy the entire NNSDelegationBuilder for every query, so we wrap it in an Arc and allow owners of an NNSDelegationReader to get such a (ref-counted) "copy" of the delegation. We introduce a new NNSDelegationSnapshot which is nothing else than an abstraction over this copy which provides the same functions as before. This is what will get sent to the query handler instead of the already-built delegation.

A nice little bonus improvement is that the delegation manager will not block anymore when sending a new delegation to the reader if many requests are concurrently borrowing the builder to verify it against the state. I.e. we are now keeping the borrow extremely short-lived (just the duration of a ref-count bump during the Arc's clone), instead of the duration to verify the delegation.

We also refactor PocketIC a bit to deduplicate code (and prepare for future changes).

pierugo-dfinity and others added 3 commits November 13, 2026 14:17
…n Arc

The delegation manager now publishes `Option<Arc<NNSDelegationBuilder>>`
on the watch channel, and `NNSDelegationReader::builder()` returns a cheap,
immutable snapshot of the latest builder.

This lets a consumer verify the delegation against a certified state and
build exactly the verified delegation without holding on to the channel,
e.g. the query handler can be handed a snapshot instead of a receiver.
It also means that:
- the reader's `get_delegation*` methods no longer hold the channel's read
  lock while verifying and building the delegation;
- the manager no longer deep-clones the builder every time it publishes one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…napshots

`NNSDelegationReader::snapshot()` returns an `NNSDelegationSnapshot`, a cheap-to-clone
handle on the most recent delegation (none on the NNS subnet). It verifies the delegation
against a certified state and builds it in one call (`build_verified`), without holding the
channel's read lock and without the delegation being replaced in between.

- `NNSDelegationReader::get_delegation` is removed: the read_state and call endpoints and
  the manager tests now go through a snapshot.
- `get_delegation_with_metadata` moves from the reader to the snapshot, and the query
  endpoint takes one snapshot per request.
- `StateMachine::query_as_with_delegation_and_sender_info` takes a snapshot (or
  `NNSDelegationSnapshot::none()`) instead of a raw delegation and its metadata, and builds
  the delegation with the flat canister ranges.
- PocketIC builds one `NNSDelegationReader` per request with `get_nns_delegation_for_subnet`,
  instead of parsing the delegation at each call site.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

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.

🟢 Approval recommended

No active review issues are reported for the shared delegation snapshot refactor.

No open issues 🎉

What changed in this PR

This refactor makes NNS delegation builders shareable across threads, preparing query-state consistency checks for #12064 without introducing the planned 503 responses yet.

Changes:

  • Adds immutable, Arc-backed delegation snapshots, shortening watch-channel borrows to a reference-counted clone.
  • Updates delegation publication, HTTP consumers, and test helpers to use snapshots.
  • Centralizes PocketIC delegation-reader construction and updates state-machine dependencies.
File Description
rs/​state_machine_tests/​src/​lib.rs Accepts delegation snapshots for queries and builds flat-format delegations.
rs/​state_machine_tests/​Cargo.toml Adds the delegation-reader dependency.
rs/​state_machine_tests/​BUILD.bazel Adds the matching Bazel dependency.
rs/​pocket_ic_server/​src/​pocket_ic.rs Consolidates delegation-reader construction across request paths.
rs/​http_endpoints/​public/​tests/​test.rs Updates drift-test helpers for shared builders.
rs/​http_endpoints/​public/​tests/​common/​mod.rs Wraps test builders and watch-channel values in Arc.
rs/​http_endpoints/​public/​src/​verified_delegation_source.rs Takes a snapshot before verifying delegations.
rs/​http_endpoints/​public/​src/​query.rs Builds query delegations from snapshots while preserving format selection.
rs/​http_endpoints/​nns_delegation_reader/​src/​reader.rs Introduces snapshots and moves delegation access methods onto them.
rs/​http_endpoints/​nns_delegation_reader/​src/​lib.rs Exports the snapshot type.
rs/​http_endpoints/​nns_delegation_manager/​src/​nns_delegation_manager.rs Publishes shared builders and adapts manager tests.
rs/​http_endpoints/​nns_delegation_manager/​src/​lib.rs Re-exports the snapshot type.
Cargo.lock Records the new state-machine dependency.

Review effort: Balanced

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants