agenda 4.3.0 → 5.0.0

package/lib/utils/process-jobs.ts

@@ -0,0 +1,379 @@
+import createDebugger from "debug";
+import { createJob } from "./create-job";
+import { Job } from "../job";
+import { Agenda } from "../agenda";
+
+const debug = createDebugger("agenda:internal:processJobs");
+
+/**
+ * Process methods for jobs
+ * @param {Job} extraJob job to run immediately
+ */
+export const processJobs = async function (
+  this: Agenda,
+  extraJob: Job
+): Promise<void> {
+  debug(
+    "starting to process jobs: [%s:%s]",
+    extraJob?.attrs?.name ?? "unknownName",
+    extraJob?.attrs?._id ?? "unknownId"
+  );
+  // Make sure an interval has actually been set
+  // Prevents race condition with 'Agenda.stop' and already scheduled run
+  if (!this._processInterval) {
+    debug("no _processInterval set when calling processJobs, returning");
+    return;
+  }
+
+  const self = this; // eslint-disable-line @typescript-eslint/no-this-alias
+  const definitions = this._definitions;
+  const jobQueue = this._jobQueue;
+  let jobName;
+
+  // Determine whether or not we have a direct process call!
+  if (!extraJob) {
+    // Go through each jobName set in 'Agenda.process' and fill the queue with the next jobs
+    const parallelJobQueueing = [];
+    for (jobName in definitions) {
+      if ({}.hasOwnProperty.call(definitions, jobName)) {
+        debug("queuing up job to process: [%s]", jobName);
+        parallelJobQueueing.push(jobQueueFilling(jobName));
+      }
+    }
+
+    await Promise.all(parallelJobQueueing);
+  } else if (definitions[extraJob.attrs.name]) {
+    // Add the job to list of jobs to lock and then lock it immediately!
+    debug(
+      "job [%s:%s] was passed directly to processJobs(), locking and running immediately",
+      extraJob.attrs.name,
+      extraJob.attrs._id
+    );
+    self._jobsToLock.push(extraJob);
+    await lockOnTheFly();
+  }
+
+  /**
+   * Returns true if a job of the specified name can be locked.
+   * Considers maximum locked jobs at any time if self._lockLimit is > 0
+   * Considers maximum locked jobs of the specified name at any time if jobDefinition.lockLimit is > 0
+   * @param name name of job to check if we should lock or not
+   * @returns whether or not you should lock job
+   */
+  function shouldLock(name: string): boolean {
+    const jobDefinition = definitions[name];
+    let shouldLock = true;
+    if (self._lockLimit && self._lockLimit <= self._lockedJobs.length) {
+      shouldLock = false;
+    }
+
+    if (
+      jobDefinition.lockLimit &&
+      jobDefinition.lockLimit <= jobDefinition.locked
+    ) {
+      shouldLock = false;
+    }
+
+    debug("job [%s] lock status: shouldLock = %s", name, shouldLock);
+    return shouldLock;
+  }
+
+  /**
+   * Internal method that adds jobs to be processed to the local queue
+   * @param jobs Jobs to queue
+   */
+  function enqueueJobs(jobs: Job[] | Job) {
+    if (!Array.isArray(jobs)) {
+      jobs = [jobs];
+    }
+
+    jobs.forEach((job: Job) => {
+      jobQueue.insert(job);
+    });
+  }
+
+  /**
+   * Internal method that will lock a job and store it on MongoDB
+   * This method is called when we immediately start to process a job without using the process interval
+   * We do this because sometimes jobs are scheduled but will be run before the next process time
+   */
+  async function lockOnTheFly() {
+    debug("lockOnTheFly: isLockingOnTheFly: %s", self._isLockingOnTheFly);
+    // Already running this? Return
+    if (self._isLockingOnTheFly) {
+      debug("lockOnTheFly() already running, returning");
+      return;
+    }
+
+    // Set that we are running this
+    self._isLockingOnTheFly = true;
+
+    // Don't have any jobs to run? Return
+    if (self._jobsToLock.length === 0) {
+      debug("no jobs to current lock on the fly, returning");
+      self._isLockingOnTheFly = false;
+      return;
+    }
+
+    // Grab a job that needs to be locked
+    const now = new Date();
+    const job = self._jobsToLock.pop();
+    if (job === undefined) {
+      debug(
+        "no job was popped from _jobsToLock, extremly unlikely but not impossible concurrency issue"
+      );
+      self._isLockingOnTheFly = false;
+      return;
+    }
+
+    if (self._isJobQueueFilling.has(job.attrs.name)) {
+      debug(
+        "lockOnTheFly: jobQueueFilling already running for: %s",
+        job.attrs.name
+      );
+      self._isLockingOnTheFly = false;
+      return;
+    }
+
+    // If locking limits have been hit, stop locking on the fly.
+    // Jobs that were waiting to be locked will be picked up during a
+    // future locking interval.
+    if (!shouldLock(job.attrs.name)) {
+      debug("lock limit hit for: [%s:%s]", job.attrs.name, job.attrs._id);
+      self._jobsToLock = [];
+      self._isLockingOnTheFly = false;
+      return;
+    }
+
+    // Query to run against collection to see if we need to lock it
+    const criteria = {
+      _id: job.attrs._id,
+      lockedAt: null,
+      nextRunAt: job.attrs.nextRunAt,
+      disabled: { $ne: true },
+    };
+
+    // Update / options for the MongoDB query
+    const update = { $set: { lockedAt: now } };
+
+    // Lock the job in MongoDB!
+    const resp = await self._collection.findOneAndUpdate(criteria, update, {
+      returnDocument: "after",
+    });
+
+    if (resp.value) {
+      // @ts-ignore
+      const job = createJob(self, resp.value);
+      debug(
+        "found job [%s:%s] that can be locked on the fly",
+        job.attrs.name,
+        job.attrs._id
+      );
+      self._lockedJobs.push(job);
+      definitions[job.attrs.name].locked++;
+      enqueueJobs(job);
+      jobProcessing();
+    }
+
+    // Mark lock on fly is done for now
+    self._isLockingOnTheFly = false;
+
+    // Re-run in case anything is in the queue
+    await lockOnTheFly();
+  }
+
+  /**
+   * Internal method used to fill a queue with jobs that can be run
+   * @param {String} name fill a queue with specific job name
+   * @returns {undefined}
+   */
+  async function jobQueueFilling(name: string): Promise<void> {
+    debug(
+      "jobQueueFilling: %s isJobQueueFilling: %s",
+      name,
+      self._isJobQueueFilling.has(name)
+    );
+    self._isJobQueueFilling.set(name, true);
+
+    try {
+      // Don't lock because of a limit we have set (lockLimit, etc)
+      if (!shouldLock(name)) {
+        debug("lock limit reached in queue filling for [%s]", name);
+        return; // Goes to finally block
+      }
+
+      // Set the date of the next time we are going to run _processEvery function
+      const now = new Date();
+      self._nextScanAt = new Date(now.valueOf() + self._processEvery);
+
+      // For this job name, find the next job to run and lock it!
+      const job = await self._findAndLockNextJob(name, definitions[name]);
+      // Still have the job?
+      // 1. Add it to lock list
+      // 2. Add count of locked jobs
+      // 3. Queue the job to actually be run now that it is locked
+      // 4. Recursively run this same method we are in to check for more available jobs of same type!
+      if (job) {
+        // Before en-queing job make sure we haven't exceed our lock limits
+        if (!shouldLock(name)) {
+          debug(
+            "lock limit reached before job was returned. Releasing lock on [%s]",
+            name
+          );
+          job.attrs.lockedAt = null;
+          await self.saveJob(job);
+          return;
+        }
+
+        debug("[%s:%s] job locked while filling queue", name, job.attrs._id);
+        self._lockedJobs.push(job);
+        definitions[job.attrs.name].locked++;
+        enqueueJobs(job);
+        await jobQueueFilling(name);
+        jobProcessing();
+      }
+    } catch (error) {
+      debug("[%s] job lock failed while filling queue", name, error);
+    } finally {
+      self._isJobQueueFilling.delete(name);
+    }
+  }
+
+  /**
+   * Internal method that processes any jobs in the local queue (array)
+   * @returns {undefined}
+   */
+  function jobProcessing() {
+    // Ensure we have jobs
+    if (jobQueue.length === 0) {
+      return;
+    }
+
+    // Store for all sorts of things
+    const now = new Date();
+
+    // Get the next job that is not blocked by concurrency
+    const job = jobQueue.returnNextConcurrencyFreeJob(definitions);
+
+    debug("[%s:%s] about to process job", job.attrs.name, job.attrs._id);
+
+    // If the 'nextRunAt' time is older than the current time, run the job
+    // Otherwise, setTimeout that gets called at the time of 'nextRunAt'
+    if (!job.attrs.nextRunAt || job.attrs.nextRunAt <= now) {
+      debug(
+        "[%s:%s] nextRunAt is in the past, run the job immediately",
+        job.attrs.name,
+        job.attrs._id
+      );
+      runOrRetry();
+    } else {
+      // @ts-expect-error linter complains about Date-arithmetic
+      const runIn = job.attrs.nextRunAt - now;
+      debug(
+        "[%s:%s] nextRunAt is in the future, calling setTimeout(%d)",
+        job.attrs.name,
+        job.attrs._id,
+        runIn
+      );
+      setTimeout(jobProcessing, runIn);
+    }
+
+    /**
+     * Internal method that tries to run a job and if it fails, retries again!
+     * @returns {undefined}
+     */
+    function runOrRetry() {
+      if (self._processInterval) {
+        // @todo: We should check if job exists
+        const job = jobQueue.pop()!;
+        const jobDefinition = definitions[job.attrs.name];
+        if (
+          jobDefinition.concurrency > jobDefinition.running &&
+          self._runningJobs.length < self._maxConcurrency
+        ) {
+          // Get the deadline of when the job is not supposed to go past for locking
+          const lockDeadline = new Date(
+            Date.now() - jobDefinition.lockLifetime
+          );
+
+          // This means a job has "expired", as in it has not been "touched" within the lockoutTime
+          // Remove from local lock
+          // NOTE: Shouldn't we update the 'lockedAt' value in MongoDB so it can be picked up on restart?
+          if (!job.attrs.lockedAt || job.attrs.lockedAt < lockDeadline) {
+            debug(
+              "[%s:%s] job lock has expired, freeing it up",
+              job.attrs.name,
+              job.attrs._id
+            );
+            self._lockedJobs.splice(self._lockedJobs.indexOf(job), 1);
+            jobDefinition.locked--;
+
+            // If you have few thousand jobs for one worker it would throw "RangeError: Maximum call stack size exceeded"
+            // every 5 minutes (using the default options).
+            // We need to utilise the setImmedaite() to break the call stack back to 0.
+            setImmediate(jobProcessing);
+            return;
+          }
+
+          // Add to local "running" queue
+          self._runningJobs.push(job);
+          jobDefinition.running++;
+
+          // CALL THE ACTUAL METHOD TO PROCESS THE JOB!!!
+          debug("[%s:%s] processing job", job.attrs.name, job.attrs._id);
+
+          job
+            .run()
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            .then((job: any) => processJobResult(job))
+            .catch((error: Error) => {
+              return job.agenda.emit("error", error);
+            });
+        } else {
+          // Run the job immediately by putting it on the top of the queue
+          debug(
+            "[%s:%s] concurrency preventing immediate run, pushing job to top of queue",
+            job.attrs.name,
+            job.attrs._id
+          );
+          enqueueJobs(job);
+        }
+      }
+    }
+  }
+
+  /**
+   * Internal method used to run the job definition
+   * @param {Error} err thrown if can't process job
+   * @param {Job} job job to process
+   */
+  function processJobResult(job: Job) {
+    const { name } = job.attrs;
+
+    // Job isn't in running jobs so throw an error
+    if (!self._runningJobs.includes(job)) {
+      debug(
+        "[%s] callback was called, job must have been marked as complete already",
+        job.attrs._id
+      );
+      throw new Error(
+        `callback already called - job ${name} already marked complete`
+      );
+    }
+
+    // Remove the job from the running queue
+    self._runningJobs.splice(self._runningJobs.indexOf(job), 1);
+    if (definitions[name].running > 0) {
+      definitions[name].running--;
+    }
+
+    // Remove the job from the locked queue
+    self._lockedJobs.splice(self._lockedJobs.indexOf(job), 1);
+    if (definitions[name].locked > 0) {
+      definitions[name].locked--;
+    }
+
+    // Re-process jobs now that one has finished
+    jobProcessing();
+  }
+};

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "agenda",
-  "version": "4.3.0",
+  "version": "5.0.0",
   "description": "Light weight job scheduler for Node.js",
   "main": "dist/cjs.js",
   "types": "dist/index.d.ts",
   "files": [
     "es.js",
-    "dist"
+    "dist",
+    "lib",
+    "tsconfig.json"
   ],
   "engines": {
     "node": ">=12.9.0"
@@ -15,15 +17,15 @@
     "prepublishOnly": "npm run build",
     "build": "tsc",
     "pretest": "npm run build",
-    "test": "npm run mocha",
+    "test": "USE_MONGODB=true npm run mocha",
     "lint": "eslint --cache --fix lib/**",
-    "mocha": "USE_MONGODB=true mocha --reporter spec --timeout 8000 --exit -b",
+    "mocha": "mocha --reporter spec --timeout 8000 --exit -b",
     "premocha-debug": "npm run build",
-    "mocha-debug": "USE_MONGODB=true DEBUG=agenda:**,-agenda:internal:** mocha --reporter spec --timeout 8000 -b",
+    "mocha-debug": "DEBUG=agenda:**,-agenda:internal:** mocha --reporter spec --timeout 8000 -b",
     "premocha-debug-internal": "npm run build",
-    "mocha-debug-internal": "USE_MONGODB=true DEBUG=agenda:internal:** mocha --reporter spec --timeout 8000 -b",
+    "mocha-debug-internal": "DEBUG=agenda:internal:** mocha --reporter spec --timeout 8000 -b",
     "premocha-debug-all": "npm run build",
-    "mocha-debug-all": "USE_MONGODB=true DEBUG=agenda:** mocha --reporter spec --timeout 8000 -b",
+    "mocha-debug-all": "DEBUG=agenda:** mocha --reporter spec --timeout 8000 -b",
     "postversion": "npm run docs",
     "predocs": "npm run build",
     "docs": "jsdoc --configure .jsdoc.json --verbose ./dist"
@@ -52,12 +54,12 @@
     "url": "https://github.com/agenda/agenda/issues"
   },
   "dependencies": {
-    "cron-parser": "^3.0.0",
+    "cron-parser": "^3.5.0",
     "date.js": "~0.3.3",
-    "debug": "~4.3.0",
-    "human-interval": "~2.0.0",
-    "moment-timezone": "~0.5.27",
-    "mongodb": "^4.1.0"
+    "debug": "~4.3.4",
+    "human-interval": "~2.0.1",
+    "moment-timezone": "~0.5.37",
+    "mongodb": "^4.11.0"
   },
   "devDependencies": {
     "@types/debug": "4.1.5",

package/tsconfig.json

@@ -0,0 +1,72 @@
+{
+  "include": [
+    "lib"
+  ],
+  "compilerOptions": {
+    /* Visit https://aka.ms/tsconfig.json to read more about this file */
+
+    /* Basic Options */
+    // "incremental": true,                   /* Enable incremental compilation */
+    "target": "es2016",                          /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020', or 'ESNEXT'. */
+    "module": "commonjs",                     /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', 'es2020', or 'ESNext'. */
+    // "lib": [],                             /* Specify library files to be included in the compilation. */
+    "allowJs": true,                       /* Allow javascript files to be compiled. */
+    // "checkJs": true,                       /* Report errors in .js files. */
+    // "jsx": "preserve",                     /* Specify JSX code generation: 'preserve', 'react-native', or 'react'. */
+    "declaration": true,                   /* Generates corresponding '.d.ts' file. */
+    "declarationMap": true,                /* Generates a sourcemap for each corresponding '.d.ts' file. */
+     "sourceMap": true,                     /* Generates corresponding '.map' file. */
+    // "outFile": "./",                       /* Concatenate and emit output to single file. */
+    "outDir": "./dist",                        /* Redirect output structure to the directory. */
+    // "rootDir": "./",                       /* Specify the root directory of input files. Use to control the output directory structure with --outDir. */
+    // "composite": true,                     /* Enable project compilation */
+    // "tsBuildInfoFile": "./",               /* Specify file to store incremental compilation information */
+    // "removeComments": true,                /* Do not emit comments to output. */
+    // "noEmit": true,                        /* Do not emit outputs. */
+    // "importHelpers": true,                 /* Import emit helpers from 'tslib'. */
+    // "downlevelIteration": true,            /* Provide full support for iterables in 'for-of', spread, and destructuring when targeting 'ES5' or 'ES3'. */
+    // "isolatedModules": true,               /* Transpile each file as a separate module (similar to 'ts.transpileModule'). */
+
+    /* Strict Type-Checking Options */
+    "strict": true,                           /* Enable all strict type-checking options. */
+    // "noImplicitAny": true,                 /* Raise error on expressions and declarations with an implied 'any' type. */
+    // "strictNullChecks": true,              /* Enable strict null checks. */
+    // "strictFunctionTypes": true,           /* Enable strict checking of function types. */
+    // "strictBindCallApply": true,           /* Enable strict 'bind', 'call', and 'apply' methods on functions. */
+    // "strictPropertyInitialization": true,  /* Enable strict checking of property initialization in classes. */
+    // "noImplicitThis": true,                /* Raise error on 'this' expressions with an implied 'any' type. */
+    // "alwaysStrict": true,                  /* Parse in strict mode and emit "use strict" for each source file. */
+
+    /* Additional Checks */
+    // "noUnusedLocals": true,                /* Report errors on unused locals. */
+    // "noUnusedParameters": true,            /* Report errors on unused parameters. */
+    // "noImplicitReturns": true,             /* Report error when not all code paths in function return a value. */
+    // "noFallthroughCasesInSwitch": true,    /* Report errors for fallthrough cases in switch statement. */
+
+    /* Module Resolution Options */
+    "moduleResolution": "node",            /* Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6). */
+    // "baseUrl": "./",                       /* Base directory to resolve non-absolute module names. */
+    // "paths": {},                           /* A series of entries which re-map imports to lookup locations relative to the 'baseUrl'. */
+    // "rootDirs": [],                        /* List of root folders whose combined content represents the structure of the project at runtime. */
+    // "typeRoots": [],                       /* List of folders to include type definitions from. */
+    // "types": [],                           /* Type declaration files to be included in compilation. */
+    // "allowSyntheticDefaultImports": true,  /* Allow default imports from modules with no default export. This does not affect code emit, just typechecking. */
+    "esModuleInterop": true,                  /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */
+    // "preserveSymlinks": true,              /* Do not resolve the real path of symlinks. */
+    // "allowUmdGlobalAccess": true,          /* Allow accessing UMD globals from modules. */
+
+    /* Source Map Options */
+    // "sourceRoot": "",                      /* Specify the location where debugger should locate TypeScript files instead of source locations. */
+    // "mapRoot": "",                         /* Specify the location where debugger should locate map files instead of generated locations. */
+    // "inlineSourceMap": true,               /* Emit a single file with source maps instead of having a separate file. */
+    // "inlineSources": true,                 /* Emit the source alongside the sourcemaps within a single file; requires '--inlineSourceMap' or '--sourceMap' to be set. */
+
+    /* Experimental Options */
+    // "experimentalDecorators": true,        /* Enables experimental support for ES7 decorators. */
+    // "emitDecoratorMetadata": true,         /* Enables experimental support for emitting type metadata for decorators. */
+
+    /* Advanced Options */
+    // "skipLibCheck": true,                     /* Skip type checking of declaration files. */
+    "forceConsistentCasingInFileNames": true  /* Disallow inconsistently-cased references to the same file. */
+  }
+}