gubernator

package
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 30, 2021 License: Apache-2.0 Imports: 10 Imported by: 0

README

Gubernator

Gubernator is a distributed, high performance, cloud native and stateless rate limiting service.

We generate gRPC client code (gubernator.pb.go) using gobernator.proto which is a file directly download from the project repository. You can find the 3rd party dependencies for proto generation under proto directory. To update or re-generate please use make proto.

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	Algorithm_name = map[int32]string{
		0: "TOKEN_BUCKET",
		1: "LEAKY_BUCKET",
	}
	Algorithm_value = map[string]int32{
		"TOKEN_BUCKET": 0,
		"LEAKY_BUCKET": 1,
	}
)

Enum value maps for Algorithm.

View Source
var (
	Behavior_name = map[int32]string{
		0:  "BATCHING",
		1:  "NO_BATCHING",
		2:  "GLOBAL",
		4:  "DURATION_IS_GREGORIAN",
		8:  "RESET_REMAINING",
		16: "MULTI_REGION",
	}
	Behavior_value = map[string]int32{
		"BATCHING":              0,
		"NO_BATCHING":           1,
		"GLOBAL":                2,
		"DURATION_IS_GREGORIAN": 4,
		"RESET_REMAINING":       8,
		"MULTI_REGION":          16,
	}
)

Enum value maps for Behavior.

View Source
var (
	Status_name = map[int32]string{
		0: "UNDER_LIMIT",
		1: "OVER_LIMIT",
	}
	Status_value = map[string]int32{
		"UNDER_LIMIT": 0,
		"OVER_LIMIT":  1,
	}
)

Enum value maps for Status.

View Source
var File_ratelimit_gubernator_gubernator_proto protoreflect.FileDescriptor

Functions

func RegisterV1Server

func RegisterV1Server(s *grpc.Server, srv V1Server)

Types

type Algorithm

type Algorithm int32
const (
	// Token bucket algorithm https://en.wikipedia.org/wiki/Token_bucket
	Algorithm_TOKEN_BUCKET Algorithm = 0
	// Leaky bucket algorithm https://en.wikipedia.org/wiki/Leaky_bucket
	Algorithm_LEAKY_BUCKET Algorithm = 1
)

func (Algorithm) Descriptor

func (Algorithm) Descriptor() protoreflect.EnumDescriptor

func (Algorithm) Enum

func (x Algorithm) Enum() *Algorithm

func (Algorithm) EnumDescriptor deprecated

func (Algorithm) EnumDescriptor() ([]byte, []int)

Deprecated: Use Algorithm.Descriptor instead.

func (Algorithm) Number

func (x Algorithm) Number() protoreflect.EnumNumber

func (Algorithm) String

func (x Algorithm) String() string

func (Algorithm) Type

type Behavior

type Behavior int32

A set of int32 flags used to control the behavior of a rate limit in gubernator

const (
	// BATCHING is the default behavior. This enables batching requests which protects the
	// service from thundering herd. IE: When a service experiences spikes of unexpected high
	// volume requests.
	//
	// Using this option introduces a small amount of latency depending on
	// the `batchWait` setting. Defaults to around 500 Microseconds of additional
	// latency in low throughput situations. For high volume loads, batching can reduce
	// the overall load on the system substantially.
	Behavior_BATCHING Behavior = 0 // <-- this is here because proto requires it, but has no effect if used
	// Disables batching. Use this for super low latency rate limit requests when
	// thundering herd is not a concern but latency of requests is of paramount importance.
	Behavior_NO_BATCHING Behavior = 1
	// Enables Global caching of the rate limit. Use this if the rate limit applies globally to
	// all ingress requests. (IE: Throttle hundreds of thousands of requests to an entire
	// datacenter or cluster of http servers)
	//
	// Using this option gubernator will continue to use a single peer as the rate limit coordinator
	// to increment and manage the state of the rate limit, however the result of the rate limit is
	// distributed to each peer and cached locally. A rate limit request received from any peer in the
	// cluster will first check the local cache for a rate limit answer, if it exists the peer will
	// immediately return the answer to the client and asynchronously forward the aggregate hits to
	// the peer coordinator. Because of GLOBALS async nature we lose some accuracy in rate limit
	// reporting, which may result in allowing some requests beyond the chosen rate limit. However we
	// gain massive performance as every request coming into the system does not have to wait for a
	// single peer to decide if the rate limit has been reached.
	Behavior_GLOBAL Behavior = 2
	// Changes the behavior of the `Duration` field. When `Behavior` is set to `DURATION_IS_GREGORIAN`
	// the `Duration` of the rate limit is reset whenever the end of selected GREGORIAN calendar
	// interval is reached.
	//
	// Given the following `Duration` values
	//   0 = Minutes
	//   1 = Hours
	//   2 = Days
	//   3 = Weeks
	//   4 = Months
	//   5 = Years
	//
	// Examples when using `Behavior = DURATION_IS_GREGORIAN`
	//
	// If  `Duration = 2` (Days) then the rate limit will expire at the end of the current day the
	// rate limit was created.
	//
	// If `Duration = 0` (Minutes) then the rate limit will expire at the end of the current minute
	// the rate limit was created.
	//
	// If `Duration = 4` (Months) then the rate limit will expire at the end of the current month
	// the rate limit was created.
	Behavior_DURATION_IS_GREGORIAN Behavior = 4
	// If this flag is set causes the rate limit to reset any accrued hits stored in the cache, and will
	// ignore any `Hit` values provided in the current request. The effect this has is dependent on
	// algorithm chosen. For instance, if used with `TOKEN_BUCKET` it will immediately expire the
	// cache value. For `LEAKY_BUCKET` it sets the `Remaining` to `Limit`.
	Behavior_RESET_REMAINING Behavior = 8
	// Enables rate limits to be pushed to other regions. Currently this is only implemented on memberlist
	// pools. Also requires GUBER_DATA_CENTER to be set to different values on at least 2 instances of
	// Gubernator.
	Behavior_MULTI_REGION Behavior = 16
)

