cost

Documentation

Overview

Package cost is a library providing utilities for estimating the cost of operations and enforcing limits on them. The primary type of interest is Enforcer, which tracks the cost of operations, and errors when that cost goes over a particular limit.

Index

• func NewCostExceededError(customMessage string, cost Cost, threshold Cost) error
• type Cost
• type Enforcer
  • func NewEnforcer(m LimitManager, t Tracker, opts EnforcerOptions) Enforcer
  • func NoopEnforcer() Enforcer
• type EnforcerOptions
  • func NewEnforcerOptions() EnforcerOptions
• type EnforcerReporter
  • func NoopEnforcerReporter() EnforcerReporter
• type Limit
• type LimitManager
  • func NewDynamicLimitManager(store kv.Store, kvLimitKey, kvEnabledKey string, opts LimitManagerOptions) (LimitManager, error)
  • func NewStaticLimitManager(opts LimitManagerOptions) LimitManager
• type LimitManagerOptions
  • func NewLimitManagerOptions() LimitManagerOptions
• type Report
• type Tracker
  • func NewNoopTracker() Tracker
  • func NewTracker() Tracker

Functions

func NewCostExceededError

func NewCostExceededError(customMessage string, cost Cost, threshold Cost) error

NewCostExceededError returns an error for going over an Enforcer's limit.

Types

type Cost

type Cost float64

Cost represents the cost of an operation.

type Enforcer

type Enforcer interface {
	Add(op Cost) Report
	State() (Report, Limit)
	Limit() Limit
	Clone() Enforcer
	Reporter() EnforcerReporter
}

Enforcer instances enforce cost limits for operations.

func NewEnforcer

func NewEnforcer(m LimitManager, t Tracker, opts EnforcerOptions) Enforcer

NewEnforcer returns a new enforcer for cost limits.

func NoopEnforcer

func NoopEnforcer() Enforcer

NoopEnforcer returns a new enforcer that always returns a current cost of 0 and

is always disabled.

type EnforcerOptions

type EnforcerOptions interface {
	// Reporter is the reporter which will be used on Enforcer events.
	Reporter() EnforcerReporter

	// SetReporter sets Reporter()
	SetReporter(r EnforcerReporter) EnforcerOptions

	// SetCostExceededMessage sets CostExceededMessage
	SetCostExceededMessage(val string) EnforcerOptions

	// CostExceededMessage returns the message appended to cost limit errors to provide
	// more context on the cost limit that was exceeded.
	CostExceededMessage() string
}

EnforcerOptions provides a set of options for an enforcer.

func NewEnforcerOptions

func NewEnforcerOptions() EnforcerOptions

NewEnforcerOptions returns a new set of enforcer options.

type EnforcerReporter

type EnforcerReporter interface {
	// ReportCost is called on every call to Enforcer#Add with the added cost
	ReportCost(c Cost)

	// ReportCurrent reports the current total on every call to Enforcer#Add
	ReportCurrent(c Cost)

	// ReportOverLimit is called every time an enforcer goes over its limit. enabled is true if the limit manager
	// says the limit is currently enabled.
	ReportOverLimit(enabled bool)
}

An EnforcerReporter is a listener for Enforcer events.

func NoopEnforcerReporter

func NoopEnforcerReporter() EnforcerReporter

NoopEnforcerReporter returns an EnforcerReporter which does nothing on all events.

type Limit

type Limit struct {
	Threshold Cost
	Enabled   bool
}

Limit encapulates the configuration of a cost limit for an operation.

type LimitManager

type LimitManager interface {
	// Limit returns the current cost limit for an operation.
	Limit() Limit

	// Report reports metrics on the state of the manager.
	Report()

	// Close closes the manager.
	Close()
}

LimitManager manages configuration of a cost limit for an operation.

func NewDynamicLimitManager

func NewDynamicLimitManager(
	store kv.Store,
	kvLimitKey, kvEnabledKey string,
	opts LimitManagerOptions,
) (LimitManager, error)

NewDynamicLimitManager returns a new LimitWatcher which watches for updates to the cost limit of an operation in KV.

func NewStaticLimitManager

func NewStaticLimitManager(opts LimitManagerOptions) LimitManager

NewStaticLimitManager returns a new LimitManager which always returns the same limit.

type LimitManagerOptions

type LimitManagerOptions interface {
	// SetDefaultLimit sets the default limit for the manager.
	SetDefaultLimit(val Limit) LimitManagerOptions

	// DefaultLimit returns the default limit for the manager.
	DefaultLimit() Limit

	// SetValidateLimitFn sets the validation function applied to updates to the cost limit.
	SetValidateLimitFn(val util.ValidateFn) LimitManagerOptions

	// ValidateLimitFn returns the validation function applied to updates to the cost limit.
	ValidateLimitFn() util.ValidateFn

	// SetInstrumentOptions sets the instrument options.
	SetInstrumentOptions(val instrument.Options) LimitManagerOptions

	// InstrumentOptions returns the instrument options.
	InstrumentOptions() instrument.Options
}

LimitManagerOptions provides a set of options for a LimitManager.

func NewLimitManagerOptions

func NewLimitManagerOptions() LimitManagerOptions

NewLimitManagerOptions returns a new set of LimitManager options.

type Report

type Report struct {
	Cost
	Error error
}

Report is a report on the cost limits of an enforcer.

type Tracker

type Tracker interface {
	// Add adds c to the tracker's current cost total and returns the new total.
	Add(c Cost) Cost

	// Current returns the tracker's current cost total.
	Current() Cost
}

Tracker tracks the cost of operations seen so far.

func NewNoopTracker

func NewNoopTracker() Tracker

NewNoopTracker returns a tracker which always always returns a cost of 0.

func NewTracker

func NewTracker() Tracker

NewTracker returns a new Tracker which maintains a simple running total of all the costs it has seen so far.