@terreno/jobs 57.4.0

package/dist/scheduler.js

@@ -0,0 +1,178 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tickDueSchedules = exports.buildScheduleRunIdempotencyKey = void 0;
+var api_1 = require("@terreno/api");
+var luxon_1 = require("luxon");
+var dispatchError_1 = require("./dispatchError");
+var job_1 = require("./models/job");
+var jobSchedule_1 = require("./models/jobSchedule");
+var modelTypes_1 = require("./modelTypes");
+var scheduleCron_1 = require("./scheduleCron");
+/** @internal */
+var buildScheduleRunIdempotencyKey = function (scheduleId, dueRunAt) {
+    return "schedule:".concat(scheduleId, ":").concat(dueRunAt.toISOString());
+};
+exports.buildScheduleRunIdempotencyKey = buildScheduleRunIdempotencyKey;
+var tickOneSchedule = function (_a) { return __awaiter(void 0, [_a], void 0, function (_b) {
+    var dueRunAt, advancedNextRunAt, claimed, inFlight, idempotencyKey, error_1, shouldRollbackSchedule;
+    var jobsService = _b.jobsService, now = _b.now, schedule = _b.schedule;
+    return __generator(this, function (_c) {
+        switch (_c.label) {
+            case 0:
+                dueRunAt = schedule.nextRunAt;
+                advancedNextRunAt = (0, scheduleCron_1.computeNextRunAtAfter)(schedule.cron, schedule.timezone, now);
+                return [4 /*yield*/, jobSchedule_1.JobSchedule.findOneAndUpdate({
+                        _id: schedule._id,
+                        enabled: true,
+                        nextRunAt: dueRunAt,
+                    }, {
+                        $set: {
+                            nextRunAt: advancedNextRunAt,
+                        },
+                    }, { returnDocument: "before" })];
+            case 1:
+                claimed = _c.sent();
+                if (!claimed) {
+                    return [2 /*return*/];
+                }
+                return [4 /*yield*/, job_1.Job.findOneOrNone({
+                        scheduleId: claimed._id,
+                        status: { $in: modelTypes_1.IN_FLIGHT_JOB_STATUSES },
+                    })];
+            case 2:
+                inFlight = _c.sent();
+                if (inFlight) {
+                    return [2 /*return*/];
+                }
+                idempotencyKey = (0, exports.buildScheduleRunIdempotencyKey)(claimed._id.toString(), claimed.nextRunAt);
+                _c.label = 3;
+            case 3:
+                _c.trys.push([3, 5, , 9]);
+                return [4 /*yield*/, jobsService.enqueue({
+                        idempotencyKey: idempotencyKey,
+                        name: claimed.handlerName,
+                        payload: {},
+                        runAt: claimed.nextRunAt,
+                        scheduleId: claimed._id.toString(),
+                    })];
+            case 4:
+                _c.sent();
+                return [3 /*break*/, 9];
+            case 5:
+                error_1 = _c.sent();
+                shouldRollbackSchedule = !(error_1 instanceof dispatchError_1.JobDispatchError) || error_1.compensationSucceeded;
+                if (!shouldRollbackSchedule) return [3 /*break*/, 7];
+                return [4 /*yield*/, jobSchedule_1.JobSchedule.updateOne({ _id: claimed._id, nextRunAt: advancedNextRunAt }, { $set: { nextRunAt: dueRunAt } })];
+            case 6:
+                _c.sent();
+                return [3 /*break*/, 8];
+            case 7:
+                api_1.logger.error("[JobSchedule] Dispatch compensation lost race for \"".concat(claimed.name, "\" (").concat(claimed._id.toString(), "); schedule nextRunAt left advanced"));
+                _c.label = 8;
+            case 8: throw error_1;
+            case 9: return [2 /*return*/];
+        }
+    });
+}); };
+var tickDueSchedules = function (_a) { return __awaiter(void 0, [_a], void 0, function (_b) {
+    var dueSchedules, dueSchedules_1, dueSchedules_1_1, schedule, scheduleLog, error_2, e_1_1;
+    var e_1, _c;
+    var jobsService = _b.jobsService, _d = _b.now, now = _d === void 0 ? luxon_1.DateTime.utc().toJSDate() : _d;
+    return __generator(this, function (_e) {
+        switch (_e.label) {
+            case 0: return [4 /*yield*/, jobSchedule_1.JobSchedule.find({
+                    enabled: true,
+                    nextRunAt: { $lte: now },
+                }).sort({ nextRunAt: 1 })];
+            case 1:
+                dueSchedules = _e.sent();
+                _e.label = 2;
+            case 2:
+                _e.trys.push([2, 9, 10, 11]);
+                dueSchedules_1 = __values(dueSchedules), dueSchedules_1_1 = dueSchedules_1.next();
+                _e.label = 3;
+            case 3:
+                if (!!dueSchedules_1_1.done) return [3 /*break*/, 8];
+                schedule = dueSchedules_1_1.value;
+                scheduleLog = (0, api_1.createScopedLogger)({
+                    labels: { scheduleName: schedule.name },
+                    prefix: "[JobSchedule]",
+                });
+                _e.label = 4;
+            case 4:
+                _e.trys.push([4, 6, , 7]);
+                return [4 /*yield*/, tickOneSchedule({ jobsService: jobsService, now: now, schedule: schedule })];
+            case 5:
+                _e.sent();
+                return [3 /*break*/, 7];
+            case 6:
+                error_2 = _e.sent();
+                api_1.logger.error("[JobSchedule] Tick failed for \"".concat(schedule.name, "\": ").concat(error_2 instanceof Error ? error_2.message : String(error_2)));
+                scheduleLog.error("Tick failed: ".concat(error_2 instanceof Error ? error_2.message : String(error_2)));
+                return [3 /*break*/, 7];
+            case 7:
+                dueSchedules_1_1 = dueSchedules_1.next();
+                return [3 /*break*/, 3];
+            case 8: return [3 /*break*/, 11];
+            case 9:
+                e_1_1 = _e.sent();
+                e_1 = { error: e_1_1 };
+                return [3 /*break*/, 11];
+            case 10:
+                try {
+                    if (dueSchedules_1_1 && !dueSchedules_1_1.done && (_c = dueSchedules_1.return)) _c.call(dueSchedules_1);
+                }
+                finally { if (e_1) throw e_1.error; }
+                return [7 /*endfinally*/];
+            case 11: return [2 /*return*/];
+        }
+    });
+}); };
+exports.tickDueSchedules = tickDueSchedules;

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+import type { ScopedLogger } from "@terreno/api";
+import type { JobDocument } from "./modelTypes";
+export interface JobsAdminPayloadViewInput {
+    name: string;
+    payload: unknown;
+    payloadRedacted: boolean;
+}
+/** Projects job payload for admin list/detail responses. Omit/return undefined to hide payload. */
+export type JobsAdminRedactPayload = (input: JobsAdminPayloadViewInput) => unknown | undefined;
+export interface JobHandlerContext {
+    jobId: string;
+    log: ScopedLogger;
+    signal: AbortSignal;
+}
+export interface JobScheduleDefinition {
+    cron: string;
+    timezone?: string;
+}
+export interface JobDefinition {
+    handler: (payload: unknown, ctx: JobHandlerContext) => Promise<void>;
+    retry?: {
+        backoffMs?: number;
+        maxAttempts?: number;
+        maxBackoffMs?: number;
+    };
+    schedule?: JobScheduleDefinition;
+}
+export interface EnqueueJobParams {
+    idempotencyKey?: string;
+    name: string;
+    payload: unknown;
+    runAt?: Date;
+    scheduleId?: string;
+}
+export interface JobRunnerStartOptions {
+    /** Host surface passed to runners so they can resolve handlers and schedules without importing internals. */
+    jobs: JobsRunnerHost;
+    pollIntervalMs?: number;
+    signal: AbortSignal;
+}
+/** Public host surface for {@link JobRunner.start} — implemented by {@link JobsApp}. */
+export interface JobsRunnerHost {
+    getDefaultTimezone(): string;
+    getDefinition(name: string): JobDefinition | undefined;
+    getLockTtlMs(): number;
+    reconcileSchedules(): Promise<void>;
+    reconcileSchedulesIfDirty(): Promise<void>;
+    tickSchedules(now?: Date): Promise<void>;
+}
+/**
+ * Pluggable job dispatch and worker lifecycle.
+ *
+ * {@link enqueue} is invoked only after a **new** job row is persisted; idempotent
+ * dedupe returns the existing row without redispatching. {@link MongoJobRunner} is
+ * the default — its {@link enqueue} is a no-op because the poll loop claims Mongo rows.
+ */
+export interface JobRunner {
+    readonly id: string;
+    /** When true, {@link JobsApp} mounts the internal execute HTTP route (requires {@link JobsAppOptions.executeAuth}). */
+    readonly requiresExecuteRoute?: boolean;
+    enqueue(job: JobDocument): Promise<void>;
+    start?(options: JobRunnerStartOptions): Promise<void>;
+    stop?(): Promise<void>;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,82 @@
+{
+  "author": "Josh Gachnang",
+  "bugs": {
+    "url": "https://github.com/FlourishHealth/terreno/issues"
+  },
+  "dependencies": {
+    "@terreno/api": "57.4.0",
+    "cron": "^4.3.4",
+    "express": "^5.2.1",
+    "luxon": "^3.7.2"
+  },
+  "description": "Durable background jobs plugin for @terreno/api — part of Terreno, the batteries-included TypeScript framework for universal apps.",
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.6",
+    "@terreno/test": "57.4.0",
+    "@types/bun": "^1.4.0",
+    "@types/express": "^5.0.6",
+    "@types/luxon": "^3.7.1",
+    "@types/supertest": "^7.2.0",
+    "chai": "^6.2.2",
+    "supertest": "^7.2.2",
+    "typescript": "~6.0.3"
+  },
+  "exports": {
+    ".": {
+      "default": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./runners/gcpCloudTasks": {
+      "default": "./dist/runners/gcpCloudTasks.js",
+      "types": "./dist/runners/gcpCloudTasks.d.ts"
+    },
+    "./runners/vercelQueues": {
+      "default": "./dist/runners/vercelQueues.js",
+      "types": "./dist/runners/vercelQueues.d.ts"
+    }
+  },
+  "homepage": "https://github.com/FlourishHealth/terreno#readme",
+  "keywords": [
+    "background-jobs",
+    "queue",
+    "api",
+    "express",
+    "terreno"
+  ],
+  "license": "MIT",
+  "main": "dist/index.js",
+  "name": "@terreno/jobs",
+  "peerDependencies": {
+    "@google-cloud/tasks": "7.1.0",
+    "@vercel/queue": "^0.5.1",
+    "mongoose": "^8.0.0 || ^9.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@google-cloud/tasks": {
+      "optional": true
+    },
+    "@vercel/queue": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/FlourishHealth/terreno.git"
+  },
+  "scripts": {
+    "compile": "bun tsc",
+    "compile:watch": "bun tsc -w",
+    "dev": "bun tsc -w",
+    "lint": "biome check ./src",
+    "lint:fix": "biome check --write ./src",
+    "test": "bun test",
+    "test:agent": "AGENT=1 bun test --only-failures",
+    "test:ci": "bun test",
+    "test:coverage": "bun run ../scripts/check-coverage.ts"
+  },
+  "types": "dist/index.d.ts",
+  "version": "57.4.0"
+}

