94 lines
3.1 KiB
Markdown
94 lines
3.1 KiB
Markdown
---
|
|
id: "02-progressive-overview-state"
|
|
title: "Add progressive overview state"
|
|
status: done
|
|
wave: 2
|
|
depends_on:
|
|
- 01-bounded-filesystem-scanner
|
|
plan: "plan.md"
|
|
requirements:
|
|
- REQ-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002
|
|
acceptance_criteria:
|
|
- AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.1
|
|
- AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.2
|
|
- AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.4
|
|
- AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.5
|
|
- AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.9
|
|
- AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.10
|
|
system_design:
|
|
- ../../specs/system-page/system-design/storage-analysis-progress.md
|
|
---
|
|
|
|
# Task 02: Add Progressive Overview State
|
|
|
|
## Summary
|
|
|
|
Make storage overview reads nonblocking. Add single-flight progress state, stale-while-revalidate
|
|
snapshots, safe notifications, timing metadata, logs, and metrics.
|
|
|
|
## In scope
|
|
|
|
- Add progressive source callbacks to `storageOverview`.
|
|
- Extend `OverviewCache` with nonblocking state reads and generation fencing.
|
|
- Extend the storage response with snapshot, progress, and timing fields.
|
|
- Publish `system.storage.analysis.updated` without storage details.
|
|
- Add gateway wiring and focused observability.
|
|
- Preserve manual Analyze run history and job behavior.
|
|
|
|
## Out of scope
|
|
|
|
- Frontend rendering and polling.
|
|
- Persistent cache storage.
|
|
- Cleanup provider changes.
|
|
|
|
## Acceptance
|
|
|
|
- A blocked cold provider cannot block the initial HTTP response.
|
|
- Expired and failed refreshes keep the last successful snapshot unchanged.
|
|
- Concurrent reads, Analyze, invalidation, and late progress obey one generation-fenced flight.
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
(cd apps/backend && go test -race ./internal/system/storage ./internal/backendapp ./internal/gateway/websocket)
|
|
```
|
|
|
|
## Files likely touched
|
|
|
|
- `apps/backend/internal/system/storage/overview_cache.go`
|
|
- `apps/backend/internal/system/storage/overview_cache_test.go`
|
|
- `apps/backend/internal/system/storage/handler.go`
|
|
- `apps/backend/internal/system/storage/handler_test.go`
|
|
- `apps/backend/internal/system/storage/types.go`
|
|
- `apps/backend/internal/system/storage/operations.go`
|
|
- `apps/backend/internal/backendapp/storage_maintenance.go`
|
|
- `apps/backend/internal/backendapp/storage_maintenance_test.go`
|
|
- `apps/backend/internal/events/types.go`
|
|
- `apps/backend/internal/gateway/websocket/system_notifications.go`
|
|
- `apps/backend/pkg/websocket/actions.go`
|
|
|
|
## Dependencies
|
|
|
|
Task 01 supplies bounded progress callbacks.
|
|
|
|
## Risks
|
|
|
|
- Manual Analyze can accidentally create a second scan or job.
|
|
- Publishing while the cache mutex is locked can deadlock event consumers.
|
|
- A late callback can replace current state without generation checks.
|
|
|
|
## Parallelism
|
|
|
|
`sequential`
|
|
|
|
## Inputs
|
|
|
|
- `storage-analysis-progress.md` sections "Analysis state", "Cache flow", and "Progress delivery".
|
|
- ADR `2026-09-05-bounded-progressive-storage-analysis`.
|
|
|
|
## Results
|
|
|
|
Implemented the progressive cache/API contract, generation-fenced single-flight refreshes,
|
|
WebSocket notifications, structured completion logging, and storage scan metrics. The exact race
|
|
suite passed: 1,423 tests across storage, backendapp, and gateway/websocket.
|