Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
fix(monitors): compute the next cron run by jumping days and hours, not minute by minute (#4963)
Gergő Móriczb60ef4ed4d71
diff --git a/apps/api/src/services/monitoring/cron.test.ts b/apps/api/src/services/monitoring/cron.test.tsnew file mode 100644index 000000000..52a1dc097--- /dev/null+++ b/apps/api/src/services/monitoring/cron.test.ts@@ -0,0 +1,166 @@+import { getNextMonitorRunAt, validateMonitorCron } from "./cron";++// Minute-by-minute reference: the previous implementation, kept here so the+// jump-based search is checked against it over short horizons (it costs one+// Intl format per minute, so horizons stay at a few days).+function referenceNextRun(cron: string, from: Date, timeZone: string): Date {+ const [mi, h, dom, mo, dow] = cron.trim().split(/\s+/);+ const expand = (field: string, min: number, max: number) => {+ const out = new Set<number>();+ for (const part of field.split(",")) {+ const [range, stepPart] = part.split("/");+ const step = stepPart ? Number(stepPart) : 1;+ let start = min;+ let end = max;+ if (range !== "*") {+ if (range.includes("-")) [start, end] = range.split("-").map(Number);+ else start = end = Number(range);+ }+ for (let v = start; v <= end; v += step) out.add(v);+ }+ return out;+ };+ const minutes = expand(mi, 0, 59);+ const hours = expand(h, 0, 23);+ const days = expand(dom, 1, 31);+ const months = expand(mo, 1, 12);+ const weekdays = expand(dow, 0, 7);+ if (weekdays.has(7)) weekdays.add(0);+ const fmt = new Intl.DateTimeFormat("en-US", {+ timeZone,+ hourCycle: "h23",+ minute: "2-digit",+ hour: "2-digit",+ day: "2-digit",+ month: "2-digit",+ weekday: "short",+ });+ const wd: Record<string, number> = {+ sun: 0,+ mon: 1,+ tue: 2,+ wed: 3,+ thu: 4,+ fri: 5,+ sat: 6,+ };+ const candidate = new Date(from);+ candidate.setUTCSeconds(0, 0);+ candidate.setUTCMinutes(candidate.getUTCMinutes() + 1);+ for (let i = 0; i < 10 * 24 * 60; i++) {+ const p = Object.fromEntries(+ fmt+ .formatToParts(candidate)+ .filter(x => x.type !== "literal")+ .map(x => [x.type, x.value]),+ );+ if (+ minutes.has(Number(p.minute)) &&+ hours.has(Number(p.hour)) &&+ days.has(Number(p.day)) &&+ months.has(Number(p.month)) &&+ weekdays.has(wd[String(p.weekday).toLowerCase()])+ ) {+ return new Date(candidate);+ }+ candidate.setUTCMinutes(candidate.getUTCMinutes() + 1);+ }+ throw new Error("reference: no run within 10 days");+}++describe("getNextMonitorRunAt", () => {+ const cases: Array<[cron: string, from: string, timeZone: string]> = [+ // Plain schedules.+ ["*/5 * * * *", "2027-06-15T10:03:20Z", "UTC"],+ ["0 * * * *", "2027-06-15T10:03:20Z", "UTC"],+ ["30 9 * * *", "2027-06-15T10:03:20Z", "UTC"],+ ["30 9 * * *", "2027-06-15T10:03:20Z", "Asia/Kolkata"],+ ["30 9 * * *", "2027-06-15T10:03:20Z", "Pacific/Chatham"],+ ["0 9 * * 1", "2027-06-15T10:03:20Z", "America/Chicago"],+ ["0 9 1,8,15,22 * *", "2027-06-10T00:00:00Z", "America/New_York"],+ ["15,45 8-17 * * 1-5", "2027-06-18T16:50:00Z", "Europe/Berlin"],+ ["0 6 * * 1,4", "2027-06-15T06:00:00Z", "UTC"],+ ["0 0 * * 0", "2027-06-15T10:03:20Z", "Europe/London"],+ ["59 23 * * *", "2027-06-15T23:58:30Z", "UTC"],+ ["0 0 * * *", "2027-06-15T23:59:30Z", "Australia/Sydney"],+ // US spring forward (2027-03-14 02:00 -> 03:00 local): 02:30 does not exist.+ ["30 2 * * *", "2027-03-13T12:00:00Z", "America/New_York"],+ ["0 * * * *", "2027-03-14T06:30:00Z", "America/New_York"],+ ["15 1 * * *", "2027-03-14T05:00:00Z", "America/New_York"],+ ["0 3 * * *", "2027-03-14T06:30:00Z", "America/New_York"],+ // US fall back (2027-11-07 02:00 -> 01:00 local): 01:30 happens twice.+ ["30 1 * * *", "2027-11-07T04:00:00Z", "America/New_York"],+ ["0 2 * * *", "2027-11-07T04:00:00Z", "America/New_York"],+ ["0 0 * * *", "2027-11-07T04:00:00Z", "America/New_York"],+ // Europe spring forward (2027-03-28 01:00 -> 02:00 local).+ ["30 1 * * *", "2027-03-27T12:00:00Z", "Europe/London"],+ ["0 0 * * *", "2027-03-28T00:30:00Z", "Europe/London"],+ // Southern hemisphere DST end (2027-04-04 03:00 -> 02:00 local).+ ["30 2 * * *", "2027-04-03T12:00:00Z", "Australia/Sydney"],+ // Two-hour spring-forward (Antarctica/Troll, 2027-03-28 01:00 UTC): a+ // 23 h jump in UTC would land at 02:00 local the next day (Monday 03-29).+ ["0 0 * * 1", "2027-03-28T00:00:00Z", "Antarctica/Troll"],+ ["0 0 * * *", "2027-03-27T12:00:00Z", "Antarctica/Troll"],+ ["30 23 * * *", "2027-03-27T22:00:00Z", "Antarctica/Troll"],+ ["0 2 * * *", "2027-03-27T12:00:00Z", "Antarctica/Troll"],+ ["30 1 * * *", "2027-03-27T12:00:00Z", "Antarctica/Troll"],+ // Half-hour DST shift (Australia/Lord_Howe, 2027-04-04 02:00 -> 01:30).+ ["0 2 * * *", "2027-04-03T12:00:00Z", "Australia/Lord_Howe"],+ ["45 1 * * *", "2027-04-03T12:00:00Z", "Australia/Lord_Howe"],+ // Zones that shift at local midnight.+ ["0 0 * * *", "2027-03-27T12:00:00Z", "Asia/Beirut"],+ ["30 0 * * *", "2027-04-03T12:00:00Z", "America/Santiago"],+ ];++ it.each(cases)(+ "matches the minute-by-minute reference for %s from %s in %s",+ (cron, from, timeZone) => {+ const fromDate = new Date(from);+ const actual = getNextMonitorRunAt(cron, fromDate, timeZone);+ expect(actual.toISOString()).toBe(+ referenceNextRun(cron, fromDate, timeZone).toISOString(),+ );+ // Chained: the second run must also agree.+ const second = getNextMonitorRunAt(cron, actual, timeZone);+ expect(second.toISOString()).toBe(+ referenceNextRun(cron, actual, timeZone).toISOString(),+ );+ },+ );++ it("finds a yearly run in milliseconds, not tens of seconds", () => {+ const start = Date.now();+ const next = getNextMonitorRunAt(+ "0 0 1 1 *",+ new Date("2027-02-03T04:05:00Z"),+ "UTC",+ );+ const second = getNextMonitorRunAt("0 0 1 1 *", next, "UTC");+ expect(next.toISOString()).toBe("2028-01-01T00:00:00.000Z");+ expect(second.toISOString()).toBe("2029-01-01T00:00:00.000Z");+ expect(Date.now() - start).toBeLessThan(500);+ });++ it("still rejects a cron with no run inside a year, quickly", () => {+ const start = Date.now();+ expect(() =>+ getNextMonitorRunAt("0 0 30 2 *", new Date("2027-06-15T00:00:00Z")),+ ).toThrow("did not produce a run within one year");+ expect(Date.now() - start).toBeLessThan(500);+ });+});++describe("validateMonitorCron", () => {+ it("returns a yearly interval for a yearly cron", () => {+ const { intervalMs } = validateMonitorCron("0 0 1 1 *", "UTC");+ expect(intervalMs / (24 * 60 * 60 * 1000)).toBeGreaterThanOrEqual(365);+ expect(intervalMs / (24 * 60 * 60 * 1000)).toBeLessThanOrEqual(366);+ });++ it("keeps the five-minute floor", () => {+ expect(validateMonitorCron("*/5 * * * *").intervalMs).toBe(5 * 60 * 1000);+ expect(() => validateMonitorCron("*/4 * * * *")).toThrow(+ "must not run more often than every 5 minutes",+ );+ });+});diff --git a/apps/api/src/services/monitoring/cron.ts b/apps/api/src/services/monitoring/cron.tsindex ca80ea2f5..181d1a32f 100644--- a/apps/api/src/services/monitoring/cron.ts+++ b/apps/api/src/services/monitoring/cron.ts@@ -177,16 +177,29 @@ function validateTimeZone(timeZone: string): void {}}+// One formatter per zone: constructing Intl.DateTimeFormat is the expensive+// part, and the next-run search below calls this hundreds of times.+const zonedFormatters = new Map<string, Intl.DateTimeFormat>();++function zonedFormatter(timeZone: string): Intl.DateTimeFormat {+ let formatter = zonedFormatters.get(timeZone);+ if (!formatter) {+ formatter = new Intl.DateTimeFormat("en-US", {+ timeZone,+ hourCycle: "h23",+ minute: "2-digit",+ hour: "2-digit",+ day: "2-digit",+ month: "2-digit",+ weekday: "short",+ });+ zonedFormatters.set(timeZone, formatter);+ }+ return formatter;+}+function getZonedParts(date: Date, timeZone: string) {- const parts = new Intl.DateTimeFormat("en-US", {- timeZone,- hourCycle: "h23",- minute: "2-digit",- hour: "2-digit",- day: "2-digit",- month: "2-digit",- weekday: "short",- }).formatToParts(date);+ const parts = zonedFormatter(timeZone).formatToParts(date);const values = Object.fromEntries(parts@@ -203,17 +216,74 @@ function getZonedParts(date: Date, timeZone: string) {};}-function matches(date: Date, cron: CronSpec, timeZone: string): boolean {- const zoned = getZonedParts(date, timeZone);+type ZonedParts = ReturnType<typeof getZonedParts>;++function dayMatches(zoned: ZonedParts, cron: CronSpec): boolean {return (- cron.minutes.has(zoned.minutes) &&- cron.hours.has(zoned.hours) &&cron.daysOfMonth.has(zoned.daysOfMonth) &&cron.months.has(zoned.months) &&cron.daysOfWeek.has(zoned.daysOfWeek));}+function matches(zoned: ZonedParts, cron: CronSpec): boolean {+ return (+ cron.minutes.has(zoned.minutes) &&+ cron.hours.has(zoned.hours) &&+ dayMatches(zoned, cron)+ );+}++/**+ * Local wall-clock position relative to the start of `base`'s local day:+ * negative on the previous day, 0-1439 on the same day, 1440+ on the next.+ * A jump never spans more than one day, so day/month alone identify it.+ */+function localMinutesFrom(base: ZonedParts, zoned: ZonedParts): number {+ const sameDay =+ zoned.daysOfMonth === base.daysOfMonth && zoned.months === base.months;+ const nextDay =+ !sameDay &&+ ((zoned.months === base.months &&+ zoned.daysOfMonth === base.daysOfMonth + 1) ||+ (zoned.months !== base.months && zoned.daysOfMonth === 1));+ const dayOffset = sameDay ? 0 : nextDay ? 24 * 60 : -(24 * 60);+ return dayOffset + zoned.hours * 60 + zoned.minutes;+}++/**+ * The next local wall-clock position (minutes from the start of `zoned`'s+ * local day) that could match: the next day's 00:00 when the day does not+ * match, the next hour when the hour does not, otherwise the next listed+ * minute (or the next hour when none is left in this one).+ */+function nextLocalTarget(zoned: ZonedParts, cron: CronSpec): number {+ const localMinutes = zoned.hours * 60 + zoned.minutes;+ if (!dayMatches(zoned, cron)) return 24 * 60;+ if (!cron.hours.has(zoned.hours)) return (zoned.hours + 1) * 60;+ let nextMinute = Infinity;+ for (const minute of cron.minutes) {+ if (minute > zoned.minutes && minute < nextMinute) nextMinute = minute;+ }+ return nextMinute === Infinity+ ? (zoned.hours + 1) * 60+ : zoned.hours * 60 + nextMinute;+}++/**+ * First instant strictly after `from` (at minute precision) matching the cron+ * in `timeZone`, or an error when none falls within the next year.+ *+ * The search jumps to the next local day, hour or listed minute instead of+ * stepping every minute: a yearly cron used to cost ~500k `Intl` formats+ * (tens of seconds on the event loop, enough to fail the liveness probe); it+ * now costs a few hundred. Jumps are made in UTC minutes, so a UTC offset+ * change inside a jump can land past the intended local target (a two-hour+ * spring-forward, say); the landing point is read back and pulled to the+ * target when that happens. A target that does not exist locally (a gap at+ * midnight) keeps the first instant after it. Landing short (fall-back) just+ * leaves the loop to jump again.+ */export function getNextMonitorRunAt(cronExpression: string,from = new Date(),@@ -225,11 +295,32 @@ export function getNextMonitorRunAt(candidate.setUTCSeconds(0, 0);candidate.setUTCMinutes(candidate.getUTCMinutes() + 1);- for (let i = 0; i < SEARCH_LIMIT_MINUTES; i++) {- if (matches(candidate, cron, timeZone)) {+ let advanced = 0;+ while (advanced < SEARCH_LIMIT_MINUTES) {+ const zoned = getZonedParts(candidate, timeZone);+ if (matches(zoned, cron)) {return new Date(candidate);}- candidate.setUTCMinutes(candidate.getUTCMinutes() + 1);++ const target = nextLocalTarget(zoned, cron);+ const step = Math.max(1, target - (zoned.hours * 60 + zoned.minutes));+ let next = new Date(candidate.getTime() + step * 60_000);+ const landed = localMinutesFrom(zoned, getZonedParts(next, timeZone));+ if (landed > target) {+ const pulled = new Date(next.getTime() - (landed - target) * 60_000);+ // Only pull back to an instant that is still after the candidate and+ // still at or past the target: a gap (the target does not exist+ // locally) can otherwise send the search backwards.+ if (+ pulled.getTime() > candidate.getTime() &&+ localMinutesFrom(zoned, getZonedParts(pulled, timeZone)) >= target+ ) {+ next = pulled;+ }+ }++ advanced += (next.getTime() - candidate.getTime()) / 60_000;+ candidate.setTime(next.getTime());}throw new Error("Cron expression did not produce a run within one year");