modelerrors: move backoff and sleep utilities to pkg/backoff

SleepWithContext and CalculateBackoff are general-purpose utilities not
specific to model errors. Move them to a new pkg/backoff package for
clarity and reusability. MaxRetryAfterWait moves there too.

Deprecated wrapper variables are left in modelerrors to maintain
backward compatibility. The runtime/fallback package now imports
pkg/backoff directly.

Assisted-By: docker-agent

Author: dgageot

pkg/backoff/backoff.go

@@ -0,0 +1,60 @@
+// Package backoff provides exponential backoff calculation and
+// context-aware sleep utilities.
+package backoff
+
+import (
+	"context"
+	"math/rand/v2"
+	"time"
+)
+
+// Configuration constants for exponential backoff.
+const (
+	baseDelay = 200 * time.Millisecond
+	maxDelay  = 2 * time.Second
+	factor    = 2.0
+	jitter    = 0.1
+
+	// MaxRetryAfterWait caps how long we'll honor a Retry-After header to prevent
+	// a misbehaving server from blocking the agent for an unreasonable amount of time.
+	MaxRetryAfterWait = 60 * time.Second
+)
+
+// Calculate returns the backoff duration for a given attempt (0-indexed).
+// Uses exponential backoff with jitter.
+func Calculate(attempt int) time.Duration {
+	if attempt < 0 {
+		attempt = 0
+	}
+
+	// Calculate exponential delay
+	delay := float64(baseDelay)
+	for range attempt {
+		delay *= factor
+	}
+
+	// Cap at max delay
+	if delay > float64(maxDelay) {
+		delay = float64(maxDelay)
+	}
+
+	// Add jitter (±10%)
+	j := delay * jitter * (2*rand.Float64() - 1)
+	delay += j
+
+	return time.Duration(delay)
+}
+
+// SleepWithContext sleeps for the specified duration, returning early if context is cancelled.
+// Returns true if the sleep completed, false if it was interrupted by context cancellation.
+func SleepWithContext(ctx context.Context, d time.Duration) bool {
+	timer := time.NewTimer(d)
+	defer timer.Stop()
+
+	select {
+	case <-timer.C:
+		return true
+	case <-ctx.Done():
+		return false
+	}
+}

pkg/backoff/backoff_test.go

@@ -0,0 +1,70 @@
+package backoff
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestCalculate(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		attempt     int
+		minExpected time.Duration
+		maxExpected time.Duration
+	}{
+		{attempt: 0, minExpected: 180 * time.Millisecond, maxExpected: 220 * time.Millisecond},
+		{attempt: 1, minExpected: 360 * time.Millisecond, maxExpected: 440 * time.Millisecond},
+		{attempt: 2, minExpected: 720 * time.Millisecond, maxExpected: 880 * time.Millisecond},
+		{attempt: 3, minExpected: 1440 * time.Millisecond, maxExpected: 1760 * time.Millisecond},
+		{attempt: 10, minExpected: 1800 * time.Millisecond, maxExpected: 2200 * time.Millisecond}, // capped at 2s
+	}
+
+	for _, tt := range tests {
+		t.Run(fmt.Sprintf("attempt_%d", tt.attempt), func(t *testing.T) {
+			t.Parallel()
+			b := Calculate(tt.attempt)
+			assert.GreaterOrEqual(t, b, tt.minExpected, "backoff should be at least %v", tt.minExpected)
+			assert.LessOrEqual(t, b, tt.maxExpected, "backoff should be at most %v", tt.maxExpected)
+		})
+	}
+
+	t.Run("negative attempt treated as 0", func(t *testing.T) {
+		t.Parallel()
+		b := Calculate(-1)
+		assert.GreaterOrEqual(t, b, 180*time.Millisecond)
+		assert.LessOrEqual(t, b, 220*time.Millisecond)
+	})
+}
+
+func TestSleepWithContext(t *testing.T) {
+	t.Parallel()
+
+	t.Run("completes normally", func(t *testing.T) {
+		t.Parallel()
+		ctx := t.Context()
+		start := time.Now()
+		completed := SleepWithContext(ctx, 10*time.Millisecond)
+		elapsed := time.Since(start)
+
+		assert.True(t, completed, "should complete normally")
+		assert.GreaterOrEqual(t, elapsed, 10*time.Millisecond)
+	})
+
+	t.Run("interrupted by context", func(t *testing.T) {
+		t.Parallel()
+		ctx, cancel := context.WithCancel(t.Context())
+		time.AfterFunc(10*time.Millisecond, cancel)
+
+		start := time.Now()
+		completed := SleepWithContext(ctx, 1*time.Second)
+		elapsed := time.Since(start)
+
+		assert.False(t, completed, "should be interrupted")
+		assert.Less(t, elapsed, 100*time.Millisecond, "should return quickly after cancel")
+	})
+}

