已关闭
Add versioned admin observation API and resumable SSE events #93
urandon创建于  24 天前关闭于  23 天前
urandon
urandon成员
24 天前 创建

Parent: #52
Depends on: embedded admin runtime foundation

Design: https://gitcode.com/urandon/gitcode-mcp/wiki/Admin-Web-UI-Design-2026-08-25.md

Goal

Expose a stable, sanitized admin observation API whose DTOs model product truth rather than mirroring CLI commands or SQLite tables.

Scope

  • Add /api/admin/v1/snapshot, caches, cache/repository detail, jobs, maintenance, diagnostics, and capabilities read endpoints.
  • Compose existing coordinator, cache, doctor, RAG, maintenance, and capability-registry use cases; do not call CLI/MCP subprocesses.
  • Model the six semantic cohorts from the design: identity/topology, readiness, corpus coverage, execution, policy, and governance/recovery.
  • Represent head freshness, tail completeness, secondary coverage, projection/content generation, and RAG coverage as independent lanes.
  • Represent current truth separately from active contention, scheduled retry, and last stage error, incorporating #91.
  • Use public cache_ref/fingerprints and sanitized typed errors; exclude credentials, raw payloads, raw cache content, and absolute private paths.
  • Add coarse overview snapshots to avoid browser N+1 calls.
  • Add a bounded SSE invalidation/progress stream with opaque cursor, reconnect, replay window, and snapshot_required fallback.
  • Define paging/filter contracts for terminal jobs and structured progress events.

Acceptance criteria

  1. A single snapshot tells the UI what needs attention, which work is active, and the independent readiness/coverage state of each managed cache/repository.
  2. A current RAG namespace remains visibly current even if the last maintenance stage failed transiently.
  3. Observation endpoints have no network/provider/indexing side effects.
  4. SSE reconnect is loss-tolerant: missed retained events replay; expired cursors force a snapshot refresh.
  5. DTOs are versioned, deterministic, public-safe, and covered by golden/contract tests.
  6. API handlers enforce the same cache identity and capability boundaries as CLI/MCP use cases.
  7. go test ./... and git diff --check pass.

Non-goals

  • Mutation endpoints.
  • Raw log streaming.
  • Direct browser access to the local JSON-RPC socket.
likedislike
urandonurandon成员
24 天前 添加了label:enhancement
urandon
urandon成员
23 天前 评论:

Implementation plan for #93 (kept as a comment so the original issue input remains fixed):

  1. Keep internal/adminhttp as transport/security only. Add versioned public DTOs there and inject one read-only snapshot provider from the coordinator; no CLI/MCP subprocesses and no provider/network calls.
  2. Build the snapshot in internal/servicectl from the in-process JobManager, MaintenanceManager, capability registry, and read-only cache access. Absolute cache paths and config references stay daemon-local; browser identities are cache UUID/path fingerprints.
  3. Model service/readiness, caches/repositories, five coverage lanes, jobs, policy, diagnostics, and capabilities as separate typed cohorts. A current lane state, active contention, scheduled retry, and last stage error remain independent fields.
  4. Serve coarse snapshot plus filtered cache/repository/job/maintenance/diagnostic/capability resources. Job history is deterministic and cursor/limit bounded.
  5. Add a controller-owned bounded event ring. SSE uses opaque monotonic cursors, retained replay, keepalives, and an explicit snapshot_required event when a cursor is outside the replay window. Events are compact invalidations/progress summaries, never raw logs.
  6. Contract tests will cover stable JSON shape, sorting/filtering/paging, public-safe serialization, observation side-effect freedom, SSE replay/expiry, auth, and existing Host/Origin boundaries.

The existing UI shell will switch from the temporary readiness DTO to the coarse snapshot and consume invalidation events without changing the selected visual direction.

likedislike
urandonurandon成员
23 天前 关联了pull request:Add versioned admin observation API and resumable SSE
urandon
urandon成员
23 天前 评论:

Implemented in !97.

The slice now provides:

  • a deterministic admin.v1 coarse snapshot plus versioned cache, repository, job, maintenance, diagnostics, and capability resources;
  • six UI-facing cohorts through composed product DTOs rather than CLI/SQLite mirrors;
  • independent head, tail, secondary, projection/content-generation, and RAG lanes;
  • current RAG truth kept independent from contention, scheduled retry, and last-stage error;
  • opaque cache_ref and one-way fingerprints, typed sanitized errors, no absolute paths/raw logs/raw cached bodies;
  • bounded job filters/paging and structured sanitized progress;
  • bounded SSE with opaque cursor, retained replay, Last-Event-ID reconnect, session expiry, and snapshot_required for expired/future cursors;
  • aggregate source-kind counts so periodic observation does not load cached source bodies/aliases;
  • the existing Svelte shell wired to snapshot + SSE while preserving System-default Light/Dark/System theming.

Verification:

  • go test ./...
  • go test -race ./internal/adminhttp ./internal/servicectl
  • go vet ./...
  • git diff --check
  • frontend typecheck/unit/Playwright smoke
  • deterministic embedded asset rebuild
  • live local Playwright QA for one-time session exchange, snapshot contract, SSE, reload continuity, and path redaction

No tag/release and no routine source install were produced; this is one slice of the larger admin epic.

likedislike
urandonurandon成员
23 天前 关闭了 issue
urandonurandon成员
23 天前 关联了里程碑:Admin Web UI
urandonurandon成员
23 天前 添加了label:admin-ui
urandonurandon成员
23 天前 添加了label:service