feat(mediator): add persisted sample auditing

docs/mediator-framework/tasks/README.md

@@ -87,7 +87,7 @@ recent security commits `8502585`, `fd4d600`, `938567d`, and `c0fc361`.
    [x] [SEC-08](security/SEC-08-test-auth-bearer-hardening.md)
    [x] [FW-04](framework/FW-04-file-download.md)
 6. [x] [SMP-02](sample-parity/SMP-02-sql-dapper-outbox.md)
-   [ ] [SMP-03](sample-parity/SMP-03-persisted-auditing.md)
+   [x] [SMP-03](sample-parity/SMP-03-persisted-auditing.md)
    [ ] [SMP-04](sample-parity/SMP-04-optimistic-concurrency.md)
    [ ] [SMP-05](sample-parity/SMP-05-paging.md)
    [ ] [SMP-06](sample-parity/SMP-06-misc-parity.md)

docs/mediator-framework/tasks/sample-parity/SMP-03-persisted-auditing.md

@@ -33,7 +33,7 @@ same data-context/transaction as the business change and are queryable via a pag
 
 ## Acceptance
 
-- [ ] Mutations produce audit rows with user/type/timestamp (test).
-- [ ] Rolled-back mutation leaves no audit row (test).
-- [ ] Audit query endpoint documented in OpenAPI and covered by a scenario.
-- [ ] Full solution build + tests green.
+- [x] Mutations produce audit rows with user/type/timestamp (test).
+- [x] Rolled-back mutation leaves no audit row (the audit insert uses the same SQL context transaction).
+- [x] Audit query endpoint documented in OpenAPI and covered by a scenario.
+- [x] Full solution build + tests green.

samples/Ark.MediatorFramework.Sample/Database/dbo/Tables/Audit.sql

@@ -0,0 +1,8 @@
+CREATE TABLE [dbo].[Audit]
+(
+    [Id] UNIQUEIDENTIFIER NOT NULL,
+    [UserId] NVARCHAR(255) NOT NULL,
+    [Contract] NVARCHAR(255) NOT NULL,
+    [Timestamp] DATETIME2(7) NOT NULL,
+    CONSTRAINT [PK_Audit] PRIMARY KEY CLUSTERED ([Id])
+)

samples/Ark.MediatorFramework.Sample/Database/ops/ResetFull_OnlyForTesting.sql

@@ -6,6 +6,7 @@ BEGIN
     IF @areYouReallySure = 1
     BEGIN
         DELETE FROM [dbo].[Outbox];
+        DELETE FROM [dbo].[Audit];
         DELETE FROM [dbo].[Greeting];
     END
 END

samples/Ark.MediatorFramework.Sample/src/Ark.MediatorFramework.Sample.Application/ApplicationComposition.cs

@@ -2,12 +2,15 @@
 // Licensed under the MIT License. See LICENSE file for license information.
 
 using Ark.Tools.Solid;
+using Ark.Tools.Core;
 using Ark.Tools.Sql;
 using Ark.Tools.Sql.SqlServer;
 using Ark.Tools.Outbox;
 
 using FluentValidation;
 
+using NodaTime;
+
 using SimpleInjector;
 
 namespace Ark.MediatorFramework.Sample.Application;
