Add client APIs to list instance IDs and read orchestration history by bachuv · Pull Request #292 · microsoft/durabletask-java

bachuv · 2026-07-01T23:31:31Z

Issue describing the changes in this PR

Adds client APIs to enumerate orchestration instances and read a completed instance's
history, plus a public history-event model.

Changes

DurableTaskClient.listInstanceIds(ListInstanceIdsQuery) → ListInstanceIdsResult — page terminal/instance IDs by filter (completion window, statuses, continuation token).
DurableTaskClient.getOrchestrationHistory(String instanceId) → List<HistoryEvent> — retrieve an instance's full ordered history.
New public model com.microsoft.durabletask.history — HistoryEvent plus per-type subclasses (ExecutionStarted/Completed, TaskScheduled/Completed/Failed, Timer*, SubOrchestration*, EntityOperation*/EntityLock*, EventSent/Raised, Generic, HistoryState, …).
Backed by the ListInstanceIds and StreamInstanceHistory gRPC operations (managed DTS; sidecar/emulator ≥ v0.4.22).

Notes

Foundation for a follow-up durable history-export feature (stacked PR).

Pull request checklist

My changes do not require documentation changes
- Otherwise: Documentation issue linked to PR
My changes are added to the CHANGELOG.md
I have added all required tests (Unit tests, E2E tests)

Copilot

Pull request overview

This PR adds new Durable Task client capabilities for bulk instance enumeration and orchestration history retrieval, along with a new public com.microsoft.durabletask.history domain model and conversion layer from protobuf history events.

Changes:

Adds DurableTaskClient.listInstanceIds(ListInstanceIdsQuery) and supporting query/result types for paging terminal instance IDs by completion-time window and status.
Adds DurableTaskClient.getOrchestrationHistory(String) backed by the sidecar StreamInstanceHistory gRPC operation, returning a typed public history-event model.
Introduces HistoryEventConverter plus unit/integration tests for history conversion and the new client APIs.

Reviewed changes

Copilot reviewed 40 out of 40 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
client/src/test/java/com/microsoft/durabletask/IntegrationTests.java	Adds integration coverage for listing completed instance IDs and fetching typed history.
client/src/test/java/com/microsoft/durabletask/HistoryEventConverterTest.java	Adds unit tests validating protobuf→domain history event conversion.
client/src/main/java/com/microsoft/durabletask/ListInstanceIdsResult.java	New paging result model for instance ID enumeration.
client/src/main/java/com/microsoft/durabletask/ListInstanceIdsQuery.java	New query model for completion-window instance ID listing.
client/src/main/java/com/microsoft/durabletask/HistoryEventConverter.java	Implements protobuf→public domain model conversion for history events.
client/src/main/java/com/microsoft/durabletask/history/TraceContext.java	Adds public model for W3C trace context on history events.
client/src/main/java/com/microsoft/durabletask/history/TimerFiredEvent.java	Adds typed history event model for fired timers.
client/src/main/java/com/microsoft/durabletask/history/TimerCreatedEvent.java	Adds typed history event model for created timers.
client/src/main/java/com/microsoft/durabletask/history/TaskScheduledEvent.java	Adds typed history event model for scheduled activities.
client/src/main/java/com/microsoft/durabletask/history/TaskFailedEvent.java	Adds typed history event model for failed activities.
client/src/main/java/com/microsoft/durabletask/history/TaskCompletedEvent.java	Adds typed history event model for completed activities.
client/src/main/java/com/microsoft/durabletask/history/SubOrchestrationInstanceFailedEvent.java	Adds typed history event model for failed sub-orchestrations.
client/src/main/java/com/microsoft/durabletask/history/SubOrchestrationInstanceCreatedEvent.java	Adds typed history event model for created sub-orchestrations.
client/src/main/java/com/microsoft/durabletask/history/SubOrchestrationInstanceCompletedEvent.java	Adds typed history event model for completed sub-orchestrations.
client/src/main/java/com/microsoft/durabletask/history/ParentInstanceInfo.java	Adds model for parent-orchestration metadata referenced by history events.
client/src/main/java/com/microsoft/durabletask/history/OrchestratorStartedEvent.java	Adds typed history event model for replay/episode start markers.
client/src/main/java/com/microsoft/durabletask/history/OrchestratorCompletedEvent.java	Adds typed history event model for replay/episode end markers.
client/src/main/java/com/microsoft/durabletask/history/OrchestrationState.java	Adds snapshot model carried by history state checkpoint events.
client/src/main/java/com/microsoft/durabletask/history/OrchestrationInstance.java	Adds model identifying an orchestration instance (+ optional execution ID).
client/src/main/java/com/microsoft/durabletask/history/HistoryStateEvent.java	Adds typed history event model for orchestration state snapshots.
client/src/main/java/com/microsoft/durabletask/history/HistoryEvent.java	Adds base class for the public history event hierarchy.
client/src/main/java/com/microsoft/durabletask/history/GenericEvent.java	Adds typed history event model for generic/free-form payload events.
client/src/main/java/com/microsoft/durabletask/history/ExecutionTerminatedEvent.java	Adds typed history event model for termination.
client/src/main/java/com/microsoft/durabletask/history/ExecutionSuspendedEvent.java	Adds typed history event model for suspension.
client/src/main/java/com/microsoft/durabletask/history/ExecutionStartedEvent.java	Adds typed history event model for orchestration start.
client/src/main/java/com/microsoft/durabletask/history/ExecutionRewoundEvent.java	Adds typed history event model for rewind operations.
client/src/main/java/com/microsoft/durabletask/history/ExecutionResumedEvent.java	Adds typed history event model for resume.
client/src/main/java/com/microsoft/durabletask/history/ExecutionCompletedEvent.java	Adds typed history event model for terminal completion.
client/src/main/java/com/microsoft/durabletask/history/EventSentEvent.java	Adds typed history event model for sending external events.
client/src/main/java/com/microsoft/durabletask/history/EventRaisedEvent.java	Adds typed history event model for receiving external events.
client/src/main/java/com/microsoft/durabletask/history/EntityUnlockSentEvent.java	Adds typed history event model for entity unlock operations.
client/src/main/java/com/microsoft/durabletask/history/EntityOperationSignaledEvent.java	Adds typed history event model for one-way entity signals.
client/src/main/java/com/microsoft/durabletask/history/EntityOperationFailedEvent.java	Adds typed history event model for failed entity operations.
client/src/main/java/com/microsoft/durabletask/history/EntityOperationCompletedEvent.java	Adds typed history event model for completed entity operations.
client/src/main/java/com/microsoft/durabletask/history/EntityOperationCalledEvent.java	Adds typed history event model for two-way entity calls.
client/src/main/java/com/microsoft/durabletask/history/EntityLockRequestedEvent.java	Adds typed history event model for entity lock requests.
client/src/main/java/com/microsoft/durabletask/history/EntityLockGrantedEvent.java	Adds typed history event model for entity lock grants.
client/src/main/java/com/microsoft/durabletask/history/ContinueAsNewEvent.java	Adds typed history event model for continue-as-new.
client/src/main/java/com/microsoft/durabletask/DurableTaskGrpcClient.java	Implements new APIs over sidecar gRPC: listInstanceIds + stream history conversion.
client/src/main/java/com/microsoft/durabletask/DurableTaskClient.java	Adds new abstract public APIs for instance ID listing and orchestration history retrieval.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

