@studious-lms/server 1.4.9 → 1.6.0

package/dist/workers/queues.js

@@ -0,0 +1,119 @@
+/**
+ * BullMQ queue producers and the `enqueueRunJob` helper.
+ *
+ * Producer side only — safe to import from HTTP routes / services running on
+ * Vercel. Importing this file does NOT start any workers; workers live in
+ * `src/workers/processors/*` and are wired up by `src/workers/index.ts`,
+ * which is the entrypoint of the separate long-running worker process.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="feefd10a-9381-5c30-a525-0ffe36e2e323")}catch(e){}}();
+import { Queue } from 'bullmq';
+import { bullConnection } from './connection.js';
+import { prisma } from '../lib/prisma.js';
+import { logger } from '../utils/logger.js';
+const DEFAULT_JOB_OPTIONS = {
+    attempts: 3,
+    backoff: { type: 'exponential', delay: 5000 },
+    removeOnComplete: { age: 60 * 60 }, // keep completed jobs in Redis for 1h, then drop
+    removeOnFail: { age: 24 * 60 * 60 }, // keep failed jobs for 24h for inspection
+};
+export const QUEUE_NAMES = {
+    PDF_TO_WORKSHEET: 'pdfToWorksheet',
+    GRADE_WORKSHEET: 'gradeWorksheet',
+    AI_LAB_CHAT: 'aiLabChat',
+    AI_NEWTON_CHAT: 'aiNewtonChat',
+    STUDENT_PROGRESS_CHAT: 'studentProgressChat',
+};
+/**
+ * One Queue instance per type. Created lazily so that importing this module
+ * does not eagerly open queues you may never use in a given runtime.
+ */
+const queueCache = new Map();
+function getQueue(type) {
+    let queue = queueCache.get(type);
+    if (!queue) {
+        queue = new Queue(QUEUE_NAMES[type], {
+            connection: bullConnection,
+            defaultJobOptions: DEFAULT_JOB_OPTIONS,
+        });
+        queueCache.set(type, queue);
+    }
+    return queue;
+}
+/**
+ * Create a `RunJob` audit row, enqueue the BullMQ job, and link the two.
+ *
+ * Returns immediately — the actual work happens on the worker process. The
+ * caller can return `runJobId` to the client and have them poll `getRunJob`
+ * (or subscribe over Pusher) to track progress.
+ *
+ * IMPORTANT: do not call this inside a Prisma `$transaction`. If the outer
+ * transaction rolls back after the BullMQ job is added, the worker will pick
+ * up an orphaned job pointing at a non-existent RunJob row. Enqueue *after*
+ * the transaction commits.
+ */
+export async function enqueueRunJob(type, input, options = {}) {
+    const runJob = await prisma.runJob.create({
+        data: {
+            type,
+            status: 'PENDING',
+            classId: options.classId ?? null,
+            userId: options.userId ?? null,
+            input: input,
+        },
+    });
+    try {
+        const queue = getQueue(type);
+        const job = await queue.add(QUEUE_NAMES[type], { runJobId: runJob.id, ...input }, options.jobOptions);
+        try {
+            await prisma.runJob.update({
+                where: { id: runJob.id },
+                data: { bullJobId: job.id ?? null },
+            });
+        }
+        catch (linkError) {
+            logger.error('RunJob enqueued but bullJobId linkage failed', {
+                runJobId: runJob.id,
+                bullJobId: job.id ?? null,
+                type,
+                error: linkError instanceof Error ? linkError.message : String(linkError),
+            });
+        }
+        return { runJobId: runJob.id, bullJobId: job.id ?? null };
+    }
+    catch (error) {
+        logger.error('Failed to enqueue RunJob; marking FAILED', {
+            runJobId: runJob.id,
+            type,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        try {
+            await prisma.runJob.update({
+                where: { id: runJob.id },
+                data: {
+                    status: 'FAILED',
+                    error: error instanceof Error ? error.message : String(error),
+                    finishedAt: new Date(),
+                },
+            });
+        }
+        catch (updateError) {
+            logger.error('Failed to mark RunJob as FAILED after enqueue error', {
+                runJobId: runJob.id,
+                error: updateError instanceof Error ? updateError.message : String(updateError),
+            });
+        }
+        throw error;
+    }
+}
+/**
+ * Close every cached queue. Call from the HTTP server's shutdown handler so
+ * the producer side disconnects from Redis cleanly.
+ */
+export async function closeAllQueues() {
+    await Promise.all(Array.from(queueCache.values()).map((q) => q.close()));
+    queueCache.clear();
+}
+//# sourceMappingURL=queues.js.map
+//# debugId=feefd10a-9381-5c30-a525-0ffe36e2e323

package/dist/workers/queues.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queues.js","sources":["workers/queues.ts"],"sourceRoot":"/","sourcesContent":["/**\n * BullMQ queue producers and the `enqueueRunJob` helper.\n *\n * Producer side only — safe to import from HTTP routes / services running on\n * Vercel. Importing this file does NOT start any workers; workers live in\n * `src/workers/processors/*` and are wired up by `src/workers/index.ts`,\n * which is the entrypoint of the separate long-running worker process.\n */\nimport { Queue, type JobsOptions } from 'bullmq';\nimport { Prisma, type RunJobType } from '@prisma/client';\nimport { bullConnection } from './connection.js';\nimport { prisma } from '../lib/prisma.js';\nimport { logger } from '../utils/logger.js';\n\nconst DEFAULT_JOB_OPTIONS: JobsOptions = {\n  attempts: 3,\n  backoff: { type: 'exponential', delay: 5_000 },\n  removeOnComplete: { age: 60 * 60 }, // keep completed jobs in Redis for 1h, then drop\n  removeOnFail: { age: 24 * 60 * 60 }, // keep failed jobs for 24h for inspection\n};\n\n/**\n * Map RunJobType → (queue name, input payload shape).\n *\n * Add a new entry here whenever you introduce a new background job type.\n * The queue name string must match what the corresponding processor passes\n * to `new Worker(<name>, ...)`.\n */\nexport type JobInputs = {\n  /**\n   * `worksheetId` is the placeholder Worksheet row created synchronously by\n   * the producer (so the client has an id to navigate to). The pipeline fills\n   * that row in asynchronously and broadcasts progress on the per-worksheet\n   * job channel.\n   */\n  PDF_TO_WORKSHEET: { gcsUrl: string; classId: string; worksheetId: string };\n  GRADE_WORKSHEET: { worksheetResponseId: string };\n  /**\n   * `aiMessageId` is the placeholder AI Message row created synchronously by\n   * the producer before enqueue (so the client renders a PENDING bubble in\n   * the timeline). The pipeline fills in the content and flips the row to\n   * COMPLETED / FAILED. Used for both intros and replies — single shape.\n   */\n  AI_LAB_CHAT: { conversationId: string; aiMessageId: string };\n  /**\n   * `aiMessageId` placeholder pattern, same as AI_LAB_CHAT — see above.\n   */\n  AI_NEWTON_CHAT: { conversationId: string; aiMessageId: string };\n  STUDENT_PROGRESS_CHAT: { classId: string; studentId: string; message: string };\n};\n\nexport const QUEUE_NAMES: Record<RunJobType, string> = {\n  PDF_TO_WORKSHEET: 'pdfToWorksheet',\n  GRADE_WORKSHEET: 'gradeWorksheet',\n  AI_LAB_CHAT: 'aiLabChat',\n  AI_NEWTON_CHAT: 'aiNewtonChat',\n  STUDENT_PROGRESS_CHAT: 'studentProgressChat',\n};\n\n/**\n * One Queue instance per type. Created lazily so that importing this module\n * does not eagerly open queues you may never use in a given runtime.\n */\nconst queueCache = new Map<RunJobType, Queue>();\n\nfunction getQueue(type: RunJobType): Queue {\n  let queue = queueCache.get(type);\n  if (!queue) {\n    queue = new Queue(QUEUE_NAMES[type], {\n      connection: bullConnection,\n      defaultJobOptions: DEFAULT_JOB_OPTIONS,\n    });\n    queueCache.set(type, queue);\n  }\n  return queue;\n}\n\nexport interface EnqueueOptions {\n  classId?: string | null;\n  userId?: string | null;\n  /** Override BullMQ job options (attempts, delay, priority, etc.). */\n  jobOptions?: JobsOptions;\n}\n\nexport interface EnqueueResult {\n  runJobId: string;\n  bullJobId: string | null;\n}\n\n/**\n * Create a `RunJob` audit row, enqueue the BullMQ job, and link the two.\n *\n * Returns immediately — the actual work happens on the worker process. The\n * caller can return `runJobId` to the client and have them poll `getRunJob`\n * (or subscribe over Pusher) to track progress.\n *\n * IMPORTANT: do not call this inside a Prisma `$transaction`. If the outer\n * transaction rolls back after the BullMQ job is added, the worker will pick\n * up an orphaned job pointing at a non-existent RunJob row. Enqueue *after*\n * the transaction commits.\n */\nexport async function enqueueRunJob<T extends RunJobType>(\n  type: T,\n  input: JobInputs[T],\n  options: EnqueueOptions = {},\n): Promise<EnqueueResult> {\n  const runJob = await prisma.runJob.create({\n    data: {\n      type,\n      status: 'PENDING',\n      classId: options.classId ?? null,\n      userId: options.userId ?? null,\n      input: input as unknown as Prisma.InputJsonValue,\n    },\n  });\n\n  try {\n    const queue = getQueue(type);\n    const job = await queue.add(\n      QUEUE_NAMES[type],\n      { runJobId: runJob.id, ...input },\n      options.jobOptions,\n    );\n\n    try {\n      await prisma.runJob.update({\n        where: { id: runJob.id },\n        data: { bullJobId: job.id ?? null },\n      });\n    } catch (linkError) {\n      logger.error('RunJob enqueued but bullJobId linkage failed', {\n        runJobId: runJob.id,\n        bullJobId: job.id ?? null,\n        type,\n        error: linkError instanceof Error ? linkError.message : String(linkError),\n      });\n    }\n\n    return { runJobId: runJob.id, bullJobId: job.id ?? null };\n  } catch (error) {\n    logger.error('Failed to enqueue RunJob; marking FAILED', {\n      runJobId: runJob.id,\n      type,\n      error: error instanceof Error ? error.message : String(error),\n    });\n\n    try {\n      await prisma.runJob.update({\n        where: { id: runJob.id },\n        data: {\n          status: 'FAILED',\n          error: error instanceof Error ? error.message : String(error),\n          finishedAt: new Date(),\n        },\n      });\n    } catch (updateError) {\n      logger.error('Failed to mark RunJob as FAILED after enqueue error', {\n        runJobId: runJob.id,\n        error: updateError instanceof Error ? updateError.message : String(updateError),\n      });\n    }\n\n    throw error;\n  }\n}\n\n/**\n * Close every cached queue. Call from the HTTP server's shutdown handler so\n * the producer side disconnects from Redis cleanly.\n */\nexport async function closeAllQueues(): Promise<void> {\n  await Promise.all(Array.from(queueCache.values()).map((q) => q.close()));\n  queueCache.clear();\n}\n"],"names":[],"mappings":"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","debug_id":"feefd10a-9381-5c30-a525-0ffe36e2e323"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@studious-lms/server",
-  "version": "1.4.9",
+  "version": "1.6.0",
   "description": "Backend server for Studious application",
   "main": "dist/exportType.js",
   "types": "dist/exportType.d.ts",
@@ -13,8 +13,10 @@
   },
   "scripts": {
     "dev": "tsx watch src/index.ts",
+    "dev:worker": "tsx watch src/workers/index.ts",
     "build": "tsc && npm run sentry:sourcemaps",
     "start": "node dist/index.js",
+    "start:worker": "node dist/workers/index.js",
     "generate": "npx prisma generate",
     "prepublishOnly": "npm run generate && npm run build",
     "test:pre": "NODE_ENV=test tsx scripts/test-pre-push.ts",
@@ -27,7 +29,7 @@
     "sentry:sourcemaps": "sentry-cli sourcemaps inject ./dist && sentry-cli sourcemaps upload --org \"${SENTRY_ORG:-studious-lms}\" --project \"${SENTRY_PROJECT:-server}\" ./dist"
   },
   "dependencies": {
-    "@google-cloud/storage": "^7.16.0",
+    "@google-cloud/storage": "^5.18.3",
     "@pdf-lib/fontkit": "^1.1.1",
     "@prisma/client": "^6.7.0",
     "@sentry/cli": "^2.58.2",
@@ -35,6 +37,7 @@
     "@trpc/server": "^11.4.3",
     "@unkey/ratelimit": "^2.1.3",
     "bcryptjs": "^3.0.2",
+    "bullmq": "^5.76.6",
     "compression": "^1.8.1",
     "cors": "^2.8.5",
     "date-fns": "^4.1.0",
@@ -43,7 +46,7 @@
     "express-rate-limit": "^8.2.1",
     "helmet": "^8.1.0",
     "ioredis": "^5.10.0",
-    "nodemailer": "^7.0.4",
+    "nodemailer": "^8.0.7",
     "openai": "^5.23.0",
     "pdf-lib": "^1.17.1",
     "prisma": "^6.7.0",

package/prisma/migrations/20260506162500_consolidate_run_job_and_unify_job_status/migration.sql

@@ -0,0 +1,166 @@
+-- Consolidate background-job tracking onto RunJob and unify domain status.
+--
+-- 1. Replace the bare-bones RunJob table with a fully-typed audit row that
+--    carries job type, status, input/result, error, attempts, timestamps.
+-- 2. Replace the catch-all GenerationStatus enum with a single shared
+--    JobStatus enum used by every domain row that has a user-observable
+--    async lifecycle (Message, StudentQuestionProgress).
+-- 3. Add a nullable runJobId FK on Message and StudentQuestionProgress so we
+--    can trace a domain row back to the job that produced it. Operational
+--    state (retries, errors, attempts) lives on RunJob, not on the row.
+-- 4. Drop the unused Comment.status column.
+
+-- ---------------------------------------------------------------------------
+-- 1. New enum types
+-- ---------------------------------------------------------------------------
+
+CREATE TYPE "RunJobType" AS ENUM (
+  'PDF_TO_WORKSHEET',
+  'GRADE_WORKSHEET',
+  'AI_LAB_CHAT',
+  'AI_NEWTON_CHAT',
+  'STUDENT_PROGRESS_CHAT'
+);
+
+-- Queue-internal lifecycle. Distinct from JobStatus because PENDING (queued
+-- but not picked up) vs RUNNING (worker actively executing) is a real
+-- operational distinction we want when debugging.
+CREATE TYPE "RunJobStatus" AS ENUM (
+  'PENDING',
+  'RUNNING',
+  'SUCCEEDED',
+  'FAILED',
+  'CANCELLED'
+);
+
+-- Shared UI-shaped status for domain rows. Not every row uses every value
+-- (e.g. Message never gets NOT_STARTED) but we keep one enum to avoid an
+-- explosion of near-duplicate types.
+CREATE TYPE "JobStatus" AS ENUM (
+  'NOT_STARTED',
+  'PENDING',
+  'COMPLETED',
+  'FAILED',
+  'CANCELLED'
+);
+
+-- ---------------------------------------------------------------------------
+-- 2. Replace the legacy RunJob table.
+--
+-- The previous schema only had `id` and `createdAt`, and was applied via
+-- `prisma db push` (no migration history) — so any rows in it are throwaway.
+-- We DROP IF EXISTS to handle both fresh production DBs and dev DBs that have
+-- the old shape.
+-- ---------------------------------------------------------------------------
+
+DROP TABLE IF EXISTS "RunJob" CASCADE;
+
+CREATE TABLE "RunJob" (
+  "id"         TEXT NOT NULL,
+  "type"       "RunJobType" NOT NULL,
+  "status"     "RunJobStatus" NOT NULL DEFAULT 'PENDING',
+  "classId"    TEXT,
+  "userId"     TEXT,
+  "bullJobId"  TEXT,
+  "input"      JSONB NOT NULL,
+  "result"     JSONB,
+  "error"      TEXT,
+  "attempts"   INTEGER NOT NULL DEFAULT 0,
+  "startedAt"  TIMESTAMP(3),
+  "finishedAt" TIMESTAMP(3),
+  "createdAt"  TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  "updatedAt"  TIMESTAMP(3) NOT NULL,
+
+  CONSTRAINT "RunJob_pkey" PRIMARY KEY ("id")
+);
+
+CREATE INDEX "RunJob_userId_type_status_idx" ON "RunJob"("userId", "type", "status");
+CREATE INDEX "RunJob_classId_status_idx"     ON "RunJob"("classId", "status");
+CREATE INDEX "RunJob_status_createdAt_idx"   ON "RunJob"("status", "createdAt");
+
+-- ---------------------------------------------------------------------------
+-- 2b. Track PDF source URLs on worksheets for idempotent PDF conversion.
+-- ---------------------------------------------------------------------------
+
+ALTER TABLE "Worksheet" ADD COLUMN "sourceUrl" TEXT;
+
+CREATE UNIQUE INDEX "Worksheet_classId_sourceUrl_key"
+  ON "Worksheet"("classId", "sourceUrl");
+
+-- ---------------------------------------------------------------------------
+-- 3. Message.status: GenerationStatus -> JobStatus.
+--
+-- Old enum had NOT_STARTED / PENDING / GENERATING / COMPLETED / FAILED /
+-- CANCELLED. New JobStatus drops GENERATING (never written). The old default
+-- of NOT_STARTED is dropped: a row without an AI lifecycle now has NULL.
+-- GENERATING is mapped to PENDING defensively in case any row carries it.
+-- ---------------------------------------------------------------------------
+
+ALTER TABLE "Message" ALTER COLUMN "status" DROP DEFAULT;
+
+ALTER TABLE "Message"
+  ALTER COLUMN "status" TYPE "JobStatus"
+  USING (
+    CASE "status"::text
+      WHEN 'NOT_STARTED' THEN NULL
+      WHEN 'GENERATING'  THEN 'PENDING'::"JobStatus"
+      WHEN 'PENDING'     THEN 'PENDING'::"JobStatus"
+      WHEN 'COMPLETED'   THEN 'COMPLETED'::"JobStatus"
+      WHEN 'FAILED'      THEN 'FAILED'::"JobStatus"
+      WHEN 'CANCELLED'   THEN 'CANCELLED'::"JobStatus"
+      ELSE NULL
+    END
+  );
+
+-- ---------------------------------------------------------------------------
+-- 4. StudentQuestionProgress.status: GenerationStatus -> JobStatus.
+--
+-- Default kept at NOT_STARTED. GENERATING -> PENDING defensively.
+-- ---------------------------------------------------------------------------
+
+ALTER TABLE "StudentQuestionProgress" ALTER COLUMN "status" DROP DEFAULT;
+
+ALTER TABLE "StudentQuestionProgress"
+  ALTER COLUMN "status" TYPE "JobStatus"
+  USING (
+    CASE "status"::text
+      WHEN 'NOT_STARTED' THEN 'NOT_STARTED'::"JobStatus"
+      WHEN 'PENDING'     THEN 'PENDING'::"JobStatus"
+      WHEN 'GENERATING'  THEN 'PENDING'::"JobStatus"
+      WHEN 'COMPLETED'   THEN 'COMPLETED'::"JobStatus"
+      WHEN 'FAILED'      THEN 'FAILED'::"JobStatus"
+      WHEN 'CANCELLED'   THEN 'CANCELLED'::"JobStatus"
+      ELSE NULL
+    END
+  );
+
+ALTER TABLE "StudentQuestionProgress"
+  ALTER COLUMN "status" SET DEFAULT 'NOT_STARTED';
+
+-- ---------------------------------------------------------------------------
+-- 5. Drop the unused Comment.status column and the legacy enum.
+-- ---------------------------------------------------------------------------
+
+ALTER TABLE "Comment" DROP COLUMN "status";
+
+DROP TYPE "GenerationStatus";
+
+-- ---------------------------------------------------------------------------
+-- 6. Add runJobId FKs and supporting indexes.
+-- ---------------------------------------------------------------------------
+
+ALTER TABLE "Message"
+  ADD COLUMN "runJobId" TEXT,
+  ADD CONSTRAINT "Message_runJobId_fkey"
+    FOREIGN KEY ("runJobId") REFERENCES "RunJob"("id")
+    ON DELETE SET NULL ON UPDATE CASCADE;
+
+CREATE INDEX "Message_runJobId_idx" ON "Message"("runJobId");
+
+ALTER TABLE "StudentQuestionProgress"
+  ADD COLUMN "runJobId" TEXT,
+  ADD CONSTRAINT "StudentQuestionProgress_runJobId_fkey"
+    FOREIGN KEY ("runJobId") REFERENCES "RunJob"("id")
+    ON DELETE SET NULL ON UPDATE CASCADE;
+
+CREATE INDEX "StudentQuestionProgress_runJobId_idx" ON "StudentQuestionProgress"("runJobId");