limit

README

Limit

Package limit provides rate limiting policies.

It was inspired by retry and rate.

Documentation

Overview

Package limit provides rate limiting policies.

Index

• Variables
• func Do(ctx context.Context, policy Policy, fn func() error) (err error)
• func DoValue[T any](ctx context.Context, policy Policy, fn func() (T, error)) (value T, err error)
• type MaxConcurrentOption
  • func WithMaxConcurrentObserver(observer Observer) MaxConcurrentOption
• type Observer
• type Policy
  • func AllowAll() Policy
  • func MaxConcurrent(n int, options ...MaxConcurrentOption) Policy
  • func RejectAll() Policy
  • func SerialPolicy(policies ...Policy) Policy
  • func TokenBucket(size int, rate Rate, options ...TokenBucketOption) Policy
• type Rate
  • func Every(interval time.Duration) Rate
• type TokenBucketOption
  • func WithTokenBucketObserver(observer Observer) TokenBucketOption

Variables

var (
	// ErrRejected signals that the operation was rejected by the Policy.
	ErrRejected = errors.New("limit: operation rejected")

	// ErrAbandoned signals that the operation was abandoned after being allowed by the Policy.
	ErrAbandoned = errors.New("limit: operation abandoned")
)

Functions

func Do

func Do(ctx context.Context, policy Policy, fn func() error) (err error)

Do executes the function according to the given policy.

func DoValue

func DoValue[T any](ctx context.Context, policy Policy, fn func() (T, error)) (value T, err error)

DoValue executes the function according to the given policy and returns the results.

Types

type MaxConcurrentOption

type MaxConcurrentOption interface {
	// contains filtered or unexported methods
}

A MaxConcurrentOption provides optional configuration for a MaxConcurrent Policy.

func WithMaxConcurrentObserver

func WithMaxConcurrentObserver(observer Observer) MaxConcurrentOption

WithMaxConcurrentObserver returns a MaxConcurrentOption that sets an Observer.

type Observer

type Observer interface {
	// ObserveAllow is called when an operation is allowed.
	ObserveAllow(wait time.Duration)
	// ObserveReport is called when the result of an operation is reported.
	ObserveReport(latency time.Duration, err error)

	// ObserveEnqueue is called when an operation can't currently be allowed
	// and is parked until it's allowed or canceled in the future.
	ObserveEnqueue()
	// ObserveDequeue allow is called when an operation is unparked
	// due to being allowed or canceled.
	ObserveDequeue()

	// ObserveCancel is called when an operation is canceled.
	ObserveCancel()
	// ObserveReject is called when an operation is rejected.
	ObserveReject()
}

An Observer observes operation events.

type Policy

type Policy interface {
	// Allow returns a value indicating if an operation is currently allowed.
	// If it is allowed, Report must be called with the operation's results.
	Allow() bool

	// Wait waits until an operation is allowed according to the policy.
	// It returns an error if ctx is done or the Policy rejects the operation.
	//
	// If an error is not returned, Report must be called with the results of
	// the operation.
	//
	// If ctx has a deadline and the policy provides a scheduled operation time
	// after the deadline, it may return context.DeadlineExceeded preemptively.
	Wait(ctx context.Context) error

	// Report must be called with the results of an operation after it is allowed.
	// Use ErrAbandoned to signal that the operation was abandoned after being allowed.
	Report(latency time.Duration, err error)
}

A Policy is a policy for limiting operations.

func AllowAll

func AllowAll() Policy

AllowAll returns a Policy that never waits.

func MaxConcurrent

func MaxConcurrent(n int, options ...MaxConcurrentOption) Policy

MaxConcurrent returns a Policy that limits the maximum concurrent operations to n. It provides no fairness guarantees.

func RejectAll

func RejectAll() Policy

RejectAll returns a Policy that rejects everything.

func SerialPolicy

func SerialPolicy(policies ...Policy) Policy

SerialPolicy returns a Policy that serially combines the policies in the given order.

func TokenBucket

func TokenBucket(size int, rate Rate, options ...TokenBucketOption) Policy

TokenBucket returns a token bucket Policy with the given bucket size and refill rate.

type Rate

type Rate float64

Rate defines a frequency as number of operations per second.

func Every

func Every(interval time.Duration) Rate

Every converts a time interval between operations to a Rate.

type TokenBucketOption

type TokenBucketOption interface {
	// contains filtered or unexported methods
}

A TokenBucketOption provides optional configuration for a TokenBucket Policy.

func WithTokenBucketObserver

func WithTokenBucketObserver(observer Observer) TokenBucketOption

WithTokenBucketObserver returns a TokenBucketOption that sets an Observer.