@interactive-inc/flume 0.10.0 → 0.11.0

package/README.md

@@ -48,6 +48,7 @@ if (running instanceof Error) throw running
 
 // later
 await running.close()
+await running.drain() // outside callbacks: finish accepted callback work and diagnostics
 ```
 
 `new Flume({ sources, ...options })` — a single options object; `sources` is the only required field, everything else is optional. There is one unified firehose: `onEvent` (push) and `FlumeRunning.stream()` (pull) both deliver the same `FlumeStreamItem` — received events **and** every log (status transitions, errors, debug) merged into one stream. The consumer filters by `item.kind` (`"event"` / `"log"`) and `item.log.level`. This is built for piping the whole picture into an agent (Claude / Codex) so it notices disconnects on its own. `onError` is a convenience filter that additionally receives only the `level: "error"` logs (route it straight to Sentry).
@@ -70,8 +71,10 @@ Flume  ──open()──▶  FlumeRunning  ──close()──▶  FlumeClosed
 ```
 
 - `Flume.open()` returns `FlumeRunning | FlumeStartError`. Branch with `instanceof Error`. On partial failure (one source fails while another succeeds), the already-opened sources are rolled back and a `FlumeStartError` is returned with per-source detail in `.message`. Calling `open()` a second time on the same `Flume` instance returns `FlumeStartError` at runtime — the type system also rejects calling `open()` on the returned `FlumeRunning`/`FlumeClosed` handles.
-- `FlumeRunning.close()` returns a `FlumeClosed` snapshot. `close()` is idempotent and concurrent-safe.
-- `FlumeClosed` exposes only `statuses()` — a frozen snapshot of each source's final state. No `open`, no `close`, no leaking source references.
+- `FlumeRunning.close()` waits for sources to stop and returns a `FlumeClosed` snapshot. It is idempotent and concurrent-safe, and can be awaited inside `onEvent` or `onError`.
+- `FlumeRunning.drain()` waits for accepted callbacks and their failure diagnostics. Call it **outside callbacks**, normally after `close()`, when shutdown must also finish callback work. Calling it inside a callback would wait for that callback itself.
+- `open()` and `close()` do not wait for observation callbacks. A slow callback cannot hold startup or source shutdown open. Callback delivery remains serial; accepted callbacks may finish after `close()` returns.
+- `FlumeClosed` exposes `statuses()` and `errors()` — frozen snapshots of final source states and disconnect failures. No `open`, no `close`, no leaking source references.
 - An `AbortSignal` on `Flume` drives an automatic transition to `FlumeClosed`.
 - `FlumeRunning.kind === "running"` and `FlumeClosed.kind === "closed"` provide a runtime discriminator when generic code holds the union.
 
@@ -89,8 +92,11 @@ const closed = await running.close()
 closed.close() // type error
 closed.open() // type error
 closed.statuses() // [{ source: "discord", status: "disconnected" }, ...]
+await running.drain() // finish callback delivery before exiting the host process
 ```
 
+Migration from 0.10.1: shutdown code that relied on `close()` waiting for `onEvent` / `onError` should now use `await running.close(); await running.drain()` outside those callbacks. A callback may use `await running.close()` on its own. Pull streams finish after the accepted callbacks and their failure diagnostics have drained. A callback that never settles can therefore keep `drain()` and stream completion pending, while source shutdown still completes.
+
 ## Dynamic groups
 
 A `Flume` is single-use: its source set is fixed at construction and the FSM is terminal once closed. To add or drop sources at runtime, compose at a higher level with `FlumeConfluence` — it holds many `Flume` instances, merges all their firehoses into one `onEvent`, and lets you `add` / `remove` groups while the others keep running.
@@ -100,7 +106,7 @@ import { FlumeConfluence } from "@interactive-inc/flume"
 
 const confluence = new FlumeConfluence({
   onEvent: (item) => {
-    if (item.kind === "event") feedToAgent(item.event)
+    if (item.kind === "event") feedToAgent(item.groupId, item.event)
     if (item.kind === "log" && item.log.action === "status") noticeDisconnect(item.log)
   },
   reconnect: { maxAttempts: 10 },
@@ -112,7 +118,9 @@ await confluence.remove("team-a") // stops only team-a
 await confluence.closeAll()
 ```
 
