# P1: Hardening, Correctness & Security Improvements

**Priority**: P1 — Important hardening and correctness work  
**Theme**: Eliminate data integrity risks, resource exhaustion vectors, and incomplete security controls.  
**Status**: Not started  
**Depends on**: P0 (recommended — many P1 items are easier to verify once the service starts/stops cleanly)

## Goal

Make the cache **safe by default** against common failure modes, malicious or malformed input, and misconfiguration while preserving the high-performance characteristics required for Steam traffic.

## Overview

Even after P0 items are resolved, several classes of defects remain:

- Unbounded memory usage on large responses or cache promotion
- Incomplete / spoofable client identification used for rate limiting
- Overstated features (LFU, hybrid eviction) that do not actually work as documented
- Significant "smart caching" code (adaptive/predictive) that provides no actual benefit today

These items directly affect correctness, security posture, and user trust.

## Tasks

### P1-01: Implement bounded / streaming response handling (prevent OOM on large bodies)

- **Description**: `ServeHTTP` currently does `bodyData, err := io.ReadAll(resp.Body)` for every cache miss before deciding whether to serve or cache. Promotion paths do the same. There are no size limits.
- **Impact**:
  - A single large (or malicious) response from upstream can exhaust RAM and crash the process.
  - Steam chunks are usually small, but manifests, depots, and especially misconfigured upstreams can be very large.
  - Coalesced request buffering also keeps full bodies in memory.
- **Affected Files**:
  - `steamcache/steamcache.go` (ServeHTTP around lines 1505-1518, reconstruct, coalesced paths)
  - `vfs/cache/cache.go` (promoteToFast)
  - Possibly disk/memory write paths
- **Approach** (choose one or hybrid):
  1. Preferred long-term: Stream to client with `io.TeeReader` (or custom tee) directly into the VFS `Create` writer while serving. Only buffer small responses.
  2. Short-term mitigation: Add a hard per-request body cap (e.g. 64 MiB or configurable) and return 502/413 for anything larger without caching.
  3. Make coalesced request buffering also respect a size limit or use a temp file for very large objects.
- **Acceptance Criteria**:
  - No `io.ReadAll` of unbounded upstream responses in the hot path.
  - Configurable or hard safety limit exists and is documented.
  - Large responses are still served correctly (streaming) when they fit the limit.
  - Existing Range + cache hit behavior is unaffected.
  - New integration test that attempts a > limit response and verifies graceful handling.
- **Dependencies**: P0-04 (error metrics will help prove the new path works)
- **Effort**: Medium-Large (4-8 hours). Streaming tee writer is the cleanest but requires care with VFS `Create` semantics.

### P1-02: Make client IP extraction for rate limiting configurable and safe

- **Description**: `getClientIP` unconditionally trusts `X-Forwarded-For` and `X-Real-IP`.
- **Impact**:
  - Any client can spoof its IP and bypass per-client `max_requests_per_client` limits.
  - In environments with a real reverse proxy this is fine; in direct or partially proxied setups it is a DoS vector.
- **Affected Files**:
  - `steamcache/steamcache.go` (getClientIP and getOrCreateClientLimiter)
  - `config/config.go` (new settings)
  - `cmd/root.go`
- **Approach**:
  1. Add config options:
     - `trusted_proxies: []string` (CIDR list) or `trust_x_forwarded_for: bool`
     - Default should be conservative (`false` or empty list).
  2. When not trusting forwarded headers, fall back strictly to `r.RemoteAddr`.
  3. When trusting, implement proper "rightmost trusted proxy" logic (do not just take the first XFF entry blindly).
  4. Document the security implications clearly in README.
- **Acceptance Criteria**:
  - Default behavior is safe (does not trust arbitrary XFF).
  - When `trusted_proxies` is configured, correct client IP is extracted.
  - Spoofing tests exist (or at least negative tests).
  - Per-client semaphore still works correctly.
- **Dependencies**: None
- **Effort**: Medium (3-5 hours including tests + docs)

### P1-03: Implement real LFU or remove the false claim; make "hybrid" meaningful

- **Description**:
  - `EvictLFU` just calls `EvictBySizeAsc` (smallest first) with a TODO comment.
  - `EvictHybrid` is literally just `EvictLRU`.
  - Documentation in README and config examples heavily advertises these algorithms.
