Merge pull request #217 from cschleiden/error-handling2

Improve error handling

Author: cschleiden

README.md

@@ -314,7 +314,7 @@ func Workflow2(ctx workflow.Context, msg string) (string, error) {
 From a workflow, call `workflow.ExecuteActivity` to execute an activity. The call returns a `Future[T]` you can await to get the result or any error it might return.
 
 ```go
-r1, err := workflow.ExecuteActivity[int](ctx, Activity1, 35, 12, nil, "test").Get(ctx)
+r1, err := workflow.ExecuteActivity[int](ctx, workflow.DefaultActivityOptions, Activity1, 35, 12, nil, "test").Get(ctx)
 if err != nil {
 	panic("error getting activity 1 result")
 }
@@ -423,9 +423,86 @@ func SubWorkflow(ctx workflow.Context, msg string) (int, error) {
 
 Similar to timer cancellation, you can pass a cancelable context to `CreateSubWorkflowInstance` and cancel the sub-workflow that way. Reacting to the cancellation is the same as canceling a workflow via the `Client`. See [Canceling workflows](#canceling-workflows) for more details.
 
+### Error handling
+
+#### Custom errors
+
+Errors returned from activities and subworkflows need to be marshalled/unmarshalled by the library so they are wrapped in a `workflow.Error`. You can access the original type via the `err.Type` field. If a stacktrace was captured, you can access it via `err.Stack()`. Example (see also `samples/errors`):
+
+```go
+func handleError(ctx workflow.Context, logger log.Logger, err error) {
+	var werr *workflow.Error
+	if errors.As(err, &werr) {
+		switch werr.Type {
+		case "CustomError": // This was a `type CustomError struct...` returned by an activity/subworkflow
+			logger.Error("Custom error", "err", werr)
+			return
+		}
+
+		logger.Error("Generic workflow error", "err", werr, "stack", werr.Stack())
+		return
+	}
+
+	var perr *workflow.PanicError
+	if errors.As(err, &perr) {
+		// Activity/subworkflow ran into a panic
+		logger.Error("Panic", "err", perr, "stack", perr.Stack())
+		return
+	}
+
+	logger.Error("Generic error", "err", err)
+}
+```
+
+#### Panics
+
+A panic in an activity will be captured by the library and made available as a `workflow.PanicError` in the calling workflow. Example:
+
+
+```go
+r1, err := workflow.ExecuteActivity[int](ctx, workflow.DefaultActivityOptions, Activity1, "test").Get(ctx)
+if err != nil {
+	panic("error getting activity 1 result")
+}
+
+var perr *workflow.PanicError
+if errors.As(err, &perr) {
+	logger.Error("Panic", "err", perr, "stack", perr.Stack())
+	return
+}
+```
+
+#### Retries
+
+With the default `DefaultActivityOptions`, Activities are retried up to three times when they return an error. If you want to keep automatic retries, but want to avoid them when hitting certain error types, you can wrap an error with `workflow.NewPermanentError`:
+
+**Workflow**:
+
+```go
+r1, err := workflow.ExecuteActivity[int](ctx, workflow.DefaultActivityOptions, Activity1, "test").Get(ctx)
+if err != nil {
+	panic("error getting activity 1 result")
+}
+
+log.Println(r1)
+```
+
+**Activity**:
+
+```go
+func Activity1(ctx context.Context, name string) (int, error) {
+	if name == "test" {
+		// No need to retry in this case, the activity will aways fail with the given inputs
+		return 0, workflow.NewPermanentError(errors.New("test is not a valid name"))
+	}
+
+	return http.Do("POST", "https://example.com", name)
+}
+```
+
 ### `ContinueAsNew`
 
-```ContinueAsNew` allows you to restart workflow execution with different inputs. The purpose is to keep the history size small enough to avoid hitting size limits, running out of memory and impacting performance. It works by returning a special `error` from your workflow that contains the new inputs:
+`ContinueAsNew` allows you to restart workflow execution with different inputs. The purpose is to keep the history size small enough to avoid hitting size limits, running out of memory and impacting performance. It works by returning a special `error` from your workflow that contains the new inputs:
 
 ```go
 wf := func(ctx workflow.Context, run int) (int, error) {

backend/test/e2e.go

@@ -19,13 +19,15 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
+type backendTest struct {
+	name         string
+	options      []backend.BackendOption
+	withoutCache bool // If set, test will only be run when the cache is disabled
+	f            func(t *testing.T, ctx context.Context, c client.Client, w worker.Worker, b TestBackend)
+}
+
 func EndToEndBackendTest(t *testing.T, setup func(options ...backend.BackendOption) TestBackend, teardown func(b TestBackend)) {
-	tests := []struct {
-		name         string
-		options      []backend.BackendOption
-		withoutCache bool // If set, test will only be run when the cache is disabled
-		f            func(t *testing.T, ctx context.Context, c client.Client, w worker.Worker, b TestBackend)
-	}{
+	tests := []backendTest{
 		{
 			name: "SimpleWorkflow",
 			f: func(t *testing.T, ctx context.Context, c client.Client, w worker.Worker, b TestBackend) {
@@ -659,6 +661,8 @@ func EndToEndBackendTest(t *testing.T, setup func(options ...backend.BackendOpti
 		},
 	}
 
+	tests = append(tests, e2eActivityTests...)
+
 	run := func(suffix string, workerOptions *worker.Options) {
 		for _, tt := range tests {
 			if tt.withoutCache && workerOptions.WorkflowExecutorCache != nil {

backend/test/e2e_activity.go

@@ -0,0 +1,77 @@
+package test
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/cschleiden/go-workflows/client"
+	"github.com/cschleiden/go-workflows/worker"
+	"github.com/cschleiden/go-workflows/workflow"
+	"github.com/stretchr/testify/require"
+)
+
+type CustomError struct {
+	msg string
+}
+
+func (e *CustomError) Error() string {
+	return e.msg
+}
+
+var e2eActivityTests = []backendTest{
+	{
+		name: "Activity_Panic",
+		f: func(t *testing.T, ctx context.Context, c client.Client, w worker.Worker, b TestBackend) {
+			a := func(context.Context) error {
+				panic("activity panic")
+			}
+
+			wf := func(ctx workflow.Context) (bool, error) {
+				_, err := workflow.ExecuteActivity[int](ctx, workflow.ActivityOptions{
+					RetryOptions: workflow.RetryOptions{
+						MaxAttempts: 1,
+					},
+				}, a).Get(ctx)
+
+				var perr *workflow.PanicError
+				return errors.As(err, &perr), nil
+			}
+			register(t, ctx, w, []interface{}{wf}, []interface{}{a})
+
+			output, err := runWorkflowWithResult[bool](t, ctx, c, wf)
+
+			require.True(t, output, "error should be PanicError")
+			require.NoError(t, err)
+		},
+	},
+	{
+		name: "Activity_CustomError",
+		f: func(t *testing.T, ctx context.Context, c client.Client, w worker.Worker, b TestBackend) {
+			a := func(context.Context) error {
+				return &CustomError{msg: "custom error"}
+			}
+
+			wf := func(ctx workflow.Context) (bool, error) {
+				_, err := workflow.ExecuteActivity[int](ctx, workflow.ActivityOptions{
+					RetryOptions: workflow.RetryOptions{
+						MaxAttempts: 1,
+					},
+				}, a).Get(ctx)
+
+				var werr *workflow.Error
+				if errors.As(err, &werr) {
+					return werr.Type == "CustomError" && werr.Error() == "custom error", nil
+				}
+
+				return false, nil
+			}
+			register(t, ctx, w, []interface{}{wf}, []interface{}{a})
+
+			output, err := runWorkflowWithResult[bool](t, ctx, c, wf)
+
+			require.True(t, output, "error should be PanicError")
+			require.NoError(t, err)
+		},
+	},
+}

client/client.go

@@ -14,6 +14,7 @@ import (
 	"github.com/cschleiden/go-workflows/internal/fn"
 	"github.com/cschleiden/go-workflows/internal/history"
 	"github.com/cschleiden/go-workflows/internal/metrickeys"
+	"github.com/cschleiden/go-workflows/internal/workflowerrors"
 	"github.com/cschleiden/go-workflows/log"
 	"github.com/cschleiden/go-workflows/metrics"
 	"github.com/cschleiden/go-workflows/workflow"
@@ -195,7 +196,7 @@ func GetWorkflowResult[T any](ctx context.Context, c Client, instance *workflow.
 		return *new(T), fmt.Errorf("workflow did not finish in time: %w", err)
 	}
 
-	h, err := b.GetWorkflowInstanceHistory(ctx, instance, nil)
+	h, err := b.GetWorkflowInstanceHistory(ctx, instance, nil) // future: could optimize this by retriving only the very last entry in the history
 	if err != nil {
 		return *new(T), fmt.Errorf("getting workflow history: %w", err)
 	}
@@ -206,8 +207,8 @@ func GetWorkflowResult[T any](ctx context.Context, c Client, instance *workflow.
 		switch event.Type {
 		case history.EventType_WorkflowExecutionFinished:
 			a := event.Attributes.(*history.ExecutionCompletedAttributes)
-			if a.Error != "" {
-				return *new(T), errors.New(a.Error)
+			if a.Error != nil {
+				return *new(T), workflowerrors.ToError(a.Error)
 			}
 
 			var r T

client/client_test.go

@@ -80,7 +80,7 @@ func Test_Client_GetWorkflowResultSuccess(t *testing.T) {
 		history.NewHistoryEvent(1, time.Now(), history.EventType_WorkflowExecutionStarted, &history.ExecutionStartedAttributes{}),
 		history.NewHistoryEvent(2, time.Now(), history.EventType_WorkflowExecutionFinished, &history.ExecutionCompletedAttributes{
 			Result: r,
-			Error:  "",
+			Error:  nil,
 		}),
 	}, nil)
 	b.On("Converter").Return(converter.DefaultConverter)

diag/app/build/asset-manifest.json

@@ -1,13 +1,13 @@
 {
   "files": {
     "main.css": "./static/css/main.8b0db0ad.css",
-    "main.js": "./static/js/main.cf32ac93.js",
+    "main.js": "./static/js/main.b236aa1e.js",
     "index.html": "./index.html",
     "main.8b0db0ad.css.map": "./static/css/main.8b0db0ad.css.map",
-    "main.cf32ac93.js.map": "./static/js/main.cf32ac93.js.map"
+    "main.b236aa1e.js.map": "./static/js/main.b236aa1e.js.map"
   },
   "entrypoints": [
     "static/css/main.8b0db0ad.css",
-    "static/js/main.cf32ac93.js"
+    "static/js/main.b236aa1e.js"
   ]
 }

diag/app/build/index.html

@@ -1 +1 @@
-<!doctype html><html lang="en"><head><meta charset="utf-8"/><meta name="viewport" content="width=device-width,initial-scale=1"/><meta name="theme-color" content="#000000"/><title>go-workflows</title><script defer="defer" src="./static/js/main.cf32ac93.js"></script><link href="./static/css/main.8b0db0ad.css" rel="stylesheet"></head><body><noscript>You need to enable JavaScript to run this app.</noscript><div id="root"></div></body></html>
+<!doctype html><html lang="en"><head><meta charset="utf-8"/><meta name="viewport" content="width=device-width,initial-scale=1"/><meta name="theme-color" content="#000000"/><title>go-workflows</title><script defer="defer" src="./static/js/main.b236aa1e.js"></script><link href="./static/css/main.8b0db0ad.css" rel="stylesheet"></head><body><noscript>You need to enable JavaScript to run this app.</noscript><div id="root"></div></body></html>