package/src/activeJobExecution.ts

@@ -0,0 +1,28 @@
+const activeExecutions = new Map<string, AbortController>();
+
+export const beginActiveJobExecution = (jobId: string, parentSignal: AbortSignal): AbortSignal => {
+  const controller = new AbortController();
+  activeExecutions.set(jobId, controller);
+
+  if (parentSignal.aborted) {
+    controller.abort();
+  } else {
+    parentSignal.addEventListener("abort", () => controller.abort(), {once: true});
+  }
+
+  return controller.signal;
+};
+
+export const endActiveJobExecution = (jobId: string): void => {
+  activeExecutions.delete(jobId);
+};
+
+export const abortActiveJobExecution = (jobId: string): boolean => {
+  const controller = activeExecutions.get(jobId);
+  if (!controller) {
+    return false;
+  }
+
+  controller.abort();
+  return true;
+};

package/src/claimLock.ts

@@ -0,0 +1,37 @@
+import {randomUUID} from "node:crypto";
+import os from "node:os";
+
+import type {JobDocument} from "./modelTypes";
+
+/** @internal */
+export const getWorkerId = (): string => `${os.hostname()}:${process.pid}`;
+
+export interface JobClaimLock {
+  lockedAt: Date;
+  lockedBy: string;
+}
+
+export const createClaimLock = (lockedAt: Date): JobClaimLock => ({
+  lockedAt,
+  lockedBy: `${getWorkerId()}:${randomUUID()}`,
+});
+
+export const buildClaimOwnershipFilter = (
+  jobId: JobDocument["_id"],
+  claim: JobClaimLock
+): {_id: JobDocument["_id"]; lockedAt: Date; lockedBy: string} => ({
+  _id: jobId,
+  lockedAt: claim.lockedAt,
+  lockedBy: claim.lockedBy,
+});
+
+/** @internal */
+export const hasWorkerIdPrefix = (lockedBy: string | undefined): boolean => {
+  if (!lockedBy) {
+    return false;
+  }
+  return lockedBy.startsWith(`${getWorkerId()}:`);
+};
+
+export const isAbortError = (error: unknown): boolean =>
+  error instanceof Error && error.name === "AbortError";

