README
¶
rlzone
Generic rate limit by key using sliding window algorithm. See Cloudflare blog for details: https://blog.cloudflare.com/counting-things-a-lot-of-different-things/
Example
package main
import (
"fmt"
"log"
"time"
"github.com/Snawoot/rlzone"
)
func main() {
rl, err := rlzone.NewSmallest[string](1*time.Minute, 5)
if err != nil {
log.Fatalf("unable to create ratelimit instance: %v", err)
}
for i := 0; i < 6; i++ {
fmt.Println(rl.Allow("user1"))
}
fmt.Println(rl.Allow("user2"))
// Output:
// true
// true
// true
// true
// true
// false
// true
}
Documentation
¶
Overview ¶
Generic rate limit by key using sliding window algorithm.
Index ¶
- type CounterValue
- type RatelimitZone
- func (z *RatelimitZone[K, V]) Allow(key K) bool
- func (z *RatelimitZone[K, V]) AllowN(key K, n uint64) bool
- func (z *RatelimitZone[K, V]) GetWindowValue(key K) float64
- func (z *RatelimitZone[K, V]) Limit() uint64
- func (z *RatelimitZone[K, V]) String() string
- func (z *RatelimitZone[K, V]) Window() time.Duration
- type Ratelimiter
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CounterValue ¶
CounterValue is a type constraint for unsigned integer values of counter.
type RatelimitZone ¶
type RatelimitZone[K comparable, V CounterValue] struct { // contains filtered or unexported fields }
RatelimitZone controls how frequently events are allowed to happen. It implements sliding window of duration `window`, allowing approximately `limit` events within that time frame.
A RatelimitZone is safe for concurrent use by multiple goroutines.
func New ¶
func New[K comparable, V CounterValue](window time.Duration, limit V) (*RatelimitZone[K, V], error)
New creates new RatelimitZone with key type K and counter type V. It will allow approximately `limit` events within `window` time frame.
func (*RatelimitZone[K, V]) Allow ¶
func (z *RatelimitZone[K, V]) Allow(key K) bool
Allow reports whether an event generated by `key` may happen now.
func (*RatelimitZone[K, V]) AllowN ¶
func (z *RatelimitZone[K, V]) AllowN(key K, n uint64) bool
AllowN reports whether `n` events generated by `key` may happen now.
func (*RatelimitZone[K, V]) GetWindowValue ¶
func (z *RatelimitZone[K, V]) GetWindowValue(key K) float64
GetWindowValue returns estimation how many events happend for a `key` within sliding time window.
func (*RatelimitZone[K, V]) Limit ¶ added in v0.2.0
func (z *RatelimitZone[K, V]) Limit() uint64
Limit method returns limit setting of rate limiter
func (*RatelimitZone[K, V]) String ¶ added in v0.2.0
func (z *RatelimitZone[K, V]) String() string
String method formats rate limit parameters into a string, compatible with format accepted by FromString function
func (*RatelimitZone[K, V]) Window ¶ added in v0.2.0
func (z *RatelimitZone[K, V]) Window() time.Duration
Window method returns limit setting of rate limiter
type Ratelimiter ¶
type Ratelimiter[K comparable] interface { Allow(key K) bool AllowN(key K, n uint64) bool GetWindowValue(key K) float64 String() string Limit() uint64 Window() time.Duration }
Ratelimit is a generic interface for specific key type, but for any uint counter size.
func FromString ¶
func FromString[K comparable](limiterSpec string) (Ratelimiter[K], error)
FromString creates a new rate limiter from string specification <limit>/<duration>. E.g. "100/20m" corresponds to 100 allowed events in 20 minutes sliding time window.
See https://pkg.golang.ir/time#ParseDuration for reference of duration format.
func Must ¶
func Must[K comparable](rl Ratelimiter[K], err error) Ratelimiter[K]
Must is a helper that wraps a call to a function returning (Ratelimiter[K], error) and panics if the error is non-nil. It is intended for use in rate limiter initializations such as
rl := Must(New[string](1*Second, 10))
func NewSmallest ¶
func NewSmallest[K comparable](window time.Duration, limit uint64) (Ratelimiter[K], error)
NewSmallest creates a new rate limiter with counter type wide enough to fit limit value.
Source Files