func (Behavior) Descriptor

func (Behavior) Descriptor() protoreflect.EnumDescriptor

func (Behavior) Enum

func (x Behavior) Enum() *Behavior

func (Behavior) EnumDescriptor deprecated

func (Behavior) EnumDescriptor() ([]byte, []int)

Deprecated: Use Behavior.Descriptor instead.

func (Behavior) Number

func (x Behavior) Number() protoreflect.EnumNumber

func (Behavior) String

func (x Behavior) String() string

func (Behavior) Type

type GetRateLimitsReq

type GetRateLimitsReq struct {
	Requests []*RateLimitReq `protobuf:"bytes,1,rep,name=requests,proto3" json:"requests,omitempty"`
	// contains filtered or unexported fields
}

Must specify at least one Request

func (*GetRateLimitsReq) Descriptor deprecated

func (*GetRateLimitsReq) Descriptor() ([]byte, []int)

Deprecated: Use GetRateLimitsReq.ProtoReflect.Descriptor instead.

func (*GetRateLimitsReq) GetRequests

func (x *GetRateLimitsReq) GetRequests() []*RateLimitReq

func (*GetRateLimitsReq) ProtoMessage

func (*GetRateLimitsReq) ProtoMessage()

func (*GetRateLimitsReq) ProtoReflect

func (x *GetRateLimitsReq) ProtoReflect() protoreflect.Message

func (*GetRateLimitsReq) Reset

func (x *GetRateLimitsReq) Reset()

func (*GetRateLimitsReq) String

func (x *GetRateLimitsReq) String() string

type GetRateLimitsResp

type GetRateLimitsResp struct {
	Responses []*RateLimitResp `protobuf:"bytes,1,rep,name=responses,proto3" json:"responses,omitempty"`
	// contains filtered or unexported fields
}

RateLimits returned are in the same order as the Requests

func (*GetRateLimitsResp) Descriptor deprecated

func (*GetRateLimitsResp) Descriptor() ([]byte, []int)

Deprecated: Use GetRateLimitsResp.ProtoReflect.Descriptor instead.

func (*GetRateLimitsResp) GetResponses

func (x *GetRateLimitsResp) GetResponses() []*RateLimitResp

func (*GetRateLimitsResp) ProtoMessage

func (*GetRateLimitsResp) ProtoMessage()

func (*GetRateLimitsResp) ProtoReflect

func (x *GetRateLimitsResp) ProtoReflect() protoreflect.Message

func (*GetRateLimitsResp) Reset

func (x *GetRateLimitsResp) Reset()

func (*GetRateLimitsResp) String

func (x *GetRateLimitsResp) String() string

type HealthCheckReq

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

func (*HealthCheckReq) Descriptor deprecated

func (*HealthCheckReq) Descriptor() ([]byte, []int)

Deprecated: Use HealthCheckReq.ProtoReflect.Descriptor instead.

func (*HealthCheckReq) ProtoMessage

func (*HealthCheckReq) ProtoMessage()

