@interactive-inc/flume 0.4.0 → 0.9.0

package/dist/flume-source.js

@@ -0,0 +1,344 @@
+//#region lib/utils/safe-error-message.ts
+/**
+* 任意の値から人が読めるメッセージ文字列を取り出す。
+* `Error.message` getter / `Symbol.toPrimitive` / `toString` / `valueOf` が throw しても固定文字列に fallback。
+* 自身は決して 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>";
+	} catch {
+		return "<unreadable error message>";
+	}
+	try {
+		return String(props.error);
+	} catch {
+		return "<unprintable error>";
+	}
+}
+//#endregion
+//#region lib/utils/safe-normalize-error.ts
+/**
+* 任意の値を `Error` インスタンスへ正規化する。すでに Error ならそのまま返し、
+* それ以外は `safeErrorMessage` で安全な文字列化を経由して new Error する。
+* Error コンストラクタ自体が throw する病的環境でも fallback を返し、決して throw しない
+*/
+function safeNormalizeError(props) {
+	if (props.value instanceof Error) return props.value;
+	const message = safeErrorMessage({ error: props.value });
+	try {
+		return new Error(message);
+	} catch {
+		try {
+			return /* @__PURE__ */ new Error("unknown error");
+		} catch {
+			const fallback = Object.create(Error.prototype);
+			fallback.name = "Error";
+			fallback.message = "unknown error";
+			return fallback;
+		}
+	}
+}
+//#endregion
+//#region lib/utils/attempt.ts
+function attempt(fn) {
+	try {
+		const result = fn();
+		if (result instanceof Promise) return result.catch((err) => safeNormalizeError({ value: err }));
+		return result;
+	} catch (err) {
+		return safeNormalizeError({ value: err });
+	}
+}
+//#endregion
+//#region lib/errors/parse-error.ts
+var FlumeParseError = class extends Error {
+	constructor(message, options) {
+		super(message, options?.cause === void 0 ? void 0 : { cause: options.cause });
+		this.name = "FlumeParseError";
+		Object.freeze(this);
+	}
+};
+//#endregion
+//#region lib/errors/start-error.ts
+var FlumeStartError = class extends Error {
+	constructor(message, options) {
+		super(message, options?.cause === void 0 ? void 0 : { cause: options.cause });
+		this.name = "FlumeStartError";
+		Object.freeze(this);
+	}
+};
+//#endregion
+//#region lib/utils/safe-now.ts
+/**
+* `deps.now()` を保護する。throw / 非数値が返った場合は 0 を返す。
+* IO 境界のため呼び出し側はこの戻り値を信頼できる
+*/
+function safeNow(props) {
+	try {
+		const value = props.deps.now();
+		if (typeof value !== "number" || !Number.isFinite(value)) return 0;
+		return value;
+	} catch {
+		return 0;
+	}
+}
+//#endregion
+//#region lib/logger.ts
+/**
+* 構造化ログを onLog に流す。handler が throw / reject してもループは継続する
+*/
+var FlumeLogger = class FlumeLogger {
+	props;
+	constructor(props) {
+		this.props = props;
+		Object.freeze(this);
+	}
+	debug(entry) {
+		this.emit("debug", entry);
+	}
+	info(entry) {
+		this.emit("info", entry);
+	}
+	warn(entry) {
+		this.emit("warn", entry);
+	}
+	error(entry) {
+		this.emit("error", entry);
+	}
+	get handler() {
+		return this.props.handler;
+	}
+	child(source) {
+		return new FlumeLogger({
+			source,
+			handler: this.props.handler,
+			deps: this.props.deps
+		});
+	}
+	emit(level, input) {
+		const handler = this.props.handler;
+		if (!handler) return;
+		const log = {
+			level,
+			source: this.props.source,
+			action: input.action,
+			message: input.message,
+			timestamp: safeNow({ deps: this.props.deps }),
+			error: input.error,
+			detail: input.detail
+		};
+		try {
+			Promise.resolve(handler(log)).catch(() => {});
+		} catch {}
+	}
+};
+//#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/source-helpers/flume-status-emitter.ts
+/**
+* Source の `currentStatus` と `onStatus` 通知を集約する。
+* 同一 (status, detail) の連続遷移は冪等に握り潰し、ユーザーコールバックは `safeInvokeCallback`
+* 経由で例外を隔離する
+*/
+var FlumeStatusEmitter = class {
+	props;
+	currentStatus = "disconnected";
+	currentDetail = null;
+	constructor(props) {
+		this.props = props;
+	}
+	get value() {
+		return this.currentStatus;
+	}
+	set(next, detail) {
+		const normalizedDetail = detail ?? null;
+		if (this.currentStatus === next && this.currentDetail === normalizedDetail) return;
+		const prev = this.currentStatus;
+		const suffix = detail ? ` (${detail})` : "";
+		this.props.log.info({
+			action: "status",
+			message: `${prev} → ${next}${suffix}`,
+			detail: {
+				from: prev,
+				to: next,
+				reason: normalizedDetail
+			}
+		});
+		this.currentStatus = next;
+		this.currentDetail = normalizedDetail;
+		const onStatus = this.props.onStatus;
+		if (!onStatus) return;
+		safeInvokeCallback({
+			fn: detail !== void 0 ? () => onStatus(next, detail) : () => onStatus(next),
+			onError: (error) => {
+				this.props.log.error({
+					action: "onStatus.error",
+					message: safeErrorMessage({ error }),
+					error
+				});
+			}
+		});
+	}
+};
+//#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`) のみ
+* subclass に実装させ、queue / status / handler 安全呼び出しといった共通の
+* cross-cutting concern は base が引き受ける。Flume 側で全 source に注入される
+* `FlumeSourceStartContext` (handler / log / deps / onStatus / reconnect) を
+* `start()` で受け取り、subclass の `connect(ctx)` に手渡す。
+*
+* subclass のテンプレート:
+*
+* ```ts
+* export class MySource extends FlumeSource {
+*   readonly name = "my-source"
+*
+*   constructor(private readonly options: { apiKey: string }) {
+*     super()
+*   }
+*
+*   protected async connect(ctx: FlumeSourceStartContext): Promise<Error | null> {
+*     // 接続して onEvent で this.emit({...}) / 状態遷移で this.setStatus(...)
+*     return null
+*   }
+*
+*   protected disconnect(): void { ... }
+* }
+* ```
+*/
+var FlumeSource = class {
+	consumed = false;
+	stopped = false;
+	ctx = null;
+	statusEmitter = null;
+	queue = new FlumeSerialQueue();
+	async start(ctx) {
+		if (this.consumed) return new FlumeStartError(`${this.name}: already started`);
+		this.consumed = true;
+		this.ctx = ctx;
+		this.statusEmitter = new FlumeStatusEmitter({
+			log: ctx.log,
+			onStatus: ctx.onStatus
+		});
+		return await this.connect(ctx);
+	}
+	async stop() {
+		if (this.stopped) return;
+		this.stopped = true;
+		try {
+			await this.disconnect();
+		} finally {
+			await this.queue.drain();
+			this.statusEmitter?.set("disconnected");
+			this.ctx = null;
+		}
+	}
+	status() {
+		return this.statusEmitter?.value ?? "disconnected";
+	}
+	/**
+	* subclass が受信した protocol イベントを `FlumeEvent` として handler へ流す。
+	* handler の throw / async reject は queue 内で catch + log し、後続を止めない
+	*/
+	emit(event) {
+		const ctx = this.ctx;
+		if (!ctx) return;
+		this.queue.add(async () => {
+			const result = await attempt(() => Promise.resolve(ctx.onEvent(event)));
+			if (result instanceof Error) ctx.log.error({
+				action: "onEvent.error",
+				message: safeErrorMessage({ error: result }),
+				error: result
+			});
+		});
+	}
+	/**
+	* subclass が protocol 状態遷移をユーザーに通知する。同一 (status, detail) の連続は冪等
+	*/
+	setStatus(status, detail) {
+		this.statusEmitter?.set(status, detail);
+	}
+	/** subclass が現在の status を読みたい場合 */
+	get currentStatus() {
+		return this.statusEmitter?.value ?? "disconnected";
+	}
+	/** subclass が start ctx を再参照したい場合 (stop 後は null) */
+	get context() {
+		return this.ctx;
+	}
+};
+//#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 };