package/src/dispatchCompensation.ts

@@ -0,0 +1,39 @@
+import {logger} from "@terreno/api";
+
+import {JobDispatchError} from "./dispatchError";
+import {Job} from "./models/job";
+import type {JobDocument} from "./modelTypes";
+import type {JobRunner} from "./types";
+
+const removeUntouchedPendingJob = async (jobId: JobDocument["_id"]): Promise<boolean> => {
+  const removed = await Job.findOneAndDelete({
+    _id: jobId,
+    $and: [
+      {$or: [{lockedAt: {$exists: false}}, {lockedAt: null}]},
+      {$or: [{lockedBy: {$exists: false}}, {lockedBy: null}]},
+    ],
+    attemptCount: 0,
+    status: "pending",
+  });
+
+  return removed !== null;
+};
+
+export const dispatchJobToRunner = async (runner: JobRunner, job: JobDocument): Promise<void> => {
+  try {
+    await runner.enqueue(job);
+  } catch (error: unknown) {
+    const compensationSucceeded = await removeUntouchedPendingJob(job._id);
+    if (!compensationSucceeded) {
+      logger.error(
+        `[jobs] Dispatch failed for job ${job._id.toString()} and compensation lost race — row was already claimed or mutated`
+      );
+    }
+
+    throw new JobDispatchError({
+      cause: error,
+      compensationSucceeded,
+      jobId: job._id.toString(),
+    });
+  }
+};

