diff --git a/src/mock.rs b/src/mock.rs index 0a1c1b774..2a0fc49b3 100644 --- a/src/mock.rs +++ b/src/mock.rs @@ -86,6 +86,14 @@ 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: + Option Result + Send + Sync + 'static>>, /// Optional observer/override for leader cache updates. #[new(default)] update_leader_hook: @@ -140,6 +148,22 @@ 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_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, @@ -241,7 +265,25 @@ impl PdClient for MockPdClient { Ok(region) } + 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() }), + 2 => Ok(Self::region1()), + 3 => Ok(Self::region2()), + _ => Err(Error::RegionNotFoundInResponse { + region_id: region.id(), + }), + } + } + 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/pd/client.rs b/src/pd/client.rs index b89658751..70394e4f8 100644 --- a/src/pd/client.rs +++ b/src/pd/client.rs @@ -60,6 +60,11 @@ 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; + /// In transactional API, the returned region is decoded (keys in raw format) async fn region_for_id(&self, id: RegionId) -> Result; @@ -242,6 +247,18 @@ 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.get_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..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,42 @@ 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( + &mut self, + key: Vec, + timeout: Duration, + ) -> Result { + let mut req = pd_request!(self.id, pdpb::GetRegionRequest); + req.region_key = key; + 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 = 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() + .and_then(|header| header.error.as_ref()) + { + return Err(internal_err!(err.message.clone())); + } + Ok(response) } pub async fn get_region_by_id( diff --git a/src/pd/retry.rs b/src/pd/retry.rs index 5449c1088..ab58bf64c 100644 --- a/src/pd/retry.rs +++ b/src/pd/retry.rs @@ -37,6 +37,8 @@ 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; + async fn get_region_by_id(self: Arc, region_id: RegionId) -> Result; async fn get_store(self: Arc, id: StoreId) -> Result; @@ -159,6 +161,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..ecdc1dd35 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. /// @@ -517,7 +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. - /// It doesn't support Scanning from "", because locating the last Region is not yet implemented. + /// 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}; @@ -569,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`, @@ -764,17 +769,30 @@ impl Client { max_limit: MAX_RAW_KV_SCAN_LIMIT, }); } + if limit == 0 { + return Ok(Vec::new()); + } 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 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() + }; 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(), limit: current_limit, key_only, reverse, @@ -790,15 +808,14 @@ impl Client { current_limit -= kvs.len() as u32; result.append(&mut kvs); } - if next_key.is_empty() { + if reverse { + 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; } - if end_key.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 +831,51 @@ 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; + let mut region_override = None; + let mut boundary_retries = 0; loop { - let region = self.rpc.clone().region_for_key(&start_key).await?; + let region = if let Some(region) = region_override.take() { + region + } 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 { + 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; + } + Err(error) => return Err(error), + }; + 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?; + let (start_key, end_key) = if scan_args.reverse { + (scan_args.range_start.clone(), 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, @@ -830,19 +887,34 @@ 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 { - continue; - } else if let Some(duration) = scan_args.backoff.next_delay_duration() { + // 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; - continue; - } else { - return Err(RegionError(Box::new(err))); } + continue; } - Ok((Some(r), region.end_key())) + let next_key = if scan_args.reverse { + region.start_key() + } else { + region.end_key() + }; + Ok((Some(r), next_key)) } Err(err) => Err(err), }; @@ -910,8 +982,9 @@ impl Client { #[derive(Clone)] struct ScanInnerArgs { - start_key: Key, - end_key: Option, + current_key: Key, + range_start: Key, + range_end: Option, limit: u32, key_only: bool, reverse: bool, @@ -921,15 +994,369 @@ 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; use super::*; use crate::mock::MockKvClient; use crate::mock::MockPdClient; + use crate::proto::errorpb; 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( + #[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); + 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: if req.key_only { vec![] } else { 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_inner(range, limit, key_only, true).await?; + assert_eq!( + 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_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(|_| { + panic!("unsupported scan must not dispatch") + })) + .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, + }; + assert!(matches!( + client.scan_inner(range, 1, key_only, true).await, + Err(Error::Unimplemented) + )); + } + + #[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_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_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![1]), (vec![10], vec![1])] + ); + 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![1]); + 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(()) + } + + #[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![255].into(), + range_start: vec![1].into(), + range_end: Some(vec![255].into()), + 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 2a4b0fbbd..0ecc2116c 100644 --- a/src/region_cache.rs +++ b/src/region_cache.rs @@ -94,6 +94,26 @@ impl RegionCache { self.read_through_region_by_key(key.clone()).await } + // 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. pub async fn get_region_by_id(&self, id: RegionId) -> Result { for _ in 0..=MAX_RETRY_WAITING_CONCURRENT_REQUEST { @@ -138,6 +158,32 @@ impl RegionCache { 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 { + 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) + } + /// 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 @@ -326,6 +372,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, @@ -532,6 +592,78 @@ mod test { Ok(()) } + #[tokio::test] + 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.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?.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_err()); + assert!(cache.get_prev_region_by_key(&Key::EMPTY).await.is_err()); + 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, 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()),