@zintrust/core 3.5.1 → 3.5.2

package/src/scheduler/ScheduleRunner.js

@@ -0,0 +1,342 @@
+/**
+ * ScheduleRunner
+ * Lightweight, zero-dependency schedule runner for long-running runtimes
+ */
+import { Logger } from '../config/logger.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { Cron } from './cron/Cron.js';
+import { InMemoryScheduleStateStore, } from './state/ScheduleStateStore.js';
+const nowMs = () => Date.now();
+const randomInt = (min, maxInclusive) => {
+    if (!Number.isFinite(min) || !Number.isFinite(maxInclusive))
+        return 0;
+    if (maxInclusive <= min)
+        return Math.floor(min);
+    return Math.floor(min + Math.random() * (maxInclusive - min + 1)); //NOSONAR
+};
+const resolveBackoffDelayMs = (state) => {
+    const policy = state.schedule.backoff;
+    if (!policy)
+        return 0;
+    const initialMs = Number.isFinite(policy.initialMs)
+        ? Math.max(0, Math.floor(policy.initialMs))
+        : 0;
+    const maxMs = Number.isFinite(policy.maxMs) ? Math.max(0, Math.floor(policy.maxMs)) : 0;
+    if (initialMs <= 0 || maxMs <= 0)
+        return 0;
+    const factor = policy.factor === undefined || !Number.isFinite(policy.factor) || policy.factor <= 1
+        ? 2
+        : policy.factor;
+    const power = Math.max(0, state.consecutiveFailures - 1);
+    const raw = initialMs * Math.pow(factor, power);
+    return Math.min(maxMs, Math.floor(raw));
+};
+const resolveJitterMs = (jitterMs) => {
+    return typeof jitterMs === 'number' && jitterMs > 0 ? randomInt(0, Math.floor(jitterMs)) : 0;
+};
+const computeBackoffDelay = (state) => {
+    if (state.schedule.enabled === false)
+        return null;
+    const backoffDelayMs = resolveBackoffDelayMs(state);
+    if (backoffDelayMs > 0) {
+        const jitter = resolveJitterMs(state.schedule.jitterMs);
+        return backoffDelayMs + jitter;
+    }
+    return null;
+};
+const computeCronDelay = (schedule) => {
+    if (typeof schedule.cron !== 'string' || schedule.cron.trim().length === 0) {
+        return null;
+    }
+    const tz = typeof schedule.timezone === 'string' && schedule.timezone.trim().length > 0
+        ? schedule.timezone
+        : undefined;
+    const nextAt = Cron.nextRunAtMs(nowMs(), schedule.cron, tz);
+    const baseDelay = Math.max(0, nextAt - nowMs());
+    const jitter = resolveJitterMs(schedule.jitterMs);
+    return baseDelay + jitter;
+};
+const computeIntervalDelay = (schedule) => {
+    if (typeof schedule.intervalMs !== 'number' || schedule.intervalMs <= 0) {
+        return null;
+    }
+    const base = Math.floor(schedule.intervalMs);
+    const jitter = resolveJitterMs(schedule.jitterMs);
+    return base + jitter;
+};
+const computeNextDelayMs = (state, outcome) => {
+    const schedule = state.schedule;
+    if (schedule.enabled === false)
+        return null;
+    if (outcome === 'failure') {
+        const backoffDelay = computeBackoffDelay(state);
+        if (backoffDelay !== null)
+            return backoffDelay;
+    }
+    const cronDelay = computeCronDelay(schedule);
+    if (cronDelay !== null)
+        return cronDelay;
+    const intervalDelay = computeIntervalDelay(schedule);
+    if (intervalDelay !== null)
+        return intervalDelay;
+    return null;
+};
+const clearTimer = (state) => {
+    if (state.timeoutId !== undefined) {
+        globalThis.clearTimeout(state.timeoutId);
+        state.timeoutId = undefined;
+    }
+};
+const scheduleNext = (state, kernel, invoke, outcome, store) => {
+    clearTimer(state);
+    const delay = computeNextDelayMs(state, outcome);
+    if (delay === null)
+        return;
+    const nextRunAt = nowMs() + delay;
+    void store.set(state.schedule.name, {
+        nextRunAt,
+        consecutiveFailures: state.consecutiveFailures,
+    });
+    state.timeoutId = globalThis.setTimeout(() => {
+        void runOnceAndReschedule(state, kernel, invoke, store);
+    }, delay);
+};
+const runOnceAndReschedule = async (state, kernel, invoke, store) => {
+    const outcome = await invoke(state, kernel);
+    scheduleNext(state, kernel, invoke, outcome, store);
+};
+const createRegister = (runner, invokeHandler) => (schedule) => {
+    const existing = runner.schedules.get(schedule.name);
+    if (existing !== undefined) {
+        Logger.warn(`Schedule replaced: ${schedule.name}`);
+        // Reuse the same internal state to avoid leaving old timers/reschedule loops behind.
+        existing.schedule = schedule;
+        // If disabled, ensure any pending timer is cleared.
+        if (schedule.enabled === false) {
+            clearTimer(existing);
+            return;
+        }
+        // If a run is currently in progress, let it finish and reschedule naturally.
+        if (existing.isRunning) {
+            return;
+        }
+        // If schedules are already started, apply the new schedule immediately.
+        if (runner.started) {
+            if (schedule.runOnStart === true) {
+                void runOnceAndReschedule(existing, runner.kernel, invokeHandler, runner.store);
+                return;
+            }
+            scheduleNext(existing, runner.kernel, invokeHandler, 'success', runner.store);
+        }
+        return;
+    }
+    const state = {
+        schedule,
+        isRunning: false,
+        consecutiveFailures: 0,
+    };
+    runner.schedules.set(schedule.name, state);
+    // If schedules are already started, register should take effect immediately.
+    if (runner.started && schedule.enabled !== false) {
+        if (schedule.runOnStart === true) {
+            void runOnceAndReschedule(state, runner.kernel, invokeHandler, runner.store);
+            return;
+        }
+        // Auto scheduling
+        scheduleNext(state, runner.kernel, invokeHandler, 'success', runner.store);
+    }
+};
+const createInvokeHandler = (runner) => async (state, kernel) => {
+    const store = runner.store;
+    if (state.isRunning) {
+        Logger.info(`Skipping overlapping run for schedule: ${state.schedule.name}`);
+        return 'failure';
+    }
+    state.isRunning = true;
+    try {
+        const handlerPromise = Promise.resolve()
+            .then(async () => state.schedule.handler(kernel))
+            .then(() => {
+            state.lastRunAt = nowMs();
+            state.consecutiveFailures = 0;
+            void store.set(state.schedule.name, {
+                lastRunAt: state.lastRunAt,
+                lastSuccessAt: state.lastRunAt,
+                lastErrorAt: undefined,
+                lastErrorMessage: undefined,
+                consecutiveFailures: state.consecutiveFailures,
+            });
+            return 'success';
+        })
+            .catch((error) => {
+            state.consecutiveFailures = Math.min(1_000_000, state.consecutiveFailures + 1);
+            const errMsg = error instanceof Error ? error.message : String(error);
+            const at = nowMs();
+            void store.set(state.schedule.name, {
+                lastRunAt: at,
+                lastErrorAt: at,
+                lastErrorMessage: errMsg,
+                consecutiveFailures: state.consecutiveFailures,
+            });
+            Logger.error(`Schedule '${state.schedule.name}' failed:`, error);
+            return 'failure';
+        });
+        state.runningPromise = handlerPromise.then(() => undefined);
+        return await handlerPromise;
+    }
+    finally {
+        state.isRunning = false;
+        state.runningPromise = undefined;
+    }
+};
+const createStart = (runner, invokeHandler) => (kernel) => {
+    if (runner.started)
+        return;
+    runner.started = true;
+    runner.kernel = kernel;
+    for (const [, state] of runner.schedules) {
+        const { schedule } = state;
+        if (schedule.enabled === false)
+            continue;
+        if (schedule.runOnStart === true) {
+            // fire-and-forget; next scheduling happens after the handler completes
+            void runOnceAndReschedule(state, kernel, invokeHandler, runner.store);
+            continue;
+        }
+        // Auto scheduling
+        scheduleNext(state, kernel, invokeHandler, 'success', runner.store);
+    }
+};
+const createStop = (runner) => async () => {
+    if (!runner.started)
+        return;
+    runner.started = false;
+    runner.kernel = undefined;
+    // Clear timers
+    for (const [, state] of runner.schedules) {
+        clearTimer(state);
+    }
+    // Await running handlers (runningPromise is guaranteed not to reject)
+    const running = [];
+    for (const [, state] of runner.schedules) {
+        if (state.isRunning && state.runningPromise !== undefined) {
+            running.push(state.runningPromise);
+        }
+    }
+    if (running.length > 0) {
+        await Promise.all(running);
+    }
+};
+const withTimeout = async (promise, timeoutMs) => {
+    const ms = typeof timeoutMs === 'number' ? timeoutMs : 0;
+    if (ms <= 0) {
+        await promise;
+        return;
+    }
+    let timeoutId;
+    try {
+        await Promise.race([
+            promise,
+            new Promise((resolve) => {
+                timeoutId = globalThis.setTimeout(() => {
+                    Logger.error('ScheduleRunner.stop() timed out; continuing shutdown', {
+                        timeoutMs: ms,
+                    });
+                    resolve();
+                }, ms);
+            }),
+        ]);
+    }
+    finally {
+        if (timeoutId !== undefined)
+            globalThis.clearTimeout(timeoutId);
+    }
+};
+const createStopWithTimeout = (stop) => async (timeoutMs) => {
+    await withTimeout(stop(), timeoutMs);
+};
+const createList = (runner) => () => Array.from(runner.schedules.values()).map((s) => s.schedule);
+const createRunOnce = (runner, invokeHandler) => async (name, kernel) => {
+    const state = runner.schedules.get(name);
+    if (state === undefined)
+        throw ErrorFactory.createNotFoundError(`Schedule not found: ${name}`);
+    if (state.schedule.enabled === false)
+        return;
+    await invokeHandler(state, kernel ?? runner.kernel);
+};
+/**
+ * Computes the epoch-ms timestamp at which a schedule next becomes due,
+ * measured from its last successful run. Cron takes precedence over interval.
+ * Returns `null` when the schedule has neither a cron nor a positive interval
+ * (i.e. it has no cadence of its own and is always considered due).
+ */
+const computeDueAtMs = (schedule, lastRunAt) => {
+    if (typeof schedule.cron === 'string' && schedule.cron.trim().length > 0) {
+        const tz = typeof schedule.timezone === 'string' && schedule.timezone.trim().length > 0
+            ? schedule.timezone
+            : undefined;
+        return Cron.nextRunAtMs(lastRunAt, schedule.cron, tz);
+    }
+    if (typeof schedule.intervalMs === 'number' && schedule.intervalMs > 0) {
+        return lastRunAt + Math.floor(schedule.intervalMs);
+    }
+    return null;
+};
+const createRunIfDue = (runner, invokeHandler) => async (name, kernel) => {
+    const state = runner.schedules.get(name);
+    if (state === undefined)
+        throw ErrorFactory.createNotFoundError(`Schedule not found: ${name}`);
+    if (state.schedule.enabled === false)
+        return { ran: false, reason: 'disabled' };
+    // Prefer the durable, persisted last-run time over the in-memory mirror so
+    // this works across stateless invocations (e.g. Cloudflare Worker cron ticks)
+    // when a persistent store has been wired via setStore().
+    const persisted = await runner.store.get(name);
+    const lastRunAt = persisted?.lastSuccessAt ?? persisted?.lastRunAt ?? state.lastRunAt ?? undefined;
+    if (typeof lastRunAt === 'number') {
+        const dueAt = computeDueAtMs(state.schedule, lastRunAt);
+        if (dueAt === null) {
+            // No cadence configured: nothing to gate on, run it.
+            const outcome = await invokeHandler(state, kernel ?? runner.kernel);
+            return { ran: true, outcome, reason: 'no-cadence' };
+        }
+        if (nowMs() < dueAt) {
+            return { ran: false, reason: 'not-due', nextRunAt: dueAt };
+        }
+    }
+    const outcome = await invokeHandler(state, kernel ?? runner.kernel);
+    return { ran: true, outcome };
+};
+export const create = (store) => {
+    const runner = {
+        schedules: new Map(),
+        started: false,
+        kernel: undefined,
+        store: store ?? InMemoryScheduleStateStore.create(),
+    };
+    const invokeHandler = createInvokeHandler(runner);
+    const register = createRegister(runner, invokeHandler);
+    const start = createStart(runner, invokeHandler);
+    const stopRaw = createStop(runner);
+    const stop = createStopWithTimeout(stopRaw);
+    const list = createList(runner);
+    const runOnce = createRunOnce(runner, invokeHandler);
+    const runIfDue = createRunIfDue(runner, invokeHandler);
+    const getState = async (name) => runner.store.get(name);
+    const listStates = async () => runner.store.list();
+    const setStore = (next) => {
+        runner.store = next;
+    };
+    return Object.freeze({
+        register,
+        start,
+        stop,
+        list,
+        runOnce,
+        runIfDue,
+        getState,
+        listStates,
+        setStore,
+    });
+};
+export default { create };

