ops: Signal disk-full and eviction capacity pressure

When the disk (or memory) tier is at cap or the volume returns ENOSPC, ops currently look like random misses with no clear "we are dropping data." Count those events as capacity_pressure_events on /metrics and log tier plus reason so operators can tell capacity pressure from a cold cache, without changing the existing evictions counter. Link: #36
ops: Signal disk-tier attach pending vs ready (#45 )
2026-09-07 19:23:55 +00:00 · 2026-09-07 12:02:10 -05:00 · 2026-09-07 16:58:13 +00:00 · 2026-09-07 11:37:06 -05:00 · 2026-09-07 16:32:36 +00:00 · 2026-09-07 10:00:58 -05:00
16 changed files with 986 additions and 90 deletions
@@ -10,8 +10,8 @@ SteamCache2 is a blazing fast download cache for Steam, designed to reduce bandw
 - Reduces bandwidth usage
 - Easy to set up and configure aside from dns stuff to trick Steam into using it
 - Supports multiple clients
- **NEW:** YAML configuration system with automatic config generation
- **NEW:** Simple Makefile for development workflow
+- YAML configuration with automatic config generation on first run
+- Makefile for development and validation workflows
 - Cross-platform builds (Linux, macOS, Windows)

 ## Quick Start
@@ -34,7 +34,10 @@ SteamCache2 is a blazing fast download cache for Steam, designed to reduce bandw

   The application will automatically create a `config.yaml` file with default settings and exit, allowing you to customize it.

-3. **Edit the configuration** (`config.yaml`):
+3. **Edit the configuration** (`config.yaml`) for a real Steam front-door:
+
+   Leave `upstream` empty. With an empty upstream, steamcache2 fetches from the request `Host` (the same pattern SteamPrefill / real Steam clients use when DNS points them at your cache). Do **not** paste a fake host like `https://steam.cdn.com` — that is not a Steam CDN and will not put you in front of Steam.
+
   ```yaml
   listen_address: :80
   cache:
@@ -45,10 +48,19 @@ SteamCache2 is a blazing fast download cache for Steam, designed to reduce bandw
           size: 10GB
           path: ./disk
           gc_algorithm: hybrid
-   upstream: "https://steam.cdn.com"  # Set your upstream server
+   # Empty upstream = use the client Host as the origin (Steam CDN names only).
+   upstream: ""
   ```

-4. **Run the application again:**
+4. **Point Steam (or SteamPrefill) at this cache** before you expect hits:
+
+   - **LAN DNS:** resolve `lancache.steamcontent.com` (and other Steam content names your clients use) to this server's LAN IP.
+   - **Single Windows PC:** add a hosts override — see [Windows Hosts File Override](#windows-hosts-file-override) (`<cache-ip> lancache.steamcontent.com`).
+   - Restart Steam (or your prefill tool) after DNS/hosts changes.
+
+   Empty-upstream direct fetch only allows Steam CDN host suffixes (`steamcontent.com`, `steampowered.com`, `steamstatic.com`). Literal IPs and unrelated hosts are rejected.
+
+5. **Run the application again:**
   ```bash
   make run  # or ./steamcache2
   ```
@@ -69,11 +81,16 @@ curl -s -i http://localhost/lancache-heartbeat
 | Field | Meaning |
 | --- | --- |
 | `cache_hits` / `cache_misses` / `hit_rate` | Whether later requests were served from cache |
+| `range_cache` / `range_upstream` | Range GETs served as 206 from a cached object vs after a full upstream fetch |
 | `memory_cache_hits` / `disk_cache_hits` | Which tier served the hits |
 | `total_requests` / `errors` | Volume and failures |
+| `disk_tier_ready` | `0` while disk slow-tier attach pending; `1` when attached, or when no disk configured (N/A — not waiting) |
+| `capacity_pressure_events` | Soft eviction under the memory or disk cap, and/or disk Create/Write/Mkdir hitting ENOSPC (volume full). Distinct from cold-cache misses and from the existing `evictions` counter. Logs `tier` (memory or disk) and `reason` (eviction or enospc). |

 A first pass through new content is mostly misses (`hit_rate` near 0). Repeat the same content and `cache_hits` / `hit_rate` should rise.

+Steam clients lean on Range requests. When an object is already cached, a Range GET is served locally as 206 from that full object (`range_cache`). On a Range miss the cache still fetches and stores the full upstream body, then returns the requested byte range as 206 (`range_upstream`).
+
 To confirm the process is up (HTTP 204 and `X-LanCache-Processed-By: SteamCache2`):

 ```bash
@@ -82,6 +99,8 @@ curl -s -i http://localhost/lancache-heartbeat

 Use GET (`curl -i`), not HEAD (`curl -I`): the server only accepts GET.

+Heartbeat also returns `X-SteamCache-Disk-Tier: pending|ready|disabled` (`disabled` = memory-only / no disk; `pending`/`ready` = disk configured attach state).
+
 These are the cache process's own `/metrics` and `/lancache-heartbeat` endpoints. There is no separate metrics daemon.

 If you changed `listen_address`, point curl at that host:port instead. For a full SteamPrefill validation workflow (small caches, coalescing, GC), see [Validating Full Functionality](#validating-full-functionality-with-external-tools).
@@ -167,7 +186,7 @@ The recommended validation config is at [docs/examples/validate-config.yaml](doc
 Running a realistic SteamPrefill benchmark workload through a built steamcache2 exercises the complete public surface that matters for production use:
 - Steam User-Agent detection and depot/manifest/chunk URL patterns
 - Full MISS → cache write → HIT (and HIT-COALESCED) paths
- Range request handling from cached full responses
+- Range request handling from cached full responses (local 206 on HIT via `range_cache`; MISS fetches the full object then serves the requested slice as 206 via `range_upstream`)
 - Request coalescing under concurrent load
 - Memory tier + disk tier interaction (including async disk attach)
 - Garbage collection and eviction under pressure
@@ -238,8 +257,9 @@ cache:
    gc_algorithm: hybrid

 # Upstream server configuration
-# The upstream server to proxy requests to
-upstream: "https://steam.cdn.com"
+# Leave empty to fetch from the request Host (Steam CDN names only).
+# Set only when chaining caches (table RAM cache -> room disk cache).
+upstream: ""
 ```

 #### Startup Validation
@@ -274,6 +294,10 @@ See `config.Validate()` and `steamcache.New` error paths. This ensures the LAN a
 - The explicit startup guard (reduce size if pre-existing on-disk > cap) runs as the literal last step of bg init, before the barrier opens.
 - Add a note for operators: very large disk caches (tens/hundreds GB with millions files) may show extended "memory-only or no-cache" behavior at startup (seconds to minutes depending on storage speed); this is by design for responsiveness.
 - Godoc on `disk.New` and `DiskFS.Size` expanded with the barrier/attach behavior.
+- Startup logs: Info "Disk slow tier attach pending..." then later "Disk slow tier attached (...)" for disk-only and mixed modes.
+- `/metrics` exposes `disk_tier_ready` 0/1 and stays responsive during attach (GetMetrics does not block on Size while pending).
+- `/lancache-heartbeat` header `X-SteamCache-Disk-Tier` mirrors that state.
+- `/metrics` `capacity_pressure_events` counts times the cache dropped data under capacity pressure (soft eviction at the memory or disk cap, or disk Create/Write/Mkdir returning ENOSPC). Logs include `tier=memory|disk` and `reason=eviction|enospc` so operators can grep and tell this apart from a cold cache. The existing `evictions` counter is unchanged.

 #### Garbage Collection Algorithms

@@ -262,6 +262,13 @@ func (sc *SteamCache) streamCachedResponse(w http.ResponseWriter, r *http.Reques
 		// Send the range data
 		_, _ = w.Write(rangeData) // client write error ignored (disconnect during range body send is not actionable)

+		// Range served from cache: count the range-specific metric and the range
+		// bytes actually written (handleCacheHit skips full-blob byte counting for
+		// Range requests so these are not double-counted).
+		sc.metrics.IncrementRangeCache()
+		sc.metrics.AddBytesServed(int64(len(rangeData)))
+		sc.metrics.AddBytesSaved(int64(len(rangeData)))
+
 		logger.Logger.Info().
 			Str("cache_key", cacheKey).
 			Str("url", r.URL.String()).
@@ -56,6 +56,15 @@ func (sc *SteamCache) handleSpecialEndpoints(w http.ResponseWriter, r *http.Requ
 		logger.Logger.Debug().
 			Str("client_ip", clientIP).
 			Msg("LanCache heartbeat request")
+		diskTier := "disabled"
+		if sc.disk != nil {
+			if sc.metrics.GetDiskTierReady() == 1 {
+				diskTier = "ready"
+			} else {
+				diskTier = "pending"
+			}
+		}
+		w.Header().Add("X-SteamCache-Disk-Tier", diskTier)
 		w.Header().Add("X-LanCache-Processed-By", "SteamCache2")
 		w.WriteHeader(http.StatusNoContent)
 		_, _ = w.Write(nil) // client write error ignored (heartbeat path; nil write is no-op)
@@ -109,8 +118,14 @@ func (sc *SteamCache) handleCacheHit(w http.ResponseWriter, r *http.Request, cac
 				// Track cache hit metrics
 				sc.metrics.IncrementCacheHits()
 				sc.metrics.AddResponseTime(time.Since(tstart))
+				if r.Header.Get("Range") == "" {
+					// Full-object HIT: count the cached blob served. Range HITs skip
+					// this here — streamCachedResponse counts the range bytes actually
+					// written to the client instead, so BytesServed/Saved reflect the
+					// partial body and are not double-counted.
 					sc.metrics.AddBytesServed(int64(len(cachedData)))
 					sc.metrics.AddBytesSaved(int64(len(cachedData)))
+				}
 				sc.metrics.IncrementServiceRequests(service.Name)

 				logger.Logger.Debug().
@@ -549,14 +564,40 @@ func (sc *SteamCache) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("X-LanCache-Status", "MISS")
 		w.Header().Set("X-LanCache-Processed-By", "SteamCache2")

-		// Stream the response body to client
+		// Stream the response body to client.
+		// Range miss: the Range header was stripped for the upstream fetch (so the
+		// FULL object is cached below); serve the client's requested slice from the
+		// full body as 206, matching the HIT Range path.
+		if rangeHeader := r.Header.Get("Range"); rangeHeader != "" {
+			start, end, totalSize, rangeValid := parseRangeHeader(rangeHeader, int64(len(bodyData)))
+			if !rangeValid {
+				// Invalid range — 416 (consistent with the HIT Range path). Drop the
+				// upstream Content-Length: it describes the full body, which 416 does
+				// not send (a stale CL would hang clients waiting for a body).
+				w.Header().Del("Content-Length")
+				w.Header().Set("Content-Range", fmt.Sprintf("bytes */%d", len(bodyData)))
+				w.WriteHeader(http.StatusRequestedRangeNotSatisfiable)
+			} else {
+				rangeData := bodyData[start : end+1]
+				w.Header().Set("Content-Range", fmt.Sprintf("bytes %d-%d/%d", start, end, totalSize))
+				w.Header().Set("Content-Length", fmt.Sprintf("%d", len(rangeData)))
+				w.Header().Set("Accept-Ranges", "bytes")
+				w.WriteHeader(http.StatusPartialContent)
+				_, _ = w.Write(rangeData) // client write error ignored (disconnect during MISS range body send is not actionable)
+
+				// Range required an upstream fetch (full object) then served as 206
+				sc.metrics.IncrementRangeUpstream()
+				sc.metrics.AddBytesServed(int64(len(rangeData))) // range bytes only, not the full cached object
+			}
+		} else {
 			w.WriteHeader(resp.StatusCode)
 			_, _ = w.Write(bodyData) // client write error ignored (disconnect during MISS body send is not actionable)
+			sc.metrics.AddBytesServed(int64(len(bodyData)))
+		}

 		// Track cache miss metrics
 		sc.metrics.IncrementCacheMisses()
 		sc.metrics.AddResponseTime(time.Since(tstart))
-		sc.metrics.AddBytesServed(int64(len(bodyData)))
 		sc.metrics.IncrementServiceRequests(service.Name)

 		// Verify we received the complete file by checking Content-Length
@@ -7,6 +7,8 @@ import (
 	"sync"
 	"sync/atomic"
 	"time"
+
+	"s1d3sw1ped/steamcache2/steamcache/logger"
 )

 // Metrics tracks various performance and operational metrics
@@ -16,6 +18,8 @@ type Metrics struct {
 	CacheHits      int64
 	CacheMisses    int64
 	CacheCoalesced int64
+	RangeCache     int64 // Range requests served as 206 from an already-cached object (HIT)
+	RangeUpstream  int64 // Range requests that required an upstream fetch (full object), served as 206
 	Errors         int64
 	RateLimited    int64

@@ -31,6 +35,8 @@ type Metrics struct {
 	DiskCacheHits          int64
 	Promotions             int64
 	Evictions              int64
+	CapacityPressureEvents int64 // soft eviction under cap and/or disk ENOSPC
+	DiskTierReady          int64 // 0=pending (or unset), 1=ready or no-disk (N/A)

 	// Expanded observability (upstream breakdowns, cache write failures, per-service errors)
 	UpstreamErrors     int64
@@ -78,6 +84,17 @@ func (m *Metrics) IncrementCacheCoalesced() {
 	atomic.AddInt64(&m.CacheCoalesced, 1)
 }

+// IncrementRangeCache increments the Range-from-cache counter (HIT served as 206)
+func (m *Metrics) IncrementRangeCache() {
+	atomic.AddInt64(&m.RangeCache, 1)
+}
+
+// IncrementRangeUpstream increments the Range-from-upstream counter (full object
+// fetched upstream, requested slice served as 206)
+func (m *Metrics) IncrementRangeUpstream() {
+	atomic.AddInt64(&m.RangeUpstream, 1)
+}
+
 // IncrementErrors increments the error counter
 func (m *Metrics) IncrementErrors() {
 	atomic.AddInt64(&m.Errors, 1)
@@ -114,6 +131,17 @@ func (m *Metrics) SetDiskCacheSize(size int64) {
 	atomic.StoreInt64(&m.DiskCacheSize, size)
 }

+// SetDiskTierReady sets whether the disk slow tier is attached (1) or still pending (0).
+// Memory-only (no disk) also uses 1 — meaning "not waiting on disk attach". Reset does not clear this.
+func (m *Metrics) SetDiskTierReady(ready int64) {
+	atomic.StoreInt64(&m.DiskTierReady, ready)
+}
+
+// GetDiskTierReady returns 1 if disk tier is ready (or no disk configured), else 0 while attach pending.
+func (m *Metrics) GetDiskTierReady() int64 {
+	return atomic.LoadInt64(&m.DiskTierReady)
+}
+
 // IncrementMemoryCacheHits increments memory cache hits
 func (m *Metrics) IncrementMemoryCacheHits() {
 	atomic.AddInt64(&m.MemoryCacheHits, 1)
@@ -140,6 +168,37 @@ func (m *Metrics) GetServiceRequests(service string) int64 {

 func (m *Metrics) IncrementPromotions()             { atomic.AddInt64(&m.Promotions, 1) }
 func (m *Metrics) IncrementEvictions()              { atomic.AddInt64(&m.Evictions, 1) }
+func (m *Metrics) IncrementCapacityPressureEvents() { atomic.AddInt64(&m.CapacityPressureEvents, 1) }
+
+// NoteSoftEviction records one cap-pressure eviction batch that freed bytes.
+// Keeps the existing evictions counter and also increments capacity_pressure_events.
+// Nil m is safe: the log still fires so ops can grep without metrics wired.
+func NoteSoftEviction(m *Metrics, tier string, evicted uint) {
+	if evicted == 0 {
+		return
+	}
+	if m != nil {
+		m.IncrementEvictions()
+		m.IncrementCapacityPressureEvents()
+	}
+	logger.Logger.Info().
+		Str("tier", tier).
+		Str("reason", "eviction").
+		Uint("bytes_evicted", evicted).
+		Msg("cache capacity pressure")
+}
+
+// NoteNoSpace records a disk Create/Write/Mkdir ENOSPC (or equivalent) event.
+func NoteNoSpace(m *Metrics, err error) {
+	if m != nil {
+		m.IncrementCapacityPressureEvents()
+	}
+	logger.Logger.Warn().
+		Str("tier", "disk").
+		Str("reason", "enospc").
+		Err(err).
+		Msg("cache capacity pressure")
+}

 // Additional observability counters
 func (m *Metrics) IncrementUpstreamErrors()     { atomic.AddInt64(&m.UpstreamErrors, 1) }
@@ -188,6 +247,8 @@ func (m *Metrics) GetStats() *Stats {
 		CacheHits:              cacheHits,
 		CacheMisses:            cacheMisses,
 		CacheCoalesced:         atomic.LoadInt64(&m.CacheCoalesced),
+		RangeCache:             atomic.LoadInt64(&m.RangeCache),
+		RangeUpstream:          atomic.LoadInt64(&m.RangeUpstream),
 		Errors:                 atomic.LoadInt64(&m.Errors),
 		RateLimited:            atomic.LoadInt64(&m.RateLimited),
 		HitRate:                hitRate,
@@ -196,10 +257,12 @@ func (m *Metrics) GetStats() *Stats {
 		TotalBytesSaved:        atomic.LoadInt64(&m.TotalBytesSaved),
 		MemoryCacheSize:        atomic.LoadInt64(&m.MemoryCacheSize),
 		DiskCacheSize:          atomic.LoadInt64(&m.DiskCacheSize),
+		DiskTierReady:          atomic.LoadInt64(&m.DiskTierReady),
 		MemoryCacheHits:        atomic.LoadInt64(&m.MemoryCacheHits),
 		DiskCacheHits:          atomic.LoadInt64(&m.DiskCacheHits),
 		Promotions:             atomic.LoadInt64(&m.Promotions),
 		Evictions:              atomic.LoadInt64(&m.Evictions),
+		CapacityPressureEvents: atomic.LoadInt64(&m.CapacityPressureEvents),
 		ServiceRequests:        serviceRequests,
 		UpstreamErrors:         atomic.LoadInt64(&m.UpstreamErrors),
 		CacheWriteFailures:     atomic.LoadInt64(&m.CacheWriteFailures),
@@ -215,6 +278,8 @@ func (m *Metrics) Reset() {
 	atomic.StoreInt64(&m.CacheHits, 0)
 	atomic.StoreInt64(&m.CacheMisses, 0)
 	atomic.StoreInt64(&m.CacheCoalesced, 0)
+	atomic.StoreInt64(&m.RangeCache, 0)
+	atomic.StoreInt64(&m.RangeUpstream, 0)
 	atomic.StoreInt64(&m.Errors, 0)
 	atomic.StoreInt64(&m.RateLimited, 0)
 	atomic.StoreInt64(&m.TotalResponseTime, 0)
@@ -224,6 +289,7 @@ func (m *Metrics) Reset() {
 	atomic.StoreInt64(&m.DiskCacheHits, 0)
 	atomic.StoreInt64(&m.Promotions, 0)
 	atomic.StoreInt64(&m.Evictions, 0)
+	atomic.StoreInt64(&m.CapacityPressureEvents, 0)
 	atomic.StoreInt64(&m.UpstreamErrors, 0)
 	atomic.StoreInt64(&m.CacheWriteFailures, 0)

@@ -244,6 +310,8 @@ type Stats struct {
 	CacheHits        int64
 	CacheMisses      int64
 	CacheCoalesced   int64
+	RangeCache       int64
+	RangeUpstream    int64
 	Errors           int64
 	RateLimited      int64
 	HitRate          float64
@@ -253,10 +321,12 @@ type Stats struct {
 	MemoryCacheSize  int64

 	DiskCacheSize          int64
+	DiskTierReady          int64
 	MemoryCacheHits        int64
 	DiskCacheHits          int64
 	Promotions             int64
 	Evictions              int64
+	CapacityPressureEvents int64
 	UpstreamErrors         int64
 	CacheWriteFailures     int64
 	ServiceErrors          map[string]int64
@@ -276,6 +346,8 @@ func WriteText(w http.ResponseWriter, stats *Stats) {
 	_, _ = fmt.Fprintf(w, "cache_hits %d\n", stats.CacheHits)
 	_, _ = fmt.Fprintf(w, "cache_misses %d\n", stats.CacheMisses)
 	_, _ = fmt.Fprintf(w, "cache_coalesced %d\n", stats.CacheCoalesced)
+	_, _ = fmt.Fprintf(w, "range_cache %d\n", stats.RangeCache)
+	_, _ = fmt.Fprintf(w, "range_upstream %d\n", stats.RangeUpstream)
 	_, _ = fmt.Fprintf(w, "errors %d\n", stats.Errors)
 	_, _ = fmt.Fprintf(w, "rate_limited %d\n", stats.RateLimited)
 	_, _ = fmt.Fprintf(w, "upstream_errors %d\n", stats.UpstreamErrors)
@@ -284,6 +356,7 @@ func WriteText(w http.ResponseWriter, stats *Stats) {
 	_, _ = fmt.Fprintf(w, "disk_cache_hits %d\n", stats.DiskCacheHits)
 	_, _ = fmt.Fprintf(w, "promotions %d\n", stats.Promotions)
 	_, _ = fmt.Fprintf(w, "evictions %d\n", stats.Evictions)
+	_, _ = fmt.Fprintf(w, "capacity_pressure_events %d\n", stats.CapacityPressureEvents)
 	for svc, cnt := range stats.ServiceErrors {
 		_, _ = fmt.Fprintf(w, "service_errors{service=%q} %d\n", svc, cnt)
 	}
@@ -297,5 +370,6 @@ func WriteText(w http.ResponseWriter, stats *Stats) {

 	_, _ = fmt.Fprintf(w, "memory_cache_size %d\n", stats.MemoryCacheSize)
 	_, _ = fmt.Fprintf(w, "disk_cache_size %d\n", stats.DiskCacheSize)
+	_, _ = fmt.Fprintf(w, "disk_tier_ready %d\n", stats.DiskTierReady)
 	_, _ = fmt.Fprintf(w, "uptime_seconds %.2f\n", stats.Uptime.Seconds())
 }
@@ -0,0 +1,63 @@
+package metrics
+
+import (
+	"bytes"
+	"errors"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestCapacityPressureEventsWriteTextAndReset(t *testing.T) {
+	t.Parallel()
+	m := NewMetrics()
+	if got := m.GetStats().CapacityPressureEvents; got != 0 {
+		t.Fatalf("initial CapacityPressureEvents=%d, want 0", got)
+	}
+
+	NoteSoftEviction(m, "memory", 0)
+	if got := m.GetStats().CapacityPressureEvents; got != 0 {
+		t.Fatalf("zero-byte eviction counted: %d", got)
+	}
+
+	NoteSoftEviction(m, "memory", 128)
+	st := m.GetStats()
+	if st.CapacityPressureEvents != 1 {
+		t.Fatalf("after memory eviction, CapacityPressureEvents=%d, want 1", st.CapacityPressureEvents)
+	}
+	if st.Evictions != 1 {
+		t.Fatalf("after memory eviction, Evictions=%d, want 1 (existing counter kept)", st.Evictions)
+	}
+
+	NoteSoftEviction(m, "disk", 64)
+	NoteNoSpace(m, errors.New("no space left on device"))
+	st = m.GetStats()
+	if st.CapacityPressureEvents != 3 {
+		t.Fatalf("after disk eviction + ENOSPC, CapacityPressureEvents=%d, want 3", st.CapacityPressureEvents)
+	}
+	if st.Evictions != 2 {
+		t.Fatalf("ENOSPC must not increment evictions; Evictions=%d, want 2", st.Evictions)
+	}
+
+	rec := httptest.NewRecorder()
+	WriteText(rec, st)
+	body := rec.Body.Bytes()
+	if !bytes.Contains(body, []byte("capacity_pressure_events 3")) {
+		t.Errorf("WriteText missing capacity_pressure_events 3: %q", rec.Body.String())
+	}
+	if !bytes.Contains(body, []byte("evictions 2")) {
+		t.Errorf("WriteText missing evictions 2: %q", rec.Body.String())
+	}
+
+	m.Reset()
+	st = m.GetStats()
+	if st.CapacityPressureEvents != 0 || st.Evictions != 0 {
+		t.Errorf("after Reset, CapacityPressureEvents=%d Evictions=%d, want 0", st.CapacityPressureEvents, st.Evictions)
+	}
+}
+
+func TestNoteSoftEvictionNilMetrics(t *testing.T) {
+	t.Parallel()
+	// Must not panic when metrics are not wired (unit tests / early init).
+	NoteSoftEviction(nil, "memory", 10)
+	NoteNoSpace(nil, errors.New("ENOSPC"))
+}
@@ -0,0 +1,386 @@
+// steamcache/range_test.go
+package steamcache
+
+import (
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// TestRangeHitServedLocally verifies that a Range GET against an already-cached
+// object is served locally as 206 (no upstream re-fetch) and increments range_cache.
+func TestRangeHitServedLocally(t *testing.T) {
+	body := []byte("0123456789abcdef") // 16 bytes
+	var upstreamCalls atomic.Int64
+	f := func(w http.ResponseWriter, r *http.Request) {
+		upstreamCalls.Add(1)
+		w.Header().Set("Content-Type", "application/octet-stream")
+		_, _ = w.Write(body)
+	}
+	sc, _ := newTestCacheWithFakeUpstream(t, f, "1MB", "0")
+	srv := newCacheServer(t, sc)
+	c := &http.Client{Timeout: 5 * time.Second}
+
+	// 1) Populate the cache with a full (non-Range) MISS.
+	req, err := http.NewRequest("GET", srv.URL+"/depot/rangetest/chunk", nil)
+	if err != nil {
+		t.Fatalf("NewRequest: %v", err)
+	}
+	req.Header.Set("User-Agent", "Valve/Steam HTTP Client 1.0")
+	resp, err := c.Do(req)
+	if err != nil {
+		t.Fatalf("miss GET: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("miss GET: expected 200, got %d", resp.StatusCode)
+	}
+	_, _ = io.Copy(io.Discard, resp.Body)
+	_ = resp.Body.Close()
+	if got := sc.GetMetrics().CacheMisses; got < 1 {
+		t.Fatalf("expected CacheMisses >= 1 after first GET, got %d", got)
+	}
+
+	// 2) Range GET against the same URL — must be a local 206 HIT.
+	req2, err := http.NewRequest("GET", srv.URL+"/depot/rangetest/chunk", nil)
+	if err != nil {
+		t.Fatalf("NewRequest: %v", err)
+	}
+	req2.Header.Set("User-Agent", "Valve/Steam HTTP Client 1.0")
+	req2.Header.Set("Range", "bytes=4-7")
+	resp2, err := c.Do(req2)
+	if err != nil {
+		t.Fatalf("range GET: %v", err)
+	}
+	data, err := io.ReadAll(resp2.Body)
+	_ = resp2.Body.Close()
+	if err != nil {
+		t.Fatalf("read range body: %v", err)
+	}
+	if resp2.StatusCode != http.StatusPartialContent {
+		t.Fatalf("range GET: expected 206, got %d", resp2.StatusCode)
+	}
+	if string(data) != "4567" {
+		t.Errorf("range GET: expected body %q, got %q", "4567", data)
+	}
+	if got := resp2.Header.Get("X-LanCache-Status"); got != "HIT" {
+		t.Errorf("range GET: expected X-LanCache-Status HIT, got %q", got)
+	}
+	if got := resp2.Header.Get("Content-Range"); got != "bytes 4-7/16" {
+		t.Errorf("range GET: expected Content-Range bytes 4-7/16, got %q", got)
+	}
+	if got := resp2.Header.Get("Accept-Ranges"); got != "bytes" {
+		t.Errorf("range GET: expected Accept-Ranges bytes, got %q", got)
+	}
+
+	// Upstream must NOT have been hit again.
+	if got := upstreamCalls.Load(); got != 1 {
+		t.Errorf("upstream hit %d times, want exactly 1 (range HIT must be local)", got)
+	}
+
+	// range_cache incremented, range_upstream untouched.
+	stats := sc.GetMetrics()
+	if stats.RangeCache != 1 {
+		t.Errorf("expected RangeCache == 1 after range HIT, got %d", stats.RangeCache)
+	}
+	if stats.RangeUpstream != 0 {
+		t.Errorf("expected RangeUpstream == 0 (no range miss yet), got %d", stats.RangeUpstream)
+	}
+	if stats.CacheHits < 1 {
+		t.Errorf("expected CacheHits >= 1 after range HIT, got %d", stats.CacheHits)
+	}
+	// BytesServed: 16 (full miss body) + 4 (range bytes) = 20.
+	if stats.TotalBytesServed != 20 {
+		t.Errorf("expected TotalBytesServed == 20 (16 + range 4), got %d", stats.TotalBytesServed)
+	}
+}
+
+// TestRangeMissServes206FromFullFetch verifies that a Range GET on a cold key fetches
+// the FULL object from upstream (Range stripped), caches it, and serves the requested
+// slice as 206 with range_upstream incremented.
+func TestRangeMissServes206FromFullFetch(t *testing.T) {
+	body := []byte("0123456789abcdef") // 16 bytes
+	var upstreamCalls atomic.Int64
+	var upstreamSawRange atomic.Bool
+	f := func(w http.ResponseWriter, r *http.Request) {
+		upstreamCalls.Add(1)
+		if r.Header.Get("Range") != "" {
+			upstreamSawRange.Store(true)
+		}
+		w.Header().Set("Content-Type", "application/octet-stream")
+		_, _ = w.Write(body)
+	}
+	sc, _ := newTestCacheWithFakeUpstream(t, f, "1MB", "0")
+	srv := newCacheServer(t, sc)
+	c := &http.Client{Timeout: 5 * time.Second}
+
+	// Range GET on a cold key.
+	req, err := http.NewRequest("GET", srv.URL+"/depot/rangetest/chunk2", nil)
+	if err != nil {
+		t.Fatalf("NewRequest: %v", err)
+	}
+	req.Header.Set("User-Agent", "Valve/Steam HTTP Client 1.0")
+	req.Header.Set("Range", "bytes=0-3")
+	resp, err := c.Do(req)
+	if err != nil {
+		t.Fatalf("range miss GET: %v", err)
+	}
+	data, err := io.ReadAll(resp.Body)
+	_ = resp.Body.Close()
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	if resp.StatusCode != http.StatusPartialContent {
+		t.Fatalf("range miss GET: expected 206, got %d", resp.StatusCode)
+	}
+	if string(data) != "0123" {
+		t.Errorf("range miss GET: expected body %q, got %q", "0123", data)
+	}
+	if got := resp.Header.Get("X-LanCache-Status"); got != "MISS" {
+		t.Errorf("range miss GET: expected X-LanCache-Status MISS, got %q", got)
+	}
+	if got := resp.Header.Get("Content-Range"); got != "bytes 0-3/16" {
+		t.Errorf("range miss GET: expected Content-Range bytes 0-3/16, got %q", got)
+	}
+	if got := resp.Header.Get("Accept-Ranges"); got != "bytes" {
+		t.Errorf("range miss GET: expected Accept-Ranges bytes, got %q", got)
+	}
+
+	// Range must have been stripped for the upstream fetch (full file cached).
+	if upstreamSawRange.Load() {
+		t.Error("upstream received a Range header; Range must be stripped so the full object is cached")
+	}
+	if got := upstreamCalls.Load(); got != 1 {
+		t.Errorf("upstream hit %d times, want exactly 1", got)
+	}
+
+	// range_upstream incremented, range_cache untouched.
+	stats := sc.GetMetrics()
+	if stats.RangeUpstream != 1 {
+		t.Errorf("expected RangeUpstream == 1 after range MISS, got %d", stats.RangeUpstream)
+	}
+	if stats.RangeCache != 0 {
+		t.Errorf("expected RangeCache == 0 (no range hit yet), got %d", stats.RangeCache)
+	}
+	if stats.CacheMisses < 1 {
+		t.Errorf("expected CacheMisses >= 1, got %d", stats.CacheMisses)
+	}
+	// BytesServed for the range miss: only the 4 range bytes, not the 16-byte fetch.
+	if stats.TotalBytesServed != 4 {
+		t.Errorf("expected TotalBytesServed == 4 (range bytes only), got %d", stats.TotalBytesServed)
+	}
+
+	// The FULL object must have been cached: a subsequent full GET is a HIT with the
+	// complete 16-byte body.
+	req3, err := http.NewRequest("GET", srv.URL+"/depot/rangetest/chunk2", nil)
+	if err != nil {
+		t.Fatalf("NewRequest: %v", err)
+	}
+	req3.Header.Set("User-Agent", "Valve/Steam HTTP Client 1.0")
+	resp3, err := c.Do(req3)
+	if err != nil {
+		t.Fatalf("full GET after range miss: %v", err)
+	}
+	fullData, err := io.ReadAll(resp3.Body)
+	_ = resp3.Body.Close()
+	if err != nil {
+		t.Fatalf("read full body: %v", err)
+	}
+	if resp3.StatusCode != http.StatusOK {
+		t.Fatalf("full GET after range miss: expected 200, got %d", resp3.StatusCode)
+	}
+	if got := resp3.Header.Get("X-LanCache-Status"); got != "HIT" {
+		t.Errorf("full GET after range miss: expected X-LanCache-Status HIT, got %q", got)
+	}
+	if len(fullData) != len(body) || string(fullData) != string(body) {
+		t.Errorf("full GET after range miss: expected full %d-byte body, got %d bytes", len(body), len(fullData))
+	}
+	if got := upstreamCalls.Load(); got != 1 {
+		t.Errorf("upstream hit %d times after HIT, want still 1", got)
+	}
+}
+
+// TestRangeMissInvalidRange416 verifies that an unsatisfiable Range on a cold key
+// fetches upstream, returns 416 (as on the HIT path), and does not count range_upstream.
+func TestRangeMissInvalidRange416(t *testing.T) {
+	body := []byte("0123456789abcdef") // 16 bytes
+	var upstreamCalls atomic.Int64
+	f := func(w http.ResponseWriter, r *http.Request) {
+		upstreamCalls.Add(1)
+		_, _ = w.Write(body)
+	}
+	sc, _ := newTestCacheWithFakeUpstream(t, f, "1MB", "0")
+	srv := newCacheServer(t, sc)
+	c := &http.Client{Timeout: 5 * time.Second}
+
+	req, err := http.NewRequest("GET", srv.URL+"/depot/rangetest/chunk3", nil)
+	if err != nil {
+		t.Fatalf("NewRequest: %v", err)
+	}
+	req.Header.Set("User-Agent", "Valve/Steam HTTP Client 1.0")
+	req.Header.Set("Range", "bytes=100-200")
+	resp, err := c.Do(req)
+	if err != nil {
+		t.Fatalf("invalid range GET: %v", err)
+	}
+	data, err := io.ReadAll(resp.Body)
+	_ = resp.Body.Close()
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	if resp.StatusCode != http.StatusRequestedRangeNotSatisfiable {
+		t.Fatalf("invalid range GET: expected 416, got %d", resp.StatusCode)
+	}
+	if len(data) != 0 {
+		t.Errorf("invalid range GET: expected empty body, got %d bytes", len(data))
+	}
+	if got := resp.Header.Get("Content-Range"); got != "bytes */16" {
+		t.Errorf("invalid range GET: expected Content-Range bytes */16, got %q", got)
+	}
+	if got := upstreamCalls.Load(); got != 1 {
+		t.Errorf("upstream hit %d times, want exactly 1 (fetch happens, then 416 to client)", got)
+	}
+	stats := sc.GetMetrics()
+	if stats.RangeUpstream != 0 {
+		t.Errorf("expected RangeUpstream == 0 for unsatisfiable range, got %d", stats.RangeUpstream)
+	}
+	if stats.RangeCache != 0 {
+		t.Errorf("expected RangeCache == 0, got %d", stats.RangeCache)
+	}
+}
+
+// TestRangeMetricsWriteText verifies /metrics emits the range_cache and range_upstream
+// lines with the expected values after a range HIT and a range MISS.
+func TestRangeMetricsWriteText(t *testing.T) {
+	body := []byte("0123456789abcdef")
+	f := func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write(body)
+	}
+	sc, _ := newTestCacheWithFakeUpstream(t, f, "1MB", "0")
+	srv := newCacheServer(t, sc)
+	c := &http.Client{Timeout: 5 * time.Second}
+
+	get := func(path, rangeHeader string) int {
+		t.Helper()
+		req, err := http.NewRequest("GET", srv.URL+path, nil)
+		if err != nil {
+			t.Fatalf("NewRequest: %v", err)
+		}
+		req.Header.Set("User-Agent", "Valve/Steam HTTP Client 1.0")
+		if rangeHeader != "" {
+			req.Header.Set("Range", rangeHeader)
+		}
+		resp, err := c.Do(req)
+		if err != nil {
+			t.Fatalf("GET %s: %v", path, err)
+		}
+		_, _ = io.Copy(io.Discard, resp.Body)
+		_ = resp.Body.Close()
+		return resp.StatusCode
+	}
+
+	// Range MISS on cold key -> range_upstream; warm it; range HIT -> range_cache.
+	if code := get("/depot/rangetest/wt/1", "bytes=0-3"); code != http.StatusPartialContent {
+		t.Fatalf("range miss: expected 206, got %d", code)
+	}
+	if code := get("/depot/rangetest/wt/2", ""); code != http.StatusOK {
+		t.Fatalf("warm miss: expected 200, got %d", code)
+	}
+	if code := get("/depot/rangetest/wt/2", "bytes=8-11"); code != http.StatusPartialContent {
+		t.Fatalf("range hit: expected 206, got %d", code)
+	}
+
+	req, err := http.NewRequest("GET", srv.URL+"/metrics", nil)
+	if err != nil {
+		t.Fatalf("NewRequest: %v", err)
+	}
+	resp, err := c.Do(req)
+	if err != nil {
+		t.Fatalf("GET /metrics: %v", err)
+	}
+	out, err := io.ReadAll(resp.Body)
+	_ = resp.Body.Close()
+	if err != nil {
+		t.Fatalf("read /metrics: %v", err)
+	}
+	text := string(out)
+	if !strings.Contains(text, "range_cache 1\n") {
+		t.Errorf("/metrics missing 'range_cache 1' line:\n%s", text)
+	}
+	if !strings.Contains(text, "range_upstream 1\n") {
+		t.Errorf("/metrics missing 'range_upstream 1' line:\n%s", text)
+	}
+}
+
+// TestStreamCachedResponseRange206 is a focused unit test for streamCachedResponse:
+// valid Range yields 206 with the exact slice + metrics; invalid Range yields 416
+// with no range metrics.
+func TestStreamCachedResponseRange206(t *testing.T) {
+	body := []byte("0123456789abcdef") // 16 bytes
+	raw := append([]byte("HTTP/1.1 200 OK\r\nContent-Type: application/octet-stream\r\n\r\n"), body...)
+	serialized, err := serializeRawResponse(raw)
+	if err != nil {
+		t.Fatalf("serialize cache file: %v", err)
+	}
+	cf, err := deserializeCacheFile(serialized)
+	if err != nil {
+		t.Fatalf("build cache file: %v", err)
+	}
+
+	sc, _ := newTestCacheWithFakeUpstream(t, func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte("x"))
+	}, "1MB", "0")
+	sc.ResetMetrics()
+
+	// Valid range -> 206 + slice + metrics.
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest("GET", "/depot/rangetest/chunk", nil)
+	req.Header.Set("Range", "bytes=4-7")
+	sc.streamCachedResponse(rec, req, cf, "steam/testkey", "127.0.0.1", time.Now())
+
+	if rec.Code != http.StatusPartialContent {
+		t.Fatalf("expected 206, got %d", rec.Code)
+	}
+	if rec.Body.String() != "4567" {
+		t.Errorf("expected body %q, got %q", "4567", rec.Body.String())
+	}
+	if got := rec.Header().Get("Content-Range"); got != "bytes 4-7/16" {
+		t.Errorf("expected Content-Range bytes 4-7/16, got %q", got)
+	}
+	if got := rec.Header().Get("X-LanCache-Status"); got != "HIT" {
+		t.Errorf("expected X-LanCache-Status HIT, got %q", got)
+	}
+	stats := sc.GetMetrics()
+	if stats.RangeCache != 1 {
+		t.Errorf("expected RangeCache == 1, got %d", stats.RangeCache)
+	}
+	if stats.TotalBytesServed != 4 {
+		t.Errorf("expected TotalBytesServed == 4 (range bytes), got %d", stats.TotalBytesServed)
+	}
+	if stats.TotalBytesSaved != 4 {
+		t.Errorf("expected TotalBytesSaved == 4 (range bytes), got %d", stats.TotalBytesSaved)
+	}
+
+	// Invalid range -> 416, no range metrics, no bytes served.
+	rec2 := httptest.NewRecorder()
+	req2 := httptest.NewRequest("GET", "/depot/rangetest/chunk", nil)
+	req2.Header.Set("Range", "bytes=100-200")
+	sc.streamCachedResponse(rec2, req2, cf, "steam/testkey", "127.0.0.1", time.Now())
+
+	if rec2.Code != http.StatusRequestedRangeNotSatisfiable {
+		t.Fatalf("expected 416, got %d", rec2.Code)
+	}
+	if got := rec2.Header().Get("Content-Range"); got != "bytes */16" {
+		t.Errorf("expected Content-Range bytes */16, got %q", got)
+	}
+	stats = sc.GetMetrics()
+	if stats.RangeCache != 1 {
+		t.Errorf("RangeCache must stay 1 after unsatisfiable range, got %d", stats.RangeCache)
+	}
+	if stats.TotalBytesServed != 4 {
+		t.Errorf("TotalBytesServed must stay 4 after 416, got %d", stats.TotalBytesServed)
+	}
+}
@@ -200,23 +200,33 @@ func New(address string, memorySize string, diskSize string, diskPath, upstream,

 	if disksize == 0 && memorysize != 0 {
 		// memory only mode - no disk
+		sc.metrics.SetDiskTierReady(1) // no disk — N/A / not pending
 		c.SetSlow(mgc)
 	} else if disksize != 0 && memorysize == 0 {
 		// disk only mode: delay attach until disk ready (pure-proxy during scan; Create returns ErrNotFound until slow tier Set)
+		sc.metrics.SetDiskTierReady(0)
+		logger.Logger.Info().Msg("Disk slow tier attach pending; Size barrier in progress")
 		sc.wg.Add(1)
 		go func() {
 			defer sc.wg.Done()
+			t0 := time.Now()
 			_ = d.Size() // block on barrier per design (all Size callers during window do this; documented)
 			select {
 			case <-sc.shutdownCh:
 				return // Shutdown raced; do not attach or SetSlow after stop
 			default:
 				c.SetSlow(dgc)
+				sc.metrics.SetDiskTierReady(1)
+				logger.Logger.Info().
+					Dur("attach_delay", time.Since(t0)).
+					Msg("Disk slow tier attached (disk-only mode); prior traffic had no disk tier")
 			}
 		}()
 	} else if disksize != 0 && memorysize != 0 {
 		// memory and disk mode: fast mem immediate, disk delayed (mem-only during scan)
 		c.SetFast(mgc)
+		sc.metrics.SetDiskTierReady(0)
+		logger.Logger.Info().Msg("Disk slow tier attach pending; Size barrier in progress")
 		sc.wg.Add(1)
 		go func() {
 			defer sc.wg.Done()
@@ -227,6 +237,7 @@ func New(address string, memorySize string, diskSize string, diskPath, upstream,
 				return
 			default:
 				c.SetSlow(dgc)
+				sc.metrics.SetDiskTierReady(1)
 				logger.Logger.Info().
 					Dur("attach_delay", time.Since(t0)).
 					Msg("Disk slow tier attached (mixed mode); prior traffic was memory-only")
@@ -326,15 +337,13 @@ func (sc *SteamCache) Shutdown() {

 // GetMetrics returns current metrics
 func (sc *SteamCache) GetMetrics() *metrics.Stats {
-	// Update cache sizes
 	if sc.memory != nil {
 		sc.metrics.SetMemoryCacheSize(sc.memory.Size())
 	}
-	if sc.disk != nil {
-		// Note: blocks on initDone (post-eviction state) for accurate post-attach size during long disk init window.
+	// Skip disk.Size() while attach pending — Size() blocks on initDone and would hang /metrics.
+	if sc.disk != nil && sc.metrics.GetDiskTierReady() == 1 {
 		sc.metrics.SetDiskCacheSize(sc.disk.Size())
 	}
-
 	return sc.metrics.GetStats()
 }

@@ -1057,6 +1057,12 @@ func TestDiskOnlyDelayedAttach(t *testing.T) {
 		t.Errorf("during init window, expected ErrNotFound from disk-only tiered Create (no slow), got %v", err)
 	}

+	// Disk tier is pending while the attach goroutine is in the Size barrier.
+	// GetMetrics must return quickly (it skips disk.Size() while pending) and report 0.
+	if got := sc.GetMetrics().DiskTierReady; got != 0 {
+		t.Errorf("during pending attach, DiskTierReady=%d, want 0", got)
+	}
+
 	// Wait the barrier (exercises the attach go's Size wait)
 	_ = sc.disk.Size()

@@ -1083,6 +1089,94 @@ func TestDiskOnlyDelayedAttach(t *testing.T) {
 	} else {
 		rc.Close()
 	}
+
+	// After attach, the disk tier must be marked ready (1)
+	if got := sc.GetMetrics().DiskTierReady; got != 1 {
+		t.Errorf("post-attach DiskTierReady=%d, want 1 (ready)", got)
+	}
+
+	// /metrics text output includes the disk_tier_ready line
+	rec := httptest.NewRecorder()
+	metrics.WriteText(rec, sc.GetMetrics())
+	if !bytes.Contains(rec.Body.Bytes(), []byte("disk_tier_ready 1")) {
+		t.Errorf("WriteText output missing \"disk_tier_ready 1\": %q", rec.Body.String())
+	}
+	if !bytes.Contains(rec.Body.Bytes(), []byte("capacity_pressure_events")) {
+		t.Errorf("WriteText output missing capacity_pressure_events: %q", rec.Body.String())
+	}
+}
+
+// TestDiskTierSignalMemoryOnly covers memory-only mode: DiskTierReady=1 (N/A, not
+// waiting on disk attach) and heartbeat header X-SteamCache-Disk-Tier: disabled.
+func TestDiskTierSignalMemoryOnly(t *testing.T) {
+	sc, err := New("127.0.0.1:0", "1MB", "0", t.TempDir(), "", "lru", "lru", 10, 5, "0", nil)
+	if err != nil {
+		t.Fatalf("New memory-only: %v", err)
+	}
+	t.Cleanup(func() { sc.Shutdown() })
+
+	if got := sc.GetMetrics().DiskTierReady; got != 1 {
+		t.Errorf("DiskTierReady=%d, want 1 (memory-only = N/A/not pending)", got)
+	}
+
+	req := httptest.NewRequest("GET", "/lancache-heartbeat", nil)
+	rec := httptest.NewRecorder()
+	sc.ServeHTTP(rec, req)
+	if rec.Code != http.StatusNoContent {
+		t.Errorf("heartbeat status=%d, want 204", rec.Code)
+	}
+	if got := rec.Header().Get("X-SteamCache-Disk-Tier"); got != "disabled" {
+		t.Errorf("X-SteamCache-Disk-Tier=%q, want disabled", got)
+	}
+	if got := rec.Header().Get("X-LanCache-Processed-By"); got != "SteamCache2" {
+		t.Errorf("X-LanCache-Processed-By=%q, want SteamCache2", got)
+	}
+}
+
+// TestDiskTierSignalMixedPendingReady covers mixed mode: DiskTierReady=0 (header
+// pending) while the disk attach is in the Size barrier, then DiskTierReady=1
+// (header ready) after the barrier opens and the attach goroutine sets SetSlow.
+func TestDiskTierSignalMixedPendingReady(t *testing.T) {
+	td := t.TempDir()
+	diskPath := filepath.Join(td, "disk")
+	if err := os.MkdirAll(diskPath, 0755); err != nil {
+		t.Fatal(err)
+	}
+	sc, err := New("127.0.0.1:0", "1MB", "10MB", diskPath, "", "lru", "lru", 10, 1, "0", nil)
+	if err != nil {
+		t.Fatalf("New mixed: %v", err)
+	}
+	t.Cleanup(func() { sc.Shutdown() })
+
+	// Immediately in the pending window
+	if got := sc.GetMetrics().DiskTierReady; got != 0 {
+		t.Errorf("immediate DiskTierReady=%d, want 0 (pending)", got)
+	}
+	req := httptest.NewRequest("GET", "/lancache-heartbeat", nil)
+	rec := httptest.NewRecorder()
+	sc.ServeHTTP(rec, req)
+	if got := rec.Header().Get("X-SteamCache-Disk-Tier"); got != "pending" {
+		t.Errorf("heartbeat header=%q, want pending", got)
+	}
+
+	// Wait the barrier, then retry until the attach goroutine flips the flag
+	_ = sc.disk.Size()
+	deadline := time.Now().Add(2 * time.Second)
+	for time.Now().Before(deadline) {
+		if sc.GetMetrics().DiskTierReady == 1 {
+			break
+		}
+		time.Sleep(1 * time.Millisecond)
+	}
+	if got := sc.GetMetrics().DiskTierReady; got != 1 {
+		t.Fatalf("DiskTierReady=%d after barrier, want 1 (ready)", got)
+	}
+
+	rec2 := httptest.NewRecorder()
+	sc.ServeHTTP(rec2, httptest.NewRequest("GET", "/lancache-heartbeat", nil))
+	if got := rec2.Header().Get("X-SteamCache-Disk-Tier"); got != "ready" {
+		t.Errorf("heartbeat header=%q, want ready", got)
+	}
 }

 // --- Phase 2: narrow black-box tests for the new wrapper types ---
@@ -403,11 +403,13 @@ func (d *DiskFS) Create(key string, size int64) (io.WriteCloser, error) {
 	dir := filepath.Dir(path)
 	// 0700 (not 0755): per-shard cache dirs hold untrusted CDN content; restrict to owner only (G301 addressed).
 	if err := os.MkdirAll(dir, 0700); err != nil {
+		d.recordIfNoSpace(err)
 		return nil, err
 	}

 	file, err := os.Create(path) // #nosec G304 -- path built by pathForKey from sanitized (Clean, no ..) hash-derived key under trusted disk.root; no untrusted file inclusion
 	if err != nil {
+		d.recordIfNoSpace(err)
 		return nil, err
 	}

@@ -438,7 +440,19 @@ type diskWriteCloser struct {
 }

 func (dwc *diskWriteCloser) Write(p []byte) (n int, err error) {
-	return dwc.file.Write(p)
+	n, err = dwc.file.Write(p)
+	if err != nil {
+		dwc.disk.recordIfNoSpace(err)
+	}
+	return n, err
+}
+
+// recordIfNoSpace increments capacity_pressure_events and logs when err is ENOSPC (or Windows disk-full).
+func (d *DiskFS) recordIfNoSpace(err error) {
+	if !isNoSpaceError(err) {
+		return
+	}
+	metrics.NoteNoSpace(d.metrics, err)
 }

 func (dwc *diskWriteCloser) Close() error {
@@ -722,9 +736,7 @@ func (d *DiskFS) EvictLRU(bytesNeeded uint) uint {
 	}
 	d.mu.Unlock()

-	if d.metrics != nil && evicted > 0 {
-		d.metrics.IncrementEvictions()
-	}
+	metrics.NoteSoftEviction(d.metrics, "disk", evicted)
 	return evicted
 }

@@ -775,9 +787,7 @@ func (d *DiskFS) EvictBySize(bytesNeeded uint, ascending bool) uint {
 	}
 	d.mu.Unlock()

-	if d.metrics != nil && evicted > 0 {
-		d.metrics.IncrementEvictions()
-	}
+	metrics.NoteSoftEviction(d.metrics, "disk", evicted)
 	return evicted
 }

@@ -826,9 +836,7 @@ func (d *DiskFS) EvictFIFO(bytesNeeded uint) uint {
 	}
 	d.mu.Unlock()

-	if d.metrics != nil && evicted > 0 {
-		d.metrics.IncrementEvictions()
-	}
+	metrics.NoteSoftEviction(d.metrics, "disk", evicted)
 	return evicted
 }

@@ -882,9 +890,7 @@ func (d *DiskFS) EvictLFU(bytesNeeded uint) uint {
 	}
 	d.mu.Unlock()

-	if d.metrics != nil && evicted > 0 {
-		d.metrics.IncrementEvictions()
-	}
+	metrics.NoteSoftEviction(d.metrics, "disk", evicted)
 	return evicted
 }

@@ -939,8 +945,6 @@ func (d *DiskFS) EvictHybrid(bytesNeeded uint) uint {
 	}
 	d.mu.Unlock()

-	if d.metrics != nil && evicted > 0 {
-		d.metrics.IncrementEvictions()
-	}
+	metrics.NoteSoftEviction(d.metrics, "disk", evicted)
 	return evicted
 }
@@ -11,6 +11,7 @@ import (
 	"testing"
 	"time"

+	"s1d3sw1ped/steamcache2/steamcache/metrics"
 	"s1d3sw1ped/steamcache2/vfs"
 )

@@ -122,6 +123,42 @@ func TestDiskFS_InitPopulatesIndexOnRestart(t *testing.T) {
 	}
 }

+func TestDiskFS_CapacityPressureOnEvict(t *testing.T) {
+	t.Parallel()
+	td := t.TempDir()
+	d, err := New(td, 500, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_ = d.Size()
+	met := metrics.NewMetrics()
+	d.SetMetrics(met)
+	for i := 0; i < 3; i++ {
+		k := "f" + string(rune('0'+i))
+		w, cerr := d.Create(k, 200)
+		if cerr != nil {
+			t.Fatal(cerr)
+		}
+		if _, werr := w.Write(make([]byte, 200)); werr != nil {
+			t.Fatal(werr)
+		}
+		if cerr := w.Close(); cerr != nil {
+			t.Fatal(cerr)
+		}
+	}
+	evicted := d.EvictLRU(100)
+	if evicted == 0 {
+		t.Fatalf("expected eviction under cap, size=%d cap=%d", d.Size(), d.Capacity())
+	}
+	st := met.GetStats()
+	if st.Evictions == 0 {
+		t.Error("evictions counter not incremented under disk cap pressure")
+	}
+	if st.CapacityPressureEvents == 0 {
+		t.Error("capacity_pressure_events not incremented under disk cap pressure")
+	}
+}
+
 func TestDiskFS_EvictAndLazyStat(t *testing.T) {
 	t.Parallel()
 	td := t.TempDir()
@@ -138,10 +175,21 @@ func TestDiskFS_EvictAndLazyStat(t *testing.T) {
 		w.Write(make([]byte, 120))
 		w.Close()
 	}
+	met := metrics.NewMetrics()
+	d.SetMetrics(met)
 	ev := d.EvictLRU(200)
 	if ev == 0 {
 		t.Log("no evict (size calc async or snapshot tolerance?)")
 	}
+	if ev > 0 {
+		st := met.GetStats()
+		if st.Evictions == 0 {
+			t.Error("evictions counter not incremented after disk EvictLRU freed bytes")
+		}
+		if st.CapacityPressureEvents == 0 {
+			t.Error("capacity_pressure_events not incremented after disk EvictLRU freed bytes")
+		}
+	}
 	// Explicit post-evict consistency checks: for any key no longer visible via Stat, its on-disk
 	// file must be absent (verifies coordinated unlink + no resurrection via lazy discovery).
 	// Keys still present after this small evict are allowed (accounting tolerance in raw DiskFS).
@@ -0,0 +1,14 @@
+//go:build !windows
+
+package disk
+
+import (
+	"errors"
+
+	"golang.org/x/sys/unix"
+)
+
+// isNoSpaceError reports whether err is ENOSPC (or wraps it).
+func isNoSpaceError(err error) bool {
+	return err != nil && errors.Is(err, unix.ENOSPC)
+}
@@ -0,0 +1,58 @@
+//go:build !windows
+
+package disk
+
+import (
+	"io"
+	"os"
+	"testing"
+
+	"golang.org/x/sys/unix"
+
+	"s1d3sw1ped/steamcache2/steamcache/metrics"
+)
+
+func TestIsNoSpaceError(t *testing.T) {
+	t.Parallel()
+	if isNoSpaceError(nil) {
+		t.Error("nil must not be ENOSPC")
+	}
+	if isNoSpaceError(io.EOF) {
+		t.Error("EOF must not be ENOSPC")
+	}
+	if !isNoSpaceError(unix.ENOSPC) {
+		t.Error("unix.ENOSPC should match")
+	}
+	wrapped := &os.PathError{Op: "write", Path: "x", Err: unix.ENOSPC}
+	if !isNoSpaceError(wrapped) {
+		t.Error("PathError wrapping ENOSPC should match")
+	}
+}
+
+func TestDiskFS_ENOSPCCapacityPressure(t *testing.T) {
+	t.Parallel()
+	d, err := New(t.TempDir(), 1024, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	met := metrics.NewMetrics()
+	d.SetMetrics(met)
+
+	d.recordIfNoSpace(io.EOF)
+	if got := met.GetStats().CapacityPressureEvents; got != 0 {
+		t.Fatalf("non-ENOSPC counted: %d", got)
+	}
+
+	d.recordIfNoSpace(unix.ENOSPC)
+	if got := met.GetStats().CapacityPressureEvents; got != 1 {
+		t.Fatalf("unix.ENOSPC: CapacityPressureEvents=%d, want 1", got)
+	}
+	if got := met.GetStats().Evictions; got != 0 {
+		t.Fatalf("ENOSPC must not increment evictions, got %d", got)
+	}
+
+	d.recordIfNoSpace(&os.PathError{Op: "write", Path: "p", Err: unix.ENOSPC})
+	if got := met.GetStats().CapacityPressureEvents; got != 2 {
+		t.Fatalf("wrapped ENOSPC: CapacityPressureEvents=%d, want 2", got)
+	}
+}
@@ -0,0 +1,17 @@
+//go:build windows
+
+package disk
+
+import (
+	"errors"
+
+	"golang.org/x/sys/windows"
+)
+
+// isNoSpaceError reports whether err is a Windows disk-full equivalent of ENOSPC.
+func isNoSpaceError(err error) bool {
+	if err == nil {
+		return false
+	}
+	return errors.Is(err, windows.ERROR_DISK_FULL) || errors.Is(err, windows.ERROR_HANDLE_DISK_FULL)
+}
@@ -0,0 +1,56 @@
+//go:build windows
+
+package disk
+
+import (
+	"io"
+	"os"
+	"testing"
+
+	"golang.org/x/sys/windows"
+
+	"s1d3sw1ped/steamcache2/steamcache/metrics"
+)
+
+func TestIsNoSpaceError(t *testing.T) {
+	t.Parallel()
+	if isNoSpaceError(nil) {
+		t.Error("nil must not be disk-full")
+	}
+	if isNoSpaceError(io.EOF) {
+		t.Error("EOF must not be disk-full")
+	}
+	if !isNoSpaceError(windows.ERROR_DISK_FULL) {
+		t.Error("ERROR_DISK_FULL should match")
+	}
+	if !isNoSpaceError(windows.ERROR_HANDLE_DISK_FULL) {
+		t.Error("ERROR_HANDLE_DISK_FULL should match")
+	}
+	wrapped := &os.PathError{Op: "write", Path: "x", Err: windows.ERROR_DISK_FULL}
+	if !isNoSpaceError(wrapped) {
+		t.Error("PathError wrapping ERROR_DISK_FULL should match")
+	}
+}
+
+func TestDiskFS_ENOSPCCapacityPressure(t *testing.T) {
+	t.Parallel()
+	d, err := New(t.TempDir(), 1024, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	met := metrics.NewMetrics()
+	d.SetMetrics(met)
+
+	d.recordIfNoSpace(io.EOF)
+	if got := met.GetStats().CapacityPressureEvents; got != 0 {
+		t.Fatalf("non-ENOSPC counted: %d", got)
+	}
+
+	d.recordIfNoSpace(windows.ERROR_DISK_FULL)
+	if got := met.GetStats().CapacityPressureEvents; got != 1 {
+		t.Fatalf("ERROR_DISK_FULL: CapacityPressureEvents=%d, want 1", got)
+	}
+	if got := met.GetStats().Evictions; got != 0 {
+		t.Fatalf("disk-full must not increment evictions, got %d", got)
+	}
+}
@@ -358,9 +358,7 @@ func (m *MemoryFS) EvictLRU(bytesNeeded uint) uint {
 	}
 	m.mu.Unlock()

-	if m.metrics != nil && evicted > 0 {
-		m.metrics.IncrementEvictions()
-	}
+	metrics.NoteSoftEviction(m.metrics, "memory", evicted)
 	return evicted
 }

@@ -413,9 +411,7 @@ func (m *MemoryFS) EvictBySize(bytesNeeded uint, ascending bool) uint {
 	}
 	m.mu.Unlock()

-	if m.metrics != nil && evicted > 0 {
-		m.metrics.IncrementEvictions()
-	}
+	metrics.NoteSoftEviction(m.metrics, "memory", evicted)
 	return evicted
 }

@@ -464,9 +460,7 @@ func (m *MemoryFS) EvictFIFO(bytesNeeded uint) uint {
 	}
 	m.mu.Unlock()

-	if m.metrics != nil && evicted > 0 {
-		m.metrics.IncrementEvictions()
-	}
+	metrics.NoteSoftEviction(m.metrics, "memory", evicted)
 	return evicted
 }

@@ -520,9 +514,7 @@ func (m *MemoryFS) EvictLFU(bytesNeeded uint) uint {
 	}
 	m.mu.Unlock()

-	if m.metrics != nil && evicted > 0 {
-		m.metrics.IncrementEvictions()
-	}
+	metrics.NoteSoftEviction(m.metrics, "memory", evicted)
 	return evicted
 }

@@ -578,8 +570,6 @@ func (m *MemoryFS) EvictHybrid(bytesNeeded uint) uint {
 	}
 	m.mu.Unlock()

-	if m.metrics != nil && evicted > 0 {
-		m.metrics.IncrementEvictions()
-	}
+	metrics.NoteSoftEviction(m.metrics, "memory", evicted)
 	return evicted
 }
@@ -8,6 +8,8 @@ import (
 	"sync/atomic"
 	"testing"
 	"time"
+
+	"s1d3sw1ped/steamcache2/steamcache/metrics"
 )

 func TestMemoryFS_Basic(t *testing.T) {
@@ -60,6 +62,8 @@ func TestMemoryFS_EvictUnderPressure(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
+	met := metrics.NewMetrics()
+	m.SetMetrics(met)
 	// create 3x200 = 600 >500, should trigger internal? but direct evict call
 	for i := 0; i < 3; i++ {
 		w, _ := m.Create("f"+string(rune('0'+i)), 200)
@@ -71,6 +75,13 @@ func TestMemoryFS_EvictUnderPressure(t *testing.T) {
 	if evicted == 0 || m.Size() > 500 {
 		t.Errorf("evict failed: evicted=%d size=%d", evicted, m.Size())
 	}
+	st := met.GetStats()
+	if st.Evictions == 0 {
+		t.Error("evictions counter not incremented under memory cap pressure")
+	}
+	if st.CapacityPressureEvents == 0 {
+		t.Error("capacity_pressure_events not incremented under memory cap pressure")
+	}
 }

 func TestMemoryFS_SizeNeverExceedsAfterEvict(t *testing.T) {
Author	SHA1	Message	Date
ash	d7af699e84	ops: Signal disk-full and eviction capacity pressure CI / vulncheck (pull_request) Successful in 14s Details CI / check-and-test (pull_request) Failing after 39s Details When the disk (or memory) tier is at cap or the volume returns ENOSPC, ops currently look like random misses with no clear "we are dropping data." Count those events as capacity_pressure_events on /metrics and log tier plus reason so operators can tell capacity pressure from a cold cache, without changing the existing evictions counter. Link: #36	2026-09-07 19:23:55 +00:00
linus	8cebc1f96c	ops: Signal disk-tier attach pending vs ready (#45 ) CI / vulncheck (push) Successful in 15s Details CI / check-and-test (push) Successful in 41s Details Release Tag / release (push) Successful in 15s Details disk_tier_ready + X-SteamCache-Disk-Tier. Closes #33.	2026-09-07 12:02:10 -05:00
pike	12ea3ee4f6	ops: Signal disk-tier attach pending vs ready CI / vulncheck (pull_request) Successful in 14s Details CI / check-and-test (pull_request) Successful in 40s Details Large disk caches can look memory-only/broken during async DiskFS attach. Expose disk_tier_ready in /metrics, pending/ready logs for disk-only and mixed modes, and X-SteamCache-Disk-Tier on /lancache-heartbeat. GetMetrics skips blocking disk.Size() while attach is pending so /metrics stays usable. Closes #33	2026-09-07 16:58:13 +00:00
linus	a500f51f17	cache: Serve Range GET from disk when present (#44 ) CI / vulncheck (push) Successful in 14s Details CI / check-and-test (push) Successful in 41s Details Range HIT/MISS as 206; range_cache/range_upstream metrics. Closes #38.	2026-09-07 11:37:06 -05:00
moss	ac2d36f1ad	cache: Serve Range GET from disk when present CI / vulncheck (pull_request) Successful in 15s Details CI / check-and-test (pull_request) Successful in 41s Details Steam clients lean on Range requests. Hit/miss looked fine while downloads still felt cold when a Range miss returned the full upstream body as 200. Add range_cache / range_upstream metrics. HIT path already sliced 206 from the cached full object; count range_cache there. On MISS, keep stripping Range for the upstream fetch (full object still cached) but serve the client's requested slice as 206 and count range_upstream. Tests in steamcache/range_test.go cover Range HIT (local, no upstream), Range MISS (206 + full object cached), and /metrics emission.	2026-09-07 16:32:36 +00:00
linus	c43bfba568	Merge pull request 'docs: Real DNS + empty upstream Quick Start' (#43 ) from docs/quick-start-real-dns into main docs: Real DNS + empty upstream Quick Start Fixes #32	2026-09-07 10:00:58 -05:00
eva	3411defd51	docs: Real DNS + empty upstream Quick Start CI / vulncheck (pull_request) Successful in 15s Details CI / check-and-test (pull_request) Successful in 40s Details	2026-09-07 14:58:06 +00:00