Skip to main content

interprex_github/code_reviews/
review_publications.rs

1use std::time::Duration;
2
3use async_trait::async_trait;
4use interprex::{
5    ChangeRequestNumber, ProviderError, ProviderTextRecord, Repository, Result, ReviewDiffSide,
6    ReviewId, ReviewPublicationKey, ReviewPublishingProvider, ReviewSubmission,
7    ReviewSubmissionDisposition, ReviewerApplication,
8};
9use octocrab::Page;
10use serde::{Deserialize, Serialize};
11use serde_json::json;
12use sha2::{Digest, Sha256};
13
14use crate::{
15    GithubProvider,
16    client::{ConfiguredApp, authenticated_external, is_not_found},
17};
18
19use super::change_requests::GithubReview;
20
21const PUBLICATION_NAMESPACE: &str = "interprex";
22const PUBLICATION_NAME: &str = "review-publication";
23const PUBLICATION_VERSION: u64 = 1;
24const PUBLICATION_IDENTIFIER: &str = "interprex:review-publication";
25const PUBLICATION_CARRIER: &str = "<!-- interprex:review-publication";
26const MAX_OBSERVED_PULL_REQUEST_COMMITS: usize = 250;
27const WRITE_TIMEOUT: Duration = Duration::from_secs(30);
28
29#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
30#[serde(deny_unknown_fields)]
31struct PublicationRecord {
32    version: u64,
33    key: String,
34    digest: String,
35    disposition: ReviewSubmissionDisposition,
36}
37
38#[derive(Deserialize)]
39struct PullRequestCommit {
40    sha: String,
41}
42
43struct Publication<'a> {
44    review: &'a GithubReview,
45    record: PublicationRecord,
46}
47
48#[derive(Clone, Copy)]
49struct PublicationScope<'a> {
50    app: &'a ConfiguredApp,
51    repository: &'a Repository,
52    number: ChangeRequestNumber,
53    reviewer: &'a ReviewerApplication,
54    key: &'a ReviewPublicationKey,
55    digest: Option<&'a str>,
56    submission: Option<&'a ReviewSubmission>,
57}
58
59impl GithubProvider {
60    fn reviewer_app(&self, reviewer: &ReviewerApplication) -> Result<&ConfiguredApp> {
61        let configured = self.configured_app(&reviewer.app().slug)?;
62        if configured.app_id.to_string() != reviewer.app().id.as_str() {
63            return Err(ProviderError::Configuration {
64                origin: configured.source.clone(),
65                reason: format!(
66                    "named app {} has APP_ID {}, but the resolved reviewer has provider app ID {}",
67                    reviewer.app().slug,
68                    configured.app_id,
69                    reviewer.app().id.as_str()
70                ),
71            });
72        }
73        Ok(configured)
74    }
75
76    fn matching_publication<'a>(
77        &self,
78        reviews: &'a [GithubReview],
79        reviewer: &ReviewerApplication,
80        key: &ReviewPublicationKey,
81        expected_digest: Option<&str>,
82        expected_submission: Option<&ReviewSubmission>,
83    ) -> Result<Option<Publication<'a>>> {
84        let mut matches = Vec::new();
85        for review in reviews {
86            if !same_reviewer(review, reviewer) {
87                continue;
88            }
89            if review.user.as_ref().and_then(|user| user.kind.as_deref()) != Some("Bot") {
90                return Err(reconciliation_error(
91                    "exact-identity publication review author is not a bot",
92                ));
93            }
94            let records = publication_records(&review.body)?;
95            if records.is_empty() {
96                if review.state == "PENDING"
97                    && expected_submission.is_some_and(|submission| {
98                        review.commit_id == submission.revision().head_sha
99                            && review.body.starts_with(submission.summary())
100                    })
101                {
102                    return Err(reconciliation_error(
103                        "an exact-identity pending review matches the submission but has no publication record",
104                    ));
105                }
106                continue;
107            }
108            if records.len() != 1 {
109                return Err(reconciliation_error(format!(
110                    "exact-identity review {} contains {} publication records",
111                    review.node_id,
112                    records.len()
113                )));
114            }
115            for record in records {
116                if record.key == key.as_str() {
117                    matches.push(Publication { review, record });
118                }
119            }
120        }
121
122        let publication = match matches.len() {
123            0 => return Ok(None),
124            1 => matches.pop().expect("one publication"),
125            count => {
126                return Err(reconciliation_error(format!(
127                    "found {count} exact-identity reviews carrying publication key {}",
128                    key.as_str()
129                )));
130            }
131        };
132        validate_review_record(publication.review, &publication.record)?;
133        if let Some(expected_digest) = expected_digest
134            && publication.record.digest != expected_digest
135        {
136            return Err(ProviderError::InvalidInput {
137                provider: "github",
138                fact: format!(
139                    "review publication key {} already identifies a different submission",
140                    key.as_str()
141                ),
142            });
143        }
144        if let Some(submission) = expected_submission
145            && (publication.review.commit_id != submission.revision().head_sha
146                || publication.record.disposition != submission.disposition())
147        {
148            return Err(reconciliation_error(
149                "matching publication record contradicts the submitted revision or disposition",
150            ));
151        }
152        Ok(Some(publication))
153    }
154
155    async fn read_matching_publication(
156        &self,
157        scope: PublicationScope<'_>,
158    ) -> Result<Option<OwnedPublication>> {
159        let reviews = self
160            .github_reviews_with(&scope.app.read, scope.repository, scope.number)
161            .await?;
162        self.matching_publication(
163            &reviews,
164            scope.reviewer,
165            scope.key,
166            scope.digest,
167            scope.submission,
168        )
169        .map(|publication| publication.map(OwnedPublication::from))
170    }
171
172    async fn require_review_revision(
173        &self,
174        app: &ConfiguredApp,
175        repository: &Repository,
176        number: ChangeRequestNumber,
177        revision: &str,
178    ) -> Result<()> {
179        let page: Page<PullRequestCommit> = app
180            .read
181            .get(
182                format!("/repos/{repository}/pulls/{}/commits", number.get()),
183                Some(&[("per_page", 100)]),
184            )
185            .await
186            .map_err(|error| {
187                if is_not_found(&error) {
188                    ProviderError::NotFound {
189                        entity: format!("change request {} in {repository}", number.get()),
190                    }
191                } else {
192                    authenticated_external("read change request revisions", &error)
193                }
194            })?;
195        let commits = app
196            .read
197            .all_pages(page)
198            .await
199            .map_err(|error| authenticated_external("read change request revisions", &error))?;
200        if commits.iter().any(|commit| commit.sha == revision) {
201            return Ok(());
202        }
203        if commits.len() >= MAX_OBSERVED_PULL_REQUEST_COMMITS {
204            return Err(reconciliation_error(
205                "GitHub capped the change request revision observation before the requested revision was found",
206            ));
207        }
208        Err(ProviderError::NotFound {
209            entity: format!(
210                "revision {revision} on change request {} in {repository}",
211                number.get()
212            ),
213        })
214    }
215
216    async fn submit_publication(
217        &self,
218        scope: PublicationScope<'_>,
219        pending: &OwnedPublication,
220    ) -> Result<ReviewId> {
221        let event = github_event(pending.record.disposition);
222        let path = format!(
223            "/repos/{}/pulls/{}/reviews/{}/events",
224            scope.repository,
225            scope.number.get(),
226            pending.numeric_id
227        );
228        let write = tokio::time::timeout(
229            WRITE_TIMEOUT,
230            scope
231                .app
232                .write
233                .post::<_, serde_json::Value>(path, Some(&json!({ "event": event }))),
234        )
235        .await;
236        let write_error = match write {
237            Ok(Ok(_)) => None,
238            Ok(Err(error)) => Some(authenticated_external("submit review", &error)),
239            Err(_) => Some(reconciliation_error("submit review timed out")),
240        };
241
242        match self.read_matching_publication(scope).await? {
243            Some(publication) if publication.review_id != pending.review_id => Err(
244                reconciliation_error("GitHub reread a different review after submission"),
245            ),
246            Some(publication) if publication.is_submitted() => Ok(publication.review_id),
247            Some(_) => Err(write_error.unwrap_or_else(|| {
248                reconciliation_error("GitHub accepted review submission but reread it as pending")
249            })),
250            None => Err(write_error.unwrap_or_else(|| {
251                reconciliation_error("GitHub accepted review submission but reread found no review")
252            })),
253        }
254    }
255
256    async fn finish_publication(
257        &self,
258        scope: PublicationScope<'_>,
259        publication: OwnedPublication,
260    ) -> Result<ReviewId> {
261        if publication.is_submitted() {
262            return Ok(publication.review_id);
263        }
264        self.submit_publication(scope, &publication).await
265    }
266
267    async fn reconcile_create(
268        &self,
269        scope: PublicationScope<'_>,
270        create_error: ProviderError,
271    ) -> Result<ReviewId> {
272        match self.read_matching_publication(scope).await? {
273            Some(publication) => self.finish_publication(scope, publication).await,
274            None => Err(create_error),
275        }
276    }
277}
278
279#[async_trait]
280impl ReviewPublishingProvider for GithubProvider {
281    async fn publish_review(
282        &self,
283        repository: &Repository,
284        number: ChangeRequestNumber,
285        reviewer: &ReviewerApplication,
286        submission: &ReviewSubmission,
287    ) -> Result<ReviewId> {
288        let app = self.reviewer_app(reviewer)?;
289        validate_submission_summary(submission.summary())?;
290        let digest = submission_digest(submission)?;
291        let scope = PublicationScope {
292            app,
293            repository,
294            number,
295            reviewer,
296            key: submission.publication_key(),
297            digest: Some(&digest),
298            submission: Some(submission),
299        };
300        if let Some(publication) = self.read_matching_publication(scope).await? {
301            if publication.is_submitted() {
302                return Ok(publication.review_id);
303            }
304            self.require_review_revision(app, repository, number, &submission.revision().head_sha)
305                .await?;
306            return self.finish_publication(scope, publication).await;
307        }
308
309        self.require_review_revision(app, repository, number, &submission.revision().head_sha)
310            .await?;
311
312        let record = PublicationRecord {
313            version: PUBLICATION_VERSION,
314            key: submission.publication_key().as_str().to_owned(),
315            digest: digest.clone(),
316            disposition: submission.disposition(),
317        };
318        let body = publication_body(submission.summary(), &record)?;
319        let comments = submission
320            .findings()
321            .iter()
322            .map(|finding| {
323                json!({
324                    "path": finding.path(),
325                    "line": finding.line().get(),
326                    "side": match finding.side() {
327                        ReviewDiffSide::Left => "LEFT",
328                        ReviewDiffSide::Right => "RIGHT",
329                    },
330                    "body": finding.body(),
331                })
332            })
333            .collect::<Vec<_>>();
334        let path = format!("/repos/{repository}/pulls/{}/reviews", number.get());
335        let create = tokio::time::timeout(
336            WRITE_TIMEOUT,
337            app.write.post::<_, GithubReview>(
338                path,
339                Some(&json!({
340                    "commit_id": submission.revision().head_sha,
341                    "body": body,
342                    "comments": comments,
343                })),
344            ),
345        )
346        .await;
347
348        let created = match create {
349            Ok(Ok(review)) => match owned_publication(
350                review,
351                reviewer,
352                submission.publication_key(),
353                &digest,
354                submission,
355            ) {
356                Ok(publication) => publication,
357                Err(response_error) => {
358                    return self.reconcile_create(scope, response_error).await;
359                }
360            },
361            Ok(Err(error)) => {
362                let create_error = create_review_error(&error);
363                return self.reconcile_create(scope, create_error).await;
364            }
365            Err(_) => {
366                let create_error = reconciliation_error("create review timed out");
367                return self.reconcile_create(scope, create_error).await;
368            }
369        };
370
371        if !created.is_pending() {
372            return Err(reconciliation_error(
373                "GitHub create-review response was not pending",
374            ));
375        }
376        self.submit_publication(scope, &created).await
377    }
378
379    async fn resume_review_publication(
380        &self,
381        repository: &Repository,
382        number: ChangeRequestNumber,
383        reviewer: &ReviewerApplication,
384        key: &ReviewPublicationKey,
385    ) -> Result<Option<ReviewId>> {
386        let app = self.reviewer_app(reviewer)?;
387        let scope = PublicationScope {
388            app,
389            repository,
390            number,
391            reviewer,
392            key,
393            digest: None,
394            submission: None,
395        };
396        let Some(publication) = self.read_matching_publication(scope).await? else {
397            return Ok(None);
398        };
399        self.finish_publication(scope, publication).await.map(Some)
400    }
401}
402
403fn validate_submission_summary(summary: &str) -> Result<()> {
404    if summary.contains(PUBLICATION_IDENTIFIER) {
405        return Err(ProviderError::InvalidInput {
406            provider: "github",
407            fact: "review summary contains the reserved interprex:review-publication identifier"
408                .to_owned(),
409        });
410    }
411    Ok(())
412}
413
414#[derive(Clone)]
415struct OwnedPublication {
416    numeric_id: u64,
417    review_id: ReviewId,
418    state: String,
419    record: PublicationRecord,
420}
421
422impl OwnedPublication {
423    fn is_pending(&self) -> bool {
424        self.state == "PENDING"
425    }
426
427    fn is_submitted(&self) -> bool {
428        !self.is_pending()
429    }
430}
431
432impl From<Publication<'_>> for OwnedPublication {
433    fn from(publication: Publication<'_>) -> Self {
434        Self {
435            numeric_id: publication.review.id,
436            review_id: ReviewId::new(publication.review.node_id.clone())
437                .expect("validated review identifier"),
438            state: publication.review.state.clone(),
439            record: publication.record,
440        }
441    }
442}
443
444fn owned_publication(
445    review: GithubReview,
446    reviewer: &ReviewerApplication,
447    key: &ReviewPublicationKey,
448    digest: &str,
449    submission: &ReviewSubmission,
450) -> Result<OwnedPublication> {
451    if !same_reviewer(&review, reviewer) {
452        return Err(reconciliation_error(
453            "GitHub create-review response has a different reviewer identity",
454        ));
455    }
456    let mut records = publication_records(&review.body)?;
457    if records.len() != 1 || records[0].key != key.as_str() {
458        return Err(reconciliation_error(format!(
459            "GitHub create-review response contains {} matching publication records",
460            records
461                .iter()
462                .filter(|record| record.key == key.as_str())
463                .count()
464        )));
465    }
466    let record = records.pop().expect("one matching publication record");
467    validate_review_record(&review, &record)?;
468    if record.digest != digest
469        || record.disposition != submission.disposition()
470        || review.commit_id != submission.revision().head_sha
471    {
472        return Err(reconciliation_error(
473            "GitHub create-review response contradicts the requested digest, revision, or disposition",
474        ));
475    }
476    let review_id = ReviewId::new(review.node_id.clone())
477        .map_err(|error| reconciliation_error(error.to_string()))?;
478    Ok(OwnedPublication {
479        numeric_id: review.id,
480        review_id,
481        state: review.state,
482        record,
483    })
484}
485
486fn same_reviewer(review: &GithubReview, reviewer: &ReviewerApplication) -> bool {
487    // GitHub omits `performed_via_github_app` on pending reviews, so the bot
488    // user is what identifies the application's actor; the app id is checked
489    // only on the responses that carry it.
490    review
491        .user
492        .as_ref()
493        .is_some_and(|user| user.node_id == reviewer.bot().id.as_str())
494        && review
495            .performed_via_github_app
496            .as_ref()
497            .is_none_or(|app| app.id.to_string() == reviewer.app().id.as_str())
498}
499
500fn publication_records(body: &str) -> Result<Vec<PublicationRecord>> {
501    let carrier_count = body.match_indices(PUBLICATION_CARRIER).count();
502    let records = super::text_records::extract_records(body)
503        .into_iter()
504        .filter(|record| {
505            record.namespace() == PUBLICATION_NAMESPACE && record.name() == PUBLICATION_NAME
506        })
507        .map(|record| {
508            serde_json::from_value::<PublicationRecord>(record.value().clone()).map_err(|error| {
509                reconciliation_error(format!("malformed publication record: {error}"))
510            })
511        })
512        .collect::<Result<Vec<_>>>()?;
513    if records.len() != carrier_count {
514        return Err(reconciliation_error(
515            "malformed publication record carrier in exact-identity review",
516        ));
517    }
518    for record in &records {
519        validate_record(record)?;
520    }
521    Ok(records)
522}
523
524fn validate_record(record: &PublicationRecord) -> Result<()> {
525    let digest = record.digest.strip_prefix("sha256:");
526    if record.version != PUBLICATION_VERSION
527        || record.key.trim().is_empty()
528        || digest.is_none_or(|value| {
529            value.len() != 64 || !value.bytes().all(|byte| byte.is_ascii_hexdigit())
530        })
531    {
532        return Err(reconciliation_error(
533            "publication record has an unsupported version, blank key, or invalid digest",
534        ));
535    }
536    Ok(())
537}
538
539fn validate_review_record(review: &GithubReview, record: &PublicationRecord) -> Result<()> {
540    if review.id == 0 || review.node_id.is_empty() || review.commit_id.trim().is_empty() {
541        return Err(reconciliation_error(
542            "publication review has an invalid identifier or revision",
543        ));
544    }
545    match review.state.as_str() {
546        "PENDING" if review.submitted_at.is_none() => Ok(()),
547        "PENDING" => Err(reconciliation_error(
548            "pending publication review has a submission time",
549        )),
550        state if state == github_state(record.disposition) && review.submitted_at.is_some() => {
551            Ok(())
552        }
553        state if state == github_state(record.disposition) => Err(reconciliation_error(
554            "submitted publication review has no submission time",
555        )),
556        state => Err(reconciliation_error(format!(
557            "publication record intends {} but GitHub reports {state}",
558            github_state(record.disposition)
559        ))),
560    }
561}
562
563fn publication_body(summary: &str, record: &PublicationRecord) -> Result<String> {
564    let record = ProviderTextRecord::new(
565        PUBLICATION_NAMESPACE,
566        PUBLICATION_NAME,
567        serde_json::to_value(record).map_err(|error| reconciliation_error(error.to_string()))?,
568    )
569    .map_err(|error| reconciliation_error(error.to_string()))?;
570    Ok(super::text_records::embed_record(summary, &record))
571}
572
573fn submission_digest(submission: &ReviewSubmission) -> Result<String> {
574    let bytes = serde_json::to_vec(submission)
575        .map_err(|error| reconciliation_error(format!("serialize review submission: {error}")))?;
576    Ok(format!("sha256:{:x}", Sha256::digest(bytes)))
577}
578
579fn create_review_error(error: &octocrab::Error) -> ProviderError {
580    if let octocrab::Error::GitHub { source, .. } = error
581        && source.status_code.as_u16() == 422
582        && let Some(errors) = source.errors.as_deref()
583        && !errors.is_empty()
584        && let Some(mut fields) = errors
585            .iter()
586            .map(review_validation_field)
587            .collect::<Option<Vec<_>>>()
588    {
589        fields.sort_unstable();
590        fields.dedup();
591        return ProviderError::InvalidInput {
592            provider: "github",
593            fact: format!("GitHub rejected these review fields: {}", fields.join(", ")),
594        };
595    }
596    authenticated_external("create review", error)
597}
598
599fn review_validation_field(error: &serde_json::Value) -> Option<&'static str> {
600    let resource = error.get("resource")?.as_str()?;
601    let field = error.get("field")?.as_str()?;
602    let code = error.get("code")?.as_str()?;
603    if !matches!(
604        code,
605        "custom" | "invalid" | "missing" | "missing_field" | "unprocessable"
606    ) {
607        return None;
608    }
609    match (resource, field) {
610        ("PullRequestReview", "body") => Some("body"),
611        ("PullRequestReview", "comments") => Some("comments"),
612        ("PullRequestReview", "commit_id") => Some("commit_id"),
613        ("PullRequestReview", "event") => Some("event"),
614        ("PullRequestReviewComment", "body") => Some("comments.body"),
615        ("PullRequestReviewComment", "line") => Some("comments.line"),
616        ("PullRequestReviewComment", "path") => Some("comments.path"),
617        ("PullRequestReviewComment", "position") => Some("comments.position"),
618        ("PullRequestReviewComment", "side") => Some("comments.side"),
619        ("PullRequestReviewComment", "start_line") => Some("comments.start_line"),
620        ("PullRequestReviewComment", "start_side") => Some("comments.start_side"),
621        _ => None,
622    }
623}
624
625fn github_event(disposition: ReviewSubmissionDisposition) -> &'static str {
626    match disposition {
627        ReviewSubmissionDisposition::Approved => "APPROVE",
628        ReviewSubmissionDisposition::ChangesRequested => "REQUEST_CHANGES",
629        ReviewSubmissionDisposition::Commented => "COMMENT",
630    }
631}
632
633fn github_state(disposition: ReviewSubmissionDisposition) -> &'static str {
634    match disposition {
635        ReviewSubmissionDisposition::Approved => "APPROVED",
636        ReviewSubmissionDisposition::ChangesRequested => "CHANGES_REQUESTED",
637        ReviewSubmissionDisposition::Commented => "COMMENTED",
638    }
639}
640
641fn reconciliation_error(message: impl Into<String>) -> ProviderError {
642    ProviderError::External {
643        provider: "github",
644        operation: "reconcile review publication",
645        message: message.into(),
646    }
647}