velocious 1.0.377 → 1.0.378

package/README.md

@@ -1789,7 +1789,8 @@ export default new Configuration({
     host: "127.0.0.1",
     port: 7331,
     databaseIdentifier: "default",
-    maxConcurrentInlineJobs: 4
+    maxConcurrentInlineJobs: 4,
+    dispatchStrategy: "beacon"
   }
 })
 ```
@@ -1801,10 +1802,21 @@ VELOCIOUS_BACKGROUND_JOBS_HOST=127.0.0.1
 VELOCIOUS_BACKGROUND_JOBS_PORT=7331
 VELOCIOUS_BACKGROUND_JOBS_DATABASE_IDENTIFIER=default
 VELOCIOUS_BACKGROUND_JOBS_MAX_CONCURRENT_INLINE_JOBS=4
+VELOCIOUS_BACKGROUND_JOBS_DISPATCH_STRATEGY=beacon
+VELOCIOUS_BACKGROUND_JOBS_POLL_INTERVAL_MS=1000
 ```
 
 `maxConcurrentInlineJobs` (default: `4`) caps how many `forked: false` jobs a single `background-jobs-worker` process runs in parallel. Concurrency is at the JS event-loop level: every job in flight shares the worker's process and DB connection pool, so the cap should fit the pool, not the CPU count. Forking remains the right tool when you need memory isolation across long-running jobs or want to use more cores.
 
