Creating cadence.IsWorkflowError helper (#1145)

We have a variety of from-workflow errors that are relevant for users calling
`client.ExecuteWorkflow(...).Get(...)` and `client.GetWorkflow(...).Get(...)`.

Since they do not share any common wrapper or "parent type" that would allow
easy comparison with an error type check or `errors.As`, they are rather
annoying to differentiate from general RPC errors like timeouts or connection
failures.

So this adds a top-level "check all relevant types" helper, which is
intended to be a stable target for users to rely on, even if we add more
types later.  It intentionally does not tell *which* kind of error it is, in
case there are multiple types in the wrapped chain, as then behavior would
be order-dependent and any change risks breaking someone's code.

Author: Groxx

client/client.go

@@ -25,7 +25,9 @@ package client
 
 import (
 	"context"
+	"errors"
 
+	"go.uber.org/cadence"
 	"go.uber.org/cadence/.gen/go/cadence/workflowserviceclient"
 	s "go.uber.org/cadence/.gen/go/shared"
 	"go.uber.org/cadence/encoded"
@@ -450,3 +452,54 @@ func NewValue(data []byte) encoded.Value {
 func NewValues(data []byte) encoded.Values {
 	return internal.NewValues(data)
 }
+
+// IsWorkflowError returns true if an error is a known returned-by-the-workflow error type, when it comes from
+// WorkflowRun from either Client.ExecuteWorkflow or Client.GetWorkflow.  If it returns false, the error comes from
+// some other source, e.g. RPC request failures or bad arguments.
+// Using it on errors from any other source is currently undefined.
+//
+// This checks for known types via errors.As, so it will check recursively if it encounters wrapped errors.
+// Note that this is different than the various `cadence.Is[Type]Error` checks, which do not unwrap.
+//
+// Currently the complete list of errors checked is:
+// *cadence.CustomError, *cadence.CanceledError, *workflow.ContinueAsNewError,
+// *workflow.GenericError, *workflow.TimeoutError, *workflow.TerminatedError,
+// *workflow.PanicError, *workflow.UnknownExternalWorkflowExecutionError
+//
+// See documentation for each error type for details.
+func IsWorkflowError(err error) bool {
+	var custom *cadence.CustomError
+	if errors.As(err, &custom) {
+		return true
+	}
+	var cancel *cadence.CanceledError
+	if errors.As(err, &cancel) {
+		return true
+	}
+
+	var generic *workflow.GenericError
+	if errors.As(err, &generic) {
+		return true
+	}
+	var timeout *workflow.TimeoutError
+	if errors.As(err, &timeout) {
+		return true
+	}
+	var terminate *workflow.TerminatedError
+	if errors.As(err, &terminate) {
+		return true
+	}
+	var panicked *workflow.PanicError
+	if errors.As(err, &panicked) {
+		return true
+	}
+	var can *workflow.ContinueAsNewError
+	if errors.As(err, &can) {
+		return true
+	}
+	var unknown *workflow.UnknownExternalWorkflowExecutionError
+	if errors.As(err, &unknown) {
+		return true
+	}
+	return false
+}

test/integration_test.go

@@ -140,6 +140,7 @@ func (ts *IntegrationTestSuite) TearDownSuite() {
 }
 
 func (ts *IntegrationTestSuite) SetupTest() {
+	ts.Assertions = require.New(ts.T())
 	ts.seq++
 	ts.activities.clearInvoked()
 	ts.taskListName = fmt.Sprintf("tl-%v", ts.seq)
@@ -252,6 +253,7 @@ func (ts *IntegrationTestSuite) TestCancellation() {
 	ts.Error(err)
 	_, ok := err.(*cadence.CanceledError)
 	ts.True(ok)
+	ts.Truef(client.IsWorkflowError(err), "err from canceled workflows should be a workflow error: %#v", err)
 }
 
 func (ts *IntegrationTestSuite) TestStackTraceQuery() {
@@ -316,6 +318,7 @@ func (ts *IntegrationTestSuite) TestWorkflowIDReuseRejectDuplicate() {
 	gerr, ok := err.(*workflow.GenericError)
 	ts.True(ok)
 	ts.True(strings.Contains(gerr.Error(), "WorkflowExecutionAlreadyStartedError"))
+	ts.Truef(client.IsWorkflowError(err), "already-started child error should be a workflow error: %#v", err)
 }
 
 func (ts *IntegrationTestSuite) TestWorkflowIDReuseAllowDuplicateFailedOnly1() {
@@ -333,6 +336,7 @@ func (ts *IntegrationTestSuite) TestWorkflowIDReuseAllowDuplicateFailedOnly1() {
 	gerr, ok := err.(*workflow.GenericError)
 	ts.True(ok)
 	ts.True(strings.Contains(gerr.Error(), "WorkflowExecutionAlreadyStartedError"))
+	ts.Truef(client.IsWorkflowError(err), "already-started child error should be a workflow error: %#v", err)
 }
 
 func (ts *IntegrationTestSuite) TestWorkflowIDReuseAllowDuplicateFailedOnly2() {
@@ -365,15 +369,39 @@ func (ts *IntegrationTestSuite) TestWorkflowIDReuseAllowDuplicate() {
 	ts.Equal("HELLOWORLD", result)
 }
 
+func (ts *IntegrationTestSuite) TestWorkflowIDReuseErrorViaStartWorkflow() {
+	duplicatedWID := "test-workflowidreuse-duplicate-start-error"
+	// setup: run any workflow once to consume the ID
+	err := ts.executeWorkflow(
+		duplicatedWID,
+		ts.workflows.SimplestWorkflow,
+		nil,
+	)
+	ts.NoError(err, "basic workflow should succeed")
+
+	// a second attempt should fail
+	ctx, cancel := context.WithTimeout(context.Background(), ctxTimeout)
+	defer cancel()
+	opts := ts.startWorkflowOptions(duplicatedWID)
+	opts.WorkflowIDReusePolicy = client.WorkflowIDReusePolicyRejectDuplicate
+	exec, err := ts.libClient.StartWorkflow(ctx, opts, ts.workflows.SimplestWorkflow)
+	ts.Nil(exec)
+	ts.Error(err)
+	ts.IsType(&shared.WorkflowExecutionAlreadyStartedError{}, err, "should be the known already-started error type")
+	ts.False(client.IsWorkflowError(err), "start-workflow rejected errors should not be workflow errors")
+}
+
 func (ts *IntegrationTestSuite) TestChildWFRetryOnError() {
 	err := ts.executeWorkflow("test-childwf-retry-on-error", ts.workflows.ChildWorkflowRetryOnError, nil)
 	ts.Error(err)
+	ts.Truef(client.IsWorkflowError(err), "child error should be a workflow error: %#v", err)
 	ts.EqualValues([]string{"toUpper", "toUpper", "toUpper"}, ts.activities.invoked())
 }
 
 func (ts *IntegrationTestSuite) TestChildWFRetryOnTimeout() {
 	err := ts.executeWorkflow("test-childwf-retry-on-timeout", ts.workflows.ChildWorkflowRetryOnTimeout, nil)
 	ts.Error(err)
+	ts.Truef(client.IsWorkflowError(err), "child-timeout error should be a workflow error: %#v", err)
 	ts.EqualValues([]string{"sleep", "sleep", "sleep"}, ts.activities.invoked())
 }
 
@@ -434,6 +462,7 @@ func (ts *IntegrationTestSuite) TestLargeQueryResultError() {
 	ts.Nil(err)
 	value, err := ts.libClient.QueryWorkflow(ctx, "test-large-query-error", run.GetRunID(), "large_query")
 	ts.Error(err)
+	ts.False(client.IsWorkflowError(err), "query errors should not be workflow errors, as they are request-related")
 
 	queryErr, ok := err.(*shared.QueryFailedError)
 	ts.True(ok)