@interactive-inc/flume 0.9.4 → 0.10.1

package/dist/flume-source.d.ts

@@ -24,9 +24,9 @@ declare class FlumeLogger {
 //#region lib/discord/discord-gateway-message-schema.d.ts
 declare const FlumeGatewayMessageSchema: z.ZodObject<{
   op: z.ZodNumber;
-  d: z.ZodUnknown;
-  s: z.ZodNullable<z.ZodNumber>;
-  t: z.ZodNullable<z.ZodString>;
+  d: z.ZodOptional<z.ZodUnknown>;
+  s: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+  t: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 //#endregion
 //#region lib/github/github-notification-schema.d.ts
@@ -103,7 +103,15 @@ type FlumeTimeEvent = {
   meta: Record<string, string>;
   receivedAt: number;
 };
-type FlumeEvent = FlumeDiscordEvent | FlumeSlackEvent | FlumeGitHubEvent | FlumeTimeEvent;
+type FlumeCustomEvent = {
+  source: "custom";
+  sourceName: string;
+  type: string;
+  data: Record<string, unknown>;
+  meta: Record<string, string>;
+  receivedAt: number;
+};
+type FlumeEvent = FlumeDiscordEvent | FlumeSlackEvent | FlumeGitHubEvent | FlumeTimeEvent | FlumeCustomEvent;
 type FlumeEventHandler = (event: FlumeEvent) => void | Promise<void>;
 type FlumeStreamItem = {
   kind: "event";
@@ -112,7 +120,16 @@ type FlumeStreamItem = {
   kind: "log";
   log: FlumeLog;
 };
-type FlumeStreamHandler = (item: FlumeStreamItem) => void;
+type FlumeStreamHandler = (item: FlumeStreamItem) => unknown | Promise<unknown>;
+/**
+ * `FlumeConfluence` が onEvent に渡す item。Flume 単体の `FlumeStreamItem` に
+ * `groupId` (`add(id, ...)` で渡したグループ識別子) をスタンプしたもの。
+ * 合流ストリームの provenance を呼び出し側で復元する必要がなくなる
+ */
+type FlumeConfluenceItem = FlumeStreamItem & {
+  readonly groupId: string;
+};
+type FlumeConfluenceItemHandler = (item: FlumeConfluenceItem) => unknown | Promise<unknown>;
 type FlumeStreamOverflow = "drop-oldest" | "drop-newest";
 type FlumeStreamOptions = {
   /** バッファ上限 (既定 1000)。consumer が遅れて溢れたら onOverflow に従う */buffer?: number; /** バッファ溢れ時の方針 (既定 "drop-oldest") */
@@ -164,17 +181,28 @@ type FlumeSourceStartContext = {
   onStatus?: FlumeSourceLocalStatusHandler;
   reconnect: FlumeReconnectConfig | null;
   /**
-   * Flume.start() に渡された signal をそのまま転送する。
-   * source 実装が自前で `fetch(url, { signal })` / `setTimeout` cancel / WS close を
-   * host abort 経由で発火させたい時に使う (Flume 自身は最外殻で runClose を駆動するので
-   * source は signal を無視しても動作的には停止する — 自然な伝播パスが欲しい場合のみ)。
-   * Flume.options.signal が未設定なら省略される。
+   * Flume に渡された signal をそのまま転送する。
+   * connect 中の abort は `FlumeSource` 基底クラスが購読して `stop()` を発火する
+   * (進行中の接続を中断して `Flume.open()` を解放する)。connect 完了後の abort は
+   * FlumeRunning が runClose を駆動する。source 実装が自前で `fetch(url, { signal })`
+   * などへ伝播させたい場合にも使える。Flume.options.signal が未設定なら省略される。
    */
   signal?: AbortSignal;
 };
 type FlumeDiscordSourceOptions = {
   token: string;
+  /**
+   * Gateway intent ビットフラグ。既定は Guilds | GuildMessages | DirectMessages。
+   * message の `content` 本文が必要な場合は privileged intent の `MessageContent` を
+   * Developer Portal で有効化した上で明示的に足す (未承認のまま足すと close 4014 で終端する)
+   */
   intents?: number;
+  /**
+   * WebSocket open から READY/RESUMED までの上限 (ms)。既定 30_000。
+   * HELLO が来ない half-open socket で `connect()` (ひいては `Flume.open()`) が
+   * 永久にハングするのを防ぐ
+   */
+  handshakeTimeoutMs?: number;
 };
 type FlumeSlackSourceOptions = {
   appToken: string;
@@ -189,6 +217,12 @@ type FlumeSlackSourceOptions = {
    * inbound frame.
    */
   idleTimeoutMs?: number | null;
+  /**
+   * WebSocket open から hello 受信までの上限 (ms)。既定 30_000。
+   * hello が来ない half-open socket で `connect()` (ひいては `Flume.open()`) が
+   * 永久にハングするのを防ぐ
+   */
+  handshakeTimeoutMs?: number;
 };
 type FlumeGitHubSourceOptions = {
   token: string;
@@ -207,9 +241,43 @@ type FlumeTimeMessage = {
   data?: Record<string, unknown>;
   meta?: Record<string, string>;
 };
+/**
+ * 起動 / 終了をまたいだ状態を 1 つ載せる純粋な DI ポート。flume 内部で fs / db / network を
+ * 触らないように、I/O の場所と方式は host が決める。load の失敗は null 復帰扱い、save の
+ * 失敗は best-effort (source 側で log するが throw しない)
+ */
+type FlumeStatePersister<S> = {
+  load(): Promise<S | null>;
+  save(state: S): Promise<void>;
+};
+/** `FlumeTimeSource` の statePersister が保存する形 */
+type FlumeTimeSourceState = {
+  readonly lastFiredAt: number;
+};
+/**
+ * `FlumeTimeSource` の起動時 catch-up 方針。statePersister が読めた lastFiredAt から
+ * 現在時刻までに過ぎ去った cron マッチを再発火するかどうかを決める。
+ *  - "off"      : 何もしない (既定。後方互換)
+ *  - "lastOnly" : 直近に過ぎ去ったマッチを 1 件だけ再発火
+ *  - "missed"   : maxWindowMs (既定 24h) 以内のすべての過ぎ去ったマッチを順に再発火
+ */
+type FlumeCatchupPolicy = {
+  readonly mode: "off";
+} | {
+  readonly mode: "lastOnly";
+} | {
+  readonly mode: "missed";
+  readonly maxWindowMs?: number;
+};
 type FlumeTimeSourceOptions = {
   /** 5 フィールド cron 式 (minute hour day-of-month month day-of-week)。壁時計 (local time) 基準 */cron: string;
   message?: (tick: FlumeTimeTick) => FlumeTimeMessage;
+  /**
+   * 起動 / 終了をまたいで `lastFiredAt` を覚えておく口。未指定なら catchup は無効化される
+   * (lastFiredAt が分からないので)。flume は fs / db を触らないので host が実装を渡す
+   */
+  statePersister?: FlumeStatePersister<FlumeTimeSourceState>; /** statePersister が読めた lastFiredAt を元に過去 tick を再発火する方針 (既定 "off") */
+  catchupPolicy?: FlumeCatchupPolicy;
 };
 type FlumeGatewayMessage = z.infer<typeof FlumeGatewayMessageSchema>;
 type FlumeSlackEnvelope = z.infer<typeof FlumeSlackEnvelopeSchema>;
@@ -224,6 +292,10 @@ type FlumeGitHubNotification = z.infer<typeof FlumeGitHubNotificationSchema>;
  * `FlumeSourceStartContext` (handler / log / deps / onStatus / reconnect) を
  * `start()` で受け取り、subclass の `connect(ctx)` に手渡す。
  *
+ * `ctx.signal` の購読も base が行う: connect 中に abort されたら `stop()` を発火して
+ * 進行中の接続を中断する (subclass の `disconnect()` が pending な connect を解決する契約)。
+ * connect 完了後の abort は Flume / FlumeRunning が runClose 経由で駆動する。
+ *
  * subclass のテンプレート:
  *
  * ```ts
@@ -247,11 +319,19 @@ declare abstract class FlumeSource {
   abstract readonly name: string;
   private consumed;
   private stopped;
+  private stopPromise;
   private ctx;
   private statusEmitter;
+  private abortHandler;
   private readonly queue;
   start(ctx: FlumeSourceStartContext): Promise<Error | null>;
-  stop(): Promise<void>;
+  /**
+   * 冪等。`disconnect()` の throw は捕捉して `Error` として返す (公開境界から reject しない)。
+   * Flume.runClose / Flume.rollback は戻り値の Error を `flume.close.failed` /
+   * `flume.rollback.failed` として firehose に流す
+   */
+  stop(): Promise<Error | null>;
+  private runStop;
   status(): FlumeStatus;
   /**
    * subclass が受信した protocol イベントを `FlumeEvent` として handler へ流す。
@@ -266,10 +346,13 @@ declare abstract class FlumeSource {
   protected get currentStatus(): FlumeStatus;
   /** subclass が start ctx を再参照したい場合 (stop 後は null) */
   protected get context(): FlumeSourceStartContext | null;
+  private isSignalAborted;
+  private attachAbortListener;
+  private detachAbortListener;
   /** protocol 接続。subclass 実装 */
   protected abstract connect(ctx: FlumeSourceStartContext): Promise<Error | null>;
   /** protocol 切断。subclass 実装。base が `stop()` 内で必ず呼ぶ */
   protected abstract disconnect(): Promise<void> | void;
 }
 //#endregion
-export { FlumeStreamOverflow as A, FlumeSourceName as C, FlumeStreamHandler as D, FlumeStatus as E, FlumeTimerHandle as F, FlumeLogger as I, FlumeTimeMessage as M, FlumeTimeSourceOptions as N, FlumeStreamItem as O, FlumeTimeTick as P, FlumeSourceLocalStatusHandler as S, FlumeSourceStatus as T, FlumeRuntimeDeps as _, FlumeEvent as a, FlumeSlackEvent as b, FlumeGitHubEvent as c, FlumeLog as d, FlumeLogHandler as f, FlumeReconnectOptions as g, FlumeReconnectConfig as h, FlumeErrorHandler as i, FlumeTimeEvent as j, FlumeStreamOptions as k, FlumeGitHubNotification as l, FlumeLogLevel as m, FlumeDiscordEvent as n, FlumeEventHandler as o, FlumeLogInput as p, FlumeDiscordSourceOptions as r, FlumeGatewayMessage as s, FlumeSource as t, FlumeGitHubSourceOptions as u, FlumeSlackConnectionResponse as v, FlumeSourceStartContext as w, FlumeSlackSourceOptions as x, FlumeSlackEnvelope as y };
+export { FlumeStatePersister as A, FlumeTimeTick as B, FlumeSlackEnvelope as C, FlumeSourceName as D, FlumeSourceLocalStatusHandler as E, FlumeStreamOverflow as F, FlumeLogger as H, FlumeTimeEvent as I, FlumeTimeMessage as L, FlumeStreamHandler as M, FlumeStreamItem as N, FlumeSourceStartContext as O, FlumeStreamOptions as P, FlumeTimeSourceOptions as R, FlumeSlackConnectionResponse as S, FlumeSlackSourceOptions as T, FlumeTimerHandle as V, FlumeLogInput as _, FlumeCustomEvent as a, FlumeReconnectOptions as b, FlumeErrorHandler as c, FlumeGatewayMessage as d, FlumeGitHubEvent as f, FlumeLogHandler as g, FlumeLog as h, FlumeConfluenceItemHandler as i, FlumeStatus as j, FlumeSourceStatus as k, FlumeEvent as l, FlumeGitHubSourceOptions as m, FlumeCatchupPolicy as n, FlumeDiscordEvent as o, FlumeGitHubNotification as p, FlumeConfluenceItem as r, FlumeDiscordSourceOptions as s, FlumeSource as t, FlumeEventHandler as u, FlumeLogLevel as v, FlumeSlackEvent as w, FlumeRuntimeDeps as x, FlumeReconnectConfig as y, FlumeTimeSourceState as z };

package/dist/flume-source.js

@@ -2,13 +2,15 @@
 /**
 * 任意の値から人が読めるメッセージ文字列を取り出す。
 * `Error.message` getter / `Symbol.toPrimitive` / `toString` / `valueOf` が throw しても固定文字列に fallback。
-* 自身は決して throw しない
+* `instanceof` 自体が throw する値 (revoked Proxy 等) にも耐える。自身は決して throw しない
 */
 function safeErrorMessage(props) {
-	if (props.error instanceof Error) try {
-		const message = props.error.message;
-		if (typeof message === "string") return message;
-		return "<non-string error message>";
+	try {
+		if (props.error instanceof Error) {
+			const message = props.error.message;
+			if (typeof message === "string") return message;
+			return "<non-string error message>";
+		}
 	} catch {
 		return "<unreadable error message>";
 	}
@@ -23,10 +25,13 @@ function safeErrorMessage(props) {
 /**
 * 任意の値を `Error` インスタンスへ正規化する。すでに Error ならそのまま返し、
 * それ以外は `safeErrorMessage` で安全な文字列化を経由して new Error する。
-* Error コンストラクタ自体が throw する病的環境でも fallback を返し、決して throw しない
+* `instanceof` 自体が throw する値 (revoked Proxy 等) や Error コンストラクタが throw する
+* 病的環境でも fallback を返し、決して throw しない
 */
 function safeNormalizeError(props) {
-	if (props.value instanceof Error) return props.value;
+	try {
+		if (props.value instanceof Error) return props.value;
+	} catch {}
 	const message = safeErrorMessage({ error: props.value });
 	try {
 		return new Error(message);
@@ -43,10 +48,16 @@ function safeNormalizeError(props) {
 }
 //#endregion
 //#region lib/utils/attempt.ts
+function isThenable(value) {
+	if (typeof value !== "object" && typeof value !== "function") return false;
+	if (value === null) return false;
+	return "then" in value && typeof value.then === "function";
+}
 function attempt(fn) {
 	try {
 		const result = fn();
 		if (result instanceof Promise) return result.catch((err) => safeNormalizeError({ value: err }));
+		if (isThenable(result)) return Promise.resolve(result).then((value) => value, (err) => safeNormalizeError({ value: err }));
 		return result;
 	} catch (err) {
 		return safeNormalizeError({ value: err });
@@ -73,14 +84,18 @@ var FlumeStartError = class extends Error {
 //#endregion
 //#region lib/utils/safe-now.ts
 /**
-* `deps.now()` を保護する。throw / 非数値が返った場合は 0 を返す。
+* `deps.now()` を保護する。throw / 非数値 / 非有限値が返った場合は `Date.now()` へ
+* フォールバックする (0 を返すと epoch 1970 が TTL / cron / レート計算へ伝播するため)。
+* `Date.now` 自体まで壊れている病的環境でのみ 0 を返す。
 * IO 境界のため呼び出し側はこの戻り値を信頼できる
 */
 function safeNow(props) {
 	try {
 		const value = props.deps.now();
-		if (typeof value !== "number" || !Number.isFinite(value)) return 0;
-		return value;
+		if (typeof value === "number" && Number.isFinite(value)) return value;
+	} catch {}
+	try {
+		return Date.now();
 	} catch {
 		return 0;
 	}
@@ -156,6 +171,60 @@ function safeInvokeCallback(props) {
 	}
 }
 //#endregion
+//#region lib/utils/serial-queue.ts
+/**
+* 投入順を保ったまま task を直列実行する。各 task は前の完了を待ってから走る。
+* task が throw しても後続には伝播しない (キュー自体は止まらない)。
+* maxDepth を超えた場合は新規 task を drop し onOverflow に通知。
+* cancel() 後は add() が no-op になり、既に積まれた未実行 task も実行せずに流れ落ちる。
+* drain() は待機中に追加された task も含めてキューが空になるまで待つ
+*/
+var FlumeSerialQueue = class {
+	props;
+	chain = Promise.resolve();
+	depth = 0;
+	cancelled = false;
+	constructor(props = {}) {
+		this.props = props;
+	}
+	add(task) {
+		if (this.cancelled) return Promise.resolve();
+		if (this.props.maxDepth !== void 0 && this.depth >= this.props.maxDepth) {
+			this.props.onOverflow?.({
+				dropped: 1,
+				depth: this.depth
+			});
+			return Promise.resolve();
+		}
+		this.depth++;
+		const completion = this.chain.then(async () => {
+			try {
+				if (!this.cancelled) await task();
+			} catch {} finally {
+				this.depth--;
+			}
+		});
+		this.chain = completion;
+		return completion;
+	}
+	async drain() {
+		while (true) {
+			const current = this.chain;
+			await current;
+			if (this.chain === current) return;
+		}
+	}
+	cancel() {
+		this.cancelled = true;
+	}
+	size() {
+		return this.depth;
+	}
+	isCancelled() {
+		return this.cancelled;
+	}
+};
+//#endregion
 //#region lib/source-helpers/flume-status-emitter.ts
 /**
 * Source の `currentStatus` と `onStatus` 通知を集約する。
@@ -203,55 +272,6 @@ var FlumeStatusEmitter = class {
 	}
 };
 //#endregion
-//#region lib/utils/serial-queue.ts
-/**
-* 投入順を保ったまま task を直列実行する。各 task は前の完了を待ってから走る。
-* task が throw しても後続には伝播しない (キュー自体は止まらない)。
-* maxDepth を超えた場合は新規 task を drop し onOverflow に通知。
-* cancel() 後の add() は no-op となり drain() は即時 resolve する
-*/
-var FlumeSerialQueue = class {
-	props;
-	chain = Promise.resolve();
-	depth = 0;
-	cancelled = false;
-	constructor(props = {}) {
-		this.props = props;
-	}
-	add(task) {
-		if (this.cancelled) return;
-		if (this.props.maxDepth !== void 0 && this.depth >= this.props.maxDepth) {
-			this.props.onOverflow?.({
-				dropped: 1,
-				depth: this.depth
-			});
-			return;
-		}
-		this.depth++;
-		this.chain = this.chain.then(async () => {
-			try {
-				await task();
-			} catch {} finally {
-				this.depth--;
-			}
-		});
-	}
-	async drain() {
-		await this.chain;
-	}
-	cancel() {
-		this.cancelled = true;
-		this.depth = 0;
-		this.chain = Promise.resolve();
-	}
-	size() {
-		return this.depth;
-	}
-	isCancelled() {
-		return this.cancelled;
-	}
-};
-//#endregion
 //#region lib/flume-source.ts
 /**
 * 全 Source の基底クラス。protocol 固有のロジック (`connect` / `disconnect`) のみ
@@ -260,6 +280,10 @@ var FlumeSerialQueue = class {
 * `FlumeSourceStartContext` (handler / log / deps / onStatus / reconnect) を
 * `start()` で受け取り、subclass の `connect(ctx)` に手渡す。
 *
+* `ctx.signal` の購読も base が行う: connect 中に abort されたら `stop()` を発火して
+* 進行中の接続を中断する (subclass の `disconnect()` が pending な connect を解決する契約)。
+* connect 完了後の abort は Flume / FlumeRunning が runClose 経由で駆動する。
+*
 * subclass のテンプレート:
 *
 * ```ts
@@ -282,29 +306,45 @@ var FlumeSerialQueue = class {
 var FlumeSource = class {
 	consumed = false;
 	stopped = false;
+	stopPromise = null;
 	ctx = null;
 	statusEmitter = null;
+	abortHandler = null;
 	queue = new FlumeSerialQueue();
 	async start(ctx) {
 		if (this.consumed) return new FlumeStartError(`${this.name}: already started`);
+		if (this.stopped) return new FlumeStartError(`${this.name}: already stopped`);
 		this.consumed = true;
 		this.ctx = ctx;
 		this.statusEmitter = new FlumeStatusEmitter({
 			log: ctx.log,
 			onStatus: ctx.onStatus
 		});
-		return await this.connect(ctx);
+		if (this.isSignalAborted(ctx)) return new FlumeStartError(`${this.name}: aborted before connect`);
+		this.attachAbortListener(ctx);
+		const result = await attempt(async () => await this.connect(ctx));
+		this.detachAbortListener(ctx);
+		return result instanceof Error ? safeNormalizeError({ value: result }) : result;
 	}
+	/**
+	* 冪等。`disconnect()` の throw は捕捉して `Error` として返す (公開境界から reject しない)。
+	* Flume.runClose / Flume.rollback は戻り値の Error を `flume.close.failed` /
+	* `flume.rollback.failed` として firehose に流す
+	*/
 	async stop() {
-		if (this.stopped) return;
+		if (this.stopPromise !== null) return this.stopPromise;
 		this.stopped = true;
-		try {
+		this.stopPromise = this.runStop();
+		return this.stopPromise;
+	}
+	async runStop() {
+		const disconnectResult = await attempt(async () => {
 			await this.disconnect();
-		} finally {
-			await this.queue.drain();
-			this.statusEmitter?.set("disconnected");
-			this.ctx = null;
-		}
+		});
+		await this.queue.drain();
+		this.statusEmitter?.set("disconnected");
+		this.ctx = null;
+		return disconnectResult instanceof Error ? disconnectResult : null;
 	}
 	status() {
 		return this.statusEmitter?.value ?? "disconnected";
@@ -339,6 +379,39 @@ var FlumeSource = class {
 	get context() {
 		return this.ctx;
 	}
+	isSignalAborted(ctx) {
+		const signal = ctx.signal;
+		if (!signal) return false;
+		const result = attempt(() => signal.aborted === true);
+		return result instanceof Error ? true : result;
+	}
+	attachAbortListener(ctx) {
+		const signal = ctx.signal;
+		if (!signal) return;
+		const handler = () => {
+			attempt(async () => {
+				await this.stop();
+			});
+		};
+		const result = attempt(() => signal.addEventListener("abort", handler, { once: true }));
+		if (result instanceof Error) {
+			ctx.log.warn({
+				action: "signal.addListener.failed",
+				message: safeErrorMessage({ error: result }),
+				error: result
+			});
+			return;
+		}
+		this.abortHandler = handler;
+	}
+	detachAbortListener(ctx) {
+		const handler = this.abortHandler;
+		if (!handler) return;
+		this.abortHandler = null;
+		const signal = ctx.signal;
+		if (!signal) return;
+		attempt(() => signal.removeEventListener("abort", handler));
+	}
 };
 //#endregion
-export { FlumeStartError as a, safeNormalizeError as c, safeNow as i, safeErrorMessage as l, safeInvokeCallback as n, FlumeParseError as o, FlumeLogger as r, attempt as s, FlumeSource as t };
+export { safeNow as a, attempt as c, FlumeLogger as i, safeNormalizeError as l, FlumeSerialQueue as n, FlumeStartError as o, safeInvokeCallback as r, FlumeParseError as s, FlumeSource as t, safeErrorMessage as u };

package/dist/github.d.ts

@@ -1,4 +1,4 @@
-import { l as FlumeGitHubNotification, t as FlumeSource, u as FlumeGitHubSourceOptions, w as FlumeSourceStartContext } from "./flume-source.js";
+import { O as FlumeSourceStartContext, m as FlumeGitHubSourceOptions, p as FlumeGitHubNotification, t as FlumeSource } from "./flume-source.js";
 
 //#region lib/github/github-source.d.ts
 declare class FlumeGitHubSource extends FlumeSource {
@@ -8,6 +8,10 @@ declare class FlumeGitHubSource extends FlumeSource {
   constructor(options: FlumeGitHubSourceOptions);
   protected connect(ctx: FlumeSourceStartContext): Promise<Error | null>;
   protected disconnect(): void;
+  /**
+   * pollInterval が非数値・非有限・0 以下の場合は既定値へフォールバックする
+   */
+  private getPollIntervalSec;
   private handleNotifications;
   private safeExtractMeta;
 }