@harperfast/harper 5.2.0-alpha.6 → 5.2.0-beta.2

package/dist/resources/scheduler/CronExpression.js

@@ -0,0 +1,367 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CronExpression = exports.InvalidCronExpressionError = void 0;
+exports.validateTimezone = validateTimezone;
+exports.getSystemTimezone = getSystemTimezone;
+exports.toZonedWallTime = toZonedWallTime;
+exports.fromZonedWallTime = fromZonedWallTime;
+const hdbError_ts_1 = require("../../utility/errors/hdbError.js");
+/**
+ * Thrown when a cron expression cannot be parsed, or a schedule can never fire
+ * (e.g. `0 0 30 2 *` — February 30th).
+ */
+class InvalidCronExpressionError extends hdbError_ts_1.ClientError {
+    constructor(message) {
+        super(message, 400);
+        this.name = 'InvalidCronExpressionError';
+    }
+}
+exports.InvalidCronExpressionError = InvalidCronExpressionError;
+const MONTH_NAMES = ['JAN', 'FEB', 'MAR', 'APR', 'MAY', 'JUN', 'JUL', 'AUG', 'SEP', 'OCT', 'NOV', 'DEC'];
+const DAY_OF_WEEK_NAMES = ['SUN', 'MON', 'TUE', 'WED', 'THU', 'FRI', 'SAT'];
+const MACROS = {
+    '@yearly': '0 0 1 1 *',
+    '@annually': '0 0 1 1 *',
+    '@monthly': '0 0 1 * *',
+    '@weekly': '0 0 * * 0',
+    '@daily': '0 0 * * *',
+    '@midnight': '0 0 * * *',
+    '@hourly': '0 * * * *',
+};
+// How far ahead/behind nextDate/prevDate will search before concluding the
+// schedule can never fire. Eight years covers leap-day schedules even across
+// a century non-leap year (2096 -> 2104 is the longest Feb 29 gap).
+const MAX_SEARCH_YEARS = 8;
+// DST transitions shift offsets by at most two hours in the IANA database
+const MAX_DST_DELTA_MS = 2 * 60 * 60 * 1000;
+const MINUTE_FIELD = { min: 0, max: 59 };
+const HOUR_FIELD = { min: 0, max: 23 };
+const DAY_OF_MONTH_FIELD = { min: 1, max: 31 };
+const MONTH_FIELD = { min: 1, max: 12, names: MONTH_NAMES, nameOffset: 1 };
+const DAY_OF_WEEK_FIELD = { min: 0, max: 7, names: DAY_OF_WEEK_NAMES, nameOffset: 0 };
+/**
+ * Parse one cron field (e.g. `1,15,30-45`, `MON-FRI`, or a step like `0-59/15`)
+ * into a boolean lookup keyed by value. Supports `*`, single values, ranges,
+ * steps, lists, and the standard month/day names.
+ */
+function parseField(fieldValue, spec, fieldName, expression) {
+    const allowed = new Array(spec.max + 1).fill(false);
+    const fail = (reason) => {
+        throw new InvalidCronExpressionError(`Invalid ${fieldName} field "${fieldValue}" in cron expression "${expression}": ${reason}`);
+    };
+    const parseValue = (raw) => {
+        if (spec.names) {
+            const nameIndex = spec.names.indexOf(raw.toUpperCase());
+            if (nameIndex >= 0)
+                return nameIndex + (spec.nameOffset ?? 0);
+        }
+        if (!/^\d+$/.test(raw))
+            fail(`"${raw}" is not a number${spec.names ? ' or recognized name' : ''}`);
+        const value = Number(raw);
+        if (value < spec.min || value > spec.max)
+            fail(`${value} is outside the allowed range ${spec.min}-${spec.max}`);
+        return value;
+    };
+    for (const part of fieldValue.split(',')) {
+        if (part === '')
+            fail('empty list entry');
+        const [base, stepText, extra] = part.split('/');
+        if (extra !== undefined)
+            fail('multiple "/" step separators');
+        let step = 1;
+        if (stepText !== undefined) {
+            if (!/^\d+$/.test(stepText) || Number(stepText) < 1)
+                fail(`step "${stepText}" must be a positive integer`);
+            step = Number(stepText);
+        }
+        let rangeStart;
+        let rangeEnd;
+        if (base === '*') {
+            rangeStart = spec.min;
+            rangeEnd = spec.max;
+        }
+        else if (base.includes('-')) {
+            const [startText, endText, extraRange] = base.split('-');
+            if (extraRange !== undefined || startText === '' || endText === '')
+                fail('malformed range');
+            rangeStart = parseValue(startText);
+            rangeEnd = parseValue(endText);
+            if (rangeStart > rangeEnd)
+                fail(`range start ${rangeStart} is greater than range end ${rangeEnd}`);
+        }
+        else {
+            rangeStart = parseValue(base);
+            // `5/15` means "every 15 starting at 5"; a bare `5` means just 5
+            rangeEnd = stepText !== undefined ? spec.max : rangeStart;
+        }
+        for (let value = rangeStart; value <= rangeEnd; value += step) {
+            allowed[value] = true;
+        }
+    }
+    return allowed;
+}
+// Cache one formatter per timezone: Intl.DateTimeFormat construction is
+// expensive relative to formatting, and the same few zones recur.
+const zoneFormatters = new Map();
+function getZoneFormatter(timezone) {
+    let formatter = zoneFormatters.get(timezone);
+    if (!formatter) {
+        formatter = new Intl.DateTimeFormat('en-US', {
+            timeZone: timezone,
+            year: 'numeric',
+            month: '2-digit',
+            day: '2-digit',
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+            hourCycle: 'h23',
+        });
+        zoneFormatters.set(timezone, formatter);
+    }
+    return formatter;
+}
+/**
+ * Validate an IANA timezone name. Returns the normalized name, or throws.
+ */
+function validateTimezone(timezone) {
+    try {
+        getZoneFormatter(timezone);
+        return timezone;
+    }
+    catch (error) {
+        zoneFormatters.delete(timezone);
+        throw new hdbError_ts_1.ClientError(`Unknown timezone "${timezone}": ${error.message}`, 400);
+    }
+}
+let systemTimezone;
+function getSystemTimezone() {
+    systemTimezone ??= Intl.DateTimeFormat().resolvedOptions().timeZone;
+    return systemTimezone;
+}
+/**
+ * Shift a real instant so its UTC fields carry the wall-clock time in the given
+ * timezone. The evaluator works entirely on these "zoned wall time" Dates
+ * (reading getUTC* fields), keeping the schedule math independent of the
+ * system timezone.
+ */
+function toZonedWallTime(date, timezone) {
+    const parts = {};
+    for (const part of getZoneFormatter(timezone).formatToParts(date)) {
+        parts[part.type] = part.value;
+    }
+    return new Date(Date.UTC(Number(parts.year), Number(parts.month) - 1, Number(parts.day), 
+    // hourCycle h23 should prevent "24", but guard anyway — some ICU
+    // versions have produced it for midnight
+    Number(parts.hour === '24' ? '0' : parts.hour), Number(parts.minute), Number(parts.second)));
+}
+/**
+ * Inverse of toZonedWallTime: given a Date whose UTC fields represent
+ * wall-clock time in `timezone`, return the real instant.
+ *
+ * Offsets are discovered by probing the zone at the wall time misread as UTC,
+ * at the candidate instant that offset implies, and two hours either side of
+ * it (DST deltas never exceed 2h), so both sides of a nearby transition are
+ * seen regardless of hemisphere or offset sign — a single re-probe missed the
+ * pre-transition offset in eastern zones (a Sydney gap job fired an hour
+ * EARLY; Lord Howe ambiguous times resolved to their second occurrence).
+ * Resolution is then deterministic in every zone: a wall time that exists
+ * maps to its instant; an ambiguous (fall-back overlap) wall time maps to its
+ * FIRST occurrence; a nonexistent (spring-forward gap) wall time maps to the
+ * first instant after the gap.
+ */
+function fromZonedWallTime(wallTime, timezone) {
+    const asUtc = wallTime.getTime();
+    const offsetAt = (instant) => toZonedWallTime(new Date(instant), timezone).getTime() - instant;
+    const firstOffset = offsetAt(asUtc);
+    const nearCandidate = asUtc - firstOffset;
+    const candidateOffsets = new Set([
+        firstOffset,
+        offsetAt(nearCandidate),
+        offsetAt(nearCandidate - MAX_DST_DELTA_MS),
+        offsetAt(nearCandidate + MAX_DST_DELTA_MS),
+    ]);
+    let earliestRoundTrip = Infinity;
+    let latestCandidate = -Infinity;
+    for (const offset of candidateOffsets) {
+        const instant = asUtc - offset;
+        latestCandidate = Math.max(latestCandidate, instant);
+        if (offsetAt(instant) === offset) {
+            earliestRoundTrip = Math.min(earliestRoundTrip, instant);
+        }
+    }
+    // No candidate reproduces this wall time: it falls in a spring-forward gap;
+    // the latest candidate is the first instant after the transition
+    return new Date(Number.isFinite(earliestRoundTrip) ? earliestRoundTrip : latestCandidate);
+}
+const MINUTE_MS = 60_000;
+// DST overlaps are at most ~2h (Lord Howe aside, offsets change by <=1h in
+// practice; 3h covers every IANA zone with margin), so occurrence convergence
+// through a fall-back never needs to look further than this past the reference
+const DST_CONVERGENCE_HORIZON_MS = 3 * 60 * 60 * 1000;
+// A minutely cron converging through a 2h overlap needs ~120 occurrences;
+// each iteration is cheap, so the cap is safety against pathologies only
+const MAX_CONVERGENCE_ATTEMPTS = 400;
+/**
+ * A parsed five-field POSIX cron expression (minute, hour, day-of-month,
+ * month, day-of-week) supporting `*`, lists, ranges, steps, month/day names,
+ * and the common `@daily`-style macros. Follows the standard rule that when
+ * both day-of-month and day-of-week are restricted, a date matches if EITHER
+ * matches.
+ */
+class CronExpression {
+    expression;
+    #minutes;
+    #hours;
+    #daysOfMonth;
+    #months;
+    #daysOfWeek;
+    #dayOfMonthRestricted;
+    #dayOfWeekRestricted;
+    constructor(expression) {
+        this.expression = expression;
+        const normalized = (MACROS[expression.trim().toLowerCase()] ?? expression).trim();
+        const fields = normalized.split(/\s+/);
+        if (fields.length !== 5) {
+            throw new InvalidCronExpressionError(`Cron expression "${expression}" has ${fields.length} fields; expected 5 (minute hour day-of-month month day-of-week)`);
+        }
+        this.#minutes = parseField(fields[0], MINUTE_FIELD, 'minute', expression);
+        this.#hours = parseField(fields[1], HOUR_FIELD, 'hour', expression);
+        this.#daysOfMonth = parseField(fields[2], DAY_OF_MONTH_FIELD, 'day-of-month', expression);
+        this.#months = parseField(fields[3], MONTH_FIELD, 'month', expression);
+        this.#daysOfWeek = parseField(fields[4], DAY_OF_WEEK_FIELD, 'day-of-week', expression);
+        // 7 is an alias for Sunday
+        if (this.#daysOfWeek[7])
+            this.#daysOfWeek[0] = true;
+        this.#dayOfMonthRestricted = fields[2] !== '*';
+        this.#dayOfWeekRestricted = fields[4] !== '*';
+        // Surface never-firing schedules (e.g. February 30th) at parse time
+        // rather than as a silently idle job
+        if (this.nextWallTime(new Date()) === null) {
+            throw new InvalidCronExpressionError(`Cron expression "${expression}" can never fire`);
+        }
+    }
+    #dayMatches(wallTime) {
+        const dayOfMonthMatch = this.#daysOfMonth[wallTime.getUTCDate()];
+        const dayOfWeekMatch = this.#daysOfWeek[wallTime.getUTCDay()];
+        if (this.#dayOfMonthRestricted && this.#dayOfWeekRestricted)
+            return dayOfMonthMatch || dayOfWeekMatch;
+        if (this.#dayOfMonthRestricted)
+            return dayOfMonthMatch;
+        if (this.#dayOfWeekRestricted)
+            return dayOfWeekMatch;
+        return true;
+    }
+    /**
+     * The next matching wall-clock time strictly after `afterWallTime` (both as
+     * "zoned wall time" Dates — see toZonedWallTime). Returns null if no match
+     * exists within the search horizon.
+     */
+    nextWallTime(afterWallTime) {
+        // Truncate to the minute, then step forward
+        let candidate = new Date(Math.floor(afterWallTime.getTime() / MINUTE_MS) * MINUTE_MS + MINUTE_MS);
+        const horizon = afterWallTime.getTime() + MAX_SEARCH_YEARS * 366 * 24 * 60 * MINUTE_MS;
+        while (candidate.getTime() <= horizon) {
+            if (!this.#months[candidate.getUTCMonth() + 1]) {
+                // First minute of the next month
+                candidate = new Date(Date.UTC(candidate.getUTCFullYear(), candidate.getUTCMonth() + 1, 1));
+                continue;
+            }
+            if (!this.#dayMatches(candidate)) {
+                candidate = new Date(Date.UTC(candidate.getUTCFullYear(), candidate.getUTCMonth(), candidate.getUTCDate() + 1));
+                continue;
+            }
+            if (!this.#hours[candidate.getUTCHours()]) {
+                candidate = new Date(Date.UTC(candidate.getUTCFullYear(), candidate.getUTCMonth(), candidate.getUTCDate(), candidate.getUTCHours() + 1));
+                continue;
+            }
+            if (!this.#minutes[candidate.getUTCMinutes()]) {
+                candidate = new Date(candidate.getTime() + MINUTE_MS);
+                continue;
+            }
+            return candidate;
+        }
+        return null;
+    }
+    /**
+     * The latest matching wall-clock time strictly before `beforeWallTime`
+     * (zoned wall time in, zoned wall time out). Returns null if no match
+     * exists within the search horizon.
+     */
+    previousWallTime(beforeWallTime) {
+        let candidate = new Date(Math.ceil(beforeWallTime.getTime() / MINUTE_MS) * MINUTE_MS - MINUTE_MS);
+        const horizon = beforeWallTime.getTime() - MAX_SEARCH_YEARS * 366 * 24 * 60 * MINUTE_MS;
+        while (candidate.getTime() >= horizon) {
+            if (!this.#months[candidate.getUTCMonth() + 1]) {
+                // Last minute of the previous month
+                candidate = new Date(Date.UTC(candidate.getUTCFullYear(), candidate.getUTCMonth(), 1) - MINUTE_MS);
+                continue;
+            }
+            if (!this.#dayMatches(candidate)) {
+                // Last minute of the previous day
+                candidate = new Date(Date.UTC(candidate.getUTCFullYear(), candidate.getUTCMonth(), candidate.getUTCDate()) - MINUTE_MS);
+                continue;
+            }
+            if (!this.#hours[candidate.getUTCHours()]) {
+                // Last minute of the previous hour
+                candidate = new Date(Date.UTC(candidate.getUTCFullYear(), candidate.getUTCMonth(), candidate.getUTCDate(), candidate.getUTCHours()) - MINUTE_MS);
+                continue;
+            }
+            if (!this.#minutes[candidate.getUTCMinutes()]) {
+                candidate = new Date(candidate.getTime() - MINUTE_MS);
+                continue;
+            }
+            return candidate;
+        }
+        return null;
+    }
+    /**
+     * The next real instant strictly after `after` at which this expression
+     * fires in the given timezone (defaults to the system timezone). Returns
+     * null for schedules with no future occurrence in the search horizon.
+     */
+    nextDate(after, timezone = getSystemTimezone()) {
+        let wall = toZonedWallTime(after, timezone);
+        // A DST fall-back overlap maps repeated-hour wall times to their FIRST
+        // occurrence, which can sit at or before `after` when `after` is inside
+        // the second pass — advance occurrences until we cross it. The bound is
+        // wall-clock distance, not attempt count: a minutely cron needs ~an
+        // hour's worth of occurrences to converge through the overlap (surfaced
+        // empirically in review; a fixed small attempt cap wedged sub-hourly
+        // jobs for the whole window).
+        const wallHorizon = wall.getTime() + DST_CONVERGENCE_HORIZON_MS;
+        for (let attempts = 0; attempts < MAX_CONVERGENCE_ATTEMPTS; attempts++) {
+            const nextWall = this.nextWallTime(wall);
+            if (nextWall === null)
+                return null;
+            const instant = fromZonedWallTime(nextWall, timezone);
+            if (instant.getTime() > after.getTime())
+                return instant;
+            if (nextWall.getTime() > wallHorizon)
+                return null;
+            wall = nextWall;
+        }
+        return null;
+    }
+    /**
+     * The most recent real instant strictly before `before` at which this
+     * expression fired in the given timezone (defaults to the system timezone).
+     */
+    previousDate(before, timezone = getSystemTimezone()) {
+        let wall = toZonedWallTime(before, timezone);
+        const wallHorizon = wall.getTime() - DST_CONVERGENCE_HORIZON_MS;
+        for (let attempts = 0; attempts < MAX_CONVERGENCE_ATTEMPTS; attempts++) {
+            const previousWall = this.previousWallTime(wall);
+            if (previousWall === null)
+                return null;
+            const instant = fromZonedWallTime(previousWall, timezone);
+            if (instant.getTime() < before.getTime())
+                return instant;
+            if (previousWall.getTime() < wallHorizon)
+                return null;
+            wall = previousWall;
+        }
+        return null;
+    }
+}
+exports.CronExpression = CronExpression;
+//# sourceMappingURL=CronExpression.js.map

package/dist/resources/scheduler/CronExpression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CronExpression.js","sourceRoot":"","sources":["../../../resources/scheduler/CronExpression.ts"],"names":[],"mappings":"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"}

package/dist/resources/scheduler/engine.d.ts

@@ -0,0 +1,91 @@
+import { CronExpression } from './CronExpression.ts';
+export declare const HEARTBEAT_INTERVAL_MS: number;
+export declare const STALE_THRESHOLD_MS: number;
+export declare const FAILOVER_WATCHER_INTERVAL_MS: number;
+export interface JobRunContext {
+    jobName: string;
+    scheduledAt: Date;
+    catchUp: boolean;
+}
+export interface ScheduledJob {
+    name: string;
+    componentName: string;
+    cron?: CronExpression;
+    intervalMs?: number;
+    timezone?: string;
+    handler: (context: JobRunContext) => unknown;
+}
+type EngineRole = 'inactive' | 'follower' | 'leader';
+/**
+ * Job handlers and storage drivers can throw anything — including objects
+ * whose property getters themselves throw — so even reading .message is
+ * guarded here (surfaced by review).
+ */
+export declare function safeErrorMessage(error: unknown): string;
+/**
+ * Deterministic election: the alphabetically-first node wins, excluding a
+ * stale leader so a wedged node cannot immediately re-elect itself. Every node
+ * evaluates this identically against the same replicated state, so no
+ * consensus round is needed.
+ */
+export declare function pickNextLeader(roster: string[], staleLeader: string | null): string | null;
+export declare function isHeartbeatStale(lastHeartbeat: string | undefined, now?: number): boolean;
+export declare const PROMOTION_ESCALATION_MS: number;
+/**
+ * How long this node should observe a leaderless cluster before promoting
+ * itself. The preferred (alphabetically-first eligible) node promotes
+ * immediately; each subsequent node adds one escalation interval, so a dead or
+ * never-started preferred node cannot deadlock the cluster — the next node in
+ * line claims leadership one rung later, and sticky leadership plus the
+ * heartbeat takeover check heal any race between rungs.
+ */
+export declare function promotionWaitMs(roster: string[], self: string, staleLeader: string | null): number;
+/**
+ * The cron occurrence that should have fired but didn't, or null if the job is
+ * up to date. `baseline` is the job's last run (or when it was first seen, so
+ * a newly-deployed job waits for its first scheduled time instead of firing
+ * immediately).
+ */
+export declare function findMissedCronOccurrence(cron: CronExpression, timezone: string | undefined, baseline: Date, now: Date): Date | null;
+/**
+ * Register (or replace) the scheduled jobs for a component. Called from the
+ * scheduler plugin's handleApplication on the scheduling worker; safe to call
+ * repeatedly — a reload or redeploy replaces the component's whole job set.
+ */
+export declare function registerComponentJobs(componentName: string, jobs: ScheduledJob[]): void;
+/**
+ * Cancel timers and forget the jobs of a component (its scope is closing —
+ * worker shutdown, redeploy, or a discarded deploy-validation load).
+ *
+ * Leadership is deliberately retained even if this empties the job set: the
+ * common cause is a reload that re-registers moments later, and stepping down
+ * here would leave the engine unable to re-elect (startSchedulerEngine is
+ * one-shot per worker). An idle leader heartbeating a zero-job cluster is
+ * harmless and resolves on the next worker restart.
+ */
+export declare function unregisterComponentJobs(componentName: string): void;
+/**
+ * Start the engine's cluster role (leader or follower). Idempotent; called
+ * once per scheduling worker regardless of how many components declare jobs.
+ * All the real work happens asynchronously so the caller (handleApplication,
+ * which holds a cross-thread load lock with a 30s timeout) returns fast.
+ */
+export declare function startSchedulerEngine(): void;
+/** @internal — testing only: resolves when the initial election has settled */
+export declare function electionSettledForTests(): Promise<void>;
+/**
+ * @internal — testing only: run one heartbeat tick immediately (same body the
+ * interval runs), so tests can drive lease renewal / takeover checks without
+ * waiting out HEARTBEAT_INTERVAL_MS. Same seam pattern as
+ * setCoolingFunctionForTests in transactionLogCooling.
+ */
+export declare function runHeartbeatForTests(): Promise<void>;
+/** @internal — testing only: run one failover-watcher tick immediately */
+export declare function runFailoverCheckForTests(): Promise<void>;
+/** Reset all engine state and timers. Intended for tests. */
+export declare function stopSchedulerEngine(): void;
+export declare function getEngineRole(): EngineRole;
+/** @internal — testing only */
+export declare function getRegisteredJobNames(componentName: string): string[];
+export declare function sanitizeStoredError(message: string): string;
+export {};