temporal

package
v0.6.15 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 2026 License: MIT Imports: 35 Imported by: 0

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

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

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

func CheckName(kind, name string)

CheckName validates a declaration name.

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

func HookDeadline(ctx workflow.Context, d time.Duration) *durationpb.Duration

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

func HookWorkflowID(service, name, suffix string) string

HookWorkflowID is the id of the CallHook workflow of <service>.<name> under suffix (a uuid, or the call's key).

func HooksQueue

func HooksQueue(service string) string

HooksQueue is the task queue of service's CallHook workflows.

func Inject

func Inject(ctx context.Context) map[string]string

Inject is the W3C trace context of ctx for an envelope.

func Local

func Local(err error) error

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.

func WorkflowTrace

func WorkflowTrace(ctx workflow.Context) map[string]string

WorkflowTrace is the trace context of the workflow's current span (set by the tracing interceptor), for an envelope; nil without one.

Types

type Client

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

Client is the service's Temporal connection and workers.

func New

func New(p Params) *Client

New creates the client; nothing connects until Connect.

func (*Client) Call

func (c *Client) Call(ctx context.Context, hook string, in []byte) ([]byte, error)

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

func (c *Client) Close(ctx context.Context) error

Close closes the connection; a dial still in flight is dropped.

func (*Client) Connect

func (c *Client) Connect(ctx context.Context, g node.Group) error

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

func (c *Client) Connected() bool

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

func (c *Client) SDK() (client.Client, error)

SDK is the connected Temporal client for the author's own workflows; ErrUnavailable while not connected.

func (*Client) StartHookWorker

func (c *Client) StartHookWorker(_ context.Context, g node.Group) error

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

func (c *Client) StartWorker(_ context.Context, g node.Group) error

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

func (c *Client) StopHookWorker(ctx context.Context) error

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.

func (*Client) StopWorker

func (c *Client) StopWorker(ctx context.Context) error

StopWorker stops polling and lets running activities finish within ctx; past it the stop goes on in the background and is logged.

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.

type Tuning

type Tuning struct {
	MaxConcurrentActivities    int
	MaxConcurrentWorkflowTasks int
	ActivityPollers            int
	WorkflowPollers            int
}

Tuning of the worker; a zero field is Temporal's default.

type WorkflowHandler

type WorkflowHandler func(ctx workflow.Context, in []byte) ([]byte, error)

WorkflowHandler is a workflow-backed activity over JSON payloads.

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.

Jump to

Keyboard shortcuts

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