feat: Add Event Hub Subscriber support (#227)

* feat: Add Event Hub Subscriber support

Author: pm7y

AGENTS.md

@@ -14,7 +14,7 @@ Azure Event Grid Simulator is a local development simulator that provides HTTPS
 **Key Features:**
 
 - Multi-topic support with individual HTTPS endpoints
-- HTTP webhook, Azure Service Bus, and Storage Queue subscriber delivery
+- HTTP webhook, Azure Service Bus, Storage Queue, and Event Hub subscriber delivery
 - Azure Event Grid-compatible retry with exponential backoff
 - Dead-letter support with local JSON file output
 - Event filtering (subject-based and advanced)
@@ -50,7 +50,7 @@ dotnet dev-certs https --trust
 The simulator uses `appsettings.json` for topic and subscriber configuration. Key settings:
 
 - **Topics**: Each topic requires `name`, `port`, and optional `key` for authentication
-- **Subscribers**: Supports HTTP webhooks, Azure Service Bus (queues/topics), and Storage Queues
+- **Subscribers**: Supports HTTP webhooks, Azure Service Bus (queues/topics), Storage Queues, and Event Hubs
 - **Filtering**: Event type, subject-based, and advanced filtering per subscriber
 - **Retry Policy**: Configurable per subscriber (maxDeliveryAttempts, eventTimeToLiveInMinutes, enabled)
 - **Dead-Letter**: Configurable per subscriber (enabled, folderPath for JSON output)
@@ -127,7 +127,7 @@ docker-compose -f /src/AzureEventGridSimulator/docker-compose.yml down
 │   │   ├── Commands/                  # Command handlers
 │   │   ├── Entities/                  # Domain models (including PendingDelivery, DeadLetterEvent)
 │   │   └── Services/                  # Domain services
-│   │       ├── Delivery/              # Event delivery services (HTTP, ServiceBus, StorageQueue)
+│   │       ├── Delivery/              # Event delivery services (HTTP, ServiceBus, StorageQueue, EventHub)
 │   │       └── Retry/                 # Retry infrastructure (queue, scheduler, dead-letter)
 │   ├── Infrastructure/                # Cross-cutting concerns
 │   │   ├── Extensions/                # Extension methods
@@ -259,13 +259,34 @@ Edit `appsettings.json` or `docker/appsettings.docker.json`:
             "endpoint": "https://example.com/webhook",
             "disableValidation": false
           }
+        ],
+        "eventHub": [
+          {
+            "name": "MyEventHubSubscriber",
+            "connectionString": "Endpoint=sb://my-namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=abc123",
+            "eventHubName": "my-event-hub",
+            "deliverySchema": "CloudEventV1_0",
+            "properties": {
+              "Label": { "type": "dynamic", "value": "Subject" },
+              "Region": { "type": "static", "value": "west-us" }
+            }
+          }
         ]
       }
     }
   ]
 }
 ```
 
+Event Hub subscribers support:
+- **connectionString**: Full connection string (or use namespace/sharedAccessKeyName/sharedAccessKey separately)
+- **eventHubName**: Target Event Hub name (required)
+- **deliverySchema**: Output schema (EventGridSchema or CloudEventV1_0)
+- **properties**: Custom properties added to EventData (static or dynamic values from event fields)
+- **filter**: Subject-based and advanced event filtering
+- **retryPolicy**: Retry configuration (maxDeliveryAttempts, eventTimeToLiveInMinutes)
+- **deadLetter**: Dead-letter configuration for failed deliveries
+
 ### Testing Event Publishing
 
 ```bash

README.md

