More route conventions

Author: ejsmith

README.md

@@ -29,6 +29,62 @@ Foundatio Mediator is a high-performance mediator library for .NET that uses sou
 dotnet add package Foundatio.Mediator
 ```
 
+Define a message and a handler — no interfaces or base classes required:
+
+```csharp
+public record Ping(string Text);
+
+public static class PingHandler
+{
+    public static string Handle(Ping msg) => $"Pong: {msg.Text}";
+}
+```
+
+Wire up DI and call it:
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddMediator();
+
+var app = builder.Build();
+
+app.MapGet("/ping", (IMediator mediator) =>
+    mediator.Invoke<string>(new Ping("Hello")));
+
+app.Run();
+```
+
+That's it. The source generator discovers handlers by naming convention at compile time — zero registration, zero reflection, near-direct-call performance.
+
+### Generate API endpoints
+
+Handlers can automatically become API endpoints. Return `Result<T>` for rich HTTP status mapping:
+
+```csharp
+public record CreateTodo(string Title);
+public record GetTodo(int Id);
+
+public class TodoHandler
+{
+    public Result<Todo> Handle(CreateTodo command) =>
+        Result<Todo>.Created(new Todo(1, command.Title));
+
+    public Result<Todo> Handle(GetTodo query) =>
+        query.Id > 0 ? new Todo(query.Id, "Sample") : Result.NotFound();
+}
+```
+
+```csharp
+app.MapMediatorEndpoints();
+```
+
+```
+POST /api/todos       → 201 Created
+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.
+
 **👉 [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)**

docs/guide/endpoints.md

@@ -240,7 +240,7 @@ The HTTP method is inferred from the message type name prefix:
 | `Delete*`, `Remove*` | DELETE |
 | `Patch*` | PATCH |
 
-**Action verbs** — prefixes like `Complete*`, `Approve*`, `Cancel*`, `Submit*`, `Archive*`, `Publish*`, etc., default to **POST** and produce an action route suffix:
+**Action verbs** — prefixes like `Complete*`, `Approve*`, `Cancel*`, `Submit*`, `Archive*`, `Publish*`, `Export*`, `Import*`, `Download*`, `Upload*`, etc., default to **POST** and produce an action route suffix:
 
 ```csharp
 // POST /api/todos/{todoId}/complete
