Distributed mediator: queues, pub/sub, and worker infrastructure

.vscode/launch.json

@@ -1,20 +1,28 @@
 {
-  // Use IntelliSense to learn about possible attributes.
-  // Hover to view descriptions of existing attributes.
-  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
-  "version": "0.2.0",
-  "configurations": [
-    {
-      "name": "Clean Architecture Sample",
-      "type": "dotnet",
-      "request": "launch",
-      "projectPath": "${workspaceFolder}/samples/CleanArchitectureSample/src/Api/Api.csproj"
-    },
-    {
-      "name": "Console Sample",
-      "type": "dotnet",
-      "request": "launch",
-      "projectPath": "${workspaceFolder}/samples/ConsoleSample/ConsoleSample.csproj"
-    }
-  ]
-}
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "aspire",
+            "request": "launch",
+            "name": "Clean Architecture Sample",
+            "program": "${workspaceFolder}/samples/CleanArchitectureSample/src/AppHost/AppHost.csproj",
+            "debuggers2": {
+                "project": {
+                    "console": "integratedTerminal",
+                    "logging": {
+                        "moduleLoad": false
+                    }
+                }
+            }
+        },
+        {
+            "name": "Console Sample",
+            "type": "dotnet",
+            "request": "launch",
+            "projectPath": "${workspaceFolder}/samples/ConsoleSample/ConsoleSample.csproj"
+        }
+    ]
+}

Foundatio.Mediator.slnx

@@ -12,6 +12,8 @@
     <Project Path="samples/CleanArchitectureSample/src/Products.Module/Products.Module.csproj" />
     <Project Path="samples/CleanArchitectureSample/src/Reports.Module/Reports.Module.csproj" />
     <Project Path="samples/CleanArchitectureSample/src/Web/Web.esproj" />
+    <Project Path="samples/CleanArchitectureSample/src/ServiceDefaults/ServiceDefaults.csproj" />
+    <Project Path="samples/CleanArchitectureSample/src/AppHost/AppHost.csproj" />
   </Folder>
   <Folder Name="/Solution Items/">
     <File Path=".github/copilot-instructions.md" />
@@ -21,8 +23,15 @@
   <Folder Name="/src/">
     <Project Path="src/Foundatio.Mediator.Abstractions/Foundatio.Mediator.Abstractions.csproj" />
     <Project Path="src/Foundatio.Mediator/Foundatio.Mediator.csproj" />
+    <Project Path="src/Foundatio.Mediator.Distributed/Foundatio.Mediator.Distributed.csproj" />
+    <Project Path="src/Foundatio.Mediator.Distributed.Aws/Foundatio.Mediator.Distributed.Aws.csproj" />
+    <Project Path="src/Foundatio.Mediator.Distributed.Redis/Foundatio.Mediator.Distributed.Redis.csproj" />
   </Folder>
   <Folder Name="/tests/">
     <Project Path="tests/Foundatio.Mediator.Tests/Foundatio.Mediator.Tests.csproj" />
+    <Project Path="tests/Foundatio.Mediator.Distributed.Tests/Foundatio.Mediator.Distributed.Tests.csproj" />
+    <Project Path="tests/Foundatio.Mediator.Distributed.Aws.Tests/Foundatio.Mediator.Distributed.Aws.Tests.csproj" />
+    <Project Path="tests/Foundatio.Mediator.Distributed.Redis.Tests/Foundatio.Mediator.Distributed.Redis.Tests.csproj" />
+
   </Folder>
 </Solution>

README.md

@@ -85,6 +85,32 @@ GET  /api/todos/{id}  → 200 OK / 404 Not Found
 
 Routes, HTTP methods, parameter binding, and OpenAPI metadata are all inferred from your message names and `Result` factory calls.
 
