Merge pull request 'payments' (#69) from payments into master

Reviewed-on: #69

.gitignore

@@ -360,4 +360,7 @@ MigrationBackup/
 .ionide/
 
 # Fody - auto-generated XML schema
-FodyWeavers.xsd
+FodyWeavers.xsd
+/LiteCharms.Features.Tests/http/http-client.env.json
+/LiteCharms.Features.Tests/http/midrandshop-api/http-client.env.json
+/LiteCharms.Features.Tests/http/authentik/http-client.env.json

LiteCharms.Features.MidrandBooks.Tests/PayfastServiceFeatureTests.cs

@@ -37,7 +37,7 @@ public sealed class PayfastServiceFeatureTests(Fixture fixture) : IClassFixture<
 
         string liveTargetIp = addresses.First().ToString();
 
-        var result = await payfastService.ValidateReferrerIpAsync(liveTargetIp, fixture.CancellationToken);
+        var result = await payfastService.ValidateReferrerIpAsync(liveTargetIp, true, fixture.CancellationToken);
 
         Assert.True(result.IsSuccess);
         Assert.True(result.Value);
@@ -48,7 +48,7 @@ public sealed class PayfastServiceFeatureTests(Fixture fixture) : IClassFixture<
     {
         string rogueIp = "8.8.8.8";
 
-        var result = await payfastService.ValidateReferrerIpAsync(rogueIp, fixture.CancellationToken);
+        var result = await payfastService.ValidateReferrerIpAsync(rogueIp, true, fixture.CancellationToken);
 
         Assert.True(result.IsSuccess);
         Assert.False(result.Value);
@@ -87,7 +87,7 @@ public sealed class PayfastServiceFeatureTests(Fixture fixture) : IClassFixture<
 
         var result = await payfastService.ValidateServerConfirmationAsync(arbitraryParameters, isSandbox: true, fixture.CancellationToken);
 
-        Assert.True(result.IsSuccess); 
+        Assert.True(result.IsSuccess);
         Assert.False(result.Value);   // Handshake data rejected as fraudulent/unrecognized
     }
 

LiteCharms.Features.MidrandBooks/Payments/Events/Handlers/PayfastPaymentConfirmationReceivedEventHandler.cs

@@ -1,17 +1,21 @@
 using LiteCharms.Features.Hasher;
 using LiteCharms.Features.Hasher.Configuration;
+using LiteCharms.Features.Mediator;
 using LiteCharms.Features.MidrandBooks.Orders;
 using LiteCharms.Features.MidrandBooks.Payments.Models;
 
 namespace LiteCharms.Features.MidrandBooks.Payments.Events.Handlers;
 
-public sealed class PayfastPaymentConfirmationReceivedEventHandler(IServiceProvider services, IOptions<HasherSettings> hasherOptions, ILogger<PayfastPaymentConfirmationReceivedEvent> logger) : 
+public sealed class PayfastPaymentConfirmationReceivedEventHandler(IServiceProvider services, IOptions<HasherSettings> hasherOptions, ILogger<PayfastPaymentConfirmationReceivedEvent> logger) :
     INotificationHandler<PayfastPaymentConfirmationReceivedEvent>
 {
     private readonly HasherSettings hasherSettings = hasherOptions.Value;
 
     public async ValueTask Handle(PayfastPaymentConfirmationReceivedEvent notification, CancellationToken cancellationToken)
     {
+        using var activity = MediatorTelemetry.Source.StartActivity($"Quartz: {typeof(PayfastPaymentConfirmationReceivedEvent).Name}");
+        activity?.SetTag("event.correlation_id", notification.CorrelationId);
+
         await using var scope = services.CreateAsyncScope();
         var hashService = scope.ServiceProvider.GetRequiredService<HashService>();
         var orderService = scope.ServiceProvider.GetRequiredService<OrderService>();
@@ -23,7 +27,7 @@ public sealed class PayfastPaymentConfirmationReceivedEventHandler(IServiceProvi
         var dict = payload.ToParamDictionary();
         var localSignature = PayfastService.GenerateSignature(dict, hasherSettings.PayfastPassphrase);
 
-        if(localSignature.IsFailed)
+        if (localSignature.IsFailed)
             throw new Exception("Failed to generate local signature for incoming webhook payload.");
 
         if (!string.Equals(localSignature.Value, payload.Signature, StringComparison.OrdinalIgnoreCase))
@@ -61,9 +65,9 @@ public sealed class PayfastPaymentConfirmationReceivedEventHandler(IServiceProvi
 
         if (notification.PerformBackgroundChecks)
         {
-            var isHostValid = await payfastService.ValidateReferrerIpAsync(notification.RemoteIpAddress!, cancellationToken);
+            var isHostValid = await payfastService.ValidateReferrerIpAsync(notification.RemoteIpAddress!, notification.AllowLoopback, cancellationToken);
 
-            if (isHostValid.IsFailed) 
+            if (isHostValid.IsFailed)
                 throw new Exception("Security validation exception: Webhook packet source address failed cluster validation checks.");
 
             if (!isHostValid.Value)
@@ -71,7 +75,7 @@ public sealed class PayfastPaymentConfirmationReceivedEventHandler(IServiceProvi
 
             var isAmountValid = payfastService.ValidatePaymentAmount(orderResult.Value.Total, payload.AmountGross);
 
-            if (!isAmountValid.Value) 
+            if (!isAmountValid.Value)
                 throw new Exception("Security validation exception: Transaction cost variance bounds breached.");
 
             var paramList = new List<string>();
@@ -91,8 +95,8 @@ public sealed class PayfastPaymentConfirmationReceivedEventHandler(IServiceProvi
 
             var serverConfirmation = await payfastService.ValidateServerConfirmationAsync(rawParamString, isSandbox: true, cancellationToken);
 
-            if (serverConfirmation.IsFailed) 
-                throw new Exception("Security validation exception: Payfast central handshake server rejected payload legitimacy."); 
+            if (serverConfirmation.IsFailed)
+                throw new Exception("Security validation exception: Payfast central handshake server rejected payload legitimacy.");
         }
 
         await payfastService.WriteLedgerEntryAsync(new CreateGatewayLedgerEntry
@@ -105,7 +109,7 @@ public sealed class PayfastPaymentConfirmationReceivedEventHandler(IServiceProvi
             AmountFee = fee,
             AmountGross = gross,
             AmountNet = net,
-            PaymentStatus = status,            
+            PaymentStatus = status,
         }, cancellationToken);
 
         if (status.Equals("COMPLETE", StringComparison.OrdinalIgnoreCase))
@@ -154,5 +158,7 @@ public sealed class PayfastPaymentConfirmationReceivedEventHandler(IServiceProvi
 
             logger.LogInformation("Webhook validation pipeline passed checks successfully, logged entry to ledger with status: {Status}", status);
         }
+        activity?.SetStatus(ActivityStatusCode.Ok);
+
     }
 }

LiteCharms.Features.MidrandBooks/Payments/Events/PayfastPaymentConfirmationReceivedEvent.cs

@@ -13,15 +13,18 @@ public sealed class PayfastPaymentConfirmationReceivedEvent : EventBase, IEvent
 
     public bool PerformBackgroundChecks { get; set; }
 
+    public bool AllowLoopback { get; set; }
+
     public PayfastPaymentConfirmationReceivedEvent() { }
 
-    private PayfastPaymentConfirmationReceivedEvent(PayfastWebhookPayload? payload, string paymentId, bool performBackgroundChecks = true)
+    private PayfastPaymentConfirmationReceivedEvent(PayfastWebhookPayload? payload, string paymentId, bool performBackgroundChecks = true, bool allowLoopback = false)
     {
         Payload = payload;
         CorrelationId = paymentId;
         PerformBackgroundChecks = performBackgroundChecks;
+        AllowLoopback = allowLoopback;
     }
 
-    public static PayfastPaymentConfirmationReceivedEvent Create(PayfastWebhookPayload? payload, string paymentId, bool performBackgroundChecks = true) =>
-        new(payload, paymentId, performBackgroundChecks);
+    public static PayfastPaymentConfirmationReceivedEvent Create(PayfastWebhookPayload? payload, string paymentId, bool performBackgroundChecks = true, bool allowLoopback = false) =>
+        new(payload, paymentId, performBackgroundChecks, allowLoopback);
 }

LiteCharms.Features.MidrandBooks/Payments/PayfastService.cs

@@ -49,7 +49,7 @@ public sealed partial class PayfastService(IDbContextFactory<MidrandBooksDbConte
         }
     }
 
-    public async ValueTask<Result<bool>> ValidateReferrerIpAsync(string remoteIpAddress, CancellationToken cancellationToken = default)
+    public async ValueTask<Result<bool>> ValidateReferrerIpAsync(string remoteIpAddress, bool allowLoopback = false, CancellationToken cancellationToken = default)
     {
         if (string.IsNullOrWhiteSpace(remoteIpAddress)) 
             return Result.Fail<bool>("Remote IP address is null or whitespace.");
@@ -74,6 +74,12 @@ public sealed partial class PayfastService(IDbContextFactory<MidrandBooksDbConte
 
             if (IPAddress.TryParse(remoteIpAddress, out var incomingIp))
             {
+                if (allowLoopback && IPAddress.IsLoopback(incomingIp))
+                {
+                    logger.LogInformation("Local development loopback IP '{RemoteIp}' allowed bypassing DNS verification.", remoteIpAddress);
+                    return Result.Ok(true);
+                }
+
                 bool isValid = validIps.Contains(incomingIp);
 
                 if (!isValid)

LiteCharms.Features.Tests/http/authentik/app.http

@@ -0,0 +1,6 @@
+## Authentik Token Request
+POST {{authority}}
+Content-Type: application/x-www-form-urlencoded
+Accept-Encoding: identity
+
+grant_type={{grantType}}&client_id={{clientId}}&client_secret={{clientSecret}}&username={{username}}&password={{password}}&scope={{scope}}

LiteCharms.Features.Tests/http/midrandshop-api/app.http

@@ -0,0 +1,8 @@
+## Payfast Payment Confirmation
+# This endpoint is used by Payfast to confirm the payment status of a transaction. 
+# It receives a POST request with the payment details and updates the order status accordingly.
+
+POST {{baseUrl}}/v1/payments/payfast/confirm
+Content-Type: application/x-www-form-urlencoded
+
+amount={{amount}}&item_name={{item_name}}&m_payment_id={{paymentId}}&signature={{signature}}

LiteCharms.Features/Abstractions/IEndpoint.cs

@@ -0,0 +1,6 @@
+namespace LiteCharms.Features.Abstractions;
+
+public interface IEndpoint
+{
+    void Map(IEndpointRouteBuilder builder);
+}

LiteCharms.Features/Abstractions/IJobOrchestrator.cs

@@ -0,0 +1,12 @@
+namespace LiteCharms.Features.Abstractions;
+
+public interface IJobOrchestrator
+{
+    ValueTask SendAsync<TNotification>(TNotification notification, CancellationToken cancellationToken = default)
+        where TNotification : IEvent;
+
+    ValueTask ScheduleAsync<TNotification>(TNotification notification, string cronExpression, CancellationToken cancellationToken = default) 
+        where TNotification : IEvent;
+
+    ValueTask<bool> InterruptAsync(string eventName, string? correlationId = null, CancellationToken cancellationToken = default);
+}

LiteCharms.Features/Api/ApiVersionTargetAttribute.cs

@@ -0,0 +1,7 @@
+namespace LiteCharms.Features.Api;
+
+[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
+public sealed class ApiVersionTargetAttribute(int majorVersion) : Attribute
+{
+    public int MajorVersion { get; } = majorVersion;
+}

LiteCharms.Features/Api/Configuration/AuthentikSettings.cs

@@ -0,0 +1,18 @@
+namespace LiteCharms.Features.Api.Configuration;
+
+public sealed class AuthentikSettings
+{
+    public string? Authority { get; set; }
+
+    public string? ApiResourceName { get; set; }
+
+    public string? ApiResourceSecret { get; set; }
+
+    public string? RequiredClaimName { get; set; }
+
+    public string? RequiredClaimNameValue { get; set; }
+
+    public bool RequireHttpsMetadata { get; set; }
+
+    public bool BypassSslErrors { get; set; }
+}

LiteCharms.Features/Api/OpenApiBearerSecuritySchemeTransformer.cs

@@ -0,0 +1,16 @@
+namespace LiteCharms.Features.Api;
+
+public sealed class OpenApiBearerSecuritySchemeTransformer : IOpenApiDocumentTransformer
+{
+    public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
+    {
+        var bearerScheme = new OpenApiSecurityScheme
+        {
+            Type = SecuritySchemeType.Http,
+            Scheme = "bearer",
+            Description = "JWT Authorization header using the Bearer scheme",
+        };
+
+        document.AddComponent("Bearer", bearerScheme);
+    }
+}

LiteCharms.Features/Email/Models/EmailEnquiryModel.cs

@@ -7,25 +7,25 @@ public sealed class EmailEnquiryModel
     [Required]
     [MinLength(2)]
     [MaxLength(255)]
-    [Display(Name = "Full Name")]
+    [System.ComponentModel.DataAnnotations.Display(Name = "Full Name")]
     public string? FullName { get; set; }
 
     [Required]
     [EmailAddress]
     [MinLength(5)]
     [MaxLength(255)]
-    [Display(Name = "Email Address")]
+    [System.ComponentModel.DataAnnotations.Display(Name = "Email Address")]
     public string? EmailAddress { get; set; }
 
     [Required]
     [MinLength(2)]
     [MaxLength(255)]
-    [Display(Name = "Subject")]
+    [System.ComponentModel.DataAnnotations.Display(Name = "Subject")]
     public string? EmailSubject { get; set; }
 
     [Required]
     [MinLength(2)]
     [MaxLength(2000)]
-    [Display(Name = "Message")]
+    [System.ComponentModel.DataAnnotations.Display(Name = "Message")]
     public string? Message { get; set; }
 }

LiteCharms.Features/Extensions/Api.cs

@@ -0,0 +1,133 @@
+using LiteCharms.Features.Abstractions;
+using LiteCharms.Features.Api;
+using LiteCharms.Features.Api.Configuration;
+
+namespace LiteCharms.Features.Extensions;
+
+public static class Api
+{
+    public const string Books = nameof(Books);
+    public const string Payments = nameof(Payments);
+
+    public static IServiceCollection AddAuthentic(this IServiceCollection services, IConfiguration configuration)
+    {
+        var configSection = configuration.GetSection(nameof(AuthentikSettings));
+
+        var authOptions = new AuthentikSettings();
+        configSection.Bind(authOptions);
+
+        services.Configure<AuthentikSettings>(configSection);
+
+        services.AddAuthentication(OAuth2IntrospectionDefaults.AuthenticationScheme)
+            .AddOAuth2Introspection(OAuth2IntrospectionDefaults.AuthenticationScheme, options =>
+            {
+                options.Authority = authOptions.Authority;
+                options.ClientId = authOptions.ApiResourceName;
+                options.ClientSecret = authOptions.ApiResourceSecret;
+
+                options.DiscoveryPolicy.RequireHttps = authOptions.RequireHttpsMetadata;
+                options.EnableCaching = true;
+                options.CacheDuration = TimeSpan.FromMinutes(10);
+            });
+
+        if (!string.IsNullOrWhiteSpace(authOptions.RequiredClaimName) && !string.IsNullOrWhiteSpace(authOptions.RequiredClaimNameValue))
+        {
+            services.AddAuthorizationBuilder()
+                .AddPolicy("ApiScope", policy =>
+                    policy.RequireClaim(authOptions.RequiredClaimName, authOptions.RequiredClaimNameValue));
+        }
+        else
+            services.AddAuthorization();
+
+        return services;
+    }
+
+    public static IServiceCollection AddApiServices(this IServiceCollection services, IConfiguration configuration)
+    {
+        services.AddHttpClient();
+
+        services.AddApiVersioning(options =>
+        {
+            options.DefaultApiVersion = new ApiVersion(1);
+            options.ReportApiVersions = true;
+            options.AssumeDefaultVersionWhenUnspecified = true;
+            options.ApiVersionReader = ApiVersionReader.Combine(new UrlSegmentApiVersionReader(),
+                new QueryStringApiVersionReader("version"),
+                new QueryStringApiVersionReader("version"),
+                new MediaTypeApiVersionReader("version"));
+        })
+        .AddApiExplorer(options =>
+        {
+            options.GroupNameFormat = "'v'VVV";
+            options.SubstituteApiVersionInUrl = true;
+        });
+
+        var urls = configuration["ASPNETCORE_URLS"] ?? configuration["Urls"];
+        var healthUrl = "http://localhost:8080/health";
+
+        if (!string.IsNullOrWhiteSpace(urls))
+        {
+            string firstUrl = urls.Split(';').FirstOrDefault(s => s.Contains("http://"))!
+                .Replace("0.0.0.0", "localhost")
+                .Replace("*", "localhost")
+                .Replace("+", "localhost");
+
+            healthUrl = $"{firstUrl.TrimEnd('/')}/health";
+        }
+
+        services.AddHealthChecksUI(setup =>
+        {
+            setup.SetNotifyUnHealthyOneTimeUntilChange();
+            setup.AddHealthCheckEndpoint("primary, heal", healthUrl);
+            setup.SetHeaderText("Midrand Books");
+        })
+        .AddInMemoryStorage();
+
+        services.AddOutputCache(options =>
+        {
+            options.AddBasePolicy(builder => builder.Cache());
+            options.DefaultExpirationTimeSpan = TimeSpan.FromSeconds(10);
+        });
+
+        services.AddOpenApi(options => options.AddDocumentTransformer<OpenApiBearerSecuritySchemeTransformer>());
+
+        return services;
+    }
+
+    public static IApplicationBuilder MapEndpoints(this WebApplication app, IDictionary<int, RouteGroupBuilder> versionGroups)
+    {
+        var endpoints = app.Services.GetRequiredService<IEnumerable<IEndpoint>>();
+
+        foreach (var endpoint in endpoints)
+        {
+            var versionAttributes = endpoint.GetType().GetCustomAttributes<ApiVersionTargetAttribute>().ToList();
+
+            if (versionAttributes.Count != 0)
+            {
+                foreach (var attr in versionAttributes)
+                    if (versionGroups.TryGetValue(attr.MajorVersion, out var targetGroup))
+                        endpoint.Map(targetGroup);
+            }
+            else
+                endpoint.Map(app);
+        }
+
+        return app;
+    }
+
+    public static IServiceCollection AddEndpoints(this IServiceCollection services, Assembly assembly)
+    {
+        ServiceDescriptor[] discriptors = [.. assembly.DefinedTypes
+            .Where(t => t is { IsInterface: false, IsAbstract: false })
+            .Where(t => t.IsAssignableTo(typeof(IEndpoint)))
+            .Select(t => ServiceDescriptor.Transient(typeof(IEndpoint), t))];
+
+        services.TryAddEnumerable(discriptors);
+
+        return services;
+    }
+
+    public static string ToEndpointName(this Type target, string? annotation = "") =>
+        $"{target.Name.Replace("Endpoint", string.Empty)}{annotation}".ToLower(CultureInfo.CurrentCulture);
+
+}

LiteCharms.Features/Extensions/Quartz.cs

@@ -1,5 +1,5 @@
-using LiteCharms.Features.Quartz;
-using LiteCharms.Features.Quartz.Abstractions;
+using LiteCharms.Features.Abstractions;
+using LiteCharms.Features.Quartz;
 using static LiteCharms.Features.Extensions.Postgres;
 
 namespace LiteCharms.Features.Extensions;

LiteCharms.Features/LiteCharms.Features.csproj

@@ -29,6 +29,38 @@
     <None Include="..\icon.png" Pack="true" PackagePath="\" />
   </ItemGroup>
 
+  <!-- Security (IODC)-->
+  <ItemGroup>
+    <PackageReference Include="IdentityModel.AspNetCore" Version="4.3.0" />
+    <PackageReference Include="IdentityModel.AspNetCore.OAuth2introspection" Version="6.2.0" />
+    <PackageReference Include="IdentityServer4.AccessTokenValidation" Version="3.0.1" />
+    <PackageReference Include="IdentityModel" Version="6.2.0" />
+    <PackageReference Include="Microsoft.AspNetCore.Authentication.Certificate" Version="10.0.8" />
+    <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.8" />
+
+    <Using Include="IdentityModel.AspNetCore.OAuth2Introspection"/>
+  </ItemGroup>
+
+  <!-- API Versioning -->
+  <ItemGroup>
+    <PackageReference Include="AccessTokenClient.Extensions" Version="5.1.0" />
+    <PackageReference Include="Asp.Versioning.Abstractions" Version="10.0.0" />
+    <PackageReference Include="Asp.Versioning.Http" Version="10.0.0" />
+    <PackageReference Include="Asp.Versioning.Mvc.ApiExplorer" Version="10.0.0" />
+
+    <Using Include="Asp.Versioning" />
+  </ItemGroup>
+
+  <!-- API Documentation -->
+  <ItemGroup>
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.8" />
+    <PackageReference Include="Scalar.AspNetCore" Version="2.14.14" />
+
+    <Using Include="Scalar.AspNetCore" />
+    <Using Include="Microsoft.OpenApi" />
+    <Using Include="Microsoft.AspNetCore.OpenApi" />
+  </ItemGroup>
+
   <!-- Quartz Scheduler-->
   <ItemGroup>    
     <PackageReference Include="Hashids.net" Version="1.7.0" />    
@@ -147,6 +179,9 @@
 
   <!-- Shared Usings -->
   <ItemGroup>
+    <Using Include="System.Reflection" />
+    <Using Include="Microsoft.Extensions.DependencyInjection.Extensions" />
+    <Using Include="Microsoft.AspNetCore.Routing" />
     <Using Include="System.Web" />
     <Using Include="Microsoft.IdentityModel.Tokens" />
     <Using Include="Microsoft.AspNetCore.Http" />

LiteCharms.Features/Quartz/Abstractions/IJobOrchestrator.cs

@@ -1,12 +0,0 @@
-using LiteCharms.Features.Abstractions;
-
-namespace LiteCharms.Features.Quartz.Abstractions;
-
-public interface IJobOrchestrator
-{
-    Task SendAsync<TNotification>(TNotification notification, CancellationToken cancellationToken = default)
-        where TNotification : IEvent;
-
-    Task ScheduleAsync<TNotification>(TNotification notification, string cronExpression, CancellationToken cancellationToken = default) 
-        where TNotification : IEvent;
-}

LiteCharms.Features/Quartz/JobOrchestrator.cs

@@ -1,11 +1,10 @@
 using LiteCharms.Features.Abstractions;
-using LiteCharms.Features.Quartz.Abstractions;
 
 namespace LiteCharms.Features.Quartz;
 
 public sealed class JobOrchestrator(ISchedulerFactory schedulerFactory) : IJobOrchestrator
 {
-    public async Task SendAsync<TNotification>(TNotification notification, CancellationToken cancellationToken = default)
+    public async ValueTask SendAsync<TNotification>(TNotification notification, CancellationToken cancellationToken = default)
         where TNotification : IEvent
     {
         var chainedJobGroup = "onetime-jobs";
@@ -19,17 +18,18 @@ public sealed class JobOrchestrator(ISchedulerFactory schedulerFactory) : IJobOr
             .WithDescription($"Correlation ID: {notification.CorrelationId}")
             .UsingJobData(new JobDataMap { ["Payload"] = JsonSerializer.Serialize(notification) })
             .DisallowConcurrentExecution()
+            .RequestRecovery()
             .Build();
 
         var trigger = global::Quartz.TriggerBuilder.Create()
             .WithIdentity(triggerKey)
-            .StartNow()            
+            .StartNow()
             .Build();
 
         await scheduler.ScheduleJob(job, new List<ITrigger> { trigger }.AsReadOnly(), replace: true, cancellationToken);
     }
 
-    public async Task ScheduleAsync<TNotification>(TNotification notification, string cronExpression, CancellationToken cancellationToken = default)
+    public async ValueTask ScheduleAsync<TNotification>(TNotification notification, string cronExpression, CancellationToken cancellationToken = default)
         where TNotification : IEvent
     {
         var chainedJobGroup = "scheduled-jobs";
@@ -63,4 +63,25 @@ public sealed class JobOrchestrator(ISchedulerFactory schedulerFactory) : IJobOr
         else
             await scheduler.ScheduleJob(job, new List<ITrigger> { trigger }.AsReadOnly(), replace: true, cancellationToken);
     }
+
+    public async ValueTask<bool> InterruptAsync(string eventName, string? correlationId = null, CancellationToken cancellationToken = default)
+    {
+        var scheduler = await schedulerFactory.GetScheduler(cancellationToken);
+
+        var jobKeyName = string.Empty;
+        var jobGroup = string.Empty;
+
+        if (!string.IsNullOrWhiteSpace(correlationId))
+        {
+            jobKeyName = $"{eventName.ToLower(CultureInfo.InvariantCulture)}-{correlationId.ToLower(CultureInfo.InvariantCulture)}";
+            jobGroup = "onetime-jobs";
+        }
+        else
+        {
+            jobKeyName = eventName.ToLower(CultureInfo.InvariantCulture);
+            jobGroup = "scheduled-jobs";
+        }
+
+        return await scheduler.Interrupt(JobKey.Create(jobKeyName, jobGroup), cancellationToken);
+    }
 }

LiteCharms.Features/Quartz/MediatorJob.cs

@@ -8,6 +8,9 @@ public sealed class MediatorJob<TNotification>(IMediator mediator) : IJob where
 {
     public async Task Execute(IJobExecutionContext context)
     {
+        if (context.Recovering)
+            Trace.WriteLine($"CRITICAL RECOVERY: Resurrecting job '{typeof(TNotification).Name}' after a previous cluster node crashed mid-execution.");
+
         var data = context.MergedJobDataMap["Payload"] as string;
 
         if (string.IsNullOrWhiteSpace(data))
@@ -21,17 +24,28 @@ public sealed class MediatorJob<TNotification>(IMediator mediator) : IJob where
 
         if (notification is null)
         {
-            Trace.WriteLine("Notification could not be JSon converted from data string, job ended");
+            Trace.WriteLine("Notification could not be Json converted from data string, job ended");
 
             return;
         }
-                
-        using var activity = MediatorTelemetry.Source.StartActivity($"Quartz: {typeof(TNotification).Name}");
-                
+
+        using var activity = MediatorTelemetry.Source.StartActivity(typeof(TNotification).Name);
+
         activity?.SetTag("event.correlation_id", notification.CorrelationId);
 
-        await mediator.Publish(notification, context.CancellationToken);
+        try
+        {
+            await mediator.Publish(notification, context.CancellationToken);
 
-        Trace.WriteLine("Job published");
+            Trace.WriteLine("Job published successfully");
+        }
+        catch (OperationCanceledException) when (context.CancellationToken.IsCancellationRequested)
+        {
+            Trace.WriteLine($"Job '{typeof(TNotification).Name}' was gracefully interrupted by the cluster control plane.");
+            
+            activity?.SetStatus(ActivityStatusCode.Ok);
+
+            return;
+        }
     }
 }

LiteCharms.Features/Quartz/RetryJobListener.cs

@@ -12,6 +12,9 @@ public sealed class RetryJobListener : IJobListener
 
     public async Task JobWasExecuted(IJobExecutionContext context, JobExecutionException? jobException, CancellationToken cancellationToken = default)
     {
+        if (context.CancellationToken.IsCancellationRequested)
+            return;
+
         if (jobException is not null && context.RefireCount < RetryCount)
             jobException.RefireImmediately = true;
     }