- **Impact**: Users who select `lfu` or `hybrid` get behavior they did not ask for. This is misleading and can produce worse cache hit rates than expected.
- **Affected Files**:
  - `vfs/eviction/eviction.go`
  - `vfs/memory/memory.go` (EvictLFU / EvictHybrid methods if they exist)
  - `vfs/disk/disk.go`
  - README.md (GC algorithm section)
  - Possibly `config/config.go` comments
- **Approach** (two options — pick one):
  **Option A (Recommended for P1)**: Implement a real (approximate) LFU using the existing `AccessCount` field already present in `FileInfo`.
  **Option B**: Remove the non-functional choices from the public API and docs for now; keep only algorithms that actually do something different (LRU, FIFO, largest, smallest). Re-introduce LFU later under P2.
- **Acceptance Criteria**:
  - Selecting `lfu` either does real LFU or is rejected at config validation time with a clear message.
  - "hybrid" either has a documented size+recency policy or is removed.
  - Unit tests exist that demonstrate different eviction behavior between the algorithms under controlled access patterns.
- **Dependencies**: P0-03 (so invalid algorithm names are caught early)
- **Effort**: Medium (if implementing real LFU: 4-6 hours; if removing: 1-2 hours)

### P1-04: Decide the fate of the adaptive/predictive caching subsystem

- **Description**: Large amounts of code (`vfs/adaptive/`, `vfs/predictive/`, plus fields and goroutines in `SteamCache`) collect access patterns but never actually change eviction strategy, promotion decisions, or GC algorithm at runtime.
- **Impact**:
  - Wasted memory and CPU (multiple background analyzers + maps).
  - Increased goroutine count and shutdown complexity.
  - False advertising in README ("adaptive and predictive caching").
  - Maintenance burden for code that provides zero user value today.
- **Affected Files**:
  - `vfs/adaptive/adaptive.go`
  - `vfs/predictive/predictive.go`
  - `steamcache/steamcache.go` (record* methods, manager fields, New, Shutdown)
  - `vfs/cache/cache.go` (promotion decisions)
- **Approach** (choose one):
  1. **Prune (fast)**: Remove the unused subsystems, the recording calls, and all related goroutines/fields. Update docs. Keep the data structures in `types.FileInfo` if they are still useful for future work.
  2. **Integrate (larger)**: Wire the analyzers into actual decisions (e.g., switch promotion aggressiveness, temporarily bias toward LFU-style scoring, pre-warm on predicted sequences). This is a P2-level project.
- **Acceptance Criteria** (for prune path):
  - No more goroutines or memory overhead from these packages at runtime.
  - `Shutdown` becomes simpler.
  - README no longer claims adaptive/predictive behavior that does not exist.
  - If kept for future, the packages are clearly marked "experimental / not yet active".
- **Dependencies**: None
- **Effort**: Prune = 2-4 hours. Full integration = multi-day project (defer to P2).

## Definition of Done (P1 Milestone)

- [ ] P1-01 (streaming/bounded bodies) implemented and load-tested.
- [ ] P1-02 (client IP trust) implemented with safe defaults + documentation.
- [ ] P1-03 (LFU/hybrid truthfulness) resolved (either real impl or removal + doc fixes).
- [ ] P1-04 (adaptive/predictive) decided and executed (prune is acceptable for P1).
- [ ] All changes have accompanying tests (unit + at least one integration test per major feature).
- [ ] `go test -race ./...` and manual long-running soak (with induced large responses and spoofed headers) pass.
- [ ] README and any user-facing docs are updated to reflect reality (no more over-claiming).

## Notes for Implementers

- P1-01 is the highest leverage item for stability under real-world (or adversarial) traffic.
- When implementing streaming writes, be careful with the current VFS `Create(key, declaredSize)` contract — it may need adjustment.
- Consider adding a `max_object_size` config knob as part of P1-01.

## References

- Original full code review
- `steamcache/steamcache.go:1506` (io.ReadAll)
- `vfs/cache/cache.go:206` (promotion ReadAll)
- `vfs/eviction/eviction.go:82` (LFU TODO)
- Large unused packages in `vfs/adaptive` and `vfs/predictive`

---

**After P1**: The service should be safe to expose to untrusted Steam clients on a LAN with reasonable resource protections.