Adding rewind client API (#253)

Author: bachuv

.github/workflows/build-validation.yml

@@ -156,8 +156,8 @@ jobs:
       - name: Archive test report
         uses: actions/upload-artifact@v4
         with:
-          name: Integration test report
-          path: client/build/reports/tests/endToEndTest
+          name: E2E test report
+          path: endtoendtests/build/reports/tests/endToEndTest
 
   functions-sample-tests:
 
@@ -195,5 +195,5 @@ jobs:
       - name: Archive test report
         uses: actions/upload-artifact@v4
         with:
-          name: Integration test report
-          path: client/build/reports/tests/endToEndTest
+          name: Functions Sample test report
+          path: samples-azure-functions/build/reports/tests/sampleTest

CHANGELOG.md

@@ -1,5 +1,7 @@
 ## Unreleased
 
+* Adding rewind client API ([#253](https://github.com/microsoft/durabletask-java/pull/253)). Note: orchestration processing for rewind is supported with Azure Functions but not with the standalone `GrpcDurableTaskWorker`.
+
 ## v1.7.0
 * Add descriptive error when orchestration type is not registered ([#261](https://github.com/microsoft/durabletask-java/pull/261))
 * Update all dependencies to latest versions ([#260](https://github.com/microsoft/durabletask-java/pull/260))

azurefunctions/src/main/java/com/microsoft/durabletask/azurefunctions/HttpManagementPayload.java

@@ -13,6 +13,7 @@ public class HttpManagementPayload {
     private final String id;
     private final String purgeHistoryDeleteUri;
     private final String restartPostUri;
+    private final String rewindPostUri;
     private final String sendEventPostUri;
     private final String statusQueryGetUri;
     private final String terminatePostUri;
@@ -33,6 +34,7 @@ public HttpManagementPayload(
         this.id = instanceId;
         this.purgeHistoryDeleteUri = instanceStatusURL + "?" + requiredQueryStringParameters;
         this.restartPostUri = instanceStatusURL + "/restart?" + requiredQueryStringParameters;
+        this.rewindPostUri = instanceStatusURL + "/rewind?reason={text}&" + requiredQueryStringParameters;
         this.sendEventPostUri = instanceStatusURL + "/raiseEvent/{eventName}?" + requiredQueryStringParameters;
         this.statusQueryGetUri = instanceStatusURL + "?" + requiredQueryStringParameters;
         this.terminatePostUri = instanceStatusURL + "/terminate?reason={text}&" + requiredQueryStringParameters;
@@ -94,4 +96,13 @@ public String getRestartPostUri() {
         return restartPostUri;
     }
 
+    /**
+     * Gets the HTTP POST instance rewind endpoint.
+     *
+     * @return The HTTP URL for posting instance rewind commands.
+     */
+    public String getRewindPostUri() {
+        return rewindPostUri;
+    }
+
 }

client/src/main/java/com/microsoft/durabletask/DurableTaskClient.java

@@ -292,6 +292,41 @@ public abstract OrchestrationMetadata waitForInstanceCompletion(
      */
     public abstract String restartInstance(String instanceId, boolean restartWithNewInstanceId);
 
+    /**
+     * Rewinds a failed orchestration instance to the last known good state and replays from there.
+     * <p>
+     * This method can only be used on orchestration instances that are in a <code>Failed</code> state.
+     * When rewound, the orchestration instance will restart from the point of failure as if the failure
+     * never occurred. It rewinds the orchestration by replaying any
+     * Failed Activities and Failed suborchestrations that themselves have Failed Activities
+     * <p>
+     * <b>Note:</b> Rewind requires a backend that supports it. When using Azure Functions with the
+     * Durable Task extension, rewind is fully supported. The standalone {@code GrpcDurableTaskWorker}
+     * does not currently support orchestration processing for rewind.
+     *
+     * @param instanceId the ID of the orchestration instance to rewind
+     */
+    public void rewindInstance(String instanceId) {
+        this.rewindInstance(instanceId, null);
+    }
+
+    /**
+     * Rewinds a failed orchestration instance to the last known good state and replays from there.
+     * <p>
+     * This method can only be used on orchestration instances that are in a <code>Failed</code> state.
+     * When rewound, the orchestration instance will restart from the point of failure as if the failure
+     * never occurred. It rewinds the orchestration by replaying any
+     * Failed Activities and Failed suborchestrations that themselves have Failed Activities
+     * <p>
+     * <b>Note:</b> Rewind requires a backend that supports it. When using Azure Functions with the
+     * Durable Task extension, rewind is fully supported. The standalone {@code GrpcDurableTaskWorker}
+     * does not currently support orchestration processing for rewind.
+     *
+     * @param instanceId the ID of the orchestration instance to rewind
+     * @param reason the reason for rewinding the orchestration instance
+     */
+    public abstract void rewindInstance(String instanceId, @Nullable String reason);
+
     /**
      * Suspends a running orchestration instance.
      * @param instanceId the ID of the orchestration instance to suspend

client/src/main/java/com/microsoft/durabletask/DurableTaskGrpcClient.java

@@ -363,6 +363,29 @@ public void resumeInstance(String instanceId, @Nullable String reason) {
         this.sidecarClient.resumeInstance(resumeRequestBuilder.build());
     }
 
+    @Override
+    public void rewindInstance(String instanceId, @Nullable String reason) {
+        Helpers.throwIfArgumentNull(instanceId, "instanceId");
+        RewindInstanceRequest.Builder rewindRequestBuilder = RewindInstanceRequest.newBuilder();
+        rewindRequestBuilder.setInstanceId(instanceId);
+        if (reason != null) {
+            rewindRequestBuilder.setReason(StringValue.of(reason));
+        }
+        try {
+            this.sidecarClient.rewindInstance(rewindRequestBuilder.build());
+        } catch (StatusRuntimeException e) {
+            if (e.getStatus().getCode() == Status.Code.NOT_FOUND) {
+                throw new IllegalArgumentException(
+                        "No orchestration instance with ID '" + instanceId + "' was found.", e);
+            }
+            if (e.getStatus().getCode() == Status.Code.FAILED_PRECONDITION) {
+                throw new IllegalStateException(
+                        "Orchestration instance '" + instanceId + "' is not in a failed state and cannot be rewound.", e);
+            }
+            throw e;
+        }
+    }
+
     @Override
     public String restartInstance(String instanceId, boolean restartWithNewInstanceId) {
         OrchestrationMetadata metadata = this.getInstanceMetadata(instanceId, true);