costbudget

package

v1.0.2 Latest Latest Go to latest Published: Nov 13, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/GLINCKER/levelrail

Links

Open Source Insights

Documentation ¶

Overview ¶

Package costbudget holds named monthly budgets scoped to a project, tag or app, and the level-triggered state machine that decides which alert thresholds fired and whether the 100 percent action is in force. It is pure arithmetic: usage, persistence and effects live with the callers.

Index ¶

Constants
Variables
func Pct(spent, monthly float64) float64
func Period(t time.Time) string
type Breach
- func BreachFor(b Budget, st State, currency string) (Breach, bool)
type Budget
- func (b Budget) Normalize() Budget
- func (b Budget) Validate() error
type Result
- func Step(b Budget, prev State, hadPrev bool, now time.Time, spent float64, ...) Result
type State

Constants ¶

View Source

const (
	ScopeProject = "project"
	ScopeTag     = "tag"
	ScopeApp     = "app"
)

Scope kinds a budget can cover.

View Source

const MaxThresholds = 8

MaxThresholds bounds the alert levels of one budget.

Variables ¶

View Source

var DefaultThresholds = spendcap.DefaultThresholds

DefaultThresholds are the alert levels, in percent of the monthly amount.

View Source

var ErrNotFound = errors.New("costbudget: not found")

ErrNotFound is returned when a budget id matches nothing.

Functions ¶

func Pct ¶

func Pct(spent, monthly float64) float64

Pct returns spent as a percent of the monthly amount.

func Period ¶

func Period(t time.Time) string

Period is the budget period key (UTC month) for t.

Types ¶

type Breach ¶

type Breach struct {
	Key  string
	Text string
}

Breach is one fired threshold, keyed so a new level notifies again.

func BreachFor ¶

func BreachFor(b Budget, st State, currency string) (Breach, bool)

BreachFor describes the highest threshold a budget crossed this period.

type Budget ¶

type Budget struct {
	ID          string  `json:"id"`
	Name        string  `json:"name"`
	Scope       string  `json:"scope"`
	ScopeValue  string  `json:"scope_value"`
	Monthly     float64 `json:"monthly"`
	Thresholds  []int   `json:"thresholds"`
	Action      string  `json:"action"`
	ThrottleRPS int     `json:"throttle_rps"`
	GuardMode   string  `json:"guard_mode"`
}

Budget is one named monthly limit. Action is applied while spend is at or above 100 percent and reuses the spend cap actions, so nothing new can be destructive.

func (Budget) Normalize ¶

func (b Budget) Normalize() Budget

Normalize fills defaults and returns the budget ready to validate or store.

func (Budget) Validate ¶

func (b Budget) Validate() error

Validate rejects a budget the ticker could not act on sensibly.

type Result ¶

type Result struct {
	State    State
	Fired    []int
	Rollover bool
	Changed  bool
}

Result is one Step outcome.

func Step ¶

func Step(b Budget, prev State, hadPrev bool, now time.Time, spent float64, apps []string) Result

Step derives the next state from the previous one and current spend. A threshold fires once per period: only levels above the stored highest fire. Enforcement is level-triggered, so raising the budget lifts it again. Apps are the resolved members of the scope, recorded while enforced.

type State ¶

type State struct {
	BudgetID     string    `json:"budget_id"`
	Period       string    `json:"period"`
	Highest      int       `json:"highest"`
	Pct          float64   `json:"pct"`
	Spent        float64   `json:"spent"`
	Enforced     string    `json:"enforced"`
	EnforcedApps []string  `json:"enforced_apps"`
	UpdatedAt    time.Time `json:"updated_at"`
}

State is what the ticker last decided for a budget in a period.

Source Files ¶

View all Source files

costbudget.go

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