Skip to main content

github_rust/github/
work_items.rs

1//! Open issues and pull requests, with bounded multi-repository traversal.
2use super::{
3    accounts::{Count, query, require_token, validate_owner},
4    pagination::{Connection, FetchOptions, Tracker},
5};
6use crate::{GitHubClient, GitHubError, Result};
7use chrono::{DateTime, Utc};
8use futures_util::{StreamExt, stream::FuturesUnordered};
9use serde::{Deserialize, Serialize};
10use serde_json::json;
11use std::collections::HashSet;
12
13/// Explicit scope for collection calls. All scopes are validated before sending requests.
14#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
15pub struct RepositoryCoordinates {
16    pub owner: String,
17    pub name: String,
18}
19impl RepositoryCoordinates {
20    pub fn new(owner: impl Into<String>, name: impl Into<String>) -> Result<Self> {
21        let value = Self {
22            owner: owner.into(),
23            name: name.into(),
24        };
25        value.validate()?;
26        Ok(value)
27    }
28    fn validate(&self) -> Result<()> {
29        validate_owner(&self.owner)?;
30        if self.name.is_empty()
31            || self.name.len() > 100
32            || matches!(self.name.as_str(), "." | "..")
33            || !self
34                .name
35                .bytes()
36                .all(|c| c.is_ascii_alphanumeric() || matches!(c, b'.' | b'_' | b'-'))
37        {
38            return Err(GitHubError::InvalidInput("Invalid repository name".into()));
39        }
40        Ok(())
41    }
42}
43impl super::RepositorySummary {
44    pub fn coordinates(&self) -> Result<RepositoryCoordinates> {
45        let (owner, name) =
46            crate::parse_repository(&self.name_with_owner).map_err(GitHubError::InvalidInput)?;
47        RepositoryCoordinates::new(owner, name)
48    }
49}
50#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
51pub struct RepositoryReference {
52    pub node_id: String,
53    pub name: String,
54    pub name_with_owner: String,
55    pub is_archived: bool,
56}
57/// An issue author may be a user, organization or bot; deleted authors are `None`.
58#[derive(Debug, Clone, Serialize, Deserialize)]
59pub struct Actor {
60    pub login: String,
61}
62#[derive(Debug, Clone, Serialize, Deserialize)]
63pub struct Label {
64    pub name: String,
65    pub color: String,
66}
67#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
68#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
69pub enum ReviewDecision {
70    Approved,
71    ChangesRequested,
72    ReviewRequired,
73}
74
75/// A validated repository page; callbacks across repositories arrive in completion order.
76/// Only successful completion of the entire call certifies traversal of all scopes.
77#[derive(Debug, Clone, Serialize, Deserialize)]
78pub struct WorkItemPage<T> {
79    pub repository: RepositoryReference,
80    pub items: Vec<T>,
81    pub total_count: usize,
82    pub has_next_page: bool,
83}
84
85/// An open issue with complete labels and assignees.
86#[derive(Debug, Clone, Serialize, Deserialize)]
87pub struct Issue {
88    pub node_id: String,
89    pub number: u64,
90    pub title: String,
91    pub url: String,
92    pub created_at: DateTime<Utc>,
93    pub updated_at: DateTime<Utc>,
94    pub author: Option<Actor>,
95    pub repository: RepositoryReference,
96    pub labels: Vec<Label>,
97    pub assignees: Vec<Actor>,
98    pub comment_count: u32,
99}
100
101/// An open pull request with complete labels and assignees.
102#[derive(Debug, Clone, Serialize, Deserialize)]
103pub struct PullRequest {
104    pub node_id: String,
105    pub number: u64,
106    pub title: String,
107    pub url: String,
108    pub created_at: DateTime<Utc>,
109    pub updated_at: DateTime<Utc>,
110    pub author: Option<Actor>,
111    pub repository: RepositoryReference,
112    pub labels: Vec<Label>,
113    pub assignees: Vec<Actor>,
114    pub comment_count: u32,
115    pub is_draft: bool,
116    pub review_decision: Option<ReviewDecision>,
117}
118
119#[derive(Deserialize)]
120#[serde(rename_all = "camelCase")]
121pub(crate) struct NodeDto {
122    id: String,
123    number: u64,
124    title: String,
125    url: String,
126    created_at: DateTime<Utc>,
127    updated_at: DateTime<Utc>,
128    author: Option<Actor>,
129    labels: Metadata<Label>,
130    assignees: Metadata<Actor>,
131    comments: Count,
132    is_draft: Option<bool>,
133    review_decision: Option<ReviewDecision>,
134}
135#[derive(Deserialize)]
136#[serde(rename_all = "camelCase")]
137struct Metadata<T> {
138    nodes: Vec<T>,
139    total_count: usize,
140}
141impl<T> Metadata<T> {
142    fn complete(self) -> Result<Vec<T>> {
143        if self.nodes.len() != self.total_count {
144            return Err(GitHubError::PaginationError(
145                "Label or assignee count does not match returned nodes; refusing incomplete or inconsistent metadata".into(),
146            ));
147        }
148        Ok(self.nodes)
149    }
150}
151pub(crate) trait Item: Sized {
152    const ISSUES: bool;
153    fn from_wire(node: NodeDto, repository: &RepositoryReference) -> Result<Self>;
154    fn id(&self) -> &str;
155    fn updated(&self) -> DateTime<Utc>;
156}
157
158impl Item for Issue {
159    const ISSUES: bool = true;
160    fn from_wire(n: NodeDto, repository: &RepositoryReference) -> Result<Self> {
161        Ok(Self {
162            node_id: n.id,
163            number: n.number,
164            title: n.title,
165            url: n.url,
166            created_at: n.created_at,
167            updated_at: n.updated_at,
168            author: n.author,
169            repository: repository.clone(),
170            labels: n.labels.complete()?,
171            assignees: n.assignees.complete()?,
172            comment_count: n.comments.total_count,
173        })
174    }
175    fn id(&self) -> &str {
176        &self.node_id
177    }
178    fn updated(&self) -> DateTime<Utc> {
179        self.updated_at
180    }
181}
182
183impl Item for PullRequest {
184    const ISSUES: bool = false;
185    fn from_wire(n: NodeDto, repository: &RepositoryReference) -> Result<Self> {
186        Ok(Self {
187            node_id: n.id,
188            number: n.number,
189            title: n.title,
190            url: n.url,
191            created_at: n.created_at,
192            updated_at: n.updated_at,
193            author: n.author,
194            repository: repository.clone(),
195            labels: n.labels.complete()?,
196            assignees: n.assignees.complete()?,
197            comment_count: n.comments.total_count,
198            is_draft: n
199                .is_draft
200                .ok_or_else(|| GitHubError::ParseError("Missing PR draft status".into()))?,
201            review_decision: n.review_decision,
202        })
203    }
204    fn id(&self) -> &str {
205        &self.node_id
206    }
207    fn updated(&self) -> DateTime<Utc> {
208        self.updated_at
209    }
210}
211
212struct Traversal {
213    scope: RepositoryCoordinates,
214    identity: Option<RepositoryReference>,
215    tracker: Tracker,
216}
217async fn next_page<T: Item>(
218    client: &GitHubClient,
219    options: FetchOptions,
220    mut traversal: Traversal,
221) -> Result<(Traversal, WorkItemPage<T>)> {
222    #[derive(Deserialize)]
223    struct Data {
224        repository: Option<RepositoryDto>,
225    }
226    #[derive(Deserialize)]
227    #[serde(rename_all = "camelCase")]
228    struct RepositoryDto {
229        id: String,
230        name: String,
231        name_with_owner: String,
232        is_archived: bool,
233        issues: Option<Connection<NodeDto>>,
234        pull_requests: Option<Connection<NodeDto>>,
235    }
236    let scope = &traversal.scope;
237    let data: Data = query(
238        client,
239        include_str!("queries/work_items.graphql"),
240        json!({
241            "owner": scope.owner, "name": scope.name, "cursor": traversal.tracker.cursor,
242            "first": options.page_size, "issues": T::ISSUES
243        }),
244    )
245    .await
246    .map_err(|e| e.with_repository_context(&scope.owner, &scope.name))?;
247    let repo = data
248        .repository
249        .ok_or_else(|| GitHubError::NotFoundError(format!("{}/{}", scope.owner, scope.name)))?;
250    let identity = RepositoryReference {
251        node_id: repo.id,
252        name: repo.name,
253        name_with_owner: repo.name_with_owner,
254        is_archived: repo.is_archived,
255    };
256    if identity.node_id.is_empty()
257        || !identity.name.eq_ignore_ascii_case(&scope.name)
258        || !identity
259            .name_with_owner
260            .eq_ignore_ascii_case(&format!("{}/{}", scope.owner, scope.name))
261        || traversal
262            .identity
263            .as_ref()
264            .is_some_and(|previous| previous != &identity)
265    {
266        return Err(GitHubError::PaginationError(
267            "Repository identity or archive status changed during pagination".into(),
268        ));
269    }
270    let connection = if T::ISSUES {
271        repo.issues
272    } else {
273        repo.pull_requests
274    }
275    .ok_or_else(|| GitHubError::ParseError("Missing work-item connection".into()))?;
276    traversal.tracker.accept(&connection, options, |n| &n.id)?;
277    let items = connection
278        .nodes
279        .into_iter()
280        .map(|n| T::from_wire(n, &identity))
281        .collect::<Result<Vec<_>>>()?;
282    traversal.identity = Some(identity.clone());
283    Ok((
284        traversal,
285        WorkItemPage {
286            repository: identity,
287            items,
288            total_count: connection.total_count,
289            has_next_page: connection.page_info.has_next_page,
290        },
291    ))
292}
293
294pub(crate) async fn collect<T, F>(
295    client: &GitHubClient,
296    scopes: &[RepositoryCoordinates],
297    options: FetchOptions,
298    mut progress: Option<F>,
299) -> Result<Vec<T>>
300where
301    T: Item,
302    F: AsyncFnMut(&WorkItemPage<T>) -> Result<()>,
303{
304    let mut names = HashSet::new();
305    for scope in scopes {
306        scope.validate()?;
307        if !names.insert(format!("{}/{}", scope.owner, scope.name).to_ascii_lowercase()) {
308            return Err(GitHubError::InvalidInput(
309                "Duplicate repository scope".into(),
310            ));
311        }
312    }
313    if scopes.is_empty() {
314        return Ok(vec![]);
315    }
316    require_token(client)?;
317    let mut scopes = scopes.iter().cloned().map(|scope| Traversal {
318        scope,
319        identity: None,
320        tracker: Tracker::default(),
321    });
322    let mut pending = FuturesUnordered::new();
323    for traversal in scopes.by_ref().take(options.max_concurrent_repositories) {
324        pending.push(next_page::<T>(client, options, traversal));
325    }
326    let mut result = vec![];
327    let mut ids = HashSet::new();
328    while let Some(page) = pending.next().await {
329        let (traversal, page) = page?;
330        for item in &page.items {
331            if !ids.insert(item.id().to_owned()) {
332                return Err(GitHubError::PaginationError(
333                    "Work item appeared in multiple repository scopes".into(),
334                ));
335            }
336        }
337        if let Some(callback) = &mut progress {
338            callback(&page).await?;
339        }
340        result.extend(page.items);
341        // No spawned tasks: callback backpressure stops polling requests, and dropping
342        // this future cancels all pending traversal, including on any callback error.
343        if traversal.tracker.cursor.is_some() {
344            pending.push(next_page::<T>(client, options, traversal));
345        } else if let Some(next) = scopes.next() {
346            pending.push(next_page::<T>(client, options, next));
347        }
348    }
349    result.sort_by(|a: &T, b| {
350        b.updated()
351            .cmp(&a.updated())
352            .then_with(|| a.id().cmp(b.id()))
353    });
354    Ok(result)
355}