-`add(id, sources)` starts a fresh `Flume` for that group and returns `Error | null` (a duplicate id or a failed start is returned, never thrown). The `id` is just a management handle — the merged stream itself is untagged; identify the origin via the `source` field inside each item. Each group is an independent `Flume`, so a failure in one group never rolls back another. Reconstructing a group (rather than mutating one in place) loses only its reconnect counters, dedup caches, and Discord session resume — acceptable on a deliberate add/remove.
+`add(id, sources)` starts a fresh `Flume` for that group and returns `Error | null` (a duplicate id or a failed start is returned, never thrown). Every merged item is stamped with that id as `groupId`, while `item.event.source` / `item.log.source` identifies the protocol source inside the group. Each group is an independent `Flume`, so a failure in one group never rolls back another. `replace(id, sources)` opens a replacement first and closes the previous group only after the new one is ready; a failed replacement leaves the previous group running.
+
+Source instances are single-use. Reusing an existing instance returns a `FlumeStartError` and preserves its current owner's connection. `remove()` / `closeAll()` wait for source shutdown; callbacks already accepted by those groups may finish afterward.
 
 ## Sub-entries
 
@@ -126,24 +134,32 @@ import { FlumeGitHubSource } from "@interactive-inc/flume/github"
 import { FlumeTimeSource } from "@interactive-inc/flume/time"
 ```
 
-- `@interactive-inc/flume` — `Flume`, `FlumeConfluence`, `FlumeRunning`, `FlumeClosed`, `FlumeSource` (abstract base for third-party sources), `createFlumeDefaultDeps`, errors, types
+- `@interactive-inc/flume` — `Flume`, `FlumeConfluence`, `FlumeRunning`, `FlumeClosed`, `FlumeSource` (abstract base for third-party sources), `createFlumeDefaultDeps`, errors, types, and the common `attempt` / `safe*` utilities used by custom sources
 - `@interactive-inc/flume/discord` — `FlumeDiscordSource`, `FlumeDiscordGatewayIntents`, `flumeExtractDiscordMeta`
 - `@interactive-inc/flume/slack` — `FlumeSlackSource`, `flumeExtractSlackMeta`
 - `@interactive-inc/flume/github` — `FlumeGitHubSource`, `flumeExtractGitHubMeta`
-- `@interactive-inc/flume/time` — `FlumeTimeSource`, `parseCron`, `flumeCronNext`
+- `@interactive-inc/flume/time` — `FlumeTimeSource`, `parseCron`, `flumeCronNext`, `flumeCollectCatchupMatches`
 
 ## Custom sources
 
 Extend `FlumeSource` to plug in any protocol. The base class owns `start`/`stop`/`status`, the per-source event queue, status emission (logged on every transition), and consumed/stopped guards. You implement `connect` (open the protocol, emit events, set status) and `disconnect` (tear it down).
 
 ```ts