+### Go distributed
+
+Ready to scale out? Add `[Queue]` to any handler — same code, now processed asynchronously via a background queue:
+
+```csharp
+public record SendEmail(string To, string Subject, string Body);
+
+[Queue]
+public class SendEmailHandler(IEmailService email)
+{
+    public async Task HandleAsync(SendEmail msg, CancellationToken ct)
+        => await email.SendAsync(msg.To, msg.Subject, msg.Body, ct);
+}
+```
+
+The message is queued and processed asynchronously by a background worker. Full retry, dead-lettering, and progress tracking built in.
+
+Broadcast events across all nodes in your cluster with a marker interface:
+
+```csharp
+public record ProductPriceChanged(string ProductId, decimal NewPrice) : IDistributedNotification;
+```
+
+Your handlers, middleware, DI, and error handling all work exactly the same — the distributed layer just changes _where_ execution happens. Pluggable transports for AWS SQS/SNS, with more coming soon.
+
+
 **👉 [Getting Started Guide](https://mediator.foundatio.dev/guide/getting-started.html)** — step-by-step setup with code samples for ASP.NET Core and console apps.
 
 **📖 [Complete Documentation](https://mediator.foundatio.dev)**

aspire.config.json

@@ -0,0 +1,5 @@
+{
+  "appHost": {
+    "path": "samples/CleanArchitectureSample/src/AppHost/AppHost.csproj"
+  }
+}

benchmarks/Foundatio.Mediator.Benchmarks/Foundatio.Mediator.Benchmarks.csproj

@@ -32,12 +32,12 @@
 
   <ItemGroup>
     <PackageReference Include="BenchmarkDotNet" Version="0.15.8" />
-    <PackageReference Include="Immediate.Handlers" Version="3.3.0" />
-    <PackageReference Include="MassTransit" Version="9.0.1" />
+    <PackageReference Include="Immediate.Handlers" Version="3.4.0" />
+    <PackageReference Include="MassTransit" Version="9.1.0" />
     <PackageReference Include="MediatR" Version="14.1.0" />
     <PackageReference Include="RhoMicro.BdnLogging" Version="1.0.3" />
-    <PackageReference Include="WolverineFx" Version="5.27.0" />
-    <PackageReference Include="Scriban" Version="7.0.3" /> <!-- Override transitive Scriban to fix NU1902/NU1903 vulnerabilities -->
+    <PackageReference Include="WolverineFx" Version="5.29.0" />
+    <PackageReference Include="Scriban" Version="7.1.0" /> <!-- Override transitive Scriban to fix NU1902/NU1903 vulnerabilities -->
     <PackageReference Include="Mediator.Abstractions" Version="3.0.2" />
     <PackageReference Include="Mediator.SourceGenerator" Version="3.0.2" PrivateAssets="All" />
     <PackageReference Include="Microsoft.AspNetCore.TestHost" Version="10.0.5" />

build/common.props

@@ -10,6 +10,7 @@
     <PackageReleaseNotes>https://github.com/FoundatioFx/Foundatio.Mediator/releases</PackageReleaseNotes>
     <PackageTags>Foundatio;Mediator;CQRS;Messaging;SourceGenerator;Interceptors</PackageTags>
     <MinVerSkip Condition="'$(Configuration)' == 'Debug'">true</MinVerSkip>
+    <MinVerDefaultPreReleaseIdentifiers>beta.0</MinVerDefaultPreReleaseIdentifiers>
     <MinVerTagPrefix>v</MinVerTagPrefix>
 
     <Copyright>Copyright © $([System.DateTime]::Now.ToString(yyyy)) Foundatio.  All rights reserved.</Copyright>

build/distributed.props

@@ -0,0 +1,10 @@
+<Project>
+
+  <!-- Distributed packages are versioned separately. Bump here when releasing. -->
+  <PropertyGroup>
+    <MinVerSkip>true</MinVerSkip>
+    <Version>0.1.0-beta1</Version>
+    <PackageTags>$(PackageTags);Distributed</PackageTags>
+  </PropertyGroup>
+
+</Project>

docs/.vitepress/config.ts

@@ -53,6 +53,15 @@ export default withMermaid(defineConfig({
             { text: 'Testing', link: '/guide/testing' }
           ]
         },
+        {
+          text: 'Distributed',
+          items: [
+            { text: 'Going Distributed', link: '/guide/distributed-overview' },
+            { text: 'Distributed Queues', link: '/guide/distributed-queues' },
+            { text: 'Distributed Notifications', link: '/guide/distributed-notifications' },
+            { text: 'Transport Providers', link: '/guide/distributed-transports' }
+          ]
+        },
         {
           text: 'Advanced Topics',
           items: [