From a97dc3bf57a93053a69ad473b8fc0364ad540641 Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Fri, 22 May 2026 22:15:08 +0000 Subject: [PATCH] docs(distributed): note progress-event ordering trade-off in InstallBackend Document near the goroutine dispatch why ordering at the consumer is best-effort, why it rarely matters in practice (worker debounce >> goroutine jitter), and what a future hardening pass would look like (Seq field + stale-by-seq drop). Stops the next reader from accidentally "fixing" the goroutine pool away. Signed-off-by: Ettore Di Giacinto --- core/services/nodes/unloader.go | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/core/services/nodes/unloader.go b/core/services/nodes/unloader.go index 69002c4cd..e9844472b 100644 --- a/core/services/nodes/unloader.go +++ b/core/services/nodes/unloader.go @@ -141,6 +141,15 @@ func (a *RemoteUnloaderAdapter) InstallBackend( } // Goroutine guard: a slow onProgress callback must not stall // the NATS reader thread. + // + // NOTE: events spawn one goroutine each, so ordering at the + // consumer is best-effort. In practice the worker debounces to + // ~250ms which is far larger than goroutine scheduling jitter, + // so reordering is rare. The worker's final Flush() event is + // intended to win as the terminal tick. A future hardening pass + // could add a Seq uint64 field to BackendInstallProgressEvent + // and drop stale-by-seq at the bridge if reordering becomes a + // real UX issue. go onProgress(ev) }) if subErr != nil {