Skip to content

rpc: add checkpoint bounds to ListPackageVersions on the fullnode and kv-rpc - #28429

Open
nickvikeras wants to merge 1 commit into
nickv/getpackage-bound-checksfrom
nickv/package-versions-checkpoint
Open

nickvikeras wants to merge 1 commit into
nickv/getpackage-bound-checksfrom
nickv/package-versions-checkpoint

Conversation

@nickvikeras

@nickvikeras nickvikeras commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Description

GraphQL's packageVersions, packageVersionsAfter and packageVersionsBefore are bounded by the checkpoint being viewed and still read Postgres kv_packages for it. This serves ListPackageVersionsRequest.at_checkpoint and PackageVersion.checkpoint (MystenLabs/sui-apis#41 on sui-apis#51; the bindings come from MystenLabs/sui-rust-sdk#341, which this PR pins) from the fullnode and kv-rpc, so they can move to gRPC. Stacked on #28573.

Both backends end the ascending scan at the first version published after the bound. Errors match across them: OUT_OF_RANGE with ErrorReason ABOVE_LATEST_AVAILABLE above the highest indexed checkpoint, OUT_OF_RANGE with BELOW_EARLIEST_AVAILABLE below the fullnode's object floor. Page tokens are unchanged.

It also fixes checkpoint-pinned package reads that trusted restore rows (a package version with no publish checkpoint) too broadly:

  • ListPackageVersions uses rpc: bound checkpoint-pinned reads, and report reads outside the indexed range as OUT_OF_RANGE #28577's shared bounds, so on a fork it rejects bounds below the fork checkpoint (RpcStateReader::get_lowest_checkpoint_with_index_history) instead of answering from restore rows. On a restored fullnode it returns UNAVAILABLE while history is still backfilling, with or without at_checkpoint: until the backfill finishes, a system package's lineage lacks the versions published in the part of the window it has not reached, so even an unbounded listing would come back partial with OK.
  • A restore loads only the latest version of a system package. The backfill records the version an in-place upgrade replaces, so a pinned read below that upgrade resolves to it. Versions before that one are still missing on a pruned node, as the proto documents. The pipeline also remembers the system package publishes it has staged this run, because the synchronizer can still hold a publish's batch unwritten when the next checkpoint upgrades that version in place; without that, the upgrade would overwrite the publish with a restore row. Only checkpoints in the backfill window [L, T] (at or below the restore checkpoint T) can carry such an input, so the pipeline reads T from its restore state at startup and scans checkpoint inputs only up to it; past T, and on a node that was never restored, it skips the scan.
  • A fullnode listing with at_checkpoint that starts below the lowest version of the lineage the node stores, from version 1 or from a page token, is refused rather than answered with a history cut short. package_versions rows outlive pruning, which deletes system-package versions replaced in place, and a restored node or a fork has no rows for the versions replaced before its history begins. The refusal follows GetPackage (rpc: serve the requested version of a system package from GetPackage #28555): UNIMPLEMENTED / NOT_SERVED_HERE (no_object_history) on nodes without object version history, INTERNAL on a node that has pruned nothing (floor 0), and otherwise OUT_OF_RANGE / BELOW_EARLIEST_AVAILABLE with lowestAvailableCheckpoint and lowestAvailableVersion, the lowest version the node stores (left out when it stores none of the versions it has rows for). The check scans rows upward from the start and stops at the first stored version: pruning deletes replaced versions oldest first, so every version after a stored one is stored too. It asks the store only about rows whose next row has the same storage ID, and about the last row. A listing without at_checkpoint lists every row it reaches, including system-package versions whose packages are pruned. kv-rpc never prunes, so it has no such refusal.

Known limitation, not changed here: a fork lists only package versions it has seeded or fetched.

Test plan

New tests:

  • fullnode e2e (list_package_versions.rs) and kv-rpc e2e (kv_rpc_tests.rs): publish checkpoint reported, bound cutting mid-lineage, bound before first publish (empty), bound above and exactly at the tip, pagination under a bound; fullnode floor test asserting OUT_OF_RANGE below the pruned object floor.
  • unit: Bigtable ascending scan stops at the bound and keeps the server-side row cap; a descending scan is capped server-side too, by rows_limit plus the publish-checkpoint filter, which get_package_versions_bounds_by_publish_checkpoint asserts by the number of rows read; kv-rpc handler bounds; rpc-store iterator reports unset checkpoints for restored rows; package_versions records an in-place upgrade's input version without overwriting a recorded publish, a publish staged but not yet written (upgrade_input_finds_a_publish_staged_but_not_yet_written), or a publish earlier in the same batch (upgrade_input_finds_a_publish_earlier_in_the_same_batch); the processor scans checkpoint inputs only up to the restore checkpoint (process_scans_upgrade_inputs_only_up_to_the_restore_anchor).
  • unit, lineage refusal in sui-rpc-api's list_package_versions.rs: unpruned_lineage_is_stored_from_every_start, pruned_versions_refuse_ranges_starting_below_the_lowest_stored, versions_without_rows_refuse_ranges_starting_below_them and rows_with_no_stored_version_refuse_without_a_lowest_stored_version check the scan's outcome and how many versions it asks the store about; refusal_below_lowest_stored_is_internal_on_a_node_that_pruned_nothing checks INTERNAL at floor 0 and BELOW_EARLIEST_AVAILABLE above it.
  • sui-fork: ListPackageVersions rejects a bound below the fork checkpoint and serves one at it; the same test checks that GetPackage at the fork checkpoint passes both bounds and finds the seeded package (whose response then fails only because it has no modules). test_system_package_listing_below_the_lowest_stored_version_is_refused seeds a system package at version 3: an at_checkpoint listing from version 1, or from a page token at 1 or 2, gets BELOW_EARLIEST_AVAILABLE with lowestAvailableVersion 3, while one from 3, and one without at_checkpoint, list version 3.

The UpgradeInput path is covered by unit tests of the processor and the commit step, not by a real system-package upgrade. The backfill gate on listings without at_checkpoint has no test: it reuses at_checkpoint_upper_bound, whose gate is tested in #28577, and no test drives a real restore. The lineage refusal is tested on the scan alone and on a fork, not on a node that has pruned a system-package version.


Release notes

Check each box that your changes affect. If none of the boxes relate to your changes, release notes aren't required.

For each box you select, include information after the relevant heading that describes the impact of your changes that a user might notice and any actions they must take to implement updates.

  • Protocol:
  • Nodes (Validators and Full nodes):
  • gRPC: ListPackageVersions reports each version's publish checkpoint and accepts at_checkpoint to list only versions published at or before a checkpoint. A bound above the highest indexed checkpoint fails with OUT_OF_RANGE / ABOVE_LATEST_AVAILABLE, and one below the floor with OUT_OF_RANGE / BELOW_EARLIEST_AVAILABLE. Without at_checkpoint, a full node lists versions only up to its highest indexed checkpoint, as kv-rpc does with its served height. On a full node, it returns UNAVAILABLE while a restore is still backfilling history, with or without at_checkpoint. On a full node, a listing with at_checkpoint that starts below the lowest version of the package the node stores (such as system-package versions it has pruned, or that were replaced before it was restored from a snapshot) fails with OUT_OF_RANGE / BELOW_EARLIEST_AVAILABLE, whose lowestAvailableVersion names that version.
  • JSON-RPC:
  • GraphQL:
  • CLI:
  • Rust SDK:
  • Indexing Framework:

@nickvikeras
nickvikeras requested a review from bmwill October 23, 2026 01:15
@nickvikeras
nickvikeras force-pushed the nickv/object-versions-rpc branch 2 times, most recently from 1752a76 to dd84d96 Compare November 3, 2026 00:46
@nickvikeras
nickvikeras force-pushed the nickv/package-versions-checkpoint branch from 640f118 to df527ee Compare November 3, 2026 00:46
@nickvikeras
nickvikeras force-pushed the nickv/object-versions-rpc branch from dd84d96 to dd3d532 Compare November 3, 2026 04:34
@nickvikeras
nickvikeras force-pushed the nickv/package-versions-checkpoint branch from df527ee to 6f5cf19 Compare November 3, 2026 04:34
@nickvikeras
nickvikeras force-pushed the nickv/object-versions-rpc branch from dd3d532 to 45e4f3f Compare November 3, 2026 16:30
@nickvikeras
nickvikeras force-pushed the nickv/package-versions-checkpoint branch from 6f5cf19 to 543aafc Compare November 3, 2026 16:30
@nickvikeras
nickvikeras force-pushed the nickv/object-versions-rpc branch from 45e4f3f to a52f497 Compare November 3, 2026 16:40
@nickvikeras
nickvikeras force-pushed the nickv/package-versions-checkpoint branch from 543aafc to c52173f Compare November 3, 2026 16:40
@nickvikeras
nickvikeras force-pushed the nickv/object-versions-rpc branch from a52f497 to 4bdc9ae Compare November 4, 2026 15:26
@nickvikeras
nickvikeras force-pushed the nickv/package-versions-checkpoint branch from c52173f to d3f6906 Compare November 4, 2026 15:27
@nickvikeras
nickvikeras force-pushed the nickv/object-versions-rpc branch from 4bdc9ae to 34ec19e Compare November 4, 2026 17:00
@nickvikeras
nickvikeras force-pushed the nickv/package-versions-checkpoint branch from d3f6906 to b04a6bb Compare November 4, 2026 17:00
@nickvikeras
nickvikeras force-pushed the nickv/object-versions-rpc branch from 34ec19e to 5183c9d Compare November 4, 2026 21:30
@nickvikeras
nickvikeras force-pushed the nickv/package-versions-checkpoint branch 2 times, most recently from b61575e to b13122a Compare November 4, 2026 22:38
@nickvikeras
nickvikeras changed the base branch from nickv/object-versions-rpc to nickv/getpackage-bound-checks November 4, 2026 22:38
@nickvikeras
nickvikeras force-pushed the nickv/getpackage-bound-checks branch from 85e660e to 6bf75f5 Compare November 5, 2026 00:05
@nickvikeras
nickvikeras force-pushed the nickv/package-versions-checkpoint branch from b13122a to 54794ca Compare November 5, 2026 00:05
@nickvikeras
nickvikeras force-pushed the nickv/package-versions-checkpoint branch from 54794ca to 93b1d60 Compare November 5, 2026 00:51
@nickvikeras
nickvikeras force-pushed the nickv/package-versions-checkpoint branch from 93b1d60 to ce4c203 Compare November 5, 2026 15:50
@nickvikeras
nickvikeras force-pushed the nickv/getpackage-bound-checks branch 2 times, most recently from a36789e to 1417925 Compare November 5, 2026 19:20
@nickvikeras
nickvikeras force-pushed the nickv/package-versions-checkpoint branch from ce4c203 to ba2a79e Compare November 5, 2026 19:20
@nickvikeras
nickvikeras marked this pull request as ready for review November 5, 2026 19:25
@nickvikeras
nickvikeras requested a review from a team as a code owner November 5, 2026 19:25
@nickvikeras
nickvikeras force-pushed the nickv/getpackage-bound-checks branch from 1417925 to 66c07eb Compare November 5, 2026 23:00
@nickvikeras
nickvikeras force-pushed the nickv/package-versions-checkpoint branch from ba2a79e to 58da7ae Compare November 5, 2026 23:00
@nickvikeras
nickvikeras force-pushed the nickv/getpackage-bound-checks branch from 66c07eb to a4ee68b Compare November 6, 2026 00:47
@nickvikeras
nickvikeras force-pushed the nickv/package-versions-checkpoint branch from 58da7ae to a99989c Compare November 6, 2026 00:47
@nickvikeras
nickvikeras force-pushed the nickv/getpackage-bound-checks branch from a4ee68b to 8b5c4a3 Compare November 6, 2026 21:32
@nickvikeras
nickvikeras force-pushed the nickv/package-versions-checkpoint branch 2 times, most recently from 333b2fc to 437d9e8 Compare November 11, 2026 01:21
@nickvikeras
nickvikeras force-pushed the nickv/getpackage-bound-checks branch 2 times, most recently from 1ad5ebb to 757f605 Compare November 11, 2026 02:23
@nickvikeras
nickvikeras force-pushed the nickv/package-versions-checkpoint branch 3 times, most recently from e891968 to 51e5896 Compare November 13, 2026 11:11
@nickvikeras
nickvikeras force-pushed the nickv/getpackage-bound-checks branch 2 times, most recently from 4ee1050 to e333d63 Compare November 14, 2026 03:01
@nickvikeras
nickvikeras force-pushed the nickv/package-versions-checkpoint branch 3 times, most recently from f363522 to 31b9436 Compare November 15, 2026 02:09
@nickvikeras
nickvikeras force-pushed the nickv/package-versions-checkpoint branch from 31b9436 to ab57e7f Compare November 15, 2026 19:59

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

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant