doorman

package
v0.0.0-...-cd31975 Latest Latest
Warning

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

 Go to latest Published: Jan 12, 2024 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package doorman is a library implementing global, distributed, client-side rate limiting.

This is an experimental and incomplete implementation. Most notably, a multi-level tree is not supported, and only the most basic algorithms are available.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Algorithm 

type Algorithm func(store LeaseStore, capacity float64, request Request) Lease

Algorithm is a function that takes a LeaseStore, the total available capacity, and a Request, and returns the lease.

func FairShare 

func FairShare(config *pb.Algorithm) Algorithm

FairShare assigns to each client a "fair" share of the available capacity. The definition of "fair" is as follows: In case the total wants is below the total available capacity, everyone gets what they want. If however the total wants is higher than the total available capacity everyone is guaranteed their equal share of the capacity. Any capacity left by clients who ask for less than their equal share is distributed to clients who ask for more than their equal share in a way so that available capacity is partitioned in equal parts in an iterative way.

func GetAlgorithm 

func GetAlgorithm(config *pb.Algorithm) Algorithm

func Learn 

func Learn(config *pb.Algorithm) Algorithm

Learn returns the algorithm used in learning mode. It assigns to the client the same capacity it reports it had before.

func NoAlgorithm 

func NoAlgorithm(config *pb.Algorithm) Algorithm

NoAlgorithm returns the zero algorithm: every clients gets as much capacity as it asks for.

func ProportionalShare 

func ProportionalShare(config *pb.Algorithm) Algorithm

ProportionalShare assigns to each client what it wants, except in an overload situation where each client gets at least an equal share (if it wants it), plus (if possible) a share of the capacity left on the table by clients who are requesting less than their equal share proportional to what the client is asking for.

func Static 

func Static(config *pb.Algorithm) Algorithm

Static assigns to each client the same configured capacity. Note that this algorithm attaches a different meaning to config.Capacity - it is the per client assigned capacity, not the total capacity available to all clients.

type ClientLeaseStatus 

type ClientLeaseStatus struct {
	ClientID string
	Lease    Lease
}

ClientLeaseStatus contains information about a lease that a client has.

type Lease 

type Lease struct {
	// Expiry is the time at which this lease expires.
	Expiry time.Time

	// RefreshInterval is the interval at which the client should
	// poll for updates for this resource.
	RefreshInterval time.Duration

	// Has is how much capacity was given to this client.
	Has float64

	// Wants is how much capacity was requested.
	Wants float64

	// Subclients is the number of subclients of this client.
	Subclients int64
}

Lease represents a lease on capacity for some resource for some client.

func (Lease) IsZero 

func (lease Lease) IsZero() bool

IsZero returns true if the lease is a zero instance.

type LeaseStore 

type LeaseStore interface {
	// SumHas returns the total capacity given out to clients
	// at the moment.
	SumHas() float64

	// SumWants returns the total capacity requested by clients.
	SumWants() float64

	// Get returns the lease currently granted to this client.
	Get(client string) Lease

	// HasClient returns whether this client currently has a lease.
	HasClient(client string) bool

	// Assign updates the lease store to represent capacity given
	// to a client.
	Assign(client string, leaseLength, refreshInterval time.Duration, has, wants float64, subclients int64) Lease

	// Release releases any leases granted to a client.
	Release(client string)

	// Clean removes any out of date leases. Returns the number of leases cleaned
	Clean() int

	// Count returns the number of subclients leases in the store.
	Count() int64

	// Returns a read-only copy of summary information about outstanding leases.
	ResourceLeaseStatus() ResourceLeaseStatus

	// Map executes a function for every lease in the store.
	Map(func(id string, lease Lease))

	// Subclients returns the number of subclients of the client with the given id.
	Subclients(id string) int64
}

LeaseStore is the set of outstanding leases for some particular resource.

func NewLeaseStore 

func NewLeaseStore(id string) LeaseStore

New returns a fresh LeaseStore implementation.

type Request 

type Request struct {
	// Client is the identifier of a client requesting capacity.
	Client string

	// Has is the capacity the client claims it has been assigned
	// previously.
	Has float64

	// Wants is the capacity that the client desires.
	Wants float64

	// Subclients is the number of subclients that the client has.
	Subclients int64
}

Request specifies a requested capacity lease that an Algorithm may grant.

type Resource 

type Resource struct {
	// ID is the name the clients use to access this resource.
	ID string
	// contains filtered or unexported fields
}

Resource giving clients capacity leases to some resource. It is safe to call or access any exported methods or properties from multiple goroutines.

func (*Resource) Decide 

func (res *Resource) Decide(request Request) Lease

Decide runs an algorithm, and returns the leased assigned to client. learning should be true if the server is in learning mode.

func (*Resource) LoadConfig 

func (res *Resource) LoadConfig(cfg *pb.ResourceTemplate, expiryTime *time.Time)

LoadConfig loads cfg into the resource. LoadConfig takes care of locking the resource.

func (*Resource) Matches 

func (res *Resource) Matches(cfg *pb.ResourceTemplate) bool

Matches returns true if the resource ID matches the glob from cfg.

func (*Resource) Release 

func (res *Resource) Release(client string)

Release releases any resources held for client. This method is safe to call from multiple goroutines.

func (*Resource) ResourceLeaseStatus 

func (res *Resource) ResourceLeaseStatus() ResourceLeaseStatus

ResourceLeaseStatus returns a read-only view of information the outstanding leases for this resource.

func (*Resource) SetSafeCapacity 

func (res *Resource) SetSafeCapacity(resp *pb.ResourceResponse)

SetSafeCapacity sets the safe capacity in a response.

func (*Resource) Status 

func (res *Resource) Status() ResourceStatus

