temporal

Documentation

Overview

Package temporal and its subdirectories contain the Temporal client side framework.

The Temporal service is a task orchestrator for your application’s tasks. Applications using Temporal can execute a logical flow of tasks, especially long-running business logic, asynchronously or synchronously. They can also scale at runtime on distributed systems.

A quick example illustrates its use case. Consider Uber Eats where Temporal manages the entire business flow from placing an order, accepting it, handling shopping cart processes (adding, updating, and calculating cart items), entering the order in a pipeline (for preparing food and coordinating delivery), to scheduling delivery as well as handling payments.

Temporal consists of a programming framework (or client library) and a managed service (or backend). The framework enables developers to author and coordinate tasks in Go code.

The root temporal package contains common data structures. The subpackages are:

• workflow - functions used to implement workflows
• activity - functions used to implement activities
• client - functions used to create Temporal service client used to start and monitor workflow executions.
• worker - functions used to create worker instance used to host workflow and activity code.
• testsuite - unit testing framework for activity and workflow testing

How Temporal works

The Temporal hosted service brokers and persists events generated during workflow execution. Worker nodes owned and operated by customers execute the coordination and task logic. To facilitate the implementation of worker nodes Temporal provides a client-side library for the Go language.

In Temporal, you can code the logical flow of events separately as a workflow and code business logic as activities. The workflow identifies the activities and sequences them, while an activity executes the logic.

Key Features

Dynamic workflow execution graphs - Determine the workflow execution graphs at runtime based on the data you are processing. Temporal does not pre-compute the execution graphs at compile time or at workflow start time. Therefore, you have the ability to write workflows that can dynamically adjust to the amount of data they are processing. If you need to trigger 10 instances of an activity to efficiently process all the data in one run, but only 3 for a subsequent run, you can do that.

Child Workflows - Orchestrate the execution of a workflow from within another workflow. Temporal will return the results of the child workflow execution to the parent workflow upon completion of the child workflow. No polling is required in the parent workflow to monitor status of the child workflow, making the process efficient and fault tolerant.

Durable Timers - Implement delayed execution of tasks in your workflows that are robust to worker failures. Temporal provides two easy to use APIs, **workflow.Sleep** and **workflow.Timer**, for implementing time based events in your workflows. Temporal ensures that the timer settings are persisted and the events are generated even if workers executing the workflow crash.

Signals - Modify/influence the execution path of a running workflow by pushing additional data directly to the workflow using a signal. Via the Signal facility, Temporal provides a mechanism to consume external events directly in workflow code.

Task routing - Efficiently process large amounts of data using a Temporal workflow, by caching the data locally on a worker and executing all activities meant to process that data on that same worker. Temporal enables you to choose the worker you want to execute a certain activity by scheduling that activity execution in the worker's specific task queue.

Unique workflow ID enforcement - Use business entity IDs for your workflows and let Temporal ensure that only one workflow is running for a particular entity at a time. Temporal implements an atomic "uniqueness check" and ensures that no race conditions are possible that would result in multiple workflow executions for the same workflow ID. Therefore, you can implement your code to attempt to start a workflow without checking if the ID is already in use, even in the cases where only one active execution per workflow ID is desired.

Perpetual/ContinueAsNew workflows - Run periodic tasks as a single perpetually running workflow. With the "ContinueAsNew" facility, Temporal allows you to leverage the "unique workflow ID enforcement" feature for periodic workflows. Temporal will complete the current execution and start the new execution atomically, ensuring you get to keep your workflow ID. By starting a new execution Temporal also ensures that workflow execution history does not grow indefinitely for perpetual workflows.

At-most once activity execution - Execute non-idempotent activities as part of your workflows. Temporal will not automatically retry activities on failure. For every activity execution Temporal will return a success result, a failure result, or a timeout to the workflow code and let the workflow code determine how each one of those result types should be handled.

Asynch Activity Completion - Incorporate human input or thrid-party service asynchronous callbacks into your workflows. Temporal allows a workflow to pause execution on an activity and wait for an external actor to resume it with a callback. During this pause the activity does not have any actively executing code, such as a polling loop, and is merely an entry in the Temporal datastore. Therefore, the workflow is unaffected by any worker failures happening over the duration of the pause.

Activity Heartbeating - Detect unexpected failures/crashes and track progress in long running activities early. By configuring your activity to report progress periodically to the Temporal server, you can detect a crash that occurs 10 minutes into an hour-long activity execution much sooner, instead of waiting for the 60-minute execution timeout. The recorded progress before the crash gives you sufficient information to determine whether to restart the activity from the beginning or resume it from the point of failure.

Timeouts for activities and workflow executions - Protect against stuck and unresponsive activities and workflows with appropriate timeout values. Temporal requires that timeout values are provided for every activity or workflow invocation. There is no upper bound on the timeout values, so you can set timeouts that span days, weeks, or even months.

Visibility - Get a list of all your active and/or completed workflow. Explore the execution history of a particular workflow execution. Temporal provides a set of visibility APIs that allow you, the workflow owner, to monitor past and current workflow executions.

Debuggability - Replay any workflow execution history locally under a debugger. The Temporal client library provides an API to allow you to capture a stack trace from any failed workflow execution history.

Index

• Constants
• Variables
• func GetDefaultFailureConverter() converter.FailureConverter
• func IsApplicationError(err error) bool
• func IsCanceledError(err error) bool
• func IsPanicError(err error) bool
• func IsTerminatedError(err error) bool
• func IsTimeoutError(err error) bool
• func IsWorkflowExecutionAlreadyStartedError(err error) bool
• func NewApplicationError(message, errType string, details ...interface{}) error
• func NewApplicationErrorWithCause(message, errType string, cause error, details ...interface{}) error
• func NewCanceledError(details ...interface{}) error
• func NewHeartbeatTimeoutError(details ...interface{}) error
• func NewNonRetryableApplicationError(message, errType string, cause error, details ...interface{}) error
• func NewTimeoutError(timeoutType enumspb.TimeoutType, lastErr error, details ...interface{}) error
• type ActivityError
• type ApplicationError
• type CanceledError
• type ChildWorkflowExecutionAlreadyStartedError
• type ChildWorkflowExecutionError
• type DefaultFailureConverter
  • func NewDefaultFailureConverter(opt DefaultFailureConverterOptions) *DefaultFailureConverter
• type DefaultFailureConverterOptions
• type NamespaceNotFoundError
• type PanicError
• type RetryPolicy
• type ServerError
• type TerminatedError
• type TimeoutError
• type UnknownExternalWorkflowExecutionError
• type WorkflowExecutionError

Constants

const SDKVersion = internal.SDKVersion

SDKVersion is a semver that represents the version of this Temporal SDK. This represents API changes visible to Temporal SDK consumers, i.e. developers that are writing workflows. So every time we change API that can affect them we have to change this number. Format: MAJOR.MINOR.PATCH

Variables

var (
	// ErrNoData is returned when trying to extract strong typed data while there is no data available.
	ErrNoData = internal.ErrNoData

	// ErrScheduleAlreadyRunning can be returned when a schedule ID is reused
	ErrScheduleAlreadyRunning = internal.ErrScheduleAlreadyRunning

	// ErrSkipScheduleUpdate is used by a user if they want to skip updating a schedule.
	ErrSkipScheduleUpdate = internal.ErrSkipScheduleUpdate
)

Functions

func GetDefaultFailureConverter

func GetDefaultFailureConverter() converter.FailureConverter

GetDefaultDataConverter returns the default failure converter used by Temporal.

func IsApplicationError

func IsApplicationError(err error) bool

IsApplicationError return if the err is a ApplicationError

func IsCanceledError

func IsCanceledError(err error) bool

IsCanceledError return if the err is a CanceledError

func IsPanicError

func IsPanicError(err error) bool

IsPanicError return if the err is a PanicError

func IsTerminatedError

func IsTerminatedError(err error) bool

IsTerminatedError return if the err is a TerminatedError

func IsTimeoutError

func IsTimeoutError(err error) bool

IsTimeoutError return if the err is a TimeoutError

func IsWorkflowExecutionAlreadyStartedError

func IsWorkflowExecutionAlreadyStartedError(err error) bool

IsWorkflowExecutionAlreadyStartedError return if the err is a WorkflowExecutionAlreadyStartedError or if an error in the chain is a ChildWorkflowExecutionAlreadyStartedError.

func NewApplicationError

func NewApplicationError(message, errType string, details ...interface{}) error

NewApplicationError creates new instance of retryable *ApplicationError with message, type, and optional details. Use ApplicationError for any use case specific errors that cross activity and child workflow boundaries. errType can be used to control if error is retryable or not. Add the same type in to RetryPolicy.NonRetryableErrorTypes to avoid retrying of particular error types.

func NewApplicationErrorWithCause

func NewApplicationErrorWithCause(message, errType string, cause error, details ...interface{}) error

NewApplicationErrorWithCause creates new instance of retryable *ApplicationError with message, type, cause, and optional details. Use ApplicationError for any use case specific errors that cross activity and child workflow boundaries. errType can be used to control if error is retryable or not. Add the same type in to RetryPolicy.NonRetryableErrorTypes to avoid retrying of particular error types.

func NewCanceledError

func NewCanceledError(details ...interface{}) error

NewCanceledError creates CanceledError instance. Return this error from activity or child workflow to indicate that it was successfully canceled.

func NewHeartbeatTimeoutError

func NewHeartbeatTimeoutError(details ...interface{}) error

NewHeartbeatTimeoutError creates TimeoutError instance WARNING: This function is public only to support unit testing of workflows. It shouldn't be used by application level code.

func NewNonRetryableApplicationError

func NewNonRetryableApplicationError(message, errType string, cause error, details ...interface{}) error

NewNonRetryableApplicationError creates new instance of non-retryable *ApplicationError with message, type, and optional cause and details. Use ApplicationError for any use case specific errors that cross activity and child workflow boundaries.

func NewTimeoutError

func NewTimeoutError(timeoutType enumspb.TimeoutType, lastErr error, details ...interface{}) error

NewTimeoutError creates TimeoutError instance. Use NewHeartbeatTimeoutError to create heartbeat TimeoutError WARNING: This function is public only to support unit testing of workflows. It shouldn't be used by application level code.

Types

type ActivityError

type ActivityError = internal.ActivityError

ActivityError returned from workflow when activity returned an error.

type ApplicationError

type ApplicationError = internal.ApplicationError

ApplicationError returned from activity implementations with message and optional details.

type CanceledError

type CanceledError = internal.CanceledError

CanceledError returned when operation was canceled.

type ChildWorkflowExecutionAlreadyStartedError

type ChildWorkflowExecutionAlreadyStartedError = internal.ChildWorkflowExecutionAlreadyStartedError

ChildWorkflowExecutionAlreadyStartedError is set as the cause of ChildWorkflowExecutionError when failure is due the child workflow having already started.

type ChildWorkflowExecutionError

type ChildWorkflowExecutionError = internal.ChildWorkflowExecutionError

ChildWorkflowExecutionError returned from workflow when child workflow returned an error.

type DefaultFailureConverter

type DefaultFailureConverter = internal.DefaultFailureConverter

DefaultFailureConverter seralizes errors with the option to encode common parameters under Failure.EncodedAttributes.

func NewDefaultFailureConverter

func NewDefaultFailureConverter(opt DefaultFailureConverterOptions) *DefaultFailureConverter

NewDefaultFailureConverter creates new instance of DefaultFailureConverter.

type DefaultFailureConverterOptions

type DefaultFailureConverterOptions = internal.DefaultFailureConverterOptions

DefaultFailureConverterOptions are optional parameters for DefaultFailureConverter creation.

type NamespaceNotFoundError

type NamespaceNotFoundError = internal.NamespaceNotFoundError

NamespaceNotFoundError is set as the cause when failure is due namespace not found.

type PanicError

type PanicError = internal.PanicError

PanicError contains information about panicked workflow/activity.

type RetryPolicy

type RetryPolicy = internal.RetryPolicy

RetryPolicy defines the retry policy for activity/workflow.

type ServerError

type ServerError = internal.ServerError

ServerError can be returned from server.

type TerminatedError

type TerminatedError = internal.TerminatedError

TerminatedError returned when workflow was terminated.

type TimeoutError

type TimeoutError = internal.TimeoutError

TimeoutError returned when activity or child workflow timed out.

type UnknownExternalWorkflowExecutionError

type UnknownExternalWorkflowExecutionError = internal.UnknownExternalWorkflowExecutionError

UnknownExternalWorkflowExecutionError can be returned when external workflow doesn't exist

type WorkflowExecutionError

type WorkflowExecutionError = internal.WorkflowExecutionError

WorkflowExecutionError returned from workflow.