IWF-405: rename and validate failure recovery policy (#278)

longquanzheng · web-flow · commit 712bae98c6c3 · 2024-12-10T13:05:08.000-08:00
diff --git a/src/main/java/io/iworkflow/core/Client.java b/src/main/java/io/iworkflow/core/Client.java
@@ -172,7 +172,7 @@ public String startWorkflow(
                 throw new WorkflowDefinitionException(String.format("input cannot be assigned to the starting state, input type: %s, starting state input type: %s", input.getClass(), registeredInputType));
             }
 
-            WorkflowStateOptions stateOptions = stateDef.getWorkflowState().getStateOptions();
+            WorkflowStateOptions stateOptions = StateMovementMapper.validateAndGetStateOptions(stateDef);
             if (shouldSkipWaitUntil(stateDef.getWorkflowState())) {
                 if (stateOptions == null) {
                     stateOptions = new WorkflowStateOptions().skipWaitUntil(true);
diff --git a/src/main/java/io/iworkflow/core/WorkflowStateOptionsExtension.java b/src/main/java/io/iworkflow/core/WorkflowStateOptionsExtension.java
@@ -1,22 +1,99 @@
 package io.iworkflow.core;
 
 import io.iworkflow.gen.models.ExecuteApiFailurePolicy;
+import io.iworkflow.gen.models.WaitUntilApiFailurePolicy;
 import io.iworkflow.gen.models.WorkflowStateOptions;
 
-// WorkflowStateOptionsExtension provides extension to WorkflowStateOptions
-// to make it easier to build
+/**
+ * WorkflowStateOptionsExtension provides extension to WorkflowStateOptions
+ * to make it easier to build some fields of the stateOptions.
+ * This is also because WorkflowState interface uses WorkflowStateOptions
+ * directly instead of using a separate model.
+ * See <a href="https://github.com/indeedeng/iwf-java-sdk/issues/200">TODO</a>
+ * Example usage in a state implementation:
+ *     public WorkflowStateOptions getStateOptions() {
+ *         return new WorkflowStateOptionsExtension()
+ *                 .setProceedAfterRetryExhaustedOnExecute(StateRecoverBasic.class)
+ *                 .executeApiRetryPolicy(
+ *                         new RetryPolicy()
+ *                                 .maximumAttempts(10)
+ *                 );
+ *     }
+ */
 public class WorkflowStateOptionsExtension extends WorkflowStateOptions {
 
+    /**
+     * By default, workflow would fail after execute API retry exhausted.
+     * Set the state to proceed to the specified state after the execute API exhausted all retries
+     * This is useful for some advanced use cases like SAGA pattern.
+     * RetryPolicy is required to be set with maximumAttempts or maximumAttemptsDurationSeconds for execute API.
+     * NOTE: The proceeding state will take the same input as the failed state that proceeded from.
+     * See more in <a href="https://github.com/indeedeng/iwf/wiki/WorkflowStateOptions">wiki</a>
+     * @param proceedingState the state to proceed to
+     * @return this
+     */
+    public WorkflowStateOptionsExtension setProceedWhenExecuteRetryExhausted(
+            final Class<? extends WorkflowState> proceedingState) {
+        return this.setProceedOnExecuteFailure(proceedingState);
+    }
+
+    /**
+     * By default, workflow would fail after execute API retry exhausted.
+     * Set the state to proceed to the specified state after the execute API exhausted all retries
+     * This is useful for some advanced use cases like SAGA pattern.
+     * RetryPolicy is required to be set with maximumAttempts or maximumAttemptsDurationSeconds for execute API.
+     * NOTE: The proceeding state will take the same input as the failed state that proceeded from.
+     * See more in <a href="https://github.com/indeedeng/iwf/wiki/WorkflowStateOptions">wiki</a>
+     * @param proceedingState the state to proceed to
+     * @param stateOptionsOverride the stateOptions for the proceeding state. This is for a rare case that you
+     *                             need to override the stateOptions returned from state instance.
+     * @return this
+     */
+    public WorkflowStateOptionsExtension setProceedWhenExecuteRetryExhausted(
+            final Class<? extends WorkflowState> proceedingState, WorkflowStateOptions stateOptionsOverride) {
+        return this.setProceedOnExecuteFailure(proceedingState, stateOptionsOverride);
+    }
+
+    /**
+     * By default, workflow would fail after waitUntil API retry exhausted.
+     * If set to true, then after waitUntil API exhausted all retries, proceed to the execute API
+     * This is useful for some advanced use cases like SAGA pattern.
+     * RetryPolicy is required to be set with maximumAttempts or maximumAttemptsDurationSeconds for waitUntil API.
+     * NOTE: execute API will use commandResults to check whether the waitUntil has succeeded or not.
+     * See more in <a href="https://github.com/indeedeng/iwf/wiki/WorkflowStateOptions">wiki</a>
+     * @param proceed true to proceed
+     * @return this
+     */
+    public WorkflowStateOptionsExtension setProceedWhenWaitUntilRetryExhausted(boolean proceed){
+        if(proceed){
+            this.waitUntilApiFailurePolicy(WaitUntilApiFailurePolicy.PROCEED_ON_FAILURE);
+        }else{
+            this.waitUntilApiFailurePolicy(WaitUntilApiFailurePolicy.FAIL_WORKFLOW_ON_FAILURE);
+        }
+
+        return this;
+    }
+
+    /**
+     * Use setProceedAfterRetryExhaustedOnExecuteFailure instead.
+     * It's a renaming for better clarity.
+     */
+    @Deprecated
     public WorkflowStateOptionsExtension setProceedOnExecuteFailure(final Class<? extends WorkflowState> proceedingState) {
         this.executeApiFailurePolicy(ExecuteApiFailurePolicy.PROCEED_TO_CONFIGURED_STATE);
         this.executeApiFailureProceedStateId(proceedingState.getSimpleName());
         return this;
     }
 
-    public WorkflowStateOptionsExtension setProceedOnExecuteFailure(final Class<? extends WorkflowState> proceedingState, WorkflowStateOptions stateOptions) {
+    /**
+     * Use setProceedAfterRetryExhaustedOnExecuteFailure instead
+     * It's a renaming for better clarity.
+     */
+    @Deprecated
+    public WorkflowStateOptionsExtension setProceedOnExecuteFailure(final Class<? extends WorkflowState> proceedingState, WorkflowStateOptions stateOptionsOverride) {
         this.executeApiFailurePolicy(ExecuteApiFailurePolicy.PROCEED_TO_CONFIGURED_STATE);
         this.executeApiFailureProceedStateId(proceedingState.getSimpleName());
-        this.executeApiFailureProceedStateOptions(stateOptions);
+        this.executeApiFailureProceedStateOptions(stateOptionsOverride);
         return this;
     }
 }
diff --git a/src/main/java/io/iworkflow/core/mapper/StateMovementMapper.java b/src/main/java/io/iworkflow/core/mapper/StateMovementMapper.java
@@ -4,8 +4,11 @@
 import io.iworkflow.core.Registry;
 import io.iworkflow.core.StateDef;
 import io.iworkflow.core.WorkflowDefinitionException;
+import io.iworkflow.core.WorkflowState;
 import io.iworkflow.gen.models.ExecuteApiFailurePolicy;
+import io.iworkflow.gen.models.RetryPolicy;
 import io.iworkflow.gen.models.StateMovement;
+import io.iworkflow.gen.models.WaitUntilApiFailurePolicy;
 import io.iworkflow.gen.models.WorkflowStateOptions;
 
 import static io.iworkflow.core.StateMovement.RESERVED_STATE_ID_PREFIX;
@@ -27,7 +30,7 @@ public static StateMovement toGenerated(final io.iworkflow.core.StateMovement st
             // Try to get the overrode stateOptions, if it's null, get the stateOptions from stateDef
             WorkflowStateOptions stateOptions = stateMovement.getStateOptionsOverride().orElse(null);
             if (stateOptions == null) {
-                stateOptions = stateDef.getWorkflowState().getStateOptions();
+                stateOptions = StateMovementMapper.validateAndGetStateOptions(stateDef);
             }
 
             if (shouldSkipWaitUntil(stateDef.getWorkflowState())) {
@@ -59,7 +62,7 @@ public static void autoFillFailureProceedingStateOptions(WorkflowStateOptions st
             // fill the state options for the proceeding state
             String proceedStateId = stateOptions.getExecuteApiFailureProceedStateId();
             final StateDef proceedStatDef = registry.getWorkflowState(workflowType, proceedStateId);
-            WorkflowStateOptions proceedStateOptions = proceedStatDef.getWorkflowState().getStateOptions();
+            WorkflowStateOptions proceedStateOptions = StateMovementMapper.validateAndGetStateOptions(proceedStatDef);
             if (proceedStateOptions != null &&
                     proceedStateOptions.getExecuteApiFailurePolicy() == ExecuteApiFailurePolicy.PROCEED_TO_CONFIGURED_STATE) {
                 throw new WorkflowDefinitionException("nested failure handling is not supported. You cannot set a failure proceeding state on top of another failure proceeding state.");
@@ -76,4 +79,35 @@ public static void autoFillFailureProceedingStateOptions(WorkflowStateOptions st
             stateOptions.executeApiFailureProceedStateOptions(proceedStateOptions);
         }
     }
+
+    public static WorkflowStateOptions validateAndGetStateOptions(final StateDef stateDef){
+        final WorkflowState state = stateDef.getWorkflowState();
+        WorkflowStateOptions stateOptions = state.getStateOptions();
+        if (stateOptions == null){
+            return null;
+        }
+        if(stateOptions.getExecuteApiFailurePolicy() == ExecuteApiFailurePolicy.PROCEED_TO_CONFIGURED_STATE){
+            // retry policy must be set
+            if(stateOptions.getExecuteApiRetryPolicy() == null){
+                throw new WorkflowDefinitionException("RetryPolicy must be set for the execute "+state.getStateId());
+            }
+            final RetryPolicy policy = stateOptions.getExecuteApiRetryPolicy();
+            // either maximumAttempts or maximumAttemptsDurationSeconds must be set and greater than zero
+            if(policy.getMaximumAttempts() == null && policy.getMaximumAttemptsDurationSeconds() == null){
+                throw new WorkflowDefinitionException("Either maximumAttempts or maximumAttemptsDurationSeconds must be set for the execute "+state.getStateId());
+            }
+        }
+        if(stateOptions.getWaitUntilApiFailurePolicy() == WaitUntilApiFailurePolicy.FAIL_WORKFLOW_ON_FAILURE){
+            // retry policy must be set
+            if(stateOptions.getWaitUntilApiRetryPolicy() == null){
+                throw new WorkflowDefinitionException("RetryPolicy must be set for the waitUntil "+state.getStateId());
+            }
+            final RetryPolicy policy = stateOptions.getWaitUntilApiRetryPolicy();
+            // either maximumAttempts or maximumAttemptsDurationSeconds must be set and greater than zero
+            if(policy.getMaximumAttempts() == null && policy.getMaximumAttemptsDurationSeconds() == null){
+                throw new WorkflowDefinitionException("Either maximumAttempts or maximumAttemptsDurationSeconds must be set for the waitUntil "+state.getStateId());
+            }
+        }
+        return stateOptions;
+    }
 }
diff --git a/src/test/java/io/iworkflow/integ/basic/ProceedOnStateStartFailWorkflowState1.java b/src/test/java/io/iworkflow/integ/basic/ProceedOnStateStartFailWorkflowState1.java
@@ -3,12 +3,12 @@
 import io.iworkflow.core.Context;
 import io.iworkflow.core.StateDecision;
 import io.iworkflow.core.WorkflowState;
+import io.iworkflow.core.WorkflowStateOptionsExtension;
 import io.iworkflow.core.command.CommandRequest;
 import io.iworkflow.core.command.CommandResults;
 import io.iworkflow.core.communication.Communication;
 import io.iworkflow.core.persistence.Persistence;
 import io.iworkflow.gen.models.RetryPolicy;
-import io.iworkflow.gen.models.WaitUntilApiFailurePolicy;
 import io.iworkflow.gen.models.WorkflowStateOptions;
 
 public class ProceedOnStateStartFailWorkflowState1 implements WorkflowState<String> {
@@ -40,8 +40,8 @@ public StateDecision execute(Context context, String input, CommandResults comma
 
     @Override
     public WorkflowStateOptions getStateOptions() {
-        return new WorkflowStateOptions()
-                .waitUntilApiRetryPolicy(new RetryPolicy().maximumAttempts(2))
-                .waitUntilApiFailurePolicy(WaitUntilApiFailurePolicy.PROCEED_ON_FAILURE);
+        return new WorkflowStateOptionsExtension()
+                .setProceedWhenWaitUntilRetryExhausted(true)
+                .waitUntilApiRetryPolicy(new RetryPolicy().maximumAttempts(2));
     }
 }
diff --git a/src/test/java/io/iworkflow/integ/stateapifail/StateFailProceedToRecoverBasic.java b/src/test/java/io/iworkflow/integ/stateapifail/StateFailProceedToRecoverBasic.java
@@ -8,7 +8,7 @@ public class StateFailProceedToRecoverBasic extends StateFailBasic {
     @Override
     public WorkflowStateOptions getStateOptions() {
         return new WorkflowStateOptionsExtension()
-                .setProceedOnExecuteFailure(StateRecoverBasic.class)
+                .setProceedWhenExecuteRetryExhausted(StateRecoverBasic.class)
                 .executeApiRetryPolicy(
                         new RetryPolicy()
                                 .maximumAttempts(1)

Original file line number	Diff line number	Diff line change
`@@ -172,7 +172,7 @@ public String startWorkflow(`
`172`	`172`	`throw new WorkflowDefinitionException(String.format("input cannot be assigned to the starting state, input type: %s, starting state input type: %s", input.getClass(), registeredInputType));`
`173`	`173`	`}`
`174`	`174`
`175`		`- WorkflowStateOptions stateOptions = stateDef.getWorkflowState().getStateOptions();`
	`175`	`+ WorkflowStateOptions stateOptions = StateMovementMapper.validateAndGetStateOptions(stateDef);`
`176`	`176`	`if (shouldSkipWaitUntil(stateDef.getWorkflowState())) {`
`177`	`177`	`if (stateOptions == null) {`
`178`	`178`	`stateOptions = new WorkflowStateOptions().skipWaitUntil(true);`