package/dist/github.d.ts

@@ -1,21 +1,13 @@
-import { C as FlumeSourceStartOptions, T as FlumeStatus, c as FlumeHandler, o as FlumeGitHubNotification, s as FlumeGitHubSourceOptions } from "./types-D-tO-Mh2.js";
+import { l as FlumeGitHubNotification, t as FlumeSource, u as FlumeGitHubSourceOptions, w as FlumeSourceStartContext } from "./flume-source.js";
 
 //#region lib/github/github-source.d.ts
-declare class FlumeGitHubSource {
+declare class FlumeGitHubSource extends FlumeSource {
   private readonly options;
   readonly name: "github";
   private poller;
-  private handler;
-  private readonly log;
-  private readonly deps;
-  private readonly queue;
-  private readonly signals;
-  private readonly statusEmitter;
-  private readonly onSignalAbort;
   constructor(options: FlumeGitHubSourceOptions);
-  start(handler: FlumeHandler, options?: FlumeSourceStartOptions): Promise<Error | null>;
-  stop(): Promise<void>;
-  status(): FlumeStatus;
+  protected connect(ctx: FlumeSourceStartContext): Promise<Error | null>;
+  protected disconnect(): void;
   private handleNotifications;
   private safeExtractMeta;
 }

package/dist/github.js

@@ -1,7 +1,7 @@
-import { a as FlumeParseError, c as safeNormalizeError, i as FlumeStartError, l as safeErrorMessage, n as FlumeLogger, o as createFlumeDefaultDeps, r as safeNow, s as attempt, t as safeInvokeCallback } from "./safe-invoke-callback-EpWXwfwp.js";
-import { t as FlumeHttpError } from "./http-error-CPSKoSie.js";
-import { i as safeJsonParse, n as FlumeStatusEmitter, r as FlumeSignalRegistry, t as FlumeSerialQueue } from "./serial-queue-B9LoBc64.js";
-import { t as safeReadText } from "./safe-read-text-DgrJ4Uhl.js";
+import { 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 { t as FlumeHttpError } from "./http-error.js";
+import { t as safeJsonParse } from "./safe-json-parse.js";
+import { t as safeReadText } from "./safe-read-text.js";
 import { z } from "zod/v4";
 //#region lib/github/extract-github-meta.ts
 function flumeExtractGitHubMeta(notification) {
@@ -43,8 +43,12 @@ var FlumeGitHubSeenCache = class {
 	}
 	trim() {
 		if (this.seen.size <= this.props.maxSize) return;
-		const entries = [...this.seen.entries()];
-		this.seen = new Map(entries.slice(entries.length - this.props.maxSize));
+		let removeCount = this.seen.size - this.props.maxSize;
+		for (const id of this.seen.keys()) {
+			if (removeCount <= 0) break;
+			this.seen.delete(id);
+			removeCount--;
+		}
 	}
 	get size() {
 		return this.seen.size;
@@ -104,6 +108,7 @@ var FlumeGitHubPoller = class {
 		const error = await this.poll();
 		if (error) return error;
 		if (this.isStoppedFlag) return null;
+		if (this.rateLimitTimer !== null) return null;
 		this.scheduleInterval();
 		return null;
 	}
@@ -128,7 +133,7 @@ var FlumeGitHubPoller = class {
 					message: safeErrorMessage({ error }),
 					error
 				});
-			}).catch(() => {});
+			});
 		}, this.effectiveIntervalSec * 1e3));
 		if (intervalResult instanceof Error) {
 			this.log.error({
@@ -447,115 +452,55 @@ var FlumeGitHubPoller = class {
 };
 //#endregion
 //#region lib/github/github-source.ts
-var FlumeGitHubSource = class {
+var FlumeGitHubSource = class extends FlumeSource {
 	options;
 	name = "github";
 	poller = null;
-	handler = null;
-	log;
-	deps;
-	queue = new FlumeSerialQueue();
-	signals;
-	statusEmitter;
-	onSignalAbort = () => {
-		safeInvokeCallback({
-			fn: () => this.stop(),
-			onError: (error) => {
-				this.log.error({
-					action: "signal.abort.stop.failed",
-					message: safeErrorMessage({ error }),
-					error
-				});
-			}
-		});
-	};
 	constructor(options) {
+		super();
 		this.options = options;
-		this.deps = options.deps ?? createFlumeDefaultDeps();
-		this.log = new FlumeLogger({
-			source: "github",
-			handler: options.onLog,
-			deps: this.deps
-		});
-		this.signals = new FlumeSignalRegistry({
-			log: this.log,
-			onAbort: this.onSignalAbort
-		});
-		this.statusEmitter = new FlumeStatusEmitter({
-			log: this.log,
-			onStatus: options.onStatus
-		});
 	}
-	async start(handler, options) {
-		if (this.signals.isAnyAborted(this.options.signal) || this.signals.isAnyAborted(options?.signal)) return new FlumeStartError("GitHub source: signal already aborted");
-		this.signals.register(this.options.signal);
-		this.signals.register(options?.signal);
-		this.handler = handler;
-		this.log.info({
-			action: "source.start",
-			message: "starting GitHub source"
-		});
-		this.statusEmitter.set("connecting");
+	async connect(ctx) {
+		this.setStatus("connecting");
 		this.poller = new FlumeGitHubPoller({
 			token: this.options.token,
 			interval: this.options.pollInterval ?? 60,
-			onLog: this.options.onLog,
-			deps: this.deps,
-			onNotifications: (notifications) => this.handleNotifications(notifications),
-			onConnected: () => this.statusEmitter.set("connected"),
-			onDisconnected: (detail) => this.statusEmitter.set("disconnected", detail)
+			onLog: ctx.log.handler,
+			deps: ctx.deps,
+			onNotifications: (notifications) => this.handleNotifications(ctx, notifications),
+			onConnected: () => this.setStatus("connected"),
+			onDisconnected: (detail) => this.setStatus("disconnected", detail)
 		});
 		const result = await this.poller.start();
 		if (result instanceof Error) {
-			this.log.error({
+			ctx.log.error({
 				action: "source.start.failed",
 				message: safeErrorMessage({ error: result }),
 				error: result
 			});
-			this.statusEmitter.set("disconnected", result.message);
+			this.setStatus("disconnected", result.message);
 			return result;
 		}
 		return null;
 	}
-	async stop() {
-		this.signals.unregisterAll();
-		this.log.info({
-			action: "source.stop",
-			message: "stopping GitHub source"
-		});
+	disconnect() {
 		this.poller?.stop();
-		await this.queue.drain();
 		this.poller = null;
-		this.handler = null;
-		this.statusEmitter.set("disconnected");
-	}
-	status() {
-		return this.statusEmitter.value;
 	}
-	handleNotifications(notifications) {
-		const handler = this.handler;
-		if (!handler) return;
-		for (const notification of notifications) this.queue.add(async () => {
-			const event = {
-				source: "github",
-				type: "notification",
-				data: notification,
-				meta: this.safeExtractMeta(notification),
-				receivedAt: safeNow({ deps: this.deps })
-			};
-			const r = await attempt(() => Promise.resolve(handler(event)));
-			if (r instanceof Error) this.log.error({
-				action: "handler.error",
-				message: safeErrorMessage({ error: r }),
-				error: r
-			});
+	handleNotifications(ctx, notifications) {
+		for (const notification of notifications) this.emit({
+			source: "github",
+			type: "notification",
+			data: notification,
+			meta: this.safeExtractMeta(ctx, notification),
+			receivedAt: safeNow({ deps: ctx.deps })
 		});
 	}
-	safeExtractMeta(notification) {
+	safeExtractMeta(ctx, notification) {
 		const result = attempt(() => flumeExtractGitHubMeta(notification));
 		if (result instanceof Error) {
 			const error = safeNormalizeError({ value: result });
-			this.log.warn({
+			ctx.log.warn({
 				action: "meta.extract.error",
 				message: safeErrorMessage({ error }),
 				error,