rate

Documentation

Overview

package rate implements server-side RPC rate limiting.

Index

• Variables
• type Handler
  • func NewHandler(cfg HandlerConfig, logger hclog.Logger) *Handler
  • func NewHandlerWithLimiter(cfg HandlerConfig, limiter multilimiter.RateLimiter, logger hclog.Logger) *Handler
  • func (h *Handler) Allow(op Operation) error
  • func (h *Handler) Register(leaderStatusProvider LeaderStatusProvider)
  • func (h *Handler) Run(ctx context.Context)
  • func (h *Handler) UpdateConfig(cfg HandlerConfig)
• type HandlerConfig
• type LeaderStatusProvider
• type MockRequestLimitsHandler
  • func NewMockRequestLimitsHandler(t mockConstructorTestingTNewMockRequestLimitsHandler) *MockRequestLimitsHandler
  • func (_m *MockRequestLimitsHandler) Allow(op Operation) error
  • func (_m *MockRequestLimitsHandler) Register(leaderStatusProvider LeaderStatusProvider)
  • func (_m *MockRequestLimitsHandler) Run(ctx context.Context)
  • func (_m *MockRequestLimitsHandler) UpdateConfig(cfg HandlerConfig)
• type Mode
  • func RequestLimitsModeFromName(name string) (Mode, bool)
  • func RequestLimitsModeFromNameWithDefault(name string) Mode
  • func (m Mode) String() string
• type Operation
• type OperationType
• type RequestLimitsHandler
  • func NullRequestLimitsHandler() RequestLimitsHandler

Variables

var (
	// ErrRetryElsewhere indicates that the operation was not allowed because the
	// rate limit was exhausted, but may succeed on a different server.
	//
	// Results in a RESOURCE_EXHAUSTED or "429 Too Many Requests" response.
	ErrRetryElsewhere = errors.New("rate limit exceeded, try again later or against a different server")

	// ErrRetryLater indicates that the operation was not allowed because the rate
	// limit was exhausted, and trying a different server won't help (e.g. because
	// the operation can only be performed on the leader).
	//
	// Results in an UNAVAILABLE or "503 Service Unavailable" response.
	ErrRetryLater = errors.New("rate limit exceeded for operation that can only be performed by the leader, try again later")
)

var Counters = []prometheus.CounterDefinition{
	{
		Name: []string{"rpc", "rate_limit", "exceeded"},
		Help: "Increments whenever an RPC is over a configured rate limit. Note: in permissive mode, the RPC will have still been allowed to proceed.",
	},
	{
		Name: []string{"rpc", "rate_limit", "log_dropped"},
		Help: "Increments whenever a log that is emitted because an RPC exceeded a rate limit gets dropped because the output buffer is full.",
	},
}

Types

type Handler

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

Handler enforces rate limits for incoming RPCs.

func NewHandler

func NewHandler(cfg HandlerConfig, logger hclog.Logger) *Handler

NewHandler creates a new RPC rate limit handler.

func NewHandlerWithLimiter

func NewHandlerWithLimiter(
	cfg HandlerConfig,
	limiter multilimiter.RateLimiter,
	logger hclog.Logger) *Handler

func (*Handler) Allow

func (h *Handler) Allow(op Operation) error

Allow returns an error if the given operation is not allowed to proceed because of an exhausted rate-limit.

func (*Handler) Register

func (h *Handler) Register(leaderStatusProvider LeaderStatusProvider)

func (*Handler) Run

func (h *Handler) Run(ctx context.Context)

Run the limiter cleanup routine until the given context is canceled.

Note: this starts a goroutine.

func (*Handler) UpdateConfig

func (h *Handler) UpdateConfig(cfg HandlerConfig)

type HandlerConfig

type HandlerConfig struct {
	multilimiter.Config

	// GlobalMode configures the action that will be taken when a global rate-limit
	// has been exhausted.
	//
	// Note: in the future there'll be a separate Mode for IP-based limits.
	GlobalMode Mode

	// GlobalWriteConfig configures the global rate limiter for write operations.
	GlobalWriteConfig multilimiter.LimiterConfig

	// GlobalReadConfig configures the global rate limiter for read operations.
	GlobalReadConfig multilimiter.LimiterConfig
}

type LeaderStatusProvider

type LeaderStatusProvider interface {
	// IsLeader is used to determine whether the operation is being performed
	// against the cluster leader, such that if it can _only_ be performed by
	// the leader (e.g. write operations) we don't tell clients to retry against
	// a different server.
	IsLeader() bool
}

type MockRequestLimitsHandler

type MockRequestLimitsHandler struct {
	mock.Mock
}

MockRequestLimitsHandler is an autogenerated mock type for the RequestLimitsHandler type

func NewMockRequestLimitsHandler

func NewMockRequestLimitsHandler(t mockConstructorTestingTNewMockRequestLimitsHandler) *MockRequestLimitsHandler

NewMockRequestLimitsHandler creates a new instance of MockRequestLimitsHandler. It also registers a testing interface on the mock and a cleanup function to assert the mocks expectations.

func (*MockRequestLimitsHandler) Allow

func (_m *MockRequestLimitsHandler) Allow(op Operation) error

Allow provides a mock function with given fields: op

func (*MockRequestLimitsHandler) Register

func (_m *MockRequestLimitsHandler) Register(leaderStatusProvider LeaderStatusProvider)

Register provides a mock function with given fields: leaderStatusProvider

func (*MockRequestLimitsHandler) Run

func (_m *MockRequestLimitsHandler) Run(ctx context.Context)

Run provides a mock function with given fields: ctx

func (*MockRequestLimitsHandler) UpdateConfig

func (_m *MockRequestLimitsHandler) UpdateConfig(cfg HandlerConfig)

UpdateConfig provides a mock function with given fields: cfg

type Mode

type Mode int

Mode determines the action that will be taken when a rate limit has been exhausted (e.g. log and allow, or reject).

const (
	// ModeDisabled causes rate limiting to be bypassed.
	ModeDisabled Mode = iota

	// ModePermissive causes the handler to log the rate-limited operation but
	// still allow it to proceed.
	ModePermissive

	// ModeEnforcing causes the handler to reject the rate-limited operation.
	ModeEnforcing
)

func RequestLimitsModeFromName

func RequestLimitsModeFromName(name string) (Mode, bool)

RequestLimitsModeFromName will unmarshal the string form of a configMode.

func RequestLimitsModeFromNameWithDefault

func RequestLimitsModeFromNameWithDefault(name string) Mode

RequestLimitsModeFromNameWithDefault will unmarshal the string form of a configMode.

func (Mode) String

func (m Mode) String() string

type Operation

type Operation struct {
	// Name of the RPC endpoint (e.g. "Foo.Bar" for net/rpc and "/foo.service/Bar" for gRPC).
	Name string

	// SourceAddr is the client's (or forwarding server's) IP address.
	SourceAddr net.Addr

	// Type of operation to be performed (e.g. read or write).
	Type OperationType
}

Operation the client is attempting to perform.

type OperationType

type OperationType int

OperationType is the type of operation the client is attempting to perform.

const (
	// OperationTypeRead represents a read operation.
	OperationTypeRead OperationType = iota

	// OperationTypeWrite represents a write operation.
	OperationTypeWrite

	// OperationTypeExempt represents an operation that is exempt from rate-limiting.
	OperationTypeExempt
)

type RequestLimitsHandler

type RequestLimitsHandler interface {
	Run(ctx context.Context)
	Allow(op Operation) error
	UpdateConfig(cfg HandlerConfig)
	Register(leaderStatusProvider LeaderStatusProvider)
}

func NullRequestLimitsHandler

func NullRequestLimitsHandler() RequestLimitsHandler

NullRequestLimitsHandler returns a RequestLimitsHandler that allows every operation.