@learnpack/learnpack 5.0.353 → 5.0.355

package/src/utils/descriptions/backfillEvents.ts

@@ -0,0 +1,152 @@
+import { v4 as uuidv4 } from "uuid"
+import { PackageManifest } from "../packageManifest"
+import {
+  buildPackageManifestUpdatedEvent,
+  fetchPackageInfo,
+  sendPublishEvent,
+} from "../publishEvents"
+import {
+  CourseDescriptionsStorage,
+  GenerateCourseDescriptionsResult,
+} from "./generateCourseDescriptions"
+
+/**
+ * `package_manifest_updated` for courses reconciled by the backfill.
+ *
+ * The backfill regenerates descriptions of packages that are already published,
+ * so breathecode needs the same notification a publication sends — but there is
+ * no publication here: no `package_published` precedes this event, and no
+ * journal tracks it (the sweep resumes publications, and a backfill is simply
+ * re-run instead).
+ *
+ * That is what makes `publish_id` awkward. The field exists to correlate the two
+ * events of one publication, a pair this event has no half of. Since it is
+ * required, the value has to be something that cannot be mistaken for a real
+ * publication: a bare uuid — the obvious choice — would be exactly that mistake,
+ * and if breathecode ever starts pairing events it would search forever for a
+ * `package_published` that was never sent.
+ *
+ * Hence `backfill-{runId}-{slug}`:
+ *
+ * - the `backfill-` prefix makes the origin readable in the webhook log and
+ *   discriminable in code (`isBackfillPublishId`); real ids are bare uuids from
+ *   `createJournal`, so the two spaces cannot collide;
+ * - `{slug}` keeps it unique per event, which a per-run id alone would not be;
+ * - a `{runId}` shared by every course of one invocation makes "every event from
+ *   the run I fired at 15:40" a single substring query, which is the question
+ *   you actually ask when the catalogue is backfilled in small batches.
+ *
+ * Encoding this in `publish_id`, rather than adding an `origin` field, keeps the
+ * event contract untouched: breathecode ignores `publish_id` today, so this
+ * costs them nothing and needs no coordination. If they ever start consuming the
+ * provenance, it can be promoted to a field of its own.
+ */
+
+export const BACKFILL_PUBLISH_ID_PREFIX = "backfill-"
+
+/** One per script invocation, shared by every course it touches. */
+export function newBackfillRunId(): string {
+  return uuidv4()
+}
+
+export function backfillPublishId(runId: string, courseSlug: string): string {
+  return `${BACKFILL_PUBLISH_ID_PREFIX}${runId}-${courseSlug}`
+}
+
+export function isBackfillPublishId(publishId: string): boolean {
+  return publishId.startsWith(BACKFILL_PUBLISH_ID_PREFIX)
+}
+
+/**
+ * `skipped` means the event was never attempted, which is not a failure: a
+ * course the backfill did not change has nothing to announce.
+ */
+export type BackfillEventOutcome = "skipped" | "delivered" | "failed";
+
+export type EmitBackfillManifestEventParams = {
+  courseSlug: string;
+  runId: string;
+  result: GenerateCourseDescriptionsResult;
+  storage: CourseDescriptionsStorage;
+  rigobotToken: string;
+  breathecodeToken: string;
+  /** Injection points for tests. */
+  emit?: typeof sendPublishEvent;
+  readPackageInfo?: typeof fetchPackageInfo;
+};
+
+/**
+ * Announce one reconciled course. Never throws: the descriptions and the
+ * manifest are already written by the time this runs, and losing the
+ * notification must not turn a successful course into a failed one.
+ */
+export async function emitBackfillManifestEvent(
+  params: EmitBackfillManifestEventParams
+): Promise<BackfillEventOutcome> {
+  const { courseSlug, result } = params
+
+  if (result.status === "skipped") {
+    return "skipped"
+  }
+
+  const emit = params.emit ?? sendPublishEvent
+  const readPackageInfo = params.readPackageInfo ?? fetchPackageInfo
+
+  // Enriching the payload must never prevent the delivery: both the manifest and
+  // the package info are optional in the contract, and an event with less
+  // context beats an event that never arrives.
+  let manifest: PackageManifest | null = null
+  try {
+    if (params.storage.readManifest) {
+      manifest = await params.storage.readManifest(courseSlug)
+    }
+  } catch (error) {
+    console.error(
+      `[backfill-events] Could not read the manifest of "${courseSlug}", reporting without it:`,
+      (error as Error).message
+    )
+  }
+
+  let packageInfo: Record<string, unknown> | null = null
+  try {
+    packageInfo = await readPackageInfo(courseSlug, params.rigobotToken)
+  } catch (error) {
+    console.error(
+      `[backfill-events] Could not read the package "${courseSlug}", reporting without it:`,
+      (error as Error).message
+    )
+  }
+
+  try {
+    const delivered = await emit(
+      buildPackageManifestUpdatedEvent(
+        {
+          publishId: backfillPublishId(params.runId, courseSlug),
+          courseSlug,
+          packageInfo,
+          manifest,
+        },
+        // A failed projection does not fail the run — the syllabus is saved
+        // either way — but this event reports the manifest, so it cannot claim
+        // success over one that was never rewritten.
+        result.status === "failed" || result.manifestProjected === false ?
+          "failed" :
+          "success",
+        {
+          generated: result.generated,
+          failed: result.failed,
+          missing: result.missing,
+        }
+      ),
+      params.breathecodeToken
+    )
+
+    return delivered ? "delivered" : "failed"
+  } catch (error) {
+    console.error(
+      `[backfill-events] Could not deliver the manifest event for "${courseSlug}":`,
+      (error as Error).message
+    )
+    return "failed"
+  }
+}

package/src/utils/descriptions/generateCourseDescriptions.ts

@@ -79,6 +79,13 @@ export type GenerateCourseDescriptionsResult = {
   errors: string[];
   /** Completion durations, to watch how close we run to the request limits. */
   durationsSeconds: number[];
+  /**
+   * Whether `package-manifest.json` was re-projected; null when the storage does
+   * not project at all. A failed projection is not a failed run — the syllabus,
+   * which is the source of truth, is already saved — but callers that announce
+   * the manifest downstream must not report success on it.
+   */
+  manifestProjected: boolean | null;
 };
 
 function emptyResult(
@@ -92,6 +99,7 @@ function emptyResult(
     missing: 0,
     errors: [],
     durationsSeconds: [],
+    manifestProjected: null,
   }
 }
 
@@ -288,9 +296,11 @@ export async function generateCourseDescriptions(
   if (storage.reprojectManifest) {
     try {
       await storage.reprojectManifest(courseSlug)
+      result.manifestProjected = true
     } catch (error) {
       // The syllabus (the source of truth) is already saved; a failed
       // projection is recoverable and must not lose the generated text.
+      result.manifestProjected = false
       result.errors.push(
         `manifest projection failed: ${(error as Error).message}`
       )