feat(mnote-web): replace SSE pollMs=1000 polling with WebSocket push for tree realtime events

## Problem
Convex backend RSS grew to 7.7G due to ~17 HTTP POST /api/query/min
(32K+ in 32h) from the SSE polling loop in /api/tree/events?pollMs=1000.
Each poll triggered a Convex query even when nothing changed.

## Root Cause
The tree live EventSource client polled every 1s via SSE, calling
load_stream_overview() → execute_runtime_query_via_convex() → Convex
POST /api/query on every cycle, regardless of workspace state.

## Solution
Replace polling with push: add a `stream_delta_tx` broadcast channel
that publishes after every Convex mutation, consumed by WebSocket and
SSE endpoints for push-only delivery.

### Server-side
- **app.rs**: Add `stream_delta_tx: broadcast::Sender<Value>` to AppState
- **command_support.rs**: `execute_runtime_command_via_convex_with_artifacts`
  now takes `&AppState` (was `&AppConfig`) and pushes `{"kind":"command_committed",...}`
  to `stream_delta_tx` after every successful mutation
- **ws.rs**: Rewrite `handle_socket` with `tokio::select!` subscribing to
  `stream_delta_tx`; pushes delta events to WS clients on mutation, handles
  client `resync` requests for fresh snapshots
- **sse.rs**: `tree_events` endpoint now subscribes to both `block_delta_tx`
  and `stream_delta_tx`; when broadcast channels are available, runs in
  push-only mode (250ms heartbeat, no Convex query). Polling degrades to
  60s safety net. Keeps backward compatibility for non-WS clients.

### Client-side
- **layout.rs**: Bootstrap JSON now defaults to `transport: "convex-command-log-ws"`
  with `wsEndpoint: "/api/realtime/ws"`. TREE_LIVE_CONTROLLER_JS extended
  with `startWithWebSocket()` supporting snapshot/delta/resync/lagged-hint
  events; auto-fallback to SSE on WS failure after 2s.

### Caller updates (17 call sites)
- documents.rs, mindmap_api.rs, resource_trash.rs, tree.rs
- hermes_tools/{artifact,block,page}.rs
All updated from `state.config()` to `&state` for the new signature.

