@interactive-inc/flume 0.9.4 → 0.10.1

package/dist/slack.js

@@ -1,4 +1,4 @@
-import { a as FlumeStartError, c as safeNormalizeError, i as safeNow, l as safeErrorMessage, 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, s as FlumeParseError, t as FlumeSource, u as safeErrorMessage } from "./flume-source.js";
 import { t as FlumeConnectionError } from "./connection-error.js";
 import { t as FlumeHttpError } from "./http-error.js";
 import { n as scheduleFlumeReconnect, r as FlumeReconnector, t as safeStringify } from "./safe-stringify.js";
@@ -10,11 +10,12 @@ import { z } from "zod/v4";
 function flumeExtractSlackMeta(envelope) {
 	const meta = { event_type: envelope.type };
 	const eventPayload = isRecord(envelope.payload.event) ? envelope.payload.event : null;
-	if (!eventPayload) return meta;
-	if (typeof eventPayload.channel === "string") meta.channel_id = eventPayload.channel;
-	if (typeof eventPayload.user === "string") meta.user_id = eventPayload.user;
-	if (typeof eventPayload.thread_ts === "string") meta.thread_ts = eventPayload.thread_ts;
-	if (typeof eventPayload.type === "string") meta.slack_event_type = eventPayload.type;
+	if (typeof envelope.payload.channel_id === "string") meta.channel_id = envelope.payload.channel_id;
+	else if (eventPayload && typeof eventPayload.channel === "string") meta.channel_id = eventPayload.channel;
+	if (typeof envelope.payload.user_id === "string") meta.user_id = envelope.payload.user_id;
+	else if (eventPayload && typeof eventPayload.user === "string") meta.user_id = eventPayload.user;
+	if (eventPayload && typeof eventPayload.thread_ts === "string") meta.thread_ts = eventPayload.thread_ts;
+	if (eventPayload && typeof eventPayload.type === "string") meta.slack_event_type = eventPayload.type;
 	return meta;
 }
 //#endregion
@@ -65,6 +66,22 @@ const FlumeSlackConnectionResponseSchema = z.object({
 	error: z.string().optional()
 });
 //#endregion
+//#region lib/slack/read-slack-retry-after-ms.ts
+/**
+* `Retry-After` ヘッダを ms で読む。整数秒表記のみ受理し、HTTP-date 形式・非数値・
+* headers 欠落 (モック Response 等) はすべて null。throw しない
+*/
+function readSlackRetryAfterMs(props) {
+	const raw = attempt(() => props.response.headers.get("retry-after"));
+	if (raw instanceof Error) return null;
+	if (typeof raw !== "string") return null;
+	const trimmed = raw.trim();
+	if (!/^\d+$/.test(trimmed)) return null;
+	const seconds = Number(trimmed);
+	if (!Number.isFinite(seconds)) return null;
+	return seconds * 1e3;
+}
+//#endregion
 //#region lib/slack/obtain-slack-url.ts
 const URL_ENDPOINT = "https://slack.com/api/apps.connections.open";
 async function obtainSlackUrl(props) {
@@ -99,6 +116,19 @@ async function obtainSlackUrl(props) {
 			url: URL_ENDPOINT
 		}
 	});
