feat(static-file): conversation workspace file serving with pluggable access guard

[zhuqingyv]

Background & Motivation

Old architecture (main)

crates/aionui-file/src/watch_service.rs provides two independent features:

1. Single-file watch (file_watcher) — one shared RecommendedWatcher, NonRecursive, broadcasts fileWatch.fileChanged on change.
2. Office watch (office_watchers) — per-workspace RecommendedWatcher, Recursive, broadcasts workspaceOfficeWatch.fileAdded on office file create.

Both share a single DashMap<String, Instant> for 200ms debouncing, with no subscription model and no WS-disconnect cleanup.

Capabilities that did not exist:

• No directory-level change push (frontend file tree could not refresh in real time).
• No workspace static-file HTTP service (frontend had to read files via the IPC bridge).
• The MessageRouter trait had no on_disconnect lifecycle hook.

What this branch does

Adds (does not replace):

1. workspace_watcher.rs + workspace_watcher_registry.rs + workspace_watcher_router.rs — subscription-based directory change push, built on notify-debouncer-full with one OS watcher per workspace and event fan-out (also covers office-file create detection).
2. aionui-static-file crate — static-file service with a pluggable async AccessGuard (Range 206, ETag, 256 MB default size limit).
3. aionui-conversation/src/routes_static_file.rs — GET /api/conversations/{id}/files/{*path}.
4. MessageRouter trait gains an on_disconnect callback.

Modifies:

