local_limit

README

Local Limit

Local Limit is a rate limiter that works on instance level. It is not intended to limit the global request rate to numerous instances of a service. This can be achieved using a somehow synchronized rate limiting algorithm, e.g. via a redis.

Local Limit allows a certain number of requests (called drops here) per second to pass. Inside, it uses a dripping like algorithm to add possible requests to a queue. Drops are added in certain intervals. Drop rates less than one per second are possible, as fractional drops are stored for the next iteration.

Every incoming request takes one (whole) drop out of the queue of drops, until it is empty. If there a no drops available, a request waits for an arbitrary time for a new drop. If none arrives, the request is rejected.

Drops can accumulate to a specified maximum. So services will not be overwhelmed if after a longer period without requests, the requests start again.

As there is an internal go routing caring to add the drops, a Stop() function is provided to gracefully shut the limiter down. This shutdown is asynchronous and will occur in the next iteration for the drops.

Example

limiter := util.Must(New(
    WithTargetRate(v.TargetRate),
    WithDefaultSleepInterval(v.SleepTime)))

if limiter.Limit() {
    doWork()
}

Documentation

Index

• func WithDropTimeout(d time.Duration) func(l *LocalLimit) error
• func WithMaxDropsAbsolute(d int64) func(l *LocalLimit) error
• func WithMaxDropsInterval(d time.Duration) func(l *LocalLimit) error
• func WithSleepInterval(i time.Duration) func(l *LocalLimit) error
• func WithTargetRate(r float64) func(l *LocalLimit) error
• type LocalLimit
  • func New(options ...func(*LocalLimit) error) (*LocalLimit, error)
  • func (l *LocalLimit) Limit() bool
  • func (l *LocalLimit) Stop()

Functions

func WithDropTimeout

func WithDropTimeout(d time.Duration) func(l *LocalLimit) error

WithDropTimeout sets the timeout a process calling Limit will wait, before giving up to get a drop.

func WithMaxDropsAbsolute

func WithMaxDropsAbsolute(d int64) func(l *LocalLimit) error

WithMaxDropsAbsolute sets the maximum number of drops to be stored before dismissing them. This is to save the server from a flood of requests after a longer period of no requests.

func WithMaxDropsInterval

func WithMaxDropsInterval(d time.Duration) func(l *LocalLimit) error

WithMaxDropsInterval sets the maximum number of drops to be stored before dismissing them. Other than WithMaxDropsAbsolute it calculates the number of drops to store depending on the TargetRate parameter. This methods must be called after setting the TargetRate. Otherwise the defaults are used.

func WithSleepInterval

func WithSleepInterval(i time.Duration) func(l *LocalLimit) error

WithSleepInterval sets the interval for the drop generator in which new drops are generated. New drops are generated for the last passed interval. Fractional drops are stored to be used in the next iteration.

func WithTargetRate

func WithTargetRate(r float64) func(l *LocalLimit) error

WithTargetRate sets the requested rate of drops per second.

Types

type LocalLimit

type LocalLimit struct {
	// TargetRate is the maximum desired request rate per second
	TargetRate float64

	// DropTimeout is the time a request waits for a drop,
	// if there are no drops currently available in the drops channel.
	DropTimeout time.Duration

	// MaxDrops specifies the maximum number of drops in the drops channel.
	// Setting the maximum prevents services from being flooded after a longer
	// period without requests.
	MaxDrops int64

	// SleepInterval is the time between the generation of drops
	SleepInterval time.Duration
	// contains filtered or unexported fields
}

LocalLimit is a instance local request limiter.

func New

func New(options ...func(*LocalLimit) error) (*LocalLimit, error)

New creates a new local rate limiter.

func (*LocalLimit) Limit

func (l *LocalLimit) Limit() bool

Limit gives true, if the rate limit is not yet exceeded, otherwise false. If there are currently no drops to exhaust, it will wait the configured DropTimeout for a drop.

func (*LocalLimit) Stop

func (l *LocalLimit) Stop()

Stop sets the stop marker, so the drop generator can stop eventually.