Merge pull request #44 from PandaTechAM/development

SignalR

Author: HaikAsatryan

Readme.md

@@ -3,13 +3,14 @@
 ## Introduction
 
 **Pandatech.ResponseCrafter** is a comprehensive NuGet package for .NET 8+, specifically designed to enhance exception
-handling and logging in ASP.NET Core applications. This package simplifies managing standard and custom exceptions by
-crafting detailed error responses suitable for both development and production environments.
+handling and logging in ASP.NET Core applications, and now extended to support SignalR hubs. This package simplifies
+managing standard and custom exceptions by crafting detailed error responses suitable for both development and
+production environments.
 
 ## Features
 
-* **Custom Exception Handling:** Streamlines the process of managing both standard HTTP exceptions and custom
-  exceptions.
+* **Custom Exception Handling:** Streamlines the process of managing both standard HTTP exceptions and custom exceptions
+  for both REST APIs and SignalR.
 * **Detailed Error Responses:** Generates verbose error messages, including stack traces for in-depth debugging in
   development environments.
 * **Environment-Sensitive Logging:** Provides flexible logging and response behavior based on visibility
@@ -20,8 +21,8 @@ crafting detailed error responses suitable for both development and production e
       message. Logging remains the same as in `Private`.
 * **Frontend-Friendly Error Messages:** Supports converting error messages to your desired case convention, facilitating
   easier integration with frontend localization systems.
-* **Standardized Error Responses:** Provides a standardized error response format, making it easier for frontend
-  applications to parse and display error messages. The error response format is shown below:
+* **Standardized Error Responses for REST and SignalR:** Provides a standardized error response format, making it easier
+  for frontend applications to parse and display error messages. The error response format for REST APIs is shown below:
 
 ```json
 {
@@ -35,7 +36,22 @@ crafting detailed error responses suitable for both development and production e
   },
   "Message": "the_request_was_invalid_or_cannot_be_otherwise_served."
 }
-````
+```
+
+For SignalR, the standard error response format is:
+
+```json
+{
+  "InvocationId": "0HMVFE0A0HMVFE0A284AMHMV00HMVFE0A284AM0A284AM",
+  "Instance": "SendMessage",
+  "StatusCode": 400,
+  "Errors": {
+    "email": "email_address_is_not_in_a_valid_format",
+    "password": "password_must_be_at_least_8_characters_long"
+  },
+  "Message": "the_request_was_invalid_or_cannot_be_otherwise_served."
+}
+```
 
 ## Installation
 
@@ -89,25 +105,80 @@ public enum NamingConvention
 }
 ```
 
-### 2. Define Custom Exceptions:
+### 2. Setup Exception Handling for SignalR:
+
+For SignalR support, register the exception filter for your hubs (or per hub) as follows:
+
+```csharp
+builder.Services.AddSignalR(options => options.AddFilter<SignalRExceptionFilter>());
+```
+
+If you already have the existing configuration for REST APIs, like
+`builder.AddResponseCrafter(NamingConvention.ToSnakeCase);`, SignalR messages will automatically use the same error
+handling and response crafting.
+
+### 3. Implement Hub Methods with Standard Arguments:
+
+To allow proper response handling, the hub methods should use the `HubArgument<T>` structure, which provides a unique
+invocation ID for tracing errors and crafting detailed responses.
+
+```csharp
+public async Task SendMessage(HubArgument<Message> hubArgument)
+{
+    throw new BadRequestException("This is a test exception");
+    await Clients.All.ReceiveMessage(hubArgument.Argument);
+}
+```
+
+### 4. Define Custom Exceptions:
 
 Create custom exception classes that inherit from `ApiException` or use the predefined ones. Use `ErrorDetails` records
 for
 specific error messages related to API requests.
 
-### 3. Configure Middleware:
+### 5. Configure Middleware:
 
 * Implement the exception handling middleware in your application's pipeline.
 
 ```csharp
 app.UseResponseCrafter();
 ```
 
-### 4. Logging and Error Responses:
+## SignalR-Specific Error Handling and Structure
+
+When using the package with SignalR, the following structures are used for standardizing request and response handling:
+**HubErrorResponse**
+This class is used to format error responses sent back to the client:
+
+```csharp
+public class HubErrorResponse
+{
+   public required string InvocationId { get; set; }
+   public required string Instance { get; set; }
+   public int StatusCode { get; set; }
+   public string Message { get; set; } = string.Empty;
+   public Dictionary<string, string>? Errors { get; set; }
+}
+```
+
+**HubArgument<T>**
+This class wraps around the standard arguments passed to SignalR methods, adding an `InvocationId` to enable unique
+error tracing.
+
+```csharp
+public class HubArgument<T>
+{
+   public required string InvocationId { get; set; }
+   public required T Argument { get; set; }
+}
+```
+
+## Logging and Error Responses:
 
-The package automatically logs warnings or errors and provides crafted responses based on the exception type.
+The package automatically logs warnings or errors and provides crafted responses based on the exception type, whether
+for REST APIs or SignalR hubs.
 
-## Custom HTTP Exception Already Created
+## Predefined HTTP Exceptions
 
 * `BadRequestException`
 * `UnauthorizedException`
@@ -161,8 +232,10 @@ UnauthorizedException.ThrowIf(userUnauthorized, "User is unauthorized");
 InternalServerErrorException.ThrowIf(userUnauthorized, "User is unauthorized");
 ```
 