@@ -12,7 +12,9 @@ of [Azure Event Grid](https://azure.microsoft.com/en-au/services/event-grid/) to
 with the `Microsoft.Azure.EventGrid` client library. Both the `EventGrid` schema and the `CloudEvents v1.0` schema are
 supported.
 
-> **Note:** This simulator is intended for **local development and testing only**. It is not designed for production use. For production workloads, use the official [Azure Event Grid](https://azure.microsoft.com/en-au/services/event-grid/) service.
+> **Note:** This simulator is intended for **local development and testing only**. It is not designed for production
+> use. For production workloads, use the
+> official [Azure Event Grid](https://azure.microsoft.com/en-au/services/event-grid/) service.
 
 ## Installation
 
@@ -98,11 +100,15 @@ An example of one topic with one subscriber is shown below.
 | `serviceBusSharedAccessKeyName` | (Optional) Default shared access key name for Service Bus.                                                                                                         |
 | `serviceBusSharedAccessKey`     | (Optional) Default shared access key for Service Bus.                                                                                                              |
 | `storageQueueConnectionString`  | (Optional) Default Storage Queue connection string for all Storage Queue subscribers in this topic. Subscribers can override with their own.                       |
+| `eventHubConnectionString`      | (Optional) Default Event Hub connection string for all Event Hub subscribers in this topic. Subscribers can override with their own.                               |
+| `eventHubNamespace`             | (Optional) Default Event Hub namespace (without `.servicebus.windows.net`). Use with `eventHubSharedAccessKeyName` and `eventHubSharedAccessKey`.                  |
+| `eventHubSharedAccessKeyName`   | (Optional) Default shared access key name for Event Hub.                                                                                                           |
+| `eventHubSharedAccessKey`       | (Optional) Default shared access key for Event Hub.                                                                                                                |
 
 ### Subscriber Settings
 
-The simulator supports three subscriber types: **HTTP webhooks**, **Azure Service Bus** (queues and topics), and **Azure
-Storage Queues**.
+The simulator supports four subscriber types: **HTTP webhooks**, **Azure Service Bus** (queues and topics), **Azure
+Storage Queues**, and **Azure Event Hubs**.
 
 #### Grouped Format (Recommended)
 
@@ -128,6 +134,13 @@ Storage Queues**.
         "connectionString": "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net",
         "queueName": "my-queue"
       }
+    ],
+    "eventHub": [
+      {
+        "name": "EventHubSubscription",
+        "connectionString": "Endpoint=sb://my-namespace.servicebus.windows.net/;SharedAccessKeyName=...;SharedAccessKey=...",
+        "eventHubName": "my-event-hub"
+      }
     ]
   }
 }
