World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
A reconnected event stream refreshes changes it missed (#1036)
Maya Kiddf637c36233b
diff --git a/web/src/queryDefaults.ts b/web/src/queryDefaults.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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();