ratelimit

Documentation

Index

• type Listener
  • func NewListener(l net.Listener, rl *RateLimiter, logger zerolog.Logger) *Listener
  • func (l *Listener) Accept() (net.Conn, error)
• type RateLimitSource
• type RateLimiter
  • func NewRateLimiter(requestsPerSecond float64, burst int, logger zerolog.Logger) *RateLimiter
  • func NewRateLimiterWithConfig(requestsPerSecond float64, burst int, cleanupInterval, staleTTL time.Duration, ...) *RateLimiter
  • func NewRateLimiterWithContext(ctx context.Context, requestsPerSecond float64, burst int, ...) *RateLimiter
  • func NewRateLimiterWithContextAndConfig(ctx context.Context, requestsPerSecond float64, burst int, ...) *RateLimiter
  • func NewRateLimiterWithSource(source RateLimitSource, logger zerolog.Logger) *RateLimiter
  • func NewRateLimiterWithSourceAndConfig(source RateLimitSource, cleanupInterval, staleTTL time.Duration, ...) *RateLimiter
  • func NewRateLimiterWithSourceAndContext(ctx context.Context, source RateLimitSource, logger zerolog.Logger) *RateLimiter
  • func NewRateLimiterWithSourceContextAndConfig(ctx context.Context, source RateLimitSource, ...) *RateLimiter
  • func (rl *RateLimiter) Allow(principal string) bool
  • func (rl *RateLimiter) RetryAfter(principal string) time.Duration
  • func (rl *RateLimiter) Stop()
• type StaticRateLimitSource
  • func (s *StaticRateLimitSource) GetLimit(principal string) (float64, int, bool)

Types

type Listener

type Listener struct {
	net.Listener
	RateLimiter *RateLimiter
	Logger      zerolog.Logger
}

Listener is a network listener that enforces rate limiting on all incoming connections.

func NewListener

func NewListener(l net.Listener, rl *RateLimiter, logger zerolog.Logger) *Listener

NewListener creates a new rate-limiting listener.

func (*Listener) Accept

func (l *Listener) Accept() (net.Conn, error)

Accept waits for and returns the next connection to the listener. It checks each connection's source IP against the RateLimiter and closes it if the limit is exceeded.

type RateLimitSource

type RateLimitSource interface {
	// GetLimit returns the rate limits to apply for a principal.
	// If it returns ok=false, the default limits of the RateLimiter will be used.
	GetLimit(principal string) (requestsPerSecond float64, burst int, ok bool)
}

RateLimitSource defines the interface for determining rate limits.

type RateLimiter

type RateLimiter struct {

	// LimitSource provides dynamic rate limits per principal.
	LimitSource RateLimitSource
	// contains filtered or unexported fields
}

RateLimiter provides per-principal rate limiting. It tracks last-used time for each principal and cleans up stale limiters.

func NewRateLimiter

func NewRateLimiter(requestsPerSecond float64, burst int, logger zerolog.Logger) *RateLimiter

NewRateLimiter creates a new rate limiter with static limits. requestsPerSecond: allowed requests per second per principal burst: maximum burst size

func NewRateLimiterWithConfig

func NewRateLimiterWithConfig(requestsPerSecond float64, burst int, cleanupInterval, staleTTL time.Duration, logger zerolog.Logger) *RateLimiter

NewRateLimiterWithConfig creates a new rate limiter with custom configuration. requestsPerSecond: allowed requests per second per principal. burst: maximum burst size. cleanupInterval: how often stale limiter cleanup runs. staleTTL: how long a limiter can remain unused before it is considered stale and removed. logger: zerolog logger used for logging within the rate limiter.

func NewRateLimiterWithContext

func NewRateLimiterWithContext(ctx context.Context, requestsPerSecond float64, burst int, logger zerolog.Logger) *RateLimiter

NewRateLimiterWithContext creates a new rate limiter with static limits and a context. The rate limiter will stop its background cleanup when the context is cancelled. requestsPerSecond: allowed requests per second per principal burst: maximum burst size

func NewRateLimiterWithContextAndConfig

func NewRateLimiterWithContextAndConfig(ctx context.Context, requestsPerSecond float64, burst int, cleanupInterval, staleTTL time.Duration, logger zerolog.Logger) *RateLimiter

