quota

Documentation

Overview

Package quota defines Trillian's Quota Management service.

The objective of the quota service is to protect Trillian from traffic peaks, rejecting requests that may put servers out of capacity or indirectly cause MMDs (maximum merge delays) to be missed.

Each Trillian request, be it either a read or write request, requires certain tokens to be allowed to continue. Tokens exist at multiple layers: per-user, per-tree and global tokens. For example, a TrillianLog.QueueLeaves request consumes a Write token from User, Tree and Global quotas. If any of those quotas is out of tokens, the request is denied with a ResourceExhausted error code.

Tokens are replenished according to each implementation. For example, User tokens may replenish over time, whereas {Write, Tree} tokens may replenish as sequencing happens. Implementations are free to ignore (effectively whitelisting) certain specs of tokens (e.g., only support Global and ignore User and Tree tokens).

Quota users are defined according to each implementation. Note that quota users don't need to match authentication/authorization users; implementations are allowed their own representation of users.

Package quota is a generated GoMock package.

Index

• Constants
• Variables
• func InitMetrics(mf monitoring.MetricFactory)
• func RegisterProvider(name string, qp NewManagerFunc) error
• type Group
  • func (i Group) String() string
• type Kind
  • func (i Kind) String() string
• type Manager
  • func NewManager(name string) (Manager, error)
  • func NewManagerFromFlags() (Manager, error)
  • func Noop() Manager
• type MockManager
  • func NewMockManager(ctrl *gomock.Controller) *MockManager
  • func (m *MockManager) EXPECT() *MockManagerMockRecorder
  • func (m *MockManager) GetTokens(arg0 context.Context, arg1 int, arg2 []Spec) error
  • func (m *MockManager) PeekTokens(arg0 context.Context, arg1 []Spec) (map[Spec]int, error)
  • func (m *MockManager) PutTokens(arg0 context.Context, arg1 int, arg2 []Spec) error
  • func (m *MockManager) ResetQuota(arg0 context.Context, arg1 []Spec) error
• type MockManagerMockRecorder
  • func (mr *MockManagerMockRecorder) GetTokens(arg0, arg1, arg2 interface{}) *gomock.Call
  • func (mr *MockManagerMockRecorder) PeekTokens(arg0, arg1 interface{}) *gomock.Call
  • func (mr *MockManagerMockRecorder) PutTokens(arg0, arg1, arg2 interface{}) *gomock.Call
  • func (mr *MockManagerMockRecorder) ResetQuota(arg0, arg1 interface{}) *gomock.Call
• type NewManagerFunc
• type Spec
  • func (s Spec) Name() string
  • func (s Spec) String() string

Constants

const MaxTokens = int(^uint(0) >> 1) // MaxInt

MaxTokens is the maximum number of available tokens a quota may have.

Variables

var (

	// Metrics groups all quota-related metrics.
	// The metrics represented here are not meant to be maintained by the quota subsystem
	// implementation.  Instead, they're meant to be updated by the quota's callers, in order to
	// record their interactions with quotas.
	// The quota implementation is encouraged to define its own metrics to monitor its internal
	// state.
	Metrics = &m{}
)

var (
	// System is a flag specifying which quota system is in use.
	// TODO(RJPercival): Only the "noop" quota system is guaranteed to be
	// present, so should default to that.
	System = flag.String("quota_system", "mysql", fmt.Sprintf("Quota system to use. One of: %v", quotaSystems()))
)

Functions

func InitMetrics

func InitMetrics(mf monitoring.MetricFactory)

InitMetrics initializes Metrics using mf to create the monitoring objects. May be called multiple times. If so, the first call is the one that counts.

func RegisterProvider

func RegisterProvider(name string, qp NewManagerFunc) error

RegisterProvider registers a function that provides Manager instances.

Types

type Group

type Group int

Group represents the scope of a token (Global, Tree or User).

const (
	// Global is the Trillian-wide token scope (applies to all users and trees).
	// A global quota shortage for a certain kind of token means all requests of that kind will
	// be denied until the quota is replenished.
	Global Group = iota

	// Tree is the tree-wide token scope.
	Tree

	// User is the per-user token scope.
	// Users are defined according to each implementation.
	User
)

func (Group) String

func (i Group) String() string

type Kind

type Kind int

Kind represents the purpose of each token (Read or Write).

