Merge remote-tracking branch 'origin/main' into vabachu/exporthistory-module

Author: bachuv

CHANGELOG.md

@@ -1,4 +1,6 @@
 ## Unreleased
+* Add client APIs to list terminal instance IDs by completion time (`listInstanceIds`) and read orchestration history (`getOrchestrationHistory`) ([#292](https://github.com/microsoft/durabletask-java/pull/292))
+* Add `createReplaySafeLogger` to suppress orchestration log output during replay ([#295](https://github.com/microsoft/durabletask-java/pull/295)).
 * Add `getParentInstance()` API to `TaskOrchestrationContext` for discovering parent orchestration info ([#284](https://github.com/microsoft/durabletask-java/pull/284))
 
 ## v1.9.0

README.md

@@ -16,6 +16,30 @@ result += ctx.callActivity("SayHello", "Seattle", String.class).await();
 return result;
 ```
 
+### Replay-safe orchestration logging
+
+Orchestrator code re-executes while rebuilding state from history. Wrap an existing
+`java.util.logging.Logger` to suppress log output during those replay segments:
+
+```java
+Logger logger = ctx.createReplaySafeLogger(
+    Logger.getLogger(MyOrchestration.class.getName()));
+
+logger.info(() -> "Starting orchestration " + ctx.getInstanceId());
+String result = ctx.callActivity("ProcessItem", input, String.class).await();
+logger.info(() -> "Activity returned: " + result);
+```
+
+In Azure Functions, pass `ExecutionContext.getLogger()` instead of creating a named
+logger so the output retains its invocation ID and normal host routing:
+
+```java
+Logger logger = ctx.createReplaySafeLogger(executionContext.getLogger());
+```
+
+Replay-safe logging suppresses calls made while replaying; it does not guarantee
+exactly-once log delivery across failed or retried live orchestration turns.
+
 ### Reliable fan-out / fan-in orchestration pattern
 
 ```java

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

@@ -247,14 +247,16 @@ public ListInstanceIdsResult listInstanceIds(ListInstanceIdsQuery query) {
                 "Listing instance IDs is not supported by this client implementation.");
     }
 
-    /**
-     * Gets the full history of an orchestration instance as an ordered list of {@link HistoryEvent} objects.
+        /**
+        * Retrieves the history of the specified orchestration instance as a list of {@link HistoryEvent} objects.
      * <p>
      * The events are returned in execution order. This is useful for archiving or offline analysis of an instance's
      * execution history. Use {@code instanceof} to inspect each concrete event type.
      *
-     * @param instanceId the unique ID of the orchestration instance whose history to fetch
-     * @return the instance's history events in order; empty if the instance has no history
+     * @param instanceId the instance ID of the orchestration
+     * @return the list of {@link HistoryEvent} objects representing the orchestration's history, in execution order;
+     *         empty if the instance has no history
+     * @throws IllegalArgumentException if {@code instanceId} is null
      * @throws UnsupportedOperationException if the current client implementation does not support history retrieval
      */
     public List<HistoryEvent> getOrchestrationHistory(String instanceId) {

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

@@ -308,7 +308,13 @@ public ListInstanceIdsResult listInstanceIds(ListInstanceIdsQuery query) {
         builder.setPageSize(query.getPageSize());
         query.getRuntimeStatusList().forEach(runtimeStatus -> Optional.ofNullable(runtimeStatus).ifPresent(status -> builder.addRuntimeStatus(OrchestrationRuntimeStatus.toProtobuf(status))));
         ListInstanceIdsResponse response = this.sidecarClient.listInstanceIds(builder.build());
-        String continuationToken = response.hasLastInstanceKey() ? response.getLastInstanceKey().getValue() : null;
+        // Treat an absent OR empty lastInstanceKey as end-of-results. A caller that loops while the
+        // continuation token is non-null would otherwise re-request with an empty cursor and restart
+        // paging from the beginning, causing an infinite loop.
+        String continuationToken =
+                response.hasLastInstanceKey() && !response.getLastInstanceKey().getValue().isEmpty()
+                        ? response.getLastInstanceKey().getValue()
+                        : null;
         return new ListInstanceIdsResult(new ArrayList<>(response.getInstanceIdsList()), continuationToken);
     }
 
@@ -319,11 +325,22 @@ public List<HistoryEvent> getOrchestrationHistory(String instanceId) {
                 .setInstanceId(instanceId)
                 .build();
         List<HistoryEvent> historyEvents = new ArrayList<>();
-        Iterator<HistoryChunk> chunks = this.sidecarClient.streamInstanceHistory(request);
-        while (chunks.hasNext()) {
-            for (OrchestratorService.HistoryEvent protoEvent : chunks.next().getEventsList()) {
-                historyEvents.add(HistoryEventConverter.fromProto(protoEvent));
+        // Bind the server-streaming call to a cancellable context so the RPC is always released, even if
+        // draining the stream exits early via an exception. Without this, an early exit abandons the
+        // blocking iterator without cancelling the call -- a known grpc-java resource-leak pattern.
+        Context.CancellableContext streamContext = Context.current().withCancellation();
+        Context previous = streamContext.attach();
+        try {
+            Iterator<HistoryChunk> chunks = this.sidecarClient.streamInstanceHistory(request);
+            while (chunks.hasNext()) {
+                for (OrchestratorService.HistoryEvent protoEvent : chunks.next().getEventsList()) {
+                    historyEvents.add(HistoryEventConverter.fromProto(protoEvent));
+                }
             }
+        } finally {
+            streamContext.detach(previous);
+            // Cancels the RPC if it is still open (e.g. early exit mid-stream); no-op once it completed normally.
+            streamContext.cancel(null);
         }
         return historyEvents;
     }

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

@@ -5,6 +5,7 @@
 import javax.annotation.Nullable;
 import java.time.Instant;
 import java.util.ArrayList;
+import java.util.Collections;
 import java.util.List;
 
 /**
@@ -93,26 +94,46 @@ public ListInstanceIdsQuery setContinuationToken(@Nullable String continuationTo
         return this;
     }
 
-    List<OrchestrationRuntimeStatus> getRuntimeStatusList() {
-        return this.runtimeStatusList;
+    /**
+     * Gets the configured terminal runtime status filter, or an empty list if none was configured.
+     * @return an unmodifiable view of the configured terminal runtime status filter
+     */
+    public List<OrchestrationRuntimeStatus> getRuntimeStatusList() {
+        return Collections.unmodifiableList(this.runtimeStatusList);
     }
 
+    /**
+     * Gets the configured minimum completion time, or {@code null} if none was configured.
+     * @return the configured minimum completion time, or {@code null} if none was configured
+     */
     @Nullable
-    Instant getCompletedTimeFrom() {
+    public Instant getCompletedTimeFrom() {
         return this.completedTimeFrom;
     }
 
+    /**
+     * Gets the configured maximum completion time, or {@code null} if none was configured.
+     * @return the configured maximum completion time, or {@code null} if none was configured
+     */
     @Nullable
-    Instant getCompletedTimeTo() {
+    public Instant getCompletedTimeTo() {
         return this.completedTimeTo;
     }
 
-    int getPageSize() {
+    /**
+     * Gets the configured maximum number of instance IDs to return per page.
+     * @return the configured page size
+     */
+    public int getPageSize() {
         return this.pageSize;
     }
 
+    /**
+     * Gets the configured pagination cursor, or {@code null} if none was configured.
+     * @return the configured pagination cursor, or {@code null} if none was configured
+     */
     @Nullable
-    String getContinuationToken() {
+    public String getContinuationToken() {
         return this.continuationToken;
     }
 }