Documentation
¶
Overview ¶
Package temporal runs the service's activities and hook calls on Temporal (design §7.2, §9).
Names: task queue = service name; activity type = activity name as declared; hook = Nexus operation <Name> of Nexus service <service>.Hooks on endpoint <service>. A hook raised outside workflow code runs through the short workflow backplane.CallHook.v1 on the service's hooks queue <service>.hooks, served by a worker of its own, id hook/<service>/<Name>/<uuid> or, with a key, hook/<service>/<Name>/<key>.
Index ¶
- Constants
- func ActivityFunc(service, name string, h env.Handler) ...
- func CheckName(kind, name string)
- func ExecuteHook(ctx workflow.Context, call *backplanev1.HookCall) (*backplanev1.HookResult, error)
- func HookDeadline(ctx workflow.Context, d time.Duration) *durationpb.Duration
- func HookWorkflowID(service, name, suffix string) string
- func HooksQueue(service string) string
- func Inject(ctx context.Context) map[string]string
- func Local(err error) error
- func WorkflowActivity(service, name string, h WorkflowHandler) ...
- func WorkflowTrace(ctx workflow.Context) map[string]string
- type Client
- func (c *Client) Alive() error
- func (c *Client) Call(ctx context.Context, hook string, in []byte) ([]byte, error)
- func (c *Client) Close(ctx context.Context) error
- func (c *Client) Connect(ctx context.Context, g node.Group) error
- func (c *Client) Connected() bool
- func (c *Client) SDK() (client.Client, error)
- func (c *Client) StartHookWorker(_ context.Context, g node.Group) error
- func (c *Client) StartWorker(_ context.Context, g node.Group) error
- func (c *Client) StopHookWorker(ctx context.Context) error
- func (c *Client) StopWorker(ctx context.Context) error
- type Params
- type Tuning
- type WorkflowHandler
Constants ¶
const ( // CallHookWorkflow runs one hook call raised outside workflow code, on // the hooks queue. The version is in the name: a change of its code // that is not replay-compatible is a new name (.v2), registered next // to the old one until runs of the old one are gone. CallHookWorkflow = wire.CallHookWorkflow // HooksSuffix: the Nexus service of <service>'s hooks is // <service>.Hooks on endpoint <service>. HooksSuffix = wire.HooksSuffix // NoBindingType is the application error type backplane fails a hook // call with when the hook has no binding. NoBindingType = wire.NoBindingType // HookFailedType: the hook call failed; the message says why. HookFailedType = wire.HookFailedType // TimeoutType: the hook call ran out of its deadline. TimeoutType = wire.TimeoutType // NonRetryableType: an activity handler marked its error final. NonRetryableType = wire.NonRetryableType )
Contract with backplane, the Nexus handler of hooks.
const ( MemoSource = wire.MemoSource AttrService = wire.AttrService AttrHook = wire.AttrHook )
Memo and search attributes of a hook call's workflow (§14): who raised it. The search attributes are set only when the namespace has them (Keyword); the memo always.
Variables ¶
This section is empty.
Functions ¶
func ActivityFunc ¶
func ActivityFunc( service, name string, h env.Handler, ) func(ctx context.Context, call *backplanev1.ActivityCall) (*backplanev1.ActivityResult, error)
ActivityFunc adapts a declared activity's handler to the Temporal activity the worker registers: the envelope, the handler's env.ActivityInfo and the error mapping of the worker, without the worker's tracing, metrics and panic recovery. backplanetest registers it on a testsuite environment.
func ExecuteHook ¶
func ExecuteHook(ctx workflow.Context, call *backplanev1.HookCall) (*backplanev1.HookResult, error)
ExecuteHook raises a hook from workflow code: Nexus operation <Name> of service <service>.Hooks on endpoint <service>, where call.hook is "<service>.<Name>". call.deadline, when set, is the operation's schedule-to-close timeout. The error is a non-retryable application error with a readable message: type NoBindingType, TimeoutType or HookFailedType.
func HookDeadline ¶
HookDeadline is the deadline of a hook call from workflow code: d, cut to what is left of the current run's timeout when the run has one. d is the call's timeout, the declared one or the platform default — never zero, so the call is never unbounded.
func HookWorkflowID ¶
HookWorkflowID is the id of the CallHook workflow of <service>.<name> under suffix (a uuid, or the call's key).
func HooksQueue ¶
HooksQueue is the task queue of service's CallHook workflows.
func Local ¶
Local maps a hook failure to what the caller sees: env.ErrNoBinding, context.DeadlineExceeded, or an error with the handler's message whose chain keeps the Temporal error.
func WorkflowActivity ¶
func WorkflowActivity( service, name string, h WorkflowHandler, ) func(ctx workflow.Context, call *backplanev1.ActivityCall) (*backplanev1.ActivityResult, error)
WorkflowActivity adapts h to the workflow a binding step runs as a child workflow by name on the service's queue: input ActivityCall, output ActivityResult. Errors map as for activities: an application error passes as is, env.NonRetryable becomes a non-retryable one, messages are prefixed with <service>.<Name>. A panic is Temporal's: the workflow task fails and is retried, the run waits for a fixed worker.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the service's Temporal connection and workers.
func (*Client) Alive ¶ added in v0.6.72
Alive is always nil: the Temporal client's gRPC connection reconnects with capped backoff for as long as it is not closed, so no state of it needs a restart.
func (*Client) Call ¶
Call implements env.Caller: a hook call from outside a workflow. It runs the workflow backplane.CallHook.v1 on the hooks queue <service>.hooks, which raises the Nexus operation, and waits for it within ctx (Params.HookTimeout when ctx has no deadline).
With a key (env.WithCallKey) the workflow id is hook/<service>/<Name>/<key>: a call while one with the key runs joins it, a call after one with the key completed gets its result without running again, a call after one with the key failed runs anew. Temporal keeps a completed run for the namespace's retention; past it the key is forgotten.
func (*Client) Connect ¶
Connect dials without blocking on an unreachable Temporal: after one short attempt it keeps retrying on g and returns. Until connected, Call fails fast with env.ErrUnavailable and the workers wait. Once connected, the connection is checked on g every few seconds (Connected). A TLS setting that cannot work is an error.
func (*Client) Connected ¶
Connected reports whether the client holds a connection that answered its last check: false before the first dial succeeds, after Close, and while the connection's health check fails.
func (*Client) SDK ¶
SDK is the connected Temporal client for the author's own workflows; ErrUnavailable while not connected.
func (*Client) StartHookWorker ¶
StartHookWorker runs the hooks worker: CallHookWorkflow alone on the hooks queue <service>.hooks. Hook calls from outside workflow code run there, so they work from the start of the author's tree to its stop — the main worker (StartWorker) starts after the tree and stops before it.
The hooks queue is its own, not the service's: a worker polling a queue fails the workflow tasks of the types it lacks, so a queue is served only by workers registering the same types. The hooks worker runs on every replica that has hooks, whatever worker.enabled says: it is what makes Call work there.
Like StartWorker it does not wait for Temporal: the worker starts on g as soon as the connection is up, retrying a failed start. Nothing starts when the service declared no hooks.
func (*Client) StartWorker ¶
StartWorker runs the service's worker on its task queue: every declared activity and the workflows registered through Env (the author's own, the workflow-backed activities). It does not wait for Temporal: the worker starts on g as soon as the connection is up, retrying a failed start. Hook calls have their own worker (StartHookWorker).
func (*Client) StopHookWorker ¶
StopHookWorker stops the hooks worker within ctx. A CallHook run in flight is not lost: Temporal hands its next task to another replica's hooks worker, or to this service's next start.
type Params ¶
type Params struct {
// Conn is the connection: address, namespace, TLS, API key, dial
// timeout (one attempt; Connect makes one before going to the
// background).
Conn inftemporal.Config
Service string
Instance string
Log *xlog.Logger
Env *env.Env
Worker Tuning
// HookTimeout is the deadline of a hook call nothing else bounds; 0 is
// env.DefaultHookTimeout. New installs it on Env for workflows.CallHook.
HookTimeout time.Duration
}
Params of New.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package temporaltest runs the SDK's Temporal tests against a dev server (BACKPLANE_TEST_TEMPORAL, e.g.
|
Package temporaltest runs the SDK's Temporal tests against a dev server (BACKPLANE_TEST_TEMPORAL, e.g. |