@interactive-inc/flume 0.4.0 → 0.9.0

package/dist/discord.js

@@ -1,7 +1,8 @@
-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 FlumeConnectionError } from "./connection-error-HUO3PC3G.js";
-import { a as FlumeReconnector, i as resolveFlumeReconnectConfig, n as isRecord, o as safeRandom, r as scheduleFlumeReconnect, t as safeStringify } from "./safe-stringify-BWS-uXZP.js";
-import { i as safeJsonParse, n as FlumeStatusEmitter, r as FlumeSignalRegistry, t as FlumeSerialQueue } from "./serial-queue-B9LoBc64.js";
+import { a as FlumeStartError, c as safeNormalizeError, i as safeNow, l as safeErrorMessage, n as safeInvokeCallback, o as FlumeParseError, r as FlumeLogger, s as attempt, t as FlumeSource } from "./flume-source.js";
+import { t as FlumeConnectionError } from "./connection-error.js";
+import { i as safeRandom, n as scheduleFlumeReconnect, r as FlumeReconnector, t as safeStringify } from "./safe-stringify.js";
+import { t as isRecord } from "./is-record.js";
+import { t as safeJsonParse } from "./safe-json-parse.js";
 import { z } from "zod/v4";
 //#region lib/discord/discord-gateway-session.ts
 var FlumeDiscordGatewaySession = class FlumeDiscordGatewaySession {
@@ -647,89 +648,38 @@ function flumeExtractDiscordMeta(eventName, eventData) {
 //#endregion
 //#region lib/discord/discord-source.ts
 const DEFAULT_INTENTS = FlumeDiscordGatewayIntents.Guilds | FlumeDiscordGatewayIntents.GuildMessages | FlumeDiscordGatewayIntents.DirectMessages;
-var FlumeDiscordSource = class {
+var FlumeDiscordSource = class extends FlumeSource {
 	options;
 	name = "discord";
 	gateway = null;
 	reconnector = 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: "discord",
-			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
-		});
-		const rc = resolveFlumeReconnectConfig(options.reconnect);
-		if (rc) this.reconnector = new FlumeReconnector({
-			...rc,
-			log: this.log,
-			deps: this.deps
-		});
 	}
-	async start(handler, options) {
-		if (this.signals.isAnyAborted(this.options.signal) || this.signals.isAnyAborted(options?.signal)) return new FlumeStartError("Discord source: signal already aborted");
-		if (!this.hasWebSocket()) return new FlumeStartError("Discord source: deps.WebSocket is null (no WebSocket runtime available)");
-		this.signals.register(this.options.signal);
-		this.signals.register(options?.signal);
-		this.handler = handler;
-		this.log.info({
-			action: "source.start",
-			message: "starting Discord source"
+	async connect(ctx) {
+		if (!this.hasWebSocket(ctx)) return new FlumeStartError("Discord source: deps.WebSocket is null (no WebSocket runtime available)");
+		if (ctx.reconnect && !this.reconnector) this.reconnector = new FlumeReconnector({
+			...ctx.reconnect,
+			log: ctx.log,
+			deps: ctx.deps
 		});
-		return await this.connectInternal();
+		return await this.connectInternal(ctx);
 	}
-	async stop() {
-		this.signals.unregisterAll();
-		this.log.info({
-			action: "source.stop",
-			message: "stopping Discord source"
-		});
-		if (this.reconnector && !this.reconnector.aborted) this.log.debug({
+	disconnect() {
+		if (this.reconnector && !this.reconnector.aborted) this.context?.log.debug({
 			action: "reconnect.cancel",
 			message: "aborting reconnector"
 		});
 		this.reconnector?.cancel();
 		this.gateway?.disconnect();
-		await this.queue.drain();
 		this.gateway = null;
-		this.handler = null;
-		this.statusEmitter.set("disconnected");
 	}
-	status() {
-		return this.statusEmitter.value;
-	}
-	hasWebSocket() {
-		const result = attempt(() => Boolean(this.deps.WebSocket));
+	hasWebSocket(ctx) {
+		const result = attempt(() => Boolean(ctx.deps.WebSocket));
 		if (result instanceof Error) {
 			const error = safeNormalizeError({ value: result });
-			this.log.error({
+			ctx.log.error({
 				action: "deps.web-socket.read.error",
 				message: safeErrorMessage({ error }),
 				error
@@ -738,55 +688,45 @@ var FlumeDiscordSource = class {
 		}
 		return result;
 	}
-	async connectInternal(resumeUrl) {
-		this.statusEmitter.set("connecting");
+	async connectInternal(ctx, resumeUrl) {
+		this.setStatus("connecting");
 		this.gateway = new FlumeDiscordGateway({
 			token: this.options.token,
 			intents: this.options.intents ?? DEFAULT_INTENTS,
-			onLog: this.options.onLog,
-			deps: this.deps,
-			onDispatch: (eventName, eventData) => this.handleDispatch(eventName, eventData),
-			onStatus: (status) => this.handleGatewayStatus(status)
+			onLog: ctx.log.handler,
+			deps: ctx.deps,
+			onDispatch: (eventName, eventData) => this.dispatch(ctx, eventName, eventData),
+			onStatus: (status) => this.handleGatewayStatus(ctx, status)
 		});
 		const error = await this.gateway.connect(resumeUrl);
 		if (error instanceof FlumeConnectionError) {
-			this.log.error({
+			ctx.log.error({
 				action: "connect.failed",
 				message: safeErrorMessage({ error }),
 				error
 			});
 			if (this.gateway.isStopped || !this.reconnector || this.reconnector.aborted) {
-				this.statusEmitter.set("disconnected");
+				this.setStatus("disconnected");
 				return error;
 			}
-			this.scheduleReconnect();
+			this.scheduleReconnect(ctx);
 		}
 		return null;
 	}
-	handleDispatch(eventName, eventData) {
-		const handler = this.handler;
-		if (!handler) return;
-		this.queue.add(async () => {
-			const event = {
-				source: "discord",
-				type: eventName,
-				data: eventData,
-				meta: this.safeExtractMeta(eventName, eventData),
-				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
-			});
+	dispatch(ctx, eventName, eventData) {
+		this.emit({
+			source: "discord",
+			type: eventName,
+			data: eventData,
+			meta: this.safeExtractMeta(ctx, eventName, eventData),
+			receivedAt: safeNow({ deps: ctx.deps })
 		});
 	}
-	safeExtractMeta(eventName, eventData) {
+	safeExtractMeta(ctx, eventName, eventData) {
 		const result = attempt(() => flumeExtractDiscordMeta(eventName, eventData));
 		if (result instanceof Error) {
 			const error = safeNormalizeError({ value: result });
-			this.log.warn({
+			ctx.log.warn({
 				action: "meta.extract.error",
 				message: safeErrorMessage({ error }),
 				error,
@@ -796,37 +736,37 @@ var FlumeDiscordSource = class {
 		}
 		return result;
 	}
-	handleGatewayStatus(status) {
+	handleGatewayStatus(ctx, status) {
 		if (status === "connected") {
-			if (this.reconnector && this.reconnector.attempt > 0) this.log.info({
+			if (this.reconnector && this.reconnector.attempt > 0) ctx.log.info({
 				action: "reconnect.reset",
 				message: `cleared ${this.reconnector.attempt} attempts`
 			});
 			this.reconnector?.reset();
-			this.statusEmitter.set("connected");
+			this.setStatus("connected");
 			return;
 		}
 		if (this.gateway?.isStopped) {
-			this.statusEmitter.set("disconnected");
+			this.setStatus("disconnected");
 			return;
 		}
-		this.scheduleReconnect();
+		this.scheduleReconnect(ctx);
 	}
-	scheduleReconnect() {
+	scheduleReconnect(ctx) {
 		const url = this.gateway?.session.resumeUrl ?? void 0;
 		scheduleFlumeReconnect({
 			reconnector: this.reconnector,
-			log: this.log,
-			setStatus: (status) => this.statusEmitter.set(status),
+			log: ctx.log,
+			setStatus: (status) => this.setStatus(status),
 			retry: () => {
-				this.connectInternal(url).catch((err) => {
+				this.connectInternal(ctx, url).catch((err) => {
 					const error = safeNormalizeError({ value: err });
-					this.log.error({
+					ctx.log.error({
 						action: "reconnect.unhandled",
 						message: safeErrorMessage({ error }),
 						error
 					});
-					this.statusEmitter.set("disconnected");
+					this.setStatus("disconnected");
 				});
 			}
 		});

package/dist/flume-source.d.ts

@@ -0,0 +1,269 @@
+import { z } from "zod/v4";
+
+//#region lib/logger.d.ts
+type Props = {
+  source: string;
+  handler?: FlumeLogHandler;
+  deps: Pick<FlumeRuntimeDeps, "now">;
+};
+/**
+ * 構造化ログを onLog に流す。handler が throw / reject してもループは継続する
+ */
+declare class FlumeLogger {
+  private readonly props;
+  constructor(props: Props);
+  debug(entry: FlumeLogInput): void;
+  info(entry: FlumeLogInput): void;
+  warn(entry: FlumeLogInput): void;
+  error(entry: FlumeLogInput): void;
+  get handler(): FlumeLogHandler | undefined;
+  child(source: string): FlumeLogger;
+  private emit;
+}
+//#endregion
+//#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>;
+}, z.core.$strip>;
+//#endregion
+//#region lib/github/github-notification-schema.d.ts
+declare const FlumeGitHubNotificationSchema: z.ZodObject<{
+  id: z.ZodString;
+  reason: z.ZodString;
+  unread: z.ZodBoolean;
+  updated_at: z.ZodString;
+  subject: z.ZodObject<{
+    title: z.ZodString;
+    url: z.ZodNullable<z.ZodString>;
+    type: z.ZodString;
+  }, z.core.$strip>;
+  repository: z.ZodObject<{
+    full_name: z.ZodString;
+  }, z.core.$strip>;
+}, z.core.$strip>;
+//#endregion
+//#region lib/slack/slack-connection-response-schema.d.ts
+declare const FlumeSlackConnectionResponseSchema: z.ZodObject<{
+  ok: z.ZodBoolean;
+  url: z.ZodOptional<z.ZodString>;
+  error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+//#endregion
+//#region lib/slack/slack-envelope-schema.d.ts
+declare const FlumeSlackEnvelopeSchema: z.ZodObject<{
+  envelope_id: z.ZodString;
+  type: z.ZodString;
+  payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  accepts_response_payload: z.ZodOptional<z.ZodBoolean>;
+  retry_attempt: z.ZodOptional<z.ZodNumber>;
+  retry_reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+//#endregion
+//#region lib/types.d.ts
+type FlumeTimerHandle = unknown;
+type FlumeRuntimeDeps = {
+  fetch(url: string | URL, init?: RequestInit): Promise<Response>;
+  WebSocket: (new (url: string | URL) => WebSocket) | null;
+  now(): number;
+  random(): number;
+  setTimeout(fn: () => void, ms: number): FlumeTimerHandle;
+  clearTimeout(id: FlumeTimerHandle): void;
+  setInterval(fn: () => void, ms: number): FlumeTimerHandle;
+  clearInterval(id: FlumeTimerHandle): void;
+};
+type FlumeSourceName = "discord" | "slack" | "github" | "time";
+type FlumeDiscordEvent = {
+  source: "discord";
+  type: string;
+  data: Record<string, unknown>;
+  meta: Record<string, string>;
+  receivedAt: number;
+};
+type FlumeSlackEvent = {
+  source: "slack";
+  type: string;
+  data: Record<string, unknown>;
+  meta: Record<string, string>;
+  receivedAt: number;
+};
+type FlumeGitHubEvent = {
+  source: "github";
+  type: "notification";
+  data: FlumeGitHubNotification;
+  meta: Record<string, string>;
+  receivedAt: number;
+};
+type FlumeTimeEvent = {
+  source: "time";
+  type: string;
+  data: Record<string, unknown>;
+  meta: Record<string, string>;
+  receivedAt: number;
+};
+type FlumeEvent = FlumeDiscordEvent | FlumeSlackEvent | FlumeGitHubEvent | FlumeTimeEvent;
+type FlumeEventHandler = (event: FlumeEvent) => void | Promise<void>;
+type FlumeStreamItem = {
+  kind: "event";
+  event: FlumeEvent;
+} | {
+  kind: "log";
+  log: FlumeLog;
+};
+type FlumeStreamHandler = (item: FlumeStreamItem) => void;
+type FlumeStreamOverflow = "drop-oldest" | "drop-newest";
+type FlumeStreamOptions = {
+  /** バッファ上限 (既定 1000)。consumer が遅れて溢れたら onOverflow に従う */buffer?: number; /** バッファ溢れ時の方針 (既定 "drop-oldest") */
+  onOverflow?: FlumeStreamOverflow;
+};
+type FlumeStatus = "disconnected" | "connecting" | "connected" | "reconnecting";
+type FlumeSourceStatus = {
+  /**
+   * 多くは `FlumeSourceName` のいずれかだが、`source.name` getter が throw する
+   * 第三者 FlumeSource 実装に備えて `string` まで広げてある (fallback で `"?"`)
+   */
+  source: string;
+  status: FlumeStatus;
+};
+type FlumeLogLevel = "debug" | "info" | "warn" | "error";
+type FlumeLog = {
+  level: FlumeLogLevel;
+  source: string;
+  action: string;
+  message: string;
+  error?: Error;
+  detail?: Record<string, unknown>;
+  timestamp: number;
+};
+type FlumeLogHandler = (log: FlumeLog) => void;
+/** error レベルのログだけを受け取る (Sentry など error 専用の送信先向け) */
+type FlumeErrorHandler = (log: FlumeLog) => void;
+type FlumeLogInput = {
+  action: string;
+  message: string;
+  error?: Error;
+  detail?: Record<string, unknown>;
+};
+type FlumeReconnectOptions = {
+  maxAttempts?: number;
+  baseDelay?: number;
+  maxDelay?: number;
+};
+type FlumeReconnectConfig = {
+  maxAttempts: number;
+  baseDelay: number;
+  maxDelay: number;
+};
+type FlumeSourceLocalStatusHandler = (status: FlumeStatus, detail?: string) => void;
+type FlumeSourceStartContext = {
+  onEvent: FlumeEventHandler;
+  log: FlumeLogger;
+  deps: FlumeRuntimeDeps; /** Source 内部の status 遷移ブリッジ。Flume 公開 API に status callback は無く、遷移は log に出る */
+  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 が未設定なら省略される。
+   */
+  signal?: AbortSignal;
+};
+type FlumeDiscordSourceOptions = {
+  token: string;
+  intents?: number;
+};
+type FlumeSlackSourceOptions = {
+  appToken: string;
+  /**
+   * Bot token (`xoxb-`). Slack Socket Mode (受信) には不要だが、ホスト側 (返信や
+   * `auth.test` での self 検出) が必ず使うため型で保持を強制する
+   */
+  botToken: string;
+};
+type FlumeGitHubSourceOptions = {
+  token: string;
+  pollInterval?: number;
+};
+type FlumeTimeTick = {
+  /** cron がマッチした壁時計時刻 (epoch ms)。setTimeout の発火実時刻ではなく予定時刻 */firedAt: number;
+  cron: string;
+};
+/**
+ * tick ごとに emit するイベントの上書き内容。全フィールド optional。
+ * 省略フィールドは既定値 (type: "tick" / data: tick 内容 / meta: { cron }) になる
+ */
+type FlumeTimeMessage = {
+  type?: string;
+  data?: Record<string, unknown>;
+  meta?: Record<string, string>;
+};
+type FlumeTimeSourceOptions = {
+  /** 5 フィールド cron 式 (minute hour day-of-month month day-of-week)。壁時計 (local time) 基準 */cron: string;
+  message?: (tick: FlumeTimeTick) => FlumeTimeMessage;
+};
+type FlumeGatewayMessage = z.infer<typeof FlumeGatewayMessageSchema>;
+type FlumeSlackEnvelope = z.infer<typeof FlumeSlackEnvelopeSchema>;
+type FlumeSlackConnectionResponse = z.infer<typeof FlumeSlackConnectionResponseSchema>;
+type FlumeGitHubNotification = z.infer<typeof FlumeGitHubNotificationSchema>;
+//#endregion
+//#region lib/flume-source.d.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 { ... }
+ * }
+ * ```
+ */
+declare abstract class FlumeSource {
+  abstract readonly name: string;
+  private consumed;
+  private stopped;
+  private ctx;
+  private statusEmitter;
+  private readonly queue;
+  start(ctx: FlumeSourceStartContext): Promise<Error | null>;
+  stop(): Promise<void>;
+  status(): FlumeStatus;
+  /**
+   * subclass が受信した protocol イベントを `FlumeEvent` として handler へ流す。
+   * handler の throw / async reject は queue 内で catch + log し、後続を止めない
+   */
+  protected emit(event: FlumeEvent): void;
+  /**
+   * subclass が protocol 状態遷移をユーザーに通知する。同一 (status, detail) の連続は冪等
+   */
+  protected setStatus(status: FlumeStatus, detail?: string): void;
+  /** subclass が現在の status を読みたい場合 */
+  protected get currentStatus(): FlumeStatus;
+  /** subclass が start ctx を再参照したい場合 (stop 後は null) */
+  protected get context(): FlumeSourceStartContext | null;
+  /** 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 };