ratelimit

Documentation

Overview

Package ratelimit implements the types.RateLimit interface for limiting access to resources shared service wide.

Index

• Constants
• Variables
• func Descriptions() string
• func DocumentPlugin(typeString, description string, configSanitiser PluginConfigSanitiser)
• func New(conf Config, mgr types.Manager, log log.Modular, stats metrics.Type) (types.RateLimit, error)
• func NewLocal(conf Config, mgr types.Manager, logger log.Modular, stats metrics.Type) (types.RateLimit, error)
• func PluginCount() int
• func PluginDescriptions() string
• func RegisterPlugin(typeString string, configConstructor PluginConfigConstructor, ...)
• func SanitiseConfig(conf Config) (interface{}, error)
• func WalkConstructors(fn func(ConstructorFunc, docs.ComponentSpec))
• type Config
  • func NewConfig() Config
  • func (conf Config) Sanitised(removeDeprecated bool) (interface{}, error)
  • func (conf *Config) UnmarshalYAML(value *yaml.Node) error
• type ConstructorFunc
  • func GetDeprecatedPlugin(name string) (ConstructorFunc, bool)
• type Local
  • func (r *Local) Access() (time.Duration, error)
  • func (r *Local) CloseAsync()
  • func (r *Local) WaitForClose(timeout time.Duration) error
• type LocalConfig
  • func NewLocalConfig() LocalConfig
• type PluginConfigConstructor
• type PluginConfigSanitiser
• type PluginConstructor
• type TypeSpec

Constants

const (
	TypeLocal = "local"
)

String constants representing each ratelimit type.

Variables

var Constructors = map[string]TypeSpec{}

Constructors is a map of all cache types with their specs.

Functions

func Descriptions

func Descriptions() string

Descriptions returns a formatted string of descriptions for each type.

func DocumentPlugin

func DocumentPlugin(
	typeString, description string,
	configSanitiser PluginConfigSanitiser,
)

DocumentPlugin adds a description and an optional configuration sanitiser function to the definition of a registered plugin. This improves the documentation generated by PluginDescriptions.

func New

func New(
	conf Config,
	mgr types.Manager,
	log log.Modular,
	stats metrics.Type,
) (types.RateLimit, error)

New creates a rate limit type based on an rate limit configuration.

func NewLocal

func NewLocal(
	conf Config,
	mgr types.Manager,
	logger log.Modular,
	stats metrics.Type,
) (types.RateLimit, error)

NewLocal creates a local rate limit from a configuration struct. This type is safe to share and call from parallel goroutines.

func PluginCount

func PluginCount() int

PluginCount returns the number of registered plugins. This does NOT count the standard set of components.

func PluginDescriptions

func PluginDescriptions() string

PluginDescriptions generates and returns a markdown formatted document listing each registered plugin and an example configuration for it.

func RegisterPlugin

func RegisterPlugin(
	typeString string,
	configConstructor PluginConfigConstructor,
	constructor PluginConstructor,
)

RegisterPlugin registers a plugin by a unique name so that it can be constructed similar to regular rate limits. If configuration is not needed for this plugin then configConstructor can be nil. A constructor for the plugin itself must be provided.

func SanitiseConfig

func SanitiseConfig(conf Config) (interface{}, error)

SanitiseConfig creates a sanitised version of a config.

func WalkConstructors

func WalkConstructors(fn func(ConstructorFunc, docs.ComponentSpec))

WalkConstructors iterates each component constructor.

Types

type Config

type Config struct {
	Label  string      `json:"label" yaml:"label"`
	Type   string      `json:"type" yaml:"type"`
	Local  LocalConfig `json:"local" yaml:"local"`
	Plugin interface{} `json:"plugin,omitempty" yaml:"plugin,omitempty"`
}

Config is the all encompassing configuration struct for all cache types.

func NewConfig

func NewConfig() Config

NewConfig returns a configuration struct fully populated with default values.

func (Config) Sanitised

func (conf Config) Sanitised(removeDeprecated bool) (interface{}, error)

Sanitised returns a sanitised version of the config, meaning sections that aren't relevant to behaviour are removed. Also optionally removes deprecated fields.

func (*Config) UnmarshalYAML

func (conf *Config) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML ensures that when parsing configs that are in a map or slice the default values are still applied.

type ConstructorFunc

type ConstructorFunc func(Config, types.Manager, log.Modular, metrics.Type) (types.RateLimit, error)

ConstructorFunc is a func signature able to construct a rate limiter.

func GetDeprecatedPlugin

func GetDeprecatedPlugin(name string) (ConstructorFunc, bool)

GetDeprecatedPlugin returns a constructor for an old plugin if it exists.

type Local

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

Local is a structure that tracks a rate limit, it can be shared across parallel processes in order to maintain a maximum rate of a protected resource.

func (*Local) Access

func (r *Local) Access() (time.Duration, error)

Access the rate limited resource. Returns a duration or an error if the rate limit check fails. The returned duration is either zero (meaning the resource can be accessed) or a reasonable length of time to wait before requesting again.

func (*Local) CloseAsync

func (r *Local) CloseAsync()

CloseAsync shuts down the rate limit.

func (*Local) WaitForClose

func (r *Local) WaitForClose(timeout time.Duration) error

WaitForClose blocks until the rate limit has closed down.

type LocalConfig

type LocalConfig struct {
	Count    int    `json:"count" yaml:"count"`
	Interval string `json:"interval" yaml:"interval"`
}

LocalConfig is a config struct containing rate limit fields for a local rate limit.

func NewLocalConfig

func NewLocalConfig() LocalConfig

NewLocalConfig returns a local rate limit configuration struct with default values.

type PluginConfigConstructor

type PluginConfigConstructor func() interface{}

PluginConfigConstructor is a func that returns a pointer to a new and fully populated configuration struct for a plugin type.

type PluginConfigSanitiser

type PluginConfigSanitiser func(conf interface{}) interface{}

PluginConfigSanitiser is a function that takes a configuration object for a plugin and returns a sanitised (minimal) version of it for printing in examples and plugin documentation.

This function is useful for when a plugins configuration struct is very large and complex, but can sometimes be expressed in a more concise way without losing the original intent.

type PluginConstructor

type PluginConstructor func(
	config interface{},
	manager types.Manager,
	logger log.Modular,
	metrics metrics.Type,
) (types.RateLimit, error)

PluginConstructor is a func that constructs a Benthos ratelimit plugin. These are plugins that are specific to certain use cases, experimental, private or otherwise unfit for widespread general use. Any number of plugins can be specified when using Benthos as a framework.

The configuration object will be the result of the PluginConfigConstructor after overlaying the user configuration.

type TypeSpec

type TypeSpec struct {
	Status      docs.Status
	Version     string
	Summary     string
	Description string
	Footnotes   string
	FieldSpecs  docs.FieldSpecs
	// contains filtered or unexported fields
}

TypeSpec is a constructor and a usage description for each ratelimit type.