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.QueueLeaf 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 ¶
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{} )
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 Providers ¶ added in v1.3.12
func Providers() []string
Providers returns a slice of registered quota provider names.
func RegisterProvider ¶ added in v1.3.8
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 )
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
// 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 ¶ added in v1.3.8
NewManager returns a Manager implementation.
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) 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) 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 ¶ added in v1.3.8
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 ¶
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".
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cacheqm contains a caching quota.Manager implementation.
|
Package cacheqm contains a caching quota.Manager implementation. |
|
Package crdbqm defines a CockroachDB-based quota.Manager implementation.
|
Package crdbqm defines a CockroachDB-based quota.Manager implementation. |
|
Package etcd provides the configuration and initialization of the etcd quota manager.
|
Package etcd provides the configuration and initialization of the etcd quota manager. |
|
etcdqm
Package etcdqm contains an etcd-based quota.Manager implementation.
|
Package etcdqm contains an etcd-based quota.Manager implementation. |
|
quotaapi
Package quotaapi provides a Quota admin server implementation.
|
Package quotaapi provides a Quota admin server implementation. |
|
quotapb
Package quotapb contains definitions for quota API protos and RPC service.
|
Package quotapb contains definitions for quota API protos and RPC service. |
|
storage
Package storage contains storage classes for etcd-based quotas.
|
Package storage contains storage classes for etcd-based quotas. |
|
storagepb
Package storagepb contains the protobuf definitions for using etcd as a Trillian quota backend.
|
Package storagepb contains the protobuf definitions for using etcd as a Trillian quota backend. |
|
Package mysqlqm defines a MySQL-based quota.Manager implementation.
|
Package mysqlqm defines a MySQL-based quota.Manager implementation. |
|
redis
|
|
|
redisqm
Package redisqm defines a Redis-based quota.Manager implementation.
|
Package redisqm defines a Redis-based quota.Manager implementation. |
|
redistb
Package redistb implements a token bucket using Redis.
|
Package redistb implements a token bucket using Redis. |