@stonyx/cron 0.2.1-alpha.60 → 0.2.1-alpha.61

package/README.md

@@ -51,7 +51,7 @@ When a job is executed, its next trigger time is updated, and it is re-inserted
 
 The default export above is `Cron`: a fire-and-forget interval registry. `@stonyx/cron/service` is a separate, heavier class for jobs that need CRUD, persistence, a run log and error backoff. It is not a drop-in replacement and the two do not share a scheduler.
 
-The two classes agree on the guarantee — the same job is never run concurrently with itself, and different jobs may overlap — but not on the mechanism or on what you can observe. `Cron` invokes callbacks fire-and-forget and reports a skipped run only through the `config.cron`-gated log. `CronService` **awaits** `onJobDue`, its return value shapes `status`/`error`/`summary`, and a refused run comes back to the caller as a value that no log setting can suppress — it is not logged.
+The two classes agree on the guarantee — the same job is never run concurrently with itself, and different jobs may overlap — but not on the mechanism or on what you can observe. `Cron` invokes callbacks fire-and-forget and reports a skipped run only as an ungated `log.warn` line, one per stuck run, never as a value. `CronService` **awaits** `onJobDue`, its return value shapes `status`/`error`/`summary`, and a refused run comes back to the caller as a value that no log setting can suppress — it is not logged. The two therefore agree on one more thing than the contrast suggests: neither can be made silent by `config.cron.log`.
 
 ```js
 import CronService from '@stonyx/cron/service';

package/dist/service.d.ts

@@ -44,7 +44,38 @@ export default class CronService {
     onJobDue: OnJobDueCallback | null;
     constructor();
     /**
-     * Start the service. Loads jobs from store (if any), arms timer.
+     * Start the service. Loads jobs from store (if any), arms timer. A no-op if
+     * already started.
+     *
+     * `initialJobs` crosses a serialization boundary — it is whatever the
+     * consumer's store handed back — so `Job[]` is a compile-time claim about
+     * runtime data. Three behaviours follow from that and are worth knowing
+     * before you call this, because all three are deliberate and two of them
+     * differ from a plain "load and arm":
+     *
+     * 1. WRITES TO `row.state`. A STALE claim (`state.runningAtMs` set by a
+     *    process that is gone) is released, because nothing else ever will —
+     *    there is no lease on the field (#35) — and left in place it is a job
+     *    that is dead forever while `status()` reports it healthy. A LIVE claim,
+     *    held by an invocation still running in this process, is left alone:
+     *    releasing it would let the timer start a second concurrent invocation of
+     *    a job that is already running.
+     *
+     * 2. THROWS on a row this class cannot use, rather than accepting it. A row
+     *    whose `state` is missing, or frozen (`structuredClone` + `Object.freeze`
+     *    is an ordinary defensive rehydration), throws out of `start()` where the
+     *    caller's own `await` can catch it. The alternative is a `TypeError` from
+     *    inside a bare timer callback later — an unhandled rejection, and
+     *    process-fatal under Node's default.
+     *
+     * 3. ARMS THE TIMER EVEN IF IT THROWS. The rows loaded before the throw are
+     *    registered and scheduled. Without this, a throw leaves `started: true`
+     *    (so a retry is a no-op) with jobs in the heap and no timer: nothing ever
+     *    fires and `status()` still reports healthy.
+     *
+     * Hand it deserialized rows and all three are invisible. Hand it live `Job`
+     * objects this service is currently executing and only 1 is observable, by
+     * design.
      */
     start(initialJobs?: Job[]): Promise<void>;
     /**

package/dist/service.js

@@ -43,9 +43,39 @@ const MAX_LOGGED_NAME_LENGTH = 120;
  * text. 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.
+ *
+ * TOTAL, for the same reason `describeError` below is total, and the parameter
+ * is coerced even though it is typed `string`. `job.name` is typed `string` but
+ * that is a compile-time claim about runtime data: `normalize.ts` only
+ * GENERATES a name when the field is falsy, so `add({ name: 12345 })` stores a
+ * number through the public API, and `start(initialJobs)` takes names verbatim
+ * from the consumer's store \u2014 the same untrusted boundary `start()` already
+ * hardens `state` against.
+ *
+ * Fixed HERE rather than by coercing in `normalize`, deliberately. Coercing at
+ * `normalize` closes the `add()` path only; the rehydration path bypasses both
+ * `normalize` and `createJob` entirely, and that is the path this class already
+ * treats as hostile. And this helper is on the ERROR path \u2014 a helper that
+ * throws while building an error report destroys the report it exists to
+ * produce. Measured pre-fix: `run()` rejected with `TypeError: value.replace is
+ * not a function` instead of returning an `ExecuteResult`, and on the timer
+ * path the failure record was swallowed entirely (0 records for a job that
+ * failed) because the throw happened inside the reporter's own `try`.
+ *
+ * `String(value)` alone is NOT enough: a value whose `toString` or
+ * `Symbol.toPrimitive` throws raises out of the coercion itself, so the `try`
+ * is load-bearing and not belt-and-braces. Kept typed `string` rather than
+ * widened to `unknown` so call sites still get compile-time pressure; the
+ * runtime coercion is the defence, not the signature.
  */
 function forLog(value, maxLength) {
-    const flattened = value.replace(/\r\n|[\r\n\u2028\u2029]/g, '\\n');
+    let flattened;
+    try {
+        flattened = String(value).replace(/\r\n|[\r\n\u2028\u2029]/g, '\\n');
+    }
+    catch {
+        return '<unrenderable value>';
+    }
     return flattened.length > maxLength ? `${flattened.slice(0, maxLength)}...` : flattened;
 }
 /**
@@ -70,8 +100,11 @@ function forLog(value, maxLength) {
  * differ: it renders for a log line only, so it prefers `err.stack`; this one
  * is also returned to the caller as `ExecuteResult.error` and persisted in a
  * per-job run log, where a stack would be an unbounded blob in every stored
- * failure. Recorded in `docs/architecture.md` under Error Handling — do not
- * merge them into a shared helper without reading that first.
+ * failure. Recorded in `docs/architecture.md` under Code Patterns &
+ * Conventions -> Private Members -> "Two `describeError` helpers, deliberately
+ * not shared (#34 / #36)" — do not merge them into a shared helper without
+ * reading that first. NOT the `### Error Handling` section further down, which
+ * is about the legacy `Cron` and does not carry this decision.
  */
 function describeError(err) {
     try {
@@ -81,6 +114,33 @@ function describeError(err) {
         return 'unknown error';
     }
 }
+/**
+ * Job objects whose claim is held by an invocation still running IN THIS
+ * PROCESS. Added by phase 1, removed by phase 3 (or by the one hand-release in
+ * `#executeClaimed`), so membership is exactly "a settle is still coming".
+ *
+ * This exists so `start()` can tell a STALE claim from a LIVE one. Both look
+ * identical in `job.state.runningAtMs` — a number — but they need opposite
+ * treatment: a stale claim must be released (it is #34's permanently-dead job,
+ * and nothing reaps it) while a live one must be left alone (releasing it lets
+ * the timer launch a second concurrent invocation of a job that is already
+ * running, breaking the one invariant this class advertises).
+ *
+ * Keyed on the Job OBJECT, not the id, and module-level rather than per
+ * instance, for the two reasons that make those the only workable choices:
+ *
+ *   - Object identity is what makes it correct across `CronService` instances.
+ *     A second service handed live rows sees the same objects, so it inherits
+ *     the answer rather than guessing; a per-instance set would report "not in
+ *     flight" for a claim a sibling instance is holding. `locked()`'s chain is
+ *     already module-global for the same reason.
+ *   - Identity is also what makes it correct after a real crash. A restart
+ *     deserializes its rows, so those are new objects and are never members —
+ *     the #34 release still fires, which is the whole point of it.
+ *
+ * `WeakSet`, so a job that is removed and dropped mid-flight is not retained.
+ */
+const inFlight = new WeakSet();
 export default class CronService {
     jobs;
     heap;
@@ -101,7 +161,38 @@ export default class CronService {
     }
     // -- Lifecycle -------------------------------------------------------
     /**
-     * Start the service. Loads jobs from store (if any), arms timer.
+     * Start the service. Loads jobs from store (if any), arms timer. A no-op if
+     * already started.
+     *
+     * `initialJobs` crosses a serialization boundary — it is whatever the
+     * consumer's store handed back — so `Job[]` is a compile-time claim about
+     * runtime data. Three behaviours follow from that and are worth knowing
+     * before you call this, because all three are deliberate and two of them
+     * differ from a plain "load and arm":
+     *
+     * 1. WRITES TO `row.state`. A STALE claim (`state.runningAtMs` set by a
+     *    process that is gone) is released, because nothing else ever will —
+     *    there is no lease on the field (#35) — and left in place it is a job
+     *    that is dead forever while `status()` reports it healthy. A LIVE claim,
+     *    held by an invocation still running in this process, is left alone:
+     *    releasing it would let the timer start a second concurrent invocation of
+     *    a job that is already running.
+     *
+     * 2. THROWS on a row this class cannot use, rather than accepting it. A row
+     *    whose `state` is missing, or frozen (`structuredClone` + `Object.freeze`
+     *    is an ordinary defensive rehydration), throws out of `start()` where the
+     *    caller's own `await` can catch it. The alternative is a `TypeError` from
+     *    inside a bare timer callback later — an unhandled rejection, and
+     *    process-fatal under Node's default.
+     *
+     * 3. ARMS THE TIMER EVEN IF IT THROWS. The rows loaded before the throw are
+     *    registered and scheduled. Without this, a throw leaves `started: true`
+     *    (so a retry is a no-op) with jobs in the heap and no timer: nothing ever
+     *    fires and `status()` still reports healthy.
+     *
+     * Hand it deserialized rows and all three are invisible. Hand it live `Job`
+     * objects this service is currently executing and only 1 is observable, by
+     * design.
      */
     async start(initialJobs) {
         if (this.started)
@@ -121,15 +212,15 @@ export default class CronService {
         try {
             if (initialJobs) {
                 for (const job of initialJobs) {
-                    // A `runningAtMs` on a rehydrated job is always stale. The claim it
-                    // records was taken by a process that is gone, so nothing will ever
-                    // settle it, and nothing reaps it — there is no lease on the field
-                    // (tracked on #35). Left in place it is a permanently dead job that
-                    // still reports healthy: `isDue` returns false forever because of the
-                    // flag, `run()` answers `'already running'` forever, `update()` never
-                    // touches `state.runningAtMs`, and `status()` counts it like any other.
-                    // The consumer's only recovery would be remove() + add(), losing the
-                    // job id and its run history.
+                    // A STALE `runningAtMs` records a claim taken by a process that is
+                    // gone. Nothing will ever settle it, and nothing reaps it — there is
+                    // no lease on the field (tracked on #35). Left in place it is a
+                    // permanently dead job that still reports healthy: `isDue` returns
+                    // false forever because of the flag, `run()` answers
+                    // `'already running'` forever, `update()` never touches
+                    // `state.runningAtMs`, and `status()` counts it like any other. The
+                    // consumer's only recovery would be remove() + add(), losing the job
+                    // id and its run history.
                     //
                     // Same hazard, same treatment as the hand-release on the `'removed'`
                     // path in `#executeClaimed`: a claim with no reachable settle must be
@@ -138,19 +229,36 @@ export default class CronService {
                     // run, so it gets no run-log row, no `lastStatus`, and no recomputed
                     // `nextRunAtMs`; it is rescheduled from the store's own value below.
                     //
-                    // Written unconditionally, and deliberately NOT guarded on a
-                    // `job.state.runningAtMs` read. Guarding it makes `start()` accept a
-                    // row whose `state` is frozen — `structuredClone` + `Object.freeze`
-                    // is an ordinary defensive rehydration — and that row is not usable
-                    // by this class at all: `markRunning` writes the same field on every
-                    // execution. Measured, the guard moves the failure from a throw out
-                    // of `start()`, which the consumer's own `await` can catch, to a
+                    // But NOT every `runningAtMs` here is stale, and the field cannot
+                    // tell you which — it is a number either way. `start()` early-returns
+                    // when `started`, so reaching this with a LIVE claim needs `stop()`
+                    // then `start(sameObjects)` (an in-process restart against a store
+                    // that hands back references rather than fresh rows) or a second
+                    // `CronService` handed live rows. Measured on the unconditional
+                    // version: the release cleared a live claim, the timer then found the
+                    // job due, and one job got TWO concurrent in-flight callbacks. That
+                    // is the single invariant this class advertises and that #34/#35
+                    // exist to protect, so the release is guarded on `inFlight` —
+                    // authoritative object identity, not a heuristic on the timestamp.
+                    // See `inFlight`'s docblock for why identity is also what keeps the
+                    // stale case working after a real crash.
+                    //
+                    // The guard is deliberately NOT a `job.state.runningAtMs` read.
+                    // Guarding on THAT makes `start()` accept a row whose `state` is
+                    // frozen — `structuredClone` + `Object.freeze` is an ordinary
+                    // defensive rehydration — and that row is not usable by this class at
+                    // all: `markRunning` writes the same field on every execution.
+                    // Measured, that guard moves the failure from a throw out of
+                    // `start()`, which the consumer's own `await` can catch, to a
                     // TypeError raised inside `onTimer`'s batch claim — a bare timer
                     // callback, so it surfaces as an unhandled rejection and is
-                    // process-fatal under Node's default. Failing loudly at the store
-                    // boundary is the better of the two, and the `finally` above keeps
-                    // the rows that loaded before it scheduled.
-                    job.state.runningAtMs = undefined;
+                    // process-fatal under Node's default. `inFlight` does not have that
+                    // problem: a deserialized row is never a member, so the write still
+                    // happens and the frozen row still fails loudly at the boundary. Both
+                    // properties are tested; do not collapse the two guards into one.
+                    if (!inFlight.has(job)) {
+                        job.state.runningAtMs = undefined;
+                    }
                     this.jobs.set(job.id, job);
                     if (job.enabled && job.state.nextRunAtMs) {
                         this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
@@ -343,6 +451,7 @@ export default class CronService {
                 const due = this.findDueJobs(nowMs);
                 for (const job of due) {
                     markRunning(job);
+                    inFlight.add(job);
                 }
                 return due;
             });
@@ -470,6 +579,7 @@ export default class CronService {
         // recomputed `nextRunAtMs` — the job did not run.
         if (this.jobs.get(job.id) !== job) {
             job.state.runningAtMs = undefined;
+            inFlight.delete(job);
             return { status: 'skipped', reason: 'removed' };
         }
         const startMs = Date.now();
@@ -533,6 +643,7 @@ export default class CronService {
         if (job.state.runningAtMs)
             return 'already running';
         markRunning(job);
+        inFlight.add(job);
         this.removeFromHeap(job.id);
         return null;
     }
@@ -589,6 +700,12 @@ export default class CronService {
             return { status, error, summary, durationMs };
         }
         finally {
+            // The invocation is over, so this job is no longer in flight in this
+            // process — whatever `applyResult` did or did not manage to write. In the
+            // `finally` so it covers a throw out of `applyResult` or `runLog.record`
+            // too: past this point no settle is coming, which is precisely the state
+            // `start()`'s release is for.
+            inFlight.delete(job);
             // One re-arm covering every exit, rather than one per branch. The claim
             // detached this job from the heap, so a timer that fired during the
             // unlocked invoke would have found nothing to arm — and `run()` has no

package/package.json

@@ -3,7 +3,7 @@
   "keywords": [
     "stonyx-module"
   ],
-  "version": "0.2.1-alpha.60",
+  "version": "0.2.1-alpha.61",
   "description": "Cron/job scheduler for Stonyx framework",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",