Add API to get orchestration history

CHANGELOG.md

@@ -13,6 +13,7 @@
 - Update project to target .net 8.0 and .net 10 and upgrade dependencies by Tomer Rosenthal ([#510](https://github.com/microsoft/durabletask-dotnet/pull/510))
 - Support worker features announcement by wangbill ([#502](https://github.com/microsoft/durabletask-dotnet/pull/502))
 - Introduce custom copilot review instructions by halspang ([#503](https://github.com/microsoft/durabletask-dotnet/pull/503))
+- Add API to get orchestration history ([#516](https://github.com/microsoft/durabletask-dotnet/pull/516))
 
 ## v1.17.1
 - Fix Worker Registry and Add Documentation Notes by nytian in [#462](https://github.com/microsoft/durabletask-dotnet/pull/495)

src/Client/Core/DurableTaskClient.cs

@@ -2,6 +2,7 @@
 // Licensed under the MIT License.
 
 using System.ComponentModel;
+using DurableTask.Core.History;
 using Microsoft.DurableTask.Client.Entities;
 using Microsoft.DurableTask.Internal;
 
@@ -456,15 +457,34 @@ public virtual Task<string> RestartAsync(
     /// <exception cref="NotSupportedException">Thrown if this implementation of <see cref="DurableTaskClient"/> does not
     /// support rewinding orchestrations.</exception>
     /// <exception cref="NotImplementedException">Thrown if the backend storage provider does not support rewinding orchestrations.</exception>
-    /// <exception cref="ArgumentException">Thrown if an orchestration with the specified <paramref name="instanceId"/> does not exist.</exception>
+    /// <exception cref="ArgumentException">Thrown if an orchestration with the specified <paramref name="instanceId"/> does not exist,
+    /// or if <paramref name="instanceId"/> is the instance ID of an entity.</exception>
     /// <exception cref="InvalidOperationException">Thrown if a precondition of the operation fails, for example if the specified
     /// orchestration is not in a "Failed" state.</exception>
     /// <exception cref="OperationCanceledException">Thrown if the operation is canceled via the <paramref name="cancellation"/> token.</exception>
     public virtual Task RewindInstanceAsync(
         string instanceId,
         string reason,
         CancellationToken cancellation = default)
-        => throw new NotSupportedException($"{this.GetType()} does not support orchestration rewind.");
+        => throw new NotSupportedException($"{this.GetType()} does not support orchestration rewind.");
+
+    /// <summary>
+    /// Retrieves the history of the specified orchestration instance as a list of <see cref="HistoryEvent"/> objects.
+    /// </summary>
+    /// <param name="instanceId">The instance ID of the orchestration.</param>
+    /// <param name="cancellation">The cancellation token.</param>
+    /// <returns>The list of <see cref="HistoryEvent"/> objects representing the orchestration's history.</returns>
+    /// <exception cref="NotSupportedException">Thrown if this implementation of <see cref="DurableTaskClient"/> does not
+    /// support retrieving orchestration history.</exception>
+    /// <exception cref="ArgumentNullException">Thrown if <paramref name="instanceId"/> is null.</exception>
+    /// <exception cref="ArgumentException">Thrown if an orchestration with the specified <paramref name="instanceId"/> does not exist,
+    /// or if <paramref name="instanceId"/> is the instance ID of an entity.</exception>
+    /// <exception cref="OperationCanceledException">Thrown if the operation is canceled via the <paramref name="cancellation"/> token.</exception>
+    /// <exception cref="InvalidOperationException">Thrown if an internal error occurs when attempting to retrieve the orchestration history.</exception>
+    public virtual Task<IList<HistoryEvent>> GetOrchestrationHistoryAsync(
+        string instanceId,
+        CancellationToken cancellation = default)
+        => throw new NotSupportedException($"{this.GetType()} does not support retrieving orchestration history.");
 
     // TODO: Create task hub
 

src/Client/Grpc/GrpcDurableTaskClient.cs

@@ -3,6 +3,7 @@
 
 using System.Diagnostics;
 using System.Text;
+using DurableTask.Core.History;
 using Google.Protobuf.WellKnownTypes;
 using Microsoft.DurableTask.Client.Entities;
 using Microsoft.DurableTask.Tracing;
@@ -468,6 +469,49 @@ public override async Task RewindInstanceAsync(
         }
     }
 
+    /// <inheritdoc/>
+    public override async Task<IList<HistoryEvent>> GetOrchestrationHistoryAsync(
+        string instanceId,
+        CancellationToken cancellation = default)
+    {
+        Check.NotNullOrEmpty(instanceId);
+        Check.NotEntity(this.options.EnableEntitySupport, instanceId);
+
+        P.StreamInstanceHistoryRequest streamRequest = new()
+        {
+            InstanceId = instanceId,
+            ForWorkItemProcessing = false,
+        };
+
+        try
+        {
+            using AsyncServerStreamingCall<P.HistoryChunk> streamResponse =
+                this.sidecarClient.StreamInstanceHistory(streamRequest, cancellationToken: cancellation);
+
+            List<HistoryEvent> pastEvents = [];
+            while (await streamResponse.ResponseStream.MoveNext(cancellation))
+            {
+                pastEvents.AddRange(streamResponse.ResponseStream.Current.Events.Select(DurableTask.ProtoUtils.ConvertHistoryEvent));
+            }
+
+            return pastEvents;
+        }
+        catch (RpcException e) when (e.StatusCode == StatusCode.NotFound)
+        {
+            throw new ArgumentException($"An orchestration with the instanceId {instanceId} was not found.", e);
+        }
+        catch (RpcException e) when (e.StatusCode == StatusCode.Cancelled)
+        {
+            throw new OperationCanceledException(
+                $"The {nameof(this.GetOrchestrationHistoryAsync)} operation was canceled.", e, cancellation);
+        }
+        catch (RpcException e) when (e.StatusCode == StatusCode.Internal)
+        {
+            throw new InvalidOperationException(
+                $"An error occurred while retrieving the history for orchestration with instanceId {instanceId}.", e);
+        }
+    }
+
     static AsyncDisposable GetCallInvoker(GrpcDurableTaskClientOptions options, out CallInvoker callInvoker)
     {
         if (options.Channel is GrpcChannel c)

src/Shared/Grpc/ProtoUtils.cs

@@ -80,7 +80,8 @@ internal static HistoryEvent ConvertHistoryEvent(P.HistoryEvent proto, EntityCon
                 historyEvent = new ExecutionCompletedEvent(
                     proto.EventId,
                     proto.ExecutionCompleted.Result,
-                    proto.ExecutionCompleted.OrchestrationStatus.ToCore());
+                    proto.ExecutionCompleted.OrchestrationStatus.ToCore(),
+                    proto.ExecutionCompleted.FailureDetails.ToCore());
                 break;
             case P.HistoryEvent.EventTypeOneofCase.ExecutionTerminated:
                 historyEvent = new ExecutionTerminatedEvent(proto.EventId, proto.ExecutionTerminated.Input);