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