initial commit

Author: bachuv

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

@@ -4,6 +4,9 @@
 
 import javax.annotation.Nullable;
 import java.time.Duration;
+import java.time.Instant;
+import java.util.Collection;
+import java.util.List;
 import java.util.concurrent.TimeoutException;
 
 /**
@@ -494,4 +497,46 @@ public CleanEntityStorageResult cleanEntityStorage(CleanEntityStorageRequest req
     }
 
     // endregion
+
+    // region History and Instance Listing APIs
+
+    /**
+     * Retrieves the full history of the specified orchestration instance.
+     * <p>
+     * Each history event is returned as a transport-neutral {@link OrchestrationHistoryEvent} that
+     * decouples the public API from the underlying wire format.
+     *
+     * @param instanceId the orchestration instance ID
+     * @return list of history events for the orchestration
+     * @throws UnsupportedOperationException if this client implementation does not support history retrieval
+     * @throws IllegalArgumentException if the instance is not found
+     */
+    public List<OrchestrationHistoryEvent> getOrchestrationHistory(String instanceId) {
+        throw new UnsupportedOperationException(
+                this.getClass().getName() + " does not support retrieving orchestration history.");
+    }
+
+    /**
+     * Lists orchestration instance IDs that match the specified runtime status and
+     * completed time range, using key-based pagination.
+     *
+     * @param runtimeStatus   optional set of runtime statuses to filter by; if {@code null}, all statuses are included
+     * @param completedTimeFrom inclusive lower bound of the orchestration completed time filter
+     * @param completedTimeTo   inclusive upper bound of the orchestration completed time filter
+     * @param pageSize          maximum number of instance IDs to return in a single page
+     * @param lastInstanceKey   continuation key from the previous page; {@code null} to start from the beginning
+     * @return a page of orchestration instance IDs along with a continuation token
+     * @throws UnsupportedOperationException if this client implementation does not support instance ID listing
+     */
+    public InstanceIdPage listInstanceIds(
+            @Nullable Collection<OrchestrationRuntimeStatus> runtimeStatus,
+            @Nullable Instant completedTimeFrom,
+            @Nullable Instant completedTimeTo,
+            int pageSize,
+            @Nullable String lastInstanceKey) {
+        throw new UnsupportedOperationException(
+                this.getClass().getName() + " does not support listing instance IDs by completed time.");
+    }
+
+    // endregion
 }

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

@@ -411,4 +411,79 @@ public DurableEntityClient getEntities() {
     }
 
     // endregion
+
+    // region History and Instance Listing APIs
+
+    @Override
+    public List<OrchestrationHistoryEvent> getOrchestrationHistory(String instanceId) {
+        Helpers.throwIfArgumentNull(instanceId, "instanceId");
+
+        StreamInstanceHistoryRequest request = StreamInstanceHistoryRequest.newBuilder()
+                .setInstanceId(instanceId)
+                .setForWorkItemProcessing(false)
+                .build();
+
+        try {
+            Iterator<HistoryChunk> chunks = this.sidecarClient.streamInstanceHistory(request);
+            List<OrchestrationHistoryEvent> events = new ArrayList<>();
+            while (chunks.hasNext()) {
+                HistoryChunk chunk = chunks.next();
+                for (HistoryEvent protoEvent : chunk.getEventsList()) {
+                    events.add(OrchestrationHistoryEventMapper.fromProto(protoEvent));
+                }
+            }
+            return events;
+        } catch (StatusRuntimeException e) {
+            if (e.getStatus().getCode() == Status.Code.NOT_FOUND) {
+                throw new IllegalArgumentException(
+                        "An orchestration with instanceId '" + instanceId + "' was not found.", e);
+            }
+            if (e.getStatus().getCode() == Status.Code.CANCELLED) {
+                throw new IllegalStateException(
+                        "The getOrchestrationHistory operation was canceled.", e);
+            }
+            throw e;
+        }
+    }
+
+    @Override
+    public InstanceIdPage listInstanceIds(
+            @Nullable Collection<OrchestrationRuntimeStatus> runtimeStatus,
+            @Nullable Instant completedTimeFrom,
+            @Nullable Instant completedTimeTo,
+            int pageSize,
+            @Nullable String lastInstanceKey) {
+
+        ListInstanceIdsRequest.Builder builder = ListInstanceIdsRequest.newBuilder()
+                .setPageSize(pageSize);
+
+        if (runtimeStatus != null) {
+            for (OrchestrationRuntimeStatus status : runtimeStatus) {
+                builder.addRuntimeStatus(OrchestrationRuntimeStatus.toProtobuf(status));
+            }
+        }
+        if (completedTimeFrom != null) {
+            builder.setCompletedTimeFrom(Timestamp.newBuilder()
+                    .setSeconds(completedTimeFrom.getEpochSecond())
+                    .setNanos(completedTimeFrom.getNano())
+                    .build());
+        }
+        if (completedTimeTo != null) {
+            builder.setCompletedTimeTo(Timestamp.newBuilder()
+                    .setSeconds(completedTimeTo.getEpochSecond())
+                    .setNanos(completedTimeTo.getNano())
+                    .build());
+        }
+        if (lastInstanceKey != null) {
+            builder.setLastInstanceKey(StringValue.of(lastInstanceKey));
+        }
+
+        ListInstanceIdsResponse response = this.sidecarClient.listInstanceIds(builder.build());
+        String nextKey = response.hasLastInstanceKey()
+                ? response.getLastInstanceKey().getValue()
+                : null;
+        return new InstanceIdPage(response.getInstanceIdsList(), nextKey);
+    }
+
+    // endregion
 }

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