## Verification
- `cargo build` + `cargo test`: 295/298 passed (3 pre-existing failures)
- Browser smoke: page loaded → transport=convex-command-log-ws, status=connected
- Convex logs: 0 POST /api/query in 2min with page idle (vs ~17/min before)
- Initial burst: 8 queries on page load (normal), then silence
This commit is contained in:
lix-2026
2026-05-17 12:58:27 +08:00
parent 46ede5e251
commit 9d8e361e43
15 changed files with 798 additions and 136 deletions
+58 -5
View File
@@ -10,7 +10,7 @@ use axum::extract::{Extension, Query, State};
use axum::http::{HeaderMap, HeaderName, HeaderValue};
use axum::response::sse::{Event, KeepAlive, Sse};
use futures_util::stream;
use serde_json::Value;
use serde_json::{json, Value};
use std::convert::Infallible;
use std::time::Duration;
use tokio::time::sleep;
@@ -28,11 +28,28 @@ async fn events_with_block_delta(
context: RequestContext,
query: StreamSnapshotQuery,
block_delta_rx: Option<tokio::sync::broadcast::Receiver<Value>>,
) -> Result<Sse<impl futures_util::Stream<Item = Result<Event, Infallible>>>, WebError> {
events_with_stream_delta(state, context, query, block_delta_rx, None).await
}
/// Unified SSE stream: when `stream_delta_rx` is present, broadcast-driven push takes priority;
/// polling acts as safety net. When absent, pure polling mode.
async fn events_with_stream_delta(
state: AppState,
context: RequestContext,
query: StreamSnapshotQuery,
block_delta_rx: Option<tokio::sync::broadcast::Receiver<Value>>,
stream_delta_rx: Option<tokio::sync::broadcast::Receiver<Value>>,
) -> Result<Sse<impl futures_util::Stream<Item = Result<Event, Infallible>>>, WebError> {
let initial_payload = load_stream_snapshot(state.config(), &context, &query).await?;
let initial_cursor = read_stream_cursor_from_payload(&initial_payload);
let max_polls = query.max_polls;
let poll_ms = query.poll_ms.unwrap_or(2_000).max(250);
// When push-driven, use long poll interval as safety net; otherwise normal polling
let poll_ms = if stream_delta_rx.is_some() {
query.poll_ms.unwrap_or(60_000).max(1_000)
} else {
query.poll_ms.unwrap_or(2_000).max(250)
};
let state_for_stream = state.clone();
let context_for_stream = context.clone();
let query_for_stream = query.clone();
@@ -46,6 +63,7 @@ async fn events_with_block_delta(
initial_payload,
initial_emitted: false,
block_delta_rx,
stream_delta_rx,
}),
move |state| async move {
let mut state = state?;
@@ -58,7 +76,7 @@ async fn events_with_block_delta(
));
}
// Phase C:在每次 poll 前先检查是否有 block.delta 可发送
// Check block.delta broadcast first
if let Some(ref mut rx) = state.block_delta_rx {
match rx.try_recv() {
Ok(payload) => {
@@ -75,6 +93,39 @@ async fn events_with_block_delta(
}
}
// Check stream.delta broadcast (push mode: command_committed hints)
if let Some(ref mut rx) = state.stream_delta_rx {
match rx.try_recv() {
Ok(payload) => {
let hint = json!({
"kind": "delta",
"hint": "command_committed",
"commandName": payload.get("commandName"),
"commandId": payload.get("commandId"),
"workspaceId": payload.get("workspaceId"),
"requestId": payload.get("requestId"),
"traceId": payload.get("traceId"),
});
return Some((
Ok(stream_event("delta", &hint)),
Some(state),
));
}
Err(tokio::sync::broadcast::error::TryRecvError::Empty) => {}
Err(tokio::sync::broadcast::error::TryRecvError::Closed) => {
state.stream_delta_rx = None;
}
Err(tokio::sync::broadcast::error::TryRecvError::Lagged(_)) => {}
}
}
// If push-driven and we already checked both broadcasts, brief sleep then re-check
if state.stream_delta_rx.is_some() {
sleep(Duration::from_millis(250)).await;
return Some((Ok(stream_event("heartbeat", &json!({}))), Some(state)));
}
// Pure polling mode
loop {
if let Some(max_polls) = max_polls {
if state.polls >= max_polls {
@@ -84,7 +135,7 @@ async fn events_with_block_delta(
state.polls += 1;
sleep(Duration::from_millis(poll_ms)).await;
// 每次 poll 后也检查一下 delta
// Check block.delta after poll sleep
if let Some(ref mut rx) = state.block_delta_rx {
match rx.try_recv() {
Ok(payload) => {
@@ -185,7 +236,8 @@ pub async fn tree_events(
headers.insert(name, HeaderValue::from_static("rust-web"));
}
let block_delta_rx = state.block_delta_tx.subscribe();
let sse = events_with_block_delta(state, context, query, Some(block_delta_rx)).await?;
let stream_delta_rx = state.stream_delta_tx.subscribe();
let sse = events_with_stream_delta(state, context, query, Some(block_delta_rx), Some(stream_delta_rx)).await?;
Ok((headers, sse))
}
@@ -199,6 +251,7 @@ struct StreamPollState {
initial_emitted: bool,
#[allow(dead_code)]
block_delta_rx: Option<tokio::sync::broadcast::Receiver<Value>>,
stream_delta_rx: Option<tokio::sync::broadcast::Receiver<Value>>,
}
fn live_poll_query(query: &StreamSnapshotQuery) -> StreamSnapshotQuery {