refactor: per-register cache to fix stale data on writes (#8)

* refactor: switch cache to per-register storage

Cache keys now address individual registers/coils instead of
request ranges. This fixes stale data when writes hit registers
that are part of a larger cached read range.

Key changes:
- RegKey(slaveID, fc, addr) for per-register storage
- RangeKey(slaveID, fc, addr, qty) for request coalescing
- GetRange/SetRange/DeleteRange for batch operations
- Rename GetOrFetch to Coalesce (no longer interacts with cache)
- Add keepStale flag to prevent cleanup from removing entries
  needed for stale-serve fallback

* refactor: update proxy for per-register cache

Decompose upstream responses into per-register cache entries and
reassemble from cache on hits. Write invalidation now correctly
removes individual registers in the written range, fixing stale
data when writes overlap with larger cached read ranges.

New helpers:
- decomposeResponse: extract per-register values from Modbus PDU
- assembleResponse: reconstruct Modbus PDU from cached values
- Roundtrip tests for all function codes (registers + coils)
- Tests verifying write invalidation of overlapping reads

* fix: log cache miss for all callers, not just the fetcher

Move the cache miss log before Coalesce so coalesced waiters
also get a log entry. The upstream client already logs request
completion with duration, so fetches vs coalesced waits are
distinguishable.

* fix: address copilot review comments

- Guard GetRange/GetRangeStale against quantity=0 (false cache hit)
- Use shared coilOn/coilOff slices in decomposeResponse to reduce
  per-coil allocations
- Extract cleanupOnce so tests exercise the real keepStale guard
  instead of manually simulating cleanup

* test: cover proxy cache miss and stale fallback

Update README and SPEC for the per-register cache design, then
add proxy-level tests for miss -> fetch -> store -> hit and stale
fallback on upstream errors. Introduce a small upstream client
interface so tests can use a mock upstream without a real Modbus
connection.

* fix: include health check in proxy test client interface

Main added Proxy.Healthy, which delegates to the upstream client. The
local mockable interface needs to include Healthy so PR merge builds
compile against the current base branch.

Author: tma

README.md

@@ -134,10 +134,12 @@ docker run --rm -v $(pwd):/app -w /app golang:1.24 go test ./...
 
 ## Cache Behavior
 
-- **Key format**: `{slave_id}:{function_code}:{start_address}:{quantity}`
-- **Read requests**: Served from cache if available and not expired
-- **Write requests**: Forwarded to upstream (if allowed), exact matching cache entries invalidated
-- **Request coalescing**: Multiple identical requests during a cache miss share a single upstream fetch
+- **Key format**: values are cached per register/coil as `{slave_id}:{function_code}:{address}`
+- **Read requests**: Served from cache only if every register/coil in the requested range is present and not expired
+- **Cache misses**: If any value in the requested range is missing or expired, the full range is fetched from upstream and decomposed into per-register/coil cache entries
+- **Write requests**: Forwarded to upstream (if allowed), then invalidate the written address range so overlapping cached reads cannot return stale values
+- **Request coalescing**: Multiple identical range requests during a cache miss share a single upstream fetch using `{slave_id}:{function_code}:{start_address}:{quantity}` as the coalescing key
+- **Stale fallback**: If enabled, expired entries are retained and can be served when upstream requests fail
 
 ## License
 

SPEC.md

@@ -49,28 +49,36 @@ Many Modbus devices (inverters, meters, battery systems) have limited polling ca
 ### 3. In-Memory Cache
 
 #### Cache Key Structure
+
+Values are cached per register/coil:
+```
+{slave_id}:{function_code}:{address}
+```
+
+Request coalescing still uses the requested range as its key:
 ```
 {slave_id}:{function_code}:{start_address}:{quantity}
 ```
 
 #### Cache Entry
 ```go
 type CacheEntry struct {
-    Data      []byte
+    Data      []byte        // one register (2 bytes) or one coil/input bit (1 byte: 0 or 1)
     Timestamp time.Time
     TTL       time.Duration
 }
 ```
 
 #### Cache Behavior
-- **Read Operations**: Check cache first, return if valid (not expired)
-- **Write Operations**: Always forward to device, invalidate exact matching cache entries (same slave_id, function_code, start_address, quantity)
+- **Read Operations**: Check the per-register/coil cache first. Return from cache only if every value in the requested range is present and not expired.
+- **Cache Misses**: If any value in the requested range is missing or expired, fetch the full requested range from upstream, then decompose the response into per-register/coil cache entries.
+- **Write Operations**: Always forward to the device when writes are allowed, then invalidate each cached register/coil in the written address range. This prevents overlapping cached read ranges from serving stale values after frequent writes.
 - **TTL**: Configurable (default: 10 seconds)
-- **Cleanup**: Time-based expiration (entries removed when TTL expires)
-- **Staleness**: Option to serve stale data on upstream failure (default: off)
+- **Cleanup**: Time-based expiration. Expired entries are removed during cleanup unless stale serving is enabled.
+- **Staleness**: Option to serve stale data on upstream failure (default: off). When enabled, expired entries are retained so they remain available for fallback.
 
 ### Request Coalescing
-- Identical in-flight requests are coalesced (same slave_id, function, address, quantity)
+- Identical in-flight range requests are coalesced (same slave_id, function, address, quantity)
 - Second request arriving while first is pending will wait for and share the first's response
 - Prevents thundering herd on cache miss
 
@@ -144,47 +152,82 @@ type CachingHandler struct {
 
 ```go
 type Cache struct {
-    mu      sync.RWMutex
-    entries map[string]*CacheEntry
-    ttl     time.Duration  // default: 10 * time.Second
+    mu         sync.RWMutex
+    entries    map[string]*CacheEntry
+    defaultTTL time.Duration
+    keepStale  bool
+
+    // Request coalescing for identical range requests.
+    inflight   map[string]*inflightRequest
+    inflightMu sync.Mutex
+}
+
+func RegKey(slaveID, functionCode byte, address uint16) string {
+    return fmt.Sprintf("%d:%d:%d", slaveID, functionCode, address)
 }
 
-func (c *Cache) Get(key string) ([]byte, bool) {
+func RangeKey(slaveID, functionCode byte, address, quantity uint16) string {
+    return fmt.Sprintf("%d:%d:%d:%d", slaveID, functionCode, address, quantity)
+}
+
+func (c *Cache) GetRange(slaveID, functionCode byte, address, quantity uint16) ([][]byte, bool) {
+    if quantity == 0 {
+        return nil, false
+    }
+
     c.mu.RLock()
     defer c.mu.RUnlock()
-    
-    entry, ok := c.entries[key]
-    if !ok || time.Since(entry.Timestamp) > entry.TTL {
-        return nil, false
+
+    values := make([][]byte, quantity)
+    for i := uint16(0); i < quantity; i++ {
+        entry, ok := c.entries[RegKey(slaveID, functionCode, address+i)]
+        if !ok || entry.IsExpired() {
+            return nil, false
+        }
+        values[i] = append([]byte(nil), entry.Data...)
+    }
+    return values, true
+}
+
+func (c *Cache) SetRange(slaveID, functionCode byte, address uint16, values [][]byte) {
+    c.mu.Lock()
+    defer c.mu.Unlock()
+
+    now := time.Now()
+    for i, value := range values {
+        c.entries[RegKey(slaveID, functionCode, address+uint16(i))] = &CacheEntry{
+            Data:      append([]byte(nil), value...),
+            Timestamp: now,
+            TTL:       c.defaultTTL,
+        }
     }
-    return entry.Data, true
 }
 
-func (c *Cache) Set(key string, data []byte, ttl time.Duration) {
+func (c *Cache) DeleteRange(slaveID, functionCode byte, address, quantity uint16) {
     c.mu.Lock()
     defer c.mu.Unlock()
-    
-    c.entries[key] = &CacheEntry{
-        Data:      data,
-        Timestamp: time.Now(),
-        TTL:       ttl,
+
+    for i := uint16(0); i < quantity; i++ {
+        delete(c.entries, RegKey(slaveID, functionCode, address+i))
     }
 }
 ```
 
+The cache also exposes `Coalesce(ctx, rangeKey, fetch)` for request coalescing. It does not read or write cache entries directly; the proxy performs cache lookups and stores decomposed responses.
+
 ### Request Flow
 
 1. Client sends Modbus TCP request
 2. Parse request: extract slave ID, function code, address, quantity
 3. **For reads**:
-   - Build cache key
-   - Check cache → if hit & valid, return cached data
-   - On miss: forward to upstream device
-   - Store response in cache
+   - Check every per-register/coil cache key in the requested range
+   - If all values are present and valid, reassemble and return the Modbus response
+   - On any miss or expired value: coalesce identical in-flight range requests, then forward to upstream device
+   - Decompose successful upstream responses into per-register/coil cache entries
    - Return response to client
 4. **For writes**:
    - Check readonly mode
-   - If allowed: forward to upstream, optionally invalidate cache
+   - If allowed: forward to upstream, then invalidate every cached register/coil in the written address range
    - Return response
 
 ## Logging