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

• type Cost
• type Enforcer
  • func NewEnforcer(m LimitManager, t Tracker, opts EnforcerOptions) Enforcer
  • func NoopEnforcer() Enforcer
• type EnforcerOptions
  • func NewEnforcerOptions() EnforcerOptions
• 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

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
}

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 {
	// SetCostExceededMessage sets the message appended to cost limit errors to provide
	// more context on the cost limit that was exceeded.
	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

	// SetValueBuckets sets the tally buckets used in histogram metrics.
	SetValueBuckets(val tally.ValueBuckets) EnforcerOptions

	// ValueBuckets returns the tally buckets used in histogram metrics.
	ValueBuckets() tally.ValueBuckets

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

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

EnforcerOptions provides a set of options for an enforcer.

func NewEnforcerOptions

func NewEnforcerOptions() EnforcerOptions

NewEnforcerOptions returns a new set of enforcer options.

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.