@@ -0,0 +1,57 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * Represents a single page of orchestration instance IDs returned by
+ * {@link DurableTaskClient#listInstanceIds}.
+ * <p>
+ * Includes a continuation token for key-based pagination. If the continuation token is
+ * {@code null}, there are no more results.
+ */
+public final class InstanceIdPage {
+
+    private final List<String> instanceIds;
+    private final String continuationToken;
+
+    /**
+     * Creates a new {@code InstanceIdPage}.
+     *
+     * @param instanceIds       the list of instance IDs in this page
+     * @param continuationToken the continuation token for the next page, or {@code null} if no more results
+     */
+    public InstanceIdPage(
+            @Nonnull List<String> instanceIds,
+            @Nullable String continuationToken) {
+        if (instanceIds == null) {
+            throw new IllegalArgumentException("instanceIds must not be null.");
+        }
+        this.instanceIds = Collections.unmodifiableList(instanceIds);
+        this.continuationToken = continuationToken;
+    }
+
+    /**
+     * Gets the list of orchestration instance IDs in this page.
+     *
+     * @return unmodifiable list of instance IDs
+     */
+    @Nonnull
+    public List<String> getInstanceIds() {
+        return this.instanceIds;
+    }
+
+    /**
+     * Gets the continuation token for fetching the next page of results.
+     *
+     * @return the continuation token, or {@code null} if there are no more results
+     */
+    @Nullable
+    public String getContinuationToken() {
+        return this.continuationToken;
+    }
+}

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

@@ -0,0 +1,94 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import java.time.Instant;
+import java.util.Collections;
+import java.util.Map;
+
+/**
+ * Transport-neutral representation of a single orchestration history event.
+ * <p>
+ * This type decouples the public SDK API from the underlying gRPC/protobuf transport types,
+ * ensuring API stability even if the wire format evolves. It is returned by
+ * {@link DurableTaskClient#getOrchestrationHistory(String)}.
+ */
+public final class OrchestrationHistoryEvent {
+
+    private final int eventId;
+    private final Instant timestamp;
+    private final String eventType;
+    private final Map<String, Object> data;
+
+    /**
+     * Creates a new {@code OrchestrationHistoryEvent}.
+     *
+     * @param eventId   the sequence ID of the event within the orchestration history
+     * @param timestamp the UTC timestamp when the event was recorded
+     * @param eventType the type name of the event (e.g., "ExecutionStarted", "TaskScheduled")
+     * @param data      the event-specific data fields, or an empty map if none
+     */
+    public OrchestrationHistoryEvent(
+            int eventId,
+            @Nonnull Instant timestamp,
+            @Nonnull String eventType,
+            @Nonnull Map<String, Object> data) {
+        if (timestamp == null) {
+            throw new IllegalArgumentException("timestamp must not be null.");
+        }
+        if (eventType == null || eventType.isEmpty()) {
+            throw new IllegalArgumentException("eventType must not be null or empty.");
+        }
+        if (data == null) {
+            throw new IllegalArgumentException("data must not be null.");
+        }
+        this.eventId = eventId;
+        this.timestamp = timestamp;
+        this.eventType = eventType;
+        this.data = Collections.unmodifiableMap(data);
+    }
+
+    /**
+     * Gets the sequence ID of this event within the orchestration history.
+     *
+     * @return the event ID
+     */
+    public int getEventId() {
+        return this.eventId;
+    }
+
+    /**
+     * Gets the UTC timestamp when this event was recorded.
+     *
+     * @return the event timestamp
+     */
+    @Nonnull
+    public Instant getTimestamp() {
+        return this.timestamp;
+    }
+
+    /**
+     * Gets the type name of this event (e.g., "ExecutionStarted", "TaskScheduled", "TaskCompleted").
+     *
+     * @return the event type name
+     */
+    @Nonnull
+    public String getEventType() {
+        return this.eventType;
+    }
+
+    /**
+     * Gets the event-specific data fields as an unmodifiable map.
+     * <p>
+     * The keys and structure of this map depend on the event type. For example, an
+     * "ExecutionStarted" event may contain "name", "input", and "version" fields.
+     *
+     * @return unmodifiable map of event data
+     */
+    @Nonnull
+    public Map<String, Object> getData() {
+        return this.data;
+    }
+}