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