Documentation
¶
Overview ¶
Package rules is the rules engine (§8.1): every active rule — a binding whose source is an event — gets a durable consumer on its event's stream, and every event its `when` matches starts one run of the executor's binding workflow, rule/<id>/<ce-id>.
The consumer is backplane__rule-<id> on bp_<service>, filtered on bp.<service>.<Event>, explicit acks, shared by all backplane replicas (competing consumers). A brand-new consumer starts at events published after it is created (deliver policy new): saving a rule does not replay the stream's history through it. An existing consumer keeps its position: a new version of the rule applies from the next event on, a pause stops consuming and keeps the consumer (the events wait), a resume continues where it stopped. A deleted rule's consumer is deleted.
Per event: the CloudEvents headers become meta, `when` is evaluated; false — ack; true — the run starts (reuse policy "reject duplicate", so a redelivered or republished event finds its run and is acked); the ack follows the start, from then on durability is Temporal's. A start that fails is redelivered with backoff, without bound; an event without ce-id, with a payload that is not JSON or on which `when` fails is terminated and logged (rules have no DLQ).
The engine reconciles on rule changes (bindings.Manager.Changes), on manifest changes (the registry) and periodically. Without NATS or Temporal it logs and does nothing; readiness does not depend on it.
Index ¶
- Constants
- Variables
- func ConsumerName(id uuid.UUID) string
- func DurableName(id uuid.UUID) string
- func IsRunOf(id uuid.UUID, workflowID string) bool
- func ParseMeta(h nats.Header) (bindings.Meta, error)
- func RunID(id, ceID string) string
- func TestRunID(id, unique string) string
- func TraceOf(h nats.Header) map[string]string
- type API
- func (a API) CancelRuleRun(ctx context.Context, req *consolev1.CancelRuleRunRequest) (*consolev1.CancelRuleRunResponse, error)
- func (a API) GetRuleRun(ctx context.Context, req *consolev1.GetRuleRunRequest) (*consolev1.GetRuleRunResponse, error)
- func (a API) ListRuleRuns(ctx context.Context, req *consolev1.ListRuleRunsRequest) (*consolev1.ListRuleRunsResponse, error)
- func (a API) TestRule(ctx context.Context, req *consolev1.TestRuleRequest) (*consolev1.TestRuleResponse, error)
- type Engine
- type JetStreamFunc
- type Option
- type Runs
- type Source
- type Starter
- type TemporalFunc
- type TemporalStarter
Constants ¶
const ( MetaRule = "bp.rule" MetaVersion = "bp.rule-version" )
Metadata of a rule's consumer besides wire.MetaService, MetaConsumer and MetaEvent: the rule and the version that last wrote the consumer.
const Subscriber = "backplane"
Subscriber is the service name rule consumers are made under: their durable is backplane__rule-<id> (wire.Durable).
const Workflow = wire.BindingWorkflow
Workflow is the workflow type that runs bindings and rules on backplane's task queue: the executor's.
Variables ¶
var ErrAlreadyStarted = errors.New("rules: run already started")
ErrAlreadyStarted: a run with the workflow id exists already (running or closed): the event was handled before — a redelivery or a republish. A Starter returns it, or Temporal's *serviceerror.WorkflowExecutionAlreadyStarted, which counts the same.
var ErrNoID = errors.New("rules: event without ce-id")
ErrNoID: the event has no ce-id — its run could not be deduplicated.
Functions ¶
func ConsumerName ¶
ConsumerName is the consumer name of rule id: rule-<id>.
func DurableName ¶
DurableName is the NATS durable of rule id's consumer: backplane__rule-<id>.
func ParseMeta ¶
ParseMeta reads the CloudEvents attributes of an event from its NATS headers (binary mode, ce-*). ce-id is required: the run's workflow id is made of it. A ce-time that is not RFC 3339 reads as no time (meta.time is empty then), as a reactor's Delivery does.
func RunID ¶
RunID is the workflow id of the rule's run on the event with ce-id: rule/<id>/<ce-id>. The same event never starts a second run.
Types ¶
type API ¶
API is RuleService: the rule RPCs of bindings.RuleAPI plus the run RPCs of the engine (TestRule, ListRuleRuns, GetRuleRun, CancelRuleRun).
func (API) CancelRuleRun ¶
func (a API) CancelRuleRun( ctx context.Context, req *consolev1.CancelRuleRunRequest, ) (*consolev1.CancelRuleRunResponse, error)
CancelRuleRun implements RuleService.
func (API) GetRuleRun ¶
func (a API) GetRuleRun(ctx context.Context, req *consolev1.GetRuleRunRequest) (*consolev1.GetRuleRunResponse, error)
GetRuleRun implements RuleService.
func (API) ListRuleRuns ¶
func (a API) ListRuleRuns( ctx context.Context, req *consolev1.ListRuleRunsRequest, ) (*consolev1.ListRuleRunsResponse, error)
ListRuleRuns implements RuleService.
func (API) TestRule ¶
func (a API) TestRule(ctx context.Context, req *consolev1.TestRuleRequest) (*consolev1.TestRuleResponse, error)
TestRule implements RuleService.
type Engine ¶
Engine is the component. It holds consumers and goroutines: share it by pointer.
func Detached ¶
Detached is an engine outside the tree — it logs nowhere and does not consume — for the run RPCs in tests and tools.
func (*Engine) Register ¶
func (e *Engine) Register(r grpc.ServiceRegistrar)
Register registers RuleService on r — in place of the bindings Manager's own, which lacks the run RPCs.
func (*Engine) Test ¶
func (e *Engine) Test(ctx context.Context, req *consolev1.TestRuleRequest) (*consolev1.TestRuleResponse, error)
Test is TestRule: see the RPC.
type JetStreamFunc ¶
JetStreamFunc gives the NATS client; TemporalFunc the Temporal one.
type Option ¶
type Option func(*Engine)
Option configures New.
func Concurrency ¶
Concurrency is how many deliveries of one rule a replica handles at once (default 8).
func WithJetStream ¶
func WithJetStream(fn JetStreamFunc) Option
WithJetStream replaces the SDK's NATS client (tests).
func WithQueue ¶
WithQueue is the task queue runs start on and are listed by; default: backplane's own (workflows.Queue).
func WithRuns ¶
WithRuns serves ListRuleRuns, GetRuleRun and CancelRuleRun through r (ops.WorkflowAPI); without it they are UNAVAILABLE.
func WithStarter ¶
WithStarter starts runs through s (the executor's) instead of the engine's own TemporalStarter.
func WithTemporal ¶
func WithTemporal(fn TemporalFunc) Option
WithTemporal replaces the SDK's Temporal client (tests).
func WithWorkflow ¶
WithWorkflow is the workflow type of the TemporalStarter; default Workflow.
type Runs ¶
type Runs interface {
ListRuns(ctx context.Context, req *consolev1.ListRunsRequest) (*consolev1.ListRunsResponse, error)
GetRun(ctx context.Context, req *consolev1.GetRunRequest) (*consolev1.GetRunResponse, error)
CancelRun(ctx context.Context, req *consolev1.CancelRunRequest) (*consolev1.CancelRunResponse, error)
}
Runs is the console's view of Temporal runs the run RPCs delegate to: ops.WorkflowAPI.
type Source ¶
type Source interface {
// Rules is every rule with its current version, deleted ones too.
Rules(ctx context.Context) ([]bindings.RuleEntry, error)
// RuleVersion is one version of a rule; 0: the current one.
RuleVersion(ctx context.Context, id uuid.UUID, version int64) (bindings.RuleVersion, error)
// Changes signals after every save, delete, pause and resume.
Changes(ctx context.Context) <-chan struct{}
// Catalog is the latest manifests.
Catalog() (bindings.Catalog, error)
// RuleAPI is RuleService without the run RPCs.
RuleAPI() bindings.RuleAPI
}
Source is where rules come from: *bindings.Manager.
type Starter ¶
type Starter interface {
StartRule(ctx context.Context, id string, version int64, prog *bindings.Program, event []byte,
meta bindings.Meta, trace map[string]string, workflowID string) error
}
Starter starts one run of a rule on an event: the executor's binding workflow with the compiled program, the event's payload and attributes, the rule's identity and the event's trace context, under workflowID (rule/<id>/<ce-id>) with the reuse policy "reject duplicate". A run that exists already is ErrAlreadyStarted. Start only: the call does not wait for the run.
type TemporalFunc ¶
JetStreamFunc gives the NATS client; TemporalFunc the Temporal one.
type TemporalStarter ¶
type TemporalStarter struct {
// contains filtered or unexported fields
}
TemporalStarter starts rule runs with ExecuteWorkflow on a Temporal client: the workflow type and the task queue given, the executor's Input (executor.RuleInput) as the argument, memo source = rule:<id> and backplane.binding = rule:<id>@<version>. It is the engine's Starter unless WithStarter gives another.
func NewTemporalStarter ¶
func NewTemporalStarter(fn TemporalFunc, queue, workflow string) TemporalStarter
NewTemporalStarter starts workflow on queue through the client fn gives.