Add mediator pattern interfaces and utility classes

Introduced a set of interfaces and classes to implement the mediator pattern, enabling asynchronous messaging and request/response handling.

- Added `INotificationHandler<TNotification>` for handling notifications asynchronously.
- Added `INotificationPublisher` for publishing notifications to handler executors.
- Added `IRequestExceptionAction<TRequest, TException>` for custom exception handling actions.
- Added `IRequestExceptionHandler<TRequest, TResponse, TException>` for managing exceptions in request pipelines.
- Added `IRequestHandler<TRequest, TResponse>` and its overload for handling requests and responses.
- Added `IRequestPreProcessor<TRequest>` and `IRequestPostProcessor<TRequest, TResponse>` for pre- and post-processing logic.
- Introduced `NotificationHandlerExecutor` to encapsulate notification handlers and their delegates.
- Added `RequestExceptionHandlerState<TResponse>` to manage exception handling state and responses.

These changes provide a flexible and extensible foundation for building asynchronous, event-driven systems.

Author: bvdcode

Sources/EasyExtensions.Mediator/Contracts/INotificationHandler.cs

@@ -0,0 +1,20 @@
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace EasyExtensions.Mediator.Contracts
+{
+    /// <summary>
+    /// Defines a handler for processing notification messages of a specified type asynchronously.
+    /// </summary>
+    /// <typeparam name="TNotification">The type of notification to handle. Must implement the <see cref="INotification"/> interface.</typeparam>
+    public interface INotificationHandler<in TNotification> where TNotification : INotification
+    {
+        /// <summary>
+        /// Handles the specified notification asynchronously.
+        /// </summary>
+        /// <param name="notification">The notification to process. Cannot be null.</param>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
+        /// <returns>A task that represents the asynchronous operation.</returns>
+        Task Handle(TNotification notification, CancellationToken cancellationToken = default);
+    }
+}

Sources/EasyExtensions.Mediator/Contracts/INotificationPublisher.cs

@@ -0,0 +1,24 @@
+using System.Threading;
+using System.Threading.Tasks;
+using System.Collections.Generic;
+
+namespace EasyExtensions.Mediator.Contracts
+{
+    /// <summary>
+    /// Defines a contract for asynchronously publishing notifications to one or more notification handler executors.
+    /// </summary>
+    /// <remarks>Implementations of this interface are responsible for delivering notifications to the
+    /// provided handler executors. The publish operation may be subject to cancellation via the supplied cancellation
+    /// token. Thread safety and delivery guarantees depend on the specific implementation.</remarks>
+    public interface INotificationPublisher
+    {
+        /// <summary>
+        /// Publishes a notification to the specified collection of notification handler executors asynchronously.
+        /// </summary>
+        /// <param name="handlerExecutors">A collection of executors responsible for handling the notification. Cannot be null.</param>
+        /// <param name="notification">The notification instance to be published. Cannot be null.</param>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the publish operation.</param>
+        /// <returns>A task that represents the asynchronous publish operation.</returns>
+        Task Publish(IEnumerable<NotificationHandlerExecutor> handlerExecutors, INotification notification, CancellationToken cancellationToken = default);
+    }
+}

Sources/EasyExtensions.Mediator/Contracts/IRequestExceptionAction.cs

@@ -0,0 +1,26 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace EasyExtensions.Mediator.Contracts
+{
+    /// <summary>
+    /// Defines an action to be performed when an exception occurs during the processing of a request.
+    /// </summary>
+    /// <remarks>Implement this interface to provide custom exception handling logic for specific request and
+    /// exception types. The action is typically invoked by a request processing pipeline or middleware when an
+    /// exception of the specified type occurs.</remarks>
+    /// <typeparam name="TRequest">The type of the request associated with the exception. This type must not be null.</typeparam>
+    /// <typeparam name="TException">The type of exception that triggered the action. This type must derive from Exception.</typeparam>
+    public interface IRequestExceptionAction<in TRequest, in TException> where TRequest : notnull where TException : Exception
+    {
+        /// <summary>
+        /// Executes the operation using the specified request and exception context.
+        /// </summary>
+        /// <param name="request">The request object that provides the necessary data for the operation.</param>
+        /// <param name="exception">The exception instance that triggered the execution. Cannot be null.</param>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
+        /// <returns>A task that represents the asynchronous execution operation.</returns>
+        Task Execute(TRequest request, TException exception, CancellationToken cancellationToken = default);
+    }
+}

