perf: change IMessage.Data from byte[] to ReadOnlyMemory<byte> (#530)

* perf: change IMessage.Data from byte[] to ReadOnlyMemory<byte>

* Fix: Correct VitePress markdown syntax in messaging.md docs

- Replace unsupported ::: warning syntax with plain markdown bold text
- Fixes CI build error: 'Element is missing end tag' at line 207:135
- Build now passes successfully

* Fix: Remove incorrect v5.0 version reference from breaking change notice

This is a current breaking change, not from v5.0

* Address PR review: preserve byte[] no-copy path and strengthen no-copy test

- MessageBusBase: when no CLR type is mapped (Subscribe<byte[]>()), return the
  underlying managed array directly when the payload wraps a full-length array
  (offset 0, full count) instead of always allocating via ToArray(). Falls back
  to a copy only when the memory is sliced or not array-backed, preserving the
  pre-ReadOnlyMemory byte[] no-copy behavior.
- MessageTests: assert the stored ReadOnlyMemory is backed by the same array
  instance and segment as the source payload to actually verify no-copy.

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* docs: restore Common Patterns heading; soften IMessage.Data buffer-lifetime wording

Address review feedback:
- Restore the '## Common Patterns' section header that was accidentally replaced
  by the breaking-change note, and promote the note to a proper '#### Breaking
  change' subsection so 'Event-Driven Architecture' is no longer mis-nested under
  'Message Types'.
- Reword the IMessage.Data remarks to frame buffer validity as an implementation
  expectation (with consumer guidance to copy via ToArray()) rather than a hard
  guarantee that external implementers may not uphold.

* style: add blank lines after guards; rename tests to 3-part convention with AAA blocks

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: niemyjski

benchmarks/Program.cs

@@ -1,3 +1,4 @@
+using BenchmarkDotNet.Configs;
 using BenchmarkDotNet.Running;
 using RhoMicro.BdnLogging;
 
@@ -14,6 +15,11 @@ public static void Main(string[] args)
         //   dotnet run -c Release -- --filter *Resilience* # Run only resilience benchmarks
         //   dotnet run -c Release -- --filter *DeepClone*  # Run only deep clone benchmarks
         //   dotnet run -c Release -- --list tree           # List all benchmarks
-        BenchmarkSwitcher.FromAssembly(typeof(Program).Assembly).Run(args, SpotlightConfig.Instance);
+
+        // The spotlight logger renders a live, cursor-positioned console. When output is
+        // redirected (CI, agents, log files) there is no interactive console and its cursor
+        // calls throw, so fall back to the default config in that case.
+        var config = System.Console.IsOutputRedirected ? DefaultConfig.Instance : SpotlightConfig.Instance;
+        BenchmarkSwitcher.FromAssembly(typeof(Program).Assembly).Run(args, config);
     }
 }

docs/guide/messaging.md

