Documentation
¶
Overview ¶
Package ratelimit implements a dual sliding-window rate limiter for authentication attempts (per-IP and per-account). Callers (typically an HTTP server's auth handlers) consume it via the Checker interface.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Checker ¶
type Checker interface {
Allow(ip ClientIP, username Username) (allowed bool, retryAfter time.Duration)
Record(ip ClientIP, username Username)
Reset(ip ClientIP, username Username)
}
Checker is the narrow interface consumed by callers (e.g. HTTP auth handlers). It decouples request handling from the concrete sliding-window implementation.
type ClientIP ¶
type ClientIP string
ClientIP is the per-client IP dimension key of the limiter. It is a distinct type so an IP and a username — both strings — cannot be swapped silently at a call site: the two dimensions have different windows and different limits, so a swap would quietly change the security posture.
type Config ¶
type Config struct {
IPLimit int
IPWindow time.Duration
AcctLimit int
AcctWindow time.Duration
PruneInterval time.Duration
MaxEntries int
}
Config groups all rate-limit tuning parameters into a single inspectable value. Use DefaultConfig() for production defaults.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns the production rate-limit configuration:
- Per-IP: 10 attempts / 15 minutes
- Per-account: 100 attempts / 1 hour
- Max tracked entries: 10000
type RateLimiter ¶
type RateLimiter struct {
// contains filtered or unexported fields
}
RateLimiter tracks failed authentication attempts per IP and per account using dual sliding windows (OWASP ASVS 2.2.1). A RateLimiter must be created with New: the zero value has nil window maps (Record panics), no prune goroutine, and a nil cancel func (Shutdown panics dereferencing it).
func New ¶
func New(ctx context.Context, cfg Config) *RateLimiter
New creates a rate limiter with the given configuration. A background goroutine prunes stale entries at cfg.PruneInterval. The goroutine stops when ctx is cancelled; call RateLimiter.Shutdown to stop it explicitly and wait for it to exit.
func (*RateLimiter) Allow ¶
func (rl *RateLimiter) Allow(ip ClientIP, username Username) (allowed bool, retryAfter time.Duration)
Allow checks both IP and account windows. Both must be within limits for the request to proceed. Returns false with a retry-after duration if either limit is exceeded. An empty ip or username skips that dimension (a missing key carries no per-client signal and would otherwise lump unrelated callers into one shared bucket); callers should supply a real per-client IP so the IP dimension applies.
func (*RateLimiter) Record ¶
func (rl *RateLimiter) Record(ip ClientIP, username Username)
Record records a failed authentication attempt in the IP and account sliding windows. An empty ip or username skips that dimension, mirroring Allow and Reset.
func (*RateLimiter) Reset ¶
func (rl *RateLimiter) Reset(ip ClientIP, username Username)
Reset clears the sliding window entries for the given IP and username. Call after a successful authentication to prevent permanent soft-lockout (OWASP ASVS 2.2.1).
func (*RateLimiter) Shutdown ¶
func (rl *RateLimiter) Shutdown(ctx context.Context) error
Shutdown stops the background prune goroutine and blocks until it has exited or ctx expires, returning nil in the first case and ctx.Err() in the second (in which case the goroutine is still winding down). Completion is consulted before the context — the stdlib net/http.Server.Shutdown shape — so once the goroutine has exited, Shutdown returns nil deterministically even when ctx is already expired. It is safe to call more than once.