Skip to content

World's first open-source enterprise world model.

A reconnected event stream refreshes changes it missed (#1036)

Maya Kiddf637c36233b
diff --git a/web/src/queryDefaults.ts b/web/src/queryDefaults.ts
index cbc8cbf1..0a30399b 100644
--- a/web/src/queryDefaults.ts
+++ b/web/src/queryDefaults.ts
@@ -12,9 +12,10 @@
// (`Login` 成功时)与登出(`UserMenu`)清空整个缓存——会话过期后同一标签页登另一个账号
// 是唯一会露馅的路,所以登录那一清不能省。deployment 由设置页的 mutation 自己失效。
// - **事件流覆盖的**:documents、graph、review、pending、sources、mappings。当前库即时;
-// 可流只订**当前**库,切库回来、EventSource 断线重连期间都没人失效,所以不是 Infinity:
-// 30 秒内自愈,且 `setKb` 切库时按 `STREAM_KEYS` 主动失效目标库。
-// - **其余**:15 秒的全局默认。来回导航不重拉;别的会话或后台任务改了,15 秒内看见。
+// 可流只订**当前**库,所以不是 Infinity:超过 30 秒后再次挂载会重取,
+// `setKb` 切库时按 `STREAM_KEYS` 主动失效目标库,断线后的 open 也补刷当前库。
+// staleTime 只决定新鲜度,不会自动轮询或触发重取。
+// - **其余**:15 秒的全局默认。新鲜时来回导航不重拉;过期后再次挂载会重取。
// 要更短的键(readiness 10 秒)在自己那处写,只有比这里短的才值得单独写。
//
// `setQueryDefaults` 按键前缀匹配:`["graph"]` 管到 `["graph", kbId, …]`。
@@ -22,7 +23,7 @@ import type { QueryClient } from "@tanstack/react-query";
/** 其余键的默认新鲜期 */
export const DEFAULT_STALE_MS = 15_000;
-/** 事件流覆盖的键:切库与断线的漏洞在这个窗口内自愈 */
+/** 事件流覆盖的键:超过这个窗口后再次挂载会重取,切库与重连另有主动失效 */
export const STREAM_STALE_MS = 30_000;
/** 事件流会失效的键头(见 `useKbEvents`);切库时也按这张表失效目标库 */
diff --git a/web/src/useAlertEvents.ts b/web/src/useAlertEvents.ts
index a9222806..956fe272 100644
--- a/web/src/useAlertEvents.ts
+++ b/web/src/useAlertEvents.ts
@@ -9,9 +9,26 @@ export function useAlertEvents() {
const queryClient = useQueryClient();
useEffect(() => {
const es = new EventSource("/api/v1/alerts/events");
- es.addEventListener("alert", () => {
- queryClient.invalidateQueries({ queryKey: ["alerts"] });
- });
- return () => es.close();
+ let disconnected = false;
+ let disposed = false;
+ const refresh = () => {
+ if (!disposed) queryClient.invalidateQueries({ queryKey: ["alerts"] });
+ };
+ const listeners: Record<string, () => void> = {
+ alert: refresh,
+ error: () => { if (!disposed) disconnected = true; },
+ open: () => {
+ if (disposed || !disconnected) return;
+ disconnected = false;
+ // 断线期间的告警不会回放:恢复时同时补刷角标与列表。
+ refresh();
+ },
+ };
+ for (const [type, listener] of Object.entries(listeners)) es.addEventListener(type, listener);
+ return () => {
+ disposed = true;
+ for (const [type, listener] of Object.entries(listeners)) es.removeEventListener(type, listener);
+ es.close();
+ };
}, [queryClient]);
}
diff --git a/web/src/useEventReconnect.test.ts b/web/src/useEventReconnect.test.ts
new file mode 100644
index 00000000..00263619
--- /dev/null
+++ b/web/src/useEventReconnect.test.ts
@@ -0,0 +1,269 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { QueryClient, QueryObserver, type QueryKey } from "@tanstack/react-query";
+import { DEFAULT_STALE_MS, STREAM_KEYS, STREAM_STALE_MS, applyQueryDefaults } from "./queryDefaults";
+import { SETTLE_MS, useKbEvents } from "./useKbEvents";
+import { useAlertEvents } from "./useAlertEvents";
+
+// 在 Node 环境执行 hook 的 effect,浏览器边界用可控事件源;查询与观察者仍用真实实现。
+const hooks = vi.hoisted(() => ({
+ effects: [] as Array<() => void | (() => void)>,
+ client: undefined as unknown,
+}));
+vi.mock("react", async (importOriginal) => ({
+ ...await importOriginal<typeof import("react")>(),
+ useEffect: (effect: () => void | (() => void)) => hooks.effects.push(effect),
+}));
+vi.mock("@tanstack/react-query", async (importOriginal) => ({
+ ...await importOriginal<typeof import("@tanstack/react-query")>(),
+ useQueryClient: () => hooks.client,
+}));
+
+class FakeEventSource {
+ static instances: FakeEventSource[] = [];
+ listeners = new Map<string, Set<() => void>>();
+ closed = false;
+
+ constructor(readonly url: string) {
+ FakeEventSource.instances.push(this);
+ }
+
+ addEventListener(type: string, listener: () => void) {
+ const listeners = this.listeners.get(type) ?? new Set();
+ listeners.add(listener);
+ this.listeners.set(type, listeners);
+ }
+
+ removeEventListener(type: string, listener: () => void) {
+ this.listeners.get(type)?.delete(listener);
+ }
+
+ emit(type: string) {
+ for (const listener of this.listeners.get(type) ?? []) listener();
+ }
+
+ close() {
+ this.closed = true;
+ }
+}
+
+const cleanups: Array<() => void> = [];
+const clients: QueryClient[] = [];
+const unsubscribes: Array<() => void> = [];
+
+function mount(hook: () => void) {
+ hook();
+ const cleanup = hooks.effects.pop()?.();
+ let mounted = true;
+ const unmount = () => {
+ if (!mounted) return;
+ mounted = false;
+ cleanup?.();
+ };
+ cleanups.push(unmount);
+ return { source: FakeEventSource.instances.at(-1)!, unmount };
+}
+
+function createClient() {
+ const client = new QueryClient({
+ defaultOptions: {
+ queries: { staleTime: DEFAULT_STALE_MS, refetchOnWindowFocus: false, retry: false },
+ },
+ });
+ applyQueryDefaults(client);
+ hooks.client = client;
+ clients.push(client);
+ return client;
+}
+
+async function watch(client: QueryClient, key: QueryKey) {
+ let serverData = "before disconnect";
+ const fetch = vi.fn(async () => serverData);
+ const observer = new QueryObserver(client, { queryKey: key, queryFn: fetch });
+ unsubscribes.push(observer.subscribe(() => {}));
+ // subscribe 启动的首次读取与 refetch 共享同一次请求。
+ await observer.refetch();
+ expect(fetch).toHaveBeenCalledTimes(1);
+ return {
+ fetch,
+ observer,
+ changeServer: () => { serverData = "after disconnect"; },
+ };
+}
+
+beforeEach(() => {
+ vi.useFakeTimers();
+ vi.stubGlobal("EventSource", FakeEventSource);
+ FakeEventSource.instances = [];
+ hooks.effects = [];
+});
+
+afterEach(() => {
+ for (const cleanup of cleanups.splice(0)) cleanup();
+ for (const unsubscribe of unsubscribes.splice(0)) unsubscribe();
+ for (const client of clients.splice(0)) client.clear();
+ vi.clearAllTimers();
+ vi.useRealTimers();
+ vi.unstubAllGlobals();
+});
+
+describe("KB stream reconnect", () => {
+ it("refetches missed changes immediately for every stream key in the current KB", async () => {
+ const client = createClient();
+ const current = await Promise.all(STREAM_KEYS.map((head) => watch(client, [head, "kb-a", "detail"])));
+ const otherKb = await watch(client, ["graph", "kb-b"]);
+ const unrelated = await watch(client, ["health"]);
+ const inactiveKey = ["documents", "kb-a", "unmounted"];
+ client.setQueryData(inactiveKey, "cached before disconnect");
+ const { source } = mount(() => useKbEvents("kb-a"));
+ expect(source.url).toBe("/api/v1/kbs/kb-a/events");
+ source.emit("open");
+ for (const query of current) expect(query.fetch).toHaveBeenCalledTimes(1);
+
+ source.emit("error");
+ for (const query of current) query.changeServer();
+ // staleTime 到期只让缓存变旧,不会自动请求;断线期间完全没有业务事件。
+ await vi.advanceTimersByTimeAsync(STREAM_STALE_MS + 1);
+ for (const query of current) expect(query.fetch).toHaveBeenCalledTimes(1);
+
+ source.emit("open");
+ // 重连不等普通事件的 300ms 合并窗口。
+ for (const query of current) expect(query.fetch).toHaveBeenCalledTimes(2);
+ await vi.waitFor(() => {
+ for (const query of current) expect(query.observer.getCurrentResult().data).toBe("after disconnect");
+ });
+ expect(client.getQueryState(inactiveKey)?.isInvalidated).toBe(true);
+ expect(otherKb.fetch).toHaveBeenCalledTimes(1);
+ expect(unrelated.fetch).toHaveBeenCalledTimes(1);
+ });
+
+ it("recovers an initial failed connection and clears the recovery flag after open", async () => {
+ const client = createClient();
+ const query = await watch(client, ["documents", "kb-a"]);
+ const { source } = mount(() => useKbEvents("kb-a"));
+ source.emit("error");
+ query.changeServer();
+ source.emit("open");
+ expect(query.fetch).toHaveBeenCalledTimes(2);
+ source.emit("open");
+ expect(query.fetch).toHaveBeenCalledTimes(2);
+ });
+
+ it("flushes a pending burst together with reconnect instead of scheduling another refetch", async () => {
+ const client = createClient();
+ const graph = await watch(client, ["graph", "kb-a"]);
+ const documents = await watch(client, ["documents", "kb-a"]);
+ const { source } = mount(() => useKbEvents("kb-a"));
+ source.emit("open");
+ source.emit("document");
+ source.emit("graph");
+ source.emit("error");
+ source.emit("open");
+ expect(graph.fetch).toHaveBeenCalledTimes(2);
+ expect(documents.fetch).toHaveBeenCalledTimes(2);
+ await vi.advanceTimersByTimeAsync(SETTLE_MS);
+ expect(graph.fetch).toHaveBeenCalledTimes(2);
+ expect(documents.fetch).toHaveBeenCalledTimes(2);
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it("keeps normal business events coalesced", async () => {
+ const client = createClient();
+ const graph = await watch(client, ["graph", "kb-a"]);
+ const documents = await watch(client, ["documents", "kb-a"]);
+ const { source } = mount(() => useKbEvents("kb-a"));
+ source.emit("open");
+ for (let i = 0; i < 12; i++) {
+ source.emit("document");
+ source.emit("graph");
+ }
+ await vi.advanceTimersByTimeAsync(SETTLE_MS - 1);
+ expect(graph.fetch).toHaveBeenCalledTimes(1);
+ expect(documents.fetch).toHaveBeenCalledTimes(1);
+ await vi.advanceTimersByTimeAsync(1);
+ expect(graph.fetch).toHaveBeenCalledTimes(2);
+ expect(documents.fetch).toHaveBeenCalledTimes(2);
+ });
+
+ it("ignores late callbacks from the old connection after switching KB", async () => {
+ const client = createClient();
+ const oldKb = await watch(client, ["graph", "kb-a"]);
+ const newKb = await watch(client, ["graph", "kb-b"]);
+ const old = mount(() => useKbEvents("kb-a"));
+ old.source.emit("open");
+ old.source.emit("error");
+ const lateOpen = [...old.source.listeners.get("open") ?? []];
+ const lateGraph = [...old.source.listeners.get("graph") ?? []];
+ old.unmount();
+ const next = mount(() => useKbEvents("kb-b"));
+ next.source.emit("open");
+ for (const callback of [...lateOpen, ...lateGraph]) callback();
+ old.source.emit("open");
+ old.source.emit("document");
+ await vi.advanceTimersByTimeAsync(SETTLE_MS);
+ expect(old.source.closed).toBe(true);
+ expect([...old.source.listeners.values()].every((listeners) => listeners.size === 0)).toBe(true);
+ expect(vi.getTimerCount()).toBe(0);
+ expect(oldKb.fetch).toHaveBeenCalledTimes(1);
+ expect(newKb.fetch).toHaveBeenCalledTimes(1);
+ next.source.emit("error");
+ next.source.emit("open");
+ expect(oldKb.fetch).toHaveBeenCalledTimes(1);
+ expect(newKb.fetch).toHaveBeenCalledTimes(2);
+ });
+
+ it("does not subscribe without a selected KB", () => {
+ createClient();
+ mount(() => useKbEvents(undefined));
+ expect(FakeEventSource.instances).toHaveLength(0);
+ });
+});
+
+describe("alert stream reconnect", () => {
+ it("refreshes both badge and list after missed alerts, without refetching on the initial open", async () => {
+ const client = createClient();
+ const badge = await watch(client, ["alerts", "unread"]);
+ const list = await watch(client, ["alerts", "list", "", 0]);
+ const other = await watch(client, ["documents", "kb-a"]);
+ const { source } = mount(useAlertEvents);
+ expect(source.url).toBe("/api/v1/alerts/events");
+ source.emit("open");
+ expect(badge.fetch).toHaveBeenCalledTimes(1);
+ expect(list.fetch).toHaveBeenCalledTimes(1);
+ source.emit("error");
+ badge.changeServer();
+ list.changeServer();
+ source.emit("open");
+ expect(badge.fetch).toHaveBeenCalledTimes(2);
+ expect(list.fetch).toHaveBeenCalledTimes(2);
+ expect(other.fetch).toHaveBeenCalledTimes(1);
+ await vi.waitFor(() => {
+ expect(badge.observer.getCurrentResult().data).toBe("after disconnect");
+ expect(list.observer.getCurrentResult().data).toBe("after disconnect");
+ });
+ });
+
+ it("also recovers when the first alert connection failed before open", async () => {
+ const client = createClient();
+ const query = await watch(client, ["alerts", "unread"]);
+ const { source } = mount(useAlertEvents);
+ source.emit("error");
+ source.emit("open");
+ expect(query.fetch).toHaveBeenCalledTimes(2);
+ source.emit("open");
+ expect(query.fetch).toHaveBeenCalledTimes(2);
+ });
+
+ it("removes listeners and ignores late alert callbacks after cleanup", async () => {
+ const client = createClient();
+ const query = await watch(client, ["alerts", "unread"]);
+ const { source, unmount } = mount(useAlertEvents);
+ source.emit("open");
+ source.emit("error");
+ const lateCallbacks = [...source.listeners.values()].flatMap((listeners) => [...listeners]);
+ unmount();
+ for (const callback of lateCallbacks) callback();
+ expect(source.closed).toBe(true);
+ expect([...source.listeners.values()].every((listeners) => listeners.size === 0)).toBe(true);
+ expect(query.fetch).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/web/src/useKbEvents.test.ts b/web/src/useKbEvents.test.ts
index d2188efb..1eac7d45 100644
--- a/web/src/useKbEvents.test.ts
+++ b/web/src/useKbEvents.test.ts
@@ -36,6 +36,19 @@ describe("a burst of events buys one refetch", () => {
expect(seen).toEqual([["graph"], ["graph"]]);
});
+ it("a broader key covers a narrower queued key regardless of their arrival order", () => {
+ for (const keys of [
+ [["graph", "kb"], ["graph"]],
+ [["graph"], ["graph", "kb"]],
+ ]) {
+ const seen: unknown[] = [];
+ const { push, flush } = createInvalidationCoalescer((key) => seen.push(key), 300);
+ for (const key of keys) push(key);
+ flush();
+ expect(seen).toEqual([["graph"]]);
+ }
+ });
+
it("flushing on unmount delivers what was pending instead of dropping it", () => {
const seen: unknown[] = [];
const { push, flush } = createInvalidationCoalescer((key) => seen.push(key), 300);
diff --git a/web/src/useKbEvents.ts b/web/src/useKbEvents.ts
index 8026f3bb..431e1e34 100644
--- a/web/src/useKbEvents.ts
+++ b/web/src/useKbEvents.ts
@@ -1,5 +1,5 @@
// KB 事件流订阅:收到事件只做 react-query 失效重取(事件不带业务数据,天然幂等)。
-// EventSource 断线自动重连;替代 Library/Review 的轮询。
+// EventSource 断线自动重连,重连成功后补刷漏掉的变化;替代 Library/Review 的轮询。
//
// **失效是合并着做的。** 一篇文档抽取时每落一条事实就发一个 graph 事件,
// 从前每个事件各失效一次,图谱页在那几秒里把 overview 重取了十几遍——
@@ -10,14 +10,15 @@
// 失效不看 staleTime:这里失效的键在 queryDefaults.ts 里放到了 30 秒,靠的就是
// 这一层把当前库的变化即时推到页面上。
import { useEffect } from "react";
-import { useQueryClient, type QueryKey } from "@tanstack/react-query";
+import { partialMatchKey, useQueryClient, type QueryKey } from "@tanstack/react-query";
+import { STREAM_KEYS } from "./queryDefaults";
/** 一阵事件之间的静默期。抽取落事实的间隔远小于它,人眼看不出这点延迟 */
export const SETTLE_MS = 300;
/**
* 把一阵失效合并成一次:`push` 只记键,静默 `settleMs` 后一起交给 `invalidate`,
- * 同一个键记多少次都只失效一次;`flush` 给卸载用,攒着的刷掉而不是丢掉。
+ * 同一个键及其前缀只失效一次;`flush` 给卸载与重连用,攒着的刷掉而不是丢掉。
* 抽成纯函数是为了能测;订阅那层只是把事件名映射到键。
*/
export function createInvalidationCoalescer(
@@ -33,7 +34,12 @@ export function createInvalidationCoalescer(
}
const keys = [...pending.values()];
pending.clear();
- for (const key of keys) invalidate(key);
+ for (const key of keys) {
+ // 正常 graph 事件可能已排了 ["graph"],重连又补上 ["graph", kbId]:
+ // 前缀已经覆盖后者,不能取消刚开始的请求再重取一遍。
+ if (keys.some((prefix) => prefix.length < key.length && partialMatchKey(key, prefix))) continue;
+ invalidate(key);
+ }
};
const push = (...keys: QueryKey[]) => {
for (const key of keys) pending.set(JSON.stringify(key), key);
@@ -53,14 +59,33 @@ export function useKbEvents(kbId: string | undefined) {
);
const es = new EventSource(`/api/v1/kbs/${kbId}/events`);
- es.addEventListener("document", () => push(["documents", kbId], ["graph"]));
- es.addEventListener("graph", () => push(["graph"]));
- // 映射探索跑完发的也是 review:Pending 那一栏得跟着刷新
- es.addEventListener("review", () => push(["review", kbId], ["mappings", kbId]));
- // 一句记忆抽出了等人点头的事实(0015):对话里那张确认卡跟着长出来
- es.addEventListener("pending", () => push(["pending", kbId], ["review", kbId]));
- es.addEventListener("source", () => push(["sources", kbId], ["documents", kbId]));
+ let disconnected = false;
+ let disposed = false;
+ const pushIfActive = (...keys: QueryKey[]) => {
+ if (!disposed) push(...keys);
+ };
+ const listeners: Record<string, () => void> = {
+ error: () => { if (!disposed) disconnected = true; },
+ open: () => {
+ if (disposed || !disconnected) return;
+ disconnected = false;
+ // 事件没有回放,staleTime 到期也不会自己发请求。断线后恢复必须补刷;
+ // 首次正常连接交给页面已有的读取,首次连接失败再恢复则同样可能漏事件。
+ push(...STREAM_KEYS.map((head) => [head, kbId]));
+ flush();
+ },
+ document: () => pushIfActive(["documents", kbId], ["graph"]),
+ graph: () => pushIfActive(["graph"]),
+ // 映射探索跑完发的也是 review:Pending 那一栏得跟着刷新
+ review: () => pushIfActive(["review", kbId], ["mappings", kbId]),
+ // 一句记忆抽出了等人点头的事实(0015):对话里那张确认卡跟着长出来
+ pending: () => pushIfActive(["pending", kbId], ["review", kbId]),
+ source: () => pushIfActive(["sources", kbId], ["documents", kbId]),
+ };
+ for (const [type, listener] of Object.entries(listeners)) es.addEventListener(type, listener);
return () => {
+ disposed = true;
+ for (const [type, listener] of Object.entries(listeners)) es.removeEventListener(type, listener);
es.close();
// 卸载时把攒着的刷掉而不是丢掉:换页回来看到的必须是新数据
flush();