Files
kandev/docs/plans/storage-analysis-progress/task-02-progressive-overview-state.md
T
2026-09-06 16:09:03 +00:00

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.