@stonyx/cron 0.2.1-beta.120 → 0.2.1-beta.121

package/README.md

@@ -35,20 +35,34 @@ When a job is executed, its next trigger time is updated, and it is re-inserted
 |  `register`  | `key: string, callback: Function, interval: number, runOnInit?: boolean` | Register a new job with a given interval in seconds. If `runOnInit` is true, the job runs immediately upon registration. |
 | `unregister` |                               `key: string`                              | Remove a previously registered job.                                                                                      |
 
+> **Callback semantics.** Callbacks are invoked fire-and-forget: `Cron` never waits for one to settle, and reschedules a job *before* invoking it. Two *different* jobs that fall due on the same tick may therefore overlap.
+>
+> A job that is still running when it next falls due is skipped — and **keeps** being skipped until that invocation settles. `Cron` provides no timeout by design, so **bounding your own callback is your responsibility**: a promise that never settles means that job never runs again for the lifetime of the process, even though the scheduler stays healthy and the job stays visible in `jobs` and in the heap. Other jobs are unaffected.
+>
+> One warning is emitted per stuck run (not per tick), including how long the invocation has been running. That warning goes to `log.warn` and is **not** gated by `config.cron.log` — a dropped execution reported on a channel a config flag can silence would be indistinguishable from a healthy scheduler.
+>
+> The same-job guarantee holds for the lifetime of a **registration**, not of a key: `unregister` followed by `register` on a key whose invocation is still in flight builds a fresh job object with a fresh guard, so the replacement can run alongside the abandoned invocation. That is also the only way to recover a permanently stuck job.
+>
+> Synchronous throws and asynchronous rejections are both caught and reported through `log.error`, with the error's stack interpolated into the message. Neither can stop the scheduler. Note that a rejection which previously escaped `register()` as an unhandled rejection — process-fatal under Node's default — is now swallowed into `log.error`.
+
 > `MinHeap` is also exported as a public subpath (`@stonyx/cron/min-heap`) and can be imported directly for advanced usage.
 
 ## Configuration
 
-Optionally, logging and debugging can be enabled through `config.cron`:
+Optionally, informational logging and debugging can be controlled through `config.cron`:
 
 ```js
 config.cron = {
-  log: true // enable cron job logs
+  log: true // informational cron job logs; defaults to true
 };
 
 config.debug = true; // optional: debug logs for job registration and execution
 ```
 
+`config.cron.log` gates **informational** messages only. Error reports and the
+stuck-job warning described above are never gated by it, so setting it to `false`
+cannot make a dropped execution silent.
+
 ## License
 
 Apache — do what you want, just keep attribution.

package/dist/main.d.ts

@@ -3,6 +3,24 @@ interface CronJob extends HeapItem {
     callback: () => void | Promise<void>;
     interval: string;
     key: string;
+    /**
+     * 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;
@@ -15,6 +33,33 @@ export default class Cron {
     runDueJobs(): Promise<void>;
     register(key: string, callback: () => void | Promise<void>, interval: string, runOnInit?: boolean): void;
     unregister(key: string): void;
+    /**
+     * 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.
+     *
+     * `@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: '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,68 @@ import config from 'stonyx/config';
 import log from 'stonyx/log';
 import { getTimestamp } from '@stonyx/utils/date';
 import MinHeap from './min-heap.js';
+/** Longest error text that may reach a log line. Anything past this is truncated. */
+const MAX_LOGGED_ERROR_LENGTH = 512;
+/**
+ * Flatten a value for interpolation into a single log line.
+ *
+ * `@stonyx/logs` writes `${timestamp} ${content}\n` to a newline-delimited
+ * file, so any `\r` or `\n` inside `content` ends the record early and
+ * everything after it is read back as a separate entry — including a forged
+ * `[timestamp] ...` prefix that is indistinguishable from a real one. Newlines
+ * become the literal two characters so the content survives for a reader, and
+ * the length cap keeps one pathological value from swamping the file.
+ *
+ * Kept byte-identical to the `forLog` landing in `src/service.ts` on #34: the
+ * two tiers render the same untrusted values into the same log file, and a
+ * reader diagnosing a forged record should not have to know which tier wrote
+ * it. Duplicated rather than shared because the two land on separate branches;
+ * folding them into one helper is a follow-up once both are on `dev`, not a
+ * cross-PR dependency that would make either unmergeable alone.
+ */
+function forLog(value, maxLength) {
+    const flattened = value.replace(/\r\n|[\r\n\u2028\u2029]/g, '\\n');
+    return flattened.length > maxLength ? `${flattened.slice(0, maxLength)}...` : flattened;
+}
+/**
+ * Render an unknown thrown value as log text. Total by construction.
+ *
+ * `@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.
+ *
+ * Every read below touches a consumer-controlled value and can therefore throw:
+ * `instanceof` runs a proxy's `getPrototypeOf` trap, `stack`/`name`/`message`
+ * can be accessor properties, and `String(Object.create(null))` throws outright.
+ * This function runs *inside* `invokeJob`'s catch — the one place whose job is
+ * to stop a callback failure from reaching the scheduler — so a throw here
+ * escapes that catch and skips `scheduleNextRun()`, which is defect #36.
+ */
+function describeError(err) {
+    try {
+        if (err instanceof Error) {
+            return forLog(err.stack ?? `${err.name}: ${err.message}`, MAX_LOGGED_ERROR_LENGTH);
+        }
+        return forLog(String(err), MAX_LOGGED_ERROR_LENGTH);
+    }
+    catch {
+        // Deliberately not re-entrant: describing the failure to describe the error
+        // would be the same read that just threw.
+        return '<thrown value could not be rendered>';
+    }
+}
+/**
+ * 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,28 +105,41 @@ 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);
-            try {
-                await job.callback();
+        // `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);
             }
-            catch (err) {
-                log.error(`Cron job "${job.key}" failed:`, err);
-            }
-            this.setNextTrigger(job);
-            heap.push(job);
         }
-        this.scheduleNextRun();
+        finally {
+            this.scheduleNextRun();
+        }
     }
     register(key, callback, interval, runOnInit = false) {
         const job = { callback, interval, key, nextTrigger: 0 };
@@ -74,15 +149,18 @@ export default class Cron {
         if (config.debug) {
             this.log(`job has been registered with interval: ${interval}`, key);
         }
-        if (runOnInit) {
-            try {
-                callback();
-            }
-            catch (err) {
-                log.error(`Cron job "${key}" failed on init:`, err);
-            }
+        // `finally`, not a trailing statement, for the same reason as `runDueJobs`:
+        // a job that is registered but never scheduled is defect #36's terminal
+        // state reached through the other entry point. `invokeJob` is total, so
+        // this guard should be unreachable — which is exactly why it is a guard and
+        // not an assumption.
+        try {
+            if (runOnInit)
+                this.invokeJob(job, true);
+        }
+        finally {
+            this.scheduleNextRun();
         }
-        this.scheduleNextRun();
     }
     unregister(key) {
         const { heap, jobs } = this;
@@ -95,13 +173,104 @@ export default class Cron {
             this.log('job has been unregistered', key);
         this.scheduleNextRun();
     }
+    /**
+     * 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, 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.runningAtMs = Date.now();
+        job.skipReported = false;
+        try {
+            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) {
+            this.release(job);
+            this.report('error', `Cron job ${describeKey(key)} ${context} ${describeError(err)}`);
+        }
+    }
+    /**
+     * 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(() => { });
+        }
+        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);
     }
     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-beta.120",
+  "version": "0.2.1-beta.121",
   "description": "Cron/job scheduler for Stonyx framework",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",