package/src/scheduler/SchedulerRuntime.d.ts

@@ -0,0 +1,30 @@
+import type { RunIfDueResult } from './ScheduleRunner.js';
+import type { IScheduleStateStore, ScheduleRunState } from './state/ScheduleStateStore.js';
+import type { ISchedule, IScheduleKernel } from './types.js';
+export declare const SchedulerRuntime: Readonly<{
+    registerMany: (schedules: ReadonlyArray<ISchedule>, source?: "core" | "app") => void;
+    start(kernel?: IScheduleKernel): void;
+    stop(timeoutMs?: number): Promise<void>;
+    list(): ISchedule[];
+    listWithState(): Promise<Array<{
+        schedule: ISchedule;
+        state: ScheduleRunState | null;
+    }>>;
+    runOnce(name: string, kernel?: IScheduleKernel): Promise<void>;
+    /**
+     * Runs a schedule only if it is due, based on its persisted last-run time and
+     * its configured cron/interval cadence. Intended for stateless cron triggers
+     * (e.g. a Cloudflare Worker `scheduled` handler) where the timer-based
+     * `start()` loop cannot run. For the due check to survive cold starts, wire a
+     * persistent state store via {@link useStateStore} first.
+     */
+    runIfDue(name: string, kernel?: IScheduleKernel): Promise<RunIfDueResult>;
+    /**
+     * Swaps the schedule state store (default is in-memory). Provide a durable
+     * implementation (Redis/KV/D1-backed) so `runIfDue` can read `lastRunAt`
+     * across stateless invocations. Call this before `registerMany`/`runIfDue`.
+     */
+    useStateStore(store: IScheduleStateStore): void;
+}>;
+export default SchedulerRuntime;
+//# sourceMappingURL=SchedulerRuntime.d.ts.map