func (*HealthCheckReq) ProtoReflect

func (x *HealthCheckReq) ProtoReflect() protoreflect.Message

func (*HealthCheckReq) Reset

func (x *HealthCheckReq) Reset()

func (*HealthCheckReq) String

func (x *HealthCheckReq) String() string

type HealthCheckResp

type HealthCheckResp struct {

	// Valid entries are 'healthy' or 'unhealthy'
	Status string `protobuf:"bytes,1,opt,name=status,proto3" json:"status,omitempty"`
	// If 'unhealthy', message indicates the problem
	Message string `protobuf:"bytes,2,opt,name=message,proto3" json:"message,omitempty"`
	// The number of peers we know about
	PeerCount int32 `protobuf:"varint,3,opt,name=peer_count,json=peerCount,proto3" json:"peer_count,omitempty"`
	// contains filtered or unexported fields
}

func (*HealthCheckResp) Descriptor deprecated

func (*HealthCheckResp) Descriptor() ([]byte, []int)

Deprecated: Use HealthCheckResp.ProtoReflect.Descriptor instead.

func (*HealthCheckResp) GetMessage

func (x *HealthCheckResp) GetMessage() string

func (*HealthCheckResp) GetPeerCount

func (x *HealthCheckResp) GetPeerCount() int32

func (*HealthCheckResp) GetStatus

func (x *HealthCheckResp) GetStatus() string

func (*HealthCheckResp) ProtoMessage

func (*HealthCheckResp) ProtoMessage()

func (*HealthCheckResp) ProtoReflect

func (x *HealthCheckResp) ProtoReflect() protoreflect.Message

func (*HealthCheckResp) Reset

func (x *HealthCheckResp) Reset()

func (*HealthCheckResp) String

func (x *HealthCheckResp) String() string

type RateLimitReq

type RateLimitReq struct {

	// The name of the rate limit IE: 'requests_per_second', 'gets_per_minute`
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// Uniquely identifies this rate limit IE: 'ip:10.2.10.7' or 'account:123445'
	UniqueKey string `protobuf:"bytes,2,opt,name=unique_key,json=uniqueKey,proto3" json:"unique_key,omitempty"`
	// Rate limit requests optionally specify the number of hits a request adds to the matched limit. If Hit
	// is zero, the request returns the current limit, but does not increment the hit count.
	Hits int64 `protobuf:"varint,3,opt,name=hits,proto3" json:"hits,omitempty"`
	// The number of requests that can occur for the duration of the rate limit
	Limit int64 `protobuf:"varint,4,opt,name=limit,proto3" json:"limit,omitempty"`
	// The duration of the rate limit in milliseconds
	// Second = 1000 Milliseconds
	// Minute = 60000 Milliseconds
	// Hour = 3600000 Milliseconds
	Duration int64 `protobuf:"varint,5,opt,name=duration,proto3" json:"duration,omitempty"`
	// The algorithm used to calculate the rate limit. The algorithm may change on
	// subsequent requests, when this occurs any previous rate limit hit counts are reset.
	Algorithm Algorithm `protobuf:"varint,6,opt,name=algorithm,proto3,enum=pb.gubernator.Algorithm" json:"algorithm,omitempty"`
	// Behavior is a set of int32 flags that control the behavior of the rate limit in gubernator
	Behavior Behavior `protobuf:"varint,7,opt,name=behavior,proto3,enum=pb.gubernator.Behavior" json:"behavior,omitempty"`
	// contains filtered or unexported fields
}

func (*RateLimitReq) Descriptor deprecated

func (*RateLimitReq) Descriptor() ([]byte, []int)

Deprecated: Use RateLimitReq.ProtoReflect.Descriptor instead.

func (*RateLimitReq) GetAlgorithm

func (x *RateLimitReq) GetAlgorithm() Algorithm

func (*RateLimitReq) GetBehavior

func (x *RateLimitReq) GetBehavior() Behavior

func (*RateLimitReq) GetDuration

func (x *RateLimitReq) GetDuration() int64

func (*RateLimitReq) GetHits

func (x *RateLimitReq) GetHits() int64

func (*RateLimitReq) GetLimit

func (x *RateLimitReq) GetLimit() int64

func (*RateLimitReq) GetName

func (x *RateLimitReq) GetName() string

func (*RateLimitReq) GetUniqueKey

func (x *RateLimitReq) GetUniqueKey() string

func (*RateLimitReq) ProtoMessage

func (*RateLimitReq) ProtoMessage()

func (*RateLimitReq) ProtoReflect

