warmupx

warmupx

Gradual capacity ramp-up (slow start) for industrial Go services.

Philosophy

One job: gradual capacity ramp-up. A [Warmer] increases its admission probability from a minimum to a maximum over a configurable duration using one of four strategies. No HTTP, no framework coupling, no struct tags.

Use cases: cold start, post-deploy rollout, circuit-breaker recovery, auto-scaling new instances.

Quick start

w := warmupx.New(
    warmupx.WithDuration(30 * time.Second),
    warmupx.WithStrategy(warmupx.Exponential),
)
w.Start()
defer w.Stop()

if w.Allow() {
    handleRequest(ctx)
} else {
    // 503 or queue
}

API

Options

Strategies

Capacity
    ^
100%│                    ┌─────────────
    │                   /
    │                  /   Linear
    │                 /    Exponential
    │                /     Logarithmic
    │               /      Step
 10%│──────────────/
    └──────────────────────────────────▶ Time
                   Duration

Behavior details

• Probabilistic admission: Allow() returns true with probability equal to current capacity. At 50% capacity, roughly half of calls are admitted.

• Allow before Start: calling Allow() before Start() uses the initial MinCapacity value (default 0.1). This means ~10% of calls are admitted even before warmup begins, providing a safe default.

• Tick-based updates: a background goroutine updates capacity at WithInterval frequency. Default is Duration/100 (100 updates), clamped to [10ms, 1s].

• Completion: when elapsed time reaches Duration, capacity is set to MaxCapacity, IsComplete() returns true, WaitForCompletion unblocks, and callbacks fire asynchronously.

• Restart safety: calling StartAt while warming safely closes the previous goroutine before starting a new one. No double-close panics.

• Callbacks are async: OnCapacityChange and OnComplete run in separate goroutines. They may be delivered out-of-order under high contention.

Error diagnostics

All errors are *errx.Error with Domain = "WARMUP", Severity = Warn, Retry = RetrySafe.

Codes

Example

WARMUP.REJECTED: request rejected during warmup | meta: capacity=0.35, progress=0.42

Thread safety

• Capacity, IsWarming, IsComplete, Progress, Stats use sync.RWMutex — readers never block each other
• Allow reads capacity under RLock, increments atomic counters — lock-free on hot path
• Start, Stop, Reset, StartAt use exclusive lock — safe for concurrent calls
• ResetStats is lock-free (atomic stores)
• Background ticker goroutine updates capacity under exclusive lock

Tests

55 tests, 97.6% statement coverage.

go test -race -count=1 -coverprofile=coverage.out ./...
ok  github.com/aasyanov/urx/pkg/warmupx  coverage: 97.6% of statements

Coverage includes:

• All four strategies reach MaxCapacity
• Direct calculate() validation for each curve
• All options: valid and invalid values, clamping
• Start/Stop/Reset lifecycle, multiple restarts
• Completion with callbacks
• Progress before/during/after warmup
• Allow at 0%, 50%, 100% capacity
• AllowOrError with errx.Error validation
• MaxRequests with rounding
• WaitForCompletion: success, timeout, already-complete
• Stats before start, during warmup
• ResetStats
• Concurrent read operations (100 goroutines)
• Concurrent Start/Stop/Reset (150 goroutines)
• tick() early returns (not warming, already complete)

The uncovered 2.4% is defensive code: remaining < 0 guard in Stats and default branch in calculate (unreachable for valid Strategy values).

Benchmarks

Environment: go1.24.0 windows/amd64, Intel Core i7-10510U @ 1.80 GHz.

BenchmarkAllow                    parallel    0 allocs/op
BenchmarkAllowOrError_Allowed     parallel    0 allocs/op
BenchmarkAllowOrError_Rejected    parallel    1 alloc/op (errx.Error)
BenchmarkCapacity                 parallel    0 allocs/op
BenchmarkProgress                 parallel    0 allocs/op
BenchmarkStats                    parallel    0 allocs/op
BenchmarkMaxRequests              sequential  0 allocs/op

Performance summary

File structure

pkg/warmupx/
    warmupx.go       -- Warmer, Strategy, New(), Start/Stop/Allow, options
    errors.go        -- DomainWarmup, Code constants, error constructors
    warmupx_test.go  -- 55 tests, 97.6% coverage
    bench_test.go    -- 7 benchmarks
    README.md