Help us shape the future of Go! Take the 2026 Go Developer Survey

bindings

package
v0.6.57 Latest Latest
Warning

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

 Go to latest Published: Oct 29, 2026 License: MIT Imports: 56 Imported by: 0

Documentation

Overview

Package bindings is backplane's side of bindings (§7.1) and rules (§8.1): the model, validation against the manifests, versions in PostgreSQL and the console's BindingService, RuleService and WiringService.

A binding implements a hook ("<service>.<Hook>") with steps — calls of activities of any service — and a result; a rule runs the same steps on an event. Values are JSON trees whose strings are CEL expressions over JSON values: `req` (the hook's input) or `event` and `meta` (a rule's event and its CloudEvents attributes), the output of every step by its name, and `steps.<name>.skipped`.

For the executor and the rules engine the package offers:

  • Manager.Active / Manager.ActiveRules: what is in force now;
  • Compile: a definition checked against a Catalog into a *Program — steps with their dependencies and groups, options resolved from the manifests, expressions compiled; JSON-serializable, so a workflow receives it as input;
  • Program's evaluation (Start, Bind, When, Input, UndoInput, Result, Match, Eval): pure and deterministic — no clock, no randomness, no I/O, map iteration in key order — so it runs inside workflow code.

Index

Constants

View Source 
const (
	DefaultStartToClose    = 30 * time.Second
	DefaultAttempts        = 3
	DefaultInitialInterval = time.Second
	DefaultMaxInterval     = 30 * time.Second
	DefaultBackoff         = 2.0
)

Platform defaults of a step, below the binding's own options and the activity's manifest defaults.

View Source 
const (
	OnErrorFail     = "fail"
	OnErrorContinue = "continue"
	// DefaultItemVar names the item without As.
	DefaultItemVar     = "item"
	DefaultConcurrency = 10
	MaxConcurrency     = 100
	DefaultMaxItems    = 1000
	MaxItemsLimit      = 10000
)

For-each options.

View Source 
const (
	CodeInvalidName     = "INVALID_NAME"
	CodeReservedName    = "RESERVED_NAME"
	CodeUnknownHook     = "UNKNOWN_HOOK"
	CodeUnknownEvent    = "UNKNOWN_EVENT"
	CodeUnknownActivity = "UNKNOWN_ACTIVITY"
	CodeUnknownStep     = "UNKNOWN_STEP"
	CodeCycle           = "CYCLE"
	CodeUndoReference   = "UNDO_REFERENCE"
	CodeCEL             = "CEL_ERROR"
	CodeCost            = "COST"
	CodeTypeMismatch    = "TYPE_MISMATCH"
	CodeMissingField    = "MISSING_FIELD"
	CodeUnknownField    = "UNKNOWN_FIELD"
	CodeInvalidValue    = "INVALID_VALUE"
	CodeInvalidOption   = "INVALID_OPTION"
	// CodeRuntimeUnsupported: the step uses what the definition's runtime
	// does not run (undo, heartbeat or a child workflow on direct).
	CodeRuntimeUnsupported = "RUNTIME_UNSUPPORTED"
)

Violation codes.

View Source 
const (
	VarReq   = "req"
	VarEvent = "event"
	VarMeta  = "meta"
	VarSteps = "steps"
)

Variables every expression may see besides the steps: step names must differ from them.

View Source 
const BoundPrefix = "backplane/bindings/"

BoundPrefix is where each service's bound hooks are published: BoundPrefix+<service> holds a JSON array of hook names without the service prefix. The SDK watches its own key (pkg/backplane's consul driver), so a service can skip work for a hook nobody bound.

View Source 
const DefaultAuthor = "admin"

DefaultAuthor is the author of a version saved outside a console session.

View Source 
const FilesAuthor = "wiring"

FilesAuthor is the author of the versions the wiring files write.

Variables

View Source 
var (
	ErrNotSynced = errors.New("bindings: the registry has not synced with consul yet")
	// ErrNoBinding: the hook has no binding in force (never saved or
	// deleted).
	ErrNoBinding = errors.New("bindings: no binding")
	ErrNoVersion = errors.New("bindings: no such version")
	ErrNoRule    = errors.New("bindings: no such rule")
	// ErrDeleted: the rule or binding is deleted already.
	ErrDeleted = errors.New("bindings: deleted")
	// ErrConflict: an edit started from a version that is no longer the
	// current one.
	ErrConflict = errors.New("bindings: changed since the edit started")
	// ErrManaged: the binding or rule is defined in a wiring file, which
	// alone changes it.
	ErrManaged = errors.New("bindings: managed by a wiring file")
)

Errors of the Manager.

View Source 
var ErrWiringFile = errors.New("bindings: wiring file")

ErrWiringFile: a wiring file is not a valid definition of bindings and rules.

Functions

func FileRuleID added in v0.6.13 

func FileRuleID(name string) uuid.UUID

FileRuleID is the id of the rule a wiring file names name.

func IsFullName 

func IsFullName(s string) bool

IsFullName reports whether s is "<service>.<Name>" (§17).

func IsIdent 

func IsIdent(s string) bool

IsIdent reports whether s is an identifier: [A-Za-z_][A-Za-z0-9_]*.

func Pointer 

func Pointer(keys ...string) string

Pointer joins keys into a JSON Pointer.

func RenameBinding 

func RenameBinding(b Binding, from, to string) (Binding, []Violation)

