@stonyx/cron 0.2.1-alpha.42 → 0.2.1-alpha.44

package/dist/main.d.ts

@@ -3,7 +3,24 @@ interface CronJob extends HeapItem {
     callback: () => void | Promise<void>;
     interval: string;
     key: string;
-    running: boolean;
+    /**
+     * Timestamp (ms) at which the current invocation started; `undefined` when the
+     * job is idle. Optional so the emitted `CronJob` stays assignable from a job
+     * object built by a consumer — `jobs`, `heap` and `setNextTrigger` all expose
+     * this interface structurally, so a required field is a breaking type change.
+     *
+     * A timestamp rather than a boolean, mirroring `job.state.runningAtMs` in the
+     * service tier (`markRunning` / `applyResult` / `isDue` in `src/job.ts`), and
+     * carrying the one fact a stuck-job warning needs: how long it has been stuck.
+     * `CronService.running` is a class-level re-entrancy flag and a different
+     * concept; reusing that word here would collide.
+     */
+    runningAtMs?: number;
+    /**
+     * True once a skip has been reported for the *current* invocation. Bounds the
+     * still-running warning to one line per stuck run instead of one per tick.
+     */
+    skipReported?: boolean;
 }
 export default class Cron {
     static instance: Cron | null;
@@ -17,14 +34,32 @@ export default class Cron {
     register(key: string, callback: () => void | Promise<void>, interval: string, runOnInit?: boolean): void;
     unregister(key: string): void;
     /**
-     * Invoke a consumer callback without ever blocking the caller.
+     * The one place this class invokes a consumer callback.
+     *
+     * Never blocks the caller, catches synchronous throws and asynchronous
+     * rejections identically, and skips the invocation entirely while the job's
+     * previous invocation has not settled (fire-and-forget would otherwise let a
+     * slow job stack invocations on itself).
+     *
+     * Everything that touches the callback — including the thenable probe and the
+     * handler attachment — is inside the `try`. A callback may return an object
+     * whose `then` is a throwing getter, and reading it outside the guard would
+     * abort the drain loop before `scheduleNextRun()`, which is defect #36 again.
+     */
+    invokeJob(job: CronJob, runOnInit?: boolean): void;
+    /**
+     * Report a scheduler-level message without ever letting the logger's own
+     * failure reach the caller.
      *
-     * Synchronous throws and rejected thenables are both routed to `log.error`
-     * with `errorMessage`; a callback that never settles simply never clears its
-     * in-flight flag. The job is skipped (and logged) while a previous invocation
-     * is still running, so fire-and-forget cannot stack invocations on one job.
+     * `@stonyx/logs` convenience methods return a promise and write to disk
+     * through an unguarded `mkdirSync` + `fsp.appendFile`. On a read-only or full
+     * log volume that promise rejects; an unobserved rejection raised from inside
+     * the handler that exists to prevent unhandled rejections would re-create
+     * exactly the defect this class was fixed for.
      */
-    invokeJob(job: CronJob, errorMessage: string): void;
+    report(level: 'error' | 'warn', message: string): void;
+    /** Release a job's in-flight guard. Only ever called for the job it belongs to. */
+    release(job: CronJob): void;
     setNextTrigger(job: CronJob): void;
     log(text: string, key?: string | null): void;
 }

package/dist/main.js

@@ -17,6 +17,30 @@ import config from 'stonyx/config';
 import log from 'stonyx/log';
 import { getTimestamp } from '@stonyx/utils/date';
 import MinHeap from './min-heap.js';
+/**
+ * Render an unknown thrown value as log text.
+ *
+ * `@stonyx/logs` reads a second argument as `logToFile`, not as a format
+ * argument, so `log.error(message, err)` discards the error entirely *and*
+ * forces a disk write on every failure. The error has to be interpolated into
+ * the message instead — the shape `CronService.executeJob` already uses.
+ */
+function describeError(err) {
+    if (err instanceof Error)
+        return err.stack ?? `${err.name}: ${err.message}`;
+    return String(err);
+}
+/**
+ * Render a consumer-supplied job key safely for log output.
+ *
+ * Keys reach the log verbatim, so a key containing a newline can forge a
+ * complete, well-formed log line (`'a:\n[FORGED] Cron::admin - all jobs
+ * healthy'`). `JSON.stringify` quotes the value and escapes the control
+ * characters, which is also how the key is rendered one tier up.
+ */
+function describeKey(key) {
+    return JSON.stringify(key);
+}
 export default class Cron {
     static instance;
     jobs = {};
@@ -43,38 +67,52 @@ export default class Cron {
         if (!nextJob)
             return;
         const delay = Math.max(0, nextJob.nextTrigger - getTimestamp()) * 1000;
-        this.timer = setTimeout(() => this.runDueJobs(), delay);
+        // Terminal catch: `runDueJobs` is async, so anything that escapes it would
+        // otherwise become an unhandled rejection raised from a bare timer callback
+        // — the very failure mode this class was fixed for.
+        this.timer = setTimeout(() => {
+            this.runDueJobs().catch((err) => {
+                this.report('error', `Cron scheduler tick failed: ${describeError(err)}`);
+            });
+        }, delay);
     }
     async runDueJobs() {
         const now = getTimestamp();
         const { heap } = this;
-        while (!heap.isEmpty()) {
-            const next = heap.peek();
-            if (!next || next.nextTrigger > now)
-                break;
-            const job = heap.pop();
-            if (config.debug)
-                this.log('job has been triggered', job.key);
-            // Reschedule before invoking: a consumer callback is never awaited here,
-            // so a callback that hangs or rejects can no longer starve the drain loop
-            // or leave the job orphaned outside the heap.
-            this.setNextTrigger(job);
-            heap.push(job);
-            this.invokeJob(job, `Cron job "${job.key}" failed:`);
+        // `finally`, not a trailing statement: `scheduleNextRun()` running on every
+        // exit from the drain loop is the invariant this whole fix is about. If
+        // anything in the loop body ever throws, the scheduler must still re-arm
+        // rather than stopping silently while `timer` still holds a fired handle.
+        try {
+            while (!heap.isEmpty()) {
+                const next = heap.peek();
+                if (!next || next.nextTrigger > now)
+                    break;
+                const job = heap.pop();
+                if (config.debug)
+                    this.log('job has been triggered', job.key);
+                // Reschedule before invoking: a consumer callback is never awaited here,
+                // so a callback that hangs or rejects can no longer starve the drain loop
+                // or leave the job orphaned outside the heap.
+                this.setNextTrigger(job);
+                heap.push(job);
+                this.invokeJob(job);
+            }
+        }
+        finally {
+            this.scheduleNextRun();
         }
-        this.scheduleNextRun();
     }
     register(key, callback, interval, runOnInit = false) {
-        const job = { callback, interval, key, nextTrigger: 0, running: false };
+        const job = { callback, interval, key, nextTrigger: 0 };
         this.jobs[key] = job;
         this.setNextTrigger(job);
         this.heap.push(job);
         if (config.debug) {
             this.log(`job has been registered with interval: ${interval}`, key);
         }
-        if (runOnInit) {
-            this.invokeJob(job, `Cron job "${key}" failed on init:`);
-        }
+        if (runOnInit)
+            this.invokeJob(job, true);
         this.scheduleNextRun();
     }
     unregister(key) {
@@ -89,37 +127,92 @@ export default class Cron {
         this.scheduleNextRun();
     }
     /**
-     * Invoke a consumer callback without ever blocking the caller.
+     * The one place this class invokes a consumer callback.
      *
-     * Synchronous throws and rejected thenables are both routed to `log.error`
-     * with `errorMessage`; a callback that never settles simply never clears its
-     * in-flight flag. The job is skipped (and logged) while a previous invocation
-     * is still running, so fire-and-forget cannot stack invocations on one job.
+     * Never blocks the caller, catches synchronous throws and asynchronous
+     * rejections identically, and skips the invocation entirely while the job's
+     * previous invocation has not settled (fire-and-forget would otherwise let a
+     * slow job stack invocations on itself).
+     *
+     * Everything that touches the callback — including the thenable probe and the
+     * handler attachment — is inside the `try`. A callback may return an object
+     * whose `then` is a throwing getter, and reading it outside the guard would
+     * abort the drain loop before `scheduleNextRun()`, which is defect #36 again.
      */
-    invokeJob(job, errorMessage) {
-        if (job.running) {
-            this.log('job is still running, skipping this run', job.key);
+    invokeJob(job, runOnInit = false) {
+        const { key } = job;
+        const context = runOnInit ? 'failed on init:' : 'failed:';
+        // The in-flight guard lives on the job object, not in a module-level set
+        // keyed by string. Object identity is invocation identity: the only thing
+        // that clears the guard is the settle handler of the invocation that set it,
+        // and that handler closes over this exact job object, so a stale handler can
+        // never release a later invocation's guard.
+        if (job.runningAtMs !== undefined) {
+            // Bounded to one line per stuck run, not one per tick. A permanently hung
+            // job is re-pushed and re-skipped every interval forever; at the 1s
+            // interval this class's own tests use that measures 43,200 lines/day per
+            // job — a disk-fill and ingest-cost vector whose natural operator response
+            // is to silence the only signal that the job is dead.
+            if (!job.skipReported) {
+                job.skipReported = true;
+                const runningForSeconds = Math.max(0, Math.round((Date.now() - job.runningAtMs) / 1000));
+                // Ungated, deliberately, matching the sibling `CronService` handler. A
+                // skipped run is a *lost* execution, and `runDueJobs`/`register` both
+                // return `void`, so this is the legacy class's only wedged-job channel.
+                // Routing it through `this.log` would put it behind `config.cron.log`,
+                // where a permanently dead job is indistinguishable from a healthy one.
+                this.report('warn', `Cron job ${describeKey(key)} is still running after ${runningForSeconds}s; skipping this `
+                    + 'tick and any further ticks until it settles (this warning is not repeated for this run)');
+            }
             return;
         }
-        job.running = true;
-        const settle = () => { job.running = false; };
-        let result;
+        job.runningAtMs = Date.now();
+        job.skipReported = false;
         try {
-            result = job.callback();
+            const result = job.callback();
+            if (result && typeof result.then === 'function') {
+                Promise.resolve(result)
+                    .catch((err) => {
+                    // Braces matter: returning `report`'s value would put it back into
+                    // the chain, and `.finally` passes a rejection straight through.
+                    this.report('error', `Cron job ${describeKey(key)} ${context} ${describeError(err)}`);
+                })
+                    .finally(() => { this.release(job); })
+                    // Backstop: a throw inside the error handler or the release must not
+                    // re-create the unhandled rejection this helper exists to prevent.
+                    .catch(() => { });
+                return;
+            }
+            this.release(job);
         }
         catch (err) {
-            log.error(errorMessage, err);
-            settle();
-            return;
+            this.release(job);
+            this.report('error', `Cron job ${describeKey(key)} ${context} ${describeError(err)}`);
         }
-        if (!result || typeof result.then !== 'function') {
-            settle();
-            return;
+    }
+    /**
+     * Report a scheduler-level message without ever letting the logger's own
+     * failure reach the caller.
+     *
+     * `@stonyx/logs` convenience methods return a promise and write to disk
+     * through an unguarded `mkdirSync` + `fsp.appendFile`. On a read-only or full
+     * log volume that promise rejects; an unobserved rejection raised from inside
+     * the handler that exists to prevent unhandled rejections would re-create
+     * exactly the defect this class was fixed for.
+     */
+    report(level, message) {
+        try {
+            const result = level === 'error' ? log.error(message) : log.warn(message);
+            void Promise.resolve(result).catch(() => { });
         }
-        result.then(settle, (err) => {
-            log.error(errorMessage, err);
-            settle();
-        });
+        catch {
+            // Nowhere left to report to; the logger must never stop the scheduler.
+        }
+    }
+    /** Release a job's in-flight guard. Only ever called for the job it belongs to. */
+    release(job) {
+        job.runningAtMs = undefined;
+        job.skipReported = false;
     }
     setNextTrigger(job) {
         job.nextTrigger = getTimestamp() + parseInt(job.interval, 10);
@@ -127,7 +220,10 @@ export default class Cron {
     log(text, key = null) {
         if (!config.cron?.log)
             return;
-        const tag = key ? `Cron::${key}` : `Cron`;
+        // The key is consumer-controlled and reaches the log verbatim. Strip the
+        // line terminators so a key cannot forge a second, well-formed log line;
+        // the surrounding format is unchanged.
+        const tag = key ? `Cron::${key.replace(/[\r\n]+/g, ' ')}` : `Cron`;
         log.cron(`${tag} - ${text}:`);
     }
 }

package/package.json

@@ -3,7 +3,7 @@
   "keywords": [
     "stonyx-module"
   ],
-  "version": "0.2.1-alpha.42",
+  "version": "0.2.1-alpha.44",
   "description": "Cron/job scheduler for Stonyx framework",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",
@@ -79,7 +79,7 @@
     "typescript": "^5.8.3"
   },
   "dependencies": {
-    "stonyx": "0.2.3-beta.81"
+    "stonyx": "0.2.3-beta.83"
   },
   "scripts": {
     "build": "tsc",