@@ -341,6 +341,61 @@ To override auto-pluralization, use an explicit route:
 public Result<Item> Handle(GetItem query) { ... }
 ```
 
+### Message Naming Conventions
+
+Routes are derived from the **message type name**. The generator strips a verb prefix, normalizes common qualifiers, pluralizes the entity, and converts to kebab-case. Understanding this pipeline helps you write message names that produce clean, consistent routes.
+
+**The golden path** — these naming patterns produce RESTful routes automatically:
+
+```csharp
+public record GetTodo(string Id);      // → GET    /api/todos/{id}
+public record GetTodos();              // → GET    /api/todos
+public record CreateTodo(string Name); // → POST   /api/todos
+public record UpdateTodo(string Id);   // → PUT    /api/todos/{id}
+public record DeleteTodo(string Id);   // → DELETE /api/todos/{id}
+public record CompleteTodo(string Id); // → POST   /api/todos/{id}/complete
+public record ExportTodos();           // → POST   /api/todos/export
+```
+
+**Common qualifiers are normalized automatically.** The generator handles a variety of CQRS naming conventions, extracting the entity name and producing clean routes:
+
+| Pattern | Example | Route |
+| ------- | ------- | ----- |
+| **`All` prefix** | `GetAllTodos` | `GET /api/todos` |
+| **`ById` suffix** | `GetTodoById` | `GET /api/todos/{id}` |
+| **`Details`/`Summary`** | `GetOrderDetails` | `GET /api/orders/{id}` |
+| **`Paged`/`Paginated`** | `GetProductsPaged` | `GET /api/products` |
+| **`With<Feature>`** | `GetTodoItemsWithPagination` | `GET /api/todo-items` |
+| **`By<Property>`** | `GetTodoByName` | `GET /api/todos/by-name` |
+| **`For<Entity>`** | `GetOrdersForCustomer` | `GET /api/orders/for-customer/{customerId}` |
+| **`From<Entity>`** | `GetOrdersFromUser` | `GET /api/orders/from-user/{userId}` |
+| **`Count` suffix** | `GetOrderCount` | `GET /api/orders/count` |
+| **Action verbs** | `ExportOrders` | `POST /api/orders/export` |
+
+**Stripped entirely** (query modifiers, not resource identity): `All`, `ById`, `Details`, `Detail`, `Summary`, `List`, `Paged`, `Paginated`, `With<Feature>`
+
+**Converted to route segments** (distinct sub-resources): `By<Property>`, `For<Entity>`, `From<Entity>`, `Count`
+
+**Action prefixes** (produce POST with action suffix): `Complete`, `Approve`, `Cancel`, `Submit`, `Export`, `Import`, `Download`, `Upload`, and [others](./handler-conventions.md)
+
+::: tip
+`By<Property>`, `For<Entity>`, and `From<Entity>` produce route segments under the entity, keeping all routes grouped. For example, `GetTodoByName(string Name)` generates `GET /api/todos/by-name?name=...` — no conflict with the list route `GET /api/todos`.
+:::
+
+**What to avoid.** Message names that don't reduce to a common entity will produce separate routes. If you see unexpected routes, check your message names:
+
+```csharp
+// ❌ These produce different route prefixes — probably not what you want
+public record GetTodo(string Id);          // → /api/todos/{id}
+public record GetActiveTodoCount();        // → /api/active-todo-counts  (different prefix!)
+
+// ✅ Better: use consistent entity root, differentiate with parameters
+public record GetTodo(string Id);          // → /api/todos/{id}
+public record GetTodos(bool? Active);      // → /api/todos?active=true
+```
+
+The generator emits diagnostic **FMED016** when handlers in the same class produce routes with different base paths, alerting you to naming inconsistencies. Use `[HandlerEndpointGroup("Todos")]` to force a shared prefix when message names don't naturally align.
+
 ### Route Parameters
 
 Properties named `Id` or ending with `Id` automatically become route parameters:

docs/guide/getting-started.md

@@ -105,7 +105,7 @@ This generates:
 
 <!-- -->
 
-HTTP methods, routes, and parameter binding are all inferred from message names and properties. See [Endpoints](./endpoints) for route customization, OpenAPI metadata, authorization, and more.
+HTTP methods, routes, and parameter binding are all inferred from message names and properties. Routes derive from the message name, are auto-pluralized, and common qualifiers like `All` and `ById` are normalized. See [Endpoints](./endpoints) for route customization, naming conventions, and more.
 
 ## Result Types
 

src/Foundatio.Mediator/EndpointGenerator.cs

@@ -247,6 +247,48 @@ private static void ValidateEndpoints(SourceProductionContext context, List<Hand
                     endpoint.Route));
             }
         }
+
+        // FMED016: Handlers in the same class produce routes with different base paths.
+        // Only check handlers without an explicit [HandlerEndpointGroup] category,
+        // since categorized handlers already have a shared group prefix.
+        var uncategorizedByClass = handlers
+            .Where(h => string.IsNullOrEmpty(h.Endpoint!.Value.CategoryRoutePrefix) && !h.Endpoint!.Value.HasExplicitRoute)
+            .GroupBy(h => h.Identifier);
+
+        foreach (var group in uncategorizedByClass)
+        {
+            var routePrefixes = group
+                .Select(h =>
+                {
+                    var route = h.Endpoint!.Value.Route.TrimStart('/');
+                    var slashIndex = route.IndexOf('/');
+                    return slashIndex > 0 ? route.Substring(0, slashIndex) : route;
+                })
+                .Where(p => !string.IsNullOrEmpty(p))
+                .Distinct(StringComparer.OrdinalIgnoreCase)
+                .ToList();
+
+            if (routePrefixes.Count > 1)
+            {
+                var handlerName = group.Key;
+                var prefixList = string.Join(", ", routePrefixes.Select(p => "/" + p));
+                context.ReportDiagnostic(Diagnostic.Create(
+                    new DiagnosticDescriptor(
+                        "FMED016",
+                        "Handler methods generate routes with different base paths",
+                        "Handler methods on '{0}' generate endpoints with different route prefixes ({1}). " +
+                        "This usually means message names don't share a common entity root. " +
+                        "Consider renaming messages to use a consistent noun (e.g., GetTodo instead of GetTodoById), " +
+                        "or use [HandlerEndpointGroup(\"{2}\")] to group them under a shared prefix.",
+                        "Foundatio.Mediator",
+                        DiagnosticSeverity.Warning,
+                        isEnabledByDefault: true),
+                    Location.None,
+                    handlerName,
+                    prefixList,
+                    handlerName.Replace("Handler", "").Replace("Consumer", "") + "s"));
+            }
+        }
     }
 
     /// <summary>

src/Foundatio.Mediator/HandlerAnalyzer.cs

@@ -805,7 +805,7 @@ private static string GenerateRoute(
         string? actionVerb = null)
     {
         var parts = new List<string>();
-        var entityName = RemoveVerbPrefix(messageTypeName);
+        var (entityName, lookupSuffix) = NormalizeEntityName(RemoveVerbPrefix(messageTypeName));
 
         // If we have a category with a route prefix, the route is relative to that prefix
         // Otherwise, we need to include the entity name in the route
@@ -819,6 +819,15 @@ private static string GenerateRoute(
             }
         }
 
+        // Add lookup suffix for By<Property>, For<Entity>, From<Entity>, Count patterns
+        // e.g., GetTodoByName in "Todos" → /todos/by-name
+        //        GetOrdersForCustomer → /orders/for-customer/{customerId}
+        // Placed before route params so the suffix reads naturally: /for-customer/{id}
+        if (lookupSuffix != null)
+        {
+            parts.Add(lookupSuffix);
+        }
+
         // Add route parameters
         foreach (var param in routeParams)
         {
@@ -874,7 +883,8 @@ private static string GenerateRoute(
         "Complete", "Approve", "Cancel", "Submit", "Process",
         "Execute", "Activate", "Deactivate", "Archive", "Restore",
         "Publish", "Unpublish", "Enable", "Disable", "Reset",
-        "Confirm", "Reject", "Assign", "Unassign", "Close", "Reopen"
+        "Confirm", "Reject", "Assign", "Unassign", "Close", "Reopen",
+        "Export", "Import", "Download", "Upload"
     ];
 
     /// <summary>
@@ -919,6 +929,86 @@ private static string RemoveVerbPrefix(string name)
         return name;
     }
 
+    /// <summary>
+    /// Common suffixes stripped from entity names to normalize routes.
+    /// For example, "TodoById" → "Todo", "OrderDetails" → "Order".
+    /// Ordered longest-first so "Details" is checked before "Detail".
+    /// </summary>
+    private static readonly string[] EntitySuffixes =
+    [
+        "Paginated", "Details", "Detail", "Summary", "ById", "Paged", "List"
+    ];
+
+    /// <summary>
+    /// Normalizes an entity name by removing common qualifiers that break route grouping.
+    /// Returns the normalized entity name and an optional route suffix for lookup patterns.
+    /// Examples:
+    ///   "AllTodos" → ("Todos", null)
+    ///   "TodoById" → ("Todo", null)                   — ById stripped, Id becomes route param
+    ///   "TodoByName" → ("Todo", "by-name")            — entity extracted, "by-name" becomes route segment
+    ///   "TodoDetails" → ("Todo", null)
+    ///   "TodoItemsWithPagination" → ("TodoItems", null) — With&lt;Feature&gt; stripped
+    ///   "OrderCount" → ("Order", "count")              — count becomes route segment
+    ///   "OrdersForCustomer" → ("Orders", "for-customer") — For&lt;Entity&gt; becomes route segment
+    ///   "OrdersFromUser" → ("Orders", "from-user")     — From&lt;Entity&gt; becomes route segment
+    /// </summary>
+    private static (string entityName, string? routeSuffix) NormalizeEntityName(string entityName)
+    {
+        if (string.IsNullOrEmpty(entityName))
+            return (entityName, null);
+
+        // Strip leading "All" prefix (e.g., AllTodos → Todos)
+        if (entityName.StartsWith("All", StringComparison.Ordinal) && entityName.Length > 3 && char.IsUpper(entityName[3]))
+        {
+            entityName = entityName.Substring(3);
+        }
+
+        // Strip known suffixes (e.g., TodoById → Todo, OrderDetails → Order, ProductsPaged → Products)
+        foreach (var suffix in EntitySuffixes)
+        {
+            if (entityName.EndsWith(suffix, StringComparison.Ordinal) && entityName.Length > suffix.Length)
+            {
+                entityName = entityName.Substring(0, entityName.Length - suffix.Length);
+                return (entityName, null);
+            }
+        }
+
+        // Strip With<Feature> suffix entirely (e.g., TodoItemsWithPagination → TodoItems)
+        // These are query modifiers (pagination, includes, filters) — not part of the resource identity.
+        var withIndex = entityName.IndexOf("With", StringComparison.Ordinal);
+        if (withIndex > 0 && withIndex + 4 < entityName.Length && char.IsUpper(entityName[withIndex + 4]))
+        {
+            entityName = entityName.Substring(0, withIndex);
+            return (entityName, null);
+        }
+
+        // Detect Count suffix (e.g., OrderCount → entity "Order", suffix "count")
+        // This is a well-established REST convention: GET /api/orders/count
+        if (entityName.EndsWith("Count", StringComparison.Ordinal) && entityName.Length > 5)
+        {
+            entityName = entityName.Substring(0, entityName.Length - 5);
+            return (entityName, "count");
+        }
+
+        // Detect For<Entity>/From<Entity>/By<Property> patterns — extract entity + route suffix.
+        // e.g., OrdersForCustomer → ("Orders", "for-customer")
+        //        OrdersFromUser → ("Orders", "from-user")
+        //        TodoByName → ("Todo", "by-name")
+        // "ById" is already handled above via EntitySuffixes.
+        foreach (var keyword in new[] { "For", "From", "By" })
+        {
+            var idx = entityName.IndexOf(keyword, StringComparison.Ordinal);
+            if (idx > 0 && idx + keyword.Length < entityName.Length && char.IsUpper(entityName[idx + keyword.Length]))
+            {
+                var suffix = entityName.Substring(idx);    // e.g., "ForCustomer"
+                entityName = entityName.Substring(0, idx); // e.g., "Orders"
+                return (entityName, suffix.ToKebabCase());  // e.g., "for-customer"
+            }
+        }
+
+        return (entityName, null);
+    }
+
     #region Event Detection
 
     /// <summary>