ratelimit

package
v1.0.3 Latest Latest
Warning

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

Go to latest
Published: Aug 11, 2026 License: AGPL-3.0 Imports: 8 Imported by: 0

Documentation

Overview

Package ratelimit owns fixed-window rate-limit state and persistence.

Index

Constants

View Source
const (
	// StorageSchemaVersion identifies the only rate-limit schema.
	StorageSchemaVersion = 1
	// StoragePrefix is the rate-limit v1 namespace.
	StoragePrefix = "ratelimit:v1:subject:"
)

Variables

View Source
var (
	// ErrRepositoryRequired reports an absent rate-limit storage adapter.
	ErrRepositoryRequired = errors.New("rate-limit storage is required")
	// ErrInvalidSubject reports an empty rate-limit identity.
	ErrInvalidSubject = errors.New("rate-limit subject is required")
	// ErrInvalidLimit reports a non-positive request limit.
	ErrInvalidLimit = errors.New("rate-limit limit must be positive")
	// ErrInvalidWindow reports a non-positive limit window.
	ErrInvalidWindow = errors.New("rate-limit window must be positive")
	// ErrConflict reports exhausted compare-and-swap attempts.
	ErrConflict = errors.New("rate-limit update conflict")
	// ErrCorruptRecord reports invalid durable rate-limit data.
	ErrCorruptRecord = errors.New("rate-limit record is invalid")
	// ErrInvalidCapacity reports a non-positive token-bucket capacity.
	ErrInvalidCapacity = errors.New("rate-limit capacity must be positive")
	// ErrInvalidRefillRate reports a non-positive token refill rate.
	ErrInvalidRefillRate = errors.New("rate-limit refill rate must be positive")
	// ErrInvalidTokens reports a token count outside bucket capacity.
	ErrInvalidTokens = errors.New("rate-limit tokens are outside capacity")
)

Functions

This section is empty.

Types

type Clock

type Clock interface {
	Now() time.Time
}

Clock supplies deterministic repository time.

type Decision

type Decision struct {
	Allowed   bool
	Limit     int64
	Count     int64
	Remaining int64
	ResetAt   time.Time
}

Decision is one atomic fixed-window consumption result.

type Repository

type Repository interface {
	Consume(context.Context, string, int64, time.Duration) (Decision, error)
}

Repository is the atomic rate-limit contract.

func Open

func Open(store storage.KVStore, clock Clock) (Repository, error)

Open returns a storage-backed fixed-window repository.

type TokenBucket

type TokenBucket struct {
	Tokens     float64   `json:"tokens"`
	Capacity   float64   `json:"capacity"`
	RefillRate float64   `json:"refill_rate"`
	LastRefill time.Time `json:"last_refill"`
}

TokenBucket is one in-memory token-bucket state value.

func (*TokenBucket) RefillAt

func (b *TokenBucket) RefillAt(now time.Time)

RefillAt applies elapsed refill at a deterministic time.

func (*TokenBucket) TryConsumeAt

func (b *TokenBucket) TryConsumeAt(tokens float64, now time.Time) bool

TryConsumeAt refills and consumes tokens at a deterministic time.

func (TokenBucket) Validate

func (b TokenBucket) Validate() error

Validate checks token-bucket invariants.

Jump to

Keyboard shortcuts

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