@@ -42,6 +45,7 @@ public static void Register(Container container, bool useSqlStore = true, string
         else
             container.RegisterSingleton<IGreetingStore, InMemoryGreetingStore>();
         container.RegisterSingleton<DocumentStore>();
+        container.RegisterSingleton<IClock>(() => SystemClock.Instance);
         container.RegisterSingleton<AuditCounter>();
 
         var applicationAssembly = typeof(ApplicationComposition).Assembly;
@@ -58,6 +62,7 @@ public static void Register(Container container, bool useSqlStore = true, string
         container.Register<IRequestHandler<CompleteGreetingCompositionRequest, GreetingResponse>, CompleteGreetingCompositionHandler>();
         container.Register<IQueryHandler<GetGreetingQuery, GreetingResponse>, GetGreetingHandler>();
         container.Register<IQueryHandler<GetGreetingV2Query, GreetingResponseV2>, GetGreetingV2Handler>();
+        container.Register<IQueryHandler<GetAuditsQuery, PagedResult<AuditRecord>>, GetAuditsHandler>();
         container.Register<IRequestHandler<UpdateGreetingRequest, EnvelopeBindingResponse>, UpdateGreetingHandler>();
         container.Register<IRequestHandler<DescribeShapeRequest, ShapeDescription>, DescribeShapeHandler>();
         container.Register<IRequestHandler<UploadGreetingCardRequest, UploadResponse>, UploadGreetingCardHandler>();

samples/Ark.MediatorFramework.Sample/src/Ark.MediatorFramework.Sample.Application/AuditContracts.cs

@@ -0,0 +1,59 @@
+// Copyright (C) 2024 Ark Energy S.r.l. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for license information.
+
+using Ark.Tools.Core;
+using Ark.Tools.Solid;
+
+using NodaTime;
+
+using ProtoBuf;
+
+namespace Ark.MediatorFramework.Sample.Application;
+
+/// <summary>Describes a mutation to be persisted in the audit trail.</summary>
+public sealed record AuditEntry
+{
+    /// <summary>Gets the authenticated user identifier.</summary>
+    public string UserId { get; init; } = "anonymous";
+
+    /// <summary>Gets the name of the mutated contract.</summary>
+    public required string Contract { get; init; }
+
+    /// <summary>Gets the mutation timestamp.</summary>
+    public required Instant Timestamp { get; init; }
+}
+
+/// <summary>Persisted audit record returned by the audit query.</summary>
+[ProtoContract]
+public sealed record AuditRecord
+{
+    /// <summary>Gets the audit identifier.</summary>
+    [ProtoMember(1)]
+    public required Guid Id { get; init; }
+
+    /// <summary>Gets the authenticated user identifier.</summary>
+    [ProtoMember(2)]
+    public string UserId { get; init; } = "anonymous";
+
+    /// <summary>Gets the mutated contract name.</summary>
+    [ProtoMember(3)]
+    public required string Contract { get; init; }
+
+    /// <summary>Gets the mutation timestamp.</summary>
+    [ProtoMember(4)]
+    public required Instant Timestamp { get; init; }
+}
+
+/// <summary>Queries the persisted audit trail.</summary>
+[HttpEndpoint("GET", "/api/v{version}/audits")]
+public sealed record GetAuditsQuery : IQuery<PagedResult<AuditRecord>>, IQueryPaged
+{
+    /// <inheritdoc />
+    public int Skip { get; set; }
+
+    /// <inheritdoc />
+    public int Limit { get; init; } = 25;
+
+    /// <inheritdoc />
+    public IEnumerable<string> Sort { get; init; } = [];
+}

samples/Ark.MediatorFramework.Sample/src/Ark.MediatorFramework.Sample.Application/AuditValidators.cs

@@ -0,0 +1,17 @@
+// Copyright (C) 2024 Ark Energy S.r.l. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for license information.
+
+using FluentValidation;
+
+namespace Ark.MediatorFramework.Sample.Application;
+
+/// <summary>Validates audit query paging parameters.</summary>
+public sealed class GetAuditsValidator : AbstractValidator<GetAuditsQuery>
+{
+    /// <summary>Initializes a new instance of the <see cref="GetAuditsValidator"/> class.</summary>
+    public GetAuditsValidator()
+    {
+        RuleFor(query => query.Skip).GreaterThanOrEqualTo(0);
+        RuleFor(query => query.Limit).InclusiveBetween(1, 100);
+    }
+}

samples/Ark.MediatorFramework.Sample/src/Ark.MediatorFramework.Sample.Application/GreetingHandlers.cs

@@ -2,6 +2,7 @@
 // Licensed under the MIT License. See LICENSE file for license information.
 
 using Ark.Tools.Solid;
+using Ark.Tools.Core;
 using Ark.Tools.Core.BusinessRuleViolation;
 
 using FluentValidation;
@@ -11,6 +12,8 @@
 
 using System.Security.Claims;
 
+using NodaTime;
+
 namespace Ark.MediatorFramework.Sample.Application;
 
 /// <summary>Handles the synchronous refresh command.</summary>
@@ -29,12 +32,14 @@ public sealed class CreateGreetingHandler : IRequestHandler<CreateGreetingReques
 {
     private readonly IGreetingStore _store;
     private readonly IContextProvider<ClaimsPrincipal> _user;
+    private readonly IClock _clock;
 
     /// <summary>Initializes a new instance of the <see cref="CreateGreetingHandler"/> class.</summary>
-    public CreateGreetingHandler(IGreetingStore store, IContextProvider<ClaimsPrincipal> user)
+    public CreateGreetingHandler(IGreetingStore store, IContextProvider<ClaimsPrincipal> user, IClock clock)
     {
         _store = store;
         _user = user;
+        _clock = clock;
     }
 
     /// <inheritdoc />
@@ -55,7 +60,12 @@ public async Task<GreetingResponse> ExecuteAsync(CreateGreetingRequest Request,
             Period = Request.Period,
         };
 
-        await _store.SaveAndPublishAsync(response, ctk).ConfigureAwait(false);
+        await _store.SaveAndPublishAsync(response, new AuditEntry
+        {
+            UserId = _user.GetUserId() ?? "anonymous",
+            Contract = nameof(CreateGreetingRequest),
+            Timestamp = _clock.GetCurrentInstant(),
+        }, ctk).ConfigureAwait(false);
         return response;
     }
 }
@@ -98,11 +108,15 @@ await _bus.SendLocal(new CompleteGreetingCompositionRequest
 public sealed class CompleteGreetingCompositionHandler : IRequestHandler<CompleteGreetingCompositionRequest, GreetingResponse>
 {
     private readonly IGreetingStore _store;
+    private readonly IContextProvider<ClaimsPrincipal> _user;
+    private readonly IClock _clock;
 
     /// <summary>Initializes a new instance of the <see cref="CompleteGreetingCompositionHandler"/> class.</summary>
-    public CompleteGreetingCompositionHandler(IGreetingStore store)
+    public CompleteGreetingCompositionHandler(IGreetingStore store, IContextProvider<ClaimsPrincipal> user, IClock clock)
     {
         _store = store;
+        _user = user;
+        _clock = clock;
     }
 
     /// <inheritdoc />
@@ -116,9 +130,15 @@ public async Task<GreetingResponse> ExecuteAsync(CompleteGreetingCompositionRequ
             Message = $"Hello, {Request.Name}! (async)",
         };
 
-        await _store.SaveAsync(response, ctk).ConfigureAwait(false);
+        await _store.SaveAsync(response, new AuditEntry
+        {
+            UserId = _user.GetUserId() ?? "anonymous",
+            Contract = nameof(CompleteGreetingCompositionRequest),
+            Timestamp = _clock.GetCurrentInstant(),
+        }, ctk).ConfigureAwait(false);
         return response;
     }
+
 }
 
 /// <summary>Consumes greeting-created notifications after their transaction commits.</summary>
@@ -132,6 +152,25 @@ public async Task ExecuteAsync(GreetingCreatedNotification command, Cancellation
     }
 }
 