nytian

Left a few comments. Thanks for the PR!

nytian · 2026-07-09T02:27:49Z

+     * @param query filter criteria: completion-time window, terminal runtime statuses, page size, and pagination cursor
+     * @return a page of matching instance IDs and a cursor for the next page
+     */
+    public abstract ListInstanceIdsResult listInstanceIds(ListInstanceIdsQuery query);


Just wondering which classes extend DurableTaskClient? Only within this repo, right? Can we add a default implementation that throws UnsupportedOperationException? I think its safer for these breaking changes.

nytian · 2026-07-09T02:33:55Z

+     * @param pageSize the maximum number of instance IDs to return per page
+     * @return this query object
+     */
+    public ListInstanceIdsQuery setPageSize(int pageSize) {


Lets add a check here to ensure pageSize won't be negative or 0

nytian · 2026-07-09T02:36:31Z

+ * Unit tests for {@link HistoryEventConverter}, which maps protobuf history events to the public
+ * {@code com.microsoft.durabletask.history} domain model.
+ */
+public class HistoryEventConverterTest {


Seems there are some history events are not tested here. Can you add them? Eg the entity types and suspend/resume and continueasnew etc,

nytian · 2026-07-09T02:42:14Z

+                historyEvents.add(HistoryEventConverter.fromProto(protoEvent));
+            }
+        }
+        return historyEvents;


nit: if cx has a very large history list, we have to return to them after processing them all in memory. So I fell like Stream/Page is better here, but I feel this is not super common case, so up to your decision :)

initial commit

74d7552

bachuv requested a review from a team as a code owner July 1, 2026 23:31

Copilot AI review requested due to automatic review settings July 1, 2026 23:31

Copilot started reviewing on behalf of bachuv July 1, 2026 23:31 View session

Copilot AI reviewed Jul 1, 2026

View reviewed changes

bachuv mentioned this pull request Jul 1, 2026

Add export history support #293

Open

4 tasks

bachuv added 4 commits July 1, 2026 16:49

normalize null runtimeStatusList in ListInstanceIdsQuery

0cd9ef9

fix javadoc broken link and heading levels

06cd428

add Helpers.throwIfArgumentNull

203d86d

defensively copy tags in OrchestrationState

fe65bf4

nytian reviewed Jul 9, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add client APIs to list instance IDs and read orchestration history#292

Add client APIs to list instance IDs and read orchestration history#292
bachuv wants to merge 5 commits into
mainfrom
vabachu/client-list-stream-history

bachuv commented Jul 1, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nytian left a comment

Uh oh!

nytian Jul 9, 2026

Uh oh!

nytian Jul 9, 2026

Uh oh!

nytian Jul 9, 2026 •

edited

Loading

Uh oh!

nytian Jul 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

bachuv commented Jul 1, 2026

Issue describing the changes in this PR

Changes

Notes

Pull request checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nytian left a comment

Choose a reason for hiding this comment

Uh oh!

nytian Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

nytian Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

nytian Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nytian Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

nytian Jul 9, 2026 •

edited

Loading