Token bucket admits more than capacity under concurrent load

A capacity guarantee that only holds under light load is not a capacity guarantee -- it fails precisely when traffic is heavy enough to matter, which is the entire reason a rate limiter exists in the first place. If a token bucket is sized to protect a downstream database, a paid third-party API with its own (billed) rate limit, or an expensive compute path, this bug means that protection quietly disappears under exactly the load spike it was provisioned for. That risk ranges from cascading internal outages to unexpected overage charges from a third party you're supposed to be shielding -- both are the kind of incident that happens once, expensively, under real production traffic, not in a quiet afternoon of manual testing.

The README is explicit about the concurrency contract here: token bucket uses a sync.Mutex per key, because refilling and consuming tokens is a compound read-modify-write over two related float64 fields and there's no lock-free way to update two dependent floats together. The mutex is still present in the code, but it no longer covers the whole compound operation -- part of the critical section (the check-and-decrement of e.tokens) now runs after the lock has already been released.

tb := ratelimit.NewTokenBucketMemory(50, 0 /* no refill */, time.Minute) var wg sync.WaitGroup; var allowed int64 for i := 0; i < 500; i++ { wg.Add(1) go func() { defer wg.Done() if res, _ := tb.Allow(ctx, "shared-key"); res.Allowed { atomic.AddInt64(&allowed, 1) } }() } wg.Wait() // want: allowed <= 50, always // got: allowed occasionally > 50; go test -race reliably reports a data race on tokens

A rate limiter that can be pushed past its configured capacity under load is worse than useless -- the failure mode (silently admitting more traffic than intended) shows up exactly when the system is under the load pressure the limiter exists to protect against, i.e. the worst possible time for it to fail.

Find where e.mu.Unlock() happens relative to the read of e.tokens in the if e.tokens >= float64(n) check and the subsequent e.tokens -= float64(n) write. The entire compound operation -- refill, check, and consume-if-sufficient -- needs to happen while holding the lock, not just the refill part. Using defer e.mu.Unlock() right after e.mu.Lock() (the pattern every other mutex-protected section in this package still uses) is the simplest way to guarantee this regardless of how many early-return branches get added later.