Documentation ¶
Overview ¶
Package rules is a rules engine for etcd. Specified functions are triggered whenever a specified rule is satisfied. Rules can contain gin-style attribute specifiers so that classes of keys are matched as opposed to having to specify each node key separately.
Index ¶
- func FormatRuleString(in string) string
- func FormatWithAttributes(pattern string, m Attributes) string
- func RuleSatisfied(rule DynamicRule, triggerKey string, triggerValue *string, ...) (bool, error)
- func SetMethod(ctx context.Context, method string) context.Context
- type Attributes
- type BaseEngine
- type ContextProvider
- type DynamicRule
- type EngineOption
- func EngineConcurrency(workers int) EngineOption
- func EngineContextProvider(cp ContextProvider) EngineOption
- func EngineCrawlMutex(mutex string, mutexTTL int) EngineOption
- func EngineEnhancedRuleFilter(enhancedRuleFilter bool) EngineOption
- func EngineLockTimeout(lockTimeout int) EngineOption
- func EngineMetricsCollector(m MetricsCollectorOpt) EngineOption
- func EngineRuleWorkBuffer(buffer int) EngineOption
- func EngineSyncDelay(delay int) EngineOption
- func EngineSyncInterval(interval int) EngineOption
- func EngineWatchTimeout(watchTimeout int) EngineOption
- func GetEngineOptions(options EngineOptions) []EngineOption
- func KeyConstraint(attribute string, prefix string, chars [][]rune) EngineOption
- func KeyExpansion(keyExpansion map[string][]string) EngineOption
- type EngineOptions
- type EtcdMetricsMetadata
- type MetricsCollector
- type MetricsCollectorOpt
- type MockMetricsCollector
- func (m *MockMetricsCollector) IncLockMetric(methodName string, pattern string, lockSucceeded bool)
- func (m *MockMetricsCollector) IncSatisfiedThenNot(methodName string, pattern string, phaseName string)
- func (m *MockMetricsCollector) SetLogger(lgr *zap.Logger)
- func (m *MockMetricsCollector) TimesEvaluated(methodName string, ruleID string, count int)
- func (m *MockMetricsCollector) WorkerQueueWaitTime(methodName string, startTime time.Time)
- type RuleOption
- type V3Engine
- type V3RuleTask
- type V3RuleTaskCallback
- type WrapKV
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FormatRuleString ¶
FormatRuleString creates an indented, more readable version of a rule string
func FormatWithAttributes ¶
func FormatWithAttributes(pattern string, m Attributes) string
FormatWithAttributes applied the specified attributes to the provided path.
func RuleSatisfied ¶
func RuleSatisfied(rule DynamicRule, triggerKey string, triggerValue *string, kvs map[string]string) (bool, error)
RuleSatisfied returns true if the rule was satisfied and false if it was not. An error is returned if the trigger key did not contain the required path variables to evaluate the rule.
Types ¶
type Attributes ¶
Attributes provide access to the key/value pairs associated with dynamic keys. For instance, a dynamic key "/static/:dynamic" that is matched against "/static/value1" would contain an yield an attribute with the key "dynamic" and the value "value1".
func NewAttributes ¶
func NewAttributes(values map[string]string) Attributes
NewAttributes provides a map-based Attributes instance, for instance for testing callbacks.
type BaseEngine ¶
type BaseEngine interface { Run() Stop() IsStopped() bool // Shutdown gracefully stops the rules engine and waits for termination to // complete. If the provided context expires before the shutdown is complete, // then the context's error is returned. Shutdown(ctx context.Context) error }
BaseEngine provides common method for etcd v2 and v3 rules engine instances.
type ContextProvider ¶
type ContextProvider func() (context.Context, context.CancelFunc)
ContextProvider is used to specify a custom provider of a context for a given rule.
type DynamicRule ¶
type DynamicRule interface { Expand(map[string][]string) ([]DynamicRule, bool) // contains filtered or unexported methods }
DynamicRule defines rules that have dynamic key paths so that classes of keys can be referenced in rules.
func NewAndRule ¶
func NewAndRule(rules ...DynamicRule) DynamicRule
NewAndRule allows two or more dynamic rules to be combined into a single rule such that every nested rule must be satisfied in order for the overall rule to be satisfied.
func NewEqualsLiteralRule ¶
func NewEqualsLiteralRule(pattern string, value *string) (DynamicRule, error)
NewEqualsLiteralRule creates a rule that compares the provided string value with the value of a node whose key matches the provided key pattern. A nil value indicates that there is no node with the given key.
func NewEqualsRule ¶
func NewEqualsRule(pattern []string) (DynamicRule, error)
NewEqualsRule enables the comparison of two or more node values with the specified key patterns.
func NewNotRule ¶
func NewNotRule(nestedRule DynamicRule) DynamicRule
NewNotRule allows a rule to be negated such that if the nested rule's key matches but the rule is otherwise not satisfied, the not rule is satisfied. This is to enable capabilities such as checking whether a given key is set, i.e. its value is not nil.
func NewOrRule ¶
func NewOrRule(rules ...DynamicRule) DynamicRule
NewOrRule allows two or more dynamic rules to be combined into a single rule such that at least one nested rule must be satisfied in order for the overall rule to be satisfied.
type EngineOption ¶
type EngineOption interface {
// contains filtered or unexported methods
}
EngineOption instances control the overall behavior of an Engine instance. Behavior for individual rules can be controlled via RuleOption instances.
func EngineConcurrency ¶
func EngineConcurrency(workers int) EngineOption
EngineConcurrency controls the number of concurrent workers processing rule tasks.
func EngineContextProvider ¶
func EngineContextProvider(cp ContextProvider) EngineOption
EngineContextProvider sets a custom provider for generating context instances for use by callbacks.
func EngineCrawlMutex ¶
func EngineCrawlMutex(mutex string, mutexTTL int) EngineOption
EngineCrawlMutex sets an application identifier mutex and a TTL value for the mutex to limit the number of instances of an application performing a crawl at any given time to one. mutexTTL refers to how long the mutex is in effect; if set too short, multiple instances of an application may end up crawling simultaneously. Note that this functionality is only implemented in etcd v3 and that a mutex in etcd v3 is held only while the app instance that created it is still active. This means that setting a high value, such as 3600 seconds, does not expose one to the risk of no crawls occuring for a maximum of one hour if an application instance terminates at the beginning of a crawler run.
func EngineEnhancedRuleFilter ¶
func EngineEnhancedRuleFilter(enhancedRuleFilter bool) EngineOption
EngineEnhancedRuleFilter uses a rule filtering mechanism that more accurately selects rules to be evaluated based on given key/value pair.
func EngineLockTimeout ¶
func EngineLockTimeout(lockTimeout int) EngineOption
EngineLockTimeout controls the TTL of a lock in seconds.
func EngineMetricsCollector ¶ added in v1.1.0
func EngineMetricsCollector(m MetricsCollectorOpt) EngineOption
EngineMetricsCollector sets a custom metrics collector
func EngineRuleWorkBuffer ¶
func EngineRuleWorkBuffer(buffer int) EngineOption
EngineRuleWorkBuffer sets the limit on the number of ruleWork in the channel without a receiving worker.
func EngineSyncDelay ¶
func EngineSyncDelay(delay int) EngineOption
EngineSyncDelay enables the throttling of the crawlers by introducing a delay (in ms) between queries to keep the crawlers from overwhelming etcd.
func EngineSyncInterval ¶
func EngineSyncInterval(interval int) EngineOption
EngineSyncInterval enables the interval between sync or crawler runs to be configured. The interval is in seconds.
func EngineWatchTimeout ¶
func EngineWatchTimeout(watchTimeout int) EngineOption
EngineWatchTimeout controls the timeout of a watch operation in seconds.
func GetEngineOptions ¶
func GetEngineOptions(options EngineOptions) []EngineOption
GetEngineOptions is used to convert an EngineOptions instance into an array of EngineOption instances which can then be used when initializing an Engine instance
func KeyConstraint ¶
func KeyConstraint(attribute string, prefix string, chars [][]rune) EngineOption
KeyConstraint enables multiple query prefixes to be generated for a specific attribute as a way to limit the scope of a query for a prefix query.
func KeyExpansion ¶
func KeyExpansion(keyExpansion map[string][]string) EngineOption
KeyExpansion enables attributes in rules to be fixed at run time while allowing the rule declarations to continue to use the attribute placeholders. For instance, an application may use a root directory "/:geo" to hold data for a given geography. Passing map[string][]string{"geo":{"na"}} into the KeyExpansion option will cause all rules with the "/:geo/" prefix to be rendered as "/na/..." but all paths rendered with attributes from realized rules will still correctly resolve ":geo" to "na". This allows the placeholder values to be set as application configuration settings while minimizing the scope of the watchers.
type EngineOptions ¶
type EngineOptions struct { Concurrency *int `toml:"concurrency"` EnhancedRuleFilter *bool `toml:"enhanced_rule_filter"` }
EngineOptions is used to configure the engine from configuration files
type EtcdMetricsMetadata ¶
EtcdMetricsMetadata provides information about calls to etcd
func GetMetricsMetadata ¶
func GetMetricsMetadata(ctx context.Context) *EtcdMetricsMetadata
GetMetricsMetadata gets metadata about an etcd call from the context
type MetricsCollector ¶ added in v1.1.0
type MetricsCollector interface { IncLockMetric(methodName string, pattern string, lockSucceeded bool) IncSatisfiedThenNot(methodName string, pattern string, phaseName string) TimesEvaluated(methodName string, ruleID string, count int) WorkerQueueWaitTime(methodName string, startTime time.Time) }
metricsCollector used for collecting metrics, implement this interface using your metrics collector of choice (ie Prometheus)
type MetricsCollectorOpt ¶ added in v1.1.0
type MetricsCollectorOpt func() MetricsCollector
type MockMetricsCollector ¶ added in v1.1.0
type MockMetricsCollector struct { // store what the IncLockMetric function was called with IncLockMetricPattern []string IncLockMetricLockSuccess []bool IncLockMetricMethod []string // store what the IncSatisfiedThenNot function was called with IncSatisfiedThenNotPattern []string IncIncSatisfiedThenNotPhase []string IncIncSatisfiedThenNotMethod []string // store what the TimesEvaluated function was called with TimesEvaluatedRuleID []string TimesEvaluatedCount []int TimesEvaluatedMethod []string // store what the WorkerQueueWaitTime was called with WorkerQueueWaitTimeTimes []time.Time WorkerQueueWaitTimeMethod []string // contains filtered or unexported fields }
a mock metrics collector used in unit tests
func NewMockMetricsCollector ¶ added in v1.1.0
func NewMockMetricsCollector() MockMetricsCollector
func (*MockMetricsCollector) IncLockMetric ¶ added in v1.1.0
func (m *MockMetricsCollector) IncLockMetric(methodName string, pattern string, lockSucceeded bool)
func (*MockMetricsCollector) IncSatisfiedThenNot ¶ added in v1.1.0
func (m *MockMetricsCollector) IncSatisfiedThenNot(methodName string, pattern string, phaseName string)
func (*MockMetricsCollector) SetLogger ¶ added in v1.1.0
func (m *MockMetricsCollector) SetLogger(lgr *zap.Logger)
func (*MockMetricsCollector) TimesEvaluated ¶ added in v1.1.0
func (m *MockMetricsCollector) TimesEvaluated(methodName string, ruleID string, count int)
func (*MockMetricsCollector) WorkerQueueWaitTime ¶ added in v1.1.0
func (m *MockMetricsCollector) WorkerQueueWaitTime(methodName string, startTime time.Time)
type RuleOption ¶
type RuleOption interface {
// contains filtered or unexported methods
}
RuleOption instances control the behavior of individual rules.
func RuleContextProvider ¶
func RuleContextProvider(cp ContextProvider) RuleOption
RuleContextProvider sets a custom provider for generating context instances for use by a specific callback.
func RuleID ¶ added in v1.1.0
func RuleID(ruleID string) RuleOption
RuleID is the ID associated with the rule
func RuleLockTimeout ¶
func RuleLockTimeout(lockTimeout int) RuleOption
RuleLockTimeout controls the TTL of the locks associated with the rule, in seconds.
type V3Engine ¶
type V3Engine interface { BaseEngine SetKVWrapper(WrapKV) AddRule(rule DynamicRule, lockPattern string, callback V3RuleTaskCallback, options ...RuleOption) AddPolling(namespacePattern string, preconditions DynamicRule, ttl int, callback V3RuleTaskCallback) error }
V3Engine defines the interactions with a rule engine instance communicating with etcd v3.
func NewV3Engine ¶
NewV3Engine creates a new V3Engine instance.
func NewV3EngineWithClient ¶
func NewV3EngineWithClient(cl *clientv3.Client, logger *zap.Logger, options ...EngineOption) V3Engine
NewV3EngineWithClient creates a new V3Engine instance with the provided etcd v3 client instance.
type V3RuleTask ¶
type V3RuleTask struct { Attr Attributes Logger *zap.Logger Context context.Context Metadata map[string]string // contains filtered or unexported fields }
V3RuleTask instances contain contextual object instances and metadata for use by rule callbacks.
type V3RuleTaskCallback ¶
type V3RuleTaskCallback func(task *V3RuleTask)
V3RuleTaskCallback is the function type for functions that are called as a reulst of a specified rule being satisfied using the etcd v3 API.