fix!: isolate token buckets per key and manage limiter lifecycle

[christiangda]

Summary

This PR fixes a critical correctness bug and modernizes the library.

The headline bug: every key shared a single underlying rate.Limiter, so all keys drained one token bucket — the core promise of per-key rate limiting did not actually hold. A new regression test (TestBucketLimiter_PerKeyIsolation) fails on the old code and passes now.

What changed

Correctness

• Per-key isolation: GetOrAdd now builds an independent Limiter per key via a func() Limiter factory. One key exhausting its budget no longer affects others.
• Atomic creation: key creation uses LoadOrStore, fixing a TOCTOU race that could create duplicate limiters for the same key.
• Correct eviction semantics + lifecycle: replaced the per-key sleeping goroutine (which deleted after a fixed time from creation, leaked a goroutine per key, and reset active buckets) with a single background sweeper that evicts genuinely idle keys — the idle timer is refreshed on every access. Added Close() to stop it.

API / best practices (Go 1.25)

• Storage[K, V] and BucketLimiter[K] are now generic for type safety.
• Added NewRateLimiterFunc(limit, burst) helper and WithClock / WithSweepInterval options.
• Storage gained LoadOrStore and Range.

Examples & headers

• Middleware uses net.SplitHostPort (IPv6-safe client IP).
• Middleware sets accurate Retry-After (from the reservation delay) and RateLimit-Limit/Remaining/Reset headers (IETF draft names + legacy X-RateLimit-*).
• examples/key is a minimal demo of per-key isolation and refill over time.

Docs & tests

• New docs/TOKEN_BUCKET.md: a thorough explanation of the token bucket algorithm, choosing limit/burst, Allow vs Wait vs Reserve, eviction, HTTP headers, algorithm comparison, and single-process vs distributed scope.
• Rewrote README.md and added package-level doc.go.
• Rewrote tests: isolation regression, deterministic eviction via an injected clock (de-flaked the old timing-bound Wait test), concurrency, storage, and benchmarks.

Verification

• go test -race ./... — passing, 100% statement coverage.
• go vet ./..., gofmt — clean.
• Both examples run; middleware verified end-to-end (200 with RateLimit-* headers → 429 with Retry-After: 1).

⚠️ Breaking changes

• NewBucketLimiter takes a func() Limiter factory instead of a Limiter instance.
• Storage and BucketLimiter are generic; NewInMemoryStorage requires type parameters (NewInMemoryStorage[string, ratelimiter.Limiter]()).
• BucketLimiter no longer implements Limiter — call GetOrAdd(key) to obtain one.
• Remove no longer returns an error.

Scope note

This library limits within a single process. Global cross-instance limiting needs a distributed algorithm and remains out of scope; Storage is for custom in-process stores.

🤖 Generated with Claude Code