rate

Documentation

Index

• type Count
• type Limit
  • func NewLimit(o Options) Limit
  • func (l *Limit) Enforce(ctx context.Context, ctr *LimitCounter) error
  • func (l Limit) EnforceVar(ctx context.Context, s *sync.Map) error
  • func (l *Limit) GetCounters(s *sync.Map) *LimitCounter
  • func (l *Limit) IsZero() bool
  • func (l *Limit) OnExceed(lc *LimitCounter) (e RateError)
  • func (l *Limit) String() string
  • func (l *Limit) UnmarshalJSON(data []byte) error
  • func (l *Limit) UnmarshalText(text []byte) (err error)
  • func (l *Limit) UnmarshalYAML(node *yaml.Node) (err error)
• type LimitCounter
  • func (w *LimitCounter) Inc(subtick Subtick, limit Count) (ok bool)
  • func (w *LimitCounter) Read(subtick Subtick, limit Count) (count Count)
  • func (c *LimitCounter) Reset()
• type Limiter
  • func LocalLimiter(l Options) Limiter
  • func (l *Limiter) Enforce(ctx context.Context) error
  • func (l *Limiter) Read() Count
  • func (l *Limiter) Reset()
• type Options
• type Rate
  • func MustParse(s string) Rate
  • func Parse(s string) (Rate, error)
  • func (d Rate) Clamp(rateMin Rate, rateMax Rate) Rate
  • func (d Rate) ClampPeriod(pmin time.Duration, pmax time.Duration) Rate
  • func (d Rate) Compare(o Rate) int
  • func (d Rate) Faster(o Rate) bool
  • func (d Rate) Interval() time.Duration
  • func (d Rate) IsPositive() bool
  • func (d Rate) IsZero() bool
  • func (d Rate) MarshalJSON() ([]byte, error)
  • func (d Rate) MarshalText() ([]byte, error)
  • func (d Rate) MarshalYAML() (any, error)
  • func (d Rate) Rescale(period time.Duration) Rate
  • func (d Rate) Slower(o Rate) bool
  • func (d Rate) String() string
  • func (d *Rate) UnmarshalJSON(data []byte) error
  • func (d *Rate) UnmarshalText(text []byte) (err error)
  • func (d *Rate) UnmarshalYAML(node *yaml.Node) error
• type RateError
  • func (e RateError) AdviseClient(now time.Time) (retryAfter time.Time, ok bool)
  • func (e RateError) Error() string
• type Subtick
  • func Subticks(dur time.Duration) Subtick
  • func ToSubticks(time time.Time, dur time.Duration) Subtick
  • func (s Subtick) Carry(prev, limit Count) Count
  • func (s Subtick) Tick() Tick
• type Tick
  • func Ticks(dur time.Duration) Tick
  • func ToTicks(time time.Time, dur time.Duration) Tick

Types

type Count

type Count = uint32

type Limit

type Limit struct {
	Options
}

func NewLimit

func NewLimit(o Options) Limit

func (*Limit) Enforce

func (l *Limit) Enforce(ctx context.Context, ctr *LimitCounter) error

Enforces a limit given the context and counter.

func (Limit) EnforceVar

func (l Limit) EnforceVar(ctx context.Context, s *sync.Map) error

Enforces a limit given the context and sync.Map to store counters per client.

func (*Limit) GetCounters

func (l *Limit) GetCounters(s *sync.Map) *LimitCounter

Returns the counter for the given limit, creating it if necessary.

func (*Limit) IsZero

func (l *Limit) IsZero() bool

func (*Limit) OnExceed

func (l *Limit) OnExceed(lc *LimitCounter) (e RateError)

Returns the advisory error for exceeding the limit.

func (*Limit) String

func (l *Limit) String() string

func (*Limit) UnmarshalJSON

func (l *Limit) UnmarshalJSON(data []byte) error

func (*Limit) UnmarshalText

func (l *Limit) UnmarshalText(text []byte) (err error)

func (*Limit) UnmarshalYAML

func (l *Limit) UnmarshalYAML(node *yaml.Node) (err error)

