@learnpack/learnpack 5.0.353 → 5.0.355

package/src/utils/descriptions/resumePublication.ts

@@ -1,200 +1,217 @@
-import {
-  abandonJournal,
-  finalizeJournal,
-  incrementAttempts,
-  isJournalStale,
-  JournalStorage,
-  markStage,
-  PublishJournal,
-} from "../publishJournal"
-import { PackageManifest } from "../packageManifest"
-import {
-  buildPackageManifestUpdatedEvent,
-  fetchPackageInfo,
-  sendPublishEvent,
-} from "../publishEvents"
-import {
-  CourseDescriptionsStorage,
-  GenerateCourseDescriptionsOptions,
-} from "./generateCourseDescriptions"
-import { runPublishDescriptionsStage } from "./publishStage"
-
-/**
- * Recovery of a publication whose background stage never finished.
- *
- * The stage runs inside the web process, so a dyno restart mid-flight leaves a
- * package published but not described, and — worse — breathecode waiting for a
- * manifest event that was promised and will never arrive. Content-wise the
- * missing descriptions would eventually be picked up by the next publication,
- * but the promised event has no such second chance: emitting it is the reason
- * this exists.
- */
-
-export const MAX_SWEEP_ATTEMPTS = 3
-
-/** Only resume publications nobody is working on any more. */
-export const DEFAULT_STALE_AFTER_MS = 15 * 60 * 1000
-
-export type ResumeOutcome =
-  | "skipped-recent"
-  | "skipped-abandoned"
-  | "abandoned"
-  | "resumed"
-  | "nothing-to-do";
-
-export type ResumeDeps = {
-  journalStorage: JournalStorage;
-  publishedStorage: CourseDescriptionsStorage;
-  draftStorage: CourseDescriptionsStorage;
-  rigobotToken: string;
-  breathecodeToken?: string;
-  staleAfterMs?: number;
-  now?: number;
-  /** Injection points for tests. */
-  emit?: typeof sendPublishEvent;
-  readPackageInfo?: typeof fetchPackageInfo;
-  generate?: GenerateCourseDescriptionsOptions["generate"];
-};
-
-function isDone(
-  journal: PublishJournal,
-  stage: "descriptions" | "gcsMirror" | "manifestEvent"
-): boolean {
-  return journal.stages[stage].status === "done"
-}
-
-/**
- * Whether breathecode is still owed a manifest event: one was promised (the
- * publish event announced `queued`) and it never went out.
- */
-export function owesManifestEvent(journal: PublishJournal): boolean {
-  const promised =
-    (
-      journal.stages.publishedEvent.meta as
-        | { descriptions?: string }
-        | undefined
-    )?.descriptions === "queued"
-  return promised && !isDone(journal, "manifestEvent")
-}
-
-export async function resumePublication(
-  journal: PublishJournal,
-  deps: ResumeDeps
-): Promise<ResumeOutcome> {
-  const { journalStorage } = deps
-  const now = deps.now ?? Date.now()
-
-  if (journal.abandoned) {
-    return "skipped-abandoned"
-  }
-
-  // A publication still in flight would race with its own stage.
-  if (
-    !isJournalStale(journal, deps.staleAfterMs ?? DEFAULT_STALE_AFTER_MS, now)
-  ) {
-    return "skipped-recent"
-  }
-
-  const needsDescriptions =
-    !isDone(journal, "descriptions") || !isDone(journal, "gcsMirror")
-  const needsEvent = owesManifestEvent(journal)
-
-  if (!needsDescriptions && !needsEvent) {
-    // Nothing left that the sweep can do; stage A failures are not its job.
-    await finalizeJournal(journalStorage, journal)
-    return "nothing-to-do"
-  }
-
-  if (journal.attempts >= MAX_SWEEP_ATTEMPTS) {
-    await abandonJournal(journalStorage, journal)
-    console.error(
-      `[sweep] Giving up on "${journal.courseSlug}" (${journal.publishId}) after ${journal.attempts} attempts`
-    )
-    return "abandoned"
-  }
-
-  await incrementAttempts(journalStorage, journal)
-
-  let succeeded = true
-  let stats: { generated: number; failed: number; missing: number } | undefined
-
-  if (needsDescriptions) {
-    const outcome = await runPublishDescriptionsStage({
-      courseSlug: journal.courseSlug,
-      rigobotToken: deps.rigobotToken,
-      journal,
-      journalStorage,
-      publishedStorage: deps.publishedStorage,
-      draftStorage: deps.draftStorage,
-      generate: deps.generate,
-    })
-    succeeded = outcome.succeeded
-    if (outcome.generation) {
-      stats = {
-        generated: outcome.generation.generated,
-        failed: outcome.generation.failed,
-        missing: outcome.generation.missing,
-      }
-    }
-  }
-
-  if (needsEvent) {
-    await emitPendingManifestEvent(journal, deps, succeeded, stats)
-  }
-
-  await finalizeJournal(journalStorage, journal)
-  return "resumed"
-}
-
-async function emitPendingManifestEvent(
-  journal: PublishJournal,
-  deps: ResumeDeps,
-  succeeded: boolean,
-  stats?: { generated: number; failed: number; missing: number }
-): Promise<void> {
-  const emit = deps.emit ?? sendPublishEvent
-  const readPackageInfo = deps.readPackageInfo ?? fetchPackageInfo
-
-  if (!deps.breathecodeToken) {
-    await markStage(deps.journalStorage, journal, "manifestEvent", "failed", {
-      error: "BREATHECODE_SYSTEM_TOKEN is not configured",
-    })
-    return
-  }
-
-  try {
-    let manifest: PackageManifest | null = null
-    if (deps.publishedStorage.readManifest) {
-      manifest = await deps.publishedStorage.readManifest(journal.courseSlug)
-    }
-
-    const delivered = await emit(
-      buildPackageManifestUpdatedEvent(
-        {
-          publishId: journal.publishId,
-          courseSlug: journal.courseSlug,
-          packageInfo: await readPackageInfo(
-            journal.courseSlug,
-            deps.rigobotToken
-          ),
-          manifest,
-        },
-        succeeded ? "success" : "failed",
-        stats
-      ),
-      deps.breathecodeToken
-    )
-
-    await markStage(
-      deps.journalStorage,
-      journal,
-      "manifestEvent",
-      delivered ? "done" : "failed",
-      { error: delivered ? undefined : "delivery failed" }
-    )
-  } catch (error) {
-    await markStage(deps.journalStorage, journal, "manifestEvent", "failed", {
-      error: (error as Error).message,
-    })
-  }
-}
+import {
+  abandonJournal,
+  finalizeJournal,
+  incrementAttempts,
+  isJournalStale,
+  JournalStorage,
+  markStage,
+  PublishJournal,
+} from "../publishJournal"
+import { PackageManifest } from "../packageManifest"
+import {
+  buildPackageManifestUpdatedEvent,
+  fetchPackageInfo,
+  sendPublishEvent,
+} from "../publishEvents"
+import {
+  CourseDescriptionsStorage,
+  GenerateCourseDescriptionsOptions,
+} from "./generateCourseDescriptions"
+import { runPublishDescriptionsStage } from "./publishStage"
+
+/**
+ * Recovery of a publication whose background stage never finished.
+ *
+ * The stage runs inside the web process, so a dyno restart mid-flight leaves a
+ * package published but not described, and — worse — breathecode waiting for a
+ * manifest event that was promised and will never arrive. Content-wise the
+ * missing descriptions would eventually be picked up by the next publication,
+ * but the promised event has no such second chance: emitting it is the reason
+ * this exists.
+ */
+
+export const MAX_SWEEP_ATTEMPTS = 3
+
+/** Only resume publications nobody is working on any more. */
+export const DEFAULT_STALE_AFTER_MS = 15 * 60 * 1000
+
+export type ResumeOutcome =
+  | "skipped-recent"
+  | "skipped-abandoned"
+  | "abandoned"
+  | "resumed"
+  | "nothing-to-do";
+
+export type ResumeDeps = {
+  journalStorage: JournalStorage;
+  publishedStorage: CourseDescriptionsStorage;
+  draftStorage: CourseDescriptionsStorage;
+  rigobotToken: string;
+  breathecodeToken?: string;
+  staleAfterMs?: number;
+  now?: number;
+  /** Injection points for tests. */
+  emit?: typeof sendPublishEvent;
+  readPackageInfo?: typeof fetchPackageInfo;
+  generate?: GenerateCourseDescriptionsOptions["generate"];
+};
+
+function isDone(
+  journal: PublishJournal,
+  stage: "descriptions" | "gcsMirror" | "manifestEvent"
+): boolean {
+  return journal.stages[stage].status === "done"
+}
+
+/**
+ * Whether breathecode is still owed a manifest event: one was promised (the
+ * publish event announced `queued`) and it never went out.
+ */
+export function owesManifestEvent(journal: PublishJournal): boolean {
+  const promised =
+    (
+      journal.stages.publishedEvent.meta as
+        | { descriptions?: string }
+        | undefined
+    )?.descriptions === "queued"
+  return promised && !isDone(journal, "manifestEvent")
+}
+
+export async function resumePublication(
+  journal: PublishJournal,
+  deps: ResumeDeps
+): Promise<ResumeOutcome> {
+  const { journalStorage } = deps
+  const now = deps.now ?? Date.now()
+
+  if (journal.abandoned) {
+    return "skipped-abandoned"
+  }
+
+  // A publication still in flight would race with its own stage.
+  if (
+    !isJournalStale(journal, deps.staleAfterMs ?? DEFAULT_STALE_AFTER_MS, now)
+  ) {
+    return "skipped-recent"
+  }
+
+  const needsDescriptions =
+    !isDone(journal, "descriptions") || !isDone(journal, "gcsMirror")
+  const needsEvent = owesManifestEvent(journal)
+
+  if (!needsDescriptions && !needsEvent) {
+    // Nothing left that the sweep can do; stage A failures are not its job.
+    await finalizeJournal(journalStorage, journal)
+    return "nothing-to-do"
+  }
+
+  if (journal.attempts >= MAX_SWEEP_ATTEMPTS) {
+    await abandonJournal(journalStorage, journal)
+    console.error(
+      `[sweep] Giving up on "${journal.courseSlug}" (${journal.publishId}) after ${journal.attempts} attempts`
+    )
+    return "abandoned"
+  }
+
+  await incrementAttempts(journalStorage, journal)
+
+  let succeeded = true
+  let stats: { generated: number; failed: number; missing: number } | undefined
+
+  if (needsDescriptions) {
+    const outcome = await runPublishDescriptionsStage({
+      courseSlug: journal.courseSlug,
+      rigobotToken: deps.rigobotToken,
+      journal,
+      journalStorage,
+      publishedStorage: deps.publishedStorage,
+      draftStorage: deps.draftStorage,
+      generate: deps.generate,
+    })
+    succeeded = outcome.succeeded
+    if (outcome.generation) {
+      stats = {
+        generated: outcome.generation.generated,
+        failed: outcome.generation.failed,
+        missing: outcome.generation.missing,
+      }
+    }
+  }
+
+  if (needsEvent) {
+    await emitPendingManifestEvent(journal, deps, succeeded, stats)
+  }
+
+  await finalizeJournal(journalStorage, journal)
+  return "resumed"
+}
+
+async function emitPendingManifestEvent(
+  journal: PublishJournal,
+  deps: ResumeDeps,
+  succeeded: boolean,
+  stats?: { generated: number; failed: number; missing: number }
+): Promise<void> {
+  const emit = deps.emit ?? sendPublishEvent
+  const readPackageInfo = deps.readPackageInfo ?? fetchPackageInfo
+
+  if (!deps.breathecodeToken) {
+    await markStage(deps.journalStorage, journal, "manifestEvent", "failed", {
+      error: "BREATHECODE_SYSTEM_TOKEN is not configured",
+    })
+    return
+  }
+
+  // Enriching the payload must never prevent the delivery: this event is the
+  // one breathecode has been waiting for since the publication stalled, and
+  // both the manifest and the package info are optional in the contract.
+  let manifest: PackageManifest | null = null
+  let packageInfo: Record<string, unknown> | null = null
+  try {
+    if (deps.publishedStorage.readManifest) {
+      manifest = await deps.publishedStorage.readManifest(journal.courseSlug)
+    }
+  } catch (error) {
+    console.error(
+      `[sweep] Could not read the manifest of "${journal.courseSlug}", reporting without it:`,
+      (error as Error).message
+    )
+  }
+
+  try {
+    packageInfo = await readPackageInfo(journal.courseSlug, deps.rigobotToken)
+  } catch (error) {
+    console.error(
+      `[sweep] Could not read the package of "${journal.courseSlug}", reporting without it:`,
+      (error as Error).message
+    )
+  }
+
+  try {
+    const delivered = await emit(
+      buildPackageManifestUpdatedEvent(
+        {
+          publishId: journal.publishId,
+          courseSlug: journal.courseSlug,
+          packageInfo,
+          manifest,
+        },
+        succeeded ? "success" : "failed",
+        stats
+      ),
+      deps.breathecodeToken
+    )
+
+    await markStage(
+      deps.journalStorage,
+      journal,
+      "manifestEvent",
+      delivered ? "done" : "failed",
+      { error: delivered ? undefined : "delivery failed" }
+    )
+  } catch (error) {
+    await markStage(deps.journalStorage, journal, "manifestEvent", "failed", {
+      error: (error as Error).message,
+    })
+  }
+}