@interactive-inc/flume 0.9.4 → 0.10.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { A as FlumeStreamOverflow, C as FlumeSourceName, D as FlumeStreamHandler, E as FlumeStatus, F as FlumeTimerHandle, I as FlumeLogger, M as FlumeTimeMessage, N as FlumeTimeSourceOptions, O as FlumeStreamItem, P as FlumeTimeTick, S as FlumeSourceLocalStatusHandler, T as FlumeSourceStatus, _ as FlumeRuntimeDeps, a as FlumeEvent, b as FlumeSlackEvent, c as FlumeGitHubEvent, d as FlumeLog, f as FlumeLogHandler, g as FlumeReconnectOptions, h as FlumeReconnectConfig, i as FlumeErrorHandler, j as FlumeTimeEvent, k as FlumeStreamOptions, l as FlumeGitHubNotification, m as FlumeLogLevel, n as FlumeDiscordEvent, o as FlumeEventHandler, p as FlumeLogInput, r as FlumeDiscordSourceOptions, s as FlumeGatewayMessage, t as FlumeSource, u as FlumeGitHubSourceOptions, v as FlumeSlackConnectionResponse, w as FlumeSourceStartContext, x as FlumeSlackSourceOptions, y as FlumeSlackEnvelope } from "./flume-source.js";
+import { A as FlumeStatePersister, B as FlumeTimeTick, C as FlumeSlackEnvelope, D as FlumeSourceName, E as FlumeSourceLocalStatusHandler, F as FlumeStreamOverflow, H as FlumeLogger, I as FlumeTimeEvent, L as FlumeTimeMessage, M as FlumeStreamHandler, N as FlumeStreamItem, O as FlumeSourceStartContext, P as FlumeStreamOptions, R as FlumeTimeSourceOptions, S as FlumeSlackConnectionResponse, T as FlumeSlackSourceOptions, V as FlumeTimerHandle, _ as FlumeLogInput, a as FlumeCustomEvent, b as FlumeReconnectOptions, c as FlumeErrorHandler, d as FlumeGatewayMessage, f as FlumeGitHubEvent, g as FlumeLogHandler, h as FlumeLog, i as FlumeConfluenceItemHandler, j as FlumeStatus, k as FlumeSourceStatus, l as FlumeEvent, m as FlumeGitHubSourceOptions, n as FlumeCatchupPolicy, o as FlumeDiscordEvent, p as FlumeGitHubNotification, r as FlumeConfluenceItem, s as FlumeDiscordSourceOptions, t as FlumeSource, u as FlumeEventHandler, v as FlumeLogLevel, w as FlumeSlackEvent, x as FlumeRuntimeDeps, y as FlumeReconnectConfig, z as FlumeTimeSourceState } from "./flume-source.js";
 import { t as FlumeParseError } from "./parse-error.js";
 
 //#region lib/deps.d.ts
@@ -29,14 +29,18 @@ declare class FlumeConnectionError extends Error {
 }
 //#endregion
 //#region lib/errors/http-error.d.ts
