World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-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.rsindex 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.mdindex 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 decidesvisibility once. Someone without permission is woken for nothing, and the push pathholds 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 fromthe 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 "nodiff --git a/docs/design/interface.md b/docs/design/interface.mdindex 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 witha red dot and a popover; a group can carry the action that closes its loop ("Run those again"); rowspurge 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.tsnew file mode 100644index 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.tsxindex 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.tsxindex 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`;文档查看页归入 Libraryconst 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.tsindex 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.tsindex 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-queryimport { 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.tsindex 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();};