package/src/dispatchError.ts

@@ -0,0 +1,14 @@
+export class JobDispatchError extends Error {
+  readonly cause: unknown;
+  readonly compensationSucceeded: boolean;
+  readonly jobId: string;
+
+  constructor(options: {cause: unknown; compensationSucceeded: boolean; jobId: string}) {
+    const detail = options.cause instanceof Error ? options.cause.message : String(options.cause);
+    super(`Job dispatch failed for ${options.jobId}: ${detail}`);
+    this.name = "JobDispatchError";
+    this.cause = options.cause;
+    this.compensationSucceeded = options.compensationSucceeded;
+    this.jobId = options.jobId;
+  }
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+export type {JobsAppOptions} from "./jobsApp";
+export {JobsApp} from "./jobsApp";
+export {getJobsService, tryGetJobsService, unregisterJobsService} from "./jobsService";
+export {Job} from "./models/job";
+export {JobSchedule} from "./models/jobSchedule";
+export type {
+  JobAttempt,
+  JobDocument,
+  JobModel,
+  JobScheduleDocument,
+  JobScheduleModel,
+  JobStatus,
+} from "./modelTypes";
+export type {ExecuteAuthVerifier} from "./routes/jobsExecute";
+export {MongoJobRunner} from "./runners/mongoRunner";
+export type {
+  EnqueueJobParams,
+  JobDefinition,
+  JobHandlerContext,
+  JobRunner,
+  JobRunnerStartOptions,
+  JobScheduleDefinition,
+  JobsRunnerHost,
+} from "./types";