-These examples show how to use the `ThrowIfNullOrNegative`, `ThrowIfNullOrWhiteSpace`, `ThrowIfNullOrEmpty` and `ThrowIfNull` helper methods
-from `BadRequestException`, `InternalServerErrorException` and `NotFoundException`. Adjust the object names and values according to your specific
+These examples show how to use the `ThrowIfNullOrNegative`, `ThrowIfNullOrWhiteSpace`, `ThrowIfNullOrEmpty` and
+`ThrowIfNull` helper methods
+from `BadRequestException`, `InternalServerErrorException` and `NotFoundException`. Adjust the object names and values
+according to your specific
 application needs.
 
 ## Recommendations

…ResponseCrafter/PandaExceptionHandler.cs …c/ResponseCrafter/ApiExceptionHandler.cssrc/ResponseCrafter/PandaExceptionHandler.cs renamed to src/ResponseCrafter/ApiExceptionHandler.cs src/ResponseCrafter/PandaExceptionHandler.cs renamed to src/ResponseCrafter/ApiExceptionHandler.cs

@@ -15,17 +15,17 @@
 
 namespace ResponseCrafter;
 
-public class PandaExceptionHandler : IExceptionHandler
+public class ApiExceptionHandler : IExceptionHandler
 {
-    private readonly ILogger<PandaExceptionHandler> _logger;
+    private readonly ILogger<ApiExceptionHandler> _logger;
     private readonly NamingConvention _convention;
     private readonly string _visibility;
     private const string DefaultMessage = "something_went_wrong_please_try_again_later_and_or_contact_it_support";
 
     private const string ConcurrencyMessage =
         "a_concurrency_conflict_occurred._please_reload_the_resource_and_try_you_update_again";
 
-    public PandaExceptionHandler(ILogger<PandaExceptionHandler> logger, IConfiguration configuration,
+    public ApiExceptionHandler(ILogger<ApiExceptionHandler> logger, IConfiguration configuration,
         NamingConventionOptions convention)
     {
         _logger = logger;
@@ -169,7 +169,7 @@ private async Task HandleApiExceptionAsync(HttpContext httpContext, ApiException
     private async Task HandleGeneralExceptionAsync(HttpContext httpContext, Exception exception,
         CancellationToken cancellationToken)
     {
-        var verboseMessage = CreateVerboseExceptionMessage(exception);
+        var verboseMessage = exception.CreateVerboseExceptionMessage();
 
         var response = new ErrorResponse
         {

src/ResponseCrafter/Dtos/HubErrorResponse.cs

@@ -0,0 +1,13 @@
+namespace ResponseCrafter.Dtos;
+
+/// <summary>
+/// Represents a standard structure for error responses sent back to SignalR clients.
+/// </summary>
+public class HubErrorResponse
+{
+   public required string InvocationId { get; set; }
+   public required string Instance { get; set; }
+   public int StatusCode { get; set; }
+   public string Message { get; set; } = string.Empty;
+   public Dictionary<string, string>? Errors { get; set; }
+}

src/ResponseCrafter/Extensions/WebApplicationExtensions.cs

@@ -11,7 +11,7 @@ public static WebApplicationBuilder AddResponseCrafter(this WebApplicationBuilde
         NamingConvention namingConvention = NamingConvention.Default)
     {
         builder.Services.AddSingleton(new NamingConventionOptions { NamingConvention = namingConvention });
-        builder.Services.AddExceptionHandler<PandaExceptionHandler>();
+        builder.Services.AddExceptionHandler<ApiExceptionHandler>();
 
 
         return builder;

src/ResponseCrafter/Helpers/ExceptionMessageBuilder.cs

@@ -5,7 +5,7 @@ namespace ResponseCrafter.Helpers;
 
 public static class ExceptionMessageBuilder
 {
-    public static string CreateVerboseExceptionMessage(Exception exception)
+    public static string CreateVerboseExceptionMessage(this Exception exception)
     {
         var stringBuilder = new StringBuilder();
 

src/ResponseCrafter/Helpers/HubArgument.cs

@@ -0,0 +1,11 @@
+namespace ResponseCrafter.Helpers;
+
+/// <summary>
+/// Generic class representing the hub method argument structure.
+/// </summary>
+/// <typeparam name="T">Type of the main argument value.</typeparam>
+public class HubArgument<T>
+{
+   public required string InvocationId { get; set; }
+   public required T Argument { get; set; }
+}

src/ResponseCrafter/ResponseCrafter.csproj

@@ -8,13 +8,13 @@
         <Copyright>MIT</Copyright>
         <PackageIcon>pandatech.png</PackageIcon>
         <PackageReadmeFile>Readme.md</PackageReadmeFile>
-        <Version>3.0.1</Version>
+        <Version>4.0.0</Version>
         <PackageId>Pandatech.ResponseCrafter</PackageId>
         <PackageTags>Pandatech, library, exception handler, exception, middleware, Api response</PackageTags>
         <Title>ResponseCrafter</Title>
         <Description>Handling exceptions, custom Dtos.</Description>
         <RepositoryUrl>https://github.com/PandaTechAM/be-lib-response-crafter</RepositoryUrl>
-        <PackageReleaseNotes>Added extensions, updated nugets</PackageReleaseNotes>
+        <PackageReleaseNotes>SignalR ResponseCrafting Support Has Been Added</PackageReleaseNotes>
     </PropertyGroup>
 
     <ItemGroup>
@@ -25,8 +25,9 @@
     <ItemGroup>
         <PackageReference Include="Humanizer" Version="2.14.1" />
         <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="8.0.8" />
+        <PackageReference Include="Microsoft.AspNetCore.SignalR.Client" Version="8.0.8" />
         <PackageReference Include="PandaTech.FluentImporter" Version="2.0.13" />
-        <PackageReference Include="Pandatech.GridifyExtensions" Version="1.5.4" />
+        <PackageReference Include="Pandatech.GridifyExtensions" Version="1.6.2" />
         <PackageReference Include="PandaTech.ServiceResponse" Version="1.2.12" />
     </ItemGroup>