Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RateLimiter ¶
func RateLimiter(opts ...Option) gin.HandlerFunc
RateLimiter returns a gin middleware that limits request rates per configurable key. Use functional options (WithRate, WithBurst, WithKeyFunc, etc.) to customize behavior.
Example:
r.Use(ratelimiter.RateLimiter(
ratelimiter.WithRate(rate.Every(100*time.Millisecond)),
ratelimiter.WithBurst(20),
ratelimiter.WithKeyFunc(func(c *gin.Context) string { return c.ClientIP() }),
ratelimiter.WithSkipFunc(func(c *gin.Context) bool { return c.FullPath() == "/health" }),
))
Types ¶
type Config ¶
type Config struct {
// Rate is the number of requests allowed per second.
// Defaults to 10 req/s if not set or non-positive.
Rate rate.Limit
// Burst is the maximum number of requests allowed to burst above the rate.
// Defaults to 50 if not set or non-positive.
Burst int
// TTL is the duration after which an idle rate limiter is evicted from the cache.
// Defaults to 24h if not set or non-positive.
TTL time.Duration
// KeyFunc extracts a unique key from the request to identify the rate limit subject.
// Defaults to client IP if not set.
//
// Common examples:
// c.ClientIP() per client IP (default)
// c.GetString("user_id") per authenticated user
// c.FullPath() per route
// c.GetHeader("X-API-Key") per API key
// c.FullPath() + ":" + c.GetString("user_id") per user per route
KeyFunc func(*gin.Context) string
// OnLimitReached is called when the rate limit is exceeded.
// If set, it is responsible for writing the response; the default 429 response is skipped.
// Defaults to responding with CodeTooManyRequests if not set.
OnLimitReached gin.HandlerFunc
// SkipFunc determines whether rate limiting should be skipped for a request.
// Returns true to bypass rate limiting (e.g. health checks, internal IPs).
SkipFunc func(*gin.Context) bool
}
Config holds the configuration for the RateLimiter middleware.
type Option ¶
type Option func(*Config)
Option is a functional option for configuring RateLimiterConfig.
func WithBurst ¶
WithBurst sets the maximum burst size (token bucket capacity). Non-positive values are ignored; the default (50) is used instead.
func WithKeyFunc ¶
WithKeyFunc sets the function used to extract a rate limit key from each request. A nil keyFunc is ignored; the default (client IP) is used instead.
func WithOnLimitReached ¶
func WithOnLimitReached(onLimitReached gin.HandlerFunc) Option
WithOnLimitReached sets a custom handler called when the rate limit is exceeded. The handler is responsible for writing the response; the default 429 response is skipped. A nil handler is ignored; the default CodeTooManyRequests response is used instead.
func WithRate ¶
WithRate sets the number of requests allowed per second. Non-positive values are ignored; the default (10 req/s) is used instead.
func WithSkipFunc ¶
WithSkipFunc sets a function that determines whether to skip rate limiting for a request. Returns true to bypass rate limiting (e.g. health check endpoints, internal IPs). A nil skipFunc is ignored.
Source Files