5. service.rs removes the post-write/-delete fileStream.contentUpdate broadcast (that responsibility moves to the workspace watcher's modify events).

Untouched:

6. watch_service.rs is left as-is (the old file_watcher + office_watchers still run).

Known issue: duplicate office watch

The new EventDispatcher already implements office fan-out (with_office_broadcaster). When the frontend subscribes to a workspace, the new system emits workspaceOfficeWatch.fileAdded automatically. However the frontend still calls the legacy /api/fs/office-watch/start API, so the same workspace ends up with two OS watchers and may emit duplicate events.

Follow-up required: the frontend must drop /api/fs/office-watch/start|stop and rely on the new fan-out; once no caller remains, office_watchers in watch_service.rs can be deleted.

---

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                         FRONTEND (Electron / Web)                        │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────────┐       ┌────────────────────┐       ┌───────────────┐ │
│  │ File Tree UI  │       │ File Content Viewer │       │ File Changes  │ │
│  │ (Arco <Tree>) │       │ (Monaco / Preview)  │       │ (Git Snapshot)│ │
│  └──────┬────────┘       └──────────┬─────────┘       └───────────────┘ │
│         │ expand/collapse            │ open file                         │
│         ▼                            ▼                                   │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │                    useWorkspaceWatcher (hook)                      │  │
│  │                                                                   │  │
│  │  expand   → ws.send("workspace.subscribe",   {workspace, dirs})   │  │
│  │  collapse → ws.send("workspace.unsubscribe", {workspace, dirs})   │  │
│  │  on "workspace.changed"  → incrementally update tree nodes        │  │
│  │  on "workspace.overflow" → full HTTP refresh                      │  │
│  │  on modify → tell viewer to refetch file content                  │  │
│  └────────────────────────┬──────────────────────────────────────────┘  │
│                           │                                              │
├───────────────────────────┼──────────────────────────────────────────────┤
│        WebSocket          │              HTTP                             │
│   (single shared conn)    │           (on demand)                         │
│                           │                                              │
│  ┌──────────────┐   ┌────┴────────────────────────┐                     │
│  │ WS messages   │   │   Static file HTTP API      │                     │
│  │ subscribe →   │   │                             │                     │
│  │ unsubscribe → │   │ GET /api/conversations/     │                     │
│  │ ← changed    │   │   {id}/files/{*path}         │                     │
│  │ ← overflow   │   │                             │                     │
│  └──────┬────────┘   │ JWT auth + Range + ETag    │                     │
│         │            └────┬────────────────────────┘                     │
└─────────┼─────────────────┼──────────────────────────────────────────────┘
          │   Network       │
          ▼                 ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         BACKEND (Rust / Axum)                            │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────────────────────┐     ┌────────────────────────────────┐ │
│  │   WebSocket layer            │     │  Static file HTTP layer         │ │
│  │   (aionui-realtime)          │     │  (aionui-conversation)          │ │
│  │                              │     │                                 │ │
│  │  recv_loop                   │     │  GET /conversations/{id}/files  │ │
│  │    ├─ "workspace.*"          │     │      /{*path}                   │ │
│  │    │       ▼                 │     │  → StaticFileService            │ │
│  │    │  MessageRouter.route()  │     │  → Range (206) / ETag / Auth    │ │
│  │    │       ▼                 │     │  → 256 MB default size limit    │ │
│  │  on_disconnect()             │     └────────────────────────────────┘ │
│  └────────────┬─────────────────┘                                        │
│               ▼                                                          │
│  ┌───────────────────────────────────────────────────────────────────┐   │
│  │              WorkspaceWatchRouter (aionui-file)                    │   │
│  │                                                                   │   │
│  │  subscribe   → SubscriptionRegistry.subscribe(conn, ws, dirs)     │   │
│  │  subscribe   → SubscriptionRegistry.subscribe_extensions(...)     │   │
│  │  unsubscribe → SubscriptionRegistry.unsubscribe(conn, ws, dirs)   │   │
│  │  disconnect  → SubscriptionRegistry.remove_connection(conn)        │   │
│  │                         │                                         │   │
│  │              is_first? ─┴─ is_last?                               │   │
│  │                │              │                                    │   │
│  │          start_watch     stop_watch                                │   │
│  └────────────────┬──────────────┬───────────────────────────────────┘   │
│                   ▼              ▼                                        │
│  ┌───────────────────────────────────────────────────────────────────┐   │
│  │         WorkspaceWatchManager                                      │   │
│  │                                                                   │   │
│  │  notify-debouncer-full (single OS watcher per workspace)           │   │
│  │  → RecursiveMode::Recursive                                       │   │
│  │  → handles atomic save / rename pairing / event de-dup            │   │
│  │  → emits semantic events (Create / Modify / Remove)               │   │
│  │                                                                   │   │
│  │  Event fan-out:                                                   │   │
│  │    ├─→ Office consumer: filter Create + .pptx/.docx/.xlsx         │   │
│  │    │   → broadcast "workspaceOfficeWatch.fileAdded"                │   │
│  │    └─→ Workspace consumer: gitignore → parent_dir → subscribers   │   │
│  └────────────────┬──────────────────────────────────────────────────┘   │
│                   │                                                       │
│                   ▼                                                       │
│  ┌───────────────────────────────────────────────────────────────────┐   │
│  │  Workspace dispatch:                                               │   │
│  │    GitignoreFilter → SubscriptionRegistry lookup → send_to         │   │
│  │                                                                   │   │
│  │  per dir:                                                         │   │
│  │    changes > 500 → "workspace.overflow" → subscribers              │   │
│  │    changes ≤ 500 → "workspace.changed"  → subscribers              │   │
│  └───────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐  │
│  │  [LEGACY — pending removal]                                       │  │
│  │  watch_service.rs: file_watcher (NonRecursive, single file)        │  │
│  │                    office_watchers (per-workspace Recursive)        │  │
│  │  Frontend still uses /api/fs/office-watch/start|stop               │  │
│  └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘  │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Data flow: directory expand → push

1.  User expands the src directory
2.  Frontend → ws.send({name:"workspace.subscribe", data:{workspace, dirs:["src"]}})
3.  WorkspaceWatchRouter.route() → registry.subscribe(conn, ws, ["src"])
4.  is_first=true → WorkspaceWatchManager.start_workspace_watch(ws)
5.  Creates a debouncer-full watcher (RecursiveMode::Recursive, single OS watcher)
6.  An external process creates src/new_file.rs
7.  OS FSEvents → debouncer-full de-dups / pairs renames → DebouncedEvent
8.  Event fan-out → office consumer (no match, skip) + workspace consumer
9.  Workspace: GitignoreFilter check → parent_dir("src/new_file.rs") = "src"
10. registry.get_subscribers_for_dir(ws, "src") → [conn_1]
11. ws_manager.send_to(conn_1, {name:"workspace.changed", data:{workspace, changes:[...]}})
12. Frontend onChanged → incrementally inserts "new_file.rs" into the tree

WS protocol

Direction	Event	Payload
→ Backend	workspace.subscribe	{workspace: string, dirs?: string[], extensions?: string[]}
→ Backend	workspace.unsubscribe	{workspace: string, dirs?: string[], extensions?: string[]}
← Frontend	workspace.changed	{workspace: string, changes: [{path, kind}]}
← Frontend	workspace.overflow	{workspace: string}

• kind: create / modify / delete
• path: relative to the workspace root
• Only changes to immediate children of subscribed directories are pushed
• Unsubscribing a parent directory cascades to its children automatically
• Authentication: JWT via Authorization: Bearer <token> header or aionui-session cookie

Follow-up plan

Current state: the new workspace watcher already provides office fan-out, but the legacy office_watchers in watch_service.rs are still running. Frontend code that uses both ends up with two OS watchers per workspace.

Steps:

1. Frontend stops calling /api/fs/office-watch/start|stop and relies on workspace-watcher fan-out.
2. Backend deletes the office_watchers code path in watch_service.rs.
3. Evaluate whether file_watcher (single-file watch) can also be replaced by the workspace watcher.
4. Final goal: at most one OS watcher per workspace.

Files changed

New crate:

• crates/aionui-static-file/ — static-file service with pluggable AccessGuard

New files:

• crates/aionui-file/src/workspace_watcher.rs — SharedWorkspaceWatcher, GitignoreFilter, EventDispatcher, WorkspaceWatchManager
• crates/aionui-file/src/workspace_watcher_registry.rs — SubscriptionRegistry
• crates/aionui-file/src/workspace_watcher_router.rs — WorkspaceWatchRouter (impl MessageRouter)
• crates/aionui-conversation/src/routes_static_file.rs — conversation static-file route

Modified:

• crates/aionui-realtime/src/router.rs — adds MessageRouter::on_disconnect
• crates/aionui-realtime/src/handler.rs — calls on_disconnect on WS close
• crates/aionui-file/src/service.rs — drops broadcaster dependency and the fileStream.contentUpdate broadcast
• crates/aionui-file/src/lib.rs — module declarations / exports
• crates/aionui-app/src/router/state.rs — wires WorkspaceWatchRouter and the office broadcaster

Untouched:

• crates/aionui-file/src/watch_service.rs — legacy file_watcher + office_watchers left as-is

Test plan

• Workspace watcher unit tests (types, gitignore, parent_dir, registry, router)
• All aionui-file tests passing
• All aionui-realtime tests passing
• aionui-app tests passing (including static_file_e2e)
• Clippy clean (-D warnings)
• Full workspace: 5615 tests pass
• Frontend integration: subscribe on expand, verify WS events arrive
• Follow-up: drop legacy office-watch API on the frontend, confirm no duplicate events

🤖 Generated with Claude Code