Skip to content

World's first open-source enterprise world model.

A page holds one notification stream and gives it up while hidden, so Stop is not left waiting for a connection (#1028) (#1053)

WaylandYang4f873e5b7e37
diff --git a/crates/utopia-server/src/api/events_routes.rs b/crates/utopia-server/src/api/events_routes.rs
index e7e36280..ad2ffe9d 100644
--- a/crates/utopia-server/src/api/events_routes.rs
+++ b/crates/utopia-server/src/api/events_routes.rs
@@ -1,5 +1,9 @@
//! KB 事件流(SSE):文档摄入/抽取状态与审核队列变化的实时推送。
//! 前端收到事件只做 react-query 失效重取——事件本身不带业务数据,天然幂等。
+//!
+//! **告警也从这条流走**(#1028)。浏览器给一个源的 HTTP/1.1 连接只有六条,事件流占着
+//! 不放:一页开两条通知流、再加一条正在生成的回答,两个标签页就占满,Stop 发不出去。
+//! 所以打开着一个库的页只订这一条,全局那条 `/alerts/events` 留给没有库的页。
use axum::extract::{Path, State};
use axum::response::sse::{Event, KeepAlive, Sse};
@@ -11,7 +15,7 @@ use uuid::Uuid;
use crate::auth::AuthUser;
use crate::error::ApiResult;
-use crate::state::AppState;
+use crate::state::{AppEvent, AppState};
pub async fn kb_events(
State(state): State<AppState>,
@@ -24,12 +28,13 @@ pub async fn kb_events(
let stream = async_stream::stream! {
loop {
match rx.recv().await {
- Ok(ev) if ev.kb_id == Some(kb_id) => {
- yield Ok(Event::default()
+ Ok(ev) => match relay(&ev, kb_id) {
+ Some(Relay::Alert) => yield Ok(Event::default().event("alert").data("{}")),
+ Some(Relay::Kb) => yield Ok(Event::default()
.event(ev.kind)
- .data(serde_json::to_string(&ev).unwrap_or_else(|_| "{}".into())));
- }
- Ok(_) => continue,
+ .data(serde_json::to_string(&ev).unwrap_or_else(|_| "{}".into()))),
+ None => continue,
+ },
// 消费落后被跳帧:无所谓,事件只是"该刷新了"的信号
Err(broadcast::error::RecvError::Lagged(_)) => continue,
Err(broadcast::error::RecvError::Closed) => return,
@@ -38,3 +43,43 @@ pub async fn kb_events(
};
Ok(Sse::new(stream).keep_alive(KeepAlive::default()))
}
+
+#[derive(Debug, PartialEq)]
+enum Relay {
+ /// 告警:不按库过滤、不带数据,和 `alerts_routes::stream` 同一个约定——收到的人
+ /// 回头重取列表,谁能看见什么由列表查询说了算
+ Alert,
+ /// 这个库自己的事件,原样送出
+ Kb,
+}
+
+fn relay(ev: &AppEvent, kb_id: Uuid) -> Option<Relay> {
+ if ev.kind == "alert" {
+ Some(Relay::Alert)
+ } else if ev.kb_id == Some(kb_id) {
+ Some(Relay::Kb)
+ } else {
+ None
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn a_kb_stream_carries_its_own_events_and_every_alert() {
+ let (here, elsewhere) = (Uuid::now_v7(), Uuid::now_v7());
+ let event = |kb_id, kind| AppEvent {
+ kb_id,
+ kind,
+ document_id: None,
+ };
+ assert_eq!(relay(&event(Some(here), "document"), here), Some(Relay::Kb));
+ assert_eq!(relay(&event(Some(elsewhere), "document"), here), None);
+ // 系统级告警没有库,别的库的告警也要叫醒角标:都送,都不带数据
+ for kb_id in [None, Some(here), Some(elsewhere)] {
+ assert_eq!(relay(&event(kb_id, "alert"), here), Some(Relay::Alert));
+ }
+ }
+}
diff --git a/docs/decisions/0005-alert-center.md b/docs/decisions/0005-alert-center.md
index 941be30d..81bb0fad 100644
--- a/docs/decisions/0005-alert-center.md
+++ b/docs/decisions/0005-alert-center.md
@@ -61,6 +61,14 @@ channel: something in this document did not land. None of it goes to Review.
broadcast (kind `alert`) and only tells clients to refetch; the list query decides
visibility once. Someone without permission is woken for nothing, and the push path
holds no permission logic.
+
+ > **Revised 2026-10-03 (#1028).** The per-KB stream now carries the `alert` event too,
+ > under the same rule: no data, no permission check. A page with a base open subscribes
+ > only to that stream, and `/alerts/events` is for a page with no base. A browser gives
+ > one origin six HTTP/1.1 connections, and a stream holds one for as long as it is open:
+ > with two notification streams and a generating answer per page, two tabs used all six
+ > and a Stop request could not be sent. A page hidden for 30 seconds also gives its
+ > notification stream up and refreshes when it is shown again.
7. **Classification is a pure function on error types.** `alert_for` decides the kind from
the error's type, never its text, and has unit tests; job failures reach it through
`observe_job_failure` only once retries are exhausted. `llm.unreachable` means "no
diff --git a/docs/design/interface.md b/docs/design/interface.md
index 1a6f09bc..b6b05972 100644
--- a/docs/design/interface.md
+++ b/docs/design/interface.md
@@ -27,8 +27,9 @@ green first: four defects in the theme cut passed every check and were found by
**Alerts.** One row per failure, never updated; the read side folds adjacent rows of one `(kb, kind)`
into an episode; read state is per person; visibility by role; a row names one subject and carries
-no display text, titles assembled by kind on the client; one global SSE stream tells clients to
-refetch; classification is a pure function on error types after retries are exhausted; a bell with
+no display text, titles assembled by kind on the client; an SSE event with no data tells clients to
+refetch, on the open base's stream or, with no base open, on a global one, so that a page holds
+one notification connection and gives it up after 30 seconds hidden (#1028); classification is a pure function on error types after retries are exhausted; a bell with
a red dot and a popover; a group can carry the action that closes its loop ("Run those again"); rows
purge after 30 days [0005]. Kinds: `source.sync_failed`, `llm.unreachable`, `llm.rate_limited`,
`llm.out_of_credit`, `data_source.schema_sync_failed`, `document.needs_reader`,
diff --git a/web/src/eventStream.ts b/web/src/eventStream.ts
new file mode 100644
index 00000000..6cb2afe3
--- /dev/null
+++ b/web/src/eventStream.ts
@@ -0,0 +1,84 @@
+// 一条通知用的事件流:断线恢复时补刷,页面藏起来一阵后把连接让出来(#1028)。
+//
+// 浏览器给同一个源的 HTTP/1.1 连接只有六条,事件流一条占一条、占着不放。从前每个标签页
+// 开两条通知流(当前库的事件、告警),正在生成的回答再占一条:两个标签页就把六条占满,
+// Stop 这样的普通请求排在后面发不出去;三个空闲的标签页也一样。所以一页只开一条通知流
+// (库事件那条顺带送告警,见 `useKbEvents`),藏起来超过 `HIDDEN_RELEASE_MS` 的页把它
+// 让出来,回到前台再连上。
+//
+// 事件没有回放:断线期间、让出期间的变化都收不到,所以重新连上时调一次 `onRecover` 补刷。
+// 首次正常连接不补刷,页面自己的读取已经是新的。
+
+/** 页面藏起来多久之后让出连接。短暂切走再回来不断流,也就不用补刷 */
+export const HIDDEN_RELEASE_MS = 30_000;
+
+export function subscribeEvents(
+ url: string,
+ handlers: Record<string, () => void>,
+ onRecover: () => void,
+): () => void {
+ const page = typeof document === "undefined" ? null : document;
+ let source: EventSource | null = null;
+ let missed = false;
+ let disposed = false;
+ let release: ReturnType<typeof setTimeout> | null = null;
+
+ // 卸载之后迟到的回调一律不作数:旧连接的事件不能再去失效新页面的查询
+ const guarded = Object.entries(handlers).map(([type, handler]): [string, () => void] => [
+ type,
+ () => {
+ if (!disposed) handler();
+ },
+ ]);
+ const listeners: Record<string, () => void> = {
+ ...Object.fromEntries(guarded),
+ error: () => {
+ if (!disposed) missed = true;
+ },
+ open: () => {
+ if (disposed || !missed) return;
+ missed = false;
+ onRecover();
+ },
+ };
+ const open = () => {
+ if (disposed || source) return;
+ source = new EventSource(url);
+ for (const [type, listener] of Object.entries(listeners)) source.addEventListener(type, listener);
+ };
+ const close = () => {
+ if (!source) return;
+ for (const [type, listener] of Object.entries(listeners)) source.removeEventListener(type, listener);
+ source.close();
+ source = null;
+ };
+ const cancelRelease = () => {
+ if (release === null) return;
+ clearTimeout(release);
+ release = null;
+ };
+ const onVisibility = () => {
+ cancelRelease();
+ if (page?.visibilityState !== "hidden") {
+ open();
+ return;
+ }
+ release = setTimeout(() => {
+ release = null;
+ if (!source) return;
+ close();
+ missed = true;
+ }, HIDDEN_RELEASE_MS);
+ };
+
+ page?.addEventListener("visibilitychange", onVisibility);
+ if (page?.visibilityState === "hidden") missed = true;
+ else open();
+
+ return () => {
+ disposed = true;
+ page?.removeEventListener("visibilitychange", onVisibility);
+ cancelRelease();
+ close();
+ };
+}
diff --git a/web/src/kb.tsx b/web/src/kb.tsx
index 594420e7..45c328cf 100644
--- a/web/src/kb.tsx
+++ b/web/src/kb.tsx
@@ -39,6 +39,8 @@ export function useKb(): {
workspaces: Workspace[];
setWorkspace: (id: string) => void;
setKb: (id: string) => void;
+ /** 工作区和库的列表都取回来了:`kb` 为空是真的没有库,不是还在加载 */
+ settled: boolean;
} {
const queryClient = useQueryClient();
const selectedId = useSyncExternalStore(wsStore.subscribe, wsStore.get);
@@ -120,5 +122,6 @@ export function useKb(): {
workspaces: list,
setWorkspace: wsStore.set,
setKb,
+ settled: workspaces.isFetched && (!ws || kbs.isFetched),
};
}
diff --git a/web/src/pages/Shell.tsx b/web/src/pages/Shell.tsx
index 4f2fe77e..dbe38890 100644
--- a/web/src/pages/Shell.tsx
+++ b/web/src/pages/Shell.tsx
@@ -50,17 +50,18 @@ export function Shell() {
queryKey: ["health"],
queryFn: api.health,
});
- const { kb, kbs, setKb } = useKb();
+ const { kb, kbs, setKb, settled } = useKb();
// 标题跟随当前 tab:`Graph · Utopia`;文档查看页归入 Library
const pathname = useRouterState({ select: (s) => s.location.pathname });
const tabLabel =
TABS.find((t) => pathname.startsWith(t.to))?.label ??
(pathname.startsWith("/doc/") ? S.nav.library : undefined);
usePageTitle(S.app.name, tabLabel);
- // 全局唯一的 KB 事件流连接:文档/审核状态实时刷新(替轮询)
+ // 全局唯一的 KB 事件流连接:文档/审核状态实时刷新(替轮询)。告警也从它来
useKbEvents(kb?.id);
- // 告警流是全局的:角标跨库,而系统级告警根本没有库
- useAlertEvents();
+ // 没有打开着的库时才单开告警流:一页只占一条通知用的连接(#1028)。
+ // 等列表取回来再判断,否则每次加载都先连上、库一到又断开
+ useAlertEvents(settled && !kb);
// 未登录就去登录页。**副作用要在 effect 里**,理由见下面 401 那一支
const unauthorized =
diff --git a/web/src/useAlertEvents.ts b/web/src/useAlertEvents.ts
index 956fe272..34c7a4d4 100644
--- a/web/src/useAlertEvents.ts
+++ b/web/src/useAlertEvents.ts
@@ -2,33 +2,19 @@
//
// 服务端推的那条不带任何数据也不判权限(见 alerts_routes::stream):收到就重取,
// 谁能看见什么由列表查询说了算。所以这里也不需要知道当前是哪个库。
+//
+// 打开着一个库的页不用这条:库事件流顺带送告警(`useKbEvents`),一页只占一条连接
+// (#1028)。`active` 为假时什么都不订。
import { useEffect } from "react";
import { useQueryClient } from "@tanstack/react-query";
+import { subscribeEvents } from "./eventStream";
-export function useAlertEvents() {
+export function useAlertEvents(active = true) {
const queryClient = useQueryClient();
useEffect(() => {
- const es = new EventSource("/api/v1/alerts/events");
- 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]);
+ if (!active) return;
+ // 断线期间的告警不会回放:恢复时同时补刷角标与列表。
+ const refresh = () => queryClient.invalidateQueries({ queryKey: ["alerts"] });
+ return subscribeEvents("/api/v1/alerts/events", { alert: refresh }, refresh);
+ }, [active, queryClient]);
}
diff --git a/web/src/useEventReconnect.test.ts b/web/src/useEventReconnect.test.ts
index 00263619..33fbf9c8 100644
--- a/web/src/useEventReconnect.test.ts
+++ b/web/src/useEventReconnect.test.ts
@@ -3,6 +3,7 @@ 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";
+import { HIDDEN_RELEASE_MS } from "./eventStream";
// 在 Node 环境执行 hook 的 effect,浏览器边界用可控事件源;查询与观察者仍用真实实现。
const hooks = vi.hoisted(() => ({
@@ -46,6 +47,26 @@ class FakeEventSource {
}
}
+/** 只有可见性的假页面:node 环境里没有 `document` */
+function fakePage(visible = true) {
+ const page = {
+ visibilityState: visible ? "visible" : "hidden",
+ listeners: new Set<() => void>(),
+ addEventListener(_type: string, listener: () => void) {
+ page.listeners.add(listener);
+ },
+ removeEventListener(_type: string, listener: () => void) {
+ page.listeners.delete(listener);
+ },
+ show(shown: boolean) {
+ page.visibilityState = shown ? "visible" : "hidden";
+ for (const listener of [...page.listeners]) listener();
+ },
+ };
+ vi.stubGlobal("document", page);
+ return page;
+}
+
const cleanups: Array<() => void> = [];
const clients: QueryClient[] = [];
const unsubscribes: Array<() => void> = [];
@@ -267,3 +288,78 @@ describe("alert stream reconnect", () => {
expect(query.fetch).toHaveBeenCalledTimes(1);
});
});
+
+describe("one notification stream per page (#1028)", () => {
+ it("carries alerts on the KB stream, and refreshes them when it recovers", async () => {
+ const client = createClient();
+ const badge = await watch(client, ["alerts", "unread"]);
+ const { source } = mount(() => useKbEvents("kb-a"));
+ source.emit("open");
+ source.emit("alert");
+ await vi.advanceTimersByTimeAsync(SETTLE_MS);
+ expect(badge.fetch).toHaveBeenCalledTimes(2);
+ source.emit("error");
+ source.emit("open");
+ expect(badge.fetch).toHaveBeenCalledTimes(3);
+ });
+
+ it("opens no alert stream while a KB stream is open", () => {
+ createClient();
+ mount(() => useKbEvents("kb-a"));
+ mount(() => useAlertEvents(false));
+ expect(FakeEventSource.instances.map((source) => source.url)).toEqual(["/api/v1/kbs/kb-a/events"]);
+ });
+
+ it("gives up the connection after the page has been hidden a while, and catches up on return", async () => {
+ const page = fakePage();
+ const client = createClient();
+ const documents = await watch(client, ["documents", "kb-a"]);
+ const { source } = mount(() => useKbEvents("kb-a"));
+ source.emit("open");
+
+ page.show(false);
+ await vi.advanceTimersByTimeAsync(HIDDEN_RELEASE_MS - 1);
+ expect(source.closed).toBe(false);
+ await vi.advanceTimersByTimeAsync(1);
+ expect(source.closed).toBe(true);
+ expect([...source.listeners.values()].every((listeners) => listeners.size === 0)).toBe(true);
+
+ documents.changeServer();
+ page.show(true);
+ const reopened = FakeEventSource.instances.at(-1)!;
+ expect(reopened).not.toBe(source);
+ expect(documents.fetch).toHaveBeenCalledTimes(1);
+ reopened.emit("open");
+ expect(documents.fetch).toHaveBeenCalledTimes(2);
+ });
+
+ it("keeps the connection through a short absence, and removes its page listener on cleanup", async () => {
+ const page = fakePage();
+ const client = createClient();
+ const documents = await watch(client, ["documents", "kb-a"]);
+ const { source, unmount } = mount(() => useKbEvents("kb-a"));
+ source.emit("open");
+ page.show(false);
+ await vi.advanceTimersByTimeAsync(HIDDEN_RELEASE_MS - 1);
+ page.show(true);
+ await vi.advanceTimersByTimeAsync(HIDDEN_RELEASE_MS);
+ expect(source.closed).toBe(false);
+ expect(FakeEventSource.instances).toHaveLength(1);
+ expect(documents.fetch).toHaveBeenCalledTimes(1);
+
+ page.show(false);
+ unmount();
+ expect(page.listeners.size).toBe(0);
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it("waits for a page opened in the background to be shown before connecting", () => {
+ const page = fakePage(false);
+ createClient();
+ mount(() => useAlertEvents());
+ expect(FakeEventSource.instances).toHaveLength(0);
+ page.show(true);
+ expect(FakeEventSource.instances).toHaveLength(1);
+ });
+});
+
diff --git a/web/src/useKbEvents.ts b/web/src/useKbEvents.ts
index 431e1e34..07de914f 100644
--- a/web/src/useKbEvents.ts
+++ b/web/src/useKbEvents.ts
@@ -1,5 +1,6 @@
// KB 事件流订阅:收到事件只做 react-query 失效重取(事件不带业务数据,天然幂等)。
// EventSource 断线自动重连,重连成功后补刷漏掉的变化;替代 Library/Review 的轮询。
+// 告警也从这条流来:一页只占一条通知用的连接(见 `eventStream`)。
//
// **失效是合并着做的。** 一篇文档抽取时每落一条事实就发一个 graph 事件,
// 从前每个事件各失效一次,图谱页在那几秒里把 overview 重取了十几遍——
@@ -11,6 +12,7 @@
// 这一层把当前库的变化即时推到页面上。
import { useEffect } from "react";
import { partialMatchKey, useQueryClient, type QueryKey } from "@tanstack/react-query";
+import { subscribeEvents } from "./eventStream";
import { STREAM_KEYS } from "./queryDefaults";
/** 一阵事件之间的静默期。抽取落事实的间隔远小于它,人眼看不出这点延迟 */
@@ -58,35 +60,28 @@ export function useKbEvents(kbId: string | undefined) {
SETTLE_MS,
);
- const es = new EventSource(`/api/v1/kbs/${kbId}/events`);
- 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;
+ const unsubscribe = subscribeEvents(
+ `/api/v1/kbs/${kbId}/events`,
+ {
+ document: () => push(["documents", kbId], ["graph"]),
+ graph: () => push(["graph"]),
+ // 映射探索跑完发的也是 review:Pending 那一栏得跟着刷新
+ review: () => push(["review", kbId], ["mappings", kbId]),
+ // 一句记忆抽出了等人点头的事实(0015):对话里那张确认卡跟着长出来
+ pending: () => push(["pending", kbId], ["review", kbId]),
+ source: () => push(["sources", kbId], ["documents", kbId]),
+ // 告警搭这条流过来(#1028):打开着一个库的页不再另开告警流
+ alert: () => push(["alerts"]),
+ },
+ () => {
// 事件没有回放,staleTime 到期也不会自己发请求。断线后恢复必须补刷;
// 首次正常连接交给页面已有的读取,首次连接失败再恢复则同样可能漏事件。
- push(...STREAM_KEYS.map((head) => [head, kbId]));
+ push(...STREAM_KEYS.map((head) => [head, kbId]), ["alerts"]);
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();
+ unsubscribe();
// 卸载时把攒着的刷掉而不是丢掉:换页回来看到的必须是新数据
flush();
};