Add initial mediator pattern

Author: jviau

src/Abstractions/Mediator/IOrchestrationRequest.cs

@@ -0,0 +1,35 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace Microsoft.DurableTask;
+
+/// <summary>
+/// Represents the base request to run a <see cref="ITaskOrchestrator" />.
+/// </summary>
+public interface IBaseOrchestrationRequest
+{
+    /// <summary>
+    /// Gets the <see cref="TaskName" /> representing the <see cref="ITaskOrchestrator" /> to run.
+    /// </summary>
+    /// <returns>A <see cref="TaskName" />.</returns>
+    /// <remarks>
+    /// This is a function instead of a property so it is excluded in serialization without needing to use a
+    /// serialization library specific attribute to exclude it.
+    /// </remarks>
+    TaskName GetTaskName();
+}
+
+/// <summary>
+/// Represents a request to run a <see cref="ITaskOrchestrator" /> which returns <typeparamref name="TResult" />.
+/// </summary>
+/// <typeparam name="TResult">The result of the orchestrator that is to be ran.</typeparam>
+public interface IOrchestrationRequest<out TResult> : IBaseOrchestrationRequest
+{
+}
+
+/// <summary>
+/// Represents a request to run a <see cref="ITaskOrchestrator" /> which has no return.
+/// </summary>
+public interface IOrchestrationRequest : IOrchestrationRequest<Unit>
+{
+}

src/Abstractions/Mediator/Orchestrator.cs

@@ -0,0 +1,103 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace Microsoft.DurableTask;
+
+/// <summary>
+/// Base class for an orchestration.
+/// </summary>
+/// <typeparam name="TInput">The orchestration input type.</typeparam>
+/// <typeparam name="TOutput">The orchestration output type.</typeparam>
+public abstract class Orchestrator<TInput, TOutput> : ITaskOrchestrator
+    where TInput : IOrchestrationRequest<TOutput>
+{
+    /// <inheritdoc/>
+    Type ITaskOrchestrator.InputType => typeof(TInput);
+
+    /// <inheritdoc/>
+    Type ITaskOrchestrator.OutputType => typeof(TOutput);
+
+    /// <inheritdoc/>
+    async Task<object?> ITaskOrchestrator.RunAsync(TaskOrchestrationContext context, object? input)
+    {
+        Check.NotNull(context, nameof(context));
+        OrchestratorHelper.ValidateInput(input, out TInput typedInput);
+
+        return await this.RunAsync(context, typedInput);
+    }
+
+    /// <summary>
+    /// Override to implement task orchestrator logic.
+    /// </summary>
+    /// <param name="context">The task orchestrator's context.</param>
+    /// <param name="input">The deserialized orchestration input.</param>
+    /// <returns>The output of the orchestration as a task.</returns>
+    public abstract Task<TOutput> RunAsync(TaskOrchestrationContext context, TInput input);
+}
+
+/// <summary>
+/// Base class for an orchestration.
+/// </summary>
+/// <typeparam name="TInput">The orchestration input type.</typeparam>
+public abstract class Orchestrator<TInput> : ITaskOrchestrator
+    where TInput : IOrchestrationRequest<Unit>
+{
+    /// <inheritdoc/>
+    Type ITaskOrchestrator.InputType => typeof(TInput);
+
+    /// <inheritdoc/>
+    Type ITaskOrchestrator.OutputType => typeof(Unit);
+
+    /// <inheritdoc/>
+    async Task<object?> ITaskOrchestrator.RunAsync(TaskOrchestrationContext context, object? input)
+    {
+        Check.NotNull(context, nameof(context));
+        OrchestratorHelper.ValidateInput(input, out TInput typedInput);
+
+        await this.RunAsync(context, typedInput);
+        return Unit.Value;
+    }
+
+    /// <summary>
+    /// Override to implement task orchestrator logic.
+    /// </summary>
+    /// <param name="context">The task orchestrator's context.</param>
+    /// <param name="input">The deserialized orchestration input.</param>
+    /// <returns>The output of the orchestration as a task.</returns>
+    public abstract Task RunAsync(TaskOrchestrationContext context, TInput input);
+}
+
+/// <summary>
+/// Orchestration implementation helpers.
+/// </summary>
+static class OrchestratorHelper
+{
+    /// <summary>
+    /// Due to nullable reference types being static analysis only, we need to do our best efforts for validating the
+    /// input type, but also give control of nullability to the implementation. It is not ideal, but we do not want to
+    /// force 'TInput?' on the RunAsync implementation.
+    /// </summary>
+    /// <typeparam name="TInput">The input type of the orchestration.</typeparam>
+    /// <param name="input">The input object.</param>
+    /// <param name="typedInput">The input converted to the desired type.</param>
+    public static void ValidateInput<TInput>(object? input, out TInput typedInput)
+    {
+        if (input is TInput typed)
+        {
+            // Quick pattern check.
+            typedInput = typed;
+            return;
+        }
+        else if (input is not null && typeof(TInput) != input.GetType())
+        {
+            throw new ArgumentException($"Input type '{input?.GetType()}' does not match expected type '{typeof(TInput)}'.");
+        }
+
+        // Input is null and did not match a nullable value type. We do not have enough information to tell if it is
+        // valid or not. We will have to defer this decision to the implementation. Additionally, we will coerce a null
+        // input to a default value type here. This is to keep the two RunAsync(context, default) overloads to have
+        // identical behavior.
+        typedInput = default!;
+        return;
+    }
+}

