Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
12b03e7
feat(workflow): expose durable termination reasons in Java SDK
ep0ll Nov 14, 2026
184c0a8
feat(workflow): expose durable termination reasons in Java SDK
ep0ll Nov 14, 2026
11c6b86
feat(workflow): expose durable termination reasons in Java SDK
ep0ll Nov 14, 2026
376b945
feat(workflow): expose durable termination reasons in Java SDK
ep0ll Nov 14, 2026
ae51fb0
feat(workflow): expose durable termination reasons in Java SDK
ep0ll Nov 14, 2026
1062bde
feat(workflow): expose durable termination reasons in Java SDK
ep0ll Nov 14, 2026
68a9a85
feat(workflow): expose durable termination reasons in Java SDK
ep0ll Nov 14, 2026
84d8481
fix(workflows): preserve WorkflowState implementation compatibility
ep0ll Nov 15, 2026
5b5d634
fix(spring): observe workflow termination with reason
ep0ll Nov 15, 2026
f42fad8
test(spring): cover observed workflow termination reasons
ep0ll Nov 15, 2026
02dae17
test(workflows): cover termination reason gRPC mapping
ep0ll Nov 15, 2026
e93e20d
fix(test): correct serialized termination output expectation
ep0ll Nov 15, 2026
f2f19d0
test(workflows): cover termination reason metadata mapping
ep0ll Nov 15, 2026
6ab5654
test(workflows): cover public termination reason state accessor
ep0ll Nov 15, 2026
e60530a
refactor(workflow): use existing durabletask protobuf contract
ep0ll Nov 18, 2026
bca92cf
refactor(workflow): reuse termination request output field
ep0ll Nov 18, 2026
736e3a1
refactor(workflow): use existing custom status metadata
ep0ll Nov 18, 2026
9ffcd64
refactor(workflow): remove redundant termination reason state
ep0ll Nov 18, 2026
6e38948
refactor(workflow): use existing custom status state
ep0ll Nov 18, 2026
2d848c3
test(workflow): verify termination reason uses existing input
ep0ll Nov 18, 2026
d47a489
test(workflow): rely on existing custom status metadata
ep0ll Nov 18, 2026
7f89af7
test(workflow): remove redundant termination reason property
ep0ll Nov 18, 2026
de6e869
docs(workflow): describe termination input mapping
ep0ll Nov 18, 2026
35cfee6
docs(workflow): clarify termination reason mapping
ep0ll Nov 18, 2026
169220d
style(workflow): wrap termination reason documentation
ep0ll Nov 18, 2026
87dac52
docs(workflow): clarify termination input mapping
ep0ll Nov 18, 2026
72795f6
refactor(workflow): remove unnecessary durabletask dependency changes
ep0ll Nov 18, 2026
afefaee
style(workflow): wrap termination reason documentation
ep0ll Nov 18, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,22 @@ private Observation observation(String name) {
return Observation.createNotStarted(name, observationRegistry);
}

private void observeTerminationWithReason(String workflowInstanceId, Runnable termination) {
Observation obs = observation("dapr.workflow.terminate")
.highCardinalityKeyValue("dapr.workflow.instance_id", workflowInstanceId)
.start();
try {
try (Observation.Scope ignored = obs.openScope()) {
termination.run();
}
} catch (RuntimeException e) {
obs.error(e);
throw e;
} finally {
obs.stop();
}
}

// -------------------------------------------------------------------------
// scheduleNewWorkflow — only String-based "leaf" overloads are overridden.
// Class<T>-based overloads in the parent delegate to this.scheduleNewWorkflow(String, ...)
Expand Down Expand Up @@ -219,6 +235,30 @@ public void terminateWorkflow(String workflowInstanceId, @Nullable Object output
}
}

@Override
public void terminateWorkflowWithReason(String workflowInstanceId, String reason) {
observeTerminationWithReason(
workflowInstanceId, () -> super.terminateWorkflowWithReason(workflowInstanceId, reason));
}

@Override
public void terminateWorkflowWithReason(
String workflowInstanceId, String reason, @Nullable Object output) {
observeTerminationWithReason(
workflowInstanceId, () -> super.terminateWorkflowWithReason(workflowInstanceId, reason, output));
}

@Override
public void terminateWorkflowWithReason(
String workflowInstanceId,
String reason,
@Nullable Object output,
@Nullable String appId) {
observeTerminationWithReason(
workflowInstanceId,
() -> super.terminateWorkflowWithReason(workflowInstanceId, reason, output, appId));
}

// -------------------------------------------------------------------------
// State queries
// -------------------------------------------------------------------------
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,47 @@ void terminateWorkflowCreatesSpan() {
.hasError();
}