pkg/modelerrors/modelerrors.go

@@ -8,25 +8,21 @@ import (
 	"context"
 	"errors"
 	"log/slog"
-	"math/rand/v2"
 	"net"
 	"net/http"
 	"regexp"
 	"strconv"
 	"strings"
 	"time"
+
+	"github.com/docker/docker-agent/pkg/backoff"
 )
 
 // Backoff and retry-after configuration constants.
 const (
-	backoffBaseDelay = 200 * time.Millisecond
-	backoffMaxDelay  = 2 * time.Second
-	backoffFactor    = 2.0
-	backoffJitter    = 0.1
-
 	// MaxRetryAfterWait caps how long we'll honor a Retry-After header to prevent
 	// a misbehaving server from blocking the agent for an unreasonable amount of time.
-	MaxRetryAfterWait = 60 * time.Second
+	MaxRetryAfterWait = backoff.MaxRetryAfterWait
 )
 
 // StatusError wraps an HTTP API error with structured metadata for retry decisions.
@@ -400,42 +396,15 @@ func ClassifyModelError(err error) (retryable, rateLimited bool, retryAfter time
 
 // CalculateBackoff returns the backoff duration for a given attempt (0-indexed).
 // Uses exponential backoff with jitter.
-func CalculateBackoff(attempt int) time.Duration {
-	if attempt < 0 {
-		attempt = 0
-	}
-
-	// Calculate exponential delay
-	delay := float64(backoffBaseDelay)
-	for range attempt {
-		delay *= backoffFactor
-	}
-
-	// Cap at max delay
-	if delay > float64(backoffMaxDelay) {
-		delay = float64(backoffMaxDelay)
-	}
-
-	// Add jitter (±10%)
-	jitter := delay * backoffJitter * (2*rand.Float64() - 1)
-	delay += jitter
-
-	return time.Duration(delay)
-}
+//
+// Deprecated: Use [backoff.Calculate] directly.
+var CalculateBackoff = backoff.Calculate
 
 // SleepWithContext sleeps for the specified duration, returning early if context is cancelled.
 // Returns true if the sleep completed, false if it was interrupted by context cancellation.
-func SleepWithContext(ctx context.Context, d time.Duration) bool {
-	timer := time.NewTimer(d)
-	defer timer.Stop()
-
-	select {
-	case <-timer.C:
-		return true
-	case <-ctx.Done():
-		return false
-	}
-}
+//
+// Deprecated: Use [backoff.SleepWithContext] directly.
+var SleepWithContext = backoff.SleepWithContext
 
 // FormatError returns a user-friendly error message for model errors.
 // Context overflow gets a dedicated actionable message; all other errors

pkg/modelerrors/modelerrors_test.go

@@ -71,66 +71,6 @@ func TestIsRetryableModelError(t *testing.T) {
 	}
 }
 
