Merge pull request #58 from salihcantekin/feature/send-request-overload

Feature/send request overload

Author: salihcantekin

SpaceSolution.sln

@@ -27,6 +27,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{02EA681E-C
 		docs\Pipelines.md = docs\Pipelines.md
 		docs\PlannedImprovements.md = docs\PlannedImprovements.md
 		docs\ProjectDoc.en.md = docs\ProjectDoc.en.md
+		docs\Versioning.md = docs\Versioning.md
 	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "github", "github", "{13AA0D40-B562-4388-B5F9-C4612A784505}"

docs/DeveloperRecommendations.md

@@ -4,5 +4,13 @@
 - Integrate with `LoggerFactory` for advanced logging.
 - Follow interface and config standards when implementing custom modules.
 - Review the `Space.Modules.InMemoryCache` implementation for module development best practices.
+- Prefer the strongly-typed Send API: `Send<TRequest, TResponse>(TRequest, string? name = null)` with `TRequest : IRequest<TResponse>`.
+  - For dynamic scenarios, use `Send<TResponse>(IRequest<TResponse>)` or `Send<TResponse>(object)`.
+- Keep handlers/pipelines ValueTask-based where possible to minimize allocations.
+- Favor singleton lifetime to hit Space’s fast-path (no scope allocations) for hot paths.
+- Avoid reflection at runtime; rely on the source generator output for registrations.
+- Pipelines: keep them small; prefer ordered composition and share state via `PipelineContext.Items`.
+- Benchmarks: run `tests/Space.Benchmarks` to compare typed/IRequest/object Send paths.
+- Always run `dotnet format` before committing.
 
-For more suggestions, see [ProjectDoc.txt](ProjectDoc.txt).
+For more, see [ProjectDoc.txt](ProjectDoc.txt).

docs/Handlers.md

@@ -4,7 +4,7 @@ Handlers in Space are methods marked with the `[Handle]` attribute. They process
 
 ## Example
 ```csharp
-public record UserLoginRequest(string UserName);
+public record UserLoginRequest(string UserName) : IRequest<UserLoginResponse>;
 public record UserLoginResponse(bool Success);
 
 public partial class UserHandlers
@@ -13,32 +13,38 @@ public partial class UserHandlers
     public async ValueTask<UserLoginResponse> Login(HandlerContext<UserLoginRequest> ctx)
     {
         var userService = ctx.ServiceProvider.GetService<UserService>();
-        var loginModel = ctx.Request;
-        var userExists = await userService.Login(loginModel);
-        return new UserLoginResponse() { Success = userExists };
+        var userExists = await userService.Login(ctx.Request);
+        return new UserLoginResponse(userExists);
     }
 }
 ```
 
 ## Usage
+Preferred strongly-typed usage:
 ```csharp
 ISpace space = serviceProvider.GetRequiredService<ISpace>();
-var loginResponse = await space.Send<UserLoginResponse>(new UserLoginRequest { UserName = "sc" });
+var loginResponse = await space.Send<UserLoginRequest, UserLoginResponse>(new UserLoginRequest("sc"));
 ```
 
+Additional overloads:
+- IRequest overload: `await space.Send<UserLoginResponse>(IRequest<UserLoginResponse> request, string? name = null)`
+- Object overload: `await space.Send<UserLoginResponse>(object request, string? name = null)`
+
+> Rule: In `Send<TRequest, TResponse>`, `TRequest` must implement `IRequest<TResponse>`. This is enforced at compile time.
+
 Handlers can be named using the `Name` parameter and invoked by name:
 ```csharp
 [Handle(Name = "CustomHandler")]
 public ValueTask<ResponseType> CustomHandler(HandlerContext<RequestType> ctx) { ... }
 
-var response = await space.Send<ResponseType>(request, name: "CustomHandler");
+var response = await space.Send<RequestType, ResponseType>(new RequestType(...), name: "CustomHandler");
 ```
 
 ## Selecting default handler with IsDefault
 When multiple handlers exist for the same request/response pair, you can mark one as the default so that `Send` without a name uses it.
 
 ```csharp
-public record PriceQuery(int Id);
+public record PriceQuery(int Id) : IRequest<PriceResult>;
 public record PriceResult(string Tag);
 
 public class PricingHandlers

docs/KnownIssues.md

@@ -1,4 +1,10 @@
-# Known Issues
+# Known Issues / Breaking Changes
+
+- Breaking: `ISpace.Send<TRequest, TResponse>` now requires `TRequest : IRequest<TResponse>`.
+  - Migration:
+    - If your request already implements `IRequest<TRes>`, nothing to change.
+    - If not, either add `IRequest<TRes>` to your request type, or use `Send<TRes>(IRequest<TRes> request)` or `Send<TRes>(object request)` overloads.
+  - Benefit: compile-time safety and better discoverability.
 
 - Circular dependency in `ISpace` and `SpaceRegistry`: The first handler receives a null `ISpace(Lazy)` instance, which is set on subsequent requests.
 - ~~When using handler names, modules are applied to all handlers instead of only those with the attribute.~~ (Fixed)

docs/Pipelines.md

@@ -4,6 +4,9 @@ Pipelines in Space act as middleware for handler execution. They are methods mar
 
 ## Example
 ```csharp
+public record UserLoginRequest(string UserName) : IRequest<UserLoginResponse>;
+public record UserLoginResponse(bool Success);
+
 public partial class UserHandlers
 {
     // Runs first (lower Order executes earlier in the chain)
@@ -29,6 +32,7 @@ public partial class UserHandlers
 You can implement pipeline interfaces for type safety and build-time validation:
 ```csharp
 public class MyPipeline : IPipelineHandler<MyRequest, MyResponse>
+    where MyRequest : IRequest<MyResponse>
 {
     public ValueTask<MyResponse> HandlePipeline(PipelineContext<MyRequest> ctx, PipelineDelegate<MyRequest, MyResponse> next)
         => next(ctx);
@@ -42,6 +46,9 @@ public class MyPipeline : IPipelineHandler<MyRequest, MyResponse>
 - Items are cleared automatically between requests.
 
 ```csharp
+public record MyReq(string Text) : IRequest<MyRes>;
+public record MyRes(string Text);
+
 public class SampleHandlers
 {
     // Global pipelines (no handle name) for the same request/response
@@ -55,17 +62,17 @@ public class SampleHandlers
         var res = await next(ctx);
         // Read again later if needed
         var tid = (string)ctx.GetItem("trace-id");
-        return res; // or: return res with { Text = $"{res.Text}:P1:{tid}" };
+        return res with { Text = $"{res.Text}:P1={tid}" };
     }
 
     // Order = 2 executes after P1 (closer to the handler)
     [Pipeline(Order = 2)]
     public async ValueTask<MyRes> P2(PipelineContext<MyReq> ctx, PipelineDelegate<MyReq, MyRes> next)
     {
         // Access value set by P1
-        var tid = (string)ctx.GetItem("trace-id"); // not null
+        var tid = (string)ctx.GetItem("trace-id");
         var res = await next(ctx);
-        return res; // or: return res with { Text = $"{res.Text}:P2:{tid}" };
+        return res with { Text = $"{res.Text}:P2={tid}" };
     }
 }
 ```

src/Space.Abstraction/ISpace.cs

@@ -1,21 +1,27 @@
+using System;
+using System.ComponentModel;
 using System.Threading;
 using System.Threading.Tasks;
 
 namespace Space.Abstraction;
 
 public interface ISpace
 {
-    // Core typed overload
-    ValueTask<TResponse> Send<TRequest, TResponse>(TRequest request, string name = null, CancellationToken ct = default)
-         where TRequest : notnull
-         where TResponse : notnull;
+    ValueTask Publish<TRequest>(TRequest request, CancellationToken ct = default);
+    ValueTask Publish<TRequest>(TRequest request, NotificationDispatchType dispatchType, CancellationToken ct = default);
 
-    // Object path kept for dynamic scenarios
-    ValueTask<TResponse> Send<TResponse>(object request, string name = null, CancellationToken ct = default) where TResponse : notnull;
+    // Preferred strongly-typed send; enforces TRequest : IRequest<TResponse>
+    ValueTask<TResponse> Send<TRequest, TResponse>(TRequest request, string name = null, CancellationToken ct = default)
+        where TRequest : notnull, IRequest<TResponse>
+        where TResponse : notnull;
 
-    // Notifications: no name parameter
-    ValueTask Publish<TRequest>(TRequest request, CancellationToken ct = default) where TRequest : notnull;
+    // Convenience overload for IRequest<TResponse>
+    [EditorBrowsable(EditorBrowsableState.Always)]
+    ValueTask<TResponse> Send<TResponse>(IRequest<TResponse> request, string name = null, CancellationToken ct = default)
+        where TResponse : notnull;
 
-    // Per-call dispatcher override using enum
-    ValueTask Publish<TRequest>(TRequest request, NotificationDispatchType dispatchType, CancellationToken ct = default) where TRequest : notnull;
+    // Object-based send with explicit response type
+    [EditorBrowsable(EditorBrowsableState.Always)]
+    ValueTask<TResponse> Send<TResponse>(object request, string name = null, CancellationToken ct = default)
+        where TResponse : notnull;
 }

src/Space.Abstraction/ISpaceStrictExtensions.cs

@@ -0,0 +1,19 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using System.ComponentModel;
+using Space.Abstraction.Contracts;
+
+namespace Space.Abstraction;
+
+public static class ISpaceStrictExtensions
+{
+    /// <summary>
+    /// Preferred strongly-typed Send that enforces TRequest : IRequest&lt;TResponse&gt; at compile time.
+    /// </summary>
+    [EditorBrowsable(EditorBrowsableState.Always)]
+    public static ValueTask<TResponse> SendStrict<TRequest, TResponse>(this ISpace space, TRequest request, string name = null, CancellationToken ct = default)
+        where TRequest : notnull, IRequest<TResponse>
+        where TResponse : notnull
+        => space.Send<TRequest, TResponse>(request, name, ct);
+}

src/Space.Abstraction/Registry/HandlerRegistry.cs

@@ -47,6 +47,10 @@ public void RegisterHandler<TRequest, TResponse>(
         }
 
         handlerMap[key] = entryObj;
+
+        // Map (TRequest, TResponse) to the last registered entry (unnamed or named).
+        // This supports unnamed Send resolving to the last handler, and with OrderedHandlers
+        // default-marked handlers are registered last.
         handlerMapByType[(typeof(TRequest), typeof(TResponse))] = entryObj;
     }
 
@@ -118,6 +122,13 @@ internal bool TryGetHandlerEntryByRuntimeType(Type requestType, Type responseTyp
 
         if (string.IsNullOrEmpty(name))
         {
+            // Prefer explicit unnamed mapping if present
+            if (readOnlyHandlerMap != null && readOnlyHandlerMap.TryGetValue((requestType, string.Empty, responseType), out var unnamed))
+            {
+                entryObj = unnamed;
+                return true;
+            }
+
             if (readOnlyHandlerMapByType != null && readOnlyHandlerMapByType.TryGetValue((requestType, responseType), out var direct))
             {
                 entryObj = direct;
@@ -159,6 +170,20 @@ public ValueTask<TResponse> DispatchHandler<TRequest, TResponse>(IServiceProvide
             return typeEntry.Invoke(ctx);
         }
 
+        // Fallback: enumerate to find the last registered handler for (TRequest,TResponse)
+        SpaceRegistry.HandlerEntry<TRequest, TResponse> lastMatch = null;
+        foreach (var kv in readOnlyHandlerMap)
+        {
+            if (kv.Key.Item1 == typeof(TRequest) && kv.Key.Item3 == typeof(TResponse) && kv.Value is SpaceRegistry.HandlerEntry<TRequest, TResponse> e)
+            {
+                lastMatch = e; // preserve insertion order, this becomes the last registered
+            }
+        }
+        if (lastMatch != null)
+        {
+            return lastMatch.Invoke(ctx);
+        }
+
         throw new InvalidOperationException($"Handler not found for type {typeof(TRequest)} -> {typeof(TResponse)} and name '{name}'");
     }
 
@@ -202,6 +227,13 @@ private ValueTask<object> DispatchHandlerInternal(object request, string name, T
             // Prefer disambiguated lookup when responseType provided
             if (responseType != null)
             {
+                // Prefer explicit unnamed mapping if present
+                if (readOnlyHandlerMap != null && readOnlyHandlerMap.TryGetValue((type, string.Empty, responseType), out var explicitUnnamed) && explicitUnnamed is SpaceRegistry.IObjectHandlerEntry explicitUnnamedEntry)
+                {
+                    var ctx = HandlerContextStruct.Create(execProvider, request, space, ct);
+                    return explicitUnnamedEntry.InvokeObject(ctx);
+                }
+
                 if (readOnlyHandlerMapByType.TryGetValue((type, responseType), out var handlerObjRt) && handlerObjRt is SpaceRegistry.IObjectHandlerEntry objectHandlerRt)
                 {
                     var ctx = HandlerContextStruct.Create(execProvider, request, space, ct);

src/Space.DependencyInjection/Space.cs

@@ -36,7 +36,7 @@ private static class GenericDispatcherCache<TRes>
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public ValueTask<TResponse> Send<TRequest, TResponse>(TRequest request, string name = null, CancellationToken ct = default)
-        where TRequest : notnull
+        where TRequest : notnull, IRequest<TResponse>
         where TResponse : notnull
     {
         if (ct.IsCancellationRequested)
@@ -172,18 +172,67 @@ static async ValueTask<TResponse> AwaitLite(ValueTask<TResponse> task, IServiceS
         }
     }
 
-    // Constrained overloads to avoid boxing for IRequest<TResponse>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public ValueTask<TResponse> Send<TRequest, TResponse>(in TRequest request, CancellationToken ct = default)
-        where TRequest : struct, IRequest<TResponse>
+    public ValueTask<TResponse> Send<TResponse>(IRequest<TResponse> request, string name = null, CancellationToken ct = default)
         where TResponse : notnull
-            => Send<TRequest, TResponse>(request, null, ct);
+    {
+        if (ct.IsCancellationRequested)
+            return ValueTask.FromCanceled<TResponse>(ct);
 
-    [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public ValueTask<TResponse> Send<TRequest, TResponse>(TRequest request, CancellationToken ct = default)
-        where TRequest : class, IRequest<TResponse>
-        where TResponse : notnull
-            => Send<TRequest, TResponse>(request, null, ct);
+        if (IsFastPath(spaceRegistry.HandlerLifetime))
+        {
+            // Try runtime-type lookup without expression/MakeGenericMethod
+            if (spaceRegistry.TryGetHandlerEntryByRuntimeType(request.GetType(), typeof(TResponse), name, out var entryObj)
+                && entryObj is SpaceRegistry.IObjectHandlerEntry entry)
+            {
+                var hctx = HandlerContextStruct.Create(rootProvider, request, this, ct);
+                var vto = entry.InvokeObject(hctx);
+
+                if (vto.IsCompletedSuccessfully)
+                    return new ValueTask<TResponse>((TResponse)vto.Result!);
+                
+                return AwaitFast1(vto);
+
+                static async ValueTask<TResponse> AwaitFast1(ValueTask<object> vt)
+                    => (TResponse)await vt.ConfigureAwait(false);
+            }
+
+            // Fallback: object dispatch through registry (still no expression compile)
+            var vtoFallback = spaceRegistry.DispatchHandler(request, name, typeof(TResponse), rootProvider, ct);
+
+            if (vtoFallback.IsCompletedSuccessfully)
+                return new ValueTask<TResponse>((TResponse)vtoFallback.Result!);
+
+            return AwaitFast2(vtoFallback);
+
+            static async ValueTask<TResponse> AwaitFast2(ValueTask<object> vt)
+                => (TResponse)await vt.ConfigureAwait(false);
+        }
+
+        // Scoped path
+        using var scope = scopeFactory.CreateScope();
+        if (ct.IsCancellationRequested)
+            return ValueTask.FromCanceled<TResponse>(ct);
+
+        var vts = spaceRegistry.DispatchHandler(request, name, typeof(TResponse), scope.ServiceProvider, ct);
+
+        if (vts.IsCompletedSuccessfully)
+            return new ValueTask<TResponse>((TResponse)vts.Result!);
+
+        return AwaitScoped(vts, scope);
+
+        static async ValueTask<TResponse> AwaitScoped(ValueTask<object> vt, IServiceScope scope)
+        {
+            try 
+            {
+                return (TResponse)await vt.ConfigureAwait(false); 
+            }
+            finally 
+            {
+                scope.Dispose(); 
+            }
+        }
+    }
 
     #endregion
 
@@ -311,4 +360,5 @@ async ValueTask SlowPublishScoped(TRequest req, NotificationDispatchType dt, Can
         }
     }
 
+    
 }

src/Space.SourceGenerator/Diagnostics/DiagnosticGenerator.cs

@@ -21,6 +21,8 @@ internal class DiagnosticGenerator
 
         new MissingPipelineAttributeRule(),
         new PipelineAttributeRule()
+        // SEND001 disabled for now (kept in code for future use)
+        // new SendGenericResponseMismatchRule()
     ];
 
     internal static bool ReportDiagnostics(SourceProductionContext spc, Compilation compilation, HandlersCompileWrapperModel model)