const (
	// Read represents tokens used by non-modifying RPCs.
	Read Kind = iota

	// Write represents tokens used by modifying RPCs.
	Write
)

func (Kind) String

func (i Kind) String() string

type Manager

type Manager interface {
	// GetTokens acquires numTokens from all specs. Tokens are taken in the order specified by
	// specs.
	// Returns error if numTokens could not be acquired for all specs.
	GetTokens(ctx context.Context, numTokens int, specs []Spec) error

	// PeekTokens returns how many tokens are available for each spec, without acquiring any.
	// Infinite quotas should return MaxTokens.
	PeekTokens(ctx context.Context, specs []Spec) (map[Spec]int, error)

	// PutTokens adds numTokens for all specs.
	PutTokens(ctx context.Context, numTokens int, specs []Spec) error

	// ResetQuota resets the quota for all specs.
	ResetQuota(ctx context.Context, specs []Spec) error
}

Manager is the component responsible for the management of tokens.

func NewManager

func NewManager(name string) (Manager, error)

NewManager returns a Manager implementation.

func NewManagerFromFlags

func NewManagerFromFlags() (Manager, error)

NewManagerFromFlags returns a Manager implementation as speficied by flag.

func Noop

func Noop() Manager

Noop returns a noop implementation of Manager. It allows all requests without restriction.

type MockManager

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

MockManager is a mock of Manager interface

func NewMockManager

func NewMockManager(ctrl *gomock.Controller) *MockManager

NewMockManager creates a new mock instance

func (*MockManager) EXPECT

func (m *MockManager) EXPECT() *MockManagerMockRecorder

EXPECT returns an object that allows the caller to indicate expected use

func (*MockManager) GetTokens

func (m *MockManager) GetTokens(arg0 context.Context, arg1 int, arg2 []Spec) error

GetTokens mocks base method

func (*MockManager) PeekTokens

func (m *MockManager) PeekTokens(arg0 context.Context, arg1 []Spec) (map[Spec]int, error)

PeekTokens mocks base method

func (*MockManager) PutTokens

func (m *MockManager) PutTokens(arg0 context.Context, arg1 int, arg2 []Spec) error

PutTokens mocks base method

func (*MockManager) ResetQuota

func (m *MockManager) ResetQuota(arg0 context.Context, arg1 []Spec) error

ResetQuota mocks base method

type MockManagerMockRecorder

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

MockManagerMockRecorder is the mock recorder for MockManager

func (*MockManagerMockRecorder) GetTokens

func (mr *MockManagerMockRecorder) GetTokens(arg0, arg1, arg2 interface{}) *gomock.Call

GetTokens indicates an expected call of GetTokens

func (*MockManagerMockRecorder) PeekTokens

func (mr *MockManagerMockRecorder) PeekTokens(arg0, arg1 interface{}) *gomock.Call

PeekTokens indicates an expected call of PeekTokens

func (*MockManagerMockRecorder) PutTokens

func (mr *MockManagerMockRecorder) PutTokens(arg0, arg1, arg2 interface{}) *gomock.Call

PutTokens indicates an expected call of PutTokens

func (*MockManagerMockRecorder) ResetQuota

func (mr *MockManagerMockRecorder) ResetQuota(arg0, arg1 interface{}) *gomock.Call

ResetQuota indicates an expected call of ResetQuota

type NewManagerFunc

type NewManagerFunc func() (Manager, error)

NewManagerFunc is the signature of a function which can be registered to provide instances of a quota manager.

type Spec

type Spec struct {
	// Group of the spec.
	Group

	// Kind of the spec.
	Kind

	// TreeID identifies the tree for specs of the Tree group.
	// Not used for other specs.
	TreeID int64

	// User identifies the user for specs of the User group.
	// Not used for other specs.
	User string

	// Refundable indicates that the tokens acquired before the operation should be returned if
	// the operation fails.
	Refundable bool
}

Spec represents a combination of Group and Kind, with all additional data required to get / put tokens.

func (Spec) Name

func (s Spec) Name() string

Name returns a textual representation of the Spec. Names are constant and may be relied upon to not change in the future.

Names are created as follows: * Global quotas are mapped to "global/read" or "global/write" * Tree quotas are mapped to "trees/$TreeID/$Kind". E.g., "trees/10/read". * User quotas are mapped to "users/$User/$Kind". E.g., "trees/10/read".

func (Spec) String

func (s Spec) String() string

String returns a description of Spec.