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    pub page_size: u32,
11    pub max_pages: usize,
12    pub max_concurrent_repositories: usize,
13}
14impl Default for FetchOptions {
15    fn default() -> Self {
16        Self {
17            page_size: 100,
18            max_pages: 500,
19            max_concurrent_repositories: 4,
20        }
21    }
22}
23impl FetchOptions {
24    pub(crate) fn validate(self) -> Result<Self> {
25        if !(1..=100).contains(&self.page_size)
26            || self.max_pages == 0
27            || self.max_concurrent_repositories == 0
28            || self
29                .max_pages
30                .checked_mul(self.page_size as usize)
31                .is_none()
32        {
33            return Err(GitHubError::InvalidInput(
34                "Invalid collection limits".into(),
35            ));
36        }
37        Ok(self)
38    }
39}
40#[derive(Deserialize)]
41#[serde(rename_all = "camelCase")]
42pub(crate) struct Connection<T> {
43    pub nodes: Vec<T>,
44    pub total_count: usize,
45    pub page_info: PageInfo,
46}
47#[derive(Deserialize)]
48#[serde(rename_all = "camelCase")]
49pub(crate) struct PageInfo {
50    pub has_next_page: bool,
51    pub end_cursor: Option<String>,
52}
53#[derive(Default)]
54pub(crate) struct Tracker {
55    pub cursor: Option<String>,
56    total: Option<usize>,
57    ids: HashSet<String>,
58    cursors: HashSet<String>,
59    pages: usize,
60}
61impl Tracker {
62    pub fn accept<T>(
63        &mut self,
64        page: &Connection<T>,
65        options: FetchOptions,
66        id: impl Fn(&T) -> &str,
67    ) -> Result<()> {
68        let fail = || GitHubError::PaginationError("Incomplete or inconsistent connection".into());
69        self.pages += 1;
70        if self.pages > options.max_pages
71            || page.nodes.len() > options.page_size as usize
72            || page.total_count > options.max_pages * options.page_size as usize
73            || self.total.is_some_and(|total| total != page.total_count)
74        {
75            return Err(fail());
76        }
77        self.total = Some(page.total_count);
78        for node in &page.nodes {
79            let id = id(node);
80            if id.is_empty() || !self.ids.insert(id.to_owned()) {
81                return Err(fail());
82            }
83        }
84        if self.ids.len() > page.total_count {
85            return Err(fail());
86        }
87        if page.page_info.has_next_page {
88            let cursor = page
89                .page_info
90                .end_cursor
91                .as_deref()
92                .filter(|c| !c.is_empty())
93                .ok_or_else(fail)?;
94            if page.nodes.is_empty()
95                || self.ids.len() >= page.total_count
96                || self.pages >= options.max_pages
97                || !self.cursors.insert(cursor.to_owned())
98            {
99                return Err(fail());
100            }
101            self.cursor = Some(cursor.to_owned());
102        } else {
103            if self.ids.len() != page.total_count {
104                return Err(fail());
105            }
106            self.cursor = None;
107        }
108        Ok(())
109    }
110}
111
112// Concrete callback type for collection calls that do not request progress.
113pub(crate) type NoProgress<T> = fn(&T) -> std::future::Ready<Result<()>>;