Documentation
¶
Overview ¶
Package ratelimit provides explicit fixed-window request throttling with a replaceable persistence contract. The in-memory store is bounded and suited to one-process applications; distributed deployments can replace Store.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidConfiguration = errors.New("rate limiter configuration is invalid")
var ErrInvalidForwardedChain = errors.New("rate limit: invalid forwarded address chain")
Functions ¶
func Key ¶
Key hashes namespaced key parts so stores do not retain raw email addresses, IP addresses, or other identifying inputs.
func Middleware ¶
func Middleware(limiter *Limiter, key KeyFunc) httpx.Middleware
Middleware enforces a limiter before invoking the next handler.
func RemoteAddress ¶
RemoteAddress returns the direct peer address without trusting spoofable forwarding headers. Applications behind trusted proxies can supply their own KeyFunc after validating proxy configuration.
Types ¶
type Limiter ¶
type Limiter struct {
// contains filtered or unexported fields
}
type MemoryStore ¶
type MemoryStore struct {
// contains filtered or unexported fields
}
MemoryStore is a bounded, concurrency-safe fixed-window store. When full it removes expired entries; if capacity is still exhausted, unseen keys are denied until the earliest active window resets instead of evicting a live key and allowing a key-spray bypass.
func NewMemoryStore ¶
func NewMemoryStore(capacity int) *MemoryStore
type Store ¶
type Store interface {
Take(context.Context, string, Policy, time.Time) (Decision, error)
Reset(context.Context, string) error
}
Store atomically consumes one attempt for key. Reset removes accumulated attempts, normally after successful authentication.
type TrustedProxies ¶
type TrustedProxies struct {
// contains filtered or unexported fields
}
TrustedProxies is an explicit allowlist of network peers whose forwarding metadata may participate in client address resolution. Its zero value trusts no peer. Prefixes are immutable after construction and safe for concurrent use.
func ParseTrustedProxies ¶
func ParseTrustedProxies(values ...string) (TrustedProxies, error)
ParseTrustedProxies validates a list of CIDR prefixes. Each argument may contain a comma-separated list, which makes the function convenient for an environment setting. An empty list is valid and trusts no peer. Bare IP addresses are rejected so the configured trust boundary remains conspicuous.
func (TrustedProxies) ClientAddress ¶
func (trusted TrustedProxies) ClientAddress(request *http.Request) string
ClientAddress resolves the effective client without ever trusting forwarding metadata automatically. Forwarded or X-Forwarded-For is considered only when the socket peer belongs to trusted. A malformed or ambiguous chain safely falls back to RemoteAddress.
func (TrustedProxies) Contains ¶
func (trusted TrustedProxies) Contains(address netip.Addr) bool
Contains reports whether address belongs to an explicitly configured proxy prefix. IPv4-mapped IPv6 addresses are normalized before comparison.
func (TrustedProxies) ResolveClientAddress ¶
func (trusted TrustedProxies) ResolveClientAddress(request *http.Request) (string, error)
ResolveClientAddress is ClientAddress with a diagnostic error for malformed forwarding data. It still returns the direct peer as its address on error so callers can log the problem without accidentally trusting attacker input.
Source Files
Directories