ratelimit

package
v5.0.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 8, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

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.

type Username

type Username string

Username is the per-account dimension key of the limiter. See ClientIP for why the two key types are distinct.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL