direct

package
v0.6.38 Latest Latest
Warning

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

Go to latest
Published: Oct 23, 2026 License: MIT Imports: 39 Imported by: 0

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

View Source
const (
	// DefaultRunTimeout bounds a rule's run (a hook call is bounded by its
	// deadline).
	DefaultRunTimeout = 5 * time.Minute
	// DefaultRetention of recorded runs.
	DefaultRetention = 7 * 24 * time.Hour
)

Defaults of the runtime.

Variables

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

View Source
var ErrAlreadyStarted = errors.New("direct: run already started")

ErrAlreadyStarted: a run with the id exists and is running or completed.

View Source
var ErrNoRun = errors.New("direct: no such run")

ErrNoRun: no run with the id.

Functions

func Readable

func Readable(err error) (string, string)

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.

func Retryable

func Retryable(err error) bool

Retryable reports whether a retry of the run may succeed.

func RunID

func RunID(workflowID string) string

RunID of a rule's event on the direct runtime, for the dedup check.

func Status

func Status(err error) error

Status is a run's error as a HookService status: the CallFailure detail carries the type and whether retrying can help. A timeout is DEADLINE_EXCEEDED, a cancellation CANCELED; the rest ABORTED — the call reached backplane and the run failed, which UNAVAILABLE would not say.

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) *Activities

NewActivities creates the transport over the registry, presenting the installation's internal secret.

func (*Activities) Call

Call implements Caller.

func (*Activities) Close

func (a *Activities) Close()

Close closes every connection.

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

CancelBindingRun implements BindingService.

func (BindingAPI) GetBindingRun

GetBindingRun implements BindingService.

func (BindingAPI) ListBindingRuns

ListBindingRuns implements BindingService.

func (BindingAPI) TestBinding

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.

func (*Failure) Error

func (f *Failure) Error() string

func (*Failure) Unwrap

func (f *Failure) Unwrap() error

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

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 Info

type Info struct {
	ID      string
	Kind    Kind
	Source  string
	Version int64
	Test    bool
}

Info is what a run is: for the console's binding and rule run RPCs.

type Kind

type Kind string

Kind is what a run executes.

const (
	KindBinding Kind = "binding"
	KindRule    Kind = "rule"
)

Kinds of runs.

type NopRecorder

type NopRecorder struct{}

NopRecorder records nothing.

func (NopRecorder) Completed

func (NopRecorder) Completed(string, []byte, time.Time)

Completed implements Recorder.

func (NopRecorder) Failed

func (NopRecorder) Failed(string, string, string, time.Time)

Failed implements Recorder.

func (NopRecorder) Scheduled

func (NopRecorder) Scheduled(string, string, string, int, string, []byte, time.Time)

Scheduled implements Recorder.

type Option

type Option func(*Service)

Option configures New.

func Author

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

Author names who made a console call from its context.

func Retention

func Retention(d time.Duration) Option

Retention of recorded runs; 0 keeps them.

func RunTimeout

func RunTimeout(d time.Duration) Option

RunTimeout bounds a rule's run; default DefaultRunTimeout.

func WithCaller

func WithCaller(c Caller) Option

WithCaller replaces the activity transport (tests).

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 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 is running or completed is ErrAlreadyStarted (the engine acks it), one whose run failed 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.

func NewRunner

func NewRunner(acts Caller) *Runner

NewRunner creates a runner calling activities through acts.

func (*Runner) Execute

func (r *Runner) Execute(ctx context.Context, run Run, rec Recorder) ([]byte, error)

Execute runs one program on its input within ctx and is the hook's answer (JSON; {} for a rule). The error is a *Failure, or ctx's.

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

func NewRuns(st deps.Dependency[*store.Store], log *xlog.Logger, drops func()) *Runs

NewRuns creates the recorder over the store; drops is told of every record lost to a full queue (nil: none).

func (*Runs) Begin

func (r *Runs) Begin(s Start, prog *redact.Program)

Begin records the start of a run that needs no dedup (a hook call, a test), asynchronously.

func (*Runs) Claim

func (r *Runs) Claim(ctx context.Context, s Start, prog *redact.Program) (bool, error)

Claim records the start of a run, synchronously: false (and no error) when a run with the id is running or completed already — the event was handled — true when it is new or a failed one is run again. The store being unavailable is an error: the caller decides whether to run blind.

func (*Runs) Expire

func (r *Runs) Expire(ctx context.Context, cutoff time.Time) error

Expire deletes the runs started before cutoff, a batch at a time.

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

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) Outcome added in v0.6.35

func (r *Runs) Outcome(ctx context.Context, id string) ([]byte, bool, error)

Outcome is how run id ended: its reply when it completed, a *Failure when it failed or was canceled; done is false while it is running.

func (*Runs) Recorder

func (r *Runs) Recorder(id string, prog *redact.Program) RunRecorder

Recorder is the RunRecorder of one run: steps masked by its program.

func (*Runs) Sweep added in v0.6.10

func (r *Runs) Sweep(ctx context.Context, cutoff time.Time) (int64, error)

Sweep closes the runs still running since before cutoff: their end was never recorded (the record was lost, or the replica died with the run). They end failed and incomplete; how many.

func (*Runs) Write

func (r *Runs) Write(ctx context.Context) error

Write runs the writer until ctx ends, then drains what is queued within the stop budget.

type Service

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

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

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

func (s *Service) Cancel(id string) bool

Cancel stops a run in flight on this replica; false when it is not running here.

func (*Service) CancelRun

func (s *Service) CancelRun(id string) error

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

func (s *Service) Execute(ctx context.Context, start Start, run Run, claim bool) ([]byte, error)

Execute runs one program and records it: the run begins (Begin, or Claim when claim is set — then a run already handled is ErrAlreadyStarted), runs within ctx, and ends. The run can be canceled by id while it runs.

func (*Service) GetRuleRun

func (s *Service) GetRuleRun(ctx context.Context, id string) (*consolev1.GetRuleRunResponse, error)

GetRuleRun is one direct rule run for the rules engine's GetRuleRun.

func (*Service) HookService

func (s *Service) HookService() HookAPI

HookService is the server.

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

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

func (s *Service) Required(hook, instance string) bool

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

func (s *Service) RunTimeout() time.Duration

RunTimeout bounds a rule's run.

func (*Service) Runs

func (s *Service) Runs() *Runs

Runs is the run store, for the console.

func (*Service) Runtime added in v0.5.0

func (s *Service) Runtime(ctx context.Context, hook string) (consolev1.Runtime, error)

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) String

func (s *Service) String() string

String names the service in logs.

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
}

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

func ParseToken(data []byte) (Token, error)

ParseToken reads a token; empty is the first page.

func (Token) Bytes

func (t Token) Bytes() []byte

Bytes is the token's wire form.

type Versions

type Versions interface {
	Version(ctx context.Context, hook string, version int64) (bindings.BindingVersion, error)
}

Versions is what the console's test needs of bindings besides Bindings: *bindings.Manager.

Jump to

Keyboard shortcuts

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