-type Props$4 = {
+type Props$6 = {
   message: string;
   status: number;
-  cause?: unknown;
+  cause?: unknown; /** API 固有のエラーコード (Slack の `invalid_auth` 等)。呼び出し側が恒久/一時を分類するのに使う */
+  code?: string | null; /** サーバーが `Retry-After` 等で指示した再試行までの待機時間 (ms) */
+  retryAfterMs?: number | null;
 };
 declare class FlumeHttpError extends Error {
   readonly status: number;
-  constructor(props: Props$4);
+  readonly code: string | null;
+  readonly retryAfterMs: number | null;
+  constructor(props: Props$6);
 }
 //#endregion
 //#region lib/errors/start-error.d.ts
@@ -48,37 +52,57 @@ declare class FlumeStartError extends Error {
 }
 //#endregion
 //#region lib/flume-stream.d.ts
-type Props$3 = {
+type Props$5 = {
   buffer: number;
   onOverflow: FlumeStreamOverflow;
-  onClose: () => void;
+  onClose: () => void; /** buffer 溢れで item を落とした時の通知 (この stream で最初の 1 回だけ発火する) */
+  onDrop?: (input: {
+    dropped: number;
+  }) => void;
 };
 /**
  * push (`FlumeStreamHub.publish`) を pull (`for await`) に変換する async iterator。
  * consumer が待っていれば即 resolve、いなければ buffer に積み、溢れたら onOverflow に従う。
- * `return()` (break / 例外) と hub.close() のどちらでも自然に done へ落ちる
+ * hub.close() ではバッファ済み item を吐き切ってから done へ落ちる (graceful tail drain)。
+ * consumer 側の `return()` (break / 例外) はバッファを破棄して即 done になる (iterator 仕様)。
+ * drop の観測は onDrop 経由 — drop 通知自体が firehose に還流して再帰しないよう初回のみ発火
  */
 declare class FlumeStream implements AsyncIterableIterator<FlumeStreamItem> {
   private readonly props;
   private readonly items;
   private readonly resolvers;
   private closed;
-  constructor(props: Props$3);
+  private droppedCount;
+  constructor(props: Props$5);
   push(item: FlumeStreamItem): void;
   close(): void;
+  get dropped(): number;
   next(): Promise<IteratorResult<FlumeStreamItem>>;
   return(): Promise<IteratorResult<FlumeStreamItem>>;
+  throw(error?: unknown): Promise<IteratorResult<FlumeStreamItem>>;
   [Symbol.asyncIterator](): AsyncIterableIterator<FlumeStreamItem>;
+  private recordDrop;
 }
 //#endregion
 //#region lib/flume-stream-hub.d.ts
+type Props$4 = {
+  /** buffer 溢れ通知。Flume が warn ログへ橋渡しする */onDrop?: (input: {
+    dropped: number;
+  }) => void;
+};
 /**
  * firehose (`onEvent` / `stream()`) の item を複数の pull consumer へ fan-out する内部ハブ。
  * subscriber が居なければ publish は実質 no-op。Flume 停止時に close() で全 stream を終端する
  */
 declare class FlumeStreamHub {
+  private readonly props;
   private readonly streams;
+  private readonly startupItems;
+  private startupDropNotified;
+  private hasSubscribed;
   private closed;
+  constructor(props?: Props$4);
+  get isClosed(): boolean;
   publish(item: FlumeStreamItem): void;
   subscribe(options?: FlumeStreamOptions): FlumeStream;
   close(): void;
@@ -89,7 +113,7 @@ type FlumeCloseError = {
   source: string;
   error: Error;
 };
-type Props$2 = {
+type Props$3 = {
   finalStatuses: ReadonlyArray<FlumeSourceStatus>;
   closeErrors: ReadonlyArray<FlumeCloseError>;
 };
@@ -99,9 +123,10 @@ type Props$2 = {
  * きれいに close したか / どれが失敗したか」を直接判定できる
  */
 declare class FlumeClosed {
-  private readonly props;
   readonly kind: "closed";
-  constructor(props: Props$2);
+  private readonly finalStatuses;
+  private readonly closeErrors;
+  constructor(props: Props$3);
   statuses(): ReadonlyArray<FlumeSourceStatus>;
   /**
    * `runClose` 中に `source.stop()` が rejected で settle した source の名前と
@@ -111,12 +136,42 @@ declare class FlumeClosed {
   errors(): ReadonlyArray<FlumeCloseError>;
 }
 //#endregion
+//#region lib/utils/serial-queue.d.ts
+type OverflowInput = {
+  dropped: number;
+  depth: number;
+};
+type Props$2 = {
+  maxDepth?: number;
+  onOverflow?: (input: OverflowInput) => void;
+};
+/**
+ * 投入順を保ったまま task を直列実行する。各 task は前の完了を待ってから走る。
+ * task が throw しても後続には伝播しない (キュー自体は止まらない)。
+ * maxDepth を超えた場合は新規 task を drop し onOverflow に通知。
+ * cancel() 後は add() が no-op になり、既に積まれた未実行 task も実行せずに流れ落ちる。
+ * drain() は待機中に追加された task も含めてキューが空になるまで待つ
+ */
+declare class FlumeSerialQueue {
+  private readonly props;
+  private chain;
+  private depth;
+  private cancelled;
+  constructor(props?: Props$2);
+  add(task: () => Promise<void>): Promise<void>;
+  drain(): Promise<void>;
+  cancel(): void;
+  size(): number;
+  isCancelled(): boolean;
+}
+//#endregion
 //#region lib/flume-running.d.ts
 type Props$1 = {
   sources: ReadonlyArray<FlumeSource>;
   signal?: AbortSignal;
   log: FlumeLogger;
   hub: FlumeStreamHub;
+  callbackQueue: FlumeSerialQueue;
 };
 /**
  * 稼働中の Flume。close() で FlumeClosed へ遷移する。signal が abort されると自動 close。
@@ -139,9 +194,10 @@ declare class FlumeRunning {
    */
   stream(options?: FlumeStreamOptions): AsyncIterableIterator<FlumeStreamItem>;
   /**
-   * Host が `Flume({ signal })` で渡した AbortSignal をそのまま公開する。
+   * `Flume({ signal })` に渡された AbortSignal をそのまま公開する。
    * 直接の controller を持っていない呼び出し元が `running.signal?.aborted`
-   * で abort 状態を確認できる
+   * で abort 状態を確認できる。`FlumeConfluence` 経由で開かれたグループでは
+   * host の signal ではなく confluence 内部の timeout controller の signal になる点に注意
    */
   get signal(): AbortSignal | undefined;
   private runClose;
@@ -161,14 +217,19 @@ type FlumeOptions = {
   onError?: FlumeErrorHandler;
   signal?: AbortSignal;
   deps?: FlumeRuntimeDeps;
-  reconnect?: FlumeReconnectOptions;
+  /**
+   * 再接続方針。未指定 / false は無効 (接続断で source は disconnected のまま)。
+   * true は既定値 (maxAttempts: Infinity / baseDelay: 1s / maxDelay: 30s)。
+   * 常駐リスナー用途では明示的に有効化を推奨
+   */
+  reconnect?: boolean | FlumeReconnectOptions;
 };
 /**
  * 起動前の Flume。`open()` で `FlumeRunning` へ遷移する。
  * コンストラクタは単一オブジェクト `{ sources, ...options }` を受け取る (`sources` のみ必須)。
  * events も全ログも 1 本の firehose (`onEvent` push / `stream()` pull) に流れ、購読側が filter する。
- * いずれかの source 失敗時は既に成功した source を全て `stop()` してロールバックし
- * `FlumeStartError` を返す。
+ * いずれかの source 失敗時は全 source を `stop()` してロールバックし `FlumeStartError` を返す
+ * (失敗した source も半接続状態のリソースを持ち得るため、成功分だけでなく全数を stop する)。
  * `source.start()` / `source.stop()` の sync throw も `Promise.resolve().then` 経由で
  * Promise rejection に正規化して `allSettled` で捕捉する (`open()` は決して reject しない)
  */
@@ -180,49 +241,103 @@ declare class Flume {
   private readonly sources;
   private readonly sourceEventHandler;
   private readonly hub;
+  private readonly callbackQueue;
   constructor(options: FlumeOptions);
+  /**
+   * stream の buffer 溢れ通知 (stream ごとに初回 1 回)。
+   * firehose (hub) には流さない — 溢れている stream 自身に還流して実イベントを
+   * さらに追い出す自己破壊になるため、push の `onEvent` にだけ warn log として届ける
+   */
+  private notifyStreamOverflow;
   /** source が受信したログを firehose へ流す handler。error は onError にも分岐する */
   private buildLogHandler;
   /**
    * firehose の単一 sink: pull の hub と push の onEvent の両方へ item を配る。
+   * close 後の遅延 emit (stop 中の straggler) は push 側にも流さない (pull 側と対称にする)。
    * onEvent への転送は this.log を経由しない (経由すると log item 経路で再帰する) ため
    * 例外をここで握り潰す
    */
   private emitItem;
+  private enqueueCallback;
   open(): Promise<FlumeRunning | FlumeStartError>;
   private guardOpen;
+  /** reconnect オプションの解決。throwing getter を持つ hostile 入力でも open() を reject させない */
+  private resolveReconnect;
   private isSignalAborted;
   private sourceName;
   private safeStart;
   private rollback;
+  private logRollbackFailure;
 }
 //#endregion
 //#region lib/flume-confluence.d.ts
 type Props = {
-  /** 配下の全 Flume の firehose をここへ合流させる単一 sink */onEvent?: FlumeStreamHandler; /** error レベル log だけ (全 Flume 共通) */
+  /**
+   * 配下の全 Flume の firehose をここへ合流させる単一 sink。
+   * 各 item には発信元グループの id が `groupId` としてスタンプされる
+   */
+  onEvent?: FlumeConfluenceItemHandler; /** error レベル log だけ (全 Flume 共通) */
   onError?: FlumeErrorHandler;
   deps?: FlumeRuntimeDeps;
-  reconnect?: FlumeReconnectOptions;
+  reconnect?: boolean | FlumeReconnectOptions;
 };
 /**
  * 複数の `Flume` を束ねて動的に増減させる上位レイヤー。各 Flume は immutable のまま、
  * `add()` で新しいグループを起動し `remove()` で個別に停止する。全グループの firehose は
- * `onEvent` 1 本に合流する。Flume 本体の FSM / rollback / reconnect はそのまま再利用される。
+ * `onEvent` 1 本に合流し、各 item には発信元グループ id が `groupId` としてスタンプされる。
+ * Flume 本体の FSM / rollback / reconnect はそのまま再利用される。
+ *
+ * `replace(id, sources)` は同じ id のグループを差し替える。新グループを先に起動し、
+ * 起動成功時にのみ旧グループを停止するので連続稼働を維持できる (token rotation 用途)。
+ * 起動失敗時は旧グループはそのまま走り続ける。
+ * 注意: 失敗した replace / add に渡した source インスタンスは consumed になるため、
+ * リトライには新しいインスタンスを構築する必要がある。
  *
- * id はグループの管理ハンドル (add/remove 用)。合流ストリーム自体は id を持たず、
- * item の中の source 名で発信元を判別する。throw しない流儀に従い `add()` は `Error | null` を返す
+ * `closeAll()` は終端操作。以後の `add()` / `replace()` は拒否され、closeAll と並行して
+ * 起動中だったグループも abort して完了を待つ (シャットダウン後に誰にも止められない
+ * グループが残らない)。
+ *
+ * throw しない流儀に従い `add()` / `replace()` は `Error | null` を返す
  */
 declare class FlumeConfluence {
   private readonly props;
   private readonly running;
+  /** open() を await 中でまだ Map に commit されていないグループの id (add 重複と remove 追跡用) */
+  private readonly pendingIds;
+  private readonly removedWhilePending;
+  private readonly pendingOpens;
+  private isClosedFlag;
+  private readonly deps;
   constructor(props?: Props);
+  get isClosed(): boolean;
   /** sources を 1 グループとして起動。id 重複や起動失敗は `Error` で返す (throw しない) */
   add(id: string, sources: ReadonlyArray<FlumeSource>): Promise<Error | null>;
-  /** 指定グループだけ close。他グループは無停止。未知の id は no-op */
+  /**
+   * 既存グループを新しい sources で差し替える。新グループを先に起動し、成功時のみ旧を停止する。
+   * 起動失敗 / replaceTimeoutMs (既定 10s) 経過時は新グループを破棄し旧を走らせたまま返す。
+   * 旧グループが存在しない場合は `Error` を返す (replace は add と違ってグループの存在を前提とする)
+   */
+  replace(id: string, sources: ReadonlyArray<FlumeSource>, options?: {
+    readonly replaceTimeoutMs?: number;
+  }): Promise<Error | null>;
+  /**
+   * 指定グループだけ close。他グループは無停止。未知の id は no-op。
+   * 起動中 (add が open を await 中) の id は commit 時点で破棄されるよう予約する
+   */
   remove(id: string): Promise<void>;
+  /** 終端操作。全グループを close し、以後の add / replace を拒否する */
   closeAll(): Promise<void>;
   has(id: string): boolean;
   ids(): ReadonlyArray<string>;
+  /**
+   * 1 グループ分の Flume を開いて FlumeRunning を返す。timeoutMs を指定すると AbortSignal を
+   * ctx.signal として各 source へ注入し、超過時に abort して進行中の connect ごと中止する
+   * (source 側は base クラスが signal を購読して stop() を発火する)。
+   * 失敗時の rollback は Flume 本体に任せる
+   */
+  private openGroup;
+  private createPendingOpen;
+  private wrapOnEvent;
 }
 //#endregion
-export { Flume, type FlumeCloseError, FlumeClosed, FlumeConfluence, FlumeConnectionError, type FlumeDiscordEvent, type FlumeDiscordSourceOptions, type FlumeErrorHandler, type FlumeEvent, type FlumeEventHandler, type FlumeGatewayMessage, type FlumeGitHubEvent, type FlumeGitHubNotification, type FlumeGitHubSourceOptions, FlumeHttpError, type FlumeLog, type FlumeLogHandler, type FlumeLogInput, type FlumeLogLevel, type FlumeOptions, FlumeParseError, type FlumeReconnectConfig, type FlumeReconnectOptions, FlumeRunning, type FlumeRuntimeDeps, type FlumeSlackConnectionResponse, type FlumeSlackEnvelope, type FlumeSlackEvent, type FlumeSlackSourceOptions, FlumeSource, type FlumeSourceLocalStatusHandler, type FlumeSourceName, type FlumeSourceStartContext, type FlumeSourceStatus, FlumeStartError, type FlumeStatus, type FlumeStreamHandler, type FlumeStreamItem, type FlumeStreamOptions, type FlumeStreamOverflow, type FlumeTimeEvent, type FlumeTimeMessage, type FlumeTimeSourceOptions, type FlumeTimeTick, type FlumeTimerHandle, createFlumeDefaultDeps };
+export { Flume, type FlumeCatchupPolicy, type FlumeCloseError, FlumeClosed, FlumeConfluence, type FlumeConfluenceItem, type FlumeConfluenceItemHandler, FlumeConnectionError, type FlumeCustomEvent, type FlumeDiscordEvent, type FlumeDiscordSourceOptions, type FlumeErrorHandler, type FlumeEvent, type FlumeEventHandler, type FlumeGatewayMessage, type FlumeGitHubEvent, type FlumeGitHubNotification, type FlumeGitHubSourceOptions, FlumeHttpError, type FlumeLog, type FlumeLogHandler, type FlumeLogInput, type FlumeLogLevel, type FlumeOptions, FlumeParseError, type FlumeReconnectConfig, type FlumeReconnectOptions, FlumeRunning, type FlumeRuntimeDeps, type FlumeSlackConnectionResponse, type FlumeSlackEnvelope, type FlumeSlackEvent, type FlumeSlackSourceOptions, FlumeSource, type FlumeSourceLocalStatusHandler, type FlumeSourceName, type FlumeSourceStartContext, type FlumeSourceStatus, FlumeStartError, type FlumeStatePersister, type FlumeStatus, type FlumeStreamHandler, type FlumeStreamItem, type FlumeStreamOptions, type FlumeStreamOverflow, type FlumeTimeEvent, type FlumeTimeMessage, type FlumeTimeSourceOptions, type FlumeTimeSourceState, type FlumeTimeTick, type FlumeTimerHandle, createFlumeDefaultDeps };