Documentation
¶
Overview ¶
Package workflows gives a service its own Temporal workflows (design §9): the SDK owns the connection and the worker on the service's task queue (= its name); the author registers on it and uses the client. Services of one product, released together, call each other's activities and workflows on the owner's queue with ActivityOf and WorkflowOf; a product reaches an integration (courier, templates, kratos, ...) only through hooks, which the installation binds.
workflows.Register(root, func(r worker.Registry) {
r.RegisterWorkflow(orders.Ship)
r.RegisterActivity(orders.Charge)
})
c, err := workflows.Client(scope)
run, err := c.ExecuteWorkflow(ctx, client.StartWorkflowOptions{TaskQueue: workflows.Queue(scope)}, orders.Ship, in)
Declare registers one workflow and records it in the manifest with its input and output schemas, so the console can start it with a form:
workflows.Declare(root, "Ship", orders.Ship, workflows.Describe("ships an order"))
Schedules are managed by the platform administrative API, never by SDK startup.
The worker is tuned by configuration, not code: BACKPLANE_TEMPORAL_WORKER_* (config.Worker).
Index ¶
- func Activity[Req, Res any](scope deps.Scope, name string, ...)
- func CallHook[Req, Res any](ctx workflow.Context, r hook.Ref[Req, Res], in Req, opts ...hook.CallOption) (Res, error)
- func Client(scope deps.Scope) (client.Client, error)
- func Codec(scope deps.Scope) temporal.Codec
- func Declare[In, Out any](scope deps.Scope, name string, ...)
- func Queue(scope deps.Scope) string
- func Register(scope deps.Scope, fn func(r worker.Registry))
- type ActivityRef
- type DeclareOption
- type WorkflowRef
- func (r WorkflowRef[Req, Res]) ExecuteChild(ctx workflow.Context, in Req) (Res, error)
- func (r WorkflowRef[Req, Res]) Name() string
- func (r WorkflowRef[Req, Res]) Queue() string
- func (r WorkflowRef[Req, Res]) Start(ctx context.Context, c client.Client, in Req, opts client.StartWorkflowOptions) (client.WorkflowRun, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Activity ¶
func Activity[Req, Res any]( scope deps.Scope, name string, fn func(ctx workflow.Context, in Req) (Res, error), opts ...activity.Option, )
Activity declares a workflow-backed activity: a binding step runs fn as a child workflow of type name on the service's queue, so the activity may itself wait, sleep, call hooks (workflows.CallHook) and run activities. name is CamelCase; errors map as for Handle (NonRetryable included).
func CallHook ¶
func CallHook[Req, Res any](ctx workflow.Context, r hook.Ref[Req, Res], in Req, opts ...hook.CallOption) (Res, error)
CallHook raises the hook from workflow code: the Nexus operation directly, no extra workflow. The deadline is Timeout, else the declared DefaultTimeout, else the platform default — cut to what is left of the run's timeout; a call is never unbounded. The error is readable ("hook <service>.<Name>: no binding") and matches ErrNoBinding when there is no binding.
func Client ¶
Client is the service's Temporal client. It fails with an error wrapping hook.ErrUnavailable while Temporal is not configured or not connected.
func Codec ¶ added in v0.6.51
Codec is the codec of the installation's workflow payloads (BACKPLANE_TEMPORAL_ENCRYPTION_*): history read through the raw service API is decoded with it. Without encryption it is temporal.Plain, which changes nothing.
func Declare ¶
func Declare[In, Out any]( scope deps.Scope, name string, fn func(ctx workflow.Context, in In) (Out, error), opts ...DeclareOption, )
Declare registers fn on the service's worker as workflow type name and records it in the manifest with the schemas of In and Out, so the console can start it with a form. name is CamelCase ([A-Z][A-Za-z0-9]*), anything else panics; declaring after Run panics. The input arrives through Temporal's default converter: JSON, protojson for proto messages. A workflow Declare registered is not registered again with Register.
workflows.Declare(root, "Ship", orders.Ship, workflows.Describe("ships an order"))
Types ¶
type ActivityRef ¶ added in v0.6.32
type ActivityRef[Req, Res any] struct { // contains filtered or unexported fields }
ActivityRef is an activity for workflow code to run: one of the service's own (HandleActivity), or of another service of the same product (ActivityOf), on that service's queue.
func ActivityOf ¶ added in v0.6.65
func ActivityOf[Req, Res any](service, name string) ActivityRef[Req, Res]
ActivityOf is activity name of service, another service of the same product, for workflow code to run on service's task queue. Its Execute is HandleActivity's: the owner registers name with activity.Handle or HandleActivity, so the payloads match. Services of one product are released together and may call each other this way; a product reaches an integration (courier, templates, kratos, ...) only through hooks, which the installation binds. A malformed service or name panics.
charge := workflows.ActivityOf[billing.ChargeIn, billing.ChargeOut]("billing", "ChargeCard")
receipt, err := charge.Execute(ctx, in) // ctx with workflow.WithActivityOptions
func HandleActivity ¶ added in v0.6.32
func HandleActivity[Req, Res any]( scope deps.Scope, name string, fn func(ctx context.Context, in Req) (Res, error), ) ActivityRef[Req, Res]
HandleActivity registers fn as an activity only the service's own workflows run (a saga's steps): on the service's worker, absent from the manifest, so no binding or rule can reach it. Otherwise it is activity.Handle's: payloads encoded as everywhere, fn's ctx carries activity.InfoOf and takes activity.Heartbeat, activity.NonRetryable stops the retries and activity.RetryAfter sets the next delay, a panic is a retried failure. name is CamelCase and shares the queue's activity names with activity.Handle: one taken panics.
charge := workflows.HandleActivity(root, "ChargeCard", billing.Charge) // in a workflow, with workflow.WithActivityOptions on ctx: receipt, err := charge.Execute(ctx, card)
func (ActivityRef[Req, Res]) Execute ¶ added in v0.6.32
func (r ActivityRef[Req, Res]) Execute(ctx workflow.Context, in Req) (Res, error)
Execute runs the activity from workflow code under ctx's activity options (workflow.WithActivityOptions: its timeouts and retry policy). The error keeps the Temporal error in its chain; a timeout matches context.DeadlineExceeded.
func (ActivityRef[Req, Res]) Name ¶ added in v0.6.32
func (r ActivityRef[Req, Res]) Name() string
Name is the activity's Temporal name.
type DeclareOption ¶
type DeclareOption func(w *backplanev1.Workflow)
DeclareOption tunes Declare.
func Describe ¶
func Describe(s string) DeclareOption
Describe is the workflow's description for the console.
type WorkflowRef ¶ added in v0.6.65
type WorkflowRef[Req, Res any] struct { // contains filtered or unexported fields }
WorkflowRef is workflow name of another service of the same product (WorkflowOf), run on that service's task queue.
func WorkflowOf ¶ added in v0.6.65
func WorkflowOf[Req, Res any](service, name string) WorkflowRef[Req, Res]
WorkflowOf is workflow name of service, another service of the same product, which declares it (Declare): its input and output go through Temporal's default converter, as there. A malformed service or name panics.
ship := workflows.WorkflowOf[orders.ShipIn, orders.ShipOut]("orders", "Ship")
out, err := ship.ExecuteChild(ctx, in) // from workflow code
run, err := ship.Start(ctx, c, in, client.StartWorkflowOptions{ID: "ship-" + id}) // from elsewhere
func (WorkflowRef[Req, Res]) ExecuteChild ¶ added in v0.6.65
func (r WorkflowRef[Req, Res]) ExecuteChild(ctx workflow.Context, in Req) (Res, error)
ExecuteChild runs the workflow as a child of the calling workflow, on the owner's queue, under ctx's child options (workflow.WithChildOptions: its id, timeouts, parent close policy), and waits for its result.
func (WorkflowRef[Req, Res]) Name ¶ added in v0.6.65
func (r WorkflowRef[Req, Res]) Name() string
Name is the workflow's Temporal type.
func (WorkflowRef[Req, Res]) Queue ¶ added in v0.6.65
func (r WorkflowRef[Req, Res]) Queue() string
Queue is the owner's task queue.
func (WorkflowRef[Req, Res]) Start ¶ added in v0.6.65
func (r WorkflowRef[Req, Res]) Start( ctx context.Context, c client.Client, in Req, opts client.StartWorkflowOptions, ) (client.WorkflowRun, error)
Start starts the workflow on the owner's queue with c (Client), from outside workflow code; opts.TaskQueue is set to it. Read the result with the run's Get.