@interactive-inc/flume 0.9.4 → 0.10.1

package/dist/time.js

@@ -1,13 +1,16 @@
-import { a as FlumeStartError, c as safeNormalizeError, i as safeNow, l as safeErrorMessage, n as safeInvokeCallback, o as FlumeParseError, r as FlumeLogger, s as attempt, t as FlumeSource } from "./flume-source.js";
+import { a as safeNow, c as attempt, i as FlumeLogger, l as safeNormalizeError, o as FlumeStartError, r as safeInvokeCallback, s as FlumeParseError, t as FlumeSource, u as safeErrorMessage } from "./flume-source.js";
 import { t as isRecord } from "./is-record.js";
 //#region lib/time/parse-cron-field.ts
 /**
 * 単一 cron フィールド (minute など) の spec を許可値の Set に展開する。
-* 対応: `*` / `* /n` / `a` / `a-b` / `a-b/n` とそれらのカンマ区切り。名前 (JAN, MON) は非対応
+* 対応: `*` / `* /n` / `a` / `a-b` / `a-b/n` とそれらのカンマ区切り。名前 (JAN, MON) は非対応。
+* 空トークン (`"5,"` / `"-5"` / `"/5"` など) は `Number("") === 0` の暗黙変換で
+* 0 に化けるため、数値が期待される位置の空文字列は明示的に拒否する
 */
 function parseCronField(spec, min, max) {
 	const values = /* @__PURE__ */ new Set();
 	for (const part of spec.split(",")) {
+		if (part === "") return new FlumeParseError(`empty cron list segment: "${spec}"`);
 		const expanded = expandCronPart(part, min, max);
 		if (expanded instanceof FlumeParseError) return expanded;
 		for (const value of expanded) values.add(value);
@@ -16,15 +19,12 @@ function parseCronField(spec, min, max) {
 	return values;
 }
 function expandCronPart(part, min, max) {
-	let range = part;
-	let step = 1;
 	const slash = part.indexOf("/");
-	if (slash !== -1) {
-		range = part.slice(0, slash);
-		const parsed = Number(part.slice(slash + 1));
-		if (!Number.isInteger(parsed) || parsed <= 0) return new FlumeParseError(`invalid cron step: "${part}"`);
-		step = parsed;
-	}
+	const range = slash === -1 ? part : part.slice(0, slash);
+	const stepToken = slash === -1 ? null : part.slice(slash + 1);
+	if (stepToken === "") return new FlumeParseError(`invalid cron step: "${part}"`);
+	const step = stepToken === null ? 1 : Number(stepToken);
+	if (!Number.isInteger(step) || step <= 0) return new FlumeParseError(`invalid cron step: "${part}"`);
 	const bounds = resolveBounds(range, min, max);
 	if (bounds instanceof FlumeParseError) return bounds;
 	const numbers = [];
@@ -37,8 +37,11 @@ function resolveBounds(range, min, max) {
 		hi: max
 	};
 	const dash = range.indexOf("-");
-	const lo = dash === -1 ? Number(range) : Number(range.slice(0, dash));
-	const hi = dash === -1 ? lo : Number(range.slice(dash + 1));
+	const loToken = dash === -1 ? range : range.slice(0, dash);
+	const hiToken = dash === -1 ? loToken : range.slice(dash + 1);
+	if (loToken === "" || hiToken === "") return new FlumeParseError(`invalid cron range: "${range}"`);
+	const lo = Number(loToken);
+	const hi = Number(hiToken);
 	if (!Number.isInteger(lo) || !Number.isInteger(hi)) return new FlumeParseError(`invalid cron range: "${range}"`);
 	if (lo < min || hi > max || lo > hi) return new FlumeParseError(`cron value out of range [${min}-${max}]: "${range}"`);
 	return {
@@ -74,20 +77,20 @@ function parseCron(expression) {
 		daysOfMonth,
 		months,
 		daysOfWeek,
-		domRestricted: fields[2] !== "*",
-		dowRestricted: fields[4] !== "*"
+		domRestricted: !fields[2]?.includes("*"),
+		dowRestricted: !fields[4]?.includes("*")
 	};
 }
 //#endregion
 //#region lib/time/cron-next.ts
-const MINUTE_MS = 6e4;
+const MINUTE_MS$1 = 6e4;
 const MAX_ITERATIONS = 5e5;
 /**
 * `afterMs` より後の最初の cron マッチ時刻 (epoch ms) を壁時計 (local time) で求める。
 * 到達不能なら FlumeParseError を返す
 */
 function flumeCronNext(cron, afterMs) {
-	let candidate = Math.floor(afterMs / MINUTE_MS) * MINUTE_MS + MINUTE_MS;
+	let candidate = Math.floor(afterMs / MINUTE_MS$1) * MINUTE_MS$1 + MINUTE_MS$1;
 	for (let iteration = 0; iteration < MAX_ITERATIONS; iteration++) {
 		const date = new Date(candidate);
 		if (!cron.months.has(date.getMonth() + 1)) {
@@ -103,7 +106,7 @@ function flumeCronNext(cron, afterMs) {
 			continue;
 		}
 		if (!cron.minutes.has(date.getMinutes())) {
-			candidate += MINUTE_MS;
+			candidate += MINUTE_MS$1;
 			continue;
 		}
 		return candidate;
@@ -114,17 +117,48 @@ function matchesDay(cron, date) {
 	const domMatch = cron.daysOfMonth.has(date.getDate());
 	const dowMatch = cron.daysOfWeek.has(date.getDay());
 	if (cron.domRestricted && cron.dowRestricted) return domMatch || dowMatch;
-	if (cron.domRestricted) return domMatch;
-	if (cron.dowRestricted) return dowMatch;
-	return true;
+	return domMatch && dowMatch;
+}
+//#endregion
+//#region lib/time/is-dst-duplicate-fire.ts
+const DEDUP_WINDOW_MS = 7200 * 1e3;
+/**
+* DST fall-back では同一壁時計分 (y/m/d/h/min) が 2 つの epoch に存在し、
+* 分単位の epoch ウォークが両方にマッチして二重発火する。fire 直後に計算した
+* 次ターゲットが直近 2 時間の fire のいずれかと同じ壁時計分なら重複と判定する。
+* 複数分にマッチする cron では巻き戻し後の最初の時刻と直前 fire の分が異なるため、
+* 直前 1 件でなく履歴を受け取る
+*/
+function isDstDuplicateFire(firedTimes, nextTarget) {
+	for (let index = firedTimes.length - 1; index >= 0; index--) {
+		const firedAt = firedTimes[index];
+		if (firedAt === void 0) continue;
+		if (nextTarget <= firedAt) continue;
+		if (nextTarget - firedAt > DEDUP_WINDOW_MS) return false;
+		if (hasSameLocalMinute(firedAt, nextTarget)) return true;
+	}
+	return false;
+}
+function hasSameLocalMinute(firedAt, nextTarget) {
+	const fired = new Date(firedAt);
+	const next = new Date(nextTarget);
+	if (fired.getFullYear() !== next.getFullYear()) return false;
+	if (fired.getMonth() !== next.getMonth()) return false;
+	if (fired.getDate() !== next.getDate()) return false;
+	if (fired.getHours() !== next.getHours()) return false;
+	return fired.getMinutes() === next.getMinutes();
 }
 //#endregion
 //#region lib/time/time-scheduler.ts
 const MAX_TIMEOUT_MS = 2e9;
 const FIRE_TOLERANCE_MS = 1e3;
+const DST_HISTORY_WINDOW_MS = 7200 * 1e3;
+const MAX_DST_SKIPS = 180;
 /**
 * cron に従って `onTick` を駆動するタイマーループ。外部接続を持たないため reconnect 不要。
-* IO 境界は全て `attempt` 経由で扱い、停止後はコールバックを発火しない
+* IO 境界は全て `attempt` 経由で扱い、停止後はコールバックを発火しない。
+* sleep-wake で複数回分を取り逃した場合は 1 回だけ発火して now まで早送りする
+* (取り逃しは `scheduler.skipped` info で観測可能)
 */
 var FlumeTimeScheduler = class {
 	props;
@@ -132,6 +166,7 @@ var FlumeTimeScheduler = class {
 	isStoppedFlag = false;
 	timer = null;
 	target = 0;
+	recentFires = [];
 	constructor(props) {
 		this.props = props;
 		this.log = new FlumeLogger({
@@ -143,8 +178,13 @@ var FlumeTimeScheduler = class {
 	get isStopped() {
 		return this.isStoppedFlag;
 	}
-	start() {
-		const next = flumeCronNext(this.props.cron, safeNow({ deps: this.props.deps }));
+	/**
+	* `fromMs` より後の最初のマッチを狙う。catchup と同じ基準時刻を共有できるよう
+	* 呼び出し側から 1 つのタイムスタンプを渡す (未指定なら now)
+	*/
+	start(fromMs) {
+		const basis = fromMs ?? safeNow({ deps: this.props.deps });
+		const next = flumeCronNext(this.props.cron, basis);
 		if (next instanceof FlumeParseError) {
 			this.log.error({
 				action: "cron.no-next",
@@ -159,14 +199,14 @@ var FlumeTimeScheduler = class {
 			message: `next fire at ${new Date(next).toISOString()}`,
 			detail: { target: next }
 		});
-		this.arm();
-		return null;
+		return this.arm();
 	}
 	stop() {
 		this.isStoppedFlag = true;
 		this.clearTimer();
 	}
 	arm() {
+		if (this.isStoppedFlag) return null;
 		this.clearTimer();
 		const delay = Math.max(0, this.target - safeNow({ deps: this.props.deps }));
 		const capped = Math.min(delay, MAX_TIMEOUT_MS);
@@ -178,18 +218,22 @@ var FlumeTimeScheduler = class {
 				error: result
 			});
 			this.timer = null;
-			return;
+			this.isStoppedFlag = true;
+			return result;
 		}
 		this.timer = result;
+		return null;
 	}
 	onWake() {
 		this.timer = null;
 		if (this.isStoppedFlag) return;
 		if (this.target - safeNow({ deps: this.props.deps }) > FIRE_TOLERANCE_MS) {
-			this.arm();
+			const error = this.arm();
+			if (error instanceof Error) this.halt(error);
 			return;
 		}
 		const firedAt = this.target;
+		this.rememberFire(firedAt);
 		safeInvokeCallback({
 			fn: () => this.props.onTick(firedAt),
 			onError: (error) => {
@@ -200,17 +244,78 @@ var FlumeTimeScheduler = class {
 				});
 			}
 		});
-		const next = flumeCronNext(this.props.cron, firedAt);
+		if (this.isStoppedFlag) return;
+		this.advanceAfterFire(firedAt);
+	}
+	/**
+	* fire 後の次ターゲット計算。sleep 明けで firedAt が過去に沈んでいる場合は
+	* now まで早送りして取り逃し分の replay burst を防ぐ (catchup は opt-in の別機構)
+	*/
+	advanceAfterFire(firedAt) {
+		const nowMs = safeNow({ deps: this.props.deps });
+		const firstAfterFired = flumeCronNext(this.props.cron, firedAt);
+		if (firstAfterFired instanceof FlumeParseError) {
+			this.halt(firstAfterFired);
+			return;
+		}
+		if (firstAfterFired <= nowMs) this.log.info({
+			action: "scheduler.skipped",
+			message: `late wake: skipped occurrence(s) between ${new Date(firedAt).toISOString()} and now`,
+			detail: {
+				latenessMs: nowMs - firedAt,
+				firedAt
+			}
+		});
+		const next = firstAfterFired > nowMs ? firstAfterFired : flumeCronNext(this.props.cron, nowMs);
 		if (next instanceof FlumeParseError) {
-			this.log.error({
-				action: "cron.no-next",
-				message: next.message,
-				error: next
-			});
+			this.halt(next);
 			return;
 		}
-		this.target = next;
-		this.arm();
+		const deduped = this.skipDstDuplicates(next);
+		if (deduped instanceof FlumeParseError) {
+			this.halt(deduped);
+			return;
+		}
+		this.target = deduped;
+		const armError = this.arm();
+		if (armError instanceof Error) this.halt(armError);
+	}
+	/** cron エラーによる恒久停止。source が接続済みのまま沈黙しないよう onHalt で通知する */
+	halt(error) {
+		this.isStoppedFlag = true;
+		this.clearTimer();
+		this.log.error({
+			action: "scheduler.halted",
+			message: error.message,
+			error
+		});
+		const onHalt = this.props.onHalt;
+		if (!onHalt) return;
+		safeInvokeCallback({
+			fn: () => onHalt(),
+			onError: (haltError) => {
+				this.log.error({
+					action: "scheduler.halt.error",
+					message: safeErrorMessage({ error: haltError }),
+					error: haltError
+				});
+			}
+		});
+	}
+	rememberFire(firedAt) {
+		this.recentFires.push(firedAt);
+		const cutoff = firedAt - DST_HISTORY_WINDOW_MS;
+		while (this.recentFires[0] !== void 0 && this.recentFires[0] < cutoff) this.recentFires.shift();
+	}
+	skipDstDuplicates(initialTarget) {
+		let target = initialTarget;
+		for (let iteration = 0; iteration < MAX_DST_SKIPS; iteration++) {
+			if (!isDstDuplicateFire(this.recentFires, target)) return target;
+			const next = flumeCronNext(this.props.cron, target);
+			if (next instanceof FlumeParseError) return next;
+			target = next;
+		}
+		return new FlumeParseError(`cron "${this.props.cron.source}" exceeded DST duplicate bound`);
 	}
 	clearTimer() {
 		if (this.timer === null) return;
@@ -225,11 +330,120 @@ var FlumeTimeScheduler = class {
 	}
 };
 //#endregion
+//#region lib/time/time-catchup.ts
+const DEFAULT_MISSED_WINDOW_MS = 1440 * 60 * 1e3;
+const MAX_CATCHUP_MATCHES = 1e4;
+const MINUTE_MS = 6e4;
+/**
+* `lastFiredAt` から `now` までに過ぎ去った cron マッチを policy に従って列挙する。
+*
+* - policy.mode === "off"      : 常に空
+* - policy.mode === "lastOnly" : 過ぎ去ったマッチの中で最も新しいもの 1 件 (件数上限なし・O(1) メモリ)
+* - policy.mode === "missed"   : maxWindowMs (既定 24h) 以内に過ぎ去ったすべてのマッチ。
+*                                window の起点は `max(lastFiredAt, now - maxWindowMs)`。
+*                                10,000 件を超えた場合は古い方を捨てて新しい 10,000 件を返し
+*                                truncated: true で通知する
+*
+* 到達不能 cron や catastrophic な policy ミス指定の場合は FlumeParseError を返す
+* (catchup 列挙だけで失敗させる。source 本体の起動は別判断)
+*/
+function flumeCollectCatchupMatches(props) {
+	const policy = props.policy;
+	if (policy.mode === "off") return {
+		matches: [],
+		truncated: false
+	};
+	if (props.lastFiredAt >= props.now) return {
+		matches: [],
+		truncated: false
+	};
+	if (policy.mode === "lastOnly") return collectLastOnly({
+		cron: props.cron,
+		windowStart: props.lastFiredAt,
+		now: props.now
+	});
+	const windowStart = Math.max(props.lastFiredAt, props.now - (policy.maxWindowMs ?? DEFAULT_MISSED_WINDOW_MS));
+	return collectMissed({
+		cron: props.cron,
+		windowStart,
+		now: props.now
+	});
+}
+function collectLastOnly(props) {
+	let lookbackMs = MINUTE_MS;
+	while (true) {
+		const recentStart = Math.max(props.windowStart, props.now - lookbackMs);
+		const walked = walkMatches({
+			...props,
+			windowStart: recentStart
+		});
+		if (walked instanceof FlumeParseError) return walked;
+		const latest = walked[walked.length - 1];
+		if (latest !== void 0) return {
+			matches: [latest],
+			truncated: false
+		};
+		if (recentStart === props.windowStart) return {
+			matches: [],
+			truncated: false
+		};
+		lookbackMs *= 2;
+	}
+}
+function collectMissed(props) {
+	let lookbackMs = MAX_CATCHUP_MATCHES * MINUTE_MS;
+	while (true) {
+		const recentStart = Math.max(props.windowStart, props.now - lookbackMs);
+		const walked = walkMatches({
+			...props,
+			windowStart: recentStart
+		});
+		if (walked instanceof FlumeParseError) return walked;
+		if (walked.length >= MAX_CATCHUP_MATCHES || recentStart === props.windowStart) {
+			const matches = walked.slice(Math.max(0, walked.length - MAX_CATCHUP_MATCHES));
+			const older = hasMatchBefore(props.cron, props.windowStart, recentStart);
+			if (older instanceof FlumeParseError) return older;
+			return {
+				matches,
+				truncated: walked.length > MAX_CATCHUP_MATCHES || older
+			};
+		}
+		lookbackMs *= 2;
+	}
+}
+function walkMatches(props) {
+	const matches = [];
+	let cursor = props.windowStart;
+	while (true) {
+		const next = flumeCronNext(props.cron, cursor);
+		if (next instanceof FlumeParseError) return next;
+		if (next > props.now) return matches;
+		if (!isDstDuplicateFire(matches, next)) matches.push(next);
+		cursor = next;
+	}
+}
+function hasMatchBefore(cron, windowStart, recentStart) {
+	if (recentStart === windowStart) return false;
+	const first = flumeCronNext(cron, windowStart);
+	if (first instanceof FlumeParseError) return first;
+	return first <= recentStart;
+}
+//#endregion
 //#region lib/time/time-source.ts
 /**
 * cron スケジュールで tick を emit する Source。外部接続を持たないため
 * 起動成功と同時に `connected` になり reconnect の対象外。
-* `options.message` で tick ごとの type / data / meta を上書きできる
+*
+* options.statePersister + options.catchupPolicy を渡すと:
+*  1. 起動時に lastFiredAt を読み出す
+*  2. lastFiredAt から now までの過ぎ去った cron マッチを policy に従って再発火する
+*  3. 各 tick 後に lastFiredAt を保存する (best-effort, ブロックしない)
+*
+* 保存先や形式は flume の関知ではなく statePersister の実装が決める (純粋 DI)。
+*
+* DST 制限: fall-back (時計の巻き戻し) の二重発火は dedup で防ぐが、spring-forward
+* (時計の飛び越し) でスキップされた壁時計時刻 (例: 02:30 が存在しない日) にスケジュール
+* された job はその日は実行されない。cron は壁時計 (local time) 基準のため仕様とする
 */
 var FlumeTimeSource = class extends FlumeSource {
 	options;
@@ -252,26 +466,41 @@ var FlumeTimeSource = class extends FlumeSource {
 			this.setStatus("disconnected", error.message);
 			return error;
 		}
+		const persister = this.options.statePersister ?? null;
+		const lastFiredAt = persister === null ? null : await this.loadLastFiredAt(ctx, persister);
 		this.scheduler = new FlumeTimeScheduler({
 			cron,
 			onLog: ctx.log.handler,
 			deps: ctx.deps,
-			onTick: (firedAt) => this.handleTick(ctx, firedAt)
+			onTick: (firedAt) => this.handleTick(ctx, firedAt, persister),
+			onHalt: () => this.handleSchedulerHalt(ctx)
 		});
-		const result = this.scheduler.start();
+		const startedAt = safeNow({ deps: ctx.deps });
+		const result = this.scheduler.start(startedAt);
 		if (result instanceof Error) {
 			const error = new FlumeStartError(`Time source: ${safeErrorMessage({ error: result })}`);
 			this.setStatus("disconnected", error.message);
 			return error;
 		}
 		this.setStatus("connected");
+		if (lastFiredAt !== null && persister !== null) this.runCatchup({
+			ctx,
+			cron,
+			lastFiredAt,
+			persister,
+			now: startedAt
+		});
 		return null;
 	}
 	disconnect() {
 		this.scheduler?.stop();
 		this.scheduler = null;
 	}
-	handleTick(ctx, firedAt) {
+	handleTick(ctx, firedAt, persister) {
+		this.emitTick(ctx, firedAt);
+		if (persister !== null) this.saveLastFiredAt(ctx, persister, firedAt);
+	}
+	emitTick(ctx, firedAt) {
 		const tick = {
 			firedAt,
 			cron: this.options.cron
@@ -288,6 +517,79 @@ var FlumeTimeSource = class extends FlumeSource {
 			receivedAt: safeNow({ deps: ctx.deps })
 		});
 	}
+	runCatchup(props) {
+		const policy = this.options.catchupPolicy ?? { mode: "off" };
+		if (policy.mode === "off") return;
+		const collected = flumeCollectCatchupMatches({
+			cron: props.cron,
+			lastFiredAt: props.lastFiredAt,
+			now: props.now,
+			policy
+		});
+		if (collected instanceof FlumeParseError) {
+			props.ctx.log.warn({
+				action: "time.catchup.failed",
+				message: collected.message,
+				error: collected
+			});
+			return;
+		}
+		if (collected.truncated) props.ctx.log.warn({
+			action: "time.catchup.truncated",
+			message: "catchup exceeded the match cap; oldest missed tick(s) were dropped",
+			detail: {
+				kept: collected.matches.length,
+				policy: policy.mode
+			}
+		});
+		const matches = collected.matches;
+		if (matches.length === 0) return;
+		props.ctx.log.info({
+			action: "time.catchup.fired",
+			message: `catchup ${matches.length} missed tick(s) since ${new Date(props.lastFiredAt).toISOString()}`,
+			detail: {
+				count: matches.length,
+				policy: policy.mode
+			}
+		});
+		for (const firedAt of matches) this.emitTick(props.ctx, firedAt);
+		const last = matches[matches.length - 1];
+		if (last !== void 0) this.saveLastFiredAt(props.ctx, props.persister, last);
+	}
+	/** スケジューラが cron エラーで恒久停止した (dead-but-green を防ぐため接続状態を落とす) */
+	handleSchedulerHalt(ctx) {
+		ctx.log.error({
+			action: "time.scheduler.halted",
+			message: "scheduler halted due to cron error; time source will not tick again"
+		});
+		this.setStatus("disconnected", "scheduler halted");
+	}
+	async loadLastFiredAt(ctx, persister) {
+		const result = await attempt(() => persister.load());
+		if (result instanceof Error) {
+			ctx.log.warn({
+				action: "time.state.load.error",
+				message: safeErrorMessage({ error: result }),
+				error: result
+			});
+			return null;
+		}
+		if (result === null) return null;
+		if (typeof result.lastFiredAt !== "number" || !Number.isFinite(result.lastFiredAt)) return null;
+		return result.lastFiredAt;
+	}
+	saveLastFiredAt(ctx, persister, lastFiredAt) {
+		safeInvokeCallback({
+			fn: () => persister.save({ lastFiredAt }),
+			onError: (error) => {
+				ctx.log.warn({
+					action: "time.state.save.error",
+					message: safeErrorMessage({ error: safeNormalizeError({ value: error }) }),
+					error
+				});
+			}
+		});
+	}
 	safeMessage(ctx, tick) {
 		const message = this.options.message;
 		if (!message) return {};
@@ -316,4 +618,4 @@ var FlumeTimeSource = class extends FlumeSource {
 	}
 };
 //#endregion
-export { FlumeTimeSource, flumeCronNext, parseCron };
+export { FlumeTimeSource, flumeCollectCatchupMatches, flumeCronNext, parseCron };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interactive-inc/flume",
-  "version": "0.9.4",
+  "version": "0.10.1",
   "description": "Unified notification listener for Discord, Slack, and GitHub. Raw WebSocket + fetch + Zod. No SDK dependencies.",
   "keywords": [
     "discord",