Sources/EasyExtensions.Mediator/Contracts/IRequestExceptionHandler.cs

@@ -0,0 +1,32 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace EasyExtensions.Mediator.Contracts
+{
+    /// <summary>
+    /// Defines a contract for handling exceptions that occur during the processing of a request and determining how the
+    /// request pipeline should proceed.
+    /// </summary>
+    /// <remarks>Implementations of this interface can be used to customize exception handling logic within a
+    /// request processing pipeline. The handler can inspect the exception and request, and decide whether to mark the
+    /// exception as handled and optionally provide a response. This enables scenarios such as logging, transforming
+    /// exceptions into responses, or allowing the pipeline to continue after certain exceptions.</remarks>
+    /// <typeparam name="TRequest">The type of the request message being processed. Must not be null.</typeparam>
+    /// <typeparam name="TResponse">The type of the response message that may be produced by the handler.</typeparam>
+    /// <typeparam name="TException">The type of exception to handle. Must derive from Exception.</typeparam>
+    public interface IRequestExceptionHandler<in TRequest, TResponse, in TException> where TRequest : notnull where TException : Exception where TResponse : class
+    {
+        /// <summary>
+        /// Handles an exception that occurred during the processing of a request and determines how the request
+        /// pipeline should proceed.
+        /// </summary>
+        /// <param name="request">The request message that was being processed when the exception was thrown.</param>
+        /// <param name="exception">The exception instance that was caught during request processing.</param>
+        /// <param name="state">The handler state object used to indicate whether the exception has been handled and to provide a response
+        /// if appropriate.</param>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the exception handling operation.</param>
+        /// <returns>A task that represents the asynchronous exception handling operation.</returns>
+        Task Handle(TRequest request, TException exception, RequestExceptionHandlerState<TResponse> state, CancellationToken cancellationToken = default);
+    }
+}

Sources/EasyExtensions.Mediator/Contracts/IRequestHandler.cs

@@ -0,0 +1,42 @@
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace EasyExtensions.Mediator.Contracts
+{
+    /// <summary>
+    /// Defines a handler for processing a request and returning a response asynchronously.
+    /// </summary>
+    /// <remarks>Implement this interface to define custom logic for handling specific request types in a
+    /// request/response pattern. The handler is typically invoked by a mediator or dispatcher component.
+    /// Implementations should be thread-safe if they are shared across multiple requests.</remarks>
+    /// <typeparam name="TRequest">The type of the request to handle. Must implement <see cref="IRequest{TResponse}"/>.</typeparam>
+    /// <typeparam name="TResponse">The type of the response returned by the handler.</typeparam>
+    public interface IRequestHandler<in TRequest, TResponse> where TRequest : IRequest<TResponse>
+    {
+        /// <summary>
+        /// Handles the specified request and returns a response asynchronously.
+        /// </summary>
+        /// <param name="request">The request message to process. Cannot be null.</param>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
+        /// <returns>A task that represents the asynchronous operation. The task result contains the response to the request.</returns>
+        Task<TResponse> Handle(TRequest request, CancellationToken cancellationToken = default);
+    }
+
+    /// <summary>
+    /// Defines a handler for processing a request of a specified type asynchronously.
+    /// </summary>
+    /// <remarks>Implement this interface to define custom logic for handling requests of type <typeparamref
+    /// name="TRequest"/>. The handler is typically invoked by a mediator or dispatcher component. Implementations
+    /// should ensure thread safety if the handler will be used concurrently.</remarks>
+    /// <typeparam name="TRequest">The type of request to handle. Must implement the <see cref="IRequest"/> interface.</typeparam>
+    public interface IRequestHandler<in TRequest> where TRequest : IRequest
+    {
+        /// <summary>
+        /// Handles the specified request asynchronously.
+        /// </summary>
+        /// <param name="request">The request message to be processed. Cannot be null.</param>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
+        /// <returns>A task that represents the asynchronous handling operation.</returns>
+        Task Handle(TRequest request, CancellationToken cancellationToken = default);
+    }
+}

Sources/EasyExtensions.Mediator/Contracts/IRequestPostProcessor.cs