package/src/scheduler/SchedulerRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SchedulerRuntime.d.ts","sourceRoot":"","sources":["../../../src/scheduler/SchedulerRuntime.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AACjG,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAgEnE,eAAO,MAAM,gBAAgB;8BAzBhB,aAAa,CAAC,SAAS,CAAC,WAC3B,MAAM,GAAG,KAAK,KACrB,IAAI;mBAyBU,eAAe,GAAG,IAAI;qBAqBd,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAOrC,SAAS,EAAE;qBAGI,OAAO,CAAC,KAAK,CAAC;QAAE,QAAQ,EAAE,SAAS,CAAC;QAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;kBAkB1E,MAAM,WAAW,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAGpE;;;;;;OAMG;mBACkB,MAAM,WAAW,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAG/E;;;;OAIG;yBACkB,mBAAmB,GAAG,IAAI;EAGjB,CAAC;AAEjC,eAAe,gBAAgB,CAAC"}

package/src/scheduler/SchedulerRuntime.js

@@ -0,0 +1,97 @@
+import { Logger } from '../config/logger.js';
+import { createScheduleRunner } from './index.js';
+import { SchedulerLeader } from './leader/SchedulerLeader.js';
+const state = {
+    runner: createScheduleRunner(),
+    registered: new Map(),
+    leader: SchedulerLeader.create(),
+    leaderStarted: false,
+};
+const registerMany = (schedules, source = 'core') => {
+    for (const schedule of schedules) {
+        if (schedule === undefined || schedule === null || typeof schedule.name !== 'string')
+            continue;
+        const name = schedule.name.trim();
+        if (name.length === 0)
+            continue;
+        const existing = state.registered.get(name);
+        // If app already registered, it always wins.
+        if (existing === 'app')
+            continue;
+        // Prevent repeated registrations from the same source.
+        if (existing === source)
+            continue;
+        if (existing === 'core' && source === 'app') {
+            Logger.info('Schedule overridden by app/Schedules', { name });
+        }
+        state.registered.set(name, source);
+        state.runner.register(schedule);
+    }
+};
+export const SchedulerRuntime = Object.freeze({
+    registerMany,
+    start(kernel) {
+        // If leader mode is enabled, only the leader instance starts timers.
+        if (state.leader.isEnabled()) {
+            if (state.leaderStarted)
+                return;
+            state.leaderStarted = true;
+            state.leader.start({
+                onBecameLeader: () => {
+                    state.runner.start(kernel);
+                },
+                onLostLeadership: () => {
+                    // Best-effort stop; leadership transitions should not crash the process.
+                    void state.runner.stop();
+                },
+            });
+            return;
+        }
+        state.runner.start(kernel);
+    },
+    async stop(timeoutMs) {
+        if (state.leaderStarted) {
+            state.leaderStarted = false;
+            await state.leader.stop();
+        }
+        await state.runner.stop(timeoutMs);
+    },
+    list() {
+        return state.runner.list();
+    },
+    async listWithState() {
+        const schedules = state.runner.list();
+        const getState = state.runner
+            .getState;
+        if (typeof getState !== 'function') {
+            return schedules.map((schedule) => ({ schedule, state: null }));
+        }
+        const rows = await Promise.all(schedules.map(async (schedule) => {
+            const stateRow = (await getState(schedule.name));
+            return { schedule, state: stateRow };
+        }));
+        return rows;
+    },
+    async runOnce(name, kernel) {
+        await state.runner.runOnce(name, kernel);
+    },
+    /**
+     * Runs a schedule only if it is due, based on its persisted last-run time and
+     * its configured cron/interval cadence. Intended for stateless cron triggers
+     * (e.g. a Cloudflare Worker `scheduled` handler) where the timer-based
+     * `start()` loop cannot run. For the due check to survive cold starts, wire a
+     * persistent state store via {@link useStateStore} first.
+     */
+    async runIfDue(name, kernel) {
+        return state.runner.runIfDue(name, kernel);
+    },
+    /**
+     * Swaps the schedule state store (default is in-memory). Provide a durable
+     * implementation (Redis/KV/D1-backed) so `runIfDue` can read `lastRunAt`
+     * across stateless invocations. Call this before `registerMany`/`runIfDue`.
+     */
+    useStateStore(store) {
+        state.runner.setStore(store);
+    },
+});
+export default SchedulerRuntime;

