Skip to main content

github_rust/github/
pagination.rs

1//! Strict connection traversal shared by account and work-item queries.
2use crate::{GitHubError, Result};
3use serde::Deserialize;
4use std::collections::HashSet;
5
6/// Limits for account, owned-repository and open-work-item collection methods.
7/// Existing search and REST pagination retain their own limits.
8#[derive(Debug, Clone, Copy)]
9pub struct FetchOptions {
10    /// Nodes requested per page, from 1 to 100. Default: 100.
11    pub page_size: u32,
12    /// Maximum pages per connection, at least 1. Default: 500.
13    pub max_pages: usize,
14    /// Maximum repository requests in flight, at least 1. Default: 4.
15    pub max_concurrent_repositories: usize,
16}
17impl Default for FetchOptions {
18    fn default() -> Self {
19        Self {
20            page_size: 100,
21            max_pages: 500,
22            max_concurrent_repositories: 4,
23        }
24    }
25}
26impl FetchOptions {
27    pub(crate) fn validate(self) -> Result<Self> {
28        let invalid = if !(1..=100).contains(&self.page_size) {
29            Some("page_size must be between 1 and 100")
30        } else if self.max_pages == 0 {
31            Some("max_pages must be greater than zero")
32        } else if self.max_concurrent_repositories == 0 {
33            Some("max_concurrent_repositories must be greater than zero")
34        } else if self
35            .max_pages
36            .checked_mul(self.page_size as usize)
37            .is_none()
38        {
39            Some("max_pages multiplied by page_size must fit in usize")
40        } else {
41            None
42        };
43        if let Some(message) = invalid {
44            return Err(GitHubError::InvalidInput(message.into()));
45        }
46        Ok(self)
47    }
48}
49#[derive(Deserialize)]
50#[serde(rename_all = "camelCase")]
51pub(crate) struct Connection<T> {
52    pub nodes: Vec<T>,
53    pub total_count: usize,
54    pub page_info: PageInfo,
55}
56#[derive(Deserialize)]
57#[serde(rename_all = "camelCase")]
58pub(crate) struct PageInfo {
59    pub has_next_page: bool,
60    pub end_cursor: Option<String>,
61}
62#[derive(Default)]
63pub(crate) struct Tracker {
64    pub cursor: Option<String>,
65    total: Option<usize>,
66    ids: HashSet<String>,
67    cursors: HashSet<String>,
68    pages: usize,
69}
70impl Tracker {
71    pub fn accept<T>(
72        &mut self,
73        page: &Connection<T>,
74        options: FetchOptions,
75        id: impl Fn(&T) -> &str,
76    ) -> Result<()> {
77        let fail = || GitHubError::PaginationError("Incomplete or inconsistent connection".into());
78        self.pages += 1;
79        if self.pages > options.max_pages
80            || page.nodes.len() > options.page_size as usize
81            || page.total_count > options.max_pages * options.page_size as usize
82            || self.total.is_some_and(|total| total != page.total_count)
83        {
84            return Err(fail());
85        }
86        self.total = Some(page.total_count);
87        for node in &page.nodes {
88            let id = id(node);
89            if id.is_empty() || !self.ids.insert(id.to_owned()) {
90                return Err(fail());
91            }
92        }
93        if self.ids.len() > page.total_count {
94            return Err(fail());
95        }
96        if page.page_info.has_next_page {
97            let cursor = page
98                .page_info
99                .end_cursor
100                .as_deref()
101                .filter(|c| !c.is_empty())
102                .ok_or_else(fail)?;
103            if page.nodes.is_empty()
104                || self.ids.len() >= page.total_count
105                || self.pages >= options.max_pages
106                || !self.cursors.insert(cursor.to_owned())
107            {
108                return Err(fail());
109            }
110            self.cursor = Some(cursor.to_owned());
111        } else {
112            if self.ids.len() != page.total_count {
113                return Err(fail());
114            }
115            self.cursor = None;
116        }
117        Ok(())
118    }
119}
120
121// Concrete callback type for collection calls that do not request progress.
122pub(crate) type NoProgress<T> = fn(&T) -> std::future::Ready<Result<()>>;