@@ -214,6 +227,31 @@ You can add custom application properties to Service Bus messages using static o
 | `retryPolicy`      | (Optional) Retry policy settings. See [Retry & Dead-Letter](#retry--dead-letter) section.                        |
 | `deadLetter`       | (Optional) Dead-letter settings. See [Retry & Dead-Letter](#retry--dead-letter) section.                         |
 
+#### Event Hub Subscriber Settings
+
+| Setting               | Description                                                                                                                                   |
+|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
+| `name`                | The name of the subscriber.                                                                                                                   |
+| `connectionString`    | The Event Hub connection string. Can be omitted if `eventHubConnectionString` is set at the topic level.                                      |
+| `namespace`           | The Event Hub namespace (without `.servicebus.windows.net` suffix). Alternative to `connectionString`. Can inherit from topic-level settings. |
+| `sharedAccessKeyName` | The shared access key name (e.g., `RootManageSharedAccessKey`). Used with `namespace`.                                                        |
+| `sharedAccessKey`     | The shared access key. Used with `namespace`.                                                                                                 |
+| `eventHubName`        | The name of the Event Hub to send events to. (Required)                                                                                       |
+| `deliverySchema`      | (Optional) Override the delivery schema. Values: `EventGridSchema` or `CloudEventV1_0`.                                                       |
+| `properties`          | (Optional) Custom delivery properties to add to Event Hub messages. See Service Bus Delivery Properties above for format.                     |
+| `filter`              | (Optional) Event filtering configuration. See [Filtering Events](#filtering-events) section.                                                  |
+| `retryPolicy`         | (Optional) Retry policy settings. See [Retry & Dead-Letter](#retry--dead-letter) section.                                                     |
+| `deadLetter`          | (Optional) Dead-letter settings. See [Retry & Dead-Letter](#retry--dead-letter) section.                                                      |
+
+Event Hub messages include standard Event Grid headers as properties:
+
+- `aeg-event-type`: Always "Notification"
+- `aeg-subscription-name`: The subscriber name (uppercase)
+- `aeg-delivery-count`: The delivery attempt number
+- `aeg-output-event-id`: The event ID
+- `aeg-data-version`: The event data version (EventGrid schema only)
+- `aeg-metadata-version`: Always "1" (EventGrid schema only)
+
 #### Complete Example
 
 ```json
@@ -225,6 +263,7 @@ You can add custom application properties to Service Bus messages using static o
       "key": "TheLocal+DevelopmentKey=",
       "serviceBusConnectionString": "Endpoint=sb://my-namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=...",
       "storageQueueConnectionString": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=...;EndpointSuffix=core.windows.net",
+      "eventHubConnectionString": "Endpoint=sb://my-eventhub-namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=...",
       "subscribers": {
         "http": [
           {
@@ -252,14 +291,26 @@ You can add custom application properties to Service Bus messages using static o
             "name": "OrdersStorageQueueSubscription",
             "queueName": "orders-archive"
           }
+        ],
+        "eventHub": [
+          {
+            "name": "OrdersEventHubSubscription",
+            "eventHubName": "orders-events",
+            "deliverySchema": "CloudEventV1_0",
+            "properties": {
+              "OrderId": { "type": "dynamic", "value": "data.orderId" },
+              "Region": { "type": "static", "value": "west-us" }
+            }
+          }
         ]
       }
     }
   ]
 }
 ```
 
-Note: The `serviceBus` and `storageQueue` subscribers above inherit their connection strings from the topic-level
+Note: The `serviceBus`, `storageQueue`, and `eventHub` subscribers above inherit their connection strings from the
+topic-level
 settings. Subscribers can override these by specifying their own `connectionString`.
 
 ### App Settings
@@ -576,9 +627,13 @@ The Docker Compose setup includes:
 
 - **Azure Event Grid Simulator** - The main simulator
 - **Azure Service Bus Emulator** - For testing Service Bus subscribers locally
+- **Azure Event Hubs Emulator** - For testing Event Hub subscribers locally
+- **Azurite** - Azure Storage emulator (required by Event Hubs emulator, also for Storage Queue subscribers)
 - **SQL Server** - Required by the Service Bus emulator
+- **Seq** - Structured log viewer (accessible at http://localhost:8081)
 
-See `docker/appsettings.docker.json` for an example configuration with both HTTP and Service Bus subscribers.
+See `docker/appsettings.docker.json` for an example configuration with HTTP, Service Bus, Storage Queue, and Event Hub
+subscribers.
 
 ## Using the Simulator
 
@@ -775,5 +830,4 @@ Some features that could be added if there was a need for them:
 
 - Certificate configuration in `appsettings.json`.
 - Subscriber token auth.
-- Azure Event Hub subscriber support.
 - Web-based console for admin stats etc.

docker/appsettings.docker.json

@@ -68,6 +68,23 @@
             "connectionString": "DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;QueueEndpoint=http://azurite:10001/devstoreaccount1;",
             "queueName": "eventgrid-events"
           }
+        ],
+        "eventHub": [
+          {
+            "name": "EventHubSubscription",
+            "connectionString": "Endpoint=sb://eventhubs-emulator;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;",
+            "eventHubName": "eventgrid-events",
+            "properties": {
+              "EventType": {
+                "type": "dynamic",
+                "value": "EventType"
+              },
+              "Source": {
+                "type": "static",
+                "value": "AzureEventGridSimulator"
+              }
+            }
+          }
         ]
       }
     }

docker/docker-compose.yml

@@ -23,6 +23,7 @@ services:
 
     depends_on:
       - servicebus-emulator
+      - eventhubs-emulator
       - azurite
       - seq
 
@@ -85,6 +86,27 @@ services:
         aliases:
           - servicebus-emulator
 
+  # Azure Event Hubs Emulator
+  # See: https://learn.microsoft.com/en-us/azure/event-hubs/test-locally-with-event-hub-emulator
+  eventhubs-emulator:
+    container_name: eventhubs-emulator
+    image: mcr.microsoft.com/azure-messaging/eventhubs-emulator:latest
+    pull_policy: always
+    volumes:
+      - ./eventhub-config.json:/Eventhubs_Emulator/ConfigFiles/Config.json
+    ports:
+      - "5673:5672"   # AMQP port (5673 external to avoid conflict with Service Bus)
+    environment:
+      BLOB_SERVER: azurite
+      METADATA_SERVER: azurite
+      ACCEPT_EULA: "Y"
+    depends_on:
+      - azurite
+    networks:
+      aegs-network:
+        aliases:
+          - eventhubs-emulator
+
   mssql:
     container_name: mssql
     image: mcr.microsoft.com/mssql/server:2022-latest

docker/eventhub-config.json

@@ -0,0 +1,24 @@
+{
+  "UserConfig": {
+    "NamespaceConfig": [
+      {
+        "Type": "EventHub",
+        "Name": "ehemulatorns",
+        "Entities": [
+          {
+            "Name": "eventgrid-events",
+            "PartitionCount": "2",
+            "ConsumerGroups": [
+              {
+                "Name": "default"
+              }
+            ]
+          }
+        ]
+      }
+    ],
+    "LoggingConfig": {
+      "Type": "File"
+    }
+  }
+}

docker/rebuild.ps1

@@ -0,0 +1,31 @@
+#!/usr/bin/env pwsh
+<#
+.SYNOPSIS
+    Rebuilds and restarts the Azure Event Grid Simulator Docker Compose stack.
+
+.DESCRIPTION
+    Stops all containers, rebuilds images with no cache, and starts the stack in detached mode.
+
+.EXAMPLE
+    ./rebuild.ps1
+#>
+
+$ErrorActionPreference = "Stop"
+
+Push-Location $PSScriptRoot
+
+try {
+    Write-Host "Stopping containers..." -ForegroundColor Yellow
+    docker-compose down
+
+    Write-Host "Rebuilding images (no cache)..." -ForegroundColor Yellow
+    docker-compose build --no-cache
+
+    Write-Host "Starting containers..." -ForegroundColor Green
+    docker-compose up -d
+
+    Write-Host "Done. Use 'docker-compose logs -f' to view logs." -ForegroundColor Cyan
+}
+finally {
+    Pop-Location
+}

src/AzureEventGridSimulator.Tests/UnitTests/Configuration/ConfigurationLoadingTests.cs

@@ -1,3 +1,4 @@
+using System.Text;
 using System.Text.Json;
 using AzureEventGridSimulator.Infrastructure.Settings;
 using Shouldly;
@@ -9,7 +10,53 @@ namespace AzureEventGridSimulator.Tests.UnitTests.Configuration;
 public class ConfigurationLoadingTests
 {
     [Fact]
-    public void TestConfigurationLoad()
+    public void IConfigurationBind_ShouldLoadEventHubSubscribers()
+    {
+        const string json = """
+            {
+                "topics": [{
+                    "name": "TestTopic",
+                    "port": 60101,
+                    "key": "TheLocal+DevelopmentKey=",
+                    "subscribers": {
+                        "http": [{
+                            "name": "HttpSubscriber",
+                            "endpoint": "https://example.com/webhook",
+                            "disableValidation": true
+                        }],
+                        "eventHub": [{
+                            "name": "EventHubSubscriber",
+                            "connectionString": "Endpoint=sb://test.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=testkey",
+                            "eventHubName": "test-hub"
+                        }]
+                    }
+                }]
+            }
+            """;
+
+        using var stream = new MemoryStream(Encoding.UTF8.GetBytes(json));
+        var configuration = new ConfigurationBuilder().AddJsonStream(stream).Build();
+
+        var settings = new SimulatorSettings();
+        configuration.Bind(settings);
+
+        settings.ShouldNotBeNull();
+        settings.Topics.ShouldNotBeNull();
+        settings.Topics.Length.ShouldBe(1);
+
+        var topic = settings.Topics.First();
+        topic.Subscribers.HttpSubscribers.Count().ShouldBe(1);
+        topic.Subscribers.HttpSubscribers.First().Name.ShouldBe("HttpSubscriber");
+
+        topic.Subscribers.EventHubSubscribers.Count().ShouldBe(1);
+        var eventHubSubscriber = topic.Subscribers.EventHubSubscribers.First();
+        eventHubSubscriber.Name.ShouldBe("EventHubSubscriber");
+        eventHubSubscriber.EventHubName.ShouldBe("test-hub");
+        eventHubSubscriber.ConnectionString.ShouldContain("sb://test.servicebus.windows.net");
+    }
+
+    [Fact]
+    public void JsonDeserialize_LegacyFormat_ShouldLoadHttpSubscribers()
     {
         // This test uses the legacy format (array of subscribers) to verify backwards compatibility
         const string json = """