type LimitCounter

type LimitCounter struct {
	// contains filtered or unexported fields
}

Limit context is a sliding window counter with backpressure, used to track the rate of events and the current wait queue length.

func (*LimitCounter) Inc

func (w *LimitCounter) Inc(subtick Subtick, limit Count) (ok bool)

func (*LimitCounter) Read

func (w *LimitCounter) Read(subtick Subtick, limit Count) (count Count)

func (*LimitCounter) Reset

func (c *LimitCounter) Reset()

type Limiter

type Limiter struct {
	Limit
	Counter *LimitCounter
}

Limiter is a rate limiter with its own local counter.

func LocalLimiter

func LocalLimiter(l Options) Limiter

func (*Limiter) Enforce

func (l *Limiter) Enforce(ctx context.Context) error

func (*Limiter) Read

func (l *Limiter) Read() Count

func (*Limiter) Reset

func (l *Limiter) Reset()

type Options

type Options struct {
	ID           string        `yaml:"id,omitempty"`          // Optional identifier.
	Rate         Rate          `yaml:"rate"`                  // The rate to enforce.
	Burst        int32         `yaml:"burst,omitempty"`       // The maximum burst size.
	BlockAfter   Rate          `yaml:"block_after,omitempty"` // The rate (of excessive requests) after which block duration is advised.
	BlockFor     util.Duration `yaml:"block_for,omitempty"`   // The duration to block the client.
	AdviseClient bool          `yaml:"advise,omitempty"`      // Whether to advise the client on the block duration.
}

Limit defines the options for a rate limiter.

type Rate

type Rate struct {
	Count  uint
	Period time.Duration
}

func MustParse

func MustParse(s string) Rate

func Parse

func Parse(s string) (Rate, error)

func (Rate) Clamp

func (d Rate) Clamp(rateMin Rate, rateMax Rate) Rate

func (Rate) ClampPeriod

func (d Rate) ClampPeriod(pmin time.Duration, pmax time.Duration) Rate

func (Rate) Compare

func (d Rate) Compare(o Rate) int

func (Rate) Faster

func (d Rate) Faster(o Rate) bool

func (Rate) Interval

func (d Rate) Interval() time.Duration

func (Rate) IsPositive

func (d Rate) IsPositive() bool

func (Rate) IsZero

func (d Rate) IsZero() bool

func (Rate) MarshalJSON

func (d Rate) MarshalJSON() ([]byte, error)

func (Rate) MarshalText

func (d Rate) MarshalText() ([]byte, error)

func (Rate) MarshalYAML

func (d Rate) MarshalYAML() (any, error)

func (Rate) Rescale

func (d Rate) Rescale(period time.Duration) Rate

func (Rate) Slower

func (d Rate) Slower(o Rate) bool

func (Rate) String

func (d Rate) String() string

func (*Rate) UnmarshalJSON

func (d *Rate) UnmarshalJSON(data []byte) error

func (*Rate) UnmarshalText

func (d *Rate) UnmarshalText(text []byte) (err error)

func (*Rate) UnmarshalYAML

func (d *Rate) UnmarshalYAML(node *yaml.Node) error

type RateError

type RateError struct {
	BlockUntil time.Duration // Advisory block duration to the server.
	RetryAfter time.Duration // Advisory retry duration to the client.
	NoHeader   bool          // Whether to suppress the Retry-After header.
}

func (RateError) AdviseClient

func (e RateError) AdviseClient(now time.Time) (retryAfter time.Time, ok bool)

func (RateError) Error

func (e RateError) Error() string

type Subtick

type Subtick uint64

func Subticks

func Subticks(dur time.Duration) Subtick

func ToSubticks

func ToSubticks(time time.Time, dur time.Duration) Subtick

func (Subtick) Carry

func (s Subtick) Carry(prev, limit Count) Count

func (Subtick) Tick

func (s Subtick) Tick() Tick

type Tick

type Tick Count

func Ticks

func Ticks(dur time.Duration) Tick

func ToTicks

func ToTicks(time time.Time, dur time.Duration) Tick