NewRateLimiterWithContextAndConfig creates a new rate limiter with custom configuration and a context. The rate limiter will stop its background cleanup when the context is cancelled. ctx: parent context for lifecycle management. requestsPerSecond: allowed requests per second per principal. burst: maximum burst size. cleanupInterval: how often stale limiter cleanup runs. staleTTL: how long a limiter can remain unused before it is considered stale and removed. logger: zerolog logger used for logging within the rate limiter.

func NewRateLimiterWithSource

func NewRateLimiterWithSource(source RateLimitSource, logger zerolog.Logger) *RateLimiter

NewRateLimiterWithSource creates a new rate limiter with a custom rate limit source.

func NewRateLimiterWithSourceAndConfig

func NewRateLimiterWithSourceAndConfig(source RateLimitSource, cleanupInterval, staleTTL time.Duration, logger zerolog.Logger) *RateLimiter

NewRateLimiterWithSourceAndConfig creates a new rate limiter with a custom rate limit source and configuration. source: provides dynamic rate limits per principal. cleanupInterval: how often stale limiter cleanup runs. staleTTL: how long a limiter can remain unused before it is considered stale and removed. logger: zerolog logger used for logging within the rate limiter. Note: This constructor does not set fallback requestsPerSecond and burst values. If the source returns ok=false for a principal, the rate limiter will use 0 for both, which will block all requests. Use NewRateLimiterWithConfig and set LimitSource if you need fallback limits.

func NewRateLimiterWithSourceAndContext

func NewRateLimiterWithSourceAndContext(ctx context.Context, source RateLimitSource, logger zerolog.Logger) *RateLimiter

NewRateLimiterWithSourceAndContext creates a new rate limiter with a custom rate limit source and a context. The rate limiter will stop its background cleanup when the context is cancelled.

func NewRateLimiterWithSourceContextAndConfig

func NewRateLimiterWithSourceContextAndConfig(ctx context.Context, source RateLimitSource, cleanupInterval, staleTTL time.Duration, logger zerolog.Logger) *RateLimiter

NewRateLimiterWithSourceContextAndConfig creates a new rate limiter with a custom rate limit source, context, and configuration. The rate limiter will stop its background cleanup when the context is cancelled. ctx: parent context for lifecycle management. source: provides dynamic rate limits per principal. cleanupInterval: how often stale limiter cleanup runs. staleTTL: how long a limiter can remain unused before it is considered stale and removed. logger: zerolog logger used for logging within the rate limiter. Note: This constructor does not set fallback requestsPerSecond and burst values. If the source returns ok=false for a principal, the rate limiter will use 0 for both, which will block all requests. Use NewRateLimiterWithContextAndConfig and set LimitSource if you need fallback limits.

func (*RateLimiter) Allow

func (rl *RateLimiter) Allow(principal string) bool

Allow checks if a request from the given principal is allowed.

func (*RateLimiter) RetryAfter

func (rl *RateLimiter) RetryAfter(principal string) time.Duration

RetryAfter returns the duration until the next request would be allowed for the given principal. This can be used to set the Retry-After header in HTTP responses. If the principal has no limiter entry (first request), it returns 0. Note: This method uses RLock because it only reads from the limiters map. The Reserve/Cancel calls on the underlying rate.Limiter are thread-safe due to rate.Limiter's internal mutex. This method is typically called immediately after Allow() returns false, so the limiter entry will exist. If rate limits change between calls, the returned duration reflects the current limits at the time of the Reserve() call, which is acceptable for advisory Retry-After headers.

func (*RateLimiter) Stop

func (rl *RateLimiter) Stop()

Stop gracefully stops the background cleanup goroutine. It should be called when the RateLimiter is no longer needed. Stop can be safely called multiple times. Note: When using context-based constructors (NewRateLimiterWithContext, etc.), calling Stop is not necessary as cleanup happens automatically when the context is cancelled. However, calling Stop after context cancellation is safe and will wait for cleanup to complete.

type StaticRateLimitSource

type StaticRateLimitSource struct {
	RequestsPerSecond float64
	Burst             int
}

StaticRateLimitSource is a simple implementation of RateLimitSource that returns fixed limits.

func (*StaticRateLimitSource) GetLimit

func (s *StaticRateLimitSource) GetLimit(principal string) (float64, int, bool)

GetLimit returns the fixed limits.