From 1bf0543cb7dcbc137ba274fe0fab33e5b20e0b95 Mon Sep 17 00:00:00 2001 From: tianyuan Date: Thu, 29 Oct 2026 16:37:53 +0800 Subject: [PATCH 01/12] fix(raw): scan reverse ranges across regions Signed-off-by: tianyuan --- src/mock.rs | 12 ++++ src/pd/client.rs | 23 ++++++++ src/pd/cluster.rs | 20 +++++++ src/pd/retry.rs | 21 +++++++ src/raw/client.rs | 132 ++++++++++++++++++++++++++++++++++++++------ src/region_cache.rs | 15 +++++ 6 files changed, 205 insertions(+), 18 deletions(-) diff --git a/src/mock.rs b/src/mock.rs index 0a1c1b774..1133d3191 100644 --- a/src/mock.rs +++ b/src/mock.rs @@ -241,6 +241,18 @@ impl PdClient for MockPdClient { Ok(region) } + async fn prev_region_for_key(&self, key: &Key) -> Result { + let region = self.region_for_key(key).await?; + match region.id() { + 1 => Err(Error::RegionForKeyNotFound { key: key.to_vec() }), + 2 => Ok(Self::region1()), + 3 => Ok(Self::region2()), + _ => Err(Error::RegionNotFoundInResponse { + region_id: region.id(), + }), + } + } + async fn region_for_id(&self, id: RegionId) -> Result { match id { 1 => Ok(Self::region1()), diff --git a/src/pd/client.rs b/src/pd/client.rs index b89658751..54147fa5d 100644 --- a/src/pd/client.rs +++ b/src/pd/client.rs @@ -28,6 +28,7 @@ use crate::store::TikvConnect; use crate::store::{KvClient, Store}; use crate::BoundRange; use crate::Config; +use crate::Error; use crate::Key; use crate::Result; use crate::SecurityManager; @@ -60,6 +61,13 @@ pub trait PdClient: Send + Sync + 'static { /// In transactional API, the key and returned region are both decoded (keys in raw format). async fn region_for_key(&self, key: &Key) -> Result; + /// Return the region immediately before the region containing `key`. + /// + /// This is used by reverse scans when they reach a region boundary. + async fn prev_region_for_key(&self, _key: &Key) -> Result { + Err(Error::Unimplemented) + } + /// In transactional API, the returned region is decoded (keys in raw format) async fn region_for_id(&self, id: RegionId) -> Result; @@ -242,6 +250,21 @@ impl PdClient for PdRpcClient { Self::decode_region(region, enable_codec) } + async fn prev_region_for_key(&self, key: &Key) -> Result { + let enable_codec = self.enable_codec; + let key = if enable_codec { + key.to_encoded() + } else { + key.clone() + }; + + let region = self + .region_cache + .read_through_prev_region_by_key(key) + .await?; + Self::decode_region(region, enable_codec) + } + async fn region_for_id(&self, id: RegionId) -> Result { let region = self.region_cache.get_region_by_id(id).await?; Self::decode_region(region, self.enable_codec) diff --git a/src/pd/cluster.rs b/src/pd/cluster.rs index 5ac0b0f3a..ec30f5526 100644 --- a/src/pd/cluster.rs +++ b/src/pd/cluster.rs @@ -53,6 +53,26 @@ impl Cluster { req.send(&mut self.client, timeout).await } + pub async fn get_prev_region( + &mut self, + key: Vec, + timeout: Duration, + ) -> Result { + let mut req = pd_request!(self.id, pdpb::GetRegionRequest); + req.region_key = key; + let mut req = req.into_request(); + req.set_timeout(timeout); + let response = self.client.get_prev_region(req).await?.into_inner(); + if let Some(err) = &response + .header + .as_ref() + .and_then(|header| header.error.as_ref()) + { + return Err(internal_err!(err.message.clone())); + } + Ok(response) + } + pub async fn get_region_by_id( &mut self, id: u64, diff --git a/src/pd/retry.rs b/src/pd/retry.rs index 5449c1088..1c5600e0b 100644 --- a/src/pd/retry.rs +++ b/src/pd/retry.rs @@ -37,6 +37,13 @@ pub trait RetryClientTrait { // It does not know about encoding. Caller should take care of it. async fn get_region(self: Arc, key: Vec) -> Result; + async fn get_prev_region(self: Arc, _key: Vec) -> Result + where + Self: Send + Sync, + { + Err(Error::Unimplemented) + } + async fn get_region_by_id(self: Arc, region_id: RegionId) -> Result; async fn get_store(self: Arc, id: StoreId) -> Result; @@ -159,6 +166,20 @@ impl RetryClientTrait for RetryClient { }) } + async fn get_prev_region(self: Arc, key: Vec) -> Result { + retry_mut!(self, "get_prev_region", |cluster| { + let key = key.clone(); + async { + cluster + .get_prev_region(key.clone(), self.timeout) + .await + .and_then(|resp| { + region_from_response(resp, || Error::RegionForKeyNotFound { key }) + }) + } + }) + } + async fn get_region_by_id(self: Arc, region_id: RegionId) -> Result { retry_mut!(self, "get_region_by_id", |cluster| async { cluster diff --git a/src/raw/client.rs b/src/raw/client.rs index 9dab092db..e79ea2a8d 100644 --- a/src/raw/client.rs +++ b/src/raw/client.rs @@ -765,16 +765,23 @@ impl Client { }); } let backoff = DEFAULT_STORE_BACKOFF; - let mut range = range.into().encode_keyspace(self.keyspace, KeyMode::Raw); + let range = range.into().encode_keyspace(self.keyspace, KeyMode::Raw); let mut result = Vec::new(); let mut current_limit = limit; - let (start_key, end_key) = range.clone().into_keys(); - let mut current_key: Key = start_key; + let (range_start, range_end) = range.into_keys(); + let reverse_unbounded = reverse && range_end.is_none(); + let mut current_key = if reverse && !reverse_unbounded { + range_end.clone().unwrap() + } else { + range_start.clone() + }; while current_limit > 0 { let scan_args = ScanInnerArgs { - start_key: current_key.clone(), - end_key: end_key.clone(), + current_key: current_key.clone(), + range_start: range_start.clone(), + range_end: range_end.clone(), + reverse_unbounded, limit: current_limit, key_only, reverse, @@ -790,15 +797,14 @@ impl Client { current_limit -= kvs.len() as u32; result.append(&mut kvs); } - if next_key.is_empty() { - break; - } - if end_key.clone().is_some_and(|ek| ek <= next_key) { + if reverse && !reverse_unbounded { + if next_key.is_empty() || next_key <= range_start { + break; + } + } else if next_key.is_empty() || range_end.clone().is_some_and(|ek| ek <= next_key) { break; - } else { - current_key = next_key; - range = BoundRange::new(std::ops::Bound::Included(current_key.clone()), range.to); } + current_key = next_key; } // limit is a soft limit, so we need check the number of results @@ -814,11 +820,30 @@ impl Client { &self, mut scan_args: ScanInnerArgs, ) -> Result<(Option, Key)> { - let start_key = scan_args.start_key; - let end_key = scan_args.end_key; + let current_key = scan_args.current_key; loop { - let region = self.rpc.clone().region_for_key(&start_key).await?; + let region = if scan_args.reverse && !scan_args.reverse_unbounded { + let region = self.rpc.clone().region_for_key(¤t_key).await?; + if !current_key.is_empty() && region.start_key() == current_key { + self.rpc.clone().prev_region_for_key(¤t_key).await? + } else { + region + } + } else { + self.rpc.clone().region_for_key(¤t_key).await? + }; let store = self.rpc.clone().store_for_id(region.id()).await?; + let (start_key, end_key) = if scan_args.reverse && !scan_args.reverse_unbounded { + let region_start = region.start_key(); + let start_key = if region_start < scan_args.range_start { + scan_args.range_start.clone() + } else { + region_start + }; + (start_key, Some(current_key.clone())) + } else { + (current_key.clone(), scan_args.range_end.clone()) + }; let request = new_raw_scan_request( (start_key.clone(), end_key.clone()).into(), scan_args.limit, @@ -842,7 +867,12 @@ impl Client { return Err(RegionError(Box::new(err))); } } - Ok((Some(r), region.end_key())) + let next_key = if scan_args.reverse && !scan_args.reverse_unbounded { + region.start_key() + } else { + region.end_key() + }; + Ok((Some(r), next_key)) } Err(err) => Err(err), }; @@ -910,8 +940,10 @@ impl Client { #[derive(Clone)] struct ScanInnerArgs { - start_key: Key, - end_key: Option, + current_key: Key, + range_start: Key, + range_end: Option, + reverse_unbounded: bool, limit: u32, key_only: bool, reverse: bool, @@ -923,6 +955,7 @@ mod tests { use std::any::Any; use std::sync::atomic::{AtomicUsize, Ordering}; use std::sync::Arc; + use std::sync::Mutex; use super::*; use crate::mock::MockKvClient; @@ -930,6 +963,69 @@ mod tests { use crate::proto::kvrpcpb; use crate::Result; + #[tokio::test] + async fn reverse_scan_across_regions_uses_previous_regions() -> Result<()> { + let keys = Arc::new(vec![vec![1], vec![11], vec![251]]); + let requests = Arc::new(Mutex::new(Vec::<(Vec, Vec)>::new())); + let dispatched_keys = keys.clone(); + let dispatched_requests = requests.clone(); + let pd_client = Arc::new(MockPdClient::new(MockKvClient::with_dispatch_hook( + move |req: &dyn Any| { + let req = req.downcast_ref::().unwrap(); + assert!(req.reverse); + dispatched_requests + .lock() + .unwrap() + .push((req.start_key.clone(), req.end_key.clone())); + + let kvs = dispatched_keys + .iter() + .filter(|key| key.as_slice() >= req.end_key.as_slice()) + .filter(|key| key.as_slice() < req.start_key.as_slice()) + .rev() + .map(|key| kvrpcpb::KvPair { + key: key.clone(), + value: key.clone(), + ..Default::default() + }) + .collect(); + Ok(Box::new(kvrpcpb::RawScanResponse { + kvs, + ..Default::default() + }) as Box) + }, + ))); + let client = Client { + rpc: pd_client, + cf: None, + backoff: DEFAULT_REGION_BACKOFF, + atomic: false, + keyspace: Keyspace::Disable, + }; + + let pairs = client.scan_reverse(vec![1]..vec![255], 2).await?; + assert_eq!( + pairs.into_iter().map(|pair| pair.0).collect::>(), + vec![Key::from(vec![251]), Key::from(vec![11])] + ); + assert_eq!( + requests.lock().unwrap().as_slice(), + &[(vec![255], vec![250, 250]), (vec![250, 250], vec![10]),] + ); + + requests.lock().unwrap().clear(); + let pairs = client.scan_reverse(vec![1]..vec![250, 250], 2).await?; + assert_eq!( + pairs.into_iter().map(|pair| pair.0).collect::>(), + vec![Key::from(vec![11]), Key::from(vec![1])] + ); + assert_eq!( + requests.lock().unwrap().as_slice(), + &[(vec![250, 250], vec![10]), (vec![10], vec![1]),] + ); + Ok(()) + } + #[rstest::rstest] #[case::forward(false)] #[case::reverse(true)] diff --git a/src/region_cache.rs b/src/region_cache.rs index 2a4b0fbbd..ee92af5c4 100644 --- a/src/region_cache.rs +++ b/src/region_cache.rs @@ -138,6 +138,21 @@ impl RegionCache { Ok(region) } + /// Force read through (query from PD) for the region immediately before + /// the region containing `key`. + pub async fn read_through_prev_region_by_key(&self, key: Key) -> Result + where + C: Send + Sync, + { + let region = self + .inner_client + .clone() + .get_prev_region(key.into()) + .await?; + self.add_region(region.clone()).await; + Ok(region) + } + /// Force read through (query from PD) and update cache async fn read_through_region_by_id(&self, id: RegionId) -> Result { // put a notify to let others know the region id is being queried From 701fb5adf9d18a1b16ceef785c76ef740d2dd47b Mon Sep 17 00:00:00 2001 From: tianyuan Date: Thu, 29 Oct 2026 20:32:38 +0800 Subject: [PATCH 02/12] fix(raw): handle reverse scan cache refreshes Signed-off-by: tianyuan --- src/mock.rs | 15 ++++++ src/raw/client.rs | 120 ++++++++++++++++++++++++++++++++++++++++++-- src/region_cache.rs | 72 +++++++++++++++++++++++++- 3 files changed, 203 insertions(+), 4 deletions(-) diff --git a/src/mock.rs b/src/mock.rs index 1133d3191..446aa3ace 100644 --- a/src/mock.rs +++ b/src/mock.rs @@ -86,6 +86,10 @@ pub struct MockPdClient { #[new(default)] region_for_key_hook: Option Result + Send + Sync + 'static>>, + /// Optional override for `prev_region_for_key`. + #[new(default)] + prev_region_for_key_hook: + Option Result + Send + Sync + 'static>>, /// Optional observer/override for leader cache updates. #[new(default)] update_leader_hook: @@ -140,6 +144,14 @@ impl MockPdClient { self } + pub fn with_prev_region_for_key_hook(mut self, hook: F) -> MockPdClient + where + F: Fn(&Key) -> Result + Send + Sync + 'static, + { + self.prev_region_for_key_hook = Some(Arc::new(hook)); + self + } + pub fn with_update_leader_hook(mut self, hook: F) -> MockPdClient where F: Fn(RegionVerId, metapb::Peer) -> Result<()> + Send + Sync + 'static, @@ -242,6 +254,9 @@ impl PdClient for MockPdClient { } async fn prev_region_for_key(&self, key: &Key) -> Result { + if let Some(hook) = &self.prev_region_for_key_hook { + return hook(key); + } let region = self.region_for_key(key).await?; match region.id() { 1 => Err(Error::RegionForKeyNotFound { key: key.to_vec() }), diff --git a/src/raw/client.rs b/src/raw/client.rs index e79ea2a8d..3e6a2728f 100644 --- a/src/raw/client.rs +++ b/src/raw/client.rs @@ -769,7 +769,13 @@ impl Client { let mut result = Vec::new(); let mut current_limit = limit; let (range_start, range_end) = range.into_keys(); - let reverse_unbounded = reverse && range_end.is_none(); + // `encode_keyspace` represents an unbounded upper bound as an empty key + // when keyspace prefixes are disabled. Keyspace-enabled ranges use the + // next keyspace prefix instead, so their encoded upper bound is non-empty. + let reverse_unbounded = reverse + && (range_end.is_none() + || (range_end.as_ref().is_some_and(Key::is_empty) + && !matches!(self.keyspace, Keyspace::Enable { .. }))); let mut current_key = if reverse && !reverse_unbounded { range_end.clone().unwrap() } else { @@ -825,7 +831,18 @@ impl Client { let region = if scan_args.reverse && !scan_args.reverse_unbounded { let region = self.rpc.clone().region_for_key(¤t_key).await?; if !current_key.is_empty() && region.start_key() == current_key { - self.rpc.clone().prev_region_for_key(¤t_key).await? + let previous = match self.rpc.clone().prev_region_for_key(¤t_key).await { + Ok(previous) if previous.end_key() == current_key => previous, + Ok(_) | Err(Error::RegionForKeyNotFound { .. }) => { + // The cached containing region is stale (for example, + // after a merge), so the predecessor no longer ends + // at this cursor. Drop it and resolve the cursor again. + self.rpc.invalidate_region_cache(region.ver_id()).await; + continue; + } + Err(error) => return Err(error), + }; + previous } else { region } @@ -953,7 +970,7 @@ struct ScanInnerArgs { #[cfg(test)] mod tests { use std::any::Any; - use std::sync::atomic::{AtomicUsize, Ordering}; + use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; use std::sync::Arc; use std::sync::Mutex; @@ -1026,6 +1043,103 @@ mod tests { Ok(()) } + #[tokio::test] + async fn reverse_scan_from_unbounded_upper_bound_uses_range_start() -> Result<()> { + let looked_up_keys = Arc::new(Mutex::new(Vec::::new())); + let dispatched_lookups = looked_up_keys.clone(); + let pd_client = Arc::new( + MockPdClient::new(MockKvClient::with_dispatch_hook(move |req: &dyn Any| { + let req = req.downcast_ref::().unwrap(); + assert!(req.reverse); + assert!(req.start_key.is_empty()); + assert_eq!(req.end_key, vec![251]); + Ok(Box::new(kvrpcpb::RawScanResponse { + kvs: vec![kvrpcpb::KvPair { + key: vec![251], + value: vec![42], + ..Default::default() + }], + ..Default::default() + }) as Box) + })) + .with_region_for_key_hook(move |key| { + dispatched_lookups.lock().unwrap().push(key.clone()); + Ok(MockPdClient::region3()) + }), + ); + let client = Client { + rpc: pd_client, + cf: None, + backoff: DEFAULT_REGION_BACKOFF, + atomic: false, + keyspace: Keyspace::Disable, + }; + + assert_eq!(client.scan_reverse(vec![251].., 1).await?.len(), 1); + assert_eq!( + looked_up_keys.lock().unwrap().as_slice(), + &[Key::from(vec![251])] + ); + Ok(()) + } + + #[tokio::test] + async fn reverse_scan_refreshes_stale_region_boundary() -> Result<()> { + let refreshed = Arc::new(AtomicBool::new(false)); + let invalidations = Arc::new(AtomicUsize::new(0)); + let requests = Arc::new(Mutex::new(Vec::<(Vec, Vec)>::new())); + let region_refreshed = refreshed.clone(); + let invalidation_count = invalidations.clone(); + let dispatched_requests = requests.clone(); + let stale_region = MockPdClient::region3(); + let mut merged_region = MockPdClient::region3(); + merged_region.region.start_key = vec![10]; + merged_region.region.region_epoch.as_mut().unwrap().version = 1; + let merged_region_for_lookup = merged_region.clone(); + let pd_client = Arc::new( + MockPdClient::new(MockKvClient::with_dispatch_hook(move |req: &dyn Any| { + let req = req.downcast_ref::().unwrap(); + dispatched_requests + .lock() + .unwrap() + .push((req.start_key.clone(), req.end_key.clone())); + Ok(Box::new(kvrpcpb::RawScanResponse::default()) as Box) + })) + .with_region_for_key_hook(move |key| { + if region_refreshed.load(Ordering::SeqCst) { + let key_bytes: &[u8] = key.into(); + if key_bytes >= [10].as_slice() { + Ok(merged_region_for_lookup.clone()) + } else { + Ok(MockPdClient::region1()) + } + } else { + Ok(stale_region.clone()) + } + }) + .with_prev_region_for_key_hook(|_| Ok(MockPdClient::region1())) + .with_invalidate_region_hook(move |_| { + invalidation_count.fetch_add(1, Ordering::SeqCst); + refreshed.store(true, Ordering::SeqCst); + }), + ); + let client = Client { + rpc: pd_client, + cf: None, + backoff: DEFAULT_REGION_BACKOFF, + atomic: false, + keyspace: Keyspace::Disable, + }; + + client.scan_reverse(vec![1]..vec![250, 250], 1).await?; + assert_eq!(invalidations.load(Ordering::SeqCst), 1); + assert_eq!( + requests.lock().unwrap().as_slice(), + &[(vec![250, 250], vec![10]), (vec![10], vec![1])] + ); + Ok(()) + } + #[rstest::rstest] #[case::forward(false)] #[case::reverse(true)] diff --git a/src/region_cache.rs b/src/region_cache.rs index ee92af5c4..c3ad81f54 100644 --- a/src/region_cache.rs +++ b/src/region_cache.rs @@ -144,11 +144,25 @@ impl RegionCache { where C: Send + Sync, { - let region = self + let mut region = self .inner_client .clone() .get_prev_region(key.into()) .await?; + + // A reverse scan may refresh the predecessor after TiKV has supplied a + // more recent NotLeader hint. Preserve that corrected leader when PD + // returns the same region version again. + let cached_leader = { + let cache = self.region_cache.read().await; + cache + .ver_id_to_region + .get(®ion.ver_id()) + .and_then(|cached| cached.leader.clone()) + }; + if cached_leader.is_some() { + region.leader = cached_leader; + } self.add_region(region.clone()).await; Ok(region) } @@ -341,6 +355,20 @@ mod test { .ok_or_else(|| Error::StringError("MockRetryClient: region not found".to_owned())) } + async fn get_prev_region( + self: Arc, + key: Vec, + ) -> Result { + self.get_region_count.fetch_add(1, SeqCst); + self.regions + .lock() + .await + .values() + .find(|r| r.end_key() == key.clone().into()) + .cloned() + .ok_or_else(|| Error::RegionForKeyNotFound { key }) + } + async fn get_region_by_id( self: Arc, region_id: crate::region::RegionId, @@ -547,6 +575,48 @@ mod test { Ok(()) } + #[tokio::test] + async fn test_prev_region_preserves_cached_leader() -> Result<()> { + let retry_client = Arc::new(MockRetryClient::default()); + let cache = RegionCache::new(retry_client.clone()); + let mut pd_region = region(1, vec![], vec![10]); + pd_region.leader = Some(metapb::Peer { + store_id: 41, + ..Default::default() + }); + retry_client + .regions + .lock() + .await + .insert(pd_region.id(), pd_region.clone()); + + cache.add_region(pd_region.clone()).await; + cache + .update_leader( + pd_region.ver_id(), + metapb::Peer { + store_id: 42, + ..Default::default() + }, + ) + .await?; + + let refreshed = cache + .read_through_prev_region_by_key(vec![10].into()) + .await?; + assert_eq!(refreshed.leader.unwrap().store_id, 42); + assert_eq!( + cache + .get_region_by_id(pd_region.id()) + .await? + .leader + .unwrap() + .store_id, + 42 + ); + Ok(()) + } + // a helper function to assert the cache is in expected state async fn assert( cache: &RegionCache, From 65fc45e1b8d77a7d0eac5a4d0facf13ac5bcddb8 Mon Sep 17 00:00:00 2001 From: tianyuan Date: Fri, 30 Oct 2026 08:51:40 +0800 Subject: [PATCH 03/12] fix(raw): traverse final region for unbounded reverse scans Signed-off-by: tianyuan --- src/raw/client.rs | 112 +++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 106 insertions(+), 6 deletions(-) diff --git a/src/raw/client.rs b/src/raw/client.rs index 3e6a2728f..11dfd19bd 100644 --- a/src/raw/client.rs +++ b/src/raw/client.rs @@ -517,7 +517,8 @@ impl Client { /// from startKey(lowerBound) to endKey(upperBound) in reverse order, up to limit pairs. /// The returned keys are in reversed lexicographical order. /// If you want to include the endKey or exclude the startKey, push a '\0' to the key. - /// It doesn't support Scanning from "", because locating the last Region is not yet implemented. + /// An unbounded upper bound is supported by locating the final Region before + /// traversing Regions backwards toward the lower bound. /// # Examples /// ```rust,no_run /// # use tikv_client::{KvPair, Config, RawClient, IntoOwnedRange}; @@ -772,7 +773,7 @@ impl Client { // `encode_keyspace` represents an unbounded upper bound as an empty key // when keyspace prefixes are disabled. Keyspace-enabled ranges use the // next keyspace prefix instead, so their encoded upper bound is non-empty. - let reverse_unbounded = reverse + let mut reverse_unbounded = reverse && (range_end.is_none() || (range_end.as_ref().is_some_and(Key::is_empty) && !matches!(self.keyspace, Keyspace::Enable { .. }))); @@ -781,6 +782,11 @@ impl Client { } else { range_start.clone() }; + let mut initial_region = if reverse_unbounded { + Some(self.last_region_for_key(&range_start).await?) + } else { + None + }; while current_limit > 0 { let scan_args = ScanInnerArgs { @@ -788,6 +794,7 @@ impl Client { range_start: range_start.clone(), range_end: range_end.clone(), reverse_unbounded, + initial_region: initial_region.take(), limit: current_limit, key_only, reverse, @@ -807,6 +814,14 @@ impl Client { if next_key.is_empty() || next_key <= range_start { break; } + } else if reverse_unbounded { + if next_key.is_empty() || next_key <= range_start { + break; + } + // The first request used the final region with an unbounded + // upper edge. Subsequent requests walk bounded regions back + // toward the lower edge just like an ordinary reverse scan. + reverse_unbounded = false; } else if next_key.is_empty() || range_end.clone().is_some_and(|ek| ek <= next_key) { break; } @@ -822,13 +837,35 @@ impl Client { Ok(result) } + async fn last_region_for_key(&self, key: &Key) -> Result { + let mut region = self.rpc.clone().region_for_key(key).await?; + loop { + let end_key = region.end_key(); + if end_key.is_empty() { + return Ok(region); + } + + let next_region = self.rpc.clone().region_for_key(&end_key).await?; + if next_region.start_key() != end_key { + self.rpc.invalidate_region_cache(region.ver_id()).await; + self.rpc.invalidate_region_cache(next_region.ver_id()).await; + region = self.rpc.clone().region_for_key(key).await?; + continue; + } + region = next_region; + } + } + async fn retryable_scan( &self, mut scan_args: ScanInnerArgs, ) -> Result<(Option, Key)> { let current_key = scan_args.current_key; + let mut region_override = scan_args.initial_region.take(); loop { - let region = if scan_args.reverse && !scan_args.reverse_unbounded { + let region = if let Some(region) = region_override.take() { + region + } else if scan_args.reverse && !scan_args.reverse_unbounded { let region = self.rpc.clone().region_for_key(¤t_key).await?; if !current_key.is_empty() && region.start_key() == current_key { let previous = match self.rpc.clone().prev_region_for_key(¤t_key).await { @@ -850,14 +887,18 @@ impl Client { self.rpc.clone().region_for_key(¤t_key).await? }; let store = self.rpc.clone().store_for_id(region.id()).await?; - let (start_key, end_key) = if scan_args.reverse && !scan_args.reverse_unbounded { + let (start_key, end_key) = if scan_args.reverse { let region_start = region.start_key(); let start_key = if region_start < scan_args.range_start { scan_args.range_start.clone() } else { region_start }; - (start_key, Some(current_key.clone())) + if scan_args.reverse_unbounded { + (start_key, None) + } else { + (start_key, Some(current_key.clone())) + } } else { (current_key.clone(), scan_args.range_end.clone()) }; @@ -876,15 +917,22 @@ impl Client { plan::handle_region_error(self.rpc.clone(), err.clone(), store.clone()) .await?; if status { + if scan_args.reverse { + region_override = Some(region.clone()); + } continue; } else if let Some(duration) = scan_args.backoff.next_delay_duration() { + if scan_args.reverse_unbounded { + region_override = + Some(self.last_region_for_key(&scan_args.range_start).await?); + } sleep(duration).await; continue; } else { return Err(RegionError(Box::new(err))); } } - let next_key = if scan_args.reverse && !scan_args.reverse_unbounded { + let next_key = if scan_args.reverse { region.start_key() } else { region.end_key() @@ -961,6 +1009,7 @@ struct ScanInnerArgs { range_start: Key, range_end: Option, reverse_unbounded: bool, + initial_region: Option, limit: u32, key_only: bool, reverse: bool, @@ -1083,6 +1132,57 @@ mod tests { Ok(()) } + #[tokio::test] + async fn reverse_scan_unbounded_upper_traverses_from_final_region() -> Result<()> { + let requests = Arc::new(Mutex::new(Vec::<(Vec, Vec)>::new())); + let dispatched_requests = requests.clone(); + let pd_client = Arc::new(MockPdClient::new(MockKvClient::with_dispatch_hook( + move |req: &dyn Any| { + let req = req.downcast_ref::().unwrap(); + assert!(req.reverse); + dispatched_requests + .lock() + .unwrap() + .push((req.start_key.clone(), req.end_key.clone())); + let key = match (req.start_key.as_slice(), req.end_key.as_slice()) { + ([], [250, 250]) => vec![251], + ([250, 250], [10]) => vec![11], + request => panic!("unexpected reverse scan request: {request:?}"), + }; + Ok(Box::new(kvrpcpb::RawScanResponse { + kvs: vec![kvrpcpb::KvPair { + key: key.clone(), + value: key, + ..Default::default() + }], + ..Default::default() + }) as Box) + }, + ))); + let client = Client { + rpc: pd_client, + cf: None, + backoff: DEFAULT_REGION_BACKOFF, + atomic: false, + keyspace: Keyspace::Disable, + }; + + assert_eq!( + client + .scan_reverse(vec![1].., 2) + .await? + .into_iter() + .map(|pair| pair.0) + .collect::>(), + vec![Key::from(vec![251]), Key::from(vec![11])] + ); + assert_eq!( + requests.lock().unwrap().as_slice(), + &[(vec![], vec![250, 250]), (vec![250, 250], vec![10])] + ); + Ok(()) + } + #[tokio::test] async fn reverse_scan_refreshes_stale_region_boundary() -> Result<()> { let refreshed = Arc::new(AtomicBool::new(false)); From 4222b00c26c73a97554e1474815327de39434fab Mon Sep 17 00:00:00 2001 From: tianyuan Date: Fri, 30 Oct 2026 09:02:27 +0800 Subject: [PATCH 04/12] refactor(pd): reuse cached predecessor regions Signed-off-by: tianyuan --- src/pd/client.rs | 6 ++++++ src/pd/retry.rs | 2 ++ src/region_cache.rs | 39 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 47 insertions(+) diff --git a/src/pd/client.rs b/src/pd/client.rs index 54147fa5d..b9d192478 100644 --- a/src/pd/client.rs +++ b/src/pd/client.rs @@ -64,6 +64,8 @@ pub trait PdClient: Send + Sync + 'static { /// Return the region immediately before the region containing `key`. /// /// This is used by reverse scans when they reach a region boundary. + /// The default keeps existing `PdClient` implementations source-compatible; + /// clients that do not support predecessor lookup report `Unimplemented`. async fn prev_region_for_key(&self, _key: &Key) -> Result { Err(Error::Unimplemented) } @@ -258,6 +260,10 @@ impl PdClient for PdRpcClient { key.clone() }; + if let Some(region) = self.region_cache.get_prev_region_by_key(&key).await { + return Self::decode_region(region, enable_codec); + } + let region = self .region_cache .read_through_prev_region_by_key(key) diff --git a/src/pd/retry.rs b/src/pd/retry.rs index 1c5600e0b..a6fe8cb71 100644 --- a/src/pd/retry.rs +++ b/src/pd/retry.rs @@ -41,6 +41,8 @@ pub trait RetryClientTrait { where Self: Send + Sync, { + // Keep this default for compatibility with custom retry clients that + // predate predecessor-region lookup. Err(Error::Unimplemented) } diff --git a/src/region_cache.rs b/src/region_cache.rs index c3ad81f54..675dec8e7 100644 --- a/src/region_cache.rs +++ b/src/region_cache.rs @@ -94,6 +94,22 @@ impl RegionCache { self.read_through_region_by_key(key.clone()).await } + /// Return a cached predecessor whose end key is exactly `key`. + /// + /// A matching boundary is safe to use for the common case and avoids a PD + /// round trip. Callers still fall back to a forced read when the predecessor + /// is absent; region errors invalidate stale entries and trigger a refresh. + pub async fn get_prev_region_by_key(&self, key: &Key) -> Option { + let region_cache_guard = self.region_cache.read().await; + region_cache_guard + .key_to_ver_id + .range::(..key) + .next_back() + .and_then(|(_, ver_id)| region_cache_guard.ver_id_to_region.get(ver_id)) + .filter(|region| region.end_key() == key.clone()) + .cloned() + } + // Retrieve cache entry by RegionId. If there's no entry, query PD and update cache. pub async fn get_region_by_id(&self, id: RegionId) -> Result { for _ in 0..=MAX_RETRY_WAITING_CONCURRENT_REQUEST { @@ -575,6 +591,29 @@ mod test { Ok(()) } + #[tokio::test] + async fn test_get_prev_region_by_key_uses_exact_cached_boundary() { + let retry_client = Arc::new(MockRetryClient::default()); + let cache = RegionCache::new(retry_client); + let region1 = region(1, vec![], vec![10]); + let region2 = region(2, vec![10], vec![20]); + cache.add_region(region1).await; + cache.add_region(region2.clone()).await; + + assert_eq!( + cache + .get_prev_region_by_key(&vec![20].into()) + .await + .map(|region| region.id()), + Some(region2.id()) + ); + assert!(cache + .get_prev_region_by_key(&vec![15].into()) + .await + .is_none()); + assert!(cache.get_prev_region_by_key(&Key::EMPTY).await.is_none()); + } + #[tokio::test] async fn test_prev_region_preserves_cached_leader() -> Result<()> { let retry_client = Arc::new(MockRetryClient::default()); From 7cec455fa4cf406a4dadabdb05d08e9fb99a38d1 Mon Sep 17 00:00:00 2001 From: tianyuan Date: Fri, 30 Oct 2026 09:45:59 +0800 Subject: [PATCH 05/12] refactor(pd): require predecessor lookup implementations Make the new predecessor-region methods required, matching the existing internal trait API and avoiding an inconsistent default error implementation. Signed-off-by: tianyuan --- src/pd/client.rs | 7 +------ src/pd/retry.rs | 9 +-------- src/request/mod.rs | 8 ++++++++ src/transaction/transaction/scanner.rs | 4 ++++ 4 files changed, 14 insertions(+), 14 deletions(-) diff --git a/src/pd/client.rs b/src/pd/client.rs index b9d192478..50355f045 100644 --- a/src/pd/client.rs +++ b/src/pd/client.rs @@ -28,7 +28,6 @@ use crate::store::TikvConnect; use crate::store::{KvClient, Store}; use crate::BoundRange; use crate::Config; -use crate::Error; use crate::Key; use crate::Result; use crate::SecurityManager; @@ -64,11 +63,7 @@ pub trait PdClient: Send + Sync + 'static { /// Return the region immediately before the region containing `key`. /// /// This is used by reverse scans when they reach a region boundary. - /// The default keeps existing `PdClient` implementations source-compatible; - /// clients that do not support predecessor lookup report `Unimplemented`. - async fn prev_region_for_key(&self, _key: &Key) -> Result { - Err(Error::Unimplemented) - } + async fn prev_region_for_key(&self, key: &Key) -> Result; /// In transactional API, the returned region is decoded (keys in raw format) async fn region_for_id(&self, id: RegionId) -> Result; diff --git a/src/pd/retry.rs b/src/pd/retry.rs index a6fe8cb71..ab58bf64c 100644 --- a/src/pd/retry.rs +++ b/src/pd/retry.rs @@ -37,14 +37,7 @@ pub trait RetryClientTrait { // It does not know about encoding. Caller should take care of it. async fn get_region(self: Arc, key: Vec) -> Result; - async fn get_prev_region(self: Arc, _key: Vec) -> Result - where - Self: Send + Sync, - { - // Keep this default for compatibility with custom retry clients that - // predate predecessor-region lookup. - Err(Error::Unimplemented) - } + async fn get_prev_region(self: Arc, key: Vec) -> Result; async fn get_region_by_id(self: Arc, region_id: RegionId) -> Result; diff --git a/src/request/mod.rs b/src/request/mod.rs index 4cac6c506..c50701122 100644 --- a/src/request/mod.rs +++ b/src/request/mod.rs @@ -293,6 +293,10 @@ mod test { Ok(Self::region()) } + async fn prev_region_for_key(&self, _key: &Key) -> Result { + Err(Error::Unimplemented) + } + async fn region_for_id(&self, id: RegionId) -> Result { match id { 1 => self.region_for_key(&Key::EMPTY).await, @@ -576,6 +580,10 @@ mod test { Ok(Self::region()) } + async fn prev_region_for_key(&self, _key: &Key) -> Result { + Err(Error::Unimplemented) + } + async fn region_for_id(&self, id: RegionId) -> Result { match id { 1 => Ok(Self::region()), diff --git a/src/transaction/transaction/scanner.rs b/src/transaction/transaction/scanner.rs index 67959f30d..a08f5436d 100644 --- a/src/transaction/transaction/scanner.rs +++ b/src/transaction/transaction/scanner.rs @@ -620,6 +620,10 @@ mod tests { } } + async fn prev_region_for_key(&self, _key: &Key) -> crate::Result { + Err(crate::Error::Unimplemented) + } + async fn region_for_id(&self, id: RegionId) -> crate::Result { match id { 10 => Ok(Self::unsplit_region()), From b4ff3d7bf42ea71ee39696967686d8c021c426d4 Mon Sep 17 00:00:00 2001 From: tianyuan Date: Fri, 30 Oct 2026 10:01:31 +0800 Subject: [PATCH 06/12] refactor(pd): centralize predecessor region lookup Keep cache read-through behavior inside RegionCache and share region RPC request handling between current and predecessor lookups. Signed-off-by: tianyuan --- src/pd/client.rs | 9 +------ src/pd/cluster.rs | 26 +++++++++++++++--- src/region_cache.rs | 66 +++++++++++++++++++++++++-------------------- 3 files changed, 61 insertions(+), 40 deletions(-) diff --git a/src/pd/client.rs b/src/pd/client.rs index 50355f045..70394e4f8 100644 --- a/src/pd/client.rs +++ b/src/pd/client.rs @@ -255,14 +255,7 @@ impl PdClient for PdRpcClient { key.clone() }; - if let Some(region) = self.region_cache.get_prev_region_by_key(&key).await { - return Self::decode_region(region, enable_codec); - } - - let region = self - .region_cache - .read_through_prev_region_by_key(key) - .await?; + let region = self.region_cache.get_prev_region_by_key(&key).await?; Self::decode_region(region, enable_codec) } diff --git a/src/pd/cluster.rs b/src/pd/cluster.rs index ec30f5526..89045ba99 100644 --- a/src/pd/cluster.rs +++ b/src/pd/cluster.rs @@ -41,6 +41,11 @@ macro_rules! pd_request { }}; } +enum RegionRequestKind { + Current, + Previous, +} + // These methods make a single attempt to make a request. impl Cluster { pub async fn get_region( @@ -50,7 +55,8 @@ impl Cluster { ) -> Result { let mut req = pd_request!(self.id, pdpb::GetRegionRequest); req.region_key = key; - req.send(&mut self.client, timeout).await + self.send_region_request(req, timeout, RegionRequestKind::Current) + .await } pub async fn get_prev_region( @@ -60,9 +66,23 @@ impl Cluster { ) -> Result { let mut req = pd_request!(self.id, pdpb::GetRegionRequest); req.region_key = key; - let mut req = req.into_request(); + self.send_region_request(req, timeout, RegionRequestKind::Previous) + .await + } + + async fn send_region_request( + &mut self, + request: pdpb::GetRegionRequest, + timeout: Duration, + kind: RegionRequestKind, + ) -> Result { + let mut req = request.into_request(); req.set_timeout(timeout); - let response = self.client.get_prev_region(req).await?.into_inner(); + let response = match kind { + RegionRequestKind::Current => self.client.get_region(req).await?, + RegionRequestKind::Previous => self.client.get_prev_region(req).await?, + } + .into_inner(); if let Some(err) = &response .header .as_ref() diff --git a/src/region_cache.rs b/src/region_cache.rs index 675dec8e7..0ecc2116c 100644 --- a/src/region_cache.rs +++ b/src/region_cache.rs @@ -94,20 +94,24 @@ impl RegionCache { self.read_through_region_by_key(key.clone()).await } - /// Return a cached predecessor whose end key is exactly `key`. - /// - /// A matching boundary is safe to use for the common case and avoids a PD - /// round trip. Callers still fall back to a forced read when the predecessor - /// is absent; region errors invalidate stale entries and trigger a refresh. - pub async fn get_prev_region_by_key(&self, key: &Key) -> Option { - let region_cache_guard = self.region_cache.read().await; - region_cache_guard - .key_to_ver_id - .range::(..key) - .next_back() - .and_then(|(_, ver_id)| region_cache_guard.ver_id_to_region.get(ver_id)) - .filter(|region| region.end_key() == key.clone()) - .cloned() + // Retrieve the cached predecessor by key. If there is no exact boundary, + // query PD and update the cache. + pub async fn get_prev_region_by_key(&self, key: &Key) -> Result { + let cached_region = { + let region_cache_guard = self.region_cache.read().await; + region_cache_guard + .key_to_ver_id + .range::(..key) + .next_back() + .and_then(|(_, ver_id)| region_cache_guard.ver_id_to_region.get(ver_id)) + .filter(|region| region.end_key() == key.clone() && region.leader.is_some()) + .cloned() + }; + + match cached_region { + Some(region) => Ok(region), + None => self.read_through_prev_region_by_key(key.clone()).await, + } } // Retrieve cache entry by RegionId. If there's no entry, query PD and update cache. @@ -156,10 +160,7 @@ impl RegionCache { /// Force read through (query from PD) for the region immediately before /// the region containing `key`. - pub async fn read_through_prev_region_by_key(&self, key: Key) -> Result - where - C: Send + Sync, - { + async fn read_through_prev_region_by_key(&self, key: Key) -> Result { let mut region = self .inner_client .clone() @@ -592,26 +593,33 @@ mod test { } #[tokio::test] - async fn test_get_prev_region_by_key_uses_exact_cached_boundary() { + async fn test_get_prev_region_by_key_reads_cache_then_pd() -> Result<()> { let retry_client = Arc::new(MockRetryClient::default()); - let cache = RegionCache::new(retry_client); - let region1 = region(1, vec![], vec![10]); - let region2 = region(2, vec![10], vec![20]); + let cache = RegionCache::new(retry_client.clone()); + let mut region1 = region(1, vec![], vec![10]); + region1.leader = Some(metapb::Peer { + store_id: 1, + ..Default::default() + }); + let mut region2 = region(2, vec![10], vec![20]); + region2.leader = Some(metapb::Peer { + store_id: 2, + ..Default::default() + }); cache.add_region(region1).await; cache.add_region(region2.clone()).await; assert_eq!( - cache - .get_prev_region_by_key(&vec![20].into()) - .await - .map(|region| region.id()), - Some(region2.id()) + cache.get_prev_region_by_key(&vec![20].into()).await?.id(), + region2.id() ); + assert_eq!(retry_client.get_region_count.load(SeqCst), 0); assert!(cache .get_prev_region_by_key(&vec![15].into()) .await - .is_none()); - assert!(cache.get_prev_region_by_key(&Key::EMPTY).await.is_none()); + .is_err()); + assert!(cache.get_prev_region_by_key(&Key::EMPTY).await.is_err()); + Ok(()) } #[tokio::test] From afae5f83d04380f585c8b74e12ef10312214d31d Mon Sep 17 00:00:00 2001 From: tianyuan Date: Sat, 31 Oct 2026 20:50:26 +0800 Subject: [PATCH 07/12] fix(raw): reload invalidated reverse scan regions Signed-off-by: tianyuan --- src/mock.rs | 15 ++++++ src/raw/client.rs | 127 +++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 141 insertions(+), 1 deletion(-) diff --git a/src/mock.rs b/src/mock.rs index 446aa3ace..2a0fc49b3 100644 --- a/src/mock.rs +++ b/src/mock.rs @@ -86,6 +86,10 @@ pub struct MockPdClient { #[new(default)] region_for_key_hook: Option Result + Send + Sync + 'static>>, + /// Optional override for `region_for_id`, e.g. after a Region is removed. + #[new(default)] + region_for_id_hook: + Option Result + Send + Sync + 'static>>, /// Optional override for `prev_region_for_key`. #[new(default)] prev_region_for_key_hook: @@ -152,6 +156,14 @@ impl MockPdClient { self } + pub fn with_region_for_id_hook(mut self, hook: F) -> MockPdClient + where + F: Fn(RegionId) -> Result + Send + Sync + 'static, + { + self.region_for_id_hook = Some(Arc::new(hook)); + self + } + pub fn with_update_leader_hook(mut self, hook: F) -> MockPdClient where F: Fn(RegionVerId, metapb::Peer) -> Result<()> + Send + Sync + 'static, @@ -269,6 +281,9 @@ impl PdClient for MockPdClient { } async fn region_for_id(&self, id: RegionId) -> Result { + if let Some(hook) = &self.region_for_id_hook { + return hook(id); + } match id { 1 => Ok(Self::region1()), 2 => Ok(Self::region2()), diff --git a/src/raw/client.rs b/src/raw/client.rs index 11dfd19bd..a512d5f92 100644 --- a/src/raw/client.rs +++ b/src/raw/client.rs @@ -519,6 +519,8 @@ impl Client { /// If you want to include the endKey or exclude the startKey, push a '\0' to the key. /// An unbounded upper bound is supported by locating the final Region before /// traversing Regions backwards toward the lower bound. + /// Without a keyspace prefix, locating that Region walks Region boundaries + /// from the lower bound and may require a PD lookup for each uncached Region. /// # Examples /// ```rust,no_run /// # use tikv_client::{KvPair, Config, RawClient, IntoOwnedRange}; @@ -765,6 +767,9 @@ impl Client { max_limit: MAX_RAW_KV_SCAN_LIMIT, }); } + if limit == 0 { + return Ok(Vec::new()); + } let backoff = DEFAULT_STORE_BACKOFF; let range = range.into().encode_keyspace(self.keyspace, KeyMode::Raw); let mut result = Vec::new(); @@ -918,7 +923,16 @@ impl Client { .await?; if status { if scan_args.reverse { - region_override = Some(region.clone()); + // Only a known-leader correction preserves the + // Region metadata. EpochNotMatch may have removed + // this Region ID, so resolve it by key again. + if err.not_leader.as_ref().is_some_and(|e| e.leader.is_some()) { + region_override = Some(region.clone()); + } else if scan_args.reverse_unbounded { + region_override = Some( + self.last_region_for_key(&scan_args.range_start).await?, + ); + } } continue; } else if let Some(duration) = scan_args.backoff.next_delay_duration() { @@ -1026,6 +1040,7 @@ mod tests { use super::*; use crate::mock::MockKvClient; use crate::mock::MockPdClient; + use crate::proto::errorpb; use crate::proto::kvrpcpb; use crate::Result; @@ -1132,6 +1147,32 @@ mod tests { Ok(()) } + #[tokio::test] + async fn reverse_scan_with_zero_limit_does_not_resolve_a_region() -> Result<()> { + let lookups = Arc::new(AtomicUsize::new(0)); + let lookup_count = lookups.clone(); + let pd_client = Arc::new( + MockPdClient::new(MockKvClient::with_dispatch_hook(|_: &dyn Any| { + panic!("zero-limit scan must not dispatch") + })) + .with_region_for_key_hook(move |_| { + lookup_count.fetch_add(1, Ordering::SeqCst); + panic!("zero-limit scan must not resolve a region") + }), + ); + let client = Client { + rpc: pd_client, + cf: None, + backoff: DEFAULT_REGION_BACKOFF, + atomic: false, + keyspace: Keyspace::Disable, + }; + + assert!(client.scan_reverse(vec![1].., 0).await?.is_empty()); + assert_eq!(lookups.load(Ordering::SeqCst), 0); + Ok(()) + } + #[tokio::test] async fn reverse_scan_unbounded_upper_traverses_from_final_region() -> Result<()> { let requests = Arc::new(Mutex::new(Vec::<(Vec, Vec)>::new())); @@ -1240,6 +1281,90 @@ mod tests { Ok(()) } + #[tokio::test] + async fn reverse_scan_reloads_region_after_epoch_not_match() -> Result<()> { + let refreshed = Arc::new(AtomicBool::new(false)); + let dispatch_count = Arc::new(AtomicUsize::new(0)); + let region_refreshed = refreshed.clone(); + let request_count = dispatch_count.clone(); + let region_id_lookups = Arc::new(AtomicUsize::new(0)); + let region_id_lookup_count = region_id_lookups.clone(); + let mut stale_region = MockPdClient::region3(); + stale_region.region.region_epoch.as_mut().unwrap().version = 0; + let mut refreshed_region = stale_region.clone(); + refreshed_region.region.id = 4; + refreshed_region.region.start_key = vec![10]; + refreshed_region.region.end_key = vec![]; + refreshed_region + .region + .region_epoch + .as_mut() + .unwrap() + .version = 1; + let refreshed_for_lookup = refreshed_region.clone(); + let refreshed_for_id = refreshed_region.clone(); + let stale_for_id = stale_region.clone(); + let pd_client = Arc::new( + MockPdClient::new(MockKvClient::with_dispatch_hook(move |req: &dyn Any| { + let req = req.downcast_ref::().unwrap(); + assert!(req.reverse); + if request_count.fetch_add(1, Ordering::SeqCst) == 0 { + Ok(Box::new(kvrpcpb::RawScanResponse { + region_error: Some(errorpb::Error { + epoch_not_match: Some(errorpb::EpochNotMatch { + current_regions: vec![], + }), + ..Default::default() + }), + ..Default::default() + }) as Box) + } else { + assert_eq!(req.end_key, vec![10]); + Ok(Box::new(kvrpcpb::RawScanResponse { + kvs: vec![kvrpcpb::KvPair { + key: vec![11], + value: vec![42], + ..Default::default() + }], + ..Default::default() + }) as Box) + } + })) + .with_region_for_key_hook(move |_| { + if region_refreshed.load(Ordering::SeqCst) { + Ok(refreshed_for_lookup.clone()) + } else { + Ok(stale_region.clone()) + } + }) + .with_region_for_id_hook(move |id| { + if id == refreshed_for_id.id() { + Ok(refreshed_for_id.clone()) + } else if id == stale_for_id.id() + && region_id_lookup_count.fetch_add(1, Ordering::SeqCst) == 0 + { + Ok(stale_for_id.clone()) + } else { + Err(Error::RegionNotFoundInResponse { region_id: id }) + } + }) + .with_invalidate_region_hook(move |_| { + refreshed.store(true, Ordering::SeqCst); + }), + ); + let client = Client { + rpc: pd_client, + cf: None, + backoff: DEFAULT_REGION_BACKOFF, + atomic: false, + keyspace: Keyspace::Disable, + }; + + assert_eq!(client.scan_reverse(vec![1]..vec![255], 1).await?.len(), 1); + assert_eq!(dispatch_count.load(Ordering::SeqCst), 2); + Ok(()) + } + #[rstest::rstest] #[case::forward(false)] #[case::reverse(true)] From 4daca6364230a4eea552ff6efe34d567ef6b641e Mon Sep 17 00:00:00 2001 From: tianyuan Date: Sat, 31 Oct 2026 21:49:44 +0800 Subject: [PATCH 08/12] fix(raw): bound reverse scan boundary retries Signed-off-by: tianyuan --- src/raw/client.rs | 80 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 79 insertions(+), 1 deletion(-) diff --git a/src/raw/client.rs b/src/raw/client.rs index a512d5f92..11a0e3be5 100644 --- a/src/raw/client.rs +++ b/src/raw/client.rs @@ -33,6 +33,7 @@ use crate::Result; use crate::Value; const MAX_RAW_KV_SCAN_LIMIT: u32 = 10240; +const MAX_REVERSE_SCAN_BOUNDARY_RETRIES: usize = 10; /// The TiKV raw `Client` is used to interact with TiKV using raw requests. /// @@ -844,6 +845,7 @@ impl Client { async fn last_region_for_key(&self, key: &Key) -> Result { let mut region = self.rpc.clone().region_for_key(key).await?; + let mut boundary_retries = 0; loop { let end_key = region.end_key(); if end_key.is_empty() { @@ -852,11 +854,20 @@ impl Client { let next_region = self.rpc.clone().region_for_key(&end_key).await?; if next_region.start_key() != end_key { + if boundary_retries >= MAX_REVERSE_SCAN_BOUNDARY_RETRIES { + return Err(Error::InternalError { + message: + "failed to resolve the final region after exhausting boundary retries" + .to_owned(), + }); + } + boundary_retries += 1; self.rpc.invalidate_region_cache(region.ver_id()).await; self.rpc.invalidate_region_cache(next_region.ver_id()).await; region = self.rpc.clone().region_for_key(key).await?; continue; } + boundary_retries = 0; region = next_region; } } @@ -867,6 +878,7 @@ impl Client { ) -> Result<(Option, Key)> { let current_key = scan_args.current_key; let mut region_override = scan_args.initial_region.take(); + let mut boundary_retries = 0; loop { let region = if let Some(region) = region_override.take() { region @@ -874,11 +886,21 @@ impl Client { let region = self.rpc.clone().region_for_key(¤t_key).await?; if !current_key.is_empty() && region.start_key() == current_key { let previous = match self.rpc.clone().prev_region_for_key(¤t_key).await { - Ok(previous) if previous.end_key() == current_key => previous, + Ok(previous) if previous.end_key() == current_key => { + boundary_retries = 0; + previous + } Ok(_) | Err(Error::RegionForKeyNotFound { .. }) => { // The cached containing region is stale (for example, // after a merge), so the predecessor no longer ends // at this cursor. Drop it and resolve the cursor again. + if boundary_retries >= MAX_REVERSE_SCAN_BOUNDARY_RETRIES { + return Err(Error::InternalError { + message: "failed to resolve the predecessor region after exhausting boundary retries" + .to_owned(), + }); + } + boundary_retries += 1; self.rpc.invalidate_region_cache(region.ver_id()).await; continue; } @@ -886,9 +908,11 @@ impl Client { }; previous } else { + boundary_retries = 0; region } } else { + boundary_retries = 0; self.rpc.clone().region_for_key(¤t_key).await? }; let store = self.rpc.clone().store_for_id(region.id()).await?; @@ -1173,6 +1197,60 @@ mod tests { Ok(()) } + #[tokio::test] + async fn reverse_scan_stops_after_repeated_stale_boundaries() -> Result<()> { + let pd_client = Arc::new( + MockPdClient::new(MockKvClient::with_dispatch_hook(|_: &dyn Any| { + panic!("stale boundary must not dispatch") + })) + .with_region_for_key_hook(|_| Ok(MockPdClient::region2())) + .with_prev_region_for_key_hook(|_| Ok(MockPdClient::region2())), + ); + let client = Client { + rpc: pd_client, + cf: None, + backoff: Backoff::no_backoff(), + atomic: false, + keyspace: Keyspace::Disable, + }; + + assert!(matches!( + client.scan_reverse(vec![1]..vec![10], 1).await, + Err(Error::InternalError { .. }) + )); + Ok(()) + } + + #[tokio::test] + async fn reverse_scan_stops_after_repeated_final_region_boundaries() -> Result<()> { + let pd_client = Arc::new( + MockPdClient::new(MockKvClient::with_dispatch_hook(|_: &dyn Any| { + panic!("stale boundary must not dispatch") + })) + .with_region_for_key_hook(|key| { + let key_bytes: &[u8] = key.into(); + if key_bytes == [1] { + Ok(MockPdClient::region1()) + } else { + Ok(MockPdClient::region3()) + } + }), + ); + let client = Client { + rpc: pd_client, + cf: None, + backoff: Backoff::no_backoff(), + atomic: false, + keyspace: Keyspace::Disable, + }; + + assert!(matches!( + client.scan_reverse(vec![1].., 1).await, + Err(Error::InternalError { .. }) + )); + Ok(()) + } + #[tokio::test] async fn reverse_scan_unbounded_upper_traverses_from_final_region() -> Result<()> { let requests = Arc::new(Mutex::new(Vec::<(Vec, Vec)>::new())); From 46130faf9cdec056927e4f821314639d657296b7 Mon Sep 17 00:00:00 2001 From: tianyuan Date: Mon, 2 Nov 2026 09:00:14 +0800 Subject: [PATCH 09/12] fix(raw): batch lookup final reverse scan region Signed-off-by: tianyuan --- src/pd/client.rs | 65 +++++++++++++++++++++++++++++++++++++++ src/pd/cluster.rs | 30 ++++++++++++++++++ src/pd/retry.rs | 36 ++++++++++++++++++++++ src/raw/client.rs | 40 +++++------------------- src/region_cache.rs | 75 +++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 213 insertions(+), 33 deletions(-) diff --git a/src/pd/client.rs b/src/pd/client.rs index 70394e4f8..3fd476c1c 100644 --- a/src/pd/client.rs +++ b/src/pd/client.rs @@ -28,11 +28,14 @@ use crate::store::TikvConnect; use crate::store::{KvClient, Store}; use crate::BoundRange; use crate::Config; +use crate::Error; use crate::Key; use crate::Result; use crate::SecurityManager; use crate::Timestamp; +const MAX_REGION_BOUNDARY_RETRIES: usize = 10; + /// The PdClient handles all the encoding stuff. /// /// Raw APIs does not require encoding/decoding at all. @@ -65,6 +68,14 @@ pub trait PdClient: Send + Sync + 'static { /// This is used by reverse scans when they reach a region boundary. async fn prev_region_for_key(&self, key: &Key) -> Result; + /// Return the final region at or after `key`. + /// + /// Implementations backed by PD can override this with a batch region scan. The default + /// implementation keeps compatibility with other clients by walking region boundaries. + async fn last_region_for_key(&self, key: &Key) -> Result { + walk_to_last_region(self, key).await + } + /// In transactional API, the returned region is decoded (keys in raw format) async fn region_for_id(&self, id: RegionId) -> Result; @@ -259,6 +270,29 @@ impl PdClient for PdRpcClient { Self::decode_region(region, enable_codec) } + async fn last_region_for_key(&self, key: &Key) -> Result { + let enable_codec = self.enable_codec; + let encoded_key = if enable_codec { + key.to_encoded() + } else { + key.clone() + }; + + let region = match self + .region_cache + .read_through_last_region_by_key(encoded_key) + .await + { + Ok(region) => region, + Err(Error::GrpcAPI(status)) if status.code() == tonic::Code::Unimplemented => { + walk_to_last_region(self, key).await? + } + Err(Error::Unimplemented) => walk_to_last_region(self, key).await?, + Err(error) => return Err(error), + }; + Self::decode_region(region, enable_codec) + } + async fn region_for_id(&self, id: RegionId) -> Result { let region = self.region_cache.get_region_by_id(id).await?; Self::decode_region(region, self.enable_codec) @@ -302,6 +336,37 @@ impl PdClient for PdRpcClient { } } +async fn walk_to_last_region( + client: &P, + key: &Key, +) -> Result { + let mut region = client.region_for_key(key).await?; + let mut boundary_retries = 0; + loop { + let end_key = region.end_key(); + if end_key.is_empty() { + return Ok(region); + } + + let next_region = client.region_for_key(&end_key).await?; + if next_region.start_key() != end_key { + if boundary_retries >= MAX_REGION_BOUNDARY_RETRIES { + return Err(Error::InternalError { + message: "failed to resolve the final region after exhausting boundary retries" + .to_owned(), + }); + } + boundary_retries += 1; + client.invalidate_region_cache(region.ver_id()).await; + client.invalidate_region_cache(next_region.ver_id()).await; + region = client.region_for_key(key).await?; + continue; + } + boundary_retries = 0; + region = next_region; + } +} + impl PdRpcClient { pub async fn connect( pd_endpoints: &[String], diff --git a/src/pd/cluster.rs b/src/pd/cluster.rs index 89045ba99..65c1314b1 100644 --- a/src/pd/cluster.rs +++ b/src/pd/cluster.rs @@ -70,6 +70,20 @@ impl Cluster { .await } + pub async fn batch_scan_regions( + &mut self, + start_key: Vec, + timeout: Duration, + ) -> Result { + let mut req = pd_request!(self.id, pdpb::BatchScanRegionsRequest); + req.ranges.push(pdpb::KeyRange { + start_key, + ..Default::default() + }); + req.contain_all_key_range = true; + req.send(&mut self.client, timeout).await + } + async fn send_region_request( &mut self, request: pdpb::GetRegionRequest, @@ -418,6 +432,16 @@ impl PdMessage for pdpb::GetRegionRequest { } } +#[async_trait] +impl PdMessage for pdpb::BatchScanRegionsRequest { + type Client = pdpb::pd_client::PdClient; + type Response = pdpb::BatchScanRegionsResponse; + + async fn rpc(req: Request, client: &mut Self::Client) -> GrpcResult { + Ok(client.batch_scan_regions(req).await?.into_inner()) + } +} + #[async_trait] impl PdMessage for pdpb::GetRegionByIdRequest { type Client = pdpb::pd_client::PdClient; @@ -484,6 +508,12 @@ impl PdResponse for pdpb::GetRegionResponse { } } +impl PdResponse for pdpb::BatchScanRegionsResponse { + fn header(&self) -> &pdpb::ResponseHeader { + self.header.as_ref().unwrap() + } +} + impl PdResponse for pdpb::GetAllStoresResponse { fn header(&self) -> &pdpb::ResponseHeader { self.header.as_ref().unwrap() diff --git a/src/pd/retry.rs b/src/pd/retry.rs index ab58bf64c..4c647362a 100644 --- a/src/pd/retry.rs +++ b/src/pd/retry.rs @@ -39,6 +39,15 @@ pub trait RetryClientTrait { async fn get_prev_region(self: Arc, key: Vec) -> Result; + /// Return all regions from `start_key` to the end of the keyspace in one PD request. + async fn batch_scan_regions( + self: Arc, + start_key: Vec, + ) -> Result> { + let _ = start_key; + Err(Error::Unimplemented) + } + async fn get_region_by_id(self: Arc, region_id: RegionId) -> Result; async fn get_store(self: Arc, id: StoreId) -> Result; @@ -175,6 +184,26 @@ impl RetryClientTrait for RetryClient { }) } + async fn batch_scan_regions( + self: Arc, + start_key: Vec, + ) -> Result> { + retry_mut!(self, "batch_scan_regions", |cluster| { + let start_key = start_key.clone(); + async { + cluster + .batch_scan_regions(start_key, self.timeout) + .await + .and_then(|resp| { + resp.regions + .into_iter() + .map(region_from_batch_scan_response) + .collect() + }) + } + }) + } + async fn get_region_by_id(self: Arc, region_id: RegionId) -> Result { retry_mut!(self, "get_region_by_id", |cluster| async { cluster @@ -240,6 +269,13 @@ fn region_from_response( Ok(RegionWithLeader::new(region, resp.leader.take())) } +fn region_from_batch_scan_response(resp: pdpb::Region) -> Result { + let region = resp.region.ok_or_else(|| Error::InternalError { + message: "PD returned a batch-scanned region without metadata".to_owned(), + })?; + Ok(RegionWithLeader::new(region, resp.leader)) +} + // A node-like thing that can be connected to. #[async_trait] trait Reconnect { diff --git a/src/raw/client.rs b/src/raw/client.rs index 11a0e3be5..336ca6985 100644 --- a/src/raw/client.rs +++ b/src/raw/client.rs @@ -789,7 +789,7 @@ impl Client { range_start.clone() }; let mut initial_region = if reverse_unbounded { - Some(self.last_region_for_key(&range_start).await?) + Some(self.rpc.last_region_for_key(&range_start).await?) } else { None }; @@ -843,35 +843,6 @@ impl Client { Ok(result) } - async fn last_region_for_key(&self, key: &Key) -> Result { - let mut region = self.rpc.clone().region_for_key(key).await?; - let mut boundary_retries = 0; - loop { - let end_key = region.end_key(); - if end_key.is_empty() { - return Ok(region); - } - - let next_region = self.rpc.clone().region_for_key(&end_key).await?; - if next_region.start_key() != end_key { - if boundary_retries >= MAX_REVERSE_SCAN_BOUNDARY_RETRIES { - return Err(Error::InternalError { - message: - "failed to resolve the final region after exhausting boundary retries" - .to_owned(), - }); - } - boundary_retries += 1; - self.rpc.invalidate_region_cache(region.ver_id()).await; - self.rpc.invalidate_region_cache(next_region.ver_id()).await; - region = self.rpc.clone().region_for_key(key).await?; - continue; - } - boundary_retries = 0; - region = next_region; - } - } - async fn retryable_scan( &self, mut scan_args: ScanInnerArgs, @@ -954,15 +925,18 @@ impl Client { region_override = Some(region.clone()); } else if scan_args.reverse_unbounded { region_override = Some( - self.last_region_for_key(&scan_args.range_start).await?, + self.rpc + .last_region_for_key(&scan_args.range_start) + .await?, ); } } continue; } else if let Some(duration) = scan_args.backoff.next_delay_duration() { if scan_args.reverse_unbounded { - region_override = - Some(self.last_region_for_key(&scan_args.range_start).await?); + region_override = Some( + self.rpc.last_region_for_key(&scan_args.range_start).await?, + ); } sleep(duration).await; continue; diff --git a/src/region_cache.rs b/src/region_cache.rs index 0ecc2116c..73961c8a4 100644 --- a/src/region_cache.rs +++ b/src/region_cache.rs @@ -158,6 +158,40 @@ impl RegionCache { Ok(region) } + /// Force a batch read through from `key` to the end of the keyspace and return the final + /// region. This avoids issuing one PD request per region when an unbounded reverse scan needs + /// to locate the final region. + pub async fn read_through_last_region_by_key(&self, key: Key) -> Result + where + C: Send + Sync, + { + let key_bytes: Vec = key.clone().into(); + let mut regions = self + .inner_client + .clone() + .batch_scan_regions(key_bytes.clone()) + .await?; + regions.sort_by_key(|region| region.start_key()); + let last_region = regions + .last() + .cloned() + .ok_or(Error::RegionForKeyNotFound { key: key_bytes })?; + for mut region in regions { + let cached_leader = { + let cache = self.region_cache.read().await; + cache + .ver_id_to_region + .get(®ion.ver_id()) + .and_then(|cached| cached.leader.clone()) + }; + if cached_leader.is_some() { + region.leader = cached_leader; + } + self.add_region(region).await; + } + Ok(last_region) + } + /// Force read through (query from PD) for the region immediately before /// the region containing `key`. async fn read_through_prev_region_by_key(&self, key: Key) -> Result { @@ -386,6 +420,24 @@ mod test { .ok_or_else(|| Error::RegionForKeyNotFound { key }) } + async fn batch_scan_regions( + self: Arc, + start_key: Vec, + ) -> Result> { + self.get_region_count.fetch_add(1, SeqCst); + let start_key: Key = start_key.into(); + let mut regions = self + .regions + .lock() + .await + .values() + .filter(|region| region.end_key().is_empty() || region.end_key() > start_key) + .cloned() + .collect::>(); + regions.sort_by_key(|region| region.start_key()); + Ok(regions) + } + async fn get_region_by_id( self: Arc, region_id: crate::region::RegionId, @@ -622,6 +674,29 @@ mod test { Ok(()) } + #[tokio::test] + async fn test_last_region_by_key_uses_one_batch_pd_request() -> Result<()> { + let retry_client = Arc::new(MockRetryClient::default()); + let cache = RegionCache::new(retry_client.clone()); + retry_client.regions.lock().await.extend([ + (1, region(1, vec![], vec![10])), + (2, region(2, vec![10], vec![20])), + (3, region(3, vec![20], vec![])), + ]); + + assert_eq!( + cache + .read_through_last_region_by_key(vec![1].into()) + .await? + .id(), + 3 + ); + assert_eq!(retry_client.get_region_count.load(SeqCst), 1); + assert_eq!(cache.get_region_by_id(2).await?.id(), 2); + assert_eq!(retry_client.get_region_count.load(SeqCst), 1); + Ok(()) + } + #[tokio::test] async fn test_prev_region_preserves_cached_leader() -> Result<()> { let retry_client = Arc::new(MockRetryClient::default()); From edfc5994a6fd165601d6e22a2d604385f5194780 Mon Sep 17 00:00:00 2001 From: tianyuan Date: Mon, 2 Nov 2026 09:03:11 +0800 Subject: [PATCH 10/12] fix(pd): preserve final region leader from cache Signed-off-by: tianyuan --- src/region_cache.rs | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/src/region_cache.rs b/src/region_cache.rs index 73961c8a4..005cc88f6 100644 --- a/src/region_cache.rs +++ b/src/region_cache.rs @@ -172,10 +172,11 @@ impl RegionCache { .batch_scan_regions(key_bytes.clone()) .await?; regions.sort_by_key(|region| region.start_key()); - let last_region = regions + let last_region_ver_id = regions .last() - .cloned() + .map(RegionWithLeader::ver_id) .ok_or(Error::RegionForKeyNotFound { key: key_bytes })?; + let mut last_region = None; for mut region in regions { let cached_leader = { let cache = self.region_cache.read().await; @@ -187,9 +188,12 @@ impl RegionCache { if cached_leader.is_some() { region.leader = cached_leader; } + if region.ver_id() == last_region_ver_id { + last_region = Some(region.clone()); + } self.add_region(region).await; } - Ok(last_region) + Ok(last_region.expect("batch scan returned its final region")) } /// Force read through (query from PD) for the region immediately before From a1415bbedf05afd3f1c4926c2c74643f6ebf73b6 Mon Sep 17 00:00:00 2001 From: tianyuan Date: Mon, 2 Nov 2026 11:45:30 +0800 Subject: [PATCH 11/12] fix(raw): bound region lookup pages and scan retries Signed-off-by: tianyuan --- src/pd/client.rs | 4 +- src/pd/cluster.rs | 5 +- src/pd/retry.rs | 11 ++-- src/raw/client.rs | 93 +++++++++++++++++++++------- src/region_cache.rs | 148 +++++++++++++++++++++++++++++++++++++------- 5 files changed, 206 insertions(+), 55 deletions(-) diff --git a/src/pd/client.rs b/src/pd/client.rs index 3fd476c1c..fe4bdb219 100644 --- a/src/pd/client.rs +++ b/src/pd/client.rs @@ -285,9 +285,9 @@ impl PdClient for PdRpcClient { { Ok(region) => region, Err(Error::GrpcAPI(status)) if status.code() == tonic::Code::Unimplemented => { - walk_to_last_region(self, key).await? + return walk_to_last_region(self, key).await; } - Err(Error::Unimplemented) => walk_to_last_region(self, key).await?, + Err(Error::Unimplemented) => return walk_to_last_region(self, key).await, Err(error) => return Err(error), }; Self::decode_region(region, enable_codec) diff --git a/src/pd/cluster.rs b/src/pd/cluster.rs index 65c1314b1..fb9c14383 100644 --- a/src/pd/cluster.rs +++ b/src/pd/cluster.rs @@ -73,6 +73,7 @@ impl Cluster { pub async fn batch_scan_regions( &mut self, start_key: Vec, + limit: i32, timeout: Duration, ) -> Result { let mut req = pd_request!(self.id, pdpb::BatchScanRegionsRequest); @@ -80,7 +81,9 @@ impl Cluster { start_key, ..Default::default() }); - req.contain_all_key_range = true; + req.limit = limit; + // A positive limit pages the range; PD may return only a prefix of the requested range. + req.contain_all_key_range = false; req.send(&mut self.client, timeout).await } diff --git a/src/pd/retry.rs b/src/pd/retry.rs index 4c647362a..e474975f2 100644 --- a/src/pd/retry.rs +++ b/src/pd/retry.rs @@ -39,14 +39,12 @@ pub trait RetryClientTrait { async fn get_prev_region(self: Arc, key: Vec) -> Result; - /// Return all regions from `start_key` to the end of the keyspace in one PD request. + /// Return up to `limit` regions starting at `start_key` in one PD request. async fn batch_scan_regions( self: Arc, start_key: Vec, - ) -> Result> { - let _ = start_key; - Err(Error::Unimplemented) - } + limit: i32, + ) -> Result>; async fn get_region_by_id(self: Arc, region_id: RegionId) -> Result; @@ -187,12 +185,13 @@ impl RetryClientTrait for RetryClient { async fn batch_scan_regions( self: Arc, start_key: Vec, + limit: i32, ) -> Result> { retry_mut!(self, "batch_scan_regions", |cluster| { let start_key = start_key.clone(); async { cluster - .batch_scan_regions(start_key, self.timeout) + .batch_scan_regions(start_key, limit, self.timeout) .await .and_then(|resp| { resp.regions diff --git a/src/raw/client.rs b/src/raw/client.rs index 336ca6985..d7b811b3a 100644 --- a/src/raw/client.rs +++ b/src/raw/client.rs @@ -519,9 +519,9 @@ impl Client { /// The returned keys are in reversed lexicographical order. /// If you want to include the endKey or exclude the startKey, push a '\0' to the key. /// An unbounded upper bound is supported by locating the final Region before - /// traversing Regions backwards toward the lower bound. - /// Without a keyspace prefix, locating that Region walks Region boundaries - /// from the lower bound and may require a PD lookup for each uncached Region. + /// traversing Regions backwards toward the lower bound. The normal path uses + /// paged PD batch-region scans; clients whose PD does not support that RPC + /// fall back to walking Region boundaries from the lower bound. /// # Examples /// ```rust,no_run /// # use tikv_client::{KvPair, Config, RawClient, IntoOwnedRange}; @@ -913,36 +913,31 @@ impl Client { return match resp { Ok(mut r) => { if let Some(err) = r.region_error() { + // Resolved Region errors still consume the retry budget, even + // when a leader correction lets us retry without sleeping. + let Some(duration) = scan_args.backoff.next_delay_duration() else { + return Err(RegionError(Box::new(err))); + }; let status = plan::handle_region_error(self.rpc.clone(), err.clone(), store.clone()) .await?; - if status { - if scan_args.reverse { - // Only a known-leader correction preserves the - // Region metadata. EpochNotMatch may have removed - // this Region ID, so resolve it by key again. - if err.not_leader.as_ref().is_some_and(|e| e.leader.is_some()) { - region_override = Some(region.clone()); - } else if scan_args.reverse_unbounded { - region_override = Some( - self.rpc - .last_region_for_key(&scan_args.range_start) - .await?, - ); - } - } - continue; - } else if let Some(duration) = scan_args.backoff.next_delay_duration() { - if scan_args.reverse_unbounded { + if scan_args.reverse { + // Only a known-leader correction preserves the + // Region metadata. EpochNotMatch may have removed + // this Region ID, so resolve it by key again. + if status && err.not_leader.as_ref().is_some_and(|e| e.leader.is_some()) + { + region_override = Some(region.clone()); + } else if scan_args.reverse_unbounded { region_override = Some( self.rpc.last_region_for_key(&scan_args.range_start).await?, ); } + } + if !status { sleep(duration).await; - continue; - } else { - return Err(RegionError(Box::new(err))); } + continue; } let next_key = if scan_args.reverse { region.start_key() @@ -1417,6 +1412,56 @@ mod tests { Ok(()) } + #[tokio::test] + async fn reverse_scan_bounds_immediate_region_error_retries() -> Result<()> { + let dispatch_count = Arc::new(AtomicUsize::new(0)); + let requests = dispatch_count.clone(); + let pd_client = Arc::new(MockPdClient::new(MockKvClient::with_dispatch_hook( + move |req: &dyn Any| { + assert!(req.downcast_ref::().is_some()); + assert!( + requests.fetch_add(1, Ordering::SeqCst) < 3, + "retry limit exceeded" + ); + Ok(Box::new(kvrpcpb::RawScanResponse { + region_error: Some(errorpb::Error { + epoch_not_match: Some(errorpb::EpochNotMatch { + current_regions: vec![], + }), + ..Default::default() + }), + ..Default::default() + }) as Box) + }, + ))); + let client = Client { + rpc: pd_client, + cf: None, + backoff: DEFAULT_REGION_BACKOFF, + atomic: false, + keyspace: Keyspace::Disable, + }; + + let result = client + .retryable_scan(ScanInnerArgs { + current_key: vec![1].into(), + range_start: vec![1].into(), + range_end: None, + reverse_unbounded: true, + initial_region: Some(MockPdClient::region3()), + limit: 1, + key_only: false, + reverse: true, + backoff: Backoff::no_jitter_backoff(0, 0, 2), + }) + .await; + assert!( + matches!(result, Err(Error::RegionError(error)) if error.epoch_not_match.is_some()) + ); + assert_eq!(dispatch_count.load(Ordering::SeqCst), 3); + Ok(()) + } + #[rstest::rstest] #[case::forward(false)] #[case::reverse(true)] diff --git a/src/region_cache.rs b/src/region_cache.rs index 005cc88f6..5dc1d0990 100644 --- a/src/region_cache.rs +++ b/src/region_cache.rs @@ -23,6 +23,7 @@ use crate::Key; use crate::Result; const MAX_RETRY_WAITING_CONCURRENT_REQUEST: usize = 4; +const BATCH_SCAN_REGIONS_PAGE_SIZE: i32 = 128; struct RegionCacheMap { /// RegionVerID -> Region. It stores the concrete region caches. @@ -158,26 +159,36 @@ impl RegionCache { Ok(region) } - /// Force a batch read through from `key` to the end of the keyspace and return the final - /// region. This avoids issuing one PD request per region when an unbounded reverse scan needs - /// to locate the final region. + /// Find the final region with bounded PD batch scans, caching only that region. + /// Each page starts at the previous page's end key so response memory stays bounded. pub async fn read_through_last_region_by_key(&self, key: Key) -> Result where C: Send + Sync, { - let key_bytes: Vec = key.clone().into(); - let mut regions = self - .inner_client - .clone() - .batch_scan_regions(key_bytes.clone()) - .await?; - regions.sort_by_key(|region| region.start_key()); - let last_region_ver_id = regions - .last() - .map(RegionWithLeader::ver_id) - .ok_or(Error::RegionForKeyNotFound { key: key_bytes })?; - let mut last_region = None; - for mut region in regions { + let mut start_key: Vec = key.into(); + loop { + let regions = self + .inner_client + .clone() + .batch_scan_regions(start_key.clone(), BATCH_SCAN_REGIONS_PAGE_SIZE) + .await?; + let mut region = regions + .into_iter() + .max_by(|a, b| a.region.start_key.cmp(&b.region.start_key)) + .ok_or_else(|| Error::RegionForKeyNotFound { + key: start_key.clone(), + })?; + if !region.region.end_key.is_empty() { + if region.region.end_key <= start_key { + return Err(Error::InternalError { + message: "batch region scan did not advance past the previous page" + .to_owned(), + }); + } + start_key = region.region.end_key; + continue; + } + let cached_leader = { let cache = self.region_cache.read().await; cache @@ -188,12 +199,9 @@ impl RegionCache { if cached_leader.is_some() { region.leader = cached_leader; } - if region.ver_id() == last_region_ver_id { - last_region = Some(region.clone()); - } - self.add_region(region).await; + self.add_region(region.clone()).await; + return Ok(region); } - Ok(last_region.expect("batch scan returned its final region")) } /// Force read through (query from PD) for the region immediately before @@ -368,6 +376,7 @@ mod test { use std::collections::BTreeMap; use std::collections::HashMap; use std::collections::HashSet; + use std::collections::VecDeque; use std::sync::atomic::AtomicU64; use std::sync::atomic::Ordering::SeqCst; use std::sync::Arc; @@ -391,6 +400,7 @@ mod test { struct MockRetryClient { pub regions: Mutex>, pub get_region_count: AtomicU64, + pub batch_scan_responses: Mutex>>, } #[async_trait] @@ -427,8 +437,13 @@ mod test { async fn batch_scan_regions( self: Arc, start_key: Vec, + limit: i32, ) -> Result> { self.get_region_count.fetch_add(1, SeqCst); + assert!(limit > 0, "batch region scans must use a bounded page size"); + if let Some(regions) = self.batch_scan_responses.lock().await.pop_front() { + return Ok(regions); + } let start_key: Key = start_key.into(); let mut regions = self .regions @@ -439,6 +454,7 @@ mod test { .cloned() .collect::>(); regions.sort_by_key(|region| region.start_key()); + regions.truncate(limit as usize); Ok(regions) } @@ -696,8 +712,96 @@ mod test { 3 ); assert_eq!(retry_client.get_region_count.load(SeqCst), 1); - assert_eq!(cache.get_region_by_id(2).await?.id(), 2); + assert_eq!(cache.get_region_by_id(3).await?.id(), 3); assert_eq!(retry_client.get_region_count.load(SeqCst), 1); + assert_eq!(cache.region_cache.read().await.ver_id_to_region.len(), 1); + Ok(()) + } + + #[tokio::test] + async fn test_last_region_by_key_pages_large_region_ranges() -> Result<()> { + let retry_client = Arc::new(MockRetryClient::default()); + let cache = RegionCache::new(retry_client.clone()); + retry_client + .regions + .lock() + .await + .extend((0..=129).map(|id| { + let start_key = vec![id as u8]; + let end_key = if id == 129 { + vec![] + } else { + vec![id as u8 + 1] + }; + (id, region(id, start_key, end_key)) + })); + + assert_eq!( + cache + .read_through_last_region_by_key(vec![1].into()) + .await? + .id(), + 129 + ); + assert_eq!(retry_client.get_region_count.load(SeqCst), 2); + assert_eq!(cache.region_cache.read().await.ver_id_to_region.len(), 1); + Ok(()) + } + + #[tokio::test] + async fn test_last_region_by_key_rejects_incomplete_or_nonadvancing_pages() { + for next_page in [vec![], vec![region(1, vec![], vec![10])]] { + let retry_client = Arc::new(MockRetryClient::default()); + let cache = RegionCache::new(retry_client.clone()); + retry_client + .batch_scan_responses + .lock() + .await + .extend([vec![region(1, vec![], vec![10])], next_page]); + + assert!(cache + .read_through_last_region_by_key(vec![1].into()) + .await + .is_err()); + assert_eq!(retry_client.get_region_count.load(SeqCst), 2); + assert!(cache.region_cache.read().await.ver_id_to_region.is_empty()); + } + } + + #[tokio::test] + async fn test_last_region_preserves_cached_leader() -> Result<()> { + let retry_client = Arc::new(MockRetryClient::default()); + let cache = RegionCache::new(retry_client.clone()); + let mut final_region = region(3, vec![20], vec![]); + final_region.leader = Some(metapb::Peer { + store_id: 41, + ..Default::default() + }); + retry_client + .regions + .lock() + .await + .insert(final_region.id(), final_region.clone()); + cache.add_region(final_region.clone()).await; + let corrected_leader = metapb::Peer { + store_id: 42, + ..Default::default() + }; + cache + .update_leader(final_region.ver_id(), corrected_leader.clone()) + .await?; + + assert_eq!( + cache + .read_through_last_region_by_key(vec![1].into()) + .await? + .leader, + Some(corrected_leader.clone()) + ); + assert_eq!( + cache.get_region_by_id(3).await?.leader, + Some(corrected_leader) + ); Ok(()) } From b830c5f41bf19fc7b7ffc340241d2bfb95b060d5 Mon Sep 17 00:00:00 2001 From: tianyuan Date: Mon, 16 Nov 2026 21:36:15 +0800 Subject: [PATCH 12/12] fix(raw): narrow reverse scan scope and strengthen coverage Remove unsupported unbounded reverse scan discovery and its batch PD lookup path. Require a finite encoded upper bound while preserving keyspace-scoped scans and zero-limit behavior. Keep the original lower bound, simplify reverse traversal state, and make regression mocks validate Region routing, limits, and key-only results. Signed-off-by: tianyuan --- src/pd/client.rs | 65 ---------- src/pd/cluster.rs | 33 ----- src/pd/retry.rs | 35 ------ src/raw/client.rs | 297 ++++++++++++++------------------------------ src/region_cache.rs | 183 --------------------------- 5 files changed, 96 insertions(+), 517 deletions(-) diff --git a/src/pd/client.rs b/src/pd/client.rs index fe4bdb219..70394e4f8 100644 --- a/src/pd/client.rs +++ b/src/pd/client.rs @@ -28,14 +28,11 @@ use crate::store::TikvConnect; use crate::store::{KvClient, Store}; use crate::BoundRange; use crate::Config; -use crate::Error; use crate::Key; use crate::Result; use crate::SecurityManager; use crate::Timestamp; -const MAX_REGION_BOUNDARY_RETRIES: usize = 10; - /// The PdClient handles all the encoding stuff. /// /// Raw APIs does not require encoding/decoding at all. @@ -68,14 +65,6 @@ pub trait PdClient: Send + Sync + 'static { /// This is used by reverse scans when they reach a region boundary. async fn prev_region_for_key(&self, key: &Key) -> Result; - /// Return the final region at or after `key`. - /// - /// Implementations backed by PD can override this with a batch region scan. The default - /// implementation keeps compatibility with other clients by walking region boundaries. - async fn last_region_for_key(&self, key: &Key) -> Result { - walk_to_last_region(self, key).await - } - /// In transactional API, the returned region is decoded (keys in raw format) async fn region_for_id(&self, id: RegionId) -> Result; @@ -270,29 +259,6 @@ impl PdClient for PdRpcClient { Self::decode_region(region, enable_codec) } - async fn last_region_for_key(&self, key: &Key) -> Result { - let enable_codec = self.enable_codec; - let encoded_key = if enable_codec { - key.to_encoded() - } else { - key.clone() - }; - - let region = match self - .region_cache - .read_through_last_region_by_key(encoded_key) - .await - { - Ok(region) => region, - Err(Error::GrpcAPI(status)) if status.code() == tonic::Code::Unimplemented => { - return walk_to_last_region(self, key).await; - } - Err(Error::Unimplemented) => return walk_to_last_region(self, key).await, - Err(error) => return Err(error), - }; - Self::decode_region(region, enable_codec) - } - async fn region_for_id(&self, id: RegionId) -> Result { let region = self.region_cache.get_region_by_id(id).await?; Self::decode_region(region, self.enable_codec) @@ -336,37 +302,6 @@ impl PdClient for PdRpcClient { } } -async fn walk_to_last_region( - client: &P, - key: &Key, -) -> Result { - let mut region = client.region_for_key(key).await?; - let mut boundary_retries = 0; - loop { - let end_key = region.end_key(); - if end_key.is_empty() { - return Ok(region); - } - - let next_region = client.region_for_key(&end_key).await?; - if next_region.start_key() != end_key { - if boundary_retries >= MAX_REGION_BOUNDARY_RETRIES { - return Err(Error::InternalError { - message: "failed to resolve the final region after exhausting boundary retries" - .to_owned(), - }); - } - boundary_retries += 1; - client.invalidate_region_cache(region.ver_id()).await; - client.invalidate_region_cache(next_region.ver_id()).await; - region = client.region_for_key(key).await?; - continue; - } - boundary_retries = 0; - region = next_region; - } -} - impl PdRpcClient { pub async fn connect( pd_endpoints: &[String], diff --git a/src/pd/cluster.rs b/src/pd/cluster.rs index fb9c14383..89045ba99 100644 --- a/src/pd/cluster.rs +++ b/src/pd/cluster.rs @@ -70,23 +70,6 @@ impl Cluster { .await } - pub async fn batch_scan_regions( - &mut self, - start_key: Vec, - limit: i32, - timeout: Duration, - ) -> Result { - let mut req = pd_request!(self.id, pdpb::BatchScanRegionsRequest); - req.ranges.push(pdpb::KeyRange { - start_key, - ..Default::default() - }); - req.limit = limit; - // A positive limit pages the range; PD may return only a prefix of the requested range. - req.contain_all_key_range = false; - req.send(&mut self.client, timeout).await - } - async fn send_region_request( &mut self, request: pdpb::GetRegionRequest, @@ -435,16 +418,6 @@ impl PdMessage for pdpb::GetRegionRequest { } } -#[async_trait] -impl PdMessage for pdpb::BatchScanRegionsRequest { - type Client = pdpb::pd_client::PdClient; - type Response = pdpb::BatchScanRegionsResponse; - - async fn rpc(req: Request, client: &mut Self::Client) -> GrpcResult { - Ok(client.batch_scan_regions(req).await?.into_inner()) - } -} - #[async_trait] impl PdMessage for pdpb::GetRegionByIdRequest { type Client = pdpb::pd_client::PdClient; @@ -511,12 +484,6 @@ impl PdResponse for pdpb::GetRegionResponse { } } -impl PdResponse for pdpb::BatchScanRegionsResponse { - fn header(&self) -> &pdpb::ResponseHeader { - self.header.as_ref().unwrap() - } -} - impl PdResponse for pdpb::GetAllStoresResponse { fn header(&self) -> &pdpb::ResponseHeader { self.header.as_ref().unwrap() diff --git a/src/pd/retry.rs b/src/pd/retry.rs index e474975f2..ab58bf64c 100644 --- a/src/pd/retry.rs +++ b/src/pd/retry.rs @@ -39,13 +39,6 @@ pub trait RetryClientTrait { async fn get_prev_region(self: Arc, key: Vec) -> Result; - /// Return up to `limit` regions starting at `start_key` in one PD request. - async fn batch_scan_regions( - self: Arc, - start_key: Vec, - limit: i32, - ) -> Result>; - async fn get_region_by_id(self: Arc, region_id: RegionId) -> Result; async fn get_store(self: Arc, id: StoreId) -> Result; @@ -182,27 +175,6 @@ impl RetryClientTrait for RetryClient { }) } - async fn batch_scan_regions( - self: Arc, - start_key: Vec, - limit: i32, - ) -> Result> { - retry_mut!(self, "batch_scan_regions", |cluster| { - let start_key = start_key.clone(); - async { - cluster - .batch_scan_regions(start_key, limit, self.timeout) - .await - .and_then(|resp| { - resp.regions - .into_iter() - .map(region_from_batch_scan_response) - .collect() - }) - } - }) - } - async fn get_region_by_id(self: Arc, region_id: RegionId) -> Result { retry_mut!(self, "get_region_by_id", |cluster| async { cluster @@ -268,13 +240,6 @@ fn region_from_response( Ok(RegionWithLeader::new(region, resp.leader.take())) } -fn region_from_batch_scan_response(resp: pdpb::Region) -> Result { - let region = resp.region.ok_or_else(|| Error::InternalError { - message: "PD returned a batch-scanned region without metadata".to_owned(), - })?; - Ok(RegionWithLeader::new(region, resp.leader)) -} - // A node-like thing that can be connected to. #[async_trait] trait Reconnect { diff --git a/src/raw/client.rs b/src/raw/client.rs index d7b811b3a..ecdc1dd35 100644 --- a/src/raw/client.rs +++ b/src/raw/client.rs @@ -518,10 +518,9 @@ impl Client { /// from startKey(lowerBound) to endKey(upperBound) in reverse order, up to limit pairs. /// The returned keys are in reversed lexicographical order. /// If you want to include the endKey or exclude the startKey, push a '\0' to the key. - /// An unbounded upper bound is supported by locating the final Region before - /// traversing Regions backwards toward the lower bound. The normal path uses - /// paged PD batch-region scans; clients whose PD does not support that RPC - /// fall back to walking Region boundaries from the lower bound. + /// Without keyspace prefixes, a nonzero-limit scan requires an upper bound; + /// otherwise it returns [`Error::Unimplemented`]. With keyspace prefixes, + /// an unbounded range ends at the next keyspace prefix and is supported. /// # Examples /// ```rust,no_run /// # use tikv_client::{KvPair, Config, RawClient, IntoOwnedRange}; @@ -573,6 +572,8 @@ impl Client { /// Create a new 'scan' request that only returns the keys in reverse order. /// + /// Upper bounds have the same restrictions as [`Client::scan_reverse`]. + /// /// Once resolved this request will result in a `Vec` of keys that lies in the specified range. /// /// If the number of eligible keys are greater than `limit`, @@ -776,31 +777,22 @@ impl Client { let mut result = Vec::new(); let mut current_limit = limit; let (range_start, range_end) = range.into_keys(); - // `encode_keyspace` represents an unbounded upper bound as an empty key - // when keyspace prefixes are disabled. Keyspace-enabled ranges use the - // next keyspace prefix instead, so their encoded upper bound is non-empty. - let mut reverse_unbounded = reverse - && (range_end.is_none() - || (range_end.as_ref().is_some_and(Key::is_empty) - && !matches!(self.keyspace, Keyspace::Enable { .. }))); - let mut current_key = if reverse && !reverse_unbounded { - range_end.clone().unwrap() + let mut current_key = if reverse { + // TiKV does not interpret an empty reverse start key as infinity. + // Keyspace-enabled ranges have a nonempty encoded upper bound. + range_end + .clone() + .filter(|key| !key.is_empty()) + .ok_or(Error::Unimplemented)? } else { range_start.clone() }; - let mut initial_region = if reverse_unbounded { - Some(self.rpc.last_region_for_key(&range_start).await?) - } else { - None - }; while current_limit > 0 { let scan_args = ScanInnerArgs { current_key: current_key.clone(), range_start: range_start.clone(), range_end: range_end.clone(), - reverse_unbounded, - initial_region: initial_region.take(), limit: current_limit, key_only, reverse, @@ -816,18 +808,10 @@ impl Client { current_limit -= kvs.len() as u32; result.append(&mut kvs); } - if reverse && !reverse_unbounded { - if next_key.is_empty() || next_key <= range_start { - break; - } - } else if reverse_unbounded { + if reverse { if next_key.is_empty() || next_key <= range_start { break; } - // The first request used the final region with an unbounded - // upper edge. Subsequent requests walk bounded regions back - // toward the lower edge just like an ordinary reverse scan. - reverse_unbounded = false; } else if next_key.is_empty() || range_end.clone().is_some_and(|ek| ek <= next_key) { break; } @@ -848,12 +832,12 @@ impl Client { mut scan_args: ScanInnerArgs, ) -> Result<(Option, Key)> { let current_key = scan_args.current_key; - let mut region_override = scan_args.initial_region.take(); + let mut region_override = None; let mut boundary_retries = 0; loop { let region = if let Some(region) = region_override.take() { region - } else if scan_args.reverse && !scan_args.reverse_unbounded { + } else if scan_args.reverse { let region = self.rpc.clone().region_for_key(¤t_key).await?; if !current_key.is_empty() && region.start_key() == current_key { let previous = match self.rpc.clone().prev_region_for_key(¤t_key).await { @@ -888,17 +872,7 @@ impl Client { }; let store = self.rpc.clone().store_for_id(region.id()).await?; let (start_key, end_key) = if scan_args.reverse { - let region_start = region.start_key(); - let start_key = if region_start < scan_args.range_start { - scan_args.range_start.clone() - } else { - region_start - }; - if scan_args.reverse_unbounded { - (start_key, None) - } else { - (start_key, Some(current_key.clone())) - } + (scan_args.range_start.clone(), Some(current_key.clone())) } else { (current_key.clone(), scan_args.range_end.clone()) }; @@ -921,18 +895,14 @@ impl Client { let status = plan::handle_region_error(self.rpc.clone(), err.clone(), store.clone()) .await?; - if scan_args.reverse { - // Only a known-leader correction preserves the - // Region metadata. EpochNotMatch may have removed - // this Region ID, so resolve it by key again. - if status && err.not_leader.as_ref().is_some_and(|e| e.leader.is_some()) - { - region_override = Some(region.clone()); - } else if scan_args.reverse_unbounded { - region_override = Some( - self.rpc.last_region_for_key(&scan_args.range_start).await?, - ); - } + // Only a known-leader correction preserves the Region + // metadata. EpochNotMatch may have removed this Region + // ID, so resolve it by key again. + if scan_args.reverse + && status + && err.not_leader.as_ref().is_some_and(|e| e.leader.is_some()) + { + region_override = Some(region.clone()); } if !status { sleep(duration).await; @@ -1015,8 +985,6 @@ struct ScanInnerArgs { current_key: Key, range_start: Key, range_end: Option, - reverse_unbounded: bool, - initial_region: Option, limit: u32, key_only: bool, reverse: bool, @@ -1037,29 +1005,59 @@ mod tests { use crate::proto::kvrpcpb; use crate::Result; + #[rstest::rstest] + #[case::limit_in_region((vec![1]..vec![255]).into(), 1, vec![vec![251]])] + #[case::cross_regions((vec![1]..vec![255]).into(), 4, vec![vec![251], vec![250, 250], vec![11], vec![10]])] + #[case::exclusive_boundary((vec![1]..vec![250, 250]).into(), 3, vec![vec![11], vec![10], vec![2]])] + #[case::inclusive_boundary((vec![1]..=vec![250, 250]).into(), 3, vec![vec![250, 250], vec![11], vec![10]])] + #[case::lower_bound((vec![2]..vec![11]).into(), 100, vec![vec![10], vec![2]])] + #[case::exclusive_lower_bound(BoundRange::new(std::ops::Bound::Excluded(vec![10].into()), std::ops::Bound::Excluded(vec![255].into())), 100, vec![vec![251], vec![250, 250], vec![11]])] + #[case::empty_region((vec![12]..vec![20]).into(), 100, vec![])] + #[case::empty_range((vec![10]..vec![10]).into(), 100, vec![])] #[tokio::test] - async fn reverse_scan_across_regions_uses_previous_regions() -> Result<()> { - let keys = Arc::new(vec![vec![1], vec![11], vec![251]]); - let requests = Arc::new(Mutex::new(Vec::<(Vec, Vec)>::new())); - let dispatched_keys = keys.clone(); - let dispatched_requests = requests.clone(); + async fn reverse_scan_across_regions_uses_previous_regions( + #[case] range: BoundRange, + #[case] limit: u32, + #[case] expected: Vec>, + #[values(false, true)] key_only: bool, + ) -> Result<()> { + let keys = [ + vec![1], + vec![2], + vec![10], + vec![11], + vec![250, 250], + vec![251], + ]; + let requests = AtomicUsize::new(0); let pd_client = Arc::new(MockPdClient::new(MockKvClient::with_dispatch_hook( move |req: &dyn Any| { let req = req.downcast_ref::().unwrap(); assert!(req.reverse); - dispatched_requests - .lock() - .unwrap() - .push((req.start_key.clone(), req.end_key.clone())); - - let kvs = dispatched_keys + assert!( + requests.fetch_add(1, Ordering::SeqCst) < 10, + "scan cursor did not advance" + ); + let region = match req.context.as_ref().unwrap().region_id { + 1 => MockPdClient::region1(), + 2 => MockPdClient::region2(), + 3 => MockPdClient::region3(), + id => panic!("unexpected region {id}"), + }; + let cursor = Key::from(req.start_key.clone()); + // A reverse cursor can equal the region's exclusive end key. + assert!(!cursor.is_empty() && cursor >= region.start_key()); + assert!(region.end_key().is_empty() || cursor <= region.end_key()); + let kvs = keys .iter() + .filter(|key| region.contains(&Key::from((*key).clone()))) .filter(|key| key.as_slice() >= req.end_key.as_slice()) .filter(|key| key.as_slice() < req.start_key.as_slice()) .rev() + .take(req.limit as usize) .map(|key| kvrpcpb::KvPair { key: key.clone(), - value: key.clone(), + value: if req.key_only { vec![] } else { key.clone() }, ..Default::default() }) .collect(); @@ -1077,67 +1075,47 @@ mod tests { keyspace: Keyspace::Disable, }; - let pairs = client.scan_reverse(vec![1]..vec![255], 2).await?; - assert_eq!( - pairs.into_iter().map(|pair| pair.0).collect::>(), - vec![Key::from(vec![251]), Key::from(vec![11])] - ); - assert_eq!( - requests.lock().unwrap().as_slice(), - &[(vec![255], vec![250, 250]), (vec![250, 250], vec![10]),] - ); - - requests.lock().unwrap().clear(); - let pairs = client.scan_reverse(vec![1]..vec![250, 250], 2).await?; - assert_eq!( - pairs.into_iter().map(|pair| pair.0).collect::>(), - vec![Key::from(vec![11]), Key::from(vec![1])] - ); + let pairs = client.scan_inner(range, limit, key_only, true).await?; assert_eq!( - requests.lock().unwrap().as_slice(), - &[(vec![250, 250], vec![10]), (vec![10], vec![1]),] + pairs, + expected + .into_iter() + .map(|key| { + let value = if key_only { vec![] } else { key.clone() }; + KvPair::new(key, value) + }) + .collect::>() ); Ok(()) } + #[rstest::rstest] + #[case::full((..).into())] + #[case::from((vec![1]..).into())] + #[case::empty_upper((vec![1]..Vec::::new()).into())] #[tokio::test] - async fn reverse_scan_from_unbounded_upper_bound_uses_range_start() -> Result<()> { - let looked_up_keys = Arc::new(Mutex::new(Vec::::new())); - let dispatched_lookups = looked_up_keys.clone(); + async fn reverse_scan_requires_an_upper_bound_without_keyspace_prefixes( + #[case] range: BoundRange, + #[values(Keyspace::Disable, Keyspace::ApiV2NoPrefix)] keyspace: Keyspace, + #[values(false, true)] key_only: bool, + ) { let pd_client = Arc::new( - MockPdClient::new(MockKvClient::with_dispatch_hook(move |req: &dyn Any| { - let req = req.downcast_ref::().unwrap(); - assert!(req.reverse); - assert!(req.start_key.is_empty()); - assert_eq!(req.end_key, vec![251]); - Ok(Box::new(kvrpcpb::RawScanResponse { - kvs: vec![kvrpcpb::KvPair { - key: vec![251], - value: vec![42], - ..Default::default() - }], - ..Default::default() - }) as Box) + MockPdClient::new(MockKvClient::with_dispatch_hook(|_| { + panic!("unsupported scan must not dispatch") })) - .with_region_for_key_hook(move |key| { - dispatched_lookups.lock().unwrap().push(key.clone()); - Ok(MockPdClient::region3()) - }), + .with_region_for_key_hook(|_| panic!("unsupported scan must not query PD")), ); let client = Client { rpc: pd_client, cf: None, backoff: DEFAULT_REGION_BACKOFF, atomic: false, - keyspace: Keyspace::Disable, + keyspace, }; - - assert_eq!(client.scan_reverse(vec![251].., 1).await?.len(), 1); - assert_eq!( - looked_up_keys.lock().unwrap().as_slice(), - &[Key::from(vec![251])] - ); - Ok(()) + assert!(matches!( + client.scan_inner(range, 1, key_only, true).await, + Err(Error::Unimplemented) + )); } #[tokio::test] @@ -1190,87 +1168,6 @@ mod tests { Ok(()) } - #[tokio::test] - async fn reverse_scan_stops_after_repeated_final_region_boundaries() -> Result<()> { - let pd_client = Arc::new( - MockPdClient::new(MockKvClient::with_dispatch_hook(|_: &dyn Any| { - panic!("stale boundary must not dispatch") - })) - .with_region_for_key_hook(|key| { - let key_bytes: &[u8] = key.into(); - if key_bytes == [1] { - Ok(MockPdClient::region1()) - } else { - Ok(MockPdClient::region3()) - } - }), - ); - let client = Client { - rpc: pd_client, - cf: None, - backoff: Backoff::no_backoff(), - atomic: false, - keyspace: Keyspace::Disable, - }; - - assert!(matches!( - client.scan_reverse(vec![1].., 1).await, - Err(Error::InternalError { .. }) - )); - Ok(()) - } - - #[tokio::test] - async fn reverse_scan_unbounded_upper_traverses_from_final_region() -> Result<()> { - let requests = Arc::new(Mutex::new(Vec::<(Vec, Vec)>::new())); - let dispatched_requests = requests.clone(); - let pd_client = Arc::new(MockPdClient::new(MockKvClient::with_dispatch_hook( - move |req: &dyn Any| { - let req = req.downcast_ref::().unwrap(); - assert!(req.reverse); - dispatched_requests - .lock() - .unwrap() - .push((req.start_key.clone(), req.end_key.clone())); - let key = match (req.start_key.as_slice(), req.end_key.as_slice()) { - ([], [250, 250]) => vec![251], - ([250, 250], [10]) => vec![11], - request => panic!("unexpected reverse scan request: {request:?}"), - }; - Ok(Box::new(kvrpcpb::RawScanResponse { - kvs: vec![kvrpcpb::KvPair { - key: key.clone(), - value: key, - ..Default::default() - }], - ..Default::default() - }) as Box) - }, - ))); - let client = Client { - rpc: pd_client, - cf: None, - backoff: DEFAULT_REGION_BACKOFF, - atomic: false, - keyspace: Keyspace::Disable, - }; - - assert_eq!( - client - .scan_reverse(vec![1].., 2) - .await? - .into_iter() - .map(|pair| pair.0) - .collect::>(), - vec![Key::from(vec![251]), Key::from(vec![11])] - ); - assert_eq!( - requests.lock().unwrap().as_slice(), - &[(vec![], vec![250, 250]), (vec![250, 250], vec![10])] - ); - Ok(()) - } - #[tokio::test] async fn reverse_scan_refreshes_stale_region_boundary() -> Result<()> { let refreshed = Arc::new(AtomicBool::new(false)); @@ -1323,7 +1220,7 @@ mod tests { assert_eq!(invalidations.load(Ordering::SeqCst), 1); assert_eq!( requests.lock().unwrap().as_slice(), - &[(vec![250, 250], vec![10]), (vec![10], vec![1])] + &[(vec![250, 250], vec![1]), (vec![10], vec![1])] ); Ok(()) } @@ -1366,7 +1263,7 @@ mod tests { ..Default::default() }) as Box) } else { - assert_eq!(req.end_key, vec![10]); + assert_eq!(req.end_key, vec![1]); Ok(Box::new(kvrpcpb::RawScanResponse { kvs: vec![kvrpcpb::KvPair { key: vec![11], @@ -1444,11 +1341,9 @@ mod tests { let result = client .retryable_scan(ScanInnerArgs { - current_key: vec![1].into(), + current_key: vec![255].into(), range_start: vec![1].into(), - range_end: None, - reverse_unbounded: true, - initial_region: Some(MockPdClient::region3()), + range_end: Some(vec![255].into()), limit: 1, key_only: false, reverse: true, diff --git a/src/region_cache.rs b/src/region_cache.rs index 5dc1d0990..0ecc2116c 100644 --- a/src/region_cache.rs +++ b/src/region_cache.rs @@ -23,7 +23,6 @@ use crate::Key; use crate::Result; const MAX_RETRY_WAITING_CONCURRENT_REQUEST: usize = 4; -const BATCH_SCAN_REGIONS_PAGE_SIZE: i32 = 128; struct RegionCacheMap { /// RegionVerID -> Region. It stores the concrete region caches. @@ -159,51 +158,6 @@ impl RegionCache { Ok(region) } - /// Find the final region with bounded PD batch scans, caching only that region. - /// Each page starts at the previous page's end key so response memory stays bounded. - pub async fn read_through_last_region_by_key(&self, key: Key) -> Result - where - C: Send + Sync, - { - let mut start_key: Vec = key.into(); - loop { - let regions = self - .inner_client - .clone() - .batch_scan_regions(start_key.clone(), BATCH_SCAN_REGIONS_PAGE_SIZE) - .await?; - let mut region = regions - .into_iter() - .max_by(|a, b| a.region.start_key.cmp(&b.region.start_key)) - .ok_or_else(|| Error::RegionForKeyNotFound { - key: start_key.clone(), - })?; - if !region.region.end_key.is_empty() { - if region.region.end_key <= start_key { - return Err(Error::InternalError { - message: "batch region scan did not advance past the previous page" - .to_owned(), - }); - } - start_key = region.region.end_key; - continue; - } - - let cached_leader = { - let cache = self.region_cache.read().await; - cache - .ver_id_to_region - .get(®ion.ver_id()) - .and_then(|cached| cached.leader.clone()) - }; - if cached_leader.is_some() { - region.leader = cached_leader; - } - self.add_region(region.clone()).await; - return Ok(region); - } - } - /// Force read through (query from PD) for the region immediately before /// the region containing `key`. async fn read_through_prev_region_by_key(&self, key: Key) -> Result { @@ -376,7 +330,6 @@ mod test { use std::collections::BTreeMap; use std::collections::HashMap; use std::collections::HashSet; - use std::collections::VecDeque; use std::sync::atomic::AtomicU64; use std::sync::atomic::Ordering::SeqCst; use std::sync::Arc; @@ -400,7 +353,6 @@ mod test { struct MockRetryClient { pub regions: Mutex>, pub get_region_count: AtomicU64, - pub batch_scan_responses: Mutex>>, } #[async_trait] @@ -434,30 +386,6 @@ mod test { .ok_or_else(|| Error::RegionForKeyNotFound { key }) } - async fn batch_scan_regions( - self: Arc, - start_key: Vec, - limit: i32, - ) -> Result> { - self.get_region_count.fetch_add(1, SeqCst); - assert!(limit > 0, "batch region scans must use a bounded page size"); - if let Some(regions) = self.batch_scan_responses.lock().await.pop_front() { - return Ok(regions); - } - let start_key: Key = start_key.into(); - let mut regions = self - .regions - .lock() - .await - .values() - .filter(|region| region.end_key().is_empty() || region.end_key() > start_key) - .cloned() - .collect::>(); - regions.sort_by_key(|region| region.start_key()); - regions.truncate(limit as usize); - Ok(regions) - } - async fn get_region_by_id( self: Arc, region_id: crate::region::RegionId, @@ -694,117 +622,6 @@ mod test { Ok(()) } - #[tokio::test] - async fn test_last_region_by_key_uses_one_batch_pd_request() -> Result<()> { - let retry_client = Arc::new(MockRetryClient::default()); - let cache = RegionCache::new(retry_client.clone()); - retry_client.regions.lock().await.extend([ - (1, region(1, vec![], vec![10])), - (2, region(2, vec![10], vec![20])), - (3, region(3, vec![20], vec![])), - ]); - - assert_eq!( - cache - .read_through_last_region_by_key(vec![1].into()) - .await? - .id(), - 3 - ); - assert_eq!(retry_client.get_region_count.load(SeqCst), 1); - assert_eq!(cache.get_region_by_id(3).await?.id(), 3); - assert_eq!(retry_client.get_region_count.load(SeqCst), 1); - assert_eq!(cache.region_cache.read().await.ver_id_to_region.len(), 1); - Ok(()) - } - - #[tokio::test] - async fn test_last_region_by_key_pages_large_region_ranges() -> Result<()> { - let retry_client = Arc::new(MockRetryClient::default()); - let cache = RegionCache::new(retry_client.clone()); - retry_client - .regions - .lock() - .await - .extend((0..=129).map(|id| { - let start_key = vec![id as u8]; - let end_key = if id == 129 { - vec![] - } else { - vec![id as u8 + 1] - }; - (id, region(id, start_key, end_key)) - })); - - assert_eq!( - cache - .read_through_last_region_by_key(vec![1].into()) - .await? - .id(), - 129 - ); - assert_eq!(retry_client.get_region_count.load(SeqCst), 2); - assert_eq!(cache.region_cache.read().await.ver_id_to_region.len(), 1); - Ok(()) - } - - #[tokio::test] - async fn test_last_region_by_key_rejects_incomplete_or_nonadvancing_pages() { - for next_page in [vec![], vec![region(1, vec![], vec![10])]] { - let retry_client = Arc::new(MockRetryClient::default()); - let cache = RegionCache::new(retry_client.clone()); - retry_client - .batch_scan_responses - .lock() - .await - .extend([vec![region(1, vec![], vec![10])], next_page]); - - assert!(cache - .read_through_last_region_by_key(vec![1].into()) - .await - .is_err()); - assert_eq!(retry_client.get_region_count.load(SeqCst), 2); - assert!(cache.region_cache.read().await.ver_id_to_region.is_empty()); - } - } - - #[tokio::test] - async fn test_last_region_preserves_cached_leader() -> Result<()> { - let retry_client = Arc::new(MockRetryClient::default()); - let cache = RegionCache::new(retry_client.clone()); - let mut final_region = region(3, vec![20], vec![]); - final_region.leader = Some(metapb::Peer { - store_id: 41, - ..Default::default() - }); - retry_client - .regions - .lock() - .await - .insert(final_region.id(), final_region.clone()); - cache.add_region(final_region.clone()).await; - let corrected_leader = metapb::Peer { - store_id: 42, - ..Default::default() - }; - cache - .update_leader(final_region.ver_id(), corrected_leader.clone()) - .await?; - - assert_eq!( - cache - .read_through_last_region_by_key(vec![1].into()) - .await? - .leader, - Some(corrected_leader.clone()) - ); - assert_eq!( - cache.get_region_by_id(3).await?.leader, - Some(corrected_leader) - ); - Ok(()) - } - #[tokio::test] async fn test_prev_region_preserves_cached_leader() -> Result<()> { let retry_client = Arc::new(MockRetryClient::default());