+### Dispatch strategy
+
+`dispatchStrategy` controls how `background-jobs-main` detects new work.
+
+- `"beacon"` (default): event-driven dispatch. `background-jobs-main` drains the queue when a job is enqueued (directly, or via a [Beacon](docs/beacon.md) broadcast from another process), when a worker comes up or reports ready, and at the exact `scheduled_at_ms` of the next future-scheduled job via a precise `setTimeout`. There is no fixed-interval polling. The `background_jobs` table is the durable log — on (re)connect to Beacon, the dispatcher does a one-shot catch-up drain so anything enqueued while the bus was unreachable is picked up.
+- `"polling"`: legacy fixed-interval poll. `background-jobs-main` runs `SELECT … FROM background_jobs WHERE status='queued' AND scheduled_at_ms <= now` every `pollIntervalMs` (default `1000`). Use this if you want the previous behavior, or for environments where Beacon is unavailable and you don't want event-driven dispatch.
+
+Beacon is opt-in for the rest of the framework, but the dispatcher uses event-driven dispatch even when Beacon is not configured — it falls back to direct in-process triggering from the enqueue/handoff paths plus `setTimeout` for scheduled jobs. Configure Beacon when you want cross-process enqueues (e.g. enqueue from an HTTP server process) to wake the main process immediately.
+
 ## Defining jobs
 
 ```js

package/build/src/background-jobs/main.d.ts

@@ -13,6 +13,8 @@ export default class BackgroundJobsMain {
     configuration: import("../configuration.js").default;
     host: string;
     port: number;
+    dispatchStrategy: import("../configuration-types.js").BackgroundJobsDispatchStrategy;
+    pollIntervalMs: number;
     store: BackgroundJobsStore;
     logger: Logger;
     /** @type {Set<JsonSocket>} */
@@ -22,12 +24,24 @@ export default class BackgroundJobsMain {
     /** @type {net.Server | undefined} */
     server: net.Server | undefined;
     /** @type {NodeJS.Timeout | undefined} */
-    _dispatchTimer: NodeJS.Timeout | undefined;
+    _pollTimer: NodeJS.Timeout | undefined;
+    /** @type {NodeJS.Timeout | undefined} */
+    _scheduledTimer: NodeJS.Timeout | undefined;
+    /** @type {NodeJS.Timeout | undefined} */
+    _errorRetryTimer: NodeJS.Timeout | undefined;
     /** @type {NodeJS.Timeout | undefined} */
     _orphanTimer: NodeJS.Timeout | undefined;
     /** @type {BackgroundJobsScheduler | undefined} */
     scheduler: BackgroundJobsScheduler | undefined;
-    _dispatching: boolean;
+    _draining: boolean;
+    _redrainQueued: boolean;
+    _stopped: boolean;
+    /** @type {(() => void) | undefined} */
+    _unsubscribeBeacon: (() => void) | undefined;
+    /** @type {((...args: any[]) => void) | undefined} */
+    _beaconConnectHandler: ((...args: any[]) => void) | undefined;
+    /** @type {import("../beacon/client.js").default | import("../beacon/in-process-client.js").default | undefined} */
+    _beaconClient: import("../beacon/client.js").default | import("../beacon/in-process-client.js").default | undefined;
     /**
      * @returns {Promise<void>} - Resolves when listening.
      */
@@ -40,6 +54,26 @@ export default class BackgroundJobsMain {
      * @returns {number} - Bound port.
      */
     getPort(): number;
+    /**
+     * Wires up the dispatch-triggering signal sources for the configured
+     * strategy. In `"beacon"` mode (default) this means subscribing to the
+     * `velocious-background-jobs-dispatch` channel for cross-process
+     * wake-ups, listening for Beacon (re)connects to catch up on missed
+     * work, and relying on direct in-process calls from `_handleEnqueue`,
+     * `_handleJobComplete`/`Failed`, worker hello/ready, and the
+     * scheduled-job `setTimeout`. In `"polling"` mode we restore the
+     * legacy fixed-interval poll for users who want the previous behavior.
+     * @returns {void}
+     */
+    _setupDispatchTriggers(): void;
+    /**
+     * Publishes a dispatch wake-up on the Beacon channel. No-op in polling
+     * mode or when Beacon is not connected; in those cases the direct
+     * in-process `_drain()` call in the enqueue/handle paths is sufficient
+     * (there are no other processes to notify).
+     * @returns {void}
+     */
+    _notifyEnqueued(): void;
     /**
      * @param {import("net").Socket} socket - Socket.
      * @returns {void}
@@ -75,7 +109,46 @@ export default class BackgroundJobsMain {
         jsonSocket: JsonSocket;
         message: import("./types.js").BackgroundJobFailedMessage;
     }): Promise<void>;
-    _dispatch(): Promise<void>;
+    /**
+     * Drains all dispatchable jobs to ready workers, then arms the
+     * scheduled-job timer for the next future `scheduled_at_ms`. Coalesces
+     * concurrent triggers: a wake-up that lands while a drain is in
+     * flight just sets a re-drain flag and lets the in-flight drain
+     * re-loop after it finishes, so no signal is dropped but no two
+     * drains run in parallel.
+     *
+     * Resilience: in beacon mode this is the sole wake-up path for
+     * already-queued work, so a transient DB error during the drain (e.g.
+     * `nextAvailableJob()` rejecting) must not strand the queue until the
+     * next external signal. On any error we log it and arm a one-shot
+     * retry via `_scheduleErrorRetry` using `pollIntervalMs` as the
+     * cadence; on success the retry timer is cleared. Polling-mode runs
+     * `_drain` from its own interval, so the retry timer is a no-op there.
+     * @returns {Promise<void>}
+     */
+    _drain(): Promise<void>;
+    /**
+     * Arms a one-shot `setTimeout` to retry `_drain` after a transient
+     * failure. Idempotent — repeated calls while a retry is already
+     * pending are no-ops. Polling mode already retries via its own
+     * interval, so this is a no-op in that mode.
+     * @returns {void}
+     */
+    _scheduleErrorRetry(): void;
+    /**
+     * Inner drain loop: pulls eligible queued jobs and hands them off to
+     * ready workers until one of them runs out.
+     * @returns {Promise<void>}
+     */
+    _drainOnce(): Promise<void>;
+    /**
+     * Arms a single `setTimeout` for the soonest future-scheduled job's
+     * `scheduled_at_ms`. Replaces the second responsibility of the legacy
+     * 1-second poll (becoming-eligible scheduled jobs). The timer is
+     * idempotently re-armed at the end of every drain.
+     * @returns {Promise<void>}
+     */
+    _armScheduledTimer(): Promise<void>;
     _sweepOrphans(): Promise<void>;
 }
 import BackgroundJobsStore from "./store.js";

package/build/src/background-jobs/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/background-jobs/main.js"],"names":[],"mappings":"AAQA;IACE;;;;;OAKG;IACH,2CAJG;QAAoD,aAAa,EAAzD,OAAO,qBAAqB,EAAE,OAAO;QACvB,IAAI;QACJ,IAAI;KAC5B,EAqBA;IAnBC,qDAAkC;IAElC,aAA+B;IAC/B,aAAyD;IACzD,2BAAoG;IACpG,eAA8B;IAC9B,8BAA8B;IAC9B,SADW,GAAG,CAAC,UAAU,CAAC,CACF;IACxB,8BAA8B;IAC9B,cADW,GAAG,CAAC,UAAU,CAAC,CACG;IAC7B,qCAAqC;IACrC,QADW,GAAG,CAAC,MAAM,GAAG,SAAS,CACV;IACvB,yCAAyC;IACzC,gBADW,MAAM,CAAC,OAAO,GAAG,SAAS,CACN;IAC/B,yCAAyC;IACzC,cADW,MAAM,CAAC,OAAO,GAAG,SAAS,CACR;IAC7B,kDAAkD;IAClD,WADW,uBAAuB,GAAG,SAAS,CACpB;IAC1B,sBAAyB;IAG3B;;OAEG;IACH,SAFa,OAAO,CAAC,IAAI,CAAC,CA6CzB;IAED;;OAEG;IACH,QAFa,OAAO,CAAC,IAAI,CAAC,CAiBzB;IAED;;OAEG;IACH,WAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,0BAHW,OAAO,KAAK,EAAE,MAAM,GAClB,IAAI,CA+DhB;IAED;;;;;OAKG;IACH,wCAJG;QAAyB,UAAU,EAA3B,UAAU;QAC6C,OAAO,EAA9D,OAAO,YAAY,EAAE,2BAA2B;KACxD,GAAU,OAAO,CAAC,IAAI,CAAC,CAgBzB;IAED;;;;;OAKG;IACH,4CAJG;QAAyB,UAAU,EAA3B,UAAU;QAC8C,OAAO,EAA/D,OAAO,YAAY,EAAE,4BAA4B;KACzD,GAAU,OAAO,CAAC,IAAI,CAAC,CAczB;IAED;;;;;OAKG;IACH,0CAJG;QAAyB,UAAU,EAA3B,UAAU;QAC4C,OAAO,EAA7D,OAAO,YAAY,EAAE,0BAA0B;KACvD,GAAU,OAAO,CAAC,IAAI,CAAC,CAgBzB;IAED,2BAyCC;IAED,+BAUC;CACF;gCApS+B,YAAY;mBACzB,cAAc;uBAHV,kBAAkB;gBADzB,KAAK;oCAEe,gBAAgB"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/background-jobs/main.js"],"names":[],"mappings":"AAwBA;IACE;;;;;OAKG;IACH,2CAJG;QAAoD,aAAa,EAAzD,OAAO,qBAAqB,EAAE,OAAO;QACvB,IAAI;QACJ,IAAI;KAC5B,EAmCA;IAjCC,qDAAkC;IAElC,aAA+B;IAC/B,aAAyD;IACzD,qFAA+C;IAC/C,uBAA2C;IAC3C,2BAAoG;IACpG,eAA8B;IAC9B,8BAA8B;IAC9B,SADW,GAAG,CAAC,UAAU,CAAC,CACF;IACxB,8BAA8B;IAC9B,cADW,GAAG,CAAC,UAAU,CAAC,CACG;IAC7B,qCAAqC;IACrC,QADW,GAAG,CAAC,MAAM,GAAG,SAAS,CACV;IACvB,yCAAyC;IACzC,YADW,MAAM,CAAC,OAAO,GAAG,SAAS,CACV;IAC3B,yCAAyC;IACzC,iBADW,MAAM,CAAC,OAAO,GAAG,SAAS,CACL;IAChC,yCAAyC;IACzC,kBADW,MAAM,CAAC,OAAO,GAAG,SAAS,CACJ;IACjC,yCAAyC;IACzC,cADW,MAAM,CAAC,OAAO,GAAG,SAAS,CACR;IAC7B,kDAAkD;IAClD,WADW,uBAAuB,GAAG,SAAS,CACpB;IAC1B,mBAAsB;IACtB,wBAA2B;IAC3B,kBAAqB;IACrB,uCAAuC;IACvC,oBADW,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CACA;IACnC,qDAAqD;IACrD,uBADW,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC,GAAG,SAAS,CACX;IACtC,mHAAmH;IACnH,eADW,OAAO,qBAAqB,EAAE,OAAO,GAAG,OAAO,gCAAgC,EAAE,OAAO,GAAG,SAAS,CACjF;IAGhC;;OAEG;IACH,SAFa,OAAO,CAAC,IAAI,CAAC,CAoDzB;IAED;;OAEG;IACH,QAFa,OAAO,CAAC,IAAI,CAAC,CAqCzB;IAED;;OAEG;IACH,WAFa,MAAM,CAIlB;IAED;;;;;;;;;;OAUG;IACH,0BAFa,IAAI,CA2BhB;IAED;;;;;;OAMG;IACH,mBAFa,IAAI,CAiBhB;IAED;;;OAGG;IACH,0BAHW,OAAO,KAAK,EAAE,MAAM,GAClB,IAAI,CA+DhB;IAED;;;;;OAKG;IACH,wCAJG;QAAyB,UAAU,EAA3B,UAAU;QAC6C,OAAO,EAA9D,OAAO,YAAY,EAAE,2BAA2B;KACxD,GAAU,OAAO,CAAC,IAAI,CAAC,CAiBzB;IAED;;;;;OAKG;IACH,4CAJG;QAAyB,UAAU,EAA3B,UAAU;QAC8C,OAAO,EAA/D,OAAO,YAAY,EAAE,4BAA4B;KACzD,GAAU,OAAO,CAAC,IAAI,CAAC,CAczB;IAED;;;;;OAKG;IACH,0CAJG;QAAyB,UAAU,EAA3B,UAAU;QAC4C,OAAO,EAA7D,OAAO,YAAY,EAAE,0BAA0B;KACvD,GAAU,OAAO,CAAC,IAAI,CAAC,CAmBzB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,UAFa,OAAO,CAAC,IAAI,CAAC,CA+CzB;IAED;;;;;;OAMG;IACH,uBAFa,IAAI,CAWhB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAAC,IAAI,CAAC,CAkCzB;IAED;;;;;;OAMG;IACH,sBAFa,OAAO,CAAC,IAAI,CAAC,CAoBzB;IAED,+BAcC;CACF;gCA5gB+B,YAAY;mBACzB,cAAc;uBAHV,kBAAkB;gBADzB,KAAK;oCAEe,gBAAgB"}