fix: prevent jobs from stopping unexpectedly (#963)

Author: sheerlox

README.md

@@ -195,7 +195,7 @@ day of week    0-7 (0 or 7 is Sunday, or use names)
 
 #### Constructor
 
-`constructor(cronTime, onTick, onComplete, start, timeZone, context, runOnInit, utcOffset, unrefTimeout)`:
+`constructor(cronTime, onTick, onComplete, start, timeZone, context, runOnInit, utcOffset, unrefTimeout, waitForCompletion, errorHandler, name, threshold)`:
 
 - `cronTime`: [REQUIRED] - The time to fire off your job. Can be cron syntax, a JS [`Date`](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date) object or a Luxon [`DateTime`](https://moment.github.io/luxon/api-docs/index.html#datetime) object.
 
@@ -219,6 +219,10 @@ day of week    0-7 (0 or 7 is Sunday, or use names)
 
 - `errorHandler`: [OPTIONAL] - Function to handle any exceptions that occur in the `onTick` method.
 
+- `name`: [OPTIONAL] - Name of the job. Useful for identifying jobs in logs.
+
+- `threshold`: [OPTIONAL] - Threshold in ms to control whether to execute or skip missed execution deadlines caused by slow or busy hardware. Execution delays within threshold will be executed immediately, and otherwise will be skipped. In both cases a warning will be printed to the console with the job name and cron expression. See [issue #962](https://github.com/kelektiv/node-cron/issues/962) for more information. Default is `250`.
+
 #### Methods
 
 - `from` (static): Create a new CronJob object providing arguments as an object. See argument names and descriptions above.

src/job.ts

@@ -22,6 +22,8 @@ export class CronJob<OC extends CronOnCompleteCommand | null = null, C = null> {
 		: undefined;
 	waitForCompletion = false;
 	errorHandler?: CronJobParams<OC, C>['errorHandler'];
+	name?: string; // optional job name for identification
+	threshold = 250; // default threshold in ms
 
 	private _isActive = false;
 	private _isCallbackRunning = false;
@@ -47,7 +49,9 @@ export class CronJob<OC extends CronOnCompleteCommand | null = null, C = null> {
 		utcOffset?: null,
 		unrefTimeout?: CronJobParams<OC, C>['unrefTimeout'],
 		waitForCompletion?: CronJobParams<OC, C>['waitForCompletion'],
-		errorHandler?: CronJobParams<OC, C>['errorHandler']
+		errorHandler?: CronJobParams<OC, C>['errorHandler'],
+		name?: CronJobParams<OC, C>['name'],
+		threshold?: CronJobParams<OC, C>['threshold']
 	);
 	constructor(
 		cronTime: CronJobParams<OC, C>['cronTime'],
@@ -60,7 +64,9 @@ export class CronJob<OC extends CronOnCompleteCommand | null = null, C = null> {
 		utcOffset?: CronJobParams<OC, C>['utcOffset'],
 		unrefTimeout?: CronJobParams<OC, C>['unrefTimeout'],
 		waitForCompletion?: CronJobParams<OC, C>['waitForCompletion'],
-		errorHandler?: CronJobParams<OC, C>['errorHandler']
+		errorHandler?: CronJobParams<OC, C>['errorHandler'],
+		name?: CronJobParams<OC, C>['name'],
+		threshold?: CronJobParams<OC, C>['threshold']
 	);
 	constructor(
 		cronTime: CronJobParams<OC, C>['cronTime'],
@@ -73,7 +79,9 @@ export class CronJob<OC extends CronOnCompleteCommand | null = null, C = null> {
 		utcOffset?: CronJobParams<OC, C>['utcOffset'],
 		unrefTimeout?: CronJobParams<OC, C>['unrefTimeout'],
 		waitForCompletion?: CronJobParams<OC, C>['waitForCompletion'],
-		errorHandler?: CronJobParams<OC, C>['errorHandler']
+		errorHandler?: CronJobParams<OC, C>['errorHandler'],
+		name?: CronJobParams<OC, C>['name'],
+		threshold?: CronJobParams<OC, C>['threshold']
 	) {
 		this.context = (context ?? this) as CronContext<C>;
 		this.waitForCompletion = Boolean(waitForCompletion);
@@ -104,6 +112,14 @@ export class CronJob<OC extends CronOnCompleteCommand | null = null, C = null> {
 			) as WithOnComplete<OC> extends true ? CronOnCompleteCallback : undefined;
 		}
 
+		if (threshold != null) {
+			this.threshold = Math.abs(threshold);
+		}
+
+		if (name != null) {
+			this.name = name;
+		}
+
 		if (this.cronTime.realDate) {
 			this.runOnce = true;
 		}
@@ -139,7 +155,9 @@ export class CronJob<OC extends CronOnCompleteCommand | null = null, C = null> {
 				params.utcOffset,
 				params.unrefTimeout,
 				params.waitForCompletion,
-				params.errorHandler
+				params.errorHandler,
+				params.name,
+				params.threshold
 			);
 		} else if (params.utcOffset != null) {
 			return new CronJob<OC, C>(
@@ -153,7 +171,9 @@ export class CronJob<OC extends CronOnCompleteCommand | null = null, C = null> {
 				params.utcOffset,
 				params.unrefTimeout,
 				params.waitForCompletion,
-				params.errorHandler
+				params.errorHandler,
+				params.name,
+				params.threshold
 			);
 		} else {
 			return new CronJob<OC, C>(
@@ -167,7 +187,9 @@ export class CronJob<OC extends CronOnCompleteCommand | null = null, C = null> {
 				params.utcOffset,
 				params.unrefTimeout,
 				params.waitForCompletion,
-				params.errorHandler
+				params.errorHandler,
+				params.name,
+				params.threshold
 			);
 		}
 	}
@@ -250,6 +272,7 @@ export class CronJob<OC extends CronOnCompleteCommand | null = null, C = null> {
 
 	start() {
 		if (this._isActive) return;
+		this._isActive = true;
 
 		const MAXDELAY = 2147483647; // the maximum number of milliseconds setTimeout will wait.
 		let timeout = this.cronTime.getTimeout();
@@ -307,8 +330,6 @@ export class CronJob<OC extends CronOnCompleteCommand | null = null, C = null> {
 		};
 
 		if (timeout >= 0) {
-			this._isActive = true;
-
 			// don't try to sleep more than MAXDELAY ms at a time.
 
 			if (timeout > MAXDELAY) {
@@ -318,7 +339,26 @@ export class CronJob<OC extends CronOnCompleteCommand | null = null, C = null> {
 
 			setCronTimeout(timeout);
 		} else {
-			this.stop();
+			// handle negative timeout
+			const absoluteTimeout = Math.abs(timeout);
+
+			const message = `[Cron] Missed execution deadline by ${absoluteTimeout}ms for job${this.name ? ` "${this.name}"` : ''} with cron expression '${String(this.cronTime.source)}'`;
+
+			if (absoluteTimeout <= this.threshold) {
+				// execute immediately if within threshold
+				console.warn(`${message}. Executing immediately.`);
+
+				this.lastExecution = new Date();
+				void this.fireOnTick();
+			} else {
+				// skip job if beyond threshold
+				console.warn(
+					`${message}. Skipping execution as it exceeds threshold (${this.threshold}ms).`
+				);
+			}
+
+			timeout = this.cronTime.getTimeout();
+			setCronTimeout(timeout);
 		}
 	}
 

src/time.ts

@@ -169,9 +169,18 @@ export class CronTime {
 
 	/**
 	 * get the number of milliseconds in the future at which to fire our callbacks.
+	 *
+	 * Can return a negative value when `sendAt` took too long to execute.
+	 * This is then handled in `CronJob` to execute the job immediately or skip
+	 * this execution based on the `threshold` option.
+	 *
+	 * We could instead call DateTime.local before `sendAt` to get the current time, but
+	 * then the calculated timeout would be offset by the time it takes to execute `sendAt`.
+	 *
+	 * As such it is better to handle negative timeouts by executing the job immediately.
 	 */
 	getTimeout() {
-		return Math.max(-1, this.sendAt().toMillis() - DateTime.utc().toMillis());
+		return this.sendAt().toMillis() - DateTime.local().toMillis();
 	}
 
 	/**

src/types/cron.types.ts

@@ -17,6 +17,8 @@ interface BaseCronJobParams<
 	unrefTimeout?: boolean | null;
 	waitForCompletion?: boolean | null;
 	errorHandler?: ((error: unknown) => void) | null;
+	threshold?: number | null;
+	name?: string | null;
 }
 
 export type CronJobParams<

tests/cron.test.ts

@@ -18,6 +18,39 @@ describe('cron', () => {
 		sinon.restore();
 	});
 
+	it('should not stop job if sendAt takes time to complete (#962)', () => {
+		const EVERY = 5;
+		const TICK = EVERY * 1000;
+		const DELAY = 350;
+
+		const job = CronJob.from({
+			cronTime: `*/${EVERY} * * * * *`,
+			onTick: callback,
+			start: false,
+			threshold: 350
+		});
+
+		sinon
+			.stub(job.cronTime, 'getTimeout')
+			.onCall(0)
+			.returns(TICK)
+			.onCall(1)
+			.returns(-DELAY);
+
+		const clock = sinon.useFakeTimers();
+
+		// mock console.warn to avoid poluting tests with the warning
+		const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+
+		job.start();
+
+		clock.tick(TICK);
+		expect(job.isActive).toBe(true);
+
+		job.stop();
+		warnSpy.mockRestore();
+	});
+
 	describe('with seconds', () => {
 		it('should run every second (* * * * * *)', () => {
 			const clock = sinon.useFakeTimers();