@Test
@DisplayName("terminateWorkflowWithReason(String, String) creates span dapr.workflow.terminate")
void terminateWorkflowWithReasonCreatesSpan() {
assertThatThrownBy(() -> client.terminateWorkflowWithReason("instance-1", "operator requested"))
.isInstanceOf(RuntimeException.class);

TestObservationRegistryAssert.assertThat(registry)
.hasObservationWithNameEqualTo("dapr.workflow.terminate")
.that()
.hasHighCardinalityKeyValue("dapr.workflow.instance_id", "instance-1")
.hasError();
}

@Test
@DisplayName("terminateWorkflowWithReason(String, String, Object) creates span dapr.workflow.terminate")
void terminateWorkflowWithReasonAndOutputCreatesSpan() {
assertThatThrownBy(() ->
client.terminateWorkflowWithReason("instance-1", "operator requested", "cancelled"))
.isInstanceOf(RuntimeException.class);

TestObservationRegistryAssert.assertThat(registry)
.hasObservationWithNameEqualTo("dapr.workflow.terminate")
.that()
.hasHighCardinalityKeyValue("dapr.workflow.instance_id", "instance-1")
.hasError();
}

@Test
@DisplayName("terminateWorkflowWithReason cross-app overload creates span dapr.workflow.terminate")
void terminateWorkflowWithReasonAndAppIdCreatesSpan() {
assertThatThrownBy(() ->
client.terminateWorkflowWithReason("instance-1", "operator requested", "cancelled", "other-app"))
.isInstanceOf(RuntimeException.class);

TestObservationRegistryAssert.assertThat(registry)
.hasObservationWithNameEqualTo("dapr.workflow.terminate")
.that()
.hasHighCardinalityKeyValue("dapr.workflow.instance_id", "instance-1")
.hasError();
}

// -------------------------------------------------------------------------
// State queries
// -------------------------------------------------------------------------
Expand Down
2 changes: 1 addition & 1 deletion pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
<grpc.version>1.84.0</grpc.version>
<protobuf.version>3.25.5</protobuf.version>
<dapr.proto.baseurl>https://raw.githubusercontent.com/dapr/dapr/v1.19.0/dapr/proto</dapr.proto.baseurl>
<durabletask.proto.baseurl>https://raw.githubusercontent.com/dapr/durabletask-protobuf/v0.6.0/protos</durabletask.proto.baseurl>
<durabletask.proto.baseurl>https://raw.githubusercontent.com/dapr/durabletask-protobuf/v0.7.0/protos</durabletask.proto.baseurl>
<dapr.sdk.version>1.20.0-SNAPSHOT</dapr.sdk.version>
<os-maven-plugin.version>1.7.1</os-maven-plugin.version>
<maven-dependency-plugin.version>3.8.1</maven-dependency-plugin.version>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -299,6 +299,49 @@ public void terminateWorkflow(String workflowInstanceId, @Nullable Object output
this.innerClient.terminate(workflowInstanceId, output, appId);
}

/**
* Terminates a workflow and records the supplied reason as its termination input.
* The reason is exposed through the existing workflow custom-status metadata.
*
* @param workflowInstanceId workflow instance ID to terminate
* @param reason optional termination input exposed as custom status
*/
public void terminateWorkflowWithReason(String workflowInstanceId, String reason) {
this.terminateWorkflowWithReason(workflowInstanceId, reason, null, null);
}

/**
* Terminates a workflow and records the supplied reason as its termination input.
* The reason is exposed through the existing workflow custom-status metadata.
*
* @param workflowInstanceId workflow instance ID to terminate
* @param reason reason recorded as termination input and exposed through custom status
* @param output optional output to set for the terminated instance; mutually exclusive with reason
*/
public void terminateWorkflowWithReason(String workflowInstanceId, String reason, @Nullable Object output) {
this.terminateWorkflowWithReason(workflowInstanceId, reason, output, null);
}

/**
* Terminates a workflow and records the supplied reason as its termination input.
* The reason is exposed through the existing workflow custom-status metadata.
*
* @param workflowInstanceId workflow instance ID to terminate
* @param reason reason recorded as termination input and exposed through custom status
* @param output optional output to set for the terminated instance; mutually exclusive with reason
* @param appId ID of the app that owns the workflow instance, or {@code null} for the local app
*/
public void terminateWorkflowWithReason(
String workflowInstanceId,
String reason,
@Nullable Object output,
@Nullable String appId) {
if (reason == null) {
throw new IllegalArgumentException("reason must not be null");
}
this.innerClient.terminate(workflowInstanceId, output, appId, reason);
}