src/Abstractions/Mediator/TaskOrchestrationContextRequestExtensions.cs

@@ -0,0 +1,45 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace Microsoft.DurableTask;
+
+/// <summary>
+/// Extensions for <see cref="TaskOrchestrationContext" /> for strongly-typed requests.
+/// </summary>
+public static class TaskOrchestrationContextRequestExtensions
+{
+    /// <summary>
+    /// Runs the sub-orchestration described by <paramref name="request" /> with <paramref name="request" /> as the
+    /// input to the orchestration itself.
+    /// </summary>
+    /// <typeparam name="TResult">The result type of the orchestration.</typeparam>
+    /// <param name="context">The context used to run the orchestration.</param>
+    /// <param name="request">The orchestration request.</param>
+    /// <param name="options">The task options.</param>
+    /// <returns>The result of the orchestration.</returns>
+    public static Task<TResult> RunAsync<TResult>(
+        this TaskOrchestrationContext context, IOrchestrationRequest<TResult> request, TaskOptions? options = null)
+    {
+        Check.NotNull(context);
+        Check.NotNull(request);
+        TaskName name = request.GetTaskName();
+        return context.CallSubOrchestratorAsync<TResult>(name, request, options);
+    }
+
+    /// <summary>
+    /// Runs the sub-orchestration described by <paramref name="request" /> with <paramref name="request" /> as the
+    /// input to the orchestration itself.
+    /// </summary>
+    /// <param name="context">The context used to run the orchestration.</param>
+    /// <param name="request">The orchestration request.</param>
+    /// <param name="options">The task options.</param>
+    /// <returns>A task that completes when the orchestration completes.</returns>
+    public static Task RunAsync(
+        this TaskOrchestrationContext context, IOrchestrationRequest<Unit> request, TaskOptions? options = null)
+    {
+        Check.NotNull(context);
+        Check.NotNull(request);
+        TaskName name = request.GetTaskName();
+        return context.CallSubOrchestratorAsync(name, request, options);
+    }
+}

src/Abstractions/Mediator/Unit.cs

@@ -0,0 +1,91 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace Microsoft.DurableTask;
+
+/// <summary>
+/// Represents a <see cref="Void" /> result.
+/// </summary>
+public readonly struct Unit : IEquatable<Unit>, IComparable<Unit>
+{
+#pragma warning disable CA1801 // unused parameters
+#pragma warning disable IDE0060 // unused parameters
+
+    static readonly Unit RefValue;
+
+    /// <summary>
+    /// Gets the default value for <see cref="Unit" />.
+    /// </summary>
+    public static ref readonly Unit Value => ref RefValue;
+
+    /// <summary>
+    /// Gets the task result for a <see cref="Unit" />.
+    /// </summary>
+    public static Task<Unit> Task { get; } = System.Threading.Tasks.Task.FromResult(RefValue);
+
+    /// <summary>
+    /// Compares two empties for equality. Always true.
+    /// </summary>
+    /// <param name="left">The left empty.</param>
+    /// <param name="right">The right empty.</param>
+    /// <returns>Always true.</returns>
+    public static bool operator ==(Unit left, Unit right) => true;
+
+    /// <summary>
+    /// Compares two empties for inequality. Always false.
+    /// </summary>
+    /// <param name="left">The left empty.</param>
+    /// <param name="right">The right empty.</param>
+    /// <returns>Always false.</returns>
+    public static bool operator !=(Unit left, Unit right) => !true;
+
+    /// <summary>
+    /// Compares two empties. Always false.
+    /// </summary>
+    /// <param name="left">The left empty.</param>
+    /// <param name="right">The right empty.</param>
+    /// <returns>Always false.</returns>
+    public static bool operator <(Unit left, Unit right) => false;
+
+    /// <summary>
+    /// Compares two empties. Always true.
+    /// </summary>
+    /// <param name="left">The left empty.</param>
+    /// <param name="right">The right empty.</param>
+    /// <returns>Always true.</returns>
+    public static bool operator <=(Unit left, Unit right) => true;
+
+    /// <summary>
+    /// Compares two empties. Always false.
+    /// </summary>
+    /// <param name="left">The left empty.</param>
+    /// <param name="right">The right empty.</param>
+    /// <returns>Always false.</returns>
+    public static bool operator >(Unit left, Unit right) => false;
+
+    /// <summary>
+    /// Compares two empties. Always true.
+    /// </summary>
+    /// <param name="left">The left empty.</param>
+    /// <param name="right">The right empty.</param>
+    /// <returns>Always true.</returns>
+    public static bool operator >=(Unit left, Unit right) => true;
+
+    /// <inheritdoc />
+    public int CompareTo(Unit other) => 0;
+
+    /// <inheritdoc />
+    public bool Equals(Unit other) => true;
+
+    /// <inheritdoc />
+    public override bool Equals(object obj) => obj is Unit;
+
+    /// <inheritdoc />
+    public override int GetHashCode() => 0;
+
+    /// <inheritdoc />
+    public override string ToString() => "{}";
+
+#pragma warning restore CA1801 // unused parameters
+#pragma warning restore IDE0060 // unused parameters
+}