+	const retryAfterMs = readSlackRetryAfterMs({ response });
+	if (response.status === 429) {
+		log.warn({
+			action: "http.rate-limited",
+			message: `apps.connections.open: rate limited (429), retry-after ${retryAfterMs ?? "unknown"}ms`,
+			detail: { retryAfterMs }
+		});
+		return new FlumeHttpError({
+			message: "apps.connections.open: rate limited (429)",
+			status: response.status,
+			retryAfterMs
+		});
+	}
 	const text = await safeReadText({
 		response,
 		context: "apps.connections.open"
@@ -121,7 +151,8 @@ async function obtainSlackUrl(props) {
 		return new FlumeHttpError({
 			message: `apps.connections.open: invalid JSON body`,
 			status: response.status,
-			cause: json
+			cause: json,
+			retryAfterMs
 		});
 	}
 	const peek = isRecord(json) ? json : {};
@@ -146,17 +177,21 @@ async function obtainSlackUrl(props) {
 		return new FlumeHttpError({
 			message: "apps.connections.open: invalid response shape",
 			status: response.status,
-			cause: parsed.error
+			cause: parsed.error,
+			retryAfterMs
 		});
 	}
 	if (!parsed.data.ok || !parsed.data.url) {
 		log.warn({
 			action: "slack.api.error",
-			message: `apps.connections.open failed: ${parsed.data.error ?? "no url"}`
+			message: `apps.connections.open failed: ${parsed.data.error ?? "no url"}`,
+			detail: { code: parsed.data.error ?? null }
 		});
 		return new FlumeHttpError({
 			message: `apps.connections.open failed: ${parsed.data.error ?? "no url"}`,
-			status: response.status
+			status: response.status,
+			code: parsed.data.error ?? null,
+			retryAfterMs
 		});
 	}
 	log.info({
@@ -178,6 +213,12 @@ const FlumeSlackEnvelopeSchema = z.object({
 //#endregion
 //#region lib/slack/slack-socket-mode.ts
 const IDLE_CHECK_INTERVAL_MS = 15e3;
+const HANDSHAKE_TIMEOUT_DEFAULT_MS = 3e4;
+/**
+* 強制 close 後に close イベントの配達を待つ猶予。silently-dropped な NAT / proxy 経路では
+* close が永遠に来ないことがあり、その場合 teardown を合成して reconnect へ渡す
+*/
+const CLOSE_FALLBACK_MS = 5e3;
 const WS_OPEN = 1;
 /**
 * Slack Socket Mode の最小 WebSocket 実装。`apps.connections.open` で URL を取得し
@@ -194,6 +235,9 @@ var FlumeSlackSocketMode = class {
 	pendingResolved = false;
 	lastFrameAt = 0;
 	idleWatchdog = null;
+	handshakeTimer = null;
+	closeFallbackTimer = null;
+	closeHandled = false;
 	constructor(props) {
 		this.props = props;
 		this.log = new FlumeLogger({
@@ -253,13 +297,15 @@ var FlumeSlackSocketMode = class {
 		});
 		this.isStoppedFlag = true;
 		this.disarmIdleWatchdog();
+		this.clearCloseFallback();
+		this.completeConnect(new FlumeConnectionError("stopped before hello"));
 		this.closeSocket(this.ws);
 		this.ws = null;
 	}
 	armIdleWatchdog() {
 		this.disarmIdleWatchdog();
 		const idleLimit = this.props.idleTimeoutMs;
-		if (idleLimit === null || idleLimit === void 0 || idleLimit <= 0) return;
+		if (typeof idleLimit !== "number" || !Number.isFinite(idleLimit) || idleLimit <= 0) return;
 		const handle = attempt(() => this.props.deps.setInterval(() => this.checkIdle(idleLimit), IDLE_CHECK_INTERVAL_MS));
 		if (handle instanceof Error) {
 			this.log.error({
@@ -284,7 +330,7 @@ var FlumeSlackSocketMode = class {
 	}
 	checkIdle(idleLimit) {
 		if (!this.hasConnected || this.isStoppedFlag) return;
-		const elapsed = this.props.deps.now() - this.lastFrameAt;
+		const elapsed = safeNow({ deps: this.props.deps }) - this.lastFrameAt;
 		if (elapsed < idleLimit) return;
 		this.log.warn({
 			action: "idle.timeout",
@@ -295,7 +341,7 @@ var FlumeSlackSocketMode = class {
 			}
 		});
 		this.disarmIdleWatchdog();
-		this.closeSocket(this.ws);
+		this.forceClose();
 	}
 	isConnected() {
 		return this.ws !== null && this.ws.readyState === WS_OPEN;
@@ -313,6 +359,7 @@ var FlumeSlackSocketMode = class {
 		}
 		this.pendingResolved = false;
 		this.hasConnected = false;
+		this.closeHandled = false;
 		return new Promise((resolve) => {
 			this.pendingResolve = resolve;
 			const socketResult = attempt(() => new WS(url));
@@ -342,17 +389,121 @@ var FlumeSlackSocketMode = class {
 					message: safeErrorMessage({ error }),
 					error
 				});
+				this.closeSocket(socket);
 				this.ws = null;
 				this.pendingResolved = true;
 				resolve(error);
+				return;
 			}
+			this.armHandshakeTimer();
 		});
 	}
 	completeConnect(error) {
+		this.clearHandshakeTimer();
 		if (this.pendingResolved || !this.pendingResolve) return;
 		this.pendingResolved = true;
 		this.pendingResolve(error);
 	}
+	armHandshakeTimer() {
+		const configured = this.props.handshakeTimeoutMs;
+		const timeoutMs = typeof configured === "number" && Number.isFinite(configured) && configured > 0 ? configured : HANDSHAKE_TIMEOUT_DEFAULT_MS;
+		const handle = attempt(() => this.props.deps.setTimeout(() => this.onHandshakeTimeout(timeoutMs), timeoutMs));
+		if (handle instanceof Error) {
+			const error = new FlumeConnectionError(`handshake timer scheduling failed: ${safeErrorMessage({ error: handle })}`, { cause: handle });
+			this.log.error({
+				action: "handshake.timer.schedule.error",
+				message: safeErrorMessage({ error }),
+				error
+			});
+			this.completeConnect(error);
+			this.forceClose();
+			return;
+		}
+		this.handshakeTimer = handle;
+	}
+	clearHandshakeTimer() {
+		if (this.handshakeTimer === null) return;
+		const handle = this.handshakeTimer;
+		this.handshakeTimer = null;
+		const result = attempt(() => this.props.deps.clearTimeout(handle));
+		if (result instanceof Error) this.log.error({
+			action: "handshake.timer.clear.error",
+			message: safeErrorMessage({ error: result }),
+			error: result
+		});
+	}
+	onHandshakeTimeout(timeoutMs) {
+		this.handshakeTimer = null;
+		if (this.pendingResolved || this.isStoppedFlag) return;
+		const error = new FlumeConnectionError(`handshake timeout: no hello within ${timeoutMs}ms — force-closing socket`);
+		this.log.error({
+			action: "handshake.timeout",
+			message: safeErrorMessage({ error }),
+			error,
+			detail: { timeoutMs }
+		});
+		this.completeConnect(error);
+		this.forceClose();
+	}
+	/**
+	* watchdog / handshake timeout / server disconnect 指示による強制 close の入口。
+	* close イベントが配達されない dead pipe に備え、close() より先に fallback timer を張る
+	*/
+	forceClose() {
+		const socket = this.ws;
+		if (socket === null) return;
+		this.armCloseFallback();
+		this.closeSocket(socket);
+	}
+	armCloseFallback() {
+		if (this.closeFallbackTimer !== null) return;
+		const handle = attempt(() => this.props.deps.setTimeout(() => this.onCloseFallback(), CLOSE_FALLBACK_MS));
+		if (handle instanceof Error) {
+			this.log.error({
+				action: "ws.close.fallback.schedule.error",
+				message: safeErrorMessage({ error: handle }),
+				error: handle
+			});
+			this.onCloseFallback();
+			return;
+		}
+		this.closeFallbackTimer = handle;
+	}
+	clearCloseFallback() {
+		if (this.closeFallbackTimer === null) return;
+		const handle = this.closeFallbackTimer;
+		this.closeFallbackTimer = null;
+		const result = attempt(() => this.props.deps.clearTimeout(handle));
+		if (result instanceof Error) this.log.error({
+			action: "ws.close.fallback.clear.error",
+			message: safeErrorMessage({ error: result }),
+			error: result
+		});
+	}
+	onCloseFallback() {
+		this.closeFallbackTimer = null;
+		if (this.closeHandled || this.isStoppedFlag) return;
+		this.log.warn({
+			action: "ws.close.fallback",
+			message: `close event not delivered within ${CLOSE_FALLBACK_MS}ms — synthesizing teardown`
+		});
+		this.settleClose({ code: null });
+	}
+	/**
+	* close teardown の唯一の入口。実 close イベントと fallback の合成 close が競合しても
+	* `closeHandled` で一度だけ実行する
+	*/
+	settleClose(props) {
+		if (this.closeHandled) return;
+		this.closeHandled = true;
+		this.clearCloseFallback();
+		this.disarmIdleWatchdog();
+		this.ws = null;
+		if (this.hasConnected) this.props.onDisconnected();
+		if (this.pendingResolved) return;
+		const error = props.code === null ? new FlumeConnectionError("WebSocket closed before hello (code=none)") : new FlumeConnectionError(`WebSocket closed before hello (code=${props.code})`, { code: props.code });
+		this.completeConnect(error);
+	}
 	safeOnMessage(ev, socket) {
 		const r = attempt(() => this.onMessage(String(ev.data), socket));
 		if (r instanceof Error) this.log.error({
@@ -378,6 +529,7 @@ var FlumeSlackSocketMode = class {
 		});
 	}
 	onMessage(raw, socket) {
+		this.lastFrameAt = safeNow({ deps: this.props.deps });
 		if (this.isStoppedFlag) return;
 		const json = safeJsonParse(raw);
 		if (json instanceof FlumeParseError) {
@@ -402,7 +554,6 @@ var FlumeSlackSocketMode = class {
 			message: `type=${typeof json.type === "string" ? json.type : "-"} length=${raw.length}`,
 			detail: { length: raw.length }
 		});
-		this.lastFrameAt = this.props.deps.now();
 		if (json.type === "hello") {
 			this.log.info({
 				action: "socket.hello",
@@ -421,7 +572,7 @@ var FlumeSlackSocketMode = class {
 				message: `reason=${reason}`,
 				detail: { reason }
 			});
-			this.closeSocket(socket);
+			this.forceClose();
 			return;
 		}
 		if (typeof json.envelope_id === "string") {
@@ -466,13 +617,14 @@ var FlumeSlackSocketMode = class {
 				reason: ev.reason
 			}
 		});
-		this.disarmIdleWatchdog();
-		this.ws = null;
-		if (this.hasConnected) this.props.onDisconnected();
-		if (!this.pendingResolved) {
-			const error = new FlumeConnectionError(`WebSocket closed before hello (code=${ev.code})`, { code: ev.code });
-			this.completeConnect(error);
+		if (this.closeHandled) {
+			this.log.debug({
+				action: "ws.close.late",
+				message: "close event arrived after synthesized teardown, ignoring"
+			});
+			return;
 		}
+		this.settleClose({ code: ev.code });
 	}
 	onError() {
 		const error = new FlumeConnectionError("WebSocket connection error");
@@ -525,6 +677,19 @@ var FlumeSlackSocketMode = class {
 //#region lib/slack/slack-source.ts
 const SEEN_CACHE_MAX = 1024;
 const SEEN_CACHE_TTL_MS = 300 * 1e3;
+/**
+* `apps.connections.open` が返す恒久エラー。トークンが無効な状態で再接続しても
+* 回復しないため、reconnect を打ち切って呼び出し側へエラーを返す
+*/
+const TERMINAL_SLACK_ERROR_CODES = new Set([
+	"invalid_auth",
+	"account_inactive",
+	"token_revoked",
+	"not_authed",
+	"not_allowed_token_type",
+	"token_expired",
+	"missing_scope"
+]);
 var FlumeSlackSource = class extends FlumeSource {
 	options;
 	name = "slack";
@@ -587,9 +752,10 @@ var FlumeSlackSource = class extends FlumeSource {
 	}
 	async connectInternal(ctx) {
 		this.setStatus("connecting");
-		this.socket = new FlumeSlackSocketMode({
+		const socket = new FlumeSlackSocketMode({
 			appToken: this.options.appToken,
 			idleTimeoutMs: this.options.idleTimeoutMs,
+			handshakeTimeoutMs: this.options.handshakeTimeoutMs,
 			onLog: ctx.log.handler,
 			deps: ctx.deps,
 			onMessage: (envelope) => this.handleMessage(ctx, envelope),
@@ -602,43 +768,64 @@ var FlumeSlackSource = class extends FlumeSource {
 				this.setStatus("connected");
 			},
 			onDisconnected: () => {
-				if (this.socket?.isStopped) {
+				if (socket.isStopped) {
 					this.setStatus("disconnected");
 					return;
 				}
 				this.scheduleReconnect(ctx);
 			}
 		});
-		const error = await this.socket.connect({ signal: this.internalController?.signal });
+		this.socket = socket;
+		const error = await socket.connect({ signal: this.internalController?.signal });
 		if (error instanceof Error) {
 			ctx.log.error({
 				action: "connect.failed",
 				message: safeErrorMessage({ error }),
 				error
 			});
-			if (this.socket.isStopped || !this.reconnector || this.reconnector.aborted) {
+			if (this.isTerminalSlackError(error)) {
+				ctx.log.error({
+					action: "reconnect.terminal",
+					message: `permanent Slack API error, not reconnecting: ${safeErrorMessage({ error })}`,
+					error
+				});
+				this.setStatus("disconnected");
+				return error;
+			}
+			if (socket.isStopped || !this.reconnector || this.reconnector.aborted) {
 				this.setStatus("disconnected");
 				return error;
 			}
-			this.scheduleReconnect(ctx);
+			this.scheduleReconnect(ctx, this.minRetryDelayMs(error));
 		}
 		return null;
 	}
+	isTerminalSlackError(error) {
+		if (!(error instanceof FlumeHttpError)) return false;
+		if (error.code === null) return false;
+		return TERMINAL_SLACK_ERROR_CODES.has(error.code);
+	}
+	minRetryDelayMs(error) {
+		if (!(error instanceof FlumeHttpError)) return void 0;
+		return error.retryAfterMs ?? void 0;
+	}
 	handleMessage(ctx, envelope) {
 		const seen = this.seen;
 		if (!seen) return;
-		if (seen.has(envelope.envelope_id)) {
+		const dedupKey = this.toDedupKey(envelope);
+		if (seen.has(dedupKey)) {
 			ctx.log.debug({
 				action: "dedup.skip",
-				message: `duplicate envelope_id=${envelope.envelope_id}`,
+				message: `duplicate key=${dedupKey}`,
 				detail: {
+					dedup_key: dedupKey,
 					envelope_id: envelope.envelope_id,
 					retry_attempt: envelope.retry_attempt
 				}
 			});
 			return;
 		}
-		seen.add(envelope.envelope_id);
+		seen.add(dedupKey);
 		seen.trim();
 		this.emit({
 			source: "slack",
@@ -648,6 +835,15 @@ var FlumeSlackSource = class extends FlumeSource {
 			receivedAt: safeNow({ deps: ctx.deps })
 		});
 	}
+	/**
+	* Events API の再配送は envelope_id が変わり得るため、payload.event_id があれば
+	* そちらを重複判定キーとして優先する (再配送をまたいで安定な識別子)
+	*/
+	toDedupKey(envelope) {
+		const eventId = envelope.payload.event_id;
+		if (typeof eventId === "string" && eventId.length > 0) return eventId;
+		return envelope.envelope_id;
+	}
 	safeExtractMeta(ctx, envelope) {
 		const result = attempt(() => flumeExtractSlackMeta(envelope));
 		if (result instanceof Error) {
@@ -662,11 +858,12 @@ var FlumeSlackSource = class extends FlumeSource {
 		}
 		return result;
 	}
-	scheduleReconnect(ctx) {
+	scheduleReconnect(ctx, minDelayMs) {
 		scheduleFlumeReconnect({
 			reconnector: this.reconnector,
 			log: ctx.log,
 			setStatus: (status) => this.setStatus(status),
+			minDelayMs,
 			retry: () => {
 				this.connectInternal(ctx).catch((err) => {
 					const error = safeNormalizeError({ value: err });

package/dist/time.d.ts

@@ -1,11 +1,21 @@
-import { N as FlumeTimeSourceOptions, t as FlumeSource, w as FlumeSourceStartContext } from "./flume-source.js";
+import { O as FlumeSourceStartContext, R as FlumeTimeSourceOptions, n as FlumeCatchupPolicy, t as FlumeSource } from "./flume-source.js";
 import { t as FlumeParseError } from "./parse-error.js";
 
 //#region lib/time/time-source.d.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) 基準のため仕様とする
  */
 declare class FlumeTimeSource extends FlumeSource {
   private readonly options;
@@ -15,6 +25,12 @@ declare class FlumeTimeSource extends FlumeSource {
   protected connect(ctx: FlumeSourceStartContext): Promise<Error | null>;
   protected disconnect(): void;
   private handleTick;
+  private emitTick;
+  private runCatchup;
+  /** スケジューラが cron エラーで恒久停止した (dead-but-green を防ぐため接続状態を落とす) */
+  private handleSchedulerHalt;
+  private loadLastFiredAt;
+  private saveLastFiredAt;
   private safeMessage;
   private normalizeMeta;
 }
@@ -26,7 +42,7 @@ type FlumeCron = {
   hours: ReadonlySet<number>;
   daysOfMonth: ReadonlySet<number>;
   months: ReadonlySet<number>;
-  daysOfWeek: ReadonlySet<number>; /** day-of-month フィールドが `*` 以外か。dow と両方制限時は OR マッチ (標準 cron 準拠) */
+  daysOfWeek: ReadonlySet<number>; /** day-of-month フィールドが wildcard を含まないか。dow と両方制限時は OR マッチ */
   domRestricted: boolean;
   dowRestricted: boolean;
 };
@@ -42,4 +58,30 @@ declare function parseCron(expression: string): FlumeCron | FlumeParseError;
  */
 declare function flumeCronNext(cron: FlumeCron, afterMs: number): number | FlumeParseError;
 //#endregion
-export { type FlumeCron, FlumeTimeSource, flumeCronNext, parseCron };
+//#region lib/time/time-catchup.d.ts
+type Props = {
+  cron: FlumeCron;
+  lastFiredAt: number;
+  now: number;
+  policy: FlumeCatchupPolicy;
+};
+type FlumeCatchupMatches = {
+  matches: ReadonlyArray<number>; /** missed: 上限超過で古いマッチを切り捨てた / lastOnly: 反復上限で now まで走査しきれなかった */
+  truncated: boolean;
+};
+/**
+ * `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 本体の起動は別判断)
+ */
+declare function flumeCollectCatchupMatches(props: Props): FlumeCatchupMatches | FlumeParseError;
+//#endregion
+export { type FlumeCron, FlumeTimeSource, flumeCollectCatchupMatches, flumeCronNext, parseCron };