/**
* Fetches workflow instance metadata from the configured durable store.
*
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -361,6 +361,29 @@ public void terminate(String instanceId, @Nullable Object output, @Nullable Stri
this.terminate(instanceId, output);
}

/**
* Terminates an orchestration and optionally records a reason as its termination input.
* The runtime exposes the value through workflow custom status.
*
* <p>The default implementation preserves compatibility with custom clients that do not support
* termination reasons. Such clients reject a non-null reason instead of silently discarding it.</p>
*
* @param instanceId the unique ID of the orchestration instance to terminate
* @param output the optional output to set for the terminated orchestration instance
* @param appID the app that owns the orchestration instance, or {@code null} for the local app
* @param reason the optional reason recorded as termination input and exposed through custom status
*/
public void terminate(
String instanceId,
@Nullable Object output,
@Nullable String appID,
@Nullable String reason) {
if (reason != null) {
throw new UnsupportedOperationException("This DurableTaskClient does not support termination reasons.");
}
this.terminate(instanceId, output, appID);
}

/**
* Purges orchestration instance metadata from the durable store.
*
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -428,10 +428,18 @@ public void terminate(String instanceId, @Nullable Object output) {

@Override
public void terminate(String instanceId, @Nullable Object output, @Nullable String appID) {
this.terminate(instanceId, output, appID, null);
}

@Override
public void terminate(String instanceId, @Nullable Object output, @Nullable String appID, @Nullable String reason) {
Helpers.throwIfArgumentNull(instanceId, "instanceId");
String serializeOutput = this.dataConverter.serialize(output);
if (output != null && reason != null) {
throw new IllegalArgumentException("output and reason cannot be supplied together");
}
String serializeOutput = reason != null ? reason : this.dataConverter.serialize(output);
this.logger.fine(() -> String.format(
"Terminating instance %s and setting output to: %s",
"Terminating instance %s and setting termination input to: %s",
instanceId,
serializeOutput != null ? serializeOutput : "(null)"));
OrchestratorService.TerminateRequest.Builder builder = OrchestratorService.TerminateRequest.newBuilder()
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,7 @@ class DurableTaskGrpcClientOperationsTest {
private final AtomicReference<OrchestratorService.RerunWorkflowFromEventRequest> rerunRequest =
new AtomicReference<>();
private final AtomicReference<OrchestratorService.CreateInstanceRequest> createRequest = new AtomicReference<>();
private final AtomicReference<OrchestratorService.TerminateRequest> terminateRequest = new AtomicReference<>();

@BeforeEach
void setUp() throws Exception {
Expand Down Expand Up @@ -147,6 +148,15 @@ public void startInstance(
.build());
responseObserver.onCompleted();
}

@Override
public void terminateInstance(
OrchestratorService.TerminateRequest request,
StreamObserver<OrchestratorService.TerminateResponse> responseObserver) {
terminateRequest.set(request);
responseObserver.onNext(OrchestratorService.TerminateResponse.getDefaultInstance());
responseObserver.onCompleted();
}
})
.build()
.start();
Expand Down Expand Up @@ -267,6 +277,38 @@ void shouldRequireASourceInstanceToRerunFrom() {
() -> client.rerunWorkflowFromEvent(null, 5, null, null, false));
}

@Test
void shouldSendTheTerminationReasonUsingTheExistingOutputField() {
client.terminate(INSTANCE_ID, null, null, "operator requested");

OrchestratorService.TerminateRequest request = terminateRequest.get();
assertEquals(INSTANCE_ID, request.getInstanceId());
assertTrue(request.hasOutput());
assertEquals("operator requested", request.getOutput().getValue());
}

@Test
void shouldPreserveAnExplicitlyEmptyTerminationReason() {
client.terminate(INSTANCE_ID, null, null, "");

OrchestratorService.TerminateRequest request = terminateRequest.get();
assertTrue(request.hasOutput());
assertEquals("", request.getOutput().getValue());
}

@Test
void shouldRejectCombiningTerminationOutputAndReason() {
assertThrows(IllegalArgumentException.class,
() -> client.terminate(INSTANCE_ID, "cancelled", null, "operator requested"));
}

@Test
void shouldOmitTheTerminationInputForLegacyTerminationCalls() {
client.terminate(INSTANCE_ID, null);

assertFalse(terminateRequest.get().hasOutput());
}

@Test
void shouldRestartAnInstanceReusingItsNameAndInput() {
String instanceId = client.restartInstance(INSTANCE_ID, false);
Expand Down