fix!: Send Service Bus events as single objects instead of arrays (#261)

* Initial plan

* feat: Add singleEventDelivery configuration for ServiceBus subscribers

- Add SerializeSingle method to IEventSchemaFormatter to serialize single events without array wrapper
- Implement SerializeSingle in CloudEventSchemaFormatter and EventGridSchemaFormatter
- Add singleEventDelivery property to ServiceBusSubscriberSettings
- Update ServiceBusEventDeliveryService to use single event serialization when configured
- Add unit tests for single event serialization

Co-authored-by: pm7y <3075792+pm7y@users.noreply.github.com>

* test: Add test for explicit false value of singleEventDelivery

Address code review feedback by adding test for SingleEventDelivery = false

Co-authored-by: pm7y <3075792+pm7y@users.noreply.github.com>

* deps: Nuget upgrade

# Conflicts:
#	src/Directory.Packages.props

* fix!: Send Service Bus events as single objects instead of arrays

Service Bus delivery now always serializes events as single JSON objects
without array wrapping, matching Azure Event Grid's actual behavior.
Previously events were wrapped in a single-element array which forced
consumers to add unnecessary array-handling logic.

Removes the singleEventDelivery configuration option in favour of always
using the correct Azure behavior.

Also updates the commit-msg hook to support the ! breaking change
indicator per the Conventional Commits spec.

BREAKING CHANGE: Service Bus message bodies are now single JSON objects
instead of single-element arrays. Consumers that parse the array format
will need to be updated.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: pm7y <3075792+pm7y@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

.githooks/commit-msg

@@ -15,16 +15,19 @@ if echo "$commit_msg" | grep -qE "^Merge "; then
     exit 0
 fi
 
-# Conventional commit pattern: type(optional scope): description
+# Conventional commit pattern: type(optional scope)(optional !): description
 # Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert, deps
-pattern="^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert|deps)(\(.+\))?: .+"
+# The optional ! before the colon indicates a breaking change.
+pattern="^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert|deps)(\(.+\))?!?: .+"
 
 if ! echo "$commit_msg" | head -1 | grep -qE "$pattern"; then
     echo ""
     echo "ERROR: Commit message does not follow Conventional Commits format."
     echo ""
     echo "Expected format: <type>: <description>"
     echo "                 <type>(<scope>): <description>"
+    echo "                 <type>!: <description>"
+    echo "                 <type>(<scope>)!: <description>"
     echo ""
     echo "Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert, deps"
     echo ""
@@ -33,8 +36,11 @@ if ! echo "$commit_msg" | head -1 | grep -qE "$pattern"; then
     echo "  fix: resolve validation error"
     echo "  docs: update README"
     echo "  chore(deps): update dependencies"
+    echo "  fix!: change Service Bus message format"
+    echo "  feat(api)!: remove deprecated endpoint"
     echo ""
     echo "Note: There must be a space after the colon."
+    echo "      Use ! before the colon to indicate a breaking change."
     echo ""
     echo "Your commit message was:"
     echo "  $(head -1 "$commit_msg_file")"

src/AzureEventGridSimulator.Tests/UnitTests/Subscribers/Delivery/ServiceBusEventDeliveryServiceTests.cs

@@ -184,7 +184,7 @@ EventSchema schema
     }
 
     [Fact]
-    public void GivenEventGridFormatter_WhenSerializing_ThenReturnsJson()
+    public void GivenEventGridFormatter_WhenSerializing_ThenReturnsJsonArray()
     {
         var formatter = _formatterFactory.GetFormatter(EventSchema.EventGridSchema);
         var evt = CreateTestEvent();
@@ -193,10 +193,12 @@ public void GivenEventGridFormatter_WhenSerializing_ThenReturnsJson()
 
         json.ShouldNotBeNullOrEmpty();
         json.ShouldContain("test-event-id");
+        json.TrimStart().ShouldStartWith("[");
+        json.TrimEnd().ShouldEndWith("]");
     }
 
     [Fact]
-    public void GivenCloudEventFormatter_WhenSerializing_ThenReturnsJson()
+    public void GivenCloudEventFormatter_WhenSerializing_ThenReturnsJsonArray()
     {
         var formatter = _formatterFactory.GetFormatter(EventSchema.CloudEventV1_0);
         var evt = CreateTestEvent();
@@ -205,6 +207,8 @@ public void GivenCloudEventFormatter_WhenSerializing_ThenReturnsJson()
 
         json.ShouldNotBeNullOrEmpty();
         json.ShouldContain("test-event-id");
+        json.TrimStart().ShouldStartWith("[");
+        json.TrimEnd().ShouldEndWith("]");
     }
 
     [Fact]
@@ -248,4 +252,34 @@ public void GivenPropertyResolver_WhenResolvingDynamicProperty_ThenReturnsEventV
 
         resolved["Subject"].ShouldBe("test/subject");
     }
