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
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}