budget

package
v0.15.2 Latest Latest
Warning

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

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package budget bounds how often the bot will answer.

Spec 0019 D19. It is a spend control wearing a count: the bot answers when mentioned, anyone on a public server can mention it, and each answer is a model call somebody pays for. Nothing else bounds that.

Global rather than per-actor, deliberately. A global budget needs no identity keying, no store and no eviction, and it bounds the blast radius of every scenario including the ones nobody has thought of. What it gives up is fairness: one abuser takes the bot away from everybody, and that is the condition that promotes a per-actor cap from the spec's Not yet specified.

Index

Constants

View Source
const DefaultWindow = time.Hour

DefaultWindow is the window the answer budget is denominated in: answers per hour, the unit an operator can reason about without a pricing table and the bot can explain in the channel when it declines (0019 D19).

Variables

View Source
var (
	// ErrNonPositiveLimit is returned for a limit of zero or less. Refused
	// rather than interpreted: it reads as "never answer" or "unlimited"
	// depending on who is reading, and both are reachable by typo.
	ErrNonPositiveLimit = errors.NewSentinel("budget.non_positive_limit",
		"budget: the limit must be positive")

	// ErrNonPositiveWindow is returned for a window of zero or less, which
	// would put every answer outside the window and so allow all of them.
	ErrNonPositiveWindow = errors.NewSentinel("budget.non_positive_window",
		"budget: the window must be positive")
)

Configuration errors.

Functions

This section is empty.

Types

type Budget

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

Budget allows a bounded number of answers in a sliding window.

func New

func New(limit int, window time.Duration, opts ...Option) (*Budget, error)

New builds a Budget of limit answers per window.

func (*Budget) Allow

func (b *Budget) Allow() bool

Allow reports whether an answer may be given, and records it when it may.

One call rather than a check and a separate spend: two callers that both asked before either recorded would both be told yes, which is the bug this exists to prevent.

func (*Budget) Limit

func (b *Budget) Limit() int

Limit is the configured ceiling, for a caller that wants to say what it is.

func (*Budget) Remaining

func (b *Budget) Remaining() int

Remaining is how many answers are left in the window now.

func (*Budget) Window

func (b *Budget) Window() time.Duration

Window is the configured window, for the same reason.

type Option

type Option func(*Budget)

Option configures a Budget.

func WithClock

func WithClock(now func() time.Time) Option

WithClock sets the clock, so a test can wind it by hand.

Injected rather than a package-level var a test swaps: that races under t.Parallel, and this type is reached from a subscriber goroutine.

Jump to

Keyboard shortcuts

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