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 review
488 .performed_via_github_app
489 .as_ref()
490 .is_some_and(|app| app.id.to_string() == reviewer.app().id.as_str())
491 && review
492 .user
493 .as_ref()
494 .is_some_and(|user| user.node_id == reviewer.bot().id.as_str())
495}
496
497fn publication_records(body: &str) -> Result<Vec<PublicationRecord>> {
498 let carrier_count = body.match_indices(PUBLICATION_CARRIER).count();
499 let records = super::text_records::extract_records(body)
500 .into_iter()
501 .filter(|record| {
502 record.namespace() == PUBLICATION_NAMESPACE && record.name() == PUBLICATION_NAME
503 })
504 .map(|record| {
505 serde_json::from_value::<PublicationRecord>(record.value().clone()).map_err(|error| {
506 reconciliation_error(format!("malformed publication record: {error}"))
507 })
508 })
509 .collect::<Result<Vec<_>>>()?;
510 if records.len() != carrier_count {
511 return Err(reconciliation_error(
512 "malformed publication record carrier in exact-identity review",
513 ));
514 }
515 for record in &records {
516 validate_record(record)?;
517 }
518 Ok(records)
519}
520
521fn validate_record(record: &PublicationRecord) -> Result<()> {
522 let digest = record.digest.strip_prefix("sha256:");
523 if record.version != PUBLICATION_VERSION
524 || record.key.trim().is_empty()
525 || digest.is_none_or(|value| {
526 value.len() != 64 || !value.bytes().all(|byte| byte.is_ascii_hexdigit())
527 })
528 {
529 return Err(reconciliation_error(
530 "publication record has an unsupported version, blank key, or invalid digest",
531 ));
532 }
533 Ok(())
534}
535
536fn validate_review_record(review: &GithubReview, record: &PublicationRecord) -> Result<()> {
537 if review.id == 0 || review.node_id.is_empty() || review.commit_id.trim().is_empty() {
538 return Err(reconciliation_error(
539 "publication review has an invalid identifier or revision",
540 ));
541 }
542 match review.state.as_str() {
543 "PENDING" if review.submitted_at.is_none() => Ok(()),
544 "PENDING" => Err(reconciliation_error(
545 "pending publication review has a submission time",
546 )),
547 state if state == github_state(record.disposition) && review.submitted_at.is_some() => {
548 Ok(())
549 }
550 state if state == github_state(record.disposition) => Err(reconciliation_error(
551 "submitted publication review has no submission time",
552 )),
553 state => Err(reconciliation_error(format!(
554 "publication record intends {} but GitHub reports {state}",
555 github_state(record.disposition)
556 ))),
557 }
558}
559
560fn publication_body(summary: &str, record: &PublicationRecord) -> Result<String> {
561 let record = ProviderTextRecord::new(
562 PUBLICATION_NAMESPACE,
563 PUBLICATION_NAME,
564 serde_json::to_value(record).map_err(|error| reconciliation_error(error.to_string()))?,
565 )
566 .map_err(|error| reconciliation_error(error.to_string()))?;
567 Ok(super::text_records::embed_record(summary, &record))
568}
569
570fn submission_digest(submission: &ReviewSubmission) -> Result<String> {
571 let bytes = serde_json::to_vec(submission)
572 .map_err(|error| reconciliation_error(format!("serialize review submission: {error}")))?;
573 Ok(format!("sha256:{:x}", Sha256::digest(bytes)))
574}
575
576fn create_review_error(error: &octocrab::Error) -> ProviderError {
577 if let octocrab::Error::GitHub { source, .. } = error
578 && source.status_code.as_u16() == 422
579 && let Some(errors) = source.errors.as_deref()
580 && !errors.is_empty()
581 && let Some(mut fields) = errors
582 .iter()
583 .map(review_validation_field)
584 .collect::<Option<Vec<_>>>()
585 {
586 fields.sort_unstable();
587 fields.dedup();
588 return ProviderError::InvalidInput {
589 provider: "github",
590 fact: format!("GitHub rejected these review fields: {}", fields.join(", ")),
591 };
592 }
593 authenticated_external("create review", error)
594}
595
596fn review_validation_field(error: &serde_json::Value) -> Option<&'static str> {
597 let resource = error.get("resource")?.as_str()?;
598 let field = error.get("field")?.as_str()?;
599 let code = error.get("code")?.as_str()?;
600 if !matches!(
601 code,
602 "custom" | "invalid" | "missing" | "missing_field" | "unprocessable"
603 ) {
604 return None;
605 }
606 match (resource, field) {
607 ("PullRequestReview", "body") => Some("body"),
608 ("PullRequestReview", "comments") => Some("comments"),
609 ("PullRequestReview", "commit_id") => Some("commit_id"),
610 ("PullRequestReview", "event") => Some("event"),
611 ("PullRequestReviewComment", "body") => Some("comments.body"),
612 ("PullRequestReviewComment", "line") => Some("comments.line"),
613 ("PullRequestReviewComment", "path") => Some("comments.path"),
614 ("PullRequestReviewComment", "position") => Some("comments.position"),
615 ("PullRequestReviewComment", "side") => Some("comments.side"),
616 ("PullRequestReviewComment", "start_line") => Some("comments.start_line"),
617 ("PullRequestReviewComment", "start_side") => Some("comments.start_side"),
618 _ => None,
619 }
620}
621
622fn github_event(disposition: ReviewSubmissionDisposition) -> &'static str {
623 match disposition {
624 ReviewSubmissionDisposition::Approved => "APPROVE",
625 ReviewSubmissionDisposition::ChangesRequested => "REQUEST_CHANGES",
626 ReviewSubmissionDisposition::Commented => "COMMENT",
627 }
628}
629
630fn github_state(disposition: ReviewSubmissionDisposition) -> &'static str {
631 match disposition {
632 ReviewSubmissionDisposition::Approved => "APPROVED",
633 ReviewSubmissionDisposition::ChangesRequested => "CHANGES_REQUESTED",
634 ReviewSubmissionDisposition::Commented => "COMMENTED",
635 }
636}
637
638fn reconciliation_error(message: impl Into<String>) -> ProviderError {
639 ProviderError::External {
640 provider: "github",
641 operation: "reconcile review publication",
642 message: message.into(),
643 }
644}