-func TestCalculateBackoff(t *testing.T) {
-	t.Parallel()
-
-	tests := []struct {
-		attempt     int
-		minExpected time.Duration
-		maxExpected time.Duration
-	}{
-		{attempt: 0, minExpected: 180 * time.Millisecond, maxExpected: 220 * time.Millisecond},
-		{attempt: 1, minExpected: 360 * time.Millisecond, maxExpected: 440 * time.Millisecond},
-		{attempt: 2, minExpected: 720 * time.Millisecond, maxExpected: 880 * time.Millisecond},
-		{attempt: 3, minExpected: 1440 * time.Millisecond, maxExpected: 1760 * time.Millisecond},
-		{attempt: 10, minExpected: 1800 * time.Millisecond, maxExpected: 2200 * time.Millisecond}, // capped at 2s
-	}
-
-	for _, tt := range tests {
-		t.Run(fmt.Sprintf("attempt_%d", tt.attempt), func(t *testing.T) {
-			t.Parallel()
-			backoff := CalculateBackoff(tt.attempt)
-			assert.GreaterOrEqual(t, backoff, tt.minExpected, "backoff should be at least %v", tt.minExpected)
-			assert.LessOrEqual(t, backoff, tt.maxExpected, "backoff should be at most %v", tt.maxExpected)
-		})
-	}
-
-	t.Run("negative attempt treated as 0", func(t *testing.T) {
-		t.Parallel()
-		backoff := CalculateBackoff(-1)
-		assert.GreaterOrEqual(t, backoff, 180*time.Millisecond)
-		assert.LessOrEqual(t, backoff, 220*time.Millisecond)
-	})
-}
-
-func TestSleepWithContext(t *testing.T) {
-	t.Parallel()
-
-	t.Run("completes normally", func(t *testing.T) {
-		t.Parallel()
-		ctx := t.Context()
-		start := time.Now()
-		completed := SleepWithContext(ctx, 10*time.Millisecond)
-		elapsed := time.Since(start)
-
-		assert.True(t, completed, "should complete normally")
-		assert.GreaterOrEqual(t, elapsed, 10*time.Millisecond)
-	})
-
-	t.Run("interrupted by context", func(t *testing.T) {
-		t.Parallel()
-		ctx, cancel := context.WithCancel(t.Context())
-		time.AfterFunc(10*time.Millisecond, cancel)
-
-		start := time.Now()
-		completed := SleepWithContext(ctx, 1*time.Second)
-		elapsed := time.Since(start)
-
-		assert.False(t, completed, "should be interrupted")
-		assert.Less(t, elapsed, 100*time.Millisecond, "should return quickly after cancel")
-	})
-}
-
 func TestExtractHTTPStatusCode(t *testing.T) {
 	t.Parallel()
 

pkg/runtime/fallback.go

@@ -8,6 +8,7 @@ import (
 	"time"
 
 	"github.com/docker/docker-agent/pkg/agent"
+	"github.com/docker/docker-agent/pkg/backoff"
 	"github.com/docker/docker-agent/pkg/chat"
 	"github.com/docker/docker-agent/pkg/model/provider"
 	"github.com/docker/docker-agent/pkg/modelerrors"
@@ -69,12 +70,12 @@ func logFallbackAttempt(agentName string, model modelWithFallback, attempt, maxR
 }
 
 // logRetryBackoff logs when we're backing off before a retry
-func logRetryBackoff(agentName, modelID string, attempt int, backoff time.Duration) {
+func logRetryBackoff(agentName, modelID string, attempt int, backoffDelay time.Duration) {
 	slog.Debug("Backing off before retry",
 		"agent", agentName,
 		"model", modelID,
 		"attempt", attempt+1,
-		"backoff", backoff)
+		"backoff", backoffDelay)
 }
 
 // getCooldownState returns the current cooldown state for an agent (thread-safe).
@@ -222,9 +223,9 @@ func (r *LocalRuntime) tryModelWithFallback(
 
 			// Apply backoff before retry (not on first attempt of each model)
 			if attempt > 0 {
-				backoff := modelerrors.CalculateBackoff(attempt - 1)
-				logRetryBackoff(a.Name(), modelEntry.provider.ID(), attempt, backoff)
-				if !modelerrors.SleepWithContext(ctx, backoff) {
+				backoffDelay := backoff.Calculate(attempt - 1)
+				logRetryBackoff(a.Name(), modelEntry.provider.ID(), attempt, backoffDelay)
+				if !backoff.SleepWithContext(ctx, backoffDelay) {
 					return streamResult{}, nil, ctx.Err()
 				}
 			}
@@ -382,14 +383,14 @@ func (r *LocalRuntime) handleModelError(
 		// Opt-in enabled, no fallbacks → retry same model after honouring Retry-After (or backoff).
 		waitDuration := retryAfter
 		if waitDuration <= 0 {
-			waitDuration = modelerrors.CalculateBackoff(attempt)
-		} else if waitDuration > modelerrors.MaxRetryAfterWait {
+			waitDuration = backoff.Calculate(attempt)
+		} else if waitDuration > backoff.MaxRetryAfterWait {
 			slog.Warn("Retry-After exceeds maximum, capping",
 				"agent", a.Name(),
 				"model", modelEntry.provider.ID(),
 				"retry_after", retryAfter,
-				"max", modelerrors.MaxRetryAfterWait)
-			waitDuration = modelerrors.MaxRetryAfterWait
+				"max", backoff.MaxRetryAfterWait)
+			waitDuration = backoff.MaxRetryAfterWait
 		}
 		slog.Warn("Rate limited, retrying (opt-in enabled)",
 			"agent", a.Name(),
@@ -398,7 +399,7 @@ func (r *LocalRuntime) handleModelError(
 			"wait", waitDuration,
 			"retry_after_from_header", retryAfter > 0,
 			"error", err)
-		if !modelerrors.SleepWithContext(ctx, waitDuration) {
+		if !backoff.SleepWithContext(ctx, waitDuration) {
 			return retryDecisionReturn
 		}
 		return retryDecisionContinue