ratelimit

package
v0.6.1000-dev.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 29, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package ratelimit is the shared in-memory token-bucket store behind the quotas: the API rate classes, the per-org webhook delivery rate, and the per-repo git push budget.

This is the single-node store — correct on one node, approximate across replicas, since each process keeps its own buckets. A Redis-backed store can replace it behind the same Allow signature on multi-node hosting. Where that approximation matters (an N-replica deployment grants roughly N× the budget), the call site says so.

Index

Constants

View Source
const DefaultIdleTTL = 2 * time.Hour

DefaultIdleTTL is how long an untouched bucket is kept.

It must be at least as long as the widest window any caller enforces. A bucket evicted early is recreated full, which would let a caller reset a budget by going quiet — for a 60-per-hour quota, a 30-minute TTL would hand back a full budget after a 30-minute pause. At or beyond the window the eviction is harmless, because a bucket idle that long has refilled anyway.

Variables

This section is empty.

Functions

func PerHour

func PerHour(n int) rate.Limit

PerHour converts an hourly budget to a rate.Limit.

func PerMinute

func PerMinute(n int) rate.Limit

PerMinute converts a per-minute budget to a rate.Limit.

func PerSecond

func PerSecond(n float64) rate.Limit

PerSecond converts a per-second budget to a rate.Limit.

Types

type Buckets

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

Buckets is a keyed set of token buckets with idle eviction.

func New

func New(idleTTL time.Duration) *Buckets

New creates a bucket store and starts its garbage collector. Call Close to stop it: the goroutine holds a reference to every bucket, so a store that is created per server and never closed leaks both the goroutine and the map.

func (*Buckets) Allow

func (b *Buckets) Allow(class, key string, lim rate.Limit, burst int) Result

Allow checks and consumes one token for the class+key pair. Both the decision and the reported numbers come from the same locked read, so the headers can never describe a different moment than the decision they accompany.

func (*Buckets) AllowN

func (b *Buckets) AllowN(class, key string, lim rate.Limit, burst int, n int) Result

AllowN consumes n tokens.

func (*Buckets) Close

func (b *Buckets) Close() error

Close stops the garbage collector. Safe to call more than once, and safe on a nil receiver.

func (*Buckets) Len

func (b *Buckets) Len() int

Len reports how many buckets are held (tests, and a cheap leak check).

type Result

type Result struct {
	OK bool
	// Limit is the burst budget for the class (the quota the headers describe).
	Limit int
	// Remaining is the whole tokens left after this request.
	Remaining int
	// Reset is how long until at least one more token exists.
	Reset time.Duration
}

Result is one decision plus the numbers the RateLimit-* headers report.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL