temporal

package
v1.26.1 Latest Latest
Warning

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

 Go to latest Published: Apr 10, 2024 License: MIT Imports: 5 Imported by: 211

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

View Source 
const (
	// VersioningIntentUnspecified indicates that the SDK should choose the most sensible default
	// behavior for the type of command, accounting for whether the command will be run on the same
	// task queue as the current worker.
	// WARNING: Worker versioning is currently experimental
	VersioningIntentUnspecified = internal.VersioningIntentUnspecified
	// VersioningIntentCompatible indicates that the command should run on a worker with compatible
	// version if possible. It may not be possible if the target task queue does not also have
	// knowledge of the current worker's build ID.
	// WARNING: Worker versioning is currently experimental
	VersioningIntentCompatible = internal.VersioningIntentCompatible
	// VersioningIntentDefault indicates that the command should run on the target task queue's
	// current overall-default build ID.
	// WARNING: Worker versioning is currently experimental
	VersioningIntentDefault = internal.VersioningIntentDefault
)
View Source 
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

View Source 
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 added in v1.18.0 

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 NewApplicationErrorWithOptions added in v1.26.0 

func NewApplicationErrorWithOptions(msg, errType string, options ApplicationErrorOptions) error

NewApplicationErrorWithOptions creates new instance of *ApplicationError type, all the options of the newly created error could be controlled through instance of ApplicationErrorOptions. The options structure also receives some extra requests. See activity.ApplicationErrorOptions for details.

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 ApplicationErrorOptions added in v1.26.0 

type ApplicationErrorOptions = internal.ApplicationErrorOptions

ApplicationErrorOptions should be used to set all the desired attributes of a new ApplicationError To get a new instance use ErrorAttributes function

type CanceledError 

type CanceledError = internal.CanceledError

CanceledError returned when operation was canceled.

type ChildWorkflowExecutionAlreadyStartedError added in v1.11.0 

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 added in v1.18.0 

type DefaultFailureConverter = internal.DefaultFailureConverter

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

func NewDefaultFailureConverter added in v1.18.0 

func NewDefaultFailureConverter(opt DefaultFailureConverterOptions) *DefaultFailureConverter

NewDefaultFailureConverter creates new instance of DefaultFailureConverter.

type DefaultFailureConverterOptions added in v1.18.0 

type DefaultFailureConverterOptions = internal.DefaultFailureConverterOptions

DefaultFailureConverterOptions are optional parameters for DefaultFailureConverter creation.

type NamespaceNotFoundError added in v1.15.0 

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 SearchAttributeKey added in v1.26.0 

type SearchAttributeKey = internal.SearchAttributeKey

SearchAttributeKey represents a typed search attribute key.

type SearchAttributeKeyBool added in v1.26.0 

type SearchAttributeKeyBool = internal.SearchAttributeKeyBool

SearchAttributeKeyBool represents a search attribute key for a boolean attribute type. Create with NewSearchAttributeKeyBool.

func NewSearchAttributeKeyBool added in v1.26.0 

func NewSearchAttributeKeyBool(name string) SearchAttributeKeyBool

NewSearchAttributeKeyBool creates a new bool-based key.

type SearchAttributeKeyFloat64 added in v1.26.0 

type SearchAttributeKeyFloat64 = internal.SearchAttributeKeyFloat64

SearchAttributeKeyFloat64 represents a search attribute key for a double attribute type. Create with NewSearchAttributeKeyFloat64.

func NewSearchAttributeKeyFloat64 added in v1.26.0 

func NewSearchAttributeKeyFloat64(name string) SearchAttributeKeyFloat64

NewSearchAttributeKeyFloat64 creates a new float64-based key.

type SearchAttributeKeyInt64 added in v1.26.0 

type SearchAttributeKeyInt64 = internal.SearchAttributeKeyInt64

SearchAttributeKeyInt64 represents a search attribute key for a integer attribute type. Create with NewSearchAttributeKeyInt64.

func NewSearchAttributeKeyInt64 added in v1.26.0 

func NewSearchAttributeKeyInt64(name string) SearchAttributeKeyInt64

NewSearchAttributeKeyInt64 creates a new int64-based key.

type SearchAttributeKeyKeyword added in v1.26.0 

type SearchAttributeKeyKeyword = internal.SearchAttributeKeyKeyword

SearchAttributeKeyKeyword represents a search attribute key for a keyword attribute type. Create with NewSearchAttributeKeyKeyword.

func NewSearchAttributeKeyKeyword added in v1.26.0 

func NewSearchAttributeKeyKeyword(name string) SearchAttributeKeyKeyword

NewSearchAttributeKeyKeyword creates a new keyword-based key.

type SearchAttributeKeyKeywordList added in v1.26.0 

type SearchAttributeKeyKeywordList = internal.SearchAttributeKeyKeywordList

SearchAttributeKeyKeywordList represents a search attribute key for a keyword list attribute type. Create with NewSearchAttributeKeyKeywordList.

func NewSearchAttributeKeyKeywordList added in v1.26.0 

func NewSearchAttributeKeyKeywordList(name string) SearchAttributeKeyKeywordList

NewSearchAttributeKeyKeywordList creates a new keyword-list-based key.

type SearchAttributeKeyString added in v1.26.0 

type SearchAttributeKeyString = internal.SearchAttributeKeyString

SearchAttributeKeyString represents a search attribute key for a text attribute type. Create with NewSearchAttributeKeyString.

func NewSearchAttributeKeyString added in v1.26.0 

func NewSearchAttributeKeyString(name string) SearchAttributeKeyString

NewSearchAttributeKeyString creates a new string-based key.

type SearchAttributeKeyTime added in v1.26.0 

type SearchAttributeKeyTime = internal.SearchAttributeKeyTime

SearchAttributeKeyTime represents a search attribute key for a time attribute type. Create with NewSearchAttributeKeyTime.

func NewSearchAttributeKeyTime added in v1.26.0 

func NewSearchAttributeKeyTime(name string) SearchAttributeKeyTime

NewSearchAttributeKeyTime creates a new time-based key.

type SearchAttributeUpdate added in v1.26.0 

type SearchAttributeUpdate = internal.SearchAttributeUpdate

SearchAttributesUpdate represents a change to SearchAttributes.

type SearchAttributes added in v1.26.0 

type SearchAttributes = internal.SearchAttributes

SearchAttributes represents a collection of typed search attributes. Create with NewSearchAttributes.

func NewSearchAttributes added in v1.26.0 

func NewSearchAttributes(attributes ...SearchAttributeUpdate) SearchAttributes

NewSearchAttributes creates a new search attribute collection for the given updates.

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 VersioningIntent added in v1.23.0 

type VersioningIntent = internal.VersioningIntent

VersioningIntent indicates whether the user intends certain commands to be run on a compatible worker build ID version or not. WARNING: Worker versioning is currently experimental

type WorkflowExecutionError 

type WorkflowExecutionError = internal.WorkflowExecutionError

WorkflowExecutionError returned from workflow.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.