RenameBinding is b with step from renamed to: its key, every `after` naming it, its editor position and every expression reading it (by the expressions' syntax trees: a string or a field of the same name stays). from is the step's id: its name, or "<for-each step>/<name>" for a step of a body (bodies nest); to is its new name. Refused: the violations say why.

func RenameRule 

func RenameRule(rule Rule, from, to string) (Rule, []Violation)

RenameRule is RenameBinding for a rule.

func SplitName 

func SplitName(full string) (string, string)

SplitName splits "<service>.<Name>" at its first dot into the service and the name.

func ViolationsPB 

func ViolationsPB(vs []Violation) []*consolev1.Violation

ViolationsPB are the violations as messages.

Types

type Analysis 

type Analysis struct {
	Violations []Violation
	// Steps by name.
	Steps []StepAnalysis
	// Types by path.
	Types []ValueType
	// References by path, then position.
	References []Reference
	// Secrets are the paths of the value nodes that carry secrets: fields
	// marked secret by a schema, or computed from one. Empty until the
	// definition is valid.
	Secrets []string
	// Runtime the definition compiled for: its own, else the catalog's
	// default, else Temporal.
	Runtime consolev1.Runtime
}

Analysis is a definition as the compiler sees it: its violations, the order of its steps, the type of every value and what every expression reads. Parts that do not compile are left out.

func AnalyzeBinding 

func AnalyzeBinding(b Binding, cat Catalog) (Analysis, error)

AnalyzeBinding checks b against the catalog and describes it.

func AnalyzeRule 

func AnalyzeRule(r Rule, cat Catalog) (Analysis, error)

AnalyzeRule checks r against the catalog and describes it.

func (Analysis) PB 

func (a Analysis) PB() *consolev1.Analysis

PB is the analysis as a message.

type Base 

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

Base is the version an edit started from. The zero Base skips the check; At(v) refuses the edit with ErrConflict when the current version is another one (0: none yet).

func At 

func At(v int64) Base

At is the base version v.

type Binding 

type Binding struct {
	// Hook is the full hook name "<service>.<Hook>".
	Hook        string
	Description string
	// Steps are sorted by name: order is not significant, execution
	// follows dependencies.
	Steps []Step
	// Result is the hook's output; zero: {}.
	Result Value
	// Runtime runs the binding; unspecified: the installation's default.
	Runtime consolev1.Runtime
	// Editor is the graph editor's layout, kept as saved; compile and
	// execution ignore it.
	Editor *consolev1.EditorLayout
}

Binding is the definition of a hook's binding.

func BindingFromPB 

func BindingFromPB(m *consolev1.BindingDefinition) Binding

BindingFromPB is the definition a message carries.

func BindingYAML 

func BindingYAML(text string) (Binding, error)

BindingYAML reads a binding definition from YAML: its protojson form written as YAML, as the console edits it. 

hook: hello.Greet
steps:
  formatted:
    activity: formatter.Format
    input: {name: req.name}
result: {text: formatted.text}

func (Binding) Equal 

func (b Binding) Equal(o Binding) bool

Equal reports whether two definitions say the same.

func (Binding) PB 

func (b Binding) PB() *consolev1.BindingDefinition

PB is the definition as a message.

type BindingAPI 

type BindingAPI struct {
	consolev1.UnimplementedBindingServiceServer
	// contains filtered or unexported fields
}

BindingAPI is the Manager as backplane.console.v1.BindingService.

func (BindingAPI) DeleteBinding 

func (a BindingAPI) DeleteBinding(
	ctx context.Context, req *consolev1.DeleteBindingRequest,
) (*consolev1.DeleteBindingResponse, error)

DeleteBinding implements BindingService.

func (BindingAPI) GetBinding 

func (a BindingAPI) GetBinding(
	ctx context.Context, req *consolev1.GetBindingRequest,
) (*consolev1.GetBindingResponse, error)

GetBinding implements BindingService.

func (BindingAPI) ListBindingVersions 

func (a BindingAPI) ListBindingVersions(
	ctx context.Context, req *consolev1.ListBindingVersionsRequest,
) (*consolev1.ListBindingVersionsResponse, error)

ListBindingVersions implements BindingService.

func (BindingAPI) ListBindings 

func (a BindingAPI) ListBindings(
	ctx context.Context, req *consolev1.ListBindingsRequest,
) (*consolev1.ListBindingsResponse, error)

ListBindings implements BindingService.

func (BindingAPI) RollbackBinding 

func (a BindingAPI) RollbackBinding(
	ctx context.Context, req *consolev1.RollbackBindingRequest,
) (*consolev1.RollbackBindingResponse, error)

RollbackBinding implements BindingService.

func (BindingAPI) SaveBinding 

func (a BindingAPI) SaveBinding(
	ctx context.Context, req *consolev1.SaveBindingRequest,
) (*consolev1.SaveBindingResponse, error)

SaveBinding implements BindingService.

func (BindingAPI) ValidateBinding 

func (a BindingAPI) ValidateBinding(
	_ context.Context, req *consolev1.ValidateBindingRequest,
) (*consolev1.ValidateBindingResponse, error)

ValidateBinding implements BindingService.

func (BindingAPI) WatchBindings 

func (a BindingAPI) WatchBindings(
	req *consolev1.WatchBindingsRequest, stream grpc.ServerStreamingServer[consolev1.WatchBindingsResponse],
) error

WatchBindings implements BindingService: the list now, then again whenever it differs — a save here or on another replica, a manifest.

type BindingVersion 

type BindingVersion struct {
	Hook    string
	Version int64
	// Binding is the definition; zero on a tombstone.
	Binding Binding
	// Deleted marks a tombstone: the delete of the binding.
	Deleted    bool
	Author     string
	Comment    string
	CreatedAt  time.Time
	RollbackOf int64 // 0: not a rollback
	// ManagedBy is the wiring file the version came from; "" for the
	// console's versions.
	ManagedBy string
}

BindingVersion is one saved version of a hook's binding.

func (BindingVersion) PB 

func (v BindingVersion) PB() *consolev1.BindingVersion

PB is the version as a message.

type CallLabel 

type CallLabel struct {
	Step   string
	Parent string
	Item   int
}

CallLabel is a call label read back: the call is of Step, in the body of the for-each step Parent (its id: "<outer>/<inner>" in a nested body; "" at the top), for Item (the step's own, or its innermost enclosing for-each step's for a step of a body; -1: none).

func ParseCallLabel 

func ParseCallLabel(label string) CallLabel

ParseCallLabel reads a call label — the envelope's step: segments "<step>" or "<step>[<item>]" joined by "." from the outermost for-each step in.

type Catalog 

type Catalog interface {
	Hook(name string) (*backplanev1.Hook, bool)
	Event(name string) (*backplanev1.Event, bool)
	Activity(name string) (*backplanev1.Activity, bool)
}

Catalog resolves full names ("<service>.<Name>") to what the manifests declare. Validation and Compile see the installation through it.

func FromRegistry 

func FromRegistry(c registry.Catalog) Catalog

FromRegistry is the catalog of the latest manifest of every service in a registry snapshot (registry.Service.Latest: the highest version a live instance runs).

func WithDefaults added in v0.3.0 

func WithDefaults(cat Catalog, d Defaults) Catalog

WithDefaults is cat with the installation's defaults.

type Defaulter added in v0.3.0 

type Defaulter interface {
	Defaults() Defaults
}

Defaulter is a Catalog that also carries the installation's defaults; compile reads them when it has them.

type Defaults added in v0.3.0 

type Defaults struct {
	// Runtime of a definition that names none; unspecified: Temporal.
	Runtime consolev1.Runtime
}

Defaults are what a definition leaves to the installation.

func DefaultsOf added in v0.3.0 

func DefaultsOf(cat Catalog) Defaults

DefaultsOf are cat's defaults, zero when it carries none.

type EvalError 

type EvalError struct {
	// Step is empty for the result and a rule's when.
	Step string
	// Place: when, input, input.<field>, undo input, output, result, event.
	Place string
	Err   error
}

EvalError is an expression that failed on the values of a run: "transform failed at step render (input.to): no such key: x".

func (*EvalError) Error 

func (e *EvalError) Error() string

func (*EvalError) Unwrap 

func (e *EvalError) Unwrap() error

type Field 

type Field struct {
	Name  string
	Value Value
}

Field is one field of an object Value.

type Files added in v0.6.13 

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

Files keeps the bindings and rules of a wiring directory in force: the directory is the desired state, and the console only reads what it holds.

Every *.yaml / *.yml file under the directory (dot-names skipped, so a Kubernetes ConfigMap mount works as is) holds one or more documents: 

bindings:
  - hook: kratos.Deliver        # BindingDefinition, as the console edits it
    steps: {...}
rules:
  - name: welcome               # the rule's identity
    event: kratos.IdentityCreated
    steps: {...}

A pass saves what differs from the current version as a new version managed by its file, and tombstones what a file held before and holds no more. A definition that does not compile against the manifests waits — for the services to register or for a fixed file — with the version in force untouched; a directory that does not read whole changes nothing. Replicas run it side by side: saves are conditional on the version read, so they converge.

func NewFiles added in v0.6.13 

func NewFiles(parent deps.Scope, m *Manager, dir string, poll time.Duration) *Files

NewFiles creates the component under parent: the directory dir, read every poll (0: 5s) and on every new manifest.

type ForEachPlan 

type ForEachPlan struct {
	// Item names the item variable; its position is Item+"Index".
	Item string `json:"item"`
	// Concurrency bounds the items in flight.
	Concurrency int `json:"concurrency"`
	// Continue: failed items are collected, the step succeeds; else the
	// first failure fails it.
	Continue bool `json:"continue,omitempty"`
	// MaxItems bounds the items: more fails the step.
	MaxItems int `json:"max_items"`
	// Steps: the body is a sub-flow (Program.Body), else the activity.
	Steps bool `json:"steps,omitempty"`
}

ForEachPlan is how a for-each step runs its items.

type InvalidError 

type InvalidError struct{ Violations []Violation }

InvalidError is a definition that does not compile: the violations say why.

func (*InvalidError) Error 

func (e *InvalidError) Error() string

type ItemError 

type ItemError struct {
	Index   int
	Message string
}

ItemError is a failed item of a for-each step: steps.<name>.errors.

type Kind 

type Kind int

Kind is what a program implements. 

const (
	// KindBinding implements a hook: input `req`, a result.
	KindBinding Kind = iota + 1
	// KindRule reacts to an event: input `event` and `meta`, a filter, no
	// result.
	KindRule
	// KindBody is a for-each step's sub-flow (Program.Body): it runs in the
	// scope of an item, its result is the item's output.
	KindBody
)

Kinds of programs.

type Manager 

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

Manager keeps bindings and rules: versions in PostgreSQL, validation against the registry's latest manifests, the console's BindingService and RuleService, and Changes for the executor and the rules engine. It holds state and a goroutine: share it by pointer.

func New 

func New(parent deps.Scope, st deps.Dependency[*store.Store], src registry.Source, opts ...Option) *Manager

New creates the component under parent: versions in st, manifests from src.

func (*Manager) Active 

func (m *Manager) Active(ctx context.Context, hook string) (Binding, int64, error)

Active is the binding in force for the hook and its version: ErrNoBinding when never saved or deleted. The executor's lookup: it answers from the snapshot, which a save on this replica refreshes before it returns and one on another replica within its notification (the poll interval at worst); the store is read only before the first snapshot.

func (*Manager) ActiveRules 

func (m *Manager) ActiveRules(ctx context.Context) ([]RuleEntry, error)

ActiveRules are the rules that run: not deleted, not paused. The rules engine's lookup (with Changes to follow it).

func (*Manager) BindingAPI 

func (m *Manager) BindingAPI() BindingAPI

BindingAPI serves m's bindings to the console.

func (*Manager) Catalog 

func (m *Manager) Catalog() (Catalog, error)

Catalog is the latest manifests as validation sees them.

func (*Manager) Changes 

func (m *Manager) Changes(ctx context.Context) <-chan struct{}

Changes signals after every save, delete, pause and resume — here or on another replica (told through PostgreSQL's LISTEN/NOTIFY, and seen by the poll at the latest) — until ctx ends; one pending signal at most. Manifests change through the registry's own Changes.

func (*Manager) Current 

func (m *Manager) Current(ctx context.Context, hook string) (BindingVersion, bool, error)

Current is the hook's current version; ok is false before the first save. A tombstone is current after a delete.

func (*Manager) CurrentAll 

func (m *Manager) CurrentAll(ctx context.Context) ([]BindingVersion, error)

CurrentAll is the current version of every hook ever bound, by hook.

func (*Manager) Defaults added in v0.3.0 

func (m *Manager) Defaults() Defaults

Defaults are the installation's defaults of definitions.

func (*Manager) Delete 

func (m *Manager) Delete(ctx context.Context, hook, comment string, base Base) (BindingVersion, error)

Delete saves a tombstone: the hook becomes unbound. ErrNoBinding when it has no binding in force.

func (*Manager) DeleteRule 

func (m *Manager) DeleteRule(ctx context.Context, id uuid.UUID, comment string, base Base) (RuleVersion, error)

DeleteRule saves a tombstone: the rule stops. ErrDeleted when it is deleted already.

func (*Manager) HookBindings 

func (m *Manager) HookBindings(ctx context.Context, service string) ([]*consolev1.HookBinding, error)

HookBindings is every hook of the latest manifests (of one service, or all for "") with its binding, and every binding whose hook is no longer declared, by hook.

func (*Manager) PauseRule 

func (m *Manager) PauseRule(ctx context.Context, id uuid.UUID, paused bool, base Base) (RuleEntry, error)

PauseRule sets the rule's pause: paused rules start no runs.

func (*Manager) Register 

func (m *Manager) Register(r grpc.ServiceRegistrar)

Register registers WiringService on r. BindingService and RuleService are served by the executor and the rules engine, around BindingAPI and RuleAPI.

func (*Manager) Rollback 

func (m *Manager) Rollback(
	ctx context.Context, hook string, version int64, comment string, base Base,
) (Saved, error)

Rollback saves the definition of an older version as the next one (validated again: manifests may have changed); rolling back to a tombstone deletes.

func (*Manager) RollbackRule 

func (m *Manager) RollbackRule(
	ctx context.Context, id uuid.UUID, version int64, comment string, base Base,
) (SavedRule, error)

RollbackRule saves the name and definition of an older version as the next one; rolling back to a tombstone deletes.

func (*Manager) Rule 

func (m *Manager) Rule(ctx context.Context, id uuid.UUID) (RuleEntry, error)

Rule is the rule with its current version: ErrNoRule when unknown.

func (*Manager) RuleAPI 

func (m *Manager) RuleAPI() RuleAPI

RuleAPI serves m's rules to the console.

func (*Manager) RuleVersion 

func (m *Manager) RuleVersion(ctx context.Context, id uuid.UUID, version int64) (RuleVersion, error)

RuleVersion is one version of a rule; 0: the current one.

func (*Manager) RuleVersions 

func (m *Manager) RuleVersions(ctx context.Context, id uuid.UUID, before int64, size int) ([]RuleVersion, error)

RuleVersions pages through a rule's versions, newest first.

func (*Manager) Rules 

func (m *Manager) Rules(ctx context.Context) ([]RuleEntry, error)

Rules is every rule with its current version (deleted ones too), by name.

func (*Manager) Save 

func (m *Manager) Save(ctx context.Context, b Binding, comment string, base Base) (Saved, error)

Save validates b and saves it as the next version of its hook's binding. Rejected: nothing is saved.

func (*Manager) SaveRule 

func (m *Manager) SaveRule(
	ctx context.Context, id uuid.UUID, name string, r Rule, comment string, base Base,
) (SavedRule, error)

SaveRule validates r and saves it as the next version of the rule; uuid.Nil creates a rule. Rejected: nothing is saved.

func (*Manager) Validate 

func (m *Manager) Validate(b Binding) ([]Violation, error)

Validate checks b against the latest manifests without saving it.

func (*Manager) ValidateRule 

func (m *Manager) ValidateRule(name string, r Rule) ([]Violation, error)

ValidateRule checks r (and its name) against the latest manifests without saving it.

func (*Manager) Version 

func (m *Manager) Version(ctx context.Context, hook string, version int64) (BindingVersion, error)

Version is one version of the hook's binding; 0: the current one.

func (*Manager) Versions 

func (m *Manager) Versions(ctx context.Context, hook string, before int64, size int) ([]BindingVersion, error)

Versions pages through the hook's versions, newest first: at most size below before (0: from the newest).

func (*Manager) WiringAPI 

func (m *Manager) WiringAPI() WiringAPI

WiringAPI serves the wiring editor.

type Manifests 

type Manifests []*backplanev1.Manifest

Manifests is a Catalog over manifests given directly: tests, and tools that validate against manifests they hold.

func (Manifests) Activity 

func (ms Manifests) Activity(full string) (*backplanev1.Activity, bool)

Activity implements Catalog.

func (Manifests) Event 

func (ms Manifests) Event(full string) (*backplanev1.Event, bool)

Event implements Catalog.

func (Manifests) Hook 

func (ms Manifests) Hook(full string) (*backplanev1.Hook, bool)

Hook implements Catalog.

type Meta 

type Meta struct {
	ID      string
	Source  string
	Subject string
	Type    string
	Time    time.Time
}

Meta are the CloudEvents attributes of the event a rule runs on, the CEL variable `meta` (time as RFC 3339).

type Option 

type Option func(*Manager)

Option configures New.

func Author 

func Author(fn func(ctx context.Context) string) Option

Author names the author of a version from the request's context; default: DefaultAuthor.

func DefaultRuntime added in v0.3.0 

func DefaultRuntime(rt consolev1.Runtime) Option

DefaultRuntime is the runtime of definitions that name none (the installation's BACKPLANE_WIRING_RUNTIME); default: Temporal.

func PollInterval 

func PollInterval(d time.Duration) Option

PollInterval is how often saves of other replicas are looked for (default 2s): Changes fires after them too.

type PathExpr 

type PathExpr struct {
	Path string
	Expr string
}

PathExpr is an expression and where it is.

type Program 

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

Program is a compiled binding or rule: the steps ordered into groups, options resolved, expressions compiled. It is built whole — by Compile or by json.Unmarshal of a marshaled Program — and not modified after: share it freely.

Evaluation is pure and deterministic: expressions read only the Scope, nothing reads a clock or randomness, maps are iterated in key order and results are JSON with sorted keys, so the same Program and Scope give the same bytes on every run — it is safe inside Temporal workflow code.

func CompileBinding 

func CompileBinding(b Binding, cat Catalog) (*Program, error)

CompileBinding checks b against the catalog and compiles it; an invalid definition is an *InvalidError.

func CompileRule 

func CompileRule(r Rule, cat Catalog) (*Program, error)

CompileRule checks r against the catalog and compiles it; an invalid definition is an *InvalidError.

func (*Program) Begin 

func (p *Program) Begin(item Scope) Scope

Begin is the scope a body starts an item in: the item's scope with the body's steps not run yet.

func (*Program) Bind 

func (p *Program) Bind(s Scope, step string, output []byte) (Scope, error)

Bind is s with the output (JSON) of a step that ran.

func (*Program) BindItems 

func (p *Program) BindItems(s Scope, step string, outputs [][]byte, failed []ItemError) (Scope, error)

BindItems is s with a for-each step done: its variable the list of the items' outputs (JSON; nil: null — skipped or failed), its state the failed items.

func (*Program) Body 

func (p *Program) Body(step string) (*Program, bool)

Body is the sub-flow of a for-each step whose body is steps.

func (*Program) Eval 

func (p *Program) Eval(src string, vars map[string]any) (any, error)

Eval evaluates src in the program's environment over vars (a Scope's Vars, possibly changed): the console's playground, tests. src is compiled on every call.

func (*Program) Groups 

func (p *Program) Groups() [][]string

Groups are the steps by level: a group's steps depend only on steps of lower groups; within a group by name. The executor does not wait for a whole group: a step starts once its Deps are done.

func (*Program) Hash added in v0.6.10 

func (p *Program) Hash() string

Hash names the program by its content: hex SHA-256 of Spec.

func (*Program) Input 

func (p *Program) Input(step string, s Scope) ([]byte, error)

Input is the step's activity input (JSON) on s.

func (*Program) ItemOutput 

func (p *Program) ItemOutput(s Scope) ([]byte, error)

ItemOutput is an item's output (JSON) in the step's list: the activity's output, or the body's result on its final scope.

func (*Program) ItemScope 

func (p *Program) ItemScope(step string, s Scope, index int, item any) (Scope, error)

ItemScope is s with a for-each step's item and its position bound: the scope its when, input, undo input and body see.

func (*Program) Items 

func (p *Program) Items(step string, s Scope) ([]any, error)

Items are the items a for-each step runs for on s: a list as is, a map as {key, value} by key.

func (*Program) Kind 

func (p *Program) Kind() Kind

Kind is what the program implements.

func (*Program) MarshalJSON 

func (p *Program) MarshalJSON() ([]byte, error)

MarshalJSON is the program's serialized form: a workflow takes it as input and evaluates exactly what was compiled.

func (*Program) Masks added in v0.6.10 

func (p *Program) Masks() *redact.Program

Masks is what the console hides of a run of the program: the secrets of its input, calls and result. Shared: read only.

func (*Program) Match 

func (p *Program) Match(s Scope) (bool, error)

Match is a rule's when on the scope of StartEvent: false — ack the event without a run. A binding, or a rule without when, matches.

func (*Program) Result 

func (p *Program) Result(s Scope) ([]byte, error)

Result is a binding's output (JSON) on s: the hook's answer.

func (*Program) Runtime added in v0.3.0 

func (p *Program) Runtime() consolev1.Runtime

Runtime is what runs the program: Temporal or direct.

func (*Program) Skip 

func (p *Program) Skip(s Scope, step string) (Scope, error)

Skip is s with a step skipped by its when: its variable is {} and steps.<name>.skipped is true. Steps depending on it still run.

func (*Program) Source 

func (p *Program) Source() string

Source is the hook or event name.

func (*Program) Spec added in v0.6.10 

func (p *Program) Spec() []byte

Spec is MarshalJSON's bytes without the copy: read, never written. A for-each body (KindBody) has none.

func (*Program) Start 

func (p *Program) Start(input []byte) (Scope, error)

Start is the scope of a binding's run on the hook's input (JSON).

func (*Program) StartEvent 

func (p *Program) StartEvent(payload []byte, meta Meta) (Scope, error)

StartEvent is the scope of a rule's run on an event: its payload (JSON) and attributes.

func (*Program) Step 

func (p *Program) Step(name string) (StepPlan, bool)

Step is one step by name.

func (*Program) Steps 

func (p *Program) Steps() []StepPlan

Steps are the steps by name.

func (*Program) UndoInput 

func (p *Program) UndoInput(step string, s Scope) ([]byte, error)

UndoInput is the input (JSON) of the step's undo activity on s: its undo input, else the step's own output.

func (*Program) UnmarshalJSON 

func (p *Program) UnmarshalJSON(data []byte) error

UnmarshalJSON rebuilds a marshaled program. Only for a new zero Program (json.Unmarshal into one): a Program is not modified once built.

func (*Program) When 

func (p *Program) When(step string, s Scope) (bool, error)

When is the step's when on s; a step without one runs.

type Publisher added in v0.6.8 

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

Publisher keeps BoundPrefix equal to the bindings in force: a pass at start, after every Changes signal and every publishResync. Replicas run it side by side; they all write what PostgreSQL holds.

func NewPublisher added in v0.6.8 

func NewPublisher(parent deps.Scope, m *Manager, consul *api.Client) *Publisher

NewPublisher creates the component under parent.

type Range 

type Range struct {
	Start int
	End   int
}

Range is a span of an expression's text in Unicode code points; End is exclusive.

func (Range) IsZero 

func (r Range) IsZero() bool

IsZero reports whether the range is unset.

type Reference 

type Reference struct {
	Path     string
	Variable string
	Fields   []string
	Expr     Range
}

Reference is one read of a variable by the expression at Path.

type Retry 

type Retry struct {
	// Attempts in total, the first included.
	Attempts        int           `json:"attempts"`
	InitialInterval time.Duration `json:"initial_interval"`
	MaxInterval     time.Duration `json:"max_interval"`
	// Backoff multiplies the interval after each attempt (>= 1).
	Backoff float64 `json:"backoff"`
}

Retry is a step's retry policy; zero fields are unset.

func (Retry) IsZero 

func (r Retry) IsZero() bool

IsZero reports whether no field is set.

type Rule 

type Rule struct {
	// Event is the full event name "<service>.<Event>".
	Event string
	// When is a CEL bool over `event` and `meta`; empty: always.
	When        string
	Description string
	// Steps are sorted by name, as Binding.Steps.
	Steps []Step
	// Runtime runs the rule; unspecified: the installation's default.
	Runtime consolev1.Runtime
	Editor  *consolev1.EditorLayout
}

Rule is the definition of a rule.

func RuleFromPB 

func RuleFromPB(m *consolev1.RuleDefinition) Rule

RuleFromPB is the definition a message carries.

func RuleYAML 

func RuleYAML(text string) (Rule, error)

RuleYAML reads a rule definition from YAML, as BindingYAML.

func (Rule) Equal 

func (r Rule) Equal(o Rule) bool

Equal reports whether two definitions say the same.

func (Rule) PB 

func (r Rule) PB() *consolev1.RuleDefinition

PB is the definition as a message.

type RuleAPI 

type RuleAPI struct {
	consolev1.UnimplementedRuleServiceServer
	// contains filtered or unexported fields
}

RuleAPI is the Manager as backplane.console.v1.RuleService.

func (RuleAPI) DeleteRule 

func (a RuleAPI) DeleteRule(
	ctx context.Context, req *consolev1.DeleteRuleRequest,
) (*consolev1.DeleteRuleResponse, error)

DeleteRule implements RuleService.

func (RuleAPI) GetRule 

func (a RuleAPI) GetRule(ctx context.Context, req *consolev1.GetRuleRequest) (*consolev1.GetRuleResponse, error)

GetRule implements RuleService.

func (RuleAPI) ListRuleVersions 

func (a RuleAPI) ListRuleVersions(
	ctx context.Context, req *consolev1.ListRuleVersionsRequest,
) (*consolev1.ListRuleVersionsResponse, error)

ListRuleVersions implements RuleService.

func (RuleAPI) ListRules 

func (a RuleAPI) ListRules(ctx context.Context, req *consolev1.ListRulesRequest) (*consolev1.ListRulesResponse, error)

ListRules implements RuleService.

func (RuleAPI) PauseRule 

func (a RuleAPI) PauseRule(ctx context.Context, req *consolev1.PauseRuleRequest) (*consolev1.PauseRuleResponse, error)

PauseRule implements RuleService.

func (RuleAPI) ResumeRule 

func (a RuleAPI) ResumeRule(
	ctx context.Context, req *consolev1.ResumeRuleRequest,
) (*consolev1.ResumeRuleResponse, error)

ResumeRule implements RuleService.

func (RuleAPI) RollbackRule 

func (a RuleAPI) RollbackRule(
	ctx context.Context, req *consolev1.RollbackRuleRequest,
) (*consolev1.RollbackRuleResponse, error)

RollbackRule implements RuleService.

func (RuleAPI) SaveRule 

func (a RuleAPI) SaveRule(ctx context.Context, req *consolev1.SaveRuleRequest) (*consolev1.SaveRuleResponse, error)

SaveRule implements RuleService.

func (RuleAPI) ValidateRule 

func (a RuleAPI) ValidateRule(
	_ context.Context, req *consolev1.ValidateRuleRequest,
) (*consolev1.ValidateRuleResponse, error)

ValidateRule implements RuleService (the name is not checked: it is not part of the definition).

func (RuleAPI) WatchRules 

func (a RuleAPI) WatchRules(
	req *consolev1.WatchRulesRequest, stream grpc.ServerStreamingServer[consolev1.WatchRulesResponse],
) error

WatchRules implements RuleService: the list now, then again whenever it differs.

type RuleEntry 

type RuleEntry struct {
	ID uuid.UUID
	// Paused: no runs start.
	Paused    bool
	CreatedAt time.Time
	UpdatedAt time.Time
	Current   RuleVersion
}

RuleEntry is a rule with its current version.

func (RuleEntry) Active 

func (r RuleEntry) Active() bool

Active reports whether the rule runs: not deleted, not paused.

func (RuleEntry) PB 

func (r RuleEntry) PB() *consolev1.Rule

PB is the rule as a message.

type RuleVersion 

type RuleVersion struct {
	RuleID  uuid.UUID
	Version int64
	Name    string
	// Rule is the definition; zero on a tombstone.
	Rule Rule
	// Deleted marks a tombstone: the delete of the rule.
	Deleted    bool
	Author     string
	Comment    string
	CreatedAt  time.Time
	RollbackOf int64 // 0: not a rollback
	// ManagedBy as BindingVersion's.
	ManagedBy string
}

RuleVersion is one saved version of a rule.

func (RuleVersion) PB 

func (v RuleVersion) PB() *consolev1.RuleVersion

PB is the version as a message.

type Saved 

type Saved struct {
	Version    BindingVersion
	Violations []Violation
}

Saved is the outcome of a save: the version, or the violations the definition was rejected with.

type SavedRule 

type SavedRule struct {
	Version    RuleVersion
	Violations []Violation
}

SavedRule is the outcome of a rule's save.

type Scope 

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

Scope is what expressions see at one point of a run: the input, the outputs of the steps done so far and which steps were skipped. It is a value: Bind and Skip return a new Scope and leave the old one as it was.

func (Scope) Vars 

func (s Scope) Vars() map[string]any

Vars is a copy of the scope's variables (values as CEL sees them).

type Step 

type Step struct {
	// Name is an identifier unique in the definition (its key): the CEL
	// variable of the step's output.
	Name string
	// Activity is the full activity name "<service>.<Activity>".
	Activity string
	// Input of the activity; zero: {}.
	Input Value
	// When is a CEL bool: the step runs only when true; empty: always.
	When string
	// After names steps this one runs after besides those its expressions
	// reference.
	After []string
	// Undo is the compensating activity (full name) run when a later step
	// fails; empty: none.
	Undo string
	// UndoInput is the undo activity's input; zero: the step's output.
	UndoInput Value
	// Retry: zero fields take the activity's defaults, then the platform's.
	Retry Retry
	// StartToClose bounds one attempt; 0: the activity's default, then the
	// platform's.
	StartToClose time.Duration
	// Heartbeat: an attempt silent this long is lost; 0: the activity's
	// default, else none.
	Heartbeat   time.Duration
	Description string

	// ForEach is a CEL list or map: the step runs once per item. Empty: once.
	ForEach string
	// As names the item variable; empty: "item". Its position is
	// "<As>Index".
	As string
	// Concurrency bounds the items in flight; 0: DefaultConcurrency.
	Concurrency int
	// OnError is OnErrorFail (default, also empty) or OnErrorContinue.
	OnError string
	// MaxItems bounds the items; 0: DefaultMaxItems.
	MaxItems int
	// Steps are the body of a for-each step as a sub-flow, sorted by name;
	// exclusive with Activity.
	Steps []Step
	// Result is each item's result when the body is Steps; zero: {}.
	Result Value
}

Step is one call of an activity.

func (Step) ItemVar 

func (s Step) ItemVar() string

ItemVar is the name of the item variable of a for-each step.

type StepAnalysis 

type StepAnalysis struct {
	Name string
	// Level is 0 for a step that depends on nothing, else one above its
	// highest dependency; -1 in a cycle or with an invalid name.
	Level int
	// Data, After and When are the steps its input, `after` and `when`
	// make it depend on; Undo the steps its undo input reads.
	Data, After, When, Undo []string
	// Parent is the for-each step whose body the step is in; "" at the top.
	Parent string
	// ItemType is the CEL type of a for-each step's item; "" without.
	ItemType string
}

StepAnalysis is where a step stands in the order of execution.

type StepPlan 

type StepPlan struct {
	Name     string `json:"name"`
	Activity string `json:"activity"`
	// Service owns the activity: its task queue (§17).
	Service string `json:"service"`
	// Kind: a Temporal activity, or a workflow run as a child workflow.
	Kind backplanev1.ActivityKind `json:"kind"`
	// Deps are the steps this one waits for: its `after` and every step
	// its input and when read.
	Deps []string `json:"deps,omitempty"`
	// Group is the step's level in Program.Groups: every dependency is in
	// a lower group.
	Group int `json:"group"`
	// Conditional: the step has a when (Program.When decides).
	Conditional bool `json:"conditional,omitempty"`
	// Undo is the compensating activity, empty for none; UndoService and
	// UndoKind as Service and Kind.
	Undo        string                   `json:"undo,omitempty"`
	UndoService string                   `json:"undo_service,omitempty"`
	UndoKind    backplanev1.ActivityKind `json:"undo_kind,omitempty"`
	// Retry is resolved: every field set.
	Retry        Retry         `json:"retry"`
	StartToClose time.Duration `json:"start_to_close"`
	// Heartbeat 0: none.
	Heartbeat time.Duration `json:"heartbeat,omitempty"`
	// ForEach: the step runs once per item; nil: once.
	ForEach *ForEachPlan `json:"for_each,omitempty"`
}

StepPlan is a step as the executor runs it: the activity, where it runs, what it waits for and its resolved options.

type Value 

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

Value is a value built by CEL: a JSON tree (google.protobuf.Value) whose strings are CEL expressions, objects are built field by field, lists item by item, and numbers, booleans and null are literals. Zero: unset, the default of its place. A Value is immutable: its tree is never changed after construction.

func Expr 

func Expr(src string) Value

Expr is a Value of one expression.

func ParseValue 

func ParseValue(data []byte) (Value, error)

ParseValue reads a Value from its JSON form; empty or "null" text is unset.

func ValueOf 

func ValueOf(m *structpb.Value) Value

ValueOf is the Value of a message; nil: unset. The message is copied.

func (Value) Equal 

func (v Value) Equal(o Value) bool

Equal reports whether two values say the same.

func (Value) Expr 

func (v Value) Expr() string

Expr is the expression of a ValueExpr node.

func (Value) Expressions 

func (v Value) Expressions(base string) []PathExpr

Expressions are the value's expressions with their JSON Pointers under base, in path order.

func (Value) Fields 

func (v Value) Fields() []Field

Fields are an object node's fields by name.

func (Value) IsZero 

func (v Value) IsZero() bool

IsZero reports whether the value is unset.

func (Value) Items 

func (v Value) Items() []Value

Items are a list node's items.

func (Value) JSON 

func (v Value) JSON() []byte

JSON is the Value's JSON form; nil when unset.

func (Value) Kind 

func (v Value) Kind() ValueKind

Kind is what the node is.

func (Value) Literal 

func (v Value) Literal() any

Literal is a literal node as JSON decodes it: float64, bool or nil.

func (Value) PB 

func (v Value) PB() *structpb.Value

PB is the Value as a message (a copy); nil when unset.

type ValueKind 

type ValueKind int

ValueKind is what a Value node is. 

const (
	// ValueUnset: the zero Value.
	ValueUnset ValueKind = iota
	// ValueExpr: a CEL expression (a JSON string).
	ValueExpr
	// ValueObject: an object built field by field.
	ValueObject
	// ValueList: a list built item by item.
	ValueList
	// ValueLiteral: a number, a boolean or null.
	ValueLiteral
)

Kinds of Value nodes.

type ValueType 

type ValueType struct {
	Path string
	Type string
}

ValueType is the CEL type of a value node.

type Violation 

type Violation struct {
	// Path is the JSON Pointer of the place in the definition
	// ("/steps/send/input/to"); empty for the whole definition.
	Path    string
	Code    string
	Message string
	// Expr is where in the expression at Path the problem is; zero when
	// it is the place itself.
	Expr Range
}

Violation is one reason a definition is rejected.

func ValidateBinding 

func ValidateBinding(b Binding, cat Catalog) ([]Violation, error)

ValidateBinding checks b against the catalog: every violation, empty when valid. The error is a failure to validate, not a violation.

func ValidateRule 

func ValidateRule(r Rule, cat Catalog) ([]Violation, error)

ValidateRule checks r against the catalog, as ValidateBinding.

func (Violation) String 

func (v Violation) String() string

type WiringAPI 

type WiringAPI struct {
	consolev1.UnimplementedWiringServiceServer
	// contains filtered or unexported fields
}

WiringAPI is the Manager as backplane.console.v1.WiringService: the wiring editor's catalog, analysis and refactoring. Nothing here saves.

func (WiringAPI) AnalyzeBinding 

func (a WiringAPI) AnalyzeBinding(
	_ context.Context, req *consolev1.AnalyzeBindingRequest,
) (*consolev1.AnalyzeBindingResponse, error)

AnalyzeBinding implements WiringService.

func (WiringAPI) AnalyzeRule 

func (a WiringAPI) AnalyzeRule(
	_ context.Context, req *consolev1.AnalyzeRuleRequest,
) (*consolev1.AnalyzeRuleResponse, error)

AnalyzeRule implements WiringService.

func (WiringAPI) GetWiringCatalog 

func (a WiringAPI) GetWiringCatalog(
	context.Context, *consolev1.GetWiringCatalogRequest,
) (*consolev1.GetWiringCatalogResponse, error)

GetWiringCatalog implements WiringService: every service's hooks, activities and events from its latest manifest.

func (WiringAPI) RenameStep 

func (a WiringAPI) RenameStep(
	_ context.Context, req *consolev1.RenameStepRequest,
) (*consolev1.RenameStepResponse, error)

RenameStep implements WiringService.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.