@interactive-inc/flume 0.10.0 → 0.11.0

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,7 @@ 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, ...)` で渡したグループ識別子) をスタンプしたもの。
@@ -121,7 +129,7 @@ type FlumeStreamHandler = (item: FlumeStreamItem) => void;
 type FlumeConfluenceItem = FlumeStreamItem & {
   readonly groupId: string;
 };
-type FlumeConfluenceItemHandler = (item: FlumeConfluenceItem) => void;
+type FlumeConfluenceItemHandler = (item: FlumeConfluenceItem) => unknown | Promise<unknown>;
 type FlumeStreamOverflow = "drop-oldest" | "drop-newest";
 type FlumeStreamOptions = {
   /** バッファ上限 (既定 1000)。consumer が遅れて溢れたら onOverflow に従う */buffer?: number; /** バッファ溢れ時の方針 (既定 "drop-oldest") */
@@ -173,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;
@@ -198,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;
@@ -219,7 +244,9 @@ type FlumeTimeMessage = {
 /**
  * 起動 / 終了をまたいだ状態を 1 つ載せる純粋な DI ポート。flume 内部で fs / db / network を
  * 触らないように、I/O の場所と方式は host が決める。load の失敗は null 復帰扱い、save の
- * 失敗は best-effort (source 側で log するが throw しない)
+ * 失敗は best-effort (source 側で log するが throw しない)。Time source は save を直列実行し、
+ * stop 時に queued save の完了を待つ。persister 内から Flume の終了を await しない。
+ * stop は load の待機を解除するが、host 側で開始した read IO 自体は中断しない。
  */
 type FlumeStatePersister<S> = {
   load(): Promise<S | null>;
@@ -267,6 +294,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
@@ -290,11 +321,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 へ流す。
@@ -305,14 +344,19 @@ declare abstract class FlumeSource {
    * subclass が protocol 状態遷移をユーザーに通知する。同一 (status, detail) の連続は冪等
    */
   protected setStatus(status: FlumeStatus, detail?: string): void;
+  /** await をまたぐ接続処理が、停止後に新しいリソースを作らないための guard。 */
+  protected get isStopped(): boolean;
   /** subclass が現在の status を読みたい場合 */
   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 { FlumeStatus as A, FlumeTimerHandle as B, FlumeSlackEvent as C, FlumeSourceStartContext as D, FlumeSourceName as E, FlumeTimeEvent as F, FlumeTimeMessage as I, FlumeTimeSourceOptions as L, FlumeStreamItem as M, FlumeStreamOptions as N, FlumeSourceStatus as O, FlumeStreamOverflow as P, FlumeTimeSourceState as R, FlumeSlackEnvelope as S, FlumeSourceLocalStatusHandler as T, FlumeLogger as V, FlumeLogLevel as _, FlumeDiscordEvent as a, FlumeRuntimeDeps as b, FlumeEvent as c, FlumeGitHubEvent as d, FlumeGitHubNotification as f, FlumeLogInput as g, FlumeLogHandler as h, FlumeConfluenceItemHandler as i, FlumeStreamHandler as j, FlumeStatePersister as k, FlumeEventHandler as l, FlumeLog as m, FlumeCatchupPolicy as n, FlumeDiscordSourceOptions as o, FlumeGitHubSourceOptions as p, FlumeConfluenceItem as r, FlumeErrorHandler as s, FlumeSource as t, FlumeGatewayMessage as u, FlumeReconnectConfig as v, FlumeSlackSourceOptions as w, FlumeSlackConnectionResponse as x, FlumeReconnectOptions as y, FlumeTimeTick as z };
+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 });
@@ -71,16 +82,44 @@ var FlumeStartError = class extends Error {
 	}
 };
 //#endregion
+//#region lib/errors/source-reuse-error.ts
+/** 起動を取得する前の拒否。Flume は他の起動処理が所有する Source を rollback しない。 */
+var FlumeSourceReuseError = class extends FlumeStartError {};
+//#endregion
+//#region lib/utils/safe-invoke-callback.ts
+/**
+* fire-and-forget でユーザーコールバックを呼び出す。sync throw と async reject のどちらも
+* `onError(Error)` に正規化して通知。`onError` 自身が throw しても外に漏らさない。
+* 戻り値を持たない fire-and-forget 専用のため log/出力先には依存しない (caller が onError で決める)
+*/
+function safeInvokeCallback(props) {
+	try {
+		Promise.resolve(props.fn()).catch((err) => {
+			try {
+				props.onError(safeNormalizeError({ value: err }));
+			} catch {}
+		}).catch(() => {});
+	} catch (err) {
+		try {
+			props.onError(safeNormalizeError({ value: err }));
+		} catch {}
+	}
+}
+//#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;
 	}
@@ -130,31 +169,38 @@ var FlumeLogger = class FlumeLogger {
 			error: input.error,
 			detail: input.detail
 		};
-		try {
-			Promise.resolve(handler(log)).catch(() => {});
-		} catch {}
+		safeInvokeCallback({
+			fn: () => handler(log),
+			onError: () => {}
+		});
 	}
 };
 //#endregion
-//#region lib/utils/safe-invoke-callback.ts
+//#region lib/utils/serial-queue.ts
 /**
-* fire-and-forget でユーザーコールバックを呼び出す。sync throw と async reject のどちらも
-* `onError(Error)` に正規化して通知。`onError` 自身が throw しても外に漏らさない。
-* 戻り値を持たない fire-and-forget 専用のため log/出力先には依存しない (caller が onError で決める)
+* 投入順を保ったまま task を直列実行する。各 task は前の完了を待ってから走る。
+* task が throw しても後続には伝播しない (キュー自体は止まらない)。
+* drain() は待機中に追加された task も含めてキューが空になるまで待つ
 */
-function safeInvokeCallback(props) {
-	try {
-		Promise.resolve(props.fn()).catch((err) => {
+var FlumeSerialQueue = class {
+	chain = Promise.resolve();
+	add(task) {
+		const completion = this.chain.then(async () => {
 			try {
-				props.onError(safeNormalizeError({ value: err }));
+				await task();
 			} catch {}
-		}).catch(() => {});
-	} catch (err) {
-		try {
-			props.onError(safeNormalizeError({ value: err }));
-		} catch {}
+		});
+		this.chain = completion;
+		return completion;
 	}
-}
+	async drain() {
+		while (true) {
+			const current = this.chain;
+			await current;
+			if (this.chain === current) return;
+		}
+	}
+};
 //#endregion
 //#region lib/source-helpers/flume-status-emitter.ts
 /**
@@ -203,55 +249,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 +257,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 +283,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.consumed) return new FlumeSourceReuseError("Source already started");
+		if (this.stopped) return new FlumeSourceReuseError("Source 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";
@@ -315,7 +332,7 @@ var FlumeSource = class {
 	*/
 	emit(event) {
 		const ctx = this.ctx;
-		if (!ctx) return;
+		if (!ctx || this.stopped) return;
 		this.queue.add(async () => {
 			const result = await attempt(() => Promise.resolve(ctx.onEvent(event)));
 			if (result instanceof Error) ctx.log.error({
@@ -329,8 +346,13 @@ var FlumeSource = class {
 	* subclass が protocol 状態遷移をユーザーに通知する。同一 (status, detail) の連続は冪等
 	*/
 	setStatus(status, detail) {
+		if (this.stopped) return;
 		this.statusEmitter?.set(status, detail);
 	}
+	/** await をまたぐ接続処理が、停止後に新しいリソースを作らないための guard。 */
+	get isStopped() {
+		return this.stopped;
+	}
 	/** subclass が現在の status を読みたい場合 */
 	get currentStatus() {
 		return this.statusEmitter?.value ?? "disconnected";
@@ -339,6 +361,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 { safeInvokeCallback as a, FlumeParseError as c, safeErrorMessage as d, safeNow as i, attempt as l, FlumeSerialQueue as n, FlumeSourceReuseError as o, FlumeLogger as r, FlumeStartError as s, FlumeSource as t, safeNormalizeError as u };

package/dist/github.d.ts

@@ -1,4 +1,4 @@
-import { D as FlumeSourceStartContext, f as FlumeGitHubNotification, p as FlumeGitHubSourceOptions, t as FlumeSource } 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;
 }