@@ -273,6 +273,16 @@ await messageBus.SubscribeAsync(async (IMessage message, CancellationToken ct) =
 });
 ```
 
+#### Breaking change: `IMessage.Data` is now `ReadOnlyMemory<byte>`
+
+`IMessage.Data` exposes the raw payload as `ReadOnlyMemory<byte>` instead of `byte[]`. This lets memory-backed transports such as Azure Service Bus avoid copying the payload into a new array. Since it is a struct, follow these patterns:
+
+- Check for an empty payload with `message.Data.IsEmpty` (not `== null`)
+- Read the bytes directly via `message.Data.Span`
+- Call `message.Data.ToArray()` only when you need a `byte[]`
+
+Most code that uses `GetBody()` / `Body` is unaffected. When constructing a `Message`, you can still pass a `byte[]`; it converts implicitly to `ReadOnlyMemory<byte>`.
+
 ## Common Patterns
 
 ### Event-Driven Architecture

src/Foundatio.TestHarness/Serializer/SerializerTestsBase.cs

@@ -31,6 +31,7 @@ public virtual void Deserialize_WithInvalidInput_ThrowsArgumentException()
         Assert.Throws<ArgumentNullException>(() => serializer.Deserialize<SerializeModel>((Stream)null!));
         Assert.Throws<ArgumentNullException>(() => serializer.Deserialize<SerializeModel>((byte[])null!));
         Assert.Throws<ArgumentException>(() => serializer.Deserialize<SerializeModel>([]));
+        Assert.Throws<ArgumentException>(() => serializer.Deserialize<SerializeModel>(ReadOnlyMemory<byte>.Empty));
         Assert.Throws<ArgumentNullException>(() => serializer.Deserialize<SerializeModel>((string)null!));
         Assert.Throws<ArgumentException>(() => serializer.Deserialize<SerializeModel>(String.Empty));
         Assert.Throws<ArgumentException>(() => serializer.Deserialize<SerializeModel>("   "));
@@ -116,6 +117,24 @@ public virtual void Deserialize_WithValidBytes_ReturnsDeserializedObject()
         Assert.Equal(model.StringProperty, actual.StringProperty);
         Assert.Equal(model.ListProperty, actual.ListProperty);
 
+        // Act - ReadOnlyMemory<byte> over a managed array (MemoryMarshal.TryGetArray fast path)
+        var fromArrayMemory = serializer.Deserialize<SerializeModel>(new ReadOnlyMemory<byte>(bytes));
+        Assert.NotNull(fromArrayMemory);
+
+        // Assert
+        Assert.Equal(model.IntProperty, fromArrayMemory.IntProperty);
+        Assert.Equal(model.StringProperty, fromArrayMemory.StringProperty);
+        Assert.Equal(model.ListProperty, fromArrayMemory.ListProperty);
+
+        // Act - ReadOnlyMemory<byte> NOT backed by a managed array (ReadOnlyMemoryStream fallback)
+        var fromNativeMemory = serializer.Deserialize<SerializeModel>(CreateNativeBackedMemory(bytes));
+        Assert.NotNull(fromNativeMemory);
+
+        // Assert
+        Assert.Equal(model.IntProperty, fromNativeMemory.IntProperty);
+        Assert.Equal(model.StringProperty, fromNativeMemory.StringProperty);
+        Assert.Equal(model.ListProperty, fromNativeMemory.ListProperty);
+
         // Act
         string text = serializer.SerializeToString(model);
         actual = serializer.Deserialize<SerializeModel>(text);
@@ -430,6 +449,32 @@ private static bool IsNumericType(object value)
         return value is byte or sbyte or short or ushort or int or uint or long or ulong
             or float or double or decimal;
     }
+
+    /// <summary>
+    /// Creates a <see cref="ReadOnlyMemory{T}"/> that is NOT backed by a managed array (it is backed by a
+    /// custom <see cref="System.Buffers.MemoryManager{T}"/>), so the
+    /// <see cref="System.Runtime.InteropServices.MemoryMarshal.TryGetArray"/> fast path fails and the
+    /// <c>ReadOnlyMemoryStream</c> fallback is exercised.
+    /// </summary>
+    private static ReadOnlyMemory<byte> CreateNativeBackedMemory(byte[] source)
+    {
+        return new ManagerBackedMemory(source).Memory;
+    }
+
+    private sealed class ManagerBackedMemory : System.Buffers.MemoryManager<byte>
+    {
+        private readonly byte[] _buffer;
+
+        public ManagerBackedMemory(byte[] source) => _buffer = source;
+
+        public override Span<byte> GetSpan() => _buffer;
+
+        public override System.Buffers.MemoryHandle Pin(int elementIndex = 0) => throw new NotSupportedException();
+
+        public override void Unpin() { }
+
+        protected override void Dispose(bool disposing) { }
+    }
 }
 
 [MemoryDiagnoser]

src/Foundatio/Messaging/Message.cs

@@ -35,7 +35,13 @@ public interface IMessage
     /// <summary>
     /// Gets the raw serialized message payload.
     /// </summary>
-    byte[] Data { get; }
+    /// <remarks>
+    /// Returned as a <see cref="ReadOnlyMemory{T}"/> to avoid forcing an array copy on providers
+    /// whose transport buffers are already memory-backed (e.g. Azure Service Bus). Implementations
+    /// are expected to keep the underlying buffer valid for the lifetime of the message; consumers
+    /// that need to retain the payload beyond the current operation should copy it via <c>ToArray()</c>.
+    /// </remarks>
+    ReadOnlyMemory<byte> Data { get; }
 
     /// <summary>
     /// Deserializes and returns the message payload.
@@ -65,7 +71,7 @@ public class Message : IMessage
 {
     private readonly Func<IMessage, object?> _getBody;
 
-    public Message(byte[] data, Func<IMessage, object?> getBody)
+    public Message(ReadOnlyMemory<byte> data, Func<IMessage, object?> getBody)
     {
         Data = data;
         _getBody = getBody;
@@ -77,7 +83,7 @@ public Message(byte[] data, Func<IMessage, object?> getBody)
     public Type? ClrType { get; set; }
     [DisallowNull]
     public IDictionary<string, string> Properties { get => field; set => field = value ?? new Dictionary<string, string>(); } = new Dictionary<string, string>();
-    public byte[] Data { get; set; }
+    public ReadOnlyMemory<byte> Data { get; set; }
     public object? GetBody() => _getBody(this);
 }
 
@@ -90,7 +96,7 @@ public Message(IMessage message)
         _message = message;
     }
 
-    public byte[] Data => _message.Data;
+    public ReadOnlyMemory<byte> Data => _message.Data;
 
     public T Body => GetBody() as T ?? throw new MessageBusException("Message body is null or not of expected type");
 

src/Foundatio/Messaging/MessageBusBase.cs

@@ -4,6 +4,7 @@
 using System.Diagnostics;
 using System.Linq;
 using System.Reflection;
+using System.Runtime.InteropServices;
 using System.Threading;
 using System.Threading.Tasks;
 using Foundatio.Resilience;
@@ -319,14 +320,14 @@ protected virtual byte[] SerializeMessageBody(string messageType, object body)
 
     protected virtual object? DeserializeMessageBody(IMessage message)
     {
-        if (message.Data is null || message.Data.Length == 0)
+        if (message.Data.IsEmpty)
             return null;
 
         object? body;
         try
         {
             var clrType = message.ClrType ?? GetMappedMessageType(message.Type);
-            body = clrType != null ? _serializer.Deserialize(message.Data, clrType) : message.Data;
+            body = clrType != null ? _serializer.Deserialize(message.Data, clrType) : GetRawBody(message.Data);
         }
         catch (Exception ex)
         {
@@ -337,6 +338,27 @@ protected virtual byte[] SerializeMessageBody(string messageType, object body)
         return body;
     }
 
+    /// <summary>
+    /// Returns the raw payload as a <see cref="byte"/> array for subscribers that consume the body
+    /// without a mapped CLR type (e.g. <c>Subscribe&lt;byte[]&gt;()</c>).
+    /// </summary>
+    /// <remarks>
+    /// When the payload already wraps a full-length managed array (offset 0, count equal to the array
+    /// length) the underlying array is returned directly, preserving the no-copy behavior that existed
+    /// before <see cref="IMessage.Data"/> became a <see cref="ReadOnlyMemory{T}"/>. Otherwise the memory
+    /// is copied to honor the <c>byte[]</c> contract.
+    /// </remarks>
+    private static byte[] GetRawBody(ReadOnlyMemory<byte> data)
+    {
+        if (MemoryMarshal.TryGetArray(data, out ArraySegment<byte> segment) && segment.Array is not null
+            && segment.Offset == 0 && segment.Count == segment.Array.Length)
+        {
+            return segment.Array;
+        }
+
+        return data.ToArray();
+    }
+
     protected async Task SendMessageToSubscribersAsync(IMessage message)
     {
         if (IsDisposed)

src/Foundatio/Serializer/ISerializer.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Diagnostics.CodeAnalysis;
 using System.IO;
+using System.Runtime.InteropServices;
 using System.Text;
 
 namespace Foundatio.Serializer;
@@ -107,6 +108,51 @@ public static T Deserialize<T>(this ISerializer serializer, byte[] data)
         return serializer.Deserialize(stream, objectType);
     }
 
+    /// <summary>
+    /// Deserializes an object of type <typeparamref name="T"/> from <paramref name="data"/>.
+    /// </summary>
+    /// <returns>The deserialized value, or <c>default</c> if the underlying serializer returns <c>null</c>.</returns>
+    /// <remarks>
+    /// The return type is <c>T</c> annotated with <c>[return: MaybeNull]</c> rather than <c>T?</c>
+    /// because <c>T?</c> on an unconstrained generic would double-wrap <c>Nullable&lt;T&gt;</c> value types.
+    /// Callers that expect <c>null</c> should use a nullable type argument, e.g. <c>Deserialize&lt;MyType?&gt;</c>.
+    /// </remarks>
+    [return: MaybeNull]
+    public static T Deserialize<T>(this ISerializer serializer, ReadOnlyMemory<byte> data)
+    {
+        ArgumentNullException.ThrowIfNull(serializer);
+        if (data.IsEmpty)
+            throw new ArgumentException("Data cannot be empty.", nameof(data));
+
+        object? result = serializer.Deserialize(data, typeof(T));
+        if (result is T typed)
+            return typed;
+
+        if (result is not null)
+            throw new SerializerException($"Deserialized object is of type '{result.GetType().FullName}', expected '{typeof(T).FullName}'.");
+
+        return default!;
+    }
+
+    public static object? Deserialize(this ISerializer serializer, ReadOnlyMemory<byte> data, Type objectType)
+    {
+        ArgumentNullException.ThrowIfNull(serializer);
+        ArgumentNullException.ThrowIfNull(objectType);
+        if (data.IsEmpty)
+            throw new ArgumentException("Data cannot be empty.", nameof(data));
+
+        // Fast path: if the memory is backed by a managed array we can hand it straight to a
+        // MemoryStream without copying. Otherwise fall back to a stream over the memory.
+        if (MemoryMarshal.TryGetArray(data, out ArraySegment<byte> segment) && segment.Array is not null)
+        {
+            using var arrayStream = new MemoryStream(segment.Array, segment.Offset, segment.Count, writable: false);
+            return serializer.Deserialize(arrayStream, objectType);
+        }
+
+        using var stream = new ReadOnlyMemoryStream(data);
+        return serializer.Deserialize(stream, objectType);
+    }
+
     /// <summary>
     /// Deserializes an object of type <typeparamref name="T"/> from <paramref name="data"/>.
     /// </summary>

src/Foundatio/Serializer/ReadOnlyMemoryStream.cs

@@ -0,0 +1,90 @@
+using System;
+using System.IO;
+
+namespace Foundatio.Serializer;
+
+/// <summary>
+/// A read-only, seekable <see cref="Stream"/> over a <see cref="ReadOnlyMemory{T}"/> of bytes.
+/// </summary>
+/// <remarks>
+/// Used as a fallback for deserializing a <see cref="ReadOnlyMemory{T}"/> whose backing store is not
+/// a managed array (so the no-copy <see cref="System.Runtime.InteropServices.MemoryMarshal.TryGetArray"/>
+/// fast path is unavailable). This avoids allocating an intermediate <c>byte[]</c> copy just to wrap
+/// the payload in a <see cref="MemoryStream"/>.
+/// </remarks>
+internal sealed class ReadOnlyMemoryStream : Stream
+{
+    private readonly ReadOnlyMemory<byte> _memory;
+    private int _position;
+
+    public ReadOnlyMemoryStream(ReadOnlyMemory<byte> memory)
+    {
+        _memory = memory;
+    }
+
+    public override bool CanRead => true;
+    public override bool CanSeek => true;
+    public override bool CanWrite => false;
+    public override long Length => _memory.Length;
+
+    public override long Position
+    {
+        get => _position;
+        set
+        {
+            ArgumentOutOfRangeException.ThrowIfNegative(value);
+            ArgumentOutOfRangeException.ThrowIfGreaterThan(value, _memory.Length);
+
+            _position = (int)value;
+        }
+    }
+
+    public override int Read(byte[] buffer, int offset, int count)
+    {
+        ArgumentNullException.ThrowIfNull(buffer);
+        return Read(buffer.AsSpan(offset, count));
+    }
+
+    public override int Read(Span<byte> buffer)
+    {
+        int remaining = _memory.Length - _position;
+        if (remaining <= 0)
+            return 0;
+
+        int toCopy = Math.Min(remaining, buffer.Length);
+        _memory.Span.Slice(_position, toCopy).CopyTo(buffer);
+        _position += toCopy;
+        return toCopy;
+    }
+
+    public override int ReadByte()
+    {
+        if (_position >= _memory.Length)
+            return -1;
+
+        return _memory.Span[_position++];
+    }
+
+    public override long Seek(long offset, SeekOrigin origin)
+    {
+        long target = origin switch
+        {
+            SeekOrigin.Begin => offset,
+            SeekOrigin.Current => _position + offset,
+            SeekOrigin.End => _memory.Length + offset,
+            _ => throw new ArgumentOutOfRangeException(nameof(origin))
+        };
+
+        ArgumentOutOfRangeException.ThrowIfNegative(target);
+        ArgumentOutOfRangeException.ThrowIfGreaterThan(target, _memory.Length);
+
+        _position = (int)target;
+        return _position;
+    }
+
+    public override void Flush() { }
+
+    public override void SetLength(long value) => throw new NotSupportedException();
+
+    public override void Write(byte[] buffer, int offset, int count) => throw new NotSupportedException();
+}

tests/Foundatio.Tests/Messaging/InMemoryMessageBusTests.cs

@@ -265,7 +265,7 @@ await messageBus.SubscribeAsync(msg =>
         {
             Assert.Null(msg.Type);
             Assert.Null(msg.ClrType);
-            Assert.NotEmpty(msg.Data);
+            Assert.False(msg.Data.IsEmpty);
             rawReceived.Signal();
         }, TestCancellationToken);