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 

func (Algorithm) Type() protoreflect.EnumType

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 

func (Behavior) Type() protoreflect.EnumType

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) GetRateLimits(context.Context, *GetRateLimitsReq) (*GetRateLimitsResp, error)

func (*UnimplementedV1Server) HealthCheck 

func (*UnimplementedV1Server) HealthCheck(context.Context, *HealthCheckReq) (*HealthCheckResp, error)

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.