func (x *RateLimitReq) ProtoReflect() protoreflect.Message

func (*RateLimitReq) Reset

func (x *RateLimitReq) Reset()

func (*RateLimitReq) String

func (x *RateLimitReq) String() string

type RateLimitResp

type RateLimitResp struct {

	// The status of the rate limit.
	Status Status `protobuf:"varint,1,opt,name=status,proto3,enum=pb.gubernator.Status" json:"status,omitempty"`
	// The currently configured request limit (Identical to RateLimitRequest.rate_limit_config.limit).
	Limit int64 `protobuf:"varint,2,opt,name=limit,proto3" json:"limit,omitempty"`
	// This is the number of requests remaining before the limit is hit.
	Remaining int64 `protobuf:"varint,3,opt,name=remaining,proto3" json:"remaining,omitempty"`
	// This is the time when the rate limit span will be reset, provided as a unix timestamp in milliseconds.
	ResetTime int64 `protobuf:"varint,4,opt,name=reset_time,json=resetTime,proto3" json:"reset_time,omitempty"`
	// Contains the error; If set all other values should be ignored
	Error string `protobuf:"bytes,5,opt,name=error,proto3" json:"error,omitempty"`
	// This is additional metadata that a client might find useful. (IE: Additional headers, corrdinator ownership, etc..)
	Metadata map[string]string `` /* 157-byte string literal not displayed */
	// contains filtered or unexported fields
}

func (*RateLimitResp) Descriptor deprecated

func (*RateLimitResp) Descriptor() ([]byte, []int)

Deprecated: Use RateLimitResp.ProtoReflect.Descriptor instead.

func (*RateLimitResp) GetError

func (x *RateLimitResp) GetError() string

func (*RateLimitResp) GetLimit

func (x *RateLimitResp) GetLimit() int64

func (*RateLimitResp) GetMetadata

func (x *RateLimitResp) GetMetadata() map[string]string

func (*RateLimitResp) GetRemaining

func (x *RateLimitResp) GetRemaining() int64

func (*RateLimitResp) GetResetTime

func (x *RateLimitResp) GetResetTime() int64

func (*RateLimitResp) GetStatus

func (x *RateLimitResp) GetStatus() Status

func (*RateLimitResp) ProtoMessage

func (*RateLimitResp) ProtoMessage()

func (*RateLimitResp) ProtoReflect

func (x *RateLimitResp) ProtoReflect() protoreflect.Message

func (*RateLimitResp) Reset

func (x *RateLimitResp) Reset()

func (*RateLimitResp) String

func (x *RateLimitResp) String() string

type Status

type Status int32
const (
	Status_UNDER_LIMIT Status = 0
	Status_OVER_LIMIT  Status = 1
)

func (Status) Descriptor

func (Status) Descriptor() protoreflect.EnumDescriptor

func (Status) Enum

func (x Status) Enum() *Status

func (Status) EnumDescriptor deprecated

func (Status) EnumDescriptor() ([]byte, []int)

Deprecated: Use Status.Descriptor instead.

func (Status) Number

func (x Status) Number() protoreflect.EnumNumber

func (Status) String

func (x Status) String() string

func (Status) Type

func (Status) Type() protoreflect.EnumType

type UnimplementedV1Server

type UnimplementedV1Server struct {
}

UnimplementedV1Server can be embedded to have forward compatible implementations.

func (*UnimplementedV1Server) GetRateLimits

func (*UnimplementedV1Server) HealthCheck

type V1Client

type V1Client interface {
	// Given a list of rate limit requests, return the rate limits of each.
	GetRateLimits(ctx context.Context, in *GetRateLimitsReq, opts ...grpc.CallOption) (*GetRateLimitsResp, error)
	// This method is for round trip benchmarking and can be used by
	// the client to determine connectivity to the server
	HealthCheck(ctx context.Context, in *HealthCheckReq, opts ...grpc.CallOption) (*HealthCheckResp, error)
}

V1Client is the client API for V1 service.

For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream.

func NewV1Client

func NewV1Client(cc grpc.ClientConnInterface) V1Client

type V1Server

type V1Server interface {
	// Given a list of rate limit requests, return the rate limits of each.
	GetRateLimits(context.Context, *GetRateLimitsReq) (*GetRateLimitsResp, error)
	// This method is for round trip benchmarking and can be used by
	// the client to determine connectivity to the server
	HealthCheck(context.Context, *HealthCheckReq) (*HealthCheckResp, error)
}

V1Server is the server API for V1 service.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL