176 lines
10 KiB
Markdown
176 lines
10 KiB
Markdown
# P2: Performance, Quality & Maintainability Improvements
|
|
|
|
**Priority**: P2 — Performance, refactoring, and long-term health
|
|
**Theme**: Make the codebase faster, smaller, easier to reason about, and production-operable at scale.
|
|
**Status**: Not started
|
|
**Depends on**: P0 strongly recommended; P1 nice-to-have for some verification steps
|
|
|
|
## Goal
|
|
|
|
Turn a clever but monolithic prototype into a high-quality, maintainable Go project that is pleasant to work on and easy to operate.
|
|
|
|
## Overview
|
|
|
|
After the critical stability (P0) and safety (P1) work, the project still carries technical debt that affects:
|
|
|
|
- Runtime performance under sustained load (lock contention, unnecessary copies)
|
|
- Developer velocity (huge source file, magic numbers, copy-paste)
|
|
- Operational visibility (weak metrics, no benchmarks, incomplete CI)
|
|
- Correctness confidence (very low test coverage on the storage layer)
|
|
|
|
These items are important for long-term success but are not immediate crash or security risks.
|
|
|
|
## Tasks
|
|
|
|
### P2-01: Refactor the monolithic `ServeHTTP` and split `steamcache/steamcache.go`
|
|
|
|
- **Description**: The core request handler is a single ~500+ line function with many responsibilities (authz, rate limiting, coalescing, upstream fetch, cache write, metrics, adaptive recording). The file itself is 1724 lines.
|
|
- **Impact**:
|
|
- Extremely hard to test individual behaviors in isolation.
|
|
- High risk of regression when touching any part of request handling.
|
|
- New contributors are intimidated.
|
|
- **Affected Files**:
|
|
- `steamcache/steamcache.go` (primary)
|
|
- Potentially new files: `steamcache/handler.go`, `steamcache/coalescing.go`, `steamcache/upstream.go`, `steamcache/response.go`, etc.
|
|
- **Approach**:
|
|
1. Extract clear types for the request context (e.g. `requestContext` holding clientIP, cacheKey, service, timing, etc.).
|
|
2. Break `ServeHTTP` into smaller focused methods: `handleCacheHit`, `handleCoalesced`, `fetchAndCache`, `writeCacheEntry`, etc.
|
|
3. Move pure helper logic (range parsing, response reconstruction, hash generation) into separate small files if they aren't already.
|
|
4. Keep the `SteamCache` struct as the coordinator but reduce its god-object nature over time.
|
|
- **Acceptance Criteria**:
|
|
- No single function in the package > 150 lines.
|
|
- `ServeHTTP` itself becomes a thin dispatcher (< 80 lines).
|
|
- All existing behavior (including edge cases around coalescing + errors + Ranges) still passes the test suite.
|
|
- New unit tests become feasible for the extracted pieces.
|
|
- **Dependencies**: None (can be done in parallel with other P2 work)
|
|
- **Effort**: Large (8-16 hours). Best done as a series of small, reviewable refactors rather than one giant PR.
|
|
|
|
### P2-02: Reduce lock contention during eviction
|
|
|
|
- **Description**: `EvictLRU`, `EvictBySize`, etc. take the global `mu.Lock()` on the entire `MemoryFS`/`DiskFS` for the duration of the scan + deletion loop.
|
|
- **Impact**: Under cache pressure (very common when the disk cache fills), all other operations (Open, Stat, Create) serialize behind the eviction. This can cause request latency spikes even for hot memory-tier hits.
|
|
- **Affected Files**:
|
|
- `vfs/memory/memory.go` (eviction methods)
|
|
- `vfs/disk/disk.go` (eviction methods)
|
|
- **Approach** options:
|
|
1. Collect candidates under read lock, then do the actual deletes and size updates in a second phase or in small batches while briefly acquiring write locks.
|
|
2. Move eviction into a dedicated background goroutine that the GC layer signals, using finer-grained coordination.
|
|
3. Use a "generation" or "watermark" approach so readers can proceed while eviction cleans up.
|
|
- **Acceptance Criteria**:
|
|
- Benchmark or load test shows improved tail latencies for `Open`/`Stat` while eviction is running.
|
|
- No data races introduced (race detector clean).
|
|
- Total size and LRU invariants remain correct after concurrent eviction.
|
|
- **Dependencies**: Good test coverage on the VFS layer (see P2-04)
|
|
- **Effort**: Medium-Large (4-8 hours + measurement)
|
|
|
|
### P2-03: Dramatically improve test coverage on the VFS and storage layer
|
|
|
|
- **Description**: Most `vfs/*` packages currently have 0% coverage. The critical storage, eviction, GC, and tiering logic is almost untested in isolation.
|
|
- **Impact**:
|
|
- Very low confidence when changing eviction, promotion, or GC behavior.
|
|
- Hard to catch regressions in size accounting, LRU ordering, or sharded locking.
|
|
- Blocks safe execution of P2-02 and future performance work.
|
|
- **Affected Areas** (need new or expanded tests):
|
|
- `vfs/memory/*`
|
|
- `vfs/disk/*`
|
|
- `vfs/gc/*`
|
|
- `vfs/cache/*`
|
|
- `vfs/eviction/*`
|
|
- `vfs/locks/*` and `vfs/lru/*` (at least basic)
|
|
- **Approach**:
|
|
1. Write focused unit tests for each VFS implementation using `t.TempDir` for disk.
|
|
2. Add property-style or table-driven tests that verify size never exceeds capacity after many Create + Evict cycles.
|
|
3. Test concurrent Create/Open/Delete/Delete under load (with `-race`).
|
|
4. Test promotion, tier fallback, and lazy discovery paths.
|
|
5. Add benchmarks (`BenchmarkMemoryFS_CreateOpen`, `BenchmarkEvictionUnderPressure`, etc.).
|
|
- **Acceptance Criteria**:
|
|
- Combined coverage for all `vfs/*` packages ≥ 70% (statement).
|
|
- At least one benchmark per major component that can be run in CI or locally.
|
|
- New tests catch at least one real bug during development (celebrated in commit message).
|
|
- **Dependencies**: None
|
|
- **Effort**: Large (12-20 hours spread over multiple sessions). High leverage.
|
|
|
|
### P2-04: Clean up build, CI, linting, and repository hygiene
|
|
|
|
- **Description**:
|
|
- Makefile `run` / `run-debug` targets are hardcoded to a Windows binary path.
|
|
- `dist/` artifacts are committed even though `.gitignore` lists `/dist/`.
|
|
- No golangci-lint, no `go vet` in CI, no vulnerability scanning.
|
|
- Test target exists but coverage reporting and gates are missing.
|
|
- **Impact**: Painful local development on non-Windows machines. Risk of shipping known-bad artifacts. Harder to maintain code quality over time.
|
|
- **Affected Files**:
|
|
- `Makefile`
|
|
- `.gitea/workflows/test-pr.yaml` (and release workflow)
|
|
- `.gitignore` (verify dist is truly ignored)
|
|
- Possibly add `.golangci.yml`
|
|
- **Approach**:
|
|
1. Fix Makefile to use `go run .` or build a platform-appropriate binary.
|
|
2. Add a `make lint` target and wire golangci-lint (with reasonable defaults + errcheck, gosec, etc.).
|
|
3. Update Gitea workflows to run `go vet`, lint, and (optionally) `govulncheck`.
|
|
4. Remove any committed files under `dist/` (or add them to `.gitignore` more aggressively and git-rm them).
|
|
5. Consider adding a coverage report step (even if not enforcing a hard gate yet).
|
|
- **Acceptance Criteria**:
|
|
- `make test` and `make run` work cleanly on Linux and macOS.
|
|
- CI runs lint + vet and fails the PR on new issues.
|
|
- Repository no longer contains built binaries in its tree.
|
|
- `go mod tidy` + build is reproducible.
|
|
- **Dependencies**: None
|
|
- **Effort**: Small-Medium (3-5 hours)
|
|
|
|
### P2-05: Use the existing rich error types consistently and improve observability
|
|
|
|
- **Description**: A nice `steamcache/errors` package with context, unwrap, retry classification, and client/server error helpers exists but is almost unused. Metrics are still very basic.
|
|
- **Impact**:
|
|
- Lost opportunity for better structured logging and error handling.
|
|
- Harder to write generic retry / circuit-breaker logic later.
|
|
- `/metrics` and logs give limited insight into what actually failed and why.
|
|
- **Approach**:
|
|
1. Audit the top 10-15 error sites in `ServeHTTP` and VFS layers.
|
|
2. Convert the most important ones to use `NewSteamCacheError*` helpers.
|
|
3. Wire more structured fields into zerolog calls using the error types.
|
|
4. Expand the metrics package (per-service error counts, upstream error breakdown, cache write failures, etc.).
|
|
5. Consider exporting Prometheus-style metrics in addition to the current text format (optional).
|
|
- **Acceptance Criteria**:
|
|
- At least the major error categories (upstream fetch, cache corruption, rate limit, validation) use the custom error types.
|
|
- `/metrics` surface becomes more useful (new counters for categories of errors).
|
|
- No behavior change for clients (still get the same HTTP status codes).
|
|
- **Dependencies**: P0-04 (basic error counting)
|
|
- **Effort**: Medium (4-6 hours)
|
|
|
|
## Definition of Done (P2 Milestone)
|
|
|
|
- [ ] Major refactoring (P2-01) landed in reviewable chunks; `ServeHTTP` is no longer a monster function.
|
|
- [ ] Eviction lock contention measurably reduced (P2-02).
|
|
- [ ] VFS/storage layer has ≥70% test coverage + benchmarks (P2-03).
|
|
- [ ] Build/CI hygiene is excellent: cross-platform make targets, lint in CI, clean repo (P2-04).
|
|
- [ ] Error handling and metrics are noticeably better (P2-05).
|
|
- [ ] `go test -race -shuffle=on ./...` + `go vet` + linter are all green.
|
|
- [ ] A new contributor can run `make help`, `make test`, `make run` on Linux/macOS without friction.
|
|
- [ ] At least one performance or quality regression has been prevented by the new tests/benchmarks during the work.
|
|
|
|
## Suggested Order of Execution (within P2)
|
|
|
|
1. P2-04 (CI hygiene) — cheap wins, improves confidence for everything else.
|
|
2. P2-03 (test coverage on VFS) — unblocks safe work on P2-02.
|
|
3. P2-02 (eviction locking).
|
|
4. P2-01 (big refactor) — do this when the test safety net is stronger.
|
|
5. P2-05 (errors + observability) — can run in parallel with others.
|
|
|
|
## Notes for Implementers
|
|
|
|
- P2 work has the highest risk of "refactoring for its own sake." Every change should be justified by either a concrete performance win, a maintainability win that reduces future bug rate, or enabling future features.
|
|
- Keep changes reviewable. Large refactors should be broken into multiple PRs with clear "no behavior change" invariants.
|
|
- The custom LRU list and sharded locking are clever — make sure any refactoring preserves their performance characteristics.
|
|
|
|
## References
|
|
|
|
- `steamcache/steamcache.go:1724` (file size)
|
|
- `vfs/disk/disk.go` and `vfs/memory/memory.go` eviction methods (global lock held)
|
|
- `.gitea/workflows/`
|
|
- `Makefile`
|
|
- `steamcache/errors/errors.go` (under-used)
|
|
|
|
---
|
|
|
|
**After P2**: The project should feel like a mature, professional Go service rather than a sophisticated prototype.
|