Status returns a read-only view of res.

type ResourceLeaseStatus 

type ResourceLeaseStatus struct {
	// Resource id.
	ID string

	// The sum of all outstanding obligations.
	SumHas float64

	// The sum of all client wants.
	SumWants float64

	// A slice containing information about outstanding leases
	Leases []ClientLeaseStatus
}

ResourceLeaseStatus is a read-only copy of information about all leases for a particular resource. It can be used for display purposes.

type ResourceStatus 

type ResourceStatus struct {
	// ID is the id of the resource.
	ID string
	// SumHas is how much capacity has been given to clients.
	SumHas float64
	// SumWants is how much capacity the clients want.
	SumWants float64
	// Capacity is the total available capacity.
	Capacity float64
	// Count is the number of clients.
	Count int64
	// InLeaarningMode is true if the resource is in learning
	// mode.
	InLearningMode bool
	// Algorithm is the algorithm with which this resource is
	// configured.
	Algorithm *pb.Algorithm
}

ResourceStatus is a view of a resource that is useful for reporting, eg in /statusz.

type Server 

type Server struct {
	Election election.Election
	ID       string
	// contains filtered or unexported fields
}

Server represents the state of a doorman server.

func MakeTestIntermediateServer 

func MakeTestIntermediateServer(name string, addr string, resources ...*pb.ResourceTemplate) (*Server, error)

MakeTestIntermediateServer creates a test intermediate server with specified name and connected to the lower-level server with address addr.

func MakeTestServer 

func MakeTestServer(resources ...*pb.ResourceTemplate) (*Server, error)

MakeTestServer creates a test root server. It doesn't start any goroutines necessary to handle master election. It is supposed to be used only in tests. On top of making the test server it also unit tests some functions related to server configuration.

func New 

func New(ctx context.Context, id string, parentAddr string, leader election.Election, opts ...connection.Option) (*Server, error)

New returns a new unconfigured server. parentAddr is the address of a parent, pass the empty string to create a root server. This function should be called only once, as it registers metrics.

func NewIntermediate 

func NewIntermediate(ctx context.Context, id string, addr string, leader election.Election, opts ...connection.Option) (*Server, error)

NewIntermediate creates a server connected to the lower level server.

func (*Server) Close 

func (server *Server) Close()

Close closes the doorman server.

func (*Server) Collect 

func (server *Server) Collect(ch chan<- prometheus.Metric)

Collect implements prometheus.Collector.

func (*Server) CurrentMaster 

func (server *Server) CurrentMaster() string

CurrentMaster returns the current master, or an empty string if there's no master or it is unknown.

func (*Server) Describe 

func (server *Server) Describe(ch chan<- *prometheus.Desc)

Describe implements prometheus.Collector.

func (*Server) Discovery 

func (server *Server) Discovery(ctx context.Context, in *pb.DiscoveryRequest) (out *pb.DiscoveryResponse, err error)

Discovery implements the Discovery RPC which can be used to discover the address of the master.

func (*Server) GetCapacity 

func (server *Server) GetCapacity(ctx context.Context, in *pb.GetCapacityRequest) (out *pb.GetCapacityResponse, err error)

GetCapacity assigns capacity leases to clients. It is part of the doorman.CapacityServer implementation.

func (*Server) GetLearningModeEndTime 

func (server *Server) GetLearningModeEndTime(learningModeDuration time.Duration) time.Time

GetLearningModeEndTime returns the timestamp where a resource that has a particular learning mode duration leaves learning mode. mode duration is still in learning mode. Note: If the learningModeDuration is less or equal to zero there is no learning mode!

func (*Server) GetServerCapacity 

func (server *Server) GetServerCapacity(ctx context.Context, in *pb.GetServerCapacityRequest) (out *pb.GetServerCapacityResponse, err error)

GetServerCapacity gives capacity to doorman servers that can assign to their clients. It is part of the doorman.CapacityServer implementation.

func (*Server) IsMaster 

func (server *Server) IsMaster() bool

IsMaster returns true if server is the master.

func (*Server) LoadConfig 

func (server *Server) LoadConfig(ctx context.Context, config *pb.ResourceRepository, expiryTimes map[string]*time.Time) error

LoadConfig loads config as the new configuration for the server. It will take care of any locking, and it will return an error if the config is invalid. LoadConfig takes care of locking the server and resources. The first call to LoadConfig also triggers taking part in the master election, if the relevant locks were specified when the server was created.

func (*Server) ReleaseCapacity 

func (server *Server) ReleaseCapacity(ctx context.Context, in *pb.ReleaseCapacityRequest) (out *pb.ReleaseCapacityResponse, err error)

ReleaseCapacity releases capacity owned by a client.

func (*Server) ResourceLeaseStatus 

func (server *Server) ResourceLeaseStatus(id string) ResourceLeaseStatus

ResourceLeaseStatus returns a read-only view of of the leases on a resource owned by this server.

func (*Server) Status 

func (server *Server) Status() ServerStatus

Status returns a read-only view of server.

func (*Server) WaitUntilConfigured 

func (server *Server) WaitUntilConfigured()

WaitUntilConfigured blocks until the server is configured. If the server is configured to begin with it immediately returns.

type ServerStatus 

type ServerStatus struct {
	// IsMaster is true if the server is a master.
	IsMaster bool
	// Election contains information related to the master  election.
	Election election.Election
	// CurrentMaster is the id of the current master.
	CurrentMaster string
	// Resources are the statuses of the resources managed by this
	// server.
	Resources map[string]ResourceStatus
	// Config is the human readable representation of this server's
	// config.
	Config string
}

ServerStatus is a read-only view of a server suitable for reporting, eg in /statusz.

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.