Wire reason parameter in workflow cancellation request (#2519)

Author: Quinn-With-Two-Ns

temporal-sdk/src/main/java/io/temporal/client/WorkflowStub.java

@@ -369,6 +369,21 @@ <R> CompletableFuture<R> getResultAsync(
    */
   void cancel();
 
+  /**
+   * Request cancellation of a workflow execution with a reason.
+   *
+   * <p>Cancellation cancels {@link io.temporal.workflow.CancellationScope} that wraps the main
+   * workflow method. Note that workflow can take long time to get canceled or even completely
+   * ignore the cancellation request.
+   *
+   * @param reason optional reason for the cancellation request
+   * @throws WorkflowNotFoundException if the workflow execution doesn't exist or is already
+   *     completed
+   * @throws WorkflowServiceException for all other failures including networking and service
+   *     availability issues
+   */
+  void cancel(@Nullable String reason);
+
   /**
    * Terminates a workflow execution.
    *

temporal-sdk/src/main/java/io/temporal/client/WorkflowStubImpl.java

@@ -429,10 +429,16 @@ public <R> WorkflowUpdateHandle<R> getUpdateHandle(
 
   @Override
   public void cancel() {
+    cancel(null);
+  }
+
+  @Override
+  public void cancel(@Nullable String reason) {
     checkStarted();
     WorkflowExecution targetExecution = currentExecutionWithoutRunId();
     try {
-      workflowClientInvoker.cancel(new WorkflowClientCallsInterceptor.CancelInput(targetExecution));
+      workflowClientInvoker.cancel(
+          new WorkflowClientCallsInterceptor.CancelInput(targetExecution, reason));
     } catch (Exception e) {
       Throwable failure = throwAsWorkflowFailureException(e, targetExecution);
       throw new WorkflowServiceException(targetExecution, workflowType.orElse(null), failure);

temporal-sdk/src/main/java/io/temporal/common/interceptors/WorkflowClientCallsInterceptor.java

@@ -398,14 +398,30 @@ public R getResult() {
 
   final class CancelInput {
     private final WorkflowExecution workflowExecution;
+    private final @Nullable String reason;
 
+    /**
+     * @deprecated Use {@link #CancelInput(WorkflowExecution, String)} to provide a cancellation
+     *     reason instead.
+     */
+    @Deprecated
     public CancelInput(WorkflowExecution workflowExecution) {
+      this(workflowExecution, null);
+    }
+
+    public CancelInput(WorkflowExecution workflowExecution, @Nullable String reason) {
       this.workflowExecution = workflowExecution;
+      this.reason = reason;
     }
 
     public WorkflowExecution getWorkflowExecution() {
       return workflowExecution;
     }
+
+    @Nullable
+    public String getReason() {
+      return reason;
+    }
   }
 
   final class StartUpdateInput<R> {

temporal-sdk/src/main/java/io/temporal/internal/client/RootWorkflowClientInvoker.java

@@ -630,6 +630,9 @@ public CancelOutput cancel(CancelInput input) {
             .setWorkflowExecution(input.getWorkflowExecution())
             .setNamespace(clientOptions.getNamespace())
             .setIdentity(clientOptions.getIdentity());
+    if (input.getReason() != null) {
+      request.setReason(input.getReason());
+    }
     genericClient.requestCancel(request.build());
     return new CancelOutput();
   }

temporal-sdk/src/test/java/io/temporal/workflow/cancellationTests/WorkflowAwaitCancellationTest.java

@@ -10,6 +10,7 @@
 import io.temporal.client.WorkflowFailedException;
 import io.temporal.client.WorkflowStub;
 import io.temporal.failure.CanceledFailure;
+import io.temporal.internal.common.WorkflowExecutionUtils;
 import io.temporal.testing.internal.SDKTestWorkflowRule;
 import io.temporal.workflow.Workflow;
 import io.temporal.workflow.shared.TestWorkflows;
@@ -29,7 +30,7 @@ public void awaitCancellation() {
     execution = WorkflowClient.start(workflow::execute, "input1");
     try {
       WorkflowStub untyped = WorkflowStub.fromTyped(workflow);
-      untyped.cancel();
+      untyped.cancel("test reason");
       untyped.getResult(String.class);
       fail("unreacheable");
     } catch (WorkflowFailedException e) {
@@ -42,6 +43,13 @@ public void awaitCancellation() {
           "WorkflowExecutionCancelled event is expected",
           EventType.EVENT_TYPE_WORKFLOW_EXECUTION_CANCELED,
           lastEvent.getEventType());
+      assertEquals(
+          "WorkflowExecutionCancelled event should have the correct cause",
+          "test reason",
+          WorkflowExecutionUtils.getEventOfType(
+                  history, EventType.EVENT_TYPE_WORKFLOW_EXECUTION_CANCEL_REQUESTED)
+              .getWorkflowExecutionCancelRequestedEventAttributes()
+              .getCause());
     }
   }
 

temporal-sdk/src/test/java/io/temporal/workflow/cancellationTests/WorkflowAwaitWithDurationCancellationTest.java

@@ -35,7 +35,7 @@ public void awaitWithDurationCancellation() throws InterruptedException {
     try {
       WorkflowStub untyped = WorkflowStub.fromTyped(workflow);
       workflowStarted.waitForSignal();
-      untyped.cancel();
+      untyped.cancel("reason");
       untyped.getResult(String.class);
       fail("unreacheable");
     } catch (WorkflowFailedException e) {

temporal-test-server/src/main/java/io/temporal/internal/testservice/StateMachines.java

@@ -1488,7 +1488,8 @@ private static void requestWorkflowCancellation(
       long notUsed) {
     WorkflowExecutionCancelRequestedEventAttributes.Builder a =
         WorkflowExecutionCancelRequestedEventAttributes.newBuilder()
-            .setIdentity(cancelRequest.getIdentity());
+            .setIdentity(cancelRequest.getIdentity())
+            .setCause(cancelRequest.getReason());
     HistoryEvent cancelRequested =
         HistoryEvent.newBuilder()
             .setEventType(EventType.EVENT_TYPE_WORKFLOW_EXECUTION_CANCEL_REQUESTED)

temporal-testing/src/main/java/io/temporal/testing/TimeLockingInterceptor.java

@@ -164,6 +164,11 @@ public void cancel() {
       next.cancel();
     }
 
+    @Override
+    public void cancel(@Nullable String reason) {
+      next.cancel(reason);
+    }
+
     @Override
     public void terminate(@Nullable String reason, Object... details) {
       next.terminate(reason, details);