@yellowpanther/shared 1.1.7 → 1.2.0

package/src/queue/quizPublishQueue.js

@@ -0,0 +1,164 @@
+// src/queue/quizPublishQueue.js
+// One-off *publish* scheduler for quiz items (BullMQ).
+// Strong upsert: purge any prior job for the same quiz before adding a new delayed job.
+
+const { Queue } = require('bullmq');
+const redisClient = require('../redis/redisClient');
+// const logger = require('../logger'); // uncomment if you have a shared logger
+
+const DEBUG    = String(process.env.DEBUG_LOGGER || '').trim() === '1';
+const DRIFT_MS = Math.max(0, Number(process.env.SCHEDULE_DRIFT_MS || 250));
+
+const quizPublishQueue = new Queue('quizPublishQueue', {
+  connection: redisClient,
+  defaultJobOptions: {
+    attempts: 5,
+    backoff: { type: 'exponential', delay: 2000 },
+    removeOnComplete: 500,
+    removeOnFail: 500,
+  },
+});
+
+// ── ID helpers ─────────────────────────────────────────────────────────────────
+
+function stableJobId(quiz_id) {
+  return `quiz:publish:${quiz_id}`;
+}
+function versionedJobId(quiz_id, runAtIso) {
+  return `quiz:publish:${quiz_id}:${runAtIso}`;
+}
+
+// ── Time helpers ───────────────────────────────────────────────────────────────
+
+/** Parse anything into a UTC Date. Strings without timezone are treated as UTC. */
+function normalizeToUtcDate(input) {
+  if (input instanceof Date) return new Date(input.getTime());
+  if (typeof input === 'number') return new Date(input); // epoch ms
+
+  if (typeof input === 'string') {
+    // Has timezone (Z or ±hh:mm)
+    if (/[zZ]|[+\-]\d{2}:\d{2}$/.test(input)) {
+      const d = new Date(input);
+      if (Number.isNaN(d.getTime())) throw new Error(`Invalid ISO datetime: ${input}`);
+      return d;
+    }
+    // No timezone => treat as UTC
+    const s = input.trim().replace(' ', 'T');
+    const d = new Date(`${s}Z`);
+    if (Number.isNaN(d.getTime())) throw new Error(`Invalid datetime (no tz): ${input}`);
+    return d;
+  }
+
+  throw new Error(`Unsupported runAtUtc type: ${typeof input}`);
+}
+
+// ── Purge helpers ─────────────────────────────────────────────────────────────
+
+async function findPendingQuizJobs(quiz_id) {
+  const states = ['delayed', 'waiting', 'waiting-children', 'active'];
+  const jobs = await quizPublishQueue.getJobs(states);
+  return jobs.filter(
+    (j) => j?.name === 'quiz:publish' && j?.data?.quiz_id === String(quiz_id)
+  );
+}
+
+async function purgeExistingForQuiz(quiz_id) {
+  let removed = 0;
+
+  // Remove any pending/waiting/active jobs for this quiz
+  const pendings = await findPendingQuizJobs(quiz_id);
+  for (const j of pendings) {
+    try {
+      await j.remove();
+      removed++;
+    } catch (e) {
+      if (DEBUG) console.warn(`[quizPublishQueue] failed to remove pending job ${j.id}: ${e.message}`);
+    }
+  }
+
+  // Also remove a leftover stable job if present
+  const last = await quizPublishQueue.getJob(stableJobId(quiz_id));
+  if (last) {
+    try {
+      await last.remove();
+      removed++;
+    } catch (e) {
+      if (DEBUG) console.warn(`[quizPublishQueue] failed to remove stable job ${last.id}: ${e.message}`);
+    }
+  }
+
+  if (DEBUG) {
+    console.info('[quizPublishQueue] purgeExistingForQuiz', {
+      quiz_id: String(quiz_id),
+      removed,
+    });
+  }
+  return removed;
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Upsert a one-off publish job for a quiz.
+ * - Purges any previous jobs for this quiz
+ * - Uses a versioned jobId by default (or stable if useStableId=true)
+ *
+ * @param {Object} params
+ * @param {string|number} params.quiz_id
+ * @param {string|number|Date} params.runAtUtc - ISO string, epoch ms, or Date (UTC)
+ * @param {object} [params.extra]
+ * @param {boolean} [params.useStableId=false] - if true, uses stable jobId
+ */
+async function addQuizPublishJob({ quiz_id, runAtUtc, extra = {}, useStableId = false }) {
+  if (!quiz_id || !runAtUtc) {
+    throw new Error('addQuizPublishJob: quiz_id and runAtUtc are required');
+  }
+
+  const runAt = normalizeToUtcDate(runAtUtc);
+  const runAtIso = runAt.toISOString();
+
+  // Drift guard to avoid immediate fire due to ms skew
+  const now = Date.now();
+  let delayMs = runAt.getTime() - now;
+  if (delayMs < DRIFT_MS) delayMs = Math.max(0, DRIFT_MS);
+
+  // Purge any prior jobs for this quiz (across states)
+  await purgeExistingForQuiz(quiz_id);
+
+  // Choose jobId strategy
+  const jobId = useStableId ? stableJobId(quiz_id) : versionedJobId(quiz_id, runAtIso);
+
+  const job = await quizPublishQueue.add(
+    'quiz:publish',
+    { quiz_id: String(quiz_id), runAtUtc: runAtIso, extra },
+    { jobId, delay: delayMs }
+  );
+
+  if (DEBUG) {
+    console.info('[quizPublishQueue] upsert', {
+      quiz_id: String(quiz_id),
+      jobId,
+      runAtIso,
+      delayMs,
+      nowIso: new Date(now).toISOString(),
+    });
+  }
+
+  return job;
+}
+
+/** Cancel any scheduled publish for a given quiz (if present). */
+async function cancelQuizPublishJob(quiz_id) {
+  const removed = await purgeExistingForQuiz(quiz_id);
+  return removed > 0;
+}
+
+module.exports = {
+  quizPublishQueue,
+  addQuizPublishJob,
+  cancelQuizPublishJob,
+  // helpers for tooling/tests
+  stableJobId,
+  versionedJobId,
+  normalizeToUtcDate,
+};

package/src/queue/videoPublishQueue.js

@@ -0,0 +1,164 @@
+// src/queue/videoPublishQueue.js
+// One-off *publish* scheduler for video items (BullMQ).
+// Strong upsert: purge any prior job for the same video before adding a new delayed job.
+
+const { Queue } = require('bullmq');
+const redisClient = require('../redis/redisClient');
+// const logger = require('../logger'); // uncomment if you have a shared logger
+
+const DEBUG   = String(process.env.DEBUG_LOGGER || '').trim() === '1';
+const DRIFT_MS = Math.max(0, Number(process.env.SCHEDULE_DRIFT_MS || 250));
+
+const videoPublishQueue = new Queue('videoPublishQueue', {
+  connection: redisClient,
+  defaultJobOptions: {
+    attempts: 5,
+    backoff: { type: 'exponential', delay: 2000 },
+    removeOnComplete: 500,
+    removeOnFail: 500,
+  },
+});
+
+// ── ID helpers ─────────────────────────────────────────────────────────────────
+
+function stableJobId(video_id) {
+  return `video:publish:${video_id}`;
+}
+function versionedJobId(video_id, runAtIso) {
+  return `video:publish:${video_id}:${runAtIso}`;
+}
+
+// ── Time helpers ───────────────────────────────────────────────────────────────
+
+/** Parse anything into a UTC Date. Strings without timezone are treated as UTC. */
+function normalizeToUtcDate(input) {
+  if (input instanceof Date) return new Date(input.getTime());
+  if (typeof input === 'number') return new Date(input); // epoch ms
+
+  if (typeof input === 'string') {
+    // Has timezone (Z or ±hh:mm)
+    if (/[zZ]|[+\-]\d{2}:\d{2}$/.test(input)) {
+      const d = new Date(input);
+      if (Number.isNaN(d.getTime())) throw new Error(`Invalid ISO datetime: ${input}`);
+      return d;
+    }
+    // No timezone => treat as UTC
+    const s = input.trim().replace(' ', 'T');
+    const d = new Date(`${s}Z`);
+    if (Number.isNaN(d.getTime())) throw new Error(`Invalid datetime (no tz): ${input}`);
+    return d;
+  }
+
+  throw new Error(`Unsupported runAtUtc type: ${typeof input}`);
+}
+
+// ── Purge helpers ─────────────────────────────────────────────────────────────
+
+async function findPendingVideoJobs(video_id) {
+  const states = ['delayed', 'waiting', 'waiting-children', 'active'];
+  const jobs = await videoPublishQueue.getJobs(states);
+  return jobs.filter(
+    (j) => j?.name === 'video:publish' && j?.data?.video_id === String(video_id)
+  );
+}
+
+async function purgeExistingForVideo(video_id) {
+  let removed = 0;
+
+  // Remove any pending/waiting/active jobs for this video
+  const pendings = await findPendingVideoJobs(video_id);
+  for (const j of pendings) {
+    try {
+      await j.remove();
+      removed++;
+    } catch (e) {
+      if (DEBUG) console.warn(`[videoPublishQueue] failed to remove pending job ${j.id}: ${e.message}`);
+    }
+  }
+
+  // Also remove a leftover stable job if present
+  const last = await videoPublishQueue.getJob(stableJobId(video_id));
+  if (last) {
+    try {
+      await last.remove();
+      removed++;
+    } catch (e) {
+      if (DEBUG) console.warn(`[videoPublishQueue] failed to remove stable job ${last.id}: ${e.message}`);
+    }
+  }
+
+  if (DEBUG) {
+    console.info('[videoPublishQueue] purgeExistingForVideo', {
+      video_id: String(video_id),
+      removed,
+    });
+  }
+  return removed;
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Upsert a one-off publish job for a video.
+ * - Purges any previous jobs for this video
+ * - Uses a versioned jobId by default (or stable if useStableId=true)
+ *
+ * @param {Object} params
+ * @param {string|number} params.video_id
+ * @param {string|number|Date} params.runAtUtc - ISO string, epoch ms, or Date (UTC)
+ * @param {object} [params.extra]
+ * @param {boolean} [params.useStableId=false] - if true, uses stable jobId
+ */
+async function addVideoPublishJob({ video_id, runAtUtc, extra = {}, useStableId = false }) {
+  if (!video_id || !runAtUtc) {
+    throw new Error('addVideoPublishJob: video_id and runAtUtc are required');
+  }
+
+  const runAt = normalizeToUtcDate(runAtUtc);
+  const runAtIso = runAt.toISOString();
+
+  // drift guard to avoid immediate fire due to ms skew
+  const now = Date.now();
+  let delayMs = runAt.getTime() - now;
+  if (delayMs < DRIFT_MS) delayMs = Math.max(0, DRIFT_MS);
+
+  // Purge any prior jobs for this video (across states)
+  await purgeExistingForVideo(video_id);
+
+  // Choose jobId strategy
+  const jobId = useStableId ? stableJobId(video_id) : versionedJobId(video_id, runAtIso);
+
+  const job = await videoPublishQueue.add(
+    'video:publish',
+    { video_id: String(video_id), runAtUtc: runAtIso, extra },
+    { jobId, delay: delayMs }
+  );
+
+  if (DEBUG) {
+    console.info('[videoPublishQueue] upsert', {
+      video_id: String(video_id),
+      jobId,
+      runAtIso,
+      delayMs,
+      nowIso: new Date(now).toISOString(),
+    });
+  }
+
+  return job;
+}
+
+/** Cancel any scheduled publish for a given video (if present). */
+async function cancelVideoPublishJob(video_id) {
+  const removed = await purgeExistingForVideo(video_id);
+  return removed > 0;
+}
+
+module.exports = {
+  videoPublishQueue,
+  addVideoPublishJob,
+  cancelVideoPublishJob,
+  // helpers for tooling/tests
+  stableJobId,
+  versionedJobId,
+  normalizeToUtcDate,
+};