refactor: replace wall-clock time with monotonic nanoseconds for request eviction

- Add `created` timestamp to Jaws struct and capture it in New()
- Introduce nowNano() method returning monotonic elapsed nanoseconds since creation
- Update oldestEvictablePendingLocked to use nowNano instead of time.Time, and check lastWriteNano against 2*maintenanceInterval window
- Replace all time.Now() calls with jw.nowNano() in pending eviction and maintenance logic
- Switch from Rendering flag + lastWrite time comparison to direct lastWriteNano recency check
- Update tests to simulate writes via MarkWritten instead of setting Rendering flag
- Add BenchmarkRequestMarkWritten for write stamping performance tracking

Signed-off-by: Johan Lindh <johan@linkdata.se>

Author: linkdata

jaws.go

@@ -155,6 +155,7 @@ type Jaws struct {
 	MaxPendingRequestsPerIP int             // Maximum number of unclaimed Requests per client IP. Defaults to DefaultMaxPendingRequestsPerIP. Set <=0 to disable the cap.
 	webSocketTimeout        time.Duration   // timeout duration passed to ServeWith
 	maintenanceInterval     time.Duration   // Serve maintenance tick interval; set by ServeWithTimeout and read under mu, zero until Serve starts
+	created                 time.Time       // monotonic base captured in New(); read-only after construction, basis for nowNano
 	bcastCh                 chan wire.Message
 	subCh                   chan subscription
 	unsubCh                 chan chan wire.Message
@@ -196,6 +197,7 @@ func New() (jw *Jaws, err error) {
 				WebSocketPingInterval:   DefaultWebSocketPingInterval,
 				MaxPendingRequestsPerIP: DefaultMaxPendingRequestsPerIP,
 				webSocketTimeout:        DefaultWebSocketTimeout,
+				created:                 time.Now(),
 				serveJS:                 serveJS,
 				serveCSS:                serveCSS,
 				bcastCh:                 make(chan wire.Message, 1),
@@ -407,15 +409,24 @@ func (jw *Jaws) NewRequest(r *http.Request) (rq *Request) {
 	return
 }
 
+// nowNano returns monotonic nanoseconds elapsed since the [Jaws] was created.
+//
+// It is the basis for [Request.MarkWritten] and the pending-eviction recency check.
+// Because it derives from [time.Since] on a [time.Time] carrying the monotonic clock,
+// the value is immune to wall-clock and NTP adjustments.
+func (jw *Jaws) nowNano() int64 {
+	return int64(time.Since(jw.created))
+}
+
 // limitPendingRequestsLocked evicts pending Requests for remoteIP until the cap is
 // satisfied, returning the eviction causes for the caller to log after releasing
 // jw.mu (see the package locking contract). Caller must hold jw.mu.
 func (jw *Jaws) limitPendingRequestsLocked(remoteIP netip.Addr) (toLog []error) {
 	limit := jw.MaxPendingRequestsPerIP
 	if limit > 0 {
-		now := time.Now()
+		nowNano := jw.nowNano()
 		for len(jw.pending[remoteIP]) >= limit {
-			victim := jw.oldestEvictablePendingLocked(remoteIP, now)
+			victim := jw.oldestEvictablePendingLocked(remoteIP, nowNano)
 			if victim == nil {
 				// Every pending Request for this IP is rendering or rendered too
 				// recently to evict safely. Recycling a still-rendering one would
@@ -437,42 +448,37 @@ func (jw *Jaws) limitPendingRequestsLocked(remoteIP netip.Addr) (toLog []error)
 }
 
 // oldestEvictablePendingLocked returns the oldest pending [Request] for remoteIP
-// that is safe to recycle, or nil if every one of them might still be rendering.
-// now is the reference time for the recency check; the caller passes a single value
-// so all candidates are judged against the same instant. Caller must hold jw.mu.
-//
-// A Request is spared when its Rendering flag is set (it has been written to by
-// [RequestWriter] and may still be assembling its initial HTML, which recycling would
-// corrupt — see [Jaws.limitPendingRequestsLocked]), OR when it last wrote within
-// 2*maintenanceInterval. The recency check is required because [Request.maintenance]
-// clears Rendering once per maintenance interval: between that clear and the render
-// goroutine's next write the flag reads false even though the HTML is still in flight,
-// so keying eviction on the flag alone would recycle a live render.
-//
-// lastWrite tracks write activity, not render duration. Each [RequestWriter] write
-// re-arms Rendering, and the next [Request.maintenance] pass that observes it set
-// advances lastWrite to that pass's time. A render that keeps writing therefore keeps
-// refreshing lastWrite and stays spared; a render that produces no write for more than
-// two maintenance intervals — whether it has finished or has merely stalled between
-// writes — falls outside the window and becomes evictable. Reading lastWrite takes
-// rq.mu beneath jw.mu, the order documented in the package "Locking" section.
-//
-// maintenanceInterval is zero until [Jaws.ServeWithTimeout] starts. With no maintenance
-// pass running nothing clears Rendering, so the flag alone is authoritative and the
-// recency window is correctly skipped.
-func (jw *Jaws) oldestEvictablePendingLocked(remoteIP netip.Addr, now time.Time) *Request {
+// that is safe to recycle, or nil if every one of them was written too recently to
+// evict safely. nowNano is the reference instant (see [Jaws.nowNano]); the caller
+// passes a single value so all candidates are judged against the same instant.
+// Caller must hold jw.mu.
+//
+// A Request is spared while its initial HTML may still be in flight. Recycling a
+// Request whose render goroutine is still writing would let a later [Jaws.NewRequest]
+// reuse the pooled pointer under a new key while that goroutine keeps appending
+// elements (see [Jaws.limitPendingRequestsLocked]). [RequestWriter.Write] stamps the
+// write instant on every write via [Request.MarkWritten], so a Request is treated as
+// possibly-rendering, and spared, while its last write is within 2*maintenanceInterval.
+//
+// The timestamp is the exact instant of the last write, not a value sampled once per
+// maintenance pass, so an actively writing render is always fresh and only a render
+// that has produced no write for two intervals — whether finished or merely stalled
+// between writes — becomes evictable. lastWriteNano is read lock-free, so this scan
+// takes no Request lock.
+//
+// maintenanceInterval is zero until [Jaws.ServeWithTimeout] starts; the window then
+// falls back to [DefaultUpdateInterval] so an in-flight render is still protected
+// before the maintenance pass begins running.
+func (jw *Jaws) oldestEvictablePendingLocked(remoteIP netip.Addr, nowNano int64) *Request {
+	interval := jw.maintenanceInterval
+	if interval <= 0 {
+		interval = DefaultUpdateInterval
+	}
+	spareWindow := int64(2 * interval)
 	for _, rq := range jw.pending[remoteIP] {
-		if rq.Rendering.Load() {
+		if nowNano-rq.lastWriteNano.Load() <= spareWindow {
 			continue
 		}
-		if jw.maintenanceInterval > 0 {
-			rq.mu.RLock()
-			recentlyRendered := now.Sub(rq.lastWrite) <= 2*jw.maintenanceInterval
-			rq.mu.RUnlock()
-			if recentlyRendered {
-				continue
-			}
-		}
 		return rq
 	}
 	return nil
@@ -744,9 +750,9 @@ func (jw *Jaws) unsubscribe(msgCh chan wire.Message) {
 func (jw *Jaws) maintenance(requestTimeout time.Duration) {
 	var toLog []error
 	jw.mu.Lock()
-	now := time.Now()
+	nowNano := jw.nowNano()
 	for _, rq := range jw.requests {
-		if expired, cause := rq.maintenance(now, requestTimeout); expired {
+		if expired, cause := rq.maintenance(nowNano, requestTimeout); expired {
 			if cause != nil {
 				toLog = append(toLog, cause)
 			}
@@ -833,7 +839,7 @@ func (jw *Jaws) getRequestLocked(jawsKey key.Key, r *http.Request, remoteIP neti
 	rq.mu.Lock()
 	defer rq.mu.Unlock()
 	rq.JawsKey = jawsKey
-	rq.lastWrite = time.Now()
+	rq.lastWriteNano.Store(jw.nowNano())
 	rq.initial = r
 	rq.remoteIP = remoteIP
 	rq.ctx, rq.cancelFn = context.WithCancelCause(jw.BaseContext)

jaws_benchmark_test.go

@@ -51,7 +51,7 @@ func newUnpooledBenchRequest(jw *Jaws) (rq *Request) {
 			}
 			rq.mu.Lock()
 			rq.JawsKey = jawsKey
-			rq.lastWrite = time.Now()
+			rq.lastWriteNano.Store(jw.nowNano())
 			rq.remoteIP = remoteIP
 			rq.ctx, rq.cancelFn = context.WithCancelCause(jw.BaseContext)
 			rq.mu.Unlock()
@@ -405,3 +405,22 @@ func BenchmarkDistributeDirtSort(b *testing.B) {
 		})
 	}
 }
+
+// BenchmarkRequestMarkWritten measures the per-write cost of recording the write
+// instant, which RequestWriter.Write incurs on every write during initial render.
+// It runs in parallel because the realistic load is many Requests rendering at
+// once; the operation must stay cheap and allocation-free under contention.
+func BenchmarkRequestMarkWritten(b *testing.B) {
+	jw, err := New()
+	if err != nil {
+		b.Fatal(err)
+	}
+	b.Cleanup(func() { jw.Close() })
+	rq := &Request{Jaws: jw}
+	b.ReportAllocs()
+	b.RunParallel(func(pb *testing.PB) {
+		for pb.Next() {
+			rq.MarkWritten()
+		}
+	})
+}

jaws_test.go

@@ -234,12 +234,16 @@ func TestJaws_MaxPendingRequestsPerIPSparesRenderingRequest(t *testing.T) {
 	renderingReq := newPendingLimitRequest("192.0.2.1:1000")
 	renderingRq := jw.NewRequest(renderingReq)
 	renderingKey := renderingRq.JawsKey
-	// Simulate an in-flight initial render on the oldest pending Request.
-	renderingRq.Rendering.Store(true)
+	// Simulate an in-flight initial render on the oldest pending Request: a fresh
+	// write timestamp. maintenanceInterval is zero here, so the spare window uses
+	// the DefaultUpdateInterval floor.
+	renderingRq.MarkWritten()
 
 	idleReq := newPendingLimitRequest("192.0.2.1:1001")
 	idleRq := jw.NewRequest(idleReq)
 	idleKey := idleRq.JawsKey
+	// Age the idle Request well past the spare window so it is the eviction victim.
+	setPendingLimitLastWrite(t, idleRq, time.Now().Add(-time.Hour))
 
 	// Creating a third same-IP Request trips the cap (pending == 2).
 	newReq := newPendingLimitRequest("192.0.2.1:1002")
@@ -258,14 +262,10 @@ func TestJaws_MaxPendingRequestsPerIPSparesRenderingRequest(t *testing.T) {
 	}
 }
 
-// TestJaws_MaxPendingRequestsPerIPSparesRecentlyRenderedRequest verifies that the
-// pending cap does not evict a Request whose initial render is still in flight even
-// after a maintenance pass has cleared its Rendering flag. [Request.maintenance]
-// clears Rendering once per interval, so between that clear and the render goroutine's
-// next write the flag reads false while the HTML is still being assembled; keying
-// eviction on the flag alone would recycle the live render. oldestEvictablePendingLocked
-// therefore also spares a Request that rendered within 2*maintenanceInterval and falls
-// through to evict a genuinely idle one instead.
+// TestJaws_MaxPendingRequestsPerIPSparesRecentlyRenderedRequest verifies that with a
+// configured maintenanceInterval the pending cap spares a Request written within the
+// 2*maintenanceInterval recency window and falls through to evict a genuinely idle one
+// instead.
 func TestJaws_MaxPendingRequestsPerIPSparesRecentlyRenderedRequest(t *testing.T) {
 	jw, err := New()
 	if err != nil {
@@ -274,23 +274,17 @@ func TestJaws_MaxPendingRequestsPerIPSparesRecentlyRenderedRequest(t *testing.T)
 	defer jw.Close()
 	jw.MaxPendingRequestsPerIP = 2
 	// Pretend the Serve loop is running with a one-minute maintenance interval so the
-	// recency window is active (it is zero until ServeWithTimeout sets it).
+	// recency window is 2*maintenanceInterval (it falls back to DefaultUpdateInterval
+	// until ServeWithTimeout sets it).
 	jw.mu.Lock()
 	jw.maintenanceInterval = time.Minute
 	jw.mu.Unlock()
 
-	// The oldest pending Request is mid-render...
+	// The oldest pending Request wrote recently (its render is still in flight).
 	renderingReq := newPendingLimitRequest("192.0.2.1:1000")
 	renderingRq := jw.NewRequest(renderingReq)
 	renderingKey := renderingRq.JawsKey
-	renderingRq.Rendering.Store(true)
-
-	// ...and a maintenance pass clears its Rendering flag (refreshing lastWrite) while
-	// the render is still in flight on its HTTP goroutine.
-	jw.maintenance(time.Hour)
-	if renderingRq.Rendering.Load() {
-		t.Fatal("maintenance did not clear Rendering")
-	}
+	renderingRq.MarkWritten()
 
 	// A genuinely idle Request that rendered long ago is the correct eviction victim.
 	idleReq := newPendingLimitRequest("192.0.2.1:1001")
@@ -316,6 +310,55 @@ func TestJaws_MaxPendingRequestsPerIPSparesRecentlyRenderedRequest(t *testing.T)
 	}
 }
 
+// TestJaws_MaxPendingRequestsPerIPSparesStalledLiveRender proves the eviction decision
+// tracks the actual last write, not a value sampled by the maintenance pass: a render
+// that wrote once and then stalled (no further writes) is still spared while that write
+// is within 2*maintenanceInterval, even across a maintenance pass — closing the gap
+// where clearing a flag on a tick could expose a live render to recycling.
+func TestJaws_MaxPendingRequestsPerIPSparesStalledLiveRender(t *testing.T) {
+	jw, err := New()
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer jw.Close()
+	jw.MaxPendingRequestsPerIP = 2
+	jw.mu.Lock()
+	jw.maintenanceInterval = time.Minute
+	jw.mu.Unlock()
+
+	// Oldest pending: a single write, then silence. Its timestamp stays fresh.
+	stalledReq := newPendingLimitRequest("192.0.2.1:1000")
+	stalledRq := jw.NewRequest(stalledReq)
+	stalledKey := stalledRq.JawsKey
+	stalledRq.MarkWritten()
+
+	// A maintenance pass must not disturb the write timestamp (generous timeout so the
+	// stalled render is not idle-expired). Under a flag-cleared-by-tick scheme this is
+	// where protection could be lost.
+	jw.maintenance(time.Hour)
+
+	// A genuinely idle sibling is the correct victim.
+	idleReq := newPendingLimitRequest("192.0.2.1:1001")
+	idleRq := jw.NewRequest(idleReq)
+	idleKey := idleRq.JawsKey
+	setPendingLimitLastWrite(t, idleRq, time.Now().Add(-time.Hour))
+
+	// A third same-IP Request trips the cap (pending == 2).
+	newReq := newPendingLimitRequest("192.0.2.1:1002")
+	newRq := jw.NewRequest(newReq)
+	newKey := newRq.JawsKey
+
+	if claimed := jw.UseRequest(stalledKey, stalledReq); claimed != stalledRq {
+		t.Fatalf("stalled-but-recently-written render claim = %v, want it to survive eviction", claimed)
+	}
+	if claimed := jw.UseRequest(idleKey, idleReq); claimed != nil {
+		t.Fatalf("idle request should have been evicted, got %v", claimed)
+	}
+	if claimed := jw.UseRequest(newKey, newReq); claimed != newRq {
+		t.Fatalf("new request claim = %v, want %v", claimed, newRq)
+	}
+}
+
 // TestJaws_MaxPendingRequestsPerIPOvershootsWhenAllRendering verifies that when
 // every pending request for an IP is mid-render, the cap is not enforced by
 // recycling one of them: oldestEvictablePendingLocked finds no idle victim, so the
@@ -331,7 +374,7 @@ func TestJaws_MaxPendingRequestsPerIPOvershootsWhenAllRendering(t *testing.T) {
 
 	rq1 := jw.NewRequest(newPendingLimitRequest("192.0.2.1:1000"))
 	rq1Key := rq1.JawsKey
-	rq1.Rendering.Store(true)
+	rq1.MarkWritten()
 
 	// A second same-IP request trips the cap, but the only pending request is
 	// rendering, so nothing is evicted and the cap overshoots to 2.
@@ -621,9 +664,11 @@ func newPendingLimitRequest(remoteAddr string) *http.Request {
 
 func setPendingLimitLastWrite(t *testing.T, rq *Request, lastWrite time.Time) {
 	t.Helper()
-	rq.mu.Lock()
-	rq.lastWrite = lastWrite
-	rq.mu.Unlock()
+	// lastWriteNano holds monotonic nanos since rq.Jaws.created; convert the wall
+	// time the test wants relative to that base. A past instant yields a negative
+	// value, which reads as far older than any spare/idle window — exactly what an
+	// "aged" request should look like.
+	rq.lastWriteNano.Store(int64(lastWrite.Sub(rq.Jaws.created)))
 }
 
 func TestCoverage_GenerateHeadAndConvenienceBroadcasts(t *testing.T) {