Add IResponseType interface and enhance response serialization

Author: pwelter34

src/Arbiter.CommandQuery/Commands/PrincipalCommandBase.cs

@@ -33,7 +33,7 @@ namespace Arbiter.CommandQuery.Commands;
 /// Console.WriteLine($"User Name: {result?.Name}");
 /// </code>
 /// </example>
-public abstract record PrincipalCommandBase<TResponse> : IRequest<TResponse>, IRequestPrincipal
+public abstract record PrincipalCommandBase<TResponse> : IRequest<TResponse>, IRequestPrincipal, IResponseType
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="PrincipalCommandBase{TResponse}"/> class.
@@ -47,6 +47,7 @@ protected PrincipalCommandBase(ClaimsPrincipal? principal)
         ActivatedBy = principal?.Identity?.Name ?? "system";
     }
 
+
     /// <summary>
     /// Gets the <see cref="ClaimsPrincipal"/> representing the user executing the command.
     /// </summary>
@@ -82,6 +83,7 @@ protected PrincipalCommandBase(ClaimsPrincipal? principal)
     [IgnoreMember]
     public string? ActivatedBy { get; private set; }
 
+
     /// <summary>
     /// Applies the specified <see cref="ClaimsPrincipal"/> to the command.
     /// </summary>
@@ -92,4 +94,9 @@ void IRequestPrincipal.ApplyPrincipal(ClaimsPrincipal? principal)
         Activated = DateTimeOffset.UtcNow;
         ActivatedBy = principal?.Identity?.Name ?? "system";
     }
+
+    /// <summary>
+    /// Gets the type of the response returned by the command.
+    /// </summary>
+    Type IResponseType.ResponseType => typeof(TResponse);
 }

src/Arbiter.CommandQuery/Definitions/IResponseType.cs

@@ -0,0 +1,12 @@
+namespace Arbiter.CommandQuery.Definitions;
+
+/// <summary>
+/// Defines a contract for types that declare their response type.
+/// </summary>
+public interface IResponseType
+{
+    /// <summary>
+    /// Gets the type of the response.
+    /// </summary>
+    abstract Type ResponseType { get; }
+}

src/Arbiter.Dispatcher.Server/DispatcherEndpoint.cs

@@ -111,9 +111,14 @@ private async Task<IResult> Send(
                 return Results.Empty;
             }
 
+            // Determine response type if available, used for serialization
+            Type? responseType = null;
+            if (response is IResponseType responseInstance)
+                responseType = responseInstance.ResponseType;
+
             return isJson
                 ? TypedResults.Json<object>(response)
-                : new MessagePackResult<object>(response);
+                : new MessagePackResult(response, valueType: responseType);
         }
         catch (Exception ex)
         {

src/Arbiter.Dispatcher.Server/MessagePackResult.cs

@@ -15,26 +15,48 @@ namespace Arbiter.Dispatcher.Server;
 /// <summary>
 /// An <see cref="IResult"/> that serializes a value to MessagePack format and writes it to the HTTP response.
 /// </summary>
-/// <typeparam name="TValue">The type of the value to serialize.</typeparam>
-public class MessagePackResult<TValue> :
+/// <remarks>
+/// <para>
+/// This class provides a way to return MessagePack-serialized responses from ASP.NET Core minimal API endpoints.
+/// MessagePack is a binary serialization format that is typically faster and more compact than JSON.
+/// </para>
+/// <para>
+/// The class automatically handles null values by returning a 204 No Content response, and supports
+/// explicit type specification for serialization scenarios where the runtime type differs from the desired
+/// serialization type. This is particularly useful with collection initializers or when serializing
+/// derived types as their base type or interface.
+/// </para>
+/// <para>
+/// When used in minimal API endpoints, this class implements <see cref="IEndpointMetadataProvider"/>
+/// to automatically populate OpenAPI metadata for proper API documentation.
+/// </para>
+/// </remarks>
+public class MessagePackResult :
     IResult,
     IValueHttpResult,
-    IValueHttpResult<TValue>,
     IStatusCodeHttpResult,
     IContentTypeHttpResult,
     IEndpointMetadataProvider
 {
     /// <summary>
-    /// Initializes a new instance of the <see cref="MessagePackResult{TValue}"/> class.
+    /// Initializes a new instance of the <see cref="MessagePackResult"/> class.
     /// </summary>
     /// <param name="value">The value to serialize. If <c>null</c>, a 204 No Content response is returned.</param>
     /// <param name="statusCode">The HTTP status code. If not specified, defaults to 200 OK for non-null values and 204 No Content for null values.</param>
     /// <param name="contentType">The content type. If not specified, defaults to the MessagePack content type.</param>
-    public MessagePackResult(TValue? value, int? statusCode = null, string? contentType = null)
+    /// <param name="valueType">The type to use for MessagePack serialization. If not specified, defaults to the runtime type of the value.</param>
+    /// <remarks>
+    /// The <paramref name="valueType"/> parameter is used to explicitly specify the type for serialization.
+    /// This is particularly useful when the runtime type differs from the desired serialization type.
+    /// A common scenario is with collection initializers, where the concrete type (e.g., <c>List&lt;T&gt;</c>)
+    /// may need to be serialized as a different type (e.g., <c>IEnumerable&lt;T&gt;</c> or <c>T[]</c>).
+    /// </remarks>
+    public MessagePackResult(object? value, int? statusCode = null, string? contentType = null, Type? valueType = null)
     {
         Value = value;
         StatusCode = statusCode;
         ContentType = contentType;
+        ValueType = valueType;
     }
 
     /// <summary>
@@ -43,10 +65,7 @@ public MessagePackResult(TValue? value, int? statusCode = null, string? contentT
     /// <value>
     /// The value to serialize, or <c>null</c> if no content should be returned.
     /// </value>
-    public TValue? Value { get; }
-
-    /// <inheritdoc/>
-    object? IValueHttpResult.Value => Value;
+    public object? Value { get; }
 
     /// <summary>
     /// Gets the content type for the response.
@@ -64,6 +83,25 @@ public MessagePackResult(TValue? value, int? statusCode = null, string? contentT
     /// </value>
     public int? StatusCode { get; }
 
+    /// <summary>
+    /// Gets the type to use for MessagePack serialization.
+    /// </summary>
+    /// <value>
+    /// The type to use for serialization, or <c>null</c> to use the runtime type of <see cref="Value"/>.
+    /// </value>
+    /// <remarks>
+    /// <para>
+    /// This property allows explicit specification of the serialization type, which is useful when
+    /// the value should be serialized as a base type or interface rather than its concrete type.
+    /// If not specified, the actual runtime type of the value is used.
+    /// </para>
+    /// <para>
+    /// The type is used both for MessagePack serialization and to generate a portable type name
+    /// that is added to the response headers via <see cref="DispatcherConstants.ResponseTypeHeader"/>.
+    /// This portable name helps clients properly deserialize the response by providing explicit type information.
+    /// </para>
+    /// </remarks>
+    public Type? ValueType { get; }
 
     /// <summary>
     /// Executes the result operation, serializing the value to MessagePack format and writing it to the HTTP response.
@@ -86,7 +124,7 @@ public async Task ExecuteAsync(HttpContext httpContext)
         if (StatusCode is { } statusCode)
             httpContext.Response.StatusCode = statusCode;
 
-        var valueType = Value.GetType();
+        var valueType = ValueType ?? Value.GetType();
         var responseType = valueType.GetPortableName();
 
         var options = httpContext.RequestServices.GetService<MessagePackSerializerOptions>()