diff --git a/Cargo.lock b/Cargo.lock index 52461531d9db..478970d46c13 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -14307,7 +14307,7 @@ dependencies = [ [[package]] name = "sui-crypto" version = "0.4.0" -source = "git+https://github.com/MystenLabs/sui-rust-sdk.git?rev=1c0451c8c213b79cbfdaa78948742c9e7680504a#1c0451c8c213b79cbfdaa78948742c9e7680504a" +source = "git+https://github.com/MystenLabs/sui-rust-sdk.git?rev=9d6cfabd67c586892e6ac68e722eb7ee9b7459cf#9d6cfabd67c586892e6ac68e722eb7ee9b7459cf" dependencies = [ "ark-bn254", "ark-ff 0.4.2", @@ -16141,7 +16141,7 @@ dependencies = [ [[package]] name = "sui-rpc" version = "0.4.0" -source = "git+https://github.com/MystenLabs/sui-rust-sdk.git?rev=1c0451c8c213b79cbfdaa78948742c9e7680504a#1c0451c8c213b79cbfdaa78948742c9e7680504a" +source = "git+https://github.com/MystenLabs/sui-rust-sdk.git?rev=9d6cfabd67c586892e6ac68e722eb7ee9b7459cf#9d6cfabd67c586892e6ac68e722eb7ee9b7459cf" dependencies = [ "base64 0.22.1", "bcs", @@ -16326,7 +16326,7 @@ dependencies = [ [[package]] name = "sui-sdk-types" version = "0.4.0" -source = "git+https://github.com/MystenLabs/sui-rust-sdk.git?rev=1c0451c8c213b79cbfdaa78948742c9e7680504a#1c0451c8c213b79cbfdaa78948742c9e7680504a" +source = "git+https://github.com/MystenLabs/sui-rust-sdk.git?rev=9d6cfabd67c586892e6ac68e722eb7ee9b7459cf#9d6cfabd67c586892e6ac68e722eb7ee9b7459cf" dependencies = [ "base64ct", "bcs", diff --git a/Cargo.toml b/Cargo.toml index 51c2121ea483..3016322fe721 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -727,9 +727,9 @@ anemo-cli = { git = "https://github.com/mystenlabs/anemo.git", rev = "845a9b5aab anemo-tower = { git = "https://github.com/mystenlabs/anemo.git", rev = "845a9b5aab1f8b78fb67c0e8e1998cb2e6a4d72e" } # core-types from the new sdk for use in gRPC -sui-sdk-types = { git = "https://github.com/MystenLabs/sui-rust-sdk.git", rev = "1c0451c8c213b79cbfdaa78948742c9e7680504a", features = [ "hash", "serde" ] } -sui-crypto = { git = "https://github.com/MystenLabs/sui-rust-sdk.git", rev = "1c0451c8c213b79cbfdaa78948742c9e7680504a", features = [ "ed25519", "secp256r1", "secp256k1", "passkey", "zklogin", "mldsa65" ] } -sui-rpc = { git = "https://github.com/MystenLabs/sui-rust-sdk.git", rev = "1c0451c8c213b79cbfdaa78948742c9e7680504a", features = [ "unstable" ] } +sui-sdk-types = { git = "https://github.com/MystenLabs/sui-rust-sdk.git", rev = "9d6cfabd67c586892e6ac68e722eb7ee9b7459cf", features = [ "hash", "serde" ] } +sui-crypto = { git = "https://github.com/MystenLabs/sui-rust-sdk.git", rev = "9d6cfabd67c586892e6ac68e722eb7ee9b7459cf", features = [ "ed25519", "secp256r1", "secp256k1", "passkey", "zklogin", "mldsa65" ] } +sui-rpc = { git = "https://github.com/MystenLabs/sui-rust-sdk.git", rev = "9d6cfabd67c586892e6ac68e722eb7ee9b7459cf", features = [ "unstable" ] } ### Workspace Members ### anemo-benchmark = { path = "crates/anemo-benchmark" } diff --git a/crates/simulacrum/src/lib.rs b/crates/simulacrum/src/lib.rs index 2b4a635146cb..674eceb376df 100644 --- a/crates/simulacrum/src/lib.rs +++ b/crates/simulacrum/src/lib.rs @@ -926,6 +926,22 @@ impl RpcStateReader for fn indexes(&self) -> Option<&dyn sui_types::storage::RpcIndexes> { None } + + /// The store records no versions at which objects were deleted or wrapped, so only a live + /// object at or below `version` can be answered exactly. Any other read fails rather than + /// return a version the object may already have left. + fn get_object_lt_or_eq_version( + &self, + object_id: &ObjectID, + version: SequenceNumber, + ) -> sui_types::storage::error::Result> { + match store::SimulatorStore::get_object(self.store(), object_id) { + Some(object) if object.version() <= version => Ok(Some(object)), + _ => Err(sui_types::storage::error::Error::custom( + "Simulacrum only serves version-bounded reads of live objects at or below the bound", + )), + } + } } impl Simulacrum { diff --git a/crates/sui-core/src/storage.rs b/crates/sui-core/src/storage.rs index e20930efc2d5..5f3e757f90da 100644 --- a/crates/sui-core/src/storage.rs +++ b/crates/sui-core/src/storage.rs @@ -85,6 +85,17 @@ impl RocksDbStore { .multi_get_objects_by_key(object_keys) } + /// See [`crate::execution_cache::ObjectCacheRead::find_object_lt_or_eq_version`]. + pub fn find_object_lt_or_eq_version( + &self, + object_id: ObjectID, + version: SequenceNumber, + ) -> Option { + self.cache_traits + .object_cache_reader + .find_object_lt_or_eq_version(object_id, version) + } + pub fn get_last_executed_checkpoint(&self) -> Option { self.checkpoint_store .get_highest_executed_checkpoint() @@ -695,6 +706,14 @@ impl RpcStateReader for RestReadStore { fn layout_package_store(&self) -> Box { Box::new(self.state.get_backing_package_store().as_ref()) } + + fn get_object_lt_or_eq_version( + &self, + object_id: &ObjectID, + version: SequenceNumber, + ) -> Result> { + Ok(self.rocks.find_object_lt_or_eq_version(*object_id, version)) + } } /// Read store backed by the embedded [`sui_rpc_store`] indexer. @@ -960,6 +979,14 @@ impl RpcStateReader for RpcStoreReadStore { Some(self) } + fn get_object_lt_or_eq_version( + &self, + object_id: &ObjectID, + version: SequenceNumber, + ) -> Result> { + Ok(self.rocks.find_object_lt_or_eq_version(*object_id, version)) + } + fn get_highest_executed_checkpoint_seq_number(&self) -> Result { // The raw executed tip, read straight from the checkpoint store. Unlike // `get_latest_checkpoint`, this is not bounded to the live-object index diff --git a/crates/sui-e2e-tests/tests/rpc/v2/ledger_service/get_object.rs b/crates/sui-e2e-tests/tests/rpc/v2/ledger_service/get_object.rs index d2cf5b511972..babeb403d30d 100644 --- a/crates/sui-e2e-tests/tests/rpc/v2/ledger_service/get_object.rs +++ b/crates/sui-e2e-tests/tests/rpc/v2/ledger_service/get_object.rs @@ -2,9 +2,11 @@ // SPDX-License-Identifier: Apache-2.0 use mysten_common::ZipDebugEqIteratorExt; +use prost::Message; use sui_macros::sim_test; use sui_rpc::field::FieldMask; use sui_rpc::field::FieldMaskUtil; +use sui_rpc::proto::google::rpc::BadRequest; use sui_rpc::proto::sui::rpc::v2::BatchGetObjectsRequest; use sui_rpc::proto::sui::rpc::v2::BatchGetObjectsResponse; use sui_rpc::proto::sui::rpc::v2::GetObjectRequest; @@ -213,9 +215,13 @@ async fn batch_get_objects() { /// Reads pinned to a checkpoint see the state left by the object's latest change at or before /// that checkpoint, through creation, mutation, wrapping, unwrapping, and deletion, and at a -/// checkpoint in which the live object did not change. +/// checkpoint in which the live object did not change. `max_version` reads see the newest +/// version at or below the bound, and `NotFound` from a deletion or wrap until the object is +/// unwrapped. `at_checkpoint` with `version` keeps that version only if it was written by the +/// end of the checkpoint, and with `max_version` fails if the version it selects was written +/// after the checkpoint, as Postgres does. #[sim_test] -async fn get_object_at_checkpoint_lifecycle() { +async fn get_object_lifecycle() { let cluster = TestClusterBuilder::new() .with_num_validators(1) // Keep every checkpoint servable; the fullnode prunes old checkpoints by default. @@ -240,11 +246,11 @@ async fn get_object_at_checkpoint_lifecycle() { .0 .0; - // Drive an object through its lifecycle, one transaction per step, recording the state each - // step leaves behind as (checkpoint, object, version if live). Wrapping creates a wrapper - // object, and unwrapping deletes it. + // Drive an object through its lifecycle, one transaction per step, recording each change as + // (checkpoint, object, version, live). `live` is false for a change that deleted or wrapped + // the object. Wrapping creates a wrapper object, and unwrapping deletes it. let sender = cluster.get_address_0(); - let mut changes: Vec<(u64, ObjectID, Option)> = Vec::new(); + let mut changes: Vec<(u64, ObjectID, u64, bool)> = Vec::new(); let mut step_checkpoints = Vec::new(); let (create, cp) = call_object_basics( @@ -255,19 +261,30 @@ async fn get_object_at_checkpoint_lifecycle() { ) .await; let object = created_object(&create); - changes.push((cp, object, Some(create.lamport_version().value()))); + changes.push((cp, object, create.lamport_version().value(), true)); step_checkpoints.push(cp); - // A checkpoint passes before the next step, so the object is live but unchanged in it. - wait_for_fullnode_checkpoint_above(&cluster, cp).await; + // Bump the gas coin `create` paid with in a checkpoint of its own, in which the object is live + // but unchanged, and pay for `set_value` with that coin, so the object skips a version between + // creation and the mutation. + let bump_tx = cluster + .test_transaction_builder_with_gas_object(sender, create.gas_object().unwrap().0) + .await + .transfer_sui(None, sender) + .build(); + let (bump, _) = execute(&cluster, bump_tx).await; - let (set_value, cp) = call_object_basics( - &cluster, - package_id, - "set_value", - vec![owned_arg(output_ref(&create, object)), pure_arg(&8u64)], - ) - .await; - changes.push((cp, object, Some(set_value.lamport_version().value()))); + let set_value_tx = cluster + .test_transaction_builder_with_gas_object(sender, bump.gas_object().unwrap().0) + .await + .move_call( + package_id, + "object_basics", + "set_value", + vec![owned_arg(output_ref(&create, object)), pure_arg(&8u64)], + ) + .build(); + let (set_value, cp) = execute(&cluster, set_value_tx).await; + changes.push((cp, object, set_value.lamport_version().value(), true)); step_checkpoints.push(cp); let (wrap, cp) = call_object_basics( @@ -278,8 +295,8 @@ async fn get_object_at_checkpoint_lifecycle() { ) .await; let wrapper = created_object(&wrap); - changes.push((cp, object, None)); - changes.push((cp, wrapper, Some(wrap.lamport_version().value()))); + changes.push((cp, object, wrap.lamport_version().value(), false)); + changes.push((cp, wrapper, wrap.lamport_version().value(), true)); step_checkpoints.push(cp); let (unwrap, cp) = call_object_basics( @@ -289,18 +306,18 @@ async fn get_object_at_checkpoint_lifecycle() { vec![owned_arg(output_ref(&wrap, wrapper))], ) .await; - changes.push((cp, object, Some(unwrap.lamport_version().value()))); - changes.push((cp, wrapper, None)); + changes.push((cp, object, unwrap.lamport_version().value(), true)); + changes.push((cp, wrapper, unwrap.lamport_version().value(), false)); step_checkpoints.push(cp); - let (_delete, cp) = call_object_basics( + let (delete, cp) = call_object_basics( &cluster, package_id, "delete", vec![owned_arg(output_ref(&unwrap, object))], ) .await; - changes.push((cp, object, None)); + changes.push((cp, object, delete.lamport_version().value(), false)); step_checkpoints.push(cp); // Each step waits for its checkpoint before the next step is built, so every step lands in @@ -320,43 +337,161 @@ async fn get_object_at_checkpoint_lifecycle() { // `at_checkpoint` reads are bounded by the rpc index's highest indexed checkpoint. cluster.wait_for_rpc_index_ready().await; + // The expected outcome of each read, from the changes: the live change a read selects, as + // (checkpoint, version), kept only if it was made by the end of the bound. + let changes_of = |id: ObjectID| { + changes + .iter() + .filter(move |(_, changed, _, _)| *changed == id) + }; + let bounded = |selected: Option<&(u64, ObjectID, u64, bool)>, at_checkpoint: Option| { + selected + .filter(|&&(changed_at, _, _, live)| { + live && at_checkpoint.is_none_or(|bound| changed_at <= bound) + }) + .map(|&(_, _, version, _)| version) + }; + // Every checkpoint from just before creation through deletion, for both objects. Checkpoints // between two changes resolve to the earlier change. - let mut cases: Vec<(Address, u64, Option)> = Vec::new(); + let mut cases: Vec<(GetObjectRequest, Option, String)> = Vec::new(); for checkpoint in first_cp - 1..=last_cp { for id in [object, wrapper] { - let expected_version = changes - .iter() - .rev() - .find(|(cp, changed, _)| *changed == id && *cp <= checkpoint) - .and_then(|(_, _, version)| *version); - cases.push((Address::from(id), checkpoint, expected_version)); + let latest_change = + changes_of(id).rfind(|(changed_at, _, _, _)| *changed_at <= checkpoint); + cases.push(( + at_checkpoint_request(Address::from(id), checkpoint), + bounded(latest_change, None), + format!( + "Object {} at checkpoint {checkpoint} not found", + Address::from(id) + ), + )); } } - // One batch covering every case twice: results come back in request order, and duplicate + // Every version from just before creation to just after deletion, read exactly and as a + // `max_version`, unbounded and bounded by each of those checkpoints, for both objects. + let versions = changes.iter().map(|&(_, _, version, _)| version); + let first_version = versions.clone().min().unwrap() - 1; + let last_version = versions.max().unwrap() + 1; + let bounds = std::iter::once(None).chain((first_cp - 1..=last_cp).map(Some)); + for id in [object, wrapper] { + let address = Address::from(id); + for version in first_version..=last_version { + for at_checkpoint in bounds.clone() { + let at = at_checkpoint + .map(|checkpoint| format!(" at checkpoint {checkpoint}")) + .unwrap_or_default(); + let exact = changes_of(id).find(|(_, _, changed, _)| *changed == version); + cases.push(( + selector_request(address, Some(version), None, at_checkpoint), + bounded(exact, at_checkpoint), + format!("Object {address} with version {version}{at} not found"), + )); + // The newest change at or below `version`, kept only if it was made by the bound. + let at_most = changes_of(id).rfind(|(_, _, changed, _)| *changed <= version); + cases.push(( + selector_request(address, None, Some(version), at_checkpoint), + bounded(at_most, at_checkpoint), + format!("Object {address} with version at most {version}{at} not found"), + )); + } + } + } + + // Batches covering every case twice: results come back in request order, and duplicate // items each get their own result. - let batch_cases: Vec<_> = cases.iter().chain(cases.iter()).copied().collect(); - let BatchGetObjectsResponse { objects, .. } = client + let batch_cases: Vec<_> = cases.iter().chain(cases.iter()).collect(); + for chunk in batch_cases.chunks(500) { + let BatchGetObjectsResponse { objects, .. } = client + .batch_get_objects({ + let mut message = BatchGetObjectsRequest::default(); + message.requests = chunk + .iter() + .map(|(request, _, _)| request.clone()) + .collect(); + message + }) + .await + .unwrap() + .into_inner(); + assert_eq!(objects.len(), chunk.len()); + for (result, (request, expected, not_found)) in objects.iter().zip_debug_eq(chunk) { + assert_outcome(batch_outcome(result), request, *expected, not_found); + } + } + + // At the checkpoint that created the object, `max_version` set to the created version reads + // it, and set to the mutation's version selects the mutation, written after that checkpoint, + // so the read fails rather than fall back to the created version. At the mutation's + // checkpoint, the mutation answers. + let (create_cp, _, create_version, _) = changes[0]; + let (set_value_cp, _, set_value_version, _) = changes[1]; + for (max_version, at_checkpoint, expected) in [ + (create_version, create_cp, Some(create_version)), + (set_value_version, create_cp, None), + (set_value_version, set_value_cp, Some(set_value_version)), + ] { + let request = selector_request( + Address::from(object), + None, + Some(max_version), + Some(at_checkpoint), + ); + let not_found = format!( + "Object {} with version at most {max_version} at checkpoint {at_checkpoint} not found", + Address::from(object), + ); + let outcome = single_outcome(client.get_object(request.clone()).await); + assert_outcome(outcome, &request, expected, ¬_found); + } + + // The object skips a version between creation and the mutation, so the cases above include + // a `max_version` between two of its versions. One in that gap reads the created version, + // unbounded and bounded by the mutation's checkpoint. + let in_gap = create_version + 1; + assert!(in_gap < set_value_version, "no version gap: {changes:?}"); + for at_checkpoint in [None, Some(set_value_cp)] { + let request = selector_request(Address::from(object), None, Some(in_gap), at_checkpoint); + let outcome = single_outcome(client.get_object(request.clone()).await); + assert_outcome(outcome, &request, Some(create_version), ""); + } + + // Setting both `version` and `max_version` is invalid, and fails the whole batch. + let both = selector_request( + Address::from(object), + Some(set_value_version), + Some(set_value_version), + None, + ); + let error = client.get_object(both.clone()).await.unwrap_err(); + assert_eq!(error.code(), tonic::Code::InvalidArgument); + assert!( + error.message().contains("mutually exclusive"), + "{}", + error.message() + ); + assert_eq!(bad_request_fields(&error), ["requests[0].max_version"]); + + let error = client .batch_get_objects({ let mut message = BatchGetObjectsRequest::default(); - message.requests = batch_cases - .iter() - .map(|&(id, checkpoint, _)| at_checkpoint_request(id, checkpoint)) - .collect(); + message.requests = vec![ + GetObjectRequest::new(&Address::from(object)), + selector_request(Address::from(object), Some(set_value_version), None, None), + both, + ]; message }) .await - .unwrap() - .into_inner(); - assert_eq!(objects.len(), batch_cases.len()); - for (result, &(id, checkpoint, expected_version)) in objects.iter().zip_debug_eq(&batch_cases) { - assert_at_checkpoint(batch_outcome(result), id, checkpoint, expected_version); - } + .unwrap_err(); + assert_eq!(error.code(), tonic::Code::InvalidArgument); + assert_eq!(bad_request_fields(&error), ["requests[2].max_version"]); } /// A checkpoint above the rpc index's highest indexed checkpoint is rejected rather than served -/// from the latest state. +/// from the latest state, including as the bound of a `version` or `max_version` read. #[sim_test] async fn get_object_at_checkpoint_not_yet_indexed() { let cluster = TestClusterBuilder::new() @@ -373,11 +508,14 @@ async fn get_object_at_checkpoint_not_yet_indexed() { let id: Address = "0x5".parse().unwrap(); - let error = client - .get_object(at_checkpoint_request(id, u64::MAX)) - .await - .unwrap_err(); - assert_above_latest_available(&error, "at_checkpoint", u64::MAX); + for request in [ + at_checkpoint_request(id, u64::MAX), + selector_request(id, Some(1), None, Some(u64::MAX)), + selector_request(id, None, Some(1), Some(u64::MAX)), + ] { + let error = client.get_object(request.clone()).await.unwrap_err(); + assert_above_latest_available(&error, "at_checkpoint", u64::MAX); + } // So is an object that does not exist, rather than `NotFound`. let unknown = Address::from(ObjectID::random()); @@ -423,7 +561,10 @@ async fn get_object_at_checkpoint_not_yet_indexed() { } /// Pruning object versions through a checkpoint leaves the state at its end readable and rejects -/// every checkpoint below it as pruned. +/// every checkpoint below it as pruned, including as the bound of a `version` or `max_version` +/// read. A `version` or `max_version` read of a version the prune deleted is rejected at the +/// object lower bound, the checkpoint after the last pruned one, with or without `at_checkpoint`; +/// a version above the object's latest is `NOT_FOUND`. #[sim_test] async fn get_object_at_checkpoint_below_available_floor() { let cluster = TestClusterBuilder::new() @@ -466,34 +607,68 @@ async fn get_object_at_checkpoint_below_available_floor() { ); assert_at_checkpoint(outcome, id, pruned_to, Some(at_end)); for checkpoint in [0, pruned_to - 1] { - let error = client - .get_object(at_checkpoint_request(id, checkpoint)) - .await - .unwrap_err(); - assert_below_earliest_available(&error, pruned_to); + for request in [ + at_checkpoint_request(id, checkpoint), + selector_request(id, Some(1), None, Some(checkpoint)), + selector_request(id, None, Some(1), Some(checkpoint)), + ] { + let error = client.get_object(request.clone()).await.unwrap_err(); + assert_below_earliest_available(&error, pruned_to); + } } - // Inside a batch, a pruned checkpoint fails only its own item. + // The version the checkpoint before the last pruned one ended with is gone, so reading it + // exactly or as a `max_version` fails at the object lower bound, also bounded by a checkpoint + // the at_checkpoint lower bound accepts. A version above the latest does not exist yet. + let objects_lower_bound = pruned_to + 1; + for request in [ + selector_request(id, Some(before_end), None, None), + selector_request(id, None, Some(before_end), None), + selector_request(id, Some(before_end), None, Some(pruned_to)), + selector_request(id, None, Some(before_end), Some(pruned_to)), + ] { + let error = client.get_object(request.clone()).await.unwrap_err(); + assert_below_earliest_available(&error, objects_lower_bound); + } + let outcome = single_outcome( + client + .get_object(selector_request(id, Some(u64::MAX), None, None)) + .await, + ); + assert_eq!( + outcome.unwrap_err(), + ( + tonic::Code::NotFound, + format!("Object {id} with version {} not found", u64::MAX) + ) + ); + + // Inside a batch, a pruned checkpoint or version fails only its own item. let BatchGetObjectsResponse { objects, .. } = client .batch_get_objects({ let mut message = BatchGetObjectsRequest::default(); message.requests = vec![ at_checkpoint_request(id, pruned_to - 1), at_checkpoint_request(id, pruned_to), + selector_request(id, Some(before_end), None, None), + selector_request(id, Some(at_end), None, None), ]; message }) .await .unwrap() .into_inner(); - assert_eq!(objects.len(), 2); - match &objects[0].result { - Some(get_object_result::Result::Error(status)) => { - assert_below_earliest_available(status, pruned_to); + assert_eq!(objects.len(), 4); + for (item, floor) in [(0, pruned_to), (2, objects_lower_bound)] { + match &objects[item].result { + Some(get_object_result::Result::Error(status)) => { + assert_below_earliest_available(status, floor); + } + other => panic!("expected a per-item error, got {other:?}"), } - other => panic!("expected a per-item error, got {other:?}"), } assert_at_checkpoint(batch_outcome(&objects[1]), id, pruned_to, Some(at_end)); + assert_eq!(batch_outcome(&objects[3]).unwrap().version, Some(at_end)); } /// A request for `id` as of the end of `checkpoint`, reading its id and version. @@ -504,6 +679,22 @@ fn at_checkpoint_request(id: Address, checkpoint: u64) -> GetObjectRequest { request } +/// A request for `id` with the given `version`, `max_version` and `at_checkpoint`, reading its id +/// and version. +fn selector_request( + id: Address, + version: Option, + max_version: Option, + at_checkpoint: Option, +) -> GetObjectRequest { + let mut request = GetObjectRequest::new(&id); + request.version = version; + request.max_version = max_version; + request.at_checkpoint = at_checkpoint; + request.read_mask = Some(FieldMask::from_paths(["object_id", "version"])); + request +} + /// A `GetObject` outcome: the object, or the error's code and message. type ObjectOutcome = Result; @@ -565,6 +756,45 @@ fn assert_at_checkpoint( } } +/// Assert that `request` returned `expected_version`, or `NotFound` with the message `not_found` +/// when there is no expected version. +fn assert_outcome( + outcome: ObjectOutcome, + request: &GetObjectRequest, + expected_version: Option, + not_found: &str, +) { + let context = format!( + "{:?}: version {:?}, max_version {:?}, at_checkpoint {:?}", + request.object_id, request.version, request.max_version, request.at_checkpoint, + ); + match (outcome, expected_version) { + (Ok(object), Some(version)) => { + assert_eq!(object.object_id, request.object_id, "{context}"); + assert_eq!(object.version, Some(version), "{context}"); + } + (Err((code, message)), None) => { + assert_eq!(code, tonic::Code::NotFound, "{context}: {message}"); + assert_eq!(message, not_found, "{context}"); + } + (outcome, expected_version) => { + panic!("{context}: expected version {expected_version:?}, got {outcome:?}") + } + } +} + +/// The fields named by the `BadRequest` field violations in `status`'s details. +fn bad_request_fields(status: &tonic::Status) -> Vec { + sui_rpc::proto::google::rpc::Status::decode(status.details()) + .expect("error details should decode as google.rpc.Status") + .details + .iter() + .filter_map(|detail| detail.to_msg::().ok()) + .flat_map(|bad_request| bad_request.field_violations) + .map(|violation| violation.field) + .collect() +} + /// A transaction builder for address 0, paying with one of its current gas coins. async fn tx_builder(cluster: &TestCluster) -> TestTransactionBuilder { let sender = cluster.get_address_0(); @@ -579,28 +809,6 @@ async fn tx_builder(cluster: &TestCluster) -> TestTransactionBuilder { .await } -/// Wait until the fullnode has executed a checkpoint above `checkpoint`. -async fn wait_for_fullnode_checkpoint_above(cluster: &TestCluster, checkpoint: u64) { - let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(60); - loop { - let highest_executed = cluster.fullnode_handle.sui_node.with(|node| { - node.state() - .get_checkpoint_store() - .get_highest_executed_checkpoint_seq_number() - .expect("db error") - .unwrap_or(0) - }); - if highest_executed > checkpoint { - return; - } - assert!( - tokio::time::Instant::now() < deadline, - "timed out waiting for the fullnode to execute a checkpoint above {checkpoint}" - ); - tokio::time::sleep(std::time::Duration::from_millis(100)).await; - } -} - /// Sign and execute `tx_data` as address 0, wait for it to be checkpointed, and return its /// effects and checkpoint. async fn execute(cluster: &TestCluster, tx_data: TransactionData) -> (TransactionEffects, u64) { diff --git a/crates/sui-fork/design/storage.md b/crates/sui-fork/design/storage.md index c0c617a9e8ce..8efd72aaa479 100644 --- a/crates/sui-fork/design/storage.md +++ b/crates/sui-fork/design/storage.md @@ -214,12 +214,16 @@ authoritative, no row means never fetched and sends the read to the remote. "The state" below sets out what may write to that index and why. - A request bounded by a version is the subtle one. It asks for the highest version at or -below some bound, which is how child objects are read during execution. A stored row at or -below the bound is only trustworthy if the fork knows nothing newer can exist below it, which -holds when that row carries live-state authority or is a tombstone. Absent that, the sparse -cache may hold some older version that an unrelated historical read left behind, and serving -it would be wrong, so the bound must also be resolved against the live network and the -higher of the two answers taken. +below some bound, which is how child objects are read during execution and how `GetObject` +serves `max_version`. The stored rows are complete only from the object's earliest +checkpoint-pinned version upward, which is either its version at the fork point or its first +local change, so they answer only a bound at or above that version. Below it, the sparse cache +may hold some older version that an unrelated historical read left behind, and serving it would +be wrong, so the live network answers instead. Its newest version within the bound may come +from after the fork point, though, so the fork first asks for the object's version at the fork +point, and records it there. That version answers if it is within the bound. Otherwise every +version within the bound is older than the fork point, or the object was not live at the fork +point, and a query pinned at the fork point returns the newest one that existed by then. - A request pinned at a checkpoint asks for the version the object had at the end of it, and `object_version_by_checkpoint` answers it whenever it holds a row at or below that checkpoint. @@ -355,27 +359,6 @@ type-keyed lookup against the live network when something asks, and cache the re object like any other. This is not a limit of forking — unlike the ledger range below — just work not done. -The remote leg of a bounded read is not pinned at the fork point. Where the latest and -exact-version object queries carry the fork checkpoint explicitly, the bounded query carries -only its version bound, so it resolves against the live network's *current* state. -Post-fork history on the other chain can therefore answer a read inside this fork, which is -the one thing every other remote path is built to prevent. It reaches `read_child_object` on -both the RPC and executor paths, so it can skew execution rather than only reads. - -That gap and the one below compound rather than merely coexisting, which is worth noticing -before either is fixed: the fix proposed below is to merge the remote `RootVersion(bound)` -result with the local candidate, and merging in an unpinned answer would make the remote leg -authoritative precisely where it is least trustworthy. Pinning has to land first. - -Bounded child reads can also serve stale history. `get_object_lt_or_eq_version` trusts the -highest *local* row at or below the bound, so a sparse cache polluted by an -exact-historical-version read, an RPC client fetching an old dynamic-field version say, can -hold a row lower than the true highest-≤-bound, which then wins without the remote ever -being consulted. This affects `read_child_object` on both the RPC and executor paths, so it -can skew execution and not only reads. Closing it means short-circuiting only on a live-state -row or a tombstone, and otherwise merging the remote `RootVersion(bound)` result with the -local candidate by maximum version. - The fork's ledger index begins at the fork point, and the range below it is permanently empty. Positions are inherited rather than restarted: Simulacrum is seeded with the real fork checkpoint, whose summary carries the chain's `network_total_transactions`, and each diff --git a/crates/sui-fork/src/gql/client.rs b/crates/sui-fork/src/gql/client.rs index 3bc1420bf271..ec1d0acf2398 100644 --- a/crates/sui-fork/src/gql/client.rs +++ b/crates/sui-fork/src/gql/client.rs @@ -1145,11 +1145,11 @@ mod tests { #[tokio::test] async fn test_get_objects() { - // Exercises the multiGetObjects batch path, which serves the - // "standard" key kinds. `VersionAtCheckpoint` keys are routed to a - // separate checkpoint-scoped query and are covered elsewhere. + // Exercises the multiGetObjects batch path, which serves `AtCheckpoint` + // keys. Keys pinned at a checkpoint with a version or root version are + // routed to a separate checkpoint-scoped query and are covered elsewhere. let server = MockServer::start().await; - let root_version_object = Object::immutable_with_id_for_testing(ObjectID::random()); + let found_object = Object::immutable_with_id_for_testing(ObjectID::random()); let missing_object_id = ObjectID::random(); Mock::given(method("POST")) @@ -1159,8 +1159,8 @@ mod tests { "variables": { "keys": [ { - "address": root_version_object.id().to_string(), - "rootVersion": 17, + "address": found_object.id().to_string(), + "atCheckpoint": 17, }, { "address": missing_object_id.to_string(), @@ -1171,7 +1171,7 @@ mod tests { }))) .respond_with( ResponseTemplate::new(200) - .set_body_json(object_response_body(&[Some(&root_version_object), None])), + .set_body_json(object_response_body(&[Some(&found_object), None])), ) .mount(&server) .await; @@ -1180,8 +1180,8 @@ mod tests { let objects = store .get_objects(&[ ObjectKey { - object_id: root_version_object.id(), - version_query: VersionQuery::RootVersion(17), + object_id: found_object.id(), + version_query: VersionQuery::AtCheckpoint(17), }, ObjectKey { object_id: missing_object_id, @@ -1193,10 +1193,7 @@ mod tests { assert_eq!( objects, vec![ - Some(( - root_version_object.clone(), - root_version_object.version().value(), - )), + Some((found_object.clone(), found_object.version().value())), None, ] ); @@ -1275,6 +1272,66 @@ mod tests { assert!(!query.contains("atCheckpoint")); } + /// A root-version bound pinned at a checkpoint goes through the checkpoint-scoped query, whose + /// scope drops a version created after the checkpoint instead of returning it. + #[tokio::test] + async fn test_get_object_root_version_at_checkpoint() { + let server = MockServer::start().await; + let object = Object::immutable_with_id_for_testing(ObjectID::random()); + + Mock::given(method("POST")) + .and(path("/")) + .and(body_partial_json(json!({ + "variables": { + "sequenceNumber": 31, + "keys": [{ + "address": object.id().to_string(), + "rootVersion": 40, + }], + } + }))) + .respond_with( + ResponseTemplate::new(200) + .set_body_json(versioned_object_at_checkpoint_response_body(Some(&object))), + ) + .expect(1) + .mount(&server) + .await; + + let store = mock_store(&server); + let objects = store + .get_objects(&[ObjectKey { + object_id: object.id(), + version_query: VersionQuery::RootVersionAtCheckpoint { + root_version: 40, + checkpoint: 31, + }, + }]) + .expect("root version query should succeed"); + + assert_eq!( + objects, + vec![Some((object.clone(), object.version().value()))] + ); + + let requests = server + .received_requests() + .await + .expect("wiremock should record requests"); + let request_body: serde_json::Value = requests[0] + .body_json() + .expect("request body should be json"); + let query = request_body + .get("query") + .and_then(serde_json::Value::as_str) + .expect("query string should be present"); + assert!(query.contains("checkpoint(sequenceNumber: $sequenceNumber)")); + assert!( + request_body["variables"]["keys"][0]["atCheckpoint"].is_null(), + "the pin lives on the query scope, not on the key", + ); + } + /// Seeding hydrates every manifest entry through this path, so a regression to one request per /// object is the difference between two round trips and seventy. Nothing about the returned /// values would reveal it — only the request count does. diff --git a/crates/sui-fork/src/gql/mod.rs b/crates/sui-fork/src/gql/mod.rs index 13784196ed02..43b218f027e7 100644 --- a/crates/sui-fork/src/gql/mod.rs +++ b/crates/sui-fork/src/gql/mod.rs @@ -49,17 +49,21 @@ pub(crate) struct ObjectKey { pub(crate) version_query: VersionQuery, } -/// Version rule for an object query. +/// Version rule for an object query. Every rule is pinned at a checkpoint, so that post-fork +/// state on the live network cannot answer a read inside the fork. +#[allow(clippy::enum_variant_names)] #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)] pub(crate) enum VersionQuery { - /// Request the highest version of the object at or below the given version. - RootVersion(u64), - /// Request the object as of the given checkpoint. Useful when the version is unknown. AtCheckpoint(u64), /// Request an exact version, but only if it existed by the given checkpoint. VersionAtCheckpoint { version: u64, checkpoint: u64 }, + + /// Request the highest version of the object at or below `root_version`, but only if that + /// version existed by the given checkpoint and is not a deletion or wrap. It does not fall + /// back to an older version when the highest one was created after the checkpoint. + RootVersionAtCheckpoint { root_version: u64, checkpoint: u64 }, } /// The `ObjectRead` trait is used to retrieve objects by their keys, with different query options. diff --git a/crates/sui-fork/src/gql/queries.rs b/crates/sui-fork/src/gql/queries.rs index 7060914d5e6e..895529a6f8c4 100644 --- a/crates/sui-fork/src/gql/queries.rs +++ b/crates/sui-fork/src/gql/queries.rs @@ -1436,31 +1436,52 @@ pub(crate) mod object_query { let mut results: Vec>> = vec![None; keys.len()]; let mut standard_indices: Vec = Vec::with_capacity(keys.len()); let mut standard_keys: Vec = Vec::with_capacity(keys.len()); - // Exact versions pinned at a checkpoint go through a checkpoint-scoped + // Keys pinned at a checkpoint go through a checkpoint-scoped // multi-get instead, so they batch too; grouped by checkpoint because // the pin lives on the query rather than on each key. let mut pinned: BTreeMap, Vec)> = BTreeMap::new(); - for (idx, key) in keys.iter().cloned().enumerate() { - match key.version_query { + for (idx, key) in keys.iter().enumerate() { + let address = SuiAddress(key.object_id.to_string()); + let (checkpoint, scoped_key) = match key.version_query { + VersionQuery::AtCheckpoint(checkpoint) => { + standard_indices.push(idx); + standard_keys.push(ObjectKey { + address, + version: None, + root_version: None, + at_checkpoint: Some(checkpoint), + }); + continue; + } VersionQuery::VersionAtCheckpoint { version, checkpoint, - } => { - let (indices, keys) = pinned.entry(checkpoint).or_default(); - indices.push(idx); - keys.push(ObjectKey { - address: SuiAddress(key.object_id.to_string()), + } => ( + checkpoint, + ObjectKey { + address, version: Some(version), root_version: None, at_checkpoint: None, - }); - } - _ => { - standard_indices.push(idx); - standard_keys.push(ObjectKey::from(key)); - } - } + }, + ), + VersionQuery::RootVersionAtCheckpoint { + root_version, + checkpoint, + } => ( + checkpoint, + ObjectKey { + address, + version: None, + root_version: Some(root_version), + at_checkpoint: None, + }, + ), + }; + let (indices, keys) = pinned.entry(checkpoint).or_default(); + indices.push(idx); + keys.push(scoped_key); } for (checkpoint, (indices, keys)) in pinned { @@ -1510,13 +1531,14 @@ pub(crate) mod object_query { .collect()) } - /// Fetch exact object versions, each returned only if it already existed at `checkpoint`. + /// Fetch objects by exact version or root version, each returned only if the version found + /// already existed at `checkpoint`. /// /// The checkpoint pins the *query scope* rather than each key, which is what lets these batch: /// `multiGetObjects` rejects a key carrying more than one bound, so a key with both a version /// and an `atCheckpoint` cannot be sent. Scoping instead keeps the guard intact — a scoped - /// exact-version read resolves through `Object::at_version`, which drops any version created - /// after the checkpoint in scope, so post-fork state still cannot leak into a diverged fork. + /// read drops any version created after the checkpoint in scope, without falling back to an + /// older one, so post-fork state still cannot leak into a diverged fork. async fn query_versions_at_checkpoint( keys: Vec, checkpoint: u64, @@ -1574,71 +1596,10 @@ pub(crate) mod object_query { } } - impl From for ObjectKey { - fn from(key: GqlObjectKey) -> Self { - ObjectKey { - address: SuiAddress(key.object_id.to_string()), - version: match key.version_query { - VersionQuery::VersionAtCheckpoint { - version, - checkpoint, - } => Some(version), - _ => None, - }, - root_version: match key.version_query { - VersionQuery::RootVersion(v) => Some(v), - _ => None, - }, - at_checkpoint: match key.version_query { - VersionQuery::AtCheckpoint(v) => Some(v), - VersionQuery::VersionAtCheckpoint { - version, - checkpoint, - } => Some(checkpoint), - _ => None, - }, - } - } - } - #[cfg(test)] mod tests { - use sui_types::base_types::ObjectID; - use super::*; - #[test] - fn object_key_from_version_query_sets_only_selected_bound() { - let object_id = ObjectID::random(); - - let root_version_key = ObjectKey::from(GqlObjectKey { - object_id, - version_query: VersionQuery::RootVersion(11), - }); - assert_eq!(root_version_key.version, None); - assert_eq!(root_version_key.root_version, Some(11)); - assert_eq!(root_version_key.at_checkpoint, None); - - let checkpoint_key = ObjectKey::from(GqlObjectKey { - object_id, - version_query: VersionQuery::AtCheckpoint(19), - }); - assert_eq!(checkpoint_key.version, None); - assert_eq!(checkpoint_key.root_version, None); - assert_eq!(checkpoint_key.at_checkpoint, Some(19)); - - let object_key = ObjectKey::from(GqlObjectKey { - object_id, - version_query: VersionQuery::VersionAtCheckpoint { - version: 23, - checkpoint: 29, - }, - }); - assert_eq!(object_key.version, Some(23)); - assert_eq!(object_key.root_version, None); - assert_eq!(object_key.at_checkpoint, Some(29)); - } - #[test] fn decode_object_fragment_returns_none_for_missing_object() { assert_eq!(decode_object_fragment(None).unwrap(), None); diff --git a/crates/sui-fork/src/local_store.rs b/crates/sui-fork/src/local_store.rs index 32e25cfa9ad9..c09c7a3fa6a8 100644 --- a/crates/sui-fork/src/local_store.rs +++ b/crates/sui-fork/src/local_store.rs @@ -169,6 +169,26 @@ impl LocalStore { self.highest_status_at_or_before(id, upper_bound) } + /// Return the checkpoint and version of the object's earliest checkpoint-pinned row. + /// + /// The object rows are complete from that version upward. The row is either the object's + /// version at the fork checkpoint, resolved by a remote query pinned there, or the object's + /// first locally executed change, and every later version was executed locally. Below it, the + /// rows are a sparse cache of historical reads. + pub(crate) fn earliest_checkpoint_pinned_version( + &self, + id: ObjectID, + ) -> anyhow::Result> { + let Some(row) = self.schema.iter_object_versions_by_checkpoint(id)?.next() else { + return Ok(None); + }; + let (key, value) = row?; + Ok(Some(( + key.checkpoint, + SequenceNumber::from_u64(value.into_inner().version), + ))) + } + /// Save an object version without changing current live state or indexes. /// /// Use this for exact-version and bounded historical reads, and choose a live-object write diff --git a/crates/sui-fork/src/remote.rs b/crates/sui-fork/src/remote.rs index 9c71829c8efd..cff06fc3de99 100644 --- a/crates/sui-fork/src/remote.rs +++ b/crates/sui-fork/src/remote.rs @@ -126,13 +126,24 @@ impl RemoteSource { ) } - /// Fetch the highest object version at or below `version_bound` (bounded child reads). + /// Fetch the highest object version at or below `version_bound`, only if it existed by the + /// fork checkpoint and is live. + /// + /// `None` also when that version was created after the fork checkpoint, without falling back + /// to an older one, so a caller must first rule out that the object's version at the fork + /// checkpoint is itself within the bound. pub(crate) fn object_at_or_before( &self, object_id: &ObjectID, version_bound: u64, ) -> anyhow::Result> { - self.object_query(object_id, VersionQuery::RootVersion(version_bound)) + self.object_query( + object_id, + VersionQuery::RootVersionAtCheckpoint { + root_version: version_bound, + checkpoint: self.forked_at_checkpoint, + }, + ) } /// Fetch an object by ID and version query, only if it existed by the fork checkpoint. diff --git a/crates/sui-fork/src/store.rs b/crates/sui-fork/src/store.rs index 4d770679bc3c..70ce5d81cada 100644 --- a/crates/sui-fork/src/store.rs +++ b/crates/sui-fork/src/store.rs @@ -312,20 +312,17 @@ impl ForkStore { Ok(object) } - /// Get the latest object version at or below the given root version. + /// Get the object's highest version at or below `version_bound`, or `None` if it has none or + /// that version is a deletion or wrap. /// - /// TODO(fork): this trusts the highest local row at or below the bound, which is only the true - /// highest when the local history is complete below the bound. A sparse cache polluted by an - /// exact-historical-version read (e.g. an RPC client fetching an old dynamic-field version) can - /// hold a lower live row than the chain's true highest at the bound, and this read then serves - /// that stale row without the remote ever being consulted. Reachable from `read_child_object` - /// on both the RPC and the executor paths, so it can skew execution as well as reads. Candidate - /// fix (undecided): short-circuit only on an authoritative current version at or below the - /// bound, or on a tombstone, and otherwise query the remote `RootVersion(bound)` and take the - /// max-version of the remote result and the local candidate. Optionally let executor-driven - /// bounds (always the parent's current root version, which Lamport-dominates the child) claim - /// currency on fetch so each child pays the remote round-trip once. Tracked in - /// design/storage.md § "Known gaps". + /// The local rows answer when the bound reaches the object's earliest checkpoint-pinned + /// version, because they are complete from there upward. Below it they are a sparse cache of + /// historical reads, so the remote answers instead, in two steps, because the remote's newest + /// version within the bound may have been created after the fork checkpoint. The object's + /// version at the fork checkpoint answers if it is within the bound. Otherwise every version + /// within the bound is older than that one, or the object was not live at the fork + /// checkpoint, and a query pinned at the fork checkpoint returns the newest of them that + /// existed by then. fn get_object_lt_or_eq_version( &self, object_id: &ObjectID, @@ -343,20 +340,37 @@ impl ForkStore { Some((_, Status::Tombstone(_))) => return Ok(None), None => {} } - match local_store.get_object_at_or_before(*object_id, version_bound)? { - Some((_, Status::Live(object))) => return Ok(Some(object)), - Some((_, Status::Tombstone(_))) => return Ok(None), - None => {} + + let earliest_pinned = local_store.earliest_checkpoint_pinned_version(*object_id)?; + if earliest_pinned.is_some_and(|(_, version)| version <= version_bound) { + return match local_store.get_object_at_or_before(*object_id, version_bound)? { + Some((_, Status::Live(object))) => Ok(Some(object)), + Some((_, Status::Tombstone(_))) => Ok(None), + None => Err(anyhow!( + "object {object_id} has a checkpoint-pinned version at or below \ + {version_bound} but no object row there" + )), + }; + } + + // A row at the fork checkpoint already records the object's version there, which is + // above the bound. + let resolved_at_fork = earliest_pinned + .is_some_and(|(checkpoint, _)| checkpoint == self.forked_at_checkpoint()); + if !resolved_at_fork + && let Some(object) = self.fetch_object_at_fork_checkpoint(object_id)? + && object.version() <= version_bound + { + return Ok(Some(object)); } let object = self .inner .remote .object_at_or_before(object_id, version_bound.value())?; - if let Some(ref object) = object { + if let Some(object) = &object { local_store.save_object_version_only(object)?; } - Ok(object) } @@ -1114,6 +1128,16 @@ impl RpcStateReader for ForkStore { fn layout_package_store(&self) -> Box { self.stock_reader().layout_package_store() } + + /// Resolve through the overlay, the local store, then the remote, as the inherent + /// `ForkStore::get_object_lt_or_eq_version` does for child-object reads. + fn get_object_lt_or_eq_version( + &self, + object_id: &ObjectID, + version: SequenceNumber, + ) -> StorageResult> { + ForkStore::get_object_lt_or_eq_version(self, object_id, version).map_err(to_storage_error) + } } /// Every index read delegates to the stock reader except diff --git a/crates/sui-fork/src/tests/store_execution.rs b/crates/sui-fork/src/tests/store_execution.rs index c378603e36d5..7542a761b169 100644 --- a/crates/sui-fork/src/tests/store_execution.rs +++ b/crates/sui-fork/src/tests/store_execution.rs @@ -982,28 +982,43 @@ fn test_owned_objects_tracks_consensus_address_owner_writes() { assert_eq!(infos[0].balance, Some(1_000_000)); } +/// The local rows answer a bounded read once it reaches the version recorded at the fork +/// checkpoint, since every later version was executed locally. The dummy remote would surface as +/// an error if the read fell through. #[test] fn test_read_child_object_uses_highest_local_version_within_bound() { - let (_temp, store) = data_store(); + let (_temp, mut store) = data_store(); let parent = ObjectID::random(); let child_id = ObjectID::random(); let child_v5 = make_gas_object(child_id, 5, Owner::ObjectOwner(parent.into())); let child_v7 = make_gas_object(child_id, 7, Owner::ObjectOwner(parent.into())); - let local_store = store.local_store(); - local_store.save_object_version_only(&child_v5).unwrap(); - local_store.save_object_version_only(&child_v7).unwrap(); - - let child = sui_types::storage::RuntimeObjectResolver::read_child_object( - &store, - &parent, - &child_id, - SequenceNumber::from_u64(6), - ) - .expect("bounded child read should not error") - .expect("child object should be found"); + store + .local_store() + .save_object_at_fork_checkpoint(&child_v5) + .unwrap(); + store.update_objects(BTreeMap::from([(child_id, child_v7.clone())]), vec![]); + let checkpoint = + sui_types::test_checkpoint_data_builder::TestCheckpointBuilder::new(1).build_checkpoint(); + store.insert_checkpoint(VerifiedCheckpoint::new_unchecked(checkpoint.summary)); + store.insert_checkpoint_contents(checkpoint.contents); - assert_eq!(child, child_v5); + for (bound, expected) in [ + (5, &child_v5), + (6, &child_v5), + (7, &child_v7), + (8, &child_v7), + ] { + let child = sui_types::storage::RuntimeObjectResolver::read_child_object( + &store, + &parent, + &child_id, + SequenceNumber::from_u64(bound), + ) + .expect("bounded child read should not error") + .expect("child object should be found"); + assert_eq!(&child, expected, "at or below version {bound}"); + } } /// Bounded child reads must see versions the in-flight checkpoint staged but has not yet sealed, or @@ -1036,8 +1051,10 @@ fn test_read_child_object_sees_staged_versions_within_bound() { ); } +/// A child the fork holds no row for resolves from its version at the fork checkpoint, which the +/// fork then records, so later reads within the bound stay local. #[tokio::test] -async fn test_read_child_object_falls_back_to_remote_root_version() { +async fn test_read_child_object_falls_back_to_the_remote_version_at_the_fork() { let temp = tempfile::tempdir().expect("failed to create tempdir"); let checkpoint = 42; let parent = ObjectID::random(); @@ -1045,36 +1062,194 @@ async fn test_read_child_object_falls_back_to_remote_root_version() { let child = make_gas_object(child_id, 5, Owner::ObjectOwner(parent.into())); let server = MockServer::start().await; + mock_live_object_at_checkpoint(&server, checkpoint, &child, 1).await; + + let (store, _services) = data_store_with_remote(temp.path(), server.uri(), checkpoint); + for _ in 0..2 { + let read = sui_types::storage::RuntimeObjectResolver::read_child_object( + &store, + &parent, + &child_id, + SequenceNumber::from_u64(6), + ) + .expect("remote bounded child read should not error") + .expect("child object should be found"); + assert_eq!(read, child); + } + assert_eq!( + store + .local_store() + .get_latest_object_status(child_id) + .unwrap(), + Some((SequenceNumber::from_u64(5), Status::Live(child))), + ); +} + +/// Serve the newest version of `object_id` at or below `root_version` that existed by +/// `checkpoint`, as the checkpoint-scoped query answers it. +async fn mock_root_version_at_checkpoint( + server: &MockServer, + checkpoint: u64, + object_id: ObjectID, + root_version: u64, + object: Option<&Object>, +) { + let response = match object { + Some(object) => object_at_checkpoint_response(&[object]), + None => serde_json::json!({ + "data": { "checkpoint": { "query": { "multiGetObjects": [null] } } } + }), + }; Mock::given(method("POST")) .and(path("/")) .and(body_partial_json(serde_json::json!({ "variables": { - "keys": [ - { - "address": child_id.to_string(), - "rootVersion": 6, - }, - ], + "sequenceNumber": checkpoint, + "keys": [{ + "address": object_id.to_string(), + "rootVersion": root_version, + }], } }))) - .respond_with(ResponseTemplate::new(200).set_body_json(objects_response(&[Some(&child)]))) - .mount(&server) + .respond_with(ResponseTemplate::new(200).set_body_json(response)) + .with_priority(1) + .mount(server) .await; +} - let (store, _services) = data_store_with_remote(temp.path(), server.uri(), checkpoint); - let read = sui_types::storage::RuntimeObjectResolver::read_child_object( - &store, - &parent, - &child_id, - SequenceNumber::from_u64(6), +/// Serve `object` as the live network's newest version at or below `root_version`, with no +/// checkpoint scope, as the network answers after the fork checkpoint. +async fn mock_unpinned_root_version( + server: &MockServer, + object_id: ObjectID, + root_version: u64, + object: &Object, +) { + Mock::given(method("POST")) + .and(path("/")) + .and(body_partial_json(serde_json::json!({ + "variables": { + "keys": [{ + "address": object_id.to_string(), + "rootVersion": root_version, + }], + } + }))) + .respond_with(ResponseTemplate::new(200).set_body_json(objects_response(&[Some(object)]))) + .mount(server) + .await; +} + +/// The live network's newest version within a bound may come from after the fork checkpoint, so +/// a bounded read must not take it: an object live at the fork checkpoint answers with its version +/// there, and one that did not exist yet answers with nothing. +#[tokio::test] +async fn test_bounded_read_never_serves_versions_created_after_the_fork() { + use sui_rpc_api::RpcService; + use sui_rpc_api::proto::sui::rpc::v2::GetObjectRequest; + use sui_rpc_api::proto::sui::rpc::v2::ledger_service_server::LedgerService; + + let temp = tempfile::tempdir().expect("failed to create tempdir"); + let fork_checkpoint = 100; + let owner = Owner::AddressOwner(SuiAddress::random_for_testing_only()); + let server = MockServer::start().await; + mock_available_range(&server, 10).await; + + // Live at the fork checkpoint at version 10, then changed to 20 on the live network. + let id = ObjectID::random(); + let before_fork = make_gas_object(id, 3, owner.clone()); + let at_fork = make_gas_object(id, 10, owner.clone()); + mock_live_object_at_checkpoint(&server, fork_checkpoint, &at_fork, 1).await; + mock_unpinned_root_version(&server, id, 50, &make_gas_object(id, 20, owner.clone())).await; + mock_root_version_at_checkpoint(&server, fork_checkpoint, id, 5, Some(&before_fork)).await; + + // Created on the live network after the fork checkpoint. + let created_id = ObjectID::random(); + Mock::given(method("POST")) + .and(path("/")) + .and(body_partial_json(serde_json::json!({ + "variables": { + "keys": [{ + "address": created_id.to_string(), + "atCheckpoint": fork_checkpoint, + }], + } + }))) + .respond_with(ResponseTemplate::new(200).set_body_json(objects_response(&[None]))) + .mount(&server) + .await; + mock_unpinned_root_version( + &server, + created_id, + 50, + &make_gas_object(created_id, 20, owner), ) - .expect("remote bounded child read should not error") - .expect("child object should be found"); + .await; + mock_root_version_at_checkpoint(&server, fork_checkpoint, created_id, 50, None).await; + + let (store, _services) = data_store_with_remote(temp.path(), server.uri(), fork_checkpoint); + store.local_store().restore_seed_objects(&[]).unwrap(); + let bounded = |id: ObjectID, bound: u64| { + RpcStateReader::get_object_lt_or_eq_version(&store, &id, SequenceNumber::from_u64(bound)) + .expect("bounded read should not error") + .map(|object| object.version().value()) + }; - assert_eq!(read, child); + // `GetObject` with `max_version` above both the version at the fork and the live network's + // later version answers with the version at the fork. + let service = RpcService::new(Arc::new(store.clone())); + let mut request = GetObjectRequest::default(); + request.object_id = Some(id.to_string()); + request.max_version = Some(50); + let read = service + .get_object(tonic::Request::new(request)) + .await + .expect("max_version read should succeed") + .into_inner() + .object + .unwrap(); + assert_eq!(read.version, Some(10), "the version at the fork answers"); + + assert_eq!( + bounded(id, 15), + Some(10), + "the recorded version answers locally" + ); assert_eq!( - ForkStore::get_object_at_version(&store, &child_id, 5).unwrap(), - Some(child), + bounded(id, 5), + Some(3), + "an older version resolves pinned at the fork" + ); + assert_eq!(bounded(created_id, 50), None); +} + +/// A cached exact version below the object's version at the fork checkpoint is not the newest +/// version within a bound, because the fork does not hold the versions between them. +#[tokio::test] +async fn test_bounded_read_ignores_cached_history_below_the_fork_version() { + let temp = tempfile::tempdir().expect("failed to create tempdir"); + let fork_checkpoint = 100; + let owner = Owner::AddressOwner(SuiAddress::random_for_testing_only()); + let id = ObjectID::random(); + let cached = make_gas_object(id, 3, owner.clone()); + let newest_within_bound = make_gas_object(id, 5, owner.clone()); + let at_fork = make_gas_object(id, 10, owner); + + let server = MockServer::start().await; + mock_live_object_at_checkpoint(&server, fork_checkpoint, &at_fork, 1).await; + mock_root_version_at_checkpoint(&server, fork_checkpoint, id, 6, Some(&newest_within_bound)) + .await; + + let (store, _services) = data_store_with_remote(temp.path(), server.uri(), fork_checkpoint); + store + .local_store() + .save_object_version_only(&cached) + .unwrap(); + + assert_eq!( + RpcStateReader::get_object_lt_or_eq_version(&store, &id, SequenceNumber::from_u64(6)) + .unwrap(), + Some(newest_within_bound), ); } @@ -1088,7 +1263,7 @@ fn test_read_child_object_rejects_wrong_owner_after_bounded_lookup() { store .local_store() - .save_object_version_only(&child) + .save_object_at_fork_checkpoint(&child) .unwrap(); let err = sui_types::storage::RuntimeObjectResolver::read_child_object( diff --git a/crates/sui-fork/src/tests/store_rpc_traits.rs b/crates/sui-fork/src/tests/store_rpc_traits.rs index 678807a03f7b..696b7ad45426 100644 --- a/crates/sui-fork/src/tests/store_rpc_traits.rs +++ b/crates/sui-fork/src/tests/store_rpc_traits.rs @@ -137,3 +137,62 @@ fn ledger_indexes_delegate_to_rpc_store() { .expect("event bitmap iterator should decode rows"); assert!(event_bitmap_rows.is_empty()); } + +/// The RPC trait's `get_object_lt_or_eq_version`, which serves `GetObject`'s `max_version`, +/// returns the newest version at or below each bound from the fork's own writes, and `None` where +/// the newest one is a removal. A bound below every local version would fall back to the remote. +#[test] +fn object_lt_or_eq_version_stops_at_removals() { + let temp = tempfile::tempdir().expect("tempdir"); + let services = ServiceManager::open( + temp.path(), + "custom".to_owned(), + 0, + CheckpointDigest::new([9; 32]).into(), + ) + .expect("service manager should open"); + let mut store = ForkStore::new_for_testing(temp.path().to_path_buf(), services.local_store()); + + // Live at 1, wrapped at 3, and unwrapped at 4. + let id = ObjectID::random(); + let live = |version: u64| { + Object::with_id_owner_version_for_testing( + id, + SequenceNumber::from_u64(version), + sui_types::object::Owner::AddressOwner(SuiAddress::ZERO), + ) + }; + store + .apply_object_updates(BTreeMap::from([(id, live(1))]), vec![]) + .expect("creation should stage"); + store + .apply_object_updates( + BTreeMap::new(), + vec![ObjectRemoval { + object_id: id, + version: SequenceNumber::from_u64(3), + kind: TombstoneKind::Wrapped, + }], + ) + .expect("wrap should stage"); + store + .apply_object_updates(BTreeMap::from([(id, live(4))]), vec![]) + .expect("unwrap should stage"); + + for (bound, expected) in [ + (1, Some(1)), + (2, Some(1)), + (3, None), + (4, Some(4)), + (u64::MAX, Some(4)), + ] { + let found = RpcStateReader::get_object_lt_or_eq_version( + &store, + &id, + SequenceNumber::from_u64(bound), + ) + .expect("local versions should answer without the remote") + .map(|object| object.version().value()); + assert_eq!(found, expected, "at or below version {bound}"); + } +} diff --git a/crates/sui-fork/src/tests/support.rs b/crates/sui-fork/src/tests/support.rs index 5379c1f01d33..1eda4a9c9b1b 100644 --- a/crates/sui-fork/src/tests/support.rs +++ b/crates/sui-fork/src/tests/support.rs @@ -9,13 +9,22 @@ use wiremock::ResponseTemplate; use wiremock::matchers::body_string_contains; use wiremock::matchers::method; -/// Mock remote that reports every object lookup as "not found". Execution routinely probes dynamic -/// fields that exist nowhere, and the fallible child-read path must see an authoritative remote -/// miss rather than a transport error, which propagates instead of reading as absent. Other query -/// shapes still fail fast (404), preserving the harness rule that tests pre-populate everything -/// else they need. +/// Mock remote that reports every object lookup as "not found", through both the plain and the +/// checkpoint-scoped object queries. Execution routinely probes dynamic fields that exist +/// nowhere, and the fallible child-read path must see an authoritative remote miss rather than a +/// transport error, which propagates instead of reading as absent. Other query shapes still fail +/// fast (404), preserving the harness rule that tests pre-populate everything else they need. pub(crate) async fn absent_objects_gql_server() -> MockServer { let server = MockServer::start().await; + Mock::given(method("POST")) + .and(body_string_contains("multiGetObjects")) + .and(body_string_contains("checkpoint(sequenceNumber")) + .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({ + "data": { "checkpoint": { "query": { "multiGetObjects": [null] } } } + }))) + .with_priority(1) + .mount(&server) + .await; Mock::given(method("POST")) .and(body_string_contains("multiGetObjects")) .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({ diff --git a/crates/sui-indexer-alt-e2e-tests/tests/kv_rpc_tests.rs b/crates/sui-indexer-alt-e2e-tests/tests/kv_rpc_tests.rs index 1d4002060a47..9bc3ed610120 100644 --- a/crates/sui-indexer-alt-e2e-tests/tests/kv_rpc_tests.rs +++ b/crates/sui-indexer-alt-e2e-tests/tests/kv_rpc_tests.rs @@ -128,8 +128,9 @@ struct CheckpointsResult { fn request_ordering(options: Option<&QueryOptions>) -> Ordering { options.map(|o| o.ordering()).unwrap_or(Ordering::Ascending) } -/// A cluster whose kv-rpc server serves the List APIs and `at_checkpoint` object reads. The -/// latter is off by default, matching production, so every test in this file opts in. +/// A cluster whose kv-rpc server serves the List APIs, and `at_checkpoint` and `max_version` +/// object reads. The object reads are off by default, matching production, so every test in +/// this file opts in. async fn list_api_cluster() -> FullCluster { list_api_cluster_with_config(KvRpcConfig::default()).await } @@ -1417,8 +1418,9 @@ fn pure_arg(value: &T) -> CallArg { } /// One `basics::object_basics::Object` driven through create, set_value, wrap, unwrap, and delete, -/// one step per checkpoint, with an empty checkpoint between create and set_value. Wrapping -/// creates `wrapper`, and unwrapping deletes it. +/// one step per checkpoint, with a checkpoint between create and set_value that only bumps the +/// gas coin's version. `set_value` pays with that coin, so the object skips a version between +/// create and set_value. Wrapping creates `wrapper`, and unwrapping deletes it. struct ObjectLifecycle { object: ObjectID, wrapper: ObjectID, @@ -1461,8 +1463,9 @@ impl ObjectLifecycle { create.lamport_version().value(), true, )); - // Seal an empty checkpoint, in which the object is live but unchanged. - cluster.create_checkpoint().await; + // Bump the gas coin in a checkpoint of its own, in which the object is live but + // unchanged. + let gas = transfer_in_own_checkpoint(cluster, sender, kp, gas).await; let (set_value, set_value_checkpoint, gas) = call_object_basics( cluster, @@ -1562,6 +1565,17 @@ fn object_request( req } +/// A `GetObjectRequest` for `id` with the given `max_version` and `at_checkpoint`. +fn max_version_request( + id: ObjectID, + max_version: u64, + at_checkpoint: Option, +) -> GetObjectRequest { + let mut req = object_request(id, None, at_checkpoint); + req.max_version = Some(max_version); + req +} + fn batch_request(requests: Vec) -> BatchGetObjectsRequest { let mut req = BatchGetObjectsRequest::default(); req.requests = requests; @@ -1638,13 +1652,7 @@ fn assert_not_live_at_checkpoint(read: &ObjectRead, id: ObjectID, checkpoint: u6 "Object {} at checkpoint {checkpoint} not found", id.to_canonical_string(true) ); - match read { - Err((code, message)) => { - assert_eq!(*code, tonic::Code::NotFound, "{context}: {message}"); - assert_eq!(message, &expected, "{context}"); - } - Ok(object) => panic!("{context}: expected NotFound, got {object:?}"), - } + assert_not_found(read, &expected, context); } /// Assert `read` is the `OutOfRange` (`ABOVE_LATEST_AVAILABLE`) for an `at_checkpoint` above the @@ -1784,35 +1792,7 @@ async fn test_get_object_at_checkpoint() { } } - // 4. Setting both `version` and `at_checkpoint` is invalid, and fails the whole batch. - let both = || { - object_request( - object, - Some(set_value_version), - Some(lifecycle.set_value_checkpoint), - ) - }; - let read = get_object_read(&mut client, both()).await; - match read { - Err((code, message)) => { - assert_eq!(code, tonic::Code::InvalidArgument, "{message}"); - assert!(message.contains("mutually exclusive"), "{message}"); - } - Ok(object) => panic!("expected InvalidArgument, got {object:?}"), - } - - let err = client - .batch_get_objects(batch_request(vec![ - object_request(gas.0, None, None), - object_request(object, None, Some(lifecycle.set_value_checkpoint)), - both(), - ])) - .await - .unwrap_err(); - assert_eq!(err.code(), tonic::Code::InvalidArgument, "{err:?}"); - assert_eq!(bad_request_fields(&err), ["requests[2].at_checkpoint"]); - - // 5. Every read above asks only for `object_id` and `version`, which the version index + // 4. Every read above asks only for `object_id` and `version`, which the version index // answers alone. A mask that needs more, such as `digest`, reads the object itself, and gets // the same object as an exact-version read of the version the index resolved. let digest_mask = || FieldMask::from_paths(["object_id", "version", "digest"]); @@ -1893,15 +1873,194 @@ async fn test_get_object_at_checkpoint_disabled_by_default() { assert_not_served_here(&err, "disabled_by_config"); // Validation runs before the capability check. + let version = gas.1.value(); + let mut both = max_version_request(gas.0, version, Some(checkpoint)); + both.version = Some(version); + let err = client + .batch_get_objects(batch_request(vec![both])) + .await + .unwrap_err(); + assert_eq!(err.code(), tonic::Code::InvalidArgument, "{err:?}"); +} + +/// Assert `read` is a `NotFound` with `message`. +fn assert_not_found(read: &ObjectRead, message: &str, context: &str) { + match read { + Err((code, actual)) => { + assert_eq!(*code, tonic::Code::NotFound, "{context}: {actual}"); + assert_eq!(actual, message, "{context}"); + } + Ok(object) => panic!("{context}: expected NotFound, got {object:?}"), + } +} + +/// `max_version` reads resolve an object to its newest version at or below the bound, through +/// creation, mutation, wrapping, unwrapping, and deletion, and are `NotFound` from a deletion or +/// wrap until the object is unwrapped. `at_checkpoint` bounds a `version` read to a version +/// written by the end of the checkpoint, and fails a `max_version` read whose selected version +/// was written after the checkpoint, as Postgres does. `GetObject` and `BatchGetObjects` agree +/// item by item. +#[tokio::test] +async fn test_get_object_max_version_and_checkpoint_bounds() { + let mut cluster = list_api_cluster().await; + let (sender, kp, gas) = cluster.funded_account(10 * DEFAULT_GAS_BUDGET).unwrap(); + let lifecycle = ObjectLifecycle::run(&mut cluster, sender, &kp, gas).await; + let ObjectLifecycle { + object, wrapper, .. + } = lifecycle; + + let mut client = LedgerServiceClient::connect(cluster.kv_rpc_url().to_string()) + .await + .unwrap(); + let served_height = client + .get_service_info(GetServiceInfoRequest::default()) + .await + .unwrap() + .into_inner() + .checkpoint_height + .expect("served height should be set"); + assert!(served_height >= lifecycle.delete_checkpoint); + + // The expected outcome of each read, from the lifecycle's `(checkpoint, object, version, + // live)` changes: the version it returns, or `None` if it is `NotFound`. + let changes = |id: ObjectID| { + lifecycle + .changes + .iter() + .filter(move |(_, changed, _, _)| *changed == id) + }; + // An exact version, kept only if it was made by the end of `at_checkpoint`. + let exact = |id: ObjectID, version: u64, at_checkpoint: Option| { + changes(id) + .find(|&&(_, _, changed, live)| live && changed == version) + .filter(|&&(changed_at, ..)| at_checkpoint.is_none_or(|bound| changed_at <= bound)) + .map(|&(_, _, version, _)| version) + }; + // The newest version at or below `version` (every change is within the served height), if it + // was made by the end of `at_checkpoint` and the object is live at it. + let at_most = |id: ObjectID, version: u64, at_checkpoint: Option| { + changes(id) + .rfind(|&&(_, _, changed, _)| changed <= version) + .filter(|&&(changed_at, ..)| at_checkpoint.is_none_or(|bound| changed_at <= bound)) + .filter(|&&(_, _, _, live)| live) + .map(|&(_, _, version, _)| version) + }; + + // Every version from just before creation to just after deletion, each read exactly and as a + // `max_version`, unbounded and bounded by every checkpoint from just before creation through + // deletion, for both objects. + let versions: Vec = lifecycle + .changes + .iter() + .map(|&(_, _, version, _)| version) + .collect(); + let first_version = versions.iter().min().unwrap() - 1; + let last_version = versions.iter().max().unwrap() + 1; + let bounds: Vec> = std::iter::once(None) + .chain((lifecycle.publish_checkpoint..=lifecycle.delete_checkpoint).map(Some)) + .collect(); + let mut cases: Vec<(GetObjectRequest, Option, String)> = Vec::new(); + for id in [object, wrapper] { + let id_string = id.to_canonical_string(true); + for version in first_version..=last_version { + for &at_checkpoint in &bounds { + let at = at_checkpoint + .map(|checkpoint| format!(" at checkpoint {checkpoint}")) + .unwrap_or_default(); + cases.push(( + object_request(id, Some(version), at_checkpoint), + exact(id, version, at_checkpoint), + format!("Object {id_string} with version {version}{at} not found"), + )); + cases.push(( + max_version_request(id, version, at_checkpoint), + at_most(id, version, at_checkpoint), + format!("Object {id_string} with version at most {version}{at} not found"), + )); + } + } + } + + let assert_case = |read: &ObjectRead, + req: &GetObjectRequest, + expected: Option, + message: &str, + how: &str| { + let id: ObjectID = req.object_id.as_deref().unwrap().parse().unwrap(); + let context = format!( + "{how}: version {:?}, max_version {:?}, at_checkpoint {:?}", + req.version, req.max_version, req.at_checkpoint, + ); + match expected { + Some(version) => assert_object_found(read, id, version, &context), + None => assert_not_found(read, message, &context), + } + }; + for (req, expected, message) in &cases { + let read = get_object_read(&mut client, req.clone()).await; + assert_case(&read, req, *expected, message, "GetObject"); + } + let batch = batch_get_object_reads( + &mut client, + cases.iter().map(|(req, _, _)| req.clone()).collect(), + ) + .await; + for (read, (req, expected, message)) in batch.iter().zip_eq(&cases) { + assert_case(read, req, *expected, message, "BatchGetObjects"); + } + + // The object skips a version between creation and the mutation, so the cases above include + // a `max_version` between two of its versions. One in that gap reads the created version, + // unbounded and bounded by the mutation's checkpoint. + let (_, _, create_version, _) = lifecycle.changes[0]; + let set_value_version = lifecycle + .live_version_at(object, lifecycle.set_value_checkpoint) + .unwrap(); + let in_gap = create_version + 1; + assert!( + in_gap < set_value_version, + "no version gap: {:?}", + lifecycle.changes + ); + for at_checkpoint in [None, Some(lifecycle.set_value_checkpoint)] { + let read = get_object_read( + &mut client, + max_version_request(object, in_gap, at_checkpoint), + ) + .await; + assert_object_found( + &read, + object, + create_version, + &format!("max_version {in_gap} at_checkpoint {at_checkpoint:?}"), + ); + } + + // Setting both `version` and `max_version` is invalid, and fails the whole batch. + let both = || { + let mut req = max_version_request(object, set_value_version, None); + req.version = Some(set_value_version); + req + }; + let read = get_object_read(&mut client, both()).await; + match read { + Err((code, message)) => { + assert_eq!(code, tonic::Code::InvalidArgument, "{message}"); + assert!(message.contains("mutually exclusive"), "{message}"); + } + Ok(object) => panic!("expected InvalidArgument, got {object:?}"), + } + let err = client - .batch_get_objects(batch_request(vec![object_request( - gas.0, - Some(gas.1.value()), - Some(checkpoint), - )])) + .batch_get_objects(batch_request(vec![ + object_request(object, None, None), + object_request(object, Some(set_value_version), None), + both(), + ])) .await .unwrap_err(); assert_eq!(err.code(), tonic::Code::InvalidArgument, "{err:?}"); + assert_eq!(bad_request_fields(&err), ["requests[2].max_version"]); } #[tokio::test] diff --git a/crates/sui-kv-rpc/src/bigtable_client.rs b/crates/sui-kv-rpc/src/bigtable_client.rs index 7b258cfeed66..643d479cc6ee 100644 --- a/crates/sui-kv-rpc/src/bigtable_client.rs +++ b/crates/sui-kv-rpc/src/bigtable_client.rs @@ -281,6 +281,22 @@ impl BigTableClient { .await } + /// The newest version of `object_id` at or below `version`, unless the + /// object was deleted or wrapped at that version. One reverse range scan of + /// the `objects` table, under one permit. + pub(crate) async fn get_object_lt_or_eq_version( + &self, + object_id: ObjectID, + version: SequenceNumber, + ) -> Result, RpcError> { + let mut inner = self.inner.clone(); + self.call_gated( + stage::OBJECTS, + inner.get_object_lt_or_eq_version(object_id, version), + ) + .await + } + pub(crate) async fn resolve_tx_digests_stream( &self, tx_sequence_numbers: Vec, diff --git a/crates/sui-kv-rpc/src/config.rs b/crates/sui-kv-rpc/src/config.rs index e1c72c73ede0..65ec343b46b1 100644 --- a/crates/sui-kv-rpc/src/config.rs +++ b/crates/sui-kv-rpc/src/config.rs @@ -641,25 +641,29 @@ pub struct KvRpcConfig { pub bigtable_http2_connection_window_bytes: Option, /// Deprecated and ignored: the `GetServiceInfo` watermark set always - /// includes the List API pipelines, adds the object versions index when - /// `enable-object-at-checkpoint` is on, and cannot be chosen per pipeline. + /// includes the List API pipelines, adds the object versions index and the + /// object tombstones when `enable-object-at-checkpoint` is on, and cannot be + /// chosen per pipeline. /// Still parsed so existing config files keep loading. #[serde(skip_serializing_if = "Option::is_none")] pub watermark_pipeline: Option>, - /// Serve `GetObject` and `BatchGetObjects` requests that set `at_checkpoint`, and fold the - /// alpha `kvstore_object_versions_by_checkpoint` pipeline into the `GetServiceInfo` - /// checkpoint height. Defaults to `false`, which rejects those requests with - /// `Unimplemented` (`NOT_SERVED_HERE`, cause `disabled_by_config`). + /// Serve `GetObject` and `BatchGetObjects` requests that set `at_checkpoint` or + /// `max_version`, and fold the alpha `kvstore_object_versions_by_checkpoint` and + /// `kvstore_object_tombstones` pipelines into the `GetServiceInfo` checkpoint height. + /// Defaults to `false`, which rejects those requests with `Unimplemented` (`NOT_SERVED_HERE`, + /// cause `disabled_by_config`). /// - /// Enable this only after `kvstore_object_versions_by_checkpoint` has been backfilled from - /// genesis. Its table has no restore floor, so an object unchanged since before the - /// pipeline's first checkpoint would wrongly read as `NotFound`. The server cannot check - /// this: a backfill run as a separate task writes its own watermark row, so the main + /// Enable this only after both pipelines have been backfilled from genesis. The versions + /// index has no restore floor, so an object unchanged since before the pipeline's first + /// checkpoint would wrongly read as `NotFound`. A `max_version` read stops at the tombstone + /// written where the object was deleted or wrapped; without it, the read resolves to the + /// object's last live version before the removal instead of `NotFound`. The server cannot + /// check this: a backfill run as a separate task writes its own watermark row, so a main /// pipeline's `reader_lo` does not say whether history is complete. Setting this flag is the /// operator's statement that it is. /// - /// If this is on but the pipeline is not running, the pipeline has no watermark and the + /// If this is on but either pipeline is not running, that pipeline has no watermark and the /// `GetServiceInfo` height cannot be computed: `/health` reports this replica not ready, and /// every request bounded by the served height fails with `Unavailable`. Requests that do not /// use the served height, such as latest and exact-version `GetObject` reads, are still @@ -1221,27 +1225,33 @@ render-ahead = 3 #[test] fn object_at_checkpoint_off_by_default_and_bounds_the_watermark_set() { + let object_pipelines = [ + sui_kvstore::OBJECT_VERSIONS_BY_CHECKPOINT_PIPELINE, + sui_kvstore::OBJECT_TOMBSTONES_PIPELINE, + ]; let cfg = KvRpcConfig::default(); assert!(!cfg.enable_object_at_checkpoint()); - assert!( - !service_info_watermark_pipelines( - cfg.ledger_history().bitmap_schema(), - cfg.enable_object_at_checkpoint() - ) - .contains(&sui_kvstore::OBJECT_VERSIONS_BY_CHECKPOINT_PIPELINE) + let pipelines = service_info_watermark_pipelines( + cfg.ledger_history().bitmap_schema(), + cfg.enable_object_at_checkpoint(), ); + for pipeline in object_pipelines { + assert!(!pipelines.contains(&pipeline), "{pipeline}"); + } let yaml = "enable-object-at-checkpoint: true\n"; let cfg: KvRpcConfig = serde_yaml::from_str(yaml).unwrap(); assert!(cfg.enable_object_at_checkpoint()); - assert!( - service_info_watermark_pipelines( - cfg.ledger_history().bitmap_schema(), - cfg.enable_object_at_checkpoint() - ) - .contains(&sui_kvstore::OBJECT_VERSIONS_BY_CHECKPOINT_PIPELINE), - "the object versions index must bound the height", + let pipelines = service_info_watermark_pipelines( + cfg.ledger_history().bitmap_schema(), + cfg.enable_object_at_checkpoint(), ); + for pipeline in object_pipelines { + assert!( + pipelines.contains(&pipeline), + "{pipeline} must bound the height" + ); + } } #[test] diff --git a/crates/sui-kv-rpc/src/indexer_streams.rs b/crates/sui-kv-rpc/src/indexer_streams.rs index 1bab92bf9f10..edf7b2245fee 100644 --- a/crates/sui-kv-rpc/src/indexer_streams.rs +++ b/crates/sui-kv-rpc/src/indexer_streams.rs @@ -382,7 +382,8 @@ mod tests { let mut client = BigTableClient::new_local(bigtable.to_string(), "test".to_string()) .await .expect("connect to mock Bigtable"); - seed_watermarks(&mut client, |_| 50).await; + let pipelines = service_info_watermark_pipelines(BitmapSchema::V2, false); + seed_watermarks(&mut client, &pipelines, |_| 50).await; mock.clear_read_rows_calls().await; // The only indexer has not advanced the epoch end pipeline since it started. diff --git a/crates/sui-kv-rpc/src/lib.rs b/crates/sui-kv-rpc/src/lib.rs index 57cddb9bded4..7ff8d327a99f 100644 --- a/crates/sui-kv-rpc/src/lib.rs +++ b/crates/sui-kv-rpc/src/lib.rs @@ -19,6 +19,7 @@ pub use sui_kvstore::ChannelHealthConfig; use sui_kvstore::EPOCH_END_PIPELINE; use sui_kvstore::EPOCH_START_PIPELINE; use sui_kvstore::KeyValueStoreReader; +use sui_kvstore::OBJECT_TOMBSTONES_PIPELINE; use sui_kvstore::OBJECT_VERSIONS_BY_CHECKPOINT_PIPELINE; use sui_kvstore::OBJECTS_PIPELINE; use sui_kvstore::PACKAGES_BY_ID_PIPELINE; @@ -297,10 +298,11 @@ pub struct KvRpcServer { pub(crate) request_bigtable_concurrency: usize, pub(crate) monotonic_read_wait_timeout: Duration, pub(crate) stages: StagesConfig, - /// `at_checkpoint` object reads need the alpha - /// [`OBJECT_VERSIONS_BY_CHECKPOINT_PIPELINE`], backfilled from genesis (see - /// [`KvRpcConfig::enable_object_at_checkpoint`]). Instances without it - /// reject those reads with `Unimplemented` (`NOT_SERVED_HERE`, cause `disabled_by_config`). + /// `at_checkpoint` and `max_version` object reads need the alpha + /// [`OBJECT_VERSIONS_BY_CHECKPOINT_PIPELINE`] and [`OBJECT_TOMBSTONES_PIPELINE`], + /// backfilled from genesis (see [`KvRpcConfig::enable_object_at_checkpoint`]). + /// Instances without them reject those reads with `Unimplemented` (`NOT_SERVED_HERE`, cause + /// `disabled_by_config`). object_at_checkpoint_enabled: bool, } @@ -687,7 +689,8 @@ impl KvRpcServer { /// Pipelines whose watermarks bound the checkpoint height reported by `GetServiceInfo`, so an /// instance does not advertise a height it cannot serve. [`OBJECT_VERSIONS_BY_CHECKPOINT_PIPELINE`] -/// is among them when `at_checkpoint` object reads are enabled. +/// and [`OBJECT_TOMBSTONES_PIPELINE`] are among them when `at_checkpoint` and `max_version` +/// object reads are enabled. pub fn service_info_watermark_pipelines( bitmap_schema: BitmapSchema, enable_object_at_checkpoint: bool, @@ -710,6 +713,7 @@ pub fn service_info_watermark_pipelines( ]; if enable_object_at_checkpoint { pipelines.push(OBJECT_VERSIONS_BY_CHECKPOINT_PIPELINE); + pipelines.push(OBJECT_TOMBSTONES_PIPELINE); } pipelines } @@ -775,13 +779,14 @@ mod tests { .expect("start kv-rpc server") } - /// Write a watermark row for every pipeline a v2 replica serves, at the checkpoint - /// `checkpoint_of` names for it. + /// Write a watermark row for each of `pipelines`, at the checkpoint `checkpoint_of` names for + /// it. pub(crate) async fn seed_watermarks( client: &mut BigTableClient, + pipelines: &[&str], checkpoint_of: impl Fn(&str) -> u64, ) { - for pipeline in service_info_watermark_pipelines(BitmapSchema::V2, false) { + for &pipeline in pipelines { let checkpoint = checkpoint_of(pipeline); client .create_pipeline_watermark_if_absent( @@ -828,7 +833,8 @@ mod tests { let error = get_service_info(&server).await.unwrap_err(); assert_eq!(error.code(), tonic::Code::Unavailable); - seed_watermarks(&mut client, |_| 20).await; + let pipelines = service_info_watermark_pipelines(BitmapSchema::V2, false); + seed_watermarks(&mut client, &pipelines, |_| 20).await; timeout(WAIT, server.cache.subscribe().wait_for(Option::is_some)) .await .expect("service info never refreshed") @@ -848,7 +854,8 @@ mod tests { // The objects pipeline lags, so it bounds the served checkpoint, and the timestamp must // come from its watermark rather than from a pipeline that is further ahead. - seed_watermarks(&mut client, |pipeline| { + let pipelines = service_info_watermark_pipelines(BitmapSchema::V2, false); + seed_watermarks(&mut client, &pipelines, |pipeline| { if pipeline == OBJECTS_PIPELINE { 20 } else { 25 } }) .await; diff --git a/crates/sui-kv-rpc/src/main.rs b/crates/sui-kv-rpc/src/main.rs index c10a6345ec2e..7c1d777090b2 100644 --- a/crates/sui-kv-rpc/src/main.rs +++ b/crates/sui-kv-rpc/src/main.rs @@ -64,7 +64,8 @@ struct App { app_profile_id: Option, /// (deprecated, ignored) Pipeline watermark to include in GetServiceInfo /// checkpoint height. The set always includes the List API pipelines, plus - /// the object versions index when `enable-object-at-checkpoint` is on. + /// the object versions index and object tombstones when + /// `enable-object-at-checkpoint` is on. #[clap( long = "watermark-pipeline", value_name = "PIPELINE", @@ -158,7 +159,7 @@ fn apply_deprecated_overrides(app: App, config: &mut KvRpcConfig) { pipelines = ?ignored_pipelines, "`watermark-pipeline` is deprecated and ignored; the GetServiceInfo \ watermark set always includes the List API pipelines, plus the object \ - versions index when `enable-object-at-checkpoint` is on" + versions index and object tombstones when `enable-object-at-checkpoint` is on" ); } } diff --git a/crates/sui-kv-rpc/src/v2/get_object.rs b/crates/sui-kv-rpc/src/v2/get_object.rs index 963cdf92fbc6..42fb4ce94988 100644 --- a/crates/sui-kv-rpc/src/v2/get_object.rs +++ b/crates/sui-kv-rpc/src/v2/get_object.rs @@ -15,8 +15,11 @@ use sui_rpc::proto::sui::rpc::v2::BatchGetObjectsRequest; use sui_rpc::proto::sui::rpc::v2::BatchGetObjectsResponse; use sui_rpc::proto::sui::rpc::v2::Object as ProtoObject; use sui_rpc::proto::sui::rpc::v2::{GetObjectRequest, GetObjectResponse, GetObjectResult}; +use sui_rpc_api::AtCheckpointUpperBound; +use sui_rpc_api::NotServedHereCause; +use sui_rpc_api::RpcError; use sui_rpc_api::grpc::v2::ledger_service::{ObjectSelector, validate_get_object_requests}; -use sui_rpc_api::{NotServedHereCause, ObjectNotFoundError, RpcError, not_served_here}; +use sui_rpc_api::not_served_here; use sui_types::base_types::{ObjectID, SequenceNumber}; use sui_types::object::Object; use sui_types::storage::ObjectKey; @@ -32,65 +35,61 @@ use crate::pipeline::{ use crate::render::needs_only_object_id_and_version; use crate::render::object_to_response; use crate::render::object_version_to_response; -use crate::request_cache::CacheFetcher; +use crate::request_cache::{CacheFetcher, RequestCache}; use crate::served_height::ServedHeight; pub const MAX_BATCH_REQUESTS: usize = 1000; +/// The version and status an object had at the end of a checkpoint, from the +/// `object_versions_by_checkpoint` index: its newest version written at or before the +/// checkpoint, including a version at which it was deleted or wrapped. `None` if the object did +/// not exist yet. +type VersionAtCheckpoint = Option<(SequenceNumber, ObjectStatus)>; + +/// Serve `GetObject`. A `max_version` read counts versions up to the served height, with or +/// without `at_checkpoint`, so a version written above the served height, whose deletion or wrap +/// may not be indexed yet, never answers it. Every BigTable read goes through the request's +/// limiter. pub(crate) async fn get_object( server: &KvRpcServer, request: tonic::Request, ) -> Result { let served_height = ServedHeight::of(&request); - let GetObjectRequest { - object_id, - version, - read_mask, - at_checkpoint, - .. - } = request.into_inner(); + let mut request = request.into_inner(); + let read_mask = request.read_mask.take(); let (requests, read_mask) = - validate_get_object_requests(vec![(object_id, version, at_checkpoint)], read_mask)?; + validate_get_object_requests(std::slice::from_ref(&request), read_mask)?; let (address, selector) = requests[0]; let object_id: ObjectID = address.into(); - let version_only = needs_only_object_id_and_version(&read_mask); let client = server.limited_client("GetObject"); + // Both checks fail the request whatever the object's state, so they come before the reads. + let at_checkpoint_reads = if selector.needs_object_version_history() { + Some(Arc::new( + server.at_checkpoint_reads(client.clone(), served_height)?, + )) + } else { + None + }; let objects = ObjectReads { - client: client.clone(), - version_only, + client, + version_only: needs_only_object_id_and_version(&read_mask), }; - let found = match selector { - ObjectSelector::Latest => objects - .latest(object_id) - .await? - .ok_or_else(|| ObjectNotFoundError::new(address))?, - ObjectSelector::Version(version) => objects - .exact(ObjectKey(object_id, version.into())) - .await? - .ok_or_else(|| ObjectNotFoundError::new_with_version(address, version))?, - ObjectSelector::AtCheckpoint(checkpoint) => { - let at_checkpoint = server.at_checkpoint_reads(client, served_height)?; - if checkpoint > at_checkpoint.served_height.checkpoint { - return Err(not_yet_indexed(checkpoint, at_checkpoint.served_height)); - } - let not_found = || ObjectNotFoundError::new_at_checkpoint(address, checkpoint); - let version = at_checkpoint - .live_version_at_checkpoint(object_id, checkpoint) - .await? - .ok_or_else(not_found)?; - // A live version's row is in the objects table, so the index answers a - // version-only read without touching it. - if version_only { - Found::Version(version) - } else { - let key = ObjectKey(object_id, version); - objects - .exact(key) - .await? - .ok_or_else(|| missing_indexed_row(key))? - } - } + let answer = match first_step(object_id, selector, at_checkpoint_reads.as_ref()) { + FirstStep::Answer(answer) => answer, + FirstStep::Scan(scan) => scan.run(&objects).await?, }; + let found = match answer { + ObjectsStageInput::RequestedRow(key) => objects.exact(key).await?, + ObjectsStageInput::IndexedRow(key) => Some( + objects + .exact(key) + .await? + .ok_or_else(|| missing_indexed_row(key))?, + ), + ObjectsStageInput::Scanned(found) => found, + ObjectsStageInput::Failed(err) => return Err(err), + } + .ok_or_else(|| selector.not_found(address))?; let message = found .render(object_id, &read_mask, &server.package_resolver) .await; @@ -100,13 +99,14 @@ pub(crate) async fn get_object( /// Serve a batch as its distinct lookups, read and rendered as they become ready: /// /// 1. Each lookup first learns which `objects` row answers it, if any. An exact version names its -/// row. An `at_checkpoint` lookup scans `object_versions_by_checkpoint` for the version live at -/// that checkpoint, because BigTable cannot return the newest row of several ranges in one -/// `ReadRows` (`rows_limit` covers the whole request). A latest lookup reads its object with -/// one reverse scan of `objects`. The scans run in groups of the `objects` stage's -/// `max-seeks-per-read`, each group one read of a [`pipelined_chunks`] stage, and every group -/// starts at once. A group's answers move on together, so the rows they name fill at most one -/// `objects` read. +/// row. A latest lookup reads its object with one reverse scan of `objects`. Every other +/// lookup reads `object_versions_by_checkpoint` (see [`AtCheckpointReads`]): a `version` +/// lookup bounded by `at_checkpoint` keeps its row only if the version was written by then, +/// and an `at_checkpoint` or `max_version` lookup is answered as [`bounded_read`] decides, by +/// a live version's row or by a reverse scan of `objects` down from `max_version`. The scans +/// run in groups of the `objects` stage's `max-seeks-per-read`, each group one read of a +/// [`pipelined_chunks`] stage, and every group starts at once. A group's answers move on +/// together, so the rows they name fill at most one `objects` read. /// 2. The rows the lookups name are read as the lookups arrive, by [`pipelined_keyed_batches`] /// under the `objects` stage ([`crate::config::StagesConfig::objects`]): reads of at most /// `max-seeks-per-read` keys, at most `concurrency` of them at a time, and each row at most @@ -116,11 +116,14 @@ pub(crate) async fn get_object( /// default render-ahead), and every request for it gets the result. /// /// Every BigTable read of the batch, scans and `objects` reads alike, shares one request-scoped -/// limiter. Rendering is not limited by it: package loads go through the server-wide -/// [`PackageResolver`]. +/// limiter, and each `(object_id, checkpoint)` of the version index is read at most once per +/// request. Rendering is not limited by it: package loads go through the server-wide +/// [`PackageResolver`]. A lookup whose `at_checkpoint` is above the served height fails without +/// a read, and a batch with a lookup that the instance cannot serve fails as a whole. /// -/// When the read mask asks for nothing but `object_id` and `version`, an `at_checkpoint` lookup is -/// answered by its scan alone, and the `objects` reads fetch only row keys, not object contents. +/// When the read mask asks for nothing but `object_id` and `version`, a lookup that the version +/// index resolves to a live version is answered by its scans alone, and the `objects` reads fetch +/// only row keys, not object contents, except the reverse scans down from `max_version`. pub(crate) async fn batch_get_objects( server: &KvRpcServer, request: tonic::Request, @@ -137,11 +140,7 @@ pub(crate) async fn batch_get_objects( format!("number of batch requests exceed limit of {MAX_BATCH_REQUESTS}"), )); } - let requests = requests - .into_iter() - .map(|req| (req.object_id, req.version, req.at_checkpoint)) - .collect(); - let (requests, read_mask) = validate_get_object_requests(requests, read_mask)?; + let (requests, read_mask) = validate_get_object_requests(&requests, read_mask)?; let version_only = needs_only_object_id_and_version(&read_mask); // Requests for the same object state share one lookup: `request_lookups[i]` is the index in @@ -161,42 +160,28 @@ pub(crate) async fn batch_get_objects( // Every read of the batch goes through this client, under one request-wide limiter. let limited_client = server.limited_client("BatchGetObjects"); + let at_checkpoint_reads = if lookups + .iter() + .any(|(_, selector)| selector.needs_object_version_history()) + { + Some(Arc::new(server.at_checkpoint_reads( + limited_client.clone(), + served_height, + )?)) + } else { + None + }; let objects = ObjectReads { - client: limited_client.clone(), + client: limited_client, version_only, }; let mut answered_without_scan = Vec::new(); let mut scans = Vec::new(); - let mut at_checkpoint_lookups = Vec::new(); for (index, &(address, selector)) in lookups.iter().enumerate() { - let object_id: ObjectID = address.into(); - match selector { - ObjectSelector::Latest => scans.push((index, Scan::Latest(object_id))), - ObjectSelector::Version(version) => answered_without_scan.push(( - index, - ObjectsStageInput::RequestedRow(ObjectKey(object_id, version.into())), - )), - ObjectSelector::AtCheckpoint(checkpoint) => { - at_checkpoint_lookups.push((index, object_id, checkpoint)) - } - } - } - if !at_checkpoint_lookups.is_empty() { - let reads = Arc::new(server.at_checkpoint_reads(limited_client.clone(), served_height)?); - for (index, object_id, checkpoint) in at_checkpoint_lookups { - if checkpoint > reads.served_height.checkpoint { - let error = not_yet_indexed(checkpoint, reads.served_height); - answered_without_scan.push((index, ObjectsStageInput::Failed(error))); - } else { - let reads = reads.clone(); - let scan = Scan::AtCheckpoint { - reads, - object_id, - checkpoint, - }; - scans.push((index, scan)); - } + match first_step(address.into(), selector, at_checkpoint_reads.as_ref()) { + FirstStep::Answer(answer) => answered_without_scan.push((index, answer)), + FirstStep::Scan(scan) => scans.push((index, scan)), } } @@ -271,18 +256,9 @@ pub(crate) async fn batch_get_objects( Ok(Some(found)) => GetObjectResult::new_object( found.render(address.into(), &read_mask, &resolver).await, ), - Ok(None) => { - let not_found = match selector { - ObjectSelector::Latest => ObjectNotFoundError::new(address), - ObjectSelector::Version(version) => { - ObjectNotFoundError::new_with_version(address, version) - } - ObjectSelector::AtCheckpoint(checkpoint) => { - ObjectNotFoundError::new_at_checkpoint(address, checkpoint) - } - }; - GetObjectResult::new_error(RpcError::from(not_found).into_status_proto()) - } + Ok(None) => GetObjectResult::new_error( + RpcError::from(selector.not_found(address)).into_status_proto(), + ), Err(err) => GetObjectResult::new_error(err.into_status_proto()), }; Ok::<_, Infallible>((index, result)) @@ -325,6 +301,112 @@ pub(crate) async fn batch_get_objects( Ok(BatchGetObjectsResponse::new(objects)) } +/// Whether `version` of an object was written at or before a checkpoint, given the object's +/// [`VersionAtCheckpoint`] there. An object's versions increase in checkpoint order, so a version +/// above its newest one written by the checkpoint was written after it, and an object that did +/// not exist yet had no version written by then. +fn written_by_checkpoint( + version: SequenceNumber, + version_at_checkpoint: VersionAtCheckpoint, +) -> bool { + version_at_checkpoint.is_some_and(|(newest, _)| version <= newest) +} + +/// The bounds of an `at_checkpoint` or `max_version` read: it selects the object's newest version +/// at or below `max_version` written by the end of checkpoint `height`, and finds nothing if that +/// version was written after `checkpoint`, or deleted or wrapped the object. +#[derive(Clone, Copy, Debug)] +struct Bounds { + max_version: u64, + checkpoint: u64, + height: u64, +} + +impl Bounds { + /// The bounds of an `at_checkpoint` or `max_version` read at `served_checkpoint`; `None` for + /// other selectors. A `max_version` read counts versions up to the served height, and its + /// `at_checkpoint` defaults to it. An `at_checkpoint` read is a `max_version` read with no + /// bound on the version, counting versions up to the checkpoint. + fn of(selector: &ObjectSelector, served_checkpoint: u64) -> Option { + match *selector { + ObjectSelector::MaxVersion { + max_version, + at_checkpoint, + } => Some(Self { + max_version, + checkpoint: at_checkpoint.unwrap_or(served_checkpoint), + height: served_checkpoint, + }), + ObjectSelector::AtCheckpoint(checkpoint) => Some(Self { + max_version: u64::MAX, + checkpoint, + height: checkpoint, + }), + ObjectSelector::Latest | ObjectSelector::Version { .. } => None, + } + } +} + +/// How an `at_checkpoint` or `max_version` read is answered. See [`bounded_read`]. +#[derive(Clone, Copy, Debug)] +enum BoundedRead { + /// No version answers it. + NotFound, + /// This version, the object's version at the end of the checkpoint, answers it, and the + /// object is live at it. + Live(SequenceNumber), + /// The newest version at or below `from`, from an `objects` reverse scan, answers it if it is + /// at or below `at_most`, the object's version at the end of the checkpoint; a newer one was + /// written after the checkpoint. + ScanFrom { + from: SequenceNumber, + at_most: SequenceNumber, + }, +} + +/// How a read with [`Bounds`] is answered, given the object's [`VersionAtCheckpoint`] at +/// `checkpoint` and at `height`. An object's versions increase in checkpoint order, so a version +/// above its version at the end of a checkpoint was written after it. +/// +/// Below the version at the checkpoint, every version at or below `max_version` was written by +/// the checkpoint, so a reverse scan from `max_version` answers. Otherwise, if the object did not +/// change between the checkpoint and the height, the version index alone decides the answer: the +/// object if it is live at its version at the checkpoint, and nothing if it was deleted or wrapped +/// there. If it did change and `max_version` reaches its version at the height, that newer +/// version is selected, and nothing answers. Below it, a reverse scan from `max_version` answers +/// only if it finds the version at the checkpoint itself. Every version the scans can reach is at +/// or below the version at the height, so versions written above the height never count. +fn bounded_read( + max_version: u64, + version_at_checkpoint: VersionAtCheckpoint, + version_at_height: VersionAtCheckpoint, +) -> BoundedRead { + let Some((at_checkpoint, status)) = version_at_checkpoint else { + // Every version of the object was written after the checkpoint. + return BoundedRead::NotFound; + }; + let scan = BoundedRead::ScanFrom { + from: max_version.into(), + at_most: at_checkpoint, + }; + if max_version < at_checkpoint.value() { + return scan; + } + match version_at_height { + Some((at_height, _)) if at_height > at_checkpoint => { + if status == ObjectStatus::Live && max_version < at_height.value() { + scan + } else { + BoundedRead::NotFound + } + } + _ => match status { + ObjectStatus::Live => BoundedRead::Live(at_checkpoint), + ObjectStatus::Deleted | ObjectStatus::Wrapped => BoundedRead::NotFound, + }, + } +} + /// An object as a read found it: the whole object, or, for a read mask that needs only /// `object_id` and `version`, just its version. #[derive(Clone)] @@ -334,6 +416,13 @@ enum Found { } impl Found { + fn version(&self) -> SequenceNumber { + match self { + Found::Object(object) => object.version(), + Found::Version(version) => *version, + } + } + async fn render( &self, object_id: ObjectID, @@ -351,44 +440,133 @@ impl Found { /// [`ObjectsStageInput`], and the rows of the keys it listed. type LookupWithRows = KeyedBatchOutput<(usize, ObjectsStageInput), ObjectKey, Found>; -/// A scan that a batch lookup starts with, before any `objects` read. +/// How a lookup starts: with its answer known up to one `objects` row, or with a scan. +enum FirstStep { + Answer(ObjectsStageInput), + Scan(Scan), +} + +/// The first step of a lookup of `object_id` by `selector`. A selector that needs object version +/// history reads the version index through `at_checkpoint_reads`, and fails without a read if its +/// `at_checkpoint` is above the served height. +fn first_step( + object_id: ObjectID, + selector: ObjectSelector, + at_checkpoint_reads: Option<&Arc>, +) -> FirstStep { + match selector { + ObjectSelector::Latest => FirstStep::Scan(Scan::Latest(object_id)), + ObjectSelector::Version { + version, + at_checkpoint: None, + } => FirstStep::Answer(ObjectsStageInput::RequestedRow(ObjectKey( + object_id, + version.into(), + ))), + ObjectSelector::Version { + at_checkpoint: Some(_), + .. + } + | ObjectSelector::MaxVersion { .. } + | ObjectSelector::AtCheckpoint(_) => { + let scan = at_checkpoint_reads + .ok_or_else(|| { + RpcError::new( + tonic::Code::Internal, + "a read of object version history has no version index reads", + ) + }) + .and_then(|reads| reads.scan(object_id, selector)); + match scan { + Ok(scan) => FirstStep::Scan(scan), + Err(err) => FirstStep::Answer(ObjectsStageInput::Failed(err)), + } + } + } +} + +/// A scan that a lookup starts with, before any `objects` multi-get. enum Scan { /// The newest version of the object, from one reverse scan of `objects`. Latest(ObjectID), - /// The version live at the end of `checkpoint`, from `object_versions_by_checkpoint`. - AtCheckpoint { + /// The version `key` names, if the object's version at the end of `checkpoint` shows that it + /// was written by then. + WrittenBy { reads: Arc, - object_id: ObjectID, + key: ObjectKey, checkpoint: u64, }, + /// An `at_checkpoint` or `max_version` read, answered as [`bounded_read`] decides. + Bounded { + reads: Arc, + object_id: ObjectID, + bounds: Bounds, + }, } impl Scan { async fn run(self, objects: &ObjectReads) -> Result { Ok(match self { Scan::Latest(object_id) => ObjectsStageInput::Scanned(objects.latest(object_id).await?), - Scan::AtCheckpoint { + Scan::WrittenBy { reads, - object_id, + key, checkpoint, - } => match reads - .live_version_at_checkpoint(object_id, checkpoint) - .await? - { - None => ObjectsStageInput::Scanned(None), - // A live version's row is in the objects table, so the index answers a - // version-only read without touching it. - Some(version) if objects.version_only => { - ObjectsStageInput::Scanned(Some(Found::Version(version))) + } => { + let version_at_checkpoint = reads.version_at_checkpoint(key.0, checkpoint).await?; + if written_by_checkpoint(key.1, version_at_checkpoint) { + ObjectsStageInput::RequestedRow(key) + } else { + ObjectsStageInput::Scanned(None) } - Some(version) => ObjectsStageInput::IndexedRow(ObjectKey(object_id, version)), - }, + } + Scan::Bounded { + reads, + object_id, + bounds, + } => { + // Both reads of the version index start at once. The version at the height + // decides nothing when the object did not exist at the checkpoint, was deleted or + // wrapped there, or `max_version` is below its version there; reading it anyway + // costs a read in those cases and saves a round trip in the others. + let (version_at_checkpoint, version_at_height) = + if bounds.height == bounds.checkpoint { + let version = reads + .version_at_checkpoint(object_id, bounds.checkpoint) + .await?; + (version, version) + } else { + future::try_join( + reads.version_at_checkpoint(object_id, bounds.checkpoint), + reads.version_at_checkpoint(object_id, bounds.height), + ) + .await? + }; + match bounded_read(bounds.max_version, version_at_checkpoint, version_at_height) { + BoundedRead::NotFound => ObjectsStageInput::Scanned(None), + // A live version's row is in the objects table, so the index answers a + // version-only read without touching it. + BoundedRead::Live(version) if objects.version_only => { + ObjectsStageInput::Scanned(Some(Found::Version(version))) + } + BoundedRead::Live(version) => { + ObjectsStageInput::IndexedRow(ObjectKey(object_id, version)) + } + BoundedRead::ScanFrom { from, at_most } => ObjectsStageInput::Scanned( + objects + .at_or_below(object_id, from) + .await? + .filter(|found| found.version() <= at_most), + ), + } + } }) } } -/// What a batch lookup carries into the `objects` stage: its answer as far as it is known -/// before the `objects` reads. +/// What a lookup carries into its `objects` reads: its answer as far as it is known before +/// them. A batch hands it to the `objects` stage; `GetObject` reads its row with +/// `ObjectReads::exact`. enum ObjectsStageInput { /// The `objects` row at the version the request asked for answers the lookup; without the /// row it is `NOT_FOUND`. @@ -431,6 +609,15 @@ impl ObjectsStageInput { } } +/// The error for a version that `object_versions_by_checkpoint` names as live but that has no +/// live `objects` row: the index and storage diverged, so the object's absence is not an answer. +fn missing_indexed_row(key: ObjectKey) -> RpcError { + RpcError::new( + tonic::Code::Internal, + format!("object_versions_by_checkpoint names {key:?} as live, but objects has no live row"), + ) +} + /// Reads of the `objects` table through a request's gated client: whole objects, or, with /// `version_only`, just the versions of the live ones, read without the objects' contents. #[derive(Clone)] @@ -461,6 +648,20 @@ impl ObjectReads { let rows: Vec<_> = self.fetch(vec![key]).await?.try_collect().await?; Ok(rows.into_iter().next().map(|(_, found)| found)) } + + /// The newest version of `object_id` at or below `version`, read whole by one reverse scan of + /// `objects`, unless the object was deleted or wrapped at that version. + async fn at_or_below( + &self, + object_id: ObjectID, + version: SequenceNumber, + ) -> Result, RpcError> { + Ok(self + .client + .get_object_lt_or_eq_version(object_id, version) + .await? + .map(|object| Found::Object(Arc::new(object)))) + } } #[async_trait::async_trait] @@ -492,18 +693,19 @@ impl CacheFetcher for ObjectReads { } } -/// What a request's `at_checkpoint` reads run with: the request-scoped gated client for their -/// `object_versions_by_checkpoint` scans, and the served height that bounds them. +/// What a request's reads of the version index run with: the served height that bounds them, and +/// a cache that reads each `(object_id, checkpoint)` at most once per request, through the +/// request's gated client. struct AtCheckpointReads { - client: BigTableClient, served_height: ServedHeight, + versions: Arc>, } impl KvRpcServer { /// `Unimplemented` / `NOT_SERVED_HERE` (cause `disabled_by_config`) unless `at_checkpoint` - /// object reads are enabled; otherwise the scans read through `client`, the request's gated - /// client, at `served_height`, the height the request was admitted at (`Unavailable` if it - /// had none). + /// and `max_version` object reads are enabled; otherwise the scans read through `client`, the + /// request's gated client, at `served_height`, the height the request was admitted at + /// (`Unavailable` if it had none). fn at_checkpoint_reads( &self, client: BigTableClient, @@ -512,51 +714,105 @@ impl KvRpcServer { if !self.object_at_checkpoint_enabled { return Err(not_served_here( NotServedHereCause::DisabledByConfig, - "at_checkpoint object reads are not enabled on this instance", + "at_checkpoint and max_version object reads are not enabled on this instance", )); } Ok(AtCheckpointReads { served_height: served_height?, - client, + versions: RequestCache::new(Arc::new(VersionIndexReads { client })), }) } } impl AtCheckpointReads { - /// The version `object_id` was live at, at the end of `checkpoint`. `None` if it did not - /// exist yet, or had been deleted or wrapped. - async fn live_version_at_checkpoint( + /// The scan of a lookup that needs object version history: a `version` bounded by + /// `at_checkpoint`, a `max_version`, or an `at_checkpoint` alone. Fails if the lookup's + /// `at_checkpoint` is above the served height. + fn scan( + self: &Arc, + object_id: ObjectID, + selector: ObjectSelector, + ) -> Result { + let served_checkpoint = self.served_height.checkpoint; + if let Some(checkpoint) = selector.at_checkpoint() { + AtCheckpointUpperBound::new(served_checkpoint).check(checkpoint)?; + } + let reads = self.clone(); + Ok(match selector { + ObjectSelector::Version { + version, + at_checkpoint: Some(checkpoint), + } => Scan::WrittenBy { + reads, + key: ObjectKey(object_id, version.into()), + checkpoint, + }, + _ => { + let bounds = Bounds::of(&selector, served_checkpoint).ok_or_else(|| { + RpcError::new( + tonic::Code::Internal, + "not an at_checkpoint or max_version read", + ) + })?; + Scan::Bounded { + reads, + object_id, + bounds, + } + } + }) + } + + /// The version and status `object_id` had at the end of `checkpoint`. The first call for an + /// `(object_id, checkpoint)` reads it in a task the cache owns, so the read returns its permit + /// whether or not its caller is polled; later calls share that read. + async fn version_at_checkpoint( &self, object_id: ObjectID, checkpoint: u64, - ) -> Result, RpcError> { - Ok( - match self - .client - .get_object_version_at_checkpoint(object_id, checkpoint) - .await? - { - Some((version, ObjectStatus::Live)) => Some(version), - Some((_, ObjectStatus::Deleted | ObjectStatus::Wrapped)) | None => None, - }, - ) + ) -> Result { + let key = (object_id, checkpoint); + let mut reservation = self.versions.reserve(&[key]); + let unread = if reservation.is_unread(&key) { + vec![key] + } else { + Vec::new() + }; + let _read_end = self.versions.read(reservation.take_unread(&unread)); + reservation.value(&key).await } } -/// The error for an `at_checkpoint` above the served height. The response does not say which -/// checkpoint it was read at, so answering from a partially indexed table could hand the caller -/// a wrong answer to persist; fail closed instead. -fn not_yet_indexed(checkpoint: u64, served_height: ServedHeight) -> RpcError { - sui_rpc_api::checkpoint_not_yet_indexed_error(checkpoint, served_height.checkpoint) +/// Reads of `object_versions_by_checkpoint` through a request's gated client: one scan per +/// `(object_id, checkpoint)`, because BigTable cannot return the newest row of several ranges in +/// one `ReadRows` (`rows_limit` covers the whole request). +struct VersionIndexReads { + client: BigTableClient, } -/// The error for a version that `object_versions_by_checkpoint` names as live but that has no -/// live `objects` row: the index and storage diverged, so the object's absence is not an answer. -fn missing_indexed_row(key: ObjectKey) -> RpcError { - RpcError::new( - tonic::Code::Internal, - format!("object_versions_by_checkpoint names {key:?} as live, but objects has no live row"), - ) +#[async_trait::async_trait] +impl CacheFetcher<(ObjectID, u64), (SequenceNumber, ObjectStatus)> for VersionIndexReads { + async fn fetch( + &self, + keys: Vec<(ObjectID, u64)>, + ) -> Result< + BoxStream<'static, Result<((ObjectID, u64), (SequenceNumber, ObjectStatus)), RpcError>>, + RpcError, + > { + let client = self.client.clone(); + Ok(stream::iter(keys) + .then(move |(object_id, checkpoint)| { + let client = client.clone(); + async move { + let version = client + .get_object_version_at_checkpoint(object_id, checkpoint) + .await?; + Ok::<_, RpcError>(version.map(|version| ((object_id, checkpoint), version))) + } + }) + .try_filter_map(|row| future::ready(Ok(row))) + .boxed()) + } } #[cfg(test)] @@ -564,7 +820,7 @@ mod tests { use std::net::SocketAddr; use std::time::Duration; - use sui_kvstore::WatermarkV1; + use mysten_common::ZipDebugEqIteratorExt; use sui_kvstore::tables::object_versions_by_checkpoint; use sui_kvstore::tables::objects; use sui_kvstore::testing::MockBigtableServer; @@ -580,6 +836,7 @@ mod tests { use crate::StageConfig; use crate::StagesConfig; use crate::service_info_watermark_pipelines; + use crate::tests::seed_watermarks; /// A kv-rpc server over the mock BigTable at `addr`, with every watermark it serves at /// checkpoint 10 and its service info loaded. @@ -587,13 +844,24 @@ mod tests { addr: SocketAddr, stages: StagesConfig, enable_object_at_checkpoint: bool, + ) -> KvRpcServer { + start_kv_rpc_at_heights(addr, stages, enable_object_at_checkpoint, |_| 10).await + } + + /// [`start_kv_rpc`], with the watermark of each pipeline it serves at `height(pipeline)`. + async fn start_kv_rpc_at_heights( + addr: SocketAddr, + stages: StagesConfig, + enable_object_at_checkpoint: bool, + height: impl Fn(&str) -> u64, ) -> KvRpcServer { let request_bigtable_concurrency = KvRpcConfig::default().request_bigtable_concurrency(); - start_kv_rpc_with_request_concurrency( + start_kv_rpc_with( addr, stages, enable_object_at_checkpoint, request_bigtable_concurrency, + height, ) .await } @@ -605,31 +873,35 @@ mod tests { stages: StagesConfig, enable_object_at_checkpoint: bool, request_bigtable_concurrency: usize, + ) -> KvRpcServer { + start_kv_rpc_with( + addr, + stages, + enable_object_at_checkpoint, + request_bigtable_concurrency, + |_| 10, + ) + .await + } + + /// A kv-rpc server over the mock BigTable at `addr`, with each request limited to + /// `request_bigtable_concurrency` BigTable reads at once, the watermark of each pipeline it + /// serves at `height(pipeline)`, and its service info loaded. + async fn start_kv_rpc_with( + addr: SocketAddr, + stages: StagesConfig, + enable_object_at_checkpoint: bool, + request_bigtable_concurrency: usize, + height: impl Fn(&str) -> u64, ) -> KvRpcServer { let mut client = sui_kvstore::BigTableClient::new_local(addr.to_string(), "test".into()) .await .expect("connect to mock BigTable"); - for pipeline in service_info_watermark_pipelines( + let pipelines = service_info_watermark_pipelines( LedgerHistoryConfig::default().bitmap_schema(), enable_object_at_checkpoint, - ) { - client - .create_pipeline_watermark_if_absent( - pipeline, - &WatermarkV1 { - epoch_hi_inclusive: 0, - checkpoint_hi_inclusive: Some(10), - tx_hi: 0, - timestamp_ms_hi_inclusive: 10_000, - reader_lo: 0, - pruner_hi: 0, - pruner_timestamp_ms: 0, - bucket_start_cp: None, - }, - ) - .await - .expect("seed watermark"); - } + ); + seed_watermarks(&mut client, &pipelines, height).await; let config = KvRpcConfig::default(); let kv_rpc = KvRpcServer::new_local_with_config( addr.to_string(), @@ -948,6 +1220,398 @@ mod tests { mock_server.abort(); } + /// Write `id`'s history, `(checkpoint, version, status)` for each change in order, to both + /// the `objects` table (a live row or a tombstone) and the `object_versions_by_checkpoint` + /// index. + async fn insert_history( + mock: &MockBigtableServer, + id: ObjectID, + history: &[(u64, u64, ObjectStatus)], + ) { + for &(checkpoint, version, status) in history { + let version = SequenceNumber::from_u64(version); + let cells = match status { + ObjectStatus::Live => objects::encode(&Object::with_id_owner_version_for_testing( + id, + version, + Owner::AddressOwner(SuiAddress::ZERO), + )) + .unwrap() + .to_vec(), + removed => objects::encode_tombstone(removed, &TransactionDigest::random()) + .unwrap() + .to_vec(), + }; + mock.insert_row( + objects::NAME, + objects::encode_key(&ObjectKey(id, version)), + cells, + ) + .await; + mock.insert_row( + object_versions_by_checkpoint::NAME, + object_versions_by_checkpoint::encode_key(&id, checkpoint), + object_versions_by_checkpoint::encode(version, status), + ) + .await; + } + } + + /// A `GetObjectRequest` for `id` with the given selector fields. + fn selector_request( + id: ObjectID, + version: Option, + max_version: Option, + at_checkpoint: Option, + ) -> GetObjectRequest { + let mut req = GetObjectRequest::default(); + req.object_id = Some(id.to_canonical_string(true)); + req.version = version; + req.max_version = max_version; + req.at_checkpoint = at_checkpoint; + req + } + + /// The version a `GetObject` call returned, or its error code. + fn single_outcome(result: Result) -> Result { + match result { + Ok(response) => Ok(response.object.unwrap().version.unwrap()), + Err(err) => Err(tonic::Status::from(err).code()), + } + } + + /// The version a `BatchGetObjects` item returned, or its error code. + fn batch_outcome(item: &GetObjectResult) -> Result { + match &item.result { + Some(get_object_result::Result::Object(object)) => Ok(object.version.unwrap()), + Some(get_object_result::Result::Error(status)) => Err(tonic::Code::from(status.code)), + other => panic!("unexpected batch result {other:?}"), + } + } + + /// `max_version` reads the newest version at or below it, and is `NotFound` from a deletion + /// or wrap until the object is unwrapped or re-created. `at_checkpoint` bounds a `version` + /// read to a version written by the end of the checkpoint, and fails a `max_version` read + /// whose selected version was written after the checkpoint, as Postgres does. `GetObject` and + /// `BatchGetObjects` agree on every read, with and without object contents. + #[tokio::test] + async fn test_max_version_and_checkpoint_bounds_follow_the_history() { + let mock = MockBigtableServer::new(); + let (addr, mock_server) = mock.start().await.expect("start mock BigTable"); + let kv_rpc = start_kv_rpc(addr, StagesConfig::default(), true).await; + + // Created at version 2 in checkpoint 1, mutated at 4 in checkpoint 3, wrapped at 6 in + // checkpoint 5, unwrapped at 8 in checkpoint 7, and deleted at 9 in checkpoint 10. + let id = ObjectID::random(); + let history = [ + (1, 2, ObjectStatus::Live), + (3, 4, ObjectStatus::Live), + (5, 6, ObjectStatus::Wrapped), + (7, 8, ObjectStatus::Live), + (10, 9, ObjectStatus::Deleted), + ]; + insert_history(&mock, id, &history).await; + + let live = |version: u64| { + history + .iter() + .any(|&(_, changed, status)| changed == version && status == ObjectStatus::Live) + }; + let written_by = |version: u64, checkpoint: u64| { + history + .iter() + .any(|&(changed_at, changed, _)| changed == version && changed_at <= checkpoint) + }; + // The newest version at or below `version` written by the served height (10), if it was + // written by `at_checkpoint` when that is set and the object is live at it. + let newest_at_or_below = |version: u64, at_checkpoint: Option| { + history + .iter() + .rev() + .find(|&&(changed_at, changed, _)| changed <= version && changed_at <= 10) + .filter(|&&(changed_at, _, status)| { + status == ObjectStatus::Live && at_checkpoint.is_none_or(|cp| changed_at <= cp) + }) + .map(|&(_, changed, _)| changed) + }; + + // Every version the history spans and one past it, each read exactly and as a + // `max_version`, unbounded and bounded by every checkpoint up to the served height. + let mut cases = Vec::new(); + for version in 0..=10 { + for at_checkpoint in std::iter::once(None).chain((0..=10).map(Some)) { + let exact = live(version) + .then_some(version) + .filter(|&found| at_checkpoint.is_none_or(|cp| written_by(found, cp))); + cases.push(( + selector_request(id, Some(version), None, at_checkpoint), + exact.ok_or(tonic::Code::NotFound), + )); + cases.push(( + selector_request(id, None, Some(version), at_checkpoint), + newest_at_or_below(version, at_checkpoint).ok_or(tonic::Code::NotFound), + )); + } + } + + for paths in [ + &["object_id", "version"][..], + &["object_id", "version", "digest"], + ] { + for (req, expected) in &cases { + let mut req = req.clone(); + req.read_mask = Some(mask(paths)); + let request = kv_rpc.admitted_request(req.clone()); + let outcome = single_outcome(get_object(&kv_rpc, request).await); + assert_eq!(&outcome, expected, "GetObject {req:?}"); + } + + let mut batch = BatchGetObjectsRequest::default(); + batch.requests = cases.iter().map(|(req, _)| req.clone()).collect(); + batch.read_mask = Some(mask(paths)); + let items = batch_get_objects(&kv_rpc, kv_rpc.admitted_request(batch)) + .await + .unwrap() + .objects; + for (item, (req, expected)) in items.iter().zip_debug_eq(&cases) { + assert_eq!( + &batch_outcome(item), + expected, + "BatchGetObjects {req:?} {paths:?}" + ); + } + } + + mock_server.abort(); + } + + /// With version 5 written in checkpoint 10 and version 8 in checkpoint 20, `max_version` 8 at + /// checkpoint 15 selects version 8 once the served height reaches checkpoint 20, and then + /// fails because version 8 was written after checkpoint 15. Below that served height, version + /// 8 does not count even with its row already in the tables, and version 5 answers. + #[tokio::test] + async fn test_max_version_at_checkpoint_counts_versions_up_to_the_served_height() { + for served in [15, 19, 20, 25] { + let mock = MockBigtableServer::new(); + let (addr, mock_server) = mock.start().await.expect("start mock BigTable"); + let kv_rpc = + start_kv_rpc_at_heights(addr, StagesConfig::default(), true, |_| served).await; + let id = ObjectID::random(); + insert_history( + &mock, + id, + &[(10, 5, ObjectStatus::Live), (20, 8, ObjectStatus::Live)], + ) + .await; + + let mut cases = vec![ + ( + selector_request(id, None, Some(8), Some(15)), + if served < 20 { + Ok(5) + } else { + Err(tonic::Code::NotFound) + }, + ), + (selector_request(id, None, Some(7), Some(15)), Ok(5)), + ( + selector_request(id, None, Some(8), Some(9)), + Err(tonic::Code::NotFound), + ), + ]; + if served >= 20 { + cases.push((selector_request(id, None, Some(8), Some(20)), Ok(8))); + cases.push((selector_request(id, None, Some(8), Some(served)), Ok(8))); + } + for (req, expected) in &cases { + let outcome = + single_outcome(get_object(&kv_rpc, kv_rpc.admitted_request(req.clone())).await); + assert_eq!( + &outcome, expected, + "GetObject, served height {served}: {req:?}" + ); + } + let mut batch = BatchGetObjectsRequest::default(); + batch.requests = cases.iter().map(|(req, _)| req.clone()).collect(); + let items = batch_get_objects(&kv_rpc, kv_rpc.admitted_request(batch)) + .await + .unwrap() + .objects; + for (item, (req, expected)) in items.iter().zip_debug_eq(&cases) { + assert_eq!( + &batch_outcome(item), + expected, + "BatchGetObjects, served height {served}: {req:?}" + ); + } + mock_server.abort(); + } + } + + /// A `max_version` read without `at_checkpoint` is bounded by the served height (10 here): a + /// version written above it never answers, even when its row is already in the tables. + #[tokio::test] + async fn test_max_version_without_checkpoint_is_bounded_by_the_served_height() { + let mock = MockBigtableServer::new(); + let (addr, mock_server) = mock.start().await.expect("start mock BigTable"); + let kv_rpc = start_kv_rpc(addr, StagesConfig::default(), true).await; + + // `mutated` is live at version 3 from checkpoint 5 and at version 5 from checkpoint 12; + // `created` is created at version 2 in checkpoint 12. + let mutated = ObjectID::random(); + insert_history( + &mock, + mutated, + &[(5, 3, ObjectStatus::Live), (12, 5, ObjectStatus::Live)], + ) + .await; + let created = ObjectID::random(); + insert_history(&mock, created, &[(12, 2, ObjectStatus::Live)]).await; + let cases = [ + (selector_request(mutated, None, Some(8), None), Ok(3)), + ( + selector_request(created, None, Some(8), None), + Err(tonic::Code::NotFound), + ), + ]; + + for paths in [ + &["object_id", "version"][..], + &["object_id", "version", "digest"], + ] { + for (req, expected) in &cases { + let mut req = req.clone(); + req.read_mask = Some(mask(paths)); + let request = kv_rpc.admitted_request(req.clone()); + let outcome = single_outcome(get_object(&kv_rpc, request).await); + assert_eq!(&outcome, expected, "GetObject {req:?}"); + } + + let mut batch = BatchGetObjectsRequest::default(); + batch.requests = cases.iter().map(|(req, _)| req.clone()).collect(); + batch.read_mask = Some(mask(paths)); + let items = batch_get_objects(&kv_rpc, kv_rpc.admitted_request(batch)) + .await + .unwrap() + .objects; + for (item, (req, expected)) in items.iter().zip_debug_eq(&cases) { + assert_eq!( + &batch_outcome(item), + expected, + "BatchGetObjects {req:?} {paths:?}" + ); + } + } + + mock_server.abort(); + } + + /// `max_version` reads, and `version` reads bounded by `at_checkpoint`, are `Unimplemented` + /// with `NOT_SERVED_HERE` / `disabled_by_config` unless `at_checkpoint` and `max_version` + /// reads are enabled, even when `at_checkpoint` is above the served height. A batch with an + /// item the instance cannot serve fails as a whole. + #[tokio::test] + async fn test_max_version_and_checkpoint_bounds_need_the_flag() { + use sui_rpc::proto::google::rpc::ErrorInfo; + use sui_rpc::proto::sui::rpc::v2::ErrorReason; + + /// The code of a failed request, and the `cause` of its `NOT_SERVED_HERE` refusal. + fn refusal(error: RpcError) -> (tonic::Code, Option) { + let status = error.into_status_proto(); + let cause = status + .details + .iter() + .filter_map(|detail| detail.to_msg::().ok()) + .find(|info| { + info.domain == ErrorReason::DOMAIN + && info.reason == ErrorReason::NotServedHere.as_str_name() + }) + .and_then(|info| info.metadata.get("cause").cloned()); + (tonic::Code::from(status.code), cause) + } + + let mock = MockBigtableServer::new(); + let (addr, mock_server) = mock.start().await.expect("start mock BigTable"); + let id = ObjectID::random(); + insert_history(&mock, id, &[(2, 2, ObjectStatus::Live)]).await; + + let disabled = Err(( + tonic::Code::Unimplemented, + Some("disabled_by_config".to_owned()), + )); + for enabled in [false, true] { + let kv_rpc = start_kv_rpc(addr, StagesConfig::default(), enabled).await; + // The served height is 10. + for (version, max_version, at_checkpoint, when_enabled) in [ + (Some(2), None, Some(5), Ok(2)), + (None, Some(2), None, Ok(2)), + (None, Some(2), Some(5), Ok(2)), + ( + Some(2), + None, + Some(11), + Err((tonic::Code::OutOfRange, None)), + ), + ] { + let expected = if enabled { + when_enabled + } else { + disabled.clone() + }; + let context = + format!("enabled {enabled}: {version:?} {max_version:?} {at_checkpoint:?}"); + let req = selector_request(id, version, max_version, at_checkpoint); + let request = kv_rpc.admitted_request(req.clone()); + let outcome = get_object(&kv_rpc, request) + .await + .map(|response| response.object.unwrap().version.unwrap()) + .map_err(refusal); + assert_eq!(outcome, expected, "GetObject {context}"); + + let mut batch = BatchGetObjectsRequest::default(); + batch.requests = vec![selector_request(id, None, None, None), req]; + let outcome = match batch_get_objects(&kv_rpc, kv_rpc.admitted_request(batch)).await + { + Ok(response) => { + batch_outcome(&response.objects[1]).map_err(|code| (code, None)) + } + Err(err) => Err(refusal(err)), + }; + assert_eq!(outcome, expected, "BatchGetObjects {context}"); + } + } + + mock_server.abort(); + } + + /// With `at_checkpoint` and `max_version` reads enabled, the watermarks of both the versions + /// index and the tombstones pipeline bound the served height. + #[tokio::test] + async fn test_object_indexes_bound_the_served_height() { + for lagging in [ + sui_kvstore::OBJECT_VERSIONS_BY_CHECKPOINT_PIPELINE, + sui_kvstore::OBJECT_TOMBSTONES_PIPELINE, + ] { + for (enabled, served) in [(false, 10), (true, 7)] { + let mock = MockBigtableServer::new(); + let (addr, mock_server) = mock.start().await.expect("start mock BigTable"); + let kv_rpc = + start_kv_rpc_at_heights(addr, StagesConfig::default(), enabled, |pipeline| { + if pipeline == lagging { 7 } else { 10 } + }) + .await; + assert_eq!( + ServedHeight::of(&kv_rpc.admitted_request(())) + .unwrap() + .checkpoint, + served, + "{lagging} lagging, enabled {enabled}", + ); + mock_server.abort(); + } + } + } + /// On an instance without `at_checkpoint` reads, a batch of exact versions goes out as /// `objects` multi-gets of at most the stage's `max-seeks-per-read` keys, and every item is /// answered, whether its version is stored or not. @@ -1110,8 +1774,10 @@ mod tests { } /// Every request of a batch gets its own lookup's answer, in request order, including a - /// request that repeats an earlier one, and each `objects` row is read once: an exact version - /// and an `at_checkpoint` lookup that resolves to it share one read. + /// request that repeats an earlier one. Each `objects` row is read once: an exact version and + /// the lookups at a checkpoint that resolve to it share one read. Each `(object_id, + /// checkpoint)` of the version index is read once too: the three lookups at checkpoint 7 share + /// one scan. #[tokio::test] async fn test_batch_answers_each_request_and_reads_each_row_once() { let mock = MockBigtableServer::new(); @@ -1144,22 +1810,23 @@ mod tests { ) .await; - let request = |object: &Object, version: Option, at_checkpoint: Option| { - let mut req = GetObjectRequest::default(); - req.object_id = Some(object.id().to_canonical_string(true)); - req.version = version; - req.at_checkpoint = at_checkpoint; - req + let request = |object: &Object, + version: Option, + max_version: Option, + at_checkpoint: Option| { + selector_request(object.id(), version, max_version, at_checkpoint) }; let mut batch = BatchGetObjectsRequest::default(); batch.requests = vec![ - request(&pinned, Some(3), None), - request(&latest, None, None), - request(&pinned, None, Some(7)), - request(&pinned, Some(3), None), - request(&pinned, Some(4), None), - request(&latest, None, None), - request(&pinned, None, Some(11)), + request(&pinned, Some(3), None, None), + request(&latest, None, None, None), + request(&pinned, None, None, Some(7)), + request(&pinned, Some(3), None, None), + request(&pinned, Some(4), None, None), + request(&latest, None, None, None), + request(&pinned, None, None, Some(11)), + request(&pinned, Some(3), None, Some(7)), + request(&pinned, None, Some(3), Some(7)), ]; batch.read_mask = Some(mask(&["object_id", "version", "digest"])); @@ -1194,19 +1861,26 @@ mod tests { Err(tonic::Code::NotFound as i32), found(&latest), Err(tonic::Code::OutOfRange as i32), + found(&pinned), + found(&pinned), ], ); + let calls = mock.read_rows_calls().await; let pinned_key = objects::encode_key(&ObjectKey(pinned.id(), pinned.version())); - let pinned_reads = mock - .read_rows_calls() - .await - .into_iter() + let pinned_reads = calls + .iter() .filter(|call| call.table == objects::NAME) - .flat_map(|call| call.row_keys) - .filter(|key| *key == pinned_key) + .flat_map(|call| &call.row_keys) + .filter(|key| **key == pinned_key) + .count(); + assert_eq!(pinned_reads, 1, "four lookups share one read of the row"); + // One scan at checkpoint 7, and one at the served height for the `max_version` lookup. + let index_scans = calls + .iter() + .filter(|call| call.table == object_versions_by_checkpoint::NAME) .count(); - assert_eq!(pinned_reads, 1, "three requests share one read of the row"); + assert_eq!(index_scans, 2, "{calls:?}"); mock_server.abort(); } diff --git a/crates/sui-rpc-api/src/error.rs b/crates/sui-rpc-api/src/error.rs index f04e05c395b1..dbbaab7a7959 100644 --- a/crates/sui-rpc-api/src/error.rs +++ b/crates/sui-rpc-api/src/error.rs @@ -354,6 +354,7 @@ impl ErrorDetails { pub struct ObjectNotFoundError { object_id: sui_sdk_types::Address, version: Option, + max_version: Option, checkpoint: Option, } @@ -362,6 +363,7 @@ impl ObjectNotFoundError { Self { object_id, version: None, + max_version: None, checkpoint: None, } } @@ -371,22 +373,31 @@ impl ObjectNotFoundError { version: sui_sdk_types::Version, ) -> Self { Self { - object_id, version: Some(version), - checkpoint: None, + ..Self::new(object_id) } } - /// The object had no live state at the end of `checkpoint`: it did not exist yet, or it had - /// been deleted or wrapped. - pub fn new_at_checkpoint( + /// The object had no version at or below `max_version`, or was deleted or wrapped at the + /// newest one. + pub fn new_with_max_version( object_id: sui_sdk_types::Address, - checkpoint: sui_sdk_types::CheckpointSequenceNumber, + max_version: sui_sdk_types::Version, ) -> Self { Self { - object_id, - version: None, + max_version: Some(max_version), + ..Self::new(object_id) + } + } + + /// Bound the read by `checkpoint`: the object had no live state at the end of `checkpoint`, + /// or the exact version was not found or was written after `checkpoint`, or the newest + /// version at or below `max_version` was written after `checkpoint`, deleted or wrapped the + /// object, or does not exist. + pub fn at_checkpoint(self, checkpoint: sui_sdk_types::CheckpointSequenceNumber) -> Self { + Self { checkpoint: Some(checkpoint), + ..self } } } @@ -399,6 +410,10 @@ impl std::fmt::Display for ObjectNotFoundError { write!(f, " with version {version}")?; } + if let Some(max_version) = self.max_version { + write!(f, " with version at most {max_version}")?; + } + if let Some(checkpoint) = self.checkpoint { write!(f, " at checkpoint {checkpoint}")?; } diff --git a/crates/sui-rpc-api/src/grpc/v2/ledger_service/get_object.rs b/crates/sui-rpc-api/src/grpc/v2/ledger_service/get_object.rs index 341422092801..baaabc9a5943 100644 --- a/crates/sui-rpc-api/src/grpc/v2/ledger_service/get_object.rs +++ b/crates/sui-rpc-api/src/grpc/v2/ledger_service/get_object.rs @@ -6,6 +6,7 @@ use crate::RpcError; use crate::RpcService; use crate::error::ObjectNotFoundError; use crate::grpc::v2::render::RenderContext; +use crate::ledger_history::query_options::below_serving_floor; use crate::reader::AtCheckpointUpperBound; use mysten_common::ZipDebugEqIteratorExt; use prost_types::FieldMask; @@ -19,6 +20,9 @@ use sui_rpc::proto::sui::rpc::v2::GetObjectResponse; use sui_rpc::proto::sui::rpc::v2::GetObjectResult; use sui_rpc::proto::sui::rpc::v2::Object; use sui_sdk_types::Address; +use sui_types::base_types::ObjectID; +use sui_types::base_types::SequenceNumber; +use sui_types::object::Object as StoredObject; pub const MAX_BATCH_REQUESTS: usize = 1000; pub const READ_MASK_DEFAULT: &str = crate::read_mask_defaults::OBJECT; @@ -26,20 +30,83 @@ pub const READ_MASK_DEFAULT: &str = crate::read_mask_defaults::OBJECT; /// Which state of an object a `GetObjectRequest` reads. #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] pub enum ObjectSelector { - /// The latest live version (neither `version` nor `at_checkpoint` set). + /// The latest live version (none of `version`, `max_version` and `at_checkpoint` set). Latest, - /// Exactly this version. - Version(u64), - /// The object's state at the end of this checkpoint. + /// Exactly `version`. With `at_checkpoint`, only if that version was written at or before + /// the checkpoint. A fullnode whose object lower bound is above 0 (it pruned object versions + /// or was restored from a snapshot) answers a version it does not hold with `OUT_OF_RANGE` / + /// `BELOW_EARLIEST_AVAILABLE` rather than `NOT_FOUND`, unless the version is above the + /// object's latest live version or `at_checkpoint` decides the answer without it (see + /// `resolve_missing_versions` in this module). + Version { + version: u64, + at_checkpoint: Option, + }, + /// The newest version at or below `max_version`, unless the object was deleted or wrapped at + /// that version. With `at_checkpoint`, versions count up to the height the server answers + /// `at_checkpoint` reads at, and the read fails if the selected version was written after the + /// checkpoint, so it agrees with a `version` read of the selected version at that checkpoint. + /// Without it, a fullnode reads its live state, counting every version it holds, and kv-rpc + /// reads at its served height, answering as if `at_checkpoint` were set to it, since versions + /// above it may be in its tables before their deletions and wraps are. A fullnode whose + /// object lower bound is above 0 answers a read that finds no live version to select with + /// `OUT_OF_RANGE` / `BELOW_EARLIEST_AVAILABLE` rather than `NOT_FOUND`, since the versions it + /// would select from may have been pruned. + MaxVersion { + max_version: u64, + at_checkpoint: Option, + }, + /// The object's state at the end of this checkpoint (`at_checkpoint` alone). AtCheckpoint(u64), } +impl ObjectSelector { + /// The request's `at_checkpoint`: the checkpoint an [`Self::AtCheckpoint`] read is pinned + /// to, or the checkpoint that bounds a [`Self::Version`] or [`Self::MaxVersion`] read to + /// versions written at or before it. Either way, the read fails if the checkpoint is outside + /// the range the server can answer for. + pub fn at_checkpoint(&self) -> Option { + match *self { + Self::Latest => None, + Self::Version { at_checkpoint, .. } | Self::MaxVersion { at_checkpoint, .. } => { + at_checkpoint + } + Self::AtCheckpoint(checkpoint) => Some(checkpoint), + } + } + + /// Whether the read needs versions that later transactions replaced, which a node without + /// object version history no longer has: every read with `at_checkpoint`, and every + /// `max_version` read. + pub fn needs_object_version_history(&self) -> bool { + matches!(self, Self::MaxVersion { .. }) || self.at_checkpoint().is_some() + } + + /// The `NotFound` error for `object_id` when this selector finds no object. + pub fn not_found(&self, object_id: Address) -> ObjectNotFoundError { + let error = match *self { + Self::Latest | Self::AtCheckpoint(_) => ObjectNotFoundError::new(object_id), + Self::Version { version, .. } => { + ObjectNotFoundError::new_with_version(object_id, version) + } + Self::MaxVersion { max_version, .. } => { + ObjectNotFoundError::new_with_max_version(object_id, max_version) + } + }; + match self.at_checkpoint() { + Some(checkpoint) => error.at_checkpoint(checkpoint), + None => error, + } + } +} + type ValidationResult = Result<(Vec<(Address, ObjectSelector)>, FieldMaskTree), RpcError>; -/// Validate `(object_id, version, at_checkpoint)` for each request, and the read mask shared by -/// all of them. A request that sets both `version` and `at_checkpoint` is rejected. +/// Validate each request's `object_id` and selector fields, and the read mask shared by all of +/// them; each request's own `read_mask` is ignored. A request that sets both `version` and +/// `max_version` is rejected. `at_checkpoint` combines with either. pub fn validate_get_object_requests( - requests: Vec<(Option, Option, Option)>, + requests: &[GetObjectRequest], read_mask: Option, ) -> ValidationResult { let read_mask = { @@ -52,10 +119,11 @@ pub fn validate_get_object_requests( FieldMaskTree::from(read_mask) }; let requests = requests - .into_iter() + .iter() .enumerate() - .map(|(idx, (object_id, version, at_checkpoint))| { - let object_id = object_id + .map(|(idx, request)| { + let object_id = request + .object_id .as_ref() .ok_or_else(|| { FieldViolation::new("object_id") @@ -69,17 +137,24 @@ pub fn validate_get_object_requests( .with_reason(ErrorReason::FieldInvalid) .nested_at("requests", idx) })?; - let selector = match (version, at_checkpoint) { - (None, None) => ObjectSelector::Latest, - (Some(version), None) => ObjectSelector::Version(version), - (None, Some(checkpoint)) => ObjectSelector::AtCheckpoint(checkpoint), - (Some(_), Some(_)) => { - return Err(FieldViolation::new("at_checkpoint") - .with_description("version and at_checkpoint are mutually exclusive") + let selector = match (request.version, request.max_version, request.at_checkpoint) { + (Some(_), Some(_), _) => { + return Err(FieldViolation::new("max_version") + .with_description("version and max_version are mutually exclusive") .with_reason(ErrorReason::FieldInvalid) .nested_at("requests", idx) .into()); } + (None, None, None) => ObjectSelector::Latest, + (None, None, Some(checkpoint)) => ObjectSelector::AtCheckpoint(checkpoint), + (Some(version), None, at_checkpoint) => ObjectSelector::Version { + version, + at_checkpoint, + }, + (None, Some(max_version), at_checkpoint) => ObjectSelector::MaxVersion { + max_version, + at_checkpoint, + }, }; Ok((object_id, selector)) }) @@ -90,30 +165,26 @@ pub fn validate_get_object_requests( #[tracing::instrument(skip(service))] pub fn get_object( service: &RpcService, - GetObjectRequest { - object_id, - version, - read_mask, - at_checkpoint, - .. - }: GetObjectRequest, + mut request: GetObjectRequest, ) -> Result { + let read_mask = request.read_mask.take(); let (requests, read_mask) = - validate_get_object_requests(vec![(object_id, version, at_checkpoint)], read_mask)?; + validate_get_object_requests(std::slice::from_ref(&request), read_mask)?; let upper_bound = load_at_checkpoint_upper_bound(service, &requests)?; let (object_id, selector) = requests[0]; let render_context = RenderContext::empty(service.reader.inner()); - let mut results = [get_object_impl( + let read = get_object_impl( service, object_id, selector, upper_bound.as_ref(), &read_mask, &render_context, - )]; - apply_at_checkpoint_lower_bound(service, &requests, &mut results)?; - let [result] = results; - result.map(GetObjectResponse::new) + ); + let mut results = resolve_missing_versions(service, &requests, vec![read])?; + apply_at_checkpoint_lower_bound(service, &requests, upper_bound.as_ref(), &mut results)?; + // One request, so one result. + results.swap_remove(0).map(GetObjectResponse::new) } #[tracing::instrument(skip(service))] @@ -132,15 +203,11 @@ pub fn batch_get_objects( )); } - let requests = requests - .into_iter() - .map(|req| (req.object_id, req.version, req.at_checkpoint)) - .collect(); - let (requests, read_mask) = validate_get_object_requests(requests, read_mask)?; + let (requests, read_mask) = validate_get_object_requests(&requests, read_mask)?; let upper_bound = load_at_checkpoint_upper_bound(service, &requests)?; let render_context = RenderContext::empty(service.reader.inner()); - let mut results: Vec<_> = requests + let reads: Vec<_> = requests .iter() .map(|&(object_id, selector)| { get_object_impl( @@ -153,7 +220,8 @@ pub fn batch_get_objects( ) }) .collect(); - apply_at_checkpoint_lower_bound(service, &requests, &mut results)?; + let mut results = resolve_missing_versions(service, &requests, reads)?; + apply_at_checkpoint_lower_bound(service, &requests, upper_bound.as_ref(), &mut results)?; let objects = results .into_iter() .map(|result| match result { @@ -164,41 +232,133 @@ pub fn batch_get_objects( Ok(BatchGetObjectsResponse::new(objects)) } -fn has_at_checkpoint(requests: &[(Address, ObjectSelector)]) -> bool { - requests +/// Before the reads, once per request: refuse the whole request if some item needs object +/// version history and this node keeps none, and, if some item sets `at_checkpoint`, load the +/// upper bound the reads at a checkpoint check (`StateReader::at_checkpoint_upper_bound`), whose +/// failure fails the whole request. Other reads still work on nodes without rpc indexes or +/// object version history. +fn load_at_checkpoint_upper_bound( + service: &RpcService, + requests: &[(Address, ObjectSelector)], +) -> Result, RpcError> { + if requests .iter() - .any(|(_, selector)| matches!(selector, ObjectSelector::AtCheckpoint(_))) + .any(|(_, selector)| selector.needs_object_version_history()) + { + service.reader.require_object_version_history()?; + } + if requests + .iter() + .any(|(_, selector)| selector.at_checkpoint().is_some()) + { + service.reader.at_checkpoint_upper_bound().map(Some) + } else { + Ok(None) + } } -/// Before the reads, once per request and only when some item reads at a checkpoint, so that -/// latest and exact-version reads still work on nodes without rpc indexes or object version -/// history: refuse the whole request if this node keeps no object version history, else load -/// the `at_checkpoint` upper bound. -fn load_at_checkpoint_upper_bound( +/// After the reads: answer every item whose read found a version missing (`Ok(None)` from +/// [`get_object_impl`]), with this node's object lower bound +/// ([`sui_types::storage::RpcStateReader::get_lowest_available_checkpoint_objects`]) and its +/// objects' latest live versions. See [`missing_version_error`]. +/// +/// The lower bound is read at most once per request, after the reads: pruning can raise it while +/// the reads run, and a version pruned meanwhile then fails as pruned rather than as one that +/// never existed. +fn resolve_missing_versions( service: &RpcService, requests: &[(Address, ObjectSelector)], -) -> Result, RpcError> { - if !has_at_checkpoint(requests) { - return Ok(None); + reads: Vec, RpcError>>, +) -> Result>, RpcError> { + let reader = service.reader.inner(); + answer_missing_versions( + requests, + reads, + || Ok(reader.get_lowest_available_checkpoint_objects()?), + |object_id| { + reader + .get_object(&ObjectID::from(object_id)) + .map(|object| object.version()) + }, + ) +} + +/// [`resolve_missing_versions`] with the object lower bound and the objects' latest live +/// versions read through `objects_lower_bound` and `latest_live_version`. `objects_lower_bound` +/// is called only if some read found a version missing. +fn answer_missing_versions( + requests: &[(Address, ObjectSelector)], + reads: Vec, RpcError>>, + objects_lower_bound: impl FnOnce() -> Result, + latest_live_version: impl Fn(Address) -> Option, +) -> Result>, RpcError> { + let objects_lower_bound = if reads.iter().any(|read| matches!(read, Ok(None))) { + objects_lower_bound()? + } else { + 0 + }; + Ok(requests + .iter() + .zip_debug_eq(reads) + .map(|(&(object_id, selector), read)| match read? { + Some(object) => Ok(object), + None => Err(missing_version_error( + object_id, + selector, + objects_lower_bound, + || latest_live_version(object_id), + )), + }) + .collect()) +} + +/// The answer to a read that found the version it needs missing from the object store. +/// +/// - `NOT_FOUND` if `objects_lower_bound` is 0: the node was neither pruned nor restored from a +/// snapshot, so it holds every version ever written, and the missing one never existed. +/// - `NOT_FOUND` for an exact `version` above the object's latest live version +/// (`latest_live_version`): it does not exist yet. +/// - Otherwise `OUT_OF_RANGE` / `BELOW_EARLIEST_AVAILABLE` with `objects_lower_bound` as the +/// lowest available checkpoint, since the version may have been pruned. That includes a +/// `max_version` read that finds no live version at or below `max_version`, and an object with +/// no version left. The object store does not tell a deletion or wrap from a pruned version, +/// so a read of an object deleted or wrapped at or below the version read, with no live +/// version above it, fails the same way. +fn missing_version_error( + object_id: Address, + selector: ObjectSelector, + objects_lower_bound: u64, + latest_live_version: impl FnOnce() -> Option, +) -> RpcError { + let not_yet_written = || match selector { + ObjectSelector::Version { version, .. } => { + latest_live_version().is_some_and(|latest| SequenceNumber::from_u64(version) > latest) + } + _ => false, + }; + if objects_lower_bound == 0 || not_yet_written() { + selector.not_found(object_id).into() + } else { + below_serving_floor(objects_lower_bound) } - service.reader.require_object_version_history()?; - service.reader.at_checkpoint_upper_bound().map(Some) } -/// After the reads: answer as pruned every `at_checkpoint` item below the lowest available -/// checkpoint, replacing whatever its read returned, since that read may have seen pruned data. -/// See `StateReader::at_checkpoint_lower_bound`. +/// After the reads: answer as pruned every item whose `at_checkpoint` is below the lower bound +/// (see `StateReader::at_checkpoint_lower_bound`), replacing whatever its read returned, since +/// that read may have seen pruned data. fn apply_at_checkpoint_lower_bound( service: &RpcService, requests: &[(Address, ObjectSelector)], + upper_bound: Option<&AtCheckpointUpperBound>, results: &mut [Result], ) -> Result<(), RpcError> { - if !has_at_checkpoint(requests) { + // The request loads an upper bound exactly when some item sets `at_checkpoint`. + if upper_bound.is_none() { return Ok(()); } let lower_bound = service.reader.at_checkpoint_lower_bound()?; for (&(_, selector), result) in requests.iter().zip_debug_eq(results.iter_mut()) { - if let ObjectSelector::AtCheckpoint(checkpoint) = selector + if let Some(checkpoint) = selector.at_checkpoint() && let Err(error) = lower_bound.check(checkpoint) { *result = Err(error); @@ -207,8 +367,38 @@ fn apply_at_checkpoint_lower_bound( Ok(()) } -/// Read one object. `upper_bound` is set whenever `selector` is -/// [`ObjectSelector::AtCheckpoint`] (see [`load_at_checkpoint_upper_bound`]). +/// What a read found for the version its selector picks. +#[derive(Debug)] +enum VersionRead { + /// The selected version, live. + Live(StoredObject), + /// The answer is that the object does not exist (`NOT_FOUND`): the selected version was + /// written after the checkpoint the read is pinned to, or deleted or wrapped the object, or + /// the object had no version yet. + NotFound, + /// The object store has no live version where the read needs one. The version may never + /// have existed, may be a deletion or wrap, or may have been pruned; see + /// [`missing_version_error`]. + Missing, +} + +impl VersionRead { + /// The object, or [`Self::NotFound`] if there is none. + fn or_not_found(object: Option) -> Self { + object.map_or(Self::NotFound, Self::Live) + } + + /// The object, or [`Self::Missing`] if there is none. + fn or_missing(object: Option) -> Self { + object.map_or(Self::Missing, Self::Live) + } +} + +/// Read one object. `upper_bound` is set whenever some item of the request sets `at_checkpoint`; +/// the reader checks it before any read at the checkpoint, so a checkpoint above it fails the +/// read whatever the object's state. `Ok(None)` if a `version` or `max_version` read found the +/// version it needs missing (see [`VersionRead::Missing`]); [`resolve_missing_versions`] answers +/// it after the reads. #[tracing::instrument(skip(service, render_context))] fn get_object_impl( service: &RpcService, @@ -217,58 +407,675 @@ fn get_object_impl( upper_bound: Option<&AtCheckpointUpperBound>, read_mask: &FieldMaskTree, render_context: &RenderContext, -) -> Result { - let object = match selector { - ObjectSelector::Latest => service - .reader - .inner() - .get_object(&object_id.into()) - .ok_or_else(|| ObjectNotFoundError::new(object_id))?, - ObjectSelector::Version(version) => get_object_version(service, object_id, version)?, - ObjectSelector::AtCheckpoint(checkpoint) => { - let upper_bound = upper_bound.ok_or_else(|| { - RpcError::new( - tonic::Code::Internal, - "at_checkpoint upper bound was not loaded", - ) - })?; - service - .reader - .get_object_at_checkpoint(object_id.into(), checkpoint, upper_bound)? - .ok_or_else(|| ObjectNotFoundError::new_at_checkpoint(object_id, checkpoint))? +) -> Result, RpcError> { + let reader = &service.reader; + let id = ObjectID::from(object_id); + // A node without object version history serves only each object's latest version. A version + // above it has not been written yet and is `NotFound`, as on any node. Any other version, and + // any version of an object with no live version, is refused (`Unimplemented`, + // `NOT_SERVED_HERE`, cause `no_object_history`) even while it is still stored, so that answer + // does not change as compaction reaches it. + if let ObjectSelector::Version { + version, + at_checkpoint: None, + } = selector + && let Err(refusal) = reader.require_object_version_history() + { + return match reader.inner().get_object(&id) { + Some(object) if object.version().value() == version => Ok(Some( + service.render_object_to_proto(&object, read_mask, render_context), + )), + Some(object) if object.version().value() < version => { + Err(selector.not_found(object_id).into()) + } + _ => Err(refusal), + }; + } + let upper_bound = || { + upper_bound.ok_or_else(|| { + RpcError::new( + tonic::Code::Internal, + "at_checkpoint upper bound was not loaded", + ) + }) + }; + let read = match selector { + ObjectSelector::Latest => VersionRead::or_not_found(reader.inner().get_object(&id)), + ObjectSelector::Version { + version, + at_checkpoint: None, + } => VersionRead::or_missing(reader.inner().get_object_by_key(&id, version.into())), + ObjectSelector::Version { + version, + at_checkpoint: Some(checkpoint), + } => version_at_checkpoint( + version.into(), + reader.get_object_version_at_checkpoint(id, checkpoint, upper_bound()?)?, + |version| reader.inner().get_object_by_key(&id, version), + ), + ObjectSelector::MaxVersion { + max_version, + at_checkpoint: None, + } => VersionRead::or_missing( + reader + .inner() + .get_object_lt_or_eq_version(&id, max_version.into())?, + ), + ObjectSelector::MaxVersion { + max_version, + at_checkpoint: Some(checkpoint), + } => { + let upper_bound = upper_bound()?; + let version_at = + |checkpoint| reader.get_object_version_at_checkpoint(id, checkpoint, upper_bound); + max_version_at_checkpoint( + max_version.into(), + version_at(checkpoint)?, + || version_at(upper_bound.highest_indexed()), + |version| reader.inner().get_object_by_key(&id, version), + |version| Ok(reader.inner().get_object_lt_or_eq_version(&id, version)?), + )? } + ObjectSelector::AtCheckpoint(checkpoint) => VersionRead::or_not_found( + reader.get_object_at_checkpoint(id, checkpoint, upper_bound()?)?, + ), }; - Ok(service.render_object_to_proto(&object, read_mask, render_context)) + match read { + VersionRead::Live(object) => Ok(Some(service.render_object_to_proto( + &object, + read_mask, + render_context, + ))), + VersionRead::NotFound => Err(selector.not_found(object_id).into()), + VersionRead::Missing => Ok(None), + } } -/// Reads `object_id` at exactly `version`. A node without object version history serves only -/// each object's latest version. A version above it has not been written yet and is `NotFound`, -/// as on any node. Any other version, and any version of an object with no live version, is -/// refused (`Unimplemented`, `NOT_SERVED_HERE`, cause `no_object_history`) even while it is still -/// stored, so that answer does not change as compaction reaches it. -fn get_object_version( - service: &RpcService, - object_id: Address, - version: u64, -) -> Result { - let store = service.reader.inner(); - let not_found = - || -> RpcError { ObjectNotFoundError::new_with_version(object_id, version).into() }; - if let Err(refusal) = service.reader.require_object_version_history() { - return match store.get_object(&object_id.into()) { - Some(object) if object.version().value() == version => Ok(object), - Some(object) if object.version().value() < version => Err(not_found()), - _ => Err(refusal), - }; +/// Serve exactly `version` with `at_checkpoint`. `version_at_checkpoint` is the object's version +/// at the end of the checkpoint (see +/// [`crate::reader::StateReader::get_object_version_at_checkpoint`]); a version above it was +/// written after the checkpoint, and so was every version if there is none. +/// +/// The read is refused unless the `at_checkpoint` lower bound accepts the checkpoint, and then +/// the checkpoint's end state is intact. So if `version_at_checkpoint` has no live object, it is +/// a deletion or wrap, or the version the rpc index records for one (see +/// [`newest_version_written_by`]), and the answer is `NOT_FOUND`. A version below it that has no +/// live object may have been pruned. +fn version_at_checkpoint( + version: SequenceNumber, + version_at_checkpoint: Option, + get_object_by_key: impl FnOnce(SequenceNumber) -> Option, +) -> VersionRead { + match version_at_checkpoint { + Some(version_at_checkpoint) if version < version_at_checkpoint => { + VersionRead::or_missing(get_object_by_key(version)) + } + Some(version_at_checkpoint) if version == version_at_checkpoint => { + VersionRead::or_not_found(get_object_by_key(version)) + } + _ => VersionRead::NotFound, + } +} + +/// Serve `max_version` with `at_checkpoint`: select the object's newest version at or below +/// `max_version` written up to the highest indexed checkpoint H, and answer +/// [`VersionRead::NotFound`] if it was written after the checkpoint, or if it deleted or wrapped +/// the object, or if the object had no version as of the checkpoint. `version_at_checkpoint` is +/// the object's version at the end of the checkpoint (see +/// [`crate::reader::StateReader::get_object_version_at_checkpoint`]), and `version_at_height` +/// reads its version at the end of H, needed only when `max_version` is at or above +/// `version_at_checkpoint`. A version above the object's version at the end of a checkpoint was +/// written after it. [`VersionRead::Missing`] if the object store has no live version at or below +/// `max_version` where the selection needs one, unless the object is live at +/// `version_at_checkpoint`: the read is refused unless the `at_checkpoint` lower bound accepts the +/// checkpoint, and then this node holds that version, so a scan from `max_version` at or above it +/// that finds no live version stopped at a deletion or wrap above it, written after the +/// checkpoint. +fn max_version_at_checkpoint( + max_version: SequenceNumber, + version_at_checkpoint: Option, + version_at_height: impl FnOnce() -> Result, RpcError>, + get_object_by_key: impl Fn(SequenceNumber) -> Option, + get_object_lt_or_eq_version: impl FnOnce(SequenceNumber) -> Result, RpcError>, +) -> Result { + let Some(version_at_checkpoint) = version_at_checkpoint else { + // Every version of the object was written after the checkpoint. + return Ok(VersionRead::NotFound); + }; + if max_version < version_at_checkpoint { + // Every version at or below `max_version` was written by the checkpoint. + return Ok(VersionRead::or_missing(get_object_lt_or_eq_version( + max_version, + )?)); + } + let selected = newest_version_written_by( + max_version, + version_at_height()?, + &get_object_by_key, + get_object_lt_or_eq_version, + )?; + // A live version is never between the version index's record of a removal and the removal's + // tombstone (see `newest_version_written_by`), so comparing it with `version_at_checkpoint` + // tells whether it was written after the checkpoint even when that is such a record. + Ok(match selected { + VersionRead::Live(object) if object.version() > version_at_checkpoint => { + VersionRead::NotFound + } + VersionRead::Missing if get_object_by_key(version_at_checkpoint).is_some() => { + VersionRead::NotFound + } + selected => selected, + }) +} + +/// The newest version of an object at or below `max_version` among those written at or before a +/// checkpoint, or [`VersionRead::NotFound`] if the object did not exist yet or that version +/// deleted or wrapped it. `version_at_checkpoint` is the object's version at the end of the +/// checkpoint; every version above it was written after the checkpoint. +/// +/// Below `version_at_checkpoint`, `max_version` selects the newest version at or below it, and +/// the read is [`VersionRead::Missing`] if the object store has no live one. At or above it, the +/// object's state at `version_at_checkpoint` answers: the object if it is live there. If it is +/// not, the object was deleted or wrapped by the checkpoint, but the version index can record +/// that removal below the version of its tombstone in the object store: for a transaction with V1 +/// effects, the index records `TransactionEffectsAPI::lamport_version`, which V1 effects recompute +/// from the modified objects alone, while the tombstone sits at the version the transaction +/// executed at, which also counts its read-only inputs. No version lies between the two, so the +/// newest version at or below `max_version` answers if it is below `version_at_checkpoint` (the +/// removal came after `max_version`), and nothing does if the scan finds a version above it, +/// which was written after the checkpoint. A scan that finds no live version either stopped at +/// the tombstone or found the version before the removal pruned, so the read is +/// [`VersionRead::Missing`]. +fn newest_version_written_by( + max_version: SequenceNumber, + version_at_checkpoint: Option, + get_object_by_key: impl FnOnce(SequenceNumber) -> Option, + get_object_lt_or_eq_version: impl FnOnce(SequenceNumber) -> Result, RpcError>, +) -> Result { + let Some(version_at_checkpoint) = version_at_checkpoint else { + return Ok(VersionRead::NotFound); + }; + if max_version < version_at_checkpoint { + return Ok(VersionRead::or_missing(get_object_lt_or_eq_version( + max_version, + )?)); + } + if let Some(object) = get_object_by_key(version_at_checkpoint) { + return Ok(VersionRead::Live(object)); } - store - .get_object_by_key(&object_id.into(), version.into()) - .ok_or_else(not_found) + Ok(match get_object_lt_or_eq_version(max_version)? { + Some(object) if object.version() < version_at_checkpoint => VersionRead::Live(object), + Some(_) => VersionRead::NotFound, + None => VersionRead::Missing, + }) } #[cfg(test)] mod tests { + use std::collections::BTreeMap; + + use sui_types::base_types::ObjectDigest; + use sui_types::base_types::ObjectID; + use sui_types::base_types::SequenceNumber; + use sui_types::base_types::SuiAddress; + use sui_types::digests::TransactionDigest; + use sui_types::effects::TransactionEffects; + use sui_types::effects::TransactionEffectsAPI; + use sui_types::execution_status::ExecutionStatus; + use sui_types::gas::GasCostSummary; + use sui_types::object::Object as StoredObject; + use sui_types::object::Owner; + + use sui_rpc::proto::sui::rpc::v2::Object; + use sui_sdk_types::Address; + + use super::ObjectSelector; + use super::VersionRead; + use super::answer_missing_versions; + use super::max_version_at_checkpoint; + use super::version_at_checkpoint; + use crate::RpcError; + use crate::ledger_history::query_options::assert_below_serving_floor_error; + + /// V1 effects of a transaction that deletes or wraps `object`, modified at + /// `object_modified_at`, paying with `gas` modified at `gas_modified_at`, and executed at + /// `executed_at`, which also counts read-only inputs the effects do not list. + fn v1_removal( + object: ObjectID, + object_modified_at: u64, + gas: ObjectID, + gas_modified_at: u64, + executed_at: u64, + wrap: bool, + ) -> TransactionEffects { + let executed_at = SequenceNumber::from_u64(executed_at); + let removed = if wrap { + (object, executed_at, ObjectDigest::OBJECT_DIGEST_WRAPPED) + } else { + (object, executed_at, ObjectDigest::OBJECT_DIGEST_DELETED) + }; + let (deleted, wrapped) = if wrap { + (vec![], vec![removed]) + } else { + (vec![removed], vec![]) + }; + TransactionEffects::new_from_execution_v1( + ExecutionStatus::Success, + 0, + GasCostSummary::default(), + vec![ + (object, SequenceNumber::from_u64(object_modified_at)), + (gas, SequenceNumber::from_u64(gas_modified_at)), + ], + vec![], + TransactionDigest::random(), + vec![], + vec![], + vec![], + deleted, + vec![], + wrapped, + ( + (gas, executed_at, ObjectDigest::random()), + Owner::AddressOwner(SuiAddress::ZERO), + ), + None, + vec![], + ) + } + + /// One of the object's versions: the checkpoint that wrote it, whether the object is live at + /// it, and the version the fullnode's rpc-store index records for it. + struct Row { + version: u64, + checkpoint: u64, + live: bool, + indexed_as: u64, + } + + /// `max_version` with `at_checkpoint` against a model of the chain rule + /// (`find_object_lt_or_eq_version` bounded by the checkpoints), with each removal at its + /// tombstone version, over a lifecycle whose wrap and deletion have V1 effects. The + /// fullnode's rpc-store index records a removal at `TransactionEffects::lamport_version`, + /// while the object store holds its tombstone at the removed object's ref version; for V1 + /// effects the first is recomputed from the modified objects alone, so it is lower. The + /// object store also holds versions written above the highest indexed checkpoint, which + /// must not count. + /// + /// For V1 removals this differs from Postgres `obj_versions`, which records the + /// removal at the recomputed lamport version: for a `max_version` at or above that version + /// and below the tombstone, Postgres answers that the object does not exist, while this read + /// returns the version before the removal if that version was written by `at_checkpoint` + /// (and nothing otherwise), as the chain does. + #[test] + fn max_version_at_checkpoint_follows_chain_rule() { + let id = ObjectID::random(); + let gas = ObjectID::random(); + let wrap = v1_removal(id, 5, gas, 7, 1001, true); + let delete = v1_removal(id, 2500, gas, 2400, 3001, false); + let removal = |effects: &TransactionEffects| { + let [(_, tombstone)] = effects.all_tombstones()[..] else { + panic!("expected one tombstone"); + }; + let indexed_as = effects.lamport_version(); + assert!(indexed_as < tombstone, "{indexed_as} < {tombstone}"); + (tombstone.value(), indexed_as.value()) + }; + let (wrapped_at, wrap_indexed_as) = removal(&wrap); + let (deleted_at, delete_indexed_as) = removal(&delete); + assert_eq!((wrapped_at, wrap_indexed_as), (1001, 8)); + assert_eq!((deleted_at, delete_indexed_as), (3001, 2501)); + + let live = |version, checkpoint| Row { + version, + checkpoint, + live: true, + indexed_as: version, + }; + let removed = |(version, indexed_as), checkpoint| Row { + version, + checkpoint, + live: false, + indexed_as, + }; + let lifecycle = [ + live(3, 1), + live(5, 2), + removed((wrapped_at, wrap_indexed_as), 3), + live(2000, 4), + live(2500, 6), + removed((deleted_at, delete_indexed_as), 7), + ]; + let objects: BTreeMap> = lifecycle + .iter() + .map(|row| { + let version = SequenceNumber::from_u64(row.version); + let object = row.live.then(|| { + StoredObject::with_id_owner_version_for_testing( + id, + version, + Owner::AddressOwner(SuiAddress::ZERO), + ) + }); + (version, object) + }) + .collect(); + let indexed_version_at = |checkpoint: u64| { + lifecycle + .iter() + .rfind(|row| row.checkpoint <= checkpoint) + .map(|row| SequenceNumber::from_u64(row.indexed_as)) + }; + let read = |max_version: u64, checkpoint: u64, highest_indexed: u64| { + let read = max_version_at_checkpoint( + SequenceNumber::from_u64(max_version), + indexed_version_at(checkpoint), + || Ok(indexed_version_at(highest_indexed)), + |version| objects.get(&version).cloned().flatten(), + |version| { + Ok(objects + .range(..=version) + .next_back() + .and_then(|(_, object)| object.clone())) + }, + ) + .unwrap(); + match read { + VersionRead::Live(object) => Ok(object.version().value()), + VersionRead::NotFound => Err("not found"), + VersionRead::Missing => Err("missing"), + } + }; + // The newest version at or below `max_version` written up to `highest_indexed`, or "not + // found" if it was written after `checkpoint` or the object had no version as of + // `checkpoint`, or "missing" if there is no such version. Removals sit at their tombstone + // versions, not at `indexed_as`. A selected removal is "not found" by the chain rule, but + // the object store's reads hide tombstones, so the read can only tell it apart from a + // pruned version when it was written after `checkpoint` and the object is live at the + // end of `checkpoint`; otherwise either answer (`None`) is accepted, never an object. + let expected = |max_version: u64, checkpoint: u64, highest_indexed: u64| { + let Some(at_checkpoint) = lifecycle.iter().rfind(|row| row.checkpoint <= checkpoint) + else { + return Some(Err("not found")); + }; + let Some(selected) = lifecycle + .iter() + .rfind(|row| row.version <= max_version && row.checkpoint <= highest_indexed) + else { + return Some(Err("missing")); + }; + if selected.live && selected.checkpoint <= checkpoint { + Some(Ok(selected.version)) + } else if selected.live || (selected.checkpoint > checkpoint && at_checkpoint.live) { + Some(Err("not found")) + } else { + None + } + }; + + let mut max_versions: Vec = (0..=12).collect(); + for row in &lifecycle { + max_versions.extend([ + row.version - 1, + row.version, + row.version + 1, + row.indexed_as, + ]); + } + max_versions.extend([1500, u64::MAX]); + for highest_indexed in 0..=8 { + for checkpoint in 0..=highest_indexed { + for &max_version in &max_versions { + let actual = read(max_version, checkpoint, highest_indexed); + let context = format!( + "max_version {max_version} at_checkpoint {checkpoint} \ + highest indexed {highest_indexed}" + ); + match expected(max_version, checkpoint, highest_indexed) { + Some(expected) => assert_eq!(actual, expected, "{context}"), + None => assert!( + matches!(actual, Err("not found" | "missing")), + "{context}: {actual:?}" + ), + } + } + } + } + + // A newer version at or below `max_version` written after the checkpoint is selected, + // so the read finds nothing rather than an older version. + assert_eq!(read(5, 1, 8), Err("not found")); + assert_eq!(read(5, 2, 8), Ok(5)); + // A version above the highest indexed checkpoint does not count. + assert_eq!(read(2500, 4, 5), Ok(2000)); + assert_eq!(read(2500, 4, 6), Err("not found")); + // Between a V1 removal's indexed version and its tombstone, the version before it is + // the newest (Postgres answers that the object does not exist), and at or above the + // tombstone nothing is, which the read reports as missing: it cannot tell the wrap's + // tombstone from a pruned version. + assert_eq!(read(1000, 3, 8), Ok(5)); + assert_eq!(read(1001, 3, 8), Err("missing")); + // A deletion written after the checkpoint, of the version live at its end, is not found + // even though the read sees no live version at or below `max_version`. + assert_eq!(read(deleted_at, 6, 8), Err("not found")); + assert_eq!(read(u64::MAX, 6, 8), Err("not found")); + } + + fn assert_not_found(result: Result) { + let status = result.unwrap_err().into_status_proto(); + assert_eq!(status.code, tonic::Code::NotFound as i32, "{status:?}"); + } + + fn version(version: u64) -> ObjectSelector { + ObjectSelector::Version { + version, + at_checkpoint: None, + } + } + + fn max_version(max_version: u64) -> ObjectSelector { + ObjectSelector::MaxVersion { + max_version, + at_checkpoint: None, + } + } + + /// Answer one read that found its version missing, on a node with `objects_lower_bound` + /// whose object's latest live version is `latest_live`. + fn answer_missing( + selector: ObjectSelector, + objects_lower_bound: u64, + latest_live: Option, + ) -> Result { + let id = Address::ZERO; + let [result] = answer_missing_versions( + &[(id, selector)], + vec![Ok(None)], + || Ok(objects_lower_bound), + |_| latest_live.map(SequenceNumber::from_u64), + ) + .unwrap() + .try_into() + .unwrap(); + result + } + + /// A missing version is `NOT_FOUND` on a node that holds every version, and when it is an + /// exact version above the object's latest live version. Otherwise a node whose object lower + /// bound is above 0 may have pruned it, and refuses the read with that lower bound. + #[test] + fn missing_versions_are_refused_on_pruned_nodes() { + const FLOOR: u64 = 42; + // A version below the latest live one, read exactly or as a `max_version`. + assert_below_serving_floor_error( + answer_missing(version(5), FLOOR, Some(10)).unwrap_err(), + FLOOR, + ); + assert_below_serving_floor_error( + answer_missing(max_version(5), FLOOR, Some(10)).unwrap_err(), + FLOOR, + ); + // An object with no live version left, or none ever. + assert_below_serving_floor_error( + answer_missing(version(5), FLOOR, None).unwrap_err(), + FLOOR, + ); + assert_below_serving_floor_error( + answer_missing(max_version(u64::MAX), FLOOR, None).unwrap_err(), + FLOOR, + ); + // With `at_checkpoint`, by the same rule. + let at_checkpoint = ObjectSelector::Version { + version: 5, + at_checkpoint: Some(100), + }; + assert_below_serving_floor_error( + answer_missing(at_checkpoint, FLOOR, Some(10)).unwrap_err(), + FLOOR, + ); + + // An exact version above the latest live one does not exist yet. + assert_not_found(answer_missing(version(11), FLOOR, Some(10))); + assert_below_serving_floor_error( + answer_missing(version(10), FLOOR, Some(10)).unwrap_err(), + FLOOR, + ); + + // A node that was neither pruned nor restored holds every version. + for selector in [version(5), version(11), max_version(5), at_checkpoint] { + for latest_live in [None, Some(10)] { + assert_not_found(answer_missing(selector, 0, latest_live)); + } + } + } + + /// In a batch, a missing version fails only its own item, the lower bound is read once, and + /// only if some read found a version missing. + #[test] + fn missing_versions_fail_only_their_own_batch_items() { + let missing = Address::new([1; 32]); + let found = Address::new([2; 32]); + let requests = [ + (missing, version(5)), + (found, version(3)), + (found, max_version(9)), + ]; + let mut lower_bound_reads = 0; + let results = answer_missing_versions( + &requests, + vec![ + Ok(None), + Ok(Some(Object::default())), + Ok(Some(Object::default())), + ], + || { + lower_bound_reads += 1; + Ok(7) + }, + |object_id| { + assert_eq!(object_id, missing); + Some(SequenceNumber::from_u64(10)) + }, + ) + .unwrap(); + assert_eq!(lower_bound_reads, 1); + let [refused, served, served_max] = results.try_into().unwrap(); + assert_below_serving_floor_error(refused.unwrap_err(), 7); + assert_eq!(served.unwrap(), Object::default()); + assert_eq!(served_max.unwrap(), Object::default()); + + let results = answer_missing_versions( + &requests[1..], + vec![ + Ok(Some(Object::default())), + Err(requests[2].1.not_found(found).into()), + ], + || panic!("no read found a version missing"), + |_| panic!("no read found a version missing"), + ) + .unwrap(); + let [served, not_found] = results.try_into().unwrap(); + assert_eq!(served.unwrap(), Object::default()); + assert_not_found(not_found); + } + + /// With `at_checkpoint`, a version written after the checkpoint, a deletion or wrap at the + /// version the checkpoint ends with, and an object with no version as of the checkpoint are + /// `NOT_FOUND` whatever the node pruned. Only a version below that one with no live object may + /// have been pruned. + #[test] + fn at_checkpoint_visibility_misses_stay_not_found() { + let id = ObjectID::random(); + let object = |version: u64| { + StoredObject::with_id_owner_version_for_testing( + id, + SequenceNumber::from_u64(version), + Owner::AddressOwner(SuiAddress::ZERO), + ) + }; + let v = SequenceNumber::from_u64; + let exact = + |version: u64, version_at: Option, held: &[u64]| match version_at_checkpoint( + v(version), + version_at.map(v), + |version| { + held.contains(&version.value()) + .then(|| object(version.value())) + }, + ) { + VersionRead::Live(object) => Ok(object.version().value()), + VersionRead::NotFound => Err("not found"), + VersionRead::Missing => Err("missing"), + }; + // The object is live at 5 at the end of the checkpoint; this node pruned 3. + assert_eq!(exact(5, Some(5), &[5, 7]), Ok(5)); + assert_eq!(exact(7, Some(5), &[5, 7]), Err("not found")); + assert_eq!(exact(9, None, &[5, 7]), Err("not found")); + assert_eq!(exact(3, Some(5), &[5, 7]), Err("missing")); + // The checkpoint ends with a deletion at 6. + assert_eq!(exact(6, Some(6), &[5]), Err("not found")); + + // Versions 3, 5 and 7 written at checkpoints 1, 2 and 3, and a deletion at 9 written at + // checkpoint 4; this node pruned 3 and 5 and holds the deletion's tombstone. + let version_at = |checkpoint: u64| match checkpoint { + 0 => None, + 1 => Some(v(3)), + 2 => Some(v(5)), + 3 => Some(v(7)), + _ => Some(v(9)), + }; + let max = |max_version: u64, checkpoint: u64| match max_version_at_checkpoint( + v(max_version), + version_at(checkpoint), + || Ok(version_at(4)), + |version| (version == v(7)).then(|| object(7)), + |version| Ok((v(7)..v(9)).contains(&version).then(|| object(7))), + ) + .unwrap() + { + VersionRead::Live(object) => Ok(object.version().value()), + VersionRead::NotFound => Err("not found"), + VersionRead::Missing => Err("missing"), + }; + // 7 is selected but was written after checkpoint 2, and the object had no version at 0. + assert_eq!(max(8, 2), Err("not found")); + assert_eq!(max(8, 0), Err("not found")); + assert_eq!(max(8, 3), Ok(7)); + // The deletion is selected but was written after checkpoint 3, where 7 is live. + assert_eq!(max(9, 3), Err("not found")); + assert_eq!(max(u64::MAX, 3), Err("not found")); + // Selecting 5 needs a version this node pruned. + assert_eq!(max(5, 3), Err("missing")); + assert_eq!(max(5, 2), Err("missing")); + // At checkpoint 4 the deletion is selected, which the object store's reads do not tell + // apart from a pruned version. + assert_eq!(max(9, 4), Err("missing")); + } +} + +#[cfg(test)] +mod version_without_history_tests { use sui_rpc::proto::sui::rpc::v2::get_object_result; use sui_types::base_types::{ObjectID, SequenceNumber, SuiAddress}; use sui_types::object::Owner; diff --git a/crates/sui-rpc-api/src/reader.rs b/crates/sui-rpc-api/src/reader.rs index f59defe63b47..42ecaa35a95d 100644 --- a/crates/sui-rpc-api/src/reader.rs +++ b/crates/sui-rpc-api/src/reader.rs @@ -8,6 +8,7 @@ use mysten_common::ZipDebugEqIteratorExt; use sui_package_resolver::{SyncPackageStore, SyncResolver}; use sui_sdk_types::{EpochId, ValidatorCommittee}; use sui_types::base_types::ObjectID; +use sui_types::base_types::SequenceNumber; use sui_types::base_types::TransactionDigest; use sui_types::effects::TransactionEffectsAPI; use sui_types::object::Object; @@ -289,8 +290,9 @@ impl StateReader { Ok(lowest_available_checkpoint.max(lowest_available_checkpoint_objects)) } - /// The upper bound for checkpoint-pinned reads ([`Self::get_object_at_checkpoint`], and - /// `GetPackage`'s `at_checkpoint`): the highest checkpoint every rpc index has committed. + /// The upper bound for checkpoint-pinned reads ([`Self::get_object_at_checkpoint`], + /// [`Self::get_object_version_at_checkpoint`], and `GetPackage`'s `at_checkpoint`): the + /// highest checkpoint every rpc index has committed. /// /// Read it before the reads. It only grows, and the indexes only add data above it, so it /// stays valid for reads made after it was read. The lower bound is the opposite; see @@ -366,18 +368,34 @@ impl StateReader { checkpoint: u64, upper_bound: &AtCheckpointUpperBound, ) -> Result, crate::RpcError> { - upper_bound.check(checkpoint)?; - - let indexes = self.inner().indexes().ok_or_else(indexes_disabled)?; - let Some(version) = indexes - .get_object_version_at_checkpoint(object_id, checkpoint) - .map_err(index_error)? + let Some(version) = + self.get_object_version_at_checkpoint(object_id, checkpoint, upper_bound)? else { return Ok(None); }; // A deletion or wrapping tombstone has no object at its version. Ok(self.inner().get_object_by_key(&object_id, version)) } + + /// The version `object_id` had at the end of `checkpoint`: its newest version written at or + /// before `checkpoint`, including a version at which it was deleted or wrapped. An object's + /// versions increase in checkpoint order, so every version above this one was written after + /// `checkpoint`. `None` if the object did not exist yet. `OutOfRange` + /// (`ABOVE_LATEST_AVAILABLE`) if `checkpoint` is above `upper_bound`; check the lower bound + /// after the read with [`Self::at_checkpoint_lower_bound`]. + pub fn get_object_version_at_checkpoint( + &self, + object_id: ObjectID, + checkpoint: u64, + upper_bound: &AtCheckpointUpperBound, + ) -> Result, crate::RpcError> { + upper_bound.check(checkpoint)?; + + let indexes = self.inner().indexes().ok_or_else(indexes_disabled)?; + indexes + .get_object_version_at_checkpoint(object_id, checkpoint) + .map_err(index_error) + } } /// See `StateReader::at_checkpoint_upper_bound`. Read once per request so that a batch checks diff --git a/crates/sui-rpc-api/src/stub_store.rs b/crates/sui-rpc-api/src/stub_store.rs index 6aed27f304b6..3ba9bb4d5d66 100644 --- a/crates/sui-rpc-api/src/stub_store.rs +++ b/crates/sui-rpc-api/src/stub_store.rs @@ -303,4 +303,17 @@ impl RpcStateReader for StubStore { fn indexes(&self) -> Option<&dyn RpcIndexes> { None } + + fn get_object_lt_or_eq_version( + &self, + object_id: &ObjectID, + version: SequenceNumber, + ) -> Result> { + Ok(self + .objects + .iter() + .filter(|object| object.id() == *object_id && object.version() <= version) + .max_by_key(|object| object.version()) + .cloned()) + } } diff --git a/crates/sui-rpc-store/src/reader/state_reader.rs b/crates/sui-rpc-store/src/reader/state_reader.rs index 93848acef728..74f903eda96c 100644 --- a/crates/sui-rpc-store/src/reader/state_reader.rs +++ b/crates/sui-rpc-store/src/reader/state_reader.rs @@ -6,7 +6,7 @@ //! impl'd in sibling modules) into the top-level trait //! `sui-rpc-api` consumes. //! -//! Adds rpc-api-specific entry points: +//! Adds these rpc-api-specific entry points: //! //! - [`get_lowest_available_checkpoint_objects`]: returns the //! pruning watermark's `tx_seq_lo`-derived checkpoint floor. We @@ -20,12 +20,17 @@ //! [`RpcIndexes`] impl through the same handle. //! - [`layout_package_store`]: supplies the package source in `layout.rs` //! for response-local layout resolution. +//! - [`get_object_lt_or_eq_version`]: delegates to the schema's +//! bounded reverse scan of the `objects` CF. use sui_consistent_store::FrameworkSchema; use sui_consistent_store::reader::Reader; +use sui_types::base_types::ObjectID; +use sui_types::base_types::SequenceNumber; use sui_types::digests::ChainIdentifier; use sui_types::digests::CheckpointDigest; use sui_types::messages_checkpoint::CheckpointSequenceNumber; +use sui_types::object::Object; use sui_types::storage::BackingPackageStore; use sui_types::storage::RpcIndexes; use sui_types::storage::RpcStateReader; @@ -75,4 +80,14 @@ impl RpcStateReader for RpcStoreReader { schema: self.schema(), }) } + + fn get_object_lt_or_eq_version( + &self, + object_id: &ObjectID, + version: SequenceNumber, + ) -> StorageResult> { + self.schema() + .get_object_lt_or_eq_version(*object_id, version) + .map_err(StorageError::custom) + } } diff --git a/crates/sui-rpc-store/src/schema/objects.rs b/crates/sui-rpc-store/src/schema/objects.rs index 66176dd6ca2c..1f676aa2c350 100644 --- a/crates/sui-rpc-store/src/schema/objects.rs +++ b/crates/sui-rpc-store/src/schema/objects.rs @@ -221,6 +221,29 @@ impl super::RpcStoreSchema { let (_key, value) = row?; Ok(decode(value.into_inner())?.into_live()) } + + /// Look up the newest version of an object at or below `version`. + /// + /// A single bounded reverse scan takes the greatest `(id, v)` row with + /// `v <= version`, returning the live object or `None` if that row is + /// a tombstone, like the validator perpetual store's + /// `find_object_lt_or_eq_version`. Returns `Ok(None)` when the object + /// has no recorded version at or below `version`. + pub fn get_object_lt_or_eq_version( + &self, + id: ObjectID, + version: SequenceNumber, + ) -> Result, Error> { + let lowest = Key { + id, + version: SequenceNumber::MIN, + }; + let Some(row) = self.objects.iter_rev(lowest..=Key { id, version })?.next() else { + return Ok(None); + }; + let (_key, value) = row?; + Ok(decode(value.into_inner())?.into_live()) + } } #[cfg(test)] @@ -228,6 +251,7 @@ mod tests { use sui_consistent_store::Db; use sui_consistent_store::DbOptions; use sui_types::base_types::SuiAddress; + use sui_types::object::Owner; use super::*; use crate::RpcStoreSchema; @@ -457,4 +481,60 @@ mod tests { assert_eq!(schema.get_object(a).unwrap(), Some(oa)); assert_eq!(schema.get_object(b).unwrap(), Some(ob)); } + + #[test] + fn get_object_lt_or_eq_version_stops_at_tombstones() { + let (_dir, db, schema) = fresh_db(); + let below = ObjectID::from_single_byte(1); + let id = ObjectID::from_single_byte(2); + let above = ObjectID::from_single_byte(3); + let v = SequenceNumber::from_u64; + let live = |id, version| { + store(&Object::with_id_owner_version_for_testing( + id, + v(version), + Owner::AddressOwner(SuiAddress::ZERO), + )) + }; + + // `id` is live at 1, wrapped at 3, unwrapped at 4 and deleted at 6. The neighboring + // objects' rows sit right next to `id`'s in key order, on either side. + let mut batch = db.batch(); + for (row_id, version, value) in [ + (below, u64::MAX, live(below, u64::MAX)), + (id, 1, live(id, 1)), + (id, 3, tombstone(TombstoneKind::Wrapped)), + (id, 4, live(id, 4)), + (id, 6, tombstone(TombstoneKind::Deleted)), + (above, 0, live(above, 0)), + ] { + let key = Key { + id: row_id, + version: v(version), + }; + batch.put(&schema.objects, &key, &value).unwrap(); + } + batch.commit().unwrap(); + + for (version, expected) in [ + (0, None), + (1, Some(1)), + (2, Some(1)), + (3, None), + (4, Some(4)), + (5, Some(4)), + (6, None), + (u64::MAX, None), + ] { + let found = schema + .get_object_lt_or_eq_version(id, v(version)) + .unwrap() + .map(|object| (object.id(), object.version().value())); + assert_eq!( + found, + expected.map(|version| (id, version)), + "at or below version {version}" + ); + } + } } diff --git a/crates/sui-transactional-test-runner/src/simulator_persisted_store.rs b/crates/sui-transactional-test-runner/src/simulator_persisted_store.rs index 080e4a8f9128..39fb6a4e1bee 100644 --- a/crates/sui-transactional-test-runner/src/simulator_persisted_store.rs +++ b/crates/sui-transactional-test-runner/src/simulator_persisted_store.rs @@ -746,6 +746,23 @@ impl RpcStateReader for PersistedStoreInnerReadOnlyWrapper { fn indexes(&self) -> Option<&dyn sui_types::storage::RpcIndexes> { None } + + /// The store records no versions at which objects were deleted or wrapped, so only a live + /// object at or below `version` can be answered exactly. Any other read fails rather than + /// return a version the object may already have left. + fn get_object_lt_or_eq_version( + &self, + object_id: &ObjectID, + version: SequenceNumber, + ) -> sui_types::storage::error::Result> { + match ObjectStore::get_object(self, object_id) { + Some(object) if object.version() <= version => Ok(Some(object)), + _ => Err(sui_types::storage::error::Error::custom( + "PersistedStoreInnerReadOnlyWrapper only serves version-bounded reads of live \ + objects at or below the bound", + )), + } + } } impl PersistedStoreInnerReadOnlyWrapper { diff --git a/crates/sui-types/src/storage/read_store.rs b/crates/sui-types/src/storage/read_store.rs index d9faf568ad66..c87789b097a3 100644 --- a/crates/sui-types/src/storage/read_store.rs +++ b/crates/sui-types/src/storage/read_store.rs @@ -750,6 +750,15 @@ pub trait RpcStateReader: ReadStore + super::RuntimeObjectResolver + Send + Sync // Get a handle to an instance of the RpcIndexes fn indexes(&self) -> Option<&dyn RpcIndexes>; + /// The object's newest version at or below `version`, like the execution cache's + /// `find_object_lt_or_eq_version`. `None` if the object has no version at or below + /// `version`, or if it was deleted or wrapped at that newest version. + fn get_object_lt_or_eq_version( + &self, + object_id: &ObjectID, + version: SequenceNumber, + ) -> Result>; + /// The sequence number of the highest executed checkpoint, independent of /// how far any embedded index has caught up. ///