temporal

README

Temporal Go SDK

Temporal is a distributed, scalable, durable, and highly available orchestration engine used to execute asynchronous long-running business logic in a scalable and resilient way.

temporal-go-sdk is the framework for authoring workflows and activities using Go language.

How to use

Clone this repo into the preferred location.

git clone git@github.com:temporalio/temporal-go-sdk.git

or

go get go.temporal.io/temporal

See samples to get started.

Documentation is available here. You can also find the API documentation here.

Contributing

We'd love your help in making the Temporal Go SDK great. Please review our contribution guidelines.

License

MIT License, please see LICENSE for details.

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 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
• type ActivityError
• type ApplicationError
  • func NewApplicationError(message string, details ...interface{}) *ApplicationError
  • func NewApplicationErrorWithCause(message string, cause error, details ...interface{}) *ApplicationError
  • func NewNonRetryableApplicationError(message string, cause error, details ...interface{}) *ApplicationError
• type CanceledError
  • func NewCanceledError(details ...interface{}) *CanceledError
• type ChildWorkflowExecutionError
• type PanicError
• type RetryPolicy
• type ServerError
• type TerminatedError
• type TimeoutError
  • func NewHeartbeatTimeoutError(details ...interface{}) *TimeoutError
  • func NewTimeoutError(timeoutType enumspb.TimeoutType, lastErr error, details ...interface{}) *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 = internal.ErrNoData

ErrNoData is returned when trying to extract strong typed data while there is no data available.

Functions

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

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.

func NewApplicationError

func NewApplicationError(message string, details ...interface{}) *ApplicationError

NewApplicationError creates new instance of retryable *ApplicationError with message and optional details. Use ApplicationError for any use case specific errors that cross activity and child workflow boundaries.

func NewApplicationErrorWithCause

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

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

func NewNonRetryableApplicationError

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

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

type CanceledError

type CanceledError = internal.CanceledError

CanceledError returned when operation was canceled.

func NewCanceledError

func NewCanceledError(details ...interface{}) *CanceledError

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

type ChildWorkflowExecutionError

type ChildWorkflowExecutionError = internal.ChildWorkflowExecutionError

ChildWorkflowExecutionError returned from workflow when child workflow returned an error.

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.

func NewHeartbeatTimeoutError

func NewHeartbeatTimeoutError(details ...interface{}) *TimeoutError

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 NewTimeoutError

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

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.

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.