Documentation
¶
Overview ¶
Package direct is backplane's direct runtime: bindings and rules run in backplane's own process, without Temporal. Steps and expressions are the compiled program's; activities are called over gRPC on the services' platform ports (the SDK's ActivityService); a run is recorded in PostgreSQL for the console. A step's activity is retried by the step's policy (attempts, backoff, the handler's RetryAfter up to the maximum interval) within the run; a failed run is retried as a whole by its caller (a hook's) or by event redelivery (a rule's). There is no undo, no heartbeat, no child workflow — the compiler rejects a definition using them for this runtime.
Index ¶
- Constants
- Variables
- func Readable(err error) (string, string)
- func Retryable(err error) bool
- func RunID(workflowID string) string
- func Status(err error) error
- type Activities
- type BindingAPI
- func (a BindingAPI) CancelBindingRun(ctx context.Context, req *consolev1.CancelBindingRunRequest) (*consolev1.CancelBindingRunResponse, error)
- func (a BindingAPI) GetBindingRun(ctx context.Context, req *consolev1.GetBindingRunRequest) (*consolev1.GetBindingRunResponse, error)
- func (a BindingAPI) ListBindingRuns(ctx context.Context, req *consolev1.ListBindingRunsRequest) (*consolev1.ListBindingRunsResponse, error)
- func (a BindingAPI) TestBinding(ctx context.Context, req *consolev1.TestBindingRequest) (*consolev1.TestBindingResponse, error)
- type Bindings
- type Caller
- type Failure
- type HookAPI
- type Info
- type Kind
- type NopRecorder
- type Option
- type Page
- type Platform
- type Recorder
- type RuleStarter
- type Run
- type RunRecorder
- type Runner
- type Runs
- func (r *Runs) Begin(s Start, prog *redact.Program)
- func (r *Runs) Claim(ctx context.Context, s Start, prog *redact.Program) error
- func (r *Runs) Expire(ctx context.Context, cutoff time.Time) error
- func (r *Runs) Finish(id string, prog *redact.Program, result, reply []byte, err error, ...)
- func (r *Runs) Get(ctx context.Context, id string) (*consolev1.GetRunResponse, []*consolev1.StepRun, Info, error)
- func (r *Runs) List(ctx context.Context, kind Kind, source string, test bool, ...) (Page, error)
- func (r *Runs) Recorder(id string, prog *redact.Program, steps bool) RunRecorder
- func (r *Runs) Reply(ctx context.Context, id string) ([]byte, error)
- func (r *Runs) SealReplies(sealer func() seal.Sealer)
- func (r *Runs) Sweep(ctx context.Context) (int64, error)
- func (r *Runs) Write(ctx context.Context) error
- type Service
- func (s *Service) BindingService(base consolev1.BindingServiceServer, v Versions, t *TemporalBindings) BindingAPI
- func (s *Service) CallActivity(ctx context.Context, call *backplanev1.ActivityCall, timeout time.Duration) (*backplanev1.ActivityResult, error)
- func (s *Service) CallHook(ctx context.Context, call *backplanev1.HookCall) (*backplanev1.HookResult, error)
- func (s *Service) Cancel(id string) bool
- func (s *Service) CancelRun(id string) error
- func (s *Service) Execute(ctx context.Context, start Start, run Run, claim bool) ([]byte, error)
- func (s *Service) GetRuleRun(ctx context.Context, id string) (*consolev1.GetRuleRunResponse, error)
- func (s *Service) HookService() HookAPI
- func (s *Service) ListRuleRuns(ctx context.Context, rule string, test bool, st consolev1.RunStatus, ...) ([]*consolev1.Run, []byte, string, error)
- func (s *Service) Program(hook string, b bindings.Binding, version int64) (*bindings.Program, error)
- func (s *Service) RaiseHook(ctx context.Context, call *backplanev1.HookCall) (*backplanev1.HookResult, string, error)
- func (s *Service) Register(r grpc.ServiceRegistrar)
- func (s *Service) RegisterBindings(base consolev1.BindingServiceServer, v Versions, t *TemporalBindings) func(r grpc.ServiceRegistrar)
- func (s *Service) Required(hook, instance string) bool
- func (s *Service) Rules() RuleStarter
- func (s *Service) RunTimeout() time.Duration
- func (s *Service) Runs() *Runs
- func (s *Service) Runtime(ctx context.Context, hook string) (consolev1.Runtime, error)
- func (s *Service) String() string
- func (s *Service) Test(ctx context.Context, hook string, prog *bindings.Program, version int64, ...) *consolev1.CallResult
- type Start
- type TemporalBindings
- type TemporalRunner
- type Token
- type Versions
Constants ¶
const ( // DefaultRunTimeout bounds a rule's run and a hook call that brings // no deadline. DefaultRunTimeout = 5 * time.Minute // DefaultRetention of recorded runs. DefaultRetention = 7 * 24 * time.Hour )
Defaults of the runtime.
Variables ¶
var ( // ErrNotSynced: the registry has no snapshot yet. ErrNotSynced = errors.New("direct: registry not synced yet") // ErrTemporalRuntime: the definition runs on Temporal, which this // backplane does not have (or does not route hook calls to). ErrTemporalRuntime = errors.New("direct: the definition runs on the temporal runtime, which is not available") )
Errors.
var ErrAlreadyStarted = errors.New("direct: run already started")
ErrAlreadyStarted: the run of the id completed (or was canceled).
var ErrNoRun = errors.New("direct: no such run")
ErrNoRun: no run with the id.
var ErrRunning = errors.New("direct: run is running")
ErrRunning: the run of the id is running within its lease, maybe on another replica; a later claim either finds it ended or, past its lease, runs it again.
Functions ¶
func Readable ¶
Readable is the message and type of a run's error: a Failure's, a cancellation's, a deadline's; else the error's text.
Types ¶
type Activities ¶
type Activities struct {
// contains filtered or unexported fields
}
Activities calls the services' activities over their platform ports: ActivityService.Run on a serving instance whose manifest declares the activity, found in the registry. An instance that cannot be reached is not the answer: the next one is tried, once per instance.
func NewActivities ¶
func NewActivities(src registry.Source, secret string, platform Platform) *Activities
NewActivities creates the transport over the registry, presenting the installation's internal secret; platform nil dials plain.
func (*Activities) Call ¶
func (a *Activities) Call( ctx context.Context, call *backplanev1.ActivityCall, timeout time.Duration, ) (*backplanev1.ActivityResult, error)
Call implements Caller.
func (*Activities) Prune ¶
func (a *Activities) Prune()
Prune closes the connections to addresses no instance has any more.
type BindingAPI ¶
type BindingAPI struct {
consolev1.BindingServiceServer
// contains filtered or unexported fields
}
BindingAPI is BindingService: the bindings Manager's RPCs (base) with the run RPCs over the direct runtime and, when the installation has Temporal, the executor's.
func (BindingAPI) CancelBindingRun ¶
func (a BindingAPI) CancelBindingRun( ctx context.Context, req *consolev1.CancelBindingRunRequest, ) (*consolev1.CancelBindingRunResponse, error)
CancelBindingRun implements BindingService.
func (BindingAPI) GetBindingRun ¶
func (a BindingAPI) GetBindingRun( ctx context.Context, req *consolev1.GetBindingRunRequest, ) (*consolev1.GetBindingRunResponse, error)
GetBindingRun implements BindingService.
func (BindingAPI) ListBindingRuns ¶
func (a BindingAPI) ListBindingRuns( ctx context.Context, req *consolev1.ListBindingRunsRequest, ) (*consolev1.ListBindingRunsResponse, error)
ListBindingRuns implements BindingService.
func (BindingAPI) TestBinding ¶
func (a BindingAPI) TestBinding( ctx context.Context, req *consolev1.TestBindingRequest, ) (*consolev1.TestBindingResponse, error)
TestBinding implements BindingService.
type Bindings ¶
type Bindings interface {
Active(ctx context.Context, hook string) (bindings.Binding, int64, error)
Catalog() (bindings.Catalog, error)
}
Bindings is what the runtime reads of bindings: *bindings.Manager.
type Caller ¶
type Caller interface {
Call(ctx context.Context, call *backplanev1.ActivityCall, timeout time.Duration) (*backplanev1.ActivityResult, error)
}
Caller runs one activity call: the Activities transport, a fake in tests.
type Failure ¶
type Failure struct {
Msg string
Type string
// Retryable: a retry of the whole run may succeed (an activity that
// could not be reached, a retryable handler error); false: the input
// or the definition is wrong, or the handler said so.
Retryable bool
// RetryAfter: the handler asked to wait this long before retrying.
RetryAfter time.Duration
// contains filtered or unexported fields
}
Failure is a run's or a call's error as the console and the caller see it: a message, a type the binding knows and whether retrying can help.
type HookAPI ¶
type HookAPI struct {
consolev1.UnimplementedHookServiceServer
// contains filtered or unexported fields
}
HookAPI serves backplane.v1.HookService on backplane's platform port: the direct transport of the services' hook calls.
func (HookAPI) Raise ¶
func (a HookAPI) Raise(ctx context.Context, req *consolev1.RaiseRequest) (*consolev1.RaiseResponse, error)
Raise implements HookService. A call with a key (the envelope's, else the bp-call-key header) answers with the outcome of the first call with that hook and key.
type NopRecorder ¶
type NopRecorder struct{}
NopRecorder records nothing.
func (NopRecorder) Completed ¶
func (NopRecorder) Completed(string, []byte, time.Time)
Completed implements Recorder.
func (NopRecorder) Incomplete ¶ added in v0.6.68
func (NopRecorder) Incomplete() bool
Incomplete implements RunRecorder: nothing was meant to be recorded.
type Option ¶
type Option func(*Service)
Option configures New.
func RunTimeout ¶
RunTimeout bounds a rule's run and a hook call without a deadline; default DefaultRunTimeout.
func WithCaller ¶
WithCaller replaces the activity transport (tests).
func WithPlatform ¶ added in v0.6.39
WithPlatform dials the services' platform ports with p (mutual TLS when the installation serves it); without it they are dialed plain.
func WithTemporal ¶
func WithTemporal(t TemporalRunner) Option
WithTemporal installs how Temporal-runtime bindings run when called through HookService.
type Page ¶
type Page struct {
Runs []*consolev1.Run
// Next is the token of the next page; empty on the last.
Next []byte
}
Page is a page of runs.
type Platform ¶ added in v0.6.39
type Platform interface {
PlatformCredentials(target string) credentials.TransportCredentials
}
Platform is how backplane dials the services' platform ports: plain, or mutual TLS as the service (backplane.mesh.platform).
type Recorder ¶
type Recorder interface {
Scheduled(label, step, parent string, item int, activity string, input []byte, at time.Time)
Completed(label string, output []byte, at time.Time)
Failed(label, msg, typ string, at time.Time)
}
Recorder is told of every call of a run, for the console. Calls come from several goroutines.
type RuleStarter ¶
type RuleStarter struct {
// contains filtered or unexported fields
}
RuleStarter runs a rule's event on the direct runtime, inline: the rules engine's Starter for rules compiled for it. The run is complete when StartRule returns, so the engine settles the event by its outcome; a redelivery of an event whose run completed is ErrAlreadyStarted (the engine acks it), one whose run is running is ErrRunning (the engine naks it: it comes back once the run ended or outlived its lease), one whose run failed or outlived its lease (its replica died) runs again.
func (RuleStarter) StartRule ¶
func (st RuleStarter) StartRule( ctx context.Context, id string, version int64, prog *bindings.Program, event []byte, meta bindings.Meta, trace map[string]string, workflowID string, ) error
StartRule runs the rule's program on the event within RunTimeout. The run's id is workflowID with the direct prefix.
func (RuleStarter) String ¶
func (st RuleStarter) String() string
String implements fmt.Stringer for logs.
func (RuleStarter) Test ¶
func (st RuleStarter) Test( ctx context.Context, id string, version int64, prog *bindings.Program, event []byte, meta bindings.Meta, trace map[string]string, workflowID string, wait time.Duration, ) (*consolev1.CallResult, error)
Test runs a rule's test on the direct runtime and is its result as the console shows it; wait bounds the run.
type Run ¶
type Run struct {
// ID of the run: the key of every call (activity.Info.Key is
// "<id>/<label>").
ID string
Kind Kind
// Program compiled for the direct runtime.
Program *bindings.Program
// Payload is the hook's input (`req`) or the event's payload
// (`event`): JSON; empty is {}.
Payload []byte
// Meta are the event's CloudEvents attributes; rules only.
Meta bindings.Meta
// Identity names what runs: ActivityCall.binding ("<hook>@<version>").
Identity string
// Trace is the caller's W3C trace context: ActivityCall.trace of every
// step when the run's context has no span of its own.
Trace map[string]string
// Metadata of the hook call: ActivityCall.metadata of every step.
Metadata map[string]string
}
Run is one execution of a program.
type RunRecorder ¶ added in v0.6.10
type RunRecorder interface {
Recorder
// Incomplete: a step record was dropped; the run's record is not the
// whole run.
Incomplete() bool
}
RunRecorder is the Recorder of one run that also knows whether every step record it was given reached the queue.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner executes programs: the steps in dependency order, each as a goroutine calling its activity, for-each items at most Concurrency at once. The first failure cancels the calls in flight and is the run's error; nothing is compensated.
type Runs ¶
type Runs struct {
// contains filtered or unexported fields
}
Runs records runs in PostgreSQL and reads them for the console. Writes are asynchronous and in order: a run never waits for the database; a database that is down loses records, not runs. Claim is the exception: the dedup of a rule's event needs the answer.
One writer takes what is queued, up to batchSize records, and commits them in one transaction: under load a run's records cost a fraction of a commit each instead of one commit each. Run records (begin, finish) go before the step records queued at the same time; within each kind the order is the order of the calls.
func NewRuns ¶
NewRuns creates the recorder over the store; drops is told of every record lost to a full queue (nil: none).
func (*Runs) Begin ¶
Begin records the start of a run that needs no dedup (a hook call, a test), asynchronously.
func (*Runs) Claim ¶
Claim records the start of a run, synchronously: nil when it is new, or a failed one (or one past its lease) is run again; ErrAlreadyStarted when the run of the id completed (or was canceled, for an unkeyed one) — the event was handled; ErrRunning when it is running within its lease or changed meanwhile — the caller tries again later. The store being unavailable is an error: the caller decides whether to run blind.
func (*Runs) Expire ¶
Expire deletes, a batch at a time, the ended runs past their own expiry (their definition's retention) and those without one started before cutoff; a zero cutoff keeps the latter (the installation keeps runs).
func (*Runs) Finish ¶
func (r *Runs) Finish(id string, prog *redact.Program, result, reply []byte, err error, incomplete bool)
Finish records the end of a run: its result masked by prog, or its error; incomplete marks a record missing step records (Recorder.Incomplete). reply, the unmasked result, is kept for a keyed call (nil otherwise).
func (*Runs) Get ¶
func (r *Runs) Get(ctx context.Context, id string) (*consolev1.GetRunResponse, []*consolev1.StepRun, Info, error)
Get is one run as the console shows it, with its steps; ErrNoRun.
func (*Runs) List ¶
func (r *Runs) List( ctx context.Context, kind Kind, source string, test bool, status consolev1.RunStatus, pageSize uint32, token []byte, ) (Page, error)
List is the runs of a source (a hook, or "rule/<id>"), newest first: test runs or the others, optionally of one status.
func (*Runs) Recorder ¶
Recorder is the RunRecorder of one run: steps masked by its program; a no-op when the run's history keeps no steps.
func (*Runs) Reply ¶ added in v0.6.56
Reply is the kept reply of keyed run id, which completed; ErrRunning when it no longer has completed (expired meanwhile) — the caller claims it again.
func (*Runs) SealReplies ¶ added in v0.6.51
SealReplies seals the replies kept from now on with what sealer returns (nil: as they are).
type Service ¶
Service is the runtime: the component owning the activity transport, the run recorder and the runs in flight.
func New ¶
func New( parent deps.Scope, b Bindings, src registry.Source, st deps.Dependency[*store.Store], secret string, opts ...Option, ) *Service
New creates the runtime under parent: bindings from b, instances from src, runs recorded in st, activities called with the internal secret.
func (*Service) BindingService ¶
func (s *Service) BindingService(base consolev1.BindingServiceServer, v Versions, t *TemporalBindings) BindingAPI
BindingService is base with the run RPCs; t is nil without Temporal.
func (*Service) CallActivity ¶ added in v0.5.0
func (s *Service) CallActivity( ctx context.Context, call *backplanev1.ActivityCall, timeout time.Duration, ) (*backplanev1.ActivityResult, error)
CallActivity calls one activity over the direct transport (the SDK's ActivityService on the service's platform port), bounded by timeout.
func (*Service) CallHook ¶
func (s *Service) CallHook(ctx context.Context, call *backplanev1.HookCall) (*backplanev1.HookResult, error)
CallHook answers one hook call: the run of its binding on the binding's runtime, {} for an optional hook without one, or a failure. The error is a *Failure (NoBindingType, HookFailedType, the run's), ErrTemporalRuntime or the context's.
func (*Service) Cancel ¶
Cancel stops a run in flight on this replica; false when it is not running here.
func (*Service) CancelRun ¶
CancelRun cancels a direct run in flight on this replica; one not running here is FAILED_PRECONDITION: a direct run can only be canceled where it runs.
func (*Service) Execute ¶
Execute runs one program and records it: the run begins (Begin, or Claim when claim is set — then a run already handled is ErrAlreadyStarted, one running is ErrRunning), runs within ctx — within RunTimeout when ctx has no deadline — and ends. The run can be canceled by id while it runs.
func (*Service) GetRuleRun ¶
GetRuleRun is one direct rule run for the rules engine's GetRuleRun.
func (*Service) ListRuleRuns ¶
func (s *Service) ListRuleRuns( ctx context.Context, rule string, test bool, st consolev1.RunStatus, size uint32, token []byte, next func(token []byte) ([]*consolev1.Run, []byte, string, error), ) ([]*consolev1.Run, []byte, string, error)
ListRuleRuns is the rules engine's listing over both sources.
func (*Service) Program ¶
func (s *Service) Program(hook string, b bindings.Binding, version int64) (*bindings.Program, error)
Program compiles version of hook's binding against the current snapshot, once per version and snapshot, with the installation's defaults.
func (*Service) RaiseHook ¶ added in v0.5.0
func (s *Service) RaiseHook(ctx context.Context, call *backplanev1.HookCall) (*backplanev1.HookResult, string, error)
RaiseHook is CallHook that also names the run it made on the direct runtime ("" otherwise: no binding, or a Temporal run).
func (*Service) Register ¶
func (s *Service) Register(r grpc.ServiceRegistrar)
Register registers HookService on r (svc.Internal).
func (*Service) RegisterBindings ¶
func (s *Service) RegisterBindings( base consolev1.BindingServiceServer, v Versions, t *TemporalBindings, ) func(r grpc.ServiceRegistrar)
RegisterBindings registers BindingService on r.
func (*Service) Required ¶
Required reports whether hook fails without a binding: as declared by the manifest of the calling instance's version, else the latest, else any; unknown hooks are required.
func (*Service) Rules ¶
func (s *Service) Rules() RuleStarter
Rules is the engine's starter for direct rules.
func (*Service) RunTimeout ¶
RunTimeout bounds a rule's run and a hook call without a deadline.
func (*Service) Runtime ¶ added in v0.5.0
Runtime is the runtime the active binding of hook runs on; a hook without a binding answers directly ({} or NoBinding), so it is direct.
func (*Service) Test ¶
func (s *Service) Test( ctx context.Context, hook string, prog *bindings.Program, version int64, input []byte, timeout time.Duration, caller string, ) *consolev1.CallResult
Test runs a test of hook's binding on the direct runtime within timeout and is its result as the console shows it, the answer masked by the program.
type Start ¶
type Start struct {
ID string
Kind Kind
Source string
Version int64
Test bool
Caller string
// Input is the run's payload, masked by prog before it is stored.
Input []byte
// Program is the marshaled program the run runs, ProgramHash its
// Program.Hash: the run references the program by it.
Program []byte
ProgramHash string
// Keyed: a hook call with a key. A canceled run is claimed again too,
// and the unmasked result is kept for the calls that repeat it.
Keyed bool
// Lease: the run's end is recorded within it; past it, a run still
// recorded running is running nowhere and is claimed again or swept.
Lease time.Duration
// Keep: the run is deleted this long after it starts (its
// definition's retention); zero: by the installation's retention.
Keep time.Duration
// Bare: the run keeps no input or result (history record none), only
// what deduplication reads.
Bare bool
}
Start is what a run begins with.
type TemporalBindings ¶
type TemporalBindings struct {
// Test runs a test of a Temporal-runtime definition.
Test func(ctx context.Context, req *consolev1.TestBindingRequest, b bindings.Binding, version int64,
prog *bindings.Program) (*consolev1.TestBindingResponse, error)
List func(ctx context.Context, req *consolev1.ListBindingRunsRequest) (*consolev1.ListBindingRunsResponse, error)
Get func(ctx context.Context, req *consolev1.GetBindingRunRequest) (*consolev1.GetBindingRunResponse, error)
Cancel func(ctx context.Context, req *consolev1.CancelBindingRunRequest) (*consolev1.CancelBindingRunResponse, error)
}
TemporalBindings is the Temporal side of BindingService's run RPCs: the executor's. Listings put the direct runs first, then these; a run id tells which side a run is on.
type TemporalRunner ¶
type TemporalRunner interface {
RunBinding(ctx context.Context, hook string, prog *bindings.Program, version int64, call *backplanev1.HookCall,
) (*backplanev1.HookResult, error)
}
TemporalRunner runs a hook call's binding on Temporal: the executor, when the installation has it. Without one, a Temporal-runtime binding called through HookService fails with ErrTemporalRuntime.
type Token ¶
type Token struct {
Phase int `json:"p"`
Direct []byte `json:"d,omitempty"`
Temporal []byte `json:"t,omitempty"`
}
Token is the page token of a listing over the two sources of runs: the direct runs first (phase 1, their own cursor), then Temporal's (phase 2, its token).
func ParseToken ¶
ParseToken reads a token; empty is the first page.