@interactive-inc/flume 0.3.0 → 0.4.0

package/dist/github.js

@@ -1,9 +1,10 @@
-import { n as createFlumeDefaultDeps, t as FlumeLogger } from "./logger-CpGB9WO_.js";
-import { t as FlumeSerialQueue } from "./serial-queue-ExmlnpzQ.js";
-import { t as safeFetch } from "./safe-fetch-30ZzOKHL.js";
+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 { z } from "zod/v4";
 //#region lib/github/extract-github-meta.ts
-function extractGitHubMeta(notification) {
+function flumeExtractGitHubMeta(notification) {
 	return {
 		event_type: "notification",
 		reason: notification.reason,
@@ -51,15 +52,28 @@ var FlumeGitHubSeenCache = class {
 };
 //#endregion
 //#region lib/github/github-poller.ts
+const NOTIFICATIONS_URL = "https://api.github.com/notifications";
+const CONSECUTIVE_ERRORS_TO_DISCONNECT = 3;
+const SEEN_CACHE_MAX = 5e3;
+/**
+* GitHub /notifications を条件付きポーリングする (ETag / Last-Modified)。
+* 304 / X-Poll-Interval / レート制限を尊重し、stop() / abort() で in-flight 通信を打ち切る
+*/
 var FlumeGitHubPoller = class {
 	props;
 	log;
-	cache = new FlumeGitHubSeenCache({ maxSize: 5e3 });
+	cache = new FlumeGitHubSeenCache({ maxSize: SEEN_CACHE_MAX });
 	timer = null;
+	rateLimitTimer = null;
 	since = null;
+	etag = null;
+	lastModified = null;
 	bootstrapped = false;
-	stopped = false;
+	isStoppedFlag = false;
+	inFlight = false;
 	consecutiveErrors = 0;
+	effectiveIntervalSec;
+	controller = null;
 	constructor(props) {
 		this.props = props;
 		this.log = new FlumeLogger({
@@ -67,45 +81,125 @@ var FlumeGitHubPoller = class {
 			handler: props.onLog,
 			deps: props.deps
 		});
+		this.effectiveIntervalSec = props.interval;
+	}
+	get isStopped() {
+		return this.isStoppedFlag;
 	}
 	async start() {
-		this.stopped = false;
+		this.isStoppedFlag = false;
+		const controllerResult = attempt(() => new AbortController());
+		if (controllerResult instanceof Error) {
+			this.log.error({
+				action: "github.abort-controller.new.error",
+				message: safeErrorMessage({ error: controllerResult }),
+				error: controllerResult
+			});
+			this.controller = null;
+		} else this.controller = controllerResult;
 		this.log.info({
-			action: "start",
-			message: `polling every ${this.props.interval}s`
+			action: "poller.start",
+			message: `polling every ${this.effectiveIntervalSec}s`
 		});
-		await this.poll();
-		this.timer = this.props.deps.setInterval(() => {
-			this.poll().catch((err) => {
-				this.log.error({
-					action: "poll.unhandled",
-					message: "unexpected error in poll loop",
-					error: err instanceof Error ? err : new Error(String(err))
-				});
-			});
-		}, this.props.interval * 1e3);
+		const error = await this.poll();
+		if (error) return error;
+		if (this.isStoppedFlag) return null;
+		this.scheduleInterval();
+		return null;
 	}
 	stop() {
 		this.log.info({
-			action: "stop",
+			action: "poller.stop",
 			message: "stopping poller"
 		});
-		this.stopped = true;
-		if (this.timer !== null) {
-			this.props.deps.clearInterval(this.timer);
+		this.isStoppedFlag = true;
+		this.controller?.abort();
+		this.controller = null;
+		this.clearTimer();
+		this.clearRateLimitTimer();
+	}
+	scheduleInterval() {
+		this.clearTimer();
+		const intervalResult = attempt(() => this.props.deps.setInterval(() => {
+			this.poll().catch((err) => {
+				const error = safeNormalizeError({ value: err });
+				this.log.error({
+					action: "poll.unhandled",
+					message: safeErrorMessage({ error }),
+					error
+				});
+			}).catch(() => {});
+		}, this.effectiveIntervalSec * 1e3));
+		if (intervalResult instanceof Error) {
+			this.log.error({
+				action: "poller.interval.schedule.error",
+				message: safeErrorMessage({ error: intervalResult }),
+				error: intervalResult
+			});
 			this.timer = null;
+			if (!this.isStoppedFlag) this.props.onDisconnected("interval scheduling rejected by runtime");
+			return;
 		}
+		this.timer = intervalResult;
 	}
 	async poll() {
-		const params = new URLSearchParams({ all: "false" });
+		if (this.inFlight || this.isStoppedFlag) return null;
+		this.inFlight = true;
+		try {
+			return await this.pollOnce();
+		} catch (err) {
+			const cause = safeNormalizeError({ value: err });
+			const error = new FlumeHttpError({
+				message: `poll loop threw: ${safeErrorMessage({ error: cause })}`,
+				status: 0,
+				cause
+			});
+			this.log.error({
+				action: "poll.unhandled",
+				message: safeErrorMessage({ error }),
+				error
+			});
+			if (!this.bootstrapped) return error;
+			return null;
+		} finally {
+			this.inFlight = false;
+		}
+	}
+	async pollOnce() {
+		const params = new URLSearchParams({
+			all: "false",
+			per_page: "50"
+		});
 		if (this.since) params.set("since", this.since);
-		const url = `https://api.github.com/notifications?${params}`;
+		const url = `${NOTIFICATIONS_URL}?${params}`;
 		this.log.debug({
 			action: "http.request",
 			message: `GET ${url}`
 		});
-		const response = await this.safeFetch(url);
-		if (response instanceof Error) return;
+		const headers = {
+			Authorization: `Bearer ${this.props.token}`,
+			Accept: "application/vnd.github+json",
+			"X-GitHub-Api-Version": "2022-11-28"
+		};
+		if (this.etag) headers["If-None-Match"] = this.etag;
+		if (this.lastModified) headers["If-Modified-Since"] = this.lastModified;
+		const response = await attempt(() => this.props.deps.fetch(url, {
+			headers,
+			signal: this.controller?.signal
+		}));
+		if (this.isStoppedFlag) return null;
+		if (response instanceof Error) {
+			this.log.error({
+				action: "http.error",
+				message: safeErrorMessage({ error: response }),
+				error: response
+			});
+			return this.recordFailure({
+				kind: "network",
+				message: response.message,
+				cause: response
+			});
+		}
 		this.log.debug({
 			action: "http.response",
 			message: `GET ${response.status}`,
@@ -114,45 +208,175 @@ var FlumeGitHubPoller = class {
 				url
 			}
 		});
+		this.maybeWidenInterval(response.headers.get("X-Poll-Interval"));
+		if (response.status === 304) {
+			this.consecutiveErrors = 0;
+			this.log.debug({
+				action: "poll.not-modified",
+				message: "304 Not Modified"
+			});
+			return null;
+		}
+		if (this.isRateLimited(response)) {
+			this.handleRateLimit(response);
+			return null;
+		}
 		if (!response.ok) {
-			this.consecutiveErrors++;
-			this.log.error({
-				action: "http.error",
-				message: `HTTP ${response.status} (consecutive=${this.consecutiveErrors})`
+			const error = new FlumeHttpError({
+				message: `HTTP ${response.status}`,
+				status: response.status
+			});
+			return this.recordFailure({
+				kind: "http",
+				message: safeErrorMessage({ error }),
+				error
 			});
-			if (this.consecutiveErrors >= 3) this.props.onDisconnected(`HTTP ${response.status}`);
-			return;
 		}
 		this.consecutiveErrors = 0;
-		const body = await response.json();
-		if (!Array.isArray(body)) {
+		this.etag = response.headers.get("ETag");
+		this.lastModified = response.headers.get("Last-Modified");
+		const text = await safeReadText({
+			response,
+			context: "notifications"
+		});
+		if (this.isStoppedFlag) return null;
+		if (text instanceof FlumeHttpError) {
 			this.log.warn({
-				action: "http.body",
+				action: "http.body.read",
+				message: safeErrorMessage({ error: text }),
+				error: text
+			});
+			return this.recordFailure({
+				kind: "http",
+				message: text.message,
+				error: text
+			});
+		}
+		const json = safeJsonParse(text);
+		if (json instanceof FlumeParseError) {
+			this.log.warn({
+				action: "http.body.parse",
+				message: json.message,
+				error: json
+			});
+			return null;
+		}
+		if (!Array.isArray(json)) {
+			this.log.warn({
+				action: "http.body.shape",
 				message: "response body is not an array, dropping",
-				detail: { bodyType: typeof body }
+				detail: { bodyType: typeof json }
 			});
-			return;
+			return null;
 		}
-		this.processNotifications(body);
+		this.processNotifications(json);
+		return null;
 	}
-	processNotifications(raw) {
-		let dropped = 0;
-		const notifications = raw.flatMap((item) => {
-			const parsed = FlumeGitHubNotificationSchema.safeParse(item);
-			if (!parsed.success) {
-				dropped++;
-				this.log.warn({
-					action: "parse.skip",
-					message: "notification did not match schema",
-					detail: { issues: parsed.error.issues.map((i) => ({
-						path: i.path,
-						message: i.message
-					})) }
-				});
-				return [];
+	recordFailure(input) {
+		this.consecutiveErrors++;
+		const error = input.error ?? new FlumeHttpError({
+			message: input.message,
+			status: 0,
+			cause: input.cause
+		});
+		this.log.error({
+			action: "http.error",
+			message: input.message,
+			error,
+			detail: { consecutiveErrors: this.consecutiveErrors }
+		});
+		if (this.consecutiveErrors >= CONSECUTIVE_ERRORS_TO_DISCONNECT && !this.isStoppedFlag) this.props.onDisconnected(input.kind === "network" ? "network error" : input.message);
+		if (!this.bootstrapped) return error;
+		return null;
+	}
+	isRateLimited(response) {
+		if (response.status === 429) return true;
+		if (response.status === 403 && response.headers.get("X-RateLimit-Remaining") === "0") return true;
+		return false;
+	}
+	handleRateLimit(response) {
+		const retryAfter = response.headers.get("Retry-After");
+		const reset = response.headers.get("X-RateLimit-Reset");
+		const nowSec = Math.floor(safeNow({ deps: this.props.deps }) / 1e3);
+		const retryAfterSec = retryAfter !== null ? Number.parseInt(retryAfter, 10) : NaN;
+		const resetSec = reset !== null ? Number.parseInt(reset, 10) - nowSec : NaN;
+		const delaySec = Number.isFinite(retryAfterSec) && retryAfterSec > 0 ? retryAfterSec : Number.isFinite(resetSec) && resetSec > 0 ? resetSec : 60;
+		this.log.warn({
+			action: "rate.limit",
+			message: `rate limited, pausing for ${delaySec}s`,
+			detail: {
+				status: response.status,
+				delaySec
 			}
-			return [parsed.data];
 		});
+		this.clearTimer();
+		this.clearRateLimitTimer();
+		const timerResult = attempt(() => this.props.deps.setTimeout(() => {
+			this.rateLimitTimer = null;
+			if (this.isStoppedFlag) return;
+			this.scheduleInterval();
+		}, delaySec * 1e3));
+		if (timerResult instanceof Error) {
+			this.log.error({
+				action: "poller.rate-limit.schedule.error",
+				message: safeErrorMessage({ error: timerResult }),
+				error: timerResult
+			});
+			this.rateLimitTimer = null;
+		} else this.rateLimitTimer = timerResult;
+	}
+	clearTimer() {
+		if (this.timer === null) return;
+		const handle = this.timer;
+		const result = attempt(() => this.props.deps.clearInterval(handle));
+		if (result instanceof Error) this.log.error({
+			action: "poller.timer.clear.error",
+			message: safeErrorMessage({ error: result }),
+			error: result
+		});
+		this.timer = null;
+	}
+	clearRateLimitTimer() {
+		if (this.rateLimitTimer === null) return;
+		const handle = this.rateLimitTimer;
+		const result = attempt(() => this.props.deps.clearTimeout(handle));
+		if (result instanceof Error) this.log.error({
+			action: "poller.rate-limit.clear.error",
+			message: safeErrorMessage({ error: result }),
+			error: result
+		});
+		this.rateLimitTimer = null;
+	}
+	maybeWidenInterval(headerValue) {
+		if (headerValue === null) return;
+		const required = Number.parseInt(headerValue, 10);
+		if (!Number.isFinite(required) || required <= this.effectiveIntervalSec) return;
+		this.log.info({
+			action: "poll.widen-interval",
+			message: `widening interval ${this.effectiveIntervalSec}s -> ${required}s per X-Poll-Interval`,
+			detail: {
+				from: this.effectiveIntervalSec,
+				to: required
+			}
+		});
+		this.effectiveIntervalSec = required;
+		if (this.timer !== null) this.scheduleInterval();
+	}
+	processNotifications(raw) {
+		const parsedResults = raw.map((item) => FlumeGitHubNotificationSchema.safeParse(item));
+		for (const result of parsedResults) {
+			if (result.success) continue;
+			this.log.warn({
+				action: "parse.skip",
+				message: "notification did not match schema",
+				detail: { issues: result.error.issues.map((i) => ({
+					path: i.path,
+					message: i.message
+				})) }
+			});
+		}
+		const notifications = parsedResults.flatMap((r) => r.success ? [r.data] : []);
+		const dropped = raw.length - notifications.length;
 		if (dropped > 0) this.log.warn({
 			action: "parse.summary",
 			message: `${dropped}/${raw.length} notifications dropped by schema`
@@ -160,53 +384,65 @@ var FlumeGitHubPoller = class {
 		if (!this.bootstrapped) {
 			this.bootstrapped = true;
 			for (const notification of notifications) this.cache.add(notification.id, notification.updated_at);
-			this.since = new Date(this.props.deps.now()).toISOString();
+			this.advanceCursor();
 			this.log.info({
-				action: "bootstrap",
+				action: "poller.bootstrap",
 				message: `seeded ${notifications.length} existing notifications`
 			});
 			this.props.onConnected();
 			return;
 		}
-		const fresh = [];
-		for (const notification of notifications) {
-			if (this.cache.has(notification.id, notification.updated_at)) continue;
+		const fresh = notifications.filter((notification) => {
+			if (this.cache.has(notification.id, notification.updated_at)) return false;
 			this.cache.add(notification.id, notification.updated_at);
-			fresh.push(notification);
-		}
+			return true;
+		});
 		this.cache.trim();
-		this.since = new Date(this.props.deps.now()).toISOString();
+		this.advanceCursor();
 		if (fresh.length > 0) {
 			this.log.info({
 				action: "poll.fresh",
-				message: `${fresh.length} new notifications`
+				message: `${fresh.length} new notifications`,
+				detail: { count: fresh.length }
 			});
 			this.props.onNotifications(fresh);
-		} else this.log.debug({
+			return;
+		}
+		this.log.debug({
 			action: "poll.idle",
 			message: "0 new notifications"
 		});
 	}
-	async safeFetch(url) {
-		const result = await safeFetch({
-			fetch: this.props.deps.fetch,
-			url,
-			init: { headers: {
-				Authorization: `Bearer ${this.props.token}`,
-				Accept: "application/vnd.github+json",
-				"X-GitHub-Api-Version": "2022-11-28"
-			} },
-			log: this.log
-		});
-		if (result instanceof Error) {
-			this.consecutiveErrors++;
+	advanceCursor() {
+		if (this.lastModified !== null) {
+			const parsed = new Date(this.lastModified);
+			if (!Number.isNaN(parsed.getTime())) {
+				const iso = attempt(() => parsed.toISOString());
+				if (!(iso instanceof Error)) {
+					this.since = iso;
+					return;
+				}
+			}
+		}
+		const nowMs = safeNow({ deps: this.props.deps });
+		if (!Number.isFinite(nowMs)) {
 			this.log.warn({
-				action: "http.error",
-				message: `consecutive=${this.consecutiveErrors}`
+				action: "cursor.advance.skip",
+				message: "deps.now() returned non-finite, leaving since cursor unchanged"
 			});
-			if (this.consecutiveErrors >= 3) this.props.onDisconnected("network error");
+			return;
 		}
-		return result;
+		const iso = attempt(() => new Date(nowMs).toISOString());
+		if (iso instanceof Error) {
+			const error = safeNormalizeError({ value: iso });
+			this.log.warn({
+				action: "cursor.advance.skip",
+				message: safeErrorMessage({ error }),
+				error
+			});
+			return;
+		}
+		this.since = iso;
 	}
 };
 //#endregion
@@ -215,10 +451,24 @@ var FlumeGitHubSource = class {
 	options;
 	name = "github";
 	poller = null;
-	currentStatus = "disconnected";
+	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) {
 		this.options = options;
 		this.deps = options.deps ?? createFlumeDefaultDeps();
@@ -227,88 +477,94 @@ var FlumeGitHubSource = class {
 			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) {
-		if (this.options.signal?.aborted) return {
-			ok: false,
-			error: /* @__PURE__ */ new Error("GitHub source: signal already aborted")
-		};
-		this.options.signal?.addEventListener("abort", () => this.stop(), { once: true });
+	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: "start",
+			action: "source.start",
 			message: "starting GitHub source"
 		});
-		this.setStatus("connecting");
+		this.statusEmitter.set("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(handler, notifications),
-			onConnected: () => this.setStatus("connected"),
-			onDisconnected: (detail) => this.setStatus("disconnected", detail)
+			onNotifications: (notifications) => this.handleNotifications(notifications),
+			onConnected: () => this.statusEmitter.set("connected"),
+			onDisconnected: (detail) => this.statusEmitter.set("disconnected", detail)
 		});
-		try {
-			await this.poller.start();
-		} catch (error) {
-			const err = error instanceof Error ? error : new Error(String(error));
+		const result = await this.poller.start();
+		if (result instanceof Error) {
 			this.log.error({
-				action: "start.failed",
-				message: err.message,
-				error: err
+				action: "source.start.failed",
+				message: safeErrorMessage({ error: result }),
+				error: result
 			});
-			this.setStatus("disconnected");
-			return {
-				ok: false,
-				error: err
-			};
+			this.statusEmitter.set("disconnected", result.message);
+			return result;
 		}
-		return { ok: true };
+		return null;
 	}
 	async stop() {
+		this.signals.unregisterAll();
 		this.log.info({
-			action: "stop",
+			action: "source.stop",
 			message: "stopping GitHub source"
 		});
 		this.poller?.stop();
-		this.poller = null;
 		await this.queue.drain();
-		this.setStatus("disconnected");
+		this.poller = null;
+		this.handler = null;
+		this.statusEmitter.set("disconnected");
 	}
 	status() {
-		return this.currentStatus;
+		return this.statusEmitter.value;
 	}
-	handleNotifications(handler, notifications) {
-		for (const notification of notifications) {
+	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: extractGitHubMeta(notification),
-				receivedAt: this.deps.now()
+				meta: this.safeExtractMeta(notification),
+				receivedAt: safeNow({ deps: this.deps })
 			};
-			this.queue.add(async () => {
-				try {
-					await handler(event);
-				} catch (err) {
-					this.log.error({
-						action: "handler.error",
-						message: "user handler threw",
-						error: err instanceof Error ? err : new Error(String(err))
-					});
-				}
+			const r = await attempt(() => Promise.resolve(handler(event)));
+			if (r instanceof Error) this.log.error({
+				action: "handler.error",
+				message: safeErrorMessage({ error: r }),
+				error: r
 			});
-		}
-	}
-	setStatus(next, detail) {
-		if (this.currentStatus === next) return;
-		this.log.info({
-			action: "status",
-			message: `${this.currentStatus} → ${next}${detail ? ` (${detail})` : ""}`
 		});
-		this.currentStatus = next;
-		this.options.onStatus?.(next, detail);
+	}
+	safeExtractMeta(notification) {
+		const result = attempt(() => flumeExtractGitHubMeta(notification));
+		if (result instanceof Error) {
+			const error = safeNormalizeError({ value: result });
+			this.log.warn({
+				action: "meta.extract.error",
+				message: safeErrorMessage({ error }),
+				error,
+				detail: { notificationId: notification.id }
+			});
+			return { event_type: "notification" };
+		}
+		return result;
 	}
 };
 //#endregion
-export { FlumeGitHubNotificationSchema, FlumeGitHubPoller, FlumeGitHubSeenCache, FlumeGitHubSource, extractGitHubMeta };
+export { FlumeGitHubSource, flumeExtractGitHubMeta };

package/dist/{http-error-BtXonO-W.js → http-error-CPSKoSie.js}

@@ -2,7 +2,7 @@
 var FlumeHttpError = class extends Error {
 	status;
 	constructor(props) {
-		super(props.message);
+		super(props.message, props.cause === void 0 ? void 0 : { cause: props.cause });
 		this.name = "FlumeHttpError";
 		this.status = props.status;
 		Object.freeze(this);