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.

Jump to

Keyboard shortcuts

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