use crate::{CoreError, Result};
pub const DEFAULT_LIST_LIMIT: u32 = 1000;
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct Paged<T> {
pub items: Vec<T>,
pub truncated: bool,
pub limit: u32,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FetchStrategy {
SingleShot,
Paged {
per_page: u32,
},
}
async fn fetch_all_pages<T, F, Fut>(per_page: u32, want: usize, fetch: &F) -> Result<Vec<T>>
where
F: Fn(u32, u32) -> Fut,
Fut: std::future::Future<Output = Result<Vec<T>>>,
{
if per_page == 0 {
return Err(CoreError::Platform(
"pagination per_page must be greater than zero".to_string(),
));
}
let mut items: Vec<T> = Vec::new();
let mut page: u32 = 1;
loop {
let batch = fetch(page, per_page).await?;
let batch_len = batch.len();
items.extend(batch);
let per_page_usize = usize::try_from(per_page).unwrap_or(usize::MAX);
if batch_len < per_page_usize {
break; }
if items.len() >= want {
break; }
page = page
.checked_add(1)
.ok_or_else(|| CoreError::Platform("pagination page number overflowed".to_string()))?;
}
Ok(items)
}
pub async fn fetch_capped<T, F, Fut>(
strategy: FetchStrategy,
cap: u32,
fetch: F,
) -> Result<Paged<T>>
where
F: Fn(u32, u32) -> Fut,
Fut: std::future::Future<Output = Result<Vec<T>>>,
{
let want = usize::try_from(cap.saturating_add(1)).unwrap_or(usize::MAX);
let mut items: Vec<T> = match strategy {
FetchStrategy::SingleShot => {
let limit = cap.saturating_add(1);
fetch(1, limit).await?
}
FetchStrategy::Paged { per_page } => fetch_all_pages(per_page, want, &fetch).await?,
};
let cap_usize = usize::try_from(cap).unwrap_or(usize::MAX);
let truncated = items.len() > cap_usize;
if truncated {
items.truncate(cap_usize);
}
Ok(Paged {
items,
truncated,
limit: cap,
})
}
impl<T> Paged<T> {
#[must_use]
pub fn into_parts(self) -> (Vec<T>, crate::output::PaginationMeta) {
let meta = crate::output::PaginationMeta {
truncated: self.truncated,
returned: self.items.len(),
limit: self.limit,
};
(self.items, meta)
}
}
#[cfg(test)]
mod tests {
use std::sync::Mutex;
use super::*;
#[derive(Debug)]
struct Source {
total: usize,
calls: Mutex<Vec<(u32, u32)>>,
}
impl Source {
fn new(total: usize) -> Self {
Self {
total,
calls: Mutex::new(Vec::new()),
}
}
fn page(&self, page: u32, limit: u32) -> Vec<usize> {
if let Ok(mut calls) = self.calls.lock() {
calls.push((page, limit));
}
let start = (page as usize - 1) * limit as usize;
if start >= self.total {
return Vec::new();
}
let end = std::cmp::min(start + limit as usize, self.total);
(start..end).collect()
}
fn recorded(&self) -> Vec<(u32, u32)> {
self.calls.lock().map(|c| c.clone()).unwrap_or_default()
}
}
async fn run_single_shot(total: usize, cap: u32) -> (Paged<usize>, Vec<(u32, u32)>) {
let src = Source::new(total);
let paged = fetch_capped(FetchStrategy::SingleShot, cap, |page, limit| {
let src = &src;
async move { Ok(src.page(page, limit)) }
})
.await
.expect("fetch_capped should succeed");
let calls = src.recorded();
(paged, calls)
}
async fn run_paged(total: usize, cap: u32, per_page: u32) -> (Paged<usize>, Vec<(u32, u32)>) {
let src = Source::new(total);
let paged = fetch_capped(FetchStrategy::Paged { per_page }, cap, |page, limit| {
let src = &src;
async move { Ok(src.page(page, limit)) }
})
.await
.expect("fetch_capped should succeed");
let calls = src.recorded();
(paged, calls)
}
#[tokio::test]
async fn test_should_request_cap_plus_one_in_single_shot() {
let (_, calls) = run_single_shot(5, 10).await;
assert_eq!(calls, vec![(1, 11)], "single-shot 必须一次要 cap+1 条");
}
#[tokio::test]
async fn test_should_not_truncate_when_total_below_cap() {
let (paged, _) = run_single_shot(5, 10).await;
assert_eq!(paged.items.len(), 5);
assert!(!paged.truncated);
assert_eq!(paged.limit, 10);
}
#[tokio::test]
async fn test_should_not_truncate_when_total_equals_cap() {
let (paged, _) = run_single_shot(10, 10).await;
assert_eq!(paged.items.len(), 10);
assert!(!paged.truncated, "恰好 cap 条不算截断");
}
#[tokio::test]
async fn test_should_truncate_when_total_exceeds_cap_by_one() {
let (paged, _) = run_single_shot(11, 10).await;
assert_eq!(paged.items.len(), 10, "超出部分必须被截掉");
assert!(paged.truncated, "N+1 探测必须发现还有更多");
}
#[tokio::test]
async fn test_should_truncate_when_total_far_exceeds_cap() {
let (paged, _) = run_single_shot(500, 10).await;
assert_eq!(paged.items.len(), 10);
assert!(paged.truncated);
}
#[tokio::test]
async fn test_should_return_empty_without_truncation_when_source_empty() {
let (paged, _) = run_single_shot(0, 10).await;
assert!(paged.items.is_empty());
assert!(!paged.truncated);
}
#[tokio::test]
async fn test_should_stop_paging_on_short_page() {
let (paged, calls) = run_paged(5, 100, 10).await;
assert_eq!(paged.items.len(), 5);
assert!(!paged.truncated);
assert_eq!(calls, vec![(1, 10)], "短页即取尽,不得再请求第 2 页");
}
#[tokio::test]
async fn test_should_walk_pages_until_cap_plus_one_collected() {
let (paged, calls) = run_paged(100, 25, 10).await;
assert_eq!(paged.items.len(), 25);
assert!(paged.truncated);
assert_eq!(calls, vec![(1, 10), (2, 10), (3, 10)]);
}
#[tokio::test]
async fn test_should_probe_one_past_cap_when_cap_is_a_multiple_of_per_page() {
let (paged, calls) = run_paged(30, 20, 10).await;
assert_eq!(
calls,
vec![(1, 10), (2, 10), (3, 10)],
"必须探到第 3 页才能发现还有更多"
);
assert_eq!(paged.items.len(), 20);
assert!(paged.truncated, "30 > cap=20,必须报告截断");
}
#[tokio::test]
async fn test_should_stop_paging_when_exhausted_exactly_at_page_boundary() {
let (paged, calls) = run_paged(20, 100, 10).await;
assert_eq!(paged.items.len(), 20);
assert!(!paged.truncated);
assert_eq!(calls, vec![(1, 10), (2, 10), (3, 10)]);
}
#[tokio::test]
async fn test_should_preserve_item_order_across_pages() {
let (paged, _) = run_paged(25, 100, 10).await;
assert_eq!(paged.items, (0..25).collect::<Vec<usize>>());
}
#[tokio::test]
async fn test_should_reject_zero_per_page() {
let src = Source::new(10);
let result = fetch_capped(FetchStrategy::Paged { per_page: 0 }, 10, |page, limit| {
let src = &src;
async move { Ok(src.page(page, limit)) }
})
.await;
assert!(
matches!(result, Err(CoreError::Platform(_))),
"per_page = 0 会导致死循环,必须直接报错"
);
}
#[tokio::test]
async fn test_should_propagate_fetch_error() {
let result: Result<Paged<usize>> =
fetch_capped(FetchStrategy::SingleShot, 10, async |_page, _limit| {
Err(CoreError::Platform("boom".to_string()))
})
.await;
assert!(matches!(result, Err(CoreError::Platform(msg)) if msg == "boom"));
}
#[tokio::test]
async fn test_should_return_empty_and_truncated_when_cap_is_zero() {
let (paged, _) = run_single_shot(5, 0).await;
assert!(paged.items.is_empty());
assert!(paged.truncated, "cap=0 但源里有数据,必须诚实报告截断");
}
#[test]
fn test_should_expose_default_list_limit_of_1000() {
assert_eq!(DEFAULT_LIST_LIMIT, 1000);
}
}