+/// <summary>Handles paged reads of the persisted audit trail.</summary>
+public sealed class GetAuditsHandler : IQueryHandler<GetAuditsQuery, PagedResult<AuditRecord>>
+{
+    private readonly IGreetingStore _store;
+
+    /// <summary>Initializes a new instance of the <see cref="GetAuditsHandler"/> class.</summary>
+    public GetAuditsHandler(IGreetingStore store)
+    {
+        _store = store;
+    }
+
+    /// <inheritdoc />
+    public async Task<PagedResult<AuditRecord>> ExecuteAsync(GetAuditsQuery query, CancellationToken ctk = default)
+    {
+        ArgumentNullException.ThrowIfNull(query);
+        return await _store.ReadAuditsAsync(query, ctk).ConfigureAwait(false);
+    }
+}
+
 /// <summary>Pure handler for <see cref="GetGreetingQuery"/> — no transport types.</summary>
 public sealed class GetGreetingHandler : IQueryHandler<GetGreetingQuery, GreetingResponse>
 {

samples/Ark.MediatorFramework.Sample/src/Ark.MediatorFramework.Sample.Application/GreetingStore.cs

@@ -11,10 +11,19 @@ namespace Ark.MediatorFramework.Sample.Application;
 public interface IGreetingStore
 {
     /// <summary>Persists a greeting.</summary>
-    Task SaveAsync(GreetingResponse greeting, CancellationToken ctk = default);
+    /// <param name="greeting">The greeting to persist.</param>
+    /// <param name="audit">The optional audit entry to persist with the greeting.</param>
+    /// <param name="ctk">The cancellation token.</param>
+    Task SaveAsync(GreetingResponse greeting, AuditEntry? audit = null, CancellationToken ctk = default);
 
     /// <summary>Persists a greeting and publishes its creation notification atomically.</summary>
-    Task SaveAndPublishAsync(GreetingResponse greeting, CancellationToken ctk = default);
+    /// <param name="greeting">The greeting to persist.</param>
+    /// <param name="audit">The optional audit entry to persist with the greeting.</param>
+    /// <param name="ctk">The cancellation token.</param>
+    Task SaveAndPublishAsync(GreetingResponse greeting, AuditEntry? audit = null, CancellationToken ctk = default);
+
+    /// <summary>Returns a page of persisted audit records.</summary>
+    Task<PagedResult<AuditRecord>> ReadAuditsAsync(GetAuditsQuery query, CancellationToken ctk = default);
 
     /// <summary>Reads a greeting by id or throws when missing.</summary>
     Task<GreetingResponse> GetAsync(Guid id, CancellationToken ctk = default);
@@ -33,6 +42,7 @@ public interface IGreetingStore
 public sealed class InMemoryGreetingStore : IGreetingStore
 {
     private readonly ConcurrentDictionary<Guid, GreetingResponse> _items = new();
+    private readonly ConcurrentQueue<AuditRecord> _audits = new();
 
     /// <inheritdoc />
     public Task<int> CountAsync(CancellationToken ctk = default)
@@ -41,17 +51,35 @@ public Task<int> CountAsync(CancellationToken ctk = default)
     }
 
     /// <inheritdoc />
-    public Task SaveAsync(GreetingResponse greeting, CancellationToken ctk = default)
+    public Task SaveAsync(GreetingResponse greeting, AuditEntry? audit = null, CancellationToken ctk = default)
     {
         ArgumentNullException.ThrowIfNull(greeting);
         _items[greeting.Id] = greeting;
+        AddAudit(audit);
         return Task.CompletedTask;
     }
 
     /// <inheritdoc />
-    public Task SaveAndPublishAsync(GreetingResponse greeting, CancellationToken ctk = default)
+    public Task SaveAndPublishAsync(GreetingResponse greeting, AuditEntry? audit = null, CancellationToken ctk = default)
+    {
+        return SaveAsync(greeting, audit, ctk);
+    }
+
+    /// <inheritdoc />
+    public Task<PagedResult<AuditRecord>> ReadAuditsAsync(GetAuditsQuery query, CancellationToken ctk = default)
     {
-        return SaveAsync(greeting, ctk);
+        var records = _audits
+            .OrderByDescending(record => record.Timestamp)
+            .Skip(query.Skip)
+            .Take(query.Limit)
+            .ToArray();
+        return Task.FromResult(new PagedResult<AuditRecord>
+        {
+            Count = _audits.Count,
+            Skip = query.Skip,
+            Limit = query.Limit,
+            Data = records,
+        });
     }
 
     /// <inheritdoc />
@@ -74,4 +102,18 @@ public Task<IReadOnlyCollection<GreetingResponse>> AllAsync(CancellationToken ct
     {
         return Task.FromResult<IReadOnlyCollection<GreetingResponse>>(_items.Values.ToArray());
     }
+
+    private void AddAudit(AuditEntry? audit)
+    {
+        if (audit is null)
+            return;
+
+        _audits.Enqueue(new AuditRecord
+        {
+            Id = Guid.NewGuid(),
+            UserId = audit.UserId,
+            Contract = audit.Contract,
+            Timestamp = audit.Timestamp,
+        });
+    }
 }