@@ -0,0 +1,29 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace EasyExtensions.Mediator.Contracts
+{
+    /// <summary>
+    /// Defines a post-processor for requests, allowing additional actions to be performed after a request handler has
+    /// processed a request and produced a response.
+    /// </summary>
+    /// <remarks>Implement this interface to execute logic that should run after the main request handler
+    /// completes, such as logging, auditing, or modifying the response. Post-processors are invoked after the request
+    /// handler and can observe both the request and its response.</remarks>
+    /// <typeparam name="TRequest">The type of the request message. Must not be null.</typeparam>
+    /// <typeparam name="TResponse">The type of the response message produced by the request handler.</typeparam>
+    public interface IRequestPostProcessor<in TRequest, in TResponse> where TRequest : notnull
+    {
+        /// <summary>
+        /// Processes the specified request and response asynchronously.
+        /// </summary>
+        /// <param name="request">The request object containing the data to be processed. Cannot be null.</param>
+        /// <param name="response">The response object to be populated or modified during processing. Cannot be null.</param>
+        /// <param name="cancellationToken">A token that can be used to request cancellation of the operation.</param>
+        /// <returns>A task that represents the asynchronous processing operation.</returns>
+        Task Process(TRequest request, TResponse response, CancellationToken cancellationToken = default);
+    }
+}

Sources/EasyExtensions.Mediator/Contracts/IRequestPreProcessor.cs

@@ -0,0 +1,23 @@
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace EasyExtensions.Mediator.Contracts
+{
+    /// <summary>
+    /// Defines a contract for processing a request asynchronously before it is handled.
+    /// </summary>
+    /// <remarks>Implement this interface to perform pre-processing logic on requests, such as validation,
+    /// logging, or modification, before the main request handler executes. Pre-processors can be used to enforce
+    /// cross-cutting concerns or prepare requests for further handling.</remarks>
+    /// <typeparam name="TRequest">The type of the request to be processed. Must not be null.</typeparam>
+    public interface IRequestPreProcessor<in TRequest> where TRequest : notnull
+    {
+        /// <summary>
+        /// Processes the specified request asynchronously.
+        /// </summary>
+        /// <param name="request">The request to be processed. Cannot be null.</param>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
+        /// <returns>A task that represents the asynchronous processing operation.</returns>
+        Task Process(TRequest request, CancellationToken cancellationToken = default);
+    }
+}

Sources/EasyExtensions.Mediator/Contracts/NotificationHandlerExecutor.cs

@@ -0,0 +1,28 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace EasyExtensions.Mediator.Contracts
+{
+    /// <summary>
+    /// Provides a container for an asynchronous notification handler and its associated delegate.
+    /// </summary>
+    /// <remarks>Use this class to encapsulate a notification handler instance along with a delegate that
+    /// processes notifications asynchronously. This enables flexible assignment and execution of notification handling
+    /// logic, typically within a messaging or event-driven system.</remarks>
+    public class NotificationHandlerExecutor
+    {
+        /// <summary>
+        /// Gets the instance of the handler associated with this object.
+        /// </summary>
+        public object HandlerInstance { get; } = null!;
+
+        /// <summary>
+        /// Gets the delegate that handles notification processing asynchronously.
+        /// </summary>
+        /// <remarks>The delegate accepts an <see cref="INotification"/> instance and a <see
+        /// cref="CancellationToken"/>, and returns a <see cref="Task"/> representing the asynchronous operation. Assign
+        /// this property to specify custom logic for handling notifications.</remarks>
+        public Func<INotification, CancellationToken, Task>? HandlerCallback { get; }
+    }
+}

Sources/EasyExtensions.Mediator/Contracts/RequestExceptionHandlerState.cs

@@ -0,0 +1,30 @@
+namespace EasyExtensions.Mediator.Contracts
+{
+    /// <summary>
+    /// Represents the state of an exception handler for a request, including whether the exception has been handled and
+    /// an optional response value.
+    /// </summary>
+    /// <typeparam name="TResponse">The type of the response associated with the handled request. Must be a reference type.</typeparam>
+    public class RequestExceptionHandlerState<TResponse>
+    {
+        /// <summary>
+        /// Gets a value indicating whether the event has been marked as handled.
+        /// </summary>
+        public bool Handled { get; private set; }
+
+        /// <summary>
+        /// Gets the response returned by the operation, if available.
+        /// </summary>
+        public TResponse Response { get; private set; } = default!;
+
+        /// <summary>
+        /// Marks the request as handled and sets the response to the specified value.
+        /// </summary>
+        /// <param name="response">The response value to associate with the handled request.</param>
+        public void SetHandled(TResponse response)
+        {
+            Handled = true;
+            Response = response;
+        }
+    }
+}