gosteady

Gosteady

Deterministic, testable token-bucket rate limiting for Go, with optional upstream-aware dynamic tuning.

This package wraps golang.org/x/time/rate but avoids real time in tests by using an injected clock (utils.Clock).

Features

• Token-bucket limiting (requests per minute + burst)
• context.Context cancellation support
• Thread-safe public API
• Deterministic tests via injected clock + fake timers
• Optional dynamic adjustment using upstream rate limit state
• Minimal logger interface (adapter-friendly)

Install

go get codeberg.org/joydx/gosteady

Import:

import "codeberg.org/joydx/gosteady"

Quick start

cfg := gosteady.DefaultLimiterConfig().
    WithRequestsLimitPerMinute(60) // ~1 request/second

l := gosteady.NewLimiter(&cfg)

for {
    if err := l.WaitForAllowance(ctx); err != nil {
        return err
    }

    // perform upstream request...
}

Semantics: does WaitForAllowance consume a token?

Yes. If WaitForAllowance returns nil, capacity has been consumed for that operation. If the context is canceled while waiting, the reservation is canceled and does not affect future scheduling.

Configuration

LimiterConfig:

• RequestsLimitPerMinute: steady-state maximum under nominal conditions
• MinRequestsPerMinute: floor when adjusting down (defaults to 1 if <= 0)
• Burst: token bucket burst size (defaults to 1 if <= 0)
• AdjustEveryMillis: minimum interval between adjustments (defaults to 10s if <= 0)

Dynamic adjustment with upstream state

If an upstream API provides:

• total allowed in the current window
• remaining
• reset time

…you can feed it into AdjustRateByState:

state := gosteady.LimiterState{
    Status:         "nominal",
    TotalLimit:     100,
    RemainingLimit: 30,
    ResetTime:      &resetTime,
}

l.AdjustRateByState(state)

If upstream says you are limited:

l.AdjustRateByState(gosteady.LimiterState{Status: "limited"})

The limiter will clamp down to MinRequestsPerMinute (conservative safety).

Hard wait until upstream reset

If you get a definitive reset timestamp (e.g., from a Retry-After or reset header), you can hard-wait:

if err := l.WaitUntilReset(ctx, &resetTime); err != nil {
    return err
}

Logging

The logger interface is intentionally small:

type Logger interface {
    Debug(msg string, kv ...any)
    Info(msg string, kv ...any)
    Warn(msg string, kv ...any)
    Error(msg string, kv ...any)
}

The limiter emits an info log when the RPM changes:

• message: limiter rate updated
• keys: prev_rpm, new_rpm, burst

Testing

Tests use utils.FakeClock to:

• advance time deterministically
• assert that operations truly block until timers fire
• avoid flakiness from goroutine scheduling

Deterministic blocking assertions

When a call should block, tests can wait until the limiter actually created a timer before advancing the fake clock:

done := make(chan error, 1)
go func() { done <- l.WaitForAllowance(ctx) }()

// Avoid “advance before timer exists” no-op.
fc.WaitForTimersCreated(1)
fc.Advance(1*time.Second + 1*time.Nanosecond)

if err := <-done; err != nil {
    t.Fatal(err)
}