v0.25.0

docs/CACHE_DIAGNOSTICS.md

@@ -1,4 +1,4 @@
-# Cache diagnostics and behavior in 0.22.3
+# Cache diagnostics and behavior
 
 This describes implemented source, not a verified Rust runtime. See
 [TEST_REPORT.md](TEST_REPORT.md).
@@ -158,6 +158,17 @@ This explains why, for example, a process RSS around 630 MiB can coexist with on
 
 The existing Linux/glibc allocator-release path remains in place: large cache demotion/purge paths call `malloc_trim(0)` through `release_allocator_memory()`. Since 0.24.5, HOT allocation, active fills and bodies moving to/from COLD are explicitly budgeted. COLD queue admission is byte-bounded as well as count-bounded. RSS is still a process-wide view containing the same cache memory plus TLS/QUIC/Hyper/Tokio, stacks and allocator retention, so cache gauges must not be added to RSS. Long-running acceptance should verify that HOT stays within `hot_limit_bytes`, transient stays within `transient_limit_bytes`, demotion drains transient bytes, and process RSS reaches a practical plateau under representative traffic.
 
+### Sustained traffic, vhost saves and RSS
+
+A vhost configuration save can make RSS fall abruptly for two independent reasons. First, the current cache compatibility identity includes vhost configuration; when that identity changes, publication performs a cache purge so representations created under the old origin/configuration contract cannot survive incorrectly. Second, publishing the newly compiled routing snapshot retires the previous snapshot and its upstream clients; once outstanding references finish, idle connection-pool state and related buffers can be released. A visible RSS drop after saving a busy vhost is therefore a useful diagnostic clue, but saving/reloading a vhost is not a memory-maintenance requirement.
+
+The 0.25.0 development runtime adds two maintenance mechanisms that do not reload configuration:
+
+- every 60 seconds on Linux/glibc, RustProxy calls `malloc_trim(0)` from a blocking maintenance task; this can return allocator pages that are already free, but cannot and does not evict live Rust objects;
+- HOT cache maintenance trims only least-recently-used entries that have been idle for the configured delay and only while HOT allocation is above the configured target waterline. The pass is bounded by `hot_eviction_max_objects`; recent/active entries are not purged.
+
+Upstream HTTP keep-alive is not reset on a timer. It is already bounded per backend by `max_idle_per_host` and `idle_timeout_seconds`, so forcing periodic client/snapshot replacement would trade memory symptoms for connection churn and lower proxy efficiency. If RSS remains high while HOT/transient usage and connection-pool bounds are stable, the remaining resident pages may still be active runtime/TLS/QUIC/Hyper/Tokio working set rather than reclaimable cache memory.
+
 ## Hot and cold tiers
 
 HOT RAM is bounded by allocated/charged `max_bytes` and `max_entries`; `hot_logical_bytes` separately exposes payload length. Fill and COLD handoff/read memory are bounded by `transient_max_bytes`, and queued demotions also obey `cold_queue_max_bytes`. Optional cold storage demotes LRU
@@ -165,10 +176,11 @@ or sufficiently idle hot objects asynchronously. Cold hits verify the body diges
 promote the object back to RAM. Version 0.11.5 uses cold metadata format 2 to persist
 Vary identity and resident age; old-format metadata is not reused.
 
-Cold is not required for normal hot-cache stability. Disabling cold must not cause hot
-objects to disappear on a timer. With cold disabled, hot objects leave RAM only because
-of expiry, hot capacity/LRU pressure, explicit purge, configuration generation changes,
-or replacement of the same logical representation.
+Cold is not required for normal hot-cache stability. With cold disabled, hot objects leave
+RAM because of expiry, hot capacity/LRU pressure, explicit purge, configuration generation
+changes, replacement of the same logical representation, or the optional HOT auto-trim
+waterline. Auto-trim is not a blind TTL: it acts only when HOT is above its configured target
+and only on entries idle longer than the configured threshold; it can be disabled independently.
 
 ## Cache panel and API