+
+    [Fact]
+    public void GivenCloudEventFormatter_WhenSerializingSingle_ThenReturnsJsonWithoutArray()
+    {
+        var formatter = _formatterFactory.GetFormatter(EventSchema.CloudEventV1_0);
+        var evt = CreateTestEvent();
+
+        var json = formatter.SerializeSingle(evt);
+
+        json.ShouldNotBeNullOrEmpty();
+        json.ShouldContain("test-event-id");
+        // Verify it's NOT an array (doesn't start with '[')
+        json.TrimStart().ShouldStartWith("{");
+        json.TrimEnd().ShouldEndWith("}");
+    }
+
+    [Fact]
+    public void GivenEventGridFormatter_WhenSerializingSingle_ThenReturnsJsonWithoutArray()
+    {
+        var formatter = _formatterFactory.GetFormatter(EventSchema.EventGridSchema);
+        var evt = CreateTestEvent();
+
+        var json = formatter.SerializeSingle(evt);
+
+        json.ShouldNotBeNullOrEmpty();
+        json.ShouldContain("test-event-id");
+        // Verify it's NOT an array (doesn't start with '[')
+        json.TrimStart().ShouldStartWith("{");
+        json.TrimEnd().ShouldEndWith("}");
+    }
 }

src/AzureEventGridSimulator/Domain/Services/CloudEventSchemaFormatter.cs

@@ -33,6 +33,13 @@ public string Serialize(SimulatorEvent evt)
         return JsonSerializer.Serialize(new[] { cloudEvent }, _serializerOptions);
     }
 
+    /// <inheritdoc />
+    public string SerializeSingle(SimulatorEvent evt)
+    {
+        var cloudEvent = ConvertToCloudEvent(evt);
+        return JsonSerializer.Serialize(cloudEvent, _serializerOptions);
+    }
+
     /// <inheritdoc />
     public string SerializeArray(IEnumerable<SimulatorEvent> events)
     {

src/AzureEventGridSimulator/Domain/Services/Delivery/ServiceBusEventDeliveryService.cs

@@ -58,8 +58,8 @@ CancellationToken cancellationToken
                 subscription.DeliverySchema ?? delivery.Topic.OutputSchema ?? delivery.InputSchema;
             var formatter = formatterFactory.GetFormatter(deliverySchema);
 
-            // Serialize the event
-            var json = formatter.Serialize(delivery.Event);
+            // Serialize as a single event (matches Azure Event Grid to Service Bus behavior)
+            var json = formatter.SerializeSingle(delivery.Event);
 
             // Get or create the sender
             var sender = GetOrCreateSender(subscription);
@@ -171,8 +171,8 @@ EventSchema inputSchema
             var deliverySchema = subscription.DeliverySchema ?? topic.OutputSchema ?? inputSchema;
             var formatter = formatterFactory.GetFormatter(deliverySchema);
 
-            // Serialize the event
-            var json = formatter.Serialize(evt);
+            // Serialize as a single event (matches Azure Event Grid to Service Bus behavior)
+            var json = formatter.SerializeSingle(evt);
 
             // Get or create the sender
             var sender = GetOrCreateSender(subscription);

src/AzureEventGridSimulator/Domain/Services/EventGridSchemaFormatter.cs

@@ -21,6 +21,13 @@ public string Serialize(SimulatorEvent evt)
         return JsonSerializer.Serialize(new[] { eventGridEvent });
     }
 
+    /// <inheritdoc />
+    public string SerializeSingle(SimulatorEvent evt)
+    {
+        var eventGridEvent = ConvertToEventGridEvent(evt);
+        return JsonSerializer.Serialize(eventGridEvent);
+    }
+
     /// <inheritdoc />
     public string SerializeArray(IEnumerable<SimulatorEvent> events)
     {

src/AzureEventGridSimulator/Domain/Services/IEventSchemaFormatter.cs

@@ -19,6 +19,7 @@ public interface IEventSchemaFormatter
 
     /// <summary>
     ///     Serializes an event to JSON for delivery.
+    ///     By default, wraps single events in an array for Azure Event Grid compatibility.
     /// </summary>
     /// <param name="evt">
     ///     The event to serialize.
@@ -28,6 +29,18 @@ public interface IEventSchemaFormatter
     /// </returns>
     string Serialize(SimulatorEvent evt);
 
+    /// <summary>
+    ///     Serializes a single event to JSON without array wrapper.
+    ///     Used for Service Bus delivery which doesn't use array format.
+    /// </summary>
+    /// <param name="evt">
+    ///     The event to serialize.
+    /// </param>
+    /// <returns>
+    ///     The JSON representation of the single event.
+    /// </returns>
+    string SerializeSingle(SimulatorEvent evt);
+
     /// <summary>
     ///     Serializes multiple events to JSON for delivery.
     /// </summary>

src/Directory.Packages.props

@@ -34,7 +34,7 @@
         <PackageVersion Include="OpenTelemetry.Instrumentation.Http" Version="1.15.0" />
         <PackageVersion Include="OpenTelemetry.Instrumentation.Runtime" Version="1.15.0" />
         <!-- Analyzers -->
-        <PackageVersion Include="Meziantou.Analyzer" Version="2.0.302" />
+        <PackageVersion Include="Meziantou.Analyzer" Version="3.0.1" />
         <!-- Conformance Testing CLI -->
         <PackageVersion Include="System.CommandLine" Version="2.0.0-beta4.22272.1" />
         <!-- Testing -->
@@ -44,6 +44,6 @@
         <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.0.1" />
         <PackageVersion Include="xunit" Version="2.9.3" />
         <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.5" />
-        <PackageVersion Include="coverlet.collector" Version="6.0.4" />
+        <PackageVersion Include="coverlet.collector" Version="8.0.0" />
     </ItemGroup>
 </Project>