@interactive-inc/flume 0.10.1 → 0.11.0

package/dist/index.d.ts

@@ -29,7 +29,7 @@ declare class FlumeConnectionError extends Error {
 }
 //#endregion
 //#region lib/errors/http-error.d.ts
-type Props$6 = {
+type Props$11 = {
   message: string;
   status: number;
   cause?: unknown; /** API 固有のエラーコード (Slack の `invalid_auth` 等)。呼び出し側が恒久/一時を分類するのに使う */
@@ -40,7 +40,7 @@ declare class FlumeHttpError extends Error {
   readonly status: number;
   readonly code: string | null;
   readonly retryAfterMs: number | null;
-  constructor(props: Props$6);
+  constructor(props: Props$11);
 }
 //#endregion
 //#region lib/errors/start-error.d.ts
@@ -52,7 +52,7 @@ declare class FlumeStartError extends Error {
 }
 //#endregion
 //#region lib/flume-stream.d.ts
-type Props$5 = {
+type Props$10 = {
   buffer: number;
   onOverflow: FlumeStreamOverflow;
   onClose: () => void; /** buffer 溢れで item を落とした時の通知 (この stream で最初の 1 回だけ発火する) */
@@ -73,10 +73,9 @@ declare class FlumeStream implements AsyncIterableIterator<FlumeStreamItem> {
   private readonly resolvers;
   private closed;
   private droppedCount;
-  constructor(props: Props$5);
+  constructor(props: Props$10);
   push(item: FlumeStreamItem): void;
   close(): void;
-  get dropped(): number;
   next(): Promise<IteratorResult<FlumeStreamItem>>;
   return(): Promise<IteratorResult<FlumeStreamItem>>;
   throw(error?: unknown): Promise<IteratorResult<FlumeStreamItem>>;
@@ -85,7 +84,7 @@ declare class FlumeStream implements AsyncIterableIterator<FlumeStreamItem> {
 }
 //#endregion
 //#region lib/flume-stream-hub.d.ts
-type Props$4 = {
+type Props$9 = {
   /** buffer 溢れ通知。Flume が warn ログへ橋渡しする */onDrop?: (input: {
     dropped: number;
   }) => void;
@@ -101,7 +100,7 @@ declare class FlumeStreamHub {
   private startupDropNotified;
   private hasSubscribed;
   private closed;
-  constructor(props?: Props$4);
+  constructor(props?: Props$9);
   get isClosed(): boolean;
   publish(item: FlumeStreamItem): void;
   subscribe(options?: FlumeStreamOptions): FlumeStream;
@@ -113,7 +112,7 @@ type FlumeCloseError = {
   source: string;
   error: Error;
 };
-type Props$3 = {
+type Props$8 = {
   finalStatuses: ReadonlyArray<FlumeSourceStatus>;
   closeErrors: ReadonlyArray<FlumeCloseError>;
 };
@@ -126,7 +125,7 @@ declare class FlumeClosed {
   readonly kind: "closed";
   private readonly finalStatuses;
   private readonly closeErrors;
-  constructor(props: Props$3);
+  constructor(props: Props$8);
   statuses(): ReadonlyArray<FlumeSourceStatus>;
   /**
    * `runClose` 中に `source.stop()` が rejected で settle した source の名前と
@@ -137,59 +136,50 @@ declare class FlumeClosed {
 }
 //#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 = {
+type Props$7 = {
   sources: ReadonlyArray<FlumeSource>;
   signal?: AbortSignal;
   log: FlumeLogger;
   hub: FlumeStreamHub;
   callbackQueue: FlumeSerialQueue;
+  seal: () => void;
 };
 /**
  * 稼働中の Flume。close() で FlumeClosed へ遷移する。signal が abort されると自動 close。
  * 全ての source 呼び出し・signal 操作・status 読み取りを `attempt` 経由で扱い、
- * `runClose` の最外殻 try/catch で想定外の throw も `FlumeClosed` の resolve に変換する
+ * `runClose` の最外殻でも `attempt` を通して想定外の throw を `FlumeClosed` の resolve に変換する
  */
 declare class FlumeRunning {
   private readonly props;
   readonly kind: "running";
   private closePromise;
   private readonly onAbort;
-  constructor(props: Props$1);
+  constructor(props: Props$7);
+  /** Source の停止まで待つ。callback の完了は callback 外から drain() で待つ。 */
   close(): Promise<FlumeClosed>;
+  /**
+   * 配送済み callback とその失敗診断が完了するまで待つ。通常は close() の後に呼ぶ。
+   * onEvent / onError 内では自身の完了待ちになるため呼ばない。
+   */
+  drain(): Promise<void>;
   statuses(): ReadonlyArray<FlumeSourceStatus>;
   /**
    * 統合 firehose を pull で受け取る async iterator。`for await (const item of running.stream())`。
    * item は events + 全ログの union (`FlumeStreamItem`)。`item.kind` で判別する。
-   * close() / signal abort で iterator は自然に終了し、`break` すると hub から自動 unsubscribe する。
+   * close() / signal abort 後、callback の失敗診断まで配送して終了する。
+   * `break` すると hub から自動 unsubscribe する。
    * consumer が遅れて buffer を超えたら `onOverflow` (既定 drop-oldest) に従う
    */
   stream(options?: FlumeStreamOptions): AsyncIterableIterator<FlumeStreamItem>;
@@ -201,6 +191,7 @@ declare class FlumeRunning {
    */
   get signal(): AbortSignal | undefined;
   private runClose;
+  private closeSources;
   private snapshotStatuses;
   private sourceName;
 }
@@ -228,14 +219,15 @@ type FlumeOptions = {
  * 起動前の Flume。`open()` で `FlumeRunning` へ遷移する。
  * コンストラクタは単一オブジェクト `{ sources, ...options }` を受け取る (`sources` のみ必須)。
  * events も全ログも 1 本の firehose (`onEvent` push / `stream()` pull) に流れ、購読側が filter する。
- * いずれかの source 失敗時は全 source を `stop()` してロールバックし `FlumeStartError` を返す
- * (失敗した source も半接続状態のリソースを持ち得るため、成功分だけでなく全数を stop する)。
+ * 起動失敗時はこの open が取得した source を `stop()` してロールバックする。
+ * 半接続状態で失敗した source も含むが、再利用を拒否した source は他の所有者のため停止しない。
  * `source.start()` / `source.stop()` の sync throw も `Promise.resolve().then` 経由で
  * Promise rejection に正規化して `allSettled` で捕捉する (`open()` は決して reject しない)
  */
 declare class Flume {
   private readonly options;
   private consumed;
+  private isAcceptingItems;
   private readonly log;
   private readonly deps;
   private readonly sources;
@@ -254,12 +246,24 @@ declare class Flume {
   /**
    * firehose の単一 sink: pull の hub と push の onEvent の両方へ item を配る。
    * close 後の遅延 emit (stop 中の straggler) は push 側にも流さない (pull 側と対称にする)。
-   * onEvent への転送は this.log を経由しない (経由すると log item 経路で再帰する) ため
-   * 例外をここで握り潰す
+   * onEvent への転送は this.log を経由しない (経由すると log item 経路で再帰する)。
+   * callback failure は reportCallbackFailure が pull hub と peer callback へ直接診断する。
    */
   private emitItem;
   private enqueueCallback;
+  /**
+   * error log 専用 sink も callbackQueue に載せ、drain() が in-flight callback と
+   * その失敗診断まで drain できるようにする
+   */
+  private invokeOnError;
+  /**
+   * 観測 sink 自身の失敗は同じ sink へ戻すと再帰するため、まず pull stream へ直接 publish し、
+   * もう一方の callback にだけ転送する。peer も失敗した場合は hub-only の診断を残して終端する
+   */
+  private reportCallbackFailure;
   open(): Promise<FlumeRunning | FlumeStartError>;
+  /** 起動失敗の戻り値は callback を待たず、配送済み診断の完了後に hub を閉じる。 */
+  private finishFailedOpen;
   private guardOpen;
   /** reconnect オプションの解決。throwing getter を持つ hostile 入力でも open() を reject させない */
   private resolveReconnect;
@@ -271,7 +275,7 @@ declare class Flume {
 }
 //#endregion
 //#region lib/flume-confluence.d.ts
-type Props = {
+type Props$6 = {
   /**
    * 配下の全 Flume の firehose をここへ合流させる単一 sink。
    * 各 item には発信元グループの id が `groupId` としてスタンプされる
@@ -308,7 +312,7 @@ declare class FlumeConfluence {
   private readonly pendingOpens;
   private isClosedFlag;
   private readonly deps;
-  constructor(props?: Props);
+  constructor(props?: Props$6);
   get isClosed(): boolean;
   /** sources を 1 グループとして起動。id 重複や起動失敗は `Error` で返す (throw しない) */
   add(id: string, sources: ReadonlyArray<FlumeSource>): Promise<Error | null>;
@@ -338,6 +342,108 @@ declare class FlumeConfluence {
   private openGroup;
   private createPendingOpen;
   private wrapOnEvent;
+  private wrapOnError;
 }
 //#endregion
-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 };
+//#region lib/utils/attempt.d.ts
+/**
+ * 関数を呼び出して throw / async reject を `T | Error` に変換する。
+ *
+ * - sync 関数を渡すと `T | Error` を返す
+ * - Promise を返す関数を渡すと `Promise<T | Error>` を返す (caller は `await` する)
+ * - `new X(...)` や `obj.method(...)` は `() => new X(...)` のようにアローで包む
+ *
+ * sync / async は arrow の戻り型から TS が推論する。
+ * native Promise でない thenable (DI モックや promise ライブラリ) の reject も
+ * `Promise.resolve` で吸収する — その代償として、`.then` メソッドを持つ純粋な値を
+ * sync overload で返すことはできない (Promise 扱いになる)
+ */
+declare function attempt<T>(fn: () => Promise<T>): Promise<T | Error>;
+declare function attempt<T>(fn: () => T): T | Error;
+//#endregion
+//#region lib/utils/is-record.d.ts
+declare function isRecord(value: unknown): value is Record<string, unknown>;
+//#endregion
+//#region lib/utils/safe-error-message.d.ts
+type Props$5 = {
+  error: unknown;
+};
+/**
+ * 任意の値から人が読めるメッセージ文字列を取り出す。
+ * `Error.message` getter / `Symbol.toPrimitive` / `toString` / `valueOf` が throw しても固定文字列に fallback。
+ * `instanceof` 自体が throw する値 (revoked Proxy 等) にも耐える。自身は決して throw しない
+ */
+declare function safeErrorMessage(props: Props$5): string;
+//#endregion
+//#region lib/utils/safe-invoke-callback.d.ts
+type Props$4 = {
+  fn: () => void;
+  onError: (error: Error) => void;
+};
+/**
+ * fire-and-forget でユーザーコールバックを呼び出す。sync throw と async reject のどちらも
+ * `onError(Error)` に正規化して通知。`onError` 自身が throw しても外に漏らさない。
+ * 戻り値を持たない fire-and-forget 専用のため log/出力先には依存しない (caller が onError で決める)
+ */
+declare function safeInvokeCallback(props: Props$4): void;
+//#endregion
+//#region lib/utils/safe-json-parse.d.ts
+declare function safeJsonParse(raw: string): unknown | FlumeParseError;
+//#endregion
+//#region lib/utils/safe-normalize-error.d.ts
+type Props$3 = {
+  value: unknown;
+};
+/**
+ * 任意の値を `Error` インスタンスへ正規化する。すでに Error ならそのまま返し、
+ * それ以外は `safeErrorMessage` で安全な文字列化を経由して new Error する。
+ * `instanceof` 自体が throw する値 (revoked Proxy 等) や Error コンストラクタが throw する
+ * 病的環境でも fallback を返し、決して throw しない
+ */
+declare function safeNormalizeError(props: Props$3): Error;
+//#endregion
+//#region lib/utils/safe-now.d.ts
+type Props$2 = {
+  deps: Pick<FlumeRuntimeDeps, "now">;
+};
+/**
+ * `deps.now()` を保護する。throw / 非数値 / 非有限値が返った場合は `Date.now()` へ
+ * フォールバックする (0 を返すと epoch 1970 が TTL / cron / レート計算へ伝播するため)。
+ * `Date.now` 自体まで壊れている病的環境でのみ 0 を返す。
+ * IO 境界のため呼び出し側はこの戻り値を信頼できる
+ */
+declare function safeNow(props: Props$2): number;
+//#endregion
+//#region lib/utils/safe-random.d.ts
+type Props$1 = {
+  deps: Pick<FlumeRuntimeDeps, "random">;
+};
+/**
+ * `deps.random()` を保護する。throw / 範囲外値 / 非数値が返った場合は `Math.random()` へ
+ * フォールバックする。0 以上 1 未満 (Math.random と同等) の値のみそのまま透過。
+ * `Math.random` 自体まで壊れている病的環境でのみ 0.5 を返す
+ */
+declare function safeRandom(props: Props$1): number;
+//#endregion
+//#region lib/utils/safe-read-text.d.ts
+type Props = {
+  response: Response;
+  context: string;
+};
+/**
+ * `response.text()` を保護する。body 読み取り中の reject (接続切断 / 解凍失敗 / 二重消費) を
+ * `FlumeHttpError` (status / cause 保持) に変換する。DI モックの `status` getter が throw
+ * しても reject しない。log には書かない (呼び出し側で書く)
+ */
+declare function safeReadText(props: Props): Promise<string | FlumeHttpError>;
+//#endregion
+//#region lib/utils/safe-stringify.d.ts
+/**
+ * `JSON.stringify` を `string | Error` に変換するラッパ。
+ * cyclic / BigInt / throwing toJSON など標準が throw するケースを Error として返す。
+ * `undefined` / function / symbol は `JSON.stringify` が (型定義に反して) `undefined` を
+ * 返すため、これも Error に正規化して戻り値を必ず string にする
+ */
+declare function safeStringify(value: unknown): string | Error;
+//#endregion
+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, attempt, createFlumeDefaultDeps, isRecord, safeErrorMessage, safeInvokeCallback, safeJsonParse, safeNormalizeError, safeNow, safeRandom, safeReadText, safeStringify };