-import { FlumeSource } from "@interactive-inc/flume"
-import type { FlumeSourceStartContext } from "@interactive-inc/flume"
+import {
+  attempt,
+  FlumeSource,
+  safeErrorMessage,
+  safeInvokeCallback,
+  safeJsonParse,
+  safeNow,
+  safeReadText,
+} from "@interactive-inc/flume"
+import type { FlumeSourceStartContext, FlumeTimerHandle } from "@interactive-inc/flume"
 
 class MyWebhookSource extends FlumeSource {
   readonly name = "my-webhook"
 
-  private timer: ReturnType<typeof setInterval> | null = null
+  private timer: FlumeTimerHandle | null = null
 
   constructor(private readonly options: { url: string; pollInterval?: number }) {
     super()
@@ -152,33 +168,73 @@ class MyWebhookSource extends FlumeSource {
   protected async connect(ctx: FlumeSourceStartContext): Promise<Error | null> {
     this.setStatus("connecting")
     const interval = (this.options.pollInterval ?? 30) * 1000
-    this.timer = ctx.deps.setInterval(() => this.poll(ctx), interval) as ReturnType<
-      typeof setInterval
-    >
+    const timer = attempt(() => ctx.deps.setInterval(() => this.runPoll(ctx), interval))
+    if (timer instanceof Error) return timer
+    this.timer = timer
     this.setStatus("connected")
     return null
   }
 
   protected disconnect(): void {
-    if (this.timer) clearInterval(this.timer)
+    const timer = this.timer
     this.timer = null
+    const ctx = this.context
+    if (timer === null || ctx === null) return
+
+    const result = attempt(() => ctx.deps.clearInterval(timer))
+    if (result instanceof Error) {
+      ctx.log.error({
+        action: "timer.clear.error",
+        message: safeErrorMessage({ error: result }),
+        error: result,
+      })
+    }
+  }
+
+  private runPoll(ctx: FlumeSourceStartContext): void {
+    safeInvokeCallback({
+      fn: async () => {
+        const result = await this.poll(ctx)
+        if (result instanceof Error) {
+          ctx.log.error({
+            action: "poll.error",
+            message: safeErrorMessage({ error: result }),
+            error: result,
+          })
+        }
+      },
+      onError: (error) => {
+        ctx.log.error({
+          action: "poll.unhandled",
+          message: safeErrorMessage({ error }),
+          error,
+        })
+      },
+    })
   }
 
-  private async poll(ctx: FlumeSourceStartContext): Promise<void> {
-    const res = await ctx.deps.fetch(this.options.url)
-    const payload = await res.json()
+  private async poll(ctx: FlumeSourceStartContext): Promise<Error | null> {
+    const response = await attempt(() => ctx.deps.fetch(this.options.url))
+    if (response instanceof Error) return response
+    const raw = await safeReadText({ response, context: this.name })
+    if (raw instanceof Error) return raw
+    const payload = safeJsonParse(raw)
+    if (payload instanceof Error) return payload
+
     this.emit({
-      source: this.name as "discord", // declare your own discriminant via FlumeEvent extension
+      source: "custom",
+      sourceName: this.name,
       type: "webhook",
-      data: payload,
+      data: { payload },
       meta: { event_type: "webhook" },
-      receivedAt: ctx.deps.now(),
+      receivedAt: safeNow({ deps: ctx.deps }),
     })
+    return null
   }
 }
 ```
 
-`this.emit({...})` queues events through the base's serial queue and routes them to `ctx.onEvent` with `attempt()` isolation. `this.setStatus(...)` deduplicates idempotent transitions and logs the change (which is how status surfaces to consumers). Subclasses never need to write try/catch.
+`this.emit({...})` queues events through the base's serial queue and routes them to `ctx.onEvent` with `attempt()` isolation. `this.setStatus(...)` deduplicates idempotent transitions and logs the change. IO started after `connect()` returns, such as timer callbacks, must use `attempt()` or `safeInvokeCallback()` as shown above; both are exported from the root entry so custom sources do not need raw try/catch.
 
 ## Time source
 
@@ -210,6 +266,8 @@ new FlumeTimeSource({
 
 `tick.firedAt` is the scheduled wall-clock time (epoch ms), not the exact `setTimeout` firing instant. A throwing `message()` is isolated and falls back to the defaults. Parse the cron up front with `parseCron(expr)` (returns `FlumeCron | FlumeParseError`) or compute the next fire with `flumeCronNext(cron, afterMs)`.
 
+With `statePersister`, state writes are serialized in tick order and source shutdown waits for queued writes to settle. A failed write is logged and later writes still run. Keep the persister's IO bounded and avoid waiting for Flume lifecycle completion inside it. Stopping during `load()` releases startup immediately and ignores a late result; cancellation of the host's underlying read remains the persister's responsibility. Use `catchupPolicy` (`off`, `lastOnly`, or `missed`) to control replay on the next start. When multiple sources share a persistence key, the host must also serialize or atomically order their writes.
+
 ## Pull stream
 
 `FlumeRunning.stream()` is the pull form of the same firehose as `onEvent` — an async iterator over `FlumeStreamItem`, handy for feeding an agent (Claude / Codex) with `for await`, where backpressure falls out naturally from how fast you pull.
@@ -224,10 +282,10 @@ for await (const item of running.stream()) {
   if (item.kind === "event") await handleWithAgent(item.event)
   if (item.kind === "log" && item.log.action === "status") noticeDisconnect(item.log)
 }
-// loop ends when the flume stops (running.close() or signal abort)
+// after close / signal abort, the loop ends once accepted callback diagnostics are delivered
 ```
 
-The iterator ends cleanly when the flume stops; `break`ing out unsubscribes automatically. When a slow consumer lets the buffer overflow, the oldest items are dropped by default:
+The iterator ends cleanly after source shutdown and accepted callback work; `break`ing out unsubscribes automatically. When a slow consumer lets the buffer overflow, the oldest items are dropped by default:
 
 ```ts
 running.stream({ buffer: 5000, onOverflow: "drop-newest" })
@@ -283,7 +341,7 @@ type FlumeEvent = FlumeDiscordEvent | FlumeSlackEvent | FlumeGitHubEvent | Flume
 
 ## Observability
 
-Flume never calls a third-party service. Every internal action is reported through the firehose (`onEvent` push / `stream()` pull) as `{ kind: "log", log }` items — there are no silent paths. Each `FlumeLog` is tagged with `source: "flume"`, `source: "discord"`, `source: "slack"`, `source: "github"`, `source: "time"`, or your custom source's `name`. `onError` is a convenience filter that additionally receives only the `level: "error"` subset (route it straight to Sentry).
+Flume never calls a third-party service. Every internal action is reported through the firehose (`onEvent` push / `stream()` pull) as `{ kind: "log", log }` items — there are no silent internal paths. Each `FlumeLog` is tagged with `source: "flume"`, `source: "discord"`, `source: "slack"`, `source: "github"`, `source: "time"`, or your custom source's `name`. `onError` is a convenience filter that additionally receives only the `level: "error"` subset (route it straight to Sentry).
 
 ```ts
 type FlumeLog = {
@@ -306,6 +364,9 @@ What gets logged:
 - Reconnect — `reconnect.scheduled` (with delay in ms), `reconnect.exhausted` (with attempt count), `reconnect.reset` (on successful connect after retries), `reconnect.cancel` (on stop).
 - Status transitions — `status` action with `previous → next`.
 - Errors — `level: "error"` carries the `error` field; use `onError` for a pre-filtered error sink.
+- Observation sink failures — a failed `onEvent` emits `onEvent.error` to `onError` and the pull stream; a failed `onError` emits `onError.error` to `onEvent` and the pull stream. `detail` identifies the callback plus the failed item's kind, source, and event type or log action. `FlumeConfluence` also stamps `groupId` onto logs sent to its `onError`. The peer notification is attempted once, without recursive reporting.
+
+For maximum diagnostics, configure both callbacks or keep a pull stream consumer. If both push callbacks fail, both failure logs remain available to the pull stream; startup logs are replayed to its first subscriber. `FlumeConfluence` has no pull iterator, so configure its `onError` as the independent diagnostic sink.
 
 Route it anywhere — Sentry, Datadog, `console`, a file — your choice. Filter the log items out of the firehose:
 
@@ -395,9 +456,9 @@ new Flume({
 
 ## Safety
 
-- Ordering — each source has its own `FlumeSerialQueue` and per-source events are delivered FIFO. Cross-source ordering between events from different sources is undefined (no global serialization). `onEvent` invocations are awaited and run one at a time per source, so async callbacks don't race and `close()` drains in-flight events before transitioning state.
+- Ordering — each source has its own `FlumeSerialQueue` and per-source events are published FIFO. The public `onEvent` and `onError` callbacks share one global queue, so callback invocations never race across sources. `close()` stops the sources; a subsequent `drain()` waits for callbacks and their failure diagnostics. Pull subscribers receive items when they are published and have independent bounded buffers. The push callback queue is unbounded; use pull-only consumption for a bounded slow consumer.
 - Duplicate suppression — Slack envelopes are deduped by `envelope_id` (`FlumeSlackSeenCache`) to absorb ack retries. GitHub notifications are deduped by `id + updated_at` (`FlumeGitHubSeenCache`). Discord uses session resume so the Gateway does not re-emit dispatches.
-- Partial-failure rollback — if any source fails during `Flume.open()`, the already-started sources are stopped and a `FlumeStartError` is returned with per-source detail.
+- Partial-failure rollback — if any source fails during `Flume.open()`, sources acquired by that open are stopped, including partially connected failures. A source that refused reuse remains with its existing owner. A `FlumeStartError` is returned with per-source detail.
 - Idempotent close — `FlumeRunning.close()` is safe to call concurrently; the first call wins and subsequent callers receive the same `FlumeClosed` snapshot. The same guard exists at source level: a double-`close()` (e.g. via signal abort racing a manual close) does not re-invoke `disconnect()`.
 
 ## Errors
@@ -409,9 +470,9 @@ Flume does not throw on protocol/network failures. Every entry point returns `T
 - `FlumeHttpError` — HTTP call returned an error payload (e.g. Slack `ok: false`)
 - `FlumeParseError` — Unparseable WebSocket frame
 
-Exceptions thrown from `onEvent` are caught and logged (never rethrown into the protocol loop).
+Exceptions thrown or rejected from `onEvent` / `onError` are isolated and emitted as `onEvent.error` / `onError.error` diagnostics; they are never rethrown into the protocol loop.
 
-The library guarantees that no exception escapes any public surface — constructors, `open()`, `close()`, the `onEvent` invocation path, the `stream()` iterator, the abort-signal path, and the `onError` callback all route IO and user-supplied callbacks through internal `safe*` wrappers and the generic `attempt()` helper. A misbehaving `onEvent` / `onError` will be logged and isolated rather than crashing the protocol loop.
+With type-valid constructor input, the library guarantees that protocol IO and user callback failures do not escape `open()`, `close()`, the `onEvent` invocation path, the `stream()` iterator, the abort-signal path, or the `onError` callback. These boundaries route work through internal `safe*` wrappers and the generic `attempt()` helper.
 
 ## Supported sources
 
@@ -441,11 +502,11 @@ const github = new FlumeGitHubSource({ token })
 
 ```bash
 bun install
-bunx vp pack       # build dist/
-bunx tsc --noEmit  # typecheck
-bunx vitest run    # tests
-bunx vp lint       # lint
-bunx vp fmt        # format
+vp pack            # build dist/
+vp run typecheck   # typecheck
+vp test            # tests
+vp lint            # lint
+vp fmt             # format
 ```
 
 The library itself is runtime-agnostic. The dev toolchain (build / test / lint) uses Bun + `vite-plus` + `vitest`, but the published `dist/` is plain ESM with TypeScript declarations and runs on Node 22+, Bun, Deno, Cloudflare Workers, or modern browsers. Runtimes without a global `WebSocket` (e.g. fetch-only edge functions) can still use `FlumeGitHubSource`; `FlumeDiscordSource` / `FlumeSlackSource` will return `FlumeStartError` at `open()` time if `deps.WebSocket` is `null`.

package/dist/discord.d.ts

@@ -1,4 +1,4 @@
-import { D as FlumeSourceStartContext, o as FlumeDiscordSourceOptions, t as FlumeSource } from "./flume-source.js";
+import { O as FlumeSourceStartContext, s as FlumeDiscordSourceOptions, t as FlumeSource } from "./flume-source.js";
 
 //#region lib/discord/discord-source.d.ts
 declare class FlumeDiscordSource extends FlumeSource {
@@ -10,10 +10,24 @@ declare class FlumeDiscordSource extends FlumeSource {
   protected connect(ctx: FlumeSourceStartContext): Promise<Error | null>;
   protected disconnect(): void;
   private hasWebSocket;
+  /**
+   * gateway を 1 接続 = 1 インスタンスで作り直す。`session` は前回接続から引き継いだ
+   * resume 可能な session (無ければ IDENTIFY)。await 後は `this.gateway` でなく local な
+   * `gateway` を参照する (並行する close() が `this.gateway` を null 化しても壊れない)
+   */
   private connectInternal;
   private dispatch;
   private safeExtractMeta;
+  /**
+   * status は発火元 gateway に束縛して受ける。交換済み (stale) な gateway からの通知は無視し、
+   * 現行 gateway の状態を誤って上書きしない
+   */
   private handleGatewayStatus;
+  /**
+   * resume 可能な session はこの時点で捕捉して次の gateway へ引き継ぐ (gateway インスタンスは
+   * 接続ごとに破棄されるため)。resume できない = IDENTIFY し直す再接続には identify rate limit
+   * (1 回 / 5 秒) を守る下限 delay を敷く
+   */
   private scheduleReconnect;
 }
 //#endregion