package/src/scheduler/cron/Cron.d.ts

@@ -0,0 +1,19 @@
+type CronAllowed = Readonly<{
+    any: true;
+}> | Readonly<{
+    any: false;
+    values: ReadonlySet<number>;
+}>;
+export type CronSpec = Readonly<{
+    minute: CronAllowed;
+    hour: CronAllowed;
+    dayOfMonth: CronAllowed;
+    month: CronAllowed;
+    dayOfWeek: CronAllowed;
+}>;
+export declare const Cron: Readonly<{
+    parse(expr: string): CronSpec;
+    nextRunAtMs(nowMs: number, expr: string, timeZone?: string): number;
+}>;
+export default Cron;
+//# sourceMappingURL=Cron.d.ts.map

package/src/scheduler/cron/Cron.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cron.d.ts","sourceRoot":"","sources":["../../../../src/scheduler/cron/Cron.ts"],"names":[],"mappings":"AAIA,KAAK,WAAW,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,IAAI,CAAA;CAAE,CAAC,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC,CAAC;AAEnG,MAAM,MAAM,QAAQ,GAAG,QAAQ,CAAC;IAC9B,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,EAAE,WAAW,CAAC;IACxB,KAAK,EAAE,WAAW,CAAC;IACnB,SAAS,EAAE,WAAW,CAAC;CACxB,CAAC,CAAC;AA0LH,eAAO,MAAM,IAAI;gBACH,MAAM,GAAG,QAAQ;uBA+BV,MAAM,QAAQ,MAAM,aAAa,MAAM,GAAG,MAAM;EAwBnE,CAAC;AAEH,eAAe,IAAI,CAAC"}