rules

package
v0.6.67 Latest Latest
Warning

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

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 39 Imported by: 0

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

View Source
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.

View Source
const Subscriber = "backplane"

Subscriber is the service name rule consumers are made under: their durable is backplane__rule-<id> (wire.Durable).

View Source
const Workflow = wire.BindingWorkflow

Workflow is the workflow type that runs bindings and rules on backplane's task queue: the executor's.

Variables

View Source
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.

View Source
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

func ConsumerName(id uuid.UUID) string

ConsumerName is the consumer name of rule id: rule-<id>.

func DurableName

func DurableName(id uuid.UUID) string

DurableName is the NATS durable of rule id's consumer: backplane__rule-<id>.

func IsRunOf

func IsRunOf(id uuid.UUID, workflowID string) bool

IsRunOf reports whether workflowID is a run or a test run of rule id.

func ParseMeta

func ParseMeta(h nats.Header) (bindings.Meta, error)

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

func RunID(id, ceID string) string

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.

func TestRunID

func TestRunID(id, unique string) string

TestRunID is the workflow id of a test run: test/rule/<id>/<uuid>, test/rule/draft/<uuid> for an unsaved definition.

func TraceOf

func TraceOf(h nats.Header) map[string]string

TraceOf is the event's W3C trace context (traceparent, tracestate) as the run carries it; nil when the event has none.

Types

type API

type API struct {
	bindings.RuleAPI
	// contains filtered or unexported fields
}

API is RuleService: the rule RPCs of bindings.RuleAPI plus the run RPCs of the engine (TestRule, ListRuleRuns, GetRuleRun, CancelRuleRun).

func (API) CancelRuleRun

CancelRuleRun implements RuleService.

func (API) GetRuleRun

GetRuleRun implements RuleService.

func (API) ListRuleRuns

ListRuleRuns implements RuleService.

func (API) TestRule

TestRule implements RuleService.

type Engine

type Engine struct {
	deps.Component
	// contains filtered or unexported fields
}

Engine is the component. It holds consumers and goroutines: share it by pointer.

func Detached

func Detached(src Source, opts ...Option) *Engine

Detached is an engine outside the tree — it logs nowhere and does not consume — for the run RPCs in tests and tools.

func New

func New(parent deps.Scope, src Source, reg registry.Source, opts ...Option) *Engine

New creates the engine under parent: rules from src, manifest changes from reg.

func (*Engine) API

func (e *Engine) API() API

API is the engine's RuleService.

func (*Engine) Queue

func (e *Engine) Queue() string

Queue is the task queue rule runs start on.

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

Test is TestRule: see the RPC.

type JetStreamFunc

type JetStreamFunc func() (jetstream.JetStream, error)

JetStreamFunc gives the NATS client; TemporalFunc the Temporal one.

type Option

type Option func(*Engine)

Option configures New.

func Concurrency

func Concurrency(n int) Option

Concurrency is how many deliveries of one rule a replica handles at once (default 8).

func Resync

func Resync(d time.Duration) Option

Resync is how often a full reconciliation runs without changes (default 1 min).

func StreamReplicas added in v0.6.53

func StreamReplicas(n int) Option

StreamReplicas is the replica count of an event stream the engine creates because it is missing (default 1): the installation's nats.replicas, so a stream made for a subscriber on a JetStream cluster is replicated before its emitter applies its own configuration.

func TemporalEnabled added in v0.3.0

func TemporalEnabled(enabled bool) Option

TemporalEnabled says whether the installation has Temporal (default true); without it rules on the temporal runtime do not run and say so.

func WithDirect added in v0.3.0

func WithDirect(d *direct.Service) Option

WithDirect installs the direct runtime: rules compiled for it run there, inline in the delivery; their runs are listed first.

func WithJetStream

func WithJetStream(fn JetStreamFunc) Option

WithJetStream replaces the SDK's NATS client (tests).

func WithQueue

func WithQueue(q string) Option

WithQueue is the task queue runs start on and are listed by; default: backplane's own (workflows.Queue).

func WithRuns

func WithRuns(r Runs) Option

WithRuns serves ListRuleRuns, GetRuleRun and CancelRuleRun through r (ops.WorkflowAPI); without it they are UNAVAILABLE.

func WithStarter

func WithStarter(s Starter) Option

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

func WithWorkflow(name string) Option

WithWorkflow is the workflow type of the TemporalStarter; default Workflow.

type Runs

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

type TemporalFunc func() (client.Client, error)

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.

func (TemporalStarter) StartRule

func (s TemporalStarter) StartRule(
	ctx context.Context, id string, version int64, prog *bindings.Program, event []byte,
	meta bindings.Meta, trace map[string]string, workflowID string,
) error

StartRule implements Starter.

Jump to

Keyboard shortcuts

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