From 4d72eda9f26a65f0c272ad471d17f556f83efabc Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Sun, 18 Oct 2026 09:01:55 +0100 Subject: [PATCH 01/41] chore: fabric updates --- .config/dotnet-tools.json | 9 +- .../purview-build.json | 0 Directory.Packages.props | 48 +++-- Justfile | 3 + global.json | 2 +- src/EventSourcing.slnx | 2 +- src/src/Admin.API/AdminEndpointOptions.cs | 2 +- .../Endpoints/AdminAggregatesEndpoints.cs | 6 +- .../Endpoints/AdminOperationalEndpoints.cs | 6 +- .../Endpoints/AdminSnapshotEndpoints.cs | 8 +- .../Builder/WebApplicationExtensions.cs | 2 +- .../Models/AdminAuditEntry.cs | 2 +- .../Admin.Abstractions/Models/AdminFeature.cs | 2 +- .../Models/AdminPermission.cs | 2 +- .../Models/AggregateSummaryResponse.cs | 2 +- .../Models/EventEnvelopeResponse.cs | 2 +- .../Models/EventMetadataResponse.cs | 2 +- .../Admin.Abstractions/Models/PagedResult.cs | 2 +- .../Models/ProjectionProvenance.cs | 2 +- .../Models/ProjectionResponse.cs | 2 +- .../Queries/AggregateSearchQuery.cs | 2 +- .../Queries/EventRangeQuery.cs | 2 +- .../Services/IAdminAggregateQueryService.cs | 6 +- .../Services/IAdminAuditLogger.cs | 4 +- .../Services/IAdminEventQueryService.cs | 6 +- .../Services/IAdminPermissionProvider.cs | 4 +- .../Services/IAdminProjectionService.cs | 4 +- .../AzureStorageAdminAggregateQueryService.cs | 6 +- .../AzureStorageAdminEventQueryService.cs | 6 +- .../AzureStorageAdminProjectionService.cs | 4 +- .../HostApplicationBuilderExtensions.cs | 2 +- .../ServiceCollectionExtensions.cs | 2 +- .../MongoDbAdminAggregateQueryService.cs | 6 +- .../MongoDbAdminEventQueryService.cs | 6 +- .../MongoDbAdminProjectionService.cs | 4 +- .../HostApplicationBuilderExtensions.cs | 2 +- .../PostgresAdminAggregateQueryService.cs | 6 +- .../PostgresAdminEventQueryService.cs | 6 +- .../PostgresAdminProjectionService.cs | 4 +- .../AuthorizationBuilderExtensions.cs | 2 +- .../ServiceCollectionExtensions.cs | 2 +- .../AdminFeatureAuthorizationHandler.cs | 2 +- .../Handlers/AggregateTypeAccessHandler.cs | 2 +- .../InMemoryAdminAuditLogger.cs | 4 +- .../Providers/DenyAllPermissionProvider.cs | 4 +- .../Requirements/AdminFeatureRequirement.cs | 2 +- .../HostApplicationBuilderExtensions.cs | 2 +- .../SqlServerAdminAggregateQueryService.cs | 6 +- .../SqlServerAdminEventQueryService.cs | 6 +- .../SqlServerAdminProjectionService.cs | 4 +- .../EFSnapshotShapeAnalyzer.cs | 4 +- .../Samples.AppHost/Samples.AppHost.csproj | 2 +- .../Services/SampleAdminPermissionProvider.cs | 4 +- .../Samples/Domain/OrderAggregate.Rules.cs | 2 +- .../SqlServerAdminProjectionServiceTests.cs | 2 +- .../Api/AdminApiEndpointTests.cs | 6 +- .../Api/AdminOperationalEndpointsTests.cs | 6 +- .../Security/PermissionProviderTests.cs | 4 +- .../EFSnapshotShapeAnalyzerTests.cs | 26 +-- .../EFSourceGeneratorTests.cs | 2 +- .../EFOpaqueAttribute.cs | 4 +- .../Snapshots/PostgresSnapshotClientTests.cs | 2 +- .../Snapshots/SqlServerSnapshotClientTests.cs | 8 +- .../AggregateSourceGeneratorTests.cs | 194 +++++++++--------- ...ggregateSourceGeneratorValueObjectTests.cs | 6 +- .../EventContractManifestIncrementalTests.cs | 4 +- .../EventContractCompatibilityTests.cs | 32 +-- .../Manifest/EventContractManifestTests.cs | 16 +- src/tools/AdminAPI.OpenAPI/Program.cs | 7 +- 69 files changed, 288 insertions(+), 267 deletions(-) rename purview-build.json => .config/purview-build.json (100%) diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index 4f9b391c..970bffd8 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -10,7 +10,7 @@ "rollForward": false }, "dotnet-inspect": { - "version": "0.20.0", + "version": "0.26.0", "commands": [ "dotnet-inspect" ], @@ -22,6 +22,13 @@ "nswag" ], "rollForward": false + }, + "purview.build": { + "version": "0.6.0", + "commands": [ + "purview-build" + ], + "rollForward": false } } } \ No newline at end of file diff --git a/purview-build.json b/.config/purview-build.json similarity index 100% rename from purview-build.json rename to .config/purview-build.json diff --git a/Directory.Packages.props b/Directory.Packages.props index 609551e9..53c8ca92 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -1,29 +1,37 @@ - - true + + true + true + + + + + + + 5.9.0 5.9.0 - 1.68.17 - 1.0.0-prerelease.54 - 1.0.0-prerelease.9 - 2.0.0-prerelease.28 - 5.0.0-prerelease.19 - 1.0.0-prerelease.41 - 13.5.3.8 - 4.15.0 + 1.75.0 + 1.1.1 + 1.1.0 + 2.2.0 + 5.0.4 + 1.0.1 + 13.5.3.11 + 4.16.0 0.14.0 - 10.0.12 - 13.5.4 - 1.19.0 - 10.10.0 + 10.0.13 + 13.6.1 + 1.20.0 + 10.11.0 - - + + @@ -48,7 +56,7 @@ - + @@ -71,12 +79,12 @@ - + - + - + diff --git a/Justfile b/Justfile index 2de6d9b2..86933100 100644 --- a/Justfile +++ b/Justfile @@ -14,6 +14,9 @@ artifacts_folder := "./artifacts" pipeline_feed := "https://api.nuget.org/v3/index.json" pipeline_tool := ".tools/purview-build/purview-build" +# Vendored unreleased CSharpier that parses C# 15 unions. See .assets/csharpier/README.md. +#csharpier := ".assets/csharpier/CSharpier.dll" + current_version := `bun -p "require('./package.json').version"` [private] diff --git a/global.json b/global.json index 0961f097..3015eba5 100644 --- a/global.json +++ b/global.json @@ -3,7 +3,7 @@ "allowPrerelease": false }, "msbuild-sdks": { - "Purview.BuildSdk": "1.0.0-prerelease.60" + "Purview.BuildSdk": "1.0.7" }, "test": { "runner": "Microsoft.Testing.Platform" diff --git a/src/EventSourcing.slnx b/src/EventSourcing.slnx index f12d3af3..2366e85d 100644 --- a/src/EventSourcing.slnx +++ b/src/EventSourcing.slnx @@ -2,10 +2,10 @@ + - diff --git a/src/src/Admin.API/AdminEndpointOptions.cs b/src/src/Admin.API/AdminEndpointOptions.cs index a9f39f19..85dca98a 100644 --- a/src/src/Admin.API/AdminEndpointOptions.cs +++ b/src/src/Admin.API/AdminEndpointOptions.cs @@ -1,6 +1,6 @@ using Microsoft.AspNetCore.Builder; using Microsoft.AspNetCore.Routing; -using Purview.EventSourcing.Admin.Abstractions.Models; +using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Security; namespace Purview.EventSourcing.Admin.API; diff --git a/src/src/Admin.API/Endpoints/AdminAggregatesEndpoints.cs b/src/src/Admin.API/Endpoints/AdminAggregatesEndpoints.cs index 94c0493f..d831d589 100644 --- a/src/src/Admin.API/Endpoints/AdminAggregatesEndpoints.cs +++ b/src/src/Admin.API/Endpoints/AdminAggregatesEndpoints.cs @@ -8,9 +8,9 @@ using Microsoft.AspNetCore.Routing; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Options; -using Purview.EventSourcing.Admin.Abstractions.Models; -using Purview.EventSourcing.Admin.Abstractions.Queries; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Queries; +using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.API.Contracts; using Purview.EventSourcing.Admin.API.Filters; using Purview.EventSourcing.Admin.Security; diff --git a/src/src/Admin.API/Endpoints/AdminOperationalEndpoints.cs b/src/src/Admin.API/Endpoints/AdminOperationalEndpoints.cs index 730df621..05835a22 100644 --- a/src/src/Admin.API/Endpoints/AdminOperationalEndpoints.cs +++ b/src/src/Admin.API/Endpoints/AdminOperationalEndpoints.cs @@ -3,9 +3,9 @@ using Microsoft.AspNetCore.Http.HttpResults; using Microsoft.AspNetCore.Routing; using Microsoft.Extensions.DependencyInjection; -using Purview.EventSourcing.Admin.Abstractions.Models; -using Purview.EventSourcing.Admin.Abstractions.Queries; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Queries; +using Purview.EventSourcing.Admin.Services; +using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Security; using Purview.EventSourcing.Manifest; using Purview.EventSourcing.Outbox; diff --git a/src/src/Admin.API/Endpoints/AdminSnapshotEndpoints.cs b/src/src/Admin.API/Endpoints/AdminSnapshotEndpoints.cs index 3e98804b..a616115a 100644 --- a/src/src/Admin.API/Endpoints/AdminSnapshotEndpoints.cs +++ b/src/src/Admin.API/Endpoints/AdminSnapshotEndpoints.cs @@ -1,16 +1,16 @@ -using System.Linq.Expressions; -using System.Reflection; using Microsoft.AspNetCore.Builder; using Microsoft.AspNetCore.Http; using Microsoft.AspNetCore.Http.HttpResults; using Microsoft.AspNetCore.Routing; using Microsoft.Extensions.DependencyInjection; -using Purview.EventSourcing.Admin.Abstractions.Models; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.Security; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Snapshotting; using Purview.EventSourcing.Services; +using System.Linq.Expressions; +using System.Reflection; namespace Purview.EventSourcing.Admin.API.Endpoints; diff --git a/src/src/Admin.API/Extensions/Microsoft/AspNetCore/Builder/WebApplicationExtensions.cs b/src/src/Admin.API/Extensions/Microsoft/AspNetCore/Builder/WebApplicationExtensions.cs index b10c8a7c..83052638 100644 --- a/src/src/Admin.API/Extensions/Microsoft/AspNetCore/Builder/WebApplicationExtensions.cs +++ b/src/src/Admin.API/Extensions/Microsoft/AspNetCore/Builder/WebApplicationExtensions.cs @@ -2,7 +2,7 @@ using System.Diagnostics.CodeAnalysis; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Options; -using Purview.EventSourcing.Admin.Abstractions.Models; +using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.API.Endpoints; namespace Microsoft.AspNetCore.Builder; diff --git a/src/src/Admin.Abstractions/Models/AdminAuditEntry.cs b/src/src/Admin.Abstractions/Models/AdminAuditEntry.cs index 82a8f94b..c5a928e0 100644 --- a/src/src/Admin.Abstractions/Models/AdminAuditEntry.cs +++ b/src/src/Admin.Abstractions/Models/AdminAuditEntry.cs @@ -1,4 +1,4 @@ -namespace Purview.EventSourcing.Admin.Abstractions.Models; +namespace Purview.EventSourcing.Admin.Models; /// /// A record of a privileged Admin portal operation for audit. diff --git a/src/src/Admin.Abstractions/Models/AdminFeature.cs b/src/src/Admin.Abstractions/Models/AdminFeature.cs index b55f6004..33157a93 100644 --- a/src/src/Admin.Abstractions/Models/AdminFeature.cs +++ b/src/src/Admin.Abstractions/Models/AdminFeature.cs @@ -1,4 +1,4 @@ -namespace Purview.EventSourcing.Admin.Abstractions.Models; +namespace Purview.EventSourcing.Admin.Models; /// /// Identifies the capabilities exposed by the admin portal. diff --git a/src/src/Admin.Abstractions/Models/AdminPermission.cs b/src/src/Admin.Abstractions/Models/AdminPermission.cs index cac33364..39bc37c8 100644 --- a/src/src/Admin.Abstractions/Models/AdminPermission.cs +++ b/src/src/Admin.Abstractions/Models/AdminPermission.cs @@ -1,4 +1,4 @@ -namespace Purview.EventSourcing.Admin.Abstractions.Models; +namespace Purview.EventSourcing.Admin.Models; /// /// Represents a permission granted to a user for an admin portal feature. diff --git a/src/src/Admin.Abstractions/Models/AggregateSummaryResponse.cs b/src/src/Admin.Abstractions/Models/AggregateSummaryResponse.cs index dd2490cd..6b55bdbf 100644 --- a/src/src/Admin.Abstractions/Models/AggregateSummaryResponse.cs +++ b/src/src/Admin.Abstractions/Models/AggregateSummaryResponse.cs @@ -1,4 +1,4 @@ -namespace Purview.EventSourcing.Admin.Abstractions.Models; +namespace Purview.EventSourcing.Admin.Models; /// /// Summarizes the current state of an aggregate stream. diff --git a/src/src/Admin.Abstractions/Models/EventEnvelopeResponse.cs b/src/src/Admin.Abstractions/Models/EventEnvelopeResponse.cs index 53203200..4c00907c 100644 --- a/src/src/Admin.Abstractions/Models/EventEnvelopeResponse.cs +++ b/src/src/Admin.Abstractions/Models/EventEnvelopeResponse.cs @@ -1,6 +1,6 @@ using System.Text.Json; -namespace Purview.EventSourcing.Admin.Abstractions.Models; +namespace Purview.EventSourcing.Admin.Models; /// /// Represents a single event together with its metadata and raw JSON payload. diff --git a/src/src/Admin.Abstractions/Models/EventMetadataResponse.cs b/src/src/Admin.Abstractions/Models/EventMetadataResponse.cs index afe7ee03..3b4219a6 100644 --- a/src/src/Admin.Abstractions/Models/EventMetadataResponse.cs +++ b/src/src/Admin.Abstractions/Models/EventMetadataResponse.cs @@ -1,4 +1,4 @@ -namespace Purview.EventSourcing.Admin.Abstractions.Models; +namespace Purview.EventSourcing.Admin.Models; /// /// Describes the metadata associated with a single event in an aggregate stream. diff --git a/src/src/Admin.Abstractions/Models/PagedResult.cs b/src/src/Admin.Abstractions/Models/PagedResult.cs index 8fbbf18a..cd01c8d4 100644 --- a/src/src/Admin.Abstractions/Models/PagedResult.cs +++ b/src/src/Admin.Abstractions/Models/PagedResult.cs @@ -1,4 +1,4 @@ -namespace Purview.EventSourcing.Admin.Abstractions.Models; +namespace Purview.EventSourcing.Admin.Models; /// /// Represents a page of items returned by a paged query. diff --git a/src/src/Admin.Abstractions/Models/ProjectionProvenance.cs b/src/src/Admin.Abstractions/Models/ProjectionProvenance.cs index d519ea9b..521665f4 100644 --- a/src/src/Admin.Abstractions/Models/ProjectionProvenance.cs +++ b/src/src/Admin.Abstractions/Models/ProjectionProvenance.cs @@ -1,4 +1,4 @@ -namespace Purview.EventSourcing.Admin.Abstractions.Models; +namespace Purview.EventSourcing.Admin.Models; /// /// Describes how a projection was produced from an aggregate event stream. diff --git a/src/src/Admin.Abstractions/Models/ProjectionResponse.cs b/src/src/Admin.Abstractions/Models/ProjectionResponse.cs index 7bbcc669..12ea5c76 100644 --- a/src/src/Admin.Abstractions/Models/ProjectionResponse.cs +++ b/src/src/Admin.Abstractions/Models/ProjectionResponse.cs @@ -1,6 +1,6 @@ using System.Text.Json; -namespace Purview.EventSourcing.Admin.Abstractions.Models; +namespace Purview.EventSourcing.Admin.Models; /// /// Represents the projected state of an aggregate at a point in time or version. diff --git a/src/src/Admin.Abstractions/Queries/AggregateSearchQuery.cs b/src/src/Admin.Abstractions/Queries/AggregateSearchQuery.cs index 8e8517de..08fdee22 100644 --- a/src/src/Admin.Abstractions/Queries/AggregateSearchQuery.cs +++ b/src/src/Admin.Abstractions/Queries/AggregateSearchQuery.cs @@ -1,4 +1,4 @@ -namespace Purview.EventSourcing.Admin.Abstractions.Queries; +namespace Purview.EventSourcing.Admin.Queries; /// /// Defines the criteria used to search for aggregates in the admin portal. diff --git a/src/src/Admin.Abstractions/Queries/EventRangeQuery.cs b/src/src/Admin.Abstractions/Queries/EventRangeQuery.cs index 0f1114ff..936a359a 100644 --- a/src/src/Admin.Abstractions/Queries/EventRangeQuery.cs +++ b/src/src/Admin.Abstractions/Queries/EventRangeQuery.cs @@ -1,4 +1,4 @@ -namespace Purview.EventSourcing.Admin.Abstractions.Queries; +namespace Purview.EventSourcing.Admin.Queries; /// /// Defines a query over a range of events within a single aggregate stream. diff --git a/src/src/Admin.Abstractions/Services/IAdminAggregateQueryService.cs b/src/src/Admin.Abstractions/Services/IAdminAggregateQueryService.cs index ab00b752..f43aa0c5 100644 --- a/src/src/Admin.Abstractions/Services/IAdminAggregateQueryService.cs +++ b/src/src/Admin.Abstractions/Services/IAdminAggregateQueryService.cs @@ -1,7 +1,7 @@ -using Purview.EventSourcing.Admin.Abstractions.Models; -using Purview.EventSourcing.Admin.Abstractions.Queries; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Queries; -namespace Purview.EventSourcing.Admin.Abstractions.Services; +namespace Purview.EventSourcing.Admin.Services; /// /// Queries aggregates for the admin portal, providing search and detail retrieval. diff --git a/src/src/Admin.Abstractions/Services/IAdminAuditLogger.cs b/src/src/Admin.Abstractions/Services/IAdminAuditLogger.cs index e9a0b8c6..9e63fd37 100644 --- a/src/src/Admin.Abstractions/Services/IAdminAuditLogger.cs +++ b/src/src/Admin.Abstractions/Services/IAdminAuditLogger.cs @@ -1,6 +1,6 @@ -using Purview.EventSourcing.Admin.Abstractions.Models; +using Purview.EventSourcing.Admin.Models; -namespace Purview.EventSourcing.Admin.Abstractions.Services; +namespace Purview.EventSourcing.Admin.Services; /// /// Records privileged Admin portal operations. Applications may replace the default in-memory diff --git a/src/src/Admin.Abstractions/Services/IAdminEventQueryService.cs b/src/src/Admin.Abstractions/Services/IAdminEventQueryService.cs index e71fce48..87585188 100644 --- a/src/src/Admin.Abstractions/Services/IAdminEventQueryService.cs +++ b/src/src/Admin.Abstractions/Services/IAdminEventQueryService.cs @@ -1,7 +1,7 @@ -using Purview.EventSourcing.Admin.Abstractions.Models; -using Purview.EventSourcing.Admin.Abstractions.Queries; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Queries; -namespace Purview.EventSourcing.Admin.Abstractions.Services; +namespace Purview.EventSourcing.Admin.Services; /// /// Queries event streams for the admin portal. diff --git a/src/src/Admin.Abstractions/Services/IAdminPermissionProvider.cs b/src/src/Admin.Abstractions/Services/IAdminPermissionProvider.cs index db7e8cbd..ca643d22 100644 --- a/src/src/Admin.Abstractions/Services/IAdminPermissionProvider.cs +++ b/src/src/Admin.Abstractions/Services/IAdminPermissionProvider.cs @@ -1,7 +1,7 @@ using System.Security.Claims; -using Purview.EventSourcing.Admin.Abstractions.Models; +using Purview.EventSourcing.Admin.Models; -namespace Purview.EventSourcing.Admin.Abstractions.Services; +namespace Purview.EventSourcing.Admin.Services; /// /// Pluggable permission provider for admin portal. diff --git a/src/src/Admin.Abstractions/Services/IAdminProjectionService.cs b/src/src/Admin.Abstractions/Services/IAdminProjectionService.cs index 9d5ad9a7..7b53c4c8 100644 --- a/src/src/Admin.Abstractions/Services/IAdminProjectionService.cs +++ b/src/src/Admin.Abstractions/Services/IAdminProjectionService.cs @@ -1,6 +1,6 @@ -using Purview.EventSourcing.Admin.Abstractions.Models; +using Purview.EventSourcing.Admin.Models; -namespace Purview.EventSourcing.Admin.Abstractions.Services; +namespace Purview.EventSourcing.Admin.Services; /// /// Projects aggregate state for the admin portal at a specific version or point in time. diff --git a/src/src/Admin.AzureStorage/AzureStorageAdminAggregateQueryService.cs b/src/src/Admin.AzureStorage/AzureStorageAdminAggregateQueryService.cs index 24173e66..fc43e157 100644 --- a/src/src/Admin.AzureStorage/AzureStorageAdminAggregateQueryService.cs +++ b/src/src/Admin.AzureStorage/AzureStorageAdminAggregateQueryService.cs @@ -1,8 +1,8 @@ using Azure; using Microsoft.Extensions.Options; -using Purview.EventSourcing.Admin.Abstractions.Models; -using Purview.EventSourcing.Admin.Abstractions.Queries; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Queries; +using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.AzureStorage.Internal; using Purview.EventSourcing.AzureStorage; using Purview.EventSourcing.AzureStorage.Entities; diff --git a/src/src/Admin.AzureStorage/AzureStorageAdminEventQueryService.cs b/src/src/Admin.AzureStorage/AzureStorageAdminEventQueryService.cs index 8e8ebb05..c7fb2971 100644 --- a/src/src/Admin.AzureStorage/AzureStorageAdminEventQueryService.cs +++ b/src/src/Admin.AzureStorage/AzureStorageAdminEventQueryService.cs @@ -1,9 +1,9 @@ using System.Text.Json; using Azure; using Microsoft.Extensions.Options; -using Purview.EventSourcing.Admin.Abstractions.Models; -using Purview.EventSourcing.Admin.Abstractions.Queries; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Queries; +using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.AzureStorage.Internal; using Purview.EventSourcing.AzureStorage; using Purview.EventSourcing.AzureStorage.Entities; diff --git a/src/src/Admin.AzureStorage/AzureStorageAdminProjectionService.cs b/src/src/Admin.AzureStorage/AzureStorageAdminProjectionService.cs index 14e6b7ee..4bc47f9f 100644 --- a/src/src/Admin.AzureStorage/AzureStorageAdminProjectionService.cs +++ b/src/src/Admin.AzureStorage/AzureStorageAdminProjectionService.cs @@ -1,8 +1,8 @@ using System.Text.Json; using Azure; using Microsoft.Extensions.Options; -using Purview.EventSourcing.Admin.Abstractions.Models; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.AzureStorage.Internal; using Purview.EventSourcing.AzureStorage; using Purview.EventSourcing.AzureStorage.Entities; diff --git a/src/src/Admin.AzureStorage/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs b/src/src/Admin.AzureStorage/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs index 5ce1c568..6c6fe47b 100644 --- a/src/src/Admin.AzureStorage/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs +++ b/src/src/Admin.AzureStorage/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs @@ -1,6 +1,6 @@ using System.ComponentModel; using Microsoft.Extensions.DependencyInjection.Extensions; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Services; namespace Microsoft.Extensions.Hosting; diff --git a/src/src/Admin.MongoDB/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/Admin.MongoDB/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs index 43e0337a..4a3753f1 100644 --- a/src/src/Admin.MongoDB/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs +++ b/src/src/Admin.MongoDB/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -1,7 +1,7 @@ using System.ComponentModel; using Microsoft.Extensions.DependencyInjection.Extensions; using MongoDB.Driver; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Services; namespace Microsoft.Extensions.DependencyInjection; diff --git a/src/src/Admin.MongoDB/MongoDbAdminAggregateQueryService.cs b/src/src/Admin.MongoDB/MongoDbAdminAggregateQueryService.cs index 5423674c..11be24fd 100644 --- a/src/src/Admin.MongoDB/MongoDbAdminAggregateQueryService.cs +++ b/src/src/Admin.MongoDB/MongoDbAdminAggregateQueryService.cs @@ -1,7 +1,7 @@ using MongoDB.Driver; -using Purview.EventSourcing.Admin.Abstractions.Models; -using Purview.EventSourcing.Admin.Abstractions.Queries; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Queries; +using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.MongoDB.Events.Entities; namespace Purview.EventSourcing.Admin.MongoDB; diff --git a/src/src/Admin.MongoDB/MongoDbAdminEventQueryService.cs b/src/src/Admin.MongoDB/MongoDbAdminEventQueryService.cs index f0ad0066..136421b8 100644 --- a/src/src/Admin.MongoDB/MongoDbAdminEventQueryService.cs +++ b/src/src/Admin.MongoDB/MongoDbAdminEventQueryService.cs @@ -1,8 +1,8 @@ using System.Text.Json; using MongoDB.Driver; -using Purview.EventSourcing.Admin.Abstractions.Models; -using Purview.EventSourcing.Admin.Abstractions.Queries; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Queries; +using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.MongoDB.Events.Entities; namespace Purview.EventSourcing.Admin.MongoDB; diff --git a/src/src/Admin.MongoDB/MongoDbAdminProjectionService.cs b/src/src/Admin.MongoDB/MongoDbAdminProjectionService.cs index 21a205dc..9a5c5524 100644 --- a/src/src/Admin.MongoDB/MongoDbAdminProjectionService.cs +++ b/src/src/Admin.MongoDB/MongoDbAdminProjectionService.cs @@ -1,7 +1,7 @@ using System.Text.Json; using MongoDB.Driver; -using Purview.EventSourcing.Admin.Abstractions.Models; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.MongoDB.Events.Entities; namespace Purview.EventSourcing.Admin.MongoDB; diff --git a/src/src/Admin.Postgres/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs b/src/src/Admin.Postgres/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs index b923f086..3c3e7f9b 100644 --- a/src/src/Admin.Postgres/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs +++ b/src/src/Admin.Postgres/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs @@ -1,5 +1,5 @@ using Microsoft.Extensions.DependencyInjection.Extensions; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Services; namespace Microsoft.Extensions.Hosting; diff --git a/src/src/Admin.Postgres/PostgresAdminAggregateQueryService.cs b/src/src/Admin.Postgres/PostgresAdminAggregateQueryService.cs index 95a1a49c..2df9410d 100644 --- a/src/src/Admin.Postgres/PostgresAdminAggregateQueryService.cs +++ b/src/src/Admin.Postgres/PostgresAdminAggregateQueryService.cs @@ -1,8 +1,8 @@ using Microsoft.EntityFrameworkCore; using Microsoft.Extensions.Options; -using Purview.EventSourcing.Admin.Abstractions.Models; -using Purview.EventSourcing.Admin.Abstractions.Queries; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Queries; +using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.Postgres.Internal; using Purview.EventSourcing.Postgres.Events; using Purview.EventSourcing.Postgres.Events.EntityFramework; diff --git a/src/src/Admin.Postgres/PostgresAdminEventQueryService.cs b/src/src/Admin.Postgres/PostgresAdminEventQueryService.cs index 00dcf76c..e8b697e4 100644 --- a/src/src/Admin.Postgres/PostgresAdminEventQueryService.cs +++ b/src/src/Admin.Postgres/PostgresAdminEventQueryService.cs @@ -1,9 +1,9 @@ using System.Text.Json; using Microsoft.EntityFrameworkCore; using Microsoft.Extensions.Options; -using Purview.EventSourcing.Admin.Abstractions.Models; -using Purview.EventSourcing.Admin.Abstractions.Queries; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Queries; +using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.Postgres.Internal; using Purview.EventSourcing.Postgres.Events; using Purview.EventSourcing.Postgres.Events.EntityFramework; diff --git a/src/src/Admin.Postgres/PostgresAdminProjectionService.cs b/src/src/Admin.Postgres/PostgresAdminProjectionService.cs index 54bd9344..a4d14c45 100644 --- a/src/src/Admin.Postgres/PostgresAdminProjectionService.cs +++ b/src/src/Admin.Postgres/PostgresAdminProjectionService.cs @@ -1,8 +1,8 @@ using System.Text.Json; using Microsoft.EntityFrameworkCore; using Microsoft.Extensions.Options; -using Purview.EventSourcing.Admin.Abstractions.Models; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.Postgres.Internal; using Purview.EventSourcing.Postgres.Events; using Purview.EventSourcing.Postgres.Events.EntityFramework; diff --git a/src/src/Admin.Security/Extensions/Microsoft/AspNetCore/Authorization/AuthorizationBuilderExtensions.cs b/src/src/Admin.Security/Extensions/Microsoft/AspNetCore/Authorization/AuthorizationBuilderExtensions.cs index 2c2ef1bc..2f3b079d 100644 --- a/src/src/Admin.Security/Extensions/Microsoft/AspNetCore/Authorization/AuthorizationBuilderExtensions.cs +++ b/src/src/Admin.Security/Extensions/Microsoft/AspNetCore/Authorization/AuthorizationBuilderExtensions.cs @@ -1,6 +1,6 @@ using System.ComponentModel; using System.Diagnostics.CodeAnalysis; -using Purview.EventSourcing.Admin.Abstractions.Models; +using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Security.Requirements; namespace Microsoft.AspNetCore.Authorization; diff --git a/src/src/Admin.Security/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/Admin.Security/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs index dfca8be9..6bd8fd0b 100644 --- a/src/src/Admin.Security/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs +++ b/src/src/Admin.Security/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -1,7 +1,7 @@ using System.ComponentModel; using Microsoft.AspNetCore.Authorization; using Microsoft.Extensions.DependencyInjection.Extensions; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.Security.Handlers; using Purview.EventSourcing.Admin.Security.Providers; diff --git a/src/src/Admin.Security/Handlers/AdminFeatureAuthorizationHandler.cs b/src/src/Admin.Security/Handlers/AdminFeatureAuthorizationHandler.cs index 6309dcda..057aafb6 100644 --- a/src/src/Admin.Security/Handlers/AdminFeatureAuthorizationHandler.cs +++ b/src/src/Admin.Security/Handlers/AdminFeatureAuthorizationHandler.cs @@ -1,6 +1,6 @@ using System.Diagnostics.CodeAnalysis; using Microsoft.AspNetCore.Authorization; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.Security.Requirements; namespace Purview.EventSourcing.Admin.Security.Handlers; diff --git a/src/src/Admin.Security/Handlers/AggregateTypeAccessHandler.cs b/src/src/Admin.Security/Handlers/AggregateTypeAccessHandler.cs index c22ca5f1..49e7539a 100644 --- a/src/src/Admin.Security/Handlers/AggregateTypeAccessHandler.cs +++ b/src/src/Admin.Security/Handlers/AggregateTypeAccessHandler.cs @@ -1,6 +1,6 @@ using System.Diagnostics.CodeAnalysis; using Microsoft.AspNetCore.Authorization; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.Security.Requirements; namespace Purview.EventSourcing.Admin.Security.Handlers; diff --git a/src/src/Admin.Security/InMemoryAdminAuditLogger.cs b/src/src/Admin.Security/InMemoryAdminAuditLogger.cs index 2fa029bc..d86539ac 100644 --- a/src/src/Admin.Security/InMemoryAdminAuditLogger.cs +++ b/src/src/Admin.Security/InMemoryAdminAuditLogger.cs @@ -1,6 +1,6 @@ using System.Collections.Concurrent; -using Purview.EventSourcing.Admin.Abstractions.Models; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Services; namespace Purview.EventSourcing.Admin.Security; diff --git a/src/src/Admin.Security/Providers/DenyAllPermissionProvider.cs b/src/src/Admin.Security/Providers/DenyAllPermissionProvider.cs index ade11dde..7f305ed5 100644 --- a/src/src/Admin.Security/Providers/DenyAllPermissionProvider.cs +++ b/src/src/Admin.Security/Providers/DenyAllPermissionProvider.cs @@ -1,6 +1,6 @@ using System.Security.Claims; -using Purview.EventSourcing.Admin.Abstractions.Models; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Services; namespace Purview.EventSourcing.Admin.Security.Providers; diff --git a/src/src/Admin.Security/Requirements/AdminFeatureRequirement.cs b/src/src/Admin.Security/Requirements/AdminFeatureRequirement.cs index dbc156dd..46dbde59 100644 --- a/src/src/Admin.Security/Requirements/AdminFeatureRequirement.cs +++ b/src/src/Admin.Security/Requirements/AdminFeatureRequirement.cs @@ -1,5 +1,5 @@ using Microsoft.AspNetCore.Authorization; -using Purview.EventSourcing.Admin.Abstractions.Models; +using Purview.EventSourcing.Admin.Models; namespace Purview.EventSourcing.Admin.Security.Requirements; diff --git a/src/src/Admin.SqlServer/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs b/src/src/Admin.SqlServer/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs index 4244bf66..66c51040 100644 --- a/src/src/Admin.SqlServer/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs +++ b/src/src/Admin.SqlServer/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs @@ -1,5 +1,5 @@ using Microsoft.Extensions.DependencyInjection.Extensions; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.SQLServer; namespace Microsoft.Extensions.Hosting; diff --git a/src/src/Admin.SqlServer/SqlServerAdminAggregateQueryService.cs b/src/src/Admin.SqlServer/SqlServerAdminAggregateQueryService.cs index 975640b4..732a801b 100644 --- a/src/src/Admin.SqlServer/SqlServerAdminAggregateQueryService.cs +++ b/src/src/Admin.SqlServer/SqlServerAdminAggregateQueryService.cs @@ -1,8 +1,8 @@ using Microsoft.EntityFrameworkCore; using Microsoft.Extensions.Options; -using Purview.EventSourcing.Admin.Abstractions.Models; -using Purview.EventSourcing.Admin.Abstractions.Queries; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Queries; +using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.SQLServer.Internal; using Purview.EventSourcing.SqlServer.Events; using Purview.EventSourcing.SqlServer.Events.EntityFramework; diff --git a/src/src/Admin.SqlServer/SqlServerAdminEventQueryService.cs b/src/src/Admin.SqlServer/SqlServerAdminEventQueryService.cs index 049ef752..11c4fc06 100644 --- a/src/src/Admin.SqlServer/SqlServerAdminEventQueryService.cs +++ b/src/src/Admin.SqlServer/SqlServerAdminEventQueryService.cs @@ -1,9 +1,9 @@ using System.Text.Json; using Microsoft.EntityFrameworkCore; using Microsoft.Extensions.Options; -using Purview.EventSourcing.Admin.Abstractions.Models; -using Purview.EventSourcing.Admin.Abstractions.Queries; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Queries; +using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.SQLServer.Internal; using Purview.EventSourcing.SqlServer.Events; using Purview.EventSourcing.SqlServer.Events.EntityFramework; diff --git a/src/src/Admin.SqlServer/SqlServerAdminProjectionService.cs b/src/src/Admin.SqlServer/SqlServerAdminProjectionService.cs index da3c1c0e..d4327a9b 100644 --- a/src/src/Admin.SqlServer/SqlServerAdminProjectionService.cs +++ b/src/src/Admin.SqlServer/SqlServerAdminProjectionService.cs @@ -1,8 +1,8 @@ using System.Text.Json; using Microsoft.EntityFrameworkCore; using Microsoft.Extensions.Options; -using Purview.EventSourcing.Admin.Abstractions.Models; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.SQLServer.Internal; using Purview.EventSourcing.SqlServer.Events; using Purview.EventSourcing.SqlServer.Events.EntityFramework; diff --git a/src/src/EntityFrameworkCore.SourceGenerator/EFSnapshotShapeAnalyzer.cs b/src/src/EntityFrameworkCore.SourceGenerator/EFSnapshotShapeAnalyzer.cs index 7ee853e1..a6c42ed3 100644 --- a/src/src/EntityFrameworkCore.SourceGenerator/EFSnapshotShapeAnalyzer.cs +++ b/src/src/EntityFrameworkCore.SourceGenerator/EFSnapshotShapeAnalyzer.cs @@ -1,8 +1,8 @@ -using System.Collections.Immutable; using Microsoft.CodeAnalysis; using Microsoft.CodeAnalysis.CSharp.Syntax; using Microsoft.CodeAnalysis.Diagnostics; using Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.Heleprs; +using System.Collections.Immutable; namespace Purview.EventSourcing.EntityFrameworkCore.SourceGenerator; @@ -298,12 +298,14 @@ static bool IsMappedStructuralMember(IPropertySymbol property) if (TypeHelpers.HasAttribute(elementType, TypeLibrary.ScalarAttribute)) return false; + // EF materializes collection elements through JSON conversion, so we only need to validate that the element type is constructible and not a system type. return IsInspectableType(elementType); } if (ImplementsGenericEnumerable(memberType)) return false; + // EF materializes complex types through JSON conversion, so we only need to validate that the type is constructible and not a system type. return memberType is INamedTypeSymbol named && IsInspectableType(named); } diff --git a/src/src/Samples.AppHost/Samples.AppHost.csproj b/src/src/Samples.AppHost/Samples.AppHost.csproj index fe1dfdab..c89472e8 100644 --- a/src/src/Samples.AppHost/Samples.AppHost.csproj +++ b/src/src/Samples.AppHost/Samples.AppHost.csproj @@ -1,4 +1,4 @@ - + Values { get; } = new Dictionary(); } """; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).DoesNotHaveDiagnostic(DiagnosticLibrary.UnsupportedDictionary); } @@ -76,7 +76,7 @@ static class Consumer public static void Query() => Store.QueryAsync(report => report.Values.Count > 0); } """; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).HasDiagnostic(DiagnosticLibrary.OpaqueQuery); } @@ -100,7 +100,7 @@ sealed class ReportAggregate readonly record struct UserInfo(System.Guid Id, string? DisplayName); """; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).HasDiagnostic(DiagnosticLibrary.UnconstructibleSnapshotType); } @@ -128,7 +128,7 @@ public Capture() readonly record struct UserInfo(System.Guid Id, string? DisplayName); """; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).DoesNotHaveDiagnostic(DiagnosticLibrary.UnconstructibleSnapshotType); } @@ -150,7 +150,7 @@ sealed class ReportAggregate readonly record struct Amount(decimal Value); """; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).DoesNotHaveDiagnostic(DiagnosticLibrary.UnconstructibleSnapshotType); } @@ -182,7 +182,7 @@ sealed class Info } """; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).HasDiagnostic(DiagnosticLibrary.UnconstructibleSnapshotType); } @@ -212,7 +212,7 @@ public Holder() readonly record struct Details(string Name); """; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).HasDiagnostic(DiagnosticLibrary.UnconstructibleSnapshotType); } @@ -252,7 +252,7 @@ sealed class Details } """; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).DoesNotHaveDiagnostic(DiagnosticLibrary.UnconstructibleSnapshotType); } @@ -292,7 +292,7 @@ sealed class Details } """; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).DoesNotHaveDiagnostic(DiagnosticLibrary.UnconstructibleSnapshotType); } @@ -327,7 +327,7 @@ sealed class Info } """; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).HasDiagnostic(DiagnosticLibrary.NonWritableValueTypeMember); } @@ -357,7 +357,7 @@ sealed class Info } """; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).DoesNotHaveDiagnostic(DiagnosticLibrary.NonWritableValueTypeMember); await Assert.That(result).DoesNotHaveDiagnostic(DiagnosticLibrary.UnconstructibleSnapshotType); @@ -390,7 +390,7 @@ sealed class Info } """; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).DoesNotHaveDiagnostic(DiagnosticLibrary.NonWritableValueTypeMember); } diff --git a/src/tests/EntityFrameworkCore.SourceGenerator.UnitTests/EFSourceGeneratorTests.cs b/src/tests/EntityFrameworkCore.SourceGenerator.UnitTests/EFSourceGeneratorTests.cs index e3e32ce1..36933a0c 100644 --- a/src/tests/EntityFrameworkCore.SourceGenerator.UnitTests/EFSourceGeneratorTests.cs +++ b/src/tests/EntityFrameworkCore.SourceGenerator.UnitTests/EFSourceGeneratorTests.cs @@ -10,7 +10,7 @@ public async Task Generate_EmitsEFOpaqueAttribute(CancellationToken cancellation { const string source = "namespace Testing { public sealed class Model { } }"; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).HasNoDiagnostics(); await Assert.That(result).HasSymbol(TypeLibrary.EFOpaqueAttribute); diff --git a/src/tests/EventSourcing.UnitTests/EFOpaqueAttribute.cs b/src/tests/EventSourcing.UnitTests/EFOpaqueAttribute.cs index 4db0dcca..60d5c457 100644 --- a/src/tests/EventSourcing.UnitTests/EFOpaqueAttribute.cs +++ b/src/tests/EventSourcing.UnitTests/EFOpaqueAttribute.cs @@ -3,5 +3,5 @@ // declaration must keep the generated namespace and type name. namespace Purview.EventSourcing.EntityFrameworkCore; -[System.AttributeUsage(System.AttributeTargets.Property, Inherited = true, AllowMultiple = false)] -public sealed class EFOpaqueAttribute : System.Attribute; +[AttributeUsage(AttributeTargets.Property, Inherited = true, AllowMultiple = false)] +public sealed class EFOpaqueAttribute : Attribute; diff --git a/src/tests/EventSourcing.UnitTests/Postgres/Snapshots/PostgresSnapshotClientTests.cs b/src/tests/EventSourcing.UnitTests/Postgres/Snapshots/PostgresSnapshotClientTests.cs index 0c9546ed..b215ed02 100644 --- a/src/tests/EventSourcing.UnitTests/Postgres/Snapshots/PostgresSnapshotClientTests.cs +++ b/src/tests/EventSourcing.UnitTests/Postgres/Snapshots/PostgresSnapshotClientTests.cs @@ -1,8 +1,8 @@ -using System.Reflection; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; using Purview.EventSourcing.EntityFrameworkCore; using Purview.EventSourcing.Postgres.Client; +using System.Reflection; namespace Purview.EventSourcing.Postgres.Snapshots; diff --git a/src/tests/EventSourcing.UnitTests/SqlServer/Snapshots/SqlServerSnapshotClientTests.cs b/src/tests/EventSourcing.UnitTests/SqlServer/Snapshots/SqlServerSnapshotClientTests.cs index bb3c17c6..17fe3aea 100644 --- a/src/tests/EventSourcing.UnitTests/SqlServer/Snapshots/SqlServerSnapshotClientTests.cs +++ b/src/tests/EventSourcing.UnitTests/SqlServer/Snapshots/SqlServerSnapshotClientTests.cs @@ -1,10 +1,10 @@ -using System.Linq.Expressions; -using System.Reflection; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; using Purview.EventSourcing.EntityFrameworkCore; using Purview.EventSourcing.SqlServer.Client; using Purview.ValueObjects.Serialization; +using System.Linq.Expressions; +using System.Reflection; namespace Purview.EventSourcing.SqlServer.Snapshots; @@ -101,7 +101,7 @@ public async Task ValidateAggregatePayloadShape_GivenReadOnlyComplexMemberOnValu .That(() => ValidateAggregatePayloadShape(typeof(ReadOnlyValueTypeMemberAggregate))) .Throws(); - await Assert.That(exception.Message).Contains(nameof(ReadOnlyStructHolder.Mirror)); + await Assert.That(exception!.Message).Contains(nameof(ReadOnlyStructHolder.Mirror)); await Assert.That(exception.Message).Contains("writeable"); } @@ -112,7 +112,7 @@ public async Task ValidateAggregatePayloadShape_GivenReadOnlyComplexCollectionMe .That(() => ValidateAggregatePayloadShape(typeof(ReadOnlyValueTypeCollectionMemberAggregate))) .Throws(); - await Assert.That(exception.Message).Contains(nameof(ReadOnlyCollectionHolder.Items)); + await Assert.That(exception!.Message).Contains(nameof(ReadOnlyCollectionHolder.Items)); } [Test] diff --git a/src/tests/SourceGenerator.UnitTests/Generators/AggregateSourceGeneratorTests.cs b/src/tests/SourceGenerator.UnitTests/Generators/AggregateSourceGeneratorTests.cs index 0d108040..0ed603d6 100644 --- a/src/tests/SourceGenerator.UnitTests/Generators/AggregateSourceGeneratorTests.cs +++ b/src/tests/SourceGenerator.UnitTests/Generators/AggregateSourceGeneratorTests.cs @@ -1,6 +1,6 @@ +using Microsoft.CodeAnalysis; using System.Reflection; using System.Text.Json; -using Microsoft.CodeAnalysis; namespace Purview.EventSourcing.SourceGenerator.Generators; @@ -24,7 +24,7 @@ public class Empty { } "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); // Assert await Assert @@ -56,7 +56,7 @@ public partial class OrderAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); // Assert that 4 attribute files + 1 generated aggregate file await Assert @@ -82,7 +82,7 @@ public partial class EmptyAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); // Assert await Assert @@ -112,7 +112,7 @@ public partial class CounterAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); // Assert await Assert @@ -137,7 +137,7 @@ protected override void RegisterEvents() { } "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); // Assert that only attribute files, no generated aggregate await Assert @@ -167,7 +167,7 @@ protected override void RegisterEvents() { } "; var generatorOnlyOptions = EventSourcingGeneratorTestOptions.Default with { AnalyzerTypes = [] }; - var result = await GenerateAsync(source, generatorOnlyOptions, cancellationToken); + using var result = await GenerateAsync(source, generatorOnlyOptions, cancellationToken); await Assert .That(result.AllSyntaxTrees.Length) @@ -196,7 +196,7 @@ protected override void RegisterEvents() { } } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).HasDiagnostic(DiagnosticLibrary.AggregateMustBePartial); await Assert @@ -227,7 +227,7 @@ public partial class ProductAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); // Assert await Assert @@ -268,7 +268,7 @@ public partial ReportUploadAggregate MarkAsCompleted( } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert .That(result) @@ -307,7 +307,7 @@ public partial class ReportAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert .That(result) @@ -346,7 +346,7 @@ public partial class ReportAggregate : AggregateBase } "; - var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); await Assert.That(result).HasDiagnostic(DiagnosticLibrary.ScalarComplexValueMayNotTranslateInSQLSnapshots); } @@ -378,7 +378,7 @@ public partial class ReportAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert .That(result) @@ -420,7 +420,7 @@ public partial ReportUploadAggregate MarkAsCompleted( } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).DoesNotHaveDiagnostic("EVENTSTORE018"); await Assert.That(result).DoesNotHaveDiagnostic("EVENTSTORE019"); @@ -463,7 +463,7 @@ partial void OnComputingCompletedEvent(ref ReportProcessingStatus status) { } } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert .That(result) @@ -508,7 +508,7 @@ public partial ReportUploadAggregate MarkAsCompleted( } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var aggregate = query.GetClass("ReportUploadAggregate", "Testing"); @@ -569,7 +569,7 @@ partial void OnComputingCompletedEvent(ref string blob, ref object summary) } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).DoesNotHaveDiagnostic("EVENTSTORE018"); await Assert.That(result).DoesNotHaveDiagnostic("EVENTSTORE019"); @@ -607,7 +607,7 @@ public partial ReportUploadAggregate MarkAsComplete( } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var aggregate = query.GetClass("ReportUploadAggregate", "Testing"); @@ -644,7 +644,7 @@ public partial class SimpleAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); // Assert that no generator exceptions foreach (var genResult in result.DriverResult.Results) @@ -683,7 +683,7 @@ public partial class OrderAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); // Assert that event class uses the default namespace pattern and is a [EventContract] record await Assert.That(result.Generated().HasNamespace("Testing.OrderEvents")).IsTrue(); @@ -712,7 +712,7 @@ public partial class OrderAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result.Generated().HasClass("OrderAggregateJsonConverter", "Testing")).IsTrue(); await Assert.That(result.Generated().HasClass("OrderAggregateJsonModel", "Testing")).IsTrue(); @@ -751,7 +751,7 @@ public partial class OrderAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var orderCreated = query.GetRecord("OrderCreatedEvent", "Testing.OrderEvents"); @@ -782,7 +782,7 @@ public partial class OrderAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); // Events are [EventContract] records: equality/hash is compiler-generated, so there is no @@ -819,7 +819,7 @@ public partial class OrderAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var aggregate = query.GetClass("OrderAggregate", "Testing"); @@ -855,7 +855,7 @@ public partial class OrderAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var aggregate = query.GetClass("OrderAggregate", "Testing"); @@ -890,7 +890,7 @@ public partial class OrderAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var aggregate = query.GetClass("OrderAggregate", "Testing"); @@ -926,7 +926,7 @@ public partial class ProfileAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var aggregate = query.GetClass("ProfileAggregate", "Testing"); @@ -958,7 +958,7 @@ public partial class ProductAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var aggregate = query.GetClass("ProductAggregate", "Testing"); @@ -992,7 +992,7 @@ public partial class ProfileAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var aggregate = query.GetClass("ProfileAggregate", "Testing"); @@ -1028,7 +1028,7 @@ public partial class ProfileAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var aggregate = query.GetClass("ProfileAggregate", "Testing"); @@ -1066,7 +1066,7 @@ public partial class CounterAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var errors = result .CompilationResult.Compilation.GetDiagnostics(cancellationToken) @@ -1119,7 +1119,7 @@ public partial class CustomerAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var aggregate = query.GetClass("CustomerAggregate", "Testing"); @@ -1151,7 +1151,7 @@ public partial class ToggleAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var aggregate = query.GetClass("ToggleAggregate", "Testing"); @@ -1180,7 +1180,7 @@ public partial class EmptyAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var aggregate = query.GetClass("EmptyAggregate", "Testing"); @@ -1217,7 +1217,7 @@ public partial class OrderAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); // Assert that both event records exist in the default events namespace await Assert.That(result.Generated().HasRecord("OrderCreatedEvent", "Testing.OrderEvents")).IsTrue(); @@ -1243,7 +1243,7 @@ public partial class NotAnAggregate } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result.DriverResult.GeneratedTrees).Count().IsEqualTo(ExpectedFileCountPlusGen); @@ -1280,7 +1280,7 @@ public void NonPartialMethod(string value) "; // Act - var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); await Assert.That(result.Generated().HasRecord("NonPartialMethodEvent", "Testing.MixedEvents")).IsFalse(); await Assert.That(result).HasDiagnostic("EVENTSTORE007"); @@ -1310,7 +1310,7 @@ public partial class InterfaceOnlyAggregate : ITaggable } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var interfaceOnlyAggregate = result.Generated().GetClass("InterfaceOnlyAggregate", "Testing"); await Assert.That(interfaceOnlyAggregate.Node.BaseList?.ToString()).Contains("AggregateBase"); @@ -1345,7 +1345,7 @@ internal partial class InternalAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); // Assert that the generated partial class uses 'internal' access modifier var internalAggregate = result.Generated().GetClass("InternalAggregate", "Testing"); @@ -1366,7 +1366,7 @@ public class Empty { } "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); // Assert that attribute files are generated await Assert.That(result.DriverResult.GeneratedTrees).Count().IsEqualTo(ExpectedFileCount); @@ -1405,7 +1405,7 @@ public partial class OrderAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); // Assert that no generator exceptions foreach (var genResult in result.DriverResult.Results) @@ -1440,7 +1440,7 @@ public partial class SimpleAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var generatedSource = result.GetSource(); // Assert that generated file starts with auto-generated header @@ -1470,7 +1470,7 @@ public partial class OrderAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); // Assert that default version is 1 var query = result.Generated(); @@ -1503,7 +1503,7 @@ public partial class OrderAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); // Assert that explicit version 3 var query = result.Generated(); @@ -1539,7 +1539,7 @@ public partial class OrderAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var orderCreatedSchemaVersion = query @@ -1576,7 +1576,7 @@ public partial class OrderAggregate : AggregateBase } "; - var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); await Assert.That(result).HasDiagnostic(DiagnosticLibrary.EventSchemaVersionMustBePositive); } @@ -1605,7 +1605,7 @@ public partial class OrderAggregate : AggregateBase } "; - var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); await Assert.That(result).HasDiagnostic(DiagnosticLibrary.DuplicateEventSchemaVersionOnAggregate); } @@ -1625,7 +1625,7 @@ public class Empty { } "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); const string aggregateNamespace = "Purview.EventSourcing.Aggregates"; var query = result.Generated(); @@ -1659,7 +1659,7 @@ public partial class OrderAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); await Assert.That(query.HasRecord("OrderCreatedEvent", "Testing.OrderEvents")).IsTrue(); @@ -1693,7 +1693,7 @@ public partial class OrderAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); await Assert.That(query.HasRecord("OrderCreatedDomainEvent", "Testing.OrderEvents")).IsTrue(); @@ -1729,7 +1729,7 @@ public partial class OrderAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); await Assert.That(query.HasRecord("OrderCreatedCustomEvent", "Testing.OrderEvents")).IsTrue(); @@ -1764,7 +1764,7 @@ public partial class OrderAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); await Assert.That(query.HasNamespace("Testing.Custom.Events")).IsTrue(); @@ -1799,7 +1799,7 @@ public partial class OrderAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); await Assert.That(query.HasNamespace("Testing.Domain.Ordering")).IsTrue(); @@ -1836,7 +1836,7 @@ public partial class NotARealAggregate : Testing.AggregateBase } "; - var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); await Assert.That(result).HasDiagnostic("EVENTSTORE002"); } @@ -1862,7 +1862,7 @@ public partial class NestedAggregate : AggregateBase } "; - var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); await Assert.That(result).HasDiagnostic("EVENTSTORE003"); } @@ -1884,7 +1884,7 @@ public partial class GenericAggregate : AggregateBase } "; - var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); await Assert.That(result).HasDiagnostic("EVENTSTORE004"); } @@ -1909,7 +1909,7 @@ protected override void RegisterEvents() { } } "; - var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); await Assert.That(result).HasDiagnostic("EVENTSTORE005"); } @@ -1940,7 +1940,7 @@ public partial class PublicSetterAggregate : AggregateBase }} "; - var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); await Assert.That(result).HasDiagnostic("EVENTSTORE011"); } @@ -1965,7 +1965,7 @@ public partial class InvalidSignatureAggregate : AggregateBase } "; - var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); await Assert.That(result).HasDiagnostic("EVENTSTORE008"); } @@ -1990,7 +1990,7 @@ public partial class InvalidSignatureAggregate : AggregateBase } "; - var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); await Assert.That(result).HasDiagnostic("EVENTSTORE008"); } @@ -2019,7 +2019,7 @@ public partial class DuplicateEventAggregate : AggregateBase } "; - var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); await Assert.That(result).HasDiagnostic(DiagnosticLibrary.DuplicateGeneratedEventName); } @@ -2042,7 +2042,7 @@ public partial class MappingAggregate : AggregateBase } "; - var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); await Assert.That(result).HasDiagnostic(DiagnosticLibrary.EventParameterMustMapToWritableProperty); } @@ -2067,7 +2067,7 @@ public partial class MappingAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).DoesNotHaveDiagnostic(DiagnosticLibrary.EventParameterMustMapToWritableProperty); @@ -2109,7 +2109,7 @@ public partial void Rename( } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).DoesNotHaveDiagnostic(DiagnosticLibrary.EventParameterMustMapToWritableProperty); @@ -2152,7 +2152,7 @@ public partial class MappingAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var stockReceived = query.GetRecord("StockReceivedEvent", "Testing.MappingEvents"); @@ -2195,7 +2195,7 @@ public partial class MappingAggregate : AggregateBase } "; - var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); await Assert.That(result).HasDiagnostic(DiagnosticLibrary.EventParameterMustMapToWritableProperty); } @@ -2218,7 +2218,7 @@ public partial class InitOnlyAggregate : AggregateBase } "; - var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); await Assert.That(result).HasDiagnostic("EVENTSTORE010"); } @@ -2255,7 +2255,7 @@ public partial class OrderAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var aggregateTrees = result.PrimarySyntaxTrees; await Assert.That(aggregateTrees.Length).IsEqualTo(2); @@ -2308,7 +2308,7 @@ partial void Apply(global::Testing.OrderEvents.OrderCanceledEvent @event) "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); const string eventsNamespace = "Testing.OrderEvents"; @@ -2360,7 +2360,7 @@ public partial class ProductAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var productUpdated = query.GetRecord("ProductUpdatedEvent", "Testing.ProductEvents"); @@ -2407,7 +2407,7 @@ public partial class AccountAggregate : DomainAggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); // Assert that attribute files + 1 generated aggregate await Assert.That(result.DriverResult.GeneratedTrees).Count().IsEqualTo(ExpectedFileCountPlusGen); @@ -2450,7 +2450,7 @@ public partial class InvoiceAggregate : BillingAggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result.DriverResult.GeneratedTrees).Count().IsEqualTo(ExpectedFileCountPlusGen); @@ -2485,7 +2485,7 @@ public partial class OrderAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); // Assert that events namespace follows the pattern @@ -2535,7 +2535,7 @@ public partial class CounterAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var aggregate = query.GetClass("CounterAggregate", "Testing"); @@ -2588,7 +2588,7 @@ public partial class ProfileAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var bioUpdated = query.GetRecord("BioUpdatedEvent", "Testing.ProfileEvents"); @@ -2620,7 +2620,7 @@ public partial class ProfileAggregate } """; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); await Assert @@ -2655,7 +2655,7 @@ public partial class ProfileAggregate } """; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var cs8777 = result .CompilationResult.Compilation.GetDiagnostics(cancellationToken) .Where(d => d.Id == "CS8777") @@ -2699,7 +2699,7 @@ public partial class PublicAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); // Assert var publicAggregate = result.Generated().GetClass("PublicAggregate", "Testing"); @@ -2730,7 +2730,7 @@ public partial class NoteAggregate : AggregateBase "; // Act - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); // Assert that command method matches partial declaration @@ -2760,7 +2760,7 @@ public partial class CustomerAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var aggregate = query.GetClass("CustomerAggregate", "Testing"); @@ -2815,7 +2815,7 @@ public partial class CustomerAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var aggregate = query.GetClass("CustomerAggregate", "Testing"); @@ -2886,7 +2886,7 @@ partial void OnShouldApplyCustomerIdSetEvent(global::Testing.CustomerEvents.Cust } "; - var result = await GenerateAsync( + using var result = await GenerateAsync( source, EventSourcingGeneratorTestOptions.Default.Compile(), cancellationToken @@ -2927,7 +2927,7 @@ public partial class CustomerAggregate : AggregateBase } "; - var result = await GenerateAsync( + using var result = await GenerateAsync( source, EventSourcingGeneratorTestOptions.Default.Compile(), cancellationToken @@ -2999,7 +2999,7 @@ public partial class OrderAggregate : AggregateBase } "; - var result = await GenerateAsync( + using var result = await GenerateAsync( source, EventSourcingGeneratorTestOptions.Default.Compile(), cancellationToken @@ -3045,7 +3045,7 @@ public partial class OrderAggregate : AggregateBase } "; - var result = await GenerateAsync( + using var result = await GenerateAsync( source, EventSourcingGeneratorTestOptions.Default.Compile(), cancellationToken @@ -3099,7 +3099,7 @@ public partial class NamingAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).HasDiagnostics(DiagnosticLibrary.AggregateMethodShouldBeVerbPhrase.Id, 4); await Assert.That(result).DoesNotHaveDiagnostic(DiagnosticLibrary.UnableToInferEventName); @@ -3135,7 +3135,7 @@ public partial class NamingAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).HasDiagnostics(DiagnosticLibrary.EventNameOverrideShouldBePastTense, 4); } @@ -3168,7 +3168,7 @@ public sealed record CustomerRegisteredEvent } "; - var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); await Assert.That(result).DoesNotHaveDiagnostic(DiagnosticLibrary.EventNameOverrideShouldBePastTense); await Assert.That(result).DoesNotHaveDiagnostic(DiagnosticLibrary.UnableToInferEventName); @@ -3197,7 +3197,7 @@ public partial class NoteAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var warnings = result .DriverResult.Diagnostics.Where(static d => d.Severity == DiagnosticSeverity.Info) .ToArray(); @@ -3226,7 +3226,7 @@ public partial class NoteAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).DoesNotHaveDiagnostic(DiagnosticLibrary.EventParameterNullabilityMismatch); } @@ -3258,7 +3258,7 @@ public partial class ItemAggregate : AggregateBase }} "; - var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); await Assert .That(result) @@ -3286,7 +3286,7 @@ public partial class ItemAggregate : AggregateBase }} "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert .That(result) @@ -3319,7 +3319,7 @@ public partial class ItemAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).DoesNotHaveDiagnostic(DiagnosticLibrary.UnsupportedEventMethodSignature); @@ -3369,7 +3369,7 @@ private partial void Apply(global::Testing.ManualEvents.ValueCommandAppliedEvent } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var aggregate = query.GetClass("ManualAggregate", "Testing"); @@ -3415,7 +3415,7 @@ private partial void Apply(global::Testing.ManualCollectionEvents.TagAddedEvent }} "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var aggregate = query.GetClass("ManualCollectionAggregate", "Testing"); @@ -3447,7 +3447,7 @@ public partial class ItemAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).DoesNotHaveDiagnostic(DiagnosticLibrary.UnsupportedEventMethodSignature); @@ -3487,7 +3487,7 @@ public partial class ItemAggregate : AggregateBase } "; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); await Assert.That(result).DoesNotHaveDiagnostic(DiagnosticLibrary.UnsupportedEventMethodSignature); diff --git a/src/tests/SourceGenerator.UnitTests/Generators/AggregateSourceGeneratorValueObjectTests.cs b/src/tests/SourceGenerator.UnitTests/Generators/AggregateSourceGeneratorValueObjectTests.cs index 795bb1db..76d3db77 100644 --- a/src/tests/SourceGenerator.UnitTests/Generators/AggregateSourceGeneratorValueObjectTests.cs +++ b/src/tests/SourceGenerator.UnitTests/Generators/AggregateSourceGeneratorValueObjectTests.cs @@ -55,7 +55,7 @@ partial void OnRaisingOrderConfirmedEvent(ref OrderStatus status) } """; - var result = await GenerateAsync(source, cancellationToken); + using var result = await GenerateAsync(source, cancellationToken); var query = result.Generated(); var aggregate = await Assert.That(query).HasGeneratedClass(TypeRefs.Named("OrderAggregate", "Testing")); @@ -122,7 +122,7 @@ partial void OnRaisingOrderConfirmedEvent(ref OrderStatus status) } """; - var result = await GenerateAsync( + using var result = await GenerateAsync( source, EventSourcingGeneratorTestOptions.Default.Compile(), cancellationToken @@ -231,7 +231,7 @@ partial void OnAppliedCustomerEmailChangedEvent(global::Testing.CustomerEvents.C } """; - var result = await GenerateAsync( + using var result = await GenerateAsync( source, EventSourcingGeneratorTestOptions.Default.Compile(), cancellationToken diff --git a/src/tests/SourceGenerator.UnitTests/Incremental/EventContractManifestIncrementalTests.cs b/src/tests/SourceGenerator.UnitTests/Incremental/EventContractManifestIncrementalTests.cs index a990992c..d705ed5f 100644 --- a/src/tests/SourceGenerator.UnitTests/Incremental/EventContractManifestIncrementalTests.cs +++ b/src/tests/SourceGenerator.UnitTests/Incremental/EventContractManifestIncrementalTests.cs @@ -84,10 +84,10 @@ public async Task TriviaOnlyChange_DoesNotRecompareContracts(CancellationToken c [Test] public async Task BaselineContentChange_AffectsOnlyComparisonDiagnostics(CancellationToken cancellationToken) { - var compatible = await GenerateAsync(OrderSource, WithBaseline(BaselineV1Json), cancellationToken); + using var compatible = await GenerateAsync(OrderSource, WithBaseline(BaselineV1Json), cancellationToken); await Assert.That(compatible).DoesNotHaveDiagnostic("EVENTSTORE035"); - var regressed = await GenerateAsync(OrderSource, WithBaseline(BaselineV2Json), cancellationToken); + using var regressed = await GenerateAsync(OrderSource, WithBaseline(BaselineV2Json), cancellationToken); await Assert.That(regressed).HasDiagnostic("EVENTSTORE035"); var compatibleGenerated = GeneratedAggregateSources(compatible); diff --git a/src/tests/SourceGenerator.UnitTests/Manifest/EventContractCompatibilityTests.cs b/src/tests/SourceGenerator.UnitTests/Manifest/EventContractCompatibilityTests.cs index 9ae34cc5..f40d73ac 100644 --- a/src/tests/SourceGenerator.UnitTests/Manifest/EventContractCompatibilityTests.cs +++ b/src/tests/SourceGenerator.UnitTests/Manifest/EventContractCompatibilityTests.cs @@ -121,7 +121,7 @@ public class NotAnAggregate } """; - var result = await GenerateAsync( + using var result = await GenerateAsync( removedAggregateSource, ManifestTestHelpers.WithBaseline(baselineJson), cancellationToken @@ -135,7 +135,7 @@ public async Task Generate_GivenRemovedEvent_ReportsEventContractEventRemoved(Ca { var baselineJson = await GenerateBaselineAsync(OrderAggregateWithTwoEvents, cancellationToken); - var result = await GenerateAsync( + using var result = await GenerateAsync( OrderAggregateSingleEvent, ManifestTestHelpers.WithBaseline(baselineJson), cancellationToken @@ -149,7 +149,7 @@ public async Task Generate_GivenRemovedField_ReportsEventContractFieldRemoved(Ca { var baselineJson = await GenerateBaselineAsync(OrderAggregateWithTwoEvents, cancellationToken); - var result = await GenerateAsync( + using var result = await GenerateAsync( OrderAggregateRemovedField, ManifestTestHelpers.WithBaseline(baselineJson), cancellationToken @@ -165,7 +165,7 @@ CancellationToken cancellationToken { var baselineJson = await GenerateBaselineAsync(OrderAggregateWithTwoEvents, cancellationToken); - var result = await GenerateAsync( + using var result = await GenerateAsync( OrderAggregateChangedFieldType, ManifestTestHelpers.WithBaseline(baselineJson), cancellationToken @@ -209,14 +209,14 @@ public partial class OrderAggregate : AggregateBase } """; - var baselineRun = await GenerateAsync( + using var baselineRun = await GenerateAsync( nullableOriginal, ManifestTestHelpers.WithManifestEnabledAndNullableContext(), cancellationToken ); var baselineJson = ManifestTestHelpers.ExtractManifestJson(ManifestTestHelpers.GetManifestSource(baselineRun)); - var result = await GenerateAsync( + using var result = await GenerateAsync( nonNullableCurrent, ManifestTestHelpers.WithBaselineAndNullableContext(baselineJson), cancellationToken @@ -246,7 +246,7 @@ public partial class OrderAggregate : AggregateBase var baselineJson = await GenerateBaselineAsync(MinimalOrderAggregate, cancellationToken); - var result = await GenerateAsync( + using var result = await GenerateAsync( requiredCurrent, ManifestTestHelpers.WithBaseline(baselineJson), cancellationToken @@ -279,7 +279,7 @@ public partial void CreateOrder( var baselineJson = await GenerateBaselineAsync(MinimalOrderAggregate, cancellationToken); - var result = await GenerateAsync( + using var result = await GenerateAsync( addedRequiredField, ManifestTestHelpers.WithBaseline(baselineJson), cancellationToken @@ -295,7 +295,7 @@ CancellationToken cancellationToken { var baselineJson = await GenerateBaselineAsync(OrderAggregateVersionTwo, cancellationToken); - var result = await GenerateAsync( + using var result = await GenerateAsync( OrderAggregateVersionOne, ManifestTestHelpers.WithBaseline(baselineJson), cancellationToken @@ -309,7 +309,7 @@ public async Task Generate_GivenMalformedBaseline_ReportsEventContractBaselineMa CancellationToken cancellationToken ) { - var result = await GenerateAsync( + using var result = await GenerateAsync( OrderAggregateSingleEvent, ManifestTestHelpers.WithBaseline("{ this is not valid json"), cancellationToken @@ -326,7 +326,7 @@ CancellationToken cancellationToken const string unsupportedVersion = /*lang=json,strict*/ """{"formatVersion":99,"aggregates":[]}"""; - var result = await GenerateAsync( + using var result = await GenerateAsync( OrderAggregateSingleEvent, ManifestTestHelpers.WithBaseline(unsupportedVersion), cancellationToken @@ -371,14 +371,14 @@ public partial class OrderAggregate : AggregateBase } """; - var baselineRun = await GenerateAsync( + using var baselineRun = await GenerateAsync( minimalNullableBaseline, ManifestTestHelpers.WithManifestEnabledAndNullableContext(), cancellationToken ); var baselineJson = ManifestTestHelpers.ExtractManifestJson(ManifestTestHelpers.GetManifestSource(baselineRun)); - var result = await GenerateAsync( + using var result = await GenerateAsync( addedOptionalField, ManifestTestHelpers.WithBaselineAndNullableContext(baselineJson), cancellationToken @@ -398,7 +398,7 @@ public async Task Generate_GivenVersionBump_ReportsNoCompatibilityDiagnostics(Ca { var baselineJson = await GenerateBaselineAsync(OrderAggregateVersionOne, cancellationToken); - var result = await GenerateAsync( + using var result = await GenerateAsync( OrderAggregateVersionTwo, ManifestTestHelpers.WithBaseline(baselineJson), cancellationToken @@ -418,7 +418,7 @@ public async Task Generate_GivenAddedEvent_ReportsNoCompatibilityDiagnostics(Can { var baselineJson = await GenerateBaselineAsync(MinimalOrderAggregate, cancellationToken); - var result = await GenerateAsync( + using var result = await GenerateAsync( OrderAggregateWithTwoEvents, ManifestTestHelpers.WithBaseline(baselineJson), cancellationToken @@ -435,7 +435,7 @@ public async Task Generate_GivenAddedEvent_ReportsNoCompatibilityDiagnostics(Can async Task GenerateBaselineAsync(string source, CancellationToken cancellationToken) { - var result = await GenerateAsync(source, ManifestTestHelpers.WithManifestEnabled(), cancellationToken); + using var result = await GenerateAsync(source, ManifestTestHelpers.WithManifestEnabled(), cancellationToken); return ManifestTestHelpers.ExtractManifestJson(ManifestTestHelpers.GetManifestSource(result)); } } diff --git a/src/tests/SourceGenerator.UnitTests/Manifest/EventContractManifestTests.cs b/src/tests/SourceGenerator.UnitTests/Manifest/EventContractManifestTests.cs index 7cbab7f6..efd3701f 100644 --- a/src/tests/SourceGenerator.UnitTests/Manifest/EventContractManifestTests.cs +++ b/src/tests/SourceGenerator.UnitTests/Manifest/EventContractManifestTests.cs @@ -101,12 +101,12 @@ public partial class InvoiceAggregate : AggregateBase [Test] public async Task Generate_WithManifestEnabled_EmitsDeterministicManifest(CancellationToken cancellationToken) { - var first = await GenerateAsync( + using var first = await GenerateAsync( OrderAggregateSource, ManifestTestHelpers.WithManifestEnabled(), cancellationToken ); - var second = await GenerateAsync( + using var second = await GenerateAsync( OrderAggregateSource, ManifestTestHelpers.WithManifestEnabled(), cancellationToken @@ -143,7 +143,7 @@ await Assert [Test] public async Task Generate_WithoutManifestProperty_DoesNotEmitManifest(CancellationToken cancellationToken) { - var result = await GenerateAsync(OrderAggregateSource, cancellationToken); + using var result = await GenerateAsync(OrderAggregateSource, cancellationToken); await Assert.That(ManifestTestHelpers.GetManifestSource(result)).IsEmpty(); } @@ -151,12 +151,12 @@ public async Task Generate_WithoutManifestProperty_DoesNotEmitManifest(Cancellat [Test] public async Task Generate_ManifestOrderingIsIndependentOfDeclarationOrder(CancellationToken cancellationToken) { - var ordered = await GenerateAsync( + using var ordered = await GenerateAsync( OrderAggregateSource, ManifestTestHelpers.WithManifestEnabled(), cancellationToken ); - var reordered = await GenerateAsync( + using var reordered = await GenerateAsync( ReorderedAggregateSource, ManifestTestHelpers.WithManifestEnabled(), cancellationToken @@ -173,7 +173,7 @@ public async Task Generate_GivenRichContracts_ManifestCapturesIdentityVersionsAn CancellationToken cancellationToken ) { - var result = await GenerateAsync( + using var result = await GenerateAsync( RichAggregateSource, ManifestTestHelpers.WithManifestEnabled(), cancellationToken @@ -224,14 +224,14 @@ public async Task Generate_UnchangedContractsAgainstOwnBaseline_ReportsNoCompati CancellationToken cancellationToken ) { - var baselineRun = await GenerateAsync( + using var baselineRun = await GenerateAsync( RichAggregateSource, ManifestTestHelpers.WithManifestEnabled(), cancellationToken ); var baselineJson = ManifestTestHelpers.ExtractManifestJson(ManifestTestHelpers.GetManifestSource(baselineRun)); - var result = await GenerateAsync( + using var result = await GenerateAsync( RichAggregateSource, ManifestTestHelpers.WithBaseline(baselineJson), cancellationToken diff --git a/src/tools/AdminAPI.OpenAPI/Program.cs b/src/tools/AdminAPI.OpenAPI/Program.cs index ce02f83b..731aebaf 100644 --- a/src/tools/AdminAPI.OpenAPI/Program.cs +++ b/src/tools/AdminAPI.OpenAPI/Program.cs @@ -1,8 +1,9 @@ using Microsoft.AspNetCore.Hosting.Server; using Microsoft.AspNetCore.Hosting.Server.Features; -using Purview.EventSourcing.Admin.Abstractions.Models; -using Purview.EventSourcing.Admin.Abstractions.Queries; -using Purview.EventSourcing.Admin.Abstractions.Services; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Queries; +using Purview.EventSourcing.Admin.Services; + // Exports the Admin API OpenAPI document to a file so it can be committed and used to generate a typed client // (for example with NSwag). Usage: From 8d984e4a002ca6947eb930636640b5d8fca864e5 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Thu, 22 Oct 2026 08:47:09 +0100 Subject: [PATCH 02/41] chore: fabric updates --- .config/dotnet-tools.json | 2 +- .config/purview-build.json | 4 +- .editorconfig | 158 ++++++++++-------- Directory.Packages.props | 23 +-- global.json | 5 +- package.json | 2 +- .../Samples.AppHost/Samples.AppHost.csproj | 2 +- 7 files changed, 103 insertions(+), 93 deletions(-) diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index 970bffd8..1e5002f0 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -24,7 +24,7 @@ "rollForward": false }, "purview.build": { - "version": "0.6.0", + "version": "0.7.0", "commands": [ "purview-build" ], diff --git a/.config/purview-build.json b/.config/purview-build.json index 6ee8eb64..b44ad059 100644 --- a/.config/purview-build.json +++ b/.config/purview-build.json @@ -3,8 +3,8 @@ "Solution": "src/EventSourcing.slnx", "TestRoot": "src/tests", "TestPatterns": "*Tests.csproj", - "TestProjects": "*UnitTests.csproj", - "TestFilter": "/*/*/*/*[Category=Unit]" + "TestProjects": "*Tests.csproj", + "TestFilter": "/*/*/*/*" }, "PackValidation": { "RequireSymbolPackage": true, diff --git a/.editorconfig b/.editorconfig index 959b4623..b5117897 100644 --- a/.editorconfig +++ b/.editorconfig @@ -1,3 +1,23 @@ +# Purview.BuildSdk 1.1.0 - managed file, do not edit +# +# This file is written by Purview.BuildSdk and is replaced whenever the SDK version changes. The version +# on the first line is how the SDK recognises a file it owns: a .editorconfig without that marker is +# yours, and is never touched. +# +# To add your own rules, create a second .editorconfig in a subdirectory - `src/.editorconfig` is the +# usual choice - without `root = true`. EditorConfig applies the nearest file last, so your settings win +# over these, and nothing you write is lost when this file is updated. +# +# To stop the SDK updating this file, set one of: +# false keep this file as it is +# Never opt out of all bootstrapping +# false +# +# Deleting the first line also works: without the marker the SDK treats the file as yours. You then own +# every rule in it, including the ones a future SDK version would have fixed. +# +# See https://github.com/purview-dev/build-sdk#editorconfig for the full description. + root = true # Base Configuration - General Settings, File Formatting, and Naming Conventions @@ -27,8 +47,10 @@ dotnet_search_reference_assemblies = true # Nullability settings dotnet_build_property.Nullable = enable -# Enable or disable the analyzers -dotnet_analyzer_diagnostic.severity = warning +# Per-rule severity is authoritative in this file. The SDK sets AnalysisMode/AnalysisLevel as +# MSBuild properties, and the .NET SDK ignores bulk 'dotnet_analyzer_diagnostic.*' severity +# configuration whenever those properties are present. Do not re-add a bulk entry here: it +# silently does nothing and hides which severities are actually enforced. # Visual Studio XML Project Files [*.{csproj,vbproj,vcxproj,vcxproj.filters,proj,projitems,shproj}] @@ -76,23 +98,20 @@ indent_style = tab dotnet_naming_rule.non_private_static_fields_should_be_pascal_case.severity = warning dotnet_naming_rule.non_private_static_fields_should_be_pascal_case.style = non_private_static_field_style dotnet_naming_rule.non_private_static_fields_should_be_pascal_case.symbols = non_private_static_fields -dotnet_naming_rule.private_fields.severity = warning -dotnet_naming_rule.private_fields.style = camel_case_underscore -dotnet_naming_rule.private_fields.symbols = private_fields -dotnet_naming_rule.private_fields_style.severity = warning -dotnet_naming_rule.private_fields_style.style = camel_case -dotnet_naming_rule.private_fields_style.symbols = private_fields dotnet_naming_style.non_private_static_field_style.capitalization = pascal_case +# NOTE: the private-field rules that used to sit here referenced a style ('camel_case_underscore') +# and a symbol group ('private_fields') that were never defined, so they never applied. The real +# private-field rules are declared in the "StyleCop Field Naming Rules" section below. dotnet_naming_symbols.non_private_static_fields.applicable_accessibilities = public, protected, internal, protected_internal, private_protected dotnet_naming_symbols.non_private_static_fields.applicable_kinds = field dotnet_naming_symbols.non_private_static_fields.required_modifiers = static -# Constants are PascalCase +# Constants are PascalCase (field constants; local constants are locals and stay camelCase) dotnet_naming_rule.constants_should_be_pascal_case.severity = warning dotnet_naming_rule.constants_should_be_pascal_case.style = non_private_static_field_style dotnet_naming_rule.constants_should_be_pascal_case.symbols = constants dotnet_naming_style.constant_style.capitalization = pascal_case -dotnet_naming_symbols.constants.applicable_kinds = field, local +dotnet_naming_symbols.constants.applicable_kinds = field dotnet_naming_symbols.constants.required_modifiers = const # Locals and parameters are camelCase @@ -102,9 +121,7 @@ dotnet_naming_rule.locals_should_be_camel_case.severity = warning # camel_case_style - Define the camelCase style dotnet_naming_style.camel_case_style.capitalization = camel_case -dotnet_naming_style.static_field_style.required_prefix = s_ dotnet_naming_symbols.locals_and_parameters.applicable_kinds = parameter, local -dotnet_naming_symbols.static_fields.required_modifiers = static # first_upper_style - The first character must start with an upper-case character dotnet_naming_style.first_upper_style.capitalization = first_word_upper @@ -152,22 +169,22 @@ dotnet_naming_symbols.other_public_protected_fields_group.applicable_kinds = fie # StyleCop Field Naming Rules -# All constant fields must be PascalCase -dotnet_naming_rule.private_or_internal_field_should_be__fieldname.severity = warning -dotnet_naming_rule.private_or_internal_field_should_be__fieldname.style = _fieldname -dotnet_naming_rule.private_or_internal_field_should_be__fieldname.symbols = private_or_internal_field +# All non-private constant fields must be PascalCase. Private constants are owned by +# 'private_static_fields_group' below - a field must be covered by exactly one rule, otherwise the +# same violation is reported once per matching rule. dotnet_naming_rule.stylecop_constant_fields_must_be_pascal_case_rule.severity = warning dotnet_naming_rule.stylecop_constant_fields_must_be_pascal_case_rule.style = non_private_static_field_style dotnet_naming_rule.stylecop_constant_fields_must_be_pascal_case_rule.symbols = stylecop_constant_fields_group -dotnet_naming_symbols.stylecop_constant_fields_group.applicable_accessibilities = public, internal, protected_internal, protected, private_protected, private +dotnet_naming_symbols.stylecop_constant_fields_group.applicable_accessibilities = public, internal, protected_internal, protected, private_protected dotnet_naming_symbols.stylecop_constant_fields_group.applicable_kinds = field dotnet_naming_symbols.stylecop_constant_fields_group.required_modifiers = const -# All static readonly fields must be PascalCase +# All non-private static readonly fields must be PascalCase. Private static readonly fields are +# owned by 'private_static_fields_group' below (see the note on the constant rule above). dotnet_naming_rule.stylecop_static_readonly_fields_must_be_pascal_case_rule.severity = warning dotnet_naming_rule.stylecop_static_readonly_fields_must_be_pascal_case_rule.style = non_private_static_field_style dotnet_naming_rule.stylecop_static_readonly_fields_must_be_pascal_case_rule.symbols = stylecop_static_readonly_fields_group -dotnet_naming_symbols.stylecop_static_readonly_fields_group.applicable_accessibilities = public, internal, protected_internal, protected, private_protected, private +dotnet_naming_symbols.stylecop_static_readonly_fields_group.applicable_accessibilities = public, internal, protected_internal, protected, private_protected dotnet_naming_symbols.stylecop_static_readonly_fields_group.applicable_kinds = field dotnet_naming_symbols.stylecop_static_readonly_fields_group.required_modifiers = static, readonly @@ -178,12 +195,22 @@ dotnet_naming_rule.stylecop_instance_fields_must_be_private_rule.symbols = style dotnet_naming_symbols.stylecop_fields_must_be_private_group.applicable_accessibilities = public, internal, protected_internal, protected, private_protected dotnet_naming_symbols.stylecop_fields_must_be_private_group.applicable_kinds = field -# Private fields must be camelCase -dotnet_naming_rule.stylecop_private_fields_must_be_camel_case_rule.severity = warning -dotnet_naming_rule.stylecop_private_fields_must_be_camel_case_rule.style = camel_case_style -dotnet_naming_rule.stylecop_private_fields_must_be_camel_case_rule.symbols = stylecop_private_fields_group -dotnet_naming_symbols.stylecop_private_fields_group.applicable_accessibilities = private -dotnet_naming_symbols.stylecop_private_fields_group.applicable_kinds = field +# Private static fields are PascalCase: they are type-level state and are never qualified with 'this.' +dotnet_naming_rule.private_static_fields_must_be_pascal_case_rule.severity = warning +dotnet_naming_rule.private_static_fields_must_be_pascal_case_rule.style = non_private_static_field_style +dotnet_naming_rule.private_static_fields_must_be_pascal_case_rule.symbols = private_static_fields_group +dotnet_naming_symbols.private_static_fields_group.applicable_accessibilities = private +dotnet_naming_symbols.private_static_fields_group.applicable_kinds = field +dotnet_naming_symbols.private_static_fields_group.required_modifiers = static + +# Private instance fields must be camelCase with a leading underscore: '_name', never 'name'. The +# prefix keeps field access unambiguous (so the noisy 'this.' qualifier is never needed) and keeps +# fields distinguishable from locals and parameters. +dotnet_naming_rule.private_instance_fields_must_be_camel_case_with_underscore_prefix.severity = warning +dotnet_naming_rule.private_instance_fields_must_be_camel_case_with_underscore_prefix.style = camel_case_underscore_style +dotnet_naming_rule.private_instance_fields_must_be_camel_case_with_underscore_prefix.symbols = private_instance_fields_group +dotnet_naming_symbols.private_instance_fields_group.applicable_accessibilities = private +dotnet_naming_symbols.private_instance_fields_group.applicable_kinds = field # Local variables must be camelCase dotnet_naming_rule.stylecop_local_fields_must_be_camel_case_rule.severity = silent @@ -232,25 +259,14 @@ dotnet_naming_style.type_parameter_style.required_prefix = T dotnet_naming_symbols.type_parameter_symbol.applicable_accessibilities = * dotnet_naming_symbols.type_parameter_symbol.applicable_kinds = type_parameter -# Instance fields are camelCase and start with _ -dotnet_naming_rule.camel_case_for_private_internal_fields.severity = suggestion -dotnet_naming_rule.camel_case_for_private_internal_fields.style = camel_case_underscore_style -dotnet_naming_rule.camel_case_for_private_internal_fields.symbols = private_internal_fields -dotnet_naming_rule.instance_fields_should_be_camel_case.severity = suggestion -dotnet_naming_rule.instance_fields_should_be_camel_case.style = camel_case_underscore_style -dotnet_naming_rule.instance_fields_should_be_camel_case.symbols = instance_fields +# Naming style shared by the private-field rules: camelCase with a required '_' prefix. dotnet_naming_style.camel_case_underscore_style.capitalization = camel_case dotnet_naming_style.camel_case_underscore_style.required_prefix = _ -dotnet_naming_style.instance_field_style.capitalization = camel_case -dotnet_naming_style.instance_field_style.required_prefix = _ -dotnet_naming_symbols.instance_fields.applicable_kinds = field -dotnet_naming_symbols.private_internal_fields.applicable_accessibilities = private, internal -dotnet_naming_symbols.private_internal_fields.applicable_kinds = field # Local functions are PascalCase dotnet_naming_rule.local_functions_should_be_pascal_case.severity = warning -dotnet_naming_rule.local_functions_should_be_pascal_case.style = non_private_static_field_style -dotnet_naming_rule.local_functions_should_be_pascal_case.symbols = all_members +dotnet_naming_rule.local_functions_should_be_pascal_case.style = local_function_style +dotnet_naming_rule.local_functions_should_be_pascal_case.symbols = local_functions dotnet_naming_style.local_function_style.capitalization = pascal_case dotnet_naming_symbols.local_functions.applicable_kinds = local_function @@ -264,12 +280,10 @@ dotnet_style_qualification_for_property = false:silent dotnet_style_operator_placement_when_wrapping = end_of_line # Naming styles -dotnet_naming_rule.interface_should_be_begins_with_i.severity = warning -dotnet_naming_rule.interface_should_be_begins_with_i.style = prefix_interface_with_i_style -dotnet_naming_rule.interface_should_be_begins_with_i.symbols = interface -dotnet_naming_rule.types_should_be_pascal_case.severity = warning -dotnet_naming_rule.types_should_be_pascal_case.style = non_private_static_field_style -dotnet_naming_rule.types_should_be_pascal_case.symbols = types +# NOTE: a 'types_should_be_pascal_case' rule (symbol group 'types') and an +# 'interface_should_be_begins_with_i' rule (symbol group 'interface') used to sit here, but neither +# symbol group was ever defined, so neither rule applied. Types are covered by 'element_rule' and +# interfaces by 'interface_rule' above. # By default, name items with PascalCase dotnet_naming_rule.non_field_members_should_be_pascal_case.severity = warning @@ -278,7 +292,6 @@ dotnet_naming_rule.non_field_members_should_be_pascal_case.symbols = non_field_m # pascal_case_style - Define the PascalCase style dotnet_naming_style.pascal_case_style.capitalization = pascal_case -dotnet_naming_symbols.all_members.applicable_kinds = * # Symbol specifications dotnet_naming_symbols.non_field_members.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected @@ -286,7 +299,6 @@ dotnet_naming_symbols.non_field_members.applicable_kinds = property, event, meth dotnet_naming_symbols.non_field_members.required_modifiers = * # Naming styles -dotnet_naming_style._fieldname.capitalization = camel_case dotnet_naming_style.begins_with_i.capitalization = pascal_case dotnet_naming_style.begins_with_i.required_prefix = I dotnet_naming_style.begins_with_i.required_suffix = @@ -314,9 +326,11 @@ dotnet_code_quality.prefer_const = true dotnet_code_quality.prefer_inferred_anonymous_type_member_names = true dotnet_code_quality.prefer_inferred_tuple_names = true dotnet_code_quality.prefer_readonly = true -dotnet_code_quality.require_accessibility_modifiers = true +# The real modifier policy is 'dotnet_style_require_accessibility_modifiers' (declared under +# "Modifier preferences" below). The 'require_accessibility_modifiers' and +# 'require_explicit_visibility' entries that used to live here are not .NET analyzer options: +# declaring them only pretended to enforce a policy that was never applied, so they were removed. dotnet_code_quality.require_explicit_type_arguments = true -dotnet_code_quality.require_explicit_visibility = true dotnet_code_quality.require_variable_declaration_for_explicit_type = false dotnet_code_quality_unused_parameters = all:warning dotnet_enable_roslyn_analyzers = true @@ -366,12 +380,8 @@ dotnet_style_require_accessibility_modifiers = omit_if_default:warning # Code-block preferences csharp_prefer_braces = when_multiline:suggestion csharp_prefer_simple_using_statement = false:silent -csharp_prefer_system_threading_lock = true dotnet_style_prefer_collection_expression = true:suggestion -# Enable foreach explicit cast preference -dotnet_style_prefer_foreach_explicit_cast_in_source = when_strongly_typed:warning - # Prefer System.Threading.Lock csharp_prefer_system_threading_lock = true:warning @@ -503,7 +513,7 @@ dotnet_style_prefer_auto_properties = true:warning dotnet_style_prefer_compound_assignment = true:warning dotnet_style_prefer_conditional_expression_over_assignment = true:suggestion dotnet_style_prefer_conditional_expression_over_return = true:suggestion -dotnet_style_prefer_foreach_explicit_cast_in_source = when_strongly_typed +dotnet_style_prefer_foreach_explicit_cast_in_source = when_strongly_typed:warning dotnet_style_prefer_inferred_anonymous_type_member_names = true:warning dotnet_style_prefer_inferred_tuple_names = true:warning dotnet_style_prefer_simplified_boolean_expressions = false:silent @@ -587,10 +597,14 @@ dotnet_diagnostic.CA1030.severity = suggestion dotnet_diagnostic.CA1031.severity = error # Implement standard exception constructors -dotnet_diagnostic.CA1032.severity = suggestion +# Raised to warning: the public API surface of exceptions is part of the accessibility policy and +# must not be invisible to command-line builds. +dotnet_diagnostic.CA1032.severity = warning # Interface methods should be callable by child types -dotnet_diagnostic.CA1033.severity = suggestion +# Raised to warning: explicit interface implementations that hide the member from derived types are +# an accessibility problem, not a style preference. +dotnet_diagnostic.CA1033.severity = warning # Nested types should not be visible dotnet_diagnostic.CA1034.severity = error @@ -599,7 +613,9 @@ dotnet_diagnostic.CA1034.severity = error dotnet_diagnostic.CA1036.severity = suggestion # Avoid empty interfaces -dotnet_diagnostic.CA1040.severity = suggestion +# Raised to warning: empty interfaces are unenforceable contracts and were previously invisible to +# command-line builds. +dotnet_diagnostic.CA1040.severity = warning # Provide ObsoleteAttribute message dotnet_diagnostic.CA1041.severity = warning @@ -794,7 +810,9 @@ dotnet_diagnostic.CA1513.severity = warning dotnet_diagnostic.CA1514.severity = warning # Consider making public types internal -dotnet_diagnostic.CA1515.severity = suggestion +# Reported as a real build warning (not a suggestion) so accessibility hygiene cannot be ignored: +# a public type in an application or test assembly should be made internal rather than suppressed. +dotnet_diagnostic.CA1515.severity = warning # Naming Rules (CA1700-CA1727 and IDE0130) # Naming rules support adherence to the naming conventions of the .NET design guidelines @@ -973,8 +991,9 @@ dotnet_diagnostic.CA1845.severity = error # Prefer AsSpan over Substring dotnet_diagnostic.CA1846.severity = error -dotnet_diagnostic.ignore_internalsvisibleto = true -dotnet_diagnostic.CA1852.ignore_internalsvisibleto = true +# CA1852 (seal internal types) is intentionally not suppressed for internal types that are exposed +# to other assemblies through InternalsVisibleTo: those types must still be sealed. The blanket +# suppression that used to sit here relied on a malformed key, so it never even applied. # Unsafe DataSet or DataTable in serializable type can be vulnerable to remote code execution attacks dotnet_diagnostic.CA2352.severity = error @@ -1319,8 +1338,9 @@ dotnet_diagnostic.IDE0038.severity = warning # Use local function instead of lambda dotnet_diagnostic.IDE0039.severity = suggestion -# Add accessibility modifiers -dotnet_diagnostic.IDE0040.severity = error +# IDE0040 is declared exactly once, in the "Accessibility modifiers" section above. A second entry +# here used to override that value (later entries win), which made the effective modifier policy +# ambiguous and let repos believe the rule had been turned off. # Use is null check dotnet_diagnostic.IDE0041.severity = suggestion @@ -1557,8 +1577,9 @@ dotnet_diagnostic.IDE0380.severity = warning # Remove unnecessary suppression (null-forgiving operator) dotnet_diagnostic.IDE0370.severity = warning -# Naming rule violation -dotnet_diagnostic.IDE1006.severity = silent +# Naming rule violation - must stay visible: the field-naming policy is only enforced when this +# diagnostic is reported, because naming rules without their own severity inherit this one. +dotnet_diagnostic.IDE1006.severity = warning # Embedded statements must be on their own line dotnet_diagnostic.IDE2001.severity = warning @@ -2638,7 +2659,7 @@ trim_trailing_whitespace = false # If it's a settings, model, dto, etc file, ignore the 'properties' cannot have arrays # and other annoying rules - the following section is duplicated -[**/*{ValueObjects,Settings,Options,Model,Models,DTO,Entity,Response,Request}.{cs,vb},] +[**/*{ValueObjects,Settings,Options,Model,Models,DTO,Entity,Response,Request}{.Nav,}.{cs,vb}] dotnet_diagnostic.CA1002.severity = none dotnet_diagnostic.CA1024.severity = none dotnet_diagnostic.CA1056.severity = none @@ -2671,17 +2692,14 @@ dotnet_diagnostic.PDS0004.severity = none [**/Extensions/**.{cs,vb}] # Files under the Extensions/ namespace-reset convention must not force developers to add pragmas; -# suppress the namespace-conflict diagnostics that arise from declaring framework-style namespaces. +# suppress only the namespace-conflict diagnostics that arise from declaring framework-style +# namespaces. Accessibility/design rules (for example CA1034) are deliberately not suppressed here. dotnet_diagnostic.IDE0130.severity = none -dotnet_diagnostic.CA1034.severity = none dotnet_diagnostic.CA1724.severity = none dotnet_diagnostic.CS0436.severity = none dotnet_diagnostic.CS1591.severity = none dotnet_diagnostic.IDE0005.severity = none -[**/{Extension,Extensions}.{cs,vb}] -dotnet_diagnostic.CA1034.severity = none - [**/Generated/**/*.{cs,vb}] generated_code = true dotnet_diagnostic.CS8602.severity = none diff --git a/Directory.Packages.props b/Directory.Packages.props index 53c8ca92..7598d854 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -1,10 +1,5 @@ - - true - true - - @@ -12,18 +7,18 @@ 5.9.0 5.9.0 - 1.75.0 - 1.1.1 - 1.1.0 - 2.2.0 - 5.0.4 - 1.0.1 - 13.5.3.11 + 1.76.0 + 1.2.0 + 1.2.0 + 2.3.0 + 5.0.5 + 1.0.2 + 13.6.0-preview.1 4.16.0 0.14.0 10.0.13 - 13.6.1 - 1.20.0 + 13.6.3 + 1.20.1 10.11.0 diff --git a/global.json b/global.json index 3015eba5..025f0be0 100644 --- a/global.json +++ b/global.json @@ -1,9 +1,6 @@ { - "sdk": { - "allowPrerelease": false - }, "msbuild-sdks": { - "Purview.BuildSdk": "1.0.7" + "Purview.BuildSdk": "1.1.0" }, "test": { "runner": "Microsoft.Testing.Platform" diff --git a/package.json b/package.json index 2d99a5ff..ee4da1d6 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "purview-event-sourcing", + "name": "event-sourcing", "version": "2.0.0-prerelease.39", "license": "MIT", "author": { diff --git a/src/src/Samples.AppHost/Samples.AppHost.csproj b/src/src/Samples.AppHost/Samples.AppHost.csproj index c89472e8..05e684e7 100644 --- a/src/src/Samples.AppHost/Samples.AppHost.csproj +++ b/src/src/Samples.AppHost/Samples.AppHost.csproj @@ -1,4 +1,4 @@ - + Date: Thu, 22 Oct 2026 20:00:09 +0100 Subject: [PATCH 03/41] chore: updated latest purview-libs --- .agents/agents/sdk-consumer-setup.md | 34 --- ...source-generator-framework-writer.agent.md | 79 ------- .agents/agents/test-author-writer.agent.md | 50 ---- ...odernize-test-to-codequery-tunit.prompt.md | 48 ---- ...r-source-generator-to-codewriter.prompt.md | 52 ----- .../prompts/sdk-diagnose-agent-folder-copy.md | 26 --- .../aspire-apphost-to-resourcekit/.gitignore | 8 - .agents/skills/dotnet-tunit/SKILL.md | 28 --- .../skills/git-conventional-commits/SKILL.md | 16 -- .agents/skills/lefthook-integration/SKILL.md | 16 -- .../project-placement-defaults/.gitignore | 8 - .../sdk-configuration-reference/.gitignore | 8 - .../.gitignore | 8 - .../.gitignore | 8 - .../source-generator-testing/.gitignore | 8 - .../.gitignore | 8 - .../.gitignore | 8 - .../.gitignore | 8 - .../skills/tunit-test-authoring/.gitignore | 8 - .agents/skills/tunit-test-authoring/SKILL.md | 214 ------------------ .agents/skills/tunit-test-runner/SKILL.md | 108 --------- .config/dotnet-tools.json | 2 +- Directory.Packages.props | 4 +- global.json | 5 + src/Directory.Build.props | 8 +- .../AzureStorageAdminEventQueryService.cs | 2 +- .../AzureStorageAdminProjectionService.cs | 6 +- .../MongoDbAdminEventQueryService.cs | 11 +- .../MongoDbAdminProjectionService.cs | 7 +- .../PostgresAdminEventQueryService.cs | 13 +- .../PostgresAdminProjectionService.cs | 8 +- .../SqlServerAdminEventQueryService.cs | 2 +- .../SqlServerAdminProjectionService.cs | 6 +- .../TableEventStore.SaveOperation.cs | 26 +-- ...DbClient.CosmosSystemTextJsonSerializer.cs | 6 +- .../EFSnapshotShapeAnalyzer.cs | 2 +- .../EFSourceGenerator.cs | 4 +- .../EventSourcing/Aggregates/AggregateBase.cs | 24 +- .../Pages/Customer/Catalog/Order.cshtml.cs | 6 +- src/src/Samples.Web/Samples.Web.csproj | 2 +- .../Common/EventContractComparison.cs | 34 +-- .../Common/PreCompilationMarker.cs | 4 +- .../Common/SourceGenLibrary.cs | 8 +- .../Generators/AggregateSourceGenerator.cs | 6 +- .../Api/AdminApiEndpointTests.cs | 16 +- .../Api/AdminOperationalEndpointsTests.cs | 10 +- .../EFOpaqueAttribute.cs | 3 + .../Snapshots/PostgresSnapshotClientTests.cs | 4 +- .../Snapshots/SqlServerSnapshotClientTests.cs | 4 + 49 files changed, 116 insertions(+), 868 deletions(-) delete mode 100644 .agents/agents/sdk-consumer-setup.md delete mode 100644 .agents/agents/source-generator-framework-writer.agent.md delete mode 100644 .agents/agents/test-author-writer.agent.md delete mode 100644 .agents/prompts/modernize-test-to-codequery-tunit.prompt.md delete mode 100644 .agents/prompts/refactor-source-generator-to-codewriter.prompt.md delete mode 100644 .agents/prompts/sdk-diagnose-agent-folder-copy.md delete mode 100644 .agents/skills/aspire-apphost-to-resourcekit/.gitignore delete mode 100644 .agents/skills/dotnet-tunit/SKILL.md delete mode 100644 .agents/skills/git-conventional-commits/SKILL.md delete mode 100644 .agents/skills/lefthook-integration/SKILL.md delete mode 100644 .agents/skills/project-placement-defaults/.gitignore delete mode 100644 .agents/skills/sdk-configuration-reference/.gitignore delete mode 100644 .agents/skills/sdk-project-behavior-and-detection/.gitignore delete mode 100644 .agents/skills/source-generator-codewriter-modernization/.gitignore delete mode 100644 .agents/skills/source-generator-testing/.gitignore delete mode 100644 .agents/skills/telemetry-sourcegenerator-design/.gitignore delete mode 100644 .agents/skills/telemetry-sourcegenerator-migration/.gitignore delete mode 100644 .agents/skills/telemetry-sourcegenerator-quickstart/.gitignore delete mode 100644 .agents/skills/tunit-test-authoring/.gitignore delete mode 100644 .agents/skills/tunit-test-authoring/SKILL.md delete mode 100644 .agents/skills/tunit-test-runner/SKILL.md diff --git a/.agents/agents/sdk-consumer-setup.md b/.agents/agents/sdk-consumer-setup.md deleted file mode 100644 index 8e5066c3..00000000 --- a/.agents/agents/sdk-consumer-setup.md +++ /dev/null @@ -1,34 +0,0 @@ -# sdk-consumer-setup (generic agent spec) - -## Goal - -Help a consuming repository adopt or troubleshoot `Purview.BuildSdk` correctly, without breaking existing build behaviour. - -## Workflow - -1. Confirm the SDK is imported in `Directory.Build.props`/`Directory.Build.targets` via - `` and the matching `Sdk.targets` import. -2. Check pre-import bootstrap properties are set **before** the `Sdk.props` import when they must affect - evaluation: `NamespacePrefix`, `UsePackageJsonVersion`, `RootPackageJson`. -3. If version resolution looks wrong, verify `package.json` discovery: explicit `RootPackageJson`, then CI - variables, `.git` root, or a nearby `package.json`. `UsePackageJsonVersion=Strict` fails fast instead of - silently skipping resolution. -4. If the bundled `.agents/**` content isn't appearing in the repo root, check `EnableAgentFolderInPackage` - (default `true`) and `AgentPackDestinationFolder` (default `.agents`) — the copy runs before build via - `EnsureAgentFolderInPackageTarget`. -5. For test-framework or project-shape questions, confirm the project follows repo naming and placement - conventions the SDK expects, rather than introducing bespoke structure. -6. Re-run `dotnet build` (or the repo's canonical build command) after each configuration change to confirm - the fix. - -## Constraints - -- Prefer minimal, targeted property changes over broad `Directory.Build.props` rewrites. -- Do not disable `PurviewAutoSdkPack` or `EnableAgentFolderInPackage` unless the consumer explicitly asks to - opt out. -- Do not duplicate SDK-managed properties in individual project files unless the scenario is intentionally - project-specific. - -## Related skill - -See `../skills/sdk-configuration-reference/SKILL.md` for the full property reference. diff --git a/.agents/agents/source-generator-framework-writer.agent.md b/.agents/agents/source-generator-framework-writer.agent.md deleted file mode 100644 index 65f5bd03..00000000 --- a/.agents/agents/source-generator-framework-writer.agent.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -name: Source Generator Framework Writer -description: "Specialist for Purview.SourceGeneratorFramework generation code using CodeWriter and XmlCodeWriter-style XML doc extensions; ideal for creating or refactoring generator emitters." -tools: - [ - "search/codebase", - "edit/editFiles", - "search", - "execute/getTerminalOutput", - "execute/runInTerminal", - "read/terminalLastCommand", - "read/terminalSelection", - "execute/createAndRunTask", - "execute/runTask", - "read/getTaskOutput", - "vscodeTasks/createAndRunTask", - "vscodeTasks/getTaskOutput", - "vscodeTasks/runTask", - ] ---- - -You are a specialist for `Purview.SourceGeneratorFramework` emitter authoring. - -## Primary objective - -Produce clear, deterministic, maintainable source-generator emission code using `CodeWriter` and XML extension helpers from `XmlCommentWriter`. - -## Background knowledge - -Before changing any source generator, analyser, or CodeWriter-related code, load and apply the `source-generator-codewriter-modernization` skill. It contains the full source-generator, analyser, and CodeWriter best-practices guidance for this framework, including incremental pipeline design, value equality, deterministic output, and Roslyn version compatibility. - -The most important rules are: - -- **Analyser for validation; generator for generation.** -- **Syntax for syntax, symbols for declarations, operations for executable semantics.** -- **Use `ForAttributeWithMetadataName` whenever possible.** -- **Remove `ISymbol`, `Compilation`, `SemanticModel`, `IOperation`, `SyntaxTree`, `SyntaxNode`, and `Location` from incremental pipeline models as early as possible.** -- **Pipeline models must be immutable and value-equatable; use `EquatableArray` for collections.** -- **Avoid `Collect()` until global knowledge is genuinely required.** -- **Never combine `CompilationProvider` into the pipeline merely because it is convenient.** -- **Generate deterministic output and stable hint names.** -- **Test incrementally, not just generated text.** -- **Compile against the oldest Roslyn API version containing the functionality you need.** -- **Create `CodeWriter` inside the output callback and pass it to helpers within that callback; never create it earlier in the pipeline or store it in incremental provider state or custom contexts.** - -## Available resources - -- `skills/source-generator-codewriter-modernization/SKILL.md` — source-generator, analyser, and CodeWriter best practices for this framework. -- `prompts/refactor-source-generator-to-codewriter.prompt.md` — prompt template for legacy-emitter refactor tasks. - -## Must-follow rules - -1. Load and apply the `source-generator-codewriter-modernization` skill. -2. Prefer structured declaration APIs over handwritten declaration strings. -3. Prefer XML helper extensions (`XmlSummary`, `XmlParam`, etc.) over raw `///` output. -4. Create `CodeWriter` inside each output callback; never create it earlier in the pipeline or cache it in incremental provider state or custom contexts. -5. Preserve semantic behavior while modernizing implementation style. -6. Keep edits minimal and localized to emitter concerns. - -## Refactoring posture - -When modernizing legacy code: - -- Replace manual indentation/braces with scope APIs. -- Replace signature text with declaration option records. -- Replace ad-hoc XML tags with helper APIs. -- Preserve diagnostics and emitted symbol names. - -## Quality gates - -- Build/tests pass for impacted projects. -- No scope leaks when materializing generated source. -- Generated artifacts remain deterministic and reviewable. - -## Skill routing - -When relevant, first load and apply: - -- `source-generator-codewriter-modernization` diff --git a/.agents/agents/test-author-writer.agent.md b/.agents/agents/test-author-writer.agent.md deleted file mode 100644 index fb5fb87d..00000000 --- a/.agents/agents/test-author-writer.agent.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -name: Test Author Writer -description: "Specialist for Purview.SourceGeneratorFramework test suites — writing, fixing, and modernising TUnit tests for generators, diagnostic analyzers, code fixes, and refactorings, and for adding stage-by-stage incremental cache tests." -tools: - [ - "search/codebase", - "edit/editFiles", - "search", - "execute/getTerminalOutput", - "execute/runInTerminal", - "read/terminalLastCommand", - "read/terminalSelection", - "execute/createAndRunTask", - "execute/runTask", - "read/getTaskOutput", - "vscodeTasks/createAndRunTask", - "vscodeTasks/getTaskOutput", - "vscodeTasks/runTask", - ] ---- - -You are a specialist for `Purview.SourceGeneratorFramework` test authoring. - -## Primary objective - -Produce correct, maintainable TUnit tests for source generators, diagnostic analyzers, code fix -providers, and refactoring providers, and prove incremental pipelines cache correctly. - -## Background knowledge - -Before writing or changing any test, load and apply the `source-generator-testing` skill (runner layer, -result types, `CodeQuery`, options, cache testing) and the `tunit-test-authoring` skill (base classes, -methods, assertion extensions, modernisation checklist). For source-generator emission work, also load the -`source-generator-codewriter-modernization` skill. - -Key rules: - -- Pick the base class by the Roslyn component type: generator → `TUnitSourceGeneratorTestBase` + - `GenerateAsync`; analyzer → `TUnitDiagnosticAnalyzerTestBase` + `AnalyzeAsync`; code fix → - `TUnitCodeFixTestBase` + `ApplyCodeFixAsync`/`ApplyFixAllAsync`; refactor → - `TUnitRefactoringTestBase` + `RefactorAsync`. -- Prefer `CodeQuery` (`result.Generated()` / `result.FixedCode()` with `Get/Has/TryGet`) over - raw-string assertions. -- Prefer the terminal assertion extensions (`HasGeneratedMethod`, `HasGeneratedClass`, …) that return - syntax nodes. -- Derive a `SourceGeneratorTestOptions` record that seeds namespaces and additional assemblies. -- For incremental pipelines, add a stage-by-stage cache test with `RunIncrementalAsync` / - `GenerateIncrementalAsync`, asserting `New` on first run and `Cached`/`Unchanged` on an identical rerun, - and `Modified` only on the stages whose inputs changed. -- Keep generated-output assertions deterministic (no timestamps); enable CodeWriter scope validation. \ No newline at end of file diff --git a/.agents/prompts/modernize-test-to-codequery-tunit.prompt.md b/.agents/prompts/modernize-test-to-codequery-tunit.prompt.md deleted file mode 100644 index cf463ceb..00000000 --- a/.agents/prompts/modernize-test-to-codequery-tunit.prompt.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -agent: ask -description: "Modernise a Roslyn test suite to use CodeQuery + TUnit assertion extensions, and add a stage-by-stage incremental cache test." ---- - -You are modernising tests in this repository. Apply the guidance from the `source-generator-testing` and -`tunit-test-authoring` skills for picking the right base class, querying generated code with `CodeQuery`, -and asserting incremental caching. - -## Inputs - -- Target test file(s): `${input:targetFiles:Path(s) to test file(s)}` -- Roslyn component under test: `${input:componentType:generator|analyzer|codefix|refactor}` (inferred if blank) -- Generator/analyzer/code-fix/refactor type name: `${input:componentName:Component type name}` - -## Task - -Modernise each test so it uses the framework's `CodeQuery` syntax-lookup API and the TUnit assertion -extensions, and add a stage-by-stage cache test proving each incremental pipeline layer caches correctly. - -### Requirements - -1. Choose the correct base class and method for the component type: - - Generator → `TUnitSourceGeneratorTestBase` → `GenerateAsync`. - - Analyzer → `TUnitDiagnosticAnalyzerTestBase` → `AnalyzeAsync`. - - Code fix → `TUnitCodeFixTestBase` → `ApplyCodeFixAsync` / `ApplyFixAllAsync`. - - Refactor → `TUnitRefactoringTestBase` → `RefactorAsync`. -2. Replace `GetGeneratedTree(...)` + `string.Contains(...)` assertions with `CodeQuery` - (`result.Generated().Get/Has/TryGet…`) and the terminal assertion extensions - (`await Assert.That(result).HasGeneratedMethod/Class/Property/Field/SyntaxTree(…)`) that return the node. -3. Replace signature string checks with `TypeReference` parameter/return-type matching. -4. Ensure options come from a derived `SourceGeneratorTestOptions` record seeding the required namespaces - and additional assemblies; remove per-test duplication. -5. Add an incremental cache test using `RunIncrementalAsync` (or `GenerateIncrementalAsync` on the TUnit - base) with the four scenarios from the skills' "Incremental cache testing" sections - (`ServiceRegistrationCacheTests` / `IncrementalPipelineCacheTests` are the reference pattern): - - first run → every framework stage `New`; - - identical rerun (`RunIncrementalAsync(sources, …)` runs the same source twice) → framework stages - `Cached`/`Unchanged`; - - source-only change → `ForAttribute_*` `Modified`, property/config stages stay `Cached`; - - property-only change (`new IncrementalRunInput(sources, [("build_property.X", "value")])`) → - `GetMSBuildPropertyValue_*`/`GetGenerationConfiguration`/`GetGenerationContext_*` `Modified`, - `ForAttribute_*` stays `Cached`. - Use the `StepReasons(IncrementalCacheRun)` flattening helper; if the generator depends on its own - post-init output, assert on the framework-named stages rather than every tracked step. -6. Keep changes minimal and behavior equivalent; do not reformat unrelated tests. - -Verify by building the test project and running its suite before finishing. \ No newline at end of file diff --git a/.agents/prompts/refactor-source-generator-to-codewriter.prompt.md b/.agents/prompts/refactor-source-generator-to-codewriter.prompt.md deleted file mode 100644 index e230d224..00000000 --- a/.agents/prompts/refactor-source-generator-to-codewriter.prompt.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -agent: ask -description: "Refactor a legacy source generator emitter from string/StringBuilder to CodeWriter + XmlCodeWriter-style XML extensions with behavior parity." ---- - -You are modernizing a source generator implementation in this repository. Apply the guidance from the `source-generator-codewriter-modernization` skill for incremental pipelines, value equality, deterministic output, and CodeWriter scope safety. - -## Inputs - -- Target file(s): `${input:targetFiles:Path(s) to emitter file(s)}` -- Generator type name: `${input:generatorName:Generator class name}` -- Generator version: `${input:generatorVersion:Version string (for generated attributes/header)}` -- Keep output byte-identical where possible: `${input:preserveFormatting:true|false}` - -## Task - -Refactor the selected legacy emitter implementation from manual `string` / `StringBuilder` output construction to `CodeWriter` and XML documentation extension helpers from `XmlCommentWriter` (XmlCodeWriter-style API usage). - -### Requirements - -1. Use structured declaration APIs where applicable: - - `Class/Struct/RecordClass/Interface/Enum` - - `Method`, `Property`, `Field`, `Constructor` -2. Use XML helper extensions instead of raw `///` composition: - - `XmlSummary`, `XmlParam`, `XmlReturn`, `XmlRemarks`, `XmlCode` or `XmlCodeBlock` -3. Use `TypeReference` when type text becomes complex (nullability, generics, arrays). -4. Ensure writer lifetime is output-scoped (`generationContext.CreateCodeWriter()` inside callback). -5. Preserve behavior, diagnostics, and generated names. -6. Keep changes minimal and focused; do not reformat unrelated logic. - -### Migration strategy - -- Identify emitter phases: header, namespace, type declarations, member declarations. -- Replace indentation/braces with scoped APIs. -- Replace signature strings with declaration options. -- Replace XML comments with XmlCommentWriter extension methods. -- Keep semantic equivalence; call out any intentional deltas. - -### Verification - -- Run relevant tests. -- Confirm generated files still compile. -- Confirm no `CodeWriter` scope leaks (`OpenScopeCount == 0` when materialized). - -### Output format - -Return: - -1. Files changed -2. Why each change was necessary -3. Risks/behavior differences (if any) -4. Verification performed diff --git a/.agents/prompts/sdk-diagnose-agent-folder-copy.md b/.agents/prompts/sdk-diagnose-agent-folder-copy.md deleted file mode 100644 index 85ad4445..00000000 --- a/.agents/prompts/sdk-diagnose-agent-folder-copy.md +++ /dev/null @@ -1,26 +0,0 @@ -# sdk-diagnose-agent-folder-copy (generic prompt spec) - -Diagnose why the bundled `.agents/**` folder from `Purview.BuildSdk` did not appear at the expected -destination in a consuming repository. - -## Required behaviour - -1. Confirm the NuGet package actually contains `.agents/**` content (inspect the `.nupkg` if available). -2. Confirm the consuming project is packable/buildable and imports the SDK via - `Sdk.props`/`Sdk.targets`, since the copy runs in `EnsureAgentFolderInPackageTarget` before build. -3. Check `EnableAgentFolderInPackage` is not set to `false` anywhere in the build (project file, - `Directory.Build.props`, or command-line `-p:` overrides). -4. Confirm the destination folder: default is `.agents` at the repo root, overridable per-build with - `-p:AgentPackDestinationFolder=`. -5. Verify repo-root discovery succeeded: explicit `RepoRoot`, then a nearby `AGENTS.md`, then source-control - root metadata. -6. Re-run the build and confirm the destination folder now contains the copied files (including the - generated `.gitignore` for skill/prompt/agent subfolders). - -## Suggested output - -- A short root-cause explanation (missing import, disabled flag, wrong destination override, or repo-root - discovery miss). -- The exact command used to reproduce/verify the fix (for example - `dotnet build -p:AgentPackDestinationFolder=`). -- Confirmation that the expected files exist at the resolved destination path. diff --git a/.agents/skills/aspire-apphost-to-resourcekit/.gitignore b/.agents/skills/aspire-apphost-to-resourcekit/.gitignore deleted file mode 100644 index 27997545..00000000 --- a/.agents/skills/aspire-apphost-to-resourcekit/.gitignore +++ /dev/null @@ -1,8 +0,0 @@ -# Ignore all files -* - -# Don't ignore directories, so Git can traverse them -!*/ - -# Keep this file -!.gitignore \ No newline at end of file diff --git a/.agents/skills/dotnet-tunit/SKILL.md b/.agents/skills/dotnet-tunit/SKILL.md deleted file mode 100644 index 4a9dec42..00000000 --- a/.agents/skills/dotnet-tunit/SKILL.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -name: dotnet-tunit -description: Use .NET with TUnit-specific test conventions. -category: dotnet -roles: - - dotnet - - dotnet-tunit - - coding -tags: - - dotnet - - csharp - - tunit - - tests ---- - -# dotnet-tunit Skill - -Use this skill for .NET repositories that use TUnit. - -## Rules - -- Use `TUnit.Core`. -- Use `TUnit.Assertions`. -- Test methods must have `[Test]`. -- Assertion calls must be awaited. -- Prefer `await Assert.That(actual).IsEqualTo(expected);`. -- Do not use xUnit, NUnit, MSTest, or FluentAssertions unless explicitly requested. -- Run the relevant `dotnet test` command before completion. diff --git a/.agents/skills/git-conventional-commits/SKILL.md b/.agents/skills/git-conventional-commits/SKILL.md deleted file mode 100644 index 49aeef1a..00000000 --- a/.agents/skills/git-conventional-commits/SKILL.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -name: git-conventional-commits -description: Git workflow and conventional commit guidance. ---- - -# Git Conventional Commits Skill - -Use this skill for Git workflow and commit hygiene. - -## Rules - -- Use Conventional Commits. -- Prefer small, reviewable commits. -- Commit types include `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `build`, and `ci`. -- Do not mix unrelated changes. -- Explain validation commands before completion. diff --git a/.agents/skills/lefthook-integration/SKILL.md b/.agents/skills/lefthook-integration/SKILL.md deleted file mode 100644 index 34fe3567..00000000 --- a/.agents/skills/lefthook-integration/SKILL.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -name: lefthook-integration -description: Lefthook Git hook integration. ---- - -# lefthook-integration Skill - -Use this skill for repo-local Git hook setup. - -## Rules - -- Prefer small, fast checks in pre-commit. -- Put slower checks in pre-push. -- Do not block commits with network-dependent checks. -- Keep commands cross-platform where possible. -- Document how to install and run hooks locally. diff --git a/.agents/skills/project-placement-defaults/.gitignore b/.agents/skills/project-placement-defaults/.gitignore deleted file mode 100644 index 27997545..00000000 --- a/.agents/skills/project-placement-defaults/.gitignore +++ /dev/null @@ -1,8 +0,0 @@ -# Ignore all files -* - -# Don't ignore directories, so Git can traverse them -!*/ - -# Keep this file -!.gitignore \ No newline at end of file diff --git a/.agents/skills/sdk-configuration-reference/.gitignore b/.agents/skills/sdk-configuration-reference/.gitignore deleted file mode 100644 index 27997545..00000000 --- a/.agents/skills/sdk-configuration-reference/.gitignore +++ /dev/null @@ -1,8 +0,0 @@ -# Ignore all files -* - -# Don't ignore directories, so Git can traverse them -!*/ - -# Keep this file -!.gitignore \ No newline at end of file diff --git a/.agents/skills/sdk-project-behavior-and-detection/.gitignore b/.agents/skills/sdk-project-behavior-and-detection/.gitignore deleted file mode 100644 index 27997545..00000000 --- a/.agents/skills/sdk-project-behavior-and-detection/.gitignore +++ /dev/null @@ -1,8 +0,0 @@ -# Ignore all files -* - -# Don't ignore directories, so Git can traverse them -!*/ - -# Keep this file -!.gitignore \ No newline at end of file diff --git a/.agents/skills/source-generator-codewriter-modernization/.gitignore b/.agents/skills/source-generator-codewriter-modernization/.gitignore deleted file mode 100644 index 27997545..00000000 --- a/.agents/skills/source-generator-codewriter-modernization/.gitignore +++ /dev/null @@ -1,8 +0,0 @@ -# Ignore all files -* - -# Don't ignore directories, so Git can traverse them -!*/ - -# Keep this file -!.gitignore \ No newline at end of file diff --git a/.agents/skills/source-generator-testing/.gitignore b/.agents/skills/source-generator-testing/.gitignore deleted file mode 100644 index 27997545..00000000 --- a/.agents/skills/source-generator-testing/.gitignore +++ /dev/null @@ -1,8 +0,0 @@ -# Ignore all files -* - -# Don't ignore directories, so Git can traverse them -!*/ - -# Keep this file -!.gitignore \ No newline at end of file diff --git a/.agents/skills/telemetry-sourcegenerator-design/.gitignore b/.agents/skills/telemetry-sourcegenerator-design/.gitignore deleted file mode 100644 index 27997545..00000000 --- a/.agents/skills/telemetry-sourcegenerator-design/.gitignore +++ /dev/null @@ -1,8 +0,0 @@ -# Ignore all files -* - -# Don't ignore directories, so Git can traverse them -!*/ - -# Keep this file -!.gitignore \ No newline at end of file diff --git a/.agents/skills/telemetry-sourcegenerator-migration/.gitignore b/.agents/skills/telemetry-sourcegenerator-migration/.gitignore deleted file mode 100644 index 27997545..00000000 --- a/.agents/skills/telemetry-sourcegenerator-migration/.gitignore +++ /dev/null @@ -1,8 +0,0 @@ -# Ignore all files -* - -# Don't ignore directories, so Git can traverse them -!*/ - -# Keep this file -!.gitignore \ No newline at end of file diff --git a/.agents/skills/telemetry-sourcegenerator-quickstart/.gitignore b/.agents/skills/telemetry-sourcegenerator-quickstart/.gitignore deleted file mode 100644 index 27997545..00000000 --- a/.agents/skills/telemetry-sourcegenerator-quickstart/.gitignore +++ /dev/null @@ -1,8 +0,0 @@ -# Ignore all files -* - -# Don't ignore directories, so Git can traverse them -!*/ - -# Keep this file -!.gitignore \ No newline at end of file diff --git a/.agents/skills/tunit-test-authoring/.gitignore b/.agents/skills/tunit-test-authoring/.gitignore deleted file mode 100644 index 27997545..00000000 --- a/.agents/skills/tunit-test-authoring/.gitignore +++ /dev/null @@ -1,8 +0,0 @@ -# Ignore all files -* - -# Don't ignore directories, so Git can traverse them -!*/ - -# Keep this file -!.gitignore \ No newline at end of file diff --git a/.agents/skills/tunit-test-authoring/SKILL.md b/.agents/skills/tunit-test-authoring/SKILL.md deleted file mode 100644 index fa58cd8f..00000000 --- a/.agents/skills/tunit-test-authoring/SKILL.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -name: tunit-test-authoring -description: "Use when writing TUnit tests for source generators, diagnostic analyzers, code fixes, or refactorings in a Purview.SourceGeneratorFramework repository — choosing the correct base class and method, customising options, using the assertion extensions, and modernising existing tests." ---- - -# TUnit test authoring for Roslyn components - -Use this skill whenever a task involves authoring, fixing, or modernising **TUnit** tests for Roslyn -components built with `Purview.SourceGeneratorFramework`. It tells you which base class to derive from, -which method to call, how to customise options with an easy starting point, and how to use the TUnit -assertion extensions. For the framework-agnostic runner layer and the `CodeQuery` API, also load the -`sdk` package's `source-generator-testing` skill. - -## Base class → method matrix - -| Roslyn type | Base class | Method to call | -|---|---|---| -| `IIncrementalGenerator` / `ISourceGenerator` | `TUnitSourceGeneratorTestBase` | `GenerateAsync(source, options, ct)` | -| `DiagnosticAnalyzer` | `TUnitDiagnosticAnalyzerTestBase` | `AnalyzeAsync(source, options, ct)` | -| `CodeFixProvider` (single fix) | `TUnitCodeFixTestBase` | `ApplyCodeFixAsync(source, options, ct)` | -| `CodeFixProvider` (fix-all) | `TUnitCodeFixTestBase` | `ApplyFixAllAsync(sources, options, ct)` | -| `CodeRefactoringProvider` | `TUnitRefactoringTestBase` | `RefactorAsync(source, options, ct)` | - -For cache tests, `TUnitSourceGeneratorTestBase` also exposes `GenerateIncrementalAsync(...)`. - -Framework-agnostic equivalents (no TUnit): `SourceGeneratorTestRunner`, `DiagnosticAnalyzerTestRunner`, -`CodeFixTestRunner`, `RefactoringTestRunner`. - -## Easy starting point: derive your options record - -Create a test-options record that seeds the namespaces and assemblies your component needs, then pass it -to every test via `new MyTestOptions()`: - -```csharp -public sealed record MyGeneratorTestOptions : SourceGeneratorTestOptions -{ - public MyGeneratorTestOptions() - { - AdditionalNamespaces = AdditionalNamespaces.Add("My.Namespace"); - AdditionalAssemblyTypes = AdditionalAssemblyTypes.AddRange( - typeof(SomeDependencyType), - typeof(TypeIdentity) // framework Shared assembly, when needed - ); - DisableSourceGeneratorPropertyName = "DisableMyGenerator"; - } -} - -public class MyGeneratorTests : TUnitSourceGeneratorTestBase -{ - [Test] - public async Task GeneratesExpectedSource(CancellationToken ct) => - await GenerateAsync("...source...", ct); -} -``` - -Use the base hooks to customise per-run: `OnBeforeRun`/`OnBeforeRunAsync` (mutate sources/options, e.g. -`options.WithAdditionalSources(markerAttributeSource)`) and `OnAfterRun`/`OnAfterRunAsync`. Use -`options.Compile()` to opt into `CompileToAssembly` while preserving the derived options type. - -For code fixes/refactorings, select a specific registered action via `CodeFixTestOptions.EquivalenceKey` -or `CodeActionIndex`, and `RefactorTestOptions.Span`/`NodeSelector` (e.g. -`NodeSelector = query => query.GetMethod("M")`). - -## TUnit assertion extensions - -All assertion extensions live under `Purview.SourceGeneratorFramework.Testing.TUnit.Assertions` -(globally imported by the package's props). `Assert.That(...)` calls are terminal and **return the value** -when awaited. - -- **`CodeQueryAssertions`** — return `CodeQueryResult` (the matched node via `.Node`, plus a query - scoped to it via `.Query`): `HasGeneratedMethod` (optionally with `TypeReference[]` parameter types), - `HasGeneratedMethodReturnType`, `HasGeneratedClass` (by name or `TypeReference`/`TypeIdentity` identity), - `HasGeneratedProperty`, `HasGeneratedField`, `HasGeneratedSyntaxTree`; `HasFixedMethod` for code-fix and - refactor results. The assertions operate on a `CodeQuery` directly, so pass any query — `result.Generated()` - (generated trees), `result.Output()` (whole compilation), or `result.FixedCode()` — or use the convenience - overloads on the test result types, which query the relevant code for you. -- **Scoped member chaining** — `HasPropertyOfType(name, type)`, `HasFieldOfType(name, type)`, - `HasMethodOfType(name, TypeReference[])`, `HasConstructorOfType(TypeReference[])`, and - `HasAttributeOfType(name)` chain from a scoped `CodeQueryResult` (e.g. the result of `HasGeneratedClass`) - and return the matched member. They are named to avoid colliding with the bool `Has*` predicates in - `MemberQueryExtensions`. -- **Fluent `.And` chains** — the node-producing assertions (`HasGeneratedClass`, `HasPropertyOfType`, - `HasMethodOfType`, `HasNestedType`) move the chain onto the matched node, so further assertions can be - appended with `.And`. Node-inspection assertions — `WithAccessibility`, `WithGetterAccessibility`, - `WithSetterAccessibility`, `WithBaseType`, `WithGenericTypeParameter(s)`, `IsInNamespace`, - `IsInGlobalNamespace` — keep the node on the chain: - ```csharp - var method = await Assert.That(query) - .HasGeneratedClass("Service") - .And.HasNestedType("Builder") - .And.WithAccessibility(Accessibility.Private) - .And.HasMethodOfType("Build", []); - ``` - Generic types are matched by arity — `HasGeneratedClass(name, arity)` or a `TypeIdentity` with arity — - so `new TypeIdentity("ResourceDefinition", ns, arity: 1)` finds `ResourceDefinition` - without matching the non-generic `ResourceDefinition`. -- **Nullable expected types in tests** — use the test-only `query.MakeNullable(type)` extension (on a - `CodeQuery`). It resolves the annotation against the query's compilation and, unlike - `TypeReference.Nullable()`/`TypeIdentity.MakeNullable()`, does not trip the `PSGFR16` context-overload - suggestion, since tests have no generation context to pass. - ```csharp - CodeQueryResult method = await Assert.That(result.Generated()).HasGeneratedMethod("DoWork", [intType, nullableInt]); - CodeQueryResult cls = await Assert.That(result.Generated()).HasGeneratedClass("Service"); - await Assert.That(cls.HasProperty("Count", intType)).IsTrue(); // chained member query - await Assert.That(cls.Node.Identifier.ValueText).IsEqualTo("Service"); // direct syntax access - await Assert.That(result.FixedCode()).HasFixedMethod("DoWork"); // code-fix / refactor results - - var query = result.Generated(); - var attributeClass = await Assert.That(query).HasGeneratedClass(hostKitAttribute); - await Assert.That(attributeClass).HasPropertyOfType("Name", query.MakeNullable(TypeLibrary.System.String)); - ``` -- **`DiagnosticAssertions`** — `HasDiagnostic(descriptor|id)`, `HasDiagnostics(count)`, - `DoesNotHaveDiagnostic`, `HasNoDiagnostics`, `HasNoErrorDiagnostics` on generator/analyzer/code-fix results. -- **`TypeIdentityAssertions`** — `HasSymbol(TypeIdentity)` / `HasSymbol("Namespace.Type")`. -- **`GeneratedCodeAssertionsExtensions`** — `GeneratesCode(expected)`, `ContainsGeneratedCode(expected)` - (whitespace-flattened string comparison). - -For structural assertions (members, signatures, namespaces) prefer `result.Generated()` + -`Get/Has/TryGet` from `CodeQuery` (see `source-generator-testing`). - -## Incremental cache tests (`GenerateIncrementalAsync`) - -`TUnitSourceGeneratorTestBase` exposes `GenerateIncrementalAsync`, which mirrors `RunIncrementalAsync` but -also wires the base class hooks (`OnBeforeRun`/`OnBeforeRunAsync`) and your derived options record. Use it to -prove the pipeline caches stage-by-stage. The reference is `ServiceRegistrationCacheTests` in -`SourceGeneratorFramework.ExampleGenerator.UnitTests`; the framework-agnostic twin with a full walkthrough is -in the `source-generator-testing` skill. - -Why the tests look the way they do: - -- `GenerateIncrementalAsync([Source])` runs the **same source twice** on a single shared driver. The first - run reports every stage `New`; the second must report `Cached`/`Unchanged` for unchanged stages — that is - the core "it caches" proof. -- `GenerateIncrementalAsync([new IncrementalRunInput([Source]), new IncrementalRunInput([changed])])` runs two - **different** source sets, so a source-only change must mark `ForAttribute_*` `Modified` while - property/configuration stages stay `Cached`. -- `new IncrementalRunInput([Source], [("build_property.X", "value")])` toggles an MSBuild property for one - run only, so a property-only change must mark `GetMSBuildPropertyValue_*`/`GetGenerationConfiguration`/ - `GetGenerationContext_*` `Modified` while `ForAttribute_*` stays `Cached`. -- The `StepReasons(IncrementalCacheRun)` helper flattens each tracked step's `Outputs` into a - `ImmutableDictionary>` so assertions can address a stage - by name (see `source-generator-testing` for the helper body). -- If the generator's pipeline depends on its own post-initialization output (a self-referencing generated - attribute), Roslyn's internal `ForAttributeWithMetadataName` `Compilation` step is legitimately `Modified` - on rerun; assert on the framework-named stages (e.g. `ForAttribute_GenerateServiceAttribute`, - `GetGenerationConfiguration`, `GetGenerationContext_EmptyCapabilities`) rather than every tracked step. - -```csharp -public class ServiceRegistrationCacheTests - : TUnitSourceGeneratorTestBase -{ - const string Source = """ - namespace Test; - - [GenerateService] - public class MyService { } - """; - - [Test] - public async Task IdenticalRerun_AllStagesCached(CancellationToken cancellationToken) - { - var result = await GenerateIncrementalAsync([Source], cancellationToken: cancellationToken); - - var second = StepReasons(result.Runs[1]); - string[] frameworkStages = - [ - "GetMSBuildPropertyValue_EmitServiceRegistrationInfo", - "GetGenerationConfiguration", - "GetGenerationContext_EmptyCapabilities", - "ForAttribute_GenerateServiceAttribute", - ]; - await Assert.That( - frameworkStages.All(stage => - second.TryGetValue(stage, out var reasons) - && reasons.All(r => r is StepReason.Cached or StepReason.Unchanged))).IsTrue(); - } - - [Test] - public async Task PropertyChange_MarksPropertyStageModified_AttributeStageStaysCached(CancellationToken cancellationToken) - { - var result = await GenerateIncrementalAsync( - [ - new IncrementalRunInput([Source]), - new IncrementalRunInput([Source], [(PropertyLibrary.EmitServiceRegistrationInfo, "true")]), - ], - cancellationToken: cancellationToken); - - var second = StepReasons(result.Runs[1]); - await Assert.That(second["GetMSBuildPropertyValue_EmitServiceRegistrationInfo"]).Contains(StepReason.Modified); - await Assert.That(second["ForAttribute_GenerateServiceAttribute"].All(r => r is StepReason.Cached or StepReason.Unchanged)).IsTrue(); - } -} -``` - -Use `using StepReason = Microsoft.CodeAnalysis.IncrementalStepRunReason;` and your own stage names. - -## Modernising existing tests - -When converting legacy tests that do `result.GetGeneratedTree(...)` + `string.Contains(...)`: - -1. Replace tree-lookup + string matching with `result.Generated().GetClass/GetMethod/GetProperty(...)` and - the `Has*`/`TryGet*` family. -2. Replace signature string checks with `TypeReference` parameter/return-type matching. -3. Replace `Assert.That(text).Contains("...")` with the terminal assertion extensions that return nodes. -4. Verify options use a derived record (namespaces + assemblies) rather than repeating `AdditionalNamespaces` - per test. -5. Add a stage-by-stage cache test if the component has an incremental pipeline — first run `New`, - identical rerun `Cached`/`Unchanged`, and targeted changes mark only the affected stage `Modified`. - Use the inlined examples in this skill and in `source-generator-testing`'s "Incremental cache testing" - section, swapping in your own generator and stage names. - -## License - -This project is licensed under the MIT license. \ No newline at end of file diff --git a/.agents/skills/tunit-test-runner/SKILL.md b/.agents/skills/tunit-test-runner/SKILL.md deleted file mode 100644 index f3b6270e..00000000 --- a/.agents/skills/tunit-test-runner/SKILL.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -name: tunit-test-runner -description: >- - Run, filter, and select TUnit tests through `dotnet test`. Use this whenever - executing .NET tests in a project that depends on TUnit (built on - Microsoft.Testing.Platform / MTP, not VSTest), when `dotnet test --filter` - reports "Zero tests ran", or when tests must be narrowed by assembly, - namespace, class, test name, [Category], or other custom properties. Covers - the `--treenode-filter` path-based query syntax, its operators, the `--` - separator rules across SDK versions, and common 0-tests troubleshooting. -license: MIT ---- - -# Running TUnit tests with `dotnet test` - -## The one rule that matters most - -TUnit runs on **Microsoft.Testing.Platform (MTP)**, not VSTest. The reflexive -`dotnet test --filter "Category=X"` **does not work**: MTP silently rejects the -`--filter` flag, prints its own help text, and exits with `Zero tests ran`. That -looks like a passing-but-empty run or a config failure, but it is just an -unrecognised flag. **Never reach for `--filter` on a TUnit project.** Use -`--treenode-filter` instead. - -| Other frameworks (VSTest) | TUnit (MTP) | -| ------------------------------------------ | ---------------------------------------------------- | -| `--filter "Category=Integration"` | `--treenode-filter "/*/*/*/*[Category=Integration]"` | -| `--filter "FullyQualifiedName~LoginTests"` | `--treenode-filter "/*/*/LoginTests/*"` | -| `--filter "Name=AcceptCookiesTest"` | `--treenode-filter "/*/*/*/AcceptCookiesTest"` | - -## How to invoke it - -Prefer `dotnet test` over `dotnet run`: `dotnet test` builds and runs every -targeted TFM automatically and works against a `.csproj`, `.sln`, or `.slnx`, -whereas `dotnet run` only runs a single TFM. - -The catch is the `--` separator, which depends on the SDK: - -```bash -# Universal form — works on every SDK. Use this by default. -dotnet test -- --treenode-filter "/*/*/LoginTests/*" - -# .NET 10+ SDK only — the platform flag can be passed directly. -dotnet test --treenode-filter "/*/*/LoginTests/*" -``` - -Anything after `--` is passed through to the TUnit test runner rather than to -the `dotnet test` command itself. Flags from extension packages -(`--coverage`, `--report-trx`, `--results-directory`, etc.) **must** also sit -after the `--`: - -```bash -dotnet test --configuration Release --no-build \ - -- --treenode-filter "/*/*/*/*[Category=Unit]" --coverage --report-trx -``` - -> Run with no filter to execute everything: `dotnet test`. - -## The `--treenode-filter` syntax - -A filter is a path with four segments, optionally annotated with a property -group on any segment: - -``` -////[Property=Value] -``` - -Use `*` as a wildcard in any segment. The classic "run all tests" filter is -`/*/*/*/*` — four wildcards, one per level. - -### Operators - -| Operator | Meaning | Example | -| -------- | --------------------------------------------- | -------------------------------------- | -| `*` | Wildcard within a segment | `/*/*/LoginTests*/*` | -| `=` | Property equals (exact) | `/*/*/*/*[Category=Unit]` | -| `!=` | Property not equal (exclude) | `/*/*/*/*[Category!=Slow]` | -| `&` | AND — within one segment / property group | `/**[(Category=Unit)&(Priority=High)]` | -| `\|` | OR — within one segment / property group | `/*/*/(LoginTests)\|(SignupTests)/*` | -| `**` | Match any path depth (must be at the **end**) | `/MyAssembly/**` | - -### Two grammar rules that are easy to get wrong - -1. **`&` and `|` operate _inside a single segment or property group_, and each - side must be wrapped in parentheses.** They do not join two complete paths. -2. **Only one property group `[...]` is allowed per path segment.** Combine - conditions _inside_ the single bracket — do not chain brackets. -3. **`**` must terminate the path.** `/MyAssembly/**` is valid; `/**/Class/*` - is not. - -## Troubleshooting: "Zero tests ran" / 0 tests discovered - -Check, in order: - -1. **`--filter` was used instead of `--treenode-filter`.** This is the most common cause. -2. **`Microsoft.NET.Test.Sdk` is still referenced.** It conflicts with the TUnit MTP platform. -3. **TUnit package missing.** Ensure ``. -4. **Missing `[Test]` attribute** or unsupported method shape. -5. **Wrong `OutputType`.** A `hostfxr.dll could not be found` error means the project needs `Exe`. -6. **Bad filter shape.** Remember the path has exactly four segments. - -## References - -- TUnit — Test Filters: https://tunit.dev/docs/execution/test-filters/ -- TUnit — Troubleshooting & FAQ: https://tunit.dev/docs/troubleshooting/ -- TUnit — CI/CD pipelines: https://tunit.dev/docs/examples/tunit-ci-pipeline/ -- TUnit — Explicit tests: https://tunit.dev/docs/writing-tests/explicit/ -- MTP graph-query filtering spec: https://github.com/microsoft/testfx/blob/main/docs/mstest-runner-graphqueryfiltering/graph-query-filtering.md diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index 1e5002f0..471a88ff 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -24,7 +24,7 @@ "rollForward": false }, "purview.build": { - "version": "0.7.0", + "version": "0.7.1", "commands": [ "purview-build" ], diff --git a/Directory.Packages.props b/Directory.Packages.props index 7598d854..f0d80b86 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -10,10 +10,10 @@ 1.76.0 1.2.0 1.2.0 - 2.3.0 + 2.4.0 5.0.5 1.0.2 - 13.6.0-preview.1 + 13.6.0-preview.2 4.16.0 0.14.0 10.0.13 diff --git a/global.json b/global.json index 025f0be0..8b388e3d 100644 --- a/global.json +++ b/global.json @@ -1,4 +1,9 @@ { + "sdk": { + "version": "11.0.100-rc.2.26504.105", + "rollForward": "latestMajor", + "allowPrerelease": true + }, "msbuild-sdks": { "Purview.BuildSdk": "1.1.0" }, diff --git a/src/Directory.Build.props b/src/Directory.Build.props index 2149f80c..f09c88d8 100644 --- a/src/Directory.Build.props +++ b/src/Directory.Build.props @@ -23,12 +23,12 @@ $(NoWarn);CA1031;CA2234 - + https://purview.dev/ @@ -57,7 +57,7 @@ /> - + diff --git a/src/src/Admin.AzureStorage/AzureStorageAdminEventQueryService.cs b/src/src/Admin.AzureStorage/AzureStorageAdminEventQueryService.cs index c7fb2971..3f30212a 100644 --- a/src/src/Admin.AzureStorage/AzureStorageAdminEventQueryService.cs +++ b/src/src/Admin.AzureStorage/AzureStorageAdminEventQueryService.cs @@ -125,7 +125,7 @@ out var version static JsonElement ParsePayload(string? payload) { if (string.IsNullOrWhiteSpace(payload)) - return JsonDocument.Parse("null").RootElement.Clone(); + return JsonSerializer.SerializeToElement("null"); using var document = JsonDocument.Parse(payload); return document.RootElement.Clone(); diff --git a/src/src/Admin.AzureStorage/AzureStorageAdminProjectionService.cs b/src/src/Admin.AzureStorage/AzureStorageAdminProjectionService.cs index 4bc47f9f..fc7970af 100644 --- a/src/src/Admin.AzureStorage/AzureStorageAdminProjectionService.cs +++ b/src/src/Admin.AzureStorage/AzureStorageAdminProjectionService.cs @@ -1,11 +1,11 @@ -using System.Text.Json; using Azure; using Microsoft.Extensions.Options; +using Purview.EventSourcing.Admin.AzureStorage.Internal; using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Services; -using Purview.EventSourcing.Admin.AzureStorage.Internal; using Purview.EventSourcing.AzureStorage; using Purview.EventSourcing.AzureStorage.Entities; +using System.Text.Json; namespace Purview.EventSourcing.Admin.AzureStorage; @@ -106,7 +106,7 @@ string reason } } - var finalState = JsonDocument.Parse(JsonSerializer.Serialize(projectedState)).RootElement.Clone(); + var finalState = JsonSerializer.SerializeToElement(projectedState); var projectedVersion = events.Max(x => x.Version); var projectedAtUtc = events.OrderByDescending(x => x.Version).First().Event.Timestamp; diff --git a/src/src/Admin.MongoDB/MongoDbAdminEventQueryService.cs b/src/src/Admin.MongoDB/MongoDbAdminEventQueryService.cs index 136421b8..dd41de7c 100644 --- a/src/src/Admin.MongoDB/MongoDbAdminEventQueryService.cs +++ b/src/src/Admin.MongoDB/MongoDbAdminEventQueryService.cs @@ -1,9 +1,9 @@ -using System.Text.Json; using MongoDB.Driver; using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Queries; using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.MongoDB.Events.Entities; +using System.Text.Json; namespace Purview.EventSourcing.Admin.MongoDB; @@ -101,12 +101,5 @@ CancellationToken cancellationToken return new PagedResult(envelopes, query.Page, pageSize, total); } - static JsonElement ParsePayload(string? payload) - { - if (string.IsNullOrWhiteSpace(payload)) - return JsonDocument.Parse("null").RootElement.Clone(); - - using var document = JsonDocument.Parse(payload); - return document.RootElement.Clone(); - } + static JsonElement ParsePayload(string? payload) => string.IsNullOrWhiteSpace(payload) ? JsonSerializer.SerializeToElement("null") : JsonSerializer.SerializeToElement(payload); } diff --git a/src/src/Admin.MongoDB/MongoDbAdminProjectionService.cs b/src/src/Admin.MongoDB/MongoDbAdminProjectionService.cs index 9a5c5524..3da6f0c0 100644 --- a/src/src/Admin.MongoDB/MongoDbAdminProjectionService.cs +++ b/src/src/Admin.MongoDB/MongoDbAdminProjectionService.cs @@ -1,8 +1,8 @@ -using System.Text.Json; using MongoDB.Driver; using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.MongoDB.Events.Entities; +using System.Text.Json; namespace Purview.EventSourcing.Admin.MongoDB; @@ -83,8 +83,7 @@ CancellationToken cancellationToken ? $"Events projected up to available version {lastEvent.Version} (target was {targetVersion})" : $"Events projected up to version {targetVersion}"; - var finalState = JsonDocument.Parse(JsonSerializer.Serialize(projectedState)).RootElement.Clone(); - + var finalState = JsonSerializer.SerializeToElement(projectedState); return new ProjectionResponse( aggregateType, aggregateId, @@ -165,7 +164,7 @@ CancellationToken cancellationToken ? $"Events projected up to available timestamp {lastEvent.Timestamp:O} (target was {targetUtc:O})" : $"Events projected up to timestamp {targetUtc:O}"; - var finalState = JsonDocument.Parse(JsonSerializer.Serialize(projectedState)).RootElement.Clone(); + var finalState = JsonSerializer.SerializeToElement(projectedState); return new ProjectionResponse( aggregateType, diff --git a/src/src/Admin.Postgres/PostgresAdminEventQueryService.cs b/src/src/Admin.Postgres/PostgresAdminEventQueryService.cs index e8b697e4..a4562e56 100644 --- a/src/src/Admin.Postgres/PostgresAdminEventQueryService.cs +++ b/src/src/Admin.Postgres/PostgresAdminEventQueryService.cs @@ -1,12 +1,12 @@ -using System.Text.Json; using Microsoft.EntityFrameworkCore; using Microsoft.Extensions.Options; using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Postgres.Internal; using Purview.EventSourcing.Admin.Queries; using Purview.EventSourcing.Admin.Services; -using Purview.EventSourcing.Admin.Postgres.Internal; using Purview.EventSourcing.Postgres.Events; using Purview.EventSourcing.Postgres.Events.EntityFramework; +using System.Text.Json; namespace Purview.EventSourcing.Admin.Postgres; @@ -97,12 +97,5 @@ static EventStoreDbContext CreateContext(PostgresEventStoreOptions options, Post return new EventStoreDbContext(builder.Options, table.SchemaName, table.TableName); } - static JsonElement ParsePayload(string? payload) - { - if (string.IsNullOrWhiteSpace(payload)) - return JsonDocument.Parse("null").RootElement.Clone(); - - using var document = JsonDocument.Parse(payload); - return document.RootElement.Clone(); - } + static JsonElement ParsePayload(string? payload) => string.IsNullOrWhiteSpace(payload) ? JsonSerializer.SerializeToElement("null") : JsonSerializer.SerializeToElement(payload); } diff --git a/src/src/Admin.Postgres/PostgresAdminProjectionService.cs b/src/src/Admin.Postgres/PostgresAdminProjectionService.cs index a4d14c45..970f6fce 100644 --- a/src/src/Admin.Postgres/PostgresAdminProjectionService.cs +++ b/src/src/Admin.Postgres/PostgresAdminProjectionService.cs @@ -1,11 +1,11 @@ -using System.Text.Json; using Microsoft.EntityFrameworkCore; using Microsoft.Extensions.Options; using Purview.EventSourcing.Admin.Models; -using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.Postgres.Internal; +using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Postgres.Events; using Purview.EventSourcing.Postgres.Events.EntityFramework; +using System.Text.Json; namespace Purview.EventSourcing.Admin.Postgres; @@ -83,7 +83,7 @@ CancellationToken cancellationToken ? $"Events projected up to available version {rowList.Last().Version} (target was {targetVersion})" : $"Events projected up to version {targetVersion}"; - var finalState = JsonDocument.Parse(JsonSerializer.Serialize(projectedState)).RootElement.Clone(); + var finalState = JsonSerializer.SerializeToElement(projectedState); return new ProjectionResponse( aggregateType, @@ -166,7 +166,7 @@ CancellationToken cancellationToken ? $"Events projected up to available timestamp {latestTimestamp:O} (target was {targetUtc:O})" : $"Events projected up to timestamp {targetUtc:O}"; - var finalState = JsonDocument.Parse(JsonSerializer.Serialize(projectedState)).RootElement.Clone(); + var finalState = JsonSerializer.SerializeToElement(projectedState); return new ProjectionResponse( aggregateType, diff --git a/src/src/Admin.SqlServer/SqlServerAdminEventQueryService.cs b/src/src/Admin.SqlServer/SqlServerAdminEventQueryService.cs index 11c4fc06..fb5ef0bc 100644 --- a/src/src/Admin.SqlServer/SqlServerAdminEventQueryService.cs +++ b/src/src/Admin.SqlServer/SqlServerAdminEventQueryService.cs @@ -100,7 +100,7 @@ static EventStoreDbContext CreateContext(SqlServerEventStoreOptions options, Sql static JsonElement ParsePayload(string? payload) { if (string.IsNullOrWhiteSpace(payload)) - return JsonDocument.Parse("null").RootElement.Clone(); + return JsonSerializer.SerializeToElement("null"); using var document = JsonDocument.Parse(payload); return document.RootElement.Clone(); diff --git a/src/src/Admin.SqlServer/SqlServerAdminProjectionService.cs b/src/src/Admin.SqlServer/SqlServerAdminProjectionService.cs index d4327a9b..fc9b2ce7 100644 --- a/src/src/Admin.SqlServer/SqlServerAdminProjectionService.cs +++ b/src/src/Admin.SqlServer/SqlServerAdminProjectionService.cs @@ -1,4 +1,3 @@ -using System.Text.Json; using Microsoft.EntityFrameworkCore; using Microsoft.Extensions.Options; using Purview.EventSourcing.Admin.Models; @@ -6,6 +5,7 @@ using Purview.EventSourcing.Admin.SQLServer.Internal; using Purview.EventSourcing.SqlServer.Events; using Purview.EventSourcing.SqlServer.Events.EntityFramework; +using System.Text.Json; namespace Purview.EventSourcing.Admin.SQLServer; @@ -83,7 +83,7 @@ CancellationToken cancellationToken ? $"Events projected up to available version {rowList.Last().Version} (target was {targetVersion})" : $"Events projected up to version {targetVersion}"; - var finalState = JsonDocument.Parse(JsonSerializer.Serialize(projectedState)).RootElement.Clone(); + var finalState = JsonSerializer.SerializeToElement(projectedState); return new ProjectionResponse( aggregateType, @@ -166,7 +166,7 @@ CancellationToken cancellationToken ? $"Events projected up to available timestamp {latestTimestamp:O} (target was {targetUtc:O})" : $"Events projected up to timestamp {targetUtc:O}"; - var finalState = JsonDocument.Parse(JsonSerializer.Serialize(projectedState)).RootElement.Clone(); + var finalState = JsonSerializer.SerializeToElement(projectedState); return new ProjectionResponse( aggregateType, diff --git a/src/src/AzureStorage/TableEventStore.SaveOperation.cs b/src/src/AzureStorage/TableEventStore.SaveOperation.cs index 1f300435..fc010e5c 100644 --- a/src/src/AzureStorage/TableEventStore.SaveOperation.cs +++ b/src/src/AzureStorage/TableEventStore.SaveOperation.cs @@ -1,8 +1,3 @@ -using System.Diagnostics; -using System.Diagnostics.CodeAnalysis; -using System.Net; -using System.Security.Claims; -using System.Text; using Azure; using Microsoft.Extensions.Options; using Purview.EventSourcing.Aggregates; @@ -16,6 +11,11 @@ using Purview.EventSourcing.Services; using Purview.EventSourcing.Storage; using Purview.EventSourcing.Validation; +using System.Diagnostics; +using System.Diagnostics.CodeAnalysis; +using System.Net; +using System.Security.Claims; +using System.Text; namespace Purview.EventSourcing.AzureStorage; @@ -51,17 +51,17 @@ internal async Task> SaveCoreAsync( params EventRecord[] additionalEvents ) { - var (Terminal, Aggregate, OperationContext, IdempotencyId, ChangeEvents, IsNew, Marker) = + var (saveResult, preparedAggregate, preparedOperationContext, idempotencyId, changeEvents, isNew, marker) = await PrepareSaveAsync(aggregate, operationContext, additionalEvents, cancellationToken); - return Terminal + return saveResult ?? await PersistAndNotifyAsync( - Aggregate, - OperationContext, - IdempotencyId, - ChangeEvents, - IsNew, - Marker!, + preparedAggregate, + preparedOperationContext, + idempotencyId, + changeEvents, + isNew, + marker!, cancellationToken ); } diff --git a/src/src/CosmosDb/CosmosDbClient.CosmosSystemTextJsonSerializer.cs b/src/src/CosmosDb/CosmosDbClient.CosmosSystemTextJsonSerializer.cs index 6f8aab01..4d134c2d 100644 --- a/src/src/CosmosDb/CosmosDbClient.CosmosSystemTextJsonSerializer.cs +++ b/src/src/CosmosDb/CosmosDbClient.CosmosSystemTextJsonSerializer.cs @@ -7,7 +7,7 @@ partial class CosmosDbClient { public sealed class CosmosSystemTextJsonSerializer : CosmosSerializer { - static readonly System.Text.Json.JsonSerializerOptions _jsonSerializerOptions = + static readonly System.Text.Json.JsonSerializerOptions JsonSerializerOptions = EventStoreSerializationHelpers.CreateJsonSerializerOptions(); public override T FromStream(Stream stream) @@ -16,13 +16,13 @@ public override T FromStream(Stream stream) return (T)(object)stream; using (stream) - return System.Text.Json.JsonSerializer.Deserialize(stream, _jsonSerializerOptions)!; + return System.Text.Json.JsonSerializer.Deserialize(stream, JsonSerializerOptions)!; } public override Stream ToStream(T input) { MemoryStream streamPayload = new(); - System.Text.Json.JsonSerializer.Serialize(streamPayload, input, _jsonSerializerOptions); + System.Text.Json.JsonSerializer.Serialize(streamPayload, input, JsonSerializerOptions); streamPayload.Position = 0; return streamPayload; diff --git a/src/src/EntityFrameworkCore.SourceGenerator/EFSnapshotShapeAnalyzer.cs b/src/src/EntityFrameworkCore.SourceGenerator/EFSnapshotShapeAnalyzer.cs index a6c42ed3..c36d09b6 100644 --- a/src/src/EntityFrameworkCore.SourceGenerator/EFSnapshotShapeAnalyzer.cs +++ b/src/src/EntityFrameworkCore.SourceGenerator/EFSnapshotShapeAnalyzer.cs @@ -214,7 +214,7 @@ HashSet visited } static IPropertySymbol[] GetMappedMembers(INamedTypeSymbol type) => - type.GetMembers().OfType().Where(property => IsMappedMember(type, property)).ToArray(); + [.. type.GetMembers().OfType().Where(property => IsMappedMember(type, property))]; static bool IsMappedMember(INamedTypeSymbol declaringType, IPropertySymbol property) => !property.IsStatic diff --git a/src/src/EntityFrameworkCore.SourceGenerator/EFSourceGenerator.cs b/src/src/EntityFrameworkCore.SourceGenerator/EFSourceGenerator.cs index cc977b46..d6fa6ebb 100644 --- a/src/src/EntityFrameworkCore.SourceGenerator/EFSourceGenerator.cs +++ b/src/src/EntityFrameworkCore.SourceGenerator/EFSourceGenerator.cs @@ -12,8 +12,8 @@ public void Initialize(IncrementalGeneratorInitializationContext context) .RegisterEmbeddedAttribute() .RegisterPostInitializationOutput(static output => { - foreach (var (HintName, Source) in AttributeEmiiter.GetAttributeSources()) - output.AddSource(HintName, Source); + foreach (var (hintName, source) in AttributeEmiiter.GetAttributeSources()) + output.AddSource(hintName, source); }); } } diff --git a/src/src/EventSourcing/Aggregates/AggregateBase.cs b/src/src/EventSourcing/Aggregates/AggregateBase.cs index 8c4d1297..7310daa8 100644 --- a/src/src/EventSourcing/Aggregates/AggregateBase.cs +++ b/src/src/EventSourcing/Aggregates/AggregateBase.cs @@ -1,8 +1,8 @@ +using Purview.EventSourcing.Aggregates.Events; +using Purview.EventSourcing.Aggregates.Exceptions; using System.Collections.Concurrent; using System.Reflection; using System.Runtime.CompilerServices; -using Purview.EventSourcing.Aggregates.Events; -using Purview.EventSourcing.Aggregates.Exceptions; namespace Purview.EventSourcing.Aggregates; @@ -26,10 +26,10 @@ public abstract class AggregateBase : IAggregate static readonly Lock ApplierBuildLock = new(); [ThreadStatic] - static Dictionary>? s_applierBuildTarget; + static Dictionary>? ApplierBuildTarget; [ThreadStatic] - static bool s_dynamicDetected; + static bool DynamicDetected; /// /// The shared static applier map for this aggregate type, or when the type @@ -194,9 +194,9 @@ protected void Register(Action applier) { ArgumentNullException.ThrowIfNull(applier); - if (s_applierBuildTarget is not null) + if (ApplierBuildTarget is not null) { - s_dynamicDetected = true; + DynamicDetected = true; return; } @@ -213,9 +213,9 @@ protected void RegisterGenerated() { var applier = GetGeneratedApplier(GetType(), typeof(TEvent)); - if (s_applierBuildTarget is not null) + if (ApplierBuildTarget is not null) { - s_applierBuildTarget[typeof(TEvent)] = applier; + ApplierBuildTarget[typeof(TEvent)] = applier; return; } @@ -297,8 +297,8 @@ static bool TryBuildStaticAppliers(Type aggregateType, out Dictionary> candidate = new(); - s_applierBuildTarget = candidate; - s_dynamicDetected = false; + ApplierBuildTarget = candidate; + DynamicDetected = false; try { @@ -308,10 +308,10 @@ static bool TryBuildStaticAppliers(Type aggregateType, out Dictionary OnGetAsync() @@ -60,7 +62,7 @@ public async Task OnPostAsync() FulfilmentResult result; try { - result = await FulfilmentService.PlaceOrderAsync( + result = await fulfilmentService.PlaceOrderAsync( customerId, InventoryId, Quantity, diff --git a/src/src/Samples.Web/Samples.Web.csproj b/src/src/Samples.Web/Samples.Web.csproj index cfd4cb4a..92a88b4b 100644 --- a/src/src/Samples.Web/Samples.Web.csproj +++ b/src/src/Samples.Web/Samples.Web.csproj @@ -1,7 +1,7 @@  true - $(NoWarn);CA1515; + diff --git a/src/src/SourceGenerator/Common/EventContractComparison.cs b/src/src/SourceGenerator/Common/EventContractComparison.cs index 59bbf24e..107985ae 100644 --- a/src/src/SourceGenerator/Common/EventContractComparison.cs +++ b/src/src/SourceGenerator/Common/EventContractComparison.cs @@ -47,8 +47,8 @@ out var currentAggregate Issue( DiagnosticLibrary.EventContractRemoved, [baselineAggregate.AggregateName], - EventKey: null, - AggregateKey: null + eventKey: null, + aggregateKey: null ) ); continue; @@ -113,12 +113,12 @@ List issues maxCurrentVersion.ToString(System.Globalization.CultureInfo.InvariantCulture), baselineEvent.SchemaVersion.ToString(System.Globalization.CultureInfo.InvariantCulture), ], - EventKey: EventContractManifestLibrary.CreateEventKey( + eventKey: EventContractManifestLibrary.CreateEventKey( baselineAggregate.AggregateNamespace, baselineAggregate.AggregateName, sameName[0].MethodName ), - AggregateKey: aggregateKey + aggregateKey: aggregateKey ) ); continue; @@ -132,8 +132,8 @@ List issues baselineEvent.SchemaVersion.ToString(System.Globalization.CultureInfo.InvariantCulture), baselineAggregate.AggregateName, ], - EventKey: null, - AggregateKey: aggregateKey + eventKey: null, + aggregateKey: aggregateKey ) ); } @@ -166,8 +166,8 @@ List issues Issue( DiagnosticLibrary.EventContractFieldRemoved, [baselineField.Name, baselineEvent.EventName, version, aggregate.AggregateName], - EventKey: eventKey, - AggregateKey: aggregateKey + eventKey: eventKey, + aggregateKey: aggregateKey ) ); continue; @@ -186,8 +186,8 @@ List issues baselineField.Type, currentField.Type, ], - EventKey: eventKey, - AggregateKey: aggregateKey + eventKey: eventKey, + aggregateKey: aggregateKey ) ); continue; @@ -199,8 +199,8 @@ List issues Issue( DiagnosticLibrary.EventContractFieldBecameRequired, [baselineField.Name, baselineEvent.EventName, version, aggregate.AggregateName], - EventKey: eventKey, - AggregateKey: aggregateKey + eventKey: eventKey, + aggregateKey: aggregateKey ) ); } @@ -219,8 +219,8 @@ List issues Issue( DiagnosticLibrary.EventContractFieldBecameRequired, [currentField.Name, baselineEvent.EventName, version, aggregate.AggregateName], - EventKey: eventKey, - AggregateKey: aggregateKey + eventKey: eventKey, + aggregateKey: aggregateKey ) ); } @@ -238,7 +238,7 @@ static bool FieldBecameRequired(EventContractField baseline, EventContractField static ContractIssue Issue( DiagnosticDescriptor descriptor, string[] messageArgs, - string? EventKey, - string? AggregateKey - ) => new(descriptor, new([.. messageArgs]), EventKey, AggregateKey); + string? eventKey, + string? aggregateKey + ) => new(descriptor, new([.. messageArgs]), eventKey, aggregateKey); } diff --git a/src/src/SourceGenerator/Common/PreCompilationMarker.cs b/src/src/SourceGenerator/Common/PreCompilationMarker.cs index 6db2a615..42630e14 100644 --- a/src/src/SourceGenerator/Common/PreCompilationMarker.cs +++ b/src/src/SourceGenerator/Common/PreCompilationMarker.cs @@ -22,6 +22,6 @@ static class PreCompilationMarker System.Text.Encoding.UTF8 ); - public static IncrementalValueProvider Provider(IncrementalGeneratorInitializationContext context) => - context.AnalyzerConfigOptionsProvider.Select(static (_, _) => Source); + public static IncrementalValueProvider Provider(IncrementalGeneratorInitializationContext context) => + context.AnalyzerConfigOptionsProvider.Select(static (_, _) => HintName); } diff --git a/src/src/SourceGenerator/Common/SourceGenLibrary.cs b/src/src/SourceGenerator/Common/SourceGenLibrary.cs index ae04d43c..91eba0a8 100644 --- a/src/src/SourceGenerator/Common/SourceGenLibrary.cs +++ b/src/src/SourceGenerator/Common/SourceGenLibrary.cs @@ -96,7 +96,7 @@ IncrementalGeneratorInitializationContext context return context .AdditionalTextsProvider.Combine(fileName) - .Where(static pair => IsBaselineFile(pair.Left?.Path ?? string.Empty, pair.Right)) + .Where(pair => IsBaselineFile(pair.Left?.Path ?? string.Empty, pair.Right)) .Collect() .Select( static (pairs, ct) => @@ -105,9 +105,9 @@ IncrementalGeneratorInitializationContext context if (pairs.IsEmpty) return new BaselineState(null, null); - var (Left, Right) = pairs[0]; - var content = Left.GetText(ct)?.ToString() ?? string.Empty; - return EventContractManifestLibrary.Parse(content, Right); + var (left, right) = pairs[0]; + var content = left.GetText(ct)?.ToString() ?? string.Empty; + return EventContractManifestLibrary.Parse(content, right); } ) .WithTrackingName("EventContractBaseline"); diff --git a/src/src/SourceGenerator/Generators/AggregateSourceGenerator.cs b/src/src/SourceGenerator/Generators/AggregateSourceGenerator.cs index d136a9f9..99bc144b 100644 --- a/src/src/SourceGenerator/Generators/AggregateSourceGenerator.cs +++ b/src/src/SourceGenerator/Generators/AggregateSourceGenerator.cs @@ -9,8 +9,8 @@ public void Initialize(IncrementalGeneratorInitializationContext context) .RegisterEmbeddedAttribute() .RegisterPostInitializationOutput(ctx => { - foreach (var (HintName, Source) in AggregateAttributeEmitter.Emit()) - ctx.AddSource(HintName, Source); + foreach (var (hintName, source) in AggregateAttributeEmitter.Emit()) + ctx.AddSource(hintName, source); }); var generationContext = SourceGenLibrary.GetGenerationContext(context); @@ -20,7 +20,7 @@ public void Initialize(IncrementalGeneratorInitializationContext context) #pragma warning disable RSEXPERIMENTAL007 // Pre-compilation source output is intentionally used to stabilize the incremental cache. context.RegisterPreCompilationSourceOutput( PreCompilationMarker.Provider(context), - static (spc, source) => spc.AddSource(PreCompilationMarker.HintName, source) + static (spc, _) => spc.AddSource(PreCompilationMarker.HintName, PreCompilationMarker.Source) ); #pragma warning restore RSEXPERIMENTAL007 diff --git a/src/tests/Admin.UnitTests/Api/AdminApiEndpointTests.cs b/src/tests/Admin.UnitTests/Api/AdminApiEndpointTests.cs index 13c3cdaf..a1ce7935 100644 --- a/src/tests/Admin.UnitTests/Api/AdminApiEndpointTests.cs +++ b/src/tests/Admin.UnitTests/Api/AdminApiEndpointTests.cs @@ -1,8 +1,3 @@ -using System.Net; -using System.Net.Http.Json; -using System.Security.Claims; -using System.Text.Encodings.Web; -using System.Text.Json; using Microsoft.AspNetCore.Authentication; using Microsoft.AspNetCore.Authorization; using Microsoft.AspNetCore.Builder; @@ -17,6 +12,11 @@ using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Queries; using Purview.EventSourcing.Admin.Services; +using System.Net; +using System.Net.Http.Json; +using System.Security.Claims; +using System.Text.Encodings.Web; +using System.Text.Json; namespace Purview.EventSourcing.Admin.API; @@ -569,7 +569,7 @@ CancellationToken cancellationToken null, null ), - JsonDocument.Parse("""{"customerId":"customer-1"}""").RootElement.Clone() + JsonSerializer.SerializeToElement(/*lang=json,strict*/ """{"customerId":"customer-1"}""") ); return Task.FromResult?>( new PagedResult([envelope], query.Page, query.PageSize, 1) @@ -579,9 +579,7 @@ CancellationToken cancellationToken sealed class RecordingProjectionService : IAdminProjectionService { - static readonly JsonElement ProjectedState = JsonDocument - .Parse("""{"event_1":{"eventType":"OrderCreatedEvent","version":1}}""") - .RootElement.Clone(); + static readonly JsonElement ProjectedState = JsonSerializer.SerializeToElement(/*lang=json,strict*/ """{"event_1":{"eventType":"OrderCreatedEvent","version":1}}"""); public Task ProjectAtVersionAsync( string aggregateType, diff --git a/src/tests/Admin.UnitTests/Api/AdminOperationalEndpointsTests.cs b/src/tests/Admin.UnitTests/Api/AdminOperationalEndpointsTests.cs index 394e0b19..1b7cb40d 100644 --- a/src/tests/Admin.UnitTests/Api/AdminOperationalEndpointsTests.cs +++ b/src/tests/Admin.UnitTests/Api/AdminOperationalEndpointsTests.cs @@ -1,14 +1,14 @@ -using System.Net; -using System.Net.Http.Json; -using System.Text.Json; using Microsoft.Extensions.DependencyInjection; using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Queries; -using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.Security; +using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Outbox; using Purview.EventSourcing.Services; +using System.Net; +using System.Net.Http.Json; +using System.Text.Json; namespace Purview.EventSourcing.Admin.API; @@ -381,7 +381,7 @@ CancellationToken cancellationToken null, null ), - JsonDocument.Parse("{}").RootElement.Clone() + JsonSerializer.SerializeToElement(/*lang=json,strict*/ """{}""") ) ); } diff --git a/src/tests/EventSourcing.UnitTests/EFOpaqueAttribute.cs b/src/tests/EventSourcing.UnitTests/EFOpaqueAttribute.cs index 60d5c457..f94bf642 100644 --- a/src/tests/EventSourcing.UnitTests/EFOpaqueAttribute.cs +++ b/src/tests/EventSourcing.UnitTests/EFOpaqueAttribute.cs @@ -1,7 +1,10 @@ // Mirrors the attribute emitted by Purview.EventSourcing.EntityFrameworkCore.SourceGenerator, which is not // referenced by this project. Entity Framework snapshot providers detect the marker by full type name, so the // declaration must keep the generated namespace and type name. + +#pragma warning disable IDE0130 // Namespace does not match folder structure namespace Purview.EventSourcing.EntityFrameworkCore; +#pragma warning restore IDE0130 // Namespace does not match folder structure [AttributeUsage(AttributeTargets.Property, Inherited = true, AllowMultiple = false)] public sealed class EFOpaqueAttribute : Attribute; diff --git a/src/tests/EventSourcing.UnitTests/Postgres/Snapshots/PostgresSnapshotClientTests.cs b/src/tests/EventSourcing.UnitTests/Postgres/Snapshots/PostgresSnapshotClientTests.cs index b215ed02..ffddfc6e 100644 --- a/src/tests/EventSourcing.UnitTests/Postgres/Snapshots/PostgresSnapshotClientTests.cs +++ b/src/tests/EventSourcing.UnitTests/Postgres/Snapshots/PostgresSnapshotClientTests.cs @@ -48,7 +48,7 @@ public async Task ValidateAggregatePayloadShape_GivenReadOnlyComplexMemberOnValu .That(() => ValidateAggregatePayloadShape(typeof(ReadOnlyValueTypeMemberAggregate))) .Throws(); - await Assert.That(exception.Message).Contains(nameof(ReadOnlyStructHolder.Mirror)); + await Assert.That(exception!.Message).Contains(nameof(ReadOnlyStructHolder.Mirror)); await Assert.That(exception.Message).Contains("writeable"); } @@ -78,7 +78,9 @@ sealed class SettableValueTypeMemberAggregate readonly struct ReadOnlyStructHolder { +#pragma warning disable IDE0051 // Remove unused private members ReadOnlyStructHolder(ValueTypeMemberInfo mirror) => Mirror = mirror; +#pragma warning restore IDE0051 // Remove unused private members public ValueTypeMemberInfo Mirror { get; } } diff --git a/src/tests/EventSourcing.UnitTests/SqlServer/Snapshots/SqlServerSnapshotClientTests.cs b/src/tests/EventSourcing.UnitTests/SqlServer/Snapshots/SqlServerSnapshotClientTests.cs index 17fe3aea..f829699e 100644 --- a/src/tests/EventSourcing.UnitTests/SqlServer/Snapshots/SqlServerSnapshotClientTests.cs +++ b/src/tests/EventSourcing.UnitTests/SqlServer/Snapshots/SqlServerSnapshotClientTests.cs @@ -151,14 +151,18 @@ sealed class SettableValueTypeMemberAggregate readonly struct ReadOnlyStructHolder { +#pragma warning disable IDE0051 // Remove unused private members ReadOnlyStructHolder(ValueTypeMemberInfo mirror) => Mirror = mirror; +#pragma warning restore IDE0051 // Remove unused private members public ValueTypeMemberInfo Mirror { get; } } readonly struct ReadOnlyCollectionHolder { +#pragma warning disable IDE0051 // Remove unused private members ReadOnlyCollectionHolder(EventStoreList items) => Items = items; +#pragma warning restore IDE0051 // Remove unused private members public EventStoreList Items { get; } } From d773aab1d2808848263279a08fc2d4c63829e5e5 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Fri, 23 Oct 2026 09:12:58 +0100 Subject: [PATCH 04/41] chore: added skills --- .../purview-architests-contracts/SKILL.md | 163 +++++++ .../purview-architests-extending/SKILL.md | 123 ++++++ .../purview-architests-migration/SKILL.md | 143 +++++++ .../SKILL.md | 190 ++++++++ .../purview-architests-type-rules/SKILL.md | 188 ++++++++ .agents/skills/purview-architests/SKILL.md | 354 +++++++++++++++ .../skills/purview-buildsdk-adoption/SKILL.md | 114 +++++ .../purview-buildsdk-configuration/SKILL.md | 110 +++++ .../references/properties.md | 146 +++++++ .../SKILL.md | 134 ++++++ .../references/detection.md | 79 ++++ .../references/test-types.md | 35 ++ .../purview-buildsdk-project-layout/SKILL.md | 136 ++++++ .../SKILL.md | 111 +++++ .../SKILL.md | 166 +++++++ .../references/repository-root.md | 55 +++ .../purview-buildsdk-skill-tests/SKILL.md | 131 ++++++ .../references/authoring.md | 79 ++++ .../skills/purview-buildsdk-testing/SKILL.md | 121 ++++++ .../references/treenode-filter.md | 107 +++++ .agents/skills/purview-results-core/SKILL.md | 140 ++++++ .../purview-results-http-mapping/SKILL.md | 135 ++++++ .../purview-results-union-errors/SKILL.md | 179 ++++++++ .../references/migrating-error-returns.md | 67 +++ .../SKILL.md | 101 +++++ .../SKILL.md | 121 ++++++ .../SKILL.md | 334 +++++++++++++++ .../references/legacy-emitter-migration.md | 58 +++ .../SKILL.md | 142 ++++++ .../SKILL.md | 245 +++++++++++ .../references/merge-internals.md | 139 ++++++ .../purview-sourcegenerator-pipeline/SKILL.md | 231 ++++++++++ .../purview-sourcegenerator-testing/SKILL.md | 404 ++++++++++++++++++ .../references/test-modernisation.md | 63 +++ .../SKILL.md | 230 ++++++++++ .../skills/purview-telemetry-design/SKILL.md | 96 +++++ .../references/REFERENCE.md | 101 +++++ .../purview-telemetry-diagnostics/SKILL.md | 168 ++++++++ .../purview-telemetry-migration/SKILL.md | 81 ++++ .../references/REFERENCE.md | 181 ++++++++ .../SKILL.md | 224 ++++++++++ .../purview-telemetry-quickstart/SKILL.md | 140 ++++++ .../SKILL.md | 85 ++++ .../purview-value-objects-efcore/SKILL.md | 277 ++++++++++++ .../references/key-value-generation.md | 101 +++++ .../purview-value-objects-zodsharp/SKILL.md | 325 ++++++++++++++ .../references/custom-rules.md | 130 ++++++ .agents/skills/purview-value-objects/SKILL.md | 263 ++++++++++++ .../purview-zodsharp-aspnetcore/SKILL.md | 242 +++++++++++ .agents/skills/purview-zodsharp-core/SKILL.md | 176 ++++++++ .../purview-zodsharp-custom-rules/SKILL.md | 241 +++++++++++ .../purview-zodsharp-diagnostics/SKILL.md | 125 ++++++ .agents/skills/purview-zodsharp-json/SKILL.md | 223 ++++++++++ .../SKILL.md | 224 ++++++++++ .../references/dataannotations.md | 137 ++++++ .../purview-architests-contracts/SKILL.md | 163 +++++++ .../purview-architests-extending/SKILL.md | 123 ++++++ .../purview-architests-migration/SKILL.md | 143 +++++++ .../SKILL.md | 190 ++++++++ .../purview-architests-type-rules/SKILL.md | 188 ++++++++ .claude/skills/purview-architests/SKILL.md | 354 +++++++++++++++ .../skills/purview-buildsdk-adoption/SKILL.md | 114 +++++ .../purview-buildsdk-configuration/SKILL.md | 110 +++++ .../references/properties.md | 146 +++++++ .../SKILL.md | 134 ++++++ .../references/detection.md | 79 ++++ .../references/test-types.md | 35 ++ .../purview-buildsdk-project-layout/SKILL.md | 136 ++++++ .../SKILL.md | 111 +++++ .../SKILL.md | 166 +++++++ .../references/repository-root.md | 55 +++ .../purview-buildsdk-skill-tests/SKILL.md | 131 ++++++ .../references/authoring.md | 79 ++++ .../skills/purview-buildsdk-testing/SKILL.md | 121 ++++++ .../references/treenode-filter.md | 107 +++++ .claude/skills/purview-results-core/SKILL.md | 140 ++++++ .../purview-results-http-mapping/SKILL.md | 135 ++++++ .../purview-results-union-errors/SKILL.md | 179 ++++++++ .../references/migrating-error-returns.md | 67 +++ .../SKILL.md | 101 +++++ .../SKILL.md | 121 ++++++ .../SKILL.md | 334 +++++++++++++++ .../references/legacy-emitter-migration.md | 58 +++ .../SKILL.md | 142 ++++++ .../SKILL.md | 245 +++++++++++ .../references/merge-internals.md | 139 ++++++ .../purview-sourcegenerator-pipeline/SKILL.md | 231 ++++++++++ .../purview-sourcegenerator-testing/SKILL.md | 404 ++++++++++++++++++ .../references/test-modernisation.md | 63 +++ .../SKILL.md | 230 ++++++++++ .../skills/purview-telemetry-design/SKILL.md | 96 +++++ .../references/REFERENCE.md | 101 +++++ .../purview-telemetry-diagnostics/SKILL.md | 168 ++++++++ .../purview-telemetry-migration/SKILL.md | 81 ++++ .../references/REFERENCE.md | 181 ++++++++ .../SKILL.md | 224 ++++++++++ .../purview-telemetry-quickstart/SKILL.md | 140 ++++++ .../SKILL.md | 85 ++++ .../purview-value-objects-efcore/SKILL.md | 277 ++++++++++++ .../references/key-value-generation.md | 101 +++++ .../purview-value-objects-zodsharp/SKILL.md | 325 ++++++++++++++ .../references/custom-rules.md | 130 ++++++ .claude/skills/purview-value-objects/SKILL.md | 263 ++++++++++++ .../purview-zodsharp-aspnetcore/SKILL.md | 242 +++++++++++ .claude/skills/purview-zodsharp-core/SKILL.md | 176 ++++++++ .../purview-zodsharp-custom-rules/SKILL.md | 241 +++++++++++ .../purview-zodsharp-diagnostics/SKILL.md | 125 ++++++ .claude/skills/purview-zodsharp-json/SKILL.md | 223 ++++++++++ .../SKILL.md | 224 ++++++++++ .../references/dataannotations.md | 137 ++++++ skills-lock.json | 245 +++++++++++ 111 files changed, 17873 insertions(+) create mode 100644 .agents/skills/purview-architests-contracts/SKILL.md create mode 100644 .agents/skills/purview-architests-extending/SKILL.md create mode 100644 .agents/skills/purview-architests-migration/SKILL.md create mode 100644 .agents/skills/purview-architests-policy-authoring/SKILL.md create mode 100644 .agents/skills/purview-architests-type-rules/SKILL.md create mode 100644 .agents/skills/purview-architests/SKILL.md create mode 100644 .agents/skills/purview-buildsdk-adoption/SKILL.md create mode 100644 .agents/skills/purview-buildsdk-configuration/SKILL.md create mode 100644 .agents/skills/purview-buildsdk-configuration/references/properties.md create mode 100644 .agents/skills/purview-buildsdk-project-detection/SKILL.md create mode 100644 .agents/skills/purview-buildsdk-project-detection/references/detection.md create mode 100644 .agents/skills/purview-buildsdk-project-detection/references/test-types.md create mode 100644 .agents/skills/purview-buildsdk-project-layout/SKILL.md create mode 100644 .agents/skills/purview-buildsdk-repository-review/SKILL.md create mode 100644 .agents/skills/purview-buildsdk-skill-installation/SKILL.md create mode 100644 .agents/skills/purview-buildsdk-skill-installation/references/repository-root.md create mode 100644 .agents/skills/purview-buildsdk-skill-tests/SKILL.md create mode 100644 .agents/skills/purview-buildsdk-skill-tests/references/authoring.md create mode 100644 .agents/skills/purview-buildsdk-testing/SKILL.md create mode 100644 .agents/skills/purview-buildsdk-testing/references/treenode-filter.md create mode 100644 .agents/skills/purview-results-core/SKILL.md create mode 100644 .agents/skills/purview-results-http-mapping/SKILL.md create mode 100644 .agents/skills/purview-results-union-errors/SKILL.md create mode 100644 .agents/skills/purview-results-union-errors/references/migrating-error-returns.md create mode 100644 .agents/skills/purview-results-zodsharp-problems/SKILL.md create mode 100644 .agents/skills/purview-results-zodsharp-validation/SKILL.md create mode 100644 .agents/skills/purview-sourcegenerator-codewriter/SKILL.md create mode 100644 .agents/skills/purview-sourcegenerator-codewriter/references/legacy-emitter-migration.md create mode 100644 .agents/skills/purview-sourcegenerator-diagnostics/SKILL.md create mode 100644 .agents/skills/purview-sourcegenerator-packaging/SKILL.md create mode 100644 .agents/skills/purview-sourcegenerator-packaging/references/merge-internals.md create mode 100644 .agents/skills/purview-sourcegenerator-pipeline/SKILL.md create mode 100644 .agents/skills/purview-sourcegenerator-testing/SKILL.md create mode 100644 .agents/skills/purview-sourcegenerator-testing/references/test-modernisation.md create mode 100644 .agents/skills/purview-sourcegenerator-tunit-tests/SKILL.md create mode 100644 .agents/skills/purview-telemetry-design/SKILL.md create mode 100644 .agents/skills/purview-telemetry-design/references/REFERENCE.md create mode 100644 .agents/skills/purview-telemetry-diagnostics/SKILL.md create mode 100644 .agents/skills/purview-telemetry-migration/SKILL.md create mode 100644 .agents/skills/purview-telemetry-migration/references/REFERENCE.md create mode 100644 .agents/skills/purview-telemetry-multi-targeting/SKILL.md create mode 100644 .agents/skills/purview-telemetry-quickstart/SKILL.md create mode 100644 .agents/skills/purview-value-objects-diagnostics/SKILL.md create mode 100644 .agents/skills/purview-value-objects-efcore/SKILL.md create mode 100644 .agents/skills/purview-value-objects-efcore/references/key-value-generation.md create mode 100644 .agents/skills/purview-value-objects-zodsharp/SKILL.md create mode 100644 .agents/skills/purview-value-objects-zodsharp/references/custom-rules.md create mode 100644 .agents/skills/purview-value-objects/SKILL.md create mode 100644 .agents/skills/purview-zodsharp-aspnetcore/SKILL.md create mode 100644 .agents/skills/purview-zodsharp-core/SKILL.md create mode 100644 .agents/skills/purview-zodsharp-custom-rules/SKILL.md create mode 100644 .agents/skills/purview-zodsharp-diagnostics/SKILL.md create mode 100644 .agents/skills/purview-zodsharp-json/SKILL.md create mode 100644 .agents/skills/purview-zodsharp-source-generator/SKILL.md create mode 100644 .agents/skills/purview-zodsharp-source-generator/references/dataannotations.md create mode 100644 .claude/skills/purview-architests-contracts/SKILL.md create mode 100644 .claude/skills/purview-architests-extending/SKILL.md create mode 100644 .claude/skills/purview-architests-migration/SKILL.md create mode 100644 .claude/skills/purview-architests-policy-authoring/SKILL.md create mode 100644 .claude/skills/purview-architests-type-rules/SKILL.md create mode 100644 .claude/skills/purview-architests/SKILL.md create mode 100644 .claude/skills/purview-buildsdk-adoption/SKILL.md create mode 100644 .claude/skills/purview-buildsdk-configuration/SKILL.md create mode 100644 .claude/skills/purview-buildsdk-configuration/references/properties.md create mode 100644 .claude/skills/purview-buildsdk-project-detection/SKILL.md create mode 100644 .claude/skills/purview-buildsdk-project-detection/references/detection.md create mode 100644 .claude/skills/purview-buildsdk-project-detection/references/test-types.md create mode 100644 .claude/skills/purview-buildsdk-project-layout/SKILL.md create mode 100644 .claude/skills/purview-buildsdk-repository-review/SKILL.md create mode 100644 .claude/skills/purview-buildsdk-skill-installation/SKILL.md create mode 100644 .claude/skills/purview-buildsdk-skill-installation/references/repository-root.md create mode 100644 .claude/skills/purview-buildsdk-skill-tests/SKILL.md create mode 100644 .claude/skills/purview-buildsdk-skill-tests/references/authoring.md create mode 100644 .claude/skills/purview-buildsdk-testing/SKILL.md create mode 100644 .claude/skills/purview-buildsdk-testing/references/treenode-filter.md create mode 100644 .claude/skills/purview-results-core/SKILL.md create mode 100644 .claude/skills/purview-results-http-mapping/SKILL.md create mode 100644 .claude/skills/purview-results-union-errors/SKILL.md create mode 100644 .claude/skills/purview-results-union-errors/references/migrating-error-returns.md create mode 100644 .claude/skills/purview-results-zodsharp-problems/SKILL.md create mode 100644 .claude/skills/purview-results-zodsharp-validation/SKILL.md create mode 100644 .claude/skills/purview-sourcegenerator-codewriter/SKILL.md create mode 100644 .claude/skills/purview-sourcegenerator-codewriter/references/legacy-emitter-migration.md create mode 100644 .claude/skills/purview-sourcegenerator-diagnostics/SKILL.md create mode 100644 .claude/skills/purview-sourcegenerator-packaging/SKILL.md create mode 100644 .claude/skills/purview-sourcegenerator-packaging/references/merge-internals.md create mode 100644 .claude/skills/purview-sourcegenerator-pipeline/SKILL.md create mode 100644 .claude/skills/purview-sourcegenerator-testing/SKILL.md create mode 100644 .claude/skills/purview-sourcegenerator-testing/references/test-modernisation.md create mode 100644 .claude/skills/purview-sourcegenerator-tunit-tests/SKILL.md create mode 100644 .claude/skills/purview-telemetry-design/SKILL.md create mode 100644 .claude/skills/purview-telemetry-design/references/REFERENCE.md create mode 100644 .claude/skills/purview-telemetry-diagnostics/SKILL.md create mode 100644 .claude/skills/purview-telemetry-migration/SKILL.md create mode 100644 .claude/skills/purview-telemetry-migration/references/REFERENCE.md create mode 100644 .claude/skills/purview-telemetry-multi-targeting/SKILL.md create mode 100644 .claude/skills/purview-telemetry-quickstart/SKILL.md create mode 100644 .claude/skills/purview-value-objects-diagnostics/SKILL.md create mode 100644 .claude/skills/purview-value-objects-efcore/SKILL.md create mode 100644 .claude/skills/purview-value-objects-efcore/references/key-value-generation.md create mode 100644 .claude/skills/purview-value-objects-zodsharp/SKILL.md create mode 100644 .claude/skills/purview-value-objects-zodsharp/references/custom-rules.md create mode 100644 .claude/skills/purview-value-objects/SKILL.md create mode 100644 .claude/skills/purview-zodsharp-aspnetcore/SKILL.md create mode 100644 .claude/skills/purview-zodsharp-core/SKILL.md create mode 100644 .claude/skills/purview-zodsharp-custom-rules/SKILL.md create mode 100644 .claude/skills/purview-zodsharp-diagnostics/SKILL.md create mode 100644 .claude/skills/purview-zodsharp-json/SKILL.md create mode 100644 .claude/skills/purview-zodsharp-source-generator/SKILL.md create mode 100644 .claude/skills/purview-zodsharp-source-generator/references/dataannotations.md create mode 100644 skills-lock.json diff --git a/.agents/skills/purview-architests-contracts/SKILL.md b/.agents/skills/purview-architests-contracts/SKILL.md new file mode 100644 index 00000000..3484534f --- /dev/null +++ b/.agents/skills/purview-architests-contracts/SKILL.md @@ -0,0 +1,163 @@ +--- +name: purview-architests-contracts +description: Use when enabling or debugging Purview.Architecture.Testing's committed-API and port rules - apiSurface, apiDocumentation, portImplementation and portPurity. Covers capturing and reviewing .config/api-surface.json, reading an added or breaking API change, requiring XML documentation, and keeping an inner-layer port implemented and technology-neutral. +license: MIT +metadata: + product: Purview.Architecture.Testing + repository: purview-dev/architests +--- + +# API contracts and ports + +Dependency rules say which project may reference which. These rules say what the public surface +actually **is**, and whether the interfaces that define a boundary are honest. They read the compiled +assemblies by metadata only and are off by default, because they need a build. + +| Rule | Group | Catches | +| -- | -- | -- | +| `apiSurface` | `apiRules` | The public API differs from the committed baseline | +| `apiDocumentation` | `apiRules` | A public type or member has no XML documentation | +| `portImplementation` | `portRules` | A port in an inner layer has no public implementation | +| `portPurity` | `portRules` | A port's signature names an infrastructure technology | + +```json +"apiRules": { + "enabled": true +}, +"portRules": { + "enabled": true +} +``` + +Each enabled rule becomes its own TUnit test. A disabled group produces no test, so an absent +`apiSurface` test means the group is off, not that the surface is unchecked. + +## The committed baseline + +`.config/api-surface.json` records every public type and member, grouped by project, with the +responsibility recorded for review context. It is the contract: a change to it is a change to what a +consumer may call. + +- **Captured, never hand-written.** `architests api capture` writes it. +- **Canonical.** Projects, types, interfaces and members are sorted; there are no timestamps; line + endings are always `\n`. An unchanged API regenerates byte for byte, so a diff means a real change. +- **Committed.** It is reviewed like code. A pull request that changes it explains why. + +```bash +dotnet tool install --global Purview.Architecture.Testing.Cli + +architests api capture # write the baseline from the current build +architests api check # compare; exit 1 on any difference +``` + +`api check` is the CI gate; `apiSurface` is the same comparison as a test. A missing baseline is +itself an `apiSurface` failure, because the rule would otherwise pass without checking anything. + +`api capture` and `api check` accept `--repository ` and `--baseline `. Unlike the test +run, a command scans the repository's own build output even when `assemblyRules.assemblyRoots` is +empty, because a tool does not run from a test output directory. + +## Reading a baseline failure + +The message names the project, the type or member, and whether it was added, removed or changed. + +- **Added.** The API grew. Run `architests api capture`, inspect the added entries, and commit them + with the feature. Additions are not breaking, but they are still a reviewed contract change. +- **Removed.** The message calls it breaking. Restore the member, or capture the baseline as a + deliberate breaking release and say so in the pull request. +- **Changed.** The shape moved: kind, `sealed`, `abstract`, base type, interfaces, a member's type, or + whether it is static. Treat the same way as a removal until proven otherwise. + +The baseline includes public **nested** types and the SDK's generated `Assembly` marker. +Both are real public metadata; leave them alone. + +## API documentation + +`apiDocumentation` reads the XML documentation file the compiler writes beside each assembly. + +- `requireTypeDocumentation` (default true) requires a `` entry for every public type. +- `requireMemberDocumentation` (default false) extends that to every public member. + +Member documentation is off by default because a record's positional parameters document its +properties through the type's entry; requiring a separate entry per generated property would punish +a correct record. + +A project that ships no XML file is reported once with the fix: set +`true`. The Purview SDK does this already. + +## The port rules + +A **port** is an interface in one of `portRules.categories`, which default to `domain` and +`application`. Those are the layers that own contracts; an interface in `shared` or in an adapter is +not a port by this definition. + +### `portImplementation` + +Every port must have at least one **public implementation** in a production project. An unimplemented +port is either dead or a boundary nobody crossed; both deserve a review. The dependency matrix still +governs where that implementation may live. + +A port implemented only by a consumer (an extension point such as `IArchitectureRule`) fits badly +here: either move it out of the port categories, or record a waiver explaining that the repository +is the contract's publisher, not its implementer. + +### `portPurity` + +A port's property types, return types and parameter types must not name a forbidden prefix. Defaults +cover `Microsoft.EntityFrameworkCore`, `System.Data`, `Microsoft.AspNetCore` and `System.Net.Http`. +Generic arguments count, so `IReadOnlyList` is caught. + +```json +"portRules": { + "enabled": true, + "forbiddenTypePrefixes": ["Microsoft.EntityFrameworkCore", "System.Data"] +} +``` + +A port that names a database or an HTTP client is not a boundary; it is a leak. Move the technology +into the adapter and keep the interface in terms the domain understands. + +## Waivers and scope + +All four rules are waivable per project and per rule, like the rest of the set: + +```json +"waivers": [ + { + "project": "Legacy.Api", + "rules": ["apiSurface"], + "reason": "The published surface is frozen for a major version; the next major captures it.", + "reviewedOn": "2026-10-18" + } +] +``` + +Prefer a narrower setting when the whole repository shares the exception: +`apiRules.requireMemberDocumentation: false`, a different `portRules.categories`, or a longer +`forbiddenTypePrefixes` list. + +## CI + +```yaml +- run: architests api check +``` + +`api check` needs a build but no test run. In the test suite, `apiSurface` does the same comparison, +so a repository that runs its architecture tests does not need the command — it is there for a fast +job and for reviewers who want the diff without running TUnit. + +## See it working + +`src/samples/ArchitectureSample` demonstrates all four rules: `Domain.IOrderRepository` is a port +implemented by `Persistence.InMemory` and `Persistence.Json`, `Application` depends only on the port, +and `.config/api-surface.json` is committed for all six projects. + +## Checklist + +- `apiRules.enabled` and `portRules.enabled` are deliberate. +- The baseline is committed, canonical, and regenerated after every intended API change. +- A removed or changed member is called out as breaking in the pull request. +- Every public type has a ``, and the project generates its XML documentation. +- Ports live in an inner layer, are implemented, and name no infrastructure technology. +- A waiver names one project and one rule, with a reason and a review date. + diff --git a/.agents/skills/purview-architests-extending/SKILL.md b/.agents/skills/purview-architests-extending/SKILL.md new file mode 100644 index 00000000..96267b20 --- /dev/null +++ b/.agents/skills/purview-architests-extending/SKILL.md @@ -0,0 +1,123 @@ +--- +name: purview-architests-extending +description: Use when adding a bespoke rule to Purview.Architecture.Testing, implementing IArchitectureRule, or working on the package's internals - the three-layer design, the project graph, the metadata-only assembly reader, or the evaluator. Covers the ArchitectureContext, what an additional rule gets for free, and testing a rule against an in-memory fixture. +license: MIT +metadata: + product: Purview.Architecture.Testing + repository: purview-dev/architests +--- + +# Extending Purview.Architecture.Testing + +A repository can add a bespoke check without a second architecture framework. This skill covers the +extension point and the internals a rule is built on. To *consume* the package — adopting it, +writing a policy, reading a failure — use the `purview-architests` skill instead. + +## Add a rule + +Implement `IArchitectureRule` and list it in `AdditionalRules`: + +```csharp +using Purview.Architecture.Testing; + +[InheritsTests] +public sealed class ArchitectureTests : PurviewArchitectureTests +{ + protected override IReadOnlyList AdditionalRules => [new NoConsoleLoggingRule()]; + + sealed class NoConsoleLoggingRule : IArchitectureRule + { + public string Rule => "noConsoleLogging"; + + public IReadOnlyList Evaluate(ArchitectureContext context) => + context.Projects.Values + .Where(project => !project.IsTestProject) + // ...inspect the project or its assembly... + .Select(project => new ArchitectureViolation(Rule, project.Name, "Console logging is banned here.")) + .ToArray(); + } +} +``` + +The `Rule` id is the key everywhere: it names the generated test, it is what `SkipRule` receives, and +it is what a waiver's `rules` array matches. + +## What the context gives you + +`ArchitectureContext` carries the three inputs a rule can need: + +| Member | What it is | +| -- | -- | +| `Policy` | The parsed `ArchitecturePolicy`, so a rule reads the same definition the built-in rules do. | +| `Projects` | The project graph, keyed by project name, with declared references, packages, framework references and analyzers. | +| `Assemblies` | The compiled assemblies, keyed by project name, each with the external types it references. Empty when `assemblyRules.enabled` is false. | + +`ArchitecturePolicy.Classify(projectName)` is the classification every built-in rule uses — the first +segment of the project name, honouring aliases and a waiver's `mapsTo`. Use it so a custom rule +agrees with the standard set. + +## What an additional rule gets for free + +- **Its own `[Test]`.** Each rule id becomes a case of + `AdditionalRule_GivenTheRepository_RespectsThePolicy`, so a failure names the rule rather than + collapsing into one assertion. +- **`SkipRule`.** Override `SkipRule` and return `true` for the rule id. +- **Waivers.** A waiver whose `rules` names the rule id is honoured automatically, so a reviewed, + per-project departure needs no code. +- **Reporting.** `ArchitecturePolicyEvaluator.Report` renders the violations, and the failure's + `.Because(...)` lists every one. + +A violation's `Project` must be the project name (or the offender a waiver can name), and its `Rule` +must be the rule id, or the waiver filter cannot match it. + +## Test the rule against a fixture + +The evaluator takes an in-memory graph, so a rule is tested as a small fixture rather than a +repository on disk — exactly how the package's own rules are tested: + +```csharp +var evaluator = new ArchitecturePolicyEvaluator( + policy, + projects, + assemblies, + [new NoConsoleLoggingRule()] +); + +await Assert.That(evaluator.EvaluateAdditionalRule("noConsoleLogging")).IsEmpty(); +``` + +`ArchitecturePolicyEvaluator` also has a two-argument constructor for project-only rules, and a +four-argument one when the rule needs the assembly graph. + +## The three layers (non-negotiable) + +Keep the separation, because it is what makes a rule testable: + +- **`ArchitecturePolicy` / `ProjectGraph` / `AssemblyGraph`** — read the policy, the `.csproj` graph + and the compiled assembly metadata. **No MSBuild and no test-framework types.** +- **`ArchitecturePolicyEvaluator`** — the rules, returning typed `ArchitectureViolation` lists. It + takes an **in-memory graph**, so a rule is testable as a small fixture. +- **`PurviewArchitectureTests`** — the TUnit wrapper, one `[Test]` per rule. + +Every new rule must be evaluable from an in-memory fixture and asserted by a small +`ArchitectureTesting.UnitTests` test. + +## Reading assemblies + +- Read compiled assemblies by **metadata only** (`System.Reflection.Metadata`). Never `Assembly.Load` + or any API that executes code or needs a probing path. +- The `TypeReference` table is the dependency set: base types, interfaces, generic arguments, + signatures, attributes and method-body uses all appear there. +- Attribute an assembly to a project by the SDK's generated `Assembly` marker, falling + back to an exact project-name match. An assembly that maps to no project is a package and is + ignored — a package is never a project. +- Resolve references against the set of assemblies actually scanned, never by name guessing. + +## Repository conventions + +- TUnit on Microsoft.Testing.Platform. No xUnit, NUnit, MSTest or FluentAssertions. +- Tests use AAA and `Subject_Scenario_Expectation` naming, and must pass on Windows, Linux and macOS. +- `architecture-policy.schema.json` at the repository root is both the published schema and the + resource embedded in the package. Never keep a second copy. +- The repository applies its own package to itself (`src/tests/Repository.UnitTests`), with the + sample at `src/samples/ArchitectureSample` showing consumer adoption. diff --git a/.agents/skills/purview-architests-migration/SKILL.md b/.agents/skills/purview-architests-migration/SKILL.md new file mode 100644 index 00000000..d2b5063b --- /dev/null +++ b/.agents/skills/purview-architests-migration/SKILL.md @@ -0,0 +1,143 @@ +--- +name: purview-architests-migration +description: Use when adopting Purview.Architecture.Testing in an existing repository that already has tangled dependencies, or when ratcheting an adopted policy tighter. Covers a permissive first policy, committing the API baseline before enforcing it, recording narrow waivers instead of using SkipRule, starting an empty dependency budget, and tightening one rule at a time without a big-bang rewrite. +license: MIT +metadata: + product: Purview.Architecture.Testing + repository: purview-dev/architests +--- + +# Migrating an existing repository + +A policy that describes the architecture you wish you had fails on day one and gets switched off. +Adopt the architecture you **do** have, then tighten it one reviewed step at a time. The rules are +the same either way; only the policy and the waivers change. + +## 1. Inventory before writing the policy + +- List every production project and what it references. `architests graph` prints the graph once the + policy can find the projects. +- Group projects into responsibilities that describe what they are for, not where they sit. A + qualified name (`Persistence.SqlServer`) belongs to `Persistence`; only the first segment counts. +- Name the composition root with `category: "composition"` and hosts with `category: "host"`, so the + composition boundary works without special cases. + +## 2. A permissive first policy + +Start with the full dependency closure permitted. The first run should fail only on things you are +ready to fix — usually naming. + +```json +{ + "version": 3, + "sourceRoots": ["src"], + "responsibilities": [ + { + "name": "Domain", + "category": "domain", + "purpose": "The domain model and its invariants.", + "mayDependOn": ["Application", "Persistence", "Composition"], + "mustNotDependOn": [] + } + ] +} +``` + +Set `sourceRoots` correctly first: an empty graph makes every rule pass vacuously, which is why +`graphDiscovery` fails instead. + +## 3. Add the test class once + +```csharp +[InheritsTests] +public sealed class ArchitectureTests : PurviewArchitectureTests; +``` + +`[InheritsTests]` is load-bearing. Without it the run is green and nothing is checked. + +## 4. Record the API before enforcing it + +If the public API is already shipped, capture it before enabling `apiRules`: + +```bash +architests api capture +``` + +Then enable the group. The first `apiSurface` run compares against the API you actually have, so it +passes, and every later change becomes a reviewed diff. Do the same for the sample or any package in +the repository. + +## 5. Waivers, not skips + +When a rule finds a real departure you cannot fix today, record it: + +```json +"waivers": [ + { + "project": "Legacy.Utilities", + "mapsTo": "Shared", + "rules": ["naming"], + "reason": "The package id is published; renaming it is a separate breaking release.", + "reviewedOn": "2026-10-18" + } +] +``` + +- `mapsTo` keeps every dependency rule in force; only the name is excused. +- Excuse one rule, not the whole set. +- Set `waiverPolicy.maxAgeDays` so a waiver has to be renewed. An unreviewed waiver is how a policy + quietly stops being true. + +`SkipRule` removes a rule for the whole repository with no record. Treat it as a last resort, never +as the adoption strategy. + +## 6. Start the dependency budget empty + +```json +"dependencyBudget": { + "enabled": true, + "failOnStale": true, + "entries": [] +} +``` + +The rule is enabled and checks nothing, which is exactly right: the mechanism is in place. Add an +entry for one project at a time, listing only the references it has today. From then on a new +reference needs a reviewed policy change, and a removed one must be removed from the budget. + +## 7. Tighten one step at a time + +Each step is a small pull request that keeps the suite green: + +1. **Naming.** Add aliases or waivers, then rename projects in a dedicated change. +2. **Forbidden packages.** Add one prefix to one responsibility, fix the violations, repeat. +3. **Dependency direction.** Move a single edge from `mayDependOn` to `mustNotDependOn`, or remove it + from `mayDependOn` entirely so silence becomes a violation. +4. **Type rules.** Enable `typeRules` for one category with `sealConcreteClasses` and generated-code + exclusions, fix, then widen the scope. +5. **Ports.** Move an interface into `domain` or `application` only when its implementation lives in + an adapter and its signature is technology-neutral. +6. **Reachability.** Turn on `policyIntegrity.checkReachability` once the matrix is honest; it will + find prohibitions the permitted closure bypasses. + +A rule that cannot pass even with waivers is telling you the policy is wrong, not the code. Change +the policy. + +## Reading a failure during migration + +- `naming` — add an alias for an established name, or a waiver with `mapsTo`. +- `dependencyMatrix` / `assemblyDependencyMatrix` — the message names the reference, the direction + and the likely fix. Prefer moving a type over widening `mayDependOn`. +- `apiSurface` — expected after any intentional API change: run `architests api capture` and review + the diff before committing. +- `dependencyBudget` — a new reference is over budget; a stale allowance needs removing. +- `policyIntegrity` — the policy contradicts itself; fix the policy before the code. + +## Checklist + +- `sourceRoots` finds the projects, and `graphDiscovery` passes. +- The matrix describes today's graph, not the target graph. +- The API baseline is committed before `apiRules` is switched on. +- Every departure is a narrow, dated waiver rather than a skip. +- The dependency budget starts empty and grows one reviewed entry at a time. +- Each tightening step is its own pull request, with the suite green. diff --git a/.agents/skills/purview-architests-policy-authoring/SKILL.md b/.agents/skills/purview-architests-policy-authoring/SKILL.md new file mode 100644 index 00000000..9f1f2f52 --- /dev/null +++ b/.agents/skills/purview-architests-policy-authoring/SKILL.md @@ -0,0 +1,190 @@ +--- +name: purview-architests-policy-authoring +description: Use when authoring or changing .config/architecture-policy.json for Purview.Architecture.Testing - defining responsibilities, categories, mayDependOn and mustNotDependOn, choosing sourceRoots, adding aliases, recording a waiver, setting waiver expiry, or fixing a policyIntegrity failure. Covers the version-3 document, the matrix semantics, and how to validate a policy without running the tests. +license: MIT +metadata: + product: Purview.Architecture.Testing + repository: purview-dev/architests +--- + +# Authoring an architecture policy + +The policy is the definition of the architecture. The tests only report what it says, so a vague or +contradictory policy produces a vague or contradictory suite. This skill is about getting the +document right; to *adopt* the package or read a failure, use `purview-architests` instead. + +## The shape + +`.config/architecture-policy.json` at the repository root: + +```json +{ + "$schema": "https://raw.githubusercontent.com/purview-dev/architests/main/architecture-policy.schema.json", + "version": 3, + "description": "What this repository's architecture is.", + "sourceRoots": ["src"], + "responsibilities": [ + { + "name": "Core", + "aliases": ["Domain"], + "category": "domain", + "purpose": "The domain model, its invariants and its rules.", + "mayDependOn": [], + "mustNotDependOn": ["Application", "Persistence", "Composition"], + "forbiddenFrameworkReferences": ["Microsoft.AspNetCore.App"] + } + ] +} +``` + +`version` and `responsibilities` are required. Everything else is optional. Version 3 adds +`policyIntegrity` and `waiverPolicy`; both are optional, so a version-2 document remains valid. + +## Responsibilities + +A project name is `[.]`, and only the **first segment** is +classified. `Persistence.SqlServer` and `Persistence` are both Persistence: qualification is a +naming choice, never a different set of rules. + +| Field | Guidance | +| -- | -- | +| `name` | One PascalCase segment. Name the role, not the technology. | +| `aliases` | Existing names you are not renaming. Prefer renaming and deleting the alias. | +| `category` | `domain`, `application`, `infrastructure`, `composition`, `host` or `shared`. `composition` is the exemption `compositionBoundary` keys on; `host` may also reference it. | +| `purpose` | At least 20 characters, and quoted in failures. Write why the responsibility exists; "misc" is not a purpose. | +| `mayDependOn` | The complete set of permitted references. Silence is not permission. | +| `mustNotDependOn` | Prohibitions that matter. Must not overlap `mayDependOn`. | +| `forbiddenPackagePrefixes` | NuGet prefixes that must never appear, such as `Microsoft.EntityFrameworkCore`. | +| `forbiddenPackageScope` | `own` (default) reports packages the project declares or its own packages pull in; `closure` also reports packages inherited from project references. | +| `forbiddenFrameworkReferences` | Framework prefixes, such as `Microsoft.AspNetCore.App` in a portable layer. | +| `siblingIndependence` | When true, qualified implementations of this responsibility must not reference each other. | + +Avoid names that describe a category. `Infrastructure`, `Services`, `Helpers`, `Common`, +`Utilities` and `Managers` are discouraged because nothing can be kept out of them. + +## The matrix is three-way + +For every declared reference, and for every type reference in the compiled assemblies: + +1. **Same responsibility** is always allowed. +2. **`mustNotDependOn`** is a violation. +3. **`mayDependOn`** is permitted. + +Anything else is a violation. That is deliberate: an unclassified dependency is a gap in the +policy, not an implicit yes. When a new edge is genuinely intended, add it to `mayDependOn` — that +is a reviewed policy change, which is the point. + +## Policy integrity + +`policyIntegrity` always runs and cannot be waived. It catches what the schema cannot: + +- a matrix entry that names no responsibility (aliases and project names are not names here); +- the same responsibility in both `mayDependOn` and `mustNotDependOn`; +- two responsibilities with the same name; +- an alias equal to a name, or two responsibilities claiming the same alias; +- with `checkReachability`, a prohibition the permitted dependencies can reach anyway. The failure + prints the path, such as `Core -> Application -> Persistence`, so the edge to remove is obvious. + +```json +"policyIntegrity": { + "checkReachability": true +} +``` + +Reachability is opt-in because it is the stronger claim: the lists can be consistent while a longer +permitted path still defeats the prohibition. + +## Waivers + +A waiver is a reviewed departure, not a skip: + +```json +"waivers": [ + { + "project": "Legacy.Utilities", + "mapsTo": "Shared", + "rules": ["naming"], + "reason": "Predates the catalogue; renaming breaks a published package identifier.", + "reviewedOn": "2026-10-18" + } +] +``` + +- `mapsTo` is the useful part: the project keeps its real responsibility, so every dependency rule + still applies and only the **name** is excused. +- Excuse the narrowest rule that applies. A waiver listing everything is a policy opt-out. +- `policyIntegrity`, `graphDiscovery` and `waiverIntegrity` cannot be waived; naming one is a + `waiverIntegrity` failure. + +### Expiry + +```json +"waiverPolicy": { + "maxAgeDays": 180 +} +``` + +A waiver older than the maximum is a `waiverIntegrity` failure. So are an undated waiver while a +maximum is set, a date that is not `yyyy-MM-dd`, and a date in the future. Expiry is off by default; +adopt it deliberately, and expect to renew or delete the waivers it surfaces. + +### Package scope + +`forbiddenPackagePrefixes` measures **ownership** by default: what the project declares, what a +shared props file injected, and what its own package references pull in. A package inherited through +a permitted project reference is not owned, so a host is not reported for its adapter’s EF Core. + +Use `"forbiddenPackageScope": "closure"` only when the policy means “this technology must not be +anywhere on the compile graph”. That makes hosts responsible for every package their adapters bring +in, and usually requires the adapter to mark implementation packages `PrivateAssets="compile"`. + +## Dependency budget + +`dependencyBudget` ratchets the project graph: it records the references each project may declare +today, so growth is a reviewed policy change. + +```json +"dependencyBudget": { + "enabled": true, + "failOnStale": true, + "entries": [ + { "project": "Application", "references": ["Domain"] }, + { "project": "Persistence.SqlServer", "references": ["Domain", "Application"] } + ] +} +``` + +- An entry lists **project names**, exactly as they appear on disk, including the qualification: + `Persistence.SqlServer`, not `Persistence`. +- A reference outside the entry is a failure. Remove it, or add it in the same reviewed commit that + adds the `ProjectReference`. +- With `failOnStale` (default true), an allowance the project no longer uses is a failure. Tighten the + budget rather than leaving a permission nobody needs. +- A project with no entry is not budgeted. Start with `entries: []`, then add one project at a time. +- The rule is not waivable; changing the budget is the sanctioned way to change the graph. + +## Validate the policy + +```bash +dotnet tool install --global Purview.Architecture.Testing.Cli +architests validate +architests waivers list --stale +``` + +`validate` runs the schema check and `policyIntegrity` without a build; `waivers list --stale` exits +non-zero when a waiver is due. Exit codes: `0` clean, `1` findings, `2` a malformed command line. +Both commands accept `--repository `. + +The test suite runs the same checks and one test per rule, so a policy that passes the tool can +still fail a matrix rule — that failure is an architecture decision, not a document error. + +## Checklist + +- Every responsibility has a purpose that says what it is for, not what it uses. +- Every dependency that exists is either permitted or forbidden; nothing is left unclassified. +- `mustNotDependOn` entries are not also in `mayDependOn`. +- Names are roles, not categories, and no alias duplicates a name. +- Waivers are narrow, justified, dated, and none is due. +- `policyIntegrity.checkReachability` is on before claiming a prohibition is enforced. +- A version bump is deliberate: adding optional sections does not require one. + diff --git a/.agents/skills/purview-architests-type-rules/SKILL.md b/.agents/skills/purview-architests-type-rules/SKILL.md new file mode 100644 index 00000000..1d933788 --- /dev/null +++ b/.agents/skills/purview-architests-type-rules/SKILL.md @@ -0,0 +1,188 @@ +--- +name: purview-architests-type-rules +description: Use when enabling or debugging Purview.Architecture.Testing's type-level rules - typeNaming, typeShape, typeNamespace and attributePolicy. Covers the typeRules policy section, which public types are governed, why a type is reported as unsealed or outside its root namespace, how generated code and nested types are treated, and how to fix or waive each finding. +license: MIT +metadata: + product: Purview.Architecture.Testing + repository: purview-dev/architests +--- + +# Type-level naming, shape and namespace rules + +These rules police the **public surface** a project compiles, not its dependencies. They read the +compiled assembly by metadata only: no assembly is loaded, no code runs, and no source file is +needed. Enable them when the API a consumer receives matters as much as the direction its +references run. + +For dependency direction, use the `purview-architests` skill. This skill covers `typeNaming`, +`typeShape`, `typeNamespace` and `attributePolicy`. + +## Enable them + +They are off by default, because they need a build to have produced the assemblies: + +```json +{ + "assemblyRules": { "enabled": true }, + "typeRules": { + "enabled": true, + "appliesTo": { "categories": ["domain", "application", "shared"] }, + "excludeGeneratedCode": true + } +} +``` + +- An empty `appliesTo.categories` governs **every production responsibility**. +- Test projects are never governed. +- `assemblyRules` and `typeRules` scan the same assemblies. `assemblyRoots` and `assemblyGlobs` live + under `assemblyRules` and apply to both; an empty `assemblyRoots` scans the test output directory. +- Only **public** types are checked, including public nested types. Internal and private types are + outside the API and are left alone. + +## What the four rules catch + +| Rule | Catches | +| -- | -- | +| `typeNaming` | An interface without `I`, an attribute without `Attribute`, an exception without `Exception`, a discouraged suffix (`Manager`, `Helper`, `Util`, `Impl`) | +| `typeShape` | An unsealed public class, a public instance field, a mutable collection return, a misnamed exception, a utility class that is not static | +| `typeNamespace` | A public type outside the project's `RootNamespace` | +| `attributePolicy` | A missing required attribute, a forbidden attribute, `[Obsolete]` without a message, `InternalsVisibleTo` naming production code | + +Each enabled rule becomes its own TUnit test. A disabled group produces **no** type-rule test rather +than a test that checks nothing, so a green run cannot mean "the group was off". + +## Governing a subset + +`appliesTo.categories` is the usual scope. A composition root is often excluded because it is allowed +to reference everything: + +```json +"appliesTo": { "categories": ["domain", "application", "infrastructure", "shared"] } +``` + +Generated code is skipped by default. A source generator must not be forced to change its output: + +```json +"excludeGeneratedCode": true, +"excludeNamespacePrefixes": ["Contoso.Generated"] +``` + +A type marked `[GeneratedCode]` or `[CompilerGenerated]` is skipped, as is any type under an excluded +namespace prefix. + +## Type naming + +- An interface name must start with `I` followed by an uppercase letter: `IOrderRepository`. +- A class deriving from `System.Attribute` must end with `Attribute`. +- A class deriving from an exception must end with `Exception`. +- A type ending with a configured `discouragedTypeSuffixes` entry is reported. The default list + names mechanisms, not responsibilities. Configure it to match the repository's vocabulary. + +Generic arity is removed before the check, so `IRepository` is checked as `IRepository`. + +## Type shape + +- **Unsealed public class.** A public concrete class must be `sealed` unless it is `abstract`. An + unsealed class is a public extension point nobody declared; seal it, or make the base type explicit. +- **Public instance field.** Constants and static readonly fields are fine; an instance field cannot + validate or evolve without a breaking change. +- **Mutable collection return.** A public property or method returning `List` or + `Dictionary` hands the caller the owner's state. Return `IReadOnlyList` or + `IReadOnlyDictionary`. +- **Misnamed exception.** A class named `...Exception` must derive from `System.Exception`. +- **Utility class.** A class with only static members and no public constructor must be declared + `static`, so it cannot be instantiated by accident. + +Turn off either check in the policy when it does not fit: + +```json +"sealConcreteClasses": false, +"requireReadOnlyCollections": false +``` + +## Type namespace + +The rule compares the type's declared namespace with the project's `RootNamespace`, read from the +`.csproj`: the namespace must equal it or start with it followed by a dot. + +Metadata records the namespace, not the file path, so the rule **cannot** check that the folder +matches. It deliberately makes no such claim. + +Set `RootNamespace` explicitly when it differs from the project name: + +```xml +Purview.Architecture.Testing +``` + +Without it, the project name is used, which is the SDK's own fallback. + +## Attribute policy + +| Setting | Default | Effect | +| -- | -- | -- | +| `requiredAttributes` | `[]` | Namespace-qualified attributes every governed public type must carry | +| `forbiddenAttributes` | `[]` | Namespace-qualified attributes no governed public type may carry | +| `allowObsoleteWithoutMessage` | `false` | Permit `[Obsolete]` with no message | +| `forbidInternalsVisibleToProduction` | `true` | Reject `InternalsVisibleTo` naming a production assembly | + +`[Obsolete("Use IOrderStore instead.")]` is fine. A bare `[Obsolete]` is reported: a caller is told +the type is going away but not what to do about it. + +`InternalsVisibleTo` is checked at assembly level. A friend that maps to a **test** project is +ordinary; a friend that maps to a **production** project is a boundary leak, because the referenced +project can now see internals it was never meant to depend on. Expose a public abstraction instead. + +## Fix or waive + +Fix the type when the rule is right; rename it, seal it, return a read-only interface, or move it +under the root namespace. + +A waiver is per project and per rule, and the project field is the **project name** the assembly +belongs to: + +```json +"waivers": [ + { + "project": "Persistence", + "rules": ["typeShape"], + "reason": "The EF entity must stay inheritable for the proxy; sealing it breaks materialisation.", + "reviewedOn": "2026-10-18" + } +] +``` + +Prefer the narrow settings when the whole repository shares an exception: `excludeNamespacePrefixes` +for generated code, `sealConcreteClasses` for a codebase that uses inheritance as a feature, or +`appliesTo.categories` to leave the composition root out. + +## Troubleshooting + +- **No type-rule tests at all.** `typeRules.enabled` is false, or the policy failed to load. The + group produces no test rather than a vacuous pass, so this is visible in the test list. +- **A rule reports nothing and you expected findings.** The projects were not built, or the + assembly was not in the scan root. Type rules use `assemblyRules.assemblyRoots`; an empty value + scans the test output directory, so the test project must reference the projects it governs. +- **A type you expected is missing.** It is internal, nested inside an internal type, marked as + generated, under an excluded namespace, in a test project, or in a responsibility outside + `appliesTo.categories`. +- **`typeNamespace` reports everything.** The project has no `RootNamespace` and its namespace is + not the project name. Set `RootNamespace` explicitly. +- **A public API baseline is also enabled.** Type-rule findings are API-shape findings; fix them + before regenerating a baseline, or the baseline records the problem. + +## See it working + +`src/samples/ArchitectureSample` enables `typeRules` for the `domain`, `application`, `infrastructure` +and `shared` categories. Its projects declare `RootNamespace` explicitly, its classes are sealed, its +collections are exposed as `IReadOnlyList`, and `IOrderRepository` follows the interface +convention. + +## Checklist + +- `typeRules.enabled` is true and the categories are deliberate. +- Every governed public class is sealed or abstract, unless `sealConcreteClasses` is off. +- No public instance fields or mutable collection returns are exposed. +- `RootNamespace` is set on projects whose namespace differs from their name. +- Generated code is excluded by attribute or namespace, not by loosening the rule. +- Every waiver names one project and one rule, with a reason and a review date. + diff --git a/.agents/skills/purview-architests/SKILL.md b/.agents/skills/purview-architests/SKILL.md new file mode 100644 index 00000000..dd9d5db6 --- /dev/null +++ b/.agents/skills/purview-architests/SKILL.md @@ -0,0 +1,354 @@ +--- +name: purview-architests +description: Adopt or debug Purview.Architecture.Testing, the package that enforces a repository's project and type-level dependency policy as TUnit tests. Use when adding architecture tests to a repository, writing or changing .config/architecture-policy.json, validating a policy with the architests tool, enabling the assembly, type, API or port rules, recording or expiring a waiver, setting a dependency budget, interpreting a policy-integrity, dependency-matrix, type-level, cycle, sibling-independence, composition-boundary, forbidden-package, framework-reference or naming failure, or when the architecture tests pass but enforce nothing. +license: MIT +metadata: + product: Purview.Architecture.Testing + repository: purview-dev/architests +--- + +# Architecture tests with Purview.Architecture.Testing + +The package defines the rules once so a policy is not copied into every repository's test project. + +## Adoption is two things + +**1. A policy file** at `.config/architecture-policy.json`: + +```json +{ + "$schema": "https://raw.githubusercontent.com/purview-dev/architests/main/architecture-policy.schema.json", + "version": 3, + "sourceRoots": ["src"], + "responsibilities": [ + { + "name": "Core", + "aliases": ["Domain"], + "category": "domain", + "purpose": "The domain model, its invariants and its rules.", + "mayDependOn": [], + "mustNotDependOn": ["Application", "Persistence"], + "forbiddenFrameworkReferences": ["Microsoft.AspNetCore.App"] + } + ] +} +``` + +**2. One derived test class:** + +```csharp +[InheritsTests] +public sealed class ArchitectureTests : PurviewArchitectureTests; +``` + +## `[InheritsTests]` is load-bearing + +TUnit does **not** walk base types during discovery. Without the attribute the class compiles, the +run is green, and nothing is enforced — the worst failure this package can have. + +TUnit's analyzer reports `TUnit0030` when it is missing. Treat it as an error, not a suggestion. + +If the architecture tests "pass" but you cannot name which rule ran, check this first. + +## The rules + +| Rule id | Test | What it catches | +| -- | -- | -- | +| `policyIntegrity` | `Policy_GivenItsOwnDefinitions_IsConsistent` | An unknown responsibility name, a dependency both permitted and forbidden, or a duplicate name or alias. Not waivable | +| `graphDiscovery` | `Repository_GivenItsSourceRoots_YieldsProjectsToCheck` | An empty graph — which satisfies every other rule | +| `naming` | `ProductionProjects_GivenTheirNames_MapToAResponsibility` | A project name matching no responsibility or alias | +| `discouragedName` | `ProductionProjects_GivenTheirNames_AvoidCatchAllNames` | A project named after a category, so nothing can be kept out of it | +| `dependencyMatrix` | `ProductionProjects_GivenTheirReferences_RespectTheDependencyMatrix` | A declared `ProjectReference` the matrix forbids or does not permit | +| `assemblyDependencyMatrix` | `AssemblyTypes_GivenTheirReferences_RespectTheDependencyMatrix` | A **type** in one responsibility using a type in another, including a dependency that only arrives transitively or through a package | +| `typeNaming` | `TypeRules_GivenTheRepository_RespectThePolicy` | A public interface without `I`, an attribute or exception without its suffix, or a discouraged suffix | +| `typeShape` | `TypeRules_GivenTheRepository_RespectThePolicy` | An unsealed public class, a public field, a mutable collection return, or a non-static utility class | +| `typeNamespace` | `TypeRules_GivenTheRepository_RespectThePolicy` | A public type outside the project's root namespace | +| `attributePolicy` | `TypeRules_GivenTheRepository_RespectThePolicy` | A missing or forbidden attribute, `[Obsolete]` without a message, or `InternalsVisibleTo` naming production code | +| `apiSurface` | `APIRules_GivenTheRepository_RespectThePolicy` | The public API differs from the committed baseline | +| `apiDocumentation` | `APIRules_GivenTheRepository_RespectThePolicy` | A public type or member has no XML documentation | +| `portImplementation` | `PortRules_GivenTheRepository_RespectThePolicy` | A port in an inner layer has no implementation | +| `portPurity` | `PortRules_GivenTheRepository_RespectThePolicy` | A port exposes an infrastructure technology | +| `dependencyBudget` | `AdoptionRules_GivenTheRepository_RespectThePolicy` | A project references beyond its budget, or the budget still allows a reference that has gone | +| `siblingIndependence` | `SiblingImplementations_GivenTheirReferences_DoNotDependOnEachOther` | A qualified implementation referencing a qualified sibling | +| `compositionBoundary` | `Implementations_GivenTheirReferences_DoNotDependOnComposition` | A non-host project referencing the composition root (`category == "composition"`) | +| `forbiddenPackage` | `ProductionProjects_GivenTheirPackages_AvoidForbiddenFrameworkDependencies` | A package matching a forbidden prefix for that responsibility | +| `forbiddenFramework` | `ProductionProjects_GivenTheirFrameworkReferences_AvoidForbiddenFrameworks` | A `` matching a forbidden prefix, e.g. `Microsoft.AspNetCore.App` in a portable layer | +| `cycle` | `ProjectGraph_GivenItsReferences_HasNoCycles` | A dependency cycle, reported readably | +| `testReference` | `ProductionProjects_GivenTheirReferences_DoNotReferenceATestProject` | Production code referencing a test project | +| `waiverIntegrity` | `PolicyWaivers_GivenTheirDefinitions_AreJustifiedAndStillApply` | A waiver that is stale, unjustified, malformed, or excuses an unknown rule id | + +A separate test validates the policy against the schema first, because a policy that does not match +its schema may be silently missing a rule. + +## Policy integrity + +`policyIntegrity` always runs and is **not waivable**, so a broken policy cannot be excused. It +reports what a JSON Schema cannot express: + +- a `mayDependOn` or `mustNotDependOn` entry that names no responsibility — aliases and project + names do not count in the matrix; +- the same responsibility in both lists, which is a contradiction rather than a choice; +- two responsibilities with the same name, or an alias that equals a name or another alias; +- with `checkReachability`, a `mustNotDependOn` the permitted `mayDependOn` closure can reach. The + message prints the path, such as `Core -> Application -> Persistence`. + +```json +"policyIntegrity": { + "checkReachability": true +} +``` + +Reachability is opt-in because it is a stronger claim: the direct lists can be consistent while a +longer permitted path still defeats the prohibition. + +## Check it without a test run + +```bash +dotnet tool install --global Purview.Architecture.Testing.Cli +architests validate +architests waivers list --stale +``` + +`validate` runs the schema check and `policyIntegrity`; it needs no build. Exit codes are `0` clean, +`1` findings, `2` a malformed command line. Both commands accept `--repository `; without it +the tool walks up from the current directory and stops at the repository boundary. + +`graphDiscovery` runs before the rules it protects. If `sourceRoots` is wrong, discovery finds +nothing and every other rule passes vacuously — that is what this rule exists to stop. + +## The type-level rule + +A project file only shows a declared `ProjectReference`. `assemblyDependencyMatrix` reads the +compiled assemblies by **metadata only** — no assembly is loaded or executed — and checks every +external type each one references against the same `mayDependOn` / `mustNotDependOn` matrix. It +catches what a project file cannot: a type that only arrives transitively, or through a package. + +```json +"assemblyRules": { + "enabled": true, + "assemblyRoots": [], + "assemblyGlobs": ["*.dll"] +} +``` + +- **Off by default.** It needs a build to have produced the assemblies, so it is opt-in. +- An empty `assemblyRoots` scans the test output directory, which already holds every project the + test project references, directly or transitively. Set it to repo-relative folders only if the + assemblies are somewhere else. +- Semantics mirror `dependencyMatrix`: same-responsibility references are always allowed; a + reference the matrix neither permits nor forbids is a violation. +- Enabled with nothing found is a **failure**, not a silent pass — the same guard `graphDiscovery` + provides for projects. +- Qualified implementations collapse into their responsibility, so `Persistence.SqlServer` is + `Persistence` at the type level too. Qualification is a naming choice, never a different rule. + +Assemblies are attributed to projects by the SDK's generated `Assembly` marker when a +project's `AssemblyName` is unrelated to its name, and by name otherwise. + +## Type naming, shape and namespace + +The same reader exposes the public declarations a project compiles, which powers four opt-in rules: +`typeNaming`, `typeShape`, `typeNamespace` and `attributePolicy`. They are configured under +`typeRules`, off by default, and share the assembly roots and globs above. + +```json +"typeRules": { + "enabled": true, + "appliesTo": { "categories": ["domain", "application", "shared"] } +} +``` + +Use the `purview-architests-type-rules` skill for what each rule catches, why a type is reported, and +how to fix or waive it. A disabled group produces no test, so a missing type-rule test is a policy +setting rather than a silent pass. + +## Classifying test and production projects + +The package decides which projects the rules govern from the project graph: + +- A project is a **test project** when its name ends with `Tests`, **or** its path contains a + `tests` directory. Test projects are excluded from every rule — a test references everything by + design, so applying the matrix to it would make the rule set unusable. +- Everything else is a **production project**, and every rule applies to it. + +## API baseline and ports + +Four more rules are opt-in. `apiRules` compares the public API with a committed baseline and checks +its documentation; `portRules` checks that inner-layer interfaces are implemented and stay +technology-neutral. + +```json +"apiRules": { "enabled": true }, +"portRules": { "enabled": true } +``` + +Write the baseline with the tool, never by hand: + +```bash +architests api capture # write .config/api-surface.json +architests api check # exit 1 on any difference +``` + +A missing baseline is itself an `apiSurface` failure. A removal is reported as breaking; an addition +still needs a reviewed baseline change, because the baseline is the contract. The +`purview-architests-contracts` skill covers the baseline document, documentation requirements and +the port rules in detail. + +## Dependency budget + +`dependencyBudget` is a ratchet on the project graph: it records the references each project may +declare today, so a new dependency needs a reviewed policy change. + +```json +"dependencyBudget": { + "enabled": true, + "failOnStale": true, + "entries": [ + { "project": "Application", "references": ["Domain"] } + ] +} +``` + +- A reference outside the entry is a `dependencyBudget` failure. +- With `failOnStale` (the default), an allowance the project no longer uses fails too, so the budget + only tightens. +- It is **not waivable**, and a project without an entry is not budgeted. +- Start with `entries: []`, then add one project at a time. + +## See it working + +`src/samples/ArchitectureSample` is a six-project repository that exercises every rule group: a port +with two adapters, a waived legacy project, the type rules, the committed baseline and a dependency +budget. Use it as the reference when a policy question is easier to answer from a working example +than from prose. + +## Prefer a waiver to a skip + +```csharp +protected override bool SkipRule(string rule) => rule == ArchitectureRules.DiscouragedName; +``` + +`SkipRule` removes a rule for the whole repository, with no record. A waiver is better: it is per +project, carries a reason and a review date, keeps every other rule in force for that project, and +is itself checked by `waiverIntegrity`. + +```json +"waivers": [ + { + "project": "Legacy.Utilities", + "mapsTo": "Shared", + "rules": ["naming"], + "reason": "Predates the catalogue; renaming breaks a published package id.", + "reviewedOn": "2026-01-14" + } +] +``` + +`mapsTo` is the useful part: it maps an established project onto the responsibility it actually has, +so the dependency rules still apply in full and only the *name* is excused. + +Any waivable rule id may be waived, including `siblingIndependence` and `assemblyDependencyMatrix`. +An unknown id is a `waiverIntegrity` failure, so a typo cannot silently excuse nothing. Naming a +guard (`policyIntegrity`, `graphDiscovery` or `waiverIntegrity`) is also a failure: those rules exist +to keep the policy falsifiable, so a waiver that appears to excuse them would be a lie. + +### Waiver expiry + +```json +"waiverPolicy": { + "maxAgeDays": 180 +} +``` + +A waiver reviewed longer ago than the maximum is a `waiverIntegrity` failure. So are a waiver with +no `reviewedOn` while a maximum is set, a date that is not `yyyy-MM-dd`, and a date in the future. +Expiry is off by default; adopting it turns the review date from a note into an obligation. + +## Adding your own rule + +A repository can add a bespoke check without a second architecture framework. Implement +`IArchitectureRule` and return the same `ArchitectureViolation` type as the built-in rules: + +```csharp +[InheritsTests] +public sealed class ArchitectureTests : PurviewArchitectureTests +{ + protected override IReadOnlyList AdditionalRules => [new NoConsoleLoggingRule()]; + + sealed class NoConsoleLoggingRule : IArchitectureRule + { + public string Rule => "noConsoleLogging"; + + public IReadOnlyList Evaluate(ArchitectureContext context) => + // context.Policy, context.Projects and context.Assemblies + []; + } +} +``` + +Each additional rule becomes its own `[Test]` (`AdditionalRule_GivenTheRepository_RespectsThePolicy`), +so a failure names the rule. It participates in the same failure reporting, `SkipRule` (by its +`Rule` id) and waiver model — a waiver whose `rules` names it is honoured automatically. + +The `purview-architests-extending` skill covers the full extension point and the package's internals. + +## Reading a failure + +Each rule is its own test, so a failure names the rule rather than collapsing the set into one +assertion. The `.Because(...)` text lists every violation the rule found. + +- `naming` — a project name is `[.]`, and only the **first segment** + is classified. `Persistence.SqlServer` and `Persistence` are both Persistence. Add an alias, or a + waiver with `mapsTo`. +- `dependencyMatrix` / `assemblyDependencyMatrix` — fix the reference, or move the type. Widening + `mayDependOn` is the last resort, and it is a policy change that needs review. +- `forbiddenPackage` — by default the package is one the project **owns**: declared, injected by + `Directory.Build.props`, or pulled in by its own package references. A package inherited from a + permitted project reference is not reported, so a host is not blamed for its adapter’s EF Core. + Set `forbiddenPackageScope: "closure"` on the responsibility only when the strict compile-graph + guarantee is intended. +- `forbiddenFramework` — a `` on a project that should not have it. Move it to + the responsibility that owns that technology. +- `graphDiscovery` — almost always a wrong `sourceRoots`. An empty array scans the repository root, + which suits a flat layout. +- `assemblyDependencyMatrix` reporting "no compiled assemblies" — the projects were not built, or + `assemblyRoots` points at the wrong folder. + +## The three layers + +Useful when extending the package rather than consuming it: + +- `ArchitecturePolicy` / `ProjectGraph` / `AssemblyGraph` — read the policy, the `.csproj` graph and + the compiled assembly metadata. No MSBuild and no test-framework types. +- `ArchitecturePolicyEvaluator` — the rules, returning typed `ArchitectureViolation` lists. It takes + an **in-memory graph**, so a rule is tested as a three-project fixture rather than a repository on + disk. +- `PurviewArchitectureTests` — the TUnit wrapper, one `[Test]` per rule. + +Project files are read because a declared `ProjectReference` is what a reviewer adds and what the +policy governs; compiled assemblies are read separately because they catch what the project file +does not show. + +## Overrides + +```csharp +[InheritsTests] +public sealed class ArchitectureTests : PurviewArchitectureTests +{ + protected override string? RepositoryRoot => "/path/to/repo"; +} +``` + +`RepositoryRoot` defaults to probing upward from the test binary for the policy file. The search +**stops at the repository boundary** (`.git`) rather than continuing into parent folders — walking +past it would happily find a sibling checkout's policy and validate this repository against someone +else's rules. + +## Policy schema version + +The current policy document version is **3**. Version 3 adds `typeRules`, `policyIntegrity` and +`waiverPolicy`, all optional, so a version-2 policy remains valid. Version 2 removed the `rules` object +(`noCycles`, `noProductionToTestReferences`, `implementationsMustNotReferenceComposition`, +`siblingImplementationsIndependent`), whose flags were deserialised but never consulted. Use +`SkipRule` or a waiver to opt out of a rule. A version-1 policy that set `rules` must delete the +block; a version-1 policy that did not still validates. diff --git a/.agents/skills/purview-buildsdk-adoption/SKILL.md b/.agents/skills/purview-buildsdk-adoption/SKILL.md new file mode 100644 index 00000000..b1f222c5 --- /dev/null +++ b/.agents/skills/purview-buildsdk-adoption/SKILL.md @@ -0,0 +1,114 @@ +--- +name: purview-buildsdk-adoption +description: Adopt Purview.BuildSdk in a repository, or troubleshoot an adoption that is not behaving. Use when wiring the SDK into Directory.Build.props for the first time, when a property seems to have no effect, when the resolved version or namespace is wrong, or when a consuming repository builds but the SDK's automatic behaviour is not appearing. Covers the import chain, pre-import property ordering, and version detection from package.json. +license: MIT +metadata: + package: Purview.BuildSdk + repository: purview-dev/build-sdk +--- + +# Adopting Purview.BuildSdk + +The goal is a working adoption that does not break existing build behaviour. Prefer minimal, +targeted property changes over rewriting a repository's `Directory.Build.props`. + +For the full property list use `purview-buildsdk-configuration`; for auditing an existing +repository's shape, `purview-buildsdk-repository-review`. + +## 1. The import chain + +```xml + + + + + Acme.Sales + + + + +``` + +```xml + + + + +``` + +Both halves are required. A repository with only `Sdk.props` imported gets the evaluation-time +defaults — naming, identity, framework selection — but none of the targets, so validation, +packaging behaviour and the generated files never run. That combination usually presents as "the +properties look right but nothing happens". + +The SDK version comes from `global.json`, which the SDK itself bootstraps. + +## 2. Pre-import ordering is the first thing to check + +**A property that must affect `Sdk.props` evaluation has to be set before the import.** Setting it +in a `.csproj`, or below the import, is too late and silently does nothing — no error, no warning. +This is the single most common adoption failure. + +Set before the import: + +- `NamespacePrefix` +- `UsePackageJsonVersion`, `RootPackageJson` +- `EnableAssemblyNameGeneration` +- `AutoIncludeUsings` +- `PurviewSharedTestingOutputType`, `PurviewTestContextNoWarn` +- any repo-wide testing-framework selection you want every project to inherit + +Everything else is read in `Sdk.targets` and can be set in a project file. + +When a property appears to have no effect, confirm what MSBuild actually resolved before changing +anything else: + +```bash +dotnet msbuild -getProperty:NamespacePrefix -getProperty:RootNamespace +``` + +## 3. Version detection + +Versions come from `package.json`. Resolution order: + +1. An explicit `RootPackageJson`. +2. CI workspace variables. +3. The `.git` root. +4. A nearby `package.json`. + +On success both `Version` and `PackageVersion` are set from the `version` field. + +If the version looks wrong, do not guess at the discovery — make it fail loudly instead: + +```xml +Strict +``` + +`Strict` fails the build when discovery or resolution cannot succeed, rather than silently skipping +it and leaving the default `1.0.0`. Set `VersionDetectionLogEnabled=true` to see what it found. + +## 4. Naming and placement + +Most of the SDK's value is inferred from project names and locations, so an adoption that keeps a +bespoke structure gets correspondingly little. Confirm the repository follows the conventions rather +than introducing new structure to work around them — see `purview-buildsdk-project-layout`, and +`purview-buildsdk-repository-review` for auditing an existing layout. + +The highest-value single check: every test project is named `.Tests`. **The dot is +required.** A project named plainly `UnitTests` is not detected as a test project at all, and +silently gets no runner, no coverage, no `InternalsVisibleTo` and no category. + +## 5. Agent skills are a separate, explicit step + +The SDK does not install agent skills, and nothing it does during a build writes to an agent +directory. It reads which skills each referenced package ships and recommends the command that +installs them; the skills CLI does the installing. See `purview-buildsdk-skill-installation`. + +## Constraints + +- Prefer minimal, targeted property changes over broad `Directory.Build.props` rewrites. +- Do not disable `PurviewAutoSdkPack` unless the consumer explicitly asks to opt out. +- Do not restate an SDK default in a project file. Hand-configuration that merely repeats a default + is pure maintenance cost, and it hides the fact that the default later changed. +- Re-run the build — or the repository's canonical build command — after each change, and confirm + the fix before moving to the next one. diff --git a/.agents/skills/purview-buildsdk-configuration/SKILL.md b/.agents/skills/purview-buildsdk-configuration/SKILL.md new file mode 100644 index 00000000..f0ee7156 --- /dev/null +++ b/.agents/skills/purview-buildsdk-configuration/SKILL.md @@ -0,0 +1,110 @@ +--- +name: purview-buildsdk-configuration +description: Configure Purview.BuildSdk from Directory.Build.props or a .csproj. Use when setting NamespacePrefix, choosing a testing or mocking framework, turning telemetry or SourceLink off, controlling version detection from package.json, tuning the repository bootstrap, or working out whether a property must be set before the SDK import. Also use when the SDK "did something automatically" and you need the property that controls it. +license: MIT +metadata: + package: Purview.BuildSdk + repository: purview-dev/build-sdk +--- + +# Purview.BuildSdk configuration + +Use this skill when the question is "what property controls this, and where do I set it?" + +For *why* the SDK classified a project a particular way, use `purview-buildsdk-project-detection` +instead. For where projects and tests should live, use `purview-buildsdk-project-layout`. + +## First rule: know where a property must be set + +A property that changes `Sdk.props` evaluation must be set **before** the SDK import — in +`Directory.Build.props`, above the import. Setting it in a `.csproj` is too late and silently has no +effect. + +Pre-import properties include: + +- `NamespacePrefix` +- `UsePackageJsonVersion`, `RootPackageJson` +- `EnableAssemblyNameGeneration` +- `PurviewSharedTestingOutputType`, `PurviewTestContextNoWarn` +- `AutoIncludeUsings` +- repo-wide testing-framework selection you want every project to inherit + +Everything else is read in `Sdk.targets` and can be set in a project file. Prefer repo-wide defaults +in `Directory.Build.props` unless the setting is deliberately project-specific. + +## The properties you will reach for most + +| Property | Default | What it does | +| -- | -- | -- | +| `NamespacePrefix` | *(required)* | The root identity. Required unless `DisableNamespacePrefixCheck=true` | +| `TestingFramework` | `TUnit` | `TUnit`, `Xunit` or `None` | +| `SubstituteFramework` | `TUnitMocks` | `TUnitMocks`, `NSubstitute` or `None` | +| `TestDataFramework` | `Bogus` | `Bogus` or `None` | +| `TargetFramework` | `net10.0` | `netstandard2.0` when `IsRoslynComponent=true` | +| `IsPackable` | `false` | Opts a project into the packable defaults | +| `UsePackageJsonVersion` | `true` | `true`, `false` or `Strict` — version from `package.json` | +| `ExcludePurviewTelemetry` | `false` | Drops the telemetry source generator | +| `DisableSourceLink` | `false` | Drops SourceLink from packable projects | +| `EnableAssemblyNameGeneration` | `true` | `AssemblyName`/`PackageId` follow the resolved `RootNamespace` | + +The full set, grouped by area and with the behaviour each one changes, is in +[references/properties.md](references/properties.md). Read it rather than guessing a property name — +several of these have near-miss names that do nothing. + +## Derived properties to inspect, not re-derive + +When explaining what the SDK did, read the value it computed rather than reasoning from the folder +name: + +`PurviewLogicalProjectName`, `PurviewNamespacePrefix`, `PurviewProjectShortName`, `PurviewTestType`, +`RootNamespace`, `AssemblyName`, `PackageVersion`, `TestingType`, `TargetProjectName`, `RepoRoot`, +`RootPackageJson`. + +Ask MSBuild for one directly: + +```bash +dotnet msbuild -getProperty:RootNamespace +dotnet msbuild -getProperty:TestingType -getProperty:TargetProjectName +``` + +## Compiler-visible properties + +The SDK exports its properties to analyzers and generators as `build_property.`. When +authoring an analyzer, read the exported property instead of re-deriving SDK behaviour — the export +is the SDK's answer, and it stays correct when the rules change. The exported set is listed in +[references/properties.md](references/properties.md). + +## Version detection + +1. If `RootPackageJson` is set, that file is used. +2. Otherwise the repo root is discovered from CI variables, `.git`, or a nearby `package.json`. +3. On success, both `Version` and `PackageVersion` come from the `version` field. +4. `UsePackageJsonVersion=Strict` turns a failed discovery into a build failure instead of a silent + fallback. + +## Repository bootstrap + +The SDK bootstraps two repository-wide files from the package: `.editorconfig` and `global.json`. + +- `PurviewRepoBootstrapMode` — `IfMissing` (default), `Always`, `WarnOnDrift`, `Never` +- `DisableAutoCopySdkFiles` — the master off switch +- `PurviewRepoBootstrapCopyRetries` / `...RetryDelayMilliseconds` / `...FailureAsError` + +Every project in a solution writes those same destinations, so the write is race-tolerant by +design: an existing file is never overwritten unless asked, each write is staged into a temporary +file and renamed into place, retries are quiet, and only a failure that survives every retry is +reported. + +**The SDK writes nothing into an agent directory.** It used to mirror a package's `.agents/**` into +the repository; that is gone, along with `EnableAgentFolderInPackage`, `AgentPackDestinationFolder` +and the `PurviewAgentFolder*` properties. Skills have exactly one installer, the skills CLI — see +`purview-buildsdk-skill-installation`. + +## Guidance when changing SDK configuration + +1. Preserve existing defaults unless the task explicitly changes product behaviour. +2. Keep `README.md`, the property declaration, its validation and the shipped skills aligned — a + property documented in one place and absent from another is the failure mode this repository + keeps hitting. +3. A new property that affects import-time behaviour must say so in its documentation. +4. Add the property to the `CompilerVisibleProperty` list if an analyzer would benefit from it. diff --git a/.agents/skills/purview-buildsdk-configuration/references/properties.md b/.agents/skills/purview-buildsdk-configuration/references/properties.md new file mode 100644 index 00000000..93a0d9b3 --- /dev/null +++ b/.agents/skills/purview-buildsdk-configuration/references/properties.md @@ -0,0 +1,146 @@ +# Purview.BuildSdk property reference + +Every user-facing property, grouped by what it changes. Defaults are what the SDK applies when the +consuming project supplies nothing. + +## Identity and naming + +| Property | Default | Behaviour | +| -- | -- | -- | +| `NamespacePrefix` | *(required)* | The root identity source. Required unless the check is disabled. Set before the SDK import | +| `DisableNamespacePrefixCheck` | `false` | Stops the build failing when `NamespacePrefix` is unset | +| `EnableAssemblyNameGeneration` | `true` | `AssemblyName` and the default `PackageId` follow the fully evaluated `RootNamespace`, or the full logical project name when suffix-stripping removed a segment (`Shared`, `ServiceDefaults`). Set `false` before the SDK import for standard project-name behaviour | +| `AssemblyIdentifierClassName` | *(derived)* | Renames the generated marker class | +| `DisableGenerateAssemblyIdentifierClass` | `false` (forced `true` for test and shared-testing projects) | Drops the empty marker class (`Assembly`, global namespace) that architecture tests use to pin an assembly by `typeof` rather than by name | +| `DisableGenerateAssemblyInfoClass` | `false` | Drops the generated `AssemblyInfo` | +| `DisableAutoInternalsVisibleTo` | `false` | Drops automatic friend-assembly generation | +| `DisableProjectFileNamingConventionCheck` | `false` | Stops validating that the `.csproj` filename matches its directory | +| `AutoIncludeUsings` | `true` | Controls the SDK-added global usings. Set before the SDK import | + +## Target framework and language + +| Property | Default | Behaviour | +| -- | -- | -- | +| `TargetFramework` | `net10.0` | Applied when neither `TargetFramework` nor `TargetFrameworks` is set. A project that explicitly declares `IsRoslynComponent=true` defaults to `netstandard2.0` | +| `IsRoslynComponent` | *(unset)* | When explicitly `true`: a single `netstandard2.0` target, `LangVersion=latest`, `Nullable=enable`, `TreatWarningsAsErrors=true`, `Deterministic=true`, extended analyzer rules, SourceLink with `EmbedUntrackedSources=true`, no dependency file, telemetry exclusion, and `PrivateAssets=all` on `Microsoft.CodeAnalysis.*` references | +| `IsRoslynComponentOnly` | `true` for Roslyn components | Analyzer-only package: `IncludeBuildOutput=false`, `IncludeSymbols=false`, portable PDB packed beside the analyzer under `analyzers/dotnet/cs/`. Set `false` for a dual-role component using normal library symbol packaging | +| `DisableRoslynCompilerDefaultsValidation` | `false` | Opts out of `ValidateRoslynComponentCompilerSettings`, which fails the pack of a packable Roslyn component missing `LangVersion`, `Nullable`, `TreatWarningsAsErrors` or `EnforceExtendedAnalyzerRules` | +| `PackProjectReferencedSourceGenerators` | `true` | Packable projects include analyzer `ProjectReference` outputs under `analyzers/dotnet/cs/`. Use `Pack="false"` on one reference to opt that one out | + +## Style policy + +| Property | Default | Behaviour | +| -- | -- | -- | +| `DisablePurviewStylePolicyValidation` | `false` | Stops the build failing (`PRSGD0006`–`PRSGD0009`) when the repository `.editorconfig` overrides the modifier policy — `dotnet_style_require_accessibility_modifiers` other than `omit_if_default`, hiding `IDE0040`/`IDE1006`, disabling the Style category in bulk, weakening the `_camelCase` private-instance-field rule, or adding the accessibility rules to `NoWarn`. Entries the SDK injects itself are ignored | +| `PurviewTestContextNoWarn` | `CA1002;CA1012;CA1034;CA1047;CA1050;CA1051;CA1062;CA1064;CA1515;CA1707` | The production API-surface rules exempted in test and shared-testing projects. Test projects keep the strict style contract (`IDE0040`, field naming, formatting, `IDE1006`) but are context aware: public test classes, `Method_Scenario_Expectation` names, exposed fields and unvalidated helper parameters are allowed. Set before the SDK import | +| `DisablePurviewTestContextRuleSet` | `false` | Makes test and shared-testing projects enforce the production API-surface rules too | +| `PurviewPolicyExemptNoWarn` | *(derived)* | The SDK-injected `NoWarn` entries `ValidatePurviewStylePolicy` accepts | + +## Testing + +| Property | Default | Behaviour | +| -- | -- | -- | +| `TestingFramework` | `TUnit` | `TUnit`, `Xunit`, `None` | +| `SubstituteFramework` | `TUnitMocks` | `TUnitMocks`, `NSubstitute`, `None` | +| `TestDataFramework` | `Bogus` | `Bogus`, `None` | +| `CollectCoverage` | `true` for detected test projects | | +| `EnableStaticNativeInstrumentation` | `false` for test projects | | +| `EnableDynamicNativeInstrumentation` | `false` for test projects | | +| `TestingPlatformDotnetTestSupport`, `UseMicrosoftTestingPlatformRunner`, `EnableMicrosoftTestingPlatform` | enabled for TUnit test projects | Microsoft.Testing.Platform wiring | +| `PurviewSharedTestingOutputType` | `Library` | Forced onto `IsSharedTestingProject` projects, with `IsTestProject`/`IsTestingPlatformApplication` cleared, because the test packages otherwise flip them into an executable test host. Set `Exe` before the SDK import to keep the package-driven shape | + +## Packaging + +| Property | Default | Behaviour | +| -- | -- | -- | +| `IsPackable` | `false` | | +| `PurviewAutoSdkPack` | `true` | Packs `Sdk/**/*` into the package at the right root-level paths | +| `PurviewSkillsSourceFolder` | `/skills` | Where authored skills live | + +Packable-project defaults, applied only when the project supplied nothing: +`GenerateDocumentationFile=true`, `IncludeSymbols=true`, `SymbolPackageFormat=snupkg`, +`PublishRepositoryUrl=true`, `EmbedUntrackedSources=true`, `DebugType=portable`. Portable PDBs ship +in the `.snupkg`; the `.nupkg` gets none unless the project opts in. Roslyn-component-only packages +instead default `IncludeSymbols=false` and ship their PDB inside `analyzers/dotnet/cs/`. + +When the repository root is discoverable, the root `README.md` is packed automatically and +registered as `PackageReadmeFile`, unless one is configured already. + +Non-packable projects, including web apps, default `WarnOnPackingNonPackableProject=false` so a +solution-wide pack skips them silently. + +`ContinuousIntegrationBuild` is set only by real CI environment variables. Packability alone never +forces SourceLink's CI-mode dirty-repository checks. + +## Telemetry and SourceLink + +| Property | Default | Behaviour | +| -- | -- | -- | +| `ExcludePurviewTelemetry` | `false` | Removes `Purview.Telemetry.SourceGenerator` | +| `ExcludeMSTelemetryExtension` | `false` | Removes `Microsoft.Extensions.Telemetry.Abstractions`. Only relevant when `ExcludePurviewTelemetry` is also `false` — the whole group is skipped otherwise | +| `SourceLinkPackageName` | `Microsoft.SourceLink.GitHub` | | +| `DisableSourceLink` | `false` | | + +## Version detection + +| Property | Default | Behaviour | +| -- | -- | -- | +| `UsePackageJsonVersion` | `true` | `true`, `false`, `Strict` | +| `RootPackageJson` | *(discovered)* | Explicit path to the `package.json` to read | +| `EnableVersionDetectionCache` | `true` | | +| `VersionDetectionCacheFile` | *(derived)* | | +| `VersionDetectionLogEnabled` | `false` | Logs the detected version | + +## Repository bootstrap + +| Property | Default | Behaviour | +| -- | -- | -- | +| `DisableAutoCopySdkFiles` | `false` | Master switch for SDK-managed repository file writes | +| `PurviewRepoBootstrapMode` | `IfMissing` | Also `Always`, `WarnOnDrift`, `Never` | +| `BootstrapEditorConfigToRepoRoot` | `true` | | +| `RepositoryEditorConfigFilePath` | *(derived)* | Overrides the destination `.editorconfig` | +| `BootstrapGlobalJsonToRepoRoot` | `true` | | +| `RepositoryGlobalJsonFilePath` | *(derived)* | Overrides the destination `global.json` | +| `PurviewBuildSdkVersionForGlobalJson` | detected SDK version, else `1.0.0` | | +| `PurviewRepoBootstrapCopyRetries` | `3` | | +| `PurviewRepoBootstrapCopyRetryDelayMilliseconds` | `500` | | +| `PurviewRepoBootstrapCopyFailureAsError` | `true` | `false` downgrades a persistent write failure to a warning | +| `PurviewSuppressCopyRetryWarnings` | `true` | Demotes the built-in copy task's `MSB3026` retry notice to a message | +| `PurviewRepositoryRootMarkers` | `.git/;.github/;.gitattributes;LICENSE.md;AGENTS.md;.agents/;CLAUDE.md;.claude/;package.json` | Ordered markers identifying a repository root, most authoritative first | + +There is no agent-folder mirror. `EnableAgentFolderInPackage`, `AgentPackDestinationFolder`, +`PurviewAgentFolderSourcePath`, `PurviewAgentFolderCopy*`, `PurviewAgentSyncManifestPath` and +`DisableMirroredFileTrackingCheck` were removed: skills are installed by the skills CLI, and +nothing else was left for the mirror to deliver. + +## Skills + +Covered in full by `purview-buildsdk-skill-installation`: `PurviewSkillsRunner`, +`PurviewSkillsRunnerCandidates`, `PurviewSkillsCommand`, `PurviewSkillsPackage`, +`PurviewSkillsAgents`, `PurviewSkillsSource`, `PurviewSkillsInstallRoot`, `PurviewSkillsRepoRoot`, +`EnablePurviewSkillRecommendations`, `PurviewSkillRecommendationsInCI`. + +## Compiler-visible properties + +Exported to analyzers and generators as `build_property.`: + +- `UsePackageJsonVersion`, `RootPackageJson`, `RepoRoot`, `Version`, `PackageVersion` +- `NamespacePrefix`, `DisableNamespacePrefixCheck` +- `TestingFramework`, `SubstituteFramework`, `TestDataFramework` +- `ExcludePurviewTelemetry`, `ExcludeMSTelemetryExtension` +- `EnableAssemblyNameGeneration`, `DisableAutoInternalsVisibleTo`, `DisableGenerateAssemblyInfoClass`, + `DisableGenerateAssemblyIdentifierClass`, `AssemblyIdentifierClassName` +- `IsCSharpProject`, `IsTestProject`, `IsSharedTestingProject`, `IsSharedProject` +- `TestingType`, `TargetProjectName` +- `IsContainerProject`, `IsSdkProject`, `SdkProjectName`, `IsWebProject`, `IsWebSdkProject`, + `IsWorkerSdkProject`, `IsAspireHostProject`, `IsCLIProject` +- `EditorConfigFilePath`, `RepositoryEditorConfigFilePath`, `BootstrapEditorConfigToRepoRoot` +- `RepositoryGlobalJsonFilePath`, `BootstrapGlobalJsonToRepoRoot`, `DisableAutoCopySdkFiles` +- `PurviewRepoBootstrapMode`, `PurviewRepoBootstrapCopyRetries`, + `PurviewRepoBootstrapCopyRetryDelayMilliseconds`, `PurviewRepoBootstrapCopyFailureAsError` +- `PurviewSuppressCopyRetryWarnings` +- `PurviewSkillsSourceFolder`, + `PurviewSkillsAgents`, `PurviewSkillsInstallRoot`, `PurviewRepositoryRootMarkers`, + `PurviewSkillsRunner` +- `PurviewBuildSdkVersionForGlobalJson`, `CurrentYear`, `AutoGeneratedAssemblyInfoFile`, + `AutoGeneratedAssemblyIdentifierFile` diff --git a/.agents/skills/purview-buildsdk-project-detection/SKILL.md b/.agents/skills/purview-buildsdk-project-detection/SKILL.md new file mode 100644 index 00000000..2d0d9862 --- /dev/null +++ b/.agents/skills/purview-buildsdk-project-detection/SKILL.md @@ -0,0 +1,134 @@ +--- +name: purview-buildsdk-project-detection +description: Explain why Purview.BuildSdk classified a project as test, shared, shared-testing, CLI, web, worker, Aspire host, container or Roslyn component, and why it added a package, a project reference, a namespace or an analyzer automatically. Use when SDK behaviour looks surprising, when a test project gets no runner or no InternalsVisibleTo, or when reasoning about RootNamespace, AssemblyName and TargetProjectName. +license: MIT +metadata: + package: Purview.BuildSdk + repository: purview-dev/build-sdk +--- + +# Why Purview.BuildSdk did that + +Use this skill when the question is **why** the SDK applied something automatically. + +For where a project should live, use `purview-buildsdk-project-layout`. For the property that turns +a behaviour off, use `purview-buildsdk-configuration`. + +## Diagnose from computed properties, never from the folder name + +Read what the SDK actually computed: + +```bash +dotnet msbuild -getProperty:PurviewLogicalProjectName -getProperty:RootNamespace \ + -getProperty:TestingType -getProperty:TargetProjectName -getProperty:IsTestProject +``` + +The values worth inspecting first: `MSBuildProjectName`, `NamespacePrefix`, +`PurviewLogicalProjectName`, `RootNamespace`, `TestingType`, `TargetProjectName`, `SdkProjectName`, +`IsTestProject`, `IsSharedProject`, `IsSharedTestingProject`, `IsContainerProject`, `IsCLIProject`, +`IsWebSdkProject`, `IsAspireHostProject`. + +## Detection rules + +### Test projects + +Name matches `^.*\.([\w|_]\w*)Tests?$` — a target name, a dot, then any word before `Test`/`Tests`. +The captured word becomes `TestingType`. + +This is a pattern, **not** a lookup. `MyProject.GoldenTests` is detected exactly as readily as +`MyProject.UnitTests`, with `TestingType=Golden` and `Category=Golden`, even though `Golden` is not a +name the SDK ships. + +**The dot is required.** A project named plainly `UnitTests` does not match, and silently gets no +runner, no coverage, no `InternalsVisibleTo` and no category. This is the single most common +surprise. + +Derived: `IsTestProject=true`, `TestingType=`, `PurviewTestType=Tests`, +`TargetProjectName=`. + +The SDK's explicit `TestType` item group governs **`InternalsVisibleTo` generation**, not detection: +a non-test project grants access to `{AssemblyName}.{TestType}Tests` for each name in the group. A +suffix outside it still builds, runs and gets a category — it just cannot see `internal` members. +The 53 names are in [references/test-types.md](references/test-types.md). + +### Shared and shared-testing projects + +Recognised by **exact name**, never by substring. The two lists are in +[references/detection.md](references/detection.md). Derived: `IsSharedProject`, +`IsSharedTestingProject`. + +### SDK and content based + +| Signal | Result | +| -- | -- | +| the project's `Sdk="..."` declaration | `IsSdkProject`, `SdkProjectName` | +| `Microsoft.NET.Sdk.Web` | `IsWebSdkProject=true` | +| `Microsoft.NET.Sdk.Worker` | `IsWorkerSdkProject=true` | +| SDK starts with `Aspire.Sdk.Host` or `Aspire.AppHost.Sdk` | `IsAspireHostProject=true` | +| `Dockerfile`, `dockerfile` or `Dockerfile.dev` in the project directory | `IsContainerProject=true` | +| name ends with `CLI`, `Console`, `CommandLine`, `QuickStart`, `QuickStarts` | `IsCLIProject=true` | + +## Namespace and identity + +1. `PurviewLogicalProjectName` is `NamespacePrefix` plus the project name, de-duplicated when the + project name already starts with the prefix's tail. +2. `RootNamespace` defaults to `PurviewLogicalProjectName`. +3. Known suffixes are stripped from `RootNamespace` — shared and shared-testing names, and segments + such as `Core`, `EF`, `Shared`, `ClientShared`, `ServiceDefaults`. +4. Test suffixes are stripped too, so `Acme.Api.UnitTests` maps back to `Acme.Api`. +5. `AssemblyName` and `PackageId` default to the fully evaluated `RootNamespace` — except where + stripping removed a segment, where they use the full `PurviewLogicalProjectName` so the artifact + stays distinct from its parent. Test and shared-testing projects keep their detected suffix. + Explicit `AssemblyName`/`PackageId`/`RootNamespace` always win. +6. The naming defaults are applied during `Sdk.props`, before the Microsoft SDK computes + `TargetName`, so the compiled output name always matches `AssemblyName`. + +## Automatic packages and references + +- **Non-test C# projects**: SourceLink (unless `DisableSourceLink`), the Purview telemetry packages + (unless `ExcludePurviewTelemetry`), `GenerateDocumentationFile=true`, and `InternalsVisibleTo` + generation (unless `DisableAutoInternalsVisibleTo`). +- **Test and shared-testing projects**: test-friendly `NoWarn` defaults, not packable or + publishable, and the packages selected by `TestingFramework`, `SubstituteFramework` and + `TestDataFramework`. TUnit test projects get Microsoft.Testing.Platform wiring automatically. + Shared-testing projects skip the runnable test package. +- **Packable projects**, **Roslyn components** and **special project types** (CLI, container, web, + Aspire host): see [references/detection.md](references/detection.md). + +Project-reference probing is layout-driven and covered by `purview-buildsdk-project-layout`. + +## The shipped analyzers + +The SDK adds `Purview.BuildSdk.Analyzers` as an `` item to every C# project, so its rules +surface in command-line builds and in Visual Studio. The code-fix assembly ships beside it. + +| Rule | What it enforces | +| -- | -- | +| `PDS0002` | Extensions classes live under `Extensions//` | +| `PDS0003` | Explicit types with target-typed `new()` | +| `PDS0004` | Correct acronym capitalisation | + +`PDS0004` follows .NET naming guidance: well-known framework spellings (`Sql`, `Guid`, `Uuid`, +`Url`, `Dns`, `Tcp`, `Http`, `Xml`, `Db`, …) are exempt — `Db` among them, so `DbContext`, +`DbConnection` and `DbSet` are never flagged. A small set is still uppercased: `Api`, `Ai`, `Ui`, +`Io`, `Os`, `Cpu`, `Gpu`, `Cli`, `Gui`, `Ram`, `Ssh`. Members mandated by a contract — interface +implementations and base-class overrides — are never renamed. + +Customise through `dotnet_analyzer_configuration.pds0004.allowed_words` (exempt segments), +`.acronym_map` (segment renames, e.g. `Sql:SQL`, or `Db:DB` to re-enable it) and +`.allowed_identifiers` (brand names, exact or word-boundary prefix, first match wins — `CosmosDb` +covers `CosmosDbServer`). All three merge with and override the shipped defaults. + +The shipped `.editorconfig` marks generated content (`Migrations/`, `*.g.cs`, `Generated/`, +`*.Designer.cs`, `obj/`, `bin/`) as `generated_code = true`, and suppresses namespace-conflict +diagnostics under `Extensions/`, so no `#pragma` suppressions are needed there. + +Two Visual Studio refactorings ship with them, both described in +[references/detection.md](references/detection.md). + +## When changing a detection rule + +1. Keep the `.csproj` filename equal to its directory name. +2. Update `README.md` and the shipped skills in the same change — a rule true in code and false in + prose is this repository's recurring failure. +3. Add or update the integration test in `src/tests/BuildSdk.IntegrationTests/` that pins it. diff --git a/.agents/skills/purview-buildsdk-project-detection/references/detection.md b/.agents/skills/purview-buildsdk-project-detection/references/detection.md new file mode 100644 index 00000000..bf75823d --- /dev/null +++ b/.agents/skills/purview-buildsdk-project-detection/references/detection.md @@ -0,0 +1,79 @@ +# Detection detail + +## Shared project names (exact) + +`Shared`, `SharedFramework`, `SharedInfrastructure`, `SharedInfra`, `SharedUtilities`, +`SharedUtils`, `SharedLibrary`, `SharedLib`, `SharedHelpers` + +## Shared testing project names (exact) + +`SharedTestingFramework`, `SharedTestingInfrastructure`, `SharedTestingInfra`, +`SharedTestingUtilities`, `SharedTestingUtils`, `SharedTestingLibrary`, `SharedTestingLib`, +`SharedTestingHelpers` + +These are matched whole, not as substrings. `SharedModels` is not a shared project. + +A shared-testing project is forced to `PurviewSharedTestingOutputType` (default `Library`), with +`IsTestProject` and `IsTestingPlatformApplication` cleared, because the test packages otherwise flip +it into an executable test host. Set `PurviewSharedTestingOutputType=Exe` before the SDK import to +keep that package-driven shape. + +## Packable projects + +Defaults applied only where the project supplied nothing: `GenerateDocumentationFile`, +`IncludeSymbols`, `SymbolPackageFormat=snupkg`, `PublishRepositoryUrl`, `EmbedUntrackedSources`, +`IncludeSource`, `DebugType=portable`. + +- Portable PDBs ship in the `.snupkg`. The `.nupkg` receives none unless the project opts in. +- The repository-root `README.md` is packed and registered as `PackageReadmeFile` when it exists and + nothing else is already being packed as one. +- Non-packable projects, web apps included, default `WarnOnPackingNonPackableProject=false`, so a + solution-wide `dotnet pack` skips them silently. +- `ContinuousIntegrationBuild` is set only by real CI environment variables. Packability alone never + forces SourceLink's CI-mode dirty-repository checks. + +## Roslyn components + +A project that explicitly declares `IsRoslynComponent=true` gets: + +- a single `netstandard2.0` target, `LangVersion=latest`, `Nullable=enable`, + `TreatWarningsAsErrors=true`, `Deterministic=true`, extended analyzer rules +- SourceLink with `EmbedUntrackedSources=true`, no dependency file, telemetry excluded +- compiler-generated output under the framework-specific intermediate directory +- `PrivateAssets=all` on `Microsoft.CodeAnalysis.*` and `Microsoft.CodeAnalysis.Analyzers`, so they + never leak into the packed nuspec + +`IsRoslynComponentOnly` defaults to `true`: `IncludeBuildOutput=false`, `IncludeSymbols=false`, no +`.symbols.nupkg` or `.snupkg`, and the analyzer PDB shipped inside the main `.nupkg` under +`analyzers/dotnet/cs/` beside the assembly (`PurviewPackAnalyzerPdb=true`). Set it to `false` for a +dual-role component that wants normal library symbol packaging. + +`ValidateRoslynComponentCompilerSettings` fails the pack of a packable Roslyn component missing +`LangVersion`, `Nullable`, `TreatWarningsAsErrors` or `EnforceExtendedAnalyzerRules`. Opt out with +`DisableRoslynCompilerDefaultsValidation=true`. + +`PackProjectReferencedSourceGenerators` (default `true`) makes a packable project include analyzer +`ProjectReference` outputs and their runtime dependencies under `analyzers/dotnet/cs/`. Set it +`false` globally, or `Pack="false"` on one analyzer reference. + +## Special project types + +| Type | Applied | +| -- | -- | +| CLI | `OutputType=Exe`, `appsettings*.json` included as content | +| Container | `InvariantGlobalization`, `PublishAot`, Linux Docker defaults, container tooling packages | +| Web SDK | `Microsoft.AspNetCore.OpenApi.Generated` added to `InterceptorsNamespaces`, unless marked as a separate web-project mode | +| Aspire host | `OutputType=Exe` | + +## The Visual Studio refactorings + +Two ship with the code-fix assembly, both serving the `PDS0002` convention: + +- **Split extensions class into one class per receiver type** — offered on a static extensions class + targeting several receiver types. It produces one `Extensions` class per receiver + (a generic `this TBuilder where TBuilder : IHostApplicationBuilder` receiver becomes + `HostApplicationBuilderExtensions`) and places each under `Extensions//`. +- **Move extensions class to conventional location** — offered on a misplaced single-receiver + extensions class. It re-paths the file to `Extensions//`, fixes the namespace + to the receiver's, and updates `using` directives in other referencing documents so the move + compiles. diff --git a/.agents/skills/purview-buildsdk-project-detection/references/test-types.md b/.agents/skills/purview-buildsdk-project-detection/references/test-types.md new file mode 100644 index 00000000..dace44fc --- /dev/null +++ b/.agents/skills/purview-buildsdk-project-detection/references/test-types.md @@ -0,0 +1,35 @@ +# The shipped `TestType` group + +These 53 names drive **`InternalsVisibleTo` generation**, not test detection. A non-test project +grants friend access to `{AssemblyName}.{TestType}Tests` for each name here. + +Detection is the pattern `^.*\.([\w|_]\w*)Tests?$`, so a suffix outside this group is still detected, +still runs and still gets its category — it simply cannot reach the target project's `internal` +members. Prefer a name from this group unless the test type genuinely needs its own word. + +```text +Unit Integration E2E EndToEnd Acceptance +Functional Performance Load Smoke Stress +Regression Security Chaos Scenario System +Threat BlackBox WhiteBox GrayBox GreyBox +Accessibility Usability Visual Interactive Localization +Globalization Environment Configuration Deployment Architecture +Contract Component Sanity Property Fuzz +Mutation Snapshot Approval Benchmark Capacity +Concurrency Endurance Soak Spike Failover +Recovery Resilience Compatibility Interoperability Migration +Upgrade Penetration Compliance +``` + +## The five to reach for first + +`Unit`, `Integration`, `E2E`, `Functional`, `Contract`. Everything else is available, but a reader +has to ask what it means — use one only when the test type itself carries operational weight. + +## What a suffix buys you + +| | detected as a test project | gets a category | gets a runner and coverage | sees `internal` members | +| -- | -- | -- | -- | -- | +| `Api.UnitTests` | yes | `Unit` | yes | yes | +| `Api.GoldenTests` | yes | `Golden` | yes | **no** | +| `UnitTests` *(no dot)* | **no** | no | **no** | no | diff --git a/.agents/skills/purview-buildsdk-project-layout/SKILL.md b/.agents/skills/purview-buildsdk-project-layout/SKILL.md new file mode 100644 index 00000000..55a019cd --- /dev/null +++ b/.agents/skills/purview-buildsdk-project-layout/SKILL.md @@ -0,0 +1,136 @@ +--- +name: purview-buildsdk-project-layout +description: Decide where a project goes and what to call it in a repository that uses Purview.BuildSdk. Use when creating, moving, splitting or renaming a project or test project, choosing a test suffix, aligning namespaces and assembly identity with NamespacePrefix, or relying on the SDK's automatic project references. Also use when rationalising a repository's shape so the SDK's conventions work without overrides. +license: MIT +metadata: + package: Purview.BuildSdk + repository: purview-dev/build-sdk +--- + +# Project layout and naming for Purview.BuildSdk + +Use this skill when physically adding, moving, splitting or renaming a project. + +For *why* the SDK classified an existing project a particular way, use +`purview-buildsdk-project-detection`. For the property that changes a behaviour, use +`purview-buildsdk-configuration`. + +## First principle + +**Treat naming and placement as configuration, not decoration.** + +The SDK infers namespaces, assembly identity, test categories, package wiring and project references +from a small set of conventions. The closer a repository sits to them, the fewer overrides it needs. + +The corollary matters just as much: **preserve the host repository's existing layout first.** Only +introduce new structure when no established pattern exists. + +## Canonical layout + +```text +/ + package.json version source + .editorconfig bootstrapped by the SDK + skills/ authored agent skills, if any + src/ + .slnx + src//.csproj + tests/.Tests/.Tests.csproj +``` + +- The `.csproj` filename must equal its containing directory name, unless + `DisableProjectFileNamingConventionCheck=true`. +- Source projects under `src/`, test projects under `tests/`. +- Place a new project beside similar ones — same language, layer and test type. +- One test type per project by default. + +A repository that already uses a different shape keeps it; add to it rather than converting it. + +## Naming and identity + +`NamespacePrefix` is the root identity source. Keep project names short and let the SDK apply the +prefix: + +| `NamespacePrefix` | Project | `RootNamespace` | +| -- | -- | -- | +| `Aspire` | `Hosting` | `Aspire.Hosting` | +| `Acme.Sales.RegionalPipeline` | `Identity.API` | `Acme.Sales.RegionalPipeline.Identity.API` | +| `Acme.Sales.RegionalPipeline` | `Identity.Core` | `Acme.Sales.RegionalPipeline.Identity` | + +`AssemblyName` and `PackageId` follow the resolved `RootNamespace` — except where suffix-stripping +removed a segment (`Core`, `Shared`, `ServiceDefaults`), in which case they keep the fuller logical +name so the artifacts stay distinct from their parent. Explicit values always win, and +`EnableAssemblyNameGeneration=false` (before the SDK import) restores standard behaviour. + +Do not hand-author an alternate namespace scheme when one is already in use. + +## Test project naming + +Test detection is a **pattern**, not a list: `^.*\.([\w|_]\w*)Tests?$`. A target name, a dot, then +any word before `Test` or `Tests`. The captured word becomes `TestingType` and the baseline category. + +**The dot is required.** A project named plainly `UnitTests`, with no target in front of it, is not +detected as a test project at all — no runner, no coverage, no `InternalsVisibleTo`, no category. +Always name a test project `.Tests`. + +Prefer these by default: `UnitTests`, `IntegrationTests`, `E2ETests`, `FunctionalTests`, +`ContractTests`. Use another suffix only when the test type itself carries operational meaning. + +A suffix outside the SDK's shipped `TestType` group still builds, runs and gets its category — it +just cannot reach the target project's `internal` members, because that group drives +`InternalsVisibleTo` generation. The full list is in `purview-buildsdk-project-detection`. + +## Shared projects: exact names only + +The SDK recognises these names exactly — a near miss gets none of the behaviour. + +Shared: `Shared`, `SharedFramework`, `SharedInfrastructure`, `SharedInfra`, `SharedUtilities`, +`SharedUtils`, `SharedLibrary`, `SharedLib`, `SharedHelpers`. + +Shared testing: `SharedTestingFramework`, `SharedTestingInfrastructure`, `SharedTestingInfra`, +`SharedTestingUtilities`, `SharedTestingUtils`, `SharedTestingLibrary`, `SharedTestingLib`, +`SharedTestingHelpers`. + +## Automatic project references to preserve + +Layout is what makes these work. Move a project off the convention and you own the reference. + +Test projects probe for their target, in order: + +- `../$(TargetProjectName)/$(TargetProjectName).csproj` +- `../../$(TargetProjectName)/$(TargetProjectName).csproj` +- `../src/$(TargetProjectName)/$(TargetProjectName).csproj` +- `../../src/$(TargetProjectName)/$(TargetProjectName).csproj` + +Non-test projects pick up sibling shared projects via `../Shared*/Shared*.csproj`; test projects +pick up `../SharedTesting*/SharedTesting*.csproj`. + +## Creating a new project + +1. Match the SDK and style of sibling projects. +2. Use Central Package Management if the repository has it. +3. Add only the dependencies the project's scope needs — the SDK supplies the testing stack, + SourceLink and telemetry by default. +4. Add the project to the solution. +5. Keep target frameworks, nullability, analyzers and warning settings consistent with neighbours. + +## Moving or splitting + +1. Create the destination using the established layout. +2. Move the files. +3. Update namespaces, usings and references for the destination. +4. Verify the destination still produces the intended `TestingType`, `TargetProjectName` and + `RootNamespace` — ask MSBuild rather than assuming: + `dotnet msbuild -getProperty:RootNamespace -getProperty:TargetProjectName`. +5. Remove dependencies the source no longer needs. +6. Update solution membership and project references. +7. Build, then run the affected tests. + +## Guardrails + +- Prefer minimal, targeted diffs; avoid cross-cutting renames unrelated to the move. +- Keep test intent unchanged while relocating. +- When the structure is ambiguous, infer from the nearest sibling projects and say which assumption + you made. +- When in doubt, preserve compatibility with the SDK's automatic naming, namespace and + project-reference behaviour. diff --git a/.agents/skills/purview-buildsdk-repository-review/SKILL.md b/.agents/skills/purview-buildsdk-repository-review/SKILL.md new file mode 100644 index 00000000..ce1fd294 --- /dev/null +++ b/.agents/skills/purview-buildsdk-repository-review/SKILL.md @@ -0,0 +1,111 @@ +--- +name: purview-buildsdk-repository-review +description: Review a repository that uses Purview.BuildSdk for naming, placement and test-structure alignment, and report what the SDK can and cannot do automatically as a result. Use when asked to audit, rationalise or health-check a repo against the SDK's conventions, when onboarding an existing codebase onto Purview.BuildSdk, or when deciding whether a layout quirk is worth changing. +license: MIT +metadata: + package: Purview.BuildSdk + repository: purview-dev/build-sdk +--- + +# Reviewing a repository against the SDK's conventions + +This is an audit, not a refactor. The deliverable is a prioritised list of findings and the cost of +each, so somebody else can decide what to change. + +For the conventions themselves use `purview-buildsdk-project-layout`; for why one project was +classified as it was, `purview-buildsdk-project-detection`. + +## The governing judgement + +**Deviation is only a finding when it costs the repository something.** The SDK infers behaviour +from naming and placement, so a deviation is interesting precisely to the extent that it turns an +automatic behaviour off. A layout that differs from the canonical one but still gets every automatic +behaviour is not debt, and reporting it as such wastes the reader's attention. + +Sort every finding into one of three buckets, and say which: + +| Bucket | Meaning | +| -- | -- | +| **Acceptable variance** | Differs from the canonical layout, costs nothing. Preserve it. | +| **Structural debt** | Blocks an automatic behaviour the repository would benefit from. | +| **Incremental opportunity** | Low-risk tidying worth doing when the area is touched anyway. | + +## 1. Read before concluding + +Inspect, in this order, before forming any opinion: + +- `Directory.Build.props` and `Directory.Build.targets` — where the SDK is imported, and what is set + before the import +- the solution entry point, for what is actually in the build +- `Directory.Packages.props`, for Central Package Management +- the project layout on disk + +## 2. Check the structural signals + +- Source projects under `src/`, test projects under `tests/`. +- `.csproj` filename equals its containing directory name — unless + `DisableProjectFileNamingConventionCheck=true`, which is itself a finding worth surfacing. +- Short project names, with `NamespacePrefix` carrying the repository identity. +- Test project names match `^.*\.([\w|_]\w*)Tests?$`. **The dot is required**; a project named + plainly `UnitTests` is not detected at all and silently gets no runner, no coverage, no + `InternalsVisibleTo` and no category. This is the single highest-value thing to check. +- Test suffixes come from the SDK's shipped `TestType` group where `internal` access is wanted — a + suffix outside it still runs, it just cannot see `internal` members. +- Shared and shared-testing projects use the **exact** recognised names. A near miss gets none of + the behaviour. + +## 3. Verify with MSBuild, do not infer from folder names + +A review that reasons from directory names will be wrong about at least one project. Ask: + +```bash +dotnet msbuild -getProperty:RootNamespace -getProperty:AssemblyName \ + -getProperty:IsTestProject -getProperty:TestingType -getProperty:TargetProjectName +``` + +Quote the computed values in the findings. "`Api.Tests` resolves `TestingType=` empty, so it has no +runner" is actionable; "`Api.Tests` looks like it might not be detected" is not. + +## 4. Review test readability + +- Subject-based suites: `{SubjectName}Tests`, with + `{SubjectOrMemberUnderTest}_{Scenario}_{Expectation}` methods. +- Non-subject-based suites — build, generator, workflow, package, full-system — named clearly for + their broader role. A forced `{Subject}Tests` on one of these is worse, not better. +- TUnit categories and display names used where a suite is large enough to need navigating. + +See `purview-buildsdk-testing`. + +## 5. Check the test dependencies are earned + +The SDK already supplies `TUnit`, `TUnit.Mocks`, `Bogus` and the Microsoft.Testing.Platform wiring +to every detected test project. Anything beyond that was a deliberate choice, and deliberate choices +go stale: + +- `TUnit.Aspire` and `Purview.Containers` are **not** universal defaults. Confirm each reference is + genuinely needed by that project rather than copied from a sibling. +- Where a project references `Testcontainers` directly, check whether a `Purview.Containers` typed + module now covers it — the module set grows, and a direct reference that was once necessary often + is not any more. +- A package the SDK already adds, restated in a project file, is maintenance cost with no effect. + +## 6. Explain consequences, not just mismatches + +For each finding, name the specific automatic behaviour that is lost: `RootNamespace`, +`AssemblyName`, `PackageId`, `TargetProjectName`, the automatic target-project reference, the +sibling `Shared*` reference, `InternalsVisibleTo` generation, the test runner and coverage wiring. + +"Project is not under `src/`" is not a finding. "Project is not under `src/`, so the test project's +four probe paths all miss and the `ProjectReference` has to be maintained by hand" is. + +## Reporting the result + +1. One sentence on whether the repository broadly fits the SDK's conventions. +2. The findings, ordered by impact, each with its bucket and the behaviour it costs. +3. The low-risk rationalisation steps, as concrete renames or moves. +4. An explicit split of what is **already automatic** versus what this repository has configured by + hand — that list is usually the most useful part of the review, because hand-configuration that + merely restates a default is pure maintenance cost. + +Do not propose a cross-cutting rename as a first step. Name the one change with the best +cost-to-benefit ratio and say what it unlocks. diff --git a/.agents/skills/purview-buildsdk-skill-installation/SKILL.md b/.agents/skills/purview-buildsdk-skill-installation/SKILL.md new file mode 100644 index 00000000..66c20a33 --- /dev/null +++ b/.agents/skills/purview-buildsdk-skill-installation/SKILL.md @@ -0,0 +1,166 @@ +--- +name: purview-buildsdk-skill-installation +description: Install, list and diagnose the agent skills a Purview.BuildSdk package ships. Use for the InstallPurviewSkills, ListPurviewSkills and RecommendPurviewSkills MSBuild targets, for any PRSKL0001-PRSKL0014 diagnostic, for choosing a package runner (npx, pnpm dlx, bunx, yarn dlx, deno), for skills-lock.json, or when a package ships skills but no agent can see them. +license: MIT +metadata: + package: Purview.BuildSdk + repository: purview-dev/build-sdk +--- + +# Installing the skills a package ships + +For *authoring* skills, use `purview-buildsdk-skill-tests`. + +## The one thing to understand first + +**The SDK writes nothing into an agent directory.** A package *ships* `.agents/skills//`, but +as metadata — it is what tells the SDK which skills the package offers and at which commit. Nothing +copies it out. + +Skills are installed by the skills CLI and by nothing else. That is a deliberate single-writer rule. +Earlier versions of this SDK mirrored a package's whole `.agents/**` folder into the consuming +repository, and the CLI's own universal install location is `.agents/skills/` — the same paths. The +mirror would silently overwrite a pinned install on the next build, while `PRSKL0011` compared a +lockfile ref against content the mirror had already replaced. The mirror was removed outright rather +than fenced off, because the CLI covers the whole job. + +Installing is therefore a separate, deliberately **explicit** step. It is never a side effect of a +restore, a build, a design-time build or a test run. + +```bash +dotnet msbuild -t:ListPurviewSkills # diagnostics only, installs nothing +dotnet msbuild -t:InstallPurviewSkills # delegates to the skills CLI +``` + +Neither target has `BeforeTargets` or `AfterTargets`. If skills are appearing or changing on their +own, something has been wired up that should not be. + +## How a skill is resolved, and why the version is always right + +There is deliberately **no custom manifest**. A package that ships skills already carries both +halves of the mapping, and `ResolvePurviewSkillSources` reads them: + +- `.agents/skills//` in the restored package says *which* skills it ships. +- The nuspec's ``, written by SourceLink for every package this + SDK builds, says which git repository and which **exact commit** produced them. + +So the resolved ref is the commit the *restored package version* was built from. An older +`PackageReference` gets that version's skills, not whatever is on the default branch. Compatibility +is exact by construction rather than by convention. + +## Installing from an explicit source + +For a skill you want but have no `PackageReference` for: + +```bash +dotnet msbuild -t:InstallPurviewSkills -p:PurviewSkillsSource=purview-dev/build-sdk +``` + +The caller owns the ref here — append `#` to pin it. This path needs no restore, so +`PRSKL0001` does not apply. + +## Diagnostics + +| Code | Meaning | Fix | +| -- | -- | -- | +| `PRSKL0001` | `project.assets.json` is missing | Restore. Resolution reads the restore graph and deliberately does not trigger a restore of its own | +| `PRSKL0002` | The package's nuspec has no GitHub repository URL, or no commit | The package cannot be pinned. It is reported rather than installed from a guessed branch | +| `PRSKL0003` | No repository root resolved | Pass `-p:PurviewSkillsInstallRoot=` | +| `PRSKL0004` | No skills CLI and no package runner found | Install Node, or set `PurviewSkillsCommand` | +| `PRSKL0005` | An authored skill is malformed | See `purview-buildsdk-skill-tests` | +| `PRSKL0010` | A skill a referenced package ships is missing | Warning. `npx skills add ...` | +| `PRSKL0011` | An installed skill is pinned to a different ref than the referenced package | Warning. Install the package's own commit | +| `PRSKL0012` | A skill cannot be verified | Message | +| `PRSKL0013` | An orphaned lockfile entry | Message | +| `PRSKL0014` | Recorded in the lockfile but never restored | Message | + +## Recommendations run during an ordinary build + +This is the **one** skill feature that does. `RecommendPurviewSkillsOnBuild` runs after `Build` and +delegates to `RecommendPurviewSkills`, which can also be invoked by name: + +```bash +dotnet msbuild -t:RecommendPurviewSkills +``` + +`EvaluatePurviewSkillState` joins the skills each restored package ships against the CLI's own +`skills-lock.json`. Both inputs are local files, so it stays offline and spawns no process. + +Four things keep it quiet, and all of them are load-bearing: + +- Design-time builds, CI builds, non-default TFM passes and + `EnablePurviewSkillRecommendations=false` are skipped outright. + `PurviewSkillRecommendationsInCI=true` re-enables CI. +- A fingerprint stamp at `/.purview/skill-recommendations.cache` means a given state is + reported once per repository, not once per project and again on every rebuild. The explicit target + ignores the stamp. +- Missing and drifted are **warnings** (fixable in one command); unverifiable and orphaned are + **messages**. No amount of skill advice can break a build using `TreatWarningsAsErrors`. +- A correctly installed set produces no output at all. + +Orphan detection is **owner-scoped on purpose**: a lockfile cannot record who asked for an entry, so +only an entry under an owner the project references — but from a repository it no longer references +— is reported. A skill from any other owner is the developer's own, and is never mentioned. + +### Drift never recommends `npx skills update` + +`update` installs the *newest* published skill, which is only correct when the newest skill happens +to describe the referenced package version. `PRSKL0011` names the referenced package's own commit in +a pinned `npx skills add` instead. + +## Package runners + +The CLI is published to npm, and every runner spells "run this npm package" differently. +`PurviewSkillsRunner` selects one, defaulting to `npx` because npx ships with Node itself. + +| Runner | Invocation | +| -- | -- | +| `npx` | `npx -y skills@1` | +| `bunx` | `bunx skills@1` | +| `bun` | `bun x skills@1` | +| `pnpm` | `pnpm dlx skills@1` | +| `yarn` | `yarn dlx skills@1` — Yarn 2+ only | +| `deno` | `deno run -A npm:skills@1` | + +An unknown runner falls through to ` $(PurviewSkillsPackage)`, so it still works. + +`DetectPurviewSkillsCli` probes `PATH` for `skills` first, then `$(PurviewSkillsRunner)`, then +`$(PurviewSkillsRunnerCandidates)`, honouring `PATHEXT` on Windows where these are `.cmd` shims. +`PATH` is read directly rather than by spawning a version check: deterministic, no process, and it +cannot hang on a cold download. **The runner actually found wins over the configured preference.** +`PurviewSkillsCommand` overrides the launcher entirely and skips detection. + +`ListPurviewSkills` reports runner availability but **never** errors on its absence — resolving and +reporting needs no Node tooling at all. + +## Always the repository root + +`skills-lock.json` and the agent directories belong to the repository, not to a project, so every +skill target runs from one resolved root: + +1. `PurviewSkillsInstallRoot` — an explicit override +2. `PurviewSkillsRepoRoot` — only when the **user** set it +3. the `PurviewRepositoryRootMarkers` walk +4. `PurviewSkillsRepoRoot` / `RepoRoot` as the SDK guessed them +5. CI workspace variables +6. SourceLink's git `SourceRoot` + +There is deliberately **no project-directory fallback**. That would scatter a lockfile and an agent +directory through the tree, one per project. An unresolved root is `PRSKL0003` on install, and +silence for recommendations — a build never fails over advice. + +The marker walk is described in [references/repository-root.md](references/repository-root.md); its +two-pass behaviour and its home-directory bound are both load-bearing. + +## Why the CLI rather than a reimplementation + +The CLI owns the agent-specific destinations and their discovery conventions, which differ per agent +and change independently of this SDK. It also owns `skills-lock.json`, so a repository can restore +the same set later with `npx skills experimental_install`. + +`PurviewSkillsAgents` (default `*`) narrows the target agents. + +The lockfile is read **directly** rather than by parsing `npx skills list --json`, because that +listing omits the `ref` — and the ref is the whole compatibility question. Reading a file also needs +no Node tooling, which is what keeps recommendations working on a machine that can build .NET but +has no Node. There is deliberately no competing lockfile. diff --git a/.agents/skills/purview-buildsdk-skill-installation/references/repository-root.md b/.agents/skills/purview-buildsdk-skill-installation/references/repository-root.md new file mode 100644 index 00000000..e90b695c --- /dev/null +++ b/.agents/skills/purview-buildsdk-skill-installation/references/repository-root.md @@ -0,0 +1,55 @@ +# The repository-root marker walk + +`FindPurviewRepositoryRoot` is an inline MSBuild task driven by `PurviewRepositoryRootMarkers`: + +```text +.git/;.github/;.gitattributes;LICENSE.md;AGENTS.md;.agents/;CLAUDE.md;.claude/;package.json +``` + +A trailing slash marks a directory. A directory marker still matches a **file** of that name, +because `.git` is a directory in a clone but a file in a worktree or a submodule, and both identify +a repository root. + +## Three things that are load-bearing + +### It cannot be an MSBuild intrinsic + +`GetDirectoryNameOfFileAbove` matches **files only** and returns nothing for `.git/`, `.github/`, +`.agents/` or `.claude/` — four of the nine markers. Verified, not assumed. + +### Two passes + +- **Pass 1** — the first marker in the list is *definitive* and is searched all the way up. `.git/` + *is* the repository root, so a monorepo sub-package with its own `package.json` does not win. +- **Pass 2** — every other marker resolves nearest-ancestor-first, with list order breaking ties + inside a single directory. Searching them all to the top would let a stray `.claude/` in a + developer's home directory outrank the real root. + +### The home directory is never a candidate + +The home directory and everything above it are excluded. Without that bound, a project outside any +repository resolves to `~` and installs into it — and a `.claude/` or a `.github/` very commonly +sits there. A repository *below* the home directory is unaffected, because it is below it. + +## Why the marker walk outranks the evaluation-time guess + +`PurviewSkillsRepoRoot` is computed during evaluation from `RepoRoot` and an `AGENTS.md` walk-up. +An `AGENTS.md` can legitimately sit in a subdirectory, and resolving to it would put a lockfile and +an agent directory somewhere that is not the repository. + +`_PurviewSkillsRepoRootWasSpecified` is captured in `Sdk.props` *before* defaulting, so a value the +**user** set still outranks the walk while a value the SDK guessed does not. + +## A target's Condition is evaluated before its DependsOnTargets + +A property a dependency computes is still empty in the depending target's `Condition`. That is why +the unresolved-root guard sits on the `EvaluatePurviewSkillState` task rather than on +`RecommendPurviewSkills` — and equally why the build hook's CI and design-time gating works at all. + +## The managed port + +`Purview.Skills.Testing` ships `SkillRepositoryRoot`, a managed port of the same walk with the same +default markers, so a test that validates a repository's skills resolves the same root the build +installs them into. The two are kept in step by `SkillRepositoryRootTests`, including an assertion +on the default marker list itself — both are defaults nobody sets, so nothing else would notice them +drifting apart. diff --git a/.agents/skills/purview-buildsdk-skill-tests/SKILL.md b/.agents/skills/purview-buildsdk-skill-tests/SKILL.md new file mode 100644 index 00000000..4043ac4f --- /dev/null +++ b/.agents/skills/purview-buildsdk-skill-tests/SKILL.md @@ -0,0 +1,131 @@ +--- +name: purview-buildsdk-skill-tests +description: Author agent skills in a repository that uses Purview.BuildSdk, and validate them with Purview.Skills.Testing or the SDK's pack-time ValidatePurviewSkills target. Use when adding or renaming a skill, writing SKILL.md frontmatter, splitting content into references/ or scripts/, fixing a PRSKL0005 pack failure or a skill-name, skill-description or skill-bundled-resources test failure, or deciding where skills belong in a repository. +license: MIT +metadata: + package: Purview.Skills.Testing + repository: purview-dev/build-sdk +--- + +# Authoring and validating agent skills + +For installing skills a package ships, use `purview-buildsdk-skill-installation`. + +## Where skills live + +**At the repository root, in `skills//SKILL.md`.** Always. + +The skills CLI only discovers skills at a root `skills/` folder, and it reaches a repository by +The skills CLI only discovers skills at a root `skills/` folder, and it reaches a repository by +cloning it, so nothing else is visible to it. Nothing is packed into a NuGet package — a package +carries .NET artifacts, and skills are delivered by the CLI from git. + +```text +skills/ + my-skill/ + SKILL.md required + references/ loaded on demand + scripts/ executable, run on demand + assets/ templates and static resources +``` + +Link to a skill by its **authored** path, `./skills//SKILL.md`. A link into `.agents/skills/` +points at a gitignored file that does not exist in a fresh clone. + +## `SKILL.md` format + +```markdown +--- +name: my-skill +description: What it does, and when to use it. Include the words a task would contain. +license: MIT +metadata: + package: My.Package +--- + +# My skill + +Instructions. +``` + +| Field | Required | Constraint | +| -- | -- | -- | +| `name` | yes | 1–64 chars, lowercase `a-z0-9` and single hyphens, no leading, trailing or consecutive hyphen, **must equal the folder name** | +| `description` | yes | 1–1024 chars, non-empty | +| `license` | no | A licence name, or the name of a bundled licence file | +| `compatibility` | no | ≤500 chars, only when the skill has real environment requirements | +| `metadata` | no | A map of string to string. Anything not defined above belongs here | +| `allowed-tools` | no | Space-separated pre-approved tools. Experimental | + +**There are no other top-level fields.** `category`, `roles` and `tags` are common inventions and a +strict client rejects them; put them under `metadata`. + +The full specification is at . +[references/authoring.md](references/authoring.md) covers description writing, naming for a shared +namespace, and progressive disclosure. + +## Progressive disclosure + +An agent loads a skill in three stages: the `name` and `description` at startup, the whole +`SKILL.md` body once the skill activates, and `references/`, `scripts/` or `assets/` only when the +task reaches them. + +So: keep `SKILL.md` **under 500 lines**, and move detail into `references/`. The body is a cost paid +on every activation; a reference file is paid only when it is needed. + +Keep file references one level deep from `SKILL.md`, and relative to the skill root. A path that +climbs out of the skill folder is broken everywhere except the authoring repository, because only +the skill's own folder is installed. + +## Validating + +### In tests — `Purview.Skills.Testing` + +```csharp +[InheritsTests] +public sealed class SkillTests : PurviewSkillTests; +``` + +**`[InheritsTests]` is load-bearing.** TUnit does not walk base types during discovery, so without +it the class compiles, the run is green and nothing is validated. TUnit reports `TUnit0030`; treat +it as an error. + +| Rule id | What it checks | +| -- | -- | +| `skills-discovery` | The folder, when present, holds at least one skill | +| `skill-structure` | Every folder has a `SKILL.md` whose frontmatter parses | +| `skill-name` | Spec-legal, unique, and equal to the folder name | +| `skill-description` | Present, non-empty, within 1024 characters | +| `skill-optional-fields` | Only spec-defined fields, each within its limit | +| `skill-bundled-resources` | Every linked file exists, inside the skill folder | +| `skill-body-size` | `SKILL.md` stays under the recommended 500 lines | + +A repository with **no** `skills/` folder passes every rule — authoring skills is optional. An +**empty** folder fails `skills-discovery`, because every other rule is vacuous against an empty +catalogue. + +Overrides: `RepositoryRoot` (default: the SDK's repository-root marker walk), +`SkillsFolderName` (default `skills`), and `SkipRule(string)`. + +The evaluator takes a `SkillCatalogue`, so a rule can be exercised against a fixture folder rather +than a real repository — the same three-layer shape this repository uses throughout: a reader, an +evaluator over an in-memory model, and a thin test base class. + +### At pack time — `ValidatePurviewSkills` + +It runs `BeforeTargets="Pack"`, so a malformed skill fails in the repository that owns it rather +than reaching the CLI, which would silently skip it. + +```bash +dotnet msbuild -t:ValidatePurviewSkills +``` + +Failures are reported as `PRSKL0005`, one per problem. Every authored skill is checked. + +The two checks overlap deliberately: the pack-time one runs without a test host, the test one +covers more of the specification. + +## What is deliberately not checked + +Prose quality, and whether an agent actually obeys the skill. A build can only check that a skill is +well formed. Treat a green run as "installable", not "good". diff --git a/.agents/skills/purview-buildsdk-skill-tests/references/authoring.md b/.agents/skills/purview-buildsdk-skill-tests/references/authoring.md new file mode 100644 index 00000000..69d4ee45 --- /dev/null +++ b/.agents/skills/purview-buildsdk-skill-tests/references/authoring.md @@ -0,0 +1,79 @@ +# Authoring a skill that fires, and keeps firing + +## The description is the whole activation decision + +`name` and `description` are the only things loaded at startup. Everything else — the body, the +references, the scripts — is invisible until an agent has already decided to activate the skill on +the strength of those two fields. + +So write the description for a *matcher*, not for a reader: + +- Say **what it does** and **when to use it**, in that order. +- Include the words a real task would contain: the tool names, the file names, the error codes, the + property names, the phrases a person would type. +- Name the thing the skill is *not*, when a neighbouring skill could be confused with it. + +| | | +| -- | -- | +| Poor | `Helps with the build SDK.` | +| Better | `Configure Purview.BuildSdk from Directory.Build.props or a .csproj. Use when setting NamespacePrefix, choosing a testing framework, or working out whether a property must be set before the SDK import.` | + +The limit is 1024 characters. Most of that budget is better spent on trigger words than on prose. + +## Naming for a shared namespace + +Skills install into one flat directory per agent, shared with every other skill a developer has +installed from anywhere. A generic name is a collision waiting to happen, and the loser is whichever +one installed second. + +- Prefix with the vendor and the product: `purview-buildsdk-configuration`, not `sdk-configuration`. +- `sdk-*`, `project-*`, `test-*`, `build-*` are all too common to use unprefixed. +- The name must be 1–64 characters, lowercase `a-z0-9` with single hyphens, no leading, trailing or + consecutive hyphen — and it must equal the folder name, because the CLI installs by the + frontmatter name while a human reads the folder. + +Renaming a skill means renaming the folder and the frontmatter together, and re-running the install. + +## Progressive disclosure in practice + +| Stage | Loaded | Budget | +| -- | -- | -- | +| Metadata | `name`, `description` | ~100 tokens, always | +| Instructions | the whole `SKILL.md` body | under 5000 tokens recommended; keep the file under 500 lines | +| Resources | `references/`, `scripts/`, `assets/` | only when the task reaches them | + +What belongs where: + +- **`SKILL.md`** — the decisions, the rules, the things that are wrong by default, and a pointer to + everything else. If a reader needs it to make the *first* correct move, it goes here. +- **`references/`** — long tables, full option lists, grammars, enumerations. Keep each file + focused; an agent loads the whole file. +- **`scripts/`** — executable code. Self-contained, or documenting its dependencies clearly, with + helpful error messages. +- **`assets/`** — templates, schemas, images, lookup data. + +Keep references one level deep. Avoid a chain where one reference sends an agent to another. + +## Links + +Use relative paths from the skill root: + +```markdown +See [the reference](references/REFERENCE.md) for detail. +Run `scripts/extract.py`. +``` + +Only the skill's own folder is installed, so a link that climbs out of it (`../other-skill/...`) is +broken on every machine except the one that authored it. To point at another skill, name it in prose +and let the agent find it by name. + +## Keeping a skill true + +A skill that describes a product goes stale the moment the product changes, and nothing about a +stale skill looks broken — it just gives confidently wrong advice. + +- Change the skill in the **same commit** as the behaviour it documents. +- Prefer stating the property name, the diagnostic code or the target name over paraphrasing the + behaviour; those are greppable when the code changes. +- Where a number or a list is authoritative somewhere else — a default, an enumeration — say where + it comes from, so a reader can check it. diff --git a/.agents/skills/purview-buildsdk-testing/SKILL.md b/.agents/skills/purview-buildsdk-testing/SKILL.md new file mode 100644 index 00000000..5a5a7d53 --- /dev/null +++ b/.agents/skills/purview-buildsdk-testing/SKILL.md @@ -0,0 +1,121 @@ +--- +name: purview-buildsdk-testing +description: Write and run tests in a repository that uses Purview.BuildSdk. Use when authoring or refactoring TUnit tests (AAA structure, Subject_Scenario_Expectation naming, awaited assertions, CancellationToken), when choosing a test project's framework packages, and when running or filtering tests - the SDK wires Microsoft.Testing.Platform, so `dotnet test --filter` reports "Zero tests ran" and `--treenode-filter` is the one that works. +license: MIT +metadata: + package: Purview.BuildSdk + repository: purview-dev/build-sdk +--- + +# Testing in a Purview.BuildSdk repository + +Two things to know before anything else: + +1. A test project is detected by **name**, and detection is what wires the runner. See + `purview-buildsdk-project-layout` if the project is new or being moved. +2. The runner is **Microsoft.Testing.Platform (MTP)**, not VSTest. `--filter` does nothing useful. + +## What a test project gets automatically + +With the defaults (`TestingFramework=TUnit`, `SubstituteFramework=TUnitMocks`, +`TestDataFramework=Bogus`), a detected test project receives: + +- `TUnit`, `TUnit.Mocks`, `Bogus` +- Microsoft.Testing.Platform integration +- `CollectCoverage=true` +- test-friendly `NoWarn` defaults (`PurviewTestContextNoWarn`), while keeping the strict style + contract — `IDE0040`, field naming, formatting, `IDE1006` +- `IsPackable=false`, `IsPublishable=false` + +Add nothing else unless the project's purpose demands it. Two that stay explicit: + +- `TUnit.Aspire` — Aspire lifecycle and AppHost-backed integration tests +- `Purview.Containers` — container-backed integration tests. One API over Microsoft WSL Containers + (no Docker install needed on Windows) or Docker, with typed modules for SQL Server, PostgreSQL, + Redis, MySQL, RabbitMQ, Azurite and NATS. Experimental and prerelease, so pin the version. + Reference `Testcontainers` directly only where no typed module exists yet. + +## Authoring rules + +- Use TUnit (`TUnit.Core`, `TUnit.Assertions`). Do not introduce xUnit, NUnit, MSTest or + FluentAssertions unless explicitly asked. +- Every test method carries `[Test]`. +- **Every assertion is awaited**: `await Assert.That(actual).IsEqualTo(expected);`. An un-awaited + assertion silently passes. +- Arrange / Act / Assert, with the `// Arrange`, `// Act`, `// Assert` comments present. +- Test classes are `{SubjectName}Tests`, in the **same namespace** as the subject. +- Test methods are `{SubjectOrMemberUnderTest}_{Scenario}_{Expectation}`. Use `ctor` as the subject + for constructor tests. Methods, constructors, properties, operators, conversions and validation + hooks are all valid subjects. +- When any method called in the test body accepts a `CancellationToken`, take + `CancellationToken cancellationToken` as the **last parameter** and pass it through. + +```csharp +[Test] +public async Task ProcessAsync_GivenAnEmptyBatch_ReturnsZero(CancellationToken cancellationToken) +{ + // Arrange + var sut = new BatchProcessor(); + + // Act + var result = await sut.ProcessAsync([], cancellationToken); + + // Assert + await Assert.That(result).IsEqualTo(0); +} +``` + +For a suite that is not subject-based — a build, generator, workflow, package or full-system suite — +a broader, more truthful class name is better than a forced `{Subject}Tests`. Use TUnit display +names and categories to keep it navigable. + +When refactoring existing tests, bring them into compliance with all of the above while preserving +test intent. + +## Categories + +The detected test type becomes the baseline category automatically — `Api.IntegrationTests` yields +`Category=Integration`. Add further categories when they make a large suite easier to navigate; +they are what `--treenode-filter` property predicates select on. + +## Running tests + +```bash +dotnet test # the whole suite +dotnet test --treenode-filter "/*/*/LoginTests/*" # one class +dotnet test --treenode-filter "/*/*/*/*[Category=Unit]" +``` + +Prefer the repository's own task (`just test`, or equivalent) for a full run. + +The filter path is `////`, with `*` wildcards, `=`/`!=` property +predicates, `&`/`|` inside a single bracket group, and `**` only at the end. The full grammar, the +`--` separator rules across SDK versions, and the zero-tests checklist are in +[references/treenode-filter.md](references/treenode-filter.md). + +### "Zero tests ran" + +In order: + +1. Are you using `--treenode-filter` and not `--filter`? This is the cause most of the time. +2. Try `dotnet test --treenode-filter "..."`; on an older SDK use `dotnet test -- --treenode-filter "..."`. +3. Broaden to `/*/*/*/*`, then narrow one segment at a time. +4. Does the project actually contain `[Test]` methods? +5. Is the project **detected** as a test project? A name without the dot — `UnitTests` rather than + `Api.UnitTests` — gets no runner at all. Check with + `dotnet msbuild -getProperty:IsTestProject`. +6. Are all property predicates inside one bracket group, `[(A=1)&(B=2)]`? + +## Cross-platform requirement + +CI runs the full suite on Linux, so a test that only passes on Windows is a failing change. + +- Never hardcode a platform-specific path — no `C:\...`, no backslash-only separators, no + case-insensitive path assumptions. +- Build paths with `Path.Combine`, `Path.GetTempPath()`, `Path.DirectorySeparatorChar`, + `Path.GetFullPath()`. +- Feed production path-math code only native-format paths. Normalise a fixed Windows-style literal + to the current platform before passing it in. +- Do not rely on a case-insensitive filesystem, a `C:` drive, or trailing-separator behaviour. +- Keep `SyntaxTree` file paths and `build_property.*` values consistent and native when writing + analyzer tests. diff --git a/.agents/skills/purview-buildsdk-testing/references/treenode-filter.md b/.agents/skills/purview-buildsdk-testing/references/treenode-filter.md new file mode 100644 index 00000000..35d032bc --- /dev/null +++ b/.agents/skills/purview-buildsdk-testing/references/treenode-filter.md @@ -0,0 +1,107 @@ +# `--treenode-filter` reference + +TUnit runs on Microsoft.Testing.Platform, not VSTest, so the VSTest `--filter` syntax does not +apply. Narrowing is done with `--treenode-filter`. + +## The path + +```text +//// +``` + +Each segment maps to one level of the tree: + +| Position | Matches | +| -- | -- | +| 1 | Assembly | +| 2 | Namespace | +| 3 | Class | +| 4 | Test name | + +```text +/*/*/LoginTests/* every test in LoginTests +/*/*/*/AcceptCookiesTest one test by name +/*/MyProject.Tests.Integration/*/* every test in a namespace +/*/*/*/* everything +``` + +## Operators + +### `*` — wildcard + +Matches a whole segment or part of one. + +```text +/*/*/LoginTests*/* +/*/*/MyProject.Tests.Api*/* +``` + +### `=` and `!=` — property predicates + +In the last segment, inside `[...]`. + +```text +/*/*/*/*[Category=Unit] +/*/*/*/*[Category!=Slow] +/*/*/*/*[Owner=*Team-Backend*] +``` + +### `&` and `|` — combining + +Inside a **single** bracket group, or a single parenthesised segment. + +```text +/*/*/*/*[(Category=Unit)&(Priority=High)] +/**[(Category=Unit)|(Priority=High)] +/*/*/(LoginTests)|(SignupTests)/* +``` + +### `**` — match all + +Any depth, but **only at the end** of the path. + +```text +/** +/MyAssembly/** +``` + +`/**/Path` is not valid. + +## Rules that catch people out + +- Only **one** property group `[...]` per path segment. `[Category=Smoke]|[Priority=High]` is not + valid; write `[(Category=Smoke)|(Priority=High)]`. +- `**` must be last. +- A segment left empty is not a wildcard — write `*`. + +## The `--` separator + +```bash +dotnet test --treenode-filter "/*/*/*/*[Category=Unit]" # preferred +dotnet test -- --treenode-filter "/*/*/*/*[Category=Unit]" # older SDKs +``` + +Newer .NET SDKs forward unrecognised arguments to the MTP runner directly. On an older SDK the `--` +separator is required, and omitting it produces an argument error rather than a filter. + +## Common selections + +| Intent | Filter | +| -- | -- | +| Everything | `/*/*/*/*` | +| All unit tests | `/*/*/*/*[Category=Unit]` | +| High-priority unit tests | `/*/*/*/*[(Category=Unit)&(Priority=High)]` | +| One class | `/*/*/MyFeatureTests/*` | +| A name pattern | `/*/*/*/MyScenario*` | +| Critical integration tests | `/*/MyProject.Tests.Integration/*/*[Priority=Critical]` | + +## Zero tests ran + +1. `--treenode-filter`, not `--filter`. +2. Try without the `--` separator first, then with it. +3. Broaden to `/*/*/*/*`, then narrow one segment at a time. +4. Confirm the project has `[Test]` methods. +5. Confirm the project is **detected** as a test project — + `dotnet msbuild -getProperty:IsTestProject`. A name without the dot, such as + `UnitTests` rather than `Api.UnitTests`, is not detected and gets no runner. +6. Confirm every property predicate sits in one bracket group. diff --git a/.agents/skills/purview-results-core/SKILL.md b/.agents/skills/purview-results-core/SKILL.md new file mode 100644 index 00000000..93719fdd --- /dev/null +++ b/.agents/skills/purview-results-core/SKILL.md @@ -0,0 +1,140 @@ +--- +name: purview-results-core +description: "Use when writing or reviewing code that returns Purview.Results Result or value-less Result values — choosing between exceptions and results, creating, reading, or transforming a result, and reasoning about the uninitialized default state." +--- + +# Purview.Results core + +Use this skill whenever a method returns `Result` or the value-less `Result` from the +`Purview.Results` package. + +## The three states + +`Result` is a `readonly record struct`, so `default` is a real, observable state. + +| State | `IsInitialized` | `IsSuccess` | `IsFailure` | `Value` | `Error` | +| --- | --- | --- | --- | --- | --- | +| Success | `true` | `true` | `false` | the value | throws | +| Failure | `true` | `false` | `true` | throws | the error | +| Uninitialized (`default`) | `false` | `false` | `false` | throws | throws | + +`Value` and `Error` throw `InvalidOperationException` when the result is in the wrong state, and `Match`, `Map`, +`Bind` and `MapError` throw `"The result is uninitialized."` for `default`. **An uninitialized result is a bug, +never a success and never a failure** — if a method can fail to produce a result, return a failure case instead +of falling off the end of the method body. + +## Creating results + +```csharp +// Named factories +Result.Success(tenant); +Result.Failure(new TenantNotFound(id)); + +// Type-inferring factories +Result.Success(tenant); +Result.Failure(new TenantNotFound(id)); + +// Implicit conversions (one hop only) +Result ok = tenant; +TenantError error = new TenantNotFound(id); // case -> union is one hop +Result failed = error; // union -> result is the next hop + +// Union-receiver factory (generated for [GenerateResult] unions; shared-case safe) +TenantError.Failure(new TenantNotFound(id)); +TenantError.Failure(new TenantNotFound(id)); +TenantError.Success(); +TenantError.Success(tenant); +``` + +The implicit conversions accept `TValue` or `TError` directly. They do **not** compose: a union *case* cannot +convert to the result in one hop, which is why the source generator exists (see the +`purview-results-union-errors` skill). + +## Reading and transforming + +| Member | Purpose | +| --- | --- | +| `Match(success, failure)` | Fold both states into one value | +| `Map(map)` | Transform the successful value, preserving the error | +| `Bind(bind)` | Chain an operation that can fail, preserving the error type | +| `Bind(bind, mapError)` | Chain an operation that fails with a different error type, widening the existing error | +| `MapError(map)` | Transform the error, preserving the value | +| `TryGetValue(out value)` | Probe without throwing: `true` only for a success | +| `TryGetError(out error)` | Probe without throwing: `true` only for a failure | +| `GetValueOrDefault()` / `(fallback)` / `(factory)` | Value, or a default/fallback — throws for `default` | +| `GetErrorOrDefault(fallback)` | Error, or a fallback — throws for `default` | +| `OrElse(fallback)` | This result when successful, otherwise another result | +| `Switch(success, failure)` | Side effects per state; returns `void` | +| `Tap(success)` / `TapError(failure)` | Side effects that return the result, so calls can be chained | +| `Ensure(predicate, errorFactory)` | Turn a value that fails a predicate into a failure | +| `MapAsync(map)` / `BindAsync(bind)` | Asynchronous `Map`/`Bind` | +| `BindAsync(bind, mapError)` | Asynchronous widening `Bind` | +| `Throw()` | Return the value, or throw `ResultException` carrying the error (escape hatch) | + +Prefer `Match`/`Map`/`Bind` over `if (result.IsSuccess)` when a value has to come out of the result: they keep +the failure path explicit and cannot silently leak a `default`. + +`TryGetValue`/`TryGetError` are the only members that never throw; the rest throw for `default` so a forgotten +initialization surfaces immediately. + +## Value-less results + +When an operation has nothing to return on success — a command, a validation-only step — use `Result` +instead of inventing a meaningless value (a `bool`, a `Unit`). It has the same three states and the same +throw-on-misuse contract, but a success holds the `Success` marker and its success callbacks take no argument: + +```csharp +Result DeleteTenant(TenantId tenantId) => + _tenants.Remove(tenantId) + ? Result.Success() + : new TenantNotFound(tenantId).AsFailure(); + +deleted.Match(() => "deleted", error => $"could not delete: {error}"); +deleted.Map(() => 1); // attach a value: Result +deleted.Bind(() => GetTenant(tenantId)); // continue with another operation +deleted.Ensure(() => _tenants.Count > 0, () => new TenantError()); +``` + +- `Result.Success()` / `.Failure(error)`, `Result.Success()` / `Result.Failure(error)`, + and the implicit conversions from `Success` and `TError` create a unit result. +- `Match`, `Switch`, `Tap` and `Ensure` take a **no-argument** success delegate; `Map` produces a value from a + success that had none; `Bind` continues with either another unit operation or a value-producing one. +- `Error` throws in the wrong state; `Throw()` returns the `Success` marker or throws `ResultException`; + `ToString()` is `Success` / `Failure(error)` / `Uninitialized`. +- `Result.DiscardValue()` drops a value result's value and keeps the error, so a value result can + join a unit-result chain. + +Use `Result` when the failure is the only interesting outcome; use `Result` when the +caller needs the produced value. + +## Infrastructural view + +`IResultValue` is the non-generic, read-only view (`IsInitialized`, `IsSuccess`, `SuccessValue`, `ErrorValue`) +for code that cannot be generic over the value and error types — an endpoint filter or a logging middleware, for +example. Its accessors never throw: the one that does not describe the current state returns `null`, and a +successful unit `Result` reports the `Success` marker as its `SuccessValue`. Use it in infrastructure, and +the generic type in domain code. + +## When to use a result + +**Use it** for expected, domain-level outcomes the caller must handle: not found, invalid, conflict, disabled, +already exists. These are values with meaning, and making them explicit keeps the happy path readable. + +**Throw instead** for programming errors and unrecoverable infrastructure faults (a lost connection, a violated +invariant, a missing configuration key). Wrapping those in a result forces every caller to branch on something +it cannot act on. + +Rules of thumb: + +1. If the caller is expected to *do* something different per outcome, the outcome is a result value. +2. If the caller can only log and rethrow, it is an exception. +3. Never use `Result` where the failure is the only interesting outcome — use the value-less + `Result` instead, or model the outcomes as cases. +4. Convert at the boundaries: a controller or endpoint handler turns the result into a response, an application + service returns it, and repositories return it rather than throwing on "not found". + +## Related skills + +- `purview-results-union-errors` — modelling the error type as a union and generating the failure helpers. +- `purview-results-http-mapping` — turning results into ASP.NET Core responses. +- `purview-results-zodsharp-validation` — folding ZodSharp validation outcomes into results. diff --git a/.agents/skills/purview-results-http-mapping/SKILL.md b/.agents/skills/purview-results-http-mapping/SKILL.md new file mode 100644 index 00000000..ac4629ea --- /dev/null +++ b/.agents/skills/purview-results-http-mapping/SKILL.md @@ -0,0 +1,135 @@ +--- +name: purview-results-http-mapping +description: "Use when an ASP.NET Core endpoint returns Purview.Results values — registering AddResultsHttp, mapping error cases to status codes with Map, answering a failure by its shape with an IResultsFailureMapper, using fallbacks, correcting unmapped-failure 500s, or converting a result with ToHttpResult." +--- + +# Mapping results onto ASP.NET Core responses + +Use this skill when a minimal-API endpoint, or any handler, returns `Result` or the value-less +`Result` and the host has to decide what each error case looks like on the wire. + +## Registration + +```csharp +using Microsoft.Extensions.DependencyInjection; + +builder.Services.AddResultsHttp(options => options + .Map(error => TypedResults.NotFound()) + .Map(error => TypedResults.Problem( + statusCode: StatusCodes.Status403Forbidden, + title: "The tenant is disabled.")) + .Map(error => TypedResults.Problem(statusCode: StatusCodes.Status409Conflict)) // every other case +); + +app.MapGet("/tenants/{id:int}", (int id) => GetTenant(id)).WithResultsHttp(); +``` + +- `AddResultsHttp` registers problem-details services, the mapper (`TryAddSingleton`, so a host can register its + own first) and the endpoint filter. Its `configure` callback is optional. +- `WithResultsHttp()` exists on both `RouteHandlerBuilder` and `RouteGroupBuilder` and adds the endpoint filter. + A handler that returns something other than an `IResultValue` is left untouched, so the filter is safe to + apply to a whole group. +- Mapping by hand is also supported: `result.ToHttpResult(context)` resolves the mapper from the request + services, and `result.ToHttpResult(mapper, context)` takes one directly. + +## Response resolution order + +**Success** + +1. `SuccessMapper` when set — it replaces the default entirely. +2. A successful value that is itself an `IResult` is passed through untouched. +3. A successful unit `Result` carries no payload, so it answers `204 No Content`. +4. Otherwise the value is serialized: `200 OK` for the default status code, `TypedResults.Json(value, + statusCode: …)` when `SuccessStatusCode` was changed. + +**Failure** — the error is resolved to its *case* value (the innermost active union case, so a nested union +resolves to its leaf; or the error itself when it is not a union), then: + +1. the mapping registered for the most specific **case** type — `Map(…)`; +2. the mapping registered for each enclosing **union** type, from the inside out — `Map(…)` handles + a whole nested union when its leaf has no mapping; +3. the mapping registered for the **error** type — `Map(…)`, which covers every case without its + own mapping; +4. the **fallback stage**, in registration order — `AddFallback(...)` delegates and + `AddFailureMapper()` mappers share this one list, so whichever was registered first is consulted + first; returning `null` defers to the next entry; +5. the **unmapped-failure** response. + +Registering the same type twice replaces the earlier mapping. Fallbacks receive the *leaf* case value, so a +fallback never has to unwrap the union itself. + +## Shape-based rules + +`Map` is keyed by type, which cannot see the *value* a failure carries. When the answer depends on the +payload — a validation error code, a category, a field — register a failure mapper instead: + +```csharp +public sealed class BlankIdentifierMapper : IResultsFailureMapper +{ + public IResult? Map(ResultsFailureContext context) => + context.Case is ITenantFailure { TenantId.Value: var id } && string.IsNullOrWhiteSpace(id) + ? TypedResults.Problem(statusCode: StatusCodes.Status400BadRequest, title: "An identifier is required.") + : null; // defer to the case mappings and the other fallbacks +} + +builder.Services.AddSingleton(); +builder.Services.AddResultsHttp(options => options.AddFailureMapper()); +``` + +- `ResultsFailureContext` carries `Case` (the innermost active case, so a nested union resolves to its leaf; or + the error itself for a non-union error), `Error` (the union or error value as a whole) and `HttpContext`. +- The mapper is resolved from the request's services, so it may take dependencies in its constructor; register + it before the first request or the failure throws an `InvalidOperationException` naming what is missing. +- A mapper shares the fallback list with `AddFallback`, so **registering it earlier makes it win** — that is how + a host answers some validation codes before a package's validation mapping (see + `purview-results-zodsharp-problems`). +- **A mapper is not a catch-all.** Answering every failure with a generic problem hides the mapping gaps the + unmapped-failure `500` exists to expose. Answer the shape you can name and return `null` for the rest. + +## Options + +| Option | Default | Notes | +| --- | --- | --- | +| `SuccessStatusCode` | `200` | Status for a serialized successful value | +| `SuccessMapper` | `null` | Replaces the default success handling | +| `UnmappedStatusCode` | `500` | Status for a failure with no mapping | +| `UnmappedTitle` | *"The operation failed with an error that is not mapped to an HTTP response."* | Title of the unmapped problem | +| `ThrowOnUnmappedFailure` | `false` | Throw instead of responding; use during development | +| `IncludeTraceId` | `true` | Whether problems this package writes carry the request trace identifier | + +## Treat an unmapped failure as a bug in the host + +An unmapped failure is a **mapping gap**, not a domain outcome: the response is `UnmappedStatusCode` (`500`) +with a `ProblemDetails` carrying an `errorType` extension naming the case, and an error is logged. When you see +one in the logs, add the mapping; do not widen a catch-all mapping to silence it. + +The same path handles an **uninitialized** result (`default`), which is logged and answered with +`errorType = "results_uninitialized"` — an endpoint returning `default` is always a bug in the handler. + +During development, `ThrowOnUnmappedFailure = true` turns both into an `InvalidOperationException` so the gap +surfaces at the call site. + +## Choosing status codes + +Map the *case*, not the HTTP verb: + +| Domain meaning | Response | +| --- | --- | +| Input failed validation | `400` with a validation problem (see `purview-results-zodsharp-problems`) | +| Not authenticated / not authorised | `401` / `403` | +| The thing does not exist | `404` | +| The thing already exists | `409` | +| The thing is in the wrong state for this operation | `409` or `422` | +| Rate-limited or temporarily unavailable | `429` / `503` | + +Keep the mapping table next to `AddResultsHttp` so every case is visible in one place; a case that is missing +from it is exactly what the unmapped-failure log is telling you. + +## Pitfalls + +- **Do not** return `IResult` from domain or application code — results stay transport-agnostic and the host + keeps the mapping. +- **Do not** map a case to a status code you would not document; `500` for a domain outcome hides real bugs. +- A shared case type used by two unions can be mapped once — mapping is keyed by the case type. +- The unmapped `ProblemDetails` is written through `IProblemDetailsService`, so ASP.NET Core adds the trace + identifier itself; `IncludeTraceId` only affects problems this package serializes itself. diff --git a/.agents/skills/purview-results-union-errors/SKILL.md b/.agents/skills/purview-results-union-errors/SKILL.md new file mode 100644 index 00000000..ce6ea9ab --- /dev/null +++ b/.agents/skills/purview-results-union-errors/SKILL.md @@ -0,0 +1,179 @@ +--- +name: purview-results-union-errors +description: "Use when modelling expected failures as a C# 15 union and converting its cases into Purview.Results values — declaring [GenerateResult] unions, using the generated per-case AsFailure()/AsFailure() helpers and the union-receiver Union.Failure(...)/Union.Success(...) factories, reacting to the RSG1000-RSG1008 diagnostics, or explaining why a union case cannot convert implicitly." +--- + +# Modelling error unions for Purview.Results + +Use this skill when a codebase models expected failures as a **union** and returns +`Result` or the value-less `Result` from the `Purview.Results` package. + +Replacing thrown domain exceptions, `bool`/`out` pairs or error enums in existing code? The +step-by-step playbook is in +[references/migrating-error-returns.md](references/migrating-error-returns.md). + +## The shape + +```csharp +using Purview.Results; + +// One small, focused type per case. +public readonly record struct TenantNotFound(TenantId TenantId); +public readonly record struct TenantDisabled(TenantId TenantId); +public readonly record struct TenantAlreadyExists(TenantId TenantId); + +// One union per operation family. +[GenerateResult] +public readonly union TenantError(TenantNotFound, TenantDisabled, TenantAlreadyExists); + +public static Result Get(TenantId id) => + _tenants.TryGet(id, out var tenant) + ? Result.Success(tenant) + : new TenantNotFound(id).AsFailure(); // generated +``` + +`AsFailure()` and the non-generic `AsFailure()` are generated **once per case type**, into +`public static class {Union}ResultExtensions` in the union's own namespace. The generic helper calls +`Result.Failure(case)`; the non-generic one calls `Result.Failure(case)` and produces a +value-less unit result: + +```csharp +Result Get(TenantId id) => new TenantNotFound(id).AsFailure(); +Result Delete(TenantId id) => new TenantNotFound(id).AsFailure(); +``` + +The same class declares a C# 14 extension block on the union type, so the union can name the call instead of the +case: + +```csharp +Result Get(TenantId id) => TenantError.Failure(new TenantNotFound(id)); +Result Delete(TenantId id) => TenantError.Failure(new TenantNotFound(id)); +Result ok = TenantError.Success(); +Result created = TenantError.Success(tenant); +``` + +Prefer the union-receiver factory when a case type is shared with another union (`RSG1006`): the per-case +`AsFailure` helper is generated once and can bind to the wrong union, while `Union.Failure(...)` always names the +union you want. A case type that is itself a union is an *included union*: sharing it is composition, so it is not +reported, and the factory also covers the included union's cases by building the nested value. + +## Why the helper is required + +The generator cannot declare an implicit conversion from a case to the result, and neither can you. Five +independent C# rules block it: + +| Attempt | Diagnostic | +| --- | --- | +| Declare the operator beside the helpers | `CS0715` — operators are illegal in a **static class** | +| Declare it in any other helper class | `CS0556` — a conversion must be declared by the **source or target type** | +| Declare it as an extension member | `CS9282` — **conversions are not allowed in extension blocks** | +| Make it generic over the result's value type | `CS0246` — operators **cannot declare type parameters** | +| Rely on `case → union → result` composing | `CS0029` — **one user-defined conversion per sequence** | + +The only shape the language accepts is a *generic case type* carrying the value type parameter, which the +generator rejects as `RSG1002` — so `AsFailure()` is the ergonomics the language allows. + +A helper-free form exists when a cast reads better, because the cast closes the first conversion: + +```csharp +Result Get(TenantId id) => (TenantError)new TenantNotFound(id); +``` + +`Purview.Results` also ships an IDE code fix: when you write +`return new TenantNotFound(id);` in a `Result`- or `Result`-returning member, the +lightbulb offers the `Union.Failure(case)` or `Union.Failure(case)` rewrite. The fix names the union, so it +is correct even when the case type is shared with another union. It is only offered when the rewrite will bind (the +converted type is a result, the error type is a `[GenerateResult]` union, the value is one of its cases, and the +union is in scope by simple name). + +## Chaining across services + +When one service calls another, the caller's operation-family union takes the callee's **error union** as a case, +then the widening `Bind` (or a `TryGetError` guard) lifts the callee's failure into the caller's contract: + +```csharp +[GenerateResult] +public readonly union RegisterTenantError(TenantError, BillingError); + +Result Register(TenantId id, string name) => + billing.ReserveQuota(id) + .Bind(quota => CreateTenant(quota, name), error => error); // BillingError -> RegisterTenantError +``` + +List the union as a case, not its leaf cases: the caller's union-receiver factory then covers the callee's cases and +builds the nested value (`CallerUnion.Failure(leaf)`), so no leaf is shared and no `RSG1006` is raised. A leaf listed +in two unions is a shared leaf: its per-case helper is generated for only one of them, so a case-receiver call site +can bind to the wrong union; convert it with the union-receiver factory instead. A case reachable through two +different included unions is reported as `RSG1008` and its inclusion factory is skipped. To keep the callee's types +out of the caller's contract, map its cases into the caller's own case types with `MapError` instead — the compiler +then forces the mapping to stay exhaustive as the callee's union grows. The ASP.NET Core mapper resolves a union +error to its innermost case, so a leaf mapping wins and an enclosing-union mapping still applies when the leaf has +none. + +## Rules of thumb + +- **One case type, one meaning.** Cases are the vocabulary of the failure surface; a case with a `string + Reason` invites callers to match on that string instead of on the type. +- **One union per operation family**, not one per method: `TenantError` covers every way tenant work fails, so + the union stays a stable contract while methods come and go. +- **Never re-derive the case from the union in the caller** — keep the case strongly typed and let the HTTP or + UI layer map it (see the `purview-results-http-mapping` skill). +- **Small unions are better.** A union with a dozen cases is usually several operation families sharing one + name. +- **Opt in deliberately.** `[GenerateResult]` on a union you do not return from a result produces dead code; + apply it where the union crosses a `Result` boundary. + +## Diagnostics + +The package ships an analyzer and a generator that share one diagnostics library. + +| ID | Severity | Meaning | +| --- | --- | --- | +| `RSG1000` | Error | `[GenerateResult]` was applied to a type that is not a union | +| `RSG1001` | Error | The union declares no union cases | +| `RSG1002` | Error | Generic union, or a case type that contains type parameters | +| `RSG1003` | Error | A type generated code must reference is not accessible (for example a `file` type) | +| `RSG1004` | Error | The same union is configured more than once; the helpers are generated once | +| `RSG1005` | Error | Two unions produce the same generated class name in one namespace | +| `RSG1006` | Warning | A **leaf** case type is shared with another union, so its per-case `AsFailure` helper is generated once; the union-receiver `Failure(...)` factory is generated for every union. A union-typed case shared across unions is composition and is not reported | +| `RSG1007` | Error | The union uses an `IUnionMembers` member provider, which is not supported | +| `RSG1008` | Warning | A case is reachable through two different included unions, so no inclusion factory can name its construction path; that case's inclusion factory is skipped | + +`RSG1004`, `RSG1006` and `RSG1008` are non-blocking: the union (or the shared/ambiguous case) is skipped and +reported. + +Unsupported by design: `IUnionMembers` member providers (`RSG1007`) and generic unions (`RSG1002`). + +## CA1815 needs no pragma + +A union declaration gets no value equality from the compiler, so it raises `CA1815` unless it is silenced by hand. +`[GenerateResult]` unions do not need that: the package ships a diagnostic suppressor that answers `CA1815` for +every union opted in with the attribute, because a result union is read by matching its case type rather than +compared by value. + +- Only the union is covered. A union without `[GenerateResult]`, the union's case types and every other value + type keep the warning, and a case declared as a plain `struct` should still be a `record struct`. +- The suppression is logged as an `Info` diagnostic under the suppression id `RSG2000`, so a build audit can see + exactly what was suppressed. +- `RSG2000` is a suppression id, not a rule: it never appears in the diagnostics table above, and + `$(NoWarn);RSG2000` brings `CA1815` back. + +## Requirements and switches + +- **.NET 11 SDK or later** with `LangVersion=preview` — union declarations are a preview language feature. +- A reference to `Purview.Results`, which provides both result shapes (`Result` and + `Result`) and this generator. +- `-p:DisableResultsSourceGenerator=true` (or a `Directory.Build.props` setting) disables the helpers while + the opt-in attribute is still emitted, which is useful when the generated code has to be inspected in + isolation. + +## Checklist + +1. Cases are small records with meaningful payloads. +2. The union is a `union` declaration annotated with `[GenerateResult]`. +3. Every method that fails for an expected reason returns `Result`, or `Result` when the + success carries no value. +4. Failures are produced with `new Case(...).AsFailure()` (or `AsFailure()` for a unit result, the + union-receiver `Union.Failure(case)` / `Union.Failure(case)` factory, or the cast form). +5. The build is clean of `RSG1000`–`RSG1008`. +6. The union is mapped to responses once, in the host (see `purview-results-http-mapping`). diff --git a/.agents/skills/purview-results-union-errors/references/migrating-error-returns.md b/.agents/skills/purview-results-union-errors/references/migrating-error-returns.md new file mode 100644 index 00000000..b0405f44 --- /dev/null +++ b/.agents/skills/purview-results-union-errors/references/migrating-error-returns.md @@ -0,0 +1,67 @@ +# Migrating ad-hoc failure signalling to an error union + +A playbook for replacing thrown domain exceptions, `bool`/`out` pairs, sentinel return values and +error-code enums with a C# 15 `union` of case types returned as `Result`. + +## Before you start, collect + +- The file(s) being migrated, and the operation family they belong to — a union is per family, not + per method, so methods can come and go without changing the error contract. +- A name for the union (for example `TenantError`). +- The failure modes to model as cases, or the decision to infer them from the current code. +- Whether genuinely exceptional exits stay throwing. They normally should: a lost connection or a + violated invariant is not a domain outcome. + +## Requirements + +1. Declare one `readonly record struct` per failure mode, carrying the payload a caller needs to + react, and declare the union once: + + ```csharp + [GenerateResult] + public readonly union TenantError(TenantNotFound, TenantDisabled, TenantAlreadyExists); + ``` + +2. Change the affected signatures to `Result` — or the value-less + `Result` when the member has nothing to return on success — and produce failures with + `TenantError.Failure(case)` / `TenantError.Failure(case)`, or the per-case + `new Case(...).AsFailure()` / `AsFailure()` helpers. +3. Leave genuinely exceptional exits throwing. +4. Do **not** attempt implicit conversions from a case to a result, and do not add operators, + extension conversions or wrapper types: `CS0715`, `CS0556`, `CS9282`, `CS0246` and `CS0029` each + block that route. Use the generated factory or helper, or `(TenantError)new TenantNotFound(id)` + when a cast reads better. Prefer the union-receiver factory when a leaf case type is shared with + another union (`RSG1006`), because it names the union. +5. Remove the replaced mechanism — thrown domain exceptions, error enums, `out` error parameters, + sentinel values — rather than leaving both paths in place. +6. Keep the union free of transport concerns: no `IResult`, no status codes, no HTTP types. +7. One case type per meaning. A case carrying a `string Reason` or an `int Code` invites string or + int matching and defeats the point. +8. Compose unions rather than repeating leaf cases. A case type that is itself a union is an + *included union*: the including union's factory also covers its cases and builds the nested value, + and sharing a union-typed case across unions is not reported. This is how to avoid `RSG1006`, + which applies only to a shared **leaf** case. + +## Migration strategy + +- Inventory the failure modes and the call sites of each affected member. +- Introduce the cases and the union before changing signatures, so each edit compiles in isolation. +- Update call sites to `Match` / `Map` / `Bind` where a value has to come out of the result, rather + than `if (IsSuccess)`. +- Update or add tests: one per case, asserting the case the caller receives. +- Map the union once in the host — see the `purview-results-http-mapping` skill — instead of deciding + status codes in the domain. + +## Verification + +- Build the solution and confirm no `RSG1000`–`RSG1008` diagnostics. +- Run the affected tests. +- Confirm no remaining `throw` for an outcome the caller is expected to handle. +- Confirm the union appears in exactly one mapper, not scattered through handlers. +- Confirm no method can fall off the end of its body: `default` is a bug, not a failure. +- Reflect public API changes in the package documentation. + +## Report + +When the migration is done, state: the files changed, the union and its cases, the failure modes that +stayed exceptional and why, and the verification performed. diff --git a/.agents/skills/purview-results-zodsharp-problems/SKILL.md b/.agents/skills/purview-results-zodsharp-problems/SKILL.md new file mode 100644 index 00000000..ed0dd935 --- /dev/null +++ b/.agents/skills/purview-results-zodsharp-problems/SKILL.md @@ -0,0 +1,101 @@ +--- +name: purview-results-zodsharp-problems +description: "Use when a Purview.Results failure that carries ZodSharp validation errors has to render as an ASP.NET Core HttpValidationProblemDetails — registering AddResultsZodSharpHttp, calling ToValidationProblem, or making a result-carried rejection and a thrown ZodException produce identical responses." +--- + +# Rendering validation-carrying failures as validation problems + +Use this skill when a result failure carries ZodSharp `ValidationError` values (it implements +`IValidationErrorCarrier`) and the host has to respond with `application/problem+json`. + +## Registration + +```csharp +builder.Services.AddZodSharpProblemDetails(); // the ZodSharp package's own problem options/exception handler +builder.Services.AddResultsHttp(); // the result-to-response mapping +builder.Services.AddResultsZodSharpHttp(); // the bridge: validation-carrying failures -> validation problem +``` + +- `AddResultsZodSharpHttp()` registers the ZodSharp problem options (a no-op when the host already did) and adds + a **failure mapper** (`ZodResultsFailureMapper`) to the fallback stage. +- Because it is a failure mapper, **a mapping the host registered for a specific error case always wins**, a + mapping registered for the error type wins too, and a host failure mapper registered *before* + `AddResultsZodSharpHttp` wins as well. That is the escape hatch: when a case deserves its own response, register + it — and when a validation **code**, **category** or **origin** deserves one, use the rules below. +- Pair it with `AddZodSharpProblemDetails()` so a thrown `ZodException` and a result-carried rejection are + rendered by the same mapper and therefore produce identical responses. + +## Rules per validation error code, category and origin + +Pass a callback to answer particular codes, categories or origins with a response of their own: + +```csharp +builder.Services.AddResultsZodSharpHttp(options => options + .MapCode("tenant_not_found", StatusCodes.Status404NotFound) // validation problem, 404 default + .MapCode("tenant_id_matches_name", (errors, context) => TypedResults.Conflict()) + .MapCategory("invalid_value", StatusCodes.Status422UnprocessableEntity) + .MapOrigin("value_object", StatusCodes.Status422UnprocessableEntity) // every type-level rule failure +); +``` + +The three axes are the identity a `ValidationError` carries: **code** (the specific rule), **category** (a broad +grouping many codes share) and **origin** (the structured origin a rule owns — `"value_object"` for a type-level +rule, `"array"` for a collection rule). Reach for `MapOrigin` when the answer is keyed by the *kind* of rule +rather than one code. + +Matching and precedence: + +1. every matching **code** rule in registration order, +2. then every matching **category** rule in registration order, +3. then every matching **origin** rule in registration order, +4. then the default validation problem — so rules only ever narrow what the host already gets. + +- A rule matches when **any** of the failure's errors carries its code/category/origin, so a registered rule is + always reachable; a factory that wants stricter semantics returns `null` to decline and matching continues. +- A factory receives the failure's **whole error set**, so a rule never hides the other problems the caller has + to fix; the `int statusCode` overloads still render every error. +- A code, category or origin registered twice with different behaviour throws at configuration time. + +## Rendering by hand + +| Member | Purpose | +| --- | --- | +| `IValidationErrorCarrier.ToValidationProblem(context, statusCode = 400)` | Renders the errors the error value carries | +| `ImmutableArray.ToValidationProblem(context, statusCode = 400)` | Renders a set of errors | +| `ZodValidationProblems.ToProblem(errors, options, defaultStatusCode = 400, traceId = null)` | The underlying mapper, for hosts that resolve the options themselves | + +```csharp +if (result.Error is IValidationErrorCarrier carrier) + return carrier.ToValidationProblem(context); +``` + +The response is written as `application/problem+json` through `TypedResults.Json`, so it does not depend on the +MVC problem-details writer. + +## Status code and trace identifier + +- The status code resolved by `ZodProblemDetailsOptions.StatusCodeSelector` wins. +- `statusCode` (or `defaultStatusCode`) is only used when the resolved error type does not define one — the + default is `400 Bad Request`. +- The request trace identifier is included when `ResultsHttpOptions.IncludeTraceId` is `true` (the default). + +## Pitfalls + +- **Do not reimplement error-to-problem mapping.** Reuse `ZodValidationProblems.ToProblem` so a carried failure + and a thrown `ZodException` cannot drift apart in status code, title, `errors` shape or `issues` extension. +- **Do not map the whole union to a validation problem** unless every case is a validation failure; map the + carrying case (or rely on the mapper, which already does exactly that). +- If a case does deserve its own response, still build it from `ToValidationProblem(context)` when the payload + is validation data, so clients see one shape. +- The mapper receives the *case* value, so the carrier is the union case that implements the interface — not + the union itself (`ResultsFailureContext.Error` carries the union when a rule needs it). + +## Verifying the pairing + +A test that exercises both paths is the cheapest guard against drift: + +1. return a failure carrying validation errors through an endpoint, and +2. throw the same errors as a `ZodException` through the host's exception handler, + +then assert the two response bodies are equal. See the `purview-results-http-mapping` skill for the surrounding +registration and status-code guidance. diff --git a/.agents/skills/purview-results-zodsharp-validation/SKILL.md b/.agents/skills/purview-results-zodsharp-validation/SKILL.md new file mode 100644 index 00000000..83bc66c6 --- /dev/null +++ b/.agents/skills/purview-results-zodsharp-validation/SKILL.md @@ -0,0 +1,121 @@ +--- +name: purview-results-zodsharp-validation +description: "Use when ZodSharp validation has to feed Purview.Results — converting ValidationResult with ToResult or the value-discarding ToUnitResult, carrying ValidationError values on a union case, implementing IValidationErrorCarrier, or deciding what a rejected input becomes in the result pipeline." +--- + +# Folding ZodSharp validation into results + +Use this skill when a codebase validates with the `Purview.ZodSharp` package and returns +`Purview.Results` values, and a rejected input has to become an ordinary failure rather than an exception. + +## The conversion + +```csharp +using Purview.Results; +using Purview.Results.ZodSharp; + +return RepositoryReconciliationResultSchema + .Validate(reconciliationResult) + .ToResult(errors => + new ReconciliationResultInvalid(reconciliationResult, errors) // a union case + ); +``` + +`ToResult(onFailure)`: + +- returns a **success carrying the validated value** when validation passed; +- returns a **failure carrying the created error** when it failed; +- invokes `onFailure` only for a failure, so a successful validation allocates no error; +- takes the error type explicitly, and it must be named when it is a union, because a union case does not carry + the union type that contains it. + +ZodSharp validation never throws: `Validate` returns the value on success and every `ValidationError` on +failure. Keep it that way — map the outcome, do not re-throw it. + +## When the validated value is not the method's success type + +`ToResult` can only produce a result whose success type is the validated type. When the surrounding method +succeeds with something else (a repository result, an aggregate, a summary), produce the failure with the +generated helper instead: + +```csharp +var validated = ProviderConnectionIdSchema.Validate(providerConnectionId); + +if (!validated.IsSuccess) + return new ProviderConnectionInvalid(providerConnectionId, validated.Errors) + .AsFailure(); + +return await ReconcileCoreAsync(validated.Value, repositories, cancellationToken); +``` + +This keeps the failure case carrying the errors while the success type stays whatever the method actually +produces. + +## When the method has no success value + +When the method reports only why an input was rejected, `ToUnitResult` discards the validated value and returns a +value-less `Result`. It still names the validated value type, because a union case does not carry its +union: + +```csharp +Result Validate(TenantInput input) => + TenantInputSchema + .Validate(input) + .ToUnitResult(errors => new TenantInputInvalid(input, errors)); +``` + +Use `ToResult` when the success carries the validated value, `ToUnitResult` when it carries nothing, and the +generated `AsFailure()` when the success carries something else. + +## Async validation + +`ValidateAsync` returns a `ValueTask>`, and the async counterparts fold it in the same way: + +```csharp +async Task> Validate(TenantInput input, CancellationToken cancellationToken) => + await TenantInputSchemaValidator + .ValidateAsync(input, cancellationToken) + .ToUnitResultAsync(errors => new TenantInputInvalid(input, errors)); +``` + +- `ToResultAsync` carries the validated value on success; `ToUnitResultAsync` discards it. +- The error type is named explicitly for the same reason as the synchronous forms. +- Do not block on `ValidateAsync` to reuse the synchronous methods — that reintroduces the sync-over-async the + bridge exists to avoid. + +## Carrying the errors + +```csharp +public readonly record struct ProviderConnectionInvalid( + ProviderConnectionId ProviderConnectionId, + ImmutableArray ValidationErrors +) : IValidationErrorCarrier; +``` + +Implement `IValidationErrorCarrier` on the case (or error) that carries ZodSharp `ValidationError` values. +`ValidationErrors` preserves each error's code, origin, category, path and parameters, so an HTTP layer can render +a validation problem **without knowing the error type** — which is exactly how +`Purview.Results.ZodSharp.AspNetCore` maps it (see the `purview-results-zodsharp-problems` skill). + +Guidance: + +- **Keep the errors on the case**, never flatten them into a message string; the structured form is what clients + and problem responses need. +- **One carrier per rejection**, holding the whole `ImmutableArray` for that input. +- Implementing the interface (rather than a helper that extracts errors) lets the HTTP mapping stay generic. + +## Why there is no factory that returns a result + +`ToResult` takes `Func, TError>` on purpose. A lambda that returns +`Result` would bind to that parameter — C# prefers `Func<…, TError>` — and silently nest the +results. Naming the error type explicitly keeps the intent unambiguous. + +## Checklist + +1. Validation outcomes are mapped, never thrown. +2. The error type is named explicitly (`ToResult(…)` or `ToUnitResult(…)`, and + the async counterparts for a `ValidateAsync` outcome). +3. The case that carries the errors implements `IValidationErrorCarrier`. +4. A method whose success type differs uses `AsFailure()`, or `AsFailure()` for a unit result, with the + validation errors. +5. The host maps the carrier to a validation problem once (see `purview-results-zodsharp-problems`). diff --git a/.agents/skills/purview-sourcegenerator-codewriter/SKILL.md b/.agents/skills/purview-sourcegenerator-codewriter/SKILL.md new file mode 100644 index 00000000..ee363c97 --- /dev/null +++ b/.agents/skills/purview-sourcegenerator-codewriter/SKILL.md @@ -0,0 +1,334 @@ +--- +name: purview-sourcegenerator-codewriter +description: >- + Use when implementing, reviewing or refactoring C# source generators and analysers built on + Purview.SourceGeneratorFramework. Covers CodeWriter and XmlCommentWriter emission, scope safety, + incremental pipeline design, value equality, deterministic output, and migrating a legacy + string/StringBuilder emitter to CodeWriter. +metadata: + product: Purview.SourceGeneratorFramework + repository: purview-dev/sourcegenerator-framework +--- + +# Source generator CodeWriter modernization + +Use this skill for any work involving C# source generators, analysers, or generated output in `Purview.SourceGeneratorFramework`. It combines CodeWriter/XmlCommentWriter emission guidance with the incremental-source-generator and analyser best practices that ship with the framework. + +Refactoring an existing emitter off `string`/`StringBuilder`? The step-by-step playbook is in +[references/legacy-emitter-migration.md](references/legacy-emitter-migration.md). + +## Required implementation pattern + +When creating source output, favor this shape: + +1. Build immutable, value-equatable pipeline values first. +2. Register source output. +3. Inside the callback: `var writer = generationContext.CreateCodeWriter();` +4. Write header/usings/namespace. +5. Write structured types and members using declaration options records. +6. Add source once per output artifact. + +### CodeWriter lifetime: created in the output callback, never in pipeline state + +The line between "fine" and "forbidden" is the **incremental-cache boundary**, not the act of +creating a writer or handing it to a helper. + +**Fine — output-scoped use inside a `RegisterSourceOutput` callback.** Create the writer inside the +callback and pass it to any emitter/helper methods called from that same callback. It may be held in +local variables, passed as a parameter, or wrapped in a short-lived output context: + +```csharp +context.RegisterSourceOutput( + targets.CombineWithContext(contextProvider), + static (spc, pair) => + { + var (model, generationContext) = pair; + var writer = generationContext.CreateCodeWriter(); + EmitHeader(writer, model); + EmitType(writer, model); + spc.AddSource($"{model.Name}.g.cs", writer.ToString()); + } +); +``` + +**Forbidden — persisting the writer across the incremental-cache boundary.** Do not create it earlier +in the pipeline and pass it down, and do not store it anywhere Roslyn caches or another callback can +observe it: + +- Do not create a `CodeWriter` in a provider stage and carry it through the pipeline. +- Do not store a `CodeWriter` as a property or field on `GenerationContext` or a custom context. +- Do not return a `CodeWriter` (or an object holding one) from an incremental provider. +- Do not cache or reuse a writer for a later callback or a different output. + +A cached writer can retain previously written source, mix output from concurrently running +callbacks, and defeat scope tracking. A writer created in the callback and used only within that +callback is safe and expected. + +## Source generator & analyser best practices + +Apply the following rules to every generator, analyser, and refactor. + +### 1. Core principles + +- **Analyser for validation; generator for generation.** +- **Syntax for syntax, symbols for declarations, operations for executable semantics.** +- **Use `ForAttributeWithMetadataName` for attribute-driven generators.** +- **Remove Roslyn objects from the incremental pipeline as early as possible.** +- **Every value crossing a pipeline boundary must have meaningful value equality.** +- **Prefer many small incremental stages over one large transform.** +- **Keep broad inputs such as `Compilation` away from downstream generation.** +- **Generate deterministic output.** +- **Compile against the oldest Roslyn API version containing the functionality you need.** +- **Test caching, not just generated text.** + +The guiding principle for an incremental generator is: + +> Extract semantic information once, convert it into a small value model, and make everything downstream operate only on that value model. + +### 2. Analyser vs source generator + +Use a `DiagnosticAnalyser` when the question is: + +> Is the source code valid according to this library's rules? + +Use an `IIncrementalGenerator` when the question is: + +> Given valid source code, what source should be generated? + +| Requirement | Prefer | +| --- | --- | +| Require a class to be `partial` | Analyser | +| Require an attribute on a declaration | Analyser | +| Validate a method signature | Analyser | +| Reject unsupported property types | Analyser | +| Detect invalid attribute arguments | Analyser | +| Detect unsupported API usage | Analyser | +| Offer an automatic fix | Analyser + `CodeFixProvider` | +| Generate members for a marked class | Incremental generator | +| Generate serializers/validators/mappers | Incremental generator | +| Generate a registry from discovered types | Incremental generator | +| Read a schema file and generate C# | Incremental generator | +| Internal generation failure | Generator diagnostic | + +### 3. Choosing an analyser action + +Use the narrowest API that represents the concept being analysed: + +- `RegisterSyntaxNodeAction` — exact source syntax (e.g., modifier presence). +- `RegisterSymbolAction` — declaration semantics (e.g., attributes, interfaces, accessibility). +- `RegisterOperationAction` — executable behaviour (e.g., invocation, assignment, object creation). +- `RegisterOperationBlockStart/EndAction` — stateful method analysis. +- `RegisterSymbolStart/EndAction` — type-wide analysis across members. +- `RegisterCompilationStartAction` — resolve known framework symbols once. +- `RegisterAdditionalFileAction` — analyse `AdditionalFiles`. +- Avoid `RegisterSyntaxTreeAction`, `RegisterSemanticModelAction`, and compilation-end actions unless genuinely necessary. + +### 4. Syntax vs symbol vs operation + +Decision tree: + +1. Does exact source spelling/structure matter? → **Syntax** +2. Otherwise, is it a declaration? → **Symbol** +3. Otherwise, is it executable behaviour? → **Operation** + +Use `SymbolEqualityComparer.Default.Equals(...)` when comparing symbols. + +### 5. Analyser best practices + +- Enable concurrent execution with `context.EnableConcurrentExecution()`. +- Explicitly configure generated-code analysis with `context.ConfigureGeneratedCodeAnalysis(...)`. +- Resolve known framework/library symbols once in a `RegisterCompilationStartAction`. +- Prefer narrow registrations over scanning entire syntax trees or compilations. +- Treat diagnostic IDs as public contracts and maintain release tracking files when publishing public diagnostics. + +### 6. Incremental generator golden rules + +Implement `IIncrementalGenerator`. Simply implementing it is not enough; the pipeline must be incremental. + +> **Pipeline values must be immutable and value-equatable.** + +Never keep these in persistent pipeline models: + +| Type | Verdict | +| --- | --- | +| `ISymbol` / `INamedTypeSymbol` / `IMethodSymbol` / `IPropertySymbol` | Never retain | +| `Compilation` | Do not propagate | +| `SemanticModel` | Do not propagate | +| `IOperation` | Do not propagate | +| `SyntaxTree` | Do not propagate | +| `SyntaxNode` | Remove ASAP | +| `Location` | Remove ASAP | +| `AdditionalText` | Project immediately | +| `T[]` / `List` | Avoid | +| `ImmutableArray` | Wrap with sequence equality | + +Use immutable records and `EquatableArray` (sequence equality) for collection members. + +### 7. Designing the pipeline + +Pipeline shape: + +```text +Roslyn Input + ↓ +Cheap discovery + ↓ +Semantic extraction + ↓ +Small equatable model + ↓ +Validation/transformation + ↓ +Generation model + ↓ +Source output +``` + +Guidelines: + +- Project the semantic transform as the boundary where Roslyn objects disappear. +- Prefer `static` callbacks to avoid capturing generator state. +- Honour cancellation tokens. +- Split transformations into many small stages. +- Keep syntax predicates cheap. +- Avoid indirect discovery (every interface implementation, every subclass, entire-compilation scans). + +### 8. Syntax discovery + +- Prefer `context.SyntaxProvider.ForAttributeWithMetadataName(...)` for attribute-driven generators. +- Use `context.SyntaxProvider.CreateSyntaxProvider(...)` only when syntax itself is the trigger and there is no marker attribute. +- The predicate must be cheap; do not walk the tree or do semantic work in it. + +### 9. `Collect`, `Combine`, and invalidation + +- `Collect()` turns per-item outputs into one aggregate. Changing any item invalidates the aggregate. +- Use `Collect()` only for genuinely global output: registries, lookups, duplicate detection, aggregate switches. +- Prefer per-item `RegisterSourceOutput`. +- `Combine()` is correct when the output depends on two providers. +- Avoid `models.Combine(context.CompilationProvider)` — project the compilation to a tiny capability fact first. +- Use `.WithComparer(...)` only when logical equality differs from the default. + +### 10. Diagnostics + +- Prefer a separate `DiagnosticAnalyser` for normal user validation. +- Use generator diagnostics only for malformed additional files, generator-only configuration, conflicting output, or failures that cannot be expressed by an analyser. +- Report diagnostics on the most useful user-authored `Location`. +- Do not keep `Location` in long-lived pipeline models. + +### 11. Output generation + +- Output must be deterministic: no timestamps, random GUIDs, process IDs, machine paths, culture-dependent output, or unordered dictionary output. +- Hint names must be deterministic, unique, and stable. +- Prefer text generation or `CodeWriter` over building Roslyn syntax trees just to stringify them. +- Use `RegisterPostInitializationOutput` for constant source such as marker attributes. +- Add generated source once per output artifact. + +### 12. Testing incrementally + +- Snapshot-testing generated source is not enough. +- Test first execution, cached second execution, unrelated changes remaining cached, per-target invalidation, deletion, renaming, global options, additional files, and global registry invalidation. +- Use `GeneratorDriverOptions` with `trackIncrementalGeneratorSteps: true` and inspect reasons: `New`, `Modified`, `Unchanged`, `Cached`, `Removed`. + +### 13. Roslyn version compatibility and packaging + +- The `Microsoft.CodeAnalysis.*` version used to compile the analyser/generator sets the minimum compiler-host requirement. +- The consumer's `TargetFramework` does not determine analyser compatibility. +- Choose the oldest Roslyn version that contains the APIs you need. +- Common baselines: Roslyn 4.8 for VS 17.8 / .NET 8, 4.12 for VS 17.12 / .NET 9, 5.0 for VS 2026 18.0 / .NET 10. +- Ship one `netstandard2.0` analyser/generator binary unless you have a deliberate multi-version strategy. +- Do not mistake multi-targeting for automatic analyser asset selection. +- Use `PrivateAssets="all"` for Roslyn development dependencies. +- Enable `EnforceExtendedAnalyzerRules` and investigate `RSxxxx` diagnostics before suppressing them. + +### 14. Recommended project configuration + +A generator project should normally include: + +```xml + + netstandard2.0 + latest + enable + true + false + true + true + + + + + + + + + + +``` + +## Preferred API map for CodeWriter + +### File and namespace + +- `AutoGeneratedHeader(...)` +- `Using(...)` +- `FileScopedNamespace(...)` or `BlockNamespace(...)` +- `OpenPragmasScope(...)` for warning suppression scopes + +### Types and members + +- Types: `Class`, `Struct`, `RecordClass`, `RecordStruct`, `Interface`, `Enum`, `Delegate` +- Members: `Method`, `MethodScope`, `Property`, `Field`, `Constructor` +- Attributes: `AttributeDeclarationOptions`, `AttributeArgumentOptions` +- Type syntax: `TypeReference` (nullable/generic/array/pointer-safe composition) + +### XML documentation + +Use `XmlCommentWriter` extension methods on `CodeWriter`: + +- `XmlSummary(...)`, `XmlParam(...)`, `XmlTypeParam(...)`, `XmlReturn(...)`, `XmlRemarks(...)`, `XmlExample(...)` +- `XmlCode(...)` / `XmlCodeBlock(...)` +- `XmlList(...)`, `XmlSeeAlso(...)`, `XmlException(...)` + +Static helpers: `CodeWriter.XmlInlineCode(...)`, `CodeWriter.XmlSee(...)`, `CodeWriter.XmlParamRef(...)`, `CodeWriter.XmlText(...)`. + +## Refactoring guide: string/StringBuilder -> CodeWriter + +Apply this checklist in order: + +1. **Move emission boundaries** — replace giant string assembly with phases: header, namespace, type, members. +2. **Replace manual braces/indentation** — use `using` scopes (`ClassScope`, `MethodScope`, `OpenBlockScope`, `IndentedScope`). +3. **Replace handwritten signatures** — use declaration option records. +4. **Replace raw XML lines** — use XML extension methods (`XmlSummary`, `XmlParam`, etc.). +5. **Normalize type strings** — use `TypeReference`. +6. **Preserve semantics and ordering** — generated members and diagnostics must remain equivalent. +7. **Validate scope safety** — keep or enable `PurviewSourceGeneratorFrameworkValidateCodeWriterScopes` for tests/dev. + +## Anti-patterns to remove during refactors + +- `StringBuilder.AppendLine("public class ...")` for declarations that can be structured. +- Manually writing `{` / `}` around methods and types where scope APIs exist. +- Hard-coded nullable type suffixes and generic syntax in arbitrary strings when `TypeReference` is available. +- Raw XML tag string composition when XML extension methods can enforce consistency. +- Creating a `CodeWriter` before the output callback and passing it through the pipeline. +- Storing a `CodeWriter` on `GenerationContext`, a custom context, or any incremental pipeline model. +- Sharing one `CodeWriter` across multiple generated outputs or callbacks. +- Keeping Roslyn objects, `CodeWriter`, or mutable state in incremental pipeline models. + +## Review checklist for pull requests + +- Generated declarations use structured APIs for types and members. +- XML docs use XML extension methods rather than raw `///` fragments. +- `CodeWriter` is created inside each output callback and never persists in pipeline state; passing it + to helper methods within that callback is expected. +- Header and generated attributes are deterministic and consistent. +- Existing diagnostics, generated member names, and public behavior are preserved. +- Roslyn objects are removed from pipeline models; `EquatableArray` is used for collections. +- Per-target output is preferred over collected global output unless global knowledge is required. +- `CompilationProvider` is not casually combined into output. +- Deterministic hint names and source text are used. +- Incremental caching behavior is tested, not just generated text. + +## See also + +- `agents/source-generator-framework-writer.agent.md` — specialist agent for `Purview.SourceGeneratorFramework` emitter authoring. +- `prompts/refactor-source-generator-to-codewriter.prompt.md` — prompt template for legacy-emitter refactor tasks. diff --git a/.agents/skills/purview-sourcegenerator-codewriter/references/legacy-emitter-migration.md b/.agents/skills/purview-sourcegenerator-codewriter/references/legacy-emitter-migration.md new file mode 100644 index 00000000..54efd09f --- /dev/null +++ b/.agents/skills/purview-sourcegenerator-codewriter/references/legacy-emitter-migration.md @@ -0,0 +1,58 @@ +# Migrating a legacy emitter to CodeWriter + +A playbook for moving a source generator's emission from manual `string` / `StringBuilder` +construction to `CodeWriter` plus the `XmlCommentWriter` documentation extensions, with behaviour +parity. + +## Before you start, collect + +- The emitter file(s) being changed. +- The generator type name, and the version string it stamps into generated attributes or headers. +- Whether the output must stay **byte-identical**. If it must, every whitespace decision below is a + constraint rather than a preference, and the diff of the generated snapshots is the acceptance + test. + +## Requirements + +1. Use the structured declaration APIs rather than hand-written declaration text: + `Class` / `Struct` / `RecordClass` / `Interface` / `Enum`, and `Method`, `Property`, `Field`, + `Constructor`. +2. Use the XML helper extensions instead of composing `///` lines: `XmlSummary`, `XmlParam`, + `XmlReturn`, `XmlRemarks`, `XmlCode` / `XmlCodeBlock`. +3. Use `TypeReference` once the type text gets complex — nullability, generics, arrays. +4. Keep the writer **output-scoped**: `generationContext.CreateCodeWriter()` *inside* the output + callback. Never create it earlier in the pipeline, and never store it in incremental provider + state or in a custom context. +5. Preserve behaviour, diagnostics and generated names. +6. Keep the change minimal. Do not reformat logic the migration does not touch. + +## Strategy + +Work phase by phase, because each phase has a different mechanical replacement: + +| Emitter phase | Replace with | +| --- | --- | +| header | the header helper, not a literal banner string | +| namespace | the namespace scope API | +| type declarations | declaration option records, not signature strings | +| member declarations | `Method` / `Property` / `Field` / `Constructor` | +| indentation and braces | scoped APIs — never manual `{`/`}` and `\t` | +| `///` comment composition | `XmlSummary`, `XmlParam`, `XmlReturn`, `XmlRemarks`, `XmlCode` | + +Call out any intentional semantic delta explicitly; a migration that quietly changes emitted names or +diagnostics is the failure mode this playbook exists to avoid. + +## Verification + +- Run the impacted tests. +- Confirm the generated files still compile. +- Confirm there are **no scope leaks**: `OpenScopeCount == 0` when the writer is materialized. Enable + CodeWriter scope validation in the test run. +- Where byte-identical output was required, diff the generated snapshots. + +## Report + +1. Files changed. +2. Why each change was necessary. +3. Risks and behaviour differences, if any. +4. The verification that actually ran. diff --git a/.agents/skills/purview-sourcegenerator-diagnostics/SKILL.md b/.agents/skills/purview-sourcegenerator-diagnostics/SKILL.md new file mode 100644 index 00000000..21d9522c --- /dev/null +++ b/.agents/skills/purview-sourcegenerator-diagnostics/SKILL.md @@ -0,0 +1,142 @@ +--- +name: purview-sourcegenerator-diagnostics +description: >- + Use when a Purview.SourceGeneratorFramework build reports a PSGFR, PSGF, PRSGD or TLB diagnostic, + when choosing which code fix applies, or when a source generator, diagnostic analyzer or code fix + provider is silently not running at all. +metadata: + product: Purview.SourceGeneratorFramework + repository: purview-dev/sourcegenerator-framework +--- + +# Purview.SourceGeneratorFramework diagnostics + +`Purview.SourceGeneratorFramework` ships `Purview.SourceGeneratorFramework.Analyzers` and +`Purview.SourceGeneratorFramework.CodeFixers` as analyzer assets inside the package, under +`analyzers/dotnet/cs/`. They are enabled automatically in any project that references the framework — +there is no separate package to add. + +Two compiler-analyzer families, plus a set of MSBuild-time diagnostics: + +- **Incremental generator best practice** — `PSGFR11`–`PSGFR33`: pipeline design, `CodeWriter` usage, + Roslyn component discovery, extension-class conventions. +- **C# 14 extension-member conventions** — `PSGFR34`–`PSGFR38`, with + `ReorganizeExtensionClassCodeFixProvider` and `ConvertToExtensionBlockCodeFixProvider`. +- **Merge and packaging** — `PSGFR39`–`PSGFR43`, where `PSGFR43` is the merge tool's blocked + public-surface code. + +## Start here when nothing runs + +A compiler host loads a generator, analyzer or code fix provider only when **three** conditions hold. +Missing any one means the component is **silently ignored** — no error, no output, a green build: + +1. **The type is public** (`PSGFR27`). +2. **The type is decorated** — `[Generator]` (`PSGFR26`), `[DiagnosticAnalyzer]` (`PSGFR25`), or + `[ExportCodeFixProvider]` (`PSGFR24`). +3. **The assembly is loaded as an analyzer** — packed under `analyzers/dotnet/cs/` in a package, or + referenced with `OutputItemType="Analyzer"` on a `ProjectReference`. + +A code fix provider additionally appears only when a diagnostic ID in its `FixableDiagnosticIds` is +actually produced by an analyzer loaded alongside it (`PSGFR28`). Visual Studio MEF-composes fix +providers when the analyzer set loads, so after adding or updating a fixer assembly you must restart +Visual Studio or reload the project before the fixes show up. + +## Build-time validation diagnostics + +These are MSBuild diagnostics, not compiler analyzers, so they are **not** tracked in +`AnalyzerReleases.*.md`: + +| Code | Raised by | Summary | +| --- | --- | --- | +| `PSGF0001` | `Purview.BuildSdk` | A Roslyn component did not produce (or declare) a source-generator analyzer file. | +| `PSGF0003` | `Purview.SourceGeneratorFramework` | A `PurviewGeneratorVisibleProperty` is not compiler-visible in the declaring project or its `Sdk/build`/`Sdk/buildTransitive` assets, so consumers cannot read `build_property.`. | +| `PRSGD0005` | `Purview.BuildSdk` | A file in the returned analyzer closure references an assembly that is neither in the closure nor a compiler-host assembly. | +| `PSGFR41` | merge tool | A component's public surface exposes framework types the merge internalizes. Reported by the analyzer at design time, and by the merge pass as `message` (default), `warning` or `error`. | +| `PSGFR43` | merge tool | The merged analyzer still exposes a public framework type, so it is not self-contained. Always an error; the merge fails with exit code 5. | + +Opt out with `PurviewSourceGeneratorFrameworkAnalyzerValidation=false` (`PRSGD0005`) or +`PurviewSourceGeneratorFrameworkGeneratorPropertyValidation=false` (`PSGF0003`). + +## Incremental pipeline rules + +| Rule | Summary | +| --- | --- | +| `PSGFR11` | Prefer `SyntaxProvider.ForAttributeWithMetadataName` over `CreateSyntaxProvider` for attribute-based detection. | +| `PSGFR12` | Use `IIncrementalGenerator` / `RegisterSourceOutput` instead of `ISourceGenerator`. | +| `PSGFR14` | Avoid `RegisterImplementationSourceOutput` unless implementation-only output is required. | +| `PSGFR15` | Pipeline model collection members should use sequence equality (`EquatableArray`). | +| `PSGFR30` | Prefer `static` lambdas in pipeline methods, so the compiler never allocates a closure on the per-item hot path. | +| `PSGFR31` | Prefer `GeneratorAttributeSyntaxContext.TargetSymbol` over `SemanticModel.GetDeclaredSymbol(ctx.TargetNode)`. | +| `PSGFR33` | Pipeline models must not retain Roslyn objects (`ISymbol`, `SyntaxNode`, `Location`, …); extract the information into value types. | + +## CodeWriter rules + +| Rule | Summary | +| --- | --- | +| `PSGFR16` | Prefer the nullable-context `Nullable()`/`MakeNullable()` overload, so annotations honour the target compilation. | +| `PSGFR17` | Consume scope-returning methods (`…Scope`, `IndentedScope`) with `using`. | +| `PSGFR18` | Prefer structured declaration APIs (`Class`, `Method`, `Property`, `Field`) over raw declaration text. | +| `PSGFR19` | Prefer structured statement APIs (`Return`, `MethodCall`, `Throw`, `Assignment`, `Using`, `Comment`) over raw statement text. | +| `PSGFR20` | Prefer the minimal `CodeWriter` overloads over hand-constructing `*DeclarationOptions` values. | +| `PSGFR21` | Prefer `HashDefines`/`HashDefinesScope` for `#if`/`#endif`. | +| `PSGFR22` | Prefer `PragmaDisable`/`OpenPragmasScope` for `#pragma warning`. | +| `PSGFR23` | Prefer structured `IfBlock`/`ElseIf`/`Else` over raw `if` block text. | +| `PSGFR29` | Do not embed a `CodeWriter` in a string; use `XmlCommentWriter.XmlInlineCode`. | +| `PSGFR32` | Avoid `NormalizeWhitespace` when generating source; use an indented text writer such as `CodeWriter`. | + +## Component, extension and merge rules + +| Rule | Summary | +| --- | --- | +| `PSGFR24` | `CodeFixProvider` is not marked `[ExportCodeFixProvider]`; Visual Studio will never discover it. | +| `PSGFR25` | `DiagnosticAnalyzer` is not marked `[DiagnosticAnalyzer]`; it will never run. | +| `PSGFR26` | A generator type is not marked `[Generator]`; it will never run. | +| `PSGFR27` | A Roslyn component type is not public; the compiler host cannot instantiate it. | +| `PSGFR28` | `FixableDiagnosticIds` names a diagnostic no analyzer in the compilation produces; the fix will never be shown. | +| `PSGFR34` | Prefer C# 14 `extension(Receiver)` blocks over classic static `this`-parameter extension methods. | +| `PSGFR35` | Extension class name must match the extended type (`{Receiver}Extensions`). | +| `PSGFR36` | Extension classes belong in the extended type's namespace, under an `Extensions` folder. | +| `PSGFR37` | One extension class per receiver type; split a class that extends several. | +| `PSGFR38` | Extension classes should carry `[EditorBrowsable(EditorBrowsableState.Never)]`. | +| `PSGFR39` | A non-packable Roslyn component opted out of the default self-contained analyzer output (`PurviewMergeSourceGeneratorFrameworkForAnalyzerFiles=false`) while embedding the framework; otherwise the package embeds the loose framework DLL under `analyzers/`. | +| `PSGFR40` | In a Roslyn component (`IsRoslynComponent=true`), reference SGF types as inline code (`Type`) rather than a `cref`: copied documentation must not depend on cref resolution. | +| `PSGFR41` | A public member (or generic constraint) whose signature references an SGF type in a component whose framework implementation is merged. The merge internalizes every SGF type, so the signature ends up referring to an internal type. Make the member, or its declaring type, non-public. | +| `PSGFR42` | A disposable Testing-harness result (`DriverRunResult`) is produced and never disposed, leaking the collectible `AssemblyLoadContext` and `MetadataLoadContext` of a compiled run. `warning` when the run syntactically compiles to an assembly (a `Compile` options member, or `CompileToAssembly = true`), otherwise `info`. Awaiting an assertion, or calling a helper handed the result — an extension on it, or a method taking it as a parameter — is not a production: both hand the same instance back, so only a task-like await or a genuine producer is reported. | + +## Type-library and attribute-model diagnostics + +The bundled generators carry their own families: `TypeLibraryValidationAnalyzer` +(`TLB0001`–`TLB0019`, plus `TLB0021`) and the attribute-data-model validation analyzers. They are +documented on their own wiki pages, `Type-Library.md` and `Attribute-Data-Models.md`. + +## Code fixes + +Most rules above have a fix in `Purview.SourceGeneratorFramework.CodeFixers`: + +| Fix provider | Rule | +| --- | --- | +| `AddGeneratorAttributeCodeFixProvider` | `PSGFR26` | +| `AddDiagnosticAnalyzerAttributeCodeFixProvider` | `PSGFR25` | +| `AddExportCodeFixProviderAttributeCodeFixProvider` | `PSGFR24` | +| `MakeRoslynComponentPublicCodeFixProvider` | `PSGFR27` | +| `RemoveOrphanedFixableDiagnosticIdCodeFixProvider` | `PSGFR28` | +| `PreferTargetSymbolCodeFixProvider` | `PSGFR31` | +| `PreferStaticLambdaCodeFixProvider` | `PSGFR30` | +| `PreferNullableContextOverloadCodeFixProvider` (project-wide Fix All) | `PSGFR16` | +| `PipelineModelReferenceEqualityCollectionCodeFixProvider` | `PSGFR15` | +| `PreferStructuredCodeWriterIfBlockCodeFixProvider` | `PSGFR23` | +| `CodeWriterToStringCodeFixProvider` | `PSGFR29` | +| `PreferInlineCodeForFrameworkCrefCodeFixProvider` | `PSGFR40` | +| `MakeComponentSurfaceNonPublicCodeFixProvider` | `PSGFR41` | +| `DisposeTestResultCodeFixProvider` | `PSGFR42` | +| `ReorganizeExtensionClassCodeFixProvider` (renames, splits, moves, updates referencing files) | `PSGFR35`, `PSGFR36`, `PSGFR37` | +| `ConvertToExtensionBlockCodeFixProvider` | `PSGFR34` | +| `AddExtensionClassMetadataCodeFixProvider` | `PSGFR38` | +| `MakeTypeLibrarySpecNonPublicCodeFixProvider` | `TLB0021` | +| `AttributeDataModelSymbolPropertyCodeFixProvider` | attribute-data-model symbol properties | +| `TypeLibraryMemberAccessibilityCodeFixProvider`, `TypeLibraryMarkerDefaultInitializerCodeFixProvider`, `MakeTypeLibrarySpecPartialCodeFixProvider`, `RenameTypeLibrarySpecCodeFixProvider`, `TypeLibraryMemberTypeCodeFixProvider` | type-library rules | + +## Related skills + +`purview-sourcegenerator-codewriter` for the emission patterns the `CodeWriter` rules push you +towards, and `purview-sourcegenerator-testing` for proving a pipeline actually caches. diff --git a/.agents/skills/purview-sourcegenerator-packaging/SKILL.md b/.agents/skills/purview-sourcegenerator-packaging/SKILL.md new file mode 100644 index 00000000..92350db8 --- /dev/null +++ b/.agents/skills/purview-sourcegenerator-packaging/SKILL.md @@ -0,0 +1,245 @@ +--- +name: purview-sourcegenerator-packaging +description: >- + Use when packaging or referencing a source generator built on Purview.SourceGeneratorFramework - + the self-contained merged analyzer, GetSourceGeneratorAnalyzerFiles, embedding a generator in + another package, PurviewGeneratorVisibleProperty, analyzer-closure validation, Roslyn version + compatibility, and errors such as CS0433, CS8784 or MSB3073 from a loaded analyzer. +metadata: + product: Purview.SourceGeneratorFramework + repository: purview-dev/sourcegenerator-framework +--- + +# Packaging a source generator + +The rule everything else follows from: **a shipped Roslyn component carries its own copy of the +framework and references no loose `Purview.SourceGeneratorFramework.dll`.** Two generators built +against different framework versions must be able to load into one compiler host. A shared DLL under +`analyzers/` cannot give you that — whichever version loads first wins, and the other fails with +`MissingMethodException` or `CS0433`. + +The framework delivers this by IL-merging and internalizing its implementation into each component's +**intermediate** output, leaving the component's `bin` unmerged. + +## Referencing the framework from a component + +```xml + + true + + + + + +``` + +And from a consuming project, as an analyzer: + +```xml + +``` + +`Purview.BuildSdk` invokes `GetSourceGeneratorAnalyzerFiles` automatically — naming +`Targets="GetSourceGeneratorAnalyzerFiles"` explicitly still works but is not required. + +## The three consumption paths + +| Path | Trigger | What you get | +| --- | --- | --- | +| `GetSourceGeneratorAnalyzerFiles` (default) | a consuming project references the component as an analyzer | the **merged** component, from the content-addressed `purview-merged//`. `bin` stays unmerged, so an in-process test harness keeps shared framework type identity and `InternalsVisibleTo` access without `CS0433`. | +| `GetSourceGeneratorAnalyzerFiles` with `PurviewMergeSourceGeneratorFrameworkForAnalyzerFiles=false` | opt-out | unmerged component **plus** the loose framework DLL from the package `lib/`. | +| `GetPurviewMergedAnalyzerFile` | the framework's own bundled-component pack, or a third-party package embedding the generator | the merged component; `bin` is never overwritten. | +| `GetPurviewMergedAnalyzerFileForPack` (pack-time, via `TargetsForTfmSpecificContentInPackage`) | packing a standalone packable generator | the merged DLL and PDB contributed straight to `analyzers/dotnet/cs`. `bin` is never mutated, so its shape does not depend on whether `build` or `pack` ran last. | + +Two properties exist and both should normally be left alone: + +- `PurviewEmbedSourceGeneratorFramework=false` — only for a project that *is* the framework + compile-time library. A published generator package must never disable embedding. +- `PurviewMergeSourceGeneratorFrameworkForAnalyzerFiles=false` — only when the analyzer-files + consumer must keep the unmerged + loose-DLL shape (a generator shipped into one compiler process + alongside an incompatible framework version). + +`PSGFR39` errors when a **non-packable** component opts out while embedding the framework, because +that shape, packed through the GASF path, forces the loose DLL back under `analyzers/`. + +## A component that references another component + +A code-fix or analyzer component can reference the generator component normally (`ProjectReference`, +`ReferenceOutputAssembly` **not** `false`) when it needs the generator's internal diagnostic +identity. Both are `IsRoslynComponent`; only the generator references the framework. + +- The referenced component is returned as **its own merged assembly** and is never IL-merged into the + dependent one — that would duplicate its types, including `InternalsVisibleTo`-visible internals, + inside a second analyzer in the same host. +- The framework assembly is declared as copy-to-output content beside the generator's `bin`, and + content with `CopyToOutputDirectory` flows transitively through `ProjectReference`. That is what + lets Visual Studio load the dependent code-fix provider from its own `bin` without a + `FileNotFoundException` for the framework assembly. +- Visual Studio's project system resolves an `OutputItemType=Analyzer` project reference to the + referenced project's **unmerged** `bin` assembly and adds it to the compiler's analyzers — the + command-line build does not. `Purview.BuildSdk` removes that item before adding the resolved + closure, so Roslyn only ever receives the merged artifact. Without that removal the unmerged copy + drags `Purview.SourceGeneratorFramework` into the compiler host + (`CS8784 FileNotFoundException: Could not load file or assembly 'Purview.SourceGeneratorFramework'`) + and every generator registers twice. + +## Analyzer-closure validation + +`Purview.BuildSdk` validates the whole closure `GetSourceGeneratorAnalyzerFiles` returns: every +file's PE `AssemblyRef` must resolve to another file in the returned set, or to a compiler-host +assembly (`Microsoft.CodeAnalysis*`, `System.Composition.*`, `System.*`, `netstandard`, …). A missing +component artifact fails the build with `PRSGD0005`. + +Extend the permitted set with `` or the +`PurviewAnalyzerClosurePermittedReferences` property. Opt out with +`PurviewSourceGeneratorFrameworkAnalyzerValidation=false`. + +## Generator-read MSBuild properties + +A generator reading `build_property.` is only correct if `` is a +`CompilerVisibleProperty` **wherever the generator runs** — including in a consumer's project. +Declare what the component reads: + +```xml + + + +``` + +`PSGF0003` fails the build when a declared property is neither a `CompilerVisibleProperty` in the +project nor declared by the project's own `Sdk/build` or `Sdk/buildTransitive` assets — which is what +consumers actually receive. Opt out with +`PurviewSourceGeneratorFrameworkGeneratorPropertyValidation=false`. + +NuGet imports `buildTransitive` assets for **PackageReference** consumers only. Inside the package +repository every project uses `ProjectReference`, so `Purview.BuildSdk`'s +`ImportProjectReferencedBuildTransitiveAssets` registers the referenced project's +`Sdk/buildTransitive/*.props|*.targets` `CompilerVisibleProperty` items for in-repo consumers. Opt +out with `PurviewImportProjectReferenceBuildTransitive=false`. + +## Embedding a generator in another package + +Pack the **merged** assembly, so the outer package ships no loose framework DLL: + +```xml + + false + $(TargetsForTfmSpecificContentInPackage);PackMyGenerator + + + + + + + + + analyzers/dotnet/cs/ + + + +``` + +If the generator is also embedded at compile time for the outer package's consumers, the outer +package must make the framework's compiler-visible properties visible to them — build assets from +`Purview.SourceGeneratorFramework` are **not** copied into the outer package. Ship a `.props` that +declares the property and its `CompilerVisibleProperty` entry, packed under the outer package's own +ID so NuGet imports it: + +```xml + +``` + +## `IsExternalInit` + +The framework assembly defines `System.Runtime.CompilerServices.IsExternalInit` **publicly**, so the +bundled generators can emit `init`-based attribute types into any consumer compilation and the merge +has a single marker definition to internalize. + +**Do not declare your own.** A generator-local marker gives calls to the framework's `init` setters a +different required-custom-modifier identity from the setter definitions. The merge tool normalizes +those modifiers in a temporary copy for compatibility with legacy tooling, but removing the redundant +marker is the preferred configuration. + +## Roslyn version compatibility + +> The version of `Microsoft.CodeAnalysis.*` you compile the component against sets a **minimum +> compiler-host API requirement**. The consumer's `` has nothing to do with it — +> analyzer code runs inside the compiler/IDE host. + +| Roslyn package | Minimum Visual Studio | Language / .NET generation | +| ---: | --- | --- | +| 4.8 | VS 2022 17.8 | C# 12 / .NET 8 | +| 4.12 | VS 2022 17.12 | C# 13 / .NET 9 | +| 5.0 | VS 2026 18.0 | C# 14 / .NET 10 | + +**This framework is built against Roslyn 5.0**, so a host loading it must be Roslyn 5.0 or later +(.NET 10 SDK / Visual Studio 2026 18.0). The testing packages multi-target `net8.0`–`net10.0`, and +Roslyn 5.x ships `net8.0`/`net9.0` assets, so those test targets still load the runner. + +## A generator project to start from + +```xml + + + netstandard2.0 + latest + enable + true + false + true + true + + + + + + + + + + + + +``` + +`Purview.BuildSdk` already defaults most of this for a project it classifies as a Roslyn component, +so in an SDK repository the project file is usually far shorter. The exact Roslyn baseline is a +product-support decision. + +## Release gates + +Acceptance criteria for self-contained packaging — check metadata, never "the sample compiled": + +1. **No framework reference, no public framework types.** Every `analyzers/dotnet/cs/*.dll` has no + assembly reference to `Purview.SourceGeneratorFramework` and exposes no public type in a + framework-owned namespace (including the generated `Generators` attribute set and the + framework-emitted `Microsoft.CodeAnalysis.EmbeddedAttribute`). The one exception is the + component's own Roslyn entry points, which must stay public — Roslyn only instantiates public + components (`PSGFR27`). +2. **No loose framework DLL in any package**, and no `*.pdb` in the `.nupkg` — symbols ship only + through the `.snupkg`. +3. **Merged entry points survive**: each merged DLL still exposes its `IIncrementalGenerator`, + `DiagnosticAnalyzer` or `CodeFixProvider`. +4. **Installed-package consumer test**: a generator project referencing the framework by + `PackageReference` packs one self-contained DLL under `analyzers/dotnet/cs`, and a consumer that + installs it builds with the generator producing output. +5. **Two-version coexistence test**: build Generator A against the current framework and Generator B + against an intentionally binary-incompatible version, install both into one consumer, and build + with both package-reference orders. Both must run against their own embedded copy. + +## Going deeper + +The merge pass, the content-addressed artifact, framework type internalization and the properties +that tune it are in [references/merge-internals.md](references/merge-internals.md) — read it when a +merge fails, when a type leaks, or when you hit `MSB3073` / `CS0433` / `CS8784` from a loaded +analyzer. diff --git a/.agents/skills/purview-sourcegenerator-packaging/references/merge-internals.md b/.agents/skills/purview-sourcegenerator-packaging/references/merge-internals.md new file mode 100644 index 00000000..5d8b6c9e --- /dev/null +++ b/.agents/skills/purview-sourcegenerator-packaging/references/merge-internals.md @@ -0,0 +1,139 @@ +# The merge pass and the self-contained analyzer + +## Where the merged artifact lives + +`_PurviewMergeSourceGeneratorFramework` only ever writes to the component's **intermediate** output. +`GetSourceGeneratorAnalyzerFiles` returns that result by substituting the merged path into +`TargetPathWithTargetPlatformMoniker` immediately before its body runs, leaving `GetTargetPath` — +which resolves assembly references — pointing at the unmerged `bin`. That split is what keeps the +in-repo test harness working while shipped assemblies stay self-contained. + +The artifact is **content-addressed**: + +```text +$(IntermediateOutputPath)purview-merged//$(TargetFileName) +``` + +`` is a SHA-256 over the component, the framework assembly and the merge tool (the tool +computes it in its `--tag` mode). The tag is in the **directory**, never the file name, because +ILRepack derives the merged assembly's simple name from the output file name and an analyzer must +keep `.dll`. + +Two properties follow, and both matter: + +- A rebuild with identical inputs reuses the existing file and **skips the merge**, so + `_PurviewMergeSourceGeneratorFramework` is idempotent across the per-consumer — and potentially + parallel — invocations of `GetSourceGeneratorAnalyzerFiles`. +- Changed inputs select a **new directory**, so the merge never overwrites an assembly a compiler + host (csc, `VBCSCompiler`, Visual Studio) already has loaded. Overwriting such a file fails on + Windows with a sharing violation, which surfaced as `MSB3073` (merge tool exit code + `-532462766`) and left consumers loading a stale or partially written analyzer — the root cause of + `CS8784 FileNotFoundException: Could not load file or assembly 'Purview.SourceGeneratorFramework'`. + +The tool merges into a per-process `.staging-` directory and publishes it with a +non-overwriting directory rename. A concurrent invocation that loses the race simply observes the +published artifact rather than failing. + +Packaging needs the stable `.dll` name, so the pack paths +(`GetPurviewMergedAnalyzerFile`, `GetPurviewMergedAnalyzerFileForPack`) copy the content-addressed +artifact into `$(IntermediateOutputPath)purview-pack/` and pack that plainly named staging copy. + +## Framework type internalization + +ILRepack's `Internalize` is best-effort, and two gaps matter: + +- a framework type that reaches the merged component's public API surface stays public; and +- the types the framework's own generators emit **into** the component — the + `Purview.SourceGeneratorFramework.Generators` attribute set, generated type libraries, marker + attributes — are not part of the merged framework assembly at all, so ILRepack never sees them. + +Either gap leaks framework types out of what must be a self-contained analyzer, and any project +loading that analyzer alongside the real framework assembly fails with `CS0433` ambiguity for every +leaked type. + +So the merge tool runs a deterministic internalization pass (`FrameworkTypeInternalizer`) after +ILRepack finishes: + +- Every type in a framework-owned namespace (`Purview.SourceGeneratorFramework` and its children, + including the generated `Generators` attribute set) becomes non-public. Ownership is evaluated + through the **declaring chain**, because Mono.Cecil reports an empty namespace for a nested type: + the framework's nested containers — generated type-library namespace classes, nested operator/enum + groups, `CodeWriter` scopes — are only reachable through their declaring type. +- Types the framework's generators emitted into the component, recognized by the tool name on their + `System.CodeDom.Compiler.GeneratedCodeAttribute` (`TypeLibraryGenerator`, + `AttributeDataModelGenerator`), become non-public too, so a generated type library can never leak a + `TypeIdentity`/`TypeReference` member as public API. +- `Microsoft.CodeAnalysis.EmbeddedAttribute`, the framework-emitted marker, becomes non-public. +- **Roslyn component entry points are never internalized.** A generator, analyzer, code fix provider + or refactoring provider reachable from the framework namespace stays public, because Roslyn only + instantiates public components (`PSGFR27`). This is what keeps the framework's own bundled + analyzers working after the pass. +- The pass reports the result. Leftover public framework types fail the merge with **exit code 5** + (`PSGFR43`). Public component members whose signature exposes a framework type are logged + (`PSGFR41`) so the author can make them, or their declaring type, non-public. Visibility is + followed through the declaring chain here too: a public nested type inside an internal type — for + example the compiler-synthesised `$`/`$` extension containers emitted for an extension class + — is not reachable from outside the component, so it is not part of the public surface and is not + reported. + +Ownership is seeded with the framework assembly's own type identities, so a framework type living +*outside* the framework namespace (`Microsoft.CodeAnalysis.*Extensions`, `System.StringExtensions`) +is internalized as well. The artifact's assembly-level `InternalsVisibleTo` / +`IgnoresAccessChecksTo` grants are removed, because a shipped analyzer is not the component's own +assembly. + +## Tuning the pass + +| Property | Default | Effect | +| --- | --- | --- | +| `PurviewMergeOwnedNamespaces` | empty | Extra namespace prefixes (semicolon-separated) treated as framework-owned. | +| `PurviewMergeOwnedTypeFullNames` | empty | Extra type full names (semicolon-separated) treated as framework-owned. | +| `PurviewMergePublicSurfaceSeverity` | `message` | How a finding is reported: `message` (plain log text), `warning`/`error` (MSBuild diagnostics with code `PSGFR41`), or `none`. | +| `PurviewMergePublicSurfaceValidation` | `true` | `false` sets the severity to `none`. | +| `PurviewMergePublicSurfaceOrigin` | the merged component assembly | The origin reported with an MSBuild finding; point it at a source or project path for IDE navigation. | + +All five participate in the content tag, so changing one re-runs the merge — and re-emits its +findings — rather than reusing a cached artifact. The compiler analyzer with the same id (`PSGFR41`) +reports the same condition while you edit, so the surface is usually fixed before the merge runs. + +## Generated accessibility: bin versus merged artifact + +The component's own generated types — the type library, the attribute data models — keep their +generated accessibility in the component's **bin output**. `TLB0015` requires a hand-written partial +to be `public static partial` so it can merge with the generated library, and in-repo consumers such +as code fixers and sibling assemblies compile against it. + +Only the **merged analyzer artifact** internalizes them. Self-containment is therefore enforced at +the merge boundary without rewriting the accessibility an in-repo consumer compiles against, and that +split is safe precisely because a merged artifact is never referenced as a compile-time dependency. + +> A merged component is an analyzer artifact. Never reference it as a compile-time dependency. Tests +> that need to run a *packaged* generator load it out of band. + +## How the framework package itself is assembled + +`Purview.SourceGeneratorFramework` is dual-role: the framework assembly ships in `lib/` so generator +projects compile against it, and `analyzers/` carries self-contained generator, analyzer and +code-fixer assemblies. The bundled projects are: + +- `SourceGeneratorFramework.Generators` — `AttributeDataModelGenerator`, `TypeLibraryGenerator`; +- `SourceGeneratorFramework.Analyzers` — the `PSGFR*` and `TLB*` analyzers; +- `SourceGeneratorFramework.CodeFixers` — the code fix providers. + +Each has the framework implementation merged and internalized into it. The package deliberately does +**not** put `Purview.SourceGeneratorFramework.dll` under `analyzers/dotnet/cs`, so generators built +against different framework versions never ask Roslyn to load competing versions of a same-named +dependency. + +The shared models and helpers that once shipped as a separate +`Purview.SourceGeneratorFramework.Shared.dll` are compiled directly into the framework assembly +(`SourceGeneratorShared.Link.targets` links the sources). Consumers get one +`Purview.SourceGeneratorFramework.dll`, which removes the version-skew hazard a separately bundled +Shared assembly caused — generator packages loading a different Shared version in-process failed with +binary-incompatibility errors, such as removed `PurviewTypeLibrary` fields. + +Those projects are `IsRoslynComponent = true` and are **not** packable on their own. The +`SourceGeneratorFramework` project builds them via `GetPurviewMergedAnalyzerFile` and packs them +under `analyzers/dotnet/cs/` in `BuildAndPackBundledAnalyzerAssemblies`. They were previously +consumed as analyzer project references, but they now reference the framework assembly for the shared +types, which would form a project-reference cycle. diff --git a/.agents/skills/purview-sourcegenerator-pipeline/SKILL.md b/.agents/skills/purview-sourcegenerator-pipeline/SKILL.md new file mode 100644 index 00000000..373942fd --- /dev/null +++ b/.agents/skills/purview-sourcegenerator-pipeline/SKILL.md @@ -0,0 +1,231 @@ +--- +name: purview-sourcegenerator-pipeline +description: >- + Use when composing an incremental pipeline with Purview.SourceGeneratorFramework - + IncrementalPipeline helpers, GenerationContext and custom contexts, CreateCodeWriter lifetime, + GeneratorResult and blocking versus non-blocking diagnostics, disabling a generator from MSBuild, + scope validation, test logging, and stage tracking names. +metadata: + product: Purview.SourceGeneratorFramework + repository: purview-dev/sourcegenerator-framework +--- + +# Incremental pipeline composition + +`IncrementalPipeline` composes `IncrementalValueProvider` and `IncrementalValuesProvider`: +attribute-based discovery, generation-context creation, disable-property checks, and thin +source-output registration. + +Everything here follows from one rule: **pipeline values must be immutable and value-equatable.** +Roslyn caches the complete value a provider publishes, and offers no way to exclude one property of +it from caching. + +## `GenerationContext` + +A base execution-services context carrying the Roslyn `Compilation`, immutable `GenerationSettings`, +an optional `ISourceGenLogger`, and a factory for independently owned `CodeWriter` instances. + +```csharp +var contextProvider = IncrementalPipeline.DefaultGenerationContextValueProvider(context); +``` + +### Custom contexts + +A custom context does not need to accept or read build properties itself: + +```csharp +public sealed class MyGenerationContext : GenerationContext +{ + public MyGenerationContext(Compilation compilation, GenerationSettings settings, ISourceGenLogger? logger) + : base(compilation, settings, logger) + { + } +} + +var contextProvider = IncrementalPipeline.GenerationContextValueProvider( + context, + nameof(MyGenerator), + "1.0.0", + factory: static (compilation, settings, logger, cancellationToken) => + { + cancellationToken.ThrowIfCancellationRequested(); + return new MyGenerationContext(compilation, settings, logger); + }, + disablePropertyName: "MyGenerator_Disable" +); +``` + +The provider resolves scope validation, generator disabling and test logging from analyzer-config +properties *before* invoking the factory. The logger is created internally only when logging is +enabled and a sink is registered for that run. + +## `CodeWriter` lifetime — the rule that bites + +Treat `GenerationContext` as **cached incremental state** and each `CodeWriter` as **mutable, +output-scoped execution state**. Create the writer inside the registered source-output callback, +after the incremental cache boundary: + +```csharp +IncrementalPipeline.RegisterSourceOutput( + context, + targets, + contextProvider, + static (spc, target, generationContext) => + { + var writer = generationContext.CreateCodeWriter(); + EmitTarget(generationContext, writer, target); + spc.AddSource($"{target.Name}.g.cs", writer.ToString()); + } +); +``` + +Creating it in the callback and passing it to emitter helpers called from that same callback is the +intended pattern. The only forbidden thing is **persisting the writer in pipeline state**. + +Why, concretely: + +- Roslyn caches the whole published value; you cannot exempt a field. +- `CodeWriter` is mutable, so a cached one retains previously written source when the context is + reused for another output or run. +- Source-output callbacks may process independent targets **concurrently**; a shared writer mixes + their output and races. +- A fresh writer gives each generated source independent scope tracking and deterministic ownership. + +`CreateCodeWriter()` returns a new, independently owned instance every call. + +**Never add a `CodeWriter` property or field to a class derived from `GenerationContext`.** A custom +context is still produced by an incremental provider and cached as one complete value. Store only +compilation-derived services and immutable configuration there. + +When an emitter needs both services and writing, pass the context and the writer separately, or +compose a short-lived wrapper created inside the callback — which must never be returned from a +provider: + +```csharp +public sealed class GenerationOutputContext : ISourceGenLogger + where TContext : GenerationContext +{ + public GenerationOutputContext(TContext generation) + { + Generation = generation; + Writer = generation.CreateCodeWriter(); + } + + public TContext Generation { get; } + + public CodeWriter Writer { get; } + + public void Log(SourceGenLogLevel level, int indentation, string message, params object[] args) => + Generation.Log(level, indentation, message, args); +} +``` + +## `GeneratorResult` and diagnostics that do not stop generation + +`RegisterSourceOutput` combines targets with the generation context, reports diagnostics, and runs +the callback only for successful results: + +```csharp +var targets = IncrementalPipeline.ForAttributeWithMetadataName( + context, + AttributeType, + static (ctx, ct) => + { + var symbol = ctx.TargetSymbol; + + return symbol is null + ? GeneratorResult.Empty + : GeneratorResult.Create(symbol.Name); + } +); +``` + +The callback runs only when `GeneratorResult.ShouldProcess` is `true` — the result carries a value +**and** none of its diagnostics are blocking. + +`ReportableDiagnostic.IsBlocking` is an explicit per-diagnostic decision, **independent of +severity**. An `Error`-severity diagnostic can still allow generation to continue, which is what you +want when the generated code is what helps the developer fix the problem — a generator emitting an +abstract base class can report an error per missing override while still emitting the base class, so +the user can see exactly what to implement: + +```csharp +static readonly DiagnosticDescriptor MissingOverride = new( + "MYGEN001", + "Missing override", + "Type '{0}' must override '{1}'", + "Usage", + DiagnosticSeverity.Error, + isEnabledByDefault: true +); + +// IsBlocking is false, so ShouldProcess stays true and the base class is still emitted. +var diagnostic = ReportableDiagnostic.Create(MissingOverride, isBlocking: false, symbol, symbol.Name, "Execute"); + +return GeneratorResult.Create(model, diagnostic); +``` + +`isBlocking: true` stops generation for that target while still reporting. +`HasBlockingDiagnostics` reports whether any carried diagnostic blocked; +`HasErrorDiagnostics` reports the severity-based view. + +## Disabling a generator at build time + +Pass the compiler-visible disable property to the context provider; its resolved value lands in +`GenerationSettings` automatically: + +```xml + + true + +``` + +```csharp +var contextProvider = IncrementalPipeline.DefaultGenerationContextValueProvider( + context, + nameof(MyGenerator), + "1.0.0", + disablePropertyName: "MyGenerator_Disable" +); + +// In the output stage: +if (generationContext.Settings.IsSourceGeneratorDisabled) + return; +``` + +`IsDisabledValueProvider` is still there for when expensive upstream transforms must be filtered +before being combined with the generation context. + +Declare the property with `PurviewGeneratorVisibleProperty` so it is compiler-visible wherever the +generator runs — `PSGF0003` otherwise fails the build. See the `purview-sourcegenerator-packaging` +skill. + +## Scope validation + +The default context provider reads +`PurviewSourceGeneratorFrameworkValidateCodeWriterScopes` and threads it into +`GenerationSettings.ValidateCodeWriterScopes`. When enabled, `ToString()` throws +`CodeWriterScopeValidationException` if `OpenScopeCount` is not zero. + +## Test logging + +Framework logging is off in ordinary compiler runs. The testing integration enables it by registering +an isolated sink and supplying a per-run session ID through analyzer config. Context providers create +the internal logger automatically — generators implement no logging interface and no logging-support +source is generated. + +The sink registry stores **callbacks only**; it never buffers entries. With logging disabled, a +missing session ID, or no matching sink, the provider supplies no logger and log calls are discarded. +Test sinks own whatever they capture and are removed when the run completes. + +## Tracking names + +The pipeline helpers assign a tracking name to every stage, so a cache test can assert which stages +were recomputed. The `purview-sourcegenerator-testing` skill covers the stage matrix and the four +scenarios a cache test should assert. + +## Related skills + +`purview-sourcegenerator-codewriter` for emission, `purview-sourcegenerator-diagnostics` for the +`PSGFR` rules that enforce most of the above, and `purview-sourcegenerator-testing` for proving the +pipeline caches. diff --git a/.agents/skills/purview-sourcegenerator-testing/SKILL.md b/.agents/skills/purview-sourcegenerator-testing/SKILL.md new file mode 100644 index 00000000..aaeff09e --- /dev/null +++ b/.agents/skills/purview-sourcegenerator-testing/SKILL.md @@ -0,0 +1,404 @@ +--- +name: purview-sourcegenerator-testing +description: >- + Use when writing or fixing tests for source generators, diagnostic analyzers, code fixes or + refactorings built on Purview.SourceGeneratorFramework - picking the right runner and base class, + configuring SourceGeneratorTestOptions, querying produced code with CodeQuery, and asserting + incremental pipeline caching stage by stage. +metadata: + product: Purview.SourceGeneratorFramework + repository: purview-dev/sourcegenerator-framework +--- + +# Testing source generators, analyzers, code fixes and refactorings + +Use this skill whenever a task involves authoring, fixing, or modernising tests for Roslyn components +(generators, diagnostic analyzers, code fix providers, refactoring providers) built with +`Purview.SourceGeneratorFramework`. It covers the framework-agnostic test runner layer and the +`CodeQuery` syntax-lookup API. For the TUnit base classes and assertion extensions, also load the +`purview-sourcegenerator-tunit-tests` skill. + +Modernising an existing suite onto `CodeQuery` and adding a stage-by-stage cache test? The playbook +is in [references/test-modernisation.md](references/test-modernisation.md). + +## Picking the right runner + +| Roslyn type | Runner | +|---|---| +| `IIncrementalGenerator` / `ISourceGenerator` | `SourceGeneratorTestRunner` | +| `DiagnosticAnalyzer` | `DiagnosticAnalyzerTestRunner` | +| `CodeFixProvider` | `CodeFixTestRunner` (single) | +| — | `CodeFixTestRunner.RunFixAllAsync` (project-wide) | +| `CodeRefactoringProvider` | `RefactoringTestRunner` | + +TUnit projects should prefer the matching base class instead (see `purview-sourcegenerator-tunit-tests`): +`TUnitSourceGeneratorTestBase`, `TUnitDiagnosticAnalyzerTestBase`, `TUnitCodeFixTestBase`, +`TUnitRefactoringTestBase`. + +## Result types + +- `DriverRunResult` (generator) — `DriverResult`, `AllSyntaxTrees`/`PrimarySyntaxTrees`, + `CompilationResult.Compilation`, `GetGeneratedTree`, `GetSource`, `GetTypeByMetadataName`, `LogEntries`. +- `AnalyzerTestResult` — `Diagnostics`, `Compilation`. +- `CodeFixTestResult` — `Diagnostics`, `CodeActions`, `FixedSource`, `Compilation`, `ChangedSolution`. +- `CodeFixFixAllResult` — `Diagnostics`, `CodeActions`, `FixedSources`, `ChangedSolution`. +- `RefactorTestResult` — `CodeActions`, `FixedSources`, `ChangedSolution`, `Compilation`. + +Use `DriverRunResultExtensions` (`AssertNoCompilationErrors`, `AssertNoGenerationExceptions`, +`AssertSingleGeneratedSource`, `AssertGeneratedSourceContains`, …) for quick checks, but prefer +`CodeQuery` for structural assertions. + +## Querying produced code with `CodeQuery` + +Every result exposes a `CodeQuery` via extensions in `CodeQueryResultExtensions`: + +```csharp +result.Generated() // DriverRunResult: generated trees (default, generated-first) +result.Output() // DriverRunResult: entire output compilation (user + generated) +analyzerResult.Code() // AnalyzerTestResult: input compilation +codeFixResult.Code() // CodeFixTestResult: input compilation +codeFixResult.FixedCode() // CodeFixTestResult: parsed fixed source (or post-fix solution) +fixAllResult.FixedCode() // CodeFixFixAllResult: post-fix documents +refactorResult.FixedCode() // RefactorTestResult: post-refactor documents +``` + +Every `Get` has an accompanying `Has` (bool) and `TryGet` (out): `GetMethod`/`HasMethod`/`TryGetMethod`, +`GetClass`, `GetStruct`, `GetInterface`, `GetEnum`, `GetDelegate`, `GetRecord`, `GetProperty`, +`GetField`, `GetConstructor`, `GetNamespace`, `GetTypeDeclaration`, plus generic `Get`/`Has` +and `GetSyntaxTree`/`HasSyntaxTree`. `Get` throws `SyntaxNotFoundException` when nothing matches. + +Type lookups accept an optional generic arity — `GetClass(name, arity)` / `HasClass(name, arity)` — and the +`TypeReference`/`TypeIdentity` overloads match arity automatically from the identity, so +`new TypeIdentity("ResourceDefinition", ns, arity: 1)` finds `ResourceDefinition` without matching the +non-generic `ResourceDefinition`. + +Every `Get` returns a `CodeQueryResult` — the matched syntax node (`Node`) plus a query scoped to it +(`Query`), with implicit conversions to both the node and the scoped query. Use `.Node` for direct syntax +access, or chain member queries (the originating query is carried by the result, so it is not passed again). + +Types can be matched against `TypeReference`/`TypeIdentity`, resolved through the compilation's semantic +model (nullable value types are significant, so `int?` never matches `int`): + +```csharp +result.Generated().HasMethod("DoWork", TypeReference.Create(), TypeReference.Create().Nullable(), complexType); +result.Generated().HasReturnType("Compute", TypeReference.Create()); +result.Generated().GetMethod("Format").HasParameters(TypeReference.Create(), objectReference); +``` + +When a test expects a nullable annotation, prefer the test-only `query.MakeNullable(type)` extension (on a +`CodeQuery`, accepting a `TypeReference` or `TypeIdentity`). It resolves the annotation against the query's +compilation and, unlike `TypeReference.Nullable()`/`TypeIdentity.MakeNullable()`, does not trigger the +`PSGFR16` context-overload suggestion (tests have no generation context to pass). + +Member chaining from a type declaration (`MemberQueryExtensions`): + +```csharp +var service = result.Generated().GetClass("ServiceCollectionExtensions"); // or GetClass(name, "Namespace") +service.HasProperty("Count", intType); +service.HasIndexer(stringType, intType); +service.HasMethod("Add", intType, complexType); +service.HasMethodReturnType("Add", stringType); +service.HasConstructor(stringType); +service.HasAttribute("SomeAttribute"); +``` + +Node-inspection checks on scoped results: + +```csharp +result.Generated().GetClass("Service").HasAccessibility(Accessibility.Public); // resolves C# defaults +result.Generated().GetClass("Service").GetProperty("Name").HasSetterAccessibility(Accessibility.Private); +result.Generated().GetClass("ResourceDefinition", 1).HasGenericTypeParameters("TResourceType"); +result.Generated().GetClass("ResourceDefinition", 1).HasBaseType(new TypeIdentity("ResourceDefinition", ns)); +result.Generated().GetClass("Service").HasNestedType("Builder"); // GetNestedType(...) to fetch +result.Generated().GetClass("Service").IsInNamespace("Example.Models"); // IsInGlobalNamespace() for no namespace +result.Generated().IsInNamespace(cls.Node, "Example.Models"); // or on the query directly +``` + +## Configuring options and a reusable starting point + +`SourceGeneratorTestOptions` is the base record. Common knobs: + +- `AdditionalNamespaces` / `IncludeDefaultNamespaces` — namespaces prepended to test source. +- `AdditionalAssemblyTypes` / `AdditionalReferences` — assemblies referenced by the test compilation + (use `AdditionalAssemblyTypes = [typeof(SomeType)]` to pull in a whole assembly). +- `AdditionalSources` — extra source files added to every run. +- `AnalyzerConfigOptions` — `build_property.*` values; keys without the prefix are also exposed as MSBuild + properties. +- `DisableSourceGeneratorPropertyName` / `DisableSourceGeneratorValue` — generator disable toggle. +- `NullableContextOptions`, `OutputKind`, `LanguageVersion`, `CompileToAssembly`. +- `ValidateCodeWriterScopes`, `EnableLogging`. +- `ExcludeGeneratedSourceHintNames` — hides generated marker trees from `PrimarySyntaxTrees`. + +**Easy starting point recipe.** Derive an options record that seeds the namespaces and assemblies your +generator needs, so every test gets a working compilation with no boilerplate: + +```csharp +public sealed record MyGeneratorTestOptions : SourceGeneratorTestOptions +{ + public MyGeneratorTestOptions() + { + AdditionalNamespaces = AdditionalNamespaces.Add("My.Namespace"); + AdditionalAssemblyTypes = AdditionalAssemblyTypes.AddRange( + typeof(SomeDependencyType), + typeof(TypeIdentity) // the framework's Shared assembly, when needed + ); + DisableSourceGeneratorPropertyName = PropertyLibrary.DisableMyGenerator; + } +} +``` + +`Compile()` returns a copy with `CompileToAssembly = true`, preserving the derived options type. Use the +base class hooks `OnBeforeRun`/`OnBeforeRunAsync`/`OnAfterRun` to mutate sources/options per run (for +example to append a marker attribute source via `WithAdditionalSources`). + +When `CompileToAssembly` is enabled, emission is fully in-memory. On .NET 8+ the assembly loads into a +collectible `AssemblyLoadContext`, so the result is `IDisposable` — `using var result = ...` unloads it and +keeps repeated runs from polluting the default context. `result.CompilationResult.Assembly` is the runnable +assembly (generated code can execute); `result.CompilationResult.Metadata` / `.MetadataAssembly` give a +metadata-only reflection view (types, members, attributes) over the emitted assembly without executing code. + +**Always write `using var result = ...`.** `PSGFR42` ("Dispose test harness results with a using +declaration") flags a `DriverRunResult` that is produced and never disposed — including the indirect case +where a helper creates a result, projects a value out of it and returns only the projection. It is a +`warning` when the run syntactically compiles to an assembly (`.Compile()`, a `Compile` options member, or +`CompileToAssembly = true`) and `info` otherwise; the `DisposeTestResultCodeFixProvider` fix inserts the +`using`. A result that is returned to the caller, or disposed explicitly, is not flagged. Neither is awaiting +an assertion, nor calling a helper that is handed the result — an extension on it, or a method taking it as a +parameter: both hand the same instance back, so `await Assert.That(result).SomeAssertion()` and +`result.AssertNoGenerationExceptions()` are not flagged. + +## Best practices + +- **Deterministic output**: `WriteAutoGeneratedHeader` is timestamp-free; assert with + `ContainsGeneratedCode`/`GeneratesCode` (whitespace-flattened) or `CodeQuery`, never with timestamps. +- **Generator references**: to use a generated type in the test project AND pass the generator type to a + runner, reference the generator project twice — once `OutputItemType="Analyzer"` and once as a normal + reference. +- **Multi-target**: build generators against the Roslyn version that supports the test matrix; the + framework is built against Roslyn 5.0 (net8.0/net9.0 assets keep a .NET 8–10 matrix loading); keep + `System.Collections.Immutable` version pinned to the shared one. +- **Scope validation**: keep `PurviewSourceGeneratorFrameworkValidateCodeWriterScopes` enabled; it makes + undisposed `CodeWriter` scopes fail tests. +- **Prefer `CodeQuery` over string matching** for structural assertions (members, signatures, namespaces). +- **Dispose results**: `using var result = ...`, enforced by `PSGFR42`. +- **Cap parallelism**: the harness shares one `MetadataReference` set per process, so memory is largely flat + in the degree of parallelism, but the platform's auto-detected default is both slower and heavier than an + explicit ceiling. Wall clock saturates around four concurrent tests; prefer + `--maximum-parallel-tests 8` (or a `TestingPlatformCommandLineArguments` equivalent) for a project that + multi-targets and runs several TFM executables at once. + +## Incremental cache testing (`RunIncrementalAsync`) + +To prove the pipeline caches correctly stage-by-stage, use `SourceGeneratorTestRunner.RunIncrementalAsync` +(or `GenerateIncrementalAsync` on the TUnit base). It runs a sequence of source sets over a **single shared +`GeneratorDriver`** and captures each run's `TrackedSteps`, keyed by tracking name. The canonical reference +implementation is `IncrementalPipelineCacheTests` in `SourceGeneratorShared.UnitTests`; the end-to-end +generator variant is `ServiceRegistrationCacheTests` in +`SourceGeneratorFramework.ExampleGenerator.UnitTests`. Copy the pattern into your own test project — do +not expect the source repo's files locally. + +### What is being asserted and why + +Roslyn reports one `IncrementalStepRunReason` per step output on each run: + +- `New` — the step ran for the first time. +- `Modified` — the step ran and produced a different value than the previous run. +- `Unchanged` — the step ran but produced the same value. +- `Cached` — the step was skipped and its previous result reused from the incremental cache. + +A pipeline is "caching correctly" when an unchanged input keeps every stage `Cached`/`Unchanged`, and a +targeted change marks **only** the stages whose inputs actually changed `Modified` while unrelated stages +stay `Cached`. If a generator accidentally leaks `Compilation`, `SemanticModel`, `ISymbol`, +`SyntaxNode`, or `Location` into a pipeline model, unrelated stages will report `Modified`/`New` on rerun — +these tests fail the build and catch the regression. + +### The four scenarios every cache test should cover + +1. **First run → all `New`.** Nothing can be cached on the first run; this confirms every stage is tracked + under the expected name. +2. **Identical rerun → all `Cached`/`Unchanged`.** `RunIncrementalAsync(sources, ...)` runs the same source + set twice for exactly this case. This is the strongest "it caches" proof. +3. **Source-only change → only the source/attribute stage `Modified`.** Changing an attributed class must + mark `ForAttribute_*` (and downstream output) `Modified` while property/config stages stay `Cached`. +4. **Property-only change → only the property/configuration stage `Modified`.** Toggling an MSBuild + property (via `IncrementalRunInput.AnalyzerConfig`) must mark `GetMSBuildPropertyValue_*` / + `GetGenerationConfiguration` / `GetGenerationContext_*` `Modified` while `ForAttribute_*` stays `Cached`. + +### How the runner makes this possible + +`RunIncrementalAsync` creates **one** driver, enables incremental step tracking, and **reuses the same +`Compilation` instance for identical source sets** (keyed by prepared source text). Without that reuse, +Roslyn would see a fresh compilation on the second run and report stages `Modified`/`New` even though the +sources are byte-identical — the "cached" assertion would fail. + +### Log entries per run + +`IncrementalCacheRun.LogEntries` carries the framework log entries that run wrote, in order. The sink is +registered for the whole sequence and drained between runs, so entries never accumulate. A rerun whose +output step is cached logs nothing, which makes it a second signal alongside the step reasons: + +```csharp +await Assert.That(result.Runs[0].LogEntries).IsNotEmpty(); +await Assert.That(result.Runs[1].LogEntries).IsEmpty(); +``` + +`DriverRunResult.LogEntries` (the `RunAsync` path) is likewise in write order. Both are empty when +`EnableLogging` is disabled. + +### The `StepReasons` helper + +`IncrementalCacheRun.Steps` is `ImmutableDictionary>` +keyed by tracking name. Flatten each step's `Outputs` into the reasons list so assertions read cleanly: + +```csharp +static ImmutableDictionary> StepReasons(IncrementalCacheRun run) +{ + var builder = ImmutableDictionary.CreateBuilder>(); + foreach (var pair in run.Steps) + builder[pair.Key] = [.. pair.Value.SelectMany(step => step.Outputs.Select(static output => output.Reason))]; + return builder.ToImmutable(); +} +``` + +### Framework pipeline stage names + +- `GetMSBuildPropertyValue_{Property}` — `IncrementalPipeline.PropertyValueProvider`. +- `GetGenerationConfiguration` — `IncrementalPipeline.GenerationContextValueProvider`. +- `GetGenerationContext_{Capabilities}` — e.g. `GetGenerationContext_EmptyCapabilities`. +- `ForAttribute_{AttributeType}` — `IncrementalPipeline.ForAttributeWithMetadataName`. + +The framework reference (`IncrementalPipelineCacheTests`, framework-agnostic runner) shows all four +scenarios against `TestGenerator`/`DiagnosticTestGenerator`: + +```csharp +using System.Collections.Immutable; +using Purview.SourceGeneratorFramework.TestGenerators; +using StepReason = Microsoft.CodeAnalysis.IncrementalStepRunReason; + +public class IncrementalPipelineCacheTests +{ + const string AttributedSource = """ + [TestAttribute] + public partial class MyClass { } + """; + const string ChangedAttributedSource = """ + [TestAttribute] + public partial class AnotherClass { } + """; + const string TestAttributeSource = """ + [System.AttributeUsage(System.AttributeTargets.Class)] + public sealed class TestAttribute : System.Attribute { } + """; + + static SourceGeneratorTestOptions CreateOptions() => + new SourceGeneratorTestOptions() + .WithAdditionalSources(TestAttributeSource) + .WithExcludeGeneratedSourceHintNames("TestAttribute"); + + static ImmutableDictionary> StepReasons(IncrementalCacheRun run) { /* as above */ } + + [Test] + public async Task FirstRun_AllStagesAreNew(CancellationToken cancellationToken) + { + var result = await new SourceGeneratorTestRunner().RunIncrementalAsync( + [new IncrementalRunInput([AttributedSource])], + CreateOptions(), + cancellationToken); + + var reasons = StepReasons(result.Runs[0]); + await Assert.That(reasons).IsNotEmpty(); + await Assert.That(reasons.Values.SelectMany(r => r).All(r => r == StepReason.New)).IsTrue(); + } + + [Test] + public async Task IdenticalRerun_AllStagesCached(CancellationToken cancellationToken) + { + var result = await new SourceGeneratorTestRunner() + .RunIncrementalAsync([AttributedSource], CreateOptions(), cancellationToken); + + var second = StepReasons(result.Runs[1]); + await Assert.That(second.Values.SelectMany(r => r).All(r => r is StepReason.Cached or StepReason.Unchanged)).IsTrue(); + } + + [Test] + public async Task SourceChange_MarksAttributeStageModified_PropertyStagesStayCached(CancellationToken cancellationToken) + { + var result = await new SourceGeneratorTestRunner().RunIncrementalAsync( + [new IncrementalRunInput([AttributedSource]), new IncrementalRunInput([ChangedAttributedSource])], + CreateOptions(), + cancellationToken); + + var second = StepReasons(result.Runs[1]); + await Assert.That(second["ForAttribute_TestAttribute"]).Contains(StepReason.Modified); + await Assert.That(second["GetMSBuildPropertyValue_DisableTestGenerator"].All(r => r == StepReason.Cached)).IsTrue(); + } + + [Test] + public async Task PropertyChange_MarksPropertyStageModified_AttributeStageStaysCached(CancellationToken cancellationToken) + { + var result = await new SourceGeneratorTestRunner().RunIncrementalAsync( + [ + new IncrementalRunInput([AttributedSource]), + new IncrementalRunInput([AttributedSource], [("build_property.DisableTestGenerator", "true")]), + ], + CreateOptions(), + cancellationToken); + + var second = StepReasons(result.Runs[1]); + await Assert.That(second["GetMSBuildPropertyValue_DisableTestGenerator"]).Contains(StepReason.Modified); + await Assert.That(second["ForAttribute_TestAttribute"].All(r => r == StepReason.Cached)).IsTrue(); + } +} +``` + +### End-to-end generator variant (`GenerateIncrementalAsync`) + +TUnit tests derive from the base class and call `GenerateIncrementalAsync` (which wires the +`OnBeforeRun`/`OnBeforeRunAsync` hooks and the derived options). `ServiceRegistrationCacheTests` in +`SourceGeneratorFramework.ExampleGenerator.UnitTests` is the reference: + +```csharp +public class ServiceRegistrationCacheTests + : TUnitSourceGeneratorTestBase +{ + const string Source = """ + namespace Test; + + [GenerateService] + public class MyService { } + """; + + [Test] + public async Task IdenticalRerun_AllStagesCached(CancellationToken cancellationToken) + { + var result = await GenerateIncrementalAsync([Source], cancellationToken: cancellationToken); + + var second = StepReasons(result.Runs[1]); + string[] frameworkStages = + [ + "GetMSBuildPropertyValue_EmitServiceRegistrationInfo", + "GetGenerationConfiguration", + "GetGenerationContext_EmptyCapabilities", + "ForAttribute_GenerateServiceAttribute", + ]; + await Assert.That( + frameworkStages.All(stage => + second.TryGetValue(stage, out var reasons) + && reasons.All(r => r is StepReason.Cached or StepReason.Unchanged))).IsTrue(); + } +} +``` + +**Why the example filters to `frameworkStages`:** `ServiceRegistrationGenerator` emits its own +`GenerateServiceAttribute` via post-initialization output, which is regenerated as a new `SyntaxTree` each +run. That makes Roslyn's *internal* `ForAttributeWithMetadataName` `Compilation` step legitimately report +`Modified` on an identical rerun. Asserting on the framework-named stages (which stay `Cached`/`Unchanged`) +is the meaningful check. If your generator does not depend on its own post-init output, the stricter +"every tracked step is `Cached`/`Unchanged`" assertion (as in the framework `IncrementalPipelineCacheTests`) +is correct. + +Per-run MSBuild-property changes are supplied with `new IncrementalRunInput(sources, [("build_property.X", "value")])`. + +## License + +This project is licensed under the MIT license. \ No newline at end of file diff --git a/.agents/skills/purview-sourcegenerator-testing/references/test-modernisation.md b/.agents/skills/purview-sourcegenerator-testing/references/test-modernisation.md new file mode 100644 index 00000000..6db47803 --- /dev/null +++ b/.agents/skills/purview-sourcegenerator-testing/references/test-modernisation.md @@ -0,0 +1,63 @@ +# Modernising a Roslyn test suite + +A playbook for moving an existing test suite onto `CodeQuery` plus the TUnit assertion extensions, +and adding a stage-by-stage incremental cache test. + +## Before you start, collect + +- The test file(s) being changed. +- The Roslyn component under test — generator, analyzer, code fix or refactor (infer it from the + base class if the task does not say). +- The component's type name. + +## Requirements + +### 1. The right base class and method + +| Component | Base class | Method | +| --- | --- | --- | +| Generator | `TUnitSourceGeneratorTestBase` | `GenerateAsync` | +| Analyzer | `TUnitDiagnosticAnalyzerTestBase` | `AnalyzeAsync` | +| Code fix | `TUnitCodeFixTestBase` | `ApplyCodeFixAsync` / `ApplyFixAllAsync` | +| Refactor | `TUnitRefactoringTestBase` | `RefactorAsync` | + +### 2. `CodeQuery` instead of string matching + +Replace `GetGeneratedTree(...)` + `string.Contains(...)` with `CodeQuery` +(`result.Generated().Get/Has/TryGet…`) and the terminal assertion extensions — +`await Assert.That(result).HasGeneratedMethod/Class/Property/Field/SyntaxTree(…)` — which return the +node so a follow-up assertion has something to work with. + +### 3. `TypeReference` instead of signature strings + +Match parameter and return types structurally. A signature string breaks on a whitespace or +nullability change that means nothing. + +### 4. Options in one place + +Derive a `SourceGeneratorTestOptions` record that seeds the required namespaces and additional +assemblies, and remove the per-test duplication it replaces. + +### 5. A stage-by-stage cache test + +Use `RunIncrementalAsync`, or `GenerateIncrementalAsync` on the TUnit base, and assert the four +scenarios. `ServiceRegistrationCacheTests` and `IncrementalPipelineCacheTests` are the reference +pattern. + +| Scenario | Expected | +| --- | --- | +| First run | every framework stage `New` | +| Identical rerun (`RunIncrementalAsync(sources, …)` runs the same source twice) | framework stages `Cached`/`Unchanged` | +| Source-only change | `ForAttribute_*` `Modified`; property/config stages stay `Cached` | +| Property-only change (`new IncrementalRunInput(sources, [("build_property.X", "value")])`) | `GetMSBuildPropertyValue_*`, `GetGenerationConfiguration`, `GetGenerationContext_*` `Modified`; `ForAttribute_*` stays `Cached` | + +Use the `StepReasons(IncrementalCacheRun)` flattening helper. If the generator depends on its own +post-init output, assert on the framework-named stages rather than on every tracked step. + +### 6. Minimal change + +Keep behaviour equivalent, and do not reformat unrelated tests. + +## Verification + +Build the test project and run its suite before finishing. diff --git a/.agents/skills/purview-sourcegenerator-tunit-tests/SKILL.md b/.agents/skills/purview-sourcegenerator-tunit-tests/SKILL.md new file mode 100644 index 00000000..bc711c59 --- /dev/null +++ b/.agents/skills/purview-sourcegenerator-tunit-tests/SKILL.md @@ -0,0 +1,230 @@ +--- +name: purview-sourcegenerator-tunit-tests +description: >- + Use when writing TUnit tests for source generators, diagnostic analyzers, code fixes or + refactorings built on Purview.SourceGeneratorFramework - choosing the correct TUnit base class and + method, customising SourceGeneratorTestOptions, using the TUnit assertion extensions, and + modernising existing tests. +metadata: + product: Purview.SourceGeneratorFramework.Testing.TUnit + repository: purview-dev/sourcegenerator-framework +--- + +# TUnit test authoring for Roslyn components + +Use this skill whenever a task involves authoring, fixing, or modernising **TUnit** tests for Roslyn +components built with `Purview.SourceGeneratorFramework`. It tells you which base class to derive from, +which method to call, how to customise options with an easy starting point, and how to use the TUnit +assertion extensions. For the framework-agnostic runner layer and the `CodeQuery` API, also load the +`purview-sourcegenerator-testing` skill. + +## Base class → method matrix + +| Roslyn type | Base class | Method to call | +|---|---|---| +| `IIncrementalGenerator` / `ISourceGenerator` | `TUnitSourceGeneratorTestBase` | `GenerateAsync(source, options, ct)` | +| `DiagnosticAnalyzer` | `TUnitDiagnosticAnalyzerTestBase` | `AnalyzeAsync(source, options, ct)` | +| `CodeFixProvider` (single fix) | `TUnitCodeFixTestBase` | `ApplyCodeFixAsync(source, options, ct)` | +| `CodeFixProvider` (fix-all) | `TUnitCodeFixTestBase` | `ApplyFixAllAsync(sources, options, ct)` | +| `CodeRefactoringProvider` | `TUnitRefactoringTestBase` | `RefactorAsync(source, options, ct)` | + +For cache tests, `TUnitSourceGeneratorTestBase` also exposes `GenerateIncrementalAsync(...)`. + +Framework-agnostic equivalents (no TUnit): `SourceGeneratorTestRunner`, `DiagnosticAnalyzerTestRunner`, +`CodeFixTestRunner`, `RefactoringTestRunner`. + +## Easy starting point: derive your options record + +Create a test-options record that seeds the namespaces and assemblies your component needs, then pass it +to every test via `new MyTestOptions()`: + +```csharp +public sealed record MyGeneratorTestOptions : SourceGeneratorTestOptions +{ + public MyGeneratorTestOptions() + { + AdditionalNamespaces = AdditionalNamespaces.Add("My.Namespace"); + AdditionalAssemblyTypes = AdditionalAssemblyTypes.AddRange( + typeof(SomeDependencyType), + typeof(TypeIdentity) // framework Shared assembly, when needed + ); + DisableSourceGeneratorPropertyName = "DisableMyGenerator"; + } +} + +public class MyGeneratorTests : TUnitSourceGeneratorTestBase +{ + [Test] + public async Task GeneratesExpectedSource(CancellationToken ct) => + await GenerateAsync("...source...", ct); +} +``` + +Use the base hooks to customise per-run: `OnBeforeRun`/`OnBeforeRunAsync` (mutate sources/options, e.g. +`options.WithAdditionalSources(markerAttributeSource)`) and `OnAfterRun`/`OnAfterRunAsync`. Use +`options.Compile()` to opt into `CompileToAssembly` while preserving the derived options type. + +Write `using var result = await GenerateAsync(...)`: `DriverRunResult` is `IDisposable`, and `PSGFR42` +flags a result that is produced and never disposed (a `warning` once the run compiles to an assembly, +`info` otherwise). It also catches the indirect case — a helper that creates a result, projects a value out +of it and returns only the projection. Awaiting an assertion, or calling a helper that is handed the result — +an extension on it, or a method taking it as a parameter — is not a production: both hand the same instance +back, so neither is flagged. + +For code fixes/refactorings, select a specific registered action via `CodeFixTestOptions.EquivalenceKey` +or `CodeActionIndex`, and `RefactorTestOptions.Span`/`NodeSelector` (e.g. +`NodeSelector = query => query.GetMethod("M")`). + +## TUnit assertion extensions + +All assertion extensions live under `Purview.SourceGeneratorFramework.Testing.TUnit.Assertions` +(globally imported by the package's props). `Assert.That(...)` calls are terminal and **return the value** +when awaited. + +- **`CodeQueryAssertions`** — return `CodeQueryResult` (the matched node via `.Node`, plus a query + scoped to it via `.Query`): `HasGeneratedMethod` (optionally with `TypeReference[]` parameter types), + `HasGeneratedMethodReturnType`, `HasGeneratedClass` (by name or `TypeReference`/`TypeIdentity` identity), + `HasGeneratedProperty`, `HasGeneratedField`, `HasGeneratedSyntaxTree`; `HasFixedMethod` for code-fix and + refactor results. The assertions operate on a `CodeQuery` directly, so pass any query — `result.Generated()` + (generated trees), `result.Output()` (whole compilation), or `result.FixedCode()` — or use the convenience + overloads on the test result types, which query the relevant code for you. +- **Scoped member chaining** — `HasPropertyOfType(name, type)`, `HasFieldOfType(name, type)`, + `HasMethodOfType(name, TypeReference[])`, `HasConstructorOfType(TypeReference[])`, and + `HasAttributeOfType(name)` chain from a scoped `CodeQueryResult` (e.g. the result of `HasGeneratedClass`) + and return the matched member. They are named to avoid colliding with the bool `Has*` predicates in + `MemberQueryExtensions`. +- **Fluent `.And` chains** — the node-producing assertions (`HasGeneratedClass`, `HasPropertyOfType`, + `HasMethodOfType`, `HasNestedType`) move the chain onto the matched node, so further assertions can be + appended with `.And`. Node-inspection assertions — `WithAccessibility`, `WithGetterAccessibility`, + `WithSetterAccessibility`, `WithBaseType`, `WithGenericTypeParameter(s)`, `IsInNamespace`, + `IsInGlobalNamespace` — keep the node on the chain: + ```csharp + var method = await Assert.That(query) + .HasGeneratedClass("Service") + .And.HasNestedType("Builder") + .And.WithAccessibility(Accessibility.Private) + .And.HasMethodOfType("Build", []); + ``` + Generic types are matched by arity — `HasGeneratedClass(name, arity)` or a `TypeIdentity` with arity — + so `new TypeIdentity("ResourceDefinition", ns, arity: 1)` finds `ResourceDefinition` + without matching the non-generic `ResourceDefinition`. +- **Nullable expected types in tests** — use the test-only `query.MakeNullable(type)` extension (on a + `CodeQuery`). It resolves the annotation against the query's compilation and, unlike + `TypeReference.Nullable()`/`TypeIdentity.MakeNullable()`, does not trip the `PSGFR16` context-overload + suggestion, since tests have no generation context to pass. + ```csharp + CodeQueryResult method = await Assert.That(result.Generated()).HasGeneratedMethod("DoWork", [intType, nullableInt]); + CodeQueryResult cls = await Assert.That(result.Generated()).HasGeneratedClass("Service"); + await Assert.That(cls.HasProperty("Count", intType)).IsTrue(); // chained member query + await Assert.That(cls.Node.Identifier.ValueText).IsEqualTo("Service"); // direct syntax access + await Assert.That(result.FixedCode()).HasFixedMethod("DoWork"); // code-fix / refactor results + + var query = result.Generated(); + var attributeClass = await Assert.That(query).HasGeneratedClass(hostKitAttribute); + await Assert.That(attributeClass).HasPropertyOfType("Name", query.MakeNullable(TypeLibrary.System.String)); + ``` +- **`DiagnosticAssertions`** — `HasDiagnostic(descriptor|id)`, `HasDiagnostics(count)`, + `DoesNotHaveDiagnostic`, `HasNoDiagnostics`, `HasNoErrorDiagnostics` on generator/analyzer/code-fix results. +- **`TypeIdentityAssertions`** — `HasSymbol(TypeIdentity)` / `HasSymbol("Namespace.Type")`. +- **`GeneratedCodeAssertionsExtensions`** — `GeneratesCode(expected)`, `ContainsGeneratedCode(expected)` + (whitespace-flattened string comparison). + +For structural assertions (members, signatures, namespaces) prefer `result.Generated()` + +`Get/Has/TryGet` from `CodeQuery` (see `purview-sourcegenerator-testing`). + +## Incremental cache tests (`GenerateIncrementalAsync`) + +`TUnitSourceGeneratorTestBase` exposes `GenerateIncrementalAsync`, which mirrors `RunIncrementalAsync` but +also wires the base class hooks (`OnBeforeRun`/`OnBeforeRunAsync`) and your derived options record. Use it to +prove the pipeline caches stage-by-stage. The reference is `ServiceRegistrationCacheTests` in +`SourceGeneratorFramework.ExampleGenerator.UnitTests`; the framework-agnostic twin with a full walkthrough is +in the `purview-sourcegenerator-testing` skill. + +Why the tests look the way they do: + +- `GenerateIncrementalAsync([Source])` runs the **same source twice** on a single shared driver. The first + run reports every stage `New`; the second must report `Cached`/`Unchanged` for unchanged stages — that is + the core "it caches" proof. +- `GenerateIncrementalAsync([new IncrementalRunInput([Source]), new IncrementalRunInput([changed])])` runs two + **different** source sets, so a source-only change must mark `ForAttribute_*` `Modified` while + property/configuration stages stay `Cached`. +- `new IncrementalRunInput([Source], [("build_property.X", "value")])` toggles an MSBuild property for one + run only, so a property-only change must mark `GetMSBuildPropertyValue_*`/`GetGenerationConfiguration`/ + `GetGenerationContext_*` `Modified` while `ForAttribute_*` stays `Cached`. +- `result.Runs[n].LogEntries` carries the framework log entries *that run* wrote, in order, so a rerun whose + output step is cached can be asserted to have logged nothing. Empty when `EnableLogging` is disabled. +- The `StepReasons(IncrementalCacheRun)` helper flattens each tracked step's `Outputs` into a + `ImmutableDictionary>` so assertions can address a stage + by name (see `purview-sourcegenerator-testing` for the helper body). +- If the generator's pipeline depends on its own post-initialization output (a self-referencing generated + attribute), Roslyn's internal `ForAttributeWithMetadataName` `Compilation` step is legitimately `Modified` + on rerun; assert on the framework-named stages (e.g. `ForAttribute_GenerateServiceAttribute`, + `GetGenerationConfiguration`, `GetGenerationContext_EmptyCapabilities`) rather than every tracked step. + +```csharp +public class ServiceRegistrationCacheTests + : TUnitSourceGeneratorTestBase +{ + const string Source = """ + namespace Test; + + [GenerateService] + public class MyService { } + """; + + [Test] + public async Task IdenticalRerun_AllStagesCached(CancellationToken cancellationToken) + { + var result = await GenerateIncrementalAsync([Source], cancellationToken: cancellationToken); + + var second = StepReasons(result.Runs[1]); + string[] frameworkStages = + [ + "GetMSBuildPropertyValue_EmitServiceRegistrationInfo", + "GetGenerationConfiguration", + "GetGenerationContext_EmptyCapabilities", + "ForAttribute_GenerateServiceAttribute", + ]; + await Assert.That( + frameworkStages.All(stage => + second.TryGetValue(stage, out var reasons) + && reasons.All(r => r is StepReason.Cached or StepReason.Unchanged))).IsTrue(); + } + + [Test] + public async Task PropertyChange_MarksPropertyStageModified_AttributeStageStaysCached(CancellationToken cancellationToken) + { + var result = await GenerateIncrementalAsync( + [ + new IncrementalRunInput([Source]), + new IncrementalRunInput([Source], [(PropertyLibrary.EmitServiceRegistrationInfo, "true")]), + ], + cancellationToken: cancellationToken); + + var second = StepReasons(result.Runs[1]); + await Assert.That(second["GetMSBuildPropertyValue_EmitServiceRegistrationInfo"]).Contains(StepReason.Modified); + await Assert.That(second["ForAttribute_GenerateServiceAttribute"].All(r => r is StepReason.Cached or StepReason.Unchanged)).IsTrue(); + } +} +``` + +Use `using StepReason = Microsoft.CodeAnalysis.IncrementalStepRunReason;` and your own stage names. + +## Modernising existing tests + +When converting legacy tests that do `result.GetGeneratedTree(...)` + `string.Contains(...)`: + +1. Replace tree-lookup + string matching with `result.Generated().GetClass/GetMethod/GetProperty(...)` and + the `Has*`/`TryGet*` family. +2. Replace signature string checks with `TypeReference` parameter/return-type matching. +3. Replace `Assert.That(text).Contains("...")` with the terminal assertion extensions that return nodes. +4. Verify options use a derived record (namespaces + assemblies) rather than repeating `AdditionalNamespaces` + per test. +5. Add a stage-by-stage cache test if the component has an incremental pipeline — first run `New`, + identical rerun `Cached`/`Unchanged`, and targeted changes mark only the affected stage `Modified`. + Use the inlined examples in this skill and in `purview-sourcegenerator-testing`'s "Incremental cache testing" + section, swapping in your own generator and stage names. + +## License + +This project is licensed under the MIT license. \ No newline at end of file diff --git a/.agents/skills/purview-telemetry-design/SKILL.md b/.agents/skills/purview-telemetry-design/SKILL.md new file mode 100644 index 00000000..c8df5f81 --- /dev/null +++ b/.agents/skills/purview-telemetry-design/SKILL.md @@ -0,0 +1,96 @@ +--- +name: purview-telemetry-design +description: Design best practices for Purview.Telemetry.SourceGenerator interfaces. Use when deciding between a single telemetry interface and per-area interfaces, choosing telemetry names, designing multi-target methods, or reviewing telemetry structure in a C# project. +license: MIT +compatibility: C# projects using Purview.Telemetry.SourceGenerator. +metadata: + author: Purview-Dev + version: "1.0" +--- + +# Design best practices for Purview Telemetry + +This skill guides the design of generated telemetry interfaces. + +## Single combined interface vs. per-area interfaces + +The generator lets you put all telemetry types on one interface, or split them by concern. + +### Combined interface + +Use one interface when: + +- A single service owns all telemetry and the operations naturally overlap. +- You want a single injection point and fewer constructor parameters. +- Multi-target methods emit Activity + Log + Metric from one call. + +Naming convention: + +```csharp +[ActivitySource] +[Logger] +[Meter] +public interface IOrderServiceTelemetry +``` + +### Per-area interfaces + +Split into separate interfaces when: + +- Different consumers need only one telemetry type (e.g., tests mock only logs). +- The team prefers clear separation between tracing, logging, and metrics. +- The service is large and each telemetry type has many operations. + +Naming convention: + +```csharp +[ActivitySource] public interface IOrderServiceTracing { ... } +[Logger] public interface IOrderServiceLogs { ... } +[Meter] public interface IOrderServiceMetrics { ... } +``` + +Default recommendation: start with one combined interface per service. Split only when a clear boundary emerges. + +## Naming conventions + +Default to the OpenTelemetry naming convention (`NamingConvention.OpenTelemetry`). + +- ActivitySource names: preserve assembly casing (e.g., `MyApp`). +- Activity names: descriptive, sentence-case-ish, no spaces: `placing-order`. +- Log message templates: human-readable, with `{PascalCase}` placeholders. +- Metric instrument names: hierarchical, dot-separated, lowercase: `myapp.orders.placed`. +- Tag/baggage keys: `snake_case`. + +Only use `NamingConvention.Legacy` for exact v3 backward compatibility. + +## Multi-target method design + +Combine attributes on one method when a single operation emits multiple telemetry types: + +```csharp +[Activity] +[Info] +[AutoCounter] +Activity? PlacingOrder(int orderId); +``` + +Rules: + +- Methods that return `Activity?` create an Activity. +- Methods that return `void` typically add events, log, or record metrics. +- Pass the `Activity?` from the starting method to event/context methods. + +## Parameter attributes + +| Attribute | Use | +|---|---| +| `[Baggage]` | Adds the parameter to Activity baggage; also included in logs. | +| `[Tag]` | Adds the parameter as an Activity tag. | +| `[ExcludeTargets(Targets.Activities)]` | Excludes the parameter from Activity generation only. | +| `[ExpandEnumerable(maximumValueCount: N)]` | Expands an array/IEnumerable into indexed log properties. | + +## Testing + +Inject the interface in your service and mock it in tests. The generated interface has no implementation code in the interface itself, so standard mocking frameworks (NSubstitute, Moq, TUnitMocks) work directly. + +See [references/REFERENCE.md](references/REFERENCE.md) for a decision matrix and naming examples. diff --git a/.agents/skills/purview-telemetry-design/references/REFERENCE.md b/.agents/skills/purview-telemetry-design/references/REFERENCE.md new file mode 100644 index 00000000..b15cfcf0 --- /dev/null +++ b/.agents/skills/purview-telemetry-design/references/REFERENCE.md @@ -0,0 +1,101 @@ +# Design reference + +## Interface shape decision matrix + +| Situation | Recommendation | +|---|---| +| Small service with < 10 telemetry operations | One combined `ITelemetry` | +| Service only logs | `ILogs` | +| Service only traces | `ITracing` | +| Service only emits metrics | `IMetrics` | +| Large service with distinct teams owning logs vs. metrics | Split into per-area interfaces | +| Need to mock only one telemetry type in many tests | Split into per-area interfaces | + +## Naming examples + +### OpenTelemetry mode (default) + +```csharp +[ActivitySource] // name = "MyApp" +[Logger] +[Meter] +public interface IOrderServiceTelemetry +{ + [Activity] + Activity? PlacingOrder(int orderId); // activity name = "placing-order" + + [Info("Placing order {OrderId}")] + void PlacingOrderInfo(int orderId); // log + + [AutoCounter] + void OrderPlaced(); // instrument = "myapp.orders.order-placed" +} +``` + +### Legacy mode + +```csharp +[assembly: TelemetryGeneration(NamingConvention = NamingConvention.Legacy)] +``` + +Use only when exact v3 names must be preserved. + +## Multi-target example + +```csharp +[ActivitySource] +[Logger] +[Meter] +public interface IOrderServiceTelemetry +{ + // Starts Activity, logs Info, increments Counter + [Activity(ActivityKind.Internal)] + [Info("Placing order {OrderId} for {CustomerName}")] + [AutoCounter] + Activity? PlacingOrder(int orderId, string customerName, [Baggage] string region); + + // Adds event to the Activity and logs Trace + [Event] + [Trace] + void OrderValidated(Activity? activity, int orderId); + + // Records histogram + [Histogram] + void OrderProcessingTime(double latencyMs); +} +``` + +## Parameter attribute examples + +```csharp +[Activity] +[Info] +Activity? FetchingOrder( + int orderId, + [Baggage] string region, // carried in Activity baggage + [Tag] string tenantId); // Activity tag only + +[Event] +void OrderLoaded( + Activity? activity, + int orderId, + [ExcludeTargets(Targets.Activities)] string[] rawLines); // not in Activity +``` + +## Testing example + +```csharp +public class OrderServiceTests +{ + [Test] + public void PlaceOrder_EmitsTelemetry() + { + var telemetry = Substitute.For(); + var service = new OrderService(telemetry); + + service.PlaceOrder(42, "Alice", "EMEA"); + + telemetry.Received().PlacingOrder(42, "Alice", "EMEA"); + } +} +``` diff --git a/.agents/skills/purview-telemetry-diagnostics/SKILL.md b/.agents/skills/purview-telemetry-diagnostics/SKILL.md new file mode 100644 index 00000000..fec24d27 --- /dev/null +++ b/.agents/skills/purview-telemetry-diagnostics/SKILL.md @@ -0,0 +1,168 @@ +--- +name: purview-telemetry-diagnostics +description: >- + Use when a Purview.Telemetry.SourceGenerator build reports a TSG diagnostic - TSG1xxx general, + TSG2xxx logging, TSG3xxx activities, TSG4xxx metrics - to find what triggered it and how to fix it, + or when deciding whether a rule can be suppressed. +license: MIT +compatibility: C# projects using Purview.Telemetry.SourceGenerator. +metadata: + author: Purview-Dev + product: Purview.Telemetry.SourceGenerator + repository: purview-dev/telemetry-sourcegenerator +--- + +# Purview.Telemetry.SourceGenerator diagnostics + +One Roslyn analyzer, `TelemetryDiagnosticAnalyzer`, validates telemetry interfaces and raises `TSG` +diagnostics in four families: + +| Family | Covers | +| --- | --- | +| `TSG1xxx` | general — interface and method shape, targets, framework support | +| `TSG2xxx` | logging | +| `TSG3xxx` | activities | +| `TSG4xxx` | metrics | + +Every rule is tracked in `AnalyzerReleases.Shipped.md` / `AnalyzerReleases.Unshipped.md` with its ID, +category and severity, validated by the Roslyn release-tracking analyzers on every build. A new or +changed diagnostic must be recorded there in the same change. + +## General — `TSG1xxx` + +| ID | Severity | Reported when | +| --- | --- | --- | +| `TSG1000` | Error | An unexpected exception escaped the generation pipeline. | +| `TSG1001` | Error | A method on a multi-target interface has no explicit generation attribute — inference is not supported there. | +| `TSG1002` | Error | Two attributes from the same target family on one method. Only one Activity, Logging or Metrics attribute per method. | +| `TSG1003` | Error | Two methods on the interface share a name. | +| `TSG1004` | Error | Generic interfaces are not supported. | +| `TSG1005` | Error | Generic methods are not supported. | +| `TSG1006` | Warning | `ExcludeTargets` names a target not present on the method. | +| `TSG1007` | Warning | `ExcludeTargets` leaves a target with an empty or invalid parameter set. | +| `TSG1008` | Warning | An `Activity`-typed parameter on a method with no `[Activity]`/`[Event]`/`[Context]`. | +| `TSG1010` | Error | A method carries an attribute for a target family the interface does not register. | +| `TSG1011` | Error | The compilation targets neither .NET 8+ nor .NET Framework 4.8+. Define `PURVIEW_TELEMETRY_NON_NULLABLE` to opt out. | + +## Logging — `TSG2xxx` + +| ID | Severity | Reported when | +| --- | --- | --- | +| `TSG2000` | Error | A non-scoped log method has more than one `Exception` parameter. | +| `TSG2001` | Error | A v1-mode log method has more than 6 non-exception parameters. | +| `TSG2002` | Info | v1 generation inferred `Error` from a lone `Exception` parameter with no explicit level. | +| `TSG2003` | Warning | No reference to `Microsoft.Extensions.Logging.ILogger`; log generation is skipped. | +| `TSG2004` | Error | Ordinal and named placeholders mixed in one message template. | +| `TSG2005` | Error | The maximum ordinal placeholder exceeds the parameter count. | +| `TSG2006` | Error | `[LogProperties]` and `[ExpandEnumerable]` on the same parameter. | +| `TSG2007` | Warning | A scoped log declares a `LogLevel`; it is ignored. | +| `TSG2008` | Warning | `[ExpandEnumerable]` has a `MaximumValueCount` above the recommended default of 5. | +| `TSG2021` | Error | A log method returns something other than `void` or `IDisposable`. (`Activity` is allowed when the method is also an Activity method.) | + +## Activities — `TSG3xxx` + +| ID | Severity | Reported when | +| --- | --- | --- | +| `TSG3000` | Warning | A baggage parameter is not a string; `ToString()` will be called. | +| `TSG3001` | Warning | No activity source name available anywhere; generation defaults to `purview`. | +| `TSG3002` | Error | An Activity/Event method returns something other than `void` or `Activity`. | +| `TSG3003` | Error | More than one parameter maps to the same reserved destination. | +| `TSG3004` | Error | An `Activity`-destination parameter on an Activity method — only valid on `[Event]`. | +| `TSG3005` | Error | A `timestamp` parameter on a method that is not `[Event]`. | +| `TSG3006` | Error | A start-time parameter on a Create-activity or Event method. | +| `TSG3007` | Error | A parent-context or parent-id parameter on an event. | +| `TSG3008` | Error | Activity-links parameters on an event or context method. | +| `TSG3009` | Error | An activity-tags parameter on a context method. | +| `TSG3010` | Error | An escaped parameter is not a boolean. | +| `TSG3011` | Error | Escaped parameters on an Activity or Context method — Events only. | +| `TSG3012` | Info | No Activity methods defined; `Activity.Current` is assumed. | +| `TSG3013` | Warning | An Activity method does not return the created `Activity`. | +| `TSG3014` | Warning | An Event/Context method has no `Activity` parameter. Controlled by `ActivitySourceGeneration.GenerateDiagnosticsForMissingActivity` (default `true`). | +| `TSG3015` | Info | `Activity` should be the first parameter. Same opt-in as `TSG3014`. | +| `TSG3016` | Error | A status-description parameter is not a string. | +| `TSG3017` | Error | Status-description parameters on an Activity or Context method — Events only. | +| `TSG3021` | Info | An `[Event]` records an exception under the OpenTelemetry rules but is not named `"exception"`. | +| `TSG3022` | Warning | An Activity method returns non-nullable `Activity`. | + +## Metrics — `TSG4xxx` + +| ID | Severity | Reported when | +| --- | --- | --- | +| `TSG4000` | Error | A method on a Metrics interface has no instrument attribute and is not excluded. | +| `TSG4001` | Error | A metrics-owned method returns something other than `void` or `bool`. | +| `TSG4002` | Error | An auto-increment instrument also declares a measurement parameter. | +| `TSG4003` | Error | More than one measurement value. | +| `TSG4004` | Error | A non-auto-increment instrument method has no measurement parameter. | +| `TSG4005` | Error | An observable instrument is not declared as `Func`. | +| `TSG4006` | Error | The measurement type is not `byte`, `short`, `int`, `long`, `double`, `float`, `decimal`, `Measurement` or `IEnumerable>`. | +| `TSG4007` | Error | An observable metric returns `bool`. | +| `TSG4008` | Error | An `AutoCounter` does not return `void`. | +| `TSG4009` | Warning | The instrument name matches the instrument type name. Name what is measured, not the instrument. | + +## The ones people actually hit + +### `TSG1001` — inference is off on a multi-target interface + +A method on an interface carrying `[ActivitySource]` + `[Logger]` + `[Meter]` has no explicit +attribute. Add one per target the method should emit, or mark it `[Exclude]`: + +```csharp +[ActivitySource("MyApp")] +[Logger] +[Meter] +interface IMyTelemetry +{ + [Info] // explicit target + void ProcessItem(int id); +} +``` + +### `TSG3013` / `TSG3014` — the Activity went missing + +Return the created `Activity` (as `Activity?`, per `TSG3022` — it is null when no listeners are +active) and pass it into the Event and Context methods that should attach to it. Both are +best-practice rules controlled by `ActivitySourceGeneration.GenerateDiagnosticsForMissingActivity`. + +### `TSG3021` — exception event name + +Name the event `exception` so the OpenTelemetry exception tags (`exception.type`, +`exception.message`, `exception.stacktrace`, `exception.escaped`) attach to *that* event rather than +a separate one: + +```csharp +[Event(Name = "exception")] // the event carries the exception tags +void FailedToRetrieve(Activity? activity, Exception exception); +``` + +A `Name` on a **logging** attribute does not name the event — it renames the log entry: + +```csharp +[Event] // event name is still the method name +[Error(Name = "exception")] // this renames the log entry +void FailedToRetrieve(Activity? activity, Exception exception); +``` + +The rule is not raised when the exception is not recorded under the OpenTelemetry rules: +`[Event(UseRecordExceptionRules = false)]`, a `[Baggage]` exception parameter, or an exception +parameter excluded from the Activities target (`[ExcludeTargets(Targets.Activities)]`). + +### `TSG2008` — unbounded enumeration + +`[ExpandEnumerable]` with `MaximumValueCount` above 5. Bring it back to the default unless you have +measured the cost. + +### `TSG4002` — auto-increment counter with a measurement + +`[AutoCounter]` — equivalently `[Counter(AutoIncrement = true)]` — must declare no measurement +parameter. The measurement is fixed at 1. + +### `TSG1003` — duplicate method names + +The method name becomes a member on the generated implementation class, so two methods cannot share +one. Rename. + +## Related skills + +`purview-telemetry-quickstart` to get an interface wired up, `purview-telemetry-design` for +structuring interfaces, and `purview-telemetry-migration` for converting existing `ILogger`, +`ActivitySource` or instrument code. diff --git a/.agents/skills/purview-telemetry-migration/SKILL.md b/.agents/skills/purview-telemetry-migration/SKILL.md new file mode 100644 index 00000000..b9a01fad --- /dev/null +++ b/.agents/skills/purview-telemetry-migration/SKILL.md @@ -0,0 +1,81 @@ +--- +name: purview-telemetry-migration +description: Migrate existing ILogger, ActivitySource, or System.Diagnostics.Metrics instrument code to Purview.Telemetry.SourceGenerator interfaces. Use when converting hand-written telemetry to generated telemetry interfaces, or when a user wants to replace ILogger, ActivitySource, or Counter/Histogram/UpDownCounter usage with Purview telemetry. +license: MIT +compatibility: C# projects using Purview.Telemetry.SourceGenerator. +metadata: + author: Purview-Dev + version: "1.0" +--- + +# Migrate to Purview Telemetry Source Generator + +Convert existing telemetry code to generated Purview telemetry interfaces. + +## Primary path: use the IDE refactorings + +The source generator ships with Roslyn code refactorings. Right-click a class containing hand-written telemetry and choose: + +- **Convert ILogger to ILogs** — replaces `ILogger` fields and constructor parameters with a generated logging interface. +- **Convert ActivitySource to ITracing** — replaces `ActivitySource` fields and `StartActivity` calls with a generated tracing interface. +- **Convert Metrics to IMetrics** — replaces `Counter`, `Histogram`, and `UpDownCounter` fields and calls with a generated metrics interface. +- **Convert all telemetry to ITelemetry** — combines all three into one interface when the class uses multiple telemetry types. + +Each refactoring offers scopes: **class**, **document**, **project**, and **solution**. + +## What the refactorings produce + +The generated interface uses attributes from the `Purview.Telemetry` namespace: + +```csharp +using Purview.Telemetry; + +[Logger] +public interface IOrderServiceLogs +{ + [Info] + void OrderPlaced(int orderId, string customerName); +} +``` + +The original class is rewritten to use the interface: + +```csharp +public class OrderService(IOrderServiceLogs logger) +{ + public void PlaceOrder(int orderId, string customerName) + { + logger.OrderPlaced(orderId, customerName); + } +} +``` + +## Manual fallback + +If the refactoring does not cover a call pattern, convert it manually: + +1. Identify the telemetry type (Logging, Activity, Metric). +2. Create a new interface with the matching class-level attribute (`[Logger]`, `[ActivitySource]`, `[Meter]`). +3. Add a method for each distinct operation, using the method-level attribute from the mapping below. +4. Replace the hand-written call with the interface method. +5. Register the interface in DI with `services.Add{InterfaceNameWithoutI}()`. + +## Attribute mapping + +| Hand-written telemetry | Generated attribute | +|---|---| +| `ILogger.LogInformation(...)` | `[Info]` | +| `ILogger.LogDebug(...)` | `[Debug]` | +| `ILogger.LogTrace(...)` | `[Trace]` | +| `ILogger.LogWarning(...)` | `[Warning]` | +| `ILogger.LogError(...)` | `[Error]` | +| `ILogger.LogCritical(...)` | `[Critical]` | +| `ActivitySource.StartActivity(...)` | `[Activity]` | +| `activity.AddEvent(...)` | `[Event]` | +| `activity.AddBaggage(...)` / `SetBaggage(...)` | `[Context]` with `[Baggage]` parameter | +| `activity.SetTag(...)` | `[Context]` with `[Tag]` parameter | +| `Counter.Add(...)` | `[Counter]` or `[AutoCounter]` for `Add(1)` | +| `Histogram.Record(...)` | `[Histogram]` | +| `UpDownCounter.Add(...)` | `[UpDownCounter]` | + +See [references/REFERENCE.md](references/REFERENCE.md) for detailed before/after examples and common conversions. diff --git a/.agents/skills/purview-telemetry-migration/references/REFERENCE.md b/.agents/skills/purview-telemetry-migration/references/REFERENCE.md new file mode 100644 index 00000000..d85eb738 --- /dev/null +++ b/.agents/skills/purview-telemetry-migration/references/REFERENCE.md @@ -0,0 +1,181 @@ +# Migration reference + +Detailed before/after examples for migrating hand-written telemetry to Purview telemetry interfaces. + +## ILogger to generated logging interface + +### Before + +```csharp +using Microsoft.Extensions.Logging; + +public class OrderService(ILogger logger) +{ + public void PlaceOrder(int orderId, string customerName) + { + logger.LogInformation("Placing order {OrderId} for {CustomerName}", orderId, customerName); + } + + public void CancelOrder(int orderId, Exception ex) + { + logger.LogError(ex, "Order {OrderId} cancelled", orderId); + } +} +``` + +### After + +```csharp +using Purview.Telemetry; + +[Logger] +public interface IOrderServiceLogs +{ + [Info("Placing order {OrderId} for {CustomerName}")] + void OrderPlaced(int orderId, string customerName); + + [Error("Order {OrderId} cancelled")] + void OrderCancelled(Exception ex, int orderId); +} + +public class OrderService(IOrderServiceLogs logger) +{ + public void PlaceOrder(int orderId, string customerName) + { + logger.OrderPlaced(orderId, customerName); + } + + public void CancelOrder(int orderId, Exception ex) + { + logger.OrderCancelled(ex, orderId); + } +} +``` + +## ActivitySource to generated tracing interface + +### Before + +```csharp +using System.Diagnostics; + +public class OrderService +{ + static readonly ActivitySource _source = new("OrderService"); + + public void PlaceOrder(int orderId) + { + using var activity = _source.StartActivity("PlaceOrder", ActivityKind.Internal); + activity?.AddEvent(new ActivityEvent("Validated")); + } +} +``` + +### After + +```csharp +using System.Diagnostics; +using Purview.Telemetry; + +[ActivitySource] +public interface IOrderServiceTracing +{ + [Activity] + Activity? PlaceOrder(int orderId); + + [Event] + void Validated(Activity? activity); +} + +public class OrderService(IOrderServiceTracing tracing) +{ + public void PlaceOrder(int orderId) + { + using var activity = tracing.PlaceOrder(orderId); + tracing.Validated(activity); + } +} +``` + +## Metrics to generated metrics interface + +### Before + +```csharp +using System.Diagnostics.Metrics; + +public class OrderService(IMeterFactory meterFactory) +{ + readonly Counter _orders = meterFactory.Create("OrderService").CreateCounter("orders-placed"); + readonly Histogram _latency = meterFactory.Create("OrderService").CreateHistogram("processing-latency-ms"); + + public void PlaceOrder(int orderId, double latencyMs) + { + _orders.Add(1); + _latency.Record(latencyMs); + } +} +``` + +### After + +```csharp +using Purview.Telemetry; + +[Meter] +public interface IOrderServiceMetrics +{ + [AutoCounter] + void OrderPlaced(); + + [Histogram] + void OrderProcessingTime(double latencyMs); +} + +public class OrderService(IOrderServiceMetrics metrics) +{ + public void PlaceOrder(int orderId, double latencyMs) + { + metrics.OrderPlaced(); + metrics.OrderProcessingTime(latencyMs); + } +} +``` + +## Combined telemetry interface + +When a class uses multiple telemetry types, prefer the combined refactoring: + +```csharp +using System.Diagnostics; +using Purview.Telemetry; + +[ActivitySource] +[Logger] +[Meter] +public interface IOrderServiceTelemetry +{ + [Activity] + [Info] + [AutoCounter] + Activity? PlacingOrder(int orderId); + + [Event] + void OrderShipped(Activity? activity, int orderId); + + [Histogram] + void OrderProcessingTime(double latencyMs); +} +``` + +## Common conversions + +| Original code | Generated method signature | +|---|---| +| `logger.LogError(ex, "Failed {OrderId}", orderId)` | `[Error("Failed {OrderId}")] void Failed(Exception exception, int orderId);` | +| `activity.AddEvent(new ActivityEvent("Loaded"))` | `[Event] void Loaded(Activity? activity);` | +| `activity.SetBaggage("tenant", tenantId)` | `[Context] void SetTenant(Activity? activity, [Baggage] string tenantId);` | +| `activity.SetTag("tenant", tenantId)` | `[Context] void SetTenant(Activity? activity, [Tag] string tenantId);` | +| `counter.Add(1, new KeyValuePair("region", region))` | `[AutoCounter] void RequestCompleted([Tag] string region);` | +| `histogram.Record(value, new KeyValuePair("region", region))` | `[Histogram] void RequestDuration(long value, [Tag] string region);` | +| `upDownCounter.Add(1)` | `[UpDownCounter] void Increment();` | diff --git a/.agents/skills/purview-telemetry-multi-targeting/SKILL.md b/.agents/skills/purview-telemetry-multi-targeting/SKILL.md new file mode 100644 index 00000000..d9654ab9 --- /dev/null +++ b/.agents/skills/purview-telemetry-multi-targeting/SKILL.md @@ -0,0 +1,224 @@ +--- +name: purview-telemetry-multi-targeting +description: >- + Use when one Purview.Telemetry.SourceGenerator method should emit several kinds of telemetry at + once - an Activity, a log entry and a metric from a single call. Covers combining [ActivitySource], + [Logger] and [Meter] on an interface, the supported per-method attribute combinations, excluding a + parameter from one target with [ExcludeTargets], return types, and why inference turns off. +license: MIT +compatibility: C# projects using Purview.Telemetry.SourceGenerator. +metadata: + author: Purview-Dev + product: Purview.Telemetry.SourceGenerator + repository: purview-dev/telemetry-sourcegenerator +--- + +# Multi-targeting + +One interface — and one *method* — can generate Activities, logs and metrics together. A single call +then emits all of them, from one set of parameters. + +```csharp +using Purview.Telemetry; + +[ActivitySource("OrderService")] +[Logger] +[Meter] +interface IOrderTelemetry +{ + // Activity + Info log + counter increment, from one call. + [Activity] + [Info] + [AutoCounter] + Activity? ProcessingOrder([Baggage] int orderId, [Tag] string customerName); + + // ActivityEvent + Debug log. + [Event] + [Debug] + void OrderValidated(Activity? activity, decimal amount); + + // Log only. + [Warning] + void OrderRejected(int orderId, string reason); + + // Metric only. + [Histogram] + void OrderProcessingDuration([InstrumentMeasurement] int milliseconds); +} +``` + +```csharp +using var activity = telemetry.ProcessingOrder(123, "Acme Corp"); +// Activity created and started, Info log written, counter incremented by 1. +``` + +## What you may combine + +| Combination | Example | +| --- | --- | +| Activity + Log | `[Activity]` + `[Info]` | +| Activity + Metric | `[Activity]` + `[AutoCounter]` | +| Log + Metric | `[Info]` + `[Histogram]` | +| Activity + Log + Metric | `[Activity]` + `[Info]` + `[AutoCounter]` | +| Event + Log | `[Event]` + `[Debug]` | +| Context + Log | `[Context]` + `[Trace]` | + +**One attribute per family, per method** — more is `TSG1002`: + +- Activities: one of `[Activity]`, `[Event]`, `[Context]`. +- Logging: one of `[Log]`, `[Trace]`, `[Debug]`, `[Info]`, `[Warning]`, `[Error]`, `[Critical]`. +- Metrics: one of `[Counter]`, `[AutoCounter]`, `[Histogram]`, `[UpDownCounter]`, or an observable + variant. + +```csharp +[Activity] +[Event] // TSG1002 +void InvalidMethod(Activity? activity); + +[Counter] +[Histogram] // TSG1002 +void InvalidMethod([InstrumentMeasurement] int value); +``` + +## Inference turns off — and that is the point + +An interface with **more than one** class-level attribute (`[ActivitySource]`, `[Logger]`, `[Meter]`) +disables inference. Every method must then declare its targets explicitly, or be `[Exclude]`d: + +```csharp +[ActivitySource("MyApp")] +[Logger] +[Meter] +interface IMyTelemetry +{ + void ProcessItem(int id); // TSG1001 - no explicit attribute + + [Info] + void ProcessItemLogged(int id); // fine + + [Exclude] + void NotTelemetry(int id); // fine +} +``` + +A single-target interface keeps inference. The alternative — guessing which of three families an +unannotated method meant — would silently emit the wrong telemetry, so the generator refuses. + +## Excluding a parameter from one target + +`[ExcludeTargets(Targets.X)]` on a parameter keeps it out of specific families. Use it when a value +is useful in one place and harmful in another — a verbose message is wasted as a metric tag, and an +internal reference may not belong in Activity baggage: + +```csharp +[ActivitySource("PaymentService")] +[Logger] +[Meter] +interface IPaymentTelemetry +{ + [Activity] + [Info] + [Counter] + Activity? ProcessingPayment( + [Baggage] Guid paymentId, + + [ExcludeTargets(Targets.Metrics)] + string processingMessage, + + [InstrumentMeasurement] + decimal amount, + + [ExcludeTargets(Targets.Activities)] + [Tag] // still in logs and metrics + string internalReference + ); +} +``` + +```csharp +[Flags] +public enum Targets +{ + None = 0, + Activities = 1, + Logging = 2, + Metrics = 4, + All = Activities | Logging | Metrics +} +``` + +Flags combine, so `[ExcludeTargets(Targets.Activities | Targets.Metrics)]` leaves a parameter to +logging alone. + +## Return types + +| Shape | Return | +| --- | --- | +| Activity + anything else | `Activity?` — so the caller can dispose it and pass it to Event/Context methods | +| Log + Metric, no Activity | `void`, or `IDisposable?` for a scoped log | +| Event/Context + Log | `void` | + +```csharp +[Activity] +[Info] +[AutoCounter] +Activity? ProcessingOrder(int orderId); + +[Info] +[AutoCounter] +IDisposable? ProcessingBatch(int batchId); // scoped log + counter + +[Event] +[Debug] +void OrderCompleted(Activity? activity, decimal total); +``` + +Return `Activity?`, not `Activity`: it is null when no listeners are active (`TSG3022`). + +## Patterns worth copying + +Full observability on one call: + +```csharp +[Activity] +[Info] +[AutoCounter] +Activity? ProcessingRequest( + [Baggage] string requestId, + [Tag] string endpoint, + [Tag] string method +); +``` + +Selective parameter routing: + +```csharp +[Activity] +[Info] +[Counter] +Activity? ApiCall( + [Baggage] string traceId, // Activity baggage only + [ExcludeTargets(Targets.Metrics)] string verboseMessage, // Activity + log + [InstrumentMeasurement] + [ExcludeTargets(Targets.Activities | Targets.Logging)] + int callCount, // metrics only + [Tag] string endpoint // all three +); +``` + +## Why bother + +One method definition instead of three call sites; the same parameters feed every family, so they +cannot drift; everything is emitted together; a change lands once; and it is one call rather than +several. + +## Diagnostics you will meet here + +| Diagnostic | Fix | +| --- | --- | +| `TSG1001` | Add an explicit target attribute, or `[Exclude]`. | +| `TSG1002` | One Activity, Logging and Metrics attribute per method. | +| `TSG1006` | `[ExcludeTargets]` names a target the method does not have — remove it, or add the target attribute. | +| `TSG1007` | Exclusions left a target with no valid parameters — adjust them. | + +The `purview-telemetry-diagnostics` skill carries the full `TSG` catalogue. diff --git a/.agents/skills/purview-telemetry-quickstart/SKILL.md b/.agents/skills/purview-telemetry-quickstart/SKILL.md new file mode 100644 index 00000000..1743ffe3 --- /dev/null +++ b/.agents/skills/purview-telemetry-quickstart/SKILL.md @@ -0,0 +1,140 @@ +--- +name: purview-telemetry-quickstart +description: Get started with Purview.Telemetry.SourceGenerator in a C# project. Use when adding the package, creating a first telemetry interface, registering it in DI, or asking how to begin with Purview telemetry. +license: MIT +compatibility: C# projects using Purview.Telemetry.SourceGenerator. +metadata: + author: Purview-Dev + version: "1.0" +--- + +# Quickstart: Purview Telemetry Source Generator + +This skill helps you bootstrap telemetry generation in a C# project using `Purview.Telemetry.SourceGenerator`. + +## Installation + +Add the analyzer package to your project: + +```xml + + all + analyzers + +``` + +Also add runtime dependencies for the telemetry types you use: + +- `System.Diagnostics.DiagnosticSource` for Activities +- `Microsoft.Extensions.Logging.Abstractions` for ILogger +- `System.Diagnostics.Metrics` for metrics (built-in on .NET 6+) + +## Define a telemetry interface + +Create a `public interface` and decorate it with class-level attributes. The generator creates the implementation and a DI registration extension. + +### Single-target examples + +```csharp +using Purview.Telemetry; + +[Logger] +public interface IOrderServiceLogs +{ + [Info] + void OrderPlaced(int orderId, string customerName); + + [Warning] + void OrderNotFound(int orderId); +} +``` + +```csharp +[ActivitySource] +public interface IOrderServiceTracing +{ + [Activity] + Activity? PlacingOrder(int orderId); + + [Event] + void OrderValidated(Activity? activity, int orderId); +} +``` + +```csharp +[Meter] +public interface IOrderServiceMetrics +{ + [Counter] + void OrderPlaced(int itemsInOrder); + + [Histogram] + void OrderProcessingTime(long milliseconds); +} +``` + +### Multi-target example + +One interface can generate Activities, Logging, and Metrics from the same methods: + +```csharp +[ActivitySource] +[Logger] +[Meter] +public interface IOrderServiceTelemetry +{ + [Activity] + [Info] + [AutoCounter] + Activity? PlacingOrder(int orderId, [Baggage] string region); + + [Event] + [Trace] + void OrderProcessed(Activity? activity, long durationMs); + + [Warning] + void OrderFailed(int orderId, Exception exception); +} +``` + +## Register with DI + +The generator creates an extension method named `Add{InterfaceNameWithoutI}()`: + +```csharp +services.AddOrderServiceTelemetry(); +``` + +Inject the interface into your service: + +```csharp +public class OrderService(IOrderServiceTelemetry telemetry) +{ + public void PlaceOrder(int orderId) + { + using var activity = telemetry.PlacingOrder(orderId, "EMEA"); + // ... + telemetry.OrderProcessed(activity, stopwatch.ElapsedMilliseconds); + } +} +``` + +## Register names with OpenTelemetry + +The generator records the generated meter and activity source names in every assembly's metadata via `[assembly: GeneratedTelemetryNames]`. In the project that registers them with OpenTelemetry, opt into the `TelemetryNames` class — it aggregates that project's names with the names recorded by every assembly it references: + +```csharp +// Program.cs or Properties/AssemblyInfo.cs of the host project +[assembly: TelemetryGeneration(GenerateTelemetryNamesClass = true)] +``` + +```csharp +builder.AddServiceDefaults(TelemetryNames.MeterNames, TelemetryNames.ActivitySourceNames); +``` + +Libraries need no configuration: they publish their names through the attribute, and the host picks them up. A project referenced *by* the telemetry owners (an Aspire-style `ServiceDefaults`) cannot aggregate them — generate the class in the host and pass the arrays down. + +## Next steps + +- To migrate existing `ILogger`, `ActivitySource`, or metrics code, use `telemetry-sourcegenerator-migration`. +- For design guidance and best practices, use `telemetry-sourcegenerator-design`. diff --git a/.agents/skills/purview-value-objects-diagnostics/SKILL.md b/.agents/skills/purview-value-objects-diagnostics/SKILL.md new file mode 100644 index 00000000..8d03cf03 --- /dev/null +++ b/.agents/skills/purview-value-objects-diagnostics/SKILL.md @@ -0,0 +1,85 @@ +--- +name: purview-value-objects-diagnostics +description: >- + Use when a Purview.ValueObjects build reports a VO1xxx diagnostic, when deciding whether to + suppress one, or when adding a new analyzer rule to the value-objects source generator and its + AnalyzerReleases tracking files. +metadata: + product: Purview.ValueObjects + repository: purview-dev/value-objects +--- + +# Purview.ValueObjects diagnostics + +`Purview.ValueObjects` ships a Roslyn analyzer and source generator that report the `VO1xxx` rules +below. Every rule is enabled by default. + +Suppress a warning the usual ways — `#pragma warning disable VO1006`, a `NoWarn` entry, or +`dotnet_diagnostic.VO1006.severity = none` in `.editorconfig`. **Errors cannot be downgraded**: they +mark declaration shapes the generator cannot emit code for at all, so silencing one only moves the +failure to the missing member. + +## Core shape rules + +| Rule | Severity | Reported when | Fix | +| --- | --- | --- | --- | +| `VO1001` | Error | A `[Scalar]` or `[ValueObject]` type is not declared `partial`. | Add `partial`. The code fix in `Purview.ValueObjects.SourceGenerator.Refactorings` does it for you. | +| `VO1002` | Error | The value object is nested inside another type. | Move it to its own top-level type; nesting is not supported. | +| `VO1003` | Error | The value object is generic. | Remove the type parameters, or declare one concrete value object per closed type. | +| `VO1004` | Error | A `[Scalar]` type does not declare the configured scalar property. | Declare it, or set `ScalarAttribute.PropertyName` to the one you have. | +| `VO1006` | Warning | A `[Scalar]` type is not a `readonly record struct`. | Prefer `readonly record struct`, so equality, immutability and allocation behaviour match the contract. | +| `VO1007` | Warning | `ValueObjectDeserializationMode.Strict` is set but no `Create` overload exists to re-validate through. | Add the `Create` overload, or use the default `Hydrate` mode. | +| `VO1008` | Error | `[Scalar]` and `[ValueObject]` are both applied to one type. | Pick one: a scalar wraps a single primitive, a value object composes members. | +| `VO1016` | Warning | A value object member is mutable. | Make it `readonly`/`init`-only — a mutable member breaks immutability and makes equality unstable. | +| `VO1022` | Error | A `[Scalar]` type declares a member with the name of the property the generator owns. | Remove the declaration, or use `[Scalar]` without a type argument and own the property yourself. | + +## String normalization rules + +| Rule | Severity | Reported when | Fix | +| --- | --- | --- | --- | +| `VO1023` | Warning | Built-in string normalization is configured but the type implements `OnNormalize` or declares its own `Create`. | Remove the option, or move the normalization into the hook/`Create`. The hand-written path wins either way. | +| `VO1024` | Warning | Built-in string normalization is configured on a non-string scalar or member. | Remove the option; `Trim`/`Casing` apply only to `string`. | +| `VO1025` | Error | `[StringNormalize]` is on a member of a `[Scalar]`, on a type that is neither `[Scalar]` nor `[ValueObject]`, or on a property that is not a value member. | Move it to a string member of a complex `[ValueObject]`; on a scalar set `Trim`/`Casing` on `[Scalar]`. | +| `VO1026` | Error | An author-declared `[assembly: ValueObjectDefaults]` repeats a value already supplied by the packaged targets from `ValueObjectsDefault*` MSBuild properties. | Remove the argument, or set a different value. | +| `VO1027` | Error | A `[Scalar]`/`[ValueObject]` option repeats the effective assembly default. | Remove the option; it repeats the inherited value. | + +Restating an assembly or type default is reported as `VO1026`/`VO1027` so each option has a single source of +truth. Only `[StringNormalize]` remains a per-member override outside that check; a value that changes the +effective configuration still raises `VO1023`/`VO1024` where those rules apply. + +## ZodSharp validation rules + +| Rule | Severity | Reported when | Fix | +| --- | --- | --- | --- | +| `VO1013` | Warning | `OnValidate` is declared but never invoked, because `ZodSchemaMode.InsteadOfHooks` is set. | Remove `OnValidate`, or choose a mode that keeps the hooks (`InAdditionToHooks`). | +| `VO1015` | Error | The ZodSharp `SchemaName` is not a valid C# identifier. | Give it a valid identifier. | + +## Entity Framework rules + +| Rule | Severity | Reported when | Fix | +| --- | --- | --- | --- | +| `VO1009` | Warning | EF mapping is requested but `Microsoft.EntityFrameworkCore` is not referenced. | Add the package reference, or stop requesting EF mapping. | +| `VO1010` | Warning | EF auto-conversion was skipped: the underlying type is not mappable. | Map it by hand with a custom `ValueConverter`. | +| `VO1017` | Warning | EF JSON mapping is requested without the JSON converter. | Register the JSON converter for the value object. | +| `VO1018` | Warning | EF complex mapping cannot convert one of the members. | Simplify the member, or map it explicitly. | +| `VO1019` | Warning | EF complex-type mapping is requested but the project resolves to EF Core 7 or earlier. | Target EF Core 8+, or choose a different `EntityFrameworkMapping`. | +| `VO1021` | Warning | EF key value generation is unavailable for the value object. | Assign keys explicitly rather than relying on store generation. | + +## Retired identifiers — never reused + +`VO1005`, `VO1011`, `VO1012`, `VO1014` and `VO1020` were used during development and withdrawn before +release. No version reports them, and the numbering is intentionally discontinuous. An occurrence of +one of these IDs means stale tooling or a stale suppression: remove it. + +`VO1005` is worth calling out. It was catalogued as an error ("scalar constructor is missing") and +documented as requiring you to declare a constructor. It never had a reporting site, and the +requirement was the **opposite** of how the generator works: when a `[Scalar]` type declares no +constructor taking the underlying type, the generator emits a private one. Nothing ever asked you to +write it. + +## Adding or changing a rule + +Rules are tracked in `src/src/SourceGenerator/AnalyzerReleases.Shipped.md` and +`AnalyzerReleases.Unshipped.md`, which Roslyn's `RS2008` catalogue rule enforces. A new or changed +diagnostic must be recorded in the same change; unshipped entries move into a new +`## Release ` block when that version ships. Never reuse a retired identifier. diff --git a/.agents/skills/purview-value-objects-efcore/SKILL.md b/.agents/skills/purview-value-objects-efcore/SKILL.md new file mode 100644 index 00000000..cb57c121 --- /dev/null +++ b/.agents/skills/purview-value-objects-efcore/SKILL.md @@ -0,0 +1,277 @@ +--- +name: purview-value-objects-efcore +description: >- + Use when persisting Purview.ValueObjects with Entity Framework Core - ConfigureValueObjects, + UseValueObjects, scalar-to-column conversion, complex-type versus JSON mapping, value objects as + keys and foreign keys, query translation, generated key values, migrations, and the VO1009-VO1021 + Entity Framework diagnostics. +metadata: + product: Purview.ValueObjects + repository: purview-dev/value-objects +--- + +# Value objects and Entity Framework Core + +`Purview.ValueObjects` source-generates the EF Core mapping **into the consuming project**, and only +when that project references `Microsoft.EntityFrameworkCore`. The runtime package itself carries no +EF dependency, so a domain assembly stays free of Entity Framework while the persistence assembly +gets the converters, comparers and conventions. + +Everything is opt-in per feature with a three-level opt-out: the `DisableValueObjectsEFGeneration` +MSBuild property, then assembly defaults (the attribute, or the `ValueObjectsDefaultEFMapping`, +`ValueObjectsDefaultGenerateEFConverter`, `ValueObjectsDefaultGenerateEFComparer` and +`ValueObjectsDefaultGenerateEFValueGenerator` properties), then per-type options. + +## Wiring it up + +Two ways, pick one: + +```csharp +// 1. In the context. +protected override void OnModelCreating(ModelBuilder modelBuilder) +{ + modelBuilder.ConfigureValueObjects(); +} +``` + +```csharp +// 2. At registration - no OnModelCreating override needed. +services.AddDbContext(options => + options.UseSqlServer(connectionString).UseValueObjects()); + +services.AddDbContextFactory(options => + options.UseSqlite("Data Source=shop.db").UseValueObjects()); +``` + +`ConfigureValueObjects` is emitted into the `Microsoft.EntityFrameworkCore` namespace — the same +namespace as `ModelBuilder` — so no extra `using` is needed. `UseValueObjects()` registers a +generated `ModelCustomizer` that runs it after `OnModelCreating`, and works for `AddDbContext`, +`AddDbContextFactory`, `AddDbContextPool` and manual construction. + +## What gets mapped + +| Shape | Maps to | Notes | +| --- | --- | --- | +| `[Scalar]` | one column of the underlying primitive | via `{Type}.EF.Converter` + `ValueComparer`; `EmailAddress` is a `TEXT` column | +| `[ValueObject]` (default) | an EF Core complex type — one column per member | EF Core 8+ only; nested scalars convert too | +| `[ValueObject(EFMapping = EntityFrameworkMapping.Json)]` | a single JSON column | a value converter, so it works on every EF Core version | + +The provider-to-model direction always goes through `Hydrate(...)`. **Materialization is a replay +path**: neither `OnValidate` nor a ZodSharp schema runs when a row is read. That matches +`ValueObjectDeserializationMode.Hydrate`, and `Strict` applies to the JSON wire format, not to the +database — validate before persisting, or enforce the invariant in the schema. + +An enum-backed scalar converts through the enum's **integral** type (`ValueConverter`). +Leaving the enum as the provider type makes EF compose its own enum-to-number converter with the +generated one, and the composite loses the provider tolerance that raw-primitive comparisons rely on. + +A plain `enum` property that is not a value object keeps EF Core's own enum mapping, untouched. + +## Querying — no `.Value` + +Because a scalar converts to its primitive column, a predicate compares the value object directly: + +```csharp +EmailAddress email = EmailAddress.Create("demo@example.com"); + +var customers = await db.Customers + .Where(c => c.Email == email) // translates to [email] = @p + .ToListAsync(); +``` + +Complex value objects map as complex types, so their members are queryable: + +```csharp +var orders = await db.Orders + .Where(o => o.Total.Amount > 20m) + .Where(o => o.Total.Currency == CurrencyCode.Create("USD")) + .ToListAsync(); +``` + +A property may also be compared to the **raw underlying value** — `c.Email == "demo@example.com"`, +`m.Id == guid` — because every generated converter accepts either shape. Without that, EF hands the +raw provider value to the converted property's built-in converter, which coerces with +`Convert.ChangeType` and throws for provider types that do not implement `IConvertible` (`Guid`, +`DateTimeOffset`, `TimeSpan`, `DateOnly`, `TimeOnly`) or cannot be converted at all (strings). See +[dotnet/efcore#32030](https://github.com/dotnet/efcore/issues/32030). + +Compiled models (`dotnet ef dbcontext optimize`) keep that tolerance because every generated +converter exposes a `JsonValueReaderWriter`-taking constructor and a `JsonReaderWriter` property, +which is what EF's design-time generator looks for. That detection is an undocumented EF +implementation detail: if it changes, compiled models fall back to the built-in converter and only +raw-primitive comparisons break. + +## Keys, foreign keys and indexes + +A value object key needs no special handling — the converter maps it to its primitive column, and +convention still makes `{Type}Id` the primary key: + +```csharp +sealed class Customer +{ + public CustomerId Id { get; set; } // primary key, stored as uniqueidentifier + public TenantId TenantId { get; set; } // foreign key to Tenant.Id + public Tenant Tenant { get; set; } = default!; +} +``` + +Column facets are configured on the value object property and apply to the converted column, exactly +as for a primitive: + +```csharp +public sealed class TenantConfiguration : IEntityTypeConfiguration +{ + public void Configure(EntityTypeBuilder builder) + { + builder.Property(entity => entity.Id).ValueGeneratedNever(); // when the domain owns the key + builder.Property(entity => entity.Key).HasMaxLength(100).IsRequired(); + builder.HasIndex(entity => new { entity.TenantId, entity.Key }).IsUnique(); + } +} +``` + +The converter is expression-based, so composite indexes, unique constraints and `HasQueryFilter` +behave like their primitive equivalents: + +```csharp +modelBuilder.Entity().HasQueryFilter(invoice => invoice.TenantId == currentTenant.TenantId); +``` + +**Complex types cannot be keys.** An identity spanning two or more members is awkward as a complex +type: either flatten the members onto the entity and put a unique index over them, or store the +value object as JSON and index the derived columns you actually query. + +## Generated key values + +A Guid-backed scalar can generate its own time-ordered keys without a database round trip. Opt in, +register one convention, and pick the ordering the store needs: + +```csharp +[Scalar(GenerateEFValueGenerator = true)] +public readonly partial record struct CustomerId { public Guid Value { get; } } + +protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder) +{ + base.ConfigureConventions(configurationBuilder); + configurationBuilder.UseValueObjectKeyGenerators(); // version 7 + // configurationBuilder.UseValueObjectKeyGenerators(ValueObjectKeyOrdering.SqlServer); +} +``` + +Ordering matters: SQL Server's `uniqueidentifier` compares the trailing six bytes first, so plain +version 7 values are effectively random there and a clustered key fragments. Full detail — the +ordering table, the public `ValueObjectSequentialGuid` helper, and the rules about when EF invokes a +generator — is in [references/key-value-generation.md](references/key-value-generation.md). + +Value generation is Guid-backed scalars only, and requires the EF converter; anywhere else reports +`VO1021`. + +## Value objects in other assemblies + +| Declaring assembly | What it emits | How the consumer discovers it | +| --- | --- | --- | +| References EF Core | a nested `EF` class and an `IEFScalarValueObject`/`IEFComplexValueObject` marker per type | through the marker interfaces | +| Does **not** reference EF Core | nothing EF-related | through the `[Scalar]`/`[ValueObject]` attributes; converters are generated **inline** in the consumer's registry | + +Either way the consuming project's registry maps them, so a shared `EmailAddress` is converted on +your entities without being configured twice. + +A provider assembly that only *defines* value objects and owns no `DbContext` should opt out of its +own registry, so consumers do not get duplicate `ValueObjectEFExtensions`/`ValueObjectModelCustomizer` +types in the `Microsoft.EntityFrameworkCore` namespace: + +```xml + + true + +``` + +A complex value object is discovered across assemblies when it opted into a mapping or a comparer +(including the default `ComplexType` mapping with `GenerateEFComparer = false`). Only one that opted +out entirely — `EFMapping = None` **and** `GenerateEFComparer = false` — is not discovered; configure +that one on the entity by hand. + +## Configuring a property explicitly + +The nested `EF` class is there when you want the registry's work done by hand: + +```csharp +builder.Entity() + .Property(c => c.Email) + .HasConversion(EmailAddress.EF.Converter, EmailAddress.EF.Comparer); + +builder.Entity() + .ComplexProperty(o => o.Total, money => + { + money.Property(m => m.Amount); + money.Property(m => m.Currency).HasConversion(CurrencyCode.EF.Converter, CurrencyCode.EF.Comparer); + }); +``` + +## Opting out + +```csharp +// Per type. +[Scalar(GenerateEFConverter = false, GenerateEFComparer = false)] +public readonly partial record struct InternalCode { } + +[ValueObject(EFMapping = EntityFrameworkMapping.Json)] +public readonly partial record struct Audit { } + +[ValueObject(EFMapping = EntityFrameworkMapping.None, GenerateEFComparer = false)] +public readonly partial record struct Notes { } +``` + +```csharp +// Per assembly. +[assembly: ValueObjectDefaults(EFMapping = EntityFrameworkMapping.Json)] +[assembly: ValueObjectDefaults(GenerateEFConverter = false, GenerateEFComparer = false)] +``` + +```xml + + + true + +``` + +## Schema and migrations + +- A scalar is a **single column** of its primitive, so `dotnet ef migrations add` sees the primitive. + Renaming the value object's property changes no schema; changing the underlying type is a column + type change you review like any other. +- A complex-type-mapped value object is a **set of columns** named after its members; a JSON-mapped + one is a **single JSON column**. Moving between the two is a schema change that usually needs a + data migration to reshape existing values. +- Converters and the key generator convention are provider-independent, so one model serves SQL + Server, PostgreSQL and SQLite; only the primitive column types differ. Keep one migration set per + provider. +- `IDesignTimeDbContextFactory` and model-cache keys that depend on runtime state (a query + filter built from the current tenant, say) must be applied consistently — a cached model is reused + for every context created the same way. + +## Version support + +Compiled and tested against EF Core **7, 9 and 10** (EF Core 7 needs `net8.0`), in +`src/tests/ValueObjects.EFCompatibility.IntegrationTests`, so version-specific API shifts are caught +by this build rather than by a consumer. + +EF Core 8+ is required for **complex type mapping**, the complex-type block in the registry, and the +compiled-model `JsonReaderWriter` members. On EF Core 7, a complex value object reports `VO1019` and +is left unmapped — use `EFMapping = Json` or configure the property manually. Everything else +(converters, the key value generator, the convention, `ValueObjectSequentialGuid`) works on EF Core 7 +and later. + +## Diagnostics + +`VO1009` (EF option set without an EF reference), `VO1010` (underlying type not mappable), `VO1017` +(JSON mapping without the JSON converter), `VO1018` (a complex member cannot be converted), `VO1019` +(complex type on EF Core 7 or earlier) and `VO1021` (value generation unavailable) are the EF rules. +The `purview-value-objects-diagnostics` skill carries the full `VO1xxx` catalogue. + +## Where to look in the repository + +- `src/src/Sample` — a runnable EF Core (SQLite) example. +- `src/tests/ValueObjects.IntegrationTests/Serialization/EntityFrameworkIntegrationTests.cs` — the + integration tests. +- `src/tests/ValueObjects.EFCompatibility.IntegrationTests` — the per-version compatibility suite. diff --git a/.agents/skills/purview-value-objects-efcore/references/key-value-generation.md b/.agents/skills/purview-value-objects-efcore/references/key-value-generation.md new file mode 100644 index 00000000..c12b84f6 --- /dev/null +++ b/.agents/skills/purview-value-objects-efcore/references/key-value-generation.md @@ -0,0 +1,101 @@ +# Generated key values + +Opt a Guid-backed scalar into key generation per type, or once for the assembly: + +```csharp +[Scalar(GenerateEFValueGenerator = true)] +public readonly partial record struct CustomerId +{ + public Guid Value { get; } +} + +// or: +[assembly: ValueObjectDefaults(GenerateEFValueGenerator = true)] +``` + +The generator emits an `EF.ValueGeneratorFactory` on the value object and registers every opted-in +type in the generated `ValueObjectKeyValueGeneratorConvention`. Register that convention once: + +```csharp +protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder) +{ + base.ConfigureConventions(configurationBuilder); + configurationBuilder.UseValueObjectKeyGenerators(); +} + +protected override void OnModelCreating(ModelBuilder modelBuilder) +{ + modelBuilder.ConfigureValueObjects(); +} +``` + +## What the convention guarantees + +- An **unset** key (still `Guid.Empty`) is assigned a time-ordered identifier when the entity is + added, so keys are unique without a database round trip and sort by creation time in stores that + compare identifiers byte by byte. +- A key the **domain already set** is never touched. Entity Framework Core only invokes a generator + while the property holds its CLR default. +- The convention runs at the lowest configuration source, so an entity configuration that owns its + keys — `ValueGeneratedNever()`, an explicit generator, a store-generated default — always wins. + +The identifier is a time-ordered UUID created with base Entity Framework Core APIs only, so the +convention holds for every provider. + +## Key ordering + +Where a store compares the identifier's sixteen bytes in order — PostgreSQL, SQLite, MySQL, and +non-clustered SQL Server keys — version 7 ordering is what you want. SQL Server's `uniqueidentifier` +compares the **trailing six bytes first**, so plain version 7 values are effectively random there and +a clustered key fragments. + +```csharp +// Default: version 7, ascending in plain byte order. +configurationBuilder.UseValueObjectKeyGenerators(); + +// SQL Server: the timestamp moves into the trailing six bytes, which SQL Server compares first. +configurationBuilder.UseValueObjectKeyGenerators(ValueObjectKeyOrdering.SqlServer); +``` + +| Ordering | Timestamp location | Ascends by creation time in | Well-formed version 7 UUID | +| --- | --- | --- | --- | +| `ValueObjectKeyOrdering.UuidV7` (default) | bytes 0-5 | PostgreSQL, SQLite, MySQL, non-clustered SQL Server keys | Yes | +| `ValueObjectKeyOrdering.SqlServer` | bytes 10-15 | SQL Server's `uniqueidentifier` ordering | No — a version 4 UUID | + +Both orderings produce unique identifiers in process, keep the domain's own value when it set one, +and start from a random value so nothing leaks about the sequence. + +Which bytes carry the timestamp is a **store** concern, so the ordering is chosen where the +convention is registered — in the persistence project, never on the value object. + +## Minting a key in application code + +`ValueObjectSequentialGuid` is public, in the `Microsoft.EntityFrameworkCore` namespace, so +application code — including code in another assembly — can mint the identifier it wants an entity to +carry, before the round trip that would otherwise assign one: + +```csharp +// The same value the convention would have generated, created where the domain needs it. +var customerId = CustomerId.Create(ValueObjectSequentialGuid.NewGuid()); +var customer = Customer.Create(customerId, tenantId, email, "Contoso"); +``` + +Because Entity Framework Core only invokes a generator while the property still holds its CLR +default, the key the application set is persisted as-is. + +| Member | Purpose | +| --- | --- | +| `NewGuid()` / `NewGuid(DateTimeOffset)` | Creates a version 7 identifier, from now or a given creation time. | +| `NewSqlServerGuid()` / `NewSqlServerGuid(DateTimeOffset)` | Creates a SQL Server-ordered identifier. | +| `TryGetTimestamp(Guid, out DateTimeOffset)` | Reads the creation time out of a version 7 identifier; false for any other shape. | +| `TryGetSqlServerTimestamp(Guid, out DateTimeOffset)` | Reads the creation time out of a SQL Server-ordered identifier. | +| `MinSqlServerGuidFor(DateTimeOffset)` / `MaxSqlServerGuidFor(DateTimeOffset)` | Inclusive bounds for a creation time, so `id >= Min… && id <= Max…` is an index seek. | + +## Limits + +- **Guid-backed scalars only**, and the Entity Framework converter must be enabled. Requesting it + anywhere else reports `VO1021` and emits no generator. +- A value object declared in an assembly that does not reference Entity Framework Core still gets a + generator: the consuming project emits it alongside the inline converters. +- A generated key value generator is typed as the **value object**, not its provider value, because + Entity Framework Core assigns what a generator returns straight to the property. diff --git a/.agents/skills/purview-value-objects-zodsharp/SKILL.md b/.agents/skills/purview-value-objects-zodsharp/SKILL.md new file mode 100644 index 00000000..ad826848 --- /dev/null +++ b/.agents/skills/purview-value-objects-zodsharp/SKILL.md @@ -0,0 +1,325 @@ +--- +name: purview-value-objects-zodsharp +description: >- + Use when validating Purview.ValueObjects with Purview.ZodSharp - the [ZodSchema] integration that + routes Create through a generated schema, ZodSchemaMode, the OnZodValidate refinement hook, custom + rules and [ZodRule] attributes on scalars, schema-first Z.* validation, DTO validation, and mapping + ZodException to ASP.NET Core Problem Details. +metadata: + product: Purview.ValueObjects + repository: purview-dev/value-objects +--- + +# Validating value objects with ZodSharp + +[Purview.ZodSharp](https://www.nuget.org/packages/Purview.ZodSharp) is a C# port of +[Zod](https://github.com/colinhacks/zod). It complements `Purview.ValueObjects` by splitting the +responsibility: **the value object owns the invariant, ZodSharp owns the rule definition and the +result shape**. + +Reference the package explicitly when you use its types — do not rely on transitive flow. The +ZodSharp source generator is active in any project that references the package. + +```text +dotnet add package Purview.ZodSharp +``` + +Four ways to use it, in rough order of how often you want them: + +1. **Generator-integrated** — `[Scalar]` + `[ZodSchema]`, and `Create` validates through the schema. +2. **Generated validators** — `[ZodSchema]` + DataAnnotations emits a zero-allocation `{Type}Schema`. +3. **Schema-first** — hand-build `Z.String()` / `Z.Number()` / `Z.Enum()` and construct through `Create`. +4. **DTO-first** — validate the request shape, then map onto value objects. + +## 1. Generator-integrated validation + +Annotate a value object with **both** `[Scalar]`/`[ValueObject]` **and** `[ZodSchema]`, and the +value-object generator routes the generated `Create` through the ZodSharp schema — no wiring: + +```csharp +using System.ComponentModel.DataAnnotations; +using Purview.ValueObjects.Serialization; +using ZodSharp; + +[Scalar] +[ZodSchema] +public readonly partial record struct EmailAddress +{ + [EmailAddress] + [StringLength(254, MinimumLength = 3)] + public string Value { get; } + + static partial void OnNormalize(ref string value) => value = value?.Trim().ToLowerInvariant()!; +} + +EmailAddress.Create("not-an-email"); // throws ZodException via EmailAddressSchema.Validate +``` + +`Create` constructs the instance, calls `{Type}Schema.Validate(instance)` and throws `ZodException` +on failure. **`Hydrate` stays replay-safe** — no schema, no hooks. +`ValueObjectDeserializationMode.Strict` deserializes through `Create`, so it picks the schema up too. + +`[ZodSchema]` reads DataAnnotations: `[Required]`, `[StringLength]`, `[Range]`, +`[RegularExpression]`, `[EmailAddress]`, `[AllowedValues]`, `[DeniedValues]`. It supports classes, +structs and records. + +### ZodSchemaMode + +| Mode | Behaviour | +| --- | --- | +| `InAdditionToHooks` (default) | the schema runs **and** `OnValidate` runs | +| `InsteadOfHooks` | the schema runs **instead of** `OnValidate`; `OnNormalize` still runs first | + +Leaving an `OnValidate` in place under `InsteadOfHooks` makes it unreachable — that is `VO1013`. + +### The automatic scalar form + +`[Scalar]` / `[Scalar(typeof(T))]` have the value-object generator declare the underlying +property, so a property-attached DataAnnotation has no host. For those types use Zod-native +**type-level** rules (`[RequiredZod]`, `[ZodRule(typeof(...))]`), which ZodSharp reads from the type +and adapts to the scalar's underlying value — or keep the manual `[Scalar]` form when you need +property-level DataAnnotations. Purview.ZodSharp 2.0.2+ generates `{Type}Schema` from the attribute +itself, so the automatic form validates through `Create` exactly like the manual one. + +A nullable scalar (`Nullable = true`, or a `T?` value type) round-trips JSON `null`, so its schema +and any string rule must be null-tolerant: use the shipped `[NullOrNonWhiteSpace]`, which accepts +`null` but rejects whitespace, rather than `[RequiredZod]`, which always rejects `null`. + +### `[ZodSchema]` options + +- `SchemaName` — overrides the generated class name (default `{TypeName}Schema`); the DI adapter + becomes `{SchemaName}Validator`. ZodSharp applies any non-empty value **verbatim**, including + whitespace, so an unusable name is reported as `VO1015` rather than silently falling back. +- `CustomValidationMethodName` — a static async method the generated validator's `ValidateAsync` + awaits after the synchronous rules pass (default `CustomValidationAsync`). + +## The `OnZodValidate` refinement hook + +For rules DataAnnotations cannot express — cross-member invariants, allowed domains, state checks — +implement the partial hook the ZodSharp generator declares: + +```csharp +[Scalar] +[ZodSchema] +public readonly partial record struct CorporateEmail +{ + [EmailAddress] + public string Value { get; } + + static partial void OnNormalize(ref string value) => value = value?.Trim().ToLowerInvariant()!; + + partial void OnZodValidate(RefineCtx context) + { + if (!context.Value.Value.EndsWith("@contoso.com", StringComparison.Ordinal)) + context.AddIssue("invalid_domain", "Corporate emails must use the contoso.com domain.", [nameof(Value)]); + } +} +``` + +Facts worth knowing: + +- The hook is declared **and invoked by the ZodSharp generator**, inside `{Type}Schema.Validate`, so + it runs for every entry point: `Validate`, `Parse`, the DI adapter, `IValidateOptions`, the + generated `Create`, and `Strict` deserialization. `Hydrate` never validates. +- Because it belongs to the schema, `{Type}Schema.Validate(instance)` reports exactly what `Create` + reports. +- The type and every containing type must be `partial`, so the generator can declare the hook. + ZodSharp reports `ZODSGEN034` (not partial) and `ZODSGEN035` (malformed signature). +- It is independent of `ZodSchemaMode`: `InsteadOfHooks` skips `OnValidate`, never `OnZodValidate`. +- The old `IEnumerable Validate()` refinement contract is **retired**; ZodSharp + reports `ZODSGEN036` for a member still using it. + +## Custom rules on scalars + +A scalar is validated as a **unit** — its single `Value` *is* the value. ZodSharp ships a validation +attribute for every built-in rule in `ZodSharp.Rules`: + +| Attribute | Rule | Notes | +| --- | --- | --- | +| `[NonSentinel(Message = "…")]` | `NonSentinelRule` | Rejects `Guid.Empty`, the `DateTime`/`DateTimeOffset`/`DateOnly`/`TimeOnly` bounds, and null/empty/whitespace strings. | +| `[Email]` | `EmailRule` | | +| `[E164]` | `E164Rule` | | +| `[UUID(UuidVersion.V4)]` | `UUIDRule` | A rule value with no default is a required constructor argument. | +| `[MinLengthZod(3)]` | `MinLengthRule` | The `Zod` suffix avoids the DataAnnotations clash. Also `[MaxLengthZod]`, `[UrlZod]`, `[PhoneZod]`, `[CreditCardZod]`, `[Base64StringZod]`. | + +Each attribute mirrors its rule's constructor; `Message` and `Code` stay named properties, so an +error code or message can be overridden per use. + +```csharp +using ZodSharp; +using ZodSharp.Rules; + +[Scalar] +[ZodSchema] +[NonSentinel(Message = "AssetId must not be empty.")] +public readonly partial record struct AssetId +{ + public Guid Value { get; init; } +} +``` + +`AssetId.Create(Guid.Empty)` throws a `ZodException` whose error carries the rule's own `Code`, no +structured `Origin`, and an **empty path** — the rule applies to the value object, not a member. +Because it runs inside the schema, `Hydrate` stays replay-safe. + +Writing your own rule attribute, the automatic adapter that lets a rule written against the +underlying value validate the value object, and the `Code`/`Origin` resolution order are in +[references/custom-rules.md](references/custom-rules.md). + +## Schema-first validation + +When you do not want the generator involved, build a schema for the **underlying** value and +construct through `Create`: + +```csharp +using ZodSharp; + +public static class ScalarSchemas +{ + public static readonly IZodSchema EmailSchema = Z.String().Email().Min(3).Max(254); + public static readonly IZodSchema CurrencySchema = Z.String().Regex("^[A-Z]{3}$"); + public static readonly IZodSchema OrderStatusSchema = Z.Enum(); + public static readonly IZodSchema MoneyAmountSchema = Z.Number().Positive(); +} +``` + +ZodSharp validates the raw value **exactly as supplied** — normalization is the value object's job in +`OnNormalize`. So: validate the raw input, then `Create`, which normalizes and wraps it. + +## Validating DTOs before mapping + +```csharp +[ZodSchema] +public sealed partial class RegistrationDto +{ + [Required, StringLength(100, MinimumLength = 2)] + public string Name { get; init; } = string.Empty; + + [Range(13, 120)] + public int Age { get; init; } + + [Required, EmailAddress] + public string Email { get; init; } = string.Empty; + + partial void OnZodValidate(RefineCtx context) + { + if (context.Value.Name.StartsWith("x", StringComparison.OrdinalIgnoreCase)) + context.AddIssue("name", "Name cannot start with 'x'.", [nameof(Name)]); + } +} + +var result = RegistrationDtoSchema.Validate(dto); + +if (result.IsSuccess) +{ + var email = EmailAddress.Create(result.Value.Email); + var money = Money.Create(19.99m, CurrencyCode.Create("USD")); +} +``` + +Async rules go through `CustomValidationMethodName`, naming a +`static ValueTask> Method(T value, CancellationToken)` that the generated +`{Type}SchemaValidator.ValidateAsync` awaits once the synchronous rules pass. + +## Dependency injection + +`ZodSchemaFactory` resolves validators by validated type: + +```csharp +using ZodSharp.Core; + +ZodSchemaFactory factory = new(); + +factory.Register(new EmailAddressSchemaValidator()); // generated adapter +factory.Register(new ZodSchemaValidator(ScalarSchemas.EmailSchema)); // hand-built + +var emailResult = factory.Validate(EmailAddress.Create("demo@example.com")); +``` + +## Error handling + +`ValidationResult` is a struct with `IsSuccess`, `Value` (only on success) and `Errors` +(`ImmutableArray`). Each `ValidationError` carries `Code`, `Message` and `Path`, +plus optional `Origin`, `Category` and size bounds: + +```csharp +foreach (var error in result.Errors) + Console.WriteLine($"{string.Join(".", error.Path)}: {error.Message} ({error.Code}, {error.Origin})"); +``` + +Use `Parse` / `GetValueOrThrow()` to throw instead of inspecting. The value-object layer never +reconstructs codes or messages — it forwards `result.Errors` into a `ZodException`, so a rule's +`Code`, `Message`, `Origin`, `Category` and path arrive intact. + +### ASP.NET Core Problem Details + +`Purview.ZodSharp.AspNetCore` maps a thrown `ZodException` to `HttpValidationProblemDetails`: + +```csharp +builder.Services.AddZodSharpProblemDetails(); +builder.Services.AddProblemDetails(); + +var app = builder.Build(); +app.UseExceptionHandler(); +``` + +Make the value object validate during model binding: + +```csharp +[Scalar( + ZodSchemaMode = ZodSchemaMode.InsteadOfHooks, + DeserializationMode = ValueObjectDeserializationMode.Strict)] +[ZodSchema] +public readonly partial record struct EmailAddress +{ + [Required, EmailAddress] + public string Value { get; } +} + +builder.Services.ConfigureHttpJsonOptions(options => + options.SerializerOptions.Converters.Add(new ScalarJsonConverterFactory())); +``` + +An invalid body now returns `400 application/problem+json` with the structured issues in the `issues` +extension. + +Map error codes to HTTP statuses with `[ErrorType]` on a `static readonly ErrorType` field; the +bundled `ErrorTypeGenerator` emits `Create{Field}(...)` and a `[DoesNotReturn]` `Throw{Field}(...)`. +The `ZODSASP001` analyzer flags a `MessageFormat` placeholder missing from `Parameters` at compile +time. + +## JSON Schema export + +```csharp +var jsonSchema = Z.ToJsonSchema(ScalarSchemas.EmailSchema, new ToJsonSchemaOptions { Title = "Email" }); +``` + +Draft 2020-12, for sharing a contract with TypeScript Zod. + +## Diagnostics + +`VO1013` (unreachable `OnValidate` under `InsteadOfHooks`) and `VO1015` (invalid `SchemaName`) are the +value-object side. ZodSharp's own `ZODSGEN030`-`ZODSGEN043` cover the refinement hook and rule +mapping; `ZODSASP001` covers the ASP.NET Core error types. + +## Testing the dual-generator integration + +Two shapes, and the distinction is load-bearing: + +- **In-memory (unit)** — `src/tests/SourceGenerator.UnitTests` registers the packaged ZodSharp + generator through `ZodSchemaValidationGeneratorTestOptions`, resolving the component types out of + band via `Common/ZodSharpSourceGenerators.cs`. The project copies + `analyzers/dotnet/cs/Purview.ZodSharp.SourceGenerators.dll` beside the test binaries + (`GeneratePathProperty` + `None`/`CopyToOutputDirectory`) and loads it with `Assembly.LoadFrom`. + **Never turn that copy into a ``**: a merged analyzer component carried + `Purview.SourceGeneratorFramework.*` types that then collided (`CS0433`) with the framework + assembly the harness loads. `Common/ZodSharpSourceGeneratorsTests.cs` guards it. +- **Real compile (integration)** — `src/tests/ValueObjects.IntegrationTests` declares `[Scalar]` + + `[ZodSchema]` fixtures and asserts runtime behaviour; both generators run in the real compiler, so + nothing is reflected or registered. + +The loaded generator carries its own framework implementation, so it keeps its own log sink and +CodeWriter scope validation: do not assert on its log entries, and leave `ValidateCodeWriterScopes` +off for that run. + +`src/src/ZodSharpSample` is the runnable example. diff --git a/.agents/skills/purview-value-objects-zodsharp/references/custom-rules.md b/.agents/skills/purview-value-objects-zodsharp/references/custom-rules.md new file mode 100644 index 00000000..43c9fc20 --- /dev/null +++ b/.agents/skills/purview-value-objects-zodsharp/references/custom-rules.md @@ -0,0 +1,130 @@ +# Custom ZodSharp rules for value objects + +## Writing a rule attribute + +A custom rule reaches a value object as a `[ZodRule]`-mapped attribute, in one of two ways. + +### 1. Map a hand-authored attribute to the rule + +Declare a `ValidationAttribute` and point it at the rule. The open generic form serves both a +primitive member and a scalar: + +```csharp +using ZodSharp.Core; + +// Reads the value object through IScalarValueObject. Implementing IZodRule lets the +// rule own its error identity, so one attribute can report a different code per scalar. +public readonly record struct NoWhitespaceRule(string? Message = null) + : IValidationRule, IZodRule + where TSelf : IScalarValueObject +{ + public const string ErrorCode = "invalid_string"; + public const string MessageFormat = "Value must not contain whitespace."; + + public bool IsValid(in TSelf value) => !value.Value.Any(char.IsWhiteSpace); + + public string GetErrorMessage(in TSelf value) => Message ?? MessageFormat; + + string? IZodRule.Code => ErrorCode; + + string? IZodRule.Origin => "value_object"; +} + +[ZodRule(typeof(NoWhitespaceRule<>))] +[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct | AttributeTargets.Property)] +public sealed class NoWhitespaceAttribute : ValidationAttribute +{ + public string? Message { get; set; } +} +``` + +### 2. Let the generator write the attribute + +Mark the rule with the parameterless `[ZodRule]` marker and ZodSharp emits a `{RuleName}Attribute` in +the rule's namespace. A trailing `Rule` becomes `Attribute`; a name clashing with a +`System.ComponentModel.DataAnnotations` attribute gets a `Zod` suffix: + +```csharp +[ZodRule] // the generator emits NoWhitespaceAttribute +public readonly record struct NoWhitespaceRule(string? Message = null) + : IValidationRule, IZodRule + where TSelf : IScalarValueObject +{ + // ... +} +``` + +The generator runs over the compilation that **declares** the rule, so the marker form suits a rule +in the same project, or in a rules library that references Purview.ZodSharp. + +Requirements the generator enforces: + +- A rule accepting a `code`/`origin` constructor parameter must implement `IZodRule`, or + `ZODSGEN039`. +- A rule should expose `public const string ErrorCode` and `public const string MessageFormat`, or + `ZODSGEN042`. +- `ZODSGEN043` reports a built-in rule that cannot produce a validation attribute. + +## How `Code` and `Origin` resolve + +First match wins: + +1. **Rule-owned** — the rule implements `IZodRule` (`IZodRule.Code` / `IZodRule.Origin`). +2. **Attribute-declared** — `Code`/`Origin` named arguments on the applied attribute. +3. **Mapping** — `[ZodRule(typeof(X), Code = "…", Origin = "…")]` on the attribute type. +4. **Default** — `validation_failed`, no origin. + +The value-object layer never reconstructs codes or messages. It calls +`{Type}Schema.Validate(instance)` and forwards `result.Errors` into a `ZodException`, so `Code`, +`Message`, `Origin`, `Category` and path arrive intact. + +## Reusing a rule written against the underlying value + +A rule written against the underlying value — `NonSentinelRule` — validates *that value*, not +the value object. Closing it with the scalar type (`NonSentinelRule`) compiles but **always +passes**, because the sentinel check only knows the primitive. + +The value-object generator emits `ScalarRuleAdapter` into every project that +references both `Purview.ValueObjects` and `Purview.ZodSharp`: + +```csharp +internal readonly record struct ScalarRuleAdapter(TRule Rule) : IValidationRule + where TSelf : IScalarValueObject + where TRule : IValidationRule +{ + public bool IsValid(in TSelf value) => Rule.IsValid(value.Value); + + public string GetErrorMessage(in TSelf value) => Rule.GetErrorMessage(value.Value); +} +``` + +**Do not declare it yourself.** A project that already declares its own copy — the guidance before +the generator emitted it — is detected and the generated copy is skipped, so both keep compiling. + +ZodSharp applies the adapter automatically when a rule is applied to a `[Scalar]` type, so the common +case needs no extra code. The built-in `[NonSentinel]` is exactly this shape: + +```csharp +using ZodSharp; +using ZodSharp.Rules; + +[Scalar] +[ZodSchema] +[NonSentinel(Message = "UserId must not be empty.")] +public readonly partial record struct UserId +{ + public Guid Value { get; init; } +} +``` + +The generator closes `NonSentinelRule<>` with the underlying `Guid` and wraps it in +`ScalarRuleAdapter>`, so the rule runs against the value object +with an empty path, and the **wrapped** rule owns the reported `Code` (the built-in rules report no +structured `Origin`). One attribute serves every scalar backed by the same primitive. + +The runnable version is `src/src/ZodSharpSample/NonSentinelModels.cs`, and the fixtures in +`src/tests/ValueObjects.IntegrationTests/Serialization/ZodSchemaRuleModels.cs` cover rule +`Code`/`Origin` and the empty path end to end. + +See ZodSharp's [Custom Rules](https://purview.dev/docs/zodsharp/custom-rules/) for the rule contract +and the full list of shipped attributes. diff --git a/.agents/skills/purview-value-objects/SKILL.md b/.agents/skills/purview-value-objects/SKILL.md new file mode 100644 index 00000000..a0e6e2fd --- /dev/null +++ b/.agents/skills/purview-value-objects/SKILL.md @@ -0,0 +1,263 @@ +--- +name: purview-value-objects +description: >- + Use when modelling domain values with Purview.ValueObjects - scalar, complex or contextual value + objects, typed identifiers, the Create/Hydrate split, OnNormalize/OnValidate hooks, built-in string + normalization, assembly-level ValueObjectDefaults, JSON deserialization modes, or deciding where an + invariant belongs. +metadata: + product: Purview.ValueObjects + repository: purview-dev/value-objects +--- + +# Purview value objects + +`Purview.ValueObjects` source-generates the plumbing for value objects: factories, equality, +comparison, formatting, parsing and JSON. You declare the shape and the invariants; the generator +emits the rest. + +Three shapes, and the choice is forced by what the value *is*: + +| Attribute | Use for | Declaration | +| --- | --- | --- | +| `[Scalar]` / `[Scalar]` | one primitive with a name and rules (ids, codes, emails) | `readonly partial record struct` | +| `[ValueObject]` | a small fixed group of members that travel together | `partial record` / `readonly partial record struct` | +| `IContextualValueObject` | a value whose validity depends on the owner's current state | a `[Scalar]` that also implements the interface | + +All three must be **top-level** and **partial**, and none may be generic. Nesting is `VO1002`, +generics are `VO1003`, a missing `partial` is `VO1001`. The `purview-value-objects-diagnostics` +skill carries the full rule list. + +## The `Create` / `Hydrate` split + +This is the single most important thing to get right. Every value object gets both: + +- **`Create(value)`** — the strict path. Runs `OnNormalize`, then `OnValidate`, then constructs. + Use it for command input, user input, parsing, and anything crossing a trust boundary. +- **`Hydrate(value)`** — the reconstruction path. Constructs without validating. Use it for + persisted state, event replay and deserialization, where validation already happened and + re-running it would reject historical data that was legal when it was written. +- **`TryCreate(value, out result)`** — `Create` without the throw; returns `false` on failure. + +| Path | Behaviour | +| --- | --- | +| `Create(...)` | Throws — the hook's exception, or `ZodException` when a ZodSharp schema is generated for the type. | +| `TryCreate(...)` | Returns `false` instead of throwing. | +| `Hydrate(...)` | Never validates, never normalizes. | + +Never make `Hydrate` validate "for safety". Replay paths exist precisely because yesterday's rules +are not today's. + +## Scalar value objects + +```csharp +[Scalar] +public readonly partial record struct EmailAddress +{ + public string Value { get; } + + static partial void OnNormalize(ref string value) => value = value?.Trim().ToLowerInvariant()!; + + static partial void OnValidate(string value) + { + if (string.IsNullOrWhiteSpace(value)) + throw new ArgumentException("Email is required.", nameof(value)); + + if (!value.Contains('@', StringComparison.Ordinal)) + throw new ArgumentException("Invalid email format.", nameof(value)); + } +} +``` + +- Declare the scalar property yourself (`[Scalar]`), or let the generator own it (`[Scalar]`). + With `[Scalar]` you must **not** declare a member of that name — that is `VO1022`. +- The default property name is `Value`; `ScalarAttribute.PropertyName` changes it. A `[Scalar]` type + with no matching property is `VO1004`. +- Prefer `readonly record struct`. Anything else is `VO1006`, because equality, immutability and + allocation behaviour stop matching the contract. +- You do not need to declare the private constructor. The generator emits one. + +### Built-in string normalization + +Trim and casing are common enough to configure rather than hand-write: + +```csharp +[Scalar(Trim = true, Casing = StringCasing.LowerInvariant)] +public readonly partial record struct EmailAddress { } + +[ValueObject] +public readonly partial record struct Contact +{ + [StringNormalize(Trim = true)] + public string Email { get; init; } + + public string Name { get; init; } +} +``` + +Trim runs first, then casing, then validation — and only inside the generated `Create`. Casing is +invariant-culture only, deliberately: a canonical form that depends on the ambient thread culture is +not canonical. A hand-written `OnNormalize` or `Create` wins and the option is ignored (`VO1023`); +the option on a non-string is ignored (`VO1024`); restating a value the assembly default already sets +is reported as redundant (`VO1026`/`VO1027`). `[StringNormalize]` itself only belongs on a complex value +object member — on a `[Scalar]` or any other type it is the error `VO1025`, and MSBuild can supply the +assembly defaults with `ValueObjectsDefaultTrim` / `ValueObjectsDefaultCasing`. + +## Complex value objects + +```csharp +[ValueObject] +public sealed partial record UserDetails(Guid Id, string? DisplayName, bool IsActive = true) +{ + static partial void OnNormalize(ref Guid id, ref string? displayName, ref bool isActive) + { + if (!isActive) + displayName = null; + } + + partial void OnValidate(Guid id, string? displayName, bool isActive) + { + if (id == Guid.Empty) + throw new ArgumentException("Id must be a valid GUID.", nameof(id)); + } +} +``` + +Normalize every component together, before validation, so cross-member canonicalization is possible. +Keep members `readonly`/`init`-only — a mutable member is `VO1016` and makes equality unstable. On a +`struct`, declare `OnValidate` as `readonly` when it does not mutate; the generator mirrors the +modifier. + +## Contextual value objects + +When validity depends on the owning instance's current state — a state machine, a cross-field rule +that needs the aggregate — implement `IContextualValueObject`: + +```csharp +[Scalar] +public readonly partial record struct OrderStatus + : IContextualValueObject +{ + public OrderStatusCode Value { get; } + + public static OrderStatus Create(OrderStatusCode value, in ValueObjectContext context) + { + var current = context.Owner.Status.Value; + + return IsValidTransition(current, value) + ? new(value) + : throw new InvalidOperationException($"Invalid transition {current} -> {value}."); + } +} +``` + +`ValueObjectContext` carries `Owner`, `MemberName` and an optional `Reason`. Keep the +contextual `Create` deterministic and side-effect free, and keep plain `Hydrate` available so replay +does not fail on historical transitions. + +## Where an invariant belongs + +| Concern | Lives in | +| --- | --- | +| Primitive format, canonicalization | `OnNormalize` / `OnValidate` on the value object | +| Cross-field invariants within the value | `partial void OnValidate(...)` on a `[ValueObject]` | +| Owner lifecycle / state-machine transitions | contextual `Create(TValue, in ValueObjectContext)` | +| Schema rules, DTO validation, API error shapes | ZodSharp — the `purview-value-objects-zodsharp` skill | +| Persistence and query shape | the entity mapping — the `purview-value-objects-efcore` skill | + +Validation must be pure: deterministic, no I/O, no clock, no ambient culture. + +## Standard interfaces + +A scalar mirrors the standard interfaces its underlying type actually implements, so it behaves like +that type in generic code: + +| Interface | Mirrored when | Forwarded member | +| --- | --- | --- | +| `IEquatable` | the underlying type implements it | `Equals(TValue)` | +| `IFormattable`, `ToString(string?)` | the underlying type implements/declares them | `ToString(format[, provider])` | +| `ISpanFormattable` / `IUtf8SpanFormattable` | the underlying type implements them | `TryFormat` | +| `IParsable` / `ISpanParsable` / `IUtf8SpanParsable` | the underlying type implements them | `Parse` / `TryParse` | + +Detection is per type **and** per target framework, so `string` gets parsing but not span formatting +and an enum gets the reverse. Declaring one of an interface's members yourself skips that interface. + +`Parse` goes through `Create` (so it normalizes and validates); `TryParse` goes through `TryCreate`. +`IComparable` and `IComparable` are always implemented, and a scalar always exposes +`CompareTo(TValue)`, because the contract requires it. Numeric/arithmetic interfaces, `IConvertible` +and collection interfaces are deliberately **not** mirrored. + +## JSON and deserialization modes + +Both attributes default to `ValueObjectDeserializationMode.Hydrate`, so a JSON read does not +re-validate. Choose `Strict` only when round-trip fidelity genuinely requires re-running validation +on read — and then make sure a `Create` overload exists to re-validate through, or you get `VO1007`. + +## Assembly-level defaults + +Repeat nothing per type that the assembly can say once: + +```csharp +[assembly: ValueObjectDefaults(Trim = true, Casing = StringCasing.LowerInvariant)] +``` + +Per-type and per-member settings override it. + +## Value objects in a domain model + +Value objects carry identity and invariants; entities and aggregates carry lifecycle. Keep the +dependency graph clean by splitting them: + +| Project | References | Contains | +| --- | --- | --- | +| Domain (`MyApp.Core`) | `Purview.ValueObjects`, optionally `Purview.ZodSharp` | Value objects, entities/aggregates, domain services. **No Entity Framework.** | +| Persistence (`MyApp.Persistence`) | EF Core, the domain project | `DbContext`, entity configuration, `ConfigureValueObjects()`, migrations | + +A domain project with no EF reference gets no EF members generated into it. That is the point: the +*consuming* project discovers the value objects from their attributes and generates the converters +into the persistence assembly, so no EF code leaks into the domain. + +**Typed identifiers.** Make every identity a scalar value object, so a `CustomerId` can never be +passed where an `OrderId` is expected: + +```csharp +// Domain project - no Entity Framework reference. +[Scalar] +public readonly partial record struct CustomerId +{ + public Guid Value { get; } +} + +public sealed class Customer +{ + Customer(CustomerId id, EmailAddress email) => (Id, Email) = (id, email); + + public CustomerId Id { get; } + + public EmailAddress Email { get; private set; } + + public static Customer Create(CustomerId id, EmailAddress email) => new(id, email); +} +``` + +Entities beside them are ordinary classes: private constructor, static `Create` factory that +validates, members typed as value objects rather than primitives. The factory is the command +boundary; mutation methods enforce invariants spanning members. + +## Queryability + +Primitive-backed scalars are the most query-friendly shape — a provider compares the value object +directly. A scalar wrapping a complex CLR type keeps its invariants and serialization, but a deep +predicate through `.Value` may not translate to SQL. Do not assume +`aggregate.ComplexScalar.Value.Child.Prop` is translatable; if you need to filter on it, expose a +separately mapped mirror property derived from canonical state, and test the exact predicate. + +## Checklist for a new value object + +1. Shape: scalar, complex, or contextual. +2. Normalization rules per member (hand-written hook, or configured trim/casing). +3. Validation rules and the exception each one throws. +4. Whether anything constructs it from storage — if so, it uses `Hydrate`. +5. Deserialization mode, if not the default. +6. Persistence shape, if it is stored. +7. Queryability, if it is filtered on. diff --git a/.agents/skills/purview-zodsharp-aspnetcore/SKILL.md b/.agents/skills/purview-zodsharp-aspnetcore/SKILL.md new file mode 100644 index 00000000..a11c2587 --- /dev/null +++ b/.agents/skills/purview-zodsharp-aspnetcore/SKILL.md @@ -0,0 +1,242 @@ +--- +name: purview-zodsharp-aspnetcore +description: >- + Use when wiring Purview.ZodSharp into ASP.NET Core or any DI host - ProblemDetails from a + ValidationResult or a thrown ZodException, minimal-API endpoint validation, registering + IZodSchemaFactory with AddZodSharp or AddZodSharpFactory, validating options objects with + IValidateOptions, and mapping error codes to HTTP statuses with ErrorType. +license: MIT +metadata: + product: Purview.ZodSharp.AspNetCore + repository: purview-dev/zodsharp +--- + +# ASP.NET Core and dependency injection + +`Purview.ZodSharp.AspNetCore` turns failed validation into standard `ProblemDetails` / +`HttpValidationProblemDetails` payloads **without losing the structured issues**, and registers +schema resolution into DI. + +```bash +dotnet add package Purview.ZodSharp.AspNetCore +``` + +## ProblemDetails from a result + +```csharp +using ZodSharp.AspNetCore; + +var result = BasketSchema.Validate(basket); + +if (!result.IsSuccess) +{ + var problem = result.ToHttpValidationProblemDetails(); + + return Results.ValidationProblem( + problem.Errors, + extensions: new Dictionary { ["issues"] = problem.Extensions["issues"] }); +} +``` + +| Member | Produces | +| --- | --- | +| `ToHttpValidationProblemDetails(result, statusCode = 400)` | `HttpValidationProblemDetails`; paths flattened to dotted keys (`user.email`, array indexes as `[0]`) | +| `ToValidationProblemDetails(result, statusCode = 400)` | `ValidationProblemDetails` | + +Both **throw `InvalidOperationException` when the result is successful** — they are failure +converters, not general mappers. The structured metadata survives in the `issues` extension as a +`ValidationIssue[]`: + +```csharp +public sealed class ValidationIssue +{ + public required string Code { get; init; } + public string? Category { get; init; } + public string? Origin { get; init; } + public int? Minimum { get; init; } + public int? Maximum { get; init; } + public bool? Inclusive { get; init; } + public required string[] Path { get; init; } + public required string Message { get; init; } + public IReadOnlyDictionary? Parameters { get; init; } +} +``` + +## Minimal APIs + +```csharp +// Validate the bound DTO automatically - needs AddZodSharp to have registered the validator. +app.MapPost("/users", (UserDto dto) => dto) + .WithZodSharpValidation(); + +// Or validate in the handler and return the IResult directly. +app.MapPost("/users", (UserDto dto) => +{ + var result = UserDtoSchema.Validate(dto); + return result.IsSuccess ? TypedResults.Ok(result.Value) : result.ToValidationProblem(); +}); +``` + +`WithZodSharpValidation()` adds an endpoint filter that validates the first bound argument of type +`T` against the `IZodSchemaFactory` registered by `AddZodSharp`/`AddZodSharpFactory`. On failure it +returns the same payload as `ToHttpValidationProblemDetails()`; on success it passes through. + +## Thrown `ZodException` + +A `ZodException` from `Parse`, `GetValueOrThrow()`, or a value object's generated `Create` under +strict deserialization maps the same way: + +```csharp +catch (ZodException ex) +{ + return Results.ValidationProblem(ex.ToHttpValidationProblemDetails().Errors); +} +``` + +Or handle it globally: + +```csharp +builder.Services.AddZodSharpProblemDetails(); + +var app = builder.Build(); +app.UseExceptionHandler(); +``` + +`AddZodSharpProblemDetails(configure?, problemDetails?)` registers `ZodExceptionHandler`, calls +`services.AddProblemDetails(problemDetails)`, and configures `ZodProblemDetailsOptions`: + +- `ErrorTypeRegistry Registry` — resolves codes to `ErrorType`s; defaults to `ErrorTypeRegistry.Default`. +- `bool FormatMessages` — format messages from the matched `ErrorType.MessageFormat`. +- `Func, int>? StatusCodeSelector` — total control of the status code. + +> It does **not** register `IZodSchemaFactory`. Pair it with `AddZodSharp` (or the core +> `AddZodSharpFactory`) when you also want DI validator resolution. + +## Error codes to HTTP statuses + +`ErrorType`, the `[ErrorType]` attribute, the generator that emits `Create`/`Throw` helpers and the +`ZODSASP001`–`ZODSASP003` analyzers all ship in the **core** package and need no ASP.NET Core +dependency. The AspNetCore package adds `ErrorTypeRegistry` and the ProblemDetails mapping on top. + +```csharp +public static partial class ConcurrentErrorType +{ + [ErrorType] + public static readonly ErrorType SaveFailed = new( + Code: "aggregate_save_failed", + Category: "invalid_value", + Description: "The aggregate could not be saved.", + HttpStatus: 409, + MessageFormat: "Aggregate '{AggregateId}' (of type {AggregateType}) failed to save", + Parameters: + [ + new("AggregateId", typeof(string)), + ErrorType.Param("AggregateType"), + ]); +} + +ErrorTypeRegistry.Default.Register(ConcurrentErrorType.SaveFailed); +``` + +`HttpStatus` lives on `ErrorType` purely for convenience — the core library never reads it; only the +ASP.NET Core mapping does. `Category` is a broad grouping that can span many specific codes (code +`invalid_tenant_id`, category `invalid_value`); the generated helpers copy it onto each +`ValidationError` and it surfaces on the serialized `ValidationIssue`. + +Marking the field `[ErrorType]` and the containing class `partial` gets you strongly typed helpers, +one parameter per declared entry: + +```csharp +var error = ConcurrentErrorType.CreateSaveFailed("agg-123", "Invoice"); +ConcurrentErrorType.ThrowSaveFailed("agg-123", "Invoice"); + +var detailed = ConcurrentErrorType.CreateSaveFailed( + "agg-123", "Invoice", + path: ["order", "items", "[0]"], + origin: "collection", minimum: 1, maximum: 10, inclusive: true); +``` + +`Create` builds a typed `ErrorTypeParameters` (validated against the declared types, exposed through +`ValidationError.Parameters`) and sets the message from `ErrorType.FormatMessage`, so +`error.Message` already reads the formatted text. + +Mapping rules: + +- **Status** — the highest matched `ErrorType.HttpStatus` wins; unmapped codes fall back to `400`. + `StatusCodeSelector` overrides everything. +- **Title / Type / Detail** — from the highest-status matched `ErrorType`, otherwise defaulted. +- **Message** — named placeholders are substituted from `ValidationError.Parameters`. A placeholder + with no matching value is **left as-is**, so a templating gap stays visible rather than silently + disappearing. `ZODSASP001` warns at compile time when a placeholder is not declared in `Parameters`. +- **Parameters** — surfaced per-issue in `issues`, and merged (camel-cased) into the top-level + extensions for client correlation. + +`ToHttpValidationProblemDetails` / `ToValidationProblemDetails` also accept an `ErrorTypeRegistry` or +a `Func` for on-demand mapping. + +## Registering the factory + +`IZodSchemaFactory` (`ZodSharp.Core`) resolves validators by type: + +| Member | Behaviour | +| --- | --- | +| `Resolve()` | the validator, or `null` | +| `ResolveRequired()` | the validator, or `InvalidOperationException` | +| `Validate(value)` | validate through the registered validator | +| `Register(…)` / `Register(Type, …)` / `TryRegister(…)` / `IsRegistered()` | registration | + +```csharp +builder.Services.AddZodSharp(options => +{ + options.ScanAssemblies.Add(typeof(UserDto).Assembly); + options.ScanAssemblyGraphs.Add(typeof(Program).Assembly); + options.ScanLoadedAssemblies = true; +}); + +// Additive, for modular apps: +builder.Services.AddZodSharpAssembly(typeof(UserDto).Assembly); +builder.Services.AddZodSharpAssemblyGraph(typeof(Program).Assembly); +builder.Services.AddZodSharpLoadedAssemblies(); +``` + +Scanning finds the generator's `[assembly: ZodSchemaGenerated(typeof(…))]` markers and registers each +`{Type}SchemaValidator`. A hand-built schema registers by wrapping: +`factory.Register(new ZodSchemaValidator>(mySchema))`. + +> **`TryAdd` semantics.** The **first** `AddZodSharp`/`AddZodSharpFactory` call wins; later calls — +> including their options and `ConfigureFactory` callbacks — are ignored. State is never overwritten, +> so calling it more than once is safe, and the additive helpers still contribute. + +| Method | Package | Registers | Use when | +| --- | --- | --- | --- | +| `AddZodSharp(options)` | AspNetCore | factory + auto-registered generated validators | an ASP.NET Core app | +| `AddZodSharpAssembly/AssemblyGraph/LoadedAssemblies` | AspNetCore | additive assembly sources | modular apps where deeper layers contribute their own schemas | +| `AddZodSharpFactory(configure)` | core | the factory only | any host; you call `RegisterFromAssembly` yourself | +| `AddZodSharpProblemDetails(…)` | AspNetCore | exception handler + ProblemDetails, **not** the factory | mapping thrown `ZodException`s | +| `AddZodSchemaOptionsValidator(…)` | core | `IValidateOptions` | options validation; needs a factory first | + +## Options validation + +```csharp +builder.Services.AddZodSharpFactory(f => f.RegisterFromAssembly(typeof(UserOptions).Assembly)); +builder.Services.AddZodSchemaOptionsValidator(); + +// or chained: +builder.Services + .AddOptions() + .Bind(configuration.GetSection("User")) + .AddZodSchemaValidator() + .ValidateOnStart(); // fail at startup, not first access +``` + +`MissingValidatorBehavior` decides what happens with no validator registered for `T`: +`Throw` (default — `ResolveRequired()`, so a missing schema is loud rather than a silent skip) or +`Ignore` (passes through as success). + +The generator also auto-generates `IValidateOptions` for types whose names end in configurable +suffixes — see the `purview-zodsharp-source-generator` skill. + +## Related skills + +`purview-zodsharp-core` for the runtime API, `purview-zodsharp-source-generator` for the compile-time +validators this resolves, and `purview-zodsharp-diagnostics` for `ZODSASP*`. diff --git a/.agents/skills/purview-zodsharp-core/SKILL.md b/.agents/skills/purview-zodsharp-core/SKILL.md new file mode 100644 index 00000000..98280dd6 --- /dev/null +++ b/.agents/skills/purview-zodsharp-core/SKILL.md @@ -0,0 +1,176 @@ +--- +name: purview-zodsharp-core +description: >- + Use when validating data with Purview.ZodSharp at runtime - picking the right package, building + schemas with the Z factory, Validate/SafeParse/Parse, reading ValidationResult and ValidationError, + composing with Transform/Refine/Pipe/Catch/Default, and how null handling and type coercion work. +license: MIT +metadata: + product: Purview.ZodSharp + repository: purview-dev/zodsharp +--- + +# Purview.ZodSharp core + +A C# port of [Zod](https://github.com/colinhacks/zod): schemas you build fluently, validated without +exceptions, reporting machine-readable issues. + +## Packages + +```bash +dotnet add package Purview.ZodSharp # core, source generator, JSON Schema export +dotnet add package Purview.ZodSharp.SystemTextJson # STJ deserialize-and-validate + schema import +dotnet add package Purview.ZodSharp.NewtonsoftJson # Newtonsoft equivalent +dotnet add package Purview.ZodSharp.AspNetCore # ProblemDetails + DI +``` + +JSON Schema **export** (`Z.ToJsonSchema`) is in the core package; **import** (`Z.FromJsonSchema`) comes +from whichever JSON integration you reference, so import its namespace +(`ZodSharp.JsonSchema.SystemTextJson` or `ZodSharp.JsonSchema.NewtonsoftJson`). + +## First schema + +```csharp +using ZodSharp; + +var nameSchema = Z.String().Min(3).Max(50); +var result = nameSchema.Validate("John"); + +if (result.IsSuccess) + Console.WriteLine(result.Value); +``` + +## Validate, SafeParse, Parse, ValidateAsync + +| Member | Behaviour | +| --- | --- | +| `Validate(value)` | returns `ValidationResult`; **never throws** | +| `SafeParse(value)` | alias of `Validate` | +| `Parse(value)` | returns the validated value, or throws `ZodException` (via `GetValueOrThrow()`) | +| `ValidateAsync(value, ct)` | `ValueTask` wrapper. The pipeline is synchronous; the token is observed before validation and throws `OperationCanceledException` if already cancelled. Genuinely async work only happens in the source generator's custom async validation. | + +Reach for `Validate` by default and `Parse` only where a throw is the right control flow. Exceptions +for expected invalid input are expensive and lose the structured issue list unless you catch. + +## `ValidationResult` + +A `readonly record struct` in `ZodSharp.Core`: + +- `bool IsSuccess` — annotated `[MemberNotNullWhen(true, nameof(Value))]`, so the compiler knows + `Value` is non-null inside the success branch. +- `T? Value` — valid only when `IsSuccess`. +- `ImmutableArray Errors`. + +Factories: `Success(value)`, `Failure(ValidationError)`, `Failure(ImmutableArray)`, +`Failure(IEnumerable)`, and `Merge(lhs, rhs)` — succeeds only if both succeed, and +concatenates the errors otherwise. + +## `ValidationError` + +A `readonly record struct` carrying machine-readable metadata, not just a message: + +| Member | Meaning | +| --- | --- | +| `Code` | `invalid_type`, `too_small`, `too_big`, `invalid_union`, `missing_field`, `unrecognized_key`, `validation_failed`, `refinement_failed`, `transform_error`, … | +| `Message` | human-readable | +| `Path` | `ImmutableArray` — `["user", "email"]`; array indexes are string segments, `"0"` | +| `Origin` | category for size issues: `"string"`, `"array"`, `"collection"` | +| `Minimum` / `Maximum` / `Inclusive` | the bound, for size issues | +| `Parameters` | `IReadOnlyDictionary`; a union failure carries every option error under `"errors"` | + +Build one with +`ValidationError.Create(code, message, path, parameters, origin, minimum, maximum, inclusive)`. + +`ZodException` carries `ImmutableArray Errors`; its `ToString()` renders one line per +error as `"{joinedPath}: {Message} ({Code})"`. + +## The `Z` factory + +| Method | Returns | +| --- | --- | +| `Z.String()` / `Z.Number()` / `Z.Boolean()` / `Z.Null()` / `Z.Date()` / `Z.BigInt()` | the matching `Zod*` schema | +| `Z.Array(elementSchema)` | `ZodArray` | +| `Z.Optional(schema)` (`T : class`) / `Z.Nullable(schema)` (`T : struct`) | `ZodOptional` / `ZodNullable` | +| `Z.Object()` | `ZodObjectBuilder` | +| `Z.Union(params ...)` / `Z.Union(...)` | `ZodUnion` / `ZodTypedUnion` | +| `Z.DiscriminatedUnion(discriminator)` | `ZodDiscriminatedUnionBuilder` | +| `Z.Intersection(left, right)` | `ZodIntersection` | +| `Z.Literal(value)` (`T : IEquatable`) | `ZodLiteral` | +| `Z.Lazy(schemaGetter)` | `ZodLazy` — for recursive schemas | +| `Z.Enum(params string[])` / `Z.Enum()` | `ZodEnum` / `ZodNativeEnum` | +| `Z.Record(valueSchema)` | `ZodRecord` | +| `Z.Tuple(…)` / `Z.Tuple(…)` | `ZodTuple<…>` | +| `Z.ToJsonSchema(schema, options?)` | `JsonSchemaDefinition` | + +`Enum` and `Union` are overloaded — `Enum(params string[])` versus `Enum()`, and +`Union(params …)` versus `Union(…)`. + +```csharp +var userSchema = Z.Object() + .Field("name", Z.String().Min(1)) + .Field("age", Z.Number().Min(0).Max(120).Int()) + .Field("email", Z.String().Email()) + .Build(); +``` + +## The validation pipeline + +Every schema derives from `ZodType` (`ZodSharp.Core`). Two phases: + +1. **`ParseInternal`** — the schema's own type check and traversal: rejecting `null` where not + allowed, coercing, walking objects/arrays/tuples/unions, producing structured failures. +2. **Rules** — on success, the accumulated `IValidationRule` structs run. A failing rule emits + a `ValidationError` with its Zod-compatible code. + +Rules are `readonly record struct`s implementing `IValidationRule` (`bool IsValid(in T value)`, +`string GetErrorMessage(in T value)`) — zero allocation. Each exposes `public const string ErrorCode` +and `MessageFormat`, so a test asserts against the rule rather than a duplicated literal. (A rule +without them is `ZODSGEN042`.) + +`ZodString` also exposes `ValidateSpan(ReadOnlySpan)` and `IsValidSpan(value, out errors)` for +allocation-free string validation; string rules implementing `IStringValidationRule` participate. + +## Composition + +`ZodType` composes by **wrapping**, never mutating. Each of these returns a new schema: + +| Call | Produces | +| --- | --- | +| `.Transform(func)` | `ZodTransform` | +| `.Refine(predicate, message?)` | `ZodRefinement` | +| `.SuperRefine(Action>)` | `ZodSuperRefinement` | +| `.Pipe(schema)` | `ZodPipe` | +| `.Catch(value \| func)` | `ZodCatch` | +| `.Prefault(value)` / `.Default(value)` | `ZodPrefault` / `ZodDefault` | +| `.And(schema)` / `.Or(schema)` | `ZodIntersection` / `ZodTypedUnion` | +| `.Describe("…")` | sets `Description` | + +Because composition lives on the base type, every schema chains all of them. + +## Null and optionality + +Schemas report optionality through the internal `IOptionalSchema`: + +- `IsOptional` — true for `ZodOptional`, `ZodNullable`, `ZodDefault`, `ZodPrefault`. +- `ProvidesValueOnMissing` — true for `ZodDefault` and `ZodPrefault`. Object fields route a missing + value through `Validate(null!)` so the produced value is injected. +- `IAcceptsNull.ValidateNull()` is implemented by the nullable/optional/default/prefault schemas and + `ZodNull`; object-field and union wrappers route `null` to it rather than failing coercion. + +## Type coercion + +Object fields and union options wrap typed schemas, so boxed values out of a +`Dictionary` validate: + +- `null` routes to `IAcceptsNull.ValidateNull()` where supported. +- An exactly-typed value reuses the original box. +- Numeric coercion goes through `IConvertible` in the **invariant** culture, so a boxed `long` + satisfies a `Z.Number()` field. +- A non-nullable value type rejects `null`; anything else falls through to failure. + +## Related skills + +`purview-zodsharp-source-generator` for compile-time `[ZodSchema]` validators (which is what you want +for a DTO), `purview-zodsharp-custom-rules` for writing rules and rule attributes, +`purview-zodsharp-aspnetcore` for ProblemDetails and DI, and `purview-zodsharp-diagnostics` for the +`ZODSGEN`/`ZODSASP` catalogue. diff --git a/.agents/skills/purview-zodsharp-custom-rules/SKILL.md b/.agents/skills/purview-zodsharp-custom-rules/SKILL.md new file mode 100644 index 00000000..06215ccb --- /dev/null +++ b/.agents/skills/purview-zodsharp-custom-rules/SKILL.md @@ -0,0 +1,241 @@ +--- +name: purview-zodsharp-custom-rules +description: >- + Use when writing a custom validation rule for Purview.ZodSharp - implementing IValidationRule and + IStringValidationRule, the ErrorCode/MessageFormat constants convention, IZodRule runtime identity, + attaching a rule with AddRule or a fluent extension, exposing it as a DataAnnotations-style + attribute with [ZodRule], generic rules, and type-level rules on scalar value objects. +license: MIT +metadata: + product: Purview.ZodSharp + repository: purview-dev/zodsharp +--- + +# Custom rules + +A **rule** is a `readonly record struct` (or class) implementing `ZodSharp.Core.IValidationRule`. +Rules run after a schema's type and structural check succeeds; each failing rule adds a +`ValidationError`. + +Rules are first class in two directions: + +- attach one to a schema with the public `AddRule`/`Rule` API, or +- surface it as a `System.ComponentModel.DataAnnotations`-style attribute that the `[ZodSchema]` + generator honours exactly like `[EmailAddress]` or `[Range]`. + +## The contract + +```csharp +namespace ZodSharp.Core; + +public interface IValidationRule +{ + bool IsValid(in T value); + string GetErrorMessage(in T value); +} +``` + +Implement it as a **struct** so validation does not allocate. `IsValid` is called only when the +surrounding schema succeeded and — for a nullable property — the value is not `null`. + +For a **string** rule, also implement `ZodSharp.Core.IStringValidationRule` +(`bool IsValid(ReadOnlySpan)` / `string GetErrorMessage(ReadOnlySpan)`) so the rule +participates in `ZodString.ValidateSpan`/`IsValidSpan` without materialising the input. A rule that +implements only `IValidationRule` still works; it falls back to the string pipeline. + +## `ErrorCode` and `MessageFormat` — not optional in practice + +Every rule **should** expose its error identity as public constants, so code and tests assert against +the rule rather than re-typing literals: + +```csharp +public readonly record struct EmailRule : IValidationRule +{ + public const string ErrorCode = "invalid_string"; + public const string MessageFormat = "Invalid email format: {0}"; + + public string Code => ErrorCode; + + public string GetErrorMessage(in string value) => + string.Format(CultureInfo.CurrentCulture, MessageFormat, value); +} +``` + +- **`ErrorCode`** is the canonical code. `IValidationRule.Code` defaults to `"validation_failed"`; + a rule accepting a per-usage `code` override returns it (falling back to `ErrorCode`) from both + `Code` and `IZodRule.Code`, so every route reports the same effective value. +- **`MessageFormat`** is a `string.Format` template. `{0}` is the offending value; `{1}`, … are + rule-specific arguments. Format with `CultureInfo.CurrentCulture`. +- The constants may be inherited from a base rule class, and **abstract bases are exempt**, so a + shared base can host them for its concrete derivations. + +A source-declared rule missing either constant is reported as **`ZODSGEN042`**. The payoff: + +```csharp +await Assert.That(error.Code).IsEqualTo(EmailRule.ErrorCode); +await Assert.That(error.Message).IsEqualTo( + string.Format(CultureInfo.CurrentCulture, EmailRule.MessageFormat, value)); +``` + +### Runtime identity: `IZodRule` + +The constants are the rule's *static* default. When one attribute must report a different code per +annotated member, implement `IZodRule` and supply code/origin at runtime: + +```csharp +public interface IZodRule +{ + string? Code { get; } // null falls back to the attribute-mapped code + string? Origin { get; } // null falls back to the attribute-mapped origin +} +``` + +The generated code casts to `IZodRule` when reading them, so identity can depend on constructor +arguments. A rule that **accepts** a `code`/`origin` constructor parameter without implementing +`IZodRule` never reaches the reported identity — that is `ZODSGEN039`. + +Code and origin resolve first-match-wins: + +1. the rule, when it implements `IZodRule`; +2. `Code`/`Origin` named arguments on the applied attribute; +3. the `[ZodRule(typeof(X), Code = "…", Origin = "…")]` mapping on the attribute type; +4. default — `validation_failed`, no origin. + +### Message precedence + +1. A `message` argument on the rule (typically a `Message` constructor parameter), when set. +2. The attribute's `ErrorMessage` / `ErrorMessageResourceName` / `ErrorMessageResourceType`, mapped + to a constructor parameter named `message`. +3. `GetErrorMessage(value)`, formatting `MessageFormat`. + +`MessageFormat` is the fallback, not the only message. + +## Writing one + +```csharp +using System.Globalization; +using ZodSharp.Core; + +namespace MyRules; + +/// Rejects strings that contain whitespace. +public readonly record struct NoWhitespaceRule(string? Message = null) : IValidationRule +{ + public const string ErrorCode = "invalid_string"; + public const string MessageFormat = "Whitespace is not allowed in '{0}'."; + + public bool IsValid(in string value) + { + if (value is null) + return false; + + foreach (var character in value) + { + if (char.IsWhiteSpace(character)) + return false; + } + + return true; + } + + public string Code => ErrorCode; + + public string GetErrorMessage(in string value) => + Message ?? string.Format(CultureInfo.CurrentCulture, MessageFormat, value); +} +``` + +It works standalone, and attaches to any schema: + +```csharp +var rule = new NoWhitespaceRule(); +if (!rule.IsValid("John Doe")) + Console.WriteLine(rule.GetErrorMessage("John Doe")); + +var schema = Z.String().Rule(new NoWhitespaceRule("No spaces allowed.")); +``` + +`ZodType.AddRule(IValidationRule)` and the generic `Rule(TRule)` +helper are both public. Give the rule a first-class fluent method with an ordinary extension method on +its schema type, the way the built-in rules are surfaced. + +## Exposing it as an attribute + +Two routes. + +**Map a hand-authored attribute to the rule.** The open generic form serves both a primitive member +and a scalar value object: + +```csharp +[ZodRule(typeof(NoWhitespaceRule<>))] +[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct | AttributeTargets.Property)] +public sealed class NoWhitespaceAttribute : ValidationAttribute +{ + public string? Message { get; set; } +} +``` + +**Or let the generator write it.** Mark the rule with the parameterless `[ZodRule]` and a +`{RuleName}Attribute` is emitted in the rule's namespace — a trailing `Rule` becomes `Attribute`, and +a name colliding with a DataAnnotations attribute takes a `Zod` suffix: + +```csharp +[ZodRule] // emits NoWhitespaceAttribute +public readonly record struct NoWhitespaceRule(string? Message = null) : IValidationRule; +``` + +The generator runs over the compilation that **declares** the rule, so the marker form suits a rule +in the same project, or in a rules library referencing `Purview.ZodSharp`. + +## Generic rules and rule families + +A generic rule closed with the property type lets one attribute serve every member of that shape — +`[ZodRule(typeof(NonSentinelRule<>))]` on a `NonSentinelAttribute` covers `Guid`, `DateTime`, +`string` and the rest. + +`ZodSharp.Rules.NonSentinelRule` is the canonical example: it rejects the framework +default/boundary values an ORM stores to mean "no value" — `Guid.Empty`, +`DateTime.MinValue`/`MaxValue`, the `DateTimeOffset`/`DateOnly`/`TimeOnly` bounds, and +null/empty/whitespace strings. A type with no known sentinel always passes, so the rule never rejects +something it does not understand. Its JSON Schema mapping is exact for `DateOnly`, `TimeOnly`, deterministic +`DateTime` forms, and `DateTimeOffset`; the optional UTC opt-in only narrows the accepted offset (see the JSON +skill). + +```csharp +var schema = Z.Date().AddRule(new NonSentinelRule()); +var result = schema.Validate(DateTime.MinValue); +// result.Errors[0].Code == NonSentinelRule.ErrorCode ("invalid_value") +``` + +## Type-level rules and scalar value objects + +An attribute applied to a **type** validates the value as a unit, reporting an **empty path**. That is +what makes a rule usable on a `Purview.ValueObjects` `[Scalar]`: + +```csharp +[Scalar] +[ZodSchema] +[NonSentinel(Message = "UserId must not be empty.")] +public readonly partial record struct UserId +{ + public Guid Value { get; init; } +} +``` + +A rule written against the *underlying* value — `NonSentinelRule` — is adapted automatically: +the generator closes it with the underlying type and wraps it, so it runs against the value object +with an empty path, and the wrapped rule owns the reported `Code`. Closing such a rule with the +scalar type instead (`NonSentinelRule`) compiles but **always passes**, because the check only +knows the primitive. + +## Diagnostics you will meet + +`ZODSGEN030` (mapped rule does not implement `IValidationRule` for the property type), +`ZODSGEN031` (a constructor parameter could not be mapped from the attribute), `ZODSGEN032` (no +attribute could be generated), `ZODSGEN033` (a rule-mapped attribute on a type that gets no generated +schema, so the rule never runs), `ZODSGEN037`/`ZODSGEN038` (attribute-name collisions and incomplete +mappings), `ZODSGEN039` (`code`/`origin` without `IZodRule`), `ZODSGEN040` (an attribute argument with +no effect), `ZODSGEN042` (missing `ErrorCode`/`MessageFormat`) and `ZODSGEN043` (a built-in rule whose +constructor parameter cannot be an attribute property). + +The `purview-zodsharp-diagnostics` skill carries the full catalogue. diff --git a/.agents/skills/purview-zodsharp-diagnostics/SKILL.md b/.agents/skills/purview-zodsharp-diagnostics/SKILL.md new file mode 100644 index 00000000..101e872d --- /dev/null +++ b/.agents/skills/purview-zodsharp-diagnostics/SKILL.md @@ -0,0 +1,125 @@ +--- +name: purview-zodsharp-diagnostics +description: >- + Use when a Purview.ZodSharp build reports a ZODSGEN or ZODSASP diagnostic - the [ZodSchema] + generator's configuration and usage rules, the custom-rule mapping rules, and the ErrorType + analyzers - to find what triggered it and how to fix it. +license: MIT +metadata: + product: Purview.ZodSharp + repository: purview-dev/zodsharp +--- + +# Purview.ZodSharp diagnostics + +Two families, both enabled by default: + +- **`ZODSGEN*`** — the `[ZodSchema]` generator's analyzer (category `ZodSharp.SourceGenerator`). +- **`ZODSASP*`** — the `ErrorType` factory's analyzer and generator, which ship in the **core** + package and need no ASP.NET Core dependency. + +`ZODSGEN033` and `ZODSGEN037`–`ZODSGEN040` and `ZODSGEN042` are warnings; `ZODSGEN041` and +`ZODSGEN043` are informational; the rest are errors. + +IDs `ZODSGEN002` and `ZODSGEN022`–`ZODSGEN026` are intentionally unused. Rule identifiers are never +renumbered or reused, so a sighting of one means stale tooling or a stale suppression. + +## Generator failures and DataAnnotations usage + +| ID | Meaning | +| --- | --- | +| `ZODSGEN001` | Unhandled generator exception. | +| `ZODSGEN003` | `[Length]` with `min > max`. | +| `ZODSGEN004` | `[Length]` on an unsupported target. | +| `ZODSGEN005` | Error-message resource name without type, or type without name. | +| `ZODSGEN006` | Unsupported DataAnnotations usage: a string-only attribute on a non-string, `[AllowedValues]`/`[DeniedValues]` on an unsupported type, `[RegularExpression]` on a non-string, `[Range]` on an unsupported type. | +| `ZODSGEN020` | `[Compare]` references an unknown property. | +| `ZODSGEN021` | `System.ComponentModel.DataAnnotations` reference is missing. | + +## Custom async validation method + +All of these mean the method the generator was told to call cannot be called: + +| ID | Meaning | +| --- | --- | +| `ZODSGEN007` | Configured but not found. | +| `ZODSGEN008` | Return type is not `ValueTask>`. | +| `ZODSGEN009` | Parameter count is not 2. | +| `ZODSGEN010` | First parameter is not the model type. | +| `ZODSGEN011` | Second parameter is not `CancellationToken`. | +| `ZODSGEN012` | The method is generic. | +| `ZODSGEN013` | Declared on the model type but not `static`. | +| `ZODSGEN014` | Inaccessible from the generated validator (private/protected). | +| `ZODSGEN015` | Ambiguous overloads — only when at least two valid candidates exist. | +| `ZODSGEN016` | The configured name is not a valid C# identifier. | +| `ZODSGEN017` | The method is abstract. | +| `ZODSGEN018` | An unimplemented partial method. | +| `ZODSGEN019` | Uses `ref`/`in`/`out`/`params`/`scoped` parameters. | + +## `IValidateOptions` + +| ID | Meaning | +| --- | --- | +| `ZODSGEN027` | Requested, but the `Microsoft.Extensions.Options` reference is missing. | +| `ZODSGEN028` | Requested on a struct — it requires a class. | + +## The refinement hook + +| ID | Meaning | +| --- | --- | +| `ZODSGEN029` | The model declares **both** `OnZodValidate` and an async custom validation method. Exactly one is allowed. | +| `ZODSGEN034` | `OnZodValidate` is on a type that is not `partial`, or whose containing types are not all `partial`, so the generated declaration cannot be emitted. | +| `ZODSGEN035` | Not declared as `partial void OnZodValidate(RefineCtx context)` — wrong modifiers, return type or parameters. | +| `ZODSGEN036` | A member still uses the retired `IEnumerable Validate()` contract, which the generator no longer binds. Implement `OnZodValidate`. | + +## Custom rules and rule attributes + +| ID | Meaning | +| --- | --- | +| `ZODSGEN030` | A rule mapped through `[ZodRule(typeof(…))]` does not implement `IValidationRule` for the property type — including an unbound generic rule that cannot be closed with it. | +| `ZODSGEN031` | A rule constructor parameter could not be mapped from the attribute. | +| `ZODSGEN032` | No validation attribute could be generated for a rule marked `[ZodRule]`. | +| `ZODSGEN033` | *(warning)* A rule-mapped attribute is applied to a type that gets no generated schema — no `[ZodSchema]`, and not reachable as a complex property — so the rule never runs. | +| `ZODSGEN037` | *(warning)* A `[ZodRule]`-derived attribute name (`XRule` → `XAttribute`) is already declared by hand, so no attribute is generated and that declaration's own mapping governs every usage. | +| `ZODSGEN038` | *(warning)* A hand-authored attribute's `[ZodRule(typeof(…))]` mapping does not address every rule declared under the name it encodes (`XAttribute` → `XRule`), so some usages resolve to no rule. | +| `ZODSGEN039` | *(warning)* A rule accepts a `code`/`origin` constructor parameter but does not implement `IZodRule`, so the value never reaches the reported error identity. | +| `ZODSGEN040` | *(warning)* An attribute argument has no effect: the resolved rule has no matching constructor parameter, and the value is not part of the reported identity. | +| `ZODSGEN042` | *(warning)* A rule does not expose a public `const string ErrorCode` **and** a public `const string MessageFormat`, so its error identity cannot be asserted in tests without duplicating literals. | +| `ZODSGEN043` | *(info)* A built-in rule marked `[ZodRule]` generates no attribute, because a constructor parameter cannot be represented as an attribute property. The rule is still reachable through the runtime/fluent API. A name colliding with DataAnnotations is **not** skipped — it is emitted with a `Zod` suffix. | + +## Collections + +| ID | Meaning | +| --- | --- | +| `ZODSGEN046` | *(warning)* `[CollectionBehavior]` is applied to a property that is not a collection of nullable elements or values (a scalar, a collection whose element cannot be `null`, or a dictionary whose value cannot be `null`), so the setting can never take effect. | + +## Unions, value objects, JSON Schema + +| ID | Meaning | +| --- | --- | +| `ZODSGEN041` | *(info)* A typed `Z.Union` whose option types are all reference types can use the allocation-free native C# 15 union from `Z.NativeUnion` on .NET 11+. A code fix is offered. | +| `ZODSGEN044` | A `[ZodSchema]` type using an automatic `[Scalar]` form (`[Scalar]` / `[Scalar(typeof(TValue))]`) cannot produce a usable schema, so the value-object generator's `Create` would reference a `{Type}Schema` that does not exist or cannot validate. Reported when `GenerateValidateMethod = false` suppresses the `Validate` it calls, or the declared underlying type cannot be represented. | +| `ZODSGEN045` | A type referenced by an exported type has `GenerateJsonSchema = false`, so the cross-platform contract surface is incomplete. | + +## `ErrorType` — `ZODSASP*` + +These ship with the **core** package, alongside the `ErrorType` factory, the `[ErrorType]` attribute +and the generator that emits `Create`/`Throw` helpers: + +| ID | Severity | Meaning | +| --- | --- | --- | +| `ZODSASP001` | Warning | A `MessageFormat` placeholder is not declared in `ErrorType.Parameters`. | +| `ZODSASP002` | Warning | The containing type of an `[ErrorType]` field is not `partial`. | +| `ZODSASP003` | Warning | An `[ErrorType]` field is not `static readonly`. | +| `ZODSASP100` | Error | Unhandled exception in the `ErrorType` source generator. | +| `ZODSASP101` | Error | The `Parameters` of an `[ErrorType]` field could not be extracted. | + +`ZODSASP001`–`ZODSASP003` explain why `Create`/`Throw` helpers were **not** generated — a silent +absence otherwise. `ZODSASP100`/`ZODSASP101` are fatal generator failures and name the field. + +## Suppressing + +Standard mechanisms: `#pragma warning disable ZODSGEN006`, a `NoWarn` entry, or an `.editorconfig` +severity override. The canonical catalogue is the analyzer's `AnalyzerReleases.Shipped.md` / +`AnalyzerReleases.Unshipped.md` in the generator project — a new or changed rule must be recorded +there in the same change. diff --git a/.agents/skills/purview-zodsharp-json/SKILL.md b/.agents/skills/purview-zodsharp-json/SKILL.md new file mode 100644 index 00000000..adaedda0 --- /dev/null +++ b/.agents/skills/purview-zodsharp-json/SKILL.md @@ -0,0 +1,223 @@ +--- +name: purview-zodsharp-json +description: >- + Use when combining Purview.ZodSharp with JSON - deserialize-and-validate and validating converters + for System.Text.Json or Newtonsoft.Json, choosing between the two packages, exporting a schema to + JSON Schema with Z.ToJsonSchema, importing one with Z.FromJsonSchema, and sharing a contract with + TypeScript Zod. +license: MIT +metadata: + product: Purview.ZodSharp + repository: purview-dev/zodsharp +--- + +# JSON and JSON Schema + +Two integration packages, and they are **mutually exclusive in practice** — pick the one matching +your JSON library: + +```bash +dotnet add package Purview.ZodSharp.SystemTextJson +dotnet add package Purview.ZodSharp.NewtonsoftJson +``` + +Each adds deserialize-and-validate, a validating converter, and JSON Schema **import**. JSON Schema +**export** is in the core package. + +Both can be referenced from one project without `extern alias` — the JSON Schema types live in +`ZodSharp.JsonSchema.SystemTextJson` / `ZodSharp.JsonSchema.NewtonsoftJson` — but the +deserialize/serialize extension overloads share names, so **import exactly one package namespace per +file**. + +## Deserialize and validate + +```csharp +using ZodSharp; + +var userSchema = Z.Object() + .Field("name", Z.String().Min(3)) + .Field("age", Z.Number().Min(0).Int()) + .Build(); + +var result = userSchema.DeserializeAndValidate("""{ "name": "John", "age": 30 }"""); + +await using var stream = File.OpenRead("user.json"); +var streamed = await userSchema.DeserializeAndValidateAsync(stream); +``` + +Going the other way: + +```csharp +var json = userSchema.ValidateAndSerialize(user); // ValidationResult +await userSchema.ValidateAndSerializeAsync(user, outputStream); +``` + +Failures add `deserialization_failed` and `json_error` codes alongside the schema's own. + +## Validating converters + +```csharp +// System.Text.Json +var options = new JsonSerializerOptions { Converters = { userSchema.CreateValidatingConverter() } }; +var value = JsonSerializer.Deserialize(json, options); + +// Newtonsoft.Json +var value2 = JsonConvert.DeserializeObject(json, userSchema.CreateValidatingConverter()); +``` + +Invalid JSON **throws** — `JsonException` (STJ) or `JsonSerializationException` (Newtonsoft), with a +`"Validation failed: …"` message. Each converter removes itself from the options/serializer it uses +internally, to avoid recursing into itself. + +## Which package differs how + +| Aspect | SystemTextJson | NewtonsoftJson | +| --- | --- | --- | +| Async result | `ValueTask<…>` | `Task<…>` | +| Options parameter | `JsonSerializerOptions` | `JsonSerializerSettings` | +| Converter return | generic `JsonConverter` | non-generic `JsonConverter` | +| `JToken` overload | no | yes | +| Formatting | via options | explicit `Formatting` argument | +| Invalid-data exception | `JsonException` | `JsonSerializationException` | +| Plumbing type | `JsonElement` | `JToken`/`JObject`/`JArray` | + +## JSON Schema export + +`Z.ToJsonSchema` (core package) produces a Draft 2020-12 `JsonSchemaDefinition`: + +```csharp +var jsonSchema = Z.ToJsonSchema>(userSchema, new ToJsonSchemaOptions +{ + Title = "User", + Id = "https://example.com/schemas/user.json", +}); +``` + +`ToJsonSchemaOptions`: `IncludeSchema` (default `true`, emits `$schema`), `Id`, `Title`. + +`JsonSchemaDefinition` (`ZodSharp.JsonSchema`) is a mutable POCO mirroring the keywords — identity +(`$schema`/`$id`/`$ref`), type and title, string/number/array/object constraints, composition +(`anyOf`/`oneOf`/`allOf`), `enum`/`const`, `$defs` and draft-07 `definitions`, and the metadata +keywords including OpenAPI 3.0 `nullable`. + +Covered schema types: `ZodString`, `ZodNumber`, `ZodBoolean`, `ZodNull`, `ZodObject`, `ZodOptional`, +`ZodUnion`, `ZodArray`, `ZodLiteral`, `ZodNullable`, `ZodNativeEnum`/`ZodEnum`, `ZodLazy`. Notable +behaviours: + +- objects emit `additionalProperties: false`; +- literals emit `const` plus `type`; +- native enums emit `enum` in their System.Text.Json wire form — numbers by default, member names + when serialized as strings. A `[Flags]` enum emits `type: integer` instead, because a combination is + valid without being a defined member; +- lazy/recursive schemas emit `$ref` entries under `$defs` (`#/$defs/__lazyN`); +- rules that describe their own constraint implement `IJsonSchemaRule` and are applied during export; +- `[NonSentinel]` exports exact patterns for `DateOnly`, `TimeOnly`, `DateTime`, and `DateTimeOffset`. The + default `DateTimeOffset` pattern is offset-aware and needs no converter. An optional narrower UTC contract + uses `ZodSharpDateTimeOffsetSerialization=Utc` or + `[assembly: ZodSharpSchemaDefaults(DateTimeOffsetSerialization = DateTimeOffsetSerialization.Utc)]`, paired + with the integration package's `UtcDateTimeOffsetConverter` (which rejects non-UTC input on read). Override + per type/property with `[DateTimeOffsetBehavior(...)]`. + +### Exporting a generated `[ZodSchema]` + +No need to rebuild the rules by hand with `Z.Object()`: + +```csharp +var jsonSchema = RepositoryInventoryItemSchema.BuildJsonSchema(); +var exported = Z.ToJsonSchema(new RepositoryInventoryItemSchemaValidator()); +``` + +The definition comes from the same metadata the generated validator uses, so the two cannot drift. +Things worth knowing: + +- **Property names** use the System.Text.Json wire form: `[JsonPropertyName]` wins, otherwise the name + is camelCased to match `JsonSerializerDefaults.Web`. A non-camelCase global naming policy configured + at runtime is invisible to the generator, so adjust the exported names or declare + `[JsonPropertyName]`. +- **Required** follows the nullable reference-type annotation: a non-nullable reference type (or + `Nullable`) is required; a nullable one is wrapped in `anyOf: [ …, { "type": "null" } ]` and is + not required. `[Required]` also makes a field required, and a rule that rejects an absent value — + `[RequiredZod]` — makes the field non-null even with a nullable annotation. The generated validator + agrees with all of this. +- **Scalar value objects** (`[Scalar]`) export as the **underlying** value's schema, not as an + object wrapping a `Value` property. A `Guid` scalar exports as a canonical 8-4-4-4-12 hexadecimal + `pattern`, not Zod's RFC `uuid` format, because a C# `Guid` accepts any 128-bit value. +- **Collection items** follow the null-items setting: `T[]`/`List` maps to `z.array(T)` and + `T?[]`/`List` (or a property allowing nulls via `[CollectionBehavior(AllowNulls = true)]`) to + `z.array(T.nullable())`. A collection whose elements may be null exports + `items.anyOf: [ …, { "type": "null" } ]`; by default the generated validator rejects a null element with + `invalid_type` at the element's path, matching `z.array(T)`. +- **Dictionaries map to `z.record(z.string(), V)`.** A property implementing `IDictionary<,>` or + `IReadOnlyDictionary<,>` exports `{ "type": "object", "additionalProperties": }` (a nullable value + wraps that value schema in a `null` branch), and its size constraints use `minProperties`/`maxProperties`. + `Z.Record(schema)` exports the same shape, and `Z.FromJsonSchema` reads an object with + `additionalProperties` back as a record in both JSON integrations. + +## JSON Schema import + +```csharp +using ZodSharp; +using ZodSharp.JsonSchema.SystemTextJson; // or …NewtonsoftJson + +var userSchema = Z.FromJsonSchema(jsonSchemaString); +var result = userSchema.Validate(userData); +``` + +Overloads take a `string` or an already-deserialized `JsonSchemaDefinition`, and both return +`IZodSchema`. + +`Z.FromJsonSchema` is a **C# 14 extension member on `Z`**, so it only exists when a JSON integration +package is referenced. `Z.ToJsonSchema` is a real static member in the core package. + +Mapped keywords: + +- `type` — `string`, `number`, `integer`, `boolean`, `null`, `object`, `array`. +- `enum` → a union of literals (a single member becomes a literal); `const` → a literal. +- `anyOf`/`oneOf` → union; `allOf` → the intersection of every branch, plus the base schema when the + schema also declares a `type`. A type-less branch is `any`, matching Zod's `fromJSONSchema`. +- Strings — `minLength`, `maxLength`, `pattern`, and `format` (`email`, `uri`, `uuid`). The + `uuid`/`guid` format maps to the versionless `.UUID()`; a versioned `.UUID(UuidVersion.V7)` schema + exports `format: "uuid"` plus a version-pinning `pattern`, and the `allOf` composition preserves it + on import. Multiple `pattern` constraints compose under `allOf`, and every branch is applied. +- Numbers — `minimum`, `maximum`, `multipleOf`; `integer` additionally applies `.Int()`. +- Objects — `required` and optional fields. Arrays — `items`, `minItems`, `maxItems` (a nullable item + schema — `anyOf` with a `{"type":"null"}` branch — imports as a nullable element). + +### Limits + +`$ref` resolves **local** references only (`#/…`, for example `#/$defs/Name`). An external target +throws `NotSupportedException` naming it — inline the referenced schema, or move it under the root +`$defs`, before importing. Local references **may be cyclic**: one still being resolved becomes a lazy +schema. + +The reader binds `$schema`, `$id`, `$ref`, `$defs` and the draft-07 `definitions` through the +integration package's `JsonSchemaSerializerOptions`, and the same options write them back, so exported +definitions round-trip through either package. `JsonSchemaDefinition` itself carries no serializer +annotations — serialize it with `JsonSchemaSerializerOptions` to get keyword-compliant output. + +## Sharing a contract with TypeScript Zod + +```typescript +import { z } from "zod"; +const UserSchema = z.object({ username: z.string().min(3), email: z.string().email() }); +const jsonSchema = z.toJSONSchema(UserSchema); // Zod v4+ +``` + +```csharp +var userSchema = Z.FromJsonSchema(jsonSchemaString); +``` + +This repository also proves agreement by fixture rather than by assertion. `bun run generate-fixtures` +runs `src/ts/generate-fixtures.ts`, writing `src/ts/fixtures/*.json` plus a `manifest.json` in which +**Zod is the authority** on each fixture's validity. `just test` then reads both, asserts the C# +outcome matches, and writes validated C# output to +`src/tests/cross-platform/output/{systemtext,newtonsoft}-valid.json`. Finally `bun run test` (vitest) +re-checks the fixtures under Zod and parses the C# output — closing the loop in both directions. + +If the C# output directory is empty, the vitest suite tells you to run the C# cross-platform tests +first. + +## Related skills + +`purview-zodsharp-core` for the schema API, and `purview-zodsharp-source-generator` for the generated +validators that export through `BuildJsonSchema`. diff --git a/.agents/skills/purview-zodsharp-source-generator/SKILL.md b/.agents/skills/purview-zodsharp-source-generator/SKILL.md new file mode 100644 index 00000000..31d140ec --- /dev/null +++ b/.agents/skills/purview-zodsharp-source-generator/SKILL.md @@ -0,0 +1,224 @@ +--- +name: purview-zodsharp-source-generator +description: >- + Use when generating a compile-time validator with Purview.ZodSharp's [ZodSchema] attribute - which + types it emits, the attribute options, DataAnnotations coverage, the OnZodValidate refinement hook, + async custom validation, automatic enum validation, IValidateOptions support, and the MSBuild + switches that control it. +license: MIT +metadata: + product: Purview.ZodSharp + repository: purview-dev/zodsharp +--- + +# The `[ZodSchema]` source generator + +Mark a class, struct or record with `[ZodSchema]` and a static, zero-allocation validator is emitted +at compile time — no reflection at runtime. The attribute itself is generated into the `ZodSharp` +namespace by `Purview.ZodSharp.SourceGenerators`, so nothing beyond `Purview.ZodSharp` is needed. + +```csharp +using System.ComponentModel.DataAnnotations; +using ZodSharp; + +[ZodSchema] +public class User +{ + [Required] + [StringLength(50, MinimumLength = 3)] + public string Name { get; set; } = string.Empty; + + [Range(0, 120)] + public int Age { get; set; } + + [EmailAddress] + public string? Email { get; set; } +} + +var result = UserSchema.Validate(user); +var validated = UserSchema.Parse(user); // throws ZodException on failure +``` + +## What gets emitted + +| Artifact | Shape | +| --- | --- | +| `{TypeName}Schema` | static partial class — the validator. Accessibility mirrors the target. Holds `Validate`, `Parse`, `BuildJsonSchema`, and (with composition on) `ApplyAnd`, `ApplyOr`, `ApplyRefine`. Renamed by `SchemaName`. | +| `{TypeName}SchemaValidator` | `partial class : IZodSchemaValidator<{TypeName}>, IJsonSchemaProvider` — the DI adapter, with `Validate`/`ValidateAsync`/`BuildJsonSchema`. Primary schema only; `{SchemaName}Validator` when renamed. | +| `{TypeName}Validator` | `sealed partial class : IValidateOptions<{TypeName}>` — only when `IValidateOptions` support is on, and the target is a class. | +| `[assembly: ZodSchemaGenerated(typeof({TypeName}))]` | the marker `IZodSchemaFactory` assembly scanning consumes. Primary, non-nested schemas only. | + +`BuildJsonSchema` is built from the same metadata as `Validate`, so a generated schema exports through +`Z.ToJsonSchema` without rebuilding its rules by hand. + +```csharp +var adult = UserSchema.ApplyRefine(user, u => u.Age >= 18, "Must be adult"); +var both = UserSchema.ApplyAnd(user, u => u.Name.Length > 5, "Name too short"); +var either = UserSchema.ApplyOr(user, u => u.Age < 18, "Must be an adult, or a minor with consent"); +``` + +## Attribute options + +| Property | Default | Purpose | +| --- | --- | --- | +| `SchemaName` | `null` | Renames `{TypeName}Schema`; the DI adapter becomes `{SchemaName}Validator`. | +| `GenerateValidateMethod` | `true` | `false` omits `Validate` **and everything that depends on it**. | +| `GenerateParseMethod` | `true` | `false` omits `Parse`. | +| `EnableComposition` | `true` | Emits `ApplyAnd`/`ApplyOr`/`ApplyRefine`. | +| `CustomValidationMethodName` | `null` | Names the async custom validation method (default lookup `CustomValidationAsync`). Mutually exclusive with `OnZodValidate`. | +| `GenerateIValidateOptions` | `false` | Forces `IValidateOptions` generation. | +| `SuppressIValidateOptions` | `false` | Opts out even when auto-detection would enable it. | +| `ValidateEnumValues` | `true` | `false` skips automatic enum validation. | +| `GenerateJsonSchema` | `true` | `false` omits `BuildJsonSchema` and `IJsonSchemaProvider`. A type referenced by an exported type is `ZODSGEN045`. | +| `AllowNulls` | unset | Whether this type's collection properties may contain `null` elements. Unset defers to the assembly default. | + +`Parse`, the composition methods, the `IZodSchemaValidator` adapter and the `IValidateOptions` +validator all depend on `Validate` — `GenerateValidateMethod = false` removes them together. + +## What is validated + +- Properties must be public, non-static, non-indexer. +- A property gets validation when it carries **any** DataAnnotations attribute, when its type is a + source-defined complex type with a nested schema, or when its type is an enum. +- Nested complex types are discovered recursively and get their own `{TypeName}Schema`, **even + without** their own `[ZodSchema]`. +- Nullable properties are null-guarded before value-set/type validation; a nullable target rejects + `null` with `invalid_type`. +- Collection elements reject `null` by default: the error is `invalid_type` at the element's own path + (`["Items", 0]`). Control it with `[CollectionBehavior(AllowNulls = ...)]` on the property, a `T?` + element annotation (implies allow), `[ZodSchema(AllowNulls = ...)]` on the containing type, + `[assembly: ZodSharpSchemaDefaults(AllowNulls = ...)]`, then the `ZodSharpAllowNulls` MSBuild + property. The most specific statement wins; an unset level defers to the next. An explicit + `AllowNulls = true` exports a `null` branch on the collection's `items` schema. +- **Dictionaries are maps, not arrays.** A property whose type implements `IDictionary` + or `IReadOnlyDictionary` (for example `Dictionary`, `SortedDictionary`, + `ConcurrentDictionary`, `ImmutableDictionary`) validates every **value** against the value type's + nested schema and reports a failure at `["Items", "key"]`. Keys are used only in error paths, and + `AllowNulls` governs a null value (`Dictionary` rejects it by default; `Child?` or + `[CollectionBehavior(AllowNulls = true)]` accepts it). A dictionary exports as + `{ "type": "object", "additionalProperties": … }` and `[Length]`/`[MinLength]`/`[MaxLength]` map to + `minProperties`/`maxProperties` — never `z.array`/`items`. +- Classes, structs and records are supported. Structs get no `IValidateOptions` (`ZODSGEN028` if + requested). + +DataAnnotations coverage, positional-record attribute targets, structured size issues and the +`[Range]` shapes are in [references/dataannotations.md](references/dataannotations.md). + +## The `OnZodValidate` refinement hook + +Rules DataAnnotations cannot express are written as a **generator-declared partial method**. The +generator emits the declaration, so the IDE offers the implementation with the right signature and +nothing is resolved by naming convention: + +```csharp +[ZodSchema] +public partial class Order +{ + public decimal Total { get; set; } + + partial void OnZodValidate(RefineCtx context) + { + if (context.Value.Total < 0) + context.AddIssue("invalid_range", "Total cannot be negative", [nameof(Total)]); + } +} +``` + +- The type **and every containing type** must be `partial` (`ZODSGEN034`). That is the only shape + requirement the hook adds. +- The signature must be `partial void OnZodValidate(RefineCtx context)`, `T` being the model + (`ZODSGEN035`). The parameter is a plain by-value `RefineCtx`. +- The hook runs for **every** entry point — `Validate`, `Parse`, the `IZodSchemaValidator` adapter, + `IValidateOptions`, any factory that validates through the schema — so a rule written here behaves + exactly like an attribute rule. +- A type that does not implement it allocates nothing: the generated `Validate` only builds a + `RefineCtx` and calls the hook when a body exists. +- The retired `IEnumerable Validate()` contract is no longer bound, and is reported + as `ZODSGEN036`. + +Alongside the hook the generator emits one `internal static` +`InvokeZodRefinementHook(T value, RefineCtx context)` bridge on the target type. A classic partial +method is private and `{Type}Schema` is a different type, so the bridge is what lets `Validate` reach +the hook while keeping the hook optional. **It is not part of your API; never implement it by hand.** + +## Async custom validation + +Mutually exclusive with `OnZodValidate` — declaring both is `ZODSGEN029`. + +```csharp +public partial class UserSchemaValidator +{ + public async ValueTask> CustomValidationAsync(User value, CancellationToken ct) + { + await Task.Delay(1, ct); + return ValidationResult.Success(value); + } +} +``` + +Signature `ValueTask> Name(T value, CancellationToken ct)`. The default lookup +name is `CustomValidationAsync` unless `CustomValidationMethodName` overrides it. A method on the +**model type** must be `static`; one on the generated `{TypeName}SchemaValidator` partial may be an +instance method. The generated `ValidateAsync` runs the synchronous `Validate`, awaits the custom +method, and merges the error sets. + +## Automatic enum validation + +Every non-`[Flags]` enum property is validated automatically: a value that is not a defined member is +rejected with `invalid_enum_value`, emitted as an `EnumRule`. + +```csharp +public enum ExampleEnum +{ + [ZodIgnore] // never a valid value, for every property of this type + Unspecified, + AValidValue, + AnotherValidValue, +} + +[ZodSchema] +public class Model +{ + public ExampleEnum Status { get; set; } + + [DeniedValues(ExampleEnum.AnotherValidValue)] // excluded for this property only + public ExampleEnum SecondaryStatus { get; set; } +} +``` + +It is skipped when the enum is `[Flags]` (a combination is valid without being a defined member), +when the property declares an explicit `[AllowedValues]` allow-list (which governs instead), or with +`[ZodSchema(ValidateEnumValues = false)]`. A nullable enum is validated only when not `null`. + +## `IValidateOptions` support + +Enabled by `GenerateIValidateOptions = true`, by auto-detection (unset, target is not a value type, +and the type name ends with a configured suffix — `Options` or `Settings` by default), or by MSBuild. + +| MSBuild property | Default | Behaviour | +| --- | --- | --- | +| `DisableZodSharpSourceGenerator` | unset | truthy disables the generator entirely | +| `ZodSharpAutoGenerateOptionsValidators` | `true` | only an explicit `false` disables auto-detection | +| `ZodSharpAutoGenerateOptionsValidatorSuffixes` | `Options;Settings` | semicolon/comma-separated | +| `ZodSharpGenerateJsonSchemas` | `true` | explicit `false` omits `BuildJsonSchema` and `IJsonSchemaProvider` assembly-wide | +| `ZodSharpEnumSerialization` | `Number` | `String` exports enums as member names, matching a global `JsonStringEnumConverter` | +| `ZodSharpEnumNamingPolicy` | `Unchanged` | `CamelCase` applies `JsonNamingPolicy.CamelCase` to string-serialized enum names | +| `ZodSharpAllowNulls` | `false` | assembly-wide default for whether collections may contain `null` elements; explicit `true` accepts them | +| `ZodSharpDateTimeOffsetSerialization` | `PreserveOffset` | `Utc` narrows `[NonSentinel] DateTimeOffset` to a zero-offset wire contract; pair with the integration package's `UtcDateTimeOffsetConverter`. Both modes export an exact sentinel pattern | + +`DateTimeOffset` precedence: `[DateTimeOffsetBehavior]` on the property/parameter, then on the type, then +`[assembly: ZodSharpSchemaDefaults(DateTimeOffsetSerialization = ...)]`, then the MSBuild property, then +`PreserveOffset`. The attribute shapes the schema only; `Utc` requires a converter that also rejects non-UTC +input on read. + +## Value objects + +A `Purview.ValueObjects` scalar marked `[Scalar]` can carry `[ZodSchema]` on the same type. The +generated validator validates the scalar **as a unit** and reports an empty path, and a rule written +against the underlying value is adapted automatically. + +## Related skills + +`purview-zodsharp-custom-rules` for `[ZodRule]` and the built-in rule attributes, +`purview-zodsharp-diagnostics` for the `ZODSGEN` catalogue, and `purview-zodsharp-core` for the +runtime API the generated code reports through. diff --git a/.agents/skills/purview-zodsharp-source-generator/references/dataannotations.md b/.agents/skills/purview-zodsharp-source-generator/references/dataannotations.md new file mode 100644 index 00000000..30e92ec3 --- /dev/null +++ b/.agents/skills/purview-zodsharp-source-generator/references/dataannotations.md @@ -0,0 +1,137 @@ +# DataAnnotations coverage + +The `[ZodSchema]` generator reads `System.ComponentModel.DataAnnotations` attributes and emits +direct, typed codegen. Nothing is reflected at runtime. + +## Supported attributes + +| Attribute | Generated behaviour | Failure code | +| --- | --- | --- | +| `[Required]` | nullable property must not be null; a string with `AllowEmptyStrings=false` must be non-empty | `missing_field` | +| `[Length(min, max)]` | min/max size; strings, arrays (including jagged and rectangular), countable collections | `too_small` / `too_big` | +| `[StringLength(max)]`, `[StringLength(max, MinimumLength=min)]` | string size via direct `.Length` | `too_small` / `too_big` | +| `[MinLength(n)]` | checked only when `n > 0` | `too_small` | +| `[MaxLength(n)]` | checked only when `n >= 0` | `too_big` | +| `[Range(…)]` | inclusive (or exclusive) numeric/parsed bounds | `invalid_range` | +| `[RegularExpression(pattern)]` | compiled `Regex` field, checked on non-empty strings | `invalid_string` | +| `[AllowedValues(…)]` | typed equality against the allowed set | `invalid_value` | +| `[DeniedValues(…)]` | typed equality against the denied set; on an enum property the values are absorbed into the automatic enum rule instead | `invalid_value` | +| `[EmailAddress]` | reuses `ZodSharp.Rules.EmailRule` on non-empty strings | `invalid_string` | +| `[Url]`, `[Phone]`, `[CreditCard]`, `[Base64String]` | reuse `UrlRule`, `PhoneRule`, `CreditCardRule`, `Base64StringRule` | `invalid_string` | +| `[Compare(otherProperty)]` | typed equality between two properties | `mismatch` | +| `[Display(Name=…)]` | not validated; `Name` is the display name in messages and `{0}` placeholders | — | + +`[Length]` follows DataAnnotations null semantics: `null` is valid unless `[Required]` is also +present. + +`[RequiredZod]` — the generated `RequiredRule` attribute — mirrors `[Required]`: it is emitted +*outside* the generator's non-null guard, so an absent value is reported as `missing_field` even +though every other rule bound to the member is skipped for `null`. Its `AllowEmptyStrings` has the +same meaning as `RequiredAttribute.AllowEmptyStrings`, and it adds `TrimWhitespace`, so it is a +drop-in replacement. + +## Positional records + +A positional record declares its properties from the primary-constructor parameter list, and the C# +compiler applies an attribute valid on both a parameter and a property **to the parameter only**. The +generator therefore reads attributes on the synthesized property *and* on the primary-constructor +parameter: + +```csharp +[ZodSchema] +public sealed record RepositoryInventorySummary( + [NonSentinel] string Name, + [NonSentinel] string CanonicalReference, + [NullOrNonWhiteSpace] string? DefaultBranch, + [NonSentinel] DateTimeOffset LastObservedAt +); +``` + +`[property: NonSentinel]` is equally honoured. When both targets carry the same attribute type the +property target wins and the rule runs **once**. Declared properties, classes and record structs are +unaffected. + +## Size validators and structured issues + +Size attributes generate direct `Length`/`Count` access where possible: + +- `string` → `.Length` +- arrays, including rectangular → `.Length` +- jagged arrays → outer-array `.Length` +- countable collections → `.Count` +- `IEnumerable` / `IEnumerable` → one counted pass via `CollectionCountHelper.GetCount`, with fast + paths for `ICollection`, `IReadOnlyCollection` and non-generic `ICollection` + +A structured size failure carries the same metadata as the runtime API: `Code` (`too_small` / +`too_big`), `Origin` (`string` for strings, `array` for arrays, `collection` for countable and +`IEnumerable` collections), `Minimum`/`Maximum` (the inclusive bound), `Inclusive` (`true`) and +`Path`. + +```csharp +[ZodSchema] +public sealed class Basket +{ + [Required] + [Length(2, 5)] + public List? Items { get; set; } +} + +var result = BasketSchema.Validate(new Basket { Items = ["apple"] }); +// Code == "too_small", Minimum == 2, Origin == "array", Inclusive == true +``` + +## `[Range]` + +Three constructor shapes, plus `MinimumIsExclusive`, `MaximumIsExclusive`, +`ConvertValueInInvariantCulture` and `ParseLimitsInInvariantCulture`: + +- `[Range(int, int)]` and `[Range(double, double)]` — literal numeric bounds. +- `[Range(typeof(T), "min", "max")]` — parsed bounds for numeric and comparable types. + +Comparable targets include `TimeSpan`, `DateTime`, `DateTimeOffset`, `DateOnly`, `TimeOnly` and +`Version` (which uses `CompareTo`), plus any `IComparable` with user-defined comparison operators. +Bounds are emitted as static typed fields and compared without running the attribute at runtime. + +## Error messages + +`ErrorMessage`, or `ErrorMessageResourceName` + `ErrorMessageResourceType`, are honoured, with `{0}` +(display name), `{1}` and `{2}` (bound) formatted through +`string.Format(CultureInfo.CurrentCulture, …)`. Supplying only one half of the resource name/type +pair is `ZODSGEN005`. + +## Applicability is a compile error, not a silent skip + +- `[Length]` with `min > max` → `ZODSGEN003`. +- `[Length]` on an unsupported target, such as `decimal` → `ZODSGEN004`. +- String-only attributes (`[RegularExpression]`, `[EmailAddress]`, `[Url]`, `[Phone]`, + `[CreditCard]`, `[Base64String]`) on a non-string, `[AllowedValues]`/`[DeniedValues]` on an + unsupported type, or `[Range]` on an unsupported type → `ZODSGEN006`. +- `[Compare]` naming an unknown property → `ZODSGEN020`. + +## Built-in rule attributes + +Every built-in rule ships a generated attribute in the `ZodSharp.Rules` namespace, usable alongside +the DataAnnotations above: + +`[Email]`, `[E164]`, `[Ulid]`, `[Uuid]`, `[Jwt]`, `[IpAddress]`, `[Hex]`, `[Regex]`, `[StartsWith]`, +`[EndsWith]`, `[Includes]`, `[MultipleOf]`, `[Finite]`, `[SafeInteger]`, `[Int]`, `[Uri]`, +`[Base64Url]`, `[Nanoid]`, `[Cuid2]`, `[DateString]`, `[DatetimeString]`, `[TimeString]`, `[Emoji]`, +`[Xid]`, `[Ksuid]`, `[Duration]`, `[Guid]`, `[Cidr]`, `[NonSentinel]`, `[NullOrNonWhiteSpace]`, +`[MinValue]`, `[MaxValue]`, `[GreaterThan]`, `[LessThan]`, `[GreaterThanOrEqual]`, +`[LessThanOrEqual]`, `[Even]`, `[Odd]`, `[Enum]`, `[RequiredZod]`, `[RangeZod]`, `[LengthZod]`, +`[StringLengthZod]`, `[CompareZod]`, `[AllowedValuesZod]`, `[DeniedValuesZod]`. + +A value the rule declares **without a default** becomes a required constructor argument — +`[Regex("…")]`, `[UUID(UuidVersion.V4)]`, `[Uri(UriKind.Absolute)]`, `[MinValue(3)]` — while +defaulted values and `Message`/`Code` stay named properties. A rule with overloaded constructors +mirrors each overload, so `[Uuid]` is the versionless rule and `[UUID(UuidVersion.V4)]` the versioned +one. `[UUID]` also applies to a `Guid` member or a `[Scalar]` type, because a `Guid` *is* a +UUID — which is how a time-ordered identifier is constrained to an RFC version. + +Names colliding with a DataAnnotations attribute take a `Zod` suffix: `[MinLengthZod]`, +`[MaxLengthZod]`, `[UrlZod]`, `[PhoneZod]`, `[CreditCardZod]`, `[Base64StringZod]`, `[RequiredZod]`, +`[RangeZod]`, `[LengthZod]`, `[StringLengthZod]`, `[CompareZod]`, `[AllowedValuesZod]`, +`[DeniedValuesZod]`. + +A custom rule reaches the same pipeline through `[ZodRule(typeof(MyRule))]` on an attribute, or +`[ZodRule]` on the rule to have the attribute generated. diff --git a/.claude/skills/purview-architests-contracts/SKILL.md b/.claude/skills/purview-architests-contracts/SKILL.md new file mode 100644 index 00000000..3484534f --- /dev/null +++ b/.claude/skills/purview-architests-contracts/SKILL.md @@ -0,0 +1,163 @@ +--- +name: purview-architests-contracts +description: Use when enabling or debugging Purview.Architecture.Testing's committed-API and port rules - apiSurface, apiDocumentation, portImplementation and portPurity. Covers capturing and reviewing .config/api-surface.json, reading an added or breaking API change, requiring XML documentation, and keeping an inner-layer port implemented and technology-neutral. +license: MIT +metadata: + product: Purview.Architecture.Testing + repository: purview-dev/architests +--- + +# API contracts and ports + +Dependency rules say which project may reference which. These rules say what the public surface +actually **is**, and whether the interfaces that define a boundary are honest. They read the compiled +assemblies by metadata only and are off by default, because they need a build. + +| Rule | Group | Catches | +| -- | -- | -- | +| `apiSurface` | `apiRules` | The public API differs from the committed baseline | +| `apiDocumentation` | `apiRules` | A public type or member has no XML documentation | +| `portImplementation` | `portRules` | A port in an inner layer has no public implementation | +| `portPurity` | `portRules` | A port's signature names an infrastructure technology | + +```json +"apiRules": { + "enabled": true +}, +"portRules": { + "enabled": true +} +``` + +Each enabled rule becomes its own TUnit test. A disabled group produces no test, so an absent +`apiSurface` test means the group is off, not that the surface is unchecked. + +## The committed baseline + +`.config/api-surface.json` records every public type and member, grouped by project, with the +responsibility recorded for review context. It is the contract: a change to it is a change to what a +consumer may call. + +- **Captured, never hand-written.** `architests api capture` writes it. +- **Canonical.** Projects, types, interfaces and members are sorted; there are no timestamps; line + endings are always `\n`. An unchanged API regenerates byte for byte, so a diff means a real change. +- **Committed.** It is reviewed like code. A pull request that changes it explains why. + +```bash +dotnet tool install --global Purview.Architecture.Testing.Cli + +architests api capture # write the baseline from the current build +architests api check # compare; exit 1 on any difference +``` + +`api check` is the CI gate; `apiSurface` is the same comparison as a test. A missing baseline is +itself an `apiSurface` failure, because the rule would otherwise pass without checking anything. + +`api capture` and `api check` accept `--repository ` and `--baseline `. Unlike the test +run, a command scans the repository's own build output even when `assemblyRules.assemblyRoots` is +empty, because a tool does not run from a test output directory. + +## Reading a baseline failure + +The message names the project, the type or member, and whether it was added, removed or changed. + +- **Added.** The API grew. Run `architests api capture`, inspect the added entries, and commit them + with the feature. Additions are not breaking, but they are still a reviewed contract change. +- **Removed.** The message calls it breaking. Restore the member, or capture the baseline as a + deliberate breaking release and say so in the pull request. +- **Changed.** The shape moved: kind, `sealed`, `abstract`, base type, interfaces, a member's type, or + whether it is static. Treat the same way as a removal until proven otherwise. + +The baseline includes public **nested** types and the SDK's generated `Assembly` marker. +Both are real public metadata; leave them alone. + +## API documentation + +`apiDocumentation` reads the XML documentation file the compiler writes beside each assembly. + +- `requireTypeDocumentation` (default true) requires a `` entry for every public type. +- `requireMemberDocumentation` (default false) extends that to every public member. + +Member documentation is off by default because a record's positional parameters document its +properties through the type's entry; requiring a separate entry per generated property would punish +a correct record. + +A project that ships no XML file is reported once with the fix: set +`true`. The Purview SDK does this already. + +## The port rules + +A **port** is an interface in one of `portRules.categories`, which default to `domain` and +`application`. Those are the layers that own contracts; an interface in `shared` or in an adapter is +not a port by this definition. + +### `portImplementation` + +Every port must have at least one **public implementation** in a production project. An unimplemented +port is either dead or a boundary nobody crossed; both deserve a review. The dependency matrix still +governs where that implementation may live. + +A port implemented only by a consumer (an extension point such as `IArchitectureRule`) fits badly +here: either move it out of the port categories, or record a waiver explaining that the repository +is the contract's publisher, not its implementer. + +### `portPurity` + +A port's property types, return types and parameter types must not name a forbidden prefix. Defaults +cover `Microsoft.EntityFrameworkCore`, `System.Data`, `Microsoft.AspNetCore` and `System.Net.Http`. +Generic arguments count, so `IReadOnlyList` is caught. + +```json +"portRules": { + "enabled": true, + "forbiddenTypePrefixes": ["Microsoft.EntityFrameworkCore", "System.Data"] +} +``` + +A port that names a database or an HTTP client is not a boundary; it is a leak. Move the technology +into the adapter and keep the interface in terms the domain understands. + +## Waivers and scope + +All four rules are waivable per project and per rule, like the rest of the set: + +```json +"waivers": [ + { + "project": "Legacy.Api", + "rules": ["apiSurface"], + "reason": "The published surface is frozen for a major version; the next major captures it.", + "reviewedOn": "2026-10-18" + } +] +``` + +Prefer a narrower setting when the whole repository shares the exception: +`apiRules.requireMemberDocumentation: false`, a different `portRules.categories`, or a longer +`forbiddenTypePrefixes` list. + +## CI + +```yaml +- run: architests api check +``` + +`api check` needs a build but no test run. In the test suite, `apiSurface` does the same comparison, +so a repository that runs its architecture tests does not need the command — it is there for a fast +job and for reviewers who want the diff without running TUnit. + +## See it working + +`src/samples/ArchitectureSample` demonstrates all four rules: `Domain.IOrderRepository` is a port +implemented by `Persistence.InMemory` and `Persistence.Json`, `Application` depends only on the port, +and `.config/api-surface.json` is committed for all six projects. + +## Checklist + +- `apiRules.enabled` and `portRules.enabled` are deliberate. +- The baseline is committed, canonical, and regenerated after every intended API change. +- A removed or changed member is called out as breaking in the pull request. +- Every public type has a ``, and the project generates its XML documentation. +- Ports live in an inner layer, are implemented, and name no infrastructure technology. +- A waiver names one project and one rule, with a reason and a review date. + diff --git a/.claude/skills/purview-architests-extending/SKILL.md b/.claude/skills/purview-architests-extending/SKILL.md new file mode 100644 index 00000000..96267b20 --- /dev/null +++ b/.claude/skills/purview-architests-extending/SKILL.md @@ -0,0 +1,123 @@ +--- +name: purview-architests-extending +description: Use when adding a bespoke rule to Purview.Architecture.Testing, implementing IArchitectureRule, or working on the package's internals - the three-layer design, the project graph, the metadata-only assembly reader, or the evaluator. Covers the ArchitectureContext, what an additional rule gets for free, and testing a rule against an in-memory fixture. +license: MIT +metadata: + product: Purview.Architecture.Testing + repository: purview-dev/architests +--- + +# Extending Purview.Architecture.Testing + +A repository can add a bespoke check without a second architecture framework. This skill covers the +extension point and the internals a rule is built on. To *consume* the package — adopting it, +writing a policy, reading a failure — use the `purview-architests` skill instead. + +## Add a rule + +Implement `IArchitectureRule` and list it in `AdditionalRules`: + +```csharp +using Purview.Architecture.Testing; + +[InheritsTests] +public sealed class ArchitectureTests : PurviewArchitectureTests +{ + protected override IReadOnlyList AdditionalRules => [new NoConsoleLoggingRule()]; + + sealed class NoConsoleLoggingRule : IArchitectureRule + { + public string Rule => "noConsoleLogging"; + + public IReadOnlyList Evaluate(ArchitectureContext context) => + context.Projects.Values + .Where(project => !project.IsTestProject) + // ...inspect the project or its assembly... + .Select(project => new ArchitectureViolation(Rule, project.Name, "Console logging is banned here.")) + .ToArray(); + } +} +``` + +The `Rule` id is the key everywhere: it names the generated test, it is what `SkipRule` receives, and +it is what a waiver's `rules` array matches. + +## What the context gives you + +`ArchitectureContext` carries the three inputs a rule can need: + +| Member | What it is | +| -- | -- | +| `Policy` | The parsed `ArchitecturePolicy`, so a rule reads the same definition the built-in rules do. | +| `Projects` | The project graph, keyed by project name, with declared references, packages, framework references and analyzers. | +| `Assemblies` | The compiled assemblies, keyed by project name, each with the external types it references. Empty when `assemblyRules.enabled` is false. | + +`ArchitecturePolicy.Classify(projectName)` is the classification every built-in rule uses — the first +segment of the project name, honouring aliases and a waiver's `mapsTo`. Use it so a custom rule +agrees with the standard set. + +## What an additional rule gets for free + +- **Its own `[Test]`.** Each rule id becomes a case of + `AdditionalRule_GivenTheRepository_RespectsThePolicy`, so a failure names the rule rather than + collapsing into one assertion. +- **`SkipRule`.** Override `SkipRule` and return `true` for the rule id. +- **Waivers.** A waiver whose `rules` names the rule id is honoured automatically, so a reviewed, + per-project departure needs no code. +- **Reporting.** `ArchitecturePolicyEvaluator.Report` renders the violations, and the failure's + `.Because(...)` lists every one. + +A violation's `Project` must be the project name (or the offender a waiver can name), and its `Rule` +must be the rule id, or the waiver filter cannot match it. + +## Test the rule against a fixture + +The evaluator takes an in-memory graph, so a rule is tested as a small fixture rather than a +repository on disk — exactly how the package's own rules are tested: + +```csharp +var evaluator = new ArchitecturePolicyEvaluator( + policy, + projects, + assemblies, + [new NoConsoleLoggingRule()] +); + +await Assert.That(evaluator.EvaluateAdditionalRule("noConsoleLogging")).IsEmpty(); +``` + +`ArchitecturePolicyEvaluator` also has a two-argument constructor for project-only rules, and a +four-argument one when the rule needs the assembly graph. + +## The three layers (non-negotiable) + +Keep the separation, because it is what makes a rule testable: + +- **`ArchitecturePolicy` / `ProjectGraph` / `AssemblyGraph`** — read the policy, the `.csproj` graph + and the compiled assembly metadata. **No MSBuild and no test-framework types.** +- **`ArchitecturePolicyEvaluator`** — the rules, returning typed `ArchitectureViolation` lists. It + takes an **in-memory graph**, so a rule is testable as a small fixture. +- **`PurviewArchitectureTests`** — the TUnit wrapper, one `[Test]` per rule. + +Every new rule must be evaluable from an in-memory fixture and asserted by a small +`ArchitectureTesting.UnitTests` test. + +## Reading assemblies + +- Read compiled assemblies by **metadata only** (`System.Reflection.Metadata`). Never `Assembly.Load` + or any API that executes code or needs a probing path. +- The `TypeReference` table is the dependency set: base types, interfaces, generic arguments, + signatures, attributes and method-body uses all appear there. +- Attribute an assembly to a project by the SDK's generated `Assembly` marker, falling + back to an exact project-name match. An assembly that maps to no project is a package and is + ignored — a package is never a project. +- Resolve references against the set of assemblies actually scanned, never by name guessing. + +## Repository conventions + +- TUnit on Microsoft.Testing.Platform. No xUnit, NUnit, MSTest or FluentAssertions. +- Tests use AAA and `Subject_Scenario_Expectation` naming, and must pass on Windows, Linux and macOS. +- `architecture-policy.schema.json` at the repository root is both the published schema and the + resource embedded in the package. Never keep a second copy. +- The repository applies its own package to itself (`src/tests/Repository.UnitTests`), with the + sample at `src/samples/ArchitectureSample` showing consumer adoption. diff --git a/.claude/skills/purview-architests-migration/SKILL.md b/.claude/skills/purview-architests-migration/SKILL.md new file mode 100644 index 00000000..d2b5063b --- /dev/null +++ b/.claude/skills/purview-architests-migration/SKILL.md @@ -0,0 +1,143 @@ +--- +name: purview-architests-migration +description: Use when adopting Purview.Architecture.Testing in an existing repository that already has tangled dependencies, or when ratcheting an adopted policy tighter. Covers a permissive first policy, committing the API baseline before enforcing it, recording narrow waivers instead of using SkipRule, starting an empty dependency budget, and tightening one rule at a time without a big-bang rewrite. +license: MIT +metadata: + product: Purview.Architecture.Testing + repository: purview-dev/architests +--- + +# Migrating an existing repository + +A policy that describes the architecture you wish you had fails on day one and gets switched off. +Adopt the architecture you **do** have, then tighten it one reviewed step at a time. The rules are +the same either way; only the policy and the waivers change. + +## 1. Inventory before writing the policy + +- List every production project and what it references. `architests graph` prints the graph once the + policy can find the projects. +- Group projects into responsibilities that describe what they are for, not where they sit. A + qualified name (`Persistence.SqlServer`) belongs to `Persistence`; only the first segment counts. +- Name the composition root with `category: "composition"` and hosts with `category: "host"`, so the + composition boundary works without special cases. + +## 2. A permissive first policy + +Start with the full dependency closure permitted. The first run should fail only on things you are +ready to fix — usually naming. + +```json +{ + "version": 3, + "sourceRoots": ["src"], + "responsibilities": [ + { + "name": "Domain", + "category": "domain", + "purpose": "The domain model and its invariants.", + "mayDependOn": ["Application", "Persistence", "Composition"], + "mustNotDependOn": [] + } + ] +} +``` + +Set `sourceRoots` correctly first: an empty graph makes every rule pass vacuously, which is why +`graphDiscovery` fails instead. + +## 3. Add the test class once + +```csharp +[InheritsTests] +public sealed class ArchitectureTests : PurviewArchitectureTests; +``` + +`[InheritsTests]` is load-bearing. Without it the run is green and nothing is checked. + +## 4. Record the API before enforcing it + +If the public API is already shipped, capture it before enabling `apiRules`: + +```bash +architests api capture +``` + +Then enable the group. The first `apiSurface` run compares against the API you actually have, so it +passes, and every later change becomes a reviewed diff. Do the same for the sample or any package in +the repository. + +## 5. Waivers, not skips + +When a rule finds a real departure you cannot fix today, record it: + +```json +"waivers": [ + { + "project": "Legacy.Utilities", + "mapsTo": "Shared", + "rules": ["naming"], + "reason": "The package id is published; renaming it is a separate breaking release.", + "reviewedOn": "2026-10-18" + } +] +``` + +- `mapsTo` keeps every dependency rule in force; only the name is excused. +- Excuse one rule, not the whole set. +- Set `waiverPolicy.maxAgeDays` so a waiver has to be renewed. An unreviewed waiver is how a policy + quietly stops being true. + +`SkipRule` removes a rule for the whole repository with no record. Treat it as a last resort, never +as the adoption strategy. + +## 6. Start the dependency budget empty + +```json +"dependencyBudget": { + "enabled": true, + "failOnStale": true, + "entries": [] +} +``` + +The rule is enabled and checks nothing, which is exactly right: the mechanism is in place. Add an +entry for one project at a time, listing only the references it has today. From then on a new +reference needs a reviewed policy change, and a removed one must be removed from the budget. + +## 7. Tighten one step at a time + +Each step is a small pull request that keeps the suite green: + +1. **Naming.** Add aliases or waivers, then rename projects in a dedicated change. +2. **Forbidden packages.** Add one prefix to one responsibility, fix the violations, repeat. +3. **Dependency direction.** Move a single edge from `mayDependOn` to `mustNotDependOn`, or remove it + from `mayDependOn` entirely so silence becomes a violation. +4. **Type rules.** Enable `typeRules` for one category with `sealConcreteClasses` and generated-code + exclusions, fix, then widen the scope. +5. **Ports.** Move an interface into `domain` or `application` only when its implementation lives in + an adapter and its signature is technology-neutral. +6. **Reachability.** Turn on `policyIntegrity.checkReachability` once the matrix is honest; it will + find prohibitions the permitted closure bypasses. + +A rule that cannot pass even with waivers is telling you the policy is wrong, not the code. Change +the policy. + +## Reading a failure during migration + +- `naming` — add an alias for an established name, or a waiver with `mapsTo`. +- `dependencyMatrix` / `assemblyDependencyMatrix` — the message names the reference, the direction + and the likely fix. Prefer moving a type over widening `mayDependOn`. +- `apiSurface` — expected after any intentional API change: run `architests api capture` and review + the diff before committing. +- `dependencyBudget` — a new reference is over budget; a stale allowance needs removing. +- `policyIntegrity` — the policy contradicts itself; fix the policy before the code. + +## Checklist + +- `sourceRoots` finds the projects, and `graphDiscovery` passes. +- The matrix describes today's graph, not the target graph. +- The API baseline is committed before `apiRules` is switched on. +- Every departure is a narrow, dated waiver rather than a skip. +- The dependency budget starts empty and grows one reviewed entry at a time. +- Each tightening step is its own pull request, with the suite green. diff --git a/.claude/skills/purview-architests-policy-authoring/SKILL.md b/.claude/skills/purview-architests-policy-authoring/SKILL.md new file mode 100644 index 00000000..9f1f2f52 --- /dev/null +++ b/.claude/skills/purview-architests-policy-authoring/SKILL.md @@ -0,0 +1,190 @@ +--- +name: purview-architests-policy-authoring +description: Use when authoring or changing .config/architecture-policy.json for Purview.Architecture.Testing - defining responsibilities, categories, mayDependOn and mustNotDependOn, choosing sourceRoots, adding aliases, recording a waiver, setting waiver expiry, or fixing a policyIntegrity failure. Covers the version-3 document, the matrix semantics, and how to validate a policy without running the tests. +license: MIT +metadata: + product: Purview.Architecture.Testing + repository: purview-dev/architests +--- + +# Authoring an architecture policy + +The policy is the definition of the architecture. The tests only report what it says, so a vague or +contradictory policy produces a vague or contradictory suite. This skill is about getting the +document right; to *adopt* the package or read a failure, use `purview-architests` instead. + +## The shape + +`.config/architecture-policy.json` at the repository root: + +```json +{ + "$schema": "https://raw.githubusercontent.com/purview-dev/architests/main/architecture-policy.schema.json", + "version": 3, + "description": "What this repository's architecture is.", + "sourceRoots": ["src"], + "responsibilities": [ + { + "name": "Core", + "aliases": ["Domain"], + "category": "domain", + "purpose": "The domain model, its invariants and its rules.", + "mayDependOn": [], + "mustNotDependOn": ["Application", "Persistence", "Composition"], + "forbiddenFrameworkReferences": ["Microsoft.AspNetCore.App"] + } + ] +} +``` + +`version` and `responsibilities` are required. Everything else is optional. Version 3 adds +`policyIntegrity` and `waiverPolicy`; both are optional, so a version-2 document remains valid. + +## Responsibilities + +A project name is `[.]`, and only the **first segment** is +classified. `Persistence.SqlServer` and `Persistence` are both Persistence: qualification is a +naming choice, never a different set of rules. + +| Field | Guidance | +| -- | -- | +| `name` | One PascalCase segment. Name the role, not the technology. | +| `aliases` | Existing names you are not renaming. Prefer renaming and deleting the alias. | +| `category` | `domain`, `application`, `infrastructure`, `composition`, `host` or `shared`. `composition` is the exemption `compositionBoundary` keys on; `host` may also reference it. | +| `purpose` | At least 20 characters, and quoted in failures. Write why the responsibility exists; "misc" is not a purpose. | +| `mayDependOn` | The complete set of permitted references. Silence is not permission. | +| `mustNotDependOn` | Prohibitions that matter. Must not overlap `mayDependOn`. | +| `forbiddenPackagePrefixes` | NuGet prefixes that must never appear, such as `Microsoft.EntityFrameworkCore`. | +| `forbiddenPackageScope` | `own` (default) reports packages the project declares or its own packages pull in; `closure` also reports packages inherited from project references. | +| `forbiddenFrameworkReferences` | Framework prefixes, such as `Microsoft.AspNetCore.App` in a portable layer. | +| `siblingIndependence` | When true, qualified implementations of this responsibility must not reference each other. | + +Avoid names that describe a category. `Infrastructure`, `Services`, `Helpers`, `Common`, +`Utilities` and `Managers` are discouraged because nothing can be kept out of them. + +## The matrix is three-way + +For every declared reference, and for every type reference in the compiled assemblies: + +1. **Same responsibility** is always allowed. +2. **`mustNotDependOn`** is a violation. +3. **`mayDependOn`** is permitted. + +Anything else is a violation. That is deliberate: an unclassified dependency is a gap in the +policy, not an implicit yes. When a new edge is genuinely intended, add it to `mayDependOn` — that +is a reviewed policy change, which is the point. + +## Policy integrity + +`policyIntegrity` always runs and cannot be waived. It catches what the schema cannot: + +- a matrix entry that names no responsibility (aliases and project names are not names here); +- the same responsibility in both `mayDependOn` and `mustNotDependOn`; +- two responsibilities with the same name; +- an alias equal to a name, or two responsibilities claiming the same alias; +- with `checkReachability`, a prohibition the permitted dependencies can reach anyway. The failure + prints the path, such as `Core -> Application -> Persistence`, so the edge to remove is obvious. + +```json +"policyIntegrity": { + "checkReachability": true +} +``` + +Reachability is opt-in because it is the stronger claim: the lists can be consistent while a longer +permitted path still defeats the prohibition. + +## Waivers + +A waiver is a reviewed departure, not a skip: + +```json +"waivers": [ + { + "project": "Legacy.Utilities", + "mapsTo": "Shared", + "rules": ["naming"], + "reason": "Predates the catalogue; renaming breaks a published package identifier.", + "reviewedOn": "2026-10-18" + } +] +``` + +- `mapsTo` is the useful part: the project keeps its real responsibility, so every dependency rule + still applies and only the **name** is excused. +- Excuse the narrowest rule that applies. A waiver listing everything is a policy opt-out. +- `policyIntegrity`, `graphDiscovery` and `waiverIntegrity` cannot be waived; naming one is a + `waiverIntegrity` failure. + +### Expiry + +```json +"waiverPolicy": { + "maxAgeDays": 180 +} +``` + +A waiver older than the maximum is a `waiverIntegrity` failure. So are an undated waiver while a +maximum is set, a date that is not `yyyy-MM-dd`, and a date in the future. Expiry is off by default; +adopt it deliberately, and expect to renew or delete the waivers it surfaces. + +### Package scope + +`forbiddenPackagePrefixes` measures **ownership** by default: what the project declares, what a +shared props file injected, and what its own package references pull in. A package inherited through +a permitted project reference is not owned, so a host is not reported for its adapter’s EF Core. + +Use `"forbiddenPackageScope": "closure"` only when the policy means “this technology must not be +anywhere on the compile graph”. That makes hosts responsible for every package their adapters bring +in, and usually requires the adapter to mark implementation packages `PrivateAssets="compile"`. + +## Dependency budget + +`dependencyBudget` ratchets the project graph: it records the references each project may declare +today, so growth is a reviewed policy change. + +```json +"dependencyBudget": { + "enabled": true, + "failOnStale": true, + "entries": [ + { "project": "Application", "references": ["Domain"] }, + { "project": "Persistence.SqlServer", "references": ["Domain", "Application"] } + ] +} +``` + +- An entry lists **project names**, exactly as they appear on disk, including the qualification: + `Persistence.SqlServer`, not `Persistence`. +- A reference outside the entry is a failure. Remove it, or add it in the same reviewed commit that + adds the `ProjectReference`. +- With `failOnStale` (default true), an allowance the project no longer uses is a failure. Tighten the + budget rather than leaving a permission nobody needs. +- A project with no entry is not budgeted. Start with `entries: []`, then add one project at a time. +- The rule is not waivable; changing the budget is the sanctioned way to change the graph. + +## Validate the policy + +```bash +dotnet tool install --global Purview.Architecture.Testing.Cli +architests validate +architests waivers list --stale +``` + +`validate` runs the schema check and `policyIntegrity` without a build; `waivers list --stale` exits +non-zero when a waiver is due. Exit codes: `0` clean, `1` findings, `2` a malformed command line. +Both commands accept `--repository `. + +The test suite runs the same checks and one test per rule, so a policy that passes the tool can +still fail a matrix rule — that failure is an architecture decision, not a document error. + +## Checklist + +- Every responsibility has a purpose that says what it is for, not what it uses. +- Every dependency that exists is either permitted or forbidden; nothing is left unclassified. +- `mustNotDependOn` entries are not also in `mayDependOn`. +- Names are roles, not categories, and no alias duplicates a name. +- Waivers are narrow, justified, dated, and none is due. +- `policyIntegrity.checkReachability` is on before claiming a prohibition is enforced. +- A version bump is deliberate: adding optional sections does not require one. + diff --git a/.claude/skills/purview-architests-type-rules/SKILL.md b/.claude/skills/purview-architests-type-rules/SKILL.md new file mode 100644 index 00000000..1d933788 --- /dev/null +++ b/.claude/skills/purview-architests-type-rules/SKILL.md @@ -0,0 +1,188 @@ +--- +name: purview-architests-type-rules +description: Use when enabling or debugging Purview.Architecture.Testing's type-level rules - typeNaming, typeShape, typeNamespace and attributePolicy. Covers the typeRules policy section, which public types are governed, why a type is reported as unsealed or outside its root namespace, how generated code and nested types are treated, and how to fix or waive each finding. +license: MIT +metadata: + product: Purview.Architecture.Testing + repository: purview-dev/architests +--- + +# Type-level naming, shape and namespace rules + +These rules police the **public surface** a project compiles, not its dependencies. They read the +compiled assembly by metadata only: no assembly is loaded, no code runs, and no source file is +needed. Enable them when the API a consumer receives matters as much as the direction its +references run. + +For dependency direction, use the `purview-architests` skill. This skill covers `typeNaming`, +`typeShape`, `typeNamespace` and `attributePolicy`. + +## Enable them + +They are off by default, because they need a build to have produced the assemblies: + +```json +{ + "assemblyRules": { "enabled": true }, + "typeRules": { + "enabled": true, + "appliesTo": { "categories": ["domain", "application", "shared"] }, + "excludeGeneratedCode": true + } +} +``` + +- An empty `appliesTo.categories` governs **every production responsibility**. +- Test projects are never governed. +- `assemblyRules` and `typeRules` scan the same assemblies. `assemblyRoots` and `assemblyGlobs` live + under `assemblyRules` and apply to both; an empty `assemblyRoots` scans the test output directory. +- Only **public** types are checked, including public nested types. Internal and private types are + outside the API and are left alone. + +## What the four rules catch + +| Rule | Catches | +| -- | -- | +| `typeNaming` | An interface without `I`, an attribute without `Attribute`, an exception without `Exception`, a discouraged suffix (`Manager`, `Helper`, `Util`, `Impl`) | +| `typeShape` | An unsealed public class, a public instance field, a mutable collection return, a misnamed exception, a utility class that is not static | +| `typeNamespace` | A public type outside the project's `RootNamespace` | +| `attributePolicy` | A missing required attribute, a forbidden attribute, `[Obsolete]` without a message, `InternalsVisibleTo` naming production code | + +Each enabled rule becomes its own TUnit test. A disabled group produces **no** type-rule test rather +than a test that checks nothing, so a green run cannot mean "the group was off". + +## Governing a subset + +`appliesTo.categories` is the usual scope. A composition root is often excluded because it is allowed +to reference everything: + +```json +"appliesTo": { "categories": ["domain", "application", "infrastructure", "shared"] } +``` + +Generated code is skipped by default. A source generator must not be forced to change its output: + +```json +"excludeGeneratedCode": true, +"excludeNamespacePrefixes": ["Contoso.Generated"] +``` + +A type marked `[GeneratedCode]` or `[CompilerGenerated]` is skipped, as is any type under an excluded +namespace prefix. + +## Type naming + +- An interface name must start with `I` followed by an uppercase letter: `IOrderRepository`. +- A class deriving from `System.Attribute` must end with `Attribute`. +- A class deriving from an exception must end with `Exception`. +- A type ending with a configured `discouragedTypeSuffixes` entry is reported. The default list + names mechanisms, not responsibilities. Configure it to match the repository's vocabulary. + +Generic arity is removed before the check, so `IRepository` is checked as `IRepository`. + +## Type shape + +- **Unsealed public class.** A public concrete class must be `sealed` unless it is `abstract`. An + unsealed class is a public extension point nobody declared; seal it, or make the base type explicit. +- **Public instance field.** Constants and static readonly fields are fine; an instance field cannot + validate or evolve without a breaking change. +- **Mutable collection return.** A public property or method returning `List` or + `Dictionary` hands the caller the owner's state. Return `IReadOnlyList` or + `IReadOnlyDictionary`. +- **Misnamed exception.** A class named `...Exception` must derive from `System.Exception`. +- **Utility class.** A class with only static members and no public constructor must be declared + `static`, so it cannot be instantiated by accident. + +Turn off either check in the policy when it does not fit: + +```json +"sealConcreteClasses": false, +"requireReadOnlyCollections": false +``` + +## Type namespace + +The rule compares the type's declared namespace with the project's `RootNamespace`, read from the +`.csproj`: the namespace must equal it or start with it followed by a dot. + +Metadata records the namespace, not the file path, so the rule **cannot** check that the folder +matches. It deliberately makes no such claim. + +Set `RootNamespace` explicitly when it differs from the project name: + +```xml +Purview.Architecture.Testing +``` + +Without it, the project name is used, which is the SDK's own fallback. + +## Attribute policy + +| Setting | Default | Effect | +| -- | -- | -- | +| `requiredAttributes` | `[]` | Namespace-qualified attributes every governed public type must carry | +| `forbiddenAttributes` | `[]` | Namespace-qualified attributes no governed public type may carry | +| `allowObsoleteWithoutMessage` | `false` | Permit `[Obsolete]` with no message | +| `forbidInternalsVisibleToProduction` | `true` | Reject `InternalsVisibleTo` naming a production assembly | + +`[Obsolete("Use IOrderStore instead.")]` is fine. A bare `[Obsolete]` is reported: a caller is told +the type is going away but not what to do about it. + +`InternalsVisibleTo` is checked at assembly level. A friend that maps to a **test** project is +ordinary; a friend that maps to a **production** project is a boundary leak, because the referenced +project can now see internals it was never meant to depend on. Expose a public abstraction instead. + +## Fix or waive + +Fix the type when the rule is right; rename it, seal it, return a read-only interface, or move it +under the root namespace. + +A waiver is per project and per rule, and the project field is the **project name** the assembly +belongs to: + +```json +"waivers": [ + { + "project": "Persistence", + "rules": ["typeShape"], + "reason": "The EF entity must stay inheritable for the proxy; sealing it breaks materialisation.", + "reviewedOn": "2026-10-18" + } +] +``` + +Prefer the narrow settings when the whole repository shares an exception: `excludeNamespacePrefixes` +for generated code, `sealConcreteClasses` for a codebase that uses inheritance as a feature, or +`appliesTo.categories` to leave the composition root out. + +## Troubleshooting + +- **No type-rule tests at all.** `typeRules.enabled` is false, or the policy failed to load. The + group produces no test rather than a vacuous pass, so this is visible in the test list. +- **A rule reports nothing and you expected findings.** The projects were not built, or the + assembly was not in the scan root. Type rules use `assemblyRules.assemblyRoots`; an empty value + scans the test output directory, so the test project must reference the projects it governs. +- **A type you expected is missing.** It is internal, nested inside an internal type, marked as + generated, under an excluded namespace, in a test project, or in a responsibility outside + `appliesTo.categories`. +- **`typeNamespace` reports everything.** The project has no `RootNamespace` and its namespace is + not the project name. Set `RootNamespace` explicitly. +- **A public API baseline is also enabled.** Type-rule findings are API-shape findings; fix them + before regenerating a baseline, or the baseline records the problem. + +## See it working + +`src/samples/ArchitectureSample` enables `typeRules` for the `domain`, `application`, `infrastructure` +and `shared` categories. Its projects declare `RootNamespace` explicitly, its classes are sealed, its +collections are exposed as `IReadOnlyList`, and `IOrderRepository` follows the interface +convention. + +## Checklist + +- `typeRules.enabled` is true and the categories are deliberate. +- Every governed public class is sealed or abstract, unless `sealConcreteClasses` is off. +- No public instance fields or mutable collection returns are exposed. +- `RootNamespace` is set on projects whose namespace differs from their name. +- Generated code is excluded by attribute or namespace, not by loosening the rule. +- Every waiver names one project and one rule, with a reason and a review date. + diff --git a/.claude/skills/purview-architests/SKILL.md b/.claude/skills/purview-architests/SKILL.md new file mode 100644 index 00000000..dd9d5db6 --- /dev/null +++ b/.claude/skills/purview-architests/SKILL.md @@ -0,0 +1,354 @@ +--- +name: purview-architests +description: Adopt or debug Purview.Architecture.Testing, the package that enforces a repository's project and type-level dependency policy as TUnit tests. Use when adding architecture tests to a repository, writing or changing .config/architecture-policy.json, validating a policy with the architests tool, enabling the assembly, type, API or port rules, recording or expiring a waiver, setting a dependency budget, interpreting a policy-integrity, dependency-matrix, type-level, cycle, sibling-independence, composition-boundary, forbidden-package, framework-reference or naming failure, or when the architecture tests pass but enforce nothing. +license: MIT +metadata: + product: Purview.Architecture.Testing + repository: purview-dev/architests +--- + +# Architecture tests with Purview.Architecture.Testing + +The package defines the rules once so a policy is not copied into every repository's test project. + +## Adoption is two things + +**1. A policy file** at `.config/architecture-policy.json`: + +```json +{ + "$schema": "https://raw.githubusercontent.com/purview-dev/architests/main/architecture-policy.schema.json", + "version": 3, + "sourceRoots": ["src"], + "responsibilities": [ + { + "name": "Core", + "aliases": ["Domain"], + "category": "domain", + "purpose": "The domain model, its invariants and its rules.", + "mayDependOn": [], + "mustNotDependOn": ["Application", "Persistence"], + "forbiddenFrameworkReferences": ["Microsoft.AspNetCore.App"] + } + ] +} +``` + +**2. One derived test class:** + +```csharp +[InheritsTests] +public sealed class ArchitectureTests : PurviewArchitectureTests; +``` + +## `[InheritsTests]` is load-bearing + +TUnit does **not** walk base types during discovery. Without the attribute the class compiles, the +run is green, and nothing is enforced — the worst failure this package can have. + +TUnit's analyzer reports `TUnit0030` when it is missing. Treat it as an error, not a suggestion. + +If the architecture tests "pass" but you cannot name which rule ran, check this first. + +## The rules + +| Rule id | Test | What it catches | +| -- | -- | -- | +| `policyIntegrity` | `Policy_GivenItsOwnDefinitions_IsConsistent` | An unknown responsibility name, a dependency both permitted and forbidden, or a duplicate name or alias. Not waivable | +| `graphDiscovery` | `Repository_GivenItsSourceRoots_YieldsProjectsToCheck` | An empty graph — which satisfies every other rule | +| `naming` | `ProductionProjects_GivenTheirNames_MapToAResponsibility` | A project name matching no responsibility or alias | +| `discouragedName` | `ProductionProjects_GivenTheirNames_AvoidCatchAllNames` | A project named after a category, so nothing can be kept out of it | +| `dependencyMatrix` | `ProductionProjects_GivenTheirReferences_RespectTheDependencyMatrix` | A declared `ProjectReference` the matrix forbids or does not permit | +| `assemblyDependencyMatrix` | `AssemblyTypes_GivenTheirReferences_RespectTheDependencyMatrix` | A **type** in one responsibility using a type in another, including a dependency that only arrives transitively or through a package | +| `typeNaming` | `TypeRules_GivenTheRepository_RespectThePolicy` | A public interface without `I`, an attribute or exception without its suffix, or a discouraged suffix | +| `typeShape` | `TypeRules_GivenTheRepository_RespectThePolicy` | An unsealed public class, a public field, a mutable collection return, or a non-static utility class | +| `typeNamespace` | `TypeRules_GivenTheRepository_RespectThePolicy` | A public type outside the project's root namespace | +| `attributePolicy` | `TypeRules_GivenTheRepository_RespectThePolicy` | A missing or forbidden attribute, `[Obsolete]` without a message, or `InternalsVisibleTo` naming production code | +| `apiSurface` | `APIRules_GivenTheRepository_RespectThePolicy` | The public API differs from the committed baseline | +| `apiDocumentation` | `APIRules_GivenTheRepository_RespectThePolicy` | A public type or member has no XML documentation | +| `portImplementation` | `PortRules_GivenTheRepository_RespectThePolicy` | A port in an inner layer has no implementation | +| `portPurity` | `PortRules_GivenTheRepository_RespectThePolicy` | A port exposes an infrastructure technology | +| `dependencyBudget` | `AdoptionRules_GivenTheRepository_RespectThePolicy` | A project references beyond its budget, or the budget still allows a reference that has gone | +| `siblingIndependence` | `SiblingImplementations_GivenTheirReferences_DoNotDependOnEachOther` | A qualified implementation referencing a qualified sibling | +| `compositionBoundary` | `Implementations_GivenTheirReferences_DoNotDependOnComposition` | A non-host project referencing the composition root (`category == "composition"`) | +| `forbiddenPackage` | `ProductionProjects_GivenTheirPackages_AvoidForbiddenFrameworkDependencies` | A package matching a forbidden prefix for that responsibility | +| `forbiddenFramework` | `ProductionProjects_GivenTheirFrameworkReferences_AvoidForbiddenFrameworks` | A `` matching a forbidden prefix, e.g. `Microsoft.AspNetCore.App` in a portable layer | +| `cycle` | `ProjectGraph_GivenItsReferences_HasNoCycles` | A dependency cycle, reported readably | +| `testReference` | `ProductionProjects_GivenTheirReferences_DoNotReferenceATestProject` | Production code referencing a test project | +| `waiverIntegrity` | `PolicyWaivers_GivenTheirDefinitions_AreJustifiedAndStillApply` | A waiver that is stale, unjustified, malformed, or excuses an unknown rule id | + +A separate test validates the policy against the schema first, because a policy that does not match +its schema may be silently missing a rule. + +## Policy integrity + +`policyIntegrity` always runs and is **not waivable**, so a broken policy cannot be excused. It +reports what a JSON Schema cannot express: + +- a `mayDependOn` or `mustNotDependOn` entry that names no responsibility — aliases and project + names do not count in the matrix; +- the same responsibility in both lists, which is a contradiction rather than a choice; +- two responsibilities with the same name, or an alias that equals a name or another alias; +- with `checkReachability`, a `mustNotDependOn` the permitted `mayDependOn` closure can reach. The + message prints the path, such as `Core -> Application -> Persistence`. + +```json +"policyIntegrity": { + "checkReachability": true +} +``` + +Reachability is opt-in because it is a stronger claim: the direct lists can be consistent while a +longer permitted path still defeats the prohibition. + +## Check it without a test run + +```bash +dotnet tool install --global Purview.Architecture.Testing.Cli +architests validate +architests waivers list --stale +``` + +`validate` runs the schema check and `policyIntegrity`; it needs no build. Exit codes are `0` clean, +`1` findings, `2` a malformed command line. Both commands accept `--repository `; without it +the tool walks up from the current directory and stops at the repository boundary. + +`graphDiscovery` runs before the rules it protects. If `sourceRoots` is wrong, discovery finds +nothing and every other rule passes vacuously — that is what this rule exists to stop. + +## The type-level rule + +A project file only shows a declared `ProjectReference`. `assemblyDependencyMatrix` reads the +compiled assemblies by **metadata only** — no assembly is loaded or executed — and checks every +external type each one references against the same `mayDependOn` / `mustNotDependOn` matrix. It +catches what a project file cannot: a type that only arrives transitively, or through a package. + +```json +"assemblyRules": { + "enabled": true, + "assemblyRoots": [], + "assemblyGlobs": ["*.dll"] +} +``` + +- **Off by default.** It needs a build to have produced the assemblies, so it is opt-in. +- An empty `assemblyRoots` scans the test output directory, which already holds every project the + test project references, directly or transitively. Set it to repo-relative folders only if the + assemblies are somewhere else. +- Semantics mirror `dependencyMatrix`: same-responsibility references are always allowed; a + reference the matrix neither permits nor forbids is a violation. +- Enabled with nothing found is a **failure**, not a silent pass — the same guard `graphDiscovery` + provides for projects. +- Qualified implementations collapse into their responsibility, so `Persistence.SqlServer` is + `Persistence` at the type level too. Qualification is a naming choice, never a different rule. + +Assemblies are attributed to projects by the SDK's generated `Assembly` marker when a +project's `AssemblyName` is unrelated to its name, and by name otherwise. + +## Type naming, shape and namespace + +The same reader exposes the public declarations a project compiles, which powers four opt-in rules: +`typeNaming`, `typeShape`, `typeNamespace` and `attributePolicy`. They are configured under +`typeRules`, off by default, and share the assembly roots and globs above. + +```json +"typeRules": { + "enabled": true, + "appliesTo": { "categories": ["domain", "application", "shared"] } +} +``` + +Use the `purview-architests-type-rules` skill for what each rule catches, why a type is reported, and +how to fix or waive it. A disabled group produces no test, so a missing type-rule test is a policy +setting rather than a silent pass. + +## Classifying test and production projects + +The package decides which projects the rules govern from the project graph: + +- A project is a **test project** when its name ends with `Tests`, **or** its path contains a + `tests` directory. Test projects are excluded from every rule — a test references everything by + design, so applying the matrix to it would make the rule set unusable. +- Everything else is a **production project**, and every rule applies to it. + +## API baseline and ports + +Four more rules are opt-in. `apiRules` compares the public API with a committed baseline and checks +its documentation; `portRules` checks that inner-layer interfaces are implemented and stay +technology-neutral. + +```json +"apiRules": { "enabled": true }, +"portRules": { "enabled": true } +``` + +Write the baseline with the tool, never by hand: + +```bash +architests api capture # write .config/api-surface.json +architests api check # exit 1 on any difference +``` + +A missing baseline is itself an `apiSurface` failure. A removal is reported as breaking; an addition +still needs a reviewed baseline change, because the baseline is the contract. The +`purview-architests-contracts` skill covers the baseline document, documentation requirements and +the port rules in detail. + +## Dependency budget + +`dependencyBudget` is a ratchet on the project graph: it records the references each project may +declare today, so a new dependency needs a reviewed policy change. + +```json +"dependencyBudget": { + "enabled": true, + "failOnStale": true, + "entries": [ + { "project": "Application", "references": ["Domain"] } + ] +} +``` + +- A reference outside the entry is a `dependencyBudget` failure. +- With `failOnStale` (the default), an allowance the project no longer uses fails too, so the budget + only tightens. +- It is **not waivable**, and a project without an entry is not budgeted. +- Start with `entries: []`, then add one project at a time. + +## See it working + +`src/samples/ArchitectureSample` is a six-project repository that exercises every rule group: a port +with two adapters, a waived legacy project, the type rules, the committed baseline and a dependency +budget. Use it as the reference when a policy question is easier to answer from a working example +than from prose. + +## Prefer a waiver to a skip + +```csharp +protected override bool SkipRule(string rule) => rule == ArchitectureRules.DiscouragedName; +``` + +`SkipRule` removes a rule for the whole repository, with no record. A waiver is better: it is per +project, carries a reason and a review date, keeps every other rule in force for that project, and +is itself checked by `waiverIntegrity`. + +```json +"waivers": [ + { + "project": "Legacy.Utilities", + "mapsTo": "Shared", + "rules": ["naming"], + "reason": "Predates the catalogue; renaming breaks a published package id.", + "reviewedOn": "2026-01-14" + } +] +``` + +`mapsTo` is the useful part: it maps an established project onto the responsibility it actually has, +so the dependency rules still apply in full and only the *name* is excused. + +Any waivable rule id may be waived, including `siblingIndependence` and `assemblyDependencyMatrix`. +An unknown id is a `waiverIntegrity` failure, so a typo cannot silently excuse nothing. Naming a +guard (`policyIntegrity`, `graphDiscovery` or `waiverIntegrity`) is also a failure: those rules exist +to keep the policy falsifiable, so a waiver that appears to excuse them would be a lie. + +### Waiver expiry + +```json +"waiverPolicy": { + "maxAgeDays": 180 +} +``` + +A waiver reviewed longer ago than the maximum is a `waiverIntegrity` failure. So are a waiver with +no `reviewedOn` while a maximum is set, a date that is not `yyyy-MM-dd`, and a date in the future. +Expiry is off by default; adopting it turns the review date from a note into an obligation. + +## Adding your own rule + +A repository can add a bespoke check without a second architecture framework. Implement +`IArchitectureRule` and return the same `ArchitectureViolation` type as the built-in rules: + +```csharp +[InheritsTests] +public sealed class ArchitectureTests : PurviewArchitectureTests +{ + protected override IReadOnlyList AdditionalRules => [new NoConsoleLoggingRule()]; + + sealed class NoConsoleLoggingRule : IArchitectureRule + { + public string Rule => "noConsoleLogging"; + + public IReadOnlyList Evaluate(ArchitectureContext context) => + // context.Policy, context.Projects and context.Assemblies + []; + } +} +``` + +Each additional rule becomes its own `[Test]` (`AdditionalRule_GivenTheRepository_RespectsThePolicy`), +so a failure names the rule. It participates in the same failure reporting, `SkipRule` (by its +`Rule` id) and waiver model — a waiver whose `rules` names it is honoured automatically. + +The `purview-architests-extending` skill covers the full extension point and the package's internals. + +## Reading a failure + +Each rule is its own test, so a failure names the rule rather than collapsing the set into one +assertion. The `.Because(...)` text lists every violation the rule found. + +- `naming` — a project name is `[.]`, and only the **first segment** + is classified. `Persistence.SqlServer` and `Persistence` are both Persistence. Add an alias, or a + waiver with `mapsTo`. +- `dependencyMatrix` / `assemblyDependencyMatrix` — fix the reference, or move the type. Widening + `mayDependOn` is the last resort, and it is a policy change that needs review. +- `forbiddenPackage` — by default the package is one the project **owns**: declared, injected by + `Directory.Build.props`, or pulled in by its own package references. A package inherited from a + permitted project reference is not reported, so a host is not blamed for its adapter’s EF Core. + Set `forbiddenPackageScope: "closure"` on the responsibility only when the strict compile-graph + guarantee is intended. +- `forbiddenFramework` — a `` on a project that should not have it. Move it to + the responsibility that owns that technology. +- `graphDiscovery` — almost always a wrong `sourceRoots`. An empty array scans the repository root, + which suits a flat layout. +- `assemblyDependencyMatrix` reporting "no compiled assemblies" — the projects were not built, or + `assemblyRoots` points at the wrong folder. + +## The three layers + +Useful when extending the package rather than consuming it: + +- `ArchitecturePolicy` / `ProjectGraph` / `AssemblyGraph` — read the policy, the `.csproj` graph and + the compiled assembly metadata. No MSBuild and no test-framework types. +- `ArchitecturePolicyEvaluator` — the rules, returning typed `ArchitectureViolation` lists. It takes + an **in-memory graph**, so a rule is tested as a three-project fixture rather than a repository on + disk. +- `PurviewArchitectureTests` — the TUnit wrapper, one `[Test]` per rule. + +Project files are read because a declared `ProjectReference` is what a reviewer adds and what the +policy governs; compiled assemblies are read separately because they catch what the project file +does not show. + +## Overrides + +```csharp +[InheritsTests] +public sealed class ArchitectureTests : PurviewArchitectureTests +{ + protected override string? RepositoryRoot => "/path/to/repo"; +} +``` + +`RepositoryRoot` defaults to probing upward from the test binary for the policy file. The search +**stops at the repository boundary** (`.git`) rather than continuing into parent folders — walking +past it would happily find a sibling checkout's policy and validate this repository against someone +else's rules. + +## Policy schema version + +The current policy document version is **3**. Version 3 adds `typeRules`, `policyIntegrity` and +`waiverPolicy`, all optional, so a version-2 policy remains valid. Version 2 removed the `rules` object +(`noCycles`, `noProductionToTestReferences`, `implementationsMustNotReferenceComposition`, +`siblingImplementationsIndependent`), whose flags were deserialised but never consulted. Use +`SkipRule` or a waiver to opt out of a rule. A version-1 policy that set `rules` must delete the +block; a version-1 policy that did not still validates. diff --git a/.claude/skills/purview-buildsdk-adoption/SKILL.md b/.claude/skills/purview-buildsdk-adoption/SKILL.md new file mode 100644 index 00000000..b1f222c5 --- /dev/null +++ b/.claude/skills/purview-buildsdk-adoption/SKILL.md @@ -0,0 +1,114 @@ +--- +name: purview-buildsdk-adoption +description: Adopt Purview.BuildSdk in a repository, or troubleshoot an adoption that is not behaving. Use when wiring the SDK into Directory.Build.props for the first time, when a property seems to have no effect, when the resolved version or namespace is wrong, or when a consuming repository builds but the SDK's automatic behaviour is not appearing. Covers the import chain, pre-import property ordering, and version detection from package.json. +license: MIT +metadata: + package: Purview.BuildSdk + repository: purview-dev/build-sdk +--- + +# Adopting Purview.BuildSdk + +The goal is a working adoption that does not break existing build behaviour. Prefer minimal, +targeted property changes over rewriting a repository's `Directory.Build.props`. + +For the full property list use `purview-buildsdk-configuration`; for auditing an existing +repository's shape, `purview-buildsdk-repository-review`. + +## 1. The import chain + +```xml + + + + + Acme.Sales + + + + +``` + +```xml + + + + +``` + +Both halves are required. A repository with only `Sdk.props` imported gets the evaluation-time +defaults — naming, identity, framework selection — but none of the targets, so validation, +packaging behaviour and the generated files never run. That combination usually presents as "the +properties look right but nothing happens". + +The SDK version comes from `global.json`, which the SDK itself bootstraps. + +## 2. Pre-import ordering is the first thing to check + +**A property that must affect `Sdk.props` evaluation has to be set before the import.** Setting it +in a `.csproj`, or below the import, is too late and silently does nothing — no error, no warning. +This is the single most common adoption failure. + +Set before the import: + +- `NamespacePrefix` +- `UsePackageJsonVersion`, `RootPackageJson` +- `EnableAssemblyNameGeneration` +- `AutoIncludeUsings` +- `PurviewSharedTestingOutputType`, `PurviewTestContextNoWarn` +- any repo-wide testing-framework selection you want every project to inherit + +Everything else is read in `Sdk.targets` and can be set in a project file. + +When a property appears to have no effect, confirm what MSBuild actually resolved before changing +anything else: + +```bash +dotnet msbuild -getProperty:NamespacePrefix -getProperty:RootNamespace +``` + +## 3. Version detection + +Versions come from `package.json`. Resolution order: + +1. An explicit `RootPackageJson`. +2. CI workspace variables. +3. The `.git` root. +4. A nearby `package.json`. + +On success both `Version` and `PackageVersion` are set from the `version` field. + +If the version looks wrong, do not guess at the discovery — make it fail loudly instead: + +```xml +Strict +``` + +`Strict` fails the build when discovery or resolution cannot succeed, rather than silently skipping +it and leaving the default `1.0.0`. Set `VersionDetectionLogEnabled=true` to see what it found. + +## 4. Naming and placement + +Most of the SDK's value is inferred from project names and locations, so an adoption that keeps a +bespoke structure gets correspondingly little. Confirm the repository follows the conventions rather +than introducing new structure to work around them — see `purview-buildsdk-project-layout`, and +`purview-buildsdk-repository-review` for auditing an existing layout. + +The highest-value single check: every test project is named `.Tests`. **The dot is +required.** A project named plainly `UnitTests` is not detected as a test project at all, and +silently gets no runner, no coverage, no `InternalsVisibleTo` and no category. + +## 5. Agent skills are a separate, explicit step + +The SDK does not install agent skills, and nothing it does during a build writes to an agent +directory. It reads which skills each referenced package ships and recommends the command that +installs them; the skills CLI does the installing. See `purview-buildsdk-skill-installation`. + +## Constraints + +- Prefer minimal, targeted property changes over broad `Directory.Build.props` rewrites. +- Do not disable `PurviewAutoSdkPack` unless the consumer explicitly asks to opt out. +- Do not restate an SDK default in a project file. Hand-configuration that merely repeats a default + is pure maintenance cost, and it hides the fact that the default later changed. +- Re-run the build — or the repository's canonical build command — after each change, and confirm + the fix before moving to the next one. diff --git a/.claude/skills/purview-buildsdk-configuration/SKILL.md b/.claude/skills/purview-buildsdk-configuration/SKILL.md new file mode 100644 index 00000000..f0ee7156 --- /dev/null +++ b/.claude/skills/purview-buildsdk-configuration/SKILL.md @@ -0,0 +1,110 @@ +--- +name: purview-buildsdk-configuration +description: Configure Purview.BuildSdk from Directory.Build.props or a .csproj. Use when setting NamespacePrefix, choosing a testing or mocking framework, turning telemetry or SourceLink off, controlling version detection from package.json, tuning the repository bootstrap, or working out whether a property must be set before the SDK import. Also use when the SDK "did something automatically" and you need the property that controls it. +license: MIT +metadata: + package: Purview.BuildSdk + repository: purview-dev/build-sdk +--- + +# Purview.BuildSdk configuration + +Use this skill when the question is "what property controls this, and where do I set it?" + +For *why* the SDK classified a project a particular way, use `purview-buildsdk-project-detection` +instead. For where projects and tests should live, use `purview-buildsdk-project-layout`. + +## First rule: know where a property must be set + +A property that changes `Sdk.props` evaluation must be set **before** the SDK import — in +`Directory.Build.props`, above the import. Setting it in a `.csproj` is too late and silently has no +effect. + +Pre-import properties include: + +- `NamespacePrefix` +- `UsePackageJsonVersion`, `RootPackageJson` +- `EnableAssemblyNameGeneration` +- `PurviewSharedTestingOutputType`, `PurviewTestContextNoWarn` +- `AutoIncludeUsings` +- repo-wide testing-framework selection you want every project to inherit + +Everything else is read in `Sdk.targets` and can be set in a project file. Prefer repo-wide defaults +in `Directory.Build.props` unless the setting is deliberately project-specific. + +## The properties you will reach for most + +| Property | Default | What it does | +| -- | -- | -- | +| `NamespacePrefix` | *(required)* | The root identity. Required unless `DisableNamespacePrefixCheck=true` | +| `TestingFramework` | `TUnit` | `TUnit`, `Xunit` or `None` | +| `SubstituteFramework` | `TUnitMocks` | `TUnitMocks`, `NSubstitute` or `None` | +| `TestDataFramework` | `Bogus` | `Bogus` or `None` | +| `TargetFramework` | `net10.0` | `netstandard2.0` when `IsRoslynComponent=true` | +| `IsPackable` | `false` | Opts a project into the packable defaults | +| `UsePackageJsonVersion` | `true` | `true`, `false` or `Strict` — version from `package.json` | +| `ExcludePurviewTelemetry` | `false` | Drops the telemetry source generator | +| `DisableSourceLink` | `false` | Drops SourceLink from packable projects | +| `EnableAssemblyNameGeneration` | `true` | `AssemblyName`/`PackageId` follow the resolved `RootNamespace` | + +The full set, grouped by area and with the behaviour each one changes, is in +[references/properties.md](references/properties.md). Read it rather than guessing a property name — +several of these have near-miss names that do nothing. + +## Derived properties to inspect, not re-derive + +When explaining what the SDK did, read the value it computed rather than reasoning from the folder +name: + +`PurviewLogicalProjectName`, `PurviewNamespacePrefix`, `PurviewProjectShortName`, `PurviewTestType`, +`RootNamespace`, `AssemblyName`, `PackageVersion`, `TestingType`, `TargetProjectName`, `RepoRoot`, +`RootPackageJson`. + +Ask MSBuild for one directly: + +```bash +dotnet msbuild -getProperty:RootNamespace +dotnet msbuild -getProperty:TestingType -getProperty:TargetProjectName +``` + +## Compiler-visible properties + +The SDK exports its properties to analyzers and generators as `build_property.`. When +authoring an analyzer, read the exported property instead of re-deriving SDK behaviour — the export +is the SDK's answer, and it stays correct when the rules change. The exported set is listed in +[references/properties.md](references/properties.md). + +## Version detection + +1. If `RootPackageJson` is set, that file is used. +2. Otherwise the repo root is discovered from CI variables, `.git`, or a nearby `package.json`. +3. On success, both `Version` and `PackageVersion` come from the `version` field. +4. `UsePackageJsonVersion=Strict` turns a failed discovery into a build failure instead of a silent + fallback. + +## Repository bootstrap + +The SDK bootstraps two repository-wide files from the package: `.editorconfig` and `global.json`. + +- `PurviewRepoBootstrapMode` — `IfMissing` (default), `Always`, `WarnOnDrift`, `Never` +- `DisableAutoCopySdkFiles` — the master off switch +- `PurviewRepoBootstrapCopyRetries` / `...RetryDelayMilliseconds` / `...FailureAsError` + +Every project in a solution writes those same destinations, so the write is race-tolerant by +design: an existing file is never overwritten unless asked, each write is staged into a temporary +file and renamed into place, retries are quiet, and only a failure that survives every retry is +reported. + +**The SDK writes nothing into an agent directory.** It used to mirror a package's `.agents/**` into +the repository; that is gone, along with `EnableAgentFolderInPackage`, `AgentPackDestinationFolder` +and the `PurviewAgentFolder*` properties. Skills have exactly one installer, the skills CLI — see +`purview-buildsdk-skill-installation`. + +## Guidance when changing SDK configuration + +1. Preserve existing defaults unless the task explicitly changes product behaviour. +2. Keep `README.md`, the property declaration, its validation and the shipped skills aligned — a + property documented in one place and absent from another is the failure mode this repository + keeps hitting. +3. A new property that affects import-time behaviour must say so in its documentation. +4. Add the property to the `CompilerVisibleProperty` list if an analyzer would benefit from it. diff --git a/.claude/skills/purview-buildsdk-configuration/references/properties.md b/.claude/skills/purview-buildsdk-configuration/references/properties.md new file mode 100644 index 00000000..93a0d9b3 --- /dev/null +++ b/.claude/skills/purview-buildsdk-configuration/references/properties.md @@ -0,0 +1,146 @@ +# Purview.BuildSdk property reference + +Every user-facing property, grouped by what it changes. Defaults are what the SDK applies when the +consuming project supplies nothing. + +## Identity and naming + +| Property | Default | Behaviour | +| -- | -- | -- | +| `NamespacePrefix` | *(required)* | The root identity source. Required unless the check is disabled. Set before the SDK import | +| `DisableNamespacePrefixCheck` | `false` | Stops the build failing when `NamespacePrefix` is unset | +| `EnableAssemblyNameGeneration` | `true` | `AssemblyName` and the default `PackageId` follow the fully evaluated `RootNamespace`, or the full logical project name when suffix-stripping removed a segment (`Shared`, `ServiceDefaults`). Set `false` before the SDK import for standard project-name behaviour | +| `AssemblyIdentifierClassName` | *(derived)* | Renames the generated marker class | +| `DisableGenerateAssemblyIdentifierClass` | `false` (forced `true` for test and shared-testing projects) | Drops the empty marker class (`Assembly`, global namespace) that architecture tests use to pin an assembly by `typeof` rather than by name | +| `DisableGenerateAssemblyInfoClass` | `false` | Drops the generated `AssemblyInfo` | +| `DisableAutoInternalsVisibleTo` | `false` | Drops automatic friend-assembly generation | +| `DisableProjectFileNamingConventionCheck` | `false` | Stops validating that the `.csproj` filename matches its directory | +| `AutoIncludeUsings` | `true` | Controls the SDK-added global usings. Set before the SDK import | + +## Target framework and language + +| Property | Default | Behaviour | +| -- | -- | -- | +| `TargetFramework` | `net10.0` | Applied when neither `TargetFramework` nor `TargetFrameworks` is set. A project that explicitly declares `IsRoslynComponent=true` defaults to `netstandard2.0` | +| `IsRoslynComponent` | *(unset)* | When explicitly `true`: a single `netstandard2.0` target, `LangVersion=latest`, `Nullable=enable`, `TreatWarningsAsErrors=true`, `Deterministic=true`, extended analyzer rules, SourceLink with `EmbedUntrackedSources=true`, no dependency file, telemetry exclusion, and `PrivateAssets=all` on `Microsoft.CodeAnalysis.*` references | +| `IsRoslynComponentOnly` | `true` for Roslyn components | Analyzer-only package: `IncludeBuildOutput=false`, `IncludeSymbols=false`, portable PDB packed beside the analyzer under `analyzers/dotnet/cs/`. Set `false` for a dual-role component using normal library symbol packaging | +| `DisableRoslynCompilerDefaultsValidation` | `false` | Opts out of `ValidateRoslynComponentCompilerSettings`, which fails the pack of a packable Roslyn component missing `LangVersion`, `Nullable`, `TreatWarningsAsErrors` or `EnforceExtendedAnalyzerRules` | +| `PackProjectReferencedSourceGenerators` | `true` | Packable projects include analyzer `ProjectReference` outputs under `analyzers/dotnet/cs/`. Use `Pack="false"` on one reference to opt that one out | + +## Style policy + +| Property | Default | Behaviour | +| -- | -- | -- | +| `DisablePurviewStylePolicyValidation` | `false` | Stops the build failing (`PRSGD0006`–`PRSGD0009`) when the repository `.editorconfig` overrides the modifier policy — `dotnet_style_require_accessibility_modifiers` other than `omit_if_default`, hiding `IDE0040`/`IDE1006`, disabling the Style category in bulk, weakening the `_camelCase` private-instance-field rule, or adding the accessibility rules to `NoWarn`. Entries the SDK injects itself are ignored | +| `PurviewTestContextNoWarn` | `CA1002;CA1012;CA1034;CA1047;CA1050;CA1051;CA1062;CA1064;CA1515;CA1707` | The production API-surface rules exempted in test and shared-testing projects. Test projects keep the strict style contract (`IDE0040`, field naming, formatting, `IDE1006`) but are context aware: public test classes, `Method_Scenario_Expectation` names, exposed fields and unvalidated helper parameters are allowed. Set before the SDK import | +| `DisablePurviewTestContextRuleSet` | `false` | Makes test and shared-testing projects enforce the production API-surface rules too | +| `PurviewPolicyExemptNoWarn` | *(derived)* | The SDK-injected `NoWarn` entries `ValidatePurviewStylePolicy` accepts | + +## Testing + +| Property | Default | Behaviour | +| -- | -- | -- | +| `TestingFramework` | `TUnit` | `TUnit`, `Xunit`, `None` | +| `SubstituteFramework` | `TUnitMocks` | `TUnitMocks`, `NSubstitute`, `None` | +| `TestDataFramework` | `Bogus` | `Bogus`, `None` | +| `CollectCoverage` | `true` for detected test projects | | +| `EnableStaticNativeInstrumentation` | `false` for test projects | | +| `EnableDynamicNativeInstrumentation` | `false` for test projects | | +| `TestingPlatformDotnetTestSupport`, `UseMicrosoftTestingPlatformRunner`, `EnableMicrosoftTestingPlatform` | enabled for TUnit test projects | Microsoft.Testing.Platform wiring | +| `PurviewSharedTestingOutputType` | `Library` | Forced onto `IsSharedTestingProject` projects, with `IsTestProject`/`IsTestingPlatformApplication` cleared, because the test packages otherwise flip them into an executable test host. Set `Exe` before the SDK import to keep the package-driven shape | + +## Packaging + +| Property | Default | Behaviour | +| -- | -- | -- | +| `IsPackable` | `false` | | +| `PurviewAutoSdkPack` | `true` | Packs `Sdk/**/*` into the package at the right root-level paths | +| `PurviewSkillsSourceFolder` | `/skills` | Where authored skills live | + +Packable-project defaults, applied only when the project supplied nothing: +`GenerateDocumentationFile=true`, `IncludeSymbols=true`, `SymbolPackageFormat=snupkg`, +`PublishRepositoryUrl=true`, `EmbedUntrackedSources=true`, `DebugType=portable`. Portable PDBs ship +in the `.snupkg`; the `.nupkg` gets none unless the project opts in. Roslyn-component-only packages +instead default `IncludeSymbols=false` and ship their PDB inside `analyzers/dotnet/cs/`. + +When the repository root is discoverable, the root `README.md` is packed automatically and +registered as `PackageReadmeFile`, unless one is configured already. + +Non-packable projects, including web apps, default `WarnOnPackingNonPackableProject=false` so a +solution-wide pack skips them silently. + +`ContinuousIntegrationBuild` is set only by real CI environment variables. Packability alone never +forces SourceLink's CI-mode dirty-repository checks. + +## Telemetry and SourceLink + +| Property | Default | Behaviour | +| -- | -- | -- | +| `ExcludePurviewTelemetry` | `false` | Removes `Purview.Telemetry.SourceGenerator` | +| `ExcludeMSTelemetryExtension` | `false` | Removes `Microsoft.Extensions.Telemetry.Abstractions`. Only relevant when `ExcludePurviewTelemetry` is also `false` — the whole group is skipped otherwise | +| `SourceLinkPackageName` | `Microsoft.SourceLink.GitHub` | | +| `DisableSourceLink` | `false` | | + +## Version detection + +| Property | Default | Behaviour | +| -- | -- | -- | +| `UsePackageJsonVersion` | `true` | `true`, `false`, `Strict` | +| `RootPackageJson` | *(discovered)* | Explicit path to the `package.json` to read | +| `EnableVersionDetectionCache` | `true` | | +| `VersionDetectionCacheFile` | *(derived)* | | +| `VersionDetectionLogEnabled` | `false` | Logs the detected version | + +## Repository bootstrap + +| Property | Default | Behaviour | +| -- | -- | -- | +| `DisableAutoCopySdkFiles` | `false` | Master switch for SDK-managed repository file writes | +| `PurviewRepoBootstrapMode` | `IfMissing` | Also `Always`, `WarnOnDrift`, `Never` | +| `BootstrapEditorConfigToRepoRoot` | `true` | | +| `RepositoryEditorConfigFilePath` | *(derived)* | Overrides the destination `.editorconfig` | +| `BootstrapGlobalJsonToRepoRoot` | `true` | | +| `RepositoryGlobalJsonFilePath` | *(derived)* | Overrides the destination `global.json` | +| `PurviewBuildSdkVersionForGlobalJson` | detected SDK version, else `1.0.0` | | +| `PurviewRepoBootstrapCopyRetries` | `3` | | +| `PurviewRepoBootstrapCopyRetryDelayMilliseconds` | `500` | | +| `PurviewRepoBootstrapCopyFailureAsError` | `true` | `false` downgrades a persistent write failure to a warning | +| `PurviewSuppressCopyRetryWarnings` | `true` | Demotes the built-in copy task's `MSB3026` retry notice to a message | +| `PurviewRepositoryRootMarkers` | `.git/;.github/;.gitattributes;LICENSE.md;AGENTS.md;.agents/;CLAUDE.md;.claude/;package.json` | Ordered markers identifying a repository root, most authoritative first | + +There is no agent-folder mirror. `EnableAgentFolderInPackage`, `AgentPackDestinationFolder`, +`PurviewAgentFolderSourcePath`, `PurviewAgentFolderCopy*`, `PurviewAgentSyncManifestPath` and +`DisableMirroredFileTrackingCheck` were removed: skills are installed by the skills CLI, and +nothing else was left for the mirror to deliver. + +## Skills + +Covered in full by `purview-buildsdk-skill-installation`: `PurviewSkillsRunner`, +`PurviewSkillsRunnerCandidates`, `PurviewSkillsCommand`, `PurviewSkillsPackage`, +`PurviewSkillsAgents`, `PurviewSkillsSource`, `PurviewSkillsInstallRoot`, `PurviewSkillsRepoRoot`, +`EnablePurviewSkillRecommendations`, `PurviewSkillRecommendationsInCI`. + +## Compiler-visible properties + +Exported to analyzers and generators as `build_property.`: + +- `UsePackageJsonVersion`, `RootPackageJson`, `RepoRoot`, `Version`, `PackageVersion` +- `NamespacePrefix`, `DisableNamespacePrefixCheck` +- `TestingFramework`, `SubstituteFramework`, `TestDataFramework` +- `ExcludePurviewTelemetry`, `ExcludeMSTelemetryExtension` +- `EnableAssemblyNameGeneration`, `DisableAutoInternalsVisibleTo`, `DisableGenerateAssemblyInfoClass`, + `DisableGenerateAssemblyIdentifierClass`, `AssemblyIdentifierClassName` +- `IsCSharpProject`, `IsTestProject`, `IsSharedTestingProject`, `IsSharedProject` +- `TestingType`, `TargetProjectName` +- `IsContainerProject`, `IsSdkProject`, `SdkProjectName`, `IsWebProject`, `IsWebSdkProject`, + `IsWorkerSdkProject`, `IsAspireHostProject`, `IsCLIProject` +- `EditorConfigFilePath`, `RepositoryEditorConfigFilePath`, `BootstrapEditorConfigToRepoRoot` +- `RepositoryGlobalJsonFilePath`, `BootstrapGlobalJsonToRepoRoot`, `DisableAutoCopySdkFiles` +- `PurviewRepoBootstrapMode`, `PurviewRepoBootstrapCopyRetries`, + `PurviewRepoBootstrapCopyRetryDelayMilliseconds`, `PurviewRepoBootstrapCopyFailureAsError` +- `PurviewSuppressCopyRetryWarnings` +- `PurviewSkillsSourceFolder`, + `PurviewSkillsAgents`, `PurviewSkillsInstallRoot`, `PurviewRepositoryRootMarkers`, + `PurviewSkillsRunner` +- `PurviewBuildSdkVersionForGlobalJson`, `CurrentYear`, `AutoGeneratedAssemblyInfoFile`, + `AutoGeneratedAssemblyIdentifierFile` diff --git a/.claude/skills/purview-buildsdk-project-detection/SKILL.md b/.claude/skills/purview-buildsdk-project-detection/SKILL.md new file mode 100644 index 00000000..2d0d9862 --- /dev/null +++ b/.claude/skills/purview-buildsdk-project-detection/SKILL.md @@ -0,0 +1,134 @@ +--- +name: purview-buildsdk-project-detection +description: Explain why Purview.BuildSdk classified a project as test, shared, shared-testing, CLI, web, worker, Aspire host, container or Roslyn component, and why it added a package, a project reference, a namespace or an analyzer automatically. Use when SDK behaviour looks surprising, when a test project gets no runner or no InternalsVisibleTo, or when reasoning about RootNamespace, AssemblyName and TargetProjectName. +license: MIT +metadata: + package: Purview.BuildSdk + repository: purview-dev/build-sdk +--- + +# Why Purview.BuildSdk did that + +Use this skill when the question is **why** the SDK applied something automatically. + +For where a project should live, use `purview-buildsdk-project-layout`. For the property that turns +a behaviour off, use `purview-buildsdk-configuration`. + +## Diagnose from computed properties, never from the folder name + +Read what the SDK actually computed: + +```bash +dotnet msbuild -getProperty:PurviewLogicalProjectName -getProperty:RootNamespace \ + -getProperty:TestingType -getProperty:TargetProjectName -getProperty:IsTestProject +``` + +The values worth inspecting first: `MSBuildProjectName`, `NamespacePrefix`, +`PurviewLogicalProjectName`, `RootNamespace`, `TestingType`, `TargetProjectName`, `SdkProjectName`, +`IsTestProject`, `IsSharedProject`, `IsSharedTestingProject`, `IsContainerProject`, `IsCLIProject`, +`IsWebSdkProject`, `IsAspireHostProject`. + +## Detection rules + +### Test projects + +Name matches `^.*\.([\w|_]\w*)Tests?$` — a target name, a dot, then any word before `Test`/`Tests`. +The captured word becomes `TestingType`. + +This is a pattern, **not** a lookup. `MyProject.GoldenTests` is detected exactly as readily as +`MyProject.UnitTests`, with `TestingType=Golden` and `Category=Golden`, even though `Golden` is not a +name the SDK ships. + +**The dot is required.** A project named plainly `UnitTests` does not match, and silently gets no +runner, no coverage, no `InternalsVisibleTo` and no category. This is the single most common +surprise. + +Derived: `IsTestProject=true`, `TestingType=`, `PurviewTestType=Tests`, +`TargetProjectName=`. + +The SDK's explicit `TestType` item group governs **`InternalsVisibleTo` generation**, not detection: +a non-test project grants access to `{AssemblyName}.{TestType}Tests` for each name in the group. A +suffix outside it still builds, runs and gets a category — it just cannot see `internal` members. +The 53 names are in [references/test-types.md](references/test-types.md). + +### Shared and shared-testing projects + +Recognised by **exact name**, never by substring. The two lists are in +[references/detection.md](references/detection.md). Derived: `IsSharedProject`, +`IsSharedTestingProject`. + +### SDK and content based + +| Signal | Result | +| -- | -- | +| the project's `Sdk="..."` declaration | `IsSdkProject`, `SdkProjectName` | +| `Microsoft.NET.Sdk.Web` | `IsWebSdkProject=true` | +| `Microsoft.NET.Sdk.Worker` | `IsWorkerSdkProject=true` | +| SDK starts with `Aspire.Sdk.Host` or `Aspire.AppHost.Sdk` | `IsAspireHostProject=true` | +| `Dockerfile`, `dockerfile` or `Dockerfile.dev` in the project directory | `IsContainerProject=true` | +| name ends with `CLI`, `Console`, `CommandLine`, `QuickStart`, `QuickStarts` | `IsCLIProject=true` | + +## Namespace and identity + +1. `PurviewLogicalProjectName` is `NamespacePrefix` plus the project name, de-duplicated when the + project name already starts with the prefix's tail. +2. `RootNamespace` defaults to `PurviewLogicalProjectName`. +3. Known suffixes are stripped from `RootNamespace` — shared and shared-testing names, and segments + such as `Core`, `EF`, `Shared`, `ClientShared`, `ServiceDefaults`. +4. Test suffixes are stripped too, so `Acme.Api.UnitTests` maps back to `Acme.Api`. +5. `AssemblyName` and `PackageId` default to the fully evaluated `RootNamespace` — except where + stripping removed a segment, where they use the full `PurviewLogicalProjectName` so the artifact + stays distinct from its parent. Test and shared-testing projects keep their detected suffix. + Explicit `AssemblyName`/`PackageId`/`RootNamespace` always win. +6. The naming defaults are applied during `Sdk.props`, before the Microsoft SDK computes + `TargetName`, so the compiled output name always matches `AssemblyName`. + +## Automatic packages and references + +- **Non-test C# projects**: SourceLink (unless `DisableSourceLink`), the Purview telemetry packages + (unless `ExcludePurviewTelemetry`), `GenerateDocumentationFile=true`, and `InternalsVisibleTo` + generation (unless `DisableAutoInternalsVisibleTo`). +- **Test and shared-testing projects**: test-friendly `NoWarn` defaults, not packable or + publishable, and the packages selected by `TestingFramework`, `SubstituteFramework` and + `TestDataFramework`. TUnit test projects get Microsoft.Testing.Platform wiring automatically. + Shared-testing projects skip the runnable test package. +- **Packable projects**, **Roslyn components** and **special project types** (CLI, container, web, + Aspire host): see [references/detection.md](references/detection.md). + +Project-reference probing is layout-driven and covered by `purview-buildsdk-project-layout`. + +## The shipped analyzers + +The SDK adds `Purview.BuildSdk.Analyzers` as an `` item to every C# project, so its rules +surface in command-line builds and in Visual Studio. The code-fix assembly ships beside it. + +| Rule | What it enforces | +| -- | -- | +| `PDS0002` | Extensions classes live under `Extensions//` | +| `PDS0003` | Explicit types with target-typed `new()` | +| `PDS0004` | Correct acronym capitalisation | + +`PDS0004` follows .NET naming guidance: well-known framework spellings (`Sql`, `Guid`, `Uuid`, +`Url`, `Dns`, `Tcp`, `Http`, `Xml`, `Db`, …) are exempt — `Db` among them, so `DbContext`, +`DbConnection` and `DbSet` are never flagged. A small set is still uppercased: `Api`, `Ai`, `Ui`, +`Io`, `Os`, `Cpu`, `Gpu`, `Cli`, `Gui`, `Ram`, `Ssh`. Members mandated by a contract — interface +implementations and base-class overrides — are never renamed. + +Customise through `dotnet_analyzer_configuration.pds0004.allowed_words` (exempt segments), +`.acronym_map` (segment renames, e.g. `Sql:SQL`, or `Db:DB` to re-enable it) and +`.allowed_identifiers` (brand names, exact or word-boundary prefix, first match wins — `CosmosDb` +covers `CosmosDbServer`). All three merge with and override the shipped defaults. + +The shipped `.editorconfig` marks generated content (`Migrations/`, `*.g.cs`, `Generated/`, +`*.Designer.cs`, `obj/`, `bin/`) as `generated_code = true`, and suppresses namespace-conflict +diagnostics under `Extensions/`, so no `#pragma` suppressions are needed there. + +Two Visual Studio refactorings ship with them, both described in +[references/detection.md](references/detection.md). + +## When changing a detection rule + +1. Keep the `.csproj` filename equal to its directory name. +2. Update `README.md` and the shipped skills in the same change — a rule true in code and false in + prose is this repository's recurring failure. +3. Add or update the integration test in `src/tests/BuildSdk.IntegrationTests/` that pins it. diff --git a/.claude/skills/purview-buildsdk-project-detection/references/detection.md b/.claude/skills/purview-buildsdk-project-detection/references/detection.md new file mode 100644 index 00000000..bf75823d --- /dev/null +++ b/.claude/skills/purview-buildsdk-project-detection/references/detection.md @@ -0,0 +1,79 @@ +# Detection detail + +## Shared project names (exact) + +`Shared`, `SharedFramework`, `SharedInfrastructure`, `SharedInfra`, `SharedUtilities`, +`SharedUtils`, `SharedLibrary`, `SharedLib`, `SharedHelpers` + +## Shared testing project names (exact) + +`SharedTestingFramework`, `SharedTestingInfrastructure`, `SharedTestingInfra`, +`SharedTestingUtilities`, `SharedTestingUtils`, `SharedTestingLibrary`, `SharedTestingLib`, +`SharedTestingHelpers` + +These are matched whole, not as substrings. `SharedModels` is not a shared project. + +A shared-testing project is forced to `PurviewSharedTestingOutputType` (default `Library`), with +`IsTestProject` and `IsTestingPlatformApplication` cleared, because the test packages otherwise flip +it into an executable test host. Set `PurviewSharedTestingOutputType=Exe` before the SDK import to +keep that package-driven shape. + +## Packable projects + +Defaults applied only where the project supplied nothing: `GenerateDocumentationFile`, +`IncludeSymbols`, `SymbolPackageFormat=snupkg`, `PublishRepositoryUrl`, `EmbedUntrackedSources`, +`IncludeSource`, `DebugType=portable`. + +- Portable PDBs ship in the `.snupkg`. The `.nupkg` receives none unless the project opts in. +- The repository-root `README.md` is packed and registered as `PackageReadmeFile` when it exists and + nothing else is already being packed as one. +- Non-packable projects, web apps included, default `WarnOnPackingNonPackableProject=false`, so a + solution-wide `dotnet pack` skips them silently. +- `ContinuousIntegrationBuild` is set only by real CI environment variables. Packability alone never + forces SourceLink's CI-mode dirty-repository checks. + +## Roslyn components + +A project that explicitly declares `IsRoslynComponent=true` gets: + +- a single `netstandard2.0` target, `LangVersion=latest`, `Nullable=enable`, + `TreatWarningsAsErrors=true`, `Deterministic=true`, extended analyzer rules +- SourceLink with `EmbedUntrackedSources=true`, no dependency file, telemetry excluded +- compiler-generated output under the framework-specific intermediate directory +- `PrivateAssets=all` on `Microsoft.CodeAnalysis.*` and `Microsoft.CodeAnalysis.Analyzers`, so they + never leak into the packed nuspec + +`IsRoslynComponentOnly` defaults to `true`: `IncludeBuildOutput=false`, `IncludeSymbols=false`, no +`.symbols.nupkg` or `.snupkg`, and the analyzer PDB shipped inside the main `.nupkg` under +`analyzers/dotnet/cs/` beside the assembly (`PurviewPackAnalyzerPdb=true`). Set it to `false` for a +dual-role component that wants normal library symbol packaging. + +`ValidateRoslynComponentCompilerSettings` fails the pack of a packable Roslyn component missing +`LangVersion`, `Nullable`, `TreatWarningsAsErrors` or `EnforceExtendedAnalyzerRules`. Opt out with +`DisableRoslynCompilerDefaultsValidation=true`. + +`PackProjectReferencedSourceGenerators` (default `true`) makes a packable project include analyzer +`ProjectReference` outputs and their runtime dependencies under `analyzers/dotnet/cs/`. Set it +`false` globally, or `Pack="false"` on one analyzer reference. + +## Special project types + +| Type | Applied | +| -- | -- | +| CLI | `OutputType=Exe`, `appsettings*.json` included as content | +| Container | `InvariantGlobalization`, `PublishAot`, Linux Docker defaults, container tooling packages | +| Web SDK | `Microsoft.AspNetCore.OpenApi.Generated` added to `InterceptorsNamespaces`, unless marked as a separate web-project mode | +| Aspire host | `OutputType=Exe` | + +## The Visual Studio refactorings + +Two ship with the code-fix assembly, both serving the `PDS0002` convention: + +- **Split extensions class into one class per receiver type** — offered on a static extensions class + targeting several receiver types. It produces one `Extensions` class per receiver + (a generic `this TBuilder where TBuilder : IHostApplicationBuilder` receiver becomes + `HostApplicationBuilderExtensions`) and places each under `Extensions//`. +- **Move extensions class to conventional location** — offered on a misplaced single-receiver + extensions class. It re-paths the file to `Extensions//`, fixes the namespace + to the receiver's, and updates `using` directives in other referencing documents so the move + compiles. diff --git a/.claude/skills/purview-buildsdk-project-detection/references/test-types.md b/.claude/skills/purview-buildsdk-project-detection/references/test-types.md new file mode 100644 index 00000000..dace44fc --- /dev/null +++ b/.claude/skills/purview-buildsdk-project-detection/references/test-types.md @@ -0,0 +1,35 @@ +# The shipped `TestType` group + +These 53 names drive **`InternalsVisibleTo` generation**, not test detection. A non-test project +grants friend access to `{AssemblyName}.{TestType}Tests` for each name here. + +Detection is the pattern `^.*\.([\w|_]\w*)Tests?$`, so a suffix outside this group is still detected, +still runs and still gets its category — it simply cannot reach the target project's `internal` +members. Prefer a name from this group unless the test type genuinely needs its own word. + +```text +Unit Integration E2E EndToEnd Acceptance +Functional Performance Load Smoke Stress +Regression Security Chaos Scenario System +Threat BlackBox WhiteBox GrayBox GreyBox +Accessibility Usability Visual Interactive Localization +Globalization Environment Configuration Deployment Architecture +Contract Component Sanity Property Fuzz +Mutation Snapshot Approval Benchmark Capacity +Concurrency Endurance Soak Spike Failover +Recovery Resilience Compatibility Interoperability Migration +Upgrade Penetration Compliance +``` + +## The five to reach for first + +`Unit`, `Integration`, `E2E`, `Functional`, `Contract`. Everything else is available, but a reader +has to ask what it means — use one only when the test type itself carries operational weight. + +## What a suffix buys you + +| | detected as a test project | gets a category | gets a runner and coverage | sees `internal` members | +| -- | -- | -- | -- | -- | +| `Api.UnitTests` | yes | `Unit` | yes | yes | +| `Api.GoldenTests` | yes | `Golden` | yes | **no** | +| `UnitTests` *(no dot)* | **no** | no | **no** | no | diff --git a/.claude/skills/purview-buildsdk-project-layout/SKILL.md b/.claude/skills/purview-buildsdk-project-layout/SKILL.md new file mode 100644 index 00000000..55a019cd --- /dev/null +++ b/.claude/skills/purview-buildsdk-project-layout/SKILL.md @@ -0,0 +1,136 @@ +--- +name: purview-buildsdk-project-layout +description: Decide where a project goes and what to call it in a repository that uses Purview.BuildSdk. Use when creating, moving, splitting or renaming a project or test project, choosing a test suffix, aligning namespaces and assembly identity with NamespacePrefix, or relying on the SDK's automatic project references. Also use when rationalising a repository's shape so the SDK's conventions work without overrides. +license: MIT +metadata: + package: Purview.BuildSdk + repository: purview-dev/build-sdk +--- + +# Project layout and naming for Purview.BuildSdk + +Use this skill when physically adding, moving, splitting or renaming a project. + +For *why* the SDK classified an existing project a particular way, use +`purview-buildsdk-project-detection`. For the property that changes a behaviour, use +`purview-buildsdk-configuration`. + +## First principle + +**Treat naming and placement as configuration, not decoration.** + +The SDK infers namespaces, assembly identity, test categories, package wiring and project references +from a small set of conventions. The closer a repository sits to them, the fewer overrides it needs. + +The corollary matters just as much: **preserve the host repository's existing layout first.** Only +introduce new structure when no established pattern exists. + +## Canonical layout + +```text +/ + package.json version source + .editorconfig bootstrapped by the SDK + skills/ authored agent skills, if any + src/ + .slnx + src//.csproj + tests/.Tests/.Tests.csproj +``` + +- The `.csproj` filename must equal its containing directory name, unless + `DisableProjectFileNamingConventionCheck=true`. +- Source projects under `src/`, test projects under `tests/`. +- Place a new project beside similar ones — same language, layer and test type. +- One test type per project by default. + +A repository that already uses a different shape keeps it; add to it rather than converting it. + +## Naming and identity + +`NamespacePrefix` is the root identity source. Keep project names short and let the SDK apply the +prefix: + +| `NamespacePrefix` | Project | `RootNamespace` | +| -- | -- | -- | +| `Aspire` | `Hosting` | `Aspire.Hosting` | +| `Acme.Sales.RegionalPipeline` | `Identity.API` | `Acme.Sales.RegionalPipeline.Identity.API` | +| `Acme.Sales.RegionalPipeline` | `Identity.Core` | `Acme.Sales.RegionalPipeline.Identity` | + +`AssemblyName` and `PackageId` follow the resolved `RootNamespace` — except where suffix-stripping +removed a segment (`Core`, `Shared`, `ServiceDefaults`), in which case they keep the fuller logical +name so the artifacts stay distinct from their parent. Explicit values always win, and +`EnableAssemblyNameGeneration=false` (before the SDK import) restores standard behaviour. + +Do not hand-author an alternate namespace scheme when one is already in use. + +## Test project naming + +Test detection is a **pattern**, not a list: `^.*\.([\w|_]\w*)Tests?$`. A target name, a dot, then +any word before `Test` or `Tests`. The captured word becomes `TestingType` and the baseline category. + +**The dot is required.** A project named plainly `UnitTests`, with no target in front of it, is not +detected as a test project at all — no runner, no coverage, no `InternalsVisibleTo`, no category. +Always name a test project `.Tests`. + +Prefer these by default: `UnitTests`, `IntegrationTests`, `E2ETests`, `FunctionalTests`, +`ContractTests`. Use another suffix only when the test type itself carries operational meaning. + +A suffix outside the SDK's shipped `TestType` group still builds, runs and gets its category — it +just cannot reach the target project's `internal` members, because that group drives +`InternalsVisibleTo` generation. The full list is in `purview-buildsdk-project-detection`. + +## Shared projects: exact names only + +The SDK recognises these names exactly — a near miss gets none of the behaviour. + +Shared: `Shared`, `SharedFramework`, `SharedInfrastructure`, `SharedInfra`, `SharedUtilities`, +`SharedUtils`, `SharedLibrary`, `SharedLib`, `SharedHelpers`. + +Shared testing: `SharedTestingFramework`, `SharedTestingInfrastructure`, `SharedTestingInfra`, +`SharedTestingUtilities`, `SharedTestingUtils`, `SharedTestingLibrary`, `SharedTestingLib`, +`SharedTestingHelpers`. + +## Automatic project references to preserve + +Layout is what makes these work. Move a project off the convention and you own the reference. + +Test projects probe for their target, in order: + +- `../$(TargetProjectName)/$(TargetProjectName).csproj` +- `../../$(TargetProjectName)/$(TargetProjectName).csproj` +- `../src/$(TargetProjectName)/$(TargetProjectName).csproj` +- `../../src/$(TargetProjectName)/$(TargetProjectName).csproj` + +Non-test projects pick up sibling shared projects via `../Shared*/Shared*.csproj`; test projects +pick up `../SharedTesting*/SharedTesting*.csproj`. + +## Creating a new project + +1. Match the SDK and style of sibling projects. +2. Use Central Package Management if the repository has it. +3. Add only the dependencies the project's scope needs — the SDK supplies the testing stack, + SourceLink and telemetry by default. +4. Add the project to the solution. +5. Keep target frameworks, nullability, analyzers and warning settings consistent with neighbours. + +## Moving or splitting + +1. Create the destination using the established layout. +2. Move the files. +3. Update namespaces, usings and references for the destination. +4. Verify the destination still produces the intended `TestingType`, `TargetProjectName` and + `RootNamespace` — ask MSBuild rather than assuming: + `dotnet msbuild -getProperty:RootNamespace -getProperty:TargetProjectName`. +5. Remove dependencies the source no longer needs. +6. Update solution membership and project references. +7. Build, then run the affected tests. + +## Guardrails + +- Prefer minimal, targeted diffs; avoid cross-cutting renames unrelated to the move. +- Keep test intent unchanged while relocating. +- When the structure is ambiguous, infer from the nearest sibling projects and say which assumption + you made. +- When in doubt, preserve compatibility with the SDK's automatic naming, namespace and + project-reference behaviour. diff --git a/.claude/skills/purview-buildsdk-repository-review/SKILL.md b/.claude/skills/purview-buildsdk-repository-review/SKILL.md new file mode 100644 index 00000000..ce1fd294 --- /dev/null +++ b/.claude/skills/purview-buildsdk-repository-review/SKILL.md @@ -0,0 +1,111 @@ +--- +name: purview-buildsdk-repository-review +description: Review a repository that uses Purview.BuildSdk for naming, placement and test-structure alignment, and report what the SDK can and cannot do automatically as a result. Use when asked to audit, rationalise or health-check a repo against the SDK's conventions, when onboarding an existing codebase onto Purview.BuildSdk, or when deciding whether a layout quirk is worth changing. +license: MIT +metadata: + package: Purview.BuildSdk + repository: purview-dev/build-sdk +--- + +# Reviewing a repository against the SDK's conventions + +This is an audit, not a refactor. The deliverable is a prioritised list of findings and the cost of +each, so somebody else can decide what to change. + +For the conventions themselves use `purview-buildsdk-project-layout`; for why one project was +classified as it was, `purview-buildsdk-project-detection`. + +## The governing judgement + +**Deviation is only a finding when it costs the repository something.** The SDK infers behaviour +from naming and placement, so a deviation is interesting precisely to the extent that it turns an +automatic behaviour off. A layout that differs from the canonical one but still gets every automatic +behaviour is not debt, and reporting it as such wastes the reader's attention. + +Sort every finding into one of three buckets, and say which: + +| Bucket | Meaning | +| -- | -- | +| **Acceptable variance** | Differs from the canonical layout, costs nothing. Preserve it. | +| **Structural debt** | Blocks an automatic behaviour the repository would benefit from. | +| **Incremental opportunity** | Low-risk tidying worth doing when the area is touched anyway. | + +## 1. Read before concluding + +Inspect, in this order, before forming any opinion: + +- `Directory.Build.props` and `Directory.Build.targets` — where the SDK is imported, and what is set + before the import +- the solution entry point, for what is actually in the build +- `Directory.Packages.props`, for Central Package Management +- the project layout on disk + +## 2. Check the structural signals + +- Source projects under `src/`, test projects under `tests/`. +- `.csproj` filename equals its containing directory name — unless + `DisableProjectFileNamingConventionCheck=true`, which is itself a finding worth surfacing. +- Short project names, with `NamespacePrefix` carrying the repository identity. +- Test project names match `^.*\.([\w|_]\w*)Tests?$`. **The dot is required**; a project named + plainly `UnitTests` is not detected at all and silently gets no runner, no coverage, no + `InternalsVisibleTo` and no category. This is the single highest-value thing to check. +- Test suffixes come from the SDK's shipped `TestType` group where `internal` access is wanted — a + suffix outside it still runs, it just cannot see `internal` members. +- Shared and shared-testing projects use the **exact** recognised names. A near miss gets none of + the behaviour. + +## 3. Verify with MSBuild, do not infer from folder names + +A review that reasons from directory names will be wrong about at least one project. Ask: + +```bash +dotnet msbuild -getProperty:RootNamespace -getProperty:AssemblyName \ + -getProperty:IsTestProject -getProperty:TestingType -getProperty:TargetProjectName +``` + +Quote the computed values in the findings. "`Api.Tests` resolves `TestingType=` empty, so it has no +runner" is actionable; "`Api.Tests` looks like it might not be detected" is not. + +## 4. Review test readability + +- Subject-based suites: `{SubjectName}Tests`, with + `{SubjectOrMemberUnderTest}_{Scenario}_{Expectation}` methods. +- Non-subject-based suites — build, generator, workflow, package, full-system — named clearly for + their broader role. A forced `{Subject}Tests` on one of these is worse, not better. +- TUnit categories and display names used where a suite is large enough to need navigating. + +See `purview-buildsdk-testing`. + +## 5. Check the test dependencies are earned + +The SDK already supplies `TUnit`, `TUnit.Mocks`, `Bogus` and the Microsoft.Testing.Platform wiring +to every detected test project. Anything beyond that was a deliberate choice, and deliberate choices +go stale: + +- `TUnit.Aspire` and `Purview.Containers` are **not** universal defaults. Confirm each reference is + genuinely needed by that project rather than copied from a sibling. +- Where a project references `Testcontainers` directly, check whether a `Purview.Containers` typed + module now covers it — the module set grows, and a direct reference that was once necessary often + is not any more. +- A package the SDK already adds, restated in a project file, is maintenance cost with no effect. + +## 6. Explain consequences, not just mismatches + +For each finding, name the specific automatic behaviour that is lost: `RootNamespace`, +`AssemblyName`, `PackageId`, `TargetProjectName`, the automatic target-project reference, the +sibling `Shared*` reference, `InternalsVisibleTo` generation, the test runner and coverage wiring. + +"Project is not under `src/`" is not a finding. "Project is not under `src/`, so the test project's +four probe paths all miss and the `ProjectReference` has to be maintained by hand" is. + +## Reporting the result + +1. One sentence on whether the repository broadly fits the SDK's conventions. +2. The findings, ordered by impact, each with its bucket and the behaviour it costs. +3. The low-risk rationalisation steps, as concrete renames or moves. +4. An explicit split of what is **already automatic** versus what this repository has configured by + hand — that list is usually the most useful part of the review, because hand-configuration that + merely restates a default is pure maintenance cost. + +Do not propose a cross-cutting rename as a first step. Name the one change with the best +cost-to-benefit ratio and say what it unlocks. diff --git a/.claude/skills/purview-buildsdk-skill-installation/SKILL.md b/.claude/skills/purview-buildsdk-skill-installation/SKILL.md new file mode 100644 index 00000000..66c20a33 --- /dev/null +++ b/.claude/skills/purview-buildsdk-skill-installation/SKILL.md @@ -0,0 +1,166 @@ +--- +name: purview-buildsdk-skill-installation +description: Install, list and diagnose the agent skills a Purview.BuildSdk package ships. Use for the InstallPurviewSkills, ListPurviewSkills and RecommendPurviewSkills MSBuild targets, for any PRSKL0001-PRSKL0014 diagnostic, for choosing a package runner (npx, pnpm dlx, bunx, yarn dlx, deno), for skills-lock.json, or when a package ships skills but no agent can see them. +license: MIT +metadata: + package: Purview.BuildSdk + repository: purview-dev/build-sdk +--- + +# Installing the skills a package ships + +For *authoring* skills, use `purview-buildsdk-skill-tests`. + +## The one thing to understand first + +**The SDK writes nothing into an agent directory.** A package *ships* `.agents/skills//`, but +as metadata — it is what tells the SDK which skills the package offers and at which commit. Nothing +copies it out. + +Skills are installed by the skills CLI and by nothing else. That is a deliberate single-writer rule. +Earlier versions of this SDK mirrored a package's whole `.agents/**` folder into the consuming +repository, and the CLI's own universal install location is `.agents/skills/` — the same paths. The +mirror would silently overwrite a pinned install on the next build, while `PRSKL0011` compared a +lockfile ref against content the mirror had already replaced. The mirror was removed outright rather +than fenced off, because the CLI covers the whole job. + +Installing is therefore a separate, deliberately **explicit** step. It is never a side effect of a +restore, a build, a design-time build or a test run. + +```bash +dotnet msbuild -t:ListPurviewSkills # diagnostics only, installs nothing +dotnet msbuild -t:InstallPurviewSkills # delegates to the skills CLI +``` + +Neither target has `BeforeTargets` or `AfterTargets`. If skills are appearing or changing on their +own, something has been wired up that should not be. + +## How a skill is resolved, and why the version is always right + +There is deliberately **no custom manifest**. A package that ships skills already carries both +halves of the mapping, and `ResolvePurviewSkillSources` reads them: + +- `.agents/skills//` in the restored package says *which* skills it ships. +- The nuspec's ``, written by SourceLink for every package this + SDK builds, says which git repository and which **exact commit** produced them. + +So the resolved ref is the commit the *restored package version* was built from. An older +`PackageReference` gets that version's skills, not whatever is on the default branch. Compatibility +is exact by construction rather than by convention. + +## Installing from an explicit source + +For a skill you want but have no `PackageReference` for: + +```bash +dotnet msbuild -t:InstallPurviewSkills -p:PurviewSkillsSource=purview-dev/build-sdk +``` + +The caller owns the ref here — append `#` to pin it. This path needs no restore, so +`PRSKL0001` does not apply. + +## Diagnostics + +| Code | Meaning | Fix | +| -- | -- | -- | +| `PRSKL0001` | `project.assets.json` is missing | Restore. Resolution reads the restore graph and deliberately does not trigger a restore of its own | +| `PRSKL0002` | The package's nuspec has no GitHub repository URL, or no commit | The package cannot be pinned. It is reported rather than installed from a guessed branch | +| `PRSKL0003` | No repository root resolved | Pass `-p:PurviewSkillsInstallRoot=` | +| `PRSKL0004` | No skills CLI and no package runner found | Install Node, or set `PurviewSkillsCommand` | +| `PRSKL0005` | An authored skill is malformed | See `purview-buildsdk-skill-tests` | +| `PRSKL0010` | A skill a referenced package ships is missing | Warning. `npx skills add ...` | +| `PRSKL0011` | An installed skill is pinned to a different ref than the referenced package | Warning. Install the package's own commit | +| `PRSKL0012` | A skill cannot be verified | Message | +| `PRSKL0013` | An orphaned lockfile entry | Message | +| `PRSKL0014` | Recorded in the lockfile but never restored | Message | + +## Recommendations run during an ordinary build + +This is the **one** skill feature that does. `RecommendPurviewSkillsOnBuild` runs after `Build` and +delegates to `RecommendPurviewSkills`, which can also be invoked by name: + +```bash +dotnet msbuild -t:RecommendPurviewSkills +``` + +`EvaluatePurviewSkillState` joins the skills each restored package ships against the CLI's own +`skills-lock.json`. Both inputs are local files, so it stays offline and spawns no process. + +Four things keep it quiet, and all of them are load-bearing: + +- Design-time builds, CI builds, non-default TFM passes and + `EnablePurviewSkillRecommendations=false` are skipped outright. + `PurviewSkillRecommendationsInCI=true` re-enables CI. +- A fingerprint stamp at `/.purview/skill-recommendations.cache` means a given state is + reported once per repository, not once per project and again on every rebuild. The explicit target + ignores the stamp. +- Missing and drifted are **warnings** (fixable in one command); unverifiable and orphaned are + **messages**. No amount of skill advice can break a build using `TreatWarningsAsErrors`. +- A correctly installed set produces no output at all. + +Orphan detection is **owner-scoped on purpose**: a lockfile cannot record who asked for an entry, so +only an entry under an owner the project references — but from a repository it no longer references +— is reported. A skill from any other owner is the developer's own, and is never mentioned. + +### Drift never recommends `npx skills update` + +`update` installs the *newest* published skill, which is only correct when the newest skill happens +to describe the referenced package version. `PRSKL0011` names the referenced package's own commit in +a pinned `npx skills add` instead. + +## Package runners + +The CLI is published to npm, and every runner spells "run this npm package" differently. +`PurviewSkillsRunner` selects one, defaulting to `npx` because npx ships with Node itself. + +| Runner | Invocation | +| -- | -- | +| `npx` | `npx -y skills@1` | +| `bunx` | `bunx skills@1` | +| `bun` | `bun x skills@1` | +| `pnpm` | `pnpm dlx skills@1` | +| `yarn` | `yarn dlx skills@1` — Yarn 2+ only | +| `deno` | `deno run -A npm:skills@1` | + +An unknown runner falls through to ` $(PurviewSkillsPackage)`, so it still works. + +`DetectPurviewSkillsCli` probes `PATH` for `skills` first, then `$(PurviewSkillsRunner)`, then +`$(PurviewSkillsRunnerCandidates)`, honouring `PATHEXT` on Windows where these are `.cmd` shims. +`PATH` is read directly rather than by spawning a version check: deterministic, no process, and it +cannot hang on a cold download. **The runner actually found wins over the configured preference.** +`PurviewSkillsCommand` overrides the launcher entirely and skips detection. + +`ListPurviewSkills` reports runner availability but **never** errors on its absence — resolving and +reporting needs no Node tooling at all. + +## Always the repository root + +`skills-lock.json` and the agent directories belong to the repository, not to a project, so every +skill target runs from one resolved root: + +1. `PurviewSkillsInstallRoot` — an explicit override +2. `PurviewSkillsRepoRoot` — only when the **user** set it +3. the `PurviewRepositoryRootMarkers` walk +4. `PurviewSkillsRepoRoot` / `RepoRoot` as the SDK guessed them +5. CI workspace variables +6. SourceLink's git `SourceRoot` + +There is deliberately **no project-directory fallback**. That would scatter a lockfile and an agent +directory through the tree, one per project. An unresolved root is `PRSKL0003` on install, and +silence for recommendations — a build never fails over advice. + +The marker walk is described in [references/repository-root.md](references/repository-root.md); its +two-pass behaviour and its home-directory bound are both load-bearing. + +## Why the CLI rather than a reimplementation + +The CLI owns the agent-specific destinations and their discovery conventions, which differ per agent +and change independently of this SDK. It also owns `skills-lock.json`, so a repository can restore +the same set later with `npx skills experimental_install`. + +`PurviewSkillsAgents` (default `*`) narrows the target agents. + +The lockfile is read **directly** rather than by parsing `npx skills list --json`, because that +listing omits the `ref` — and the ref is the whole compatibility question. Reading a file also needs +no Node tooling, which is what keeps recommendations working on a machine that can build .NET but +has no Node. There is deliberately no competing lockfile. diff --git a/.claude/skills/purview-buildsdk-skill-installation/references/repository-root.md b/.claude/skills/purview-buildsdk-skill-installation/references/repository-root.md new file mode 100644 index 00000000..e90b695c --- /dev/null +++ b/.claude/skills/purview-buildsdk-skill-installation/references/repository-root.md @@ -0,0 +1,55 @@ +# The repository-root marker walk + +`FindPurviewRepositoryRoot` is an inline MSBuild task driven by `PurviewRepositoryRootMarkers`: + +```text +.git/;.github/;.gitattributes;LICENSE.md;AGENTS.md;.agents/;CLAUDE.md;.claude/;package.json +``` + +A trailing slash marks a directory. A directory marker still matches a **file** of that name, +because `.git` is a directory in a clone but a file in a worktree or a submodule, and both identify +a repository root. + +## Three things that are load-bearing + +### It cannot be an MSBuild intrinsic + +`GetDirectoryNameOfFileAbove` matches **files only** and returns nothing for `.git/`, `.github/`, +`.agents/` or `.claude/` — four of the nine markers. Verified, not assumed. + +### Two passes + +- **Pass 1** — the first marker in the list is *definitive* and is searched all the way up. `.git/` + *is* the repository root, so a monorepo sub-package with its own `package.json` does not win. +- **Pass 2** — every other marker resolves nearest-ancestor-first, with list order breaking ties + inside a single directory. Searching them all to the top would let a stray `.claude/` in a + developer's home directory outrank the real root. + +### The home directory is never a candidate + +The home directory and everything above it are excluded. Without that bound, a project outside any +repository resolves to `~` and installs into it — and a `.claude/` or a `.github/` very commonly +sits there. A repository *below* the home directory is unaffected, because it is below it. + +## Why the marker walk outranks the evaluation-time guess + +`PurviewSkillsRepoRoot` is computed during evaluation from `RepoRoot` and an `AGENTS.md` walk-up. +An `AGENTS.md` can legitimately sit in a subdirectory, and resolving to it would put a lockfile and +an agent directory somewhere that is not the repository. + +`_PurviewSkillsRepoRootWasSpecified` is captured in `Sdk.props` *before* defaulting, so a value the +**user** set still outranks the walk while a value the SDK guessed does not. + +## A target's Condition is evaluated before its DependsOnTargets + +A property a dependency computes is still empty in the depending target's `Condition`. That is why +the unresolved-root guard sits on the `EvaluatePurviewSkillState` task rather than on +`RecommendPurviewSkills` — and equally why the build hook's CI and design-time gating works at all. + +## The managed port + +`Purview.Skills.Testing` ships `SkillRepositoryRoot`, a managed port of the same walk with the same +default markers, so a test that validates a repository's skills resolves the same root the build +installs them into. The two are kept in step by `SkillRepositoryRootTests`, including an assertion +on the default marker list itself — both are defaults nobody sets, so nothing else would notice them +drifting apart. diff --git a/.claude/skills/purview-buildsdk-skill-tests/SKILL.md b/.claude/skills/purview-buildsdk-skill-tests/SKILL.md new file mode 100644 index 00000000..4043ac4f --- /dev/null +++ b/.claude/skills/purview-buildsdk-skill-tests/SKILL.md @@ -0,0 +1,131 @@ +--- +name: purview-buildsdk-skill-tests +description: Author agent skills in a repository that uses Purview.BuildSdk, and validate them with Purview.Skills.Testing or the SDK's pack-time ValidatePurviewSkills target. Use when adding or renaming a skill, writing SKILL.md frontmatter, splitting content into references/ or scripts/, fixing a PRSKL0005 pack failure or a skill-name, skill-description or skill-bundled-resources test failure, or deciding where skills belong in a repository. +license: MIT +metadata: + package: Purview.Skills.Testing + repository: purview-dev/build-sdk +--- + +# Authoring and validating agent skills + +For installing skills a package ships, use `purview-buildsdk-skill-installation`. + +## Where skills live + +**At the repository root, in `skills//SKILL.md`.** Always. + +The skills CLI only discovers skills at a root `skills/` folder, and it reaches a repository by +The skills CLI only discovers skills at a root `skills/` folder, and it reaches a repository by +cloning it, so nothing else is visible to it. Nothing is packed into a NuGet package — a package +carries .NET artifacts, and skills are delivered by the CLI from git. + +```text +skills/ + my-skill/ + SKILL.md required + references/ loaded on demand + scripts/ executable, run on demand + assets/ templates and static resources +``` + +Link to a skill by its **authored** path, `./skills//SKILL.md`. A link into `.agents/skills/` +points at a gitignored file that does not exist in a fresh clone. + +## `SKILL.md` format + +```markdown +--- +name: my-skill +description: What it does, and when to use it. Include the words a task would contain. +license: MIT +metadata: + package: My.Package +--- + +# My skill + +Instructions. +``` + +| Field | Required | Constraint | +| -- | -- | -- | +| `name` | yes | 1–64 chars, lowercase `a-z0-9` and single hyphens, no leading, trailing or consecutive hyphen, **must equal the folder name** | +| `description` | yes | 1–1024 chars, non-empty | +| `license` | no | A licence name, or the name of a bundled licence file | +| `compatibility` | no | ≤500 chars, only when the skill has real environment requirements | +| `metadata` | no | A map of string to string. Anything not defined above belongs here | +| `allowed-tools` | no | Space-separated pre-approved tools. Experimental | + +**There are no other top-level fields.** `category`, `roles` and `tags` are common inventions and a +strict client rejects them; put them under `metadata`. + +The full specification is at . +[references/authoring.md](references/authoring.md) covers description writing, naming for a shared +namespace, and progressive disclosure. + +## Progressive disclosure + +An agent loads a skill in three stages: the `name` and `description` at startup, the whole +`SKILL.md` body once the skill activates, and `references/`, `scripts/` or `assets/` only when the +task reaches them. + +So: keep `SKILL.md` **under 500 lines**, and move detail into `references/`. The body is a cost paid +on every activation; a reference file is paid only when it is needed. + +Keep file references one level deep from `SKILL.md`, and relative to the skill root. A path that +climbs out of the skill folder is broken everywhere except the authoring repository, because only +the skill's own folder is installed. + +## Validating + +### In tests — `Purview.Skills.Testing` + +```csharp +[InheritsTests] +public sealed class SkillTests : PurviewSkillTests; +``` + +**`[InheritsTests]` is load-bearing.** TUnit does not walk base types during discovery, so without +it the class compiles, the run is green and nothing is validated. TUnit reports `TUnit0030`; treat +it as an error. + +| Rule id | What it checks | +| -- | -- | +| `skills-discovery` | The folder, when present, holds at least one skill | +| `skill-structure` | Every folder has a `SKILL.md` whose frontmatter parses | +| `skill-name` | Spec-legal, unique, and equal to the folder name | +| `skill-description` | Present, non-empty, within 1024 characters | +| `skill-optional-fields` | Only spec-defined fields, each within its limit | +| `skill-bundled-resources` | Every linked file exists, inside the skill folder | +| `skill-body-size` | `SKILL.md` stays under the recommended 500 lines | + +A repository with **no** `skills/` folder passes every rule — authoring skills is optional. An +**empty** folder fails `skills-discovery`, because every other rule is vacuous against an empty +catalogue. + +Overrides: `RepositoryRoot` (default: the SDK's repository-root marker walk), +`SkillsFolderName` (default `skills`), and `SkipRule(string)`. + +The evaluator takes a `SkillCatalogue`, so a rule can be exercised against a fixture folder rather +than a real repository — the same three-layer shape this repository uses throughout: a reader, an +evaluator over an in-memory model, and a thin test base class. + +### At pack time — `ValidatePurviewSkills` + +It runs `BeforeTargets="Pack"`, so a malformed skill fails in the repository that owns it rather +than reaching the CLI, which would silently skip it. + +```bash +dotnet msbuild -t:ValidatePurviewSkills +``` + +Failures are reported as `PRSKL0005`, one per problem. Every authored skill is checked. + +The two checks overlap deliberately: the pack-time one runs without a test host, the test one +covers more of the specification. + +## What is deliberately not checked + +Prose quality, and whether an agent actually obeys the skill. A build can only check that a skill is +well formed. Treat a green run as "installable", not "good". diff --git a/.claude/skills/purview-buildsdk-skill-tests/references/authoring.md b/.claude/skills/purview-buildsdk-skill-tests/references/authoring.md new file mode 100644 index 00000000..69d4ee45 --- /dev/null +++ b/.claude/skills/purview-buildsdk-skill-tests/references/authoring.md @@ -0,0 +1,79 @@ +# Authoring a skill that fires, and keeps firing + +## The description is the whole activation decision + +`name` and `description` are the only things loaded at startup. Everything else — the body, the +references, the scripts — is invisible until an agent has already decided to activate the skill on +the strength of those two fields. + +So write the description for a *matcher*, not for a reader: + +- Say **what it does** and **when to use it**, in that order. +- Include the words a real task would contain: the tool names, the file names, the error codes, the + property names, the phrases a person would type. +- Name the thing the skill is *not*, when a neighbouring skill could be confused with it. + +| | | +| -- | -- | +| Poor | `Helps with the build SDK.` | +| Better | `Configure Purview.BuildSdk from Directory.Build.props or a .csproj. Use when setting NamespacePrefix, choosing a testing framework, or working out whether a property must be set before the SDK import.` | + +The limit is 1024 characters. Most of that budget is better spent on trigger words than on prose. + +## Naming for a shared namespace + +Skills install into one flat directory per agent, shared with every other skill a developer has +installed from anywhere. A generic name is a collision waiting to happen, and the loser is whichever +one installed second. + +- Prefix with the vendor and the product: `purview-buildsdk-configuration`, not `sdk-configuration`. +- `sdk-*`, `project-*`, `test-*`, `build-*` are all too common to use unprefixed. +- The name must be 1–64 characters, lowercase `a-z0-9` with single hyphens, no leading, trailing or + consecutive hyphen — and it must equal the folder name, because the CLI installs by the + frontmatter name while a human reads the folder. + +Renaming a skill means renaming the folder and the frontmatter together, and re-running the install. + +## Progressive disclosure in practice + +| Stage | Loaded | Budget | +| -- | -- | -- | +| Metadata | `name`, `description` | ~100 tokens, always | +| Instructions | the whole `SKILL.md` body | under 5000 tokens recommended; keep the file under 500 lines | +| Resources | `references/`, `scripts/`, `assets/` | only when the task reaches them | + +What belongs where: + +- **`SKILL.md`** — the decisions, the rules, the things that are wrong by default, and a pointer to + everything else. If a reader needs it to make the *first* correct move, it goes here. +- **`references/`** — long tables, full option lists, grammars, enumerations. Keep each file + focused; an agent loads the whole file. +- **`scripts/`** — executable code. Self-contained, or documenting its dependencies clearly, with + helpful error messages. +- **`assets/`** — templates, schemas, images, lookup data. + +Keep references one level deep. Avoid a chain where one reference sends an agent to another. + +## Links + +Use relative paths from the skill root: + +```markdown +See [the reference](references/REFERENCE.md) for detail. +Run `scripts/extract.py`. +``` + +Only the skill's own folder is installed, so a link that climbs out of it (`../other-skill/...`) is +broken on every machine except the one that authored it. To point at another skill, name it in prose +and let the agent find it by name. + +## Keeping a skill true + +A skill that describes a product goes stale the moment the product changes, and nothing about a +stale skill looks broken — it just gives confidently wrong advice. + +- Change the skill in the **same commit** as the behaviour it documents. +- Prefer stating the property name, the diagnostic code or the target name over paraphrasing the + behaviour; those are greppable when the code changes. +- Where a number or a list is authoritative somewhere else — a default, an enumeration — say where + it comes from, so a reader can check it. diff --git a/.claude/skills/purview-buildsdk-testing/SKILL.md b/.claude/skills/purview-buildsdk-testing/SKILL.md new file mode 100644 index 00000000..5a5a7d53 --- /dev/null +++ b/.claude/skills/purview-buildsdk-testing/SKILL.md @@ -0,0 +1,121 @@ +--- +name: purview-buildsdk-testing +description: Write and run tests in a repository that uses Purview.BuildSdk. Use when authoring or refactoring TUnit tests (AAA structure, Subject_Scenario_Expectation naming, awaited assertions, CancellationToken), when choosing a test project's framework packages, and when running or filtering tests - the SDK wires Microsoft.Testing.Platform, so `dotnet test --filter` reports "Zero tests ran" and `--treenode-filter` is the one that works. +license: MIT +metadata: + package: Purview.BuildSdk + repository: purview-dev/build-sdk +--- + +# Testing in a Purview.BuildSdk repository + +Two things to know before anything else: + +1. A test project is detected by **name**, and detection is what wires the runner. See + `purview-buildsdk-project-layout` if the project is new or being moved. +2. The runner is **Microsoft.Testing.Platform (MTP)**, not VSTest. `--filter` does nothing useful. + +## What a test project gets automatically + +With the defaults (`TestingFramework=TUnit`, `SubstituteFramework=TUnitMocks`, +`TestDataFramework=Bogus`), a detected test project receives: + +- `TUnit`, `TUnit.Mocks`, `Bogus` +- Microsoft.Testing.Platform integration +- `CollectCoverage=true` +- test-friendly `NoWarn` defaults (`PurviewTestContextNoWarn`), while keeping the strict style + contract — `IDE0040`, field naming, formatting, `IDE1006` +- `IsPackable=false`, `IsPublishable=false` + +Add nothing else unless the project's purpose demands it. Two that stay explicit: + +- `TUnit.Aspire` — Aspire lifecycle and AppHost-backed integration tests +- `Purview.Containers` — container-backed integration tests. One API over Microsoft WSL Containers + (no Docker install needed on Windows) or Docker, with typed modules for SQL Server, PostgreSQL, + Redis, MySQL, RabbitMQ, Azurite and NATS. Experimental and prerelease, so pin the version. + Reference `Testcontainers` directly only where no typed module exists yet. + +## Authoring rules + +- Use TUnit (`TUnit.Core`, `TUnit.Assertions`). Do not introduce xUnit, NUnit, MSTest or + FluentAssertions unless explicitly asked. +- Every test method carries `[Test]`. +- **Every assertion is awaited**: `await Assert.That(actual).IsEqualTo(expected);`. An un-awaited + assertion silently passes. +- Arrange / Act / Assert, with the `// Arrange`, `// Act`, `// Assert` comments present. +- Test classes are `{SubjectName}Tests`, in the **same namespace** as the subject. +- Test methods are `{SubjectOrMemberUnderTest}_{Scenario}_{Expectation}`. Use `ctor` as the subject + for constructor tests. Methods, constructors, properties, operators, conversions and validation + hooks are all valid subjects. +- When any method called in the test body accepts a `CancellationToken`, take + `CancellationToken cancellationToken` as the **last parameter** and pass it through. + +```csharp +[Test] +public async Task ProcessAsync_GivenAnEmptyBatch_ReturnsZero(CancellationToken cancellationToken) +{ + // Arrange + var sut = new BatchProcessor(); + + // Act + var result = await sut.ProcessAsync([], cancellationToken); + + // Assert + await Assert.That(result).IsEqualTo(0); +} +``` + +For a suite that is not subject-based — a build, generator, workflow, package or full-system suite — +a broader, more truthful class name is better than a forced `{Subject}Tests`. Use TUnit display +names and categories to keep it navigable. + +When refactoring existing tests, bring them into compliance with all of the above while preserving +test intent. + +## Categories + +The detected test type becomes the baseline category automatically — `Api.IntegrationTests` yields +`Category=Integration`. Add further categories when they make a large suite easier to navigate; +they are what `--treenode-filter` property predicates select on. + +## Running tests + +```bash +dotnet test # the whole suite +dotnet test --treenode-filter "/*/*/LoginTests/*" # one class +dotnet test --treenode-filter "/*/*/*/*[Category=Unit]" +``` + +Prefer the repository's own task (`just test`, or equivalent) for a full run. + +The filter path is `////`, with `*` wildcards, `=`/`!=` property +predicates, `&`/`|` inside a single bracket group, and `**` only at the end. The full grammar, the +`--` separator rules across SDK versions, and the zero-tests checklist are in +[references/treenode-filter.md](references/treenode-filter.md). + +### "Zero tests ran" + +In order: + +1. Are you using `--treenode-filter` and not `--filter`? This is the cause most of the time. +2. Try `dotnet test --treenode-filter "..."`; on an older SDK use `dotnet test -- --treenode-filter "..."`. +3. Broaden to `/*/*/*/*`, then narrow one segment at a time. +4. Does the project actually contain `[Test]` methods? +5. Is the project **detected** as a test project? A name without the dot — `UnitTests` rather than + `Api.UnitTests` — gets no runner at all. Check with + `dotnet msbuild -getProperty:IsTestProject`. +6. Are all property predicates inside one bracket group, `[(A=1)&(B=2)]`? + +## Cross-platform requirement + +CI runs the full suite on Linux, so a test that only passes on Windows is a failing change. + +- Never hardcode a platform-specific path — no `C:\...`, no backslash-only separators, no + case-insensitive path assumptions. +- Build paths with `Path.Combine`, `Path.GetTempPath()`, `Path.DirectorySeparatorChar`, + `Path.GetFullPath()`. +- Feed production path-math code only native-format paths. Normalise a fixed Windows-style literal + to the current platform before passing it in. +- Do not rely on a case-insensitive filesystem, a `C:` drive, or trailing-separator behaviour. +- Keep `SyntaxTree` file paths and `build_property.*` values consistent and native when writing + analyzer tests. diff --git a/.claude/skills/purview-buildsdk-testing/references/treenode-filter.md b/.claude/skills/purview-buildsdk-testing/references/treenode-filter.md new file mode 100644 index 00000000..35d032bc --- /dev/null +++ b/.claude/skills/purview-buildsdk-testing/references/treenode-filter.md @@ -0,0 +1,107 @@ +# `--treenode-filter` reference + +TUnit runs on Microsoft.Testing.Platform, not VSTest, so the VSTest `--filter` syntax does not +apply. Narrowing is done with `--treenode-filter`. + +## The path + +```text +//// +``` + +Each segment maps to one level of the tree: + +| Position | Matches | +| -- | -- | +| 1 | Assembly | +| 2 | Namespace | +| 3 | Class | +| 4 | Test name | + +```text +/*/*/LoginTests/* every test in LoginTests +/*/*/*/AcceptCookiesTest one test by name +/*/MyProject.Tests.Integration/*/* every test in a namespace +/*/*/*/* everything +``` + +## Operators + +### `*` — wildcard + +Matches a whole segment or part of one. + +```text +/*/*/LoginTests*/* +/*/*/MyProject.Tests.Api*/* +``` + +### `=` and `!=` — property predicates + +In the last segment, inside `[...]`. + +```text +/*/*/*/*[Category=Unit] +/*/*/*/*[Category!=Slow] +/*/*/*/*[Owner=*Team-Backend*] +``` + +### `&` and `|` — combining + +Inside a **single** bracket group, or a single parenthesised segment. + +```text +/*/*/*/*[(Category=Unit)&(Priority=High)] +/**[(Category=Unit)|(Priority=High)] +/*/*/(LoginTests)|(SignupTests)/* +``` + +### `**` — match all + +Any depth, but **only at the end** of the path. + +```text +/** +/MyAssembly/** +``` + +`/**/Path` is not valid. + +## Rules that catch people out + +- Only **one** property group `[...]` per path segment. `[Category=Smoke]|[Priority=High]` is not + valid; write `[(Category=Smoke)|(Priority=High)]`. +- `**` must be last. +- A segment left empty is not a wildcard — write `*`. + +## The `--` separator + +```bash +dotnet test --treenode-filter "/*/*/*/*[Category=Unit]" # preferred +dotnet test -- --treenode-filter "/*/*/*/*[Category=Unit]" # older SDKs +``` + +Newer .NET SDKs forward unrecognised arguments to the MTP runner directly. On an older SDK the `--` +separator is required, and omitting it produces an argument error rather than a filter. + +## Common selections + +| Intent | Filter | +| -- | -- | +| Everything | `/*/*/*/*` | +| All unit tests | `/*/*/*/*[Category=Unit]` | +| High-priority unit tests | `/*/*/*/*[(Category=Unit)&(Priority=High)]` | +| One class | `/*/*/MyFeatureTests/*` | +| A name pattern | `/*/*/*/MyScenario*` | +| Critical integration tests | `/*/MyProject.Tests.Integration/*/*[Priority=Critical]` | + +## Zero tests ran + +1. `--treenode-filter`, not `--filter`. +2. Try without the `--` separator first, then with it. +3. Broaden to `/*/*/*/*`, then narrow one segment at a time. +4. Confirm the project has `[Test]` methods. +5. Confirm the project is **detected** as a test project — + `dotnet msbuild -getProperty:IsTestProject`. A name without the dot, such as + `UnitTests` rather than `Api.UnitTests`, is not detected and gets no runner. +6. Confirm every property predicate sits in one bracket group. diff --git a/.claude/skills/purview-results-core/SKILL.md b/.claude/skills/purview-results-core/SKILL.md new file mode 100644 index 00000000..93719fdd --- /dev/null +++ b/.claude/skills/purview-results-core/SKILL.md @@ -0,0 +1,140 @@ +--- +name: purview-results-core +description: "Use when writing or reviewing code that returns Purview.Results Result or value-less Result values — choosing between exceptions and results, creating, reading, or transforming a result, and reasoning about the uninitialized default state." +--- + +# Purview.Results core + +Use this skill whenever a method returns `Result` or the value-less `Result` from the +`Purview.Results` package. + +## The three states + +`Result` is a `readonly record struct`, so `default` is a real, observable state. + +| State | `IsInitialized` | `IsSuccess` | `IsFailure` | `Value` | `Error` | +| --- | --- | --- | --- | --- | --- | +| Success | `true` | `true` | `false` | the value | throws | +| Failure | `true` | `false` | `true` | throws | the error | +| Uninitialized (`default`) | `false` | `false` | `false` | throws | throws | + +`Value` and `Error` throw `InvalidOperationException` when the result is in the wrong state, and `Match`, `Map`, +`Bind` and `MapError` throw `"The result is uninitialized."` for `default`. **An uninitialized result is a bug, +never a success and never a failure** — if a method can fail to produce a result, return a failure case instead +of falling off the end of the method body. + +## Creating results + +```csharp +// Named factories +Result.Success(tenant); +Result.Failure(new TenantNotFound(id)); + +// Type-inferring factories +Result.Success(tenant); +Result.Failure(new TenantNotFound(id)); + +// Implicit conversions (one hop only) +Result ok = tenant; +TenantError error = new TenantNotFound(id); // case -> union is one hop +Result failed = error; // union -> result is the next hop + +// Union-receiver factory (generated for [GenerateResult] unions; shared-case safe) +TenantError.Failure(new TenantNotFound(id)); +TenantError.Failure(new TenantNotFound(id)); +TenantError.Success(); +TenantError.Success(tenant); +``` + +The implicit conversions accept `TValue` or `TError` directly. They do **not** compose: a union *case* cannot +convert to the result in one hop, which is why the source generator exists (see the +`purview-results-union-errors` skill). + +## Reading and transforming + +| Member | Purpose | +| --- | --- | +| `Match(success, failure)` | Fold both states into one value | +| `Map(map)` | Transform the successful value, preserving the error | +| `Bind(bind)` | Chain an operation that can fail, preserving the error type | +| `Bind(bind, mapError)` | Chain an operation that fails with a different error type, widening the existing error | +| `MapError(map)` | Transform the error, preserving the value | +| `TryGetValue(out value)` | Probe without throwing: `true` only for a success | +| `TryGetError(out error)` | Probe without throwing: `true` only for a failure | +| `GetValueOrDefault()` / `(fallback)` / `(factory)` | Value, or a default/fallback — throws for `default` | +| `GetErrorOrDefault(fallback)` | Error, or a fallback — throws for `default` | +| `OrElse(fallback)` | This result when successful, otherwise another result | +| `Switch(success, failure)` | Side effects per state; returns `void` | +| `Tap(success)` / `TapError(failure)` | Side effects that return the result, so calls can be chained | +| `Ensure(predicate, errorFactory)` | Turn a value that fails a predicate into a failure | +| `MapAsync(map)` / `BindAsync(bind)` | Asynchronous `Map`/`Bind` | +| `BindAsync(bind, mapError)` | Asynchronous widening `Bind` | +| `Throw()` | Return the value, or throw `ResultException` carrying the error (escape hatch) | + +Prefer `Match`/`Map`/`Bind` over `if (result.IsSuccess)` when a value has to come out of the result: they keep +the failure path explicit and cannot silently leak a `default`. + +`TryGetValue`/`TryGetError` are the only members that never throw; the rest throw for `default` so a forgotten +initialization surfaces immediately. + +## Value-less results + +When an operation has nothing to return on success — a command, a validation-only step — use `Result` +instead of inventing a meaningless value (a `bool`, a `Unit`). It has the same three states and the same +throw-on-misuse contract, but a success holds the `Success` marker and its success callbacks take no argument: + +```csharp +Result DeleteTenant(TenantId tenantId) => + _tenants.Remove(tenantId) + ? Result.Success() + : new TenantNotFound(tenantId).AsFailure(); + +deleted.Match(() => "deleted", error => $"could not delete: {error}"); +deleted.Map(() => 1); // attach a value: Result +deleted.Bind(() => GetTenant(tenantId)); // continue with another operation +deleted.Ensure(() => _tenants.Count > 0, () => new TenantError()); +``` + +- `Result.Success()` / `.Failure(error)`, `Result.Success()` / `Result.Failure(error)`, + and the implicit conversions from `Success` and `TError` create a unit result. +- `Match`, `Switch`, `Tap` and `Ensure` take a **no-argument** success delegate; `Map` produces a value from a + success that had none; `Bind` continues with either another unit operation or a value-producing one. +- `Error` throws in the wrong state; `Throw()` returns the `Success` marker or throws `ResultException`; + `ToString()` is `Success` / `Failure(error)` / `Uninitialized`. +- `Result.DiscardValue()` drops a value result's value and keeps the error, so a value result can + join a unit-result chain. + +Use `Result` when the failure is the only interesting outcome; use `Result` when the +caller needs the produced value. + +## Infrastructural view + +`IResultValue` is the non-generic, read-only view (`IsInitialized`, `IsSuccess`, `SuccessValue`, `ErrorValue`) +for code that cannot be generic over the value and error types — an endpoint filter or a logging middleware, for +example. Its accessors never throw: the one that does not describe the current state returns `null`, and a +successful unit `Result` reports the `Success` marker as its `SuccessValue`. Use it in infrastructure, and +the generic type in domain code. + +## When to use a result + +**Use it** for expected, domain-level outcomes the caller must handle: not found, invalid, conflict, disabled, +already exists. These are values with meaning, and making them explicit keeps the happy path readable. + +**Throw instead** for programming errors and unrecoverable infrastructure faults (a lost connection, a violated +invariant, a missing configuration key). Wrapping those in a result forces every caller to branch on something +it cannot act on. + +Rules of thumb: + +1. If the caller is expected to *do* something different per outcome, the outcome is a result value. +2. If the caller can only log and rethrow, it is an exception. +3. Never use `Result` where the failure is the only interesting outcome — use the value-less + `Result` instead, or model the outcomes as cases. +4. Convert at the boundaries: a controller or endpoint handler turns the result into a response, an application + service returns it, and repositories return it rather than throwing on "not found". + +## Related skills + +- `purview-results-union-errors` — modelling the error type as a union and generating the failure helpers. +- `purview-results-http-mapping` — turning results into ASP.NET Core responses. +- `purview-results-zodsharp-validation` — folding ZodSharp validation outcomes into results. diff --git a/.claude/skills/purview-results-http-mapping/SKILL.md b/.claude/skills/purview-results-http-mapping/SKILL.md new file mode 100644 index 00000000..ac4629ea --- /dev/null +++ b/.claude/skills/purview-results-http-mapping/SKILL.md @@ -0,0 +1,135 @@ +--- +name: purview-results-http-mapping +description: "Use when an ASP.NET Core endpoint returns Purview.Results values — registering AddResultsHttp, mapping error cases to status codes with Map, answering a failure by its shape with an IResultsFailureMapper, using fallbacks, correcting unmapped-failure 500s, or converting a result with ToHttpResult." +--- + +# Mapping results onto ASP.NET Core responses + +Use this skill when a minimal-API endpoint, or any handler, returns `Result` or the value-less +`Result` and the host has to decide what each error case looks like on the wire. + +## Registration + +```csharp +using Microsoft.Extensions.DependencyInjection; + +builder.Services.AddResultsHttp(options => options + .Map(error => TypedResults.NotFound()) + .Map(error => TypedResults.Problem( + statusCode: StatusCodes.Status403Forbidden, + title: "The tenant is disabled.")) + .Map(error => TypedResults.Problem(statusCode: StatusCodes.Status409Conflict)) // every other case +); + +app.MapGet("/tenants/{id:int}", (int id) => GetTenant(id)).WithResultsHttp(); +``` + +- `AddResultsHttp` registers problem-details services, the mapper (`TryAddSingleton`, so a host can register its + own first) and the endpoint filter. Its `configure` callback is optional. +- `WithResultsHttp()` exists on both `RouteHandlerBuilder` and `RouteGroupBuilder` and adds the endpoint filter. + A handler that returns something other than an `IResultValue` is left untouched, so the filter is safe to + apply to a whole group. +- Mapping by hand is also supported: `result.ToHttpResult(context)` resolves the mapper from the request + services, and `result.ToHttpResult(mapper, context)` takes one directly. + +## Response resolution order + +**Success** + +1. `SuccessMapper` when set — it replaces the default entirely. +2. A successful value that is itself an `IResult` is passed through untouched. +3. A successful unit `Result` carries no payload, so it answers `204 No Content`. +4. Otherwise the value is serialized: `200 OK` for the default status code, `TypedResults.Json(value, + statusCode: …)` when `SuccessStatusCode` was changed. + +**Failure** — the error is resolved to its *case* value (the innermost active union case, so a nested union +resolves to its leaf; or the error itself when it is not a union), then: + +1. the mapping registered for the most specific **case** type — `Map(…)`; +2. the mapping registered for each enclosing **union** type, from the inside out — `Map(…)` handles + a whole nested union when its leaf has no mapping; +3. the mapping registered for the **error** type — `Map(…)`, which covers every case without its + own mapping; +4. the **fallback stage**, in registration order — `AddFallback(...)` delegates and + `AddFailureMapper()` mappers share this one list, so whichever was registered first is consulted + first; returning `null` defers to the next entry; +5. the **unmapped-failure** response. + +Registering the same type twice replaces the earlier mapping. Fallbacks receive the *leaf* case value, so a +fallback never has to unwrap the union itself. + +## Shape-based rules + +`Map` is keyed by type, which cannot see the *value* a failure carries. When the answer depends on the +payload — a validation error code, a category, a field — register a failure mapper instead: + +```csharp +public sealed class BlankIdentifierMapper : IResultsFailureMapper +{ + public IResult? Map(ResultsFailureContext context) => + context.Case is ITenantFailure { TenantId.Value: var id } && string.IsNullOrWhiteSpace(id) + ? TypedResults.Problem(statusCode: StatusCodes.Status400BadRequest, title: "An identifier is required.") + : null; // defer to the case mappings and the other fallbacks +} + +builder.Services.AddSingleton(); +builder.Services.AddResultsHttp(options => options.AddFailureMapper()); +``` + +- `ResultsFailureContext` carries `Case` (the innermost active case, so a nested union resolves to its leaf; or + the error itself for a non-union error), `Error` (the union or error value as a whole) and `HttpContext`. +- The mapper is resolved from the request's services, so it may take dependencies in its constructor; register + it before the first request or the failure throws an `InvalidOperationException` naming what is missing. +- A mapper shares the fallback list with `AddFallback`, so **registering it earlier makes it win** — that is how + a host answers some validation codes before a package's validation mapping (see + `purview-results-zodsharp-problems`). +- **A mapper is not a catch-all.** Answering every failure with a generic problem hides the mapping gaps the + unmapped-failure `500` exists to expose. Answer the shape you can name and return `null` for the rest. + +## Options + +| Option | Default | Notes | +| --- | --- | --- | +| `SuccessStatusCode` | `200` | Status for a serialized successful value | +| `SuccessMapper` | `null` | Replaces the default success handling | +| `UnmappedStatusCode` | `500` | Status for a failure with no mapping | +| `UnmappedTitle` | *"The operation failed with an error that is not mapped to an HTTP response."* | Title of the unmapped problem | +| `ThrowOnUnmappedFailure` | `false` | Throw instead of responding; use during development | +| `IncludeTraceId` | `true` | Whether problems this package writes carry the request trace identifier | + +## Treat an unmapped failure as a bug in the host + +An unmapped failure is a **mapping gap**, not a domain outcome: the response is `UnmappedStatusCode` (`500`) +with a `ProblemDetails` carrying an `errorType` extension naming the case, and an error is logged. When you see +one in the logs, add the mapping; do not widen a catch-all mapping to silence it. + +The same path handles an **uninitialized** result (`default`), which is logged and answered with +`errorType = "results_uninitialized"` — an endpoint returning `default` is always a bug in the handler. + +During development, `ThrowOnUnmappedFailure = true` turns both into an `InvalidOperationException` so the gap +surfaces at the call site. + +## Choosing status codes + +Map the *case*, not the HTTP verb: + +| Domain meaning | Response | +| --- | --- | +| Input failed validation | `400` with a validation problem (see `purview-results-zodsharp-problems`) | +| Not authenticated / not authorised | `401` / `403` | +| The thing does not exist | `404` | +| The thing already exists | `409` | +| The thing is in the wrong state for this operation | `409` or `422` | +| Rate-limited or temporarily unavailable | `429` / `503` | + +Keep the mapping table next to `AddResultsHttp` so every case is visible in one place; a case that is missing +from it is exactly what the unmapped-failure log is telling you. + +## Pitfalls + +- **Do not** return `IResult` from domain or application code — results stay transport-agnostic and the host + keeps the mapping. +- **Do not** map a case to a status code you would not document; `500` for a domain outcome hides real bugs. +- A shared case type used by two unions can be mapped once — mapping is keyed by the case type. +- The unmapped `ProblemDetails` is written through `IProblemDetailsService`, so ASP.NET Core adds the trace + identifier itself; `IncludeTraceId` only affects problems this package serializes itself. diff --git a/.claude/skills/purview-results-union-errors/SKILL.md b/.claude/skills/purview-results-union-errors/SKILL.md new file mode 100644 index 00000000..ce6ea9ab --- /dev/null +++ b/.claude/skills/purview-results-union-errors/SKILL.md @@ -0,0 +1,179 @@ +--- +name: purview-results-union-errors +description: "Use when modelling expected failures as a C# 15 union and converting its cases into Purview.Results values — declaring [GenerateResult] unions, using the generated per-case AsFailure()/AsFailure() helpers and the union-receiver Union.Failure(...)/Union.Success(...) factories, reacting to the RSG1000-RSG1008 diagnostics, or explaining why a union case cannot convert implicitly." +--- + +# Modelling error unions for Purview.Results + +Use this skill when a codebase models expected failures as a **union** and returns +`Result` or the value-less `Result` from the `Purview.Results` package. + +Replacing thrown domain exceptions, `bool`/`out` pairs or error enums in existing code? The +step-by-step playbook is in +[references/migrating-error-returns.md](references/migrating-error-returns.md). + +## The shape + +```csharp +using Purview.Results; + +// One small, focused type per case. +public readonly record struct TenantNotFound(TenantId TenantId); +public readonly record struct TenantDisabled(TenantId TenantId); +public readonly record struct TenantAlreadyExists(TenantId TenantId); + +// One union per operation family. +[GenerateResult] +public readonly union TenantError(TenantNotFound, TenantDisabled, TenantAlreadyExists); + +public static Result Get(TenantId id) => + _tenants.TryGet(id, out var tenant) + ? Result.Success(tenant) + : new TenantNotFound(id).AsFailure(); // generated +``` + +`AsFailure()` and the non-generic `AsFailure()` are generated **once per case type**, into +`public static class {Union}ResultExtensions` in the union's own namespace. The generic helper calls +`Result.Failure(case)`; the non-generic one calls `Result.Failure(case)` and produces a +value-less unit result: + +```csharp +Result Get(TenantId id) => new TenantNotFound(id).AsFailure(); +Result Delete(TenantId id) => new TenantNotFound(id).AsFailure(); +``` + +The same class declares a C# 14 extension block on the union type, so the union can name the call instead of the +case: + +```csharp +Result Get(TenantId id) => TenantError.Failure(new TenantNotFound(id)); +Result Delete(TenantId id) => TenantError.Failure(new TenantNotFound(id)); +Result ok = TenantError.Success(); +Result created = TenantError.Success(tenant); +``` + +Prefer the union-receiver factory when a case type is shared with another union (`RSG1006`): the per-case +`AsFailure` helper is generated once and can bind to the wrong union, while `Union.Failure(...)` always names the +union you want. A case type that is itself a union is an *included union*: sharing it is composition, so it is not +reported, and the factory also covers the included union's cases by building the nested value. + +## Why the helper is required + +The generator cannot declare an implicit conversion from a case to the result, and neither can you. Five +independent C# rules block it: + +| Attempt | Diagnostic | +| --- | --- | +| Declare the operator beside the helpers | `CS0715` — operators are illegal in a **static class** | +| Declare it in any other helper class | `CS0556` — a conversion must be declared by the **source or target type** | +| Declare it as an extension member | `CS9282` — **conversions are not allowed in extension blocks** | +| Make it generic over the result's value type | `CS0246` — operators **cannot declare type parameters** | +| Rely on `case → union → result` composing | `CS0029` — **one user-defined conversion per sequence** | + +The only shape the language accepts is a *generic case type* carrying the value type parameter, which the +generator rejects as `RSG1002` — so `AsFailure()` is the ergonomics the language allows. + +A helper-free form exists when a cast reads better, because the cast closes the first conversion: + +```csharp +Result Get(TenantId id) => (TenantError)new TenantNotFound(id); +``` + +`Purview.Results` also ships an IDE code fix: when you write +`return new TenantNotFound(id);` in a `Result`- or `Result`-returning member, the +lightbulb offers the `Union.Failure(case)` or `Union.Failure(case)` rewrite. The fix names the union, so it +is correct even when the case type is shared with another union. It is only offered when the rewrite will bind (the +converted type is a result, the error type is a `[GenerateResult]` union, the value is one of its cases, and the +union is in scope by simple name). + +## Chaining across services + +When one service calls another, the caller's operation-family union takes the callee's **error union** as a case, +then the widening `Bind` (or a `TryGetError` guard) lifts the callee's failure into the caller's contract: + +```csharp +[GenerateResult] +public readonly union RegisterTenantError(TenantError, BillingError); + +Result Register(TenantId id, string name) => + billing.ReserveQuota(id) + .Bind(quota => CreateTenant(quota, name), error => error); // BillingError -> RegisterTenantError +``` + +List the union as a case, not its leaf cases: the caller's union-receiver factory then covers the callee's cases and +builds the nested value (`CallerUnion.Failure(leaf)`), so no leaf is shared and no `RSG1006` is raised. A leaf listed +in two unions is a shared leaf: its per-case helper is generated for only one of them, so a case-receiver call site +can bind to the wrong union; convert it with the union-receiver factory instead. A case reachable through two +different included unions is reported as `RSG1008` and its inclusion factory is skipped. To keep the callee's types +out of the caller's contract, map its cases into the caller's own case types with `MapError` instead — the compiler +then forces the mapping to stay exhaustive as the callee's union grows. The ASP.NET Core mapper resolves a union +error to its innermost case, so a leaf mapping wins and an enclosing-union mapping still applies when the leaf has +none. + +## Rules of thumb + +- **One case type, one meaning.** Cases are the vocabulary of the failure surface; a case with a `string + Reason` invites callers to match on that string instead of on the type. +- **One union per operation family**, not one per method: `TenantError` covers every way tenant work fails, so + the union stays a stable contract while methods come and go. +- **Never re-derive the case from the union in the caller** — keep the case strongly typed and let the HTTP or + UI layer map it (see the `purview-results-http-mapping` skill). +- **Small unions are better.** A union with a dozen cases is usually several operation families sharing one + name. +- **Opt in deliberately.** `[GenerateResult]` on a union you do not return from a result produces dead code; + apply it where the union crosses a `Result` boundary. + +## Diagnostics + +The package ships an analyzer and a generator that share one diagnostics library. + +| ID | Severity | Meaning | +| --- | --- | --- | +| `RSG1000` | Error | `[GenerateResult]` was applied to a type that is not a union | +| `RSG1001` | Error | The union declares no union cases | +| `RSG1002` | Error | Generic union, or a case type that contains type parameters | +| `RSG1003` | Error | A type generated code must reference is not accessible (for example a `file` type) | +| `RSG1004` | Error | The same union is configured more than once; the helpers are generated once | +| `RSG1005` | Error | Two unions produce the same generated class name in one namespace | +| `RSG1006` | Warning | A **leaf** case type is shared with another union, so its per-case `AsFailure` helper is generated once; the union-receiver `Failure(...)` factory is generated for every union. A union-typed case shared across unions is composition and is not reported | +| `RSG1007` | Error | The union uses an `IUnionMembers` member provider, which is not supported | +| `RSG1008` | Warning | A case is reachable through two different included unions, so no inclusion factory can name its construction path; that case's inclusion factory is skipped | + +`RSG1004`, `RSG1006` and `RSG1008` are non-blocking: the union (or the shared/ambiguous case) is skipped and +reported. + +Unsupported by design: `IUnionMembers` member providers (`RSG1007`) and generic unions (`RSG1002`). + +## CA1815 needs no pragma + +A union declaration gets no value equality from the compiler, so it raises `CA1815` unless it is silenced by hand. +`[GenerateResult]` unions do not need that: the package ships a diagnostic suppressor that answers `CA1815` for +every union opted in with the attribute, because a result union is read by matching its case type rather than +compared by value. + +- Only the union is covered. A union without `[GenerateResult]`, the union's case types and every other value + type keep the warning, and a case declared as a plain `struct` should still be a `record struct`. +- The suppression is logged as an `Info` diagnostic under the suppression id `RSG2000`, so a build audit can see + exactly what was suppressed. +- `RSG2000` is a suppression id, not a rule: it never appears in the diagnostics table above, and + `$(NoWarn);RSG2000` brings `CA1815` back. + +## Requirements and switches + +- **.NET 11 SDK or later** with `LangVersion=preview` — union declarations are a preview language feature. +- A reference to `Purview.Results`, which provides both result shapes (`Result` and + `Result`) and this generator. +- `-p:DisableResultsSourceGenerator=true` (or a `Directory.Build.props` setting) disables the helpers while + the opt-in attribute is still emitted, which is useful when the generated code has to be inspected in + isolation. + +## Checklist + +1. Cases are small records with meaningful payloads. +2. The union is a `union` declaration annotated with `[GenerateResult]`. +3. Every method that fails for an expected reason returns `Result`, or `Result` when the + success carries no value. +4. Failures are produced with `new Case(...).AsFailure()` (or `AsFailure()` for a unit result, the + union-receiver `Union.Failure(case)` / `Union.Failure(case)` factory, or the cast form). +5. The build is clean of `RSG1000`–`RSG1008`. +6. The union is mapped to responses once, in the host (see `purview-results-http-mapping`). diff --git a/.claude/skills/purview-results-union-errors/references/migrating-error-returns.md b/.claude/skills/purview-results-union-errors/references/migrating-error-returns.md new file mode 100644 index 00000000..b0405f44 --- /dev/null +++ b/.claude/skills/purview-results-union-errors/references/migrating-error-returns.md @@ -0,0 +1,67 @@ +# Migrating ad-hoc failure signalling to an error union + +A playbook for replacing thrown domain exceptions, `bool`/`out` pairs, sentinel return values and +error-code enums with a C# 15 `union` of case types returned as `Result`. + +## Before you start, collect + +- The file(s) being migrated, and the operation family they belong to — a union is per family, not + per method, so methods can come and go without changing the error contract. +- A name for the union (for example `TenantError`). +- The failure modes to model as cases, or the decision to infer them from the current code. +- Whether genuinely exceptional exits stay throwing. They normally should: a lost connection or a + violated invariant is not a domain outcome. + +## Requirements + +1. Declare one `readonly record struct` per failure mode, carrying the payload a caller needs to + react, and declare the union once: + + ```csharp + [GenerateResult] + public readonly union TenantError(TenantNotFound, TenantDisabled, TenantAlreadyExists); + ``` + +2. Change the affected signatures to `Result` — or the value-less + `Result` when the member has nothing to return on success — and produce failures with + `TenantError.Failure(case)` / `TenantError.Failure(case)`, or the per-case + `new Case(...).AsFailure()` / `AsFailure()` helpers. +3. Leave genuinely exceptional exits throwing. +4. Do **not** attempt implicit conversions from a case to a result, and do not add operators, + extension conversions or wrapper types: `CS0715`, `CS0556`, `CS9282`, `CS0246` and `CS0029` each + block that route. Use the generated factory or helper, or `(TenantError)new TenantNotFound(id)` + when a cast reads better. Prefer the union-receiver factory when a leaf case type is shared with + another union (`RSG1006`), because it names the union. +5. Remove the replaced mechanism — thrown domain exceptions, error enums, `out` error parameters, + sentinel values — rather than leaving both paths in place. +6. Keep the union free of transport concerns: no `IResult`, no status codes, no HTTP types. +7. One case type per meaning. A case carrying a `string Reason` or an `int Code` invites string or + int matching and defeats the point. +8. Compose unions rather than repeating leaf cases. A case type that is itself a union is an + *included union*: the including union's factory also covers its cases and builds the nested value, + and sharing a union-typed case across unions is not reported. This is how to avoid `RSG1006`, + which applies only to a shared **leaf** case. + +## Migration strategy + +- Inventory the failure modes and the call sites of each affected member. +- Introduce the cases and the union before changing signatures, so each edit compiles in isolation. +- Update call sites to `Match` / `Map` / `Bind` where a value has to come out of the result, rather + than `if (IsSuccess)`. +- Update or add tests: one per case, asserting the case the caller receives. +- Map the union once in the host — see the `purview-results-http-mapping` skill — instead of deciding + status codes in the domain. + +## Verification + +- Build the solution and confirm no `RSG1000`–`RSG1008` diagnostics. +- Run the affected tests. +- Confirm no remaining `throw` for an outcome the caller is expected to handle. +- Confirm the union appears in exactly one mapper, not scattered through handlers. +- Confirm no method can fall off the end of its body: `default` is a bug, not a failure. +- Reflect public API changes in the package documentation. + +## Report + +When the migration is done, state: the files changed, the union and its cases, the failure modes that +stayed exceptional and why, and the verification performed. diff --git a/.claude/skills/purview-results-zodsharp-problems/SKILL.md b/.claude/skills/purview-results-zodsharp-problems/SKILL.md new file mode 100644 index 00000000..ed0dd935 --- /dev/null +++ b/.claude/skills/purview-results-zodsharp-problems/SKILL.md @@ -0,0 +1,101 @@ +--- +name: purview-results-zodsharp-problems +description: "Use when a Purview.Results failure that carries ZodSharp validation errors has to render as an ASP.NET Core HttpValidationProblemDetails — registering AddResultsZodSharpHttp, calling ToValidationProblem, or making a result-carried rejection and a thrown ZodException produce identical responses." +--- + +# Rendering validation-carrying failures as validation problems + +Use this skill when a result failure carries ZodSharp `ValidationError` values (it implements +`IValidationErrorCarrier`) and the host has to respond with `application/problem+json`. + +## Registration + +```csharp +builder.Services.AddZodSharpProblemDetails(); // the ZodSharp package's own problem options/exception handler +builder.Services.AddResultsHttp(); // the result-to-response mapping +builder.Services.AddResultsZodSharpHttp(); // the bridge: validation-carrying failures -> validation problem +``` + +- `AddResultsZodSharpHttp()` registers the ZodSharp problem options (a no-op when the host already did) and adds + a **failure mapper** (`ZodResultsFailureMapper`) to the fallback stage. +- Because it is a failure mapper, **a mapping the host registered for a specific error case always wins**, a + mapping registered for the error type wins too, and a host failure mapper registered *before* + `AddResultsZodSharpHttp` wins as well. That is the escape hatch: when a case deserves its own response, register + it — and when a validation **code**, **category** or **origin** deserves one, use the rules below. +- Pair it with `AddZodSharpProblemDetails()` so a thrown `ZodException` and a result-carried rejection are + rendered by the same mapper and therefore produce identical responses. + +## Rules per validation error code, category and origin + +Pass a callback to answer particular codes, categories or origins with a response of their own: + +```csharp +builder.Services.AddResultsZodSharpHttp(options => options + .MapCode("tenant_not_found", StatusCodes.Status404NotFound) // validation problem, 404 default + .MapCode("tenant_id_matches_name", (errors, context) => TypedResults.Conflict()) + .MapCategory("invalid_value", StatusCodes.Status422UnprocessableEntity) + .MapOrigin("value_object", StatusCodes.Status422UnprocessableEntity) // every type-level rule failure +); +``` + +The three axes are the identity a `ValidationError` carries: **code** (the specific rule), **category** (a broad +grouping many codes share) and **origin** (the structured origin a rule owns — `"value_object"` for a type-level +rule, `"array"` for a collection rule). Reach for `MapOrigin` when the answer is keyed by the *kind* of rule +rather than one code. + +Matching and precedence: + +1. every matching **code** rule in registration order, +2. then every matching **category** rule in registration order, +3. then every matching **origin** rule in registration order, +4. then the default validation problem — so rules only ever narrow what the host already gets. + +- A rule matches when **any** of the failure's errors carries its code/category/origin, so a registered rule is + always reachable; a factory that wants stricter semantics returns `null` to decline and matching continues. +- A factory receives the failure's **whole error set**, so a rule never hides the other problems the caller has + to fix; the `int statusCode` overloads still render every error. +- A code, category or origin registered twice with different behaviour throws at configuration time. + +## Rendering by hand + +| Member | Purpose | +| --- | --- | +| `IValidationErrorCarrier.ToValidationProblem(context, statusCode = 400)` | Renders the errors the error value carries | +| `ImmutableArray.ToValidationProblem(context, statusCode = 400)` | Renders a set of errors | +| `ZodValidationProblems.ToProblem(errors, options, defaultStatusCode = 400, traceId = null)` | The underlying mapper, for hosts that resolve the options themselves | + +```csharp +if (result.Error is IValidationErrorCarrier carrier) + return carrier.ToValidationProblem(context); +``` + +The response is written as `application/problem+json` through `TypedResults.Json`, so it does not depend on the +MVC problem-details writer. + +## Status code and trace identifier + +- The status code resolved by `ZodProblemDetailsOptions.StatusCodeSelector` wins. +- `statusCode` (or `defaultStatusCode`) is only used when the resolved error type does not define one — the + default is `400 Bad Request`. +- The request trace identifier is included when `ResultsHttpOptions.IncludeTraceId` is `true` (the default). + +## Pitfalls + +- **Do not reimplement error-to-problem mapping.** Reuse `ZodValidationProblems.ToProblem` so a carried failure + and a thrown `ZodException` cannot drift apart in status code, title, `errors` shape or `issues` extension. +- **Do not map the whole union to a validation problem** unless every case is a validation failure; map the + carrying case (or rely on the mapper, which already does exactly that). +- If a case does deserve its own response, still build it from `ToValidationProblem(context)` when the payload + is validation data, so clients see one shape. +- The mapper receives the *case* value, so the carrier is the union case that implements the interface — not + the union itself (`ResultsFailureContext.Error` carries the union when a rule needs it). + +## Verifying the pairing + +A test that exercises both paths is the cheapest guard against drift: + +1. return a failure carrying validation errors through an endpoint, and +2. throw the same errors as a `ZodException` through the host's exception handler, + +then assert the two response bodies are equal. See the `purview-results-http-mapping` skill for the surrounding +registration and status-code guidance. diff --git a/.claude/skills/purview-results-zodsharp-validation/SKILL.md b/.claude/skills/purview-results-zodsharp-validation/SKILL.md new file mode 100644 index 00000000..83bc66c6 --- /dev/null +++ b/.claude/skills/purview-results-zodsharp-validation/SKILL.md @@ -0,0 +1,121 @@ +--- +name: purview-results-zodsharp-validation +description: "Use when ZodSharp validation has to feed Purview.Results — converting ValidationResult with ToResult or the value-discarding ToUnitResult, carrying ValidationError values on a union case, implementing IValidationErrorCarrier, or deciding what a rejected input becomes in the result pipeline." +--- + +# Folding ZodSharp validation into results + +Use this skill when a codebase validates with the `Purview.ZodSharp` package and returns +`Purview.Results` values, and a rejected input has to become an ordinary failure rather than an exception. + +## The conversion + +```csharp +using Purview.Results; +using Purview.Results.ZodSharp; + +return RepositoryReconciliationResultSchema + .Validate(reconciliationResult) + .ToResult(errors => + new ReconciliationResultInvalid(reconciliationResult, errors) // a union case + ); +``` + +`ToResult(onFailure)`: + +- returns a **success carrying the validated value** when validation passed; +- returns a **failure carrying the created error** when it failed; +- invokes `onFailure` only for a failure, so a successful validation allocates no error; +- takes the error type explicitly, and it must be named when it is a union, because a union case does not carry + the union type that contains it. + +ZodSharp validation never throws: `Validate` returns the value on success and every `ValidationError` on +failure. Keep it that way — map the outcome, do not re-throw it. + +## When the validated value is not the method's success type + +`ToResult` can only produce a result whose success type is the validated type. When the surrounding method +succeeds with something else (a repository result, an aggregate, a summary), produce the failure with the +generated helper instead: + +```csharp +var validated = ProviderConnectionIdSchema.Validate(providerConnectionId); + +if (!validated.IsSuccess) + return new ProviderConnectionInvalid(providerConnectionId, validated.Errors) + .AsFailure(); + +return await ReconcileCoreAsync(validated.Value, repositories, cancellationToken); +``` + +This keeps the failure case carrying the errors while the success type stays whatever the method actually +produces. + +## When the method has no success value + +When the method reports only why an input was rejected, `ToUnitResult` discards the validated value and returns a +value-less `Result`. It still names the validated value type, because a union case does not carry its +union: + +```csharp +Result Validate(TenantInput input) => + TenantInputSchema + .Validate(input) + .ToUnitResult(errors => new TenantInputInvalid(input, errors)); +``` + +Use `ToResult` when the success carries the validated value, `ToUnitResult` when it carries nothing, and the +generated `AsFailure()` when the success carries something else. + +## Async validation + +`ValidateAsync` returns a `ValueTask>`, and the async counterparts fold it in the same way: + +```csharp +async Task> Validate(TenantInput input, CancellationToken cancellationToken) => + await TenantInputSchemaValidator + .ValidateAsync(input, cancellationToken) + .ToUnitResultAsync(errors => new TenantInputInvalid(input, errors)); +``` + +- `ToResultAsync` carries the validated value on success; `ToUnitResultAsync` discards it. +- The error type is named explicitly for the same reason as the synchronous forms. +- Do not block on `ValidateAsync` to reuse the synchronous methods — that reintroduces the sync-over-async the + bridge exists to avoid. + +## Carrying the errors + +```csharp +public readonly record struct ProviderConnectionInvalid( + ProviderConnectionId ProviderConnectionId, + ImmutableArray ValidationErrors +) : IValidationErrorCarrier; +``` + +Implement `IValidationErrorCarrier` on the case (or error) that carries ZodSharp `ValidationError` values. +`ValidationErrors` preserves each error's code, origin, category, path and parameters, so an HTTP layer can render +a validation problem **without knowing the error type** — which is exactly how +`Purview.Results.ZodSharp.AspNetCore` maps it (see the `purview-results-zodsharp-problems` skill). + +Guidance: + +- **Keep the errors on the case**, never flatten them into a message string; the structured form is what clients + and problem responses need. +- **One carrier per rejection**, holding the whole `ImmutableArray` for that input. +- Implementing the interface (rather than a helper that extracts errors) lets the HTTP mapping stay generic. + +## Why there is no factory that returns a result + +`ToResult` takes `Func, TError>` on purpose. A lambda that returns +`Result` would bind to that parameter — C# prefers `Func<…, TError>` — and silently nest the +results. Naming the error type explicitly keeps the intent unambiguous. + +## Checklist + +1. Validation outcomes are mapped, never thrown. +2. The error type is named explicitly (`ToResult(…)` or `ToUnitResult(…)`, and + the async counterparts for a `ValidateAsync` outcome). +3. The case that carries the errors implements `IValidationErrorCarrier`. +4. A method whose success type differs uses `AsFailure()`, or `AsFailure()` for a unit result, with the + validation errors. +5. The host maps the carrier to a validation problem once (see `purview-results-zodsharp-problems`). diff --git a/.claude/skills/purview-sourcegenerator-codewriter/SKILL.md b/.claude/skills/purview-sourcegenerator-codewriter/SKILL.md new file mode 100644 index 00000000..ee363c97 --- /dev/null +++ b/.claude/skills/purview-sourcegenerator-codewriter/SKILL.md @@ -0,0 +1,334 @@ +--- +name: purview-sourcegenerator-codewriter +description: >- + Use when implementing, reviewing or refactoring C# source generators and analysers built on + Purview.SourceGeneratorFramework. Covers CodeWriter and XmlCommentWriter emission, scope safety, + incremental pipeline design, value equality, deterministic output, and migrating a legacy + string/StringBuilder emitter to CodeWriter. +metadata: + product: Purview.SourceGeneratorFramework + repository: purview-dev/sourcegenerator-framework +--- + +# Source generator CodeWriter modernization + +Use this skill for any work involving C# source generators, analysers, or generated output in `Purview.SourceGeneratorFramework`. It combines CodeWriter/XmlCommentWriter emission guidance with the incremental-source-generator and analyser best practices that ship with the framework. + +Refactoring an existing emitter off `string`/`StringBuilder`? The step-by-step playbook is in +[references/legacy-emitter-migration.md](references/legacy-emitter-migration.md). + +## Required implementation pattern + +When creating source output, favor this shape: + +1. Build immutable, value-equatable pipeline values first. +2. Register source output. +3. Inside the callback: `var writer = generationContext.CreateCodeWriter();` +4. Write header/usings/namespace. +5. Write structured types and members using declaration options records. +6. Add source once per output artifact. + +### CodeWriter lifetime: created in the output callback, never in pipeline state + +The line between "fine" and "forbidden" is the **incremental-cache boundary**, not the act of +creating a writer or handing it to a helper. + +**Fine — output-scoped use inside a `RegisterSourceOutput` callback.** Create the writer inside the +callback and pass it to any emitter/helper methods called from that same callback. It may be held in +local variables, passed as a parameter, or wrapped in a short-lived output context: + +```csharp +context.RegisterSourceOutput( + targets.CombineWithContext(contextProvider), + static (spc, pair) => + { + var (model, generationContext) = pair; + var writer = generationContext.CreateCodeWriter(); + EmitHeader(writer, model); + EmitType(writer, model); + spc.AddSource($"{model.Name}.g.cs", writer.ToString()); + } +); +``` + +**Forbidden — persisting the writer across the incremental-cache boundary.** Do not create it earlier +in the pipeline and pass it down, and do not store it anywhere Roslyn caches or another callback can +observe it: + +- Do not create a `CodeWriter` in a provider stage and carry it through the pipeline. +- Do not store a `CodeWriter` as a property or field on `GenerationContext` or a custom context. +- Do not return a `CodeWriter` (or an object holding one) from an incremental provider. +- Do not cache or reuse a writer for a later callback or a different output. + +A cached writer can retain previously written source, mix output from concurrently running +callbacks, and defeat scope tracking. A writer created in the callback and used only within that +callback is safe and expected. + +## Source generator & analyser best practices + +Apply the following rules to every generator, analyser, and refactor. + +### 1. Core principles + +- **Analyser for validation; generator for generation.** +- **Syntax for syntax, symbols for declarations, operations for executable semantics.** +- **Use `ForAttributeWithMetadataName` for attribute-driven generators.** +- **Remove Roslyn objects from the incremental pipeline as early as possible.** +- **Every value crossing a pipeline boundary must have meaningful value equality.** +- **Prefer many small incremental stages over one large transform.** +- **Keep broad inputs such as `Compilation` away from downstream generation.** +- **Generate deterministic output.** +- **Compile against the oldest Roslyn API version containing the functionality you need.** +- **Test caching, not just generated text.** + +The guiding principle for an incremental generator is: + +> Extract semantic information once, convert it into a small value model, and make everything downstream operate only on that value model. + +### 2. Analyser vs source generator + +Use a `DiagnosticAnalyser` when the question is: + +> Is the source code valid according to this library's rules? + +Use an `IIncrementalGenerator` when the question is: + +> Given valid source code, what source should be generated? + +| Requirement | Prefer | +| --- | --- | +| Require a class to be `partial` | Analyser | +| Require an attribute on a declaration | Analyser | +| Validate a method signature | Analyser | +| Reject unsupported property types | Analyser | +| Detect invalid attribute arguments | Analyser | +| Detect unsupported API usage | Analyser | +| Offer an automatic fix | Analyser + `CodeFixProvider` | +| Generate members for a marked class | Incremental generator | +| Generate serializers/validators/mappers | Incremental generator | +| Generate a registry from discovered types | Incremental generator | +| Read a schema file and generate C# | Incremental generator | +| Internal generation failure | Generator diagnostic | + +### 3. Choosing an analyser action + +Use the narrowest API that represents the concept being analysed: + +- `RegisterSyntaxNodeAction` — exact source syntax (e.g., modifier presence). +- `RegisterSymbolAction` — declaration semantics (e.g., attributes, interfaces, accessibility). +- `RegisterOperationAction` — executable behaviour (e.g., invocation, assignment, object creation). +- `RegisterOperationBlockStart/EndAction` — stateful method analysis. +- `RegisterSymbolStart/EndAction` — type-wide analysis across members. +- `RegisterCompilationStartAction` — resolve known framework symbols once. +- `RegisterAdditionalFileAction` — analyse `AdditionalFiles`. +- Avoid `RegisterSyntaxTreeAction`, `RegisterSemanticModelAction`, and compilation-end actions unless genuinely necessary. + +### 4. Syntax vs symbol vs operation + +Decision tree: + +1. Does exact source spelling/structure matter? → **Syntax** +2. Otherwise, is it a declaration? → **Symbol** +3. Otherwise, is it executable behaviour? → **Operation** + +Use `SymbolEqualityComparer.Default.Equals(...)` when comparing symbols. + +### 5. Analyser best practices + +- Enable concurrent execution with `context.EnableConcurrentExecution()`. +- Explicitly configure generated-code analysis with `context.ConfigureGeneratedCodeAnalysis(...)`. +- Resolve known framework/library symbols once in a `RegisterCompilationStartAction`. +- Prefer narrow registrations over scanning entire syntax trees or compilations. +- Treat diagnostic IDs as public contracts and maintain release tracking files when publishing public diagnostics. + +### 6. Incremental generator golden rules + +Implement `IIncrementalGenerator`. Simply implementing it is not enough; the pipeline must be incremental. + +> **Pipeline values must be immutable and value-equatable.** + +Never keep these in persistent pipeline models: + +| Type | Verdict | +| --- | --- | +| `ISymbol` / `INamedTypeSymbol` / `IMethodSymbol` / `IPropertySymbol` | Never retain | +| `Compilation` | Do not propagate | +| `SemanticModel` | Do not propagate | +| `IOperation` | Do not propagate | +| `SyntaxTree` | Do not propagate | +| `SyntaxNode` | Remove ASAP | +| `Location` | Remove ASAP | +| `AdditionalText` | Project immediately | +| `T[]` / `List` | Avoid | +| `ImmutableArray` | Wrap with sequence equality | + +Use immutable records and `EquatableArray` (sequence equality) for collection members. + +### 7. Designing the pipeline + +Pipeline shape: + +```text +Roslyn Input + ↓ +Cheap discovery + ↓ +Semantic extraction + ↓ +Small equatable model + ↓ +Validation/transformation + ↓ +Generation model + ↓ +Source output +``` + +Guidelines: + +- Project the semantic transform as the boundary where Roslyn objects disappear. +- Prefer `static` callbacks to avoid capturing generator state. +- Honour cancellation tokens. +- Split transformations into many small stages. +- Keep syntax predicates cheap. +- Avoid indirect discovery (every interface implementation, every subclass, entire-compilation scans). + +### 8. Syntax discovery + +- Prefer `context.SyntaxProvider.ForAttributeWithMetadataName(...)` for attribute-driven generators. +- Use `context.SyntaxProvider.CreateSyntaxProvider(...)` only when syntax itself is the trigger and there is no marker attribute. +- The predicate must be cheap; do not walk the tree or do semantic work in it. + +### 9. `Collect`, `Combine`, and invalidation + +- `Collect()` turns per-item outputs into one aggregate. Changing any item invalidates the aggregate. +- Use `Collect()` only for genuinely global output: registries, lookups, duplicate detection, aggregate switches. +- Prefer per-item `RegisterSourceOutput`. +- `Combine()` is correct when the output depends on two providers. +- Avoid `models.Combine(context.CompilationProvider)` — project the compilation to a tiny capability fact first. +- Use `.WithComparer(...)` only when logical equality differs from the default. + +### 10. Diagnostics + +- Prefer a separate `DiagnosticAnalyser` for normal user validation. +- Use generator diagnostics only for malformed additional files, generator-only configuration, conflicting output, or failures that cannot be expressed by an analyser. +- Report diagnostics on the most useful user-authored `Location`. +- Do not keep `Location` in long-lived pipeline models. + +### 11. Output generation + +- Output must be deterministic: no timestamps, random GUIDs, process IDs, machine paths, culture-dependent output, or unordered dictionary output. +- Hint names must be deterministic, unique, and stable. +- Prefer text generation or `CodeWriter` over building Roslyn syntax trees just to stringify them. +- Use `RegisterPostInitializationOutput` for constant source such as marker attributes. +- Add generated source once per output artifact. + +### 12. Testing incrementally + +- Snapshot-testing generated source is not enough. +- Test first execution, cached second execution, unrelated changes remaining cached, per-target invalidation, deletion, renaming, global options, additional files, and global registry invalidation. +- Use `GeneratorDriverOptions` with `trackIncrementalGeneratorSteps: true` and inspect reasons: `New`, `Modified`, `Unchanged`, `Cached`, `Removed`. + +### 13. Roslyn version compatibility and packaging + +- The `Microsoft.CodeAnalysis.*` version used to compile the analyser/generator sets the minimum compiler-host requirement. +- The consumer's `TargetFramework` does not determine analyser compatibility. +- Choose the oldest Roslyn version that contains the APIs you need. +- Common baselines: Roslyn 4.8 for VS 17.8 / .NET 8, 4.12 for VS 17.12 / .NET 9, 5.0 for VS 2026 18.0 / .NET 10. +- Ship one `netstandard2.0` analyser/generator binary unless you have a deliberate multi-version strategy. +- Do not mistake multi-targeting for automatic analyser asset selection. +- Use `PrivateAssets="all"` for Roslyn development dependencies. +- Enable `EnforceExtendedAnalyzerRules` and investigate `RSxxxx` diagnostics before suppressing them. + +### 14. Recommended project configuration + +A generator project should normally include: + +```xml + + netstandard2.0 + latest + enable + true + false + true + true + + + + + + + + + + +``` + +## Preferred API map for CodeWriter + +### File and namespace + +- `AutoGeneratedHeader(...)` +- `Using(...)` +- `FileScopedNamespace(...)` or `BlockNamespace(...)` +- `OpenPragmasScope(...)` for warning suppression scopes + +### Types and members + +- Types: `Class`, `Struct`, `RecordClass`, `RecordStruct`, `Interface`, `Enum`, `Delegate` +- Members: `Method`, `MethodScope`, `Property`, `Field`, `Constructor` +- Attributes: `AttributeDeclarationOptions`, `AttributeArgumentOptions` +- Type syntax: `TypeReference` (nullable/generic/array/pointer-safe composition) + +### XML documentation + +Use `XmlCommentWriter` extension methods on `CodeWriter`: + +- `XmlSummary(...)`, `XmlParam(...)`, `XmlTypeParam(...)`, `XmlReturn(...)`, `XmlRemarks(...)`, `XmlExample(...)` +- `XmlCode(...)` / `XmlCodeBlock(...)` +- `XmlList(...)`, `XmlSeeAlso(...)`, `XmlException(...)` + +Static helpers: `CodeWriter.XmlInlineCode(...)`, `CodeWriter.XmlSee(...)`, `CodeWriter.XmlParamRef(...)`, `CodeWriter.XmlText(...)`. + +## Refactoring guide: string/StringBuilder -> CodeWriter + +Apply this checklist in order: + +1. **Move emission boundaries** — replace giant string assembly with phases: header, namespace, type, members. +2. **Replace manual braces/indentation** — use `using` scopes (`ClassScope`, `MethodScope`, `OpenBlockScope`, `IndentedScope`). +3. **Replace handwritten signatures** — use declaration option records. +4. **Replace raw XML lines** — use XML extension methods (`XmlSummary`, `XmlParam`, etc.). +5. **Normalize type strings** — use `TypeReference`. +6. **Preserve semantics and ordering** — generated members and diagnostics must remain equivalent. +7. **Validate scope safety** — keep or enable `PurviewSourceGeneratorFrameworkValidateCodeWriterScopes` for tests/dev. + +## Anti-patterns to remove during refactors + +- `StringBuilder.AppendLine("public class ...")` for declarations that can be structured. +- Manually writing `{` / `}` around methods and types where scope APIs exist. +- Hard-coded nullable type suffixes and generic syntax in arbitrary strings when `TypeReference` is available. +- Raw XML tag string composition when XML extension methods can enforce consistency. +- Creating a `CodeWriter` before the output callback and passing it through the pipeline. +- Storing a `CodeWriter` on `GenerationContext`, a custom context, or any incremental pipeline model. +- Sharing one `CodeWriter` across multiple generated outputs or callbacks. +- Keeping Roslyn objects, `CodeWriter`, or mutable state in incremental pipeline models. + +## Review checklist for pull requests + +- Generated declarations use structured APIs for types and members. +- XML docs use XML extension methods rather than raw `///` fragments. +- `CodeWriter` is created inside each output callback and never persists in pipeline state; passing it + to helper methods within that callback is expected. +- Header and generated attributes are deterministic and consistent. +- Existing diagnostics, generated member names, and public behavior are preserved. +- Roslyn objects are removed from pipeline models; `EquatableArray` is used for collections. +- Per-target output is preferred over collected global output unless global knowledge is required. +- `CompilationProvider` is not casually combined into output. +- Deterministic hint names and source text are used. +- Incremental caching behavior is tested, not just generated text. + +## See also + +- `agents/source-generator-framework-writer.agent.md` — specialist agent for `Purview.SourceGeneratorFramework` emitter authoring. +- `prompts/refactor-source-generator-to-codewriter.prompt.md` — prompt template for legacy-emitter refactor tasks. diff --git a/.claude/skills/purview-sourcegenerator-codewriter/references/legacy-emitter-migration.md b/.claude/skills/purview-sourcegenerator-codewriter/references/legacy-emitter-migration.md new file mode 100644 index 00000000..54efd09f --- /dev/null +++ b/.claude/skills/purview-sourcegenerator-codewriter/references/legacy-emitter-migration.md @@ -0,0 +1,58 @@ +# Migrating a legacy emitter to CodeWriter + +A playbook for moving a source generator's emission from manual `string` / `StringBuilder` +construction to `CodeWriter` plus the `XmlCommentWriter` documentation extensions, with behaviour +parity. + +## Before you start, collect + +- The emitter file(s) being changed. +- The generator type name, and the version string it stamps into generated attributes or headers. +- Whether the output must stay **byte-identical**. If it must, every whitespace decision below is a + constraint rather than a preference, and the diff of the generated snapshots is the acceptance + test. + +## Requirements + +1. Use the structured declaration APIs rather than hand-written declaration text: + `Class` / `Struct` / `RecordClass` / `Interface` / `Enum`, and `Method`, `Property`, `Field`, + `Constructor`. +2. Use the XML helper extensions instead of composing `///` lines: `XmlSummary`, `XmlParam`, + `XmlReturn`, `XmlRemarks`, `XmlCode` / `XmlCodeBlock`. +3. Use `TypeReference` once the type text gets complex — nullability, generics, arrays. +4. Keep the writer **output-scoped**: `generationContext.CreateCodeWriter()` *inside* the output + callback. Never create it earlier in the pipeline, and never store it in incremental provider + state or in a custom context. +5. Preserve behaviour, diagnostics and generated names. +6. Keep the change minimal. Do not reformat logic the migration does not touch. + +## Strategy + +Work phase by phase, because each phase has a different mechanical replacement: + +| Emitter phase | Replace with | +| --- | --- | +| header | the header helper, not a literal banner string | +| namespace | the namespace scope API | +| type declarations | declaration option records, not signature strings | +| member declarations | `Method` / `Property` / `Field` / `Constructor` | +| indentation and braces | scoped APIs — never manual `{`/`}` and `\t` | +| `///` comment composition | `XmlSummary`, `XmlParam`, `XmlReturn`, `XmlRemarks`, `XmlCode` | + +Call out any intentional semantic delta explicitly; a migration that quietly changes emitted names or +diagnostics is the failure mode this playbook exists to avoid. + +## Verification + +- Run the impacted tests. +- Confirm the generated files still compile. +- Confirm there are **no scope leaks**: `OpenScopeCount == 0` when the writer is materialized. Enable + CodeWriter scope validation in the test run. +- Where byte-identical output was required, diff the generated snapshots. + +## Report + +1. Files changed. +2. Why each change was necessary. +3. Risks and behaviour differences, if any. +4. The verification that actually ran. diff --git a/.claude/skills/purview-sourcegenerator-diagnostics/SKILL.md b/.claude/skills/purview-sourcegenerator-diagnostics/SKILL.md new file mode 100644 index 00000000..21d9522c --- /dev/null +++ b/.claude/skills/purview-sourcegenerator-diagnostics/SKILL.md @@ -0,0 +1,142 @@ +--- +name: purview-sourcegenerator-diagnostics +description: >- + Use when a Purview.SourceGeneratorFramework build reports a PSGFR, PSGF, PRSGD or TLB diagnostic, + when choosing which code fix applies, or when a source generator, diagnostic analyzer or code fix + provider is silently not running at all. +metadata: + product: Purview.SourceGeneratorFramework + repository: purview-dev/sourcegenerator-framework +--- + +# Purview.SourceGeneratorFramework diagnostics + +`Purview.SourceGeneratorFramework` ships `Purview.SourceGeneratorFramework.Analyzers` and +`Purview.SourceGeneratorFramework.CodeFixers` as analyzer assets inside the package, under +`analyzers/dotnet/cs/`. They are enabled automatically in any project that references the framework — +there is no separate package to add. + +Two compiler-analyzer families, plus a set of MSBuild-time diagnostics: + +- **Incremental generator best practice** — `PSGFR11`–`PSGFR33`: pipeline design, `CodeWriter` usage, + Roslyn component discovery, extension-class conventions. +- **C# 14 extension-member conventions** — `PSGFR34`–`PSGFR38`, with + `ReorganizeExtensionClassCodeFixProvider` and `ConvertToExtensionBlockCodeFixProvider`. +- **Merge and packaging** — `PSGFR39`–`PSGFR43`, where `PSGFR43` is the merge tool's blocked + public-surface code. + +## Start here when nothing runs + +A compiler host loads a generator, analyzer or code fix provider only when **three** conditions hold. +Missing any one means the component is **silently ignored** — no error, no output, a green build: + +1. **The type is public** (`PSGFR27`). +2. **The type is decorated** — `[Generator]` (`PSGFR26`), `[DiagnosticAnalyzer]` (`PSGFR25`), or + `[ExportCodeFixProvider]` (`PSGFR24`). +3. **The assembly is loaded as an analyzer** — packed under `analyzers/dotnet/cs/` in a package, or + referenced with `OutputItemType="Analyzer"` on a `ProjectReference`. + +A code fix provider additionally appears only when a diagnostic ID in its `FixableDiagnosticIds` is +actually produced by an analyzer loaded alongside it (`PSGFR28`). Visual Studio MEF-composes fix +providers when the analyzer set loads, so after adding or updating a fixer assembly you must restart +Visual Studio or reload the project before the fixes show up. + +## Build-time validation diagnostics + +These are MSBuild diagnostics, not compiler analyzers, so they are **not** tracked in +`AnalyzerReleases.*.md`: + +| Code | Raised by | Summary | +| --- | --- | --- | +| `PSGF0001` | `Purview.BuildSdk` | A Roslyn component did not produce (or declare) a source-generator analyzer file. | +| `PSGF0003` | `Purview.SourceGeneratorFramework` | A `PurviewGeneratorVisibleProperty` is not compiler-visible in the declaring project or its `Sdk/build`/`Sdk/buildTransitive` assets, so consumers cannot read `build_property.`. | +| `PRSGD0005` | `Purview.BuildSdk` | A file in the returned analyzer closure references an assembly that is neither in the closure nor a compiler-host assembly. | +| `PSGFR41` | merge tool | A component's public surface exposes framework types the merge internalizes. Reported by the analyzer at design time, and by the merge pass as `message` (default), `warning` or `error`. | +| `PSGFR43` | merge tool | The merged analyzer still exposes a public framework type, so it is not self-contained. Always an error; the merge fails with exit code 5. | + +Opt out with `PurviewSourceGeneratorFrameworkAnalyzerValidation=false` (`PRSGD0005`) or +`PurviewSourceGeneratorFrameworkGeneratorPropertyValidation=false` (`PSGF0003`). + +## Incremental pipeline rules + +| Rule | Summary | +| --- | --- | +| `PSGFR11` | Prefer `SyntaxProvider.ForAttributeWithMetadataName` over `CreateSyntaxProvider` for attribute-based detection. | +| `PSGFR12` | Use `IIncrementalGenerator` / `RegisterSourceOutput` instead of `ISourceGenerator`. | +| `PSGFR14` | Avoid `RegisterImplementationSourceOutput` unless implementation-only output is required. | +| `PSGFR15` | Pipeline model collection members should use sequence equality (`EquatableArray`). | +| `PSGFR30` | Prefer `static` lambdas in pipeline methods, so the compiler never allocates a closure on the per-item hot path. | +| `PSGFR31` | Prefer `GeneratorAttributeSyntaxContext.TargetSymbol` over `SemanticModel.GetDeclaredSymbol(ctx.TargetNode)`. | +| `PSGFR33` | Pipeline models must not retain Roslyn objects (`ISymbol`, `SyntaxNode`, `Location`, …); extract the information into value types. | + +## CodeWriter rules + +| Rule | Summary | +| --- | --- | +| `PSGFR16` | Prefer the nullable-context `Nullable()`/`MakeNullable()` overload, so annotations honour the target compilation. | +| `PSGFR17` | Consume scope-returning methods (`…Scope`, `IndentedScope`) with `using`. | +| `PSGFR18` | Prefer structured declaration APIs (`Class`, `Method`, `Property`, `Field`) over raw declaration text. | +| `PSGFR19` | Prefer structured statement APIs (`Return`, `MethodCall`, `Throw`, `Assignment`, `Using`, `Comment`) over raw statement text. | +| `PSGFR20` | Prefer the minimal `CodeWriter` overloads over hand-constructing `*DeclarationOptions` values. | +| `PSGFR21` | Prefer `HashDefines`/`HashDefinesScope` for `#if`/`#endif`. | +| `PSGFR22` | Prefer `PragmaDisable`/`OpenPragmasScope` for `#pragma warning`. | +| `PSGFR23` | Prefer structured `IfBlock`/`ElseIf`/`Else` over raw `if` block text. | +| `PSGFR29` | Do not embed a `CodeWriter` in a string; use `XmlCommentWriter.XmlInlineCode`. | +| `PSGFR32` | Avoid `NormalizeWhitespace` when generating source; use an indented text writer such as `CodeWriter`. | + +## Component, extension and merge rules + +| Rule | Summary | +| --- | --- | +| `PSGFR24` | `CodeFixProvider` is not marked `[ExportCodeFixProvider]`; Visual Studio will never discover it. | +| `PSGFR25` | `DiagnosticAnalyzer` is not marked `[DiagnosticAnalyzer]`; it will never run. | +| `PSGFR26` | A generator type is not marked `[Generator]`; it will never run. | +| `PSGFR27` | A Roslyn component type is not public; the compiler host cannot instantiate it. | +| `PSGFR28` | `FixableDiagnosticIds` names a diagnostic no analyzer in the compilation produces; the fix will never be shown. | +| `PSGFR34` | Prefer C# 14 `extension(Receiver)` blocks over classic static `this`-parameter extension methods. | +| `PSGFR35` | Extension class name must match the extended type (`{Receiver}Extensions`). | +| `PSGFR36` | Extension classes belong in the extended type's namespace, under an `Extensions` folder. | +| `PSGFR37` | One extension class per receiver type; split a class that extends several. | +| `PSGFR38` | Extension classes should carry `[EditorBrowsable(EditorBrowsableState.Never)]`. | +| `PSGFR39` | A non-packable Roslyn component opted out of the default self-contained analyzer output (`PurviewMergeSourceGeneratorFrameworkForAnalyzerFiles=false`) while embedding the framework; otherwise the package embeds the loose framework DLL under `analyzers/`. | +| `PSGFR40` | In a Roslyn component (`IsRoslynComponent=true`), reference SGF types as inline code (`Type`) rather than a `cref`: copied documentation must not depend on cref resolution. | +| `PSGFR41` | A public member (or generic constraint) whose signature references an SGF type in a component whose framework implementation is merged. The merge internalizes every SGF type, so the signature ends up referring to an internal type. Make the member, or its declaring type, non-public. | +| `PSGFR42` | A disposable Testing-harness result (`DriverRunResult`) is produced and never disposed, leaking the collectible `AssemblyLoadContext` and `MetadataLoadContext` of a compiled run. `warning` when the run syntactically compiles to an assembly (a `Compile` options member, or `CompileToAssembly = true`), otherwise `info`. Awaiting an assertion, or calling a helper handed the result — an extension on it, or a method taking it as a parameter — is not a production: both hand the same instance back, so only a task-like await or a genuine producer is reported. | + +## Type-library and attribute-model diagnostics + +The bundled generators carry their own families: `TypeLibraryValidationAnalyzer` +(`TLB0001`–`TLB0019`, plus `TLB0021`) and the attribute-data-model validation analyzers. They are +documented on their own wiki pages, `Type-Library.md` and `Attribute-Data-Models.md`. + +## Code fixes + +Most rules above have a fix in `Purview.SourceGeneratorFramework.CodeFixers`: + +| Fix provider | Rule | +| --- | --- | +| `AddGeneratorAttributeCodeFixProvider` | `PSGFR26` | +| `AddDiagnosticAnalyzerAttributeCodeFixProvider` | `PSGFR25` | +| `AddExportCodeFixProviderAttributeCodeFixProvider` | `PSGFR24` | +| `MakeRoslynComponentPublicCodeFixProvider` | `PSGFR27` | +| `RemoveOrphanedFixableDiagnosticIdCodeFixProvider` | `PSGFR28` | +| `PreferTargetSymbolCodeFixProvider` | `PSGFR31` | +| `PreferStaticLambdaCodeFixProvider` | `PSGFR30` | +| `PreferNullableContextOverloadCodeFixProvider` (project-wide Fix All) | `PSGFR16` | +| `PipelineModelReferenceEqualityCollectionCodeFixProvider` | `PSGFR15` | +| `PreferStructuredCodeWriterIfBlockCodeFixProvider` | `PSGFR23` | +| `CodeWriterToStringCodeFixProvider` | `PSGFR29` | +| `PreferInlineCodeForFrameworkCrefCodeFixProvider` | `PSGFR40` | +| `MakeComponentSurfaceNonPublicCodeFixProvider` | `PSGFR41` | +| `DisposeTestResultCodeFixProvider` | `PSGFR42` | +| `ReorganizeExtensionClassCodeFixProvider` (renames, splits, moves, updates referencing files) | `PSGFR35`, `PSGFR36`, `PSGFR37` | +| `ConvertToExtensionBlockCodeFixProvider` | `PSGFR34` | +| `AddExtensionClassMetadataCodeFixProvider` | `PSGFR38` | +| `MakeTypeLibrarySpecNonPublicCodeFixProvider` | `TLB0021` | +| `AttributeDataModelSymbolPropertyCodeFixProvider` | attribute-data-model symbol properties | +| `TypeLibraryMemberAccessibilityCodeFixProvider`, `TypeLibraryMarkerDefaultInitializerCodeFixProvider`, `MakeTypeLibrarySpecPartialCodeFixProvider`, `RenameTypeLibrarySpecCodeFixProvider`, `TypeLibraryMemberTypeCodeFixProvider` | type-library rules | + +## Related skills + +`purview-sourcegenerator-codewriter` for the emission patterns the `CodeWriter` rules push you +towards, and `purview-sourcegenerator-testing` for proving a pipeline actually caches. diff --git a/.claude/skills/purview-sourcegenerator-packaging/SKILL.md b/.claude/skills/purview-sourcegenerator-packaging/SKILL.md new file mode 100644 index 00000000..92350db8 --- /dev/null +++ b/.claude/skills/purview-sourcegenerator-packaging/SKILL.md @@ -0,0 +1,245 @@ +--- +name: purview-sourcegenerator-packaging +description: >- + Use when packaging or referencing a source generator built on Purview.SourceGeneratorFramework - + the self-contained merged analyzer, GetSourceGeneratorAnalyzerFiles, embedding a generator in + another package, PurviewGeneratorVisibleProperty, analyzer-closure validation, Roslyn version + compatibility, and errors such as CS0433, CS8784 or MSB3073 from a loaded analyzer. +metadata: + product: Purview.SourceGeneratorFramework + repository: purview-dev/sourcegenerator-framework +--- + +# Packaging a source generator + +The rule everything else follows from: **a shipped Roslyn component carries its own copy of the +framework and references no loose `Purview.SourceGeneratorFramework.dll`.** Two generators built +against different framework versions must be able to load into one compiler host. A shared DLL under +`analyzers/` cannot give you that — whichever version loads first wins, and the other fails with +`MissingMethodException` or `CS0433`. + +The framework delivers this by IL-merging and internalizing its implementation into each component's +**intermediate** output, leaving the component's `bin` unmerged. + +## Referencing the framework from a component + +```xml + + true + + + + + +``` + +And from a consuming project, as an analyzer: + +```xml + +``` + +`Purview.BuildSdk` invokes `GetSourceGeneratorAnalyzerFiles` automatically — naming +`Targets="GetSourceGeneratorAnalyzerFiles"` explicitly still works but is not required. + +## The three consumption paths + +| Path | Trigger | What you get | +| --- | --- | --- | +| `GetSourceGeneratorAnalyzerFiles` (default) | a consuming project references the component as an analyzer | the **merged** component, from the content-addressed `purview-merged//`. `bin` stays unmerged, so an in-process test harness keeps shared framework type identity and `InternalsVisibleTo` access without `CS0433`. | +| `GetSourceGeneratorAnalyzerFiles` with `PurviewMergeSourceGeneratorFrameworkForAnalyzerFiles=false` | opt-out | unmerged component **plus** the loose framework DLL from the package `lib/`. | +| `GetPurviewMergedAnalyzerFile` | the framework's own bundled-component pack, or a third-party package embedding the generator | the merged component; `bin` is never overwritten. | +| `GetPurviewMergedAnalyzerFileForPack` (pack-time, via `TargetsForTfmSpecificContentInPackage`) | packing a standalone packable generator | the merged DLL and PDB contributed straight to `analyzers/dotnet/cs`. `bin` is never mutated, so its shape does not depend on whether `build` or `pack` ran last. | + +Two properties exist and both should normally be left alone: + +- `PurviewEmbedSourceGeneratorFramework=false` — only for a project that *is* the framework + compile-time library. A published generator package must never disable embedding. +- `PurviewMergeSourceGeneratorFrameworkForAnalyzerFiles=false` — only when the analyzer-files + consumer must keep the unmerged + loose-DLL shape (a generator shipped into one compiler process + alongside an incompatible framework version). + +`PSGFR39` errors when a **non-packable** component opts out while embedding the framework, because +that shape, packed through the GASF path, forces the loose DLL back under `analyzers/`. + +## A component that references another component + +A code-fix or analyzer component can reference the generator component normally (`ProjectReference`, +`ReferenceOutputAssembly` **not** `false`) when it needs the generator's internal diagnostic +identity. Both are `IsRoslynComponent`; only the generator references the framework. + +- The referenced component is returned as **its own merged assembly** and is never IL-merged into the + dependent one — that would duplicate its types, including `InternalsVisibleTo`-visible internals, + inside a second analyzer in the same host. +- The framework assembly is declared as copy-to-output content beside the generator's `bin`, and + content with `CopyToOutputDirectory` flows transitively through `ProjectReference`. That is what + lets Visual Studio load the dependent code-fix provider from its own `bin` without a + `FileNotFoundException` for the framework assembly. +- Visual Studio's project system resolves an `OutputItemType=Analyzer` project reference to the + referenced project's **unmerged** `bin` assembly and adds it to the compiler's analyzers — the + command-line build does not. `Purview.BuildSdk` removes that item before adding the resolved + closure, so Roslyn only ever receives the merged artifact. Without that removal the unmerged copy + drags `Purview.SourceGeneratorFramework` into the compiler host + (`CS8784 FileNotFoundException: Could not load file or assembly 'Purview.SourceGeneratorFramework'`) + and every generator registers twice. + +## Analyzer-closure validation + +`Purview.BuildSdk` validates the whole closure `GetSourceGeneratorAnalyzerFiles` returns: every +file's PE `AssemblyRef` must resolve to another file in the returned set, or to a compiler-host +assembly (`Microsoft.CodeAnalysis*`, `System.Composition.*`, `System.*`, `netstandard`, …). A missing +component artifact fails the build with `PRSGD0005`. + +Extend the permitted set with `` or the +`PurviewAnalyzerClosurePermittedReferences` property. Opt out with +`PurviewSourceGeneratorFrameworkAnalyzerValidation=false`. + +## Generator-read MSBuild properties + +A generator reading `build_property.` is only correct if `` is a +`CompilerVisibleProperty` **wherever the generator runs** — including in a consumer's project. +Declare what the component reads: + +```xml + + + +``` + +`PSGF0003` fails the build when a declared property is neither a `CompilerVisibleProperty` in the +project nor declared by the project's own `Sdk/build` or `Sdk/buildTransitive` assets — which is what +consumers actually receive. Opt out with +`PurviewSourceGeneratorFrameworkGeneratorPropertyValidation=false`. + +NuGet imports `buildTransitive` assets for **PackageReference** consumers only. Inside the package +repository every project uses `ProjectReference`, so `Purview.BuildSdk`'s +`ImportProjectReferencedBuildTransitiveAssets` registers the referenced project's +`Sdk/buildTransitive/*.props|*.targets` `CompilerVisibleProperty` items for in-repo consumers. Opt +out with `PurviewImportProjectReferenceBuildTransitive=false`. + +## Embedding a generator in another package + +Pack the **merged** assembly, so the outer package ships no loose framework DLL: + +```xml + + false + $(TargetsForTfmSpecificContentInPackage);PackMyGenerator + + + + + + + + + analyzers/dotnet/cs/ + + + +``` + +If the generator is also embedded at compile time for the outer package's consumers, the outer +package must make the framework's compiler-visible properties visible to them — build assets from +`Purview.SourceGeneratorFramework` are **not** copied into the outer package. Ship a `.props` that +declares the property and its `CompilerVisibleProperty` entry, packed under the outer package's own +ID so NuGet imports it: + +```xml + +``` + +## `IsExternalInit` + +The framework assembly defines `System.Runtime.CompilerServices.IsExternalInit` **publicly**, so the +bundled generators can emit `init`-based attribute types into any consumer compilation and the merge +has a single marker definition to internalize. + +**Do not declare your own.** A generator-local marker gives calls to the framework's `init` setters a +different required-custom-modifier identity from the setter definitions. The merge tool normalizes +those modifiers in a temporary copy for compatibility with legacy tooling, but removing the redundant +marker is the preferred configuration. + +## Roslyn version compatibility + +> The version of `Microsoft.CodeAnalysis.*` you compile the component against sets a **minimum +> compiler-host API requirement**. The consumer's `` has nothing to do with it — +> analyzer code runs inside the compiler/IDE host. + +| Roslyn package | Minimum Visual Studio | Language / .NET generation | +| ---: | --- | --- | +| 4.8 | VS 2022 17.8 | C# 12 / .NET 8 | +| 4.12 | VS 2022 17.12 | C# 13 / .NET 9 | +| 5.0 | VS 2026 18.0 | C# 14 / .NET 10 | + +**This framework is built against Roslyn 5.0**, so a host loading it must be Roslyn 5.0 or later +(.NET 10 SDK / Visual Studio 2026 18.0). The testing packages multi-target `net8.0`–`net10.0`, and +Roslyn 5.x ships `net8.0`/`net9.0` assets, so those test targets still load the runner. + +## A generator project to start from + +```xml + + + netstandard2.0 + latest + enable + true + false + true + true + + + + + + + + + + + + +``` + +`Purview.BuildSdk` already defaults most of this for a project it classifies as a Roslyn component, +so in an SDK repository the project file is usually far shorter. The exact Roslyn baseline is a +product-support decision. + +## Release gates + +Acceptance criteria for self-contained packaging — check metadata, never "the sample compiled": + +1. **No framework reference, no public framework types.** Every `analyzers/dotnet/cs/*.dll` has no + assembly reference to `Purview.SourceGeneratorFramework` and exposes no public type in a + framework-owned namespace (including the generated `Generators` attribute set and the + framework-emitted `Microsoft.CodeAnalysis.EmbeddedAttribute`). The one exception is the + component's own Roslyn entry points, which must stay public — Roslyn only instantiates public + components (`PSGFR27`). +2. **No loose framework DLL in any package**, and no `*.pdb` in the `.nupkg` — symbols ship only + through the `.snupkg`. +3. **Merged entry points survive**: each merged DLL still exposes its `IIncrementalGenerator`, + `DiagnosticAnalyzer` or `CodeFixProvider`. +4. **Installed-package consumer test**: a generator project referencing the framework by + `PackageReference` packs one self-contained DLL under `analyzers/dotnet/cs`, and a consumer that + installs it builds with the generator producing output. +5. **Two-version coexistence test**: build Generator A against the current framework and Generator B + against an intentionally binary-incompatible version, install both into one consumer, and build + with both package-reference orders. Both must run against their own embedded copy. + +## Going deeper + +The merge pass, the content-addressed artifact, framework type internalization and the properties +that tune it are in [references/merge-internals.md](references/merge-internals.md) — read it when a +merge fails, when a type leaks, or when you hit `MSB3073` / `CS0433` / `CS8784` from a loaded +analyzer. diff --git a/.claude/skills/purview-sourcegenerator-packaging/references/merge-internals.md b/.claude/skills/purview-sourcegenerator-packaging/references/merge-internals.md new file mode 100644 index 00000000..5d8b6c9e --- /dev/null +++ b/.claude/skills/purview-sourcegenerator-packaging/references/merge-internals.md @@ -0,0 +1,139 @@ +# The merge pass and the self-contained analyzer + +## Where the merged artifact lives + +`_PurviewMergeSourceGeneratorFramework` only ever writes to the component's **intermediate** output. +`GetSourceGeneratorAnalyzerFiles` returns that result by substituting the merged path into +`TargetPathWithTargetPlatformMoniker` immediately before its body runs, leaving `GetTargetPath` — +which resolves assembly references — pointing at the unmerged `bin`. That split is what keeps the +in-repo test harness working while shipped assemblies stay self-contained. + +The artifact is **content-addressed**: + +```text +$(IntermediateOutputPath)purview-merged//$(TargetFileName) +``` + +`` is a SHA-256 over the component, the framework assembly and the merge tool (the tool +computes it in its `--tag` mode). The tag is in the **directory**, never the file name, because +ILRepack derives the merged assembly's simple name from the output file name and an analyzer must +keep `.dll`. + +Two properties follow, and both matter: + +- A rebuild with identical inputs reuses the existing file and **skips the merge**, so + `_PurviewMergeSourceGeneratorFramework` is idempotent across the per-consumer — and potentially + parallel — invocations of `GetSourceGeneratorAnalyzerFiles`. +- Changed inputs select a **new directory**, so the merge never overwrites an assembly a compiler + host (csc, `VBCSCompiler`, Visual Studio) already has loaded. Overwriting such a file fails on + Windows with a sharing violation, which surfaced as `MSB3073` (merge tool exit code + `-532462766`) and left consumers loading a stale or partially written analyzer — the root cause of + `CS8784 FileNotFoundException: Could not load file or assembly 'Purview.SourceGeneratorFramework'`. + +The tool merges into a per-process `.staging-` directory and publishes it with a +non-overwriting directory rename. A concurrent invocation that loses the race simply observes the +published artifact rather than failing. + +Packaging needs the stable `.dll` name, so the pack paths +(`GetPurviewMergedAnalyzerFile`, `GetPurviewMergedAnalyzerFileForPack`) copy the content-addressed +artifact into `$(IntermediateOutputPath)purview-pack/` and pack that plainly named staging copy. + +## Framework type internalization + +ILRepack's `Internalize` is best-effort, and two gaps matter: + +- a framework type that reaches the merged component's public API surface stays public; and +- the types the framework's own generators emit **into** the component — the + `Purview.SourceGeneratorFramework.Generators` attribute set, generated type libraries, marker + attributes — are not part of the merged framework assembly at all, so ILRepack never sees them. + +Either gap leaks framework types out of what must be a self-contained analyzer, and any project +loading that analyzer alongside the real framework assembly fails with `CS0433` ambiguity for every +leaked type. + +So the merge tool runs a deterministic internalization pass (`FrameworkTypeInternalizer`) after +ILRepack finishes: + +- Every type in a framework-owned namespace (`Purview.SourceGeneratorFramework` and its children, + including the generated `Generators` attribute set) becomes non-public. Ownership is evaluated + through the **declaring chain**, because Mono.Cecil reports an empty namespace for a nested type: + the framework's nested containers — generated type-library namespace classes, nested operator/enum + groups, `CodeWriter` scopes — are only reachable through their declaring type. +- Types the framework's generators emitted into the component, recognized by the tool name on their + `System.CodeDom.Compiler.GeneratedCodeAttribute` (`TypeLibraryGenerator`, + `AttributeDataModelGenerator`), become non-public too, so a generated type library can never leak a + `TypeIdentity`/`TypeReference` member as public API. +- `Microsoft.CodeAnalysis.EmbeddedAttribute`, the framework-emitted marker, becomes non-public. +- **Roslyn component entry points are never internalized.** A generator, analyzer, code fix provider + or refactoring provider reachable from the framework namespace stays public, because Roslyn only + instantiates public components (`PSGFR27`). This is what keeps the framework's own bundled + analyzers working after the pass. +- The pass reports the result. Leftover public framework types fail the merge with **exit code 5** + (`PSGFR43`). Public component members whose signature exposes a framework type are logged + (`PSGFR41`) so the author can make them, or their declaring type, non-public. Visibility is + followed through the declaring chain here too: a public nested type inside an internal type — for + example the compiler-synthesised `$`/`$` extension containers emitted for an extension class + — is not reachable from outside the component, so it is not part of the public surface and is not + reported. + +Ownership is seeded with the framework assembly's own type identities, so a framework type living +*outside* the framework namespace (`Microsoft.CodeAnalysis.*Extensions`, `System.StringExtensions`) +is internalized as well. The artifact's assembly-level `InternalsVisibleTo` / +`IgnoresAccessChecksTo` grants are removed, because a shipped analyzer is not the component's own +assembly. + +## Tuning the pass + +| Property | Default | Effect | +| --- | --- | --- | +| `PurviewMergeOwnedNamespaces` | empty | Extra namespace prefixes (semicolon-separated) treated as framework-owned. | +| `PurviewMergeOwnedTypeFullNames` | empty | Extra type full names (semicolon-separated) treated as framework-owned. | +| `PurviewMergePublicSurfaceSeverity` | `message` | How a finding is reported: `message` (plain log text), `warning`/`error` (MSBuild diagnostics with code `PSGFR41`), or `none`. | +| `PurviewMergePublicSurfaceValidation` | `true` | `false` sets the severity to `none`. | +| `PurviewMergePublicSurfaceOrigin` | the merged component assembly | The origin reported with an MSBuild finding; point it at a source or project path for IDE navigation. | + +All five participate in the content tag, so changing one re-runs the merge — and re-emits its +findings — rather than reusing a cached artifact. The compiler analyzer with the same id (`PSGFR41`) +reports the same condition while you edit, so the surface is usually fixed before the merge runs. + +## Generated accessibility: bin versus merged artifact + +The component's own generated types — the type library, the attribute data models — keep their +generated accessibility in the component's **bin output**. `TLB0015` requires a hand-written partial +to be `public static partial` so it can merge with the generated library, and in-repo consumers such +as code fixers and sibling assemblies compile against it. + +Only the **merged analyzer artifact** internalizes them. Self-containment is therefore enforced at +the merge boundary without rewriting the accessibility an in-repo consumer compiles against, and that +split is safe precisely because a merged artifact is never referenced as a compile-time dependency. + +> A merged component is an analyzer artifact. Never reference it as a compile-time dependency. Tests +> that need to run a *packaged* generator load it out of band. + +## How the framework package itself is assembled + +`Purview.SourceGeneratorFramework` is dual-role: the framework assembly ships in `lib/` so generator +projects compile against it, and `analyzers/` carries self-contained generator, analyzer and +code-fixer assemblies. The bundled projects are: + +- `SourceGeneratorFramework.Generators` — `AttributeDataModelGenerator`, `TypeLibraryGenerator`; +- `SourceGeneratorFramework.Analyzers` — the `PSGFR*` and `TLB*` analyzers; +- `SourceGeneratorFramework.CodeFixers` — the code fix providers. + +Each has the framework implementation merged and internalized into it. The package deliberately does +**not** put `Purview.SourceGeneratorFramework.dll` under `analyzers/dotnet/cs`, so generators built +against different framework versions never ask Roslyn to load competing versions of a same-named +dependency. + +The shared models and helpers that once shipped as a separate +`Purview.SourceGeneratorFramework.Shared.dll` are compiled directly into the framework assembly +(`SourceGeneratorShared.Link.targets` links the sources). Consumers get one +`Purview.SourceGeneratorFramework.dll`, which removes the version-skew hazard a separately bundled +Shared assembly caused — generator packages loading a different Shared version in-process failed with +binary-incompatibility errors, such as removed `PurviewTypeLibrary` fields. + +Those projects are `IsRoslynComponent = true` and are **not** packable on their own. The +`SourceGeneratorFramework` project builds them via `GetPurviewMergedAnalyzerFile` and packs them +under `analyzers/dotnet/cs/` in `BuildAndPackBundledAnalyzerAssemblies`. They were previously +consumed as analyzer project references, but they now reference the framework assembly for the shared +types, which would form a project-reference cycle. diff --git a/.claude/skills/purview-sourcegenerator-pipeline/SKILL.md b/.claude/skills/purview-sourcegenerator-pipeline/SKILL.md new file mode 100644 index 00000000..373942fd --- /dev/null +++ b/.claude/skills/purview-sourcegenerator-pipeline/SKILL.md @@ -0,0 +1,231 @@ +--- +name: purview-sourcegenerator-pipeline +description: >- + Use when composing an incremental pipeline with Purview.SourceGeneratorFramework - + IncrementalPipeline helpers, GenerationContext and custom contexts, CreateCodeWriter lifetime, + GeneratorResult and blocking versus non-blocking diagnostics, disabling a generator from MSBuild, + scope validation, test logging, and stage tracking names. +metadata: + product: Purview.SourceGeneratorFramework + repository: purview-dev/sourcegenerator-framework +--- + +# Incremental pipeline composition + +`IncrementalPipeline` composes `IncrementalValueProvider` and `IncrementalValuesProvider`: +attribute-based discovery, generation-context creation, disable-property checks, and thin +source-output registration. + +Everything here follows from one rule: **pipeline values must be immutable and value-equatable.** +Roslyn caches the complete value a provider publishes, and offers no way to exclude one property of +it from caching. + +## `GenerationContext` + +A base execution-services context carrying the Roslyn `Compilation`, immutable `GenerationSettings`, +an optional `ISourceGenLogger`, and a factory for independently owned `CodeWriter` instances. + +```csharp +var contextProvider = IncrementalPipeline.DefaultGenerationContextValueProvider(context); +``` + +### Custom contexts + +A custom context does not need to accept or read build properties itself: + +```csharp +public sealed class MyGenerationContext : GenerationContext +{ + public MyGenerationContext(Compilation compilation, GenerationSettings settings, ISourceGenLogger? logger) + : base(compilation, settings, logger) + { + } +} + +var contextProvider = IncrementalPipeline.GenerationContextValueProvider( + context, + nameof(MyGenerator), + "1.0.0", + factory: static (compilation, settings, logger, cancellationToken) => + { + cancellationToken.ThrowIfCancellationRequested(); + return new MyGenerationContext(compilation, settings, logger); + }, + disablePropertyName: "MyGenerator_Disable" +); +``` + +The provider resolves scope validation, generator disabling and test logging from analyzer-config +properties *before* invoking the factory. The logger is created internally only when logging is +enabled and a sink is registered for that run. + +## `CodeWriter` lifetime — the rule that bites + +Treat `GenerationContext` as **cached incremental state** and each `CodeWriter` as **mutable, +output-scoped execution state**. Create the writer inside the registered source-output callback, +after the incremental cache boundary: + +```csharp +IncrementalPipeline.RegisterSourceOutput( + context, + targets, + contextProvider, + static (spc, target, generationContext) => + { + var writer = generationContext.CreateCodeWriter(); + EmitTarget(generationContext, writer, target); + spc.AddSource($"{target.Name}.g.cs", writer.ToString()); + } +); +``` + +Creating it in the callback and passing it to emitter helpers called from that same callback is the +intended pattern. The only forbidden thing is **persisting the writer in pipeline state**. + +Why, concretely: + +- Roslyn caches the whole published value; you cannot exempt a field. +- `CodeWriter` is mutable, so a cached one retains previously written source when the context is + reused for another output or run. +- Source-output callbacks may process independent targets **concurrently**; a shared writer mixes + their output and races. +- A fresh writer gives each generated source independent scope tracking and deterministic ownership. + +`CreateCodeWriter()` returns a new, independently owned instance every call. + +**Never add a `CodeWriter` property or field to a class derived from `GenerationContext`.** A custom +context is still produced by an incremental provider and cached as one complete value. Store only +compilation-derived services and immutable configuration there. + +When an emitter needs both services and writing, pass the context and the writer separately, or +compose a short-lived wrapper created inside the callback — which must never be returned from a +provider: + +```csharp +public sealed class GenerationOutputContext : ISourceGenLogger + where TContext : GenerationContext +{ + public GenerationOutputContext(TContext generation) + { + Generation = generation; + Writer = generation.CreateCodeWriter(); + } + + public TContext Generation { get; } + + public CodeWriter Writer { get; } + + public void Log(SourceGenLogLevel level, int indentation, string message, params object[] args) => + Generation.Log(level, indentation, message, args); +} +``` + +## `GeneratorResult` and diagnostics that do not stop generation + +`RegisterSourceOutput` combines targets with the generation context, reports diagnostics, and runs +the callback only for successful results: + +```csharp +var targets = IncrementalPipeline.ForAttributeWithMetadataName( + context, + AttributeType, + static (ctx, ct) => + { + var symbol = ctx.TargetSymbol; + + return symbol is null + ? GeneratorResult.Empty + : GeneratorResult.Create(symbol.Name); + } +); +``` + +The callback runs only when `GeneratorResult.ShouldProcess` is `true` — the result carries a value +**and** none of its diagnostics are blocking. + +`ReportableDiagnostic.IsBlocking` is an explicit per-diagnostic decision, **independent of +severity**. An `Error`-severity diagnostic can still allow generation to continue, which is what you +want when the generated code is what helps the developer fix the problem — a generator emitting an +abstract base class can report an error per missing override while still emitting the base class, so +the user can see exactly what to implement: + +```csharp +static readonly DiagnosticDescriptor MissingOverride = new( + "MYGEN001", + "Missing override", + "Type '{0}' must override '{1}'", + "Usage", + DiagnosticSeverity.Error, + isEnabledByDefault: true +); + +// IsBlocking is false, so ShouldProcess stays true and the base class is still emitted. +var diagnostic = ReportableDiagnostic.Create(MissingOverride, isBlocking: false, symbol, symbol.Name, "Execute"); + +return GeneratorResult.Create(model, diagnostic); +``` + +`isBlocking: true` stops generation for that target while still reporting. +`HasBlockingDiagnostics` reports whether any carried diagnostic blocked; +`HasErrorDiagnostics` reports the severity-based view. + +## Disabling a generator at build time + +Pass the compiler-visible disable property to the context provider; its resolved value lands in +`GenerationSettings` automatically: + +```xml + + true + +``` + +```csharp +var contextProvider = IncrementalPipeline.DefaultGenerationContextValueProvider( + context, + nameof(MyGenerator), + "1.0.0", + disablePropertyName: "MyGenerator_Disable" +); + +// In the output stage: +if (generationContext.Settings.IsSourceGeneratorDisabled) + return; +``` + +`IsDisabledValueProvider` is still there for when expensive upstream transforms must be filtered +before being combined with the generation context. + +Declare the property with `PurviewGeneratorVisibleProperty` so it is compiler-visible wherever the +generator runs — `PSGF0003` otherwise fails the build. See the `purview-sourcegenerator-packaging` +skill. + +## Scope validation + +The default context provider reads +`PurviewSourceGeneratorFrameworkValidateCodeWriterScopes` and threads it into +`GenerationSettings.ValidateCodeWriterScopes`. When enabled, `ToString()` throws +`CodeWriterScopeValidationException` if `OpenScopeCount` is not zero. + +## Test logging + +Framework logging is off in ordinary compiler runs. The testing integration enables it by registering +an isolated sink and supplying a per-run session ID through analyzer config. Context providers create +the internal logger automatically — generators implement no logging interface and no logging-support +source is generated. + +The sink registry stores **callbacks only**; it never buffers entries. With logging disabled, a +missing session ID, or no matching sink, the provider supplies no logger and log calls are discarded. +Test sinks own whatever they capture and are removed when the run completes. + +## Tracking names + +The pipeline helpers assign a tracking name to every stage, so a cache test can assert which stages +were recomputed. The `purview-sourcegenerator-testing` skill covers the stage matrix and the four +scenarios a cache test should assert. + +## Related skills + +`purview-sourcegenerator-codewriter` for emission, `purview-sourcegenerator-diagnostics` for the +`PSGFR` rules that enforce most of the above, and `purview-sourcegenerator-testing` for proving the +pipeline caches. diff --git a/.claude/skills/purview-sourcegenerator-testing/SKILL.md b/.claude/skills/purview-sourcegenerator-testing/SKILL.md new file mode 100644 index 00000000..aaeff09e --- /dev/null +++ b/.claude/skills/purview-sourcegenerator-testing/SKILL.md @@ -0,0 +1,404 @@ +--- +name: purview-sourcegenerator-testing +description: >- + Use when writing or fixing tests for source generators, diagnostic analyzers, code fixes or + refactorings built on Purview.SourceGeneratorFramework - picking the right runner and base class, + configuring SourceGeneratorTestOptions, querying produced code with CodeQuery, and asserting + incremental pipeline caching stage by stage. +metadata: + product: Purview.SourceGeneratorFramework + repository: purview-dev/sourcegenerator-framework +--- + +# Testing source generators, analyzers, code fixes and refactorings + +Use this skill whenever a task involves authoring, fixing, or modernising tests for Roslyn components +(generators, diagnostic analyzers, code fix providers, refactoring providers) built with +`Purview.SourceGeneratorFramework`. It covers the framework-agnostic test runner layer and the +`CodeQuery` syntax-lookup API. For the TUnit base classes and assertion extensions, also load the +`purview-sourcegenerator-tunit-tests` skill. + +Modernising an existing suite onto `CodeQuery` and adding a stage-by-stage cache test? The playbook +is in [references/test-modernisation.md](references/test-modernisation.md). + +## Picking the right runner + +| Roslyn type | Runner | +|---|---| +| `IIncrementalGenerator` / `ISourceGenerator` | `SourceGeneratorTestRunner` | +| `DiagnosticAnalyzer` | `DiagnosticAnalyzerTestRunner` | +| `CodeFixProvider` | `CodeFixTestRunner` (single) | +| — | `CodeFixTestRunner.RunFixAllAsync` (project-wide) | +| `CodeRefactoringProvider` | `RefactoringTestRunner` | + +TUnit projects should prefer the matching base class instead (see `purview-sourcegenerator-tunit-tests`): +`TUnitSourceGeneratorTestBase`, `TUnitDiagnosticAnalyzerTestBase`, `TUnitCodeFixTestBase`, +`TUnitRefactoringTestBase`. + +## Result types + +- `DriverRunResult` (generator) — `DriverResult`, `AllSyntaxTrees`/`PrimarySyntaxTrees`, + `CompilationResult.Compilation`, `GetGeneratedTree`, `GetSource`, `GetTypeByMetadataName`, `LogEntries`. +- `AnalyzerTestResult` — `Diagnostics`, `Compilation`. +- `CodeFixTestResult` — `Diagnostics`, `CodeActions`, `FixedSource`, `Compilation`, `ChangedSolution`. +- `CodeFixFixAllResult` — `Diagnostics`, `CodeActions`, `FixedSources`, `ChangedSolution`. +- `RefactorTestResult` — `CodeActions`, `FixedSources`, `ChangedSolution`, `Compilation`. + +Use `DriverRunResultExtensions` (`AssertNoCompilationErrors`, `AssertNoGenerationExceptions`, +`AssertSingleGeneratedSource`, `AssertGeneratedSourceContains`, …) for quick checks, but prefer +`CodeQuery` for structural assertions. + +## Querying produced code with `CodeQuery` + +Every result exposes a `CodeQuery` via extensions in `CodeQueryResultExtensions`: + +```csharp +result.Generated() // DriverRunResult: generated trees (default, generated-first) +result.Output() // DriverRunResult: entire output compilation (user + generated) +analyzerResult.Code() // AnalyzerTestResult: input compilation +codeFixResult.Code() // CodeFixTestResult: input compilation +codeFixResult.FixedCode() // CodeFixTestResult: parsed fixed source (or post-fix solution) +fixAllResult.FixedCode() // CodeFixFixAllResult: post-fix documents +refactorResult.FixedCode() // RefactorTestResult: post-refactor documents +``` + +Every `Get` has an accompanying `Has` (bool) and `TryGet` (out): `GetMethod`/`HasMethod`/`TryGetMethod`, +`GetClass`, `GetStruct`, `GetInterface`, `GetEnum`, `GetDelegate`, `GetRecord`, `GetProperty`, +`GetField`, `GetConstructor`, `GetNamespace`, `GetTypeDeclaration`, plus generic `Get`/`Has` +and `GetSyntaxTree`/`HasSyntaxTree`. `Get` throws `SyntaxNotFoundException` when nothing matches. + +Type lookups accept an optional generic arity — `GetClass(name, arity)` / `HasClass(name, arity)` — and the +`TypeReference`/`TypeIdentity` overloads match arity automatically from the identity, so +`new TypeIdentity("ResourceDefinition", ns, arity: 1)` finds `ResourceDefinition` without matching the +non-generic `ResourceDefinition`. + +Every `Get` returns a `CodeQueryResult` — the matched syntax node (`Node`) plus a query scoped to it +(`Query`), with implicit conversions to both the node and the scoped query. Use `.Node` for direct syntax +access, or chain member queries (the originating query is carried by the result, so it is not passed again). + +Types can be matched against `TypeReference`/`TypeIdentity`, resolved through the compilation's semantic +model (nullable value types are significant, so `int?` never matches `int`): + +```csharp +result.Generated().HasMethod("DoWork", TypeReference.Create(), TypeReference.Create().Nullable(), complexType); +result.Generated().HasReturnType("Compute", TypeReference.Create()); +result.Generated().GetMethod("Format").HasParameters(TypeReference.Create(), objectReference); +``` + +When a test expects a nullable annotation, prefer the test-only `query.MakeNullable(type)` extension (on a +`CodeQuery`, accepting a `TypeReference` or `TypeIdentity`). It resolves the annotation against the query's +compilation and, unlike `TypeReference.Nullable()`/`TypeIdentity.MakeNullable()`, does not trigger the +`PSGFR16` context-overload suggestion (tests have no generation context to pass). + +Member chaining from a type declaration (`MemberQueryExtensions`): + +```csharp +var service = result.Generated().GetClass("ServiceCollectionExtensions"); // or GetClass(name, "Namespace") +service.HasProperty("Count", intType); +service.HasIndexer(stringType, intType); +service.HasMethod("Add", intType, complexType); +service.HasMethodReturnType("Add", stringType); +service.HasConstructor(stringType); +service.HasAttribute("SomeAttribute"); +``` + +Node-inspection checks on scoped results: + +```csharp +result.Generated().GetClass("Service").HasAccessibility(Accessibility.Public); // resolves C# defaults +result.Generated().GetClass("Service").GetProperty("Name").HasSetterAccessibility(Accessibility.Private); +result.Generated().GetClass("ResourceDefinition", 1).HasGenericTypeParameters("TResourceType"); +result.Generated().GetClass("ResourceDefinition", 1).HasBaseType(new TypeIdentity("ResourceDefinition", ns)); +result.Generated().GetClass("Service").HasNestedType("Builder"); // GetNestedType(...) to fetch +result.Generated().GetClass("Service").IsInNamespace("Example.Models"); // IsInGlobalNamespace() for no namespace +result.Generated().IsInNamespace(cls.Node, "Example.Models"); // or on the query directly +``` + +## Configuring options and a reusable starting point + +`SourceGeneratorTestOptions` is the base record. Common knobs: + +- `AdditionalNamespaces` / `IncludeDefaultNamespaces` — namespaces prepended to test source. +- `AdditionalAssemblyTypes` / `AdditionalReferences` — assemblies referenced by the test compilation + (use `AdditionalAssemblyTypes = [typeof(SomeType)]` to pull in a whole assembly). +- `AdditionalSources` — extra source files added to every run. +- `AnalyzerConfigOptions` — `build_property.*` values; keys without the prefix are also exposed as MSBuild + properties. +- `DisableSourceGeneratorPropertyName` / `DisableSourceGeneratorValue` — generator disable toggle. +- `NullableContextOptions`, `OutputKind`, `LanguageVersion`, `CompileToAssembly`. +- `ValidateCodeWriterScopes`, `EnableLogging`. +- `ExcludeGeneratedSourceHintNames` — hides generated marker trees from `PrimarySyntaxTrees`. + +**Easy starting point recipe.** Derive an options record that seeds the namespaces and assemblies your +generator needs, so every test gets a working compilation with no boilerplate: + +```csharp +public sealed record MyGeneratorTestOptions : SourceGeneratorTestOptions +{ + public MyGeneratorTestOptions() + { + AdditionalNamespaces = AdditionalNamespaces.Add("My.Namespace"); + AdditionalAssemblyTypes = AdditionalAssemblyTypes.AddRange( + typeof(SomeDependencyType), + typeof(TypeIdentity) // the framework's Shared assembly, when needed + ); + DisableSourceGeneratorPropertyName = PropertyLibrary.DisableMyGenerator; + } +} +``` + +`Compile()` returns a copy with `CompileToAssembly = true`, preserving the derived options type. Use the +base class hooks `OnBeforeRun`/`OnBeforeRunAsync`/`OnAfterRun` to mutate sources/options per run (for +example to append a marker attribute source via `WithAdditionalSources`). + +When `CompileToAssembly` is enabled, emission is fully in-memory. On .NET 8+ the assembly loads into a +collectible `AssemblyLoadContext`, so the result is `IDisposable` — `using var result = ...` unloads it and +keeps repeated runs from polluting the default context. `result.CompilationResult.Assembly` is the runnable +assembly (generated code can execute); `result.CompilationResult.Metadata` / `.MetadataAssembly` give a +metadata-only reflection view (types, members, attributes) over the emitted assembly without executing code. + +**Always write `using var result = ...`.** `PSGFR42` ("Dispose test harness results with a using +declaration") flags a `DriverRunResult` that is produced and never disposed — including the indirect case +where a helper creates a result, projects a value out of it and returns only the projection. It is a +`warning` when the run syntactically compiles to an assembly (`.Compile()`, a `Compile` options member, or +`CompileToAssembly = true`) and `info` otherwise; the `DisposeTestResultCodeFixProvider` fix inserts the +`using`. A result that is returned to the caller, or disposed explicitly, is not flagged. Neither is awaiting +an assertion, nor calling a helper that is handed the result — an extension on it, or a method taking it as a +parameter: both hand the same instance back, so `await Assert.That(result).SomeAssertion()` and +`result.AssertNoGenerationExceptions()` are not flagged. + +## Best practices + +- **Deterministic output**: `WriteAutoGeneratedHeader` is timestamp-free; assert with + `ContainsGeneratedCode`/`GeneratesCode` (whitespace-flattened) or `CodeQuery`, never with timestamps. +- **Generator references**: to use a generated type in the test project AND pass the generator type to a + runner, reference the generator project twice — once `OutputItemType="Analyzer"` and once as a normal + reference. +- **Multi-target**: build generators against the Roslyn version that supports the test matrix; the + framework is built against Roslyn 5.0 (net8.0/net9.0 assets keep a .NET 8–10 matrix loading); keep + `System.Collections.Immutable` version pinned to the shared one. +- **Scope validation**: keep `PurviewSourceGeneratorFrameworkValidateCodeWriterScopes` enabled; it makes + undisposed `CodeWriter` scopes fail tests. +- **Prefer `CodeQuery` over string matching** for structural assertions (members, signatures, namespaces). +- **Dispose results**: `using var result = ...`, enforced by `PSGFR42`. +- **Cap parallelism**: the harness shares one `MetadataReference` set per process, so memory is largely flat + in the degree of parallelism, but the platform's auto-detected default is both slower and heavier than an + explicit ceiling. Wall clock saturates around four concurrent tests; prefer + `--maximum-parallel-tests 8` (or a `TestingPlatformCommandLineArguments` equivalent) for a project that + multi-targets and runs several TFM executables at once. + +## Incremental cache testing (`RunIncrementalAsync`) + +To prove the pipeline caches correctly stage-by-stage, use `SourceGeneratorTestRunner.RunIncrementalAsync` +(or `GenerateIncrementalAsync` on the TUnit base). It runs a sequence of source sets over a **single shared +`GeneratorDriver`** and captures each run's `TrackedSteps`, keyed by tracking name. The canonical reference +implementation is `IncrementalPipelineCacheTests` in `SourceGeneratorShared.UnitTests`; the end-to-end +generator variant is `ServiceRegistrationCacheTests` in +`SourceGeneratorFramework.ExampleGenerator.UnitTests`. Copy the pattern into your own test project — do +not expect the source repo's files locally. + +### What is being asserted and why + +Roslyn reports one `IncrementalStepRunReason` per step output on each run: + +- `New` — the step ran for the first time. +- `Modified` — the step ran and produced a different value than the previous run. +- `Unchanged` — the step ran but produced the same value. +- `Cached` — the step was skipped and its previous result reused from the incremental cache. + +A pipeline is "caching correctly" when an unchanged input keeps every stage `Cached`/`Unchanged`, and a +targeted change marks **only** the stages whose inputs actually changed `Modified` while unrelated stages +stay `Cached`. If a generator accidentally leaks `Compilation`, `SemanticModel`, `ISymbol`, +`SyntaxNode`, or `Location` into a pipeline model, unrelated stages will report `Modified`/`New` on rerun — +these tests fail the build and catch the regression. + +### The four scenarios every cache test should cover + +1. **First run → all `New`.** Nothing can be cached on the first run; this confirms every stage is tracked + under the expected name. +2. **Identical rerun → all `Cached`/`Unchanged`.** `RunIncrementalAsync(sources, ...)` runs the same source + set twice for exactly this case. This is the strongest "it caches" proof. +3. **Source-only change → only the source/attribute stage `Modified`.** Changing an attributed class must + mark `ForAttribute_*` (and downstream output) `Modified` while property/config stages stay `Cached`. +4. **Property-only change → only the property/configuration stage `Modified`.** Toggling an MSBuild + property (via `IncrementalRunInput.AnalyzerConfig`) must mark `GetMSBuildPropertyValue_*` / + `GetGenerationConfiguration` / `GetGenerationContext_*` `Modified` while `ForAttribute_*` stays `Cached`. + +### How the runner makes this possible + +`RunIncrementalAsync` creates **one** driver, enables incremental step tracking, and **reuses the same +`Compilation` instance for identical source sets** (keyed by prepared source text). Without that reuse, +Roslyn would see a fresh compilation on the second run and report stages `Modified`/`New` even though the +sources are byte-identical — the "cached" assertion would fail. + +### Log entries per run + +`IncrementalCacheRun.LogEntries` carries the framework log entries that run wrote, in order. The sink is +registered for the whole sequence and drained between runs, so entries never accumulate. A rerun whose +output step is cached logs nothing, which makes it a second signal alongside the step reasons: + +```csharp +await Assert.That(result.Runs[0].LogEntries).IsNotEmpty(); +await Assert.That(result.Runs[1].LogEntries).IsEmpty(); +``` + +`DriverRunResult.LogEntries` (the `RunAsync` path) is likewise in write order. Both are empty when +`EnableLogging` is disabled. + +### The `StepReasons` helper + +`IncrementalCacheRun.Steps` is `ImmutableDictionary>` +keyed by tracking name. Flatten each step's `Outputs` into the reasons list so assertions read cleanly: + +```csharp +static ImmutableDictionary> StepReasons(IncrementalCacheRun run) +{ + var builder = ImmutableDictionary.CreateBuilder>(); + foreach (var pair in run.Steps) + builder[pair.Key] = [.. pair.Value.SelectMany(step => step.Outputs.Select(static output => output.Reason))]; + return builder.ToImmutable(); +} +``` + +### Framework pipeline stage names + +- `GetMSBuildPropertyValue_{Property}` — `IncrementalPipeline.PropertyValueProvider`. +- `GetGenerationConfiguration` — `IncrementalPipeline.GenerationContextValueProvider`. +- `GetGenerationContext_{Capabilities}` — e.g. `GetGenerationContext_EmptyCapabilities`. +- `ForAttribute_{AttributeType}` — `IncrementalPipeline.ForAttributeWithMetadataName`. + +The framework reference (`IncrementalPipelineCacheTests`, framework-agnostic runner) shows all four +scenarios against `TestGenerator`/`DiagnosticTestGenerator`: + +```csharp +using System.Collections.Immutable; +using Purview.SourceGeneratorFramework.TestGenerators; +using StepReason = Microsoft.CodeAnalysis.IncrementalStepRunReason; + +public class IncrementalPipelineCacheTests +{ + const string AttributedSource = """ + [TestAttribute] + public partial class MyClass { } + """; + const string ChangedAttributedSource = """ + [TestAttribute] + public partial class AnotherClass { } + """; + const string TestAttributeSource = """ + [System.AttributeUsage(System.AttributeTargets.Class)] + public sealed class TestAttribute : System.Attribute { } + """; + + static SourceGeneratorTestOptions CreateOptions() => + new SourceGeneratorTestOptions() + .WithAdditionalSources(TestAttributeSource) + .WithExcludeGeneratedSourceHintNames("TestAttribute"); + + static ImmutableDictionary> StepReasons(IncrementalCacheRun run) { /* as above */ } + + [Test] + public async Task FirstRun_AllStagesAreNew(CancellationToken cancellationToken) + { + var result = await new SourceGeneratorTestRunner().RunIncrementalAsync( + [new IncrementalRunInput([AttributedSource])], + CreateOptions(), + cancellationToken); + + var reasons = StepReasons(result.Runs[0]); + await Assert.That(reasons).IsNotEmpty(); + await Assert.That(reasons.Values.SelectMany(r => r).All(r => r == StepReason.New)).IsTrue(); + } + + [Test] + public async Task IdenticalRerun_AllStagesCached(CancellationToken cancellationToken) + { + var result = await new SourceGeneratorTestRunner() + .RunIncrementalAsync([AttributedSource], CreateOptions(), cancellationToken); + + var second = StepReasons(result.Runs[1]); + await Assert.That(second.Values.SelectMany(r => r).All(r => r is StepReason.Cached or StepReason.Unchanged)).IsTrue(); + } + + [Test] + public async Task SourceChange_MarksAttributeStageModified_PropertyStagesStayCached(CancellationToken cancellationToken) + { + var result = await new SourceGeneratorTestRunner().RunIncrementalAsync( + [new IncrementalRunInput([AttributedSource]), new IncrementalRunInput([ChangedAttributedSource])], + CreateOptions(), + cancellationToken); + + var second = StepReasons(result.Runs[1]); + await Assert.That(second["ForAttribute_TestAttribute"]).Contains(StepReason.Modified); + await Assert.That(second["GetMSBuildPropertyValue_DisableTestGenerator"].All(r => r == StepReason.Cached)).IsTrue(); + } + + [Test] + public async Task PropertyChange_MarksPropertyStageModified_AttributeStageStaysCached(CancellationToken cancellationToken) + { + var result = await new SourceGeneratorTestRunner().RunIncrementalAsync( + [ + new IncrementalRunInput([AttributedSource]), + new IncrementalRunInput([AttributedSource], [("build_property.DisableTestGenerator", "true")]), + ], + CreateOptions(), + cancellationToken); + + var second = StepReasons(result.Runs[1]); + await Assert.That(second["GetMSBuildPropertyValue_DisableTestGenerator"]).Contains(StepReason.Modified); + await Assert.That(second["ForAttribute_TestAttribute"].All(r => r == StepReason.Cached)).IsTrue(); + } +} +``` + +### End-to-end generator variant (`GenerateIncrementalAsync`) + +TUnit tests derive from the base class and call `GenerateIncrementalAsync` (which wires the +`OnBeforeRun`/`OnBeforeRunAsync` hooks and the derived options). `ServiceRegistrationCacheTests` in +`SourceGeneratorFramework.ExampleGenerator.UnitTests` is the reference: + +```csharp +public class ServiceRegistrationCacheTests + : TUnitSourceGeneratorTestBase +{ + const string Source = """ + namespace Test; + + [GenerateService] + public class MyService { } + """; + + [Test] + public async Task IdenticalRerun_AllStagesCached(CancellationToken cancellationToken) + { + var result = await GenerateIncrementalAsync([Source], cancellationToken: cancellationToken); + + var second = StepReasons(result.Runs[1]); + string[] frameworkStages = + [ + "GetMSBuildPropertyValue_EmitServiceRegistrationInfo", + "GetGenerationConfiguration", + "GetGenerationContext_EmptyCapabilities", + "ForAttribute_GenerateServiceAttribute", + ]; + await Assert.That( + frameworkStages.All(stage => + second.TryGetValue(stage, out var reasons) + && reasons.All(r => r is StepReason.Cached or StepReason.Unchanged))).IsTrue(); + } +} +``` + +**Why the example filters to `frameworkStages`:** `ServiceRegistrationGenerator` emits its own +`GenerateServiceAttribute` via post-initialization output, which is regenerated as a new `SyntaxTree` each +run. That makes Roslyn's *internal* `ForAttributeWithMetadataName` `Compilation` step legitimately report +`Modified` on an identical rerun. Asserting on the framework-named stages (which stay `Cached`/`Unchanged`) +is the meaningful check. If your generator does not depend on its own post-init output, the stricter +"every tracked step is `Cached`/`Unchanged`" assertion (as in the framework `IncrementalPipelineCacheTests`) +is correct. + +Per-run MSBuild-property changes are supplied with `new IncrementalRunInput(sources, [("build_property.X", "value")])`. + +## License + +This project is licensed under the MIT license. \ No newline at end of file diff --git a/.claude/skills/purview-sourcegenerator-testing/references/test-modernisation.md b/.claude/skills/purview-sourcegenerator-testing/references/test-modernisation.md new file mode 100644 index 00000000..6db47803 --- /dev/null +++ b/.claude/skills/purview-sourcegenerator-testing/references/test-modernisation.md @@ -0,0 +1,63 @@ +# Modernising a Roslyn test suite + +A playbook for moving an existing test suite onto `CodeQuery` plus the TUnit assertion extensions, +and adding a stage-by-stage incremental cache test. + +## Before you start, collect + +- The test file(s) being changed. +- The Roslyn component under test — generator, analyzer, code fix or refactor (infer it from the + base class if the task does not say). +- The component's type name. + +## Requirements + +### 1. The right base class and method + +| Component | Base class | Method | +| --- | --- | --- | +| Generator | `TUnitSourceGeneratorTestBase` | `GenerateAsync` | +| Analyzer | `TUnitDiagnosticAnalyzerTestBase` | `AnalyzeAsync` | +| Code fix | `TUnitCodeFixTestBase` | `ApplyCodeFixAsync` / `ApplyFixAllAsync` | +| Refactor | `TUnitRefactoringTestBase` | `RefactorAsync` | + +### 2. `CodeQuery` instead of string matching + +Replace `GetGeneratedTree(...)` + `string.Contains(...)` with `CodeQuery` +(`result.Generated().Get/Has/TryGet…`) and the terminal assertion extensions — +`await Assert.That(result).HasGeneratedMethod/Class/Property/Field/SyntaxTree(…)` — which return the +node so a follow-up assertion has something to work with. + +### 3. `TypeReference` instead of signature strings + +Match parameter and return types structurally. A signature string breaks on a whitespace or +nullability change that means nothing. + +### 4. Options in one place + +Derive a `SourceGeneratorTestOptions` record that seeds the required namespaces and additional +assemblies, and remove the per-test duplication it replaces. + +### 5. A stage-by-stage cache test + +Use `RunIncrementalAsync`, or `GenerateIncrementalAsync` on the TUnit base, and assert the four +scenarios. `ServiceRegistrationCacheTests` and `IncrementalPipelineCacheTests` are the reference +pattern. + +| Scenario | Expected | +| --- | --- | +| First run | every framework stage `New` | +| Identical rerun (`RunIncrementalAsync(sources, …)` runs the same source twice) | framework stages `Cached`/`Unchanged` | +| Source-only change | `ForAttribute_*` `Modified`; property/config stages stay `Cached` | +| Property-only change (`new IncrementalRunInput(sources, [("build_property.X", "value")])`) | `GetMSBuildPropertyValue_*`, `GetGenerationConfiguration`, `GetGenerationContext_*` `Modified`; `ForAttribute_*` stays `Cached` | + +Use the `StepReasons(IncrementalCacheRun)` flattening helper. If the generator depends on its own +post-init output, assert on the framework-named stages rather than on every tracked step. + +### 6. Minimal change + +Keep behaviour equivalent, and do not reformat unrelated tests. + +## Verification + +Build the test project and run its suite before finishing. diff --git a/.claude/skills/purview-sourcegenerator-tunit-tests/SKILL.md b/.claude/skills/purview-sourcegenerator-tunit-tests/SKILL.md new file mode 100644 index 00000000..bc711c59 --- /dev/null +++ b/.claude/skills/purview-sourcegenerator-tunit-tests/SKILL.md @@ -0,0 +1,230 @@ +--- +name: purview-sourcegenerator-tunit-tests +description: >- + Use when writing TUnit tests for source generators, diagnostic analyzers, code fixes or + refactorings built on Purview.SourceGeneratorFramework - choosing the correct TUnit base class and + method, customising SourceGeneratorTestOptions, using the TUnit assertion extensions, and + modernising existing tests. +metadata: + product: Purview.SourceGeneratorFramework.Testing.TUnit + repository: purview-dev/sourcegenerator-framework +--- + +# TUnit test authoring for Roslyn components + +Use this skill whenever a task involves authoring, fixing, or modernising **TUnit** tests for Roslyn +components built with `Purview.SourceGeneratorFramework`. It tells you which base class to derive from, +which method to call, how to customise options with an easy starting point, and how to use the TUnit +assertion extensions. For the framework-agnostic runner layer and the `CodeQuery` API, also load the +`purview-sourcegenerator-testing` skill. + +## Base class → method matrix + +| Roslyn type | Base class | Method to call | +|---|---|---| +| `IIncrementalGenerator` / `ISourceGenerator` | `TUnitSourceGeneratorTestBase` | `GenerateAsync(source, options, ct)` | +| `DiagnosticAnalyzer` | `TUnitDiagnosticAnalyzerTestBase` | `AnalyzeAsync(source, options, ct)` | +| `CodeFixProvider` (single fix) | `TUnitCodeFixTestBase` | `ApplyCodeFixAsync(source, options, ct)` | +| `CodeFixProvider` (fix-all) | `TUnitCodeFixTestBase` | `ApplyFixAllAsync(sources, options, ct)` | +| `CodeRefactoringProvider` | `TUnitRefactoringTestBase` | `RefactorAsync(source, options, ct)` | + +For cache tests, `TUnitSourceGeneratorTestBase` also exposes `GenerateIncrementalAsync(...)`. + +Framework-agnostic equivalents (no TUnit): `SourceGeneratorTestRunner`, `DiagnosticAnalyzerTestRunner`, +`CodeFixTestRunner`, `RefactoringTestRunner`. + +## Easy starting point: derive your options record + +Create a test-options record that seeds the namespaces and assemblies your component needs, then pass it +to every test via `new MyTestOptions()`: + +```csharp +public sealed record MyGeneratorTestOptions : SourceGeneratorTestOptions +{ + public MyGeneratorTestOptions() + { + AdditionalNamespaces = AdditionalNamespaces.Add("My.Namespace"); + AdditionalAssemblyTypes = AdditionalAssemblyTypes.AddRange( + typeof(SomeDependencyType), + typeof(TypeIdentity) // framework Shared assembly, when needed + ); + DisableSourceGeneratorPropertyName = "DisableMyGenerator"; + } +} + +public class MyGeneratorTests : TUnitSourceGeneratorTestBase +{ + [Test] + public async Task GeneratesExpectedSource(CancellationToken ct) => + await GenerateAsync("...source...", ct); +} +``` + +Use the base hooks to customise per-run: `OnBeforeRun`/`OnBeforeRunAsync` (mutate sources/options, e.g. +`options.WithAdditionalSources(markerAttributeSource)`) and `OnAfterRun`/`OnAfterRunAsync`. Use +`options.Compile()` to opt into `CompileToAssembly` while preserving the derived options type. + +Write `using var result = await GenerateAsync(...)`: `DriverRunResult` is `IDisposable`, and `PSGFR42` +flags a result that is produced and never disposed (a `warning` once the run compiles to an assembly, +`info` otherwise). It also catches the indirect case — a helper that creates a result, projects a value out +of it and returns only the projection. Awaiting an assertion, or calling a helper that is handed the result — +an extension on it, or a method taking it as a parameter — is not a production: both hand the same instance +back, so neither is flagged. + +For code fixes/refactorings, select a specific registered action via `CodeFixTestOptions.EquivalenceKey` +or `CodeActionIndex`, and `RefactorTestOptions.Span`/`NodeSelector` (e.g. +`NodeSelector = query => query.GetMethod("M")`). + +## TUnit assertion extensions + +All assertion extensions live under `Purview.SourceGeneratorFramework.Testing.TUnit.Assertions` +(globally imported by the package's props). `Assert.That(...)` calls are terminal and **return the value** +when awaited. + +- **`CodeQueryAssertions`** — return `CodeQueryResult` (the matched node via `.Node`, plus a query + scoped to it via `.Query`): `HasGeneratedMethod` (optionally with `TypeReference[]` parameter types), + `HasGeneratedMethodReturnType`, `HasGeneratedClass` (by name or `TypeReference`/`TypeIdentity` identity), + `HasGeneratedProperty`, `HasGeneratedField`, `HasGeneratedSyntaxTree`; `HasFixedMethod` for code-fix and + refactor results. The assertions operate on a `CodeQuery` directly, so pass any query — `result.Generated()` + (generated trees), `result.Output()` (whole compilation), or `result.FixedCode()` — or use the convenience + overloads on the test result types, which query the relevant code for you. +- **Scoped member chaining** — `HasPropertyOfType(name, type)`, `HasFieldOfType(name, type)`, + `HasMethodOfType(name, TypeReference[])`, `HasConstructorOfType(TypeReference[])`, and + `HasAttributeOfType(name)` chain from a scoped `CodeQueryResult` (e.g. the result of `HasGeneratedClass`) + and return the matched member. They are named to avoid colliding with the bool `Has*` predicates in + `MemberQueryExtensions`. +- **Fluent `.And` chains** — the node-producing assertions (`HasGeneratedClass`, `HasPropertyOfType`, + `HasMethodOfType`, `HasNestedType`) move the chain onto the matched node, so further assertions can be + appended with `.And`. Node-inspection assertions — `WithAccessibility`, `WithGetterAccessibility`, + `WithSetterAccessibility`, `WithBaseType`, `WithGenericTypeParameter(s)`, `IsInNamespace`, + `IsInGlobalNamespace` — keep the node on the chain: + ```csharp + var method = await Assert.That(query) + .HasGeneratedClass("Service") + .And.HasNestedType("Builder") + .And.WithAccessibility(Accessibility.Private) + .And.HasMethodOfType("Build", []); + ``` + Generic types are matched by arity — `HasGeneratedClass(name, arity)` or a `TypeIdentity` with arity — + so `new TypeIdentity("ResourceDefinition", ns, arity: 1)` finds `ResourceDefinition` + without matching the non-generic `ResourceDefinition`. +- **Nullable expected types in tests** — use the test-only `query.MakeNullable(type)` extension (on a + `CodeQuery`). It resolves the annotation against the query's compilation and, unlike + `TypeReference.Nullable()`/`TypeIdentity.MakeNullable()`, does not trip the `PSGFR16` context-overload + suggestion, since tests have no generation context to pass. + ```csharp + CodeQueryResult method = await Assert.That(result.Generated()).HasGeneratedMethod("DoWork", [intType, nullableInt]); + CodeQueryResult cls = await Assert.That(result.Generated()).HasGeneratedClass("Service"); + await Assert.That(cls.HasProperty("Count", intType)).IsTrue(); // chained member query + await Assert.That(cls.Node.Identifier.ValueText).IsEqualTo("Service"); // direct syntax access + await Assert.That(result.FixedCode()).HasFixedMethod("DoWork"); // code-fix / refactor results + + var query = result.Generated(); + var attributeClass = await Assert.That(query).HasGeneratedClass(hostKitAttribute); + await Assert.That(attributeClass).HasPropertyOfType("Name", query.MakeNullable(TypeLibrary.System.String)); + ``` +- **`DiagnosticAssertions`** — `HasDiagnostic(descriptor|id)`, `HasDiagnostics(count)`, + `DoesNotHaveDiagnostic`, `HasNoDiagnostics`, `HasNoErrorDiagnostics` on generator/analyzer/code-fix results. +- **`TypeIdentityAssertions`** — `HasSymbol(TypeIdentity)` / `HasSymbol("Namespace.Type")`. +- **`GeneratedCodeAssertionsExtensions`** — `GeneratesCode(expected)`, `ContainsGeneratedCode(expected)` + (whitespace-flattened string comparison). + +For structural assertions (members, signatures, namespaces) prefer `result.Generated()` + +`Get/Has/TryGet` from `CodeQuery` (see `purview-sourcegenerator-testing`). + +## Incremental cache tests (`GenerateIncrementalAsync`) + +`TUnitSourceGeneratorTestBase` exposes `GenerateIncrementalAsync`, which mirrors `RunIncrementalAsync` but +also wires the base class hooks (`OnBeforeRun`/`OnBeforeRunAsync`) and your derived options record. Use it to +prove the pipeline caches stage-by-stage. The reference is `ServiceRegistrationCacheTests` in +`SourceGeneratorFramework.ExampleGenerator.UnitTests`; the framework-agnostic twin with a full walkthrough is +in the `purview-sourcegenerator-testing` skill. + +Why the tests look the way they do: + +- `GenerateIncrementalAsync([Source])` runs the **same source twice** on a single shared driver. The first + run reports every stage `New`; the second must report `Cached`/`Unchanged` for unchanged stages — that is + the core "it caches" proof. +- `GenerateIncrementalAsync([new IncrementalRunInput([Source]), new IncrementalRunInput([changed])])` runs two + **different** source sets, so a source-only change must mark `ForAttribute_*` `Modified` while + property/configuration stages stay `Cached`. +- `new IncrementalRunInput([Source], [("build_property.X", "value")])` toggles an MSBuild property for one + run only, so a property-only change must mark `GetMSBuildPropertyValue_*`/`GetGenerationConfiguration`/ + `GetGenerationContext_*` `Modified` while `ForAttribute_*` stays `Cached`. +- `result.Runs[n].LogEntries` carries the framework log entries *that run* wrote, in order, so a rerun whose + output step is cached can be asserted to have logged nothing. Empty when `EnableLogging` is disabled. +- The `StepReasons(IncrementalCacheRun)` helper flattens each tracked step's `Outputs` into a + `ImmutableDictionary>` so assertions can address a stage + by name (see `purview-sourcegenerator-testing` for the helper body). +- If the generator's pipeline depends on its own post-initialization output (a self-referencing generated + attribute), Roslyn's internal `ForAttributeWithMetadataName` `Compilation` step is legitimately `Modified` + on rerun; assert on the framework-named stages (e.g. `ForAttribute_GenerateServiceAttribute`, + `GetGenerationConfiguration`, `GetGenerationContext_EmptyCapabilities`) rather than every tracked step. + +```csharp +public class ServiceRegistrationCacheTests + : TUnitSourceGeneratorTestBase +{ + const string Source = """ + namespace Test; + + [GenerateService] + public class MyService { } + """; + + [Test] + public async Task IdenticalRerun_AllStagesCached(CancellationToken cancellationToken) + { + var result = await GenerateIncrementalAsync([Source], cancellationToken: cancellationToken); + + var second = StepReasons(result.Runs[1]); + string[] frameworkStages = + [ + "GetMSBuildPropertyValue_EmitServiceRegistrationInfo", + "GetGenerationConfiguration", + "GetGenerationContext_EmptyCapabilities", + "ForAttribute_GenerateServiceAttribute", + ]; + await Assert.That( + frameworkStages.All(stage => + second.TryGetValue(stage, out var reasons) + && reasons.All(r => r is StepReason.Cached or StepReason.Unchanged))).IsTrue(); + } + + [Test] + public async Task PropertyChange_MarksPropertyStageModified_AttributeStageStaysCached(CancellationToken cancellationToken) + { + var result = await GenerateIncrementalAsync( + [ + new IncrementalRunInput([Source]), + new IncrementalRunInput([Source], [(PropertyLibrary.EmitServiceRegistrationInfo, "true")]), + ], + cancellationToken: cancellationToken); + + var second = StepReasons(result.Runs[1]); + await Assert.That(second["GetMSBuildPropertyValue_EmitServiceRegistrationInfo"]).Contains(StepReason.Modified); + await Assert.That(second["ForAttribute_GenerateServiceAttribute"].All(r => r is StepReason.Cached or StepReason.Unchanged)).IsTrue(); + } +} +``` + +Use `using StepReason = Microsoft.CodeAnalysis.IncrementalStepRunReason;` and your own stage names. + +## Modernising existing tests + +When converting legacy tests that do `result.GetGeneratedTree(...)` + `string.Contains(...)`: + +1. Replace tree-lookup + string matching with `result.Generated().GetClass/GetMethod/GetProperty(...)` and + the `Has*`/`TryGet*` family. +2. Replace signature string checks with `TypeReference` parameter/return-type matching. +3. Replace `Assert.That(text).Contains("...")` with the terminal assertion extensions that return nodes. +4. Verify options use a derived record (namespaces + assemblies) rather than repeating `AdditionalNamespaces` + per test. +5. Add a stage-by-stage cache test if the component has an incremental pipeline — first run `New`, + identical rerun `Cached`/`Unchanged`, and targeted changes mark only the affected stage `Modified`. + Use the inlined examples in this skill and in `purview-sourcegenerator-testing`'s "Incremental cache testing" + section, swapping in your own generator and stage names. + +## License + +This project is licensed under the MIT license. \ No newline at end of file diff --git a/.claude/skills/purview-telemetry-design/SKILL.md b/.claude/skills/purview-telemetry-design/SKILL.md new file mode 100644 index 00000000..c8df5f81 --- /dev/null +++ b/.claude/skills/purview-telemetry-design/SKILL.md @@ -0,0 +1,96 @@ +--- +name: purview-telemetry-design +description: Design best practices for Purview.Telemetry.SourceGenerator interfaces. Use when deciding between a single telemetry interface and per-area interfaces, choosing telemetry names, designing multi-target methods, or reviewing telemetry structure in a C# project. +license: MIT +compatibility: C# projects using Purview.Telemetry.SourceGenerator. +metadata: + author: Purview-Dev + version: "1.0" +--- + +# Design best practices for Purview Telemetry + +This skill guides the design of generated telemetry interfaces. + +## Single combined interface vs. per-area interfaces + +The generator lets you put all telemetry types on one interface, or split them by concern. + +### Combined interface + +Use one interface when: + +- A single service owns all telemetry and the operations naturally overlap. +- You want a single injection point and fewer constructor parameters. +- Multi-target methods emit Activity + Log + Metric from one call. + +Naming convention: + +```csharp +[ActivitySource] +[Logger] +[Meter] +public interface IOrderServiceTelemetry +``` + +### Per-area interfaces + +Split into separate interfaces when: + +- Different consumers need only one telemetry type (e.g., tests mock only logs). +- The team prefers clear separation between tracing, logging, and metrics. +- The service is large and each telemetry type has many operations. + +Naming convention: + +```csharp +[ActivitySource] public interface IOrderServiceTracing { ... } +[Logger] public interface IOrderServiceLogs { ... } +[Meter] public interface IOrderServiceMetrics { ... } +``` + +Default recommendation: start with one combined interface per service. Split only when a clear boundary emerges. + +## Naming conventions + +Default to the OpenTelemetry naming convention (`NamingConvention.OpenTelemetry`). + +- ActivitySource names: preserve assembly casing (e.g., `MyApp`). +- Activity names: descriptive, sentence-case-ish, no spaces: `placing-order`. +- Log message templates: human-readable, with `{PascalCase}` placeholders. +- Metric instrument names: hierarchical, dot-separated, lowercase: `myapp.orders.placed`. +- Tag/baggage keys: `snake_case`. + +Only use `NamingConvention.Legacy` for exact v3 backward compatibility. + +## Multi-target method design + +Combine attributes on one method when a single operation emits multiple telemetry types: + +```csharp +[Activity] +[Info] +[AutoCounter] +Activity? PlacingOrder(int orderId); +``` + +Rules: + +- Methods that return `Activity?` create an Activity. +- Methods that return `void` typically add events, log, or record metrics. +- Pass the `Activity?` from the starting method to event/context methods. + +## Parameter attributes + +| Attribute | Use | +|---|---| +| `[Baggage]` | Adds the parameter to Activity baggage; also included in logs. | +| `[Tag]` | Adds the parameter as an Activity tag. | +| `[ExcludeTargets(Targets.Activities)]` | Excludes the parameter from Activity generation only. | +| `[ExpandEnumerable(maximumValueCount: N)]` | Expands an array/IEnumerable into indexed log properties. | + +## Testing + +Inject the interface in your service and mock it in tests. The generated interface has no implementation code in the interface itself, so standard mocking frameworks (NSubstitute, Moq, TUnitMocks) work directly. + +See [references/REFERENCE.md](references/REFERENCE.md) for a decision matrix and naming examples. diff --git a/.claude/skills/purview-telemetry-design/references/REFERENCE.md b/.claude/skills/purview-telemetry-design/references/REFERENCE.md new file mode 100644 index 00000000..b15cfcf0 --- /dev/null +++ b/.claude/skills/purview-telemetry-design/references/REFERENCE.md @@ -0,0 +1,101 @@ +# Design reference + +## Interface shape decision matrix + +| Situation | Recommendation | +|---|---| +| Small service with < 10 telemetry operations | One combined `ITelemetry` | +| Service only logs | `ILogs` | +| Service only traces | `ITracing` | +| Service only emits metrics | `IMetrics` | +| Large service with distinct teams owning logs vs. metrics | Split into per-area interfaces | +| Need to mock only one telemetry type in many tests | Split into per-area interfaces | + +## Naming examples + +### OpenTelemetry mode (default) + +```csharp +[ActivitySource] // name = "MyApp" +[Logger] +[Meter] +public interface IOrderServiceTelemetry +{ + [Activity] + Activity? PlacingOrder(int orderId); // activity name = "placing-order" + + [Info("Placing order {OrderId}")] + void PlacingOrderInfo(int orderId); // log + + [AutoCounter] + void OrderPlaced(); // instrument = "myapp.orders.order-placed" +} +``` + +### Legacy mode + +```csharp +[assembly: TelemetryGeneration(NamingConvention = NamingConvention.Legacy)] +``` + +Use only when exact v3 names must be preserved. + +## Multi-target example + +```csharp +[ActivitySource] +[Logger] +[Meter] +public interface IOrderServiceTelemetry +{ + // Starts Activity, logs Info, increments Counter + [Activity(ActivityKind.Internal)] + [Info("Placing order {OrderId} for {CustomerName}")] + [AutoCounter] + Activity? PlacingOrder(int orderId, string customerName, [Baggage] string region); + + // Adds event to the Activity and logs Trace + [Event] + [Trace] + void OrderValidated(Activity? activity, int orderId); + + // Records histogram + [Histogram] + void OrderProcessingTime(double latencyMs); +} +``` + +## Parameter attribute examples + +```csharp +[Activity] +[Info] +Activity? FetchingOrder( + int orderId, + [Baggage] string region, // carried in Activity baggage + [Tag] string tenantId); // Activity tag only + +[Event] +void OrderLoaded( + Activity? activity, + int orderId, + [ExcludeTargets(Targets.Activities)] string[] rawLines); // not in Activity +``` + +## Testing example + +```csharp +public class OrderServiceTests +{ + [Test] + public void PlaceOrder_EmitsTelemetry() + { + var telemetry = Substitute.For(); + var service = new OrderService(telemetry); + + service.PlaceOrder(42, "Alice", "EMEA"); + + telemetry.Received().PlacingOrder(42, "Alice", "EMEA"); + } +} +``` diff --git a/.claude/skills/purview-telemetry-diagnostics/SKILL.md b/.claude/skills/purview-telemetry-diagnostics/SKILL.md new file mode 100644 index 00000000..fec24d27 --- /dev/null +++ b/.claude/skills/purview-telemetry-diagnostics/SKILL.md @@ -0,0 +1,168 @@ +--- +name: purview-telemetry-diagnostics +description: >- + Use when a Purview.Telemetry.SourceGenerator build reports a TSG diagnostic - TSG1xxx general, + TSG2xxx logging, TSG3xxx activities, TSG4xxx metrics - to find what triggered it and how to fix it, + or when deciding whether a rule can be suppressed. +license: MIT +compatibility: C# projects using Purview.Telemetry.SourceGenerator. +metadata: + author: Purview-Dev + product: Purview.Telemetry.SourceGenerator + repository: purview-dev/telemetry-sourcegenerator +--- + +# Purview.Telemetry.SourceGenerator diagnostics + +One Roslyn analyzer, `TelemetryDiagnosticAnalyzer`, validates telemetry interfaces and raises `TSG` +diagnostics in four families: + +| Family | Covers | +| --- | --- | +| `TSG1xxx` | general — interface and method shape, targets, framework support | +| `TSG2xxx` | logging | +| `TSG3xxx` | activities | +| `TSG4xxx` | metrics | + +Every rule is tracked in `AnalyzerReleases.Shipped.md` / `AnalyzerReleases.Unshipped.md` with its ID, +category and severity, validated by the Roslyn release-tracking analyzers on every build. A new or +changed diagnostic must be recorded there in the same change. + +## General — `TSG1xxx` + +| ID | Severity | Reported when | +| --- | --- | --- | +| `TSG1000` | Error | An unexpected exception escaped the generation pipeline. | +| `TSG1001` | Error | A method on a multi-target interface has no explicit generation attribute — inference is not supported there. | +| `TSG1002` | Error | Two attributes from the same target family on one method. Only one Activity, Logging or Metrics attribute per method. | +| `TSG1003` | Error | Two methods on the interface share a name. | +| `TSG1004` | Error | Generic interfaces are not supported. | +| `TSG1005` | Error | Generic methods are not supported. | +| `TSG1006` | Warning | `ExcludeTargets` names a target not present on the method. | +| `TSG1007` | Warning | `ExcludeTargets` leaves a target with an empty or invalid parameter set. | +| `TSG1008` | Warning | An `Activity`-typed parameter on a method with no `[Activity]`/`[Event]`/`[Context]`. | +| `TSG1010` | Error | A method carries an attribute for a target family the interface does not register. | +| `TSG1011` | Error | The compilation targets neither .NET 8+ nor .NET Framework 4.8+. Define `PURVIEW_TELEMETRY_NON_NULLABLE` to opt out. | + +## Logging — `TSG2xxx` + +| ID | Severity | Reported when | +| --- | --- | --- | +| `TSG2000` | Error | A non-scoped log method has more than one `Exception` parameter. | +| `TSG2001` | Error | A v1-mode log method has more than 6 non-exception parameters. | +| `TSG2002` | Info | v1 generation inferred `Error` from a lone `Exception` parameter with no explicit level. | +| `TSG2003` | Warning | No reference to `Microsoft.Extensions.Logging.ILogger`; log generation is skipped. | +| `TSG2004` | Error | Ordinal and named placeholders mixed in one message template. | +| `TSG2005` | Error | The maximum ordinal placeholder exceeds the parameter count. | +| `TSG2006` | Error | `[LogProperties]` and `[ExpandEnumerable]` on the same parameter. | +| `TSG2007` | Warning | A scoped log declares a `LogLevel`; it is ignored. | +| `TSG2008` | Warning | `[ExpandEnumerable]` has a `MaximumValueCount` above the recommended default of 5. | +| `TSG2021` | Error | A log method returns something other than `void` or `IDisposable`. (`Activity` is allowed when the method is also an Activity method.) | + +## Activities — `TSG3xxx` + +| ID | Severity | Reported when | +| --- | --- | --- | +| `TSG3000` | Warning | A baggage parameter is not a string; `ToString()` will be called. | +| `TSG3001` | Warning | No activity source name available anywhere; generation defaults to `purview`. | +| `TSG3002` | Error | An Activity/Event method returns something other than `void` or `Activity`. | +| `TSG3003` | Error | More than one parameter maps to the same reserved destination. | +| `TSG3004` | Error | An `Activity`-destination parameter on an Activity method — only valid on `[Event]`. | +| `TSG3005` | Error | A `timestamp` parameter on a method that is not `[Event]`. | +| `TSG3006` | Error | A start-time parameter on a Create-activity or Event method. | +| `TSG3007` | Error | A parent-context or parent-id parameter on an event. | +| `TSG3008` | Error | Activity-links parameters on an event or context method. | +| `TSG3009` | Error | An activity-tags parameter on a context method. | +| `TSG3010` | Error | An escaped parameter is not a boolean. | +| `TSG3011` | Error | Escaped parameters on an Activity or Context method — Events only. | +| `TSG3012` | Info | No Activity methods defined; `Activity.Current` is assumed. | +| `TSG3013` | Warning | An Activity method does not return the created `Activity`. | +| `TSG3014` | Warning | An Event/Context method has no `Activity` parameter. Controlled by `ActivitySourceGeneration.GenerateDiagnosticsForMissingActivity` (default `true`). | +| `TSG3015` | Info | `Activity` should be the first parameter. Same opt-in as `TSG3014`. | +| `TSG3016` | Error | A status-description parameter is not a string. | +| `TSG3017` | Error | Status-description parameters on an Activity or Context method — Events only. | +| `TSG3021` | Info | An `[Event]` records an exception under the OpenTelemetry rules but is not named `"exception"`. | +| `TSG3022` | Warning | An Activity method returns non-nullable `Activity`. | + +## Metrics — `TSG4xxx` + +| ID | Severity | Reported when | +| --- | --- | --- | +| `TSG4000` | Error | A method on a Metrics interface has no instrument attribute and is not excluded. | +| `TSG4001` | Error | A metrics-owned method returns something other than `void` or `bool`. | +| `TSG4002` | Error | An auto-increment instrument also declares a measurement parameter. | +| `TSG4003` | Error | More than one measurement value. | +| `TSG4004` | Error | A non-auto-increment instrument method has no measurement parameter. | +| `TSG4005` | Error | An observable instrument is not declared as `Func`. | +| `TSG4006` | Error | The measurement type is not `byte`, `short`, `int`, `long`, `double`, `float`, `decimal`, `Measurement` or `IEnumerable>`. | +| `TSG4007` | Error | An observable metric returns `bool`. | +| `TSG4008` | Error | An `AutoCounter` does not return `void`. | +| `TSG4009` | Warning | The instrument name matches the instrument type name. Name what is measured, not the instrument. | + +## The ones people actually hit + +### `TSG1001` — inference is off on a multi-target interface + +A method on an interface carrying `[ActivitySource]` + `[Logger]` + `[Meter]` has no explicit +attribute. Add one per target the method should emit, or mark it `[Exclude]`: + +```csharp +[ActivitySource("MyApp")] +[Logger] +[Meter] +interface IMyTelemetry +{ + [Info] // explicit target + void ProcessItem(int id); +} +``` + +### `TSG3013` / `TSG3014` — the Activity went missing + +Return the created `Activity` (as `Activity?`, per `TSG3022` — it is null when no listeners are +active) and pass it into the Event and Context methods that should attach to it. Both are +best-practice rules controlled by `ActivitySourceGeneration.GenerateDiagnosticsForMissingActivity`. + +### `TSG3021` — exception event name + +Name the event `exception` so the OpenTelemetry exception tags (`exception.type`, +`exception.message`, `exception.stacktrace`, `exception.escaped`) attach to *that* event rather than +a separate one: + +```csharp +[Event(Name = "exception")] // the event carries the exception tags +void FailedToRetrieve(Activity? activity, Exception exception); +``` + +A `Name` on a **logging** attribute does not name the event — it renames the log entry: + +```csharp +[Event] // event name is still the method name +[Error(Name = "exception")] // this renames the log entry +void FailedToRetrieve(Activity? activity, Exception exception); +``` + +The rule is not raised when the exception is not recorded under the OpenTelemetry rules: +`[Event(UseRecordExceptionRules = false)]`, a `[Baggage]` exception parameter, or an exception +parameter excluded from the Activities target (`[ExcludeTargets(Targets.Activities)]`). + +### `TSG2008` — unbounded enumeration + +`[ExpandEnumerable]` with `MaximumValueCount` above 5. Bring it back to the default unless you have +measured the cost. + +### `TSG4002` — auto-increment counter with a measurement + +`[AutoCounter]` — equivalently `[Counter(AutoIncrement = true)]` — must declare no measurement +parameter. The measurement is fixed at 1. + +### `TSG1003` — duplicate method names + +The method name becomes a member on the generated implementation class, so two methods cannot share +one. Rename. + +## Related skills + +`purview-telemetry-quickstart` to get an interface wired up, `purview-telemetry-design` for +structuring interfaces, and `purview-telemetry-migration` for converting existing `ILogger`, +`ActivitySource` or instrument code. diff --git a/.claude/skills/purview-telemetry-migration/SKILL.md b/.claude/skills/purview-telemetry-migration/SKILL.md new file mode 100644 index 00000000..b9a01fad --- /dev/null +++ b/.claude/skills/purview-telemetry-migration/SKILL.md @@ -0,0 +1,81 @@ +--- +name: purview-telemetry-migration +description: Migrate existing ILogger, ActivitySource, or System.Diagnostics.Metrics instrument code to Purview.Telemetry.SourceGenerator interfaces. Use when converting hand-written telemetry to generated telemetry interfaces, or when a user wants to replace ILogger, ActivitySource, or Counter/Histogram/UpDownCounter usage with Purview telemetry. +license: MIT +compatibility: C# projects using Purview.Telemetry.SourceGenerator. +metadata: + author: Purview-Dev + version: "1.0" +--- + +# Migrate to Purview Telemetry Source Generator + +Convert existing telemetry code to generated Purview telemetry interfaces. + +## Primary path: use the IDE refactorings + +The source generator ships with Roslyn code refactorings. Right-click a class containing hand-written telemetry and choose: + +- **Convert ILogger to ILogs** — replaces `ILogger` fields and constructor parameters with a generated logging interface. +- **Convert ActivitySource to ITracing** — replaces `ActivitySource` fields and `StartActivity` calls with a generated tracing interface. +- **Convert Metrics to IMetrics** — replaces `Counter`, `Histogram`, and `UpDownCounter` fields and calls with a generated metrics interface. +- **Convert all telemetry to ITelemetry** — combines all three into one interface when the class uses multiple telemetry types. + +Each refactoring offers scopes: **class**, **document**, **project**, and **solution**. + +## What the refactorings produce + +The generated interface uses attributes from the `Purview.Telemetry` namespace: + +```csharp +using Purview.Telemetry; + +[Logger] +public interface IOrderServiceLogs +{ + [Info] + void OrderPlaced(int orderId, string customerName); +} +``` + +The original class is rewritten to use the interface: + +```csharp +public class OrderService(IOrderServiceLogs logger) +{ + public void PlaceOrder(int orderId, string customerName) + { + logger.OrderPlaced(orderId, customerName); + } +} +``` + +## Manual fallback + +If the refactoring does not cover a call pattern, convert it manually: + +1. Identify the telemetry type (Logging, Activity, Metric). +2. Create a new interface with the matching class-level attribute (`[Logger]`, `[ActivitySource]`, `[Meter]`). +3. Add a method for each distinct operation, using the method-level attribute from the mapping below. +4. Replace the hand-written call with the interface method. +5. Register the interface in DI with `services.Add{InterfaceNameWithoutI}()`. + +## Attribute mapping + +| Hand-written telemetry | Generated attribute | +|---|---| +| `ILogger.LogInformation(...)` | `[Info]` | +| `ILogger.LogDebug(...)` | `[Debug]` | +| `ILogger.LogTrace(...)` | `[Trace]` | +| `ILogger.LogWarning(...)` | `[Warning]` | +| `ILogger.LogError(...)` | `[Error]` | +| `ILogger.LogCritical(...)` | `[Critical]` | +| `ActivitySource.StartActivity(...)` | `[Activity]` | +| `activity.AddEvent(...)` | `[Event]` | +| `activity.AddBaggage(...)` / `SetBaggage(...)` | `[Context]` with `[Baggage]` parameter | +| `activity.SetTag(...)` | `[Context]` with `[Tag]` parameter | +| `Counter.Add(...)` | `[Counter]` or `[AutoCounter]` for `Add(1)` | +| `Histogram.Record(...)` | `[Histogram]` | +| `UpDownCounter.Add(...)` | `[UpDownCounter]` | + +See [references/REFERENCE.md](references/REFERENCE.md) for detailed before/after examples and common conversions. diff --git a/.claude/skills/purview-telemetry-migration/references/REFERENCE.md b/.claude/skills/purview-telemetry-migration/references/REFERENCE.md new file mode 100644 index 00000000..d85eb738 --- /dev/null +++ b/.claude/skills/purview-telemetry-migration/references/REFERENCE.md @@ -0,0 +1,181 @@ +# Migration reference + +Detailed before/after examples for migrating hand-written telemetry to Purview telemetry interfaces. + +## ILogger to generated logging interface + +### Before + +```csharp +using Microsoft.Extensions.Logging; + +public class OrderService(ILogger logger) +{ + public void PlaceOrder(int orderId, string customerName) + { + logger.LogInformation("Placing order {OrderId} for {CustomerName}", orderId, customerName); + } + + public void CancelOrder(int orderId, Exception ex) + { + logger.LogError(ex, "Order {OrderId} cancelled", orderId); + } +} +``` + +### After + +```csharp +using Purview.Telemetry; + +[Logger] +public interface IOrderServiceLogs +{ + [Info("Placing order {OrderId} for {CustomerName}")] + void OrderPlaced(int orderId, string customerName); + + [Error("Order {OrderId} cancelled")] + void OrderCancelled(Exception ex, int orderId); +} + +public class OrderService(IOrderServiceLogs logger) +{ + public void PlaceOrder(int orderId, string customerName) + { + logger.OrderPlaced(orderId, customerName); + } + + public void CancelOrder(int orderId, Exception ex) + { + logger.OrderCancelled(ex, orderId); + } +} +``` + +## ActivitySource to generated tracing interface + +### Before + +```csharp +using System.Diagnostics; + +public class OrderService +{ + static readonly ActivitySource _source = new("OrderService"); + + public void PlaceOrder(int orderId) + { + using var activity = _source.StartActivity("PlaceOrder", ActivityKind.Internal); + activity?.AddEvent(new ActivityEvent("Validated")); + } +} +``` + +### After + +```csharp +using System.Diagnostics; +using Purview.Telemetry; + +[ActivitySource] +public interface IOrderServiceTracing +{ + [Activity] + Activity? PlaceOrder(int orderId); + + [Event] + void Validated(Activity? activity); +} + +public class OrderService(IOrderServiceTracing tracing) +{ + public void PlaceOrder(int orderId) + { + using var activity = tracing.PlaceOrder(orderId); + tracing.Validated(activity); + } +} +``` + +## Metrics to generated metrics interface + +### Before + +```csharp +using System.Diagnostics.Metrics; + +public class OrderService(IMeterFactory meterFactory) +{ + readonly Counter _orders = meterFactory.Create("OrderService").CreateCounter("orders-placed"); + readonly Histogram _latency = meterFactory.Create("OrderService").CreateHistogram("processing-latency-ms"); + + public void PlaceOrder(int orderId, double latencyMs) + { + _orders.Add(1); + _latency.Record(latencyMs); + } +} +``` + +### After + +```csharp +using Purview.Telemetry; + +[Meter] +public interface IOrderServiceMetrics +{ + [AutoCounter] + void OrderPlaced(); + + [Histogram] + void OrderProcessingTime(double latencyMs); +} + +public class OrderService(IOrderServiceMetrics metrics) +{ + public void PlaceOrder(int orderId, double latencyMs) + { + metrics.OrderPlaced(); + metrics.OrderProcessingTime(latencyMs); + } +} +``` + +## Combined telemetry interface + +When a class uses multiple telemetry types, prefer the combined refactoring: + +```csharp +using System.Diagnostics; +using Purview.Telemetry; + +[ActivitySource] +[Logger] +[Meter] +public interface IOrderServiceTelemetry +{ + [Activity] + [Info] + [AutoCounter] + Activity? PlacingOrder(int orderId); + + [Event] + void OrderShipped(Activity? activity, int orderId); + + [Histogram] + void OrderProcessingTime(double latencyMs); +} +``` + +## Common conversions + +| Original code | Generated method signature | +|---|---| +| `logger.LogError(ex, "Failed {OrderId}", orderId)` | `[Error("Failed {OrderId}")] void Failed(Exception exception, int orderId);` | +| `activity.AddEvent(new ActivityEvent("Loaded"))` | `[Event] void Loaded(Activity? activity);` | +| `activity.SetBaggage("tenant", tenantId)` | `[Context] void SetTenant(Activity? activity, [Baggage] string tenantId);` | +| `activity.SetTag("tenant", tenantId)` | `[Context] void SetTenant(Activity? activity, [Tag] string tenantId);` | +| `counter.Add(1, new KeyValuePair("region", region))` | `[AutoCounter] void RequestCompleted([Tag] string region);` | +| `histogram.Record(value, new KeyValuePair("region", region))` | `[Histogram] void RequestDuration(long value, [Tag] string region);` | +| `upDownCounter.Add(1)` | `[UpDownCounter] void Increment();` | diff --git a/.claude/skills/purview-telemetry-multi-targeting/SKILL.md b/.claude/skills/purview-telemetry-multi-targeting/SKILL.md new file mode 100644 index 00000000..d9654ab9 --- /dev/null +++ b/.claude/skills/purview-telemetry-multi-targeting/SKILL.md @@ -0,0 +1,224 @@ +--- +name: purview-telemetry-multi-targeting +description: >- + Use when one Purview.Telemetry.SourceGenerator method should emit several kinds of telemetry at + once - an Activity, a log entry and a metric from a single call. Covers combining [ActivitySource], + [Logger] and [Meter] on an interface, the supported per-method attribute combinations, excluding a + parameter from one target with [ExcludeTargets], return types, and why inference turns off. +license: MIT +compatibility: C# projects using Purview.Telemetry.SourceGenerator. +metadata: + author: Purview-Dev + product: Purview.Telemetry.SourceGenerator + repository: purview-dev/telemetry-sourcegenerator +--- + +# Multi-targeting + +One interface — and one *method* — can generate Activities, logs and metrics together. A single call +then emits all of them, from one set of parameters. + +```csharp +using Purview.Telemetry; + +[ActivitySource("OrderService")] +[Logger] +[Meter] +interface IOrderTelemetry +{ + // Activity + Info log + counter increment, from one call. + [Activity] + [Info] + [AutoCounter] + Activity? ProcessingOrder([Baggage] int orderId, [Tag] string customerName); + + // ActivityEvent + Debug log. + [Event] + [Debug] + void OrderValidated(Activity? activity, decimal amount); + + // Log only. + [Warning] + void OrderRejected(int orderId, string reason); + + // Metric only. + [Histogram] + void OrderProcessingDuration([InstrumentMeasurement] int milliseconds); +} +``` + +```csharp +using var activity = telemetry.ProcessingOrder(123, "Acme Corp"); +// Activity created and started, Info log written, counter incremented by 1. +``` + +## What you may combine + +| Combination | Example | +| --- | --- | +| Activity + Log | `[Activity]` + `[Info]` | +| Activity + Metric | `[Activity]` + `[AutoCounter]` | +| Log + Metric | `[Info]` + `[Histogram]` | +| Activity + Log + Metric | `[Activity]` + `[Info]` + `[AutoCounter]` | +| Event + Log | `[Event]` + `[Debug]` | +| Context + Log | `[Context]` + `[Trace]` | + +**One attribute per family, per method** — more is `TSG1002`: + +- Activities: one of `[Activity]`, `[Event]`, `[Context]`. +- Logging: one of `[Log]`, `[Trace]`, `[Debug]`, `[Info]`, `[Warning]`, `[Error]`, `[Critical]`. +- Metrics: one of `[Counter]`, `[AutoCounter]`, `[Histogram]`, `[UpDownCounter]`, or an observable + variant. + +```csharp +[Activity] +[Event] // TSG1002 +void InvalidMethod(Activity? activity); + +[Counter] +[Histogram] // TSG1002 +void InvalidMethod([InstrumentMeasurement] int value); +``` + +## Inference turns off — and that is the point + +An interface with **more than one** class-level attribute (`[ActivitySource]`, `[Logger]`, `[Meter]`) +disables inference. Every method must then declare its targets explicitly, or be `[Exclude]`d: + +```csharp +[ActivitySource("MyApp")] +[Logger] +[Meter] +interface IMyTelemetry +{ + void ProcessItem(int id); // TSG1001 - no explicit attribute + + [Info] + void ProcessItemLogged(int id); // fine + + [Exclude] + void NotTelemetry(int id); // fine +} +``` + +A single-target interface keeps inference. The alternative — guessing which of three families an +unannotated method meant — would silently emit the wrong telemetry, so the generator refuses. + +## Excluding a parameter from one target + +`[ExcludeTargets(Targets.X)]` on a parameter keeps it out of specific families. Use it when a value +is useful in one place and harmful in another — a verbose message is wasted as a metric tag, and an +internal reference may not belong in Activity baggage: + +```csharp +[ActivitySource("PaymentService")] +[Logger] +[Meter] +interface IPaymentTelemetry +{ + [Activity] + [Info] + [Counter] + Activity? ProcessingPayment( + [Baggage] Guid paymentId, + + [ExcludeTargets(Targets.Metrics)] + string processingMessage, + + [InstrumentMeasurement] + decimal amount, + + [ExcludeTargets(Targets.Activities)] + [Tag] // still in logs and metrics + string internalReference + ); +} +``` + +```csharp +[Flags] +public enum Targets +{ + None = 0, + Activities = 1, + Logging = 2, + Metrics = 4, + All = Activities | Logging | Metrics +} +``` + +Flags combine, so `[ExcludeTargets(Targets.Activities | Targets.Metrics)]` leaves a parameter to +logging alone. + +## Return types + +| Shape | Return | +| --- | --- | +| Activity + anything else | `Activity?` — so the caller can dispose it and pass it to Event/Context methods | +| Log + Metric, no Activity | `void`, or `IDisposable?` for a scoped log | +| Event/Context + Log | `void` | + +```csharp +[Activity] +[Info] +[AutoCounter] +Activity? ProcessingOrder(int orderId); + +[Info] +[AutoCounter] +IDisposable? ProcessingBatch(int batchId); // scoped log + counter + +[Event] +[Debug] +void OrderCompleted(Activity? activity, decimal total); +``` + +Return `Activity?`, not `Activity`: it is null when no listeners are active (`TSG3022`). + +## Patterns worth copying + +Full observability on one call: + +```csharp +[Activity] +[Info] +[AutoCounter] +Activity? ProcessingRequest( + [Baggage] string requestId, + [Tag] string endpoint, + [Tag] string method +); +``` + +Selective parameter routing: + +```csharp +[Activity] +[Info] +[Counter] +Activity? ApiCall( + [Baggage] string traceId, // Activity baggage only + [ExcludeTargets(Targets.Metrics)] string verboseMessage, // Activity + log + [InstrumentMeasurement] + [ExcludeTargets(Targets.Activities | Targets.Logging)] + int callCount, // metrics only + [Tag] string endpoint // all three +); +``` + +## Why bother + +One method definition instead of three call sites; the same parameters feed every family, so they +cannot drift; everything is emitted together; a change lands once; and it is one call rather than +several. + +## Diagnostics you will meet here + +| Diagnostic | Fix | +| --- | --- | +| `TSG1001` | Add an explicit target attribute, or `[Exclude]`. | +| `TSG1002` | One Activity, Logging and Metrics attribute per method. | +| `TSG1006` | `[ExcludeTargets]` names a target the method does not have — remove it, or add the target attribute. | +| `TSG1007` | Exclusions left a target with no valid parameters — adjust them. | + +The `purview-telemetry-diagnostics` skill carries the full `TSG` catalogue. diff --git a/.claude/skills/purview-telemetry-quickstart/SKILL.md b/.claude/skills/purview-telemetry-quickstart/SKILL.md new file mode 100644 index 00000000..1743ffe3 --- /dev/null +++ b/.claude/skills/purview-telemetry-quickstart/SKILL.md @@ -0,0 +1,140 @@ +--- +name: purview-telemetry-quickstart +description: Get started with Purview.Telemetry.SourceGenerator in a C# project. Use when adding the package, creating a first telemetry interface, registering it in DI, or asking how to begin with Purview telemetry. +license: MIT +compatibility: C# projects using Purview.Telemetry.SourceGenerator. +metadata: + author: Purview-Dev + version: "1.0" +--- + +# Quickstart: Purview Telemetry Source Generator + +This skill helps you bootstrap telemetry generation in a C# project using `Purview.Telemetry.SourceGenerator`. + +## Installation + +Add the analyzer package to your project: + +```xml + + all + analyzers + +``` + +Also add runtime dependencies for the telemetry types you use: + +- `System.Diagnostics.DiagnosticSource` for Activities +- `Microsoft.Extensions.Logging.Abstractions` for ILogger +- `System.Diagnostics.Metrics` for metrics (built-in on .NET 6+) + +## Define a telemetry interface + +Create a `public interface` and decorate it with class-level attributes. The generator creates the implementation and a DI registration extension. + +### Single-target examples + +```csharp +using Purview.Telemetry; + +[Logger] +public interface IOrderServiceLogs +{ + [Info] + void OrderPlaced(int orderId, string customerName); + + [Warning] + void OrderNotFound(int orderId); +} +``` + +```csharp +[ActivitySource] +public interface IOrderServiceTracing +{ + [Activity] + Activity? PlacingOrder(int orderId); + + [Event] + void OrderValidated(Activity? activity, int orderId); +} +``` + +```csharp +[Meter] +public interface IOrderServiceMetrics +{ + [Counter] + void OrderPlaced(int itemsInOrder); + + [Histogram] + void OrderProcessingTime(long milliseconds); +} +``` + +### Multi-target example + +One interface can generate Activities, Logging, and Metrics from the same methods: + +```csharp +[ActivitySource] +[Logger] +[Meter] +public interface IOrderServiceTelemetry +{ + [Activity] + [Info] + [AutoCounter] + Activity? PlacingOrder(int orderId, [Baggage] string region); + + [Event] + [Trace] + void OrderProcessed(Activity? activity, long durationMs); + + [Warning] + void OrderFailed(int orderId, Exception exception); +} +``` + +## Register with DI + +The generator creates an extension method named `Add{InterfaceNameWithoutI}()`: + +```csharp +services.AddOrderServiceTelemetry(); +``` + +Inject the interface into your service: + +```csharp +public class OrderService(IOrderServiceTelemetry telemetry) +{ + public void PlaceOrder(int orderId) + { + using var activity = telemetry.PlacingOrder(orderId, "EMEA"); + // ... + telemetry.OrderProcessed(activity, stopwatch.ElapsedMilliseconds); + } +} +``` + +## Register names with OpenTelemetry + +The generator records the generated meter and activity source names in every assembly's metadata via `[assembly: GeneratedTelemetryNames]`. In the project that registers them with OpenTelemetry, opt into the `TelemetryNames` class — it aggregates that project's names with the names recorded by every assembly it references: + +```csharp +// Program.cs or Properties/AssemblyInfo.cs of the host project +[assembly: TelemetryGeneration(GenerateTelemetryNamesClass = true)] +``` + +```csharp +builder.AddServiceDefaults(TelemetryNames.MeterNames, TelemetryNames.ActivitySourceNames); +``` + +Libraries need no configuration: they publish their names through the attribute, and the host picks them up. A project referenced *by* the telemetry owners (an Aspire-style `ServiceDefaults`) cannot aggregate them — generate the class in the host and pass the arrays down. + +## Next steps + +- To migrate existing `ILogger`, `ActivitySource`, or metrics code, use `telemetry-sourcegenerator-migration`. +- For design guidance and best practices, use `telemetry-sourcegenerator-design`. diff --git a/.claude/skills/purview-value-objects-diagnostics/SKILL.md b/.claude/skills/purview-value-objects-diagnostics/SKILL.md new file mode 100644 index 00000000..8d03cf03 --- /dev/null +++ b/.claude/skills/purview-value-objects-diagnostics/SKILL.md @@ -0,0 +1,85 @@ +--- +name: purview-value-objects-diagnostics +description: >- + Use when a Purview.ValueObjects build reports a VO1xxx diagnostic, when deciding whether to + suppress one, or when adding a new analyzer rule to the value-objects source generator and its + AnalyzerReleases tracking files. +metadata: + product: Purview.ValueObjects + repository: purview-dev/value-objects +--- + +# Purview.ValueObjects diagnostics + +`Purview.ValueObjects` ships a Roslyn analyzer and source generator that report the `VO1xxx` rules +below. Every rule is enabled by default. + +Suppress a warning the usual ways — `#pragma warning disable VO1006`, a `NoWarn` entry, or +`dotnet_diagnostic.VO1006.severity = none` in `.editorconfig`. **Errors cannot be downgraded**: they +mark declaration shapes the generator cannot emit code for at all, so silencing one only moves the +failure to the missing member. + +## Core shape rules + +| Rule | Severity | Reported when | Fix | +| --- | --- | --- | --- | +| `VO1001` | Error | A `[Scalar]` or `[ValueObject]` type is not declared `partial`. | Add `partial`. The code fix in `Purview.ValueObjects.SourceGenerator.Refactorings` does it for you. | +| `VO1002` | Error | The value object is nested inside another type. | Move it to its own top-level type; nesting is not supported. | +| `VO1003` | Error | The value object is generic. | Remove the type parameters, or declare one concrete value object per closed type. | +| `VO1004` | Error | A `[Scalar]` type does not declare the configured scalar property. | Declare it, or set `ScalarAttribute.PropertyName` to the one you have. | +| `VO1006` | Warning | A `[Scalar]` type is not a `readonly record struct`. | Prefer `readonly record struct`, so equality, immutability and allocation behaviour match the contract. | +| `VO1007` | Warning | `ValueObjectDeserializationMode.Strict` is set but no `Create` overload exists to re-validate through. | Add the `Create` overload, or use the default `Hydrate` mode. | +| `VO1008` | Error | `[Scalar]` and `[ValueObject]` are both applied to one type. | Pick one: a scalar wraps a single primitive, a value object composes members. | +| `VO1016` | Warning | A value object member is mutable. | Make it `readonly`/`init`-only — a mutable member breaks immutability and makes equality unstable. | +| `VO1022` | Error | A `[Scalar]` type declares a member with the name of the property the generator owns. | Remove the declaration, or use `[Scalar]` without a type argument and own the property yourself. | + +## String normalization rules + +| Rule | Severity | Reported when | Fix | +| --- | --- | --- | --- | +| `VO1023` | Warning | Built-in string normalization is configured but the type implements `OnNormalize` or declares its own `Create`. | Remove the option, or move the normalization into the hook/`Create`. The hand-written path wins either way. | +| `VO1024` | Warning | Built-in string normalization is configured on a non-string scalar or member. | Remove the option; `Trim`/`Casing` apply only to `string`. | +| `VO1025` | Error | `[StringNormalize]` is on a member of a `[Scalar]`, on a type that is neither `[Scalar]` nor `[ValueObject]`, or on a property that is not a value member. | Move it to a string member of a complex `[ValueObject]`; on a scalar set `Trim`/`Casing` on `[Scalar]`. | +| `VO1026` | Error | An author-declared `[assembly: ValueObjectDefaults]` repeats a value already supplied by the packaged targets from `ValueObjectsDefault*` MSBuild properties. | Remove the argument, or set a different value. | +| `VO1027` | Error | A `[Scalar]`/`[ValueObject]` option repeats the effective assembly default. | Remove the option; it repeats the inherited value. | + +Restating an assembly or type default is reported as `VO1026`/`VO1027` so each option has a single source of +truth. Only `[StringNormalize]` remains a per-member override outside that check; a value that changes the +effective configuration still raises `VO1023`/`VO1024` where those rules apply. + +## ZodSharp validation rules + +| Rule | Severity | Reported when | Fix | +| --- | --- | --- | --- | +| `VO1013` | Warning | `OnValidate` is declared but never invoked, because `ZodSchemaMode.InsteadOfHooks` is set. | Remove `OnValidate`, or choose a mode that keeps the hooks (`InAdditionToHooks`). | +| `VO1015` | Error | The ZodSharp `SchemaName` is not a valid C# identifier. | Give it a valid identifier. | + +## Entity Framework rules + +| Rule | Severity | Reported when | Fix | +| --- | --- | --- | --- | +| `VO1009` | Warning | EF mapping is requested but `Microsoft.EntityFrameworkCore` is not referenced. | Add the package reference, or stop requesting EF mapping. | +| `VO1010` | Warning | EF auto-conversion was skipped: the underlying type is not mappable. | Map it by hand with a custom `ValueConverter`. | +| `VO1017` | Warning | EF JSON mapping is requested without the JSON converter. | Register the JSON converter for the value object. | +| `VO1018` | Warning | EF complex mapping cannot convert one of the members. | Simplify the member, or map it explicitly. | +| `VO1019` | Warning | EF complex-type mapping is requested but the project resolves to EF Core 7 or earlier. | Target EF Core 8+, or choose a different `EntityFrameworkMapping`. | +| `VO1021` | Warning | EF key value generation is unavailable for the value object. | Assign keys explicitly rather than relying on store generation. | + +## Retired identifiers — never reused + +`VO1005`, `VO1011`, `VO1012`, `VO1014` and `VO1020` were used during development and withdrawn before +release. No version reports them, and the numbering is intentionally discontinuous. An occurrence of +one of these IDs means stale tooling or a stale suppression: remove it. + +`VO1005` is worth calling out. It was catalogued as an error ("scalar constructor is missing") and +documented as requiring you to declare a constructor. It never had a reporting site, and the +requirement was the **opposite** of how the generator works: when a `[Scalar]` type declares no +constructor taking the underlying type, the generator emits a private one. Nothing ever asked you to +write it. + +## Adding or changing a rule + +Rules are tracked in `src/src/SourceGenerator/AnalyzerReleases.Shipped.md` and +`AnalyzerReleases.Unshipped.md`, which Roslyn's `RS2008` catalogue rule enforces. A new or changed +diagnostic must be recorded in the same change; unshipped entries move into a new +`## Release ` block when that version ships. Never reuse a retired identifier. diff --git a/.claude/skills/purview-value-objects-efcore/SKILL.md b/.claude/skills/purview-value-objects-efcore/SKILL.md new file mode 100644 index 00000000..cb57c121 --- /dev/null +++ b/.claude/skills/purview-value-objects-efcore/SKILL.md @@ -0,0 +1,277 @@ +--- +name: purview-value-objects-efcore +description: >- + Use when persisting Purview.ValueObjects with Entity Framework Core - ConfigureValueObjects, + UseValueObjects, scalar-to-column conversion, complex-type versus JSON mapping, value objects as + keys and foreign keys, query translation, generated key values, migrations, and the VO1009-VO1021 + Entity Framework diagnostics. +metadata: + product: Purview.ValueObjects + repository: purview-dev/value-objects +--- + +# Value objects and Entity Framework Core + +`Purview.ValueObjects` source-generates the EF Core mapping **into the consuming project**, and only +when that project references `Microsoft.EntityFrameworkCore`. The runtime package itself carries no +EF dependency, so a domain assembly stays free of Entity Framework while the persistence assembly +gets the converters, comparers and conventions. + +Everything is opt-in per feature with a three-level opt-out: the `DisableValueObjectsEFGeneration` +MSBuild property, then assembly defaults (the attribute, or the `ValueObjectsDefaultEFMapping`, +`ValueObjectsDefaultGenerateEFConverter`, `ValueObjectsDefaultGenerateEFComparer` and +`ValueObjectsDefaultGenerateEFValueGenerator` properties), then per-type options. + +## Wiring it up + +Two ways, pick one: + +```csharp +// 1. In the context. +protected override void OnModelCreating(ModelBuilder modelBuilder) +{ + modelBuilder.ConfigureValueObjects(); +} +``` + +```csharp +// 2. At registration - no OnModelCreating override needed. +services.AddDbContext(options => + options.UseSqlServer(connectionString).UseValueObjects()); + +services.AddDbContextFactory(options => + options.UseSqlite("Data Source=shop.db").UseValueObjects()); +``` + +`ConfigureValueObjects` is emitted into the `Microsoft.EntityFrameworkCore` namespace — the same +namespace as `ModelBuilder` — so no extra `using` is needed. `UseValueObjects()` registers a +generated `ModelCustomizer` that runs it after `OnModelCreating`, and works for `AddDbContext`, +`AddDbContextFactory`, `AddDbContextPool` and manual construction. + +## What gets mapped + +| Shape | Maps to | Notes | +| --- | --- | --- | +| `[Scalar]` | one column of the underlying primitive | via `{Type}.EF.Converter` + `ValueComparer`; `EmailAddress` is a `TEXT` column | +| `[ValueObject]` (default) | an EF Core complex type — one column per member | EF Core 8+ only; nested scalars convert too | +| `[ValueObject(EFMapping = EntityFrameworkMapping.Json)]` | a single JSON column | a value converter, so it works on every EF Core version | + +The provider-to-model direction always goes through `Hydrate(...)`. **Materialization is a replay +path**: neither `OnValidate` nor a ZodSharp schema runs when a row is read. That matches +`ValueObjectDeserializationMode.Hydrate`, and `Strict` applies to the JSON wire format, not to the +database — validate before persisting, or enforce the invariant in the schema. + +An enum-backed scalar converts through the enum's **integral** type (`ValueConverter`). +Leaving the enum as the provider type makes EF compose its own enum-to-number converter with the +generated one, and the composite loses the provider tolerance that raw-primitive comparisons rely on. + +A plain `enum` property that is not a value object keeps EF Core's own enum mapping, untouched. + +## Querying — no `.Value` + +Because a scalar converts to its primitive column, a predicate compares the value object directly: + +```csharp +EmailAddress email = EmailAddress.Create("demo@example.com"); + +var customers = await db.Customers + .Where(c => c.Email == email) // translates to [email] = @p + .ToListAsync(); +``` + +Complex value objects map as complex types, so their members are queryable: + +```csharp +var orders = await db.Orders + .Where(o => o.Total.Amount > 20m) + .Where(o => o.Total.Currency == CurrencyCode.Create("USD")) + .ToListAsync(); +``` + +A property may also be compared to the **raw underlying value** — `c.Email == "demo@example.com"`, +`m.Id == guid` — because every generated converter accepts either shape. Without that, EF hands the +raw provider value to the converted property's built-in converter, which coerces with +`Convert.ChangeType` and throws for provider types that do not implement `IConvertible` (`Guid`, +`DateTimeOffset`, `TimeSpan`, `DateOnly`, `TimeOnly`) or cannot be converted at all (strings). See +[dotnet/efcore#32030](https://github.com/dotnet/efcore/issues/32030). + +Compiled models (`dotnet ef dbcontext optimize`) keep that tolerance because every generated +converter exposes a `JsonValueReaderWriter`-taking constructor and a `JsonReaderWriter` property, +which is what EF's design-time generator looks for. That detection is an undocumented EF +implementation detail: if it changes, compiled models fall back to the built-in converter and only +raw-primitive comparisons break. + +## Keys, foreign keys and indexes + +A value object key needs no special handling — the converter maps it to its primitive column, and +convention still makes `{Type}Id` the primary key: + +```csharp +sealed class Customer +{ + public CustomerId Id { get; set; } // primary key, stored as uniqueidentifier + public TenantId TenantId { get; set; } // foreign key to Tenant.Id + public Tenant Tenant { get; set; } = default!; +} +``` + +Column facets are configured on the value object property and apply to the converted column, exactly +as for a primitive: + +```csharp +public sealed class TenantConfiguration : IEntityTypeConfiguration +{ + public void Configure(EntityTypeBuilder builder) + { + builder.Property(entity => entity.Id).ValueGeneratedNever(); // when the domain owns the key + builder.Property(entity => entity.Key).HasMaxLength(100).IsRequired(); + builder.HasIndex(entity => new { entity.TenantId, entity.Key }).IsUnique(); + } +} +``` + +The converter is expression-based, so composite indexes, unique constraints and `HasQueryFilter` +behave like their primitive equivalents: + +```csharp +modelBuilder.Entity().HasQueryFilter(invoice => invoice.TenantId == currentTenant.TenantId); +``` + +**Complex types cannot be keys.** An identity spanning two or more members is awkward as a complex +type: either flatten the members onto the entity and put a unique index over them, or store the +value object as JSON and index the derived columns you actually query. + +## Generated key values + +A Guid-backed scalar can generate its own time-ordered keys without a database round trip. Opt in, +register one convention, and pick the ordering the store needs: + +```csharp +[Scalar(GenerateEFValueGenerator = true)] +public readonly partial record struct CustomerId { public Guid Value { get; } } + +protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder) +{ + base.ConfigureConventions(configurationBuilder); + configurationBuilder.UseValueObjectKeyGenerators(); // version 7 + // configurationBuilder.UseValueObjectKeyGenerators(ValueObjectKeyOrdering.SqlServer); +} +``` + +Ordering matters: SQL Server's `uniqueidentifier` compares the trailing six bytes first, so plain +version 7 values are effectively random there and a clustered key fragments. Full detail — the +ordering table, the public `ValueObjectSequentialGuid` helper, and the rules about when EF invokes a +generator — is in [references/key-value-generation.md](references/key-value-generation.md). + +Value generation is Guid-backed scalars only, and requires the EF converter; anywhere else reports +`VO1021`. + +## Value objects in other assemblies + +| Declaring assembly | What it emits | How the consumer discovers it | +| --- | --- | --- | +| References EF Core | a nested `EF` class and an `IEFScalarValueObject`/`IEFComplexValueObject` marker per type | through the marker interfaces | +| Does **not** reference EF Core | nothing EF-related | through the `[Scalar]`/`[ValueObject]` attributes; converters are generated **inline** in the consumer's registry | + +Either way the consuming project's registry maps them, so a shared `EmailAddress` is converted on +your entities without being configured twice. + +A provider assembly that only *defines* value objects and owns no `DbContext` should opt out of its +own registry, so consumers do not get duplicate `ValueObjectEFExtensions`/`ValueObjectModelCustomizer` +types in the `Microsoft.EntityFrameworkCore` namespace: + +```xml + + true + +``` + +A complex value object is discovered across assemblies when it opted into a mapping or a comparer +(including the default `ComplexType` mapping with `GenerateEFComparer = false`). Only one that opted +out entirely — `EFMapping = None` **and** `GenerateEFComparer = false` — is not discovered; configure +that one on the entity by hand. + +## Configuring a property explicitly + +The nested `EF` class is there when you want the registry's work done by hand: + +```csharp +builder.Entity() + .Property(c => c.Email) + .HasConversion(EmailAddress.EF.Converter, EmailAddress.EF.Comparer); + +builder.Entity() + .ComplexProperty(o => o.Total, money => + { + money.Property(m => m.Amount); + money.Property(m => m.Currency).HasConversion(CurrencyCode.EF.Converter, CurrencyCode.EF.Comparer); + }); +``` + +## Opting out + +```csharp +// Per type. +[Scalar(GenerateEFConverter = false, GenerateEFComparer = false)] +public readonly partial record struct InternalCode { } + +[ValueObject(EFMapping = EntityFrameworkMapping.Json)] +public readonly partial record struct Audit { } + +[ValueObject(EFMapping = EntityFrameworkMapping.None, GenerateEFComparer = false)] +public readonly partial record struct Notes { } +``` + +```csharp +// Per assembly. +[assembly: ValueObjectDefaults(EFMapping = EntityFrameworkMapping.Json)] +[assembly: ValueObjectDefaults(GenerateEFConverter = false, GenerateEFComparer = false)] +``` + +```xml + + + true + +``` + +## Schema and migrations + +- A scalar is a **single column** of its primitive, so `dotnet ef migrations add` sees the primitive. + Renaming the value object's property changes no schema; changing the underlying type is a column + type change you review like any other. +- A complex-type-mapped value object is a **set of columns** named after its members; a JSON-mapped + one is a **single JSON column**. Moving between the two is a schema change that usually needs a + data migration to reshape existing values. +- Converters and the key generator convention are provider-independent, so one model serves SQL + Server, PostgreSQL and SQLite; only the primitive column types differ. Keep one migration set per + provider. +- `IDesignTimeDbContextFactory` and model-cache keys that depend on runtime state (a query + filter built from the current tenant, say) must be applied consistently — a cached model is reused + for every context created the same way. + +## Version support + +Compiled and tested against EF Core **7, 9 and 10** (EF Core 7 needs `net8.0`), in +`src/tests/ValueObjects.EFCompatibility.IntegrationTests`, so version-specific API shifts are caught +by this build rather than by a consumer. + +EF Core 8+ is required for **complex type mapping**, the complex-type block in the registry, and the +compiled-model `JsonReaderWriter` members. On EF Core 7, a complex value object reports `VO1019` and +is left unmapped — use `EFMapping = Json` or configure the property manually. Everything else +(converters, the key value generator, the convention, `ValueObjectSequentialGuid`) works on EF Core 7 +and later. + +## Diagnostics + +`VO1009` (EF option set without an EF reference), `VO1010` (underlying type not mappable), `VO1017` +(JSON mapping without the JSON converter), `VO1018` (a complex member cannot be converted), `VO1019` +(complex type on EF Core 7 or earlier) and `VO1021` (value generation unavailable) are the EF rules. +The `purview-value-objects-diagnostics` skill carries the full `VO1xxx` catalogue. + +## Where to look in the repository + +- `src/src/Sample` — a runnable EF Core (SQLite) example. +- `src/tests/ValueObjects.IntegrationTests/Serialization/EntityFrameworkIntegrationTests.cs` — the + integration tests. +- `src/tests/ValueObjects.EFCompatibility.IntegrationTests` — the per-version compatibility suite. diff --git a/.claude/skills/purview-value-objects-efcore/references/key-value-generation.md b/.claude/skills/purview-value-objects-efcore/references/key-value-generation.md new file mode 100644 index 00000000..c12b84f6 --- /dev/null +++ b/.claude/skills/purview-value-objects-efcore/references/key-value-generation.md @@ -0,0 +1,101 @@ +# Generated key values + +Opt a Guid-backed scalar into key generation per type, or once for the assembly: + +```csharp +[Scalar(GenerateEFValueGenerator = true)] +public readonly partial record struct CustomerId +{ + public Guid Value { get; } +} + +// or: +[assembly: ValueObjectDefaults(GenerateEFValueGenerator = true)] +``` + +The generator emits an `EF.ValueGeneratorFactory` on the value object and registers every opted-in +type in the generated `ValueObjectKeyValueGeneratorConvention`. Register that convention once: + +```csharp +protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder) +{ + base.ConfigureConventions(configurationBuilder); + configurationBuilder.UseValueObjectKeyGenerators(); +} + +protected override void OnModelCreating(ModelBuilder modelBuilder) +{ + modelBuilder.ConfigureValueObjects(); +} +``` + +## What the convention guarantees + +- An **unset** key (still `Guid.Empty`) is assigned a time-ordered identifier when the entity is + added, so keys are unique without a database round trip and sort by creation time in stores that + compare identifiers byte by byte. +- A key the **domain already set** is never touched. Entity Framework Core only invokes a generator + while the property holds its CLR default. +- The convention runs at the lowest configuration source, so an entity configuration that owns its + keys — `ValueGeneratedNever()`, an explicit generator, a store-generated default — always wins. + +The identifier is a time-ordered UUID created with base Entity Framework Core APIs only, so the +convention holds for every provider. + +## Key ordering + +Where a store compares the identifier's sixteen bytes in order — PostgreSQL, SQLite, MySQL, and +non-clustered SQL Server keys — version 7 ordering is what you want. SQL Server's `uniqueidentifier` +compares the **trailing six bytes first**, so plain version 7 values are effectively random there and +a clustered key fragments. + +```csharp +// Default: version 7, ascending in plain byte order. +configurationBuilder.UseValueObjectKeyGenerators(); + +// SQL Server: the timestamp moves into the trailing six bytes, which SQL Server compares first. +configurationBuilder.UseValueObjectKeyGenerators(ValueObjectKeyOrdering.SqlServer); +``` + +| Ordering | Timestamp location | Ascends by creation time in | Well-formed version 7 UUID | +| --- | --- | --- | --- | +| `ValueObjectKeyOrdering.UuidV7` (default) | bytes 0-5 | PostgreSQL, SQLite, MySQL, non-clustered SQL Server keys | Yes | +| `ValueObjectKeyOrdering.SqlServer` | bytes 10-15 | SQL Server's `uniqueidentifier` ordering | No — a version 4 UUID | + +Both orderings produce unique identifiers in process, keep the domain's own value when it set one, +and start from a random value so nothing leaks about the sequence. + +Which bytes carry the timestamp is a **store** concern, so the ordering is chosen where the +convention is registered — in the persistence project, never on the value object. + +## Minting a key in application code + +`ValueObjectSequentialGuid` is public, in the `Microsoft.EntityFrameworkCore` namespace, so +application code — including code in another assembly — can mint the identifier it wants an entity to +carry, before the round trip that would otherwise assign one: + +```csharp +// The same value the convention would have generated, created where the domain needs it. +var customerId = CustomerId.Create(ValueObjectSequentialGuid.NewGuid()); +var customer = Customer.Create(customerId, tenantId, email, "Contoso"); +``` + +Because Entity Framework Core only invokes a generator while the property still holds its CLR +default, the key the application set is persisted as-is. + +| Member | Purpose | +| --- | --- | +| `NewGuid()` / `NewGuid(DateTimeOffset)` | Creates a version 7 identifier, from now or a given creation time. | +| `NewSqlServerGuid()` / `NewSqlServerGuid(DateTimeOffset)` | Creates a SQL Server-ordered identifier. | +| `TryGetTimestamp(Guid, out DateTimeOffset)` | Reads the creation time out of a version 7 identifier; false for any other shape. | +| `TryGetSqlServerTimestamp(Guid, out DateTimeOffset)` | Reads the creation time out of a SQL Server-ordered identifier. | +| `MinSqlServerGuidFor(DateTimeOffset)` / `MaxSqlServerGuidFor(DateTimeOffset)` | Inclusive bounds for a creation time, so `id >= Min… && id <= Max…` is an index seek. | + +## Limits + +- **Guid-backed scalars only**, and the Entity Framework converter must be enabled. Requesting it + anywhere else reports `VO1021` and emits no generator. +- A value object declared in an assembly that does not reference Entity Framework Core still gets a + generator: the consuming project emits it alongside the inline converters. +- A generated key value generator is typed as the **value object**, not its provider value, because + Entity Framework Core assigns what a generator returns straight to the property. diff --git a/.claude/skills/purview-value-objects-zodsharp/SKILL.md b/.claude/skills/purview-value-objects-zodsharp/SKILL.md new file mode 100644 index 00000000..ad826848 --- /dev/null +++ b/.claude/skills/purview-value-objects-zodsharp/SKILL.md @@ -0,0 +1,325 @@ +--- +name: purview-value-objects-zodsharp +description: >- + Use when validating Purview.ValueObjects with Purview.ZodSharp - the [ZodSchema] integration that + routes Create through a generated schema, ZodSchemaMode, the OnZodValidate refinement hook, custom + rules and [ZodRule] attributes on scalars, schema-first Z.* validation, DTO validation, and mapping + ZodException to ASP.NET Core Problem Details. +metadata: + product: Purview.ValueObjects + repository: purview-dev/value-objects +--- + +# Validating value objects with ZodSharp + +[Purview.ZodSharp](https://www.nuget.org/packages/Purview.ZodSharp) is a C# port of +[Zod](https://github.com/colinhacks/zod). It complements `Purview.ValueObjects` by splitting the +responsibility: **the value object owns the invariant, ZodSharp owns the rule definition and the +result shape**. + +Reference the package explicitly when you use its types — do not rely on transitive flow. The +ZodSharp source generator is active in any project that references the package. + +```text +dotnet add package Purview.ZodSharp +``` + +Four ways to use it, in rough order of how often you want them: + +1. **Generator-integrated** — `[Scalar]` + `[ZodSchema]`, and `Create` validates through the schema. +2. **Generated validators** — `[ZodSchema]` + DataAnnotations emits a zero-allocation `{Type}Schema`. +3. **Schema-first** — hand-build `Z.String()` / `Z.Number()` / `Z.Enum()` and construct through `Create`. +4. **DTO-first** — validate the request shape, then map onto value objects. + +## 1. Generator-integrated validation + +Annotate a value object with **both** `[Scalar]`/`[ValueObject]` **and** `[ZodSchema]`, and the +value-object generator routes the generated `Create` through the ZodSharp schema — no wiring: + +```csharp +using System.ComponentModel.DataAnnotations; +using Purview.ValueObjects.Serialization; +using ZodSharp; + +[Scalar] +[ZodSchema] +public readonly partial record struct EmailAddress +{ + [EmailAddress] + [StringLength(254, MinimumLength = 3)] + public string Value { get; } + + static partial void OnNormalize(ref string value) => value = value?.Trim().ToLowerInvariant()!; +} + +EmailAddress.Create("not-an-email"); // throws ZodException via EmailAddressSchema.Validate +``` + +`Create` constructs the instance, calls `{Type}Schema.Validate(instance)` and throws `ZodException` +on failure. **`Hydrate` stays replay-safe** — no schema, no hooks. +`ValueObjectDeserializationMode.Strict` deserializes through `Create`, so it picks the schema up too. + +`[ZodSchema]` reads DataAnnotations: `[Required]`, `[StringLength]`, `[Range]`, +`[RegularExpression]`, `[EmailAddress]`, `[AllowedValues]`, `[DeniedValues]`. It supports classes, +structs and records. + +### ZodSchemaMode + +| Mode | Behaviour | +| --- | --- | +| `InAdditionToHooks` (default) | the schema runs **and** `OnValidate` runs | +| `InsteadOfHooks` | the schema runs **instead of** `OnValidate`; `OnNormalize` still runs first | + +Leaving an `OnValidate` in place under `InsteadOfHooks` makes it unreachable — that is `VO1013`. + +### The automatic scalar form + +`[Scalar]` / `[Scalar(typeof(T))]` have the value-object generator declare the underlying +property, so a property-attached DataAnnotation has no host. For those types use Zod-native +**type-level** rules (`[RequiredZod]`, `[ZodRule(typeof(...))]`), which ZodSharp reads from the type +and adapts to the scalar's underlying value — or keep the manual `[Scalar]` form when you need +property-level DataAnnotations. Purview.ZodSharp 2.0.2+ generates `{Type}Schema` from the attribute +itself, so the automatic form validates through `Create` exactly like the manual one. + +A nullable scalar (`Nullable = true`, or a `T?` value type) round-trips JSON `null`, so its schema +and any string rule must be null-tolerant: use the shipped `[NullOrNonWhiteSpace]`, which accepts +`null` but rejects whitespace, rather than `[RequiredZod]`, which always rejects `null`. + +### `[ZodSchema]` options + +- `SchemaName` — overrides the generated class name (default `{TypeName}Schema`); the DI adapter + becomes `{SchemaName}Validator`. ZodSharp applies any non-empty value **verbatim**, including + whitespace, so an unusable name is reported as `VO1015` rather than silently falling back. +- `CustomValidationMethodName` — a static async method the generated validator's `ValidateAsync` + awaits after the synchronous rules pass (default `CustomValidationAsync`). + +## The `OnZodValidate` refinement hook + +For rules DataAnnotations cannot express — cross-member invariants, allowed domains, state checks — +implement the partial hook the ZodSharp generator declares: + +```csharp +[Scalar] +[ZodSchema] +public readonly partial record struct CorporateEmail +{ + [EmailAddress] + public string Value { get; } + + static partial void OnNormalize(ref string value) => value = value?.Trim().ToLowerInvariant()!; + + partial void OnZodValidate(RefineCtx context) + { + if (!context.Value.Value.EndsWith("@contoso.com", StringComparison.Ordinal)) + context.AddIssue("invalid_domain", "Corporate emails must use the contoso.com domain.", [nameof(Value)]); + } +} +``` + +Facts worth knowing: + +- The hook is declared **and invoked by the ZodSharp generator**, inside `{Type}Schema.Validate`, so + it runs for every entry point: `Validate`, `Parse`, the DI adapter, `IValidateOptions`, the + generated `Create`, and `Strict` deserialization. `Hydrate` never validates. +- Because it belongs to the schema, `{Type}Schema.Validate(instance)` reports exactly what `Create` + reports. +- The type and every containing type must be `partial`, so the generator can declare the hook. + ZodSharp reports `ZODSGEN034` (not partial) and `ZODSGEN035` (malformed signature). +- It is independent of `ZodSchemaMode`: `InsteadOfHooks` skips `OnValidate`, never `OnZodValidate`. +- The old `IEnumerable Validate()` refinement contract is **retired**; ZodSharp + reports `ZODSGEN036` for a member still using it. + +## Custom rules on scalars + +A scalar is validated as a **unit** — its single `Value` *is* the value. ZodSharp ships a validation +attribute for every built-in rule in `ZodSharp.Rules`: + +| Attribute | Rule | Notes | +| --- | --- | --- | +| `[NonSentinel(Message = "…")]` | `NonSentinelRule` | Rejects `Guid.Empty`, the `DateTime`/`DateTimeOffset`/`DateOnly`/`TimeOnly` bounds, and null/empty/whitespace strings. | +| `[Email]` | `EmailRule` | | +| `[E164]` | `E164Rule` | | +| `[UUID(UuidVersion.V4)]` | `UUIDRule` | A rule value with no default is a required constructor argument. | +| `[MinLengthZod(3)]` | `MinLengthRule` | The `Zod` suffix avoids the DataAnnotations clash. Also `[MaxLengthZod]`, `[UrlZod]`, `[PhoneZod]`, `[CreditCardZod]`, `[Base64StringZod]`. | + +Each attribute mirrors its rule's constructor; `Message` and `Code` stay named properties, so an +error code or message can be overridden per use. + +```csharp +using ZodSharp; +using ZodSharp.Rules; + +[Scalar] +[ZodSchema] +[NonSentinel(Message = "AssetId must not be empty.")] +public readonly partial record struct AssetId +{ + public Guid Value { get; init; } +} +``` + +`AssetId.Create(Guid.Empty)` throws a `ZodException` whose error carries the rule's own `Code`, no +structured `Origin`, and an **empty path** — the rule applies to the value object, not a member. +Because it runs inside the schema, `Hydrate` stays replay-safe. + +Writing your own rule attribute, the automatic adapter that lets a rule written against the +underlying value validate the value object, and the `Code`/`Origin` resolution order are in +[references/custom-rules.md](references/custom-rules.md). + +## Schema-first validation + +When you do not want the generator involved, build a schema for the **underlying** value and +construct through `Create`: + +```csharp +using ZodSharp; + +public static class ScalarSchemas +{ + public static readonly IZodSchema EmailSchema = Z.String().Email().Min(3).Max(254); + public static readonly IZodSchema CurrencySchema = Z.String().Regex("^[A-Z]{3}$"); + public static readonly IZodSchema OrderStatusSchema = Z.Enum(); + public static readonly IZodSchema MoneyAmountSchema = Z.Number().Positive(); +} +``` + +ZodSharp validates the raw value **exactly as supplied** — normalization is the value object's job in +`OnNormalize`. So: validate the raw input, then `Create`, which normalizes and wraps it. + +## Validating DTOs before mapping + +```csharp +[ZodSchema] +public sealed partial class RegistrationDto +{ + [Required, StringLength(100, MinimumLength = 2)] + public string Name { get; init; } = string.Empty; + + [Range(13, 120)] + public int Age { get; init; } + + [Required, EmailAddress] + public string Email { get; init; } = string.Empty; + + partial void OnZodValidate(RefineCtx context) + { + if (context.Value.Name.StartsWith("x", StringComparison.OrdinalIgnoreCase)) + context.AddIssue("name", "Name cannot start with 'x'.", [nameof(Name)]); + } +} + +var result = RegistrationDtoSchema.Validate(dto); + +if (result.IsSuccess) +{ + var email = EmailAddress.Create(result.Value.Email); + var money = Money.Create(19.99m, CurrencyCode.Create("USD")); +} +``` + +Async rules go through `CustomValidationMethodName`, naming a +`static ValueTask> Method(T value, CancellationToken)` that the generated +`{Type}SchemaValidator.ValidateAsync` awaits once the synchronous rules pass. + +## Dependency injection + +`ZodSchemaFactory` resolves validators by validated type: + +```csharp +using ZodSharp.Core; + +ZodSchemaFactory factory = new(); + +factory.Register(new EmailAddressSchemaValidator()); // generated adapter +factory.Register(new ZodSchemaValidator(ScalarSchemas.EmailSchema)); // hand-built + +var emailResult = factory.Validate(EmailAddress.Create("demo@example.com")); +``` + +## Error handling + +`ValidationResult` is a struct with `IsSuccess`, `Value` (only on success) and `Errors` +(`ImmutableArray`). Each `ValidationError` carries `Code`, `Message` and `Path`, +plus optional `Origin`, `Category` and size bounds: + +```csharp +foreach (var error in result.Errors) + Console.WriteLine($"{string.Join(".", error.Path)}: {error.Message} ({error.Code}, {error.Origin})"); +``` + +Use `Parse` / `GetValueOrThrow()` to throw instead of inspecting. The value-object layer never +reconstructs codes or messages — it forwards `result.Errors` into a `ZodException`, so a rule's +`Code`, `Message`, `Origin`, `Category` and path arrive intact. + +### ASP.NET Core Problem Details + +`Purview.ZodSharp.AspNetCore` maps a thrown `ZodException` to `HttpValidationProblemDetails`: + +```csharp +builder.Services.AddZodSharpProblemDetails(); +builder.Services.AddProblemDetails(); + +var app = builder.Build(); +app.UseExceptionHandler(); +``` + +Make the value object validate during model binding: + +```csharp +[Scalar( + ZodSchemaMode = ZodSchemaMode.InsteadOfHooks, + DeserializationMode = ValueObjectDeserializationMode.Strict)] +[ZodSchema] +public readonly partial record struct EmailAddress +{ + [Required, EmailAddress] + public string Value { get; } +} + +builder.Services.ConfigureHttpJsonOptions(options => + options.SerializerOptions.Converters.Add(new ScalarJsonConverterFactory())); +``` + +An invalid body now returns `400 application/problem+json` with the structured issues in the `issues` +extension. + +Map error codes to HTTP statuses with `[ErrorType]` on a `static readonly ErrorType` field; the +bundled `ErrorTypeGenerator` emits `Create{Field}(...)` and a `[DoesNotReturn]` `Throw{Field}(...)`. +The `ZODSASP001` analyzer flags a `MessageFormat` placeholder missing from `Parameters` at compile +time. + +## JSON Schema export + +```csharp +var jsonSchema = Z.ToJsonSchema(ScalarSchemas.EmailSchema, new ToJsonSchemaOptions { Title = "Email" }); +``` + +Draft 2020-12, for sharing a contract with TypeScript Zod. + +## Diagnostics + +`VO1013` (unreachable `OnValidate` under `InsteadOfHooks`) and `VO1015` (invalid `SchemaName`) are the +value-object side. ZodSharp's own `ZODSGEN030`-`ZODSGEN043` cover the refinement hook and rule +mapping; `ZODSASP001` covers the ASP.NET Core error types. + +## Testing the dual-generator integration + +Two shapes, and the distinction is load-bearing: + +- **In-memory (unit)** — `src/tests/SourceGenerator.UnitTests` registers the packaged ZodSharp + generator through `ZodSchemaValidationGeneratorTestOptions`, resolving the component types out of + band via `Common/ZodSharpSourceGenerators.cs`. The project copies + `analyzers/dotnet/cs/Purview.ZodSharp.SourceGenerators.dll` beside the test binaries + (`GeneratePathProperty` + `None`/`CopyToOutputDirectory`) and loads it with `Assembly.LoadFrom`. + **Never turn that copy into a ``**: a merged analyzer component carried + `Purview.SourceGeneratorFramework.*` types that then collided (`CS0433`) with the framework + assembly the harness loads. `Common/ZodSharpSourceGeneratorsTests.cs` guards it. +- **Real compile (integration)** — `src/tests/ValueObjects.IntegrationTests` declares `[Scalar]` + + `[ZodSchema]` fixtures and asserts runtime behaviour; both generators run in the real compiler, so + nothing is reflected or registered. + +The loaded generator carries its own framework implementation, so it keeps its own log sink and +CodeWriter scope validation: do not assert on its log entries, and leave `ValidateCodeWriterScopes` +off for that run. + +`src/src/ZodSharpSample` is the runnable example. diff --git a/.claude/skills/purview-value-objects-zodsharp/references/custom-rules.md b/.claude/skills/purview-value-objects-zodsharp/references/custom-rules.md new file mode 100644 index 00000000..43c9fc20 --- /dev/null +++ b/.claude/skills/purview-value-objects-zodsharp/references/custom-rules.md @@ -0,0 +1,130 @@ +# Custom ZodSharp rules for value objects + +## Writing a rule attribute + +A custom rule reaches a value object as a `[ZodRule]`-mapped attribute, in one of two ways. + +### 1. Map a hand-authored attribute to the rule + +Declare a `ValidationAttribute` and point it at the rule. The open generic form serves both a +primitive member and a scalar: + +```csharp +using ZodSharp.Core; + +// Reads the value object through IScalarValueObject. Implementing IZodRule lets the +// rule own its error identity, so one attribute can report a different code per scalar. +public readonly record struct NoWhitespaceRule(string? Message = null) + : IValidationRule, IZodRule + where TSelf : IScalarValueObject +{ + public const string ErrorCode = "invalid_string"; + public const string MessageFormat = "Value must not contain whitespace."; + + public bool IsValid(in TSelf value) => !value.Value.Any(char.IsWhiteSpace); + + public string GetErrorMessage(in TSelf value) => Message ?? MessageFormat; + + string? IZodRule.Code => ErrorCode; + + string? IZodRule.Origin => "value_object"; +} + +[ZodRule(typeof(NoWhitespaceRule<>))] +[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct | AttributeTargets.Property)] +public sealed class NoWhitespaceAttribute : ValidationAttribute +{ + public string? Message { get; set; } +} +``` + +### 2. Let the generator write the attribute + +Mark the rule with the parameterless `[ZodRule]` marker and ZodSharp emits a `{RuleName}Attribute` in +the rule's namespace. A trailing `Rule` becomes `Attribute`; a name clashing with a +`System.ComponentModel.DataAnnotations` attribute gets a `Zod` suffix: + +```csharp +[ZodRule] // the generator emits NoWhitespaceAttribute +public readonly record struct NoWhitespaceRule(string? Message = null) + : IValidationRule, IZodRule + where TSelf : IScalarValueObject +{ + // ... +} +``` + +The generator runs over the compilation that **declares** the rule, so the marker form suits a rule +in the same project, or in a rules library that references Purview.ZodSharp. + +Requirements the generator enforces: + +- A rule accepting a `code`/`origin` constructor parameter must implement `IZodRule`, or + `ZODSGEN039`. +- A rule should expose `public const string ErrorCode` and `public const string MessageFormat`, or + `ZODSGEN042`. +- `ZODSGEN043` reports a built-in rule that cannot produce a validation attribute. + +## How `Code` and `Origin` resolve + +First match wins: + +1. **Rule-owned** — the rule implements `IZodRule` (`IZodRule.Code` / `IZodRule.Origin`). +2. **Attribute-declared** — `Code`/`Origin` named arguments on the applied attribute. +3. **Mapping** — `[ZodRule(typeof(X), Code = "…", Origin = "…")]` on the attribute type. +4. **Default** — `validation_failed`, no origin. + +The value-object layer never reconstructs codes or messages. It calls +`{Type}Schema.Validate(instance)` and forwards `result.Errors` into a `ZodException`, so `Code`, +`Message`, `Origin`, `Category` and path arrive intact. + +## Reusing a rule written against the underlying value + +A rule written against the underlying value — `NonSentinelRule` — validates *that value*, not +the value object. Closing it with the scalar type (`NonSentinelRule`) compiles but **always +passes**, because the sentinel check only knows the primitive. + +The value-object generator emits `ScalarRuleAdapter` into every project that +references both `Purview.ValueObjects` and `Purview.ZodSharp`: + +```csharp +internal readonly record struct ScalarRuleAdapter(TRule Rule) : IValidationRule + where TSelf : IScalarValueObject + where TRule : IValidationRule +{ + public bool IsValid(in TSelf value) => Rule.IsValid(value.Value); + + public string GetErrorMessage(in TSelf value) => Rule.GetErrorMessage(value.Value); +} +``` + +**Do not declare it yourself.** A project that already declares its own copy — the guidance before +the generator emitted it — is detected and the generated copy is skipped, so both keep compiling. + +ZodSharp applies the adapter automatically when a rule is applied to a `[Scalar]` type, so the common +case needs no extra code. The built-in `[NonSentinel]` is exactly this shape: + +```csharp +using ZodSharp; +using ZodSharp.Rules; + +[Scalar] +[ZodSchema] +[NonSentinel(Message = "UserId must not be empty.")] +public readonly partial record struct UserId +{ + public Guid Value { get; init; } +} +``` + +The generator closes `NonSentinelRule<>` with the underlying `Guid` and wraps it in +`ScalarRuleAdapter>`, so the rule runs against the value object +with an empty path, and the **wrapped** rule owns the reported `Code` (the built-in rules report no +structured `Origin`). One attribute serves every scalar backed by the same primitive. + +The runnable version is `src/src/ZodSharpSample/NonSentinelModels.cs`, and the fixtures in +`src/tests/ValueObjects.IntegrationTests/Serialization/ZodSchemaRuleModels.cs` cover rule +`Code`/`Origin` and the empty path end to end. + +See ZodSharp's [Custom Rules](https://purview.dev/docs/zodsharp/custom-rules/) for the rule contract +and the full list of shipped attributes. diff --git a/.claude/skills/purview-value-objects/SKILL.md b/.claude/skills/purview-value-objects/SKILL.md new file mode 100644 index 00000000..a0e6e2fd --- /dev/null +++ b/.claude/skills/purview-value-objects/SKILL.md @@ -0,0 +1,263 @@ +--- +name: purview-value-objects +description: >- + Use when modelling domain values with Purview.ValueObjects - scalar, complex or contextual value + objects, typed identifiers, the Create/Hydrate split, OnNormalize/OnValidate hooks, built-in string + normalization, assembly-level ValueObjectDefaults, JSON deserialization modes, or deciding where an + invariant belongs. +metadata: + product: Purview.ValueObjects + repository: purview-dev/value-objects +--- + +# Purview value objects + +`Purview.ValueObjects` source-generates the plumbing for value objects: factories, equality, +comparison, formatting, parsing and JSON. You declare the shape and the invariants; the generator +emits the rest. + +Three shapes, and the choice is forced by what the value *is*: + +| Attribute | Use for | Declaration | +| --- | --- | --- | +| `[Scalar]` / `[Scalar]` | one primitive with a name and rules (ids, codes, emails) | `readonly partial record struct` | +| `[ValueObject]` | a small fixed group of members that travel together | `partial record` / `readonly partial record struct` | +| `IContextualValueObject` | a value whose validity depends on the owner's current state | a `[Scalar]` that also implements the interface | + +All three must be **top-level** and **partial**, and none may be generic. Nesting is `VO1002`, +generics are `VO1003`, a missing `partial` is `VO1001`. The `purview-value-objects-diagnostics` +skill carries the full rule list. + +## The `Create` / `Hydrate` split + +This is the single most important thing to get right. Every value object gets both: + +- **`Create(value)`** — the strict path. Runs `OnNormalize`, then `OnValidate`, then constructs. + Use it for command input, user input, parsing, and anything crossing a trust boundary. +- **`Hydrate(value)`** — the reconstruction path. Constructs without validating. Use it for + persisted state, event replay and deserialization, where validation already happened and + re-running it would reject historical data that was legal when it was written. +- **`TryCreate(value, out result)`** — `Create` without the throw; returns `false` on failure. + +| Path | Behaviour | +| --- | --- | +| `Create(...)` | Throws — the hook's exception, or `ZodException` when a ZodSharp schema is generated for the type. | +| `TryCreate(...)` | Returns `false` instead of throwing. | +| `Hydrate(...)` | Never validates, never normalizes. | + +Never make `Hydrate` validate "for safety". Replay paths exist precisely because yesterday's rules +are not today's. + +## Scalar value objects + +```csharp +[Scalar] +public readonly partial record struct EmailAddress +{ + public string Value { get; } + + static partial void OnNormalize(ref string value) => value = value?.Trim().ToLowerInvariant()!; + + static partial void OnValidate(string value) + { + if (string.IsNullOrWhiteSpace(value)) + throw new ArgumentException("Email is required.", nameof(value)); + + if (!value.Contains('@', StringComparison.Ordinal)) + throw new ArgumentException("Invalid email format.", nameof(value)); + } +} +``` + +- Declare the scalar property yourself (`[Scalar]`), or let the generator own it (`[Scalar]`). + With `[Scalar]` you must **not** declare a member of that name — that is `VO1022`. +- The default property name is `Value`; `ScalarAttribute.PropertyName` changes it. A `[Scalar]` type + with no matching property is `VO1004`. +- Prefer `readonly record struct`. Anything else is `VO1006`, because equality, immutability and + allocation behaviour stop matching the contract. +- You do not need to declare the private constructor. The generator emits one. + +### Built-in string normalization + +Trim and casing are common enough to configure rather than hand-write: + +```csharp +[Scalar(Trim = true, Casing = StringCasing.LowerInvariant)] +public readonly partial record struct EmailAddress { } + +[ValueObject] +public readonly partial record struct Contact +{ + [StringNormalize(Trim = true)] + public string Email { get; init; } + + public string Name { get; init; } +} +``` + +Trim runs first, then casing, then validation — and only inside the generated `Create`. Casing is +invariant-culture only, deliberately: a canonical form that depends on the ambient thread culture is +not canonical. A hand-written `OnNormalize` or `Create` wins and the option is ignored (`VO1023`); +the option on a non-string is ignored (`VO1024`); restating a value the assembly default already sets +is reported as redundant (`VO1026`/`VO1027`). `[StringNormalize]` itself only belongs on a complex value +object member — on a `[Scalar]` or any other type it is the error `VO1025`, and MSBuild can supply the +assembly defaults with `ValueObjectsDefaultTrim` / `ValueObjectsDefaultCasing`. + +## Complex value objects + +```csharp +[ValueObject] +public sealed partial record UserDetails(Guid Id, string? DisplayName, bool IsActive = true) +{ + static partial void OnNormalize(ref Guid id, ref string? displayName, ref bool isActive) + { + if (!isActive) + displayName = null; + } + + partial void OnValidate(Guid id, string? displayName, bool isActive) + { + if (id == Guid.Empty) + throw new ArgumentException("Id must be a valid GUID.", nameof(id)); + } +} +``` + +Normalize every component together, before validation, so cross-member canonicalization is possible. +Keep members `readonly`/`init`-only — a mutable member is `VO1016` and makes equality unstable. On a +`struct`, declare `OnValidate` as `readonly` when it does not mutate; the generator mirrors the +modifier. + +## Contextual value objects + +When validity depends on the owning instance's current state — a state machine, a cross-field rule +that needs the aggregate — implement `IContextualValueObject`: + +```csharp +[Scalar] +public readonly partial record struct OrderStatus + : IContextualValueObject +{ + public OrderStatusCode Value { get; } + + public static OrderStatus Create(OrderStatusCode value, in ValueObjectContext context) + { + var current = context.Owner.Status.Value; + + return IsValidTransition(current, value) + ? new(value) + : throw new InvalidOperationException($"Invalid transition {current} -> {value}."); + } +} +``` + +`ValueObjectContext` carries `Owner`, `MemberName` and an optional `Reason`. Keep the +contextual `Create` deterministic and side-effect free, and keep plain `Hydrate` available so replay +does not fail on historical transitions. + +## Where an invariant belongs + +| Concern | Lives in | +| --- | --- | +| Primitive format, canonicalization | `OnNormalize` / `OnValidate` on the value object | +| Cross-field invariants within the value | `partial void OnValidate(...)` on a `[ValueObject]` | +| Owner lifecycle / state-machine transitions | contextual `Create(TValue, in ValueObjectContext)` | +| Schema rules, DTO validation, API error shapes | ZodSharp — the `purview-value-objects-zodsharp` skill | +| Persistence and query shape | the entity mapping — the `purview-value-objects-efcore` skill | + +Validation must be pure: deterministic, no I/O, no clock, no ambient culture. + +## Standard interfaces + +A scalar mirrors the standard interfaces its underlying type actually implements, so it behaves like +that type in generic code: + +| Interface | Mirrored when | Forwarded member | +| --- | --- | --- | +| `IEquatable` | the underlying type implements it | `Equals(TValue)` | +| `IFormattable`, `ToString(string?)` | the underlying type implements/declares them | `ToString(format[, provider])` | +| `ISpanFormattable` / `IUtf8SpanFormattable` | the underlying type implements them | `TryFormat` | +| `IParsable` / `ISpanParsable` / `IUtf8SpanParsable` | the underlying type implements them | `Parse` / `TryParse` | + +Detection is per type **and** per target framework, so `string` gets parsing but not span formatting +and an enum gets the reverse. Declaring one of an interface's members yourself skips that interface. + +`Parse` goes through `Create` (so it normalizes and validates); `TryParse` goes through `TryCreate`. +`IComparable` and `IComparable` are always implemented, and a scalar always exposes +`CompareTo(TValue)`, because the contract requires it. Numeric/arithmetic interfaces, `IConvertible` +and collection interfaces are deliberately **not** mirrored. + +## JSON and deserialization modes + +Both attributes default to `ValueObjectDeserializationMode.Hydrate`, so a JSON read does not +re-validate. Choose `Strict` only when round-trip fidelity genuinely requires re-running validation +on read — and then make sure a `Create` overload exists to re-validate through, or you get `VO1007`. + +## Assembly-level defaults + +Repeat nothing per type that the assembly can say once: + +```csharp +[assembly: ValueObjectDefaults(Trim = true, Casing = StringCasing.LowerInvariant)] +``` + +Per-type and per-member settings override it. + +## Value objects in a domain model + +Value objects carry identity and invariants; entities and aggregates carry lifecycle. Keep the +dependency graph clean by splitting them: + +| Project | References | Contains | +| --- | --- | --- | +| Domain (`MyApp.Core`) | `Purview.ValueObjects`, optionally `Purview.ZodSharp` | Value objects, entities/aggregates, domain services. **No Entity Framework.** | +| Persistence (`MyApp.Persistence`) | EF Core, the domain project | `DbContext`, entity configuration, `ConfigureValueObjects()`, migrations | + +A domain project with no EF reference gets no EF members generated into it. That is the point: the +*consuming* project discovers the value objects from their attributes and generates the converters +into the persistence assembly, so no EF code leaks into the domain. + +**Typed identifiers.** Make every identity a scalar value object, so a `CustomerId` can never be +passed where an `OrderId` is expected: + +```csharp +// Domain project - no Entity Framework reference. +[Scalar] +public readonly partial record struct CustomerId +{ + public Guid Value { get; } +} + +public sealed class Customer +{ + Customer(CustomerId id, EmailAddress email) => (Id, Email) = (id, email); + + public CustomerId Id { get; } + + public EmailAddress Email { get; private set; } + + public static Customer Create(CustomerId id, EmailAddress email) => new(id, email); +} +``` + +Entities beside them are ordinary classes: private constructor, static `Create` factory that +validates, members typed as value objects rather than primitives. The factory is the command +boundary; mutation methods enforce invariants spanning members. + +## Queryability + +Primitive-backed scalars are the most query-friendly shape — a provider compares the value object +directly. A scalar wrapping a complex CLR type keeps its invariants and serialization, but a deep +predicate through `.Value` may not translate to SQL. Do not assume +`aggregate.ComplexScalar.Value.Child.Prop` is translatable; if you need to filter on it, expose a +separately mapped mirror property derived from canonical state, and test the exact predicate. + +## Checklist for a new value object + +1. Shape: scalar, complex, or contextual. +2. Normalization rules per member (hand-written hook, or configured trim/casing). +3. Validation rules and the exception each one throws. +4. Whether anything constructs it from storage — if so, it uses `Hydrate`. +5. Deserialization mode, if not the default. +6. Persistence shape, if it is stored. +7. Queryability, if it is filtered on. diff --git a/.claude/skills/purview-zodsharp-aspnetcore/SKILL.md b/.claude/skills/purview-zodsharp-aspnetcore/SKILL.md new file mode 100644 index 00000000..a11c2587 --- /dev/null +++ b/.claude/skills/purview-zodsharp-aspnetcore/SKILL.md @@ -0,0 +1,242 @@ +--- +name: purview-zodsharp-aspnetcore +description: >- + Use when wiring Purview.ZodSharp into ASP.NET Core or any DI host - ProblemDetails from a + ValidationResult or a thrown ZodException, minimal-API endpoint validation, registering + IZodSchemaFactory with AddZodSharp or AddZodSharpFactory, validating options objects with + IValidateOptions, and mapping error codes to HTTP statuses with ErrorType. +license: MIT +metadata: + product: Purview.ZodSharp.AspNetCore + repository: purview-dev/zodsharp +--- + +# ASP.NET Core and dependency injection + +`Purview.ZodSharp.AspNetCore` turns failed validation into standard `ProblemDetails` / +`HttpValidationProblemDetails` payloads **without losing the structured issues**, and registers +schema resolution into DI. + +```bash +dotnet add package Purview.ZodSharp.AspNetCore +``` + +## ProblemDetails from a result + +```csharp +using ZodSharp.AspNetCore; + +var result = BasketSchema.Validate(basket); + +if (!result.IsSuccess) +{ + var problem = result.ToHttpValidationProblemDetails(); + + return Results.ValidationProblem( + problem.Errors, + extensions: new Dictionary { ["issues"] = problem.Extensions["issues"] }); +} +``` + +| Member | Produces | +| --- | --- | +| `ToHttpValidationProblemDetails(result, statusCode = 400)` | `HttpValidationProblemDetails`; paths flattened to dotted keys (`user.email`, array indexes as `[0]`) | +| `ToValidationProblemDetails(result, statusCode = 400)` | `ValidationProblemDetails` | + +Both **throw `InvalidOperationException` when the result is successful** — they are failure +converters, not general mappers. The structured metadata survives in the `issues` extension as a +`ValidationIssue[]`: + +```csharp +public sealed class ValidationIssue +{ + public required string Code { get; init; } + public string? Category { get; init; } + public string? Origin { get; init; } + public int? Minimum { get; init; } + public int? Maximum { get; init; } + public bool? Inclusive { get; init; } + public required string[] Path { get; init; } + public required string Message { get; init; } + public IReadOnlyDictionary? Parameters { get; init; } +} +``` + +## Minimal APIs + +```csharp +// Validate the bound DTO automatically - needs AddZodSharp to have registered the validator. +app.MapPost("/users", (UserDto dto) => dto) + .WithZodSharpValidation(); + +// Or validate in the handler and return the IResult directly. +app.MapPost("/users", (UserDto dto) => +{ + var result = UserDtoSchema.Validate(dto); + return result.IsSuccess ? TypedResults.Ok(result.Value) : result.ToValidationProblem(); +}); +``` + +`WithZodSharpValidation()` adds an endpoint filter that validates the first bound argument of type +`T` against the `IZodSchemaFactory` registered by `AddZodSharp`/`AddZodSharpFactory`. On failure it +returns the same payload as `ToHttpValidationProblemDetails()`; on success it passes through. + +## Thrown `ZodException` + +A `ZodException` from `Parse`, `GetValueOrThrow()`, or a value object's generated `Create` under +strict deserialization maps the same way: + +```csharp +catch (ZodException ex) +{ + return Results.ValidationProblem(ex.ToHttpValidationProblemDetails().Errors); +} +``` + +Or handle it globally: + +```csharp +builder.Services.AddZodSharpProblemDetails(); + +var app = builder.Build(); +app.UseExceptionHandler(); +``` + +`AddZodSharpProblemDetails(configure?, problemDetails?)` registers `ZodExceptionHandler`, calls +`services.AddProblemDetails(problemDetails)`, and configures `ZodProblemDetailsOptions`: + +- `ErrorTypeRegistry Registry` — resolves codes to `ErrorType`s; defaults to `ErrorTypeRegistry.Default`. +- `bool FormatMessages` — format messages from the matched `ErrorType.MessageFormat`. +- `Func, int>? StatusCodeSelector` — total control of the status code. + +> It does **not** register `IZodSchemaFactory`. Pair it with `AddZodSharp` (or the core +> `AddZodSharpFactory`) when you also want DI validator resolution. + +## Error codes to HTTP statuses + +`ErrorType`, the `[ErrorType]` attribute, the generator that emits `Create`/`Throw` helpers and the +`ZODSASP001`–`ZODSASP003` analyzers all ship in the **core** package and need no ASP.NET Core +dependency. The AspNetCore package adds `ErrorTypeRegistry` and the ProblemDetails mapping on top. + +```csharp +public static partial class ConcurrentErrorType +{ + [ErrorType] + public static readonly ErrorType SaveFailed = new( + Code: "aggregate_save_failed", + Category: "invalid_value", + Description: "The aggregate could not be saved.", + HttpStatus: 409, + MessageFormat: "Aggregate '{AggregateId}' (of type {AggregateType}) failed to save", + Parameters: + [ + new("AggregateId", typeof(string)), + ErrorType.Param("AggregateType"), + ]); +} + +ErrorTypeRegistry.Default.Register(ConcurrentErrorType.SaveFailed); +``` + +`HttpStatus` lives on `ErrorType` purely for convenience — the core library never reads it; only the +ASP.NET Core mapping does. `Category` is a broad grouping that can span many specific codes (code +`invalid_tenant_id`, category `invalid_value`); the generated helpers copy it onto each +`ValidationError` and it surfaces on the serialized `ValidationIssue`. + +Marking the field `[ErrorType]` and the containing class `partial` gets you strongly typed helpers, +one parameter per declared entry: + +```csharp +var error = ConcurrentErrorType.CreateSaveFailed("agg-123", "Invoice"); +ConcurrentErrorType.ThrowSaveFailed("agg-123", "Invoice"); + +var detailed = ConcurrentErrorType.CreateSaveFailed( + "agg-123", "Invoice", + path: ["order", "items", "[0]"], + origin: "collection", minimum: 1, maximum: 10, inclusive: true); +``` + +`Create` builds a typed `ErrorTypeParameters` (validated against the declared types, exposed through +`ValidationError.Parameters`) and sets the message from `ErrorType.FormatMessage`, so +`error.Message` already reads the formatted text. + +Mapping rules: + +- **Status** — the highest matched `ErrorType.HttpStatus` wins; unmapped codes fall back to `400`. + `StatusCodeSelector` overrides everything. +- **Title / Type / Detail** — from the highest-status matched `ErrorType`, otherwise defaulted. +- **Message** — named placeholders are substituted from `ValidationError.Parameters`. A placeholder + with no matching value is **left as-is**, so a templating gap stays visible rather than silently + disappearing. `ZODSASP001` warns at compile time when a placeholder is not declared in `Parameters`. +- **Parameters** — surfaced per-issue in `issues`, and merged (camel-cased) into the top-level + extensions for client correlation. + +`ToHttpValidationProblemDetails` / `ToValidationProblemDetails` also accept an `ErrorTypeRegistry` or +a `Func` for on-demand mapping. + +## Registering the factory + +`IZodSchemaFactory` (`ZodSharp.Core`) resolves validators by type: + +| Member | Behaviour | +| --- | --- | +| `Resolve()` | the validator, or `null` | +| `ResolveRequired()` | the validator, or `InvalidOperationException` | +| `Validate(value)` | validate through the registered validator | +| `Register(…)` / `Register(Type, …)` / `TryRegister(…)` / `IsRegistered()` | registration | + +```csharp +builder.Services.AddZodSharp(options => +{ + options.ScanAssemblies.Add(typeof(UserDto).Assembly); + options.ScanAssemblyGraphs.Add(typeof(Program).Assembly); + options.ScanLoadedAssemblies = true; +}); + +// Additive, for modular apps: +builder.Services.AddZodSharpAssembly(typeof(UserDto).Assembly); +builder.Services.AddZodSharpAssemblyGraph(typeof(Program).Assembly); +builder.Services.AddZodSharpLoadedAssemblies(); +``` + +Scanning finds the generator's `[assembly: ZodSchemaGenerated(typeof(…))]` markers and registers each +`{Type}SchemaValidator`. A hand-built schema registers by wrapping: +`factory.Register(new ZodSchemaValidator>(mySchema))`. + +> **`TryAdd` semantics.** The **first** `AddZodSharp`/`AddZodSharpFactory` call wins; later calls — +> including their options and `ConfigureFactory` callbacks — are ignored. State is never overwritten, +> so calling it more than once is safe, and the additive helpers still contribute. + +| Method | Package | Registers | Use when | +| --- | --- | --- | --- | +| `AddZodSharp(options)` | AspNetCore | factory + auto-registered generated validators | an ASP.NET Core app | +| `AddZodSharpAssembly/AssemblyGraph/LoadedAssemblies` | AspNetCore | additive assembly sources | modular apps where deeper layers contribute their own schemas | +| `AddZodSharpFactory(configure)` | core | the factory only | any host; you call `RegisterFromAssembly` yourself | +| `AddZodSharpProblemDetails(…)` | AspNetCore | exception handler + ProblemDetails, **not** the factory | mapping thrown `ZodException`s | +| `AddZodSchemaOptionsValidator(…)` | core | `IValidateOptions` | options validation; needs a factory first | + +## Options validation + +```csharp +builder.Services.AddZodSharpFactory(f => f.RegisterFromAssembly(typeof(UserOptions).Assembly)); +builder.Services.AddZodSchemaOptionsValidator(); + +// or chained: +builder.Services + .AddOptions() + .Bind(configuration.GetSection("User")) + .AddZodSchemaValidator() + .ValidateOnStart(); // fail at startup, not first access +``` + +`MissingValidatorBehavior` decides what happens with no validator registered for `T`: +`Throw` (default — `ResolveRequired()`, so a missing schema is loud rather than a silent skip) or +`Ignore` (passes through as success). + +The generator also auto-generates `IValidateOptions` for types whose names end in configurable +suffixes — see the `purview-zodsharp-source-generator` skill. + +## Related skills + +`purview-zodsharp-core` for the runtime API, `purview-zodsharp-source-generator` for the compile-time +validators this resolves, and `purview-zodsharp-diagnostics` for `ZODSASP*`. diff --git a/.claude/skills/purview-zodsharp-core/SKILL.md b/.claude/skills/purview-zodsharp-core/SKILL.md new file mode 100644 index 00000000..98280dd6 --- /dev/null +++ b/.claude/skills/purview-zodsharp-core/SKILL.md @@ -0,0 +1,176 @@ +--- +name: purview-zodsharp-core +description: >- + Use when validating data with Purview.ZodSharp at runtime - picking the right package, building + schemas with the Z factory, Validate/SafeParse/Parse, reading ValidationResult and ValidationError, + composing with Transform/Refine/Pipe/Catch/Default, and how null handling and type coercion work. +license: MIT +metadata: + product: Purview.ZodSharp + repository: purview-dev/zodsharp +--- + +# Purview.ZodSharp core + +A C# port of [Zod](https://github.com/colinhacks/zod): schemas you build fluently, validated without +exceptions, reporting machine-readable issues. + +## Packages + +```bash +dotnet add package Purview.ZodSharp # core, source generator, JSON Schema export +dotnet add package Purview.ZodSharp.SystemTextJson # STJ deserialize-and-validate + schema import +dotnet add package Purview.ZodSharp.NewtonsoftJson # Newtonsoft equivalent +dotnet add package Purview.ZodSharp.AspNetCore # ProblemDetails + DI +``` + +JSON Schema **export** (`Z.ToJsonSchema`) is in the core package; **import** (`Z.FromJsonSchema`) comes +from whichever JSON integration you reference, so import its namespace +(`ZodSharp.JsonSchema.SystemTextJson` or `ZodSharp.JsonSchema.NewtonsoftJson`). + +## First schema + +```csharp +using ZodSharp; + +var nameSchema = Z.String().Min(3).Max(50); +var result = nameSchema.Validate("John"); + +if (result.IsSuccess) + Console.WriteLine(result.Value); +``` + +## Validate, SafeParse, Parse, ValidateAsync + +| Member | Behaviour | +| --- | --- | +| `Validate(value)` | returns `ValidationResult`; **never throws** | +| `SafeParse(value)` | alias of `Validate` | +| `Parse(value)` | returns the validated value, or throws `ZodException` (via `GetValueOrThrow()`) | +| `ValidateAsync(value, ct)` | `ValueTask` wrapper. The pipeline is synchronous; the token is observed before validation and throws `OperationCanceledException` if already cancelled. Genuinely async work only happens in the source generator's custom async validation. | + +Reach for `Validate` by default and `Parse` only where a throw is the right control flow. Exceptions +for expected invalid input are expensive and lose the structured issue list unless you catch. + +## `ValidationResult` + +A `readonly record struct` in `ZodSharp.Core`: + +- `bool IsSuccess` — annotated `[MemberNotNullWhen(true, nameof(Value))]`, so the compiler knows + `Value` is non-null inside the success branch. +- `T? Value` — valid only when `IsSuccess`. +- `ImmutableArray Errors`. + +Factories: `Success(value)`, `Failure(ValidationError)`, `Failure(ImmutableArray)`, +`Failure(IEnumerable)`, and `Merge(lhs, rhs)` — succeeds only if both succeed, and +concatenates the errors otherwise. + +## `ValidationError` + +A `readonly record struct` carrying machine-readable metadata, not just a message: + +| Member | Meaning | +| --- | --- | +| `Code` | `invalid_type`, `too_small`, `too_big`, `invalid_union`, `missing_field`, `unrecognized_key`, `validation_failed`, `refinement_failed`, `transform_error`, … | +| `Message` | human-readable | +| `Path` | `ImmutableArray` — `["user", "email"]`; array indexes are string segments, `"0"` | +| `Origin` | category for size issues: `"string"`, `"array"`, `"collection"` | +| `Minimum` / `Maximum` / `Inclusive` | the bound, for size issues | +| `Parameters` | `IReadOnlyDictionary`; a union failure carries every option error under `"errors"` | + +Build one with +`ValidationError.Create(code, message, path, parameters, origin, minimum, maximum, inclusive)`. + +`ZodException` carries `ImmutableArray Errors`; its `ToString()` renders one line per +error as `"{joinedPath}: {Message} ({Code})"`. + +## The `Z` factory + +| Method | Returns | +| --- | --- | +| `Z.String()` / `Z.Number()` / `Z.Boolean()` / `Z.Null()` / `Z.Date()` / `Z.BigInt()` | the matching `Zod*` schema | +| `Z.Array(elementSchema)` | `ZodArray` | +| `Z.Optional(schema)` (`T : class`) / `Z.Nullable(schema)` (`T : struct`) | `ZodOptional` / `ZodNullable` | +| `Z.Object()` | `ZodObjectBuilder` | +| `Z.Union(params ...)` / `Z.Union(...)` | `ZodUnion` / `ZodTypedUnion` | +| `Z.DiscriminatedUnion(discriminator)` | `ZodDiscriminatedUnionBuilder` | +| `Z.Intersection(left, right)` | `ZodIntersection` | +| `Z.Literal(value)` (`T : IEquatable`) | `ZodLiteral` | +| `Z.Lazy(schemaGetter)` | `ZodLazy` — for recursive schemas | +| `Z.Enum(params string[])` / `Z.Enum()` | `ZodEnum` / `ZodNativeEnum` | +| `Z.Record(valueSchema)` | `ZodRecord` | +| `Z.Tuple(…)` / `Z.Tuple(…)` | `ZodTuple<…>` | +| `Z.ToJsonSchema(schema, options?)` | `JsonSchemaDefinition` | + +`Enum` and `Union` are overloaded — `Enum(params string[])` versus `Enum()`, and +`Union(params …)` versus `Union(…)`. + +```csharp +var userSchema = Z.Object() + .Field("name", Z.String().Min(1)) + .Field("age", Z.Number().Min(0).Max(120).Int()) + .Field("email", Z.String().Email()) + .Build(); +``` + +## The validation pipeline + +Every schema derives from `ZodType` (`ZodSharp.Core`). Two phases: + +1. **`ParseInternal`** — the schema's own type check and traversal: rejecting `null` where not + allowed, coercing, walking objects/arrays/tuples/unions, producing structured failures. +2. **Rules** — on success, the accumulated `IValidationRule` structs run. A failing rule emits + a `ValidationError` with its Zod-compatible code. + +Rules are `readonly record struct`s implementing `IValidationRule` (`bool IsValid(in T value)`, +`string GetErrorMessage(in T value)`) — zero allocation. Each exposes `public const string ErrorCode` +and `MessageFormat`, so a test asserts against the rule rather than a duplicated literal. (A rule +without them is `ZODSGEN042`.) + +`ZodString` also exposes `ValidateSpan(ReadOnlySpan)` and `IsValidSpan(value, out errors)` for +allocation-free string validation; string rules implementing `IStringValidationRule` participate. + +## Composition + +`ZodType` composes by **wrapping**, never mutating. Each of these returns a new schema: + +| Call | Produces | +| --- | --- | +| `.Transform(func)` | `ZodTransform` | +| `.Refine(predicate, message?)` | `ZodRefinement` | +| `.SuperRefine(Action>)` | `ZodSuperRefinement` | +| `.Pipe(schema)` | `ZodPipe` | +| `.Catch(value \| func)` | `ZodCatch` | +| `.Prefault(value)` / `.Default(value)` | `ZodPrefault` / `ZodDefault` | +| `.And(schema)` / `.Or(schema)` | `ZodIntersection` / `ZodTypedUnion` | +| `.Describe("…")` | sets `Description` | + +Because composition lives on the base type, every schema chains all of them. + +## Null and optionality + +Schemas report optionality through the internal `IOptionalSchema`: + +- `IsOptional` — true for `ZodOptional`, `ZodNullable`, `ZodDefault`, `ZodPrefault`. +- `ProvidesValueOnMissing` — true for `ZodDefault` and `ZodPrefault`. Object fields route a missing + value through `Validate(null!)` so the produced value is injected. +- `IAcceptsNull.ValidateNull()` is implemented by the nullable/optional/default/prefault schemas and + `ZodNull`; object-field and union wrappers route `null` to it rather than failing coercion. + +## Type coercion + +Object fields and union options wrap typed schemas, so boxed values out of a +`Dictionary` validate: + +- `null` routes to `IAcceptsNull.ValidateNull()` where supported. +- An exactly-typed value reuses the original box. +- Numeric coercion goes through `IConvertible` in the **invariant** culture, so a boxed `long` + satisfies a `Z.Number()` field. +- A non-nullable value type rejects `null`; anything else falls through to failure. + +## Related skills + +`purview-zodsharp-source-generator` for compile-time `[ZodSchema]` validators (which is what you want +for a DTO), `purview-zodsharp-custom-rules` for writing rules and rule attributes, +`purview-zodsharp-aspnetcore` for ProblemDetails and DI, and `purview-zodsharp-diagnostics` for the +`ZODSGEN`/`ZODSASP` catalogue. diff --git a/.claude/skills/purview-zodsharp-custom-rules/SKILL.md b/.claude/skills/purview-zodsharp-custom-rules/SKILL.md new file mode 100644 index 00000000..06215ccb --- /dev/null +++ b/.claude/skills/purview-zodsharp-custom-rules/SKILL.md @@ -0,0 +1,241 @@ +--- +name: purview-zodsharp-custom-rules +description: >- + Use when writing a custom validation rule for Purview.ZodSharp - implementing IValidationRule and + IStringValidationRule, the ErrorCode/MessageFormat constants convention, IZodRule runtime identity, + attaching a rule with AddRule or a fluent extension, exposing it as a DataAnnotations-style + attribute with [ZodRule], generic rules, and type-level rules on scalar value objects. +license: MIT +metadata: + product: Purview.ZodSharp + repository: purview-dev/zodsharp +--- + +# Custom rules + +A **rule** is a `readonly record struct` (or class) implementing `ZodSharp.Core.IValidationRule`. +Rules run after a schema's type and structural check succeeds; each failing rule adds a +`ValidationError`. + +Rules are first class in two directions: + +- attach one to a schema with the public `AddRule`/`Rule` API, or +- surface it as a `System.ComponentModel.DataAnnotations`-style attribute that the `[ZodSchema]` + generator honours exactly like `[EmailAddress]` or `[Range]`. + +## The contract + +```csharp +namespace ZodSharp.Core; + +public interface IValidationRule +{ + bool IsValid(in T value); + string GetErrorMessage(in T value); +} +``` + +Implement it as a **struct** so validation does not allocate. `IsValid` is called only when the +surrounding schema succeeded and — for a nullable property — the value is not `null`. + +For a **string** rule, also implement `ZodSharp.Core.IStringValidationRule` +(`bool IsValid(ReadOnlySpan)` / `string GetErrorMessage(ReadOnlySpan)`) so the rule +participates in `ZodString.ValidateSpan`/`IsValidSpan` without materialising the input. A rule that +implements only `IValidationRule` still works; it falls back to the string pipeline. + +## `ErrorCode` and `MessageFormat` — not optional in practice + +Every rule **should** expose its error identity as public constants, so code and tests assert against +the rule rather than re-typing literals: + +```csharp +public readonly record struct EmailRule : IValidationRule +{ + public const string ErrorCode = "invalid_string"; + public const string MessageFormat = "Invalid email format: {0}"; + + public string Code => ErrorCode; + + public string GetErrorMessage(in string value) => + string.Format(CultureInfo.CurrentCulture, MessageFormat, value); +} +``` + +- **`ErrorCode`** is the canonical code. `IValidationRule.Code` defaults to `"validation_failed"`; + a rule accepting a per-usage `code` override returns it (falling back to `ErrorCode`) from both + `Code` and `IZodRule.Code`, so every route reports the same effective value. +- **`MessageFormat`** is a `string.Format` template. `{0}` is the offending value; `{1}`, … are + rule-specific arguments. Format with `CultureInfo.CurrentCulture`. +- The constants may be inherited from a base rule class, and **abstract bases are exempt**, so a + shared base can host them for its concrete derivations. + +A source-declared rule missing either constant is reported as **`ZODSGEN042`**. The payoff: + +```csharp +await Assert.That(error.Code).IsEqualTo(EmailRule.ErrorCode); +await Assert.That(error.Message).IsEqualTo( + string.Format(CultureInfo.CurrentCulture, EmailRule.MessageFormat, value)); +``` + +### Runtime identity: `IZodRule` + +The constants are the rule's *static* default. When one attribute must report a different code per +annotated member, implement `IZodRule` and supply code/origin at runtime: + +```csharp +public interface IZodRule +{ + string? Code { get; } // null falls back to the attribute-mapped code + string? Origin { get; } // null falls back to the attribute-mapped origin +} +``` + +The generated code casts to `IZodRule` when reading them, so identity can depend on constructor +arguments. A rule that **accepts** a `code`/`origin` constructor parameter without implementing +`IZodRule` never reaches the reported identity — that is `ZODSGEN039`. + +Code and origin resolve first-match-wins: + +1. the rule, when it implements `IZodRule`; +2. `Code`/`Origin` named arguments on the applied attribute; +3. the `[ZodRule(typeof(X), Code = "…", Origin = "…")]` mapping on the attribute type; +4. default — `validation_failed`, no origin. + +### Message precedence + +1. A `message` argument on the rule (typically a `Message` constructor parameter), when set. +2. The attribute's `ErrorMessage` / `ErrorMessageResourceName` / `ErrorMessageResourceType`, mapped + to a constructor parameter named `message`. +3. `GetErrorMessage(value)`, formatting `MessageFormat`. + +`MessageFormat` is the fallback, not the only message. + +## Writing one + +```csharp +using System.Globalization; +using ZodSharp.Core; + +namespace MyRules; + +/// Rejects strings that contain whitespace. +public readonly record struct NoWhitespaceRule(string? Message = null) : IValidationRule +{ + public const string ErrorCode = "invalid_string"; + public const string MessageFormat = "Whitespace is not allowed in '{0}'."; + + public bool IsValid(in string value) + { + if (value is null) + return false; + + foreach (var character in value) + { + if (char.IsWhiteSpace(character)) + return false; + } + + return true; + } + + public string Code => ErrorCode; + + public string GetErrorMessage(in string value) => + Message ?? string.Format(CultureInfo.CurrentCulture, MessageFormat, value); +} +``` + +It works standalone, and attaches to any schema: + +```csharp +var rule = new NoWhitespaceRule(); +if (!rule.IsValid("John Doe")) + Console.WriteLine(rule.GetErrorMessage("John Doe")); + +var schema = Z.String().Rule(new NoWhitespaceRule("No spaces allowed.")); +``` + +`ZodType.AddRule(IValidationRule)` and the generic `Rule(TRule)` +helper are both public. Give the rule a first-class fluent method with an ordinary extension method on +its schema type, the way the built-in rules are surfaced. + +## Exposing it as an attribute + +Two routes. + +**Map a hand-authored attribute to the rule.** The open generic form serves both a primitive member +and a scalar value object: + +```csharp +[ZodRule(typeof(NoWhitespaceRule<>))] +[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct | AttributeTargets.Property)] +public sealed class NoWhitespaceAttribute : ValidationAttribute +{ + public string? Message { get; set; } +} +``` + +**Or let the generator write it.** Mark the rule with the parameterless `[ZodRule]` and a +`{RuleName}Attribute` is emitted in the rule's namespace — a trailing `Rule` becomes `Attribute`, and +a name colliding with a DataAnnotations attribute takes a `Zod` suffix: + +```csharp +[ZodRule] // emits NoWhitespaceAttribute +public readonly record struct NoWhitespaceRule(string? Message = null) : IValidationRule; +``` + +The generator runs over the compilation that **declares** the rule, so the marker form suits a rule +in the same project, or in a rules library referencing `Purview.ZodSharp`. + +## Generic rules and rule families + +A generic rule closed with the property type lets one attribute serve every member of that shape — +`[ZodRule(typeof(NonSentinelRule<>))]` on a `NonSentinelAttribute` covers `Guid`, `DateTime`, +`string` and the rest. + +`ZodSharp.Rules.NonSentinelRule` is the canonical example: it rejects the framework +default/boundary values an ORM stores to mean "no value" — `Guid.Empty`, +`DateTime.MinValue`/`MaxValue`, the `DateTimeOffset`/`DateOnly`/`TimeOnly` bounds, and +null/empty/whitespace strings. A type with no known sentinel always passes, so the rule never rejects +something it does not understand. Its JSON Schema mapping is exact for `DateOnly`, `TimeOnly`, deterministic +`DateTime` forms, and `DateTimeOffset`; the optional UTC opt-in only narrows the accepted offset (see the JSON +skill). + +```csharp +var schema = Z.Date().AddRule(new NonSentinelRule()); +var result = schema.Validate(DateTime.MinValue); +// result.Errors[0].Code == NonSentinelRule.ErrorCode ("invalid_value") +``` + +## Type-level rules and scalar value objects + +An attribute applied to a **type** validates the value as a unit, reporting an **empty path**. That is +what makes a rule usable on a `Purview.ValueObjects` `[Scalar]`: + +```csharp +[Scalar] +[ZodSchema] +[NonSentinel(Message = "UserId must not be empty.")] +public readonly partial record struct UserId +{ + public Guid Value { get; init; } +} +``` + +A rule written against the *underlying* value — `NonSentinelRule` — is adapted automatically: +the generator closes it with the underlying type and wraps it, so it runs against the value object +with an empty path, and the wrapped rule owns the reported `Code`. Closing such a rule with the +scalar type instead (`NonSentinelRule`) compiles but **always passes**, because the check only +knows the primitive. + +## Diagnostics you will meet + +`ZODSGEN030` (mapped rule does not implement `IValidationRule` for the property type), +`ZODSGEN031` (a constructor parameter could not be mapped from the attribute), `ZODSGEN032` (no +attribute could be generated), `ZODSGEN033` (a rule-mapped attribute on a type that gets no generated +schema, so the rule never runs), `ZODSGEN037`/`ZODSGEN038` (attribute-name collisions and incomplete +mappings), `ZODSGEN039` (`code`/`origin` without `IZodRule`), `ZODSGEN040` (an attribute argument with +no effect), `ZODSGEN042` (missing `ErrorCode`/`MessageFormat`) and `ZODSGEN043` (a built-in rule whose +constructor parameter cannot be an attribute property). + +The `purview-zodsharp-diagnostics` skill carries the full catalogue. diff --git a/.claude/skills/purview-zodsharp-diagnostics/SKILL.md b/.claude/skills/purview-zodsharp-diagnostics/SKILL.md new file mode 100644 index 00000000..101e872d --- /dev/null +++ b/.claude/skills/purview-zodsharp-diagnostics/SKILL.md @@ -0,0 +1,125 @@ +--- +name: purview-zodsharp-diagnostics +description: >- + Use when a Purview.ZodSharp build reports a ZODSGEN or ZODSASP diagnostic - the [ZodSchema] + generator's configuration and usage rules, the custom-rule mapping rules, and the ErrorType + analyzers - to find what triggered it and how to fix it. +license: MIT +metadata: + product: Purview.ZodSharp + repository: purview-dev/zodsharp +--- + +# Purview.ZodSharp diagnostics + +Two families, both enabled by default: + +- **`ZODSGEN*`** — the `[ZodSchema]` generator's analyzer (category `ZodSharp.SourceGenerator`). +- **`ZODSASP*`** — the `ErrorType` factory's analyzer and generator, which ship in the **core** + package and need no ASP.NET Core dependency. + +`ZODSGEN033` and `ZODSGEN037`–`ZODSGEN040` and `ZODSGEN042` are warnings; `ZODSGEN041` and +`ZODSGEN043` are informational; the rest are errors. + +IDs `ZODSGEN002` and `ZODSGEN022`–`ZODSGEN026` are intentionally unused. Rule identifiers are never +renumbered or reused, so a sighting of one means stale tooling or a stale suppression. + +## Generator failures and DataAnnotations usage + +| ID | Meaning | +| --- | --- | +| `ZODSGEN001` | Unhandled generator exception. | +| `ZODSGEN003` | `[Length]` with `min > max`. | +| `ZODSGEN004` | `[Length]` on an unsupported target. | +| `ZODSGEN005` | Error-message resource name without type, or type without name. | +| `ZODSGEN006` | Unsupported DataAnnotations usage: a string-only attribute on a non-string, `[AllowedValues]`/`[DeniedValues]` on an unsupported type, `[RegularExpression]` on a non-string, `[Range]` on an unsupported type. | +| `ZODSGEN020` | `[Compare]` references an unknown property. | +| `ZODSGEN021` | `System.ComponentModel.DataAnnotations` reference is missing. | + +## Custom async validation method + +All of these mean the method the generator was told to call cannot be called: + +| ID | Meaning | +| --- | --- | +| `ZODSGEN007` | Configured but not found. | +| `ZODSGEN008` | Return type is not `ValueTask>`. | +| `ZODSGEN009` | Parameter count is not 2. | +| `ZODSGEN010` | First parameter is not the model type. | +| `ZODSGEN011` | Second parameter is not `CancellationToken`. | +| `ZODSGEN012` | The method is generic. | +| `ZODSGEN013` | Declared on the model type but not `static`. | +| `ZODSGEN014` | Inaccessible from the generated validator (private/protected). | +| `ZODSGEN015` | Ambiguous overloads — only when at least two valid candidates exist. | +| `ZODSGEN016` | The configured name is not a valid C# identifier. | +| `ZODSGEN017` | The method is abstract. | +| `ZODSGEN018` | An unimplemented partial method. | +| `ZODSGEN019` | Uses `ref`/`in`/`out`/`params`/`scoped` parameters. | + +## `IValidateOptions` + +| ID | Meaning | +| --- | --- | +| `ZODSGEN027` | Requested, but the `Microsoft.Extensions.Options` reference is missing. | +| `ZODSGEN028` | Requested on a struct — it requires a class. | + +## The refinement hook + +| ID | Meaning | +| --- | --- | +| `ZODSGEN029` | The model declares **both** `OnZodValidate` and an async custom validation method. Exactly one is allowed. | +| `ZODSGEN034` | `OnZodValidate` is on a type that is not `partial`, or whose containing types are not all `partial`, so the generated declaration cannot be emitted. | +| `ZODSGEN035` | Not declared as `partial void OnZodValidate(RefineCtx context)` — wrong modifiers, return type or parameters. | +| `ZODSGEN036` | A member still uses the retired `IEnumerable Validate()` contract, which the generator no longer binds. Implement `OnZodValidate`. | + +## Custom rules and rule attributes + +| ID | Meaning | +| --- | --- | +| `ZODSGEN030` | A rule mapped through `[ZodRule(typeof(…))]` does not implement `IValidationRule` for the property type — including an unbound generic rule that cannot be closed with it. | +| `ZODSGEN031` | A rule constructor parameter could not be mapped from the attribute. | +| `ZODSGEN032` | No validation attribute could be generated for a rule marked `[ZodRule]`. | +| `ZODSGEN033` | *(warning)* A rule-mapped attribute is applied to a type that gets no generated schema — no `[ZodSchema]`, and not reachable as a complex property — so the rule never runs. | +| `ZODSGEN037` | *(warning)* A `[ZodRule]`-derived attribute name (`XRule` → `XAttribute`) is already declared by hand, so no attribute is generated and that declaration's own mapping governs every usage. | +| `ZODSGEN038` | *(warning)* A hand-authored attribute's `[ZodRule(typeof(…))]` mapping does not address every rule declared under the name it encodes (`XAttribute` → `XRule`), so some usages resolve to no rule. | +| `ZODSGEN039` | *(warning)* A rule accepts a `code`/`origin` constructor parameter but does not implement `IZodRule`, so the value never reaches the reported error identity. | +| `ZODSGEN040` | *(warning)* An attribute argument has no effect: the resolved rule has no matching constructor parameter, and the value is not part of the reported identity. | +| `ZODSGEN042` | *(warning)* A rule does not expose a public `const string ErrorCode` **and** a public `const string MessageFormat`, so its error identity cannot be asserted in tests without duplicating literals. | +| `ZODSGEN043` | *(info)* A built-in rule marked `[ZodRule]` generates no attribute, because a constructor parameter cannot be represented as an attribute property. The rule is still reachable through the runtime/fluent API. A name colliding with DataAnnotations is **not** skipped — it is emitted with a `Zod` suffix. | + +## Collections + +| ID | Meaning | +| --- | --- | +| `ZODSGEN046` | *(warning)* `[CollectionBehavior]` is applied to a property that is not a collection of nullable elements or values (a scalar, a collection whose element cannot be `null`, or a dictionary whose value cannot be `null`), so the setting can never take effect. | + +## Unions, value objects, JSON Schema + +| ID | Meaning | +| --- | --- | +| `ZODSGEN041` | *(info)* A typed `Z.Union` whose option types are all reference types can use the allocation-free native C# 15 union from `Z.NativeUnion` on .NET 11+. A code fix is offered. | +| `ZODSGEN044` | A `[ZodSchema]` type using an automatic `[Scalar]` form (`[Scalar]` / `[Scalar(typeof(TValue))]`) cannot produce a usable schema, so the value-object generator's `Create` would reference a `{Type}Schema` that does not exist or cannot validate. Reported when `GenerateValidateMethod = false` suppresses the `Validate` it calls, or the declared underlying type cannot be represented. | +| `ZODSGEN045` | A type referenced by an exported type has `GenerateJsonSchema = false`, so the cross-platform contract surface is incomplete. | + +## `ErrorType` — `ZODSASP*` + +These ship with the **core** package, alongside the `ErrorType` factory, the `[ErrorType]` attribute +and the generator that emits `Create`/`Throw` helpers: + +| ID | Severity | Meaning | +| --- | --- | --- | +| `ZODSASP001` | Warning | A `MessageFormat` placeholder is not declared in `ErrorType.Parameters`. | +| `ZODSASP002` | Warning | The containing type of an `[ErrorType]` field is not `partial`. | +| `ZODSASP003` | Warning | An `[ErrorType]` field is not `static readonly`. | +| `ZODSASP100` | Error | Unhandled exception in the `ErrorType` source generator. | +| `ZODSASP101` | Error | The `Parameters` of an `[ErrorType]` field could not be extracted. | + +`ZODSASP001`–`ZODSASP003` explain why `Create`/`Throw` helpers were **not** generated — a silent +absence otherwise. `ZODSASP100`/`ZODSASP101` are fatal generator failures and name the field. + +## Suppressing + +Standard mechanisms: `#pragma warning disable ZODSGEN006`, a `NoWarn` entry, or an `.editorconfig` +severity override. The canonical catalogue is the analyzer's `AnalyzerReleases.Shipped.md` / +`AnalyzerReleases.Unshipped.md` in the generator project — a new or changed rule must be recorded +there in the same change. diff --git a/.claude/skills/purview-zodsharp-json/SKILL.md b/.claude/skills/purview-zodsharp-json/SKILL.md new file mode 100644 index 00000000..adaedda0 --- /dev/null +++ b/.claude/skills/purview-zodsharp-json/SKILL.md @@ -0,0 +1,223 @@ +--- +name: purview-zodsharp-json +description: >- + Use when combining Purview.ZodSharp with JSON - deserialize-and-validate and validating converters + for System.Text.Json or Newtonsoft.Json, choosing between the two packages, exporting a schema to + JSON Schema with Z.ToJsonSchema, importing one with Z.FromJsonSchema, and sharing a contract with + TypeScript Zod. +license: MIT +metadata: + product: Purview.ZodSharp + repository: purview-dev/zodsharp +--- + +# JSON and JSON Schema + +Two integration packages, and they are **mutually exclusive in practice** — pick the one matching +your JSON library: + +```bash +dotnet add package Purview.ZodSharp.SystemTextJson +dotnet add package Purview.ZodSharp.NewtonsoftJson +``` + +Each adds deserialize-and-validate, a validating converter, and JSON Schema **import**. JSON Schema +**export** is in the core package. + +Both can be referenced from one project without `extern alias` — the JSON Schema types live in +`ZodSharp.JsonSchema.SystemTextJson` / `ZodSharp.JsonSchema.NewtonsoftJson` — but the +deserialize/serialize extension overloads share names, so **import exactly one package namespace per +file**. + +## Deserialize and validate + +```csharp +using ZodSharp; + +var userSchema = Z.Object() + .Field("name", Z.String().Min(3)) + .Field("age", Z.Number().Min(0).Int()) + .Build(); + +var result = userSchema.DeserializeAndValidate("""{ "name": "John", "age": 30 }"""); + +await using var stream = File.OpenRead("user.json"); +var streamed = await userSchema.DeserializeAndValidateAsync(stream); +``` + +Going the other way: + +```csharp +var json = userSchema.ValidateAndSerialize(user); // ValidationResult +await userSchema.ValidateAndSerializeAsync(user, outputStream); +``` + +Failures add `deserialization_failed` and `json_error` codes alongside the schema's own. + +## Validating converters + +```csharp +// System.Text.Json +var options = new JsonSerializerOptions { Converters = { userSchema.CreateValidatingConverter() } }; +var value = JsonSerializer.Deserialize(json, options); + +// Newtonsoft.Json +var value2 = JsonConvert.DeserializeObject(json, userSchema.CreateValidatingConverter()); +``` + +Invalid JSON **throws** — `JsonException` (STJ) or `JsonSerializationException` (Newtonsoft), with a +`"Validation failed: …"` message. Each converter removes itself from the options/serializer it uses +internally, to avoid recursing into itself. + +## Which package differs how + +| Aspect | SystemTextJson | NewtonsoftJson | +| --- | --- | --- | +| Async result | `ValueTask<…>` | `Task<…>` | +| Options parameter | `JsonSerializerOptions` | `JsonSerializerSettings` | +| Converter return | generic `JsonConverter` | non-generic `JsonConverter` | +| `JToken` overload | no | yes | +| Formatting | via options | explicit `Formatting` argument | +| Invalid-data exception | `JsonException` | `JsonSerializationException` | +| Plumbing type | `JsonElement` | `JToken`/`JObject`/`JArray` | + +## JSON Schema export + +`Z.ToJsonSchema` (core package) produces a Draft 2020-12 `JsonSchemaDefinition`: + +```csharp +var jsonSchema = Z.ToJsonSchema>(userSchema, new ToJsonSchemaOptions +{ + Title = "User", + Id = "https://example.com/schemas/user.json", +}); +``` + +`ToJsonSchemaOptions`: `IncludeSchema` (default `true`, emits `$schema`), `Id`, `Title`. + +`JsonSchemaDefinition` (`ZodSharp.JsonSchema`) is a mutable POCO mirroring the keywords — identity +(`$schema`/`$id`/`$ref`), type and title, string/number/array/object constraints, composition +(`anyOf`/`oneOf`/`allOf`), `enum`/`const`, `$defs` and draft-07 `definitions`, and the metadata +keywords including OpenAPI 3.0 `nullable`. + +Covered schema types: `ZodString`, `ZodNumber`, `ZodBoolean`, `ZodNull`, `ZodObject`, `ZodOptional`, +`ZodUnion`, `ZodArray`, `ZodLiteral`, `ZodNullable`, `ZodNativeEnum`/`ZodEnum`, `ZodLazy`. Notable +behaviours: + +- objects emit `additionalProperties: false`; +- literals emit `const` plus `type`; +- native enums emit `enum` in their System.Text.Json wire form — numbers by default, member names + when serialized as strings. A `[Flags]` enum emits `type: integer` instead, because a combination is + valid without being a defined member; +- lazy/recursive schemas emit `$ref` entries under `$defs` (`#/$defs/__lazyN`); +- rules that describe their own constraint implement `IJsonSchemaRule` and are applied during export; +- `[NonSentinel]` exports exact patterns for `DateOnly`, `TimeOnly`, `DateTime`, and `DateTimeOffset`. The + default `DateTimeOffset` pattern is offset-aware and needs no converter. An optional narrower UTC contract + uses `ZodSharpDateTimeOffsetSerialization=Utc` or + `[assembly: ZodSharpSchemaDefaults(DateTimeOffsetSerialization = DateTimeOffsetSerialization.Utc)]`, paired + with the integration package's `UtcDateTimeOffsetConverter` (which rejects non-UTC input on read). Override + per type/property with `[DateTimeOffsetBehavior(...)]`. + +### Exporting a generated `[ZodSchema]` + +No need to rebuild the rules by hand with `Z.Object()`: + +```csharp +var jsonSchema = RepositoryInventoryItemSchema.BuildJsonSchema(); +var exported = Z.ToJsonSchema(new RepositoryInventoryItemSchemaValidator()); +``` + +The definition comes from the same metadata the generated validator uses, so the two cannot drift. +Things worth knowing: + +- **Property names** use the System.Text.Json wire form: `[JsonPropertyName]` wins, otherwise the name + is camelCased to match `JsonSerializerDefaults.Web`. A non-camelCase global naming policy configured + at runtime is invisible to the generator, so adjust the exported names or declare + `[JsonPropertyName]`. +- **Required** follows the nullable reference-type annotation: a non-nullable reference type (or + `Nullable`) is required; a nullable one is wrapped in `anyOf: [ …, { "type": "null" } ]` and is + not required. `[Required]` also makes a field required, and a rule that rejects an absent value — + `[RequiredZod]` — makes the field non-null even with a nullable annotation. The generated validator + agrees with all of this. +- **Scalar value objects** (`[Scalar]`) export as the **underlying** value's schema, not as an + object wrapping a `Value` property. A `Guid` scalar exports as a canonical 8-4-4-4-12 hexadecimal + `pattern`, not Zod's RFC `uuid` format, because a C# `Guid` accepts any 128-bit value. +- **Collection items** follow the null-items setting: `T[]`/`List` maps to `z.array(T)` and + `T?[]`/`List` (or a property allowing nulls via `[CollectionBehavior(AllowNulls = true)]`) to + `z.array(T.nullable())`. A collection whose elements may be null exports + `items.anyOf: [ …, { "type": "null" } ]`; by default the generated validator rejects a null element with + `invalid_type` at the element's path, matching `z.array(T)`. +- **Dictionaries map to `z.record(z.string(), V)`.** A property implementing `IDictionary<,>` or + `IReadOnlyDictionary<,>` exports `{ "type": "object", "additionalProperties": }` (a nullable value + wraps that value schema in a `null` branch), and its size constraints use `minProperties`/`maxProperties`. + `Z.Record(schema)` exports the same shape, and `Z.FromJsonSchema` reads an object with + `additionalProperties` back as a record in both JSON integrations. + +## JSON Schema import + +```csharp +using ZodSharp; +using ZodSharp.JsonSchema.SystemTextJson; // or …NewtonsoftJson + +var userSchema = Z.FromJsonSchema(jsonSchemaString); +var result = userSchema.Validate(userData); +``` + +Overloads take a `string` or an already-deserialized `JsonSchemaDefinition`, and both return +`IZodSchema`. + +`Z.FromJsonSchema` is a **C# 14 extension member on `Z`**, so it only exists when a JSON integration +package is referenced. `Z.ToJsonSchema` is a real static member in the core package. + +Mapped keywords: + +- `type` — `string`, `number`, `integer`, `boolean`, `null`, `object`, `array`. +- `enum` → a union of literals (a single member becomes a literal); `const` → a literal. +- `anyOf`/`oneOf` → union; `allOf` → the intersection of every branch, plus the base schema when the + schema also declares a `type`. A type-less branch is `any`, matching Zod's `fromJSONSchema`. +- Strings — `minLength`, `maxLength`, `pattern`, and `format` (`email`, `uri`, `uuid`). The + `uuid`/`guid` format maps to the versionless `.UUID()`; a versioned `.UUID(UuidVersion.V7)` schema + exports `format: "uuid"` plus a version-pinning `pattern`, and the `allOf` composition preserves it + on import. Multiple `pattern` constraints compose under `allOf`, and every branch is applied. +- Numbers — `minimum`, `maximum`, `multipleOf`; `integer` additionally applies `.Int()`. +- Objects — `required` and optional fields. Arrays — `items`, `minItems`, `maxItems` (a nullable item + schema — `anyOf` with a `{"type":"null"}` branch — imports as a nullable element). + +### Limits + +`$ref` resolves **local** references only (`#/…`, for example `#/$defs/Name`). An external target +throws `NotSupportedException` naming it — inline the referenced schema, or move it under the root +`$defs`, before importing. Local references **may be cyclic**: one still being resolved becomes a lazy +schema. + +The reader binds `$schema`, `$id`, `$ref`, `$defs` and the draft-07 `definitions` through the +integration package's `JsonSchemaSerializerOptions`, and the same options write them back, so exported +definitions round-trip through either package. `JsonSchemaDefinition` itself carries no serializer +annotations — serialize it with `JsonSchemaSerializerOptions` to get keyword-compliant output. + +## Sharing a contract with TypeScript Zod + +```typescript +import { z } from "zod"; +const UserSchema = z.object({ username: z.string().min(3), email: z.string().email() }); +const jsonSchema = z.toJSONSchema(UserSchema); // Zod v4+ +``` + +```csharp +var userSchema = Z.FromJsonSchema(jsonSchemaString); +``` + +This repository also proves agreement by fixture rather than by assertion. `bun run generate-fixtures` +runs `src/ts/generate-fixtures.ts`, writing `src/ts/fixtures/*.json` plus a `manifest.json` in which +**Zod is the authority** on each fixture's validity. `just test` then reads both, asserts the C# +outcome matches, and writes validated C# output to +`src/tests/cross-platform/output/{systemtext,newtonsoft}-valid.json`. Finally `bun run test` (vitest) +re-checks the fixtures under Zod and parses the C# output — closing the loop in both directions. + +If the C# output directory is empty, the vitest suite tells you to run the C# cross-platform tests +first. + +## Related skills + +`purview-zodsharp-core` for the schema API, and `purview-zodsharp-source-generator` for the generated +validators that export through `BuildJsonSchema`. diff --git a/.claude/skills/purview-zodsharp-source-generator/SKILL.md b/.claude/skills/purview-zodsharp-source-generator/SKILL.md new file mode 100644 index 00000000..31d140ec --- /dev/null +++ b/.claude/skills/purview-zodsharp-source-generator/SKILL.md @@ -0,0 +1,224 @@ +--- +name: purview-zodsharp-source-generator +description: >- + Use when generating a compile-time validator with Purview.ZodSharp's [ZodSchema] attribute - which + types it emits, the attribute options, DataAnnotations coverage, the OnZodValidate refinement hook, + async custom validation, automatic enum validation, IValidateOptions support, and the MSBuild + switches that control it. +license: MIT +metadata: + product: Purview.ZodSharp + repository: purview-dev/zodsharp +--- + +# The `[ZodSchema]` source generator + +Mark a class, struct or record with `[ZodSchema]` and a static, zero-allocation validator is emitted +at compile time — no reflection at runtime. The attribute itself is generated into the `ZodSharp` +namespace by `Purview.ZodSharp.SourceGenerators`, so nothing beyond `Purview.ZodSharp` is needed. + +```csharp +using System.ComponentModel.DataAnnotations; +using ZodSharp; + +[ZodSchema] +public class User +{ + [Required] + [StringLength(50, MinimumLength = 3)] + public string Name { get; set; } = string.Empty; + + [Range(0, 120)] + public int Age { get; set; } + + [EmailAddress] + public string? Email { get; set; } +} + +var result = UserSchema.Validate(user); +var validated = UserSchema.Parse(user); // throws ZodException on failure +``` + +## What gets emitted + +| Artifact | Shape | +| --- | --- | +| `{TypeName}Schema` | static partial class — the validator. Accessibility mirrors the target. Holds `Validate`, `Parse`, `BuildJsonSchema`, and (with composition on) `ApplyAnd`, `ApplyOr`, `ApplyRefine`. Renamed by `SchemaName`. | +| `{TypeName}SchemaValidator` | `partial class : IZodSchemaValidator<{TypeName}>, IJsonSchemaProvider` — the DI adapter, with `Validate`/`ValidateAsync`/`BuildJsonSchema`. Primary schema only; `{SchemaName}Validator` when renamed. | +| `{TypeName}Validator` | `sealed partial class : IValidateOptions<{TypeName}>` — only when `IValidateOptions` support is on, and the target is a class. | +| `[assembly: ZodSchemaGenerated(typeof({TypeName}))]` | the marker `IZodSchemaFactory` assembly scanning consumes. Primary, non-nested schemas only. | + +`BuildJsonSchema` is built from the same metadata as `Validate`, so a generated schema exports through +`Z.ToJsonSchema` without rebuilding its rules by hand. + +```csharp +var adult = UserSchema.ApplyRefine(user, u => u.Age >= 18, "Must be adult"); +var both = UserSchema.ApplyAnd(user, u => u.Name.Length > 5, "Name too short"); +var either = UserSchema.ApplyOr(user, u => u.Age < 18, "Must be an adult, or a minor with consent"); +``` + +## Attribute options + +| Property | Default | Purpose | +| --- | --- | --- | +| `SchemaName` | `null` | Renames `{TypeName}Schema`; the DI adapter becomes `{SchemaName}Validator`. | +| `GenerateValidateMethod` | `true` | `false` omits `Validate` **and everything that depends on it**. | +| `GenerateParseMethod` | `true` | `false` omits `Parse`. | +| `EnableComposition` | `true` | Emits `ApplyAnd`/`ApplyOr`/`ApplyRefine`. | +| `CustomValidationMethodName` | `null` | Names the async custom validation method (default lookup `CustomValidationAsync`). Mutually exclusive with `OnZodValidate`. | +| `GenerateIValidateOptions` | `false` | Forces `IValidateOptions` generation. | +| `SuppressIValidateOptions` | `false` | Opts out even when auto-detection would enable it. | +| `ValidateEnumValues` | `true` | `false` skips automatic enum validation. | +| `GenerateJsonSchema` | `true` | `false` omits `BuildJsonSchema` and `IJsonSchemaProvider`. A type referenced by an exported type is `ZODSGEN045`. | +| `AllowNulls` | unset | Whether this type's collection properties may contain `null` elements. Unset defers to the assembly default. | + +`Parse`, the composition methods, the `IZodSchemaValidator` adapter and the `IValidateOptions` +validator all depend on `Validate` — `GenerateValidateMethod = false` removes them together. + +## What is validated + +- Properties must be public, non-static, non-indexer. +- A property gets validation when it carries **any** DataAnnotations attribute, when its type is a + source-defined complex type with a nested schema, or when its type is an enum. +- Nested complex types are discovered recursively and get their own `{TypeName}Schema`, **even + without** their own `[ZodSchema]`. +- Nullable properties are null-guarded before value-set/type validation; a nullable target rejects + `null` with `invalid_type`. +- Collection elements reject `null` by default: the error is `invalid_type` at the element's own path + (`["Items", 0]`). Control it with `[CollectionBehavior(AllowNulls = ...)]` on the property, a `T?` + element annotation (implies allow), `[ZodSchema(AllowNulls = ...)]` on the containing type, + `[assembly: ZodSharpSchemaDefaults(AllowNulls = ...)]`, then the `ZodSharpAllowNulls` MSBuild + property. The most specific statement wins; an unset level defers to the next. An explicit + `AllowNulls = true` exports a `null` branch on the collection's `items` schema. +- **Dictionaries are maps, not arrays.** A property whose type implements `IDictionary` + or `IReadOnlyDictionary` (for example `Dictionary`, `SortedDictionary`, + `ConcurrentDictionary`, `ImmutableDictionary`) validates every **value** against the value type's + nested schema and reports a failure at `["Items", "key"]`. Keys are used only in error paths, and + `AllowNulls` governs a null value (`Dictionary` rejects it by default; `Child?` or + `[CollectionBehavior(AllowNulls = true)]` accepts it). A dictionary exports as + `{ "type": "object", "additionalProperties": … }` and `[Length]`/`[MinLength]`/`[MaxLength]` map to + `minProperties`/`maxProperties` — never `z.array`/`items`. +- Classes, structs and records are supported. Structs get no `IValidateOptions` (`ZODSGEN028` if + requested). + +DataAnnotations coverage, positional-record attribute targets, structured size issues and the +`[Range]` shapes are in [references/dataannotations.md](references/dataannotations.md). + +## The `OnZodValidate` refinement hook + +Rules DataAnnotations cannot express are written as a **generator-declared partial method**. The +generator emits the declaration, so the IDE offers the implementation with the right signature and +nothing is resolved by naming convention: + +```csharp +[ZodSchema] +public partial class Order +{ + public decimal Total { get; set; } + + partial void OnZodValidate(RefineCtx context) + { + if (context.Value.Total < 0) + context.AddIssue("invalid_range", "Total cannot be negative", [nameof(Total)]); + } +} +``` + +- The type **and every containing type** must be `partial` (`ZODSGEN034`). That is the only shape + requirement the hook adds. +- The signature must be `partial void OnZodValidate(RefineCtx context)`, `T` being the model + (`ZODSGEN035`). The parameter is a plain by-value `RefineCtx`. +- The hook runs for **every** entry point — `Validate`, `Parse`, the `IZodSchemaValidator` adapter, + `IValidateOptions`, any factory that validates through the schema — so a rule written here behaves + exactly like an attribute rule. +- A type that does not implement it allocates nothing: the generated `Validate` only builds a + `RefineCtx` and calls the hook when a body exists. +- The retired `IEnumerable Validate()` contract is no longer bound, and is reported + as `ZODSGEN036`. + +Alongside the hook the generator emits one `internal static` +`InvokeZodRefinementHook(T value, RefineCtx context)` bridge on the target type. A classic partial +method is private and `{Type}Schema` is a different type, so the bridge is what lets `Validate` reach +the hook while keeping the hook optional. **It is not part of your API; never implement it by hand.** + +## Async custom validation + +Mutually exclusive with `OnZodValidate` — declaring both is `ZODSGEN029`. + +```csharp +public partial class UserSchemaValidator +{ + public async ValueTask> CustomValidationAsync(User value, CancellationToken ct) + { + await Task.Delay(1, ct); + return ValidationResult.Success(value); + } +} +``` + +Signature `ValueTask> Name(T value, CancellationToken ct)`. The default lookup +name is `CustomValidationAsync` unless `CustomValidationMethodName` overrides it. A method on the +**model type** must be `static`; one on the generated `{TypeName}SchemaValidator` partial may be an +instance method. The generated `ValidateAsync` runs the synchronous `Validate`, awaits the custom +method, and merges the error sets. + +## Automatic enum validation + +Every non-`[Flags]` enum property is validated automatically: a value that is not a defined member is +rejected with `invalid_enum_value`, emitted as an `EnumRule`. + +```csharp +public enum ExampleEnum +{ + [ZodIgnore] // never a valid value, for every property of this type + Unspecified, + AValidValue, + AnotherValidValue, +} + +[ZodSchema] +public class Model +{ + public ExampleEnum Status { get; set; } + + [DeniedValues(ExampleEnum.AnotherValidValue)] // excluded for this property only + public ExampleEnum SecondaryStatus { get; set; } +} +``` + +It is skipped when the enum is `[Flags]` (a combination is valid without being a defined member), +when the property declares an explicit `[AllowedValues]` allow-list (which governs instead), or with +`[ZodSchema(ValidateEnumValues = false)]`. A nullable enum is validated only when not `null`. + +## `IValidateOptions` support + +Enabled by `GenerateIValidateOptions = true`, by auto-detection (unset, target is not a value type, +and the type name ends with a configured suffix — `Options` or `Settings` by default), or by MSBuild. + +| MSBuild property | Default | Behaviour | +| --- | --- | --- | +| `DisableZodSharpSourceGenerator` | unset | truthy disables the generator entirely | +| `ZodSharpAutoGenerateOptionsValidators` | `true` | only an explicit `false` disables auto-detection | +| `ZodSharpAutoGenerateOptionsValidatorSuffixes` | `Options;Settings` | semicolon/comma-separated | +| `ZodSharpGenerateJsonSchemas` | `true` | explicit `false` omits `BuildJsonSchema` and `IJsonSchemaProvider` assembly-wide | +| `ZodSharpEnumSerialization` | `Number` | `String` exports enums as member names, matching a global `JsonStringEnumConverter` | +| `ZodSharpEnumNamingPolicy` | `Unchanged` | `CamelCase` applies `JsonNamingPolicy.CamelCase` to string-serialized enum names | +| `ZodSharpAllowNulls` | `false` | assembly-wide default for whether collections may contain `null` elements; explicit `true` accepts them | +| `ZodSharpDateTimeOffsetSerialization` | `PreserveOffset` | `Utc` narrows `[NonSentinel] DateTimeOffset` to a zero-offset wire contract; pair with the integration package's `UtcDateTimeOffsetConverter`. Both modes export an exact sentinel pattern | + +`DateTimeOffset` precedence: `[DateTimeOffsetBehavior]` on the property/parameter, then on the type, then +`[assembly: ZodSharpSchemaDefaults(DateTimeOffsetSerialization = ...)]`, then the MSBuild property, then +`PreserveOffset`. The attribute shapes the schema only; `Utc` requires a converter that also rejects non-UTC +input on read. + +## Value objects + +A `Purview.ValueObjects` scalar marked `[Scalar]` can carry `[ZodSchema]` on the same type. The +generated validator validates the scalar **as a unit** and reports an empty path, and a rule written +against the underlying value is adapted automatically. + +## Related skills + +`purview-zodsharp-custom-rules` for `[ZodRule]` and the built-in rule attributes, +`purview-zodsharp-diagnostics` for the `ZODSGEN` catalogue, and `purview-zodsharp-core` for the +runtime API the generated code reports through. diff --git a/.claude/skills/purview-zodsharp-source-generator/references/dataannotations.md b/.claude/skills/purview-zodsharp-source-generator/references/dataannotations.md new file mode 100644 index 00000000..30e92ec3 --- /dev/null +++ b/.claude/skills/purview-zodsharp-source-generator/references/dataannotations.md @@ -0,0 +1,137 @@ +# DataAnnotations coverage + +The `[ZodSchema]` generator reads `System.ComponentModel.DataAnnotations` attributes and emits +direct, typed codegen. Nothing is reflected at runtime. + +## Supported attributes + +| Attribute | Generated behaviour | Failure code | +| --- | --- | --- | +| `[Required]` | nullable property must not be null; a string with `AllowEmptyStrings=false` must be non-empty | `missing_field` | +| `[Length(min, max)]` | min/max size; strings, arrays (including jagged and rectangular), countable collections | `too_small` / `too_big` | +| `[StringLength(max)]`, `[StringLength(max, MinimumLength=min)]` | string size via direct `.Length` | `too_small` / `too_big` | +| `[MinLength(n)]` | checked only when `n > 0` | `too_small` | +| `[MaxLength(n)]` | checked only when `n >= 0` | `too_big` | +| `[Range(…)]` | inclusive (or exclusive) numeric/parsed bounds | `invalid_range` | +| `[RegularExpression(pattern)]` | compiled `Regex` field, checked on non-empty strings | `invalid_string` | +| `[AllowedValues(…)]` | typed equality against the allowed set | `invalid_value` | +| `[DeniedValues(…)]` | typed equality against the denied set; on an enum property the values are absorbed into the automatic enum rule instead | `invalid_value` | +| `[EmailAddress]` | reuses `ZodSharp.Rules.EmailRule` on non-empty strings | `invalid_string` | +| `[Url]`, `[Phone]`, `[CreditCard]`, `[Base64String]` | reuse `UrlRule`, `PhoneRule`, `CreditCardRule`, `Base64StringRule` | `invalid_string` | +| `[Compare(otherProperty)]` | typed equality between two properties | `mismatch` | +| `[Display(Name=…)]` | not validated; `Name` is the display name in messages and `{0}` placeholders | — | + +`[Length]` follows DataAnnotations null semantics: `null` is valid unless `[Required]` is also +present. + +`[RequiredZod]` — the generated `RequiredRule` attribute — mirrors `[Required]`: it is emitted +*outside* the generator's non-null guard, so an absent value is reported as `missing_field` even +though every other rule bound to the member is skipped for `null`. Its `AllowEmptyStrings` has the +same meaning as `RequiredAttribute.AllowEmptyStrings`, and it adds `TrimWhitespace`, so it is a +drop-in replacement. + +## Positional records + +A positional record declares its properties from the primary-constructor parameter list, and the C# +compiler applies an attribute valid on both a parameter and a property **to the parameter only**. The +generator therefore reads attributes on the synthesized property *and* on the primary-constructor +parameter: + +```csharp +[ZodSchema] +public sealed record RepositoryInventorySummary( + [NonSentinel] string Name, + [NonSentinel] string CanonicalReference, + [NullOrNonWhiteSpace] string? DefaultBranch, + [NonSentinel] DateTimeOffset LastObservedAt +); +``` + +`[property: NonSentinel]` is equally honoured. When both targets carry the same attribute type the +property target wins and the rule runs **once**. Declared properties, classes and record structs are +unaffected. + +## Size validators and structured issues + +Size attributes generate direct `Length`/`Count` access where possible: + +- `string` → `.Length` +- arrays, including rectangular → `.Length` +- jagged arrays → outer-array `.Length` +- countable collections → `.Count` +- `IEnumerable` / `IEnumerable` → one counted pass via `CollectionCountHelper.GetCount`, with fast + paths for `ICollection`, `IReadOnlyCollection` and non-generic `ICollection` + +A structured size failure carries the same metadata as the runtime API: `Code` (`too_small` / +`too_big`), `Origin` (`string` for strings, `array` for arrays, `collection` for countable and +`IEnumerable` collections), `Minimum`/`Maximum` (the inclusive bound), `Inclusive` (`true`) and +`Path`. + +```csharp +[ZodSchema] +public sealed class Basket +{ + [Required] + [Length(2, 5)] + public List? Items { get; set; } +} + +var result = BasketSchema.Validate(new Basket { Items = ["apple"] }); +// Code == "too_small", Minimum == 2, Origin == "array", Inclusive == true +``` + +## `[Range]` + +Three constructor shapes, plus `MinimumIsExclusive`, `MaximumIsExclusive`, +`ConvertValueInInvariantCulture` and `ParseLimitsInInvariantCulture`: + +- `[Range(int, int)]` and `[Range(double, double)]` — literal numeric bounds. +- `[Range(typeof(T), "min", "max")]` — parsed bounds for numeric and comparable types. + +Comparable targets include `TimeSpan`, `DateTime`, `DateTimeOffset`, `DateOnly`, `TimeOnly` and +`Version` (which uses `CompareTo`), plus any `IComparable` with user-defined comparison operators. +Bounds are emitted as static typed fields and compared without running the attribute at runtime. + +## Error messages + +`ErrorMessage`, or `ErrorMessageResourceName` + `ErrorMessageResourceType`, are honoured, with `{0}` +(display name), `{1}` and `{2}` (bound) formatted through +`string.Format(CultureInfo.CurrentCulture, …)`. Supplying only one half of the resource name/type +pair is `ZODSGEN005`. + +## Applicability is a compile error, not a silent skip + +- `[Length]` with `min > max` → `ZODSGEN003`. +- `[Length]` on an unsupported target, such as `decimal` → `ZODSGEN004`. +- String-only attributes (`[RegularExpression]`, `[EmailAddress]`, `[Url]`, `[Phone]`, + `[CreditCard]`, `[Base64String]`) on a non-string, `[AllowedValues]`/`[DeniedValues]` on an + unsupported type, or `[Range]` on an unsupported type → `ZODSGEN006`. +- `[Compare]` naming an unknown property → `ZODSGEN020`. + +## Built-in rule attributes + +Every built-in rule ships a generated attribute in the `ZodSharp.Rules` namespace, usable alongside +the DataAnnotations above: + +`[Email]`, `[E164]`, `[Ulid]`, `[Uuid]`, `[Jwt]`, `[IpAddress]`, `[Hex]`, `[Regex]`, `[StartsWith]`, +`[EndsWith]`, `[Includes]`, `[MultipleOf]`, `[Finite]`, `[SafeInteger]`, `[Int]`, `[Uri]`, +`[Base64Url]`, `[Nanoid]`, `[Cuid2]`, `[DateString]`, `[DatetimeString]`, `[TimeString]`, `[Emoji]`, +`[Xid]`, `[Ksuid]`, `[Duration]`, `[Guid]`, `[Cidr]`, `[NonSentinel]`, `[NullOrNonWhiteSpace]`, +`[MinValue]`, `[MaxValue]`, `[GreaterThan]`, `[LessThan]`, `[GreaterThanOrEqual]`, +`[LessThanOrEqual]`, `[Even]`, `[Odd]`, `[Enum]`, `[RequiredZod]`, `[RangeZod]`, `[LengthZod]`, +`[StringLengthZod]`, `[CompareZod]`, `[AllowedValuesZod]`, `[DeniedValuesZod]`. + +A value the rule declares **without a default** becomes a required constructor argument — +`[Regex("…")]`, `[UUID(UuidVersion.V4)]`, `[Uri(UriKind.Absolute)]`, `[MinValue(3)]` — while +defaulted values and `Message`/`Code` stay named properties. A rule with overloaded constructors +mirrors each overload, so `[Uuid]` is the versionless rule and `[UUID(UuidVersion.V4)]` the versioned +one. `[UUID]` also applies to a `Guid` member or a `[Scalar]` type, because a `Guid` *is* a +UUID — which is how a time-ordered identifier is constrained to an RFC version. + +Names colliding with a DataAnnotations attribute take a `Zod` suffix: `[MinLengthZod]`, +`[MaxLengthZod]`, `[UrlZod]`, `[PhoneZod]`, `[CreditCardZod]`, `[Base64StringZod]`, `[RequiredZod]`, +`[RangeZod]`, `[LengthZod]`, `[StringLengthZod]`, `[CompareZod]`, `[AllowedValuesZod]`, +`[DeniedValuesZod]`. + +A custom rule reaches the same pipeline through `[ZodRule(typeof(MyRule))]` on an attribute, or +`[ZodRule]` on the rule to have the attribute generated. diff --git a/skills-lock.json b/skills-lock.json new file mode 100644 index 00000000..f55059ba --- /dev/null +++ b/skills-lock.json @@ -0,0 +1,245 @@ +{ + "version": 1, + "skills": { + "purview-architests": { + "source": "purview-dev/architests", + "sourceType": "github", + "skillPath": "skills/purview-architests/SKILL.md", + "computedHash": "08af64852b85c486e94cb5a17a51f8b532cdf076d2cf433636bfb09f8f12a241" + }, + "purview-architests-contracts": { + "source": "purview-dev/architests", + "sourceType": "github", + "skillPath": "skills/purview-architests-contracts/SKILL.md", + "computedHash": "f57286614b04054e6e5652ee36bef82e25b4a052fd800ecfc28e6a138d52d512" + }, + "purview-architests-extending": { + "source": "purview-dev/architests", + "sourceType": "github", + "skillPath": "skills/purview-architests-extending/SKILL.md", + "computedHash": "0827d32a900c2c09dc9be1f08c5cfc3337bb9e6d581747b04607bff76ee4c2a1" + }, + "purview-architests-migration": { + "source": "purview-dev/architests", + "sourceType": "github", + "skillPath": "skills/purview-architests-migration/SKILL.md", + "computedHash": "a485cb4ae3686615e7f53789e4a06a0a8397ab56a79d3f1f5edbed2666edf7c7" + }, + "purview-architests-policy-authoring": { + "source": "purview-dev/architests", + "sourceType": "github", + "skillPath": "skills/purview-architests-policy-authoring/SKILL.md", + "computedHash": "cab652d18daaf3a7af225c2af904cf7b27608188c6dd34a2f1ea2fa5f3bb2c7b" + }, + "purview-architests-type-rules": { + "source": "purview-dev/architests", + "sourceType": "github", + "skillPath": "skills/purview-architests-type-rules/SKILL.md", + "computedHash": "4a010c679317c958d7ca0f4cf4f095014e12495ebe2e239814ebecab06e5fbaf" + }, + "purview-buildsdk-adoption": { + "source": "purview-dev/build-sdk", + "sourceType": "github", + "skillPath": "skills/purview-buildsdk-adoption/SKILL.md", + "computedHash": "ca2e13fc8074281f8ca2b510b742ae99db28f97d78f5fb36a6f27936a91941fc" + }, + "purview-buildsdk-configuration": { + "source": "purview-dev/build-sdk", + "sourceType": "github", + "skillPath": "skills/purview-buildsdk-configuration/SKILL.md", + "computedHash": "55f96148b07e03f292f06a786a9733ae6df6d971870af48caf32212a3b58e46d" + }, + "purview-buildsdk-project-detection": { + "source": "purview-dev/build-sdk", + "sourceType": "github", + "skillPath": "skills/purview-buildsdk-project-detection/SKILL.md", + "computedHash": "1f251609d5e0c219a9eb627ce27fc38f845e1ab826a2b0bc0985af8ec1a069a2" + }, + "purview-buildsdk-project-layout": { + "source": "purview-dev/build-sdk", + "sourceType": "github", + "skillPath": "skills/purview-buildsdk-project-layout/SKILL.md", + "computedHash": "d88899ee89edf9615af4b8406b50d53ffb9cec63ed2a9a4ace6d9a322aeef059" + }, + "purview-buildsdk-repository-review": { + "source": "purview-dev/build-sdk", + "sourceType": "github", + "skillPath": "skills/purview-buildsdk-repository-review/SKILL.md", + "computedHash": "d366821995ff410caa436ccb996eaa6429f1ba51ba985b210d74ec3963f6c06f" + }, + "purview-buildsdk-skill-installation": { + "source": "purview-dev/build-sdk", + "sourceType": "github", + "skillPath": "skills/purview-buildsdk-skill-installation/SKILL.md", + "computedHash": "b61cce9f0f213469c3acab4dd5ebaec450ee2be730680b166c9718c901aedffe" + }, + "purview-buildsdk-skill-tests": { + "source": "purview-dev/build-sdk", + "sourceType": "github", + "skillPath": "skills/purview-buildsdk-skill-tests/SKILL.md", + "computedHash": "807b64466de0a871e5f8e678e7686c48a06d8bb9d42a03448f604a35d40d3935" + }, + "purview-buildsdk-testing": { + "source": "purview-dev/build-sdk", + "sourceType": "github", + "skillPath": "skills/purview-buildsdk-testing/SKILL.md", + "computedHash": "d6a2ac1167faf68e8c27493de81c2e5b0d8183e523de4411aca5f5b9249c8a9c" + }, + "purview-results-core": { + "source": "purview-dev/results", + "sourceType": "github", + "skillPath": "skills/purview-results-core/SKILL.md", + "computedHash": "9de2cc5f5437b69b2111b62b7ac18992c1fbcae188e16d526aae0f0f63b01c26" + }, + "purview-results-http-mapping": { + "source": "purview-dev/results", + "sourceType": "github", + "skillPath": "skills/purview-results-http-mapping/SKILL.md", + "computedHash": "56453f137355cb5fe36d57c07e8fe6170067ad99bba0cd3bb2c3d2cd7bd742b6" + }, + "purview-results-union-errors": { + "source": "purview-dev/results", + "sourceType": "github", + "skillPath": "skills/purview-results-union-errors/SKILL.md", + "computedHash": "c27ecdef80f6591b8cf5ebbe28a9287911441368299198356578a6f31ab9388e" + }, + "purview-results-zodsharp-problems": { + "source": "purview-dev/results", + "sourceType": "github", + "skillPath": "skills/purview-results-zodsharp-problems/SKILL.md", + "computedHash": "68ef2db6a1231c8821fa805809c21927e02382709f8a00326b5574cbbdfba638" + }, + "purview-results-zodsharp-validation": { + "source": "purview-dev/results", + "sourceType": "github", + "skillPath": "skills/purview-results-zodsharp-validation/SKILL.md", + "computedHash": "22c2b89ff4c06bac4943614ce36dff7fa525334270341e580f49b2fe2e80e7a5" + }, + "purview-sourcegenerator-codewriter": { + "source": "purview-dev/sourcegenerator-framework", + "sourceType": "github", + "skillPath": "skills/purview-sourcegenerator-codewriter/SKILL.md", + "computedHash": "f24ae680340784e62236d044cbc3658d5ca7bdc3cea3fc44f2bb5cf75a84f5e4" + }, + "purview-sourcegenerator-diagnostics": { + "source": "purview-dev/sourcegenerator-framework", + "sourceType": "github", + "skillPath": "skills/purview-sourcegenerator-diagnostics/SKILL.md", + "computedHash": "c3c7920701e0e688f34ddece9e448472e010e69767e8c08914638128d34a8f17" + }, + "purview-sourcegenerator-packaging": { + "source": "purview-dev/sourcegenerator-framework", + "sourceType": "github", + "skillPath": "skills/purview-sourcegenerator-packaging/SKILL.md", + "computedHash": "e0e6372e92aefc8df026a73010d9e7436b0a8c2378a96fdebd8b4de9e025d4a0" + }, + "purview-sourcegenerator-pipeline": { + "source": "purview-dev/sourcegenerator-framework", + "sourceType": "github", + "skillPath": "skills/purview-sourcegenerator-pipeline/SKILL.md", + "computedHash": "7d48394d7e3890f288949c79f040646207f34af9ae85827a63d056bae1b1b985" + }, + "purview-sourcegenerator-testing": { + "source": "purview-dev/sourcegenerator-framework", + "sourceType": "github", + "skillPath": "skills/purview-sourcegenerator-testing/SKILL.md", + "computedHash": "d88bf2353073013ff9ddf9d3fe1a2e9415eb60d319bbd053baa105f50fa3f889" + }, + "purview-sourcegenerator-tunit-tests": { + "source": "purview-dev/sourcegenerator-framework", + "sourceType": "github", + "skillPath": "skills/purview-sourcegenerator-tunit-tests/SKILL.md", + "computedHash": "14809d3727643e9a779d590b6627b3283af7b36c835e902cb80162552cb45b4f" + }, + "purview-telemetry-design": { + "source": "purview-dev/telemetry-sourcegenerator", + "sourceType": "github", + "skillPath": "skills/purview-telemetry-design/SKILL.md", + "computedHash": "74c4c4a810713ef34e0179ebd83494c8763d4409e4b3c1289863a8c4a5676cd9" + }, + "purview-telemetry-diagnostics": { + "source": "purview-dev/telemetry-sourcegenerator", + "sourceType": "github", + "skillPath": "skills/purview-telemetry-diagnostics/SKILL.md", + "computedHash": "ae3d02a28143d6e2dbf1af1f89a2394055cfa728864eaee7e2ff05b1398958bc" + }, + "purview-telemetry-migration": { + "source": "purview-dev/telemetry-sourcegenerator", + "sourceType": "github", + "skillPath": "skills/purview-telemetry-migration/SKILL.md", + "computedHash": "703fe6f5ccbe1e4fe644873fab681ab98caae4bd552edf03dd6d61ff5eeffba2" + }, + "purview-telemetry-multi-targeting": { + "source": "purview-dev/telemetry-sourcegenerator", + "sourceType": "github", + "skillPath": "skills/purview-telemetry-multi-targeting/SKILL.md", + "computedHash": "f220ef392d37139a9870a49e9d5be41bf8374e27b42f2808878daa968c666793" + }, + "purview-telemetry-quickstart": { + "source": "purview-dev/telemetry-sourcegenerator", + "sourceType": "github", + "skillPath": "skills/purview-telemetry-quickstart/SKILL.md", + "computedHash": "e4ebadfa44536c949ea8600430d6d1b92986958abd25bc6f149d0a00dc9c9b86" + }, + "purview-value-objects": { + "source": "purview-dev/value-objects", + "sourceType": "github", + "skillPath": "skills/purview-value-objects/SKILL.md", + "computedHash": "a101ad1f21a1c8ab402532c068c3a94bcbd5e5690f504bd8cd4f65223866f66e" + }, + "purview-value-objects-diagnostics": { + "source": "purview-dev/value-objects", + "sourceType": "github", + "skillPath": "skills/purview-value-objects-diagnostics/SKILL.md", + "computedHash": "e3ed36c5e626d1d275b1da47a136c2066c1e2c705dc64bcd3e66551872f60e86" + }, + "purview-value-objects-efcore": { + "source": "purview-dev/value-objects", + "sourceType": "github", + "skillPath": "skills/purview-value-objects-efcore/SKILL.md", + "computedHash": "d1364b2be516cb46466827b108ce0cbcc6ba0d840cdad7932a8e79c639e2af47" + }, + "purview-value-objects-zodsharp": { + "source": "purview-dev/value-objects", + "sourceType": "github", + "skillPath": "skills/purview-value-objects-zodsharp/SKILL.md", + "computedHash": "e42f9ee98ce66b59ae4ee0d7037d683de232955b35c627cb6bab13ac08204134" + }, + "purview-zodsharp-aspnetcore": { + "source": "purview-dev/zodsharp", + "sourceType": "github", + "skillPath": "skills/purview-zodsharp-aspnetcore/SKILL.md", + "computedHash": "a1c1f9fc008be609cb12622ca08022965497fe306cc1b4203333440a0edb4206" + }, + "purview-zodsharp-core": { + "source": "purview-dev/zodsharp", + "sourceType": "github", + "skillPath": "skills/purview-zodsharp-core/SKILL.md", + "computedHash": "e89c1000bb305420b85c1b93f3f77d9b500fc6b7d52b7016f670430fab1659b0" + }, + "purview-zodsharp-custom-rules": { + "source": "purview-dev/zodsharp", + "sourceType": "github", + "skillPath": "skills/purview-zodsharp-custom-rules/SKILL.md", + "computedHash": "3726a476b75b842daf67898e19b197331a1195061053183d66e9e05a66294266" + }, + "purview-zodsharp-diagnostics": { + "source": "purview-dev/zodsharp", + "sourceType": "github", + "skillPath": "skills/purview-zodsharp-diagnostics/SKILL.md", + "computedHash": "19e480b1eca26e417642b8c55f689580eb7b741f02e78387041ffebba1216ddb" + }, + "purview-zodsharp-json": { + "source": "purview-dev/zodsharp", + "sourceType": "github", + "skillPath": "skills/purview-zodsharp-json/SKILL.md", + "computedHash": "82da551adff5506232d5419d925ed198d71844f7901ad13ef7a3a0bead4a826f" + }, + "purview-zodsharp-source-generator": { + "source": "purview-dev/zodsharp", + "sourceType": "github", + "skillPath": "skills/purview-zodsharp-source-generator/SKILL.md", + "computedHash": "7172450983d6130c3335276fdcec80ca87b473ab7fbb43dfd08304b55c1632b0" + } + } +} From 0aad83c3f39ce91527e72ca3b86212921ab5a8b5 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Fri, 23 Oct 2026 10:02:46 +0100 Subject: [PATCH 05/41] fix: brought inline with recs --- .../EFSnapshotShapeAnalyzer.cs | 539 ++++++++++-------- .../EFSourceGenerator.cs | 2 +- ...ttributeEmiiter.cs => AttributeEmitter.cs} | 4 +- .../CompilerServices/IsExternalInit.cs | 15 - .../{Heleprs => Helpers}/DiagnosticLibrary.cs | 2 +- .../{Heleprs => Helpers}/TypeLibrary.cs | 2 +- .../Purview.EventSourcing.targets | 6 + .../Common/EventContractManifestLibrary.cs | 71 ++- .../CompilerServices/IsExternalInit.cs | 15 - ...view.EventSourcing.SourceGenerator.targets | 25 + .../SourceGenerator/SourceGenerator.csproj | 8 + .../EFSnapshotShapeAnalyzerTests.cs | 2 +- .../EFSourceGeneratorTestOptions.cs | 2 +- .../EFSourceGeneratorTests.cs | 2 +- .../AggregateIncrementalCacheTests.cs | 8 +- ...ggregateSourceGeneratorIncrementalTests.cs | 6 +- 16 files changed, 394 insertions(+), 315 deletions(-) rename src/src/EntityFrameworkCore.SourceGenerator/Emitters/{AttributeEmiiter.cs => AttributeEmitter.cs} (97%) delete mode 100644 src/src/EntityFrameworkCore.SourceGenerator/Extensions/System/Runtime/CompilerServices/IsExternalInit.cs rename src/src/EntityFrameworkCore.SourceGenerator/{Heleprs => Helpers}/DiagnosticLibrary.cs (99%) rename src/src/EntityFrameworkCore.SourceGenerator/{Heleprs => Helpers}/TypeLibrary.cs (99%) delete mode 100644 src/src/SourceGenerator/Extensions/System/Runtime/CompilerServices/IsExternalInit.cs create mode 100644 src/src/SourceGenerator/Sdk/buildTransitive/Purview.EventSourcing.SourceGenerator.targets diff --git a/src/src/EntityFrameworkCore.SourceGenerator/EFSnapshotShapeAnalyzer.cs b/src/src/EntityFrameworkCore.SourceGenerator/EFSnapshotShapeAnalyzer.cs index c36d09b6..48ee4ea6 100644 --- a/src/src/EntityFrameworkCore.SourceGenerator/EFSnapshotShapeAnalyzer.cs +++ b/src/src/EntityFrameworkCore.SourceGenerator/EFSnapshotShapeAnalyzer.cs @@ -1,8 +1,9 @@ +using System.Collections.Immutable; using Microsoft.CodeAnalysis; using Microsoft.CodeAnalysis.CSharp.Syntax; using Microsoft.CodeAnalysis.Diagnostics; -using Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.Heleprs; -using System.Collections.Immutable; +using Microsoft.CodeAnalysis.Operations; +using Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.Helpers; namespace Purview.EventSourcing.EntityFrameworkCore.SourceGenerator; @@ -18,334 +19,374 @@ public override void Initialize(AnalysisContext context) context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None); context.EnableConcurrentExecution(); - context.RegisterCompilationAction(AnalyzeSnapshotShapes); - context.RegisterSyntaxNodeAction( - AnalyzeOpaqueQueryUse, - Microsoft.CodeAnalysis.CSharp.SyntaxKind.SimpleMemberAccessExpression - ); + context.RegisterCompilationStartAction(OnCompilationStart); } - static void AnalyzeSnapshotShapes(CompilationAnalysisContext context) + /// + /// Resolves the marker attributes once per compilation so the per-symbol checks compare symbol + /// identity instead of re-matching names, and a compilation that declares no aggregate skips the + /// snapshot walk entirely. + /// + static void OnCompilationStart(CompilationStartAnalysisContext context) { - HashSet visited = new(SymbolEqualityComparer.Default); - HashSet materializationVisited = new(SymbolEqualityComparer.Default); - foreach (var type in GetSourceTypes(context.Compilation.Assembly.GlobalNamespace)) - { - if (!TypeHelpers.HasAttribute(type, TypeLibrary.AggregateAttribute)) - continue; + if (!TypeHelpers.HasType(context.Compilation, TypeLibrary.AggregateAttribute)) + return; - AnalyzeType(type, context, visited); - AnalyzeMaterializableType(type, context, materializationVisited); - } + SymbolResolver.TryResolve(context.Compilation, TypeLibrary.EFOpaqueAttribute, out var opaqueAttribute); + SnapshotShapeAnalysis analysis = new(opaqueAttribute); + + // The shape rules walk the graph reachable from each aggregate and report on the member that + // owns the problem, which is routinely declared on a different type. A symbol action may only + // report within the symbol it was given, so these rules stay compilation-end - which is what + // their WellKnownDiagnosticTags.CompilationEnd tags declare. + context.RegisterCompilationEndAction(analysis.AnalyzeSnapshotShapes); + + // A property read is executable behavior, so it is an operation rather than a syntax concern. + context.RegisterOperationAction(analysis.AnalyzeOpaqueQueryUse, OperationKind.PropertyReference); } - static void AnalyzeType(ITypeSymbol type, CompilationAnalysisContext context, HashSet visited) + sealed class SnapshotShapeAnalysis(INamedTypeSymbol? opaqueAttribute) { - type = UnwrapCollection(type); - if ( - !visited.Add(type) - || !type.Locations.Any(static location => location.IsInSource) - || type.SpecialType != SpecialType.None - || type.TypeKind is TypeKind.Enum or TypeKind.TypeParameter - ) + public void AnalyzeSnapshotShapes(CompilationAnalysisContext context) { - return; + HashSet visited = new(SymbolEqualityComparer.Default); + HashSet materializationVisited = new(SymbolEqualityComparer.Default); + foreach (var type in GetSourceTypes(context.Compilation.Assembly.GlobalNamespace)) + { + context.CancellationToken.ThrowIfCancellationRequested(); + + if (!TypeHelpers.HasAttribute(type, TypeLibrary.AggregateAttribute)) + continue; + + AnalyzeType(type, context, visited); + AnalyzeMaterializableType(type, context, materializationVisited); + } } - foreach ( - var property in type.GetMembers() - .OfType() - .Where(static property => !property.IsStatic && property.DeclaredAccessibility == Accessibility.Public) - ) + void AnalyzeType(ITypeSymbol type, CompilationAnalysisContext context, HashSet visited) { - if (IsDictionaryLike(property.Type)) + context.CancellationToken.ThrowIfCancellationRequested(); + + type = UnwrapCollection(type); + if ( + !visited.Add(type) + || !type.Locations.Any(static location => location.IsInSource) + || type.SpecialType != SpecialType.None + || type.TypeKind is TypeKind.Enum or TypeKind.TypeParameter + ) { - if (!HasOpaqueAttribute(property)) + return; + } + + foreach ( + var property in type.GetMembers() + .OfType() + .Where(static property => + !property.IsStatic && property.DeclaredAccessibility == Accessibility.Public + ) + ) + { + if (IsDictionaryLike(property.Type)) { - context.ReportDiagnostic( - Diagnostic.Create( - DiagnosticLibrary.UnsupportedDictionary, - property.Locations.FirstOrDefault(), - property.Name, - property.Type.ToDisplayString(SymbolDisplayFormat.MinimallyQualifiedFormat) - ) - ); + if (!HasOpaqueAttribute(property)) + { + context.ReportDiagnostic( + Diagnostic.Create( + DiagnosticLibrary.UnsupportedDictionary, + property.Locations.FirstOrDefault(), + property.Name, + property.Type.ToDisplayString(SymbolDisplayFormat.MinimallyQualifiedFormat) + ) + ); + } + + continue; } - continue; + if (!HasOpaqueAttribute(property)) + AnalyzeType(property.Type, context, visited); } - - if (!HasOpaqueAttribute(property)) - AnalyzeType(property.Type, context, visited); } - } - - static ITypeSymbol UnwrapCollection(ITypeSymbol type) - { - if (type is IArrayTypeSymbol array) - return array.ElementType; - if (type is INamedTypeSymbol named) + static ITypeSymbol UnwrapCollection(ITypeSymbol type) { - var enumerable = named.AllInterfaces.FirstOrDefault(static item => - item.IsGenericType && TypeHelpers.IsCollectionLike(item.ConstructedFrom) - ); - if (enumerable is not null) - return enumerable.TypeArguments[0]; - } + if (type is IArrayTypeSymbol array) + return array.ElementType; - return type; - } + if (type is INamedTypeSymbol named) + { + var enumerable = named.AllInterfaces.FirstOrDefault(static item => + item.IsGenericType && TypeHelpers.IsCollectionLike(item.ConstructedFrom) + ); + if (enumerable is not null) + return enumerable.TypeArguments[0]; + } - static IEnumerable GetSourceTypes(INamespaceSymbol namespaceSymbol) - { - foreach (var member in namespaceSymbol.GetMembers()) + return type; + } + + static IEnumerable GetSourceTypes(INamespaceSymbol namespaceSymbol) { - if (member is INamespaceSymbol childNamespace) + foreach (var member in namespaceSymbol.GetMembers()) { - foreach (var type in GetSourceTypes(childNamespace)) + if (member is INamespaceSymbol childNamespace) + { + foreach (var type in GetSourceTypes(childNamespace)) + yield return type; + } + else if (member is INamedTypeSymbol type && type.Locations.Any(static location => location.IsInSource)) + { yield return type; - } - else if (member is INamedTypeSymbol type && type.Locations.Any(static location => location.IsInSource)) - { - yield return type; + } } } - } - static void AnalyzeOpaqueQueryUse(SyntaxNodeAnalysisContext context) - { - var access = (MemberAccessExpressionSyntax)context.Node; - if ( - context.SemanticModel.GetSymbolInfo(access, context.CancellationToken).Symbol - is not IPropertySymbol property - || !HasOpaqueAttribute(property) - || !IsInsideSnapshotQuery(access, context.SemanticModel, context.CancellationToken) - ) - return; - - context.ReportDiagnostic( - Diagnostic.Create(DiagnosticLibrary.OpaqueQuery, access.Name.GetLocation(), property.Name) - ); - } - - static bool IsInsideSnapshotQuery(SyntaxNode node, SemanticModel model, CancellationToken cancellationToken) - { - foreach (var invocation in node.Ancestors().OfType()) + public void AnalyzeOpaqueQueryUse(OperationAnalysisContext context) { - if (model.GetSymbolInfo(invocation, cancellationToken).Symbol is not IMethodSymbol method) - continue; + var reference = (IPropertyReferenceOperation)context.Operation; + if (!HasOpaqueAttribute(reference.Property) || !IsInsideSnapshotQuery(reference)) + return; - if (method.Name is "QueryAsync" or "FirstOrDefaultAsync" or "SingleOrDefaultAsync") - return true; + context.ReportDiagnostic( + Diagnostic.Create(DiagnosticLibrary.OpaqueQuery, GetMemberLocation(reference), reference.Property.Name) + ); } - return false; - } - - static bool HasOpaqueAttribute(IPropertySymbol property) => - TypeHelpers.HasAttribute(property, TypeLibrary.EFOpaqueAttribute); - - static bool IsDictionaryLike(ITypeSymbol type) => type is INamedTypeSymbol named ? IsDictionaryType(named) : false; + /// + /// Reports on the member name alone rather than the whole access expression, matching where a + /// reader looks for the offending property. + /// + static Location GetMemberLocation(IOperation operation) => + operation.Syntax is MemberAccessExpressionSyntax access + ? access.Name.GetLocation() + : operation.Syntax.GetLocation(); - static bool IsDictionaryType(INamedTypeSymbol type) => - type.IsGenericType - ? TypeHelpers.Is( - type, - TypeLibrary.DictionaryKV, - TypeLibrary.IDictionaryKV, - TypeLibrary.IReadOnlyDictionaryKV - ) - : false; - - // EF constructs every structurally mapped snapshot member. A member type is materializable when it exposes - // either a parameterless constructor or a constructor whose parameters all bind to scalar members: EF cannot - // bind complex or collection constructor parameters during JSON materialization. - static void AnalyzeMaterializableType( - ITypeSymbol type, - CompilationAnalysisContext context, - HashSet visited - ) - { - if (type is not INamedTypeSymbol named || !IsInspectableType(named) || !visited.Add(named)) - return; - - var mappedMembers = GetMappedMembers(named); - - if (!HasEfUsableConstructor(named, mappedMembers)) + static bool IsInsideSnapshotQuery(IOperation operation) { - var location = named.Locations.FirstOrDefault(static candidate => candidate.IsInSource); - if (location is not null) + for (var parent = operation.Parent; parent is not null; parent = parent.Parent) { - context.ReportDiagnostic( - Diagnostic.Create( - DiagnosticLibrary.UnconstructibleSnapshotType, - location, - named.ToDisplayString(SymbolDisplayFormat.MinimallyQualifiedFormat) - ) - ); + if ( + parent is IInvocationOperation invocation + && invocation.TargetMethod.Name is "QueryAsync" or "FirstOrDefaultAsync" or "SingleOrDefaultAsync" + ) + { + return true; + } } + + return false; } - foreach (var member in mappedMembers) + bool HasOpaqueAttribute(ISymbol symbol) => + opaqueAttribute is not null + && symbol + .GetAttributes() + .Any(attribute => SymbolEqualityComparer.Default.Equals(attribute.AttributeClass, opaqueAttribute)); + + static bool IsDictionaryLike(ITypeSymbol type) => + type is INamedTypeSymbol named ? IsDictionaryType(named) : false; + + static bool IsDictionaryType(INamedTypeSymbol type) => + type.IsGenericType + ? TypeHelpers.Is( + type, + TypeLibrary.DictionaryKV, + TypeLibrary.IDictionaryKV, + TypeLibrary.IReadOnlyDictionaryKV + ) + : false; + + // EF constructs every structurally mapped snapshot member. A member type is materializable when it exposes + // either a parameterless constructor or a constructor whose parameters all bind to scalar members: EF cannot + // bind complex or collection constructor parameters during JSON materialization. + void AnalyzeMaterializableType( + ITypeSymbol type, + CompilationAnalysisContext context, + HashSet visited + ) { - if (!IsMappedStructuralMember(member)) - continue; + context.CancellationToken.ThrowIfCancellationRequested(); + + if (type is not INamedTypeSymbol named || !IsInspectableType(named) || !visited.Add(named)) + return; - if (type.TypeKind == TypeKind.Struct && member.SetMethod is null) + var mappedMembers = GetMappedMembers(named); + + if (!HasEfUsableConstructor(named, mappedMembers)) { - var location = member.Locations.FirstOrDefault(static candidate => candidate.IsInSource); + var location = named.Locations.FirstOrDefault(static candidate => candidate.IsInSource); if (location is not null) { context.ReportDiagnostic( Diagnostic.Create( - DiagnosticLibrary.NonWritableValueTypeMember, + DiagnosticLibrary.UnconstructibleSnapshotType, location, - member.Name, named.ToDisplayString(SymbolDisplayFormat.MinimallyQualifiedFormat) ) ); } } - foreach (var relatedType in GetStructuralMemberTypes(member)) - AnalyzeMaterializableType(relatedType, context, visited); - } - } - - static IPropertySymbol[] GetMappedMembers(INamedTypeSymbol type) => - [.. type.GetMembers().OfType().Where(property => IsMappedMember(type, property))]; - - static bool IsMappedMember(INamedTypeSymbol declaringType, IPropertySymbol property) => - !property.IsStatic - && !property.IsIndexer - && property.DeclaredAccessibility == Accessibility.Public - && property.GetMethod is not null - && !TypeHelpers.HasAttribute(property, TypeLibrary.JsonIgnoreAttribute) - && (property.SetMethod is not null || HasBindableConstructorParameter(declaringType, property)); - - static bool HasBindableConstructorParameter(INamedTypeSymbol type, IPropertySymbol property) => - type.InstanceConstructors.Any(constructor => - constructor.Parameters.Any(parameter => - SymbolEqualityComparer.Default.Equals(parameter.Type, property.Type) - && string.Equals(parameter.Name, property.Name, StringComparison.OrdinalIgnoreCase) - ) - ); + foreach (var member in mappedMembers) + { + if (!IsMappedStructuralMember(member)) + continue; - static bool HasEfUsableConstructor(INamedTypeSymbol type, IReadOnlyList mappedMembers) - { - var constructors = type.InstanceConstructors.Where(static constructor => !constructor.IsStatic).ToArray(); + if (type.TypeKind == TypeKind.Struct && member.SetMethod is null) + { + var location = member.Locations.FirstOrDefault(static candidate => candidate.IsInSource); + if (location is not null) + { + context.ReportDiagnostic( + Diagnostic.Create( + DiagnosticLibrary.NonWritableValueTypeMember, + location, + member.Name, + named.ToDisplayString(SymbolDisplayFormat.MinimallyQualifiedFormat) + ) + ); + } + } - // A value type that declares no constructors is materialized from its default value plus member assignment. - if ( - type.TypeKind == TypeKind.Struct - && constructors.All(static constructor => constructor.IsImplicitlyDeclared) - ) - { - return true; + foreach (var relatedType in GetStructuralMemberTypes(member)) + AnalyzeMaterializableType(relatedType, context, visited); + } } - foreach (var constructor in constructors) + IPropertySymbol[] GetMappedMembers(INamedTypeSymbol type) => + [.. type.GetMembers().OfType().Where(property => IsMappedMember(type, property))]; + + bool IsMappedMember(INamedTypeSymbol declaringType, IPropertySymbol property) => + !property.IsStatic + && !property.IsIndexer + && property.DeclaredAccessibility == Accessibility.Public + && property.GetMethod is not null + && !TypeHelpers.HasAttribute(property, TypeLibrary.JsonIgnoreAttribute) + && (property.SetMethod is not null || HasBindableConstructorParameter(declaringType, property)); + + static bool HasBindableConstructorParameter(INamedTypeSymbol type, IPropertySymbol property) => + type.InstanceConstructors.Any(constructor => + constructor.Parameters.Any(parameter => + SymbolEqualityComparer.Default.Equals(parameter.Type, property.Type) + && string.Equals(parameter.Name, property.Name, StringComparison.OrdinalIgnoreCase) + ) + ); + + bool HasEfUsableConstructor(INamedTypeSymbol type, IReadOnlyList mappedMembers) { + var constructors = type.InstanceConstructors.Where(static constructor => !constructor.IsStatic).ToArray(); + + // A value type that declares no constructors is materialized from its default value plus member assignment. if ( - constructor.Parameters.Length == 0 - && (type.TypeKind != TypeKind.Struct || !constructor.IsImplicitlyDeclared) + type.TypeKind == TypeKind.Struct + && constructors.All(static constructor => constructor.IsImplicitlyDeclared) ) { return true; } - if ( - constructor.Parameters.Length > 0 - && constructor.Parameters.All(parameter => IsBindableScalarParameter(mappedMembers, parameter)) - ) + foreach (var constructor in constructors) { - return true; + if ( + constructor.Parameters.Length == 0 + && (type.TypeKind != TypeKind.Struct || !constructor.IsImplicitlyDeclared) + ) + { + return true; + } + + if ( + constructor.Parameters.Length > 0 + && constructor.Parameters.All(parameter => IsBindableScalarParameter(mappedMembers, parameter)) + ) + { + return true; + } } + + return false; } - return false; - } + bool IsBindableScalarParameter(IReadOnlyList mappedMembers, IParameterSymbol parameter) => + mappedMembers.Any(member => + string.Equals(member.Name, parameter.Name, StringComparison.OrdinalIgnoreCase) + && SymbolEqualityComparer.Default.Equals(member.Type, parameter.Type) + && !IsMappedStructuralMember(member) + ); - static bool IsBindableScalarParameter(IReadOnlyList mappedMembers, IParameterSymbol parameter) => - mappedMembers.Any(member => - string.Equals(member.Name, parameter.Name, StringComparison.OrdinalIgnoreCase) - && SymbolEqualityComparer.Default.Equals(member.Type, parameter.Type) - && !IsMappedStructuralMember(member) - ); + bool IsMappedStructuralMember(IPropertySymbol property) + { + if (HasOpaqueAttribute(property)) + return false; - static bool IsMappedStructuralMember(IPropertySymbol property) - { - if (HasOpaqueAttribute(property)) - return false; + var memberType = UnwrapNullable(property.Type); - var memberType = UnwrapNullable(property.Type); + if (TypeHelpers.HasAttribute(memberType, TypeLibrary.ScalarAttribute)) + return false; - if (TypeHelpers.HasAttribute(memberType, TypeLibrary.ScalarAttribute)) - return false; + if (IsDictionaryLike(memberType)) + return false; - if (IsDictionaryLike(memberType)) - return false; + if (memberType is INamedTypeSymbol collection && IsEventStoreCollection(collection)) + { + var elementType = collection.TypeArguments[0]; - if (memberType is INamedTypeSymbol collection && IsEventStoreCollection(collection)) - { - var elementType = collection.TypeArguments[0]; + // Struct value objects and scalars are persisted through JSON or primitive collection conversions. + if (elementType.IsValueType && TypeHelpers.HasAttribute(elementType, TypeLibrary.ValueObjectAttribute)) + return false; - // Struct value objects and scalars are persisted through JSON or primitive collection conversions. - if (elementType.IsValueType && TypeHelpers.HasAttribute(elementType, TypeLibrary.ValueObjectAttribute)) - return false; + if (TypeHelpers.HasAttribute(elementType, TypeLibrary.ScalarAttribute)) + return false; + + // EF materializes collection elements through JSON conversion, so we only need to validate that the element type is constructible and not a system type. + return IsInspectableType(elementType); + } - if (TypeHelpers.HasAttribute(elementType, TypeLibrary.ScalarAttribute)) + if (ImplementsGenericEnumerable(memberType)) return false; - // EF materializes collection elements through JSON conversion, so we only need to validate that the element type is constructible and not a system type. - return IsInspectableType(elementType); + // EF materializes complex types through JSON conversion, so we only need to validate that the type is constructible and not a system type. + return memberType is INamedTypeSymbol named && IsInspectableType(named); } - if (ImplementsGenericEnumerable(memberType)) - return false; - - // EF materializes complex types through JSON conversion, so we only need to validate that the type is constructible and not a system type. - return memberType is INamedTypeSymbol named && IsInspectableType(named); - } + static IEnumerable GetStructuralMemberTypes(IPropertySymbol property) + { + var memberType = UnwrapNullable(property.Type); - static IEnumerable GetStructuralMemberTypes(IPropertySymbol property) - { - var memberType = UnwrapNullable(property.Type); + if (memberType is INamedTypeSymbol collection && IsEventStoreCollection(collection)) + { + yield return collection.TypeArguments[0]; + yield break; + } - if (memberType is INamedTypeSymbol collection && IsEventStoreCollection(collection)) - { - yield return collection.TypeArguments[0]; - yield break; + yield return memberType; } - yield return memberType; - } + static bool IsEventStoreCollection(INamedTypeSymbol type) => + type.IsGenericType + && type.TypeArguments.Length == 1 + && TypeHelpers.Is(type, TypeLibrary.EventStoreList, TypeLibrary.EventStoreSet); - static bool IsEventStoreCollection(INamedTypeSymbol type) => - type.IsGenericType - && type.TypeArguments.Length == 1 - && TypeHelpers.Is(type, TypeLibrary.EventStoreList, TypeLibrary.EventStoreSet); - - static bool ImplementsGenericEnumerable(ITypeSymbol type) => - type is INamedTypeSymbol named - && named.AllInterfaces.Any(static candidate => - candidate.IsGenericType - && candidate.ConstructedFrom.SpecialType == SpecialType.System_Collections_Generic_IEnumerable_T - ); - - static bool IsInspectableType(ITypeSymbol type) => - type is INamedTypeSymbol named - && !named.IsStatic - && !named.IsAbstract - && named.SpecialType == SpecialType.None - && named.TypeKind is TypeKind.Class or TypeKind.Struct - && named.ContainingNamespace is not null - && !named.ContainingNamespace.ToDisplayString().StartsWith("System", StringComparison.Ordinal); - - static ITypeSymbol UnwrapNullable(ITypeSymbol type) => - type is INamedTypeSymbol { IsGenericType: true } nullable - && nullable.ConstructedFrom.SpecialType == SpecialType.System_Nullable_T - ? nullable.TypeArguments[0] - : type; + static bool ImplementsGenericEnumerable(ITypeSymbol type) => + type is INamedTypeSymbol named + && named.AllInterfaces.Any(static candidate => + candidate.IsGenericType + && candidate.ConstructedFrom.SpecialType == SpecialType.System_Collections_Generic_IEnumerable_T + ); + + static bool IsInspectableType(ITypeSymbol type) => + type is INamedTypeSymbol named + && !named.IsStatic + && !named.IsAbstract + && named.SpecialType == SpecialType.None + && named.TypeKind is TypeKind.Class or TypeKind.Struct + && named.ContainingNamespace is not null + && !named.ContainingNamespace.ToDisplayString().StartsWith("System", StringComparison.Ordinal); + + static ITypeSymbol UnwrapNullable(ITypeSymbol type) => + type is INamedTypeSymbol { IsGenericType: true } nullable + && nullable.ConstructedFrom.SpecialType == SpecialType.System_Nullable_T + ? nullable.TypeArguments[0] + : type; + } } diff --git a/src/src/EntityFrameworkCore.SourceGenerator/EFSourceGenerator.cs b/src/src/EntityFrameworkCore.SourceGenerator/EFSourceGenerator.cs index d6fa6ebb..4de4d818 100644 --- a/src/src/EntityFrameworkCore.SourceGenerator/EFSourceGenerator.cs +++ b/src/src/EntityFrameworkCore.SourceGenerator/EFSourceGenerator.cs @@ -12,7 +12,7 @@ public void Initialize(IncrementalGeneratorInitializationContext context) .RegisterEmbeddedAttribute() .RegisterPostInitializationOutput(static output => { - foreach (var (hintName, source) in AttributeEmiiter.GetAttributeSources()) + foreach (var (hintName, source) in AttributeEmitter.GetAttributeSources()) output.AddSource(hintName, source); }); } diff --git a/src/src/EntityFrameworkCore.SourceGenerator/Emitters/AttributeEmiiter.cs b/src/src/EntityFrameworkCore.SourceGenerator/Emitters/AttributeEmitter.cs similarity index 97% rename from src/src/EntityFrameworkCore.SourceGenerator/Emitters/AttributeEmiiter.cs rename to src/src/EntityFrameworkCore.SourceGenerator/Emitters/AttributeEmitter.cs index a6cdf8c2..627ae0e2 100644 --- a/src/src/EntityFrameworkCore.SourceGenerator/Emitters/AttributeEmiiter.cs +++ b/src/src/EntityFrameworkCore.SourceGenerator/Emitters/AttributeEmitter.cs @@ -1,9 +1,9 @@ using Microsoft.CodeAnalysis.Text; -using Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.Heleprs; +using Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.Helpers; namespace Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.Emitters; -static class AttributeEmiiter +static class AttributeEmitter { public static IEnumerable<(string HintName, SourceText Source)> GetAttributeSources() { diff --git a/src/src/EntityFrameworkCore.SourceGenerator/Extensions/System/Runtime/CompilerServices/IsExternalInit.cs b/src/src/EntityFrameworkCore.SourceGenerator/Extensions/System/Runtime/CompilerServices/IsExternalInit.cs deleted file mode 100644 index ae5a5983..00000000 --- a/src/src/EntityFrameworkCore.SourceGenerator/Extensions/System/Runtime/CompilerServices/IsExternalInit.cs +++ /dev/null @@ -1,15 +0,0 @@ -#if NETSTANDARD2_0 || NETSTANDARD2_1_OR_GREATER || NETCOREAPP2_0 || NETCOREAPP2_1 || NETCOREAPP2_2 || NETCOREAPP3_0 || NETCOREAPP3_1 || NET45 || NET451 || NET452 || NET6 || NET461 || NET462 || NET47 || NET471 || NET472 || NET48 - -using System.ComponentModel; - -// Compilation error of CS0518 IsExternalInit is not defined when using .NET Standard. -// re: https://mking.net/blog/error-cs0518-isexternalinit-not-defined -#pragma warning disable IDE0130 // Namespace does not match folder structure -namespace System.Runtime.CompilerServices; - -#pragma warning restore IDE0130 // Namespace does not match folder structure - -[EditorBrowsable(EditorBrowsableState.Never)] -static class IsExternalInit; - -#endif diff --git a/src/src/EntityFrameworkCore.SourceGenerator/Heleprs/DiagnosticLibrary.cs b/src/src/EntityFrameworkCore.SourceGenerator/Helpers/DiagnosticLibrary.cs similarity index 99% rename from src/src/EntityFrameworkCore.SourceGenerator/Heleprs/DiagnosticLibrary.cs rename to src/src/EntityFrameworkCore.SourceGenerator/Helpers/DiagnosticLibrary.cs index 436792ed..1f7c4de2 100644 --- a/src/src/EntityFrameworkCore.SourceGenerator/Heleprs/DiagnosticLibrary.cs +++ b/src/src/EntityFrameworkCore.SourceGenerator/Helpers/DiagnosticLibrary.cs @@ -1,7 +1,7 @@ using System.Collections.Immutable; using Microsoft.CodeAnalysis; -namespace Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.Heleprs; +namespace Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.Helpers; static class DiagnosticLibrary { diff --git a/src/src/EntityFrameworkCore.SourceGenerator/Heleprs/TypeLibrary.cs b/src/src/EntityFrameworkCore.SourceGenerator/Helpers/TypeLibrary.cs similarity index 99% rename from src/src/EntityFrameworkCore.SourceGenerator/Heleprs/TypeLibrary.cs rename to src/src/EntityFrameworkCore.SourceGenerator/Helpers/TypeLibrary.cs index c3a72bfa..733f7407 100644 --- a/src/src/EntityFrameworkCore.SourceGenerator/Heleprs/TypeLibrary.cs +++ b/src/src/EntityFrameworkCore.SourceGenerator/Helpers/TypeLibrary.cs @@ -1,4 +1,4 @@ -namespace Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.Heleprs; +namespace Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.Helpers; static class TypeLibrary { diff --git a/src/src/EventSourcing/Sdk/buildTransitive/Purview.EventSourcing.targets b/src/src/EventSourcing/Sdk/buildTransitive/Purview.EventSourcing.targets index 8cd8440a..2b99b93c 100644 --- a/src/src/EventSourcing/Sdk/buildTransitive/Purview.EventSourcing.targets +++ b/src/src/EventSourcing/Sdk/buildTransitive/Purview.EventSourcing.targets @@ -1,4 +1,10 @@ + Specifies whether to disable the Purview EventSourcing source generators. diff --git a/src/src/SourceGenerator/Common/EventContractManifestLibrary.cs b/src/src/SourceGenerator/Common/EventContractManifestLibrary.cs index 614a6be4..9431f6c8 100644 --- a/src/src/SourceGenerator/Common/EventContractManifestLibrary.cs +++ b/src/src/SourceGenerator/Common/EventContractManifestLibrary.cs @@ -1,5 +1,7 @@ +using System.Globalization; using System.Text; using Microsoft.CodeAnalysis.Text; +using Purview.EventSourcing.SourceGenerator.Generators; namespace Purview.EventSourcing.SourceGenerator.Common; @@ -21,6 +23,8 @@ static class EventContractManifestLibrary public const string GeneratedHintName = "EventContractManifest.g.cs"; + const string GeneratedNamespace = "Purview.EventSourcing.Generated"; + public static string CreateAggregateKey(string aggregateNamespace, string aggregateName) => $"{aggregateNamespace}\0{aggregateName}"; @@ -135,32 +139,47 @@ public static SourceText EmitSource(EventContractManifest manifest) var json = Serialize(manifest); var escaped = json.Replace("\\", "\\\\").Replace("\"", "\\\""); - StringBuilder builder = new(256 + escaped.Length); - builder.AppendLine("// "); - builder.AppendLine("#nullable enable"); - builder.AppendLine(); - builder.AppendLine("namespace Purview.EventSourcing.Generated"); - builder.AppendLine("{"); - builder.AppendLine(" /// "); - builder.AppendLine(" /// The deterministic event-contract manifest for this compilation."); - builder.AppendLine( - " /// Register it at startup with AddEventContractManifest to enable runtime and Admin inspection." - ); - builder.AppendLine(" /// "); - builder.AppendLine(" public static class EventContractManifest"); - builder.AppendLine(" {"); - builder.AppendLine(" /// The manifest format version."); - builder.AppendLine( - $" public const int FormatVersion = {manifest.FormatVersion.ToString(System.Globalization.CultureInfo.InvariantCulture)};" - ); - builder.AppendLine(); - builder.AppendLine(" /// The event-contract manifest serialized as compact JSON."); - builder.AppendLine(" public const string Json ="); - builder.AppendLine($" \"{escaped}\";"); - builder.AppendLine(" }"); - builder.AppendLine("}"); - - return SourceText.From(builder.ToString(), Encoding.UTF8); + CodeWriter writer = new(SourceGenLibrary.CreateGenerationSettings()); + + writer.AutoGeneratedHeader().FileScopedNamespace(GeneratedNamespace); + + TypeIdentity intType = new("int", null); + TypeIdentity stringType = new("string", null); + + writer + .XmlSummary( + "The deterministic event-contract manifest for this compilation.", + "Register it at startup with AddEventContractManifest to enable runtime and Admin inspection." + ) + .Class( + new("EventContractManifest", TypeDeclarationAccessibility.Public) { IsStatic = true }, + body => + { + body.XmlSummary("The manifest format version.") + .Field( + new("FormatVersion", intType, TypeDeclarationAccessibility.Public) + { + IsConst = true, + Initializer = manifest.FormatVersion.ToString(CultureInfo.InvariantCulture), + IncludeGeneratedAttributes = false, + } + ); + + body.NewLine(); + + body.XmlSummary("The event-contract manifest serialized as compact JSON.") + .Field( + new("Json", stringType, TypeDeclarationAccessibility.Public) + { + IsConst = true, + Initializer = $"\"{escaped}\"", + IncludeGeneratedAttributes = false, + } + ); + } + ); + + return SourceText.From(writer.ToString(), Encoding.UTF8); } static void AppendString(StringBuilder builder, string value) diff --git a/src/src/SourceGenerator/Extensions/System/Runtime/CompilerServices/IsExternalInit.cs b/src/src/SourceGenerator/Extensions/System/Runtime/CompilerServices/IsExternalInit.cs deleted file mode 100644 index ae5a5983..00000000 --- a/src/src/SourceGenerator/Extensions/System/Runtime/CompilerServices/IsExternalInit.cs +++ /dev/null @@ -1,15 +0,0 @@ -#if NETSTANDARD2_0 || NETSTANDARD2_1_OR_GREATER || NETCOREAPP2_0 || NETCOREAPP2_1 || NETCOREAPP2_2 || NETCOREAPP3_0 || NETCOREAPP3_1 || NET45 || NET451 || NET452 || NET6 || NET461 || NET462 || NET47 || NET471 || NET472 || NET48 - -using System.ComponentModel; - -// Compilation error of CS0518 IsExternalInit is not defined when using .NET Standard. -// re: https://mking.net/blog/error-cs0518-isexternalinit-not-defined -#pragma warning disable IDE0130 // Namespace does not match folder structure -namespace System.Runtime.CompilerServices; - -#pragma warning restore IDE0130 // Namespace does not match folder structure - -[EditorBrowsable(EditorBrowsableState.Never)] -static class IsExternalInit; - -#endif diff --git a/src/src/SourceGenerator/Sdk/buildTransitive/Purview.EventSourcing.SourceGenerator.targets b/src/src/SourceGenerator/Sdk/buildTransitive/Purview.EventSourcing.SourceGenerator.targets new file mode 100644 index 00000000..308022fe --- /dev/null +++ b/src/src/SourceGenerator/Sdk/buildTransitive/Purview.EventSourcing.SourceGenerator.targets @@ -0,0 +1,25 @@ + + + + + Specifies whether to disable the Purview EventSourcing source generators. + + + When true, the Purview EventSourcing generator emits the deterministic event-contract manifest as generated source and materializes it to EventContractManifest.json after build. + + + Overrides the AdditionalFiles name (default EventContractManifest.json) used as the approved event-contract baseline. + + + diff --git a/src/src/SourceGenerator/SourceGenerator.csproj b/src/src/SourceGenerator/SourceGenerator.csproj index 6198aed8..9fb5a2f8 100644 --- a/src/src/SourceGenerator/SourceGenerator.csproj +++ b/src/src/SourceGenerator/SourceGenerator.csproj @@ -10,6 +10,14 @@ + + + + + + + diff --git a/src/tests/EntityFrameworkCore.SourceGenerator.UnitTests/EFSnapshotShapeAnalyzerTests.cs b/src/tests/EntityFrameworkCore.SourceGenerator.UnitTests/EFSnapshotShapeAnalyzerTests.cs index 84710de6..4f0c9116 100644 --- a/src/tests/EntityFrameworkCore.SourceGenerator.UnitTests/EFSnapshotShapeAnalyzerTests.cs +++ b/src/tests/EntityFrameworkCore.SourceGenerator.UnitTests/EFSnapshotShapeAnalyzerTests.cs @@ -1,4 +1,4 @@ -using Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.Heleprs; +using Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.Helpers; namespace Purview.EventSourcing.EntityFrameworkCore.SourceGenerator; diff --git a/src/tests/EntityFrameworkCore.SourceGenerator.UnitTests/EFSourceGeneratorTestOptions.cs b/src/tests/EntityFrameworkCore.SourceGenerator.UnitTests/EFSourceGeneratorTestOptions.cs index 3bfca0c3..501fa708 100644 --- a/src/tests/EntityFrameworkCore.SourceGenerator.UnitTests/EFSourceGeneratorTestOptions.cs +++ b/src/tests/EntityFrameworkCore.SourceGenerator.UnitTests/EFSourceGeneratorTestOptions.cs @@ -1,4 +1,4 @@ -using Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.Heleprs; +using Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.Helpers; namespace Purview.EventSourcing.EntityFrameworkCore.SourceGenerator; diff --git a/src/tests/EntityFrameworkCore.SourceGenerator.UnitTests/EFSourceGeneratorTests.cs b/src/tests/EntityFrameworkCore.SourceGenerator.UnitTests/EFSourceGeneratorTests.cs index 36933a0c..13a9b5e4 100644 --- a/src/tests/EntityFrameworkCore.SourceGenerator.UnitTests/EFSourceGeneratorTests.cs +++ b/src/tests/EntityFrameworkCore.SourceGenerator.UnitTests/EFSourceGeneratorTests.cs @@ -1,4 +1,4 @@ -using Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.Heleprs; +using Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.Helpers; namespace Purview.EventSourcing.EntityFrameworkCore.SourceGenerator; diff --git a/src/tests/SourceGenerator.UnitTests/Incremental/AggregateIncrementalCacheTests.cs b/src/tests/SourceGenerator.UnitTests/Incremental/AggregateIncrementalCacheTests.cs index e4a03fef..4a649559 100644 --- a/src/tests/SourceGenerator.UnitTests/Incremental/AggregateIncrementalCacheTests.cs +++ b/src/tests/SourceGenerator.UnitTests/Incremental/AggregateIncrementalCacheTests.cs @@ -72,10 +72,16 @@ public async Task IdenticalRerun_AllStagesCached(CancellationToken cancellationT "GetGenerationConfiguration", "GetGenerationContext_AggregateGenerationCapabilities", ]; + // Cached or Unchanged: the generator emits its own aggregate attributes through + // post-initialization output, so Roslyn sees a new SyntaxTree and reports the internal + // Compilation step Modified even on a byte-identical rerun. Any stage derived from the + // compilation therefore re-runs and reports Unchanged rather than Cached. Unchanged is the + // proof that value equality holds; Modified is the regression this guards against. await Assert .That( frameworkStages.All(stage => - second.TryGetValue(stage, out var reasons) && reasons.All(r => r == StepReason.Cached) + second.TryGetValue(stage, out var reasons) + && reasons.All(r => r is StepReason.Cached or StepReason.Unchanged) ) ) .IsTrue(); diff --git a/src/tests/SourceGenerator.UnitTests/Incremental/AggregateSourceGeneratorIncrementalTests.cs b/src/tests/SourceGenerator.UnitTests/Incremental/AggregateSourceGeneratorIncrementalTests.cs index cc1d72d9..40b42f0f 100644 --- a/src/tests/SourceGenerator.UnitTests/Incremental/AggregateSourceGeneratorIncrementalTests.cs +++ b/src/tests/SourceGenerator.UnitTests/Incremental/AggregateSourceGeneratorIncrementalTests.cs @@ -86,7 +86,11 @@ public async Task Generate_RerunWithUnchangedCompilation_AggregateTargetsCached( var reasons = StepReasons(result.Runs[1], "GetAggregateTargets"); await Assert.That(reasons.Length).IsEqualTo(2); - await Assert.That(reasons.All(static reason => reason == StepReason.Cached)).IsTrue(); + // Cached or Unchanged: the post-initialization attribute trees make Roslyn's internal + // Compilation step Modified on an identical rerun, so the attribute transform re-runs and + // reports Unchanged. That it is never Modified is what proves AggregateTarget's value + // equality keeps downstream stages from being invalidated. + await Assert.That(reasons.All(static reason => reason is StepReason.Cached or StepReason.Unchanged)).IsTrue(); } [Test] From 5b352e6ef7fca99f9ffd37565624100f70a53ff5 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Sun, 25 Oct 2026 11:53:44 +0000 Subject: [PATCH 06/41] chore(skills): move authored skills to the root skills folder The skills CLI only discovers skills in a root `skills/` folder and delivers them from git, so the previous `Sdk/.agents/skills` location was never reachable by it. The pack-validation rule requiring it inside the NuGet package goes with it. All three existing skills declared `category`, `roles` and `tags` as top-level frontmatter. The specification defines none of them, and a strict client rejects the skill outright. Adds skills for the result model, multi-tenancy and crypto-shredding, and a Skills.UnitTests project so the catalogue is validated rather than assumed - ValidatePurviewSkills silently passed a deliberately malformed skill, so it is not sufficient on its own. AGENTS.md now requires feature work to update both `skills/` and `docs/wiki`, and records the tenant-isolation testing rules that the defects found in this work would have been caught by. --- .../SKILL.md | 128 +++++++++++++ .../purview-containers-lifecycle/SKILL.md | 144 ++++++++++++++ .../purview-containers-quickstart/SKILL.md | 181 ++++++++++++++++++ .../purview-containers-testing/SKILL.md | 126 ++++++++++++ .../SKILL.md | 128 +++++++++++++ .../purview-containers-lifecycle/SKILL.md | 144 ++++++++++++++ .../purview-containers-quickstart/SKILL.md | 181 ++++++++++++++++++ .../purview-containers-testing/SKILL.md | 126 ++++++++++++ .config/purview-build.json | 9 +- AGENTS.md | 71 ++++++- skills-lock.json | 24 +++ .../event-sourcing-aggregate-design/SKILL.md | 18 +- .../SKILL.md | 26 +-- .../event-sourcing-crypto-shredding/SKILL.md | 104 ++++++++++ skills/event-sourcing-multi-tenancy/SKILL.md | 118 ++++++++++++ skills/event-sourcing-results/SKILL.md | 141 ++++++++++++++ .../event-sourcing-value-objects/SKILL.md | 18 +- src/tests/Skills.UnitTests/SkillTests.cs | 13 ++ .../Skills.UnitTests/Skills.UnitTests.csproj | 5 + 19 files changed, 1654 insertions(+), 51 deletions(-) create mode 100644 .agents/skills/purview-containers-consumer-requirements/SKILL.md create mode 100644 .agents/skills/purview-containers-lifecycle/SKILL.md create mode 100644 .agents/skills/purview-containers-quickstart/SKILL.md create mode 100644 .agents/skills/purview-containers-testing/SKILL.md create mode 100644 .claude/skills/purview-containers-consumer-requirements/SKILL.md create mode 100644 .claude/skills/purview-containers-lifecycle/SKILL.md create mode 100644 .claude/skills/purview-containers-quickstart/SKILL.md create mode 100644 .claude/skills/purview-containers-testing/SKILL.md rename {src/src/EventSourcing/Sdk/.agents/skills => skills}/event-sourcing-aggregate-design/SKILL.md (94%) rename {src/src/EventSourcing/Sdk/.agents/skills => skills}/event-sourcing-aggregate-validation/SKILL.md (75%) create mode 100644 skills/event-sourcing-crypto-shredding/SKILL.md create mode 100644 skills/event-sourcing-multi-tenancy/SKILL.md create mode 100644 skills/event-sourcing-results/SKILL.md rename {src/src/EventSourcing/Sdk/.agents/skills => skills}/event-sourcing-value-objects/SKILL.md (93%) create mode 100644 src/tests/Skills.UnitTests/SkillTests.cs create mode 100644 src/tests/Skills.UnitTests/Skills.UnitTests.csproj diff --git a/.agents/skills/purview-containers-consumer-requirements/SKILL.md b/.agents/skills/purview-containers-consumer-requirements/SKILL.md new file mode 100644 index 00000000..28a7ee46 --- /dev/null +++ b/.agents/skills/purview-containers-consumer-requirements/SKILL.md @@ -0,0 +1,128 @@ +--- +name: purview-containers-consumer-requirements +description: >- + Use when a project consuming Purview.Containers will not build - PCC0001 or PCC0002, CS1705 for + Microsoft.Windows.SDK.NET, CS0234/CS0246 for Microsoft.WSL types, NETSDK1100 on a Linux build agent + - or when choosing the target framework and platform for a consumer of the WSL Containers backend. +metadata: + product: Purview.Containers + repository: purview-dev/containers +--- + +# Consumer requirements + +## Which package requires what + +| Package | Target frameworks | Notes | +| --- | --- | --- | +| `Purview.Containers` | `net10.0`, any platform | the umbrella: `Core` plus both backends | +| `Purview.Containers.Core` | `net10.0`, any platform | backend-neutral abstractions | +| `Purview.Containers.` | `net10.0`, any platform | service modules; restore anywhere, need a backend to run | +| `Purview.Containers.Wsl` | `net10.0` **and** `net10.0-windows10.0.19041.0` | a portable facade plus the Windows implementation. **Everything below is its contract.** | +| `Purview.Containers.Docker` | `net10.0`, any platform | needs a reachable Docker daemon, not a Windows target framework | + +A consumer of any backend other than WSL needs only a portable `net10.0` project. + +## Most projects need nothing + +```xml +net10.0 +``` + +That binds the portable facade and gets automatic backend selection — WSLC on a Windows host, Docker +everywhere else. It is the recommended choice, and it is why a Windows developer and a Linux CI +runner can share one test project. + +A Windows-targeting project binds the implementation directly, with no run-time load: + +```xml + + net10.0-windows10.0.19041.0 + x64 + 10.0.26100.80 + +``` + +The last two lines are optional — the package ships MSBuild defaults — but stating them makes the +requirement visible to the next person reading the project file, and the defaults only fill in a +value you have not chosen. + +## The five requirements + +| # | Requirement | Why | +| --- | --- | --- | +| 1 | **.NET 10 or later** | the package ships `lib/net10.0/` (facade) and `lib/net10.0-windows10.0.19041/` (implementation) | +| 2 | **A Windows target framework that names the OS version** — *only* if you want the implementation bound directly | the `Microsoft.WSL.Containers` projection ships Windows assets only | +| 3 | **64-bit** — `PlatformTarget` `x64`/`arm64`, or a matching `RuntimeIdentifier` | the native `wslcsdk.dll` ships for `win-x64` and `win-arm64` only | +| 4 | **`WindowsSdkPackageVersion` ≥ `10.0.26100.80`** | the projection is compiled against `Microsoft.Windows.SDK.NET` `10.0.26100.79`, and the pack the SDK resolves for a `10.0.19041.0` target framework is older | +| 5 | **A Windows 10/11 host with WSL Containers**, to actually run anything | the library drives WSLC; it never installs or updates it for you | + +### Always spell out the Windows version + +```xml +net10.0-windows10.0.19041.0 +net10.0-windows +``` + +`net10.0-windows` resolves its platform version to **7.0**, older than the `10.0.19041.0` the +implementation was built against, so NuGet selects no compile assets at all. (The +`Microsoft.WSL.Containers` package is itself `net8.0-windows10.0.19041.0`, which a +`net10.0-windows10.0.19041.0` project consumes without issue.) + +## What the package does for you + +`Purview.Containers.Wsl` ships two `buildTransitive` files, imported by NuGet for **direct and +transitive** references: + +| File | Effect | +| --- | --- | +| `…Wsl.props` | defaults `WindowsSdkPackageVersion` to `10.0.26100.80` when unset, and registers the `wsl` backend | +| `…Wsl.targets` | **Windows consumer:** defaults `PlatformTarget` to `x64` when unset or `AnyCPU` and no `RuntimeIdentifier` is selected, and fails with `PCC0001`/`PCC0002` when the target framework or platform cannot be supported. **Platform-neutral consumer:** copies the Windows implementation payload — implementation, WSLC projection, its Windows SDK dependencies, the native SDK — into `wslc/` beside the output on a Windows build host, so the facade can load it at run time. | + +An explicit `PlatformTarget`, `RuntimeIdentifier` or `WindowsSdkPackageVersion` in the consumer +always wins. + +A **service module** is backend-neutral and brings no backend. Reference the module *and* a backend +package, and use `PURVIEW_CONTAINERS_BACKEND` to pin which one runs. + +> Because `buildTransitive` assets are framework-agnostic, NuGet no longer reports `NU1202` for an +> incompatible target framework: restore succeeds and the **guard target** produces the failure +> instead. That is deliberate. `PCC0001` names the required target framework, whereas an empty +> compile-asset set only produces `CS0246` errors in your own code — which blame the wrong thing. + +## Error reference + +| Error | Raised by | Means | Fix | +| --- | --- | --- | --- | +| `PCC0001` | the shipped guard target | the target framework is neither .NET 10+ on Windows `10.0.19041.0`+ nor a platform-neutral .NET 10+ framework | retarget as above | +| `PCC0002` | the shipped guard target | the consumer is not 64-bit | remove `PlatformTarget`, set it to `x64`/`arm64`, or choose a matching `RuntimeIdentifier` | +| `CS1705` naming `Microsoft.Windows.SDK.NET` | the compiler | the resolved Windows SDK targeting pack is older than the projection's | pin `WindowsSdkPackageVersion` to `10.0.26100.80` | +| `CS0234`/`CS0246` for `Microsoft.WSL`/`Purview` types | the compiler | the package contributed no compile assets — an unsupported target framework, or an unverified escape hatch | fix the target framework; `PCC0001` says the same thing more clearly | +| `NETSDK1100` | the SDK | building a Windows-targeted project on a non-Windows agent | set `EnableWindowsTargeting=true` | + +### `EnableWindowsTargeting` on a non-Windows agent + +It lets a Linux build agent *compile* a Windows-targeted project. It does **not** make the +implementation runnable there — the facade still reports `wsl` unavailable, and Docker is selected. +Use it to keep one solution building in CI, not as a way to run WSLC off Windows. + +## Verifying all of this + +The repository proves every row above rather than asserting it: + +- `Wsl.UnitTests/ConsumerRequirementsTests.cs` guards the **shape** inside the normal unit run — the + Windows build targets `.NETCoreApp,Version=v10.0`, targets `Windows10.0.19041.0`, and declares only + that OS platform. If the target framework drifts, that test fails, and this page, the package + READMEs and the `buildTransitive` defaults all have to move with it. +- `just verify-consumers` proves the **behaviour**: it packs, then builds throwaway consumer projects + for every documented outcome, including the guard errors (`PlatformTarget=x86` → `PCC0002`; + `net8.0-windows` → `PCC0001`; `net11.0-windows` without an OS version → `PCC0001`). It sits outside + the `[Category=Unit]` filter because it restores from nuget.org. + +That split is the point: **a library's own build is not a consumer**, so a claim about consumers is +only true if something builds one. + +## Related skills + +`purview-containers-quickstart` for packages and backend selection, and +`purview-containers-testing` for the test tiers and CI shape. diff --git a/.agents/skills/purview-containers-lifecycle/SKILL.md b/.agents/skills/purview-containers-lifecycle/SKILL.md new file mode 100644 index 00000000..01b84ed7 --- /dev/null +++ b/.agents/skills/purview-containers-lifecycle/SKILL.md @@ -0,0 +1,144 @@ +--- +name: purview-containers-lifecycle +description: >- + Use when reasoning about a Purview.Containers container's lifecycle or readiness - StartAsync, + StopAsync and DisposeAsync semantics, cleanup guarantees and why there is no restart, the Wait + strategy family and started-versus-ready, and WSL Containers networking, port mapping and the + absence of inter-container DNS. +metadata: + product: Purview.Containers + repository: purview-dev/containers +--- + +# Lifecycle, readiness and networking + +## The public surface + +```csharp +public interface IContainer : IAsyncDisposable +{ + Task StartAsync(CancellationToken ct = default); + Task StopAsync(CancellationToken ct = default); + ValueTask DisposeAsync(); + // restart is intentionally NOT offered +} +``` + +**There is no `RestartAsync`.** WSLC has no restart operation, and stop-then-start is not equivalent, +so offering one would be a method that quietly means something different per backend. + +WSLC's `ContainerState` runs `Invalid → Created → Running → Exited → Deleted`. + +| Operation | Behaviour | +| --- | --- | +| `StartAsync` | creates the session if needed, ensures the image per the pull policy, creates the container, starts it, then waits. A missing init binary throws `ArgumentException 0x80070057` with the OCI message, surfaced as `WslContainerStartupException`. | +| `StopAsync` | `Stop(SIGTERM, grace)`, then `Stop(SIGKILL, …)` if still running. **Idempotent** — WSLC accepts stopping an already-stopped container. | +| `DeleteAsync` | `Delete(Force)`. A double delete throws `0x80010108` (`RPC_E_DISCONNECTED`) and is swallowed. | +| `DisposeAsync` | stop if running → delete → release the WinRT object. **Idempotent.** | + +## Cleanup guarantees + +These are the ones that matter when a test throws: + +- `DisposeAsync` runs in a `finally` by callers, **and** the container object is registered for + cleanup by the runtime, so disposal happens even if a test throws after `StartAsync`. +- `EnableAutoRemove` defaults to **`false`**: the library owns deletion. WSLC auto-removal would + delete a one-shot container before its state or output could be inspected — precisely when you need + them. Opt in with `.WithAutoRemove()`. +- A **partial startup failure** — image pull, create, start or wait — tears down through the same + `DisposeAsync` path. So does a **cancelled** `StartAsync` or wait. +- A **container crash** fires `InitProcess.Exited`; the container is then `Exited` and `DisposeAsync` + deletes it. +- A **session crash** marks the runtime session dead, and subsequent operations throw + `WslContainerSessionTerminatedException` rather than failing obscurely. +- **Test-process termination** disposes the shared session through a process-exit hook, freeing the + name. A *crashed* process leaves an orphaned session that only reserves its name; sweep it with + `wslc --session system session terminate`. + +## Secrets and names + +Container names are generated uniquely as `{service}-{processId}-{random8}` and **never contain +credentials**; session names are `wslc-{pid}-{random8}`. Diagnostics redact secrets through a +`Secret` wrapper whose `ToString()` returns ``. + +## Wait strategies + +**A started container is not a ready service.** `Container.Start()` returns once the init process is +running; readiness is a separate check, and it is the one your test actually depends on. + +```text +IWaitStrategy + TimeSpan? Timeout // null -> the container's StartupTimeout + TimeSpan Interval // default 250 ms + int? Retries // optional max failed checks + Task UntilAsync(WaitContext context, CancellationToken ct) + +WaitContext { IContainer Container; string? NetworkIp; int? GetHostPort(ushort); int? FirstHostPort; } +``` + +| Factory | Checks | +| --- | --- | +| `Wait.ForContainerRunning()` | `State == Running`. **Started, not ready.** | +| `Wait.ForTcpPort(8080)` | connects to `127.0.0.1:`. IPv4 only. | +| `Wait.ForHttp("/health")` | `.ForPort`, `.ForScheme`, `.ForStatusCode`, `.ForStatusPredicate`, `.ForHeader`, `.AllowInsecureTls` | +| `Wait.ForLogMessage(string \| Regex)` | case-insensitive substring, or regex, against **accumulated** init-process output | +| `Wait.ForCommand("pg_isready", "-U", "postgres")` | runs it via `ExecAsync`; ready at the expected exit code (default 0, `.ForExitCode(…)`) | +| `Wait.ForCustom((context, ct) => …)` | anything else | +| `Wait.ForAll(…)` / `Wait.ForAny(…)` | every strategy ready on the same check / at least one | + +Fluent modifiers: `.WithTimeout(…)`, `.WithInterval(…)`, `.WithRetries(…)`. + +Details worth knowing: + +- Waits run **inside** `StartAsync()`, after the container starts. `StartAsync` only returns when + every strategy is ready, or throws `ContainerTimeoutException`. +- The default timeout is the container's `StartupTimeout` — 5 minutes, overridable with + `.WithStartupTimeout(…)` or per-strategy. +- A timeout diagnostic includes the container name, image, state, mapped ports, the strategy type, + the last check error, and a bounded, secret-redacted tail of stdout/stderr. +- The container buffers output from process start, so a log message emitted **before** the waiter's + first check still matches. +- HTTP TLS validation is **on** by default. `AllowInsecureTls()` disables it for that request handler + only, never globally. +- Transient exec failures during startup count as not-ready, not as failure. + +Modules pick their own readiness check: PostgreSQL `pg_isready`, Redis `redis-cli ping`, RabbitMQ +`rabbitmq-diagnostics ping`, SQL Server a host-side connection. + +## Networking + +| `ContainerNetworkingMode` | Effect | Port mappings | +| --- | --- | --- | +| `null` (raw default) | Docker `NetworkMode: "none"` — no network, no IP | `CreateContainer` throws `0x80070057` | +| `None` | the same | no | +| `Bridged` | `172.17.0.x` on the session bridge; host→container mapped ports work | yes | + +`ContainerBuilder` defaults to **`Bridged`**, because a container with no network is not useful. + +Verified WSLC behaviour, and the parts that surprise people: + +- The host bind address is **IPv4 loopback only** (`HostIp: 127.0.0.1`). IPv6 `::1` does not connect. +- **Clients must use `127.0.0.1`, not `localhost`.** `localhost` resolves to `::1` first on .NET. + Npgsql and StackExchange.Redis fall back to IPv4; `Microsoft.Data.SqlClient` **hangs** without + falling back. +- Containers in the same session **can** reach each other by IP under `Bridged`. +- There is **no name or DNS resolution between containers**. `http://:8080/` and + `http://:8080/` fail with "bad address"; `/etc/hosts` holds only localhost and the + container's own `IP `. +- There are **no managed network objects** — `Microsoft.WSL.Containers` has no `network + create/connect`, unlike the CLI. + +How the library models it: `GetMappedPublicPort(containerPort)` reads +`Inspect().Ports["/tcp"][0].HostPort`; `GetNetworkIp()` reads +`Inspect().NetworkSettings.Networks.bridge.IPAddress` (Bridged only); TCP and HTTP waits connect to +`127.0.0.1:`. + +**What not to model.** Do not invent Docker-style `Network` objects — the semantics are just "bridged +with IPs". Do not claim container-name resolution works; it does not. Multi-container environments +are deliberately deferred, and would wire containers together by passing each other's IPs from +`GetNetworkIp()` into configuration or environment — which is why the core API does not preclude it. + +## Related skills + +`purview-containers-quickstart` for packages, backends and connection strings; +`purview-containers-testing` for how a suite is organised and why it runs serially. diff --git a/.agents/skills/purview-containers-quickstart/SKILL.md b/.agents/skills/purview-containers-quickstart/SKILL.md new file mode 100644 index 00000000..c90b6c10 --- /dev/null +++ b/.agents/skills/purview-containers-quickstart/SKILL.md @@ -0,0 +1,181 @@ +--- +name: purview-containers-quickstart +description: >- + Use when adding throwaway containers to a .NET test suite with Purview.Containers - which package to + reference, how the WSL Containers and Docker backends are selected automatically, running a generic + container with ContainerBuilder, using a typed service module, and getting a connection string. +metadata: + product: Purview.Containers + repository: purview-dev/containers +--- + +# Purview.Containers quickstart + +Throwaway Linux containers for .NET tests, behind one API, over either **WSL Containers** (no Docker +installation on Windows) or **Docker** (anywhere). The same test code runs on both. + +> **Experimental and prerelease.** The API, defaults and packaging rules can change between releases. +> Pin the version you adopt. + +## Which package + +| Package | Use it when | +| --- | --- | +| `Purview.Containers` | the umbrella: `Core` plus both backends. One reference, zero config — WSLC on Windows, Docker elsewhere. **The default.** | +| `Purview.Containers.Wsl` | WSL Containers only — a Windows machine with no Docker. | +| `Purview.Containers.Docker` | Docker only — any platform, CI, Linux/macOS. A Linux-only job can skip the WSL backend's ~19 MB payload with `Core` + `.Docker`. | + +A service module is backend-neutral, so it needs a backend (or the umbrella) alongside it: + +```bash +dotnet add package Purview.Containers.PostgreSql +dotnet add package Purview.Containers +``` + +## The zero-config shape + +```xml + + + net10.0 + + + + + + + +``` + +Three things make it work, and nothing else is required: + +- **A platform-neutral target framework** (`net10.0`). `Purview.Containers.Wsl` is multi-targeted; a + `net10.0` project binds its **portable facade**, which runs the WSLC implementation on Windows and + reports `wsl` unavailable everywhere else. A Windows target framework binds the implementation + directly — and then cannot run on a Linux CI runner. +- **The umbrella package**, bringing `Core` and both backends. +- **No registration line and no environment variable.** Each backend package ships `buildTransitive` + assets that generate a module initializer in your assembly, so the process discovers the registered + backends itself. Those assets flow transitively through the umbrella. + +## Backend selection + +| Host | Selected | Why | +| --- | --- | --- | +| Windows with WSL Containers | `wsl` | the facade loads the WSLC implementation, and WSLC is preferred | +| Windows with Docker only | `docker` | the facade reports `wsl` unavailable, so selection falls through | +| Linux / macOS | `docker` | the facade only ever activates on Windows | + +Selection probes the registered backends in priority order (`wsl` is `0`, `docker` is `100`) and +returns the first that is both **available** and **compatible**. When none is usable, the exception +lists each backend's availability, version and missing components. + +```csharp +foreach (var backend in await ContainerBackends.ProbeAllAsync()) + Console.WriteLine($"{backend.Name}: usable={backend.IsUsable} version={backend.Version}"); +``` + +```bash +PURVIEW_CONTAINERS_BACKEND=docker # or wsl - fail loudly instead of falling back +``` + +A **named** backend never silently falls back: if it cannot run, the test fails with that backend's own +diagnostics. That is usually what you want in CI. + +The library never installs a runtime. `WslContainerRuntime.GetInfoAsync()` and +`DockerContainerBackend.GetInfoAsync()` report what is missing. Verify a host with `wsl --version` and +`wslc version`, or `docker info`. + +## A generic container + +```csharp +using Purview.Containers; +using Purview.Containers.Waiting; + +await using var container = new ContainerBuilder() + .WithImage("docker.io/library/redis:latest") + .WithPortBinding(6379, assignRandomHostPort: true) + .WithWaitStrategy(Wait.ForTcpPort(6379)) + .Build(); + +await container.StartAsync(); + +ushort port = container.GetMappedPublicPort(6379); +``` + +`Build()` validates the accumulated configuration and resolves the backend when the container starts. +`StartAsync()` creates the container, starts it, and **only returns once every configured wait +strategy is satisfied**. `DisposeAsync()` stops and deletes the container — and never terminates a +shared WSLC session. + +## A typed module + +```csharp +using Npgsql; +using Purview.Containers.PostgreSql; + +await using var postgres = new PostgreSqlBuilder() + .WithDatabase("tests") + .WithUsername("postgres") + .WithPassword("postgres") + .Build(); + +await postgres.StartAsync(); // returns once pg_isready succeeds + +await using var connection = new NpgsqlConnection(postgres.GetConnectionString()); +await connection.OpenAsync(); +``` + +No image names, no ports, no `docker`, no `wslc`. The default image, the random host port mapping and +the readiness check all come from the module. + +Modules: PostgreSQL, Redis, SQL Server, MySQL, RabbitMQ, Azurite, NATS and the Azure Key Vault +Emulator. Each ships a README inside its own package. + +## Connection strings + +Every container implements `IConnectionStringProvider`, so you can ask any container without knowing +its module type: + +```csharp +string connectionString = container.GetConnectionString(); // ConnectionMode.Host +string same = container.GetConnectionString(ConnectionMode.Host); +``` + +| Mode | Meaning | Support | +| --- | --- | --- | +| `Host` | test host → container, via the mapped host port (`127.0.0.1:{port}`) | both backends | +| `Container` | container → container, via the container network | **not supported** — throws `ConnectionStringModeNotSupportedException` | + +Container-to-container is deliberately deferred: WSLC has no managed networks or inter-container DNS, +and the Docker backend does not attach containers to a shared network. + +**Use `127.0.0.1`, never `localhost`.** `localhost` resolves to `::1` first on .NET, and while most +clients fall back to IPv4, `Microsoft.Data.SqlClient` **hangs** on `::1` without falling back — which +is why the SQL Server module's connection strings are explicitly `127.0.0.1,{port}`. + +### A custom provider + +```csharp +sealed class ReadOnlyPostgreSql : ContainerConnectionStringProvider +{ + protected override string GetHostConnectionString() => + $"{Container.GetConnectionString()};ApplicationName=readonly"; +} + +var postgres = new PostgreSqlBuilder() + .WithConnectionStringProvider(new ReadOnlyPostgreSql()) + .Build(); +``` + +`Configure` runs once, **after** the container has started, so runtime-assigned ports are available. A +provider producing an empty string throws `ConnectionStringNotAvailableException`; one used before +`Configure` throws `ConnectionStringProviderNotConfiguredException`. The named overload +(`GetConnectionString(name, mode)`) exists for modules with several endpoints and otherwise throws +`ConnectionStringNameNotSupportedException`. + +## Related skills + +`purview-containers-lifecycle` for start/stop/dispose semantics, wait strategies and networking; +`purview-containers-testing` for suite layout, serial execution and CI; and +`purview-containers-consumer-requirements` for the target-framework contract and the `PCC` guards. diff --git a/.agents/skills/purview-containers-testing/SKILL.md b/.agents/skills/purview-containers-testing/SKILL.md new file mode 100644 index 00000000..5d8be988 --- /dev/null +++ b/.agents/skills/purview-containers-testing/SKILL.md @@ -0,0 +1,126 @@ +--- +name: purview-containers-testing +description: >- + Use when organising or running a test suite that uses Purview.Containers - the Unit and Integration + tiers, why test modules must run serially under WSL Containers, pinning or skipping a backend, + running the Docker suites in CI and the WSL suites on a self-hosted runner, and verifying the + consumer contract. +metadata: + product: Purview.Containers + repository: purview-dev/containers +--- + +# Testing with containers + +## Tiers + +The SDK stamps every test assembly with a TUnit category derived from the **project name**, so the +tier is a property of the project rather than of a hand-written attribute: + +| Project | Category | Runtime needed | +| --- | --- | --- | +| `*.UnitTests` | `Unit` | none — logic, parsing, configuration, wait-strategy units, in-process fakes | +| `Wsl.*` and module `*.IntegrationTests` | `Integration` | a **WSLC host** | +| `Docker.IntegrationTests`, `Modules.DockerIntegrationTests` | `Integration` | any **Docker daemon**; these target `net10.0`, so they run on Linux too | + +The shared pipeline filters to `/*/*/*/*[Category=Unit]`, so **the standard pipeline never starts a +container**. The Docker suites are the exception: the PR workflow adds an `integration-docker` job on +`ubuntu-latest`. That job is the standing proof that the library and every service module work off +Windows and WSL — the same modules a developer runs on WSLC locally. + +```powershell +just test # every discovered project +just test '/*/*/*/*[Category=Unit]' # unit only +just test '/*/*/*/*[Category=Integration]' --max-parallel-test-modules 1 +just test src/tests/Docker.IntegrationTests/Docker.IntegrationTests.csproj +``` + +Filtering uses TUnit's `--treenode-filter`, not `--filter`: this runs on Microsoft.Testing.Platform, +where `dotnet test --filter` reports "Zero tests ran". + +## Why test modules run serially + +A WSLC session takes an **exclusive lock on its `storage.vhdx`**, and takes it lazily on first store +access rather than at session start. Running test assemblies in parallel therefore makes the losers +fail: + +```text +0x80070020: The process cannot access the file because it is being used by another process. +``` + +`just test` passes `--max-parallel-test-modules 1` for exactly that reason. The runtime verifies the +store once and transparently falls back to an isolated per-process store, but serial modules keep the +**warm shared image cache** — no per-process re-pull — and are the fastest option. + +In Visual Studio, untick **Run Tests in Parallel** (or set *Maximum Parallel Test Projects* to 1) +before running the WSLC integration suites. + +## Choosing a backend in a suite + +Automatic detection prefers WSLC and falls back to Docker, so a WSLC host runs the WSLC suites and a +Docker-only host runs the Docker ones. Pin one to **fail loudly instead of falling back** — +usually what you want in CI: + +```bash +PURVIEW_CONTAINERS_BACKEND=wsl # or docker +``` + +Both halves skip themselves when their runtime is unreachable: the Docker suites when no daemon +responds, the WSLC suites when the host lacks the WSL Containers components. That is what lets a +machine without WSLC still run the unit tier — and it is also why a mis-provisioned CI runner reports +*successes with skips* rather than real coverage. Print `wsl --version` and `wslc version` as the +job's first step so that failure is visible immediately. + +## CI shape + +- **Docker half** — runs on every pull request, on `ubuntu-latest`. +- **WSL half** — cannot: it needs a Windows host with WSL Containers, which no GitHub-hosted runner + provides. It is a **manual** workflow on a self-hosted runner: + + ```bash + gh workflow run "Integration (WSL Containers)" --ref main + gh run watch + ``` + + It runs `Wsl.IntegrationTests` then each service-module suite **one project at a time**, so the + shared WSLC image store is never contended. Inputs: `ref` and `filter` (a treenode filter). + +Self-hosted runner prerequisites: a **Windows x64** runner labelled `self-hosted` and `wslc`, with +WSL Containers installed (`wsl --install --no-distribution`) and the pinned .NET SDK. Tell +`actionlint` about the custom label in `.github/actionlint.yaml`. + +> The shared pipeline runs on `ubuntu-latest`, so it builds the portable `net10.0` projects **and** +> the Windows-targeted test projects on Linux. That works only because `src/Directory.Build.props` +> sets `EnableWindowsTargeting=true`; without it the SDK reports `NETSDK1100`. + +## Expectations + +`Wsl.IntegrationTests` runs many real containers in one session and can take several minutes, because +WSLC serialises container operations. Slow-test warnings while it runs are expected, not a signal. + +## Verifying the consumer contract + +Two layers, and the split matters. + +**Shape, inside the unit run.** `Wsl.UnitTests/ConsumerRequirementsTests.cs` asserts that the Windows +build targets `.NETCoreApp,Version=v10.0`, targets `Windows10.0.19041.0`, and declares only that OS +platform. If the target framework drifts, that test fails — and the consumer-requirements page, the +package READMEs and the shipped `buildTransitive` defaults all have to move with it. + +**Behaviour, outside it.** `just verify-consumers` packs the packages and builds throwaway consumer +projects for every documented outcome — the happy paths *and* the documented guard errors. It is +deliberately outside the `[Category=Unit]` filter because it packs and restores from nuget.org: + +```powershell +just verify-consumers # 21 consumer projects, all assertions +just verify-consumers -Keep # keep the generated projects for inspection +``` + +This is the general rule worth copying: **a library's own build is not a consumer**, so a claim about +consumers is only true if something builds one. + +## Related skills + +`purview-containers-quickstart` for the packages and backend selection, +`purview-containers-lifecycle` for readiness and cleanup, and +`purview-containers-consumer-requirements` for the target-framework contract and `PCC` guards. diff --git a/.claude/skills/purview-containers-consumer-requirements/SKILL.md b/.claude/skills/purview-containers-consumer-requirements/SKILL.md new file mode 100644 index 00000000..28a7ee46 --- /dev/null +++ b/.claude/skills/purview-containers-consumer-requirements/SKILL.md @@ -0,0 +1,128 @@ +--- +name: purview-containers-consumer-requirements +description: >- + Use when a project consuming Purview.Containers will not build - PCC0001 or PCC0002, CS1705 for + Microsoft.Windows.SDK.NET, CS0234/CS0246 for Microsoft.WSL types, NETSDK1100 on a Linux build agent + - or when choosing the target framework and platform for a consumer of the WSL Containers backend. +metadata: + product: Purview.Containers + repository: purview-dev/containers +--- + +# Consumer requirements + +## Which package requires what + +| Package | Target frameworks | Notes | +| --- | --- | --- | +| `Purview.Containers` | `net10.0`, any platform | the umbrella: `Core` plus both backends | +| `Purview.Containers.Core` | `net10.0`, any platform | backend-neutral abstractions | +| `Purview.Containers.` | `net10.0`, any platform | service modules; restore anywhere, need a backend to run | +| `Purview.Containers.Wsl` | `net10.0` **and** `net10.0-windows10.0.19041.0` | a portable facade plus the Windows implementation. **Everything below is its contract.** | +| `Purview.Containers.Docker` | `net10.0`, any platform | needs a reachable Docker daemon, not a Windows target framework | + +A consumer of any backend other than WSL needs only a portable `net10.0` project. + +## Most projects need nothing + +```xml +net10.0 +``` + +That binds the portable facade and gets automatic backend selection — WSLC on a Windows host, Docker +everywhere else. It is the recommended choice, and it is why a Windows developer and a Linux CI +runner can share one test project. + +A Windows-targeting project binds the implementation directly, with no run-time load: + +```xml + + net10.0-windows10.0.19041.0 + x64 + 10.0.26100.80 + +``` + +The last two lines are optional — the package ships MSBuild defaults — but stating them makes the +requirement visible to the next person reading the project file, and the defaults only fill in a +value you have not chosen. + +## The five requirements + +| # | Requirement | Why | +| --- | --- | --- | +| 1 | **.NET 10 or later** | the package ships `lib/net10.0/` (facade) and `lib/net10.0-windows10.0.19041/` (implementation) | +| 2 | **A Windows target framework that names the OS version** — *only* if you want the implementation bound directly | the `Microsoft.WSL.Containers` projection ships Windows assets only | +| 3 | **64-bit** — `PlatformTarget` `x64`/`arm64`, or a matching `RuntimeIdentifier` | the native `wslcsdk.dll` ships for `win-x64` and `win-arm64` only | +| 4 | **`WindowsSdkPackageVersion` ≥ `10.0.26100.80`** | the projection is compiled against `Microsoft.Windows.SDK.NET` `10.0.26100.79`, and the pack the SDK resolves for a `10.0.19041.0` target framework is older | +| 5 | **A Windows 10/11 host with WSL Containers**, to actually run anything | the library drives WSLC; it never installs or updates it for you | + +### Always spell out the Windows version + +```xml +net10.0-windows10.0.19041.0 +net10.0-windows +``` + +`net10.0-windows` resolves its platform version to **7.0**, older than the `10.0.19041.0` the +implementation was built against, so NuGet selects no compile assets at all. (The +`Microsoft.WSL.Containers` package is itself `net8.0-windows10.0.19041.0`, which a +`net10.0-windows10.0.19041.0` project consumes without issue.) + +## What the package does for you + +`Purview.Containers.Wsl` ships two `buildTransitive` files, imported by NuGet for **direct and +transitive** references: + +| File | Effect | +| --- | --- | +| `…Wsl.props` | defaults `WindowsSdkPackageVersion` to `10.0.26100.80` when unset, and registers the `wsl` backend | +| `…Wsl.targets` | **Windows consumer:** defaults `PlatformTarget` to `x64` when unset or `AnyCPU` and no `RuntimeIdentifier` is selected, and fails with `PCC0001`/`PCC0002` when the target framework or platform cannot be supported. **Platform-neutral consumer:** copies the Windows implementation payload — implementation, WSLC projection, its Windows SDK dependencies, the native SDK — into `wslc/` beside the output on a Windows build host, so the facade can load it at run time. | + +An explicit `PlatformTarget`, `RuntimeIdentifier` or `WindowsSdkPackageVersion` in the consumer +always wins. + +A **service module** is backend-neutral and brings no backend. Reference the module *and* a backend +package, and use `PURVIEW_CONTAINERS_BACKEND` to pin which one runs. + +> Because `buildTransitive` assets are framework-agnostic, NuGet no longer reports `NU1202` for an +> incompatible target framework: restore succeeds and the **guard target** produces the failure +> instead. That is deliberate. `PCC0001` names the required target framework, whereas an empty +> compile-asset set only produces `CS0246` errors in your own code — which blame the wrong thing. + +## Error reference + +| Error | Raised by | Means | Fix | +| --- | --- | --- | --- | +| `PCC0001` | the shipped guard target | the target framework is neither .NET 10+ on Windows `10.0.19041.0`+ nor a platform-neutral .NET 10+ framework | retarget as above | +| `PCC0002` | the shipped guard target | the consumer is not 64-bit | remove `PlatformTarget`, set it to `x64`/`arm64`, or choose a matching `RuntimeIdentifier` | +| `CS1705` naming `Microsoft.Windows.SDK.NET` | the compiler | the resolved Windows SDK targeting pack is older than the projection's | pin `WindowsSdkPackageVersion` to `10.0.26100.80` | +| `CS0234`/`CS0246` for `Microsoft.WSL`/`Purview` types | the compiler | the package contributed no compile assets — an unsupported target framework, or an unverified escape hatch | fix the target framework; `PCC0001` says the same thing more clearly | +| `NETSDK1100` | the SDK | building a Windows-targeted project on a non-Windows agent | set `EnableWindowsTargeting=true` | + +### `EnableWindowsTargeting` on a non-Windows agent + +It lets a Linux build agent *compile* a Windows-targeted project. It does **not** make the +implementation runnable there — the facade still reports `wsl` unavailable, and Docker is selected. +Use it to keep one solution building in CI, not as a way to run WSLC off Windows. + +## Verifying all of this + +The repository proves every row above rather than asserting it: + +- `Wsl.UnitTests/ConsumerRequirementsTests.cs` guards the **shape** inside the normal unit run — the + Windows build targets `.NETCoreApp,Version=v10.0`, targets `Windows10.0.19041.0`, and declares only + that OS platform. If the target framework drifts, that test fails, and this page, the package + READMEs and the `buildTransitive` defaults all have to move with it. +- `just verify-consumers` proves the **behaviour**: it packs, then builds throwaway consumer projects + for every documented outcome, including the guard errors (`PlatformTarget=x86` → `PCC0002`; + `net8.0-windows` → `PCC0001`; `net11.0-windows` without an OS version → `PCC0001`). It sits outside + the `[Category=Unit]` filter because it restores from nuget.org. + +That split is the point: **a library's own build is not a consumer**, so a claim about consumers is +only true if something builds one. + +## Related skills + +`purview-containers-quickstart` for packages and backend selection, and +`purview-containers-testing` for the test tiers and CI shape. diff --git a/.claude/skills/purview-containers-lifecycle/SKILL.md b/.claude/skills/purview-containers-lifecycle/SKILL.md new file mode 100644 index 00000000..01b84ed7 --- /dev/null +++ b/.claude/skills/purview-containers-lifecycle/SKILL.md @@ -0,0 +1,144 @@ +--- +name: purview-containers-lifecycle +description: >- + Use when reasoning about a Purview.Containers container's lifecycle or readiness - StartAsync, + StopAsync and DisposeAsync semantics, cleanup guarantees and why there is no restart, the Wait + strategy family and started-versus-ready, and WSL Containers networking, port mapping and the + absence of inter-container DNS. +metadata: + product: Purview.Containers + repository: purview-dev/containers +--- + +# Lifecycle, readiness and networking + +## The public surface + +```csharp +public interface IContainer : IAsyncDisposable +{ + Task StartAsync(CancellationToken ct = default); + Task StopAsync(CancellationToken ct = default); + ValueTask DisposeAsync(); + // restart is intentionally NOT offered +} +``` + +**There is no `RestartAsync`.** WSLC has no restart operation, and stop-then-start is not equivalent, +so offering one would be a method that quietly means something different per backend. + +WSLC's `ContainerState` runs `Invalid → Created → Running → Exited → Deleted`. + +| Operation | Behaviour | +| --- | --- | +| `StartAsync` | creates the session if needed, ensures the image per the pull policy, creates the container, starts it, then waits. A missing init binary throws `ArgumentException 0x80070057` with the OCI message, surfaced as `WslContainerStartupException`. | +| `StopAsync` | `Stop(SIGTERM, grace)`, then `Stop(SIGKILL, …)` if still running. **Idempotent** — WSLC accepts stopping an already-stopped container. | +| `DeleteAsync` | `Delete(Force)`. A double delete throws `0x80010108` (`RPC_E_DISCONNECTED`) and is swallowed. | +| `DisposeAsync` | stop if running → delete → release the WinRT object. **Idempotent.** | + +## Cleanup guarantees + +These are the ones that matter when a test throws: + +- `DisposeAsync` runs in a `finally` by callers, **and** the container object is registered for + cleanup by the runtime, so disposal happens even if a test throws after `StartAsync`. +- `EnableAutoRemove` defaults to **`false`**: the library owns deletion. WSLC auto-removal would + delete a one-shot container before its state or output could be inspected — precisely when you need + them. Opt in with `.WithAutoRemove()`. +- A **partial startup failure** — image pull, create, start or wait — tears down through the same + `DisposeAsync` path. So does a **cancelled** `StartAsync` or wait. +- A **container crash** fires `InitProcess.Exited`; the container is then `Exited` and `DisposeAsync` + deletes it. +- A **session crash** marks the runtime session dead, and subsequent operations throw + `WslContainerSessionTerminatedException` rather than failing obscurely. +- **Test-process termination** disposes the shared session through a process-exit hook, freeing the + name. A *crashed* process leaves an orphaned session that only reserves its name; sweep it with + `wslc --session system session terminate`. + +## Secrets and names + +Container names are generated uniquely as `{service}-{processId}-{random8}` and **never contain +credentials**; session names are `wslc-{pid}-{random8}`. Diagnostics redact secrets through a +`Secret` wrapper whose `ToString()` returns ``. + +## Wait strategies + +**A started container is not a ready service.** `Container.Start()` returns once the init process is +running; readiness is a separate check, and it is the one your test actually depends on. + +```text +IWaitStrategy + TimeSpan? Timeout // null -> the container's StartupTimeout + TimeSpan Interval // default 250 ms + int? Retries // optional max failed checks + Task UntilAsync(WaitContext context, CancellationToken ct) + +WaitContext { IContainer Container; string? NetworkIp; int? GetHostPort(ushort); int? FirstHostPort; } +``` + +| Factory | Checks | +| --- | --- | +| `Wait.ForContainerRunning()` | `State == Running`. **Started, not ready.** | +| `Wait.ForTcpPort(8080)` | connects to `127.0.0.1:`. IPv4 only. | +| `Wait.ForHttp("/health")` | `.ForPort`, `.ForScheme`, `.ForStatusCode`, `.ForStatusPredicate`, `.ForHeader`, `.AllowInsecureTls` | +| `Wait.ForLogMessage(string \| Regex)` | case-insensitive substring, or regex, against **accumulated** init-process output | +| `Wait.ForCommand("pg_isready", "-U", "postgres")` | runs it via `ExecAsync`; ready at the expected exit code (default 0, `.ForExitCode(…)`) | +| `Wait.ForCustom((context, ct) => …)` | anything else | +| `Wait.ForAll(…)` / `Wait.ForAny(…)` | every strategy ready on the same check / at least one | + +Fluent modifiers: `.WithTimeout(…)`, `.WithInterval(…)`, `.WithRetries(…)`. + +Details worth knowing: + +- Waits run **inside** `StartAsync()`, after the container starts. `StartAsync` only returns when + every strategy is ready, or throws `ContainerTimeoutException`. +- The default timeout is the container's `StartupTimeout` — 5 minutes, overridable with + `.WithStartupTimeout(…)` or per-strategy. +- A timeout diagnostic includes the container name, image, state, mapped ports, the strategy type, + the last check error, and a bounded, secret-redacted tail of stdout/stderr. +- The container buffers output from process start, so a log message emitted **before** the waiter's + first check still matches. +- HTTP TLS validation is **on** by default. `AllowInsecureTls()` disables it for that request handler + only, never globally. +- Transient exec failures during startup count as not-ready, not as failure. + +Modules pick their own readiness check: PostgreSQL `pg_isready`, Redis `redis-cli ping`, RabbitMQ +`rabbitmq-diagnostics ping`, SQL Server a host-side connection. + +## Networking + +| `ContainerNetworkingMode` | Effect | Port mappings | +| --- | --- | --- | +| `null` (raw default) | Docker `NetworkMode: "none"` — no network, no IP | `CreateContainer` throws `0x80070057` | +| `None` | the same | no | +| `Bridged` | `172.17.0.x` on the session bridge; host→container mapped ports work | yes | + +`ContainerBuilder` defaults to **`Bridged`**, because a container with no network is not useful. + +Verified WSLC behaviour, and the parts that surprise people: + +- The host bind address is **IPv4 loopback only** (`HostIp: 127.0.0.1`). IPv6 `::1` does not connect. +- **Clients must use `127.0.0.1`, not `localhost`.** `localhost` resolves to `::1` first on .NET. + Npgsql and StackExchange.Redis fall back to IPv4; `Microsoft.Data.SqlClient` **hangs** without + falling back. +- Containers in the same session **can** reach each other by IP under `Bridged`. +- There is **no name or DNS resolution between containers**. `http://:8080/` and + `http://:8080/` fail with "bad address"; `/etc/hosts` holds only localhost and the + container's own `IP `. +- There are **no managed network objects** — `Microsoft.WSL.Containers` has no `network + create/connect`, unlike the CLI. + +How the library models it: `GetMappedPublicPort(containerPort)` reads +`Inspect().Ports["/tcp"][0].HostPort`; `GetNetworkIp()` reads +`Inspect().NetworkSettings.Networks.bridge.IPAddress` (Bridged only); TCP and HTTP waits connect to +`127.0.0.1:`. + +**What not to model.** Do not invent Docker-style `Network` objects — the semantics are just "bridged +with IPs". Do not claim container-name resolution works; it does not. Multi-container environments +are deliberately deferred, and would wire containers together by passing each other's IPs from +`GetNetworkIp()` into configuration or environment — which is why the core API does not preclude it. + +## Related skills + +`purview-containers-quickstart` for packages, backends and connection strings; +`purview-containers-testing` for how a suite is organised and why it runs serially. diff --git a/.claude/skills/purview-containers-quickstart/SKILL.md b/.claude/skills/purview-containers-quickstart/SKILL.md new file mode 100644 index 00000000..c90b6c10 --- /dev/null +++ b/.claude/skills/purview-containers-quickstart/SKILL.md @@ -0,0 +1,181 @@ +--- +name: purview-containers-quickstart +description: >- + Use when adding throwaway containers to a .NET test suite with Purview.Containers - which package to + reference, how the WSL Containers and Docker backends are selected automatically, running a generic + container with ContainerBuilder, using a typed service module, and getting a connection string. +metadata: + product: Purview.Containers + repository: purview-dev/containers +--- + +# Purview.Containers quickstart + +Throwaway Linux containers for .NET tests, behind one API, over either **WSL Containers** (no Docker +installation on Windows) or **Docker** (anywhere). The same test code runs on both. + +> **Experimental and prerelease.** The API, defaults and packaging rules can change between releases. +> Pin the version you adopt. + +## Which package + +| Package | Use it when | +| --- | --- | +| `Purview.Containers` | the umbrella: `Core` plus both backends. One reference, zero config — WSLC on Windows, Docker elsewhere. **The default.** | +| `Purview.Containers.Wsl` | WSL Containers only — a Windows machine with no Docker. | +| `Purview.Containers.Docker` | Docker only — any platform, CI, Linux/macOS. A Linux-only job can skip the WSL backend's ~19 MB payload with `Core` + `.Docker`. | + +A service module is backend-neutral, so it needs a backend (or the umbrella) alongside it: + +```bash +dotnet add package Purview.Containers.PostgreSql +dotnet add package Purview.Containers +``` + +## The zero-config shape + +```xml + + + net10.0 + + + + + + + +``` + +Three things make it work, and nothing else is required: + +- **A platform-neutral target framework** (`net10.0`). `Purview.Containers.Wsl` is multi-targeted; a + `net10.0` project binds its **portable facade**, which runs the WSLC implementation on Windows and + reports `wsl` unavailable everywhere else. A Windows target framework binds the implementation + directly — and then cannot run on a Linux CI runner. +- **The umbrella package**, bringing `Core` and both backends. +- **No registration line and no environment variable.** Each backend package ships `buildTransitive` + assets that generate a module initializer in your assembly, so the process discovers the registered + backends itself. Those assets flow transitively through the umbrella. + +## Backend selection + +| Host | Selected | Why | +| --- | --- | --- | +| Windows with WSL Containers | `wsl` | the facade loads the WSLC implementation, and WSLC is preferred | +| Windows with Docker only | `docker` | the facade reports `wsl` unavailable, so selection falls through | +| Linux / macOS | `docker` | the facade only ever activates on Windows | + +Selection probes the registered backends in priority order (`wsl` is `0`, `docker` is `100`) and +returns the first that is both **available** and **compatible**. When none is usable, the exception +lists each backend's availability, version and missing components. + +```csharp +foreach (var backend in await ContainerBackends.ProbeAllAsync()) + Console.WriteLine($"{backend.Name}: usable={backend.IsUsable} version={backend.Version}"); +``` + +```bash +PURVIEW_CONTAINERS_BACKEND=docker # or wsl - fail loudly instead of falling back +``` + +A **named** backend never silently falls back: if it cannot run, the test fails with that backend's own +diagnostics. That is usually what you want in CI. + +The library never installs a runtime. `WslContainerRuntime.GetInfoAsync()` and +`DockerContainerBackend.GetInfoAsync()` report what is missing. Verify a host with `wsl --version` and +`wslc version`, or `docker info`. + +## A generic container + +```csharp +using Purview.Containers; +using Purview.Containers.Waiting; + +await using var container = new ContainerBuilder() + .WithImage("docker.io/library/redis:latest") + .WithPortBinding(6379, assignRandomHostPort: true) + .WithWaitStrategy(Wait.ForTcpPort(6379)) + .Build(); + +await container.StartAsync(); + +ushort port = container.GetMappedPublicPort(6379); +``` + +`Build()` validates the accumulated configuration and resolves the backend when the container starts. +`StartAsync()` creates the container, starts it, and **only returns once every configured wait +strategy is satisfied**. `DisposeAsync()` stops and deletes the container — and never terminates a +shared WSLC session. + +## A typed module + +```csharp +using Npgsql; +using Purview.Containers.PostgreSql; + +await using var postgres = new PostgreSqlBuilder() + .WithDatabase("tests") + .WithUsername("postgres") + .WithPassword("postgres") + .Build(); + +await postgres.StartAsync(); // returns once pg_isready succeeds + +await using var connection = new NpgsqlConnection(postgres.GetConnectionString()); +await connection.OpenAsync(); +``` + +No image names, no ports, no `docker`, no `wslc`. The default image, the random host port mapping and +the readiness check all come from the module. + +Modules: PostgreSQL, Redis, SQL Server, MySQL, RabbitMQ, Azurite, NATS and the Azure Key Vault +Emulator. Each ships a README inside its own package. + +## Connection strings + +Every container implements `IConnectionStringProvider`, so you can ask any container without knowing +its module type: + +```csharp +string connectionString = container.GetConnectionString(); // ConnectionMode.Host +string same = container.GetConnectionString(ConnectionMode.Host); +``` + +| Mode | Meaning | Support | +| --- | --- | --- | +| `Host` | test host → container, via the mapped host port (`127.0.0.1:{port}`) | both backends | +| `Container` | container → container, via the container network | **not supported** — throws `ConnectionStringModeNotSupportedException` | + +Container-to-container is deliberately deferred: WSLC has no managed networks or inter-container DNS, +and the Docker backend does not attach containers to a shared network. + +**Use `127.0.0.1`, never `localhost`.** `localhost` resolves to `::1` first on .NET, and while most +clients fall back to IPv4, `Microsoft.Data.SqlClient` **hangs** on `::1` without falling back — which +is why the SQL Server module's connection strings are explicitly `127.0.0.1,{port}`. + +### A custom provider + +```csharp +sealed class ReadOnlyPostgreSql : ContainerConnectionStringProvider +{ + protected override string GetHostConnectionString() => + $"{Container.GetConnectionString()};ApplicationName=readonly"; +} + +var postgres = new PostgreSqlBuilder() + .WithConnectionStringProvider(new ReadOnlyPostgreSql()) + .Build(); +``` + +`Configure` runs once, **after** the container has started, so runtime-assigned ports are available. A +provider producing an empty string throws `ConnectionStringNotAvailableException`; one used before +`Configure` throws `ConnectionStringProviderNotConfiguredException`. The named overload +(`GetConnectionString(name, mode)`) exists for modules with several endpoints and otherwise throws +`ConnectionStringNameNotSupportedException`. + +## Related skills + +`purview-containers-lifecycle` for start/stop/dispose semantics, wait strategies and networking; +`purview-containers-testing` for suite layout, serial execution and CI; and +`purview-containers-consumer-requirements` for the target-framework contract and the `PCC` guards. diff --git a/.claude/skills/purview-containers-testing/SKILL.md b/.claude/skills/purview-containers-testing/SKILL.md new file mode 100644 index 00000000..5d8be988 --- /dev/null +++ b/.claude/skills/purview-containers-testing/SKILL.md @@ -0,0 +1,126 @@ +--- +name: purview-containers-testing +description: >- + Use when organising or running a test suite that uses Purview.Containers - the Unit and Integration + tiers, why test modules must run serially under WSL Containers, pinning or skipping a backend, + running the Docker suites in CI and the WSL suites on a self-hosted runner, and verifying the + consumer contract. +metadata: + product: Purview.Containers + repository: purview-dev/containers +--- + +# Testing with containers + +## Tiers + +The SDK stamps every test assembly with a TUnit category derived from the **project name**, so the +tier is a property of the project rather than of a hand-written attribute: + +| Project | Category | Runtime needed | +| --- | --- | --- | +| `*.UnitTests` | `Unit` | none — logic, parsing, configuration, wait-strategy units, in-process fakes | +| `Wsl.*` and module `*.IntegrationTests` | `Integration` | a **WSLC host** | +| `Docker.IntegrationTests`, `Modules.DockerIntegrationTests` | `Integration` | any **Docker daemon**; these target `net10.0`, so they run on Linux too | + +The shared pipeline filters to `/*/*/*/*[Category=Unit]`, so **the standard pipeline never starts a +container**. The Docker suites are the exception: the PR workflow adds an `integration-docker` job on +`ubuntu-latest`. That job is the standing proof that the library and every service module work off +Windows and WSL — the same modules a developer runs on WSLC locally. + +```powershell +just test # every discovered project +just test '/*/*/*/*[Category=Unit]' # unit only +just test '/*/*/*/*[Category=Integration]' --max-parallel-test-modules 1 +just test src/tests/Docker.IntegrationTests/Docker.IntegrationTests.csproj +``` + +Filtering uses TUnit's `--treenode-filter`, not `--filter`: this runs on Microsoft.Testing.Platform, +where `dotnet test --filter` reports "Zero tests ran". + +## Why test modules run serially + +A WSLC session takes an **exclusive lock on its `storage.vhdx`**, and takes it lazily on first store +access rather than at session start. Running test assemblies in parallel therefore makes the losers +fail: + +```text +0x80070020: The process cannot access the file because it is being used by another process. +``` + +`just test` passes `--max-parallel-test-modules 1` for exactly that reason. The runtime verifies the +store once and transparently falls back to an isolated per-process store, but serial modules keep the +**warm shared image cache** — no per-process re-pull — and are the fastest option. + +In Visual Studio, untick **Run Tests in Parallel** (or set *Maximum Parallel Test Projects* to 1) +before running the WSLC integration suites. + +## Choosing a backend in a suite + +Automatic detection prefers WSLC and falls back to Docker, so a WSLC host runs the WSLC suites and a +Docker-only host runs the Docker ones. Pin one to **fail loudly instead of falling back** — +usually what you want in CI: + +```bash +PURVIEW_CONTAINERS_BACKEND=wsl # or docker +``` + +Both halves skip themselves when their runtime is unreachable: the Docker suites when no daemon +responds, the WSLC suites when the host lacks the WSL Containers components. That is what lets a +machine without WSLC still run the unit tier — and it is also why a mis-provisioned CI runner reports +*successes with skips* rather than real coverage. Print `wsl --version` and `wslc version` as the +job's first step so that failure is visible immediately. + +## CI shape + +- **Docker half** — runs on every pull request, on `ubuntu-latest`. +- **WSL half** — cannot: it needs a Windows host with WSL Containers, which no GitHub-hosted runner + provides. It is a **manual** workflow on a self-hosted runner: + + ```bash + gh workflow run "Integration (WSL Containers)" --ref main + gh run watch + ``` + + It runs `Wsl.IntegrationTests` then each service-module suite **one project at a time**, so the + shared WSLC image store is never contended. Inputs: `ref` and `filter` (a treenode filter). + +Self-hosted runner prerequisites: a **Windows x64** runner labelled `self-hosted` and `wslc`, with +WSL Containers installed (`wsl --install --no-distribution`) and the pinned .NET SDK. Tell +`actionlint` about the custom label in `.github/actionlint.yaml`. + +> The shared pipeline runs on `ubuntu-latest`, so it builds the portable `net10.0` projects **and** +> the Windows-targeted test projects on Linux. That works only because `src/Directory.Build.props` +> sets `EnableWindowsTargeting=true`; without it the SDK reports `NETSDK1100`. + +## Expectations + +`Wsl.IntegrationTests` runs many real containers in one session and can take several minutes, because +WSLC serialises container operations. Slow-test warnings while it runs are expected, not a signal. + +## Verifying the consumer contract + +Two layers, and the split matters. + +**Shape, inside the unit run.** `Wsl.UnitTests/ConsumerRequirementsTests.cs` asserts that the Windows +build targets `.NETCoreApp,Version=v10.0`, targets `Windows10.0.19041.0`, and declares only that OS +platform. If the target framework drifts, that test fails — and the consumer-requirements page, the +package READMEs and the shipped `buildTransitive` defaults all have to move with it. + +**Behaviour, outside it.** `just verify-consumers` packs the packages and builds throwaway consumer +projects for every documented outcome — the happy paths *and* the documented guard errors. It is +deliberately outside the `[Category=Unit]` filter because it packs and restores from nuget.org: + +```powershell +just verify-consumers # 21 consumer projects, all assertions +just verify-consumers -Keep # keep the generated projects for inspection +``` + +This is the general rule worth copying: **a library's own build is not a consumer**, so a claim about +consumers is only true if something builds one. + +## Related skills + +`purview-containers-quickstart` for the packages and backend selection, +`purview-containers-lifecycle` for readiness and cleanup, and +`purview-containers-consumer-requirements` for the target-framework contract and `PCC` guards. diff --git a/.config/purview-build.json b/.config/purview-build.json index b44ad059..d4ca35c7 100644 --- a/.config/purview-build.json +++ b/.config/purview-build.json @@ -11,7 +11,6 @@ "RequireSymbolFiles": true, "RequiredContent": { "purview.eventsourcing": [ - ".agents/**/*", "analyzers/dotnet/cs/Purview.EventSourcing.SourceGenerator.CodeFixes.dll", "analyzers/dotnet/cs/Purview.EventSourcing.SourceGenerator.dll", "buildTransitive/Purview.EventSourcing.targets", @@ -88,9 +87,11 @@ "README.md" ], "purview.eventsourcing.cosmosdb": [ + "analyzers/dotnet/cs/Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.dll", "lib/$(TFM)/Purview.EventSourcing.CosmosDb.dll", - "lib/$(TFM)/Purview.EventSourcing.CosmosDb.runtimeconfig.json", "lib/$(TFM)/Purview.EventSourcing.CosmosDb.xml", + "lib/$(TFM)/Purview.EventSourcing.EntityFrameworkCore.dll", + "lib/$(TFM)/Purview.EventSourcing.EntityFrameworkCore.xml", "lib/$(TFM)/Purview.EventSourcing.ImplementationShared.dll", "lib/$(TFM)/Purview.EventSourcing.ImplementationShared.xml", "purview-logo-light.png", @@ -115,6 +116,8 @@ ], "purview.eventsourcing.postgres": [ "analyzers/dotnet/cs/Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.dll", + "lib/$(TFM)/Purview.EventSourcing.EntityFrameworkCore.dll", + "lib/$(TFM)/Purview.EventSourcing.EntityFrameworkCore.xml", "lib/$(TFM)/Purview.EventSourcing.ImplementationShared.dll", "lib/$(TFM)/Purview.EventSourcing.ImplementationShared.xml", "lib/$(TFM)/Purview.EventSourcing.Postgres.dll", @@ -125,6 +128,8 @@ ], "purview.eventsourcing.sqlserver": [ "analyzers/dotnet/cs/Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.dll", + "lib/$(TFM)/Purview.EventSourcing.EntityFrameworkCore.dll", + "lib/$(TFM)/Purview.EventSourcing.EntityFrameworkCore.xml", "lib/$(TFM)/Purview.EventSourcing.ImplementationShared.dll", "lib/$(TFM)/Purview.EventSourcing.ImplementationShared.xml", "lib/$(TFM)/Purview.EventSourcing.SqlServer.dll", diff --git a/AGENTS.md b/AGENTS.md index 4c4f261b..79c585b4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,10 +32,11 @@ This repository contains the `Purview.EventSourcing` framework, its incremental | `src/src/Admin.*` | Administration abstractions, security, API, UI, and provider adapters | | `src/src/Samples*` | Reference domains, quick start, web app, shared defaults, and Aspire AppHost | | `src/tests` | Unit, integration, source-generator, sample, admin, and performance projects | -| `src/tests/SharedTestingFramework` | Shared provider fixtures and Testcontainers infrastructure | +| `src/tests/SharedTestingFramework` | Shared provider fixtures and Purview.Containers infrastructure | | `docs/wiki` | User-facing design, provider, generator, dependency, and release guidance | | `.github/workflows` | PR validation, reusable validation/pack, and release workflows | -| `.agents/skills` | Repository workflow and SDK guidance available to supporting agents | +| `skills` | Agent skills this repository authors and ships to consumers via the skills CLI | +| `.agents/skills` | Skills consumed from other repositories, installed by the CLI and gitignored | | `Directory.Packages.props` | Centrally managed NuGet versions | | `src/Directory.Build.props` / `src/Directory.Build.targets` | Solution-wide SDK, package, analyzer, and build behavior | | `global.json` | Required .NET SDK and Microsoft.Testing.Platform selection | @@ -50,8 +51,9 @@ Do not introduce a second version source, dependency-version location, or parall 2. Confirm behavior from code and tests rather than relying on memory or documentation alone. Documentation describes intent but may lag implementation. 3. Make the smallest coherent change. Preserve public behavior unless the task explicitly changes it. 4. Update tests for fixes and behavior changes. Update documentation when public behavior, provider support, configuration, query semantics, generated API shape, or limitations change. -5. Run the narrowest meaningful validation first, then broader validation in proportion to risk. -6. Review the diff for unrelated edits, generated noise, compatibility risks, and missing docs or tests. +5. Feature work is not finished until the authored skills in `skills/` and the guides in `docs/wiki` describe it. See [Skills and documentation are part of the feature](#skills-and-documentation-are-part-of-the-feature). +6. Run the narrowest meaningful validation first, then broader validation in proportion to risk. +7. Review the diff for unrelated edits, generated noise, compatibility risks, and missing docs, skills or tests. Use repository-local skills when their trigger applies: @@ -110,6 +112,7 @@ Use repository-local skills when their trigger applies: - Keep SQL identifiers, Mongo collections, Cosmos containers/partitions, and Azure Table/Blob routing configurable through established abstractions. Validate identifiers rather than concatenating untrusted input into commands. - Use provider-native parameterization and escaping. Never construct SQL or provider queries by interpolating untrusted values. - Integration tests should exercise the actual provider when behavior depends on translation, serialization, concurrency, indexing, transactions, or SDK behavior; an in-memory substitute is insufficient. +- A new read path must be tenant-filtered and a new write path must stamp the tenant, in the same change. Both are easy to add and invisible to every existing test; see [Tenant isolation](#tenant-isolation). ## Snapshots and query translation @@ -138,10 +141,38 @@ Use repository-local skills when their trigger applies: - Samples are executable documentation. Keep them idiomatic, comprehensible, and aligned with supported public APIs rather than using internal shortcuts. - Update sample tests and relevant README/wiki examples when a public workflow changes. - `Samples.AppHost` defines external infrastructure for local distributed execution. Prefer its established resources and configuration wiring; do not hardcode local ports, credentials, or machine-specific paths. -- Aspire/Testcontainers work may require Docker and provider images. Report infrastructure prerequisites or failures rather than weakening tests to avoid them. +- Aspire and container work may require a container runtime (WSL Containers or Docker) and provider images. Report infrastructure prerequisites or failures rather than weakening tests to avoid them. + +## Tenant isolation + +Tenant isolation is a security boundary, not a feature. When a change touches any read or write path in +a provider, the event store, a snapshot store, the cache, or the Admin API, **write or update the tenancy +test before the feature test**. Every point below was a real defect found in this repository, in several +cases while its own tenancy tests were passing. + +- **A tenancy test must share storage between scopes.** Two stores built with different run identifiers + use different tables, databases or containers, so "tenant B cannot see tenant A" passes while proving + nothing. Pass the same `runId` and change only the `ICurrentTenant`. +- **Test the cached path explicitly.** The distributed cache is read *before* the tenant-filtered storage + lookup, so an unqualified cache key bypasses every filter. Prime the cache as the owning tenant, then + assert the other tenant still cannot read. Per-test cache instances hide this entirely. +- **Assert all three outcomes**: the owner reads it, another tenant does not, and `TenantScope.System` + does. Testing only the denial misses a filter that hides data from everyone. +- **Audit every write path for the stamp.** The SQL providers had three distinct entity-construction + paths; two were stamped and one was not, which made reads behave as if filtering were broken. Count the + call sites rather than trusting a search-and-replace. +- **Unowned rows fail closed.** Do not add `|| TenantId == null` to a filter. It turns a missed stamp from + an obvious absence into silent cross-tenant exposure. Only `TenantScope.System` sees unowned rows. +- **Confirm the filter is on the runtime context.** Some providers have a migrations-only `DbContext` + alongside the one that actually executes queries. A filter on the wrong one compiles, passes, and + protects nothing. +- Prefer structural isolation where the store allows it - a tenant-qualified key or partition - over a + predicate a future query can forget. ## Testing conventions +- **Tenant isolation comes first.** Before testing what a change does, test that it does not leak across + tenants; see [Tenant isolation](#tenant-isolation). A green suite is not evidence the boundary holds. - This repository uses TUnit on Microsoft.Testing.Platform, selected in `global.json`. Do not add xUnit, NUnit, MSTest, or FluentAssertions patterns unless explicitly requested. - TUnit test methods use `[Test]`, and assertion calls are awaited, for example `await Assert.That(actual).IsEqualTo(expected);`. - Never use VSTest `dotnet test --filter` for these projects. Use `--treenode-filter` and observe the command form supported by the repository/SDK. @@ -154,12 +185,35 @@ Use repository-local skills when their trigger applies: - PR validation restores and builds the Release solution, then runs the unit-test tree filter `/*/*/*/*[Category=Unit]` (the `Purview.BuildSdk` applies `[assembly: TUnit.Core.Category("Unit")]` to unit-test projects) and emits TRX results. - Unit tests should cover domain logic, contracts, failure behavior, and regressions without external infrastructure. - Source-generator tests should assert generated code and diagnostics using the existing testing framework. -- Provider integration tests use `src/tests/SharedTestingFramework` and Testcontainers or provider infrastructure. Run affected-provider tests for translation, persistence, concurrency, or serialization changes when infrastructure is available. +- Provider integration tests use `src/tests/SharedTestingFramework` and Purview.Containers (WSL Containers on Windows, Docker elsewhere) or provider infrastructure. Run affected-provider tests for translation, persistence, concurrency, or serialization changes when infrastructure is available. - Multi-provider contract changes require shared tests plus affected provider suites; do not prove parity with only one provider. - Performance work should use the source-generator or SQL Server performance harness and report comparable before/after conditions; performance tests are not a substitute for correctness tests. - Documentation-only changes do not require the .NET suite unless they alter executable snippets, build/release commands, or configuration whose validity needs testing. - Do not update approved/verified output merely to make a failure disappear. Inspect the semantic difference first. +## Skills and documentation are part of the feature + +A capability a consumer cannot discover is not finished. **Every feature, behaviour change, new +option, new failure case, or new limitation updates both the authored skills in `skills/` and the +guides in `docs/wiki`, in the same change as the code.** Neither is a follow-up task. + +- **`skills//SKILL.md`** is how an agent working in a consumer's codebase learns the capability. + Add a skill when a capability needs its own decisions - a new subsystem, a security boundary, a + model a caller must adopt. Extend an existing skill when it is a new rule within one. +- **`docs/wiki`** is how a person learns it. `Guarantees-and-Limitations.md` is the authoritative + summary: if a change alters what the framework guarantees, or adds a gap, it belongs there. +- A skill is for *decisions and traps*, not API reference. Write the thing a caller would otherwise + get wrong, and say why. Prefer a rule that was a real defect over a rule that sounds prudent. +- **State limitations in both.** A capability wired for some providers and not others, or disabled + under some configuration, must say so plainly. Implying parity that the tests do not demonstrate is + worse than documenting the gap. +- Skills live at the repository root in lowercase `skills/`, are validated by + `src/tests/Skills.UnitTests`, and follow the spec frontmatter - `name`, `description`, `license`, + `compatibility`, `metadata`, `allowed-tools` and nothing else. See the + `purview-buildsdk-skill-tests` skill before authoring one. +- Skills are **not** packed into any NuGet package; the skills CLI delivers them from git. Do not + reintroduce a package path for them. + ## Documentation rules - Keep `README.md`, package/provider READMEs, and `docs/wiki` aligned with actual supported behavior. @@ -181,6 +235,7 @@ just pipeline-build # restore, build, lint, pack, validate (no test just restore just build just test # accepts a treenode filter and extra arguments +just test-integration # the same, one test module at a time (required by WSL Containers) just lint-check just pack just perf-source-generator @@ -201,7 +256,7 @@ dotnet csharpier check . - Use `dotnet csharpier check .` for validation (the pipeline lints the repository root). Run the rewriting formatter only when formatting changes are in scope, and ensure it does not touch unrelated user files. - Local `just` recipes default to the `Debug` configuration; Release-style builds, tests, and packs run through the `Purview.Build` pipeline (`just pipeline-pr` / `just pipeline-build`). -- The pipeline discovers tests under `src/tests` with `Build:TestPatterns` (`*Tests.csproj`), restricts the run list with `Build:TestProjects` (`*UnitTests.csproj`), and applies `Build:TestFilter` (`/*/*/*/*[Category=Unit]`), so GH Actions never runs provider integration tests or the performance harnesses; run those locally with `just test` when Docker/Testcontainers infrastructure is available. +- The pipeline discovers tests under `src/tests` with `Build:TestPatterns` (`*Tests.csproj`), restricts the run list with `Build:TestProjects` (`*UnitTests.csproj`), and applies `Build:TestFilter` (`/*/*/*/*[Category=Unit]`), so GH Actions never runs provider integration tests or the performance harnesses; run those locally with `just test` when a container runtime (WSL Containers or Docker) is available. - Pack when package assets, public package dependencies, analyzers, build targets, or packaging metadata change. - Build the canonical solution when shared contracts, project configuration, central packages, or generator/package wiring change. @@ -221,6 +276,8 @@ Before handing work back: - Confirm only intended files changed and all pre-existing worktree changes remain intact. - Review public API, serialization, event-schema, provider-parity, security, and package-content implications. - Add or update focused tests for code changes and verify failures are not hidden by empty filters or ignored infrastructure errors. +- If the change touched a read path, a write path, or the cache, confirm a tenancy test covers it and that the test would fail without the filter or the stamp. - Update all affected docs, samples, feature matrices, analyzer metadata, and release notes when applicable. +- Confirm the authored skills in `skills/` and the guides in `docs/wiki` describe the change, including any provider it is *not* wired for. If neither needed a change, say why. - Run appropriate build, test, formatting, and pack checks in proportion to risk. - State exactly what validation ran. If a check was skipped or blocked, give the concrete reason and remaining risk. diff --git a/skills-lock.json b/skills-lock.json index f55059ba..8f192f03 100644 --- a/skills-lock.json +++ b/skills-lock.json @@ -85,6 +85,30 @@ "skillPath": "skills/purview-buildsdk-testing/SKILL.md", "computedHash": "d6a2ac1167faf68e8c27493de81c2e5b0d8183e523de4411aca5f5b9249c8a9c" }, + "purview-containers-consumer-requirements": { + "source": "purview-dev/containers", + "sourceType": "github", + "skillPath": "skills/purview-containers-consumer-requirements/SKILL.md", + "computedHash": "e8a661dec9460b57c1f4b7593fee6e1118d78c97f279df854c1b5a12f842df9f" + }, + "purview-containers-lifecycle": { + "source": "purview-dev/containers", + "sourceType": "github", + "skillPath": "skills/purview-containers-lifecycle/SKILL.md", + "computedHash": "77543920e8ec8f2290bb34a324e985847cbf03670829d76e659966cfcf16ae46" + }, + "purview-containers-quickstart": { + "source": "purview-dev/containers", + "sourceType": "github", + "skillPath": "skills/purview-containers-quickstart/SKILL.md", + "computedHash": "1aef67ea0d562d97cdef42e2dab4d18f17e0522bca6bc039ff4a82e6926e1916" + }, + "purview-containers-testing": { + "source": "purview-dev/containers", + "sourceType": "github", + "skillPath": "skills/purview-containers-testing/SKILL.md", + "computedHash": "ac4f871c85c69e627562d52e09f028c1d91105a34d599bd5f684bb109d69eb9a" + }, "purview-results-core": { "source": "purview-dev/results", "sourceType": "github", diff --git a/src/src/EventSourcing/Sdk/.agents/skills/event-sourcing-aggregate-design/SKILL.md b/skills/event-sourcing-aggregate-design/SKILL.md similarity index 94% rename from src/src/EventSourcing/Sdk/.agents/skills/event-sourcing-aggregate-design/SKILL.md rename to skills/event-sourcing-aggregate-design/SKILL.md index 076b1d14..8ffdc033 100644 --- a/src/src/EventSourcing/Sdk/.agents/skills/event-sourcing-aggregate-design/SKILL.md +++ b/skills/event-sourcing-aggregate-design/SKILL.md @@ -1,18 +1,10 @@ --- name: event-sourcing-aggregate-design -description: "Use when designing or refining event-sourced aggregates, commands, events, invariants, source-generator hooks, or snapshot-queryable mirror properties." -category: architecture -roles: - - architecture - - coding - - domain-driven-design -tags: - - event-sourcing - - aggregates - - domain-modeling - - ddd - - snapshots - - sql +description: "Use when designing or refining an event-sourced aggregate in Purview.EventSourcing - aggregate boundaries and invariants, turning state changes into domain events, the [GenerateAggregate] and [GenerateAggregateEvent] source-generator contract and its hooks, naming, and query-facing snapshot mirror properties." +license: MIT +metadata: + package: Purview.EventSourcing + category: architecture --- # Event Sourcing Aggregate Design Skill diff --git a/src/src/EventSourcing/Sdk/.agents/skills/event-sourcing-aggregate-validation/SKILL.md b/skills/event-sourcing-aggregate-validation/SKILL.md similarity index 75% rename from src/src/EventSourcing/Sdk/.agents/skills/event-sourcing-aggregate-validation/SKILL.md rename to skills/event-sourcing-aggregate-validation/SKILL.md index 04482581..997cf281 100644 --- a/src/src/EventSourcing/Sdk/.agents/skills/event-sourcing-aggregate-validation/SKILL.md +++ b/skills/event-sourcing-aggregate-validation/SKILL.md @@ -1,17 +1,10 @@ --- name: event-sourcing-aggregate-validation -description: "Use when defining event-sourced aggregate validation at command time, hook time, save time, or for computed snapshot/query mirror properties." -category: architecture -roles: - - architecture - - coding - - domain-driven-design -tags: - - event-sourcing - - aggregate - - validation - - fluentvalidation - - snapshots +description: "Use when deciding where validation belongs for a Purview.EventSourcing aggregate - command and hook-time invariants, DataAnnotations or FluentValidation at save time via IAggregateValidator, the AggregateInvalid failure case returned by SaveAsync, and computed snapshot mirror properties." +license: MIT +metadata: + package: Purview.EventSourcing + category: architecture --- # Event Sourcing Aggregate Validation Skill @@ -42,8 +35,9 @@ Use this skill when defining validation strategy for event-sourced aggregates in - Keep invariant checks close to mutation points (command/hook layer). - Keep structural and shape constraints declarative (DataAnnotations/FluentValidation). - Do not silently swallow validation failures. -- Treat `SaveResult.IsValid` and `ValidationResult` as first-class outcomes. -- Use `SaveResult.EnsureValid()` when invalid saves must throw immediately. +- Treat the `AggregateInvalid` failure case, and the `ValidationResult` it carries, as first-class outcomes. +- `SaveAsync` returns `Result, AggregateSaveFailure>`; a rejected save is the + `AggregateInvalid` case, not an exception. Throw from the call site only if the caller genuinely cannot continue. - Preserve replay tolerance by avoiding command-time assumptions in hydration-only paths. - For computed snapshot/query mirrors, validate derivation rules, not user-supplied values. - If a save-time validator is added, prefer `IAggregateValidator` over ad-hoc validation inside stores. @@ -54,7 +48,7 @@ Use this skill when defining validation strategy for event-sourced aggregates in - Property transitions are guarded (`OnChanging` / `OnChanged` where needed). - Aggregate-level attributes capture simple declarative constraints. - Custom FluentValidation rules are used for cross-field/business policies not suited to attributes. -- Save handlers inspect or enforce `SaveResult.ValidationResult`. +- Save handlers match the result and act on `AggregateInvalid.ValidationResult`. - Query-facing mirror properties are recomputed consistently from canonical state. ## Output template to use @@ -63,5 +57,5 @@ Use this skill when defining validation strategy for event-sourced aggregates in 2. Hook methods and invariants per command (`OnComputing...Event`, `OnRaising...Event`, `OnShouldApply...Event`, `OnChanging`/`Changed`). 3. Attribute-based constraints and rationale. 4. FluentValidation rules (if any) and when they execute. -5. SaveResult handling policy (`IsValid`, `EnsureValid`, error propagation). +5. Save-result handling policy (matching `AggregateInvalid`, error propagation). 6. Mirror-property derivation guarantees when query-facing fields exist. diff --git a/skills/event-sourcing-crypto-shredding/SKILL.md b/skills/event-sourcing-crypto-shredding/SKILL.md new file mode 100644 index 00000000..cbee8b31 --- /dev/null +++ b/skills/event-sourcing-crypto-shredding/SKILL.md @@ -0,0 +1,104 @@ +--- +name: event-sourcing-crypto-shredding +description: "Use when an event-sourced aggregate carries personal data and it must be erasable - marking events with IEventDataSubject, supplying per-subject keys through IEventCryptoKeyStore, what replay does once a key is shredded, and why snapshots are disabled while payload protection is on." +license: MIT +metadata: + package: Purview.EventSourcing + category: security +--- + +# Crypto-shredding + +An event stream is append-only, so personal data cannot be deleted from it. Instead, encrypt each +subject's payloads under a key belonging to that subject and **delete the key**. The events remain; +their contents become unreadable. + +## Marking an event + +```csharp +[EventContract] +public sealed record CustomerDetailsChanged : IEventDataSubject +{ + public static int SchemaVersion => 1; + + public EventMetadata Metadata { get; init; } + + public string Name { get; set; } = default!; + + public string DataSubjectId { get; set; } = default!; +} +``` + +Only events implementing `IEventDataSubject` are encrypted. Everything else is stored as before. + +`DataSubjectId` must be **stable for the subject's lifetime** - it is the key identifier, so a value +that changes orphans the earlier events. It is stored in clear alongside the ciphertext, so it must +not itself be personal data: use a surrogate identifier, never an email address. + +## Supplying keys + +```csharp +builder.Services.AddSingleton(); +builder.Services.AddSingleton(); +``` + +`InMemoryEventCryptoKeyStore` ships for local development and tests only: its keys die with the +process, so every payload becomes unreadable on restart. That is deliberate - a key store is the one +component where a convenient default would be actively harmful. + +**The key store is the erasure mechanism.** Back it with something that has its own access control +and audit trail, and that does not silently restore deleted entries from a backup. + +## Erasing a subject + +```csharp +await keyStore.ShredAsync(dataSubjectId, cancellationToken); +``` + +That is the whole operation. No event is rewritten or deleted, and no other subject is affected. + +## What replay does afterwards + +A payload whose key has been erased is surfaced as an **unknown event**: + +- the aggregate version still advances, +- the read **succeeds**, +- the gap is reported through `AggregateBase.SkippedEvents`. + +Replay never fails because somebody exercised their right to erasure. A caller that needs to know +whether reconstruction was complete inspects `SkippedEvents`. + +```csharp +var result = await store.GetAsync(id, cancellationToken); +var incomplete = (result.Value as AggregateBase)?.SkippedEvents.Count > 0; +``` + +Design aggregates so that a skipped event does not corrupt derived state - the same tolerance an +unknown event type already requires. + +## Snapshots are disabled while protection is on + +A snapshot serializes aggregate state, which holds the same personal data in clear, and one snapshot +can span many subjects - so it cannot be encrypted under any single subject's key. A store +configured with an `IEventPayloadProtector` therefore **writes no snapshots at all**. + +Replay from events stays correct; reads of long streams get slower. A snapshot surviving key erasure +would make the whole feature untrue, so this is not configurable. + +Snapshots written *before* protection was enabled are **not** removed retrospectively. Delete them as +part of enabling protection, or the erased data survives in them. + +## Where it applies + +Wired for the SQL Server, PostgreSQL, MongoDB and Azure Storage event stores, including the Azure +blob route used for oversized events. The in-memory store holds live objects rather than serialized +payloads, so there is nothing to encrypt and shredding does not apply to it. + +## What to verify + +1. The stored payload is ciphertext - read raw storage and assert the plaintext is absent. +2. Erasure is surgical - shred one subject, assert another subject's payload still decrypts. +3. After shredding, the read succeeds and `SkippedEvents` reports the gap. +4. Assert on distinctive strings. A short fragment such as `"42"` appears in base64 by chance and + makes the test pass or fail at random. +5. Snapshots are absent for a protected store, and any pre-existing ones are deleted. diff --git a/skills/event-sourcing-multi-tenancy/SKILL.md b/skills/event-sourcing-multi-tenancy/SKILL.md new file mode 100644 index 00000000..4b501f35 --- /dev/null +++ b/skills/event-sourcing-multi-tenancy/SKILL.md @@ -0,0 +1,118 @@ +--- +name: event-sourcing-multi-tenancy +description: "Use when running Purview.EventSourcing for more than one tenant - registering ICurrentTenant, the TenantScope.System infrastructure scope, which stores enforce isolation, why unowned rows fail closed, admin tenant scoping, and what to test so the boundary actually holds." +license: MIT +metadata: + package: Purview.EventSourcing + category: security +--- + +# Multi-tenancy + +Tenant isolation is opt-in and **enforced by the store**, not by callers remembering to filter. + +## Registering a tenant resolver + +```csharp +sealed class HttpContextCurrentTenant(IHttpContextAccessor accessor) : ICurrentTenant +{ + public TenantScope Current => + accessor.HttpContext?.User.FindFirst("tenant")?.Value is { Length: > 0 } tenantId + ? TenantScope.For(tenantId) + : TenantScope.System; +} + +builder.Services.AddHttpContextAccessor(); +builder.Services.AddSingleton(); +builder.Services.AddEventSourcing(); // registers its default only if none is present +``` + +Register **before** `AddEventSourcing()`: the framework uses `TryAddSingleton`, so the first +registration wins. + +> Returning `TenantScope.System` when no tenant can be resolved, as above, grants a cross-tenant +> view. In a request pipeline prefer rejecting the request instead. + +## `TenantScope.System` is not "no tenant" + +`System` is the **infrastructure** scope: it crosses every tenant and applies no filter. It exists +for projection rebuilds, migrations and outbox dispatch, and it is what a single-tenant deployment +runs under by default. + +It is deliberately distinct from a null tenant id, so a resolver that *fails* to determine a tenant +cannot be mistaken for permission to read everything. + +Change scope temporarily with `AmbientCurrentTenant.BeginScope`: + +```csharp +using (AmbientCurrentTenant.BeginScope(TenantScope.System)) + await rebuilder.RebuildAsync(cancellationToken); +``` + +## A tenant-less deployment needs no configuration + +Register nothing: the scope stays `System`, every filter short-circuits, writes record no owner, and +behaviour is exactly as it was before tenancy existed. + +## Unowned rows fail closed + +A row with no `TenantId` is visible **only** to `TenantScope.System`. The filters deliberately do not +treat a null owner as visible to every tenant. + +That matters more than it looks. If a write path ever fails to stamp the tenant, the row becomes +invisible to its own tenant - an obvious, reportable absence - instead of silently readable by all of +them. **Fail-closed turns a stamping bug into missing data rather than a cross-tenant leak.** + +The consequence: enabling tenancy over data written while tenant-less hides that data from +tenant-scoped reads. Backfill `TenantId`, or read it under `TenantScope.System`. + +## What each store enforces + +| Store | Mechanism | +| --- | --- | +| SQL Server, PostgreSQL | `TenantId` column, Entity Framework global query filter | +| MongoDB | `TenantId` field composed into every read and delete filter | +| Azure Storage | `TenantId` property in the OData filter; point reads filtered on read-back | +| Cosmos DB snapshots | `__tenantId` shadow property applied after `WithPartitionKey` | +| In-memory | Ownership tracked beside the data | + +**The distributed cache is namespaced by tenant.** The cache is read *before* the tenant-filtered +storage lookup, so an unqualified key would let one tenant read another's aggregate straight out of a +shared cache, bypassing every filter above. If you add a cache, namespace its key the same way. + +Azure Storage blob-backed snapshots are not filtered directly; they are unreachable without first +passing the tenant-filtered stream-version read. + +## Admin scoping + +Set `AdminPortalOptions.EnforceTenantScope` and every admin request must resolve to exactly one +tenant. `IAdminTenantResolver` decides it from the caller's entitlements and the `Purview-Tenant` +header: + +| Entitlements | Tenant requested | Result | +| --- | --- | --- | +| one | none | scoped to it | +| one | a different one | `403` | +| several | none | `400` | +| several | one they hold | scoped to it | + +A super user who names no tenant is **refused, not given the system scope**. The resolver returns a +tenant identifier and nothing else, so crossing tenants is unreachable from a signed-in session. + +## Testing it - the part that is easy to get wrong + +Every item below was a real defect found while the tenancy tests were passing. + +- **Share storage between scopes.** Two stores built with different run identifiers use different + databases, so "tenant B cannot see tenant A" passes while proving nothing. Change only the + `ICurrentTenant`. +- **Test the cached path.** Prime the cache as the owning tenant, then assert the other tenant still + cannot read. Per-test cache instances hide the leak entirely. +- **Assert all three outcomes**: the owner reads it, another tenant does not, and `System` does. + Testing only the denial misses a filter that hides data from everyone. +- **Count the write paths.** A provider may construct its stored entity in several places; one that + misses the stamp makes reads look like the filter is broken. +- **Check the filter is on the runtime context.** A filter on a migrations-only `DbContext` compiles, + passes, and protects nothing. + +A green suite is not evidence the boundary holds. diff --git a/skills/event-sourcing-results/SKILL.md b/skills/event-sourcing-results/SKILL.md new file mode 100644 index 00000000..175a9a58 --- /dev/null +++ b/skills/event-sourcing-results/SKILL.md @@ -0,0 +1,141 @@ +--- +name: event-sourcing-results +description: "Use when calling or handling the result of a Purview.EventSourcing store operation - GetAsync, SaveAsync, DeleteAsync and RestoreAsync return Result values rather than null, bool or exceptions. Covers the failure cases, SaveOutcome, which failures are results versus exceptions, and retrying a concurrency conflict." +license: MIT +metadata: + package: Purview.EventSourcing + category: architecture +--- + +# Handling event-store results + +The store returns outcomes a caller can act on as **result values**, and reserves exceptions for +faults a caller cannot. Nothing returns `null`, and nothing returns a bare `bool`. + +> The `Result` type and its union helpers come from `Purview.Results`. For the +> general mechanics of composing results, prefer the `purview-results-core` and +> `purview-results-union-errors` skills; this skill covers the event store's own vocabulary. + +## The principle + +> A failure a correct caller can anticipate and act on is a **result case**. +> A failure meaning the system, the configuration or the calling code is wrong is an **exception**. + +Cancellation is always `OperationCanceledException`, as everywhere else in .NET. + +## Reads + +`GetAsync`, `GetAtAsync`, `GetOrCreateAsync` and `GetDeletedAsync` return +`Result`. + +```csharp +var result = await store.GetAsync(orderId, cancellationToken); +if (result.IsFailure) +{ + return result.Error switch + { + AggregateNotFound => Results.NotFound(), + AggregateDeleted => Results.Problem(statusCode: 410), + _ => Results.Problem(), + }; +} + +var order = result.Value; +``` + +`AggregateReadFailure` carries `AggregateNotFound`, `AggregateDeleted`, `AggregateNotDeleted` and +`AggregateLocked`. **"Absent" and "deleted" are different answers** - the previous `T?` return could +not distinguish them. + +## Writes + +`SaveAsync` returns `Result, AggregateSaveFailure>`. A success that wrote nothing is +still a success: + +| `SaveOutcomeKind` | Meaning | +| --- | --- | +| `Written` | Events were appended | +| `NoChanges` | The aggregate had nothing to persist | +| `AlreadyApplied` | An idempotency marker matched an earlier attempt | + +```csharp +var saved = await store.SaveAsync(order, cancellationToken); +if (saved.IsFailure) +{ + if (saved.Error is AggregateInvalid invalid) + return Results.ValidationProblem(invalid.ValidationResult.Failures.ToProblem()); + + return Results.Conflict(); +} +``` + +`AggregateSaveFailure` carries `ConcurrencyConflict`, `AggregateDeleted`, `AggregateLocked` and +`AggregateInvalid`. `DeleteAsync` and `RestoreAsync` return their own unions, which add +`AggregateAlreadyDeleted` and `AggregateNotDeleted` respectively. + +**Do not treat a failure as "nothing happened".** `NoChanges` is a success; `ConcurrencyConflict` is +a failure. Collapsing the two is the ambiguity this model exists to remove. + +## Constructing failures + +A case shared by more than one union has its per-case `AsFailure` helper generated once, so name the +union explicitly: + +```csharp +// Correct - names the union. +return AggregateSaveFailure.Failure>(new AggregateLocked(type, id)); + +// Risky for a shared case - can bind to another union's helper. +return new AggregateLocked(type, id).AsFailure>(); +``` + +## Concurrency retries + +`ConcurrencyConflict` is a result, not an exception, so an exception-based retry loop will not see +it. Use the result-aware overload: + +```csharp +var saved = await ConcurrencyRetry.ExecuteAsync( + async ct => + { + var current = await store.GetAsync(orderId, ct); + current.Value.Confirm(); + return await store.SaveAsync(current.Value, ct); + }, + cancellationToken: cancellationToken +); +``` + +Re-read the aggregate inside the retry. Retrying with the stale instance conflicts again forever. + +## Inside a transaction + +`TransactionAggregateResult` exposes both. `Failure` carries the save failure a caller can act on; +`Error` carries only genuine exceptions. A `Saved == false` with neither set would be an +unexplained failure, which is why both exist: + +```csharp +var conflicted = transactionResult.Results.Any(r => r.Failure is ConcurrencyConflict); +``` + +## What still throws + +| Exception | Why | +| --- | --- | +| `CommitException` | Storage refused the write - infrastructure, not an outcome | +| `AggregateStreamVersionMissingException` | The stream is corrupt; no caller can continue | +| `MissingAggregateIdException`, `IdAlreadySetException` | Programming errors in aggregate construction | +| `UnregisteredEventException` | The aggregate never registered the event - a wiring defect | +| `EventStoreTransactionGuaranteeException` | A required guarantee the provider cannot honour | +| `TenantScopeNotSupportedException` | The provider cannot enforce the requested tenant scope | + +Queryable stores also keep throwing: a predicate that cannot be translated is a programming error, +not an outcome. + +## Checklist + +1. No call site treats a read as nullable or a save as `bool`. +2. `AggregateNotFound` and `AggregateDeleted` are handled distinctly where it matters. +3. `NoChanges` and `AlreadyApplied` are treated as success. +4. Concurrency retries use the result-aware overload and re-read inside the loop. +5. Transactional callers inspect `Failure`, not just `Saved`. diff --git a/src/src/EventSourcing/Sdk/.agents/skills/event-sourcing-value-objects/SKILL.md b/skills/event-sourcing-value-objects/SKILL.md similarity index 93% rename from src/src/EventSourcing/Sdk/.agents/skills/event-sourcing-value-objects/SKILL.md rename to skills/event-sourcing-value-objects/SKILL.md index 2ca6a421..06263446 100644 --- a/src/src/EventSourcing/Sdk/.agents/skills/event-sourcing-value-objects/SKILL.md +++ b/skills/event-sourcing-value-objects/SKILL.md @@ -1,18 +1,10 @@ --- name: event-sourcing-value-objects -description: "Use when modeling scalar, complex, or contextual value objects with source-generated normalization, validation, Hydrate/Create semantics, or query-translation awareness." -category: architecture -roles: - - architecture - - coding - - domain-driven-design -tags: - - event-sourcing - - value-objects - - source-generator - - validation - - snapshots - - sql +description: "Use when modelling value objects used by Purview.EventSourcing aggregates - [Scalar] and [ValueObject] from Purview.ValueObjects, OnNormalize and OnValidate, the Create versus Hydrate split for replay, and which shapes a provider can translate in a snapshot query." +license: MIT +metadata: + package: Purview.EventSourcing + category: architecture --- # Event Sourcing Value Objects Skill diff --git a/src/tests/Skills.UnitTests/SkillTests.cs b/src/tests/Skills.UnitTests/SkillTests.cs new file mode 100644 index 00000000..b1df382d --- /dev/null +++ b/src/tests/Skills.UnitTests/SkillTests.cs @@ -0,0 +1,13 @@ +using Purview.Skills.Testing; + +namespace Purview.EventSourcing.Skills; + +/// +/// Validates the agent skills this repository authors under skills/. +/// +/// +/// is load-bearing: TUnit does not walk base types during +/// discovery, so without it this class compiles, the run is green, and nothing is validated. +/// +[InheritsTests] +public sealed class SkillTests : PurviewSkillTests; diff --git a/src/tests/Skills.UnitTests/Skills.UnitTests.csproj b/src/tests/Skills.UnitTests/Skills.UnitTests.csproj new file mode 100644 index 00000000..a32dcfd9 --- /dev/null +++ b/src/tests/Skills.UnitTests/Skills.UnitTests.csproj @@ -0,0 +1,5 @@ + + + + + From 49d158e19bc8ec6fe41c97800e79d0da615208c1 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Sun, 25 Oct 2026 11:53:53 +0000 Subject: [PATCH 07/41] docs: describe the result, tenancy, crypto-shredding and metrics behaviour Guarantees-and-Limitations.md is the authoritative summary, so it now covers the failure vocabulary, tenant isolation per store, crypto-shredding, metrics and the originating-user capture. States the limits explicitly rather than implying parity: Azure Storage blob snapshots are not tenant-filtered directly, snapshots are disabled while payload protection is enabled, and enabling tenancy over data written while tenant-less hides it from tenant-scoped reads. --- README.md | 7 +- docs/wiki/Event-Versioning-Examples.md | 8 +- docs/wiki/Getting-Started.md | 34 +++- docs/wiki/Guarantees-and-Limitations.md | 161 ++++++++++++++++- docs/wiki/Home.md | 1 + docs/wiki/Provider-Feature-Matrix.md | 44 ++++- docs/wiki/Release-Flow.md | 11 ++ docs/wiki/Result-And-Failure-Model.md | 218 ++++++++++++++++++++++++ docs/wiki/SQL-Server-Guide.md | 9 +- docs/wiki/Shared-Testing-Framework.md | 18 +- docs/wiki/Snapshot-Schema-Versioning.md | 8 + docs/wiki/Solution-Design-Guide.md | 5 +- docs/wiki/Solution-Design-Worksheet.md | 2 +- docs/wiki/Transactional-Outbox.md | 6 +- 14 files changed, 503 insertions(+), 29 deletions(-) create mode 100644 docs/wiki/Result-And-Failure-Model.md diff --git a/README.md b/README.md index a43e2dab..0f424a61 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,7 @@ Purview Event Sourcing is a .NET event sourcing framework for building aggregate | `Purview.EventSourcing.AzureStorage` | Azure Table / Blob event store | [`src/src/AzureStorage/Sdk/README.md`](src/src/AzureStorage/Sdk/README.md) | [![NuGet](https://img.shields.io/nuget/v/Purview.EventSourcing.AzureStorage.svg)](https://www.nuget.org/packages/Purview.EventSourcing.AzureStorage) | | `Purview.EventSourcing.MongoDB` | MongoDB event stream and queryable snapshot stores | [`src/src/MongoDB/Sdk/README.md`](src/src/MongoDB/Sdk/README.md) | [![NuGet](https://img.shields.io/nuget/v/Purview.EventSourcing.MongoDB.svg)](https://www.nuget.org/packages/Purview.EventSourcing.MongoDB) | | `Purview.EventSourcing.CosmosDb` | Azure Cosmos DB queryable snapshot store | [`src/src/CosmosDb/Sdk/README.md`](src/src/CosmosDb/Sdk/README.md) | [![NuGet](https://img.shields.io/nuget/v/Purview.EventSourcing.CosmosDb.svg)](https://www.nuget.org/packages/Purview.EventSourcing.CosmosDb) | +| `Purview.EventSourcing.EntityFrameworkCore` | Shared Entity Framework Core mapping, conversion, and query translation. Brought in automatically by the SQL Server, PostgreSQL, and Cosmos DB packages; you do not install it directly | (see package source at `src/src/EntityFrameworkCore`) | [![NuGet](https://img.shields.io/nuget/v/Purview.EventSourcing.EntityFrameworkCore.svg)](https://www.nuget.org/packages/Purview.EventSourcing.EntityFrameworkCore) | | `Purview.EventSourcing.InMemory` | In-memory event/snapshot store implementation for local and test scenarios | (see package source at `src/src/InMemory`) | [![NuGet](https://img.shields.io/nuget/v/Purview.EventSourcing.InMemory.svg)](https://www.nuget.org/packages/Purview.EventSourcing.InMemory) | | `Purview.EventSourcing.Validation.FluentValidation` | `FluentValidation` adapter for aggregate save-time validation | (see package source at `src/src/Validation.FluentValidation`) | [![NuGet](https://img.shields.io/nuget/v/Purview.EventSourcing.Validation.FluentValidation.svg)](https://www.nuget.org/packages/Purview.EventSourcing.Validation.FluentValidation) | | `Purview.EventSourcing.Validation.ZodSharp` | `Purview.ZodSharp` adapter for aggregate save-time validation | (see package source at `src/src/Validation.ZodSharp`) | [![NuGet](https://img.shields.io/nuget/v/Purview.EventSourcing.Validation.ZodSharp.svg)](https://www.nuget.org/packages/Purview.EventSourcing.Validation.ZodSharp) | @@ -102,8 +103,10 @@ public sealed class OrderService(IEventStore store) { public async Task PlaceOrderAsync(string orderId, string customerId, CancellationToken cancellationToken) { - var order = await store.GetAsync(orderId, cancellationToken) - ?? await store.CreateAsync(orderId, cancellationToken: cancellationToken); + var orderResult = await store.GetAsync(orderId, cancellationToken); + var order = orderResult.IsSuccess + ? orderResult.Value + : await store.CreateAsync(orderId, cancellationToken: cancellationToken); order.CreateOrder(customerId); order.AddLineItem("SKU-1", "Demo product", 1, 19.99m); diff --git a/docs/wiki/Event-Versioning-Examples.md b/docs/wiki/Event-Versioning-Examples.md index d79fb62b..a8751e87 100644 --- a/docs/wiki/Event-Versioning-Examples.md +++ b/docs/wiki/Event-Versioning-Examples.md @@ -496,7 +496,7 @@ public async Task Replay_WithV1Events_UpcastsToV2AndAppliesCorrectly() // write an OrderCreatedEventV1 payload under the aggregate's stream. // 3. Load the aggregate (triggers replay with upcasting) - var aggregate = await eventStore.GetAsync("123", cancellationToken); + var aggregate = (await eventStore.GetAsync("123", cancellationToken)).Value; // 4. Verify the aggregate state matches the upcast event await Assert.That(aggregate.OrderId).IsEqualTo("123"); @@ -514,11 +514,11 @@ public async Task Replay_WithUnknownEventType_ReturnsUnknownEventAndContinues() // 1. Seed an event whose persisted type name does not resolve to a registered event type // 2. Load the aggregate - var aggregate = await eventStore.GetAsync("123", cancellationToken); + var result = await eventStore.GetAsync("123", cancellationToken); // 3. Verify replay continues without throwing - await Assert.That(aggregate).IsNotNull(); - await Assert.That(aggregate.SkippedEvents).IsNotEmpty(); + await Assert.That(result.IsSuccess).IsTrue(); + await Assert.That(result.Value.SkippedEvents).IsNotEmpty(); // 4. In a real test, you'd have a mixture of known and unknown events // to verify partial replay works correctly diff --git a/docs/wiki/Getting-Started.md b/docs/wiki/Getting-Started.md index e6f2213c..94e1eee4 100644 --- a/docs/wiki/Getting-Started.md +++ b/docs/wiki/Getting-Started.md @@ -95,8 +95,10 @@ public sealed class OrderService(IEventStore store) { public async Task PlaceOrderAsync(string orderId, string customerId, CancellationToken cancellationToken) { - var order = await store.GetAsync(orderId, cancellationToken) - ?? await store.CreateAsync(orderId, cancellationToken: cancellationToken); + var orderResult = await store.GetAsync(orderId, cancellationToken); + var order = orderResult.IsSuccess + ? orderResult.Value + : await store.CreateAsync(orderId, cancellationToken: cancellationToken); order.CreateOrder(customerId); await store.SaveAsync(order, cancellationToken); @@ -104,6 +106,34 @@ public sealed class OrderService(IEventStore store) } ``` +## Record who made the change + +A save records the originating user in `EventMetadata.UserId`, read from the claim named by +`EventStoreOperationContext.ClaimIdentifier`. The principal comes from `IEventStorePrincipalAccessor`, +resolved from dependency injection. + +The default implementation reads the ambient `ClaimsPrincipal.Current`. **In ASP.NET Core that is always +`null`** - the framework populates neither `ClaimsPrincipal.Current` nor `Thread.CurrentPrincipal` from the +request - so a web application must register an accessor backed by its own notion of the current user: + +```csharp +sealed class HttpContextPrincipalAccessor(IHttpContextAccessor accessor) : IEventStorePrincipalAccessor +{ + public ClaimsPrincipal? GetPrincipal() => accessor.HttpContext?.User; +} + +builder.Services.AddHttpContextAccessor(); +builder.Services.AddSingleton(); +``` + +Register it **before** `AddEventSourcing()`, or use `TryAddSingleton` semantics in mind: the framework +registers its default with `TryAddSingleton`, so an earlier registration wins. + +`RequiresValidPrincipalIdentifier` (default `true`, and settable per provider or through +`EventStoreOperationContext.RequiresValidPrincipalIdentifierDefault`) makes a save fail when no identifier +is available. Leave it on for an authenticated application; turn it off for background work, seeding, or a +sample with no authentication, where there is legitimately no user. + ## Query aggregate event history (time/range filters) ```csharp diff --git a/docs/wiki/Guarantees-and-Limitations.md b/docs/wiki/Guarantees-and-Limitations.md index f275708b..985c0d5b 100644 --- a/docs/wiki/Guarantees-and-Limitations.md +++ b/docs/wiki/Guarantees-and-Limitations.md @@ -9,10 +9,38 @@ not. Individual topics link to their detailed pages; do not duplicate conflictin optimizations or read models. - Events within a stream are persisted in aggregate-version order. Writes to different aggregates never contend. -- Providers detect conflicting writes (optimistic concurrency) and surface them as - `ConcurrencyException`/`IConcurrencyConflict`; see `ConcurrencyRetry` and `AggregateWriteLock` - for retry and in-process serialization. `EventStoreCapabilities.Concurrency` reports which - providers are optimistic versus last-writer-wins. +- Providers detect conflicting writes (optimistic concurrency) and surface them as the + `ConcurrencyConflict` case on the operation's result; see `ConcurrencyRetry` and + `AggregateWriteLock` for retry and in-process serialization. + `EventStoreCapabilities.Concurrency` reports which providers are optimistic versus + last-writer-wins. This holds whichever row the conflict is detected on - a stream-version + check or a duplicate event row for an already-persisted version are the same outcome, and a + shared contract test asserts it against every event-store provider. +- Inside a transaction the same failure arrives on `TransactionAggregateResult.Failure`. + `Error` carries only genuine exceptions, so a save that failed for a reason the caller can act + on is never reported as an unexplained `Saved == false`. + +## Expected failures are results; exceptions are exceptional + +See [Result and Failure Model](Result-And-Failure-Model.md) for the full vocabulary. + +- A failure a correct caller can anticipate and act on is a **result case**. A failure that means + the system, the configuration or the calling code is wrong stays an **exception**. Cancellation is + always `OperationCanceledException`. +- `GetAsync`, `GetAtAsync`, `GetOrCreateAsync` and `GetDeletedAsync` return + `Result`. None of them returns `null`, so "absent" and "deleted" are no + longer the same answer. +- `SaveAsync`, `DeleteAsync` and `RestoreAsync` return `Result, …>`. A success that + wrote nothing is still a success: `SaveOutcomeKind` distinguishes `Written`, `NoChanges` and + `AlreadyApplied` (an idempotency marker matched), which the old `bool` conflated with failure. +- The failure cases are shared across every provider, so a caller handles `AggregateNotFound`, + `AggregateDeleted`, `AggregateLocked`, `ConcurrencyConflict` or `AggregateInvalid` without + referencing a provider assembly. +- `CommitException` and the provider infrastructure exceptions still throw: storage refusing a write + is not an outcome a caller can act on. +- `ExistsAsync` returns `AggregateExistence`, which was already a typed outcome. It carries `DoesExist` + and `IsDeleted` separately, because an aggregate that exists in a deleted state is not the same answer + as one that exists, and it has no conversion to `bool` that could flatten the two. ## Transaction guarantees and failure modes @@ -40,6 +68,120 @@ Providers persist and expose event metadata where supported `CorrelationId`, `CausationId`, `UserId`, `IdempotencyId`, `AggregateVersion`, and `When`. A field that is not preserved by a provider is exposed as `null`/default. +## Crypto-shredding + +Opt-in. An event implementing `IEventDataSubject` has its payload encrypted (AES-GCM-256) under a key +belonging to that subject, held in `IEventCryptoKeyStore`. Erasing the key erases the subject's data +everywhere it appears, without rewriting or deleting a single event, and without touching any other +subject's data. + +- The ciphertext is stored as an envelope **in place of the plaintext payload**, so no provider needs a + schema change. A payload written before protection was configured is still readable. +- The subject id is bound into the encryption as associated data, so ciphertext cannot be re-attributed + from one subject to another. +- On replay, a payload whose key has been erased is surfaced as an unknown event: the aggregate version + still advances, the read succeeds, and the gap is reported through `AggregateBase.SkippedEvents`. + Replay never fails because somebody exercised their right to erasure. +- Wired for the SQL Server, PostgreSQL, MongoDB and Azure Storage event stores, including the Azure blob + route used for oversized events. + +**Snapshots are disabled while payload protection is enabled.** A snapshot serializes aggregate state, +which holds the same personal data in clear, and one snapshot can span many subjects - so it cannot be +encrypted under any single subject's key. A snapshot surviving key erasure would make crypto-shredding +untrue, so a store configured with an `IEventPayloadProtector` does not write snapshots at all. Replay +from events stays correct; reads of long streams are slower. Existing snapshots written before protection +was enabled are **not** retrospectively removed - delete them as part of enabling protection. + +The in-memory store holds live objects rather than serialized payloads, so there is nothing to encrypt +and crypto-shredding does not apply to it. + +## Multi-tenancy + +Opt-in, and **currently enforced only by the SQL Server and PostgreSQL providers**. + +- `ICurrentTenant` supplies the `TenantScope` an operation runs under. The default registration reports + `TenantScope.System`, which applies no filter, so a single-tenant deployment is unaffected. +- A multi-tenant host registers its own `ICurrentTenant` - typically resolving the tenant from a claim on + the current principal - before `AddEventSourcing()`. +- `TenantScope.System` is a distinct state rather than a null tenant id, so a resolver that *fails* to + determine a tenant can never be mistaken for permission to read every tenant. Use it for infrastructure + work that deliberately crosses tenants; `AmbientCurrentTenant.BeginScope` changes scope temporarily, + which is how a super user selects a tenant. +- Rows carry a `TenantId`, stamped on write, and reads are constrained by an Entity Framework global query + filter. The filter is the enforcement point: a read that forgets the tenant is the failure this exists to + prevent, so it is applied to the entity rather than to individual queries. +Enforced by every event store - SQL Server, PostgreSQL, MongoDB, Azure Storage and in-memory - and by the +SQL Server, PostgreSQL, MongoDB and Cosmos DB queryable snapshot stores. The mechanism differs by what the +store can express, but the guarantee does not: + +| Store | Mechanism | +| --- | --- | +| SQL Server, PostgreSQL | `TenantId` column with an Entity Framework global query filter | +| MongoDB | `TenantId` field composed into every read and delete filter | +| Azure Storage | `TenantId` property, composed into the OData filter; point reads filtered on read-back | +| Cosmos DB snapshots | `__tenantId` shadow property, applied after `WithPartitionKey` | +| In-memory | Ownership tracked beside the data | + +**Azure Storage snapshots are blob-backed and are not tenant-filtered.** Everything else above is. + +### A tenant-less deployment + +Registering no `ICurrentTenant` leaves the scope as `TenantScope.System`: every filter short-circuits, no +tenant predicate is applied, and writes record no owner. A single-tenant deployment therefore behaves +exactly as it did before tenancy existed, and needs no configuration. + +**An unowned row is visible only to the system scope.** The filters deliberately do *not* treat a null +`TenantId` as visible to every tenant. That choice matters more than it looks: if any write path ever +fails to stamp the tenant, the row becomes invisible to its own tenant - an obvious, reported absence - +rather than silently readable by all of them. Fail-closed turns a stamping bug into missing data instead +of a cross-tenant leak. + +The consequence is that **enabling tenancy over data written while tenant-less hides that data from +tenant-scoped reads**. The system scope still sees it. Backfill `TenantId` on existing rows as part of +enabling tenancy, or read that data under `TenantScope.System`. + +### Admin portal + +- `AdminPortalOptions.EnforceTenantScope` (off by default) requires every admin request to resolve to a + single tenant. `IAdminTenantResolver` decides it from the caller's entitlements and the tenant named in + the `Purview-Tenant` header; the default implementation reads tenant claims. +- An administrator entitled to one tenant is scoped to it. One entitled to several - a super user - must + name the tenant; naming none is refused with `400`, and naming an unentitled tenant with `403`. **There + is no fallback that serves every tenant**: the resolver returns a tenant identifier and nothing else, so + the system scope is unreachable from a signed-in session. +- The filter is applied to the whole admin route group before any endpoint is mapped, so an endpoint added + later cannot escape tenant scoping by omitting it. + +## Metrics + +Every storage provider records the same instruments on the `Purview.EventSourcing` meter, so a dashboard +built against one provider keeps working against another. Instrument and tag names are a compatibility +contract. + +| Instrument | Kind | Tags | +| --- | --- | --- | +| `purview.eventsourcing.save.duration` | Histogram (ms) | `aggregate.type`, `outcome` | +| `purview.eventsourcing.get.duration` | Histogram (ms) | `aggregate.type` | +| `purview.eventsourcing.events.appended` | Counter | `aggregate.type` | + +`outcome` is `written`, `no-changes`, `already-applied`, or the failure case - `concurrency-conflict`, +`locked`, `deleted`, `invalid`. Only a returned result is recorded; an exception escaping a save is an +infrastructure fault, already reported through logging and the activity. `events.appended` counts only a +real write, so an empty save or an idempotent replay records nothing rather than a zero. + +Recording requires the host to have configured metrics (`IMeterFactory`, registered by +`AddMetrics()` and by default in ASP.NET Core). Without it the recorder is a no-op: metrics are never a +precondition for persisting events. + +## Originating user + +`EventMetadata.UserId` is read from the claim named by `EventStoreOperationContext.ClaimIdentifier`, taken +from the `IEventStorePrincipalAccessor` registered in dependency injection. The default accessor reads the +ambient `ClaimsPrincipal.Current`, which ASP.NET Core never populates, so a web application must register +its own; see [Getting Started](Getting-Started.md#record-who-made-the-change). With +`RequiresValidPrincipalIdentifier` enabled and no identifier available, the save fails rather than +recording an anonymous change. + ## Schema evolution, manifests, and upcasters - [Event-Versioning-Strategy.md](Event-Versioning-Strategy.md) describes how to evolve event @@ -83,8 +225,10 @@ facts for package selection. `GET /admin/api/aggregates/{aggregateType}/{aggregateId}/snapshot`, and the opt-in mutation `POST /admin/api/aggregates/{aggregateType}/{aggregateId}/snapshot/rebuild`) are opt-in, separately authorized, and audited through `IAdminAuditLogger` (default in-memory; replace with a - durable implementation in production). Health reflects whether the capability contract resolves; - it does not probe live storage. The manifest endpoint reports the runtime event-contract manifest + durable implementation in production). Health probes the configured storage through the provider's + `IAdminStorageProbe` and reports `Healthy`, `Unhealthy`, or `Unknown` when no probe is registered; + the probe failure is logged rather than returned, because a storage error can carry endpoint or + credential detail. The manifest endpoint reports the runtime event-contract manifest and its compatibility status against a supplied baseline. A snapshot rebuild reconstructs the aggregate from its canonical event stream and persists a fresh snapshot; it is idempotent and requires both an event-backed `IEventStore` and a registered `IQueryableEventStore`. @@ -96,6 +240,11 @@ facts for package selection. provider-converted scalar value objects may not translate deep members through `.Value`; see the [Provider Feature Matrix](Provider-Feature-Matrix.md) and [SQL Server Guide](SQL-Server-Guide.md) for exact limits. +- The Cosmos DB snapshot store shares that Entity Framework mapping, so the same member shapes are + supported and rejected. It differs in paging: continuation tokens are native Cosmos DB tokens - + opaque, forward-only, and `null` on the final page - and Cosmos DB reports no total count while + paging. Ordering by more than one member, or ordering alongside a range filter, needs a matching + composite index declared through `CosmosDbIndexOptions.CompositeIndices`. ## Unknown-event handling and recovery diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md index 497e9110..63bc5c09 100644 --- a/docs/wiki/Home.md +++ b/docs/wiki/Home.md @@ -12,6 +12,7 @@ This wiki is the project documentation hub for framework features, provider capa - [Provider Capabilities](Provider-Capabilities.md) - [Transactional Outbox](Transactional-Outbox.md) - [Transaction Guarantees](Transaction-Guarantees.md) +- [Result and Failure Model](Result-And-Failure-Model.md) - [Event Contract Manifest](Event-Contract-Manifest.md) - [Event Versioning Strategy](Event-Versioning-Strategy.md) - [Event Versioning Examples](Event-Versioning-Examples.md) diff --git a/docs/wiki/Provider-Feature-Matrix.md b/docs/wiki/Provider-Feature-Matrix.md index 4b543ae4..5be4e332 100644 --- a/docs/wiki/Provider-Feature-Matrix.md +++ b/docs/wiki/Provider-Feature-Matrix.md @@ -17,7 +17,9 @@ per-registration values. | Provider-neutral transaction guarantee | Explicit `BestEffort` or required `Atomic` | Atomic within one database boundary | Atomic within one database boundary | Best effort | Best effort | Best effort | | Transactional outbox (atomic with events) | No | Yes (`AddSqlServerOutbox`) | Yes (`AddPostgresOutbox`) | No | No | No | | Provider-specific native transaction factory | No | `ISqlServerEventStoreTransactionFactory` | `IPostgresEventStoreTransactionFactory` | No | No | No | -| Runtime-configured JSON payload indexes | No | Yes (event + snapshot stores, auto-create path) | Yes (GIN + expression indexes on event + snapshot stores) | No | No | No | +| Runtime-configured JSON payload indexes | No | Yes (event + snapshot stores, auto-create path) | Yes (GIN + expression indexes on event + snapshot stores) | No | No | Yes (container indexing policy, including composite and spatial paths) | +| Snapshot query paging | n/a | Offset (integer continuation) | Offset (integer continuation) | n/a | Offset (integer continuation) | Native Cosmos DB continuation tokens | +| Snapshot query mapping | n/a | Entity Framework | Entity Framework | n/a | MongoDB driver | Entity Framework | | DI registration helpers | `AddNullQueryableEventStore()` | `AddSqlServerEventStore()`, `AddSqlServerSnapshotQueryableEventStore()` | `AddPostgresEventStore()`, `AddPostgresSnapshotQueryableEventStore()` | `AddAzureStorageEventStore()` | `AddMongoDBEventStore()`, `AddMongoDBSnapshotQueryableEventStore()` | `AddCosmosDbSnapshotQueryableEventStore()` | ## Selection guidance @@ -46,11 +48,14 @@ guaranteed per stream. The following capabilities are built in: - **Strategy-gated snapshots.** The SQL Server/PostgreSQL same-table snapshot honors `ISnapshotStrategy` (defaults to every save, preserving historical behavior) and per-operation overrides via `SetSnapshotStrategy`, so write amplification can be tuned. -- **Concurrency retry + in-process serialization.** `ConcurrencyRetry.ExecuteAsync` retries conflicts (all provider - `ConcurrencyException` types implement `IConcurrencyConflict`) with exponential backoff; `AggregateWriteLock` - serializes read-modify-write work per stream within a process. -- **Conflict recognition across providers.** MongoDB duplicate-key writes now surface as `ConcurrencyException` (not - `CommitException`), and the in-memory store throws on conflicting versions instead of silently dropping them. +- **Concurrency retry + in-process serialization.** `ConcurrencyRetry.ExecuteAsync` retries conflicts with exponential + backoff — the result overload retries while the operation returns `ConcurrencyConflict`, and the exception overload + remains for operations that still throw; `AggregateWriteLock` serializes read-modify-write work per stream within a + process. +- **Conflict recognition across providers.** Every provider reports a lost optimistic-concurrency check as the same + `ConcurrencyConflict` case, carrying the expected and actual stream versions. MongoDB duplicate-key writes report a + conflict rather than a commit failure, and the in-memory store reports conflicting versions instead of silently + dropping them. - **Partial-replay detection.** `AggregateBase.SkippedEvents` reports events skipped during replay so callers can detect a partially reconstructed aggregate in a mixed-version fleet. `SkippedEvents` is replay-transient metadata and is **not** persisted in SQL Server/PostgreSQL EF-backed snapshot payloads; snapshot reads reconstruct stored aggregate @@ -65,8 +70,9 @@ guaranteed per stream. The following capabilities are built in: - **Hot-partition mitigation / sharding.** A stream is a single aggregate instance; a hot aggregate concentrates onto one partition in every provider. SQL Server per-aggregate-type table/schema overrides and provider-native partitioning are the available levers. -- **Snapshot query listing paging is offset-based.** Queryable store `ListAsync`/`QueryAsync` continuation is an integer - skip; deep pages are O(n). Keyset conversion for arbitrary `orderBy` clauses is not implemented. +- **Snapshot query listing paging is offset-based** for the SQL Server, PostgreSQL and MongoDB query stores. Queryable + store `ListAsync`/`QueryAsync` continuation is an integer skip; deep pages are O(n). Keyset conversion for arbitrary + `orderBy` clauses is not implemented. The Cosmos DB store is the exception: it pages with native continuation tokens. - **Event-stream aggregate listing is an unbounded scan.** `GetAggregateIdsAsync` streams ids in deterministic (ordered) form but does not support keyset resumption through the API. @@ -81,6 +87,28 @@ indexes, and per-type schema overrides). - Applications may also pair one event-store provider with a different query-store provider when that better fits read requirements. +### Cosmos DB query translation notes + +- The Cosmos DB snapshot store is Entity Framework-backed and shares the SQL Server/PostgreSQL snapshot mapping, so the + same member shapes are supported and the same shapes are rejected. The aggregate is mapped as the document root, so + predicates translate against the document itself. +- Paging uses **Cosmos DB continuation tokens** rather than an offset, so deep pages cost the same as shallow ones. + Tokens are opaque, forward-only, and the token returned with the final page is `null`. `IncludeTotalCount` issues a + separate `COUNT` query. +- Every query is scoped to the aggregate type's partition. Comparisons against `AggregateType` in a caller predicate are + folded to a constant, as they are for the SQL providers. +- `ToLowerInvariant()`/`ToUpperInvariant()` are rewritten to `ToLower()`/`ToUpper()` so they translate to `LOWER`/ + `UPPER`; `StringComparison` overloads of `Equals`, `Contains`, `StartsWith` and `EndsWith` translate natively. +- Ordering by more than one member, or ordering alongside a range filter, requires a matching composite index — configure + it through `CosmosDbIndexOptions.CompositeIndices`. +- Cosmos DB cannot report a total page or item count while paging, and does not support backwards paging. +- Dictionary members and other read-only collection members are not part of the queryable snapshot shape; mark them + `[EFOpaque]` to persist them as converted JSON, or remodel them as complex entry collections to query their contents. +- Writing a snapshot costs one additional request: Entity Framework has no Cosmos DB upsert, so the store establishes + whether the document exists before writing it. +- Container creation and the indexing policy remain on the Azure Cosmos DB SDK, because Entity Framework does not emit a + container indexing policy. + ### SQL Server query translation notes - SQL snapshot queries support predicates over JSON-mapped primitive members and supported value-object shapes. diff --git a/docs/wiki/Release-Flow.md b/docs/wiki/Release-Flow.md index 219c2dbd..ea2faaac 100644 --- a/docs/wiki/Release-Flow.md +++ b/docs/wiki/Release-Flow.md @@ -56,6 +56,17 @@ The shared workflow: A release is therefore produced simply by bumping `package.json` (via changesets) and merging to `main`. Do not create release tags manually. +## Release gates for 2.0.0 + +The 2.0.0 GA release is gated on all of the following. A prerelease may ship without them; a stable release may not. + +| Gate | Why | +| --- | --- | +| **.NET 11 is GA, and every dependency is re-pinned to the stable line** | The repository builds against `11.0.0-rc.2.*` for the runtime, EF Core and SourceLink, and `11.0.0-rc.2` for the Npgsql EF provider. Shipping a stable package against release-candidate dependencies is not supportable. Re-pin `DotnetRuntimeVersion`, `Npgsql.EntityFrameworkCore.PostgreSQL`, `System.Security.Cryptography.Pkcs` and `Microsoft.SourceLink.GitHub`, then re-run the full build, unit and provider integration suites. | +| **`LangVersion` is reviewed** | C# 15 union declarations are a preview language feature and back the result model. If unions have not stabilised by GA, the decision to ship on `LangVersion=preview` must be taken explicitly rather than inherited. | +| **Every declared capability is behaviourally contract-tested** | `EventStoreCapabilities` is a promise to consumers; a capability that is advertised but unverified is a defect. | +| **Provider integration suites pass in CI** | The unit filter never starts a container, so provider regressions are otherwise invisible. | + ## Prerelease support Prerelease versions (any SemVer containing a hyphen, for example `2.0.0-prerelease.29`) release through the same diff --git a/docs/wiki/Result-And-Failure-Model.md b/docs/wiki/Result-And-Failure-Model.md new file mode 100644 index 00000000..5cf7d4d0 --- /dev/null +++ b/docs/wiki/Result-And-Failure-Model.md @@ -0,0 +1,218 @@ +# Result and Failure Model + +> **Status: implemented.** Every step in the rollout table below is done. This page is now the reference +> for the failure vocabulary the event store returns, and the record of the decisions that shaped it. + +## Why + +Three problems in the model this replaced. + +**Failure types are duplicated per provider.** `ConcurrencyException`, `AggregateDeletedException`, +`AggregateLockedException`, `AggregateNotDeletedException`, `AggregateAlreadyDeletedException`, +`MissingAggregateIdException` and `CommitException` each exist **four or five times** — once in +`AzureStorage`, `MongoDB`, `Postgres`, `SqlServer`, and `InMemory` for concurrency. They share no base type. +A caller cannot write a provider-portable `catch`, which is why the empty marker interface +`IConcurrencyConflict` exists at all: it is the one bridge, and it only covers concurrency. + +**`bool` conflates "nothing to do" with "failed".** `SaveResult` converts implicitly to `bool`, +and its own documentation says a `false` "does not always mean failure, it may mean there was no events to +save, or the events were already saved — in the case where idempotency markers are recorded and validated". +Two very different outcomes, one value. + +**`null` conflates "absent" with "deleted".** `GetAsync` returned `T?`, and whether a soft-deleted aggregate +came back as `null` or threw was controlled by `EventStoreOperationContext.DeleteMode`. The caller could not +tell the cases apart from the return value. + +Results fix all three at once: the vocabulary becomes a small set of **core, shared, provider-neutral types**, +and the compiler forces callers to handle them. + +## Principle + +> A failure that a correct caller can anticipate and act on is a **result case**. +> A failure that means the system, the configuration or the calling code is wrong is an **exception**. + +Cancellation is always an exception (`OperationCanceledException`), as everywhere else in .NET. + +## Case vocabulary + +Core types in `Purview.EventSourcing`, each a small `readonly record struct` carrying the identity needed to +act on it. Versions are `long` from the outset, so the Phase 6 `int`→`long` widening is not a second break. + +| Case | Payload | Meaning | +| --- | --- | --- | +| `AggregateNotFound` | type, id | No stream exists | +| `AggregateDeleted` | type, id | The stream exists and is soft-deleted | +| `AggregateNotDeleted` | type, id | Restore, or `GetDeletedAsync`, attempted on a live aggregate | +| `AggregateAlreadyDeleted` | type, id | Delete attempted on an already-deleted aggregate | +| `AggregateLocked` | type, id | The aggregate is locked against modification | +| `ConcurrencyConflict` | type, id, expected version, actual version | Optimistic concurrency lost | +| `AggregateInvalid` | `ValidationResult` | Validation rejected the aggregate before any write | + +## Unions + +One union per **operation family**, not per method. Cases are deliberately shared between families. + +```csharp +[GenerateResult] +public readonly union AggregateReadFailure( + AggregateNotFound, AggregateDeleted, AggregateNotDeleted, AggregateLocked); + +[GenerateResult] +public readonly union AggregateSaveFailure( + ConcurrencyConflict, AggregateDeleted, AggregateLocked, AggregateInvalid); + +[GenerateResult] +public readonly union AggregateDeleteFailure( + AggregateNotFound, AggregateAlreadyDeleted, AggregateLocked, ConcurrencyConflict); + +[GenerateResult] +public readonly union AggregateRestoreFailure( + AggregateNotFound, AggregateNotDeleted, AggregateLocked, ConcurrencyConflict); +``` + +**Authoring rule that follows from the sharing.** A leaf case listed in more than one union gets its per-case +`AsFailure()` helper generated only once, and the generator reports `RSG1006`. Construct shared cases +through the union-receiver factory, which always names the union you mean: + +```csharp +// Correct - names the union. +return AggregateSaveFailure.Failure(new AggregateLocked(type, id)); + +// Wrong for a shared case - can bind to a different union's helper. +return new AggregateLocked(type, id).AsFailure(); +``` + +Cases unique to one union may use the shorter `AsFailure()` form. + +## What stays an exception + +| Type | Why | +| --- | --- | +| `CommitException` | Storage refused the write — infrastructure, not an expected outcome | +| `AggregateStreamVersionMissingException` | The stream is corrupt; no caller can sensibly continue | +| `MissingAggregateIdException`, `IdAlreadySetException` | Programming errors in aggregate construction | +| `UnregisteredEventException` | The aggregate never registered the event — a wiring defect | +| `EventStoreTransactionGuaranteeException` | A required guarantee the provider cannot honour: a startup contract violation | +| `InvalidPartitionKeyException`, `TableOperationException` | Provider-level infrastructure faults | + +## Mapping from today + +| Today | Tomorrow | +| --- | --- | +| `ConcurrencyException` ×5 | one core `ConcurrencyException`, translated at the provider boundary into the `ConcurrencyConflict` case. The type and the `IConcurrencyConflict` marker remain for the paths that still raise one; no save throws it | +| `AggregateDeletedException` / `AggregateIsDeletedException` ×4 | `AggregateDeleted` case | +| `AggregateAlreadyDeletedException` ×4 | `AggregateAlreadyDeleted` case | +| `AggregateNotDeletedException` / `AggregatedNotAlreadyDeletedException` ×4 | `AggregateNotDeleted` case | +| `AggregateLockedException` ×4, `LockedException` | `AggregateLocked` case | +| `ValidationException` thrown by `SaveResult.EnsureValid()` | `AggregateInvalid` case | +| `GetAsync` returning `null` | `AggregateNotFound` case | + +The ~25 duplicated provider exception files are **deleted**; providers translate their storage errors into the +core cases at the provider boundary. + +## Consequences for existing API + +**`SaveResult` is replaced** by `Result, AggregateSaveFailure>`, where +`SaveOutcome` carries the aggregate and why no write occurred when none did +(`Written`, `NoChanges`, `AlreadyApplied` for an idempotent replay). This removes the `Saved`/`Skipped` +ambiguity and the implicit `bool` conversion. + +> **Blast radius.** `bool saved = await store.SaveAsync(...)` was used throughout the samples, fixtures and the +> shared contract suites. Every one became an explicit result check, done in one pass. + +**`LockHandlingMode` is deleted outright**, along with `EventStoreOperationContext.LockMode`. Removing the +throwing mode left one member, and a one-member enum is not a choice: a locked aggregate is always reported as +`AggregateLocked`. + +**Delete and restore widen the save's failure.** Both append an event through the save path, so +`AggregateSaveFailure` is mapped into their own families — `AggregateDeleted` becomes +`AggregateAlreadyDeleted` for a delete, and a lost concurrency check now reaches the caller as +`ConcurrencyConflict` instead of being flattened into "no changes". Validation can reject either, so +`AggregateInvalid` joined both unions. + +**`DeleteHandlingMode` shrinks to two members.** The throwing mode is gone; the remaining two decide whether a +deleted aggregate is an outcome or a failure: + +```csharp +public enum DeleteHandlingMode +{ + ReturnsFailure = 0, // default - reported as AggregateDeleted + ReturnsAggregate, // returned in its deleted state, as a success +} +``` + +`ReturnsNull` is renamed because nothing returns null any more, and `ReturnsAggregate` has to be a *success* +rather than "the case plus the state": the cases are non-generic core records, so none of them can carry a +`T`. `GetDeletedAsync` is the one caller that asks for `ReturnsAggregate`. + +**`ExistsState` was already a typed outcome, not an error**, so it survived the migration unchanged. The +API cleanup then renamed it `AggregateExistence` and removed its implicit `bool` conversion, which was +flattening "exists in a deleted state" into "exists"; see the note below on `IsDeletedAsync`. + +**Query APIs stay as they are.** A predicate that cannot be translated is a programming error, so +`IQueryableEventStoreCore` keeps throwing. See the decision below. + +## Tooling constraints + +Two things the toolchain imposes, both verified against the code rather than assumed: + +- **CSharpier cannot format a union.** Version 1.3.0 — the latest — reports *"Was not formatted due to + syntax errors"* for any file containing a `union` declaration. Union declarations therefore live in + dedicated files matched by `**/Failures/*Failure.cs` in `.csharpierignore`; the exclusion is removed when + CSharpier supports the syntax. Everything else, including the case types, formats normally. +- **`RSG1006` is expected and suppressed in the core project.** The unions deliberately share leaf cases, so + each shared case has its `AsFailure` helper generated for one union only. Using the wrong helper is a + compile error, not a silent mis-binding, which is why the suppression is safe. + +## Composition + +Callers of several stores wrap the callee unions as cases rather than re-listing leaves, then widen with +`Bind`/`MapError`: + +```csharp +[GenerateResult] +public readonly union PlaceOrderFailure(AggregateSaveFailure, AggregateReadFailure); +``` + +The Admin API maps results to HTTP in one place, so the mapping from `AdminAggregateNotFound` → 404 lives +there instead of in every endpoint. + +> `Purview.Results.AspNetCore` is the intended home for this. The published version (1.0.0.1) keeps +> `ToHttpResult` and `ResultHttpExtensions` internal, exposing only the endpoint filter — which cannot be +> used by handlers that also return validation problems. Until a release exposes the mapper, `Admin.API` +> owns a single `AdminQueryFailureResults` table and the package is not referenced. + +## Rollout + +The conversion ran **one operation family at a time**, each ending with a green build: changing the whole +contract at once would have left the repository non-compiling across far more work than a single change +should span. Measured call sites: `SaveAsync` 419, `GetAsync` 412, `DeleteAsync` 134, `SaveResult` 179. + +| # | Step | Status | +| --- | --- | --- | +| 1 | Case types and unions in core — additive | **Done** | +| 2 | Unify the duplicated provider exception types into core | **Done** — 36 definitions deleted, 3 of them never constructed | +| 3 | `DeleteAsync` / `RestoreAsync` through contract, facades, extensions, all five providers, snapshot stores and callers | **Done** | +| 4 | `GetAsync` / `GetAtAsync` / `GetOrCreateAsync` / `GetDeletedAsync` → `Result` | **Done** — `DeleteHandlingMode.ThrowsException` removed with it | +| 5 | `SaveAsync` → `Result, AggregateSaveFailure>`; retire `SaveResult` | **Done** — `LockHandlingMode` removed with it | +| 6 | Admin query services, and map results to HTTP in the Admin API | **Done** — mapping is local to the Admin API; see the note below | +| 7 | `ConcurrencyRetry` retargeted from `IConcurrencyConflict` to the `ConcurrencyConflict` case; delete the transitional exception types | **Done** — result-aware overload added; four dead exception types deleted | +| 8 | Update `Guarantees-and-Limitations.md` and the provider guides | **Done** | + +Steps 4 and 5 were the large ones. Steps 5 and 7 had to land together: the moment a provider stops throwing +`ConcurrencyException`, an exception-based retry loop silently stops retrying. + +## Still outstanding + +Nothing. `IsDeletedAsync` — the last read on the old model, returning `bool` and throwing for a missing +stream — was removed in the API cleanup. Its one distinct answer is now `AggregateExistence.IsDeleted`, +alongside `DoesExist`, on the result `ExistsAsync` already returned. + +## Decisions + +| Question | Decision | +| --- | --- | +| Query failures | `IQueryableEventStoreCore` **keeps throwing**. A predicate that cannot be translated is a programming error, not an outcome a caller can act on, so no `QueryFailure` union is introduced. | +| `DeleteHandlingMode` | **Kept**, reduced to `ReturnsFailure` (default) and `ReturnsAggregate`. The throwing behaviour is removed. The original wording — "the case plus the deleted state" — turned out to be unimplementable, because the core cases are non-generic and cannot carry a `T`; `ReturnsAggregate` therefore returns a success. | +| `AggregateNotDeleted` in the read union | **Added.** `GetDeletedAsync` is a read that can fail because the aggregate is live, and it used to throw `AggregateNotDeletedException`. Widening the read union by one case beat minting a per-method union for it; the other reads never produce it. | +| `SaveOutcome` granularity | **Three outcomes**: `Written`, `NoChanges`, `AlreadyApplied`. An idempotent replay and an empty save are operationally different — the first proves a marker matched, the second that the caller had nothing to persist — and collapsing them would re-create the ambiguity this change exists to remove. | diff --git a/docs/wiki/SQL-Server-Guide.md b/docs/wiki/SQL-Server-Guide.md index 263c920f..ebeb7627 100644 --- a/docs/wiki/SQL-Server-Guide.md +++ b/docs/wiki/SQL-Server-Guide.md @@ -70,7 +70,11 @@ public class OrderService(IEventStore store) { public async Task PlaceOrderAsync(string orderId, string customerId) { - var order = await store.GetOrCreateAsync(orderId); + var result = await store.GetOrCreateAsync(orderId); + if (result.IsFailure) + return; + + var order = result.Value; order.CreateOrder(customerId, 0m); await store.SaveAsync(order); } @@ -657,7 +661,8 @@ Generator Behaviors](Source-Generator-Behaviors.md). ## Behavior Notes and Caveats -- `IsDeletedAsync` throws when the aggregate does not exist (it does not return `false` for missing aggregates). +- Reads and writes return results rather than `null` or `bool`; see + [Result and Failure Model](Result-And-Failure-Model.md) for the cases each operation can report. - Event replay is tolerant by default: unknown or unappliable events are skipped, and stream version continues to advance. - Integration coverage includes replay compatibility scenarios for: diff --git a/docs/wiki/Shared-Testing-Framework.md b/docs/wiki/Shared-Testing-Framework.md index a7cd6f47..fb5da1af 100644 --- a/docs/wiki/Shared-Testing-Framework.md +++ b/docs/wiki/Shared-Testing-Framework.md @@ -104,7 +104,23 @@ notifications, event ranges, query results) and shared aggregates (`PersistenceA ## Environment notes -- Integration suites require Docker and the provider images (Testcontainers). +- Integration suites start their containers through [Purview.Containers](https://www.nuget.org/packages/Purview.Containers), + which selects **WSL Containers** on a Windows host and **Docker** everywhere else. Either runtime + works; nothing in the fixtures names one. Pin a backend with `PURVIEW_CONTAINERS_BACKEND=wsl` or + `=docker` to fail loudly instead of falling back. +- Under WSL Containers a session holds an exclusive lock on its image store, so run the integration + suites one module at a time: `just test '/*/*/*/*' --max-parallel-test-modules 1`. +- Azure Storage, Cosmos DB, PostgreSQL and SQL Server use the matching service modules. MongoDB and + the Cosmos DB emulator have no module, so `MongoDBTestContainer` and `CosmosDbTestContainer` in + `SharedTestingFramework` build them from the generic `ContainerBuilder` — including the MongoDB + single-node replica set the event store's transactions need. - The Azure/Cosmos/Mongo snapshot fixtures rely on Azurite; the SQL fixtures on a SQL Server image. +- **The Cosmos DB suite cannot pass against the `vnext` emulator.** That emulator's query engine does + not resolve the `root` alias Entity Framework emits (`SELECT VALUE c FROM root c`) and answers every + query with `400 SC2001 Identifier 'root' could not be resolved`, including the existence check the + snapshot write performs. The alias is not configurable in EF. The classic emulator image accepts it, + as the service itself does, but is heavy enough to be unreliable under a default WSL Containers + session. Until the vnext query engine supports the alias, validate the Cosmos provider against a + real Cosmos DB account. - The CI pipeline runs only the unit-test tree filter; integration suites are exercised locally or via an opt-in run. \ No newline at end of file diff --git a/docs/wiki/Snapshot-Schema-Versioning.md b/docs/wiki/Snapshot-Schema-Versioning.md index 5333c2bb..0f706483 100644 --- a/docs/wiki/Snapshot-Schema-Versioning.md +++ b/docs/wiki/Snapshot-Schema-Versioning.md @@ -24,6 +24,14 @@ This fallback is safe because it never mutates the event stream and never treats version bump may temporarily increase replay work, so deploy it before removing runtime types or converters needed by old snapshot payloads if a rolling deployment must support both application versions. +## Cosmos DB document shape change + +The Cosmos DB snapshot store now maps documents with Entity Framework rather than serializing the aggregate with +`System.Text.Json`. Documents written by an earlier version do not match the new model and are not read back. Because +snapshots are replaceable, the migration is a re-snapshot: delete the container's documents (or the container) and let +snapshot-eligible saves rewrite them, or rebuild them from the event stream through the Admin portal. No event data is +affected. + ## Administrative inspection and rebuild The Admin portal reports whether a snapshot is materialized for an aggregate diff --git a/docs/wiki/Solution-Design-Guide.md b/docs/wiki/Solution-Design-Guide.md index 1cfaea6f..2b5a8bc2 100644 --- a/docs/wiki/Solution-Design-Guide.md +++ b/docs/wiki/Solution-Design-Guide.md @@ -414,8 +414,9 @@ public sealed class OrderAggregate : AggregateBase Do not rely only on save-time validation for user-facing command errors. Put business guard clauses near the command method as well so invalid operations fail before an event is created. -`SaveResult` carries `Saved`, `Skipped`, and `ValidationResult`. Check `IsValid` or call `EnsureValid()` -when callers need validation failures surfaced as exceptions. +`SaveAsync` returns `Result, AggregateSaveFailure>`. A success carries the outcome +(`Written`, `NoChanges` or `AlreadyApplied`); a validation rejection arrives as the `AggregateInvalid` case, +which carries the `ValidationResult`. ## Implementation Pattern diff --git a/docs/wiki/Solution-Design-Worksheet.md b/docs/wiki/Solution-Design-Worksheet.md index 56b92702..33465418 100644 --- a/docs/wiki/Solution-Design-Worksheet.md +++ b/docs/wiki/Solution-Design-Worksheet.md @@ -125,7 +125,7 @@ Validation checks: - Command errors fail before events are recorded. - Save-time validation covers whole-aggregate consistency. - Replay/hydration paths do not reject historical facts that were valid when written. -- Validation failures are surfaced from `SaveResult` where needed. +- Validation failures are surfaced as the `AggregateInvalid` case where needed. ## Operation Semantics diff --git a/docs/wiki/Transactional-Outbox.md b/docs/wiki/Transactional-Outbox.md index 1a265fc8..40b79a67 100644 --- a/docs/wiki/Transactional-Outbox.md +++ b/docs/wiki/Transactional-Outbox.md @@ -83,7 +83,11 @@ Enqueuing with the same `IdempotencyKey` again is a no-op (deduplicated at the s ## Concurrent dispatchers Multiple dispatchers (or hosts) may run concurrently. The lease claim is atomic, so each message is -claimed by exactly one dispatcher at a time. See `SqlServerOutboxIntegrationTests` and +claimed by exactly one dispatcher at a time. Disjointness comes from the row lock the claim takes +while selecting candidates — `FOR UPDATE SKIP LOCKED` on Postgres, `WITH (UPDLOCK, READPAST, +ROWLOCK)` on SQL Server. Without it a concurrent claim blocks on the same rows and then re-applies +the update once the first transaction commits, handing both dispatchers the same batch. +See `SqlServerOutboxIntegrationTests` and `PostgresOutboxIntegrationTests` for real-provider coverage of atomic commit/rollback, retry/poison, deduplication, and concurrent claim disjointness. From 9bb2f8b623c1669f561e92596a40e0f4ef3415cd Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Sun, 25 Oct 2026 11:54:08 +0000 Subject: [PATCH 08/41] feat!: results, tenancy, crypto-shredding, metrics and principal capture BREAKING CHANGE: the store contract returns results rather than null, bool or provider exceptions. Reads return Result and saves return Result, AggregateSaveFailure>, so "absent" and "deleted" are distinguishable and a save that wrote nothing is a success rather than a failure. SaveResult, LockHandlingMode, ValidationException, IsDeletedAsync and ~36 duplicated provider exceptions are removed; ExistsState becomes AggregateExistence without the implicit bool that flattened "exists in a deleted state" into "exists". Stream versions widen from int to long. Tenant isolation is enforced by every event store, the SQL Server, PostgreSQL, MongoDB and Cosmos DB snapshot stores, and the distributed cache - whose key was previously unqualified, letting one tenant read another's aggregate ahead of every storage filter. Unowned rows are visible only to TenantScope.System, so a missed stamp becomes an absence rather than a leak. Crypto-shredding encrypts the payload of any event implementing IEventDataSubject under a per-subject key; erasing the key makes it unreadable everywhere and replay reports the gap through SkippedEvents. Snapshots are disabled while protection is enabled, because a snapshot holds the same data in clear and cannot be keyed to one subject. Also fixes several defects found along the way: the EF source generator shipped in three provider packages, so referencing two of them failed a consumer build with CS0579; concurrency conflicts escaped as exceptions on some providers and as DbUpdateException on others; Azure Storage's batch FailedEntity was never assigned, making its conflict classification dead code; transactions discarded the save failure; and the admin health endpoint reported a hardcoded "Ready". --- .csharpierignore | 7 + Directory.Packages.props | 45 +- Justfile | 8 +- src/Directory.Build.props | 8 + src/Directory.Build.targets | 4 + src/EventSourcing.slnx | 3 + src/src/Admin.API/Admin.API.csproj | 2 +- src/src/Admin.API/AdminPortalOptions.cs | 20 + src/src/Admin.API/AdminQueryFailureResults.cs | 40 + .../Endpoints/AdminAggregatesEndpoints.cs | 47 +- .../Endpoints/AdminHealthResponse.cs | 2 +- .../Admin.API/Endpoints/AdminHealthStatus.cs | 19 + .../Endpoints/AdminOperationalEndpoints.cs | 70 +- .../Endpoints/AdminSnapshotEndpoints.cs | 35 +- .../Endpoints/AdminTenantScopeFilter.cs | 54 + .../Builder/WebApplicationExtensions.cs | 18 +- .../HostApplicationBuilderExtensions.cs | 7 +- .../Admin.Abstractions.csproj | 4 + .../Failures/AdminAggregateNotFound.cs | 12 + .../Failures/AdminQueryFailure.cs | 13 + .../Failures/AdminTenantFailure.cs | 13 + .../Failures/AdminTenantForbidden.cs | 8 + .../Failures/AdminTenantNotSelected.cs | 8 + .../Services/IAdminAggregateQueryService.cs | 8 +- .../Services/IAdminEventQueryService.cs | 7 +- .../Services/IAdminProjectionService.cs | 12 +- .../Services/IAdminStorageProbe.cs | 19 + .../Services/IAdminTenantResolver.cs | 30 + .../Admin.AzureStorage.csproj | 1 - .../AzureStorageAdminAggregateQueryService.cs | 12 +- .../AzureStorageAdminEventQueryService.cs | 8 +- .../AzureStorageAdminProjectionService.cs | 14 +- .../AzureStorageAdminStorageProbe.cs | 26 + .../HostApplicationBuilderExtensions.cs | 1 + .../Internal/AzureStorageAdminTableHelpers.cs | 10 +- src/src/Admin.Client/Admin.Client.csproj | 1 - .../Generated/AdminApiClient.g.cs | 4 +- .../ServiceCollectionExtensions.cs | 6 + .../Admin.MongoDB/MongoDBAdminStorageProbe.cs | 24 + .../MongoDbAdminAggregateQueryService.cs | 8 +- .../MongoDbAdminEventQueryService.cs | 11 +- .../MongoDbAdminProjectionService.cs | 22 +- src/src/Admin.Postgres/Admin.Postgres.csproj | 1 - .../HostApplicationBuilderExtensions.cs | 1 + .../PostgresAdminAggregateQueryService.cs | 24 +- .../PostgresAdminEventQueryService.cs | 23 +- .../PostgresAdminProjectionService.cs | 28 +- .../PostgresAdminStorageProbe.cs | 24 + .../ServiceCollectionExtensions.cs | 5 +- .../AdminFeatureAuthorizationHandler.cs | 2 +- .../Handlers/AggregateTypeAccessHandler.cs | 2 +- .../Providers/ClaimsAdminTenantResolver.cs | 58 ++ .../ServiceCollectionExtensions.cs | 6 + src/src/Admin.Site/Pages/AdminIndex.cshtml.cs | 2 +- src/src/Admin.Site/Pages/Events.cshtml.cs | 2 +- src/src/Admin.Site/Pages/Projection.cshtml.cs | 2 +- src/src/Admin.Site/Properties/AssemblyInfo.cs | 3 + .../Admin.SqlServer/Admin.SqlServer.csproj | 1 - .../HostApplicationBuilderExtensions.cs | 1 + .../SqlServerAdminAggregateQueryService.cs | 22 +- .../SqlServerAdminEventQueryService.cs | 16 +- .../SqlServerAdminProjectionService.cs | 28 +- .../SqlServerAdminStorageProbe.cs | 24 + src/src/AzureStorage/AggregateVersionData.cs | 4 +- src/src/AzureStorage/AzureStorage.csproj | 4 +- src/src/AzureStorage/Entities/EventEntity.cs | 9 +- src/src/AzureStorage/Entities/IHasTenant.cs | 9 + .../Entities/IdempotencyMarkerEntity.cs | 9 +- .../Entities/IdempotencyMarkerEventPayload.cs | 4 +- .../Entities/StreamVersionEntity.cs | 11 +- .../AggregateAlreadyDeletedException.cs | 24 - .../Exceptions/AggregateDeletedException.cs | 24 - .../Exceptions/AggregateIsDeletedException.cs | 16 - .../Exceptions/AggregateLockedException.cs | 18 - .../AggregateNotDeletedException.cs | 16 - .../AggregateStreamVersionMissingException.cs | 24 - .../AggregatedNotAlreadyDeletedException.cs | 24 - .../Exceptions/CommitException.cs | 50 - .../Exceptions/ConcurrencyException.cs | 37 - .../Exceptions/MissingAggregateIdException.cs | 16 - .../AzureStorage/ITableEventStoreTelemetry.cs | 14 +- .../StorageClients/Table/AzureTableClient.cs | 58 +- .../StorageClients/Table/BatchOperation.cs | 10 + .../TableEventStore.CreateAsync.cs | 8 + .../TableEventStore.DeleteAsync.cs | 33 +- .../TableEventStore.ExceptionHelpers.cs | 12 +- .../TableEventStore.ExistsAsync.cs | 10 +- .../AzureStorage/TableEventStore.GetAsync.cs | 27 +- .../TableEventStore.GetAtAsync.cs | 12 +- .../TableEventStore.GetDeletedAsync.cs | 20 +- .../TableEventStore.GetEventRangeAsync.cs | 37 +- .../TableEventStore.GetOrCreateAsync.cs | 11 +- .../TableEventStore.IsDeletedAsync.cs | 15 - .../TableEventStore.RestoreAsync.cs | 18 +- .../AzureStorage/TableEventStore.SaveAsync.cs | 4 +- .../TableEventStore.SaveOperation.cs | 161 ++- src/src/AzureStorage/TableEventStore.cs | 68 +- src/src/Benchmarks/BenchmarkPolicies.cs | 2 - src/src/Benchmarks/BenchmarkRun.cs | 7 +- src/src/Benchmarks/BenchmarkRunExporter.cs | 23 +- src/src/Benchmarks/Benchmarks.csproj | 2 +- .../InMemoryPerformanceBenchmarks.cs | 14 +- .../SourceGeneratorPerformanceScenarios.cs | 4 +- .../SqlServerPerformanceBenchmarks.cs | 29 +- .../CosmosDbContainerProvisioner.cs} | 183 ++-- .../CosmosDb/Client/CosmosDbSnapshotClient.cs | 266 +++++ src/src/CosmosDb/Client/SnapshotDbContext.cs | 151 +++ src/src/CosmosDb/CosmosDb.csproj | 15 +- .../CosmosDbClient.CosmosDbSpecific.cs | 374 ------- ...DbClient.CosmosSystemTextJsonSerializer.cs | 31 - src/src/CosmosDb/CosmosDbClientOverrides.cs | 23 + src/src/CosmosDb/CosmosDbOptions.cs | 4 + src/src/CosmosDb/CosmosDbUtilities.cs | 151 --- src/src/CosmosDb/ICosmosDbClientExtensions.cs | 307 ------ src/src/CosmosDb/Sdk/README.md | 17 +- .../CosmosDbSnapshotEventStore.EventStore.cs | 41 +- .../CosmosDbSnapshotEventStore.Query.cs | 126 ++- .../Snapshots/CosmosDbSnapshotEventStore.cs | 41 +- .../Conversion}/JsonScalarValueConverter.cs | 48 +- .../JsonValueObjectCollectionConverter.cs | 7 +- .../Conversion}/OpaqueJsonValueConverter.cs | 7 +- .../Conversion/ScalarValueConverter.cs | 54 + .../Conversion/ScalarValueObjects.cs | 69 ++ .../EntityFrameworkCore.csproj | 25 + .../Mapping/ISnapshotGraphBuilder.cs | 129 +++ .../Mapping/SnapshotModelCacheKeyFactory.cs | 36 + .../Mapping/SnapshotModelMapper.cs | 292 ++++++ .../Mapping/SnapshotTypes.cs | 239 +++++ .../Properties/AssemblyInfo.cs | 8 + .../Query/SnapshotPredicateRewriter.cs | 218 ++++ .../AggregateEventHistoryItem.cs | 2 +- src/src/EventSourcing/AggregateExistence.cs | 39 + .../EventSourcing/Aggregates/AggregateBase.cs | 6 +- .../Aggregates/AggregateDetails.cs | 8 +- .../Aggregates/Events/EventMetadata.cs | 2 +- .../EventSourcing/Aggregates/SaveOutcome.cs | 37 + .../EventSourcing/Aggregates/SaveResult.cs | 137 --- .../Aggregates/SkippedEventRecord.cs | 2 +- .../AmbientEventStorePrincipalAccessor.cs | 18 + .../ChangeFeed/AggregateChangeFeedNotifier.cs | 2 +- .../IAggregateChangeFeedNotifier.cs | 2 +- .../IAggregateChangeFeedProcessor.cs | 4 +- src/src/EventSourcing/ConcurrencyRetry.cs | 66 +- .../AesGcmEventPayloadProtector.cs | 99 ++ .../Cryptography/IEventCryptoKeyStore.cs | 40 + .../Cryptography/IEventDataSubject.cs | 23 + .../Cryptography/IEventPayloadProtector.cs | 34 + .../InMemoryEventCryptoKeyStore.cs | 40 + .../Cryptography/ProtectedPayload.cs | 47 + src/src/EventSourcing/DeleteHandlingMode.cs | 18 +- src/src/EventSourcing/EventSourcing.csproj | 24 +- src/src/EventSourcing/EventStoreFacade.cs | 31 +- .../EventStoreMetricsExtensions.cs | 60 ++ .../EventStoreOperationContext.cs | 7 +- .../EventSourcing/EventStoreTransaction.cs | 41 +- .../NullQueryable/NullQueryableEventStore.cs | 31 +- .../Exceptions/CommitException.cs | 99 ++ .../Exceptions/ConcurrencyException.cs | 12 +- .../Exceptions/MissingAggregateIdException.cs | 8 +- .../{ExistsStatus.cs => ExistenceStatus.cs} | 4 +- src/src/EventSourcing/ExistsState.cs | 47 - .../ServiceCollectionExtensions.cs | 21 + .../Failures/AggregateAlreadyDeleted.cs | 8 + .../Failures/AggregateDeleteFailure.cs | 19 + .../Failures/AggregateDeleted.cs | 12 + .../Failures/AggregateInvalid.cs | 9 + .../EventSourcing/Failures/AggregateLocked.cs | 8 + .../Failures/AggregateNotDeleted.cs | 8 + .../Failures/AggregateNotFound.cs | 8 + .../Failures/AggregateReadFailure.cs | 19 + .../Failures/AggregateRestoreFailure.cs | 19 + .../Failures/AggregateSaveFailure.cs | 18 + .../AggregateSaveFailureExtensions.cs | 55 + .../Failures/ConcurrencyConflict.cs | 18 + .../IAggregateEventHistoryStoreCore.cs | 4 +- src/src/EventSourcing/IConcurrencyConflict.cs | 9 +- src/src/EventSourcing/IEventStore.cs | 57 +- src/src/EventSourcing/IEventStoreCore.cs | 72 +- .../IEventStoreCoreExtensions.cs | 738 +------------- .../EventSourcing/IEventStoreExtensions.cs | 949 +---------------- src/src/EventSourcing/IEventStoreMetrics.cs | 49 + .../IEventStorePrincipalAccessor.cs | 23 + .../Internal/TransactionalSaveOperation.cs | 18 +- src/src/EventSourcing/LockHandlingMode.cs | 17 - .../EventSourcing/NoOpEventStoreMetrics.cs | 28 + .../QueryableEventStoreFacade.cs | 32 +- .../Tenancy/AmbientCurrentTenant.cs | 37 + .../EventSourcing/Tenancy/ICurrentTenant.cs | 17 + .../Tenancy/SystemCurrentTenant.cs | 16 + src/src/EventSourcing/Tenancy/TenantScope.cs | 46 + .../TenantScopeNotSupportedException.cs | 59 ++ .../TransactionAggregateResult.cs | 18 +- .../Validation/ValidationException.cs | 57 -- .../Storage/SaveResultBuilder.cs | 23 - .../Events/Exceptions/ConcurrencyException.cs | 37 - .../InMemoryEventStore.ExceptionHelpers.cs | 20 +- src/src/InMemory/Events/InMemoryEventStore.cs | 255 +++-- src/src/InMemory/Sdk/README.md | 6 +- .../EventStoreExtensionsMirrorGenerator.cs | 150 +++ .../MirrorGenerator/MirrorGenerator.csproj | 15 + .../MongoDB/Events/AggregateVersionData.cs | 4 +- .../MongoDB/Events/Entities/EventEntity.cs | 9 +- .../Entities/IdempotencyMarkerEntity.cs | 9 +- .../MongoDB/Events/Entities/SnapshotEntity.cs | 7 +- .../Events/Entities/StreamVersionEntity.cs | 9 +- .../AggregateAlreadyDeletedException.cs | 24 - .../Exceptions/AggregateDeletedException.cs | 24 - .../Exceptions/AggregateIsDeletedException.cs | 16 - .../Exceptions/AggregateLockedException.cs | 18 - .../AggregateNotDeletedException.cs | 16 - .../AggregateStreamVersionMissingException.cs | 24 - .../AggregatedNotAlreadyDeletedException.cs | 24 - .../Events/Exceptions/CommitException.cs | 44 - .../Events/Exceptions/ConcurrencyException.cs | 37 - .../Exceptions/MissingAggregateIdException.cs | 16 - .../Events/IMongoDBEventStoreTelemetry.cs | 12 +- .../Events/MongoDBEventStore.DeleteAsync.cs | 37 +- .../MongoDBEventStore.ExceptionHelpers.cs | 12 +- .../Events/MongoDBEventStore.ExistsAsync.cs | 10 +- .../Events/MongoDBEventStore.GetAsync.cs | 27 +- .../Events/MongoDBEventStore.GetAtAsync.cs | 12 +- .../MongoDBEventStore.GetDeletedAsync.cs | 20 +- .../MongoDBEventStore.GetEventRangeAsync.cs | 29 +- .../MongoDBEventStore.GetOrCreateAsync.cs | 11 +- .../MongoDBEventStore.IsDeletedAsync.cs | 15 - .../Events/MongoDBEventStore.RestoreAsync.cs | 18 +- .../Events/MongoDBEventStore.SaveAsync.cs | 122 ++- src/src/MongoDB/Events/MongoDBEventStore.cs | 64 +- src/src/MongoDB/MongoDB.csproj | 4 +- .../MongoDBSnapshotEventStore.EventStore.cs | 40 +- .../Snapshots/MongoDBSnapshotEventStore.cs | 8 +- src/src/MongoDB/StorageClient/IEntity.cs | 4 +- .../MongoDBClient.MongoDBSpecific.cs | 29 +- .../MongoDB/StorageClient/MongoDBClient.cs | 43 +- .../Client/JsonScalarValueConverter.cs | 114 --- src/src/Postgres/Client/Models.cs | 7 +- src/src/Postgres/Client/PostgresClient.cs | 956 +++--------------- .../Postgres/Client/ScalarValueConverter.cs | 74 -- .../Postgres/Events/AggregateVersionData.cs | 2 +- .../EntityFramework/EventStoreDbContext.cs | 20 +- .../EntityFramework/EventStoreEntity.cs | 5 +- .../AggregateAlreadyDeletedException.cs | 24 - .../Exceptions/AggregateDeletedException.cs | 24 - .../Exceptions/AggregateIsDeletedException.cs | 16 - .../Exceptions/AggregateLockedException.cs | 18 - .../AggregateNotDeletedException.cs | 16 - .../AggregateStreamVersionMissingException.cs | 24 - .../AggregatedNotAlreadyDeletedException.cs | 24 - .../Events/Exceptions/CommitException.cs | 44 - .../Events/Exceptions/ConcurrencyException.cs | 37 - .../Exceptions/MissingAggregateIdException.cs | 16 - .../Events/IPostgresEventStoreTelemetry.cs | 16 +- .../Events/PostgresEventStore.DeleteAsync.cs | 33 +- .../PostgresEventStore.ExceptionHelpers.cs | 12 +- .../Events/PostgresEventStore.ExistsAsync.cs | 8 +- .../Events/PostgresEventStore.GetAsync.cs | 25 +- .../Events/PostgresEventStore.GetAtAsync.cs | 12 +- .../PostgresEventStore.GetDeletedAsync.cs | 18 +- .../PostgresEventStore.GetEventRangeAsync.cs | 28 +- .../PostgresEventStore.GetOrCreateAsync.cs | 9 +- .../PostgresEventStore.IsDeletedAsync.cs | 15 - .../Events/PostgresEventStore.RestoreAsync.cs | 22 +- .../Events/PostgresEventStore.SaveAsync.cs | 105 +- src/src/Postgres/Events/PostgresEventStore.cs | 62 +- .../Events/PostgresEventStoreClient.cs | 54 +- .../Events/PostgresEventStoreTransaction.cs | 4 +- .../Postgres/Outbox/PostgresOutboxStore.cs | 3 + src/src/Postgres/Postgres.csproj | 6 +- .../PostgresJsonIndexSchemaManager.cs | 2 +- src/src/Postgres/Sdk/README.md | 2 +- .../PostgresSnapshotEventStore.EventStore.cs | 44 +- .../Snapshots/PostgresSnapshotEventStore.cs | 7 +- .../InMemoryTransactionalEventStore.cs | 59 +- src/src/Samples.QuickStart/Program.cs | 43 +- .../Samples.QuickStart/ValidatorScenarios.cs | 25 +- .../Infrastructure/EventSourcingPageModel.cs | 40 +- .../Pages/BackOffice/Catalog/Create.cshtml.cs | 3 +- .../BackOffice/Catalog/Deleted.cshtml.cs | 8 +- .../Pages/BackOffice/Catalog/Edit.cshtml.cs | 14 +- .../Pages/BackOffice/Catalog/Index.cshtml.cs | 3 +- .../BackOffice/Customers/Deleted.cshtml.cs | 8 +- .../Pages/BackOffice/Customers/Edit.cshtml.cs | 28 +- .../BackOffice/Customers/Index.cshtml.cs | 3 +- .../Pages/BackOffice/Stock/Create.cshtml.cs | 3 +- .../Pages/BackOffice/Stock/Deleted.cshtml.cs | 8 +- .../Pages/BackOffice/Stock/Edit.cshtml.cs | 28 +- .../Pages/BackOffice/Stock/Transfer.cshtml.cs | 28 +- .../Pages/Customer/Cart/Index.cshtml.cs | 6 +- .../Pages/Customer/Catalog/Index.cshtml.cs | 3 +- .../Pages/Customer/Catalog/Order.cshtml.cs | 40 +- .../Pages/Customer/Orders/Details.cshtml.cs | 31 +- .../Pages/Customer/Orders/Index.cshtml.cs | 3 +- .../Pages/Customer/Profile/Index.cshtml.cs | 23 +- .../Services/ISampleSeedServiceTelemetry.cs | 7 +- .../Samples.Web/Services/SampleSeedService.cs | 35 +- src/src/Samples/Domain/OrderAggregate.cs | 9 +- .../Samples/Services/CartCheckoutService.cs | 12 +- src/src/Samples/Services/ISeedDataService.cs | 6 +- .../Services/OrderFulfilmentService.cs | 28 +- src/src/Samples/Services/SeedDataService.cs | 42 +- .../Samples/Services/StockTransferService.cs | 35 +- src/src/Samples/ValueObjects/EmailAddress.cs | 17 +- .../JsonValueObjectCollectionConverter.cs | 16 - src/src/SqlServer/Client/Models.cs | 7 +- .../Client/OpaqueJsonValueConverter.cs | 17 - .../SqlServer/Client/ScalarValueConverter.cs | 74 -- src/src/SqlServer/Client/SqlServerClient.cs | 884 ++-------------- .../SqlServer/Events/AggregateVersionData.cs | 2 +- .../EntityFramework/EventStoreDbContext.cs | 22 +- .../EntityFramework/EventStoreEntity.cs | 7 +- .../AggregateAlreadyDeletedException.cs | 24 - .../Exceptions/AggregateDeletedException.cs | 24 - .../Exceptions/AggregateIsDeletedException.cs | 16 - .../Exceptions/AggregateLockedException.cs | 18 - .../AggregateNotDeletedException.cs | 16 - .../AggregateStreamVersionMissingException.cs | 24 - .../AggregatedNotAlreadyDeletedException.cs | 24 - .../Events/Exceptions/CommitException.cs | 44 - .../Events/ISqlServerEventStoreTelemetry.cs | 18 +- .../Events/SqlServerEventStore.DeleteAsync.cs | 33 +- .../SqlServerEventStore.ExceptionHelpers.cs | 12 +- .../Events/SqlServerEventStore.ExistsAsync.cs | 10 +- .../Events/SqlServerEventStore.GetAsync.cs | 25 +- .../Events/SqlServerEventStore.GetAtAsync.cs | 12 +- .../SqlServerEventStore.GetDeletedAsync.cs | 20 +- .../SqlServerEventStore.GetEventRangeAsync.cs | 28 +- .../SqlServerEventStore.GetOrCreateAsync.cs | 11 +- .../SqlServerEventStore.IsDeletedAsync.cs | 15 - .../SqlServerEventStore.RestoreAsync.cs | 22 +- .../Events/SqlServerEventStore.SaveAsync.cs | 106 +- .../SqlServer/Events/SqlServerEventStore.cs | 62 +- .../Events/SqlServerEventStoreClient.cs | 54 +- .../Events/SqlServerEventStoreTransaction.cs | 4 +- .../SqlServer/Outbox/SqlServerOutboxStore.cs | 4 +- src/src/SqlServer/Sdk/README.md | 2 +- .../SqlServerSnapshotEventStore.EventStore.cs | 44 +- .../Snapshots/SqlServerSnapshotEventStore.cs | 9 +- src/src/SqlServer/SqlServer.csproj | 6 +- .../SqlServerJsonIndexSchemaManager.cs | 2 +- .../Validation.FluentValidation/Sdk/README.md | 5 +- src/src/Validation.ZodSharp/Sdk/README.md | 5 +- .../Api/AdminApiEndpointTests.cs | 39 +- .../Api/AdminOperationalEndpointsTests.cs | 66 +- .../Api/AdminSnapshotEndpointsTests.cs | 43 +- .../Api/AdminTenantScopeFilterTests.cs | 110 ++ .../ClaimsAdminTenantResolverTests.cs | 67 ++ .../Security/PermissionProviderTests.cs | 2 +- .../AzureTableEventStoreTenancyTests.cs | 72 ++ .../Guards/AzureTableEventStoreGuardTests.cs | 72 +- .../CosmosDbSnapshotEventStoreTests.Paging.cs | 139 +++ ...napshotEventStoreTests.QueryTranslation.cs | 125 +++ ...napshotEventStoreTests.WithStringValues.cs | 99 -- .../CosmosDbSnapshotEventStoreTests.cs | 14 +- .../Snapshots/SnapshotStoreContractTests.cs | 2 +- .../AggregateExistenceTests.cs | 33 + .../AggregateBaseTests.ClearUnsavedEvents.cs | 2 +- .../Aggregates/AggregateBaseTests.cs | 2 +- .../Snapshotting/SnapshotStrategyTests.cs | 4 +- .../Aggregates/Test/TestAggregate.cs | 2 +- .../AesGcmEventPayloadProtectorTests.cs | 109 ++ .../EFOpaqueAttribute.cs | 1 + .../SnapshotModelMapperTests.cs | 320 ++++++ .../EventHistoryExtensionsTests.cs | 37 +- .../EventSourcing.UnitTests.csproj | 3 + .../EventStoreExtensionsMirrorTests.cs | 76 ++ .../EventStoreTransactionTests.cs | 103 +- .../ExistsStateTests.cs | 34 - .../Failures/AggregateFailureTests.cs | 92 ++ .../IEventStoreExtensionsEnlistTests.cs | 11 +- .../InMemoryEventStoreConcurrencyTests.cs | 15 +- .../Events/InMemoryEventStoreMetricsTests.cs | 142 +++ .../InMemoryEventStorePrincipalTests.cs | 104 ++ .../Events/InMemoryEventStoreTenancyTests.cs | 145 +++ .../EntityFrameworkGeneratorPackagingTests.cs | 65 ++ .../Snapshots/PostgresSnapshotClientTests.cs | 115 --- ...eMapperTests.GetName_AggregateEventType.cs | 2 +- ...eEventNameMapperTests.GetName_EventBase.cs | 2 +- .../SqlServerEventStoreTransactionTests.cs | 31 +- .../Snapshots/SqlServerSnapshotClientTests.cs | 277 +---- .../SqlServerSnapshotEventStoreTests.cs | 52 +- .../TypeNameHelperTests.cs | 2 +- .../Events/MongoDBEventStoreTenancyTests.cs | 72 ++ .../Guards/MongoDBEventStoreGuardTests.cs | 38 +- .../Events/PostgresEventStoreTenancyTests.cs | 72 ++ .../Outbox/PostgresOutboxIntegrationTests.cs | 15 +- .../PostgresContainerParallelLimit.cs | 18 + .../PostgresProviderIntegrationTests.cs | 12 +- ...tUploadAggregateSnapshotEventStoreTests.cs | 3 +- .../Services/CartCheckoutServiceTests.cs | 16 +- .../Web/Admin/AdminApiClientTests.cs | 2 +- .../AzureVariantStartupUsageTests.cs | 14 +- .../Web/Pages/AuditPageTests.cs | 4 +- .../Web/Pages/CustomerPageTests.cs | 5 +- .../Web/Pages/InventoryPageTests.cs | 4 +- .../Web/Pages/OrderPageTests.cs | 6 +- .../CustomerAggregateIntegrationTests.cs | 38 +- .../InventoryAggregateIntegrationTests.cs | 24 +- .../Domain/MultiAggregateIntegrationTests.cs | 21 +- .../Domain/OrderAggregateIntegrationTests.cs | 39 +- .../ValueObjects/UserCaptureTests.cs | 5 +- .../Domain/OrderAggregateTests.cs | 7 +- .../Services/OrderFulfilmentServiceTests.cs | 23 +- .../Services/StockTransferServiceTests.cs | 24 +- .../ValueObjects/BlobUriTests.cs | 2 +- .../Aggregates/ComplexNestedTestType.cs | 2 +- .../Aggregates/ComplexTestType.cs | 2 +- .../Aggregates/IAggregateTest.cs | 2 +- .../Persistence/Events/SubjectNameSetEvent.cs | 24 + .../Persistence/PersistenceAggregate.cs | 9 +- .../ContainerHelper.Resources.cs | 9 + .../SharedTestingFramework/ContainerHelper.cs | 150 +-- .../Contracts/EventStoreContractTestsBase.cs | 168 ++- .../Contracts/EventStoreTestSeed.cs | 19 +- .../SnapshotStoreContractTestsBase.cs | 126 +-- .../CosmosDbTestContainer.cs | 66 ++ .../Fixtures/AppServiceHelper.cs | 2 +- .../AzureStorage/TableEventStoreFixture.cs | 24 +- .../CosmosDbSnapshotEventStoreContext.cs | 28 +- .../CosmosDbSnapshotEventStoreFixture.cs | 23 +- .../MongoDB/MongoDBEventStoreFixture.cs | 19 +- .../MongoDBSnapshotEventStoreFixture.cs | 6 +- .../Postgres/PostgresEventStoreFixture.cs | 22 +- .../SqlServer/SqlServerEventStoreFixture.cs | 27 +- .../MongoDBTestContainer.cs | 77 ++ src/tests/SharedTestingFramework/Records.cs | 2 +- .../SharedTestingFramework.csproj | 16 +- .../Common/ManifestTestHelpers.cs | 2 +- .../AggregateSourceGeneratorTests.cs | 104 +- ...SqlServerEventStoreCryptoShreddingTests.cs | 114 +++ .../Events/SqlServerEventStoreTenancyTests.cs | 97 ++ .../SqlServerEventStoreTests.IndexCreation.cs | 4 +- ...erEventStoreTransactionIntegrationTests.cs | 41 +- .../Guards/SqlServerEventStoreGuardTests.cs | 37 +- .../Outbox/SqlServerOutboxIntegrationTests.cs | 15 +- ...tUploadAggregateSnapshotEventStoreTests.cs | 3 +- ...erSnapshotEventStoreTests.IndexCreation.cs | 2 +- ...erSnapshotQueryTranslationBoundaryTests.cs | 6 + ...rverSnapshotValueObjectPersistenceTests.cs | 2 +- src/tools/AdminAPI.OpenAPI/Program.cs | 11 +- 439 files changed, 9645 insertions(+), 8413 deletions(-) create mode 100644 .csharpierignore create mode 100644 src/src/Admin.API/AdminQueryFailureResults.cs create mode 100644 src/src/Admin.API/Endpoints/AdminHealthStatus.cs create mode 100644 src/src/Admin.API/Endpoints/AdminTenantScopeFilter.cs create mode 100644 src/src/Admin.Abstractions/Failures/AdminAggregateNotFound.cs create mode 100644 src/src/Admin.Abstractions/Failures/AdminQueryFailure.cs create mode 100644 src/src/Admin.Abstractions/Failures/AdminTenantFailure.cs create mode 100644 src/src/Admin.Abstractions/Failures/AdminTenantForbidden.cs create mode 100644 src/src/Admin.Abstractions/Failures/AdminTenantNotSelected.cs create mode 100644 src/src/Admin.Abstractions/Services/IAdminStorageProbe.cs create mode 100644 src/src/Admin.Abstractions/Services/IAdminTenantResolver.cs create mode 100644 src/src/Admin.AzureStorage/AzureStorageAdminStorageProbe.cs create mode 100644 src/src/Admin.MongoDB/MongoDBAdminStorageProbe.cs create mode 100644 src/src/Admin.Postgres/PostgresAdminStorageProbe.cs create mode 100644 src/src/Admin.Security/Providers/ClaimsAdminTenantResolver.cs create mode 100644 src/src/Admin.SqlServer/SqlServerAdminStorageProbe.cs create mode 100644 src/src/AzureStorage/Entities/IHasTenant.cs delete mode 100644 src/src/AzureStorage/Exceptions/AggregateAlreadyDeletedException.cs delete mode 100644 src/src/AzureStorage/Exceptions/AggregateDeletedException.cs delete mode 100644 src/src/AzureStorage/Exceptions/AggregateIsDeletedException.cs delete mode 100644 src/src/AzureStorage/Exceptions/AggregateLockedException.cs delete mode 100644 src/src/AzureStorage/Exceptions/AggregateNotDeletedException.cs delete mode 100644 src/src/AzureStorage/Exceptions/AggregateStreamVersionMissingException.cs delete mode 100644 src/src/AzureStorage/Exceptions/AggregatedNotAlreadyDeletedException.cs delete mode 100644 src/src/AzureStorage/Exceptions/CommitException.cs delete mode 100644 src/src/AzureStorage/Exceptions/ConcurrencyException.cs delete mode 100644 src/src/AzureStorage/Exceptions/MissingAggregateIdException.cs delete mode 100644 src/src/AzureStorage/TableEventStore.IsDeletedAsync.cs rename src/src/CosmosDb/{CosmosDbClient.cs => Client/CosmosDbContainerProvisioner.cs} (78%) create mode 100644 src/src/CosmosDb/Client/CosmosDbSnapshotClient.cs create mode 100644 src/src/CosmosDb/Client/SnapshotDbContext.cs delete mode 100644 src/src/CosmosDb/CosmosDbClient.CosmosDbSpecific.cs delete mode 100644 src/src/CosmosDb/CosmosDbClient.CosmosSystemTextJsonSerializer.cs create mode 100644 src/src/CosmosDb/CosmosDbClientOverrides.cs delete mode 100644 src/src/CosmosDb/CosmosDbUtilities.cs delete mode 100644 src/src/CosmosDb/ICosmosDbClientExtensions.cs rename src/src/{SqlServer/Client => EntityFrameworkCore/Conversion}/JsonScalarValueConverter.cs (57%) rename src/src/{Postgres/Client => EntityFrameworkCore/Conversion}/JsonValueObjectCollectionConverter.cs (66%) rename src/src/{Postgres/Client => EntityFrameworkCore/Conversion}/OpaqueJsonValueConverter.cs (72%) create mode 100644 src/src/EntityFrameworkCore/Conversion/ScalarValueConverter.cs create mode 100644 src/src/EntityFrameworkCore/Conversion/ScalarValueObjects.cs create mode 100644 src/src/EntityFrameworkCore/EntityFrameworkCore.csproj create mode 100644 src/src/EntityFrameworkCore/Mapping/ISnapshotGraphBuilder.cs create mode 100644 src/src/EntityFrameworkCore/Mapping/SnapshotModelCacheKeyFactory.cs create mode 100644 src/src/EntityFrameworkCore/Mapping/SnapshotModelMapper.cs create mode 100644 src/src/EntityFrameworkCore/Mapping/SnapshotTypes.cs create mode 100644 src/src/EntityFrameworkCore/Properties/AssemblyInfo.cs create mode 100644 src/src/EntityFrameworkCore/Query/SnapshotPredicateRewriter.cs create mode 100644 src/src/EventSourcing/AggregateExistence.cs create mode 100644 src/src/EventSourcing/Aggregates/SaveOutcome.cs delete mode 100644 src/src/EventSourcing/Aggregates/SaveResult.cs create mode 100644 src/src/EventSourcing/AmbientEventStorePrincipalAccessor.cs create mode 100644 src/src/EventSourcing/Cryptography/AesGcmEventPayloadProtector.cs create mode 100644 src/src/EventSourcing/Cryptography/IEventCryptoKeyStore.cs create mode 100644 src/src/EventSourcing/Cryptography/IEventDataSubject.cs create mode 100644 src/src/EventSourcing/Cryptography/IEventPayloadProtector.cs create mode 100644 src/src/EventSourcing/Cryptography/InMemoryEventCryptoKeyStore.cs create mode 100644 src/src/EventSourcing/Cryptography/ProtectedPayload.cs create mode 100644 src/src/EventSourcing/EventStoreMetricsExtensions.cs create mode 100644 src/src/EventSourcing/Exceptions/CommitException.cs rename src/src/{SqlServer/Events => EventSourcing}/Exceptions/ConcurrencyException.cs (77%) rename src/src/{SqlServer/Events => EventSourcing}/Exceptions/MissingAggregateIdException.cs (52%) rename src/src/EventSourcing/{ExistsStatus.cs => ExistenceStatus.cs} (86%) delete mode 100644 src/src/EventSourcing/ExistsState.cs create mode 100644 src/src/EventSourcing/Failures/AggregateAlreadyDeleted.cs create mode 100644 src/src/EventSourcing/Failures/AggregateDeleteFailure.cs create mode 100644 src/src/EventSourcing/Failures/AggregateDeleted.cs create mode 100644 src/src/EventSourcing/Failures/AggregateInvalid.cs create mode 100644 src/src/EventSourcing/Failures/AggregateLocked.cs create mode 100644 src/src/EventSourcing/Failures/AggregateNotDeleted.cs create mode 100644 src/src/EventSourcing/Failures/AggregateNotFound.cs create mode 100644 src/src/EventSourcing/Failures/AggregateReadFailure.cs create mode 100644 src/src/EventSourcing/Failures/AggregateRestoreFailure.cs create mode 100644 src/src/EventSourcing/Failures/AggregateSaveFailure.cs create mode 100644 src/src/EventSourcing/Failures/AggregateSaveFailureExtensions.cs create mode 100644 src/src/EventSourcing/Failures/ConcurrencyConflict.cs create mode 100644 src/src/EventSourcing/IEventStoreMetrics.cs create mode 100644 src/src/EventSourcing/IEventStorePrincipalAccessor.cs delete mode 100644 src/src/EventSourcing/LockHandlingMode.cs create mode 100644 src/src/EventSourcing/NoOpEventStoreMetrics.cs create mode 100644 src/src/EventSourcing/Tenancy/AmbientCurrentTenant.cs create mode 100644 src/src/EventSourcing/Tenancy/ICurrentTenant.cs create mode 100644 src/src/EventSourcing/Tenancy/SystemCurrentTenant.cs create mode 100644 src/src/EventSourcing/Tenancy/TenantScope.cs create mode 100644 src/src/EventSourcing/Tenancy/TenantScopeNotSupportedException.cs delete mode 100644 src/src/EventSourcing/Validation/ValidationException.cs delete mode 100644 src/src/ImplementationShared/Storage/SaveResultBuilder.cs delete mode 100644 src/src/InMemory/Events/Exceptions/ConcurrencyException.cs create mode 100644 src/src/MirrorGenerator/EventStoreExtensionsMirrorGenerator.cs create mode 100644 src/src/MirrorGenerator/MirrorGenerator.csproj delete mode 100644 src/src/MongoDB/Events/Exceptions/AggregateAlreadyDeletedException.cs delete mode 100644 src/src/MongoDB/Events/Exceptions/AggregateDeletedException.cs delete mode 100644 src/src/MongoDB/Events/Exceptions/AggregateIsDeletedException.cs delete mode 100644 src/src/MongoDB/Events/Exceptions/AggregateLockedException.cs delete mode 100644 src/src/MongoDB/Events/Exceptions/AggregateNotDeletedException.cs delete mode 100644 src/src/MongoDB/Events/Exceptions/AggregateStreamVersionMissingException.cs delete mode 100644 src/src/MongoDB/Events/Exceptions/AggregatedNotAlreadyDeletedException.cs delete mode 100644 src/src/MongoDB/Events/Exceptions/CommitException.cs delete mode 100644 src/src/MongoDB/Events/Exceptions/ConcurrencyException.cs delete mode 100644 src/src/MongoDB/Events/Exceptions/MissingAggregateIdException.cs delete mode 100644 src/src/MongoDB/Events/MongoDBEventStore.IsDeletedAsync.cs delete mode 100644 src/src/Postgres/Client/JsonScalarValueConverter.cs delete mode 100644 src/src/Postgres/Client/ScalarValueConverter.cs delete mode 100644 src/src/Postgres/Events/Exceptions/AggregateAlreadyDeletedException.cs delete mode 100644 src/src/Postgres/Events/Exceptions/AggregateDeletedException.cs delete mode 100644 src/src/Postgres/Events/Exceptions/AggregateIsDeletedException.cs delete mode 100644 src/src/Postgres/Events/Exceptions/AggregateLockedException.cs delete mode 100644 src/src/Postgres/Events/Exceptions/AggregateNotDeletedException.cs delete mode 100644 src/src/Postgres/Events/Exceptions/AggregateStreamVersionMissingException.cs delete mode 100644 src/src/Postgres/Events/Exceptions/AggregatedNotAlreadyDeletedException.cs delete mode 100644 src/src/Postgres/Events/Exceptions/CommitException.cs delete mode 100644 src/src/Postgres/Events/Exceptions/ConcurrencyException.cs delete mode 100644 src/src/Postgres/Events/Exceptions/MissingAggregateIdException.cs delete mode 100644 src/src/Postgres/Events/PostgresEventStore.IsDeletedAsync.cs delete mode 100644 src/src/SqlServer/Client/JsonValueObjectCollectionConverter.cs delete mode 100644 src/src/SqlServer/Client/OpaqueJsonValueConverter.cs delete mode 100644 src/src/SqlServer/Client/ScalarValueConverter.cs delete mode 100644 src/src/SqlServer/Events/Exceptions/AggregateAlreadyDeletedException.cs delete mode 100644 src/src/SqlServer/Events/Exceptions/AggregateDeletedException.cs delete mode 100644 src/src/SqlServer/Events/Exceptions/AggregateIsDeletedException.cs delete mode 100644 src/src/SqlServer/Events/Exceptions/AggregateLockedException.cs delete mode 100644 src/src/SqlServer/Events/Exceptions/AggregateNotDeletedException.cs delete mode 100644 src/src/SqlServer/Events/Exceptions/AggregateStreamVersionMissingException.cs delete mode 100644 src/src/SqlServer/Events/Exceptions/AggregatedNotAlreadyDeletedException.cs delete mode 100644 src/src/SqlServer/Events/Exceptions/CommitException.cs delete mode 100644 src/src/SqlServer/Events/SqlServerEventStore.IsDeletedAsync.cs create mode 100644 src/tests/Admin.UnitTests/Api/AdminTenantScopeFilterTests.cs create mode 100644 src/tests/Admin.UnitTests/Security/ClaimsAdminTenantResolverTests.cs create mode 100644 src/tests/AzureStorage.IntegrationTests/Events/AzureTableEventStoreTenancyTests.cs create mode 100644 src/tests/CosmosDb.IntegrationTests/Snapshots/CosmosDbSnapshotEventStoreTests.Paging.cs create mode 100644 src/tests/CosmosDb.IntegrationTests/Snapshots/CosmosDbSnapshotEventStoreTests.QueryTranslation.cs delete mode 100644 src/tests/CosmosDb.IntegrationTests/Snapshots/CosmosDbSnapshotEventStoreTests.WithStringValues.cs create mode 100644 src/tests/EventSourcing.UnitTests/AggregateExistenceTests.cs create mode 100644 src/tests/EventSourcing.UnitTests/Cryptography/AesGcmEventPayloadProtectorTests.cs create mode 100644 src/tests/EventSourcing.UnitTests/EntityFrameworkCore/SnapshotModelMapperTests.cs create mode 100644 src/tests/EventSourcing.UnitTests/EventStoreExtensionsMirrorTests.cs delete mode 100644 src/tests/EventSourcing.UnitTests/ExistsStateTests.cs create mode 100644 src/tests/EventSourcing.UnitTests/Failures/AggregateFailureTests.cs create mode 100644 src/tests/EventSourcing.UnitTests/InMemory/Events/InMemoryEventStoreMetricsTests.cs create mode 100644 src/tests/EventSourcing.UnitTests/InMemory/Events/InMemoryEventStorePrincipalTests.cs create mode 100644 src/tests/EventSourcing.UnitTests/InMemory/Events/InMemoryEventStoreTenancyTests.cs create mode 100644 src/tests/EventSourcing.UnitTests/Packaging/EntityFrameworkGeneratorPackagingTests.cs delete mode 100644 src/tests/EventSourcing.UnitTests/Postgres/Snapshots/PostgresSnapshotClientTests.cs create mode 100644 src/tests/MongoDB.IntegrationTests/Events/MongoDBEventStoreTenancyTests.cs create mode 100644 src/tests/Postgres.IntegrationTests/Events/PostgresEventStoreTenancyTests.cs create mode 100644 src/tests/Postgres.IntegrationTests/PostgresContainerParallelLimit.cs create mode 100644 src/tests/SharedTestingFramework/Aggregates/Persistence/Events/SubjectNameSetEvent.cs create mode 100644 src/tests/SharedTestingFramework/CosmosDbTestContainer.cs create mode 100644 src/tests/SharedTestingFramework/MongoDBTestContainer.cs create mode 100644 src/tests/SqlServer.IntegrationTests/Events/SqlServerEventStoreCryptoShreddingTests.cs create mode 100644 src/tests/SqlServer.IntegrationTests/Events/SqlServerEventStoreTenancyTests.cs diff --git a/.csharpierignore b/.csharpierignore new file mode 100644 index 00000000..e684caba --- /dev/null +++ b/.csharpierignore @@ -0,0 +1,7 @@ +# CSharpier 1.3.0 - the latest release - cannot parse C# 15 union declarations and reports +# "Was not formatted due to syntax errors" for any file containing one. The compiler accepts them; +# only the formatter lags. Union declarations are therefore kept in dedicated files, excluded here, +# and this entry is removed once CSharpier supports the syntax. +# +# See docs/wiki/Result-And-Failure-Model.md. +**/Failures/*Failure.cs diff --git a/Directory.Packages.props b/Directory.Packages.props index f0d80b86..3951f10b 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -1,22 +1,25 @@ - - - + + + - + 5.9.0 5.9.0 1.76.0 1.2.0 - 1.2.0 - 2.4.0 + 1.2.1 + 2.4.1 + 1.0.3 5.0.5 1.0.2 13.6.0-preview.2 - 4.16.0 + + 1.0.0-prerelease.8 0.14.0 - 10.0.13 + + 11.0.0-rc.2.26504.105 13.6.3 1.20.1 10.11.0 @@ -35,40 +38,32 @@ - - - + + - + - - - - - - - - + + + + @@ -83,8 +78,10 @@ + - + + diff --git a/Justfile b/Justfile index 86933100..30a372eb 100644 --- a/Justfile +++ b/Justfile @@ -139,7 +139,7 @@ perf-runtime *args: perf-inmemory *args: dotnet run --project {{ benchmarks_project }} --configuration Release -- inmemory {{ args }} -# Run SQL Server event/snapshot performance harness (pass --benchmark for larger runs; requires Docker/Testcontainers) +# Run SQL Server event/snapshot performance harness (pass --benchmark for larger runs; requires a container runtime - WSL Containers or Docker) [group('Performance Tests')] perf-sql-server *args: dotnet run --project {{ benchmarks_project }} --configuration Release -- sql-server {{ args }} @@ -155,6 +155,12 @@ test filter="/*/*/*/*" *args: test-unit *args: just test "/*/*/*/*[Category=Unit]" {{ args }} +# Run the provider integration suites one module at a time, which WSL Containers requires: a session +# holds an exclusive lock on its image store, so parallel test modules fail to reach it. +[group('Build and Test')] +test-integration filter="/*/*/*/*" *args: + just test "{{ filter }}" --max-parallel-test-modules 1 {{ args }} + # Pack all packable projects [group('Build and Test')] pack artifact_folder=artifacts_folder *args: diff --git a/src/Directory.Build.props b/src/Directory.Build.props index f09c88d8..283c55cf 100644 --- a/src/Directory.Build.props +++ b/src/Directory.Build.props @@ -1,10 +1,18 @@ Purview.EventSourcing + + net11.0 + + + preview + + $(TargetsForTfmSpecificBuildOutput);CopyProjectReferencesToPackage diff --git a/src/Directory.Build.targets b/src/Directory.Build.targets index 86aef8d5..d0fd211d 100644 --- a/src/Directory.Build.targets +++ b/src/Directory.Build.targets @@ -20,6 +20,10 @@ <_ReferenceCopyLocalPaths Include="@(ReferenceCopyLocalPaths->WithMetadataValue('ReferenceSourceTarget', 'ProjectReference')->WithMetadataValue('PrivateAssets', 'All'))" /> + + <_ReferenceCopyLocalPaths Remove="@(_ReferenceCopyLocalPaths->WithMetadataValue('Pack', 'false'))" /> diff --git a/src/EventSourcing.slnx b/src/EventSourcing.slnx index 2366e85d..889e2ffe 100644 --- a/src/EventSourcing.slnx +++ b/src/EventSourcing.slnx @@ -10,9 +10,11 @@ + + @@ -56,6 +58,7 @@ + diff --git a/src/src/Admin.API/Admin.API.csproj b/src/src/Admin.API/Admin.API.csproj index fb48c3db..7ea12f59 100644 --- a/src/src/Admin.API/Admin.API.csproj +++ b/src/src/Admin.API/Admin.API.csproj @@ -1,4 +1,4 @@ - + true Purview Event Sourcing Admin Portal API diff --git a/src/src/Admin.API/AdminPortalOptions.cs b/src/src/Admin.API/AdminPortalOptions.cs index 8ea7f48d..c6db9814 100644 --- a/src/src/Admin.API/AdminPortalOptions.cs +++ b/src/src/Admin.API/AdminPortalOptions.cs @@ -45,6 +45,26 @@ public sealed class AdminPortalOptions /// [Required] public AdminProjectionOptions Projections { get; set; } = new(); + + /// + /// Gets or sets whether every admin request must resolve to a single tenant. + /// + /// + /// Off by default, so a single-tenant deployment is unaffected. When on, an + /// decides the tenant from the caller's entitlements and + /// the tenant named on the request; a request that resolves to none is refused rather than served + /// across every tenant. + /// + public bool EnforceTenantScope { get; set; } + + /// + /// Gets or sets the request header naming the tenant to act for. + /// + /// + /// Only meaningful to a caller entitled to more than one tenant; naming a tenant the caller does not + /// hold is refused. + /// + public string TenantHeaderName { get; set; } = "Purview-Tenant"; } /// diff --git a/src/src/Admin.API/AdminQueryFailureResults.cs b/src/src/Admin.API/AdminQueryFailureResults.cs new file mode 100644 index 00000000..5e07d0fe --- /dev/null +++ b/src/src/Admin.API/AdminQueryFailureResults.cs @@ -0,0 +1,40 @@ +using Microsoft.AspNetCore.Http; +using Purview.EventSourcing.Admin.Failures; +using Purview.Results; + +namespace Purview.EventSourcing.Admin.API; + +/// +/// Maps an onto its HTTP response. +/// +/// +/// The whole table lives here, so no endpoint decides a status code and a new case has exactly one place to be +/// added. Purview.Results.AspNetCore would own this, but the published version's mapper is not part of +/// its public surface; adopt it once a release exposes ToHttpResult. +/// +static class AdminQueryFailureResults +{ + /// + /// Returns the successful value, or the response for the failure case. + /// + /// The value the query produces. + /// The query result. + /// An carrying the value or the mapped failure. + public static IResult ToHttpResult(this Result result) => + result.IsSuccess ? TypedResults.Ok(result.Value) : ToHttpResult(result.Error); + + /// + /// Returns the response for a failure case. + /// + /// The failure to map. + /// The mapped . + public static IResult ToHttpResult(this AdminQueryFailure failure) => + failure switch + { + AdminAggregateNotFound => TypedResults.NotFound(), + _ => TypedResults.Problem( + statusCode: StatusCodes.Status500InternalServerError, + title: "The query failed with an error that is not mapped to a response." + ), + }; +} diff --git a/src/src/Admin.API/Endpoints/AdminAggregatesEndpoints.cs b/src/src/Admin.API/Endpoints/AdminAggregatesEndpoints.cs index d831d589..53aa9397 100644 --- a/src/src/Admin.API/Endpoints/AdminAggregatesEndpoints.cs +++ b/src/src/Admin.API/Endpoints/AdminAggregatesEndpoints.cs @@ -8,12 +8,12 @@ using Microsoft.AspNetCore.Routing; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Options; -using Purview.EventSourcing.Admin.Models; -using Purview.EventSourcing.Admin.Queries; -using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.API.Contracts; using Purview.EventSourcing.Admin.API.Filters; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Queries; using Purview.EventSourcing.Admin.Security; +using Purview.EventSourcing.Admin.Services; using ZodSharp.Core; namespace Purview.EventSourcing.Admin.API.Endpoints; @@ -215,10 +215,11 @@ CancellationToken cancellationToken return TypedResults.Ok(result); } - static async Task, NotFound, ValidationProblem>> GetAggregateAsync( + static async Task GetAggregateAsync( string aggregateType, string aggregateId, IAdminAggregateQueryService queryService, + HttpContext httpContext, CancellationToken cancellationToken ) { @@ -227,10 +228,11 @@ CancellationToken cancellationToken return routeValidation; var result = await queryService.GetAsync(aggregateType, aggregateId, cancellationToken); - return result is null ? TypedResults.NotFound() : TypedResults.Ok(result); + + return result.ToHttpResult(); } - static async Task>, NotFound, ValidationProblem>> GetEventRangeAsync( + static async Task GetEventRangeAsync( string aggregateType, string aggregateId, [AsParameters] EventRangeRequest request, @@ -256,8 +258,8 @@ CancellationToken cancellationToken ); var result = await queryService.GetRangeAsync(aggregateType, aggregateId, query, cancellationToken); - if (result is null) - return TypedResults.NotFound(); + if (result.IsFailure) + return result.ToHttpResult(); var payloadAuthorization = await authorizationService.AuthorizeAsync( httpContext.User, @@ -265,20 +267,22 @@ CancellationToken cancellationToken AdminPortalPolicies.ViewEventPayloads ); if (payloadAuthorization.Succeeded) - return TypedResults.Ok(result); + return TypedResults.Ok(result.Value); - var redacted = result with + var redacted = result.Value with { - Items = result.Items.Select(envelope => envelope with { Payload = null }).ToArray(), + Items = result.Value.Items.Select(envelope => envelope with { Payload = null }).ToArray(), }; + return TypedResults.Ok(redacted); } - static async Task, NotFound, ValidationProblem>> GetProjectionAtVersionAsync( + static async Task GetProjectionAtVersionAsync( string aggregateType, string aggregateId, [FromQuery] long? version, IAdminProjectionService projectionService, + HttpContext httpContext, CancellationToken cancellationToken ) { @@ -298,14 +302,15 @@ CancellationToken cancellationToken cancellationToken ); - return result is null ? TypedResults.NotFound() : TypedResults.Ok(result); + return result.ToHttpResult(); } - static async Task, NotFound, ValidationProblem>> GetProjectionAtTimeAsync( + static async Task GetProjectionAtTimeAsync( string aggregateType, string aggregateId, [FromQuery] DateTimeOffset? asOfUtc, IAdminProjectionService projectionService, + HttpContext httpContext, CancellationToken cancellationToken ) { @@ -334,10 +339,10 @@ CancellationToken cancellationToken cancellationToken ); - return result is null ? TypedResults.NotFound() : TypedResults.Ok(result); + return result.ToHttpResult(); } - static async Task> ExportEventsAsync( + static async Task ExportEventsAsync( string aggregateType, string aggregateId, [AsParameters] EventRangeRequest request, @@ -363,8 +368,8 @@ CancellationToken cancellationToken cancellationToken ); - if (firstPage is null) - return TypedResults.NotFound(); + if (firstPage.IsFailure) + return firstPage.Error.ToHttpResult(); MemoryStream stream = new(); await using ( @@ -376,7 +381,7 @@ CancellationToken cancellationToken ) ) { - var current = firstPage; + var current = firstPage.Value; while (true) { foreach (var envelope in current.Items) @@ -405,10 +410,10 @@ await writer.WriteLineAsync( BuildExportQuery(request, page, batchSize), cancellationToken ); - if (next is null) + if (next.IsFailure) break; - current = next; + current = next.Value; } await writer.FlushAsync(cancellationToken); diff --git a/src/src/Admin.API/Endpoints/AdminHealthResponse.cs b/src/src/Admin.API/Endpoints/AdminHealthResponse.cs index dddadee2..db79c659 100644 --- a/src/src/Admin.API/Endpoints/AdminHealthResponse.cs +++ b/src/src/Admin.API/Endpoints/AdminHealthResponse.cs @@ -3,7 +3,7 @@ namespace Purview.EventSourcing.Admin.API.Endpoints; /// /// The operational health summary returned by the Admin portal. /// -/// Always Ready when the endpoint responds. +/// One of : whether storage responded to the probe, or Unknown when no probe is registered. /// The UTC time the summary was produced. /// The merged transaction guarantee. /// Whether event streams are persisted. diff --git a/src/src/Admin.API/Endpoints/AdminHealthStatus.cs b/src/src/Admin.API/Endpoints/AdminHealthStatus.cs new file mode 100644 index 00000000..0573c71f --- /dev/null +++ b/src/src/Admin.API/Endpoints/AdminHealthStatus.cs @@ -0,0 +1,19 @@ +namespace Purview.EventSourcing.Admin.API.Endpoints; + +/// +/// The values reported by . +/// +public static class AdminHealthStatus +{ + /// Storage responded to the probe. + public const string Healthy = "Healthy"; + + /// Storage did not respond, or the probe failed. + public const string Unhealthy = "Unhealthy"; + + /// + /// No is registered, so storage was not probed. The + /// response still describes the capability contract. + /// + public const string Unknown = "Unknown"; +} diff --git a/src/src/Admin.API/Endpoints/AdminOperationalEndpoints.cs b/src/src/Admin.API/Endpoints/AdminOperationalEndpoints.cs index 05835a22..d828e46b 100644 --- a/src/src/Admin.API/Endpoints/AdminOperationalEndpoints.cs +++ b/src/src/Admin.API/Endpoints/AdminOperationalEndpoints.cs @@ -1,12 +1,14 @@ using Microsoft.AspNetCore.Builder; using Microsoft.AspNetCore.Http; using Microsoft.AspNetCore.Http.HttpResults; +using Microsoft.AspNetCore.Mvc; using Microsoft.AspNetCore.Routing; using Microsoft.Extensions.DependencyInjection; -using Purview.EventSourcing.Admin.Queries; -using Purview.EventSourcing.Admin.Services; +using Microsoft.Extensions.Logging; using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Queries; using Purview.EventSourcing.Admin.Security; +using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Manifest; using Purview.EventSourcing.Outbox; using Purview.EventSourcing.Services; @@ -44,8 +46,9 @@ public static RouteHandlerBuilder MapCapabilities( /// /// Maps the GET /health endpoint that reports operational readiness for the Admin portal. - /// Readiness reflects whether the event-store capability contract can be resolved; it does not - /// probe live storage. + /// Readiness probes the configured storage when the provider registers an + /// ; without one the status is Unknown and the response + /// describes only the capability contract. /// /// The route group to map the endpoint onto. /// The host authorization policy required by the endpoint. @@ -58,7 +61,9 @@ public static RouteHandlerBuilder MapHealth( .MapGet("/health", GetHealthAsync) .WithName("GetAdminHealth") .WithSummary("Get Admin portal health") - .WithDescription("Reports whether the Admin portal can resolve the event-store capability contract.") + .WithDescription( + "Reports whether the configured storage is reachable, and the event-store capability contract." + ) .WithTags(AdminPortalTag) .Produces() .RequireAuthorization(policyName); @@ -93,10 +98,15 @@ static async Task> GetHealthAsync( IEventStoreCapabilitiesProvider capabilitiesProvider, IAdminAuditLogger auditLogger, HttpContext httpContext, - CancellationToken cancellationToken + CancellationToken cancellationToken, + // Explicitly from services: a GET endpoint otherwise infers an unannotated complex parameter + // as a request body, which minimal APIs reject. + [FromServices] IAdminStorageProbe? storageProbe = null, + [FromServices] ILogger? logger = null ) { var capabilities = capabilitiesProvider.GetCapabilities(); + var status = await ProbeStorageAsync(storageProbe, logger, cancellationToken); await auditLogger.LogAsync( new AdminAuditEntry( @@ -113,7 +123,7 @@ await auditLogger.LogAsync( return TypedResults.Ok( new AdminHealthResponse( - Status: "Ready", + Status: status, TimestampUtc: DateTimeOffset.UtcNow, TransactionGuarantee: capabilities.TransactionGuarantee, SupportsEventStreams: capabilities.SupportsEventStreams, @@ -124,6 +134,42 @@ await auditLogger.LogAsync( ); } + /// + /// Resolves the reported health status, probing storage when the registered provider supports it. + /// + /// + /// The failure is logged rather than returned: a storage error can carry endpoint or credential + /// detail, and this endpoint answers an unauthenticated-adjacent monitoring caller. + /// + static async Task ProbeStorageAsync( + IAdminStorageProbe? storageProbe, + ILogger? logger, + CancellationToken cancellationToken + ) + { + if (storageProbe is null) + return AdminHealthStatus.Unknown; + + try + { + return await storageProbe.IsReachableAsync(cancellationToken) + ? AdminHealthStatus.Healthy + : AdminHealthStatus.Unhealthy; + } + catch (OperationCanceledException) + { + throw; + } +#pragma warning disable CA1031 + catch (Exception ex) +#pragma warning restore CA1031 + { + logger?.LogError(ex, "The Admin portal storage probe failed."); + + return AdminHealthStatus.Unhealthy; + } + } + /// /// Maps the GET /outbox/poisoned endpoint that lists poisoned (dead-letter) transactional /// outbox messages. @@ -246,7 +292,7 @@ public static RouteHandlerBuilder MapUnknownEvents( .RequireAuthorization(policyName); } - static async Task, NotFound>> GetUnknownEventsAsync( + static async Task GetUnknownEventsAsync( string aggregateType, string aggregateId, IAdminEventQueryService queryService, @@ -283,10 +329,10 @@ CancellationToken cancellationToken Sort: "Version asc" ); var result = await queryService.GetRangeAsync(aggregateType, aggregateId, query, cancellationToken); - if (result is null) - return TypedResults.NotFound(); + if (result.IsFailure) + return result.Error.ToHttpResult(); - foreach (var envelope in result.Items) + foreach (var envelope in result.Value.Items) { totalEvents++; var eventType = envelope.Metadata.EventType; @@ -297,7 +343,7 @@ CancellationToken cancellationToken unknown.Add(eventType); } - if (!result.HasNextPage) + if (!result.Value.HasNextPage) break; page++; diff --git a/src/src/Admin.API/Endpoints/AdminSnapshotEndpoints.cs b/src/src/Admin.API/Endpoints/AdminSnapshotEndpoints.cs index a616115a..26eb27b5 100644 --- a/src/src/Admin.API/Endpoints/AdminSnapshotEndpoints.cs +++ b/src/src/Admin.API/Endpoints/AdminSnapshotEndpoints.cs @@ -1,16 +1,16 @@ +using System.Linq.Expressions; +using System.Reflection; using Microsoft.AspNetCore.Builder; using Microsoft.AspNetCore.Http; using Microsoft.AspNetCore.Http.HttpResults; using Microsoft.AspNetCore.Routing; using Microsoft.Extensions.DependencyInjection; using Purview.EventSourcing.Admin.Models; -using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.Security; +using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Snapshotting; using Purview.EventSourcing.Services; -using System.Linq.Expressions; -using System.Reflection; namespace Purview.EventSourcing.Admin.API.Endpoints; @@ -151,11 +151,8 @@ eventStore is null // Load from the canonical event stream, then persist a fresh snapshot through the queryable store. var getAsync = GenericInterfaceMethod(typeof(IEventStore), "GetAsync", parameterCount: 3); - var aggregate = await InvokeGenericAsync( - getAsync, - aggregateTypeSymbol, - eventStore, - [aggregateId, null, cancellationToken] + var aggregate = UnwrapResultValue( + await InvokeGenericAsync(getAsync, aggregateTypeSymbol, eventStore, [aggregateId, null, cancellationToken]) ); if (aggregate is null) return TypedResults.NotFound(); @@ -167,8 +164,8 @@ eventStore is null queryableStore, [aggregate, null, cancellationToken] ); - var rebuilt = - saveResult is not null && (bool)(saveResult.GetType().GetProperty("Saved")?.GetValue(saveResult) ?? false); + var outcome = UnwrapResultValue(saveResult); + var rebuilt = outcome?.GetType().GetProperty("Written")?.GetValue(outcome) is true; var currentVersion = aggregate is IAggregate value ? value.Details.CurrentVersion : 0; await auditLogger.LogAsync( @@ -204,6 +201,20 @@ static MethodInfo GenericInterfaceMethod(Type interfaceType, string name, int pa return task.GetType().GetProperty("Result")?.GetValue(task); } + // GetAsync returns Result, so reflection sees the boxed result rather than + // the aggregate. A failure unwraps to null, which the caller already treats as "not found". + static object? UnwrapResultValue(object? result) + { + if (result is null) + return null; + + var resultType = result.GetType(); + + return resultType.GetProperty("IsSuccess")?.GetValue(result) is true + ? resultType.GetProperty("Value")?.GetValue(result) + : null; + } + static LambdaExpression BuildIdEqualsExpression(Type aggregateType, string aggregateId) { var parameter = Expression.Parameter(aggregateType, "x"); @@ -228,7 +239,7 @@ public sealed record SnapshotStatusResponse( string AggregateType, string AggregateId, bool Exists, - int CurrentVersion, + long CurrentVersion, int SchemaVersion ); @@ -243,5 +254,5 @@ public sealed record SnapshotRebuildResponse( string AggregateType, string AggregateId, bool Rebuilt, - int CurrentVersion + long CurrentVersion ); diff --git a/src/src/Admin.API/Endpoints/AdminTenantScopeFilter.cs b/src/src/Admin.API/Endpoints/AdminTenantScopeFilter.cs new file mode 100644 index 00000000..6af64701 --- /dev/null +++ b/src/src/Admin.API/Endpoints/AdminTenantScopeFilter.cs @@ -0,0 +1,54 @@ +using Microsoft.AspNetCore.Http; +using Purview.EventSourcing.Admin.Failures; +using Purview.EventSourcing.Admin.Services; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.Admin.API.Endpoints; + +/// +/// Resolves the tenant an admin request acts for, and applies it for the duration of the request. +/// +/// +/// Applied to the whole admin group rather than to individual endpoints: an endpoint added later must not +/// be able to escape tenant scoping by omitting a filter. A request that cannot be resolved to exactly one +/// tenant is refused - there is no fallback that serves every tenant. +/// +/// Decides the tenant from the caller's entitlements and the request. +/// The request header naming the tenant to act for. +public sealed class AdminTenantScopeFilter(IAdminTenantResolver resolver, string headerName) : IEndpointFilter +{ + /// + public async ValueTask InvokeAsync(EndpointFilterInvocationContext context, EndpointFilterDelegate next) + { + ArgumentNullException.ThrowIfNull(context); + ArgumentNullException.ThrowIfNull(next); + + var httpContext = context.HttpContext; + var requested = httpContext.Request.Headers.TryGetValue(headerName, out var header) ? header.ToString() : null; + + var resolved = await resolver.ResolveAsync( + httpContext.User, + string.IsNullOrWhiteSpace(requested) ? null : requested, + httpContext.RequestAborted + ); + + if (resolved.IsFailure) + { + return resolved.Error switch + { + AdminTenantForbidden => TypedResults.Problem( + statusCode: StatusCodes.Status403Forbidden, + title: "The requested tenant is not available to this user." + ), + _ => TypedResults.Problem( + statusCode: StatusCodes.Status400BadRequest, + title: $"A tenant must be named using the '{headerName}' header." + ), + }; + } + + using var scope = AmbientCurrentTenant.BeginScope(TenantScope.For(resolved.Value)); + + return await next(context); + } +} diff --git a/src/src/Admin.API/Extensions/Microsoft/AspNetCore/Builder/WebApplicationExtensions.cs b/src/src/Admin.API/Extensions/Microsoft/AspNetCore/Builder/WebApplicationExtensions.cs index 83052638..28b9b870 100644 --- a/src/src/Admin.API/Extensions/Microsoft/AspNetCore/Builder/WebApplicationExtensions.cs +++ b/src/src/Admin.API/Extensions/Microsoft/AspNetCore/Builder/WebApplicationExtensions.cs @@ -1,9 +1,11 @@ using System.ComponentModel; using System.Diagnostics.CodeAnalysis; +using Microsoft.AspNetCore.Http; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Options; -using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.API.Endpoints; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Services; namespace Microsoft.AspNetCore.Builder; @@ -40,6 +42,20 @@ public void MapPurviewEventSourcingAdminAPI( configureEndpoints?.Invoke(endpointOptions); var group = app.MapGroup(options.RoutePrefix).WithName("AdminPortal").RequireAuthorization(); + + // Added to the group before any endpoint is mapped, so an endpoint added later cannot escape + // tenant scoping by forgetting to opt in. + if (options.EnforceTenantScope) + { + var resolver = + app.Services.GetService() + ?? throw new InvalidOperationException( + $"{nameof(AdminPortalOptions.EnforceTenantScope)} is enabled but no {nameof(IAdminTenantResolver)} is registered." + ); + + group.AddEndpointFilter(new AdminTenantScopeFilter(resolver, options.TenantHeaderName)); + } + endpointOptions.GroupConvention?.Invoke(group); // Map endpoint groups diff --git a/src/src/Admin.API/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs b/src/src/Admin.API/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs index 213f7c3b..812d91d6 100644 --- a/src/src/Admin.API/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs +++ b/src/src/Admin.API/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs @@ -116,9 +116,14 @@ public TBuilder AddPurviewEventSourcingAdminOpenAPI(Action? conf && response.Content is not null ) { + // IOpenApiMediaType exposes Schema read-only; the concrete media type is what + // carries the setter. foreach (var content in response.Content.Values) { - content.Schema = new OpenApiSchema + if (content is not OpenApiMediaType mediaType) + continue; + + mediaType.Schema = new OpenApiSchema { Type = JsonSchemaType.String, Format = "binary", diff --git a/src/src/Admin.Abstractions/Admin.Abstractions.csproj b/src/src/Admin.Abstractions/Admin.Abstractions.csproj index 873a7b37..d57ae093 100644 --- a/src/src/Admin.Abstractions/Admin.Abstractions.csproj +++ b/src/src/Admin.Abstractions/Admin.Abstractions.csproj @@ -5,4 +5,8 @@ Core abstractions and contracts for Purview EventSourcing Admin Portal — query services, permission models, and DTOs. $(PackageTags);purview;dotnet;event-sourcing;admin;abstractions; + + + + diff --git a/src/src/Admin.Abstractions/Failures/AdminAggregateNotFound.cs b/src/src/Admin.Abstractions/Failures/AdminAggregateNotFound.cs new file mode 100644 index 00000000..4b3e88e2 --- /dev/null +++ b/src/src/Admin.Abstractions/Failures/AdminAggregateNotFound.cs @@ -0,0 +1,12 @@ +namespace Purview.EventSourcing.Admin.Failures; + +/// +/// The admin query found nothing for the requested aggregate. +/// +/// The aggregate type name that was queried. +/// The identifier that was requested. +/// +/// Covers a stream that does not exist and one that holds no events within the requested bounds; both leave +/// the caller with nothing to show. +/// +public readonly record struct AdminAggregateNotFound(string AggregateType, string AggregateId); diff --git a/src/src/Admin.Abstractions/Failures/AdminQueryFailure.cs b/src/src/Admin.Abstractions/Failures/AdminQueryFailure.cs new file mode 100644 index 00000000..5b2b904f --- /dev/null +++ b/src/src/Admin.Abstractions/Failures/AdminQueryFailure.cs @@ -0,0 +1,13 @@ +using Purview.Results; + +namespace Purview.EventSourcing.Admin.Failures; + +/// +/// The expected ways an admin query fails. +/// +/// +/// Deliberately separate from the event store's own failure unions: the admin abstractions carry no reference +/// to the store, so a host can implement these services over anything. +/// +[GenerateResult] +public readonly union AdminQueryFailure(AdminAggregateNotFound); diff --git a/src/src/Admin.Abstractions/Failures/AdminTenantFailure.cs b/src/src/Admin.Abstractions/Failures/AdminTenantFailure.cs new file mode 100644 index 00000000..85e28446 --- /dev/null +++ b/src/src/Admin.Abstractions/Failures/AdminTenantFailure.cs @@ -0,0 +1,13 @@ +using Purview.Results; + +namespace Purview.EventSourcing.Admin.Failures; + +/// +/// The expected ways resolving the tenant for an admin request fails. +/// +/// +/// Both cases are denials rather than errors: neither grants a cross-tenant view. A super user who names +/// no tenant gets , not the system scope. +/// +[GenerateResult] +public readonly union AdminTenantFailure(AdminTenantNotSelected, AdminTenantForbidden); diff --git a/src/src/Admin.Abstractions/Failures/AdminTenantForbidden.cs b/src/src/Admin.Abstractions/Failures/AdminTenantForbidden.cs new file mode 100644 index 00000000..7894e739 --- /dev/null +++ b/src/src/Admin.Abstractions/Failures/AdminTenantForbidden.cs @@ -0,0 +1,8 @@ +namespace Purview.EventSourcing.Admin.Failures; + +/// +/// The user named a tenant they are not entitled to. +/// +/// The identifier of the user, when known. +/// The tenant the user asked for. +public readonly record struct AdminTenantForbidden(string? UserId, string RequestedTenantId); diff --git a/src/src/Admin.Abstractions/Failures/AdminTenantNotSelected.cs b/src/src/Admin.Abstractions/Failures/AdminTenantNotSelected.cs new file mode 100644 index 00000000..f425518e --- /dev/null +++ b/src/src/Admin.Abstractions/Failures/AdminTenantNotSelected.cs @@ -0,0 +1,8 @@ +namespace Purview.EventSourcing.Admin.Failures; + +/// +/// The user is entitled to more than one tenant but named none, so there is nothing to scope the +/// request to. +/// +/// The identifier of the user, when known. +public readonly record struct AdminTenantNotSelected(string? UserId); diff --git a/src/src/Admin.Abstractions/Services/IAdminAggregateQueryService.cs b/src/src/Admin.Abstractions/Services/IAdminAggregateQueryService.cs index f43aa0c5..41ee8fd8 100644 --- a/src/src/Admin.Abstractions/Services/IAdminAggregateQueryService.cs +++ b/src/src/Admin.Abstractions/Services/IAdminAggregateQueryService.cs @@ -1,5 +1,7 @@ +using Purview.EventSourcing.Admin.Failures; using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Queries; +using Purview.Results; namespace Purview.EventSourcing.Admin.Services; @@ -25,8 +27,10 @@ CancellationToken cancellationToken /// The aggregate type name. /// The aggregate identifier. /// The token to monitor for cancellation requests. - /// The aggregate summary, or if the aggregate does not exist. - Task GetAsync( + /// + /// The aggregate summary, or when the aggregate does not exist. + /// + Task> GetAsync( string aggregateType, string aggregateId, CancellationToken cancellationToken diff --git a/src/src/Admin.Abstractions/Services/IAdminEventQueryService.cs b/src/src/Admin.Abstractions/Services/IAdminEventQueryService.cs index 87585188..844c76bc 100644 --- a/src/src/Admin.Abstractions/Services/IAdminEventQueryService.cs +++ b/src/src/Admin.Abstractions/Services/IAdminEventQueryService.cs @@ -1,5 +1,7 @@ +using Purview.EventSourcing.Admin.Failures; using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Queries; +using Purview.Results; namespace Purview.EventSourcing.Admin.Services; @@ -16,9 +18,10 @@ public interface IAdminEventQueryService /// The event range filter and paging criteria. /// The token to monitor for cancellation requests. /// - /// A paged collection of event envelopes for the stream, or when the aggregate stream does not exist. + /// A paged collection of event envelopes for the stream, or when the + /// stream does not exist. /// - Task?> GetRangeAsync( + Task, AdminQueryFailure>> GetRangeAsync( string aggregateType, string aggregateId, EventRangeQuery query, diff --git a/src/src/Admin.Abstractions/Services/IAdminProjectionService.cs b/src/src/Admin.Abstractions/Services/IAdminProjectionService.cs index 7b53c4c8..dfc6c75d 100644 --- a/src/src/Admin.Abstractions/Services/IAdminProjectionService.cs +++ b/src/src/Admin.Abstractions/Services/IAdminProjectionService.cs @@ -1,4 +1,6 @@ +using Purview.EventSourcing.Admin.Failures; using Purview.EventSourcing.Admin.Models; +using Purview.Results; namespace Purview.EventSourcing.Admin.Services; @@ -15,9 +17,10 @@ public interface IAdminProjectionService /// The stream version up to and including which events are applied. /// The token to monitor for cancellation requests. /// - /// The projected aggregate state, or when the aggregate stream does not exist. + /// The projected aggregate state, or when the stream holds no events + /// up to that version. /// - Task ProjectAtVersionAsync( + Task> ProjectAtVersionAsync( string aggregateType, string aggregateId, long targetVersion, @@ -32,9 +35,10 @@ CancellationToken cancellationToken /// The UTC timestamp up to and including which events are applied. /// The token to monitor for cancellation requests. /// - /// The projected aggregate state, or when the aggregate stream does not exist. + /// The projected aggregate state, or when the stream holds no events + /// at or before that time. /// - Task ProjectAtTimeAsync( + Task> ProjectAtTimeAsync( string aggregateType, string aggregateId, DateTimeOffset targetUtc, diff --git a/src/src/Admin.Abstractions/Services/IAdminStorageProbe.cs b/src/src/Admin.Abstractions/Services/IAdminStorageProbe.cs new file mode 100644 index 00000000..e321cec8 --- /dev/null +++ b/src/src/Admin.Abstractions/Services/IAdminStorageProbe.cs @@ -0,0 +1,19 @@ +namespace Purview.EventSourcing.Admin.Services; + +/// +/// Probes the configured event-store storage so the Admin portal can report whether it is reachable. +/// +/// +/// Implemented by the provider-specific Admin.* adapter, because only it knows how to reach the +/// storage cheaply. The probe must be read-only and side-effect free: it runs on an operational endpoint +/// that may be polled frequently. +/// +public interface IAdminStorageProbe +{ + /// + /// Checks that the configured storage is reachable. + /// + /// The token to monitor for cancellation requests. + /// when storage responded; otherwise . + Task IsReachableAsync(CancellationToken cancellationToken); +} diff --git a/src/src/Admin.Abstractions/Services/IAdminTenantResolver.cs b/src/src/Admin.Abstractions/Services/IAdminTenantResolver.cs new file mode 100644 index 00000000..ce8ac5ad --- /dev/null +++ b/src/src/Admin.Abstractions/Services/IAdminTenantResolver.cs @@ -0,0 +1,30 @@ +using System.Security.Claims; +using Purview.EventSourcing.Admin.Failures; +using Purview.Results; + +namespace Purview.EventSourcing.Admin.Services; + +/// +/// Decides which tenant an admin request runs against. +/// +/// +/// An administrator entitled to a single tenant is scoped to it. One entitled to several - a super user - +/// must name the tenant on the request; naming none is a denial, not permission to see every tenant. The +/// system scope is deliberately unreachable from here - the contract returns a tenant identifier and +/// nothing else - because crossing tenants belongs to infrastructure, not to a signed-in user. +/// +public interface IAdminTenantResolver +{ + /// + /// Resolves the tenant scope for a request. + /// + /// The signed-in administrator. + /// The tenant named on the request, if any. + /// The token to monitor for cancellation requests. + /// The tenant identifier to scope to, or the reason the request is denied. + Task> ResolveAsync( + ClaimsPrincipal user, + string? requestedTenantId, + CancellationToken cancellationToken + ); +} diff --git a/src/src/Admin.AzureStorage/Admin.AzureStorage.csproj b/src/src/Admin.AzureStorage/Admin.AzureStorage.csproj index 87a69d7c..150250e9 100644 --- a/src/src/Admin.AzureStorage/Admin.AzureStorage.csproj +++ b/src/src/Admin.AzureStorage/Admin.AzureStorage.csproj @@ -14,6 +14,5 @@ - diff --git a/src/src/Admin.AzureStorage/AzureStorageAdminAggregateQueryService.cs b/src/src/Admin.AzureStorage/AzureStorageAdminAggregateQueryService.cs index fc43e157..e876eabf 100644 --- a/src/src/Admin.AzureStorage/AzureStorageAdminAggregateQueryService.cs +++ b/src/src/Admin.AzureStorage/AzureStorageAdminAggregateQueryService.cs @@ -1,11 +1,13 @@ using Azure; using Microsoft.Extensions.Options; +using Purview.EventSourcing.Admin.AzureStorage.Internal; +using Purview.EventSourcing.Admin.Failures; using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Queries; using Purview.EventSourcing.Admin.Services; -using Purview.EventSourcing.Admin.AzureStorage.Internal; using Purview.EventSourcing.AzureStorage; using Purview.EventSourcing.AzureStorage.Entities; +using Purview.Results; namespace Purview.EventSourcing.Admin.AzureStorage; @@ -106,7 +108,7 @@ var row in table.QueryAsync( } /// - public async Task GetAsync( + public async Task> GetAsync( string aggregateType, string aggregateId, CancellationToken cancellationToken @@ -117,7 +119,11 @@ CancellationToken cancellationToken AggregateSearchQuery query = new(aggregateType, aggregateId, null, null, null, null, 1, 1); var result = await SearchAsync(query, cancellationToken); - return result.Items.Count == 0 ? null : result.Items[0]; + return result.Items.Count == 0 + ? AdminQueryFailure.Failure( + new AdminAggregateNotFound(aggregateType, aggregateId) + ) + : result.Items[0]; } static IEnumerable ApplySort(IEnumerable rows, string sort) diff --git a/src/src/Admin.AzureStorage/AzureStorageAdminEventQueryService.cs b/src/src/Admin.AzureStorage/AzureStorageAdminEventQueryService.cs index 3f30212a..e1b6ddcf 100644 --- a/src/src/Admin.AzureStorage/AzureStorageAdminEventQueryService.cs +++ b/src/src/Admin.AzureStorage/AzureStorageAdminEventQueryService.cs @@ -1,12 +1,14 @@ using System.Text.Json; using Azure; using Microsoft.Extensions.Options; +using Purview.EventSourcing.Admin.AzureStorage.Internal; +using Purview.EventSourcing.Admin.Failures; using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Queries; using Purview.EventSourcing.Admin.Services; -using Purview.EventSourcing.Admin.AzureStorage.Internal; using Purview.EventSourcing.AzureStorage; using Purview.EventSourcing.AzureStorage.Entities; +using Purview.Results; namespace Purview.EventSourcing.Admin.AzureStorage; @@ -23,7 +25,7 @@ public sealed class AzureStorageAdminEventQueryService(IOptions - public async Task?> GetRangeAsync( + public async Task, AdminQueryFailure>> GetRangeAsync( string aggregateType, string aggregateId, EventRangeQuery query, @@ -43,7 +45,7 @@ CancellationToken cancellationToken cancellationToken ); - List<(string AggregateType, int Version, EventEntity Event)> rows = []; + List<(string AggregateType, long Version, EventEntity Event)> rows = []; foreach (var tableName in tableNames) { var table = AzureStorageAdminTableHelpers.CreateTableClient(tableService, tableName); diff --git a/src/src/Admin.AzureStorage/AzureStorageAdminProjectionService.cs b/src/src/Admin.AzureStorage/AzureStorageAdminProjectionService.cs index fc7970af..5052b10a 100644 --- a/src/src/Admin.AzureStorage/AzureStorageAdminProjectionService.cs +++ b/src/src/Admin.AzureStorage/AzureStorageAdminProjectionService.cs @@ -1,11 +1,13 @@ +using System.Text.Json; using Azure; using Microsoft.Extensions.Options; using Purview.EventSourcing.Admin.AzureStorage.Internal; +using Purview.EventSourcing.Admin.Failures; using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.AzureStorage; using Purview.EventSourcing.AzureStorage.Entities; -using System.Text.Json; +using Purview.Results; namespace Purview.EventSourcing.Admin.AzureStorage; @@ -22,7 +24,7 @@ public sealed class AzureStorageAdminProjectionService(IOptions - public async Task ProjectAtVersionAsync( + public async Task> ProjectAtVersionAsync( string aggregateType, string aggregateId, long targetVersion, @@ -46,7 +48,7 @@ CancellationToken cancellationToken } /// - public async Task ProjectAtTimeAsync( + public async Task> ProjectAtTimeAsync( string aggregateType, string aggregateId, DateTimeOffset targetUtc, @@ -66,7 +68,7 @@ CancellationToken cancellationToken return BuildProjection(aggregateType, aggregateId, events, $"Events projected up to timestamp {targetUtc:O}"); } - static ProjectionResponse? BuildProjection( + static Result BuildProjection( string aggregateType, string aggregateId, List<(long Version, EventEntity Event)> events, @@ -74,7 +76,9 @@ string reason ) { if (events.Count == 0) - return null; + return AdminQueryFailure.Failure( + new AdminAggregateNotFound(aggregateType, aggregateId) + ); List appliedVersions = []; List skippedVersions = []; diff --git a/src/src/Admin.AzureStorage/AzureStorageAdminStorageProbe.cs b/src/src/Admin.AzureStorage/AzureStorageAdminStorageProbe.cs new file mode 100644 index 00000000..3e9d71ce --- /dev/null +++ b/src/src/Admin.AzureStorage/AzureStorageAdminStorageProbe.cs @@ -0,0 +1,26 @@ +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Admin.AzureStorage.Internal; +using Purview.EventSourcing.Admin.Services; +using Purview.EventSourcing.AzureStorage; + +namespace Purview.EventSourcing.Admin.AzureStorage; + +/// +/// Reports whether the configured Azure Table Storage event store is reachable. +/// +/// The event-store options supplying the storage connection. +public sealed class AzureStorageAdminStorageProbe(IOptions options) : IAdminStorageProbe +{ + /// + public async Task IsReachableAsync(CancellationToken cancellationToken) + { + // Listing a single table name is the cheapest call that still proves the account is reachable + // and the credential is accepted; an empty account is still a reachable account. + var tableService = AzureStorageAdminTableHelpers.CreateTableServiceClient(options.Value); + + await foreach (var _ in tableService.QueryAsync(maxPerPage: 1, cancellationToken: cancellationToken)) + break; + + return true; + } +} diff --git a/src/src/Admin.AzureStorage/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs b/src/src/Admin.AzureStorage/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs index 6c6fe47b..3cac464b 100644 --- a/src/src/Admin.AzureStorage/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs +++ b/src/src/Admin.AzureStorage/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs @@ -17,6 +17,7 @@ public static class HostApplicationBuilderExtensions public TBuilder AddPurviewEventSourcingAdminAzureStorage() { builder.Services.TryAddTransient(); + builder.Services.TryAddTransient(); builder.Services.TryAddTransient(); builder.Services.TryAddTransient(); diff --git a/src/src/Admin.AzureStorage/Internal/AzureStorageAdminTableHelpers.cs b/src/src/Admin.AzureStorage/Internal/AzureStorageAdminTableHelpers.cs index 24d889b9..9c4ab287 100644 --- a/src/src/Admin.AzureStorage/Internal/AzureStorageAdminTableHelpers.cs +++ b/src/src/Admin.AzureStorage/Internal/AzureStorageAdminTableHelpers.cs @@ -88,8 +88,8 @@ public static string BuildEventRangeFilter( string aggregateId, string eventPrefix, int eventSuffixLength, - int versionFrom, - int? versionTo + long versionFrom, + long? versionTo ) { var fromKey = BuildEventRowKey(eventPrefix, eventSuffixLength, versionFrom); @@ -97,15 +97,15 @@ public static string BuildEventRangeFilter( return $"(PartitionKey eq '{aggregateId}') and ((RowKey ge '{fromKey}') and (RowKey le '{toKey}'))"; } - public static string BuildEventRowKey(string eventPrefix, int eventSuffixLength, int version) => + public static string BuildEventRowKey(string eventPrefix, int eventSuffixLength, long version) => $"{eventPrefix}_{version.ToString(System.Globalization.CultureInfo.InvariantCulture).PadLeft(eventSuffixLength, '0')}"; - public static bool TryParseEventVersion(string rowKey, string eventPrefix, out int version) + public static bool TryParseEventVersion(string rowKey, string eventPrefix, out long version) { version = default; var prefix = $"{eventPrefix}_"; return rowKey.StartsWith(prefix, StringComparison.Ordinal) - && int.TryParse(rowKey[prefix.Length..], out version); + && long.TryParse(rowKey[prefix.Length..], out version); } public static bool MatchesAggregateType(string persistedAggregateType, string requestedAggregateType) => diff --git a/src/src/Admin.Client/Admin.Client.csproj b/src/src/Admin.Client/Admin.Client.csproj index ba6fe0ec..87b45bd5 100644 --- a/src/src/Admin.Client/Admin.Client.csproj +++ b/src/src/Admin.Client/Admin.Client.csproj @@ -8,6 +8,5 @@ - diff --git a/src/src/Admin.Client/Generated/AdminApiClient.g.cs b/src/src/Admin.Client/Generated/AdminApiClient.g.cs index 24be9a75..11240141 100644 --- a/src/src/Admin.Client/Generated/AdminApiClient.g.cs +++ b/src/src/Admin.Client/Generated/AdminApiClient.g.cs @@ -2070,7 +2070,7 @@ public partial class SnapshotRebuildResponse public bool Rebuilt { get; set; } = default!; [System.Text.Json.Serialization.JsonPropertyName("currentVersion")] - public int CurrentVersion { get; set; } = default!; + public long CurrentVersion { get; set; } = default!; private System.Collections.Generic.IDictionary? _additionalProperties; @@ -2097,7 +2097,7 @@ public partial class SnapshotStatusResponse public bool Exists { get; set; } = default!; [System.Text.Json.Serialization.JsonPropertyName("currentVersion")] - public int CurrentVersion { get; set; } = default!; + public long CurrentVersion { get; set; } = default!; [System.Text.Json.Serialization.JsonPropertyName("schemaVersion")] public int SchemaVersion { get; set; } = default!; diff --git a/src/src/Admin.MongoDB/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/Admin.MongoDB/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs index 4a3753f1..a49177db 100644 --- a/src/src/Admin.MongoDB/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs +++ b/src/src/Admin.MongoDB/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -38,6 +38,12 @@ public IServiceCollection AddPurviewEventSourcingAdminMongoDB(string databaseNam return new MongoDBAdminProjectionService(mongoClient, databaseName); }); + services.TryAddTransient(sp => + { + var mongoClient = sp.GetRequiredService(); + return new MongoDBAdminStorageProbe(mongoClient, databaseName); + }); + return services; } } diff --git a/src/src/Admin.MongoDB/MongoDBAdminStorageProbe.cs b/src/src/Admin.MongoDB/MongoDBAdminStorageProbe.cs new file mode 100644 index 00000000..08095537 --- /dev/null +++ b/src/src/Admin.MongoDB/MongoDBAdminStorageProbe.cs @@ -0,0 +1,24 @@ +using MongoDB.Bson; +using MongoDB.Driver; +using Purview.EventSourcing.Admin.Services; + +namespace Purview.EventSourcing.Admin.MongoDB; + +/// +/// Reports whether the configured MongoDB event store is reachable. +/// +/// The client used to reach the server. +/// The database holding the event-store collections. +public sealed class MongoDBAdminStorageProbe(IMongoClient mongoClient, string databaseName) : IAdminStorageProbe +{ + /// + public async Task IsReachableAsync(CancellationToken cancellationToken) + { + // ping is the server's own liveness command: no collection access, no read permissions needed. + var response = await mongoClient + .GetDatabase(databaseName) + .RunCommandAsync(new BsonDocument("ping", 1), cancellationToken: cancellationToken); + + return response.GetValue("ok", BsonValue.Create(0)).ToDouble() is 1d; + } +} diff --git a/src/src/Admin.MongoDB/MongoDbAdminAggregateQueryService.cs b/src/src/Admin.MongoDB/MongoDbAdminAggregateQueryService.cs index 11be24fd..cab72093 100644 --- a/src/src/Admin.MongoDB/MongoDbAdminAggregateQueryService.cs +++ b/src/src/Admin.MongoDB/MongoDbAdminAggregateQueryService.cs @@ -1,8 +1,10 @@ using MongoDB.Driver; +using Purview.EventSourcing.Admin.Failures; using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Queries; using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.MongoDB.Events.Entities; +using Purview.Results; namespace Purview.EventSourcing.Admin.MongoDB; @@ -87,7 +89,7 @@ CancellationToken cancellationToken } /// - public async Task GetAsync( + public async Task> GetAsync( string aggregateType, string aggregateId, CancellationToken cancellationToken @@ -108,7 +110,9 @@ CancellationToken cancellationToken var item = await collection.Find(filter).FirstOrDefaultAsync(cancellationToken); return item == null - ? null + ? AdminQueryFailure.Failure( + new AdminAggregateNotFound(aggregateType, aggregateId) + ) : new AggregateSummaryResponse( aggregateType, item.AggregateId, diff --git a/src/src/Admin.MongoDB/MongoDbAdminEventQueryService.cs b/src/src/Admin.MongoDB/MongoDbAdminEventQueryService.cs index dd41de7c..748286a9 100644 --- a/src/src/Admin.MongoDB/MongoDbAdminEventQueryService.cs +++ b/src/src/Admin.MongoDB/MongoDbAdminEventQueryService.cs @@ -1,9 +1,11 @@ +using System.Text.Json; using MongoDB.Driver; +using Purview.EventSourcing.Admin.Failures; using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Queries; using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.MongoDB.Events.Entities; -using System.Text.Json; +using Purview.Results; namespace Purview.EventSourcing.Admin.MongoDB; @@ -24,7 +26,7 @@ public sealed class MongoDBAdminEventQueryService(IMongoClient mongoClient, stri readonly string _databaseName = databaseName ?? throw new ArgumentNullException(nameof(databaseName)); /// - public async Task?> GetRangeAsync( + public async Task, AdminQueryFailure>> GetRangeAsync( string aggregateType, string aggregateId, EventRangeQuery query, @@ -101,5 +103,8 @@ CancellationToken cancellationToken return new PagedResult(envelopes, query.Page, pageSize, total); } - static JsonElement ParsePayload(string? payload) => string.IsNullOrWhiteSpace(payload) ? JsonSerializer.SerializeToElement("null") : JsonSerializer.SerializeToElement(payload); + static JsonElement ParsePayload(string? payload) => + string.IsNullOrWhiteSpace(payload) + ? JsonSerializer.SerializeToElement("null") + : JsonSerializer.SerializeToElement(payload); } diff --git a/src/src/Admin.MongoDB/MongoDbAdminProjectionService.cs b/src/src/Admin.MongoDB/MongoDbAdminProjectionService.cs index 3da6f0c0..448953b0 100644 --- a/src/src/Admin.MongoDB/MongoDbAdminProjectionService.cs +++ b/src/src/Admin.MongoDB/MongoDbAdminProjectionService.cs @@ -1,8 +1,11 @@ +using System.Diagnostics.CodeAnalysis; +using System.Text.Json; using MongoDB.Driver; +using Purview.EventSourcing.Admin.Failures; using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.MongoDB.Events.Entities; -using System.Text.Json; +using Purview.Results; namespace Purview.EventSourcing.Admin.MongoDB; @@ -23,7 +26,12 @@ public sealed class MongoDBAdminProjectionService(IMongoClient mongoClient, stri readonly string _databaseName = databaseName ?? throw new ArgumentNullException(nameof(databaseName)); /// - public async Task ProjectAtVersionAsync( + [SuppressMessage( + "Maintainability", + "CA1506:Avoid excessive class coupling", + Justification = "Projection replays a stream through the Mongo driver, the event mapper and the result model." + )] + public async Task> ProjectAtVersionAsync( string aggregateType, string aggregateId, long targetVersion, @@ -49,7 +57,9 @@ CancellationToken cancellationToken if (events.Count == 0) { - return null; + return AdminQueryFailure.Failure( + new AdminAggregateNotFound(aggregateType, aggregateId) + ); } List appliedVersions = []; @@ -101,7 +111,7 @@ CancellationToken cancellationToken } /// - public async Task ProjectAtTimeAsync( + public async Task> ProjectAtTimeAsync( string aggregateType, string aggregateId, DateTimeOffset targetUtc, @@ -125,7 +135,9 @@ CancellationToken cancellationToken if (events.Count == 0) { - return null; + return AdminQueryFailure.Failure( + new AdminAggregateNotFound(aggregateType, aggregateId) + ); } List appliedVersions = []; diff --git a/src/src/Admin.Postgres/Admin.Postgres.csproj b/src/src/Admin.Postgres/Admin.Postgres.csproj index 0bc5f4f2..53d6c0aa 100644 --- a/src/src/Admin.Postgres/Admin.Postgres.csproj +++ b/src/src/Admin.Postgres/Admin.Postgres.csproj @@ -15,7 +15,6 @@ - diff --git a/src/src/Admin.Postgres/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs b/src/src/Admin.Postgres/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs index 3c3e7f9b..a0b4fede 100644 --- a/src/src/Admin.Postgres/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs +++ b/src/src/Admin.Postgres/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs @@ -16,6 +16,7 @@ public static class HostApplicationBuilderExtensions public TBuilder AddPurviewEventSourcingAdminPostgres() { builder.Services.TryAddTransient(); + builder.Services.TryAddTransient(); builder.Services.TryAddTransient(); builder.Services.TryAddTransient(); diff --git a/src/src/Admin.Postgres/PostgresAdminAggregateQueryService.cs b/src/src/Admin.Postgres/PostgresAdminAggregateQueryService.cs index 2df9410d..f4a0fa1c 100644 --- a/src/src/Admin.Postgres/PostgresAdminAggregateQueryService.cs +++ b/src/src/Admin.Postgres/PostgresAdminAggregateQueryService.cs @@ -1,11 +1,14 @@ using Microsoft.EntityFrameworkCore; using Microsoft.Extensions.Options; +using Purview.EventSourcing.Admin.Failures; using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Postgres.Internal; using Purview.EventSourcing.Admin.Queries; using Purview.EventSourcing.Admin.Services; -using Purview.EventSourcing.Admin.Postgres.Internal; using Purview.EventSourcing.Postgres.Events; using Purview.EventSourcing.Postgres.Events.EntityFramework; +using Purview.EventSourcing.Tenancy; +using Purview.Results; namespace Purview.EventSourcing.Admin.Postgres; @@ -18,8 +21,11 @@ namespace Purview.EventSourcing.Admin.Postgres; /// paged in memory. /// /// The configured . -public sealed class PostgresAdminAggregateQueryService(IOptions options) - : IAdminAggregateQueryService +/// Optional tenant scope; when omitted the query is not tenant-filtered. +public sealed class PostgresAdminAggregateQueryService( + IOptions options, + ICurrentTenant? currentTenant = null +) : IAdminAggregateQueryService { /// public async Task> SearchAsync( @@ -48,7 +54,7 @@ CancellationToken cancellationToken } /// - public async Task GetAsync( + public async Task> GetAsync( string aggregateType, string aggregateId, CancellationToken cancellationToken @@ -59,7 +65,11 @@ CancellationToken cancellationToken AggregateSearchQuery query = new(aggregateType, aggregateId, null, null, null, null, 1, 1); var result = await SearchAsync(query, cancellationToken); - return result.Items.Count == 0 ? null : result.Items[0]; + return result.Items.Count == 0 + ? AdminQueryFailure.Failure( + new AdminAggregateNotFound(aggregateType, aggregateId) + ) + : result.Items[0]; } static async Task> BuildAggregateRowsAsync( @@ -121,10 +131,10 @@ static IEnumerable ApplySort(IEnumerable builder = new(); builder.UseNpgsql(options.ConnectionString); - return new EventStoreDbContext(builder.Options, table.SchemaName, table.TableName); + return new EventStoreDbContext(builder.Options, table.SchemaName, table.TableName, currentTenant); } } diff --git a/src/src/Admin.Postgres/PostgresAdminEventQueryService.cs b/src/src/Admin.Postgres/PostgresAdminEventQueryService.cs index a4562e56..5f01e97f 100644 --- a/src/src/Admin.Postgres/PostgresAdminEventQueryService.cs +++ b/src/src/Admin.Postgres/PostgresAdminEventQueryService.cs @@ -1,12 +1,15 @@ +using System.Text.Json; using Microsoft.EntityFrameworkCore; using Microsoft.Extensions.Options; +using Purview.EventSourcing.Admin.Failures; using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Postgres.Internal; using Purview.EventSourcing.Admin.Queries; using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Postgres.Events; using Purview.EventSourcing.Postgres.Events.EntityFramework; -using System.Text.Json; +using Purview.EventSourcing.Tenancy; +using Purview.Results; namespace Purview.EventSourcing.Admin.Postgres; @@ -19,11 +22,14 @@ namespace Purview.EventSourcing.Admin.Postgres; /// database. /// /// The configured . -public sealed class PostgresAdminEventQueryService(IOptions options) - : IAdminEventQueryService +/// Optional tenant scope; when omitted the query is not tenant-filtered. +public sealed class PostgresAdminEventQueryService( + IOptions options, + ICurrentTenant? currentTenant = null +) : IAdminEventQueryService { /// - public async Task?> GetRangeAsync( + public async Task, AdminQueryFailure>> GetRangeAsync( string aggregateType, string aggregateId, EventRangeQuery query, @@ -90,12 +96,15 @@ CancellationToken cancellationToken return new PagedResult(items, page, pageSize, totalCount); } - static EventStoreDbContext CreateContext(PostgresEventStoreOptions options, PostgresAdminTableDescriptor table) + EventStoreDbContext CreateContext(PostgresEventStoreOptions options, PostgresAdminTableDescriptor table) { DbContextOptionsBuilder builder = new(); builder.UseNpgsql(options.ConnectionString); - return new EventStoreDbContext(builder.Options, table.SchemaName, table.TableName); + return new EventStoreDbContext(builder.Options, table.SchemaName, table.TableName, currentTenant); } - static JsonElement ParsePayload(string? payload) => string.IsNullOrWhiteSpace(payload) ? JsonSerializer.SerializeToElement("null") : JsonSerializer.SerializeToElement(payload); + static JsonElement ParsePayload(string? payload) => + string.IsNullOrWhiteSpace(payload) + ? JsonSerializer.SerializeToElement("null") + : JsonSerializer.SerializeToElement(payload); } diff --git a/src/src/Admin.Postgres/PostgresAdminProjectionService.cs b/src/src/Admin.Postgres/PostgresAdminProjectionService.cs index 970f6fce..645a9b0a 100644 --- a/src/src/Admin.Postgres/PostgresAdminProjectionService.cs +++ b/src/src/Admin.Postgres/PostgresAdminProjectionService.cs @@ -1,11 +1,14 @@ +using System.Text.Json; using Microsoft.EntityFrameworkCore; using Microsoft.Extensions.Options; +using Purview.EventSourcing.Admin.Failures; using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Postgres.Internal; using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Postgres.Events; using Purview.EventSourcing.Postgres.Events.EntityFramework; -using System.Text.Json; +using Purview.EventSourcing.Tenancy; +using Purview.Results; namespace Purview.EventSourcing.Admin.Postgres; @@ -18,11 +21,14 @@ namespace Purview.EventSourcing.Admin.Postgres; /// which event versions were applied and which were skipped. /// /// The configured . -public sealed class PostgresAdminProjectionService(IOptions options) - : IAdminProjectionService +/// Optional tenant scope; when omitted the query is not tenant-filtered. +public sealed class PostgresAdminProjectionService( + IOptions options, + ICurrentTenant? currentTenant = null +) : IAdminProjectionService { /// - public async Task ProjectAtVersionAsync( + public async Task> ProjectAtVersionAsync( string aggregateType, string aggregateId, long targetVersion, @@ -76,7 +82,9 @@ CancellationToken cancellationToken } if (rowList.Count == 0) - return null; + return AdminQueryFailure.Failure( + new AdminAggregateNotFound(aggregateType, aggregateId) + ); var reason = targetVersion > rowList.Last().Version @@ -102,7 +110,7 @@ CancellationToken cancellationToken } /// - public async Task ProjectAtTimeAsync( + public async Task> ProjectAtTimeAsync( string aggregateType, string aggregateId, DateTimeOffset targetUtc, @@ -158,7 +166,9 @@ CancellationToken cancellationToken } if (rowList.Count == 0) - return null; + return AdminQueryFailure.Failure( + new AdminAggregateNotFound(aggregateType, aggregateId) + ); var latestTimestamp = rowList.Last().Timestamp; var reason = @@ -184,10 +194,10 @@ CancellationToken cancellationToken ); } - static EventStoreDbContext CreateContext(PostgresEventStoreOptions options, PostgresAdminTableDescriptor table) + EventStoreDbContext CreateContext(PostgresEventStoreOptions options, PostgresAdminTableDescriptor table) { DbContextOptionsBuilder builder = new(); builder.UseNpgsql(options.ConnectionString); - return new EventStoreDbContext(builder.Options, table.SchemaName, table.TableName); + return new EventStoreDbContext(builder.Options, table.SchemaName, table.TableName, currentTenant); } } diff --git a/src/src/Admin.Postgres/PostgresAdminStorageProbe.cs b/src/src/Admin.Postgres/PostgresAdminStorageProbe.cs new file mode 100644 index 00000000..4b62e70a --- /dev/null +++ b/src/src/Admin.Postgres/PostgresAdminStorageProbe.cs @@ -0,0 +1,24 @@ +using Microsoft.Extensions.Options; +using Npgsql; +using Purview.EventSourcing.Admin.Services; +using Purview.EventSourcing.Postgres.Events; + +namespace Purview.EventSourcing.Admin.Postgres; + +/// +/// Reports whether the configured PostgreSQL event store is reachable. +/// +/// The event-store options supplying the connection string. +public sealed class PostgresAdminStorageProbe(IOptions options) : IAdminStorageProbe +{ + /// + public async Task IsReachableAsync(CancellationToken cancellationToken) + { + // Opening the connection is the probe: it exercises resolution, network, and authentication + // without reading a row, so a frequently polled health endpoint stays cheap. + await using NpgsqlConnection connection = new(options.Value.ConnectionString); + await connection.OpenAsync(cancellationToken); + + return connection.State is System.Data.ConnectionState.Open; + } +} diff --git a/src/src/Admin.Security/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/Admin.Security/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs index 6bd8fd0b..48a9f7a3 100644 --- a/src/src/Admin.Security/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs +++ b/src/src/Admin.Security/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -1,9 +1,9 @@ using System.ComponentModel; using Microsoft.AspNetCore.Authorization; using Microsoft.Extensions.DependencyInjection.Extensions; -using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.Security.Handlers; using Purview.EventSourcing.Admin.Security.Providers; +using Purview.EventSourcing.Admin.Services; namespace Microsoft.Extensions.DependencyInjection; @@ -33,6 +33,9 @@ public IServiceCollection AddPurviewEventSourcingAdminSecurity( // Default in-memory audit logger; applications may replace it with a durable implementation. services.TryAddSingleton(); + // TryAdd: a host entitling administrators differently registers its own resolver first. + services.TryAddSingleton(new ClaimsAdminTenantResolver()); + return services; } } diff --git a/src/src/Admin.Security/Handlers/AdminFeatureAuthorizationHandler.cs b/src/src/Admin.Security/Handlers/AdminFeatureAuthorizationHandler.cs index 057aafb6..25847547 100644 --- a/src/src/Admin.Security/Handlers/AdminFeatureAuthorizationHandler.cs +++ b/src/src/Admin.Security/Handlers/AdminFeatureAuthorizationHandler.cs @@ -1,7 +1,7 @@ using System.Diagnostics.CodeAnalysis; using Microsoft.AspNetCore.Authorization; -using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.Security.Requirements; +using Purview.EventSourcing.Admin.Services; namespace Purview.EventSourcing.Admin.Security.Handlers; diff --git a/src/src/Admin.Security/Handlers/AggregateTypeAccessHandler.cs b/src/src/Admin.Security/Handlers/AggregateTypeAccessHandler.cs index 49e7539a..88a5dce4 100644 --- a/src/src/Admin.Security/Handlers/AggregateTypeAccessHandler.cs +++ b/src/src/Admin.Security/Handlers/AggregateTypeAccessHandler.cs @@ -1,7 +1,7 @@ using System.Diagnostics.CodeAnalysis; using Microsoft.AspNetCore.Authorization; -using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.Security.Requirements; +using Purview.EventSourcing.Admin.Services; namespace Purview.EventSourcing.Admin.Security.Handlers; diff --git a/src/src/Admin.Security/Providers/ClaimsAdminTenantResolver.cs b/src/src/Admin.Security/Providers/ClaimsAdminTenantResolver.cs new file mode 100644 index 00000000..20d7cade --- /dev/null +++ b/src/src/Admin.Security/Providers/ClaimsAdminTenantResolver.cs @@ -0,0 +1,58 @@ +using System.Security.Claims; +using Purview.EventSourcing.Admin.Failures; +using Purview.EventSourcing.Admin.Services; +using Purview.Results; + +namespace Purview.EventSourcing.Admin.Security.Providers; + +/// +/// Resolves the admin tenant from the signed-in user's tenant claims. +/// +/// +/// Every tenant the administrator may act for is a separate claim of the configured type. One claim means +/// the administrator is scoped to it and may not name another; several means they must choose. +/// +/// The claim carrying an entitled tenant identifier. +public sealed class ClaimsAdminTenantResolver(string claimType = ClaimsAdminTenantResolver.DefaultClaimType) + : IAdminTenantResolver +{ + /// + /// The claim type used when none is configured. + /// + public const string DefaultClaimType = "tenant"; + + /// + public Task> ResolveAsync( + ClaimsPrincipal user, + string? requestedTenantId, + CancellationToken cancellationToken + ) + { + ArgumentNullException.ThrowIfNull(user); + + var entitled = user.FindAll(claimType) + .Select(claim => claim.Value) + .Where(value => !string.IsNullOrWhiteSpace(value)) + .ToHashSet(StringComparer.OrdinalIgnoreCase); + + var userId = user.FindFirst(ClaimTypes.NameIdentifier)?.Value; + + if (!string.IsNullOrWhiteSpace(requestedTenantId)) + { + return Task.FromResult( + entitled.Contains(requestedTenantId) + ? Result.Success(requestedTenantId) + : AdminTenantFailure.Failure(new AdminTenantForbidden(userId, requestedTenantId)) + ); + } + + // Exactly one entitlement needs no choice. Anything else - none, or several - is a denial: + // defaulting to the first would silently pick a tenant, and the system scope is not a user's + // to assume. + return Task.FromResult( + entitled.Count is 1 + ? Result.Success(entitled.First()) + : AdminTenantFailure.Failure(new AdminTenantNotSelected(userId)) + ); + } +} diff --git a/src/src/Admin.Site/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/Admin.Site/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs index 1ce44f42..8d811f67 100644 --- a/src/src/Admin.Site/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs +++ b/src/src/Admin.Site/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -26,7 +26,13 @@ public static IMvcBuilder AddPurviewEventSourcingAdminSite( var mvcBuilder = services.AddRazorPages(); if (enableRazorRuntimeCompilation) + { + // ASP.NET Core 11 deprecates runtime compilation (ASPDEPR003). This stays opt-in and + // development-only; removing the parameter is a public API change and is tracked separately. +#pragma warning disable ASPDEPR003 mvcBuilder.AddRazorRuntimeCompilation(); +#pragma warning restore ASPDEPR003 + } services.AddHttpContextAccessor(); services.AddTransient(); diff --git a/src/src/Admin.Site/Pages/AdminIndex.cshtml.cs b/src/src/Admin.Site/Pages/AdminIndex.cshtml.cs index f30456db..64286bb4 100644 --- a/src/src/Admin.Site/Pages/AdminIndex.cshtml.cs +++ b/src/src/Admin.Site/Pages/AdminIndex.cshtml.cs @@ -8,7 +8,7 @@ namespace Purview.EventSourcing.Admin.Site.Pages; /// Page model for the admin portal home page that searches for aggregates. /// /// The generated Admin API client used to search aggregates. -public class AdminIndexModel(AdminApiClient adminApiClient) : PageModel +sealed class AdminIndexModel(AdminApiClient adminApiClient) : PageModel { readonly AdminApiClient _adminAPIClient = adminApiClient ?? throw new ArgumentNullException(nameof(adminApiClient)); diff --git a/src/src/Admin.Site/Pages/Events.cshtml.cs b/src/src/Admin.Site/Pages/Events.cshtml.cs index b5211be8..770ccaa6 100644 --- a/src/src/Admin.Site/Pages/Events.cshtml.cs +++ b/src/src/Admin.Site/Pages/Events.cshtml.cs @@ -8,7 +8,7 @@ namespace Purview.EventSourcing.Admin.Site.Pages; /// Page model for the admin portal event history page. /// /// The generated Admin API client used to load event ranges. -public class EventsModel(AdminApiClient adminApiClient) : PageModel +sealed class EventsModel(AdminApiClient adminApiClient) : PageModel { readonly AdminApiClient _adminAPIClient = adminApiClient ?? throw new ArgumentNullException(nameof(adminApiClient)); diff --git a/src/src/Admin.Site/Pages/Projection.cshtml.cs b/src/src/Admin.Site/Pages/Projection.cshtml.cs index 4b6c4eb9..7697438f 100644 --- a/src/src/Admin.Site/Pages/Projection.cshtml.cs +++ b/src/src/Admin.Site/Pages/Projection.cshtml.cs @@ -8,7 +8,7 @@ namespace Purview.EventSourcing.Admin.Site.Pages; /// Page model for the admin portal point-in-time projection page. /// /// The generated Admin API client used to build projections. -public class ProjectionModel(AdminApiClient adminApiClient) : PageModel +sealed class ProjectionModel(AdminApiClient adminApiClient) : PageModel { readonly AdminApiClient _adminAPIClient = adminApiClient ?? throw new ArgumentNullException(nameof(adminApiClient)); diff --git a/src/src/Admin.Site/Properties/AssemblyInfo.cs b/src/src/Admin.Site/Properties/AssemblyInfo.cs index 785d6bac..6bd95e82 100644 --- a/src/src/Admin.Site/Properties/AssemblyInfo.cs +++ b/src/src/Admin.Site/Properties/AssemblyInfo.cs @@ -1,3 +1,6 @@ using System.Runtime.CompilerServices; [assembly: InternalsVisibleTo("Admin.Site.UnitTests")] +// The page models are internal - they are the site's implementation, not a contract a consumer binds to - +// and their tests live in the samples suite rather than a matching Admin.Site.UnitTests project. +[assembly: InternalsVisibleTo("Purview.EventSourcing.Samples.UnitTests")] diff --git a/src/src/Admin.SqlServer/Admin.SqlServer.csproj b/src/src/Admin.SqlServer/Admin.SqlServer.csproj index aed4ddad..30c62be4 100644 --- a/src/src/Admin.SqlServer/Admin.SqlServer.csproj +++ b/src/src/Admin.SqlServer/Admin.SqlServer.csproj @@ -13,7 +13,6 @@ - diff --git a/src/src/Admin.SqlServer/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs b/src/src/Admin.SqlServer/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs index 66c51040..3fa6a56c 100644 --- a/src/src/Admin.SqlServer/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs +++ b/src/src/Admin.SqlServer/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs @@ -17,6 +17,7 @@ public static class HostApplicationBuilderExtensions public TBuilder AddPurviewEventSourcingAdminSqlServer() { builder.Services.TryAddTransient(); + builder.Services.TryAddTransient(); builder.Services.TryAddTransient(); builder.Services.TryAddTransient(); diff --git a/src/src/Admin.SqlServer/SqlServerAdminAggregateQueryService.cs b/src/src/Admin.SqlServer/SqlServerAdminAggregateQueryService.cs index 732a801b..06783aa2 100644 --- a/src/src/Admin.SqlServer/SqlServerAdminAggregateQueryService.cs +++ b/src/src/Admin.SqlServer/SqlServerAdminAggregateQueryService.cs @@ -1,11 +1,14 @@ using Microsoft.EntityFrameworkCore; using Microsoft.Extensions.Options; +using Purview.EventSourcing.Admin.Failures; using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Queries; using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.SQLServer.Internal; using Purview.EventSourcing.SqlServer.Events; using Purview.EventSourcing.SqlServer.Events.EntityFramework; +using Purview.EventSourcing.Tenancy; +using Purview.Results; namespace Purview.EventSourcing.Admin.SQLServer; @@ -18,8 +21,11 @@ namespace Purview.EventSourcing.Admin.SQLServer; /// paged in memory. /// /// The configured . -public sealed class SqlServerAdminAggregateQueryService(IOptions options) - : IAdminAggregateQueryService +/// Optional tenant scope; when omitted the query is not tenant-filtered. +public sealed class SqlServerAdminAggregateQueryService( + IOptions options, + ICurrentTenant? currentTenant = null +) : IAdminAggregateQueryService { /// public async Task> SearchAsync( @@ -48,7 +54,7 @@ CancellationToken cancellationToken } /// - public async Task GetAsync( + public async Task> GetAsync( string aggregateType, string aggregateId, CancellationToken cancellationToken @@ -59,7 +65,11 @@ CancellationToken cancellationToken AggregateSearchQuery query = new(aggregateType, aggregateId, null, null, null, null, 1, 1); var result = await SearchAsync(query, cancellationToken); - return result.Items.Count == 0 ? null : result.Items[0]; + return result.Items.Count == 0 + ? AdminQueryFailure.Failure( + new AdminAggregateNotFound(aggregateType, aggregateId) + ) + : result.Items[0]; } static async Task> BuildAggregateRowsAsync( @@ -121,10 +131,10 @@ static IEnumerable ApplySort(IEnumerable builder = new(); builder.UseSqlServer(options.ConnectionString); - return new EventStoreDbContext(builder.Options, table.SchemaName, table.TableName); + return new EventStoreDbContext(builder.Options, table.SchemaName, table.TableName, currentTenant); } } diff --git a/src/src/Admin.SqlServer/SqlServerAdminEventQueryService.cs b/src/src/Admin.SqlServer/SqlServerAdminEventQueryService.cs index fb5ef0bc..22974ebd 100644 --- a/src/src/Admin.SqlServer/SqlServerAdminEventQueryService.cs +++ b/src/src/Admin.SqlServer/SqlServerAdminEventQueryService.cs @@ -1,12 +1,15 @@ using System.Text.Json; using Microsoft.EntityFrameworkCore; using Microsoft.Extensions.Options; +using Purview.EventSourcing.Admin.Failures; using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Queries; using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.SQLServer.Internal; using Purview.EventSourcing.SqlServer.Events; using Purview.EventSourcing.SqlServer.Events.EntityFramework; +using Purview.EventSourcing.Tenancy; +using Purview.Results; namespace Purview.EventSourcing.Admin.SQLServer; @@ -19,11 +22,14 @@ namespace Purview.EventSourcing.Admin.SQLServer; /// database. /// /// The configured . -public sealed class SqlServerAdminEventQueryService(IOptions options) - : IAdminEventQueryService +/// Optional tenant scope; when omitted the query is not tenant-filtered. +public sealed class SqlServerAdminEventQueryService( + IOptions options, + ICurrentTenant? currentTenant = null +) : IAdminEventQueryService { /// - public async Task?> GetRangeAsync( + public async Task, AdminQueryFailure>> GetRangeAsync( string aggregateType, string aggregateId, EventRangeQuery query, @@ -90,11 +96,11 @@ CancellationToken cancellationToken return new PagedResult(items, page, pageSize, totalCount); } - static EventStoreDbContext CreateContext(SqlServerEventStoreOptions options, SqlServerAdminTableDescriptor table) + EventStoreDbContext CreateContext(SqlServerEventStoreOptions options, SqlServerAdminTableDescriptor table) { DbContextOptionsBuilder builder = new(); builder.UseSqlServer(options.ConnectionString); - return new EventStoreDbContext(builder.Options, table.SchemaName, table.TableName); + return new EventStoreDbContext(builder.Options, table.SchemaName, table.TableName, currentTenant); } static JsonElement ParsePayload(string? payload) diff --git a/src/src/Admin.SqlServer/SqlServerAdminProjectionService.cs b/src/src/Admin.SqlServer/SqlServerAdminProjectionService.cs index fc9b2ce7..2b25ab7a 100644 --- a/src/src/Admin.SqlServer/SqlServerAdminProjectionService.cs +++ b/src/src/Admin.SqlServer/SqlServerAdminProjectionService.cs @@ -1,11 +1,14 @@ +using System.Text.Json; using Microsoft.EntityFrameworkCore; using Microsoft.Extensions.Options; +using Purview.EventSourcing.Admin.Failures; using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.SQLServer.Internal; using Purview.EventSourcing.SqlServer.Events; using Purview.EventSourcing.SqlServer.Events.EntityFramework; -using System.Text.Json; +using Purview.EventSourcing.Tenancy; +using Purview.Results; namespace Purview.EventSourcing.Admin.SQLServer; @@ -18,11 +21,14 @@ namespace Purview.EventSourcing.Admin.SQLServer; /// which event versions were applied and which were skipped. /// /// The configured . -public sealed class SqlServerAdminProjectionService(IOptions options) - : IAdminProjectionService +/// Optional tenant scope; when omitted the query is not tenant-filtered. +public sealed class SqlServerAdminProjectionService( + IOptions options, + ICurrentTenant? currentTenant = null +) : IAdminProjectionService { /// - public async Task ProjectAtVersionAsync( + public async Task> ProjectAtVersionAsync( string aggregateType, string aggregateId, long targetVersion, @@ -76,7 +82,9 @@ CancellationToken cancellationToken } if (rowList.Count == 0) - return null; + return AdminQueryFailure.Failure( + new AdminAggregateNotFound(aggregateType, aggregateId) + ); var reason = targetVersion > rowList.Last().Version @@ -102,7 +110,7 @@ CancellationToken cancellationToken } /// - public async Task ProjectAtTimeAsync( + public async Task> ProjectAtTimeAsync( string aggregateType, string aggregateId, DateTimeOffset targetUtc, @@ -158,7 +166,9 @@ CancellationToken cancellationToken } if (rowList.Count == 0) - return null; + return AdminQueryFailure.Failure( + new AdminAggregateNotFound(aggregateType, aggregateId) + ); var latestTimestamp = rowList.Last().Timestamp; var reason = @@ -184,10 +194,10 @@ CancellationToken cancellationToken ); } - static EventStoreDbContext CreateContext(SqlServerEventStoreOptions options, SqlServerAdminTableDescriptor table) + EventStoreDbContext CreateContext(SqlServerEventStoreOptions options, SqlServerAdminTableDescriptor table) { DbContextOptionsBuilder builder = new(); builder.UseSqlServer(options.ConnectionString); - return new EventStoreDbContext(builder.Options, table.SchemaName, table.TableName); + return new EventStoreDbContext(builder.Options, table.SchemaName, table.TableName, currentTenant); } } diff --git a/src/src/Admin.SqlServer/SqlServerAdminStorageProbe.cs b/src/src/Admin.SqlServer/SqlServerAdminStorageProbe.cs new file mode 100644 index 00000000..71b000ee --- /dev/null +++ b/src/src/Admin.SqlServer/SqlServerAdminStorageProbe.cs @@ -0,0 +1,24 @@ +using Microsoft.Data.SqlClient; +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Admin.Services; +using Purview.EventSourcing.SqlServer.Events; + +namespace Purview.EventSourcing.Admin.SqlServer; + +/// +/// Reports whether the configured SQL Server event store is reachable. +/// +/// The event-store options supplying the connection string. +public sealed class SqlServerAdminStorageProbe(IOptions options) : IAdminStorageProbe +{ + /// + public async Task IsReachableAsync(CancellationToken cancellationToken) + { + // Opening the connection is the probe: it exercises resolution, network, and authentication + // without reading a row, so a frequently polled health endpoint stays cheap. + await using SqlConnection connection = new(options.Value.ConnectionString); + await connection.OpenAsync(cancellationToken); + + return connection.State is System.Data.ConnectionState.Open; + } +} diff --git a/src/src/AzureStorage/AggregateVersionData.cs b/src/src/AzureStorage/AggregateVersionData.cs index 7c276c83..86cdabcf 100644 --- a/src/src/AzureStorage/AggregateVersionData.cs +++ b/src/src/AzureStorage/AggregateVersionData.cs @@ -1,4 +1,4 @@ -using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Aggregates; namespace Purview.EventSourcing.AzureStorage; @@ -8,7 +8,7 @@ namespace Purview.EventSourcing.AzureStorage; /// The last version persisted to the event store. /// The version covered by the most recent snapshot. /// The current version of the aggregate. -public record struct AggregateVersionData(int SavedVersion, int SnapshotVersion, int CurrentVersion) +public record struct AggregateVersionData(long SavedVersion, long SnapshotVersion, long CurrentVersion) { /// /// Creates an from the details of the given . diff --git a/src/src/AzureStorage/AzureStorage.csproj b/src/src/AzureStorage/AzureStorage.csproj index cce91514..ae8e193a 100644 --- a/src/src/AzureStorage/AzureStorage.csproj +++ b/src/src/AzureStorage/AzureStorage.csproj @@ -1,4 +1,4 @@ - + true Purview Event Store for Azure Table and Blob Storage @@ -9,9 +9,7 @@ - - diff --git a/src/src/AzureStorage/Entities/EventEntity.cs b/src/src/AzureStorage/Entities/EventEntity.cs index 2ce499cc..5b70737f 100644 --- a/src/src/AzureStorage/Entities/EventEntity.cs +++ b/src/src/AzureStorage/Entities/EventEntity.cs @@ -1,4 +1,4 @@ -using Azure; +using Azure; using Azure.Data.Tables; namespace Purview.EventSourcing.AzureStorage.Entities; @@ -11,7 +11,7 @@ namespace Purview.EventSourcing.AzureStorage.Entities; /// produced the event. The is the aggregate id and the /// encodes the aggregate version. /// -public sealed class EventEntity : ITableEntity +public sealed class EventEntity : ITableEntity, IHasTenant { /// /// Gets or sets the serialized event payload. @@ -58,5 +58,10 @@ public sealed class EventEntity : ITableEntity /// /// Gets or sets the entity tag used for optimistic concurrency. /// + /// + /// The tenant that owns the row; null in a single-tenant deployment. + /// + public string? TenantId { get; set; } + public ETag ETag { get; set; } } diff --git a/src/src/AzureStorage/Entities/IHasTenant.cs b/src/src/AzureStorage/Entities/IHasTenant.cs new file mode 100644 index 00000000..39361883 --- /dev/null +++ b/src/src/AzureStorage/Entities/IHasTenant.cs @@ -0,0 +1,9 @@ +namespace Purview.EventSourcing.AzureStorage.Entities; + +/// +/// A table row that records the tenant owning it. +/// +interface IHasTenant +{ + string? TenantId { get; set; } +} diff --git a/src/src/AzureStorage/Entities/IdempotencyMarkerEntity.cs b/src/src/AzureStorage/Entities/IdempotencyMarkerEntity.cs index 5c73777b..88762845 100644 --- a/src/src/AzureStorage/Entities/IdempotencyMarkerEntity.cs +++ b/src/src/AzureStorage/Entities/IdempotencyMarkerEntity.cs @@ -1,4 +1,4 @@ -using Azure; +using Azure; using Azure.Data.Tables; namespace Purview.EventSourcing.AzureStorage.Entities; @@ -10,7 +10,7 @@ namespace Purview.EventSourcing.AzureStorage.Entities; /// The marker records which event versions were persisted for a given idempotency id, allowing the store to /// detect and skip already-applied saves. /// -public sealed class IdempotencyMarkerEntity : ITableEntity +public sealed class IdempotencyMarkerEntity : ITableEntity, IHasTenant { /// /// Initializes a new instance of the class with the given keys. @@ -51,5 +51,10 @@ public IdempotencyMarkerEntity() { } /// /// Gets or sets the entity tag used for optimistic concurrency. /// + /// + /// The tenant that owns the row; null in a single-tenant deployment. + /// + public string? TenantId { get; set; } + public ETag ETag { get; set; } } diff --git a/src/src/AzureStorage/Entities/IdempotencyMarkerEventPayload.cs b/src/src/AzureStorage/Entities/IdempotencyMarkerEventPayload.cs index 2625c6dc..4186b7e4 100644 --- a/src/src/AzureStorage/Entities/IdempotencyMarkerEventPayload.cs +++ b/src/src/AzureStorage/Entities/IdempotencyMarkerEventPayload.cs @@ -1,4 +1,4 @@ -namespace Purview.EventSourcing.AzureStorage.Entities; +namespace Purview.EventSourcing.AzureStorage.Entities; /// /// The payload stored on an . @@ -16,5 +16,5 @@ public sealed class IdempotencyMarkerEventPayload "CA1819:Properties should not return arrays", Justification = "This is a DTO." )] - public int[] EventIds { get; set; } = default!; + public long[] EventIds { get; set; } = default!; } diff --git a/src/src/AzureStorage/Entities/StreamVersionEntity.cs b/src/src/AzureStorage/Entities/StreamVersionEntity.cs index 517bf80e..f6844bd6 100644 --- a/src/src/AzureStorage/Entities/StreamVersionEntity.cs +++ b/src/src/AzureStorage/Entities/StreamVersionEntity.cs @@ -1,4 +1,4 @@ -using Azure; +using Azure; using Azure.Data.Tables; namespace Purview.EventSourcing.AzureStorage.Entities; @@ -10,7 +10,7 @@ namespace Purview.EventSourcing.AzureStorage.Entities; /// Each aggregate has a single stream-version entity that records its most recently saved version, whether it /// has been deleted, and the aggregate type. It is used to check existence and enforce optimistic concurrency. /// -public sealed class StreamVersionEntity : ITableEntity +public sealed class StreamVersionEntity : ITableEntity, IHasTenant { /// /// Gets or sets a value indicating whether the aggregate has been deleted. @@ -25,7 +25,7 @@ public sealed class StreamVersionEntity : ITableEntity /// /// This is the most recently saved version of the aggregate. /// - public int Version { get; set; } + public long Version { get; set; } /// /// Gets or sets the partition key of the entity, which is the aggregate id. @@ -45,5 +45,10 @@ public sealed class StreamVersionEntity : ITableEntity /// /// Gets or sets the entity tag used for optimistic concurrency. /// + /// + /// The tenant that owns the row; null in a single-tenant deployment. + /// + public string? TenantId { get; set; } + public ETag ETag { get; set; } } diff --git a/src/src/AzureStorage/Exceptions/AggregateAlreadyDeletedException.cs b/src/src/AzureStorage/Exceptions/AggregateAlreadyDeletedException.cs deleted file mode 100644 index 96418455..00000000 --- a/src/src/AzureStorage/Exceptions/AggregateAlreadyDeletedException.cs +++ /dev/null @@ -1,24 +0,0 @@ -namespace Purview.EventSourcing.AzureStorage.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an attempt is made to delete an aggregate that has already been deleted. -/// -/// The id of the aggregate. -/// The idempotency id associated with the delete attempt. -public class AggregateAlreadyDeletedException(string aggregateId, string idempotencyId) - : Exception( - $"An attempt to delete an aggregate (Id: {aggregateId}) that is already deleted was made. {nameof(idempotencyId)}: {idempotencyId}." - ) -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// Gets the id of the aggregate that was already deleted. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// Gets the idempotency id associated with the delete attempt. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/AzureStorage/Exceptions/AggregateDeletedException.cs b/src/src/AzureStorage/Exceptions/AggregateDeletedException.cs deleted file mode 100644 index 25113b39..00000000 --- a/src/src/AzureStorage/Exceptions/AggregateDeletedException.cs +++ /dev/null @@ -1,24 +0,0 @@ -namespace Purview.EventSourcing.AzureStorage.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an attempt is made to save events to an aggregate that has been deleted. -/// -/// The id of the aggregate. -/// The idempotency id associated with the save attempt. -public class AggregateDeletedException(string aggregateId, string idempotencyId) - : Exception( - $"An attempt to save an aggregate that has been deleted, aggregate Id: {aggregateId}, {nameof(IdempotencyId)}: {idempotencyId}." - ) -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// Gets the id of the aggregate that has been deleted. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// Gets the idempotency id associated with the save attempt. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/AzureStorage/Exceptions/AggregateIsDeletedException.cs b/src/src/AzureStorage/Exceptions/AggregateIsDeletedException.cs deleted file mode 100644 index 2585fc72..00000000 --- a/src/src/AzureStorage/Exceptions/AggregateIsDeletedException.cs +++ /dev/null @@ -1,16 +0,0 @@ -namespace Purview.EventSourcing.AzureStorage.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an operation is attempted against an aggregate that has been deleted. -/// -/// The id of the aggregate. -public class AggregateIsDeletedException(string aggregateId) - : Exception($"Invalid operation against an aggregate (Id: {aggregateId}) that has been deleted.") -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// Gets the id of the deleted aggregate. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); -} diff --git a/src/src/AzureStorage/Exceptions/AggregateLockedException.cs b/src/src/AzureStorage/Exceptions/AggregateLockedException.cs deleted file mode 100644 index 9f5985ea..00000000 --- a/src/src/AzureStorage/Exceptions/AggregateLockedException.cs +++ /dev/null @@ -1,18 +0,0 @@ -namespace Purview.EventSourcing.AzureStorage.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an attempt is made to save an aggregate that is currently locked. -/// -/// The idempotency id associated with the save attempt. -public class AggregateLockedException(string idempotencyId) - : Exception( - $"An attempt to save an aggregate that is currently locked was made, {nameof(idempotencyId)}: {idempotencyId}." - ) -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// Gets the idempotency id associated with the save attempt. - /// - public string IdempotencyId { get; set; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/AzureStorage/Exceptions/AggregateNotDeletedException.cs b/src/src/AzureStorage/Exceptions/AggregateNotDeletedException.cs deleted file mode 100644 index a614b606..00000000 --- a/src/src/AzureStorage/Exceptions/AggregateNotDeletedException.cs +++ /dev/null @@ -1,16 +0,0 @@ -namespace Purview.EventSourcing.AzureStorage.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an attempt is made to get an aggregate that is not deleted. -/// -/// The id of the aggregate. -public class AggregateNotDeletedException(string aggregateId) - : Exception($"An attempt to get an aggregate that has not been deleted, aggregate Id: {aggregateId}.") -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// Gets the id of the aggregate that is not deleted. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); -} diff --git a/src/src/AzureStorage/Exceptions/AggregateStreamVersionMissingException.cs b/src/src/AzureStorage/Exceptions/AggregateStreamVersionMissingException.cs deleted file mode 100644 index 9180dcd5..00000000 --- a/src/src/AzureStorage/Exceptions/AggregateStreamVersionMissingException.cs +++ /dev/null @@ -1,24 +0,0 @@ -namespace Purview.EventSourcing.AzureStorage.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an operation requires a stream version that does not exist for the aggregate. -/// -/// The id of the aggregate. -/// The idempotency id associated with the operation. -public class AggregateStreamVersionMissingException(string aggregateId, string idempotencyId) - : Exception( - $"An attempt to delete an aggregate (Id: {aggregateId}) that doesn't a stream version deleted was made. {nameof(idempotencyId)}: {idempotencyId}." - ) -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// Gets the id of the aggregate. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// Gets the idempotency id associated with the operation. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/AzureStorage/Exceptions/AggregatedNotAlreadyDeletedException.cs b/src/src/AzureStorage/Exceptions/AggregatedNotAlreadyDeletedException.cs deleted file mode 100644 index 3acdfdd7..00000000 --- a/src/src/AzureStorage/Exceptions/AggregatedNotAlreadyDeletedException.cs +++ /dev/null @@ -1,24 +0,0 @@ -namespace Purview.EventSourcing.AzureStorage.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an attempt is made to restore an aggregate that is not deleted. -/// -/// The id of the aggregate. -/// The idempotency id associated with the restore attempt. -public class AggregatedNotAlreadyDeletedException(string aggregateId, string idempotencyId) - : Exception( - $"An attempt to restore an aggregate (Id: {aggregateId}) that is not deleted was made.\n\n\tIdempotencyId: {idempotencyId}." - ) -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// Gets the id of the aggregate that is not deleted. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// Gets the idempotency id associated with the restore attempt. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/AzureStorage/Exceptions/CommitException.cs b/src/src/AzureStorage/Exceptions/CommitException.cs deleted file mode 100644 index cb1ad100..00000000 --- a/src/src/AzureStorage/Exceptions/CommitException.cs +++ /dev/null @@ -1,50 +0,0 @@ -namespace Purview.EventSourcing.AzureStorage.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when a batch of events could not be committed to Azure Table Storage. -/// -/// The HTTP status code returned by the storage operation. -/// The id of the aggregate. -/// The idempotency id associated with the commit. -/// The aggregate version that was attempted to be committed. -/// The aggregate version present in the store. -/// The HTTP status message returned by the storage operation. -public class CommitException( - int errorCode, - string aggregateId, - string idempotencyId, - int versionAttempted, - int version, - string httpStatusMessage -) - : Exception( - $"Failed to commit events.\n\tErrorCode: {errorCode} - {httpStatusMessage}\n\tAggregateId: {aggregateId}\n\tIdempotencyId: {idempotencyId}\n\tVersionAttempted: {versionAttempted}\n\tVersionPresent: {version}" - ) -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// Gets the id of the aggregate. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// Gets the aggregate version that was attempted to be committed. - /// - public int VersionAttempted { get; } = versionAttempted; - - /// - /// Gets the idempotency id associated with the commit. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); - - /// - /// Gets the aggregate version present in the store. - /// - public int Version { get; } = version; - - /// - /// Gets the HTTP status message returned by the storage operation. - /// - public string HttpStatusMessage { get; } = httpStatusMessage; -} diff --git a/src/src/AzureStorage/Exceptions/ConcurrencyException.cs b/src/src/AzureStorage/Exceptions/ConcurrencyException.cs deleted file mode 100644 index 1bf3972a..00000000 --- a/src/src/AzureStorage/Exceptions/ConcurrencyException.cs +++ /dev/null @@ -1,37 +0,0 @@ -namespace Purview.EventSourcing.AzureStorage.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an optimistic concurrency check fails while saving an aggregate. -/// -/// The id of the aggregate. -/// The idempotency id associated with the save attempt. -/// The aggregate version that was attempted to be saved. -/// The aggregate version present in the store. -public class ConcurrencyException(string aggregateId, string idempotencyId, int versionAttempted, int version) - : Exception( - $"Optimistic concurrency error:\n\tAggregateId: {aggregateId}\n\tIdempotencyId: {idempotencyId}\n\tVersionAttempted:{versionAttempted}\n\tVersionPresent:{version}" - ), - IConcurrencyConflict -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// Gets the id of the aggregate. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// Gets the aggregate version that was attempted to be saved. - /// - public int VersionAttempted { get; } = versionAttempted; - - /// - /// Gets the idempotency id associated with the save attempt. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); - - /// - /// Gets the aggregate version present in the store. - /// - public int Version { get; } = version; -} diff --git a/src/src/AzureStorage/Exceptions/MissingAggregateIdException.cs b/src/src/AzureStorage/Exceptions/MissingAggregateIdException.cs deleted file mode 100644 index 4a7e4705..00000000 --- a/src/src/AzureStorage/Exceptions/MissingAggregateIdException.cs +++ /dev/null @@ -1,16 +0,0 @@ -namespace Purview.EventSourcing.AzureStorage.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an attempt is made to save an aggregate that does not have an id. -/// -/// The idempotency id associated with the save attempt. -public class MissingAggregateIdException(string idempotencyId) - : Exception($"An attempt to save an aggregate is a missing Id was made, {nameof(idempotencyId)}: {idempotencyId}.") -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// Gets the idempotency id associated with the save attempt. - /// - public string IdempotencyId { get; set; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/AzureStorage/ITableEventStoreTelemetry.cs b/src/src/AzureStorage/ITableEventStoreTelemetry.cs index 9ab90606..4b8ad875 100644 --- a/src/src/AzureStorage/ITableEventStoreTelemetry.cs +++ b/src/src/AzureStorage/ITableEventStoreTelemetry.cs @@ -1,4 +1,4 @@ -using Microsoft.Extensions.Logging; +using Microsoft.Extensions.Logging; using Purview.Telemetry; namespace Purview.EventSourcing.AzureStorage; @@ -41,7 +41,7 @@ public interface ITableEventStoreTelemetry void GetAggregateAtSpecificVersionFailed( string aggregateId, string aggregateTypeFullName, - int specificVersion, + long specificVersion, Exception exception ); @@ -69,7 +69,7 @@ AggregateVersionData versionData /// The requested aggregate version. /// The full name of the aggregate type. [Log(LogLevel.Debug)] - void GetAggregateAtSpecificVersionStart(string aggregateId, int specificVersion, string aggregateTypeFullName); + void GetAggregateAtSpecificVersionStart(string aggregateId, long specificVersion, string aggregateTypeFullName); /// /// Logs that a save was skipped because the aggregate contained no changes. @@ -94,7 +94,7 @@ void SkippedUnknownEvent( string aggregateTypeFullName, string aggregateType, string eventType, - int aggregateVersion + long aggregateVersion ); /// @@ -113,7 +113,7 @@ void CannotApplyEvent( string aggregateType, string eventType, string eventTypeFullName, - int aggregateVersion + long aggregateVersion ); /// @@ -235,7 +235,7 @@ int aggregateVersion void GetAggregateAtSpecificVersionComplete( string aggregateId, string aggregateTypeFullName, - int specificVersion, + long specificVersion, long elapsedMilliseconds ); @@ -339,7 +339,7 @@ string aggregateTypeFullName /// The name of the aggregate type. /// Whether the aggregate is marked as deleted. [Log(LogLevel.Debug)] - void StreamVersionFound(string aggregateId, int streamVersion, string aggregateType, bool isDeleted); + void StreamVersionFound(string aggregateId, long streamVersion, string aggregateType, bool isDeleted); /// /// Logs that reading the stream version entity failed. diff --git a/src/src/AzureStorage/StorageClients/Table/AzureTableClient.cs b/src/src/AzureStorage/StorageClients/Table/AzureTableClient.cs index 368db6e0..8ca213e2 100644 --- a/src/src/AzureStorage/StorageClients/Table/AzureTableClient.cs +++ b/src/src/AzureStorage/StorageClients/Table/AzureTableClient.cs @@ -1,7 +1,9 @@ -using System.ComponentModel; +using System.ComponentModel; using System.Linq.Expressions; using System.Runtime.CompilerServices; using Azure.Data.Tables; +using Purview.EventSourcing.AzureStorage.Entities; +using Purview.EventSourcing.Tenancy; namespace Purview.EventSourcing.AzureStorage.StorageClients.Table; @@ -13,11 +15,49 @@ sealed class AzureTableClient : IAsyncDisposable readonly AzureStorageEventStoreOptions _configuration; readonly string _tableName; + readonly ICurrentTenant _currentTenant; + + /// + /// Narrows an OData filter to the current tenant. + /// + /// + /// Composed here rather than by each caller: a query that forgets the tenant is the failure this + /// exists to prevent. An unowned row is visible only to the system scope: treating it as visible + /// to every tenant would turn a missed stamp into silent cross-tenant exposure. + /// + string? ScopedFilter(string? filter) + { + var scope = _currentTenant.Current; + if (scope.IsSystem) + return filter; + + var tenantFilter = $"TenantId eq '{scope.TenantId!.Replace("'", "''", StringComparison.Ordinal)}'"; + + return string.IsNullOrWhiteSpace(filter) ? tenantFilter : $"({filter}) and {tenantFilter}"; + } + + void Stamp(ITableEntity? entity) + { + if (entity is IHasTenant tenanted) + tenanted.TenantId = _currentTenant.Current.TenantId; + } + + bool IsVisible(ITableEntity? entity) => + _currentTenant.Current.IsSystem + || entity is null + || entity is not IHasTenant tenanted + || string.Equals(tenanted.TenantId, _currentTenant.Current.TenantId, StringComparison.OrdinalIgnoreCase); + static readonly string[] SelectedColumnsForEntityExistsQuery = [nameof(ITableEntity.PartitionKey)]; - public AzureTableClient(AzureStorageEventStoreOptions configuration, string? tableOverride = null) + public AzureTableClient( + AzureStorageEventStoreOptions configuration, + string? tableOverride = null, + ICurrentTenant? currentTenant = null + ) { _configuration = configuration ?? throw new ArgumentNullException(nameof(configuration)); + _currentTenant = currentTenant ?? new SystemCurrentTenant(); _tableName = tableOverride ?? _configuration.Table; _tableClient = new(InitializeAsync); @@ -31,6 +71,7 @@ public AzureTableClient(AzureStorageEventStoreOptions configuration, string? tab where T : class, ITableEntity, new() { ArgumentNullException.ThrowIfNull(entity, nameof(entity)); + Stamp(entity); var table = await _tableClient.GetValueAsync(cancellationToken); Azure.Response response; @@ -78,6 +119,11 @@ public async Task SubmitBatchAsync( if (!batchOperation.Any()) throw new InvalidOperationException("No entities in batch."); + // Stamped once for the whole batch rather than per call site, so a new write path cannot omit + // it; an unstamped row would then be hidden from its own tenant by the read filter. + foreach (var action in batchOperation.GetActions()) + Stamp(action.Entity); + var tableClient = await _tableClient.GetValueAsync(cancellationToken); var sets = batchOperation.GetActions().Chunk(size: MaximumBatchSize); @@ -126,7 +172,7 @@ public async IAsyncEnumerable QueryEnumerableAsync( { var table = await _tableClient.GetValueAsync(cancellationToken); - var results = table.QueryAsync(filter, maxPerPage, fields, cancellationToken); + var results = table.QueryAsync(ScopedFilter(filter), maxPerPage, fields, cancellationToken); string? continuationToken = null; await foreach (var result in results.AsPages(continuationToken, maxPerPage)) { @@ -168,7 +214,7 @@ public async Task> QueryAsync( { var table = await _tableClient.GetValueAsync(cancellationToken); - var results = table.QueryAsync(filter, maxPerPage, fields, cancellationToken); + var results = table.QueryAsync(ScopedFilter(filter), maxPerPage, fields, cancellationToken); await foreach (var result in results.AsPages(continuationToken, maxPerPage)) { return new() { ContinuationToken = result.ContinuationToken, Results = [.. result.Values] }; @@ -202,7 +248,9 @@ public async Task> QueryAsync( ); // The foreach is because it's a paged result set. await foreach (var entity in pagedResults) - return entity; + // A point read is by key, so the tenant cannot be part of the query: another tenant's + // row is filtered out here instead. + return IsVisible(entity) ? entity : null; return null; //return await table.GetEntityAsync(partitionKey, rowKey, fields, cancellationToken); diff --git a/src/src/AzureStorage/StorageClients/Table/BatchOperation.cs b/src/src/AzureStorage/StorageClients/Table/BatchOperation.cs index 286e5908..1b46d5f8 100644 --- a/src/src/AzureStorage/StorageClients/Table/BatchOperation.cs +++ b/src/src/AzureStorage/StorageClients/Table/BatchOperation.cs @@ -50,4 +50,14 @@ public void AddAction(TableTransactionActionType actionType, TEntity en } internal IEnumerable GetActions() => _operations; + + /// + /// Resolves the entity behind a failed transaction action so a caller can classify the failure + /// by the row it collided with. + /// + internal void RecordFailedAction(int? failedActionIndex) => + FailedEntity = + failedActionIndex is int index && index >= 0 && index < _operations.Count + ? _operations[index].Entity + : null; } diff --git a/src/src/AzureStorage/TableEventStore.CreateAsync.cs b/src/src/AzureStorage/TableEventStore.CreateAsync.cs index 7c83e94d..0090328f 100644 --- a/src/src/AzureStorage/TableEventStore.CreateAsync.cs +++ b/src/src/AzureStorage/TableEventStore.CreateAsync.cs @@ -2,6 +2,14 @@ namespace Purview.EventSourcing.AzureStorage; +// The store is a provider facade over Table Storage, Blob Storage, caching, telemetry and the change +// feed, so its coupling is inherent to the role; adopting the result model added the two failure-model +// namespaces and tipped it two types past the limit. +[System.Diagnostics.CodeAnalysis.SuppressMessage( + "Maintainability", + "CA1506:Avoid excessive class coupling", + Justification = "Provider facade; the coupling is the sum of the storage, caching and telemetry surfaces it owns." +)] partial class TableEventStore { /// diff --git a/src/src/AzureStorage/TableEventStore.DeleteAsync.cs b/src/src/AzureStorage/TableEventStore.DeleteAsync.cs index 6aab3d0a..bf780099 100644 --- a/src/src/AzureStorage/TableEventStore.DeleteAsync.cs +++ b/src/src/AzureStorage/TableEventStore.DeleteAsync.cs @@ -3,13 +3,15 @@ using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; using Purview.EventSourcing.AzureStorage.StorageClients.Table; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.AzureStorage; partial class TableEventStore { /// - public async Task DeleteAsync( + public async Task, AggregateDeleteFailure>> DeleteAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -19,12 +21,20 @@ public async Task DeleteAsync( throw NullAggregate(aggregate); if (aggregate.Details.IsDeleted) - throw AggregateIsDeletedException(aggregate.Id()); + { + return AggregateDeleteFailure.Failure>( + new AggregateAlreadyDeleted(aggregate.AggregateType, aggregate.Id()) + ); + } operationContext ??= EventStoreOperationContext.DefaultContext(); if (aggregate.IsNew()) - return false; + { + return AggregateDeleteFailure.Failure>( + new AggregateNotFound(aggregate.AggregateType, aggregate.Id()) + ); + } if (operationContext.PermanentlyDelete) return await PermanentlyDeleteAsync(aggregate, cancellationToken); @@ -48,10 +58,13 @@ public async Task DeleteAsync( new EventRecord(deleteAggregateEvent, metadata) ); - return result.Saved; + return result.IsFailure ? result.Error.ToDeleteFailure() : result.Value; } - async Task PermanentlyDeleteAsync(T aggregate, CancellationToken cancellationToken = default) + async Task, AggregateDeleteFailure>> PermanentlyDeleteAsync( + T aggregate, + CancellationToken cancellationToken = default + ) { if (aggregate == null) throw NullAggregate(aggregate); @@ -59,7 +72,11 @@ async Task PermanentlyDeleteAsync(T aggregate, CancellationToken cancellat var aggregateId = aggregate.Id(); var streamVersion = await GetStreamVersionAsync(aggregateId, true, cancellationToken); if (streamVersion == null) - return false; + { + return AggregateDeleteFailure.Failure>( + new AggregateNotFound(aggregate.AggregateType, aggregateId) + ); + } _eventStoreTelemetry.PermanentDeleteRequested(aggregateId); @@ -104,7 +121,7 @@ async Task PermanentlyDeleteAsync(T aggregate, CancellationToken cancellat aggregate.Details.IsDeleted = true; aggregate.Details.Locked = true; - return true; + return new SaveOutcome(aggregate, SaveOutcomeKind.Written); } #pragma warning disable CA1031 catch (Exception ex) @@ -112,7 +129,7 @@ async Task PermanentlyDeleteAsync(T aggregate, CancellationToken cancellat { _eventStoreTelemetry.PermanentDeleteFailed(aggregateId, ex); - return false; + throw; } finally { diff --git a/src/src/AzureStorage/TableEventStore.ExceptionHelpers.cs b/src/src/AzureStorage/TableEventStore.ExceptionHelpers.cs index 7eadbc87..9917275d 100644 --- a/src/src/AzureStorage/TableEventStore.ExceptionHelpers.cs +++ b/src/src/AzureStorage/TableEventStore.ExceptionHelpers.cs @@ -1,4 +1,5 @@ -using Purview.EventSourcing.AzureStorage.Exceptions; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.AzureStorage; @@ -7,7 +8,12 @@ partial class TableEventStore { static ArgumentNullException NullAggregate(T? aggregate) => new(nameof(aggregate)); - static AggregateIsDeletedException AggregateIsDeletedException(string aggregateId) => new(aggregateId); + Result NotFound(string aggregateId) => + AggregateReadFailure.Failure(new AggregateNotFound(_aggregateTypeShortName, aggregateId)); - static AggregateNotDeletedException AggregateNotDeletedException(string aggregateId) => new(aggregateId); + Result Deleted(string aggregateId) => + AggregateReadFailure.Failure(new AggregateDeleted(_aggregateTypeShortName, aggregateId)); + + Result NotDeleted(string aggregateId) => + AggregateReadFailure.Failure(new AggregateNotDeleted(_aggregateTypeShortName, aggregateId)); } diff --git a/src/src/AzureStorage/TableEventStore.ExistsAsync.cs b/src/src/AzureStorage/TableEventStore.ExistsAsync.cs index ca1f923d..f541cd4c 100644 --- a/src/src/AzureStorage/TableEventStore.ExistsAsync.cs +++ b/src/src/AzureStorage/TableEventStore.ExistsAsync.cs @@ -1,18 +1,18 @@ -namespace Purview.EventSourcing.AzureStorage; +namespace Purview.EventSourcing.AzureStorage; partial class TableEventStore { /// - public async Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) + public async Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) { ArgumentException.ThrowIfNullOrWhiteSpace(aggregateId, nameof(aggregateId)); var streamVersion = await GetStreamVersionAsync(aggregateId, false, cancellationToken); return streamVersion == null - ? ExistsState.DoesNotExist - : new ExistsState + ? AggregateExistence.DoesNotExist + : new AggregateExistence { - Status = streamVersion.IsDeleted ? ExistsStatus.ExistsInDeletedState : ExistsStatus.Exists, + Status = streamVersion.IsDeleted ? ExistenceStatus.ExistsInDeletedState : ExistenceStatus.Exists, Version = streamVersion.Version, }; } diff --git a/src/src/AzureStorage/TableEventStore.GetAsync.cs b/src/src/AzureStorage/TableEventStore.GetAsync.cs index 4101d193..937ea026 100644 --- a/src/src/AzureStorage/TableEventStore.GetAsync.cs +++ b/src/src/AzureStorage/TableEventStore.GetAsync.cs @@ -2,7 +2,9 @@ using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; using Purview.EventSourcing.AzureStorage.Entities; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.Serialization; +using Purview.Results; namespace Purview.EventSourcing.AzureStorage; @@ -10,13 +12,13 @@ partial class TableEventStore { /// [System.Diagnostics.DebuggerStepThrough] - public Task GetAsync( + public Task> GetAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => GetCoreAsync(aggregateId, operationContext, cancellationToken); - async Task GetCoreAsync( + async Task> GetCoreAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -44,9 +46,9 @@ partial class TableEventStore { _eventStoreTelemetry.AggregateRetrievedFromCache(aggregateId, _aggregateTypeFullName); - return ReturnAggregate(aggregate.Details.IsDeleted, aggregateId, operationContext) + return ReturnAggregate(aggregate.Details.IsDeleted, operationContext) ? PrepareAggregateForReturn(aggregate, _aggregateRequirementsManager) - : null; + : Deleted(aggregateId); } // Single-flight: when the aggregate will be written back to the cache, serialize @@ -72,30 +74,30 @@ partial class TableEventStore { _eventStoreTelemetry.AggregateRetrievedFromCache(aggregateId, _aggregateTypeFullName); - return ReturnAggregate(cached.Details.IsDeleted, aggregateId, operationContext) + return ReturnAggregate(cached.Details.IsDeleted, operationContext) ? PrepareAggregateForReturn(cached, _aggregateRequirementsManager) - : null; + : Deleted(aggregateId); } } var streamVersion = await GetStreamVersionAsync(aggregateId, true, cancellationToken); if (streamVersion == null) - return null; + return NotFound(aggregateId); - if (!ReturnAggregate(streamVersion.IsDeleted, aggregateId, operationContext)) - return null; + if (!ReturnAggregate(streamVersion.IsDeleted, operationContext)) + return Deleted(aggregateId); //** THIS ISN'T CORRECT, SO WE'RE PASSING IN NULL TO ENABLE ALL ADDITIONAL EVENTS **// // TODO: It's only odd as in I haven't thought it through completely... - //int? streamVersionIdentifier = streamVersion.Version; + //long? streamVersionIdentifier = streamVersion.Version; //if (streamVersionIdentifier < 1) // // Passing in null for the maxVersion, because we want it to go and find all additional events // // because we don't have a valid version. // streamVersionIdentifier = null; // Passing in null for the maxVersion, because we want it to go and find all additional events - int? streamVersionIdentifier = null; + long? streamVersionIdentifier = null; if (!operationContext.SkipSnapshot) { // If there's no snapshot, then this isn't doing a create (as in brand new @@ -124,6 +126,7 @@ partial class TableEventStore _aggregateTypeFullName, getStopwatch.ElapsedMilliseconds ); + _metrics.GetDuration(getStopwatch.Elapsed.TotalMilliseconds, _aggregateTypeShortName); } async Task IsCacheHitFreshAsync(T aggregate, string aggregateId, CancellationToken cancellationToken) @@ -152,7 +155,7 @@ Services.IAggregateRequirementsManager aggregateRequirementsManager async Task GetAndApplyEventsAsync( T aggregate, StreamVersionEntity streamVersion, - int? maxVersion, + long? maxVersion, CancellationToken cancellationToken ) { diff --git a/src/src/AzureStorage/TableEventStore.GetAtAsync.cs b/src/src/AzureStorage/TableEventStore.GetAtAsync.cs index c57c8e39..28840a13 100644 --- a/src/src/AzureStorage/TableEventStore.GetAtAsync.cs +++ b/src/src/AzureStorage/TableEventStore.GetAtAsync.cs @@ -1,13 +1,15 @@ using System.Diagnostics; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.AzureStorage; partial class TableEventStore { /// - public async Task GetAtAsync( + public async Task> GetAtAsync( string aggregateId, - int version, + long version, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) @@ -22,10 +24,10 @@ partial class TableEventStore { var streamVersion = await GetStreamVersionAsync(aggregateId, true, cancellationToken); if (streamVersion == null) - return null; + return NotFound(aggregateId); - if (!ReturnAggregate(streamVersion.IsDeleted, aggregateId, operationContext)) - return null; + if (!ReturnAggregate(streamVersion.IsDeleted, operationContext)) + return Deleted(aggregateId); T aggregate = new() { Details = { Id = aggregateId } }; diff --git a/src/src/AzureStorage/TableEventStore.GetDeletedAsync.cs b/src/src/AzureStorage/TableEventStore.GetDeletedAsync.cs index 67266625..b816d358 100644 --- a/src/src/AzureStorage/TableEventStore.GetDeletedAsync.cs +++ b/src/src/AzureStorage/TableEventStore.GetDeletedAsync.cs @@ -1,18 +1,26 @@ -namespace Purview.EventSourcing.AzureStorage; +using Purview.EventSourcing.Failures; +using Purview.Results; + +namespace Purview.EventSourcing.AzureStorage; partial class TableEventStore { /// - public async Task GetDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) + public async Task> GetDeletedAsync( + string aggregateId, + CancellationToken cancellationToken = default + ) { - var aggregate = await GetCoreAsync( + var result = await GetCoreAsync( aggregateId, new() { SnapshotCacheMode = SnapshotCachingOptions.None, DeleteMode = DeleteHandlingMode.ReturnsAggregate }, cancellationToken ); + if (result.IsFailure) + return result; + + var aggregate = result.Value; - return aggregate == null ? null - : aggregate.Details.IsDeleted ? FulfilRequirements(aggregate) - : throw AggregateNotDeletedException(aggregateId); + return aggregate.Details.IsDeleted ? FulfilRequirements(aggregate) : NotDeleted(aggregateId); } } diff --git a/src/src/AzureStorage/TableEventStore.GetEventRangeAsync.cs b/src/src/AzureStorage/TableEventStore.GetEventRangeAsync.cs index cc7476c3..28b8dfc0 100644 --- a/src/src/AzureStorage/TableEventStore.GetEventRangeAsync.cs +++ b/src/src/AzureStorage/TableEventStore.GetEventRangeAsync.cs @@ -11,8 +11,8 @@ partial class TableEventStore /// public async IAsyncEnumerable<(EventRecord EventRecord, string EventType)> GetEventRangeAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, [EnumeratorCancellation] CancellationToken cancellationToken ) { @@ -45,8 +45,8 @@ [EnumeratorCancellation] CancellationToken cancellationToken internal async IAsyncEnumerable GetEventRangeEntitiesAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, [EnumeratorCancellation] CancellationToken cancellationToken ) { @@ -60,13 +60,13 @@ [EnumeratorCancellation] CancellationToken cancellationToken async Task DeserializeEventAsync( EventEntity eventEntity, - int aggregateVersion, + long aggregateVersion, CancellationToken cancellationToken ) { cancellationToken.ThrowIfCancellationRequested(); - static UnknownEvent ReturnUnknownEvent(EventEntity eventEntity, int aggregateVersion) => + static UnknownEvent ReturnUnknownEvent(EventEntity eventEntity, long aggregateVersion) => new() { SchemaVersion = eventEntity.SchemaVersion, @@ -166,6 +166,31 @@ static UnknownEvent ReturnUnknownEvent(EventEntity eventEntity, int aggregateVer using (eventStream) { + // The blob holds the same envelope as the table would, so an oversized event is + // erased by the same key and must be unprotected the same way. + if (_payloadProtector is not null) + { + using StreamReader reader = new(eventStream); + var blobPayload = await reader.ReadToEndAsync(cancellationToken); + if (_payloadProtector.IsProtected(blobPayload)) + { + var unprotectedBlob = await _payloadProtector.UnprotectAsync( + blobPayload, + cancellationToken + ); + if (unprotectedBlob is null) + return new EventRecord(ReturnUnknownEvent(eventEntity, aggregateVersion), metadata); + + var protectedEvent = DeserializeEvent(unprotectedBlob, blobEventType); + + return protectedEvent == null ? null : new EventRecord(protectedEvent, metadata); + } + + var plainEvent = DeserializeEvent(blobPayload, blobEventType); + + return plainEvent == null ? null : new EventRecord(plainEvent, metadata); + } + var blobEvent = await DeserializeEventAsync(eventStream, blobEventType, cancellationToken); if (blobEvent == null) return null; diff --git a/src/src/AzureStorage/TableEventStore.GetOrCreateAsync.cs b/src/src/AzureStorage/TableEventStore.GetOrCreateAsync.cs index 5722742b..67979bb7 100644 --- a/src/src/AzureStorage/TableEventStore.GetOrCreateAsync.cs +++ b/src/src/AzureStorage/TableEventStore.GetOrCreateAsync.cs @@ -1,9 +1,12 @@ -namespace Purview.EventSourcing.AzureStorage; +using Purview.EventSourcing.Failures; +using Purview.Results; + +namespace Purview.EventSourcing.AzureStorage; partial class TableEventStore { /// - public async Task GetOrCreateAsync( + public async Task> GetOrCreateAsync( string? aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -11,8 +14,8 @@ partial class TableEventStore { if (!string.IsNullOrWhiteSpace(aggregateId)) { - var exists = await ExistsAsync(aggregateId, cancellationToken); - if (exists) + var existence = await ExistsAsync(aggregateId, cancellationToken); + if (existence.DoesExist) return await GetAsync(aggregateId, operationContext, cancellationToken); //return null; diff --git a/src/src/AzureStorage/TableEventStore.IsDeletedAsync.cs b/src/src/AzureStorage/TableEventStore.IsDeletedAsync.cs deleted file mode 100644 index 9396e8e5..00000000 --- a/src/src/AzureStorage/TableEventStore.IsDeletedAsync.cs +++ /dev/null @@ -1,15 +0,0 @@ -namespace Purview.EventSourcing.AzureStorage; - -partial class TableEventStore -{ - /// - public async Task IsDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) - { - ArgumentException.ThrowIfNullOrWhiteSpace(aggregateId, nameof(aggregateId)); - - var streamVersion = await GetStreamVersionAsync(aggregateId, true, cancellationToken); - return streamVersion == null - ? throw new NullReferenceException($"The aggregate specified ({aggregateId}) does not exist.") - : streamVersion.IsDeleted; - } -} diff --git a/src/src/AzureStorage/TableEventStore.RestoreAsync.cs b/src/src/AzureStorage/TableEventStore.RestoreAsync.cs index c3a9c096..77c7757e 100644 --- a/src/src/AzureStorage/TableEventStore.RestoreAsync.cs +++ b/src/src/AzureStorage/TableEventStore.RestoreAsync.cs @@ -1,12 +1,14 @@ using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.AzureStorage; partial class TableEventStore { /// - public async Task RestoreAsync( + public async Task, AggregateRestoreFailure>> RestoreAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -16,7 +18,11 @@ public async Task RestoreAsync( throw NullAggregate(aggregate); if (!aggregate.Details.IsDeleted) - throw AggregateNotDeletedException(aggregate.Id()); + { + return AggregateRestoreFailure.Failure>( + new AggregateNotDeleted(aggregate.AggregateType, aggregate.Id()) + ); + } operationContext ??= EventStoreOperationContext.DefaultContext(); @@ -33,7 +39,11 @@ public async Task RestoreAsync( aggregate.ApplyEvent(restoreAggregateEvent, metadata); if (aggregate.IsNew()) - return false; + { + return AggregateRestoreFailure.Failure>( + new AggregateNotFound(aggregate.AggregateType, aggregate.Id()) + ); + } var result = await _saveOperation.SaveCoreAsync( aggregate, @@ -41,6 +51,6 @@ public async Task RestoreAsync( cancellationToken, new EventRecord(restoreAggregateEvent, metadata) ); - return result.Saved; + return result.IsFailure ? result.Error.ToRestoreFailure() : result.Value; } } diff --git a/src/src/AzureStorage/TableEventStore.SaveAsync.cs b/src/src/AzureStorage/TableEventStore.SaveAsync.cs index 50d9199d..d83c982f 100644 --- a/src/src/AzureStorage/TableEventStore.SaveAsync.cs +++ b/src/src/AzureStorage/TableEventStore.SaveAsync.cs @@ -1,6 +1,8 @@ using System.Diagnostics; using System.Diagnostics.CodeAnalysis; using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.AzureStorage; @@ -8,7 +10,7 @@ partial class TableEventStore { /// [DebuggerStepThrough] - public Task> SaveAsync( + public Task, AggregateSaveFailure>> SaveAsync( [NotNull] T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default diff --git a/src/src/AzureStorage/TableEventStore.SaveOperation.cs b/src/src/AzureStorage/TableEventStore.SaveOperation.cs index fc010e5c..67c9ed19 100644 --- a/src/src/AzureStorage/TableEventStore.SaveOperation.cs +++ b/src/src/AzureStorage/TableEventStore.SaveOperation.cs @@ -1,4 +1,9 @@ +using System.Diagnostics; +using System.Diagnostics.CodeAnalysis; +using System.Net; +using System.Text; using Azure; +using Azure.Data.Tables; using Microsoft.Extensions.Options; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; @@ -7,15 +12,12 @@ using Purview.EventSourcing.AzureStorage.Events; using Purview.EventSourcing.AzureStorage.StorageClients.Blob; using Purview.EventSourcing.AzureStorage.StorageClients.Table; +using Purview.EventSourcing.Cryptography; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.Serialization; using Purview.EventSourcing.Services; -using Purview.EventSourcing.Storage; using Purview.EventSourcing.Validation; -using System.Diagnostics; -using System.Diagnostics.CodeAnalysis; -using System.Net; -using System.Security.Claims; -using System.Text; +using Purview.Results; namespace Purview.EventSourcing.AzureStorage; @@ -30,7 +32,10 @@ sealed class TableSaveOperation( ITableEventStoreTelemetry eventStoreTelemetry, string aggregateTypeFullName, ISnapshotStrategy snapshotStrategy, - ISnapshotStrategySelector? snapshotStrategySelector + ISnapshotStrategySelector? snapshotStrategySelector, + IEventStorePrincipalAccessor principalAccessor, + IEventStoreMetrics metrics, + IEventPayloadProtector? payloadProtector ) where T : class, IAggregate, new() { @@ -38,23 +43,25 @@ sealed class TableSaveOperation( const int MaxEventSize = 32000; [DebuggerStepThrough] - public Task> SaveAsync( + public Task, AggregateSaveFailure>> SaveAsync( [NotNull] T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => SaveCoreAsync(aggregate, operationContext, cancellationToken); - internal async Task> SaveCoreAsync( + internal async Task, AggregateSaveFailure>> SaveCoreAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken, params EventRecord[] additionalEvents ) { + var saveStopwatch = System.Diagnostics.Stopwatch.StartNew(); var (saveResult, preparedAggregate, preparedOperationContext, idempotencyId, changeEvents, isNew, marker) = await PrepareSaveAsync(aggregate, operationContext, additionalEvents, cancellationToken); - return saveResult + var result = + saveResult ?? await PersistAndNotifyAsync( preparedAggregate, preparedOperationContext, @@ -64,10 +71,19 @@ params EventRecord[] additionalEvents marker!, cancellationToken ); + + saveStopwatch.Stop(); + metrics.RecordSave(saveStopwatch.Elapsed.TotalMilliseconds, store.AggregateTypeShortName, result); + + // Only a write actually appended events; a no-op or an idempotent replay appended none. + if (result.IsSuccess && result.Value.Kind is SaveOutcomeKind.Written) + metrics.EventsAppended(changeEvents.Length, store.AggregateTypeShortName); + + return result; } async Task<( - SaveResult? Terminal, + Result, AggregateSaveFailure>? Terminal, T Aggregate, EventStoreOperationContext OperationContext, string IdempotencyId, @@ -90,7 +106,7 @@ CancellationToken cancellationToken if (!validationResult.IsValid) return ( - SaveResultBuilder.Create(aggregate, false, false, validationResult), + AggregateSaveFailure.Failure>(new AggregateInvalid(validationResult)), aggregate, operationContext, idempotencyId, @@ -101,17 +117,17 @@ CancellationToken cancellationToken if (aggregate.Details.Locked) { - return operationContext.LockMode is LockHandlingMode.ThrowsException - ? throw new Exceptions.AggregateLockedException(idempotencyId) - : ( - SaveResultBuilder.Create(aggregate, false, false), - aggregate, - operationContext, - idempotencyId, - [], - false, - null - ); + return ( + AggregateSaveFailure.Failure>( + new AggregateLocked(aggregate.AggregateType, aggregate.Id()) + ), + aggregate, + operationContext, + idempotencyId, + [], + false, + null + ); } if (string.IsNullOrWhiteSpace(aggregate.Details.Id)) @@ -123,7 +139,7 @@ CancellationToken cancellationToken eventStoreTelemetry.SaveContainedNoChanges(aggregate.Id(), aggregateTypeFullName, aggregate.AggregateType); return ( - SaveResultBuilder.Create(aggregate, false, true), + new SaveOutcome(aggregate, SaveOutcomeKind.NoChanges), aggregate, operationContext, idempotencyId, @@ -153,7 +169,7 @@ CancellationToken cancellationToken { eventStoreTelemetry.EventsAlreadyApplied(aggregate.Id(), idempotencyId); return ( - SaveResultBuilder.Create(aggregate, true, true), + new SaveOutcome(aggregate, SaveOutcomeKind.AlreadyApplied), aggregate, operationContext, idempotencyId, @@ -172,7 +188,7 @@ CancellationToken cancellationToken "CA1502:Avoid excessive complexity", Justification = "Save orchestration handles many interleaved states; keep the flow readable." )] - async Task> PersistAndNotifyAsync( + async Task, AggregateSaveFailure>> PersistAndNotifyAsync( T aggregate, EventStoreOperationContext operationContext, string idempotencyId, @@ -192,11 +208,11 @@ CancellationToken cancellationToken var streamEntity = await store.GetStreamVersionAsync(aggregate.Id(), !isNew, cancellationToken); var hasStreamEntity = streamEntity != null; - if (streamEntity?.IsDeleted == true) + if (streamEntity?.IsDeleted == true && !changeEvents.Any(record => record.Event is Restored)) { - var throwIfDeleted = !changeEvents.Any(record => record.Event is Restored); - if (throwIfDeleted) - throw new Exceptions.AggregateDeletedException(aggregate.Id(), idempotencyId); + return AggregateSaveFailure.Failure>( + new AggregateDeleted(aggregate.AggregateType, aggregate.Id()) + ); } try @@ -219,7 +235,7 @@ CancellationToken cancellationToken else batchOperation.Update(streamEntity, merge: false); - var userId = ClaimsPrincipal.Current?.FindFirst(operationContext.ClaimIdentifier)?.Value; + var userId = principalAccessor.GetPrincipal()?.FindFirst(operationContext.ClaimIdentifier)?.Value; if (operationContext.RequiresValidPrincipalIdentifier && string.IsNullOrWhiteSpace(userId)) throw new NullReferenceException( $"Missing ClaimsPrincipal identifier '{operationContext.ClaimIdentifier}'. Unable to save aggregate." @@ -238,13 +254,14 @@ CancellationToken cancellationToken CorrelationId = changeEvents[i].Metadata.CorrelationId ?? operationContext.CorrelationId, }; - AppendEventToBatch( + await AppendEventToBatchAsync( changeEvent, metadata, aggregate, idempotencyMarkerOperation, batchOperation, - largeChangeEvents + largeChangeEvents, + cancellationToken ); } @@ -314,22 +331,39 @@ await aggregateChangeNotifier.AfterSaveAsync( await aggregateChangeNotifier.FailureAsync(aggregate, deleteRequested, ex, cancellationToken); } + if (ex is Exceptions.ConcurrencyException conflict) + { + return AggregateSaveFailure.Failure>( + new ConcurrencyConflict( + aggregate.AggregateType, + aggregate.Id(), + conflict.VersionAttempted, + conflict.Version + ) + ); + } + throw; } - return SaveResultBuilder.Create(aggregate, true, false); + return new SaveOutcome(aggregate, SaveOutcomeKind.Written); } - void AppendEventToBatch( + async Task AppendEventToBatchAsync( object changeEvent, EventMetadata metadata, T aggregate, IdempotencyMarkerEntity idempotencyMarkerOperation, BatchOperation batchOperation, - Dictionary largeChangeEvents + Dictionary largeChangeEvents, + CancellationToken cancellationToken ) { - var serializedEvent = TableEventStore.SerializeEvent(changeEvent); + var serializedEvent = await ProtectIfRequiredAsync( + changeEvent, + TableEventStore.SerializeEvent(changeEvent), + cancellationToken + ); var eventEntity = CreateSerializedEvent( aggregate.Id(), changeEvent, @@ -388,6 +422,10 @@ CancellationToken cancellationToken { eventStoreTelemetry.SaveFailedAtStorage(aggregate.Id(), aggregateTypeFullName, ex.Status, ex); + // Only a transaction failure identifies which action collided, and the classification + // below is meaningless without it. + batchOperation.RecordFailedAction((ex as TableTransactionFailedException)?.FailedTransactionActionIndex); + var statusCode = (HttpStatusCode)ex.Status; store.ClearCacheFireAndForget(aggregate); @@ -414,19 +452,17 @@ CancellationToken cancellationToken // Idempotency marker already exists, that means transaction with this idempotencyId already succeeded, so we don't care anymore return; - if ( - errorEntity.RowKey.Equals( - TableEventStoreConstants.StreamVersionRowKey, - StringComparison.Ordinal - ) - ) - // Stream version Etag check or initial insert has failed, so somebody modified aggregate before us and whole transaction has to be retried. - throw new Exceptions.ConcurrencyException( - aggregate.Id(), - idempotencyId, - aggregate.Details.CurrentVersion, - aggregate.Details.SavedVersion - ); + // Either the stream-version row lost its ETag check, or an event row already + // exists for this version. Event rows are keyed by aggregate version, so a + // collision means another writer already persisted it - both are the same + // concurrency conflict, and reporting the second as a commit failure would + // present a retryable race as an infrastructure fault. + throw new Exceptions.ConcurrencyException( + aggregate.Id(), + idempotencyId, + aggregate.Details.CurrentVersion, + aggregate.Details.SavedVersion + ); } } @@ -499,7 +535,11 @@ CancellationToken cancellationToken { var largeEvent = largeChangeEvents[i]; var blobName = store.GenerateEventBlobName(aggregateId, largeEvent.Key); - var largeEventContent = TableEventStore.SerializeEvent(largeEvent.Value); + var largeEventContent = await ProtectIfRequiredAsync( + largeEvent.Value, + TableEventStore.SerializeEvent(largeEvent.Value), + cancellationToken + ); using MemoryStream stream = new(); using (StreamWriter writer = new(stream, Encoding.UTF8, SerializationBufferSize, true)) await writer.WriteAsync(largeEventContent); @@ -562,6 +602,13 @@ static string GenerateIdempotencyId(string idempotencyId, EventRecord[] changeEv bool ShouldSnapShot(T aggregate, EventRecord[] events, EventStoreOperationContext? operationContext) { + // A snapshot serializes aggregate state, which holds the same personal data as the protected + // events in clear - and one snapshot can span many subjects, so no single key can protect it. + // With protection enabled the store does not snapshot at all: a snapshot surviving key erasure + // would make crypto-shredding untrue. Replay from events stays correct, only slower. + if (payloadProtector is not null) + return false; + if (aggregate.Details.IsDeleted || events.Any(record => record.Event is Restored)) return true; @@ -584,4 +631,16 @@ async Task GuardAsync(T aggregate, CancellationToken cancellat ? await DefaultAggregateValidator.Instance.ValidateAsync(aggregate, cancellationToken) : await validator.ValidateAsync(aggregate, cancellationToken); } + + /// + /// Encrypts a serialized payload when its event names a data subject. + /// + /// + /// Applied to both the table payload and the blob used for oversized events, so routing an event to + /// blob storage does not quietly store it in clear. + /// + Task ProtectIfRequiredAsync(object changeEvent, string serialized, CancellationToken cancellationToken) => + payloadProtector is not null && changeEvent is IEventDataSubject dataSubject + ? payloadProtector.ProtectAsync(serialized, dataSubject.DataSubjectId, cancellationToken) + : Task.FromResult(serialized); } diff --git a/src/src/AzureStorage/TableEventStore.cs b/src/src/AzureStorage/TableEventStore.cs index 07252819..aa678002 100644 --- a/src/src/AzureStorage/TableEventStore.cs +++ b/src/src/AzureStorage/TableEventStore.cs @@ -8,7 +8,9 @@ using Purview.EventSourcing.Aggregates.Events.Upcasting; using Purview.EventSourcing.Aggregates.Snapshotting; using Purview.EventSourcing.AzureStorage.Entities; +using Purview.EventSourcing.Cryptography; using Purview.EventSourcing.Services; +using Purview.EventSourcing.Tenancy; using Purview.EventSourcing.Validation; namespace Purview.EventSourcing.AzureStorage; @@ -47,8 +49,19 @@ public sealed partial class TableEventStore : ITableEventStore, IAsyncDisp readonly ISnapshotStrategySelector? _snapshotStrategySelector; readonly IEventUpcasterRegistry? _eventUpcasterRegistry; + readonly IEventStorePrincipalAccessor _principalAccessor; + + readonly IEventStoreMetrics _metrics; + + readonly ICurrentTenant _currentTenant; + + readonly IEventPayloadProtector? _payloadProtector; + readonly string _aggregateTypeFullName; readonly string _aggregateTypeShortName; + + // Exposed so the save operation tags metrics with the same value every other provider uses. + internal string AggregateTypeShortName => _aggregateTypeShortName; readonly TableSaveOperation _saveOperation; static readonly ConcurrentDictionary EventTypeCache = new(StringComparer.Ordinal); @@ -68,6 +81,10 @@ public sealed partial class TableEventStore : ITableEventStore, IAsyncDisp /// Optional, the strategy that decides when a snapshot should be written. /// Optional, the selector used to pick a snapshot strategy. /// Optional, the registry used to upcast persisted events during replay. + /// Optional accessor supplying the principal recorded against saved events. + /// Optional metrics recorder; defaults to a no-op. + /// Optional tenant scope. This provider does not enforce tenant isolation and refuses a tenant-scoped operation. + /// Optional payload protector; when omitted payloads are stored unencrypted. /// is . public TableEventStore( IAggregateEventNameMapper eventNameMapper, @@ -81,7 +98,11 @@ public TableEventStore( IAggregateIdFactory? aggregateIdFactory = null, ISnapshotStrategy? snapshotStrategy = null, ISnapshotStrategySelector? snapshotStrategySelector = null, - IEventUpcasterRegistry? eventUpcasterRegistry = null + IEventUpcasterRegistry? eventUpcasterRegistry = null, + IEventStorePrincipalAccessor? principalAccessor = null, + IEventStoreMetrics? metrics = null, + ICurrentTenant? currentTenant = null, + IEventPayloadProtector? payloadProtector = null ) { _eventNameMapper = eventNameMapper; @@ -95,13 +116,17 @@ public TableEventStore( _snapshotStrategy = snapshotStrategy ?? new IntervalSnapshotStrategy(); _snapshotStrategySelector = snapshotStrategySelector; _eventUpcasterRegistry = eventUpcasterRegistry; + _principalAccessor = principalAccessor ?? new AmbientEventStorePrincipalAccessor(); + _metrics = metrics ?? NoOpEventStoreMetrics.Instance; + _currentTenant = currentTenant ?? new SystemCurrentTenant(); + _payloadProtector = payloadProtector; var name = typeof(T).Name; TableName = nameBuilder?.GetTableName() ?? $"{azureStorageOptions.Value.Table}{name}"; ContainerName = nameBuilder?.GetBlobContainerName() ?? azureStorageOptions.Value.Container; - _tableClient = new(azureStorageOptions.Value, TableName); + _tableClient = new(azureStorageOptions.Value, TableName, _currentTenant); _blobClient = new(azureStorageOptions.Value, ContainerName); _aggregateTypeShortName = typeof(T).Name; @@ -123,7 +148,10 @@ public TableEventStore( _eventStoreTelemetry, _aggregateTypeFullName, _snapshotStrategy, - _snapshotStrategySelector + _snapshotStrategySelector, + _principalAccessor, + _metrics, + _payloadProtector ); } @@ -274,25 +302,10 @@ internal void ClearCacheFireAndForget(T aggregate) }); } - static bool ReturnAggregate(bool isDeleted, string aggregateId, EventStoreOperationContext context) - { - if (isDeleted) - { -#pragma warning disable IDE0010 // Add missing cases - switch (context.DeleteMode) - { - case DeleteHandlingMode.ThrowsException: - throw AggregateIsDeletedException(aggregateId); - case DeleteHandlingMode.ReturnsNull: - return false; - } -#pragma warning restore IDE0010 // Add missing cases - } - - return true; - } + static bool ReturnAggregate(bool isDeleted, EventStoreOperationContext context) => + !isDeleted || context.DeleteMode == DeleteHandlingMode.ReturnsAggregate; - internal string CreateEventRowKey(int version) => + internal string CreateEventRowKey(long version) => $"{_eventStoreOptions.Value.EventPrefix}_{$"{version}".PadLeft(_eventStoreOptions.Value.EventSuffixLength, '0')}"; internal static string CreateIdempotencyCheckRowKey(string idempotencyId) => @@ -344,7 +357,18 @@ public string GenerateSnapshotBlobPath(string aggregateId) => /// /// is null, empty, or white space. public string CreateCacheKey(string aggregateId) => - $"{_aggregateTypeShortName}:{aggregateId}{AggregateSnapshotSchema.GetStorageSuffix()}".ToLowerInvariant(); + $"{TenantCacheScope()}{_aggregateTypeShortName}:{aggregateId}{AggregateSnapshotSchema.GetStorageSuffix()}".ToLowerInvariant(); + + /// + /// Namespaces a cache key by tenant. + /// + /// + /// The distributed cache is read before the tenant-filtered storage lookup, so an unqualified key + /// would let one tenant read another's cached aggregate straight out of a shared cache, bypassing + /// every storage filter. The system scope keeps the unqualified key, matching unowned rows. + /// + /// The tenant prefix, or an empty string under the system scope. + string TenantCacheScope() => _currentTenant.Current.IsSystem ? string.Empty : $"{_currentTenant.Current.TenantId}:"; #pragma warning restore CA1308 // Normalize strings to uppercase /// diff --git a/src/src/Benchmarks/BenchmarkPolicies.cs b/src/src/Benchmarks/BenchmarkPolicies.cs index 913d07b0..604de291 100644 --- a/src/src/Benchmarks/BenchmarkPolicies.cs +++ b/src/src/Benchmarks/BenchmarkPolicies.cs @@ -18,8 +18,6 @@ static class BenchmarkPolicies new BenchmarkRatioPolicy("AggregateSimple", "WarmRerun", "ColdGeneration", 0.40), new BenchmarkRatioPolicy("AggregateWithValueObjects", "WarmRerun", "ColdGeneration", 0.40), new BenchmarkRatioPolicy("AggregateMulti", "WarmRerun", "ColdGeneration", 0.40), - new BenchmarkRatioPolicy("ScalarValueObject", "WarmRerun", "ColdGeneration", 0.40), - new BenchmarkRatioPolicy("ComplexValueObject", "WarmRerun", "ColdGeneration", 0.40), new BenchmarkRatioPolicy("AggregateMulti", "SingleAggregateEdit", "ColdGeneration", 1.50), ], }; diff --git a/src/src/Benchmarks/BenchmarkRun.cs b/src/src/Benchmarks/BenchmarkRun.cs index 29f9cba7..a5e36409 100644 --- a/src/src/Benchmarks/BenchmarkRun.cs +++ b/src/src/Benchmarks/BenchmarkRun.cs @@ -18,7 +18,9 @@ sealed class BenchmarkSuiteRun public List Warnings { get; set; } = []; - public bool Passed => Failures.Count == 0; + // A suite that measured nothing is a failure, not a pass. Every benchmark in a suite can error during + // setup and BenchmarkDotNet still exits cleanly, which previously reported a green run from no data. + public bool Passed => Failures.Count == 0 && Cases.Count > 0; public IEnumerable FormatSummary() { @@ -32,6 +34,9 @@ public IEnumerable FormatSummary() foreach (var caseRecord in Cases) yield return caseRecord.Format(); + if (Cases.Count == 0) + yield return " FAILURE: the suite executed no benchmarks; every case errored or none was discovered."; + if (Failures.Count > 0) { yield return string.Empty; diff --git a/src/src/Benchmarks/BenchmarkRunExporter.cs b/src/src/Benchmarks/BenchmarkRunExporter.cs index 1b7a25e7..55342bef 100644 --- a/src/src/Benchmarks/BenchmarkRunExporter.cs +++ b/src/src/Benchmarks/BenchmarkRunExporter.cs @@ -100,8 +100,10 @@ static void ApplyRatioPolicies(BenchmarkSuiteRun run, BenchmarkSuitePolicy polic if (denominator is null || numerator is null) { - run.Warnings.Add( - $"Ratio check '{ratioPolicy.NumeratorBenchmark}/{ratioPolicy.DenominatorBenchmark}' for '{ratioPolicy.ScenarioPattern}' could not be evaluated (missing case)." + // A policy naming a scenario the suite does not run is a configuration bug: the guarantee it + // describes is silently unchecked, which is worse than having no policy at all. + run.Failures.Add( + $"Ratio check '{ratioPolicy.NumeratorBenchmark}/{ratioPolicy.DenominatorBenchmark}' for '{ratioPolicy.ScenarioPattern}' could not be evaluated: no such case." ); continue; } @@ -119,6 +121,9 @@ static void ApplyRatioPolicies(BenchmarkSuiteRun run, BenchmarkSuitePolicy polic } } + // Means below this are dominated by measurement noise rather than by the code under test. + const double MinimumComparableMeanMilliseconds = 0.01; + static void ApplyPreviousComparison(BenchmarkSuiteRun run, BenchmarkSuitePolicy policy) { var previousRun = new BenchmarkHistoryStore(run.Mode).TryLoadLatest(); @@ -139,14 +144,22 @@ static void ApplyPreviousComparison(BenchmarkSuiteRun run, BenchmarkSuitePolicy if (policy.DefaultMaxMeanRegressionPercent is double maxMeanPercent) { - if (previous.MeanMilliseconds > 0) + // Below this, run-to-run jitter dwarfs any real change: a 1µs benchmark moving by a few + // hundred nanoseconds is a 50% "regression" that means nothing. + if (previous.MeanMilliseconds < MinimumComparableMeanMilliseconds) + { + run.Warnings.Add( + $"[{caseRecord.Name}] mean of {previous.MeanMilliseconds:G3}ms is below the {MinimumComparableMeanMilliseconds:G3}ms comparison floor; regression check skipped." + ); + } + else { var regression = (caseRecord.MeanMilliseconds - previous.MeanMilliseconds) / previous.MeanMilliseconds; if (regression > maxMeanPercent / 100d) { run.Failures.Add( - $"[{caseRecord.Name}] mean regressed by {regression:P0} vs previous run ({previous.MeanMilliseconds:F2}ms -> {caseRecord.MeanMilliseconds:F2}ms), exceeding the {maxMeanPercent:P0} threshold." + $"[{caseRecord.Name}] mean regressed by {regression:P0} vs previous run ({previous.MeanMilliseconds:G3}ms -> {caseRecord.MeanMilliseconds:G3}ms), exceeding the {maxMeanPercent:N0}% threshold." ); } } @@ -164,7 +177,7 @@ policy.DefaultMaxAllocationRegressionPercent is double maxAllocationPercent if (regression > maxAllocationPercent / 100d) { run.Failures.Add( - $"[{caseRecord.Name}] allocations regressed by {regression:P0} vs previous run ({previousAllocation:N0}B -> {currentAllocation:N0}B), exceeding the {maxAllocationPercent:P0} threshold." + $"[{caseRecord.Name}] allocations regressed by {regression:P0} vs previous run ({previousAllocation:N0}B -> {currentAllocation:N0}B), exceeding the {maxAllocationPercent:N0}% threshold." ); } } diff --git a/src/src/Benchmarks/Benchmarks.csproj b/src/src/Benchmarks/Benchmarks.csproj index 48e861cd..d561265f 100644 --- a/src/src/Benchmarks/Benchmarks.csproj +++ b/src/src/Benchmarks/Benchmarks.csproj @@ -1,6 +1,6 @@ - net10.0 + net11.0 enable enable Purview.EventSourcing.Benchmarks diff --git a/src/src/Benchmarks/InMemoryPerformanceBenchmarks.cs b/src/src/Benchmarks/InMemoryPerformanceBenchmarks.cs index 0391d9b0..fdd8da24 100644 --- a/src/src/Benchmarks/InMemoryPerformanceBenchmarks.cs +++ b/src/src/Benchmarks/InMemoryPerformanceBenchmarks.cs @@ -74,13 +74,19 @@ public OrderAggregate SaveNewAggregate() public async Task GetCachedAggregate() { var id = _seededIds[_getIndex++ % _seededIds.Length]; - return await _store.GetAsync(id, null); + var result = await _store.GetAsync(id, null); + + return result.IsSuccess ? result.Value : null; } [Benchmark] [BenchmarkCategory("InMemoryStore")] - public async Task ReplayLargeStream() => - await _store.GetAtAsync(_largeAggregateId, int.MaxValue, null); + public async Task ReplayLargeStream() + { + var result = await _store.GetAtAsync(_largeAggregateId, int.MaxValue, null); + + return result.IsSuccess ? result.Value : null; + } [GlobalCleanup] public void GlobalCleanup() => Dispose(); @@ -112,7 +118,7 @@ public Task BeforeDeleteAsync(TAggregate aggregate, CancellationToken cancellati public Task AfterSaveAsync( TAggregate aggregate, - int previousSavedVersion, + long previousSavedVersion, bool isNew, EventRecord[] events, CancellationToken cancellationToken = default diff --git a/src/src/Benchmarks/SourceGenerator/SourceGeneratorPerformanceScenarios.cs b/src/src/Benchmarks/SourceGenerator/SourceGeneratorPerformanceScenarios.cs index 9a8c734f..3eee166d 100644 --- a/src/src/Benchmarks/SourceGenerator/SourceGeneratorPerformanceScenarios.cs +++ b/src/src/Benchmarks/SourceGenerator/SourceGeneratorPerformanceScenarios.cs @@ -57,7 +57,7 @@ public sealed class AggregateAttribute : System.Attribute [System.AttributeUsage(System.AttributeTargets.Method, AllowMultiple = false, Inherited = false)] public sealed class EventAttribute : System.Attribute { - public int Version { get; set; } = 1; + public long Version { get; set; } = 1; public string? EventName { get; set; } public string? EventNamespace { get; set; } } @@ -94,7 +94,7 @@ namespace Purview.EventSourcing.Aggregates.Events public sealed class EventContractAttribute : System.Attribute { } public readonly record struct EventMetadata( - int AggregateVersion, + long AggregateVersion, System.DateTimeOffset When, int SchemaVersion, string? IdempotencyId, diff --git a/src/src/Benchmarks/SqlServer/SqlServerPerformanceBenchmarks.cs b/src/src/Benchmarks/SqlServer/SqlServerPerformanceBenchmarks.cs index 257c7054..673d07fb 100644 --- a/src/src/Benchmarks/SqlServer/SqlServerPerformanceBenchmarks.cs +++ b/src/src/Benchmarks/SqlServer/SqlServerPerformanceBenchmarks.cs @@ -2,6 +2,7 @@ using BenchmarkDotNet.Attributes; using Microsoft.Extensions.Caching.Distributed; using Microsoft.Extensions.Options; +using Purview.Containers.MsSql; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Persistence; using Purview.EventSourcing.Aggregates.Snapshotting; @@ -12,7 +13,6 @@ using Purview.EventSourcing.SqlServer.Events; using Purview.EventSourcing.SqlServer.Snapshot; using Purview.EventSourcing.SqlServer.Snapshots; -using Testcontainers.MsSql; namespace Purview.EventSourcing.Benchmarks.SqlServer; @@ -76,12 +76,14 @@ public void GlobalSetup() var aggregate = _eventStore.CreateAsync(_seededIds[i]).GetAwaiter().GetResult(); PopulateAggregate(aggregate, i, _workload.EventsPerAggregate); var result = _eventStore.SaveAsync(aggregate, operationContext: null).GetAwaiter().GetResult(); - if (!result.Saved || !result.IsValid) + if (result.IsFailure) throw new InvalidOperationException($"Seeding save failed for aggregate '{_seededIds[i]}'."); - var loadedAggregate = - _eventStore.GetAsync(_seededIds[i], operationContext: null).GetAwaiter().GetResult() - ?? throw new InvalidOperationException($"Seeded aggregate '{_seededIds[i]}' was not found."); + var loadResult = _eventStore.GetAsync(_seededIds[i], operationContext: null).GetAwaiter().GetResult(); + if (loadResult.IsFailure) + throw new InvalidOperationException($"Seeded aggregate '{_seededIds[i]}' was not found."); + + var loadedAggregate = loadResult.Value; ValidateAggregate(loadedAggregate, i, _workload.EventsPerAggregate); loaded.Add(loadedAggregate); } @@ -173,7 +175,7 @@ public async Task EventStore_Save() PopulateAggregate(aggregate, _saveCounter, _workload.EventsPerAggregate); var result = await _eventStore.SaveAsync(aggregate, operationContext: null); - if (!result.Saved || !result.IsValid) + if (result.IsFailure) throw new InvalidOperationException($"Save failed for aggregate '{aggregate.Id()}'."); } @@ -188,7 +190,7 @@ public async Task EventStore_Save_NoSnapshot() operationContext.SetSnapshotStrategy(new IntervalSnapshotStrategy(1000)); var result = await _eventStore.SaveAsync(aggregate, operationContext); - if (!result.Saved || !result.IsValid) + if (result.IsFailure) throw new InvalidOperationException($"Save failed for aggregate '{aggregate.Id()}'."); } @@ -197,11 +199,11 @@ public async Task EventStore_Save_NoSnapshot() public async Task EventStore_Get() { var index = _getIndex++ % _seededIds.Length; - var aggregate = - await _eventStore!.GetAsync(_seededIds[index], operationContext: null) - ?? throw new InvalidOperationException($"Aggregate '{_seededIds[index]}' was not found."); + var result = await _eventStore!.GetAsync(_seededIds[index], operationContext: null); + if (result.IsFailure) + throw new InvalidOperationException($"Aggregate '{_seededIds[index]}' was not found."); - ValidateAggregate(aggregate, index, _workload.EventsPerAggregate); + ValidateAggregate(result.Value, index, _workload.EventsPerAggregate); } [Benchmark] @@ -513,7 +515,7 @@ public Task BeforeDeleteAsync(TAggregate aggregate, CancellationToken cancellati public Task AfterSaveAsync( TAggregate aggregate, - int previousSavedVersion, + long previousSavedVersion, bool isNew, EventRecord[] events, CancellationToken cancellationToken = default @@ -560,7 +562,8 @@ public static T Create() where T : class => DispatchProxy.Create(); } - sealed class NoOpDispatchProxy : DispatchProxy + // Not sealed: DispatchProxy.Create derives a type from this at runtime and rejects a sealed base. + class NoOpDispatchProxy : DispatchProxy { protected override object? Invoke(MethodInfo? targetMethod, object?[]? args) { diff --git a/src/src/CosmosDb/CosmosDbClient.cs b/src/src/CosmosDb/Client/CosmosDbContainerProvisioner.cs similarity index 78% rename from src/src/CosmosDb/CosmosDbClient.cs rename to src/src/CosmosDb/Client/CosmosDbContainerProvisioner.cs index acef6239..b46a844a 100644 --- a/src/src/CosmosDb/CosmosDbClient.cs +++ b/src/src/CosmosDb/Client/CosmosDbContainerProvisioner.cs @@ -3,47 +3,122 @@ using Microsoft.Azure.Cosmos; using Purview.EventSourcing.CosmosDb.Snapshots; -namespace Purview.EventSourcing.CosmosDb; - -sealed partial class CosmosDbClient : IAsyncDisposable +namespace Purview.EventSourcing.CosmosDb.Client; + +/// +/// Creates and reconciles the Cosmos DB database and container. +/// +/// +/// Entity Framework does not emit a container indexing policy, and its EnsureCreated is documented +/// as a deployment-time operation that cannot run against a management plane secured with RBAC, so +/// provisioning stays on the Azure Cosmos DB SDK while all data access goes through Entity Framework. +/// +sealed class CosmosDbContainerProvisioner : IAsyncDisposable { - Database _database = default!; - - readonly AsyncLazy _container; + static readonly ConcurrentDictionary CosmosDbClients = new(); + static readonly ConcurrentDictionary> CreatedDatabases = new(); + static readonly ConcurrentDictionary> CreatedContainers = new(); readonly CosmosDbEventStoreOptions _cosmosDbOptions; + readonly CosmosDbClientOverrides? _overrides; readonly string _containerName; + readonly string _partitionKeyPath; readonly string _databaseCreatedKey; readonly string _containerCreatedKey; - readonly string _partitionKey; - static readonly ConcurrentDictionary CosmosDbClients = new(); - static readonly ConcurrentDictionary> CreatedDatabases = new(); - static readonly ConcurrentDictionary> CreatedContainers = new(); + readonly AsyncLazy _container; - public CosmosDbClient( + public CosmosDbContainerProvisioner( [NotNull] CosmosDbEventStoreOptions cosmosDbOptions, string? partitionKeyOverride = null, string? containerNameOverride = null, - CosmosClient? cosmosClient = null + CosmosDbClientOverrides? overrides = null ) { _cosmosDbOptions = cosmosDbOptions; + _overrides = overrides; _containerName = containerNameOverride ?? cosmosDbOptions.Container; - _partitionKey = partitionKeyOverride ?? cosmosDbOptions.PartitionKeyPath; + _partitionKeyPath = partitionKeyOverride ?? cosmosDbOptions.PartitionKeyPath; _databaseCreatedKey = $"{cosmosDbOptions.ConnectionString}-{cosmosDbOptions.Database}"; _containerCreatedKey = $"{cosmosDbOptions.ConnectionString}-{_containerName}"; - _container = new AsyncLazy(token => InitializeAsync(cosmosClient, token)); + _container = new AsyncLazy(InitializeAsync); + } + + public async Task EnsureCreatedAsync(CancellationToken cancellationToken = default) => + await _container.GetValueAsync(cancellationToken); + + public async Task DeleteContainerAsync(CancellationToken cancellationToken = default) + { + var container = await _container.GetValueAsync(cancellationToken); + await container.DeleteContainerAsync(cancellationToken: cancellationToken); + + _ = CreatedContainers.TryRemove(_containerCreatedKey, out _); + } + + async Task InitializeAsync(CancellationToken cancellationToken) + { + var client = GetOrCreateClient(); + await InitializeDatabaseAsync(client, cancellationToken); + + return await InitializeContainerAsync(cancellationToken); + } + + async Task InitializeContainerAsync(CancellationToken cancellationToken) + { + return await CreatedContainers + .GetOrAdd( + _containerCreatedKey, + _ => new AsyncLazy(async ct => + { + var response = + await GetOrCreateContainerAsync(ct) + ?? throw new NullReferenceException( + $"Unable to get the container response for '{_containerName}'" + ); + return response.StatusCode is System.Net.HttpStatusCode.OK or System.Net.HttpStatusCode.Accepted + ? response.Container + : throw new InvalidOperationException( + $"Unable to get or create the container '{_containerName}', with status code: {response.StatusCode}" + ); + }) + ) + .GetValueAsync(cancellationToken); + } + + async Task InitializeDatabaseAsync(CosmosClient client, CancellationToken cancellationToken) + { + return await CreatedDatabases + .GetOrAdd( + _databaseCreatedKey, + _ => new AsyncLazy(async ct => + { + var response = await client.CreateDatabaseIfNotExistsAsync( + _cosmosDbOptions.Database, + throughput: _cosmosDbOptions.DatabaseThroughput, + cancellationToken: ct + ); + return + response.StatusCode + is System.Net.HttpStatusCode.OK + or System.Net.HttpStatusCode.Accepted + or System.Net.HttpStatusCode.Created + ? response.Database + : throw new InvalidOperationException( + $"Unable to get or create the database '{_cosmosDbOptions.Database}', with status code: {response.StatusCode}" + ); + }) + ) + .GetValueAsync(cancellationToken); } async Task GetOrCreateContainerAsync(CancellationToken cancellationToken) { var client = GetOrCreateClient(); - var database = await InitializeDatabase(client, cancellationToken); + var database = await InitializeDatabaseAsync(client, cancellationToken); var container = database.GetContainer(_containerName); var response = await container.ReadContainerStreamAsync(cancellationToken: cancellationToken); @@ -148,7 +223,7 @@ await container.ReplaceContainerStreamAsync( else { // Attempt to create the container... - var containerBuilder = database.DefineContainer(_containerName, _partitionKey); + var containerBuilder = database.DefineContainer(_containerName, _partitionKeyPath); #region Attempt to create the container @@ -194,80 +269,26 @@ await container.ReplaceContainerStreamAsync( } } - async Task InitializeAsync(CosmosClient? cosmosClient, CancellationToken cancellationToken) - { - var client = cosmosClient ?? GetOrCreateClient(); - await InitializeDatabase(client, cancellationToken); - - return await InitializeContainerAsync(cancellationToken); - } - - async Task InitializeContainerAsync(CancellationToken cancellationToken) - { - return await CreatedContainers - .GetOrAdd( - _containerCreatedKey, - _ => new AsyncLazy(async ct => - { - var response = - await GetOrCreateContainerAsync(ct) - ?? throw new NullReferenceException( - $"Unable to get the container response for '{_containerName}'" - ); - return response.StatusCode is System.Net.HttpStatusCode.OK or System.Net.HttpStatusCode.Accepted - ? response.Container - : throw new InvalidOperationException( - $"Unable to get or create the container '{_containerName}', with status code: {response.StatusCode}" - ); - }) - ) - .GetValueAsync(cancellationToken); - } - - async Task InitializeDatabase(CosmosClient client, CancellationToken cancellationToken) - { - return _database = await CreatedDatabases - .GetOrAdd( - _databaseCreatedKey, - _ => new AsyncLazy(async ct => - { - var response = await client.CreateDatabaseIfNotExistsAsync( - _cosmosDbOptions.Database, - throughput: _cosmosDbOptions.DatabaseThroughput, - cancellationToken: ct - ); - return - response.StatusCode - is System.Net.HttpStatusCode.OK - or System.Net.HttpStatusCode.Accepted - or System.Net.HttpStatusCode.Created - ? response.Database - : throw new InvalidOperationException( - $"Unable to get or create the database '{_cosmosDbOptions.Database}', with status code: {response.StatusCode}" - ); - }) - ) - .GetValueAsync(cancellationToken); - } - - CosmosClient GetOrCreateClient() => GetOrCreateClient(_cosmosDbOptions); - - static CosmosClient GetOrCreateClient(CosmosDbEventStoreOptions configuration) + CosmosClient GetOrCreateClient() { return CosmosDbClients.GetOrAdd( - $"{configuration.ConnectionString}".ToUpperInvariant(), + $"{_cosmosDbOptions.ConnectionString}".ToUpperInvariant(), _ => { CosmosClientOptions clientOptions = new() { - ConnectionMode = configuration.ConnectionMode, + ConnectionMode = _cosmosDbOptions.ConnectionMode, RequestTimeout = TimeSpan.FromSeconds( - configuration.RequestTimeoutInSeconds ?? CosmosDbOptions.DefaultRequestTimeout + _cosmosDbOptions.RequestTimeoutInSeconds ?? CosmosDbOptions.DefaultRequestTimeout ), - Serializer = new CosmosSystemTextJsonSerializer(), }; - if (configuration.IgnoreSSLWarnings) + if (_overrides?.HttpClientFactory is not null) + { + clientOptions.HttpClientFactory = _overrides.HttpClientFactory; + clientOptions.LimitToEndpoint = _overrides.LimitToEndpoint; + } + else if (_cosmosDbOptions.IgnoreSSLWarnings) { clientOptions.HttpClientFactory = () => { @@ -281,7 +302,7 @@ static CosmosClient GetOrCreateClient(CosmosDbEventStoreOptions configuration) }; } - return new(configuration.ConnectionString, clientOptions); + return new(_cosmosDbOptions.ConnectionString, clientOptions); } ); } diff --git a/src/src/CosmosDb/Client/CosmosDbSnapshotClient.cs b/src/src/CosmosDb/Client/CosmosDbSnapshotClient.cs new file mode 100644 index 00000000..eb4cecfc --- /dev/null +++ b/src/src/CosmosDb/Client/CosmosDbSnapshotClient.cs @@ -0,0 +1,266 @@ +using System.Collections.Concurrent; +using System.Linq.Expressions; +using Microsoft.EntityFrameworkCore; +using Purview.EventSourcing.CosmosDb.Snapshots; +using Purview.EventSourcing.EntityFrameworkCore.Query; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.CosmosDb.Client; + +/// +/// Reads and writes aggregate snapshots through Entity Framework, scoping every operation to the +/// aggregate type's partition. +/// +/// The aggregate type. +sealed class CosmosDbSnapshotClient : IAsyncDisposable + where T : class +{ + // Entity Framework builds - and caches - an internal service provider per distinct set of context + // options, so one set is shared by every store that talks to the same account. + static readonly ConcurrentDictionary< + ContextOptionsKey, + DbContextOptions> + > ContextOptionsCache = new(); + + readonly CosmosDbEventStoreOptions _options; + readonly CosmosDbContainerProvisioner _provisioner; + readonly DbContextOptions> _contextOptions; + readonly string _containerName; + readonly ICurrentTenant _currentTenant; + + /// + /// Narrows a snapshot query to the current tenant. + /// + /// + /// Applied after WithPartitionKey rather than as a global query filter: EF Cosmos requires the + /// partition-key call to sit on a plain entity query root, and a global filter stops it being one. + /// A document with no recorded owner stays visible. + /// + IQueryable Scoped(IQueryable query) + { + var scope = _currentTenant.Current; + + return scope.IsSystem + ? query + : query.Where(candidate => + EF.Property(candidate, SnapshotDbContext.TenantPropertyName) == scope.TenantId + || EF.Property(candidate, SnapshotDbContext.TenantPropertyName) == null + ); + } + + readonly string _aggregateTypeName; + + readonly record struct ContextOptionsKey( + string ConnectionString, + string Database, + Microsoft.Azure.Cosmos.ConnectionMode ConnectionMode, + int? RequestTimeoutInSeconds, + bool IgnoreSSLWarnings, + CosmosDbClientOverrides? Overrides + ); + + public CosmosDbSnapshotClient( + CosmosDbEventStoreOptions options, + string aggregateTypeName, + CosmosDbClientOverrides? overrides = null, + string? containerNameOverride = null, + ICurrentTenant? currentTenant = null + ) + { + ArgumentNullException.ThrowIfNull(options); + _currentTenant = currentTenant ?? new SystemCurrentTenant(); + + // Snapshot documents are partitioned by aggregate type, and the mapping depends on it: a + // container built around any other path would not match the model. + if (!string.Equals(options.PartitionKeyPath, SnapshotDbContext.PartitionKeyPath, StringComparison.Ordinal)) + { + throw new InvalidOperationException( + $"Snapshot containers must use the partition key path '{SnapshotDbContext.PartitionKeyPath}', but '{options.PartitionKeyPath}' was configured." + ); + } + + _options = options; + _aggregateTypeName = aggregateTypeName; + _containerName = containerNameOverride ?? options.Container; + _provisioner = new(options, containerNameOverride: _containerName, overrides: overrides); + _contextOptions = ContextOptionsCache.GetOrAdd( + new ContextOptionsKey( + options.ConnectionString, + options.Database, + options.ConnectionMode, + options.RequestTimeoutInSeconds, + options.IgnoreSSLWarnings, + overrides + ), + _ => SnapshotDbContext.BuildContextOptions(options, overrides) + ); + } + + public Task EnsureCreatedAsync(CancellationToken cancellationToken = default) => + _provisioner.EnsureCreatedAsync(cancellationToken); + + public Task DeleteContainerAsync(CancellationToken cancellationToken = default) => + _provisioner.DeleteContainerAsync(cancellationToken); + + /// + /// Writes the snapshot, creating the document when it does not already exist. + /// + /// + /// Entity Framework has no upsert for Cosmos DB - an added entity issues CreateItem and a + /// modified one ReplaceItem - so existence is established first, which costs an additional + /// request per snapshot. + /// + public async Task UpsertAsync(T aggregate, string id, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(aggregate); + + await EnsureCreatedAsync(cancellationToken); + await using var context = CreateContext(); + + var exists = await Scoped(context.Snapshots.WithPartitionKey(_aggregateTypeName).AsNoTracking()) + .AnyAsync( + candidate => EF.Property(candidate, SnapshotDbContext.IdPropertyName) == id, + cancellationToken + ); + + // Entry() rather than Attach(): the shadow key is still null here, and Attach would start + // tracking - and reject it. A detached entry takes the key first, then begins tracking. + var entry = context.Entry(aggregate); + entry.Property(SnapshotDbContext.IdPropertyName).CurrentValue = id; + entry.Property(SnapshotDbContext.PartitionKeyPropertyName).CurrentValue = _aggregateTypeName; + entry.Property(SnapshotDbContext.TenantPropertyName).CurrentValue = _currentTenant.Current.TenantId; + entry.State = exists ? EntityState.Modified : EntityState.Added; + + return await context.SaveChangesAsync(cancellationToken) > 0; + } + + public async Task DeleteAsync(string id, CancellationToken cancellationToken = default) + { + ArgumentException.ThrowIfNullOrWhiteSpace(id); + + await EnsureCreatedAsync(cancellationToken); + await using var context = CreateContext(); + + var existing = await Scoped(context.Snapshots.WithPartitionKey(_aggregateTypeName)) + .SingleOrDefaultAsync( + candidate => EF.Property(candidate, SnapshotDbContext.IdPropertyName) == id, + cancellationToken + ); + + if (existing is null) + return false; + + context.Remove(existing); + return await context.SaveChangesAsync(cancellationToken) > 0; + } + + public async Task CountAsync( + Expression>? whereClause, + CancellationToken cancellationToken = default + ) + { + await EnsureCreatedAsync(cancellationToken); + await using var context = CreateContext(); + + return await BuildQuery(context, whereClause, orderByClause: null, applyDefaultOrdering: false) + .LongCountAsync(cancellationToken); + } + + /// + /// Reads a single page, resuming from when one is supplied. + /// + /// The page's values and the token for the next page, which is null once the last page has been read. + public async Task<(IReadOnlyList Values, string? ContinuationToken)> QueryPageAsync( + Expression>? whereClause, + Func, IQueryable>? orderByClause, + int maxRecords, + string? continuationToken, + CancellationToken cancellationToken = default + ) + { + await EnsureCreatedAsync(cancellationToken); + await using var context = CreateContext(); + + var query = BuildQuery(context, whereClause, orderByClause, applyDefaultOrdering: true); + + if (TryReadOffset(continuationToken, out var offset)) + return await ReadOffsetPageAsync(query, offset, maxRecords, cancellationToken); + + // ToPageAsync is the only API that exposes Cosmos DB continuation tokens; paging with Skip/Take + // instead would re-read every preceding page. It is experimental in EF, hence the suppression. +#pragma warning disable EF9102 + var page = await query.ToPageAsync(maxRecords, continuationToken, cancellationToken: cancellationToken); +#pragma warning restore EF9102 + + if (page.Values.Count <= maxRecords) + return (page.Values, page.ContinuationToken); + + // The page size is a request hint, and a backend that ignores it returns a token positioned past + // more rows than the caller asked for - so the token cannot be handed back. OFFSET/LIMIT is part + // of the query itself and is always applied, so paging continues through an offset token instead. + return BuildOffsetPage(page.Values, offset: 0, maxRecords); + } + + const string OffsetTokenPrefix = "o:"; + + static bool TryReadOffset(string? continuationToken, out int offset) + { + offset = 0; + + return continuationToken?.StartsWith(OffsetTokenPrefix, StringComparison.Ordinal) == true + && int.TryParse( + continuationToken.AsSpan(OffsetTokenPrefix.Length), + System.Globalization.CultureInfo.InvariantCulture, + out offset + ); + } + + static async Task<(IReadOnlyList Values, string? ContinuationToken)> ReadOffsetPageAsync( + IQueryable query, + int offset, + int maxRecords, + CancellationToken cancellationToken + ) + { + // One row beyond the page shows whether a further page exists. + var values = await query.Skip(offset).Take(maxRecords + 1).ToListAsync(cancellationToken); + + return BuildOffsetPage(values, offset, maxRecords); + } + + static (IReadOnlyList Values, string? ContinuationToken) BuildOffsetPage( + IReadOnlyList values, + int offset, + int maxRecords + ) => ([.. values.Take(maxRecords)], values.Count > maxRecords ? $"{OffsetTokenPrefix}{offset + maxRecords}" : null); + + IQueryable BuildQuery( + SnapshotDbContext context, + Expression>? whereClause, + Func, IQueryable>? orderByClause, + bool applyDefaultOrdering + ) + { + var query = Scoped(context.Snapshots.WithPartitionKey(_aggregateTypeName).AsNoTracking()); + + if (whereClause is not null) + query = query.Where(SnapshotPredicateRewriter.Rewrite(whereClause, _aggregateTypeName)); + + if (orderByClause is not null) + { + query = orderByClause(query); + SnapshotPredicateRewriter.EnsureSupportedOrderByExpression(query.Expression); + } + else if (applyDefaultOrdering) + { + // Paging without an order is not stable across continuations. + query = query.OrderBy(candidate => EF.Property(candidate, SnapshotDbContext.IdPropertyName)); + } + + return query; + } + + SnapshotDbContext CreateContext() => new(_contextOptions, _options.Database, _containerName); + + public async ValueTask DisposeAsync() => await _provisioner.DisposeAsync(); +} diff --git a/src/src/CosmosDb/Client/SnapshotDbContext.cs b/src/src/CosmosDb/Client/SnapshotDbContext.cs new file mode 100644 index 00000000..59f61532 --- /dev/null +++ b/src/src/CosmosDb/Client/SnapshotDbContext.cs @@ -0,0 +1,151 @@ +using Microsoft.EntityFrameworkCore; +using Microsoft.EntityFrameworkCore.Infrastructure; +using Purview.EventSourcing.CosmosDb.Snapshots; +using Purview.EventSourcing.EntityFrameworkCore.Mapping; + +namespace Purview.EventSourcing.CosmosDb.Client; + +/// +/// Maps onto the Cosmos DB container as the document root, so caller +/// predicates translate against the document itself rather than a nested payload. +/// +/// The aggregate type. +sealed class SnapshotDbContext : DbContext, ISnapshotModelCacheKeySource + where TAggregate : class +{ + /// + /// The shadow property carrying the document id. Aggregates hold their identity on + /// Details.Id, and a key cannot live inside a complex type. + /// + public const string IdPropertyName = "id"; + + /// + /// The shadow property carrying the partition key. The CLR AggregateType member is read-only + /// and is rebuilt by the aggregate's own constructor, so the value is persisted separately. + /// + public const string PartitionKeyPropertyName = "__aggregateType"; + + const string PartitionKeyJsonPropertyName = "AggregateType"; + + /// + /// The container partition key path this model requires. + /// + public const string PartitionKeyPath = "/" + PartitionKeyJsonPropertyName; + + /// + /// The shadow property recording the tenant that owns the snapshot. + /// + public const string TenantPropertyName = "__tenantId"; + + readonly string _databaseName; + readonly string _containerName; + + public SnapshotDbContext( + DbContextOptions> contextOptions, + string databaseName, + string containerName + ) + : base(contextOptions) + { + _databaseName = databaseName; + _containerName = containerName; + } + + public DbSet Snapshots => Set(); + + public object CreateModelCacheKey(bool designTime) => + (typeof(SnapshotDbContext<>), typeof(TAggregate), _databaseName, _containerName, designTime); + + protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder) + { + SnapshotModelMapper.RegisterScalarValueObjectConversions(configurationBuilder, typeof(TAggregate)); + } + + /// + /// Builds the context options for a snapshot container. + /// + /// + /// Entity Framework caches its internal service provider per distinct set of options, so these are + /// built once per container and reused: a fresh set per context would build a new provider every + /// time, which EF reports as ManyServiceProvidersCreatedWarning once it has seen twenty. + /// + public static DbContextOptions> BuildContextOptions( + CosmosDbEventStoreOptions options, + CosmosDbClientOverrides? overrides + ) + { + ArgumentNullException.ThrowIfNull(options); + + DbContextOptionsBuilder> optionsBuilder = new(); + + optionsBuilder.UseCosmos( + options.ConnectionString, + options.Database, + cosmos => + { + cosmos.ConnectionMode(options.ConnectionMode); + cosmos.RequestTimeout( + TimeSpan.FromSeconds(options.RequestTimeoutInSeconds ?? CosmosDbOptions.DefaultRequestTimeout) + ); + + if (overrides?.HttpClientFactory is not null) + { + cosmos.HttpClientFactory(overrides.HttpClientFactory); + if (overrides.LimitToEndpoint) + cosmos.LimitToEndpoint(); + } + else if (options.IgnoreSSLWarnings) + { + cosmos.HttpClientFactory(CreateInsecureHttpClient); + } + } + ); + + optionsBuilder.ReplaceService(); + + return optionsBuilder.Options; + } + + [System.Diagnostics.CodeAnalysis.SuppressMessage( + "Reliability", + "CA2000:Dispose objects before losing scope", + Justification = "The handler is owned by the returned HttpClient." + )] + [System.Diagnostics.CodeAnalysis.SuppressMessage( + "Security", + "CA5400:HttpClient may be created without enabling CheckCertificateRevocationList", + Justification = "Opted into explicitly through IgnoreSSLWarnings, which documents itself as emulator-only." + )] + static HttpClient CreateInsecureHttpClient() => + new( + new HttpClientHandler + { + ServerCertificateCustomValidationCallback = + HttpClientHandler.DangerousAcceptAnyServerCertificateValidator, + } + ); + + protected override void OnModelCreating(ModelBuilder modelBuilder) + { + // Snapshot payloads are value-object graphs whose members are init-only (or value-object + // struct members). PreferProperty writes members through their accessors (init included) and + // only falls back to the backing field when no setter exists. + modelBuilder.UsePropertyAccessMode(PropertyAccessMode.PreferProperty); + + var entity = modelBuilder.Entity(); + entity.ToContainer(_containerName); + + // One aggregate type per partition, so documents are already unambiguous without EF's $type + // discriminator - which would otherwise be added to every document. + entity.HasNoDiscriminator(); + + entity.Property(IdPropertyName).ToJsonProperty(IdPropertyName); + entity.Property(PartitionKeyPropertyName).ToJsonProperty(PartitionKeyJsonPropertyName); + entity.Property(TenantPropertyName).ToJsonProperty(TenantPropertyName); + entity.HasKey(IdPropertyName); + entity.HasPartitionKey(PartitionKeyPropertyName); + + SnapshotModelMapper.ValidateAggregatePayloadShape(typeof(TAggregate)); + SnapshotModelMapper.ConfigureGraph(SnapshotGraphBuilder.For(entity), typeof(TAggregate)); + } +} diff --git a/src/src/CosmosDb/CosmosDb.csproj b/src/src/CosmosDb/CosmosDb.csproj index e8111719..27c6328d 100644 --- a/src/src/CosmosDb/CosmosDb.csproj +++ b/src/src/CosmosDb/CosmosDb.csproj @@ -1,4 +1,4 @@ - + true Purview Queryable Snapshot Store for Azure Cosmos DB @@ -9,13 +9,20 @@ + + - + - + - diff --git a/src/src/CosmosDb/CosmosDbClient.CosmosDbSpecific.cs b/src/src/CosmosDb/CosmosDbClient.CosmosDbSpecific.cs deleted file mode 100644 index e9eab60b..00000000 --- a/src/src/CosmosDb/CosmosDbClient.CosmosDbSpecific.cs +++ /dev/null @@ -1,374 +0,0 @@ -using System.Linq.Expressions; -using LinqKit; -using Microsoft.Azure.Cosmos; -using Microsoft.Azure.Cosmos.Linq; - -namespace Purview.EventSourcing.CosmosDb; - -partial class CosmosDbClient -{ - public async Task> ListAsync( - Func, IQueryable>? orderByClause, - ContinuationRequest request, - PartitionKey partitionKey, - CancellationToken cancellationToken = default - ) - where T : class - { - QueryRequestOptions requestOptions = new() { MaxItemCount = request.MaxRecords, PartitionKey = partitionKey }; - - var queryIterator = await FeedQueryAsync( - orderByClause, - request.ContinuationToken, - requestOptions, - cancellationToken: cancellationToken - ); - if (queryIterator.HasMoreResults) - { - var currentSet = await queryIterator.ReadNextAsync(cancellationToken); - - return new ContinuationResponse - { - ContinuationToken = currentSet.ContinuationToken, - RequestedCount = request.MaxRecords, - Results = [.. currentSet], - }; - } - - return new ContinuationResponse - { - ContinuationToken = null, - RequestedCount = request.MaxRecords, - Results = [], - }; - } - - public async Task CountAsync( - Expression>? whereClause, - PartitionKey partitionKey, - CancellationToken cancellationToken = default - ) - { - var container = await _container.GetValueAsync(cancellationToken); - - QueryRequestOptions requestOptions = new() { MaxItemCount = 1, PartitionKey = partitionKey }; - - var queryable = container.GetItemLinqQueryable(requestOptions: requestOptions).AsQueryable(); - if (whereClause != null) - { - queryable = queryable.Where(whereClause); - } - - return await queryable.CountAsync(cancellationToken); - } - - public async Task> QueryAsync( - Expression> whereClause, - Func, IQueryable>? orderByClause, - ContinuationRequest request, - PartitionKey partitionKey, - CancellationToken cancellationToken = default - ) - where T : class - { - QueryRequestOptions requestOptions = new() { MaxItemCount = request.MaxRecords, PartitionKey = partitionKey }; - - var queryIterator = await FeedQueryAsync( - whereClause, - orderByClause, - request.ContinuationToken, - requestOptions, - cancellationToken: cancellationToken - ); - if (queryIterator.HasMoreResults) - { - var currentSet = await queryIterator.ReadNextAsync(cancellationToken); - return new() - { - ContinuationToken = currentSet.ContinuationToken, - RequestedCount = request.MaxRecords, - Results = [.. currentSet], - }; - } - - return new() - { - ContinuationToken = null, - RequestedCount = request.MaxRecords, - Results = [], - }; - } - - async Task> FeedQueryAsync( - Func, IQueryable>? orderByClause, - string? continuationToken = null, - QueryRequestOptions? requestOptions = null, - CancellationToken cancellationToken = default - ) - where T : class - { - var container = await _container.GetValueAsync(cancellationToken); - - cancellationToken.ThrowIfCancellationRequested(); - - var listQuery = container - .GetItemLinqQueryable(continuationToken: continuationToken, requestOptions: requestOptions) - .AsQueryable(); - - if (orderByClause != null) - listQuery = orderByClause(listQuery); - - return listQuery.ToFeedIterator(); - } - - async Task> FeedQueryAsync( - Expression> whereClause, - Func, IQueryable>? orderByClause, - string? continuationToken = null, - QueryRequestOptions? requestOptions = null, - CancellationToken cancellationToken = default - ) - { - var container = await _container.GetValueAsync(cancellationToken); - var c = whereClause.Expand(); - - cancellationToken.ThrowIfCancellationRequested(); - - var whereQuery = container - .GetItemLinqQueryable(continuationToken: continuationToken, requestOptions: requestOptions) - .Where(c); - - if (orderByClause != null) - whereQuery = orderByClause(whereQuery); - - return whereQuery.ToFeedIterator(); - } - - public async Task GetAsync( - string id, - PartitionKey partitionKey, - CancellationToken cancellationToken = default - ) - where T : class - { - ArgumentException.ThrowIfNullOrWhiteSpace(id, nameof(id)); - var container = await _container.GetValueAsync(cancellationToken); - - var response = await container.ReadItemStreamAsync(id, partitionKey, cancellationToken: cancellationToken); - if (response.StatusCode == System.Net.HttpStatusCode.NotFound) - return null; - - var client = GetOrCreateClient(_cosmosDbOptions); - return client.ClientOptions.Serializer.FromStream(response.Content); - } - - public async Task DeleteAsync( - T document, - PartitionKey partitionKey, - CancellationToken cancellationToken = default - ) - where T : class - { - ArgumentNullException.ThrowIfNull(document, nameof(document)); - - var responses = await DeleteAsync([document], partitionKey, cancellationToken); - - return responses.Single(); - } - - public Task> DeleteAsync( - T[] documents, - PartitionKey partitionKey, - CancellationToken cancellationToken = default - ) - where T : class - { - ArgumentNullException.ThrowIfNull(documents, nameof(documents)); - if (documents.Length == 0) - return Task.FromResult(Enumerable.Empty()); - - var ids = documents.Where(m => m != null).Select(CosmosDbUtilities.GetDocumentId).ToArray(); - return DeleteAsync(ids, partitionKey, cancellationToken); - } - - public async Task DeleteAsync( - string id, - PartitionKey partitionKey, - CancellationToken cancellationToken = default - ) - { - ArgumentException.ThrowIfNullOrWhiteSpace(id, nameof(id)); - - var responses = await DeleteAsync([id], partitionKey, cancellationToken); - return responses.Single(); - } - - public async Task> DeleteAsync( - string[] ids, - PartitionKey partitionKey, - CancellationToken cancellationToken = default - ) - { - ArgumentNullException.ThrowIfNull(ids, nameof(ids)); - if (ids.Length == 0) - return []; - - var container = await _container.GetValueAsync(cancellationToken); - return await Task.WhenAll( - ids.Where(m => m != null) - .Select(async id => - { - var response = await container.DeleteItemStreamAsync( - id, - partitionKey, - cancellationToken: cancellationToken - ); - - return response; - }) - ); - } - - public async Task InsertAsync( - T document, - PartitionKey partitionKey, - CancellationToken cancellationToken = default - ) - where T : class - { - ArgumentNullException.ThrowIfNull(document, nameof(document)); - - var responses = await InsertAsync([document], partitionKey, cancellationToken); - return responses.Single(); - } - - public async Task> InsertAsync( - T[] documents, - PartitionKey partitionKey, - CancellationToken cancellationToken = default - ) - where T : class - { - ArgumentNullException.ThrowIfNull(documents, nameof(documents)); - if (documents.Length == 0) - return []; - - var container = await _container.GetValueAsync(cancellationToken); - return await Task.WhenAll( - documents.Select(async document => - { - var stream = await CosmosDbUtilities.SerializeDocumentAsync(document, cancellationToken); - var response = await container.CreateItemStreamAsync( - stream, - partitionKey, - cancellationToken: cancellationToken - ); - - return response; - }) - ); - } - - public async Task UpsertAsync( - T document, - PartitionKey partitionKey, - CancellationToken cancellationToken = default - ) - where T : class - { - ArgumentNullException.ThrowIfNull(document, nameof(document)); - - var responses = await UpsertAsync([document], partitionKey, cancellationToken); - return responses.Single(); - } - - public async Task> UpsertAsync( - T[] documents, - PartitionKey partitionKey, - CancellationToken cancellationToken = default - ) - where T : class - { - ArgumentNullException.ThrowIfNull(documents, nameof(documents)); - if (documents.Length == 0) - return []; - - var container = await _container.GetValueAsync(cancellationToken); - return await Task.WhenAll( - documents - .Where(m => m != null) - .Select(async document => - { - var stream = await CosmosDbUtilities.SerializeDocumentAsync(document, cancellationToken); - var response = await container.UpsertItemStreamAsync( - stream, - partitionKey, - cancellationToken: cancellationToken - ); - - return response; - }) - ); - } - - public async Task ReplaceAsync( - T document, - PartitionKey partitionKey, - CancellationToken cancellationToken = default - ) - where T : class - { - ArgumentNullException.ThrowIfNull(document, nameof(document)); - - var responses = await ReplaceAsync([document], partitionKey, cancellationToken); - return responses.Single(); - } - - public async Task> ReplaceAsync( - T[] documents, - PartitionKey partitionKey, - CancellationToken cancellationToken = default - ) - where T : class - { - ArgumentNullException.ThrowIfNull(documents, nameof(documents)); - if (documents.Length == 0) - return []; - - var container = await _container.GetValueAsync(cancellationToken); - - return await Task.WhenAll( - documents - .Where(m => m != null) - .Select(async document => - { - var documentId = CosmosDbUtilities.GetDocumentId(document); - var stream = await CosmosDbUtilities.SerializeDocumentAsync(document, cancellationToken); - var response = await container.ReplaceItemStreamAsync( - stream, - documentId, - partitionKey, - cancellationToken: cancellationToken - ); - - return response; - }) - ); - } - - public async Task DeleteDatabaseAsync(CancellationToken cancellationToken = default) - { - await _container.GetValueAsync(cancellationToken); - await _database.DeleteAsync(cancellationToken: cancellationToken); - - _ = CreatedDatabases.TryRemove(_databaseCreatedKey, out _); - } - - public async Task DeleteContainerAsync(CancellationToken cancellationToken = default) - { - var container = await _container.GetValueAsync(cancellationToken); - await container.DeleteContainerAsync(cancellationToken: cancellationToken); - - _ = CreatedContainers.TryRemove(_containerCreatedKey, out _); - } -} diff --git a/src/src/CosmosDb/CosmosDbClient.CosmosSystemTextJsonSerializer.cs b/src/src/CosmosDb/CosmosDbClient.CosmosSystemTextJsonSerializer.cs deleted file mode 100644 index 4d134c2d..00000000 --- a/src/src/CosmosDb/CosmosDbClient.CosmosSystemTextJsonSerializer.cs +++ /dev/null @@ -1,31 +0,0 @@ -using Microsoft.Azure.Cosmos; -using Purview.EventSourcing.Serialization; - -namespace Purview.EventSourcing.CosmosDb; - -partial class CosmosDbClient -{ - public sealed class CosmosSystemTextJsonSerializer : CosmosSerializer - { - static readonly System.Text.Json.JsonSerializerOptions JsonSerializerOptions = - EventStoreSerializationHelpers.CreateJsonSerializerOptions(); - - public override T FromStream(Stream stream) - { - if (typeof(Stream).IsAssignableFrom(typeof(T))) - return (T)(object)stream; - - using (stream) - return System.Text.Json.JsonSerializer.Deserialize(stream, JsonSerializerOptions)!; - } - - public override Stream ToStream(T input) - { - MemoryStream streamPayload = new(); - System.Text.Json.JsonSerializer.Serialize(streamPayload, input, JsonSerializerOptions); - - streamPayload.Position = 0; - return streamPayload; - } - } -} diff --git a/src/src/CosmosDb/CosmosDbClientOverrides.cs b/src/src/CosmosDb/CosmosDbClientOverrides.cs new file mode 100644 index 00000000..d7b7b316 --- /dev/null +++ b/src/src/CosmosDb/CosmosDbClientOverrides.cs @@ -0,0 +1,23 @@ +namespace Purview.EventSourcing.CosmosDb; + +/// +/// Overrides applied to the underlying Azure Cosmos DB client, for environments - such as the local +/// emulator - that cannot be reached with the default client configuration. +/// +/// +/// These are applied both to the Entity Framework context used for data access and to the client used to +/// create the database and container, so the two always talk to the same endpoint. +/// +public sealed class CosmosDbClientOverrides +{ + /// + /// Gets the factory used to create the the Cosmos DB client uses. + /// + public Func? HttpClientFactory { get; init; } + + /// + /// Gets a value indicating whether the client is limited to the configured endpoint, rather than + /// discovering the account's regional endpoints. + /// + public bool LimitToEndpoint { get; init; } +} diff --git a/src/src/CosmosDb/CosmosDbOptions.cs b/src/src/CosmosDb/CosmosDbOptions.cs index e343344c..849f41ba 100644 --- a/src/src/CosmosDb/CosmosDbOptions.cs +++ b/src/src/CosmosDb/CosmosDbOptions.cs @@ -77,6 +77,10 @@ public class CosmosDbOptions /// /// Gets or sets the partition key path used when creating the container. /// + /// + /// Snapshot documents are partitioned by aggregate type, so this must remain + /// "/AggregateType"; any other value is rejected when the store is created. + /// [Required] [RegularExpression("^[/].+$")] public string PartitionKeyPath { get; set; } = default!; diff --git a/src/src/CosmosDb/CosmosDbUtilities.cs b/src/src/CosmosDb/CosmosDbUtilities.cs deleted file mode 100644 index df5c6264..00000000 --- a/src/src/CosmosDb/CosmosDbUtilities.cs +++ /dev/null @@ -1,151 +0,0 @@ -using System.Collections.Concurrent; -using System.Dynamic; -using System.Reflection; -using System.Text.Json.Serialization; -using Purview.EventSourcing.Serialization; - -namespace Purview.EventSourcing.CosmosDb; - -static class CosmosDbUtilities -{ - static readonly ConcurrentDictionary DocumentSerializers = new(); - - public static string GetDocumentId(object document) - { - var documentType = document.GetType(); - var processData = GetOrCreateSerializeProcess(documentType); - - return processData.GetId(document); - } - - public static Task SerializeDocumentAsync(object document, CancellationToken cancellationToken = default) - { - ArgumentNullException.ThrowIfNull(document); - - var documentType = document.GetType(); - var processData = GetOrCreateSerializeProcess(documentType); - - return processData.SerializeAsync(document, cancellationToken); - } - - static SerializeProcessData GetOrCreateSerializeProcess(Type documentType) - { - if (!DocumentSerializers.TryGetValue(documentType, out var processData)) - { - var properties = documentType.GetProperties(); - var idProperties = FindIdProperties(properties); - if (idProperties == null || !idProperties.Any()) - throw new NullReferenceException($"Unable to locate an `Id` property on {documentType.FullName}."); - - processData = new SerializeProcessData([.. idProperties], properties); - if (!DocumentSerializers.TryAdd(documentType, processData)) - processData = DocumentSerializers[documentType]; - } - - return processData; - } - - static IEnumerable? FindIdProperties(IEnumerable properties) - { - foreach (var property in properties) - { - if (string.Equals(property.Name, "id", StringComparison.OrdinalIgnoreCase)) - return [property]; - - var propertyType = property.PropertyType; - if (propertyType == typeof(string) || !propertyType.GetTypeInfo().IsClass) - continue; - - var childProperties = FindIdProperties(property.PropertyType.GetProperties()); - if (childProperties != null && childProperties.Any()) - return new[] { property }.Concat(childProperties); - } - - return null; - } - - sealed class SerializeProcessData - { - const string IdPropertyName = "id"; - - readonly PropertyInfo[] _idProperties; - readonly PropertyInfo[] _properties; - - public SerializeProcessData(PropertyInfo[] idProperties, PropertyInfo[] properties) - { - if (idProperties.Length == 1) - { - var p = idProperties.Single(); - if (p.Name != IdPropertyName) - { - var jsonAttrib = p.GetCustomAttribute(); - if (jsonAttrib?.Name != IdPropertyName) - throw new NullReferenceException( - "Unable to process object, missing property with name 'id' or System.Text.Json.Serialization.JsonPropertyNameAttribute using that name." - ); - } - } - - _idProperties = idProperties; - _properties = properties; - } - - public bool IsIdDefinedAtTopLevel => _idProperties.Length == 1; - - public async Task SerializeAsync(object document, CancellationToken cancellationToken) - { - var documentResponse = GetDocument(document); - - cancellationToken.ThrowIfCancellationRequested(); - - MemoryStream memoryStream = new(); - await EventStoreSerializationHelpers.SerializeAsync( - memoryStream, - documentResponse, - documentResponse.GetType(), - cancellationToken - ); - - cancellationToken.ThrowIfCancellationRequested(); - - memoryStream.Position = 0; - - return memoryStream; - } - - public string GetId(object document) - { - var currentItem = document; - for (var i = 0; i < _idProperties.Length; i++) - { - var idProperty = _idProperties[i]; - currentItem = - idProperty.GetValue(currentItem) - ?? throw new NullReferenceException("Some or all of id parts are null."); - } - - var id = currentItem.ToString() ?? throw new NullReferenceException("Some or all of id parts are null."); - return id; - } - - public object GetDocument(object document) - { - if (IsIdDefinedAtTopLevel) - return document; - - ExpandoObject documentResponse = new(); - documentResponse.TryAdd(IdPropertyName, GetId(document)); - - object? currentItem; - for (var i = 0; i < _properties.Length; i++) - { - var property = _properties[i]; - - currentItem = property.GetValue(document); - documentResponse.TryAdd(property.Name, currentItem); - } - - return documentResponse; - } - } -} diff --git a/src/src/CosmosDb/ICosmosDbClientExtensions.cs b/src/src/CosmosDb/ICosmosDbClientExtensions.cs deleted file mode 100644 index b5f88d0f..00000000 --- a/src/src/CosmosDb/ICosmosDbClientExtensions.cs +++ /dev/null @@ -1,307 +0,0 @@ -using System.ComponentModel; -using System.Diagnostics.CodeAnalysis; -using System.Linq.Expressions; -using System.Runtime.CompilerServices; -using Microsoft.Azure.Cosmos; - -namespace Purview.EventSourcing.CosmosDb; - -[EditorBrowsable(EditorBrowsableState.Never)] -static class CosmosDbClientExtensions -{ - #region GetQueryEnumerableAsync - - public static async IAsyncEnumerable GetQueryEnumerableAsync( - [NotNull] this CosmosDbClient cosmosDbClient, - Expression> whereClause, - Func, IQueryable>? orderByClause, - PartitionKey partitionKey, - int maxRecordsPerOperation = ContinuationRequest.DefaultMaxRecords, - [EnumeratorCancellation] CancellationToken cancellationToken = default - ) - where T : class - { - ContinuationRequest request = new() { MaxRecords = maxRecordsPerOperation }; - do - { - var response = await cosmosDbClient.QueryAsync( - whereClause, - orderByClause, - request, - partitionKey, - cancellationToken - ); - foreach (var result in response.Results) - yield return result; - - request = response.ToRequest(); - } while (request.ContinuationToken != null); - } - - public static IAsyncEnumerable GetQueryEnumerableAsync( - this CosmosDbClient cosmosDbClient, - Expression> whereClause, - PartitionKey partitionKey, - int maxRecordsPerOperation = ContinuationRequest.DefaultMaxRecords, - CancellationToken cancellationToken = default - ) - where T : class => - cosmosDbClient.GetQueryEnumerableAsync( - whereClause, - null, - partitionKey, - maxRecordsPerOperation, - cancellationToken - ); - - public static IAsyncEnumerable GetQueryEnumerableAsync( - this CosmosDbClient cosmosDbClient, - Expression> whereClause, - Expression> orderByAscending, - PartitionKey partitionKey, - int maxRecordsPerOperation = ContinuationRequest.DefaultMaxRecords, - CancellationToken cancellationToken = default - ) - where T : class => - cosmosDbClient.GetQueryEnumerableAsync( - whereClause, - m => m.OrderBy(orderByAscending), - partitionKey, - maxRecordsPerOperation, - cancellationToken - ); - - #endregion GetQueryEnumerableAsync - - #region GetListEnumerableAsync - - public static async IAsyncEnumerable GetListEnumerableAsync( - [NotNull] this CosmosDbClient cosmosDbClient, - Func, IQueryable>? orderByClause, - PartitionKey partitionKey, - int maxRecordsPerOperation = ContinuationRequest.DefaultMaxRecords, - [EnumeratorCancellation] CancellationToken cancellationToken = default - ) - where T : class - { - ContinuationRequest request = new() { MaxRecords = maxRecordsPerOperation }; - do - { - var response = await cosmosDbClient.ListAsync(orderByClause, request, partitionKey, cancellationToken); - foreach (var result in response.Results) - yield return result; - - request = response.ToRequest(); - } while (request.ContinuationToken != null); - } - - public static IAsyncEnumerable GetListEnumerableAsync( - this CosmosDbClient cosmosDbClient, - PartitionKey partitionKey, - int maxRecordsPerOperation = ContinuationRequest.DefaultMaxRecords, - CancellationToken cancellationToken = default - ) - where T : class => - cosmosDbClient.GetListEnumerableAsync(null, partitionKey, maxRecordsPerOperation, cancellationToken); - - public static IAsyncEnumerable GetListEnumerableAsync( - this CosmosDbClient cosmosDbClient, - Expression> orderByAscending, - PartitionKey partitionKey, - int maxRecordsPerOperation = ContinuationRequest.DefaultMaxRecords, - CancellationToken cancellationToken = default - ) - where T : class => - cosmosDbClient.GetListEnumerableAsync( - m => m.OrderBy(orderByAscending), - partitionKey, - maxRecordsPerOperation, - cancellationToken - ); - - #endregion GetListEnumerableAsync - - #region QueryAsync - - public static Task> QueryAsync( - [NotNull] this CosmosDbClient cosmosDbClient, - Expression> whereClause, - Func, IQueryable>? orderByClause, - PartitionKey partitionKey, - int maxRecords = ContinuationRequest.DefaultMaxRecords, - CancellationToken cancellationToken = default - ) - where T : class => - cosmosDbClient.QueryAsync( - whereClause, - orderByClause, - new ContinuationRequest { MaxRecords = maxRecords, ContinuationToken = null }, - partitionKey, - cancellationToken - ); - - public static Task> QueryAsync( - [NotNull] this CosmosDbClient cosmosDbClient, - Expression> whereClause, - PartitionKey partitionKey, - int maxRecords = ContinuationRequest.DefaultMaxRecords, - CancellationToken cancellationToken = default - ) - where T : class => cosmosDbClient.QueryAsync(whereClause, null, partitionKey, maxRecords, cancellationToken); - - public static Task> QueryAsync( - [NotNull] this CosmosDbClient cosmosDbClient, - Expression> whereClause, - ContinuationRequest request, - PartitionKey partitionKey, - CancellationToken cancellationToken = default - ) - where T : class => cosmosDbClient.QueryAsync(whereClause, null, request, partitionKey, cancellationToken); - - public static Task> QueryAsync( - [NotNull] this CosmosDbClient cosmosDbClient, - Expression> whereClause, - Expression> orderByAscending, - PartitionKey partitionKey, - int maxRecords = ContinuationRequest.DefaultMaxRecords, - CancellationToken cancellationToken = default - ) - where T : class => - cosmosDbClient.QueryAsync( - whereClause, - m => m.OrderBy(orderByAscending), - partitionKey, - maxRecords, - cancellationToken - ); - - public static Task> QueryAsync( - [NotNull] this CosmosDbClient cosmosDbClient, - Expression> whereClause, - Expression> orderByAscending, - ContinuationRequest request, - PartitionKey partitionKey, - CancellationToken cancellationToken = default - ) - where T : class => - cosmosDbClient.QueryAsync( - whereClause, - m => m.OrderBy(orderByAscending), - request, - partitionKey, - cancellationToken - ); - - #endregion QueryAsync - - #region ListAsync - - public static Task> ListAsync( - [NotNull] this CosmosDbClient cosmosDbClient, - Func, IQueryable>? orderByClause, - PartitionKey partitionKey, - int maxRecords = ContinuationRequest.DefaultMaxRecords, - CancellationToken cancellationToken = default - ) - where T : class => - cosmosDbClient.ListAsync( - orderByClause, - new ContinuationRequest { MaxRecords = maxRecords, ContinuationToken = null }, - partitionKey, - cancellationToken - ); - - public static Task> ListAsync( - [NotNull] this CosmosDbClient cosmosDbClient, - PartitionKey partitionKey, - int maxRecords = ContinuationRequest.DefaultMaxRecords, - CancellationToken cancellationToken = default - ) - where T : class => cosmosDbClient.ListAsync(null, partitionKey, maxRecords, cancellationToken); - - public static Task> ListAsync( - [NotNull] this CosmosDbClient cosmosDbClient, - ContinuationRequest request, - PartitionKey partitionKey, - CancellationToken cancellationToken = default - ) - where T : class => cosmosDbClient.ListAsync(null, request, partitionKey, cancellationToken); - - public static Task> ListAsync( - [NotNull] this CosmosDbClient cosmosDbClient, - Expression> orderByAscending, - PartitionKey partitionKey, - int maxRecords = ContinuationRequest.DefaultMaxRecords, - CancellationToken cancellationToken = default - ) - where T : class => - cosmosDbClient.ListAsync(m => m.OrderBy(orderByAscending), partitionKey, maxRecords, cancellationToken); - - public static Task> ListAsync( - [NotNull] this CosmosDbClient cosmosDbClient, - Expression> orderByAscending, - ContinuationRequest request, - PartitionKey partitionKey, - CancellationToken cancellationToken = default - ) - where T : class => - cosmosDbClient.ListAsync(m => m.OrderBy(orderByAscending), request, partitionKey, cancellationToken); - - #endregion ListAsync - - #region CRUD - - public static async Task> DeleteAsync( - [NotNull] this CosmosDbClient cosmosDbClient, - IEnumerable documents, - PartitionKey partitionKey, - CancellationToken cancellationToken = default - ) - where T : class - { - ArgumentNullException.ThrowIfNull(documents, nameof(documents)); - - return await cosmosDbClient.DeleteAsync(documents.ToArray(), partitionKey, cancellationToken); - } - - public static async Task> InsertAsync( - [NotNull] this CosmosDbClient cosmosDbClient, - IEnumerable documents, - PartitionKey partitionKey, - CancellationToken cancellationToken = default - ) - where T : class - { - ArgumentNullException.ThrowIfNull(documents, nameof(documents)); - - return await cosmosDbClient.InsertAsync(documents.ToArray(), partitionKey, cancellationToken); - } - - public static async Task> UpsertAsync( - [NotNull] this CosmosDbClient cosmosDbClient, - IEnumerable documents, - PartitionKey partitionKey, - CancellationToken cancellationToken = default - ) - where T : class - { - ArgumentNullException.ThrowIfNull(documents, nameof(documents)); - - return await cosmosDbClient.UpsertAsync(documents.ToArray(), partitionKey, cancellationToken); - } - - public static async Task> ReplaceAsync( - [NotNull] this CosmosDbClient cosmosDbClient, - IEnumerable documents, - PartitionKey partitionKey, - CancellationToken cancellationToken = default - ) - where T : class - { - ArgumentNullException.ThrowIfNull(documents, nameof(documents)); - - return await cosmosDbClient.ReplaceAsync(documents.ToArray(), partitionKey, cancellationToken); - } - - #endregion CRUD -} diff --git a/src/src/CosmosDb/Sdk/README.md b/src/src/CosmosDb/Sdk/README.md index 3480bbc9..6da63fb9 100644 --- a/src/src/CosmosDb/Sdk/README.md +++ b/src/src/CosmosDb/Sdk/README.md @@ -17,8 +17,21 @@ builder.Services.AddCosmosDbSnapshotQueryableEventStore(); ## What it provides - Query, list, count, and snapshot-backed reads through `IQueryableEventStore` -- Azure Cosmos DB persistence for aggregate read models -- Configuration binding for the Cosmos DB snapshot store +- Azure Cosmos DB persistence for aggregate read models, mapped by Entity Framework +- Paging through native Cosmos DB continuation tokens +- Configuration binding for the Cosmos DB snapshot store, including the container indexing policy + +## Snapshot shape + +Snapshot documents are the aggregate itself: the mapped members sit at the document root, `id` carries +`Details.Id`, and `AggregateType` is the partition key. The mapping is shared with the SQL Server and PostgreSQL +snapshot stores, so the same member shapes are supported everywhere - primitives, `[Scalar]` value objects, complex +types, and `EventStoreList`/`EventStoreSet` collections of those. Members that cannot be mapped structurally +(dictionaries, read-only collections) are reported at startup; mark them `[EFOpaque]` to persist them as converted +JSON instead. + +Writing a snapshot costs one additional request, because Entity Framework has no Cosmos DB upsert and the store +establishes whether the document already exists before writing it. ## Documentation diff --git a/src/src/CosmosDb/Snapshots/CosmosDbSnapshotEventStore.EventStore.cs b/src/src/CosmosDb/Snapshots/CosmosDbSnapshotEventStore.EventStore.cs index dab3a3c9..5ebd7baf 100644 --- a/src/src/CosmosDb/Snapshots/CosmosDbSnapshotEventStore.EventStore.cs +++ b/src/src/CosmosDb/Snapshots/CosmosDbSnapshotEventStore.EventStore.cs @@ -1,5 +1,7 @@ using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Snapshotting; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.CosmosDb.Snapshot; @@ -10,29 +12,29 @@ public Task CreateAsync(string? aggregateId = null, CancellationToken cancell _eventStore.CreateAsync(aggregateId, cancellationToken); /// - public Task GetOrCreateAsync( + public Task> GetOrCreateAsync( string? aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => _eventStore.GetOrCreateAsync(aggregateId, operationContext, cancellationToken); /// - public Task GetAsync( + public Task> GetAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => _eventStore.GetAsync(aggregateId, operationContext, cancellationToken); /// - public Task GetAtAsync( + public Task> GetAtAsync( string aggregateId, - int version, + long version, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => _eventStore.GetAtAsync(aggregateId, version, operationContext, cancellationToken); /// - public async Task> SaveAsync( + public async Task, AggregateSaveFailure>> SaveAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -43,8 +45,8 @@ public async Task> SaveAsync( var result = await _eventStore.SaveAsync(aggregate, operationContext, cancellationToken); if ( - result - && !result.Skipped + result.IsSuccess + && result.Value.Written && SnapshotStrategyResolver.ShouldSnapshot( aggregate, eventsApplied, @@ -59,15 +61,14 @@ public async Task> SaveAsync( } /// - public Task IsDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) => - _eventStore.IsDeletedAsync(aggregateId, cancellationToken); - /// - public Task GetDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) => - _eventStore.GetDeletedAsync(aggregateId, cancellationToken); + public Task> GetDeletedAsync( + string aggregateId, + CancellationToken cancellationToken = default + ) => _eventStore.GetDeletedAsync(aggregateId, cancellationToken); /// - public async Task DeleteAsync( + public async Task, AggregateDeleteFailure>> DeleteAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -76,14 +77,14 @@ public async Task DeleteAsync( ArgumentNullException.ThrowIfNull(aggregate, nameof(aggregate)); var result = await _eventStore.DeleteAsync(aggregate, operationContext, cancellationToken); - if (result) - await _cosmosDbClient.DeleteAsync(aggregate.Details.Id, _partitionKey, cancellationToken); + if (result.IsSuccess) + await _cosmosDbClient.DeleteAsync(aggregate.Details.Id, cancellationToken); return result; } /// - public async Task RestoreAsync( + public async Task, AggregateRestoreFailure>> RestoreAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -92,7 +93,7 @@ public async Task RestoreAsync( ArgumentNullException.ThrowIfNull(aggregate, nameof(aggregate)); var result = await _eventStore.RestoreAsync(aggregate, operationContext, cancellationToken); - if (result) + if (result.IsSuccess) await SnapshotAsync(aggregate, cancellationToken); return result; @@ -105,7 +106,7 @@ public IAsyncEnumerable GetAggregateIdsAsync( ) => _eventStore.GetAggregateIdsAsync(includeDeleted, cancellationToken); /// - public Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) => + public Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) => _eventStore.ExistsAsync(aggregateId, cancellationToken); /// @@ -114,8 +115,8 @@ public Task ExistsAsync(string aggregateId, CancellationToken cance /// public IAsyncEnumerable<(EventRecord EventRecord, string EventType)> GetEventRangeAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, CancellationToken cancellationToken ) => _eventStore.GetEventRangeAsync(aggregateId, versionFrom, versionTo, cancellationToken); } diff --git a/src/src/CosmosDb/Snapshots/CosmosDbSnapshotEventStore.Query.cs b/src/src/CosmosDb/Snapshots/CosmosDbSnapshotEventStore.Query.cs index 5d1504cb..b45901ff 100644 --- a/src/src/CosmosDb/Snapshots/CosmosDbSnapshotEventStore.Query.cs +++ b/src/src/CosmosDb/Snapshots/CosmosDbSnapshotEventStore.Query.cs @@ -1,41 +1,35 @@ using System.Linq.Expressions; -using LinqKit; +using System.Runtime.CompilerServices; namespace Purview.EventSourcing.CosmosDb.Snapshot; partial class CosmosDbSnapshotEventStore { /// - public IAsyncEnumerable GetQueryEnumerableAsync( + public async IAsyncEnumerable GetQueryEnumerableAsync( Expression> whereClause, Func, IQueryable>? orderByClause, int maxRecordsPerIteration = ContinuationRequest.DefaultMaxRecords, - CancellationToken cancellationToken = default + [EnumeratorCancellation] CancellationToken cancellationToken = default ) { - var expressionToRun = BuildQueryExpression(whereClause); - - return _cosmosDbClient - .GetQueryEnumerableAsync( - whereClause, - orderByClause, - _partitionKey, - maxRecordsPerIteration, - cancellationToken - ) - .SelectAsync(FulfilRequirements); + ArgumentNullException.ThrowIfNull(whereClause, nameof(whereClause)); + + await foreach ( + var aggregate in EnumerateAsync(whereClause, orderByClause, maxRecordsPerIteration, cancellationToken) + ) + yield return aggregate; } /// - public IAsyncEnumerable GetListEnumerableAsync( + public async IAsyncEnumerable GetListEnumerableAsync( Func, IQueryable>? orderByClause, int maxRecordsPerIteration = ContinuationRequest.DefaultMaxRecords, - CancellationToken cancellationToken = default + [EnumeratorCancellation] CancellationToken cancellationToken = default ) { - return _cosmosDbClient - .GetListEnumerableAsync(orderByClause, _partitionKey, maxRecordsPerIteration, cancellationToken) - .SelectAsync(FulfilRequirements); + await foreach (var aggregate in EnumerateAsync(null, orderByClause, maxRecordsPerIteration, cancellationToken)) + yield return aggregate; } /// @@ -49,20 +43,7 @@ public async Task> QueryAsync( ArgumentNullException.ThrowIfNull(whereClause, nameof(whereClause)); ArgumentNullException.ThrowIfNull(request, nameof(request)); - var expressionToRun = BuildQueryExpression(whereClause); - var results = await _cosmosDbClient.QueryAsync( - expressionToRun, - orderByClause, - request, - _partitionKey, - cancellationToken - ); - - results.Results = [.. results.Results.Select(FulfilRequirements)]; - if (request.IncludeTotalCount) - results.TotalCount = await _cosmosDbClient.CountAsync(expressionToRun, _partitionKey, cancellationToken); - - return results; + return await ExecuteQueryAsync(whereClause, orderByClause, request, cancellationToken); } /// @@ -74,20 +55,7 @@ public async Task> ListAsync( { ArgumentNullException.ThrowIfNull(request, nameof(request)); - var expressionToRun = BuildQueryExpression(); - var results = await _cosmosDbClient.QueryAsync( - expressionToRun, - orderByClause, - request, - _partitionKey, - cancellationToken - ); - - results.Results = [.. results.Results.Select(FulfilRequirements)]; - if (request.IncludeTotalCount) - results.TotalCount = await _cosmosDbClient.CountAsync(expressionToRun, _partitionKey, cancellationToken); - - return results; + return await ExecuteQueryAsync(null, orderByClause, request, cancellationToken); } /// @@ -113,12 +81,10 @@ public async Task> ListAsync( } /// - public Task CountAsync(Expression>? whereClause, CancellationToken cancellationToken = default) - { - var expressionToRun = BuildQueryExpression(whereClause); - - return _cosmosDbClient.CountAsync(expressionToRun, _partitionKey, cancellationToken); - } + public Task CountAsync( + Expression>? whereClause, + CancellationToken cancellationToken = default + ) => _cosmosDbClient.CountAsync(whereClause, cancellationToken); async Task> GetSpecificNumberAsync( Expression> whereClause, @@ -127,7 +93,6 @@ async Task> GetSpecificNumberAsync( CancellationToken cancellationToken = default ) { - // We call QueryAsync because we need the query by the AggregateType. var query = await QueryAsync( whereClause, orderByClause, @@ -135,20 +100,53 @@ async Task> GetSpecificNumberAsync( cancellationToken: cancellationToken ); - return query.Results.Select(FulfilRequirements); + return query.Results; } - Expression> BuildQueryExpression(Expression>? whereClause = null) + async IAsyncEnumerable EnumerateAsync( + Expression>? whereClause, + Func, IQueryable>? orderByClause, + int maxRecordsPerIteration, + [EnumeratorCancellation] CancellationToken cancellationToken + ) { - var aggregateTypeName = GetAggregateTypeName(); - Expression> defaultClause = m => m.AggregateType == aggregateTypeName; - - if (whereClause == null) - return PredicateBuilder.New(defaultClause); + ContinuationRequest request = new() { MaxRecords = maxRecordsPerIteration }; + ContinuationResponse response; + do + { + response = await ExecuteQueryAsync(whereClause, orderByClause, request, cancellationToken); + foreach (var result in response.Results) + yield return result; + + request = response; + } while (response.HasMoreRecords); + } - var aggregateClause = PredicateBuilder.Extend(defaultClause, whereClause, PredicateOperator.And); - var expressionToRun = aggregateClause.Expand(); + async Task> ExecuteQueryAsync( + Expression>? whereClause, + Func, IQueryable>? orderByClause, + ContinuationRequest request, + CancellationToken cancellationToken + ) + { + var (values, continuationToken) = await _cosmosDbClient.QueryPageAsync( + whereClause, + orderByClause, + request.MaxRecords, + request.ContinuationToken, + cancellationToken + ); - return expressionToRun; + var results = values.Select(FulfilRequirements).ToArray(); + + return new ContinuationResponse + { + Results = results, + RequestedCount = request.MaxRecords, + ContinuationToken = continuationToken, + TotalCount = request.IncludeTotalCount + ? await _cosmosDbClient.CountAsync(whereClause, cancellationToken) + : null, + }; } } diff --git a/src/src/CosmosDb/Snapshots/CosmosDbSnapshotEventStore.cs b/src/src/CosmosDb/Snapshots/CosmosDbSnapshotEventStore.cs index 7203a8e7..90da7caf 100644 --- a/src/src/CosmosDb/Snapshots/CosmosDbSnapshotEventStore.cs +++ b/src/src/CosmosDb/Snapshots/CosmosDbSnapshotEventStore.cs @@ -1,9 +1,10 @@ -using Microsoft.Azure.Cosmos; using Microsoft.Extensions.Options; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Snapshotting; +using Purview.EventSourcing.CosmosDb.Client; using Purview.EventSourcing.CosmosDb.Snapshots; using Purview.EventSourcing.Internal; +using Purview.EventSourcing.Tenancy; namespace Purview.EventSourcing.CosmosDb.Snapshot; @@ -12,10 +13,11 @@ namespace Purview.EventSourcing.CosmosDb.Snapshot; /// /// An implementation. /// -/// Aggregates are upserted as documents into the configured Cosmos DB container, partitioned by -/// . Event persistence is delegated to the registered -/// , while snapshots are written according to the configured -/// and telemetry is recorded via . +/// Aggregates are written as documents into the configured Cosmos DB container, partitioned by +/// , and mapped by Entity Framework so queries translate against the +/// document itself. Event persistence is delegated to the registered , +/// while snapshots are written according to the configured and telemetry +/// is recorded via . /// public sealed partial class CosmosDbSnapshotEventStore : ICosmosDbSnapshotEventStore, IAsyncDisposable where T : class, IAggregate, new() @@ -26,9 +28,7 @@ public sealed partial class CosmosDbSnapshotEventStore : ICosmosDbSnapshotEve readonly ISnapshotStrategy _snapshotStrategy; readonly ISnapshotStrategySelector? _snapshotStrategySelector; - readonly CosmosDbClient _cosmosDbClient; - - readonly PartitionKey _partitionKey; + readonly CosmosDbSnapshotClient _cosmosDbClient; readonly Type _aggregateType = typeof(T); readonly string _aggregateName; @@ -41,17 +41,19 @@ public sealed partial class CosmosDbSnapshotEventStore : ICosmosDbSnapshotEve /// The non-queryable event store used to persist the aggregate's events. /// The options used to configure the Cosmos DB connection, container, and indexing. /// The telemetry used to record snapshot metrics. - /// Optional, a pre-configured ; when null, one is created from the options. + /// Optional, overrides applied to the Cosmos DB client, for endpoints - such as the emulator - the default configuration cannot reach. /// Optional, the strategy used to decide when a snapshot should be written; defaults to . /// Optional, the selector used to resolve a snapshot strategy for the aggregate. + /// Optional tenant scope applied to snapshot reads and writes. public CosmosDbSnapshotEventStore( // Explicitly request a non-queryable event store. INonQueryableEventStore eventStore, IOptions cosmosDbEventStoreOptions, ICosmosDbSnapshotEventStoreTelemetry telemetry, - CosmosClient? cosmosClient = null, + CosmosDbClientOverrides? clientOverrides = null, ISnapshotStrategy? snapshotStrategy = null, - ISnapshotStrategySelector? snapshotStrategySelector = null + ISnapshotStrategySelector? snapshotStrategySelector = null, + ICurrentTenant? currentTenant = null ) { _eventStore = eventStore; @@ -60,9 +62,12 @@ public CosmosDbSnapshotEventStore( _snapshotStrategy = snapshotStrategy ?? new AlwaysSnapshotStrategy(); _snapshotStrategySelector = snapshotStrategySelector; - _partitionKey = new(GetAggregateTypeName()); - - _cosmosDbClient = new CosmosDbClient(_cosmosDbEventStoreOptions.Value, cosmosClient: cosmosClient); + _cosmosDbClient = new( + _cosmosDbEventStoreOptions.Value, + GetAggregateTypeName(), + clientOverrides, + currentTenant: currentTenant + ); _aggregateName = TypeNameHelper.GetName(_aggregateType, "Aggregate"); } @@ -75,13 +80,17 @@ public async Task SnapshotAsync(T aggregate, CancellationToken cancellationToken { ArgumentNullException.ThrowIfNull(aggregate, nameof(aggregate)); - var result = await _cosmosDbClient.UpsertAsync(aggregate, _partitionKey, cancellationToken); - if (result.IsSuccessStatusCode) + var result = await _cosmosDbClient.UpsertAsync(aggregate, aggregate.Details.Id, cancellationToken); + if (result) _telemetry.SnapshotCreated(_aggregateName); } string GetAggregateTypeName() => AggregateTypeNames.GetOrAdd(_aggregateType, _ => new T().AggregateType); + // Used by the test fixtures to tear down the container they provisioned. + internal Task DeleteContainerAsync(CancellationToken cancellationToken = default) => + _cosmosDbClient.DeleteContainerAsync(cancellationToken); + /// public async ValueTask DisposeAsync() { diff --git a/src/src/SqlServer/Client/JsonScalarValueConverter.cs b/src/src/EntityFrameworkCore/Conversion/JsonScalarValueConverter.cs similarity index 57% rename from src/src/SqlServer/Client/JsonScalarValueConverter.cs rename to src/src/EntityFrameworkCore/Conversion/JsonScalarValueConverter.cs index 8e3df266..9562fbbc 100644 --- a/src/src/SqlServer/Client/JsonScalarValueConverter.cs +++ b/src/src/EntityFrameworkCore/Conversion/JsonScalarValueConverter.cs @@ -2,15 +2,23 @@ using System.Reflection; using System.Text.Json; using Microsoft.EntityFrameworkCore.Storage.ValueConversion; -using Purview.ValueObjects.Serialization; -namespace Purview.EventSourcing.SqlServer.Client; +namespace Purview.EventSourcing.EntityFrameworkCore.Conversion; +/// +/// Converts a [Scalar] value object whose underlying value is not primitive-like to and from its +/// JSON representation. +/// +/// The scalar value object type. +/// The underlying scalar type. sealed class JsonScalarValueConverter : ValueConverter { - static readonly PropertyInfo ScalarProperty = GetScalarProperty(); + static readonly PropertyInfo ScalarProperty = ScalarValueObjects.GetScalarProperty(typeof(TScalarObject)); static readonly Func Creator = BuildCreator(); + /// + /// Creates a new . + /// public JsonScalarValueConverter() : base(BuildToProviderExpression(), BuildFromProviderExpression()) { } @@ -54,39 +62,12 @@ static TScalarObject Deserialize(string value) return Creator(scalarValue); } - static PropertyInfo GetScalarProperty() - { - var scalarType = typeof(TScalarObject); - var scalarAttribute = - scalarType.GetCustomAttribute() - ?? throw new InvalidOperationException($"{scalarType.Name} must be annotated with [Scalar]."); - - return scalarType.GetProperty(scalarAttribute.PropertyName, BindingFlags.Instance | BindingFlags.Public) - ?? throw new InvalidOperationException( - $"'{scalarType.Name}' missing scalar property '{scalarAttribute.PropertyName}'." - ); - } - static Func BuildCreator() { var scalarType = typeof(TScalarObject); var scalarPropertyType = typeof(TScalar); - var scalarAttribute = - scalarType.GetCustomAttribute() - ?? throw new InvalidOperationException($"{scalarType.Name} must be annotated with [Scalar]."); - - var preferredFactoryName = - scalarAttribute.DeserializationMode == ValueObjectDeserializationMode.Strict ? "Create" : "Hydrate"; - var secondaryFactoryName = preferredFactoryName == "Hydrate" ? "Create" : "Hydrate"; - - var create = - scalarType.GetMethod(preferredFactoryName, BindingFlags.Public | BindingFlags.Static, [scalarPropertyType]) - ?? scalarType.GetMethod( - secondaryFactoryName, - BindingFlags.Public | BindingFlags.Static, - [scalarPropertyType] - ); + var create = ScalarValueObjects.FindFactoryMethod(scalarType, scalarPropertyType); if (create is not null) return value => (TScalarObject)create.Invoke(null, [value])!; @@ -94,10 +75,7 @@ static Func BuildCreator() scalarType.GetConstructor( BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic, [scalarPropertyType] - ) - ?? throw new InvalidOperationException( - $"{scalarType.Name} must expose static {preferredFactoryName}({scalarPropertyType.Name}), static {secondaryFactoryName}({scalarPropertyType.Name}), or ctor({scalarPropertyType.Name})." - ); + ) ?? throw ScalarValueObjects.CreateMissingFactoryException(scalarType, scalarPropertyType); return value => (TScalarObject)ctor.Invoke([value]); } diff --git a/src/src/Postgres/Client/JsonValueObjectCollectionConverter.cs b/src/src/EntityFrameworkCore/Conversion/JsonValueObjectCollectionConverter.cs similarity index 66% rename from src/src/Postgres/Client/JsonValueObjectCollectionConverter.cs rename to src/src/EntityFrameworkCore/Conversion/JsonValueObjectCollectionConverter.cs index af50683d..7dff702c 100644 --- a/src/src/Postgres/Client/JsonValueObjectCollectionConverter.cs +++ b/src/src/EntityFrameworkCore/Conversion/JsonValueObjectCollectionConverter.cs @@ -1,12 +1,13 @@ using Microsoft.EntityFrameworkCore.Storage.ValueConversion; using Purview.EventSourcing.Serialization; -namespace Purview.EventSourcing.Postgres.Client; +namespace Purview.EventSourcing.EntityFrameworkCore.Conversion; /// -/// Converts a collection of value objects to and from its JSON-serialized string representation for storage in PostgreSQL. +/// Persists a collection - or any other member EF cannot map structurally - as a JSON string using the +/// event store's serialization settings. /// -/// The collection type being converted. +/// The collection type. sealed class JsonValueObjectCollectionConverter : ValueConverter { /// diff --git a/src/src/Postgres/Client/OpaqueJsonValueConverter.cs b/src/src/EntityFrameworkCore/Conversion/OpaqueJsonValueConverter.cs similarity index 72% rename from src/src/Postgres/Client/OpaqueJsonValueConverter.cs rename to src/src/EntityFrameworkCore/Conversion/OpaqueJsonValueConverter.cs index e641932d..ca1e755e 100644 --- a/src/src/Postgres/Client/OpaqueJsonValueConverter.cs +++ b/src/src/EntityFrameworkCore/Conversion/OpaqueJsonValueConverter.cs @@ -2,13 +2,12 @@ using Microsoft.EntityFrameworkCore.Storage.ValueConversion; using Purview.EventSourcing.Serialization; -namespace Purview.EventSourcing.Postgres.Client; +namespace Purview.EventSourcing.EntityFrameworkCore.Conversion; /// -/// Converts a value marked with the EF opaque attribute to and from its JSON-serialized string -/// representation for storage in PostgreSQL. +/// Persists a member marked [EFOpaque] as a JSON string, keeping it out of query translation. /// -/// The opaque value type being converted. +/// The member type. sealed class OpaqueJsonValueConverter : ValueConverter { /// diff --git a/src/src/EntityFrameworkCore/Conversion/ScalarValueConverter.cs b/src/src/EntityFrameworkCore/Conversion/ScalarValueConverter.cs new file mode 100644 index 00000000..a964831f --- /dev/null +++ b/src/src/EntityFrameworkCore/Conversion/ScalarValueConverter.cs @@ -0,0 +1,54 @@ +using System.Linq.Expressions; +using System.Reflection; +using Microsoft.EntityFrameworkCore.Storage.ValueConversion; + +namespace Purview.EventSourcing.EntityFrameworkCore.Conversion; + +/// +/// Converts a [Scalar] value object to and from its underlying scalar value, so the member is +/// stored - and queried - as the primitive it wraps. +/// +/// The scalar value object type. +/// The underlying scalar type. +sealed class ScalarValueConverter : ValueConverter +{ + /// + /// Creates a new . + /// + public ScalarValueConverter() + : base(BuildToProviderExpression(), BuildFromProviderExpression()) { } + + static Expression> BuildToProviderExpression() + { + var scalarProperty = ScalarValueObjects.GetScalarProperty(typeof(TScalarObject)); + var source = Expression.Parameter(typeof(TScalarObject), "value"); + var body = Expression.Property(source, scalarProperty); + return Expression.Lambda>(body, source); + } + + static Expression> BuildFromProviderExpression() + { + var source = Expression.Parameter(typeof(TScalar), "value"); + var body = BuildCreatorExpression(source); + return Expression.Lambda>(body, source); + } + + static Expression BuildCreatorExpression(ParameterExpression source) + { + var scalarType = typeof(TScalarObject); + var scalarPropertyType = typeof(TScalar); + + var create = ScalarValueObjects.FindFactoryMethod(scalarType, scalarPropertyType); + if (create is not null) + return Expression.Call(create, source); + + var ctor = scalarType.GetConstructor( + BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic, + [scalarPropertyType] + ); + + return ctor is null + ? throw ScalarValueObjects.CreateMissingFactoryException(scalarType, scalarPropertyType) + : (Expression)Expression.New(ctor, source); + } +} diff --git a/src/src/EntityFrameworkCore/Conversion/ScalarValueObjects.cs b/src/src/EntityFrameworkCore/Conversion/ScalarValueObjects.cs new file mode 100644 index 00000000..a99fc8dd --- /dev/null +++ b/src/src/EntityFrameworkCore/Conversion/ScalarValueObjects.cs @@ -0,0 +1,69 @@ +using System.Reflection; +using Purview.ValueObjects.Serialization; + +namespace Purview.EventSourcing.EntityFrameworkCore.Conversion; + +/// +/// Reflection helpers shared by the scalar value-object converters, resolving the member that carries the +/// scalar value and the factory used to rebuild the value object from it. +/// +static class ScalarValueObjects +{ + /// + /// Gets the property identified by the type's . + /// + /// The scalar value object type. + /// The property carrying the scalar value. + public static PropertyInfo GetScalarProperty(Type scalarType) + { + var scalarAttribute = GetScalarAttribute(scalarType); + + return scalarType.GetProperty(scalarAttribute.PropertyName, BindingFlags.Instance | BindingFlags.Public) + ?? throw new InvalidOperationException( + $"'{scalarType.Name}' missing scalar property '{scalarAttribute.PropertyName}'." + ); + } + + /// + /// Finds the static factory used to rebuild the value object, honouring the deserialization mode + /// declared by the type's . + /// + /// The scalar value object type. + /// The underlying scalar type. + /// The factory method, or when the type exposes none. + public static MethodInfo? FindFactoryMethod(Type scalarType, Type scalarPropertyType) + { + var (preferred, secondary) = GetFactoryNames(scalarType); + + return scalarType.GetMethod(preferred, BindingFlags.Public | BindingFlags.Static, [scalarPropertyType]) + ?? scalarType.GetMethod(secondary, BindingFlags.Public | BindingFlags.Static, [scalarPropertyType]); + } + + /// + /// Creates the exception describing the factory members a scalar value object must expose. + /// + /// The scalar value object type. + /// The underlying scalar type. + /// The exception to throw. + public static InvalidOperationException CreateMissingFactoryException(Type scalarType, Type scalarPropertyType) + { + var (preferred, secondary) = GetFactoryNames(scalarType); + + return new( + $"{scalarType.Name} must expose static {preferred}({scalarPropertyType.Name}), static {secondary}({scalarPropertyType.Name}), or ctor({scalarPropertyType.Name})." + ); + } + + static (string Preferred, string Secondary) GetFactoryNames(Type scalarType) + { + var scalarAttribute = GetScalarAttribute(scalarType); + var preferred = + scalarAttribute.DeserializationMode == ValueObjectDeserializationMode.Strict ? "Create" : "Hydrate"; + + return (preferred, preferred == "Hydrate" ? "Create" : "Hydrate"); + } + + static ScalarAttribute GetScalarAttribute(Type scalarType) => + scalarType.GetCustomAttribute() + ?? throw new InvalidOperationException($"{scalarType.Name} must be annotated with [Scalar]."); +} diff --git a/src/src/EntityFrameworkCore/EntityFrameworkCore.csproj b/src/src/EntityFrameworkCore/EntityFrameworkCore.csproj new file mode 100644 index 00000000..25329fbf --- /dev/null +++ b/src/src/EntityFrameworkCore/EntityFrameworkCore.csproj @@ -0,0 +1,25 @@ + + + true + Purview Event Sourcing Entity Framework Core Support + Shared Entity Framework Core mapping, conversion, and query translation used by the Purview EventSourcing SQL Server, PostgreSQL, and Cosmos DB providers. + $(PackageTags);purview;dotnet;event-sourcing;event-store;entity-framework-core;efcore;snapshot; + + + + + + + + + + + + diff --git a/src/src/EntityFrameworkCore/Mapping/ISnapshotGraphBuilder.cs b/src/src/EntityFrameworkCore/Mapping/ISnapshotGraphBuilder.cs new file mode 100644 index 00000000..d580274a --- /dev/null +++ b/src/src/EntityFrameworkCore/Mapping/ISnapshotGraphBuilder.cs @@ -0,0 +1,129 @@ +using Microsoft.EntityFrameworkCore.Metadata.Builders; + +namespace Purview.EventSourcing.EntityFrameworkCore.Mapping; + +/// +/// The subset of the EF builder API the snapshot graph walker needs, so the same walk can configure an +/// entity root (document stores), a complex property, or an element of a complex collection. +/// +interface ISnapshotGraphBuilder +{ + /// Excludes a member from the model. + /// The member name. + void Ignore(string propertyName); + + /// Maps a member as a scalar property. + /// The member type. + /// The member name. + void Property(Type propertyType, string propertyName); + + /// Maps a member as a scalar property converted by . + /// The member type. + /// The member name. + /// The closed value-converter type. + void PropertyWithConversion(Type propertyType, string propertyName, Type converterType); + + /// Maps a member as a collection of primitives. + /// The collection type. + /// The member name. + void PrimitiveCollection(Type propertyType, string propertyName); + + /// Maps a member as a nested complex type. + /// The member type. + /// The member name. + /// Configures the nested type. + void ComplexProperty(Type propertyType, string propertyName, Action configure); + + /// Maps a member as a collection of nested complex types. + /// The collection type. + /// The member name. + /// Configures the element type. + void ComplexCollection(Type propertyType, string propertyName, Action configure); +} + +/// +/// Adapts the EF builders to . +/// +static class SnapshotGraphBuilder +{ + /// Adapts an entity root. + /// The entity builder. + /// The adapted builder. + public static ISnapshotGraphBuilder For(EntityTypeBuilder builder) => new EntityAdapter(builder); + + /// Adapts a complex property. + /// The complex property builder. + /// The adapted builder. + public static ISnapshotGraphBuilder For(ComplexPropertyBuilder builder) => new ComplexPropertyAdapter(builder); + + /// Adapts a complex collection. + /// The complex collection builder. + /// The adapted builder. + public static ISnapshotGraphBuilder For(ComplexCollectionBuilder builder) => new ComplexCollectionAdapter(builder); + + sealed class EntityAdapter(EntityTypeBuilder builder) : ISnapshotGraphBuilder + { + public void Ignore(string propertyName) => builder.Ignore(propertyName); + + public void Property(Type propertyType, string propertyName) => builder.Property(propertyType, propertyName); + + public void PropertyWithConversion(Type propertyType, string propertyName, Type converterType) => + builder.Property(propertyType, propertyName).HasConversion(converterType); + + public void PrimitiveCollection(Type propertyType, string propertyName) => + builder.PrimitiveCollection(propertyType, propertyName); + + public void ComplexProperty(Type propertyType, string propertyName, Action configure) => + builder.ComplexProperty(propertyType, propertyName, nested => configure(For(nested))); + + public void ComplexCollection( + Type propertyType, + string propertyName, + Action configure + ) => builder.ComplexCollection(propertyType, propertyName, nested => configure(For(nested))); + } + + sealed class ComplexPropertyAdapter(ComplexPropertyBuilder builder) : ISnapshotGraphBuilder + { + public void Ignore(string propertyName) => builder.Ignore(propertyName); + + public void Property(Type propertyType, string propertyName) => builder.Property(propertyType, propertyName); + + public void PropertyWithConversion(Type propertyType, string propertyName, Type converterType) => + builder.Property(propertyType, propertyName).HasConversion(converterType); + + public void PrimitiveCollection(Type propertyType, string propertyName) => + builder.PrimitiveCollection(propertyType, propertyName); + + public void ComplexProperty(Type propertyType, string propertyName, Action configure) => + builder.ComplexProperty(propertyType, propertyName, nested => configure(For(nested))); + + public void ComplexCollection( + Type propertyType, + string propertyName, + Action configure + ) => builder.ComplexCollection(propertyType, propertyName, nested => configure(For(nested))); + } + + sealed class ComplexCollectionAdapter(ComplexCollectionBuilder builder) : ISnapshotGraphBuilder + { + public void Ignore(string propertyName) => builder.Ignore(propertyName); + + public void Property(Type propertyType, string propertyName) => builder.Property(propertyType, propertyName); + + public void PropertyWithConversion(Type propertyType, string propertyName, Type converterType) => + builder.Property(propertyType, propertyName).HasConversion(converterType); + + public void PrimitiveCollection(Type propertyType, string propertyName) => + builder.PrimitiveCollection(propertyType, propertyName); + + public void ComplexProperty(Type propertyType, string propertyName, Action configure) => + builder.ComplexProperty(propertyType, propertyName, nested => configure(For(nested))); + + public void ComplexCollection( + Type propertyType, + string propertyName, + Action configure + ) => builder.ComplexCollection(propertyType, propertyName, nested => configure(For(nested))); + } +} diff --git a/src/src/EntityFrameworkCore/Mapping/SnapshotModelCacheKeyFactory.cs b/src/src/EntityFrameworkCore/Mapping/SnapshotModelCacheKeyFactory.cs new file mode 100644 index 00000000..3152db18 --- /dev/null +++ b/src/src/EntityFrameworkCore/Mapping/SnapshotModelCacheKeyFactory.cs @@ -0,0 +1,36 @@ +using Microsoft.EntityFrameworkCore; +using Microsoft.EntityFrameworkCore.Infrastructure; + +namespace Purview.EventSourcing.EntityFrameworkCore.Mapping; + +/// +/// Implemented by a snapshot whose model varies with its options - the aggregate +/// being mapped, and the table or container it is stored in. +/// +interface ISnapshotModelCacheKeySource +{ + /// + /// Creates the key identifying this context's model. + /// + /// Whether the model is being built for design-time use. + /// The model cache key. + object CreateModelCacheKey(bool designTime); +} + +/// +/// Keys the EF model cache on the snapshot context's own identity, so two contexts that map different +/// aggregates - or the same aggregate into a different table or container - do not share a model. +/// +sealed class SnapshotModelCacheKeyFactory : IModelCacheKeyFactory +{ + /// + /// Creates the model cache key for . + /// + /// The context. + /// Whether the model is being built for design-time use. + /// The model cache key. + public object Create(DbContext context, bool designTime) => + context is ISnapshotModelCacheKeySource source + ? source.CreateModelCacheKey(designTime) + : (context?.GetType(), designTime); +} diff --git a/src/src/EntityFrameworkCore/Mapping/SnapshotModelMapper.cs b/src/src/EntityFrameworkCore/Mapping/SnapshotModelMapper.cs new file mode 100644 index 00000000..5dd2c31a --- /dev/null +++ b/src/src/EntityFrameworkCore/Mapping/SnapshotModelMapper.cs @@ -0,0 +1,292 @@ +using System.Reflection; +using Microsoft.EntityFrameworkCore; +using Purview.EventSourcing.EntityFrameworkCore.Conversion; + +namespace Purview.EventSourcing.EntityFrameworkCore.Mapping; + +/// +/// Maps an aggregate snapshot graph onto an Entity Framework model. The same walk is used by every +/// EF-backed provider so an aggregate that persists on one provider persists identically on the others. +/// +static class SnapshotModelMapper +{ + /// + /// Registers the conversions for every [Scalar] value object reachable from + /// , so scalar members are stored as the value they wrap. + /// + /// The model configuration builder. + /// The aggregate type. + public static void RegisterScalarValueObjectConversions( + ModelConfigurationBuilder configurationBuilder, + Type rootType + ) + { + ArgumentNullException.ThrowIfNull(configurationBuilder); + ArgumentNullException.ThrowIfNull(rootType); + + HashSet visited = []; + RegisterScalarValueObjectConversionsRecursive(configurationBuilder, rootType, visited); + } + + /// + /// Validates that every member reachable from can be persisted, throwing a + /// message that names the offending member rather than failing later inside EF. + /// + /// The aggregate type. + public static void ValidateAggregatePayloadShape(Type type) + { + ArgumentNullException.ThrowIfNull(type); + + HashSet visited = []; + ValidateAggregatePayloadShapeRecursive(type, visited); + } + + /// + /// Configures the snapshot graph for onto . + /// + /// The builder owning the members. + /// The type being mapped. + public static void ConfigureGraph(ISnapshotGraphBuilder builder, Type type) + { + ArgumentNullException.ThrowIfNull(builder); + ArgumentNullException.ThrowIfNull(type); + + HashSet visited = []; + ConfigureGraphRecursive(builder, type, visited); + } + + static void RegisterScalarValueObjectConversionsRecursive( + ModelConfigurationBuilder configurationBuilder, + Type type, + HashSet visited + ) + { + type = Nullable.GetUnderlyingType(type) ?? type; + if (!visited.Add(type)) + return; + + if (SnapshotTypes.IsScalarValueObjectType(type)) + { + RegisterScalarValueObjectConversion(configurationBuilder, type); + return; + } + + if (!SnapshotTypes.ShouldInspectType(type)) + return; + + foreach (var property in type.GetProperties(BindingFlags.Instance | BindingFlags.Public)) + { + var propertyType = Nullable.GetUnderlyingType(property.PropertyType) ?? property.PropertyType; + + if (propertyType == typeof(string) || propertyType == typeof(byte[])) + continue; + + if (SnapshotTypes.TryGetEnumerableElementType(propertyType, out var elementType)) + { + RegisterScalarValueObjectConversionsRecursive(configurationBuilder, elementType, visited); + continue; + } + + RegisterScalarValueObjectConversionsRecursive(configurationBuilder, propertyType, visited); + } + } + + static void RegisterScalarValueObjectConversion(ModelConfigurationBuilder configurationBuilder, Type scalarType) + { + var scalarProperty = ScalarValueObjects.GetScalarProperty(scalarType); + var scalarPropertyType = scalarProperty.PropertyType; + var converterType = SnapshotTypes.IsPrimitiveLike(scalarPropertyType) + ? typeof(ScalarValueConverter<,>).MakeGenericType(scalarType, scalarPropertyType) + : typeof(JsonScalarValueConverter<,>).MakeGenericType(scalarType, scalarPropertyType); + + configurationBuilder.Properties(scalarType, builder => builder.HaveConversion(converterType)); + } + + static void ConfigureGraphRecursive(ISnapshotGraphBuilder builder, Type type, HashSet visited) + { + type = Nullable.GetUnderlyingType(type) ?? type; + if (!SnapshotTypes.ShouldInspectType(type) || !visited.Add(type)) + return; + + foreach (var property in type.GetProperties(BindingFlags.Instance | BindingFlags.Public)) + { + if (SnapshotTypes.ShouldSkipJsonProperty(type, property)) + { + builder.Ignore(property.Name); + continue; + } + + var propertyType = Nullable.GetUnderlyingType(property.PropertyType) ?? property.PropertyType; + + if (propertyType == typeof(string) || propertyType == typeof(byte[])) + { + MapReadOnlyConstructorBoundProperty(builder, type, property, propertyType); + continue; + } + + if (SnapshotTypes.IsScalarValueObjectType(propertyType)) + { + MapReadOnlyConstructorBoundProperty(builder, type, property, propertyType); + continue; + } + + if (SnapshotTypes.HasEfOpaqueAttribute(property)) + { + builder.PropertyWithConversion( + propertyType, + property.Name, + typeof(OpaqueJsonValueConverter<>).MakeGenericType(propertyType) + ); + continue; + } + + if (SnapshotTypes.TryGetEnumerableElementType(propertyType, out var elementType)) + { + if (SnapshotTypes.IsStructValueObjectType(elementType)) + { + MapAsJsonProperty(builder, propertyType, property.Name); + continue; + } + + if (SnapshotTypes.IsPrimitiveLike(elementType) || SnapshotTypes.IsScalarValueObjectType(elementType)) + builder.PrimitiveCollection(propertyType, property.Name); + else if (SnapshotTypes.ShouldInspectType(elementType)) + builder.ComplexCollection( + propertyType, + property.Name, + nested => ConfigureGraphRecursive(nested, elementType, [.. visited]) + ); + else + throw SnapshotTypes.CreateUnsupportedShapeException(type, property); + + continue; + } + + if ( + SnapshotTypes.IsDictionaryLikeType(propertyType) + || SnapshotTypes.IsJsonConvertibleCollectionType(propertyType) + ) + { + MapAsJsonProperty(builder, propertyType, property.Name); + continue; + } + + if (SnapshotTypes.IsCollectionLikeType(propertyType)) + throw SnapshotTypes.CreateUnsupportedCollectionTypeException(type, property, propertyType); + + if (SnapshotTypes.ShouldOwnType(propertyType)) + { + builder.ComplexProperty( + propertyType, + property.Name, + nested => ConfigureGraphRecursive(nested, propertyType, [.. visited]) + ); + continue; + } + + if (SnapshotTypes.IsPrimitiveLike(propertyType)) + { + MapReadOnlyConstructorBoundProperty(builder, type, property, propertyType); + continue; + } + + throw SnapshotTypes.CreateUnsupportedShapeException(type, property); + } + } + + static void MapAsJsonProperty(ISnapshotGraphBuilder builder, Type propertyType, string propertyName) => + builder.PropertyWithConversion( + propertyType, + propertyName, + typeof(JsonValueObjectCollectionConverter<>).MakeGenericType(propertyType) + ); + + // EF discovers settable members on its own; a read-only member is only mapped when a constructor + // parameter can supply it during materialization. + static void MapReadOnlyConstructorBoundProperty( + ISnapshotGraphBuilder builder, + Type containingType, + PropertyInfo property, + Type propertyType + ) + { + if ( + property.GetSetMethod(true) is null + && SnapshotTypes.HasBindableConstructorParameter(containingType, property) + ) + builder.Property(propertyType, property.Name); + } + + static void ValidateAggregatePayloadShapeRecursive(Type type, HashSet visited) + { + type = Nullable.GetUnderlyingType(type) ?? type; + if (!SnapshotTypes.ShouldInspectType(type) || !visited.Add(type)) + return; + + foreach (var property in type.GetProperties(BindingFlags.Instance | BindingFlags.Public)) + { + if (SnapshotTypes.ShouldSkipJsonProperty(type, property)) + continue; + + var propertyType = Nullable.GetUnderlyingType(property.PropertyType) ?? property.PropertyType; + + if (propertyType == typeof(string) || propertyType == typeof(byte[])) + continue; + + if (SnapshotTypes.IsScalarValueObjectType(propertyType)) + continue; + + if (SnapshotTypes.HasEfOpaqueAttribute(property)) + continue; + + if (SnapshotTypes.TryGetEnumerableElementType(propertyType, out var elementType)) + { + if ( + !SnapshotTypes.IsPrimitiveLike(elementType) + && !SnapshotTypes.IsScalarValueObjectType(elementType) + && !SnapshotTypes.IsStructValueObjectType(elementType) + ) + { + if (!SnapshotTypes.ShouldInspectType(elementType)) + throw SnapshotTypes.CreateUnsupportedShapeException(type, property); + + EnsureValueTypeMemberIsWritable(type, property); + ValidateAggregatePayloadShapeRecursive(elementType, visited); + } + + continue; + } + + if (SnapshotTypes.IsReadOnlyCollectionType(propertyType)) + throw SnapshotTypes.CreateUnsupportedCollectionTypeException(type, property, propertyType); + + if ( + SnapshotTypes.IsDictionaryLikeType(propertyType) + || SnapshotTypes.IsJsonConvertibleCollectionType(propertyType) + ) + continue; + + if (SnapshotTypes.IsCollectionLikeType(propertyType)) + throw SnapshotTypes.CreateUnsupportedCollectionTypeException(type, property, propertyType); + + if (SnapshotTypes.ShouldOwnType(propertyType)) + { + EnsureValueTypeMemberIsWritable(type, property); + ValidateAggregatePayloadShapeRecursive(propertyType, visited); + continue; + } + + if (!SnapshotTypes.IsPrimitiveLike(propertyType)) + throw SnapshotTypes.CreateUnsupportedShapeException(type, property); + } + } + + // EF materializes value-type JSON members through their backing field, and it cannot rebuild an assignment to a + // read-only member while fixing up a value type, which fails snapshot query compilation with + // "Expression must be writeable" (analyzer diagnostic EVENTSTOREEF004). + static void EnsureValueTypeMemberIsWritable(Type type, PropertyInfo property) + { + if (type.IsValueType && property.GetSetMethod(nonPublic: true) is null) + throw SnapshotTypes.CreateUnsupportedValueTypeMemberException(type, property); + } +} diff --git a/src/src/EntityFrameworkCore/Mapping/SnapshotTypes.cs b/src/src/EntityFrameworkCore/Mapping/SnapshotTypes.cs new file mode 100644 index 00000000..8cca5283 --- /dev/null +++ b/src/src/EntityFrameworkCore/Mapping/SnapshotTypes.cs @@ -0,0 +1,239 @@ +using System.Reflection; +using Purview.ValueObjects.Serialization; + +namespace Purview.EventSourcing.EntityFrameworkCore.Mapping; + +/// +/// The type-shape rules shared by every Entity Framework snapshot provider: which members are mapped, +/// which are skipped, and which shapes cannot be persisted at all. +/// +static class SnapshotTypes +{ + // Must match the attribute emitted by Purview.EventSourcing.EntityFrameworkCore.SourceGenerator + // (TypeLibrary.EFOpaqueAttribute) and applied by consumers as [EFOpaque]. + const string EFOpaqueAttributeFullName = "Purview.EventSourcing.EntityFrameworkCore.EFOpaqueAttribute"; + + /// Determines whether a member is marked [EFOpaque]. + /// The member. + /// when the member is opaque. + public static bool HasEfOpaqueAttribute(MemberInfo member) => + member.CustomAttributes.Any(attribute => attribute.AttributeType.FullName == EFOpaqueAttributeFullName); + + /// Determines whether a type should be walked rather than treated as a leaf. + /// The type. + /// when the type should be inspected. + public static bool ShouldInspectType(Type type) => + !type.IsPrimitive + && !type.IsEnum + && type != typeof(string) + && type != typeof(decimal) + && type != typeof(Guid) + && type != typeof(DateTime) + && type != typeof(DateTimeOffset) + && type != typeof(DateOnly) + && type != typeof(TimeOnly) + && type != typeof(TimeSpan) + && (type.Namespace is null || !type.Namespace.StartsWith("System", StringComparison.Ordinal)); + + /// Determines whether a type should be mapped as a nested complex type. + /// The type. + /// when the type should be owned. + public static bool ShouldOwnType(Type type) => + ShouldInspectType(type) && (type.IsClass || (type.IsValueType && !type.IsPrimitive && !type.IsEnum)); + + /// Determines whether a member is excluded from the snapshot payload. + /// The declaring type. + /// The member. + /// when the member is not persisted. + public static bool ShouldSkipJsonProperty(Type containingType, PropertyInfo property) => + property.GetCustomAttribute() is not null + || property.GetGetMethod(true) is null + || (property.GetSetMethod(true) is null && !HasBindableConstructorParameter(containingType, property)); + + /// Determines whether a member is bound through a constructor parameter. + /// The declaring type. + /// The member. + /// when a matching constructor parameter exists. + public static bool HasBindableConstructorParameter(Type containingType, PropertyInfo property) + { + var constructors = containingType.GetConstructors( + BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic + ); + foreach (var constructor in constructors) + { + foreach (var parameter in constructor.GetParameters()) + { + if ( + string.Equals(parameter.Name, property.Name, StringComparison.OrdinalIgnoreCase) + && parameter.ParameterType == property.PropertyType + ) + return true; + } + } + + return false; + } + + /// Determines whether a type is stored as a single scalar value. + /// The type. + /// when the type is primitive-like. + public static bool IsPrimitiveLike(Type type) => + type.IsPrimitive + || type.IsEnum + || type == typeof(string) + || type == typeof(decimal) + || type == typeof(Uri) + || type == typeof(Guid) + || type == typeof(DateTime) + || type == typeof(DateTimeOffset) + || type == typeof(DateOnly) + || type == typeof(TimeOnly) + || type == typeof(TimeSpan) + || type == typeof(byte[]); + + /// Determines whether a type is a struct value object. + /// The type. + /// when the type is a value-type value object. + public static bool IsStructValueObjectType(Type type) => + type.IsValueType && type.GetCustomAttribute() is not null; + + /// Determines whether a type is a scalar value object. + /// The type. + /// when the type carries . + public static bool IsScalarValueObjectType(Type type) => type.GetCustomAttribute() is not null; + + /// Gets the element type of an event-store collection member. + /// The member type. + /// The element type, when the member is an event-store collection. + /// when an element type was resolved. + public static bool TryGetEnumerableElementType(Type type, out Type elementType) + { + elementType = null!; + + if (!type.IsGenericType) + return false; + + if (!IsEventStoreCollectionType(type)) + return false; + + elementType = type.GetGenericArguments()[0]; + return true; + } + + /// Determines whether a type is an EventStoreList<T> or EventStoreSet<T>. + /// The type. + /// for event-store collections. + public static bool IsEventStoreCollectionType(Type type) => + type.IsGenericType + && type.GetGenericTypeDefinition() is var genericDefinition + && (genericDefinition == typeof(EventStoreList<>) || genericDefinition == typeof(EventStoreSet<>)); + + /// Determines whether a type is a collection of any kind. + /// The type. + /// for collection-like types. + public static bool IsCollectionLikeType(Type type) + { + if (type == typeof(string) || type == typeof(byte[])) + return false; + + if (type.IsArray) + return true; + + if (!type.IsGenericType) + return false; + + // Test for our own collection types or if the type implements IEnumerable somewhere... + return IsEventStoreCollectionType(type) + || type.GetInterfaces().Any(i => i.IsGenericType && i.GetGenericTypeDefinition() == typeof(IEnumerable<>)); + } + + /// Determines whether a type is a read-only collection interface. + /// The type. + /// for read-only collection interfaces. + public static bool IsReadOnlyCollectionType(Type type) + { + if (!type.IsGenericType) + return false; + + var genericTypeDefinition = type.GetGenericTypeDefinition(); + return genericTypeDefinition == typeof(IReadOnlyList<>) + || genericTypeDefinition == typeof(IReadOnlyCollection<>); + } + + /// Determines whether a type is a dictionary. + /// The type. + /// for dictionary-like types. + public static bool IsDictionaryLikeType(Type type) + { + if (!type.IsGenericType) + return false; + + var genericTypeDefinition = type.GetGenericTypeDefinition(); + if ( + genericTypeDefinition == typeof(Dictionary<,>) + || genericTypeDefinition == typeof(IDictionary<,>) + || genericTypeDefinition == typeof(IReadOnlyDictionary<,>) + ) + return true; + + // Test if the type implements IDictionary or IReadOnlyDictionary somewhere... + return type.GetInterfaces() + .Any(i => i.IsGenericType && i.GetGenericTypeDefinition() == typeof(IReadOnlyDictionary<,>)); + } + + /// Determines whether a collection can be persisted as JSON rather than structurally. + /// The type. + /// when the collection is JSON-convertible. + public static bool IsJsonConvertibleCollectionType(Type type) + { + if (type == typeof(string) || type == typeof(byte[])) + return false; + + if (!type.IsGenericType || IsEventStoreCollectionType(type) || IsDictionaryLikeType(type)) + return false; + + if (type.GetGenericTypeDefinition() == typeof(IEnumerable<>)) + return true; + + // Test if the type implements IEnumerable somewhere... + return type.GetInterfaces().Any(i => i.IsGenericType && i.GetGenericTypeDefinition() == typeof(IEnumerable<>)); + } + + /// Creates the exception describing an unmappable member. + /// The declaring type. + /// The member. + /// The exception to throw. + public static InvalidOperationException CreateUnsupportedShapeException(Type containingType, MemberInfo member) => + new( + $"{containingType.Name}.{member.Name} cannot be mapped into the snapshot JSON payload. " + + "Supported members are primitive types, [Scalar] value objects, complex types, and EventStoreList/EventStoreSet collections of those shapes." + ); + + /// Creates the exception describing an unsupported collection member. + /// The declaring type. + /// The member. + /// The collection type. + /// The exception to throw. + public static InvalidOperationException CreateUnsupportedCollectionTypeException( + Type containingType, + MemberInfo member, + Type collectionType + ) => + new( + $"{containingType.Name}.{member.Name} uses unsupported collection type '{collectionType.Name}'. " + + "Collection and array members must use Purview.EventSourcing.EventStoreList or Purview.EventSourcing.EventStoreSet." + ); + + /// Creates the exception describing a read-only member of a value type. + /// The declaring type. + /// The member. + /// The exception to throw. + public static InvalidOperationException CreateUnsupportedValueTypeMemberException( + Type containingType, + MemberInfo member + ) => + new( + $"{containingType.Name}.{member.Name} is a read-only complex member of value type '{containingType.Name}' and cannot be assigned during snapshot JSON materialization, which fails queries with 'Expression must be writeable'. " + + "Add an 'init' or 'set' accessor, mark the member [JsonIgnore] to exclude it from the snapshot, or mark it [EFOpaque] to persist it as non-queryable JSON." + ); +} diff --git a/src/src/EntityFrameworkCore/Properties/AssemblyInfo.cs b/src/src/EntityFrameworkCore/Properties/AssemblyInfo.cs new file mode 100644 index 00000000..053e2ec9 --- /dev/null +++ b/src/src/EntityFrameworkCore/Properties/AssemblyInfo.cs @@ -0,0 +1,8 @@ +using System.Runtime.CompilerServices; + +// This assembly is bundled into each Entity Framework-backed provider package rather than shipped on its +// own, so its types stay internal and are shared with the providers that consume them. +[assembly: InternalsVisibleTo("Purview.EventSourcing.SqlServer")] +[assembly: InternalsVisibleTo("Purview.EventSourcing.Postgres")] +[assembly: InternalsVisibleTo("Purview.EventSourcing.CosmosDb")] +[assembly: InternalsVisibleTo("Purview.EventSourcing.UnitTests")] diff --git a/src/src/EntityFrameworkCore/Query/SnapshotPredicateRewriter.cs b/src/src/EntityFrameworkCore/Query/SnapshotPredicateRewriter.cs new file mode 100644 index 00000000..724b8202 --- /dev/null +++ b/src/src/EntityFrameworkCore/Query/SnapshotPredicateRewriter.cs @@ -0,0 +1,218 @@ +using System.Linq.Expressions; +using System.Reflection; +using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.EntityFrameworkCore.Mapping; +using Purview.ValueObjects.Serialization; + +namespace Purview.EventSourcing.EntityFrameworkCore.Query; + +/// +/// Normalizes a caller-supplied snapshot predicate into a shape Entity Framework can translate: +/// aggregate-type comparisons are folded away, culture-invariant string methods are mapped onto their +/// translatable counterparts, and scalar value-object member access is unwrapped. +/// +static class SnapshotPredicateRewriter +{ + /// + /// Rewrites a predicate for execution against a snapshot store. + /// + /// The aggregate type. + /// The caller-supplied predicate. + /// The aggregate type name the query is already scoped to. + /// The rewritten predicate. + public static Expression> Rewrite(Expression> whereClause, string aggregateType) + where T : class + { + ArgumentNullException.ThrowIfNull(whereClause); + + AggregateTypeExpressionVisitor aggregateTypeVisitor = new(aggregateType); + var rewritten = (Expression>)aggregateTypeVisitor.Visit(whereClause); + InvariantStringMethodNormalizationVisitor invariantCasingVisitor = new(); + rewritten = (Expression>)invariantCasingVisitor.Visit(rewritten); + ScalarValueMemberAccessPredicateVisitor scalarVisitor = new(); + return (Expression>)scalarVisitor.Visit(rewritten); + } + + /// + /// Throws when an ordering clause orders by the inner member of a scalar value object, which the + /// snapshot stores cannot translate. + /// + /// The query expression to inspect. + public static void EnsureSupportedOrderByExpression(Expression queryExpression) => + new UnsupportedScalarValueOrderByDetector().Visit(queryExpression); + + sealed class AggregateTypeExpressionVisitor(string aggregateType) : ExpressionVisitor + { + readonly ConstantExpression _aggregateType = Expression.Constant(aggregateType, typeof(string)); + + protected override Expression VisitMember(MemberExpression node) => + node.Member.Name == nameof(IAggregate.AggregateType) + && node.Expression is not null + && typeof(IAggregate).IsAssignableFrom(node.Expression.Type) + ? _aggregateType + : base.VisitMember(node); + } + + sealed class UnsupportedScalarValueOrderByDetector : ExpressionVisitor + { + protected override Expression VisitMethodCall(MethodCallExpression node) + { + if ( + node.Method.DeclaringType == typeof(Queryable) + && ( + node.Method.Name == nameof(Queryable.OrderBy) + || node.Method.Name == nameof(Queryable.OrderByDescending) + || node.Method.Name == nameof(Queryable.ThenBy) + || node.Method.Name == nameof(Queryable.ThenByDescending) + ) + ) + { + var lambda = (LambdaExpression)StripQuotes(node.Arguments[1]); + new ScalarValueMemberAccessDetector().Visit(lambda.Body); + } + + return base.VisitMethodCall(node); + } + + static Expression StripQuotes(Expression expression) + { + while (expression.NodeType == ExpressionType.Quote) + expression = ((UnaryExpression)expression).Operand; + + return expression; + } + } + + sealed class ScalarValueMemberAccessPredicateVisitor : ExpressionVisitor + { + protected override Expression VisitBinary(BinaryExpression node) + { + var visitedLeft = Visit(node.Left); + var visitedRight = Visit(node.Right); + + return + (node.NodeType == ExpressionType.Equal || node.NodeType == ExpressionType.NotEqual) + && TryRewriteScalarPrimitiveComparison( + visitedLeft, + visitedRight, + out var rewrittenLeft, + out var rewrittenRight + ) + ? Expression.MakeBinary(node.NodeType, rewrittenLeft, rewrittenRight) + : node.Update(visitedLeft, node.Conversion, visitedRight); + } + + protected override Expression VisitMember(MemberExpression node) + { + var visitedExpression = base.VisitMember(node); + if (visitedExpression is not MemberExpression visited || visited.Expression is null) + return visitedExpression; + + var scalarAttribute = visited.Expression.Type.GetCustomAttribute(); + if (scalarAttribute is null || visited.Member.Name != scalarAttribute.PropertyName) + return visited; + + try + { + return Expression.Convert(visited.Expression, visited.Type); + } + catch (InvalidOperationException) + { + return visited; + } + } + + static bool TryRewriteScalarPrimitiveComparison( + Expression left, + Expression right, + out Expression rewrittenLeft, + out Expression rewrittenRight + ) + { + rewrittenLeft = left; + rewrittenRight = right; + + if ( + TryGetScalarPropertyType(left.Type, out var leftScalarType) + && IsSameOrNullable(right.Type, leftScalarType) + ) + { + rewrittenLeft = Expression.Convert(left, right.Type); + return true; + } + + if ( + TryGetScalarPropertyType(right.Type, out var rightScalarType) + && IsSameOrNullable(left.Type, rightScalarType) + ) + { + rewrittenRight = Expression.Convert(right, left.Type); + return true; + } + + return false; + } + + static bool TryGetScalarPropertyType(Type candidateType, out Type scalarPropertyType) + { + scalarPropertyType = null!; + if (!SnapshotTypes.IsScalarValueObjectType(candidateType)) + return false; + + var scalarAttribute = candidateType.GetCustomAttribute()!; + var scalarProperty = candidateType.GetProperty( + scalarAttribute.PropertyName, + BindingFlags.Instance | BindingFlags.Public + ); + if (scalarProperty is null) + return false; + + scalarPropertyType = scalarProperty.PropertyType; + return true; + } + + static bool IsSameOrNullable(Type candidate, Type expected) + { + var underlyingType = Nullable.GetUnderlyingType(candidate); + return candidate == expected || underlyingType == expected; + } + } + + sealed class InvariantStringMethodNormalizationVisitor : ExpressionVisitor + { + protected override Expression VisitMethodCall(MethodCallExpression node) + { + var visitedObject = Visit(node.Object); + var visitedArguments = Visit(node.Arguments); + + if (node.Method.DeclaringType == typeof(string) && node.Arguments.Count == 0 && visitedObject is not null) + { + if (node.Method.Name == nameof(string.ToLowerInvariant)) + return Expression.Call(visitedObject, nameof(string.ToLower), Type.EmptyTypes); + + if (node.Method.Name == nameof(string.ToUpperInvariant)) + return Expression.Call(visitedObject, nameof(string.ToUpper), Type.EmptyTypes); + } + + return node.Update(visitedObject, visitedArguments); + } + } + + sealed class ScalarValueMemberAccessDetector : ExpressionVisitor + { + protected override Expression VisitMember(MemberExpression node) + { + var visited = base.VisitMember(node); + if (node.Expression is null) + return visited; + + var scalarAttribute = node.Expression.Type.GetCustomAttribute(); + return scalarAttribute is not null && node.Member.Name == scalarAttribute.PropertyName + ? throw new InvalidOperationException( + $"Ordering by '{node.Expression.Type.Name}.{node.Member.Name}' is not supported for snapshot JSON queries. " + + "Order by the scalar value object property itself (for example: c => c.Name) instead of its inner scalar member." + ) + : visited; + } + } +} diff --git a/src/src/EventSourcing/AggregateEventHistoryItem.cs b/src/src/EventSourcing/AggregateEventHistoryItem.cs index fa7c8ce9..1c56fc59 100644 --- a/src/src/EventSourcing/AggregateEventHistoryItem.cs +++ b/src/src/EventSourcing/AggregateEventHistoryItem.cs @@ -33,7 +33,7 @@ public sealed class AggregateEventHistoryItem /// /// Gets or sets the aggregate version the event was recorded at. /// - public int AggregateVersion { get; set; } + public long AggregateVersion { get; set; } /// /// Gets or sets the UTC timestamp the event was recorded at. diff --git a/src/src/EventSourcing/AggregateExistence.cs b/src/src/EventSourcing/AggregateExistence.cs new file mode 100644 index 00000000..47d92629 --- /dev/null +++ b/src/src/EventSourcing/AggregateExistence.cs @@ -0,0 +1,39 @@ +namespace Purview.EventSourcing; + +/// +/// Whether an aggregate's stream exists, whether it is deleted, and the version it is at. +/// +/// Whether the aggregate exists, and in what state. +/// The stream version when the aggregate exists, otherwise null. +/// +/// There is deliberately no conversion to : an aggregate that exists in a deleted state is +/// not the same answer as one that exists, and a single boolean cannot say which. +/// +[System.Diagnostics.DebuggerStepThrough] +public readonly record struct AggregateExistence(ExistenceStatus Status, long? Version) +{ + /// + /// Gets a value indicating whether the aggregate exists at all, deleted or not. + /// + public bool DoesExist => Status is ExistenceStatus.Exists or ExistenceStatus.ExistsInDeletedState; + + /// + /// Gets a value indicating whether the aggregate exists and is in a deleted state. + /// + public bool IsDeleted => Status is ExistenceStatus.ExistsInDeletedState; + + /// + /// An aggregate that does not exist. + /// + public static AggregateExistence DoesNotExist => new(ExistenceStatus.DoesNotExist, null); + + /// + /// An aggregate that exists and is not deleted. + /// + public static AggregateExistence Exists => new(ExistenceStatus.Exists, null); + + /// + /// An aggregate that exists in a deleted state. + /// + public static AggregateExistence ExistsInDeletedState => new(ExistenceStatus.ExistsInDeletedState, null); +} diff --git a/src/src/EventSourcing/Aggregates/AggregateBase.cs b/src/src/EventSourcing/Aggregates/AggregateBase.cs index 7310daa8..6777fc4e 100644 --- a/src/src/EventSourcing/Aggregates/AggregateBase.cs +++ b/src/src/EventSourcing/Aggregates/AggregateBase.cs @@ -1,8 +1,8 @@ -using Purview.EventSourcing.Aggregates.Events; -using Purview.EventSourcing.Aggregates.Exceptions; using System.Collections.Concurrent; using System.Reflection; using System.Runtime.CompilerServices; +using Purview.EventSourcing.Aggregates.Events; +using Purview.EventSourcing.Aggregates.Exceptions; namespace Purview.EventSourcing.Aggregates; @@ -178,7 +178,7 @@ public void ForceSave() RecordAndApply(new ForceSaved()); } - internal void RecordSkippedEvent(int aggregateVersion, string? eventTypeName, bool isUnknown) + internal void RecordSkippedEvent(long aggregateVersion, string? eventTypeName, bool isUnknown) { _skippedEvents ??= []; _skippedEvents.Add(new SkippedEventRecord(aggregateVersion, eventTypeName, isUnknown)); diff --git a/src/src/EventSourcing/Aggregates/AggregateDetails.cs b/src/src/EventSourcing/Aggregates/AggregateDetails.cs index 035da898..9c90bcb0 100644 --- a/src/src/EventSourcing/Aggregates/AggregateDetails.cs +++ b/src/src/EventSourcing/Aggregates/AggregateDetails.cs @@ -1,4 +1,4 @@ -using Purview.EventSourcing.Aggregates.Exceptions; +using Purview.EventSourcing.Aggregates.Exceptions; namespace Purview.EventSourcing.Aggregates; @@ -33,7 +33,7 @@ public string Id /// The version of the snapshot that has been saved, if there are any events that are un-saved, or the snapshot doesn't /// contain more recent events then this value may not reflect the latest version of the aggregate. /// - public int SnapshotVersion { get; set; } + public long SnapshotVersion { get; set; } /// /// The version of this instance that has been saved to the . @@ -45,7 +45,7 @@ public string Id /// represents all of the persisted events. /// /// - public int SavedVersion { get; set; } + public long SavedVersion { get; set; } /// /// The current version of this instance of the , @@ -53,7 +53,7 @@ public string Id /// /// While the events maybe unsaved, they are still applied and therefore /// used to update this value. - public int CurrentVersion { get; set; } + public long CurrentVersion { get; set; } /// /// Indicates if the aggregate is in a deleted state. diff --git a/src/src/EventSourcing/Aggregates/Events/EventMetadata.cs b/src/src/EventSourcing/Aggregates/Events/EventMetadata.cs index dbacabb1..0a12e2ec 100644 --- a/src/src/EventSourcing/Aggregates/Events/EventMetadata.cs +++ b/src/src/EventSourcing/Aggregates/Events/EventMetadata.cs @@ -5,7 +5,7 @@ namespace Purview.EventSourcing.Aggregates.Events; /// it. The struct is immutable and allocation-free. /// public readonly record struct EventMetadata( - int AggregateVersion, + long AggregateVersion, DateTimeOffset When, int SchemaVersion, string? IdempotencyId, diff --git a/src/src/EventSourcing/Aggregates/SaveOutcome.cs b/src/src/EventSourcing/Aggregates/SaveOutcome.cs new file mode 100644 index 00000000..25033796 --- /dev/null +++ b/src/src/EventSourcing/Aggregates/SaveOutcome.cs @@ -0,0 +1,37 @@ +namespace Purview.EventSourcing.Aggregates; + +/// +/// Why a save operation did, or did not, write to the stream. +/// +public enum SaveOutcomeKind +{ + /// Events were appended to the stream. + Written = 0, + + /// The aggregate had no unsaved events, so there was nothing to append. + NoChanges = 1, + + /// + /// An idempotency marker matched, so the events had already been appended by an earlier attempt. + /// + AlreadyApplied = 2, +} + +/// +/// The successful result of a save, delete or restore operation. +/// +/// The aggregate type the operation was performed on. +/// The aggregate the operation was performed on. +/// Whether the operation wrote to the stream, and if not, why not. +/// +/// Success that wrote nothing is still success. The failure side of the result carries every reason an +/// operation did not succeed, so no caller has to infer one from a boolean. +/// +public readonly record struct SaveOutcome(TAggregate Aggregate, SaveOutcomeKind Kind) + where TAggregate : IAggregate +{ + /// + /// Indicates whether events were appended to the stream. + /// + public bool Written => Kind == SaveOutcomeKind.Written; +} diff --git a/src/src/EventSourcing/Aggregates/SaveResult.cs b/src/src/EventSourcing/Aggregates/SaveResult.cs deleted file mode 100644 index 29a45e32..00000000 --- a/src/src/EventSourcing/Aggregates/SaveResult.cs +++ /dev/null @@ -1,137 +0,0 @@ -using System.Collections.Immutable; -using System.Diagnostics.CodeAnalysis; -using Purview.EventSourcing.Validation; - -namespace Purview.EventSourcing.Aggregates; - -/// -/// Represents the results of a save operation on a . -/// -/// -/// A save operation could be due to , -/// or -/// the operations. -/// -/// The where a save operations was attempted. -public sealed record class SaveResult - where TAggregate : IAggregate -{ - /// - /// Converts a to a . - /// - /// The save result to convert. - /// - public static implicit operator bool([NotNull] SaveResult aggregateSaveResult) => - aggregateSaveResult.Saved && aggregateSaveResult.IsValid; - - /// - /// Converts a to a . - /// - /// The save result to convert. - /// - public static implicit operator ImmutableArray( - [NotNull] SaveResult aggregateSaveResult - ) => aggregateSaveResult.ValidationResult.Failures; - - /// - /// Converts a to an . - /// - /// The save result to convert. - /// - public static implicit operator TAggregate([NotNull] SaveResult aggregateSaveResult) => - aggregateSaveResult.Aggregate; - - /// - /// Constructs a new based on the saved and validation state - /// from an . - /// - /// The aggregate that was processed. - /// The validation result. - /// Indicates if the operations resulted in a save operation. - /// Indicates if, while the result of maybe true, - /// in-fact the results affected no changes. - public SaveResult(TAggregate aggregate, ValidationResult validationResult, bool saved, bool skipped) - { - Aggregate = aggregate; - ValidationResult = validationResult; - Saved = saved; - Skipped = skipped; - } - - /// - /// The aggregate where a save operation - /// was attempted. - /// - public TAggregate Aggregate { get; } - - /// - /// The result of the validation. - /// - public ValidationResult ValidationResult { get; } - - /// - /// The number of validation failures. - /// - public int FailureCount => ValidationResult.Failures.Length; - - /// - /// Indicates if the - /// denotes failures or success. - /// - public bool IsValid => ValidationResult.IsValid; - - /// - /// Indicates if the save operation was successful. - /// - /// A value of false does not always mean failure, it may mean - /// there was no events to save, or the events were already saved - in the case - /// where idempotency markers are recorded and validated. - public bool Saved { get; } - - /// - /// Indicates the result from a - /// operation was skipped. - /// - /// - /// This maybe true when checking idempotency markers, or having not events to save. - /// - /// Note: This result is not featured in the ability to convert to - /// a via or the implicit case. - /// - /// - public bool Skipped { get; } - - /// - /// Converts this to a - /// to quickly indicate success or failure of the save operation. - /// - /// Returns true if and is true, - /// otherwise, returns false. - public bool ToBoolean() => this; - - /// - /// Converts this to an . - /// - /// Returns the instance. - public TAggregate ToAggregate() - { - EnsureValid(); - - return this; - } - - /// - /// Converts this to a . - /// - /// Returns the instance. - public ImmutableArray ToValidationFailures() => this; - - /// - /// If is false, a is thrown. - /// - public void EnsureValid() - { - if (!IsValid) - throw new ValidationException(ValidationResult.Failures); - } -} diff --git a/src/src/EventSourcing/Aggregates/SkippedEventRecord.cs b/src/src/EventSourcing/Aggregates/SkippedEventRecord.cs index 9a0b8af4..fe7e21c6 100644 --- a/src/src/EventSourcing/Aggregates/SkippedEventRecord.cs +++ b/src/src/EventSourcing/Aggregates/SkippedEventRecord.cs @@ -7,4 +7,4 @@ namespace Purview.EventSourcing.Aggregates; /// The aggregate version the skipped event was recorded at. /// The persisted event type name, when known. /// True when the event type could not be resolved to a CLR type. -public sealed record SkippedEventRecord(int AggregateVersion, string? EventTypeName, bool IsUnknown); +public sealed record SkippedEventRecord(long AggregateVersion, string? EventTypeName, bool IsUnknown); diff --git a/src/src/EventSourcing/AmbientEventStorePrincipalAccessor.cs b/src/src/EventSourcing/AmbientEventStorePrincipalAccessor.cs new file mode 100644 index 00000000..a47b6710 --- /dev/null +++ b/src/src/EventSourcing/AmbientEventStorePrincipalAccessor.cs @@ -0,0 +1,18 @@ +using System.Security.Claims; + +namespace Purview.EventSourcing; + +/// +/// The default , reading . +/// +/// +/// Only useful where the application populates the ambient principal - by setting +/// , or on a host that flows +/// . ASP.NET Core does neither, so a web application should register +/// its own accessor; see . +/// +public sealed class AmbientEventStorePrincipalAccessor : IEventStorePrincipalAccessor +{ + /// + public ClaimsPrincipal? GetPrincipal() => ClaimsPrincipal.Current; +} diff --git a/src/src/EventSourcing/ChangeFeed/AggregateChangeFeedNotifier.cs b/src/src/EventSourcing/ChangeFeed/AggregateChangeFeedNotifier.cs index 0b3f0126..4f19b6fd 100644 --- a/src/src/EventSourcing/ChangeFeed/AggregateChangeFeedNotifier.cs +++ b/src/src/EventSourcing/ChangeFeed/AggregateChangeFeedNotifier.cs @@ -79,7 +79,7 @@ await ProcessTimedNotifyAsync( public async Task AfterSaveAsync( T aggregate, - int previousSavedVersion, + long previousSavedVersion, bool isNew, EventRecord[] events, CancellationToken cancellationToken = default diff --git a/src/src/EventSourcing/ChangeFeed/IAggregateChangeFeedNotifier.cs b/src/src/EventSourcing/ChangeFeed/IAggregateChangeFeedNotifier.cs index 6ef00044..d656e15b 100644 --- a/src/src/EventSourcing/ChangeFeed/IAggregateChangeFeedNotifier.cs +++ b/src/src/EventSourcing/ChangeFeed/IAggregateChangeFeedNotifier.cs @@ -46,7 +46,7 @@ public interface IAggregateChangeFeedNotifier /// An awaitable task. Task AfterSaveAsync( T aggregate, - int previousSavedVersion, + long previousSavedVersion, bool isNew, EventRecord[] events, CancellationToken cancellationToken = default diff --git a/src/src/EventSourcing/ChangeFeed/IAggregateChangeFeedProcessor.cs b/src/src/EventSourcing/ChangeFeed/IAggregateChangeFeedProcessor.cs index 301f29b9..133e54e1 100644 --- a/src/src/EventSourcing/ChangeFeed/IAggregateChangeFeedProcessor.cs +++ b/src/src/EventSourcing/ChangeFeed/IAggregateChangeFeedProcessor.cs @@ -43,7 +43,7 @@ Task BeforeSaveAsync(IAggregate aggregate, bool isNew, CancellationToken cancell /// Returns a . Task AfterSaveAsync( IAggregate aggregate, - int previousSavedVersion, + long previousSavedVersion, bool isNew, EventRecord[] events, CancellationToken cancellationToken = default @@ -114,7 +114,7 @@ public interface IAggregateChangeFeedProcessor /// Returns a . Task AfterSaveAsync( T aggregate, - int previousSavedVersion, + long previousSavedVersion, bool isNew, EventRecord[] events, CancellationToken cancellationToken = default diff --git a/src/src/EventSourcing/ConcurrencyRetry.cs b/src/src/EventSourcing/ConcurrencyRetry.cs index b2db6f23..174fbbb3 100644 --- a/src/src/EventSourcing/ConcurrencyRetry.cs +++ b/src/src/EventSourcing/ConcurrencyRetry.cs @@ -1,3 +1,6 @@ +using Purview.EventSourcing.Failures; +using Purview.Results; + namespace Purview.EventSourcing; /// @@ -5,19 +8,68 @@ namespace Purview.EventSourcing; /// /// /// -/// The framework itself does not retry failed writes; a ConcurrencyException is surfaced -/// to the caller. Callers that need a read-modify-write loop (load an aggregate, apply domain -/// changes, save, and re-read + re-apply on a conflict) should wrap their operation with -/// . +/// The framework itself does not retry failed writes; a conflict is surfaced to the caller. Callers +/// that need a read-modify-write loop (load an aggregate, apply domain changes, save, and re-read + +/// re-apply on a conflict) should wrap their operation with one of the ExecuteAsync overloads. /// /// -/// By default the policy only retries exceptions that implement , -/// which all provider ConcurrencyException types implement. Provide a custom predicate to -/// widen or narrow the set of retryable failures. +/// Save operations report a conflict as a case, so use +/// +/// for those. The exception-based overload remains for operations that still throw, and by default +/// retries exceptions implementing . /// /// public static class ConcurrencyRetry { + /// + /// Executes retrying it with exponential backoff while it returns a + /// . After attempts the last + /// result is returned as-is. + /// + /// The result's value type. + /// The result's error union. + /// The operation to execute, typically a load → modify → save loop. + /// The maximum number of attempts (inclusive), at least 1. + /// The base delay before the first retry; doubles each attempt. + /// The stopping token, also cancels the backoff delay. + /// The first non-conflicting result, or the last conflicting one once the attempts run out. + /// is null. + /// is less than 1. + public static async Task> ExecuteAsync( + Func>> operation, + int maxAttempts = 3, + TimeSpan? initialBackoff = null, + CancellationToken cancellationToken = default + ) + { + ArgumentNullException.ThrowIfNull(operation); + if (maxAttempts < 1) + throw new ArgumentOutOfRangeException(nameof(maxAttempts), maxAttempts, "Must be at least 1."); + + var backoff = initialBackoff ?? TimeSpan.FromMilliseconds(50); + + for (var attempt = 1; ; attempt++) + { + var result = await operation().ConfigureAwait(false); + if (result.IsSuccess || attempt >= maxAttempts || !IsConcurrencyConflict(result.Error)) + return result; + + await Task.Delay(backoff * Math.Pow(2, attempt - 1), cancellationToken).ConfigureAwait(false); + } + } + + // The error may be the case itself, or a union wrapping it, so the union's own members are checked + // rather than assuming a particular union shape. + static bool IsConcurrencyConflict(TError error) => + error switch + { + ConcurrencyConflict => true, + AggregateSaveFailure save => save is ConcurrencyConflict, + AggregateDeleteFailure delete => delete is ConcurrencyConflict, + AggregateRestoreFailure restore => restore is ConcurrencyConflict, + _ => false, + }; + /// /// Executes retrying it with exponential backoff when it throws a /// concurrency-conflict exception. After attempts the last diff --git a/src/src/EventSourcing/Cryptography/AesGcmEventPayloadProtector.cs b/src/src/EventSourcing/Cryptography/AesGcmEventPayloadProtector.cs new file mode 100644 index 00000000..5eae831f --- /dev/null +++ b/src/src/EventSourcing/Cryptography/AesGcmEventPayloadProtector.cs @@ -0,0 +1,99 @@ +using System.Security.Cryptography; +using System.Text; +using Purview.EventSourcing.Serialization; + +namespace Purview.EventSourcing.Cryptography; + +/// +/// Encrypts event payloads with AES-GCM under a per-subject key. +/// +/// +/// AES-GCM is authenticated, so a payload that has been altered fails to decrypt rather than yielding +/// plausible rubbish. The subject identifier is bound into the encryption as associated data, so moving +/// ciphertext from one subject's event to another's is detected rather than silently decrypting. +/// +/// Supplies and erases the per-subject keys. +public sealed class AesGcmEventPayloadProtector(IEventCryptoKeyStore keyStore) : IEventPayloadProtector +{ + /// + /// The algorithm identifier written into . + /// + public const string AlgorithmName = "AES-GCM-256"; + + /// + /// The key length in bytes. + /// + public const int KeySizeInBytes = 32; + + /// + public async Task ProtectAsync( + string payload, + string dataSubjectId, + CancellationToken cancellationToken = default + ) + { + ArgumentNullException.ThrowIfNull(payload); + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + var key = await keyStore.GetOrCreateAsync(dataSubjectId, cancellationToken); + var plaintext = Encoding.UTF8.GetBytes(payload); + + var nonce = new byte[AesGcm.NonceByteSizes.MaxSize]; + RandomNumberGenerator.Fill(nonce); + + var cipherText = new byte[plaintext.Length]; + var tag = new byte[AesGcm.TagByteSizes.MaxSize]; + + using AesGcm aes = new(key, tag.Length); + aes.Encrypt(nonce, plaintext, cipherText, tag, Encoding.UTF8.GetBytes(dataSubjectId)); + + return EventStoreSerializationHelpers.Serialize( + new ProtectedPayload + { + DataSubjectId = dataSubjectId, + Nonce = Convert.ToBase64String(nonce), + Tag = Convert.ToBase64String(tag), + CipherText = Convert.ToBase64String(cipherText), + } + ); + } + + /// + public async Task UnprotectAsync(string payload, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(payload); + + if (!IsProtected(payload)) + return payload; + + var envelope = + EventStoreSerializationHelpers.Deserialize(payload) + ?? throw new InvalidOperationException("The payload is marked as protected but could not be read."); + + var key = await keyStore.TryGetAsync(envelope.DataSubjectId, cancellationToken); + if (key is null) + // The subject has been erased. Expected, not exceptional: the caller turns this into a + // skipped event so replay continues and the gap stays visible. + return null; + + var nonce = Convert.FromBase64String(envelope.Nonce); + var tag = Convert.FromBase64String(envelope.Tag); + var cipherText = Convert.FromBase64String(envelope.CipherText); + var plaintext = new byte[cipherText.Length]; + + using AesGcm aes = new(key, tag.Length); + aes.Decrypt(nonce, cipherText, tag, plaintext, Encoding.UTF8.GetBytes(envelope.DataSubjectId)); + + return Encoding.UTF8.GetString(plaintext); + } + + /// + public bool IsProtected(string payload) => + payload is not null && payload.Contains(ProtectedPayload.MarkerPropertyName, StringComparison.Ordinal); + + /// + /// Creates a new random key. + /// + /// A key of bytes. + public static byte[] CreateKey() => RandomNumberGenerator.GetBytes(KeySizeInBytes); +} diff --git a/src/src/EventSourcing/Cryptography/IEventCryptoKeyStore.cs b/src/src/EventSourcing/Cryptography/IEventCryptoKeyStore.cs new file mode 100644 index 00000000..24d5e78f --- /dev/null +++ b/src/src/EventSourcing/Cryptography/IEventCryptoKeyStore.cs @@ -0,0 +1,40 @@ +namespace Purview.EventSourcing.Cryptography; + +/// +/// Stores the per-subject keys used to encrypt event payloads. +/// +/// +/// The store is the erasure mechanism: deleting a key is the irreversible act, so a production +/// implementation should be backed by a key vault with its own access control and audit trail, and must +/// not be backed by anything that silently restores deleted entries from a backup. +/// +public interface IEventCryptoKeyStore +{ + /// + /// Gets the key for a subject, creating one if none exists. + /// + /// The subject the key belongs to. + /// The token to monitor for cancellation requests. + /// The subject's key. + Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken); + + /// + /// Gets the key for a subject, or when it has been erased or never existed. + /// + /// The subject the key belongs to. + /// The token to monitor for cancellation requests. + /// The subject's key, or . + /// + /// A missing key is an expected outcome during replay - it is what erasure looks like - so this + /// returns null rather than throwing. + /// + Task TryGetAsync(string dataSubjectId, CancellationToken cancellationToken); + + /// + /// Erases a subject's key, rendering every payload encrypted with it permanently unreadable. + /// + /// The subject to erase. + /// The token to monitor for cancellation requests. + /// when a key was erased; when none existed. + Task ShredAsync(string dataSubjectId, CancellationToken cancellationToken); +} diff --git a/src/src/EventSourcing/Cryptography/IEventDataSubject.cs b/src/src/EventSourcing/Cryptography/IEventDataSubject.cs new file mode 100644 index 00000000..fd262d9e --- /dev/null +++ b/src/src/EventSourcing/Cryptography/IEventDataSubject.cs @@ -0,0 +1,23 @@ +namespace Purview.EventSourcing.Cryptography; + +/// +/// Marks an event as carrying personal data belonging to a single data subject. +/// +/// +/// The payload of an event implementing this is encrypted with a key belonging to +/// . Erasing that subject deletes the key, which renders their payloads +/// unreadable everywhere they appear without rewriting or deleting any event - the stream stays +/// append-only and every other subject's data is untouched. +/// +public interface IEventDataSubject +{ + /// + /// Identifies the person the event's personal data belongs to. + /// + /// + /// Must be stable for the lifetime of the subject: it is the key identifier, so a value that changes + /// orphans the earlier events. It is recorded in clear alongside the ciphertext, so it must not + /// itself be personal data - use a surrogate identifier, not an email address. + /// + string DataSubjectId { get; } +} diff --git a/src/src/EventSourcing/Cryptography/IEventPayloadProtector.cs b/src/src/EventSourcing/Cryptography/IEventPayloadProtector.cs new file mode 100644 index 00000000..a62a69b3 --- /dev/null +++ b/src/src/EventSourcing/Cryptography/IEventPayloadProtector.cs @@ -0,0 +1,34 @@ +namespace Purview.EventSourcing.Cryptography; + +/// +/// Encrypts and decrypts event payloads for crypto-shredding. +/// +public interface IEventPayloadProtector +{ + /// + /// Encrypts a payload under the subject's key. + /// + /// The serialized event payload. + /// The subject whose key to use. + /// The token to monitor for cancellation requests. + /// The protected payload, to be stored in place of the plaintext. + Task ProtectAsync(string payload, string dataSubjectId, CancellationToken cancellationToken = default); + + /// + /// Decrypts a payload, or reports that its key has been erased. + /// + /// The stored payload, protected or not. + /// The token to monitor for cancellation requests. + /// + /// The plaintext payload; the payload unchanged when it was never protected; or + /// when the subject's key has been erased. + /// + Task UnprotectAsync(string payload, CancellationToken cancellationToken = default); + + /// + /// Reports whether a stored payload is protected. + /// + /// The stored payload. + /// when the payload is encrypted. + bool IsProtected(string payload); +} diff --git a/src/src/EventSourcing/Cryptography/InMemoryEventCryptoKeyStore.cs b/src/src/EventSourcing/Cryptography/InMemoryEventCryptoKeyStore.cs new file mode 100644 index 00000000..8860e643 --- /dev/null +++ b/src/src/EventSourcing/Cryptography/InMemoryEventCryptoKeyStore.cs @@ -0,0 +1,40 @@ +using System.Collections.Concurrent; + +namespace Purview.EventSourcing.Cryptography; + +/// +/// An in-memory for local development and tests. +/// +/// +/// Keys live only for the lifetime of the process, so every payload becomes unreadable on restart. +/// That makes it unusable in production by construction, which is the intent: a key store is the one +/// component where a convenient default would be actively harmful. +/// +public sealed class InMemoryEventCryptoKeyStore : IEventCryptoKeyStore +{ + readonly ConcurrentDictionary _keys = new(StringComparer.Ordinal); + + /// + public Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + return Task.FromResult(_keys.GetOrAdd(dataSubjectId, _ => AesGcmEventPayloadProtector.CreateKey())); + } + + /// + public Task TryGetAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + return Task.FromResult(_keys.TryGetValue(dataSubjectId, out var key) ? key : null); + } + + /// + public Task ShredAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + return Task.FromResult(_keys.TryRemove(dataSubjectId, out _)); + } +} diff --git a/src/src/EventSourcing/Cryptography/ProtectedPayload.cs b/src/src/EventSourcing/Cryptography/ProtectedPayload.cs new file mode 100644 index 00000000..1907710b --- /dev/null +++ b/src/src/EventSourcing/Cryptography/ProtectedPayload.cs @@ -0,0 +1,47 @@ +using System.Text.Json.Serialization; + +namespace Purview.EventSourcing.Cryptography; + +/// +/// The stored form of an encrypted event payload. +/// +/// +/// Written in place of the plaintext payload, so no provider needs a new column: every store already +/// persists the payload as text. The subject identifier travels with the ciphertext because replay has +/// to know which key to ask for before it can read anything. +/// +public sealed record ProtectedPayload +{ + /// + /// Discriminates an encrypted payload from a plaintext one. + /// + /// + /// Deliberately unlikely to collide with a real event property, so an unprotected payload is never + /// mistaken for a protected one. + /// + public const string MarkerPropertyName = "__protected"; + + /// Always ; present so the payload can be recognised before parsing. + [JsonPropertyName(MarkerPropertyName)] + public bool Protected { get; init; } = true; + + /// The algorithm the payload was encrypted with. + [JsonPropertyName("alg")] + public string Algorithm { get; init; } = AesGcmEventPayloadProtector.AlgorithmName; + + /// The subject whose key the payload was encrypted with. + [JsonPropertyName("sub")] + public string DataSubjectId { get; init; } = default!; + + /// The base64 nonce. + [JsonPropertyName("n")] + public string Nonce { get; init; } = default!; + + /// The base64 authentication tag. + [JsonPropertyName("t")] + public string Tag { get; init; } = default!; + + /// The base64 ciphertext. + [JsonPropertyName("c")] + public string CipherText { get; init; } = default!; +} diff --git a/src/src/EventSourcing/DeleteHandlingMode.cs b/src/src/EventSourcing/DeleteHandlingMode.cs index 78fbfc5f..7b020925 100644 --- a/src/src/EventSourcing/DeleteHandlingMode.cs +++ b/src/src/EventSourcing/DeleteHandlingMode.cs @@ -1,22 +1,22 @@ namespace Purview.EventSourcing; /// -/// Controls how to handle aggregates in a deleted state during get and save/ restore operations. +/// Controls how a soft-deleted aggregate is reported by get operations. /// +/// +/// The mode no longer decides whether an exception is thrown: a deleted aggregate is an expected +/// outcome, reported as . It decides only whether the caller +/// wants that state back instead. +/// public enum DeleteHandlingMode { /// - /// If the aggregate is marked as deleted, returns null. This is the default. + /// A deleted aggregate is reported as . This is the default. /// - ReturnsNull = 0, + ReturnsFailure = 0, /// - /// Should throw an exception. - /// - ThrowsException, - - /// - /// Returns the aggregate in it's deleted state. + /// A deleted aggregate is returned in its deleted state. /// ReturnsAggregate, } diff --git a/src/src/EventSourcing/EventSourcing.csproj b/src/src/EventSourcing/EventSourcing.csproj index 9af1552f..9746c5e9 100644 --- a/src/src/EventSourcing/EventSourcing.csproj +++ b/src/src/EventSourcing/EventSourcing.csproj @@ -1,4 +1,4 @@ - + true Purview Event Sourcing @@ -7,6 +7,13 @@ + + + + $(NoWarn);RSG1006 + + - - - - - + diff --git a/src/src/EventSourcing/EventStoreFacade.cs b/src/src/EventSourcing/EventStoreFacade.cs index 996e571a..4d3229b2 100644 --- a/src/src/EventSourcing/EventStoreFacade.cs +++ b/src/src/EventSourcing/EventStoreFacade.cs @@ -2,7 +2,9 @@ using System.ComponentModel; using Microsoft.Extensions.DependencyInjection; using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.Internal; +using Purview.Results; namespace Purview.EventSourcing; @@ -31,7 +33,7 @@ public Task CreateAsync(string? aggregateId = null, CancellationToken canc where T : class, IAggregate, new() => GetEventStore().CreateAsync(aggregateId, cancellationToken); /// - public Task GetOrCreateAsync( + public Task> GetOrCreateAsync( string? aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -40,7 +42,7 @@ public Task CreateAsync(string? aggregateId = null, CancellationToken canc GetEventStore().GetOrCreateAsync(aggregateId, operationContext, cancellationToken); /// - public Task GetAsync( + public Task> GetAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -49,9 +51,9 @@ public Task CreateAsync(string? aggregateId = null, CancellationToken canc GetEventStore().GetAsync(aggregateId, operationContext, cancellationToken); /// - public Task GetAtAsync( + public Task> GetAtAsync( string aggregateId, - int version, + long version, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) @@ -59,7 +61,7 @@ public Task CreateAsync(string? aggregateId = null, CancellationToken canc GetEventStore().GetAtAsync(aggregateId, version, operationContext, cancellationToken); /// - public Task> SaveAsync( + public Task, AggregateSaveFailure>> SaveAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -68,15 +70,14 @@ public Task> SaveAsync( GetEventStore().SaveAsync(aggregate, operationContext, cancellationToken); /// - public Task IsDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) - where T : class, IAggregate, new() => GetEventStore().IsDeletedAsync(aggregateId, cancellationToken); - - /// - public Task GetDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) + public Task> GetDeletedAsync( + string aggregateId, + CancellationToken cancellationToken = default + ) where T : class, IAggregate, new() => GetEventStore().GetDeletedAsync(aggregateId, cancellationToken); /// - public Task DeleteAsync( + public Task, AggregateDeleteFailure>> DeleteAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -85,7 +86,7 @@ public Task DeleteAsync( GetEventStore().DeleteAsync(aggregate, operationContext, cancellationToken); /// - public Task RestoreAsync( + public Task, AggregateRestoreFailure>> RestoreAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -102,7 +103,7 @@ public IAsyncEnumerable GetAggregateIdsAsync( GetEventStore().GetAggregateIdsAsync(includeDeleted, cancellationToken); /// - public Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) + public Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) where T : class, IAggregate, new() => GetEventStore().ExistsAsync(aggregateId, cancellationToken); /// @@ -112,8 +113,8 @@ public T FulfilRequirements(T aggregate) /// public IAsyncEnumerable<(EventRecord EventRecord, string EventType)> GetEventRangeAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, CancellationToken cancellationToken ) where T : class, IAggregate, new() => diff --git a/src/src/EventSourcing/EventStoreMetricsExtensions.cs b/src/src/EventSourcing/EventStoreMetricsExtensions.cs new file mode 100644 index 00000000..1dcb83bb --- /dev/null +++ b/src/src/EventSourcing/EventStoreMetricsExtensions.cs @@ -0,0 +1,60 @@ +using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Failures; +using Purview.Results; + +namespace Purview.EventSourcing; + +/// +/// Helpers that keep the metric tags identical across storage providers. +/// +public static class EventStoreMetricsExtensions +{ + /// + /// Records the duration and outcome of a save. + /// + /// The aggregate type. + /// The metrics recorder. + /// The elapsed time, in milliseconds. + /// The aggregate type name. + /// The save result. + /// + /// Only a returned result is recorded. An exception escaping a save is an infrastructure fault + /// rather than an outcome, and is already reported through logging and the activity. + /// + public static void RecordSave( + this IEventStoreMetrics metrics, + double milliseconds, + string aggregateType, + Result, AggregateSaveFailure> result + ) + where T : class, IAggregate, new() + { + ArgumentNullException.ThrowIfNull(metrics); + + metrics.SaveDuration(milliseconds, aggregateType, OutcomeTag(result)); + } + + static string OutcomeTag(Result, AggregateSaveFailure> result) + where T : class, IAggregate, new() + { + if (result.IsFailure) + { + return result.Error switch + { + ConcurrencyConflict => "concurrency-conflict", + AggregateLocked => "locked", + AggregateDeleted => "deleted", + AggregateInvalid => "invalid", + _ => "failed", + }; + } + + return result.Value.Kind switch + { + SaveOutcomeKind.Written => "written", + SaveOutcomeKind.NoChanges => "no-changes", + SaveOutcomeKind.AlreadyApplied => "already-applied", + _ => "unknown", + }; + } +} diff --git a/src/src/EventSourcing/EventStoreOperationContext.cs b/src/src/EventSourcing/EventStoreOperationContext.cs index 72322891..97b52dfe 100644 --- a/src/src/EventSourcing/EventStoreOperationContext.cs +++ b/src/src/EventSourcing/EventStoreOperationContext.cs @@ -62,12 +62,7 @@ public string CorrelationId /// /// Controls how to handle aggregates marked as deleted during get and save/ restore operations. /// - public DeleteHandlingMode DeleteMode { get; set; } = DeleteHandlingMode.ReturnsNull; - - /// - /// Controls how to handle aggregates marked as locked. - /// - public LockHandlingMode LockMode { get; set; } = LockHandlingMode.ThrowsException; + public DeleteHandlingMode DeleteMode { get; set; } = DeleteHandlingMode.ReturnsFailure; /// /// Gets/ sets a value indicating how the diff --git a/src/src/EventSourcing/EventStoreTransaction.cs b/src/src/EventSourcing/EventStoreTransaction.cs index 4be6cef6..5ed8bef8 100644 --- a/src/src/EventSourcing/EventStoreTransaction.cs +++ b/src/src/EventSourcing/EventStoreTransaction.cs @@ -1,6 +1,7 @@ using System.Data.Common; using System.Diagnostics; using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.Internal; namespace Purview.EventSourcing; @@ -155,9 +156,15 @@ async Task CommitSequentiallyAsync(CancellationToken cancella { try { - var (saved, skipped) = await enlisted.SaveAsync(CorrelationId, cancellationToken); + var (saved, skipped, failure) = await enlisted.SaveAsync(CorrelationId, cancellationToken); results.Add( - new TransactionAggregateResult(enlisted.Aggregate, saved: saved, skipped: skipped, error: null) + new TransactionAggregateResult( + enlisted.Aggregate, + saved: saved, + skipped: skipped, + error: null, + failure: failure + ) ); // Stop processing remaining aggregates on first failure. @@ -247,7 +254,8 @@ async Task CommitWithNativeTransactionAsync(CancellationToken operation.Aggregate, operation.Saved, operation.Skipped, - postCommitError + postCommitError, + operation.Failure ) ); } @@ -281,7 +289,8 @@ failure is null operation.Aggregate, saved: false, skipped: !isFailedOperation && !wasRolledBack && operation.Skipped, - error: isFailedOperation || operation.Skipped ? null : rollbackError + error: isFailedOperation || operation.Skipped ? null : rollbackError, + failure: operation.Failure ) ); } @@ -315,7 +324,10 @@ internal interface IEnlistedAggregate string? TransactionBoundaryKey { get; } - Task<(bool saved, bool skipped)> SaveAsync(string correlationId, CancellationToken cancellationToken); + Task<(bool saved, bool skipped, AggregateSaveFailure? failure)> SaveAsync( + string correlationId, + CancellationToken cancellationToken + ); DbConnection CreateTransactionConnection(); @@ -337,6 +349,8 @@ internal interface IProcessedSaveOperation bool Skipped { get; } + AggregateSaveFailure? Failure { get; } + Task AfterCommitAsync(CancellationToken cancellationToken); Task AfterRollbackAsync(CancellationToken cancellationToken); @@ -387,7 +401,7 @@ bool useIdempotencyMarker public string? TransactionBoundaryKey => _transactionalEventStore?.TransactionBoundaryKey; - public async Task<(bool saved, bool skipped)> SaveAsync( + public async Task<(bool saved, bool skipped, AggregateSaveFailure? failure)> SaveAsync( string correlationId, CancellationToken cancellationToken ) @@ -402,7 +416,14 @@ CancellationToken cancellationToken var result = _eventStoreImpl is not null ? await _eventStoreImpl.SaveAsync(_aggregate, context, cancellationToken) : await _eventStore!.SaveAsync(_aggregate, context, cancellationToken); - return (result.Saved, result.Skipped); + + return result.IsSuccess + ? ( + result.Value.Kind is not SaveOutcomeKind.NoChanges, + result.Value.Kind is not SaveOutcomeKind.Written, + null + ) + : (false, false, result.Error); } public DbConnection CreateTransactionConnection() => @@ -456,9 +477,11 @@ sealed class ProcessedSaveOperation(T aggregate, TransactionalSaveOperation aggregate; - public bool Saved => operation.Result.Saved; + public bool Saved => operation.Saved; + + public bool Skipped => operation.Skipped; - public bool Skipped => operation.Result.Skipped; + public AggregateSaveFailure? Failure => operation.Result.IsFailure ? operation.Result.Error : null; public Task AfterCommitAsync(CancellationToken cancellationToken) => operation.AfterCommitAsync(cancellationToken); diff --git a/src/src/EventSourcing/EventStores/NullQueryable/NullQueryableEventStore.cs b/src/src/EventSourcing/EventStores/NullQueryable/NullQueryableEventStore.cs index 45f8a55b..5f5cf1df 100644 --- a/src/src/EventSourcing/EventStores/NullQueryable/NullQueryableEventStore.cs +++ b/src/src/EventSourcing/EventStores/NullQueryable/NullQueryableEventStore.cs @@ -1,7 +1,9 @@ using System.Linq.Expressions; using System.Runtime.CompilerServices; using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.Internal; +using Purview.Results; namespace Purview.EventSourcing.EventStores.NullQueryable; @@ -14,21 +16,21 @@ sealed class NullQueryableEventStore(INonQueryableEventStore eventStore) : public IAsyncEnumerable<(EventRecord EventRecord, string EventType)> GetEventRangeAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, CancellationToken cancellationToken ) => _eventStore.GetEventRangeAsync(aggregateId, versionFrom, versionTo, cancellationToken); public Task CreateAsync(string? id = null, CancellationToken cancellationToken = default) => _eventStore.CreateAsync(id, cancellationToken); - public Task DeleteAsync( + public Task, AggregateDeleteFailure>> DeleteAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => _eventStore.DeleteAsync(aggregate, operationContext, cancellationToken); - public Task ExistsAsync(string id, CancellationToken cancellationToken = default) => + public Task ExistsAsync(string id, CancellationToken cancellationToken = default) => _eventStore.ExistsAsync(id, cancellationToken); public IAsyncEnumerable GetAggregateIdsAsync( @@ -36,31 +38,30 @@ public IAsyncEnumerable GetAggregateIdsAsync( CancellationToken cancellationToken = default ) => _eventStore.GetAggregateIdsAsync(includeDeleted, cancellationToken); - public Task GetAsync( + public Task> GetAsync( string id, EventStoreOperationContext? context, CancellationToken cancellationToken = default ) => _eventStore.GetAsync(id, context, cancellationToken); - public Task GetAtAsync( + public Task> GetAtAsync( string id, - int version, + long version, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => _eventStore.GetAtAsync(id, version, operationContext, cancellationToken); - public Task GetDeletedAsync(string id, CancellationToken cancellationToken = default) => - _eventStore.GetDeletedAsync(id, cancellationToken); + public Task> GetDeletedAsync( + string id, + CancellationToken cancellationToken = default + ) => _eventStore.GetDeletedAsync(id, cancellationToken); - public Task GetOrCreateAsync( + public Task> GetOrCreateAsync( string? id, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => _eventStore.GetOrCreateAsync(id, operationContext, cancellationToken); - public Task IsDeletedAsync(string id, CancellationToken cancellationToken = default) => - _eventStore.IsDeletedAsync(id, cancellationToken); - public Task> QueryAsync( Expression> whereClause, Func, IQueryable>? orderByClause, @@ -74,13 +75,13 @@ public Task> ListAsync( CancellationToken cancellationToken = default ) => Task.FromResult(new ContinuationResponse() { Results = [], RequestedCount = request.MaxRecords }); - public Task RestoreAsync( + public Task, AggregateRestoreFailure>> RestoreAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => _eventStore.RestoreAsync(aggregate, operationContext, cancellationToken); - public Task> SaveAsync( + public Task, AggregateSaveFailure>> SaveAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default diff --git a/src/src/EventSourcing/Exceptions/CommitException.cs b/src/src/EventSourcing/Exceptions/CommitException.cs new file mode 100644 index 00000000..dd44197a --- /dev/null +++ b/src/src/EventSourcing/Exceptions/CommitException.cs @@ -0,0 +1,99 @@ +namespace Purview.EventSourcing.Exceptions; + +/// +/// Thrown when events could not be committed for a reason other than optimistic concurrency. +/// +/// +/// One type for every provider. Providers that surface a transport status - Azure Table Storage, for +/// example - supply it through and ; the rest attach the +/// underlying failure as the inner exception. +/// +#pragma warning disable CA1032 // Implement standard exception constructors +public class CommitException : Exception +#pragma warning restore CA1032 // Implement standard exception constructors +{ + /// + /// Creates a commit failure that wraps the underlying storage exception. + /// + /// The id of the aggregate. + /// The idempotency id associated with the commit. + /// The aggregate version that was attempted. + /// The aggregate version present in the store. + /// The underlying storage failure. + public CommitException( + string aggregateId, + string idempotencyId, + long versionAttempted, + long version, + Exception? innerException = null + ) + : base( + $"Failed to commit events.\n\tAggregateId: {aggregateId}\n\tIdempotencyId: {idempotencyId}\n\tVersionAttempted: {versionAttempted}\n\tVersionPresent: {version}", + innerException + ) + { + AggregateId = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); + IdempotencyId = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); + VersionAttempted = versionAttempted; + Version = version; + } + + /// + /// Creates a commit failure that carries the transport status returned by the storage operation. + /// + /// The status code returned by the storage operation. + /// The id of the aggregate. + /// The idempotency id associated with the commit. + /// The aggregate version that was attempted. + /// The aggregate version present in the store. + /// The status message returned by the storage operation. + public CommitException( + int errorCode, + string aggregateId, + string idempotencyId, + long versionAttempted, + long version, + string statusMessage + ) + : base( + $"Failed to commit events.\n\tErrorCode: {errorCode} - {statusMessage}\n\tAggregateId: {aggregateId}\n\tIdempotencyId: {idempotencyId}\n\tVersionAttempted: {versionAttempted}\n\tVersionPresent: {version}" + ) + { + AggregateId = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); + IdempotencyId = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); + VersionAttempted = versionAttempted; + Version = version; + ErrorCode = errorCode; + StatusMessage = statusMessage; + } + + /// + /// Gets the id of the aggregate. + /// + public string AggregateId { get; } + + /// + /// Gets the idempotency id associated with the commit. + /// + public string IdempotencyId { get; } + + /// + /// Gets the aggregate version that was attempted. + /// + public long VersionAttempted { get; } + + /// + /// Gets the aggregate version present in the store. + /// + public long Version { get; } + + /// + /// Gets the status code returned by the storage operation, when the provider surfaces one. + /// + public int? ErrorCode { get; } + + /// + /// Gets the status message returned by the storage operation, when the provider surfaces one. + /// + public string? StatusMessage { get; } +} diff --git a/src/src/SqlServer/Events/Exceptions/ConcurrencyException.cs b/src/src/EventSourcing/Exceptions/ConcurrencyException.cs similarity index 77% rename from src/src/SqlServer/Events/Exceptions/ConcurrencyException.cs rename to src/src/EventSourcing/Exceptions/ConcurrencyException.cs index a545c13e..6fe80af8 100644 --- a/src/src/SqlServer/Events/Exceptions/ConcurrencyException.cs +++ b/src/src/EventSourcing/Exceptions/ConcurrencyException.cs @@ -1,4 +1,4 @@ -namespace Purview.EventSourcing.SqlServer.Events.Exceptions; +namespace Purview.EventSourcing.Exceptions; /// /// Thrown when an optimistic-concurrency violation is detected while saving events. @@ -7,8 +7,12 @@ namespace Purview.EventSourcing.SqlServer.Events.Exceptions; /// The idempotency identifier of the save operation. /// The aggregate version that was attempted. /// The version currently present in the store. +/// +/// One type for every provider: a caller catches this without referencing a provider assembly, and +/// recognizes it through . +/// #pragma warning disable CA1032 // Implement standard exception constructors -public class ConcurrencyException(string aggregateId, string idempotencyId, int versionAttempted, int version) +public class ConcurrencyException(string aggregateId, string idempotencyId, long versionAttempted, long version) : Exception( $"Optimistic concurrency error:\n\tAggregateId: {aggregateId}\n\tIdempotencyId: {idempotencyId}\n\tVersionAttempted:{versionAttempted}\n\tVersionPresent:{version}" ), @@ -23,7 +27,7 @@ public class ConcurrencyException(string aggregateId, string idempotencyId, int /// /// The aggregate version that was attempted. /// - public int VersionAttempted { get; } = versionAttempted; + public long VersionAttempted { get; } = versionAttempted; /// /// The idempotency identifier of the save operation. @@ -33,5 +37,5 @@ public class ConcurrencyException(string aggregateId, string idempotencyId, int /// /// The version currently present in the store. /// - public int Version { get; } = version; + public long Version { get; } = version; } diff --git a/src/src/SqlServer/Events/Exceptions/MissingAggregateIdException.cs b/src/src/EventSourcing/Exceptions/MissingAggregateIdException.cs similarity index 52% rename from src/src/SqlServer/Events/Exceptions/MissingAggregateIdException.cs rename to src/src/EventSourcing/Exceptions/MissingAggregateIdException.cs index 892e2ff7..370b3e42 100644 --- a/src/src/SqlServer/Events/Exceptions/MissingAggregateIdException.cs +++ b/src/src/EventSourcing/Exceptions/MissingAggregateIdException.cs @@ -1,16 +1,16 @@ -namespace Purview.EventSourcing.SqlServer.Events.Exceptions; +namespace Purview.EventSourcing.Exceptions; /// -/// Thrown when an attempt is made to save an aggregate that is missing an id. +/// Thrown when a save is attempted for an aggregate that has no id. /// /// The idempotency identifier of the save operation. #pragma warning disable CA1032 // Implement standard exception constructors public class MissingAggregateIdException(string idempotencyId) - : Exception($"An attempt to save an aggregate is a missing Id was made, {nameof(idempotencyId)}: {idempotencyId}.") + : Exception($"An attempt to save an aggregate with a missing Id was made, IdempotencyId: {idempotencyId}.") #pragma warning restore CA1032 // Implement standard exception constructors { /// /// The idempotency identifier of the save operation. /// - public string IdempotencyId { get; set; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); + public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); } diff --git a/src/src/EventSourcing/ExistsStatus.cs b/src/src/EventSourcing/ExistenceStatus.cs similarity index 86% rename from src/src/EventSourcing/ExistsStatus.cs rename to src/src/EventSourcing/ExistenceStatus.cs index c3fa4eb2..a639dd41 100644 --- a/src/src/EventSourcing/ExistsStatus.cs +++ b/src/src/EventSourcing/ExistenceStatus.cs @@ -1,9 +1,9 @@ -namespace Purview.EventSourcing; +namespace Purview.EventSourcing; /// /// Defines states for working out if an aggregate exists. /// -public enum ExistsStatus +public enum ExistenceStatus { /// /// The aggregate does not exist. diff --git a/src/src/EventSourcing/ExistsState.cs b/src/src/EventSourcing/ExistsState.cs deleted file mode 100644 index 14574466..00000000 --- a/src/src/EventSourcing/ExistsState.cs +++ /dev/null @@ -1,47 +0,0 @@ -using System.Diagnostics.CodeAnalysis; - -namespace Purview.EventSourcing; - -/// -/// The result of an exists operations on an aggregate. Is implicitly comparable to a . -/// -/// -/// -/// When converting to a , when the is -/// or , true is returned. -/// -/// Otherwise, false is returned. -/// -[System.Diagnostics.DebuggerStepThrough] -public readonly record struct ExistsState(ExistsStatus Status, int? Version) -{ - /// - /// If is - /// or , then returns true. - /// Otherwise, returns false. - /// - public bool DoesExist => this; - - /// - /// Converts this instance of a to a . - /// - /// The value to convert. - /// Returns true if the equals - public static implicit operator bool([NotNull] ExistsState state) => - state.Status is ExistsStatus.Exists or ExistsStatus.ExistsInDeletedState; - - /// - /// Represents a value that indicates the aggregate does not exist. - /// - public static ExistsState DoesNotExist => new(ExistsStatus.DoesNotExist, null); - - /// - /// Represents a value that indicates the aggregate does exist. - /// - public static ExistsState Exists => new(ExistsStatus.Exists, null); - - /// - /// Represents a value that indicates the aggregate exists, but is in a deleted state. - /// - public static ExistsState ExistsInDeletedState => new(ExistsStatus.ExistsInDeletedState, null); -} diff --git a/src/src/EventSourcing/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/EventSourcing/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs index 4f0e7110..33bff4ad 100644 --- a/src/src/EventSourcing/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs +++ b/src/src/EventSourcing/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -99,6 +99,27 @@ public IServiceCollection AddEventSourcing() .AddSingleton(); services.TryAddSingleton(); + + // TryAdd, so a host that knows who the current user is - a web application resolving it from + // the request - replaces the ambient default by registering its own first. + services.TryAddSingleton(); + + // Defaults to TenantScope.System, which applies no tenant filter, so a single-tenant + // deployment behaves as before. A multi-tenant host registers its own resolver. + services.TryAddSingleton< + Purview.EventSourcing.Tenancy.ICurrentTenant, + Purview.EventSourcing.Tenancy.AmbientCurrentTenant + >(); + + // The generated recorder needs an IMeterFactory, which only a host that configured metrics + // provides. Falling back keeps a host that has not - a console application, a test - working + // instead of failing to resolve the event store; recording metrics is never a precondition + // for persisting events. + services.TryAddSingleton(static serviceProvider => + serviceProvider.GetService() is null + ? NoOpEventStoreMetrics.Instance + : ActivatorUtilities.CreateInstance(serviceProvider) + ); services.TryAddSingleton(); services.TryAddSingleton(); diff --git a/src/src/EventSourcing/Failures/AggregateAlreadyDeleted.cs b/src/src/EventSourcing/Failures/AggregateAlreadyDeleted.cs new file mode 100644 index 00000000..be4a0f61 --- /dev/null +++ b/src/src/EventSourcing/Failures/AggregateAlreadyDeleted.cs @@ -0,0 +1,8 @@ +namespace Purview.EventSourcing.Failures; + +/// +/// A delete was attempted on an aggregate that is already deleted. +/// +/// The aggregate type name. +/// The identifier of the aggregate. +public readonly record struct AggregateAlreadyDeleted(string AggregateType, string AggregateId); diff --git a/src/src/EventSourcing/Failures/AggregateDeleteFailure.cs b/src/src/EventSourcing/Failures/AggregateDeleteFailure.cs new file mode 100644 index 00000000..b79e818d --- /dev/null +++ b/src/src/EventSourcing/Failures/AggregateDeleteFailure.cs @@ -0,0 +1,19 @@ +using Purview.Results; + +namespace Purview.EventSourcing.Failures; + +/// +/// The expected ways a delete of an aggregate fails. +/// +/// +/// Every case is shared with another failure union, so construct them through +/// AggregateDeleteFailure.Failure(...) rather than the per-case helper. +/// +[GenerateResult] +public readonly union AggregateDeleteFailure( + AggregateNotFound, + AggregateAlreadyDeleted, + AggregateLocked, + ConcurrencyConflict, + AggregateInvalid +); diff --git a/src/src/EventSourcing/Failures/AggregateDeleted.cs b/src/src/EventSourcing/Failures/AggregateDeleted.cs new file mode 100644 index 00000000..2dc60d3a --- /dev/null +++ b/src/src/EventSourcing/Failures/AggregateDeleted.cs @@ -0,0 +1,12 @@ +namespace Purview.EventSourcing.Failures; + +/// +/// The stream exists but the aggregate is soft-deleted. +/// +/// The aggregate type name. +/// The identifier of the deleted aggregate. +/// +/// A deleted aggregate can be read with and brought back +/// with . +/// +public readonly record struct AggregateDeleted(string AggregateType, string AggregateId); diff --git a/src/src/EventSourcing/Failures/AggregateInvalid.cs b/src/src/EventSourcing/Failures/AggregateInvalid.cs new file mode 100644 index 00000000..8c004d1c --- /dev/null +++ b/src/src/EventSourcing/Failures/AggregateInvalid.cs @@ -0,0 +1,9 @@ +using Purview.EventSourcing.Validation; + +namespace Purview.EventSourcing.Failures; + +/// +/// Validation rejected the aggregate, so nothing was written. +/// +/// The failures that caused the rejection. +public readonly record struct AggregateInvalid(ValidationResult ValidationResult); diff --git a/src/src/EventSourcing/Failures/AggregateLocked.cs b/src/src/EventSourcing/Failures/AggregateLocked.cs new file mode 100644 index 00000000..9dba107d --- /dev/null +++ b/src/src/EventSourcing/Failures/AggregateLocked.cs @@ -0,0 +1,8 @@ +namespace Purview.EventSourcing.Failures; + +/// +/// The aggregate is locked against modification. +/// +/// The aggregate type name. +/// The identifier of the locked aggregate. +public readonly record struct AggregateLocked(string AggregateType, string AggregateId); diff --git a/src/src/EventSourcing/Failures/AggregateNotDeleted.cs b/src/src/EventSourcing/Failures/AggregateNotDeleted.cs new file mode 100644 index 00000000..c0f01733 --- /dev/null +++ b/src/src/EventSourcing/Failures/AggregateNotDeleted.cs @@ -0,0 +1,8 @@ +namespace Purview.EventSourcing.Failures; + +/// +/// A restore was attempted on an aggregate that is not deleted. +/// +/// The aggregate type name. +/// The identifier of the aggregate. +public readonly record struct AggregateNotDeleted(string AggregateType, string AggregateId); diff --git a/src/src/EventSourcing/Failures/AggregateNotFound.cs b/src/src/EventSourcing/Failures/AggregateNotFound.cs new file mode 100644 index 00000000..6146707a --- /dev/null +++ b/src/src/EventSourcing/Failures/AggregateNotFound.cs @@ -0,0 +1,8 @@ +namespace Purview.EventSourcing.Failures; + +/// +/// No stream exists for the requested aggregate. +/// +/// The aggregate type name. +/// The identifier that was requested. +public readonly record struct AggregateNotFound(string AggregateType, string AggregateId); diff --git a/src/src/EventSourcing/Failures/AggregateReadFailure.cs b/src/src/EventSourcing/Failures/AggregateReadFailure.cs new file mode 100644 index 00000000..f1af9833 --- /dev/null +++ b/src/src/EventSourcing/Failures/AggregateReadFailure.cs @@ -0,0 +1,19 @@ +using Purview.Results; + +namespace Purview.EventSourcing.Failures; + +/// +/// The expected ways a read of an aggregate fails. +/// +/// +/// belongs to the family because +/// GetDeletedAsync is a read: it reports a live aggregate rather than returning one the +/// caller asked for in its deleted state. The other reads never produce it. +/// +[GenerateResult] +public readonly union AggregateReadFailure( + AggregateNotFound, + AggregateDeleted, + AggregateNotDeleted, + AggregateLocked +); diff --git a/src/src/EventSourcing/Failures/AggregateRestoreFailure.cs b/src/src/EventSourcing/Failures/AggregateRestoreFailure.cs new file mode 100644 index 00000000..3d571548 --- /dev/null +++ b/src/src/EventSourcing/Failures/AggregateRestoreFailure.cs @@ -0,0 +1,19 @@ +using Purview.Results; + +namespace Purview.EventSourcing.Failures; + +/// +/// The expected ways a restore of a deleted aggregate fails. +/// +/// +/// Every case is shared with another failure union, so construct them through +/// AggregateRestoreFailure.Failure(...) rather than the per-case helper. +/// +[GenerateResult] +public readonly union AggregateRestoreFailure( + AggregateNotFound, + AggregateNotDeleted, + AggregateLocked, + ConcurrencyConflict, + AggregateInvalid +); diff --git a/src/src/EventSourcing/Failures/AggregateSaveFailure.cs b/src/src/EventSourcing/Failures/AggregateSaveFailure.cs new file mode 100644 index 00000000..cf4d9995 --- /dev/null +++ b/src/src/EventSourcing/Failures/AggregateSaveFailure.cs @@ -0,0 +1,18 @@ +using Purview.Results; + +namespace Purview.EventSourcing.Failures; + +/// +/// The expected ways a save of an aggregate fails. +/// +/// +/// and are shared with other failure unions, so +/// construct them through AggregateSaveFailure.Failure(...) rather than the per-case helper. +/// +[GenerateResult] +public readonly union AggregateSaveFailure( + ConcurrencyConflict, + AggregateDeleted, + AggregateLocked, + AggregateInvalid +); diff --git a/src/src/EventSourcing/Failures/AggregateSaveFailureExtensions.cs b/src/src/EventSourcing/Failures/AggregateSaveFailureExtensions.cs new file mode 100644 index 00000000..a61ce212 --- /dev/null +++ b/src/src/EventSourcing/Failures/AggregateSaveFailureExtensions.cs @@ -0,0 +1,55 @@ +using System.ComponentModel; +using Purview.EventSourcing.Aggregates; +using Purview.Results; + +namespace Purview.EventSourcing.Failures; + +/// +/// Widens a save failure into the delete and restore families, which are implemented on top of a save. +/// +/// +/// Deleting and restoring append an event and go through the same save path, so every way that save can +/// fail has to reach the caller as the failure of the operation they actually asked for. +/// +[EditorBrowsable(EditorBrowsableState.Never)] +public static class AggregateSaveFailureExtensions +{ + /// + /// Converts a save failure into the equivalent delete failure. + /// + /// The aggregate type. + /// The failure reported by the underlying save. + /// The same reason, expressed in the delete family. + public static Result, AggregateDeleteFailure> ToDeleteFailure(this AggregateSaveFailure failure) + where T : class, IAggregate, new() => + failure switch + { + // A save that reports the aggregate is already deleted is, to a delete, an already-deleted + // aggregate rather than an obstacle. + AggregateDeleted deleted => AggregateDeleteFailure.Failure>( + new AggregateAlreadyDeleted(deleted.AggregateType, deleted.AggregateId) + ), + AggregateLocked locked => AggregateDeleteFailure.Failure>(locked), + ConcurrencyConflict conflict => AggregateDeleteFailure.Failure>(conflict), + AggregateInvalid invalid => AggregateDeleteFailure.Failure>(invalid), + _ => throw new ArgumentOutOfRangeException(nameof(failure), failure, "Unhandled save failure."), + }; + + /// + /// Converts a save failure into the equivalent restore failure. + /// + /// The aggregate type. + /// The failure reported by the underlying save. + /// The same reason, expressed in the restore family. + public static Result, AggregateRestoreFailure> ToRestoreFailure(this AggregateSaveFailure failure) + where T : class, IAggregate, new() => + failure switch + { + AggregateLocked locked => AggregateRestoreFailure.Failure>(locked), + ConcurrencyConflict conflict => AggregateRestoreFailure.Failure>(conflict), + AggregateInvalid invalid => AggregateRestoreFailure.Failure>(invalid), + // A restore appends a Restored event, which is exactly what exempts the save from its + // deleted-aggregate check, so AggregateDeleted cannot reach here. + _ => throw new ArgumentOutOfRangeException(nameof(failure), failure, "Unhandled save failure."), + }; +} diff --git a/src/src/EventSourcing/Failures/ConcurrencyConflict.cs b/src/src/EventSourcing/Failures/ConcurrencyConflict.cs new file mode 100644 index 00000000..5377e512 --- /dev/null +++ b/src/src/EventSourcing/Failures/ConcurrencyConflict.cs @@ -0,0 +1,18 @@ +namespace Purview.EventSourcing.Failures; + +/// +/// The write lost an optimistic-concurrency check: the stream moved on after the aggregate was read. +/// +/// The aggregate type name. +/// The identifier of the aggregate. +/// The stream version the write expected. +/// The stream version that was found. +/// +/// This is the case recognizes, and the one a caller re-reads and retries on. +/// +public readonly record struct ConcurrencyConflict( + string AggregateType, + string AggregateId, + long ExpectedVersion, + long ActualVersion +); diff --git a/src/src/EventSourcing/IAggregateEventHistoryStoreCore.cs b/src/src/EventSourcing/IAggregateEventHistoryStoreCore.cs index 7ed9dfe4..71f3bd91 100644 --- a/src/src/EventSourcing/IAggregateEventHistoryStoreCore.cs +++ b/src/src/EventSourcing/IAggregateEventHistoryStoreCore.cs @@ -20,8 +20,8 @@ public interface IAggregateEventHistoryStoreCore /// The events and their persisted names in the requested range. IAsyncEnumerable<(EventRecord EventRecord, string EventType)> GetEventRangeAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, CancellationToken cancellationToken ); } diff --git a/src/src/EventSourcing/IConcurrencyConflict.cs b/src/src/EventSourcing/IConcurrencyConflict.cs index b4c4b60a..b2612735 100644 --- a/src/src/EventSourcing/IConcurrencyConflict.cs +++ b/src/src/EventSourcing/IConcurrencyConflict.cs @@ -5,10 +5,11 @@ namespace Purview.EventSourcing; /// retryable write conflicts from other storage failures across every provider. /// /// -/// Each storage provider surfaces write conflicts through its own -/// ConcurrencyException type. Implementing this interface lets a single retry policy -/// (see ) recognize all of them without -/// referencing provider assemblies. +/// A save reports a lost concurrency check as the result case +/// rather than throwing, so this marker covers the paths that still raise one - a caller's own +/// ConcurrencyException, or an operation outside the save contract - and lets a single retry policy +/// (see ) recognize them without referencing provider +/// assemblies. /// [System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1040:Avoid empty interfaces")] public interface IConcurrencyConflict; diff --git a/src/src/EventSourcing/IEventStore.cs b/src/src/EventSourcing/IEventStore.cs index b7353b54..2c03a501 100644 --- a/src/src/EventSourcing/IEventStore.cs +++ b/src/src/EventSourcing/IEventStore.cs @@ -1,4 +1,6 @@ using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing; @@ -34,9 +36,9 @@ Task CreateAsync(string? aggregateId = null, CancellationToken cancellatio /// Optional, the id of the aggregate to get, or used as the id of the aggregate to create. /// The operational context, controlling things such as if and when exceptions are thrown. /// The stopping token. - /// A existing or new aggregate, or null. - /// Null can be returned if the aggregate exists, but is in a deleted state. This is controlled by the . - Task GetOrCreateAsync( + /// An existing or new aggregate, or the reason it could not be read. + /// is reported if the aggregate exists but is in a deleted state. This is controlled by the . + Task> GetOrCreateAsync( string? aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -49,8 +51,8 @@ Task CreateAsync(string? aggregateId = null, CancellationToken cancellatio /// The id of the . /// The that controls how the aggregate is retrieved. /// The stopping token. - /// The requested of based on the , or null. - Task GetAsync( + /// The requested of based on the , or the reason it could not be read. + Task> GetAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -64,13 +66,13 @@ Task CreateAsync(string? aggregateId = null, CancellationToken cancellatio /// The version of the aggregate to get. /// The that controls how the aggregate is retrieved. /// The stopping token. - /// The requested of based on the , or null. + /// The requested of based on the , or the reason it could not be read. /// The resulting aggregate, if any, will be in a locked state preventing any modifications. /// This includes applying new events, or attempting to save, delete or restore the aggregate. /// - Task GetAtAsync( + Task> GetAtAsync( string aggregateId, - int version, + long version, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) @@ -82,34 +84,27 @@ Task CreateAsync(string? aggregateId = null, CancellationToken cancellatio /// The to save. /// The that controls how the aggregate is saved. /// The stopping token. - /// An detailing the result of the save operation. + /// The outcome of the save, or the reason it did not happen. /// The underlying persistence store should ensure that no existing events are overridden, and /// the events and additional data are persisted in a transactional way. - Task> SaveAsync( + Task, AggregateSaveFailure>> SaveAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) where T : class, IAggregate, new(); - /// - /// Determines if the of type as specified by exists - /// in the deleted state. - /// - /// The Id of the to check. - /// The stopping token. - /// Returns true if the aggregate exists in the deleted state, otherwise, returns false. - Task IsDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) - where T : class, IAggregate, new(); - /// /// Gets an of given the specified . /// /// The Id of the deleted aggregate to get. /// The stopping token. - /// If the aggregate is not found, returns null. If the aggregate was found, but is not deleted - /// an exception is thrown. Otherwise, returns the aggregate. - Task GetDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) + /// The deleted aggregate, when no stream exists, or + /// when the aggregate was found but is live. + Task> GetDeletedAsync( + string aggregateId, + CancellationToken cancellationToken = default + ) where T : class, IAggregate, new(); /// @@ -118,10 +113,10 @@ Task IsDeletedAsync(string aggregateId, CancellationToken cancellationT /// The aggregate to delete. /// The that controls how the aggregate is deleted. /// The stopping token. - /// Indicates if the operation successfully deleted the aggregate. + /// The outcome of the delete, or the reason it did not happen. /// If the is true, the aggregate and all /// of it's associated data is permanently deleted. If false (the default), the aggregate is soft-deleted. - Task DeleteAsync( + Task, AggregateDeleteFailure>> DeleteAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -134,8 +129,8 @@ Task DeleteAsync( /// The aggregate to restore, usually obtained from . /// The that controls how the aggregate is restored. /// The stopping token. - /// Returns true if the aggregate was successfully restored, otherwise, false. - Task RestoreAsync( + /// The outcome of the restore, or the reason it did not happen. + Task, AggregateRestoreFailure>> RestoreAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -157,9 +152,9 @@ IAsyncEnumerable GetAggregateIdsAsync(bool includeDeleted, Cancellati /// /// The id of the aggregate to check. /// The stopping token. - /// A that determines the existence (in either a deleted or non-deleted state), + /// A that determines the existence (in either a deleted or non-deleted state), /// or if it exists at all. If the aggregate does exist, it's version is also returned. - Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) + Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) where T : class, IAggregate, new(); /// @@ -181,8 +176,8 @@ T FulfilRequirements(T aggregate) /// If no is specified all available events greater than are returned. IAsyncEnumerable<(EventRecord EventRecord, string EventType)> GetEventRangeAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, CancellationToken cancellationToken ) where T : class, IAggregate, new(); diff --git a/src/src/EventSourcing/IEventStoreCore.cs b/src/src/EventSourcing/IEventStoreCore.cs index 78589bea..2228b5e7 100644 --- a/src/src/EventSourcing/IEventStoreCore.cs +++ b/src/src/EventSourcing/IEventStoreCore.cs @@ -1,5 +1,7 @@ using System.ComponentModel; using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing; @@ -27,8 +29,11 @@ public interface IEventStoreCore /// Optional, the id of the aggregate to get, or use as the id of the aggregate to create. /// The operational context controlling how the aggregate is retrieved. /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - Task GetOrCreateAsync( + /// + /// The existing or newly created aggregate, or the reason it could not be read - the aggregate is + /// deleted or locked. + /// + Task> GetOrCreateAsync( string? aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -40,8 +45,11 @@ public interface IEventStoreCore /// The id of the aggregate to get. /// The operational context controlling how the aggregate is retrieved. /// A token that can be used to cancel the operation. - /// The requested aggregate, or null when it does not exist. - Task GetAsync( + /// + /// The requested aggregate, or the reason it could not be read - no stream exists, or the + /// aggregate is deleted or locked. + /// + Task> GetAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -54,10 +62,13 @@ public interface IEventStoreCore /// The version of the aggregate to get. /// The operational context controlling how the aggregate is retrieved. /// A token that can be used to cancel the operation. - /// The requested aggregate, or null when it does not exist. - Task GetAtAsync( + /// + /// The requested aggregate at that version, or the reason it could not be read - no stream + /// exists, or the aggregate is deleted or locked. + /// + Task> GetAtAsync( string aggregateId, - int version, + long version, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ); @@ -68,28 +79,29 @@ public interface IEventStoreCore /// The aggregate to save. /// The operational context controlling how the aggregate is saved. /// A token that can be used to cancel the operation. - /// A describing the result of the save. - Task> SaveAsync( + /// + /// The outcome of the save, or the reason it did not happen - validation rejected the aggregate, + /// the aggregate is deleted or locked, or the write lost a concurrency check. + /// + Task, AggregateSaveFailure>> SaveAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ); - /// - /// Determines if the aggregate exists in the deleted state. - /// - /// The id of the aggregate to check. - /// A token that can be used to cancel the operation. - /// True when the aggregate exists in the deleted state, otherwise false. - Task IsDeletedAsync(string aggregateId, CancellationToken cancellationToken = default); - /// /// Gets a deleted aggregate. /// /// The id of the deleted aggregate to get. /// A token that can be used to cancel the operation. - /// The deleted aggregate, or null when it is not found. - Task GetDeletedAsync(string aggregateId, CancellationToken cancellationToken = default); + /// + /// The deleted aggregate, or the reason it could not be read - no stream exists, or the + /// aggregate is not deleted. + /// + Task> GetDeletedAsync( + string aggregateId, + CancellationToken cancellationToken = default + ); /// /// Deletes the aggregate. @@ -97,8 +109,11 @@ Task> SaveAsync( /// The aggregate to delete. /// The operational context controlling how the aggregate is deleted. /// A token that can be used to cancel the operation. - /// True when the aggregate was successfully deleted, otherwise false. - Task DeleteAsync( + /// + /// The outcome of the delete, or the reason it did not happen - the aggregate was already deleted, + /// locked, had no stream, or the delete lost a concurrency check. + /// + Task, AggregateDeleteFailure>> DeleteAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -110,8 +125,11 @@ Task DeleteAsync( /// The aggregate to restore. /// The operational context controlling how the aggregate is restored. /// A token that can be used to cancel the operation. - /// True when the aggregate was successfully restored, otherwise false. - Task RestoreAsync( + /// + /// The outcome of the restore, or the reason it did not happen - the aggregate was not deleted, + /// locked, had no stream, or the restore lost a concurrency check. + /// + Task, AggregateRestoreFailure>> RestoreAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -130,8 +148,8 @@ Task RestoreAsync( /// /// The id of the aggregate to check. /// A token that can be used to cancel the operation. - /// An describing the existence of the aggregate. - Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default); + /// An describing the existence of the aggregate. + Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default); /// /// Fulfils the aggregate's requirements by injecting the required services. @@ -150,8 +168,8 @@ Task RestoreAsync( /// The events and their persisted names in the requested range. IAsyncEnumerable<(EventRecord EventRecord, string EventType)> GetEventRangeAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, CancellationToken cancellationToken ); } diff --git a/src/src/EventSourcing/IEventStoreCoreExtensions.cs b/src/src/EventSourcing/IEventStoreCoreExtensions.cs index bf308f5e..50b87ad8 100644 --- a/src/src/EventSourcing/IEventStoreCoreExtensions.cs +++ b/src/src/EventSourcing/IEventStoreCoreExtensions.cs @@ -1,7 +1,8 @@ using System.ComponentModel; using System.Diagnostics.CodeAnalysis; using Purview.EventSourcing.Aggregates; -using Purview.EventSourcing.Services; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing; @@ -19,128 +20,6 @@ namespace Purview.EventSourcing; [System.Diagnostics.DebuggerStepThrough] public static class IEventStoreCoreExtensions { - #region QuickCreate/ QuickCreateAsync - - /// - /// Creates a new , but will not call - /// to create a new Id. It will take the parameter, or the id parameter is null or empty - /// use a new lowered . - /// - /// The used as the root object. - /// The to create. - /// The id to use, or null with either the specified or a generated id. - /// A new aggregate of . - /// Calls to apply any requirements. - public static T QuickCreate([NotNull] this IEventStoreCore eventStore, string? aggregateId = null) - where T : class, IAggregate, new() - { - if (string.IsNullOrWhiteSpace(aggregateId)) - aggregateId = $"{Guid.NewGuid():D}"; - - T aggregate = new() { Details = new() { Id = aggregateId } }; - - eventStore.FulfilRequirements(aggregate); - - return aggregate; - } - - /// - /// Creates a new aggregate of using the string representation of the id. - /// - /// The used as the root object. - /// The to create. - /// The id to use; when null, a new is generated. - /// A new aggregate of . - public static T QuickCreate(this IEventStoreCore eventStore, object? aggregateId) - where T : class, IAggregate, new() => eventStore.QuickCreate(aggregateId?.ToString()); - - /// - /// Creates a new aggregate of and runs the callback - /// against it. - /// - /// The used as the root object. - /// The to create. - /// The id to use; when null, a new is generated. - /// The callback used to initialize the new aggregate. - /// The initialized aggregate. - public static T QuickCreate(this IEventStoreCore eventStore, string? aggregateId, [NotNull] Action creator) - where T : class, IAggregate, new() - { - var aggregate = eventStore.QuickCreate(aggregateId); - - creator(aggregate); - - return aggregate; - } - - /// - /// Creates a new aggregate of using the string representation of the id and runs - /// the callback against it. - /// - /// The used as the root object. - /// The to create. - /// The id to use; when null, a new is generated. - /// The callback used to initialize the new aggregate. - /// The initialized aggregate. - public static T QuickCreate(this IEventStoreCore eventStore, object? aggregateId, Action creator) - where T : class, IAggregate, new() => eventStore.QuickCreate(aggregateId?.ToString(), creator); - - /// - /// Asynchronously creates a new aggregate of and runs the - /// callback against it. - /// - /// The used as the root object. - /// The to create. - /// The id to use; when null, a new is generated. - /// The asynchronous callback used to initialize the new aggregate. - /// A token that can be used to cancel the operation. - /// The initialized aggregate. - public static async Task QuickCreateAsync( - this IEventStoreCore eventStore, - string? aggregateId, - [NotNull] Func creator, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = eventStore.QuickCreate(aggregateId); - - await creator(aggregate, cancellationToken); - - return aggregate; - } - - /// - /// Asynchronously creates a new aggregate of using the string representation of the - /// id and runs the callback against it. - /// - /// The used as the root object. - /// The to create. - /// The id to use; when null, a new is generated. - /// The asynchronous callback used to initialize the new aggregate. - /// A token that can be used to cancel the operation. - /// The initialized aggregate. - public static async Task QuickCreateAsync( - this IEventStoreCore eventStore, - object? aggregateId, - [NotNull] Func creator, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = eventStore.QuickCreate(aggregateId?.ToString()); - - await creator(aggregate, cancellationToken); - - return aggregate; - } - - #endregion QuickCreate/ QuickCreateAsync - - #region GetOrCreateAsync - - #region id: string, with context. - /// /// Gets the aggregate for the id, creating and initializing it with the when it /// does not yet exist. @@ -151,8 +30,8 @@ public static async Task QuickCreateAsync( /// The asynchronous callback used to initialize a newly created aggregate. /// The operational context controlling how the aggregate is retrieved. /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - public static async Task GetOrCreateAsync( + /// The existing or newly created aggregate, or the reason it could not be read. + public static async Task> GetOrCreateAsync( [NotNull] this IEventStoreCore eventStore, string? aggregateId, [NotNull] Func creator, @@ -161,44 +40,17 @@ public static async Task QuickCreateAsync( ) where T : class, IAggregate, new() { - var aggregate = await eventStore.GetOrCreateAsync(aggregateId, context, cancellationToken); - if (aggregate?.IsNew() == true) - await creator(aggregate, cancellationToken); + var result = await eventStore.GetOrCreateAsync(aggregateId, context, cancellationToken); + if (result.IsFailure) + return result; - return aggregate; - } - - /// - /// Gets the aggregate for the id, creating and initializing it with the when it - /// does not yet exist. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get, or use as the id of the aggregate to create. - /// The callback used to initialize a newly created aggregate. - /// The operational context controlling how the aggregate is retrieved. - /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - public static async Task GetOrCreateAsync( - [NotNull] this IEventStoreCore eventStore, - string? aggregateId, - [NotNull] Action creator, - EventStoreOperationContext? context, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = await eventStore.GetOrCreateAsync(aggregateId, context, cancellationToken); - if (aggregate?.IsNew() == true) - creator(aggregate); + var aggregate = result.Value; + if (aggregate.IsNew()) + await creator(aggregate, cancellationToken); return aggregate; } - #endregion id: string, with context. - - #region id: string, without context. - /// /// Gets the aggregate for the id, creating it when it does not yet exist using the default context. /// @@ -206,8 +58,8 @@ public static async Task QuickCreateAsync( /// The used as the root object. /// The id of the aggregate to get, or use as the id of the aggregate to create. /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - public static Task GetOrCreateAsync( + /// The existing or newly created aggregate, or the reason it could not be read. + public static Task> GetOrCreateAsync( [NotNull] this IEventStoreCore eventStore, string? aggregateId, CancellationToken cancellationToken = default @@ -223,200 +75,26 @@ public static async Task QuickCreateAsync( /// The id of the aggregate to get, or use as the id of the aggregate to create. /// The asynchronous callback used to initialize a newly created aggregate. /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - public static async Task GetOrCreateAsync( - [NotNull] this IEventStoreCore eventStore, - string? aggregateId, - [NotNull] Func creator, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = await eventStore.GetOrCreateAsync(aggregateId, null, cancellationToken); - if (aggregate?.IsNew() == true) - await creator(aggregate, cancellationToken); - - return aggregate; - } - - /// - /// Gets the aggregate for the id, creating and initializing it with the when it - /// does not yet exist using the default context. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get, or use as the id of the aggregate to create. - /// The callback used to initialize a newly created aggregate. - /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - public static async Task GetOrCreateAsync( + /// The existing or newly created aggregate, or the reason it could not be read. + public static async Task> GetOrCreateAsync( [NotNull] this IEventStoreCore eventStore, string? aggregateId, - [NotNull] Action creator, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = await eventStore.GetOrCreateAsync(aggregateId, null, cancellationToken); - if (aggregate?.IsNew() == true) - creator(aggregate); - - return aggregate; - } - - #endregion id: string, without context. - - #region id: object, with context. - - /// - /// Gets the aggregate for the string representation of the id, creating it when it does not yet exist. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get, or use as the id of the aggregate to create. - /// The operational context controlling how the aggregate is retrieved. - /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - public static Task GetOrCreateAsync( - [NotNull] this IEventStoreCore eventStore, - object? aggregateId, - EventStoreOperationContext? operationContext, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() => - eventStore.GetOrCreateAsync(aggregateId?.ToString(), operationContext, cancellationToken); - - /// - /// Gets the aggregate for the string representation of the id, creating and initializing it with the - /// when it does not yet exist. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get, or use as the id of the aggregate to create. - /// The asynchronous callback used to initialize a newly created aggregate. - /// The operational context controlling how the aggregate is retrieved. - /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - public static async Task GetOrCreateAsync( - [NotNull] this IEventStoreCore eventStore, - object? aggregateId, [NotNull] Func creator, - EventStoreOperationContext? context, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = await eventStore.GetOrCreateAsync(aggregateId?.ToString(), context, cancellationToken); - if (aggregate?.IsNew() == true) - await creator(aggregate, cancellationToken); - - return aggregate; - } - - /// - /// Gets the aggregate for the string representation of the id, creating and initializing it with the - /// when it does not yet exist. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get, or use as the id of the aggregate to create. - /// The callback used to initialize a newly created aggregate. - /// The operational context controlling how the aggregate is retrieved. - /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - public static async Task GetOrCreateAsync( - [NotNull] this IEventStoreCore eventStore, - object? aggregateId, - [NotNull] Action creator, - EventStoreOperationContext? context, CancellationToken cancellationToken = default ) where T : class, IAggregate, new() { - var aggregate = await eventStore.GetOrCreateAsync(aggregateId?.ToString(), context, cancellationToken); - if (aggregate?.IsNew() == true) - creator(aggregate); - - return aggregate; - } - - #endregion id: object, with context. + var result = await eventStore.GetOrCreateAsync(aggregateId, null, cancellationToken); + if (result.IsFailure) + return result; - #region id: object, no context. - - /// - /// Gets the aggregate for the string representation of the id, creating it when it does not yet exist - /// using the default context. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get, or use as the id of the aggregate to create. - /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - public static Task GetOrCreateAsync( - [NotNull] this IEventStoreCore eventStore, - object? aggregateId, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() => - eventStore.GetOrCreateAsync(aggregateId?.ToString(), null, cancellationToken); - - /// - /// Gets the aggregate for the string representation of the id, creating and initializing it with the - /// when it does not yet exist using the default context. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get, or use as the id of the aggregate to create. - /// The asynchronous callback used to initialize a newly created aggregate. - /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - public static async Task GetOrCreateAsync( - [NotNull] this IEventStoreCore eventStore, - object? aggregateId, - [NotNull] Func creator, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = await eventStore.GetOrCreateAsync(aggregateId?.ToString(), null, cancellationToken); - if (aggregate?.IsNew() == true) + var aggregate = result.Value; + if (aggregate.IsNew()) await creator(aggregate, cancellationToken); return aggregate; } - /// - /// Gets the aggregate for the string representation of the id, creating and initializing it with the - /// when it does not yet exist using the default context. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get, or use as the id of the aggregate to create. - /// The callback used to initialize a newly created aggregate. - /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - public static async Task GetOrCreateAsync( - [NotNull] this IEventStoreCore eventStore, - object? id, - [NotNull] Action creator, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = await eventStore.GetOrCreateAsync(id?.ToString(), null, cancellationToken); - if (aggregate?.IsNew() == true) - creator(aggregate); - - return aggregate; - } - - #endregion id: object, no context. - - #endregion GetOrCreateAsync - - #region CreateAsync - /// /// Creates a new aggregate of and optionally runs the /// callback against it. @@ -442,98 +120,6 @@ public static async Task CreateAsync( return aggregate; } - /// - /// Creates a new aggregate of and optionally runs the - /// callback against it. - /// - /// The to create. - /// The used as the root object. - /// Optional, the id of the aggregate to create; when null, an id is generated. - /// Optional callback used to initialize the new aggregate. - /// A token that can be used to cancel the operation. - /// The newly created aggregate. - public static async Task CreateAsync( - [NotNull] this IEventStoreCore eventStore, - string? aggregateId = null, - Action? creator = null, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = await eventStore.CreateAsync(aggregateId, cancellationToken); - creator?.Invoke(aggregate); - - return aggregate; - } - - /// - /// Creates a new aggregate of using the string representation of the id. - /// - /// The to create. - /// The used as the root object. - /// Optional, the id of the aggregate to create; when null, an id is generated. - /// A token that can be used to cancel the operation. - /// The newly created aggregate. - public static Task CreateAsync( - [NotNull] this IEventStoreCore eventStore, - object? aggregateId = null, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() => eventStore.CreateAsync(aggregateId?.ToString(), cancellationToken); - - /// - /// Creates a new aggregate of using the string representation of the id and - /// optionally runs the callback against it. - /// - /// The to create. - /// The used as the root object. - /// Optional, the id of the aggregate to create; when null, an id is generated. - /// Optional asynchronous callback used to initialize the new aggregate. - /// A token that can be used to cancel the operation. - /// The newly created aggregate. - public static async Task CreateAsync( - [NotNull] this IEventStoreCore eventStore, - object? aggregateId = null, - Func? creator = null, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = await eventStore.CreateAsync(aggregateId?.ToString(), cancellationToken); - if (creator != null) - await creator(aggregate, cancellationToken); - - return aggregate; - } - - /// - /// Creates a new aggregate of using the string representation of the id and - /// optionally runs the callback against it. - /// - /// The to create. - /// The used as the root object. - /// Optional, the id of the aggregate to create; when null, an id is generated. - /// Optional callback used to initialize the new aggregate. - /// A token that can be used to cancel the operation. - /// The newly created aggregate. - public static async Task CreateAsync( - [NotNull] this IEventStoreCore eventStore, - object? aggregateId = null, - Action? creator = null, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = await eventStore.CreateAsync(aggregateId?.ToString(), cancellationToken); - creator?.Invoke(aggregate); - - return aggregate; - } - - #endregion CreateAsync - - #region GetAsync - /// /// Gets the aggregate for the id using the default operation context. /// @@ -541,64 +127,14 @@ public static async Task CreateAsync( /// The used as the root object. /// The id of the aggregate to get. /// A token that can be used to cancel the operation. - /// The requested aggregate, or null when it does not exist. - public static Task GetAsync( + /// The requested aggregate, or the reason it could not be read. + public static Task> GetAsync( [NotNull] this IEventStoreCore eventStore, string aggregateId, CancellationToken cancellationToken = default ) where T : class, IAggregate, new() => eventStore.GetAsync(aggregateId, null, cancellationToken); - /// - /// Gets the aggregate for the string representation of the id using the default operation context. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get. - /// A token that can be used to cancel the operation. - /// The requested aggregate, or null when it does not exist. - /// Thrown when has no string representation. - public static Task GetAsync( - [NotNull] this IEventStoreCore eventStore, - object aggregateId, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var idAsString = aggregateId?.ToString(); - ArgumentException.ThrowIfNullOrWhiteSpace(idAsString, nameof(aggregateId)); - - return eventStore.GetAsync(idAsString, null, cancellationToken); - } - - /// - /// Gets the aggregate for the string representation of the id using the supplied operation context. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get. - /// The operational context controlling how the aggregate is retrieved. - /// A token that can be used to cancel the operation. - /// The requested aggregate, or null when it does not exist. - /// Thrown when has no string representation. - public static Task GetAsync( - [NotNull] this IEventStoreCore eventStore, - object aggregateId, - EventStoreOperationContext? context, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var idAsString = aggregateId?.ToString(); - ArgumentException.ThrowIfNullOrWhiteSpace(idAsString, nameof(aggregateId)); - - return eventStore.GetAsync(idAsString, context, cancellationToken); - } - - #endregion GetAsync - - #region GetAtAsync - /// /// Gets the aggregate up to a specific version using the default operation context. /// @@ -607,184 +143,15 @@ public static async Task CreateAsync( /// The id of the aggregate to get. /// The version of the aggregate to get. /// A token that can be used to cancel the operation. - /// The requested aggregate, or null when it does not exist. - public static Task GetAtAsync( + /// The requested aggregate, or the reason it could not be read. + public static Task> GetAtAsync( [NotNull] this IEventStoreCore eventStore, string aggregateId, - int version, + long version, CancellationToken cancellationToken = default ) where T : class, IAggregate, new() => eventStore.GetAtAsync(aggregateId, version, null, cancellationToken); - /// - /// Gets the aggregate up to a specific version using the string representation of the id. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get. - /// The version of the aggregate to get. - /// A token that can be used to cancel the operation. - /// The requested aggregate, or null when it does not exist. - public static Task GetAtAsync( - [NotNull] this IEventStoreCore eventStore, - object aggregateId, - int version, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() => eventStore.GetAtAsync(aggregateId, version, null, cancellationToken); - - /// - /// Gets the aggregate up to a specific version using the string representation of the id and the supplied - /// operation context. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get. - /// The version of the aggregate to get. - /// The operational context controlling how the aggregate is retrieved. - /// A token that can be used to cancel the operation. - /// The requested aggregate, or null when it does not exist. - /// Thrown when has no string representation. - public static Task GetAtAsync( - [NotNull] this IEventStoreCore eventStore, - object aggregateId, - int version, - EventStoreOperationContext? context, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var idAsString = aggregateId?.ToString(); - ArgumentException.ThrowIfNullOrWhiteSpace(idAsString, nameof(aggregateId)); - - return eventStore.GetAtAsync(idAsString, version, context, cancellationToken); - } - - #endregion GetAtAsync - - #region IsDeletedAsync - - /// - /// Determines if the aggregate with the string representation of the id exists in the deleted state. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to check. - /// A token that can be used to cancel the operation. - /// True when the aggregate exists in the deleted state, otherwise false. - /// Thrown when has no string representation. - public static Task IsDeletedAsync( - [NotNull] this IEventStoreCore eventStore, - object aggregateId, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var idAsString = aggregateId?.ToString(); - ArgumentException.ThrowIfNullOrWhiteSpace(idAsString, nameof(aggregateId)); - - return eventStore.IsDeletedAsync(idAsString, cancellationToken); - } - - #endregion IsDeletedAsync - - #region GetDeletedAsync - - /// - /// Gets a deleted aggregate using the string representation of the id. - /// - /// The type. - /// The used as the root object. - /// The id of the deleted aggregate to get. - /// A token that can be used to cancel the operation. - /// The deleted aggregate, or null when it is not found. - /// Thrown when has no string representation. - public static Task GetDeletedAsync( - [NotNull] this IEventStoreCore eventStore, - object aggregateId, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var idAsString = aggregateId?.ToString(); - ArgumentException.ThrowIfNullOrWhiteSpace(idAsString, nameof(aggregateId)); - - return eventStore.GetDeletedAsync(idAsString, cancellationToken); - } - - #endregion GetDeletedAsync - - #region ExistsAsync - - /// - /// Determines if the aggregate with the string representation of the id exists, including deleted states. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to check. - /// A token that can be used to cancel the operation. - /// An describing the existence of the aggregate. - /// Thrown when has no string representation. - public static Task ExistsAsync( - [NotNull] this IEventStoreCore eventStore, - object aggregateId, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var idAsString = aggregateId?.ToString(); - ArgumentException.ThrowIfNullOrWhiteSpace(idAsString, nameof(aggregateId)); - - return eventStore.ExistsAsync(idAsString, cancellationToken); - } - - /// - /// Determines if the aggregate with the string representation of the id exists, returning - /// for null or blank ids instead of throwing. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to check. - /// A token that can be used to cancel the operation. - /// An describing the existence of the aggregate. - public static Task ExistsWithNullCheckAsync( - [NotNull] this IEventStoreCore eventStore, - object aggregateId, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var idAsString = aggregateId?.ToString(); - ArgumentException.ThrowIfNullOrWhiteSpace(idAsString, nameof(aggregateId)); - - return eventStore.ExistsWithNullCheckAsync(idAsString, cancellationToken); - } - - /// - /// Determines if the aggregate exists, returning for null or blank - /// ids instead of throwing. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to check. - /// A token that can be used to cancel the operation. - /// An describing the existence of the aggregate. - public static Task ExistsWithNullCheckAsync( - [NotNull] this IEventStoreCore eventStore, - string aggregateId, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - return string.IsNullOrWhiteSpace(aggregateId) - ? Task.FromResult(ExistsState.DoesNotExist) - : eventStore.ExistsAsync(aggregateId, cancellationToken); - } - - #endregion ExistsAsync - - #region Enlist - /// /// Creates a new and enlists all /// against this event store, using an auto-generated correlation ID. @@ -851,10 +218,6 @@ params T[] aggregates return transaction; } - #endregion Enlist - - #region SaveAsync - /// /// Saves the aggregate using the default operation context. /// @@ -862,18 +225,14 @@ params T[] aggregates /// The used as the root object. /// The aggregate to save. /// A token that can be used to cancel the operation. - /// A describing the result of the save. - public static Task> SaveAsync( + /// The outcome of the save, or the reason it did not happen. + public static Task, AggregateSaveFailure>> SaveAsync( [NotNull] this IEventStoreCore eventStore, T aggregate, CancellationToken cancellationToken = default ) where T : class, IAggregate, new() => eventStore.SaveAsync(aggregate, null, cancellationToken); - #endregion SaveAsync - - #region DeleteAsync - /// /// Deletes the aggregate using the default operation context. /// @@ -881,8 +240,8 @@ public static Task> SaveAsync( /// The used as the root object. /// The aggregate to delete. /// A token that can be used to cancel the operation. - /// True when the aggregate was successfully deleted, otherwise false. - public static Task DeleteAsync( + /// The outcome of the delete, or the reason it did not happen. + public static Task, AggregateDeleteFailure>> DeleteAsync( [NotNull] this IEventStoreCore eventStore, T aggregate, CancellationToken cancellationToken = default @@ -896,8 +255,8 @@ public static Task DeleteAsync( /// The used as the root object. /// The id of the aggregate to delete. /// A token that can be used to cancel the operation. - /// True when the aggregate was successfully deleted, otherwise false. - public static Task DeleteAsync( + /// The outcome of the delete, or the reason it did not happen. + public static Task, AggregateDeleteFailure>> DeleteAsync( [NotNull] this IEventStoreCore eventStore, string aggregateId, CancellationToken cancellationToken = default @@ -912,9 +271,9 @@ public static Task DeleteAsync( /// The id of the aggregate to delete. /// The operational context controlling how the aggregate is deleted. /// A token that can be used to cancel the operation. - /// True when the aggregate was successfully deleted, otherwise false. + /// The outcome of the delete, or the reason it did not happen. /// Thrown when is null or whitespace. - public static async Task DeleteAsync( + public static async Task, AggregateDeleteFailure>> DeleteAsync( [NotNull] this IEventStoreCore eventStore, string aggregateId, EventStoreOperationContext? operationContext, @@ -924,13 +283,30 @@ public static async Task DeleteAsync( { ArgumentException.ThrowIfNullOrWhiteSpace(aggregateId, nameof(aggregateId)); - var aggregate = await eventStore.GetAsync(aggregateId, operationContext, cancellationToken); - return aggregate != null && await eventStore.DeleteAsync(aggregate, operationContext, cancellationToken); - } + var result = await eventStore.GetAsync(aggregateId, operationContext, cancellationToken); - #endregion DeleteAsync + return result.IsFailure + ? ToDeleteFailure(result.Error, aggregateId) + : await eventStore.DeleteAsync(result.Value, operationContext, cancellationToken); + } - #region RestoreAsync + // A read that fails on the way to a delete is still a delete failure, so the read case is widened + // rather than reported as "not found" for every reason the read did not produce an aggregate. + static Result, AggregateDeleteFailure> ToDeleteFailure( + AggregateReadFailure failure, + string aggregateId + ) + where T : class, IAggregate, new() => + failure switch + { + AggregateDeleted deleted => AggregateDeleteFailure.Failure>( + new AggregateAlreadyDeleted(deleted.AggregateType, deleted.AggregateId) + ), + AggregateLocked locked => AggregateDeleteFailure.Failure>(locked), + AggregateNotFound notFound => AggregateDeleteFailure.Failure>(notFound), + // GetAsync never reports AggregateNotDeleted; it belongs to GetDeletedAsync. + _ => AggregateDeleteFailure.Failure>(new AggregateNotFound(typeof(T).Name, aggregateId)), + }; /// /// Restores a previously deleted aggregate using the default operation context. @@ -939,13 +315,11 @@ public static async Task DeleteAsync( /// The used as the root object. /// The aggregate to restore. /// A token that can be used to cancel the operation. - /// True when the aggregate was successfully restored, otherwise false. - public static Task RestoreAsync( + /// The outcome of the restore, or the reason it did not happen. + public static Task, AggregateRestoreFailure>> RestoreAsync( [NotNull] this IEventStoreCore eventStore, T aggregate, CancellationToken cancellationToken = default ) where T : class, IAggregate, new() => eventStore.RestoreAsync(aggregate, null, cancellationToken); - - #endregion RestoreAsync } diff --git a/src/src/EventSourcing/IEventStoreExtensions.cs b/src/src/EventSourcing/IEventStoreExtensions.cs index e277746c..d3357338 100644 --- a/src/src/EventSourcing/IEventStoreExtensions.cs +++ b/src/src/EventSourcing/IEventStoreExtensions.cs @@ -1,7 +1,8 @@ using System.ComponentModel; using System.Diagnostics.CodeAnalysis; using Purview.EventSourcing.Aggregates; -using Purview.EventSourcing.Services; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing; @@ -17,774 +18,8 @@ namespace Purview.EventSourcing; /// [EditorBrowsable(EditorBrowsableState.Never)] [System.Diagnostics.DebuggerStepThrough] -public static class IEventStoreExtensions +public static partial class IEventStoreExtensions { - #region QuickCreate/ QuickCreateAsync - - /// - /// Creates a new , but will not call - /// to create a new Id. It will take the parameter, or the id parameter is null or empty - /// use a new lowered . - /// - /// The used as the root object. - /// The to create. - /// The id to use, or null with either the specified or a generated id. - /// A new aggregate of . - /// Calls to apply any requirements. - public static T QuickCreate([NotNull] this IEventStore eventStore, string? aggregateId = null) - where T : class, IAggregate, new() - { - if (string.IsNullOrWhiteSpace(aggregateId)) - aggregateId = $"{Guid.NewGuid()}:D"; - - T aggregate = new() { Details = new() { Id = aggregateId } }; - - eventStore.FulfilRequirements(aggregate); - - return aggregate; - } - - /// - /// Creates a new aggregate of using the string representation of the id. - /// - /// The used as the root object. - /// The to create. - /// The id to use; when null, a new is generated. - /// A new aggregate of . - public static T QuickCreate(this IEventStore eventStore, object? aggregateId) - where T : class, IAggregate, new() => eventStore.QuickCreate(aggregateId?.ToString()); - - /// - /// Creates a new aggregate of and runs the callback - /// against it. - /// - /// The used as the root object. - /// The to create. - /// The id to use; when null, a new is generated. - /// The callback used to initialize the new aggregate. - /// The initialized aggregate. - public static T QuickCreate(this IEventStore eventStore, string? aggregateId, [NotNull] Action creator) - where T : class, IAggregate, new() - { - var aggregate = eventStore.QuickCreate(aggregateId); - - creator(aggregate); - - return aggregate; - } - - /// - /// Creates a new aggregate of using the string representation of the id and runs - /// the callback against it. - /// - /// The used as the root object. - /// The to create. - /// The id to use; when null, a new is generated. - /// The callback used to initialize the new aggregate. - /// The initialized aggregate. - public static T QuickCreate(this IEventStore eventStore, object? aggregateId, Action creator) - where T : class, IAggregate, new() => eventStore.QuickCreate(aggregateId?.ToString(), creator); - - /// - /// Asynchronously creates a new aggregate of and runs the - /// callback against it. - /// - /// The used as the root object. - /// The to create. - /// The id to use; when null, a new is generated. - /// The asynchronous callback used to initialize the new aggregate. - /// A token that can be used to cancel the operation. - /// The initialized aggregate. - public static async Task QuickCreateAsync( - this IEventStore eventStore, - string? aggregateId, - [NotNull] Func creator, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = eventStore.QuickCreate(aggregateId); - - await creator(aggregate, cancellationToken); - - return aggregate; - } - - /// - /// Asynchronously creates a new aggregate of using the string representation of the - /// id and runs the callback against it. - /// - /// The used as the root object. - /// The to create. - /// The id to use; when null, a new is generated. - /// The asynchronous callback used to initialize the new aggregate. - /// A token that can be used to cancel the operation. - /// The initialized aggregate. - public static async Task QuickCreateAsync( - this IEventStore eventStore, - object? aggregateId, - [NotNull] Func creator, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = eventStore.QuickCreate(aggregateId?.ToString()); - - await creator(aggregate, cancellationToken); - - return aggregate; - } - - #endregion QuickCreate/ QuickCreateAsync - - #region GetOrCreateAsync - - #region id: string, with context. - - /// - /// Gets the aggregate for the id, creating and initializing it with the when it - /// does not yet exist. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get, or use as the id of the aggregate to create. - /// The asynchronous callback used to initialize a newly created aggregate. - /// The operational context controlling how the aggregate is retrieved. - /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - public static async Task GetOrCreateAsync( - [NotNull] this IEventStore eventStore, - string? aggregateId, - [NotNull] Func creator, - EventStoreOperationContext? context, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = await eventStore.GetOrCreateAsync(aggregateId, context, cancellationToken); - if (aggregate?.IsNew() == true) - await creator(aggregate, cancellationToken); - - return aggregate; - } - - /// - /// Gets the aggregate for the id, creating and initializing it with the when it - /// does not yet exist. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get, or use as the id of the aggregate to create. - /// The callback used to initialize a newly created aggregate. - /// The operational context controlling how the aggregate is retrieved. - /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - public static async Task GetOrCreateAsync( - [NotNull] this IEventStore eventStore, - string? aggregateId, - [NotNull] Action creator, - EventStoreOperationContext? context, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = await eventStore.GetOrCreateAsync(aggregateId, context, cancellationToken); - if (aggregate?.IsNew() == true) - creator(aggregate); - - return aggregate; - } - - #endregion id: string, with context. - - #region id: string, without context. - - /// - /// Gets the aggregate for the id, creating it when it does not yet exist using the default context. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get, or use as the id of the aggregate to create. - /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - public static Task GetOrCreateAsync( - [NotNull] this IEventStore eventStore, - string? aggregateId, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() => eventStore.GetOrCreateAsync(aggregateId, null, cancellationToken); - - /// - /// Gets the aggregate for the id, creating and initializing it with the when it - /// does not yet exist using the default context. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get, or use as the id of the aggregate to create. - /// The asynchronous callback used to initialize a newly created aggregate. - /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - public static async Task GetOrCreateAsync( - [NotNull] this IEventStore eventStore, - string? aggregateId, - [NotNull] Func creator, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = await eventStore.GetOrCreateAsync(aggregateId, null, cancellationToken); - if (aggregate?.IsNew() == true) - await creator(aggregate, cancellationToken); - - return aggregate; - } - - /// - /// Gets the aggregate for the id, creating and initializing it with the when it - /// does not yet exist using the default context. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get, or use as the id of the aggregate to create. - /// The callback used to initialize a newly created aggregate. - /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - public static async Task GetOrCreateAsync( - [NotNull] this IEventStore eventStore, - string? aggregateId, - [NotNull] Action creator, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = await eventStore.GetOrCreateAsync(aggregateId, null, cancellationToken); - if (aggregate?.IsNew() == true) - creator(aggregate); - - return aggregate; - } - - #endregion id: string, without context. - - #region id: object, with context. - - /// - /// Gets the aggregate for the string representation of the id, creating it when it does not yet exist. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get, or use as the id of the aggregate to create. - /// The operational context controlling how the aggregate is retrieved. - /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - public static Task GetOrCreateAsync( - [NotNull] this IEventStore eventStore, - object? aggregateId, - EventStoreOperationContext? operationContext, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() => - eventStore.GetOrCreateAsync(aggregateId?.ToString(), operationContext, cancellationToken); - - /// - /// Gets the aggregate for the string representation of the id, creating and initializing it with the - /// when it does not yet exist. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get, or use as the id of the aggregate to create. - /// The asynchronous callback used to initialize a newly created aggregate. - /// The operational context controlling how the aggregate is retrieved. - /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - public static async Task GetOrCreateAsync( - [NotNull] this IEventStore eventStore, - object? aggregateId, - [NotNull] Func creator, - EventStoreOperationContext? context, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = await eventStore.GetOrCreateAsync(aggregateId?.ToString(), context, cancellationToken); - if (aggregate?.IsNew() == true) - await creator(aggregate, cancellationToken); - - return aggregate; - } - - /// - /// Gets the aggregate for the string representation of the id, creating and initializing it with the - /// when it does not yet exist. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get, or use as the id of the aggregate to create. - /// The callback used to initialize a newly created aggregate. - /// The operational context controlling how the aggregate is retrieved. - /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - public static async Task GetOrCreateAsync( - [NotNull] this IEventStore eventStore, - object? aggregateId, - [NotNull] Action creator, - EventStoreOperationContext? context, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = await eventStore.GetOrCreateAsync(aggregateId?.ToString(), context, cancellationToken); - if (aggregate?.IsNew() == true) - creator(aggregate); - - return aggregate; - } - - #endregion id: object, with context. - - #region id: object, no context. - - /// - /// Gets the aggregate for the string representation of the id, creating it when it does not yet exist - /// using the default context. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get, or use as the id of the aggregate to create. - /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - public static Task GetOrCreateAsync( - [NotNull] this IEventStore eventStore, - object? aggregateId, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() => - eventStore.GetOrCreateAsync(aggregateId?.ToString(), null, cancellationToken); - - /// - /// Gets the aggregate for the string representation of the id, creating and initializing it with the - /// when it does not yet exist using the default context. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get, or use as the id of the aggregate to create. - /// The asynchronous callback used to initialize a newly created aggregate. - /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - public static async Task GetOrCreateAsync( - [NotNull] this IEventStore eventStore, - object? aggregateId, - [NotNull] Func creator, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = await eventStore.GetOrCreateAsync(aggregateId?.ToString(), null, cancellationToken); - if (aggregate?.IsNew() == true) - await creator(aggregate, cancellationToken); - - return aggregate; - } - - /// - /// Gets the aggregate for the string representation of the id, creating and initializing it with the - /// when it does not yet exist using the default context. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get, or use as the id of the aggregate to create. - /// The callback used to initialize a newly created aggregate. - /// A token that can be used to cancel the operation. - /// The existing or newly created aggregate, or null. - public static async Task GetOrCreateAsync( - [NotNull] this IEventStore eventStore, - object? id, - [NotNull] Action creator, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = await eventStore.GetOrCreateAsync(id?.ToString(), null, cancellationToken); - if (aggregate?.IsNew() == true) - creator(aggregate); - - return aggregate; - } - - #endregion id: object, no context. - - #endregion GetOrCreateAsync - - #region CreateAsync - - /// - /// Creates a new aggregate of and optionally runs the - /// callback against it. - /// - /// The to create. - /// The used as the root object. - /// Optional, the id of the aggregate to create; when null, an id is generated. - /// Optional asynchronous callback used to initialize the new aggregate. - /// A token that can be used to cancel the operation. - /// The newly created aggregate. - public static async Task CreateAsync( - [NotNull] this IEventStore eventStore, - string? aggregateId = null, - Func? creator = null, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = await eventStore.CreateAsync(aggregateId, cancellationToken); - if (creator != null) - await creator(aggregate, cancellationToken); - - return aggregate; - } - - /// - /// Creates a new aggregate of and optionally runs the - /// callback against it. - /// - /// The to create. - /// The used as the root object. - /// Optional, the id of the aggregate to create; when null, an id is generated. - /// Optional callback used to initialize the new aggregate. - /// A token that can be used to cancel the operation. - /// The newly created aggregate. - public static async Task CreateAsync( - [NotNull] this IEventStore eventStore, - string? aggregateId = null, - Action? creator = null, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = await eventStore.CreateAsync(aggregateId, cancellationToken); - creator?.Invoke(aggregate); - - return aggregate; - } - - /// - /// Creates a new aggregate of using the string representation of the id. - /// - /// The to create. - /// The used as the root object. - /// Optional, the id of the aggregate to create; when null, an id is generated. - /// A token that can be used to cancel the operation. - /// The newly created aggregate. - public static Task CreateAsync( - [NotNull] this IEventStore eventStore, - object? aggregateId = null, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() => eventStore.CreateAsync(aggregateId?.ToString(), cancellationToken); - - /// - /// Creates a new aggregate of using the string representation of the id and - /// optionally runs the callback against it. - /// - /// The to create. - /// The used as the root object. - /// Optional, the id of the aggregate to create; when null, an id is generated. - /// Optional asynchronous callback used to initialize the new aggregate. - /// A token that can be used to cancel the operation. - /// The newly created aggregate. - public static async Task CreateAsync( - [NotNull] this IEventStore eventStore, - object? aggregateId = null, - Func? creator = null, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = await eventStore.CreateAsync(aggregateId?.ToString(), cancellationToken); - if (creator != null) - await creator(aggregate, cancellationToken); - - return aggregate; - } - - /// - /// Creates a new aggregate of using the string representation of the id and - /// optionally runs the callback against it. - /// - /// The to create. - /// The used as the root object. - /// Optional, the id of the aggregate to create; when null, an id is generated. - /// Optional callback used to initialize the new aggregate. - /// A token that can be used to cancel the operation. - /// The newly created aggregate. - public static async Task CreateAsync( - [NotNull] this IEventStore eventStore, - object? aggregateId = null, - Action? creator = null, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var aggregate = await eventStore.CreateAsync(aggregateId?.ToString(), cancellationToken); - creator?.Invoke(aggregate); - - return aggregate; - } - - #endregion CreateAsync - - #region GetAsync - - /// - /// Gets the aggregate for the id using the default operation context. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get. - /// A token that can be used to cancel the operation. - /// The requested aggregate, or null when it does not exist. - public static Task GetAsync( - [NotNull] this IEventStore eventStore, - string aggregateId, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() => eventStore.GetAsync(aggregateId, null, cancellationToken); - - /// - /// Gets the aggregate for the string representation of the id using the default operation context. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get. - /// A token that can be used to cancel the operation. - /// The requested aggregate, or null when it does not exist. - /// Thrown when has no string representation. - public static Task GetAsync( - [NotNull] this IEventStore eventStore, - object aggregateId, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var idAsString = aggregateId?.ToString(); - ArgumentException.ThrowIfNullOrWhiteSpace(idAsString, nameof(aggregateId)); - - return eventStore.GetAsync(idAsString, null, cancellationToken); - } - - /// - /// Gets the aggregate for the string representation of the id using the supplied operation context. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get. - /// The operational context controlling how the aggregate is retrieved. - /// A token that can be used to cancel the operation. - /// The requested aggregate, or null when it does not exist. - /// Thrown when has no string representation. - public static Task GetAsync( - [NotNull] this IEventStore eventStore, - object aggregateId, - EventStoreOperationContext? context, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var idAsString = aggregateId?.ToString(); - ArgumentException.ThrowIfNullOrWhiteSpace(idAsString, nameof(aggregateId)); - - return eventStore.GetAsync(idAsString, context, cancellationToken); - } - - #endregion GetAsync - - #region GetAtAsync - - /// - /// Gets the aggregate up to a specific version using the default operation context. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get. - /// The version of the aggregate to get. - /// A token that can be used to cancel the operation. - /// The requested aggregate, or null when it does not exist. - public static Task GetAtAsync( - [NotNull] this IEventStore eventStore, - string aggregateId, - int version, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() => eventStore.GetAtAsync(aggregateId, version, null, cancellationToken); - - /// - /// Gets the aggregate up to a specific version using the string representation of the id. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get. - /// The version of the aggregate to get. - /// A token that can be used to cancel the operation. - /// The requested aggregate, or null when it does not exist. - public static Task GetAtAsync( - [NotNull] this IEventStore eventStore, - object aggregateId, - int version, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() => eventStore.GetAtAsync(aggregateId, version, null, cancellationToken); - - /// - /// Gets the aggregate up to a specific version using the string representation of the id and the supplied - /// operation context. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to get. - /// The version of the aggregate to get. - /// The operational context controlling how the aggregate is retrieved. - /// A token that can be used to cancel the operation. - /// The requested aggregate, or null when it does not exist. - /// Thrown when has no string representation. - public static Task GetAtAsync( - [NotNull] this IEventStore eventStore, - object aggregateId, - int version, - EventStoreOperationContext? context, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var idAsString = aggregateId?.ToString(); - ArgumentException.ThrowIfNullOrWhiteSpace(idAsString, nameof(aggregateId)); - - return eventStore.GetAtAsync(idAsString, version, context, cancellationToken); - } - - #endregion GetAtAsync - - #region IsDeletedAsync - - /// - /// Determines if the aggregate with the string representation of the id exists in the deleted state. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to check. - /// A token that can be used to cancel the operation. - /// True when the aggregate exists in the deleted state, otherwise false. - /// Thrown when has no string representation. - public static Task IsDeletedAsync( - [NotNull] this IEventStore eventStore, - object aggregateId, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var idAsString = aggregateId?.ToString(); - ArgumentException.ThrowIfNullOrWhiteSpace(idAsString, nameof(aggregateId)); - - return eventStore.IsDeletedAsync(idAsString, cancellationToken); - } - - #endregion IsDeletedAsync - - #region GetDeletedAsync - - /// - /// Gets a deleted aggregate using the string representation of the id. - /// - /// The type. - /// The used as the root object. - /// The id of the deleted aggregate to get. - /// A token that can be used to cancel the operation. - /// The deleted aggregate, or null when it is not found. - /// Thrown when has no string representation. - public static Task GetDeletedAsync( - [NotNull] this IEventStore eventStore, - object aggregateId, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var idAsString = aggregateId?.ToString(); - ArgumentException.ThrowIfNullOrWhiteSpace(idAsString, nameof(aggregateId)); - - return eventStore.GetDeletedAsync(idAsString, cancellationToken); - } - - #endregion GetDeletedAsync - - #region ExistsAsync - - /// - /// Determines if the aggregate with the string representation of the id exists, including deleted states. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to check. - /// A token that can be used to cancel the operation. - /// An describing the existence of the aggregate. - /// Thrown when has no string representation. - public static Task ExistsAsync( - [NotNull] this IEventStore eventStore, - object aggregateId, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var idAsString = aggregateId?.ToString(); - ArgumentException.ThrowIfNullOrWhiteSpace(idAsString, nameof(aggregateId)); - - return eventStore.ExistsAsync(idAsString, cancellationToken); - } - - /// - /// Determines if the aggregate with the string representation of the id exists, returning - /// for null or blank ids instead of throwing. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to check. - /// A token that can be used to cancel the operation. - /// An describing the existence of the aggregate. - public static Task ExistsWithNullCheckAsync( - [NotNull] this IEventStore eventStore, - object aggregateId, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - var idAsString = aggregateId?.ToString(); - ArgumentException.ThrowIfNullOrWhiteSpace(idAsString, nameof(aggregateId)); - - return eventStore.ExistsWithNullCheckAsync(idAsString, cancellationToken); - } - - /// - /// Determines if the aggregate exists, returning for null or blank - /// ids instead of throwing. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to check. - /// A token that can be used to cancel the operation. - /// An describing the existence of the aggregate. - public static Task ExistsWithNullCheckAsync( - [NotNull] this IEventStore eventStore, - string aggregateId, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - return string.IsNullOrWhiteSpace(aggregateId) - ? Task.FromResult(ExistsState.DoesNotExist) - : eventStore.ExistsAsync(aggregateId, cancellationToken); - } - - #endregion ExistsAsync - - #region Enlist - /// /// Creates a new with no enlisted aggregates. /// @@ -833,167 +68,21 @@ public static IEventStoreTransaction Enlist( return new EventStoreTransaction(operationContext?.CorrelationId); } - /// - /// Creates a new and enlists all - /// against this event store, using an auto-generated correlation ID. - /// - /// The responsible for persisting each aggregate. - /// The aggregates to include in the transaction. - /// A new ready to be committed. - /// Call to persist all enlisted aggregates. - public static IEventStoreTransaction Enlist([NotNull] this IEventStore eventStore, params T[] aggregates) - where T : class, IAggregate, new() => eventStore.Enlist(correlationId: null, aggregates); - - /// - /// Creates a new with the given - /// and enlists all against this event store. - /// - /// The responsible for persisting each aggregate. - /// - /// Optional correlation ID to bind all events together. When , a new GUID is generated. - /// - /// The aggregates to include in the transaction. - /// A new ready to be committed. - public static IEventStoreTransaction Enlist( - [NotNull] this IEventStore eventStore, - string? correlationId, - params T[] aggregates - ) - where T : class, IAggregate, new() - { - ArgumentNullException.ThrowIfNull(eventStore); - ArgumentNullException.ThrowIfNull(aggregates); - - EventStoreTransaction transaction = new(correlationId); - foreach (var aggregate in aggregates) - transaction.Enlist(aggregate, eventStore); - - return transaction; - } - - /// - /// Creates a new and enlists all - /// against this event store, applying a shared to each. - /// - /// The responsible for persisting each aggregate. - /// - /// Optional applied to every aggregate save. - /// When , the default context is used. - /// - /// The aggregates to include in the transaction. - /// A new ready to be committed. - public static IEventStoreTransaction Enlist( - [NotNull] this IEventStore eventStore, - EventStoreOperationContext? operationContext, - params T[] aggregates + // A read that fails on the way to a delete is still a delete failure, so the read case is widened + // rather than reported as "not found" for every reason the read did not produce an aggregate. + static Result, AggregateDeleteFailure> ToDeleteFailure( + AggregateReadFailure failure, + string aggregateId ) - where T : class, IAggregate, new() - { - ArgumentNullException.ThrowIfNull(eventStore); - ArgumentNullException.ThrowIfNull(aggregates); - - EventStoreTransaction transaction = new(operationContext?.CorrelationId); - foreach (var aggregate in aggregates) - transaction.Enlist(aggregate, eventStore, operationContext); - - return transaction; - } - - #endregion Enlist - - #region SaveAsync - - /// - /// Saves the aggregate using the default operation context. - /// - /// The type. - /// The used as the root object. - /// The aggregate to save. - /// A token that can be used to cancel the operation. - /// A describing the result of the save. - public static Task> SaveAsync( - [NotNull] this IEventStore eventStore, - T aggregate, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() => eventStore.SaveAsync(aggregate, null, cancellationToken); - - #endregion SaveAsync - - #region DeleteAsync - - /// - /// Deletes the aggregate using the default operation context. - /// - /// The type. - /// The used as the root object. - /// The aggregate to delete. - /// A token that can be used to cancel the operation. - /// True when the aggregate was successfully deleted, otherwise false. - public static Task DeleteAsync( - [NotNull] this IEventStore eventStore, - T aggregate, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() => eventStore.DeleteAsync(aggregate, null, cancellationToken); - - /// - /// Deletes the aggregate with the given id using the default operation context. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to delete. - /// A token that can be used to cancel the operation. - /// True when the aggregate was successfully deleted, otherwise false. - public static Task DeleteAsync( - [NotNull] this IEventStore eventStore, - string aggregateId, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() => eventStore.DeleteAsync(aggregateId, null, cancellationToken); - - /// - /// Deletes the aggregate with the given id using the supplied operation context. - /// - /// The type. - /// The used as the root object. - /// The id of the aggregate to delete. - /// The operational context controlling how the aggregate is deleted. - /// A token that can be used to cancel the operation. - /// True when the aggregate was successfully deleted, otherwise false. - /// Thrown when is null or whitespace. - public static async Task DeleteAsync( - [NotNull] this IEventStore eventStore, - string aggregateId, - EventStoreOperationContext? operationContext, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() - { - ArgumentException.ThrowIfNullOrWhiteSpace(aggregateId, nameof(aggregateId)); - - var aggregate = await eventStore.GetAsync(aggregateId, operationContext, cancellationToken); - return aggregate != null && await eventStore.DeleteAsync(aggregate, operationContext, cancellationToken); - } - - #endregion DeleteAsync - - #region RestoreAsync - - /// - /// Restores a previously deleted aggregate using the default operation context. - /// - /// The type. - /// The used as the root object. - /// The aggregate to restore. - /// A token that can be used to cancel the operation. - /// True when the aggregate was successfully restored, otherwise false. - public static Task RestoreAsync( - [NotNull] this IEventStore eventStore, - T aggregate, - CancellationToken cancellationToken = default - ) - where T : class, IAggregate, new() => eventStore.RestoreAsync(aggregate, null, cancellationToken); - - #endregion RestoreAsync + where T : class, IAggregate, new() => + failure switch + { + AggregateDeleted deleted => AggregateDeleteFailure.Failure>( + new AggregateAlreadyDeleted(deleted.AggregateType, deleted.AggregateId) + ), + AggregateLocked locked => AggregateDeleteFailure.Failure>(locked), + AggregateNotFound notFound => AggregateDeleteFailure.Failure>(notFound), + // GetAsync never reports AggregateNotDeleted; it belongs to GetDeletedAsync. + _ => AggregateDeleteFailure.Failure>(new AggregateNotFound(typeof(T).Name, aggregateId)), + }; } diff --git a/src/src/EventSourcing/IEventStoreMetrics.cs b/src/src/EventSourcing/IEventStoreMetrics.cs new file mode 100644 index 00000000..9b6999d4 --- /dev/null +++ b/src/src/EventSourcing/IEventStoreMetrics.cs @@ -0,0 +1,49 @@ +using Purview.Telemetry; + +namespace Purview.EventSourcing; + +/// +/// Provider-neutral event-store metrics. +/// +/// +/// An implementation is generated by the Purview telemetry source generator. Every storage provider +/// records the same instruments with the same tags, so a dashboard built against one provider keeps +/// working against another. Instrument and tag names are a public contract: changing one breaks the +/// queries and alerts built on it. +/// +// InstrumentPrefix is set explicitly: the generator otherwise derives it from the interface name, +// publishing "event_store_metrics.save.duration". +[Meter("Purview.EventSourcing", InstrumentPrefix = "purview.eventsourcing")] +public interface IEventStoreMetrics +{ + /// + /// Records how long a save took, and how it ended. + /// + /// The elapsed time, in milliseconds. + /// The aggregate type name. + /// + /// written, no-changes, already-applied, or the failure case name. + /// + [Histogram("save.duration")] + void SaveDuration( + [InstrumentMeasurement] double milliseconds, + [Tag("aggregate.type")] string aggregateType, + [Tag("outcome")] string outcome + ); + + /// + /// Records how long reconstituting an aggregate took. + /// + /// The elapsed time, in milliseconds. + /// The aggregate type name. + [Histogram("get.duration")] + void GetDuration([InstrumentMeasurement] double milliseconds, [Tag("aggregate.type")] string aggregateType); + + /// + /// Counts events appended to a stream by a successful save. + /// + /// The number of events appended. + /// The aggregate type name. + [Counter("events.appended")] + void EventsAppended([InstrumentMeasurement] int count, [Tag("aggregate.type")] string aggregateType); +} diff --git a/src/src/EventSourcing/IEventStorePrincipalAccessor.cs b/src/src/EventSourcing/IEventStorePrincipalAccessor.cs new file mode 100644 index 00000000..df6ec5be --- /dev/null +++ b/src/src/EventSourcing/IEventStorePrincipalAccessor.cs @@ -0,0 +1,23 @@ +using System.Security.Claims; + +namespace Purview.EventSourcing; + +/// +/// Supplies the a save records as the originating user in +/// . +/// +/// +/// Resolve this from dependency injection rather than reading an ambient principal: ASP.NET Core does not +/// populate , so is +/// in a web host unless the application sets +/// itself. Register an implementation backed by the +/// host's own notion of the current user - IHttpContextAccessor in a web application - to record a +/// user against saved events. +/// +public interface IEventStorePrincipalAccessor +{ + /// + /// Gets the principal for the operation in progress, or when there is none. + /// + ClaimsPrincipal? GetPrincipal(); +} diff --git a/src/src/EventSourcing/Internal/TransactionalSaveOperation.cs b/src/src/EventSourcing/Internal/TransactionalSaveOperation.cs index 48cc20f7..61e9ee86 100644 --- a/src/src/EventSourcing/Internal/TransactionalSaveOperation.cs +++ b/src/src/EventSourcing/Internal/TransactionalSaveOperation.cs @@ -1,5 +1,7 @@ using System.ComponentModel; using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.Internal; @@ -14,7 +16,7 @@ namespace Purview.EventSourcing.Internal; /// [EditorBrowsable(EditorBrowsableState.Never)] public sealed class TransactionalSaveOperation( - SaveResult result, + Result, AggregateSaveFailure> result, Func? afterCommit = null, Func? afterRollback = null ) @@ -25,7 +27,19 @@ public sealed class TransactionalSaveOperation( /// /// Gets the result of the save operation. /// - public SaveResult Result { get; } = result; + public Result, AggregateSaveFailure> Result { get; } = result; + + /// + /// Gets a value indicating whether the save produced a write, or matched an idempotency marker for + /// one an earlier attempt had already made. + /// + public bool Saved => Result.IsSuccess && Result.Value.Kind is not SaveOutcomeKind.NoChanges; + + /// + /// Gets a value indicating whether the save appended nothing, either because there was nothing to + /// append or because the events were already applied. + /// + public bool Skipped => Result.IsSuccess && Result.Value.Kind is not SaveOutcomeKind.Written; readonly Func _afterCommit = afterCommit ?? NoOp; readonly Func _afterRollback = afterRollback ?? NoOp; diff --git a/src/src/EventSourcing/LockHandlingMode.cs b/src/src/EventSourcing/LockHandlingMode.cs deleted file mode 100644 index f02dde35..00000000 --- a/src/src/EventSourcing/LockHandlingMode.cs +++ /dev/null @@ -1,17 +0,0 @@ -namespace Purview.EventSourcing; - -/// -/// Controls how to handle aggregates in a locked state with save operations. -/// -public enum LockHandlingMode -{ - /// - /// If the aggregate is marked as locked, save operations throw an exception. This is the default. - /// - ThrowsException, - - /// - /// If the aggregate is marked as locked, save operations return false. - /// - ReturnsFalse = 1, -} diff --git a/src/src/EventSourcing/NoOpEventStoreMetrics.cs b/src/src/EventSourcing/NoOpEventStoreMetrics.cs new file mode 100644 index 00000000..dc35c83b --- /dev/null +++ b/src/src/EventSourcing/NoOpEventStoreMetrics.cs @@ -0,0 +1,28 @@ +namespace Purview.EventSourcing; + +/// +/// An that records nothing. +/// +/// +/// Used when a store is constructed directly rather than resolved from dependency injection, where there +/// is no to build instruments from. Recording +/// metrics is never a precondition for persisting events. +/// +public sealed class NoOpEventStoreMetrics : IEventStoreMetrics +{ + /// + /// The shared instance. + /// + public static readonly NoOpEventStoreMetrics Instance = new(); + + NoOpEventStoreMetrics() { } + + /// + public void SaveDuration(double milliseconds, string aggregateType, string outcome) { } + + /// + public void GetDuration(double milliseconds, string aggregateType) { } + + /// + public void EventsAppended(int count, string aggregateType) { } +} diff --git a/src/src/EventSourcing/QueryableEventStoreFacade.cs b/src/src/EventSourcing/QueryableEventStoreFacade.cs index 5951eb7a..c8aa610c 100644 --- a/src/src/EventSourcing/QueryableEventStoreFacade.cs +++ b/src/src/EventSourcing/QueryableEventStoreFacade.cs @@ -3,7 +3,9 @@ using System.Linq.Expressions; using Microsoft.Extensions.DependencyInjection; using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.Internal; +using Purview.Results; namespace Purview.EventSourcing; @@ -35,7 +37,7 @@ public Task CreateAsync(string? aggregateId = null, CancellationToken canc where T : class, IAggregate, new() => GetQueryableEventStore().CreateAsync(aggregateId, cancellationToken); /// - public Task GetOrCreateAsync( + public Task> GetOrCreateAsync( string? aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -44,7 +46,7 @@ public Task CreateAsync(string? aggregateId = null, CancellationToken canc GetQueryableEventStore().GetOrCreateAsync(aggregateId, operationContext, cancellationToken); /// - public Task GetAsync( + public Task> GetAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -53,9 +55,9 @@ public Task CreateAsync(string? aggregateId = null, CancellationToken canc GetQueryableEventStore().GetAsync(aggregateId, operationContext, cancellationToken); /// - public Task GetAtAsync( + public Task> GetAtAsync( string aggregateId, - int version, + long version, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) @@ -63,7 +65,7 @@ public Task CreateAsync(string? aggregateId = null, CancellationToken canc GetQueryableEventStore().GetAtAsync(aggregateId, version, operationContext, cancellationToken); /// - public Task> SaveAsync( + public Task, AggregateSaveFailure>> SaveAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -72,17 +74,15 @@ public Task> SaveAsync( GetQueryableEventStore().SaveAsync(aggregate, operationContext, cancellationToken); /// - public Task IsDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) - where T : class, IAggregate, new() => - GetQueryableEventStore().IsDeletedAsync(aggregateId, cancellationToken); - - /// - public Task GetDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) + public Task> GetDeletedAsync( + string aggregateId, + CancellationToken cancellationToken = default + ) where T : class, IAggregate, new() => GetQueryableEventStore().GetDeletedAsync(aggregateId, cancellationToken); /// - public Task DeleteAsync( + public Task, AggregateDeleteFailure>> DeleteAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -91,7 +91,7 @@ public Task DeleteAsync( GetQueryableEventStore().DeleteAsync(aggregate, operationContext, cancellationToken); /// - public Task RestoreAsync( + public Task, AggregateRestoreFailure>> RestoreAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -108,7 +108,7 @@ public IAsyncEnumerable GetAggregateIdsAsync( GetQueryableEventStore().GetAggregateIdsAsync(includeDeleted, cancellationToken); /// - public Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) + public Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) where T : class, IAggregate, new() => GetQueryableEventStore().ExistsAsync(aggregateId, cancellationToken); /// @@ -118,8 +118,8 @@ public T FulfilRequirements(T aggregate) /// public IAsyncEnumerable<(EventRecord EventRecord, string EventType)> GetEventRangeAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, CancellationToken cancellationToken ) where T : class, IAggregate, new() => diff --git a/src/src/EventSourcing/Tenancy/AmbientCurrentTenant.cs b/src/src/EventSourcing/Tenancy/AmbientCurrentTenant.cs new file mode 100644 index 00000000..9a44bc26 --- /dev/null +++ b/src/src/EventSourcing/Tenancy/AmbientCurrentTenant.cs @@ -0,0 +1,37 @@ +namespace Purview.EventSourcing.Tenancy; + +/// +/// An backed by an ambient scope that flows across . +/// +/// +/// The default scope is , which applies no tenant filter. That keeps a +/// single-tenant deployment working without configuration; a multi-tenant host registers its own +/// resolving the caller's tenant, and uses only +/// where it deliberately changes tenant - a super user selecting one, or infrastructure work running as +/// . +/// +public sealed class AmbientCurrentTenant : ICurrentTenant +{ + static readonly AsyncLocal Ambient = new(); + + /// + public TenantScope Current => Ambient.Value ?? TenantScope.System; + + /// + /// Sets the ambient scope until the returned value is disposed. + /// + /// The scope to apply. + /// A value that restores the previous scope when disposed. + public static IDisposable BeginScope(TenantScope scope) + { + var previous = Ambient.Value; + Ambient.Value = scope; + + return new Restore(previous); + } + + sealed class Restore(TenantScope? previous) : IDisposable + { + public void Dispose() => Ambient.Value = previous; + } +} diff --git a/src/src/EventSourcing/Tenancy/ICurrentTenant.cs b/src/src/EventSourcing/Tenancy/ICurrentTenant.cs new file mode 100644 index 00000000..22ee48ac --- /dev/null +++ b/src/src/EventSourcing/Tenancy/ICurrentTenant.cs @@ -0,0 +1,17 @@ +namespace Purview.EventSourcing.Tenancy; + +/// +/// Supplies the the current operation runs under. +/// +/// +/// Resolved per operation, so a request-scoped implementation can return the caller's tenant while +/// background work runs as . The event store applies the scope as a +/// filter on reads and stamps it on writes. +/// +public interface ICurrentTenant +{ + /// + /// Gets the scope for the operation in progress. + /// + TenantScope Current { get; } +} diff --git a/src/src/EventSourcing/Tenancy/SystemCurrentTenant.cs b/src/src/EventSourcing/Tenancy/SystemCurrentTenant.cs new file mode 100644 index 00000000..12dff469 --- /dev/null +++ b/src/src/EventSourcing/Tenancy/SystemCurrentTenant.cs @@ -0,0 +1,16 @@ +namespace Purview.EventSourcing.Tenancy; + +/// +/// An that always reports . +/// +/// +/// The infrastructure scope: it applies no tenant filter, so it reads and writes across every tenant. +/// Use it for a single-tenant deployment, and for background work that legitimately spans tenants. +/// Do not register it as the resolver in a multi-tenant host serving user requests - every request would +/// then see every tenant's data. +/// +public sealed class SystemCurrentTenant : ICurrentTenant +{ + /// + public TenantScope Current => TenantScope.System; +} diff --git a/src/src/EventSourcing/Tenancy/TenantScope.cs b/src/src/EventSourcing/Tenancy/TenantScope.cs new file mode 100644 index 00000000..3ea210e7 --- /dev/null +++ b/src/src/EventSourcing/Tenancy/TenantScope.cs @@ -0,0 +1,46 @@ +namespace Purview.EventSourcing.Tenancy; + +/// +/// The tenant an operation runs under. +/// +/// +/// Either a single tenant, or for infrastructure work that deliberately crosses +/// tenants. The distinction is explicit rather than a tenant id, so a resolver +/// that fails to determine a tenant cannot be mistaken for permission to read every tenant. +/// +public readonly record struct TenantScope +{ + TenantScope(string? tenantId, bool isSystem) + { + TenantId = tenantId; + IsSystem = isSystem; + } + + /// + /// Crosses every tenant. Use for infrastructure operations - projection rebuilds, migrations, + /// outbox dispatch - and for a single-tenant deployment, where no tenant filter applies. + /// + public static TenantScope System { get; } = new(null, isSystem: true); + + /// + /// The tenant identifier, or when this is . + /// + public string? TenantId { get; } + + /// + /// when the scope crosses every tenant. + /// + public bool IsSystem { get; } + + /// + /// Creates a scope limited to a single tenant. + /// + /// The tenant identifier. + /// Thrown when is blank. + public static TenantScope For(string tenantId) + { + ArgumentException.ThrowIfNullOrWhiteSpace(tenantId); + + return new(tenantId, isSystem: false); + } +} diff --git a/src/src/EventSourcing/Tenancy/TenantScopeNotSupportedException.cs b/src/src/EventSourcing/Tenancy/TenantScopeNotSupportedException.cs new file mode 100644 index 00000000..3e769c9a --- /dev/null +++ b/src/src/EventSourcing/Tenancy/TenantScopeNotSupportedException.cs @@ -0,0 +1,59 @@ +namespace Purview.EventSourcing.Tenancy; + +/// +/// Thrown when an operation runs under a tenant scope that the storage provider cannot enforce. +/// +/// +/// A configuration fault, not an outcome a caller can act on, so it throws rather than returning a +/// failure case. Only the SQL Server and PostgreSQL providers isolate tenants; the others would ignore +/// the scope, and silently serving one tenant's request from every tenant's data is the failure this +/// prevents. +/// +public sealed class TenantScopeNotSupportedException : InvalidOperationException +{ + /// + /// Constructs the exception for a provider and tenant. + /// + /// The storage provider that cannot enforce the scope. + /// The tenant the operation was scoped to. + public TenantScopeNotSupportedException(string providerName, string? tenantId) + : base( + $"The '{providerName}' provider does not enforce tenant isolation, so it cannot serve an operation scoped to tenant '{tenantId}'. " + + "Use the SQL Server or PostgreSQL provider for multi-tenant storage, or run this operation under TenantScope.System." + ) + { + ProviderName = providerName; + TenantId = tenantId; + } + + /// Constructs the exception. + public TenantScopeNotSupportedException() { } + + /// Constructs the exception with a message. + /// The message. + public TenantScopeNotSupportedException(string message) + : base(message) { } + + /// Constructs the exception with a message and inner exception. + /// The message. + /// The inner exception. + public TenantScopeNotSupportedException(string message, Exception innerException) + : base(message, innerException) { } + + /// The storage provider that cannot enforce the scope. + public string? ProviderName { get; } + + /// The tenant the operation was scoped to. + public string? TenantId { get; } + + /// + /// Throws when names a tenant. + /// + /// The scope the operation is running under. + /// The storage provider. + public static void ThrowIfScoped(TenantScope scope, string providerName) + { + if (!scope.IsSystem) + throw new TenantScopeNotSupportedException(providerName, scope.TenantId); + } +} diff --git a/src/src/EventSourcing/TransactionAggregateResult.cs b/src/src/EventSourcing/TransactionAggregateResult.cs index 85647ccb..3a9ed09b 100644 --- a/src/src/EventSourcing/TransactionAggregateResult.cs +++ b/src/src/EventSourcing/TransactionAggregateResult.cs @@ -1,11 +1,18 @@ using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Failures; namespace Purview.EventSourcing; /// /// Represents the outcome of saving a single aggregate within a transaction. /// -public sealed class TransactionAggregateResult(IAggregate aggregate, bool saved, bool skipped, Exception? error) +public sealed class TransactionAggregateResult( + IAggregate aggregate, + bool saved, + bool skipped, + Exception? error, + AggregateSaveFailure? failure = null +) { /// The aggregate that was processed. public IAggregate Aggregate { get; } = aggregate; @@ -18,4 +25,13 @@ public sealed class TransactionAggregateResult(IAggregate aggregate, bool saved, /// The exception that caused the save to fail, if any. public Exception? Error { get; } = error; + + /// + /// The save failure returned by the event store, if the save failed for a reason the caller can act on. + /// + /// + /// Expected failures - a lost concurrency check, a locked or deleted aggregate, a rejected validation - + /// are returned by the store rather than thrown, so they arrive here and not in . + /// + public AggregateSaveFailure? Failure { get; } = failure; } diff --git a/src/src/EventSourcing/Validation/ValidationException.cs b/src/src/EventSourcing/Validation/ValidationException.cs deleted file mode 100644 index bca055f6..00000000 --- a/src/src/EventSourcing/Validation/ValidationException.cs +++ /dev/null @@ -1,57 +0,0 @@ -namespace Purview.EventSourcing.Validation; - -/// -/// Thrown when aggregate validation fails (e.g. via ). -/// -public sealed class ValidationException : Exception -{ - /// - /// The validation failures that caused this exception. - /// - public IReadOnlyList Errors { get; } - - /// - /// Constructs a new . - /// - public ValidationException() - : base("Validation failed.") - { - Errors = []; - } - - /// - /// Constructs a new with the given failures. - /// - public ValidationException(IEnumerable errors) - : base("Validation failed: " + string.Join("; ", errors.Select(e => e.ErrorMessage))) - { - Errors = [.. errors]; - } - - /// - /// Constructs a new with the given message and failures. - /// - public ValidationException(string message, IEnumerable errors) - : base(message) - { - Errors = [.. errors]; - } - - /// - /// Constructs a new with the given message. - /// - public ValidationException(string message) - : base(message) - { - Errors = []; - } - - /// - /// Constructs a new with the given message and inner exception. - /// - public ValidationException(string message, Exception innerException) - : base(message, innerException) - { - Errors = []; - } -} diff --git a/src/src/ImplementationShared/Storage/SaveResultBuilder.cs b/src/src/ImplementationShared/Storage/SaveResultBuilder.cs deleted file mode 100644 index 31041c89..00000000 --- a/src/src/ImplementationShared/Storage/SaveResultBuilder.cs +++ /dev/null @@ -1,23 +0,0 @@ -using Purview.EventSourcing.Aggregates; -using Purview.EventSourcing.Validation; - -namespace Purview.EventSourcing.Storage; - -/// -/// Builds instances for event-store save operations, -/// centralizing the construction that was previously duplicated across each storage provider. -/// -public static class SaveResultBuilder -{ - /// - /// Creates a , defaulting the validation result to a - /// successful when one is not supplied. - /// - public static SaveResult Create( - TAggregate aggregate, - bool saved, - bool skipped, - ValidationResult? validationResult = null - ) - where TAggregate : IAggregate => new(aggregate, validationResult ?? new ValidationResult(), saved, skipped); -} diff --git a/src/src/InMemory/Events/Exceptions/ConcurrencyException.cs b/src/src/InMemory/Events/Exceptions/ConcurrencyException.cs deleted file mode 100644 index e8f95a2b..00000000 --- a/src/src/InMemory/Events/Exceptions/ConcurrencyException.cs +++ /dev/null @@ -1,37 +0,0 @@ -namespace Purview.EventSourcing.InMemory.Events.Exceptions; - -/// -/// Thrown when an optimistic-concurrency violation is detected while saving events. -/// -/// The id of the aggregate. -/// The idempotency identifier of the save operation. -/// The aggregate version that was attempted. -/// The version currently present in the store. -#pragma warning disable CA1032 // Implement standard exception constructors -public class ConcurrencyException(string aggregateId, string idempotencyId, int versionAttempted, int version) - : Exception( - $"Optimistic concurrency error:\n\tAggregateId: {aggregateId}\n\tIdempotencyId: {idempotencyId}\n\tVersionAttempted:{versionAttempted}\n\tVersionPresent:{version}" - ), - IConcurrencyConflict -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The id of the aggregate that failed the concurrency check. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// The aggregate version that was attempted. - /// - public int VersionAttempted { get; } = versionAttempted; - - /// - /// The idempotency identifier of the save operation. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); - - /// - /// The version currently present in the store. - /// - public int Version { get; } = version; -} diff --git a/src/src/InMemory/Events/InMemoryEventStore.ExceptionHelpers.cs b/src/src/InMemory/Events/InMemoryEventStore.ExceptionHelpers.cs index 1b342299..fdafd1db 100644 --- a/src/src/InMemory/Events/InMemoryEventStore.ExceptionHelpers.cs +++ b/src/src/InMemory/Events/InMemoryEventStore.ExceptionHelpers.cs @@ -1,18 +1,24 @@ +using Purview.EventSourcing.Exceptions; +using Purview.EventSourcing.Failures; +using Purview.Results; + namespace Purview.EventSourcing.InMemory.Events; [System.Diagnostics.CodeAnalysis.SuppressMessage("Style", "IDE0060:Remove unused parameter")] partial class InMemoryEventStore { + static readonly string AggregateTypeName = new T().AggregateType; + static ArgumentNullException NullAggregate(T? aggregate) => new(nameof(aggregate)); - static Exception AggregateIsDeletedException(string aggregateId) => - new($"Aggregate with ID '{aggregateId}' is deleted."); + static MissingAggregateIdException MissingAggregateIdException() => new(string.Empty); - static Exception AggregateNotDeletedException(string aggregateId) => - new($"Aggregate with ID '{aggregateId}' is not deleted."); + Result NotFound(string aggregateId) => + AggregateReadFailure.Failure(new AggregateNotFound(AggregateTypeName, aggregateId)); - static Exception MissingAggregateIdException() => new("Aggregate ID is missing."); + Result Deleted(string aggregateId) => + AggregateReadFailure.Failure(new AggregateDeleted(AggregateTypeName, aggregateId)); - static Exception AggregateLockedException(string aggregateId) => - new($"Aggregate with ID '{aggregateId}' is locked."); + Result NotDeleted(string aggregateId) => + AggregateReadFailure.Failure(new AggregateNotDeleted(AggregateTypeName, aggregateId)); } diff --git a/src/src/InMemory/Events/InMemoryEventStore.cs b/src/src/InMemory/Events/InMemoryEventStore.cs index 73301bb6..b448083e 100644 --- a/src/src/InMemory/Events/InMemoryEventStore.cs +++ b/src/src/InMemory/Events/InMemoryEventStore.cs @@ -1,9 +1,11 @@ using System.Collections.Concurrent; -using System.Security.Claims; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.Services; +using Purview.EventSourcing.Tenancy; using Purview.EventSourcing.Validation; +using Purview.Results; namespace Purview.EventSourcing.InMemory.Events; @@ -16,6 +18,9 @@ namespace Purview.EventSourcing.InMemory.Events; /// The manager used to fulfil aggregate requirements. /// Optional used to validate aggregates before they are saved. /// Optional factory used to generate aggregate ids when none is supplied. +/// Optional accessor supplying the principal recorded against saved events. +/// Optional metrics recorder; defaults to a no-op. +/// Optional tenant scope. This store does not enforce tenant isolation and refuses a tenant-scoped operation. /// /// Aggregates are held in memory and are identified by id in a case-insensitive manner. This store is /// intended for testing and single-process scenarios; data is not shared between instances or persisted @@ -26,15 +31,46 @@ public partial class InMemoryEventStore( ChangeFeed.IAggregateChangeFeedNotifier aggregateChangeNotifier, IAggregateRequirementsManager aggregateRequirementsManager, IAggregateValidator? validator = null, - IAggregateIdFactory? aggregateIdFactory = null + IAggregateIdFactory? aggregateIdFactory = null, + IEventStorePrincipalAccessor? principalAccessor = null, + IEventStoreMetrics? metrics = null, + ICurrentTenant? currentTenant = null ) : IInMemoryEventStore, IDisposable where T : class, IAggregate, new() { readonly ConcurrentDictionary _aggregates = new(StringComparer.OrdinalIgnoreCase); - readonly ConcurrentDictionary> _events = new(); + readonly ConcurrentDictionary> _events = new(); readonly IAggregateValidator? _validator = validator; + readonly IEventStorePrincipalAccessor _principalAccessor = + principalAccessor ?? new AmbientEventStorePrincipalAccessor(); + + readonly IEventStoreMetrics _metrics = metrics ?? NoOpEventStoreMetrics.Instance; + + readonly ICurrentTenant _currentTenant = currentTenant ?? new SystemCurrentTenant(); + + // The tenant that owns each stream. Kept beside the data rather than folded into the key so the + // system scope can still enumerate every tenant, exactly as the SQL providers allow. + readonly ConcurrentDictionary _tenants = new(StringComparer.OrdinalIgnoreCase); + + // Reads fail closed: an unowned stream is visible only to the system scope. Treating it as visible + // to every tenant would turn a missed stamp into silent cross-tenant exposure. + bool IsVisible(string aggregateId) + { + var scope = _currentTenant.Current; + + return scope.IsSystem + || ( + _tenants.TryGetValue(aggregateId, out var owner) + && string.Equals(owner, scope.TenantId, StringComparison.OrdinalIgnoreCase) + ); + } + + // Writes are the one place an unowned stream must be allowed: that is a stream being created, which + // has no owner until this save records one. + bool CanWrite(string aggregateId) => !_tenants.ContainsKey(aggregateId) || IsVisible(aggregateId); + /// /// The aggregates currently held by the store. /// @@ -52,23 +88,8 @@ public Task ClearAsync(CancellationToken cancellationToken = default) return Task.CompletedTask; } - static Task ReturnAggregateAsync(bool isDeleted, string aggregateId, EventStoreOperationContext context) - { - if (isDeleted) - { -#pragma warning disable IDE0010 // Add missing cases - switch (context.DeleteMode) - { - case DeleteHandlingMode.ThrowsException: - throw AggregateIsDeletedException(aggregateId); - case DeleteHandlingMode.ReturnsNull: - return Task.FromResult(false); - } -#pragma warning restore IDE0010 // Add missing cases - } - - return Task.FromResult(true); - } + static bool ReturnAggregate(bool isDeleted, EventStoreOperationContext context) => + !isDeleted || context.DeleteMode == DeleteHandlingMode.ReturnsAggregate; /// public async Task CreateAsync(string? aggregateId = null, CancellationToken cancellationToken = default) @@ -93,7 +114,7 @@ public async Task CreateAsync(string? aggregateId = null, CancellationToken c } /// - public async Task DeleteAsync( + public async Task, AggregateDeleteFailure>> DeleteAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -103,17 +124,25 @@ public async Task DeleteAsync( throw NullAggregate(aggregate); if (aggregate.Details.IsDeleted) - throw AggregateIsDeletedException(aggregate.Id()); + { + return AggregateDeleteFailure.Failure>( + new AggregateAlreadyDeleted(aggregate.AggregateType, aggregate.Id()) + ); + } operationContext ??= EventStoreOperationContext.DefaultContext(); if (aggregate.IsNew()) - return false; + { + return AggregateDeleteFailure.Failure>( + new AggregateNotFound(aggregate.AggregateType, aggregate.Id()) + ); + } if (operationContext.PermanentlyDelete) { RemoveFromCache(aggregate); - return true; + return new SaveOutcome(aggregate, SaveOutcomeKind.Written); } Deleted deleteAggregateEvent = new(); @@ -128,27 +157,43 @@ public async Task DeleteAsync( ); aggregate.ApplyEvent(deleteAggregateEvent, metadata); - await AddToCacheAsync(aggregate, new EventRecord(deleteAggregateEvent, metadata)); + await AddToCacheAsync(aggregate, additionalEvents: new EventRecord(deleteAggregateEvent, metadata)); - return true; + return new SaveOutcome(aggregate, SaveOutcomeKind.Written); } void RemoveFromCache(T aggregate) { _aggregates.TryRemove(aggregate.Id(), out _); + _tenants.TryRemove(aggregate.Id(), out _); if (_events.TryRemove(aggregate.Id(), out var events)) events.Clear(); } - Task AddToCacheAsync(T aggregate, params EventRecord[] additionalEvents) => - AddToCache(aggregate, true, additionalEvents); + Task AddToCacheAsync(T aggregate, string? userId = null, params EventRecord[] additionalEvents) => + AddToCache(aggregate, true, userId, additionalEvents); - Task AddToCache(T aggregate, bool fulfilRequirements, params EventRecord[] additionalEvents) + Task AddToCache( + T aggregate, + bool fulfilRequirements, + string? userId = null, + params EventRecord[] additionalEvents + ) { + // Another tenant writing into an existing stream would silently take ownership of it. + if (!CanWrite(aggregate.Id())) + throw new Exceptions.ConcurrencyException(aggregate.Id(), $"{Guid.NewGuid()}", 0, 0); + var events = _events.GetOrAdd(aggregate.Id(), _ => new()); var unsavedEvents = aggregate.GetUnsavedEvents(); var toPersist = additionalEvents is { Length: > 0 } ? unsavedEvents.Concat(additionalEvents) : unsavedEvents; + // Events carry the metadata they were recorded with, which predates knowing who is saving. + // The persistent providers stamp the user onto the stored row; do the same here so the + // in-memory store reports the same metadata on read-back. + if (userId != null) + toPersist = toPersist.Select(record => record with { Metadata = record.Metadata with { UserId = userId } }); + foreach (var record in toPersist) { // A conflicting version means another write already persisted this aggregate @@ -165,6 +210,7 @@ Task AddToCache(T aggregate, bool fulfilRequirements, params EventRecord[] ad aggregate.ClearUnsavedEvents(); + _tenants[aggregate.Id()] = _currentTenant.Current.TenantId; _aggregates.AddOrUpdate(aggregate.Id(), aggregate, (key, existingAggregate) => aggregate); if (fulfilRequirements) @@ -174,21 +220,21 @@ Task AddToCache(T aggregate, bool fulfilRequirements, params EventRecord[] ad } /// - public async Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) + public async Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) { await Task.CompletedTask; - return _aggregates.TryGetValue(aggregateId, out var aggregate) + return _aggregates.TryGetValue(aggregateId, out var aggregate) && IsVisible(aggregateId) ? aggregate.Details.IsDeleted - ? ExistsState.ExistsInDeletedState with + ? AggregateExistence.ExistsInDeletedState with { Version = aggregate.Details.CurrentVersion, } - : ExistsState.Exists with + : AggregateExistence.Exists with { Version = aggregate.Details.CurrentVersion, } - : ExistsState.DoesNotExist; + : AggregateExistence.DoesNotExist; } /// @@ -205,7 +251,7 @@ public IAsyncEnumerable GetAggregateIdsAsync( CancellationToken cancellationToken = default ) { - var results = _aggregates.Values.AsEnumerable(); + var results = _aggregates.Where(kvp => IsVisible(kvp.Key)).Select(kvp => kvp.Value); if (!includeDeleted) results = results.Where(a => !a.Details.IsDeleted); @@ -213,7 +259,7 @@ public IAsyncEnumerable GetAggregateIdsAsync( } /// - public async Task GetAsync( + public async Task> GetAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -223,10 +269,15 @@ public IAsyncEnumerable GetAggregateIdsAsync( operationContext ??= EventStoreOperationContext.DefaultContext(); + // An existing stream owned by another tenant reports as absent, and must not fall through to the + // create path below: that would replace the owner's aggregate with an empty one. + if (_aggregates.ContainsKey(aggregateId) && !IsVisible(aggregateId)) + return NotFound(aggregateId); + if (_aggregates.TryGetValue(aggregateId, out var aggregate)) { - if (!await ReturnAggregateAsync(aggregate.Details.IsDeleted, aggregateId, operationContext)) - return null; + if (!ReturnAggregate(aggregate.Details.IsDeleted, operationContext)) + return Deleted(aggregateId); // Cache hit: return the aggregate directly. Requirements are fulfilled when the // aggregate is first created/loaded; re-fulfilling here would refresh scoped services @@ -239,16 +290,16 @@ public IAsyncEnumerable GetAggregateIdsAsync( } /// - public async Task GetAtAsync( + public async Task> GetAtAsync( string aggregateId, - int version, + long version, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) { - var exists = await ExistsAsync(aggregateId, cancellationToken); - if (!exists) - return null; + var existence = await ExistsAsync(aggregateId, cancellationToken); + if (!existence.DoesExist) + return NotFound(aggregateId); T aggregate = new() { Details = new() { Id = aggregateId } }; @@ -260,28 +311,33 @@ public IAsyncEnumerable GetAggregateIdsAsync( } /// - public async Task GetDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) + public async Task> GetDeletedAsync( + string aggregateId, + CancellationToken cancellationToken = default + ) { - var aggregate = await GetAsync( + var result = await GetAsync( aggregateId, new() { DeleteMode = DeleteHandlingMode.ReturnsAggregate }, cancellationToken ); + if (result.IsFailure) + return result; - return aggregate == null ? null - : aggregate.Details.IsDeleted ? FulfilRequirements(aggregate) - : throw AggregateNotDeletedException(aggregateId); + var aggregate = result.Value; + + return aggregate.Details.IsDeleted ? FulfilRequirements(aggregate) : NotDeleted(aggregateId); } /// public IAsyncEnumerable<(EventRecord EventRecord, string EventType)> GetEventRangeAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, CancellationToken cancellationToken ) { - if (!_events.TryGetValue(aggregateId, out var eventList)) + if (!IsVisible(aggregateId) || !_events.TryGetValue(aggregateId, out var eventList)) return AsyncEnumerable.Empty<(EventRecord EventRecord, string EventType)>(); // We have some events... so query and return. Materialize once instead of chaining LINQ @@ -296,7 +352,7 @@ CancellationToken cancellationToken } /// - public async Task GetOrCreateAsync( + public async Task> GetOrCreateAsync( string? aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -304,8 +360,8 @@ CancellationToken cancellationToken { if (!string.IsNullOrWhiteSpace(aggregateId)) { - var exists = await ExistsAsync(aggregateId, cancellationToken); - if (exists) + var existence = await ExistsAsync(aggregateId, cancellationToken); + if (existence.DoesExist) return await GetAsync(aggregateId, operationContext, cancellationToken); } @@ -313,12 +369,7 @@ CancellationToken cancellationToken } /// - public async Task IsDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) => - await ExistsAsync(aggregateId, cancellationToken) - && (_aggregates.TryGetValue(aggregateId, out var aggregate) && aggregate.Details.IsDeleted); - - /// - public async Task RestoreAsync( + public async Task, AggregateRestoreFailure>> RestoreAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -328,7 +379,11 @@ public async Task RestoreAsync( throw NullAggregate(aggregate); if (!aggregate.Details.IsDeleted) - throw AggregateNotDeletedException(aggregate.Id()); + { + return AggregateRestoreFailure.Failure>( + new AggregateNotDeleted(aggregate.AggregateType, aggregate.Id()) + ); + } Restored restoreAggregateEvent = new(); EventMetadata metadata = new( @@ -343,47 +398,63 @@ public async Task RestoreAsync( aggregate.ApplyEvent(restoreAggregateEvent, metadata); if (aggregate.IsNew()) - return false; + { + return AggregateRestoreFailure.Failure>( + new AggregateNotFound(aggregate.AggregateType, aggregate.Id()) + ); + } - await AddToCacheAsync(aggregate, new EventRecord(restoreAggregateEvent, metadata)); + await AddToCacheAsync(aggregate, additionalEvents: new EventRecord(restoreAggregateEvent, metadata)); - return true; + return new SaveOutcome(aggregate, SaveOutcomeKind.Written); } /// - public async Task> SaveAsync( + public async Task, AggregateSaveFailure>> SaveAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) + { + ArgumentNullException.ThrowIfNull(aggregate); + + // Wrapped rather than inlined: the core has several early returns, and every one of them is an + // outcome worth recording. + var saveStopwatch = System.Diagnostics.Stopwatch.StartNew(); + var result = await SaveCoreAsync(aggregate, operationContext, cancellationToken); + + saveStopwatch.Stop(); + _metrics.RecordSave(saveStopwatch.Elapsed.TotalMilliseconds, typeof(T).Name, result); + + return result; + } + + async Task, AggregateSaveFailure>> SaveCoreAsync( + T aggregate, + EventStoreOperationContext? operationContext, + CancellationToken cancellationToken + ) { operationContext ??= EventStoreOperationContext.DefaultContext(); FulfilRequirements(aggregate); var validationResult = await GuardAsync(aggregate, cancellationToken); - static SaveResult ReturnSaveResult( - T a, - bool success, - bool skipped, - ValidationResult? validationResult = null - ) => new(a, validationResult ?? new ValidationResult(), success, skipped); - if (!validationResult.IsValid) - return ReturnSaveResult(aggregate, false, false, validationResult); + return AggregateSaveFailure.Failure>(new AggregateInvalid(validationResult)); if (aggregate.Details.Locked) { - return operationContext.LockMode is LockHandlingMode.ThrowsException - ? throw AggregateLockedException(aggregate.Id()) - : ReturnSaveResult(aggregate, false, false); + return AggregateSaveFailure.Failure>( + new AggregateLocked(aggregate.AggregateType, aggregate.Id()) + ); } if (string.IsNullOrWhiteSpace(aggregate.Details.Id)) throw MissingAggregateIdException(); if (!aggregate.HasUnsavedEvents()) - return ReturnSaveResult(aggregate, false, true); + return new SaveOutcome(aggregate, SaveOutcomeKind.NoChanges); var isNew = aggregate.IsNew(); var previousAggregateVersion = aggregate.Details.CurrentVersion; @@ -397,22 +468,26 @@ static SaveResult ReturnSaveResult( else if (operationContext.NotificationMode.HasFlag(NotificationModes.BeforeSave)) await aggregateChangeNotifier.BeforeSaveAsync(aggregate, isNew, cancellationToken); - if (await IsDeletedAsync(aggregate.Id(), cancellationToken)) + if ( + (await ExistsAsync(aggregate.Id(), cancellationToken)).IsDeleted + && !changeEvents.Any(record => record.Event is Restored) + ) { - var throwIfDeleted = !changeEvents.Any(record => record.Event is Restored); - if (throwIfDeleted) - throw AggregateIsDeletedException(aggregate.Id()); + return AggregateSaveFailure.Failure>( + new AggregateDeleted(aggregate.AggregateType, aggregate.Id()) + ); } try { - var userId = ClaimsPrincipal.Current?.FindFirst(operationContext.ClaimIdentifier)?.Value; + var userId = _principalAccessor.GetPrincipal()?.FindFirst(operationContext.ClaimIdentifier)?.Value; if (operationContext.RequiresValidPrincipalIdentifier && string.IsNullOrWhiteSpace(userId)) throw new NullReferenceException( $"Missing ClaimsPrincipal identifier '{operationContext.ClaimIdentifier}'. Unable to save aggregate." ); - await AddToCacheAsync(aggregate); + await AddToCacheAsync(aggregate, userId); + _metrics.EventsAppended(changeEvents.Length, typeof(T).Name); // Mirror the persistence providers: after a successful save the aggregate must // reflect the persisted version so a subsequent mutation on the same instance @@ -446,10 +521,22 @@ await aggregateChangeNotifier.AfterSaveAsync( await aggregateChangeNotifier.FailureAsync(aggregate, deleteRequested, ex, cancellationToken); } + if (ex is Exceptions.ConcurrencyException conflict) + { + return AggregateSaveFailure.Failure>( + new ConcurrencyConflict( + aggregate.AggregateType, + aggregate.Id(), + conflict.VersionAttempted, + conflict.Version + ) + ); + } + throw; } - return ReturnSaveResult(aggregate, true, false); + return new SaveOutcome(aggregate, SaveOutcomeKind.Written); } /// diff --git a/src/src/InMemory/Sdk/README.md b/src/src/InMemory/Sdk/README.md index df71b443..a66d5222 100644 --- a/src/src/InMemory/Sdk/README.md +++ b/src/src/InMemory/Sdk/README.md @@ -29,10 +29,10 @@ builder.Services.AddInMemorySnapshotEventStore(); ## Typical usage ```csharp -var order = await store.GetAsync(orderId, cancellationToken); -if (order is null) +var orderResult = await store.GetAsync(orderId, cancellationToken); +if (orderResult.IsFailure) { - order = await store.CreateAsync(orderId, cancellationToken); + var order = await store.CreateAsync(orderId, cancellationToken); order.CreateOrder(customerId); await store.SaveAsync(order, cancellationToken); } diff --git a/src/src/MirrorGenerator/EventStoreExtensionsMirrorGenerator.cs b/src/src/MirrorGenerator/EventStoreExtensionsMirrorGenerator.cs new file mode 100644 index 00000000..7343f55e --- /dev/null +++ b/src/src/MirrorGenerator/EventStoreExtensionsMirrorGenerator.cs @@ -0,0 +1,150 @@ +using System.Text; +using Microsoft.CodeAnalysis; +using Microsoft.CodeAnalysis.CSharp; +using Microsoft.CodeAnalysis.CSharp.Syntax; +using Microsoft.CodeAnalysis.Text; + +namespace Purview.EventSourcing.MirrorGenerator; + +/// +/// Mirrors the IEventStoreCore<T> convenience extensions onto the non-generic +/// IEventStore facade. +/// +/// +/// The two sets were hand-maintained copies of each other, which is a standing invitation to drift. Only +/// the receiver and the type argument differ, so the facade set is derived from the typed one and the +/// facade keeps a hand-written partial for the members that have no typed counterpart. +/// +[Generator(LanguageNames.CSharp)] +public sealed class EventStoreExtensionsMirrorGenerator : IIncrementalGenerator +{ + const string SourceClass = "IEventStoreCoreExtensions"; + const string TargetClass = "IEventStoreExtensions"; + const string TypedReceiver = "IEventStoreCore"; + const string FacadeReceiver = "IEventStore"; + + /// + public void Initialize(IncrementalGeneratorInitializationContext context) + { + // The transform produces the finished source text, so the pipeline caches on a string rather + // than on syntax nodes or a semantic model. + var mirrored = context + .SyntaxProvider.CreateSyntaxProvider( + static (node, _) => node is ClassDeclarationSyntax { Identifier.ValueText: SourceClass }, + static (syntaxContext, cancellationToken) => + Mirror((ClassDeclarationSyntax)syntaxContext.Node, syntaxContext.SemanticModel, cancellationToken) + ) + .Where(static source => source is not null); + + context.RegisterSourceOutput( + mirrored, + static (sourceContext, source) => + sourceContext.AddSource($"{TargetClass}.g.cs", SourceText.From(source!, Encoding.UTF8)) + ); + } + + static string? Mirror( + ClassDeclarationSyntax declaration, + SemanticModel semanticModel, + CancellationToken cancellationToken + ) + { + var members = declaration + .Members.OfType() + .Where(static method => + method.Modifiers.Any(SyntaxKind.PublicKeyword) && method.Modifiers.Any(SyntaxKind.StaticKeyword) + ) + .Where(method => IsTypedReceiver(method)) + .Select(method => Rewrite(method, semanticModel, cancellationToken)) + .ToArray(); + + if (members.Length == 0) + return null; + + StringBuilder builder = new(); + builder + .AppendLine("// ") + .AppendLine("#nullable enable") + .AppendLine() + .AppendLine("using System.Diagnostics.CodeAnalysis;") + .AppendLine("using Purview.EventSourcing.Aggregates;") + .AppendLine("using Purview.EventSourcing.Failures;") + .AppendLine("using Purview.Results;") + .AppendLine() + .AppendLine("namespace Purview.EventSourcing;") + .AppendLine() + .AppendLine($"static partial class {TargetClass}") + .AppendLine("{"); + + foreach (var member in members) + builder.AppendLine(member).AppendLine(); + + builder.AppendLine("}"); + + return builder.ToString(); + } + + static bool IsTypedReceiver(MethodDeclarationSyntax method) + { + var receiver = method.ParameterList.Parameters.FirstOrDefault(); + + return receiver?.Modifiers.Any(SyntaxKind.ThisKeyword) == true && receiver.Type?.ToString() == TypedReceiver; + } + + static string Rewrite( + MethodDeclarationSyntax method, + SemanticModel semanticModel, + CancellationToken cancellationToken + ) + { + MirrorRewriter rewriter = new(semanticModel, cancellationToken); + var rewritten = (MethodDeclarationSyntax)rewriter.Visit(method); + + return rewritten.NormalizeWhitespace("\t", "\n").ToFullString(); + } + + sealed class MirrorRewriter(SemanticModel semanticModel, CancellationToken cancellationToken) : CSharpSyntaxRewriter + { + public override SyntaxNode? VisitParameter(ParameterSyntax node) + { + var visited = (ParameterSyntax)base.VisitParameter(node)!; + + return visited.Type?.ToString() == TypedReceiver + ? visited.WithType(SyntaxFactory.ParseTypeName(FacadeReceiver)) + : visited; + } + + public override SyntaxNode? VisitInvocationExpression(InvocationExpressionSyntax node) + { + // On IEventStoreCore the aggregate type is fixed by the receiver, so a call like + // DeleteAsync(aggregateId, ...) is unambiguous. On the facade every member is generic, and + // the interface's own DeleteAsync(T, ...) would win by inferring T from the id. Both the + // interface members and this class's own extensions therefore need the type argument spelled + // out, which is decided from the resolved symbol rather than from the method's name. + var needsTypeArgument = + node.Expression is MemberAccessExpressionSyntax { Name: IdentifierNameSyntax } + && semanticModel.GetSymbolInfo(node, cancellationToken).Symbol is IMethodSymbol symbol + && symbol.ContainingType.Name is "IEventStoreCore" or SourceClass; + + var visited = (InvocationExpressionSyntax)base.VisitInvocationExpression(node)!; + if (!needsTypeArgument || visited.Expression is not MemberAccessExpressionSyntax access) + return visited; + + var generic = SyntaxFactory.GenericName( + ((IdentifierNameSyntax)access.Name).Identifier, + SyntaxFactory.TypeArgumentList( + SyntaxFactory.SingletonSeparatedList(SyntaxFactory.ParseTypeName("T")) + ) + ); + + return visited.WithExpression(access.WithName(generic)); + } + + public override SyntaxTriviaList VisitList(SyntaxTriviaList list) => + // The documentation names the receiver too, and a cref to IEventStoreCore{T} would not + // resolve from a method whose receiver is now IEventStore. + SyntaxFactory.ParseLeadingTrivia( + base.VisitList(list).ToFullString().Replace("IEventStoreCore{T}", "IEventStore") + ); + } +} diff --git a/src/src/MirrorGenerator/MirrorGenerator.csproj b/src/src/MirrorGenerator/MirrorGenerator.csproj new file mode 100644 index 00000000..c5ef00f5 --- /dev/null +++ b/src/src/MirrorGenerator/MirrorGenerator.csproj @@ -0,0 +1,15 @@ + + + netstandard2.0 + true + + false + true + + + + + + + diff --git a/src/src/MongoDB/Events/AggregateVersionData.cs b/src/src/MongoDB/Events/AggregateVersionData.cs index 22173843..d70659d0 100644 --- a/src/src/MongoDB/Events/AggregateVersionData.cs +++ b/src/src/MongoDB/Events/AggregateVersionData.cs @@ -1,4 +1,4 @@ -using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Aggregates; namespace Purview.EventSourcing.MongoDB.Events; @@ -8,7 +8,7 @@ namespace Purview.EventSourcing.MongoDB.Events; /// The last version persisted to the event stream. /// The version captured by the most recent snapshot, or zero when none exists. /// The current version of the aggregate. -public record struct AggregateVersionData(int SavedVersion, int SnapshotVersion, int CurrentVersion) +public record struct AggregateVersionData(long SavedVersion, long SnapshotVersion, long CurrentVersion) { /// /// Creates an instance from the details of an . diff --git a/src/src/MongoDB/Events/Entities/EventEntity.cs b/src/src/MongoDB/Events/Entities/EventEntity.cs index 88d75e4f..3cf91240 100644 --- a/src/src/MongoDB/Events/Entities/EventEntity.cs +++ b/src/src/MongoDB/Events/Entities/EventEntity.cs @@ -1,4 +1,4 @@ -using System.Diagnostics; +using System.Diagnostics; using System.Text.Json.Serialization; using MongoDB.Bson.Serialization.Attributes; using Purview.EventSourcing.MongoDB.StorageClient; @@ -27,6 +27,11 @@ public sealed class EventEntity : IEntity /// public int EntityType { get; set; } = EntityTypes.EventType; + /// + /// The tenant that owns the document; null in a single-tenant deployment. + /// + public string? TenantId { get; set; } + /// /// The identifier of the aggregate the event belongs to. /// @@ -35,7 +40,7 @@ public sealed class EventEntity : IEntity /// /// The aggregate version the event was applied at. /// - public int Version { get; set; } + public long Version { get; set; } /// /// The serialized event payload. diff --git a/src/src/MongoDB/Events/Entities/IdempotencyMarkerEntity.cs b/src/src/MongoDB/Events/Entities/IdempotencyMarkerEntity.cs index ca9f8da7..27a007a2 100644 --- a/src/src/MongoDB/Events/Entities/IdempotencyMarkerEntity.cs +++ b/src/src/MongoDB/Events/Entities/IdempotencyMarkerEntity.cs @@ -1,4 +1,4 @@ -using System.Diagnostics; +using System.Diagnostics; using System.Text.Json.Serialization; using MongoDB.Bson.Serialization.Attributes; using Purview.EventSourcing.MongoDB.StorageClient; @@ -28,6 +28,11 @@ public sealed class IdempotencyMarkerEntity : IEntity /// public int EntityType { get; set; } = EntityTypes.IdempotencyMarkerType; + /// + /// The tenant that owns the document; null in a single-tenant deployment. + /// + public string? TenantId { get; set; } + /// /// The identifier of the aggregate the save operation targeted. /// @@ -41,7 +46,7 @@ public sealed class IdempotencyMarkerEntity : IEntity "CA1819:Properties should not return arrays", Justification = "This is a DTO." )] - public int[] EventVersions { get; set; } = []; + public long[] EventVersions { get; set; } = []; /// /// The time the marker was persisted. diff --git a/src/src/MongoDB/Events/Entities/SnapshotEntity.cs b/src/src/MongoDB/Events/Entities/SnapshotEntity.cs index 8f01ebd1..07045e39 100644 --- a/src/src/MongoDB/Events/Entities/SnapshotEntity.cs +++ b/src/src/MongoDB/Events/Entities/SnapshotEntity.cs @@ -1,4 +1,4 @@ -using System.Diagnostics; +using System.Diagnostics; using System.Text.Json.Serialization; using MongoDB.Bson.Serialization.Attributes; using Purview.EventSourcing.MongoDB.StorageClient; @@ -41,6 +41,11 @@ public string AggregateId /// public int EntityType { get; set; } = EntityTypes.SnapshotType; + /// + /// The tenant that owns the document; null in a single-tenant deployment. + /// + public string? TenantId { get; set; } + /// /// The short name of the aggregate type the snapshot belongs to. /// diff --git a/src/src/MongoDB/Events/Entities/StreamVersionEntity.cs b/src/src/MongoDB/Events/Entities/StreamVersionEntity.cs index 482ad42e..65c63189 100644 --- a/src/src/MongoDB/Events/Entities/StreamVersionEntity.cs +++ b/src/src/MongoDB/Events/Entities/StreamVersionEntity.cs @@ -1,4 +1,4 @@ -using System.Diagnostics; +using System.Diagnostics; using System.Text.Json.Serialization; using MongoDB.Bson.Serialization.Attributes; using Purview.EventSourcing.MongoDB.StorageClient; @@ -32,6 +32,11 @@ public sealed class StreamVersionEntity : IEntity /// public int EntityType { get; set; } = EntityTypes.StreamVersionType; + /// + /// The tenant that owns the document; null in a single-tenant deployment. + /// + public string? TenantId { get; set; } + /// /// Indicates whether the aggregate is soft-deleted. /// @@ -45,7 +50,7 @@ public sealed class StreamVersionEntity : IEntity /// /// This is the most recently saved version of the aggregate. /// - public int Version { get; set; } + public long Version { get; set; } /// /// The time the record was last updated. diff --git a/src/src/MongoDB/Events/Exceptions/AggregateAlreadyDeletedException.cs b/src/src/MongoDB/Events/Exceptions/AggregateAlreadyDeletedException.cs deleted file mode 100644 index f5813307..00000000 --- a/src/src/MongoDB/Events/Exceptions/AggregateAlreadyDeletedException.cs +++ /dev/null @@ -1,24 +0,0 @@ -namespace Purview.EventSourcing.MongoDB.Events.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an attempt is made to delete an aggregate that is already deleted. -/// -/// The identifier of the aggregate. -/// The idempotency identifier of the operation. -public class AggregateAlreadyDeletedException(string aggregateId, string idempotencyId) - : Exception( - $"An attempt to delete an aggregate (Id: {aggregateId}) that is already deleted was made. {nameof(idempotencyId)}: {idempotencyId}." - ) -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The identifier of the aggregate that is already deleted. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// The idempotency identifier of the delete operation. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/MongoDB/Events/Exceptions/AggregateDeletedException.cs b/src/src/MongoDB/Events/Exceptions/AggregateDeletedException.cs deleted file mode 100644 index d62cd6c9..00000000 --- a/src/src/MongoDB/Events/Exceptions/AggregateDeletedException.cs +++ /dev/null @@ -1,24 +0,0 @@ -namespace Purview.EventSourcing.MongoDB.Events.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an attempt is made to save an aggregate that has been deleted. -/// -/// The identifier of the aggregate. -/// The idempotency identifier of the operation. -public class AggregateDeletedException(string aggregateId, string idempotencyId) - : Exception( - $"An attempt to save an aggregate that has been deleted, aggregate Id: {aggregateId}, {nameof(IdempotencyId)}: {idempotencyId}." - ) -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The identifier of the aggregate that has been deleted. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// The idempotency identifier of the save operation. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/MongoDB/Events/Exceptions/AggregateIsDeletedException.cs b/src/src/MongoDB/Events/Exceptions/AggregateIsDeletedException.cs deleted file mode 100644 index f30995fa..00000000 --- a/src/src/MongoDB/Events/Exceptions/AggregateIsDeletedException.cs +++ /dev/null @@ -1,16 +0,0 @@ -namespace Purview.EventSourcing.MongoDB.Events.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an invalid operation is performed against an aggregate that has been deleted. -/// -/// The identifier of the aggregate. -public class AggregateIsDeletedException(string aggregateId) - : Exception($"Invalid operation against an aggregate (Id: {aggregateId}) that has been deleted.") -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The identifier of the aggregate that has been deleted. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); -} diff --git a/src/src/MongoDB/Events/Exceptions/AggregateLockedException.cs b/src/src/MongoDB/Events/Exceptions/AggregateLockedException.cs deleted file mode 100644 index 9fc14ffe..00000000 --- a/src/src/MongoDB/Events/Exceptions/AggregateLockedException.cs +++ /dev/null @@ -1,18 +0,0 @@ -namespace Purview.EventSourcing.MongoDB.Events.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an attempt is made to save an aggregate that is currently locked. -/// -/// The idempotency identifier of the operation. -public class AggregateLockedException(string idempotencyId) - : Exception( - $"An attempt to save an aggregate that is currently locked was made, {nameof(idempotencyId)}: {idempotencyId}." - ) -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The idempotency identifier of the save operation. - /// - public string IdempotencyId { get; set; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/MongoDB/Events/Exceptions/AggregateNotDeletedException.cs b/src/src/MongoDB/Events/Exceptions/AggregateNotDeletedException.cs deleted file mode 100644 index ee566d80..00000000 --- a/src/src/MongoDB/Events/Exceptions/AggregateNotDeletedException.cs +++ /dev/null @@ -1,16 +0,0 @@ -namespace Purview.EventSourcing.MongoDB.Events.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an attempt is made to get an aggregate that has not been deleted using a deleted-aggregate operation. -/// -/// The identifier of the aggregate. -public class AggregateNotDeletedException(string aggregateId) - : Exception($"An attempt to get an aggregate that has not been deleted, aggregate Id: {aggregateId}.") -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The identifier of the aggregate that has not been deleted. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); -} diff --git a/src/src/MongoDB/Events/Exceptions/AggregateStreamVersionMissingException.cs b/src/src/MongoDB/Events/Exceptions/AggregateStreamVersionMissingException.cs deleted file mode 100644 index ec45449b..00000000 --- a/src/src/MongoDB/Events/Exceptions/AggregateStreamVersionMissingException.cs +++ /dev/null @@ -1,24 +0,0 @@ -namespace Purview.EventSourcing.MongoDB.Events.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an attempt is made to delete an aggregate that has no stream version record. -/// -/// The identifier of the aggregate. -/// The idempotency identifier of the operation. -public class AggregateStreamVersionMissingException(string aggregateId, string idempotencyId) - : Exception( - $"An attempt to delete an aggregate (Id: {aggregateId}) that doesn't a stream version deleted was made. {nameof(idempotencyId)}: {idempotencyId}." - ) -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The identifier of the aggregate with no stream version record. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// The idempotency identifier of the delete operation. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/MongoDB/Events/Exceptions/AggregatedNotAlreadyDeletedException.cs b/src/src/MongoDB/Events/Exceptions/AggregatedNotAlreadyDeletedException.cs deleted file mode 100644 index e905984b..00000000 --- a/src/src/MongoDB/Events/Exceptions/AggregatedNotAlreadyDeletedException.cs +++ /dev/null @@ -1,24 +0,0 @@ -namespace Purview.EventSourcing.MongoDB.Events.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an attempt is made to restore an aggregate that is not currently deleted. -/// -/// The identifier of the aggregate. -/// The idempotency identifier of the operation. -public class AggregatedNotAlreadyDeletedException(string aggregateId, string idempotencyId) - : Exception( - $"An attempt to restore an aggregate (Id: {aggregateId}) that is not deleted was made.\n\n\tIdempotencyId: {idempotencyId}." - ) -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The identifier of the aggregate that is not deleted. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// The idempotency identifier of the restore operation. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/MongoDB/Events/Exceptions/CommitException.cs b/src/src/MongoDB/Events/Exceptions/CommitException.cs deleted file mode 100644 index a94c3309..00000000 --- a/src/src/MongoDB/Events/Exceptions/CommitException.cs +++ /dev/null @@ -1,44 +0,0 @@ -namespace Purview.EventSourcing.MongoDB.Events.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when a batch of events fails to commit to MongoDB storage. -/// -/// The identifier of the aggregate being saved. -/// The idempotency identifier of the operation. -/// The aggregate version that was attempted to be saved. -/// The current aggregate version present in storage. -/// The underlying storage exception that caused the commit to fail. -public class CommitException( - string aggregateId, - string idempotencyId, - int versionAttempted, - int version, - Exception exception -) - : Exception( - $"Failed to commit events.\n\tAggregateId: {aggregateId}\n\tIdempotencyId: {idempotencyId}\n\tVersionAttempted: {versionAttempted}\n\tVersionPresent: {version}", - exception - ) -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The identifier of the aggregate being saved. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// The aggregate version that was attempted to be saved. - /// - public int VersionAttempted { get; } = versionAttempted; - - /// - /// The idempotency identifier of the save operation. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); - - /// - /// The current aggregate version present in storage. - /// - public int Version { get; } = version; -} diff --git a/src/src/MongoDB/Events/Exceptions/ConcurrencyException.cs b/src/src/MongoDB/Events/Exceptions/ConcurrencyException.cs deleted file mode 100644 index c1b12f23..00000000 --- a/src/src/MongoDB/Events/Exceptions/ConcurrencyException.cs +++ /dev/null @@ -1,37 +0,0 @@ -namespace Purview.EventSourcing.MongoDB.Events.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an optimistic concurrency check fails during a save operation. -/// -/// The identifier of the aggregate being saved. -/// The idempotency identifier of the operation. -/// The aggregate version that was attempted to be saved. -/// The current aggregate version present in storage. -public class ConcurrencyException(string aggregateId, string idempotencyId, int versionAttempted, int version) - : Exception( - $"Optimistic concurrency error:\n\tAggregateId: {aggregateId}\n\tIdempotencyId: {idempotencyId}\n\tVersionAttempted:{versionAttempted}\n\tVersionPresent:{version}" - ), - IConcurrencyConflict -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The identifier of the aggregate being saved. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// The aggregate version that was attempted to be saved. - /// - public int VersionAttempted { get; } = versionAttempted; - - /// - /// The idempotency identifier of the save operation. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); - - /// - /// The current aggregate version present in storage. - /// - public int Version { get; } = version; -} diff --git a/src/src/MongoDB/Events/Exceptions/MissingAggregateIdException.cs b/src/src/MongoDB/Events/Exceptions/MissingAggregateIdException.cs deleted file mode 100644 index b5e6853c..00000000 --- a/src/src/MongoDB/Events/Exceptions/MissingAggregateIdException.cs +++ /dev/null @@ -1,16 +0,0 @@ -namespace Purview.EventSourcing.MongoDB.Events.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an attempt is made to save an aggregate that does not have an identifier. -/// -/// The idempotency identifier of the operation. -public class MissingAggregateIdException(string idempotencyId) - : Exception($"An attempt to save an aggregate is a missing Id was made, {nameof(idempotencyId)}: {idempotencyId}.") -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The idempotency identifier of the save operation. - /// - public string IdempotencyId { get; set; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/MongoDB/Events/IMongoDBEventStoreTelemetry.cs b/src/src/MongoDB/Events/IMongoDBEventStoreTelemetry.cs index eb95a652..4e8ef321 100644 --- a/src/src/MongoDB/Events/IMongoDBEventStoreTelemetry.cs +++ b/src/src/MongoDB/Events/IMongoDBEventStoreTelemetry.cs @@ -40,7 +40,7 @@ public interface IMongoDBEventStoreTelemetry void GetAggregateAtSpecificVersionFailed( string aggregateId, string aggregateTypeFullName, - int specificVersion, + long specificVersion, Exception exception ); @@ -68,7 +68,7 @@ AggregateVersionData versionData /// The version the aggregate is requested at. /// The full name of the aggregate type. [Debug] - void GetAggregateAtSpecificVersionStart(string aggregateId, int specificVersion, string aggregateTypeFullName); + void GetAggregateAtSpecificVersionStart(string aggregateId, long specificVersion, string aggregateTypeFullName); /// /// Logs that a save operation contained no changes to persist. @@ -93,7 +93,7 @@ void SkippedUnknownEvent( string aggregateTypeFullName, string aggregateType, string eventType, - int aggregateVersion + long aggregateVersion ); /// @@ -112,7 +112,7 @@ void CannotApplyEvent( string aggregateType, string eventType, string eventTypeFullName, - int aggregateVersion + long aggregateVersion ); /// @@ -233,7 +233,7 @@ int aggregateVersion void GetAggregateAtSpecificVersionComplete( string aggregateId, string aggregateTypeFullName, - int specificVersion, + long specificVersion, long elapsedMilliseconds ); @@ -327,7 +327,7 @@ string aggregateTypeFullName /// The short name of the aggregate type. /// Whether the aggregate is soft-deleted. [Debug] - void StreamVersionFound(string aggregateId, int streamVersion, string aggregateType, bool isDeleted); + void StreamVersionFound(string aggregateId, long streamVersion, string aggregateType, bool isDeleted); /// /// Logs that reading the stream version record failed. diff --git a/src/src/MongoDB/Events/MongoDBEventStore.DeleteAsync.cs b/src/src/MongoDB/Events/MongoDBEventStore.DeleteAsync.cs index b835f592..fcffa3d7 100644 --- a/src/src/MongoDB/Events/MongoDBEventStore.DeleteAsync.cs +++ b/src/src/MongoDB/Events/MongoDBEventStore.DeleteAsync.cs @@ -1,13 +1,15 @@ using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.MongoDB.Events.Entities; +using Purview.Results; namespace Purview.EventSourcing.MongoDB; partial class MongoDBEventStore { /// - public async Task DeleteAsync( + public async Task, AggregateDeleteFailure>> DeleteAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -17,12 +19,20 @@ public async Task DeleteAsync( throw NullAggregate(aggregate); if (aggregate.Details.IsDeleted) - throw AggregateIsDeletedException(aggregate.Id()); + { + return AggregateDeleteFailure.Failure>( + new AggregateAlreadyDeleted(aggregate.AggregateType, aggregate.Id()) + ); + } operationContext ??= EventStoreOperationContext.DefaultContext(); if (aggregate.IsNew()) - return false; + { + return AggregateDeleteFailure.Failure>( + new AggregateNotFound(aggregate.AggregateType, aggregate.Id()) + ); + } if (operationContext.PermanentlyDelete) return await PermanentlyDeleteAsync(aggregate, operationContext, cancellationToken); @@ -46,10 +56,10 @@ public async Task DeleteAsync( new EventRecord(deleteAggregateEvent, metadata) ); - return result.Saved; + return result.IsFailure ? result.Error.ToDeleteFailure() : result.Value; } - async Task PermanentlyDeleteAsync( + async Task, AggregateDeleteFailure>> PermanentlyDeleteAsync( T aggregate, EventStoreOperationContext operationContext, CancellationToken cancellationToken = default @@ -61,14 +71,19 @@ async Task PermanentlyDeleteAsync( var aggregateId = aggregate.Id(); var streamVersion = await GetStreamVersionAsync(aggregateId, true, cancellationToken); if (streamVersion == null) - return false; + { + return AggregateDeleteFailure.Failure>( + new AggregateNotFound(aggregate.AggregateType, aggregateId) + ); + } _eventStoreTelemetry.PermanentDeleteRequested(aggregateId); try { - var ids = Enumerable - .Range(1, streamVersion.Version) - .Select(id => CreateEventId(aggregateId, id).ToString()); + // The stream version is a long, so the id range is built over longs: Enumerable.Range is int-only. + List ids = []; + for (var version = 1L; version <= streamVersion.Version; version++) + ids.Add(CreateEventId(aggregateId, version)); List entitiesToDelete = [.. ids]; entitiesToDelete.Add(streamVersion.Id); @@ -91,7 +106,7 @@ async Task PermanentlyDeleteAsync( aggregate.Details.IsDeleted = true; aggregate.Details.Locked = true; - return true; + return new SaveOutcome(aggregate, SaveOutcomeKind.Written); } #pragma warning disable CA1031 catch (Exception ex) @@ -99,7 +114,7 @@ async Task PermanentlyDeleteAsync( { _eventStoreTelemetry.PermanentDeleteFailed(aggregateId, ex); - return false; + throw; } finally { diff --git a/src/src/MongoDB/Events/MongoDBEventStore.ExceptionHelpers.cs b/src/src/MongoDB/Events/MongoDBEventStore.ExceptionHelpers.cs index 2df7a55d..50ae0bc7 100644 --- a/src/src/MongoDB/Events/MongoDBEventStore.ExceptionHelpers.cs +++ b/src/src/MongoDB/Events/MongoDBEventStore.ExceptionHelpers.cs @@ -1,4 +1,5 @@ -using Purview.EventSourcing.MongoDB.Events.Exceptions; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.MongoDB; @@ -7,7 +8,12 @@ partial class MongoDBEventStore { static ArgumentNullException NullAggregate(T? aggregate) => new(nameof(aggregate)); - static AggregateIsDeletedException AggregateIsDeletedException(string aggregateId) => new(aggregateId); + Result NotFound(string aggregateId) => + AggregateReadFailure.Failure(new AggregateNotFound(_aggregateTypeShortName, aggregateId)); - static AggregateNotDeletedException AggregateNotDeletedException(string aggregateId) => new(aggregateId); + Result Deleted(string aggregateId) => + AggregateReadFailure.Failure(new AggregateDeleted(_aggregateTypeShortName, aggregateId)); + + Result NotDeleted(string aggregateId) => + AggregateReadFailure.Failure(new AggregateNotDeleted(_aggregateTypeShortName, aggregateId)); } diff --git a/src/src/MongoDB/Events/MongoDBEventStore.ExistsAsync.cs b/src/src/MongoDB/Events/MongoDBEventStore.ExistsAsync.cs index 698a40c3..50565577 100644 --- a/src/src/MongoDB/Events/MongoDBEventStore.ExistsAsync.cs +++ b/src/src/MongoDB/Events/MongoDBEventStore.ExistsAsync.cs @@ -1,18 +1,18 @@ -namespace Purview.EventSourcing.MongoDB; +namespace Purview.EventSourcing.MongoDB; partial class MongoDBEventStore { /// - public async Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) + public async Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) { ArgumentException.ThrowIfNullOrWhiteSpace(aggregateId, nameof(aggregateId)); var streamVersion = await GetStreamVersionAsync(aggregateId, false, cancellationToken); return streamVersion == null - ? ExistsState.DoesNotExist - : new ExistsState + ? AggregateExistence.DoesNotExist + : new AggregateExistence { - Status = streamVersion.IsDeleted ? ExistsStatus.ExistsInDeletedState : ExistsStatus.Exists, + Status = streamVersion.IsDeleted ? ExistenceStatus.ExistsInDeletedState : ExistenceStatus.Exists, Version = streamVersion.Version, }; } diff --git a/src/src/MongoDB/Events/MongoDBEventStore.GetAsync.cs b/src/src/MongoDB/Events/MongoDBEventStore.GetAsync.cs index d028b853..4cffe088 100644 --- a/src/src/MongoDB/Events/MongoDBEventStore.GetAsync.cs +++ b/src/src/MongoDB/Events/MongoDBEventStore.GetAsync.cs @@ -2,8 +2,10 @@ using Microsoft.Extensions.Caching.Distributed; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.MongoDB.Events; using Purview.EventSourcing.MongoDB.Events.Entities; +using Purview.Results; namespace Purview.EventSourcing.MongoDB; @@ -11,13 +13,13 @@ partial class MongoDBEventStore { /// [System.Diagnostics.DebuggerStepThrough] - public Task GetAsync( + public Task> GetAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => GetCoreAsync(aggregateId, operationContext, cancellationToken); - async Task GetCoreAsync( + async Task> GetCoreAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -45,9 +47,9 @@ partial class MongoDBEventStore { _eventStoreTelemetry.AggregateRetrievedFromCache(aggregateId, _aggregateTypeFullName); - return ReturnAggregate(aggregate.Details.IsDeleted, aggregateId, operationContext) + return ReturnAggregate(aggregate.Details.IsDeleted, operationContext) ? PrepareAggregateForReturn(aggregate, _aggregateRequirementsManager) - : null; + : Deleted(aggregateId); } // Single-flight: when the aggregate will be written back to the cache, serialize @@ -73,30 +75,30 @@ partial class MongoDBEventStore { _eventStoreTelemetry.AggregateRetrievedFromCache(aggregateId, _aggregateTypeFullName); - return ReturnAggregate(cached.Details.IsDeleted, aggregateId, operationContext) + return ReturnAggregate(cached.Details.IsDeleted, operationContext) ? PrepareAggregateForReturn(cached, _aggregateRequirementsManager) - : null; + : Deleted(aggregateId); } } var streamVersion = await GetStreamVersionAsync(aggregateId, true, cancellationToken); if (streamVersion == null) - return null; + return NotFound(aggregateId); - if (!ReturnAggregate(streamVersion.IsDeleted, aggregateId, operationContext)) - return null; + if (!ReturnAggregate(streamVersion.IsDeleted, operationContext)) + return Deleted(aggregateId); //** THIS ISN'T CORRECT, SO WE'RE PASSING IN NULL TO ENABLE ALL ADDITIONAL EVENTS **// // TODO: It's only odd as in I haven't thought it through completely... - //int? streamVersionIdentifier = streamVersion.Version; + //long? streamVersionIdentifier = streamVersion.Version; //if (streamVersionIdentifier < 1) // // Passing in null for the maxVersion, because we want it to go and find all additional events // // because we don't have a valid version. // streamVersionIdentifier = null; // Passing in null for the maxVersion, because we want it to go and find all additional events - int? streamVersionIdentifier = null; + long? streamVersionIdentifier = null; if (!operationContext.SkipSnapshot) { // If there's no snapshot, then this isn't doing a create (as in brand new @@ -125,6 +127,7 @@ partial class MongoDBEventStore _aggregateTypeFullName, getStopwatch.ElapsedMilliseconds ); + _metrics.GetDuration(getStopwatch.Elapsed.TotalMilliseconds, _aggregateTypeShortName); } async Task IsCacheHitFreshAsync(T aggregate, string aggregateId, CancellationToken cancellationToken) @@ -153,7 +156,7 @@ Services.IAggregateRequirementsManager aggregateRequirementsManager async Task GetAndApplyEventsAsync( T aggregate, StreamVersionEntity streamVersion, - int? maxVersion, + long? maxVersion, CancellationToken cancellationToken ) { diff --git a/src/src/MongoDB/Events/MongoDBEventStore.GetAtAsync.cs b/src/src/MongoDB/Events/MongoDBEventStore.GetAtAsync.cs index 99e3e6fa..add824ae 100644 --- a/src/src/MongoDB/Events/MongoDBEventStore.GetAtAsync.cs +++ b/src/src/MongoDB/Events/MongoDBEventStore.GetAtAsync.cs @@ -1,13 +1,15 @@ using System.Diagnostics; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.MongoDB; partial class MongoDBEventStore { /// - public async Task GetAtAsync( + public async Task> GetAtAsync( string aggregateId, - int version, + long version, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) @@ -22,10 +24,10 @@ partial class MongoDBEventStore { var streamVersion = await GetStreamVersionAsync(aggregateId, true, cancellationToken); if (streamVersion == null) - return null; + return NotFound(aggregateId); - if (!ReturnAggregate(streamVersion.IsDeleted, aggregateId, operationContext)) - return null; + if (!ReturnAggregate(streamVersion.IsDeleted, operationContext)) + return Deleted(aggregateId); T aggregate = new() { Details = { Id = aggregateId } }; diff --git a/src/src/MongoDB/Events/MongoDBEventStore.GetDeletedAsync.cs b/src/src/MongoDB/Events/MongoDBEventStore.GetDeletedAsync.cs index 94932399..6b26be68 100644 --- a/src/src/MongoDB/Events/MongoDBEventStore.GetDeletedAsync.cs +++ b/src/src/MongoDB/Events/MongoDBEventStore.GetDeletedAsync.cs @@ -1,18 +1,26 @@ -namespace Purview.EventSourcing.MongoDB; +using Purview.EventSourcing.Failures; +using Purview.Results; + +namespace Purview.EventSourcing.MongoDB; partial class MongoDBEventStore { /// - public async Task GetDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) + public async Task> GetDeletedAsync( + string aggregateId, + CancellationToken cancellationToken = default + ) { - var aggregate = await GetCoreAsync( + var result = await GetCoreAsync( aggregateId, new() { SnapshotCacheMode = SnapshotCachingOptions.None, DeleteMode = DeleteHandlingMode.ReturnsAggregate }, cancellationToken ); + if (result.IsFailure) + return result; + + var aggregate = result.Value; - return aggregate == null ? null - : aggregate.Details.IsDeleted ? FulfilRequirements(aggregate) - : throw AggregateNotDeletedException(aggregateId); + return aggregate.Details.IsDeleted ? FulfilRequirements(aggregate) : NotDeleted(aggregateId); } } diff --git a/src/src/MongoDB/Events/MongoDBEventStore.GetEventRangeAsync.cs b/src/src/MongoDB/Events/MongoDBEventStore.GetEventRangeAsync.cs index 954445d7..bc835823 100644 --- a/src/src/MongoDB/Events/MongoDBEventStore.GetEventRangeAsync.cs +++ b/src/src/MongoDB/Events/MongoDBEventStore.GetEventRangeAsync.cs @@ -17,8 +17,8 @@ partial class MongoDBEventStore /// If no is specified all available events greater than are returned. public async IAsyncEnumerable<(EventRecord EventRecord, string EventType)> GetEventRangeAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, [EnumeratorCancellation] CancellationToken cancellationToken ) { @@ -40,7 +40,7 @@ [EnumeratorCancellation] CancellationToken cancellationToken var entities = GetEventRangeEntitiesAsync(aggregateId, versionFrom, versionTo, cancellationToken); await foreach (var entity in entities) { - var item = DeserializeEvent(entity); + var item = await DeserializeEventAsync(entity, cancellationToken); if (item != null) yield return (item.Value, entity.EventType); } @@ -48,8 +48,8 @@ [EnumeratorCancellation] CancellationToken cancellationToken internal async IAsyncEnumerable GetEventRangeEntitiesAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, [EnumeratorCancellation] CancellationToken cancellationToken ) { @@ -70,9 +70,10 @@ [EnumeratorCancellation] CancellationToken cancellationToken } /// - EventRecord? DeserializeEvent(EventEntity eventEntity) + /// + async Task DeserializeEventAsync(EventEntity eventEntity, CancellationToken cancellationToken) { - static UnknownEvent ReturnUnknownEvent(EventEntity eventEntity, int aggregateVersion) => + static UnknownEvent ReturnUnknownEvent(EventEntity eventEntity, long aggregateVersion) => new() { SchemaVersion = eventEntity.SchemaVersion, @@ -114,7 +115,19 @@ static UnknownEvent ReturnUnknownEvent(EventEntity eventEntity, int aggregateVer Type.GetType(name, throwOnError: false) ?? throw new ApplicationException($"Unable to load event type: {name}") ); - var @event = DeserializeEvent(eventEntity.Payload, runtimeEventType); + var payload = eventEntity.Payload; + if (_payloadProtector is not null && _payloadProtector.IsProtected(payload)) + { + var unprotected = await _payloadProtector.UnprotectAsync(payload, cancellationToken); + if (unprotected is null) + // The subject has been erased. Surfaced as an unknown event so replay continues and + // the aggregate reports the gap, rather than failing the whole read. + return new EventRecord(ReturnUnknownEvent(eventEntity, eventEntity.Version), metadata); + + payload = unprotected; + } + + var @event = DeserializeEvent(payload, runtimeEventType); // Apply upcasting chain when a registry is available. if (@event != null && _eventUpcasterRegistry?.CanUpcast(@event) == true) diff --git a/src/src/MongoDB/Events/MongoDBEventStore.GetOrCreateAsync.cs b/src/src/MongoDB/Events/MongoDBEventStore.GetOrCreateAsync.cs index d1ceada1..b9bb989e 100644 --- a/src/src/MongoDB/Events/MongoDBEventStore.GetOrCreateAsync.cs +++ b/src/src/MongoDB/Events/MongoDBEventStore.GetOrCreateAsync.cs @@ -1,9 +1,12 @@ -namespace Purview.EventSourcing.MongoDB; +using Purview.EventSourcing.Failures; +using Purview.Results; + +namespace Purview.EventSourcing.MongoDB; partial class MongoDBEventStore { /// - public async Task GetOrCreateAsync( + public async Task> GetOrCreateAsync( string? aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -11,8 +14,8 @@ partial class MongoDBEventStore { if (!string.IsNullOrWhiteSpace(aggregateId)) { - var exists = await ExistsAsync(aggregateId, cancellationToken); - if (exists) + var existence = await ExistsAsync(aggregateId, cancellationToken); + if (existence.DoesExist) return await GetAsync(aggregateId, operationContext, cancellationToken); } diff --git a/src/src/MongoDB/Events/MongoDBEventStore.IsDeletedAsync.cs b/src/src/MongoDB/Events/MongoDBEventStore.IsDeletedAsync.cs deleted file mode 100644 index 1ca3c8cb..00000000 --- a/src/src/MongoDB/Events/MongoDBEventStore.IsDeletedAsync.cs +++ /dev/null @@ -1,15 +0,0 @@ -namespace Purview.EventSourcing.MongoDB; - -partial class MongoDBEventStore -{ - /// - public async Task IsDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) - { - ArgumentException.ThrowIfNullOrWhiteSpace(aggregateId, nameof(aggregateId)); - - var streamVersion = await GetStreamVersionAsync(aggregateId, true, cancellationToken); - return streamVersion == null - ? throw new NullReferenceException($"The aggregate specified ({aggregateId}) does not exist.") - : streamVersion.IsDeleted; - } -} diff --git a/src/src/MongoDB/Events/MongoDBEventStore.RestoreAsync.cs b/src/src/MongoDB/Events/MongoDBEventStore.RestoreAsync.cs index 3cf75522..0cee054f 100644 --- a/src/src/MongoDB/Events/MongoDBEventStore.RestoreAsync.cs +++ b/src/src/MongoDB/Events/MongoDBEventStore.RestoreAsync.cs @@ -1,12 +1,14 @@ using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.MongoDB; partial class MongoDBEventStore { /// - public async Task RestoreAsync( + public async Task, AggregateRestoreFailure>> RestoreAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -16,7 +18,11 @@ public async Task RestoreAsync( throw NullAggregate(aggregate); if (!aggregate.Details.IsDeleted) - throw AggregateNotDeletedException(aggregate.Id()); + { + return AggregateRestoreFailure.Failure>( + new AggregateNotDeleted(aggregate.AggregateType, aggregate.Id()) + ); + } operationContext ??= EventStoreOperationContext.DefaultContext(); @@ -33,7 +39,11 @@ public async Task RestoreAsync( aggregate.ApplyEvent(restoreAggregateEvent, metadata); if (aggregate.IsNew()) - return false; + { + return AggregateRestoreFailure.Failure>( + new AggregateNotFound(aggregate.AggregateType, aggregate.Id()) + ); + } var result = await SaveCoreAsync( aggregate, @@ -41,6 +51,6 @@ public async Task RestoreAsync( cancellationToken, new EventRecord(restoreAggregateEvent, metadata) ); - return result.Saved; + return result.IsFailure ? result.Error.ToRestoreFailure() : result.Value; } } diff --git a/src/src/MongoDB/Events/MongoDBEventStore.SaveAsync.cs b/src/src/MongoDB/Events/MongoDBEventStore.SaveAsync.cs index faf11010..a09df1f3 100644 --- a/src/src/MongoDB/Events/MongoDBEventStore.SaveAsync.cs +++ b/src/src/MongoDB/Events/MongoDBEventStore.SaveAsync.cs @@ -1,15 +1,16 @@ using System.Diagnostics; using System.Diagnostics.CodeAnalysis; using System.Globalization; -using System.Security.Claims; using MongoDB.Driver; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; +using Purview.EventSourcing.Cryptography; +using Purview.EventSourcing.Exceptions; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.MongoDB.Events.Entities; -using Purview.EventSourcing.MongoDB.Events.Exceptions; using Purview.EventSourcing.MongoDB.StorageClient; -using Purview.EventSourcing.Storage; using Purview.EventSourcing.Validation; +using Purview.Results; namespace Purview.EventSourcing.MongoDB; @@ -17,22 +18,31 @@ partial class MongoDBEventStore { /// [DebuggerStepThrough] - public Task> SaveAsync( + public Task, AggregateSaveFailure>> SaveAsync( [NotNull] T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => SaveCoreAsync(aggregate, operationContext, cancellationToken); - async Task> SaveCoreAsync( + async Task, AggregateSaveFailure>> SaveCoreAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken, params EventRecord[] additionalEvents ) { + var saveStopwatch = System.Diagnostics.Stopwatch.StartNew(); var preparation = await PrepareSaveAsync(aggregate, operationContext, additionalEvents, cancellationToken); + var result = preparation.Terminal ?? await PersistAndNotifyAsync(preparation, cancellationToken); - return preparation.Terminal ?? await PersistAndNotifyAsync(preparation, cancellationToken); + saveStopwatch.Stop(); + _metrics.RecordSave(saveStopwatch.Elapsed.TotalMilliseconds, _aggregateTypeShortName, result); + + // Only a write actually appended events; a no-op or an idempotent replay appended none. + if (result.IsSuccess && result.Value.Kind is SaveOutcomeKind.Written) + _metrics.EventsAppended(preparation.ChangeEvents.Length, _aggregateTypeShortName); + + return result; } async Task PrepareSaveAsync( @@ -51,7 +61,7 @@ CancellationToken cancellationToken if (!validationResult.IsValid) return new MongoSavePreparation( - SaveResultBuilder.Create(aggregate, false, false, validationResult), + AggregateSaveFailure.Failure>(new AggregateInvalid(validationResult)), aggregate, operationContext, idempotencyId, @@ -62,17 +72,17 @@ CancellationToken cancellationToken if (aggregate.Details.Locked) { - return operationContext.LockMode is LockHandlingMode.ThrowsException - ? throw new AggregateLockedException(idempotencyId) - : new MongoSavePreparation( - SaveResultBuilder.Create(aggregate, false, false), - aggregate, - operationContext, - idempotencyId, - [], - isNew: false, - marker: null - ); + return new MongoSavePreparation( + AggregateSaveFailure.Failure>( + new AggregateLocked(aggregate.AggregateType, aggregate.Id()) + ), + aggregate, + operationContext, + idempotencyId, + [], + isNew: false, + marker: null + ); } if (string.IsNullOrWhiteSpace(aggregate.Details.Id)) @@ -88,7 +98,7 @@ CancellationToken cancellationToken ); return new MongoSavePreparation( - SaveResultBuilder.Create(aggregate, false, true), + new SaveOutcome(aggregate, SaveOutcomeKind.NoChanges), aggregate, operationContext, idempotencyId, @@ -121,7 +131,7 @@ await _eventClient.GetAsync( { _eventStoreTelemetry.EventsAlreadyApplied(aggregate.Id(), idempotencyId); return new MongoSavePreparation( - SaveResultBuilder.Create(aggregate, true, true), + new SaveOutcome(aggregate, SaveOutcomeKind.AlreadyApplied), aggregate, operationContext, idempotencyId, @@ -143,7 +153,7 @@ await _eventClient.GetAsync( ); } - async Task> PersistAndNotifyAsync( + async Task, AggregateSaveFailure>> PersistAndNotifyAsync( MongoSavePreparation preparation, CancellationToken cancellationToken ) @@ -165,11 +175,11 @@ CancellationToken cancellationToken var streamEntity = await GetStreamVersionAsync(aggregate.Id(), !isNew, cancellationToken); var hasStreamEntity = streamEntity != null; - if (streamEntity?.IsDeleted == true) + if (streamEntity?.IsDeleted == true && !changeEvents.Any(record => record.Event is Restored)) { - var throwIfDeleted = !changeEvents.Any(record => record.Event is Restored); - if (throwIfDeleted) - throw new AggregateDeletedException(aggregate.Id(), idempotencyId); + return AggregateSaveFailure.Failure>( + new AggregateDeleted(aggregate.AggregateType, aggregate.Id()) + ); } try @@ -193,7 +203,7 @@ CancellationToken cancellationToken else batchOperation.Update(streamEntity); - var userId = ClaimsPrincipal.Current?.FindFirst(operationContext.ClaimIdentifier)?.Value; + var userId = _principalAccessor.GetPrincipal()?.FindFirst(operationContext.ClaimIdentifier)?.Value; if (operationContext.RequiresValidPrincipalIdentifier && string.IsNullOrWhiteSpace(userId)) throw new NullReferenceException( $"Missing ClaimsPrincipal identifier '{operationContext.ClaimIdentifier}'. Unable to save aggregate." @@ -211,7 +221,11 @@ CancellationToken cancellationToken CorrelationId = changeEvents[i].Metadata.CorrelationId ?? operationContext.CorrelationId, }; - var serializedEvent = SerializeEvent(changeEvent); + var serializedEvent = await ProtectIfRequiredAsync( + changeEvent, + SerializeEvent(changeEvent), + cancellationToken + ); var eventEntity = CreateSerializedEvent( aggregate.Id(), changeEvent, @@ -263,20 +277,37 @@ await _aggregateChangeNotifier.AfterSaveAsync( { ClearCacheFireAndForget(aggregate); - if (operationContext.NotificationMode.HasFlag(NotificationModes.OnFailure)) - { - var deleteRequested = changeEvents.Any(record => record.Event is Deleted); - await _aggregateChangeNotifier.FailureAsync(aggregate, deleteRequested, ex, cancellationToken); - } + await HandleSaveFailureAsync(aggregate, operationContext, changeEvents, ex, cancellationToken); + + if (ex is ConcurrencyException conflict) + return AggregateSaveFailure.Failure>(ToConcurrencyConflict(aggregate, conflict)); throw; } - return SaveResultBuilder.Create(aggregate, true, false); + return new SaveOutcome(aggregate, SaveOutcomeKind.Written); + } + + static ConcurrencyConflict ToConcurrencyConflict(T aggregate, ConcurrencyException exception) => + new(aggregate.AggregateType, aggregate.Id(), exception.VersionAttempted, exception.Version); + + async Task HandleSaveFailureAsync( + T aggregate, + EventStoreOperationContext operationContext, + EventRecord[] changeEvents, + Exception exception, + CancellationToken cancellationToken + ) + { + if (!operationContext.NotificationMode.HasFlag(NotificationModes.OnFailure)) + return; + + var deleteRequested = changeEvents.Any(record => record.Event is Deleted); + await _aggregateChangeNotifier.FailureAsync(aggregate, deleteRequested, exception, cancellationToken); } sealed class MongoSavePreparation( - SaveResult? terminal, + Result, AggregateSaveFailure>? terminal, T aggregate, EventStoreOperationContext operationContext, string idempotencyId, @@ -285,7 +316,7 @@ sealed class MongoSavePreparation( IdempotencyMarkerEntity? marker ) { - public SaveResult? Terminal => terminal; + public Result, AggregateSaveFailure>? Terminal => terminal; public T Aggregate => aggregate; public EventStoreOperationContext OperationContext => operationContext; public string IdempotencyId => idempotencyId; @@ -304,8 +335,14 @@ async Task GuardAsync(T aggregate, CancellationToken cancellat ; } - static bool ShouldSnapShot(T aggregate, EventRecord[] events) + bool ShouldSnapShot(T aggregate, EventRecord[] events) { + // A snapshot serializes aggregate state, which holds the same personal data as the protected + // events in clear - and one snapshot can span many subjects, so no single key can protect it. + // With protection enabled the store does not snapshot at all: a snapshot surviving key erasure + // would make crypto-shredding untrue. Replay from events stays correct, only slower. + if (_payloadProtector is not null) + return false; return aggregate.Details.IsDeleted || events.Any(record => record.Event is Restored) || events.Length > 0; } @@ -443,4 +480,17 @@ void ClearCacheFireAndForget(T aggregate) } }); } + + /// + /// Encrypts a serialized payload when its event names a data subject. + /// + /// + /// Applied after serialization so the stored payload is the envelope, which keeps the persistence + /// schema unchanged. An event with no data subject, or a store with no protector configured, is + /// stored as before. + /// + Task ProtectIfRequiredAsync(object changeEvent, string serialized, CancellationToken cancellationToken) => + _payloadProtector is not null && changeEvent is IEventDataSubject dataSubject + ? _payloadProtector.ProtectAsync(serialized, dataSubject.DataSubjectId, cancellationToken) + : Task.FromResult(serialized); } diff --git a/src/src/MongoDB/Events/MongoDBEventStore.cs b/src/src/MongoDB/Events/MongoDBEventStore.cs index ec5b2bc0..bb577fbe 100644 --- a/src/src/MongoDB/Events/MongoDBEventStore.cs +++ b/src/src/MongoDB/Events/MongoDBEventStore.cs @@ -7,10 +7,12 @@ using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events.Upcasting; using Purview.EventSourcing.Aggregates.Snapshotting; +using Purview.EventSourcing.Cryptography; using Purview.EventSourcing.MongoDB.Events; using Purview.EventSourcing.MongoDB.Events.Entities; using Purview.EventSourcing.MongoDB.StorageClient; using Purview.EventSourcing.Services; +using Purview.EventSourcing.Tenancy; using Purview.EventSourcing.Validation; namespace Purview.EventSourcing.MongoDB; @@ -49,6 +51,14 @@ public sealed partial class MongoDBEventStore : IMongoDBEventStore, IDispo readonly IAggregateRequirementsManager _aggregateRequirementsManager; readonly IEventUpcasterRegistry? _eventUpcasterRegistry; + readonly IEventStorePrincipalAccessor _principalAccessor; + + readonly IEventStoreMetrics _metrics; + + readonly ICurrentTenant _currentTenant; + + readonly IEventPayloadProtector? _payloadProtector; + readonly string _aggregateTypeFullName; readonly string _aggregateTypeShortName; readonly int _snapshotSchemaVersion = AggregateSnapshotSchema.GetVersion(); @@ -69,6 +79,10 @@ public sealed partial class MongoDBEventStore : IMongoDBEventStore, IDispo /// Optional used to validate aggregates before they are saved. /// Optional factory used to generate aggregate ids when none is supplied. /// Optional registry used to upcast legacy events during replay. + /// Optional accessor supplying the principal recorded against saved events. + /// Optional metrics recorder; defaults to a no-op. + /// Optional tenant scope. This provider does not enforce tenant isolation and refuses a tenant-scoped operation. + /// Optional payload protector; when omitted payloads are stored unencrypted. public MongoDBEventStore( IAggregateEventNameMapper eventNameMapper, [NotNull] IOptions mongoDbOptions, @@ -80,7 +94,11 @@ public MongoDBEventStore( IMongoDBEventStoreStorageNameBuilder? storageNameBuilder = null, IAggregateValidator? validator = null, IAggregateIdFactory? aggregateIdFactory = null, - IEventUpcasterRegistry? eventUpcasterRegistry = null + IEventUpcasterRegistry? eventUpcasterRegistry = null, + IEventStorePrincipalAccessor? principalAccessor = null, + IEventStoreMetrics? metrics = null, + ICurrentTenant? currentTenant = null, + IEventPayloadProtector? payloadProtector = null ) { _eventNameMapper = eventNameMapper; @@ -92,6 +110,10 @@ public MongoDBEventStore( _aggregateChangeNotifier = aggregateChangeNotifier; _aggregateRequirementsManager = aggregateRequirementsManager; _eventUpcasterRegistry = eventUpcasterRegistry; + _principalAccessor = principalAccessor ?? new AmbientEventStorePrincipalAccessor(); + _metrics = metrics ?? NoOpEventStoreMetrics.Instance; + _currentTenant = currentTenant ?? new SystemCurrentTenant(); + _payloadProtector = payloadProtector; _aggregateTypeShortName = typeof(T).Name; _aggregateTypeFullName = typeof(T).FullName ?? _aggregateTypeShortName; @@ -112,7 +134,8 @@ public MongoDBEventStore( ?? $"es-{_aggregateTypeShortName}-events", ConnectionString = mongoDbOptions.Value.ConnectionString, ReplicaName = mongoDbOptions.Value.ReplicaName, - } + }, + currentTenant: _currentTenant ); _snapshotClient = new( @@ -127,7 +150,8 @@ public MongoDBEventStore( ?? $"es-{_aggregateTypeShortName}-snapshots", ConnectionString = mongoDbOptions.Value.ConnectionString, ReplicaName = mongoDbOptions.Value.ReplicaName, - } + }, + currentTenant: _currentTenant ); } @@ -253,27 +277,12 @@ CancellationToken cancellationToken return result; } - static bool ReturnAggregate(bool isDeleted, string aggregateId, EventStoreOperationContext context) - { - if (isDeleted) - { -#pragma warning disable IDE0010 // Add missing cases - switch (context.DeleteMode) - { - case DeleteHandlingMode.ThrowsException: - throw AggregateIsDeletedException(aggregateId); - case DeleteHandlingMode.ReturnsNull: - return false; - } -#pragma warning restore IDE0010 // Add missing cases - } - - return true; - } + static bool ReturnAggregate(bool isDeleted, EventStoreOperationContext context) => + !isDeleted || context.DeleteMode == DeleteHandlingMode.ReturnsAggregate; string CreateStreamVersionId(string aggregateId) => $"s_{_aggregateTypeShortName}_{aggregateId}"; - string CreateEventId(string aggregateId, int version) => + string CreateEventId(string aggregateId, long version) => $"e_{_aggregateTypeShortName}_{aggregateId}_{$"{version}".PadLeft(_eventStoreOptions.Value.EventSuffixLength, '0')}"; string CreateIdempotencyCheckId(string aggregateId, string idempotencyId) => @@ -286,7 +295,18 @@ string CreateIdempotencyCheckId(string aggregateId, string idempotencyId) => /// The identifier of the aggregate. /// The case-insensitive cache key used to store and retrieve the aggregate snapshot. public string CreateCacheKey(string aggregateId) => - $"{_aggregateTypeShortName}:{aggregateId}{AggregateSnapshotSchema.GetStorageSuffix()}".ToLowerInvariant(); + $"{TenantCacheScope()}{_aggregateTypeShortName}:{aggregateId}{AggregateSnapshotSchema.GetStorageSuffix()}".ToLowerInvariant(); + + /// + /// Namespaces a cache key by tenant. + /// + /// + /// The distributed cache is read before the tenant-filtered storage lookup, so an unqualified key + /// would let one tenant read another's cached aggregate straight out of a shared cache, bypassing + /// every storage filter. The system scope keeps the unqualified key, matching unowned rows. + /// + /// The tenant prefix, or an empty string under the system scope. + string TenantCacheScope() => _currentTenant.Current.IsSystem ? string.Empty : $"{_currentTenant.Current.TenantId}:"; #pragma warning restore CA1308 // Normalize strings to uppercase /// diff --git a/src/src/MongoDB/MongoDB.csproj b/src/src/MongoDB/MongoDB.csproj index c665bbb1..24d6fde3 100644 --- a/src/src/MongoDB/MongoDB.csproj +++ b/src/src/MongoDB/MongoDB.csproj @@ -1,4 +1,4 @@ - + true Purview Event Store for MongoDB @@ -14,8 +14,6 @@ - - diff --git a/src/src/MongoDB/Snapshots/MongoDBSnapshotEventStore.EventStore.cs b/src/src/MongoDB/Snapshots/MongoDBSnapshotEventStore.EventStore.cs index d17a9239..17035b4e 100644 --- a/src/src/MongoDB/Snapshots/MongoDBSnapshotEventStore.EventStore.cs +++ b/src/src/MongoDB/Snapshots/MongoDBSnapshotEventStore.EventStore.cs @@ -1,5 +1,7 @@ using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Snapshotting; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.MongoDB.Snapshots; @@ -10,29 +12,29 @@ public Task CreateAsync(string? aggregateId = null, CancellationToken cancell _eventStore.CreateAsync(aggregateId, cancellationToken); /// - public Task GetOrCreateAsync( + public Task> GetOrCreateAsync( string? aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => _eventStore.GetOrCreateAsync(aggregateId, operationContext, cancellationToken); /// - public Task GetAsync( + public Task> GetAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => _eventStore.GetAsync(aggregateId, operationContext, cancellationToken); /// - public Task GetAtAsync( + public Task> GetAtAsync( string aggregateId, - int version, + long version, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => _eventStore.GetAtAsync(aggregateId, version, operationContext, cancellationToken); /// - public async Task> SaveAsync( + public async Task, AggregateSaveFailure>> SaveAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -43,8 +45,8 @@ public async Task> SaveAsync( var eventsApplied = aggregate.GetUnsavedEvents().Count; var result = await _eventStore.SaveAsync(aggregate, operationContext, cancellationToken); if ( - result - && !result.Skipped + result.IsSuccess + && result.Value.Written && SnapshotStrategyResolver.ShouldSnapshot( aggregate, eventsApplied, @@ -59,36 +61,34 @@ public async Task> SaveAsync( } /// - public Task IsDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) => - _eventStore.IsDeletedAsync(aggregateId, cancellationToken); - - /// - public Task GetDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) => - _eventStore.GetDeletedAsync(aggregateId, cancellationToken); + public Task> GetDeletedAsync( + string aggregateId, + CancellationToken cancellationToken = default + ) => _eventStore.GetDeletedAsync(aggregateId, cancellationToken); /// - public async Task DeleteAsync( + public async Task, AggregateDeleteFailure>> DeleteAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) { var result = await _eventStore.DeleteAsync(aggregate, operationContext, cancellationToken); - if (result) + if (result.IsSuccess) await _mongoDBClient.DeleteAsync(BuildPredicate(aggregate), cancellationToken); return result; } /// - public async Task RestoreAsync( + public async Task, AggregateRestoreFailure>> RestoreAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) { var result = await _eventStore.RestoreAsync(aggregate, operationContext, cancellationToken); - if (result) + if (result.IsSuccess) await _mongoDBClient.UpsertAsync(aggregate, BuildPredicate(aggregate), cancellationToken); return result; @@ -101,7 +101,7 @@ public IAsyncEnumerable GetAggregateIdsAsync( ) => _eventStore.GetAggregateIdsAsync(includeDeleted, cancellationToken); /// - public Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) => + public Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) => _eventStore.ExistsAsync(aggregateId, cancellationToken); /// @@ -110,8 +110,8 @@ public Task ExistsAsync(string aggregateId, CancellationToken cance /// public IAsyncEnumerable<(EventRecord EventRecord, string EventType)> GetEventRangeAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, CancellationToken cancellationToken ) => _eventStore.GetEventRangeAsync(aggregateId, versionFrom, versionTo, cancellationToken); } diff --git a/src/src/MongoDB/Snapshots/MongoDBSnapshotEventStore.cs b/src/src/MongoDB/Snapshots/MongoDBSnapshotEventStore.cs index 2dea83ec..7c87a9a1 100644 --- a/src/src/MongoDB/Snapshots/MongoDBSnapshotEventStore.cs +++ b/src/src/MongoDB/Snapshots/MongoDBSnapshotEventStore.cs @@ -3,6 +3,7 @@ using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Snapshotting; using Purview.EventSourcing.MongoDB.StorageClient; +using Purview.EventSourcing.Tenancy; namespace Purview.EventSourcing.MongoDB.Snapshots; @@ -38,13 +39,15 @@ public sealed partial class MongoDBSnapshotEventStore : IMongoDBSnapshotEvent /// The telemetry contract used to trace MongoDB client operations. /// Optional strategy controlling when snapshots are taken; defaults to always snapshotting. /// Optional selector used to resolve the snapshot strategy for an operation. + /// Optional tenant scope applied to snapshot reads and writes. public MongoDBSnapshotEventStore( Internal.INonQueryableEventStore eventStore, IOptions mongoDbOptions, IMongoDBSnapshotEventStoreTelemetry telemetry, IMongoDBClientTelemetry mongoDBClientTelemetry, ISnapshotStrategy? snapshotStrategy = null, - ISnapshotStrategySelector? snapshotStrategySelector = null + ISnapshotStrategySelector? snapshotStrategySelector = null, + ICurrentTenant? currentTenant = null ) { _eventStore = eventStore; @@ -63,7 +66,8 @@ public MongoDBSnapshotEventStore( Database = _mongoDBOptions.Value.Database, Collection = collectionName, ApplicationName = _mongoDBOptions.Value.ApplicationName, - } + }, + currentTenant: currentTenant ); } diff --git a/src/src/MongoDB/StorageClient/IEntity.cs b/src/src/MongoDB/StorageClient/IEntity.cs index e48d57cd..97f18e0e 100644 --- a/src/src/MongoDB/StorageClient/IEntity.cs +++ b/src/src/MongoDB/StorageClient/IEntity.cs @@ -1,4 +1,4 @@ -namespace Purview.EventSourcing.MongoDB.StorageClient; +namespace Purview.EventSourcing.MongoDB.StorageClient; interface IEntity { @@ -7,4 +7,6 @@ interface IEntity string AggregateId { get; set; } int EntityType { get; } + + string? TenantId { get; set; } } diff --git a/src/src/MongoDB/StorageClient/MongoDBClient.MongoDBSpecific.cs b/src/src/MongoDB/StorageClient/MongoDBClient.MongoDBSpecific.cs index ca8a5b3e..ec408ab7 100644 --- a/src/src/MongoDB/StorageClient/MongoDBClient.MongoDBSpecific.cs +++ b/src/src/MongoDB/StorageClient/MongoDBClient.MongoDBSpecific.cs @@ -37,12 +37,12 @@ await session.WithTransactionAsync( case TransactionActionType.Insert: await collection.InsertOneAsync( session, - op.Document.ToBsonDocument(), + Stamp(op.Document).ToBsonDocument(), cancellationToken: cancellationToken ); break; case TransactionActionType.Update: - var d = op.Document.ToBsonDocument(); + var d = Stamp(op.Document).ToBsonDocument(); d.Remove("_id"); await collection.ReplaceOneAsync( @@ -145,7 +145,7 @@ await session.WithTransactionAsync( } } - static async Task SubmitBatchWithoutTransactionAsync( + async Task SubmitBatchWithoutTransactionAsync( IMongoCollection collection, IEnumerable actions, CancellationToken cancellationToken @@ -157,10 +157,13 @@ CancellationToken cancellationToken switch (op.ActionType) { case TransactionActionType.Insert: - await collection.InsertOneAsync(op.Document.ToBsonDocument(), cancellationToken: cancellationToken); + await collection.InsertOneAsync( + Stamp(op.Document).ToBsonDocument(), + cancellationToken: cancellationToken + ); break; case TransactionActionType.Update: - var d = op.Document.ToBsonDocument(); + var d = Stamp(op.Document).ToBsonDocument(); d.Remove("_id"); await collection.ReplaceOneAsync( m => m["_id"] == op.Document.Id, @@ -184,7 +187,11 @@ await collection.DeleteOneAsync( where T : class { var collection = GetCollection(); - var findResult = await collection.FindAsync(predicate, new FindOptions { Limit = 1 }, cancellationToken); + var findResult = await collection.FindAsync( + Scoped(predicate), + new FindOptions { Limit = 1 }, + cancellationToken + ); return await findResult.SingleOrDefaultAsync(cancellationToken); } @@ -201,7 +208,7 @@ await collection.DeleteOneAsync( var collection = GetCollection(); var result = await collection.FindAsync( - predicate, + Scoped(predicate), options: new() { Limit = 1 }, cancellationToken: cancellationToken ); @@ -224,7 +231,7 @@ public async Task UpsertAsync( var collection = GetCollection(); var result = await collection.ReplaceOneAsync( predicate, - document, + Stamp(document), new ReplaceOptions { IsUpsert = true, BypassDocumentValidation = true }, cancellationToken ); @@ -242,7 +249,7 @@ public async Task UpsertAsync( var result = await collection.ReplaceOneAsync( predicate, - document, + Stamp(document), new ReplaceOptions { IsUpsert = true }, cancellationToken ); @@ -273,7 +280,7 @@ public async Task DeleteAsync(Expression> predicate, Cancellati { var collection = GetCollection(); - await collection.DeleteOneAsync(predicate, cancellationToken); + await collection.DeleteOneAsync(Scoped(predicate), cancellationToken); } public async Task DeleteAsync(FilterDefinition predicate, CancellationToken cancellationToken = default) @@ -281,7 +288,7 @@ public async Task DeleteAsync(FilterDefinition predicate, CancellationToke { var collection = GetCollection(); - await collection.DeleteOneAsync(predicate, cancellationToken); + await collection.DeleteOneAsync(Scoped(predicate), cancellationToken); } public async Task DeleteManyAsync( diff --git a/src/src/MongoDB/StorageClient/MongoDBClient.cs b/src/src/MongoDB/StorageClient/MongoDBClient.cs index aeb89aa3..7f1ff667 100644 --- a/src/src/MongoDB/StorageClient/MongoDBClient.cs +++ b/src/src/MongoDB/StorageClient/MongoDBClient.cs @@ -4,6 +4,7 @@ using MongoDB.Bson.Serialization.IdGenerators; using MongoDB.Bson.Serialization.Serializers; using MongoDB.Driver; +using Purview.EventSourcing.Tenancy; namespace Purview.EventSourcing.MongoDB.StorageClient; @@ -17,6 +18,44 @@ sealed partial class MongoDBClient : IDisposable readonly string _collectionName; + readonly ICurrentTenant _currentTenant; + + /// + /// Narrows a filter to the current tenant. + /// + /// + /// Applied by every read and delete rather than by each caller: a query that forgets the tenant is the + /// failure this exists to prevent. A document with no recorded owner stays visible, so data written + /// before tenancy was configured is still readable. + /// + /// + /// Records the current tenant on a document before it is written. + /// + /// + /// Applied centrally so a new write path cannot omit it; an unstamped document would then be hidden + /// from its own tenant by . + /// + T Stamp(T document) + { + if (document is IEntity entity) + entity.TenantId = _currentTenant.Current.TenantId; + + return document; + } + + FilterDefinition Scoped(FilterDefinition predicate) + { + var scope = _currentTenant.Current; + if (scope.IsSystem) + return predicate; + + FilterDefinitionBuilder builder = new(); + + // An unowned document is visible only to the system scope: treating it as visible to every + // tenant would turn a missed stamp on any write path into silent cross-tenant exposure. + return builder.And(predicate, builder.Eq(nameof(IEntity.TenantId), scope.TenantId)); + } + static readonly Lazy Initialized = new(Init); #if EventsBasedStore @@ -74,11 +113,13 @@ public MongoDBClient( IMongoDBClientTelemetry telemetry, MongoDBConfiguration configuration, string? databaseOverride = null, - string? collectionOverride = null + string? collectionOverride = null, + ICurrentTenant? currentTenant = null ) { _telemetry = telemetry; _configuration = configuration; + _currentTenant = currentTenant ?? new SystemCurrentTenant(); var settings = MongoClientSettings.FromConnectionString(configuration.ConnectionString); settings.ApplicationName = configuration.ApplicationName; diff --git a/src/src/Postgres/Client/JsonScalarValueConverter.cs b/src/src/Postgres/Client/JsonScalarValueConverter.cs deleted file mode 100644 index 5518fab9..00000000 --- a/src/src/Postgres/Client/JsonScalarValueConverter.cs +++ /dev/null @@ -1,114 +0,0 @@ -using System.Linq.Expressions; -using System.Reflection; -using System.Text.Json; -using Microsoft.EntityFrameworkCore.Storage.ValueConversion; -using Purview.ValueObjects.Serialization; - -namespace Purview.EventSourcing.Postgres.Client; - -/// -/// Converts a -annotated value object whose scalar property is a complex type -/// to and from its JSON-serialized string representation for storage in PostgreSQL. -/// -/// The value object type annotated with . -/// The scalar property type of . -sealed class JsonScalarValueConverter : ValueConverter -{ - static readonly PropertyInfo ScalarProperty = GetScalarProperty(); - static readonly Func Creator = BuildCreator(); - - /// - /// Creates a new . - /// - public JsonScalarValueConverter() - : base(BuildToProviderExpression(), BuildFromProviderExpression()) { } - - static Expression> BuildToProviderExpression() - { - var source = Expression.Parameter(typeof(TScalarObject), "value"); - var serializeMethod = typeof(JsonScalarValueConverter).GetMethod( - nameof(Serialize), - BindingFlags.Static | BindingFlags.NonPublic - )!; - var body = Expression.Call(serializeMethod, source); - return Expression.Lambda>(body, source); - } - - static Expression> BuildFromProviderExpression() - { - var source = Expression.Parameter(typeof(string), "value"); - var deserializeMethod = typeof(JsonScalarValueConverter).GetMethod( - nameof(Deserialize), - BindingFlags.Static | BindingFlags.NonPublic - )!; - var body = Expression.Call(deserializeMethod, source); - return Expression.Lambda>(body, source); - } - - static string Serialize(TScalarObject value) - { - if (value is null) - return null!; - - var scalarValue = (TScalar)ScalarProperty.GetValue(value)!; - return JsonSerializer.Serialize(scalarValue); - } - - static TScalarObject Deserialize(string value) - { - if (value is null) - return default!; - - var scalarValue = JsonSerializer.Deserialize(value)!; - return Creator(scalarValue); - } - - static PropertyInfo GetScalarProperty() - { - var scalarType = typeof(TScalarObject); - var scalarAttribute = - scalarType.GetCustomAttribute() - ?? throw new InvalidOperationException($"{scalarType.Name} must be annotated with [Scalar]."); - - return scalarType.GetProperty(scalarAttribute.PropertyName, BindingFlags.Instance | BindingFlags.Public) - ?? throw new InvalidOperationException( - $"'{scalarType.Name}' missing scalar property '{scalarAttribute.PropertyName}'." - ); - } - - static Func BuildCreator() - { - var scalarType = typeof(TScalarObject); - var scalarPropertyType = typeof(TScalar); - var scalarAttribute = - scalarType.GetCustomAttribute() - ?? throw new InvalidOperationException($"{scalarType.Name} must be annotated with [Scalar]."); - - var preferredFactoryName = - scalarAttribute.DeserializationMode == ValueObjectDeserializationMode.Strict ? "Create" : "Hydrate"; - var secondaryFactoryName = preferredFactoryName == "Hydrate" ? "Create" : "Hydrate"; - - var create = - scalarType.GetMethod(preferredFactoryName, BindingFlags.Public | BindingFlags.Static, [scalarPropertyType]) - ?? scalarType.GetMethod( - secondaryFactoryName, - BindingFlags.Public | BindingFlags.Static, - [scalarPropertyType] - ); - - if (create is not null) - return value => (TScalarObject)create.Invoke(null, [value])!; - - var ctor = - scalarType.GetConstructor( - BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic, - [scalarPropertyType] - ) - ?? throw new InvalidOperationException( - $"{scalarType.Name} must expose static {preferredFactoryName}({scalarPropertyType.Name}), static {secondaryFactoryName}({scalarPropertyType.Name}), or ctor({scalarPropertyType.Name})." - ); - - // If we reach here, we have a constructor that takes the scalar property type - return value => (TScalarObject)ctor.Invoke([value]); - } -} diff --git a/src/src/Postgres/Client/Models.cs b/src/src/Postgres/Client/Models.cs index fd3eaaaa..109ff177 100644 --- a/src/src/Postgres/Client/Models.cs +++ b/src/src/Postgres/Client/Models.cs @@ -1,6 +1,6 @@ namespace Purview.EventSourcing.Postgres.Client; -sealed record SnapshotStorageRow(string Id, string AggregateType, string Payload); +sealed record SnapshotStorageRow(string Id, string AggregateType, string Payload, string? TenantId = null); sealed class SnapshotQueryRow where TAggregate : class @@ -10,6 +10,11 @@ sealed class SnapshotQueryRow public required string AggregateType { get; set; } public required TAggregate Payload { get; set; } + + /// + /// The tenant that owns the snapshot; null in a single-tenant deployment. + /// + public string? TenantId { get; set; } } sealed record PostgresClientOptions(string ConnectionString, bool UseDataCompression) diff --git a/src/src/Postgres/Client/PostgresClient.cs b/src/src/Postgres/Client/PostgresClient.cs index 7b0c3803..e23c2f13 100644 --- a/src/src/Postgres/Client/PostgresClient.cs +++ b/src/src/Postgres/Client/PostgresClient.cs @@ -1,14 +1,13 @@ using System.Collections.Concurrent; using System.Linq.Expressions; -using System.Reflection; using System.Text.RegularExpressions; using Microsoft.EntityFrameworkCore; using Microsoft.EntityFrameworkCore.Infrastructure; -using Microsoft.EntityFrameworkCore.Metadata.Builders; using Microsoft.EntityFrameworkCore.Storage; using Npgsql; -using Purview.EventSourcing.Aggregates; -using Purview.ValueObjects.Serialization; +using Purview.EventSourcing.EntityFrameworkCore.Mapping; +using Purview.EventSourcing.EntityFrameworkCore.Query; +using Purview.EventSourcing.Tenancy; namespace Purview.EventSourcing.Postgres.Client; @@ -17,18 +16,16 @@ sealed partial class PostgresClient static readonly ConcurrentDictionary EnsureTableLocks = new(StringComparer.Ordinal); static readonly ConcurrentDictionary EnsuredTables = new(StringComparer.Ordinal); - // Must match the attribute emitted by Purview.EventSourcing.EntityFrameworkCore.SourceGenerator - // (TypeLibrary.EFOpaqueAttribute) and applied by consumers as [EFOpaque]. - const string EFOpaqueAttributeFullName = "Purview.EventSourcing.EntityFrameworkCore.EFOpaqueAttribute"; - static readonly HashSet SupportedSnapshotIncludeColumns = ["Id", "AggregateType", "Payload"]; readonly PostgresClientOptions _options; + readonly ICurrentTenant _currentTenant; readonly string _tableEnsureKey; - public PostgresClient(PostgresClientOptions options) + public PostgresClient(PostgresClientOptions options, ICurrentTenant? currentTenant = null) { _options = options ?? throw new ArgumentNullException(nameof(options)); + _currentTenant = currentTenant ?? new SystemCurrentTenant(); _tableEnsureKey = $"{_options.ConnectionString}|{_options.SchemaName}|{_options.TableName}"; ValidateIdentifier(_options.SchemaName); @@ -144,7 +141,7 @@ public async Task> QueryByAggregateTypeAsync( await EnsureTableIfEnabledAsync(cancellationToken); var normalizedWhereClause = whereClause is null ? null - : RewriteAggregateTypePredicate(whereClause, aggregateType); + : SnapshotPredicateRewriter.Rewrite(whereClause, aggregateType); var rowQuery = context.Snapshots.AsNoTracking().AsSplitQuery().Where(s => s.AggregateType == aggregateType); @@ -155,7 +152,7 @@ public async Task> QueryByAggregateTypeAsync( if (orderByClause != null) { aggregateQuery = orderByClause(aggregateQuery); - EnsureSupportedOrderByExpression(aggregateQuery.Expression); + SnapshotPredicateRewriter.EnsureSupportedOrderByExpression(aggregateQuery.Expression); } var page = aggregateQuery.Skip(Math.Max(0, skipCount)).Take(Math.Max(0, takeCount)); @@ -176,22 +173,26 @@ public async Task> QueryByAggregateTypeJsonContainsAsync( await EnsureTableIfEnabledAsync(cancellationToken); var sql = $""" - SELECT "Id", "AggregateType", "Payload" + SELECT "Id" FROM {QuoteIdentifier(_options.SchemaName)}.{QuoteIdentifier(_options.TableName)} WHERE "AggregateType" = @aggregateType AND "Payload" @> CAST(@jsonFragment AS jsonb) + ORDER BY "Id" + OFFSET @skipCount LIMIT @takeCount """; NpgsqlParameter aggregateTypeParameter = new("aggregateType", aggregateType); NpgsqlParameter jsonFragmentParameter = new("jsonFragment", jsonFragment); - var query = context - .Snapshots.FromSqlRaw(sql, aggregateTypeParameter, jsonFragmentParameter) - .AsNoTracking() - .OrderBy(static s => s.Id) - .Select(static s => s.Payload) - .Skip(Math.Max(0, skipCount)) - .Take(Math.Max(0, takeCount)); - - return await query.ToListAsync(cancellationToken); + var ids = await context + .Database.SqlQueryRaw( + sql, + aggregateTypeParameter, + jsonFragmentParameter, + new NpgsqlParameter("skipCount", Math.Max(0, skipCount)), + new NpgsqlParameter("takeCount", Math.Max(0, takeCount)) + ) + .ToListAsync(cancellationToken); + + return await LoadPayloadsByIdAsync(context, ids, cancellationToken); } public async Task> QueryByAggregateTypeJsonExistsAsync( @@ -208,22 +209,50 @@ public async Task> QueryByAggregateTypeJsonExistsAsync( await EnsureTableIfEnabledAsync(cancellationToken); var sql = $""" - SELECT "Id", "AggregateType", "Payload" + SELECT "Id" FROM {QuoteIdentifier(_options.SchemaName)}.{QuoteIdentifier(_options.TableName)} WHERE "AggregateType" = @aggregateType AND "Payload" ? @payloadKey + ORDER BY "Id" + OFFSET @skipCount LIMIT @takeCount """; NpgsqlParameter aggregateTypeParameter = new("aggregateType", aggregateType); NpgsqlParameter keyParameter = new("payloadKey", key); - var query = context - .Snapshots.FromSqlRaw(sql, aggregateTypeParameter, keyParameter) - .AsNoTracking() - .OrderBy(static s => s.Id) - .Select(static s => s.Payload) - .Skip(Math.Max(0, skipCount)) - .Take(Math.Max(0, takeCount)); - - return await query.ToListAsync(cancellationToken); + var ids = await context + .Database.SqlQueryRaw( + sql, + aggregateTypeParameter, + keyParameter, + new NpgsqlParameter("skipCount", Math.Max(0, skipCount)), + new NpgsqlParameter("takeCount", Math.Max(0, takeCount)) + ) + .ToListAsync(cancellationToken); + + return await LoadPayloadsByIdAsync(context, ids, cancellationToken); + } + + // EF cannot shape a complex JSON property over a FromSqlRaw source - it throws inside + // GenerateComplexJsonShaper - so the raw query selects ids and the payloads load through the model. + static async Task> LoadPayloadsByIdAsync( + SnapshotQueryDBContext context, + List orderedIds, + CancellationToken cancellationToken + ) + where T : class + { + if (orderedIds.Count == 0) + return []; + + var rows = await context + .Snapshots.AsNoTracking() + .Where(s => orderedIds.Contains(s.Id)) + .Select(static s => new { s.Id, s.Payload }) + .ToListAsync(cancellationToken); + + var payloadsById = rows.ToDictionary(static row => row.Id, static row => row.Payload, StringComparer.Ordinal); + + // The raw query already ordered and paged; preserve that order. + return [.. orderedIds.Where(payloadsById.ContainsKey).Select(id => payloadsById[id])]; } public async Task GetByIdAsync(string id, CancellationToken cancellationToken = default) @@ -247,7 +276,7 @@ static IQueryable BuildAggregateQuery( .Where(s => s.AggregateType == aggregateType) .Select(s => s.Payload); - return whereClause is null ? query : query.Where(RewriteAggregateTypePredicate(whereClause, aggregateType)); + return whereClause is null ? query : query.Where(SnapshotPredicateRewriter.Rewrite(whereClause, aggregateType)); } static async Task UpsertAsync( @@ -266,6 +295,9 @@ CancellationToken cancellationToken Id = id, AggregateType = aggregateType, Payload = aggregate, + // Stamped from the context that will write it, so a snapshot cannot be saved without an + // owner and then be hidden from its own tenant by the query filter. + TenantId = context.TenantId, }; if (exists) @@ -276,9 +308,10 @@ CancellationToken cancellationToken return await context.SaveChangesAsync(cancellationToken) > 0; } - SnapshotStorageDBContext CreateStorageContext() => new(_options); + SnapshotStorageDBContext CreateStorageContext() => new(_options, _currentTenant); - SnapshotStorageDBContext CreateStorageContext(NpgsqlConnection connection) => new(_options, connection); + SnapshotStorageDBContext CreateStorageContext(NpgsqlConnection connection) => + new(_options, connection, _currentTenant); SnapshotQueryDBContext CreateQueryContext() where T : class => new(_options); @@ -300,24 +333,48 @@ static void ValidateIdentifier(string identifier) [GeneratedRegex(@"^[\w\-\.]+$")] private static partial Regex IdentifierRegex(); - sealed class SnapshotStorageDBContext : DbContext + sealed class SnapshotStorageDBContext : DbContext, ISnapshotModelCacheKeySource { readonly PostgresClientOptions _options; readonly NpgsqlConnection? _connection; - public SnapshotStorageDBContext(PostgresClientOptions options) + // Captured once per context: a context is scoped to one operation, and EF only re-evaluates + // plain context fields when it reuses the cached model. + bool _crossesTenants = true; + string? _tenantId; + + /// The tenant owning rows written through this context. + public string? TenantId => _tenantId; + + void SetTenant(ICurrentTenant? currentTenant) + { + var scope = (currentTenant ?? new SystemCurrentTenant()).Current; + _crossesTenants = scope.IsSystem; + _tenantId = scope.TenantId; + } + + public SnapshotStorageDBContext(PostgresClientOptions options, ICurrentTenant? currentTenant = null) { _options = options; + SetTenant(currentTenant); } - public SnapshotStorageDBContext(PostgresClientOptions options, NpgsqlConnection connection) + public SnapshotStorageDBContext( + PostgresClientOptions options, + NpgsqlConnection connection, + ICurrentTenant? currentTenant = null + ) { _options = options; _connection = connection; + SetTenant(currentTenant); } public DbSet Snapshots => Set(); + public object CreateModelCacheKey(bool designTime) => + (typeof(SnapshotStorageDBContext), _options.SchemaName, _options.TableName, designTime); + protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) { if (_connection is null) @@ -336,32 +393,63 @@ protected override void OnModelCreating(ModelBuilder modelBuilder) entity.Property(x => x.Id).HasMaxLength(450); entity.Property(x => x.AggregateType).HasMaxLength(450); entity.Property(x => x.Payload).HasColumnType("jsonb"); + entity.Property(x => x.TenantId).HasMaxLength(450); + + // A global filter rather than a per-query predicate: the snapshot store is the queryable + // read model, so a query that forgets the tenant returns another tenant's aggregates. + // An unowned row is visible only to the system scope: treating it as visible to everyone + // would turn a missed stamp on any write path into silent cross-tenant exposure. + entity.HasQueryFilter(x => _crossesTenants || x.TenantId == _tenantId); entity.HasIndex(x => x.AggregateType); } } - sealed class SnapshotQueryDBContext : DbContext + sealed class SnapshotQueryDBContext : DbContext, ISnapshotModelCacheKeySource where TAggregate : class { readonly PostgresClientOptions _options; readonly NpgsqlConnection? _connection; - public SnapshotQueryDBContext(PostgresClientOptions options) + // Captured once per context: a context is scoped to one operation, and EF only re-evaluates + // plain context fields when it reuses the cached model. + bool _crossesTenants = true; + string? _tenantId; + + /// The tenant owning rows written through this context. + public string? TenantId => _tenantId; + + void SetTenant(ICurrentTenant? currentTenant) + { + var scope = (currentTenant ?? new SystemCurrentTenant()).Current; + _crossesTenants = scope.IsSystem; + _tenantId = scope.TenantId; + } + + public SnapshotQueryDBContext(PostgresClientOptions options, ICurrentTenant? currentTenant = null) { _options = options; + SetTenant(currentTenant); } - public SnapshotQueryDBContext(PostgresClientOptions options, NpgsqlConnection connection) + public SnapshotQueryDBContext( + PostgresClientOptions options, + NpgsqlConnection connection, + ICurrentTenant? currentTenant = null + ) { _options = options; _connection = connection; + SetTenant(currentTenant); } public DbSet> Snapshots => Set>(); + public object CreateModelCacheKey(bool designTime) => + (typeof(SnapshotQueryDBContext<>), typeof(TAggregate), _options.SchemaName, _options.TableName, designTime); + protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder) { - RegisterScalarValueObjectConversions(configurationBuilder, typeof(TAggregate)); + SnapshotModelMapper.RegisterScalarValueObjectConversions(configurationBuilder, typeof(TAggregate)); } protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) @@ -391,793 +479,25 @@ protected override void OnModelCreating(ModelBuilder modelBuilder) entity.Property(static x => x.Id).HasMaxLength(450); entity.Property(static x => x.AggregateType).HasMaxLength(450); entity.HasIndex(static x => x.AggregateType); - ValidateAggregatePayloadShape(typeof(TAggregate)); + entity.Property(x => x.TenantId).HasMaxLength(450); + + // A global filter rather than a per-query predicate: the snapshot store is the queryable + // read model, so a query that forgets the tenant returns another tenant's aggregates. + // An unowned row is visible only to the system scope: treating it as visible to everyone + // would turn a missed stamp on any write path into silent cross-tenant exposure. + entity.HasQueryFilter(x => _crossesTenants || x.TenantId == _tenantId); + SnapshotModelMapper.ValidateAggregatePayloadShape(typeof(TAggregate)); entity.ComplexProperty( static x => x.Payload, static payload => { payload.ToJson(); - ConfigureComplexGraph(payload, typeof(TAggregate)); + SnapshotModelMapper.ConfigureGraph(SnapshotGraphBuilder.For(payload), typeof(TAggregate)); } ); } } - static void RegisterScalarValueObjectConversions(ModelConfigurationBuilder configurationBuilder, Type rootType) - { - HashSet visited = []; - RegisterScalarValueObjectConversionsRecursive(configurationBuilder, rootType, visited); - } - - static void RegisterScalarValueObjectConversionsRecursive( - ModelConfigurationBuilder configurationBuilder, - Type type, - HashSet visited - ) - { - type = Nullable.GetUnderlyingType(type) ?? type; - if (!visited.Add(type)) - return; - - var scalarAttribute = type.GetCustomAttribute(); - if (scalarAttribute is not null) - { - RegisterScalarValueObjectConversion(configurationBuilder, type, scalarAttribute); - return; - } - - if (!ShouldInspectType(type)) - return; - - foreach (var property in type.GetProperties(BindingFlags.Instance | BindingFlags.Public)) - { - var propertyType = Nullable.GetUnderlyingType(property.PropertyType) ?? property.PropertyType; - - if (propertyType == typeof(string) || propertyType == typeof(byte[])) - continue; - - if (TryGetEnumerableElementType(propertyType, out var elementType)) - { - RegisterScalarValueObjectConversionsRecursive(configurationBuilder, elementType, visited); - continue; - } - - RegisterScalarValueObjectConversionsRecursive(configurationBuilder, propertyType, visited); - } - } - - static void RegisterScalarValueObjectConversion( - ModelConfigurationBuilder configurationBuilder, - Type scalarType, - ScalarAttribute scalarAttribute - ) - { - var scalarProperty = - scalarType.GetProperty(scalarAttribute.PropertyName, BindingFlags.Instance | BindingFlags.Public) - ?? throw new InvalidOperationException( - $"'{scalarType.Name}' missing scalar property '{scalarAttribute.PropertyName}'." - ); - - var scalarPropertyType = scalarProperty.PropertyType; - var converterType = IsPrimitiveLike(scalarPropertyType) - ? typeof(ScalarValueConverter<,>).MakeGenericType(scalarType, scalarPropertyType) - : typeof(JsonScalarValueConverter<,>).MakeGenericType(scalarType, scalarPropertyType); - configurationBuilder.Properties(scalarType, builder => builder.HaveConversion(converterType)); - } - - static void ConfigureComplexGraph(ComplexPropertyBuilder builder, Type type) - { - HashSet visited = []; - ConfigureComplexGraphRecursive(builder, type, visited); - } - - static void ConfigureComplexGraphRecursive(ComplexPropertyBuilder builder, Type type, HashSet visited) - { - type = Nullable.GetUnderlyingType(type) ?? type; - if (!ShouldInspectType(type) || !visited.Add(type)) - return; - - foreach (var property in type.GetProperties(BindingFlags.Instance | BindingFlags.Public)) - { - if (ShouldSkipJsonProperty(type, property)) - { - builder.Ignore(property.Name); - continue; - } - - var propertyType = Nullable.GetUnderlyingType(property.PropertyType) ?? property.PropertyType; - - if (propertyType == typeof(string) || propertyType == typeof(byte[])) - { - MapReadOnlyConstructorBoundProperty(builder, type, property, propertyType); - continue; - } - - if (propertyType.GetCustomAttribute() is not null) - { - MapReadOnlyConstructorBoundProperty(builder, type, property, propertyType); - continue; - } - - if (HasEfOpaqueAttribute(property)) - { - MapOpaqueJsonProperty(builder, propertyType, property.Name); - continue; - } - - if (TryGetEnumerableElementType(propertyType, out var elementType)) - { - if (!IsEventStoreCollectionType(propertyType)) - throw CreateUnsupportedCollectionTypeException(type, property, propertyType); - - if (IsStructValueObjectType(elementType)) - { - MapCollectionAsJsonProperty(builder, propertyType, property.Name); - continue; - } - - if (IsPrimitiveLike(elementType) || elementType.GetCustomAttribute() is not null) - builder.PrimitiveCollection(propertyType, property.Name); - else if (ShouldInspectType(elementType)) - builder.ComplexCollection( - propertyType, - property.Name, - nested => ConfigureComplexGraphRecursive(nested, elementType, [.. visited]) - ); - else - throw CreateUnsupportedShapeException(type, property); - - continue; - } - - if (IsDictionaryLikeType(propertyType) || IsJsonConvertibleCollectionType(propertyType)) - { - MapJsonProperty(builder, propertyType, property.Name); - continue; - } - - if (IsCollectionLikeType(propertyType)) - throw CreateUnsupportedCollectionTypeException(type, property, propertyType); - - if (ShouldOwnType(propertyType)) - { - builder.ComplexProperty( - propertyType, - property.Name, - nested => ConfigureComplexGraphRecursive(nested, propertyType, [.. visited]) - ); - continue; - } - - if (IsPrimitiveLike(propertyType)) - { - MapReadOnlyConstructorBoundProperty(builder, type, property, propertyType); - continue; - } - - throw CreateUnsupportedShapeException(type, property); - } - } - - static void ConfigureComplexGraphRecursive(ComplexCollectionBuilder builder, Type type, HashSet visited) - { - type = Nullable.GetUnderlyingType(type) ?? type; - if (!ShouldInspectType(type) || !visited.Add(type)) - return; - - foreach (var property in type.GetProperties(BindingFlags.Instance | BindingFlags.Public)) - { - if (ShouldSkipJsonProperty(type, property)) - { - builder.Ignore(property.Name); - continue; - } - - var propertyType = Nullable.GetUnderlyingType(property.PropertyType) ?? property.PropertyType; - - if (propertyType == typeof(string) || propertyType == typeof(byte[])) - { - MapReadOnlyConstructorBoundProperty(builder, type, property, propertyType); - continue; - } - - if (propertyType.GetCustomAttribute() is not null) - { - MapReadOnlyConstructorBoundProperty(builder, type, property, propertyType); - continue; - } - - if (HasEfOpaqueAttribute(property)) - { - MapOpaqueJsonProperty(builder, propertyType, property.Name); - continue; - } - - if (TryGetEnumerableElementType(propertyType, out var elementType)) - { - if (!IsEventStoreCollectionType(propertyType)) - throw CreateUnsupportedCollectionTypeException(type, property, propertyType); - - if (IsStructValueObjectType(elementType)) - { - MapCollectionAsJsonProperty(builder, propertyType, property.Name); - continue; - } - - if (IsPrimitiveLike(elementType) || elementType.GetCustomAttribute() is not null) - builder.PrimitiveCollection(propertyType, property.Name); - else if (ShouldInspectType(elementType)) - builder.ComplexCollection( - propertyType, - property.Name, - nested => ConfigureComplexGraphRecursive(nested, elementType, [.. visited]) - ); - else - throw CreateUnsupportedShapeException(type, property); - - continue; - } - - if (IsDictionaryLikeType(propertyType) || IsJsonConvertibleCollectionType(propertyType)) - { - MapJsonProperty(builder, propertyType, property.Name); - continue; - } - - if (IsCollectionLikeType(propertyType)) - throw CreateUnsupportedCollectionTypeException(type, property, propertyType); - - if (ShouldOwnType(propertyType)) - { - builder.ComplexProperty( - propertyType, - property.Name, - nested => ConfigureComplexGraphRecursive(nested, propertyType, [.. visited]) - ); - continue; - } - - if (IsPrimitiveLike(propertyType)) - { - MapReadOnlyConstructorBoundProperty(builder, type, property, propertyType); - continue; - } - - throw CreateUnsupportedShapeException(type, property); - } - } - - static void MapReadOnlyConstructorBoundProperty( - ComplexPropertyBuilder builder, - Type containingType, - PropertyInfo property, - Type propertyType - ) - { - if (property.GetSetMethod(true) is null && HasBindableConstructorParameter(containingType, property)) - builder.Property(propertyType, property.Name); - } - - static void MapReadOnlyConstructorBoundProperty( - ComplexCollectionBuilder builder, - Type containingType, - PropertyInfo property, - Type propertyType - ) - { - if (property.GetSetMethod(true) is null && HasBindableConstructorParameter(containingType, property)) - builder.Property(propertyType, property.Name); - } - - static void ValidateAggregatePayloadShape(Type type) - { - HashSet visited = []; - ValidateAggregatePayloadShapeRecursive(type, visited); - } - - static void ValidateAggregatePayloadShapeRecursive(Type type, HashSet visited) - { - type = Nullable.GetUnderlyingType(type) ?? type; - if (!ShouldInspectType(type) || !visited.Add(type)) - return; - - foreach (var property in type.GetProperties(BindingFlags.Instance | BindingFlags.Public)) - { - if (ShouldSkipJsonProperty(type, property)) - continue; - - var propertyType = Nullable.GetUnderlyingType(property.PropertyType) ?? property.PropertyType; - - if (propertyType == typeof(string) || propertyType == typeof(byte[])) - continue; - - if (propertyType.GetCustomAttribute() is not null) - continue; - - if (HasEfOpaqueAttribute(property)) - continue; - - if (TryGetEnumerableElementType(propertyType, out var elementType)) - { - if (!IsEventStoreCollectionType(propertyType)) - throw CreateUnsupportedCollectionTypeException(type, property, propertyType); - - if ( - !IsPrimitiveLike(elementType) - && elementType.GetCustomAttribute() is null - && !IsStructValueObjectType(elementType) - ) - { - if (!ShouldInspectType(elementType)) - throw CreateUnsupportedShapeException(type, property); - - EnsureValueTypeMemberIsWritable(type, property); - ValidateAggregatePayloadShapeRecursive(elementType, visited); - } - - continue; - } - - if (IsReadOnlyCollectionType(propertyType)) - throw CreateUnsupportedCollectionTypeException(type, property, propertyType); - - if (IsDictionaryLikeType(propertyType) || IsJsonConvertibleCollectionType(propertyType)) - continue; - - if (IsCollectionLikeType(propertyType)) - throw CreateUnsupportedCollectionTypeException(type, property, propertyType); - - if (ShouldOwnType(propertyType)) - { - EnsureValueTypeMemberIsWritable(type, property); - ValidateAggregatePayloadShapeRecursive(propertyType, visited); - continue; - } - - if (!IsPrimitiveLike(propertyType)) - throw CreateUnsupportedShapeException(type, property); - } - } - - static bool IsStructValueObjectType(Type type) => - type.IsValueType && type.GetCustomAttribute() is not null; - - // EF materializes value-type JSON members through their backing field, and it cannot rebuild an assignment to a - // read-only member while fixing up a value type, which fails snapshot query compilation with - // "Expression must be writeable" (analyzer diagnostic EVENTSTOREEF004). - static void EnsureValueTypeMemberIsWritable(Type type, PropertyInfo property) - { - if (type.IsValueType && property.GetSetMethod(nonPublic: true) is null) - throw CreateUnsupportedValueTypeMemberException(type, property); - } - - static bool HasEfOpaqueAttribute(MemberInfo member) => - member.CustomAttributes.Any(attribute => attribute.AttributeType.FullName == EFOpaqueAttributeFullName); - - static void MapOpaqueJsonProperty(ComplexPropertyBuilder builder, Type propertyType, string propertyName) - { - var propertyBuilder = builder.Property(propertyType, propertyName); - propertyBuilder.HasConversion(typeof(OpaqueJsonValueConverter<>).MakeGenericType(propertyType)); - } - - static void MapOpaqueJsonProperty(ComplexCollectionBuilder builder, Type propertyType, string propertyName) - { - var propertyBuilder = builder.Property(propertyType, propertyName); - propertyBuilder.HasConversion(typeof(OpaqueJsonValueConverter<>).MakeGenericType(propertyType)); - } - - static void MapCollectionAsJsonProperty(ComplexPropertyBuilder builder, Type propertyType, string propertyName) - { - var propertyBuilder = builder.Property(propertyType, propertyName); - var converterType = typeof(JsonValueObjectCollectionConverter<>).MakeGenericType(propertyType); - propertyBuilder.HasConversion(converterType); - } - - static void MapCollectionAsJsonProperty(ComplexCollectionBuilder builder, Type propertyType, string propertyName) - { - var propertyBuilder = builder.Property(propertyType, propertyName); - var converterType = typeof(JsonValueObjectCollectionConverter<>).MakeGenericType(propertyType); - propertyBuilder.HasConversion(converterType); - } - - static void MapJsonProperty(ComplexPropertyBuilder builder, Type propertyType, string propertyName) - { - var propertyBuilder = builder.Property(propertyType, propertyName); - var converterType = typeof(JsonValueObjectCollectionConverter<>).MakeGenericType(propertyType); - propertyBuilder.HasConversion(converterType); - } - - static void MapJsonProperty(ComplexCollectionBuilder builder, Type propertyType, string propertyName) - { - var propertyBuilder = builder.Property(propertyType, propertyName); - var converterType = typeof(JsonValueObjectCollectionConverter<>).MakeGenericType(propertyType); - propertyBuilder.HasConversion(converterType); - } - - static bool ShouldOwnType(Type type) => - !type.IsPrimitive - && !type.IsEnum - && type != typeof(string) - && type != typeof(decimal) - && type != typeof(Guid) - && type != typeof(DateTime) - && type != typeof(DateTimeOffset) - && type != typeof(DateOnly) - && type != typeof(TimeOnly) - && type != typeof(TimeSpan) - && (type.Namespace is null || !type.Namespace.StartsWith("System", StringComparison.Ordinal)) - && (type.IsClass || (type.IsValueType && !type.IsPrimitive && !type.IsEnum)); - - static bool ShouldInspectType(Type type) => - !type.IsPrimitive - && !type.IsEnum - && type != typeof(string) - && type != typeof(decimal) - && type != typeof(Guid) - && type != typeof(DateTime) - && type != typeof(DateTimeOffset) - && type != typeof(DateOnly) - && type != typeof(TimeOnly) - && type != typeof(TimeSpan) - && (type.Namespace is null || !type.Namespace.StartsWith("System", StringComparison.Ordinal)); - - static bool ShouldSkipJsonProperty(Type containingType, PropertyInfo property) => - property.GetCustomAttribute() is not null - || property.GetGetMethod(true) is null - || (property.GetSetMethod(true) is null && !HasBindableConstructorParameter(containingType, property)); - - static bool HasBindableConstructorParameter(Type containingType, PropertyInfo property) - { - var constructors = containingType.GetConstructors( - BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic - ); - foreach (var constructor in constructors) - { - foreach (var parameter in constructor.GetParameters()) - { - if ( - string.Equals(parameter.Name, property.Name, StringComparison.OrdinalIgnoreCase) - && parameter.ParameterType == property.PropertyType - ) - return true; - } - } - - return false; - } - - static bool IsPrimitiveLike(Type type) => - type.IsPrimitive - || type.IsEnum - || type == typeof(string) - || type == typeof(decimal) - || type == typeof(Guid) - || type == typeof(Uri) - || type == typeof(DateTime) - || type == typeof(DateTimeOffset) - || type == typeof(DateOnly) - || type == typeof(TimeOnly) - || type == typeof(TimeSpan) - || type == typeof(byte[]); - - static bool TryGetEnumerableElementType(Type type, out Type elementType) - { - elementType = null!; - - if (!type.IsGenericType) - return false; - - if (!IsEventStoreCollectionType(type)) - return false; - - elementType = type.GetGenericArguments()[0]; - return true; - } - - static bool IsEventStoreCollectionType(Type type) => - type.IsGenericType - && type.GetGenericTypeDefinition() is var genericDefinition - && (genericDefinition == typeof(EventStoreList<>) || genericDefinition == typeof(EventStoreSet<>)); - - static bool IsCollectionLikeType(Type type) - { - if (type == typeof(string) || type == typeof(byte[])) - return false; - - if (type.IsArray) - return true; - - if (!type.IsGenericType) - return false; - - // Test for our own collection types or if the type implements IEnumerable somewhere... - return IsEventStoreCollectionType(type) - || type.GetInterfaces().Any(i => i.IsGenericType && i.GetGenericTypeDefinition() == typeof(IEnumerable<>)); - } - - static bool IsReadOnlyCollectionType(Type type) - { - if (!type.IsGenericType) - return false; - - var genericTypeDefinition = type.GetGenericTypeDefinition(); - return genericTypeDefinition == typeof(IReadOnlyList<>) - || genericTypeDefinition == typeof(IReadOnlyCollection<>); - } - - static bool IsDictionaryLikeType(Type type) - { - if (!type.IsGenericType) - return false; - - var genericTypeDefinition = type.GetGenericTypeDefinition(); - if ( - genericTypeDefinition == typeof(Dictionary<,>) - || genericTypeDefinition == typeof(IDictionary<,>) - || genericTypeDefinition == typeof(IReadOnlyDictionary<,>) - ) - return true; - - // Check if the type implements IDictionary or IReadOnlyDictionary somewhere... - return type.GetInterfaces() - .Any(i => i.IsGenericType && i.GetGenericTypeDefinition() == typeof(IReadOnlyDictionary<,>)); - } - - static bool IsJsonConvertibleCollectionType(Type type) - { - if (type == typeof(string) || type == typeof(byte[])) - return false; - - if (!type.IsGenericType || IsEventStoreCollectionType(type) || IsDictionaryLikeType(type)) - return false; - - if (type.GetGenericTypeDefinition() == typeof(IEnumerable<>)) - return true; - - // Check if the type implements IEnumerable somewhere... - return type.GetInterfaces().Any(i => i.IsGenericType && i.GetGenericTypeDefinition() == typeof(IEnumerable<>)); - } - - static InvalidOperationException CreateUnsupportedShapeException(Type containingType, MemberInfo member) => - new( - $"{containingType.Name}.{member.Name} cannot be mapped into the snapshot JSON payload. " - + "Supported members are primitive types, [Scalar] value objects, complex types, and EventStoreList/EventStoreSet collections of those shapes." - ); - - static InvalidOperationException CreateUnsupportedValueTypeMemberException( - Type containingType, - MemberInfo member - ) => - new( - $"{containingType.Name}.{member.Name} is a read-only complex member of value type '{containingType.Name}' and cannot be assigned during snapshot JSON materialization, which fails queries with 'Expression must be writeable'. " - + "Add an 'init' or 'set' accessor, mark the member [JsonIgnore] to exclude it from the snapshot, or mark it [EFOpaque] to persist it as non-queryable JSON." - ); - - static InvalidOperationException CreateUnsupportedCollectionTypeException( - Type containingType, - MemberInfo member, - Type collectionType - ) => - new( - $"{containingType.Name}.{member.Name} uses unsupported collection type '{collectionType.Name}'. " - + "Collection and array members must use Purview.EventSourcing.EventStoreList or Purview.EventSourcing.EventStoreSet." - ); - - static void EnsureSupportedOrderByExpression(Expression queryExpression) => - new UnsupportedScalarValueOrderByDetector().Visit(queryExpression); - - static Expression> RewriteAggregateTypePredicate( - Expression> whereClause, - string aggregateType - ) - where T : class - { - AggregateTypeExpressionVisitor aggregateTypeVisitor = new(aggregateType); - var rewritten = (Expression>)aggregateTypeVisitor.Visit(whereClause); - InvariantStringMethodNormalizationVisitor invariantCasingVisitor = new(); - rewritten = (Expression>)invariantCasingVisitor.Visit(rewritten); - ScalarValueMemberAccessPredicateVisitor scalarVisitor = new(); - return (Expression>)scalarVisitor.Visit(rewritten); - } - - sealed class AggregateTypeExpressionVisitor(string aggregateType) : ExpressionVisitor - { - readonly ConstantExpression _aggregateType = Expression.Constant(aggregateType, typeof(string)); - - protected override Expression VisitMember(MemberExpression node) => - node.Member.Name == nameof(IAggregate.AggregateType) - && node.Expression is not null - && typeof(IAggregate).IsAssignableFrom(node.Expression.Type) - ? _aggregateType - : base.VisitMember(node); - } - - sealed class UnsupportedScalarValueOrderByDetector : ExpressionVisitor - { - protected override Expression VisitMethodCall(MethodCallExpression node) - { - if ( - node.Method.DeclaringType == typeof(Queryable) - && ( - node.Method.Name == nameof(Queryable.OrderBy) - || node.Method.Name == nameof(Queryable.OrderByDescending) - || node.Method.Name == nameof(Queryable.ThenBy) - || node.Method.Name == nameof(Queryable.ThenByDescending) - ) - ) - { - var lambda = (LambdaExpression)StripQuotes(node.Arguments[1]); - new ScalarValueMemberAccessDetector().Visit(lambda.Body); - } - - return base.VisitMethodCall(node); - } - - static Expression StripQuotes(Expression expression) - { - while (expression.NodeType == ExpressionType.Quote) - expression = ((UnaryExpression)expression).Operand; - - return expression; - } - } - - sealed class ScalarValueMemberAccessPredicateVisitor : ExpressionVisitor - { - protected override Expression VisitBinary(BinaryExpression node) - { - var visitedLeft = Visit(node.Left); - var visitedRight = Visit(node.Right); - - return - (node.NodeType == ExpressionType.Equal || node.NodeType == ExpressionType.NotEqual) - && TryRewriteScalarPrimitiveComparison( - visitedLeft, - visitedRight, - out var rewrittenLeft, - out var rewrittenRight - ) - ? Expression.MakeBinary(node.NodeType, rewrittenLeft, rewrittenRight) - : node.Update(visitedLeft, node.Conversion, visitedRight); - } - - protected override Expression VisitMember(MemberExpression node) - { - var visitedExpression = base.VisitMember(node); - if (visitedExpression is not MemberExpression visited || visited.Expression is null) - return visitedExpression; - - var scalarAttribute = visited.Expression.Type.GetCustomAttribute(); - if (scalarAttribute is null || visited.Member.Name != scalarAttribute.PropertyName) - return visited; - - try - { - return Expression.Convert(visited.Expression, visited.Type); - } - catch (InvalidOperationException) - { - return visited; - } - } - - static bool TryRewriteScalarPrimitiveComparison( - Expression left, - Expression right, - out Expression rewrittenLeft, - out Expression rewrittenRight - ) - { - rewrittenLeft = left; - rewrittenRight = right; - - if ( - TryGetScalarPropertyType(left.Type, out var leftScalarType) - && IsSameOrNullable(right.Type, leftScalarType) - ) - { - rewrittenLeft = Expression.Convert(left, right.Type); - return true; - } - - if ( - TryGetScalarPropertyType(right.Type, out var rightScalarType) - && IsSameOrNullable(left.Type, rightScalarType) - ) - { - rewrittenRight = Expression.Convert(right, left.Type); - return true; - } - - return false; - } - - static bool TryGetScalarPropertyType(Type candidateType, out Type scalarPropertyType) - { - scalarPropertyType = null!; - var scalarAttribute = candidateType.GetCustomAttribute(); - if (scalarAttribute is null) - return false; - - var scalarProperty = candidateType.GetProperty( - scalarAttribute.PropertyName, - BindingFlags.Instance | BindingFlags.Public - ); - if (scalarProperty is null) - return false; - - scalarPropertyType = scalarProperty.PropertyType; - return true; - } - - static bool IsSameOrNullable(Type candidate, Type expected) - { - var underlyingType = Nullable.GetUnderlyingType(candidate); - return candidate == expected || underlyingType == expected; - } - } - - sealed class InvariantStringMethodNormalizationVisitor : ExpressionVisitor - { - protected override Expression VisitMethodCall(MethodCallExpression node) - { - var visitedObject = Visit(node.Object); - var visitedArguments = Visit(node.Arguments); - - if (node.Method.DeclaringType == typeof(string) && node.Arguments.Count == 0 && visitedObject is not null) - { - if (node.Method.Name == nameof(string.ToLowerInvariant)) - return Expression.Call(visitedObject, nameof(string.ToLower), Type.EmptyTypes); - - if (node.Method.Name == nameof(string.ToUpperInvariant)) - return Expression.Call(visitedObject, nameof(string.ToUpper), Type.EmptyTypes); - } - - return node.Update(visitedObject, visitedArguments); - } - } - - sealed class ScalarValueMemberAccessDetector : ExpressionVisitor - { - protected override Expression VisitMember(MemberExpression node) - { - var visited = base.VisitMember(node); - if (node.Expression is null) - return visited; - - var scalarAttribute = node.Expression.Type.GetCustomAttribute(); - return scalarAttribute is not null && node.Member.Name == scalarAttribute.PropertyName - ? throw new InvalidOperationException( - $"Ordering by '{node.Expression.Type.Name}.{node.Member.Name}' is not supported for SQL snapshot JSON queries. " - + "Order by the scalar value object property itself (for example: c => c.Name) instead of its inner scalar member." - ) - : visited; - } - } - - sealed class SnapshotModelCacheKeyFactory : IModelCacheKeyFactory - { - public object Create(DbContext context, bool designTime) - { - var optionsField = context.GetType().GetField("_options", BindingFlags.Instance | BindingFlags.NonPublic); - if (optionsField?.GetValue(context) is PostgresClientOptions options) - { - if ( - context.GetType().IsGenericType - && context.GetType().GetGenericTypeDefinition() == typeof(SnapshotQueryDBContext<>) - ) - { - var aggregateType = context.GetType().GenericTypeArguments[0]; - return (context.GetType(), aggregateType, options.SchemaName, options.TableName, designTime); - } - - return (context.GetType(), options.SchemaName, options.TableName, designTime); - } - - return (context.GetType(), designTime); - } - } - async Task EnsureTableIfEnabledAsync(CancellationToken cancellationToken) { if (!_options.AutoCreateTable || IsTableEnsured()) diff --git a/src/src/Postgres/Client/ScalarValueConverter.cs b/src/src/Postgres/Client/ScalarValueConverter.cs deleted file mode 100644 index 61c236c2..00000000 --- a/src/src/Postgres/Client/ScalarValueConverter.cs +++ /dev/null @@ -1,74 +0,0 @@ -using System.Linq.Expressions; -using System.Reflection; -using Microsoft.EntityFrameworkCore.Storage.ValueConversion; -using Purview.ValueObjects.Serialization; - -namespace Purview.EventSourcing.Postgres.Client; - -sealed class ScalarValueConverter : ValueConverter -{ - public ScalarValueConverter() - : base(BuildToProviderExpression(), BuildFromProviderExpression()) { } - - static Expression> BuildToProviderExpression() - { - var scalarProperty = GetScalarProperty(); - var source = Expression.Parameter(typeof(TScalarObject), "value"); - var body = Expression.Property(source, scalarProperty); - return Expression.Lambda>(body, source); - } - - static Expression> BuildFromProviderExpression() - { - var source = Expression.Parameter(typeof(TScalar), "value"); - var body = BuildCreatorExpression(source); - return Expression.Lambda>(body, source); - } - - static PropertyInfo GetScalarProperty() - { - var scalarType = typeof(TScalarObject); - var scalarAttribute = - scalarType.GetCustomAttribute() - ?? throw new InvalidOperationException($"{scalarType.Name} must be annotated with [Scalar]."); - - return scalarType.GetProperty(scalarAttribute.PropertyName, BindingFlags.Instance | BindingFlags.Public) - ?? throw new InvalidOperationException( - $"'{scalarType.Name}' missing scalar property '{scalarAttribute.PropertyName}'." - ); - } - - static Expression BuildCreatorExpression(ParameterExpression source) - { - var scalarType = typeof(TScalarObject); - var scalarPropertyType = typeof(TScalar); - var scalarAttribute = - scalarType.GetCustomAttribute() - ?? throw new InvalidOperationException($"{scalarType.Name} must be annotated with [Scalar]."); - - var preferredFactoryName = - scalarAttribute.DeserializationMode == ValueObjectDeserializationMode.Strict ? "Create" : "Hydrate"; - var secondaryFactoryName = preferredFactoryName == "Hydrate" ? "Create" : "Hydrate"; - - var create = - scalarType.GetMethod(preferredFactoryName, BindingFlags.Public | BindingFlags.Static, [scalarPropertyType]) - ?? scalarType.GetMethod( - secondaryFactoryName, - BindingFlags.Public | BindingFlags.Static, - [scalarPropertyType] - ); - if (create is not null) - return Expression.Call(create, source); - - var ctor = scalarType.GetConstructor( - BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic, - [scalarPropertyType] - ); - - return ctor is null - ? throw new InvalidOperationException( - $"{scalarType.Name} must expose static {preferredFactoryName}({scalarPropertyType.Name}), static {secondaryFactoryName}({scalarPropertyType.Name}), or ctor({scalarPropertyType.Name})." - ) - : (Expression)Expression.New(ctor, source); - } -} diff --git a/src/src/Postgres/Events/AggregateVersionData.cs b/src/src/Postgres/Events/AggregateVersionData.cs index c70c0cdf..cea4492d 100644 --- a/src/src/Postgres/Events/AggregateVersionData.cs +++ b/src/src/Postgres/Events/AggregateVersionData.cs @@ -8,7 +8,7 @@ namespace Purview.EventSourcing.Postgres.Events; /// The last version that was persisted to the event store. /// The version captured by the latest snapshot, or zero when no snapshot exists. /// The current version of the aggregate. -public record struct AggregateVersionData(int SavedVersion, int SnapshotVersion, int CurrentVersion) +public record struct AggregateVersionData(long SavedVersion, long SnapshotVersion, long CurrentVersion) { /// /// Creates version data from the aggregate's current details. diff --git a/src/src/Postgres/Events/EntityFramework/EventStoreDbContext.cs b/src/src/Postgres/Events/EntityFramework/EventStoreDbContext.cs index 09c6d1e7..eb325dea 100644 --- a/src/src/Postgres/Events/EntityFramework/EventStoreDbContext.cs +++ b/src/src/Postgres/Events/EntityFramework/EventStoreDbContext.cs @@ -1,5 +1,6 @@ using Microsoft.EntityFrameworkCore; using Microsoft.EntityFrameworkCore.Infrastructure; +using Purview.EventSourcing.Tenancy; namespace Purview.EventSourcing.Postgres.Events.EntityFramework; @@ -11,12 +12,21 @@ namespace Purview.EventSourcing.Postgres.Events.EntityFramework; /// /// Creates a new with explicit schema and table names. /// -public class EventStoreDbContext(DbContextOptions options, string schemaName, string tableName) - : DbContext(options) +public class EventStoreDbContext( + DbContextOptions options, + string schemaName, + string tableName, + ICurrentTenant? currentTenant = null +) : DbContext(options) { readonly string _schemaName = schemaName; readonly string _tableName = tableName; + // Captured once per context rather than read per query: a context is short-lived and scoped to one + // operation, and EF only re-evaluates plain context fields when it reuses the cached model. + readonly bool _crossesTenants = (currentTenant?.Current ?? TenantScope.System).IsSystem; + readonly string? _tenantId = (currentTenant?.Current ?? TenantScope.System).TenantId; + /// /// All event store rows (stream versions, events, idempotency markers, snapshots). /// @@ -52,6 +62,12 @@ protected override void OnModelCreating(ModelBuilder modelBuilder) entity.Property(e => e.CorrelationId).HasMaxLength(450); entity.Property(e => e.CausationId).HasMaxLength(450); entity.Property(e => e.UserId).HasMaxLength(450); + entity.Property(e => e.TenantId).HasMaxLength(450); + + // A global filter rather than a per-query predicate: a read that forgets the tenant is the + // failure mode this exists to prevent, and EF applies this to every LINQ query on the set. + // Both members are fields, so EF parameterises them and one cached model serves all tenants. + entity.HasQueryFilter(e => _crossesTenants || e.TenantId == _tenantId); entity.Property(e => e.Timestamp).HasDefaultValueSql("CURRENT_TIMESTAMP").IsRequired(); // Covers: GetByAggregateIdAndEntityType, GetIdempotencyMarkers, DeleteByAggregateId diff --git a/src/src/Postgres/Events/EntityFramework/EventStoreEntity.cs b/src/src/Postgres/Events/EntityFramework/EventStoreEntity.cs index 5af906ad..67b9f8e4 100644 --- a/src/src/Postgres/Events/EntityFramework/EventStoreEntity.cs +++ b/src/src/Postgres/Events/EntityFramework/EventStoreEntity.cs @@ -29,7 +29,7 @@ public sealed class EventStoreEntity /// /// The event or stream version number. /// - public int Version { get; set; } + public long Version { get; set; } /// /// Whether this aggregate has been soft-deleted. @@ -63,6 +63,9 @@ public sealed class EventStoreEntity /// The user identifier recorded with the event. public string? UserId { get; set; } + /// The tenant that owns the row; null in a single-tenant deployment. + public string? TenantId { get; set; } + /// /// UTC timestamp of when this row was created or last modified. /// diff --git a/src/src/Postgres/Events/Exceptions/AggregateAlreadyDeletedException.cs b/src/src/Postgres/Events/Exceptions/AggregateAlreadyDeletedException.cs deleted file mode 100644 index b2bc4ccc..00000000 --- a/src/src/Postgres/Events/Exceptions/AggregateAlreadyDeletedException.cs +++ /dev/null @@ -1,24 +0,0 @@ -#pragma warning disable CA1032 // Implement standard exception constructors - -namespace Purview.EventSourcing.Postgres.Events.Exceptions; - -/// -/// Thrown when an attempt is made to delete an aggregate that has already been deleted. -/// -/// The id of the aggregate that is already deleted. -/// The idempotency id of the operation that attempted the deletion. -public class AggregateAlreadyDeletedException(string aggregateId, string idempotencyId) - : Exception( - $"An attempt to delete an aggregate (Id: {aggregateId}) that is already deleted was made. {nameof(idempotencyId)}: {idempotencyId}." - ) -{ - /// - /// The id of the aggregate that is already deleted. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// The idempotency id of the operation that attempted the deletion. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/Postgres/Events/Exceptions/AggregateDeletedException.cs b/src/src/Postgres/Events/Exceptions/AggregateDeletedException.cs deleted file mode 100644 index 90e089c0..00000000 --- a/src/src/Postgres/Events/Exceptions/AggregateDeletedException.cs +++ /dev/null @@ -1,24 +0,0 @@ -#pragma warning disable CA1032 // Implement standard exception constructors - -namespace Purview.EventSourcing.Postgres.Events.Exceptions; - -/// -/// Thrown when an attempt is made to save an aggregate that has been deleted. -/// -/// The id of the deleted aggregate. -/// The idempotency id of the operation that attempted the save. -public class AggregateDeletedException(string aggregateId, string idempotencyId) - : Exception( - $"An attempt to save an aggregate that has been deleted, aggregate Id: {aggregateId}, {nameof(IdempotencyId)}: {idempotencyId}." - ) -{ - /// - /// The id of the deleted aggregate. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// The idempotency id of the operation that attempted the save. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/Postgres/Events/Exceptions/AggregateIsDeletedException.cs b/src/src/Postgres/Events/Exceptions/AggregateIsDeletedException.cs deleted file mode 100644 index 9e8b1e08..00000000 --- a/src/src/Postgres/Events/Exceptions/AggregateIsDeletedException.cs +++ /dev/null @@ -1,16 +0,0 @@ -namespace Purview.EventSourcing.Postgres.Events.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an operation is attempted against an aggregate that has been deleted. -/// -/// The id of the deleted aggregate. -public class AggregateIsDeletedException(string aggregateId) - : Exception($"Invalid operation against an aggregate (Id: {aggregateId}) that has been deleted.") -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The id of the deleted aggregate. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); -} diff --git a/src/src/Postgres/Events/Exceptions/AggregateLockedException.cs b/src/src/Postgres/Events/Exceptions/AggregateLockedException.cs deleted file mode 100644 index e146e11b..00000000 --- a/src/src/Postgres/Events/Exceptions/AggregateLockedException.cs +++ /dev/null @@ -1,18 +0,0 @@ -namespace Purview.EventSourcing.Postgres.Events.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an attempt is made to save an aggregate that is currently locked. -/// -/// The idempotency id of the operation that attempted the save. -public class AggregateLockedException(string idempotencyId) - : Exception( - $"An attempt to save an aggregate that is currently locked was made, {nameof(idempotencyId)}: {idempotencyId}." - ) -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The idempotency id of the operation that attempted the save. - /// - public string IdempotencyId { get; set; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/Postgres/Events/Exceptions/AggregateNotDeletedException.cs b/src/src/Postgres/Events/Exceptions/AggregateNotDeletedException.cs deleted file mode 100644 index ba500d13..00000000 --- a/src/src/Postgres/Events/Exceptions/AggregateNotDeletedException.cs +++ /dev/null @@ -1,16 +0,0 @@ -namespace Purview.EventSourcing.Postgres.Events.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an attempt is made to get an aggregate that has not been deleted. -/// -/// The id of the aggregate that is not deleted. -public class AggregateNotDeletedException(string aggregateId) - : Exception($"An attempt to get an aggregate that has not been deleted, aggregate Id: {aggregateId}.") -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The id of the aggregate that is not deleted. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); -} diff --git a/src/src/Postgres/Events/Exceptions/AggregateStreamVersionMissingException.cs b/src/src/Postgres/Events/Exceptions/AggregateStreamVersionMissingException.cs deleted file mode 100644 index 942cf363..00000000 --- a/src/src/Postgres/Events/Exceptions/AggregateStreamVersionMissingException.cs +++ /dev/null @@ -1,24 +0,0 @@ -namespace Purview.EventSourcing.Postgres.Events.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an aggregate does not have an expected stream version row. -/// -/// The id of the aggregate missing its stream version. -/// The idempotency id of the operation. -public class AggregateStreamVersionMissingException(string aggregateId, string idempotencyId) - : Exception( - $"An attempt to delete an aggregate (Id: {aggregateId}) that doesn't a stream version deleted was made. {nameof(idempotencyId)}: {idempotencyId}." - ) -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The id of the aggregate missing its stream version. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// The idempotency id of the operation. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/Postgres/Events/Exceptions/AggregatedNotAlreadyDeletedException.cs b/src/src/Postgres/Events/Exceptions/AggregatedNotAlreadyDeletedException.cs deleted file mode 100644 index 5c2125b8..00000000 --- a/src/src/Postgres/Events/Exceptions/AggregatedNotAlreadyDeletedException.cs +++ /dev/null @@ -1,24 +0,0 @@ -namespace Purview.EventSourcing.Postgres.Events.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an attempt is made to restore an aggregate that is not currently deleted. -/// -/// The id of the aggregate that is not deleted. -/// The idempotency id of the operation that attempted the restore. -public class AggregatedNotAlreadyDeletedException(string aggregateId, string idempotencyId) - : Exception( - $"An attempt to restore an aggregate (Id: {aggregateId}) that is not deleted was made.\n\n\tIdempotencyId: {idempotencyId}." - ) -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The id of the aggregate that is not deleted. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// The idempotency id of the operation that attempted the restore. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/Postgres/Events/Exceptions/CommitException.cs b/src/src/Postgres/Events/Exceptions/CommitException.cs deleted file mode 100644 index 6e8ba89f..00000000 --- a/src/src/Postgres/Events/Exceptions/CommitException.cs +++ /dev/null @@ -1,44 +0,0 @@ -namespace Purview.EventSourcing.Postgres.Events.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when committing events to the PostgreSQL event store fails. -/// -/// The id of the aggregate whose events failed to commit. -/// The idempotency id of the operation that failed to commit. -/// The aggregate version the operation attempted to commit. -/// The aggregate version currently persisted in the store. -/// The underlying exception that caused the commit to fail. -public class CommitException( - string aggregateId, - string idempotencyId, - int versionAttempted, - int version, - Exception exception -) - : Exception( - $"Failed to commit events.\n\tAggregateId: {aggregateId}\n\tIdempotencyId: {idempotencyId}\n\tVersionAttempted: {versionAttempted}\n\tVersionPresent: {version}", - exception - ) -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The id of the aggregate whose events failed to commit. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// The aggregate version the operation attempted to commit. - /// - public int VersionAttempted { get; } = versionAttempted; - - /// - /// The idempotency id of the operation that failed to commit. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); - - /// - /// The aggregate version currently persisted in the store. - /// - public int Version { get; } = version; -} diff --git a/src/src/Postgres/Events/Exceptions/ConcurrencyException.cs b/src/src/Postgres/Events/Exceptions/ConcurrencyException.cs deleted file mode 100644 index 30ede447..00000000 --- a/src/src/Postgres/Events/Exceptions/ConcurrencyException.cs +++ /dev/null @@ -1,37 +0,0 @@ -namespace Purview.EventSourcing.Postgres.Events.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an optimistic concurrency conflict is detected while saving an aggregate. -/// -/// The id of the aggregate that could not be saved. -/// The idempotency id of the operation that could not be saved. -/// The aggregate version the operation attempted to save. -/// The aggregate version currently persisted in the store. -public class ConcurrencyException(string aggregateId, string idempotencyId, int versionAttempted, int version) - : Exception( - $"Optimistic concurrency error:\n\tAggregateId: {aggregateId}\n\tIdempotencyId: {idempotencyId}\n\tVersionAttempted:{versionAttempted}\n\tVersionPresent:{version}" - ), - IConcurrencyConflict -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The id of the aggregate that could not be saved. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// The aggregate version the operation attempted to save. - /// - public int VersionAttempted { get; } = versionAttempted; - - /// - /// The idempotency id of the operation that could not be saved. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); - - /// - /// The aggregate version currently persisted in the store. - /// - public int Version { get; } = version; -} diff --git a/src/src/Postgres/Events/Exceptions/MissingAggregateIdException.cs b/src/src/Postgres/Events/Exceptions/MissingAggregateIdException.cs deleted file mode 100644 index bf952fdc..00000000 --- a/src/src/Postgres/Events/Exceptions/MissingAggregateIdException.cs +++ /dev/null @@ -1,16 +0,0 @@ -namespace Purview.EventSourcing.Postgres.Events.Exceptions; - -#pragma warning disable CA1032 // Implement standard exception constructors -/// -/// Thrown when an attempt is made to save an aggregate that has no id. -/// -/// The idempotency id of the operation that attempted the save. -public class MissingAggregateIdException(string idempotencyId) - : Exception($"An attempt to save an aggregate is a missing Id was made, {nameof(idempotencyId)}: {idempotencyId}.") -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The idempotency id of the operation that attempted the save. - /// - public string IdempotencyId { get; set; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/Postgres/Events/IPostgresEventStoreTelemetry.cs b/src/src/Postgres/Events/IPostgresEventStoreTelemetry.cs index 7d82363d..5b27a9ec 100644 --- a/src/src/Postgres/Events/IPostgresEventStoreTelemetry.cs +++ b/src/src/Postgres/Events/IPostgresEventStoreTelemetry.cs @@ -31,7 +31,7 @@ public interface IPostgresEventStoreTelemetry /// The full name of the aggregate type being retrieved. /// The started activity, or when the activity source is disabled. [Activity] - Activity? GetAggregateAtVersion(string aggregateId, int version, [Baggage] string aggregateTypeFullName); + Activity? GetAggregateAtVersion(string aggregateId, long version, [Baggage] string aggregateTypeFullName); /// /// Starts an activity for an aggregate save operation. @@ -58,7 +58,7 @@ public interface IPostgresEventStoreTelemetry /// The number of events applied. /// The aggregate version after reconstitution. [Event] - void EventsReconstituted(Activity? activity, int eventCount, int version); + void EventsReconstituted(Activity? activity, int eventCount, long version); /// /// Records the completion of a save operation. @@ -120,7 +120,7 @@ public interface IPostgresEventStoreTelemetry void GetAggregateAtSpecificVersionFailed( string aggregateId, string aggregateTypeFullName, - int specificVersion, + long specificVersion, Exception exception ); @@ -148,7 +148,7 @@ AggregateVersionData versionData /// The version of the aggregate being retrieved. /// The full name of the aggregate type being retrieved. [Log(LogLevel.Debug)] - void GetAggregateAtSpecificVersionStart(string aggregateId, int specificVersion, string aggregateTypeFullName); + void GetAggregateAtSpecificVersionStart(string aggregateId, long specificVersion, string aggregateTypeFullName); /// /// Logs that a save operation contained no changes. @@ -173,7 +173,7 @@ void SkippedUnknownEvent( string aggregateTypeFullName, string aggregateType, string eventType, - int aggregateVersion + long aggregateVersion ); /// @@ -192,7 +192,7 @@ void CannotApplyEvent( string aggregateType, string eventType, string eventTypeFullName, - int aggregateVersion + long aggregateVersion ); /// @@ -312,7 +312,7 @@ int aggregateVersion void GetAggregateAtSpecificVersionComplete( string aggregateId, string aggregateTypeFullName, - int specificVersion, + long specificVersion, long elapsedMilliseconds ); @@ -381,7 +381,7 @@ string aggregateTypeFullName /// The short type name of the aggregate. /// Whether the aggregate is deleted. [Log(LogLevel.Debug)] - void StreamVersionFound(string aggregateId, int streamVersion, string aggregateType, bool isDeleted); + void StreamVersionFound(string aggregateId, long streamVersion, string aggregateType, bool isDeleted); /// /// Logs that retrieving a stream version failed. diff --git a/src/src/Postgres/Events/PostgresEventStore.DeleteAsync.cs b/src/src/Postgres/Events/PostgresEventStore.DeleteAsync.cs index 04450511..a360f861 100644 --- a/src/src/Postgres/Events/PostgresEventStore.DeleteAsync.cs +++ b/src/src/Postgres/Events/PostgresEventStore.DeleteAsync.cs @@ -1,12 +1,14 @@ using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.Postgres.Events; partial class PostgresEventStore { /// - public async Task DeleteAsync( + public async Task, AggregateDeleteFailure>> DeleteAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -16,12 +18,20 @@ public async Task DeleteAsync( throw NullAggregate(aggregate); if (aggregate.Details.IsDeleted) - throw AggregateIsDeletedException(aggregate.Id()); + { + return AggregateDeleteFailure.Failure>( + new AggregateAlreadyDeleted(aggregate.AggregateType, aggregate.Id()) + ); + } operationContext ??= EventStoreOperationContext.DefaultContext(); if (aggregate.IsNew()) - return false; + { + return AggregateDeleteFailure.Failure>( + new AggregateNotFound(aggregate.AggregateType, aggregate.Id()) + ); + } if (operationContext.PermanentlyDelete) return await PermanentlyDeleteAsync(aggregate, operationContext, cancellationToken); @@ -46,12 +56,15 @@ public async Task DeleteAsync( cancellationToken, new EventRecord(deleteAggregateEvent, metadata) ); + if (result.Result.IsFailure) + return result.Result.Error.ToDeleteFailure(); + await result.AfterCommitAsync(cancellationToken); - return result.Result.Saved; + return result.Result.Value; } - async Task PermanentlyDeleteAsync( + async Task, AggregateDeleteFailure>> PermanentlyDeleteAsync( T aggregate, EventStoreOperationContext operationContext, CancellationToken cancellationToken = default @@ -63,7 +76,11 @@ async Task PermanentlyDeleteAsync( var aggregateId = aggregate.Id(); var streamVersion = await GetStreamVersionAsync(aggregateId, true, cancellationToken); if (streamVersion == null) - return false; + { + return AggregateDeleteFailure.Failure>( + new AggregateNotFound(aggregate.AggregateType, aggregateId) + ); + } _eventStoreTelemetry.PermanentDeleteRequested(aggregateId); using var activity = _eventStoreTelemetry.DeleteAggregate(aggregateId, _aggregateTypeFullName); @@ -77,7 +94,7 @@ async Task PermanentlyDeleteAsync( aggregate.Details.IsDeleted = true; aggregate.Details.Locked = true; - return true; + return new SaveOutcome(aggregate, SaveOutcomeKind.Written); } #pragma warning disable CA1031 catch (Exception ex) @@ -85,7 +102,7 @@ async Task PermanentlyDeleteAsync( { _eventStoreTelemetry.PermanentDeleteFailed(aggregateId, ex); - return false; + throw; } finally { diff --git a/src/src/Postgres/Events/PostgresEventStore.ExceptionHelpers.cs b/src/src/Postgres/Events/PostgresEventStore.ExceptionHelpers.cs index c3c55767..a5253ea6 100644 --- a/src/src/Postgres/Events/PostgresEventStore.ExceptionHelpers.cs +++ b/src/src/Postgres/Events/PostgresEventStore.ExceptionHelpers.cs @@ -1,4 +1,5 @@ -using Purview.EventSourcing.Postgres.Events.Exceptions; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.Postgres.Events; @@ -7,7 +8,12 @@ partial class PostgresEventStore { static ArgumentNullException NullAggregate(T? aggregate) => new(nameof(aggregate)); - static AggregateIsDeletedException AggregateIsDeletedException(string aggregateId) => new(aggregateId); + Result NotFound(string aggregateId) => + AggregateReadFailure.Failure(new AggregateNotFound(_aggregateTypeShortName, aggregateId)); - static AggregateNotDeletedException AggregateNotDeletedException(string aggregateId) => new(aggregateId); + Result Deleted(string aggregateId) => + AggregateReadFailure.Failure(new AggregateDeleted(_aggregateTypeShortName, aggregateId)); + + Result NotDeleted(string aggregateId) => + AggregateReadFailure.Failure(new AggregateNotDeleted(_aggregateTypeShortName, aggregateId)); } diff --git a/src/src/Postgres/Events/PostgresEventStore.ExistsAsync.cs b/src/src/Postgres/Events/PostgresEventStore.ExistsAsync.cs index c43f357d..79294f08 100644 --- a/src/src/Postgres/Events/PostgresEventStore.ExistsAsync.cs +++ b/src/src/Postgres/Events/PostgresEventStore.ExistsAsync.cs @@ -3,16 +3,16 @@ namespace Purview.EventSourcing.Postgres.Events; partial class PostgresEventStore { /// - public async Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) + public async Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) { ArgumentException.ThrowIfNullOrWhiteSpace(aggregateId, nameof(aggregateId)); var streamVersion = await GetStreamVersionAsync(aggregateId, false, cancellationToken); return streamVersion == null - ? ExistsState.DoesNotExist - : new ExistsState + ? AggregateExistence.DoesNotExist + : new AggregateExistence { - Status = streamVersion.IsDeleted ? ExistsStatus.ExistsInDeletedState : ExistsStatus.Exists, + Status = streamVersion.IsDeleted ? ExistenceStatus.ExistsInDeletedState : ExistenceStatus.Exists, Version = streamVersion.Version, }; } diff --git a/src/src/Postgres/Events/PostgresEventStore.GetAsync.cs b/src/src/Postgres/Events/PostgresEventStore.GetAsync.cs index 028b0f3b..25c6fa2f 100644 --- a/src/src/Postgres/Events/PostgresEventStore.GetAsync.cs +++ b/src/src/Postgres/Events/PostgresEventStore.GetAsync.cs @@ -2,6 +2,8 @@ using Microsoft.Extensions.Caching.Distributed; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.Postgres.Events; @@ -9,13 +11,13 @@ partial class PostgresEventStore { /// [System.Diagnostics.DebuggerStepThrough] - public Task GetAsync( + public Task> GetAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => GetCoreAsync(aggregateId, operationContext, cancellationToken); - async Task GetCoreAsync( + async Task> GetCoreAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -44,9 +46,9 @@ partial class PostgresEventStore { _eventStoreTelemetry.AggregateRetrievedFromCache(aggregateId, _aggregateTypeFullName); - return ReturnAggregate(aggregate.Details.IsDeleted, aggregateId, operationContext) + return ReturnAggregate(aggregate.Details.IsDeleted, operationContext) ? PrepareAggregateForReturn(aggregate, _aggregateRequirementsManager) - : null; + : Deleted(aggregateId); } // Single-flight: when the aggregate will be written back to the cache, serialize @@ -72,20 +74,20 @@ partial class PostgresEventStore { _eventStoreTelemetry.AggregateRetrievedFromCache(aggregateId, _aggregateTypeFullName); - return ReturnAggregate(cached.Details.IsDeleted, aggregateId, operationContext) + return ReturnAggregate(cached.Details.IsDeleted, operationContext) ? PrepareAggregateForReturn(cached, _aggregateRequirementsManager) - : null; + : Deleted(aggregateId); } } var streamVersion = await GetStreamVersionAsync(aggregateId, true, cancellationToken); if (streamVersion == null) - return null; + return NotFound(aggregateId); - if (!ReturnAggregate(streamVersion.IsDeleted, aggregateId, operationContext)) - return null; + if (!ReturnAggregate(streamVersion.IsDeleted, operationContext)) + return Deleted(aggregateId); - int? streamVersionIdentifier = null; + long? streamVersionIdentifier = null; if (!operationContext.SkipSnapshot) aggregate = await GetLatestSnapshotAsync(aggregateId, cancellationToken); @@ -111,6 +113,7 @@ partial class PostgresEventStore _aggregateTypeFullName, getStopwatch.ElapsedMilliseconds ); + _metrics.GetDuration(getStopwatch.Elapsed.TotalMilliseconds, _aggregateTypeShortName); } async Task IsCacheHitFreshAsync(T aggregate, string aggregateId, CancellationToken cancellationToken) @@ -139,7 +142,7 @@ Services.IAggregateRequirementsManager aggregateRequirementsManager async Task GetAndApplyEventsAsync( T aggregate, StreamVersionData streamVersion, - int? maxVersion, + long? maxVersion, CancellationToken cancellationToken ) { diff --git a/src/src/Postgres/Events/PostgresEventStore.GetAtAsync.cs b/src/src/Postgres/Events/PostgresEventStore.GetAtAsync.cs index d9c634ce..00ab5437 100644 --- a/src/src/Postgres/Events/PostgresEventStore.GetAtAsync.cs +++ b/src/src/Postgres/Events/PostgresEventStore.GetAtAsync.cs @@ -1,13 +1,15 @@ using System.Diagnostics; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.Postgres.Events; partial class PostgresEventStore { /// - public async Task GetAtAsync( + public async Task> GetAtAsync( string aggregateId, - int version, + long version, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) @@ -23,10 +25,10 @@ partial class PostgresEventStore { var streamVersion = await GetStreamVersionAsync(aggregateId, true, cancellationToken); if (streamVersion == null) - return null; + return NotFound(aggregateId); - if (!ReturnAggregate(streamVersion.IsDeleted, aggregateId, operationContext)) - return null; + if (!ReturnAggregate(streamVersion.IsDeleted, operationContext)) + return Deleted(aggregateId); T aggregate = new() { Details = { Id = aggregateId } }; diff --git a/src/src/Postgres/Events/PostgresEventStore.GetDeletedAsync.cs b/src/src/Postgres/Events/PostgresEventStore.GetDeletedAsync.cs index ab93e4f3..b7fec80f 100644 --- a/src/src/Postgres/Events/PostgresEventStore.GetDeletedAsync.cs +++ b/src/src/Postgres/Events/PostgresEventStore.GetDeletedAsync.cs @@ -1,18 +1,26 @@ +using Purview.EventSourcing.Failures; +using Purview.Results; + namespace Purview.EventSourcing.Postgres.Events; partial class PostgresEventStore { /// - public async Task GetDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) + public async Task> GetDeletedAsync( + string aggregateId, + CancellationToken cancellationToken = default + ) { - var aggregate = await GetCoreAsync( + var result = await GetCoreAsync( aggregateId, new() { SnapshotCacheMode = SnapshotCachingOptions.None, DeleteMode = DeleteHandlingMode.ReturnsAggregate }, cancellationToken ); + if (result.IsFailure) + return result; + + var aggregate = result.Value; - return aggregate == null ? null - : aggregate.Details.IsDeleted ? FulfilRequirements(aggregate) - : throw AggregateNotDeletedException(aggregateId); + return aggregate.Details.IsDeleted ? FulfilRequirements(aggregate) : NotDeleted(aggregateId); } } diff --git a/src/src/Postgres/Events/PostgresEventStore.GetEventRangeAsync.cs b/src/src/Postgres/Events/PostgresEventStore.GetEventRangeAsync.cs index 08b5051e..351fa475 100644 --- a/src/src/Postgres/Events/PostgresEventStore.GetEventRangeAsync.cs +++ b/src/src/Postgres/Events/PostgresEventStore.GetEventRangeAsync.cs @@ -16,8 +16,8 @@ partial class PostgresEventStore /// If no is specified all available events greater than are returned. public async IAsyncEnumerable<(EventRecord EventRecord, string EventType)> GetEventRangeAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, [EnumeratorCancellation] CancellationToken cancellationToken ) { @@ -46,16 +46,20 @@ [EnumeratorCancellation] CancellationToken cancellationToken ); await foreach (var entity in entities) { - var item = DeserializeEvent(entity); + var item = await DeserializeEventAsync(entity, cancellationToken); if (item != null) yield return (item.Value, entity.EventType!); } } /// - EventRecord? DeserializeEvent(PostgresEventStoreClient.RowData eventRow) + /// + async Task DeserializeEventAsync( + PostgresEventStoreClient.RowData eventRow, + CancellationToken cancellationToken + ) { - static UnknownEvent ReturnUnknownEvent(PostgresEventStoreClient.RowData eventRow, int aggregateVersion) => + static UnknownEvent ReturnUnknownEvent(PostgresEventStoreClient.RowData eventRow, long aggregateVersion) => new() { SchemaVersion = eventRow.SchemaVersion, @@ -97,7 +101,19 @@ static UnknownEvent ReturnUnknownEvent(PostgresEventStoreClient.RowData eventRow Type.GetType(name, throwOnError: false) ?? throw new ApplicationException($"Unable to load event type: {name}") ); - var @event = DeserializeEvent(eventRow.Payload!, runtimeEventType); + var payload = eventRow.Payload!; + if (_payloadProtector is not null && _payloadProtector.IsProtected(payload)) + { + var unprotected = await _payloadProtector.UnprotectAsync(payload, cancellationToken); + if (unprotected is null) + // The subject has been erased. Surfaced as an unknown event so replay continues and + // the aggregate reports the gap, rather than failing the whole read. + return new EventRecord(ReturnUnknownEvent(eventRow, eventRow.Version), metadata); + + payload = unprotected; + } + + var @event = DeserializeEvent(payload, runtimeEventType); // Apply upcasting chain when a registry is available. if (@event != null && _eventUpcasterRegistry?.CanUpcast(@event) == true) diff --git a/src/src/Postgres/Events/PostgresEventStore.GetOrCreateAsync.cs b/src/src/Postgres/Events/PostgresEventStore.GetOrCreateAsync.cs index 0154910f..9d012cca 100644 --- a/src/src/Postgres/Events/PostgresEventStore.GetOrCreateAsync.cs +++ b/src/src/Postgres/Events/PostgresEventStore.GetOrCreateAsync.cs @@ -1,9 +1,12 @@ +using Purview.EventSourcing.Failures; +using Purview.Results; + namespace Purview.EventSourcing.Postgres.Events; partial class PostgresEventStore { /// - public async Task GetOrCreateAsync( + public async Task> GetOrCreateAsync( string? aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -11,8 +14,8 @@ partial class PostgresEventStore { if (!string.IsNullOrWhiteSpace(aggregateId)) { - var exists = await ExistsAsync(aggregateId, cancellationToken); - if (exists) + var existence = await ExistsAsync(aggregateId, cancellationToken); + if (existence.DoesExist) return await GetAsync(aggregateId, operationContext, cancellationToken); } diff --git a/src/src/Postgres/Events/PostgresEventStore.IsDeletedAsync.cs b/src/src/Postgres/Events/PostgresEventStore.IsDeletedAsync.cs deleted file mode 100644 index 259c34a1..00000000 --- a/src/src/Postgres/Events/PostgresEventStore.IsDeletedAsync.cs +++ /dev/null @@ -1,15 +0,0 @@ -namespace Purview.EventSourcing.Postgres.Events; - -partial class PostgresEventStore -{ - /// - public async Task IsDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) - { - ArgumentException.ThrowIfNullOrWhiteSpace(aggregateId, nameof(aggregateId)); - - var streamVersion = await GetStreamVersionAsync(aggregateId, true, cancellationToken); - return streamVersion == null - ? throw new NullReferenceException($"The aggregate specified ({aggregateId}) does not exist.") - : streamVersion.IsDeleted; - } -} diff --git a/src/src/Postgres/Events/PostgresEventStore.RestoreAsync.cs b/src/src/Postgres/Events/PostgresEventStore.RestoreAsync.cs index 7617a7f1..082cc219 100644 --- a/src/src/Postgres/Events/PostgresEventStore.RestoreAsync.cs +++ b/src/src/Postgres/Events/PostgresEventStore.RestoreAsync.cs @@ -1,12 +1,14 @@ using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.Postgres.Events; partial class PostgresEventStore { /// - public async Task RestoreAsync( + public async Task, AggregateRestoreFailure>> RestoreAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -16,7 +18,11 @@ public async Task RestoreAsync( throw NullAggregate(aggregate); if (!aggregate.Details.IsDeleted) - throw AggregateNotDeletedException(aggregate.Id()); + { + return AggregateRestoreFailure.Failure>( + new AggregateNotDeleted(aggregate.AggregateType, aggregate.Id()) + ); + } operationContext ??= EventStoreOperationContext.DefaultContext(); @@ -33,7 +39,11 @@ public async Task RestoreAsync( aggregate.ApplyEvent(restoreAggregateEvent, metadata); if (aggregate.IsNew()) - return false; + { + return AggregateRestoreFailure.Failure>( + new AggregateNotFound(aggregate.AggregateType, aggregate.Id()) + ); + } var result = await SaveCoreAsync( aggregate, @@ -43,7 +53,11 @@ public async Task RestoreAsync( cancellationToken, new EventRecord(restoreAggregateEvent, metadata) ); + if (result.Result.IsFailure) + return result.Result.Error.ToRestoreFailure(); + await result.AfterCommitAsync(cancellationToken); - return result.Result.Saved; + + return result.Result.Value; } } diff --git a/src/src/Postgres/Events/PostgresEventStore.SaveAsync.cs b/src/src/Postgres/Events/PostgresEventStore.SaveAsync.cs index 7d5e7e5a..20b6951e 100644 --- a/src/src/Postgres/Events/PostgresEventStore.SaveAsync.cs +++ b/src/src/Postgres/Events/PostgresEventStore.SaveAsync.cs @@ -2,15 +2,16 @@ using System.Diagnostics; using System.Diagnostics.CodeAnalysis; using System.Globalization; -using System.Security.Claims; using Npgsql; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; using Purview.EventSourcing.Aggregates.Snapshotting; +using Purview.EventSourcing.Cryptography; +using Purview.EventSourcing.Exceptions; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.Internal; -using Purview.EventSourcing.Postgres.Events.Exceptions; -using Purview.EventSourcing.Storage; using Purview.EventSourcing.Validation; +using Purview.Results; namespace Purview.EventSourcing.Postgres.Events; @@ -18,14 +19,19 @@ partial class PostgresEventStore { /// [DebuggerStepThrough] - public async Task> SaveAsync( + public async Task, AggregateSaveFailure>> SaveAsync( [NotNull] T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) { + var saveStopwatch = Stopwatch.StartNew(); var operation = await SaveCoreAsync(aggregate, operationContext, null, null, cancellationToken); await operation.AfterCommitAsync(cancellationToken); + + saveStopwatch.Stop(); + _metrics.RecordSave(saveStopwatch.Elapsed.TotalMilliseconds, _aggregateTypeShortName, operation.Result); + return operation.Result; } @@ -72,17 +78,15 @@ params EventRecord[] additionalEvents var validationResult = await GuardAsync(aggregate, cancellationToken); if (!validationResult.IsValid) - { - return new TransactionalSaveOperation( - SaveResultBuilder.Create(aggregate, false, false, validationResult) - ); - } + return Failed(AggregateSaveFailure.Failure>(new AggregateInvalid(validationResult))); if (aggregate.Details.Locked) { - return operationContext.LockMode is LockHandlingMode.ThrowsException - ? throw new AggregateLockedException(idempotencyId) - : new TransactionalSaveOperation(SaveResultBuilder.Create(aggregate, false, false)); + return Failed( + AggregateSaveFailure.Failure>( + new AggregateLocked(aggregate.AggregateType, aggregate.Id()) + ) + ); } if (string.IsNullOrWhiteSpace(aggregate.Details.Id)) @@ -100,7 +104,7 @@ params EventRecord[] additionalEvents ); activity?.Dispose(); - return new TransactionalSaveOperation(SaveResultBuilder.Create(aggregate, false, true)); + return Outcome(aggregate, SaveOutcomeKind.NoChanges); } var isNew = aggregate.IsNew(); @@ -132,7 +136,7 @@ params EventRecord[] additionalEvents { _eventStoreTelemetry.EventsAlreadyApplied(aggregate.Id(), idempotencyId); activity?.Dispose(); - return new TransactionalSaveOperation(SaveResultBuilder.Create(aggregate, true, true)); + return Outcome(aggregate, SaveOutcomeKind.AlreadyApplied); } } #pragma warning disable CA1031 @@ -143,7 +147,7 @@ params EventRecord[] additionalEvents } } - return await PersistAndNotifyAsync( + var persisted = await PersistAndNotifyAsync( aggregate, operationContext, idempotencyId, @@ -156,6 +160,12 @@ params EventRecord[] additionalEvents activity, cancellationToken ); + + // Only a write actually appended events; a no-op or an idempotent replay appended none. + if (persisted.Result.IsSuccess && persisted.Result.Value.Kind is SaveOutcomeKind.Written) + _metrics.EventsAppended(changeEvents.Length, _aggregateTypeShortName); + + return persisted; } [SuppressMessage( @@ -193,14 +203,15 @@ CancellationToken cancellationToken cancellationToken ); - if (streamEntity?.IsDeleted == true) + if (streamEntity?.IsDeleted == true && !changeEvents.Any(record => record.Event is Restored)) { - var throwIfDeleted = !changeEvents.Any(record => record.Event is Restored); - if (throwIfDeleted) - { - activity?.Dispose(); - throw new AggregateDeletedException(aggregate.Id(), idempotencyId); - } + activity?.Dispose(); + + return Failed( + AggregateSaveFailure.Failure>( + new AggregateDeleted(aggregate.AggregateType, aggregate.Id()) + ) + ); } try @@ -221,7 +232,7 @@ CancellationToken cancellationToken Timestamp = now, }; - var userId = ClaimsPrincipal.Current?.FindFirst(operationContext.ClaimIdentifier)?.Value; + var userId = _principalAccessor.GetPrincipal()?.FindFirst(operationContext.ClaimIdentifier)?.Value; if (operationContext.RequiresValidPrincipalIdentifier && string.IsNullOrWhiteSpace(userId)) throw new NullReferenceException( $"Missing ClaimsPrincipal identifier '{operationContext.ClaimIdentifier}'. Unable to save aggregate." @@ -239,7 +250,11 @@ CancellationToken cancellationToken CorrelationId = changeEvents[i].Metadata.CorrelationId ?? operationContext.CorrelationId, }; - var serializedEvent = SerializeEvent(changeEvent); + var serializedEvent = await ProtectIfRequiredAsync( + changeEvent, + SerializeEvent(changeEvent), + cancellationToken + ); insertRows.Add( new PostgresEventStoreClient.RowData { @@ -298,10 +313,8 @@ await SubmitBatchOperationsAsync( if (shouldSnapshot && !requireSnapshotWrite) await CreateSnapshotBestEffortAsync(aggregate, connection, transaction, cancellationToken); - var result = SaveResultBuilder.Create(aggregate, true, false); - return new TransactionalSaveOperation( - result, + new SaveOutcome(aggregate, SaveOutcomeKind.Written), async afterCommitCancellationToken => { try @@ -366,10 +379,21 @@ await _aggregateChangeNotifier.AfterSaveAsync( await HandleSaveFailureAsync(aggregate, operationContext, changeEvents, ex); + if (ex is ConcurrencyException conflict) + return Failed(AggregateSaveFailure.Failure>(ToConcurrencyConflict(aggregate, conflict))); + throw; } } + static ConcurrencyConflict ToConcurrencyConflict(T aggregate, ConcurrencyException exception) => + new(aggregate.AggregateType, aggregate.Id(), exception.VersionAttempted, exception.Version); + + static TransactionalSaveOperation Failed(Result, AggregateSaveFailure> failure) => new(failure); + + static TransactionalSaveOperation Outcome(T aggregate, SaveOutcomeKind kind) => + new(new SaveOutcome(aggregate, kind)); + async Task HandleSaveFailureAsync( T aggregate, EventStoreOperationContext operationContext, @@ -393,8 +417,14 @@ async Task GuardAsync(T aggregate, CancellationToken cancellat : await _validator.ValidateAsync(aggregate, cancellationToken); } - static bool ShouldSnapShot(T aggregate, EventRecord[] events, EventStoreOperationContext context) + bool ShouldSnapShot(T aggregate, EventRecord[] events, EventStoreOperationContext context) { + // A snapshot serializes aggregate state, which holds the same personal data as the protected + // events in clear - and one snapshot can span many subjects, so no single key can protect it. + // With protection enabled the store does not snapshot at all: a snapshot surviving key erasure + // would make crypto-shredding untrue. Replay from events stays correct, only slower. + if (_payloadProtector is not null) + return false; // Deleted/restored transitions must always be reflected promptly. if (aggregate.Details.IsDeleted || events.Any(record => record.Event is Restored)) return true; @@ -462,8 +492,12 @@ await _client.UpsertWithBatchAsync( ); } } - catch (PostgresException ex) + // Writes reach storage both directly and through Entity Framework, which wraps the provider + // exception. Unwrap it so a duplicate event-row key is classified identically on both paths. + catch (Exception outer) when (outer is PostgresException || outer.InnerException is PostgresException) { + var ex = outer as PostgresException ?? (PostgresException)outer.InnerException!; + _eventStoreTelemetry.SaveFailedAtStorage(aggregate.Id(), _aggregateTypeFullName, ex); ClearCacheFireAndForget(aggregate); @@ -645,4 +679,17 @@ connection as NpgsqlConnection static NpgsqlTransaction GetNpgsqlTransaction(DbTransaction transaction) => transaction as NpgsqlTransaction ?? throw new InvalidOperationException("PostgreSQL transactions require a NpgsqlTransaction."); + + /// + /// Encrypts a serialized payload when its event names a data subject. + /// + /// + /// Applied after serialization so the stored payload is the envelope, which keeps the persistence + /// schema unchanged. An event with no data subject, or a store with no protector configured, is + /// stored as before. + /// + Task ProtectIfRequiredAsync(object changeEvent, string serialized, CancellationToken cancellationToken) => + _payloadProtector is not null && changeEvent is IEventDataSubject dataSubject + ? _payloadProtector.ProtectAsync(serialized, dataSubject.DataSubjectId, cancellationToken) + : Task.FromResult(serialized); } diff --git a/src/src/Postgres/Events/PostgresEventStore.cs b/src/src/Postgres/Events/PostgresEventStore.cs index 9d6d5f8c..97196c83 100644 --- a/src/src/Postgres/Events/PostgresEventStore.cs +++ b/src/src/Postgres/Events/PostgresEventStore.cs @@ -8,8 +8,10 @@ using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events.Upcasting; using Purview.EventSourcing.Aggregates.Snapshotting; +using Purview.EventSourcing.Cryptography; using Purview.EventSourcing.Internal; using Purview.EventSourcing.Services; +using Purview.EventSourcing.Tenancy; using Purview.EventSourcing.Validation; namespace Purview.EventSourcing.Postgres.Events; @@ -52,6 +54,14 @@ public sealed partial class PostgresEventStore : IPostgresEventStore, ITra readonly IAggregateRequirementsManager _aggregateRequirementsManager; readonly IEventUpcasterRegistry? _eventUpcasterRegistry; + readonly IEventStorePrincipalAccessor _principalAccessor; + + readonly IEventStoreMetrics _metrics; + + readonly ICurrentTenant _currentTenant; + + readonly IEventPayloadProtector? _payloadProtector; + readonly string _aggregateTypeFullName; readonly string _aggregateTypeShortName; readonly string _eventIdPrefix; @@ -73,6 +83,10 @@ public sealed partial class PostgresEventStore : IPostgresEventStore, ITra /// Optional validator used before saving aggregates. /// Optional factory used to generate aggregate ids. /// Optional registry used to upcast historical events. + /// Optional accessor supplying the principal recorded against saved events. + /// Optional metrics recorder; defaults to a no-op. + /// Optional tenant resolver; defaults to the system scope, which applies no filter. + /// Optional payload protector; when omitted payloads are stored unencrypted. public PostgresEventStore( IAggregateEventNameMapper eventNameMapper, [NotNull] IOptions sqlServerOptions, @@ -82,7 +96,11 @@ public PostgresEventStore( IAggregateRequirementsManager aggregateRequirementsManager, IAggregateValidator? validator = null, IAggregateIdFactory? aggregateIdFactory = null, - IEventUpcasterRegistry? eventUpcasterRegistry = null + IEventUpcasterRegistry? eventUpcasterRegistry = null, + IEventStorePrincipalAccessor? principalAccessor = null, + IEventStoreMetrics? metrics = null, + ICurrentTenant? currentTenant = null, + IEventPayloadProtector? payloadProtector = null ) { _eventNameMapper = eventNameMapper; @@ -94,6 +112,10 @@ public PostgresEventStore( _aggregateChangeNotifier = aggregateChangeNotifier; _aggregateRequirementsManager = aggregateRequirementsManager; _eventUpcasterRegistry = eventUpcasterRegistry; + _principalAccessor = principalAccessor ?? new AmbientEventStorePrincipalAccessor(); + _metrics = metrics ?? NoOpEventStoreMetrics.Instance; + _currentTenant = currentTenant ?? new SystemCurrentTenant(); + _payloadProtector = payloadProtector; _aggregateTypeShortName = typeof(T).Name; _aggregateTypeFullName = typeof(T).FullName ?? _aggregateTypeShortName; @@ -107,7 +129,7 @@ public PostgresEventStore( _snapshotIdPrefix = $"snap_{_aggregateTypeShortName}_"; var clientOptions = ResolveClientOptions(sqlServerOptions.Value, _aggregateTypeShortName); - _client = new PostgresEventStoreClient(clientOptions); + _client = new PostgresEventStoreClient(clientOptions, _currentTenant); } /// @@ -245,27 +267,12 @@ CancellationToken cancellationToken return result; } - static bool ReturnAggregate(bool isDeleted, string aggregateId, EventStoreOperationContext context) - { - if (isDeleted) - { -#pragma warning disable IDE0010 // Add missing cases - switch (context.DeleteMode) - { - case DeleteHandlingMode.ThrowsException: - throw AggregateIsDeletedException(aggregateId); - case DeleteHandlingMode.ReturnsNull: - return false; - } -#pragma warning restore IDE0010 // Add missing cases - } - - return true; - } + static bool ReturnAggregate(bool isDeleted, EventStoreOperationContext context) => + !isDeleted || context.DeleteMode == DeleteHandlingMode.ReturnsAggregate; string CreateStreamVersionId(string aggregateId) => $"s_{_aggregateTypeShortName}_{aggregateId}"; - string CreateEventId(string aggregateId, int version) + string CreateEventId(string aggregateId, long version) { var versionText = version.ToString(CultureInfo.InvariantCulture); var padLength = Math.Max(0, _eventStoreOptions.Value.EventSuffixLength - versionText.Length); @@ -298,7 +305,18 @@ string CreateIdempotencyCheckId(string aggregateId, string idempotencyId) => /// The id of the aggregate. /// The cache key used for . public string CreateCacheKey(string aggregateId) => - $"{_aggregateTypeShortName}:{aggregateId}{AggregateSnapshotSchema.GetStorageSuffix()}".ToUpperInvariant(); + $"{TenantCacheScope()}{_aggregateTypeShortName}:{aggregateId}{AggregateSnapshotSchema.GetStorageSuffix()}".ToUpperInvariant(); + + /// + /// Namespaces a cache key by tenant. + /// + /// + /// The distributed cache is read before the tenant-filtered storage lookup, so an unqualified key + /// would let one tenant read another's cached aggregate straight out of a shared cache, bypassing + /// every storage filter. The system scope keeps the unqualified key, matching unowned rows. + /// + /// The tenant prefix, or an empty string under the system scope. + string TenantCacheScope() => _currentTenant.Current.IsSystem ? string.Empty : $"{_currentTenant.Current.TenantId}:"; //async Task EnsureConfiguredAsync(CancellationToken cancellationToken) //{ @@ -337,7 +355,7 @@ internal sealed class StreamVersionData public string Id { get; set; } = default!; public string AggregateId { get; set; } = default!; public string AggregateType { get; set; } = default!; - public int Version { get; set; } + public long Version { get; set; } public bool IsDeleted { get; set; } } } diff --git a/src/src/Postgres/Events/PostgresEventStoreClient.cs b/src/src/Postgres/Events/PostgresEventStoreClient.cs index 803b4a10..7e1f9b0c 100644 --- a/src/src/Postgres/Events/PostgresEventStoreClient.cs +++ b/src/src/Postgres/Events/PostgresEventStoreClient.cs @@ -5,6 +5,7 @@ using Microsoft.EntityFrameworkCore.Storage; using Npgsql; using Purview.EventSourcing.Postgres.Events.EntityFramework; +using Purview.EventSourcing.Tenancy; namespace Purview.EventSourcing.Postgres.Events; @@ -33,9 +34,12 @@ sealed partial class PostgresEventStoreClient readonly PostgresEventStoreOptions _options; readonly string _tableEnsureKey; - public PostgresEventStoreClient(PostgresEventStoreOptions options) + readonly ICurrentTenant _currentTenant; + + public PostgresEventStoreClient(PostgresEventStoreOptions options, ICurrentTenant? currentTenant = null) { _options = options ?? throw new ArgumentNullException(nameof(options)); + _currentTenant = currentTenant ?? new SystemCurrentTenant(); ValidateIdentifier(_options.SchemaName); ValidateIdentifier(_options.TableName); PostgresJsonIndexSchemaManager.ValidateOrThrow( @@ -62,7 +66,7 @@ public async Task InsertAsync( int entityType, string aggregateId, string aggregateType, - int version, + long version, bool isDeleted, string? payload, string? eventType, @@ -90,7 +94,7 @@ public async Task InsertAsync( int entityType, string aggregateId, string aggregateType, - int version, + long version, bool isDeleted, string? payload, string? eventType, @@ -133,7 +137,7 @@ public async Task UpsertAsync( int entityType, string aggregateId, string aggregateType, - int version, + long version, bool isDeleted, string? payload, string? eventType, @@ -161,7 +165,7 @@ public async Task UpsertAsync( int entityType, string aggregateId, string aggregateType, - int version, + long version, bool isDeleted, string? payload, string? eventType, @@ -195,7 +199,7 @@ public async Task UpsertAsync( int entityType, string aggregateId, string aggregateType, - int version, + long version, bool isDeleted, string? payload, string? eventType, @@ -227,7 +231,7 @@ public async Task UpsertAsync( int entityType, string aggregateId, string aggregateType, - int version, + long version, bool isDeleted, string? payload, string? eventType, @@ -270,7 +274,7 @@ public async Task UpsertWithBatchAsync( int entityType, string aggregateId, string aggregateType, - int version, + long version, bool isDeleted, string? payload, string? eventType, @@ -325,7 +329,7 @@ public async Task UpsertWithBatchAsync( int entityType, string aggregateId, string aggregateType, - int version, + long version, bool isDeleted, string? payload, string? eventType, @@ -372,7 +376,7 @@ await UpsertSnapshotInBatchAsync( await context.SaveChangesAsync(cancellationToken); } - static async Task UpsertSnapshotInBatchAsync( + async Task UpsertSnapshotInBatchAsync( EventStoreDbContext context, RowData snapshotRow, bool snapshotIsNew, @@ -496,8 +500,8 @@ public async Task DeleteByAggregateIdAsync( public async IAsyncEnumerable GetEventRangeAsync( string aggregateId, string aggregateType, - int versionFrom, - int versionTo, + long versionFrom, + long versionTo, [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default ) { @@ -665,7 +669,7 @@ EventStoreDbContext CreateContext() DbContextOptionsBuilder optionsBuilder = new(); var commandTimeout = Math.Max(1, _options.TimeoutInSeconds ?? 60); optionsBuilder.UseNpgsql(_options.ConnectionString, sql => sql.CommandTimeout(commandTimeout)); - return new(optionsBuilder.Options, _options.SchemaName, _options.TableName); + return new(optionsBuilder.Options, _options.SchemaName, _options.TableName, _currentTenant); } EventStoreDbContext CreateContext(NpgsqlConnection connection, NpgsqlTransaction? transaction) @@ -673,19 +677,24 @@ EventStoreDbContext CreateContext(NpgsqlConnection connection, NpgsqlTransaction DbContextOptionsBuilder optionsBuilder = new(); var commandTimeout = Math.Max(1, _options.TimeoutInSeconds ?? 60); optionsBuilder.UseNpgsql(connection, sql => sql.CommandTimeout(commandTimeout)); - EventStoreDbContext context = new(optionsBuilder.Options, _options.SchemaName, _options.TableName); + EventStoreDbContext context = new( + optionsBuilder.Options, + _options.SchemaName, + _options.TableName, + _currentTenant + ); if (transaction is not null) context.Database.UseTransaction(transaction); return context; } - static async Task UpsertCoreAsync( + async Task UpsertCoreAsync( EventStoreDbContext context, string id, int entityType, string aggregateId, string aggregateType, - int version, + long version, bool isDeleted, string? payload, string? eventType, @@ -725,18 +734,19 @@ CancellationToken cancellationToken entity.EventType = eventType; entity.IdempotencyId = idempotencyId; entity.SchemaVersion = schemaVersion; + entity.TenantId = _currentTenant.Current.TenantId; entity.Timestamp = timestamp; } await context.SaveChangesAsync(cancellationToken); } - static EventStoreEntity CreateEntity( + EventStoreEntity CreateEntity( string id, int entityType, string aggregateId, string aggregateType, - int version, + long version, bool isDeleted, string? payload, string? eventType, @@ -756,10 +766,13 @@ static EventStoreEntity CreateEntity( EventType = eventType, IdempotencyId = idempotencyId, SchemaVersion = schemaVersion, + TenantId = _currentTenant.Current.TenantId, Timestamp = timestamp, }; - static EventStoreEntity ToEntity(RowData row) => + // Instance, not static: the tenant is stamped here rather than at each call site, so a new write + // path cannot forget it. The query filter would then hide the row from its own tenant. + EventStoreEntity ToEntity(RowData row) => new() { Id = row.Id, @@ -775,6 +788,7 @@ static EventStoreEntity ToEntity(RowData row) => CorrelationId = row.CorrelationId, CausationId = row.CausationId, UserId = row.UserId, + TenantId = _currentTenant.Current.TenantId, Timestamp = row.Timestamp, }; @@ -841,7 +855,7 @@ public RowData() { } public int EntityType { get; init; } public string AggregateId { get; init; } = default!; public string AggregateType { get; init; } = default!; - public int Version { get; init; } + public long Version { get; init; } public bool IsDeleted { get; init; } public string? Payload { get; init; } public string? EventType { get; init; } diff --git a/src/src/Postgres/Events/PostgresEventStoreTransaction.cs b/src/src/Postgres/Events/PostgresEventStoreTransaction.cs index 28d49faa..b1ad89b4 100644 --- a/src/src/Postgres/Events/PostgresEventStoreTransaction.cs +++ b/src/src/Postgres/Events/PostgresEventStoreTransaction.cs @@ -417,8 +417,8 @@ sealed class ProcessedSaveOperation(T aggregate, TransactionalSaveOperation aggregate; - public bool Saved => operation.Result.Saved; - public bool Skipped => operation.Result.Skipped; + public bool Saved => operation.Saved; + public bool Skipped => operation.Skipped; public Task AfterCommitAsync(CancellationToken cancellationToken) => operation.AfterCommitAsync(cancellationToken); diff --git a/src/src/Postgres/Outbox/PostgresOutboxStore.cs b/src/src/Postgres/Outbox/PostgresOutboxStore.cs index 4f12b674..2a04e228 100644 --- a/src/src/Postgres/Outbox/PostgresOutboxStore.cs +++ b/src/src/Postgres/Outbox/PostgresOutboxStore.cs @@ -73,6 +73,8 @@ await ExecuteWithConnectionAsync( { await EnsureSchemaAsync(token); + // Without SKIP LOCKED a concurrent claim blocks on the same rows, then re-applies the + // outer UPDATE once the first commits - handing both dispatchers the same batch. await using NpgsqlCommand command = new( $""" UPDATE {_schema}.{_table} @@ -84,6 +86,7 @@ await ExecuteWithConnectionAsync( AND ("NextAttemptUtc" IS NULL OR "NextAttemptUtc" <= @now) ORDER BY "CreatedUtc", "Id" LIMIT @batch + FOR UPDATE SKIP LOCKED ) RETURNING "Id", "AggregateType", "AggregateId", "EventType", "PayloadJson", "IdempotencyKey", "CorrelationId", "CreatedUtc", "State", "AttemptCount", diff --git a/src/src/Postgres/Postgres.csproj b/src/src/Postgres/Postgres.csproj index 40a12a3c..1822d2b0 100644 --- a/src/src/Postgres/Postgres.csproj +++ b/src/src/Postgres/Postgres.csproj @@ -1,4 +1,4 @@ - + true Purview Event Store for PostgreSQL @@ -15,19 +15,19 @@ all runtime; build; native; contentfiles; analyzers; buildtransitive - - + diff --git a/src/src/Postgres/PostgresJsonIndexSchemaManager.cs b/src/src/Postgres/PostgresJsonIndexSchemaManager.cs index 14e4d8ed..7452b49e 100644 --- a/src/src/Postgres/PostgresJsonIndexSchemaManager.cs +++ b/src/src/Postgres/PostgresJsonIndexSchemaManager.cs @@ -99,7 +99,7 @@ static string[] ParsePath(string path) var normalized = path.Trim(); if (normalized.StartsWith("$.", StringComparison.Ordinal)) normalized = normalized[2..]; - else if (normalized.StartsWith('$')) + else if (normalized.StartsWith('$', StringComparison.Ordinal)) normalized = normalized[1..]; return normalized.Split('.', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries); diff --git a/src/src/Postgres/Sdk/README.md b/src/src/Postgres/Sdk/README.md index e88dddef..cb96ae90 100644 --- a/src/src/Postgres/Sdk/README.md +++ b/src/src/Postgres/Sdk/README.md @@ -100,5 +100,5 @@ The snapshot query model writes members through their property accessors (`Prope - [Homepage](https://purview.dev/projects/event-sourcing/) - [Documentation](https://purview.dev/docs/event-sourcing/) - [Provider feature matrix](https://github.com/purview-dev/event-sourcing/blob/main/docs/wiki/Provider-Feature-Matrix.md) - - Includes behavior notes/caveats (`IsDeletedAsync` missing behavior, tolerant replay, principal requirements) + - Includes behavior notes/caveats (`ExistsAsync` missing-stream behavior, tolerant replay, principal requirements) - Includes snapshot payload/query-translation guidance for scalar value objects vs directly mapped complex mirrors diff --git a/src/src/Postgres/Snapshots/PostgresSnapshotEventStore.EventStore.cs b/src/src/Postgres/Snapshots/PostgresSnapshotEventStore.EventStore.cs index 3a75eab5..84ff8f7a 100644 --- a/src/src/Postgres/Snapshots/PostgresSnapshotEventStore.EventStore.cs +++ b/src/src/Postgres/Snapshots/PostgresSnapshotEventStore.EventStore.cs @@ -2,7 +2,9 @@ using Npgsql; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Snapshotting; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.Internal; +using Purview.Results; namespace Purview.EventSourcing.Postgres.Snapshot; @@ -13,29 +15,29 @@ public Task CreateAsync(string? aggregateId = null, CancellationToken cancell _eventStore.CreateAsync(aggregateId, cancellationToken); /// - public Task GetOrCreateAsync( + public Task> GetOrCreateAsync( string? aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => _eventStore.GetOrCreateAsync(aggregateId, operationContext, cancellationToken); /// - public Task GetAsync( + public Task> GetAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => _eventStore.GetAsync(aggregateId, operationContext, cancellationToken); /// - public Task GetAtAsync( + public Task> GetAtAsync( string aggregateId, - int version, + long version, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => _eventStore.GetAtAsync(aggregateId, version, operationContext, cancellationToken); /// - public async Task> SaveAsync( + public async Task, AggregateSaveFailure>> SaveAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -46,8 +48,8 @@ public async Task> SaveAsync( var result = await _eventStore.SaveAsync(aggregate, operationContext, cancellationToken); if ( - result - && !result.Skipped + result.IsSuccess + && result.Value.Written && SnapshotStrategyResolver.ShouldSnapshot( aggregate, eventsApplied, @@ -110,8 +112,8 @@ CancellationToken cancellationToken try { if ( - innerOperation.Result.Saved - && !innerOperation.Result.Skipped + innerOperation.Saved + && !innerOperation.Skipped && SnapshotStrategyResolver.ShouldSnapshot( aggregate, eventsApplied, @@ -163,15 +165,13 @@ CancellationToken cancellationToken } /// - public Task IsDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) => - _eventStore.IsDeletedAsync(aggregateId, cancellationToken); - - /// - public Task GetDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) => - _eventStore.GetDeletedAsync(aggregateId, cancellationToken); + public Task> GetDeletedAsync( + string aggregateId, + CancellationToken cancellationToken = default + ) => _eventStore.GetDeletedAsync(aggregateId, cancellationToken); /// - public async Task DeleteAsync( + public async Task, AggregateDeleteFailure>> DeleteAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -185,7 +185,7 @@ public async Task DeleteAsync( try { var result = await _eventStore.DeleteAsync(aggregate, operationContext, cancellationToken); - if (result) + if (result.IsSuccess) { await _sqlServerClient.DeleteAsync(aggregate.Details.Id, cancellationToken); _telemetry.SnapshotDeleteComplete(aggregate.Details.Id, _aggregateName); @@ -201,7 +201,7 @@ public async Task DeleteAsync( } /// - public async Task RestoreAsync( + public async Task, AggregateRestoreFailure>> RestoreAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -210,7 +210,7 @@ public async Task RestoreAsync( ArgumentNullException.ThrowIfNull(aggregate, nameof(aggregate)); var result = await _eventStore.RestoreAsync(aggregate, operationContext, cancellationToken); - if (result) + if (result.IsSuccess) await SnapshotAsync(aggregate, cancellationToken); return result; @@ -223,7 +223,7 @@ public IAsyncEnumerable GetAggregateIdsAsync( ) => _eventStore.GetAggregateIdsAsync(includeDeleted, cancellationToken); /// - public Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) => + public Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) => _eventStore.ExistsAsync(aggregateId, cancellationToken); /// @@ -232,8 +232,8 @@ public Task ExistsAsync(string aggregateId, CancellationToken cance /// public IAsyncEnumerable<(EventRecord EventRecord, string EventType)> GetEventRangeAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, CancellationToken cancellationToken ) => _eventStore.GetEventRangeAsync(aggregateId, versionFrom, versionTo, cancellationToken); diff --git a/src/src/Postgres/Snapshots/PostgresSnapshotEventStore.cs b/src/src/Postgres/Snapshots/PostgresSnapshotEventStore.cs index 6c1175d5..7b17bab1 100644 --- a/src/src/Postgres/Snapshots/PostgresSnapshotEventStore.cs +++ b/src/src/Postgres/Snapshots/PostgresSnapshotEventStore.cs @@ -4,6 +4,7 @@ using Purview.EventSourcing.Internal; using Purview.EventSourcing.Postgres.Client; using Purview.EventSourcing.Postgres.Snapshots; +using Purview.EventSourcing.Tenancy; namespace Purview.EventSourcing.Postgres.Snapshot; @@ -39,13 +40,15 @@ public sealed partial class PostgresSnapshotEventStore : IPostgresSnapshotEve /// The telemetry sink for snapshot operations. /// Optional strategy controlling when snapshots are written; defaults to snapshotting always. /// Optional selector used to pick a snapshot strategy per aggregate. + /// Optional tenant scope applied to snapshot reads and writes. public PostgresSnapshotEventStore( // Explicitly request a non-queryable event store. INonQueryableEventStore eventStore, IOptions sqlServerEventStoreOptions, IPostgresSnapshotEventStoreTelemetry telemetry, ISnapshotStrategy? snapshotStrategy = null, - ISnapshotStrategySelector? snapshotStrategySelector = null + ISnapshotStrategySelector? snapshotStrategySelector = null, + ICurrentTenant? currentTenant = null ) { _eventStore = eventStore; @@ -57,7 +60,7 @@ public PostgresSnapshotEventStore( _aggregateName = TypeNameHelper.GetName(_aggregateType, "Aggregate"); var clientOptions = ResolveClientOptions(_sqlServerEventStoreOptions.Value, _aggregateName); - _sqlServerClient = new(clientOptions); + _sqlServerClient = new(clientOptions, currentTenant); } /// diff --git a/src/src/Samples.QuickStart/Infrastructure/InMemoryTransactionalEventStore.cs b/src/src/Samples.QuickStart/Infrastructure/InMemoryTransactionalEventStore.cs index 24c4f177..2779bdb0 100644 --- a/src/src/Samples.QuickStart/Infrastructure/InMemoryTransactionalEventStore.cs +++ b/src/src/Samples.QuickStart/Infrastructure/InMemoryTransactionalEventStore.cs @@ -7,8 +7,9 @@ using System.Runtime.CompilerServices; using System.Text.Json; using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.Internal; -using Purview.EventSourcing.Validation; +using Purview.Results; namespace Purview.EventSourcing.Samples.QuickStart.Infrastructure; @@ -20,6 +21,9 @@ sealed class InMemoryTransactionalEventStore(InMemoryFailurePlan failurePlan) { static readonly ConcurrentDictionary Persisted = new(StringComparer.OrdinalIgnoreCase); + static Result NotFound(string aggregateId) => + AggregateReadFailure.Failure(new AggregateNotFound(typeof(T).Name, aggregateId)); + public string TransactionBoundaryKey => "quickstart-inmemory"; public Task CreateAsync(string? aggregateId = null, CancellationToken cancellationToken = default) @@ -34,7 +38,7 @@ public Task CreateAsync(string? aggregateId = null, CancellationToken cancell return Task.FromResult(aggregate); } - public async Task GetOrCreateAsync( + public async Task> GetOrCreateAsync( string? aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -43,31 +47,35 @@ public Task CreateAsync(string? aggregateId = null, CancellationToken cancell if (!string.IsNullOrWhiteSpace(aggregateId)) { var existing = await GetAsync(aggregateId, operationContext, cancellationToken); - if (existing is not null) + if (existing.IsSuccess) return existing; } return await CreateAsync(aggregateId, cancellationToken); } - public Task GetAsync( + public Task> GetAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default - ) => Task.FromResult(Persisted.TryGetValue(aggregateId, out var json) ? Deserialize(json) : default); + ) => + Task.FromResult>( + Persisted.TryGetValue(aggregateId, out var json) ? Deserialize(json) : NotFound(aggregateId) + ); - public async Task GetAtAsync( + public async Task> GetAtAsync( string aggregateId, - int version, + long version, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) { - var aggregate = await GetAsync(aggregateId, operationContext, cancellationToken); - return aggregate?.Details.CurrentVersion == version ? aggregate : null; + var result = await GetAsync(aggregateId, operationContext, cancellationToken); + + return result.IsSuccess && result.Value.Details.CurrentVersion == version ? result : NotFound(aggregateId); } - public Task> SaveAsync( + public Task, AggregateSaveFailure>> SaveAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -84,19 +92,18 @@ public Task> SaveAsync( return Task.FromResult(CreateSavedResult(aggregate)); } - public Task IsDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) => - Task.FromResult(false); - - public Task GetDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) => - Task.FromResult(default); + public Task> GetDeletedAsync( + string aggregateId, + CancellationToken cancellationToken = default + ) => Task.FromResult(NotFound(aggregateId)); - public Task DeleteAsync( + public Task, AggregateDeleteFailure>> DeleteAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => throw new NotSupportedException("The quick start store only demonstrates create, load, query, and save."); - public Task RestoreAsync( + public Task, AggregateRestoreFailure>> RestoreAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -113,19 +120,19 @@ public async IAsyncEnumerable GetAggregateIdsAsync( await Task.CompletedTask; } - public Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) + public Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) { return !Persisted.TryGetValue(aggregateId, out var json) - ? Task.FromResult(ExistsState.DoesNotExist) - : Task.FromResult(new ExistsState(ExistsStatus.Exists, Deserialize(json).Details.CurrentVersion)); + ? Task.FromResult(AggregateExistence.DoesNotExist) + : Task.FromResult(new AggregateExistence(ExistenceStatus.Exists, Deserialize(json).Details.CurrentVersion)); } public T FulfilRequirements(T aggregate) => aggregate; public IAsyncEnumerable<(EventRecord EventRecord, string EventType)> GetEventRangeAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, CancellationToken cancellationToken ) => throw new NotSupportedException("The quick start store only demonstrates create, load, query, and save."); @@ -264,11 +271,11 @@ static T Deserialize(string json) return aggregate; } - static SaveResult CreateSavedResult(T aggregate) => - new(aggregate, new ValidationResult(), saved: true, skipped: false); + static Result, AggregateSaveFailure> CreateSavedResult(T aggregate) => + new SaveOutcome(aggregate, SaveOutcomeKind.Written); - static SaveResult CreateSkippedResult(T aggregate) => - new(aggregate, new ValidationResult(), saved: false, skipped: true); + static Result, AggregateSaveFailure> CreateSkippedResult(T aggregate) => + new SaveOutcome(aggregate, SaveOutcomeKind.NoChanges); static void MarkAsSaved(T aggregate) { diff --git a/src/src/Samples.QuickStart/Program.cs b/src/src/Samples.QuickStart/Program.cs index d99f58f3..1e90196c 100644 --- a/src/src/Samples.QuickStart/Program.cs +++ b/src/src/Samples.QuickStart/Program.cs @@ -1,6 +1,8 @@ using Microsoft.Extensions.DependencyInjection; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.Samples.Domain; using Purview.EventSourcing.Samples.QuickStart.Infrastructure; +using Purview.Results; EventStoreOperationContext.RequiresValidPrincipalIdentifierDefault = false; @@ -60,13 +62,10 @@ static async Task RunSuccessfulCheckoutAsync( IEventStoreTransactionFactory transactionFactory ) { - var customer = await store.GetAsync("customer-quickstart"); - var keyboard = await store.GetAsync("inventory-keyboard"); - var dock = await store.GetAsync("inventory-dock"); - - ArgumentNullException.ThrowIfNull(customer); - ArgumentNullException.ThrowIfNull(keyboard); - ArgumentNullException.ThrowIfNull(dock); + // The seeded aggregates must be there; a failure here is a broken sample, not an expected outcome. + var customer = (await store.GetAsync("customer-quickstart")).Value; + var keyboard = (await store.GetAsync("inventory-keyboard")).Value; + var dock = (await store.GetAsync("inventory-dock")).Value; var order = await store.CreateAsync("order-success"); order @@ -99,13 +98,10 @@ static async Task RunRollbackDemoAsync( InMemoryFailurePlan failurePlan ) { - var customer = await store.GetAsync("customer-quickstart"); - var keyboard = await store.GetAsync("inventory-keyboard"); - var dock = await store.GetAsync("inventory-dock"); - - ArgumentNullException.ThrowIfNull(customer); - ArgumentNullException.ThrowIfNull(keyboard); - ArgumentNullException.ThrowIfNull(dock); + // The seeded aggregates must be there; a failure here is a broken sample, not an expected outcome. + var customer = (await store.GetAsync("customer-quickstart")).Value; + var keyboard = (await store.GetAsync("inventory-keyboard")).Value; + var dock = (await store.GetAsync("inventory-dock")).Value; var order = await store.CreateAsync("order-rollback"); order.CreateOrder(customer.Id()); @@ -131,23 +127,25 @@ InMemoryFailurePlan failurePlan Console.WriteLine("Rollback when one enlisted aggregate fails"); Console.WriteLine($"Correlation: {transaction.CorrelationId}"); PrintTransactionResult(result); - Console.WriteLine($"Rolled-back order persisted: {persistedOrder is not null}"); + Console.WriteLine($"Rolled-back order persisted: {persistedOrder.IsSuccess}"); Console.WriteLine($"Committed order count: {orderCount}"); await PrintInventorySnapshotAsync(store, "Committed stock after rollback"); } static async Task PrintOrderSnapshotAsync(IQueryableEventStore store, string title, string orderId) { - var order = await store.GetAsync(orderId); + var result = await store.GetAsync(orderId); Console.WriteLine(title); - if (order is null) + if (result.IsFailure) { Console.WriteLine(" (not found)"); Console.WriteLine(); return; } + var order = result.Value; + Console.WriteLine($" {order.Id()} status={order.Status} total={order.TotalAmount:C}"); Console.WriteLine(); } @@ -158,11 +156,14 @@ static async Task PrintInventorySnapshotAsync(IQueryableEventStore store, string var dock = await store.GetAsync("inventory-dock"); Console.WriteLine(title); - Console.WriteLine( - $" inventory-keyboard available={keyboard?.AvailableQuantity} reserved={keyboard?.ReservedQuantity}" - ); - Console.WriteLine($" inventory-dock available={dock?.AvailableQuantity} reserved={dock?.ReservedQuantity}"); + Console.WriteLine($" inventory-keyboard {Describe(keyboard)}"); + Console.WriteLine($" inventory-dock {Describe(dock)}"); Console.WriteLine(); + + static string Describe(Result result) => + result.IsFailure + ? "(not found)" + : $"available={result.Value.AvailableQuantity} reserved={result.Value.ReservedQuantity}"; } static void PrintTransactionResult(TransactionResult result) diff --git a/src/src/Samples.QuickStart/ValidatorScenarios.cs b/src/src/Samples.QuickStart/ValidatorScenarios.cs index cdcc1b05..0803449e 100644 --- a/src/src/Samples.QuickStart/ValidatorScenarios.cs +++ b/src/src/Samples.QuickStart/ValidatorScenarios.cs @@ -1,6 +1,8 @@ -using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.DependencyInjection; using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.Samples.Domain; +using Purview.Results; namespace Purview.EventSourcing.Samples.QuickStart; @@ -24,9 +26,12 @@ IServiceProvider BuildServices(Action? action = null) return scope.ServiceProvider; } + // Registered first so the phone number is the only thing wrong with the aggregate: ZodSharp validates + // the whole graph, and an unregistered customer also fails on its null name and email. static CustomerAggregate CreateAggregate(int numberOfChars = 200) { CustomerAggregate agg = new(); + agg.RegisterCustomer("Quick Start", "quickstart@example.com"); return agg.ChangePhoneNumber(new string('1', numberOfChars)); } @@ -74,21 +79,25 @@ async Task ValidateZodSharpAsync(CancellationToken cancellationToken) DisplaySummary("ZodSharp", result); } - static void DisplaySummary(string type, SaveResult result) + static void DisplaySummary(string type, Result, AggregateSaveFailure> result) { Console.WriteLine($"Validated '{type}':"); - if (result.IsValid) + + if (result.IsSuccess || result.Error is not AggregateInvalid invalid) Console.WriteLine(" FAILED: Did not validate correctly!!"); else { - if (result.FailureCount != 1) - Console.WriteLine($" FAILED: Should be exactly 1 error, but found {result.FailureCount}"); - else if (result.ValidationResult.Failures[0].PropertyName != nameof(CustomerAggregate.PhoneNumber)) + var failures = invalid.ValidationResult.Failures; + if (failures.Length != 1) + Console.WriteLine( + $" FAILED: Should be exactly 1 error, but found {failures.Length}: {string.Join(" | ", failures.Select(f => $"{f.PropertyName}={f.ErrorMessage}"))}" + ); + else if (failures[0].PropertyName != nameof(CustomerAggregate.PhoneNumber)) Console.WriteLine( - $" FAILED: Error should have validatedd '{nameof(CustomerAggregate.PhoneNumber)}', but found '{result.ValidationResult.Failures[0].PropertyName}'" + $" FAILED: Error should have validated '{nameof(CustomerAggregate.PhoneNumber)}', but found '{failures[0].PropertyName}'" ); else - Console.WriteLine($" SUCCESS: Found {result.ValidationResult.Failures[0].ErrorMessage}"); + Console.WriteLine($" SUCCESS: Found {failures[0].ErrorMessage}"); } Console.WriteLine(); diff --git a/src/src/Samples.Web/Infrastructure/EventSourcingPageModel.cs b/src/src/Samples.Web/Infrastructure/EventSourcingPageModel.cs index 17023303..04eafe49 100644 --- a/src/src/Samples.Web/Infrastructure/EventSourcingPageModel.cs +++ b/src/src/Samples.Web/Infrastructure/EventSourcingPageModel.cs @@ -1,13 +1,15 @@ using Microsoft.AspNetCore.Mvc; using Microsoft.AspNetCore.Mvc.RazorPages; -using Purview.EventSourcing.SqlServer.Events.Exceptions; +using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.Samples.Web.Infrastructure; /// /// Base page model that provides a helper for wrapping event-store saves with -/// typed concurrency-conflict handling. A -/// is surfaced as a user-friendly TempData error rather than an unhandled 500. +/// typed failure handling, surfaced as a user-friendly TempData message rather +/// than an unhandled 500. /// abstract class EventSourcingPageModel : PageModel { @@ -16,20 +18,38 @@ abstract class EventSourcingPageModel : PageModel + "The page has been refreshed — please review and resubmit your change."; /// - /// Executes , sets a success or conflict message, + /// Executes , sets a success or failure message, /// and returns in both cases. /// - protected async Task TrySaveAsync(Func saveAction, string successMessage, IActionResult result) + /// + /// The save returns its failure rather than throwing, so the outcome has to be inspected: a page + /// that ignored it would report success for a write that never happened. + /// + protected async Task TrySaveAsync( + Func, AggregateSaveFailure>>> saveAction, + string successMessage, + IActionResult result + ) + where TAggregate : class, IAggregate, new() { - try + var saveResult = await saveAction(); + if (saveResult.IsSuccess) { - await saveAction(); TempData["Success"] = successMessage; + return result; } - catch (ConcurrencyException) + + TempData["Error"] = saveResult.Error switch { - TempData["Error"] = ConflictMessage; - } + ConcurrencyConflict => ConflictMessage, + AggregateLocked => "This record is locked and cannot be changed.", + AggregateDeleted => "This record has been deleted.", + AggregateInvalid invalid => string.Join( + " ", + invalid.ValidationResult.Failures.Select(failure => failure.ErrorMessage) + ), + _ => "The change could not be saved.", + }; return result; } diff --git a/src/src/Samples.Web/Pages/BackOffice/Catalog/Create.cshtml.cs b/src/src/Samples.Web/Pages/BackOffice/Catalog/Create.cshtml.cs index 5fb8b65c..31290ee2 100644 --- a/src/src/Samples.Web/Pages/BackOffice/Catalog/Create.cshtml.cs +++ b/src/src/Samples.Web/Pages/BackOffice/Catalog/Create.cshtml.cs @@ -41,7 +41,8 @@ public async Task OnPostAsync() var productName = ProductName.Trim(); var locationId = LocationId.Trim(); - var location = await store.GetAsync(locationId, ct); + var locationResult = await store.GetAsync(locationId, ct); + var location = locationResult.IsSuccess ? locationResult.Value : null; if (location is null || location.Details.IsDeleted) { ModelState.AddModelError(nameof(LocationId), "Please select a valid physical location."); diff --git a/src/src/Samples.Web/Pages/BackOffice/Catalog/Deleted.cshtml.cs b/src/src/Samples.Web/Pages/BackOffice/Catalog/Deleted.cshtml.cs index 4f4e86b3..283bf4e6 100644 --- a/src/src/Samples.Web/Pages/BackOffice/Catalog/Deleted.cshtml.cs +++ b/src/src/Samples.Web/Pages/BackOffice/Catalog/Deleted.cshtml.cs @@ -15,9 +15,10 @@ public async Task OnGetAsync() var id in store.GetAggregateIdsAsync(includeDeleted: true, HttpContext.RequestAborted) ) { - if (await store.IsDeletedAsync(id, HttpContext.RequestAborted)) + if ((await store.ExistsAsync(id, HttpContext.RequestAborted)).IsDeleted) { - var aggregate = await store.GetDeletedAsync(id, HttpContext.RequestAborted); + var aggregateResult = await store.GetDeletedAsync(id, HttpContext.RequestAborted); + var aggregate = aggregateResult.IsSuccess ? aggregateResult.Value : null; if (aggregate != null) deleted.Add(aggregate); } @@ -28,7 +29,8 @@ var id in store.GetAggregateIdsAsync(includeDeleted: true, H public async Task OnPostRestoreAsync(string id) { - var item = await store.GetDeletedAsync(id, HttpContext.RequestAborted); + var itemResult = await store.GetDeletedAsync(id, HttpContext.RequestAborted); + var item = itemResult.IsSuccess ? itemResult.Value : null; if (item == null) return NotFound(); diff --git a/src/src/Samples.Web/Pages/BackOffice/Catalog/Edit.cshtml.cs b/src/src/Samples.Web/Pages/BackOffice/Catalog/Edit.cshtml.cs index 0d5a8a85..cc833726 100644 --- a/src/src/Samples.Web/Pages/BackOffice/Catalog/Edit.cshtml.cs +++ b/src/src/Samples.Web/Pages/BackOffice/Catalog/Edit.cshtml.cs @@ -12,21 +12,23 @@ sealed class EditModel(IQueryableEventStore store, IProductImageService imageSer public async Task OnGetAsync(string id) { - Item = await store.GetAsync(id, HttpContext.RequestAborted); + var itemResult = await store.GetAsync(id, HttpContext.RequestAborted); + Item = itemResult.IsSuccess ? itemResult.Value : null; if (Item != null) CurrentImageUrl = await imageService.GetImageUrlAsync(Item.ProductId, HttpContext.RequestAborted); } public async Task OnPostUpdateProductNameAsync(string id, string productName) { - var item = await store.GetAsync(id, HttpContext.RequestAborted); + var itemResult = await store.GetAsync(id, HttpContext.RequestAborted); + var item = itemResult.IsSuccess ? itemResult.Value : null; return item == null ? NotFound() : await TrySaveAsync( async () => { item.UpdateDetails(productName: productName.Trim()); - await store.SaveAsync(item, HttpContext.RequestAborted); + return await store.SaveAsync(item, HttpContext.RequestAborted); }, "Product name updated.", RedirectToPage(new { id }) @@ -41,7 +43,8 @@ public async Task OnPostUploadImageAsync(string id, IFormFile? im return RedirectToPage(new { id }); } - var item = await store.GetAsync(id, HttpContext.RequestAborted); + var itemResult = await store.GetAsync(id, HttpContext.RequestAborted); + var item = itemResult.IsSuccess ? itemResult.Value : null; if (item == null) return NotFound(); @@ -61,7 +64,8 @@ public async Task OnPostUploadImageAsync(string id, IFormFile? im public async Task OnPostDeleteImageAsync(string id) { - var item = await store.GetAsync(id, HttpContext.RequestAborted); + var itemResult = await store.GetAsync(id, HttpContext.RequestAborted); + var item = itemResult.IsSuccess ? itemResult.Value : null; if (item == null) return NotFound(); diff --git a/src/src/Samples.Web/Pages/BackOffice/Catalog/Index.cshtml.cs b/src/src/Samples.Web/Pages/BackOffice/Catalog/Index.cshtml.cs index fdc4d946..0fd889ca 100644 --- a/src/src/Samples.Web/Pages/BackOffice/Catalog/Index.cshtml.cs +++ b/src/src/Samples.Web/Pages/BackOffice/Catalog/Index.cshtml.cs @@ -77,7 +77,8 @@ public async Task OnGetAsync() public async Task OnPostArchiveAsync(string id) { - var item = await store.GetAsync(id, HttpContext.RequestAborted); + var itemResult = await store.GetAsync(id, HttpContext.RequestAborted); + var item = itemResult.IsSuccess ? itemResult.Value : null; if (item != null) { await store.DeleteAsync(item, HttpContext.RequestAborted); diff --git a/src/src/Samples.Web/Pages/BackOffice/Customers/Deleted.cshtml.cs b/src/src/Samples.Web/Pages/BackOffice/Customers/Deleted.cshtml.cs index 335a33e9..810a2d3d 100644 --- a/src/src/Samples.Web/Pages/BackOffice/Customers/Deleted.cshtml.cs +++ b/src/src/Samples.Web/Pages/BackOffice/Customers/Deleted.cshtml.cs @@ -15,9 +15,10 @@ public async Task OnGetAsync() var id in store.GetAggregateIdsAsync(includeDeleted: true, HttpContext.RequestAborted) ) { - if (await store.IsDeletedAsync(id, HttpContext.RequestAborted)) + if ((await store.ExistsAsync(id, HttpContext.RequestAborted)).IsDeleted) { - var aggregate = await store.GetDeletedAsync(id, HttpContext.RequestAborted); + var aggregateResult = await store.GetDeletedAsync(id, HttpContext.RequestAborted); + var aggregate = aggregateResult.IsSuccess ? aggregateResult.Value : null; if (aggregate != null) deleted.Add(aggregate); } @@ -28,7 +29,8 @@ var id in store.GetAggregateIdsAsync(includeDeleted: true, Ht public async Task OnPostRestoreAsync(string id) { - var customer = await store.GetDeletedAsync(id, HttpContext.RequestAborted); + var customerResult = await store.GetDeletedAsync(id, HttpContext.RequestAborted); + var customer = customerResult.IsSuccess ? customerResult.Value : null; if (customer == null) return NotFound(); diff --git a/src/src/Samples.Web/Pages/BackOffice/Customers/Edit.cshtml.cs b/src/src/Samples.Web/Pages/BackOffice/Customers/Edit.cshtml.cs index b464cd07..0801a3d5 100644 --- a/src/src/Samples.Web/Pages/BackOffice/Customers/Edit.cshtml.cs +++ b/src/src/Samples.Web/Pages/BackOffice/Customers/Edit.cshtml.cs @@ -10,7 +10,8 @@ sealed class EditModel(IQueryableEventStore store) : EventSourcingPageModel public async Task OnGetAsync(string id) { - Customer = await store.GetAsync(id, HttpContext.RequestAborted); + var customerResult = await store.GetAsync(id, HttpContext.RequestAborted); + Customer = customerResult.IsSuccess ? customerResult.Value : null; } public async Task OnPostChangeNameAsync(string id, string newName) @@ -21,14 +22,15 @@ public async Task OnPostChangeNameAsync(string id, string newName return RedirectToPage(new { id }); } - var customer = await store.GetAsync(id, HttpContext.RequestAborted); + var customerResult = await store.GetAsync(id, HttpContext.RequestAborted); + var customer = customerResult.IsSuccess ? customerResult.Value : null; return customer == null ? NotFound() : await TrySaveAsync( async () => { customer.ChangeName(newName); - await store.SaveAsync(customer, HttpContext.RequestAborted); + return await store.SaveAsync(customer, HttpContext.RequestAborted); }, "Name updated.", RedirectToPage(new { id }) @@ -37,14 +39,15 @@ public async Task OnPostChangeNameAsync(string id, string newName public async Task OnPostChangeEmailAsync(string id, string newEmail) { - var customer = await store.GetAsync(id, HttpContext.RequestAborted); + var customerResult = await store.GetAsync(id, HttpContext.RequestAborted); + var customer = customerResult.IsSuccess ? customerResult.Value : null; return customer == null ? NotFound() : await TrySaveAsync( async () => { customer.ChangeEmail(newEmail); - await store.SaveAsync(customer, HttpContext.RequestAborted); + return await store.SaveAsync(customer, HttpContext.RequestAborted); }, "Email updated.", RedirectToPage(new { id }) @@ -53,14 +56,15 @@ public async Task OnPostChangeEmailAsync(string id, string newEma public async Task OnPostChangePhoneAsync(string id, string? phoneNumber) { - var customer = await store.GetAsync(id, HttpContext.RequestAborted); + var customerResult = await store.GetAsync(id, HttpContext.RequestAborted); + var customer = customerResult.IsSuccess ? customerResult.Value : null; return customer == null ? NotFound() : await TrySaveAsync( async () => { customer.ChangePhoneNumber(phoneNumber); - await store.SaveAsync(customer, HttpContext.RequestAborted); + return await store.SaveAsync(customer, HttpContext.RequestAborted); }, "Phone number updated.", RedirectToPage(new { id }) @@ -69,14 +73,15 @@ public async Task OnPostChangePhoneAsync(string id, string? phone public async Task OnPostDeactivateAsync(string id) { - var customer = await store.GetAsync(id, HttpContext.RequestAborted); + var customerResult = await store.GetAsync(id, HttpContext.RequestAborted); + var customer = customerResult.IsSuccess ? customerResult.Value : null; return customer == null ? NotFound() : await TrySaveAsync( async () => { customer.Deactivate(); - await store.SaveAsync(customer, HttpContext.RequestAborted); + return await store.SaveAsync(customer, HttpContext.RequestAborted); }, "Customer deactivated.", RedirectToPage(new { id }) @@ -85,14 +90,15 @@ public async Task OnPostDeactivateAsync(string id) public async Task OnPostReactivateAsync(string id) { - var customer = await store.GetAsync(id, HttpContext.RequestAborted); + var customerResult = await store.GetAsync(id, HttpContext.RequestAborted); + var customer = customerResult.IsSuccess ? customerResult.Value : null; return customer == null ? NotFound() : await TrySaveAsync( async () => { customer.Reactivate(); - await store.SaveAsync(customer, HttpContext.RequestAborted); + return await store.SaveAsync(customer, HttpContext.RequestAborted); }, "Customer reactivated.", RedirectToPage(new { id }) diff --git a/src/src/Samples.Web/Pages/BackOffice/Customers/Index.cshtml.cs b/src/src/Samples.Web/Pages/BackOffice/Customers/Index.cshtml.cs index c0364ee5..c70d7fea 100644 --- a/src/src/Samples.Web/Pages/BackOffice/Customers/Index.cshtml.cs +++ b/src/src/Samples.Web/Pages/BackOffice/Customers/Index.cshtml.cs @@ -86,7 +86,8 @@ public async Task OnGetAsync() public async Task OnPostArchiveAsync(string id) { - var customer = await store.GetAsync(id, HttpContext.RequestAborted); + var customerResult = await store.GetAsync(id, HttpContext.RequestAborted); + var customer = customerResult.IsSuccess ? customerResult.Value : null; if (customer != null) { await store.DeleteAsync(customer, HttpContext.RequestAborted); diff --git a/src/src/Samples.Web/Pages/BackOffice/Stock/Create.cshtml.cs b/src/src/Samples.Web/Pages/BackOffice/Stock/Create.cshtml.cs index af5447cc..bc62d551 100644 --- a/src/src/Samples.Web/Pages/BackOffice/Stock/Create.cshtml.cs +++ b/src/src/Samples.Web/Pages/BackOffice/Stock/Create.cshtml.cs @@ -41,7 +41,8 @@ public async Task OnPostAsync() var productName = ProductName.Trim(); var locationId = LocationId.Trim(); - var location = await store.GetAsync(locationId, ct); + var locationResult = await store.GetAsync(locationId, ct); + var location = locationResult.IsSuccess ? locationResult.Value : null; if (location is null || location.Details.IsDeleted) { ModelState.AddModelError(nameof(LocationId), "Please select a valid physical location."); diff --git a/src/src/Samples.Web/Pages/BackOffice/Stock/Deleted.cshtml.cs b/src/src/Samples.Web/Pages/BackOffice/Stock/Deleted.cshtml.cs index 7d98f18d..2b0b50eb 100644 --- a/src/src/Samples.Web/Pages/BackOffice/Stock/Deleted.cshtml.cs +++ b/src/src/Samples.Web/Pages/BackOffice/Stock/Deleted.cshtml.cs @@ -15,9 +15,10 @@ public async Task OnGetAsync() var id in store.GetAggregateIdsAsync(includeDeleted: true, HttpContext.RequestAborted) ) { - if (await store.IsDeletedAsync(id, HttpContext.RequestAborted)) + if ((await store.ExistsAsync(id, HttpContext.RequestAborted)).IsDeleted) { - var aggregate = await store.GetDeletedAsync(id, HttpContext.RequestAborted); + var aggregateResult = await store.GetDeletedAsync(id, HttpContext.RequestAborted); + var aggregate = aggregateResult.IsSuccess ? aggregateResult.Value : null; if (aggregate != null) deleted.Add(aggregate); } @@ -28,7 +29,8 @@ var id in store.GetAggregateIdsAsync(includeDeleted: true, H public async Task OnPostRestoreAsync(string id) { - var item = await store.GetDeletedAsync(id, HttpContext.RequestAborted); + var itemResult = await store.GetDeletedAsync(id, HttpContext.RequestAborted); + var item = itemResult.IsSuccess ? itemResult.Value : null; if (item == null) return NotFound(); diff --git a/src/src/Samples.Web/Pages/BackOffice/Stock/Edit.cshtml.cs b/src/src/Samples.Web/Pages/BackOffice/Stock/Edit.cshtml.cs index b6eafc41..9c8ce7b1 100644 --- a/src/src/Samples.Web/Pages/BackOffice/Stock/Edit.cshtml.cs +++ b/src/src/Samples.Web/Pages/BackOffice/Stock/Edit.cshtml.cs @@ -10,19 +10,21 @@ sealed class EditModel(IQueryableEventStore store) : EventSourcingPageModel public async Task OnGetAsync(string id) { - Item = await store.GetAsync(id, HttpContext.RequestAborted); + var itemResult = await store.GetAsync(id, HttpContext.RequestAborted); + Item = itemResult.IsSuccess ? itemResult.Value : null; } public async Task OnPostReceiveStockAsync(string id, int quantity) { - var item = await store.GetAsync(id, HttpContext.RequestAborted); + var itemResult = await store.GetAsync(id, HttpContext.RequestAborted); + var item = itemResult.IsSuccess ? itemResult.Value : null; return item == null ? NotFound() : await TrySaveAsync( async () => { item.ReceiveStock(quantity); - await store.SaveAsync(item, HttpContext.RequestAborted); + return await store.SaveAsync(item, HttpContext.RequestAborted); }, $"Received {quantity} unit(s).", RedirectToPage(new { id }) @@ -31,14 +33,15 @@ public async Task OnPostReceiveStockAsync(string id, int quantity public async Task OnPostAdjustStockAsync(string id, int newQuantity, string reason) { - var item = await store.GetAsync(id, HttpContext.RequestAborted); + var itemResult = await store.GetAsync(id, HttpContext.RequestAborted); + var item = itemResult.IsSuccess ? itemResult.Value : null; return item == null ? NotFound() : await TrySaveAsync( async () => { item.AdjustStock(newQuantity, reason.Trim()); - await store.SaveAsync(item, HttpContext.RequestAborted); + return await store.SaveAsync(item, HttpContext.RequestAborted); }, $"Stock adjusted to {newQuantity}.", RedirectToPage(new { id }) @@ -47,14 +50,15 @@ public async Task OnPostAdjustStockAsync(string id, int newQuanti public async Task OnPostReserveStockAsync(string id, int quantity, string orderId) { - var item = await store.GetAsync(id, HttpContext.RequestAborted); + var itemResult = await store.GetAsync(id, HttpContext.RequestAborted); + var item = itemResult.IsSuccess ? itemResult.Value : null; return item == null ? NotFound() : await TrySaveAsync( async () => { item.ReserveStock(quantity, orderId.Trim()); - await store.SaveAsync(item, HttpContext.RequestAborted); + return await store.SaveAsync(item, HttpContext.RequestAborted); }, $"Reserved {quantity} unit(s) for order {orderId}.", RedirectToPage(new { id }) @@ -63,14 +67,15 @@ public async Task OnPostReserveStockAsync(string id, int quantity public async Task OnPostReleaseReservationAsync(string id, int quantity, string orderId) { - var item = await store.GetAsync(id, HttpContext.RequestAborted); + var itemResult = await store.GetAsync(id, HttpContext.RequestAborted); + var item = itemResult.IsSuccess ? itemResult.Value : null; return item == null ? NotFound() : await TrySaveAsync( async () => { item.ReleaseReservation(quantity, orderId.Trim()); - await store.SaveAsync(item, HttpContext.RequestAborted); + return await store.SaveAsync(item, HttpContext.RequestAborted); }, $"Released {quantity} unit(s) for order {orderId}.", RedirectToPage(new { id }) @@ -79,14 +84,15 @@ public async Task OnPostReleaseReservationAsync(string id, int qu public async Task OnPostShipStockAsync(string id, int quantity, string orderId) { - var item = await store.GetAsync(id, HttpContext.RequestAborted); + var itemResult = await store.GetAsync(id, HttpContext.RequestAborted); + var item = itemResult.IsSuccess ? itemResult.Value : null; return item == null ? NotFound() : await TrySaveAsync( async () => { item.ShipStock(quantity, orderId.Trim()); - await store.SaveAsync(item, HttpContext.RequestAborted); + return await store.SaveAsync(item, HttpContext.RequestAborted); }, $"Shipped {quantity} unit(s) for order {orderId}.", RedirectToPage(new { id }) diff --git a/src/src/Samples.Web/Pages/BackOffice/Stock/Transfer.cshtml.cs b/src/src/Samples.Web/Pages/BackOffice/Stock/Transfer.cshtml.cs index 853975b0..066b0d4f 100644 --- a/src/src/Samples.Web/Pages/BackOffice/Stock/Transfer.cshtml.cs +++ b/src/src/Samples.Web/Pages/BackOffice/Stock/Transfer.cshtml.cs @@ -3,7 +3,6 @@ using Microsoft.AspNetCore.Mvc.Rendering; using Purview.EventSourcing.Samples.Domain; using Purview.EventSourcing.Samples.Services; -using Purview.EventSourcing.SqlServer.Events.Exceptions; namespace Purview.EventSourcing.Samples.Web.Pages.BackOffice.Stock; @@ -48,26 +47,13 @@ public async Task OnPostAsync() return Page(); } - StockTransferResult result; - try - { - result = await transferService.TransferAsync( - SourceInventoryId, - DestinationLocationId, - Quantity, - Reason.Trim(), - ct - ); - } - catch (ConcurrencyException) - { - ModelState.AddModelError( - string.Empty, - "Another user modified the stock concurrently. Please refresh and try again." - ); - await LoadDropdownsAsync(ct); - return Page(); - } + var result = await transferService.TransferAsync( + SourceInventoryId, + DestinationLocationId, + Quantity, + Reason.Trim(), + ct + ); if (!result.Succeeded) { diff --git a/src/src/Samples.Web/Pages/Customer/Cart/Index.cshtml.cs b/src/src/Samples.Web/Pages/Customer/Cart/Index.cshtml.cs index 195f136f..c86d006e 100644 --- a/src/src/Samples.Web/Pages/Customer/Cart/Index.cshtml.cs +++ b/src/src/Samples.Web/Pages/Customer/Cart/Index.cshtml.cs @@ -20,7 +20,11 @@ public async Task OnGetAsync() if (string.IsNullOrEmpty(customerId)) return RedirectToPage("/Customer/Index"); - CurrentCustomer = await customerStore.GetAsync(customerId, HttpContext.RequestAborted); + var currentCustomerResult = await customerStore.GetAsync( + customerId, + HttpContext.RequestAborted + ); + CurrentCustomer = currentCustomerResult.IsSuccess ? currentCustomerResult.Value : null; CartItems = HttpContext.Session.GetCart(); return Page(); } diff --git a/src/src/Samples.Web/Pages/Customer/Catalog/Index.cshtml.cs b/src/src/Samples.Web/Pages/Customer/Catalog/Index.cshtml.cs index 205cbe24..43ecd8b3 100644 --- a/src/src/Samples.Web/Pages/Customer/Catalog/Index.cshtml.cs +++ b/src/src/Samples.Web/Pages/Customer/Catalog/Index.cshtml.cs @@ -36,7 +36,8 @@ public async Task OnGetAsync() return RedirectToPage("/Customer/Index"); var ct = HttpContext.RequestAborted; - CurrentCustomer = await customerStore.GetAsync(customerId, ct); + var currentCustomerResult = await customerStore.GetAsync(customerId, ct); + CurrentCustomer = currentCustomerResult.IsSuccess ? currentCustomerResult.Value : null; ContinuationRequest request = new() { MaxRecords = 500 }; var inventoryResult = await inventoryStore.ListAsync( diff --git a/src/src/Samples.Web/Pages/Customer/Catalog/Order.cshtml.cs b/src/src/Samples.Web/Pages/Customer/Catalog/Order.cshtml.cs index 7d103d3a..4fbbfdc2 100644 --- a/src/src/Samples.Web/Pages/Customer/Catalog/Order.cshtml.cs +++ b/src/src/Samples.Web/Pages/Customer/Catalog/Order.cshtml.cs @@ -2,7 +2,6 @@ using Microsoft.AspNetCore.Mvc.RazorPages; using Purview.EventSourcing.Samples.Domain; using Purview.EventSourcing.Samples.Services; -using Purview.EventSourcing.SqlServer.Events.Exceptions; namespace Purview.EventSourcing.Samples.Web.Pages.Customer.Catalog; @@ -34,8 +33,10 @@ public async Task OnGetAsync() return RedirectToPage("/Customer/Index"); var ct = HttpContext.RequestAborted; - CurrentCustomer = await customerStore.GetAsync(customerId, ct); - InventoryItem = await inventoryStore.GetAsync(InventoryId, ct); + var currentCustomerResult = await customerStore.GetAsync(customerId, ct); + CurrentCustomer = currentCustomerResult.IsSuccess ? currentCustomerResult.Value : null; + var inventoryItemResult = await inventoryStore.GetAsync(InventoryId, ct); + InventoryItem = inventoryItemResult.IsSuccess ? inventoryItemResult.Value : null; if (InventoryItem != null) UnitPrice = Math.Round( @@ -59,26 +60,13 @@ public async Task OnPostAsync() return Page(); } - FulfilmentResult result; - try - { - result = await fulfilmentService.PlaceOrderAsync( - customerId, - InventoryId, - Quantity, - ShippingAddress, - HttpContext.RequestAborted - ); - } - catch (ConcurrencyException) - { - ModelState.AddModelError( - string.Empty, - "Another user modified the inventory concurrently. Please try again." - ); - await ReloadAsync(customerId, HttpContext.RequestAborted); - return Page(); - } + var result = await fulfilmentService.PlaceOrderAsync( + customerId, + InventoryId, + Quantity, + ShippingAddress, + HttpContext.RequestAborted + ); if (!result.Succeeded) { @@ -94,8 +82,10 @@ public async Task OnPostAsync() async Task ReloadAsync(string customerId, CancellationToken ct) { - CurrentCustomer = await customerStore.GetAsync(customerId, ct); - InventoryItem = await inventoryStore.GetAsync(InventoryId, ct); + var currentCustomerResult = await customerStore.GetAsync(customerId, ct); + CurrentCustomer = currentCustomerResult.IsSuccess ? currentCustomerResult.Value : null; + var inventoryItemResult = await inventoryStore.GetAsync(InventoryId, ct); + InventoryItem = inventoryItemResult.IsSuccess ? inventoryItemResult.Value : null; if (InventoryItem != null) UnitPrice = Math.Round( 9.99m + (Math.Abs(InventoryItem.ProductId.GetHashCode(StringComparison.Ordinal)) % 9000 / 100m), diff --git a/src/src/Samples.Web/Pages/Customer/Orders/Details.cshtml.cs b/src/src/Samples.Web/Pages/Customer/Orders/Details.cshtml.cs index c0841745..3ed1aa09 100644 --- a/src/src/Samples.Web/Pages/Customer/Orders/Details.cshtml.cs +++ b/src/src/Samples.Web/Pages/Customer/Orders/Details.cshtml.cs @@ -17,8 +17,10 @@ public async Task OnGetAsync(string id) return RedirectToPage("/Customer/Index"); var ct = HttpContext.RequestAborted; - CurrentCustomer = await customerStore.GetAsync(customerId, ct); - Order = await orderStore.GetAsync(id, ct); + var currentCustomerResult = await customerStore.GetAsync(customerId, ct); + CurrentCustomer = currentCustomerResult.IsSuccess ? currentCustomerResult.Value : null; + var orderResult = await orderStore.GetAsync(id, ct); + Order = orderResult.IsSuccess ? orderResult.Value : null; return Order == null || Order.CustomerId != customerId ? NotFound() : Page(); } @@ -35,7 +37,8 @@ decimal unitPrice if (string.IsNullOrEmpty(customerId)) return RedirectToPage("/Customer/Index"); - var order = await orderStore.GetAsync(id, HttpContext.RequestAborted); + var orderResult = await orderStore.GetAsync(id, HttpContext.RequestAborted); + var order = orderResult.IsSuccess ? orderResult.Value : null; if (order == null || order.CustomerId != customerId) return NotFound(); if (order.Status != OrderStatusCode.Draft) @@ -48,7 +51,7 @@ decimal unitPrice async () => { order.AddLineItem(productId.Trim(), productName.Trim(), quantity, unitPrice); - await orderStore.SaveAsync(order, HttpContext.RequestAborted); + return await orderStore.SaveAsync(order, HttpContext.RequestAborted); }, "Line item added.", RedirectToPage(new { id }) @@ -61,7 +64,8 @@ public async Task OnPostRemoveLineItemAsync(string id, string pro if (string.IsNullOrEmpty(customerId)) return RedirectToPage("/Customer/Index"); - var order = await orderStore.GetAsync(id, HttpContext.RequestAborted); + var orderResult = await orderStore.GetAsync(id, HttpContext.RequestAborted); + var order = orderResult.IsSuccess ? orderResult.Value : null; if (order == null || order.CustomerId != customerId) return NotFound(); if (order.Status != OrderStatus.Draft) @@ -74,7 +78,7 @@ public async Task OnPostRemoveLineItemAsync(string id, string pro async () => { order.RemoveLineItem(productId); - await orderStore.SaveAsync(order, HttpContext.RequestAborted); + return await orderStore.SaveAsync(order, HttpContext.RequestAborted); }, "Line item removed.", RedirectToPage(new { id }) @@ -87,7 +91,8 @@ public async Task OnPostSetShippingAddressAsync(string id, string if (string.IsNullOrEmpty(customerId)) return RedirectToPage("/Customer/Index"); - var order = await orderStore.GetAsync(id, HttpContext.RequestAborted); + var orderResult = await orderStore.GetAsync(id, HttpContext.RequestAborted); + var order = orderResult.IsSuccess ? orderResult.Value : null; if (order == null || order.CustomerId != customerId) return NotFound(); if (order.Status != OrderStatus.Draft) @@ -100,7 +105,7 @@ public async Task OnPostSetShippingAddressAsync(string id, string async () => { order.SetShippingAddress(address); - await orderStore.SaveAsync(order, HttpContext.RequestAborted); + return await orderStore.SaveAsync(order, HttpContext.RequestAborted); }, "Shipping address updated.", RedirectToPage(new { id }) @@ -113,7 +118,8 @@ public async Task OnPostUpdateNotesAsync(string id, string? notes if (string.IsNullOrEmpty(customerId)) return RedirectToPage("/Customer/Index"); - var order = await orderStore.GetAsync(id, HttpContext.RequestAborted); + var orderResult = await orderStore.GetAsync(id, HttpContext.RequestAborted); + var order = orderResult.IsSuccess ? orderResult.Value : null; if (order == null || order.CustomerId != customerId) return NotFound(); if (order.Status != OrderStatus.Draft) @@ -126,7 +132,7 @@ public async Task OnPostUpdateNotesAsync(string id, string? notes async () => { order.UpdateNotes(string.IsNullOrWhiteSpace(notes) ? null : notes.Trim()); - await orderStore.SaveAsync(order, HttpContext.RequestAborted); + return await orderStore.SaveAsync(order, HttpContext.RequestAborted); }, "Notes updated.", RedirectToPage(new { id }) @@ -139,7 +145,8 @@ public async Task OnPostCancelAsync(string id) if (string.IsNullOrEmpty(customerId)) return RedirectToPage("/Customer/Index"); - var order = await orderStore.GetAsync(id, HttpContext.RequestAborted); + var orderResult = await orderStore.GetAsync(id, HttpContext.RequestAborted); + var order = orderResult.IsSuccess ? orderResult.Value : null; if (order == null || order.CustomerId != customerId) return NotFound(); if (order.Status != OrderStatus.Draft) @@ -152,7 +159,7 @@ public async Task OnPostCancelAsync(string id) async () => { order.CancelOrder(); - await orderStore.SaveAsync(order, HttpContext.RequestAborted); + return await orderStore.SaveAsync(order, HttpContext.RequestAborted); }, "Order cancelled.", RedirectToPage(new { id }) diff --git a/src/src/Samples.Web/Pages/Customer/Orders/Index.cshtml.cs b/src/src/Samples.Web/Pages/Customer/Orders/Index.cshtml.cs index f7f393e5..f1dc3288 100644 --- a/src/src/Samples.Web/Pages/Customer/Orders/Index.cshtml.cs +++ b/src/src/Samples.Web/Pages/Customer/Orders/Index.cshtml.cs @@ -36,7 +36,8 @@ public async Task OnGetAsync() PageSize = DefaultPageSize; var ct = HttpContext.RequestAborted; - CurrentCustomer = await customerStore.GetAsync(customerId, ct); + var currentCustomerResult = await customerStore.GetAsync(customerId, ct); + CurrentCustomer = currentCustomerResult.IsSuccess ? currentCustomerResult.Value : null; var skipCount = (Page - 1) * PageSize; ContinuationRequest request = new() diff --git a/src/src/Samples.Web/Pages/Customer/Profile/Index.cshtml.cs b/src/src/Samples.Web/Pages/Customer/Profile/Index.cshtml.cs index 0b650b25..c5ebe762 100644 --- a/src/src/Samples.Web/Pages/Customer/Profile/Index.cshtml.cs +++ b/src/src/Samples.Web/Pages/Customer/Profile/Index.cshtml.cs @@ -14,7 +14,8 @@ public async Task OnGetAsync() if (string.IsNullOrEmpty(customerId)) return RedirectToPage("/Customer/Index"); - CurrentCustomer = await store.GetAsync(customerId, HttpContext.RequestAborted); + var currentCustomerResult = await store.GetAsync(customerId, HttpContext.RequestAborted); + CurrentCustomer = currentCustomerResult.IsSuccess ? currentCustomerResult.Value : null; return Page(); } @@ -30,14 +31,15 @@ public async Task OnPostChangeNameAsync(string newName) return RedirectToPage(); } - var customer = await store.GetAsync(customerId, HttpContext.RequestAborted); + var customerResult = await store.GetAsync(customerId, HttpContext.RequestAborted); + var customer = customerResult.IsSuccess ? customerResult.Value : null; return customer == null ? NotFound() : await TrySaveAsync( async () => { customer.ChangeName(newName.Trim()); - await store.SaveAsync(customer, HttpContext.RequestAborted); + return await store.SaveAsync(customer, HttpContext.RequestAborted); }, "Name updated.", RedirectToPage() @@ -50,14 +52,15 @@ public async Task OnPostChangeEmailAsync(string newEmail) if (string.IsNullOrEmpty(customerId)) return RedirectToPage("/Customer/Index"); - var customer = await store.GetAsync(customerId, HttpContext.RequestAborted); + var customerResult = await store.GetAsync(customerId, HttpContext.RequestAborted); + var customer = customerResult.IsSuccess ? customerResult.Value : null; return customer == null ? NotFound() : await TrySaveAsync( async () => { customer.ChangeEmail(newEmail); - await store.SaveAsync(customer, HttpContext.RequestAborted); + return await store.SaveAsync(customer, HttpContext.RequestAborted); }, "Email updated.", RedirectToPage() @@ -70,14 +73,15 @@ public async Task OnPostChangePhoneAsync(string? phoneNumber) if (string.IsNullOrEmpty(customerId)) return RedirectToPage("/Customer/Index"); - var customer = await store.GetAsync(customerId, HttpContext.RequestAborted); + var customerResult = await store.GetAsync(customerId, HttpContext.RequestAborted); + var customer = customerResult.IsSuccess ? customerResult.Value : null; return customer == null ? NotFound() : await TrySaveAsync( async () => { customer.ChangePhoneNumber(string.IsNullOrWhiteSpace(phoneNumber) ? null : phoneNumber.Trim()); - await store.SaveAsync(customer, HttpContext.RequestAborted); + return await store.SaveAsync(customer, HttpContext.RequestAborted); }, "Phone number updated.", RedirectToPage() @@ -102,14 +106,15 @@ public async Task OnPostUpdateAllAsync(string newName, string new return RedirectToPage(); } - var customer = await store.GetAsync(customerId, HttpContext.RequestAborted); + var customerResult = await store.GetAsync(customerId, HttpContext.RequestAborted); + var customer = customerResult.IsSuccess ? customerResult.Value : null; return customer == null ? NotFound() : await TrySaveAsync( async () => { customer.UpdateDetails(name: newName, email: newEmail, phoneNumber: phoneNumber); - await store.SaveAsync(customer, HttpContext.RequestAborted); + return await store.SaveAsync(customer, HttpContext.RequestAborted); }, "Profile updated.", RedirectToPage() diff --git a/src/src/Samples.Web/Services/ISampleSeedServiceTelemetry.cs b/src/src/Samples.Web/Services/ISampleSeedServiceTelemetry.cs index 52aa56b9..ac48e9fb 100644 --- a/src/src/Samples.Web/Services/ISampleSeedServiceTelemetry.cs +++ b/src/src/Samples.Web/Services/ISampleSeedServiceTelemetry.cs @@ -1,7 +1,7 @@ using Azure; using MongoDB.Driver; using Npgsql; -using Purview.EventSourcing.AzureStorage.Exceptions; +using Purview.EventSourcing.Exceptions; using Purview.Telemetry; namespace Purview.EventSourcing.Samples.Web.Services; @@ -19,7 +19,7 @@ interface ISampleSeedServiceTelemetry void ArgumentFailed(string currentKey, ArgumentException ex); [Error] - void AzureCommitFailed(string currentKey, CommitException ex); + void CommitFailed(string currentKey, CommitException ex); [Error] void FormatFailed(string currentKey, FormatException ex); @@ -35,7 +35,4 @@ interface ISampleSeedServiceTelemetry [Error] void RequestFailed(string currentKey, RequestFailedException ex); - - [Error] - void SqlServerCommitFailed(string currentKey, SqlServer.Events.Exceptions.CommitException ex); } diff --git a/src/src/Samples.Web/Services/SampleSeedService.cs b/src/src/Samples.Web/Services/SampleSeedService.cs index 749002f3..12b4701a 100644 --- a/src/src/Samples.Web/Services/SampleSeedService.cs +++ b/src/src/Samples.Web/Services/SampleSeedService.cs @@ -3,12 +3,11 @@ using Microsoft.Extensions.Options; using MongoDB.Driver; using Npgsql; +// Commit and concurrency failures are one type across every provider now, so the sample catches each +// once rather than once per store. +using Purview.EventSourcing.Exceptions; using Purview.EventSourcing.Samples.Options; using Purview.EventSourcing.Samples.Services; -using AzureCommitException = Purview.EventSourcing.AzureStorage.Exceptions.CommitException; -using AzureConcurrencyException = Purview.EventSourcing.AzureStorage.Exceptions.ConcurrencyException; -using SqlServerCommitException = Purview.EventSourcing.SqlServer.Events.Exceptions.CommitException; -using SqlServerConcurrencyException = Purview.EventSourcing.SqlServer.Events.Exceptions.ConcurrencyException; namespace Purview.EventSourcing.Samples.Web.Services; @@ -27,24 +26,21 @@ public async Task SeedAsync(CancellationToken cancellationToken = default) try { var sw = Stopwatch.StartNew(); - await seedDataService.SeedAsync(cancellationToken); + var seeded = await seedDataService.SeedAsync(cancellationToken); sw.Stop(); + if (!seeded && attempt < 2) + { + // Another app instance may be seeding the demo store at the same time. + await Task.Delay(TimeSpan.FromMilliseconds(100 * (attempt + 1)), cancellationToken); + continue; + } + telemetry.Complete(sampleStoreOptions.Value.CurrentKey, attempt + 1, sw.Elapsed); return; } - catch (SqlServerConcurrencyException) when (attempt < 2) - { - // Another app instance may be seeding the demo store at the same time. - await Task.Delay(TimeSpan.FromMilliseconds(100 * (attempt + 1)), cancellationToken); - } - catch (AzureConcurrencyException) when (attempt < 2) - { - // Another app instance may be seeding the demo store at the same time. - await Task.Delay(TimeSpan.FromMilliseconds(100 * (attempt + 1)), cancellationToken); - } catch (RequestFailedException ex) { telemetry.RequestFailed(sampleStoreOptions.Value.CurrentKey, ex); @@ -60,14 +56,9 @@ public async Task SeedAsync(CancellationToken cancellationToken = default) telemetry.NpgsqlFailed(sampleStoreOptions.Value.CurrentKey, ex); break; } - catch (SqlServerCommitException ex) - { - telemetry.SqlServerCommitFailed(sampleStoreOptions.Value.CurrentKey, ex); - break; - } - catch (AzureCommitException ex) + catch (CommitException ex) { - telemetry.AzureCommitFailed(sampleStoreOptions.Value.CurrentKey, ex); + telemetry.CommitFailed(sampleStoreOptions.Value.CurrentKey, ex); break; } catch (FormatException ex) diff --git a/src/src/Samples/Domain/OrderAggregate.cs b/src/src/Samples/Domain/OrderAggregate.cs index 97f915db..f12bca76 100644 --- a/src/src/Samples/Domain/OrderAggregate.cs +++ b/src/src/Samples/Domain/OrderAggregate.cs @@ -34,12 +34,15 @@ public sealed partial class OrderAggregate : AggregateBase /// /// Updates one or more order details in a single operation, raising a granular event - /// for each field that has actually changed. Pass for any field - /// that should remain unchanged. To clear notes, use directly. + /// for each field that has actually changed. Pass - or, for the shipping + /// address, any whitespace - for a field that should remain unchanged. To clear a field, use + /// or directly. /// public OrderAggregate UpdateDetails(string? shippingAddress = null, string? notes = null) { - if (shippingAddress is not null) + // A blank address is normalized to an empty string, so accepting one here would raise an event + // for what the caller asked to leave alone. + if (!string.IsNullOrWhiteSpace(shippingAddress)) SetShippingAddress(shippingAddress); if (notes is not null) diff --git a/src/src/Samples/Services/CartCheckoutService.cs b/src/src/Samples/Services/CartCheckoutService.cs index c1967381..77305ca8 100644 --- a/src/src/Samples/Services/CartCheckoutService.cs +++ b/src/src/Samples/Services/CartCheckoutService.cs @@ -18,9 +18,11 @@ public async Task CheckoutAsync( if (items == null || items.Count == 0) return CartCheckoutResult.Fail("Cart is empty."); - var customer = await store.GetAsync(customerId, cancellationToken); - if (customer is null || customer.Details.IsDeleted) + var customerResult = await store.GetAsync(customerId, cancellationToken); + if (customerResult.IsFailure) return CartCheckoutResult.Fail("Customer not found."); + + var customer = customerResult.Value; if (!customer.IsActive) return CartCheckoutResult.Fail($"Customer '{customer.Name}' is not active."); @@ -29,11 +31,11 @@ public async Task CheckoutAsync( { if (!inventoryReservations.TryGetValue(item.InventoryId, out var reservation)) { - var inventory = await store.GetAsync(item.InventoryId, cancellationToken); - if (inventory is null || inventory.Details.IsDeleted) + var inventoryResult = await store.GetAsync(item.InventoryId, cancellationToken); + if (inventoryResult.IsFailure) return CartCheckoutResult.Fail($"Product '{item.ProductName}' is no longer available."); - reservation = new InventoryReservation(inventory); + reservation = new InventoryReservation(inventoryResult.Value); inventoryReservations.Add(item.InventoryId, reservation); } diff --git a/src/src/Samples/Services/ISeedDataService.cs b/src/src/Samples/Services/ISeedDataService.cs index bfea405b..50fb1cb4 100644 --- a/src/src/Samples/Services/ISeedDataService.cs +++ b/src/src/Samples/Services/ISeedDataService.cs @@ -2,5 +2,9 @@ namespace Purview.EventSourcing.Samples.Services; public interface ISeedDataService { - Task SeedAsync(CancellationToken cancellationToken = default); + /// + /// Seeds the demo store, returning when a save lost a concurrency check - + /// typically another instance seeding the same store - so the caller can retry. + /// + Task SeedAsync(CancellationToken cancellationToken = default); } diff --git a/src/src/Samples/Services/OrderFulfilmentService.cs b/src/src/Samples/Services/OrderFulfilmentService.cs index 83993cef..60757d4b 100644 --- a/src/src/Samples/Services/OrderFulfilmentService.cs +++ b/src/src/Samples/Services/OrderFulfilmentService.cs @@ -1,6 +1,7 @@ using System.Collections.Concurrent; using System.Security.Cryptography; using System.Text; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.Samples.Domain; namespace Purview.EventSourcing.Samples.Services; @@ -19,15 +20,19 @@ public async Task PlaceOrderAsync( CancellationToken cancellationToken = default ) { - var customer = await store.GetAsync(customerId, cancellationToken); - if (customer is null || customer.Details.IsDeleted) + var customerResult = await store.GetAsync(customerId, cancellationToken); + if (customerResult.IsFailure) return FulfilmentResult.Fail("Customer not found."); + + var customer = customerResult.Value; if (!customer.IsActive) return FulfilmentResult.Fail($"Customer '{customer.Name}' is not active."); - var inventory = await store.GetAsync(inventoryId, cancellationToken); - if (inventory is null || inventory.Details.IsDeleted) + var inventoryResult = await store.GetAsync(inventoryId, cancellationToken); + if (inventoryResult.IsFailure) return FulfilmentResult.Fail("Inventory item not found."); + + var inventory = inventoryResult.Value; if (inventory.AvailableQuantity < quantity) return FulfilmentResult.Fail( $"Insufficient stock for '{inventory.ProductName}'. Available: {inventory.AvailableQuantity}, requested: {quantity}." @@ -50,9 +55,18 @@ public async Task PlaceOrderAsync( transaction.Enlist(inventory, store); var transactionResult = await transaction.CommitAsync(cancellationToken); - return transactionResult.Success - ? FulfilmentResult.Success(order, inventory) - : FulfilmentResult.Fail("Failed to place order. Nothing was saved."); + if (transactionResult.Success) + return FulfilmentResult.Success(order, inventory); + + // A lost concurrency check is reported, not thrown, so the caller can tell a retryable race + // apart from a genuine failure. + var conflicted = transactionResult.Results.Any(result => result.Failure is ConcurrencyConflict); + + return FulfilmentResult.Fail( + conflicted + ? "Another user modified the inventory concurrently. Nothing was saved - please try again." + : "Failed to place order. Nothing was saved." + ); } static decimal GetUnitPrice(string productId) diff --git a/src/src/Samples/Services/SeedDataService.cs b/src/src/Samples/Services/SeedDataService.cs index c28b06a2..05e29521 100644 --- a/src/src/Samples/Services/SeedDataService.cs +++ b/src/src/Samples/Services/SeedDataService.cs @@ -123,20 +123,24 @@ static readonly (string LocationId, string LocationName)[] Locations = "77 Church Lane, Liverpool, L1 1AA", ]; - public async Task SeedAsync(CancellationToken cancellationToken = default) + public async Task SeedAsync(CancellationToken cancellationToken = default) { - await EnsureLocationsAsync(cancellationToken); + if (!await EnsureLocationsAsync(cancellationToken)) + return false; var customerCount = await store.CountAsync(null, cancellationToken); if (customerCount > 0) - return; + return true; var customerIds = await SeedCustomersAsync(cancellationToken); + if (customerIds is null) + return false; + var inventoryIds = await SeedInventoryAsync(cancellationToken); - await SeedOrdersAsync(customerIds, inventoryIds, cancellationToken); + return inventoryIds is not null && await SeedOrdersAsync(customerIds, inventoryIds, cancellationToken); } - async Task EnsureLocationsAsync(CancellationToken cancellationToken) + async Task EnsureLocationsAsync(CancellationToken cancellationToken) { HashSet existingLocationIds = new(StringComparer.OrdinalIgnoreCase); await foreach ( @@ -165,11 +169,16 @@ var inventory in store.GetListEnumerableAsync(cancellationTo var location = await store.CreateAsync(locationId, cancellationToken); location.Create(locationId, locationName); - await store.SaveAsync(location, cancellationToken); + + // Another instance seeding the same demo store wins the race; the caller retries. + if ((await store.SaveAsync(location, cancellationToken)).IsFailure) + return false; } + + return true; } - async Task SeedCustomersAsync(CancellationToken cancellationToken) + async Task SeedCustomersAsync(CancellationToken cancellationToken) { List ids = []; var phones = new[] { "+44 7700 900000", "+44 7700 900001", null, "+44 7700 900002", null }; @@ -191,13 +200,16 @@ async Task SeedCustomersAsync(CancellationToken cancellationToken) customer.Deactivate(); var result = await store.SaveAsync(customer, cancellationToken); - ids.Add(result.Aggregate.Id()); + if (result.IsFailure) + return null; + + ids.Add(result.Value.Aggregate.Id()); } return [.. ids]; } - async Task<(string AggregateId, int Index)[]> SeedInventoryAsync(CancellationToken cancellationToken) + async Task<(string AggregateId, int Index)[]?> SeedInventoryAsync(CancellationToken cancellationToken) { List<(string, int)> ids = []; @@ -210,13 +222,16 @@ async Task SeedCustomersAsync(CancellationToken cancellationToken) item.Create(productId, productName, locationId, locationName, initialQty); var result = await store.SaveAsync(item, cancellationToken); - ids.Add((result.Aggregate.Id(), i)); + if (result.IsFailure) + return null; + + ids.Add((result.Value.Aggregate.Id(), i)); } return [.. ids]; } - async Task SeedOrdersAsync( + async Task SeedOrdersAsync( string[] customerIds, (string AggregateId, int Index)[] inventoryItems, CancellationToken cancellationToken @@ -260,7 +275,10 @@ CancellationToken cancellationToken await store.SaveAsync(cancelled, cancellationToken); } - await store.SaveAsync(order, cancellationToken); + if ((await store.SaveAsync(order, cancellationToken)).IsFailure) + return false; } + + return true; } } diff --git a/src/src/Samples/Services/StockTransferService.cs b/src/src/Samples/Services/StockTransferService.cs index fb43d7c8..4c2eb059 100644 --- a/src/src/Samples/Services/StockTransferService.cs +++ b/src/src/Samples/Services/StockTransferService.cs @@ -1,3 +1,4 @@ +using Purview.EventSourcing.Failures; using Purview.EventSourcing.Samples.Domain; namespace Purview.EventSourcing.Samples.Services; @@ -24,21 +25,28 @@ public async Task TransferAsync( ArgumentOutOfRangeException.ThrowIfNegativeOrZero(quantity); ArgumentException.ThrowIfNullOrWhiteSpace(reason); - var source = await store.GetAsync(sourceInventoryId, cancellationToken); - if (source is null || source.Details.IsDeleted) + var sourceResult = await store.GetAsync(sourceInventoryId, cancellationToken); + if (sourceResult.IsFailure) return StockTransferResult.Fail("Source stock item not found."); + var source = sourceResult.Value; if (string.Equals(source.LocationId, destinationLocationId, StringComparison.OrdinalIgnoreCase)) return StockTransferResult.Fail("Source and destination locations must be different."); - var sourceLocation = await store.GetAsync(source.LocationId, cancellationToken); - if (sourceLocation is null || sourceLocation.Details.IsDeleted) + var sourceLocationResult = await store.GetAsync(source.LocationId, cancellationToken); + if (sourceLocationResult.IsFailure) return StockTransferResult.Fail($"Source location '{source.LocationId}' not found."); - var destinationLocation = await store.GetAsync(destinationLocationId, cancellationToken); - if (destinationLocation is null || destinationLocation.Details.IsDeleted) + var destinationLocationResult = await store.GetAsync( + destinationLocationId, + cancellationToken + ); + if (destinationLocationResult.IsFailure) return StockTransferResult.Fail("Destination location not found."); + var sourceLocation = sourceLocationResult.Value; + var destinationLocation = destinationLocationResult.Value; + if (source.AvailableQuantity < quantity) return StockTransferResult.Fail( $"Insufficient available stock at '{sourceLocation.LocationName}'. " @@ -81,8 +89,17 @@ public async Task TransferAsync( var transactionResult = await transaction.CommitAsync(cancellationToken); - return transactionResult.Success - ? StockTransferResult.Success(source, destination, quantity) - : StockTransferResult.Fail("Failed to transfer stock. Nothing was saved."); + if (transactionResult.Success) + return StockTransferResult.Success(source, destination, quantity); + + // A lost concurrency check is reported, not thrown, so the caller can tell a retryable race + // apart from a genuine failure. + var conflicted = transactionResult.Results.Any(result => result.Failure is ConcurrencyConflict); + + return StockTransferResult.Fail( + conflicted + ? "Another user modified the stock concurrently. Nothing was saved - please refresh and try again." + : "Failed to transfer stock. Nothing was saved." + ); } } diff --git a/src/src/Samples/ValueObjects/EmailAddress.cs b/src/src/Samples/ValueObjects/EmailAddress.cs index ffc5134a..1c3a12a4 100644 --- a/src/src/Samples/ValueObjects/EmailAddress.cs +++ b/src/src/Samples/ValueObjects/EmailAddress.cs @@ -8,7 +8,22 @@ public readonly partial record struct EmailAddress { public string Value { get; } - public string Domain => Value.Split('@')[1]; + /// + /// The part after the '@', or an empty string when there is no value to read. + /// + /// + /// A record struct is always constructible as default, and validators read computed members + /// before a value is assigned, so this cannot assume is a well-formed address. + /// + public string Domain + { + get + { + var separator = Value?.IndexOf('@', StringComparison.Ordinal) ?? -1; + + return separator < 0 ? string.Empty : Value![(separator + 1)..]; + } + } [System.Diagnostics.CodeAnalysis.SuppressMessage("Globalization", "CA1308:Normalize strings to uppercase")] static partial void OnNormalize(ref string value) => value = value?.Trim().ToLowerInvariant()!; diff --git a/src/src/SqlServer/Client/JsonValueObjectCollectionConverter.cs b/src/src/SqlServer/Client/JsonValueObjectCollectionConverter.cs deleted file mode 100644 index 0c7539a6..00000000 --- a/src/src/SqlServer/Client/JsonValueObjectCollectionConverter.cs +++ /dev/null @@ -1,16 +0,0 @@ -using Microsoft.EntityFrameworkCore.Storage.ValueConversion; -using Purview.EventSourcing.Serialization; - -namespace Purview.EventSourcing.SqlServer.Client; - -sealed class JsonValueObjectCollectionConverter : ValueConverter -{ - public JsonValueObjectCollectionConverter() - : base( - value => EventStoreSerializationHelpers.Serialize(value), - value => EventStoreSerializationHelpers.Deserialize(value)! - ) - { - // - } -} diff --git a/src/src/SqlServer/Client/Models.cs b/src/src/SqlServer/Client/Models.cs index edf8f9e0..0c7bd250 100644 --- a/src/src/SqlServer/Client/Models.cs +++ b/src/src/SqlServer/Client/Models.cs @@ -1,6 +1,6 @@ namespace Purview.EventSourcing.SqlServer.Client; -sealed record SnapshotStorageRow(string Id, string AggregateType, string Payload); +sealed record SnapshotStorageRow(string Id, string AggregateType, string Payload, string? TenantId = null); sealed class SnapshotQueryRow where TAggregate : class @@ -10,6 +10,11 @@ sealed class SnapshotQueryRow public required string AggregateType { get; set; } public required TAggregate Payload { get; set; } + + /// + /// The tenant that owns the snapshot; null in a single-tenant deployment. + /// + public string? TenantId { get; set; } } sealed record SqlServerClientOptions(string ConnectionString, bool UseDataCompression) diff --git a/src/src/SqlServer/Client/OpaqueJsonValueConverter.cs b/src/src/SqlServer/Client/OpaqueJsonValueConverter.cs deleted file mode 100644 index b7a14516..00000000 --- a/src/src/SqlServer/Client/OpaqueJsonValueConverter.cs +++ /dev/null @@ -1,17 +0,0 @@ -using System.Linq.Expressions; -using Microsoft.EntityFrameworkCore.Storage.ValueConversion; -using Purview.EventSourcing.Serialization; - -namespace Purview.EventSourcing.SqlServer.Client; - -sealed class OpaqueJsonValueConverter : ValueConverter -{ - public OpaqueJsonValueConverter() - : base(ToJsonExpression(), FromJsonExpression()) { } - - static Expression> ToJsonExpression() => - value => EventStoreSerializationHelpers.Serialize(value); - - static Expression> FromJsonExpression() => - value => EventStoreSerializationHelpers.Deserialize(value)!; -} diff --git a/src/src/SqlServer/Client/ScalarValueConverter.cs b/src/src/SqlServer/Client/ScalarValueConverter.cs deleted file mode 100644 index 51fffc45..00000000 --- a/src/src/SqlServer/Client/ScalarValueConverter.cs +++ /dev/null @@ -1,74 +0,0 @@ -using System.Linq.Expressions; -using System.Reflection; -using Microsoft.EntityFrameworkCore.Storage.ValueConversion; -using Purview.ValueObjects.Serialization; - -namespace Purview.EventSourcing.SqlServer.Client; - -sealed class ScalarValueConverter : ValueConverter -{ - public ScalarValueConverter() - : base(BuildToProviderExpression(), BuildFromProviderExpression()) { } - - static Expression> BuildToProviderExpression() - { - var scalarProperty = GetScalarProperty(); - var source = Expression.Parameter(typeof(TScalarObject), "value"); - var body = Expression.Property(source, scalarProperty); - return Expression.Lambda>(body, source); - } - - static Expression> BuildFromProviderExpression() - { - var source = Expression.Parameter(typeof(TScalar), "value"); - var body = BuildCreatorExpression(source); - return Expression.Lambda>(body, source); - } - - static PropertyInfo GetScalarProperty() - { - var scalarType = typeof(TScalarObject); - var scalarAttribute = - scalarType.GetCustomAttribute() - ?? throw new InvalidOperationException($"{scalarType.Name} must be annotated with [Scalar]."); - - return scalarType.GetProperty(scalarAttribute.PropertyName, BindingFlags.Instance | BindingFlags.Public) - ?? throw new InvalidOperationException( - $"'{scalarType.Name}' missing scalar property '{scalarAttribute.PropertyName}'." - ); - } - - static Expression BuildCreatorExpression(ParameterExpression source) - { - var scalarType = typeof(TScalarObject); - var scalarPropertyType = typeof(TScalar); - var scalarAttribute = - scalarType.GetCustomAttribute() - ?? throw new InvalidOperationException($"{scalarType.Name} must be annotated with [Scalar]."); - - var preferredFactoryName = - scalarAttribute.DeserializationMode == ValueObjectDeserializationMode.Strict ? "Create" : "Hydrate"; - var secondaryFactoryName = preferredFactoryName == "Hydrate" ? "Create" : "Hydrate"; - - var create = - scalarType.GetMethod(preferredFactoryName, BindingFlags.Public | BindingFlags.Static, [scalarPropertyType]) - ?? scalarType.GetMethod( - secondaryFactoryName, - BindingFlags.Public | BindingFlags.Static, - [scalarPropertyType] - ); - if (create is not null) - return Expression.Call(create, source); - - var ctor = scalarType.GetConstructor( - BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic, - [scalarPropertyType] - ); - - return ctor is null - ? throw new InvalidOperationException( - $"{scalarType.Name} must expose static {preferredFactoryName}({scalarPropertyType.Name}), static {secondaryFactoryName}({scalarPropertyType.Name}), or ctor({scalarPropertyType.Name})." - ) - : (Expression)Expression.New(ctor, source); - } -} diff --git a/src/src/SqlServer/Client/SqlServerClient.cs b/src/src/SqlServer/Client/SqlServerClient.cs index 71c22941..32e0abca 100644 --- a/src/src/SqlServer/Client/SqlServerClient.cs +++ b/src/src/SqlServer/Client/SqlServerClient.cs @@ -1,14 +1,13 @@ using System.Collections.Concurrent; using System.Linq.Expressions; -using System.Reflection; using System.Text.RegularExpressions; using Microsoft.Data.SqlClient; using Microsoft.EntityFrameworkCore; using Microsoft.EntityFrameworkCore.Infrastructure; -using Microsoft.EntityFrameworkCore.Metadata.Builders; using Microsoft.EntityFrameworkCore.Storage; -using Purview.EventSourcing.Aggregates; -using Purview.ValueObjects.Serialization; +using Purview.EventSourcing.EntityFrameworkCore.Mapping; +using Purview.EventSourcing.EntityFrameworkCore.Query; +using Purview.EventSourcing.Tenancy; namespace Purview.EventSourcing.SqlServer.Client; @@ -18,16 +17,14 @@ sealed partial class SqlServerClient static readonly ConcurrentDictionary EnsuredTables = new(StringComparer.Ordinal); static readonly HashSet SupportedSnapshotIncludeColumns = ["Id", "AggregateType", "Payload"]; - // Must match the attribute emitted by Purview.EventSourcing.EntityFrameworkCore.SourceGenerator - // (TypeLibrary.EFOpaqueAttribute) and applied by consumers as [EFOpaque]. - const string EFOpaqueAttributeFullName = "Purview.EventSourcing.EntityFrameworkCore.EFOpaqueAttribute"; - readonly SqlServerClientOptions _options; + readonly ICurrentTenant _currentTenant; readonly string _tableEnsureKey; - public SqlServerClient(SqlServerClientOptions options) + public SqlServerClient(SqlServerClientOptions options, ICurrentTenant? currentTenant = null) { _options = options ?? throw new ArgumentNullException(nameof(options)); + _currentTenant = currentTenant ?? new SystemCurrentTenant(); _tableEnsureKey = $"{_options.ConnectionString}|{_options.SchemaName}|{_options.TableName}"; ValidateIdentifier(_options.SchemaName); @@ -144,7 +141,7 @@ public async Task> QueryByAggregateTypeAsync( await EnsureTableIfEnabledAsync(cancellationToken); var normalizedWhereClause = whereClause is null ? null - : RewriteAggregateTypePredicate(whereClause, aggregateType); + : SnapshotPredicateRewriter.Rewrite(whereClause, aggregateType); var rowQuery = context.Snapshots.AsNoTracking().AsSplitQuery().Where(s => s.AggregateType == aggregateType); @@ -155,7 +152,7 @@ public async Task> QueryByAggregateTypeAsync( if (orderByClause != null) { aggregateQuery = orderByClause(aggregateQuery); - EnsureSupportedOrderByExpression(aggregateQuery.Expression); + SnapshotPredicateRewriter.EnsureSupportedOrderByExpression(aggregateQuery.Expression); } var page = aggregateQuery.Skip(Math.Max(0, skipCount)).Take(Math.Max(0, takeCount)); @@ -183,7 +180,7 @@ static IQueryable BuildAggregateQuery( .Where(s => s.AggregateType == aggregateType) .Select(s => s.Payload); - return whereClause is null ? query : query.Where(RewriteAggregateTypePredicate(whereClause, aggregateType)); + return whereClause is null ? query : query.Where(SnapshotPredicateRewriter.Rewrite(whereClause, aggregateType)); } static async Task UpsertAsync( @@ -202,6 +199,9 @@ CancellationToken cancellationToken Id = id, AggregateType = aggregateType, Payload = aggregate, + // Stamped from the context that will write it, so a snapshot cannot be saved without an + // owner and then be hidden from its own tenant by the query filter. + TenantId = context.TenantId, }; if (exists) @@ -212,9 +212,10 @@ CancellationToken cancellationToken return await context.SaveChangesAsync(cancellationToken) > 0; } - SnapshotStorageDbContext CreateStorageContext() => new(_options); + SnapshotStorageDbContext CreateStorageContext() => new(_options, _currentTenant); - SnapshotStorageDbContext CreateStorageContext(SqlConnection connection) => new(_options, connection); + SnapshotStorageDbContext CreateStorageContext(SqlConnection connection) => + new(_options, connection, _currentTenant); SnapshotQueryDbContext CreateQueryContext() where T : class => new(_options); @@ -234,24 +235,48 @@ static void ValidateIdentifier(string identifier) [GeneratedRegex(@"^[\w\-\.]+$")] private static partial Regex IdentifierRegex(); - sealed class SnapshotStorageDbContext : DbContext + sealed class SnapshotStorageDbContext : DbContext, ISnapshotModelCacheKeySource { readonly SqlServerClientOptions _options; readonly SqlConnection? _connection; - public SnapshotStorageDbContext(SqlServerClientOptions options) + // Captured once per context: a context is scoped to one operation, and EF only re-evaluates + // plain context fields when it reuses the cached model. + bool _crossesTenants = true; + string? _tenantId; + + /// The tenant owning rows written through this context. + public string? TenantId => _tenantId; + + void SetTenant(ICurrentTenant? currentTenant) + { + var scope = (currentTenant ?? new SystemCurrentTenant()).Current; + _crossesTenants = scope.IsSystem; + _tenantId = scope.TenantId; + } + + public SnapshotStorageDbContext(SqlServerClientOptions options, ICurrentTenant? currentTenant = null) { _options = options; + SetTenant(currentTenant); } - public SnapshotStorageDbContext(SqlServerClientOptions options, SqlConnection connection) + public SnapshotStorageDbContext( + SqlServerClientOptions options, + SqlConnection connection, + ICurrentTenant? currentTenant = null + ) { _options = options; _connection = connection; + SetTenant(currentTenant); } public DbSet Snapshots => Set(); + public object CreateModelCacheKey(bool designTime) => + (typeof(SnapshotStorageDbContext), _options.SchemaName, _options.TableName, designTime); + protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) { if (_connection is null) @@ -270,32 +295,63 @@ protected override void OnModelCreating(ModelBuilder modelBuilder) entity.Property(x => x.Id).HasMaxLength(450); entity.Property(x => x.AggregateType).HasMaxLength(450); entity.Property(x => x.Payload).HasColumnType("json"); + entity.Property(x => x.TenantId).HasMaxLength(450); + + // A global filter rather than a per-query predicate: the snapshot store is the queryable + // read model, so a query that forgets the tenant returns another tenant's aggregates. + // An unowned row is visible only to the system scope: treating it as visible to everyone + // would turn a missed stamp on any write path into silent cross-tenant exposure. + entity.HasQueryFilter(x => _crossesTenants || x.TenantId == _tenantId); entity.HasIndex(x => x.AggregateType); } } - sealed class SnapshotQueryDbContext : DbContext + sealed class SnapshotQueryDbContext : DbContext, ISnapshotModelCacheKeySource where TAggregate : class { readonly SqlServerClientOptions _options; readonly SqlConnection? _connection; - public SnapshotQueryDbContext(SqlServerClientOptions options) + // Captured once per context: a context is scoped to one operation, and EF only re-evaluates + // plain context fields when it reuses the cached model. + bool _crossesTenants = true; + string? _tenantId; + + /// The tenant owning rows written through this context. + public string? TenantId => _tenantId; + + void SetTenant(ICurrentTenant? currentTenant) + { + var scope = (currentTenant ?? new SystemCurrentTenant()).Current; + _crossesTenants = scope.IsSystem; + _tenantId = scope.TenantId; + } + + public SnapshotQueryDbContext(SqlServerClientOptions options, ICurrentTenant? currentTenant = null) { _options = options; + SetTenant(currentTenant); } - public SnapshotQueryDbContext(SqlServerClientOptions options, SqlConnection connection) + public SnapshotQueryDbContext( + SqlServerClientOptions options, + SqlConnection connection, + ICurrentTenant? currentTenant = null + ) { _options = options; _connection = connection; + SetTenant(currentTenant); } public DbSet> Snapshots => Set>(); + public object CreateModelCacheKey(bool designTime) => + (typeof(SnapshotQueryDbContext<>), typeof(TAggregate), _options.SchemaName, _options.TableName, designTime); + protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder) { - RegisterScalarValueObjectConversions(configurationBuilder, typeof(TAggregate)); + SnapshotModelMapper.RegisterScalarValueObjectConversions(configurationBuilder, typeof(TAggregate)); } protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) @@ -325,793 +381,25 @@ protected override void OnModelCreating(ModelBuilder modelBuilder) entity.Property(static x => x.Id).HasMaxLength(450); entity.Property(static x => x.AggregateType).HasMaxLength(450); entity.HasIndex(static x => x.AggregateType); - ValidateAggregatePayloadShape(typeof(TAggregate)); + entity.Property(x => x.TenantId).HasMaxLength(450); + + // A global filter rather than a per-query predicate: the snapshot store is the queryable + // read model, so a query that forgets the tenant returns another tenant's aggregates. + // An unowned row is visible only to the system scope: treating it as visible to everyone + // would turn a missed stamp on any write path into silent cross-tenant exposure. + entity.HasQueryFilter(x => _crossesTenants || x.TenantId == _tenantId); + SnapshotModelMapper.ValidateAggregatePayloadShape(typeof(TAggregate)); entity.ComplexProperty( static x => x.Payload, static payload => { payload.ToJson(); - ConfigureComplexGraph(payload, typeof(TAggregate)); + SnapshotModelMapper.ConfigureGraph(SnapshotGraphBuilder.For(payload), typeof(TAggregate)); } ); } } - static void RegisterScalarValueObjectConversions(ModelConfigurationBuilder configurationBuilder, Type rootType) - { - HashSet visited = []; - RegisterScalarValueObjectConversionsRecursive(configurationBuilder, rootType, visited); - } - - static void RegisterScalarValueObjectConversionsRecursive( - ModelConfigurationBuilder configurationBuilder, - Type type, - HashSet visited - ) - { - type = Nullable.GetUnderlyingType(type) ?? type; - if (!visited.Add(type)) - return; - - var scalarAttribute = type.GetCustomAttribute(); - if (scalarAttribute is not null) - { - RegisterScalarValueObjectConversion(configurationBuilder, type, scalarAttribute); - return; - } - - if (!ShouldInspectType(type)) - return; - - foreach (var property in type.GetProperties(BindingFlags.Instance | BindingFlags.Public)) - { - var propertyType = Nullable.GetUnderlyingType(property.PropertyType) ?? property.PropertyType; - - if (propertyType == typeof(string) || propertyType == typeof(byte[])) - continue; - - if (TryGetEnumerableElementType(propertyType, out var elementType)) - { - RegisterScalarValueObjectConversionsRecursive(configurationBuilder, elementType, visited); - continue; - } - - RegisterScalarValueObjectConversionsRecursive(configurationBuilder, propertyType, visited); - } - } - - static void RegisterScalarValueObjectConversion( - ModelConfigurationBuilder configurationBuilder, - Type scalarType, - ScalarAttribute scalarAttribute - ) - { - var scalarProperty = - scalarType.GetProperty(scalarAttribute.PropertyName, BindingFlags.Instance | BindingFlags.Public) - ?? throw new InvalidOperationException( - $"'{scalarType.Name}' missing scalar property '{scalarAttribute.PropertyName}'." - ); - - var scalarPropertyType = scalarProperty.PropertyType; - var converterType = IsPrimitiveLike(scalarPropertyType) - ? typeof(ScalarValueConverter<,>).MakeGenericType(scalarType, scalarPropertyType) - : typeof(JsonScalarValueConverter<,>).MakeGenericType(scalarType, scalarPropertyType); - configurationBuilder.Properties(scalarType, builder => builder.HaveConversion(converterType)); - } - - static void ConfigureComplexGraph(ComplexPropertyBuilder builder, Type type) - { - HashSet visited = []; - ConfigureComplexGraphRecursive(builder, type, visited); - } - - static void ConfigureComplexGraphRecursive(ComplexPropertyBuilder builder, Type type, HashSet visited) - { - type = Nullable.GetUnderlyingType(type) ?? type; - if (!ShouldInspectType(type) || !visited.Add(type)) - return; - - foreach (var property in type.GetProperties(BindingFlags.Instance | BindingFlags.Public)) - { - if (ShouldSkipJsonProperty(type, property)) - { - builder.Ignore(property.Name); - continue; - } - - var propertyType = Nullable.GetUnderlyingType(property.PropertyType) ?? property.PropertyType; - - if (propertyType == typeof(string) || propertyType == typeof(byte[])) - { - MapReadOnlyConstructorBoundProperty(builder, type, property, propertyType); - continue; - } - - if (propertyType.GetCustomAttribute() is not null) - { - MapReadOnlyConstructorBoundProperty(builder, type, property, propertyType); - continue; - } - - if (HasEfOpaqueAttribute(property)) - { - MapOpaqueJsonProperty(builder, propertyType, property.Name); - continue; - } - - if (TryGetEnumerableElementType(propertyType, out var elementType)) - { - if (!IsEventStoreCollectionType(propertyType)) - throw CreateUnsupportedCollectionTypeException(type, property, propertyType); - - if (IsStructValueObjectType(elementType)) - { - MapCollectionAsJsonProperty(builder, propertyType, property.Name); - continue; - } - - if (IsPrimitiveLike(elementType) || elementType.GetCustomAttribute() is not null) - builder.PrimitiveCollection(propertyType, property.Name); - else if (ShouldInspectType(elementType)) - builder.ComplexCollection( - propertyType, - property.Name, - nested => ConfigureComplexGraphRecursive(nested, elementType, [with(visited)]) - ); - else - throw CreateUnsupportedShapeException(type, property); - - continue; - } - - if (IsDictionaryLikeType(propertyType) || IsJsonConvertibleCollectionType(propertyType)) - { - MapJsonProperty(builder, propertyType, property.Name); - continue; - } - - if (IsCollectionLikeType(propertyType)) - throw CreateUnsupportedCollectionTypeException(type, property, propertyType); - - if (ShouldOwnType(propertyType)) - { - builder.ComplexProperty( - propertyType, - property.Name, - nested => ConfigureComplexGraphRecursive(nested, propertyType, [with(visited)]) - ); - continue; - } - - if (IsPrimitiveLike(propertyType)) - { - MapReadOnlyConstructorBoundProperty(builder, type, property, propertyType); - continue; - } - - throw CreateUnsupportedShapeException(type, property); - } - } - - static void ConfigureComplexGraphRecursive(ComplexCollectionBuilder builder, Type type, HashSet visited) - { - type = Nullable.GetUnderlyingType(type) ?? type; - if (!ShouldInspectType(type) || !visited.Add(type)) - return; - - foreach (var property in type.GetProperties(BindingFlags.Instance | BindingFlags.Public)) - { - if (ShouldSkipJsonProperty(type, property)) - { - builder.Ignore(property.Name); - continue; - } - - var propertyType = Nullable.GetUnderlyingType(property.PropertyType) ?? property.PropertyType; - - if (propertyType == typeof(string) || propertyType == typeof(byte[])) - { - MapReadOnlyConstructorBoundProperty(builder, type, property, propertyType); - continue; - } - - if (propertyType.GetCustomAttribute() is not null) - { - MapReadOnlyConstructorBoundProperty(builder, type, property, propertyType); - continue; - } - - if (HasEfOpaqueAttribute(property)) - { - MapOpaqueJsonProperty(builder, propertyType, property.Name); - continue; - } - - if (TryGetEnumerableElementType(propertyType, out var elementType)) - { - if (!IsEventStoreCollectionType(propertyType)) - throw CreateUnsupportedCollectionTypeException(type, property, propertyType); - - if (IsStructValueObjectType(elementType)) - { - MapCollectionAsJsonProperty(builder, propertyType, property.Name); - continue; - } - - if (IsPrimitiveLike(elementType) || elementType.GetCustomAttribute() is not null) - builder.PrimitiveCollection(propertyType, property.Name); - else if (ShouldInspectType(elementType)) - builder.ComplexCollection( - propertyType, - property.Name, - nested => ConfigureComplexGraphRecursive(nested, elementType, [with(visited)]) - ); - else - throw CreateUnsupportedShapeException(type, property); - - continue; - } - - if (IsDictionaryLikeType(propertyType) || IsJsonConvertibleCollectionType(propertyType)) - { - MapJsonProperty(builder, propertyType, property.Name); - continue; - } - - if (IsCollectionLikeType(propertyType)) - throw CreateUnsupportedCollectionTypeException(type, property, propertyType); - - if (ShouldOwnType(propertyType)) - { - builder.ComplexProperty( - propertyType, - property.Name, - nested => ConfigureComplexGraphRecursive(nested, propertyType, [with(visited)]) - ); - continue; - } - - if (IsPrimitiveLike(propertyType)) - { - MapReadOnlyConstructorBoundProperty(builder, type, property, propertyType); - continue; - } - - throw CreateUnsupportedShapeException(type, property); - } - } - - static void MapReadOnlyConstructorBoundProperty( - ComplexPropertyBuilder builder, - Type containingType, - PropertyInfo property, - Type propertyType - ) - { - if (property.GetSetMethod(true) is null && HasBindableConstructorParameter(containingType, property)) - builder.Property(propertyType, property.Name); - } - - static void MapReadOnlyConstructorBoundProperty( - ComplexCollectionBuilder builder, - Type containingType, - PropertyInfo property, - Type propertyType - ) - { - if (property.GetSetMethod(true) is null && HasBindableConstructorParameter(containingType, property)) - builder.Property(propertyType, property.Name); - } - - static void ValidateAggregatePayloadShape(Type type) - { - HashSet visited = []; - ValidateAggregatePayloadShapeRecursive(type, visited); - } - - static void ValidateAggregatePayloadShapeRecursive(Type type, HashSet visited) - { - type = Nullable.GetUnderlyingType(type) ?? type; - if (!ShouldInspectType(type) || !visited.Add(type)) - return; - - foreach (var property in type.GetProperties(BindingFlags.Instance | BindingFlags.Public)) - { - if (ShouldSkipJsonProperty(type, property)) - continue; - - var propertyType = Nullable.GetUnderlyingType(property.PropertyType) ?? property.PropertyType; - - if (propertyType == typeof(string) || propertyType == typeof(byte[])) - continue; - - if (propertyType.GetCustomAttribute() is not null) - continue; - - if (HasEfOpaqueAttribute(property)) - continue; - - if (TryGetEnumerableElementType(propertyType, out var elementType)) - { - if (!IsEventStoreCollectionType(propertyType)) - throw CreateUnsupportedCollectionTypeException(type, property, propertyType); - - if ( - !IsPrimitiveLike(elementType) - && elementType.GetCustomAttribute() is null - && !IsStructValueObjectType(elementType) - ) - { - if (!ShouldInspectType(elementType)) - throw CreateUnsupportedShapeException(type, property); - - EnsureValueTypeMemberIsWritable(type, property); - ValidateAggregatePayloadShapeRecursive(elementType, visited); - } - - continue; - } - - if (IsReadOnlyCollectionType(propertyType)) - throw CreateUnsupportedCollectionTypeException(type, property, propertyType); - - if (IsDictionaryLikeType(propertyType) || IsJsonConvertibleCollectionType(propertyType)) - continue; - - if (IsCollectionLikeType(propertyType)) - throw CreateUnsupportedCollectionTypeException(type, property, propertyType); - - if (ShouldOwnType(propertyType)) - { - EnsureValueTypeMemberIsWritable(type, property); - ValidateAggregatePayloadShapeRecursive(propertyType, visited); - continue; - } - - if (!IsPrimitiveLike(propertyType)) - throw CreateUnsupportedShapeException(type, property); - } - } - - static bool IsStructValueObjectType(Type type) => - type.IsValueType && type.GetCustomAttribute() is not null; - - // EF materializes value-type JSON members through their backing field, and it cannot rebuild an assignment to a - // read-only member while fixing up a value type, which fails snapshot query compilation with - // "Expression must be writeable" (analyzer diagnostic EVENTSTOREEF004). - static void EnsureValueTypeMemberIsWritable(Type type, PropertyInfo property) - { - if (type.IsValueType && property.GetSetMethod(nonPublic: true) is null) - throw CreateUnsupportedValueTypeMemberException(type, property); - } - - static bool HasEfOpaqueAttribute(MemberInfo member) => - member.CustomAttributes.Any(attribute => attribute.AttributeType.FullName == EFOpaqueAttributeFullName); - - static void MapOpaqueJsonProperty(ComplexPropertyBuilder builder, Type propertyType, string propertyName) - { - var propertyBuilder = builder.Property(propertyType, propertyName); - propertyBuilder.HasConversion(typeof(OpaqueJsonValueConverter<>).MakeGenericType(propertyType)); - } - - static void MapOpaqueJsonProperty(ComplexCollectionBuilder builder, Type propertyType, string propertyName) - { - var propertyBuilder = builder.Property(propertyType, propertyName); - propertyBuilder.HasConversion(typeof(OpaqueJsonValueConverter<>).MakeGenericType(propertyType)); - } - - static void MapCollectionAsJsonProperty(ComplexPropertyBuilder builder, Type propertyType, string propertyName) - { - var propertyBuilder = builder.Property(propertyType, propertyName); - var converterType = typeof(JsonValueObjectCollectionConverter<>).MakeGenericType(propertyType); - propertyBuilder.HasConversion(converterType); - } - - static void MapCollectionAsJsonProperty(ComplexCollectionBuilder builder, Type propertyType, string propertyName) - { - var propertyBuilder = builder.Property(propertyType, propertyName); - var converterType = typeof(JsonValueObjectCollectionConverter<>).MakeGenericType(propertyType); - propertyBuilder.HasConversion(converterType); - } - - static void MapJsonProperty(ComplexPropertyBuilder builder, Type propertyType, string propertyName) - { - var propertyBuilder = builder.Property(propertyType, propertyName); - var converterType = typeof(JsonValueObjectCollectionConverter<>).MakeGenericType(propertyType); - propertyBuilder.HasConversion(converterType); - } - - static void MapJsonProperty(ComplexCollectionBuilder builder, Type propertyType, string propertyName) - { - var propertyBuilder = builder.Property(propertyType, propertyName); - var converterType = typeof(JsonValueObjectCollectionConverter<>).MakeGenericType(propertyType); - propertyBuilder.HasConversion(converterType); - } - - static bool ShouldOwnType(Type type) => - !type.IsPrimitive - && !type.IsEnum - && type != typeof(string) - && type != typeof(decimal) - && type != typeof(Guid) - && type != typeof(DateTime) - && type != typeof(DateTimeOffset) - && type != typeof(DateOnly) - && type != typeof(TimeOnly) - && type != typeof(TimeSpan) - && (type.Namespace is null || !type.Namespace.StartsWith("System", StringComparison.Ordinal)) - && (type.IsClass || (type.IsValueType && !type.IsPrimitive && !type.IsEnum)); - - static bool ShouldInspectType(Type type) => - !type.IsPrimitive - && !type.IsEnum - && type != typeof(string) - && type != typeof(decimal) - && type != typeof(Guid) - && type != typeof(DateTime) - && type != typeof(DateTimeOffset) - && type != typeof(DateOnly) - && type != typeof(TimeOnly) - && type != typeof(TimeSpan) - && (type.Namespace is null || !type.Namespace.StartsWith("System", StringComparison.Ordinal)); - - static bool ShouldSkipJsonProperty(Type containingType, PropertyInfo property) => - property.GetCustomAttribute() is not null - || property.GetGetMethod(true) is null - || (property.GetSetMethod(true) is null && !HasBindableConstructorParameter(containingType, property)); - - static bool HasBindableConstructorParameter(Type containingType, PropertyInfo property) - { - var constructors = containingType.GetConstructors( - BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic - ); - foreach (var constructor in constructors) - { - foreach (var parameter in constructor.GetParameters()) - { - if ( - string.Equals(parameter.Name, property.Name, StringComparison.OrdinalIgnoreCase) - && parameter.ParameterType == property.PropertyType - ) - return true; - } - } - - return false; - } - - static bool IsPrimitiveLike(Type type) => - type.IsPrimitive - || type.IsEnum - || type == typeof(string) - || type == typeof(decimal) - || type == typeof(Uri) - || type == typeof(Guid) - || type == typeof(DateTime) - || type == typeof(DateTimeOffset) - || type == typeof(DateOnly) - || type == typeof(TimeOnly) - || type == typeof(TimeSpan) - || type == typeof(byte[]); - - static bool TryGetEnumerableElementType(Type type, out Type elementType) - { - elementType = null!; - - if (!type.IsGenericType) - return false; - - if (!IsEventStoreCollectionType(type)) - return false; - - elementType = type.GetGenericArguments()[0]; - return true; - } - - static bool IsEventStoreCollectionType(Type type) => - type.IsGenericType - && type.GetGenericTypeDefinition() is var genericDefinition - && (genericDefinition == typeof(EventStoreList<>) || genericDefinition == typeof(EventStoreSet<>)); - - static bool IsCollectionLikeType(Type type) - { - if (type == typeof(string) || type == typeof(byte[])) - return false; - - if (type.IsArray) - return true; - - if (!type.IsGenericType) - return false; - - // Test for our own collection types or if the type implements IEnumerable somewhere... - return IsEventStoreCollectionType(type) - || type.GetInterfaces().Any(i => i.IsGenericType && i.GetGenericTypeDefinition() == typeof(IEnumerable<>)); - } - - static bool IsReadOnlyCollectionType(Type type) - { - if (!type.IsGenericType) - return false; - - var genericTypeDefinition = type.GetGenericTypeDefinition(); - return genericTypeDefinition == typeof(IReadOnlyList<>) - || genericTypeDefinition == typeof(IReadOnlyCollection<>); - } - - static bool IsDictionaryLikeType(Type type) - { - if (!type.IsGenericType) - return false; - - var genericTypeDefinition = type.GetGenericTypeDefinition(); - if ( - genericTypeDefinition == typeof(Dictionary<,>) - || genericTypeDefinition == typeof(IDictionary<,>) - || genericTypeDefinition == typeof(IReadOnlyDictionary<,>) - ) - return true; - - // Test if the type implements IDictionary or IReadOnlyDictionary somewhere... - return type.GetInterfaces() - .Any(i => i.IsGenericType && i.GetGenericTypeDefinition() == typeof(IReadOnlyDictionary<,>)); - } - - static bool IsJsonConvertibleCollectionType(Type type) - { - if (type == typeof(string) || type == typeof(byte[])) - return false; - - if (!type.IsGenericType || IsEventStoreCollectionType(type) || IsDictionaryLikeType(type)) - return false; - - if (type.GetGenericTypeDefinition() == typeof(IEnumerable<>)) - return true; - - // Test if the type implements IEnumerable somewhere... - return type.GetInterfaces().Any(i => i.IsGenericType && i.GetGenericTypeDefinition() == typeof(IEnumerable<>)); - } - - static InvalidOperationException CreateUnsupportedShapeException(Type containingType, MemberInfo member) => - new( - $"{containingType.Name}.{member.Name} cannot be mapped into the snapshot JSON payload. " - + "Supported members are primitive types, [Scalar] value objects, complex types, and EventStoreList/EventStoreSet collections of those shapes." - ); - - static InvalidOperationException CreateUnsupportedCollectionTypeException( - Type containingType, - MemberInfo member, - Type collectionType - ) => - new( - $"{containingType.Name}.{member.Name} uses unsupported collection type '{collectionType.Name}'. " - + "Collection and array members must use Purview.EventSourcing.EventStoreList or Purview.EventSourcing.EventStoreSet." - ); - - static InvalidOperationException CreateUnsupportedValueTypeMemberException( - Type containingType, - MemberInfo member - ) => - new( - $"{containingType.Name}.{member.Name} is a read-only complex member of value type '{containingType.Name}' and cannot be assigned during snapshot JSON materialization, which fails queries with 'Expression must be writeable'. " - + "Add an 'init' or 'set' accessor, mark the member [JsonIgnore] to exclude it from the snapshot, or mark it [EFOpaque] to persist it as non-queryable JSON." - ); - - static void EnsureSupportedOrderByExpression(Expression queryExpression) => - new UnsupportedScalarValueOrderByDetector().Visit(queryExpression); - - static Expression> RewriteAggregateTypePredicate( - Expression> whereClause, - string aggregateType - ) - where T : class - { - AggregateTypeExpressionVisitor aggregateTypeVisitor = new(aggregateType); - var rewritten = (Expression>)aggregateTypeVisitor.Visit(whereClause); - InvariantStringMethodNormalizationVisitor invariantCasingVisitor = new(); - rewritten = (Expression>)invariantCasingVisitor.Visit(rewritten); - ScalarValueMemberAccessPredicateVisitor scalarVisitor = new(); - return (Expression>)scalarVisitor.Visit(rewritten); - } - - sealed class AggregateTypeExpressionVisitor(string aggregateType) : ExpressionVisitor - { - readonly ConstantExpression _aggregateType = Expression.Constant(aggregateType, typeof(string)); - - protected override Expression VisitMember(MemberExpression node) => - node.Member.Name == nameof(IAggregate.AggregateType) - && node.Expression is not null - && typeof(IAggregate).IsAssignableFrom(node.Expression.Type) - ? _aggregateType - : base.VisitMember(node); - } - - sealed class UnsupportedScalarValueOrderByDetector : ExpressionVisitor - { - protected override Expression VisitMethodCall(MethodCallExpression node) - { - if ( - node.Method.DeclaringType == typeof(Queryable) - && ( - node.Method.Name == nameof(Queryable.OrderBy) - || node.Method.Name == nameof(Queryable.OrderByDescending) - || node.Method.Name == nameof(Queryable.ThenBy) - || node.Method.Name == nameof(Queryable.ThenByDescending) - ) - ) - { - var lambda = (LambdaExpression)StripQuotes(node.Arguments[1]); - new ScalarValueMemberAccessDetector().Visit(lambda.Body); - } - - return base.VisitMethodCall(node); - } - - static Expression StripQuotes(Expression expression) - { - while (expression.NodeType == ExpressionType.Quote) - expression = ((UnaryExpression)expression).Operand; - - return expression; - } - } - - sealed class ScalarValueMemberAccessPredicateVisitor : ExpressionVisitor - { - protected override Expression VisitBinary(BinaryExpression node) - { - var visitedLeft = Visit(node.Left); - var visitedRight = Visit(node.Right); - - return - (node.NodeType == ExpressionType.Equal || node.NodeType == ExpressionType.NotEqual) - && TryRewriteScalarPrimitiveComparison( - visitedLeft, - visitedRight, - out var rewrittenLeft, - out var rewrittenRight - ) - ? Expression.MakeBinary(node.NodeType, rewrittenLeft, rewrittenRight) - : node.Update(visitedLeft, node.Conversion, visitedRight); - } - - protected override Expression VisitMember(MemberExpression node) - { - var visitedExpression = base.VisitMember(node); - if (visitedExpression is not MemberExpression visited || visited.Expression is null) - return visitedExpression; - - var scalarAttribute = visited.Expression.Type.GetCustomAttribute(); - if (scalarAttribute is null || visited.Member.Name != scalarAttribute.PropertyName) - return visited; - - try - { - return Expression.Convert(visited.Expression, visited.Type); - } - catch (InvalidOperationException) - { - return visited; - } - } - - static bool TryRewriteScalarPrimitiveComparison( - Expression left, - Expression right, - out Expression rewrittenLeft, - out Expression rewrittenRight - ) - { - rewrittenLeft = left; - rewrittenRight = right; - - if ( - TryGetScalarPropertyType(left.Type, out var leftScalarType) - && IsSameOrNullable(right.Type, leftScalarType) - ) - { - rewrittenLeft = Expression.Convert(left, right.Type); - return true; - } - - if ( - TryGetScalarPropertyType(right.Type, out var rightScalarType) - && IsSameOrNullable(left.Type, rightScalarType) - ) - { - rewrittenRight = Expression.Convert(right, left.Type); - return true; - } - - return false; - } - - static bool TryGetScalarPropertyType(Type candidateType, out Type scalarPropertyType) - { - scalarPropertyType = null!; - var scalarAttribute = candidateType.GetCustomAttribute(); - if (scalarAttribute is null) - return false; - - var scalarProperty = candidateType.GetProperty( - scalarAttribute.PropertyName, - BindingFlags.Instance | BindingFlags.Public - ); - if (scalarProperty is null) - return false; - - scalarPropertyType = scalarProperty.PropertyType; - return true; - } - - static bool IsSameOrNullable(Type candidate, Type expected) - { - var underlyingType = Nullable.GetUnderlyingType(candidate); - return candidate == expected || underlyingType == expected; - } - } - - sealed class InvariantStringMethodNormalizationVisitor : ExpressionVisitor - { - protected override Expression VisitMethodCall(MethodCallExpression node) - { - var visitedObject = Visit(node.Object); - var visitedArguments = Visit(node.Arguments); - - if (node.Method.DeclaringType == typeof(string) && node.Arguments.Count == 0 && visitedObject is not null) - { - if (node.Method.Name == nameof(string.ToLowerInvariant)) - return Expression.Call(visitedObject, nameof(string.ToLower), Type.EmptyTypes); - - if (node.Method.Name == nameof(string.ToUpperInvariant)) - return Expression.Call(visitedObject, nameof(string.ToUpper), Type.EmptyTypes); - } - - return node.Update(visitedObject, visitedArguments); - } - } - - sealed class ScalarValueMemberAccessDetector : ExpressionVisitor - { - protected override Expression VisitMember(MemberExpression node) - { - var visited = base.VisitMember(node); - if (node.Expression is null) - return visited; - - var scalarAttribute = node.Expression.Type.GetCustomAttribute(); - return scalarAttribute is not null && node.Member.Name == scalarAttribute.PropertyName - ? throw new InvalidOperationException( - $"Ordering by '{node.Expression.Type.Name}.{node.Member.Name}' is not supported for SQL snapshot JSON queries. " - + "Order by the scalar value object property itself (for example: c => c.Name) instead of its inner scalar member." - ) - : visited; - } - } - - sealed class SnapshotModelCacheKeyFactory : IModelCacheKeyFactory - { - public object Create(DbContext context, bool designTime) - { - var optionsField = context.GetType().GetField("_options", BindingFlags.Instance | BindingFlags.NonPublic); - if (optionsField?.GetValue(context) is SqlServerClientOptions options) - { - if ( - context.GetType().IsGenericType - && context.GetType().GetGenericTypeDefinition() == typeof(SnapshotQueryDbContext<>) - ) - { - var aggregateType = context.GetType().GenericTypeArguments[0]; - return (context.GetType(), aggregateType, options.SchemaName, options.TableName, designTime); - } - - return (context.GetType(), options.SchemaName, options.TableName, designTime); - } - - return (context.GetType(), designTime); - } - } - async Task EnsureTableIfEnabledAsync(CancellationToken cancellationToken) { if (!_options.AutoCreateTable || IsTableEnsured()) diff --git a/src/src/SqlServer/Events/AggregateVersionData.cs b/src/src/SqlServer/Events/AggregateVersionData.cs index 9347f109..a68689ce 100644 --- a/src/src/SqlServer/Events/AggregateVersionData.cs +++ b/src/src/SqlServer/Events/AggregateVersionData.cs @@ -12,7 +12,7 @@ namespace Purview.EventSourcing.SqlServer.Events; /// The version of the aggregate persisted in the event store. /// The version of the aggregate captured in the latest snapshot. /// The current version of the aggregate, including unsaved events. -public record struct AggregateVersionData(int SavedVersion, int SnapshotVersion, int CurrentVersion) +public record struct AggregateVersionData(long SavedVersion, long SnapshotVersion, long CurrentVersion) { /// /// Creates an instance from the specified aggregate's details. diff --git a/src/src/SqlServer/Events/EntityFramework/EventStoreDbContext.cs b/src/src/SqlServer/Events/EntityFramework/EventStoreDbContext.cs index 5c7e22f7..6589fb9a 100644 --- a/src/src/SqlServer/Events/EntityFramework/EventStoreDbContext.cs +++ b/src/src/SqlServer/Events/EntityFramework/EventStoreDbContext.cs @@ -1,5 +1,6 @@ -using Microsoft.EntityFrameworkCore; +using Microsoft.EntityFrameworkCore; using Microsoft.EntityFrameworkCore.Infrastructure; +using Purview.EventSourcing.Tenancy; namespace Purview.EventSourcing.SqlServer.Events.EntityFramework; @@ -11,12 +12,21 @@ namespace Purview.EventSourcing.SqlServer.Events.EntityFramework; /// /// Creates a new with explicit schema and table names. /// -public class EventStoreDbContext(DbContextOptions options, string schemaName, string tableName) - : DbContext(options) +public class EventStoreDbContext( + DbContextOptions options, + string schemaName, + string tableName, + ICurrentTenant? currentTenant = null +) : DbContext(options) { readonly string _schemaName = schemaName; readonly string _tableName = tableName; + // Captured once per context rather than read per query: a context is short-lived and scoped to one + // operation, and EF only re-evaluates plain context fields when it reuses the cached model. + readonly bool _crossesTenants = (currentTenant?.Current ?? TenantScope.System).IsSystem; + readonly string? _tenantId = (currentTenant?.Current ?? TenantScope.System).TenantId; + /// /// All event store rows (stream versions, events, idempotency markers, snapshots). /// @@ -52,6 +62,12 @@ protected override void OnModelCreating(ModelBuilder modelBuilder) entity.Property(e => e.CorrelationId).HasMaxLength(450); entity.Property(e => e.CausationId).HasMaxLength(450); entity.Property(e => e.UserId).HasMaxLength(450); + entity.Property(e => e.TenantId).HasMaxLength(450); + + // A global filter rather than a per-query predicate: a read that forgets the tenant is the + // failure mode this exists to prevent, and EF applies this to every LINQ query on the set. + // Both members are fields, so EF parameterises them and one cached model serves all tenants. + entity.HasQueryFilter(e => _crossesTenants || e.TenantId == _tenantId); entity.Property(e => e.Timestamp).HasDefaultValueSql("SYSUTCDATETIME()").IsRequired(); // Covers: GetByAggregateIdAndEntityType, GetIdempotencyMarkers, DeleteByAggregateId diff --git a/src/src/SqlServer/Events/EntityFramework/EventStoreEntity.cs b/src/src/SqlServer/Events/EntityFramework/EventStoreEntity.cs index 2fb0f5df..1f74e90a 100644 --- a/src/src/SqlServer/Events/EntityFramework/EventStoreEntity.cs +++ b/src/src/SqlServer/Events/EntityFramework/EventStoreEntity.cs @@ -1,4 +1,4 @@ -namespace Purview.EventSourcing.SqlServer.Events.EntityFramework; +namespace Purview.EventSourcing.SqlServer.Events.EntityFramework; /// /// EF Core entity model representing a row in the SQL Server event store table. @@ -29,7 +29,7 @@ public sealed class EventStoreEntity /// /// The event or stream version number. /// - public int Version { get; set; } + public long Version { get; set; } /// /// Whether this aggregate has been soft-deleted. @@ -63,6 +63,9 @@ public sealed class EventStoreEntity /// The user identifier recorded with the event. public string? UserId { get; set; } + /// The tenant that owns the row; null in a single-tenant deployment. + public string? TenantId { get; set; } + /// /// UTC timestamp of when this row was created or last modified. /// diff --git a/src/src/SqlServer/Events/Exceptions/AggregateAlreadyDeletedException.cs b/src/src/SqlServer/Events/Exceptions/AggregateAlreadyDeletedException.cs deleted file mode 100644 index 97c9801c..00000000 --- a/src/src/SqlServer/Events/Exceptions/AggregateAlreadyDeletedException.cs +++ /dev/null @@ -1,24 +0,0 @@ -namespace Purview.EventSourcing.SqlServer.Events.Exceptions; - -/// -/// Thrown when an attempt is made to delete an aggregate that is already deleted. -/// -/// The id of the aggregate. -/// The idempotency identifier of the delete operation. -#pragma warning disable CA1032 // Implement standard exception constructors -public class AggregateAlreadyDeletedException(string aggregateId, string idempotencyId) - : Exception( - $"An attempt to delete an aggregate (Id: {aggregateId}) that is already deleted was made. {nameof(idempotencyId)}: {idempotencyId}." - ) -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The id of the aggregate that was already deleted. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// The idempotency identifier of the delete operation. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/SqlServer/Events/Exceptions/AggregateDeletedException.cs b/src/src/SqlServer/Events/Exceptions/AggregateDeletedException.cs deleted file mode 100644 index e6f437de..00000000 --- a/src/src/SqlServer/Events/Exceptions/AggregateDeletedException.cs +++ /dev/null @@ -1,24 +0,0 @@ -namespace Purview.EventSourcing.SqlServer.Events.Exceptions; - -/// -/// Thrown when an attempt is made to save an aggregate that has been deleted. -/// -/// The id of the aggregate. -/// The idempotency identifier of the save operation. -#pragma warning disable CA1032 // Implement standard exception constructors -public class AggregateDeletedException(string aggregateId, string idempotencyId) - : Exception( - $"An attempt to save an aggregate that has been deleted, aggregate Id: {aggregateId}, {nameof(IdempotencyId)}: {idempotencyId}." - ) -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The id of the aggregate that has been deleted. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// The idempotency identifier of the save operation. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/SqlServer/Events/Exceptions/AggregateIsDeletedException.cs b/src/src/SqlServer/Events/Exceptions/AggregateIsDeletedException.cs deleted file mode 100644 index 46e6d5a4..00000000 --- a/src/src/SqlServer/Events/Exceptions/AggregateIsDeletedException.cs +++ /dev/null @@ -1,16 +0,0 @@ -namespace Purview.EventSourcing.SqlServer.Events.Exceptions; - -/// -/// Thrown when an invalid operation is attempted against an aggregate that has been deleted. -/// -/// The id of the aggregate. -#pragma warning disable CA1032 // Implement standard exception constructors -public class AggregateIsDeletedException(string aggregateId) - : Exception($"Invalid operation against an aggregate (Id: {aggregateId}) that has been deleted.") -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The id of the aggregate that has been deleted. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); -} diff --git a/src/src/SqlServer/Events/Exceptions/AggregateLockedException.cs b/src/src/SqlServer/Events/Exceptions/AggregateLockedException.cs deleted file mode 100644 index d2286e40..00000000 --- a/src/src/SqlServer/Events/Exceptions/AggregateLockedException.cs +++ /dev/null @@ -1,18 +0,0 @@ -namespace Purview.EventSourcing.SqlServer.Events.Exceptions; - -/// -/// Thrown when an attempt is made to save an aggregate that is currently locked. -/// -/// The idempotency identifier of the save operation. -#pragma warning disable CA1032 // Implement standard exception constructors -public class AggregateLockedException(string idempotencyId) - : Exception( - $"An attempt to save an aggregate that is currently locked was made, {nameof(idempotencyId)}: {idempotencyId}." - ) -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The idempotency identifier of the save operation. - /// - public string IdempotencyId { get; set; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/SqlServer/Events/Exceptions/AggregateNotDeletedException.cs b/src/src/SqlServer/Events/Exceptions/AggregateNotDeletedException.cs deleted file mode 100644 index 5b5c8203..00000000 --- a/src/src/SqlServer/Events/Exceptions/AggregateNotDeletedException.cs +++ /dev/null @@ -1,16 +0,0 @@ -namespace Purview.EventSourcing.SqlServer.Events.Exceptions; - -/// -/// Thrown when an attempt is made to get an aggregate that has not been deleted. -/// -/// The id of the aggregate. -#pragma warning disable CA1032 // Implement standard exception constructors -public class AggregateNotDeletedException(string aggregateId) - : Exception($"An attempt to get an aggregate that has not been deleted, aggregate Id: {aggregateId}.") -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The id of the aggregate that is not deleted. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); -} diff --git a/src/src/SqlServer/Events/Exceptions/AggregateStreamVersionMissingException.cs b/src/src/SqlServer/Events/Exceptions/AggregateStreamVersionMissingException.cs deleted file mode 100644 index 61a5d689..00000000 --- a/src/src/SqlServer/Events/Exceptions/AggregateStreamVersionMissingException.cs +++ /dev/null @@ -1,24 +0,0 @@ -namespace Purview.EventSourcing.SqlServer.Events.Exceptions; - -/// -/// Thrown when an operation requires a stream-version row that is missing. -/// -/// The id of the aggregate. -/// The idempotency identifier of the operation. -#pragma warning disable CA1032 // Implement standard exception constructors -public class AggregateStreamVersionMissingException(string aggregateId, string idempotencyId) - : Exception( - $"An attempt to delete an aggregate (Id: {aggregateId}) that doesn't a stream version deleted was made. {nameof(idempotencyId)}: {idempotencyId}." - ) -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The id of the aggregate whose stream version is missing. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// The idempotency identifier of the operation. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/SqlServer/Events/Exceptions/AggregatedNotAlreadyDeletedException.cs b/src/src/SqlServer/Events/Exceptions/AggregatedNotAlreadyDeletedException.cs deleted file mode 100644 index 509e76a0..00000000 --- a/src/src/SqlServer/Events/Exceptions/AggregatedNotAlreadyDeletedException.cs +++ /dev/null @@ -1,24 +0,0 @@ -namespace Purview.EventSourcing.SqlServer.Events.Exceptions; - -/// -/// Thrown when an attempt is made to restore an aggregate that is not deleted. -/// -/// The id of the aggregate. -/// The idempotency identifier of the restore operation. -#pragma warning disable CA1032 // Implement standard exception constructors -public class AggregatedNotAlreadyDeletedException(string aggregateId, string idempotencyId) - : Exception( - $"An attempt to restore an aggregate (Id: {aggregateId}) that is not deleted was made.\n\n\tIdempotencyId: {idempotencyId}." - ) -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The id of the aggregate that is not deleted. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// The idempotency identifier of the restore operation. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); -} diff --git a/src/src/SqlServer/Events/Exceptions/CommitException.cs b/src/src/SqlServer/Events/Exceptions/CommitException.cs deleted file mode 100644 index 59c341f5..00000000 --- a/src/src/SqlServer/Events/Exceptions/CommitException.cs +++ /dev/null @@ -1,44 +0,0 @@ -namespace Purview.EventSourcing.SqlServer.Events.Exceptions; - -/// -/// Thrown when a batch of events fails to commit to the SQL Server event store. -/// -/// The id of the aggregate. -/// The idempotency identifier of the save operation. -/// The aggregate version that was attempted. -/// The version currently present in the store. -/// The underlying exception that caused the commit to fail. -#pragma warning disable CA1032 // Implement standard exception constructors -public class CommitException( - string aggregateId, - string idempotencyId, - int versionAttempted, - int version, - Exception exception -) - : Exception( - $"Failed to commit events.\n\tAggregateId: {aggregateId}\n\tIdempotencyId: {idempotencyId}\n\tVersionAttempted: {versionAttempted}\n\tVersionPresent: {version}", - exception - ) -#pragma warning restore CA1032 // Implement standard exception constructors -{ - /// - /// The id of the aggregate that failed to commit. - /// - public string AggregateId { get; } = aggregateId ?? throw new ArgumentNullException(nameof(aggregateId)); - - /// - /// The aggregate version that was attempted. - /// - public int VersionAttempted { get; } = versionAttempted; - - /// - /// The idempotency identifier of the save operation. - /// - public string IdempotencyId { get; } = idempotencyId ?? throw new ArgumentNullException(nameof(idempotencyId)); - - /// - /// The version currently present in the store. - /// - public int Version { get; } = version; -} diff --git a/src/src/SqlServer/Events/ISqlServerEventStoreTelemetry.cs b/src/src/SqlServer/Events/ISqlServerEventStoreTelemetry.cs index 0a8cf5c8..68dfb61b 100644 --- a/src/src/SqlServer/Events/ISqlServerEventStoreTelemetry.cs +++ b/src/src/SqlServer/Events/ISqlServerEventStoreTelemetry.cs @@ -1,4 +1,4 @@ -using System.Diagnostics; +using System.Diagnostics; using Microsoft.Extensions.Logging; using Purview.Telemetry; @@ -35,7 +35,7 @@ public interface ISqlServerEventStoreTelemetry /// The full name of the aggregate type. /// The activity, or when tracing is not enabled. [Activity] - Activity? GetAggregateAtVersion(string aggregateId, int version, [Baggage] string aggregateTypeFullName); + Activity? GetAggregateAtVersion(string aggregateId, long version, [Baggage] string aggregateTypeFullName); /// /// Starts an activity representing a save-aggregate operation. @@ -62,7 +62,7 @@ public interface ISqlServerEventStoreTelemetry /// The number of events applied. /// The resulting aggregate version. [Event] - void EventsReconstituted(Activity? activity, int eventCount, int version); + void EventsReconstituted(Activity? activity, int eventCount, long version); /// /// Records the completion of a save operation. @@ -124,7 +124,7 @@ public interface ISqlServerEventStoreTelemetry void GetAggregateAtSpecificVersionFailed( string aggregateId, string aggregateTypeFullName, - int specificVersion, + long specificVersion, Exception exception ); @@ -152,7 +152,7 @@ AggregateVersionData versionData /// The version being retrieved. /// The full name of the aggregate type. [Log(LogLevel.Debug)] - void GetAggregateAtSpecificVersionStart(string aggregateId, int specificVersion, string aggregateTypeFullName); + void GetAggregateAtSpecificVersionStart(string aggregateId, long specificVersion, string aggregateTypeFullName); /// /// Logs that a save operation contained no changes. @@ -177,7 +177,7 @@ void SkippedUnknownEvent( string aggregateTypeFullName, string aggregateType, string eventType, - int aggregateVersion + long aggregateVersion ); /// @@ -196,7 +196,7 @@ void CannotApplyEvent( string aggregateType, string eventType, string eventTypeFullName, - int aggregateVersion + long aggregateVersion ); /// @@ -316,7 +316,7 @@ int aggregateVersion void GetAggregateAtSpecificVersionComplete( string aggregateId, string aggregateTypeFullName, - int specificVersion, + long specificVersion, long elapsedMilliseconds ); @@ -385,7 +385,7 @@ string aggregateTypeFullName /// The short name of the aggregate type. /// Whether the aggregate is soft-deleted. [Log(LogLevel.Debug)] - void StreamVersionFound(string aggregateId, int streamVersion, string aggregateType, bool isDeleted); + void StreamVersionFound(string aggregateId, long streamVersion, string aggregateType, bool isDeleted); /// /// Logs a failure while retrieving the stream version. diff --git a/src/src/SqlServer/Events/SqlServerEventStore.DeleteAsync.cs b/src/src/SqlServer/Events/SqlServerEventStore.DeleteAsync.cs index b452c5dd..6c53b7b6 100644 --- a/src/src/SqlServer/Events/SqlServerEventStore.DeleteAsync.cs +++ b/src/src/SqlServer/Events/SqlServerEventStore.DeleteAsync.cs @@ -1,12 +1,14 @@ using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.SqlServer.Events; partial class SqlServerEventStore { /// - public async Task DeleteAsync( + public async Task, AggregateDeleteFailure>> DeleteAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -16,12 +18,20 @@ public async Task DeleteAsync( throw NullAggregate(aggregate); if (aggregate.Details.IsDeleted) - throw AggregateIsDeletedException(aggregate.Id()); + { + return AggregateDeleteFailure.Failure>( + new AggregateAlreadyDeleted(aggregate.AggregateType, aggregate.Id()) + ); + } operationContext ??= EventStoreOperationContext.DefaultContext(); if (aggregate.IsNew()) - return false; + { + return AggregateDeleteFailure.Failure>( + new AggregateNotFound(aggregate.AggregateType, aggregate.Id()) + ); + } if (operationContext.PermanentlyDelete) return await PermanentlyDeleteAsync(aggregate, operationContext, cancellationToken); @@ -46,12 +56,15 @@ public async Task DeleteAsync( cancellationToken, new EventRecord(deleteAggregateEvent, metadata) ); + if (result.Result.IsFailure) + return result.Result.Error.ToDeleteFailure(); + await result.AfterCommitAsync(cancellationToken); - return result.Result.Saved; + return result.Result.Value; } - async Task PermanentlyDeleteAsync( + async Task, AggregateDeleteFailure>> PermanentlyDeleteAsync( T aggregate, EventStoreOperationContext operationContext, CancellationToken cancellationToken = default @@ -63,7 +76,11 @@ async Task PermanentlyDeleteAsync( var aggregateId = aggregate.Id(); var streamVersion = await GetStreamVersionAsync(aggregateId, true, cancellationToken); if (streamVersion == null) - return false; + { + return AggregateDeleteFailure.Failure>( + new AggregateNotFound(aggregate.AggregateType, aggregateId) + ); + } _eventStoreTelemetry.PermanentDeleteRequested(aggregateId); using var activity = _eventStoreTelemetry.DeleteAggregate(aggregateId, _aggregateTypeFullName); @@ -77,7 +94,7 @@ async Task PermanentlyDeleteAsync( aggregate.Details.IsDeleted = true; aggregate.Details.Locked = true; - return true; + return new SaveOutcome(aggregate, SaveOutcomeKind.Written); } #pragma warning disable CA1031 catch (Exception ex) @@ -85,7 +102,7 @@ async Task PermanentlyDeleteAsync( { _eventStoreTelemetry.PermanentDeleteFailed(aggregateId, ex); - return false; + throw; } finally { diff --git a/src/src/SqlServer/Events/SqlServerEventStore.ExceptionHelpers.cs b/src/src/SqlServer/Events/SqlServerEventStore.ExceptionHelpers.cs index e08decbc..d4c47b3f 100644 --- a/src/src/SqlServer/Events/SqlServerEventStore.ExceptionHelpers.cs +++ b/src/src/SqlServer/Events/SqlServerEventStore.ExceptionHelpers.cs @@ -1,4 +1,5 @@ -using Purview.EventSourcing.SqlServer.Events.Exceptions; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.SqlServer.Events; @@ -7,7 +8,12 @@ partial class SqlServerEventStore { static ArgumentNullException NullAggregate(T? aggregate) => new(nameof(aggregate)); - static AggregateIsDeletedException AggregateIsDeletedException(string aggregateId) => new(aggregateId); + Result NotFound(string aggregateId) => + AggregateReadFailure.Failure(new AggregateNotFound(_aggregateTypeShortName, aggregateId)); - static AggregateNotDeletedException AggregateNotDeletedException(string aggregateId) => new(aggregateId); + Result Deleted(string aggregateId) => + AggregateReadFailure.Failure(new AggregateDeleted(_aggregateTypeShortName, aggregateId)); + + Result NotDeleted(string aggregateId) => + AggregateReadFailure.Failure(new AggregateNotDeleted(_aggregateTypeShortName, aggregateId)); } diff --git a/src/src/SqlServer/Events/SqlServerEventStore.ExistsAsync.cs b/src/src/SqlServer/Events/SqlServerEventStore.ExistsAsync.cs index 633204d5..01ba7065 100644 --- a/src/src/SqlServer/Events/SqlServerEventStore.ExistsAsync.cs +++ b/src/src/SqlServer/Events/SqlServerEventStore.ExistsAsync.cs @@ -1,18 +1,18 @@ -namespace Purview.EventSourcing.SqlServer.Events; +namespace Purview.EventSourcing.SqlServer.Events; partial class SqlServerEventStore { /// - public async Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) + public async Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) { ArgumentException.ThrowIfNullOrWhiteSpace(aggregateId, nameof(aggregateId)); var streamVersion = await GetStreamVersionAsync(aggregateId, false, cancellationToken); return streamVersion == null - ? ExistsState.DoesNotExist - : new ExistsState + ? AggregateExistence.DoesNotExist + : new AggregateExistence { - Status = streamVersion.IsDeleted ? ExistsStatus.ExistsInDeletedState : ExistsStatus.Exists, + Status = streamVersion.IsDeleted ? ExistenceStatus.ExistsInDeletedState : ExistenceStatus.Exists, Version = streamVersion.Version, }; } diff --git a/src/src/SqlServer/Events/SqlServerEventStore.GetAsync.cs b/src/src/SqlServer/Events/SqlServerEventStore.GetAsync.cs index 89d0f615..67a2fc0e 100644 --- a/src/src/SqlServer/Events/SqlServerEventStore.GetAsync.cs +++ b/src/src/SqlServer/Events/SqlServerEventStore.GetAsync.cs @@ -2,6 +2,8 @@ using Microsoft.Extensions.Caching.Distributed; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.SqlServer.Events; @@ -9,13 +11,13 @@ partial class SqlServerEventStore { /// [System.Diagnostics.DebuggerStepThrough] - public Task GetAsync( + public Task> GetAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => GetCoreAsync(aggregateId, operationContext, cancellationToken); - async Task GetCoreAsync( + async Task> GetCoreAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -44,9 +46,9 @@ partial class SqlServerEventStore { _eventStoreTelemetry.AggregateRetrievedFromCache(aggregateId, _aggregateTypeFullName); - return ReturnAggregate(aggregate.Details.IsDeleted, aggregateId, operationContext) + return ReturnAggregate(aggregate.Details.IsDeleted, operationContext) ? PrepareAggregateForReturn(aggregate, _aggregateRequirementsManager) - : null; + : Deleted(aggregateId); } // Single-flight: when the aggregate will be written back to the cache, serialize @@ -72,20 +74,20 @@ partial class SqlServerEventStore { _eventStoreTelemetry.AggregateRetrievedFromCache(aggregateId, _aggregateTypeFullName); - return ReturnAggregate(cached.Details.IsDeleted, aggregateId, operationContext) + return ReturnAggregate(cached.Details.IsDeleted, operationContext) ? PrepareAggregateForReturn(cached, _aggregateRequirementsManager) - : null; + : Deleted(aggregateId); } } var streamVersion = await GetStreamVersionAsync(aggregateId, true, cancellationToken); if (streamVersion == null) - return null; + return NotFound(aggregateId); - if (!ReturnAggregate(streamVersion.IsDeleted, aggregateId, operationContext)) - return null; + if (!ReturnAggregate(streamVersion.IsDeleted, operationContext)) + return Deleted(aggregateId); - int? streamVersionIdentifier = null; + long? streamVersionIdentifier = null; if (!operationContext.SkipSnapshot) aggregate = await GetLatestSnapshotAsync(aggregateId, cancellationToken); @@ -111,6 +113,7 @@ partial class SqlServerEventStore _aggregateTypeFullName, getStopwatch.ElapsedMilliseconds ); + _metrics.GetDuration(getStopwatch.Elapsed.TotalMilliseconds, _aggregateTypeShortName); } async Task IsCacheHitFreshAsync(T aggregate, string aggregateId, CancellationToken cancellationToken) @@ -139,7 +142,7 @@ Services.IAggregateRequirementsManager aggregateRequirementsManager async Task GetAndApplyEventsAsync( T aggregate, StreamVersionData streamVersion, - int? maxVersion, + long? maxVersion, CancellationToken cancellationToken ) { diff --git a/src/src/SqlServer/Events/SqlServerEventStore.GetAtAsync.cs b/src/src/SqlServer/Events/SqlServerEventStore.GetAtAsync.cs index b39ae234..746e724d 100644 --- a/src/src/SqlServer/Events/SqlServerEventStore.GetAtAsync.cs +++ b/src/src/SqlServer/Events/SqlServerEventStore.GetAtAsync.cs @@ -1,13 +1,15 @@ using System.Diagnostics; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.SqlServer.Events; partial class SqlServerEventStore { /// - public async Task GetAtAsync( + public async Task> GetAtAsync( string aggregateId, - int version, + long version, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) @@ -23,10 +25,10 @@ partial class SqlServerEventStore { var streamVersion = await GetStreamVersionAsync(aggregateId, true, cancellationToken); if (streamVersion == null) - return null; + return NotFound(aggregateId); - if (!ReturnAggregate(streamVersion.IsDeleted, aggregateId, operationContext)) - return null; + if (!ReturnAggregate(streamVersion.IsDeleted, operationContext)) + return Deleted(aggregateId); T aggregate = new() { Details = { Id = aggregateId } }; diff --git a/src/src/SqlServer/Events/SqlServerEventStore.GetDeletedAsync.cs b/src/src/SqlServer/Events/SqlServerEventStore.GetDeletedAsync.cs index debe5380..b027a33e 100644 --- a/src/src/SqlServer/Events/SqlServerEventStore.GetDeletedAsync.cs +++ b/src/src/SqlServer/Events/SqlServerEventStore.GetDeletedAsync.cs @@ -1,18 +1,26 @@ -namespace Purview.EventSourcing.SqlServer.Events; +using Purview.EventSourcing.Failures; +using Purview.Results; + +namespace Purview.EventSourcing.SqlServer.Events; partial class SqlServerEventStore { /// - public async Task GetDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) + public async Task> GetDeletedAsync( + string aggregateId, + CancellationToken cancellationToken = default + ) { - var aggregate = await GetCoreAsync( + var result = await GetCoreAsync( aggregateId, new() { SnapshotCacheMode = SnapshotCachingOptions.None, DeleteMode = DeleteHandlingMode.ReturnsAggregate }, cancellationToken ); + if (result.IsFailure) + return result; + + var aggregate = result.Value; - return aggregate == null ? null - : aggregate.Details.IsDeleted ? FulfilRequirements(aggregate) - : throw AggregateNotDeletedException(aggregateId); + return aggregate.Details.IsDeleted ? FulfilRequirements(aggregate) : NotDeleted(aggregateId); } } diff --git a/src/src/SqlServer/Events/SqlServerEventStore.GetEventRangeAsync.cs b/src/src/SqlServer/Events/SqlServerEventStore.GetEventRangeAsync.cs index 8151319d..87eb431c 100644 --- a/src/src/SqlServer/Events/SqlServerEventStore.GetEventRangeAsync.cs +++ b/src/src/SqlServer/Events/SqlServerEventStore.GetEventRangeAsync.cs @@ -16,8 +16,8 @@ partial class SqlServerEventStore /// If no is specified all available events greater than are returned. public async IAsyncEnumerable<(EventRecord EventRecord, string EventType)> GetEventRangeAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, [EnumeratorCancellation] CancellationToken cancellationToken ) { @@ -46,16 +46,20 @@ [EnumeratorCancellation] CancellationToken cancellationToken ); await foreach (var entity in entities) { - var item = DeserializeEvent(entity); + var item = await DeserializeEventAsync(entity, cancellationToken); if (item != null) yield return (item.Value, entity.EventType!); } } /// - EventRecord? DeserializeEvent(SqlServerEventStoreClient.RowData eventRow) + /// + async Task DeserializeEventAsync( + SqlServerEventStoreClient.RowData eventRow, + CancellationToken cancellationToken + ) { - static UnknownEvent ReturnUnknownEvent(SqlServerEventStoreClient.RowData eventRow, int aggregateVersion) => + static UnknownEvent ReturnUnknownEvent(SqlServerEventStoreClient.RowData eventRow, long aggregateVersion) => new() { SchemaVersion = eventRow.SchemaVersion, @@ -97,7 +101,19 @@ static UnknownEvent ReturnUnknownEvent(SqlServerEventStoreClient.RowData eventRo Type.GetType(name, throwOnError: false) ?? throw new ApplicationException($"Unable to load event type: {name}") ); - var @event = DeserializeEvent(eventRow.Payload!, runtimeEventType); + var payload = eventRow.Payload!; + if (_payloadProtector is not null && _payloadProtector.IsProtected(payload)) + { + var unprotected = await _payloadProtector.UnprotectAsync(payload, cancellationToken); + if (unprotected is null) + // The subject has been erased. Surfaced as an unknown event so replay continues and + // the aggregate reports the gap, rather than failing the whole read. + return new EventRecord(ReturnUnknownEvent(eventRow, eventRow.Version), metadata); + + payload = unprotected; + } + + var @event = DeserializeEvent(payload, runtimeEventType); // Apply upcasting chain when a registry is available. if (@event != null && _eventUpcasterRegistry?.CanUpcast(@event) == true) diff --git a/src/src/SqlServer/Events/SqlServerEventStore.GetOrCreateAsync.cs b/src/src/SqlServer/Events/SqlServerEventStore.GetOrCreateAsync.cs index e3409fab..9c1ad412 100644 --- a/src/src/SqlServer/Events/SqlServerEventStore.GetOrCreateAsync.cs +++ b/src/src/SqlServer/Events/SqlServerEventStore.GetOrCreateAsync.cs @@ -1,9 +1,12 @@ -namespace Purview.EventSourcing.SqlServer.Events; +using Purview.EventSourcing.Failures; +using Purview.Results; + +namespace Purview.EventSourcing.SqlServer.Events; partial class SqlServerEventStore { /// - public async Task GetOrCreateAsync( + public async Task> GetOrCreateAsync( string? aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -11,8 +14,8 @@ partial class SqlServerEventStore { if (!string.IsNullOrWhiteSpace(aggregateId)) { - var exists = await ExistsAsync(aggregateId, cancellationToken); - if (exists) + var existence = await ExistsAsync(aggregateId, cancellationToken); + if (existence.DoesExist) return await GetAsync(aggregateId, operationContext, cancellationToken); } diff --git a/src/src/SqlServer/Events/SqlServerEventStore.IsDeletedAsync.cs b/src/src/SqlServer/Events/SqlServerEventStore.IsDeletedAsync.cs deleted file mode 100644 index c6afa27f..00000000 --- a/src/src/SqlServer/Events/SqlServerEventStore.IsDeletedAsync.cs +++ /dev/null @@ -1,15 +0,0 @@ -namespace Purview.EventSourcing.SqlServer.Events; - -partial class SqlServerEventStore -{ - /// - public async Task IsDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) - { - ArgumentException.ThrowIfNullOrWhiteSpace(aggregateId, nameof(aggregateId)); - - var streamVersion = await GetStreamVersionAsync(aggregateId, true, cancellationToken); - return streamVersion == null - ? throw new NullReferenceException($"The aggregate specified ({aggregateId}) does not exist.") - : streamVersion.IsDeleted; - } -} diff --git a/src/src/SqlServer/Events/SqlServerEventStore.RestoreAsync.cs b/src/src/SqlServer/Events/SqlServerEventStore.RestoreAsync.cs index 8395e058..4ddb0c9e 100644 --- a/src/src/SqlServer/Events/SqlServerEventStore.RestoreAsync.cs +++ b/src/src/SqlServer/Events/SqlServerEventStore.RestoreAsync.cs @@ -1,12 +1,14 @@ using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.SqlServer.Events; partial class SqlServerEventStore { /// - public async Task RestoreAsync( + public async Task, AggregateRestoreFailure>> RestoreAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -16,7 +18,11 @@ public async Task RestoreAsync( throw NullAggregate(aggregate); if (!aggregate.Details.IsDeleted) - throw AggregateNotDeletedException(aggregate.Id()); + { + return AggregateRestoreFailure.Failure>( + new AggregateNotDeleted(aggregate.AggregateType, aggregate.Id()) + ); + } operationContext ??= EventStoreOperationContext.DefaultContext(); @@ -33,7 +39,11 @@ public async Task RestoreAsync( aggregate.ApplyEvent(restoreAggregateEvent, metadata); if (aggregate.IsNew()) - return false; + { + return AggregateRestoreFailure.Failure>( + new AggregateNotFound(aggregate.AggregateType, aggregate.Id()) + ); + } var result = await SaveCoreAsync( aggregate, @@ -43,7 +53,11 @@ public async Task RestoreAsync( cancellationToken, new EventRecord(restoreAggregateEvent, metadata) ); + if (result.Result.IsFailure) + return result.Result.Error.ToRestoreFailure(); + await result.AfterCommitAsync(cancellationToken); - return result.Result.Saved; + + return result.Result.Value; } } diff --git a/src/src/SqlServer/Events/SqlServerEventStore.SaveAsync.cs b/src/src/SqlServer/Events/SqlServerEventStore.SaveAsync.cs index 6ed6286c..8112b09a 100644 --- a/src/src/SqlServer/Events/SqlServerEventStore.SaveAsync.cs +++ b/src/src/SqlServer/Events/SqlServerEventStore.SaveAsync.cs @@ -2,15 +2,16 @@ using System.Diagnostics; using System.Diagnostics.CodeAnalysis; using System.Globalization; -using System.Security.Claims; using Microsoft.Data.SqlClient; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; using Purview.EventSourcing.Aggregates.Snapshotting; +using Purview.EventSourcing.Cryptography; +using Purview.EventSourcing.Exceptions; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.Internal; -using Purview.EventSourcing.SqlServer.Events.Exceptions; -using Purview.EventSourcing.Storage; using Purview.EventSourcing.Validation; +using Purview.Results; namespace Purview.EventSourcing.SqlServer.Events; @@ -18,14 +19,19 @@ partial class SqlServerEventStore { /// [DebuggerStepThrough] - public async Task> SaveAsync( + public async Task, AggregateSaveFailure>> SaveAsync( [NotNull] T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) { + var saveStopwatch = Stopwatch.StartNew(); var operation = await SaveCoreAsync(aggregate, operationContext, null, null, cancellationToken); await operation.AfterCommitAsync(cancellationToken); + + saveStopwatch.Stop(); + _metrics.RecordSave(saveStopwatch.Elapsed.TotalMilliseconds, _aggregateTypeShortName, operation.Result); + return operation.Result; } @@ -72,17 +78,15 @@ params EventRecord[] additionalEvents var validationResult = await GuardAsync(aggregate, cancellationToken); if (!validationResult.IsValid) - { - return new TransactionalSaveOperation( - SaveResultBuilder.Create(aggregate, false, false, validationResult) - ); - } + return Failed(AggregateSaveFailure.Failure>(new AggregateInvalid(validationResult))); if (aggregate.Details.Locked) { - return operationContext.LockMode is LockHandlingMode.ThrowsException - ? throw new AggregateLockedException(idempotencyId) - : new TransactionalSaveOperation(SaveResultBuilder.Create(aggregate, false, false)); + return Failed( + AggregateSaveFailure.Failure>( + new AggregateLocked(aggregate.AggregateType, aggregate.Id()) + ) + ); } if (string.IsNullOrWhiteSpace(aggregate.Details.Id)) @@ -100,7 +104,7 @@ params EventRecord[] additionalEvents ); activity?.Dispose(); - return new TransactionalSaveOperation(SaveResultBuilder.Create(aggregate, false, true)); + return Outcome(aggregate, SaveOutcomeKind.NoChanges); } var isNew = aggregate.IsNew(); @@ -132,7 +136,7 @@ params EventRecord[] additionalEvents { _eventStoreTelemetry.EventsAlreadyApplied(aggregate.Id(), idempotencyId); activity?.Dispose(); - return new TransactionalSaveOperation(SaveResultBuilder.Create(aggregate, true, true)); + return Outcome(aggregate, SaveOutcomeKind.AlreadyApplied); } } #pragma warning disable CA1031 @@ -143,7 +147,7 @@ params EventRecord[] additionalEvents } } - return await PersistAndNotifyAsync( + var persisted = await PersistAndNotifyAsync( aggregate, operationContext, idempotencyId, @@ -156,6 +160,12 @@ params EventRecord[] additionalEvents activity, cancellationToken ); + + // Only a write actually appended events; a no-op or an idempotent replay appended none. + if (persisted.Result.IsSuccess && persisted.Result.Value.Kind is SaveOutcomeKind.Written) + _metrics.EventsAppended(changeEvents.Length, _aggregateTypeShortName); + + return persisted; } [SuppressMessage( @@ -193,14 +203,15 @@ CancellationToken cancellationToken cancellationToken ); - if (streamEntity?.IsDeleted == true) + if (streamEntity?.IsDeleted == true && !changeEvents.Any(record => record.Event is Restored)) { - var throwIfDeleted = !changeEvents.Any(record => record.Event is Restored); - if (throwIfDeleted) - { - activity?.Dispose(); - throw new AggregateDeletedException(aggregate.Id(), idempotencyId); - } + activity?.Dispose(); + + return Failed( + AggregateSaveFailure.Failure>( + new AggregateDeleted(aggregate.AggregateType, aggregate.Id()) + ) + ); } try @@ -221,7 +232,7 @@ CancellationToken cancellationToken Timestamp = now, }; - var userId = ClaimsPrincipal.Current?.FindFirst(operationContext.ClaimIdentifier)?.Value; + var userId = _principalAccessor.GetPrincipal()?.FindFirst(operationContext.ClaimIdentifier)?.Value; if (operationContext.RequiresValidPrincipalIdentifier && string.IsNullOrWhiteSpace(userId)) throw new NullReferenceException( $"Missing ClaimsPrincipal identifier '{operationContext.ClaimIdentifier}'. Unable to save aggregate." @@ -239,7 +250,11 @@ CancellationToken cancellationToken CorrelationId = changeEvents[i].Metadata.CorrelationId ?? operationContext.CorrelationId, }; - var serializedEvent = SerializeEvent(changeEvent); + var serializedEvent = await ProtectIfRequiredAsync( + changeEvent, + SerializeEvent(changeEvent), + cancellationToken + ); insertRows.Add( new SqlServerEventStoreClient.RowData { @@ -298,10 +313,8 @@ await SubmitBatchOperationsAsync( if (shouldSnapshot && !requireSnapshotWrite) await CreateSnapshotBestEffortAsync(aggregate, connection, transaction, cancellationToken); - var result = SaveResultBuilder.Create(aggregate, true, false); - return new TransactionalSaveOperation( - result, + new SaveOutcome(aggregate, SaveOutcomeKind.Written), async afterCommitCancellationToken => { try @@ -366,10 +379,21 @@ await _aggregateChangeNotifier.AfterSaveAsync( await HandleSaveFailureAsync(aggregate, operationContext, changeEvents, ex); + if (ex is ConcurrencyException conflict) + return Failed(AggregateSaveFailure.Failure>(ToConcurrencyConflict(aggregate, conflict))); + throw; } } + static ConcurrencyConflict ToConcurrencyConflict(T aggregate, ConcurrencyException exception) => + new(aggregate.AggregateType, aggregate.Id(), exception.VersionAttempted, exception.Version); + + static TransactionalSaveOperation Failed(Result, AggregateSaveFailure> failure) => new(failure); + + static TransactionalSaveOperation Outcome(T aggregate, SaveOutcomeKind kind) => + new(new SaveOutcome(aggregate, kind)); + async Task HandleSaveFailureAsync( T aggregate, EventStoreOperationContext operationContext, @@ -393,8 +417,15 @@ async Task GuardAsync(T aggregate, CancellationToken cancellat : await _validator.ValidateAsync(aggregate, cancellationToken); } - static bool ShouldSnapShot(T aggregate, EventRecord[] events, EventStoreOperationContext context) + bool ShouldSnapShot(T aggregate, EventRecord[] events, EventStoreOperationContext context) { + // A snapshot serializes aggregate state, which holds the same personal data as the protected + // events in clear - and one snapshot can span many subjects, so no single key can protect it. + // With protection enabled the store does not snapshot at all: a snapshot surviving key erasure + // would make crypto-shredding untrue. Replay from events stays correct, only slower. + if (_payloadProtector is not null) + return false; + // Deleted/restored transitions must always be reflected promptly. if (aggregate.Details.IsDeleted || events.Any(record => record.Event is Restored)) return true; @@ -464,8 +495,12 @@ await _client.UpsertWithBatchAsync( ); } } - catch (SqlException ex) + // Writes reach storage both directly and through Entity Framework, which wraps the provider + // exception. Unwrap it so a duplicate event-row key is classified identically on both paths. + catch (Exception outer) when (outer is SqlException || outer.InnerException is SqlException) { + var ex = outer as SqlException ?? (SqlException)outer.InnerException!; + _eventStoreTelemetry.SaveFailedAtStorage(aggregate.Id(), _aggregateTypeFullName, ex); ClearCacheFireAndForget(aggregate); @@ -647,4 +682,17 @@ connection as SqlConnection static SqlTransaction GetSqlTransaction(DbTransaction transaction) => transaction as SqlTransaction ?? throw new InvalidOperationException("SQL Server transactions require a SqlTransaction."); + + /// + /// Encrypts a serialized payload when its event names a data subject. + /// + /// + /// Applied after serialization so the stored payload is the envelope, which keeps the persistence + /// schema unchanged. An event with no data subject, or a store with no protector configured, is + /// stored as before. + /// + Task ProtectIfRequiredAsync(object changeEvent, string serialized, CancellationToken cancellationToken) => + _payloadProtector is not null && changeEvent is IEventDataSubject dataSubject + ? _payloadProtector.ProtectAsync(serialized, dataSubject.DataSubjectId, cancellationToken) + : Task.FromResult(serialized); } diff --git a/src/src/SqlServer/Events/SqlServerEventStore.cs b/src/src/SqlServer/Events/SqlServerEventStore.cs index 2fd6a48c..b775d66f 100644 --- a/src/src/SqlServer/Events/SqlServerEventStore.cs +++ b/src/src/SqlServer/Events/SqlServerEventStore.cs @@ -7,8 +7,10 @@ using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events.Upcasting; using Purview.EventSourcing.Aggregates.Snapshotting; +using Purview.EventSourcing.Cryptography; using Purview.EventSourcing.Internal; using Purview.EventSourcing.Services; +using Purview.EventSourcing.Tenancy; using Purview.EventSourcing.Validation; namespace Purview.EventSourcing.SqlServer.Events; @@ -50,6 +52,14 @@ public sealed partial class SqlServerEventStore : ISqlServerEventStore, IT readonly IAggregateRequirementsManager _aggregateRequirementsManager; readonly IEventUpcasterRegistry? _eventUpcasterRegistry; + readonly IEventStorePrincipalAccessor _principalAccessor; + + readonly IEventStoreMetrics _metrics; + + readonly ICurrentTenant _currentTenant; + + readonly IEventPayloadProtector? _payloadProtector; + readonly string _aggregateTypeFullName; readonly string _aggregateTypeShortName; readonly string _cacheKeyPrefix; @@ -74,6 +84,10 @@ public sealed partial class SqlServerEventStore : ISqlServerEventStore, IT /// Optional validator invoked before persisting aggregates. /// Optional factory used to generate aggregate ids when none is supplied. /// Optional registry used to upcast events during reconstitution. + /// Optional accessor supplying the principal recorded against saved events. + /// Optional metrics recorder; defaults to a no-op. + /// Optional tenant resolver; defaults to the system scope, which applies no filter. + /// Optional payload protector; when omitted payloads are stored unencrypted. /// /// Any of , , , /// , , or @@ -88,7 +102,11 @@ public SqlServerEventStore( IAggregateRequirementsManager aggregateRequirementsManager, IAggregateValidator? validator = null, IAggregateIdFactory? aggregateIdFactory = null, - IEventUpcasterRegistry? eventUpcasterRegistry = null + IEventUpcasterRegistry? eventUpcasterRegistry = null, + IEventStorePrincipalAccessor? principalAccessor = null, + IEventStoreMetrics? metrics = null, + ICurrentTenant? currentTenant = null, + IEventPayloadProtector? payloadProtector = null ) { _eventNameMapper = eventNameMapper; @@ -100,6 +118,10 @@ public SqlServerEventStore( _aggregateChangeNotifier = aggregateChangeNotifier; _aggregateRequirementsManager = aggregateRequirementsManager; _eventUpcasterRegistry = eventUpcasterRegistry; + _principalAccessor = principalAccessor ?? new AmbientEventStorePrincipalAccessor(); + _metrics = metrics ?? NoOpEventStoreMetrics.Instance; + _currentTenant = currentTenant ?? new SystemCurrentTenant(); + _payloadProtector = payloadProtector; _aggregateTypeShortName = typeof(T).Name; _aggregateTypeFullName = typeof(T).FullName ?? _aggregateTypeShortName; @@ -114,7 +136,7 @@ public SqlServerEventStore( _snapshotIdPrefix = $"snap_{_aggregateTypeShortName}_"; var clientOptions = ResolveClientOptions(sqlServerOptions.Value, _aggregateTypeShortName); - _client = new SqlServerEventStoreClient(clientOptions); + _client = new SqlServerEventStoreClient(clientOptions, _currentTenant); } /// @@ -252,26 +274,12 @@ CancellationToken cancellationToken return result; } - [SuppressMessage("Style", "IDE0010:Add missing cases")] - static bool ReturnAggregate(bool isDeleted, string aggregateId, EventStoreOperationContext context) - { - if (isDeleted) - { - switch (context.DeleteMode) - { - case DeleteHandlingMode.ThrowsException: - throw AggregateIsDeletedException(aggregateId); - case DeleteHandlingMode.ReturnsNull: - return false; - } - } - - return true; - } + static bool ReturnAggregate(bool isDeleted, EventStoreOperationContext context) => + !isDeleted || context.DeleteMode == DeleteHandlingMode.ReturnsAggregate; string CreateStreamVersionId(string aggregateId) => $"s_{_aggregateTypeShortName}_{aggregateId}"; - string CreateEventId(string aggregateId, int version) + string CreateEventId(string aggregateId, long version) { var versionText = version.ToString(CultureInfo.InvariantCulture); var padLength = Math.Max(0, _eventStoreOptions.Value.EventSuffixLength - versionText.Length); @@ -303,7 +311,19 @@ string CreateIdempotencyCheckId(string aggregateId, string idempotencyId) => /// /// The id of the aggregate. /// The cache key, derived from the aggregate type's short name and id. - public string CreateCacheKey(string aggregateId) => $"{_cacheKeyPrefix}{aggregateId}".ToUpperInvariant(); + public string CreateCacheKey(string aggregateId) => + $"{TenantCacheScope()}{_cacheKeyPrefix}{aggregateId}".ToUpperInvariant(); + + /// + /// Namespaces a cache key by tenant. + /// + /// + /// The distributed cache is read before the tenant-filtered storage lookup, so an unqualified key + /// would let one tenant read another's cached aggregate straight out of a shared cache, bypassing + /// every storage filter. The system scope keeps the unqualified key, matching unowned rows. + /// + /// The tenant prefix, or an empty string under the system scope. + string TenantCacheScope() => _currentTenant.Current.IsSystem ? string.Empty : $"{_currentTenant.Current.TenantId}:"; //async Task EnsureConfiguredAsync(CancellationToken cancellationToken) //{ @@ -342,7 +362,7 @@ internal sealed class StreamVersionData public string Id { get; set; } = default!; public string AggregateId { get; set; } = default!; public string AggregateType { get; set; } = default!; - public int Version { get; set; } + public long Version { get; set; } public bool IsDeleted { get; set; } } } diff --git a/src/src/SqlServer/Events/SqlServerEventStoreClient.cs b/src/src/SqlServer/Events/SqlServerEventStoreClient.cs index 8c39affd..57aa5b75 100644 --- a/src/src/SqlServer/Events/SqlServerEventStoreClient.cs +++ b/src/src/SqlServer/Events/SqlServerEventStoreClient.cs @@ -5,6 +5,7 @@ using Microsoft.EntityFrameworkCore.Infrastructure; using Microsoft.EntityFrameworkCore.Storage; using Purview.EventSourcing.SqlServer.Events.EntityFramework; +using Purview.EventSourcing.Tenancy; namespace Purview.EventSourcing.SqlServer.Events; @@ -33,10 +34,12 @@ sealed partial class SqlServerEventStoreClient readonly SqlServerEventStoreOptions _options; readonly string _tableEnsureKey; readonly DbContextOptions _connectionStringOptions; + readonly ICurrentTenant _currentTenant; - public SqlServerEventStoreClient(SqlServerEventStoreOptions options) + public SqlServerEventStoreClient(SqlServerEventStoreOptions options, ICurrentTenant? currentTenant = null) { _options = options ?? throw new ArgumentNullException(nameof(options)); + _currentTenant = currentTenant ?? new SystemCurrentTenant(); ValidateIdentifier(_options.SchemaName); ValidateIdentifier(_options.TableName); SqlServerJsonIndexSchemaManager.ValidateOrThrow( @@ -72,7 +75,7 @@ public async Task InsertAsync( int entityType, string aggregateId, string aggregateType, - int version, + long version, bool isDeleted, string? payload, string? eventType, @@ -100,7 +103,7 @@ public async Task InsertAsync( int entityType, string aggregateId, string aggregateType, - int version, + long version, bool isDeleted, string? payload, string? eventType, @@ -143,7 +146,7 @@ public async Task UpsertAsync( int entityType, string aggregateId, string aggregateType, - int version, + long version, bool isDeleted, string? payload, string? eventType, @@ -171,7 +174,7 @@ public async Task UpsertAsync( int entityType, string aggregateId, string aggregateType, - int version, + long version, bool isDeleted, string? payload, string? eventType, @@ -205,7 +208,7 @@ public async Task UpsertAsync( int entityType, string aggregateId, string aggregateType, - int version, + long version, bool isDeleted, string? payload, string? eventType, @@ -237,7 +240,7 @@ public async Task UpsertAsync( int entityType, string aggregateId, string aggregateType, - int version, + long version, bool isDeleted, string? payload, string? eventType, @@ -280,7 +283,7 @@ public async Task UpsertWithBatchAsync( int entityType, string aggregateId, string aggregateType, - int version, + long version, bool isDeleted, string? payload, string? eventType, @@ -337,7 +340,7 @@ public async Task UpsertWithBatchAsync( int entityType, string aggregateId, string aggregateType, - int version, + long version, bool isDeleted, string? payload, string? eventType, @@ -386,7 +389,7 @@ await UpsertSnapshotInBatchAsync( await context.SaveChangesAsync(cancellationToken); } - static async Task UpsertSnapshotInBatchAsync( + async Task UpsertSnapshotInBatchAsync( EventStoreDbContext context, RowData snapshotRow, bool snapshotIsNew, @@ -511,8 +514,8 @@ public async Task DeleteByAggregateIdAsync( public async IAsyncEnumerable GetEventRangeAsync( string aggregateId, string aggregateType, - int versionFrom, - int versionTo, + long versionFrom, + long versionTo, [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default ) { @@ -675,26 +678,32 @@ await SqlServerJsonIndexSchemaManager.ApplyAsync( } } - EventStoreDbContext CreateContext() => new(_connectionStringOptions, _options.SchemaName, _options.TableName); + EventStoreDbContext CreateContext() => + new(_connectionStringOptions, _options.SchemaName, _options.TableName, _currentTenant); EventStoreDbContext CreateContext(SqlConnection connection, SqlTransaction? transaction) { DbContextOptionsBuilder optionsBuilder = new(); var commandTimeout = Math.Max(1, _options.TimeoutInSeconds ?? 60); optionsBuilder.UseSqlServer(connection, sql => sql.CommandTimeout(commandTimeout)); - EventStoreDbContext context = new(optionsBuilder.Options, _options.SchemaName, _options.TableName); + EventStoreDbContext context = new( + optionsBuilder.Options, + _options.SchemaName, + _options.TableName, + _currentTenant + ); if (transaction is not null) context.Database.UseTransaction(transaction); return context; } - static async Task UpsertCoreAsync( + async Task UpsertCoreAsync( EventStoreDbContext context, string id, int entityType, string aggregateId, string aggregateType, - int version, + long version, bool isDeleted, string? payload, string? eventType, @@ -738,18 +747,19 @@ static async Task UpsertCoreAsync( entity.EventType = eventType; entity.IdempotencyId = idempotencyId; entity.SchemaVersion = schemaVersion; + entity.TenantId = _currentTenant.Current.TenantId; entity.Timestamp = timestamp; } await context.SaveChangesAsync(cancellationToken); } - static EventStoreEntity CreateEntity( + EventStoreEntity CreateEntity( string id, int entityType, string aggregateId, string aggregateType, - int version, + long version, bool isDeleted, string? payload, string? eventType, @@ -769,10 +779,13 @@ static EventStoreEntity CreateEntity( EventType = eventType, IdempotencyId = idempotencyId, SchemaVersion = schemaVersion, + TenantId = _currentTenant.Current.TenantId, Timestamp = timestamp, }; - static EventStoreEntity ToEntity(RowData row) => + // Instance, not static: the tenant is stamped here rather than at each call site, so a new write + // path cannot forget it. The query filter would then hide the row from its own tenant. + EventStoreEntity ToEntity(RowData row) => new() { Id = row.Id, @@ -788,6 +801,7 @@ static EventStoreEntity ToEntity(RowData row) => CorrelationId = row.CorrelationId, CausationId = row.CausationId, UserId = row.UserId, + TenantId = _currentTenant.Current.TenantId, Timestamp = row.Timestamp, }; @@ -854,7 +868,7 @@ public RowData() { } public int EntityType { get; init; } public string AggregateId { get; init; } = default!; public string AggregateType { get; init; } = default!; - public int Version { get; init; } + public long Version { get; init; } public bool IsDeleted { get; init; } public string? Payload { get; init; } public string? EventType { get; init; } diff --git a/src/src/SqlServer/Events/SqlServerEventStoreTransaction.cs b/src/src/SqlServer/Events/SqlServerEventStoreTransaction.cs index 0ba3fb73..369a267e 100644 --- a/src/src/SqlServer/Events/SqlServerEventStoreTransaction.cs +++ b/src/src/SqlServer/Events/SqlServerEventStoreTransaction.cs @@ -417,8 +417,8 @@ sealed class ProcessedSaveOperation(T aggregate, TransactionalSaveOperation aggregate; - public bool Saved => operation.Result.Saved; - public bool Skipped => operation.Result.Skipped; + public bool Saved => operation.Saved; + public bool Skipped => operation.Skipped; public Task AfterCommitAsync(CancellationToken cancellationToken) => operation.AfterCommitAsync(cancellationToken); diff --git a/src/src/SqlServer/Outbox/SqlServerOutboxStore.cs b/src/src/SqlServer/Outbox/SqlServerOutboxStore.cs index 700404b6..ef41bbfd 100644 --- a/src/src/SqlServer/Outbox/SqlServerOutboxStore.cs +++ b/src/src/SqlServer/Outbox/SqlServerOutboxStore.cs @@ -73,6 +73,8 @@ await ExecuteWithConnectionAsync( { await EnsureSchemaAsync(token); + // Without READPAST a concurrent claim blocks on the same rows, then re-applies the + // outer UPDATE once the first commits - handing both dispatchers the same batch. await using SqlCommand command = new( $""" UPDATE {_schema}.{_table} @@ -82,7 +84,7 @@ await ExecuteWithConnectionAsync( INSERTED.[State], INSERTED.[AttemptCount], INSERTED.[NextAttemptUtc], INSERTED.[DispatchedUtc], INSERTED.[LeaseExpiresUtc], INSERTED.[LastError] WHERE [Id] IN ( - SELECT TOP (@batch) [Id] FROM {_schema}.{_table} + SELECT TOP (@batch) [Id] FROM {_schema}.{_table} WITH (UPDLOCK, READPAST, ROWLOCK) WHERE ([State] = 0 OR [State] = 2) AND ([LeaseExpiresUtc] IS NULL OR [LeaseExpiresUtc] < @now) AND ([NextAttemptUtc] IS NULL OR [NextAttemptUtc] <= @now) diff --git a/src/src/SqlServer/Sdk/README.md b/src/src/SqlServer/Sdk/README.md index 3fa6cf42..2524b986 100644 --- a/src/src/SqlServer/Sdk/README.md +++ b/src/src/SqlServer/Sdk/README.md @@ -60,5 +60,5 @@ The snapshot query model writes members through their property accessors (`Prope - [Homepage](https://purview.dev/projects/event-sourcing/) - [Documentation](https://purview.dev/docs/event-sourcing/) - [SQL Server guide](https://github.com/purview-dev/event-sourcing/blob/main/docs/wiki/SQL-Server-Guide.md) - - Includes behavior notes/caveats (`IsDeletedAsync` missing behavior, tolerant replay, principal requirements) + - Includes behavior notes/caveats (`ExistsAsync` missing-stream behavior, tolerant replay, principal requirements) - Includes snapshot payload/query-translation guidance for scalar value objects vs directly mapped complex mirrors diff --git a/src/src/SqlServer/Snapshots/SqlServerSnapshotEventStore.EventStore.cs b/src/src/SqlServer/Snapshots/SqlServerSnapshotEventStore.EventStore.cs index 476019f7..77e31bbf 100644 --- a/src/src/SqlServer/Snapshots/SqlServerSnapshotEventStore.EventStore.cs +++ b/src/src/SqlServer/Snapshots/SqlServerSnapshotEventStore.EventStore.cs @@ -2,7 +2,9 @@ using Microsoft.Data.SqlClient; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Snapshotting; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.Internal; +using Purview.Results; namespace Purview.EventSourcing.SqlServer.Snapshot; @@ -13,29 +15,29 @@ public Task CreateAsync(string? aggregateId = null, CancellationToken cancell _eventStore.CreateAsync(aggregateId, cancellationToken); /// - public Task GetOrCreateAsync( + public Task> GetOrCreateAsync( string? aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => _eventStore.GetOrCreateAsync(aggregateId, operationContext, cancellationToken); /// - public Task GetAsync( + public Task> GetAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => _eventStore.GetAsync(aggregateId, operationContext, cancellationToken); /// - public Task GetAtAsync( + public Task> GetAtAsync( string aggregateId, - int version, + long version, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => _eventStore.GetAtAsync(aggregateId, version, operationContext, cancellationToken); /// - public async Task> SaveAsync( + public async Task, AggregateSaveFailure>> SaveAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -46,8 +48,8 @@ public async Task> SaveAsync( var result = await _eventStore.SaveAsync(aggregate, operationContext, cancellationToken); if ( - result - && !result.Skipped + result.IsSuccess + && result.Value.Written && SnapshotStrategyResolver.ShouldSnapshot( aggregate, eventsApplied, @@ -110,8 +112,8 @@ CancellationToken cancellationToken try { if ( - innerOperation.Result.Saved - && !innerOperation.Result.Skipped + innerOperation.Saved + && !innerOperation.Skipped && SnapshotStrategyResolver.ShouldSnapshot( aggregate, eventsApplied, @@ -163,15 +165,13 @@ CancellationToken cancellationToken } /// - public Task IsDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) => - _eventStore.IsDeletedAsync(aggregateId, cancellationToken); - - /// - public Task GetDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) => - _eventStore.GetDeletedAsync(aggregateId, cancellationToken); + public Task> GetDeletedAsync( + string aggregateId, + CancellationToken cancellationToken = default + ) => _eventStore.GetDeletedAsync(aggregateId, cancellationToken); /// - public async Task DeleteAsync( + public async Task, AggregateDeleteFailure>> DeleteAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -185,7 +185,7 @@ public async Task DeleteAsync( try { var result = await _eventStore.DeleteAsync(aggregate, operationContext, cancellationToken); - if (result) + if (result.IsSuccess) { await _sqlServerClient.DeleteAsync(aggregate.Details.Id, cancellationToken); _telemetry.SnapshotDeleteComplete(aggregate.Details.Id, _aggregateName); @@ -201,7 +201,7 @@ public async Task DeleteAsync( } /// - public async Task RestoreAsync( + public async Task, AggregateRestoreFailure>> RestoreAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -210,7 +210,7 @@ public async Task RestoreAsync( ArgumentNullException.ThrowIfNull(aggregate, nameof(aggregate)); var result = await _eventStore.RestoreAsync(aggregate, operationContext, cancellationToken); - if (result) + if (result.IsSuccess) await SnapshotAsync(aggregate, cancellationToken); return result; @@ -223,7 +223,7 @@ public IAsyncEnumerable GetAggregateIdsAsync( ) => _eventStore.GetAggregateIdsAsync(includeDeleted, cancellationToken); /// - public Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) => + public Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) => _eventStore.ExistsAsync(aggregateId, cancellationToken); /// @@ -232,8 +232,8 @@ public Task ExistsAsync(string aggregateId, CancellationToken cance /// public IAsyncEnumerable<(EventRecord EventRecord, string EventType)> GetEventRangeAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, CancellationToken cancellationToken ) => _eventStore.GetEventRangeAsync(aggregateId, versionFrom, versionTo, cancellationToken); diff --git a/src/src/SqlServer/Snapshots/SqlServerSnapshotEventStore.cs b/src/src/SqlServer/Snapshots/SqlServerSnapshotEventStore.cs index fcca2797..b9b4fc96 100644 --- a/src/src/SqlServer/Snapshots/SqlServerSnapshotEventStore.cs +++ b/src/src/SqlServer/Snapshots/SqlServerSnapshotEventStore.cs @@ -1,9 +1,10 @@ -using Microsoft.Extensions.Options; +using Microsoft.Extensions.Options; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Snapshotting; using Purview.EventSourcing.Internal; using Purview.EventSourcing.SqlServer.Client; using Purview.EventSourcing.SqlServer.Snapshots; +using Purview.EventSourcing.Tenancy; namespace Purview.EventSourcing.SqlServer.Snapshot; @@ -42,6 +43,7 @@ public sealed partial class SqlServerSnapshotEventStore /// The telemetry contract used to emit activities, metrics, and logs. /// Optional strategy that decides when an aggregate should be snapshotted; defaults to . /// Optional selector used to resolve a snapshot strategy for a given aggregate. + /// Optional tenant scope applied to snapshot reads and writes. /// /// , , or is . /// @@ -51,7 +53,8 @@ public SqlServerSnapshotEventStore( IOptions sqlServerEventStoreOptions, ISqlServerSnapshotEventStoreTelemetry telemetry, ISnapshotStrategy? snapshotStrategy = null, - ISnapshotStrategySelector? snapshotStrategySelector = null + ISnapshotStrategySelector? snapshotStrategySelector = null, + ICurrentTenant? currentTenant = null ) { _eventStore = eventStore; @@ -63,7 +66,7 @@ public SqlServerSnapshotEventStore( _aggregateName = TypeNameHelper.GetName(_aggregateType, "Aggregate"); var clientOptions = ResolveClientOptions(_sqlServerEventStoreOptions.Value, _aggregateName); - _sqlServerClient = new(clientOptions); + _sqlServerClient = new(clientOptions, currentTenant); } /// diff --git a/src/src/SqlServer/SqlServer.csproj b/src/src/SqlServer/SqlServer.csproj index af9bdbe7..7d194b66 100644 --- a/src/src/SqlServer/SqlServer.csproj +++ b/src/src/SqlServer/SqlServer.csproj @@ -1,4 +1,4 @@ - + true Purview Event Store for Azure SQL and SQL Server @@ -14,19 +14,19 @@ all runtime; build; native; contentfiles; analyzers; buildtransitive - - + diff --git a/src/src/SqlServer/SqlServerJsonIndexSchemaManager.cs b/src/src/SqlServer/SqlServerJsonIndexSchemaManager.cs index 6f4ff1a5..c7fc7e0f 100644 --- a/src/src/SqlServer/SqlServerJsonIndexSchemaManager.cs +++ b/src/src/SqlServer/SqlServerJsonIndexSchemaManager.cs @@ -188,7 +188,7 @@ List errors ) { var jsonPath = definition.JsonPath?.Trim(); - if (string.IsNullOrWhiteSpace(jsonPath) || !jsonPath.StartsWith('$')) + if (string.IsNullOrWhiteSpace(jsonPath) || !jsonPath.StartsWith('$', StringComparison.Ordinal)) errors.Add($"{optionsName}.Indexes[{i}].JsonPath must start with '$'."); return jsonPath; diff --git a/src/src/Validation.FluentValidation/Sdk/README.md b/src/src/Validation.FluentValidation/Sdk/README.md index 2bb4462f..16fec87e 100644 --- a/src/src/Validation.FluentValidation/Sdk/README.md +++ b/src/src/Validation.FluentValidation/Sdk/README.md @@ -32,7 +32,10 @@ Both overloads accept an optional `ServiceLifetime` (defaults to `Singleton`). ```csharp // The store invokes the registered IAggregateValidator before saving. -await store.SaveAsync(order, cancellationToken); +var result = await store.SaveAsync(order, cancellationToken); +if (result.IsFailure && result.Error is AggregateInvalid invalid) + foreach (var failure in invalid.ValidationResult.Failures) + Console.WriteLine($"{failure.PropertyName}: {failure.ErrorMessage}"); ``` ## What it provides diff --git a/src/src/Validation.ZodSharp/Sdk/README.md b/src/src/Validation.ZodSharp/Sdk/README.md index 45ca5ad8..af8c4957 100644 --- a/src/src/Validation.ZodSharp/Sdk/README.md +++ b/src/src/Validation.ZodSharp/Sdk/README.md @@ -45,7 +45,10 @@ See `docs/wiki/Dependency-Guardrails.md` for the full rationale. ```csharp // The store invokes the registered IAggregateValidator before saving. -await store.SaveAsync(order, cancellationToken); +var result = await store.SaveAsync(order, cancellationToken); +if (result.IsFailure && result.Error is AggregateInvalid invalid) + foreach (var failure in invalid.ValidationResult.Failures) + Console.WriteLine($"{failure.PropertyName}: {failure.ErrorMessage}"); ``` ## What it provides diff --git a/src/tests/Admin.UnitTests/Api/AdminApiEndpointTests.cs b/src/tests/Admin.UnitTests/Api/AdminApiEndpointTests.cs index a1ce7935..63eb5d89 100644 --- a/src/tests/Admin.UnitTests/Api/AdminApiEndpointTests.cs +++ b/src/tests/Admin.UnitTests/Api/AdminApiEndpointTests.cs @@ -1,3 +1,7 @@ +using System.Net; +using System.Security.Claims; +using System.Text.Encodings.Web; +using System.Text.Json; using Microsoft.AspNetCore.Authentication; using Microsoft.AspNetCore.Authorization; using Microsoft.AspNetCore.Builder; @@ -9,14 +13,11 @@ using Microsoft.Extensions.Hosting; using Microsoft.Extensions.Logging; using Microsoft.Extensions.Options; +using Purview.EventSourcing.Admin.Failures; using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Queries; using Purview.EventSourcing.Admin.Services; -using System.Net; -using System.Net.Http.Json; -using System.Security.Claims; -using System.Text.Encodings.Web; -using System.Text.Json; +using Purview.Results; namespace Purview.EventSourcing.Admin.API; @@ -529,12 +530,12 @@ CancellationToken cancellationToken return Task.FromResult(new PagedResult([item], query.Page, query.PageSize, 1)); } - public Task GetAsync( + public Task> GetAsync( string aggregateType, string aggregateId, CancellationToken cancellationToken ) => - Task.FromResult( + Task.FromResult>( new AggregateSummaryResponse( aggregateType, aggregateId, @@ -549,7 +550,7 @@ CancellationToken cancellationToken sealed class RecordingEventQueryService : IAdminEventQueryService { - public Task?> GetRangeAsync( + public Task, AdminQueryFailure>> GetRangeAsync( string aggregateType, string aggregateId, EventRangeQuery query, @@ -569,9 +570,13 @@ CancellationToken cancellationToken null, null ), - JsonSerializer.SerializeToElement(/*lang=json,strict*/ """{"customerId":"customer-1"}""") + // Deserialize, not SerializeToElement: the latter would turn this JSON text into a JSON + // string, where the contract carries the payload as raw JSON. + JsonSerializer.Deserialize( /*lang=json,strict*/ + """{"customerId":"customer-1"}""" + ) ); - return Task.FromResult?>( + return Task.FromResult, AdminQueryFailure>>( new PagedResult([envelope], query.Page, query.PageSize, 1) ); } @@ -579,15 +584,19 @@ CancellationToken cancellationToken sealed class RecordingProjectionService : IAdminProjectionService { - static readonly JsonElement ProjectedState = JsonSerializer.SerializeToElement(/*lang=json,strict*/ """{"event_1":{"eventType":"OrderCreatedEvent","version":1}}"""); + // Deserialize, not SerializeToElement: the latter would turn this JSON text into a JSON string, + // where the contract carries the projected state as raw JSON. + static readonly JsonElement ProjectedState = JsonSerializer.Deserialize( /*lang=json,strict*/ + """{"event_1":{"eventType":"OrderCreatedEvent","version":1}}""" + ); - public Task ProjectAtVersionAsync( + public Task> ProjectAtVersionAsync( string aggregateType, string aggregateId, long targetVersion, CancellationToken cancellationToken ) => - Task.FromResult( + Task.FromResult>( new ProjectionResponse( aggregateType, aggregateId, @@ -598,13 +607,13 @@ CancellationToken cancellationToken ) ); - public Task ProjectAtTimeAsync( + public Task> ProjectAtTimeAsync( string aggregateType, string aggregateId, DateTimeOffset targetUtc, CancellationToken cancellationToken ) => - Task.FromResult( + Task.FromResult>( new ProjectionResponse( aggregateType, aggregateId, diff --git a/src/tests/Admin.UnitTests/Api/AdminOperationalEndpointsTests.cs b/src/tests/Admin.UnitTests/Api/AdminOperationalEndpointsTests.cs index 1b7cb40d..06a66df1 100644 --- a/src/tests/Admin.UnitTests/Api/AdminOperationalEndpointsTests.cs +++ b/src/tests/Admin.UnitTests/Api/AdminOperationalEndpointsTests.cs @@ -1,4 +1,7 @@ +using System.Net; +using System.Text.Json; using Microsoft.Extensions.DependencyInjection; +using Purview.EventSourcing.Admin.Failures; using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Queries; using Purview.EventSourcing.Admin.Security; @@ -6,9 +9,7 @@ using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Outbox; using Purview.EventSourcing.Services; -using System.Net; -using System.Net.Http.Json; -using System.Text.Json; +using Purview.Results; namespace Purview.EventSourcing.Admin.API; @@ -44,7 +45,7 @@ public async Task Capabilities_WhenFeatureDisabled_ReturnsNotFound(CancellationT } [Test] - public async Task Health_WhenFeatureEnabled_ReturnsReadinessSummary(CancellationToken cancellationToken) + public async Task Health_WhenNoStorageProbeRegistered_ReportsUnknown(CancellationToken cancellationToken) { await using var host = await AdminTestHost.CreateAsync(configureAdmin: static options => options.Features.ViewCapabilities = true @@ -56,10 +57,57 @@ public async Task Health_WhenFeatureEnabled_ReturnsReadinessSummary(Cancellation await Assert.That(response.StatusCode).IsEqualTo(HttpStatusCode.OK); var json = await response.Content.ReadFromJsonAsync(cancellationToken: cancellationToken); var root = json!.RootElement; - await Assert.That(root.GetProperty("status").GetString()).IsEqualTo("Ready"); + await Assert.That(root.GetProperty("status").GetString()).IsEqualTo("Unknown"); await Assert.That(root.GetProperty("supportsTransactionalOutbox").GetBoolean()).IsFalse(); } + sealed class StubStorageProbe(Func probe) : IAdminStorageProbe + { + public Task IsReachableAsync(CancellationToken cancellationToken) => Task.FromResult(probe()); + } + + static async Task GetHealthStatusAsync(Func probe, CancellationToken cancellationToken) + { + await using var host = await AdminTestHost.CreateAsync( + configureAdmin: static options => options.Features.ViewCapabilities = true, + configureServices: services => services.AddSingleton(new StubStorageProbe(probe)) + ); + + var response = await host.Client.GetAsync("/admin/api/health", cancellationToken); + var json = await response.Content.ReadFromJsonAsync(cancellationToken: cancellationToken); + + return json!.RootElement.GetProperty("status").GetString(); + } + + [Test] + public async Task Health_WhenStorageProbeSucceeds_ReportsHealthy(CancellationToken cancellationToken) + { + var status = await GetHealthStatusAsync(static () => true, cancellationToken); + + await Assert.That(status).IsEqualTo("Healthy"); + } + + [Test] + public async Task Health_WhenStorageProbeReportsUnreachable_ReportsUnhealthy(CancellationToken cancellationToken) + { + var status = await GetHealthStatusAsync(static () => false, cancellationToken); + + await Assert.That(status).IsEqualTo("Unhealthy"); + } + + // A probe that throws is the realistic failure: storage is down, so the driver raises rather than + // returning. The endpoint must still answer, and must answer Unhealthy. + [Test] + public async Task Health_WhenStorageProbeThrows_ReportsUnhealthy(CancellationToken cancellationToken) + { + var status = await GetHealthStatusAsync( + static () => throw new InvalidOperationException("storage unavailable"), + cancellationToken + ); + + await Assert.That(status).IsEqualTo("Unhealthy"); + } + [Test] public async Task Capabilities_GivenDeniedPermission_ReturnsForbidden(CancellationToken cancellationToken) { @@ -350,7 +398,7 @@ public string InitializeAggregate() sealed class PagingEventQueryService : IAdminEventQueryService { - public Task?> GetRangeAsync( + public Task, AdminQueryFailure>> GetRangeAsync( string aggregateType, string aggregateId, EventRangeQuery query, @@ -381,12 +429,14 @@ CancellationToken cancellationToken null, null ), - JsonSerializer.SerializeToElement(/*lang=json,strict*/ """{}""") + JsonSerializer.SerializeToElement( /*lang=json,strict*/ + """{}""" + ) ) ); } - return Task.FromResult?>( + return Task.FromResult, AdminQueryFailure>>( new PagedResult(items, page, pageSize, total) ); } diff --git a/src/tests/Admin.UnitTests/Api/AdminSnapshotEndpointsTests.cs b/src/tests/Admin.UnitTests/Api/AdminSnapshotEndpointsTests.cs index 26f73754..87a02c89 100644 --- a/src/tests/Admin.UnitTests/Api/AdminSnapshotEndpointsTests.cs +++ b/src/tests/Admin.UnitTests/Api/AdminSnapshotEndpointsTests.cs @@ -1,11 +1,12 @@ using System.Linq.Expressions; using System.Net; -using System.Net.Http.Json; using System.Text.Json; using Microsoft.Extensions.DependencyInjection; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Persistence; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.Services; +using Purview.Results; namespace Purview.EventSourcing.Admin.API; @@ -153,12 +154,15 @@ sealed class StubQueryableEventStore : IQueryableEventStore public int SaveCount { get; private set; } - public Task GetAsync( + public Task> GetAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) - where T : class, IAggregate, new() => Task.FromResult(Snapshot as T); + where T : class, IAggregate, new() => + Task.FromResult>( + Snapshot as T ?? AggregateReadFailure.Failure(new AggregateNotFound(typeof(T).Name, aggregateId)) + ); public Task FirstOrDefaultAsync( Expression> whereClause, @@ -167,7 +171,7 @@ sealed class StubQueryableEventStore : IQueryableEventStore ) where T : class, IAggregate, new() => Task.FromResult(Snapshot as T); - public Task> SaveAsync( + public Task, AggregateSaveFailure>> SaveAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -175,43 +179,43 @@ public Task> SaveAsync( where T : class, IAggregate, new() { SaveCount++; - return Task.FromResult( - new SaveResult(aggregate, Validation.ValidationResult.Success, saved: true, skipped: false) + return Task.FromResult, AggregateSaveFailure>>( + new SaveOutcome(aggregate, SaveOutcomeKind.Written) ); } public Task CreateAsync(string? aggregateId = null, CancellationToken cancellationToken = default) where T : class, IAggregate, new() => throw new NotSupportedException(); - public Task GetOrCreateAsync( + public Task> GetOrCreateAsync( string? aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) where T : class, IAggregate, new() => throw new NotSupportedException(); - public Task GetAtAsync( + public Task> GetAtAsync( string aggregateId, - int version, + long version, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) where T : class, IAggregate, new() => throw new NotSupportedException(); - public Task GetDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) - where T : class, IAggregate, new() => throw new NotSupportedException(); - - public Task IsDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) + public Task> GetDeletedAsync( + string aggregateId, + CancellationToken cancellationToken = default + ) where T : class, IAggregate, new() => throw new NotSupportedException(); - public Task DeleteAsync( + public Task, AggregateDeleteFailure>> DeleteAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) where T : class, IAggregate, new() => throw new NotSupportedException(); - public Task RestoreAsync( + public Task, AggregateRestoreFailure>> RestoreAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -224,7 +228,10 @@ public IAsyncEnumerable GetAggregateIdsAsync( ) where T : class, IAggregate, new() => throw new NotSupportedException(); - public Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) + public Task ExistsAsync( + string aggregateId, + CancellationToken cancellationToken = default + ) where T : class, IAggregate, new() => throw new NotSupportedException(); public T FulfilRequirements(T aggregate) @@ -232,8 +239,8 @@ public T FulfilRequirements(T aggregate) public IAsyncEnumerable<(EventRecord EventRecord, string EventType)> GetEventRangeAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, CancellationToken cancellationToken ) where T : class, IAggregate, new() => throw new NotSupportedException(); diff --git a/src/tests/Admin.UnitTests/Api/AdminTenantScopeFilterTests.cs b/src/tests/Admin.UnitTests/Api/AdminTenantScopeFilterTests.cs new file mode 100644 index 00000000..525dced1 --- /dev/null +++ b/src/tests/Admin.UnitTests/Api/AdminTenantScopeFilterTests.cs @@ -0,0 +1,110 @@ +using System.Net; +using System.Security.Claims; +using Microsoft.Extensions.DependencyInjection; +using Purview.EventSourcing.Admin.Failures; +using Purview.EventSourcing.Admin.Services; +using Purview.Results; + +namespace Purview.EventSourcing.Admin.API; + +/// +/// Guards that tenant scoping is enforced for the whole admin group, and only when asked for. +/// +public sealed class AdminTenantScopeFilterTests +{ + sealed class StubResolver(Result result) : IAdminTenantResolver + { + public string? ObservedRequestedTenant { get; private set; } + + public Task> ResolveAsync( + ClaimsPrincipal user, + string? requestedTenantId, + CancellationToken cancellationToken + ) + { + ObservedRequestedTenant = requestedTenantId; + return Task.FromResult(result); + } + } + + static async Task<(HttpStatusCode Status, StubResolver Resolver)> CallHealthAsync( + Result resolution, + bool enforce, + string? tenantHeader, + CancellationToken cancellationToken + ) + { + StubResolver resolver = new(resolution); + + await using var host = await AdminTestHost.CreateAsync( + configureAdmin: options => + { + options.Features.ViewCapabilities = true; + options.EnforceTenantScope = enforce; + }, + configureServices: services => services.AddSingleton(resolver) + ); + + if (tenantHeader is not null) + host.Client.DefaultRequestHeaders.Add("Purview-Tenant", tenantHeader); + + var response = await host.Client.GetAsync("/admin/api/health", cancellationToken); + + return (response.StatusCode, resolver); + } + + // The default: a single-tenant deployment must be unaffected, and must not be asked for a tenant. + [Test] + public async Task Health_WhenTenantScopeNotEnforced_SucceedsWithoutATenant(CancellationToken cancellationToken) + { + var (status, resolver) = await CallHealthAsync( + Result.Success("acme"), + enforce: false, + tenantHeader: null, + cancellationToken + ); + + await Assert.That(status).IsEqualTo(HttpStatusCode.OK); + await Assert.That(resolver.ObservedRequestedTenant).IsNull(); + } + + [Test] + public async Task Health_WhenTenantResolves_Succeeds(CancellationToken cancellationToken) + { + var (status, resolver) = await CallHealthAsync( + Result.Success("globex"), + enforce: true, + tenantHeader: "globex", + cancellationToken + ); + + await Assert.That(status).IsEqualTo(HttpStatusCode.OK); + await Assert.That(resolver.ObservedRequestedTenant).IsEqualTo("globex"); + } + + [Test] + public async Task Health_WhenNoTenantSelected_IsRefused(CancellationToken cancellationToken) + { + var (status, _) = await CallHealthAsync( + AdminTenantFailure.Failure(new AdminTenantNotSelected("admin-1")), + enforce: true, + tenantHeader: null, + cancellationToken + ); + + await Assert.That(status).IsEqualTo(HttpStatusCode.BadRequest); + } + + [Test] + public async Task Health_WhenTenantNotEntitled_IsForbidden(CancellationToken cancellationToken) + { + var (status, _) = await CallHealthAsync( + AdminTenantFailure.Failure(new AdminTenantForbidden("admin-1", "globex")), + enforce: true, + tenantHeader: "globex", + cancellationToken + ); + + await Assert.That(status).IsEqualTo(HttpStatusCode.Forbidden); + } +} diff --git a/src/tests/Admin.UnitTests/Security/ClaimsAdminTenantResolverTests.cs b/src/tests/Admin.UnitTests/Security/ClaimsAdminTenantResolverTests.cs new file mode 100644 index 00000000..f58d4192 --- /dev/null +++ b/src/tests/Admin.UnitTests/Security/ClaimsAdminTenantResolverTests.cs @@ -0,0 +1,67 @@ +using System.Security.Claims; +using Purview.EventSourcing.Admin.Failures; +using Purview.EventSourcing.Admin.Security.Providers; + +namespace Purview.EventSourcing.Admin.Security; + +/// +/// Guards the rule that an admin request is always scoped to exactly one named tenant. +/// +public sealed class ClaimsAdminTenantResolverTests +{ + static ClaimsPrincipal UserWith(params string[] tenants) => + new(new ClaimsIdentity([.. tenants.Select(t => new Claim(ClaimsAdminTenantResolver.DefaultClaimType, t))])); + + static Task> ResolveAsync( + ClaimsPrincipal user, + string? requested = null + ) => new ClaimsAdminTenantResolver().ResolveAsync(user, requested, CancellationToken.None); + + [Test] + public async Task ResolveAsync_GivenASingleEntitlement_ScopesToIt() + { + var result = await ResolveAsync(UserWith("acme")); + + await Assert.That(result.IsSuccess).IsTrue(); + await Assert.That(result.Value).IsEqualTo("acme"); + } + + // The super user case: several entitlements and no choice made. Defaulting to the first would + // silently pick a tenant, and falling back to the system scope would hand a browser session a + // cross-tenant view. + [Test] + public async Task ResolveAsync_GivenSeveralEntitlementsAndNoSelection_IsDenied() + { + var result = await ResolveAsync(UserWith("acme", "globex")); + + await Assert.That(result.IsFailure).IsTrue(); + await Assert.That(result.Error is AdminTenantNotSelected).IsTrue(); + } + + [Test] + public async Task ResolveAsync_GivenSeveralEntitlementsAndASelection_ScopesToTheSelection() + { + var result = await ResolveAsync(UserWith("acme", "globex"), requested: "globex"); + + await Assert.That(result.IsSuccess).IsTrue(); + await Assert.That(result.Value).IsEqualTo("globex"); + } + + [Test] + public async Task ResolveAsync_GivenAnUnentitledSelection_IsForbidden() + { + var result = await ResolveAsync(UserWith("acme"), requested: "globex"); + + await Assert.That(result.IsFailure).IsTrue(); + await Assert.That(result.Error is AdminTenantForbidden).IsTrue(); + } + + [Test] + public async Task ResolveAsync_GivenNoEntitlements_IsDenied() + { + var result = await ResolveAsync(UserWith()); + + await Assert.That(result.IsFailure).IsTrue(); + await Assert.That(result.Error is AdminTenantNotSelected).IsTrue(); + } +} diff --git a/src/tests/Admin.UnitTests/Security/PermissionProviderTests.cs b/src/tests/Admin.UnitTests/Security/PermissionProviderTests.cs index d66c8e22..798a130e 100644 --- a/src/tests/Admin.UnitTests/Security/PermissionProviderTests.cs +++ b/src/tests/Admin.UnitTests/Security/PermissionProviderTests.cs @@ -2,8 +2,8 @@ using Microsoft.AspNetCore.Authorization; using Microsoft.Extensions.DependencyInjection; using Purview.EventSourcing.Admin.Models; -using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.Security.Providers; +using Purview.EventSourcing.Admin.Services; namespace Purview.EventSourcing.Admin.Security; diff --git a/src/tests/AzureStorage.IntegrationTests/Events/AzureTableEventStoreTenancyTests.cs b/src/tests/AzureStorage.IntegrationTests/Events/AzureTableEventStoreTenancyTests.cs new file mode 100644 index 00000000..a73b57fe --- /dev/null +++ b/src/tests/AzureStorage.IntegrationTests/Events/AzureTableEventStoreTenancyTests.cs @@ -0,0 +1,72 @@ +using Purview.EventSourcing.Aggregates.Persistence; +using Purview.EventSourcing.Fixtures.AzureStorage; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.AzureStorage.Events; + +/// +/// Guards that the tenant query filter isolates event streams. +/// +/// +/// Exercised against real Azure Table Storage rather than in memory: the isolation is an Entity Framework global +/// query filter translated into SQL, so an in-memory substitute would prove nothing about the predicate +/// that actually runs. +/// +[ClassDataSource(Shared = SharedType.PerAssembly)] +public sealed class AzureTableEventStoreTenancyTests(TableEventStoreFixture fixture) +{ + sealed class StubTenant(TenantScope scope) : ICurrentTenant + { + public TenantScope Current => scope; + } + + TableEventStore StoreFor(TenantScope scope, Guid runId) => + fixture.CreateEventStore(currentTenant: new StubTenant(scope), runId: runId); + + [Test] + public async Task GetAsync_GivenAnotherTenantsAggregate_DoesNotReturnIt(CancellationToken cancellationToken) + { + // Arrange - one physical table, two tenants, the same aggregate id. + var runId = Guid.NewGuid(); + var aggregateId = $"{Guid.NewGuid()}"; + + var acme = StoreFor(TenantScope.For("acme"), runId); + var globex = StoreFor(TenantScope.For("globex"), runId); + + var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); + aggregate.IncrementInt32Value(); + + var saved = await acme.SaveAsync(aggregate, cancellationToken: cancellationToken); + await Assert.That(saved.IsSuccess).IsTrue(); + + // Act + var fromOwner = await acme.GetAsync(aggregateId, cancellationToken: cancellationToken); + var fromOther = await globex.GetAsync(aggregateId, cancellationToken: cancellationToken); + + // Assert + await Assert.That(fromOwner.IsSuccess).IsTrue(); + await Assert.That(fromOther.IsFailure).IsTrue(); + } + + [Test] + public async Task GetAsync_GivenSystemScope_ReadsAcrossTenants(CancellationToken cancellationToken) + { + // Arrange + var runId = Guid.NewGuid(); + var aggregateId = $"{Guid.NewGuid()}"; + + var acme = StoreFor(TenantScope.For("acme"), runId); + var system = StoreFor(TenantScope.System, runId); + + var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); + aggregate.IncrementInt32Value(); + + await acme.SaveAsync(aggregate, cancellationToken: cancellationToken); + + // Act - infrastructure work deliberately crosses tenants. + var result = await system.GetAsync(aggregateId, cancellationToken: cancellationToken); + + // Assert + await Assert.That(result.IsSuccess).IsTrue(); + } +} diff --git a/src/tests/AzureStorage.IntegrationTests/Guards/AzureTableEventStoreGuardTests.cs b/src/tests/AzureStorage.IntegrationTests/Guards/AzureTableEventStoreGuardTests.cs index e3155358..63896630 100644 --- a/src/tests/AzureStorage.IntegrationTests/Guards/AzureTableEventStoreGuardTests.cs +++ b/src/tests/AzureStorage.IntegrationTests/Guards/AzureTableEventStoreGuardTests.cs @@ -1,5 +1,7 @@ +using System.Diagnostics.CodeAnalysis; using System.Text; using Azure.Data.Tables; +using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Persistence; using Purview.EventSourcing.Aggregates.Persistence.Events; using Purview.EventSourcing.AzureStorage.Entities; @@ -52,7 +54,7 @@ await Assert var tableClient = ctx.TableClient; // Act - bool result = await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); + var result = await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); var streamVersionVersion = await GetStreamVersionNumberAndAssertNotNull( tableClient, @@ -61,10 +63,16 @@ await Assert ); // Assert - await Assert.That(result).IsTrue(); + await Assert.That(result.IsSuccess).IsTrue(); await Assert.That(aggregate.IsNew()).IsFalse(); - var aggregateFromEventStore = await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken); + var aggregateFromEventStoreResult = await eventStore.GetAsync( + aggregateId, + cancellationToken: cancellationToken + ); + var aggregateFromEventStore = aggregateFromEventStoreResult.IsSuccess + ? aggregateFromEventStoreResult.Value + : null; await AssertRecreatedMatchesSource(aggregateFromEventStore, aggregate); @@ -90,16 +98,22 @@ CancellationToken cancellationToken var tableClient = ctx.TableClient; // Act - bool result = await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); + var result = await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); // Get and update stream version to remove the Version property. var streamVersionVersion = await ReadAndRemoveStreamVersion(tableClient, aggregateId, cancellationToken); // Assert - await Assert.That(result).IsTrue(); + await Assert.That(result.IsSuccess).IsTrue(); await Assert.That(aggregate.IsNew()).IsFalse(); - var aggregateFromEventStore = await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken); + var aggregateFromEventStoreResult = await eventStore.GetAsync( + aggregateId, + cancellationToken: cancellationToken + ); + var aggregateFromEventStore = aggregateFromEventStoreResult.IsSuccess + ? aggregateFromEventStoreResult.Value + : null; await AssertRecreatedMatchesSource(aggregateFromEventStore, aggregate); @@ -124,15 +138,13 @@ CancellationToken cancellationToken await eventStore.SaveAsync(aggregate, cancellationToken); - var aggregateResult = - await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken) - ?? throw new NullReferenceException(); + var aggregateResult = (await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken)).Value; // Act var result = await eventStore.DeleteAsync(aggregateResult, cancellationToken: cancellationToken); // Assert - await Assert.That(result).IsTrue(); + await Assert.That(result.IsSuccess).IsTrue(); cache.RemoveAsync(cacheKey, Any()).WasCalled(Times.Once); } @@ -153,7 +165,8 @@ CancellationToken cancellationToken await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); - aggregate = await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken); + var aggregateResult = await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken); + aggregate = aggregateResult.IsSuccess ? aggregateResult.Value : null; await Assert.That(aggregate).IsNotNull(); // Act @@ -164,7 +177,7 @@ CancellationToken cancellationToken ); // Assert - await Assert.That(result).IsTrue(); + await Assert.That(result.IsSuccess).IsTrue(); await Assert.That(aggregate.Details.IsDeleted).IsTrue(); await Assert.That(aggregate.Details.Locked).IsTrue(); @@ -200,7 +213,8 @@ CancellationToken cancellationToken await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); - aggregate = await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken); + var aggregateResult = await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken); + aggregate = aggregateResult.IsSuccess ? aggregateResult.Value : null; await Assert.That(aggregate).IsNotNull(); // Act @@ -211,7 +225,7 @@ CancellationToken cancellationToken ); // Assert - await Assert.That(result).IsTrue(); + await Assert.That(result.IsSuccess).IsTrue(); await Assert.That(aggregate.Details.IsDeleted).IsTrue(); await Assert.That(aggregate.Details.Locked).IsTrue(); @@ -232,16 +246,22 @@ CancellationToken cancellationToken var telemetry = ctx.Telemetry; // Act - bool result = await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); + var result = await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); // Assert - await Assert.That(result).IsFalse(); + await Assert.That(result.IsSuccess).IsTrue(); + await Assert.That(result.Value.Kind).IsEqualTo(SaveOutcomeKind.NoChanges); telemetry.SaveContainedNoChanges(aggregateId, Any(), Any()).WasCalled(Times.Once); } [Test] [MethodDataSource(nameof(OldEventCountTestData))] + [SuppressMessage( + "Maintainability", + "CA1506", + Justification = "Guard scenario intentionally touches the full event-store surface." + )] public async Task GetAsync_GivenAnAggregateWithNonRegisteredEventType_TelemetryLogsCannotApplyEvent( int eventsToCreate, int numberOfOldEventsToCreate, @@ -261,11 +281,12 @@ CancellationToken cancellationToken // Act await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); - var result = await eventStore.GetAsync( + var resultResult = await eventStore.GetAsync( aggregateId, new EventStoreOperationContext { SkipSnapshot = true }, cancellationToken: cancellationToken ); + var result = resultResult.IsSuccess ? resultResult.Value : null; // Assert telemetry @@ -275,7 +296,7 @@ CancellationToken cancellationToken Any(), Any(), Is(eventType => eventType!.Contains(nameof(OldEvent), StringComparison.Ordinal)), - Any() + Any() ) .WasCalled(Times.Exactly(numberOfOldEventsToCreate)); @@ -318,15 +339,16 @@ await MarkEventsAsUnknown( cancellationToken ); - var result = await eventStore.GetAsync( + var resultResult = await eventStore.GetAsync( aggregateId, new EventStoreOperationContext { SkipSnapshot = true }, cancellationToken: cancellationToken ); + var result = resultResult.IsSuccess ? resultResult.Value : null; // Assert telemetry - .SkippedUnknownEvent(aggregateId, Any(), Any(), unknownEventType, Any()) + .SkippedUnknownEvent(aggregateId, Any(), Any(), unknownEventType, Any()) .WasCalled(Times.Exactly(numberOfOldEventsToCreate)); await Assert.That(result).IsNotNull(); @@ -400,7 +422,7 @@ CancellationToken cancellationToken await tableClient.SubmitBatchAsync(batch, cancellationToken); } - static async Task ReadAndRemoveStreamVersion( + static async Task ReadAndRemoveStreamVersion( AzureTableClient tableClient, string aggregateId, CancellationToken cancellationToken @@ -413,7 +435,8 @@ await tableClient.GetAsync( TableEventStoreConstants.StreamVersionRowKey, cancellationToken: cancellationToken ) ?? throw new NullReferenceException(); - var streamVersionVersion = streamVersion[nameof(StreamVersionEntity.Version)] as int?; + // Stored as Edm.Int64 since the stream version widened; reading it as int? would silently yield null. + var streamVersionVersion = streamVersion[nameof(StreamVersionEntity.Version)] as long?; streamVersion.Remove(nameof(StreamVersionEntity.Version)); @@ -426,7 +449,7 @@ await tableClient.OperationAsync( return streamVersionVersion; } - static async Task GetStreamVersionNumberAndAssertNotNull( + static async Task GetStreamVersionNumberAndAssertNotNull( AzureTableClient tableClient, string aggregateId, CancellationToken cancellationToken @@ -441,7 +464,8 @@ CancellationToken cancellationToken await Assert.That(streamVersion).IsNotNull(); - return streamVersion![nameof(StreamVersionEntity.Version)] as int?; + // Stored as Edm.Int64 since the stream version widened; reading it as int? would silently yield null. + return streamVersion![nameof(StreamVersionEntity.Version)] as long?; } static async Task AssertRecreatedMatchesSource(PersistenceAggregate? result, PersistenceAggregate aggregate) diff --git a/src/tests/CosmosDb.IntegrationTests/Snapshots/CosmosDbSnapshotEventStoreTests.Paging.cs b/src/tests/CosmosDb.IntegrationTests/Snapshots/CosmosDbSnapshotEventStoreTests.Paging.cs new file mode 100644 index 00000000..501a5edd --- /dev/null +++ b/src/tests/CosmosDb.IntegrationTests/Snapshots/CosmosDbSnapshotEventStoreTests.Paging.cs @@ -0,0 +1,139 @@ +namespace Purview.EventSourcing.CosmosDb.Snapshots; + +// Cosmos DB pages through continuation tokens rather than offsets, so these cover the token's own +// semantics: it resumes where the previous page ended, and is null once the last page has been read. +partial class CosmosDbSnapshotEventStoreTests +{ + [Test] + [Arguments(10, 3)] + [Arguments(10, 10)] + [Arguments(5, 20)] + public async Task ListAsync_GivenPageSize_PagesThroughEveryAggregateExactlyOnce( + int numberOfAggregates, + int pageSize, + CancellationToken cancellationToken + ) + { + // Arrange + await using var context = fixture.CreateContext(correlationIdsToGenerate: numberOfAggregates); + + HashSet expectedIds = []; + for (var index = 0; index < numberOfAggregates; index++) + { + var aggregate = CreateAggregate($"{index}_{context.RunId}"); + aggregate.IncrementInt32Value(); + + var saveResult = await context.EventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); + + await Assert.That(saveResult.IsSuccess).IsTrue(); + expectedIds.Add(aggregate.Details.Id); + } + + // Act + List ids = []; + var response = await context.EventStore.ListAsync( + new ContinuationRequest { MaxRecords = pageSize }, + cancellationToken: cancellationToken + ); + ids.AddRange(response.Results.Select(aggregate => aggregate.Details.Id)); + + await Assert.That(response.Results.Length).IsEqualTo(Math.Min(pageSize, numberOfAggregates)); + + while (response.ContinuationToken != null) + { + response = await context.EventStore.ListAsync(response.ToRequest(), cancellationToken: cancellationToken); + ids.AddRange(response.Results.Select(aggregate => aggregate.Details.Id)); + } + + // Assert + await Assert.That(ids.Count).IsEqualTo(numberOfAggregates); + await Assert.That(ids.Distinct().Count()).IsEqualTo(numberOfAggregates); + await Assert.That(ids.ToHashSet().SetEquals(expectedIds)).IsTrue(); + } + + [Test] + public async Task ListAsync_GivenPageSizeLargerThanResultSet_ReturnsNullContinuationToken( + CancellationToken cancellationToken + ) + { + // Arrange + const int numberOfAggregates = 3; + await using var context = fixture.CreateContext(correlationIdsToGenerate: numberOfAggregates); + + for (var index = 0; index < numberOfAggregates; index++) + { + var aggregate = CreateAggregate($"{index}_{context.RunId}"); + aggregate.IncrementInt32Value(); + + var saveResult = await context.EventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); + + await Assert.That(saveResult.IsSuccess).IsTrue(); + } + + // Act + var response = await context.EventStore.ListAsync( + new ContinuationRequest { MaxRecords = numberOfAggregates + 10 }, + cancellationToken: cancellationToken + ); + + // Assert + await Assert.That(response.Results.Length).IsEqualTo(numberOfAggregates); + await Assert.That(response.ContinuationToken).IsNull(); + } + + [Test] + public async Task QueryAsync_GivenNoMatchingAggregates_ReturnsEmptyPageWithoutToken( + CancellationToken cancellationToken + ) + { + // Arrange + await using var context = fixture.CreateContext(); + + var aggregate = CreateAggregate($"no-match_{context.RunId}"); + aggregate.IncrementInt32Value(); + + var saveResult = await context.EventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); + await Assert.That(saveResult.IsSuccess).IsTrue(); + + // Act + var response = await context.EventStore.QueryAsync( + m => m.IncrementInt32 == -1, + cancellationToken: cancellationToken + ); + + // Assert + await Assert.That(response.Results).IsEmpty(); + await Assert.That(response.ContinuationToken).IsNull(); + } + + [Test] + public async Task QueryAsync_GivenIncludeTotalCount_ReturnsTotalBeyondThePage(CancellationToken cancellationToken) + { + // Arrange + const int numberOfAggregates = 6; + const int pageSize = 2; + + await using var context = fixture.CreateContext(correlationIdsToGenerate: numberOfAggregates); + + for (var index = 0; index < numberOfAggregates; index++) + { + var aggregate = CreateAggregate($"{index}_{context.RunId}"); + aggregate.SetInt32Value(42); + + var saveResult = await context.EventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); + + await Assert.That(saveResult.IsSuccess).IsTrue(); + } + + // Act + var response = await context.EventStore.QueryAsync( + m => m.Int32Value == 42, + new ContinuationRequest { MaxRecords = pageSize, IncludeTotalCount = true }, + cancellationToken: cancellationToken + ); + + // Assert + await Assert.That(response.Results.Length).IsEqualTo(pageSize); + await Assert.That(response.TotalCount).IsEqualTo(numberOfAggregates); + } +} diff --git a/src/tests/CosmosDb.IntegrationTests/Snapshots/CosmosDbSnapshotEventStoreTests.QueryTranslation.cs b/src/tests/CosmosDb.IntegrationTests/Snapshots/CosmosDbSnapshotEventStoreTests.QueryTranslation.cs new file mode 100644 index 00000000..d8ef6ec3 --- /dev/null +++ b/src/tests/CosmosDb.IntegrationTests/Snapshots/CosmosDbSnapshotEventStoreTests.QueryTranslation.cs @@ -0,0 +1,125 @@ +using Purview.EventSourcing.Aggregates; + +namespace Purview.EventSourcing.CosmosDb.Snapshots; + +// Predicates are translated by Entity Framework against the document root, so these cover the shapes +// that depend on that mapping: string functions, culture-invariant casing (which is rewritten to the +// translatable overload), and members of a nested complex type. +partial class CosmosDbSnapshotEventStoreTests +{ + [Test] + public async Task QueryAsync_GivenStartsWithPredicate_TranslatesAndMatches(CancellationToken cancellationToken) + { + // Arrange + await using var context = fixture.CreateContext(); + + var prefix = $"prefix-{context.RunId}"; + var aggregate = CreateAggregate($"starts-with_{context.RunId}"); + aggregate.AppendString($"{prefix}-value"); + + var saveResult = await context.EventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); + await Assert.That(saveResult.IsSuccess).IsTrue(); + + // Act + var result = await context.EventStore.SingleOrDefaultAsync( + m => m.StringProperty.StartsWith(prefix, StringComparison.Ordinal), + cancellationToken: cancellationToken + ); + + // Assert + await Assert.That(result).IsNotNull(); + await Assert.That(result!.Details.Id).IsEqualTo(aggregate.Details.Id); + } + + [Test] + public async Task QueryAsync_GivenContainsPredicate_TranslatesAndMatches(CancellationToken cancellationToken) + { + // Arrange + await using var context = fixture.CreateContext(); + + var fragment = $"fragment-{context.RunId}"; + var aggregate = CreateAggregate($"contains_{context.RunId}"); + aggregate.AppendString($"leading-{fragment}-trailing"); + + var saveResult = await context.EventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); + await Assert.That(saveResult.IsSuccess).IsTrue(); + + // Act + var result = await context.EventStore.SingleOrDefaultAsync( + m => m.StringProperty.Contains(fragment, StringComparison.Ordinal), + cancellationToken: cancellationToken + ); + + // Assert + await Assert.That(result).IsNotNull(); + await Assert.That(result!.Details.Id).IsEqualTo(aggregate.Details.Id); + } + + [Test] + public async Task QueryAsync_GivenInvariantLowerCasePredicate_TranslatesAndMatches( + CancellationToken cancellationToken + ) + { + // Arrange + await using var context = fixture.CreateContext(); + + var value = $"MIXED-Case-{context.RunId}"; + var aggregate = CreateAggregate($"casing_{context.RunId}"); + aggregate.AppendString(value); + + var saveResult = await context.EventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); + await Assert.That(saveResult.IsSuccess).IsTrue(); + +#pragma warning disable CA1308 // Normalize strings to uppercase +#pragma warning disable CA1862 // Use the 'StringComparison' method overloads + var expected = value.ToLowerInvariant(); + + // Act + // ToLowerInvariant has no Cosmos DB translation; the shared predicate rewriter normalizes it to + // ToLower, which maps onto LOWER. + var result = await context.EventStore.SingleOrDefaultAsync( + m => m.StringProperty.ToLowerInvariant() == expected, + cancellationToken: cancellationToken + ); +#pragma warning restore CA1862 // Use the 'StringComparison' method overloads +#pragma warning restore CA1308 // Normalize strings to uppercase + + // Assert + await Assert.That(result).IsNotNull(); + await Assert.That(result!.Details.Id).IsEqualTo(aggregate.Details.Id); + } + + [Test] + public async Task QueryAsync_GivenComplexMemberPredicate_TranslatesAndMatches(CancellationToken cancellationToken) + { + // Arrange + await using var context = fixture.CreateContext(); + + var complexValue = $"complex-{context.RunId}"; + var aggregate = CreateAggregate($"complex_{context.RunId}"); + aggregate.SetComplexProperty( + new ComplexTestType + { + Int16Property = 16, + Int32Property = 32, + Int64Property = 64, + StringProperty = complexValue, + DateTimeOffsetProperty = DateTimeOffset.UtcNow, + } + ); + + var saveResult = await context.EventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); + await Assert.That(saveResult.IsSuccess).IsTrue(); + + // Act + var result = await context.EventStore.SingleOrDefaultAsync( + m => m.ComplexTestType!.StringProperty == complexValue, + cancellationToken: cancellationToken + ); + + // Assert + await Assert.That(result).IsNotNull(); + await Assert.That(result!.Details.Id).IsEqualTo(aggregate.Details.Id); + await Assert.That(result.ComplexTestType!.Int32Property).IsEqualTo(32); + } +} diff --git a/src/tests/CosmosDb.IntegrationTests/Snapshots/CosmosDbSnapshotEventStoreTests.WithStringValues.cs b/src/tests/CosmosDb.IntegrationTests/Snapshots/CosmosDbSnapshotEventStoreTests.WithStringValues.cs deleted file mode 100644 index 7bf90a4f..00000000 --- a/src/tests/CosmosDb.IntegrationTests/Snapshots/CosmosDbSnapshotEventStoreTests.WithStringValues.cs +++ /dev/null @@ -1,99 +0,0 @@ -using Microsoft.Azure.Cosmos; -using Microsoft.Extensions.Primitives; -using Purview.EventSourcing.Aggregates.Persistence; - -namespace Purview.EventSourcing.CosmosDb.Snapshots; - -partial class CosmosDbSnapshotEventStoreTests -{ - [Test] - [Arguments(1)] - [Arguments(5)] - [Arguments(10)] - [System.Diagnostics.CodeAnalysis.SuppressMessage("Performance", "CA1861:Avoid constant arrays as arguments")] - public async Task CanQuery_GivenAggregatesContainsDictionaryWithStringValuesAsValue_QueryAsExpected( - int numberOfAggregates, - CancellationToken cancellationToken - ) - { - // Arrange - await using var context = fixture.CreateContext(correlationIdsToGenerate: numberOfAggregates); - - var aggregateType = CreateAggregate().AggregateType; - PartitionKey partitionKey = new(aggregateType); - - for (var aggregateIndex = 0; aggregateIndex < numberOfAggregates; aggregateIndex++) - { - var aggregate = CreateAggregate($"{aggregateIndex}_{context.RunId}"); - aggregate.AddKVPs([ - new KeyValuePair("name-1", "value-1"), - new KeyValuePair("name-2", new[] { "value-100", "value-200" }), - ]); - - bool saveResult = await context.EventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); - - await Assert.That(saveResult).IsTrue(); - } - - // Act - var aggregates = ( - await context.CosmosDbClient.QueryAsync( - m => m.StringValuesDictionary["name-1"] == "value-1", - partitionKey, - maxRecords: numberOfAggregates, - cancellationToken: cancellationToken - ) - ).Results; - - // Assert - await Assert.That(aggregates.Length).IsEqualTo(numberOfAggregates); - } - - [Test] - [Arguments(1)] - [Arguments(5)] - [Arguments(10)] - public async Task CanQuery_GivenAggregatesContainsDictionaryWithStringsAsValues_QueryAsExpected( - int numberOfAggregates, - CancellationToken cancellationToken - ) - { - // Arrange - await using var context = fixture.CreateContext(correlationIdsToGenerate: numberOfAggregates); - - var aggregateType = CreateAggregate().AggregateType; - PartitionKey partitionKey = new(aggregateType); - - for (var aggregateIndex = 0; aggregateIndex < numberOfAggregates; aggregateIndex++) - { - var aggregate = CreateAggregate($"{aggregateIndex}_{context.RunId}"); - aggregate.AddKVPs([ - new KeyValuePair("name-1", "value-1"), - new KeyValuePair("name-2", "value-100"), - ]); - - bool saveResult = await context.EventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); - - await Assert.That(saveResult).IsTrue(); - } - - // Act -#pragma warning disable CA1304 // Specify CultureInfo -#pragma warning disable CA1862 // Use the 'StringComparison' method overloads to perform case-insensitive string comparisons -#pragma warning disable CA1311 // Specify a culture or use an invariant version - var aggregates = ( - await context.CosmosDbClient.QueryAsync( - m => m.StringsDictionary["name-1"].ToLower() == "value-1", - partitionKey, - maxRecords: numberOfAggregates, - cancellationToken: cancellationToken - ) - ).Results; -#pragma warning restore CA1311 // Specify a culture or use an invariant version -#pragma warning restore CA1862 // Use the 'StringComparison' method overloads to perform case-insensitive string comparisons -#pragma warning restore CA1304 // Specify CultureInfo - - // Assert - await Assert.That(aggregates.Length).IsEqualTo(numberOfAggregates); - } -} diff --git a/src/tests/CosmosDb.IntegrationTests/Snapshots/CosmosDbSnapshotEventStoreTests.cs b/src/tests/CosmosDb.IntegrationTests/Snapshots/CosmosDbSnapshotEventStoreTests.cs index 8a873c58..02189cb0 100644 --- a/src/tests/CosmosDb.IntegrationTests/Snapshots/CosmosDbSnapshotEventStoreTests.cs +++ b/src/tests/CosmosDb.IntegrationTests/Snapshots/CosmosDbSnapshotEventStoreTests.cs @@ -1,12 +1,12 @@ -using Purview.EventSourcing.Aggregates.Persistence; +using Purview.EventSourcing.Aggregates.Persistence; using Purview.EventSourcing.Fixtures.CosmosDb; namespace Purview.EventSourcing.CosmosDb.Snapshots; -// Holds the fixture and shared helpers for Cosmos-specific snapshot tests (dictionary/partition-key -// queries). The provider-agnostic snapshot contract suite lives in SnapshotStoreContractTests. +// Holds the fixture and shared helpers for Cosmos-specific snapshot tests (paging and query +// translation). The provider-agnostic snapshot contract suite lives in SnapshotStoreContractTests. [ClassDataSource(Shared = SharedType.PerTestSession)] -[NotInParallel(nameof(CosmosDbClient))] +[NotInParallel(CosmosDbTestConstraints.Container)] public partial class CosmosDbSnapshotEventStoreTests(CosmosDbSnapshotEventStoreFixture fixture) { static PersistenceAggregate CreateAggregate(string? id = null, Action? action = null) @@ -18,3 +18,9 @@ static PersistenceAggregate CreateAggregate(string? id = null, Action(Shared = SharedType.PerTestSession)] -[NotInParallel(nameof(CosmosDbClient))] +[NotInParallel(CosmosDbTestConstraints.Container)] [InheritsTests] public sealed class SnapshotStoreContractTests(CosmosDbSnapshotEventStoreFixture fixture) : SnapshotStoreContractTestsBase, diff --git a/src/tests/EventSourcing.UnitTests/AggregateExistenceTests.cs b/src/tests/EventSourcing.UnitTests/AggregateExistenceTests.cs new file mode 100644 index 00000000..213e62e5 --- /dev/null +++ b/src/tests/EventSourcing.UnitTests/AggregateExistenceTests.cs @@ -0,0 +1,33 @@ +namespace Purview.EventSourcing; + +public class AggregateExistenceTests +{ + [Test] + [Arguments(ExistenceStatus.Exists, true, false)] + [Arguments(ExistenceStatus.ExistsInDeletedState, true, true)] + [Arguments(ExistenceStatus.DoesNotExist, false, false)] + public async Task Status_GivenEachState_ReportsExistenceAndDeletion( + ExistenceStatus status, + bool expectedDoesExist, + bool expectedIsDeleted + ) + { + // Act + AggregateExistence existence = new(status, Version: null); + + // Assert + await Assert.That(existence.DoesExist).IsEqualTo(expectedDoesExist); + await Assert.That(existence.IsDeleted).IsEqualTo(expectedIsDeleted); + } + + [Test] + public async Task IsDeleted_GivenExistsInDeletedState_IsDistinctFromDoesExist() + { + // A deleted aggregate exists and is deleted; a single boolean cannot carry both, which is why + // there is no conversion to bool. + var existence = AggregateExistence.ExistsInDeletedState; + + await Assert.That(existence.DoesExist).IsTrue(); + await Assert.That(existence.IsDeleted).IsTrue(); + } +} diff --git a/src/tests/EventSourcing.UnitTests/Aggregates/AggregateBaseTests.ClearUnsavedEvents.cs b/src/tests/EventSourcing.UnitTests/Aggregates/AggregateBaseTests.ClearUnsavedEvents.cs index b277989d..88ff0fe5 100644 --- a/src/tests/EventSourcing.UnitTests/Aggregates/AggregateBaseTests.ClearUnsavedEvents.cs +++ b/src/tests/EventSourcing.UnitTests/Aggregates/AggregateBaseTests.ClearUnsavedEvents.cs @@ -1,4 +1,4 @@ -namespace Purview.EventSourcing.Aggregates; +namespace Purview.EventSourcing.Aggregates; partial class AggregateBaseTests { diff --git a/src/tests/EventSourcing.UnitTests/Aggregates/AggregateBaseTests.cs b/src/tests/EventSourcing.UnitTests/Aggregates/AggregateBaseTests.cs index b9b432fe..9af0efe8 100644 --- a/src/tests/EventSourcing.UnitTests/Aggregates/AggregateBaseTests.cs +++ b/src/tests/EventSourcing.UnitTests/Aggregates/AggregateBaseTests.cs @@ -58,7 +58,7 @@ public async Task GetUnsavedEvents_GivenEvent_RecordsOneEventToBeRecorded() public async Task ClearUnsavedEvents_GivenEventsAndClearEventsCalledWithSpecificVersion_ClearEventsThatAreGreaterThanOrOrEqualToSpecifiedVersion( int eventsToCreate, int versionToClear, - int expectedVersion + long expectedVersion ) { // Arrange diff --git a/src/tests/EventSourcing.UnitTests/Aggregates/Snapshotting/SnapshotStrategyTests.cs b/src/tests/EventSourcing.UnitTests/Aggregates/Snapshotting/SnapshotStrategyTests.cs index 6430aa72..07850073 100644 --- a/src/tests/EventSourcing.UnitTests/Aggregates/Snapshotting/SnapshotStrategyTests.cs +++ b/src/tests/EventSourcing.UnitTests/Aggregates/Snapshotting/SnapshotStrategyTests.cs @@ -17,7 +17,7 @@ public bool ShouldSnapshot(TestAggregate aggregate, int eventsApplied) } } - static TestAggregate CreateAggregate(int savedVersion) + static TestAggregate CreateAggregate(long savedVersion) { TestAggregate aggregate = new() { Details = { Id = Guid.NewGuid().ToString() } }; aggregate.Details.SavedVersion = savedVersion; @@ -35,7 +35,7 @@ static TestAggregate CreateAggregate(int savedVersion) [Arguments(3, 5, false)] // 3 % 5 != 0 [Arguments(7, 5, false)] // 7 % 5 != 0 public async Task IntervalStrategy_GivenSavedVersionAndInterval_ReturnsExpected( - int savedVersion, + long savedVersion, int interval, bool expectedResult ) diff --git a/src/tests/EventSourcing.UnitTests/Aggregates/Test/TestAggregate.cs b/src/tests/EventSourcing.UnitTests/Aggregates/Test/TestAggregate.cs index fa9efd90..8e40aba9 100644 --- a/src/tests/EventSourcing.UnitTests/Aggregates/Test/TestAggregate.cs +++ b/src/tests/EventSourcing.UnitTests/Aggregates/Test/TestAggregate.cs @@ -1,4 +1,4 @@ -using System.Collections.ObjectModel; +using System.Collections.ObjectModel; using Purview.EventSourcing.Aggregates.Test.Events; namespace Purview.EventSourcing.Aggregates.Test; diff --git a/src/tests/EventSourcing.UnitTests/Cryptography/AesGcmEventPayloadProtectorTests.cs b/src/tests/EventSourcing.UnitTests/Cryptography/AesGcmEventPayloadProtectorTests.cs new file mode 100644 index 00000000..2f048593 --- /dev/null +++ b/src/tests/EventSourcing.UnitTests/Cryptography/AesGcmEventPayloadProtectorTests.cs @@ -0,0 +1,109 @@ +namespace Purview.EventSourcing.Cryptography; + +/// +/// Guards the crypto-shredding contract: a payload round-trips for its own subject, becomes unreadable +/// once that subject is erased, and leaves every other subject untouched. +/// +public sealed class AesGcmEventPayloadProtectorTests +{ + const string Payload = """{"Amount":42,"Name":"Ada"}"""; + + static (AesGcmEventPayloadProtector Protector, InMemoryEventCryptoKeyStore Keys) Create() + { + InMemoryEventCryptoKeyStore keys = new(); + + return (new AesGcmEventPayloadProtector(keys), keys); + } + + [Test] + public async Task ProtectAsync_ThenUnprotect_RoundTripsThePayload() + { + var (protector, _) = Create(); + + var protectedPayload = await protector.ProtectAsync(Payload, "user-4712"); + + await Assert.That(protector.IsProtected(protectedPayload)).IsTrue(); + await Assert.That(await protector.UnprotectAsync(protectedPayload)).IsEqualTo(Payload); + } + + // The whole point: the ciphertext must not contain the plaintext, or erasing the key achieves nothing. + [Test] + public async Task ProtectAsync_DoesNotLeaveThePlaintextReadable() + { + var (protector, _) = Create(); + + var protectedPayload = await protector.ProtectAsync(Payload, "user-4712"); + + // Distinctive fragments, not short ones: a two-character value like "42" turns up in base64 by + // chance and would make this pass or fail at random. + await Assert.That(protectedPayload).DoesNotContain("Ada"); + await Assert.That(protectedPayload).DoesNotContain("Amount"); + await Assert.That(protectedPayload).DoesNotContain(Payload); + } + + [Test] + public async Task UnprotectAsync_AfterShredding_ReturnsNull() + { + var (protector, keys) = Create(); + var protectedPayload = await protector.ProtectAsync(Payload, "user-4712"); + + var shredded = await keys.ShredAsync("user-4712", CancellationToken.None); + + await Assert.That(shredded).IsTrue(); + await Assert.That(await protector.UnprotectAsync(protectedPayload)).IsNull(); + } + + // Erasure must be surgical: one subject's erasure cannot take another's data with it. + [Test] + public async Task ShredAsync_LeavesOtherSubjectsReadable() + { + var (protector, keys) = Create(); + var erased = await protector.ProtectAsync(Payload, "user-4712"); + var retained = await protector.ProtectAsync(Payload, "user-9003"); + + await keys.ShredAsync("user-4712", CancellationToken.None); + + await Assert.That(await protector.UnprotectAsync(erased)).IsNull(); + await Assert.That(await protector.UnprotectAsync(retained)).IsEqualTo(Payload); + } + + // A payload written before protection was configured must still be readable. + [Test] + public async Task UnprotectAsync_GivenAnUnprotectedPayload_ReturnsItUnchanged() + { + var (protector, _) = Create(); + + await Assert.That(await protector.UnprotectAsync(Payload)).IsEqualTo(Payload); + } + + // The subject is bound as associated data, so ciphertext cannot be re-attributed to another subject. + [Test] + public async Task UnprotectAsync_GivenCipherTextReattributedToAnotherSubject_Fails() + { + var (protector, keys) = Create(); + var protectedPayload = await protector.ProtectAsync(Payload, "user-4712"); + + // Give the other subject the same key, so only the bound subject id differs. + var key = await keys.GetOrCreateAsync("user-4712", CancellationToken.None); + StubKeyStore sharedKeys = new(key); + AesGcmEventPayloadProtector attacker = new(sharedKeys); + + var reattributed = protectedPayload.Replace("user-4712", "user-9003", StringComparison.Ordinal); + + await Assert + .That(async () => await attacker.UnprotectAsync(reattributed)) + .Throws(); + } + + sealed class StubKeyStore(byte[] key) : IEventCryptoKeyStore + { + public Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) => + Task.FromResult(key); + + public Task TryGetAsync(string dataSubjectId, CancellationToken cancellationToken) => + Task.FromResult(key); + + public Task ShredAsync(string dataSubjectId, CancellationToken cancellationToken) => + Task.FromResult(true); + } +} diff --git a/src/tests/EventSourcing.UnitTests/EFOpaqueAttribute.cs b/src/tests/EventSourcing.UnitTests/EFOpaqueAttribute.cs index f94bf642..5b8eb245 100644 --- a/src/tests/EventSourcing.UnitTests/EFOpaqueAttribute.cs +++ b/src/tests/EventSourcing.UnitTests/EFOpaqueAttribute.cs @@ -4,6 +4,7 @@ #pragma warning disable IDE0130 // Namespace does not match folder structure namespace Purview.EventSourcing.EntityFrameworkCore; + #pragma warning restore IDE0130 // Namespace does not match folder structure [AttributeUsage(AttributeTargets.Property, Inherited = true, AllowMultiple = false)] diff --git a/src/tests/EventSourcing.UnitTests/EntityFrameworkCore/SnapshotModelMapperTests.cs b/src/tests/EventSourcing.UnitTests/EntityFrameworkCore/SnapshotModelMapperTests.cs new file mode 100644 index 00000000..bd53cc49 --- /dev/null +++ b/src/tests/EventSourcing.UnitTests/EntityFrameworkCore/SnapshotModelMapperTests.cs @@ -0,0 +1,320 @@ +using System.Linq.Expressions; +using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Aggregates.Events; +using Purview.EventSourcing.EntityFrameworkCore.Mapping; +using Purview.EventSourcing.EntityFrameworkCore.Query; +using Purview.ValueObjects.Serialization; + +namespace Purview.EventSourcing.EntityFrameworkCore.Snapshots; + +// The snapshot shape rules and predicate rewriting are shared by every EF-backed provider +// (SQL Server, Postgres and Cosmos DB), so they are covered once, here. +public sealed class SnapshotModelMapperTests +{ + [Test] + public async Task ValidateAggregatePayloadShape_GivenEventStoreCollections_DoesNotThrow() + { + await Assert + .That(() => SnapshotModelMapper.ValidateAggregatePayloadShape(typeof(SupportedCollectionAggregate))) + .ThrowsNothing(); + } + + [Test] + public async Task ValidateAggregatePayloadShape_GivenArrayCollection_Throws() + { + var ex = await Assert + .That(() => SnapshotModelMapper.ValidateAggregatePayloadShape(typeof(ArrayCollectionAggregate))) + .Throws(); + await Assert.That(ex).IsNotNull(); + await Assert.That(ex!.Message).Contains(nameof(ArrayCollectionAggregate.Values)); + await Assert.That(ex.Message).Contains("EventStoreList"); + } + + [Test] + public async Task ValidateAggregatePayloadShape_GivenIReadOnlyListCollection_Throws() + { + var ex = await Assert + .That(() => SnapshotModelMapper.ValidateAggregatePayloadShape(typeof(ReadOnlyListCollectionAggregate))) + .Throws(); + await Assert.That(ex).IsNotNull(); + await Assert.That(ex!.Message).Contains(nameof(ReadOnlyListCollectionAggregate.Values)); + await Assert.That(ex.Message).Contains("EventStoreSet"); + } + + [Test] + public async Task ValidateAggregatePayloadShape_GivenUriProperty_DoesNotThrow() + { + await Assert + .That(() => SnapshotModelMapper.ValidateAggregatePayloadShape(typeof(UriAggregate))) + .ThrowsNothing(); + } + + [Test] + public async Task Rewrite_GivenScalarEqualsPrimitive_RewritesToPrimitiveComparison() + { + // Arrange + Expression> whereClause = model => model.Email == "updated@test.com"; + + // Act + var rewritten = SnapshotPredicateRewriter.Rewrite(whereClause, nameof(ScalarHolder)); + + // Assert + var binaryExpression = rewritten.Body as BinaryExpression; + await Assert.That(binaryExpression).IsNotNull(); + await Assert.That(binaryExpression!.NodeType).IsEqualTo(ExpressionType.Equal); + await Assert.That(binaryExpression.Left.Type).IsEqualTo(typeof(string)); + await Assert.That(binaryExpression.Right.Type).IsEqualTo(typeof(string)); + } + + [Test] + public async Task Rewrite_GivenAggregateTypeComparison_FoldsToConstant() + { + // Arrange + Expression> whereClause = model => + model.AggregateType == nameof(UriAggregate) && model.BlobUri != null; + + // Act + var rewritten = SnapshotPredicateRewriter.Rewrite(whereClause, nameof(UriAggregate)); + + // Assert + var binaryExpression = (BinaryExpression)rewritten.Body; + var aggregateTypeComparison = (BinaryExpression)binaryExpression.Left; + await Assert.That(aggregateTypeComparison.Left).IsTypeOf(); + } + + [Test] + public async Task Rewrite_GivenInvariantCasing_NormalizesToTranslatableOverload() + { +#pragma warning disable CA1308 // Normalize strings to uppercase +#pragma warning disable CA1862 // Use the 'StringComparison' method overloads + // Arrange + Expression> whereClause = model => model.Name.ToLowerInvariant() == "value"; + + // Act + var rewritten = SnapshotPredicateRewriter.Rewrite(whereClause, nameof(UriAggregate)); +#pragma warning restore CA1862 // Use the 'StringComparison' method overloads +#pragma warning restore CA1308 // Normalize strings to uppercase + + // Assert + var binaryExpression = (BinaryExpression)rewritten.Body; + var methodCall = (MethodCallExpression)binaryExpression.Left; + await Assert.That(methodCall.Method.Name).IsEqualTo(nameof(string.ToLower)); + } + + [Test] + public async Task EnsureSupportedOrderByExpression_GivenScalarInnerMemberOrdering_Throws() + { + // Arrange + var query = Array.Empty().AsQueryable().OrderBy(model => model.Email.Value); + + // Act & Assert + var exception = await Assert + .That(() => SnapshotPredicateRewriter.EnsureSupportedOrderByExpression(query.Expression)) + .Throws(); + + await Assert.That(exception!.Message).Contains(nameof(ScalarEmail.Value)); + } + + [Test] + public async Task ValidateAggregatePayloadShape_GivenOpaqueReadOnlyCollection_DoesNotThrow() + { + await Assert + .That(() => SnapshotModelMapper.ValidateAggregatePayloadShape(typeof(OpaqueMemberAggregate))) + .ThrowsNothing(); + } + + [Test] + public async Task ValidateAggregatePayloadShape_GivenReadOnlyComplexMemberOnValueType_Throws() + { + var exception = await Assert + .That(() => SnapshotModelMapper.ValidateAggregatePayloadShape(typeof(ReadOnlyValueTypeMemberAggregate))) + .Throws(); + + await Assert.That(exception!.Message).Contains(nameof(ReadOnlyStructHolder.Mirror)); + await Assert.That(exception.Message).Contains("writeable"); + } + + [Test] + public async Task ValidateAggregatePayloadShape_GivenReadOnlyComplexCollectionMemberOnValueType_Throws() + { + var exception = await Assert + .That(() => + SnapshotModelMapper.ValidateAggregatePayloadShape(typeof(ReadOnlyValueTypeCollectionMemberAggregate)) + ) + .Throws(); + + await Assert.That(exception!.Message).Contains(nameof(ReadOnlyCollectionHolder.Items)); + } + + [Test] + public async Task ValidateAggregatePayloadShape_GivenSettableComplexMemberOnValueType_DoesNotThrow() + { + await Assert + .That(() => SnapshotModelMapper.ValidateAggregatePayloadShape(typeof(SettableValueTypeMemberAggregate))) + .ThrowsNothing(); + } + + sealed class ScalarHolder + { + public ScalarEmail Email { get; init; } = new("default@test.com"); + } + + sealed class OpaqueMemberAggregate + { + [EFOpaque] + public IReadOnlyList Values { get; init; } = []; + } + + sealed class ReadOnlyValueTypeMemberAggregate + { + public ReadOnlyStructHolder Holder { get; init; } + } + + sealed class ReadOnlyValueTypeCollectionMemberAggregate + { + public ReadOnlyCollectionHolder Holder { get; init; } + } + + sealed class SettableValueTypeMemberAggregate + { + public SettableStructHolder Holder { get; init; } + } + + readonly struct ReadOnlyStructHolder + { +#pragma warning disable IDE0051 // Remove unused private members + ReadOnlyStructHolder(ValueTypeMemberInfo mirror) => Mirror = mirror; +#pragma warning restore IDE0051 // Remove unused private members + + public ValueTypeMemberInfo Mirror { get; } + } + + readonly struct ReadOnlyCollectionHolder + { +#pragma warning disable IDE0051 // Remove unused private members + ReadOnlyCollectionHolder(EventStoreList items) => Items = items; +#pragma warning restore IDE0051 // Remove unused private members + + public EventStoreList Items { get; } + } + + readonly struct SettableStructHolder + { + public ValueTypeMemberInfo Mirror { get; init; } + } + + sealed class ValueTypeMemberInfo + { + public string? Name { get; set; } + } + + sealed class UriAggregate : IAggregate + { + public string AggregateType => nameof(UriAggregate); + + public AggregateDetails Details { get; init; } = new(); + + public Uri BlobUri { get; init; } = new("/", UriKind.Relative); + + public string Name { get; init; } = string.Empty; + + public IReadOnlyList GetUnsavedEvents() => []; + + public bool HasUnsavedEvents() => false; + + public IEnumerable GetRegisteredEventTypes() => []; + + public bool CanApplyEvent(object aggregateEvent) => false; + + public void ClearUnsavedEvents(int? upToVersion = null) { } + + void IAggregate.ApplyEvent(object @event, EventMetadata metadata) { } + } + + sealed class SupportedCollectionAggregate : IAggregate + { + public string AggregateType => nameof(SupportedCollectionAggregate); + + public AggregateDetails Details { get; init; } = new(); + + public EventStoreList IntValues { get; init; } = new(); + + public EventStoreSet StringValues { get; init; } = new(); + + public IReadOnlyList GetUnsavedEvents() => []; + + public bool HasUnsavedEvents() => false; + + public IEnumerable GetRegisteredEventTypes() => []; + + public bool CanApplyEvent(object aggregateEvent) => false; + + public void ClearUnsavedEvents(int? upToVersion = null) { } + + void IAggregate.ApplyEvent(object @event, EventMetadata metadata) { } + } + + sealed class ArrayCollectionAggregate : IAggregate + { + public string AggregateType => nameof(ArrayCollectionAggregate); + + public AggregateDetails Details { get; init; } = new(); + + public int[] Values { get; init; } = []; + + public IReadOnlyList GetUnsavedEvents() => []; + + public bool HasUnsavedEvents() => false; + + public IEnumerable GetRegisteredEventTypes() => []; + + public bool CanApplyEvent(object aggregateEvent) => false; + + public void ClearUnsavedEvents(int? upToVersion = null) { } + + void IAggregate.ApplyEvent(object @event, EventMetadata metadata) { } + } + + sealed class ReadOnlyListCollectionAggregate : IAggregate + { + public string AggregateType => nameof(ReadOnlyListCollectionAggregate); + + public AggregateDetails Details { get; init; } = new(); + + public IReadOnlyList Values { get; init; } = []; + + public IReadOnlyList GetUnsavedEvents() => []; + + public bool HasUnsavedEvents() => false; + + public IEnumerable GetRegisteredEventTypes() => []; + + public bool CanApplyEvent(object aggregateEvent) => false; + + public void ClearUnsavedEvents(int? upToVersion = null) { } + + void IAggregate.ApplyEvent(object @event, EventMetadata metadata) { } + } +} + +[Scalar( + GenerateJsonConverter = false, + GenerateComparable = false, + GenerateComparisonOperators = false, + GenerateEnumProperties = false, + GenerateImplicitFromPrimitive = false, + GenerateImplicitToPrimitive = false, + GenerateEmpty = false +)] +readonly partial record struct ScalarEmail +{ + public string Value { get; } + + public ScalarEmail(string value) => Value = value; + + public static bool operator ==(ScalarEmail left, string right) => left.Value == right; + + public static bool operator !=(ScalarEmail left, string right) => !(left == right); + + public static implicit operator string(ScalarEmail value) => value.Value; +} diff --git a/src/tests/EventSourcing.UnitTests/EventHistoryExtensionsTests.cs b/src/tests/EventSourcing.UnitTests/EventHistoryExtensionsTests.cs index 09ae890a..8ab9d788 100644 --- a/src/tests/EventSourcing.UnitTests/EventHistoryExtensionsTests.cs +++ b/src/tests/EventSourcing.UnitTests/EventHistoryExtensionsTests.cs @@ -1,6 +1,8 @@ using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; using Purview.EventSourcing.Aggregates.Test; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing; @@ -34,7 +36,7 @@ CancellationToken cancellationToken // Assert await Assert.That(response.Results).Count().IsEqualTo(2); - await Assert.That(response.Results.Select(m => m.AggregateVersion)).IsEquivalentTo([2, 3]); + await Assert.That(response.Results.Select(m => m.AggregateVersion)).IsEquivalentTo([2L, 3L]); await Assert.That(response.ContinuationToken).IsNull(); } @@ -166,7 +168,7 @@ CancellationToken cancellationToken await Assert.That(first.Results).Count().IsEqualTo(2); await Assert.That(first.ContinuationToken).IsEqualTo("k2"); await Assert.That(second.Results).Count().IsEqualTo(2); - await Assert.That(second.Results.Select(m => m.AggregateVersion)).IsEquivalentTo([3, 4]); + await Assert.That(second.Results.Select(m => m.AggregateVersion)).IsEquivalentTo([3L, 4L]); await Assert.That(second.ContinuationToken).IsNull(); } @@ -200,7 +202,7 @@ await Assert.That(() => store.GetEventHistoryAsync("agg-1", request)!).Throws GetEventRangeAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken ) { @@ -258,46 +260,43 @@ public Task CreateAsync( CancellationToken cancellationToken = default ) => throw new NotImplementedException(); - public Task GetOrCreateAsync( + public Task> GetOrCreateAsync( string? aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => throw new NotImplementedException(); - public Task GetAsync( + public Task> GetAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => throw new NotImplementedException(); - public Task GetAtAsync( + public Task> GetAtAsync( string aggregateId, - int version, + long version, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => throw new NotImplementedException(); - public Task> SaveAsync( + public Task, AggregateSaveFailure>> SaveAsync( TestAggregate aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => throw new NotImplementedException(); - public Task IsDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) => - throw new NotImplementedException(); - - public Task GetDeletedAsync( + public Task> GetDeletedAsync( string aggregateId, CancellationToken cancellationToken = default ) => throw new NotImplementedException(); - public Task DeleteAsync( + public Task, AggregateDeleteFailure>> DeleteAsync( TestAggregate aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => throw new NotImplementedException(); - public Task RestoreAsync( + public Task, AggregateRestoreFailure>> RestoreAsync( TestAggregate aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -315,8 +314,10 @@ public async IAsyncEnumerable GetAggregateIdsAsync( yield break; } - public Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) => - throw new NotImplementedException(); + public Task ExistsAsync( + string aggregateId, + CancellationToken cancellationToken = default + ) => throw new NotImplementedException(); public TestAggregate FulfilRequirements(TestAggregate aggregate) => aggregate; } diff --git a/src/tests/EventSourcing.UnitTests/EventSourcing.UnitTests.csproj b/src/tests/EventSourcing.UnitTests/EventSourcing.UnitTests.csproj index 4e7a6b89..ac2b7764 100644 --- a/src/tests/EventSourcing.UnitTests/EventSourcing.UnitTests.csproj +++ b/src/tests/EventSourcing.UnitTests/EventSourcing.UnitTests.csproj @@ -1,5 +1,8 @@  + + diff --git a/src/tests/EventSourcing.UnitTests/EventStoreExtensionsMirrorTests.cs b/src/tests/EventSourcing.UnitTests/EventStoreExtensionsMirrorTests.cs new file mode 100644 index 00000000..b3b1c991 --- /dev/null +++ b/src/tests/EventSourcing.UnitTests/EventStoreExtensionsMirrorTests.cs @@ -0,0 +1,76 @@ +using System.Reflection; + +namespace Purview.EventSourcing; + +/// +/// Guards the mirror between the typed and facade extension sets. +/// +/// +/// The facade set is generated from the typed one, so these assert the property that matters to a caller - +/// that the two surfaces agree - rather than asserting how the generator produced it. They would equally +/// catch drift if either set were hand-written again. +/// +public class EventStoreExtensionsMirrorTests +{ + static MethodInfo[] PublicExtensions(Type type) => + [.. type.GetMethods(BindingFlags.Public | BindingFlags.Static | BindingFlags.DeclaredOnly)]; + + // Signature without the receiver: the receiver is the one thing the two sets differ by. + static string Signature(MethodInfo method) => + $"{method.Name}({string.Join(", ", method.GetParameters().Skip(1).Select(p => p.ParameterType.ToString()))})"; + + [Test] + public async Task FacadeExtensions_ForEveryTypedExtension_ExposeTheSameSignature() + { + var typed = PublicExtensions(typeof(IEventStoreCoreExtensions)) + .Select(Signature) + .ToHashSet(StringComparer.Ordinal); + var facade = PublicExtensions(typeof(IEventStoreExtensions)) + .Select(Signature) + .ToHashSet(StringComparer.Ordinal); + + var missing = typed.Except(facade, StringComparer.Ordinal).ToArray(); + + await Assert.That(missing).IsEmpty().Because($"the facade is missing: {string.Join(", ", missing)}"); + } + + [Test] + public async Task FacadeExtensions_BeyondTheTypedSet_AreOnlyTheReceiverlessTransactionHelpers() + { + var typed = PublicExtensions(typeof(IEventStoreCoreExtensions)) + .Select(Signature) + .ToHashSet(StringComparer.Ordinal); + var extra = PublicExtensions(typeof(IEventStoreExtensions)) + .Where(method => !typed.Contains(Signature(method))) + .Select(static method => method.Name) + .Distinct(StringComparer.Ordinal) + .ToArray(); + + // Enlist has non-generic overloads that start an empty transaction; there is no typed equivalent + // because the typed receiver already fixes an aggregate type. + await Assert + .That(extra) + .IsEquivalentTo(new[] { nameof(IEventStoreExtensions.Enlist) }) + .Because($"unexpected facade-only members: {string.Join(", ", extra)}"); + } + + [Test] + public async Task TypedExtensions_TakeNoObjectTypedIdentifiers() + { + // The object-id overloads were removed in the API cleanup; they silently accepted anything and + // deferred the failure to ToString(). + var offenders = PublicExtensions(typeof(IEventStoreCoreExtensions)) + .Concat(PublicExtensions(typeof(IEventStoreExtensions))) + .Where(static method => + method + .GetParameters() + .Any(static p => + p.ParameterType == typeof(object) && p.Name?.Contains("Id", StringComparison.Ordinal) == true + ) + ) + .Select(Signature) + .ToArray(); + + await Assert.That(offenders).IsEmpty().Because(string.Join(", ", offenders)); + } +} diff --git a/src/tests/EventSourcing.UnitTests/EventStoreTransactionTests.cs b/src/tests/EventSourcing.UnitTests/EventStoreTransactionTests.cs index a7c5a519..27f42804 100644 --- a/src/tests/EventSourcing.UnitTests/EventStoreTransactionTests.cs +++ b/src/tests/EventSourcing.UnitTests/EventStoreTransactionTests.cs @@ -2,7 +2,9 @@ using System.Data.Common; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Test; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.Internal; +using Purview.Results; using ValidationFailure = Purview.EventSourcing.Validation.ValidationFailure; using ValidationResult = Purview.EventSourcing.Validation.ValidationResult; @@ -48,7 +50,7 @@ public async Task CommitAsync_GivenSingleAggregate_CallsSaveAsyncOnEventStore(Ca var eventStore = IEventStore.Mock(); eventStore .SaveAsync(Any(), Any(), Any()) - .Returns(new SaveResult(aggregate, new ValidationResult(), true, false)); + .Returns(new SaveOutcome(aggregate, SaveOutcomeKind.Written)); await using EventStoreTransaction transaction = new(); transaction.Enlist(aggregate, eventStore); @@ -81,12 +83,12 @@ public async Task CommitAsync_GivenMultipleAggregates_SavesAllInOrder(Cancellati var store1 = IEventStore.Mock(); store1 .SaveAsync(Any(), Any(), Any()) - .Returns(new SaveResult(agg1, new ValidationResult(), true, false)); + .Returns(new SaveOutcome(agg1, SaveOutcomeKind.Written)); var store2 = IEventStore.Mock(); store2 .SaveAsync(Any(), Any(), Any()) - .Returns(new SaveResult(agg2, new ValidationResult(), true, false)); + .Returns(new SaveOutcome(agg2, SaveOutcomeKind.Written)); await using EventStoreTransaction transaction = new(); transaction.Enlist(agg1, store1); @@ -120,12 +122,12 @@ CancellationToken cancellationToken var store1 = IEventStore.Mock(); store1 .SaveAsync(Any(), Any(), Any()) - .Returns((agg, _, _) => new SaveResult(agg, new ValidationResult(), true, false)); + .Returns((agg, _, _) => new SaveOutcome(agg, SaveOutcomeKind.Written)); var store2 = IEventStore.Mock(); store2 .SaveAsync(Any(), Any(), Any()) - .Returns((agg, _, _) => new SaveResult(agg, new ValidationResult(), true, false)); + .Returns((agg, _, _) => new SaveOutcome(agg, SaveOutcomeKind.Written)); await using EventStoreTransaction transaction = new(correlationId); transaction.Enlist(agg1, store1); @@ -196,7 +198,7 @@ public async Task CommitAsync_CalledTwice_ThrowsInvalidOperationException(Cancel var eventStore = IEventStore.Mock(); eventStore .SaveAsync(Any(), Any(), Any()) - .Returns(new SaveResult(aggregate, new ValidationResult(), true, false)); + .Returns(new SaveOutcome(aggregate, SaveOutcomeKind.Written)); await using EventStoreTransaction transaction = new(); transaction.Enlist(aggregate, eventStore); @@ -218,7 +220,7 @@ public async Task Enlist_AfterCommit_ThrowsInvalidOperationException(Cancellatio var eventStore = IEventStore.Mock(); eventStore .SaveAsync(Any(), Any(), Any()) - .Returns(new SaveResult(aggregate, new ValidationResult(), true, false)); + .Returns(new SaveOutcome(aggregate, SaveOutcomeKind.Written)); await using EventStoreTransaction transaction = new(); transaction.Enlist(aggregate, eventStore); @@ -341,9 +343,7 @@ CancellationToken cancellationToken var nonTransactionalStore = IEventStore.Mock(); nonTransactionalStore .SaveAsync(Any(), Any(), Any()) - .Returns( - (aggregate, _, _) => new SaveResult(aggregate, new ValidationResult(), true, false) - ); + .Returns((aggregate, _, _) => new SaveOutcome(aggregate, SaveOutcomeKind.Written)); await using EventStoreTransaction transaction = new("mixed"); transaction.Enlist(agg1, (IEventStore)transactionalStore); @@ -425,7 +425,7 @@ CancellationToken cancellationToken FakeTransactionalEventStore successfulStore = new("sqlserver:primary"); FakeTransactionalEventStore failingStore = new( "sqlserver:primary", - new SaveBehavior(false, false, new InvalidOperationException("boom")) + new SaveBehavior(SaveOutcomeKind.Written, new InvalidOperationException("boom")) ); await using EventStoreTransaction transaction = new("rollback"); @@ -504,7 +504,7 @@ public async Task CommitAsync_WhenSaveReturnsNotSaved_StopsAndReportsFailure(Can var store1 = IEventStore.Mock(); store1 .SaveAsync(Any(), Any(), Any()) - .Returns(new SaveResult(agg1, validationResult, false, false)); + .Returns(AggregateSaveFailure.Failure>(new AggregateInvalid(validationResult))); var store2 = IEventStore.Mock(); @@ -536,12 +536,12 @@ public async Task CommitAsync_WhenSaveSkipped_ContinuesToNextAggregate(Cancellat var store1 = IEventStore.Mock(); store1 .SaveAsync(Any(), Any(), Any()) - .Returns(new SaveResult(agg1, new ValidationResult(), false, true)); + .Returns(new SaveOutcome(agg1, SaveOutcomeKind.NoChanges)); var store2 = IEventStore.Mock(); store2 .SaveAsync(Any(), Any(), Any()) - .Returns(new SaveResult(agg2, new ValidationResult(), true, false)); + .Returns(new SaveOutcome(agg2, SaveOutcomeKind.Written)); await using EventStoreTransaction transaction = new(); transaction.Enlist(agg1, store1); @@ -571,7 +571,7 @@ CancellationToken cancellationToken var eventStore = IEventStore.Mock(); eventStore .SaveAsync(Any(), Any(), Any()) - .Returns(new SaveResult(aggregate, new ValidationResult(), true, false)); + .Returns(new SaveOutcome(aggregate, SaveOutcomeKind.Written)); var originalDefaultCorrelationId = EventStoreOperationContext.DefaultContext().CorrelationId; @@ -605,14 +605,18 @@ public async Task TransactionResult_CompletedWithoutError_ReturnsFalseWhenAggreg CancellationToken cancellationToken ) { - // Arrange — first aggregate save returns Saved=false, Skipped=false (failure) + // Arrange — the first aggregate's save fails var agg = TestHelpers.Aggregate(clearEvents: false); agg.Increment(); var store = IEventStore.Mock(); store .SaveAsync(Any(), Any(), Any()) - .Returns(new SaveResult(agg, new ValidationResult(), false, false)); + .Returns( + AggregateSaveFailure.Failure>( + new AggregateLocked(agg.AggregateType, agg.Id()) + ) + ); await using EventStoreTransaction transaction = new(); transaction.Enlist(agg, store); @@ -639,7 +643,7 @@ CancellationToken cancellationToken var eventStore = IEventStore.Mock(); eventStore .SaveAsync(Any(), Any(), Any()) - .Returns(new SaveResult(aggregate, new ValidationResult(), true, false)); + .Returns(new SaveOutcome(aggregate, SaveOutcomeKind.Written)); await using EventStoreTransaction transaction = new("transaction-correlation"); transaction.Enlist(aggregate, eventStore, customContext); @@ -686,14 +690,14 @@ CancellationToken cancellationToken } } - sealed record SaveBehavior(bool Saved, bool Skipped, Exception? Exception = null); + sealed record SaveBehavior(SaveOutcomeKind Kind, Exception? Exception = null); sealed class FakeTransactionalEventStore(string transactionBoundaryKey, SaveBehavior? behavior = null) : ITransactionalEventStore, IEventStore, IEventStoreImplementationAccessor { - readonly SaveBehavior _behavior = behavior ?? new SaveBehavior(true, false); + readonly SaveBehavior _behavior = behavior ?? new SaveBehavior(SaveOutcomeKind.Written); public int SaveAsyncCalls { get; private set; } @@ -736,7 +740,7 @@ public Task> SaveInTransactionAsync( : Task.FromResult(CreateOperation(aggregate)); } - public Task> SaveAsync( + public Task, AggregateSaveFailure>> SaveAsync( TestAggregate aggregate, EventStoreOperationContext? operationContext, CancellationToken _ = default @@ -751,14 +755,15 @@ public Task> SaveAsync( : Task.FromResult(CreateOperation(aggregate).Result); } - Task> IEventStore.SaveAsync( + Task, AggregateSaveFailure>> IEventStore.SaveAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken ) { return aggregate is TestAggregate testAggregate && typeof(T) == typeof(TestAggregate) - ? (Task>)(object)SaveAsync(testAggregate, operationContext, cancellationToken) + ? (Task, AggregateSaveFailure>>) + (object)SaveAsync(testAggregate, operationContext, cancellationToken) : throw new NotSupportedException(); } @@ -772,41 +777,38 @@ IEventStoreCore IEventStoreImplementationAccessor.GetEventStore() Task IEventStore.CreateAsync(string? aggregateId, CancellationToken _) => throw new NotSupportedException(); - Task IEventStore.GetOrCreateAsync( + Task> IEventStore.GetOrCreateAsync( string? aggregateId, EventStoreOperationContext? operationContext, CancellationToken _ ) where T : class => throw new NotSupportedException(); - Task IEventStore.GetAsync( + Task> IEventStore.GetAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken _ ) where T : class => throw new NotSupportedException(); - Task IEventStore.GetAtAsync( + Task> IEventStore.GetAtAsync( string aggregateId, - int version, + long version, EventStoreOperationContext? operationContext, CancellationToken _ ) where T : class => throw new NotSupportedException(); - Task IEventStore.IsDeletedAsync(string aggregateId, CancellationToken _) => - throw new NotSupportedException(); - - Task IEventStore.GetDeletedAsync(string aggregateId, CancellationToken _) + Task> IEventStore.GetDeletedAsync(string aggregateId, CancellationToken _) where T : class => throw new NotSupportedException(); - Task IEventStore.DeleteAsync( + Task, AggregateDeleteFailure>> IEventStore.DeleteAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken _ ) => throw new NotSupportedException(); - Task IEventStore.RestoreAsync( + Task, AggregateRestoreFailure>> IEventStore.RestoreAsync( T aggregate, EventStoreOperationContext? operationContext, CancellationToken _ @@ -821,21 +823,21 @@ [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken _ yield break; } - Task IEventStore.ExistsAsync(string aggregateId, CancellationToken _) => + Task IEventStore.ExistsAsync(string aggregateId, CancellationToken _) => throw new NotSupportedException(); T IEventStore.FulfilRequirements(T aggregate) => aggregate; IAsyncEnumerable<(EventRecord EventRecord, string EventType)> IEventStore.GetEventRangeAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, CancellationToken cancellationToken ) => throw new NotSupportedException(); TransactionalSaveOperation CreateOperation(TestAggregate aggregate) => new( - new SaveResult(aggregate, new ValidationResult(), _behavior.Saved, _behavior.Skipped), + new SaveOutcome(aggregate, _behavior.Kind), _ => { AfterCommitCalls++; @@ -851,38 +853,37 @@ TransactionalSaveOperation CreateOperation(TestAggregate aggregat public Task CreateAsync(string? aggregateId = null, CancellationToken _ = default) => throw new NotSupportedException(); - public Task GetOrCreateAsync( + public Task> GetOrCreateAsync( string? aggregateId, EventStoreOperationContext? operationContext, CancellationToken _ = default ) => throw new NotSupportedException(); - public Task GetAsync( + public Task> GetAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken _ = default ) => throw new NotSupportedException(); - public Task GetAtAsync( + public Task> GetAtAsync( string aggregateId, - int version, + long version, EventStoreOperationContext? operationContext, CancellationToken _ = default ) => throw new NotSupportedException(); - public Task IsDeletedAsync(string aggregateId, CancellationToken _ = default) => - throw new NotSupportedException(); - - public Task GetDeletedAsync(string aggregateId, CancellationToken _ = default) => - throw new NotSupportedException(); + public Task> GetDeletedAsync( + string aggregateId, + CancellationToken _ = default + ) => throw new NotSupportedException(); - public Task DeleteAsync( + public Task, AggregateDeleteFailure>> DeleteAsync( TestAggregate aggregate, EventStoreOperationContext? operationContext, CancellationToken _ = default ) => throw new NotSupportedException(); - public Task RestoreAsync( + public Task, AggregateRestoreFailure>> RestoreAsync( TestAggregate aggregate, EventStoreOperationContext? operationContext, CancellationToken _ = default @@ -898,15 +899,15 @@ public async IAsyncEnumerable GetAggregateIdsAsync( yield break; } - public Task ExistsAsync(string aggregateId, CancellationToken _ = default) => + public Task ExistsAsync(string aggregateId, CancellationToken _ = default) => throw new NotSupportedException(); public TestAggregate FulfilRequirements(TestAggregate aggregate) => aggregate; public IAsyncEnumerable<(EventRecord EventRecord, string EventType)> GetEventRangeAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, CancellationToken cancellationToken = default ) => throw new NotSupportedException(); } diff --git a/src/tests/EventSourcing.UnitTests/ExistsStateTests.cs b/src/tests/EventSourcing.UnitTests/ExistsStateTests.cs deleted file mode 100644 index bd356eeb..00000000 --- a/src/tests/EventSourcing.UnitTests/ExistsStateTests.cs +++ /dev/null @@ -1,34 +0,0 @@ -namespace Purview.EventSourcing; - -public class ExistsStateTests -{ - [Test] - public async Task ImplicitBoolConversion_GivenExists_ReturnsTrue() - { - // Act - bool result = ExistsState.Exists; - - // Assert - await Assert.That(result).IsTrue(); - } - - [Test] - public async Task ImplicitBoolConversion_GivenDoesNotExist_ReturnsFalse() - { - // Act - bool result = ExistsState.DoesNotExist; - - // Assert - await Assert.That(result).IsFalse(); - } - - [Test] - public async Task ImplicitBoolConversion_GivenExistsInDeletedState_ReturnsTrue() - { - // Act - bool result = ExistsState.ExistsInDeletedState; - - // Assert - await Assert.That(result).IsTrue(); - } -} diff --git a/src/tests/EventSourcing.UnitTests/Failures/AggregateFailureTests.cs b/src/tests/EventSourcing.UnitTests/Failures/AggregateFailureTests.cs new file mode 100644 index 00000000..f393e636 --- /dev/null +++ b/src/tests/EventSourcing.UnitTests/Failures/AggregateFailureTests.cs @@ -0,0 +1,92 @@ +using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Aggregates.Persistence; +using ValidationFailure = Purview.EventSourcing.Validation.ValidationFailure; +using ValidationResult = Purview.EventSourcing.Validation.ValidationResult; + +namespace Purview.EventSourcing.Failures; + +// Guards the failure vocabulary itself: that each union converts its cases into a result, that the case +// survives the round trip, and that a success is not mistaken for a failure. The unions share leaf cases +// deliberately, so these also pin the union-receiver factory as the way shared cases are constructed. +public class AggregateFailureTests +{ + const string AggregateType = "order"; + const string AggregateId = "order-1"; + + [Test] + public async Task Failure_GivenNotFound_ReturnsReadFailureCarryingTheCase() + { + // Arrange + AggregateNotFound notFound = new(AggregateType, AggregateId); + + // Act + var result = AggregateReadFailure.Failure(notFound); + + // Assert + await Assert.That(result.IsFailure).IsTrue(); + await Assert.That(result.Error.Value).IsTypeOf(); + await Assert.That(((AggregateNotFound)result.Error.Value).AggregateId).IsEqualTo(AggregateId); + } + + [Test] + public async Task Failure_GivenConcurrencyConflict_CarriesBothVersions() + { + // Arrange + ConcurrencyConflict conflict = new(AggregateType, AggregateId, ExpectedVersion: 3, ActualVersion: 5); + + // Act + var result = AggregateSaveFailure.Failure(conflict); + + // Assert + await Assert.That(result.IsFailure).IsTrue(); + + var value = (ConcurrencyConflict)result.Error.Value; + await Assert.That(value.ExpectedVersion).IsEqualTo(3L); + await Assert.That(value.ActualVersion).IsEqualTo(5L); + } + + [Test] + public async Task Failure_GivenInvalidAggregate_CarriesTheValidationResult() + { + // Arrange + ValidationResult validationResult = new([new ValidationFailure("Name", "Name is required.")]); + + // Act + var result = AggregateSaveFailure.Failure(new AggregateInvalid(validationResult)); + + // Assert + await Assert.That(result.IsFailure).IsTrue(); + + var value = (AggregateInvalid)result.Error.Value; + await Assert.That(value.ValidationResult.IsValid).IsFalse(); + await Assert.That(value.ValidationResult.Failures.Length).IsEqualTo(1); + } + + [Test] + public async Task Success_GivenValue_IsNotAFailure() + { + // Act + var result = AggregateSaveFailure.Success("saved"); + + // Assert + await Assert.That(result.IsSuccess).IsTrue(); + await Assert.That(result.IsFailure).IsFalse(); + await Assert.That(result.Value).IsEqualTo("saved"); + } + + [Test] + [Arguments(SaveOutcomeKind.Written, true)] + [Arguments(SaveOutcomeKind.NoChanges, false)] + [Arguments(SaveOutcomeKind.AlreadyApplied, false)] + public async Task SaveOutcome_GivenKind_ReportsWhetherTheStreamWasWritten( + SaveOutcomeKind kind, + bool expectedWritten + ) + { + // Arrange & Act + SaveOutcome outcome = new(new(), kind); + + // Assert + await Assert.That(outcome.Written).IsEqualTo(expectedWritten); + } +} diff --git a/src/tests/EventSourcing.UnitTests/IEventStoreExtensionsEnlistTests.cs b/src/tests/EventSourcing.UnitTests/IEventStoreExtensionsEnlistTests.cs index 9a70159f..ab0e1c57 100644 --- a/src/tests/EventSourcing.UnitTests/IEventStoreExtensionsEnlistTests.cs +++ b/src/tests/EventSourcing.UnitTests/IEventStoreExtensionsEnlistTests.cs @@ -1,6 +1,5 @@ using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Test; -using ValidationResult = Purview.EventSourcing.Validation.ValidationResult; namespace Purview.EventSourcing; @@ -27,7 +26,7 @@ public async Task Enlist_GivenSingleAggregate_ReturnsPreparedTransaction(Cancell var eventStore = IEventStore.Mock(); eventStore .SaveAsync(Any(), Any(), Any()) - .Returns(new SaveResult(aggregate, new ValidationResult(), true, false)); + .Returns(new SaveOutcome(aggregate, SaveOutcomeKind.Written)); // Act await using var transaction = eventStore.Enlist(aggregate); @@ -54,7 +53,7 @@ public async Task Enlist_GivenMultipleAggregates_EnlistsAllInTransaction(Cancell var eventStore = IEventStore.Mock(); eventStore .SaveAsync(Any(), Any(), Any()) - .Returns(static (a, _, _) => new SaveResult(a, new ValidationResult(), true, false)); + .Returns(static (a, _, _) => new SaveOutcome(a, SaveOutcomeKind.Written)); // Act await using var transaction = eventStore.Enlist(agg1, agg2); @@ -82,7 +81,7 @@ public async Task Enlist_WithCorrelationId_PropagatesCorrelationIdToTransaction( var eventStore = IEventStore.Mock(); eventStore .SaveAsync(Any(), Any(), Any()) - .Returns(new SaveResult(aggregate, new ValidationResult(), true, false)); + .Returns(new SaveOutcome(aggregate, SaveOutcomeKind.Written)); // Act await using var transaction = eventStore.Enlist(correlationId, aggregate); @@ -136,7 +135,7 @@ CancellationToken cancellationToken var eventStore = IEventStore.Mock(); eventStore .SaveAsync(Any(), Any(), Any()) - .Returns(new SaveResult(aggregate, new ValidationResult(), true, false)); + .Returns(new SaveOutcome(aggregate, SaveOutcomeKind.Written)); // Act await using var transaction = eventStore.Enlist(context, aggregate); @@ -226,7 +225,7 @@ CancellationToken cancellationToken var eventStore = IEventStore.Mock(); eventStore .SaveAsync(Any(), Any(), Any()) - .Returns(static (a, _, _) => new SaveResult(a, new ValidationResult(), true, false)); + .Returns(static (a, _, _) => new SaveOutcome(a, SaveOutcomeKind.Written)); // Act await using var transaction = eventStore.Enlist(context, agg1, agg2); diff --git a/src/tests/EventSourcing.UnitTests/InMemory/Events/InMemoryEventStoreConcurrencyTests.cs b/src/tests/EventSourcing.UnitTests/InMemory/Events/InMemoryEventStoreConcurrencyTests.cs index 97ef9686..8ff24726 100644 --- a/src/tests/EventSourcing.UnitTests/InMemory/Events/InMemoryEventStoreConcurrencyTests.cs +++ b/src/tests/EventSourcing.UnitTests/InMemory/Events/InMemoryEventStoreConcurrencyTests.cs @@ -1,6 +1,7 @@ using Microsoft.Extensions.DependencyInjection; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; +using Purview.EventSourcing.Failures; namespace Purview.EventSourcing.InMemory.Events; @@ -36,7 +37,7 @@ static ServiceProvider CreateProvider() static EventStoreOperationContext CreateContext() => new() { RequiresValidPrincipalIdentifier = false }; [Test] - public async Task SaveAsync_GivenConflictingAggregateVersion_ThrowsConcurrencyException() + public async Task SaveAsync_GivenConflictingAggregateVersion_ReturnsConcurrencyConflict() { // Arrange using var provider = CreateProvider(); @@ -56,10 +57,12 @@ public async Task SaveAsync_GivenConflictingAggregateVersion_ThrowsConcurrencyEx TestAggregate staleWriter = new() { Details = { Id = "agg-1" } }; staleWriter.Increment(3); - // Act & Assert - await Assert - .That(async () => await eventStore.SaveAsync(staleWriter, context)) - .Throws(); + // Act + var result = await eventStore.SaveAsync(staleWriter, context); + + // Assert + await Assert.That(result.IsFailure).IsTrue(); + await Assert.That(result.Error is ConcurrencyConflict).IsTrue(); } [Test] @@ -78,7 +81,7 @@ public async Task SaveAsync_GivenSequentialSaves_Succeeds() var result = await eventStore.SaveAsync(aggregate, context); // Assert - await Assert.That(result.Saved).IsTrue(); + await Assert.That(result.IsSuccess && result.Value.Written).IsTrue(); await Assert.That(aggregate.Details.SavedVersion).IsEqualTo(2); } } diff --git a/src/tests/EventSourcing.UnitTests/InMemory/Events/InMemoryEventStoreMetricsTests.cs b/src/tests/EventSourcing.UnitTests/InMemory/Events/InMemoryEventStoreMetricsTests.cs new file mode 100644 index 00000000..90af857c --- /dev/null +++ b/src/tests/EventSourcing.UnitTests/InMemory/Events/InMemoryEventStoreMetricsTests.cs @@ -0,0 +1,142 @@ +using System.Diagnostics.Metrics; +using Microsoft.Extensions.DependencyInjection; +using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Aggregates.Events; + +namespace Purview.EventSourcing.InMemory.Events; + +/// +/// Guards that a save records the shared event-store instruments. +/// +/// +/// Listens to the real rather than a stub, because instrument and tag names are the +/// public contract a dashboard is built against: a test against a mock would not notice them changing. +/// +// A MeterListener observes the whole process, so two of these running together would each record the +// other's measurements. +[NotInParallel] +public sealed class InMemoryEventStoreMetricsTests +{ + const string MeterName = "Purview.EventSourcing"; + + [EventContract] + sealed record ValueIncremented + { + public static int SchemaVersion => 1; + + public EventMetadata Metadata { get; init; } + + public int Amount { get; set; } + } + + sealed class TestAggregate : AggregateBase + { + public int Value { get; private set; } + + protected override void RegisterEvents() => Register(ev => Value += ev.Amount); + + public void Increment(int amount) => RecordAndApply(new ValueIncremented { Amount = amount }); + } + + sealed record Measurement(string Instrument, double Value, IReadOnlyDictionary Tags); + + static async Task> RecordAsync(Func action) + { + List measurements = []; + + ServiceCollection services = new(); + services.AddLogging(); + services.AddMetrics(); + services.AddEventSourcing().AddInMemoryEventStore(); + + using var provider = services.BuildServiceProvider(); + + using MeterListener listener = new() + { + InstrumentPublished = (instrument, l) => + { + if (instrument.Meter.Name == MeterName) + l.EnableMeasurementEvents(instrument); + }, + }; + + void Record( + Instrument instrument, + TValue value, + ReadOnlySpan> tags, + object? _ + ) + where TValue : struct + { + Dictionary tagMap = []; + foreach (var tag in tags) + tagMap[tag.Key] = tag.Value?.ToString(); + + lock (measurements) + measurements.Add( + new Measurement( + instrument.Name, + Convert.ToDouble(value, System.Globalization.CultureInfo.InvariantCulture), + tagMap + ) + ); + } + + listener.SetMeasurementEventCallback(Record); + listener.SetMeasurementEventCallback(Record); + listener.SetMeasurementEventCallback(Record); + listener.Start(); + + await action(provider.GetRequiredService()); + + listener.Dispose(); + + return measurements; + } + + [Test] + public async Task SaveAsync_GivenAWrite_RecordsDurationAndEventCount() + { + var measurements = await RecordAsync(async store => + { + var aggregate = await store.CreateAsync("metrics-1"); + aggregate.Increment(1); + aggregate.Increment(2); + + await store.SaveAsync( + aggregate, + new EventStoreOperationContext { RequiresValidPrincipalIdentifier = false } + ); + }); + + var save = measurements.SingleOrDefault(m => m.Instrument == "purview.eventsourcing.save.duration"); + await Assert.That(save).IsNotNull(); + await Assert.That(save!.Tags["outcome"]).IsEqualTo("written"); + await Assert.That(save.Tags["aggregate.type"]).IsEqualTo(nameof(TestAggregate)); + + var appended = measurements.SingleOrDefault(m => m.Instrument == "purview.eventsourcing.events.appended"); + await Assert.That(appended).IsNotNull(); + await Assert.That(appended!.Value).IsEqualTo(2d); + } + + [Test] + public async Task SaveAsync_GivenNothingToSave_RecordsNoChangesAndNoEventCount() + { + var measurements = await RecordAsync(async store => + { + var aggregate = await store.CreateAsync("metrics-2"); + + await store.SaveAsync( + aggregate, + new EventStoreOperationContext { RequiresValidPrincipalIdentifier = false } + ); + }); + + var save = measurements.SingleOrDefault(m => m.Instrument == "purview.eventsourcing.save.duration"); + await Assert.That(save).IsNotNull(); + await Assert.That(save!.Tags["outcome"]).IsEqualTo("no-changes"); + + // An empty save appended nothing, so the counter must stay silent rather than record a zero. + await Assert.That(measurements.Any(m => m.Instrument == "purview.eventsourcing.events.appended")).IsFalse(); + } +} diff --git a/src/tests/EventSourcing.UnitTests/InMemory/Events/InMemoryEventStorePrincipalTests.cs b/src/tests/EventSourcing.UnitTests/InMemory/Events/InMemoryEventStorePrincipalTests.cs new file mode 100644 index 00000000..81027bba --- /dev/null +++ b/src/tests/EventSourcing.UnitTests/InMemory/Events/InMemoryEventStorePrincipalTests.cs @@ -0,0 +1,104 @@ +using System.Security.Claims; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.DependencyInjection.Extensions; +using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Aggregates.Events; + +namespace Purview.EventSourcing.InMemory.Events; + +/// +/// Guards that a save records the user from the registered . +/// +/// +/// The accessor exists because the ambient is null in a web host - +/// ASP.NET Core populates neither it nor - so every save recorded a +/// null user, and the default RequiresValidPrincipalIdentifier could not be satisfied at all. +/// +public sealed class InMemoryEventStorePrincipalTests +{ + const string UserId = "user-42"; + + [EventContract] + sealed record ValueIncremented + { + public static int SchemaVersion => 1; + + public EventMetadata Metadata { get; init; } + + public int Amount { get; set; } + } + + sealed class TestAggregate : AggregateBase + { + public int Value { get; private set; } + + protected override void RegisterEvents() => Register(ev => Value += ev.Amount); + + public void Increment(int amount) => RecordAndApply(new ValueIncremented { Amount = amount }); + } + + sealed class StubPrincipalAccessor(ClaimsPrincipal? principal) : IEventStorePrincipalAccessor + { + public ClaimsPrincipal? GetPrincipal() => principal; + } + + static ServiceProvider CreateProvider(ClaimsPrincipal? principal) + { + ServiceCollection services = new(); + services.AddLogging(); + services.TryAddSingleton(new StubPrincipalAccessor(principal)); + services.AddEventSourcing().AddInMemoryEventStore(); + return services.BuildServiceProvider(); + } + + static ClaimsPrincipal PrincipalWith(string claimType, string value) => + new(new ClaimsIdentity([new Claim(claimType, value)])); + + [Test] + public async Task SaveAsync_GivenRegisteredPrincipalAccessor_RecordsTheUserAgainstTheEvent() + { + // Arrange + EventStoreOperationContext context = new() { RequiresValidPrincipalIdentifier = true }; + using var provider = CreateProvider(PrincipalWith(context.ClaimIdentifier, UserId)); + var eventStore = provider.GetRequiredService(); + + var aggregate = await eventStore.CreateAsync("principal-1"); + aggregate.Increment(1); + + // Act + var result = await eventStore.SaveAsync(aggregate, context); + + // Assert + await Assert.That(result.IsSuccess).IsTrue(); + + List<(Aggregates.EventRecord EventRecord, string EventType)> events = []; + await foreach ( + var @event in eventStore.GetEventRangeAsync("principal-1", 1, null, CancellationToken.None) + ) + events.Add(@event); + + await Assert.That(events).IsNotEmpty(); + await Assert.That(events[0].EventRecord.Metadata.UserId).IsEqualTo(UserId); + } + + [Test] + public async Task SaveAsync_GivenNoPrincipalAndIdentifierRequired_Throws() + { + // Arrange + using var provider = CreateProvider(principal: null); + var eventStore = provider.GetRequiredService(); + + var aggregate = await eventStore.CreateAsync("principal-2"); + aggregate.Increment(1); + + // Act & Assert + await Assert + .That(async () => + await eventStore.SaveAsync( + aggregate, + new EventStoreOperationContext { RequiresValidPrincipalIdentifier = true } + ) + ) + .Throws(); + } +} diff --git a/src/tests/EventSourcing.UnitTests/InMemory/Events/InMemoryEventStoreTenancyTests.cs b/src/tests/EventSourcing.UnitTests/InMemory/Events/InMemoryEventStoreTenancyTests.cs new file mode 100644 index 00000000..e6ca9ca5 --- /dev/null +++ b/src/tests/EventSourcing.UnitTests/InMemory/Events/InMemoryEventStoreTenancyTests.cs @@ -0,0 +1,145 @@ +using Microsoft.Extensions.DependencyInjection; +using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Aggregates.Events; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.InMemory.Events; + +/// +/// Guards that the in-memory store isolates tenants. +/// +/// +/// One store instance throughout, with the ambient scope switched between calls - two stores would prove +/// nothing but that two dictionaries hold different data. Ownership is tracked beside the data rather than +/// folded into the key, so the system scope still reads across tenants, matching the SQL providers this +/// store stands in for. +/// +public sealed class InMemoryEventStoreTenancyTests +{ + [EventContract] + sealed record ValueIncremented + { + public static int SchemaVersion => 1; + + public EventMetadata Metadata { get; init; } + + public int Amount { get; set; } + } + + sealed class TestAggregate : AggregateBase + { + public int Value { get; private set; } + + protected override void RegisterEvents() => Register(ev => Value += ev.Amount); + + public void Increment(int amount) => RecordAndApply(new ValueIncremented { Amount = amount }); + } + + static ServiceProvider CreateProvider() + { + ServiceCollection services = new(); + services.AddLogging(); + services.AddEventSourcing().AddInMemoryEventStore(); + return services.BuildServiceProvider(); + } + + static EventStoreOperationContext Context() => new() { RequiresValidPrincipalIdentifier = false }; + + static async Task> SeedAsync(ServiceProvider provider, string aggregateId) + { + var store = provider.GetRequiredService>(); + + using (AmbientCurrentTenant.BeginScope(TenantScope.For("acme"))) + { + var aggregate = await store.CreateAsync(aggregateId); + aggregate.Increment(1); + await store.SaveAsync(aggregate, Context()); + } + + return store; + } + + [Test] + public async Task GetAsync_GivenAnotherTenantsAggregate_DoesNotReturnIt() + { + using var provider = CreateProvider(); + var store = await SeedAsync(provider, "tenancy-1"); + + using (AmbientCurrentTenant.BeginScope(TenantScope.For("acme"))) + await Assert.That((await store.GetAsync("tenancy-1", Context())).IsSuccess).IsTrue(); + + using (AmbientCurrentTenant.BeginScope(TenantScope.For("globex"))) + await Assert.That((await store.GetAsync("tenancy-1", Context())).IsFailure).IsTrue(); + } + + [Test] + public async Task ExistsAsync_GivenAnotherTenantsAggregate_ReportsItAbsent() + { + using var provider = CreateProvider(); + var store = await SeedAsync(provider, "tenancy-2"); + + using (AmbientCurrentTenant.BeginScope(TenantScope.For("globex"))) + { + var existence = await store.ExistsAsync("tenancy-2"); + + await Assert.That(existence.DoesExist).IsFalse(); + } + } + + [Test] + public async Task GetEventRangeAsync_GivenAnotherTenantsAggregate_ReturnsNothing() + { + using var provider = CreateProvider(); + var store = await SeedAsync(provider, "tenancy-3"); + + using (AmbientCurrentTenant.BeginScope(TenantScope.For("globex"))) + { + List<(EventRecord EventRecord, string EventType)> events = []; + await foreach ( + var @event in ((IEventStoreCore)store).GetEventRangeAsync( + "tenancy-3", + 1, + null, + CancellationToken.None + ) + ) + events.Add(@event); + + await Assert.That(events).IsEmpty(); + } + } + + // Data written with no tenant - a tenant-less deployment, or a write path that missed the stamp - + // must not become visible to every tenant. Failing closed turns a missed stamp into absent data + // rather than silent cross-tenant exposure. + [Test] + public async Task GetAsync_GivenAnUnownedStream_IsNotVisibleToATenant() + { + using var provider = CreateProvider(); + var store = provider.GetRequiredService>(); + + // Seeded under the system scope, so the stream has no owner. + using (AmbientCurrentTenant.BeginScope(TenantScope.System)) + { + var aggregate = await store.CreateAsync("unowned-1"); + aggregate.Increment(1); + await store.SaveAsync(aggregate, Context()); + } + + using (AmbientCurrentTenant.BeginScope(TenantScope.For("acme"))) + await Assert.That((await store.GetAsync("unowned-1", Context())).IsFailure).IsTrue(); + + using (AmbientCurrentTenant.BeginScope(TenantScope.System)) + await Assert.That((await store.GetAsync("unowned-1", Context())).IsSuccess).IsTrue(); + } + + [Test] + public async Task GetAsync_GivenTheSystemScope_ReadsAcrossTenants() + { + using var provider = CreateProvider(); + var store = await SeedAsync(provider, "tenancy-4"); + + using (AmbientCurrentTenant.BeginScope(TenantScope.System)) + await Assert.That((await store.GetAsync("tenancy-4", Context())).IsSuccess).IsTrue(); + } +} diff --git a/src/tests/EventSourcing.UnitTests/Packaging/EntityFrameworkGeneratorPackagingTests.cs b/src/tests/EventSourcing.UnitTests/Packaging/EntityFrameworkGeneratorPackagingTests.cs new file mode 100644 index 00000000..c704f1d3 --- /dev/null +++ b/src/tests/EventSourcing.UnitTests/Packaging/EntityFrameworkGeneratorPackagingTests.cs @@ -0,0 +1,65 @@ +using System.Xml.Linq; + +namespace Purview.EventSourcing.Packaging; + +/// +/// Guards the rule that the Entity Framework Core source generator is packaged by exactly one project. +/// +/// +/// Roslyn loads an analyzer per path, not per identity. When three provider packages each carried a copy, +/// a consumer referencing two of them ran the generator twice and the second copy of its post-initialization +/// output failed the build with CS0579 - reported against a path in the consumer's own obj directory, naming +/// none of the packages responsible. NuGet dedupes by package identity, so the generator now ships only with +/// Purview.EventSourcing.EntityFrameworkCore, which every Entity Framework provider depends on. The providers +/// keep the reference for their own compilation and opt out of bundling it with Pack="false". +/// +public class EntityFrameworkGeneratorPackagingTests +{ + const string GeneratorProject = "EntityFrameworkCore.SourceGenerator.csproj"; + + static DirectoryInfo RepositorySource() + { + DirectoryInfo? directory = new(AppContext.BaseDirectory); + while (directory != null && !File.Exists(Path.Combine(directory.FullName, "src", "EventSourcing.slnx"))) + directory = directory.Parent; + + return directory == null + ? throw new DirectoryNotFoundException( + "Could not locate the repository root from the test output directory." + ) + : new DirectoryInfo(Path.Combine(directory.FullName, "src", "src")); + } + + static XElement[] GeneratorReferences(string projectFile) => + [ + .. XDocument + .Load(projectFile) + .Descendants("ProjectReference") + .Where(reference => + reference.Attribute("Include")?.Value.EndsWith(GeneratorProject, StringComparison.Ordinal) == true + ), + ]; + + [Test] + public async Task EntityFrameworkCoreProject_IsPackableAndReferencesTheGenerator() + { + var project = Path.Combine(RepositorySource().FullName, "EntityFrameworkCore", "EntityFrameworkCore.csproj"); + var document = XDocument.Load(project); + + await Assert.That(document.Descendants("IsPackable").Select(x => x.Value)).Contains("true"); + await Assert.That(GeneratorReferences(project)).Count().IsEqualTo(1); + } + + [Test] + [Arguments("SqlServer")] + [Arguments("Postgres")] + [Arguments("CosmosDb")] + public async Task EntityFrameworkProvider_ReferencesTheGenerator_WithoutPackagingIt(string provider) + { + var project = Path.Combine(RepositorySource().FullName, provider, $"{provider}.csproj"); + var references = GeneratorReferences(project); + + await Assert.That(references).Count().IsEqualTo(1); + await Assert.That(references[0].Attribute("Pack")?.Value).IsEqualTo("false"); + } +} diff --git a/src/tests/EventSourcing.UnitTests/Postgres/Snapshots/PostgresSnapshotClientTests.cs b/src/tests/EventSourcing.UnitTests/Postgres/Snapshots/PostgresSnapshotClientTests.cs deleted file mode 100644 index ffddfc6e..00000000 --- a/src/tests/EventSourcing.UnitTests/Postgres/Snapshots/PostgresSnapshotClientTests.cs +++ /dev/null @@ -1,115 +0,0 @@ -using Purview.EventSourcing.Aggregates; -using Purview.EventSourcing.Aggregates.Events; -using Purview.EventSourcing.EntityFrameworkCore; -using Purview.EventSourcing.Postgres.Client; -using System.Reflection; - -namespace Purview.EventSourcing.Postgres.Snapshots; - -public sealed class PostgresSnapshotClientTests -{ - [Test] - public async Task ValidateAggregatePayloadShape_GivenUriProperty_DoesNotThrow() - { - await Assert.That(() => ValidateAggregatePayloadShape(typeof(UriAggregate))).ThrowsNothing(); - } - - sealed class UriAggregate : IAggregate - { - public string AggregateType => nameof(UriAggregate); - - public AggregateDetails Details { get; init; } = new(); - - public Uri BlobUri { get; init; } = new("/", UriKind.Relative); - - public IReadOnlyList GetUnsavedEvents() => []; - - public bool HasUnsavedEvents() => false; - - public IEnumerable GetRegisteredEventTypes() => []; - - public bool CanApplyEvent(object aggregateEvent) => false; - - public void ClearUnsavedEvents(int? upToVersion = null) { } - - void IAggregate.ApplyEvent(object @event, EventMetadata metadata) { } - } - - [Test] - public async Task ValidateAggregatePayloadShape_GivenOpaqueReadOnlyCollection_DoesNotThrow() - { - await Assert.That(() => ValidateAggregatePayloadShape(typeof(OpaqueMemberAggregate))).ThrowsNothing(); - } - - [Test] - public async Task ValidateAggregatePayloadShape_GivenReadOnlyComplexMemberOnValueType_Throws() - { - var exception = await Assert - .That(() => ValidateAggregatePayloadShape(typeof(ReadOnlyValueTypeMemberAggregate))) - .Throws(); - - await Assert.That(exception!.Message).Contains(nameof(ReadOnlyStructHolder.Mirror)); - await Assert.That(exception.Message).Contains("writeable"); - } - - [Test] - public async Task ValidateAggregatePayloadShape_GivenSettableComplexMemberOnValueType_DoesNotThrow() - { - await Assert - .That(() => ValidateAggregatePayloadShape(typeof(SettableValueTypeMemberAggregate))) - .ThrowsNothing(); - } - - sealed class OpaqueMemberAggregate - { - [EFOpaque] - public IReadOnlyList Values { get; init; } = []; - } - - sealed class ReadOnlyValueTypeMemberAggregate - { - public ReadOnlyStructHolder Holder { get; init; } - } - - sealed class SettableValueTypeMemberAggregate - { - public SettableStructHolder Holder { get; init; } - } - - readonly struct ReadOnlyStructHolder - { -#pragma warning disable IDE0051 // Remove unused private members - ReadOnlyStructHolder(ValueTypeMemberInfo mirror) => Mirror = mirror; -#pragma warning restore IDE0051 // Remove unused private members - - public ValueTypeMemberInfo Mirror { get; } - } - - readonly struct SettableStructHolder - { - public ValueTypeMemberInfo Mirror { get; init; } - } - - sealed class ValueTypeMemberInfo - { - public string? Name { get; set; } - } - - static void ValidateAggregatePayloadShape(Type aggregateType) - { - var method = - typeof(PostgresClient).GetMethod( - "ValidateAggregatePayloadShape", - BindingFlags.Static | BindingFlags.NonPublic - ) ?? throw new InvalidOperationException("Unable to locate ValidateAggregatePayloadShape via reflection."); - - try - { - method.Invoke(null, [aggregateType]); - } - catch (TargetInvocationException ex) when (ex.InnerException is not null) - { - throw ex.InnerException; - } - } -} diff --git a/src/tests/EventSourcing.UnitTests/Services/AggregateEventNameMapperTests.GetName_AggregateEventType.cs b/src/tests/EventSourcing.UnitTests/Services/AggregateEventNameMapperTests.GetName_AggregateEventType.cs index 6a89071a..5a2a1a79 100644 --- a/src/tests/EventSourcing.UnitTests/Services/AggregateEventNameMapperTests.GetName_AggregateEventType.cs +++ b/src/tests/EventSourcing.UnitTests/Services/AggregateEventNameMapperTests.GetName_AggregateEventType.cs @@ -1,4 +1,4 @@ -namespace Purview.EventSourcing; +namespace Purview.EventSourcing; partial class AggregateEventNameMapperTests { diff --git a/src/tests/EventSourcing.UnitTests/Services/AggregateEventNameMapperTests.GetName_EventBase.cs b/src/tests/EventSourcing.UnitTests/Services/AggregateEventNameMapperTests.GetName_EventBase.cs index f734c393..da698719 100644 --- a/src/tests/EventSourcing.UnitTests/Services/AggregateEventNameMapperTests.GetName_EventBase.cs +++ b/src/tests/EventSourcing.UnitTests/Services/AggregateEventNameMapperTests.GetName_EventBase.cs @@ -1,4 +1,4 @@ -namespace Purview.EventSourcing; +namespace Purview.EventSourcing; partial class AggregateEventNameMapperTests { diff --git a/src/tests/EventSourcing.UnitTests/SqlServer/Events/SqlServerEventStoreTransactionTests.cs b/src/tests/EventSourcing.UnitTests/SqlServer/Events/SqlServerEventStoreTransactionTests.cs index 4af4c3a6..151f2d81 100644 --- a/src/tests/EventSourcing.UnitTests/SqlServer/Events/SqlServerEventStoreTransactionTests.cs +++ b/src/tests/EventSourcing.UnitTests/SqlServer/Events/SqlServerEventStoreTransactionTests.cs @@ -1,6 +1,8 @@ using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Test; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.Internal; +using Purview.Results; namespace Purview.EventSourcing.SqlServer.Events; @@ -48,46 +50,43 @@ public Task CreateAsync( CancellationToken cancellationToken = default ) => throw new NotSupportedException(); - public Task GetOrCreateAsync( + public Task> GetOrCreateAsync( string? aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => throw new NotSupportedException(); - public Task GetAsync( + public Task> GetAsync( string aggregateId, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => throw new NotSupportedException(); - public Task GetAtAsync( + public Task> GetAtAsync( string aggregateId, - int version, + long version, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => throw new NotSupportedException(); - public Task> SaveAsync( + public Task, AggregateSaveFailure>> SaveAsync( TestAggregate aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => throw new NotSupportedException(); - public Task IsDeletedAsync(string aggregateId, CancellationToken cancellationToken = default) => - throw new NotSupportedException(); - - public Task GetDeletedAsync( + public Task> GetDeletedAsync( string aggregateId, CancellationToken cancellationToken = default ) => throw new NotSupportedException(); - public Task DeleteAsync( + public Task, AggregateDeleteFailure>> DeleteAsync( TestAggregate aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default ) => throw new NotSupportedException(); - public Task RestoreAsync( + public Task, AggregateRestoreFailure>> RestoreAsync( TestAggregate aggregate, EventStoreOperationContext? operationContext, CancellationToken cancellationToken = default @@ -102,15 +101,17 @@ public async IAsyncEnumerable GetAggregateIdsAsync( yield break; } - public Task ExistsAsync(string aggregateId, CancellationToken cancellationToken = default) => - throw new NotSupportedException(); + public Task ExistsAsync( + string aggregateId, + CancellationToken cancellationToken = default + ) => throw new NotSupportedException(); public TestAggregate FulfilRequirements(TestAggregate aggregate) => aggregate; public IAsyncEnumerable<(EventRecord EventRecord, string EventType)> GetEventRangeAsync( string aggregateId, - int versionFrom, - int? versionTo, + long versionFrom, + long? versionTo, CancellationToken cancellationToken = default ) => throw new NotSupportedException(); diff --git a/src/tests/EventSourcing.UnitTests/SqlServer/Snapshots/SqlServerSnapshotClientTests.cs b/src/tests/EventSourcing.UnitTests/SqlServer/Snapshots/SqlServerSnapshotClientTests.cs index f829699e..ab1ef651 100644 --- a/src/tests/EventSourcing.UnitTests/SqlServer/Snapshots/SqlServerSnapshotClientTests.cs +++ b/src/tests/EventSourcing.UnitTests/SqlServer/Snapshots/SqlServerSnapshotClientTests.cs @@ -1,10 +1,5 @@ -using Purview.EventSourcing.Aggregates; -using Purview.EventSourcing.Aggregates.Events; -using Purview.EventSourcing.EntityFrameworkCore; -using Purview.EventSourcing.SqlServer.Client; -using Purview.ValueObjects.Serialization; -using System.Linq.Expressions; using System.Reflection; +using Purview.EventSourcing.SqlServer.Client; namespace Purview.EventSourcing.SqlServer.Snapshots; @@ -32,274 +27,4 @@ public async Task Constructor_GivenDefaultOptions_DoesNotUseLegacyEnsureTableSql await Assert.That(client).IsNotNull(); await Assert.That(ensureTableSqlField).IsNull(); } - - [Test] - public async Task ValidateAggregatePayloadShape_GivenEventStoreCollections_DoesNotThrow() - { - await Assert.That(() => ValidateAggregatePayloadShape(typeof(SupportedCollectionAggregate))).ThrowsNothing(); - } - - [Test] - public async Task ValidateAggregatePayloadShape_GivenArrayCollection_Throws() - { - var ex = await Assert - .That(() => ValidateAggregatePayloadShape(typeof(ArrayCollectionAggregate))) - .Throws(); - await Assert.That(ex).IsNotNull(); - await Assert.That(ex.Message).Contains(nameof(ArrayCollectionAggregate.Values)); - await Assert.That(ex.Message).Contains("EventStoreList"); - } - - [Test] - public async Task ValidateAggregatePayloadShape_GivenIReadOnlyListCollection_Throws() - { - var ex = await Assert - .That(() => ValidateAggregatePayloadShape(typeof(ReadOnlyListCollectionAggregate))) - .Throws(); - await Assert.That(ex).IsNotNull(); - await Assert.That(ex.Message).Contains(nameof(ReadOnlyListCollectionAggregate.Values)); - await Assert.That(ex.Message).Contains("EventStoreSet"); - } - - [Test] - public async Task ValidateAggregatePayloadShape_GivenUriProperty_DoesNotThrow() - { - await Assert.That(() => ValidateAggregatePayloadShape(typeof(UriAggregate))).ThrowsNothing(); - } - - [Test] - public async Task RewriteAggregateTypePredicate_GivenScalarEqualsPrimitive_RewritesToPrimitiveComparison() - { - Expression> whereClause = model => model.Email == "updated@test.com"; - var method = typeof(SqlServerClient).GetMethod( - "RewriteAggregateTypePredicate", - BindingFlags.Static | BindingFlags.NonPublic - ); - await Assert.That(method).IsNotNull(); - - var genericMethod = method!.MakeGenericMethod(typeof(ScalarHolder)); - var rewritten = - (Expression>)genericMethod.Invoke(null, [whereClause, nameof(ScalarHolder)])!; - - var binaryExpression = rewritten.Body as BinaryExpression; - await Assert.That(binaryExpression).IsNotNull(); - await Assert.That(binaryExpression!.NodeType).IsEqualTo(ExpressionType.Equal); - await Assert.That(binaryExpression.Left.Type).IsEqualTo(typeof(string)); - await Assert.That(binaryExpression.Right.Type).IsEqualTo(typeof(string)); - } - - [Test] - public async Task ValidateAggregatePayloadShape_GivenOpaqueReadOnlyCollection_DoesNotThrow() - { - await Assert.That(() => ValidateAggregatePayloadShape(typeof(OpaqueMemberAggregate))).ThrowsNothing(); - } - - [Test] - public async Task ValidateAggregatePayloadShape_GivenReadOnlyComplexMemberOnValueType_Throws() - { - var exception = await Assert - .That(() => ValidateAggregatePayloadShape(typeof(ReadOnlyValueTypeMemberAggregate))) - .Throws(); - - await Assert.That(exception!.Message).Contains(nameof(ReadOnlyStructHolder.Mirror)); - await Assert.That(exception.Message).Contains("writeable"); - } - - [Test] - public async Task ValidateAggregatePayloadShape_GivenReadOnlyComplexCollectionMemberOnValueType_Throws() - { - var exception = await Assert - .That(() => ValidateAggregatePayloadShape(typeof(ReadOnlyValueTypeCollectionMemberAggregate))) - .Throws(); - - await Assert.That(exception!.Message).Contains(nameof(ReadOnlyCollectionHolder.Items)); - } - - [Test] - public async Task ValidateAggregatePayloadShape_GivenSettableComplexMemberOnValueType_DoesNotThrow() - { - await Assert - .That(() => ValidateAggregatePayloadShape(typeof(SettableValueTypeMemberAggregate))) - .ThrowsNothing(); - } - - sealed class ScalarHolder - { - public ScalarEmail Email { get; init; } = new("default@test.com"); - } - - sealed class OpaqueMemberAggregate - { - [EFOpaque] - public IReadOnlyList Values { get; init; } = []; - } - - sealed class ReadOnlyValueTypeMemberAggregate - { - public ReadOnlyStructHolder Holder { get; init; } - } - - sealed class ReadOnlyValueTypeCollectionMemberAggregate - { - public ReadOnlyCollectionHolder Holder { get; init; } - } - - sealed class SettableValueTypeMemberAggregate - { - public SettableStructHolder Holder { get; init; } - } - - readonly struct ReadOnlyStructHolder - { -#pragma warning disable IDE0051 // Remove unused private members - ReadOnlyStructHolder(ValueTypeMemberInfo mirror) => Mirror = mirror; -#pragma warning restore IDE0051 // Remove unused private members - - public ValueTypeMemberInfo Mirror { get; } - } - - readonly struct ReadOnlyCollectionHolder - { -#pragma warning disable IDE0051 // Remove unused private members - ReadOnlyCollectionHolder(EventStoreList items) => Items = items; -#pragma warning restore IDE0051 // Remove unused private members - - public EventStoreList Items { get; } - } - - readonly struct SettableStructHolder - { - public ValueTypeMemberInfo Mirror { get; init; } - } - - sealed class ValueTypeMemberInfo - { - public string? Name { get; set; } - } - - sealed class UriAggregate : IAggregate - { - public string AggregateType => nameof(UriAggregate); - - public AggregateDetails Details { get; init; } = new(); - - public Uri BlobUri { get; init; } = new("/", UriKind.Relative); - - public IReadOnlyList GetUnsavedEvents() => []; - - public bool HasUnsavedEvents() => false; - - public IEnumerable GetRegisteredEventTypes() => []; - - public bool CanApplyEvent(object aggregateEvent) => false; - - public void ClearUnsavedEvents(int? upToVersion = null) { } - - void IAggregate.ApplyEvent(object @event, EventMetadata metadata) { } - } - - sealed class SupportedCollectionAggregate : IAggregate - { - public string AggregateType => nameof(SupportedCollectionAggregate); - - public AggregateDetails Details { get; init; } = new(); - - public EventStoreList IntValues { get; init; } = new(); - - public EventStoreSet StringValues { get; init; } = new(); - - public IReadOnlyList GetUnsavedEvents() => []; - - public bool HasUnsavedEvents() => false; - - public IEnumerable GetRegisteredEventTypes() => []; - - public bool CanApplyEvent(object aggregateEvent) => false; - - public void ClearUnsavedEvents(int? upToVersion = null) { } - - void IAggregate.ApplyEvent(object @event, EventMetadata metadata) { } - } - - sealed class ArrayCollectionAggregate : IAggregate - { - public string AggregateType => nameof(ArrayCollectionAggregate); - - public AggregateDetails Details { get; init; } = new(); - - public int[] Values { get; init; } = []; - - public IReadOnlyList GetUnsavedEvents() => []; - - public bool HasUnsavedEvents() => false; - - public IEnumerable GetRegisteredEventTypes() => []; - - public bool CanApplyEvent(object aggregateEvent) => false; - - public void ClearUnsavedEvents(int? upToVersion = null) { } - - void IAggregate.ApplyEvent(object @event, EventMetadata metadata) { } - } - - sealed class ReadOnlyListCollectionAggregate : IAggregate - { - public string AggregateType => nameof(ReadOnlyListCollectionAggregate); - - public AggregateDetails Details { get; init; } = new(); - - public IReadOnlyList Values { get; init; } = []; - - public IReadOnlyList GetUnsavedEvents() => []; - - public bool HasUnsavedEvents() => false; - - public IEnumerable GetRegisteredEventTypes() => []; - - public bool CanApplyEvent(object aggregateEvent) => false; - - public void ClearUnsavedEvents(int? upToVersion = null) { } - - void IAggregate.ApplyEvent(object @event, EventMetadata metadata) { } - } - - static void ValidateAggregatePayloadShape(Type aggregateType) - { - var method = - typeof(SqlServerClient).GetMethod( - "ValidateAggregatePayloadShape", - BindingFlags.Static | BindingFlags.NonPublic - ) ?? throw new InvalidOperationException("Unable to locate ValidateAggregatePayloadShape via reflection."); - - try - { - method.Invoke(null, [aggregateType]); - } - catch (TargetInvocationException ex) when (ex.InnerException is not null) - { - throw ex.InnerException; - } - } -} - -[Scalar( - GenerateJsonConverter = false, - GenerateComparable = false, - GenerateComparisonOperators = false, - GenerateEnumProperties = false, - GenerateImplicitFromPrimitive = false, - GenerateImplicitToPrimitive = false, - GenerateEmpty = false -)] -readonly partial record struct ScalarEmail -{ - public string Value { get; } - - public ScalarEmail(string value) => Value = value; - - public static bool operator ==(ScalarEmail left, string right) => left.Value == right; - - public static bool operator !=(ScalarEmail left, string right) => !(left == right); - - public static implicit operator string(ScalarEmail value) => value.Value; } diff --git a/src/tests/EventSourcing.UnitTests/SqlServer/Snapshots/SqlServerSnapshotEventStoreTests.cs b/src/tests/EventSourcing.UnitTests/SqlServer/Snapshots/SqlServerSnapshotEventStoreTests.cs index 98525528..eb2eb992 100644 --- a/src/tests/EventSourcing.UnitTests/SqlServer/Snapshots/SqlServerSnapshotEventStoreTests.cs +++ b/src/tests/EventSourcing.UnitTests/SqlServer/Snapshots/SqlServerSnapshotEventStoreTests.cs @@ -1,10 +1,9 @@ -using Microsoft.Extensions.Options; +using Microsoft.Extensions.Options; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Snapshotting; using Purview.EventSourcing.Aggregates.Test; using Purview.EventSourcing.Internal; using Purview.EventSourcing.SqlServer.Snapshot; -using ValidationResult = Purview.EventSourcing.Validation.ValidationResult; namespace Purview.EventSourcing.SqlServer.Snapshots; @@ -51,7 +50,8 @@ public async Task GetAsync_GivenAggregateId_DelegatesToEventStore() var store = CreateStore(eventStore); // Act - var result = await store.GetAsync("test-id", null); + var resultResult = await store.GetAsync("test-id", null); + var result = resultResult.IsSuccess ? resultResult.Value : null; // Assert await Assert.That(result).IsEqualTo(expectedAggregate); @@ -73,7 +73,8 @@ public async Task GetOrCreateAsync_GivenAggregateId_DelegatesToEventStore(Cancel var store = CreateStore(eventStore); // Act - var result = await store.GetOrCreateAsync("test-id", null, cancellationToken); + var resultResult = await store.GetOrCreateAsync("test-id", null, cancellationToken); + var result = resultResult.IsSuccess ? resultResult.Value : null; // Assert await Assert.That(result).IsEqualTo(expectedAggregate); @@ -89,38 +90,22 @@ public async Task GetAtAsync_GivenAggregateIdAndVersion_DelegatesToEventStore(Ca var expectedAggregate = TestHelpers.Aggregate(); var eventStore = INonQueryableEventStore.Mock(); eventStore - .GetAtAsync(Any(), Any(), Any(), Is(cancellationToken)) + .GetAtAsync(Any(), Any(), Any(), Is(cancellationToken)) .Returns(expectedAggregate); var store = CreateStore(eventStore); // Act - var result = await store.GetAtAsync("test-id", 5, null, cancellationToken); + var resultResult = await store.GetAtAsync("test-id", 5, null, cancellationToken); + var result = resultResult.IsSuccess ? resultResult.Value : null; // Assert await Assert.That(result).IsEqualTo(expectedAggregate); eventStore - .GetAtAsync(Is("test-id"), Is(5), Any(), Is(cancellationToken)) + .GetAtAsync(Is("test-id"), Is(5L), Any(), Is(cancellationToken)) .WasCalled(Times.Once); } - [Test] - public async Task IsDeletedAsync_DelegatesToEventStore(CancellationToken cancellationToken) - { - // Arrange - var eventStore = INonQueryableEventStore.Mock(); - eventStore.IsDeletedAsync(Any(), Is(cancellationToken)).Returns(true); - - var store = CreateStore(eventStore); - - // Act - var result = await store.IsDeletedAsync("test-id", cancellationToken); - - // Assert - await Assert.That(result).IsTrue(); - eventStore.IsDeletedAsync(Is("test-id"), Is(cancellationToken)).WasCalled(Times.Once); - } - [Test] public async Task GetDeletedAsync_DelegatesToEventStore(CancellationToken cancellationToken) { @@ -132,7 +117,8 @@ public async Task GetDeletedAsync_DelegatesToEventStore(CancellationToken cancel var store = CreateStore(eventStore); // Act - var result = await store.GetDeletedAsync("test-id", cancellationToken); + var resultResult = await store.GetDeletedAsync("test-id", cancellationToken); + var result = resultResult.IsSuccess ? resultResult.Value : null; // Assert await Assert.That(result).IsEqualTo(expectedAggregate); @@ -143,7 +129,7 @@ public async Task GetDeletedAsync_DelegatesToEventStore(CancellationToken cancel public async Task ExistsAsync_DelegatesToEventStore(CancellationToken cancellationToken) { // Arrange - var expectedState = ExistsState.Exists; + var expectedState = AggregateExistence.Exists; var eventStore = INonQueryableEventStore.Mock(); eventStore.ExistsAsync(Any(), Any()).Returns(expectedState); @@ -182,15 +168,12 @@ public async Task SaveAsync_GivenNeverSnapshotStrategy_DoesNotWriteSnapshot(Canc var eventStore = INonQueryableEventStore.Mock(); eventStore .SaveAsync(Any(), Any(), Any()) - .Returns( - static (a, _, _) => - new SaveResult(a, new ValidationResult(), saved: true, skipped: false) - ); + .Returns(static (a, _, _) => new SaveOutcome(a, SaveOutcomeKind.Written)); var store = CreateStore(eventStore, snapshotStrategy: new NeverSnapshotStrategy()); var result = await store.SaveAsync(aggregate, null, cancellationToken); - await Assert.That(result.Saved).IsTrue(); + await Assert.That(result.IsSuccess && result.Value.Written).IsTrue(); eventStore .SaveAsync(Is(aggregate), Any(), Any()) .WasCalled(Times.Once); @@ -205,17 +188,14 @@ CancellationToken cancellationToken var eventStore = INonQueryableEventStore.Mock(); eventStore .SaveAsync(Any(), Any(), Any()) - .Returns( - static (a, _, _) => - new SaveResult(a, new ValidationResult(), saved: true, skipped: false) - ); + .Returns(static (a, _, _) => new SaveOutcome(a, SaveOutcomeKind.Written)); var store = CreateStore(eventStore, snapshotStrategy: new AlwaysSnapshotStrategy()); var context = new EventStoreOperationContext().SetSnapshotStrategy(new NeverSnapshotStrategy()); var result = await store.SaveAsync(aggregate, context, cancellationToken); - await Assert.That(result.Saved).IsTrue(); + await Assert.That(result.IsSuccess && result.Value.Written).IsTrue(); eventStore.SaveAsync(Is(aggregate), context, Any()).WasCalled(Times.Once); } diff --git a/src/tests/EventSourcing.UnitTests/TypeNameHelperTests.cs b/src/tests/EventSourcing.UnitTests/TypeNameHelperTests.cs index 736ec310..a4672115 100644 --- a/src/tests/EventSourcing.UnitTests/TypeNameHelperTests.cs +++ b/src/tests/EventSourcing.UnitTests/TypeNameHelperTests.cs @@ -1,4 +1,4 @@ -namespace Purview.EventSourcing; +namespace Purview.EventSourcing; public class TypeNameHelperTests { diff --git a/src/tests/MongoDB.IntegrationTests/Events/MongoDBEventStoreTenancyTests.cs b/src/tests/MongoDB.IntegrationTests/Events/MongoDBEventStoreTenancyTests.cs new file mode 100644 index 00000000..a4da1fa2 --- /dev/null +++ b/src/tests/MongoDB.IntegrationTests/Events/MongoDBEventStoreTenancyTests.cs @@ -0,0 +1,72 @@ +using Purview.EventSourcing.Aggregates.Persistence; +using Purview.EventSourcing.Fixtures.MongoDB; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.MongoDB.Events; + +/// +/// Guards that the tenant query filter isolates event streams. +/// +/// +/// Exercised against real MongoDB rather than in memory: the isolation is an Entity Framework global +/// query filter translated into SQL, so an in-memory substitute would prove nothing about the predicate +/// that actually runs. +/// +[ClassDataSource(Shared = SharedType.PerAssembly)] +public sealed class MongoDBEventStoreTenancyTests(MongoDBEventStoreFixture fixture) +{ + sealed class StubTenant(TenantScope scope) : ICurrentTenant + { + public TenantScope Current => scope; + } + + MongoDBEventStore StoreFor(TenantScope scope, Guid runId) => + fixture.CreateEventStore(currentTenant: new StubTenant(scope), runId: runId); + + [Test] + public async Task GetAsync_GivenAnotherTenantsAggregate_DoesNotReturnIt(CancellationToken cancellationToken) + { + // Arrange - one physical table, two tenants, the same aggregate id. + var runId = Guid.NewGuid(); + var aggregateId = $"{Guid.NewGuid()}"; + + var acme = StoreFor(TenantScope.For("acme"), runId); + var globex = StoreFor(TenantScope.For("globex"), runId); + + var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); + aggregate.IncrementInt32Value(); + + var saved = await acme.SaveAsync(aggregate, cancellationToken: cancellationToken); + await Assert.That(saved.IsSuccess).IsTrue(); + + // Act + var fromOwner = await acme.GetAsync(aggregateId, cancellationToken: cancellationToken); + var fromOther = await globex.GetAsync(aggregateId, cancellationToken: cancellationToken); + + // Assert + await Assert.That(fromOwner.IsSuccess).IsTrue(); + await Assert.That(fromOther.IsFailure).IsTrue(); + } + + [Test] + public async Task GetAsync_GivenSystemScope_ReadsAcrossTenants(CancellationToken cancellationToken) + { + // Arrange + var runId = Guid.NewGuid(); + var aggregateId = $"{Guid.NewGuid()}"; + + var acme = StoreFor(TenantScope.For("acme"), runId); + var system = StoreFor(TenantScope.System, runId); + + var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); + aggregate.IncrementInt32Value(); + + await acme.SaveAsync(aggregate, cancellationToken: cancellationToken); + + // Act - infrastructure work deliberately crosses tenants. + var result = await system.GetAsync(aggregateId, cancellationToken: cancellationToken); + + // Assert + await Assert.That(result.IsSuccess).IsTrue(); + } +} diff --git a/src/tests/MongoDB.IntegrationTests/Guards/MongoDBEventStoreGuardTests.cs b/src/tests/MongoDB.IntegrationTests/Guards/MongoDBEventStoreGuardTests.cs index 2834c4a2..7be2da23 100644 --- a/src/tests/MongoDB.IntegrationTests/Guards/MongoDBEventStoreGuardTests.cs +++ b/src/tests/MongoDB.IntegrationTests/Guards/MongoDBEventStoreGuardTests.cs @@ -1,4 +1,6 @@ +using System.Diagnostics.CodeAnalysis; using System.Text; +using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Persistence; using Purview.EventSourcing.Aggregates.Persistence.Events; using Purview.EventSourcing.Fixtures.MongoDB; @@ -33,15 +35,13 @@ CancellationToken cancellationToken await eventStore.SaveAsync(aggregate, cancellationToken); - var aggregateResult = - await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken) - ?? throw new NullReferenceException(); + var aggregateResult = (await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken)).Value; // Act var result = await eventStore.DeleteAsync(aggregateResult, cancellationToken: cancellationToken); // Assert - await Assert.That(result).IsTrue(); + await Assert.That(result.IsSuccess).IsTrue(); cache.RemoveAsync(cacheKey, Any()).WasCalled(Times.Once); } @@ -62,7 +62,8 @@ CancellationToken cancellationToken await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); - aggregate = await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken); + var aggregateResult = await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken); + aggregate = aggregateResult.IsSuccess ? aggregateResult.Value : null; await Assert.That(aggregate).IsNotNull(); // Act @@ -73,7 +74,7 @@ CancellationToken cancellationToken ); // Assert - await Assert.That(result).IsTrue(); + await Assert.That(result.IsSuccess).IsTrue(); await Assert.That(aggregate.Details.IsDeleted).IsTrue(); await Assert.That(aggregate.Details.Locked).IsTrue(); @@ -109,7 +110,8 @@ CancellationToken cancellationToken await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); - aggregate = await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken); + var aggregateResult = await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken); + aggregate = aggregateResult.IsSuccess ? aggregateResult.Value : null; await Assert.That(aggregate).IsNotNull(); // Act @@ -120,7 +122,7 @@ CancellationToken cancellationToken ); // Assert - await Assert.That(result).IsTrue(); + await Assert.That(result.IsSuccess).IsTrue(); await Assert.That(aggregate.Details.IsDeleted).IsTrue(); await Assert.That(aggregate.Details.Locked).IsTrue(); @@ -141,16 +143,22 @@ CancellationToken cancellationToken var telemetry = ctx.Telemetry; // Act - bool result = await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); + var result = await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); // Assert - await Assert.That(result).IsFalse(); + await Assert.That(result.IsSuccess).IsTrue(); + await Assert.That(result.Value.Kind).IsEqualTo(SaveOutcomeKind.NoChanges); telemetry.SaveContainedNoChanges(aggregateId, Any(), Any()).WasCalled(Times.Once); } [Test] [MethodDataSource(nameof(OldEventCountTestData))] + [SuppressMessage( + "Maintainability", + "CA1506", + Justification = "Guard scenario intentionally touches the full event-store surface." + )] public async Task GetAsync_GivenAnAggregateWithNonRegisteredEventType_TelemetryLogsCannotApplyEvent( int eventsToCreate, int numberOfOldEventsToCreate, @@ -170,11 +178,12 @@ CancellationToken cancellationToken // Act await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); - var result = await eventStore.GetAsync( + var resultResult = await eventStore.GetAsync( aggregateId, new EventStoreOperationContext { SkipSnapshot = true }, cancellationToken: cancellationToken ); + var result = resultResult.IsSuccess ? resultResult.Value : null; // Assert telemetry @@ -184,7 +193,7 @@ CancellationToken cancellationToken Any(), Any(), Is(eventType => eventType!.Contains(nameof(OldEvent), StringComparison.Ordinal)), - Any() + Any() ) .WasCalled(Times.Exactly(numberOfOldEventsToCreate)); @@ -227,15 +236,16 @@ await MarkEventsAsUnknown( cancellationToken ); - var result = await eventStore.GetAsync( + var resultResult = await eventStore.GetAsync( aggregateId, new EventStoreOperationContext { SkipSnapshot = true }, cancellationToken: cancellationToken ); + var result = resultResult.IsSuccess ? resultResult.Value : null; // Assert telemetry - .SkippedUnknownEvent(aggregateId, Any(), Any(), unknownEventType, Any()) + .SkippedUnknownEvent(aggregateId, Any(), Any(), unknownEventType, Any()) .WasCalled(Times.Exactly(numberOfOldEventsToCreate)); await Assert.That(result).IsNotNull(); diff --git a/src/tests/Postgres.IntegrationTests/Events/PostgresEventStoreTenancyTests.cs b/src/tests/Postgres.IntegrationTests/Events/PostgresEventStoreTenancyTests.cs new file mode 100644 index 00000000..c994d439 --- /dev/null +++ b/src/tests/Postgres.IntegrationTests/Events/PostgresEventStoreTenancyTests.cs @@ -0,0 +1,72 @@ +using Purview.EventSourcing.Aggregates.Persistence; +using Purview.EventSourcing.Fixtures.Postgres; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.Postgres.Events; + +/// +/// Guards that the tenant query filter isolates event streams. +/// +/// +/// Exercised against real PostgreSQL rather than in memory: the isolation is an Entity Framework global +/// query filter translated into SQL, so an in-memory substitute would prove nothing about the predicate +/// that actually runs. +/// +[ClassDataSource(Shared = SharedType.PerAssembly)] +public sealed class PostgresEventStoreTenancyTests(PostgresEventStoreFixture fixture) +{ + sealed class StubTenant(TenantScope scope) : ICurrentTenant + { + public TenantScope Current => scope; + } + + PostgresEventStore StoreFor(TenantScope scope, Guid runId) => + fixture.CreateEventStore(runId: runId, currentTenant: new StubTenant(scope)); + + [Test] + public async Task GetAsync_GivenAnotherTenantsAggregate_DoesNotReturnIt(CancellationToken cancellationToken) + { + // Arrange - one physical table, two tenants, the same aggregate id. + var runId = Guid.NewGuid(); + var aggregateId = $"{Guid.NewGuid()}"; + + var acme = StoreFor(TenantScope.For("acme"), runId); + var globex = StoreFor(TenantScope.For("globex"), runId); + + var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); + aggregate.IncrementInt32Value(); + + var saved = await acme.SaveAsync(aggregate, cancellationToken: cancellationToken); + await Assert.That(saved.IsSuccess).IsTrue(); + + // Act + var fromOwner = await acme.GetAsync(aggregateId, cancellationToken: cancellationToken); + var fromOther = await globex.GetAsync(aggregateId, cancellationToken: cancellationToken); + + // Assert + await Assert.That(fromOwner.IsSuccess).IsTrue(); + await Assert.That(fromOther.IsFailure).IsTrue(); + } + + [Test] + public async Task GetAsync_GivenSystemScope_ReadsAcrossTenants(CancellationToken cancellationToken) + { + // Arrange + var runId = Guid.NewGuid(); + var aggregateId = $"{Guid.NewGuid()}"; + + var acme = StoreFor(TenantScope.For("acme"), runId); + var system = StoreFor(TenantScope.System, runId); + + var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); + aggregate.IncrementInt32Value(); + + await acme.SaveAsync(aggregate, cancellationToken: cancellationToken); + + // Act - infrastructure work deliberately crosses tenants. + var result = await system.GetAsync(aggregateId, cancellationToken: cancellationToken); + + // Assert + await Assert.That(result.IsSuccess).IsTrue(); + } +} diff --git a/src/tests/Postgres.IntegrationTests/Outbox/PostgresOutboxIntegrationTests.cs b/src/tests/Postgres.IntegrationTests/Outbox/PostgresOutboxIntegrationTests.cs index 04769739..43ae6508 100644 --- a/src/tests/Postgres.IntegrationTests/Outbox/PostgresOutboxIntegrationTests.cs +++ b/src/tests/Postgres.IntegrationTests/Outbox/PostgresOutboxIntegrationTests.cs @@ -1,3 +1,5 @@ +using System.Collections.Concurrent; +using System.Diagnostics.CodeAnalysis; using Microsoft.Extensions.Logging.Abstractions; using Microsoft.Extensions.Options; using Npgsql; @@ -15,6 +17,11 @@ namespace Purview.EventSourcing.Postgres.Outbox; public sealed class PostgresOutboxIntegrationTests(PostgresEventStoreFixture fixture) { [Test] + [SuppressMessage( + "Maintainability", + "CA1506:Avoid excessive class coupling", + Justification = "Test wiring: the store, its infrastructure and the result model are all named here." + )] public async Task CommitAsync_GivenEnlistedOutboxAndAggregate_CommitsBothAtomically( CancellationToken cancellationToken ) @@ -37,7 +44,8 @@ await store.EnqueueInTransactionAsync(connection, sqlTransaction, envelope, toke ); var result = await transaction.CommitAsync(cancellationToken); - var savedAggregate = await eventStore.GetAsync(aggregateId, null, cancellationToken); + var savedAggregateResult = await eventStore.GetAsync(aggregateId, null, cancellationToken); + var savedAggregate = savedAggregateResult.IsSuccess ? savedAggregateResult.Value : null; var row = await ReadOutboxRowAsync(tableName, envelope.Id, cancellationToken); await Assert.That(result.Success).IsTrue(); @@ -69,7 +77,8 @@ await store.EnqueueInTransactionAsync(connection, sqlTransaction, envelope, toke transaction.Enlist((_, _, _) => Task.FromException(new InvalidOperationException("enlisted operation failed"))); var result = await transaction.CommitAsync(cancellationToken); - var savedAggregate = await eventStore.GetAsync(aggregateId, null, cancellationToken); + var savedAggregateResult = await eventStore.GetAsync(aggregateId, null, cancellationToken); + var savedAggregate = savedAggregateResult.IsSuccess ? savedAggregateResult.Value : null; var row = await ReadOutboxRowAsync(tableName, envelope.Id, cancellationToken); await Assert.That(result.Success).IsFalse(); @@ -255,7 +264,7 @@ public Task HandleAsync(OutboxEnvelope message, CancellationToken cancellationTo sealed class SlowRecordingHandler : IOutboxHandler { - public List HandledIds { get; } = []; + public ConcurrentBag HandledIds { get; } = []; public async Task HandleAsync(OutboxEnvelope message, CancellationToken cancellationToken) { diff --git a/src/tests/Postgres.IntegrationTests/PostgresContainerParallelLimit.cs b/src/tests/Postgres.IntegrationTests/PostgresContainerParallelLimit.cs new file mode 100644 index 00000000..b0056b73 --- /dev/null +++ b/src/tests/Postgres.IntegrationTests/PostgresContainerParallelLimit.cs @@ -0,0 +1,18 @@ +using TUnit.Core.Interfaces; + +// The suite shares one PostgreSQL container, and its connection limit - not the CPU count - is what +// bounds safe concurrency here. Unbounded parallelism exhausts the pool and fails with connection +// timeouts, so the limit travels with the suite rather than depending on the caller passing +// --maximum-parallel-tests. +[assembly: ParallelLimiter] + +namespace Purview.EventSourcing.Postgres; + +/// +/// Caps concurrent tests to a level the shared PostgreSQL container's connection pool sustains. +/// +public sealed class PostgresContainerParallelLimit : IParallelLimit +{ + /// + public int Limit => 4; +} diff --git a/src/tests/Postgres.IntegrationTests/Snapshots/PostgresProviderIntegrationTests.cs b/src/tests/Postgres.IntegrationTests/Snapshots/PostgresProviderIntegrationTests.cs index e9a402a5..41e82dd2 100644 --- a/src/tests/Postgres.IntegrationTests/Snapshots/PostgresProviderIntegrationTests.cs +++ b/src/tests/Postgres.IntegrationTests/Snapshots/PostgresProviderIntegrationTests.cs @@ -18,7 +18,8 @@ public async Task EventStore_SaveAndReplay_RestoresAggregateState(CancellationTo await store.SaveAsync(aggregate, cancellationToken: cancellationToken); - var rehydrated = await store.GetAsync(aggregate.Details.Id, cancellationToken: cancellationToken); + var rehydratedResult = await store.GetAsync(aggregate.Details.Id, cancellationToken: cancellationToken); + var rehydrated = rehydratedResult.IsSuccess ? rehydratedResult.Value : null; await Assert.That(rehydrated).IsNotNull(); await Assert.That(rehydrated!.Int32Value).IsEqualTo(123); await Assert.That(rehydrated.StringProperty).Contains("hello"); @@ -78,7 +79,12 @@ public async Task ExecuteUpdate_PartialJsonUpdate_UpdatesSingleField(Cancellatio await using (var setupContext = new ExecuteUpdateDBContext(options, tableName)) { - await setupContext.Database.EnsureCreatedAsync(cancellationToken); + // Not EnsureCreatedAsync: it creates nothing once the database holds any table, so this + // test's uniquely named table was skipped whenever another test had already created one. + await setupContext.Database.ExecuteSqlRawAsync( + setupContext.Database.GenerateCreateScript(), + cancellationToken + ); setupContext.Rows.Add( new ExecuteUpdateRow { @@ -174,7 +180,7 @@ sealed class ExecuteUpdateRow sealed class ExecuteUpdateState { - public int Version { get; set; } + public long Version { get; set; } public required string Status { get; set; } } diff --git a/src/tests/Postgres.IntegrationTests/Snapshots/ReportUploadAggregateSnapshotEventStoreTests.cs b/src/tests/Postgres.IntegrationTests/Snapshots/ReportUploadAggregateSnapshotEventStoreTests.cs index 2df78ac0..e28031ed 100644 --- a/src/tests/Postgres.IntegrationTests/Snapshots/ReportUploadAggregateSnapshotEventStoreTests.cs +++ b/src/tests/Postgres.IntegrationTests/Snapshots/ReportUploadAggregateSnapshotEventStoreTests.cs @@ -65,7 +65,8 @@ CancellationToken cancellationToken await store.SaveAsync(aggregate, cancellationToken); - var restored = await store.GetAsync(id, cancellationToken: cancellationToken); + var restoredResult = await store.GetAsync(id, cancellationToken: cancellationToken); + var restored = restoredResult.IsSuccess ? restoredResult.Value : null; await Assert.That(restored).IsNotNull(); await Assert.That(restored!.ReportSummary).IsNotNull(); diff --git a/src/tests/Samples.AppHost.IntegrationTests/Services/CartCheckoutServiceTests.cs b/src/tests/Samples.AppHost.IntegrationTests/Services/CartCheckoutServiceTests.cs index 3ffa1a12..63bb4348 100644 --- a/src/tests/Samples.AppHost.IntegrationTests/Services/CartCheckoutServiceTests.cs +++ b/src/tests/Samples.AppHost.IntegrationTests/Services/CartCheckoutServiceTests.cs @@ -36,8 +36,10 @@ CancellationToken cancellationToken await Assert.That(result.Succeeded).IsTrue(); await Assert.That(result.Order).IsNotNull(); - var savedOrder = await orderStore.GetAsync(result.Order!.Id(), cancellationToken); - var savedInventory = await inventoryStore.GetAsync(inventory.Id(), cancellationToken); + var savedOrderResult = await orderStore.GetAsync(result.Order!.Id(), cancellationToken); + var savedOrder = savedOrderResult.IsSuccess ? savedOrderResult.Value : null; + var savedInventoryResult = await inventoryStore.GetAsync(inventory.Id(), cancellationToken); + var savedInventory = savedInventoryResult.IsSuccess ? savedInventoryResult.Value : null; var orderCount = await orderStore.CountAsync( order => order.CustomerId == customer.Id(), cancellationToken @@ -74,10 +76,11 @@ CancellationToken cancellationToken { await using var hookScope = serviceProvider.CreateAsyncScope(); var inventoryStore = hookScope.ServiceProvider.GetRequiredService(); - var inventory = await inventoryStore.GetAsync( + var inventoryResult = await inventoryStore.GetAsync( inventoryId, hookCancellationToken ); + var inventory = inventoryResult.IsSuccess ? inventoryResult.Value : null; inventory!.ReserveStock(3, "concurrent-order"); await inventoryStore.SaveAsync(inventory, hookCancellationToken); @@ -107,7 +110,8 @@ [new CartItem(inventory.ProductId, inventory.ProductName, inventory.Id(), 8, 19. order => order.CustomerId == customer.Id(), cancellationToken ); - var savedInventory = await inventoryStore.GetAsync(inventory.Id(), cancellationToken); + var savedInventoryResult = await inventoryStore.GetAsync(inventory.Id(), cancellationToken); + var savedInventory = savedInventoryResult.IsSuccess ? savedInventoryResult.Value : null; await Assert.That(result.Succeeded).IsFalse(); await Assert.That(result.ErrorMessage).Contains("Nothing was saved"); @@ -135,7 +139,7 @@ CancellationToken cancellationToken customer.RegisterCustomer($"Cart Test {Guid.NewGuid():N}", $"{Guid.NewGuid():N}@example.com"); var result = await customerStore.SaveAsync(customer, cancellationToken); - return result.Aggregate; + return result.Value.Aggregate; } static async Task CreateInventoryAsync( @@ -154,7 +158,7 @@ CancellationToken cancellationToken ); var result = await inventoryStore.SaveAsync(inventory, cancellationToken); - return result.Aggregate; + return result.Value.Aggregate; } sealed class HookedTransactionFactory( diff --git a/src/tests/Samples.AppHost.IntegrationTests/Web/Admin/AdminApiClientTests.cs b/src/tests/Samples.AppHost.IntegrationTests/Web/Admin/AdminApiClientTests.cs index 416f3e33..6e8ab427 100644 --- a/src/tests/Samples.AppHost.IntegrationTests/Web/Admin/AdminApiClientTests.cs +++ b/src/tests/Samples.AppHost.IntegrationTests/Web/Admin/AdminApiClientTests.cs @@ -202,6 +202,6 @@ public async Task SearchAggregates_InvalidRequest_ThrowsValidationProblem(Cancel .SetShippingAddress("1 Client Test Way"); var result = await store.SaveAsync(order, cancellationToken); - return (result.Aggregate.Id(), customerId); + return (result.Value.Aggregate.Id(), customerId); } } diff --git a/src/tests/Samples.AppHost.IntegrationTests/Web/Infrastructure/AzureVariantStartupUsageTests.cs b/src/tests/Samples.AppHost.IntegrationTests/Web/Infrastructure/AzureVariantStartupUsageTests.cs index 36da4e6a..e1cd15d5 100644 --- a/src/tests/Samples.AppHost.IntegrationTests/Web/Infrastructure/AzureVariantStartupUsageTests.cs +++ b/src/tests/Samples.AppHost.IntegrationTests/Web/Infrastructure/AzureVariantStartupUsageTests.cs @@ -62,9 +62,17 @@ static async Task GetDashboardHtmlAsync(HttpClient client, CancellationT while (true) { - var response = await client.GetAsync("/", timeoutCts.Token); - if (response.IsSuccessStatusCode) - return await response.Content.ReadAsStringAsync(timeoutCts.Token); + try + { + var response = await client.GetAsync("/", timeoutCts.Token); + if (response.IsSuccessStatusCode) + return await response.Content.ReadAsStringAsync(timeoutCts.Token); + } + catch (HttpRequestException) when (!timeoutCts.IsCancellationRequested) + { + // Connection refused: Kestrel has not bound the port yet. This is the case the retry + // exists for, and it arrives as an exception rather than a status code. + } await Task.Delay(TimeSpan.FromMilliseconds(500), timeoutCts.Token); } diff --git a/src/tests/Samples.AppHost.IntegrationTests/Web/Pages/AuditPageTests.cs b/src/tests/Samples.AppHost.IntegrationTests/Web/Pages/AuditPageTests.cs index f0c66940..1c1f7e7c 100644 --- a/src/tests/Samples.AppHost.IntegrationTests/Web/Pages/AuditPageTests.cs +++ b/src/tests/Samples.AppHost.IntegrationTests/Web/Pages/AuditPageTests.cs @@ -63,12 +63,12 @@ async Task CreateOrderAsync(CancellationToken cancellationToken) var order = await store.CreateAsync(cancellationToken: cancellationToken); order - .CreateOrder(customerResult.Aggregate.Id()) + .CreateOrder(customerResult.Value.Aggregate.Id()) .AddLineItem("SKU-AUDIT-001", "Audit Product", 1, 9.99m) .SetShippingAddress("1 Audit Way"); var orderResult = await store.SaveAsync(order, cancellationToken); - return orderResult.Aggregate.Id(); + return orderResult.Value.Aggregate.Id(); } //sealed class AuditWebAppFactory : WebApplicationFactory diff --git a/src/tests/Samples.AppHost.IntegrationTests/Web/Pages/CustomerPageTests.cs b/src/tests/Samples.AppHost.IntegrationTests/Web/Pages/CustomerPageTests.cs index dbeff58a..213bc325 100644 --- a/src/tests/Samples.AppHost.IntegrationTests/Web/Pages/CustomerPageTests.cs +++ b/src/tests/Samples.AppHost.IntegrationTests/Web/Pages/CustomerPageTests.cs @@ -143,7 +143,7 @@ async Task GetAntiForgeryTokenAsync(string url, CancellationToken cancel return string.Empty; var valueStart = html.IndexOf("value=\"", start, StringComparison.Ordinal) + 7; - var valueEnd = html.IndexOf('"', valueStart); + var valueEnd = html.IndexOf('"', valueStart, StringComparison.Ordinal); return html[valueStart..valueEnd]; } @@ -157,8 +157,7 @@ async Task CreateCustomersAsync(string prefix, int count, CancellationToken canc customer.RegisterCustomer($"{prefix}-customer-{i:D2}", $"{prefix}-{i:D2}@example.com"); var result = await store.SaveAsync(customer, cancellationToken); - await Assert.That(result).IsNotNull(); - await Assert.That(result.IsValid).IsTrue().Because(result.ValidationResult.ToString()!); + await Assert.That(result.IsSuccess).IsTrue().Because(result.IsFailure ? $"{result.Error}" : string.Empty); } var totalCount = await store.CountAsync(cancellationToken); diff --git a/src/tests/Samples.AppHost.IntegrationTests/Web/Pages/InventoryPageTests.cs b/src/tests/Samples.AppHost.IntegrationTests/Web/Pages/InventoryPageTests.cs index 8718ceed..ad4c7574 100644 --- a/src/tests/Samples.AppHost.IntegrationTests/Web/Pages/InventoryPageTests.cs +++ b/src/tests/Samples.AppHost.IntegrationTests/Web/Pages/InventoryPageTests.cs @@ -147,7 +147,7 @@ async Task GetAntiForgeryTokenAsync(string url, CancellationToken cancel return string.Empty; var valueStart = html.IndexOf("value=\"", start, StringComparison.Ordinal) + 7; - var valueEnd = html.IndexOf('"', valueStart); + var valueEnd = html.IndexOf('"', valueStart, StringComparison.Ordinal); return html[valueStart..valueEnd]; } @@ -167,7 +167,7 @@ static string ExtractFirstSelectValue(string html, string selectName) return string.Empty; var valueStart = optionStart + 15; - var valueEnd = html.IndexOf('"', valueStart); + var valueEnd = html.IndexOf('"', valueStart, StringComparison.Ordinal); if (valueEnd == -1) return string.Empty; diff --git a/src/tests/Samples.AppHost.IntegrationTests/Web/Pages/OrderPageTests.cs b/src/tests/Samples.AppHost.IntegrationTests/Web/Pages/OrderPageTests.cs index 3e5de87e..befe7ca0 100644 --- a/src/tests/Samples.AppHost.IntegrationTests/Web/Pages/OrderPageTests.cs +++ b/src/tests/Samples.AppHost.IntegrationTests/Web/Pages/OrderPageTests.cs @@ -125,7 +125,7 @@ CancellationToken cancellationToken ); var saveResult = await store.SaveAsync(inventory, cancellationToken); - return (saveResult.Aggregate.Id(), destinationLocationId); + return (saveResult.Value.Aggregate.Id(), destinationLocationId); } async Task GetAntiForgeryTokenAsync(HttpClient client, string url, CancellationToken cancellationToken) @@ -138,7 +138,7 @@ async Task GetAntiForgeryTokenAsync(HttpClient client, string url, Cance return string.Empty; var valueStart = html.IndexOf("value=\"", start, StringComparison.Ordinal) + 7; - var valueEnd = html.IndexOf('"', valueStart); + var valueEnd = html.IndexOf('"', valueStart, StringComparison.Ordinal); return html[valueStart..valueEnd]; } @@ -149,7 +149,7 @@ async Task CreateCustomerWithOrdersAsync(int orderCount, CancellationTok var customer = await store.CreateAsync(cancellationToken: cancellationToken); customer.RegisterCustomer($"paging-orders-{Guid.NewGuid():N}", $"paging-orders-{Guid.NewGuid():N}@example.com"); var customerResult = await store.SaveAsync(customer, cancellationToken); - var customerId = customerResult.Aggregate.Id(); + var customerId = customerResult.Value.Aggregate.Id(); for (var i = 0; i < orderCount; i++) { diff --git a/src/tests/Samples.IntegrationTests/Domain/CustomerAggregateIntegrationTests.cs b/src/tests/Samples.IntegrationTests/Domain/CustomerAggregateIntegrationTests.cs index 14d1471a..f20db852 100644 --- a/src/tests/Samples.IntegrationTests/Domain/CustomerAggregateIntegrationTests.cs +++ b/src/tests/Samples.IntegrationTests/Domain/CustomerAggregateIntegrationTests.cs @@ -19,7 +19,8 @@ public async Task SaveAsync_GivenRegisteredCustomer_LoadedStateMatchesOriginal(C var store = fixture.CreateEventStore(); await store.SaveAsync(customer, cancellationToken); - var loaded = await store.GetAsync(id, cancellationToken); + var loadedResult = await store.GetAsync(id, cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.Name).IsEqualTo("Jane Smith"); @@ -40,9 +41,10 @@ public async Task SaveAsync_GivenCustomerWithPhoneNumber_LoadedPhoneMatches(Canc var store = fixture.CreateEventStore(); var result = await store.SaveAsync(customer, cancellationToken); - await Assert.That(result.EnsureValid).ThrowsNothing(); + await Assert.That(result.IsSuccess).IsTrue(); - var loaded = await store.GetAsync(id, cancellationToken); + var loadedResult = await store.GetAsync(id, cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.PhoneNumber).IsEqualTo("+1-555-0199"); @@ -63,7 +65,8 @@ CancellationToken cancellationToken var store = fixture.CreateEventStore(); await store.SaveAsync(customer, cancellationToken); - var loaded = await store.GetAsync(id, cancellationToken); + var loadedResult = await store.GetAsync(id, cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.Email).IsEqualTo("v3@test.com"); @@ -81,7 +84,8 @@ public async Task SaveAsync_GivenDeactivatedCustomer_LoadedIsActiveFalse(Cancell var store = fixture.CreateEventStore(); await store.SaveAsync(customer, cancellationToken); - var loaded = await store.GetAsync(id, cancellationToken); + var loadedResult = await store.GetAsync(id, cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.IsActive).IsFalse(); @@ -100,7 +104,8 @@ public async Task SaveAsync_GivenReactivatedCustomer_LoadedIsActiveTrue(Cancella var store = fixture.CreateEventStore(); await store.SaveAsync(customer, cancellationToken); - var loaded = await store.GetAsync(id, cancellationToken); + var loadedResult = await store.GetAsync(id, cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.IsActive).IsTrue(); @@ -123,9 +128,10 @@ public async Task SaveAsync_GivenMultipleOperations_VersionIsTrackedCorrectly(Ca var store = fixture.CreateEventStore(); var result = await store.SaveAsync(customer, cancellationToken); - await Assert.That(result.EnsureValid).ThrowsNothing(); + await Assert.That(result.IsSuccess).IsTrue(); - var loaded = await store.GetAsync(id, cancellationToken); + var loadedResult = await store.GetAsync(id, cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.Details.SavedVersion).IsEqualTo(3); @@ -148,7 +154,7 @@ public async Task DeleteAsync_GivenSavedCustomer_AggregateIsMarkedDeleted(Cancel await store.SaveAsync(customer, cancellationToken); await store.DeleteAsync(customer, cancellationToken); - var isDeleted = await store.IsDeletedAsync(id, cancellationToken); + var isDeleted = (await store.ExistsAsync(id, cancellationToken)).IsDeleted; await Assert.That(isDeleted).IsTrue(); } @@ -167,14 +173,16 @@ CancellationToken cancellationToken await store.SaveAsync(customer, cancellationToken); await store.DeleteAsync(customer, cancellationToken); - var deleted = await store.GetDeletedAsync(id, cancellationToken); + var deletedResult = await store.GetDeletedAsync(id, cancellationToken); + var deleted = deletedResult.IsSuccess ? deletedResult.Value : null; await store.RestoreAsync(deleted!, cancellationToken); - var restored = await store.GetAsync(id, cancellationToken); + var restoredResult = await store.GetAsync(id, cancellationToken); + var restored = restoredResult.IsSuccess ? restoredResult.Value : null; await Assert.That(restored).IsNotNull(); await Assert.That(restored!.Name).IsEqualTo("Grace"); - await Assert.That(await store.IsDeletedAsync(id, cancellationToken)).IsFalse(); + await Assert.That((await store.ExistsAsync(id, cancellationToken)).IsDeleted).IsFalse(); } #endregion @@ -195,7 +203,8 @@ CancellationToken cancellationToken var store = fixture.CreateEventStore(); await store.SaveAsync(customer, cancellationToken); - var atVersion1 = await store.GetAtAsync(id, 1, cancellationToken); + var atVersion1Result = await store.GetAtAsync(id, 1, cancellationToken); + var atVersion1 = atVersion1Result.IsSuccess ? atVersion1Result.Value : null; await Assert.That(atVersion1).IsNotNull(); await Assert.That(atVersion1!.Email).IsEqualTo("original@test.com"); @@ -222,7 +231,8 @@ CancellationToken cancellationToken var store = fixture.CreateSnapshotStore(snapshotStrategy: new AlwaysSnapshotStrategy()); await store.SaveAsync(customer, cancellationToken); - var loaded = await store.GetAsync(id, cancellationToken); + var loadedResult = await store.GetAsync(id, cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.Name).IsEqualTo("Ivan"); diff --git a/src/tests/Samples.IntegrationTests/Domain/InventoryAggregateIntegrationTests.cs b/src/tests/Samples.IntegrationTests/Domain/InventoryAggregateIntegrationTests.cs index cb862dc6..0c5fd01a 100644 --- a/src/tests/Samples.IntegrationTests/Domain/InventoryAggregateIntegrationTests.cs +++ b/src/tests/Samples.IntegrationTests/Domain/InventoryAggregateIntegrationTests.cs @@ -29,7 +29,8 @@ public async Task SaveAsync_GivenInitializedInventory_LoadedQuantitiesMatch(Canc var store = fixture.CreateEventStore(); await store.SaveAsync(inv, cancellationToken); - var loaded = await store.GetAsync(inv.Id(), cancellationToken); + var loadedResult = await store.GetAsync(inv.Id(), cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.ProductId).IsEqualTo("prod-1"); @@ -50,7 +51,8 @@ CancellationToken cancellationToken var store = fixture.CreateEventStore(); await store.SaveAsync(inv, cancellationToken); - var loaded = await store.GetAsync(inv.Id(), cancellationToken); + var loadedResult = await store.GetAsync(inv.Id(), cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.QuantityOnHand).IsEqualTo(100); @@ -71,7 +73,8 @@ CancellationToken cancellationToken var store = fixture.CreateEventStore(); await store.SaveAsync(inv, cancellationToken); - var loaded = await store.GetAsync(inv.Id(), cancellationToken); + var loadedResult = await store.GetAsync(inv.Id(), cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.QuantityOnHand).IsEqualTo(140); @@ -91,7 +94,8 @@ CancellationToken cancellationToken var store = fixture.CreateEventStore(); await store.SaveAsync(inv, cancellationToken); - var loaded = await store.GetAsync(inv.Id(), cancellationToken); + var loadedResult = await store.GetAsync(inv.Id(), cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.QuantityOnHand).IsEqualTo(20); @@ -111,7 +115,8 @@ CancellationToken cancellationToken var store = fixture.CreateEventStore(); await store.SaveAsync(inv, cancellationToken); - var loaded = await store.GetAsync(inv.Id(), cancellationToken); + var loadedResult = await store.GetAsync(inv.Id(), cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.ReservedQuantity).IsEqualTo(0); @@ -132,7 +137,8 @@ public async Task SaveAsync_GivenMultipleOperations_VersionIsTrackedCorrectly(Ca var store = fixture.CreateEventStore(); await store.SaveAsync(inv, cancellationToken); - var loaded = await store.GetAsync(inv.Id(), cancellationToken); + var loadedResult = await store.GetAsync(inv.Id(), cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.Details.SavedVersion).IsEqualTo(3); @@ -155,7 +161,8 @@ CancellationToken cancellationToken var store = fixture.CreateEventStore(); await store.SaveAsync(inv, cancellationToken); - var atV1 = await store.GetAtAsync(id, 1, cancellationToken); + var atV1Result = await store.GetAtAsync(id, 1, cancellationToken); + var atV1 = atV1Result.IsSuccess ? atV1Result.Value : null; await Assert.That(atV1).IsNotNull(); await Assert.That(atV1!.QuantityOnHand).IsEqualTo(100); @@ -179,7 +186,8 @@ CancellationToken cancellationToken var store = fixture.CreateSnapshotStore(snapshotStrategy: new AlwaysSnapshotStrategy()); await store.SaveAsync(inv, cancellationToken); - var loaded = await store.GetAsync(inv.Id(), cancellationToken); + var loadedResult = await store.GetAsync(inv.Id(), cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.QuantityOnHand).IsEqualTo(250); diff --git a/src/tests/Samples.IntegrationTests/Domain/MultiAggregateIntegrationTests.cs b/src/tests/Samples.IntegrationTests/Domain/MultiAggregateIntegrationTests.cs index 8bb902e0..2280a100 100644 --- a/src/tests/Samples.IntegrationTests/Domain/MultiAggregateIntegrationTests.cs +++ b/src/tests/Samples.IntegrationTests/Domain/MultiAggregateIntegrationTests.cs @@ -65,9 +65,12 @@ CancellationToken cancellationToken await orderStore.SaveAsync(order, cancellationToken); // Act: Reload all three aggregates from their respective stores - var loadedCustomer = await customerStore.GetAsync(customer.Id(), cancellationToken); - var loadedInventory = await inventoryStore.GetAsync(inventory.Id(), cancellationToken); - var loadedOrder = await orderStore.GetAsync(order.Id(), cancellationToken); + var loadedCustomerResult = await customerStore.GetAsync(customer.Id(), cancellationToken); + var loadedCustomer = loadedCustomerResult.IsSuccess ? loadedCustomerResult.Value : null; + var loadedInventoryResult = await inventoryStore.GetAsync(inventory.Id(), cancellationToken); + var loadedInventory = loadedInventoryResult.IsSuccess ? loadedInventoryResult.Value : null; + var loadedOrderResult = await orderStore.GetAsync(order.Id(), cancellationToken); + var loadedOrder = loadedOrderResult.IsSuccess ? loadedOrderResult.Value : null; // Assert: Customer await Assert.That(loadedCustomer).IsNotNull(); @@ -122,8 +125,10 @@ CancellationToken cancellationToken await inventoryStore.SaveAsync(inventory, cancellationToken); // Act: Reload - var loadedOrder = await orderStore.GetAsync(order.Id(), cancellationToken); - var loadedInventory = await inventoryStore.GetAsync(inventory.Id(), cancellationToken); + var loadedOrderResult = await orderStore.GetAsync(order.Id(), cancellationToken); + var loadedOrder = loadedOrderResult.IsSuccess ? loadedOrderResult.Value : null; + var loadedInventoryResult = await inventoryStore.GetAsync(inventory.Id(), cancellationToken); + var loadedInventory = loadedInventoryResult.IsSuccess ? loadedInventoryResult.Value : null; // Assert await Assert.That(loadedOrder).IsNotNull(); @@ -161,8 +166,10 @@ CancellationToken cancellationToken await customerStore.SaveAsync(customer, cancellationToken); // Reload both - var loadedCustomer = await customerStore.GetAsync(customer.Id(), cancellationToken); - var loadedOrder = await orderStore.GetAsync(order.Id(), cancellationToken); + var loadedCustomerResult = await customerStore.GetAsync(customer.Id(), cancellationToken); + var loadedCustomer = loadedCustomerResult.IsSuccess ? loadedCustomerResult.Value : null; + var loadedOrderResult = await orderStore.GetAsync(order.Id(), cancellationToken); + var loadedOrder = loadedOrderResult.IsSuccess ? loadedOrderResult.Value : null; await Assert.That(loadedCustomer).IsNotNull(); await Assert.That(loadedCustomer!.IsActive).IsFalse(); diff --git a/src/tests/Samples.IntegrationTests/Domain/OrderAggregateIntegrationTests.cs b/src/tests/Samples.IntegrationTests/Domain/OrderAggregateIntegrationTests.cs index d9b94801..50806e48 100644 --- a/src/tests/Samples.IntegrationTests/Domain/OrderAggregateIntegrationTests.cs +++ b/src/tests/Samples.IntegrationTests/Domain/OrderAggregateIntegrationTests.cs @@ -1,3 +1,4 @@ +using System.Diagnostics.CodeAnalysis; using Purview.EventSourcing.Aggregates.Snapshotting; using Purview.EventSourcing.Fixtures.SqlServer; using Purview.EventSourcing.Samples.ValueObjects; @@ -22,6 +23,11 @@ static OrderAggregate CreateDraftWithItems(string id) #region Round-Trip Persistence [Test] + [SuppressMessage( + "Maintainability", + "CA1506:Avoid excessive class coupling", + Justification = "Test wiring: the store, its infrastructure and the result model are all named here." + )] public async Task SaveAsync_GivenDraftOrderWithLineItems_LoadedLineItemsMatch(CancellationToken cancellationToken) { var id = $"{Guid.NewGuid()}"; @@ -30,7 +36,8 @@ public async Task SaveAsync_GivenDraftOrderWithLineItems_LoadedLineItemsMatch(Ca var store = fixture.CreateEventStore(); await store.SaveAsync(order, cancellationToken); - var loaded = await store.GetAsync(id, cancellationToken); + var loadedResult = await store.GetAsync(id, cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.CustomerId).IsEqualTo("customer-1"); @@ -56,7 +63,8 @@ public async Task SaveAsync_GivenDraftOrderWithNullableNotes_LoadedNotesMatch(Ca var store = fixture.CreateEventStore(); await store.SaveAsync(order, cancellationToken); - var loaded = await store.GetAsync(id, cancellationToken); + var loadedResult = await store.GetAsync(id, cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.Notes).IsEqualTo("Rush delivery"); @@ -72,7 +80,8 @@ public async Task SaveAsync_GivenConfirmedOrder_LoadedStatusIsConfirmed(Cancella var store = fixture.CreateEventStore(); await store.SaveAsync(order, cancellationToken); - var loaded = await store.GetAsync(id, cancellationToken); + var loadedResult = await store.GetAsync(id, cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.Status).IsEqualTo(OrderStatus.Confirmed); @@ -90,7 +99,8 @@ public async Task SaveAsync_GivenShippedOrder_LoadedShippedAtAndStatusMatch(Canc var store = fixture.CreateEventStore(); await store.SaveAsync(order, cancellationToken); - var loaded = await store.GetAsync(id, cancellationToken); + var loadedResult = await store.GetAsync(id, cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.Status).IsEqualTo(OrderStatus.Shipped); @@ -111,7 +121,8 @@ public async Task SaveAsync_GivenFullLifecycleOrder_LoadedStateMatchesFinal(Canc var store = fixture.CreateEventStore(); await store.SaveAsync(order, cancellationToken); - var loaded = await store.GetAsync(id, cancellationToken); + var loadedResult = await store.GetAsync(id, cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.Status).IsEqualTo(OrderStatus.Completed); @@ -131,7 +142,8 @@ public async Task SaveAsync_GivenCancelledOrder_LoadedStatusIsCancelled(Cancella var store = fixture.CreateEventStore(); await store.SaveAsync(order, cancellationToken); - var loaded = await store.GetAsync(id, cancellationToken); + var loadedResult = await store.GetAsync(id, cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.Status).IsEqualTo(OrderStatus.Cancelled); @@ -149,7 +161,8 @@ CancellationToken cancellationToken var store = fixture.CreateEventStore(); await store.SaveAsync(order, cancellationToken); - var loaded = await store.GetAsync(id, cancellationToken); + var loadedResult = await store.GetAsync(id, cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.LineItems).Count().IsEqualTo(1); @@ -175,7 +188,8 @@ public async Task SaveAsync_GivenFullLifecycleOrder_VersionMatchesEventCount(Can var store = fixture.CreateEventStore(); await store.SaveAsync(order, cancellationToken); - var loaded = await store.GetAsync(id, cancellationToken); + var loadedResult = await store.GetAsync(id, cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.Details.SavedVersion).IsEqualTo(7); @@ -197,7 +211,8 @@ public async Task GetAtAsync_GivenOrderAtVersion1_ReturnsDraftStatusWithNoItems( await store.SaveAsync(order, cancellationToken); // At version 1, only CreateOrder has been applied - var atV1 = await store.GetAtAsync(id, 1, cancellationToken); + var atV1Result = await store.GetAtAsync(id, 1, cancellationToken); + var atV1 = atV1Result.IsSuccess ? atV1Result.Value : null; await Assert.That(atV1).IsNotNull(); await Assert.That(atV1!.Status).IsEqualTo(OrderStatus.Draft); @@ -219,7 +234,8 @@ CancellationToken cancellationToken await store.SaveAsync(order, cancellationToken); // At version 3 (after two AddLineItem), status is still Draft - var atV3 = await store.GetAtAsync(id, 3, cancellationToken); + var atV3Result = await store.GetAtAsync(id, 3, cancellationToken); + var atV3 = atV3Result.IsSuccess ? atV3Result.Value : null; await Assert.That(atV3).IsNotNull(); await Assert.That(atV3!.Status).IsEqualTo(OrderStatus.Draft); @@ -243,7 +259,8 @@ CancellationToken cancellationToken var store = fixture.CreateSnapshotStore(snapshotStrategy: new AlwaysSnapshotStrategy()); await store.SaveAsync(order, cancellationToken); - var loaded = await store.GetAsync(id, cancellationToken); + var loadedResult = await store.GetAsync(id, cancellationToken); + var loaded = loadedResult.IsSuccess ? loadedResult.Value : null; await Assert.That(loaded).IsNotNull(); await Assert.That(loaded!.Status).IsEqualTo(OrderStatus.Confirmed); diff --git a/src/tests/Samples.IntegrationTests/ValueObjects/UserCaptureTests.cs b/src/tests/Samples.IntegrationTests/ValueObjects/UserCaptureTests.cs index 396fcfec..e8ef02f7 100644 --- a/src/tests/Samples.IntegrationTests/ValueObjects/UserCaptureTests.cs +++ b/src/tests/Samples.IntegrationTests/ValueObjects/UserCaptureTests.cs @@ -1,4 +1,4 @@ -using Purview.EventSourcing.Fixtures.SqlServer; +using Purview.EventSourcing.Fixtures.SqlServer; namespace Purview.EventSourcing.Samples.ValueObjects; @@ -30,7 +30,8 @@ public async Task UserCapture_GivenComplexValueObject_CanStoreAndRetrieveInEF(Ca // Act await eventStore.SnapshotAsync(aggregate, cancellationToken); - var retrievedAggregate = await eventStore.GetAsync(aggregate.Id(), cancellationToken); + var retrievedAggregateResult = await eventStore.GetAsync(aggregate.Id(), cancellationToken); + var retrievedAggregate = retrievedAggregateResult.IsSuccess ? retrievedAggregateResult.Value : null; // Assert await Assert.That(retrievedAggregate).IsNotNull(); diff --git a/src/tests/Samples.UnitTests/Domain/OrderAggregateTests.cs b/src/tests/Samples.UnitTests/Domain/OrderAggregateTests.cs index 3e45f522..4b7e6a7c 100644 --- a/src/tests/Samples.UnitTests/Domain/OrderAggregateTests.cs +++ b/src/tests/Samples.UnitTests/Domain/OrderAggregateTests.cs @@ -15,7 +15,12 @@ static OrderAggregate CreateOrder( if (id is not null) order.Details.Id = id; - order.CreateOrder("customer-1").SetShippingAddress(shippingAddress: shippingAddress); + order.CreateOrder("customer-1"); + + // Only when one was asked for: SetShippingAddress normalizes null to an empty string, so + // calling it unconditionally would raise an extra event and leave ShippingAddress non-null. + if (shippingAddress is not null) + order.SetShippingAddress(shippingAddress: shippingAddress); if (withItems) { diff --git a/src/tests/Samples.UnitTests/Services/OrderFulfilmentServiceTests.cs b/src/tests/Samples.UnitTests/Services/OrderFulfilmentServiceTests.cs index 4139aba2..586eef48 100644 --- a/src/tests/Samples.UnitTests/Services/OrderFulfilmentServiceTests.cs +++ b/src/tests/Samples.UnitTests/Services/OrderFulfilmentServiceTests.cs @@ -1,5 +1,6 @@ using System.Diagnostics.CodeAnalysis; using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.Samples.Domain; using Purview.EventSourcing.Samples.ValueObjects; @@ -61,7 +62,11 @@ public async Task PlaceOrderAsync_GivenNullCustomer_ReturnsFail(CancellationToke var store = IQueryableEventStore.Mock(); store .GetAsync(Is("missing"), Any(), Is(cancellationToken)) - .Returns((CustomerAggregate?)null); + .Returns( + AggregateReadFailure.Failure( + new AggregateNotFound(nameof(CustomerAggregate), "missing") + ) + ); var result = await CreateService(store: store).PlaceOrderAsync("missing", "inv-1", 1, null, cancellationToken); @@ -97,7 +102,11 @@ public async Task PlaceOrderAsync_GivenNullInventory_ReturnsFail(CancellationTok .Returns(customer); store .GetAsync(Is("missing-inv"), Any(), Is(cancellationToken)) - .Returns((InventoryAggregate?)null); + .Returns( + AggregateReadFailure.Failure( + new AggregateNotFound(nameof(InventoryAggregate), "missing") + ) + ); var result = await CreateService(store: store) .PlaceOrderAsync(customer.Id(), "missing-inv", 1, null, cancellationToken); @@ -128,6 +137,11 @@ public async Task PlaceOrderAsync_GivenInsufficientStock_ReturnsFail(Cancellatio } [Test] + [SuppressMessage( + "Maintainability", + "CA1506:Avoid excessive class coupling", + Justification = "Test wiring: the store, its infrastructure and the result model are all named here." + )] public async Task PlaceOrderAsync_GivenValidData_ReturnsSuccess(CancellationToken cancellationToken) { var customer = ActiveCustomer(); @@ -227,6 +241,11 @@ CancellationToken cancellationToken } [Test] + [SuppressMessage( + "Maintainability", + "CA1506:Avoid excessive class coupling", + Justification = "Test wiring: the store, its infrastructure and the result model are all named here." + )] public async Task PlaceOrderAsync_WhenTransactionCommitFails_DoesNotCancelOrderInMemory( CancellationToken cancellationToken ) diff --git a/src/tests/Samples.UnitTests/Services/StockTransferServiceTests.cs b/src/tests/Samples.UnitTests/Services/StockTransferServiceTests.cs index ca359583..93ef0262 100644 --- a/src/tests/Samples.UnitTests/Services/StockTransferServiceTests.cs +++ b/src/tests/Samples.UnitTests/Services/StockTransferServiceTests.cs @@ -1,6 +1,7 @@ using System.Diagnostics.CodeAnalysis; using System.Linq.Expressions; using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Failures; using Purview.EventSourcing.Samples.Domain; namespace Purview.EventSourcing.Samples.Services; @@ -75,7 +76,11 @@ public async Task TransferAsync_GivenNullSource_ReturnsFail(CancellationToken ca var store = IQueryableEventStore.Mock(); store .GetAsync(Is("missing"), Any(), Is(cancellationToken)) - .Returns((InventoryAggregate?)null); + .Returns( + AggregateReadFailure.Failure( + new AggregateNotFound(nameof(InventoryAggregate), "missing") + ) + ); var result = await CreateService(store: store).TransferAsync("missing", "inv-2", 5, "test", cancellationToken); @@ -97,7 +102,11 @@ public async Task TransferAsync_GivenNullDestination_ReturnsFail(CancellationTok .Returns(sourceLocation); store .GetAsync(Is("missing"), Any(), Is(cancellationToken)) - .Returns((LocationAggregate?)null); + .Returns( + AggregateReadFailure.Failure( + new AggregateNotFound(nameof(LocationAggregate), "missing") + ) + ); var result = await CreateService(store: store).TransferAsync("inv-1", "missing", 5, "test", cancellationToken); @@ -116,7 +125,11 @@ public async Task TransferAsync_GivenMissingSourceLocationAggregate_ReturnsFail( .Returns(source); store .GetAsync(Is("LOC-001"), Any(), Is(cancellationToken)) - .Returns((LocationAggregate?)null); + .Returns( + AggregateReadFailure.Failure( + new AggregateNotFound(nameof(LocationAggregate), "missing") + ) + ); store .GetAsync(Is("LOC-002"), Any(), Is(cancellationToken)) .Returns(destinationLocation); @@ -289,6 +302,11 @@ CancellationToken cancellationToken } [Test] + [SuppressMessage( + "Maintainability", + "CA1506:Avoid excessive class coupling", + Justification = "Test wiring: the store, its infrastructure and the result model are all named here." + )] public async Task TransferAsync_WhenTransactionCommitFails_ReturnsFail(CancellationToken cancellationToken) { var source = StockedItem("inv-1", "LOC-001", "Warehouse North", 100); diff --git a/src/tests/Samples.UnitTests/ValueObjects/BlobUriTests.cs b/src/tests/Samples.UnitTests/ValueObjects/BlobUriTests.cs index fea2a048..074c66e4 100644 --- a/src/tests/Samples.UnitTests/ValueObjects/BlobUriTests.cs +++ b/src/tests/Samples.UnitTests/ValueObjects/BlobUriTests.cs @@ -1,4 +1,4 @@ -namespace Purview.EventSourcing.Samples.ValueObjects; +namespace Purview.EventSourcing.Samples.ValueObjects; public sealed class BlobUriTests { diff --git a/src/tests/SharedTestingFramework/Aggregates/ComplexNestedTestType.cs b/src/tests/SharedTestingFramework/Aggregates/ComplexNestedTestType.cs index c925a57d..e808e060 100644 --- a/src/tests/SharedTestingFramework/Aggregates/ComplexNestedTestType.cs +++ b/src/tests/SharedTestingFramework/Aggregates/ComplexNestedTestType.cs @@ -1,4 +1,4 @@ -namespace Purview.EventSourcing.Aggregates; +namespace Purview.EventSourcing.Aggregates; public class ComplexNestedTestType { diff --git a/src/tests/SharedTestingFramework/Aggregates/ComplexTestType.cs b/src/tests/SharedTestingFramework/Aggregates/ComplexTestType.cs index 8033bed4..9724e0cf 100644 --- a/src/tests/SharedTestingFramework/Aggregates/ComplexTestType.cs +++ b/src/tests/SharedTestingFramework/Aggregates/ComplexTestType.cs @@ -1,4 +1,4 @@ -namespace Purview.EventSourcing.Aggregates; +namespace Purview.EventSourcing.Aggregates; public class ComplexTestType { diff --git a/src/tests/SharedTestingFramework/Aggregates/IAggregateTest.cs b/src/tests/SharedTestingFramework/Aggregates/IAggregateTest.cs index 6f157b32..2cd98d31 100644 --- a/src/tests/SharedTestingFramework/Aggregates/IAggregateTest.cs +++ b/src/tests/SharedTestingFramework/Aggregates/IAggregateTest.cs @@ -1,4 +1,4 @@ -using Microsoft.Extensions.Primitives; +using Microsoft.Extensions.Primitives; namespace Purview.EventSourcing.Aggregates; diff --git a/src/tests/SharedTestingFramework/Aggregates/Persistence/Events/SubjectNameSetEvent.cs b/src/tests/SharedTestingFramework/Aggregates/Persistence/Events/SubjectNameSetEvent.cs new file mode 100644 index 00000000..301d551f --- /dev/null +++ b/src/tests/SharedTestingFramework/Aggregates/Persistence/Events/SubjectNameSetEvent.cs @@ -0,0 +1,24 @@ +using System.Text.Json.Serialization; +using Purview.EventSourcing.Aggregates.Events; +using Purview.EventSourcing.Cryptography; + +namespace Purview.EventSourcing.Aggregates.Persistence.Events; + +/// +/// An event carrying personal data, used to exercise crypto-shredding. +/// +[EventContract] +public sealed record SubjectNameSetEvent : IEventDataSubject +{ + public static int SchemaVersion => 1; + + [JsonIgnore] + public EventMetadata Metadata { get; init; } + + public string Name { get; set; } = default!; + + /// + /// The subject the name belongs to. Serialized, because it is the key identifier replay needs. + /// + public string DataSubjectId { get; set; } = default!; +} diff --git a/src/tests/SharedTestingFramework/Aggregates/Persistence/PersistenceAggregate.cs b/src/tests/SharedTestingFramework/Aggregates/Persistence/PersistenceAggregate.cs index c012fd02..888b2594 100644 --- a/src/tests/SharedTestingFramework/Aggregates/Persistence/PersistenceAggregate.cs +++ b/src/tests/SharedTestingFramework/Aggregates/Persistence/PersistenceAggregate.cs @@ -1,4 +1,4 @@ -using System.ComponentModel.DataAnnotations; +using System.ComponentModel.DataAnnotations; using System.Text.Json.Serialization; using Microsoft.Extensions.Primitives; using Purview.EventSourcing.Aggregates.Persistence.Events; @@ -31,6 +31,12 @@ public sealed class PersistenceAggregate : AggregateBase, IAggregateTest [JsonInclude] public ComplexTestType? ComplexTestType { get; private set; } + [JsonInclude] + public string? SubjectName { get; private set; } + + public void SetSubjectName(string name, string dataSubjectId) => + RecordAndApply(new SubjectNameSetEvent { Name = name, DataSubjectId = dataSubjectId }); + public void RegisterOldEventType() { Register(Apply); @@ -45,6 +51,7 @@ protected override void RegisterEvents() Register(@event => ComplexTestType = @event.ComplexProperty); Register(Apply); Register(Apply); + Register(@event => SubjectName = @event.Name); } void Apply(StringValueKVPsAddedEvent obj) diff --git a/src/tests/SharedTestingFramework/ContainerHelper.Resources.cs b/src/tests/SharedTestingFramework/ContainerHelper.Resources.cs index f164ce05..8fb5f4d0 100644 --- a/src/tests/SharedTestingFramework/ContainerHelper.Resources.cs +++ b/src/tests/SharedTestingFramework/ContainerHelper.Resources.cs @@ -11,4 +11,13 @@ partial class ContainerHelper public const string CosmosDbImageTag = "vnext-latest"; public const string MongoDBImageTag = "8.0"; + + public const string MongoDBReplicaSetName = "rs0"; + + /// + /// The published development account key every Azure Storage emulator accepts. It is a fixed, + /// documented constant rather than a credential. + /// + public const string AzuriteWellKnownAccountKey = + "Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw=="; } diff --git a/src/tests/SharedTestingFramework/ContainerHelper.cs b/src/tests/SharedTestingFramework/ContainerHelper.cs index 586cea3c..1dc4b295 100644 --- a/src/tests/SharedTestingFramework/ContainerHelper.cs +++ b/src/tests/SharedTestingFramework/ContainerHelper.cs @@ -1,114 +1,116 @@ -using DotNet.Testcontainers.Builders; -using DotNet.Testcontainers.Configurations; -using DotNet.Testcontainers.Containers; -using Testcontainers.Azurite; -using Testcontainers.CosmosDb; -using Testcontainers.MongoDb; -using Testcontainers.MsSql; -using Testcontainers.PostgreSql; +using Purview.Containers; +using Purview.Containers.Azurite; +using Purview.Containers.MsSql; +using Purview.Containers.PostgreSql; +using Purview.Containers.Waiting; namespace Purview.EventSourcing; +/// +/// Creates the throwaway containers the integration suites run against, through Purview.Containers - +/// which selects WSL Containers on a Windows host and Docker everywhere else. +/// public static partial class ContainerHelper { public static AzuriteContainer CreateAzurite(Action? config = null) { - // Note: Testcontainers.Azurite's default command already binds the emulator to 0.0.0.0 and - // WithCommand appends to that default. Do not repeat the --blobHost/--queueHost/--tableHost - // flags here: duplicated flags make Azurite fall back to binding 127.0.0.1, which is not - // reachable through Docker's published ports. - var builder = new AzuriteBuilder($"mcr.microsoft.com/azure-storage/azurite:{AzuriteImageTag}").WithCommand( + AzuriteBuilder builder = new($"mcr.microsoft.com/azure-storage/azurite:{AzuriteImageTag}"); + + // WithCommand replaces the module's command, so the host bindings it sets are repeated here + // alongside --skipApiVersionCheck: the Azure Storage SDK sends a newer x-ms-version than this + // Azurite release knows, and rejects every request without it. Each --*Host flag must appear + // exactly once - a duplicate makes Azurite fall back to binding 127.0.0.1 inside the container, + // which is not reachable through the mapped port. + builder.WithCommand( + "azurite", + "--blobHost", + "0.0.0.0", + "--queueHost", + "0.0.0.0", + "--tableHost", + "0.0.0.0", "--skipApiVersionCheck" - ) - //.WithWaitStrategy(Wait.ForUnixContainer() - // .UntilPortIsAvailable(10000) // Blob - // .UntilPortIsAvailable(10001) // Queue - // .UntilPortIsAvailable(10002) // Table - //) - ; + ); config?.Invoke(builder); return builder.Build(); } - public static CosmosDbContainer CreateCosmosDB(Action? config = null) + /// + /// Builds the emulator connection string with the real well-known account key. + /// + /// + /// The module deliberately ships a placeholder for , so the key is + /// supplied here. It is not a secret: it is the published, fixed development key every Azure Storage + /// emulator uses. + /// + public static string GetEmulatorConnectionString(this AzuriteContainer container) { - var builder = new CosmosDbBuilder($"mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:{CosmosDbImageTag}") - .WithWaitStrategy( - Wait.ForUnixContainer() - .AddCustomWaitStrategy(new CosmosDbWaitUntil(), ws => ws.WithTimeout(TimeSpan.FromMinutes(5))) - ) - //.WithAutoRemove(true) - //.WithCleanUp(true) - // The emulator must serve plain HTTP: Testcontainers' connection string and the Cosmos SDK - // gateway reader both use http:// (the PROTOCOL=https emulator only serves HTTPS and is - // unreachable over the published port). - .WithEnvironment("AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE", "false"); - - config?.Invoke(builder); + ArgumentNullException.ThrowIfNull(container); - return builder.Build(); + return container + .GetConnectionString() + .Replace(AzuriteAccount.Key, AzuriteWellKnownAccountKey, StringComparison.Ordinal); } - // The vnext-preview CosmosDB emulator's HTTP server starts before the data engine. - // A 503 "pgcosmos extension is still starting" means the gateway is up but not ready. - // Wait until we get any response other than 503. - sealed class CosmosDbWaitUntil : IWaitUntil + public static MsSqlContainer CreateMsSql(Action? config = null) { - public async Task UntilAsync(IContainer container) - { - // The emulator serves plain HTTP on the gateway; probe it the same way the Cosmos SDK's - // gateway reader connects (via the published port). - var endpoint = new UriBuilder( - Uri.UriSchemeHttp, - container.Hostname, - container.GetMappedPublicPort(CosmosDbBuilder.CosmosDbPort) - ).Uri; - - using HttpClient httpClient = new(); - try - { - using var httpResponse = await httpClient.GetAsync(endpoint).ConfigureAwait(false); - return httpResponse.StatusCode != System.Net.HttpStatusCode.ServiceUnavailable; - } -#pragma warning disable CA1031 - catch -#pragma warning restore CA1031 - { - return false; - } - } + MsSqlBuilder builder = new($"mcr.microsoft.com/mssql/server:{SqlServerImageTag}"); + builder.AcceptLicense(); + + config?.Invoke(builder); + + return builder.Build(); } - public static MongoDbContainer CreateMongoDB(Action? config = null) + public static PostgreSqlContainer CreatePostgreSql(Action? config = null) { - var builder = new MongoDbBuilder($"mongo:{MongoDBImageTag}").WithReplicaSet() - //.WithAutoRemove(true) - //.WithCleanUp(true) - //.WithWaitStrategy(Wait.ForUnixContainer().UntilPortIsAvailable(27017)) - ; + PostgreSqlBuilder builder = new($"postgres:{PostgresImageTag}"); config?.Invoke(builder); return builder.Build(); } - public static MsSqlContainer CreateMsSql(Action? config = null) + public static MongoDBTestContainer CreateMongoDB(Action? config = null) { - MsSqlBuilder builder = new($"mcr.microsoft.com/mssql/server:{SqlServerImageTag}"); + ContainerBuilder builder = new(); + builder + .WithImage($"mongo:{MongoDBImageTag}") + // The event store uses transactions, which MongoDB only offers on a replica set. + .WithCommand("--replSet", MongoDBReplicaSetName, "--bind_ip_all") + .WithPortBinding(MongoDBTestContainer.MongoDBPort, assignRandomHostPort: true) + // Not a TCP probe: the host port is forwarded - and so accepts connections - before mongod + // itself is listening, and the replica-set initiation that follows would then be refused. + // Pinging from inside the container only succeeds once the server answers. + .WithWaitStrategy(Wait.ForCommand("mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok")); config?.Invoke(builder); - return builder.Build(); + return new(builder.Build()); } - public static PostgreSqlContainer CreatePostgreSql(Action? config = null) + public static CosmosDbTestContainer CreateCosmosDB(Action? config = null) { - PostgreSqlBuilder builder = new($"postgres:{PostgresImageTag}"); + ContainerBuilder builder = new(); + builder + .WithImage($"mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:{CosmosDbImageTag}") + .WithEnvironment("AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE", "false") + .WithPortBinding(CosmosDbTestContainer.CosmosDbPort, assignRandomHostPort: true) + .WithStartupTimeout(TimeSpan.FromMinutes(5)) + // The vnext emulator's HTTP gateway answers before its data engine is up, returning 503 + // ("pgcosmos extension is still starting"); anything else means it is ready. + .WithWaitStrategy( + Wait.ForHttp("/") + .ForPort(CosmosDbTestContainer.CosmosDbPort) + .ForStatusPredicate(static status => status != (int)System.Net.HttpStatusCode.ServiceUnavailable) + .AllowInsecureTls() + .WithTimeout(TimeSpan.FromMinutes(5)) + ); config?.Invoke(builder); - return builder.Build(); + return new(builder.Build()); } } diff --git a/src/tests/SharedTestingFramework/Contracts/EventStoreContractTestsBase.cs b/src/tests/SharedTestingFramework/Contracts/EventStoreContractTestsBase.cs index a17c13aa..2426bc0c 100644 --- a/src/tests/SharedTestingFramework/Contracts/EventStoreContractTestsBase.cs +++ b/src/tests/SharedTestingFramework/Contracts/EventStoreContractTestsBase.cs @@ -1,5 +1,6 @@ using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.ChangeFeed; +using Purview.EventSourcing.Failures; namespace Purview.EventSourcing.Contracts; @@ -39,6 +40,42 @@ CancellationToken cancellationToken ) => throw new NotSupportedException($"{GetType().Name} does not support marking stored event types as unknown."); #pragma warning restore CA1506 + [Test] + public async Task SaveAsync_GivenAggregateLoadedBeforeAnotherWriterSaved_ReturnsConcurrencyConflict( + CancellationToken cancellationToken + ) + { + // Arrange + var aggregateId = $"{Guid.NewGuid()}"; + var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); + aggregate.IncrementInt32Value(); + + var eventStore = CreateEventStore(); + await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); + + var firstResult = await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken); + var secondResult = await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken); + + await Assert.That(firstResult.IsSuccess).IsTrue(); + await Assert.That(secondResult.IsSuccess).IsTrue(); + + var first = firstResult.Value; + var second = secondResult.Value; + + first.IncrementInt32Value(); + second.IncrementInt32Value(); + + // Act + var firstSave = await eventStore.SaveAsync(first, cancellationToken: cancellationToken); + var secondSave = await eventStore.SaveAsync(second, cancellationToken: cancellationToken); + + // Assert - the second writer read the same version, so its write loses. It must lose as the + // shared ConcurrencyConflict case: a caller handles it without referencing a provider assembly. + await Assert.That(firstSave.IsSuccess).IsTrue(); + await Assert.That(secondSave.IsFailure).IsTrue(); + await Assert.That(secondSave.Error is ConcurrencyConflict).IsTrue(); + } + [Test] public async Task SaveAsync_GivenNewAggregateWithChanges_SavesAggregate(CancellationToken cancellationToken) { @@ -50,13 +87,19 @@ public async Task SaveAsync_GivenNewAggregateWithChanges_SavesAggregate(Cancella var eventStore = CreateEventStore(); // Act - bool result = await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); + var result = await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); // Assert - await Assert.That(result).IsTrue(); + await Assert.That(result.IsSuccess).IsTrue(); await Assert.That(aggregate.IsNew()).IsFalse(); - var aggregateFromEventStore = await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken); + var aggregateFromEventStoreResult = await eventStore.GetAsync( + aggregateId, + cancellationToken: cancellationToken + ); + var aggregateFromEventStore = aggregateFromEventStoreResult.IsSuccess + ? aggregateFromEventStoreResult.Value + : null; await Assert.That(aggregateFromEventStore).IsNotNull(); await Assert.That(aggregateFromEventStore!.Id()).IsEqualTo(aggregate.Id()); @@ -77,10 +120,11 @@ public async Task SaveAsync_GivenAggregateWithNoChanges_DoesNotSave(Cancellation var eventStore = CreateEventStore(); // Act - bool result = await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); + var result = await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); // Assert - await Assert.That(result).IsFalse(); + await Assert.That(result.IsSuccess).IsTrue(); + await Assert.That(result.Value.Kind).IsEqualTo(SaveOutcomeKind.NoChanges); } [Test] @@ -99,7 +143,7 @@ public async Task SaveAsync_GivenAggregateWithNoChanges_DoesNotNotifyChangeFeed( // Assert aggregateChangeNotifier - .AfterSaveAsync(aggregate, Any(), true, Any(), Any()) + .AfterSaveAsync(aggregate, Any(), true, Any(), Any()) .WasNeverCalled(); } @@ -138,7 +182,7 @@ CancellationToken cancellationToken .Callback(() => afterWasCalled = true); // Act - bool result = await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); + var result = await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); // Assert await Assert.That(beforeWasCalled).IsTrue(); @@ -149,7 +193,7 @@ CancellationToken cancellationToken aggregateChangeNotifier .AfterSaveAsync( aggregate, - Any(), + Any(), true, Is(events => events!.Length == eventsToCreate), Any() @@ -172,12 +216,14 @@ CancellationToken cancellationToken var result = await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); // Assert - await Assert.That(result.Saved).IsFalse(); - await Assert.That(result.IsValid).IsFalse(); - await Assert.That((bool)result).IsFalse(); - await Assert.That(result.ValidationResult.Failures).HasSingleItem(); + await Assert.That(result.IsFailure).IsTrue(); + await Assert.That(result.Error is AggregateInvalid).IsTrue(); + + var invalid = result.Error is AggregateInvalid value ? value : default; + + await Assert.That(invalid.ValidationResult.Failures).HasSingleItem(); await Assert - .That(result.ValidationResult.Failures.Single().PropertyName) + .That(invalid.ValidationResult.Failures.Single().PropertyName) .IsEqualTo(nameof(IAggregateTest.IncrementInt32)); } @@ -194,10 +240,11 @@ CancellationToken cancellationToken var eventStore = CreateEventStore(); var result = await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(result.Saved).IsTrue(); + await Assert.That(result.IsSuccess && result.Value.Written).IsTrue(); // Act - var aggregateGetResult = await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken); + var aggregateGetResultResult = await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken); + var aggregateGetResult = aggregateGetResultResult.IsSuccess ? aggregateGetResultResult.Value : null; // Assert await EventStoreTestSeed.AssertComplexPropertyMatches(aggregate, aggregateGetResult); @@ -218,13 +265,19 @@ CancellationToken cancellationToken var eventStore = CreateEventStore(); // Act - bool result = await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); + var result = await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); // Assert - await Assert.That(result).IsTrue(); + await Assert.That(result.IsSuccess).IsTrue(); await Assert.That(aggregate.IsNew()).IsFalse(); - var aggregateFromEventStore = await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken); + var aggregateFromEventStoreResult = await eventStore.GetAsync( + aggregateId, + cancellationToken: cancellationToken + ); + var aggregateFromEventStore = aggregateFromEventStoreResult.IsSuccess + ? aggregateFromEventStoreResult.Value + : null; await Assert .That((aggregateFromEventStore?.StringProperty ?? string.Empty).Length) @@ -248,18 +301,21 @@ CancellationToken cancellationToken var eventStore = CreateEventStore(); // Act - bool result = await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); + var result = await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); // Assert - await Assert.That(result).IsTrue(); + await Assert.That(result.IsSuccess).IsTrue(); await Assert.That(aggregate.IsNew()).IsFalse(); // Re-read the aggregate straight from the event records, bypassing the snapshot. - var aggregateFromEventStore = await eventStore.GetAsync( + var aggregateFromEventStoreResult = await eventStore.GetAsync( aggregateId, new EventStoreOperationContext { SkipSnapshot = true }, cancellationToken: cancellationToken ); + var aggregateFromEventStore = aggregateFromEventStoreResult.IsSuccess + ? aggregateFromEventStoreResult.Value + : null; await Assert .That((aggregateFromEventStore?.StringProperty ?? string.Empty).Length) @@ -303,11 +359,12 @@ CancellationToken cancellationToken await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); // Act - var result = await eventStore.GetAsync( + var resultResult = await eventStore.GetAsync( aggregateId, new EventStoreOperationContext { SkipSnapshot = true }, cancellationToken: cancellationToken ); + var result = resultResult.IsSuccess ? resultResult.Value : null; // Assert await Assert.That(result).IsNotNull(); @@ -349,7 +406,8 @@ CancellationToken cancellationToken await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); // Act - var result = await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken); + var resultResult = await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken); + var result = resultResult.IsSuccess ? resultResult.Value : null; // Assert await Assert.That(result).IsNotNull(); @@ -389,11 +447,12 @@ CancellationToken cancellationToken await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); // Get without using the snapshot, just from the event records. - var result = await eventStore.GetAsync( + var resultResult = await eventStore.GetAsync( aggregateId, new EventStoreOperationContext { SkipSnapshot = true }, cancellationToken: cancellationToken ); + var result = resultResult.IsSuccess ? resultResult.Value : null; // Assert await EventStoreTestSeed.AssertRecreatedWithTotals(result, aggregate, totalEvents); @@ -442,20 +501,19 @@ await MarkEventTypesAsUnknownAsync( ); // Get without using the snapshot, just from the event records. - var result = await eventStore.GetAsync( + var resultResult = await eventStore.GetAsync( aggregateId, new EventStoreOperationContext { SkipSnapshot = true }, cancellationToken: cancellationToken ); + var result = resultResult.IsSuccess ? resultResult.Value : null; // Assert await EventStoreTestSeed.AssertRecreatedWithTotals(result, aggregate, totalEvents); } [Test] - public async Task GetAsync_GivenAggregateIsDeletedAndDeletedModeIsSetToThrow_ThrowsEventStoreAggregateDeletedException( - CancellationToken cancellationToken - ) + public async Task GetAsync_GivenAggregateIsDeleted_ReportsAggregateDeleted(CancellationToken cancellationToken) { // Arrange var aggregateId = $"{Guid.NewGuid()}"; @@ -468,7 +526,7 @@ CancellationToken cancellationToken await eventStore.DeleteAsync(aggregate, cancellationToken: cancellationToken); // Act / Assert - await EventStoreTestSeed.AssertGetAsyncThrowsDeletedException(eventStore, aggregateId, cancellationToken); + await EventStoreTestSeed.AssertGetAsyncReportsDeleted(eventStore, aggregateId, cancellationToken); } [Test] @@ -495,11 +553,12 @@ CancellationToken cancellationToken await Assert.That(aggregate.IncrementInt32).IsEqualTo(previousEventsToCreate + 1); // Act - var result = await eventStore.GetAtAsync( + var resultResult = await eventStore.GetAtAsync( aggregateId, version: previousEventsToCreate, cancellationToken: cancellationToken ); + var result = resultResult.IsSuccess ? resultResult.Value : null; // Assert await Assert.That(result).IsNotNull(); @@ -519,11 +578,12 @@ CancellationToken cancellationToken var eventStore = CreateEventStore(); // Act - var result = await eventStore.GetOrCreateAsync( + var resultResult = await eventStore.GetOrCreateAsync( aggregateId, operationContext: null, cancellationToken: cancellationToken ); + var result = resultResult.IsSuccess ? resultResult.Value : null; // Assert await Assert.That(result).IsNotNull(); @@ -548,7 +608,7 @@ public async Task ExistsAsync_GivenSavedAggregate_ReturnsExists(CancellationToke // Assert await Assert.That(result.DoesExist).IsTrue(); - await Assert.That(result.Status).IsEqualTo(ExistsStatus.Exists); + await Assert.That(result.Status).IsEqualTo(ExistenceStatus.Exists); } [Test] @@ -565,7 +625,8 @@ public async Task GetDeletedAsync_GivenDeletedAggregate_ReturnsAggregate(Cancell await eventStore.DeleteAsync(aggregate, cancellationToken: cancellationToken); // Act - var aggregateResult = await eventStore.GetDeletedAsync(aggregateId, cancellationToken: cancellationToken); + var aggregateResultResult = await eventStore.GetDeletedAsync(aggregateId, cancellationToken: cancellationToken); + var aggregateResult = aggregateResultResult.IsSuccess ? aggregateResultResult.Value : null; // Assert await Assert.That(aggregateResult).IsNotNull(); @@ -574,7 +635,7 @@ public async Task GetDeletedAsync_GivenDeletedAggregate_ReturnsAggregate(Cancell } [Test] - public async Task IsDeletedAsync_GivenDeletedAggregates_ReturnsTrue(CancellationToken cancellationToken) + public async Task ExistsAsync_GivenDeletedAggregate_ReportsExistsInDeletedState(CancellationToken cancellationToken) { // Arrange var aggregateId = $"{Guid.NewGuid()}"; @@ -587,14 +648,14 @@ public async Task IsDeletedAsync_GivenDeletedAggregates_ReturnsTrue(Cancellation await eventStore.DeleteAsync(aggregate, cancellationToken: cancellationToken); // Act - var result = await eventStore.IsDeletedAsync(aggregateId, cancellationToken: cancellationToken); + var result = await eventStore.ExistsAsync(aggregateId, cancellationToken: cancellationToken); // Assert - await Assert.That(result).IsTrue(); + await Assert.That(result.Status).IsEqualTo(ExistenceStatus.ExistsInDeletedState); } [Test] - public async Task IsDeletedAsync_GivenNonDeletedAggregates_ReturnsFalse(CancellationToken cancellationToken) + public async Task ExistsAsync_GivenLiveAggregate_ReportsExists(CancellationToken cancellationToken) { // Arrange var aggregateId = $"{Guid.NewGuid()}"; @@ -606,10 +667,10 @@ public async Task IsDeletedAsync_GivenNonDeletedAggregates_ReturnsFalse(Cancella await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); // Act - var result = await eventStore.IsDeletedAsync(aggregateId, cancellationToken: cancellationToken); + var result = await eventStore.ExistsAsync(aggregateId, cancellationToken: cancellationToken); // Assert - await Assert.That(result).IsFalse(); + await Assert.That(result.Status).IsEqualTo(ExistenceStatus.Exists); } [Test] @@ -627,14 +688,15 @@ CancellationToken cancellationToken await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); await eventStore.DeleteAsync(aggregate, cancellationToken: cancellationToken); - aggregate = await eventStore.GetDeletedAsync(aggregateId, cancellationToken); + var aggregateResult = await eventStore.GetDeletedAsync(aggregateId, cancellationToken); + aggregate = aggregateResult.IsSuccess ? aggregateResult.Value : null; await Assert.That(aggregate).IsNotNull(); // Act var result = await eventStore.RestoreAsync(aggregate!, cancellationToken: cancellationToken); // Assert - await Assert.That(result).IsTrue(); + await Assert.That(result.IsSuccess).IsTrue(); await Assert.That(aggregate.Details.IsDeleted).IsFalse(); await Assert.That(aggregate.Details.SavedVersion).IsEqualTo(3); } @@ -651,15 +713,13 @@ public async Task DeleteAsync_GivenPreviouslySavedAggregate_MarksAsDeleted(Cance await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); - var aggregateResult = - await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken) - ?? throw new NullReferenceException(); + var aggregateResult = (await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken)).Value; // Act var result = await eventStore.DeleteAsync(aggregateResult, cancellationToken: cancellationToken); // Assert - await Assert.That(result).IsTrue(); + await Assert.That(result.IsSuccess).IsTrue(); await Assert.That(aggregateResult.Details.IsDeleted).IsTrue(); await Assert.That(aggregateResult.Details.SavedVersion).IsEqualTo(2); } @@ -711,7 +771,8 @@ public async Task DeleteAsync_GivenAggregateExists_PermanentlyDeletesAllData(Can await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); - aggregate = await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken); + var aggregateResult = await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken); + aggregate = aggregateResult.IsSuccess ? aggregateResult.Value : null; await Assert.That(aggregate).IsNotNull(); // Act @@ -722,10 +783,12 @@ public async Task DeleteAsync_GivenAggregateExists_PermanentlyDeletesAllData(Can ); // Assert - await Assert.That(result).IsTrue(); + await Assert.That(result.IsSuccess).IsTrue(); // The aggregate and all of its data are gone. - await Assert.That(await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken)).IsNull(); + await Assert + .That((await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken)).IsFailure) + .IsTrue(); } [Test] @@ -744,7 +807,8 @@ CancellationToken cancellationToken await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); - aggregate = await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken); + var aggregateResult = await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken); + aggregate = aggregateResult.IsSuccess ? aggregateResult.Value : null; await Assert.That(aggregate).IsNotNull(); // Act @@ -755,10 +819,12 @@ CancellationToken cancellationToken ); // Assert - await Assert.That(result).IsTrue(); + await Assert.That(result.IsSuccess).IsTrue(); // The aggregate and all of its data are gone. - await Assert.That(await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken)).IsNull(); + await Assert + .That((await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken)).IsFailure) + .IsTrue(); } [Test] diff --git a/src/tests/SharedTestingFramework/Contracts/EventStoreTestSeed.cs b/src/tests/SharedTestingFramework/Contracts/EventStoreTestSeed.cs index 8c04781f..b3ef5caf 100644 --- a/src/tests/SharedTestingFramework/Contracts/EventStoreTestSeed.cs +++ b/src/tests/SharedTestingFramework/Contracts/EventStoreTestSeed.cs @@ -1,6 +1,8 @@ using System.Security.Cryptography; using System.Text; using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Failures; +using Purview.Results; namespace Purview.EventSourcing.Contracts; @@ -114,14 +116,14 @@ CancellationToken cancellationToken where TAggregate : class, IAggregateTest, new() { // Act - async Task?> Func() => + async Task, AggregateSaveFailure>> Func() => await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); // Assert await Assert.That(Func).Throws(); } - public static async Task AssertGetAsyncThrowsDeletedException( + public static async Task AssertGetAsyncReportsDeleted( IEventStoreCore eventStore, string aggregateId, CancellationToken cancellationToken @@ -129,17 +131,10 @@ CancellationToken cancellationToken where TAggregate : class, IAggregateTest, new() { // Act - Task Func() => - eventStore.GetAsync( - aggregateId, - new EventStoreOperationContext { DeleteMode = DeleteHandlingMode.ThrowsException }, - cancellationToken: cancellationToken - ); + var result = await eventStore.GetAsync(aggregateId, null, cancellationToken: cancellationToken); // Assert - // Each provider surfaces its own AggregateIsDeletedException type (they do not share a base type), - // so assert on the exception type name as the shared observable. - var exception = await Assert.That(Func).Throws(); - await Assert.That(exception!.GetType().Name).IsEqualTo("AggregateIsDeletedException"); + await Assert.That(result.IsFailure).IsTrue(); + await Assert.That(result.Error is AggregateDeleted).IsTrue(); } } diff --git a/src/tests/SharedTestingFramework/Contracts/SnapshotStoreContractTestsBase.cs b/src/tests/SharedTestingFramework/Contracts/SnapshotStoreContractTestsBase.cs index 70a58393..433aec8f 100644 --- a/src/tests/SharedTestingFramework/Contracts/SnapshotStoreContractTestsBase.cs +++ b/src/tests/SharedTestingFramework/Contracts/SnapshotStoreContractTestsBase.cs @@ -55,14 +55,15 @@ public async Task SaveAsync_GivenNewAggregateWithChanges_SavesAggregate(Cancella aggregate.AppendString(aggregateId); // Act - bool result = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); + var result = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); // Assert - await Assert.That(result).IsTrue(); + await Assert.That(result.IsSuccess).IsTrue(); await Assert.That(aggregate.IsNew()).IsFalse(); // Verify by re-getting the aggregate, knowing that the cache is disabled. - var aggregateFromStore = await store.GetAsync(aggregateId, cancellationToken: cancellationToken); + var aggregateFromStoreResult = await store.GetAsync(aggregateId, cancellationToken: cancellationToken); + var aggregateFromStore = aggregateFromStoreResult.IsSuccess ? aggregateFromStoreResult.Value : null; await Assert.That(aggregateFromStore).IsNotNull(); await Assert.That(aggregateFromStore!.Id()).IsEqualTo(aggregate.Id()); @@ -129,16 +130,17 @@ CancellationToken cancellationToken ); // Act - bool saveResult = await store.SaveAsync( + var saveResult = await store.SaveAsync( aggregate, CreateOperationContext(), cancellationToken: cancellationToken ); // Assert - await Assert.That(saveResult).IsTrue(); + await Assert.That(saveResult.IsSuccess).IsTrue(); - var fromDb = await store.GetAsync(aggregateId, cancellationToken: cancellationToken); + var fromDbResult = await store.GetAsync(aggregateId, cancellationToken: cancellationToken); + var fromDb = fromDbResult.IsSuccess ? fromDbResult.Value : null; await Assert.That(fromDb).IsNotNull(); await Assert.That(fromDb.IncrementInt32).IsEqualTo(3); @@ -168,12 +170,12 @@ public async Task SaveAsync_GivenMultipleSavesOfSameAggregate_UpdatesSnapshot(Ca var aggregate = CreateAggregate(id: aggregateId); aggregate.IncrementInt32Value(); - bool firstSave = await store.SaveAsync( + var firstSave = await store.SaveAsync( aggregate, CreateOperationContext(), cancellationToken: cancellationToken ); - await Assert.That(firstSave).IsTrue(); + await Assert.That(firstSave.IsSuccess).IsTrue(); var firstVersion = aggregate.Details.CurrentVersion; @@ -181,15 +183,16 @@ public async Task SaveAsync_GivenMultipleSavesOfSameAggregate_UpdatesSnapshot(Ca aggregate.IncrementInt32Value(); aggregate.SetInt32Value(99); - bool secondSave = await store.SaveAsync( + var secondSave = await store.SaveAsync( aggregate, CreateOperationContext(), cancellationToken: cancellationToken ); - await Assert.That(secondSave).IsTrue(); + await Assert.That(secondSave.IsSuccess).IsTrue(); // Act - read from the store. - var fromDb = await store.GetAsync(aggregateId, cancellationToken: cancellationToken); + var fromDbResult = await store.GetAsync(aggregateId, cancellationToken: cancellationToken); + var fromDb = fromDbResult.IsSuccess ? fromDbResult.Value : null; // Assert - should have the latest state. await Assert.That(fromDb).IsNotNull(); @@ -210,27 +213,29 @@ CancellationToken cancellationToken var aggregate = CreateAggregate(id: aggregateId); aggregate.IncrementInt32Value(); - bool saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saveResult).IsTrue(); + var saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); + await Assert.That(saveResult.IsSuccess).IsTrue(); - var aggregateFromStore = await store.GetAsync( + var aggregateFromStoreResult = await store.GetAsync( aggregateId, new EventStoreOperationContext { SnapshotCacheMode = SnapshotCachingOptions.None }, cancellationToken: cancellationToken ); + var aggregateFromStore = aggregateFromStoreResult.IsSuccess ? aggregateFromStoreResult.Value : null; await Assert.That(aggregateFromStore).IsNotNull(); // Act var deleteResult = await store.DeleteAsync(aggregate, cancellationToken: cancellationToken); - aggregateFromStore = await store.GetAsync( + aggregateFromStoreResult = await store.GetAsync( aggregateId, new EventStoreOperationContext { SnapshotCacheMode = SnapshotCachingOptions.None }, cancellationToken: cancellationToken ); + aggregateFromStore = aggregateFromStoreResult.IsSuccess ? aggregateFromStoreResult.Value : null; // Assert - await Assert.That(deleteResult).IsTrue(); + await Assert.That(deleteResult.IsSuccess).IsTrue(); await Assert.That(aggregateFromStore).IsNull(); } @@ -244,25 +249,28 @@ public async Task RestoreAsync_GivenDeletedAggregate_RestoresSnapshot(Cancellati var aggregate = CreateAggregate(id: aggregateId); aggregate.IncrementInt32Value(); - bool saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saveResult).IsTrue(); + var saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); + await Assert.That(saveResult.IsSuccess).IsTrue(); - var aggregateFromStore = await store.GetAsync(aggregateId, cancellationToken: cancellationToken); + var aggregateFromStoreResult = await store.GetAsync(aggregateId, cancellationToken: cancellationToken); + var aggregateFromStore = aggregateFromStoreResult.IsSuccess ? aggregateFromStoreResult.Value : null; await Assert.That(aggregateFromStore).IsNotNull(); var deleteResult = await store.DeleteAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(deleteResult).IsTrue(); + await Assert.That(deleteResult.IsSuccess).IsTrue(); - aggregateFromStore = await store.GetAsync(aggregateId, cancellationToken: cancellationToken); + aggregateFromStoreResult = await store.GetAsync(aggregateId, cancellationToken: cancellationToken); + aggregateFromStore = aggregateFromStoreResult.IsSuccess ? aggregateFromStoreResult.Value : null; await Assert.That(aggregateFromStore).IsNull(); // Act var restoreResult = await store.RestoreAsync(aggregate, cancellationToken: cancellationToken); - aggregateFromStore = await store.GetAsync(aggregateId, cancellationToken: cancellationToken); + aggregateFromStoreResult = await store.GetAsync(aggregateId, cancellationToken: cancellationToken); + aggregateFromStore = aggregateFromStoreResult.IsSuccess ? aggregateFromStoreResult.Value : null; // Assert - await Assert.That(restoreResult).IsTrue(); + await Assert.That(restoreResult.IsSuccess).IsTrue(); await Assert.That(aggregateFromStore).IsNotNull(); } @@ -287,9 +295,9 @@ CancellationToken cancellationToken for (var eventIndex = 0; eventIndex < numberOfEvents; eventIndex++) aggregate.IncrementInt32Value(); - bool saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); + var saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saveResult).IsTrue(); + await Assert.That(saveResult.IsSuccess).IsTrue(); } // Act @@ -318,9 +326,9 @@ CancellationToken cancellationToken var aggregate = CreateAggregate($"agg_{aggregateIndex}"); aggregate.IncrementInt32Value(); - bool saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); + var saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saveResult).IsTrue(); + await Assert.That(saveResult.IsSuccess).IsTrue(); } // Act @@ -355,9 +363,9 @@ CancellationToken cancellationToken for (var eventIndex = 0; eventIndex < numberOfEvents; eventIndex++) aggregate.IncrementInt32Value(); - bool saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); + var saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saveResult).IsTrue(); + await Assert.That(saveResult.IsSuccess).IsTrue(); } // Act @@ -399,9 +407,9 @@ CancellationToken cancellationToken for (var eventIndex = 0; eventIndex < numberOfEvents; eventIndex++) aggregate.IncrementInt32Value(); - bool saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); + var saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saveResult).IsTrue(); + await Assert.That(saveResult.IsSuccess).IsTrue(); } // These are non-matching. @@ -413,9 +421,9 @@ CancellationToken cancellationToken for (var eventIndex = 0; eventIndex < (numberOfEvents * 2); eventIndex++) aggregate.IncrementInt32Value(); - bool saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); + var saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saveResult).IsTrue(); + await Assert.That(saveResult.IsSuccess).IsTrue(); } // Act @@ -462,8 +470,8 @@ CancellationToken cancellationToken var saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saveResult.ToBoolean()).IsTrue(); - await Assert.That(saveResult.Skipped).IsFalse(); + await Assert.That(saveResult.IsSuccess).IsTrue(); + await Assert.That(saveResult.IsSuccess && saveResult.Value.Written).IsTrue(); } // Act @@ -495,8 +503,8 @@ CancellationToken cancellationToken for (var x = 0; x < matchingIncrement; x++) aggregate.IncrementInt32Value(); - bool saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saveResult).IsTrue(); + var saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); + await Assert.That(saveResult.IsSuccess).IsTrue(); // Act var result = await store.SingleOrDefaultAsync( @@ -522,8 +530,8 @@ public async Task SingleOrDefaultAsync_GivenNoMatchingAggregates_ReturnsNull(Can for (var x = 0; x < eventsToCreate; x++) aggregate.IncrementInt32Value(); - bool saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saveResult).IsTrue(); + var saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); + await Assert.That(saveResult.IsSuccess).IsTrue(); } // Act @@ -555,13 +563,13 @@ CancellationToken cancellationToken aggregate.SetInt32Value(i + 1); - bool saveResult = await store.SaveAsync( + var saveResult = await store.SaveAsync( aggregate, CreateOperationContext(), cancellationToken: cancellationToken ); - await Assert.That(saveResult).IsTrue(); + await Assert.That(saveResult.IsSuccess).IsTrue(); } // Act @@ -595,9 +603,9 @@ CancellationToken cancellationToken aggregate.SetInt32Value(i + 1); - bool saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); + var saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saveResult).IsTrue(); + await Assert.That(saveResult.IsSuccess).IsTrue(); } // Act @@ -631,9 +639,9 @@ CancellationToken cancellationToken aggregate.IncrementInt32Value(); } - bool saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); + var saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saveResult).IsTrue(); + await Assert.That(saveResult.IsSuccess).IsTrue(); } // Act @@ -663,9 +671,9 @@ CancellationToken cancellationToken for (var x = 0; x < matchingIncrement; x++) aggregate.IncrementInt32Value(); - bool saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); + var saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saveResult).IsTrue(); + await Assert.That(saveResult.IsSuccess).IsTrue(); } // Act @@ -693,9 +701,9 @@ CancellationToken cancellationToken for (var x = 0; x < matchingIncrement; x++) aggregate.IncrementInt32Value(); - bool saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); + var saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saveResult).IsTrue(); + await Assert.That(saveResult.IsSuccess).IsTrue(); // Act var result = await store.FirstOrDefaultAsync( @@ -722,9 +730,9 @@ public async Task FirstOrDefaultAsync_GivenNoMatchingAggregates_ReturnsNull(Canc for (var x = 0; x < matchingIncrement; x++) aggregate.IncrementInt32Value(); - bool saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); + var saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saveResult).IsTrue(); + await Assert.That(saveResult.IsSuccess).IsTrue(); } // Act @@ -753,12 +761,12 @@ CancellationToken cancellationToken for (var eventIndex = 0; eventIndex < numberOfEvents; eventIndex++) aggregate.IncrementInt32Value(); - bool saveResult = await store.SaveAsync( + var saveResult = await store.SaveAsync( aggregate, CreateOperationContext(), cancellationToken: cancellationToken ); - await Assert.That(saveResult).IsTrue(); + await Assert.That(saveResult.IsSuccess).IsTrue(); } // Act @@ -780,8 +788,8 @@ public async Task CountAsync_GivenNoMatchingAggregates_ReturnsZero(CancellationT var aggregate = CreateAggregate(); aggregate.IncrementInt32Value(); - bool saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saveResult).IsTrue(); + var saveResult = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); + await Assert.That(saveResult.IsSuccess).IsTrue(); // Act var count = await store.CountAsync(m => m.IncrementInt32 == -1, cancellationToken: cancellationToken); @@ -809,12 +817,12 @@ CancellationToken cancellationToken for (var eventIndex = 0; eventIndex < numberOfEvents; eventIndex++) aggregate.IncrementInt32Value(); - bool saveResult = await store.SaveAsync( + var saveResult = await store.SaveAsync( aggregate, CreateOperationContext(), cancellationToken: cancellationToken ); - await Assert.That(saveResult).IsTrue(); + await Assert.That(saveResult.IsSuccess).IsTrue(); } // Act @@ -850,12 +858,12 @@ CancellationToken cancellationToken for (var eventIndex = 0; eventIndex < numberOfEvents; eventIndex++) aggregate.IncrementInt32Value(); - bool saveResult = await store.SaveAsync( + var saveResult = await store.SaveAsync( aggregate, CreateOperationContext(), cancellationToken: cancellationToken ); - await Assert.That(saveResult).IsTrue(); + await Assert.That(saveResult.IsSuccess).IsTrue(); } // Act diff --git a/src/tests/SharedTestingFramework/CosmosDbTestContainer.cs b/src/tests/SharedTestingFramework/CosmosDbTestContainer.cs new file mode 100644 index 00000000..56d472ff --- /dev/null +++ b/src/tests/SharedTestingFramework/CosmosDbTestContainer.cs @@ -0,0 +1,66 @@ +using System.Globalization; +using Purview.Containers; + +namespace Purview.EventSourcing; + +/// +/// The Azure Cosmos DB emulator. Purview.Containers has no Cosmos DB module, so the endpoint, the +/// connection string and the client used to reach the emulator are assembled here. +/// +public sealed class CosmosDbTestContainer(IContainer container) : IAsyncDisposable +{ + public const ushort CosmosDbPort = 8081; + + /// + /// The published emulator account key. It is a fixed, documented constant rather than a credential. + /// + public const string WellKnownAccountKey = + "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="; + + public IContainer Container { get; } = container; + + public Task StartAsync(CancellationToken cancellationToken = default) => Container.StartAsync(cancellationToken); + + /// + /// The vnext emulator serves the gateway over plain HTTP, and the host binding is IPv4 loopback + /// only, so the endpoint is addressed as 127.0.0.1 rather than localhost. + /// + public Uri GetEndpoint() => + new( + string.Create( + CultureInfo.InvariantCulture, + $"http://127.0.0.1:{Container.GetMappedPublicPort(CosmosDbPort)}/" + ) + ); + + public string GetConnectionString() => + string.Create( + CultureInfo.InvariantCulture, + $"AccountEndpoint={GetEndpoint()};AccountKey={WellKnownAccountKey};" + ); + + /// + /// Creates a client that accepts the emulator's certificate, for the Cosmos SDK and Entity + /// Framework to reach it. + /// + [System.Diagnostics.CodeAnalysis.SuppressMessage( + "Reliability", + "CA2000:Dispose objects before losing scope", + Justification = "The handler is owned by the returned HttpClient." + )] + [System.Diagnostics.CodeAnalysis.SuppressMessage( + "Security", + "CA5400:HttpClient may be created without enabling CheckCertificateRevocationList", + Justification = "The emulator presents a self-signed certificate; this client only ever talks to it." + )] + public static HttpClient CreateHttpClient() => + new( + new HttpClientHandler + { + ServerCertificateCustomValidationCallback = + HttpClientHandler.DangerousAcceptAnyServerCertificateValidator, + } + ); + + public ValueTask DisposeAsync() => Container.DisposeAsync(); +} diff --git a/src/tests/SharedTestingFramework/Fixtures/AppServiceHelper.cs b/src/tests/SharedTestingFramework/Fixtures/AppServiceHelper.cs index d1f5a8a1..4c2e1f5a 100644 --- a/src/tests/SharedTestingFramework/Fixtures/AppServiceHelper.cs +++ b/src/tests/SharedTestingFramework/Fixtures/AppServiceHelper.cs @@ -1,4 +1,4 @@ -using Microsoft.Extensions.Configuration; +using Microsoft.Extensions.Configuration; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.DependencyInjection.Extensions; using Microsoft.Extensions.Logging; diff --git a/src/tests/SharedTestingFramework/Fixtures/AzureStorage/TableEventStoreFixture.cs b/src/tests/SharedTestingFramework/Fixtures/AzureStorage/TableEventStoreFixture.cs index e77cbc9f..01a6a70b 100644 --- a/src/tests/SharedTestingFramework/Fixtures/AzureStorage/TableEventStoreFixture.cs +++ b/src/tests/SharedTestingFramework/Fixtures/AzureStorage/TableEventStoreFixture.cs @@ -6,13 +6,14 @@ using Purview.EventSourcing.AzureStorage.StorageClients.Table; using Purview.EventSourcing.ChangeFeed; using Purview.EventSourcing.Services; +using Purview.EventSourcing.Tenancy; using TUnit.Core.Interfaces; namespace Purview.EventSourcing.Fixtures.AzureStorage; public sealed class TableEventStoreFixture : IAsyncInitializer, IAsyncDisposable { - readonly Testcontainers.Azurite.AzuriteContainer _azuriteContainer = ContainerHelper.CreateAzurite(); + readonly Containers.Azurite.AzuriteContainer _azuriteContainer = ContainerHelper.CreateAzurite(); IAggregateEventNameMapper _eventNameMapper = default!; IDisposable? _eventStoreAsDisposable; @@ -33,13 +34,17 @@ public TableEventStoreFixture() public TableEventStore CreateEventStore( IAggregateChangeFeedNotifier? aggregateChangeNotifier = null, bool removeFromCacheOnDelete = false, - int snapshotRecalculationInterval = 1 + int snapshotRecalculationInterval = 1, + ICurrentTenant? currentTenant = null, + Guid? runId = null ) where TAggregate : class, IAggregate, new() => CreateEventStoreContext( aggregateChangeNotifier, removeFromCacheOnDelete, - snapshotRecalculationInterval + snapshotRecalculationInterval, + currentTenant, + runId ).EventStore; internal ( @@ -51,11 +56,13 @@ AzureBlobClient BlobClient ) CreateEventStoreContext( IAggregateChangeFeedNotifier? aggregateChangeNotifier = null, bool removeFromCacheOnDelete = false, - int snapshotRecalculationInterval = 1 + int snapshotRecalculationInterval = 1, + ICurrentTenant? currentTenant = null, + Guid? runId = null ) where TAggregate : class, IAggregate, new() { - var runId = Guid.NewGuid(); + runId ??= Guid.NewGuid(); var tableName = TestHelpers.GenAzureTableName(runId); var containerName = TestHelpers.GenAzureBlobContainerName(runId); @@ -71,7 +78,7 @@ AzureBlobClient BlobClient var aggregateRequirementsManager = IAggregateRequirementsManager.Mock(); AzureStorageEventStoreOptions azureStorageOptions = new() { - ConnectionString = _azuriteContainer.GetConnectionString(), + ConnectionString = _azuriteContainer.GetEmulatorConnectionString(), Table = tableName, Container = containerName, TimeoutInSeconds = 10, @@ -85,10 +92,11 @@ AzureBlobClient BlobClient aggregateChangeNotifier: aggregateChangeNotifier ?? IAggregateChangeFeedNotifier.Mock(), eventStoreTelemetry: telemetry, aggregateRequirementsManager: aggregateRequirementsManager, - snapshotStrategy: new IntervalSnapshotStrategy(snapshotRecalculationInterval) + snapshotStrategy: new IntervalSnapshotStrategy(snapshotRecalculationInterval), + currentTenant: currentTenant ); - AzureTableClient tableClient = new(azureStorageOptions, eventStore.TableName); + AzureTableClient tableClient = new(azureStorageOptions, eventStore.TableName, currentTenant); TableClient = tableClient; AzureBlobClient blobClient = new(azureStorageOptions, eventStore.ContainerName); diff --git a/src/tests/SharedTestingFramework/Fixtures/CosmosDb/CosmosDbSnapshotEventStoreContext.cs b/src/tests/SharedTestingFramework/Fixtures/CosmosDb/CosmosDbSnapshotEventStoreContext.cs index 0d339edc..67cadcaa 100644 --- a/src/tests/SharedTestingFramework/Fixtures/CosmosDb/CosmosDbSnapshotEventStoreContext.cs +++ b/src/tests/SharedTestingFramework/Fixtures/CosmosDb/CosmosDbSnapshotEventStoreContext.cs @@ -1,5 +1,4 @@ -using Microsoft.Extensions.Caching.Distributed; -using Purview.EventSourcing.Aggregates; +using Microsoft.Extensions.Caching.Distributed; using Purview.EventSourcing.Aggregates.Persistence; using Purview.EventSourcing.AzureStorage; using Purview.EventSourcing.AzureStorage.StorageClients.Blob; @@ -14,7 +13,7 @@ namespace Purview.EventSourcing.Fixtures.CosmosDb; public sealed class CosmosDbSnapshotEventStoreContext( string cosmosDbConnectionString, - HttpClient cosmosDbHttpClient, + CosmosDbClientOverrides cosmosDbClientOverrides, string azuriteConnectionString ) : IAsyncDisposable { @@ -29,8 +28,6 @@ string azuriteConnectionString internal AzureBlobClient BlobClient { get; private set; } = default!; - internal CosmosDbClient CosmosDbClient { get; private set; } = default!; - [System.Diagnostics.CodeAnalysis.SuppressMessage( "Reliability", "CA2000:Dispose objects before losing scope", @@ -52,24 +49,11 @@ public void CreateCosmosDbEventStore(int correlationIdsToGenerate = 1, string? c ConnectionMode = Microsoft.Azure.Cosmos.ConnectionMode.Gateway, }; - Microsoft.Azure.Cosmos.CosmosClient cosmosClient = new( - config.ConnectionString, - clientOptions: new Microsoft.Azure.Cosmos.CosmosClientOptions() - { - HttpClientFactory = () => cosmosDbHttpClient, - ConnectionMode = config.ConnectionMode, - LimitToEndpoint = true, - Serializer = new CosmosDbClient.CosmosSystemTextJsonSerializer(), - } - ); - - CosmosDbClient = new(config, $"/{nameof(IAggregate.AggregateType)}", null, cosmosClient); - CosmosDbSnapshotEventStore eventStore = new( tableEventStore, Microsoft.Extensions.Options.Options.Create(config), ICosmosDbSnapshotEventStoreTelemetry.Mock(), - cosmosClient + cosmosDbClientOverrides ); EventStore = eventStore; @@ -109,5 +93,9 @@ TableEventStore CreateTableEventStore(int correlationIdsTo return eventStore; } - public async ValueTask DisposeAsync() => await CosmosDbClient.DeleteContainerAsync(); + public async ValueTask DisposeAsync() + { + await EventStore.DeleteContainerAsync(); + await EventStore.DisposeAsync(); + } } diff --git a/src/tests/SharedTestingFramework/Fixtures/CosmosDb/CosmosDbSnapshotEventStoreFixture.cs b/src/tests/SharedTestingFramework/Fixtures/CosmosDb/CosmosDbSnapshotEventStoreFixture.cs index 6e2d889b..0f9e4893 100644 --- a/src/tests/SharedTestingFramework/Fixtures/CosmosDb/CosmosDbSnapshotEventStoreFixture.cs +++ b/src/tests/SharedTestingFramework/Fixtures/CosmosDb/CosmosDbSnapshotEventStoreFixture.cs @@ -1,11 +1,17 @@ +using Purview.EventSourcing.CosmosDb; using TUnit.Core.Interfaces; namespace Purview.EventSourcing.Fixtures.CosmosDb; public class CosmosDbSnapshotEventStoreFixture : IAsyncInitializer, IAsyncDisposable { - readonly Testcontainers.Azurite.AzuriteContainer _azuriteContainer; - readonly Testcontainers.CosmosDb.CosmosDbContainer _cosmosDbContainer; + readonly Containers.Azurite.AzuriteContainer _azuriteContainer; + readonly CosmosDbTestContainer _cosmosDbContainer; + + // One set of overrides for the whole session: Entity Framework keys its internal service provider + // on the context options, and these form part of them, so a fresh instance per context would have + // EF build a provider per test. + readonly CosmosDbClientOverrides _cosmosDbClientOverrides; public CosmosDbSnapshotEventStoreFixture() { @@ -13,14 +19,23 @@ public CosmosDbSnapshotEventStoreFixture() _azuriteContainer = ContainerHelper.CreateAzurite(); _cosmosDbContainer = ContainerHelper.CreateCosmosDB(); + + // The emulator is only reachable through a client that accepts its certificate, and only at the + // endpoint it advertises. The factory must hand out a new client each time: a Cosmos client + // configures the one it is given, and rejects one that has already issued a request. + _cosmosDbClientOverrides = new() + { + HttpClientFactory = CosmosDbTestContainer.CreateHttpClient, + LimitToEndpoint = true, + }; } public CosmosDbSnapshotEventStoreContext CreateContext(int correlationIdsToGenerate = 1) { CosmosDbSnapshotEventStoreContext eventStoreContext = new( _cosmosDbContainer.GetConnectionString(), - _cosmosDbContainer.HttpClient, - _azuriteContainer.GetConnectionString() + _cosmosDbClientOverrides, + _azuriteContainer.GetEmulatorConnectionString() ); eventStoreContext.CreateCosmosDbEventStore(correlationIdsToGenerate: correlationIdsToGenerate); diff --git a/src/tests/SharedTestingFramework/Fixtures/MongoDB/MongoDBEventStoreFixture.cs b/src/tests/SharedTestingFramework/Fixtures/MongoDB/MongoDBEventStoreFixture.cs index 22a78d56..a6b5280e 100644 --- a/src/tests/SharedTestingFramework/Fixtures/MongoDB/MongoDBEventStoreFixture.cs +++ b/src/tests/SharedTestingFramework/Fixtures/MongoDB/MongoDBEventStoreFixture.cs @@ -5,14 +5,14 @@ using Purview.EventSourcing.MongoDB.Events; using Purview.EventSourcing.MongoDB.StorageClient; using Purview.EventSourcing.Services; -using Testcontainers.MongoDb; +using Purview.EventSourcing.Tenancy; using TUnit.Core.Interfaces; namespace Purview.EventSourcing.Fixtures.MongoDB; public sealed class MongoDBEventStoreFixture : IAsyncInitializer, IAsyncDisposable { - readonly MongoDbContainer _mongoDBContainer; + readonly MongoDBTestContainer _mongoDBContainer; IAggregateEventNameMapper _eventNameMapper = default!; @@ -32,10 +32,12 @@ public MongoDBEventStoreFixture() public MongoDBEventStore CreateEventStore( IAggregateChangeFeedNotifier? aggregateChangeNotifier = null, - bool removeFromCacheOnDelete = false + bool removeFromCacheOnDelete = false, + ICurrentTenant? currentTenant = null, + Guid? runId = null ) where TAggregate : class, IAggregate, new() => - CreateEventStoreContext(aggregateChangeNotifier, removeFromCacheOnDelete).EventStore; + CreateEventStoreContext(aggregateChangeNotifier, removeFromCacheOnDelete, currentTenant, runId).EventStore; internal ( MongoDBEventStore EventStore, @@ -45,11 +47,13 @@ public MongoDBEventStore CreateEventStore( MongoDBClient SnapshotClient ) CreateEventStoreContext( IAggregateChangeFeedNotifier? aggregateChangeNotifier = null, - bool removeFromCacheOnDelete = false + bool removeFromCacheOnDelete = false, + ICurrentTenant? currentTenant = null, + Guid? runId = null ) where TAggregate : class, IAggregate, new() { - var runId = Guid.NewGuid(); + runId ??= Guid.NewGuid(); var cache = CreateDistributedCache(); Cache = cache; @@ -82,7 +86,8 @@ MongoDBClient SnapshotClient aggregateChangeNotifier: aggregateChangeNotifier ?? IAggregateChangeFeedNotifier.Mock(), eventStoreTelemetry: telemetry, mongoDBClientTelemetry: mongoDBClientTelemetry, - aggregateRequirementsManager: aggregateRequirementsManager + aggregateRequirementsManager: aggregateRequirementsManager, + currentTenant: currentTenant ); MongoDBClient eventClient = new( diff --git a/src/tests/SharedTestingFramework/Fixtures/MongoDB/MongoDBSnapshotEventStoreFixture.cs b/src/tests/SharedTestingFramework/Fixtures/MongoDB/MongoDBSnapshotEventStoreFixture.cs index 91437f38..8178d0ac 100644 --- a/src/tests/SharedTestingFramework/Fixtures/MongoDB/MongoDBSnapshotEventStoreFixture.cs +++ b/src/tests/SharedTestingFramework/Fixtures/MongoDB/MongoDBSnapshotEventStoreFixture.cs @@ -4,8 +4,8 @@ namespace Purview.EventSourcing.Fixtures.MongoDB; public class MongoDBSnapshotEventStoreFixture : IAsyncInitializer, IAsyncDisposable { - readonly Testcontainers.Azurite.AzuriteContainer _azuriteContainer; - readonly Testcontainers.MongoDb.MongoDbContainer _mongoDBContainer; + readonly Containers.Azurite.AzuriteContainer _azuriteContainer; + readonly MongoDBTestContainer _mongoDBContainer; public MongoDBSnapshotEventStoreFixture() { @@ -18,7 +18,7 @@ public MongoDBSnapshotEventStoreFixture() public MongoDBSnapshotTestContext CreateContext(int correlationIdsToGenerate = 1, string? collectionName = null) => new( _mongoDBContainer.GetConnectionString(), - _azuriteContainer.GetConnectionString(), + _azuriteContainer.GetEmulatorConnectionString(), correlationIdsToGenerate, collectionName ); diff --git a/src/tests/SharedTestingFramework/Fixtures/Postgres/PostgresEventStoreFixture.cs b/src/tests/SharedTestingFramework/Fixtures/Postgres/PostgresEventStoreFixture.cs index 7d8d12f4..02e1d3b6 100644 --- a/src/tests/SharedTestingFramework/Fixtures/Postgres/PostgresEventStoreFixture.cs +++ b/src/tests/SharedTestingFramework/Fixtures/Postgres/PostgresEventStoreFixture.cs @@ -1,9 +1,10 @@ using Microsoft.Extensions.Caching.Distributed; +using Purview.Containers.PostgreSql; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.ChangeFeed; using Purview.EventSourcing.Postgres.Events; using Purview.EventSourcing.Services; -using Testcontainers.PostgreSql; +using Purview.EventSourcing.Tenancy; using TUnit.Core.Interfaces; namespace Purview.EventSourcing.Fixtures.Postgres; @@ -31,10 +32,17 @@ public PostgresEventStore CreateEventStore( IAggregateChangeFeedNotifier? aggregateChangeNotifier = null, bool removeFromCacheOnDelete = false, Guid? runId = null, - Action? configureOptions = null + Action? configureOptions = null, + ICurrentTenant? currentTenant = null ) where TAggregate : class, IAggregate, new() => - CreateEventStoreContext(aggregateChangeNotifier, removeFromCacheOnDelete, runId, configureOptions).EventStore; + CreateEventStoreContext( + aggregateChangeNotifier, + removeFromCacheOnDelete, + runId, + configureOptions, + currentTenant + ).EventStore; internal ( PostgresEventStore EventStore, @@ -45,7 +53,8 @@ IPostgresEventStoreTelemetryMock Telemetry IAggregateChangeFeedNotifier? aggregateChangeNotifier = null, bool removeFromCacheOnDelete = false, Guid? runId = null, - Action? configureOptions = null + Action? configureOptions = null, + ICurrentTenant? currentTenant = null ) where TAggregate : class, IAggregate, new() { @@ -68,7 +77,7 @@ IPostgresEventStoreTelemetryMock Telemetry }; configureOptions?.Invoke(options); - PostgresEventStoreClient client = new(options); + PostgresEventStoreClient client = new(options, currentTenant); Client = client; PostgresEventStore eventStore = new( @@ -77,7 +86,8 @@ IPostgresEventStoreTelemetryMock Telemetry distributedCache: cache, eventStoreTelemetry: telemetry, aggregateChangeNotifier: aggregateChangeNotifier ?? IAggregateChangeFeedNotifier.Mock(), - aggregateRequirementsManager: aggregateRequirementsManager + aggregateRequirementsManager: aggregateRequirementsManager, + currentTenant: currentTenant ); return (eventStore, client, cache, telemetry); diff --git a/src/tests/SharedTestingFramework/Fixtures/SqlServer/SqlServerEventStoreFixture.cs b/src/tests/SharedTestingFramework/Fixtures/SqlServer/SqlServerEventStoreFixture.cs index d1e6c2de..27876ad8 100644 --- a/src/tests/SharedTestingFramework/Fixtures/SqlServer/SqlServerEventStoreFixture.cs +++ b/src/tests/SharedTestingFramework/Fixtures/SqlServer/SqlServerEventStoreFixture.cs @@ -1,9 +1,11 @@ using Microsoft.Extensions.Caching.Distributed; +using Purview.Containers.MsSql; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.ChangeFeed; +using Purview.EventSourcing.Cryptography; using Purview.EventSourcing.Services; using Purview.EventSourcing.SqlServer.Events; -using Testcontainers.MsSql; +using Purview.EventSourcing.Tenancy; using TUnit.Core.Interfaces; namespace Purview.EventSourcing.Fixtures.SqlServer; @@ -31,10 +33,19 @@ public SqlServerEventStore CreateEventStore( IAggregateChangeFeedNotifier? aggregateChangeNotifier = null, bool removeFromCacheOnDelete = false, Guid? runId = null, - Action? configureOptions = null + Action? configureOptions = null, + ICurrentTenant? currentTenant = null, + IEventPayloadProtector? payloadProtector = null ) where TAggregate : class, IAggregate, new() => - CreateEventStoreContext(aggregateChangeNotifier, removeFromCacheOnDelete, runId, configureOptions).EventStore; + CreateEventStoreContext( + aggregateChangeNotifier, + removeFromCacheOnDelete, + runId, + configureOptions, + currentTenant, + payloadProtector + ).EventStore; internal ( SqlServerEventStore EventStore, @@ -45,7 +56,9 @@ ISqlServerEventStoreTelemetryMock Telemetry IAggregateChangeFeedNotifier? aggregateChangeNotifier = null, bool removeFromCacheOnDelete = false, Guid? runId = null, - Action? configureOptions = null + Action? configureOptions = null, + ICurrentTenant? currentTenant = null, + IEventPayloadProtector? payloadProtector = null ) where TAggregate : class, IAggregate, new() { @@ -70,7 +83,7 @@ ISqlServerEventStoreTelemetryMock Telemetry }; configureOptions?.Invoke(options); - SqlServerEventStoreClient client = new(options); + SqlServerEventStoreClient client = new(options, currentTenant); Client = client; SqlServerEventStore eventStore = new( @@ -79,7 +92,9 @@ ISqlServerEventStoreTelemetryMock Telemetry distributedCache: cache, eventStoreTelemetry: telemetry, aggregateChangeNotifier: aggregateChangeNotifier ?? IAggregateChangeFeedNotifier.Mock(), - aggregateRequirementsManager: aggregateRequirementsManager + aggregateRequirementsManager: aggregateRequirementsManager, + currentTenant: currentTenant, + payloadProtector: payloadProtector ); return (eventStore, client, cache, telemetry); diff --git a/src/tests/SharedTestingFramework/MongoDBTestContainer.cs b/src/tests/SharedTestingFramework/MongoDBTestContainer.cs new file mode 100644 index 00000000..973fd20c --- /dev/null +++ b/src/tests/SharedTestingFramework/MongoDBTestContainer.cs @@ -0,0 +1,77 @@ +using System.Globalization; +using Purview.Containers; + +namespace Purview.EventSourcing; + +/// +/// A MongoDB container running as a single-node replica set, which the event store's transactions +/// require. Purview.Containers has no MongoDB module, so the replica set is initiated here. +/// +public sealed class MongoDBTestContainer(IContainer container) : IAsyncDisposable +{ + public const ushort MongoDBPort = 27017; + + static readonly TimeSpan PrimaryTimeout = TimeSpan.FromMinutes(2); + + public IContainer Container { get; } = container; + + public async Task StartAsync(CancellationToken cancellationToken = default) + { + await Container.StartAsync(cancellationToken); + await InitiateReplicaSetAsync(cancellationToken); + await WaitForPrimaryAsync(cancellationToken); + } + + /// + /// The replica set advertises its member as 127.0.0.1:27017, which is the container's own + /// address rather than the mapped host port, so clients connect directly instead of discovering + /// the set. + /// + public string GetConnectionString() => + string.Create( + CultureInfo.InvariantCulture, + $"mongodb://127.0.0.1:{Container.GetMappedPublicPort(MongoDBPort)}/?directConnection=true" + ); + + public ValueTask DisposeAsync() => Container.DisposeAsync(); + + async Task InitiateReplicaSetAsync(CancellationToken cancellationToken) + { + var result = await Container.ExecAsync( + [ + "mongosh", + "--quiet", + "--eval", + $"try {{ rs.status().ok }} catch (e) {{ rs.initiate({{ _id: '{ContainerHelper.MongoDBReplicaSetName}', members: [{{ _id: 0, host: '127.0.0.1:{MongoDBPort}' }}] }}) }}", + ], + cancellationToken: cancellationToken + ); + + if (result.ExitCode != 0) + { + throw new InvalidOperationException( + $"Unable to initiate the MongoDB replica set (exit code {result.ExitCode}): {result.Stderr}" + ); + } + } + + async Task WaitForPrimaryAsync(CancellationToken cancellationToken) + { + var deadline = DateTimeOffset.UtcNow.Add(PrimaryTimeout); + while (true) + { + var result = await Container.ExecAsync( + ["mongosh", "--quiet", "--eval", "db.hello().isWritablePrimary"], + cancellationToken: cancellationToken + ); + + if (result.ExitCode == 0 && result.Stdout.Contains("true", StringComparison.OrdinalIgnoreCase)) + return; + + if (DateTimeOffset.UtcNow > deadline) + throw new InvalidOperationException("The MongoDB replica set did not elect a primary in time."); + + await Task.Delay(TimeSpan.FromMilliseconds(250), cancellationToken); + } + } +} diff --git a/src/tests/SharedTestingFramework/Records.cs b/src/tests/SharedTestingFramework/Records.cs index 812957d7..df073801 100644 --- a/src/tests/SharedTestingFramework/Records.cs +++ b/src/tests/SharedTestingFramework/Records.cs @@ -1,3 +1,3 @@ -namespace Purview.EventSourcing; +namespace Purview.EventSourcing; public sealed record ServiceDefinition(Type ServiceType, object Instance); diff --git a/src/tests/SharedTestingFramework/SharedTestingFramework.csproj b/src/tests/SharedTestingFramework/SharedTestingFramework.csproj index 61322c3f..1b01b107 100644 --- a/src/tests/SharedTestingFramework/SharedTestingFramework.csproj +++ b/src/tests/SharedTestingFramework/SharedTestingFramework.csproj @@ -19,11 +19,17 @@ - - - - - + + + + + diff --git a/src/tests/SourceGenerator.UnitTests/Common/ManifestTestHelpers.cs b/src/tests/SourceGenerator.UnitTests/Common/ManifestTestHelpers.cs index 1d571182..3f772921 100644 --- a/src/tests/SourceGenerator.UnitTests/Common/ManifestTestHelpers.cs +++ b/src/tests/SourceGenerator.UnitTests/Common/ManifestTestHelpers.cs @@ -53,7 +53,7 @@ public static string ExtractManifestJson(string generatedSource) if (markerIndex < 0) throw new InvalidOperationException($"Generated source does not contain '{marker}'."); - var valueStart = generatedSource.IndexOf('"', markerIndex) + 1; + var valueStart = generatedSource.IndexOf('"', markerIndex, StringComparison.Ordinal) + 1; var valueEnd = FindClosingQuote(generatedSource, valueStart); if (valueStart <= markerIndex || valueEnd <= valueStart) throw new InvalidOperationException("Generated manifest constant is malformed."); diff --git a/src/tests/SourceGenerator.UnitTests/Generators/AggregateSourceGeneratorTests.cs b/src/tests/SourceGenerator.UnitTests/Generators/AggregateSourceGeneratorTests.cs index 0ed603d6..7a2ed4a3 100644 --- a/src/tests/SourceGenerator.UnitTests/Generators/AggregateSourceGeneratorTests.cs +++ b/src/tests/SourceGenerator.UnitTests/Generators/AggregateSourceGeneratorTests.cs @@ -1,6 +1,6 @@ -using Microsoft.CodeAnalysis; using System.Reflection; using System.Text.Json; +using Microsoft.CodeAnalysis; namespace Purview.EventSourcing.SourceGenerator.Generators; @@ -346,7 +346,11 @@ public partial class ReportAggregate : AggregateBase } "; - using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync( + source, + EventSourcingGeneratorTestOptions.NoValidation, + cancellationToken + ); await Assert.That(result).HasDiagnostic(DiagnosticLibrary.ScalarComplexValueMayNotTranslateInSQLSnapshots); } @@ -1280,7 +1284,11 @@ public void NonPartialMethod(string value) "; // Act - using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync( + source, + EventSourcingGeneratorTestOptions.NoValidation, + cancellationToken + ); await Assert.That(result.Generated().HasRecord("NonPartialMethodEvent", "Testing.MixedEvents")).IsFalse(); await Assert.That(result).HasDiagnostic("EVENTSTORE007"); @@ -1576,7 +1584,11 @@ public partial class OrderAggregate : AggregateBase } "; - using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync( + source, + EventSourcingGeneratorTestOptions.NoValidation, + cancellationToken + ); await Assert.That(result).HasDiagnostic(DiagnosticLibrary.EventSchemaVersionMustBePositive); } @@ -1605,7 +1617,11 @@ public partial class OrderAggregate : AggregateBase } "; - using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync( + source, + EventSourcingGeneratorTestOptions.NoValidation, + cancellationToken + ); await Assert.That(result).HasDiagnostic(DiagnosticLibrary.DuplicateEventSchemaVersionOnAggregate); } @@ -1836,7 +1852,11 @@ public partial class NotARealAggregate : Testing.AggregateBase } "; - using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync( + source, + EventSourcingGeneratorTestOptions.NoValidation, + cancellationToken + ); await Assert.That(result).HasDiagnostic("EVENTSTORE002"); } @@ -1862,7 +1882,11 @@ public partial class NestedAggregate : AggregateBase } "; - using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync( + source, + EventSourcingGeneratorTestOptions.NoValidation, + cancellationToken + ); await Assert.That(result).HasDiagnostic("EVENTSTORE003"); } @@ -1884,7 +1908,11 @@ public partial class GenericAggregate : AggregateBase } "; - using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync( + source, + EventSourcingGeneratorTestOptions.NoValidation, + cancellationToken + ); await Assert.That(result).HasDiagnostic("EVENTSTORE004"); } @@ -1909,7 +1937,11 @@ protected override void RegisterEvents() { } } "; - using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync( + source, + EventSourcingGeneratorTestOptions.NoValidation, + cancellationToken + ); await Assert.That(result).HasDiagnostic("EVENTSTORE005"); } @@ -1940,7 +1972,11 @@ public partial class PublicSetterAggregate : AggregateBase }} "; - using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync( + source, + EventSourcingGeneratorTestOptions.NoValidation, + cancellationToken + ); await Assert.That(result).HasDiagnostic("EVENTSTORE011"); } @@ -1965,7 +2001,11 @@ public partial class InvalidSignatureAggregate : AggregateBase } "; - using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync( + source, + EventSourcingGeneratorTestOptions.NoValidation, + cancellationToken + ); await Assert.That(result).HasDiagnostic("EVENTSTORE008"); } @@ -1990,7 +2030,11 @@ public partial class InvalidSignatureAggregate : AggregateBase } "; - using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync( + source, + EventSourcingGeneratorTestOptions.NoValidation, + cancellationToken + ); await Assert.That(result).HasDiagnostic("EVENTSTORE008"); } @@ -2019,7 +2063,11 @@ public partial class DuplicateEventAggregate : AggregateBase } "; - using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync( + source, + EventSourcingGeneratorTestOptions.NoValidation, + cancellationToken + ); await Assert.That(result).HasDiagnostic(DiagnosticLibrary.DuplicateGeneratedEventName); } @@ -2042,7 +2090,11 @@ public partial class MappingAggregate : AggregateBase } "; - using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync( + source, + EventSourcingGeneratorTestOptions.NoValidation, + cancellationToken + ); await Assert.That(result).HasDiagnostic(DiagnosticLibrary.EventParameterMustMapToWritableProperty); } @@ -2195,7 +2247,11 @@ public partial class MappingAggregate : AggregateBase } "; - using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync( + source, + EventSourcingGeneratorTestOptions.NoValidation, + cancellationToken + ); await Assert.That(result).HasDiagnostic(DiagnosticLibrary.EventParameterMustMapToWritableProperty); } @@ -2218,7 +2274,11 @@ public partial class InitOnlyAggregate : AggregateBase } "; - using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync( + source, + EventSourcingGeneratorTestOptions.NoValidation, + cancellationToken + ); await Assert.That(result).HasDiagnostic("EVENTSTORE010"); } @@ -3168,7 +3228,11 @@ public sealed record CustomerRegisteredEvent } "; - using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync( + source, + EventSourcingGeneratorTestOptions.NoValidation, + cancellationToken + ); await Assert.That(result).DoesNotHaveDiagnostic(DiagnosticLibrary.EventNameOverrideShouldBePastTense); await Assert.That(result).DoesNotHaveDiagnostic(DiagnosticLibrary.UnableToInferEventName); @@ -3258,7 +3322,11 @@ public partial class ItemAggregate : AggregateBase }} "; - using var result = await GenerateAsync(source, EventSourcingGeneratorTestOptions.NoValidation, cancellationToken); + using var result = await GenerateAsync( + source, + EventSourcingGeneratorTestOptions.NoValidation, + cancellationToken + ); await Assert .That(result) diff --git a/src/tests/SqlServer.IntegrationTests/Events/SqlServerEventStoreCryptoShreddingTests.cs b/src/tests/SqlServer.IntegrationTests/Events/SqlServerEventStoreCryptoShreddingTests.cs new file mode 100644 index 00000000..1df94e08 --- /dev/null +++ b/src/tests/SqlServer.IntegrationTests/Events/SqlServerEventStoreCryptoShreddingTests.cs @@ -0,0 +1,114 @@ +using System.Diagnostics.CodeAnalysis; +using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Aggregates.Persistence; +using Purview.EventSourcing.Cryptography; +using Purview.EventSourcing.Fixtures.SqlServer; + +namespace Purview.EventSourcing.SqlServer.Events; + +/// +/// Guards crypto-shredding end to end against real SQL Server. +/// +/// +/// Exercised against the database rather than in memory because the point is what reaches storage: the +/// stored payload must be ciphertext, and erasing the key must make it unreadable on the way back out. +/// +[ClassDataSource(Shared = SharedType.PerAssembly)] +public sealed class SqlServerEventStoreCryptoShreddingTests(SqlServerEventStoreFixture fixture) +{ + static (InMemoryEventCryptoKeyStore Keys, AesGcmEventPayloadProtector Protector) CreateProtection() + { + InMemoryEventCryptoKeyStore keys = new(); + + return (keys, new AesGcmEventPayloadProtector(keys)); + } + + [Test] + [SuppressMessage( + "Maintainability", + "CA1506", + Justification = "Reads raw storage to prove the payload is ciphertext, which needs both the store and the client." + )] + public async Task SaveAsync_GivenAnEventWithADataSubject_StoresCipherText(CancellationToken cancellationToken) + { + // Arrange + var (_, protector) = CreateProtection(); + var runId = Guid.NewGuid(); + var aggregateId = $"{Guid.NewGuid()}"; + + var store = fixture.CreateEventStore(runId: runId, payloadProtector: protector); + + var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); + aggregate.SetSubjectName("Ada Lovelace", "user-4712"); + + // Act + var saved = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); + + // Assert - the name must not be readable in the stored payload. + await Assert.That(saved.IsSuccess).IsTrue(); + + var payloads = await ReadRawEventPayloadsAsync(runId, aggregateId, cancellationToken); + + await Assert.That(payloads).IsNotEmpty(); + await Assert.That(payloads.Any(p => p.Contains("Ada Lovelace", StringComparison.Ordinal))).IsFalse(); + await Assert + .That(payloads.Any(p => p.Contains(ProtectedPayload.MarkerPropertyName, StringComparison.Ordinal))) + .IsTrue(); + } + + [Test] + public async Task GetAsync_AfterShredding_SkipsTheEventAndStillReturnsTheAggregate( + CancellationToken cancellationToken + ) + { + // Arrange + var (keys, protector) = CreateProtection(); + var runId = Guid.NewGuid(); + var aggregateId = $"{Guid.NewGuid()}"; + + var store = fixture.CreateEventStore(runId: runId, payloadProtector: protector); + + var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); + aggregate.SetSubjectName("Ada Lovelace", "user-4712"); + await store.SaveAsync(aggregate, cancellationToken: cancellationToken); + + // Act - erase the subject, then replay. + await keys.ShredAsync("user-4712", cancellationToken); + + var result = await store.GetAsync(aggregateId, cancellationToken: cancellationToken); + + // Assert - replay succeeds, the event is skipped, and the gap is visible to the caller. + await Assert.That(result.IsSuccess).IsTrue(); + + var skipped = (result.Value as AggregateBase)?.SkippedEvents; + + await Assert.That(skipped).IsNotNull(); + await Assert.That(skipped!.Count).IsGreaterThan(0); + } + + async Task> ReadRawEventPayloadsAsync( + Guid runId, + string aggregateId, + CancellationToken cancellationToken + ) + { + List payloads = []; + + await using Microsoft.Data.SqlClient.SqlConnection connection = new(fixture.ConnectionString); + await connection.OpenAsync(cancellationToken); + + // The table name is a test-generated GUID, not user input; the aggregate id is parameterised. +#pragma warning disable CA2100 + await using var command = connection.CreateCommand(); + command.CommandText = + $"SELECT Payload FROM [dbo].[EventStoreEvents_{runId:N}] WHERE AggregateId = @id AND EntityType = 1 AND Payload IS NOT NULL"; + command.Parameters.AddWithValue("@id", aggregateId); +#pragma warning restore CA2100 + + await using var reader = await command.ExecuteReaderAsync(cancellationToken); + while (await reader.ReadAsync(cancellationToken)) + payloads.Add(reader.GetString(0)); + + return payloads; + } +} diff --git a/src/tests/SqlServer.IntegrationTests/Events/SqlServerEventStoreTenancyTests.cs b/src/tests/SqlServer.IntegrationTests/Events/SqlServerEventStoreTenancyTests.cs new file mode 100644 index 00000000..4fa943ed --- /dev/null +++ b/src/tests/SqlServer.IntegrationTests/Events/SqlServerEventStoreTenancyTests.cs @@ -0,0 +1,97 @@ +using Purview.EventSourcing.Aggregates.Persistence; +using Purview.EventSourcing.Fixtures.SqlServer; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.SqlServer.Events; + +/// +/// Guards that the tenant query filter isolates event streams. +/// +/// +/// Exercised against real SQL Server rather than in memory: the isolation is an Entity Framework global +/// query filter translated into SQL, so an in-memory substitute would prove nothing about the predicate +/// that actually runs. +/// +[ClassDataSource(Shared = SharedType.PerAssembly)] +public sealed class SqlServerEventStoreTenancyTests(SqlServerEventStoreFixture fixture) +{ + sealed class StubTenant(TenantScope scope) : ICurrentTenant + { + public TenantScope Current => scope; + } + + SqlServerEventStore StoreFor(TenantScope scope, Guid runId) => + fixture.CreateEventStore(runId: runId, currentTenant: new StubTenant(scope)); + + [Test] + public async Task GetAsync_GivenAnotherTenantsAggregate_DoesNotReturnIt(CancellationToken cancellationToken) + { + // Arrange - one physical table, two tenants, the same aggregate id. + var runId = Guid.NewGuid(); + var aggregateId = $"{Guid.NewGuid()}"; + + var acme = StoreFor(TenantScope.For("acme"), runId); + var globex = StoreFor(TenantScope.For("globex"), runId); + + var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); + aggregate.IncrementInt32Value(); + + var saved = await acme.SaveAsync(aggregate, cancellationToken: cancellationToken); + await Assert.That(saved.IsSuccess).IsTrue(); + + // Act + var fromOwner = await acme.GetAsync(aggregateId, cancellationToken: cancellationToken); + var fromOther = await globex.GetAsync(aggregateId, cancellationToken: cancellationToken); + + // Assert + await Assert.That(fromOwner.IsSuccess).IsTrue(); + await Assert.That(fromOther.IsFailure).IsTrue(); + } + + // The distributed cache is read before the tenant-filtered storage lookup, so an unqualified cache + // key would let a second tenant read the first tenant's aggregate straight out of a shared cache, + // bypassing every storage filter. Reading twice as the owner guarantees the entry is cached. + [Test] + public async Task GetAsync_GivenACachedAggregate_DoesNotServeItToAnotherTenant(CancellationToken cancellationToken) + { + var runId = Guid.NewGuid(); + var aggregateId = $"{Guid.NewGuid()}"; + + var acme = StoreFor(TenantScope.For("acme"), runId); + var globex = StoreFor(TenantScope.For("globex"), runId); + + var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); + aggregate.IncrementInt32Value(); + await acme.SaveAsync(aggregate, cancellationToken: cancellationToken); + + // Prime the cache as the owning tenant. + await acme.GetAsync(aggregateId, cancellationToken: cancellationToken); + await Assert.That((await acme.GetAsync(aggregateId, cancellationToken: cancellationToken)).IsSuccess).IsTrue(); + + await Assert + .That((await globex.GetAsync(aggregateId, cancellationToken: cancellationToken)).IsFailure) + .IsTrue(); + } + + [Test] + public async Task GetAsync_GivenSystemScope_ReadsAcrossTenants(CancellationToken cancellationToken) + { + // Arrange + var runId = Guid.NewGuid(); + var aggregateId = $"{Guid.NewGuid()}"; + + var acme = StoreFor(TenantScope.For("acme"), runId); + var system = StoreFor(TenantScope.System, runId); + + var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); + aggregate.IncrementInt32Value(); + + await acme.SaveAsync(aggregate, cancellationToken: cancellationToken); + + // Act - infrastructure work deliberately crosses tenants. + var result = await system.GetAsync(aggregateId, cancellationToken: cancellationToken); + + // Assert + await Assert.That(result.IsSuccess).IsTrue(); + } +} diff --git a/src/tests/SqlServer.IntegrationTests/Events/SqlServerEventStoreTests.IndexCreation.cs b/src/tests/SqlServer.IntegrationTests/Events/SqlServerEventStoreTests.IndexCreation.cs index 5d76a558..9653a852 100644 --- a/src/tests/SqlServer.IntegrationTests/Events/SqlServerEventStoreTests.IndexCreation.cs +++ b/src/tests/SqlServer.IntegrationTests/Events/SqlServerEventStoreTests.IndexCreation.cs @@ -24,7 +24,7 @@ CancellationToken cancellationToken var saved = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saved.Saved).IsTrue(); + await Assert.That(saved.IsSuccess && saved.Value.Written).IsTrue(); var aggregateLookupKeyColumns = await GetIndexKeyColumnsAsync( fixture.ConnectionString, @@ -88,7 +88,7 @@ CancellationToken cancellationToken var saved = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saved.Saved).IsTrue(); + await Assert.That(saved.IsSuccess && saved.Value.Written).IsTrue(); await Assert .That(await ColumnExistsAsync(fixture.ConnectionString, tableName, computedColumnName, cancellationToken)) .IsTrue(); diff --git a/src/tests/SqlServer.IntegrationTests/Events/SqlServerEventStoreTransactionIntegrationTests.cs b/src/tests/SqlServer.IntegrationTests/Events/SqlServerEventStoreTransactionIntegrationTests.cs index a73a4308..470001d6 100644 --- a/src/tests/SqlServer.IntegrationTests/Events/SqlServerEventStoreTransactionIntegrationTests.cs +++ b/src/tests/SqlServer.IntegrationTests/Events/SqlServerEventStoreTransactionIntegrationTests.cs @@ -15,6 +15,11 @@ namespace Purview.EventSourcing.SqlServer.Events; public sealed partial class SqlServerEventStoreTransactionIntegrationTests(SqlServerEventStoreFixture fixture) { [Test] + [SuppressMessage( + "Maintainability", + "CA1506", + Justification = "SQL Server transaction integration scenario intentionally touches the full transaction surface." + )] public async Task CommitAsync_GivenEnlistedRawSqlOperation_CommitsAggregateAndRawSqlTogether( CancellationToken cancellationToken ) @@ -49,7 +54,8 @@ CancellationToken cancellationToken ); var result = await transaction.CommitAsync(cancellationToken); - var savedAggregate = await eventStore.GetAsync(aggregateId, null, cancellationToken); + var savedAggregateResult = await eventStore.GetAsync(aggregateId, null, cancellationToken); + var savedAggregate = savedAggregateResult.IsSuccess ? savedAggregateResult.Value : null; var rowCount = await GetAuditRowCountAsync(fixture.ConnectionString, tableName, cancellationToken); await Assert.That(result.Success).IsTrue(); @@ -59,6 +65,11 @@ CancellationToken cancellationToken } [Test] + [SuppressMessage( + "Maintainability", + "CA1506", + Justification = "SQL Server transaction integration scenario intentionally touches the full transaction surface." + )] public async Task CommitAsync_GivenEnlistedEfOperation_CommitsAggregateAndEfSaveTogether( CancellationToken cancellationToken ) @@ -85,7 +96,8 @@ CancellationToken cancellationToken ); var result = await transaction.CommitAsync(cancellationToken); - var savedAggregate = await eventStore.GetAsync(aggregateId, null, cancellationToken); + var savedAggregateResult = await eventStore.GetAsync(aggregateId, null, cancellationToken); + var savedAggregate = savedAggregateResult.IsSuccess ? savedAggregateResult.Value : null; var rowCount = await GetAuditRowCountAsync(fixture.ConnectionString, tableName, cancellationToken); await Assert.That(result.Success).IsTrue(); @@ -135,7 +147,8 @@ CancellationToken cancellationToken ); var result = await transaction.CommitAsync(cancellationToken); - var savedAggregate = await eventStore.GetAsync(aggregateId, null, cancellationToken); + var savedAggregateResult = await eventStore.GetAsync(aggregateId, null, cancellationToken); + var savedAggregate = savedAggregateResult.IsSuccess ? savedAggregateResult.Value : null; var rowCount = await GetAuditRowCountAsync(fixture.ConnectionString, tableName, cancellationToken); await Assert.That(result.Success).IsFalse(); @@ -146,6 +159,11 @@ CancellationToken cancellationToken } [Test] + [SuppressMessage( + "Maintainability", + "CA1506", + Justification = "SQL Server transaction integration scenario intentionally touches the full transaction surface." + )] public async Task CommitAsync_GivenMultipleCrossImplementationStoresAndRawSql_CommitsAllInSingleTransaction( CancellationToken cancellationToken ) @@ -187,8 +205,10 @@ CancellationToken cancellationToken ); var result = await transaction.CommitAsync(cancellationToken); - var savedFirst = await primaryStore.GetAsync(firstAggregateId, null, cancellationToken); - var savedSecond = await snapshotStore.GetAsync(secondAggregateId, null, cancellationToken); + var savedFirstResult = await primaryStore.GetAsync(firstAggregateId, null, cancellationToken); + var savedFirst = savedFirstResult.IsSuccess ? savedFirstResult.Value : null; + var savedSecondResult = await snapshotStore.GetAsync(secondAggregateId, null, cancellationToken); + var savedSecond = savedSecondResult.IsSuccess ? savedSecondResult.Value : null; var rowCount = await GetAuditRowCountAsync(fixture.ConnectionString, tableName, cancellationToken); await Assert.That(result.Success).IsTrue(); @@ -200,6 +220,11 @@ CancellationToken cancellationToken } [Test] + [SuppressMessage( + "Maintainability", + "CA1506", + Justification = "SQL Server transaction integration scenario intentionally touches the full transaction surface." + )] public async Task CommitAsync_GivenMultipleCrossImplementationStoresAndFailingRawSql_RollsBackAllChanges( CancellationToken cancellationToken ) @@ -242,8 +267,10 @@ CancellationToken cancellationToken ); var result = await transaction.CommitAsync(cancellationToken); - var savedFirst = await primaryStore.GetAsync(firstAggregateId, null, cancellationToken); - var savedSecond = await snapshotStore.GetAsync(secondAggregateId, null, cancellationToken); + var savedFirstResult = await primaryStore.GetAsync(firstAggregateId, null, cancellationToken); + var savedFirst = savedFirstResult.IsSuccess ? savedFirstResult.Value : null; + var savedSecondResult = await snapshotStore.GetAsync(secondAggregateId, null, cancellationToken); + var savedSecond = savedSecondResult.IsSuccess ? savedSecondResult.Value : null; var rowCount = await GetAuditRowCountAsync(fixture.ConnectionString, tableName, cancellationToken); await Assert.That(result.Success).IsFalse(); diff --git a/src/tests/SqlServer.IntegrationTests/Guards/SqlServerEventStoreGuardTests.cs b/src/tests/SqlServer.IntegrationTests/Guards/SqlServerEventStoreGuardTests.cs index 1de345b4..e6b02c42 100644 --- a/src/tests/SqlServer.IntegrationTests/Guards/SqlServerEventStoreGuardTests.cs +++ b/src/tests/SqlServer.IntegrationTests/Guards/SqlServerEventStoreGuardTests.cs @@ -1,3 +1,5 @@ +using System.Diagnostics.CodeAnalysis; +using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Persistence; using Purview.EventSourcing.Aggregates.Persistence.Events; using Purview.EventSourcing.Fixtures.SqlServer; @@ -30,15 +32,13 @@ CancellationToken cancellationToken await eventStore.SaveAsync(aggregate, cancellationToken); - var aggregateResult = - await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken) - ?? throw new NullReferenceException(); + var aggregateResult = (await eventStore.GetAsync(aggregateId, cancellationToken: cancellationToken)).Value; // Act var result = await eventStore.DeleteAsync(aggregateResult, cancellationToken: cancellationToken); // Assert - await Assert.That(result).IsTrue(); + await Assert.That(result.IsSuccess).IsTrue(); cache.RemoveAsync(cacheKey, Any()).WasCalled(Times.Once); } @@ -65,13 +65,13 @@ CancellationToken cancellationToken ); // Assert - await Assert.That(result).IsTrue(); + await Assert.That(result.IsSuccess).IsTrue(); await Assert.That(aggregate.Details.IsDeleted).IsTrue(); await Assert.That(aggregate.Details.Locked).IsTrue(); // Verify all data was removed. var exists = await eventStore.ExistsAsync(aggregateId, cancellationToken: cancellationToken); - await Assert.That(exists.Status).IsEqualTo(ExistsStatus.DoesNotExist); + await Assert.That(exists.Status).IsEqualTo(ExistenceStatus.DoesNotExist); } [Test] @@ -88,16 +88,22 @@ CancellationToken cancellationToken var telemetry = ctx.Telemetry; // Act - bool result = await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); + var result = await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); // Assert - await Assert.That(result).IsFalse(); + await Assert.That(result.IsSuccess).IsTrue(); + await Assert.That(result.Value.Kind).IsEqualTo(SaveOutcomeKind.NoChanges); telemetry.SaveContainedNoChanges(aggregateId, Any(), Any()).WasCalled(Times.Once); } [Test] [MethodDataSource(nameof(OldEventCountTestData))] + [SuppressMessage( + "Maintainability", + "CA1506:Avoid excessive class coupling", + Justification = "Test wiring: the store, its infrastructure and the result model are all named here." + )] public async Task GetAsync_GivenAnAggregateWithNonRegisteredEventType_TelemetryLogsCannotApplyEvent( int eventsToCreate, int numberOfOldEventsToCreate, @@ -117,11 +123,12 @@ CancellationToken cancellationToken // Act await eventStore.SaveAsync(aggregate, cancellationToken: cancellationToken); - var result = await eventStore.GetAsync( + var resultResult = await eventStore.GetAsync( aggregateId, new EventStoreOperationContext { SkipSnapshot = true }, cancellationToken: cancellationToken ); + var result = resultResult.IsSuccess ? resultResult.Value : null; // Assert telemetry @@ -131,7 +138,7 @@ CancellationToken cancellationToken Any(), Any(), Is(eventType => eventType!.Contains(nameof(OldEvent), StringComparison.Ordinal)), - Any() + Any() ) .WasCalled(Times.Exactly(numberOfOldEventsToCreate)); @@ -141,6 +148,11 @@ CancellationToken cancellationToken [Test] [MethodDataSource(nameof(OldEventCountTestData))] + [SuppressMessage( + "Maintainability", + "CA1506:Avoid excessive class coupling", + Justification = "Test wiring: the store, its infrastructure and the result model are all named here." + )] public async Task GetAsync_GivenAnAggregateWithUnknownEventType_TelemetryLogsSkippedUnknownEvent( int eventsToCreate, int numberOfOldEventsToCreate, @@ -189,15 +201,16 @@ await client.UpsertAsync( ); } - var result = await eventStore.GetAsync( + var resultResult = await eventStore.GetAsync( aggregateId, new EventStoreOperationContext { SkipSnapshot = true }, cancellationToken: cancellationToken ); + var result = resultResult.IsSuccess ? resultResult.Value : null; // Assert telemetry - .SkippedUnknownEvent(aggregateId, Any(), Any(), unknownEventType, Any()) + .SkippedUnknownEvent(aggregateId, Any(), Any(), unknownEventType, Any()) .WasCalled(Times.Exactly(numberOfOldEventsToCreate)); await Assert.That(result).IsNotNull(); diff --git a/src/tests/SqlServer.IntegrationTests/Outbox/SqlServerOutboxIntegrationTests.cs b/src/tests/SqlServer.IntegrationTests/Outbox/SqlServerOutboxIntegrationTests.cs index 29b45c49..ce4afbcb 100644 --- a/src/tests/SqlServer.IntegrationTests/Outbox/SqlServerOutboxIntegrationTests.cs +++ b/src/tests/SqlServer.IntegrationTests/Outbox/SqlServerOutboxIntegrationTests.cs @@ -1,3 +1,5 @@ +using System.Collections.Concurrent; +using System.Diagnostics.CodeAnalysis; using Microsoft.Data.SqlClient; using Microsoft.Extensions.Logging.Abstractions; using Microsoft.Extensions.Options; @@ -15,6 +17,11 @@ namespace Purview.EventSourcing.SqlServer.Outbox; public sealed class SqlServerOutboxIntegrationTests(SqlServerEventStoreFixture fixture) { [Test] + [SuppressMessage( + "Maintainability", + "CA1506:Avoid excessive class coupling", + Justification = "Test wiring: the store, its infrastructure and the result model are all named here." + )] public async Task CommitAsync_GivenEnlistedOutboxAndAggregate_CommitsBothAtomically( CancellationToken cancellationToken ) @@ -37,7 +44,8 @@ await store.EnqueueInTransactionAsync(connection, sqlTransaction, envelope, toke ); var result = await transaction.CommitAsync(cancellationToken); - var savedAggregate = await eventStore.GetAsync(aggregateId, null, cancellationToken); + var savedAggregateResult = await eventStore.GetAsync(aggregateId, null, cancellationToken); + var savedAggregate = savedAggregateResult.IsSuccess ? savedAggregateResult.Value : null; var row = await ReadOutboxRowAsync(tableName, envelope.Id, cancellationToken); await Assert.That(result.Success).IsTrue(); @@ -69,7 +77,8 @@ await store.EnqueueInTransactionAsync(connection, sqlTransaction, envelope, toke transaction.Enlist((_, _, _) => Task.FromException(new InvalidOperationException("enlisted operation failed"))); var result = await transaction.CommitAsync(cancellationToken); - var savedAggregate = await eventStore.GetAsync(aggregateId, null, cancellationToken); + var savedAggregateResult = await eventStore.GetAsync(aggregateId, null, cancellationToken); + var savedAggregate = savedAggregateResult.IsSuccess ? savedAggregateResult.Value : null; var row = await ReadOutboxRowAsync(tableName, envelope.Id, cancellationToken); await Assert.That(result.Success).IsFalse(); @@ -251,7 +260,7 @@ public Task HandleAsync(OutboxEnvelope message, CancellationToken cancellationTo sealed class SlowRecordingHandler : IOutboxHandler { - public List HandledIds { get; } = []; + public ConcurrentBag HandledIds { get; } = []; public async Task HandleAsync(OutboxEnvelope message, CancellationToken cancellationToken) { diff --git a/src/tests/SqlServer.IntegrationTests/Snapshots/ReportUploadAggregateSnapshotEventStoreTests.cs b/src/tests/SqlServer.IntegrationTests/Snapshots/ReportUploadAggregateSnapshotEventStoreTests.cs index 13e2de3f..9395420c 100644 --- a/src/tests/SqlServer.IntegrationTests/Snapshots/ReportUploadAggregateSnapshotEventStoreTests.cs +++ b/src/tests/SqlServer.IntegrationTests/Snapshots/ReportUploadAggregateSnapshotEventStoreTests.cs @@ -65,7 +65,8 @@ CancellationToken cancellationToken await store.SaveAsync(aggregate, cancellationToken); - var restored = await store.GetAsync(id, cancellationToken: cancellationToken); + var restoredResult = await store.GetAsync(id, cancellationToken: cancellationToken); + var restored = restoredResult.IsSuccess ? restoredResult.Value : null; await Assert.That(restored).IsNotNull(); await Assert.That(restored!.ReportSummary).IsNotNull(); diff --git a/src/tests/SqlServer.IntegrationTests/Snapshots/SqlServerSnapshotEventStoreTests.IndexCreation.cs b/src/tests/SqlServer.IntegrationTests/Snapshots/SqlServerSnapshotEventStoreTests.IndexCreation.cs index 5f14b27a..f990929c 100644 --- a/src/tests/SqlServer.IntegrationTests/Snapshots/SqlServerSnapshotEventStoreTests.IndexCreation.cs +++ b/src/tests/SqlServer.IntegrationTests/Snapshots/SqlServerSnapshotEventStoreTests.IndexCreation.cs @@ -38,7 +38,7 @@ CancellationToken cancellationToken var saved = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saved.Saved).IsTrue(); + await Assert.That(saved.IsSuccess && saved.Value.Written).IsTrue(); await Assert .That(await ColumnExistsAsync(fixture.ConnectionString, tableName, computedColumnName, cancellationToken)) .IsTrue(); diff --git a/src/tests/SqlServer.IntegrationTests/Snapshots/SqlServerSnapshotQueryTranslationBoundaryTests.cs b/src/tests/SqlServer.IntegrationTests/Snapshots/SqlServerSnapshotQueryTranslationBoundaryTests.cs index dc26deaf..f7054c94 100644 --- a/src/tests/SqlServer.IntegrationTests/Snapshots/SqlServerSnapshotQueryTranslationBoundaryTests.cs +++ b/src/tests/SqlServer.IntegrationTests/Snapshots/SqlServerSnapshotQueryTranslationBoundaryTests.cs @@ -1,3 +1,4 @@ +using System.Diagnostics.CodeAnalysis; using Purview.EventSourcing.Aggregates.Persistence; using Purview.EventSourcing.Fixtures.SqlServer; using Purview.EventSourcing.Samples.Domain; @@ -54,6 +55,11 @@ public async Task QueryAsync_GivenNonScalarValueObjectMembers_Translates(Cancell } [Test] + [SuppressMessage( + "Maintainability", + "CA1506:Avoid excessive class coupling", + Justification = "Test wiring: the store, its infrastructure and the result model are all named here." + )] public async Task QueryAsync_GivenDirectlyMappedComplexNestedMembers_Translates(CancellationToken cancellationToken) { var store = fixture.CreateSnapshotStore(); diff --git a/src/tests/SqlServer.IntegrationTests/Snapshots/SqlServerSnapshotValueObjectPersistenceTests.cs b/src/tests/SqlServer.IntegrationTests/Snapshots/SqlServerSnapshotValueObjectPersistenceTests.cs index b524244a..44eab8c1 100644 --- a/src/tests/SqlServer.IntegrationTests/Snapshots/SqlServerSnapshotValueObjectPersistenceTests.cs +++ b/src/tests/SqlServer.IntegrationTests/Snapshots/SqlServerSnapshotValueObjectPersistenceTests.cs @@ -62,7 +62,7 @@ var @event in store.GetEventRangeAsync(aggregateId, versionFrom: 1, versionTo: n var eventDisplayName2 = (string) eventUserDetails2.GetType().GetProperty(nameof(UserDetails2.DisplayName))!.GetValue(eventUserDetails2)!; - await Assert.That(saveResult.Saved).IsTrue(); + await Assert.That(saveResult.IsSuccess && saveResult.Value.Written).IsTrue(); await Assert.That(events).Count().IsEqualTo(1); await Assert.That(eventDisplayName).IsEqualTo(displayName); await Assert.That(eventDisplayName2).IsEqualTo(displayName2); diff --git a/src/tools/AdminAPI.OpenAPI/Program.cs b/src/tools/AdminAPI.OpenAPI/Program.cs index 731aebaf..0d0412a7 100644 --- a/src/tools/AdminAPI.OpenAPI/Program.cs +++ b/src/tools/AdminAPI.OpenAPI/Program.cs @@ -1,9 +1,10 @@ using Microsoft.AspNetCore.Hosting.Server; using Microsoft.AspNetCore.Hosting.Server.Features; +using Purview.EventSourcing.Admin.Failures; using Purview.EventSourcing.Admin.Models; using Purview.EventSourcing.Admin.Queries; using Purview.EventSourcing.Admin.Services; - +using Purview.Results; // Exports the Admin API OpenAPI document to a file so it can be committed and used to generate a typed client // (for example with NSwag). Usage: @@ -94,7 +95,7 @@ public Task> SearchAsync( CancellationToken cancellationToken ) => throw new NotSupportedException(); - public Task GetAsync( + public Task> GetAsync( string aggregateType, string aggregateId, CancellationToken cancellationToken @@ -103,7 +104,7 @@ CancellationToken cancellationToken sealed class StubEventQueryService : IAdminEventQueryService { - public Task?> GetRangeAsync( + public Task, AdminQueryFailure>> GetRangeAsync( string aggregateType, string aggregateId, EventRangeQuery query, @@ -113,14 +114,14 @@ CancellationToken cancellationToken sealed class StubProjectionService : IAdminProjectionService { - public Task ProjectAtVersionAsync( + public Task> ProjectAtVersionAsync( string aggregateType, string aggregateId, long targetVersion, CancellationToken cancellationToken ) => throw new NotSupportedException(); - public Task ProjectAtTimeAsync( + public Task> ProjectAtTimeAsync( string aggregateType, string aggregateId, DateTimeOffset targetUtc, From a0997a9c46644e83cefdab6aac965250807a7246 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Sun, 25 Oct 2026 12:23:22 +0000 Subject: [PATCH 09/41] test: make tenant isolation a provider contract and add acceptance scenarios Tenancy was proved per-provider, in four near-identical copies, so a new provider could be added without any tenancy coverage at all. The tests now live in the shared event-store contract suite behind an abstract seam: protected abstract IEventStoreCore CreateTenantScopedEventStore( TenantScope scope, Guid runId); Abstract rather than virtual, so a provider cannot be added without stating how it is scoped. Both scopes in a test share a runId and therefore the same physical storage - sharing storage is what the isolation protects, and a provider returning an isolated store per scope would pass while proving nothing. Five shared tests replace the four per-provider copies, adding the cached-read and unowned-aggregate cases that only one provider had. Also adds EventSourcing.AcceptanceTests: the guarantees stated as BDTest scenarios in domain language, over reusable [StepText] steps, against the in-memory store so they need no container. The AcceptanceTests suffix gives them the Acceptance category, so PR validation's unit filter excludes them. --- Directory.Packages.props | 1 + docs/wiki/Shared-Testing-Framework.md | 54 ++++++++- src/EventSourcing.slnx | 1 + .../AzureTableEventStoreTenancyTests.cs | 72 ------------ .../Events/EventStoreContractTests.cs | 4 + .../AcceptanceAggregate.cs | 34 ++++++ .../EventSourcing.AcceptanceTests.csproj | 9 ++ .../EventStoreScenarioContext.cs | 65 +++++++++++ .../SaveOutcomeScenarios.cs | 32 ++++++ .../Steps/EventStoreAssertions.cs | 40 +++++++ .../Steps/EventStoreSteps.cs | 85 +++++++++++++++ .../TenantIsolationScenarios.cs | 59 ++++++++++ .../Events/EventStoreContractTests.cs | 4 + .../Events/MongoDBEventStoreTenancyTests.cs | 72 ------------ .../Events/EventStoreContractTests.cs | 4 + .../Events/PostgresEventStoreTenancyTests.cs | 72 ------------ .../Contracts/EventStoreContractTestsBase.cs | 103 ++++++++++++++++++ .../Contracts/EventStoreTenantScopeStub.cs | 17 +++ .../Events/EventStoreContractTests.cs | 4 + .../Events/SqlServerEventStoreTenancyTests.cs | 97 ----------------- 20 files changed, 514 insertions(+), 315 deletions(-) delete mode 100644 src/tests/AzureStorage.IntegrationTests/Events/AzureTableEventStoreTenancyTests.cs create mode 100644 src/tests/EventSourcing.AcceptanceTests/AcceptanceAggregate.cs create mode 100644 src/tests/EventSourcing.AcceptanceTests/EventSourcing.AcceptanceTests.csproj create mode 100644 src/tests/EventSourcing.AcceptanceTests/EventStoreScenarioContext.cs create mode 100644 src/tests/EventSourcing.AcceptanceTests/SaveOutcomeScenarios.cs create mode 100644 src/tests/EventSourcing.AcceptanceTests/Steps/EventStoreAssertions.cs create mode 100644 src/tests/EventSourcing.AcceptanceTests/Steps/EventStoreSteps.cs create mode 100644 src/tests/EventSourcing.AcceptanceTests/TenantIsolationScenarios.cs delete mode 100644 src/tests/MongoDB.IntegrationTests/Events/MongoDBEventStoreTenancyTests.cs delete mode 100644 src/tests/Postgres.IntegrationTests/Events/PostgresEventStoreTenancyTests.cs create mode 100644 src/tests/SharedTestingFramework/Contracts/EventStoreTenantScopeStub.cs delete mode 100644 src/tests/SqlServer.IntegrationTests/Events/SqlServerEventStoreTenancyTests.cs diff --git a/Directory.Packages.props b/Directory.Packages.props index 3951f10b..565e1d91 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -27,6 +27,7 @@ + diff --git a/docs/wiki/Shared-Testing-Framework.md b/docs/wiki/Shared-Testing-Framework.md index fb5da1af..dd056f5b 100644 --- a/docs/wiki/Shared-Testing-Framework.md +++ b/docs/wiki/Shared-Testing-Framework.md @@ -67,6 +67,9 @@ public sealed class EventStoreContractTests(SqlServerEventStoreFixtu fixture.CreateEventStore(aggregateChangeNotifier: notifier); protected override Task MarkEventTypesAsUnknownAsync(...) => /* provider-specific event rewrite */; + + protected override IEventStoreCore CreateTenantScopedEventStore(TenantScope scope, Guid runId) => + fixture.CreateEventStore(runId: runId, currentTenant: new EventStoreTenantScopeStub(scope)); } ``` @@ -75,6 +78,52 @@ The shared base classes only exercise the public contracts (`IEventStoreCore` notifications, event ranges, query results) and shared aggregates (`PersistenceAggregate`, `ComplexTestType`). Provider internals are deliberately out of scope for the shared suites. +## Tenant isolation is part of the contract + +The event-store contract suite owns the tenancy tests: one tenant cannot read another's aggregate, +the owning tenant can, the system scope reads across all of them, a cached aggregate is not served +across tenants, and an unowned aggregate is invisible to a tenant. + +The seam those tests use is **abstract**, not virtual: + +```csharp +protected abstract IEventStoreCore CreateTenantScopedEventStore(TenantScope scope, Guid runId); +``` + +A provider cannot be added without stating how it is scoped — there is no default that quietly opts +out. `runId` is shared across the two scopes in a test on purpose: both stores must address the +**same** physical storage, because sharing storage is what the isolation is protecting. A provider +that returns an isolated store per scope will pass the tests while proving nothing. + +`EventStoreTenantScopeStub` (an `ICurrentTenant` fixed to one scope) is named to match the +`Contracts\EventStore*.cs` link glob, so it travels with the contract suite. + +## Acceptance suite + +`src/tests/EventSourcing.AcceptanceTests` states the guarantees the framework makes as +[BDTest](https://github.com/thomhurst/BDTest) scenarios, in domain language: + +```csharp +await Given(() => Steps.AnAggregateExistsForTenant("acme", 5)) + .And(() => Steps.TheTenantReadsTheAggregateTwice("acme")) + .When(() => Steps.TheTenantReadsTheAggregate("globex")) + .Then(() => Expect.TheAggregateIsReportedAsAbsent()) + .WithScenarioText("A cached aggregate is not served to another tenant"); +``` + +Steps live in `Steps/EventStoreSteps.cs` (actions) and `Steps/EventStoreAssertions.cs` (outcomes), +each carrying `[StepText]` so a scenario reads as prose in the BDTest report. They are reusable: a +new scenario is assembled from existing steps rather than written from scratch. + +The suite runs against the **in-memory** store, so a scenario describing a guarantee needs no +container. That store enforces the same tenant isolation and returns the same result cases as the +persistent providers. Behaviour that depends on real storage — query translation, crypto-shredding, +transactions — belongs in the provider integration suites instead. + +The project's `AcceptanceTests` suffix gives it `PurviewTestType=AcceptanceTests` and the TUnit +category `Acceptance`, so PR validation's `[Category=Unit]` filter excludes it. Run it with +`just test '/*/*/*/*[Category=Acceptance]'`. + ## Where each suite runs | Suite | AzureStorage | CosmosDb | MongoDB | Postgres | SqlServer | @@ -91,8 +140,9 @@ notifications, event ranges, query results) and shared aggregates (`PersistenceA links in the existing provider test projects. 2. Add an `EventStoreContractTests` (and/or `SnapshotStoreContractTests`) derived class wired to the provider fixture. -3. Implement the provider-specific seams (`MarkEventTypesAsUnknownAsync` for the unknown-event test, - `SnapshotAsync` for the snapshot suite). +3. Implement the provider-specific seams (`CreateTenantScopedEventStore` for the tenancy tests, + `MarkEventTypesAsUnknownAsync` for the unknown-event test, `SnapshotAsync` for the snapshot + suite). Only `CreateTenantScopedEventStore` is abstract; the compiler will ask for it. 4. Add guard tests for capabilities that are not part of the shared contract. ## Adding a shared test diff --git a/src/EventSourcing.slnx b/src/EventSourcing.slnx index 889e2ffe..0039aa52 100644 --- a/src/EventSourcing.slnx +++ b/src/EventSourcing.slnx @@ -55,6 +55,7 @@ + diff --git a/src/tests/AzureStorage.IntegrationTests/Events/AzureTableEventStoreTenancyTests.cs b/src/tests/AzureStorage.IntegrationTests/Events/AzureTableEventStoreTenancyTests.cs deleted file mode 100644 index a73b57fe..00000000 --- a/src/tests/AzureStorage.IntegrationTests/Events/AzureTableEventStoreTenancyTests.cs +++ /dev/null @@ -1,72 +0,0 @@ -using Purview.EventSourcing.Aggregates.Persistence; -using Purview.EventSourcing.Fixtures.AzureStorage; -using Purview.EventSourcing.Tenancy; - -namespace Purview.EventSourcing.AzureStorage.Events; - -/// -/// Guards that the tenant query filter isolates event streams. -/// -/// -/// Exercised against real Azure Table Storage rather than in memory: the isolation is an Entity Framework global -/// query filter translated into SQL, so an in-memory substitute would prove nothing about the predicate -/// that actually runs. -/// -[ClassDataSource(Shared = SharedType.PerAssembly)] -public sealed class AzureTableEventStoreTenancyTests(TableEventStoreFixture fixture) -{ - sealed class StubTenant(TenantScope scope) : ICurrentTenant - { - public TenantScope Current => scope; - } - - TableEventStore StoreFor(TenantScope scope, Guid runId) => - fixture.CreateEventStore(currentTenant: new StubTenant(scope), runId: runId); - - [Test] - public async Task GetAsync_GivenAnotherTenantsAggregate_DoesNotReturnIt(CancellationToken cancellationToken) - { - // Arrange - one physical table, two tenants, the same aggregate id. - var runId = Guid.NewGuid(); - var aggregateId = $"{Guid.NewGuid()}"; - - var acme = StoreFor(TenantScope.For("acme"), runId); - var globex = StoreFor(TenantScope.For("globex"), runId); - - var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); - aggregate.IncrementInt32Value(); - - var saved = await acme.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saved.IsSuccess).IsTrue(); - - // Act - var fromOwner = await acme.GetAsync(aggregateId, cancellationToken: cancellationToken); - var fromOther = await globex.GetAsync(aggregateId, cancellationToken: cancellationToken); - - // Assert - await Assert.That(fromOwner.IsSuccess).IsTrue(); - await Assert.That(fromOther.IsFailure).IsTrue(); - } - - [Test] - public async Task GetAsync_GivenSystemScope_ReadsAcrossTenants(CancellationToken cancellationToken) - { - // Arrange - var runId = Guid.NewGuid(); - var aggregateId = $"{Guid.NewGuid()}"; - - var acme = StoreFor(TenantScope.For("acme"), runId); - var system = StoreFor(TenantScope.System, runId); - - var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); - aggregate.IncrementInt32Value(); - - await acme.SaveAsync(aggregate, cancellationToken: cancellationToken); - - // Act - infrastructure work deliberately crosses tenants. - var result = await system.GetAsync(aggregateId, cancellationToken: cancellationToken); - - // Assert - await Assert.That(result.IsSuccess).IsTrue(); - } -} diff --git a/src/tests/AzureStorage.IntegrationTests/Events/EventStoreContractTests.cs b/src/tests/AzureStorage.IntegrationTests/Events/EventStoreContractTests.cs index 119d53a5..33a2f8b8 100644 --- a/src/tests/AzureStorage.IntegrationTests/Events/EventStoreContractTests.cs +++ b/src/tests/AzureStorage.IntegrationTests/Events/EventStoreContractTests.cs @@ -5,6 +5,7 @@ using Purview.EventSourcing.ChangeFeed; using Purview.EventSourcing.Contracts; using Purview.EventSourcing.Fixtures.AzureStorage; +using Purview.EventSourcing.Tenancy; namespace Purview.EventSourcing.AzureStorage.Events; @@ -71,4 +72,7 @@ CancellationToken cancellationToken await tableClient.SubmitBatchAsync(batch, cancellationToken); } + + protected override IEventStoreCore CreateTenantScopedEventStore(TenantScope scope, Guid runId) => + fixture.CreateEventStore(currentTenant: new EventStoreTenantScopeStub(scope), runId: runId); } diff --git a/src/tests/EventSourcing.AcceptanceTests/AcceptanceAggregate.cs b/src/tests/EventSourcing.AcceptanceTests/AcceptanceAggregate.cs new file mode 100644 index 00000000..8bbc84e9 --- /dev/null +++ b/src/tests/EventSourcing.AcceptanceTests/AcceptanceAggregate.cs @@ -0,0 +1,34 @@ +using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Aggregates.Events; + +namespace Purview.EventSourcing; + +/// +/// The aggregate the acceptance scenarios act on. +/// +public sealed class AcceptanceAggregate : AggregateBase +{ + /// The running total. + public int Value { get; private set; } + + /// + protected override void RegisterEvents() => Register(@event => Value += @event.Amount); + + /// Records an increment. + /// The amount to add. + public void Increment(int amount) => RecordAndApply(new ValueIncremented { Amount = amount }); +} + +/// An increment to the aggregate's value. +[EventContract] +public sealed record ValueIncremented +{ + /// The event schema version. + public static int SchemaVersion => 1; + + /// The event metadata. + public EventMetadata Metadata { get; init; } + + /// The amount added. + public int Amount { get; set; } +} diff --git a/src/tests/EventSourcing.AcceptanceTests/EventSourcing.AcceptanceTests.csproj b/src/tests/EventSourcing.AcceptanceTests/EventSourcing.AcceptanceTests.csproj new file mode 100644 index 00000000..88144c21 --- /dev/null +++ b/src/tests/EventSourcing.AcceptanceTests/EventSourcing.AcceptanceTests.csproj @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/src/tests/EventSourcing.AcceptanceTests/EventStoreScenarioContext.cs b/src/tests/EventSourcing.AcceptanceTests/EventStoreScenarioContext.cs new file mode 100644 index 00000000..aadc19a3 --- /dev/null +++ b/src/tests/EventSourcing.AcceptanceTests/EventStoreScenarioContext.cs @@ -0,0 +1,65 @@ +using Microsoft.Extensions.DependencyInjection; +using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Failures; +using Purview.EventSourcing.InMemory.Events; +using Purview.EventSourcing.Tenancy; +using Purview.Results; + +namespace Purview.EventSourcing; + +/// +/// The state one acceptance scenario builds up and asserts against. +/// +/// +/// Backed by the in-memory store so a scenario describing a guarantee runs anywhere, with no container. +/// The in-memory store enforces the same tenant isolation and returns the same result cases as the +/// persistent providers, which is what these scenarios are about; behaviour that depends on real storage +/// - query translation, crypto-shredding, transactions - belongs in the provider integration suites. +/// +public sealed class EventStoreScenarioContext : IDisposable +{ + readonly ServiceProvider _provider; + + /// Creates the context and its store. + public EventStoreScenarioContext() + { + ServiceCollection services = new(); + services.AddLogging(); + services.AddEventSourcing().AddInMemoryEventStore(); + + _provider = services.BuildServiceProvider(); + Store = _provider.GetRequiredService>(); + } + + /// The store every step acts through. + public IInMemoryEventStore Store { get; } + + /// The aggregate identifier the scenario is working with. + public string AggregateId { get; set; } = $"{Guid.NewGuid()}"; + + /// The aggregate most recently created or read. + public AcceptanceAggregate? Aggregate { get; set; } + + /// The result of the most recent read. + public Result? ReadResult { get; set; } + + /// The result of the most recent save. + public Result, AggregateSaveFailure>? SaveResult { get; set; } + + /// Runs an action under a tenant scope. + /// The tenant, or for the system scope. + /// The work to run. + public static async Task AsTenantAsync(string? tenant, Func action) + { + var scope = tenant is null ? TenantScope.System : TenantScope.For(tenant); + + using (AmbientCurrentTenant.BeginScope(scope)) + await action(); + } + + /// The operation context scenarios use; no principal is configured. + public static EventStoreOperationContext OperationContext() => new() { RequiresValidPrincipalIdentifier = false }; + + /// + public void Dispose() => _provider.Dispose(); +} diff --git a/src/tests/EventSourcing.AcceptanceTests/SaveOutcomeScenarios.cs b/src/tests/EventSourcing.AcceptanceTests/SaveOutcomeScenarios.cs new file mode 100644 index 00000000..d94e8c66 --- /dev/null +++ b/src/tests/EventSourcing.AcceptanceTests/SaveOutcomeScenarios.cs @@ -0,0 +1,32 @@ +using BDTest; +using Purview.EventSourcing.Steps; + +namespace Purview.EventSourcing; + +/// +/// How the store reports the outcome of a save, stated as scenarios. +/// +/// +/// The distinction these protect is that a save which wrote nothing is a success, while a lost update +/// is a failure - the ambiguity the previous bool-returning API could not express. +/// +public sealed class SaveOutcomeScenarios : TUnitBDTestBase +{ + EventStoreSteps Steps => field ??= new(Context); + + EventStoreAssertions Expect => field ??= new(Context); + + [Test] + public async Task SavingWithNothingToWriteIsASuccess() => + await Given(() => Steps.AnAggregateExistsForTenant("acme", 5)) + .When(() => Steps.TheAggregateIsSavedWithNoChanges()) + .Then(() => Expect.TheSaveSucceedsHavingWrittenNothing()) + .WithScenarioText("Saving an aggregate with nothing to write is a success, not a failure"); + + [Test] + public async Task ALostUpdateIsReportedRatherThanThrown() => + await Given(() => Steps.AnAggregateExistsForTenant("acme", 5)) + .When(() => Steps.ASecondWriterSavesACompetingChange()) + .Then(() => Expect.TheSaveIsRefusedAsAConcurrencyConflict()) + .WithScenarioText("A lost update is reported as a concurrency conflict, not thrown"); +} diff --git a/src/tests/EventSourcing.AcceptanceTests/Steps/EventStoreAssertions.cs b/src/tests/EventSourcing.AcceptanceTests/Steps/EventStoreAssertions.cs new file mode 100644 index 00000000..577f0594 --- /dev/null +++ b/src/tests/EventSourcing.AcceptanceTests/Steps/EventStoreAssertions.cs @@ -0,0 +1,40 @@ +using BDTest; +using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Failures; + +namespace Purview.EventSourcing.Steps; + +/// +/// The outcomes an acceptance scenario asserts. +/// +/// The scenario's state. +public sealed class EventStoreAssertions(EventStoreScenarioContext context) +{ + [StepText("the aggregate is returned")] + public async Task TheAggregateIsReturned() => await Assert.That(context.ReadResult!.Value.IsSuccess).IsTrue(); + + [StepText("the aggregate is reported as absent")] + public async Task TheAggregateIsReportedAsAbsent() + { + await Assert.That(context.ReadResult!.Value.IsFailure).IsTrue(); + await Assert.That(context.ReadResult!.Value.Error is AggregateNotFound).IsTrue(); + } + + [StepText("the value is {amount}")] + public async Task TheValueIs(int amount) => + await Assert.That(context.ReadResult!.Value.Value.Value).IsEqualTo(amount); + + [StepText("the save succeeds having written nothing")] + public async Task TheSaveSucceedsHavingWrittenNothing() + { + await Assert.That(context.SaveResult!.Value.IsSuccess).IsTrue(); + await Assert.That(context.SaveResult!.Value.Value.Kind).IsEqualTo(SaveOutcomeKind.NoChanges); + } + + [StepText("the save is refused as a concurrency conflict")] + public async Task TheSaveIsRefusedAsAConcurrencyConflict() + { + await Assert.That(context.SaveResult!.Value.IsFailure).IsTrue(); + await Assert.That(context.SaveResult!.Value.Error is ConcurrencyConflict).IsTrue(); + } +} diff --git a/src/tests/EventSourcing.AcceptanceTests/Steps/EventStoreSteps.cs b/src/tests/EventSourcing.AcceptanceTests/Steps/EventStoreSteps.cs new file mode 100644 index 00000000..3468a69d --- /dev/null +++ b/src/tests/EventSourcing.AcceptanceTests/Steps/EventStoreSteps.cs @@ -0,0 +1,85 @@ +using BDTest; + +namespace Purview.EventSourcing.Steps; + +/// +/// The actions an acceptance scenario performs against the event store. +/// +/// +/// Reusable across scenarios: a step describes an intent in domain language, so the same step reads +/// correctly wherever it appears and a new scenario is assembled rather than written. +/// +/// The scenario's state. +public sealed class EventStoreSteps(EventStoreScenarioContext context) +{ + [StepText("tenant {tenant} has an aggregate with a value of {amount}")] + public Task AnAggregateExistsForTenant(string tenant, int amount) => + EventStoreScenarioContext.AsTenantAsync( + tenant, + async () => + { + var aggregate = await context.Store.CreateAsync(context.AggregateId); + aggregate.Increment(amount); + + await context.Store.SaveAsync(aggregate, EventStoreScenarioContext.OperationContext()); + } + ); + + [StepText("an aggregate exists that belongs to no tenant")] + public Task AnUnownedAggregateExists() => AnAggregateExistsForTenant(tenant: null!, amount: 1); + + [StepText("tenant {tenant} reads that aggregate")] + public Task TheTenantReadsTheAggregate(string tenant) => + EventStoreScenarioContext.AsTenantAsync( + tenant, + async () => + context.ReadResult = await context.Store.GetAsync( + context.AggregateId, + EventStoreScenarioContext.OperationContext() + ) + ); + + [StepText("infrastructure reads that aggregate across every tenant")] + public Task InfrastructureReadsTheAggregate() => TheTenantReadsTheAggregate(tenant: null!); + + [StepText("tenant {tenant} reads the aggregate twice, so it is cached")] + public async Task TheTenantReadsTheAggregateTwice(string tenant) + { + await TheTenantReadsTheAggregate(tenant); + await TheTenantReadsTheAggregate(tenant); + } + + [StepText("the aggregate is saved again with nothing changed")] + public Task TheAggregateIsSavedWithNoChanges() => + EventStoreScenarioContext.AsTenantAsync( + null, + async () => + { + var read = await context.Store.GetAsync( + context.AggregateId, + EventStoreScenarioContext.OperationContext() + ); + + context.SaveResult = await context.Store.SaveAsync( + read.Value, + EventStoreScenarioContext.OperationContext() + ); + } + ); + + // A second writer that never saw the first writer's event. This is the shape of a lost update, and + // the store must report it rather than overwrite or throw. + [StepText("a second writer saves a competing change to the same aggregate")] + public Task ASecondWriterSavesACompetingChange() => + EventStoreScenarioContext.AsTenantAsync( + null, + async () => + { + AcceptanceAggregate stale = new(); + stale.Details.Id = context.AggregateId; + stale.Increment(1); + + context.SaveResult = await context.Store.SaveAsync(stale, EventStoreScenarioContext.OperationContext()); + } + ); +} diff --git a/src/tests/EventSourcing.AcceptanceTests/TenantIsolationScenarios.cs b/src/tests/EventSourcing.AcceptanceTests/TenantIsolationScenarios.cs new file mode 100644 index 00000000..a6a7e462 --- /dev/null +++ b/src/tests/EventSourcing.AcceptanceTests/TenantIsolationScenarios.cs @@ -0,0 +1,59 @@ +using BDTest; +using Purview.EventSourcing.Steps; + +namespace Purview.EventSourcing; + +/// +/// The tenant isolation guarantee, stated as scenarios. +/// +/// +/// These read as the promise the framework makes, rather than as a test of how it is implemented. Each +/// one corresponds to a real defect found while the unit and integration suites were green. +/// +public sealed class TenantIsolationScenarios : TUnitBDTestBase +{ + EventStoreSteps Steps => field ??= new(Context); + + EventStoreAssertions Expect => field ??= new(Context); + + [Test] + public async Task OneTenantCannotReadAnotherTenantsAggregate() => + await Given(() => Steps.AnAggregateExistsForTenant("acme", 5)) + .When(() => Steps.TheTenantReadsTheAggregate("globex")) + .Then(() => Expect.TheAggregateIsReportedAsAbsent()) + .WithScenarioText("One tenant cannot read another tenant's aggregate"); + + [Test] + public async Task TheOwningTenantCanReadItsOwnAggregate() => + await Given(() => Steps.AnAggregateExistsForTenant("acme", 5)) + .When(() => Steps.TheTenantReadsTheAggregate("acme")) + .Then(() => Expect.TheAggregateIsReturned()) + .And(() => Expect.TheValueIs(5)) + .WithScenarioText("The owning tenant can read its own aggregate"); + + [Test] + public async Task InfrastructureCanReadAcrossEveryTenant() => + await Given(() => Steps.AnAggregateExistsForTenant("acme", 5)) + .When(() => Steps.InfrastructureReadsTheAggregate()) + .Then(() => Expect.TheAggregateIsReturned()) + .WithScenarioText("Infrastructure can read across every tenant"); + + // The cache is consulted before the tenant-filtered storage lookup, so priming it as the owner is + // what exposes an unqualified cache key. + [Test] + public async Task ACachedAggregateIsNotServedToAnotherTenant() => + await Given(() => Steps.AnAggregateExistsForTenant("acme", 5)) + .And(() => Steps.TheTenantReadsTheAggregateTwice("acme")) + .When(() => Steps.TheTenantReadsTheAggregate("globex")) + .Then(() => Expect.TheAggregateIsReportedAsAbsent()) + .WithScenarioText("A cached aggregate is not served to another tenant"); + + // Fail-closed: a write path that missed the tenant stamp produces absent data for its own tenant, + // rather than data readable by all of them. + [Test] + public async Task DataBelongingToNoTenantIsNotVisibleToATenant() => + await Given(() => Steps.AnUnownedAggregateExists()) + .When(() => Steps.TheTenantReadsTheAggregate("acme")) + .Then(() => Expect.TheAggregateIsReportedAsAbsent()) + .WithScenarioText("Data belonging to no tenant is not visible to a tenant"); +} diff --git a/src/tests/MongoDB.IntegrationTests/Events/EventStoreContractTests.cs b/src/tests/MongoDB.IntegrationTests/Events/EventStoreContractTests.cs index 3db35e62..2b689027 100644 --- a/src/tests/MongoDB.IntegrationTests/Events/EventStoreContractTests.cs +++ b/src/tests/MongoDB.IntegrationTests/Events/EventStoreContractTests.cs @@ -4,6 +4,7 @@ using Purview.EventSourcing.Contracts; using Purview.EventSourcing.Fixtures.MongoDB; using Purview.EventSourcing.MongoDB.StorageClient; +using Purview.EventSourcing.Tenancy; namespace Purview.EventSourcing.MongoDB.Events; @@ -70,4 +71,7 @@ CancellationToken cancellationToken await eventClient.SubmitBatchAsync(batch, cancellationToken); } + + protected override IEventStoreCore CreateTenantScopedEventStore(TenantScope scope, Guid runId) => + fixture.CreateEventStore(currentTenant: new EventStoreTenantScopeStub(scope), runId: runId); } diff --git a/src/tests/MongoDB.IntegrationTests/Events/MongoDBEventStoreTenancyTests.cs b/src/tests/MongoDB.IntegrationTests/Events/MongoDBEventStoreTenancyTests.cs deleted file mode 100644 index a4da1fa2..00000000 --- a/src/tests/MongoDB.IntegrationTests/Events/MongoDBEventStoreTenancyTests.cs +++ /dev/null @@ -1,72 +0,0 @@ -using Purview.EventSourcing.Aggregates.Persistence; -using Purview.EventSourcing.Fixtures.MongoDB; -using Purview.EventSourcing.Tenancy; - -namespace Purview.EventSourcing.MongoDB.Events; - -/// -/// Guards that the tenant query filter isolates event streams. -/// -/// -/// Exercised against real MongoDB rather than in memory: the isolation is an Entity Framework global -/// query filter translated into SQL, so an in-memory substitute would prove nothing about the predicate -/// that actually runs. -/// -[ClassDataSource(Shared = SharedType.PerAssembly)] -public sealed class MongoDBEventStoreTenancyTests(MongoDBEventStoreFixture fixture) -{ - sealed class StubTenant(TenantScope scope) : ICurrentTenant - { - public TenantScope Current => scope; - } - - MongoDBEventStore StoreFor(TenantScope scope, Guid runId) => - fixture.CreateEventStore(currentTenant: new StubTenant(scope), runId: runId); - - [Test] - public async Task GetAsync_GivenAnotherTenantsAggregate_DoesNotReturnIt(CancellationToken cancellationToken) - { - // Arrange - one physical table, two tenants, the same aggregate id. - var runId = Guid.NewGuid(); - var aggregateId = $"{Guid.NewGuid()}"; - - var acme = StoreFor(TenantScope.For("acme"), runId); - var globex = StoreFor(TenantScope.For("globex"), runId); - - var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); - aggregate.IncrementInt32Value(); - - var saved = await acme.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saved.IsSuccess).IsTrue(); - - // Act - var fromOwner = await acme.GetAsync(aggregateId, cancellationToken: cancellationToken); - var fromOther = await globex.GetAsync(aggregateId, cancellationToken: cancellationToken); - - // Assert - await Assert.That(fromOwner.IsSuccess).IsTrue(); - await Assert.That(fromOther.IsFailure).IsTrue(); - } - - [Test] - public async Task GetAsync_GivenSystemScope_ReadsAcrossTenants(CancellationToken cancellationToken) - { - // Arrange - var runId = Guid.NewGuid(); - var aggregateId = $"{Guid.NewGuid()}"; - - var acme = StoreFor(TenantScope.For("acme"), runId); - var system = StoreFor(TenantScope.System, runId); - - var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); - aggregate.IncrementInt32Value(); - - await acme.SaveAsync(aggregate, cancellationToken: cancellationToken); - - // Act - infrastructure work deliberately crosses tenants. - var result = await system.GetAsync(aggregateId, cancellationToken: cancellationToken); - - // Assert - await Assert.That(result.IsSuccess).IsTrue(); - } -} diff --git a/src/tests/Postgres.IntegrationTests/Events/EventStoreContractTests.cs b/src/tests/Postgres.IntegrationTests/Events/EventStoreContractTests.cs index a01d7831..af6eb645 100644 --- a/src/tests/Postgres.IntegrationTests/Events/EventStoreContractTests.cs +++ b/src/tests/Postgres.IntegrationTests/Events/EventStoreContractTests.cs @@ -3,6 +3,7 @@ using Purview.EventSourcing.ChangeFeed; using Purview.EventSourcing.Contracts; using Purview.EventSourcing.Fixtures.Postgres; +using Purview.EventSourcing.Tenancy; namespace Purview.EventSourcing.Postgres.Events; @@ -66,4 +67,7 @@ await client.UpsertAsync( ); } } + + protected override IEventStoreCore CreateTenantScopedEventStore(TenantScope scope, Guid runId) => + fixture.CreateEventStore(runId: runId, currentTenant: new EventStoreTenantScopeStub(scope)); } diff --git a/src/tests/Postgres.IntegrationTests/Events/PostgresEventStoreTenancyTests.cs b/src/tests/Postgres.IntegrationTests/Events/PostgresEventStoreTenancyTests.cs deleted file mode 100644 index c994d439..00000000 --- a/src/tests/Postgres.IntegrationTests/Events/PostgresEventStoreTenancyTests.cs +++ /dev/null @@ -1,72 +0,0 @@ -using Purview.EventSourcing.Aggregates.Persistence; -using Purview.EventSourcing.Fixtures.Postgres; -using Purview.EventSourcing.Tenancy; - -namespace Purview.EventSourcing.Postgres.Events; - -/// -/// Guards that the tenant query filter isolates event streams. -/// -/// -/// Exercised against real PostgreSQL rather than in memory: the isolation is an Entity Framework global -/// query filter translated into SQL, so an in-memory substitute would prove nothing about the predicate -/// that actually runs. -/// -[ClassDataSource(Shared = SharedType.PerAssembly)] -public sealed class PostgresEventStoreTenancyTests(PostgresEventStoreFixture fixture) -{ - sealed class StubTenant(TenantScope scope) : ICurrentTenant - { - public TenantScope Current => scope; - } - - PostgresEventStore StoreFor(TenantScope scope, Guid runId) => - fixture.CreateEventStore(runId: runId, currentTenant: new StubTenant(scope)); - - [Test] - public async Task GetAsync_GivenAnotherTenantsAggregate_DoesNotReturnIt(CancellationToken cancellationToken) - { - // Arrange - one physical table, two tenants, the same aggregate id. - var runId = Guid.NewGuid(); - var aggregateId = $"{Guid.NewGuid()}"; - - var acme = StoreFor(TenantScope.For("acme"), runId); - var globex = StoreFor(TenantScope.For("globex"), runId); - - var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); - aggregate.IncrementInt32Value(); - - var saved = await acme.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saved.IsSuccess).IsTrue(); - - // Act - var fromOwner = await acme.GetAsync(aggregateId, cancellationToken: cancellationToken); - var fromOther = await globex.GetAsync(aggregateId, cancellationToken: cancellationToken); - - // Assert - await Assert.That(fromOwner.IsSuccess).IsTrue(); - await Assert.That(fromOther.IsFailure).IsTrue(); - } - - [Test] - public async Task GetAsync_GivenSystemScope_ReadsAcrossTenants(CancellationToken cancellationToken) - { - // Arrange - var runId = Guid.NewGuid(); - var aggregateId = $"{Guid.NewGuid()}"; - - var acme = StoreFor(TenantScope.For("acme"), runId); - var system = StoreFor(TenantScope.System, runId); - - var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); - aggregate.IncrementInt32Value(); - - await acme.SaveAsync(aggregate, cancellationToken: cancellationToken); - - // Act - infrastructure work deliberately crosses tenants. - var result = await system.GetAsync(aggregateId, cancellationToken: cancellationToken); - - // Assert - await Assert.That(result.IsSuccess).IsTrue(); - } -} diff --git a/src/tests/SharedTestingFramework/Contracts/EventStoreContractTestsBase.cs b/src/tests/SharedTestingFramework/Contracts/EventStoreContractTestsBase.cs index 2426bc0c..5a510238 100644 --- a/src/tests/SharedTestingFramework/Contracts/EventStoreContractTestsBase.cs +++ b/src/tests/SharedTestingFramework/Contracts/EventStoreContractTestsBase.cs @@ -1,6 +1,7 @@ using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.ChangeFeed; using Purview.EventSourcing.Failures; +using Purview.EventSourcing.Tenancy; namespace Purview.EventSourcing.Contracts; @@ -25,6 +26,26 @@ protected abstract IEventStoreCore CreateEventStore( IAggregateChangeFeedNotifier? changeFeedNotifier ); + /// + /// Creates a store bound to a tenant scope, sharing storage with every other store created for the + /// same . + /// + /// The tenant the store runs under. + /// Identifies the storage the stores share. + /// + /// + /// Abstract rather than virtual, so a provider cannot be added without stating how it is scoped. The + /// tenancy tests below are the reason: they were previously per-provider copies, and a provider that + /// simply never had one looked just as green as a provider that passed. + /// + /// + /// **Sharing storage is the whole point.** Two stores built with different run identifiers use + /// different tables, databases or containers, so "the other tenant cannot see it" passes while + /// proving nothing. + /// + /// + protected abstract IEventStoreCore CreateTenantScopedEventStore(TenantScope scope, Guid runId); + /// /// Rewrites the stored event-type names for a range of events so they can no longer be resolved. /// Used by the unknown-event-type test to simulate schema/type evolution. Providers that cannot @@ -40,6 +61,88 @@ CancellationToken cancellationToken ) => throw new NotSupportedException($"{GetType().Name} does not support marking stored event types as unknown."); #pragma warning restore CA1506 + async Task SeedForTenantAsync(Guid runId, string tenantId, CancellationToken cancellationToken) + { + var aggregateId = $"{Guid.NewGuid()}"; + var store = CreateTenantScopedEventStore(TenantScope.For(tenantId), runId); + + var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); + aggregate.IncrementInt32Value(); + + var saved = await store.SaveAsync(aggregate, cancellationToken: cancellationToken); + + await Assert.That(saved.IsSuccess).IsTrue(); + + return aggregateId; + } + + [Test] + public async Task GetAsync_GivenAnotherTenantsAggregate_DoesNotReturnIt(CancellationToken cancellationToken) + { + var runId = Guid.NewGuid(); + var aggregateId = await SeedForTenantAsync(runId, "acme", cancellationToken); + + var owner = CreateTenantScopedEventStore(TenantScope.For("acme"), runId); + var other = CreateTenantScopedEventStore(TenantScope.For("globex"), runId); + + await Assert.That((await owner.GetAsync(aggregateId, cancellationToken: cancellationToken)).IsSuccess).IsTrue(); + await Assert.That((await other.GetAsync(aggregateId, cancellationToken: cancellationToken)).IsFailure).IsTrue(); + } + + [Test] + public async Task GetAsync_GivenSystemScope_ReadsAcrossTenants(CancellationToken cancellationToken) + { + var runId = Guid.NewGuid(); + var aggregateId = await SeedForTenantAsync(runId, "acme", cancellationToken); + + var system = CreateTenantScopedEventStore(TenantScope.System, runId); + + await Assert + .That((await system.GetAsync(aggregateId, cancellationToken: cancellationToken)).IsSuccess) + .IsTrue(); + } + + // The distributed cache is read before the tenant-filtered storage lookup, so an unqualified cache + // key serves one tenant's aggregate to another ahead of every storage filter. Reading twice as the + // owner guarantees the entry is cached before the other tenant asks for it. + [Test] + public async Task GetAsync_GivenACachedAggregate_DoesNotServeItToAnotherTenant(CancellationToken cancellationToken) + { + var runId = Guid.NewGuid(); + var aggregateId = await SeedForTenantAsync(runId, "acme", cancellationToken); + + var owner = CreateTenantScopedEventStore(TenantScope.For("acme"), runId); + await owner.GetAsync(aggregateId, cancellationToken: cancellationToken); + await Assert.That((await owner.GetAsync(aggregateId, cancellationToken: cancellationToken)).IsSuccess).IsTrue(); + + var other = CreateTenantScopedEventStore(TenantScope.For("globex"), runId); + + await Assert.That((await other.GetAsync(aggregateId, cancellationToken: cancellationToken)).IsFailure).IsTrue(); + } + + // An unowned row - written tenant-less, or by a write path that missed the stamp - must not become + // visible to every tenant. Failing closed turns a stamping bug into absent data, not a leak. + [Test] + public async Task GetAsync_GivenAnUnownedAggregate_IsNotVisibleToATenant(CancellationToken cancellationToken) + { + var runId = Guid.NewGuid(); + var aggregateId = $"{Guid.NewGuid()}"; + + var system = CreateTenantScopedEventStore(TenantScope.System, runId); + var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); + aggregate.IncrementInt32Value(); + await system.SaveAsync(aggregate, cancellationToken: cancellationToken); + + var tenant = CreateTenantScopedEventStore(TenantScope.For("acme"), runId); + + await Assert + .That((await tenant.GetAsync(aggregateId, cancellationToken: cancellationToken)).IsFailure) + .IsTrue(); + await Assert + .That((await system.GetAsync(aggregateId, cancellationToken: cancellationToken)).IsSuccess) + .IsTrue(); + } + [Test] public async Task SaveAsync_GivenAggregateLoadedBeforeAnotherWriterSaved_ReturnsConcurrencyConflict( CancellationToken cancellationToken diff --git a/src/tests/SharedTestingFramework/Contracts/EventStoreTenantScopeStub.cs b/src/tests/SharedTestingFramework/Contracts/EventStoreTenantScopeStub.cs new file mode 100644 index 00000000..3f871759 --- /dev/null +++ b/src/tests/SharedTestingFramework/Contracts/EventStoreTenantScopeStub.cs @@ -0,0 +1,17 @@ +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.Contracts; + +/// +/// An fixed to one scope, for the tenancy contract tests. +/// +/// +/// Named to match the Contracts\EventStore*.cs link glob the provider test projects use, so it +/// travels with the contract suite rather than needing a reference in each project. +/// +/// The scope to report. +public sealed class EventStoreTenantScopeStub(TenantScope scope) : ICurrentTenant +{ + /// + public TenantScope Current => scope; +} diff --git a/src/tests/SqlServer.IntegrationTests/Events/EventStoreContractTests.cs b/src/tests/SqlServer.IntegrationTests/Events/EventStoreContractTests.cs index 9e91544f..7ea411aa 100644 --- a/src/tests/SqlServer.IntegrationTests/Events/EventStoreContractTests.cs +++ b/src/tests/SqlServer.IntegrationTests/Events/EventStoreContractTests.cs @@ -3,6 +3,7 @@ using Purview.EventSourcing.ChangeFeed; using Purview.EventSourcing.Contracts; using Purview.EventSourcing.Fixtures.SqlServer; +using Purview.EventSourcing.Tenancy; namespace Purview.EventSourcing.SqlServer.Events; @@ -66,4 +67,7 @@ await client.UpsertAsync( ); } } + + protected override IEventStoreCore CreateTenantScopedEventStore(TenantScope scope, Guid runId) => + fixture.CreateEventStore(runId: runId, currentTenant: new EventStoreTenantScopeStub(scope)); } diff --git a/src/tests/SqlServer.IntegrationTests/Events/SqlServerEventStoreTenancyTests.cs b/src/tests/SqlServer.IntegrationTests/Events/SqlServerEventStoreTenancyTests.cs deleted file mode 100644 index 4fa943ed..00000000 --- a/src/tests/SqlServer.IntegrationTests/Events/SqlServerEventStoreTenancyTests.cs +++ /dev/null @@ -1,97 +0,0 @@ -using Purview.EventSourcing.Aggregates.Persistence; -using Purview.EventSourcing.Fixtures.SqlServer; -using Purview.EventSourcing.Tenancy; - -namespace Purview.EventSourcing.SqlServer.Events; - -/// -/// Guards that the tenant query filter isolates event streams. -/// -/// -/// Exercised against real SQL Server rather than in memory: the isolation is an Entity Framework global -/// query filter translated into SQL, so an in-memory substitute would prove nothing about the predicate -/// that actually runs. -/// -[ClassDataSource(Shared = SharedType.PerAssembly)] -public sealed class SqlServerEventStoreTenancyTests(SqlServerEventStoreFixture fixture) -{ - sealed class StubTenant(TenantScope scope) : ICurrentTenant - { - public TenantScope Current => scope; - } - - SqlServerEventStore StoreFor(TenantScope scope, Guid runId) => - fixture.CreateEventStore(runId: runId, currentTenant: new StubTenant(scope)); - - [Test] - public async Task GetAsync_GivenAnotherTenantsAggregate_DoesNotReturnIt(CancellationToken cancellationToken) - { - // Arrange - one physical table, two tenants, the same aggregate id. - var runId = Guid.NewGuid(); - var aggregateId = $"{Guid.NewGuid()}"; - - var acme = StoreFor(TenantScope.For("acme"), runId); - var globex = StoreFor(TenantScope.For("globex"), runId); - - var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); - aggregate.IncrementInt32Value(); - - var saved = await acme.SaveAsync(aggregate, cancellationToken: cancellationToken); - await Assert.That(saved.IsSuccess).IsTrue(); - - // Act - var fromOwner = await acme.GetAsync(aggregateId, cancellationToken: cancellationToken); - var fromOther = await globex.GetAsync(aggregateId, cancellationToken: cancellationToken); - - // Assert - await Assert.That(fromOwner.IsSuccess).IsTrue(); - await Assert.That(fromOther.IsFailure).IsTrue(); - } - - // The distributed cache is read before the tenant-filtered storage lookup, so an unqualified cache - // key would let a second tenant read the first tenant's aggregate straight out of a shared cache, - // bypassing every storage filter. Reading twice as the owner guarantees the entry is cached. - [Test] - public async Task GetAsync_GivenACachedAggregate_DoesNotServeItToAnotherTenant(CancellationToken cancellationToken) - { - var runId = Guid.NewGuid(); - var aggregateId = $"{Guid.NewGuid()}"; - - var acme = StoreFor(TenantScope.For("acme"), runId); - var globex = StoreFor(TenantScope.For("globex"), runId); - - var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); - aggregate.IncrementInt32Value(); - await acme.SaveAsync(aggregate, cancellationToken: cancellationToken); - - // Prime the cache as the owning tenant. - await acme.GetAsync(aggregateId, cancellationToken: cancellationToken); - await Assert.That((await acme.GetAsync(aggregateId, cancellationToken: cancellationToken)).IsSuccess).IsTrue(); - - await Assert - .That((await globex.GetAsync(aggregateId, cancellationToken: cancellationToken)).IsFailure) - .IsTrue(); - } - - [Test] - public async Task GetAsync_GivenSystemScope_ReadsAcrossTenants(CancellationToken cancellationToken) - { - // Arrange - var runId = Guid.NewGuid(); - var aggregateId = $"{Guid.NewGuid()}"; - - var acme = StoreFor(TenantScope.For("acme"), runId); - var system = StoreFor(TenantScope.System, runId); - - var aggregate = TestHelpers.Aggregate(aggregateId: aggregateId); - aggregate.IncrementInt32Value(); - - await acme.SaveAsync(aggregate, cancellationToken: cancellationToken); - - // Act - infrastructure work deliberately crosses tenants. - var result = await system.GetAsync(aggregateId, cancellationToken: cancellationToken); - - // Assert - await Assert.That(result.IsSuccess).IsTrue(); - } -} From 5a15bf2003bd97cdf1fe8b2d30c5c038e7b20673 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Sun, 25 Oct 2026 14:01:33 +0000 Subject: [PATCH 10/41] docs: design subscriptions and retention before building them The GA 4 plan existed only as the label "subscriptions/retention", so this writes the design down before any code. Marked clearly as a proposal: nothing on the page is implemented. The substance is that there is no global event order to subscribe to. Streams are per-aggregate on every provider, and Azure Table Storage cannot have a cross-partition sequence at all, so "subscribe to the event stream" is a choice about what ordering a subscriber is promised rather than one design. Three options are compared with their real costs; per-aggregate catch-up is recommended as the only one implementable everywhere and honest about its promise. Retention is the inverse of the framework's first invariant - the snapshot becomes load-bearing - so the page states that pruning without a covering snapshot must not be possible, and lists the interactions (crypto-shredding, upcasting, lagging subscriptions, tenancy) that constrain it. Ends with the decisions needed before implementation starts. --- docs/wiki/Home.md | 6 + .../Subscriptions-And-Retention-Design.md | 243 ++++++++++++++++++ docs/wiki/_Sidebar.md | 1 + 3 files changed, 250 insertions(+) create mode 100644 docs/wiki/Subscriptions-And-Retention-Design.md diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md index 63bc5c09..270c6c52 100644 --- a/docs/wiki/Home.md +++ b/docs/wiki/Home.md @@ -25,6 +25,12 @@ This wiki is the project documentation hub for framework features, provider capa - [Shared Testing Framework](Shared-Testing-Framework.md) - [Release Flow](Release-Flow.md) +## Proposals + +Designs under discussion. **Not implemented** — nothing described on these pages exists yet. + +- [Subscriptions and Retention](Subscriptions-And-Retention-Design.md) + ## Feature highlights - **Core framework (`Purview.EventSourcing`)** diff --git a/docs/wiki/Subscriptions-And-Retention-Design.md b/docs/wiki/Subscriptions-And-Retention-Design.md new file mode 100644 index 00000000..f7e340f0 --- /dev/null +++ b/docs/wiki/Subscriptions-And-Retention-Design.md @@ -0,0 +1,243 @@ +# Subscriptions and Retention — Design + +> **Status: proposal. Nothing on this page is implemented.** +> +> No type, option or method described here exists in the framework today. This page is a design to +> be agreed before any code is written; treat every signature as illustrative. When the work lands, +> this page is replaced by documentation of what was actually built, and +> [Provider Feature Matrix](Provider-Feature-Matrix.md) and +> [Guarantees and Limitations](Guarantees-and-Limitations.md) are updated with it. + +## What already exists, and what is missing + +Two mechanisms already carry events outwards: + +| Mechanism | What it is | What it does not do | +| --- | --- | --- | +| [Change feed](Transactional-Outbox.md) (`IAggregateChangeFeedProcessor`) | In-process callbacks around save and delete | Does not survive a restart, has no position, and cannot replay history | +| [Transactional outbox](Transactional-Outbox.md) (`IOutboxStore`) | Durable at-least-once hand-off, written in the save's transaction, leased and retried by `OutboxDispatchHostedService` | Only carries what a handler chose to enqueue **at write time**. A consumer added later sees nothing that happened before it existed | + +The gap is a consumer that can be **added after the fact** and read the history: a projection +rebuild, a new read model, a late integration. That is what a subscription is for. + +Retention is the other end of the same stream. Event streams currently grow without bound; nothing +removes an event, ever. For a long-lived aggregate that is a cost and a replay-time problem, and for +a regulated deployment it is a compliance problem that +[crypto-shredding](../../skills/event-sourcing-crypto-shredding/SKILL.md) only partly answers — +shredding makes a payload unreadable, it does not remove the row. + +## The central difficulty: there is no global order + +This framework's event streams are **per aggregate**. There is no ordered log across aggregates, and +no provider currently persists one: + +- **Azure Table Storage** — `PartitionKey` is the aggregate id, `RowKey` encodes the aggregate + version. Ordering exists only inside a partition. Azure Tables offers no cross-partition sequence. +- **SQL Server / PostgreSQL** — events are keyed by aggregate id and version. An identity or + sequence column could be added, but does not exist. +- **MongoDB** — the same shape; `ObjectId` is roughly time-ordered but is not a gap-free sequence + and is not safe to checkpoint against. +- **Cosmos DB** — no event stream at all (`no-event-stream` operational limitation). + +So "subscribe to the event stream" is not a single design; it is a choice about what order a +subscriber is promised. Three options, honestly compared: + +### Option A — per-aggregate catch-up, no global order + +A subscription is scoped to one aggregate type and delivers each aggregate's events in version +order. Aggregates are visited in an unspecified order, discovered by enumerating the snapshot store +or an aggregate index. + +- **Promise**: per-aggregate ordering only. Good enough for projections keyed by aggregate id, which + is most of them. +- **Cost**: no new storage. Works on every provider that has an event stream. +- **Weakness**: a consumer that needs "everything that happened, in order" cannot have it. Discovery + requires a way to enumerate aggregate ids, which Azure Tables does cheaply and others less so. + +### Option B — a global sequence column, provider-side + +Each provider gains a monotonic sequence on the event row, and a subscription is a cursor over it. + +- **Promise**: total order within an aggregate type, or across all of them. +- **Cost**: a schema change on every provider, and **Azure Table Storage cannot do it** — there is + no cross-partition atomic counter, and synthesising one serialises every write. Azure would have + to be excluded, which breaks the parity rule the repository holds to. +- **Weakness**: gap-free sequences and concurrent writers interact badly. A reader that checkpoints + at sequence *N* can miss a row committed later with a lower sequence, unless reads trail by a + safety window or the sequence is assigned at commit. This is the classic correctness trap. + +### Option C — subscriptions are outbox consumers + +Keep the outbox as the only ordered, durable log, and make a subscription a second consumer group +over it, with its own checkpoint and retention. + +- **Promise**: the outbox's existing ordering (creation time) and at-least-once delivery. +- **Cost**: smallest. Reuses leasing, retry, poison handling, and the transactional write. +- **Weakness**: **does not solve the actual gap.** The outbox only contains what was enqueued at + write time, so a subscriber added later still sees nothing historical — unless every event is + enqueued unconditionally, which makes the outbox a full copy of the event stream and doubles + storage. + +**Recommendation: Option A.** It is the only one that is both implementable on every provider with +an event stream and honest about what it promises. Option B can be added later for the relational +providers as a stronger, opt-in guarantee reported through `EventStoreCapabilities`, without +invalidating Option A's contract. + +## Part 1 — Subscriptions (Option A) + +### Contracts + +```csharp +// Where a subscription has got to. Per subscription, per aggregate, per tenant. +public interface ISubscriptionCheckpointStore +{ + Task GetAsync(string subscriptionName, string aggregateId, CancellationToken cancellationToken); + + Task SetAsync(string subscriptionName, string aggregateId, long version, CancellationToken cancellationToken); +} + +// What a consumer implements. +public interface IEventSubscriber + where T : class, IAggregate, new() +{ + string SubscriptionName { get; } + + Task OnEventAsync(EventSubscriptionContext context, CancellationToken cancellationToken); +} +``` + +`EventSubscriptionContext` carries the aggregate id, the `EventRecord`, its persisted type name, +the aggregate version and the `EventMetadata` — the same material `GetEventRangeAsync` already +returns, so nothing new has to be persisted. + +Driving it is a hosted service shaped like `OutboxDispatchHostedService`: claim a batch, deliver, +checkpoint, back off. Reusing that shape rather than inventing a second one is deliberate. + +### Delivery guarantee + +**At-least-once, with per-aggregate ordering.** The checkpoint is written *after* the handler +returns, so a crash between the two redelivers. Subscribers must be idempotent, and the +documentation must say so as plainly as the outbox's does. + +Exactly-once is not offered. It would require the checkpoint write to share the subscriber's +transaction, which the framework cannot see. + +### Tenancy + +Per the repository's rule that +[tenancy is tested first](Shared-Testing-Framework.md#tenant-isolation-is-part-of-the-contract): + +- Checkpoints are **tenant-scoped rows**. Two tenants running the same subscription name must not + share a position, or one tenant's progress silently skips the other's events. +- A subscription runs under a `TenantScope`. A tenant-scoped subscription sees only its tenant's + aggregates; a `TenantScope.System` subscription sees all of them and must checkpoint per tenant + regardless. +- An unowned aggregate (no tenant stamp) is invisible to a tenant-scoped subscription, matching the + fail-closed read behaviour. + +These are contract tests before they are code. + +### Interaction with unknown events and upcasting + +A subscriber may encounter an event type it cannot resolve — the same situation replay handles with +`SkippedEventRecord`. The subscription must not stall on it. Proposal: deliver it as an unresolved +event with its persisted type name, let the subscriber ignore it, and checkpoint past it. +Upcasters apply before delivery, so a subscriber sees current shapes. + +### Open questions + +1. How are aggregate ids enumerated for discovery? Azure Tables can scan partitions; the SQL + providers would use the snapshot store. Is a snapshot store a **prerequisite** for subscriptions? +2. Does a subscription deliver events for **deleted** aggregates, and does it see the `Deleted` + event? +3. One hosted service per subscription, or one driving all of them? + +## Part 2 — Retention + +### What it is + +Remove events from a stream once they are no longer needed to reconstruct the aggregate — which is +only safe **once a snapshot covers them**, because the snapshot then becomes the replay base. + +```csharp +public sealed record EventRetentionPolicy +{ + // Never prune events newer than this. + public TimeSpan MinimumAge { get; init; } = TimeSpan.FromDays(90); + + // Always leave this many events behind the snapshot, as a safety margin. + public int RetainedVersions { get; init; } = 100; + + // Refuse to prune at all unless a snapshot at or beyond the prune point exists. + public bool RequireSnapshot { get; init; } = true; +} +``` + +### The hard constraint + +**`RequireSnapshot` must not be defeasible.** Pruning an event with no snapshot behind it destroys +business state permanently, which violates the repository's first invariant: event streams are the +canonical source of truth and snapshots are replaceable optimisations. Retention is the one place +where that relationship inverts, and it must do so only when the snapshot provably exists and +provably covers the prune point. + +A provider without snapshot support therefore cannot offer retention, and must report that rather +than silently no-op. + +### Interactions + +| With | Consequence | +| --- | --- | +| **Snapshots** | The snapshot becomes load-bearing. Its schema version must still be readable, so [snapshot schema versioning](Snapshot-Schema-Versioning.md) becomes a correctness concern, not just a convenience | +| **Crypto-shredding** | Retention and shredding overlap but are not substitutes. Shredding removes the key for a data subject; retention removes the row for everyone. A shredded event that is later pruned is fine; a pruned event cannot be shredded, so the snapshot must not retain the plaintext | +| **Subscriptions** | A subscription whose checkpoint is behind the prune point can never catch up. Retention must either refuse to prune past the slowest checkpoint, or report the subscription as permanently gapped. Refusing is safer and should be the default | +| **Upcasting** | Pruned events are never upcast again, so a future upcaster cannot reach them. Any schema migration must run before the events ageing out | +| **Tenancy** | Pruning runs per tenant or as a system operation, and must never prune across a tenant boundary | +| **Admin** | Retention is an operator action with a blast radius. It belongs behind the existing `Admin.Security` policy, and should report what it would remove before removing it | + +### Open questions + +1. Is retention **scheduled** (a hosted service) or **invoked** (an admin action)? Scheduled is more + useful and considerably more dangerous. +2. Is a dry-run mode required before the first destructive release? (Strong recommendation: yes.) +3. Does pruning interact with the audit expectations some deployments have — is there a jurisdiction + where removing an event is itself a problem? + +## Provider impact + +| Provider | Subscriptions (Option A) | Retention | +| --- | --- | --- | +| Azure Storage | Yes — partition scan for discovery | Yes — snapshot-backed, blob snapshots | +| MongoDB | Yes | Yes | +| PostgreSQL | Yes | Yes | +| SQL Server | Yes | Yes | +| Cosmos DB | **No** — `no-event-stream` | **No** — nothing to prune | +| InMemory | Yes — needed for the acceptance scenarios | Yes | + +Both features need new flags on `EventStoreCapabilities` (`SupportsSubscriptions`, +`SupportsRetention`) so an application can discover the truth rather than infer it, in line with how +every other capability is reported. + +## What the work includes + +Beyond the implementation, per the repository's rules: + +- Shared contract tests in `EventStoreContractTestsBase`, **tenancy cases first**, with an abstract + seam per provider so no provider can be added without stating its behaviour. +- Acceptance scenarios in `EventSourcing.AcceptanceTests` stating the guarantees in domain language + — particularly "a subscription added today sees what happened yesterday" and "retention never + removes an event that is still needed". +- A `skills/event-sourcing-subscriptions` skill, and retention guidance added to + `skills/event-sourcing-crypto-shredding` where the two meet. +- Updates to [Provider Feature Matrix](Provider-Feature-Matrix.md), + [Provider Capabilities](Provider-Capabilities.md), + [Guarantees and Limitations](Guarantees-and-Limitations.md) and the provider guides. + +## Decisions needed before implementation + +1. **Option A, B or C** for ordering. (Recommendation: A.) +2. Whether a **snapshot store is a prerequisite** for subscriptions, which decides the discovery + mechanism. +3. Whether retention is **scheduled or operator-invoked**, and whether a dry run ships first. +4. Whether both halves ship together, or **subscriptions first** — they are independent, and + retention is the one that can destroy data. diff --git a/docs/wiki/_Sidebar.md b/docs/wiki/_Sidebar.md index 7766c8e3..d54cb4ea 100644 --- a/docs/wiki/_Sidebar.md +++ b/docs/wiki/_Sidebar.md @@ -19,3 +19,4 @@ - [Source Generator Code Fixes](Code-Fixes.md) - [SQL Server Guide](SQL-Server-Guide.md) - [Release Flow](Release-Flow.md) +- _Proposal:_ [Subscriptions and Retention](Subscriptions-And-Retention-Design.md) From 26e6fcc8e26bcb7feb14f0b08036d80afb4d3941 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Sun, 25 Oct 2026 14:34:27 +0000 Subject: [PATCH 11/41] docs: add an external ordered log as a fourth subscription option The previous draft claimed a global sequence would break provider parity because Azure Table Storage cannot hold one. That was too strong: a capability gated on configuration and reported through EventStoreCapabilities is how this repository already models capabilities that are not universal. Adds Option D - publish through the existing outbox to an ordered log, so a provider that cannot offer a sequence itself still gets ordered delivery. Distinguishes transports that qualify from those that do not: Kafka and Event Hubs have offsets and replay, Service Bus has FIFO sessions but no replay, so a subscriber added later sees nothing. That difference decides the design. Option D layers on Option A rather than replacing it, because a transport cannot be the source of history - it holds nothing published before it was enabled, and retaining from genesis makes it a second full copy of the stream. Catch-up reads the store; live tail reads the transport. Records the two costs this exposes: the outbox does not currently preserve order under retry, and no transport integration exists today. --- .../Subscriptions-And-Retention-Design.md | 111 ++++++++++++++---- 1 file changed, 90 insertions(+), 21 deletions(-) diff --git a/docs/wiki/Subscriptions-And-Retention-Design.md b/docs/wiki/Subscriptions-And-Retention-Design.md index f7e340f0..87c827b5 100644 --- a/docs/wiki/Subscriptions-And-Retention-Design.md +++ b/docs/wiki/Subscriptions-And-Retention-Design.md @@ -40,7 +40,7 @@ no provider currently persists one: - **Cosmos DB** — no event stream at all (`no-event-stream` operational limitation). So "subscribe to the event stream" is not a single design; it is a choice about what order a -subscriber is promised. Three options, honestly compared: +subscriber is promised. Four options, honestly compared: ### Option A — per-aggregate catch-up, no global order @@ -60,8 +60,8 @@ Each provider gains a monotonic sequence on the event row, and a subscription is - **Promise**: total order within an aggregate type, or across all of them. - **Cost**: a schema change on every provider, and **Azure Table Storage cannot do it** — there is - no cross-partition atomic counter, and synthesising one serialises every write. Azure would have - to be excluded, which breaks the parity rule the repository holds to. + no cross-partition atomic counter, and synthesising one serialises every write. Azure Storage + would be left without the capability (though see Option D, which closes that gap by other means). - **Weakness**: gap-free sequences and concurrent writers interact badly. A reader that checkpoints at sequence *N* can miss a row committed later with a lower sequence, unless reads trail by a safety window or the sequence is assigned at commit. This is the classic correctness trap. @@ -78,10 +78,63 @@ over it, with its own checkpoint and retention. enqueued unconditionally, which makes the outbox a full copy of the event stream and doubles storage. -**Recommendation: Option A.** It is the only one that is both implementable on every provider with -an event stream and honest about what it promises. Option B can be added later for the relational -providers as a stronger, opt-in guarantee reported through `EventStoreCapabilities`, without -invalidating Option A's contract. +### Option D — an external ordered log, when one is configured + +Ordering does not have to come from the storage provider. Where the deployment already runs an +ordered log, events are published to it through the existing outbox and subscribers consume from +there — so a provider that cannot offer a sequence itself, Azure Table Storage included, still gets +ordered delivery. The capability is reported through `EventStoreCapabilities` and is present only +when a transport is configured, which is the established way this repository models a capability +that is not universal. + +**Not every broker qualifies.** The requirement is a *log*, not a queue: + +| Transport | Ordering | Replay from the start | Verdict | +| --- | --- | --- | --- | +| Kafka | Per-partition, total with one partition | Yes — offsets, retention configurable to infinite | Qualifies | +| Azure Event Hubs | Per-partition sequence numbers | Yes, within retention (1–90 days; longer via Capture) | Qualifies, with a retention ceiling | +| Azure Service Bus | FIFO per session | **No** — a message is consumed and gone | Does **not** qualify | +| RabbitMQ (classic queues) | Per-queue | **No** | Does **not** qualify | + +Service Bus is the one to be careful about: sessions make it look like an ordering solution, but +there are no offsets and no replay, so a subscriber added tomorrow sees nothing from today. It +solves ordered *live delivery* and not catch-up, which is the gap this feature exists to close. + +- **Promise**: ordered, low-latency live delivery, at-least-once, with the transport's own + checkpointing. Total order across aggregates only on a single partition. +- **Cost**: no storage schema change. Reuses the transactional outbox for atomicity, so no dual + write is introduced — the path is save → outbox (in the save's transaction) → dispatcher → + transport. +- **Weaknesses**, all real: + 1. **The outbox does not currently preserve order.** `ClaimNextBatchAsync` claims by creation time + across *all* messages, with leases and retries, so a failed message is redelivered after later + ones. Ordered publication requires leasing per ordering key (the aggregate id) and stalling + that key on failure — a genuine change to the outbox, and head-of-line blocking is the hard + part of it. + 2. **Replay from genesis means a second full copy.** If the transport is the history, it must + retain everything ever written. Log compaction does not rescue this: keyed on aggregate id it + keeps only the latest event per aggregate, which destroys event sourcing. Event Hubs caps at 90 + days without Capture. + 3. **Nothing published before the transport was enabled is in it.** Historical catch-up still has + to come from the store. + 4. Total ordering costs a single partition, and therefore a throughput ceiling. + +### Recommendation — Option A, with Option D layered on + +Option D does not replace Option A; weaknesses 2 and 3 mean a transport cannot be the source of +history. The two compose: + +- **Catch-up** reads history from the event store, per aggregate, in version order (Option A). Works + on every provider with an event stream, needs no transport. +- **Live tail** switches to the transport once a subscription reaches the head (Option D), when one + is configured — giving ordered, low-latency delivery to providers that could never offer a + sequence themselves. + +A deployment with no transport still gets catch-up plus unordered at-least-once live delivery. +Parity is preserved, and the stronger guarantee is advertised only where it genuinely holds. + +Option B remains available later as a store-native strengthening for the relational providers, +without invalidating Option A's contract. ## Part 1 — Subscriptions (Option A) @@ -205,18 +258,27 @@ than silently no-op. ## Provider impact -| Provider | Subscriptions (Option A) | Retention | -| --- | --- | --- | -| Azure Storage | Yes — partition scan for discovery | Yes — snapshot-backed, blob snapshots | -| MongoDB | Yes | Yes | -| PostgreSQL | Yes | Yes | -| SQL Server | Yes | Yes | -| Cosmos DB | **No** — `no-event-stream` | **No** — nothing to prune | -| InMemory | Yes — needed for the acceptance scenarios | Yes | +| Provider | Catch-up (Option A) | Ordered live tail (Option D) | Retention | +| --- | --- | --- | --- | +| Azure Storage | Yes — partition scan for discovery | With a transport | Yes — snapshot-backed, blob snapshots | +| MongoDB | Yes | With a transport | Yes | +| PostgreSQL | Yes | With a transport | Yes | +| SQL Server | Yes | With a transport | Yes | +| Cosmos DB | **No** — `no-event-stream` | **No** — nothing to publish | **No** — nothing to prune | +| InMemory | Yes — needed for the acceptance scenarios | No | Yes | + +Ordered live tail is a property of the configured transport, not of the provider, which is why it is +uniform across every provider that has a stream. Both features need new flags on `EventStoreCapabilities` (`SupportsSubscriptions`, -`SupportsRetention`) so an application can discover the truth rather than infer it, in line with how -every other capability is reported. +`SupportsOrderedDelivery`, `SupportsRetention`) so an application can discover the truth rather than +infer it, in line with how every other capability is reported. + +**No transport integration exists today.** `IOutboxHandler` is the seam a consumer implements to +publish, and the repository ships no Kafka, Event Hubs or Service Bus package. Option D therefore +also decides whether the framework starts shipping transport adapters, or documents the handler +contract an ordered transport must satisfy and leaves the adapter to the consumer. The second is +much smaller and avoids a new dependency surface. ## What the work includes @@ -235,9 +297,16 @@ Beyond the implementation, per the repository's rules: ## Decisions needed before implementation -1. **Option A, B or C** for ordering. (Recommendation: A.) -2. Whether a **snapshot store is a prerequisite** for subscriptions, which decides the discovery +1. **Ordering model.** (Recommendation: A for catch-up, with D layered on for ordered live tail + where a transport is configured.) +2. If Option D is adopted: does the framework **ship transport adapters**, or publish the + `IOutboxHandler` contract an ordered transport must satisfy and leave the adapter to the + consumer? (Recommendation: the latter — no new dependency surface.) +3. If Option D is adopted: is **ordered outbox dispatch** in scope? Per-key leasing with head-of-line + blocking is the substantial part of the work, and without it publication order is not commit + order. +4. Whether a **snapshot store is a prerequisite** for subscriptions, which decides the discovery mechanism. -3. Whether retention is **scheduled or operator-invoked**, and whether a dry run ships first. -4. Whether both halves ship together, or **subscriptions first** — they are independent, and +5. Whether retention is **scheduled or operator-invoked**, and whether a dry run ships first. +6. Whether both halves ship together, or **subscriptions first** — they are independent, and retention is the one that can destroy data. From 29c0bfd9665c81476e56f84abb87b9faf28dbfd3 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Sun, 25 Oct 2026 15:03:26 +0000 Subject: [PATCH 12/41] feat: catch-up subscriptions over the event stream Adds IEventSubscriber and a catch-up processor that reads each visible aggregate stream from a recorded position. Unlike the change feed and the outbox, which only carry what happened while they were running, a subscription reads the stream itself - so a projection added today can be built from history. Delivery is at-least-once and ordered within an aggregate. There is no ordering between aggregates, because no provider holds a global sequence; docs/wiki/Subscriptions-And-Retention-Design.md records why. Tenancy is structural rather than remembered: the TenantScope is part of SubscriptionCheckpointKey, so a position cannot be written without stating its tenant. Two tenants sharing one would let whichever ran first advance it past the other's unread events, which would then never be delivered. The tenancy tests assert on what discovery returns, not on what the subscriber receives. Removing the discovery filter fails two of them while every acceptance scenario stays green - the event read is filtered too, and that second filter masks the first. A subscriber that throws stops its stream at the failing event and retries from there, so a poison event stalls one stream indefinitely rather than being skipped. Documented, because skipping loses data silently. Retention and the ordered live tail remain unimplemented. --- docs/wiki/Guarantees-and-Limitations.md | 29 ++++ docs/wiki/Home.md | 8 +- docs/wiki/Provider-Feature-Matrix.md | 3 + .../Subscriptions-And-Retention-Design.md | 14 +- docs/wiki/Subscriptions.md | 144 +++++++++++++++++ docs/wiki/_Sidebar.md | 1 + skills/event-sourcing-subscriptions/SKILL.md | 116 ++++++++++++++ .../ServiceCollectionExtensions.cs | 60 +++++++ .../Subscriptions/EventSubscriptionContext.cs | 41 +++++ .../EventSubscriptionProcessor.cs | 117 ++++++++++++++ .../IAggregateStreamDiscovery.cs | 30 ++++ .../Subscriptions/IEventSubscriber.cs | 40 +++++ .../IEventSubscriptionProcessor.cs | 18 +++ .../ISubscriptionCheckpointStore.cs | 28 ++++ .../InMemorySubscriptionCheckpointStore.cs | 29 ++++ .../QueryableAggregateStreamDiscovery.cs | 28 ++++ .../SubscriptionCheckpointKey.cs | 18 +++ .../Subscriptions/SubscriptionCycleResult.cs | 12 ++ .../SubscriptionHostedService.cs | 54 +++++++ .../Subscriptions/SubscriptionOptions.cs | 35 +++++ .../InMemory/Events/IInMemoryEventStore.cs | 10 ++ .../InMemoryAggregateStreamDiscovery.cs | 23 +++ src/src/InMemory/Events/InMemoryEventStore.cs | 8 +- .../ServiceCollectionExtensions.cs | 9 ++ .../RecordingSubscriber.cs | 38 +++++ .../Steps/SubscriptionAssertions.cs | 41 +++++ .../Steps/SubscriptionSteps.cs | 68 ++++++++ .../SubscriptionScenarioContext.cs | 91 +++++++++++ .../SubscriptionScenarios.cs | 95 +++++++++++ .../Subscriptions/SubscriptionOptionsTests.cs | 51 ++++++ .../Subscriptions/SubscriptionTenancyTests.cs | 147 ++++++++++++++++++ .../SubscriptionTestAggregate.cs | 30 ++++ 32 files changed, 1427 insertions(+), 9 deletions(-) create mode 100644 docs/wiki/Subscriptions.md create mode 100644 skills/event-sourcing-subscriptions/SKILL.md create mode 100644 src/src/EventSourcing/Subscriptions/EventSubscriptionContext.cs create mode 100644 src/src/EventSourcing/Subscriptions/EventSubscriptionProcessor.cs create mode 100644 src/src/EventSourcing/Subscriptions/IAggregateStreamDiscovery.cs create mode 100644 src/src/EventSourcing/Subscriptions/IEventSubscriber.cs create mode 100644 src/src/EventSourcing/Subscriptions/IEventSubscriptionProcessor.cs create mode 100644 src/src/EventSourcing/Subscriptions/ISubscriptionCheckpointStore.cs create mode 100644 src/src/EventSourcing/Subscriptions/InMemorySubscriptionCheckpointStore.cs create mode 100644 src/src/EventSourcing/Subscriptions/QueryableAggregateStreamDiscovery.cs create mode 100644 src/src/EventSourcing/Subscriptions/SubscriptionCheckpointKey.cs create mode 100644 src/src/EventSourcing/Subscriptions/SubscriptionCycleResult.cs create mode 100644 src/src/EventSourcing/Subscriptions/SubscriptionHostedService.cs create mode 100644 src/src/EventSourcing/Subscriptions/SubscriptionOptions.cs create mode 100644 src/src/InMemory/Events/InMemoryAggregateStreamDiscovery.cs create mode 100644 src/tests/EventSourcing.AcceptanceTests/RecordingSubscriber.cs create mode 100644 src/tests/EventSourcing.AcceptanceTests/Steps/SubscriptionAssertions.cs create mode 100644 src/tests/EventSourcing.AcceptanceTests/Steps/SubscriptionSteps.cs create mode 100644 src/tests/EventSourcing.AcceptanceTests/SubscriptionScenarioContext.cs create mode 100644 src/tests/EventSourcing.AcceptanceTests/SubscriptionScenarios.cs create mode 100644 src/tests/EventSourcing.UnitTests/Subscriptions/SubscriptionOptionsTests.cs create mode 100644 src/tests/EventSourcing.UnitTests/Subscriptions/SubscriptionTenancyTests.cs create mode 100644 src/tests/EventSourcing.UnitTests/Subscriptions/SubscriptionTestAggregate.cs diff --git a/docs/wiki/Guarantees-and-Limitations.md b/docs/wiki/Guarantees-and-Limitations.md index 985c0d5b..0c5c041e 100644 --- a/docs/wiki/Guarantees-and-Limitations.md +++ b/docs/wiki/Guarantees-and-Limitations.md @@ -152,6 +152,35 @@ enabling tenancy, or read that data under `TenantScope.System`. - The filter is applied to the whole admin route group before any endpoint is mapped, so an endpoint added later cannot escape tenant scoping by omitting it. +## Subscriptions + +A [subscription](Subscriptions.md) reads the event stream itself, so it delivers events written before +the subscriber existed - the thing neither the change feed nor the outbox can do. + +Guaranteed: **at-least-once** delivery (the position is written after the subscriber returns, so a crash +redelivers rather than skips), **version order within one aggregate**, and **tenant isolation** across +discovery, the event read and the recorded position. + +Not guaranteed, and not configurable: + +- **No ordering between aggregates.** Streams are per-aggregate on every provider and there is no global + sequence. A projection that depends on the relative order of two different aggregates' events cannot be + built on a subscription. +- **No dead-letter path.** A subscriber that throws stops that stream at the failing event and retries it + every cycle, indefinitely. This is fail-closed by choice: skipping would lose data silently. An + unresolvable event type is not a failure - it is delivered with `IsUnresolved` set and skipped past. +- **No durable checkpoint store ships.** The default is in-memory and replays every stream after a + restart. +- **Cosmos DB cannot be subscribed to** (no event stream), and **Azure Storage ships no stream discovery** + (no queryable snapshot store), so subscriptions need a supplied `IAggregateStreamDiscovery` there. +- Discovery over a queryable snapshot store finds only **snapshotted** aggregates. + +Subscriptions are deliberately absent from `EventStoreCapabilities`: whether one can run depends on the +registered discovery implementation, which is dependency-injection state rather than a property of the +store, so a capability flag could not report it truthfully. + +Event-stream **retention** is not implemented. Streams grow without bound; nothing removes an event. + ## Metrics Every storage provider records the same instruments on the `Purview.EventSourcing` meter, so a dashboard diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md index 270c6c52..7e485174 100644 --- a/docs/wiki/Home.md +++ b/docs/wiki/Home.md @@ -11,6 +11,7 @@ This wiki is the project documentation hub for framework features, provider capa - [Provider Feature Matrix](Provider-Feature-Matrix.md) - [Provider Capabilities](Provider-Capabilities.md) - [Transactional Outbox](Transactional-Outbox.md) +- [Subscriptions](Subscriptions.md) - [Transaction Guarantees](Transaction-Guarantees.md) - [Result and Failure Model](Result-And-Failure-Model.md) - [Event Contract Manifest](Event-Contract-Manifest.md) @@ -27,14 +28,17 @@ This wiki is the project documentation hub for framework features, provider capa ## Proposals -Designs under discussion. **Not implemented** — nothing described on these pages exists yet. +Designs under discussion. Check each page's status banner before relying on it. -- [Subscriptions and Retention](Subscriptions-And-Retention-Design.md) +- [Subscriptions and Retention](Subscriptions-And-Retention-Design.md) — subscriptions shipped; the + retention half and the ordered live tail remain proposals ## Feature highlights - **Core framework (`Purview.EventSourcing`)** - `AggregateBase`, `IEventStore`, `IQueryableEventStore`, and `IEventStoreTransactionFactory`. + - [Subscriptions](Subscriptions.md): catch-up reads over the event stream, including events written + before the subscriber existed. - [Transaction guarantees](Transaction-Guarantees.md): atomic requirements, best-effort fallback, and failure behavior. - [Snapshot schema versioning](Snapshot-Schema-Versioning.md): compatibility detection and event-replay rebuilds. diff --git a/docs/wiki/Provider-Feature-Matrix.md b/docs/wiki/Provider-Feature-Matrix.md index 5be4e332..eedd2bbd 100644 --- a/docs/wiki/Provider-Feature-Matrix.md +++ b/docs/wiki/Provider-Feature-Matrix.md @@ -16,6 +16,9 @@ per-registration values. | Blob-backed snapshots / large payloads | No | No | No | Yes | No | No | | Provider-neutral transaction guarantee | Explicit `BestEffort` or required `Atomic` | Atomic within one database boundary | Atomic within one database boundary | Best effort | Best effort | Best effort | | Transactional outbox (atomic with events) | No | Yes (`AddSqlServerOutbox`) | Yes (`AddPostgresOutbox`) | No | No | No | +| [Subscriptions](Subscriptions.md) (catch-up over the event stream) | Contracts + `AddEventSubscription` | Yes, via snapshot-store discovery | Yes, via snapshot-store discovery | Needs a supplied `IAggregateStreamDiscovery` | Yes, via snapshot-store discovery | No (no event stream) | +| Durable subscription checkpoints | In-memory only (replays after restart) | Not provided | Not provided | Not provided | Not provided | n/a | +| Event-stream retention / pruning | No | No | No | No | No | n/a | | Provider-specific native transaction factory | No | `ISqlServerEventStoreTransactionFactory` | `IPostgresEventStoreTransactionFactory` | No | No | No | | Runtime-configured JSON payload indexes | No | Yes (event + snapshot stores, auto-create path) | Yes (GIN + expression indexes on event + snapshot stores) | No | No | Yes (container indexing policy, including composite and spatial paths) | | Snapshot query paging | n/a | Offset (integer continuation) | Offset (integer continuation) | n/a | Offset (integer continuation) | Native Cosmos DB continuation tokens | diff --git a/docs/wiki/Subscriptions-And-Retention-Design.md b/docs/wiki/Subscriptions-And-Retention-Design.md index 87c827b5..b4231d83 100644 --- a/docs/wiki/Subscriptions-And-Retention-Design.md +++ b/docs/wiki/Subscriptions-And-Retention-Design.md @@ -1,12 +1,14 @@ # Subscriptions and Retention — Design -> **Status: proposal. Nothing on this page is implemented.** +> **Status: subscriptions are implemented; retention is not.** > -> No type, option or method described here exists in the framework today. This page is a design to -> be agreed before any code is written; treat every signature as illustrative. When the work lands, -> this page is replaced by documentation of what was actually built, and -> [Provider Feature Matrix](Provider-Feature-Matrix.md) and -> [Guarantees and Limitations](Guarantees-and-Limitations.md) are updated with it. +> Part 1 shipped as catch-up subscriptions (Option A) — see [Subscriptions](Subscriptions.md) for +> what actually exists, which is the authoritative reference. The shipped contracts differ in detail +> from the sketches below; this page is kept for the *reasoning*, particularly the ordering analysis +> and the options that were rejected. +> +> **Part 2, retention, remains a proposal.** No type, option or method in that section exists. The +> ordered live tail described in Option D is not implemented either. ## What already exists, and what is missing diff --git a/docs/wiki/Subscriptions.md b/docs/wiki/Subscriptions.md new file mode 100644 index 00000000..745b6bde --- /dev/null +++ b/docs/wiki/Subscriptions.md @@ -0,0 +1,144 @@ +# Subscriptions + +A subscription reads an aggregate's event stream from a recorded position and delivers each event to +a subscriber, including events written **before the subscriber existed**. + +That is the difference from the two mechanisms that already carry events outwards: + +| Mechanism | Carries | A consumer added today sees | +| --- | --- | --- | +| Change feed (`IAggregateChangeFeedProcessor`) | In-process callbacks around save and delete | Nothing historical; nothing after a restart | +| [Transactional outbox](Transactional-Outbox.md) | What a handler enqueued at write time | Nothing written before it was wired up | +| **Subscription** | The event stream itself | Everything, from the beginning | + +So a projection rebuild, a new read model, or a late integration uses a subscription. Live +fan-out to another system uses the outbox. + +## Registering one + +```csharp +services.AddInMemoryEventStore(); // or any provider with an event stream +services.AddEventSubscription(); +``` + +```csharp +public sealed class OrderProjection(IReadModel readModel) : IEventSubscriber +{ + public string SubscriptionName => "order-projection"; + + public async Task OnEventAsync(EventSubscriptionContext context, CancellationToken cancellationToken) + { + if (context.IsUnresolved) + return; + + switch (context.Event) + { + case OrderPlaced placed: + await readModel.AddAsync(context.AggregateId, placed.Total, cancellationToken); + break; + } + } +} +``` + +`SubscriptionName` is the identity positions are recorded against. **Renaming a live subscription +abandons its progress** and replays every stream from the beginning. + +## What is guaranteed + +- **At-least-once delivery.** The position is written *after* the subscriber returns, so a crash + between the two redelivers. Subscribers must be idempotent. +- **Version order within one aggregate.** Events for a given aggregate arrive in the order they were + recorded. +- **No ordering between aggregates.** Streams are visited in an unspecified order. There is no + global sequence to subscribe to — see + [the design discussion](Subscriptions-And-Retention-Design.md#the-central-difficulty-there-is-no-global-order) + for why, and what an external ordered log would add. +- **Tenant isolation.** Discovery, the event read and the position are all scoped to the current + tenant. Two tenants running the same subscription name hold separate positions. + +## Failure behaviour + +If `OnEventAsync` throws, that aggregate's stream **stops at the failing event** and is retried from +there on the next cycle. Events already delivered stay delivered, other aggregates are unaffected, +and `SubscriptionCycleResult.StreamsFaulted` counts it. + +This is deliberately fail-closed: skipping the event would lose data silently. The consequence is +that a permanently failing event **stalls that one stream indefinitely**, logging an error every +cycle. There is currently no dead-letter or skip mechanism — handle poison events inside the +subscriber, by catching and recording them yourself. + +An event whose type can no longer be resolved is *not* a failure: it is delivered with +`IsUnresolved` set to `true`, and the subscription advances past it. An application that has deleted +an event contract must not have every later event in the stream blocked by it. + +## Stream discovery + +Event streams are keyed by aggregate id, and no provider holds an index of "every stream that +exists". Discovery is therefore a seam, `IAggregateStreamDiscovery`: + +| Provider | Discovery | +| --- | --- | +| InMemory | `InMemoryAggregateStreamDiscovery`, registered automatically. Exact — it enumerates the streams the store holds | +| SQL Server, PostgreSQL, MongoDB, Cosmos DB | `QueryableAggregateStreamDiscovery`, the default. **Requires a queryable snapshot store**, and finds only aggregates that have been snapshotted | +| Azure Storage | **No implementation.** It has no queryable snapshot store, so supply your own `IAggregateStreamDiscovery` | + +Register your own before calling `AddEventSubscription` and it will be used instead of the default. + +> An implementation must honour the current tenant. The event read is filtered too, so a leaky +> discovery will not deliver another tenant's *events* — but aggregate ids are themselves data, and +> that second filter masks the first in any test that only asserts on deliveries. This is why +> `SubscriptionTenancyTests` asserts on what discovery returns rather than on what arrives. + +## Checkpoints + +`ISubscriptionCheckpointStore` records the last delivered version per subscription, per tenant, per +aggregate. The tenant is part of `SubscriptionCheckpointKey` rather than something a store is +trusted to apply, so a position cannot be written without stating which tenant it belongs to. + +The default registration is `InMemorySubscriptionCheckpointStore`, which **loses every position on +restart** and therefore replays all streams. That is fine for tests and local development. A +deployed application should register a durable store: + +```csharp +services.AddSingleton(); +services.AddEventSubscription(); +``` + +No provider ships a durable checkpoint store yet. + +## Configuration + +| Option | Default | Notes | +| --- | --- | --- | +| `PollInterval` | 5 seconds | The delay between catch-up cycles | +| `CheckpointInterval` | 100 events | Write volume against redelivery after a crash. The position is also written whenever a stream is exhausted | + +Bind from `EventStore:Subscriptions`, or configure inline: + +```csharp +services.AddEventSubscription(options => options.PollInterval = TimeSpan.FromSeconds(1)); +``` + +## Limitations + +- **No global ordering**, and no ordered live tail. Both are discussed in + [the design page](Subscriptions-And-Retention-Design.md). +- **No durable checkpoint store ships with any provider.** +- **Azure Storage has no discovery implementation**, so subscriptions do not work there without one. +- **Cosmos DB cannot be subscribed to at all** — it persists no event stream, and `RunCycleAsync` + throws `NotSupportedException`. +- **A permanently failing event stalls its stream.** There is no dead-letter path. +- Discovery over a queryable snapshot store only finds **snapshotted** aggregates. +- The in-memory event store keeps its data per instance and is registered transient, so a + subscription over it must resolve the same instance — register it as a singleton. +- Subscriptions are not reported through `EventStoreCapabilities`. Whether one can run depends on + the registered discovery implementation, which is dependency-injection state rather than a + property of the store. + +## Related + +- [Transactional Outbox](Transactional-Outbox.md) — live fan-out, atomic with the save +- [Subscriptions and Retention — Design](Subscriptions-And-Retention-Design.md) — why it works this + way, and what retention would add +- [Guarantees and Limitations](Guarantees-and-Limitations.md) diff --git a/docs/wiki/_Sidebar.md b/docs/wiki/_Sidebar.md index d54cb4ea..513f3674 100644 --- a/docs/wiki/_Sidebar.md +++ b/docs/wiki/_Sidebar.md @@ -6,6 +6,7 @@ - [Provider Feature Matrix](Provider-Feature-Matrix.md) - [Provider Capabilities](Provider-Capabilities.md) - [Transactional Outbox](Transactional-Outbox.md) +- [Subscriptions](Subscriptions.md) - [Transaction Guarantees](Transaction-Guarantees.md) - [Event Contract Manifest](Event-Contract-Manifest.md) - [Source Generator Performance](Source-Generator-Performance.md) diff --git a/skills/event-sourcing-subscriptions/SKILL.md b/skills/event-sourcing-subscriptions/SKILL.md new file mode 100644 index 00000000..2f4a42c5 --- /dev/null +++ b/skills/event-sourcing-subscriptions/SKILL.md @@ -0,0 +1,116 @@ +--- +name: event-sourcing-subscriptions +description: Build projections, read models and integrations that read a Purview.EventSourcing event stream from a recorded position, including events written before the consumer existed. Use when adding a subscriber, a projection rebuild, stream discovery, or a checkpoint store, or when choosing between a subscription, the change feed and the transactional outbox. +license: MIT +metadata: + package: Purview.EventSourcing + category: event-sourcing +--- + +# Subscriptions + +A subscription reads the event stream itself, so it delivers events written before the subscriber +existed. That is the one thing the change feed and the outbox cannot do. + +## Pick the right mechanism first + +| You want | Use | +| -- | -- | +| A projection or read model that can be rebuilt from history | **Subscription** | +| A consumer added after the system was already running | **Subscription** | +| To publish to another system as part of the write | **Outbox** - atomic with the save | +| To react in-process during save or delete | **Change feed** | + +Reaching for the outbox to build a projection is the common mistake. It only contains what a handler +enqueued at write time, so the projection can never be rebuilt and a replay is impossible. + +## Write the subscriber idempotently + +Delivery is at-least-once: the position is written *after* `OnEventAsync` returns, so a crash +between the two redelivers. This is not a rare edge case - it happens on every ungraceful shutdown. + +```csharp +public sealed class OrderProjection(IReadModel readModel) : IEventSubscriber +{ + public string SubscriptionName => "order-projection"; + + public async Task OnEventAsync(EventSubscriptionContext context, CancellationToken cancellationToken) + { + if (context.IsUnresolved) + return; + + // Upsert keyed by (aggregate id, version), not an append - redelivery must be harmless. + if (context.Event is OrderPlaced placed) + await readModel.UpsertAsync(context.AggregateId, context.AggregateVersion, placed.Total, cancellationToken); + } +} +``` + +**Do not rename a live `SubscriptionName`.** Positions are recorded against it, so a rename +abandons all progress and replays every stream from the beginning. If that is what you want, say so +deliberately. + +## Ordering: what you actually get + +- **Ordered within one aggregate.** Guaranteed. +- **Unordered between aggregates.** There is no global sequence. Streams are per-aggregate on every + provider, and Azure Table Storage cannot hold a cross-partition sequence at all. + +So a projection keyed by aggregate id is safe. A projection that depends on the relative order of +two *different* aggregates' events is not, and no option will make it so. Model it as a single +aggregate instead, or accept eventual convergence. + +## Stream discovery is a seam, and it must be tenant-filtered + +No provider holds an index of every stream, so discovery is supplied per provider: + +- **InMemory** - automatic and exact. +- **SQL Server, PostgreSQL, MongoDB, Cosmos DB** - the queryable default, which needs a snapshot + store and finds only **snapshotted** aggregates. An aggregate saved under a snapshot strategy that + has not written one yet is invisible to the subscription. +- **Azure Storage** - none ships. Supply your own or subscriptions will not run. + +Register yours before `AddEventSubscription` and it wins over the default. + +**A discovery implementation that ignores the current tenant leaks.** The trap is that it will not +look like a leak: the event read is filtered too, so no cross-tenant *events* are delivered, and any +test that only asserts "the other tenant's subscriber received nothing" passes. Aggregate ids are +data. Assert on what discovery returns, not on what arrives - see `SubscriptionTenancyTests`, where +removing the discovery filter fails two tests and the acceptance scenarios stay green. + +## Checkpoints are per tenant, structurally + +The tenant is part of `SubscriptionCheckpointKey`, not something the store applies. A position +cannot be written without stating the tenant it belongs to. + +If two tenants shared a position, whichever ran first would advance it past the other's unread +events and those events would **never** be delivered - a silent, permanent gap rather than a +visible error. + +The default checkpoint store is in-memory and loses every position on restart, replaying all +streams. Register a durable one in anything deployed. No provider ships one yet. + +## Failure stalls the stream, on purpose + +If `OnEventAsync` throws, that stream stops at the failing event and retries from there next cycle. +Other aggregates continue, and `SubscriptionCycleResult.StreamsFaulted` counts it. + +The consequence worth planning for: **a permanently failing event stalls that stream forever**, with +an error logged every cycle. There is no dead-letter path. Catch and record poison events inside the +subscriber if you need to move past them - the framework will not skip for you, because skipping +loses data silently. + +An unresolvable event type is not a failure. It arrives with `IsUnresolved` set and the subscription +advances past it, so deleting an event contract does not block the rest of the stream. + +## Gotchas + +- **Cosmos DB cannot be subscribed to.** It persists no event stream; `RunCycleAsync` throws + `NotSupportedException`. +- **The in-memory store is transient and keeps data per instance.** A subscription over it reads a + different, empty store unless you register it as a singleton. +- Subscriptions are **not** reported through `EventStoreCapabilities` - whether one can run depends + on the registered discovery, which is DI state rather than a store property. + +See `docs/wiki/Subscriptions.md` for the full reference and +`docs/wiki/Subscriptions-And-Retention-Design.md` for why the ordering model is what it is. diff --git a/src/src/EventSourcing/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/EventSourcing/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs index 33bff4ad..9aa8d852 100644 --- a/src/src/EventSourcing/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs +++ b/src/src/EventSourcing/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -1,6 +1,7 @@ using System.ComponentModel; using System.Diagnostics; using Microsoft.Extensions.DependencyInjection.Extensions; +using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; using Purview.EventSourcing.Aggregates.Events.Upcasting; using Purview.EventSourcing.ChangeFeed; @@ -8,6 +9,7 @@ using Purview.EventSourcing.Manifest; using Purview.EventSourcing.Outbox; using Purview.EventSourcing.Services; +using Purview.EventSourcing.Subscriptions; namespace Microsoft.Extensions.DependencyInjection; @@ -85,6 +87,64 @@ public IServiceCollection AddOutbox( return services; } + /// + /// Registers a subscriber, its catch-up processor, and a hosted loop that drives it. + /// + /// The aggregate type to subscribe to. + /// The implementation. + /// Optional configuration. + /// The for chaining. + /// + /// + /// Unlike the change feed and the outbox, a subscription reads the event stream itself, so it + /// delivers events written before the subscriber existed. Delivery is at-least-once and ordered + /// within an aggregate, so the subscriber must be idempotent. + /// + /// + /// Registers only if no + /// is already registered. That default loses every + /// position on restart, which replays all streams; register a durable store in a deployed + /// application. + /// + /// + /// Stream discovery defaults to , which needs a + /// queryable snapshot store. Register an before calling + /// this to use a provider-specific implementation instead. + /// + /// + public IServiceCollection AddEventSubscription( + Action? configure = null + ) + where TAggregate : class, IAggregate, new() + where TSubscriber : class, IEventSubscriber + { + services.TryAddScoped, TSubscriber>(); + services.TryAddSingleton(); + // TryAdd compares service types exactly, so a closed-generic TryAdd would not see a + // provider's open-generic registration and would win by being registered last. + var hasDiscovery = services.Any(descriptor => + descriptor.ServiceType == typeof(IAggregateStreamDiscovery) + || descriptor.ServiceType == typeof(IAggregateStreamDiscovery<>) + ); + if (!hasDiscovery) + { + services.AddScoped< + IAggregateStreamDiscovery, + QueryableAggregateStreamDiscovery + >(); + } + services.TryAddScoped, EventSubscriptionProcessor>(); + services.AddHostedService>(); + services + .AddOptions() + .Configure(options => configure?.Invoke(options)) + .Validate( + static options => options.PollInterval > TimeSpan.Zero && options.CheckpointInterval >= 1, + "SubscriptionOptions is invalid." + ); + return services; + } + /// /// Register the event store components. /// diff --git a/src/src/EventSourcing/Subscriptions/EventSubscriptionContext.cs b/src/src/EventSourcing/Subscriptions/EventSubscriptionContext.cs new file mode 100644 index 00000000..d9d8cb7f --- /dev/null +++ b/src/src/EventSourcing/Subscriptions/EventSubscriptionContext.cs @@ -0,0 +1,41 @@ +using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Aggregates.Events; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.Subscriptions; + +/// +/// One event delivered to an . +/// +/// The aggregate type the subscription reads. +/// The aggregate the event belongs to. +/// The event payload and its framework-managed metadata. +/// The persisted event type name. +/// The tenant the subscription is running as. +public sealed record EventSubscriptionContext( + string AggregateId, + EventRecord Record, + string EventType, + TenantScope Scope +) + where T : class, IAggregate, new() +{ + /// The event payload. + public object Event => Record.Event; + + /// The framework-managed metadata for the event. + public EventMetadata Metadata => Record.Metadata; + + /// The aggregate version the event was recorded at. + public long AggregateVersion => Record.Metadata.AggregateVersion; + + /// + /// when the persisted event type could not be resolved to a CLR type. + /// + /// + /// A subscriber that does not understand the event should return without doing anything. The + /// subscription still advances past it, because an event the application has deleted the contract + /// for must not stall every later event in the stream. + /// + public bool IsUnresolved => Record.Event is UnknownEvent; +} diff --git a/src/src/EventSourcing/Subscriptions/EventSubscriptionProcessor.cs b/src/src/EventSourcing/Subscriptions/EventSubscriptionProcessor.cs new file mode 100644 index 00000000..c92f7ad3 --- /dev/null +++ b/src/src/EventSourcing/Subscriptions/EventSubscriptionProcessor.cs @@ -0,0 +1,117 @@ +using Microsoft.Extensions.Logging; +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.Subscriptions; + +/// +/// Reads each visible aggregate stream from its recorded position and delivers the events in version +/// order. +/// +/// +/// +/// The checkpoint is written after the subscriber returns, never before, so a failure redelivers +/// rather than skips. That makes delivery at-least-once. +/// +/// +/// The cycle runs under whatever is current. Discovery, the event read and +/// the checkpoint all use that scope, so a tenant-scoped subscription sees only its own aggregates +/// and keeps its own position. +/// +/// +/// The aggregate type the subscription reads. +public sealed class EventSubscriptionProcessor( + IEventSubscriber subscriber, + ISubscriptionCheckpointStore checkpoints, + IAggregateStreamDiscovery discovery, + IEventStoreCore eventStore, + ICurrentTenant currentTenant, + IOptions options, + ILogger> logger +) : IEventSubscriptionProcessor + where T : class, IAggregate, new() +{ + /// + public async Task RunCycleAsync(CancellationToken cancellationToken) + { + if (eventStore is not IAggregateEventHistoryStoreCore history) + { + throw new NotSupportedException( + $"The configured event store for aggregate type '{typeof(T).FullName}' does not persist an event stream, so it cannot be subscribed to." + ); + } + + var scope = currentTenant.Current; + var checkpointInterval = options.Value.CheckpointInterval; + + var streamsVisited = 0; + var eventsDelivered = 0; + var streamsFaulted = 0; + + await foreach (var aggregateId in discovery.GetAggregateIdsAsync(cancellationToken)) + { + streamsVisited++; + + SubscriptionCheckpointKey key = new(subscriber.SubscriptionName, scope, aggregateId); + var lastDelivered = await checkpoints.GetAsync(key, cancellationToken) ?? 0; + + // Aggregate versions start at 1, so a stream never read before resumes at 1. + var resumeFrom = lastDelivered + 1; + var sinceCheckpoint = 0; + + try + { + await foreach ( + var (record, eventType) in history.GetEventRangeAsync( + aggregateId, + resumeFrom, + versionTo: null, + cancellationToken + ) + ) + { + await subscriber.OnEventAsync(new(aggregateId, record, eventType, scope), cancellationToken); + + lastDelivered = record.Metadata.AggregateVersion; + eventsDelivered++; + + if (++sinceCheckpoint >= checkpointInterval) + { + await checkpoints.SetAsync(key, lastDelivered, cancellationToken); + sinceCheckpoint = 0; + } + } + } + catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested) + { + // Record what was delivered before unwinding, so the cancelled cycle is not replayed. + if (sinceCheckpoint > 0) + await checkpoints.SetAsync(key, lastDelivered, CancellationToken.None); + + throw; + } + // One subscriber failure must not abandon the remaining streams. +#pragma warning disable CA1031 + catch (Exception ex) +#pragma warning restore CA1031 + { + streamsFaulted++; + logger.LogError( + ex, + "Subscription {SubscriptionName} stopped reading aggregate {AggregateId} at version {Version}; it will retry from there on the next cycle.", + subscriber.SubscriptionName, + aggregateId, + lastDelivered + 1 + ); + } + + // Also checkpoint when the stream is exhausted, so progress on a quiet stream is not + // left unrecorded until the interval happens to be reached. + if (sinceCheckpoint > 0) + await checkpoints.SetAsync(key, lastDelivered, cancellationToken); + } + + return new(streamsVisited, eventsDelivered, streamsFaulted); + } +} diff --git a/src/src/EventSourcing/Subscriptions/IAggregateStreamDiscovery.cs b/src/src/EventSourcing/Subscriptions/IAggregateStreamDiscovery.cs new file mode 100644 index 00000000..79d618bc --- /dev/null +++ b/src/src/EventSourcing/Subscriptions/IAggregateStreamDiscovery.cs @@ -0,0 +1,30 @@ +using Purview.EventSourcing.Aggregates; + +namespace Purview.EventSourcing.Subscriptions; + +/// +/// Finds the aggregate streams a subscription should read. +/// +/// +/// +/// Event streams are keyed by aggregate id, and no provider holds an index of "every stream that +/// exists". Discovery is therefore a seam rather than a fixed implementation: a provider with a +/// queryable snapshot store can enumerate it (), +/// while others need their own. +/// +/// +/// Implementations must honour the current tenant. An implementation that enumerates every stream +/// regardless of scope hands one tenant's aggregate ids to another, even if the subsequent event +/// read is filtered. +/// +/// +/// The aggregate type to discover streams for. +public interface IAggregateStreamDiscovery + where T : class, IAggregate, new() +{ + /// + /// Enumerates the ids of the aggregates visible to the current tenant, in an unspecified order. + /// + /// A token that can be used to cancel the operation. + IAsyncEnumerable GetAggregateIdsAsync(CancellationToken cancellationToken); +} diff --git a/src/src/EventSourcing/Subscriptions/IEventSubscriber.cs b/src/src/EventSourcing/Subscriptions/IEventSubscriber.cs new file mode 100644 index 00000000..a0a537e2 --- /dev/null +++ b/src/src/EventSourcing/Subscriptions/IEventSubscriber.cs @@ -0,0 +1,40 @@ +using Purview.EventSourcing.Aggregates; + +namespace Purview.EventSourcing.Subscriptions; + +/// +/// Receives events from an aggregate's stream, in version order, including events written before the +/// subscriber existed. +/// +/// +/// +/// This is the difference between a subscription and the change feed or the outbox: both of those +/// only carry what happened while they were running, so a projection added today cannot use them to +/// rebuild from history. A subscription reads the stream itself. +/// +/// +/// Delivery is at-least-once, so implementations must be idempotent. Ordering is guaranteed within +/// one aggregate and not between aggregates. +/// +/// +/// The aggregate type to subscribe to. +public interface IEventSubscriber + where T : class, IAggregate, new() +{ + /// + /// The subscription's stable name. Positions are recorded against it, so renaming a live + /// subscription abandons its progress and replays every stream from the beginning. + /// + string SubscriptionName { get; } + + /// + /// Handles one event. + /// + /// The event, its metadata, and the tenant it belongs to. + /// A token that can be used to cancel the operation. + /// + /// Throwing stops this aggregate's stream at the failing event and retries it on the next cycle. + /// Events already delivered in this cycle stay delivered, and other aggregates are unaffected. + /// + Task OnEventAsync(EventSubscriptionContext context, CancellationToken cancellationToken); +} diff --git a/src/src/EventSourcing/Subscriptions/IEventSubscriptionProcessor.cs b/src/src/EventSourcing/Subscriptions/IEventSubscriptionProcessor.cs new file mode 100644 index 00000000..208abfaf --- /dev/null +++ b/src/src/EventSourcing/Subscriptions/IEventSubscriptionProcessor.cs @@ -0,0 +1,18 @@ +using Purview.EventSourcing.Aggregates; + +namespace Purview.EventSourcing.Subscriptions; + +/// +/// Runs a subscription's catch-up cycles. +/// +/// The aggregate type the subscription reads. +public interface IEventSubscriptionProcessor + where T : class, IAggregate, new() +{ + /// + /// Reads every visible stream from its recorded position to the end, delivering each event. + /// + /// A token that can be used to cancel the operation. + /// What the cycle did. + Task RunCycleAsync(CancellationToken cancellationToken); +} diff --git a/src/src/EventSourcing/Subscriptions/ISubscriptionCheckpointStore.cs b/src/src/EventSourcing/Subscriptions/ISubscriptionCheckpointStore.cs new file mode 100644 index 00000000..18298152 --- /dev/null +++ b/src/src/EventSourcing/Subscriptions/ISubscriptionCheckpointStore.cs @@ -0,0 +1,28 @@ +namespace Purview.EventSourcing.Subscriptions; + +/// +/// Persists how far a subscription has read each aggregate's stream. +/// +/// +/// A checkpoint is written only after the subscriber has handled the event, so a crash between the +/// two redelivers rather than skips. Delivery is therefore at-least-once and subscribers must be +/// idempotent. +/// +public interface ISubscriptionCheckpointStore +{ + /// + /// Gets the last aggregate version delivered for , or + /// when the subscription has not read this stream before. + /// + /// The subscription, tenant and aggregate the position belongs to. + /// A token that can be used to cancel the operation. + Task GetAsync(SubscriptionCheckpointKey key, CancellationToken cancellationToken); + + /// + /// Records that every event up to and including has been delivered. + /// + /// The subscription, tenant and aggregate the position belongs to. + /// The last delivered aggregate version. + /// A token that can be used to cancel the operation. + Task SetAsync(SubscriptionCheckpointKey key, long version, CancellationToken cancellationToken); +} diff --git a/src/src/EventSourcing/Subscriptions/InMemorySubscriptionCheckpointStore.cs b/src/src/EventSourcing/Subscriptions/InMemorySubscriptionCheckpointStore.cs new file mode 100644 index 00000000..54e36d35 --- /dev/null +++ b/src/src/EventSourcing/Subscriptions/InMemorySubscriptionCheckpointStore.cs @@ -0,0 +1,29 @@ +using System.Collections.Concurrent; + +namespace Purview.EventSourcing.Subscriptions; + +/// +/// A non-persistent held in process memory. +/// +/// +/// Positions are lost on restart, so every subscription replays its streams from the beginning. +/// That is correct but rarely desirable: use this for tests and local development, and register a +/// durable store in a deployed application. +/// +public sealed class InMemorySubscriptionCheckpointStore : ISubscriptionCheckpointStore +{ + readonly ConcurrentDictionary _checkpoints = new(); + + /// + public Task GetAsync(SubscriptionCheckpointKey key, CancellationToken cancellationToken) => + Task.FromResult(_checkpoints.TryGetValue(key, out var version) ? version : (long?)null); + + /// + public Task SetAsync(SubscriptionCheckpointKey key, long version, CancellationToken cancellationToken) + { + // A cycle that re-read an earlier range must not move the position backwards. + _checkpoints.AddOrUpdate(key, version, (_, existing) => Math.Max(existing, version)); + + return Task.CompletedTask; + } +} diff --git a/src/src/EventSourcing/Subscriptions/QueryableAggregateStreamDiscovery.cs b/src/src/EventSourcing/Subscriptions/QueryableAggregateStreamDiscovery.cs new file mode 100644 index 00000000..df692d1b --- /dev/null +++ b/src/src/EventSourcing/Subscriptions/QueryableAggregateStreamDiscovery.cs @@ -0,0 +1,28 @@ +using System.Runtime.CompilerServices; +using Purview.EventSourcing.Aggregates; + +namespace Purview.EventSourcing.Subscriptions; + +/// +/// Discovers streams by enumerating the queryable snapshot store. +/// +/// +/// The snapshot store is already tenant-filtered, so the enumeration inherits that filtering. Only +/// aggregates that have been snapshotted are found: a provider configured with a snapshot strategy +/// that has not yet written one will not surface that aggregate to a subscription until it does. +/// +/// The aggregate type to discover streams for. +/// The queryable store to enumerate. +public sealed class QueryableAggregateStreamDiscovery(IQueryableEventStoreCore eventStore) + : IAggregateStreamDiscovery + where T : class, IAggregate, new() +{ + /// + public async IAsyncEnumerable GetAggregateIdsAsync( + [EnumeratorCancellation] CancellationToken cancellationToken + ) + { + await foreach (var aggregate in eventStore.GetListEnumerableAsync(null, cancellationToken: cancellationToken)) + yield return aggregate.Id(); + } +} diff --git a/src/src/EventSourcing/Subscriptions/SubscriptionCheckpointKey.cs b/src/src/EventSourcing/Subscriptions/SubscriptionCheckpointKey.cs new file mode 100644 index 00000000..5216c791 --- /dev/null +++ b/src/src/EventSourcing/Subscriptions/SubscriptionCheckpointKey.cs @@ -0,0 +1,18 @@ +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.Subscriptions; + +/// +/// Identifies one subscription's position in one aggregate's stream, for one tenant. +/// +/// +/// The is part of the key rather than something a store is trusted to +/// apply, so a checkpoint cannot be written without stating which tenant it belongs to. Two tenants +/// running the same subscription therefore hold separate positions; if they shared one, whichever +/// tenant ran first would advance the position past the other's unread events and those events +/// would never be delivered. +/// +/// The subscription's stable name. +/// The tenant the subscription is running as. +/// The aggregate whose stream the position refers to. +public readonly record struct SubscriptionCheckpointKey(string SubscriptionName, TenantScope Scope, string AggregateId); diff --git a/src/src/EventSourcing/Subscriptions/SubscriptionCycleResult.cs b/src/src/EventSourcing/Subscriptions/SubscriptionCycleResult.cs new file mode 100644 index 00000000..c40591d1 --- /dev/null +++ b/src/src/EventSourcing/Subscriptions/SubscriptionCycleResult.cs @@ -0,0 +1,12 @@ +namespace Purview.EventSourcing.Subscriptions; + +/// +/// What one catch-up cycle did. +/// +/// The number of aggregate streams examined. +/// The number of events handed to the subscriber. +/// +/// The number of streams stopped early because the subscriber threw. Each is retried on the next +/// cycle from the last event it did handle. +/// +public readonly record struct SubscriptionCycleResult(int StreamsVisited, int EventsDelivered, int StreamsFaulted); diff --git a/src/src/EventSourcing/Subscriptions/SubscriptionHostedService.cs b/src/src/EventSourcing/Subscriptions/SubscriptionHostedService.cs new file mode 100644 index 00000000..a8f08634 --- /dev/null +++ b/src/src/EventSourcing/Subscriptions/SubscriptionHostedService.cs @@ -0,0 +1,54 @@ +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Logging; +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Aggregates; + +namespace Purview.EventSourcing.Subscriptions; + +/// +/// Drives a subscription's catch-up cycles on a fixed interval. +/// +/// +/// A scope is created per cycle so scoped services - the event store, the current tenant - resolve +/// the way they do for a request. +/// +/// The aggregate type the subscription reads. +public sealed class SubscriptionHostedService( + IServiceScopeFactory scopeFactory, + IOptions options, + ILogger> logger +) : BackgroundService + where T : class, IAggregate, new() +{ + /// + protected override async Task ExecuteAsync(CancellationToken stoppingToken) + { + while (!stoppingToken.IsCancellationRequested) + { + try + { + using var scope = scopeFactory.CreateScope(); + var processor = scope.ServiceProvider.GetRequiredService>(); + await processor.RunCycleAsync(stoppingToken); + } + catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested) + { + break; + } + // A store or discovery failure must not terminate the loop; the next cycle retries. +#pragma warning disable CA1031 + catch (Exception ex) +#pragma warning restore CA1031 + { + logger.LogError( + ex, + "Subscription cycle for aggregate type {AggregateType} failed; the loop will retry after the poll interval.", + typeof(T).Name + ); + } + + await Task.Delay(options.Value.PollInterval, stoppingToken); + } + } +} diff --git a/src/src/EventSourcing/Subscriptions/SubscriptionOptions.cs b/src/src/EventSourcing/Subscriptions/SubscriptionOptions.cs new file mode 100644 index 00000000..2023ca9e --- /dev/null +++ b/src/src/EventSourcing/Subscriptions/SubscriptionOptions.cs @@ -0,0 +1,35 @@ +namespace Purview.EventSourcing.Subscriptions; + +/// +/// Configuration for event subscriptions. +/// +public sealed class SubscriptionOptions +{ + /// The configuration section name used to bind these options. + public const string Section = "EventStore:Subscriptions"; + + /// The delay between catch-up cycles. + public TimeSpan PollInterval { get; set; } = TimeSpan.FromSeconds(5); + + /// + /// How many events are delivered between checkpoint writes. + /// + /// + /// The trade-off is write volume against redelivery after a crash: a larger interval writes less + /// and redelivers more. Whatever the value, the position is also written when an aggregate's + /// stream is exhausted, so a quiet stream does not leave progress unrecorded. + /// + public int CheckpointInterval { get; set; } = 100; + + /// + /// Validates the option set. + /// + /// Thrown when any option is outside its supported range. + public void Validate() + { + if (PollInterval <= TimeSpan.Zero) + throw new InvalidOperationException("SubscriptionOptions.PollInterval must be positive."); + if (CheckpointInterval < 1) + throw new InvalidOperationException("SubscriptionOptions.CheckpointInterval must be >= 1."); + } +} diff --git a/src/src/InMemory/Events/IInMemoryEventStore.cs b/src/src/InMemory/Events/IInMemoryEventStore.cs index 6c6f8b97..bd07eac7 100644 --- a/src/src/InMemory/Events/IInMemoryEventStore.cs +++ b/src/src/InMemory/Events/IInMemoryEventStore.cs @@ -22,4 +22,14 @@ public interface IInMemoryEventStore : INonQueryableEventStore, IAggregate /// A token that can be used to cancel the operation. /// A task that completes when the store has been cleared. Task ClearAsync(CancellationToken cancellationToken = default); + + /// + /// Enumerates the ids of the streams visible to the current tenant. + /// + /// A token that can be used to cancel the operation. + /// + /// This store has no queryable snapshot reads, so it supplies its own stream discovery for + /// subscriptions rather than using the queryable default. + /// + IAsyncEnumerable GetAggregateIdsAsync(CancellationToken cancellationToken = default); } diff --git a/src/src/InMemory/Events/InMemoryAggregateStreamDiscovery.cs b/src/src/InMemory/Events/InMemoryAggregateStreamDiscovery.cs new file mode 100644 index 00000000..3b722b86 --- /dev/null +++ b/src/src/InMemory/Events/InMemoryAggregateStreamDiscovery.cs @@ -0,0 +1,23 @@ +using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Subscriptions; + +namespace Purview.EventSourcing.InMemory.Events; + +/// +/// Discovers streams directly from the in-memory store. +/// +/// +/// The in-memory store has no queryable snapshot reads, so the queryable default cannot be used. It +/// does hold every stream it has written, which makes discovery exact rather than dependent on a +/// snapshot having been taken. +/// +/// The aggregate type to discover streams for. +/// The store to enumerate. +public sealed class InMemoryAggregateStreamDiscovery(IInMemoryEventStore eventStore) + : IAggregateStreamDiscovery + where T : class, IAggregate, new() +{ + /// + public IAsyncEnumerable GetAggregateIdsAsync(CancellationToken cancellationToken) => + eventStore.GetAggregateIdsAsync(cancellationToken); +} diff --git a/src/src/InMemory/Events/InMemoryEventStore.cs b/src/src/InMemory/Events/InMemoryEventStore.cs index b448083e..a118b2d2 100644 --- a/src/src/InMemory/Events/InMemoryEventStore.cs +++ b/src/src/InMemory/Events/InMemoryEventStore.cs @@ -20,7 +20,7 @@ namespace Purview.EventSourcing.InMemory.Events; /// Optional factory used to generate aggregate ids when none is supplied. /// Optional accessor supplying the principal recorded against saved events. /// Optional metrics recorder; defaults to a no-op. -/// Optional tenant scope. This store does not enforce tenant isolation and refuses a tenant-scoped operation. +/// Optional tenant scope; defaults to the system scope. Reads fail closed, so an unowned stream is visible only to the system scope. /// /// Aggregates are held in memory and are identified by id in a case-insensitive manner. This store is /// intended for testing and single-process scenarios; data is not shared between instances or persisted @@ -351,6 +351,12 @@ CancellationToken cancellationToken return matched.ToAsyncEnumerable(); } + /// + public IAsyncEnumerable GetAggregateIdsAsync(CancellationToken cancellationToken = default) => + // Filtered the same way every read is: an unowned stream is visible only to the system scope, + // so discovery cannot hand one tenant's aggregate ids to another. + _events.Keys.Where(IsVisible).ToArray().ToAsyncEnumerable(); + /// public async Task> GetOrCreateAsync( string? aggregateId, diff --git a/src/src/InMemory/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/InMemory/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs index e372a56f..9b04a756 100644 --- a/src/src/InMemory/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs +++ b/src/src/InMemory/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -2,6 +2,7 @@ using Purview.EventSourcing.InMemory.Events; using Purview.EventSourcing.InMemory.Snapshots; using Purview.EventSourcing.Internal; +using Purview.EventSourcing.Subscriptions; namespace Microsoft.Extensions.DependencyInjection; @@ -37,6 +38,10 @@ public IServiceCollection AddInMemoryEventStore() .AddTransient(typeof(IInMemoryEventStore<>), typeof(InMemoryEventStore<>)) .AddTransient(); + // Registered ahead of AddEventSubscription's TryAdd default, which needs a queryable + // snapshot store this provider does not have. + services.AddTransient(typeof(IAggregateStreamDiscovery<>), typeof(InMemoryAggregateStreamDiscovery<>)); + services.AddEventStoreCapabilities( new EventStoreCapabilities( EventStoreTransactionGuarantee.BestEffort, @@ -83,6 +88,10 @@ public IServiceCollection AddInMemorySnapshotEventStore() .AddTransient() .AddTransient(); + // Registered ahead of AddEventSubscription's TryAdd default, which needs a queryable + // snapshot store this provider does not have. + services.AddTransient(typeof(IAggregateStreamDiscovery<>), typeof(InMemoryAggregateStreamDiscovery<>)); + services.AddEventStoreCapabilities( new EventStoreCapabilities( EventStoreTransactionGuarantee.BestEffort, diff --git a/src/tests/EventSourcing.AcceptanceTests/RecordingSubscriber.cs b/src/tests/EventSourcing.AcceptanceTests/RecordingSubscriber.cs new file mode 100644 index 00000000..b2603168 --- /dev/null +++ b/src/tests/EventSourcing.AcceptanceTests/RecordingSubscriber.cs @@ -0,0 +1,38 @@ +using System.Collections.Concurrent; +using Purview.EventSourcing.Subscriptions; + +namespace Purview.EventSourcing; + +/// +/// What a subscriber was handed, and for which tenant. +/// +/// The tenant the subscription was running as; null for the system scope. +/// The aggregate the event belonged to. +/// The version the event was recorded at. +public sealed record DeliveredEvent(string? TenantId, string AggregateId, long AggregateVersion); + +/// +/// An that records what it receives, so a scenario can assert on it. +/// +public sealed class RecordingSubscriber : IEventSubscriber +{ + /// + public string SubscriptionName => "acceptance"; + + /// Every event handed to the subscriber, in delivery order. + public ConcurrentQueue Delivered { get; } = new(); + + /// When set, the subscriber throws for any event this returns true for. + public Func, bool>? FailOn { get; set; } + + /// + public Task OnEventAsync(EventSubscriptionContext context, CancellationToken cancellationToken) + { + if (FailOn?.Invoke(context) == true) + throw new InvalidOperationException($"Subscriber refused version {context.AggregateVersion}."); + + Delivered.Enqueue(new(context.Scope.TenantId, context.AggregateId, context.AggregateVersion)); + + return Task.CompletedTask; + } +} diff --git a/src/tests/EventSourcing.AcceptanceTests/Steps/SubscriptionAssertions.cs b/src/tests/EventSourcing.AcceptanceTests/Steps/SubscriptionAssertions.cs new file mode 100644 index 00000000..dc4d1d12 --- /dev/null +++ b/src/tests/EventSourcing.AcceptanceTests/Steps/SubscriptionAssertions.cs @@ -0,0 +1,41 @@ +using BDTest; + +namespace Purview.EventSourcing.Steps; + +/// +/// The outcomes a subscription scenario asserts. +/// +/// The scenario's state. +public sealed class SubscriptionAssertions(SubscriptionScenarioContext context) +{ + [StepText("the subscriber received {count} events")] + public async Task TheSubscriberReceived(int count) => + await Assert.That(context.Subscriber.Delivered.Count).IsEqualTo(count); + + [StepText("the subscriber received nothing")] + public async Task TheSubscriberReceivedNothing() => await Assert.That(context.Subscriber.Delivered).IsEmpty(); + + [StepText("every event the subscriber received belonged to tenant {tenant}")] + public async Task EveryEventBelongedToTenant(string tenant) => + await Assert.That(context.Subscriber.Delivered.All(delivered => delivered.TenantId == tenant)).IsTrue(); + + [StepText("the events arrived in version order")] + public async Task TheEventsArrivedInVersionOrder() + { + var versions = context.Subscriber.Delivered.Select(delivered => delivered.AggregateVersion).ToArray(); + + await Assert.That(versions).IsEquivalentTo(versions.OrderBy(version => version).ToArray()); + } + + [StepText("no event was delivered more than once")] + public async Task NoEventWasDeliveredTwice() + { + var delivered = context.Subscriber.Delivered.ToArray(); + + await Assert.That(delivered.Distinct().Count()).IsEqualTo(delivered.Length); + } + + [StepText("the cycle reported {count} faulted streams")] + public async Task TheCycleReportedFaultedStreams(int count) => + await Assert.That(context.LastCycle!.Value.StreamsFaulted).IsEqualTo(count); +} diff --git a/src/tests/EventSourcing.AcceptanceTests/Steps/SubscriptionSteps.cs b/src/tests/EventSourcing.AcceptanceTests/Steps/SubscriptionSteps.cs new file mode 100644 index 00000000..e27e5c9c --- /dev/null +++ b/src/tests/EventSourcing.AcceptanceTests/Steps/SubscriptionSteps.cs @@ -0,0 +1,68 @@ +using BDTest; + +namespace Purview.EventSourcing.Steps; + +/// +/// The actions a subscription scenario performs. +/// +/// The scenario's state. +public sealed class SubscriptionSteps(SubscriptionScenarioContext context) +{ + [StepText("tenant {tenant} has an aggregate that was incremented {count} times")] + public Task AnAggregateExistsForTenant(string tenant, int count) => + SubscriptionScenarioContext.AsTenantAsync( + tenant, + async () => + { + var aggregate = await context.Store.CreateAsync(context.AggregateId); + for (var i = 0; i < count; i++) + aggregate.Increment(1); + + await context.Store.SaveAsync(aggregate, SubscriptionScenarioContext.OperationContext()); + } + ); + + [StepText("tenant {tenant} increments that aggregate {count} more times")] + public Task TheAggregateIsIncrementedAgain(string tenant, int count) => + SubscriptionScenarioContext.AsTenantAsync( + tenant, + async () => + { + var read = await context.Store.GetAsync( + context.AggregateId, + SubscriptionScenarioContext.OperationContext() + ); + + var aggregate = read.Value; + for (var i = 0; i < count; i++) + aggregate.Increment(1); + + await context.Store.SaveAsync(aggregate, SubscriptionScenarioContext.OperationContext()); + } + ); + + [StepText("a subscription runs for tenant {tenant}")] + public Task TheSubscriptionRunsForTenant(string tenant) => context.RunCycleAsync(tenant); + + [StepText("a subscription runs as infrastructure, across every tenant")] + public Task TheSubscriptionRunsAsInfrastructure() => context.RunCycleAsync(null); + + [StepText("the subscription for tenant {tenant} runs a second time")] + public Task TheSubscriptionRunsAgainForTenant(string tenant) => context.RunCycleAsync(tenant); + + [StepText("the subscriber refuses the event at version {version}")] + public Task TheSubscriberRefusesVersion(int version) + { + context.Subscriber.FailOn = delivered => delivered.AggregateVersion == version; + + return Task.CompletedTask; + } + + [StepText("the subscriber starts accepting every event again")] + public Task TheSubscriberAcceptsEverything() + { + context.Subscriber.FailOn = null; + + return Task.CompletedTask; + } +} diff --git a/src/tests/EventSourcing.AcceptanceTests/SubscriptionScenarioContext.cs b/src/tests/EventSourcing.AcceptanceTests/SubscriptionScenarioContext.cs new file mode 100644 index 00000000..9e6ddd6d --- /dev/null +++ b/src/tests/EventSourcing.AcceptanceTests/SubscriptionScenarioContext.cs @@ -0,0 +1,91 @@ +using Microsoft.Extensions.DependencyInjection; +using Purview.EventSourcing.InMemory.Events; +using Purview.EventSourcing.Subscriptions; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing; + +/// +/// The state one subscription scenario builds up and asserts against. +/// +/// +/// Cycles are run explicitly rather than by the hosted service, so a scenario is deterministic: it +/// states when the subscription reads, and asserts what it read. +/// +public sealed class SubscriptionScenarioContext : IDisposable +{ + readonly ServiceProvider _provider; + + /// Creates the context, its store, and its subscription. + public SubscriptionScenarioContext() + { + ServiceCollection services = new(); + services.AddLogging(); + services.AddEventSourcing().AddInMemoryEventStore(); + + // The in-memory store keeps its data in the instance, and is registered transient, so the + // subscription would otherwise read a different, empty store than the scenario writes to. + services.AddSingleton, InMemoryEventStore>(); + services.AddSingleton>(static provider => + provider.GetRequiredService>() + ); + + // Registered before AddEventSubscription so its TryAdd leaves this shared instance in place. + Subscriber = new RecordingSubscriber(); + services.AddSingleton>(Subscriber); + + services.AddEventSubscription(); + + _provider = services.BuildServiceProvider(); + Store = _provider.GetRequiredService>(); + } + + /// The store every step writes through. + public IInMemoryEventStore Store { get; } + + /// The subscriber whose deliveries the scenario asserts on. + public RecordingSubscriber Subscriber { get; } + + /// The aggregate identifier the scenario is working with. + public string AggregateId { get; set; } = $"{Guid.NewGuid()}"; + + /// The result of the most recent catch-up cycle. + public SubscriptionCycleResult? LastCycle { get; set; } + + /// Runs one catch-up cycle as the given tenant. + /// The tenant, or for the system scope. + public async Task RunCycleAsync(string? tenant) + { + var scope = tenant is null ? TenantScope.System : TenantScope.For(tenant); + + using (AmbientCurrentTenant.BeginScope(scope)) + { + using var serviceScope = _provider.CreateScope(); + var processor = serviceScope.ServiceProvider.GetRequiredService< + IEventSubscriptionProcessor + >(); + + var result = await processor.RunCycleAsync(CancellationToken.None); + LastCycle = result; + + return result; + } + } + + /// Runs an action under a tenant scope. + /// The tenant, or for the system scope. + /// The work to run. + public static async Task AsTenantAsync(string? tenant, Func action) + { + var scope = tenant is null ? TenantScope.System : TenantScope.For(tenant); + + using (AmbientCurrentTenant.BeginScope(scope)) + await action(); + } + + /// The operation context scenarios use; no principal is configured. + public static EventStoreOperationContext OperationContext() => new() { RequiresValidPrincipalIdentifier = false }; + + /// + public void Dispose() => _provider.Dispose(); +} diff --git a/src/tests/EventSourcing.AcceptanceTests/SubscriptionScenarios.cs b/src/tests/EventSourcing.AcceptanceTests/SubscriptionScenarios.cs new file mode 100644 index 00000000..a95d1668 --- /dev/null +++ b/src/tests/EventSourcing.AcceptanceTests/SubscriptionScenarios.cs @@ -0,0 +1,95 @@ +using BDTest; +using Purview.EventSourcing.Steps; + +namespace Purview.EventSourcing; + +/// +/// What a subscription promises, stated as scenarios. +/// +/// +/// Tenant isolation comes first, because a subscription reads streams it did not write and a +/// discovery that ignores the tenant hands one tenant's data to another regardless of how the +/// subsequent read is filtered. +/// +public sealed class SubscriptionScenarios : TUnitBDTestBase +{ + SubscriptionSteps Steps => field ??= new(Context); + + SubscriptionAssertions Expect => field ??= new(Context); + + [Test] + public async Task ASubscriptionDoesNotReceiveAnotherTenantsEvents() => + await Given(() => Steps.AnAggregateExistsForTenant("acme", 3)) + .When(() => Steps.TheSubscriptionRunsForTenant("globex")) + .Then(() => Expect.TheSubscriberReceivedNothing()) + .WithScenarioText("A subscription does not receive another tenant's events"); + + [Test] + public async Task ASubscriptionReceivesItsOwnTenantsEvents() => + await Given(() => Steps.AnAggregateExistsForTenant("acme", 3)) + .When(() => Steps.TheSubscriptionRunsForTenant("acme")) + .Then(() => Expect.TheSubscriberReceived(3)) + .And(() => Expect.EveryEventBelongedToTenant("acme")) + .WithScenarioText("A subscription receives its own tenant's events"); + + // The position is keyed by tenant, so one tenant's progress must not advance another's past + // events it has never seen. + [Test] + public async Task EachTenantKeepsItsOwnPosition() => + await Given(() => Steps.AnAggregateExistsForTenant("acme", 3)) + .And(() => Steps.TheSubscriptionRunsForTenant("acme")) + .When(() => Steps.TheSubscriptionRunsAsInfrastructure()) + .Then(() => Expect.TheSubscriberReceived(6)) + .WithScenarioText("Each tenant keeps its own subscription position"); + + // The whole reason a subscription exists rather than the change feed or the outbox: those only + // carry what happened while they were running. + [Test] + public async Task ASubscriptionReadsEventsWrittenBeforeItRan() => + await Given(() => Steps.AnAggregateExistsForTenant("acme", 5)) + .When(() => Steps.TheSubscriptionRunsForTenant("acme")) + .Then(() => Expect.TheSubscriberReceived(5)) + .And(() => Expect.TheEventsArrivedInVersionOrder()) + .WithScenarioText("A subscription reads events written before it ever ran"); + + [Test] + public async Task ASubscriptionDoesNotRedeliverWhatItAlreadyRead() => + await Given(() => Steps.AnAggregateExistsForTenant("acme", 3)) + .And(() => Steps.TheSubscriptionRunsForTenant("acme")) + .When(() => Steps.TheSubscriptionRunsAgainForTenant("acme")) + .Then(() => Expect.TheSubscriberReceived(3)) + .And(() => Expect.NoEventWasDeliveredTwice()) + .WithScenarioText("A subscription does not redeliver what it already read"); + + [Test] + public async Task ASubscriptionResumesFromItsPosition() => + await Given(() => Steps.AnAggregateExistsForTenant("acme", 3)) + .And(() => Steps.TheSubscriptionRunsForTenant("acme")) + .And(() => Steps.TheAggregateIsIncrementedAgain("acme", 2)) + .When(() => Steps.TheSubscriptionRunsAgainForTenant("acme")) + .Then(() => Expect.TheSubscriberReceived(5)) + .And(() => Expect.NoEventWasDeliveredTwice()) + .WithScenarioText("A subscription resumes from its position and reads only what is new"); + + // Fail-closed: a refused event stops that stream where it is, rather than being skipped. The + // alternative loses data silently. + [Test] + public async Task ARefusedEventStopsTheStreamRatherThanBeingSkipped() => + await Given(() => Steps.AnAggregateExistsForTenant("acme", 4)) + .And(() => Steps.TheSubscriberRefusesVersion(3)) + .When(() => Steps.TheSubscriptionRunsForTenant("acme")) + .Then(() => Expect.TheSubscriberReceived(2)) + .And(() => Expect.TheCycleReportedFaultedStreams(1)) + .WithScenarioText("A refused event stops that stream rather than being skipped"); + + [Test] + public async Task AStreamResumesOnceTheSubscriberAcceptsTheEventAgain() => + await Given(() => Steps.AnAggregateExistsForTenant("acme", 4)) + .And(() => Steps.TheSubscriberRefusesVersion(3)) + .And(() => Steps.TheSubscriptionRunsForTenant("acme")) + .And(() => Steps.TheSubscriberAcceptsEverything()) + .When(() => Steps.TheSubscriptionRunsAgainForTenant("acme")) + .Then(() => Expect.TheSubscriberReceived(4)) + .And(() => Expect.NoEventWasDeliveredTwice()) + .WithScenarioText("A stream resumes from the refused event once the subscriber accepts it"); +} diff --git a/src/tests/EventSourcing.UnitTests/Subscriptions/SubscriptionOptionsTests.cs b/src/tests/EventSourcing.UnitTests/Subscriptions/SubscriptionOptionsTests.cs new file mode 100644 index 00000000..8f1e8b9d --- /dev/null +++ b/src/tests/EventSourcing.UnitTests/Subscriptions/SubscriptionOptionsTests.cs @@ -0,0 +1,51 @@ +namespace Purview.EventSourcing.Subscriptions; + +public sealed class SubscriptionOptionsTests +{ + [Test] + public async Task Validate_GivenDefaults_DoesNotThrow() + { + SubscriptionOptions options = new(); + + await Assert.That(options.Validate).ThrowsNothing(); + } + + [Test] + public async Task Validate_GivenANonPositivePollInterval_Throws() + { + SubscriptionOptions options = new() { PollInterval = TimeSpan.Zero }; + + await Assert.That(options.Validate).Throws(); + } + + [Test] + public async Task Validate_GivenACheckpointIntervalBelowOne_Throws() + { + SubscriptionOptions options = new() { CheckpointInterval = 0 }; + + await Assert.That(options.Validate).Throws(); + } + + // A cycle that re-read an earlier range must not rewind a position that is already further on, + // which would redeliver everything between the two. + [Test] + public async Task SetAsync_GivenAnEarlierVersionThanRecorded_DoesNotMoveBackwards() + { + InMemorySubscriptionCheckpointStore checkpoints = new(); + SubscriptionCheckpointKey key = new("projection", Tenancy.TenantScope.System, "aggregate-1"); + + await checkpoints.SetAsync(key, 50, CancellationToken.None); + await checkpoints.SetAsync(key, 10, CancellationToken.None); + + await Assert.That(await checkpoints.GetAsync(key, CancellationToken.None)).IsEqualTo(50); + } + + [Test] + public async Task GetAsync_GivenAStreamNeverRead_ReturnsNull() + { + InMemorySubscriptionCheckpointStore checkpoints = new(); + SubscriptionCheckpointKey key = new("projection", Tenancy.TenantScope.System, "aggregate-1"); + + await Assert.That(await checkpoints.GetAsync(key, CancellationToken.None)).IsNull(); + } +} diff --git a/src/tests/EventSourcing.UnitTests/Subscriptions/SubscriptionTenancyTests.cs b/src/tests/EventSourcing.UnitTests/Subscriptions/SubscriptionTenancyTests.cs new file mode 100644 index 00000000..4619f05e --- /dev/null +++ b/src/tests/EventSourcing.UnitTests/Subscriptions/SubscriptionTenancyTests.cs @@ -0,0 +1,147 @@ +using Microsoft.Extensions.DependencyInjection; +using Purview.EventSourcing.InMemory.Events; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.Subscriptions; + +/// +/// Tenant isolation for subscriptions, tested at the seam that can leak rather than through the +/// subscription as a whole. +/// +/// +/// A scenario that asserts "the other tenant's subscriber received nothing" passes even when +/// discovery leaks, because the subsequent event read is filtered too and returns nothing. That +/// second filter masks the first. These tests therefore assert on what discovery itself returns: +/// aggregate ids are data, and handing one tenant's ids to another is a leak whether or not the +/// events behind them can be read. +/// +public sealed class SubscriptionTenancyTests +{ + [Test] + public async Task GetAggregateIdsAsync_GivenAnotherTenantsAggregate_DoesNotReturnIt() + { + await using Fixture fixture = new(); + await fixture.SeedAsync("acme", "acme-1"); + + var discovered = await fixture.DiscoverAsync(TenantScope.For("globex")); + + await Assert.That(discovered).IsEmpty(); + } + + [Test] + public async Task GetAggregateIdsAsync_GivenItsOwnAggregate_ReturnsIt() + { + await using Fixture fixture = new(); + await fixture.SeedAsync("acme", "acme-1"); + + var discovered = await fixture.DiscoverAsync(TenantScope.For("acme")); + + await Assert.That(discovered).IsEquivalentTo(["acme-1"]); + } + + [Test] + public async Task GetAggregateIdsAsync_GivenSystemScope_ReturnsEveryTenantsAggregates() + { + await using Fixture fixture = new(); + await fixture.SeedAsync("acme", "acme-1"); + await fixture.SeedAsync("globex", "globex-1"); + + var discovered = await fixture.DiscoverAsync(TenantScope.System); + + await Assert.That(discovered.OrderBy(id => id, StringComparer.Ordinal)).IsEquivalentTo(["acme-1", "globex-1"]); + } + + // Fail closed: a stream whose write path forgot the tenant stamp must not become visible to + // every tenant. Only the system scope sees it. + [Test] + public async Task GetAggregateIdsAsync_GivenAnUnownedAggregate_IsNotVisibleToATenant() + { + await using Fixture fixture = new(); + await fixture.SeedAsync(tenant: null, "unowned-1"); + + var discovered = await fixture.DiscoverAsync(TenantScope.For("acme")); + + await Assert.That(discovered).IsEmpty(); + } + + // Two tenants sharing a position would let whichever ran first advance the checkpoint past the + // other's unread events, and those events would never be delivered. + [Test] + public async Task Checkpoints_GivenTheSameSubscriptionAndAggregate_AreSeparatePerTenant() + { + InMemorySubscriptionCheckpointStore checkpoints = new(); + + SubscriptionCheckpointKey acme = new("projection", TenantScope.For("acme"), "shared-id"); + SubscriptionCheckpointKey globex = new("projection", TenantScope.For("globex"), "shared-id"); + + await checkpoints.SetAsync(acme, 50, CancellationToken.None); + + await Assert.That(await checkpoints.GetAsync(acme, CancellationToken.None)).IsEqualTo(50); + await Assert.That(await checkpoints.GetAsync(globex, CancellationToken.None)).IsNull(); + } + + [Test] + public async Task Checkpoints_GivenTheSystemScope_IsSeparateFromEveryTenant() + { + InMemorySubscriptionCheckpointStore checkpoints = new(); + + SubscriptionCheckpointKey system = new("projection", TenantScope.System, "shared-id"); + SubscriptionCheckpointKey acme = new("projection", TenantScope.For("acme"), "shared-id"); + + await checkpoints.SetAsync(system, 50, CancellationToken.None); + + await Assert.That(await checkpoints.GetAsync(acme, CancellationToken.None)).IsNull(); + } + + sealed class Fixture : IAsyncDisposable + { + readonly ServiceProvider _provider; + + public Fixture() + { + ServiceCollection services = new(); + services.AddLogging(); + services.AddEventSourcing().AddInMemoryEventStore(); + + // The in-memory store holds its data in the instance and is registered transient, so the + // seed and the discovery must resolve the same one. + services.AddSingleton< + IInMemoryEventStore, + InMemoryEventStore + >(); + + _provider = services.BuildServiceProvider(); + } + + public async Task SeedAsync(string? tenant, string aggregateId) + { + var store = _provider.GetRequiredService>(); + var scope = tenant is null ? TenantScope.System : TenantScope.For(tenant); + + using (AmbientCurrentTenant.BeginScope(scope)) + { + var aggregate = await store.CreateAsync(aggregateId); + aggregate.Touch(); + + await store.SaveAsync(aggregate, new() { RequiresValidPrincipalIdentifier = false }); + } + } + + public async Task> DiscoverAsync(TenantScope scope) + { + var store = _provider.GetRequiredService>(); + InMemoryAggregateStreamDiscovery discovery = new(store); + + using (AmbientCurrentTenant.BeginScope(scope)) + { + List ids = []; + await foreach (var id in discovery.GetAggregateIdsAsync(CancellationToken.None)) + ids.Add(id); + + return ids; + } + } + + public ValueTask DisposeAsync() => _provider.DisposeAsync(); + } +} diff --git a/src/tests/EventSourcing.UnitTests/Subscriptions/SubscriptionTestAggregate.cs b/src/tests/EventSourcing.UnitTests/Subscriptions/SubscriptionTestAggregate.cs new file mode 100644 index 00000000..3d4bad0b --- /dev/null +++ b/src/tests/EventSourcing.UnitTests/Subscriptions/SubscriptionTestAggregate.cs @@ -0,0 +1,30 @@ +using Purview.EventSourcing.Aggregates; +using Purview.EventSourcing.Aggregates.Events; + +namespace Purview.EventSourcing.Subscriptions; + +/// +/// A minimal aggregate for the subscription tests: it only needs a stream to exist. +/// +public sealed class SubscriptionTestAggregate : AggregateBase +{ + /// How many times the aggregate has been touched. + public int TouchCount { get; private set; } + + /// + protected override void RegisterEvents() => Register(_ => TouchCount++); + + /// Records one event. + public void Touch() => RecordAndApply(new Touched()); +} + +/// An event with no payload beyond its metadata. +[EventContract] +public sealed record Touched +{ + /// The event schema version. + public static int SchemaVersion => 1; + + /// The event metadata. + public EventMetadata Metadata { get; init; } +} From 4c092b5ee6bffece39c9466ea2e009661e1992ca Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Sun, 25 Oct 2026 21:59:18 +0000 Subject: [PATCH 13/41] feat: durable subscription checkpoints for SQL Server and PostgreSQL Subscriptions previously replayed every stream after a restart, which made them unusable in a deployed application. AddSqlServerSubscriptionCheckpoints and AddPostgresSubscriptionCheckpoints persist the position instead. Also removes the stream-discovery duplication introduced with subscriptions. IEventStoreCore.GetAggregateIdsAsync already existed on every store and is already tenant-filtered - by the EF global query filter on the SQL providers, the scoped table client on Azure, and IsVisible on InMemory. The default discovery now reads that, which deletes two implementations and makes subscriptions work on Azure Storage, where the previous snapshot-store default could never have run. The scope is encoded into one non-null column by a shared helper rather than per provider. A nullable tenant column would not behave the same on both: PostgreSQL treats NULLs as distinct in a unique index, so the system scope would silently accumulate duplicate rows. The concurrency test found a real defect: PostgreSQL's CREATE TABLE IF NOT EXISTS is not safe to run concurrently - it still races on the table's implicit row type and raises 23505. Both stores now serialise creation in process and tolerate the cross-process race, which no in-process lock covers. Azure Storage and MongoDB still ship no durable checkpoint store. --- docs/wiki/Guarantees-and-Limitations.md | 13 +- docs/wiki/Provider-Feature-Matrix.md | 4 +- docs/wiki/Subscriptions.md | 52 +++-- skills/event-sourcing-subscriptions/SKILL.md | 41 ++-- .../ServiceCollectionExtensions.cs | 13 +- .../EventStoreAggregateStreamDiscovery.cs | 28 +++ .../QueryableAggregateStreamDiscovery.cs | 28 --- .../SubscriptionCheckpointTenantColumn.cs | 29 +++ .../InMemory/Events/IInMemoryEventStore.cs | 10 - .../InMemoryAggregateStreamDiscovery.cs | 23 --- src/src/InMemory/Events/InMemoryEventStore.cs | 6 - .../ServiceCollectionExtensions.cs | 9 - .../ServiceCollectionExtensions.cs | 35 ++++ .../PostgresSubscriptionCheckpointStore.cs | 167 +++++++++++++++ ...tgresSubscriptionCheckpointStoreOptions.cs | 38 ++++ ...criptionCheckpointStoreOptionsValidator.cs | 21 ++ .../ServiceCollectionExtensions.cs | 35 ++++ .../SqlServerSubscriptionCheckpointStore.cs | 194 ++++++++++++++++++ ...erverSubscriptionCheckpointStoreOptions.cs | 38 ++++ ...criptionCheckpointStoreOptionsValidator.cs | 21 ++ .../Subscriptions/SubscriptionTenancyTests.cs | 2 +- ...ostgresSubscriptionCheckpointStoreTests.cs | 126 ++++++++++++ ...lServerSubscriptionCheckpointStoreTests.cs | 126 ++++++++++++ 23 files changed, 939 insertions(+), 120 deletions(-) create mode 100644 src/src/EventSourcing/Subscriptions/EventStoreAggregateStreamDiscovery.cs delete mode 100644 src/src/EventSourcing/Subscriptions/QueryableAggregateStreamDiscovery.cs create mode 100644 src/src/EventSourcing/Subscriptions/SubscriptionCheckpointTenantColumn.cs delete mode 100644 src/src/InMemory/Events/InMemoryAggregateStreamDiscovery.cs create mode 100644 src/src/Postgres/Subscriptions/PostgresSubscriptionCheckpointStore.cs create mode 100644 src/src/Postgres/Subscriptions/PostgresSubscriptionCheckpointStoreOptions.cs create mode 100644 src/src/Postgres/Subscriptions/PostgresSubscriptionCheckpointStoreOptionsValidator.cs create mode 100644 src/src/SqlServer/Subscriptions/SqlServerSubscriptionCheckpointStore.cs create mode 100644 src/src/SqlServer/Subscriptions/SqlServerSubscriptionCheckpointStoreOptions.cs create mode 100644 src/src/SqlServer/Subscriptions/SqlServerSubscriptionCheckpointStoreOptionsValidator.cs create mode 100644 src/tests/Postgres.IntegrationTests/Subscriptions/PostgresSubscriptionCheckpointStoreTests.cs create mode 100644 src/tests/SqlServer.IntegrationTests/Subscriptions/SqlServerSubscriptionCheckpointStoreTests.cs diff --git a/docs/wiki/Guarantees-and-Limitations.md b/docs/wiki/Guarantees-and-Limitations.md index 0c5c041e..939c9f2d 100644 --- a/docs/wiki/Guarantees-and-Limitations.md +++ b/docs/wiki/Guarantees-and-Limitations.md @@ -169,11 +169,14 @@ Not guaranteed, and not configurable: - **No dead-letter path.** A subscriber that throws stops that stream at the failing event and retries it every cycle, indefinitely. This is fail-closed by choice: skipping would lose data silently. An unresolvable event type is not a failure - it is delivered with `IsUnresolved` set and skipped past. -- **No durable checkpoint store ships.** The default is in-memory and replays every stream after a - restart. -- **Cosmos DB cannot be subscribed to** (no event stream), and **Azure Storage ships no stream discovery** - (no queryable snapshot store), so subscriptions need a supplied `IAggregateStreamDiscovery` there. -- Discovery over a queryable snapshot store finds only **snapshotted** aggregates. +- **Durable checkpoints ship for SQL Server and PostgreSQL only** (`AddSqlServerSubscriptionCheckpoints`, + `AddPostgresSubscriptionCheckpoints`). Elsewhere the default is in-memory and replays every stream after + a restart. +- **Cosmos DB cannot be subscribed to** — it persists no event stream. Every other provider works, because + stream discovery reads `IEventStoreCore.GetAggregateIdsAsync`, which every store implements and + tenant-filters. +- **Every cycle enumerates every stream** of the aggregate type: the work is linear in the number of + aggregates, not the number of new events. With no global sequence there is nothing cheaper to read. Subscriptions are deliberately absent from `EventStoreCapabilities`: whether one can run depends on the registered discovery implementation, which is dependency-injection state rather than a property of the diff --git a/docs/wiki/Provider-Feature-Matrix.md b/docs/wiki/Provider-Feature-Matrix.md index eedd2bbd..0279e307 100644 --- a/docs/wiki/Provider-Feature-Matrix.md +++ b/docs/wiki/Provider-Feature-Matrix.md @@ -16,8 +16,8 @@ per-registration values. | Blob-backed snapshots / large payloads | No | No | No | Yes | No | No | | Provider-neutral transaction guarantee | Explicit `BestEffort` or required `Atomic` | Atomic within one database boundary | Atomic within one database boundary | Best effort | Best effort | Best effort | | Transactional outbox (atomic with events) | No | Yes (`AddSqlServerOutbox`) | Yes (`AddPostgresOutbox`) | No | No | No | -| [Subscriptions](Subscriptions.md) (catch-up over the event stream) | Contracts + `AddEventSubscription` | Yes, via snapshot-store discovery | Yes, via snapshot-store discovery | Needs a supplied `IAggregateStreamDiscovery` | Yes, via snapshot-store discovery | No (no event stream) | -| Durable subscription checkpoints | In-memory only (replays after restart) | Not provided | Not provided | Not provided | Not provided | n/a | +| [Subscriptions](Subscriptions.md) (catch-up over the event stream) | Contracts + `AddEventSubscription` | Yes | Yes | Yes | Yes | No (no event stream) | +| Durable subscription checkpoints | In-memory only (replays after restart) | `AddSqlServerSubscriptionCheckpoints()` | `AddPostgresSubscriptionCheckpoints()` | Not provided | Not provided | n/a | | Event-stream retention / pruning | No | No | No | No | No | n/a | | Provider-specific native transaction factory | No | `ISqlServerEventStoreTransactionFactory` | `IPostgresEventStoreTransactionFactory` | No | No | No | | Runtime-configured JSON payload indexes | No | Yes (event + snapshot stores, auto-create path) | Yes (GIN + expression indexes on event + snapshot stores) | No | No | Yes (container indexing policy, including composite and spatial paths) | diff --git a/docs/wiki/Subscriptions.md b/docs/wiki/Subscriptions.md index 745b6bde..be098ebb 100644 --- a/docs/wiki/Subscriptions.md +++ b/docs/wiki/Subscriptions.md @@ -74,16 +74,18 @@ an event contract must not have every later event in the stream blocked by it. ## Stream discovery -Event streams are keyed by aggregate id, and no provider holds an index of "every stream that -exists". Discovery is therefore a seam, `IAggregateStreamDiscovery`: +The default is `EventStoreAggregateStreamDiscovery`, over +`IEventStoreCore.GetAggregateIdsAsync`. Every store implements that method and filters it by the +current tenant, so **discovery works on every provider that persists an event stream**, with no +snapshot store involved. -| Provider | Discovery | -| --- | --- | -| InMemory | `InMemoryAggregateStreamDiscovery`, registered automatically. Exact — it enumerates the streams the store holds | -| SQL Server, PostgreSQL, MongoDB, Cosmos DB | `QueryableAggregateStreamDiscovery`, the default. **Requires a queryable snapshot store**, and finds only aggregates that have been snapshotted | -| Azure Storage | **No implementation.** It has no queryable snapshot store, so supply your own `IAggregateStreamDiscovery` | +Deleted aggregates are included: a subscription that stopped seeing a stream the moment it was +deleted would never deliver the `Deleted` event, so a projection could not learn the aggregate had +gone. -Register your own before calling `AddEventSubscription` and it will be used instead of the default. +It enumerates **every** stream of that aggregate type each cycle, which is the cost of having no +global sequence to read instead. Supply your own `IAggregateStreamDiscovery` to narrow it — to +the aggregates changed since a watermark, say — by registering it before `AddEventSubscription`. > An implementation must honour the current tenant. The event read is filtered too, so a leaky > discovery will not deliver another tenant's *events* — but aggregate ids are themselves data, and @@ -97,15 +99,33 @@ aggregate. The tenant is part of `SubscriptionCheckpointKey` rather than somethi trusted to apply, so a position cannot be written without stating which tenant it belongs to. The default registration is `InMemorySubscriptionCheckpointStore`, which **loses every position on -restart** and therefore replays all streams. That is fine for tests and local development. A -deployed application should register a durable store: +restart** and therefore replays all streams. That is fine for tests and local development; a +deployed application should register a durable store before `AddEventSubscription`: ```csharp -services.AddSingleton(); +services.AddSqlServerEventStore(); +services.AddSqlServerSubscriptionCheckpoints(); // or AddPostgresSubscriptionCheckpoints() services.AddEventSubscription(); ``` -No provider ships a durable checkpoint store yet. +| Provider | Durable checkpoints | +| --- | --- | +| SQL Server | `AddSqlServerSubscriptionCheckpoints()` | +| PostgreSQL | `AddPostgresSubscriptionCheckpoints()` | +| Azure Storage, MongoDB, Cosmos DB | Not provided — supply an `ISubscriptionCheckpointStore` | + +Both SQL stores create their table on first use (`AutoCreateTable`, on by default) and are +configured from `EventStore:SqlServer:Subscriptions` / `EventStore:Postgres:Subscriptions`. They +fall back to the event-store connection string when none is given. + +The scope is stored in a single non-null `TenantId` column, with the system scope encoded as the +empty string by `SubscriptionCheckpointTenantColumn`. That is shared rather than per-provider +because the encoding has to be identical everywhere, and because a nullable column would behave +differently between the two engines — PostgreSQL treats NULLs as distinct in a unique index, which +would silently allow duplicate system-scope rows. + +A position never moves backwards: a cycle that re-read an earlier range cannot rewind a position +that is already further on, which would redeliver everything in between. ## Configuration @@ -124,12 +144,14 @@ services.AddEventSubscription(options => options.PollInt - **No global ordering**, and no ordered live tail. Both are discussed in [the design page](Subscriptions-And-Retention-Design.md). -- **No durable checkpoint store ships with any provider.** -- **Azure Storage has no discovery implementation**, so subscriptions do not work there without one. +- **Durable checkpoints ship for SQL Server and PostgreSQL only.** Azure Storage, MongoDB and an + InMemory deployment replay every stream after a restart unless you supply a store. - **Cosmos DB cannot be subscribed to at all** — it persists no event stream, and `RunCycleAsync` throws `NotSupportedException`. - **A permanently failing event stalls its stream.** There is no dead-letter path. -- Discovery over a queryable snapshot store only finds **snapshotted** aggregates. +- **Every cycle enumerates every stream** of the aggregate type. There is no global sequence to read + instead, so this is linear in the number of aggregates rather than in the number of new events. + Supply a narrower `IAggregateStreamDiscovery` if that is too expensive. - The in-memory event store keeps its data per instance and is registered transient, so a subscription over it must resolve the same instance — register it as a singleton. - Subscriptions are not reported through `EventStoreCapabilities`. Whether one can run depends on diff --git a/skills/event-sourcing-subscriptions/SKILL.md b/skills/event-sourcing-subscriptions/SKILL.md index 2f4a42c5..14e22e2c 100644 --- a/skills/event-sourcing-subscriptions/SKILL.md +++ b/skills/event-sourcing-subscriptions/SKILL.md @@ -60,23 +60,22 @@ So a projection keyed by aggregate id is safe. A projection that depends on the two *different* aggregates' events is not, and no option will make it so. Model it as a single aggregate instead, or accept eventual convergence. -## Stream discovery is a seam, and it must be tenant-filtered +## Stream discovery, and why a custom one is usually a mistake -No provider holds an index of every stream, so discovery is supplied per provider: +The default reads `IEventStoreCore.GetAggregateIdsAsync`, which every store implements and +filters by the current tenant. It works on every provider with an event stream - no snapshot store, +no provider-specific wiring. -- **InMemory** - automatic and exact. -- **SQL Server, PostgreSQL, MongoDB, Cosmos DB** - the queryable default, which needs a snapshot - store and finds only **snapshotted** aggregates. An aggregate saved under a snapshot strategy that - has not written one yet is invisible to the subscription. -- **Azure Storage** - none ships. Supply your own or subscriptions will not run. +The cost: **every cycle enumerates every stream** of that aggregate type, so the work is linear in +the number of aggregates, not in the number of new events. With no global sequence there is nothing +cheaper to read. If that is too expensive, register your own `IAggregateStreamDiscovery` before +`AddEventSubscription` to narrow it - aggregates changed since a watermark, for instance. -Register yours before `AddEventSubscription` and it wins over the default. - -**A discovery implementation that ignores the current tenant leaks.** The trap is that it will not -look like a leak: the event read is filtered too, so no cross-tenant *events* are delivered, and any -test that only asserts "the other tenant's subscriber received nothing" passes. Aggregate ids are -data. Assert on what discovery returns, not on what arrives - see `SubscriptionTenancyTests`, where -removing the discovery filter fails two tests and the acceptance scenarios stay green. +**If you do write one, it must honour the current tenant.** The trap is that a leak will not look +like one: the event read is filtered too, so no cross-tenant *events* are delivered, and any test +that only asserts "the other tenant's subscriber received nothing" passes. Aggregate ids are data. +Assert on what discovery returns, not on what arrives - in `SubscriptionTenancyTests`, removing the +filter fails two tests while every acceptance scenario stays green. ## Checkpoints are per tenant, structurally @@ -88,7 +87,19 @@ events and those events would **never** be delivered - a silent, permanent gap r visible error. The default checkpoint store is in-memory and loses every position on restart, replaying all -streams. Register a durable one in anything deployed. No provider ships one yet. +streams. Register a durable one in anything deployed, **before** `AddEventSubscription`: + +```csharp +services.AddSqlServerSubscriptionCheckpoints(); // or AddPostgresSubscriptionCheckpoints() +services.AddEventSubscription(); +``` + +Only SQL Server and PostgreSQL ship one. On Azure Storage or MongoDB you must supply an +`ISubscriptionCheckpointStore` yourself, or accept a full replay on every restart. + +If you write one, encode the scope with `SubscriptionCheckpointTenantColumn` rather than inventing +your own, and do not use a nullable tenant column: PostgreSQL treats NULLs as distinct in a unique +index, so the system scope would silently get duplicate rows. ## Failure stalls the stream, on purpose diff --git a/src/src/EventSourcing/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/EventSourcing/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs index 9aa8d852..7520ab58 100644 --- a/src/src/EventSourcing/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs +++ b/src/src/EventSourcing/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -107,9 +107,10 @@ public IServiceCollection AddOutbox( /// application. /// /// - /// Stream discovery defaults to , which needs a - /// queryable snapshot store. Register an before calling - /// this to use a provider-specific implementation instead. + /// Stream discovery defaults to , which works on + /// every provider that persists an event stream. Register an + /// before calling this to narrow it - for example to the + /// aggregates changed since a watermark, rather than all of them. /// /// public IServiceCollection AddEventSubscription( @@ -120,8 +121,8 @@ public IServiceCollection AddEventSubscription( { services.TryAddScoped, TSubscriber>(); services.TryAddSingleton(); - // TryAdd compares service types exactly, so a closed-generic TryAdd would not see a - // provider's open-generic registration and would win by being registered last. + // TryAdd compares service types exactly, so it would not see an open-generic registration + // supplied by a provider or a consumer; check both shapes before adding the default. var hasDiscovery = services.Any(descriptor => descriptor.ServiceType == typeof(IAggregateStreamDiscovery) || descriptor.ServiceType == typeof(IAggregateStreamDiscovery<>) @@ -130,7 +131,7 @@ public IServiceCollection AddEventSubscription( { services.AddScoped< IAggregateStreamDiscovery, - QueryableAggregateStreamDiscovery + EventStoreAggregateStreamDiscovery >(); } services.TryAddScoped, EventSubscriptionProcessor>(); diff --git a/src/src/EventSourcing/Subscriptions/EventStoreAggregateStreamDiscovery.cs b/src/src/EventSourcing/Subscriptions/EventStoreAggregateStreamDiscovery.cs new file mode 100644 index 00000000..0d92812a --- /dev/null +++ b/src/src/EventSourcing/Subscriptions/EventStoreAggregateStreamDiscovery.cs @@ -0,0 +1,28 @@ +using Purview.EventSourcing.Aggregates; + +namespace Purview.EventSourcing.Subscriptions; + +/// +/// The default , over +/// . +/// +/// +/// +/// Every store implements that method and filters it by the current tenant, so this works on every +/// provider that persists an event stream, with no snapshot store required. +/// +/// +/// Deleted aggregates are included. A subscription that stopped seeing a stream the moment it was +/// deleted would never deliver the Deleted event, so a projection could not learn that the +/// aggregate had gone. +/// +/// +/// The aggregate type to discover streams for. +/// The store to enumerate. +public sealed class EventStoreAggregateStreamDiscovery(IEventStoreCore eventStore) : IAggregateStreamDiscovery + where T : class, IAggregate, new() +{ + /// + public IAsyncEnumerable GetAggregateIdsAsync(CancellationToken cancellationToken) => + eventStore.GetAggregateIdsAsync(includeDeleted: true, cancellationToken); +} diff --git a/src/src/EventSourcing/Subscriptions/QueryableAggregateStreamDiscovery.cs b/src/src/EventSourcing/Subscriptions/QueryableAggregateStreamDiscovery.cs deleted file mode 100644 index df692d1b..00000000 --- a/src/src/EventSourcing/Subscriptions/QueryableAggregateStreamDiscovery.cs +++ /dev/null @@ -1,28 +0,0 @@ -using System.Runtime.CompilerServices; -using Purview.EventSourcing.Aggregates; - -namespace Purview.EventSourcing.Subscriptions; - -/// -/// Discovers streams by enumerating the queryable snapshot store. -/// -/// -/// The snapshot store is already tenant-filtered, so the enumeration inherits that filtering. Only -/// aggregates that have been snapshotted are found: a provider configured with a snapshot strategy -/// that has not yet written one will not surface that aggregate to a subscription until it does. -/// -/// The aggregate type to discover streams for. -/// The queryable store to enumerate. -public sealed class QueryableAggregateStreamDiscovery(IQueryableEventStoreCore eventStore) - : IAggregateStreamDiscovery - where T : class, IAggregate, new() -{ - /// - public async IAsyncEnumerable GetAggregateIdsAsync( - [EnumeratorCancellation] CancellationToken cancellationToken - ) - { - await foreach (var aggregate in eventStore.GetListEnumerableAsync(null, cancellationToken: cancellationToken)) - yield return aggregate.Id(); - } -} diff --git a/src/src/EventSourcing/Subscriptions/SubscriptionCheckpointTenantColumn.cs b/src/src/EventSourcing/Subscriptions/SubscriptionCheckpointTenantColumn.cs new file mode 100644 index 00000000..8da47bae --- /dev/null +++ b/src/src/EventSourcing/Subscriptions/SubscriptionCheckpointTenantColumn.cs @@ -0,0 +1,29 @@ +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.Subscriptions; + +/// +/// Encodes a into the single non-null column a checkpoint store keys on. +/// +/// +/// +/// Shared so every provider encodes the scope identically. A store that invented its own encoding +/// could make one tenant's position collide with another's, or with the system scope's, which would +/// advance a position past events that are then never delivered. +/// +/// +/// The system scope encodes as the empty string. That cannot collide with a real tenant, because +/// rejects a blank identifier. Keeping the column non-null +/// also keeps the unique index free of NULLs, which matters because SQL Server and PostgreSQL +/// disagree about whether NULLs are distinct in a unique index. +/// +/// +public static class SubscriptionCheckpointTenantColumn +{ + /// The value stored for . + public const string SystemValue = ""; + + /// Encodes a scope for storage. + /// The scope to encode. + public static string Encode(TenantScope scope) => scope.IsSystem ? SystemValue : scope.TenantId!; +} diff --git a/src/src/InMemory/Events/IInMemoryEventStore.cs b/src/src/InMemory/Events/IInMemoryEventStore.cs index bd07eac7..6c6f8b97 100644 --- a/src/src/InMemory/Events/IInMemoryEventStore.cs +++ b/src/src/InMemory/Events/IInMemoryEventStore.cs @@ -22,14 +22,4 @@ public interface IInMemoryEventStore : INonQueryableEventStore, IAggregate /// A token that can be used to cancel the operation. /// A task that completes when the store has been cleared. Task ClearAsync(CancellationToken cancellationToken = default); - - /// - /// Enumerates the ids of the streams visible to the current tenant. - /// - /// A token that can be used to cancel the operation. - /// - /// This store has no queryable snapshot reads, so it supplies its own stream discovery for - /// subscriptions rather than using the queryable default. - /// - IAsyncEnumerable GetAggregateIdsAsync(CancellationToken cancellationToken = default); } diff --git a/src/src/InMemory/Events/InMemoryAggregateStreamDiscovery.cs b/src/src/InMemory/Events/InMemoryAggregateStreamDiscovery.cs deleted file mode 100644 index 3b722b86..00000000 --- a/src/src/InMemory/Events/InMemoryAggregateStreamDiscovery.cs +++ /dev/null @@ -1,23 +0,0 @@ -using Purview.EventSourcing.Aggregates; -using Purview.EventSourcing.Subscriptions; - -namespace Purview.EventSourcing.InMemory.Events; - -/// -/// Discovers streams directly from the in-memory store. -/// -/// -/// The in-memory store has no queryable snapshot reads, so the queryable default cannot be used. It -/// does hold every stream it has written, which makes discovery exact rather than dependent on a -/// snapshot having been taken. -/// -/// The aggregate type to discover streams for. -/// The store to enumerate. -public sealed class InMemoryAggregateStreamDiscovery(IInMemoryEventStore eventStore) - : IAggregateStreamDiscovery - where T : class, IAggregate, new() -{ - /// - public IAsyncEnumerable GetAggregateIdsAsync(CancellationToken cancellationToken) => - eventStore.GetAggregateIdsAsync(cancellationToken); -} diff --git a/src/src/InMemory/Events/InMemoryEventStore.cs b/src/src/InMemory/Events/InMemoryEventStore.cs index a118b2d2..f6789c3a 100644 --- a/src/src/InMemory/Events/InMemoryEventStore.cs +++ b/src/src/InMemory/Events/InMemoryEventStore.cs @@ -351,12 +351,6 @@ CancellationToken cancellationToken return matched.ToAsyncEnumerable(); } - /// - public IAsyncEnumerable GetAggregateIdsAsync(CancellationToken cancellationToken = default) => - // Filtered the same way every read is: an unowned stream is visible only to the system scope, - // so discovery cannot hand one tenant's aggregate ids to another. - _events.Keys.Where(IsVisible).ToArray().ToAsyncEnumerable(); - /// public async Task> GetOrCreateAsync( string? aggregateId, diff --git a/src/src/InMemory/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/InMemory/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs index 9b04a756..e372a56f 100644 --- a/src/src/InMemory/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs +++ b/src/src/InMemory/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -2,7 +2,6 @@ using Purview.EventSourcing.InMemory.Events; using Purview.EventSourcing.InMemory.Snapshots; using Purview.EventSourcing.Internal; -using Purview.EventSourcing.Subscriptions; namespace Microsoft.Extensions.DependencyInjection; @@ -38,10 +37,6 @@ public IServiceCollection AddInMemoryEventStore() .AddTransient(typeof(IInMemoryEventStore<>), typeof(InMemoryEventStore<>)) .AddTransient(); - // Registered ahead of AddEventSubscription's TryAdd default, which needs a queryable - // snapshot store this provider does not have. - services.AddTransient(typeof(IAggregateStreamDiscovery<>), typeof(InMemoryAggregateStreamDiscovery<>)); - services.AddEventStoreCapabilities( new EventStoreCapabilities( EventStoreTransactionGuarantee.BestEffort, @@ -88,10 +83,6 @@ public IServiceCollection AddInMemorySnapshotEventStore() .AddTransient() .AddTransient(); - // Registered ahead of AddEventSubscription's TryAdd default, which needs a queryable - // snapshot store this provider does not have. - services.AddTransient(typeof(IAggregateStreamDiscovery<>), typeof(InMemoryAggregateStreamDiscovery<>)); - services.AddEventStoreCapabilities( new EventStoreCapabilities( EventStoreTransactionGuarantee.BestEffort, diff --git a/src/src/Postgres/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/Postgres/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs index 4702e506..64dd6535 100644 --- a/src/src/Postgres/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs +++ b/src/src/Postgres/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -8,6 +8,8 @@ using Purview.EventSourcing.Postgres.Outbox; using Purview.EventSourcing.Postgres.Snapshot; using Purview.EventSourcing.Postgres.Snapshots; +using Purview.EventSourcing.Postgres.Subscriptions; +using Purview.EventSourcing.Subscriptions; namespace Microsoft.Extensions.DependencyInjection; @@ -224,5 +226,38 @@ public IServiceCollection AddPostgresOutbox(Action + /// Registers the PostgreSQL subscription checkpoint store, so subscription positions survive a + /// restart. + /// + /// The for chaining. + /// + /// Call this before AddEventSubscription. Without a durable checkpoint store the default + /// in-memory one is used, and every subscription replays every stream from the beginning after a + /// restart. + /// + public IServiceCollection AddPostgresSubscriptionCheckpoints() + { + services.TryAddSingleton(); + + services + .AddOptions() + .Configure( + (options, configuration) => + configuration + .GetSection(PostgresSubscriptionCheckpointStoreOptions.PostgresSubscriptions) + .Bind(options) + ); + + services.TryAddEnumerable( + ServiceDescriptor.Singleton< + IValidateOptions, + PostgresSubscriptionCheckpointStoreOptionsValidator + >() + ); + + return services; + } } } diff --git a/src/src/Postgres/Subscriptions/PostgresSubscriptionCheckpointStore.cs b/src/src/Postgres/Subscriptions/PostgresSubscriptionCheckpointStore.cs new file mode 100644 index 00000000..b12a6130 --- /dev/null +++ b/src/src/Postgres/Subscriptions/PostgresSubscriptionCheckpointStore.cs @@ -0,0 +1,167 @@ +using System.Text.RegularExpressions; +using Microsoft.Extensions.Options; +using Npgsql; +using Purview.EventSourcing.Postgres.Events; +using Purview.EventSourcing.Subscriptions; + +namespace Purview.EventSourcing.Postgres.Subscriptions; + +// SQL strings are built from validated identifiers at construction time, not from user input. +#pragma warning disable CA2100 + +/// +/// A durable backed by a PostgreSQL table. +/// +/// +/// Without a durable store every subscription replays every stream after a restart, so this is what +/// makes a subscription usable in a deployed application. +/// +public sealed partial class PostgresSubscriptionCheckpointStore( + IOptions checkpointOptions, + IOptions eventStoreOptions +) : ISubscriptionCheckpointStore, IDisposable +{ + [GeneratedRegex("^[\\w\\-.]+$", RegexOptions.Compiled)] + private static partial Regex ValidIdentifier(); + + readonly string _connectionString = ResolveConnectionString(checkpointOptions.Value, eventStoreOptions.Value); + readonly string _schema = QuoteIdentifier(checkpointOptions.Value.SchemaName); + readonly string _table = QuoteIdentifier(checkpointOptions.Value.TableName); + readonly SemaphoreSlim _schemaLock = new(1, 1); + bool _schemaEnsured; + + /// + public async Task GetAsync(SubscriptionCheckpointKey key, CancellationToken cancellationToken) + { + await EnsureSchemaAsync(cancellationToken); + + await using NpgsqlConnection connection = new(_connectionString); + await connection.OpenAsync(cancellationToken); + + await using NpgsqlCommand command = new( + $""" + SELECT "Version" FROM {_schema}.{_table} + WHERE "SubscriptionName" = @name AND "TenantId" = @tenantId AND "AggregateId" = @aggregateId + """, + connection + ); + AddKeyParameters(command, key); + + var result = await command.ExecuteScalarAsync(cancellationToken); + + return result is null or DBNull ? null : Convert.ToInt64(result, provider: null); + } + + /// + public async Task SetAsync(SubscriptionCheckpointKey key, long version, CancellationToken cancellationToken) + { + await EnsureSchemaAsync(cancellationToken); + + await using NpgsqlConnection connection = new(_connectionString); + await connection.OpenAsync(cancellationToken); + + // The DO UPDATE is guarded so a cycle that re-read an earlier range cannot rewind a position + // that is already further on, which would redeliver everything in between. + await using NpgsqlCommand command = new( + $""" + INSERT INTO {_schema}.{_table} + ("SubscriptionName", "TenantId", "AggregateId", "Version", "UpdatedUtc") + VALUES (@name, @tenantId, @aggregateId, @version, @now) + ON CONFLICT ("SubscriptionName", "TenantId", "AggregateId") DO UPDATE + SET "Version" = EXCLUDED."Version", "UpdatedUtc" = EXCLUDED."UpdatedUtc" + WHERE {_table}."Version" < EXCLUDED."Version" + """, + connection + ); + AddKeyParameters(command, key); + command.Parameters.AddWithValue("@version", version); + command.Parameters.AddWithValue("@now", DateTimeOffset.UtcNow); + + await command.ExecuteNonQueryAsync(cancellationToken); + } + + static void AddKeyParameters(NpgsqlCommand command, SubscriptionCheckpointKey key) + { + command.Parameters.AddWithValue("@name", key.SubscriptionName); + command.Parameters.AddWithValue("@tenantId", SubscriptionCheckpointTenantColumn.Encode(key.Scope)); + command.Parameters.AddWithValue("@aggregateId", key.AggregateId); + } + + async Task EnsureSchemaAsync(CancellationToken cancellationToken) + { + if (_schemaEnsured) + return; + + if (checkpointOptions.Value.AutoCreateTable) + { + // CREATE TABLE IF NOT EXISTS is not safe to run concurrently: PostgreSQL still races on + // the table's implicit row type and raises 23505 on pg_type_typname_nsp_index. The + // semaphore serialises callers in this process; the catch covers a second process, which + // no in-process lock can. + await _schemaLock.WaitAsync(cancellationToken); + try + { + if (_schemaEnsured) + return; + + await using NpgsqlConnection connection = new(_connectionString); + await connection.OpenAsync(cancellationToken); + + // "TenantId" is NOT NULL and encodes the system scope as an empty string. PostgreSQL + // treats NULLs as distinct in a unique index before NULLS NOT DISTINCT (15+), so a + // nullable tenant column would silently allow duplicate system-scope rows. + await using NpgsqlCommand command = new( + $""" + CREATE TABLE IF NOT EXISTS {_schema}.{_table} ( + "SubscriptionName" VARCHAR(256) NOT NULL, + "TenantId" VARCHAR(256) NOT NULL, + "AggregateId" VARCHAR(256) NOT NULL, + "Version" BIGINT NOT NULL, + "UpdatedUtc" TIMESTAMPTZ NOT NULL, + PRIMARY KEY ("SubscriptionName", "TenantId", "AggregateId") + ); + """, + connection + ); + + try + { + await command.ExecuteNonQueryAsync(cancellationToken); + } + catch (PostgresException ex) when (ex.SqlState is "23505" or "42P07") + { + // Another writer created it first, which is the outcome we wanted anyway. + } + } + finally + { + _schemaLock.Release(); + } + } + + _schemaEnsured = true; + } + + static string ResolveConnectionString( + PostgresSubscriptionCheckpointStoreOptions checkpointOptions, + PostgresEventStoreOptions eventStoreOptions + ) => + checkpointOptions.ConnectionString + ?? eventStoreOptions.ConnectionString + ?? throw new InvalidOperationException( + "PostgresSubscriptionCheckpointStore requires a connection string. Configure 'EventStore:Postgres:Subscriptions:ConnectionString' or 'EventStore:Postgres:ConnectionString'." + ); + + /// + public void Dispose() => _schemaLock.Dispose(); + + static string QuoteIdentifier(string identifier) + { + if (!ValidIdentifier().IsMatch(identifier)) + throw new InvalidOperationException( + $"The subscription checkpoint table identifier '{identifier}' is invalid. Identifiers may only contain letters, digits, underscores, dots, and hyphens." + ); + + return $"\"{identifier}\""; + } +} diff --git a/src/src/Postgres/Subscriptions/PostgresSubscriptionCheckpointStoreOptions.cs b/src/src/Postgres/Subscriptions/PostgresSubscriptionCheckpointStoreOptions.cs new file mode 100644 index 00000000..e8d6146a --- /dev/null +++ b/src/src/Postgres/Subscriptions/PostgresSubscriptionCheckpointStoreOptions.cs @@ -0,0 +1,38 @@ +using System.ComponentModel.DataAnnotations; + +namespace Purview.EventSourcing.Postgres.Subscriptions; + +/// +/// Options that configure the PostgreSQL subscription checkpoint store. +/// +/// +/// Bound from the EventStore:Postgres:Subscriptions configuration section. When +/// is not supplied, the event-store connection string is used. +/// +public sealed class PostgresSubscriptionCheckpointStoreOptions +{ + /// The configuration section name used to bind these options. + public const string PostgresSubscriptions = "EventStore:Postgres:Subscriptions"; + + /// The default table name used to persist subscription positions. + public const string DefaultTableName = "EventStoreSubscriptionCheckpoints"; + + /// + /// The connection string used to access the PostgreSQL database. When null, the event-store + /// connection string is used. + /// + public string? ConnectionString { get; set; } + + /// The schema that owns the checkpoint table. + [Required(AllowEmptyStrings = false)] + [RegularExpression(@"^[\w\-.]+$")] + public string SchemaName { get; set; } = "public"; + + /// The name of the table that stores subscription positions. + [Required(AllowEmptyStrings = false)] + [RegularExpression(@"^[\w\-.]+$")] + public string TableName { get; set; } = DefaultTableName; + + /// When true, the checkpoint table is created if it does not exist. + public bool AutoCreateTable { get; set; } = true; +} diff --git a/src/src/Postgres/Subscriptions/PostgresSubscriptionCheckpointStoreOptionsValidator.cs b/src/src/Postgres/Subscriptions/PostgresSubscriptionCheckpointStoreOptionsValidator.cs new file mode 100644 index 00000000..8bada879 --- /dev/null +++ b/src/src/Postgres/Subscriptions/PostgresSubscriptionCheckpointStoreOptionsValidator.cs @@ -0,0 +1,21 @@ +using System.ComponentModel.DataAnnotations; +using Microsoft.Extensions.Options; + +namespace Purview.EventSourcing.Postgres.Subscriptions; + +sealed class PostgresSubscriptionCheckpointStoreOptionsValidator + : IValidateOptions +{ + public ValidateOptionsResult Validate(string? name, PostgresSubscriptionCheckpointStoreOptions options) + { + ArgumentNullException.ThrowIfNull(options); + ValidationContext validationContext = new(options); + List validationResults = []; + if (!Validator.TryValidateObject(options, validationContext, validationResults, validateAllProperties: true)) + return ValidateOptionsResult.Fail( + validationResults.Select(static x => x.ErrorMessage ?? "Options validation failed.") + ); + + return ValidateOptionsResult.Success; + } +} diff --git a/src/src/SqlServer/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/SqlServer/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs index a3014a71..4d42ac78 100644 --- a/src/src/SqlServer/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs +++ b/src/src/SqlServer/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -8,6 +8,8 @@ using Purview.EventSourcing.SqlServer.Outbox; using Purview.EventSourcing.SqlServer.Snapshot; using Purview.EventSourcing.SqlServer.Snapshots; +using Purview.EventSourcing.SqlServer.Subscriptions; +using Purview.EventSourcing.Subscriptions; namespace Microsoft.Extensions.DependencyInjection; @@ -232,5 +234,38 @@ public IServiceCollection AddSqlServerOutbox(Action + /// Registers the SQL Server subscription checkpoint store, so subscription positions survive a + /// restart. + /// + /// The for chaining. + /// + /// Call this before AddEventSubscription. Without a durable checkpoint store the default + /// in-memory one is used, and every subscription replays every stream from the beginning after a + /// restart. + /// + public IServiceCollection AddSqlServerSubscriptionCheckpoints() + { + services.TryAddSingleton(); + + services + .AddOptions() + .Configure( + (options, configuration) => + configuration + .GetSection(SqlServerSubscriptionCheckpointStoreOptions.SqlServerSubscriptions) + .Bind(options) + ); + + services.TryAddEnumerable( + ServiceDescriptor.Singleton< + IValidateOptions, + SqlServerSubscriptionCheckpointStoreOptionsValidator + >() + ); + + return services; + } } } diff --git a/src/src/SqlServer/Subscriptions/SqlServerSubscriptionCheckpointStore.cs b/src/src/SqlServer/Subscriptions/SqlServerSubscriptionCheckpointStore.cs new file mode 100644 index 00000000..c6d3ef5c --- /dev/null +++ b/src/src/SqlServer/Subscriptions/SqlServerSubscriptionCheckpointStore.cs @@ -0,0 +1,194 @@ +using System.Text.RegularExpressions; +using Microsoft.Data.SqlClient; +using Microsoft.Extensions.Options; +using Purview.EventSourcing.SqlServer.Events; +using Purview.EventSourcing.Subscriptions; + +namespace Purview.EventSourcing.SqlServer.Subscriptions; + +// SQL strings are built from validated identifiers at construction time, not from user input. +#pragma warning disable CA2100 + +/// +/// A durable backed by a SQL Server table. +/// +/// +/// Without a durable store every subscription replays every stream after a restart, so this is what +/// makes a subscription usable in a deployed application. +/// +public sealed partial class SqlServerSubscriptionCheckpointStore( + IOptions checkpointOptions, + IOptions eventStoreOptions +) : ISubscriptionCheckpointStore, IDisposable +{ + [GeneratedRegex("^[\\w\\-.]+$", RegexOptions.Compiled)] + private static partial Regex ValidIdentifier(); + + readonly string _connectionString = ResolveConnectionString(checkpointOptions.Value, eventStoreOptions.Value); + readonly string _schema = QuoteIdentifier(checkpointOptions.Value.SchemaName); + readonly string _table = QuoteIdentifier(checkpointOptions.Value.TableName); + readonly SemaphoreSlim _schemaLock = new(1, 1); + bool _schemaEnsured; + + /// + public async Task GetAsync(SubscriptionCheckpointKey key, CancellationToken cancellationToken) + { + await EnsureSchemaAsync(cancellationToken); + + await using SqlConnection connection = new(_connectionString); + await connection.OpenAsync(cancellationToken); + + await using SqlCommand command = new( + $""" + SELECT [Version] FROM {_schema}.{_table} + WHERE [SubscriptionName] = @name AND [TenantId] = @tenantId AND [AggregateId] = @aggregateId + """, + connection + ); + AddKeyParameters(command, key); + + var result = await command.ExecuteScalarAsync(cancellationToken); + + return result is null or DBNull ? null : Convert.ToInt64(result, provider: null); + } + + /// + public async Task SetAsync(SubscriptionCheckpointKey key, long version, CancellationToken cancellationToken) + { + await EnsureSchemaAsync(cancellationToken); + + await using SqlConnection connection = new(_connectionString); + await connection.OpenAsync(cancellationToken); + + // The UPDATE is guarded by [Version] < @version so a cycle that re-read an earlier range + // cannot rewind a position that is already further on, which would redeliver everything in + // between. The INSERT races another writer creating the same row; losing that race is + // swallowed, because the worst outcome is a position that is behind, and a position behind + // redelivers rather than skips. + await using SqlCommand command = new( + $""" + UPDATE {_schema}.{_table} + SET [Version] = @version, [UpdatedUtc] = @now + WHERE [SubscriptionName] = @name AND [TenantId] = @tenantId AND [AggregateId] = @aggregateId + AND [Version] < @version; + + IF @@ROWCOUNT = 0 AND NOT EXISTS ( + SELECT 1 FROM {_schema}.{_table} + WHERE [SubscriptionName] = @name AND [TenantId] = @tenantId AND [AggregateId] = @aggregateId + ) + BEGIN + BEGIN TRY + INSERT INTO {_schema}.{_table} + ([SubscriptionName], [TenantId], [AggregateId], [Version], [UpdatedUtc]) + VALUES (@name, @tenantId, @aggregateId, @version, @now); + END TRY + BEGIN CATCH + IF ERROR_NUMBER() NOT IN (2601, 2627) THROW; + END CATCH + END + """, + connection + ); + AddKeyParameters(command, key); + command.Parameters.AddWithValue("@version", version); + command.Parameters.AddWithValue("@now", DateTimeOffset.UtcNow); + + await command.ExecuteNonQueryAsync(cancellationToken); + } + + static void AddKeyParameters(SqlCommand command, SubscriptionCheckpointKey key) + { + command.Parameters.AddWithValue("@name", key.SubscriptionName); + command.Parameters.AddWithValue("@tenantId", SubscriptionCheckpointTenantColumn.Encode(key.Scope)); + command.Parameters.AddWithValue("@aggregateId", key.AggregateId); + } + + async Task EnsureSchemaAsync(CancellationToken cancellationToken) + { + if (_schemaEnsured) + return; + + if (checkpointOptions.Value.AutoCreateTable) + { + // IF OBJECT_ID(...) IS NULL is a check, not a lock: two callers can both pass it and + // both try to create the table. The semaphore serialises this process; the T-SQL CATCH + // below covers a second process, which no in-process lock can. + await _schemaLock.WaitAsync(cancellationToken); + try + { + if (_schemaEnsured) + return; + + await EnsureSchemaCoreAsync(cancellationToken); + } + finally + { + _schemaLock.Release(); + } + } + + _schemaEnsured = true; + } + + async Task EnsureSchemaCoreAsync(CancellationToken cancellationToken) + { + await using SqlConnection connection = new(_connectionString); + await connection.OpenAsync(cancellationToken); + + var indexName = QuoteIdentifier($"UX_{checkpointOptions.Value.TableName}_Key"); + + // [TenantId] is NOT NULL and encodes the system scope as an empty string, so the unique + // index never contains a NULL. A nullable tenant column behaves differently between SQL + // Server and PostgreSQL - PostgreSQL treats NULLs as distinct - and would silently allow + // duplicate system-scope rows there. + // + // 2714 is "object already exists": another process won the race between the OBJECT_ID check + // and the CREATE, which is the outcome we wanted anyway. + await using SqlCommand command = new( + $""" + BEGIN TRY + IF OBJECT_ID(N'{_schema}.{_table}', N'U') IS NULL + BEGIN + CREATE TABLE {_schema}.{_table} ( + [SubscriptionName] NVARCHAR(256) NOT NULL, + [TenantId] NVARCHAR(256) NOT NULL, + [AggregateId] NVARCHAR(256) NOT NULL, + [Version] BIGINT NOT NULL, + [UpdatedUtc] DATETIMEOFFSET NOT NULL + ); + CREATE UNIQUE INDEX {indexName} ON {_schema}.{_table} + ([SubscriptionName], [TenantId], [AggregateId]); + END + END TRY + BEGIN CATCH + IF ERROR_NUMBER() <> 2714 THROW; + END CATCH + """, + connection + ); + await command.ExecuteNonQueryAsync(cancellationToken); + } + + static string ResolveConnectionString( + SqlServerSubscriptionCheckpointStoreOptions checkpointOptions, + SqlServerEventStoreOptions eventStoreOptions + ) => + checkpointOptions.ConnectionString + ?? eventStoreOptions.ConnectionString + ?? throw new InvalidOperationException( + "SqlServerSubscriptionCheckpointStore requires a connection string. Configure 'EventStore:SqlServer:Subscriptions:ConnectionString' or 'EventStore:SqlServer:ConnectionString'." + ); + + /// + public void Dispose() => _schemaLock.Dispose(); + + static string QuoteIdentifier(string identifier) + { + if (!ValidIdentifier().IsMatch(identifier)) + throw new InvalidOperationException( + $"The subscription checkpoint table identifier '{identifier}' is invalid. Identifiers may only contain letters, digits, underscores, dots, and hyphens." + ); + + return $"[{identifier}]"; + } +} diff --git a/src/src/SqlServer/Subscriptions/SqlServerSubscriptionCheckpointStoreOptions.cs b/src/src/SqlServer/Subscriptions/SqlServerSubscriptionCheckpointStoreOptions.cs new file mode 100644 index 00000000..1eee1783 --- /dev/null +++ b/src/src/SqlServer/Subscriptions/SqlServerSubscriptionCheckpointStoreOptions.cs @@ -0,0 +1,38 @@ +using System.ComponentModel.DataAnnotations; + +namespace Purview.EventSourcing.SqlServer.Subscriptions; + +/// +/// Options that configure the SQL Server subscription checkpoint store. +/// +/// +/// Bound from the EventStore:SqlServer:Subscriptions configuration section. When +/// is not supplied, the event-store connection string is used. +/// +public sealed class SqlServerSubscriptionCheckpointStoreOptions +{ + /// The configuration section name used to bind these options. + public const string SqlServerSubscriptions = "EventStore:SqlServer:Subscriptions"; + + /// The default table name used to persist subscription positions. + public const string DefaultTableName = "EventStoreSubscriptionCheckpoints"; + + /// + /// The connection string used to access the SQL Server database. When null, the event-store + /// connection string is used. + /// + public string? ConnectionString { get; set; } + + /// The schema that owns the checkpoint table. + [Required(AllowEmptyStrings = false)] + [RegularExpression(@"^[\w\-.]+$")] + public string SchemaName { get; set; } = "dbo"; + + /// The name of the table that stores subscription positions. + [Required(AllowEmptyStrings = false)] + [RegularExpression(@"^[\w\-.]+$")] + public string TableName { get; set; } = DefaultTableName; + + /// When true, the checkpoint table is created if it does not exist. + public bool AutoCreateTable { get; set; } = true; +} diff --git a/src/src/SqlServer/Subscriptions/SqlServerSubscriptionCheckpointStoreOptionsValidator.cs b/src/src/SqlServer/Subscriptions/SqlServerSubscriptionCheckpointStoreOptionsValidator.cs new file mode 100644 index 00000000..0b2c7d99 --- /dev/null +++ b/src/src/SqlServer/Subscriptions/SqlServerSubscriptionCheckpointStoreOptionsValidator.cs @@ -0,0 +1,21 @@ +using System.ComponentModel.DataAnnotations; +using Microsoft.Extensions.Options; + +namespace Purview.EventSourcing.SqlServer.Subscriptions; + +sealed class SqlServerSubscriptionCheckpointStoreOptionsValidator + : IValidateOptions +{ + public ValidateOptionsResult Validate(string? name, SqlServerSubscriptionCheckpointStoreOptions options) + { + ArgumentNullException.ThrowIfNull(options); + ValidationContext validationContext = new(options); + List validationResults = []; + if (!Validator.TryValidateObject(options, validationContext, validationResults, validateAllProperties: true)) + return ValidateOptionsResult.Fail( + validationResults.Select(static x => x.ErrorMessage ?? "Options validation failed.") + ); + + return ValidateOptionsResult.Success; + } +} diff --git a/src/tests/EventSourcing.UnitTests/Subscriptions/SubscriptionTenancyTests.cs b/src/tests/EventSourcing.UnitTests/Subscriptions/SubscriptionTenancyTests.cs index 4619f05e..6a3a30a0 100644 --- a/src/tests/EventSourcing.UnitTests/Subscriptions/SubscriptionTenancyTests.cs +++ b/src/tests/EventSourcing.UnitTests/Subscriptions/SubscriptionTenancyTests.cs @@ -130,7 +130,7 @@ public async Task SeedAsync(string? tenant, string aggregateId) public async Task> DiscoverAsync(TenantScope scope) { var store = _provider.GetRequiredService>(); - InMemoryAggregateStreamDiscovery discovery = new(store); + EventStoreAggregateStreamDiscovery discovery = new(store); using (AmbientCurrentTenant.BeginScope(scope)) { diff --git a/src/tests/Postgres.IntegrationTests/Subscriptions/PostgresSubscriptionCheckpointStoreTests.cs b/src/tests/Postgres.IntegrationTests/Subscriptions/PostgresSubscriptionCheckpointStoreTests.cs new file mode 100644 index 00000000..fbe4b8a9 --- /dev/null +++ b/src/tests/Postgres.IntegrationTests/Subscriptions/PostgresSubscriptionCheckpointStoreTests.cs @@ -0,0 +1,126 @@ +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Fixtures.Postgres; +using Purview.EventSourcing.Postgres.Events; +using Purview.EventSourcing.Subscriptions; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.Postgres.Subscriptions; + +/// +/// The durable checkpoint store against real SQL Server. +/// +/// +/// Tenant separation is first: the whole point of a durable position is that it survives a restart, +/// and a position shared between tenants would survive as a permanent gap - whichever tenant ran +/// first advances it past the other's unread events, which are then never delivered. +/// +[ClassDataSource(Shared = SharedType.PerTestSession)] +public sealed class PostgresSubscriptionCheckpointStoreTests(PostgresEventStoreFixture fixture) +{ + [Test] + public async Task SetAsync_GivenTwoTenants_KeepsSeparatePositions(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var aggregateId = $"{Guid.NewGuid():N}"; + + SubscriptionCheckpointKey acme = new("projection", TenantScope.For("acme"), aggregateId); + SubscriptionCheckpointKey globex = new("projection", TenantScope.For("globex"), aggregateId); + + await store.SetAsync(acme, 50, cancellationToken); + + await Assert.That(await store.GetAsync(acme, cancellationToken)).IsEqualTo(50); + await Assert.That(await store.GetAsync(globex, cancellationToken)).IsNull(); + } + + [Test] + public async Task SetAsync_GivenTheSystemScope_IsSeparateFromEveryTenant(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var aggregateId = $"{Guid.NewGuid():N}"; + + SubscriptionCheckpointKey system = new("projection", TenantScope.System, aggregateId); + SubscriptionCheckpointKey acme = new("projection", TenantScope.For("acme"), aggregateId); + + await store.SetAsync(system, 50, cancellationToken); + + await Assert.That(await store.GetAsync(system, cancellationToken)).IsEqualTo(50); + await Assert.That(await store.GetAsync(acme, cancellationToken)).IsNull(); + } + + [Test] + public async Task SetAsync_GivenTwoSubscriptionNames_KeepsSeparatePositions(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var aggregateId = $"{Guid.NewGuid():N}"; + + SubscriptionCheckpointKey first = new("projection-a", TenantScope.System, aggregateId); + SubscriptionCheckpointKey second = new("projection-b", TenantScope.System, aggregateId); + + await store.SetAsync(first, 50, cancellationToken); + + await Assert.That(await store.GetAsync(second, cancellationToken)).IsNull(); + } + + [Test] + public async Task GetAsync_GivenAStreamNeverRead_ReturnsNull(CancellationToken cancellationToken) + { + using var store = CreateStore(); + SubscriptionCheckpointKey key = new("projection", TenantScope.System, $"{Guid.NewGuid():N}"); + + await Assert.That(await store.GetAsync(key, cancellationToken)).IsNull(); + } + + [Test] + public async Task SetAsync_GivenAHigherVersion_AdvancesThePosition(CancellationToken cancellationToken) + { + using var store = CreateStore(); + SubscriptionCheckpointKey key = new("projection", TenantScope.System, $"{Guid.NewGuid():N}"); + + await store.SetAsync(key, 10, cancellationToken); + await store.SetAsync(key, 20, cancellationToken); + + await Assert.That(await store.GetAsync(key, cancellationToken)).IsEqualTo(20); + } + + // A cycle that re-read an earlier range must not rewind a position that is already further on, + // which would redeliver everything in between. + [Test] + public async Task SetAsync_GivenALowerVersion_DoesNotMoveBackwards(CancellationToken cancellationToken) + { + using var store = CreateStore(); + SubscriptionCheckpointKey key = new("projection", TenantScope.System, $"{Guid.NewGuid():N}"); + + await store.SetAsync(key, 50, cancellationToken); + await store.SetAsync(key, 10, cancellationToken); + + await Assert.That(await store.GetAsync(key, cancellationToken)).IsEqualTo(50); + } + + [Test] + public async Task SetAsync_GivenConcurrentFirstWrites_RecordsOneOfThem(CancellationToken cancellationToken) + { + using var store = CreateStore(); + SubscriptionCheckpointKey key = new("projection", TenantScope.System, $"{Guid.NewGuid():N}"); + + // Both writers race to create the same row; the loser's duplicate-key failure is swallowed + // rather than surfaced, because a position behind redelivers and redelivery is safe. + await Task.WhenAll(Enumerable.Range(1, 8).Select(version => store.SetAsync(key, version, cancellationToken))); + + var recorded = await store.GetAsync(key, cancellationToken); + + await Assert.That(recorded).IsNotNull(); + await Assert.That(recorded!.Value).IsGreaterThanOrEqualTo(1).And.IsLessThanOrEqualTo(8); + } + + PostgresSubscriptionCheckpointStore CreateStore() => + new( + Options.Create( + new PostgresSubscriptionCheckpointStoreOptions + { + ConnectionString = fixture.ConnectionString, + TableName = $"Checkpoints_{Guid.NewGuid():N}", + } + ), + Options.Create(new PostgresEventStoreOptions { ConnectionString = fixture.ConnectionString }) + ); +} diff --git a/src/tests/SqlServer.IntegrationTests/Subscriptions/SqlServerSubscriptionCheckpointStoreTests.cs b/src/tests/SqlServer.IntegrationTests/Subscriptions/SqlServerSubscriptionCheckpointStoreTests.cs new file mode 100644 index 00000000..c10fb5cf --- /dev/null +++ b/src/tests/SqlServer.IntegrationTests/Subscriptions/SqlServerSubscriptionCheckpointStoreTests.cs @@ -0,0 +1,126 @@ +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Fixtures.SqlServer; +using Purview.EventSourcing.SqlServer.Events; +using Purview.EventSourcing.Subscriptions; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.SqlServer.Subscriptions; + +/// +/// The durable checkpoint store against real SQL Server. +/// +/// +/// Tenant separation is first: the whole point of a durable position is that it survives a restart, +/// and a position shared between tenants would survive as a permanent gap - whichever tenant ran +/// first advances it past the other's unread events, which are then never delivered. +/// +[ClassDataSource(Shared = SharedType.PerTestSession)] +public sealed class SqlServerSubscriptionCheckpointStoreTests(SqlServerEventStoreFixture fixture) +{ + [Test] + public async Task SetAsync_GivenTwoTenants_KeepsSeparatePositions(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var aggregateId = $"{Guid.NewGuid():N}"; + + SubscriptionCheckpointKey acme = new("projection", TenantScope.For("acme"), aggregateId); + SubscriptionCheckpointKey globex = new("projection", TenantScope.For("globex"), aggregateId); + + await store.SetAsync(acme, 50, cancellationToken); + + await Assert.That(await store.GetAsync(acme, cancellationToken)).IsEqualTo(50); + await Assert.That(await store.GetAsync(globex, cancellationToken)).IsNull(); + } + + [Test] + public async Task SetAsync_GivenTheSystemScope_IsSeparateFromEveryTenant(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var aggregateId = $"{Guid.NewGuid():N}"; + + SubscriptionCheckpointKey system = new("projection", TenantScope.System, aggregateId); + SubscriptionCheckpointKey acme = new("projection", TenantScope.For("acme"), aggregateId); + + await store.SetAsync(system, 50, cancellationToken); + + await Assert.That(await store.GetAsync(system, cancellationToken)).IsEqualTo(50); + await Assert.That(await store.GetAsync(acme, cancellationToken)).IsNull(); + } + + [Test] + public async Task SetAsync_GivenTwoSubscriptionNames_KeepsSeparatePositions(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var aggregateId = $"{Guid.NewGuid():N}"; + + SubscriptionCheckpointKey first = new("projection-a", TenantScope.System, aggregateId); + SubscriptionCheckpointKey second = new("projection-b", TenantScope.System, aggregateId); + + await store.SetAsync(first, 50, cancellationToken); + + await Assert.That(await store.GetAsync(second, cancellationToken)).IsNull(); + } + + [Test] + public async Task GetAsync_GivenAStreamNeverRead_ReturnsNull(CancellationToken cancellationToken) + { + using var store = CreateStore(); + SubscriptionCheckpointKey key = new("projection", TenantScope.System, $"{Guid.NewGuid():N}"); + + await Assert.That(await store.GetAsync(key, cancellationToken)).IsNull(); + } + + [Test] + public async Task SetAsync_GivenAHigherVersion_AdvancesThePosition(CancellationToken cancellationToken) + { + using var store = CreateStore(); + SubscriptionCheckpointKey key = new("projection", TenantScope.System, $"{Guid.NewGuid():N}"); + + await store.SetAsync(key, 10, cancellationToken); + await store.SetAsync(key, 20, cancellationToken); + + await Assert.That(await store.GetAsync(key, cancellationToken)).IsEqualTo(20); + } + + // A cycle that re-read an earlier range must not rewind a position that is already further on, + // which would redeliver everything in between. + [Test] + public async Task SetAsync_GivenALowerVersion_DoesNotMoveBackwards(CancellationToken cancellationToken) + { + using var store = CreateStore(); + SubscriptionCheckpointKey key = new("projection", TenantScope.System, $"{Guid.NewGuid():N}"); + + await store.SetAsync(key, 50, cancellationToken); + await store.SetAsync(key, 10, cancellationToken); + + await Assert.That(await store.GetAsync(key, cancellationToken)).IsEqualTo(50); + } + + [Test] + public async Task SetAsync_GivenConcurrentFirstWrites_RecordsOneOfThem(CancellationToken cancellationToken) + { + using var store = CreateStore(); + SubscriptionCheckpointKey key = new("projection", TenantScope.System, $"{Guid.NewGuid():N}"); + + // Both writers race to create the same row; the loser's duplicate-key failure is swallowed + // rather than surfaced, because a position behind redelivers and redelivery is safe. + await Task.WhenAll(Enumerable.Range(1, 8).Select(version => store.SetAsync(key, version, cancellationToken))); + + var recorded = await store.GetAsync(key, cancellationToken); + + await Assert.That(recorded).IsNotNull(); + await Assert.That(recorded!.Value).IsGreaterThanOrEqualTo(1).And.IsLessThanOrEqualTo(8); + } + + SqlServerSubscriptionCheckpointStore CreateStore() => + new( + Options.Create( + new SqlServerSubscriptionCheckpointStoreOptions + { + ConnectionString = fixture.ConnectionString, + TableName = $"Checkpoints_{Guid.NewGuid():N}", + } + ), + Options.Create(new SqlServerEventStoreOptions { ConnectionString = fixture.ConnectionString }) + ); +} From 8e4ba899c254805c8edbaefb81a0948cfc73f249 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Mon, 26 Oct 2026 07:11:00 +0000 Subject: [PATCH 14/41] feat: durable subscription checkpoints for Azure Storage and MongoDB Completes durable checkpoints for every provider that persists an event stream. Cosmos DB has none, so there is nothing to checkpoint. The monotonic guarantee - a position never moves backwards - has to be expressed differently per engine. MongoDB uses a filtered upsert and treats the resulting duplicate-key error as "already further on", which is the documented consequence of an upsert whose filter excludes the existing document. Azure Table Storage has no conditional-on-value write at all, so it reads and then writes conditionally on the ETag, retrying on contention and giving up after MaxWriteAttempts - leaving the position behind, which redelivers rather than skips. Neither composes its key by concatenation: a subscription name, tenant or aggregate id containing the delimiter would make two different keys identical. Azure Base64Url-encodes each segment, Mongo uses a compound _id document. Adds ConnectionString accessors to the Mongo and Azure fixtures so a test can build its own client. --- docs/wiki/Guarantees-and-Limitations.md | 4 +- docs/wiki/Provider-Feature-Matrix.md | 2 +- docs/wiki/Subscriptions.md | 30 ++-- skills/event-sourcing-subscriptions/SKILL.md | 23 ++- .../ServiceCollectionExtensions.cs | 37 ++++ ...AzureStorageSubscriptionCheckpointStore.cs | 165 ++++++++++++++++++ ...orageSubscriptionCheckpointStoreOptions.cs | 41 +++++ ...criptionCheckpointStoreOptionsValidator.cs | 21 +++ .../ServiceCollectionExtensions.cs | 35 ++++ .../MongoDBSubscriptionCheckpointStore.cs | 108 ++++++++++++ ...ngoDBSubscriptionCheckpointStoreOptions.cs | 36 ++++ ...criptionCheckpointStoreOptionsValidator.cs | 21 +++ ...StorageSubscriptionCheckpointStoreTests.cs | 126 +++++++++++++ ...MongoDBSubscriptionCheckpointStoreTests.cs | 129 ++++++++++++++ .../AzureStorage/TableEventStoreFixture.cs | 3 + .../MongoDB/MongoDBEventStoreFixture.cs | 3 + 16 files changed, 763 insertions(+), 21 deletions(-) create mode 100644 src/src/AzureStorage/Subscriptions/AzureStorageSubscriptionCheckpointStore.cs create mode 100644 src/src/AzureStorage/Subscriptions/AzureStorageSubscriptionCheckpointStoreOptions.cs create mode 100644 src/src/AzureStorage/Subscriptions/AzureStorageSubscriptionCheckpointStoreOptionsValidator.cs create mode 100644 src/src/MongoDB/Subscriptions/MongoDBSubscriptionCheckpointStore.cs create mode 100644 src/src/MongoDB/Subscriptions/MongoDBSubscriptionCheckpointStoreOptions.cs create mode 100644 src/src/MongoDB/Subscriptions/MongoDBSubscriptionCheckpointStoreOptionsValidator.cs create mode 100644 src/tests/AzureStorage.IntegrationTests/Subscriptions/AzureStorageSubscriptionCheckpointStoreTests.cs create mode 100644 src/tests/MongoDB.IntegrationTests/Subscriptions/MongoDBSubscriptionCheckpointStoreTests.cs diff --git a/docs/wiki/Guarantees-and-Limitations.md b/docs/wiki/Guarantees-and-Limitations.md index 939c9f2d..042c3274 100644 --- a/docs/wiki/Guarantees-and-Limitations.md +++ b/docs/wiki/Guarantees-and-Limitations.md @@ -169,9 +169,7 @@ Not guaranteed, and not configurable: - **No dead-letter path.** A subscriber that throws stops that stream at the failing event and retries it every cycle, indefinitely. This is fail-closed by choice: skipping would lose data silently. An unresolvable event type is not a failure - it is delivered with `IsUnresolved` set and skipped past. -- **Durable checkpoints ship for SQL Server and PostgreSQL only** (`AddSqlServerSubscriptionCheckpoints`, - `AddPostgresSubscriptionCheckpoints`). Elsewhere the default is in-memory and replays every stream after - a restart. +- **Durable checkpoints ship for every provider with an event stream** — SQL Server, PostgreSQL, Azure Storage and MongoDB, each via `AddSubscriptionCheckpoints()`. Without one the default is in-memory and replays every stream after a restart. - **Cosmos DB cannot be subscribed to** — it persists no event stream. Every other provider works, because stream discovery reads `IEventStoreCore.GetAggregateIdsAsync`, which every store implements and tenant-filters. diff --git a/docs/wiki/Provider-Feature-Matrix.md b/docs/wiki/Provider-Feature-Matrix.md index 0279e307..5b79bf4f 100644 --- a/docs/wiki/Provider-Feature-Matrix.md +++ b/docs/wiki/Provider-Feature-Matrix.md @@ -17,7 +17,7 @@ per-registration values. | Provider-neutral transaction guarantee | Explicit `BestEffort` or required `Atomic` | Atomic within one database boundary | Atomic within one database boundary | Best effort | Best effort | Best effort | | Transactional outbox (atomic with events) | No | Yes (`AddSqlServerOutbox`) | Yes (`AddPostgresOutbox`) | No | No | No | | [Subscriptions](Subscriptions.md) (catch-up over the event stream) | Contracts + `AddEventSubscription` | Yes | Yes | Yes | Yes | No (no event stream) | -| Durable subscription checkpoints | In-memory only (replays after restart) | `AddSqlServerSubscriptionCheckpoints()` | `AddPostgresSubscriptionCheckpoints()` | Not provided | Not provided | n/a | +| Durable subscription checkpoints | In-memory only (replays after restart) | `AddSqlServerSubscriptionCheckpoints()` | `AddPostgresSubscriptionCheckpoints()` | `AddAzureStorageSubscriptionCheckpoints()` | `AddMongoDBSubscriptionCheckpoints()` | n/a | | Event-stream retention / pruning | No | No | No | No | No | n/a | | Provider-specific native transaction factory | No | `ISqlServerEventStoreTransactionFactory` | `IPostgresEventStoreTransactionFactory` | No | No | No | | Runtime-configured JSON payload indexes | No | Yes (event + snapshot stores, auto-create path) | Yes (GIN + expression indexes on event + snapshot stores) | No | No | Yes (container indexing policy, including composite and spatial paths) | diff --git a/docs/wiki/Subscriptions.md b/docs/wiki/Subscriptions.md index be098ebb..d17fad47 100644 --- a/docs/wiki/Subscriptions.md +++ b/docs/wiki/Subscriptions.md @@ -108,15 +108,24 @@ services.AddSqlServerSubscriptionCheckpoints(); // or AddPostgresSubscriptionC services.AddEventSubscription(); ``` -| Provider | Durable checkpoints | -| --- | --- | -| SQL Server | `AddSqlServerSubscriptionCheckpoints()` | -| PostgreSQL | `AddPostgresSubscriptionCheckpoints()` | -| Azure Storage, MongoDB, Cosmos DB | Not provided — supply an `ISubscriptionCheckpointStore` | - -Both SQL stores create their table on first use (`AutoCreateTable`, on by default) and are -configured from `EventStore:SqlServer:Subscriptions` / `EventStore:Postgres:Subscriptions`. They -fall back to the event-store connection string when none is given. +| Provider | Durable checkpoints | Section | +| --- | --- | --- | +| SQL Server | `AddSqlServerSubscriptionCheckpoints()` | `EventStore:SqlServer:Subscriptions` | +| PostgreSQL | `AddPostgresSubscriptionCheckpoints()` | `EventStore:Postgres:Subscriptions` | +| Azure Storage | `AddAzureStorageSubscriptionCheckpoints()` | `EventStore:AzureStorage:Subscriptions` | +| MongoDB | `AddMongoDBSubscriptionCheckpoints()` | `EventStore:MongoDB:Subscriptions` | +| Cosmos DB | n/a — it has no event stream to subscribe to | | + +Each creates its table or collection on first use and falls back to the event-store connection +string when none is given. + +The guarantee that a position never moves backwards is expressed differently per store, because the +engines differ: SQL Server uses a guarded `UPDATE` then a conditional `INSERT`; PostgreSQL uses +`ON CONFLICT ... DO UPDATE ... WHERE`; MongoDB uses a filtered upsert and treats the resulting +duplicate-key error as "already further on"; Azure Table Storage has no conditional-on-value write +at all, so it reads and then writes conditionally on the ETag, retrying on contention +(`MaxWriteAttempts`, default 5). If Azure exhausts its retries it leaves the position behind, which +redelivers — safe, because delivery is at-least-once regardless. The scope is stored in a single non-null `TenantId` column, with the system scope encoded as the empty string by `SubscriptionCheckpointTenantColumn`. That is shared rather than per-provider @@ -144,8 +153,7 @@ services.AddEventSubscription(options => options.PollInt - **No global ordering**, and no ordered live tail. Both are discussed in [the design page](Subscriptions-And-Retention-Design.md). -- **Durable checkpoints ship for SQL Server and PostgreSQL only.** Azure Storage, MongoDB and an - InMemory deployment replay every stream after a restart unless you supply a store. +- **Durable checkpoints ship for every provider with an event stream** — SQL Server, PostgreSQL, Azure Storage and MongoDB. An InMemory deployment still replays every stream after a restart. - **Cosmos DB cannot be subscribed to at all** — it persists no event stream, and `RunCycleAsync` throws `NotSupportedException`. - **A permanently failing event stalls its stream.** There is no dead-letter path. diff --git a/skills/event-sourcing-subscriptions/SKILL.md b/skills/event-sourcing-subscriptions/SKILL.md index 14e22e2c..f7207812 100644 --- a/skills/event-sourcing-subscriptions/SKILL.md +++ b/skills/event-sourcing-subscriptions/SKILL.md @@ -94,12 +94,23 @@ services.AddSqlServerSubscriptionCheckpoints(); // or AddPostgresSubscriptionC services.AddEventSubscription(); ``` -Only SQL Server and PostgreSQL ship one. On Azure Storage or MongoDB you must supply an -`ISubscriptionCheckpointStore` yourself, or accept a full replay on every restart. - -If you write one, encode the scope with `SubscriptionCheckpointTenantColumn` rather than inventing -your own, and do not use a nullable tenant column: PostgreSQL treats NULLs as distinct in a unique -index, so the system scope would silently get duplicate rows. +Every provider with an event stream ships one - `AddSqlServerSubscriptionCheckpoints`, +`AddPostgresSubscriptionCheckpoints`, `AddAzureStorageSubscriptionCheckpoints`, +`AddMongoDBSubscriptionCheckpoints`. Cosmos DB has no event stream, so there is nothing to +checkpoint. + +If you write your own, encode the scope with `SubscriptionCheckpointTenantColumn` rather than +inventing your own scheme, and note two traps the shipped stores had to handle: + +- **Do not use a nullable tenant column.** PostgreSQL treats NULLs as distinct in a unique index, so + the system scope would silently accumulate duplicate rows. +- **Do not build the key by concatenating with a delimiter** unless you encode the segments. A + subscription name, tenant or aggregate id containing the delimiter makes two different keys + identical. The Azure store Base64Url-encodes each segment; the Mongo store uses a compound `_id` + document, which is unambiguous by construction. + +The position must never move backwards: a cycle that re-read an earlier range would otherwise rewind +a position that is already further on and redeliver everything in between. ## Failure stalls the stream, on purpose diff --git a/src/src/AzureStorage/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/AzureStorage/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs index bbea2a8f..f57dd4c4 100644 --- a/src/src/AzureStorage/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs +++ b/src/src/AzureStorage/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -1,7 +1,11 @@ using System.ComponentModel; using System.ComponentModel.DataAnnotations; using Microsoft.Extensions.Configuration; +using Microsoft.Extensions.DependencyInjection.Extensions; +using Microsoft.Extensions.Options; +using Purview.EventSourcing.AzureStorage.Subscriptions; using Purview.EventSourcing.Internal; +using Purview.EventSourcing.Subscriptions; namespace Microsoft.Extensions.DependencyInjection; @@ -80,5 +84,38 @@ public IServiceCollection AddAzureStorageEventStore(string? connectionStringName return services; } + + /// + /// Registers the Azure Table Storage subscription checkpoint store, so subscription positions + /// survive a restart. + /// + /// The for chaining. + /// + /// Call this before AddEventSubscription. Without a durable checkpoint store the default + /// in-memory one is used, and every subscription replays every stream from the beginning after a + /// restart. + /// + public IServiceCollection AddAzureStorageSubscriptionCheckpoints() + { + services.TryAddSingleton(); + + services + .AddOptions() + .Configure( + (options, configuration) => + configuration + .GetSection(AzureStorageSubscriptionCheckpointStoreOptions.AzureStorageSubscriptions) + .Bind(options) + ); + + services.TryAddEnumerable( + ServiceDescriptor.Singleton< + IValidateOptions, + AzureStorageSubscriptionCheckpointStoreOptionsValidator + >() + ); + + return services; + } } } diff --git a/src/src/AzureStorage/Subscriptions/AzureStorageSubscriptionCheckpointStore.cs b/src/src/AzureStorage/Subscriptions/AzureStorageSubscriptionCheckpointStore.cs new file mode 100644 index 00000000..a81a3f7b --- /dev/null +++ b/src/src/AzureStorage/Subscriptions/AzureStorageSubscriptionCheckpointStore.cs @@ -0,0 +1,165 @@ +using System.Text; +using Azure; +using Azure.Data.Tables; +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Subscriptions; + +namespace Purview.EventSourcing.AzureStorage.Subscriptions; + +/// +/// A durable backed by an Azure Storage table. +/// +/// +/// Without a durable store every subscription replays every stream after a restart, so this is what +/// makes a subscription usable in a deployed application. +/// +public sealed class AzureStorageSubscriptionCheckpointStore : ISubscriptionCheckpointStore, IDisposable +{ + readonly TableClient _tableClient; + readonly int _maxWriteAttempts; + readonly SemaphoreSlim _tableLock = new(1, 1); + bool _tableEnsured; + + /// Creates the store. + /// The checkpoint options. + /// The event-store options, used for any value not overridden. + public AzureStorageSubscriptionCheckpointStore( + IOptions checkpointOptions, + IOptions eventStoreOptions + ) + { + ArgumentNullException.ThrowIfNull(checkpointOptions); + ArgumentNullException.ThrowIfNull(eventStoreOptions); + + var options = checkpointOptions.Value; + var connectionString = + options.ConnectionString + ?? eventStoreOptions.Value.ConnectionString + ?? throw new InvalidOperationException( + "AzureStorageSubscriptionCheckpointStore requires a connection string. Configure 'EventStore:AzureStorage:Subscriptions:ConnectionString' or 'EventStore:AzureStorage:ConnectionString'." + ); + + _maxWriteAttempts = options.MaxWriteAttempts; + _tableClient = new(connectionString, options.TableName); + } + + /// + public async Task GetAsync(SubscriptionCheckpointKey key, CancellationToken cancellationToken) + { + await EnsureTableAsync(cancellationToken); + + var entity = await ReadAsync(key, cancellationToken); + + return entity?.Version; + } + + /// + public async Task SetAsync(SubscriptionCheckpointKey key, long version, CancellationToken cancellationToken) + { + await EnsureTableAsync(cancellationToken); + + // Table Storage has no "update only if the stored value is lower", so the guard is a read + // followed by an ETag-conditional write, retried when another writer gets there first. + for (var attempt = 0; attempt < _maxWriteAttempts; attempt++) + { + var existing = await ReadAsync(key, cancellationToken); + + // A cycle that re-read an earlier range must not rewind a position that is already + // further on, which would redeliver everything in between. + if (existing is not null && existing.Version >= version) + return; + + CheckpointEntity entity = new() + { + PartitionKey = PartitionKeyFor(key), + RowKey = RowKeyFor(key), + Version = version, + UpdatedUtc = DateTimeOffset.UtcNow, + }; + + try + { + if (existing is null) + await _tableClient.AddEntityAsync(entity, cancellationToken); + else + await _tableClient.UpdateEntityAsync( + entity, + existing.ETag, + TableUpdateMode.Replace, + cancellationToken + ); + + return; + } + catch (RequestFailedException ex) when (ex.Status is 409 or 412) + { + // 409: another writer created the row between the read and the add. + // 412: another writer changed it between the read and the update. + // Either way, re-read and decide again. + } + } + + // Leaving the position behind is safe: a position that is behind redelivers, and delivery is + // at-least-once already. The next cycle will advance it. + } + + async Task ReadAsync(SubscriptionCheckpointKey key, CancellationToken cancellationToken) + { + var response = await _tableClient.GetEntityIfExistsAsync( + PartitionKeyFor(key), + RowKeyFor(key), + cancellationToken: cancellationToken + ); + + return response.HasValue ? response.Value : null; + } + + async Task EnsureTableAsync(CancellationToken cancellationToken) + { + if (_tableEnsured) + return; + + await _tableLock.WaitAsync(cancellationToken); + try + { + if (_tableEnsured) + return; + + await _tableClient.CreateIfNotExistsAsync(cancellationToken); + _tableEnsured = true; + } + finally + { + _tableLock.Release(); + } + } + + // Azure table keys cannot contain '/', '\', '#' or '?', and a delimited key would be ambiguous if + // any segment contained the delimiter. Base64Url uses only characters that are legal in a key and + // never produces the '|' separator, so the composed key is both legal and unambiguous. + static string PartitionKeyFor(SubscriptionCheckpointKey key) => + $"{Encode(key.SubscriptionName)}|{Encode(SubscriptionCheckpointTenantColumn.Encode(key.Scope))}"; + + static string RowKeyFor(SubscriptionCheckpointKey key) => Encode(key.AggregateId); + + static string Encode(string value) => + Convert.ToBase64String(Encoding.UTF8.GetBytes(value)).TrimEnd('=').Replace('+', '-').Replace('/', '_'); + + /// + public void Dispose() => _tableLock.Dispose(); + + sealed class CheckpointEntity : ITableEntity + { + public long Version { get; set; } + + public DateTimeOffset UpdatedUtc { get; set; } + + public string PartitionKey { get; set; } = default!; + + public string RowKey { get; set; } = default!; + + public DateTimeOffset? Timestamp { get; set; } + + public ETag ETag { get; set; } + } +} diff --git a/src/src/AzureStorage/Subscriptions/AzureStorageSubscriptionCheckpointStoreOptions.cs b/src/src/AzureStorage/Subscriptions/AzureStorageSubscriptionCheckpointStoreOptions.cs new file mode 100644 index 00000000..af7b19c7 --- /dev/null +++ b/src/src/AzureStorage/Subscriptions/AzureStorageSubscriptionCheckpointStoreOptions.cs @@ -0,0 +1,41 @@ +using System.ComponentModel.DataAnnotations; + +namespace Purview.EventSourcing.AzureStorage.Subscriptions; + +/// +/// Options that configure the Azure Table Storage subscription checkpoint store. +/// +/// +/// Bound from the EventStore:AzureStorage:Subscriptions configuration section. When +/// is not supplied, the event-store connection string is used. +/// +public sealed class AzureStorageSubscriptionCheckpointStoreOptions +{ + /// The configuration section name used to bind these options. + public const string AzureStorageSubscriptions = "EventStore:AzureStorage:Subscriptions"; + + /// The default table name used to persist subscription positions. + public const string DefaultTableName = "EventStoreSubscriptionCheckpoints"; + + /// + /// The storage connection string. When null, the event-store connection string is used. + /// + public string? ConnectionString { get; set; } + + /// The name of the table that stores subscription positions. + /// Azure table names must be alphanumeric and start with a letter. + [Required(AllowEmptyStrings = false)] + [RegularExpression("^[A-Za-z][A-Za-z0-9]{2,62}$")] + public string TableName { get; set; } = DefaultTableName; + + /// + /// How many times a contended position write is retried before it is left for the next cycle. + /// + /// + /// Table Storage cannot express "update only if the stored version is lower", so the guard is a + /// read followed by an ETag-conditional write. Two instances running the same subscription can + /// collide; giving up leaves the position behind, which redelivers rather than skips. + /// + [Range(1, 20)] + public int MaxWriteAttempts { get; set; } = 5; +} diff --git a/src/src/AzureStorage/Subscriptions/AzureStorageSubscriptionCheckpointStoreOptionsValidator.cs b/src/src/AzureStorage/Subscriptions/AzureStorageSubscriptionCheckpointStoreOptionsValidator.cs new file mode 100644 index 00000000..036223e2 --- /dev/null +++ b/src/src/AzureStorage/Subscriptions/AzureStorageSubscriptionCheckpointStoreOptionsValidator.cs @@ -0,0 +1,21 @@ +using System.ComponentModel.DataAnnotations; +using Microsoft.Extensions.Options; + +namespace Purview.EventSourcing.AzureStorage.Subscriptions; + +sealed class AzureStorageSubscriptionCheckpointStoreOptionsValidator + : IValidateOptions +{ + public ValidateOptionsResult Validate(string? name, AzureStorageSubscriptionCheckpointStoreOptions options) + { + ArgumentNullException.ThrowIfNull(options); + ValidationContext validationContext = new(options); + List validationResults = []; + if (!Validator.TryValidateObject(options, validationContext, validationResults, validateAllProperties: true)) + return ValidateOptionsResult.Fail( + validationResults.Select(static x => x.ErrorMessage ?? "Options validation failed.") + ); + + return ValidateOptionsResult.Success; + } +} diff --git a/src/src/MongoDB/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/MongoDB/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs index d3cbee31..e326b39f 100644 --- a/src/src/MongoDB/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs +++ b/src/src/MongoDB/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -9,6 +9,8 @@ using Purview.EventSourcing.Internal; using Purview.EventSourcing.MongoDB.Events; using Purview.EventSourcing.MongoDB.Snapshots; +using Purview.EventSourcing.MongoDB.Subscriptions; +using Purview.EventSourcing.Subscriptions; namespace Microsoft.Extensions.DependencyInjection; @@ -219,5 +221,38 @@ public IServiceCollection AddMongoDBSnapshotQueryableEventStore( return services; } + + /// + /// Registers the MongoDB subscription checkpoint store, so subscription positions survive a + /// restart. + /// + /// The for chaining. + /// + /// Call this before AddEventSubscription. Without a durable checkpoint store the default + /// in-memory one is used, and every subscription replays every stream from the beginning after a + /// restart. + /// + public IServiceCollection AddMongoDBSubscriptionCheckpoints() + { + services.TryAddSingleton(); + + services + .AddOptions() + .Configure( + (options, configuration) => + configuration + .GetSection(MongoDBSubscriptionCheckpointStoreOptions.MongoDBSubscriptions) + .Bind(options) + ); + + services.TryAddEnumerable( + ServiceDescriptor.Singleton< + IValidateOptions, + MongoDBSubscriptionCheckpointStoreOptionsValidator + >() + ); + + return services; + } } } diff --git a/src/src/MongoDB/Subscriptions/MongoDBSubscriptionCheckpointStore.cs b/src/src/MongoDB/Subscriptions/MongoDBSubscriptionCheckpointStore.cs new file mode 100644 index 00000000..b06c0f4e --- /dev/null +++ b/src/src/MongoDB/Subscriptions/MongoDBSubscriptionCheckpointStore.cs @@ -0,0 +1,108 @@ +using Microsoft.Extensions.Options; +using MongoDB.Bson; +using MongoDB.Driver; +using Purview.EventSourcing.MongoDB.Events; +using Purview.EventSourcing.Subscriptions; + +namespace Purview.EventSourcing.MongoDB.Subscriptions; + +/// +/// A durable backed by a MongoDB collection. +/// +/// +/// Without a durable store every subscription replays every stream after a restart, so this is what +/// makes a subscription usable in a deployed application. +/// +public sealed class MongoDBSubscriptionCheckpointStore : ISubscriptionCheckpointStore, IDisposable +{ + const string VersionField = "v"; + const string UpdatedUtcField = "u"; + + readonly MongoClient _client; + readonly IMongoCollection _collection; + + /// Creates the store. + /// The checkpoint options. + /// The event-store options, used for any value not overridden. + public MongoDBSubscriptionCheckpointStore( + IOptions checkpointOptions, + IOptions eventStoreOptions + ) + { + ArgumentNullException.ThrowIfNull(checkpointOptions); + ArgumentNullException.ThrowIfNull(eventStoreOptions); + + var options = checkpointOptions.Value; + var connectionString = + options.ConnectionString + ?? eventStoreOptions.Value.ConnectionString + ?? throw new InvalidOperationException( + "MongoDBSubscriptionCheckpointStore requires a connection string. Configure 'EventStore:MongoDB:Subscriptions:ConnectionString' or 'EventStore:MongoDB:ConnectionString'." + ); + + var database = + options.Database + ?? eventStoreOptions.Value.Database + ?? throw new InvalidOperationException( + "MongoDBSubscriptionCheckpointStore requires a database. Configure 'EventStore:MongoDB:Subscriptions:Database' or 'EventStore:MongoDB:Database'." + ); + + _client = new(connectionString); + _collection = _client.GetDatabase(database).GetCollection(options.CollectionName); + } + + /// + public void Dispose() => _client.Dispose(); + + /// + public async Task GetAsync(SubscriptionCheckpointKey key, CancellationToken cancellationToken) + { + var document = await _collection + .Find(Filter(key)) + .Project(Builders.Projection.Include(VersionField)) + .FirstOrDefaultAsync(cancellationToken); + + return document is not null && document.TryGetValue(VersionField, out var version) ? version.ToInt64() : null; + } + + /// + public async Task SetAsync(SubscriptionCheckpointKey key, long version, CancellationToken cancellationToken) + { + // The filter requires the stored version to be lower, so a cycle that re-read an earlier + // range cannot rewind a position that is already further on - that would redeliver + // everything in between. + var filter = Builders.Filter.And( + Filter(key), + Builders.Filter.Lt(VersionField, version) + ); + + var update = Builders + .Update.Set(VersionField, version) + .Set(UpdatedUtcField, DateTimeOffset.UtcNow.UtcDateTime); + + try + { + await _collection.UpdateOneAsync(filter, update, new UpdateOptions { IsUpsert = true }, cancellationToken); + } + catch (MongoWriteException ex) when (ex.WriteError?.Category == ServerErrorCategory.DuplicateKey) + { + // An upsert whose filter excludes the existing document tries to insert it instead, and + // collides on _id. That happens in exactly two cases: a position at or beyond this one is + // already recorded, or another writer created the row first. Both mean the stored + // position is already at least as far on as this one, so there is nothing to do. + } + } + + // A compound _id rather than a delimited string: it is unique by definition and cannot be made + // ambiguous by a subscription name, tenant or aggregate id that happens to contain the delimiter. + static FilterDefinition Filter(SubscriptionCheckpointKey key) => + Builders.Filter.Eq( + "_id", + new BsonDocument + { + ["s"] = key.SubscriptionName, + ["t"] = SubscriptionCheckpointTenantColumn.Encode(key.Scope), + ["a"] = key.AggregateId, + } + ); +} diff --git a/src/src/MongoDB/Subscriptions/MongoDBSubscriptionCheckpointStoreOptions.cs b/src/src/MongoDB/Subscriptions/MongoDBSubscriptionCheckpointStoreOptions.cs new file mode 100644 index 00000000..7efc075d --- /dev/null +++ b/src/src/MongoDB/Subscriptions/MongoDBSubscriptionCheckpointStoreOptions.cs @@ -0,0 +1,36 @@ +using System.ComponentModel.DataAnnotations; + +namespace Purview.EventSourcing.MongoDB.Subscriptions; + +/// +/// Options that configure the MongoDB subscription checkpoint store. +/// +/// +/// Bound from the EventStore:MongoDB:Subscriptions configuration section. When +/// or are not supplied, the event-store values +/// are used. +/// +public sealed class MongoDBSubscriptionCheckpointStoreOptions +{ + /// The configuration section name used to bind these options. + public const string MongoDBSubscriptions = "EventStore:MongoDB:Subscriptions"; + + /// The default collection name used to persist subscription positions. + public const string DefaultCollectionName = "EventStoreSubscriptionCheckpoints"; + + /// + /// The MongoDB connection string. When null, the event-store connection string is used. + /// + public string? ConnectionString { get; set; } + + /// + /// The database that holds the checkpoint collection. When null, the event-store database is used. + /// + [RegularExpression(@"^[\w\-.]+$")] + public string? Database { get; set; } + + /// The name of the collection that stores subscription positions. + [Required(AllowEmptyStrings = false)] + [RegularExpression(@"^[\w\-.]+$")] + public string CollectionName { get; set; } = DefaultCollectionName; +} diff --git a/src/src/MongoDB/Subscriptions/MongoDBSubscriptionCheckpointStoreOptionsValidator.cs b/src/src/MongoDB/Subscriptions/MongoDBSubscriptionCheckpointStoreOptionsValidator.cs new file mode 100644 index 00000000..b1ea79cd --- /dev/null +++ b/src/src/MongoDB/Subscriptions/MongoDBSubscriptionCheckpointStoreOptionsValidator.cs @@ -0,0 +1,21 @@ +using System.ComponentModel.DataAnnotations; +using Microsoft.Extensions.Options; + +namespace Purview.EventSourcing.MongoDB.Subscriptions; + +sealed class MongoDBSubscriptionCheckpointStoreOptionsValidator + : IValidateOptions +{ + public ValidateOptionsResult Validate(string? name, MongoDBSubscriptionCheckpointStoreOptions options) + { + ArgumentNullException.ThrowIfNull(options); + ValidationContext validationContext = new(options); + List validationResults = []; + if (!Validator.TryValidateObject(options, validationContext, validationResults, validateAllProperties: true)) + return ValidateOptionsResult.Fail( + validationResults.Select(static x => x.ErrorMessage ?? "Options validation failed.") + ); + + return ValidateOptionsResult.Success; + } +} diff --git a/src/tests/AzureStorage.IntegrationTests/Subscriptions/AzureStorageSubscriptionCheckpointStoreTests.cs b/src/tests/AzureStorage.IntegrationTests/Subscriptions/AzureStorageSubscriptionCheckpointStoreTests.cs new file mode 100644 index 00000000..2d34864a --- /dev/null +++ b/src/tests/AzureStorage.IntegrationTests/Subscriptions/AzureStorageSubscriptionCheckpointStoreTests.cs @@ -0,0 +1,126 @@ +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Fixtures.AzureStorage; +using Purview.EventSourcing.Subscriptions; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.AzureStorage.Subscriptions; + +/// +/// The durable checkpoint store against real Azure Table Storage. +/// +/// +/// Tenant separation is first: the whole point of a durable position is that it survives a restart, +/// and a position shared between tenants would survive as a permanent gap - whichever tenant ran +/// first advances it past the other's unread events, which are then never delivered. +/// +[ClassDataSource(Shared = SharedType.PerTestSession)] +public sealed class AzureStorageSubscriptionCheckpointStoreTests(TableEventStoreFixture fixture) +{ + [Test] + public async Task SetAsync_GivenTwoTenants_KeepsSeparatePositions(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var aggregateId = $"{Guid.NewGuid():N}"; + + SubscriptionCheckpointKey acme = new("projection", TenantScope.For("acme"), aggregateId); + SubscriptionCheckpointKey globex = new("projection", TenantScope.For("globex"), aggregateId); + + await store.SetAsync(acme, 50, cancellationToken); + + await Assert.That(await store.GetAsync(acme, cancellationToken)).IsEqualTo(50); + await Assert.That(await store.GetAsync(globex, cancellationToken)).IsNull(); + } + + [Test] + public async Task SetAsync_GivenTheSystemScope_IsSeparateFromEveryTenant(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var aggregateId = $"{Guid.NewGuid():N}"; + + SubscriptionCheckpointKey system = new("projection", TenantScope.System, aggregateId); + SubscriptionCheckpointKey acme = new("projection", TenantScope.For("acme"), aggregateId); + + await store.SetAsync(system, 50, cancellationToken); + + await Assert.That(await store.GetAsync(system, cancellationToken)).IsEqualTo(50); + await Assert.That(await store.GetAsync(acme, cancellationToken)).IsNull(); + } + + [Test] + public async Task SetAsync_GivenTwoSubscriptionNames_KeepsSeparatePositions(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var aggregateId = $"{Guid.NewGuid():N}"; + + SubscriptionCheckpointKey first = new("projection-a", TenantScope.System, aggregateId); + SubscriptionCheckpointKey second = new("projection-b", TenantScope.System, aggregateId); + + await store.SetAsync(first, 50, cancellationToken); + + await Assert.That(await store.GetAsync(second, cancellationToken)).IsNull(); + } + + [Test] + public async Task GetAsync_GivenAStreamNeverRead_ReturnsNull(CancellationToken cancellationToken) + { + using var store = CreateStore(); + SubscriptionCheckpointKey key = new("projection", TenantScope.System, $"{Guid.NewGuid():N}"); + + await Assert.That(await store.GetAsync(key, cancellationToken)).IsNull(); + } + + [Test] + public async Task SetAsync_GivenAHigherVersion_AdvancesThePosition(CancellationToken cancellationToken) + { + using var store = CreateStore(); + SubscriptionCheckpointKey key = new("projection", TenantScope.System, $"{Guid.NewGuid():N}"); + + await store.SetAsync(key, 10, cancellationToken); + await store.SetAsync(key, 20, cancellationToken); + + await Assert.That(await store.GetAsync(key, cancellationToken)).IsEqualTo(20); + } + + // A cycle that re-read an earlier range must not rewind a position that is already further on, + // which would redeliver everything in between. + [Test] + public async Task SetAsync_GivenALowerVersion_DoesNotMoveBackwards(CancellationToken cancellationToken) + { + using var store = CreateStore(); + SubscriptionCheckpointKey key = new("projection", TenantScope.System, $"{Guid.NewGuid():N}"); + + await store.SetAsync(key, 50, cancellationToken); + await store.SetAsync(key, 10, cancellationToken); + + await Assert.That(await store.GetAsync(key, cancellationToken)).IsEqualTo(50); + } + + [Test] + public async Task SetAsync_GivenConcurrentFirstWrites_RecordsOneOfThem(CancellationToken cancellationToken) + { + using var store = CreateStore(); + SubscriptionCheckpointKey key = new("projection", TenantScope.System, $"{Guid.NewGuid():N}"); + + // Both writers race to create the same row; the loser's duplicate-key failure is swallowed + // rather than surfaced, because a position behind redelivers and redelivery is safe. + await Task.WhenAll(Enumerable.Range(1, 8).Select(version => store.SetAsync(key, version, cancellationToken))); + + var recorded = await store.GetAsync(key, cancellationToken); + + await Assert.That(recorded).IsNotNull(); + await Assert.That(recorded!.Value).IsGreaterThanOrEqualTo(1).And.IsLessThanOrEqualTo(8); + } + + AzureStorageSubscriptionCheckpointStore CreateStore() => + new( + Options.Create( + new AzureStorageSubscriptionCheckpointStoreOptions + { + ConnectionString = fixture.ConnectionString, + // Azure table names are alphanumeric and must start with a letter. + TableName = $"Checkpoints{Guid.NewGuid():N}", + } + ), + Options.Create(new AzureStorageEventStoreOptions { ConnectionString = fixture.ConnectionString }) + ); +} diff --git a/src/tests/MongoDB.IntegrationTests/Subscriptions/MongoDBSubscriptionCheckpointStoreTests.cs b/src/tests/MongoDB.IntegrationTests/Subscriptions/MongoDBSubscriptionCheckpointStoreTests.cs new file mode 100644 index 00000000..c38affab --- /dev/null +++ b/src/tests/MongoDB.IntegrationTests/Subscriptions/MongoDBSubscriptionCheckpointStoreTests.cs @@ -0,0 +1,129 @@ +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Fixtures.MongoDB; +using Purview.EventSourcing.MongoDB.Events; +using Purview.EventSourcing.Subscriptions; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.MongoDB.Subscriptions; + +/// +/// The durable checkpoint store against real MongoDB. +/// +/// +/// Tenant separation is first: the whole point of a durable position is that it survives a restart, +/// and a position shared between tenants would survive as a permanent gap - whichever tenant ran +/// first advances it past the other's unread events, which are then never delivered. +/// +[ClassDataSource(Shared = SharedType.PerTestSession)] +public sealed class MongoDBSubscriptionCheckpointStoreTests(MongoDBEventStoreFixture fixture) +{ + [Test] + public async Task SetAsync_GivenTwoTenants_KeepsSeparatePositions(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var aggregateId = $"{Guid.NewGuid():N}"; + + SubscriptionCheckpointKey acme = new("projection", TenantScope.For("acme"), aggregateId); + SubscriptionCheckpointKey globex = new("projection", TenantScope.For("globex"), aggregateId); + + await store.SetAsync(acme, 50, cancellationToken); + + await Assert.That(await store.GetAsync(acme, cancellationToken)).IsEqualTo(50); + await Assert.That(await store.GetAsync(globex, cancellationToken)).IsNull(); + } + + [Test] + public async Task SetAsync_GivenTheSystemScope_IsSeparateFromEveryTenant(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var aggregateId = $"{Guid.NewGuid():N}"; + + SubscriptionCheckpointKey system = new("projection", TenantScope.System, aggregateId); + SubscriptionCheckpointKey acme = new("projection", TenantScope.For("acme"), aggregateId); + + await store.SetAsync(system, 50, cancellationToken); + + await Assert.That(await store.GetAsync(system, cancellationToken)).IsEqualTo(50); + await Assert.That(await store.GetAsync(acme, cancellationToken)).IsNull(); + } + + [Test] + public async Task SetAsync_GivenTwoSubscriptionNames_KeepsSeparatePositions(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var aggregateId = $"{Guid.NewGuid():N}"; + + SubscriptionCheckpointKey first = new("projection-a", TenantScope.System, aggregateId); + SubscriptionCheckpointKey second = new("projection-b", TenantScope.System, aggregateId); + + await store.SetAsync(first, 50, cancellationToken); + + await Assert.That(await store.GetAsync(second, cancellationToken)).IsNull(); + } + + [Test] + public async Task GetAsync_GivenAStreamNeverRead_ReturnsNull(CancellationToken cancellationToken) + { + using var store = CreateStore(); + SubscriptionCheckpointKey key = new("projection", TenantScope.System, $"{Guid.NewGuid():N}"); + + await Assert.That(await store.GetAsync(key, cancellationToken)).IsNull(); + } + + [Test] + public async Task SetAsync_GivenAHigherVersion_AdvancesThePosition(CancellationToken cancellationToken) + { + using var store = CreateStore(); + SubscriptionCheckpointKey key = new("projection", TenantScope.System, $"{Guid.NewGuid():N}"); + + await store.SetAsync(key, 10, cancellationToken); + await store.SetAsync(key, 20, cancellationToken); + + await Assert.That(await store.GetAsync(key, cancellationToken)).IsEqualTo(20); + } + + // A cycle that re-read an earlier range must not rewind a position that is already further on, + // which would redeliver everything in between. + [Test] + public async Task SetAsync_GivenALowerVersion_DoesNotMoveBackwards(CancellationToken cancellationToken) + { + using var store = CreateStore(); + SubscriptionCheckpointKey key = new("projection", TenantScope.System, $"{Guid.NewGuid():N}"); + + await store.SetAsync(key, 50, cancellationToken); + await store.SetAsync(key, 10, cancellationToken); + + await Assert.That(await store.GetAsync(key, cancellationToken)).IsEqualTo(50); + } + + [Test] + public async Task SetAsync_GivenConcurrentFirstWrites_RecordsOneOfThem(CancellationToken cancellationToken) + { + using var store = CreateStore(); + SubscriptionCheckpointKey key = new("projection", TenantScope.System, $"{Guid.NewGuid():N}"); + + // Both writers race to create the same row; the loser's duplicate-key failure is swallowed + // rather than surfaced, because a position behind redelivers and redelivery is safe. + await Task.WhenAll(Enumerable.Range(1, 8).Select(version => store.SetAsync(key, version, cancellationToken))); + + var recorded = await store.GetAsync(key, cancellationToken); + + await Assert.That(recorded).IsNotNull(); + await Assert.That(recorded!.Value).IsGreaterThanOrEqualTo(1).And.IsLessThanOrEqualTo(8); + } + + MongoDBSubscriptionCheckpointStore CreateStore() => + new( + Options.Create( + new MongoDBSubscriptionCheckpointStoreOptions + { + ConnectionString = fixture.ConnectionString, + Database = $"chk{Guid.NewGuid():N}", + CollectionName = "Checkpoints", + } + ), + Options.Create( + new MongoDBEventStoreOptions { ConnectionString = fixture.ConnectionString, Database = "unused" } + ) + ); +} diff --git a/src/tests/SharedTestingFramework/Fixtures/AzureStorage/TableEventStoreFixture.cs b/src/tests/SharedTestingFramework/Fixtures/AzureStorage/TableEventStoreFixture.cs index 01a6a70b..6bfb4795 100644 --- a/src/tests/SharedTestingFramework/Fixtures/AzureStorage/TableEventStoreFixture.cs +++ b/src/tests/SharedTestingFramework/Fixtures/AzureStorage/TableEventStoreFixture.cs @@ -23,6 +23,9 @@ public TableEventStoreFixture() EventStoreOperationContext.RequiresValidPrincipalIdentifierDefault = false; } + /// The emulator connection string, for tests that build their own storage client. + public string ConnectionString => _azuriteContainer.GetEmulatorConnectionString(); + public IDistributedCacheMock Cache { get; private set; } = default!; public ITableEventStoreTelemetryMock Telemetry { get; private set; } = default!; diff --git a/src/tests/SharedTestingFramework/Fixtures/MongoDB/MongoDBEventStoreFixture.cs b/src/tests/SharedTestingFramework/Fixtures/MongoDB/MongoDBEventStoreFixture.cs index a6b5280e..2594c7b5 100644 --- a/src/tests/SharedTestingFramework/Fixtures/MongoDB/MongoDBEventStoreFixture.cs +++ b/src/tests/SharedTestingFramework/Fixtures/MongoDB/MongoDBEventStoreFixture.cs @@ -22,6 +22,9 @@ public MongoDBEventStoreFixture() _mongoDBContainer = ContainerHelper.CreateMongoDB(); } + /// The container connection string, for tests that build their own Mongo client. + public string ConnectionString => _mongoDBContainer.GetConnectionString(); + public IDistributedCacheMock Cache { get; private set; } = default!; public IMongoDBEventStoreTelemetryMock Telemetry { get; private set; } = default!; From cdf51fed074d370a4b55a65a016dec3b46066955 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Mon, 26 Oct 2026 08:09:06 +0000 Subject: [PATCH 15/41] fix(ci): restore the unit-only test selection in the pipeline config Moving purview-build.json to .config/ in 4d72eda also widened the test selection: TestProjects went from *UnitTests.csproj to *Tests.csproj and TestFilter dropped the [Category=Unit] predicate. That made PR validation run every test project with no category filter, including the provider integration suites and Samples.AppHost, which need a container runtime and an Aspire host. On a hosted runner those fail at "Connection refused", which is what red CI on this branch was. AGENTS.md already states the pipeline never runs provider integration tests or the performance harnesses; this restores that. Also corrects the config path in AGENTS.md and README.md, which still pointed at the repository root. --- .config/purview-build.json | 4 ++-- AGENTS.md | 2 +- README.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.config/purview-build.json b/.config/purview-build.json index d4ca35c7..b9a7c266 100644 --- a/.config/purview-build.json +++ b/.config/purview-build.json @@ -3,8 +3,8 @@ "Solution": "src/EventSourcing.slnx", "TestRoot": "src/tests", "TestPatterns": "*Tests.csproj", - "TestProjects": "*Tests.csproj", - "TestFilter": "/*/*/*/*" + "TestProjects": "*UnitTests.csproj", + "TestFilter": "/*/*/*/*[Category=Unit]" }, "PackValidation": { "RequireSymbolPackage": true, diff --git a/AGENTS.md b/AGENTS.md index 79c585b4..dc2f2887 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -243,7 +243,7 @@ just perf-sql-server just current-version ``` -The repository uses the shared `Purview.Build` pipeline (`purview-build.json` at the root), also driven in CI through the `purview-dev/build` reusable workflows. `just pipeline-pr` installs the pinned `Purview.Build` tool to `.tools/purview-build` when missing. +The repository uses the shared `Purview.Build` pipeline (`.config/purview-build.json`), also driven in CI through the `purview-dev/build` reusable workflows. `just pipeline-pr` installs the pinned `Purview.Build` tool to `.tools/purview-build` when missing. Local CI-equivalent validation: diff --git a/README.md b/README.md index 0f424a61..0b32dff5 100644 --- a/README.md +++ b/README.md @@ -193,7 +193,7 @@ The sample solution demonstrates how the framework is intended to be consumed: | `src/tests` | Unit, integration, and source generator test projects | | `docs/wiki` | Wiki-style project documentation (`Home.md`, SQL Server guide, release flow, source-generator behaviors) | | `Justfile` | Build, test, format, version, pack, and pipeline workflow definitions | -| `purview-build.json` | Shared `Purview.Build` pipeline configuration (restore, build, lint, tests, pack) | +| `.config/purview-build.json` | Shared `Purview.Build` pipeline configuration (restore, build, lint, tests, pack) | ## Development workflow From 78b32f8e013c98ae2923324b6f4c39f97876b3e5 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Mon, 26 Oct 2026 08:14:49 +0000 Subject: [PATCH 16/41] fix(ci): align pack validation with the EntityFrameworkCore package split The EF Core support library and its source generator were moved into their own package so three providers no longer each embed a copy of the analyzer, which was producing duplicate-attribute errors in consumer builds. The pack validation rules were not updated with it, so they still required Postgres, SqlServer and CosmosDb to contain Purview.EventSourcing.EntityFrameworkCore.dll and the analyzer - content those packages correctly no longer carry - and the new package had no RequiredContent rule at all, which RequireExplicitContent rejects. Rules now match the packages that are actually produced, verified by reading the nupkg contents rather than by assumption. --- .config/purview-build.json | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/.config/purview-build.json b/.config/purview-build.json index b9a7c266..99532c27 100644 --- a/.config/purview-build.json +++ b/.config/purview-build.json @@ -87,16 +87,20 @@ "README.md" ], "purview.eventsourcing.cosmosdb": [ - "analyzers/dotnet/cs/Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.dll", "lib/$(TFM)/Purview.EventSourcing.CosmosDb.dll", "lib/$(TFM)/Purview.EventSourcing.CosmosDb.xml", - "lib/$(TFM)/Purview.EventSourcing.EntityFrameworkCore.dll", - "lib/$(TFM)/Purview.EventSourcing.EntityFrameworkCore.xml", "lib/$(TFM)/Purview.EventSourcing.ImplementationShared.dll", "lib/$(TFM)/Purview.EventSourcing.ImplementationShared.xml", "purview-logo-light.png", "README.md" ], + "purview.eventsourcing.entityframeworkcore": [ + "analyzers/dotnet/cs/Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.dll", + "lib/$(TFM)/Purview.EventSourcing.EntityFrameworkCore.dll", + "lib/$(TFM)/Purview.EventSourcing.EntityFrameworkCore.xml", + "purview-logo-light.png", + "README.md" + ], "purview.eventsourcing.inmemory": [ "lib/$(TFM)/Purview.EventSourcing.ImplementationShared.dll", "lib/$(TFM)/Purview.EventSourcing.ImplementationShared.xml", @@ -115,9 +119,6 @@ "README.md" ], "purview.eventsourcing.postgres": [ - "analyzers/dotnet/cs/Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.dll", - "lib/$(TFM)/Purview.EventSourcing.EntityFrameworkCore.dll", - "lib/$(TFM)/Purview.EventSourcing.EntityFrameworkCore.xml", "lib/$(TFM)/Purview.EventSourcing.ImplementationShared.dll", "lib/$(TFM)/Purview.EventSourcing.ImplementationShared.xml", "lib/$(TFM)/Purview.EventSourcing.Postgres.dll", @@ -127,9 +128,6 @@ "README.md" ], "purview.eventsourcing.sqlserver": [ - "analyzers/dotnet/cs/Purview.EventSourcing.EntityFrameworkCore.SourceGenerator.dll", - "lib/$(TFM)/Purview.EventSourcing.EntityFrameworkCore.dll", - "lib/$(TFM)/Purview.EventSourcing.EntityFrameworkCore.xml", "lib/$(TFM)/Purview.EventSourcing.ImplementationShared.dll", "lib/$(TFM)/Purview.EventSourcing.ImplementationShared.xml", "lib/$(TFM)/Purview.EventSourcing.SqlServer.dll", From 49895a2afc6774a9ce3925b13d7a73347018d708 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Mon, 26 Oct 2026 09:05:48 +0000 Subject: [PATCH 17/41] docs: plan the five production-readiness workstreams Detailed designs for each gap from the enterprise-readiness assessment, all marked as proposals. Each states the problem with evidence from the code, a design, phases, the tests that would prove it, and the decisions still open. Crypto key management is the blocking one and carries the explicit requirement for local, in-memory and external stores. Three tiers over the existing IEventCryptoKeyStore, which does not change: in-memory for tests, SQL/Postgres for self-hosted, Key Vault for external custody - recommending envelope encryption so a vault holds one KEK rather than a secret per subject, which does not scale. Two findings the plan had to confront. ProtectedPayload records alg and sub but no key identifier, so rotation is impossible without a payload format change; adding an optional kid is backward compatible because absent means "the only key". And erasure is only as irreversible as the least-irreversible copy - Key Vault purge protection and database backups both silently defeat shredding, which makes them operational guidance rather than footnotes. Retention supersedes Part 2 of the subscriptions design and widens it to idempotency markers, which grow unboundedly today and are safe to delete, so that half can ship first. Observability parity records the measured state: tracing exists on SQL Server and Postgres only, not on MongoDB, Azure Storage or Cosmos DB, though the cross-provider metrics are uniform. --- docs/wiki/Admin-Audit-Durability-Design.md | 140 ++++++++++++++ docs/wiki/Crypto-Key-Management-Design.md | 177 ++++++++++++++++++ docs/wiki/Home.md | 10 +- docs/wiki/Observability-Parity-Design.md | 102 ++++++++++ docs/wiki/Resilience-Testing-Design.md | 124 ++++++++++++ docs/wiki/Retention-Design.md | 143 ++++++++++++++ .../Subscriptions-And-Retention-Design.md | 6 +- docs/wiki/_Sidebar.md | 5 + 8 files changed, 704 insertions(+), 3 deletions(-) create mode 100644 docs/wiki/Admin-Audit-Durability-Design.md create mode 100644 docs/wiki/Crypto-Key-Management-Design.md create mode 100644 docs/wiki/Observability-Parity-Design.md create mode 100644 docs/wiki/Resilience-Testing-Design.md create mode 100644 docs/wiki/Retention-Design.md diff --git a/docs/wiki/Admin-Audit-Durability-Design.md b/docs/wiki/Admin-Audit-Durability-Design.md new file mode 100644 index 00000000..4e83298d --- /dev/null +++ b/docs/wiki/Admin-Audit-Durability-Design.md @@ -0,0 +1,140 @@ +# Durable Admin Audit — Design + +> **Status: proposal. Nothing on this page is implemented.** +> +> `InMemoryAdminAuditLogger` is the only `IAdminAuditLogger` that ships. + +## The problem + +In a regulated deployment the audit trail *is* the control. Ours currently dies with the process: +`Admin.Security/InMemoryAdminAuditLogger.cs` is the only implementation, so every record of who read +which event payload, who triggered a rebuild, and who erased a data subject is lost on restart — and +lost silently. + +Three further gaps in the contract itself: + +- **No tenant on the entry.** `AdminAuditEntry` records timestamp, feature, action, principal, + target, success and details — but not the `TenantScope` the operation ran under. In a multi-tenant + deployment "who did this" is incomplete without "to which tenant". +- **No read side.** `IAdminAuditLogger` has `LogAsync` only. An audit trail nobody can query is + evidence you cannot produce. +- **No failure policy.** If the audit write fails, nothing says whether the operation should + proceed. + +## Design + +### Contract changes + +```csharp +public sealed record AdminAuditEntry( + DateTimeOffset TimestampUtc, + AdminFeature Feature, + string Action, + string? Principal, + string? Target, + bool Succeeded, + string? Details +) +{ + /// The tenant the operation ran under; null for the system scope. + public string? TenantId { get; init; } + + /// Correlates the audit entry with the request and with emitted events. + public string? CorrelationId { get; init; } +} +``` + +Both additive, so existing construction sites keep compiling. + +```csharp +public interface IAdminAuditQueryService +{ + Task> QueryAsync(AdminAuditQuery query, CancellationToken cancellationToken); +} +``` + +Kept separate from `IAdminAuditLogger` deliberately: writing and reading an audit trail are +different privileges, and a component that can write must not automatically be able to read. + +### Implementations + +| Provider | Store | +| --- | --- | +| SQL Server, PostgreSQL | A dedicated append-only table | +| Azure Storage | A table, partitioned by tenant and day | +| MongoDB | A collection with a TTL index for retention | + +Append-only is enforced by **not offering** update or delete on the contract, and by documenting the +database grants the table expects (`INSERT`/`SELECT` only for the application principal). The +framework cannot enforce the grant; it can state it. + +### Failure policy + +An explicit option, because both answers are defensible and the choice is the deployment's: + +```csharp +public enum AdminAuditFailureMode +{ + /// The operation proceeds; the failure is logged. Availability over evidence. + Continue = 0, + + /// The operation is refused. Evidence over availability - the regulated default. + Fail = 1, +} +``` + +Default `Fail` for privileged, mutating features (rebuild, erase); `Continue` for reads. A +deployment can override both. + +### Retention + +Audit entries are themselves subject to retention — typically a *minimum* retention, which is the +opposite of the event-stream problem in [Retention](Retention-Design.md). The MongoDB TTL index and +a scheduled cleanup for the SQL providers both need a floor that cannot be configured below the +deployment's policy. + +## Tamper evidence + +Worth deciding explicitly rather than implying. Options, cheapest first: + +1. **Append-only grants plus provider-native immutability** (Azure immutable storage, SQL temporal + tables). No framework work; strongest when the platform supports it. +2. **Hash chaining** — each entry carries the hash of its predecessor, so deletion or alteration is + detectable on verification. Modest cost, needs a verification API and a per-tenant chain head. +3. **External sink** — write to a SIEM and treat the local table as a cache. Strongest, but moves + the problem outside the framework. + +Recommendation: ship (1), design the schema so (2) can be added without a migration (reserve a +`PreviousHash` column), and document (3) as the pattern for anyone who needs it. + +## Phases + +| Phase | Work | +| --- | --- | +| 1 | `TenantId` and `CorrelationId` on `AdminAuditEntry`; populate from the request scope | +| 2 | SQL Server + PostgreSQL durable loggers, with the failure-mode option | +| 3 | `IAdminAuditQueryService` and an Admin API endpoint behind its own permission | +| 4 | Azure Storage + MongoDB loggers | +| 5 | Retention floor and cleanup | + +## Testing + +- **Tenancy first**: an entry written under tenant A is not returned to tenant B's query; the system + scope sees both. +- The audit write happens even when the audited operation *fails* — a refused operation is the one + most worth recording. +- `AdminAuditFailureMode.Fail` refuses the operation when the audit store is unavailable; `Continue` + does not. This needs the fault injection from [Resilience Testing](Resilience-Testing-Design.md). +- Reading the audit trail requires its own permission, and the deny-by-default provider refuses it. +- No code path updates or deletes an entry — asserted structurally, by the contract having no such + method. + +## Decisions needed + +1. Default **failure mode** for mutating features. (Recommendation: `Fail`.) +2. Whether **hash chaining** is in scope now or reserved for later. +3. Whether the audit query endpoint is part of the Admin API or deliberately left out, so audit can + only be read through the database. +4. Whether audit entries are **tenant-scoped or system-scoped** when a super-user acts across + tenants — my assumption is the entry records the tenant acted *upon*, with the principal's own + scope in `Details`. diff --git a/docs/wiki/Crypto-Key-Management-Design.md b/docs/wiki/Crypto-Key-Management-Design.md new file mode 100644 index 00000000..07b6db96 --- /dev/null +++ b/docs/wiki/Crypto-Key-Management-Design.md @@ -0,0 +1,177 @@ +# Crypto Key Management — Design + +> **Status: proposal. Nothing on this page is implemented.** +> +> The only `IEventCryptoKeyStore` that ships today is `InMemoryEventCryptoKeyStore`. + +## The problem + +Crypto-shredding is currently a trap rather than a feature. + +`InMemoryEventCryptoKeyStore` holds keys in a `ConcurrentDictionary` for the lifetime of the +process. Restart the host and **every protected event becomes permanently unreadable** — and +indistinguishable from an event whose subject was deliberately erased. There is no durable +alternative in the box, and nothing stops an application registering it in production. + +Its own XML docs say this is intentional ("unusable in production by construction"), and that is a +defensible position for a default. It is not defensible as the *only* option. + +Two further gaps: + +- **No key rotation.** `ProtectedPayload` records `alg` and `sub` but no key identifier, so there is + no way to tell which key a payload was encrypted under. Rotation is impossible without a format + change. +- **No caching.** Every protect/unprotect calls the store. Against an external vault that is both + too slow and too expensive to run. + +## Three tiers + +The requirement is local, in-memory, and external. All three implement the existing +`IEventCryptoKeyStore`, which does not change. + +| Tier | Implementation | Use | +| --- | --- | --- | +| **In-memory** | `InMemoryEventCryptoKeyStore` (exists) | Tests and local development only | +| **Local** | `SqlServerEventCryptoKeyStore`, `PostgresEventCryptoKeyStore` | Self-hosted and on-premises; keys live in a dedicated table beside the data | +| **External** | `AzureKeyVaultEventCryptoKeyStore` | Deployments where key custody must sit outside the application's database | + +### The guard + +A startup check that refuses `InMemoryEventCryptoKeyStore` outside Development, unless explicitly +overridden: + +```csharp +services.AddEventCryptoShredding(options => options.AllowNonDurableKeyStore = true); +``` + +The override exists because a test host or a demo legitimately wants it; the default refuses, +because the failure mode is silent and total. It throws at startup rather than first use, so a +misconfiguration cannot reach the point where events have already been written. + +## The external tier: two models + +Azure Key Vault can hold the keys two ways, and they differ in what erasure means. + +### Model A — one vault secret per subject + +`GetOrCreateAsync` creates a secret named for the subject; `ShredAsync` deletes it. + +- Erasure maps directly onto the vault's own ACL, audit trail and delete semantics. +- **Does not scale.** A vault is not designed for millions of secrets: listing is slow, throughput + is throttled per-vault, and cost is per-operation. + +### Model B — envelope encryption (recommended) + +A per-subject data key (DEK) is generated locally and stored, **wrapped**, in the local tier. The +wrapping key (KEK) lives in Key Vault and never leaves it; the vault performs wrap/unwrap. + +- Scales to any number of subjects; one vault object per tenant or per deployment. +- `ShredAsync` deletes the wrapped DEK row — a local delete, not a vault operation. +- Key Vault holds custody of the KEK, so a stolen database is still unreadable. + +**Model B is the recommendation**, with Model A available for deployments with few subjects and a +hard requirement that erasure be a vault-audited event. + +Model B means the local tier is a prerequisite for the external tier, not an alternative to it. + +## The hard part: erasure is only as irreversible as the least-irreversible copy + +This deserves stating plainly in the documentation, because it is the thing that makes +crypto-shredding fail an audit: + +- **Key Vault soft-delete and purge protection conflict with erasure.** With purge protection + enabled, a deleted secret is recoverable for the retention period — so a "shredded" subject is + not actually erased until that window expires. For Model A the vault must either have purge + protection disabled, or `ShredAsync` must delete *and purge*, and the implementation must fail + loudly when it cannot. +- **Database backups restore keys.** For the local tier and for Model B, a point-in-time restore + brings shredded keys back. The key table must be excluded from long-retention backups, or the + deployment must accept that erasure completes only when the last backup containing the key ages + out. + +The existing `IEventCryptoKeyStore` remarks already warn about this. The plan is to make it +operational guidance in `docs/wiki`, not just an XML comment, and to have each implementation +document its own erasure latency. + +## Caching + +Against an external vault, an uncached store is unusable: every event protect/unprotect becomes a +network call. + +```csharp +public sealed class CachingEventCryptoKeyStore(IEventCryptoKeyStore inner, IMemoryCache cache, IOptions options) + : IEventCryptoKeyStore; +``` + +The rule that makes it safe: **`ShredAsync` must evict before it deletes, and a cache miss must not +be retried from a stale replica.** A cached key outliving its erasure is a compliance failure, not a +performance quirk. Default TTL should be short (minutes) and configurable, and the cache must be +keyed by tenant as well as subject. + +Decision needed: whether the cache is process-local (`IMemoryCache`) only, or whether a distributed +cache is permitted. A distributed cache holding plaintext keys is a second copy of the key material +and probably should be refused outright. + +## Rotation + +`ProtectedPayload` gains an optional key identifier: + +```csharp +[JsonPropertyName("kid")] +public string? KeyId { get; init; } +``` + +Absent means "the subject's only key", which is exactly what every payload written today means — so +the change is backward compatible and needs no upcaster. + +`IEventCryptoKeyStore` gains: + +```csharp +Task<(string KeyId, byte[] Key)> GetOrCreateCurrentAsync(string dataSubjectId, CancellationToken cancellationToken); +Task TryGetAsync(string dataSubjectId, string? keyId, CancellationToken cancellationToken); +Task RotateAsync(string dataSubjectId, CancellationToken cancellationToken); +``` + +Rotation generates a new key and marks it current. **Old keys are retained**, because existing +events were encrypted under them — rotation limits the blast radius of a future key compromise, it +does not re-encrypt history. Rotation and erasure stay distinct: `ShredAsync` deletes *every* +generation for the subject. + +This is an additive but breaking interface change for anyone who has implemented the interface. +Default implementations on the interface can keep existing implementers compiling. + +## Phases + +| Phase | Work | +| --- | --- | +| 1 | Startup guard refusing the in-memory store outside Development | +| 2 | SQL Server + PostgreSQL key stores, with the tenancy and monotonic-write patterns used by the subscription checkpoint stores | +| 3 | `CachingEventCryptoKeyStore`, with evict-before-delete | +| 4 | Key Vault store, Model B envelope wrapping (Model A behind an option) | +| 5 | Rotation: `kid` on the payload, the three interface methods, and an admin-triggered rotate | + +Phase 1 alone removes the trap and is worth shipping on its own. + +## Testing + +Tenancy first, as always — a key store is per-tenant, and a key leaking across tenants is worse than +a snapshot leaking across tenants. + +- One tenant cannot read, create or shred another tenant's key; the system scope can. +- `ShredAsync` makes a previously readable payload return null from `UnprotectAsync`, **through the + cache** — the test must prime the cache first, exactly as the tenancy cache test does. +- Rotation: a payload written under key 1 stays readable after rotating to key 2; a payload written + after rotation uses key 2; shredding removes both. +- Replay of a stream containing a shredded event yields a `SkippedEventRecord` rather than throwing. +- Key Vault tests run against a real vault or a recorded transport; the emulator story is poor, so + this will likely be an opt-in suite with its own category. + +## Decisions needed + +1. **Model A or Model B** for Key Vault. (Recommendation: B, with A available.) +2. Whether a **distributed cache** may hold key material. (Recommendation: no.) +3. Whether the **key store is a separate package per provider** (`Purview.EventSourcing.SqlServer` + gains it) or a single `Purview.EventSourcing.Cryptography.*` family. +4. Whether rotation ships in the first release or follows. +5. Whether the startup guard is **on by default** — it is a breaking change for anyone currently + running the in-memory store in production, which is precisely the population it protects. diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md index 7e485174..a0662bf8 100644 --- a/docs/wiki/Home.md +++ b/docs/wiki/Home.md @@ -31,7 +31,15 @@ This wiki is the project documentation hub for framework features, provider capa Designs under discussion. Check each page's status banner before relying on it. - [Subscriptions and Retention](Subscriptions-And-Retention-Design.md) — subscriptions shipped; the - retention half and the ordered live tail remain proposals + ordered live tail remains a proposal +- [Crypto Key Management](Crypto-Key-Management-Design.md) — local, in-memory and Key Vault key + stores, plus rotation. **Blocking: crypto-shredding has no production key store today** +- [Durable Admin Audit](Admin-Audit-Durability-Design.md) — the audit trail currently dies with the + process +- [Retention](Retention-Design.md) — event streams and idempotency markers both grow without bound +- [Observability Parity](Observability-Parity-Design.md) — distributed tracing exists on two + providers of five +- [Resilience Testing](Resilience-Testing-Design.md) — fault injection, load and soak ## Feature highlights diff --git a/docs/wiki/Observability-Parity-Design.md b/docs/wiki/Observability-Parity-Design.md new file mode 100644 index 00000000..e8d6e7a1 --- /dev/null +++ b/docs/wiki/Observability-Parity-Design.md @@ -0,0 +1,102 @@ +# Observability Parity — Design + +> **Status: proposal. Nothing on this page is implemented.** + +## The problem + +Observability is not at parity across providers, and the documentation implies more coverage than +exists. Measured from the telemetry interfaces in each provider: + +| Provider | Tracing (`[ActivitySource]`) | Logging (`[Logger]`) | Provider metrics (`[Meter]`) | +| --- | --- | --- | --- | +| SQL Server | Yes | Yes | Yes | +| PostgreSQL | Yes | Yes | Yes | +| MongoDB | **No** | Yes | Yes | +| Azure Storage | **No** | Yes | **No** | +| Cosmos DB | **No** | **No** | Yes | +| InMemory | **No** | **No** | **No** | + +The cross-provider `IEventStoreMetrics` — `save.duration`, `get.duration`, `events.appended` — *is* +uniform, and [Guarantees and Limitations](Guarantees-and-Limitations.md) correctly says so. The gap +is **distributed tracing**, which exists on two providers of five. + +That is the capability you need when a save is slow in production: metrics tell you *that* it is +slow, a trace tells you *where*. On Azure Storage, MongoDB and Cosmos DB there is currently no +answer. + +## Design + +No new abstraction. Each provider already has a telemetry interface implemented by +`Purview.Telemetry`'s generator; the work is to bring each up to the same three attributes and the +same span names, following `ISqlServerEventStoreTelemetry` as the template. + +### Span naming is a compatibility contract + +Instrument names already are one. Span names must be too, or a dashboard built against SQL Server +breaks when the same service moves to MongoDB. Proposed convention, matching the existing SQL +spans: + +```text +EventStore.Get +EventStore.Save +EventStore.Delete +EventStore.Restore +EventStore.GetEventRange +EventStore.Snapshot +``` + +with attributes `aggregate.type`, `aggregate.id`, `event.count`, `tenant.id` and the outcome. + +**`aggregate.id` and `tenant.id` are a decision, not an obvious yes.** An aggregate id can be a +natural key and a tenant id identifies a customer; both end up in a trace backend with a different +retention and access model from the database. Recommendation: `tenant.id` always, +`aggregate.id` behind an option defaulting to off, consistent with how a careful HTTP +instrumentation treats a URL path. + +### Where spans belong + +One span per public store operation, started in the provider implementation, not in the facade — +the facade cannot see provider-specific retries or batch splits, which is exactly the detail a +trace is for. Nested spans for provider-native work worth seeing: batch submission on Azure, +transaction scope on SQL, replica-set round trips on Mongo. + +### InMemory + +Deliberately left without telemetry. It exists for tests and local development, and instrumenting +it adds noise to every test run for no diagnostic value. This should be *documented* as a decision +rather than left looking like an omission. + +## Phases + +| Phase | Work | +| --- | --- | +| 1 | Agree span names and attributes; document them as a contract alongside the metric names | +| 2 | Azure Storage: add `[ActivitySource]` and `[Meter]` to `ITableEventStoreTelemetry` | +| 3 | MongoDB: add `[ActivitySource]` | +| 4 | Cosmos DB: add `[ActivitySource]` and `[Logger]` | +| 5 | Update `Guarantees-and-Limitations.md` and the provider guides to state the real coverage | + +Phase 5 is worth doing **first** if the others are deferred: documenting the gap honestly costs +nothing and stops someone designing around parity that does not exist. + +## Testing + +The existing telemetry mocks (`ITableEventStoreTelemetryMock` and friends) already make this +assertable per provider. + +- Each provider's contract suite asserts that a save and a get **start the expected span**, with the + expected attributes — added to the shared contract tests so a new provider cannot omit them. +- `aggregate.id` is absent unless the option is enabled; `tenant.id` is present and correct under + both a tenant scope and the system scope. +- A failed operation records the failure on the span rather than leaving it successful. + +Putting the span assertions in the shared contract suite is the same structural move as the +tenancy seam: parity that is asserted centrally cannot be forgotten by the next provider. + +## Decisions needed + +1. Whether **`aggregate.id`** is recorded by default. (Recommendation: no, behind an option.) +2. Whether span names follow the `EventStore.*` convention above or OpenTelemetry's database + semantic conventions (`db.operation` etc.), which would be more portable but less readable. +3. Whether **InMemory** stays uninstrumented. (Recommendation: yes, documented.) +4. Whether provider-native nested spans are in scope for the first pass or follow later. diff --git a/docs/wiki/Resilience-Testing-Design.md b/docs/wiki/Resilience-Testing-Design.md new file mode 100644 index 00000000..75480c1c --- /dev/null +++ b/docs/wiki/Resilience-Testing-Design.md @@ -0,0 +1,124 @@ +# Resilience Testing — Design + +> **Status: proposal. Nothing on this page is implemented.** + +## The problem + +The suite is broad — ~1,450 tests, per-provider contract suites, acceptance scenarios — but it only +tests the **happy path and expected failures**. The failure modes that actually corrupt an event +store are the ones no current test reaches: + +- A save that commits events but fails writing the snapshot. +- A storage call that succeeds server-side but whose response is lost, so the client retries. +- An outbox lease that expires mid-dispatch, so two dispatchers hold the same message. +- A provider that times out under load rather than failing fast. +- Two writers racing on the same aggregate under real contention, not simulated. + +Every one of these is a correctness question, and all of them are currently unanswered. Three times +during this work a filter looked correct, was not, and the suite stayed green — the same category of +blind spot. + +There is also **no load or soak testing**. The performance harness under `src/src/Benchmarks` +measures throughput; it does not assert that behaviour stays correct while under it. + +## Design + +Three layers, cheapest first. + +### 1. Fault injection at the store boundary + +A decorating `IEventStoreCore` that fails on command, composed in test wiring only: + +```csharp +public sealed class FaultInjectingEventStore(IEventStoreCore inner, FaultPlan plan) : IEventStoreCore; +``` + +`FaultPlan` describes *when* and *how*: fail the nth call to a named operation, throw a specific +exception, delay, or succeed-then-report-failure (the lost-response case, which is the one that +produces duplicates). + +This covers the framework's own logic — retry behaviour, transaction rollback, outbox state +transitions — without a container. Fast enough to live in the unit suite. + +### 2. Fault injection at the transport + +Some failures only exist below the abstraction: a connection reset mid-read, a partial write, a +server-side timeout. These need a proxy between the client and the container (Toxiproxy, or the +provider SDK's own fault hooks) and belong in the integration suites, gated behind a category so +they do not run on every PR. + +### 3. Load and soak + +A harness that runs the contract suite's invariants **while** under concurrent load, asserting that +the invariants still hold rather than measuring a number: + +- N writers on the same aggregate: exactly one wins per version, no event is lost, no version is + duplicated. +- N writers across M aggregates for a sustained period: event count reconciles, no orphaned + snapshots, outbox drains to empty. +- A subscription keeps up or falls behind, but never skips. + +Soak matters for the leaks that only appear over time — unbounded idempotency markers, outbox rows +that never reach a terminal state, connections not returned to the pool. + +## The invariants worth asserting under fault + +These are the assertions; the mechanism above exists to make them testable. + +| Invariant | Fault that threatens it | +| --- | --- | +| An event is never lost once a save reports success | Snapshot write fails after event commit | +| An event is never applied twice | Lost response, client retries | +| Stream version is contiguous, never gapped | Concurrent writers, partial batch | +| A failed save leaves no partial state | Transaction rollback, batch split on Azure | +| The outbox delivers at least once, never zero | Lease expiry mid-dispatch | +| A subscription never skips an event | Checkpoint written before handler completes | +| Tenant isolation holds | Any of the above, under a tenant scope | + +The last line is the point: **every resilience test should run under a tenant scope**, because a +failure path is exactly where a tenant stamp gets forgotten. + +## Placement + +| Layer | Project | Category | +| --- | --- | --- | +| Store-boundary faults | `EventSourcing.UnitTests` | `Unit` — runs in PR validation | +| Transport faults | `.IntegrationTests` | New `Resilience` category, opt-in | +| Load and soak | New `EventSourcing.ResilienceTests` console harness under `src/src/Benchmarks` | Not a test project; run on demand | + +Only the first runs in CI. The other two are too slow and too infrastructure-dependent, which is the +same reasoning that keeps the provider integration suites out of PR validation. + +## Other gaps worth closing alongside + +Found during the same assessment, cheaper than the above and arguably higher value per hour: + +- **Admin surface is thinly tested relative to its risk** — 7 files in `Admin.UnitTests` for the + whole API and authorization model; `Admin.SqlServer.UnitTests` has 2. This is the security + boundary. +- **No Admin integration tests** for the MongoDB, Azure or Postgres adapters. +- **Uneven provider depth** — `SqlServer.IntegrationTests` has 15 files, `AzureStorage.IntegrationTests` 3. +- **No upgrade test** — nothing proves data written by 1.x reads under 2.0, which matters for a + release carrying breaking changes. +- **Cosmos DB is never validated against the real service**; the vnext emulator cannot run the + suite. Already documented, still a risk. + +## Phases + +| Phase | Work | +| --- | --- | +| 1 | `FaultInjectingEventStore` and `FaultPlan`; the first six invariants above as unit tests | +| 2 | Admin test coverage up to the level its risk warrants | +| 3 | An upgrade/compatibility suite reading 1.x-shaped data | +| 4 | Transport fault injection in one provider as a pilot, then the rest | +| 5 | Load and soak harness | + +## Decisions needed + +1. Whether fault injection lives in `SharedTestingFramework` (reusable by provider suites) or only + in the unit project. (Recommendation: `SharedTestingFramework`.) +2. Which transport-fault tool — Toxiproxy adds a container per suite; SDK-level hooks are + provider-specific and less realistic. +3. Whether the upgrade suite needs **committed fixture data** in 1.x shape, which is a maintenance + commitment but the only way to test it honestly. +4. Whether load/soak runs anywhere automatically, or purely on demand. diff --git a/docs/wiki/Retention-Design.md b/docs/wiki/Retention-Design.md new file mode 100644 index 00000000..8428c8d1 --- /dev/null +++ b/docs/wiki/Retention-Design.md @@ -0,0 +1,143 @@ +# Retention — Design + +> **Status: proposal. Nothing on this page is implemented.** +> +> Supersedes Part 2 of [Subscriptions and Retention](Subscriptions-And-Retention-Design.md), which +> covered event-stream retention only. + +## The problem + +Nothing in the framework ever removes anything. Three things grow without bound: + +| What | Growth | Consequence | +| --- | --- | --- | +| **Event streams** | One row per event, forever | Replay cost and storage cost rise with aggregate age | +| **Idempotency markers** | One row per save, forever | Pure overhead after the dedupe window has passed | +| **Outbox messages** | Bounded — `IOutboxStore.CleanupAsync` exists | Already solved; the precedent for the rest | + +The outbox already shows the shape: `Task CleanupAsync(TimeSpan retention, CancellationToken)`, +removing terminal messages older than a window. The other two need the same treatment, with very +different risk profiles. + +## Idempotency markers — the easy half + +A marker exists to deduplicate a retried save. Its usefulness expires with the retry window, which +is minutes, not years. After that it is dead weight that is never read. + +```csharp +Task CleanupIdempotencyMarkersAsync(TimeSpan retention, CancellationToken cancellationToken); +``` + +Default retention of 7 days is generous against any plausible retry window. + +Deleting an expired marker is **safe**: the worst case is that a save retried after the window +elapsed is applied twice, which optimistic concurrency already rejects. That is why this half can +ship first and independently. + +MongoDB and Azure Storage can use native TTL (a TTL index; `DeleteAfter` on the entity) rather than +a sweep. The SQL providers need a scheduled delete. + +## Event streams — the dangerous half + +Removing an event is the one operation that can destroy business state permanently, because the +event stream is the canonical source of truth. It is only safe once a **snapshot covers the prune +point**, at which moment the snapshot becomes the replay base. + +```csharp +public sealed record EventRetentionPolicy +{ + /// Never prune events newer than this. + public TimeSpan MinimumAge { get; init; } = TimeSpan.FromDays(90); + + /// Always leave this many events behind the snapshot, as a safety margin. + public int RetainedVersions { get; init; } = 100; + + /// Refuse to prune unless a snapshot at or beyond the prune point exists. + public bool RequireSnapshot { get; init; } = true; +} +``` + +### `RequireSnapshot` must not be defeasible + +Pruning with no snapshot behind it destroys state irrecoverably and inverts the repository's first +invariant. The option exists to be *read*, not to be turned off: the implementation should treat +`false` as a request that requires a second, explicitly destructive opt-in, or refuse it entirely. + +A provider without snapshot support therefore cannot offer stream retention, and must report that +rather than silently no-op. + +### Interactions + +| With | Consequence | +| --- | --- | +| **Snapshots** | The snapshot becomes load-bearing, so [snapshot schema versioning](Snapshot-Schema-Versioning.md) becomes a correctness concern rather than a convenience | +| **Subscriptions** | A subscription whose checkpoint is behind the prune point can never catch up. Retention must refuse to prune past the slowest checkpoint — not merely warn | +| **Crypto-shredding** | Complementary, not substitutes: shredding removes the key for one subject, retention removes rows for everyone. A pruned event can no longer be shredded, so the snapshot must not retain plaintext | +| **Upcasting** | Pruned events are never upcast again, so a schema migration must run *before* the events it touches age out | +| **Tenancy** | Pruning runs per tenant or as a system operation, and must never cross a tenant boundary | + +The subscription interaction is the one most likely to be got wrong, because it is invisible: a +projection that is merely slow becomes a projection that is permanently incomplete, with no error. + +## Operating model + +Two questions, and I would answer both conservatively: + +**Scheduled or invoked?** Scheduled is more useful and considerably more dangerous — an unattended +job that deletes history is a bad default. Recommendation: **operator-invoked through the Admin API +first**, behind its own permission and audited; a scheduled host service later, opt-in. + +**Dry run?** Yes, and it should ship *before* the destructive path: + +```csharp +Task PreviewAsync(EventRetentionPolicy policy, CancellationToken cancellationToken); +``` + +returning what would be removed — counts per aggregate, the oldest and newest version affected, and +any stream blocked by a lagging subscription or a missing snapshot. A preview that reports blockers +is how an operator learns the policy is wrong before it costs them. + +## Provider support + +| Provider | Marker cleanup | Stream retention | +| --- | --- | --- | +| SQL Server, PostgreSQL | Scheduled delete | Yes — snapshot-backed | +| MongoDB | TTL index | Yes | +| Azure Storage | Entity TTL | Yes, plus blob cleanup for large payloads | +| Cosmos DB | n/a | n/a — no event stream | +| InMemory | Yes | Yes, for the acceptance scenarios | + +Azure needs care: an oversized event is stored as a blob behind a pointer event, so pruning the +pointer must also delete the blob or it leaks storage silently. + +## Phases + +| Phase | Work | +| --- | --- | +| 1 | Idempotency marker cleanup, all providers — safe and independently valuable | +| 2 | `EventRetentionPolicy`, `PreviewAsync`, and the blocker checks (snapshot coverage, subscription lag) | +| 3 | Destructive prune, operator-invoked through the Admin API, audited | +| 4 | Azure blob cleanup for pruned large payloads | +| 5 | Optional scheduled host service, opt-in | + +## Testing + +- **Tenancy first**: pruning as tenant A leaves tenant B's streams untouched; the system scope can + prune across tenants. +- Pruning with no covering snapshot is refused, and the aggregate still loads afterwards. +- After a prune, the aggregate rehydrates **from the snapshot plus the remaining events** to exactly + the state it had before. +- A stream with a lagging subscription checkpoint is reported as blocked and not pruned. +- A pruned Azure stream leaves no orphaned blobs. +- `PreviewAsync` and the destructive path agree: what preview reported is what prune removed. +- Marker cleanup does not remove a marker still inside the retry window. + +## Decisions needed + +1. **Scheduled or operator-invoked** for stream retention. (Recommendation: invoked first.) +2. Whether **dry run ships before** the destructive path. (Recommendation: yes.) +3. Whether `RequireSnapshot = false` is permitted at all, and if so behind what second opt-in. +4. Whether retention is **blocked by** a lagging subscription or merely warns. (Recommendation: + blocked.) +5. Whether any jurisdiction in scope forbids removing an event, which would make stream retention + opt-in per aggregate type rather than per deployment. diff --git a/docs/wiki/Subscriptions-And-Retention-Design.md b/docs/wiki/Subscriptions-And-Retention-Design.md index b4231d83..ba88b822 100644 --- a/docs/wiki/Subscriptions-And-Retention-Design.md +++ b/docs/wiki/Subscriptions-And-Retention-Design.md @@ -7,8 +7,10 @@ > from the sketches below; this page is kept for the *reasoning*, particularly the ordering analysis > and the options that were rejected. > -> **Part 2, retention, remains a proposal.** No type, option or method in that section exists. The -> ordered live tail described in Option D is not implemented either. +> **Part 2, retention, has been superseded by [Retention](Retention-Design.md)**, which covers +> idempotency markers and the outbox alongside event streams, and sets out an operating model. The +> section below is kept for its interaction analysis. The ordered live tail described in Option D is +> not implemented either. ## What already exists, and what is missing diff --git a/docs/wiki/_Sidebar.md b/docs/wiki/_Sidebar.md index 513f3674..ba4d96ce 100644 --- a/docs/wiki/_Sidebar.md +++ b/docs/wiki/_Sidebar.md @@ -21,3 +21,8 @@ - [SQL Server Guide](SQL-Server-Guide.md) - [Release Flow](Release-Flow.md) - _Proposal:_ [Subscriptions and Retention](Subscriptions-And-Retention-Design.md) +- _Proposal:_ [Crypto Key Management](Crypto-Key-Management-Design.md) +- _Proposal:_ [Durable Admin Audit](Admin-Audit-Durability-Design.md) +- _Proposal:_ [Retention](Retention-Design.md) +- _Proposal:_ [Observability Parity](Observability-Parity-Design.md) +- _Proposal:_ [Resilience Testing](Resilience-Testing-Design.md) From 31a906b503b5cf36bb0174912edd34b8727befe0 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Mon, 26 Oct 2026 10:45:13 +0000 Subject: [PATCH 18/41] feat: durable crypto key stores and a guard against the non-durable one Crypto-shredding was a trap rather than a feature: InMemoryEventCryptoKeyStore was the only implementation, so a restart made every protected event permanently unreadable - indistinguishable from erasing every data subject, with no error and no way back. Nothing stopped it reaching production. Two changes close that. A start-up check refuses a key store that declares itself non-durable outside Development, overridable by an explicit option; it runs at start-up rather than first use, so a misconfiguration cannot reach the point where events have been written under keys about to be lost. The check tests for INonDurableEventCryptoKeyStore rather than a concrete type, so a store the framework has never seen is covered too. And SQL Server and PostgreSQL key stores, tenant-scoped: the same data subject id in two tenants is two different people, so they get different keys and neither tenant can read or erase the other's. Verified by sabotage - removing the tenant from the predicate fails three tests. The Postgres concurrency test found a real bug. ON CONFLICT DO NOTHING returns no row, and a fallback SELECT in the same statement runs against the same snapshot, so it cannot see a row a concurrent transaction just inserted: the losing caller got nothing and threw. A no-op DO UPDATE takes the lock and returns the stored row either way. Had that shipped, concurrent first use of a subject would have failed intermittently under load. Also consolidates the tenant column encoding. Subscriptions had its own copy; crypto keys would have been a second, and two encodings of one concept is how one tenant's row collides with another's. Key Vault, caching and rotation remain planned, not built. --- docs/wiki/Crypto-Key-Management-Design.md | 6 +- docs/wiki/Guarantees-and-Limitations.md | 27 ++ docs/wiki/Provider-Feature-Matrix.md | 1 + docs/wiki/Subscriptions.md | 2 +- .../event-sourcing-crypto-shredding/SKILL.md | 36 ++- skills/event-sourcing-subscriptions/SKILL.md | 2 +- ...AzureStorageSubscriptionCheckpointStore.cs | 3 +- .../Cryptography/EventCryptoOptions.cs | 27 ++ .../INonDurableEventCryptoKeyStore.cs | 26 ++ .../InMemoryEventCryptoKeyStore.cs | 2 +- .../NonDurableKeyStoreStartupCheck.cs | 45 ++++ .../ServiceCollectionExtensions.cs | 44 ++++ .../SubscriptionCheckpointTenantColumn.cs | 29 --- src/src/EventSourcing/Tenancy/TenantColumn.cs | 27 ++ .../MongoDBSubscriptionCheckpointStore.cs | 3 +- .../PostgresEventCryptoKeyStore.cs | 221 +++++++++++++++++ .../PostgresEventCryptoKeyStoreOptions.cs | 43 ++++ ...gresEventCryptoKeyStoreOptionsValidator.cs | 20 ++ .../ServiceCollectionExtensions.cs | 33 +++ .../PostgresSubscriptionCheckpointStore.cs | 3 +- .../SqlServerEventCryptoKeyStore.cs | 234 ++++++++++++++++++ .../SqlServerEventCryptoKeyStoreOptions.cs | 43 ++++ ...rverEventCryptoKeyStoreOptionsValidator.cs | 20 ++ .../ServiceCollectionExtensions.cs | 35 +++ .../SqlServerSubscriptionCheckpointStore.cs | 3 +- .../NonDurableKeyStoreStartupCheckTests.cs | 117 +++++++++ .../PostgresEventCryptoKeyStoreTests.cs | 158 ++++++++++++ .../SqlServerEventCryptoKeyStoreTests.cs | 158 ++++++++++++ 28 files changed, 1323 insertions(+), 45 deletions(-) create mode 100644 src/src/EventSourcing/Cryptography/EventCryptoOptions.cs create mode 100644 src/src/EventSourcing/Cryptography/INonDurableEventCryptoKeyStore.cs create mode 100644 src/src/EventSourcing/Cryptography/NonDurableKeyStoreStartupCheck.cs delete mode 100644 src/src/EventSourcing/Subscriptions/SubscriptionCheckpointTenantColumn.cs create mode 100644 src/src/EventSourcing/Tenancy/TenantColumn.cs create mode 100644 src/src/Postgres/Cryptography/PostgresEventCryptoKeyStore.cs create mode 100644 src/src/Postgres/Cryptography/PostgresEventCryptoKeyStoreOptions.cs create mode 100644 src/src/Postgres/Cryptography/PostgresEventCryptoKeyStoreOptionsValidator.cs create mode 100644 src/src/SqlServer/Cryptography/SqlServerEventCryptoKeyStore.cs create mode 100644 src/src/SqlServer/Cryptography/SqlServerEventCryptoKeyStoreOptions.cs create mode 100644 src/src/SqlServer/Cryptography/SqlServerEventCryptoKeyStoreOptionsValidator.cs create mode 100644 src/tests/EventSourcing.UnitTests/Cryptography/NonDurableKeyStoreStartupCheckTests.cs create mode 100644 src/tests/Postgres.IntegrationTests/Cryptography/PostgresEventCryptoKeyStoreTests.cs create mode 100644 src/tests/SqlServer.IntegrationTests/Cryptography/SqlServerEventCryptoKeyStoreTests.cs diff --git a/docs/wiki/Crypto-Key-Management-Design.md b/docs/wiki/Crypto-Key-Management-Design.md index 07b6db96..04db645d 100644 --- a/docs/wiki/Crypto-Key-Management-Design.md +++ b/docs/wiki/Crypto-Key-Management-Design.md @@ -1,8 +1,10 @@ # Crypto Key Management — Design -> **Status: proposal. Nothing on this page is implemented.** +> **Status: partly implemented.** > -> The only `IEventCryptoKeyStore` that ships today is `InMemoryEventCryptoKeyStore`. +> Phase 1 (the start-up guard) and Phase 2 (SQL Server and PostgreSQL key stores) have shipped — see +> [Guarantees and Limitations](Guarantees-and-Limitations.md#key-stores). Caching, the Key Vault +> store and rotation remain proposals. ## The problem diff --git a/docs/wiki/Guarantees-and-Limitations.md b/docs/wiki/Guarantees-and-Limitations.md index 042c3274..54d73fbb 100644 --- a/docs/wiki/Guarantees-and-Limitations.md +++ b/docs/wiki/Guarantees-and-Limitations.md @@ -95,6 +95,33 @@ was enabled are **not** retrospectively removed - delete them as part of enablin The in-memory store holds live objects rather than serialized payloads, so there is nothing to encrypt and crypto-shredding does not apply to it. +### Key stores + +Keys are **tenant-scoped**: the same data-subject identifier in two tenants is two different people, so +they get two different keys, and neither tenant can read or erase the other's. + +| Store | Registration | Durable | +| --- | --- | --- | +| In-memory | `AddInMemoryEventCryptoShredding()` | **No** - keys are lost on restart | +| SQL Server | `AddSqlServerEventCryptoShredding()` | Yes | +| PostgreSQL | `AddPostgresEventCryptoShredding()` | Yes | +| Azure Storage, MongoDB, Key Vault | Not provided yet | - | + +**The host refuses to start with a non-durable key store outside Development.** Losing the keys is +indistinguishable from erasing every data subject at once, and nothing reports that it happened, so the +only safe moment to object is before any event has been written under a key that is about to be lost. +Set `EventStore:Cryptography:AllowNonDurableKeyStore` to override, if that outcome is genuinely +acceptable. A store declares itself non-durable by implementing `INonDurableEventCryptoKeyStore`, so a +custom store is covered by the same guard. + +**Erasure is only as irreversible as the least-irreversible copy of the key.** A point-in-time restore +of the key table brings shredded keys back. A deployment that must erase on request has to exclude the +key table from long-retention backups, or accept that erasure completes only when the last backup +containing the key ages out. This is an operational control, not something the framework can enforce. + +Key rotation is **not** implemented: `ProtectedPayload` records no key identifier, so there is no way to +tell which key a payload used. See [Crypto Key Management](Crypto-Key-Management-Design.md). + ## Multi-tenancy Opt-in, and **currently enforced only by the SQL Server and PostgreSQL providers**. diff --git a/docs/wiki/Provider-Feature-Matrix.md b/docs/wiki/Provider-Feature-Matrix.md index 5b79bf4f..7027d2af 100644 --- a/docs/wiki/Provider-Feature-Matrix.md +++ b/docs/wiki/Provider-Feature-Matrix.md @@ -18,6 +18,7 @@ per-registration values. | Transactional outbox (atomic with events) | No | Yes (`AddSqlServerOutbox`) | Yes (`AddPostgresOutbox`) | No | No | No | | [Subscriptions](Subscriptions.md) (catch-up over the event stream) | Contracts + `AddEventSubscription` | Yes | Yes | Yes | Yes | No (no event stream) | | Durable subscription checkpoints | In-memory only (replays after restart) | `AddSqlServerSubscriptionCheckpoints()` | `AddPostgresSubscriptionCheckpoints()` | `AddAzureStorageSubscriptionCheckpoints()` | `AddMongoDBSubscriptionCheckpoints()` | n/a | +| Durable crypto-shredding key store | In-memory only (refused outside Development) | `AddSqlServerEventCryptoShredding()` | `AddPostgresEventCryptoShredding()` | Not provided | Not provided | n/a | | Event-stream retention / pruning | No | No | No | No | No | n/a | | Provider-specific native transaction factory | No | `ISqlServerEventStoreTransactionFactory` | `IPostgresEventStoreTransactionFactory` | No | No | No | | Runtime-configured JSON payload indexes | No | Yes (event + snapshot stores, auto-create path) | Yes (GIN + expression indexes on event + snapshot stores) | No | No | Yes (container indexing policy, including composite and spatial paths) | diff --git a/docs/wiki/Subscriptions.md b/docs/wiki/Subscriptions.md index d17fad47..20b82a15 100644 --- a/docs/wiki/Subscriptions.md +++ b/docs/wiki/Subscriptions.md @@ -128,7 +128,7 @@ at all, so it reads and then writes conditionally on the ETag, retrying on conte redelivers — safe, because delivery is at-least-once regardless. The scope is stored in a single non-null `TenantId` column, with the system scope encoded as the -empty string by `SubscriptionCheckpointTenantColumn`. That is shared rather than per-provider +empty string by `TenantColumn`. That is shared rather than per-provider because the encoding has to be identical everywhere, and because a nullable column would behave differently between the two engines — PostgreSQL treats NULLs as distinct in a unique index, which would silently allow duplicate system-scope rows. diff --git a/skills/event-sourcing-crypto-shredding/SKILL.md b/skills/event-sourcing-crypto-shredding/SKILL.md index cbee8b31..650d45fb 100644 --- a/skills/event-sourcing-crypto-shredding/SKILL.md +++ b/skills/event-sourcing-crypto-shredding/SKILL.md @@ -38,16 +38,38 @@ not itself be personal data: use a surrogate identifier, never an email address. ## Supplying keys ```csharp -builder.Services.AddSingleton(); -builder.Services.AddSingleton(); +builder.Services.AddSqlServerEventCryptoShredding(); // or AddPostgresEventCryptoShredding() ``` -`InMemoryEventCryptoKeyStore` ships for local development and tests only: its keys die with the -process, so every payload becomes unreadable on restart. That is deliberate - a key store is the one -component where a convenient default would be actively harmful. +One call registers the key store, the AES-GCM protector and a start-up guard. Every provider takes +an optional `IEventPayloadProtector`, so registering it turns protection on for whichever store is +configured. -**The key store is the erasure mechanism.** Back it with something that has its own access control -and audit trail, and that does not silently restore deleted entries from a backup. +| Store | Registration | Durable | +| -- | -- | -- | +| In-memory | `AddInMemoryEventCryptoShredding()` | **No** | +| SQL Server | `AddSqlServerEventCryptoShredding()` | Yes | +| PostgreSQL | `AddPostgresEventCryptoShredding()` | Yes | +| Azure Storage, MongoDB, Key Vault | not provided yet | - | + +**The host refuses to start with a non-durable key store outside Development.** Keys that die with +the process make every protected payload unreadable - the same outcome as erasing every subject at +once, with no error and no way back. `EventStore:Cryptography:AllowNonDurableKeyStore` overrides it; +if you are reaching for that to make a start-up failure go away, register a durable store instead. + +Writing your own store? Implement `INonDurableEventCryptoKeyStore` on any test double so the guard +recognises it, and scope keys by the current tenant - the same subject id in two tenants is two +different people. + +**Erasure is only as irreversible as the least-irreversible copy of the key.** This is the thing +that fails an audit: + +- A point-in-time **database restore** brings shredded keys back. Exclude the key table from + long-retention backups, or accept that erasure completes only when the last backup ages out. +- **Key Vault purge protection** keeps a deleted secret recoverable for the retention window, so a + "shredded" subject is not actually erased until it expires. + +Neither is something the framework can enforce; both belong in the deployment's runbook. ## Erasing a subject diff --git a/skills/event-sourcing-subscriptions/SKILL.md b/skills/event-sourcing-subscriptions/SKILL.md index f7207812..21bee27d 100644 --- a/skills/event-sourcing-subscriptions/SKILL.md +++ b/skills/event-sourcing-subscriptions/SKILL.md @@ -99,7 +99,7 @@ Every provider with an event stream ships one - `AddSqlServerSubscriptionCheckpo `AddMongoDBSubscriptionCheckpoints`. Cosmos DB has no event stream, so there is nothing to checkpoint. -If you write your own, encode the scope with `SubscriptionCheckpointTenantColumn` rather than +If you write your own, encode the scope with `TenantColumn` rather than inventing your own scheme, and note two traps the shipped stores had to handle: - **Do not use a nullable tenant column.** PostgreSQL treats NULLs as distinct in a unique index, so diff --git a/src/src/AzureStorage/Subscriptions/AzureStorageSubscriptionCheckpointStore.cs b/src/src/AzureStorage/Subscriptions/AzureStorageSubscriptionCheckpointStore.cs index a81a3f7b..8d388777 100644 --- a/src/src/AzureStorage/Subscriptions/AzureStorageSubscriptionCheckpointStore.cs +++ b/src/src/AzureStorage/Subscriptions/AzureStorageSubscriptionCheckpointStore.cs @@ -3,6 +3,7 @@ using Azure.Data.Tables; using Microsoft.Extensions.Options; using Purview.EventSourcing.Subscriptions; +using Purview.EventSourcing.Tenancy; namespace Purview.EventSourcing.AzureStorage.Subscriptions; @@ -138,7 +139,7 @@ async Task EnsureTableAsync(CancellationToken cancellationToken) // any segment contained the delimiter. Base64Url uses only characters that are legal in a key and // never produces the '|' separator, so the composed key is both legal and unambiguous. static string PartitionKeyFor(SubscriptionCheckpointKey key) => - $"{Encode(key.SubscriptionName)}|{Encode(SubscriptionCheckpointTenantColumn.Encode(key.Scope))}"; + $"{Encode(key.SubscriptionName)}|{Encode(TenantColumn.Encode(key.Scope))}"; static string RowKeyFor(SubscriptionCheckpointKey key) => Encode(key.AggregateId); diff --git a/src/src/EventSourcing/Cryptography/EventCryptoOptions.cs b/src/src/EventSourcing/Cryptography/EventCryptoOptions.cs new file mode 100644 index 00000000..d65d30ce --- /dev/null +++ b/src/src/EventSourcing/Cryptography/EventCryptoOptions.cs @@ -0,0 +1,27 @@ +namespace Purview.EventSourcing.Cryptography; + +/// +/// Configuration for crypto-shredding. +/// +public sealed class EventCryptoOptions +{ + /// The configuration section name used to bind these options. + public const string Section = "EventStore:Cryptography"; + + /// + /// Permits an outside the Development environment. + /// + /// + /// + /// Off by default, and deliberately awkward to turn on. A non-durable key store loses every key + /// on restart, which makes every protected event permanently unreadable - the same outcome as + /// erasing every data subject at once, with no error and no way back. + /// + /// + /// Legitimate uses are a demo, an ephemeral test host, or a deployment that has accepted that + /// consequence in writing. If you are reaching for this to make a start-up failure go away, + /// register a durable key store instead. + /// + /// + public bool AllowNonDurableKeyStore { get; set; } +} diff --git a/src/src/EventSourcing/Cryptography/INonDurableEventCryptoKeyStore.cs b/src/src/EventSourcing/Cryptography/INonDurableEventCryptoKeyStore.cs new file mode 100644 index 00000000..0b7d478e --- /dev/null +++ b/src/src/EventSourcing/Cryptography/INonDurableEventCryptoKeyStore.cs @@ -0,0 +1,26 @@ +using System.Diagnostics.CodeAnalysis; + +namespace Purview.EventSourcing.Cryptography; + +/// +/// Marks an whose keys do not survive a restart. +/// +/// +/// +/// Losing a crypto-shredding key is indistinguishable from erasing it deliberately: every payload +/// encrypted under it becomes permanently unreadable, and nothing reports that it happened. A store +/// marked with this is therefore refused at start-up outside Development unless +/// is set. +/// +/// +/// Implement it on any test double or development store so the guard recognises it. The check is on +/// this marker rather than on a concrete type, so a store the framework has never heard of is still +/// protected by it. +/// +/// +[SuppressMessage( + "Design", + "CA1040:Avoid empty interfaces", + Justification = "A marker is the point: the start-up guard tests for a capability a store declares about itself, rather than for a concrete type it has to know in advance." +)] +public interface INonDurableEventCryptoKeyStore; diff --git a/src/src/EventSourcing/Cryptography/InMemoryEventCryptoKeyStore.cs b/src/src/EventSourcing/Cryptography/InMemoryEventCryptoKeyStore.cs index 8860e643..a97746d0 100644 --- a/src/src/EventSourcing/Cryptography/InMemoryEventCryptoKeyStore.cs +++ b/src/src/EventSourcing/Cryptography/InMemoryEventCryptoKeyStore.cs @@ -10,7 +10,7 @@ namespace Purview.EventSourcing.Cryptography; /// That makes it unusable in production by construction, which is the intent: a key store is the one /// component where a convenient default would be actively harmful. /// -public sealed class InMemoryEventCryptoKeyStore : IEventCryptoKeyStore +public sealed class InMemoryEventCryptoKeyStore : IEventCryptoKeyStore, INonDurableEventCryptoKeyStore { readonly ConcurrentDictionary _keys = new(StringComparer.Ordinal); diff --git a/src/src/EventSourcing/Cryptography/NonDurableKeyStoreStartupCheck.cs b/src/src/EventSourcing/Cryptography/NonDurableKeyStoreStartupCheck.cs new file mode 100644 index 00000000..d1dd9e24 --- /dev/null +++ b/src/src/EventSourcing/Cryptography/NonDurableKeyStoreStartupCheck.cs @@ -0,0 +1,45 @@ +using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Options; + +namespace Purview.EventSourcing.Cryptography; + +/// +/// Refuses to start when crypto-shredding is configured with a key store that cannot survive a +/// restart. +/// +/// +/// The check runs at start-up rather than on first use, so a misconfiguration cannot reach the point +/// where events have already been written under keys that are about to be lost. By then the damage +/// is unrecoverable and silent. +/// +/// The configured key store. +/// The host environment; the check does not apply in Development. +/// The crypto options carrying the explicit override. +public sealed class NonDurableKeyStoreStartupCheck( + IEventCryptoKeyStore keyStore, + IHostEnvironment environment, + IOptions options +) : IHostedService +{ + /// + public Task StartAsync(CancellationToken cancellationToken) + { + if (keyStore is not INonDurableEventCryptoKeyStore) + return Task.CompletedTask; + + if (environment.IsDevelopment() || options.Value.AllowNonDurableKeyStore) + return Task.CompletedTask; + + throw new InvalidOperationException( + $"Crypto-shredding is configured with '{keyStore.GetType().Name}', which does not persist keys across a restart, " + + $"in the '{environment.EnvironmentName}' environment. Every protected event would become permanently " + + "unreadable when this process restarts, which is indistinguishable from erasing every data subject. " + + "Register a durable key store, or set " + + $"'{EventCryptoOptions.Section}:{nameof(EventCryptoOptions.AllowNonDurableKeyStore)}' to true if that " + + "outcome is genuinely acceptable here." + ); + } + + /// + public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask; +} diff --git a/src/src/EventSourcing/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/EventSourcing/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs index 7520ab58..16055e42 100644 --- a/src/src/EventSourcing/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs +++ b/src/src/EventSourcing/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -5,6 +5,7 @@ using Purview.EventSourcing.Aggregates.Events; using Purview.EventSourcing.Aggregates.Events.Upcasting; using Purview.EventSourcing.ChangeFeed; +using Purview.EventSourcing.Cryptography; using Purview.EventSourcing.EventStores.NullQueryable; using Purview.EventSourcing.Manifest; using Purview.EventSourcing.Outbox; @@ -87,6 +88,49 @@ public IServiceCollection AddOutbox( return services; } + /// + /// Registers crypto-shredding: a key store, the AES-GCM payload protector, and a start-up + /// check that refuses a key store which cannot survive a restart. + /// + /// The implementation. + /// Optional configuration. + /// The for chaining. + /// + /// + /// Every provider takes an optional , so registering it here + /// turns protection on for whichever store is configured. Events implementing + /// are then encrypted under that subject's key. + /// + /// + /// Erasing a subject is only as irreversible as the least-irreversible copy of their key: a + /// database restore or a vault's purge protection can both bring one back. See + /// docs/wiki/Crypto-Key-Management-Design.md. + /// + /// + public IServiceCollection AddEventCryptoShredding(Action? configure = null) + where TKeyStore : class, IEventCryptoKeyStore + { + services.TryAddSingleton(); + services.TryAddSingleton(static provider => provider.GetRequiredService()); + services.TryAddSingleton(); + services.AddOptions().Configure(options => configure?.Invoke(options)); + services.AddHostedService(); + + return services; + } + + /// + /// Registers crypto-shredding with the in-memory key store. + /// + /// Optional configuration. + /// The for chaining. + /// + /// For tests and local development only. Keys are lost on restart, so the host refuses to start + /// outside Development unless is set. + /// + public IServiceCollection AddInMemoryEventCryptoShredding(Action? configure = null) => + services.AddEventCryptoShredding(configure); + /// /// Registers a subscriber, its catch-up processor, and a hosted loop that drives it. /// diff --git a/src/src/EventSourcing/Subscriptions/SubscriptionCheckpointTenantColumn.cs b/src/src/EventSourcing/Subscriptions/SubscriptionCheckpointTenantColumn.cs deleted file mode 100644 index 8da47bae..00000000 --- a/src/src/EventSourcing/Subscriptions/SubscriptionCheckpointTenantColumn.cs +++ /dev/null @@ -1,29 +0,0 @@ -using Purview.EventSourcing.Tenancy; - -namespace Purview.EventSourcing.Subscriptions; - -/// -/// Encodes a into the single non-null column a checkpoint store keys on. -/// -/// -/// -/// Shared so every provider encodes the scope identically. A store that invented its own encoding -/// could make one tenant's position collide with another's, or with the system scope's, which would -/// advance a position past events that are then never delivered. -/// -/// -/// The system scope encodes as the empty string. That cannot collide with a real tenant, because -/// rejects a blank identifier. Keeping the column non-null -/// also keeps the unique index free of NULLs, which matters because SQL Server and PostgreSQL -/// disagree about whether NULLs are distinct in a unique index. -/// -/// -public static class SubscriptionCheckpointTenantColumn -{ - /// The value stored for . - public const string SystemValue = ""; - - /// Encodes a scope for storage. - /// The scope to encode. - public static string Encode(TenantScope scope) => scope.IsSystem ? SystemValue : scope.TenantId!; -} diff --git a/src/src/EventSourcing/Tenancy/TenantColumn.cs b/src/src/EventSourcing/Tenancy/TenantColumn.cs new file mode 100644 index 00000000..7acc5452 --- /dev/null +++ b/src/src/EventSourcing/Tenancy/TenantColumn.cs @@ -0,0 +1,27 @@ +namespace Purview.EventSourcing.Tenancy; + +/// +/// Encodes a into the single non-null column a side table keys on. +/// +/// +/// +/// Shared by every subsystem that stores rows keyed by tenant outside the event store itself - +/// subscription checkpoints, crypto keys - so they cannot drift apart. Two encodings of the same +/// concept is how one tenant's row ends up colliding with another's. +/// +/// +/// The system scope encodes as the empty string, which cannot collide with a real tenant because +/// rejects a blank identifier. Keeping the column non-null +/// also keeps a unique index free of NULLs, which matters because SQL Server and PostgreSQL +/// disagree about whether NULLs are distinct in one. +/// +/// +public static class TenantColumn +{ + /// The value stored for . + public const string SystemValue = ""; + + /// Encodes a scope for storage. + /// The scope to encode. + public static string Encode(TenantScope scope) => scope.IsSystem ? SystemValue : scope.TenantId!; +} diff --git a/src/src/MongoDB/Subscriptions/MongoDBSubscriptionCheckpointStore.cs b/src/src/MongoDB/Subscriptions/MongoDBSubscriptionCheckpointStore.cs index b06c0f4e..545bc67a 100644 --- a/src/src/MongoDB/Subscriptions/MongoDBSubscriptionCheckpointStore.cs +++ b/src/src/MongoDB/Subscriptions/MongoDBSubscriptionCheckpointStore.cs @@ -3,6 +3,7 @@ using MongoDB.Driver; using Purview.EventSourcing.MongoDB.Events; using Purview.EventSourcing.Subscriptions; +using Purview.EventSourcing.Tenancy; namespace Purview.EventSourcing.MongoDB.Subscriptions; @@ -101,7 +102,7 @@ static FilterDefinition Filter(SubscriptionCheckpointKey key) => new BsonDocument { ["s"] = key.SubscriptionName, - ["t"] = SubscriptionCheckpointTenantColumn.Encode(key.Scope), + ["t"] = TenantColumn.Encode(key.Scope), ["a"] = key.AggregateId, } ); diff --git a/src/src/Postgres/Cryptography/PostgresEventCryptoKeyStore.cs b/src/src/Postgres/Cryptography/PostgresEventCryptoKeyStore.cs new file mode 100644 index 00000000..f3ecbe7c --- /dev/null +++ b/src/src/Postgres/Cryptography/PostgresEventCryptoKeyStore.cs @@ -0,0 +1,221 @@ +using System.Text.RegularExpressions; +using Microsoft.Extensions.Options; +using Npgsql; +using Purview.EventSourcing.Cryptography; +using Purview.EventSourcing.Postgres.Events; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.Postgres.Cryptography; + +// SQL strings are built from validated identifiers at construction time, not from user input. +#pragma warning disable CA2100 + +/// +/// A durable backed by a PostgreSQL table. +/// +/// +/// +/// Keys are scoped to the current tenant: the same data-subject identifier in two tenants is two +/// different people, so they get two different keys, and neither tenant can read or erase the +/// other's. +/// +/// +/// Erasure is only as irreversible as the least-irreversible copy of the key. A +/// point-in-time restore of this table brings shredded keys back, so a deployment that must erase +/// on request has to exclude it from long-retention backups, or accept that erasure completes only +/// when the last backup containing the key ages out. +/// +/// +public sealed partial class PostgresEventCryptoKeyStore : IEventCryptoKeyStore, IDisposable +{ + [GeneratedRegex("^[\\w\\-.]+$", RegexOptions.Compiled)] + private static partial Regex ValidIdentifier(); + + readonly IOptions _options; + readonly ICurrentTenant _currentTenant; + readonly string _connectionString; + readonly string _schema; + readonly string _table; + readonly SemaphoreSlim _schemaLock = new(1, 1); + bool _schemaEnsured; + + /// Creates the store. + /// The key-store options. + /// The event-store options, used for any value not overridden. + /// The tenant scope keys are read and written under. + public PostgresEventCryptoKeyStore( + IOptions keyStoreOptions, + IOptions eventStoreOptions, + ICurrentTenant? currentTenant = null + ) + { + ArgumentNullException.ThrowIfNull(keyStoreOptions); + ArgumentNullException.ThrowIfNull(eventStoreOptions); + + _options = keyStoreOptions; + _currentTenant = currentTenant ?? new SystemCurrentTenant(); + _connectionString = ResolveConnectionString(keyStoreOptions.Value, eventStoreOptions.Value); + _schema = QuoteIdentifier(keyStoreOptions.Value.SchemaName); + _table = QuoteIdentifier(keyStoreOptions.Value.TableName); + } + + /// + public async Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + await EnsureSchemaAsync(cancellationToken); + + await using NpgsqlConnection connection = new(_connectionString); + await connection.OpenAsync(cancellationToken); + + // Two callers racing to create the first key for a subject must end up with the same one, or + // payloads written by the loser become unreadable. + // + // DO NOTHING is the wrong tool here: it returns no row, and a fallback SELECT in the same + // statement runs against the same snapshot, so it cannot see a row a concurrent transaction + // has just inserted - the loser gets nothing at all. A no-op DO UPDATE takes the lock and + // returns the stored row either way, which is the point. + await using NpgsqlCommand command = new( + $""" + INSERT INTO {_schema}.{_table} ("TenantId", "DataSubjectId", "KeyMaterial", "CreatedUtc") + VALUES (@tenantId, @subject, @key, @now) + ON CONFLICT ("TenantId", "DataSubjectId") DO UPDATE + SET "KeyMaterial" = {_table}."KeyMaterial" + RETURNING "KeyMaterial" + """, + connection + ); + AddKeyParameters(command, dataSubjectId); + command.Parameters.AddWithValue("@key", AesGcmEventPayloadProtector.CreateKey()); + command.Parameters.AddWithValue("@now", DateTimeOffset.UtcNow); + + var result = await command.ExecuteScalarAsync(cancellationToken); + + return result as byte[] + ?? throw new InvalidOperationException( + $"The key for data subject '{dataSubjectId}' could not be read back immediately after being created." + ); + } + + /// + public async Task TryGetAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + await EnsureSchemaAsync(cancellationToken); + + await using NpgsqlConnection connection = new(_connectionString); + await connection.OpenAsync(cancellationToken); + + await using NpgsqlCommand command = new( + $""" + SELECT "KeyMaterial" FROM {_schema}.{_table} + WHERE "TenantId" = @tenantId AND "DataSubjectId" = @subject + """, + connection + ); + AddKeyParameters(command, dataSubjectId); + + var result = await command.ExecuteScalarAsync(cancellationToken); + + return result as byte[]; + } + + /// + public async Task ShredAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + await EnsureSchemaAsync(cancellationToken); + + await using NpgsqlConnection connection = new(_connectionString); + await connection.OpenAsync(cancellationToken); + + await using NpgsqlCommand command = new( + $"""DELETE FROM {_schema}.{_table} WHERE "TenantId" = @tenantId AND "DataSubjectId" = @subject""", + connection + ); + AddKeyParameters(command, dataSubjectId); + + return await command.ExecuteNonQueryAsync(cancellationToken) > 0; + } + + void AddKeyParameters(NpgsqlCommand command, string dataSubjectId) + { + command.Parameters.AddWithValue("@tenantId", TenantColumn.Encode(_currentTenant.Current)); + command.Parameters.AddWithValue("@subject", dataSubjectId); + } + + async Task EnsureSchemaAsync(CancellationToken cancellationToken) + { + if (_schemaEnsured) + return; + + if (_options.Value.AutoCreateTable) + { + // CREATE TABLE IF NOT EXISTS is not safe to run concurrently: PostgreSQL still races on + // the table's implicit row type and raises 23505. + await _schemaLock.WaitAsync(cancellationToken); + try + { + if (_schemaEnsured) + return; + + await using NpgsqlConnection connection = new(_connectionString); + await connection.OpenAsync(cancellationToken); + + await using NpgsqlCommand command = new( + $""" + CREATE TABLE IF NOT EXISTS {_schema}.{_table} ( + "TenantId" VARCHAR(256) NOT NULL, + "DataSubjectId" VARCHAR(256) NOT NULL, + "KeyMaterial" BYTEA NOT NULL, + "CreatedUtc" TIMESTAMPTZ NOT NULL, + PRIMARY KEY ("TenantId", "DataSubjectId") + ); + """, + connection + ); + + try + { + await command.ExecuteNonQueryAsync(cancellationToken); + } + catch (PostgresException ex) when (ex.SqlState is "23505" or "42P07") + { + // Another writer created it first, which is the outcome we wanted anyway. + } + } + finally + { + _schemaLock.Release(); + } + } + + _schemaEnsured = true; + } + + /// + public void Dispose() => _schemaLock.Dispose(); + + static string ResolveConnectionString( + PostgresEventCryptoKeyStoreOptions keyStoreOptions, + PostgresEventStoreOptions eventStoreOptions + ) => + keyStoreOptions.ConnectionString + ?? eventStoreOptions.ConnectionString + ?? throw new InvalidOperationException( + "PostgresEventCryptoKeyStore requires a connection string. Configure 'EventStore:Postgres:Cryptography:ConnectionString' or 'EventStore:Postgres:ConnectionString'." + ); + + static string QuoteIdentifier(string identifier) + { + if (!ValidIdentifier().IsMatch(identifier)) + throw new InvalidOperationException( + $"The crypto key table identifier '{identifier}' is invalid. Identifiers may only contain letters, digits, underscores, dots, and hyphens." + ); + + return $"\"{identifier}\""; + } +} diff --git a/src/src/Postgres/Cryptography/PostgresEventCryptoKeyStoreOptions.cs b/src/src/Postgres/Cryptography/PostgresEventCryptoKeyStoreOptions.cs new file mode 100644 index 00000000..9acd43cb --- /dev/null +++ b/src/src/Postgres/Cryptography/PostgresEventCryptoKeyStoreOptions.cs @@ -0,0 +1,43 @@ +using System.ComponentModel.DataAnnotations; + +namespace Purview.EventSourcing.Postgres.Cryptography; + +/// +/// Options that configure the PostgreSQL crypto key store. +/// +/// +/// Bound from the EventStore:Postgres:Cryptography configuration section. When +/// is not supplied, the event-store connection string is used. +/// +public sealed class PostgresEventCryptoKeyStoreOptions +{ + /// The configuration section name used to bind these options. + public const string PostgresCryptography = "EventStore:Postgres:Cryptography"; + + /// The default table name used to persist per-subject keys. + public const string DefaultTableName = "EventStoreCryptoKeys"; + + /// + /// The connection string used to access the PostgreSQL database. When null, the event-store + /// connection string is used. + /// + /// + /// Pointing this at a separate database is worth considering: the key table's backup policy is + /// what decides how long an erasure takes to become irreversible, and it rarely wants the same + /// retention as the event data it protects. + /// + public string? ConnectionString { get; set; } + + /// The schema that owns the key table. + [Required(AllowEmptyStrings = false)] + [RegularExpression(@"^[\w\-.]+$")] + public string SchemaName { get; set; } = "public"; + + /// The name of the table that stores per-subject keys. + [Required(AllowEmptyStrings = false)] + [RegularExpression(@"^[\w\-.]+$")] + public string TableName { get; set; } = DefaultTableName; + + /// When true, the key table is created if it does not exist. + public bool AutoCreateTable { get; set; } = true; +} diff --git a/src/src/Postgres/Cryptography/PostgresEventCryptoKeyStoreOptionsValidator.cs b/src/src/Postgres/Cryptography/PostgresEventCryptoKeyStoreOptionsValidator.cs new file mode 100644 index 00000000..0cae0317 --- /dev/null +++ b/src/src/Postgres/Cryptography/PostgresEventCryptoKeyStoreOptionsValidator.cs @@ -0,0 +1,20 @@ +using System.ComponentModel.DataAnnotations; +using Microsoft.Extensions.Options; + +namespace Purview.EventSourcing.Postgres.Cryptography; + +sealed class PostgresEventCryptoKeyStoreOptionsValidator : IValidateOptions +{ + public ValidateOptionsResult Validate(string? name, PostgresEventCryptoKeyStoreOptions options) + { + ArgumentNullException.ThrowIfNull(options); + ValidationContext validationContext = new(options); + List validationResults = []; + if (!Validator.TryValidateObject(options, validationContext, validationResults, validateAllProperties: true)) + return ValidateOptionsResult.Fail( + validationResults.Select(static x => x.ErrorMessage ?? "Options validation failed.") + ); + + return ValidateOptionsResult.Success; + } +} diff --git a/src/src/Postgres/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/Postgres/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs index 64dd6535..da16b5d3 100644 --- a/src/src/Postgres/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs +++ b/src/src/Postgres/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -2,8 +2,10 @@ using Microsoft.Extensions.Configuration; using Microsoft.Extensions.DependencyInjection.Extensions; using Microsoft.Extensions.Options; +using Purview.EventSourcing.Cryptography; using Purview.EventSourcing.Internal; using Purview.EventSourcing.Outbox; +using Purview.EventSourcing.Postgres.Cryptography; using Purview.EventSourcing.Postgres.Events; using Purview.EventSourcing.Postgres.Outbox; using Purview.EventSourcing.Postgres.Snapshot; @@ -259,5 +261,36 @@ public IServiceCollection AddPostgresSubscriptionCheckpoints() return services; } + + /// + /// Registers crypto-shredding backed by a durable PostgreSQL key table. + /// + /// Optional configuration. + /// The for chaining. + /// + /// Keys are scoped to the current tenant and survive a restart, so this is what makes + /// crypto-shredding usable in a deployed application. Note that a point-in-time restore of the + /// key table brings shredded keys back; see docs/wiki/Crypto-Key-Management-Design.md. + /// + public IServiceCollection AddPostgresEventCryptoShredding(Action? configure = null) + { + services.AddEventCryptoShredding(configure); + + services + .AddOptions() + .Configure( + (options, configuration) => + configuration.GetSection(PostgresEventCryptoKeyStoreOptions.PostgresCryptography).Bind(options) + ); + + services.TryAddEnumerable( + ServiceDescriptor.Singleton< + IValidateOptions, + PostgresEventCryptoKeyStoreOptionsValidator + >() + ); + + return services; + } } } diff --git a/src/src/Postgres/Subscriptions/PostgresSubscriptionCheckpointStore.cs b/src/src/Postgres/Subscriptions/PostgresSubscriptionCheckpointStore.cs index b12a6130..4831fe2e 100644 --- a/src/src/Postgres/Subscriptions/PostgresSubscriptionCheckpointStore.cs +++ b/src/src/Postgres/Subscriptions/PostgresSubscriptionCheckpointStore.cs @@ -3,6 +3,7 @@ using Npgsql; using Purview.EventSourcing.Postgres.Events; using Purview.EventSourcing.Subscriptions; +using Purview.EventSourcing.Tenancy; namespace Purview.EventSourcing.Postgres.Subscriptions; @@ -83,7 +84,7 @@ ON CONFLICT ("SubscriptionName", "TenantId", "AggregateId") DO UPDATE static void AddKeyParameters(NpgsqlCommand command, SubscriptionCheckpointKey key) { command.Parameters.AddWithValue("@name", key.SubscriptionName); - command.Parameters.AddWithValue("@tenantId", SubscriptionCheckpointTenantColumn.Encode(key.Scope)); + command.Parameters.AddWithValue("@tenantId", TenantColumn.Encode(key.Scope)); command.Parameters.AddWithValue("@aggregateId", key.AggregateId); } diff --git a/src/src/SqlServer/Cryptography/SqlServerEventCryptoKeyStore.cs b/src/src/SqlServer/Cryptography/SqlServerEventCryptoKeyStore.cs new file mode 100644 index 00000000..18634015 --- /dev/null +++ b/src/src/SqlServer/Cryptography/SqlServerEventCryptoKeyStore.cs @@ -0,0 +1,234 @@ +using System.Text.RegularExpressions; +using Microsoft.Data.SqlClient; +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Cryptography; +using Purview.EventSourcing.SqlServer.Events; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.SqlServer.Cryptography; + +// SQL strings are built from validated identifiers at construction time, not from user input. +#pragma warning disable CA2100 + +/// +/// A durable backed by a SQL Server table. +/// +/// +/// +/// Keys are scoped to the current tenant: the same data-subject identifier in two tenants is two +/// different people, so they get two different keys, and neither tenant can read or erase the +/// other's. +/// +/// +/// Erasure is only as irreversible as the least-irreversible copy of the key. A +/// point-in-time restore of this table brings shredded keys back, so a deployment that must erase +/// on request has to exclude it from long-retention backups, or accept that erasure completes only +/// when the last backup containing the key ages out. +/// +/// +public sealed partial class SqlServerEventCryptoKeyStore : IEventCryptoKeyStore, IDisposable +{ + [GeneratedRegex("^[\\w\\-.]+$", RegexOptions.Compiled)] + private static partial Regex ValidIdentifier(); + + readonly IOptions _options; + readonly ICurrentTenant _currentTenant; + readonly string _connectionString; + readonly string _schema; + readonly string _table; + readonly SemaphoreSlim _schemaLock = new(1, 1); + bool _schemaEnsured; + + /// Creates the store. + /// The key-store options. + /// The event-store options, used for any value not overridden. + /// The tenant scope keys are read and written under. + public SqlServerEventCryptoKeyStore( + IOptions keyStoreOptions, + IOptions eventStoreOptions, + ICurrentTenant? currentTenant = null + ) + { + ArgumentNullException.ThrowIfNull(keyStoreOptions); + ArgumentNullException.ThrowIfNull(eventStoreOptions); + + _options = keyStoreOptions; + _currentTenant = currentTenant ?? new SystemCurrentTenant(); + _connectionString = ResolveConnectionString(keyStoreOptions.Value, eventStoreOptions.Value); + _schema = QuoteIdentifier(keyStoreOptions.Value.SchemaName); + _table = QuoteIdentifier(keyStoreOptions.Value.TableName); + } + + /// + public async Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + var existing = await TryGetAsync(dataSubjectId, cancellationToken); + if (existing is not null) + return existing; + + var key = AesGcmEventPayloadProtector.CreateKey(); + + await using SqlConnection connection = new(_connectionString); + await connection.OpenAsync(cancellationToken); + + // Insert-if-absent, then re-read: two callers racing to create the first key for a subject + // must end up with the same key, or payloads written by the loser become unreadable. + await using SqlCommand command = new( + $""" + IF NOT EXISTS ( + SELECT 1 FROM {_schema}.{_table} WHERE [TenantId] = @tenantId AND [DataSubjectId] = @subject + ) + BEGIN + BEGIN TRY + INSERT INTO {_schema}.{_table} ([TenantId], [DataSubjectId], [KeyMaterial], [CreatedUtc]) + VALUES (@tenantId, @subject, @key, @now); + END TRY + BEGIN CATCH + IF ERROR_NUMBER() NOT IN (2601, 2627) THROW; + END CATCH + END + """, + connection + ); + AddKeyParameters(command, dataSubjectId); + command.Parameters.AddWithValue("@key", key); + command.Parameters.AddWithValue("@now", DateTimeOffset.UtcNow); + + await command.ExecuteNonQueryAsync(cancellationToken); + + return await TryGetAsync(dataSubjectId, cancellationToken) + ?? throw new InvalidOperationException( + $"The key for data subject '{dataSubjectId}' could not be read back immediately after being created." + ); + } + + /// + public async Task TryGetAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + await EnsureSchemaAsync(cancellationToken); + + await using SqlConnection connection = new(_connectionString); + await connection.OpenAsync(cancellationToken); + + await using SqlCommand command = new( + $""" + SELECT [KeyMaterial] FROM {_schema}.{_table} + WHERE [TenantId] = @tenantId AND [DataSubjectId] = @subject + """, + connection + ); + AddKeyParameters(command, dataSubjectId); + + var result = await command.ExecuteScalarAsync(cancellationToken); + + return result as byte[]; + } + + /// + public async Task ShredAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + await EnsureSchemaAsync(cancellationToken); + + await using SqlConnection connection = new(_connectionString); + await connection.OpenAsync(cancellationToken); + + await using SqlCommand command = new( + $"DELETE FROM {_schema}.{_table} WHERE [TenantId] = @tenantId AND [DataSubjectId] = @subject", + connection + ); + AddKeyParameters(command, dataSubjectId); + + return await command.ExecuteNonQueryAsync(cancellationToken) > 0; + } + + void AddKeyParameters(SqlCommand command, string dataSubjectId) + { + command.Parameters.AddWithValue("@tenantId", TenantColumn.Encode(_currentTenant.Current)); + command.Parameters.AddWithValue("@subject", dataSubjectId); + } + + async Task EnsureSchemaAsync(CancellationToken cancellationToken) + { + if (_schemaEnsured) + return; + + if (_options.Value.AutoCreateTable) + { + await _schemaLock.WaitAsync(cancellationToken); + try + { + if (_schemaEnsured) + return; + + await EnsureSchemaCoreAsync(cancellationToken); + } + finally + { + _schemaLock.Release(); + } + } + + _schemaEnsured = true; + } + + async Task EnsureSchemaCoreAsync(CancellationToken cancellationToken) + { + await using SqlConnection connection = new(_connectionString); + await connection.OpenAsync(cancellationToken); + + var indexName = QuoteIdentifier($"UX_{_options.Value.TableName}_Subject"); + + // 2714 is "object already exists": another process won the race between the OBJECT_ID check + // and the CREATE, which is the outcome we wanted anyway. + await using SqlCommand command = new( + $""" + BEGIN TRY + IF OBJECT_ID(N'{_schema}.{_table}', N'U') IS NULL + BEGIN + CREATE TABLE {_schema}.{_table} ( + [TenantId] NVARCHAR(256) NOT NULL, + [DataSubjectId] NVARCHAR(256) NOT NULL, + [KeyMaterial] VARBINARY(256) NOT NULL, + [CreatedUtc] DATETIMEOFFSET NOT NULL + ); + CREATE UNIQUE INDEX {indexName} ON {_schema}.{_table} ([TenantId], [DataSubjectId]); + END + END TRY + BEGIN CATCH + IF ERROR_NUMBER() <> 2714 THROW; + END CATCH + """, + connection + ); + await command.ExecuteNonQueryAsync(cancellationToken); + } + + /// + public void Dispose() => _schemaLock.Dispose(); + + static string ResolveConnectionString( + SqlServerEventCryptoKeyStoreOptions keyStoreOptions, + SqlServerEventStoreOptions eventStoreOptions + ) => + keyStoreOptions.ConnectionString + ?? eventStoreOptions.ConnectionString + ?? throw new InvalidOperationException( + "SqlServerEventCryptoKeyStore requires a connection string. Configure 'EventStore:SqlServer:Cryptography:ConnectionString' or 'EventStore:SqlServer:ConnectionString'." + ); + + static string QuoteIdentifier(string identifier) + { + if (!ValidIdentifier().IsMatch(identifier)) + throw new InvalidOperationException( + $"The crypto key table identifier '{identifier}' is invalid. Identifiers may only contain letters, digits, underscores, dots, and hyphens." + ); + + return $"[{identifier}]"; + } +} diff --git a/src/src/SqlServer/Cryptography/SqlServerEventCryptoKeyStoreOptions.cs b/src/src/SqlServer/Cryptography/SqlServerEventCryptoKeyStoreOptions.cs new file mode 100644 index 00000000..ca58bbbe --- /dev/null +++ b/src/src/SqlServer/Cryptography/SqlServerEventCryptoKeyStoreOptions.cs @@ -0,0 +1,43 @@ +using System.ComponentModel.DataAnnotations; + +namespace Purview.EventSourcing.SqlServer.Cryptography; + +/// +/// Options that configure the SQL Server crypto key store. +/// +/// +/// Bound from the EventStore:SqlServer:Cryptography configuration section. When +/// is not supplied, the event-store connection string is used. +/// +public sealed class SqlServerEventCryptoKeyStoreOptions +{ + /// The configuration section name used to bind these options. + public const string SqlServerCryptography = "EventStore:SqlServer:Cryptography"; + + /// The default table name used to persist per-subject keys. + public const string DefaultTableName = "EventStoreCryptoKeys"; + + /// + /// The connection string used to access the SQL Server database. When null, the event-store + /// connection string is used. + /// + /// + /// Pointing this at a separate database is worth considering: the key table's backup policy is + /// what decides how long an erasure takes to become irreversible, and it rarely wants the same + /// retention as the event data it protects. + /// + public string? ConnectionString { get; set; } + + /// The schema that owns the key table. + [Required(AllowEmptyStrings = false)] + [RegularExpression(@"^[\w\-.]+$")] + public string SchemaName { get; set; } = "dbo"; + + /// The name of the table that stores per-subject keys. + [Required(AllowEmptyStrings = false)] + [RegularExpression(@"^[\w\-.]+$")] + public string TableName { get; set; } = DefaultTableName; + + /// When true, the key table is created if it does not exist. + public bool AutoCreateTable { get; set; } = true; +} diff --git a/src/src/SqlServer/Cryptography/SqlServerEventCryptoKeyStoreOptionsValidator.cs b/src/src/SqlServer/Cryptography/SqlServerEventCryptoKeyStoreOptionsValidator.cs new file mode 100644 index 00000000..aea2ee3c --- /dev/null +++ b/src/src/SqlServer/Cryptography/SqlServerEventCryptoKeyStoreOptionsValidator.cs @@ -0,0 +1,20 @@ +using System.ComponentModel.DataAnnotations; +using Microsoft.Extensions.Options; + +namespace Purview.EventSourcing.SqlServer.Cryptography; + +sealed class SqlServerEventCryptoKeyStoreOptionsValidator : IValidateOptions +{ + public ValidateOptionsResult Validate(string? name, SqlServerEventCryptoKeyStoreOptions options) + { + ArgumentNullException.ThrowIfNull(options); + ValidationContext validationContext = new(options); + List validationResults = []; + if (!Validator.TryValidateObject(options, validationContext, validationResults, validateAllProperties: true)) + return ValidateOptionsResult.Fail( + validationResults.Select(static x => x.ErrorMessage ?? "Options validation failed.") + ); + + return ValidateOptionsResult.Success; + } +} diff --git a/src/src/SqlServer/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/SqlServer/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs index 4d42ac78..f0bdaa80 100644 --- a/src/src/SqlServer/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs +++ b/src/src/SqlServer/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -2,8 +2,10 @@ using Microsoft.Extensions.Configuration; using Microsoft.Extensions.DependencyInjection.Extensions; using Microsoft.Extensions.Options; +using Purview.EventSourcing.Cryptography; using Purview.EventSourcing.Internal; using Purview.EventSourcing.Outbox; +using Purview.EventSourcing.SqlServer.Cryptography; using Purview.EventSourcing.SqlServer.Events; using Purview.EventSourcing.SqlServer.Outbox; using Purview.EventSourcing.SqlServer.Snapshot; @@ -267,5 +269,38 @@ public IServiceCollection AddSqlServerSubscriptionCheckpoints() return services; } + + /// + /// Registers crypto-shredding backed by a durable SQL Server key table. + /// + /// Optional configuration. + /// The for chaining. + /// + /// Keys are scoped to the current tenant and survive a restart, so this is what makes + /// crypto-shredding usable in a deployed application. Note that a point-in-time restore of the + /// key table brings shredded keys back; see docs/wiki/Crypto-Key-Management-Design.md. + /// + public IServiceCollection AddSqlServerEventCryptoShredding(Action? configure = null) + { + services.AddEventCryptoShredding(configure); + + services + .AddOptions() + .Configure( + (options, configuration) => + configuration + .GetSection(SqlServerEventCryptoKeyStoreOptions.SqlServerCryptography) + .Bind(options) + ); + + services.TryAddEnumerable( + ServiceDescriptor.Singleton< + IValidateOptions, + SqlServerEventCryptoKeyStoreOptionsValidator + >() + ); + + return services; + } } } diff --git a/src/src/SqlServer/Subscriptions/SqlServerSubscriptionCheckpointStore.cs b/src/src/SqlServer/Subscriptions/SqlServerSubscriptionCheckpointStore.cs index c6d3ef5c..1a0dfc90 100644 --- a/src/src/SqlServer/Subscriptions/SqlServerSubscriptionCheckpointStore.cs +++ b/src/src/SqlServer/Subscriptions/SqlServerSubscriptionCheckpointStore.cs @@ -3,6 +3,7 @@ using Microsoft.Extensions.Options; using Purview.EventSourcing.SqlServer.Events; using Purview.EventSourcing.Subscriptions; +using Purview.EventSourcing.Tenancy; namespace Purview.EventSourcing.SqlServer.Subscriptions; @@ -99,7 +100,7 @@ END CATCH static void AddKeyParameters(SqlCommand command, SubscriptionCheckpointKey key) { command.Parameters.AddWithValue("@name", key.SubscriptionName); - command.Parameters.AddWithValue("@tenantId", SubscriptionCheckpointTenantColumn.Encode(key.Scope)); + command.Parameters.AddWithValue("@tenantId", TenantColumn.Encode(key.Scope)); command.Parameters.AddWithValue("@aggregateId", key.AggregateId); } diff --git a/src/tests/EventSourcing.UnitTests/Cryptography/NonDurableKeyStoreStartupCheckTests.cs b/src/tests/EventSourcing.UnitTests/Cryptography/NonDurableKeyStoreStartupCheckTests.cs new file mode 100644 index 00000000..700c5ebd --- /dev/null +++ b/src/tests/EventSourcing.UnitTests/Cryptography/NonDurableKeyStoreStartupCheckTests.cs @@ -0,0 +1,117 @@ +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Options; + +namespace Purview.EventSourcing.Cryptography; + +/// +/// The start-up guard that refuses a key store which cannot survive a restart. +/// +/// +/// Losing the keys is indistinguishable from erasing every data subject, and nothing reports that it +/// happened - so the only safe moment to object is before the host starts, and before any event has +/// been written under a key that is about to be lost. +/// +public sealed class NonDurableKeyStoreStartupCheckTests +{ + [Test] + public async Task StartAsync_GivenANonDurableStoreInProduction_Throws() + { + var check = CreateCheck(new InMemoryEventCryptoKeyStore(), "Production"); + + await Assert + .That(async () => await check.StartAsync(CancellationToken.None)) + .Throws(); + } + + [Test] + public async Task StartAsync_GivenANonDurableStoreInDevelopment_DoesNotThrow() + { + var check = CreateCheck(new InMemoryEventCryptoKeyStore(), "Development"); + + await Assert.That(async () => await check.StartAsync(CancellationToken.None)).ThrowsNothing(); + } + + [Test] + public async Task StartAsync_GivenANonDurableStoreAndTheExplicitOverride_DoesNotThrow() + { + var check = CreateCheck(new InMemoryEventCryptoKeyStore(), "Production", allowNonDurable: true); + + await Assert.That(async () => await check.StartAsync(CancellationToken.None)).ThrowsNothing(); + } + + [Test] + public async Task StartAsync_GivenADurableStoreInProduction_DoesNotThrow() + { + var check = CreateCheck(new DurableKeyStoreStub(), "Production"); + + await Assert.That(async () => await check.StartAsync(CancellationToken.None)).ThrowsNothing(); + } + + // The message is what an operator acts on at 3am, so it has to name the store, the environment + // and the way out. + [Test] + public async Task StartAsync_WhenItRefuses_ExplainsWhatToDo() + { + var check = CreateCheck(new InMemoryEventCryptoKeyStore(), "Production"); + + var exception = await Assert + .That(async () => await check.StartAsync(CancellationToken.None)) + .Throws(); + + await Assert.That(exception!.Message).Contains(nameof(InMemoryEventCryptoKeyStore)); + await Assert.That(exception.Message).Contains("Production"); + await Assert.That(exception.Message).Contains(nameof(EventCryptoOptions.AllowNonDurableKeyStore)); + } + + // The guard is only useful if it is wired by the registration everyone uses. + [Test] + public async Task AddInMemoryEventCryptoShredding_RegistersTheGuardAndTheProtector() + { + ServiceCollection services = new(); + services.AddLogging(); + services.AddSingleton(new HostEnvironmentStub("Production")); + services.AddEventSourcing().AddInMemoryEventCryptoShredding(); + + await using var provider = services.BuildServiceProvider(); + + await Assert.That(provider.GetService()).IsNotNull(); + await Assert.That(provider.GetServices().OfType()).IsNotEmpty(); + } + + static NonDurableKeyStoreStartupCheck CreateCheck( + IEventCryptoKeyStore keyStore, + string environmentName, + bool allowNonDurable = false + ) => + new( + keyStore, + new HostEnvironmentStub(environmentName), + Options.Create(new EventCryptoOptions { AllowNonDurableKeyStore = allowNonDurable }) + ); + + sealed class HostEnvironmentStub(string environmentName) : IHostEnvironment + { + public string EnvironmentName { get; set; } = environmentName; + + public string ApplicationName { get; set; } = "Tests"; + + public string ContentRootPath { get; set; } = AppContext.BaseDirectory; + + public Microsoft.Extensions.FileProviders.IFileProvider ContentRootFileProvider { get; set; } = + new Microsoft.Extensions.FileProviders.NullFileProvider(); + } + + // Durable by omission: it does not carry the non-durable marker. + sealed class DurableKeyStoreStub : IEventCryptoKeyStore + { + public Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) => + Task.FromResult(AesGcmEventPayloadProtector.CreateKey()); + + public Task TryGetAsync(string dataSubjectId, CancellationToken cancellationToken) => + Task.FromResult(null); + + public Task ShredAsync(string dataSubjectId, CancellationToken cancellationToken) => + Task.FromResult(false); + } +} diff --git a/src/tests/Postgres.IntegrationTests/Cryptography/PostgresEventCryptoKeyStoreTests.cs b/src/tests/Postgres.IntegrationTests/Cryptography/PostgresEventCryptoKeyStoreTests.cs new file mode 100644 index 00000000..eecb77a3 --- /dev/null +++ b/src/tests/Postgres.IntegrationTests/Cryptography/PostgresEventCryptoKeyStoreTests.cs @@ -0,0 +1,158 @@ +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Cryptography; +using Purview.EventSourcing.Fixtures.Postgres; +using Purview.EventSourcing.Postgres.Events; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.Postgres.Cryptography; + +/// +/// The durable crypto key store against real PostgreSQL. +/// +/// +/// Tenant separation comes first. A key is the most sensitive row in the system: reading another +/// tenant's key reads all of their protected events, and erasing it destroys their data +/// irreversibly. The same data-subject identifier in two tenants is two different people. +/// +[ClassDataSource(Shared = SharedType.PerTestSession)] +public sealed class PostgresEventCryptoKeyStoreTests(PostgresEventStoreFixture fixture) +{ + [Test] + public async Task TryGetAsync_GivenAnotherTenantsSubject_DoesNotReturnTheKey(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + + var other = await AsTenantAsync("globex", () => store.TryGetAsync(subject, cancellationToken)); + + await Assert.That(other).IsNull(); + } + + [Test] + public async Task GetOrCreateAsync_GivenTheSameSubjectInTwoTenants_CreatesDifferentKeys( + CancellationToken cancellationToken + ) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var acme = await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + var globex = await AsTenantAsync("globex", () => store.GetOrCreateAsync(subject, cancellationToken)); + + await Assert.That(acme).IsNotEquivalentTo(globex); + } + + // Erasing one tenant's subject must not erase another tenant's subject of the same name. + [Test] + public async Task ShredAsync_GivenAnotherTenantsSubject_LeavesTheOwnersKeyIntact( + CancellationToken cancellationToken + ) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var owner = await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + var shredded = await AsTenantAsync("globex", () => store.ShredAsync(subject, cancellationToken)); + var stillThere = await AsTenantAsync("acme", () => store.TryGetAsync(subject, cancellationToken)); + + await Assert.That(shredded).IsFalse(); + await Assert.That(stillThere).IsEquivalentTo(owner); + } + + [Test] + public async Task GetOrCreateAsync_CalledTwice_ReturnsTheSameKey(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var first = await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + var second = await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + + await Assert.That(first).IsEquivalentTo(second); + } + + // Concurrent first-use must converge on one key. If two callers each created their own, whichever + // lost would have written payloads nothing can decrypt. + [Test] + public async Task GetOrCreateAsync_GivenConcurrentFirstUse_ConvergesOnOneKey(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var keys = await AsTenantAsync( + "acme", + async () => + await Task.WhenAll( + Enumerable.Range(0, 8).Select(_ => store.GetOrCreateAsync(subject, cancellationToken)) + ) + ); + + await Assert.That(keys.Select(Convert.ToBase64String).Distinct().Count()).IsEqualTo(1); + } + + [Test] + public async Task ShredAsync_GivenAnExistingKey_RemovesItPermanently(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + var shredded = await AsTenantAsync("acme", () => store.ShredAsync(subject, cancellationToken)); + var afterwards = await AsTenantAsync("acme", () => store.TryGetAsync(subject, cancellationToken)); + + await Assert.That(shredded).IsTrue(); + await Assert.That(afterwards).IsNull(); + } + + [Test] + public async Task ShredAsync_GivenNoKey_ReportsThatNothingWasErased(CancellationToken cancellationToken) + { + using var store = CreateStore(); + + var shredded = await AsTenantAsync("acme", () => store.ShredAsync($"{Guid.NewGuid():N}", cancellationToken)); + + await Assert.That(shredded).IsFalse(); + } + + // End to end: the key store is only useful if shredding actually makes a payload unreadable. + [Test] + public async Task UnprotectAsync_AfterTheKeyIsShredded_ReportsErasure(CancellationToken cancellationToken) + { + using var store = CreateStore(); + AesGcmEventPayloadProtector protector = new(store); + var subject = $"{Guid.NewGuid():N}"; + + var protectedPayload = await AsTenantAsync( + "acme", + () => protector.ProtectAsync("""{"name":"a-distinctive-value"}""", subject, cancellationToken) + ); + + var before = await AsTenantAsync("acme", () => protector.UnprotectAsync(protectedPayload, cancellationToken)); + await AsTenantAsync("acme", () => store.ShredAsync(subject, cancellationToken)); + var after = await AsTenantAsync("acme", () => protector.UnprotectAsync(protectedPayload, cancellationToken)); + + await Assert.That(before).IsEqualTo("""{"name":"a-distinctive-value"}"""); + await Assert.That(after).IsNull(); + } + + static async Task AsTenantAsync(string tenant, Func> operation) + { + using (AmbientCurrentTenant.BeginScope(TenantScope.For(tenant))) + return await operation(); + } + + PostgresEventCryptoKeyStore CreateStore() => + new( + Options.Create( + new PostgresEventCryptoKeyStoreOptions + { + ConnectionString = fixture.ConnectionString, + TableName = $"CryptoKeys_{Guid.NewGuid():N}", + } + ), + Options.Create(new PostgresEventStoreOptions { ConnectionString = fixture.ConnectionString }), + new AmbientCurrentTenant() + ); +} diff --git a/src/tests/SqlServer.IntegrationTests/Cryptography/SqlServerEventCryptoKeyStoreTests.cs b/src/tests/SqlServer.IntegrationTests/Cryptography/SqlServerEventCryptoKeyStoreTests.cs new file mode 100644 index 00000000..af7e7539 --- /dev/null +++ b/src/tests/SqlServer.IntegrationTests/Cryptography/SqlServerEventCryptoKeyStoreTests.cs @@ -0,0 +1,158 @@ +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Cryptography; +using Purview.EventSourcing.Fixtures.SqlServer; +using Purview.EventSourcing.SqlServer.Events; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.SqlServer.Cryptography; + +/// +/// The durable crypto key store against real SQL Server. +/// +/// +/// Tenant separation comes first. A key is the most sensitive row in the system: reading another +/// tenant's key reads all of their protected events, and erasing it destroys their data +/// irreversibly. The same data-subject identifier in two tenants is two different people. +/// +[ClassDataSource(Shared = SharedType.PerTestSession)] +public sealed class SqlServerEventCryptoKeyStoreTests(SqlServerEventStoreFixture fixture) +{ + [Test] + public async Task TryGetAsync_GivenAnotherTenantsSubject_DoesNotReturnTheKey(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + + var other = await AsTenantAsync("globex", () => store.TryGetAsync(subject, cancellationToken)); + + await Assert.That(other).IsNull(); + } + + [Test] + public async Task GetOrCreateAsync_GivenTheSameSubjectInTwoTenants_CreatesDifferentKeys( + CancellationToken cancellationToken + ) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var acme = await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + var globex = await AsTenantAsync("globex", () => store.GetOrCreateAsync(subject, cancellationToken)); + + await Assert.That(acme).IsNotEquivalentTo(globex); + } + + // Erasing one tenant's subject must not erase another tenant's subject of the same name. + [Test] + public async Task ShredAsync_GivenAnotherTenantsSubject_LeavesTheOwnersKeyIntact( + CancellationToken cancellationToken + ) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var owner = await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + var shredded = await AsTenantAsync("globex", () => store.ShredAsync(subject, cancellationToken)); + var stillThere = await AsTenantAsync("acme", () => store.TryGetAsync(subject, cancellationToken)); + + await Assert.That(shredded).IsFalse(); + await Assert.That(stillThere).IsEquivalentTo(owner); + } + + [Test] + public async Task GetOrCreateAsync_CalledTwice_ReturnsTheSameKey(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var first = await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + var second = await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + + await Assert.That(first).IsEquivalentTo(second); + } + + // Concurrent first-use must converge on one key. If two callers each created their own, whichever + // lost would have written payloads nothing can decrypt. + [Test] + public async Task GetOrCreateAsync_GivenConcurrentFirstUse_ConvergesOnOneKey(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var keys = await AsTenantAsync( + "acme", + async () => + await Task.WhenAll( + Enumerable.Range(0, 8).Select(_ => store.GetOrCreateAsync(subject, cancellationToken)) + ) + ); + + await Assert.That(keys.Select(Convert.ToBase64String).Distinct().Count()).IsEqualTo(1); + } + + [Test] + public async Task ShredAsync_GivenAnExistingKey_RemovesItPermanently(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + var shredded = await AsTenantAsync("acme", () => store.ShredAsync(subject, cancellationToken)); + var afterwards = await AsTenantAsync("acme", () => store.TryGetAsync(subject, cancellationToken)); + + await Assert.That(shredded).IsTrue(); + await Assert.That(afterwards).IsNull(); + } + + [Test] + public async Task ShredAsync_GivenNoKey_ReportsThatNothingWasErased(CancellationToken cancellationToken) + { + using var store = CreateStore(); + + var shredded = await AsTenantAsync("acme", () => store.ShredAsync($"{Guid.NewGuid():N}", cancellationToken)); + + await Assert.That(shredded).IsFalse(); + } + + // End to end: the key store is only useful if shredding actually makes a payload unreadable. + [Test] + public async Task UnprotectAsync_AfterTheKeyIsShredded_ReportsErasure(CancellationToken cancellationToken) + { + using var store = CreateStore(); + AesGcmEventPayloadProtector protector = new(store); + var subject = $"{Guid.NewGuid():N}"; + + var protectedPayload = await AsTenantAsync( + "acme", + () => protector.ProtectAsync("""{"name":"a-distinctive-value"}""", subject, cancellationToken) + ); + + var before = await AsTenantAsync("acme", () => protector.UnprotectAsync(protectedPayload, cancellationToken)); + await AsTenantAsync("acme", () => store.ShredAsync(subject, cancellationToken)); + var after = await AsTenantAsync("acme", () => protector.UnprotectAsync(protectedPayload, cancellationToken)); + + await Assert.That(before).IsEqualTo("""{"name":"a-distinctive-value"}"""); + await Assert.That(after).IsNull(); + } + + static async Task AsTenantAsync(string tenant, Func> operation) + { + using (AmbientCurrentTenant.BeginScope(TenantScope.For(tenant))) + return await operation(); + } + + SqlServerEventCryptoKeyStore CreateStore() => + new( + Options.Create( + new SqlServerEventCryptoKeyStoreOptions + { + ConnectionString = fixture.ConnectionString, + TableName = $"CryptoKeys_{Guid.NewGuid():N}", + } + ), + Options.Create(new SqlServerEventStoreOptions { ConnectionString = fixture.ConnectionString }), + new AmbientCurrentTenant() + ); +} From 42e7648e4e8d76c4bd042c5af8fc370a55c2a1d1 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Mon, 26 Oct 2026 11:10:17 +0000 Subject: [PATCH 19/41] feat: durable crypto key stores for Azure Storage and MongoDB Completes durable key storage for every provider that persists an event stream, so crypto-shredding is no longer viable on the SQL providers only. Cosmos DB has no event stream, so there is nothing to protect. Each engine expresses atomic get-or-create differently, and getting it wrong is not a performance problem: two callers each generating their own key means payloads written by the loser can never be decrypted. Azure adds the entity and re-reads on 409; MongoDB uses $setOnInsert with an upsert and ReturnDocument.After, which is atomic without a second round trip. Tenant scoping is structural rather than filtered - the tenant is part of Azure's partition key and of Mongo's compound _id - so a query cannot forget it. Verified by sabotage: collapsing the scope fails three tests per provider. Also lifts Azure's Base64Url key encoder out of the subscription checkpoint store into a shared helper, for the same reason the tenant column was shared: a second copy is how two side tables drift into colliding keys. Documents the erasure caveat per provider, since each has its own way of bringing a shredded key back - Azure soft delete and point-in-time restore, a Mongo replica lagging the delete, a SQL point-in-time restore. --- docs/wiki/Guarantees-and-Limitations.md | 4 +- docs/wiki/Provider-Feature-Matrix.md | 2 +- .../event-sourcing-crypto-shredding/SKILL.md | 6 +- src/src/AzureStorage/AzureTableKeyEncoding.cs | 29 +++ .../AzureStorageEventCryptoKeyStore.cs | 168 ++++++++++++++++++ .../AzureStorageEventCryptoKeyStoreOptions.cs | 35 ++++ ...rageEventCryptoKeyStoreOptionsValidator.cs | 20 +++ .../ServiceCollectionExtensions.cs | 35 ++++ ...AzureStorageSubscriptionCheckpointStore.cs | 11 +- .../MongoDBEventCryptoKeyStore.cs | 120 +++++++++++++ .../MongoDBEventCryptoKeyStoreOptions.cs | 36 ++++ ...goDBEventCryptoKeyStoreOptionsValidator.cs | 20 +++ .../ServiceCollectionExtensions.cs | 33 ++++ .../AzureStorageEventCryptoKeyStoreTests.cs | 157 ++++++++++++++++ .../MongoDBEventCryptoKeyStoreTests.cs | 161 +++++++++++++++++ 15 files changed, 825 insertions(+), 12 deletions(-) create mode 100644 src/src/AzureStorage/AzureTableKeyEncoding.cs create mode 100644 src/src/AzureStorage/Cryptography/AzureStorageEventCryptoKeyStore.cs create mode 100644 src/src/AzureStorage/Cryptography/AzureStorageEventCryptoKeyStoreOptions.cs create mode 100644 src/src/AzureStorage/Cryptography/AzureStorageEventCryptoKeyStoreOptionsValidator.cs create mode 100644 src/src/MongoDB/Cryptography/MongoDBEventCryptoKeyStore.cs create mode 100644 src/src/MongoDB/Cryptography/MongoDBEventCryptoKeyStoreOptions.cs create mode 100644 src/src/MongoDB/Cryptography/MongoDBEventCryptoKeyStoreOptionsValidator.cs create mode 100644 src/tests/AzureStorage.IntegrationTests/Cryptography/AzureStorageEventCryptoKeyStoreTests.cs create mode 100644 src/tests/MongoDB.IntegrationTests/Cryptography/MongoDBEventCryptoKeyStoreTests.cs diff --git a/docs/wiki/Guarantees-and-Limitations.md b/docs/wiki/Guarantees-and-Limitations.md index 54d73fbb..656be5b9 100644 --- a/docs/wiki/Guarantees-and-Limitations.md +++ b/docs/wiki/Guarantees-and-Limitations.md @@ -105,7 +105,9 @@ they get two different keys, and neither tenant can read or erase the other's. | In-memory | `AddInMemoryEventCryptoShredding()` | **No** - keys are lost on restart | | SQL Server | `AddSqlServerEventCryptoShredding()` | Yes | | PostgreSQL | `AddPostgresEventCryptoShredding()` | Yes | -| Azure Storage, MongoDB, Key Vault | Not provided yet | - | +| Azure Storage | `AddAzureStorageEventCryptoShredding()` | Yes | +| MongoDB | `AddMongoDBEventCryptoShredding()` | Yes | +| Key Vault | Not provided yet | - | **The host refuses to start with a non-durable key store outside Development.** Losing the keys is indistinguishable from erasing every data subject at once, and nothing reports that it happened, so the diff --git a/docs/wiki/Provider-Feature-Matrix.md b/docs/wiki/Provider-Feature-Matrix.md index 7027d2af..51b77001 100644 --- a/docs/wiki/Provider-Feature-Matrix.md +++ b/docs/wiki/Provider-Feature-Matrix.md @@ -18,7 +18,7 @@ per-registration values. | Transactional outbox (atomic with events) | No | Yes (`AddSqlServerOutbox`) | Yes (`AddPostgresOutbox`) | No | No | No | | [Subscriptions](Subscriptions.md) (catch-up over the event stream) | Contracts + `AddEventSubscription` | Yes | Yes | Yes | Yes | No (no event stream) | | Durable subscription checkpoints | In-memory only (replays after restart) | `AddSqlServerSubscriptionCheckpoints()` | `AddPostgresSubscriptionCheckpoints()` | `AddAzureStorageSubscriptionCheckpoints()` | `AddMongoDBSubscriptionCheckpoints()` | n/a | -| Durable crypto-shredding key store | In-memory only (refused outside Development) | `AddSqlServerEventCryptoShredding()` | `AddPostgresEventCryptoShredding()` | Not provided | Not provided | n/a | +| Durable crypto-shredding key store | In-memory only (refused outside Development) | `AddSqlServerEventCryptoShredding()` | `AddPostgresEventCryptoShredding()` | `AddAzureStorageEventCryptoShredding()` | `AddMongoDBEventCryptoShredding()` | n/a | | Event-stream retention / pruning | No | No | No | No | No | n/a | | Provider-specific native transaction factory | No | `ISqlServerEventStoreTransactionFactory` | `IPostgresEventStoreTransactionFactory` | No | No | No | | Runtime-configured JSON payload indexes | No | Yes (event + snapshot stores, auto-create path) | Yes (GIN + expression indexes on event + snapshot stores) | No | No | Yes (container indexing policy, including composite and spatial paths) | diff --git a/skills/event-sourcing-crypto-shredding/SKILL.md b/skills/event-sourcing-crypto-shredding/SKILL.md index 650d45fb..e036dddd 100644 --- a/skills/event-sourcing-crypto-shredding/SKILL.md +++ b/skills/event-sourcing-crypto-shredding/SKILL.md @@ -50,7 +50,9 @@ configured. | In-memory | `AddInMemoryEventCryptoShredding()` | **No** | | SQL Server | `AddSqlServerEventCryptoShredding()` | Yes | | PostgreSQL | `AddPostgresEventCryptoShredding()` | Yes | -| Azure Storage, MongoDB, Key Vault | not provided yet | - | +| Azure Storage | `AddAzureStorageEventCryptoShredding()` | Yes | +| MongoDB | `AddMongoDBEventCryptoShredding()` | Yes | +| Key Vault | not provided yet | - | **The host refuses to start with a non-durable key store outside Development.** Keys that die with the process make every protected payload unreadable - the same outcome as erasing every subject at @@ -68,6 +70,8 @@ that fails an audit: long-retention backups, or accept that erasure completes only when the last backup ages out. - **Key Vault purge protection** keeps a deleted secret recoverable for the retention window, so a "shredded" subject is not actually erased until it expires. +- **Azure Storage soft delete / point-in-time restore**, and a **MongoDB replica that has not yet + applied the delete**, both do the same thing. Neither is something the framework can enforce; both belong in the deployment's runbook. diff --git a/src/src/AzureStorage/AzureTableKeyEncoding.cs b/src/src/AzureStorage/AzureTableKeyEncoding.cs new file mode 100644 index 00000000..7bfc044f --- /dev/null +++ b/src/src/AzureStorage/AzureTableKeyEncoding.cs @@ -0,0 +1,29 @@ +using System.Text; + +namespace Purview.EventSourcing.AzureStorage; + +/// +/// Encodes arbitrary text into a value that is legal in an Azure Table partition or row key. +/// +/// +/// +/// Azure table keys cannot contain /, \, #, ? or control characters, and +/// a composed key built by concatenation is ambiguous when a segment contains the separator. +/// Base64Url uses only characters that are legal in a key and never produces |, so a key +/// composed from encoded segments is both legal and unambiguous. +/// +/// +/// Shared so every side table in this provider encodes identically. Two encodings of the same +/// concept is how one tenant's row ends up colliding with another's. +/// +/// +static class AzureTableKeyEncoding +{ + /// The separator placed between encoded segments of a composed key. + public const char SegmentSeparator = '|'; + + /// Encodes one segment of a key. + /// The value to encode. + public static string Encode(string value) => + Convert.ToBase64String(Encoding.UTF8.GetBytes(value)).TrimEnd('=').Replace('+', '-').Replace('/', '_'); +} diff --git a/src/src/AzureStorage/Cryptography/AzureStorageEventCryptoKeyStore.cs b/src/src/AzureStorage/Cryptography/AzureStorageEventCryptoKeyStore.cs new file mode 100644 index 00000000..a599f17d --- /dev/null +++ b/src/src/AzureStorage/Cryptography/AzureStorageEventCryptoKeyStore.cs @@ -0,0 +1,168 @@ +using Azure; +using Azure.Data.Tables; +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Cryptography; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.AzureStorage.Cryptography; + +/// +/// A durable backed by an Azure Storage table. +/// +/// +/// +/// Keys are scoped to the current tenant: the same data-subject identifier in two tenants is two +/// different people, so they get two different keys, and neither tenant can read or erase the +/// other's. The tenant is part of the partition key rather than a filtered property, so the scoping +/// is structural - a query cannot forget it. +/// +/// +/// Erasure is only as irreversible as the least-irreversible copy of the key. A +/// storage account with soft delete or point-in-time restore enabled keeps a deleted key +/// recoverable for the retention window, so a shredded subject is not actually erased until it +/// expires. Disable those on the key table, or accept the delay. +/// +/// +public sealed class AzureStorageEventCryptoKeyStore : IEventCryptoKeyStore, IDisposable +{ + readonly TableClient _tableClient; + readonly ICurrentTenant _currentTenant; + readonly SemaphoreSlim _tableLock = new(1, 1); + bool _tableEnsured; + + /// Creates the store. + /// The key-store options. + /// The event-store options, used for any value not overridden. + /// The tenant scope keys are read and written under. + public AzureStorageEventCryptoKeyStore( + IOptions keyStoreOptions, + IOptions eventStoreOptions, + ICurrentTenant? currentTenant = null + ) + { + ArgumentNullException.ThrowIfNull(keyStoreOptions); + ArgumentNullException.ThrowIfNull(eventStoreOptions); + + var connectionString = + keyStoreOptions.Value.ConnectionString + ?? eventStoreOptions.Value.ConnectionString + ?? throw new InvalidOperationException( + "AzureStorageEventCryptoKeyStore requires a connection string. Configure 'EventStore:AzureStorage:Cryptography:ConnectionString' or 'EventStore:AzureStorage:ConnectionString'." + ); + + _currentTenant = currentTenant ?? new SystemCurrentTenant(); + _tableClient = new(connectionString, keyStoreOptions.Value.TableName); + } + + /// + public async Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + await EnsureTableAsync(cancellationToken); + + var existing = await TryGetAsync(dataSubjectId, cancellationToken); + if (existing is not null) + return existing; + + CryptoKeyEntity entity = new() + { + PartitionKey = PartitionKeyFor(), + RowKey = RowKeyFor(dataSubjectId), + KeyMaterial = AesGcmEventPayloadProtector.CreateKey(), + CreatedUtc = DateTimeOffset.UtcNow, + }; + + try + { + await _tableClient.AddEntityAsync(entity, cancellationToken); + + return entity.KeyMaterial; + } + catch (RequestFailedException ex) when (ex.Status == 409) + { + // Another caller created the key between the read and the add. Both must end up with the + // same key, or payloads written by the loser become unreadable - so return theirs, not + // the one just generated. + return await TryGetAsync(dataSubjectId, cancellationToken) + ?? throw new InvalidOperationException( + $"The key for data subject '{dataSubjectId}' could not be read back after a concurrent creation." + ); + } + } + + /// + public async Task TryGetAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + await EnsureTableAsync(cancellationToken); + + var response = await _tableClient.GetEntityIfExistsAsync( + PartitionKeyFor(), + RowKeyFor(dataSubjectId), + cancellationToken: cancellationToken + ); + + return response.HasValue ? response.Value!.KeyMaterial : null; + } + + /// + public async Task ShredAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + await EnsureTableAsync(cancellationToken); + + var response = await _tableClient.DeleteEntityAsync( + PartitionKeyFor(), + RowKeyFor(dataSubjectId), + cancellationToken: cancellationToken + ); + + // Delete is idempotent in Table Storage and reports 404 when nothing was there. + return !response.IsError && response.Status != 404; + } + + async Task EnsureTableAsync(CancellationToken cancellationToken) + { + if (_tableEnsured) + return; + + await _tableLock.WaitAsync(cancellationToken); + try + { + if (_tableEnsured) + return; + + await _tableClient.CreateIfNotExistsAsync(cancellationToken); + _tableEnsured = true; + } + finally + { + _tableLock.Release(); + } + } + + string PartitionKeyFor() => AzureTableKeyEncoding.Encode(TenantColumn.Encode(_currentTenant.Current)); + + static string RowKeyFor(string dataSubjectId) => AzureTableKeyEncoding.Encode(dataSubjectId); + + /// + public void Dispose() => _tableLock.Dispose(); + + sealed class CryptoKeyEntity : ITableEntity + { + public byte[] KeyMaterial { get; set; } = default!; + + public DateTimeOffset CreatedUtc { get; set; } + + public string PartitionKey { get; set; } = default!; + + public string RowKey { get; set; } = default!; + + public DateTimeOffset? Timestamp { get; set; } + + public ETag ETag { get; set; } + } +} diff --git a/src/src/AzureStorage/Cryptography/AzureStorageEventCryptoKeyStoreOptions.cs b/src/src/AzureStorage/Cryptography/AzureStorageEventCryptoKeyStoreOptions.cs new file mode 100644 index 00000000..b642abfb --- /dev/null +++ b/src/src/AzureStorage/Cryptography/AzureStorageEventCryptoKeyStoreOptions.cs @@ -0,0 +1,35 @@ +using System.ComponentModel.DataAnnotations; + +namespace Purview.EventSourcing.AzureStorage.Cryptography; + +/// +/// Options that configure the Azure Table Storage crypto key store. +/// +/// +/// Bound from the EventStore:AzureStorage:Cryptography configuration section. When +/// is not supplied, the event-store connection string is used. +/// +public sealed class AzureStorageEventCryptoKeyStoreOptions +{ + /// The configuration section name used to bind these options. + public const string AzureStorageCryptography = "EventStore:AzureStorage:Cryptography"; + + /// The default table name used to persist per-subject keys. + public const string DefaultTableName = "EventStoreCryptoKeys"; + + /// + /// The storage connection string. When null, the event-store connection string is used. + /// + /// + /// Pointing this at a separate storage account is worth considering: the key table's retention + /// and access policy is what decides how long an erasure takes to become irreversible, and it + /// rarely wants the same treatment as the event data it protects. + /// + public string? ConnectionString { get; set; } + + /// The name of the table that stores per-subject keys. + /// Azure table names are alphanumeric and must start with a letter. + [Required(AllowEmptyStrings = false)] + [RegularExpression("^[A-Za-z][A-Za-z0-9]{2,62}$")] + public string TableName { get; set; } = DefaultTableName; +} diff --git a/src/src/AzureStorage/Cryptography/AzureStorageEventCryptoKeyStoreOptionsValidator.cs b/src/src/AzureStorage/Cryptography/AzureStorageEventCryptoKeyStoreOptionsValidator.cs new file mode 100644 index 00000000..86c6f7cb --- /dev/null +++ b/src/src/AzureStorage/Cryptography/AzureStorageEventCryptoKeyStoreOptionsValidator.cs @@ -0,0 +1,20 @@ +using System.ComponentModel.DataAnnotations; +using Microsoft.Extensions.Options; + +namespace Purview.EventSourcing.AzureStorage.Cryptography; + +sealed class AzureStorageEventCryptoKeyStoreOptionsValidator : IValidateOptions +{ + public ValidateOptionsResult Validate(string? name, AzureStorageEventCryptoKeyStoreOptions options) + { + ArgumentNullException.ThrowIfNull(options); + ValidationContext validationContext = new(options); + List validationResults = []; + if (!Validator.TryValidateObject(options, validationContext, validationResults, validateAllProperties: true)) + return ValidateOptionsResult.Fail( + validationResults.Select(static x => x.ErrorMessage ?? "Options validation failed.") + ); + + return ValidateOptionsResult.Success; + } +} diff --git a/src/src/AzureStorage/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/AzureStorage/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs index f57dd4c4..319af5a5 100644 --- a/src/src/AzureStorage/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs +++ b/src/src/AzureStorage/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -3,7 +3,9 @@ using Microsoft.Extensions.Configuration; using Microsoft.Extensions.DependencyInjection.Extensions; using Microsoft.Extensions.Options; +using Purview.EventSourcing.AzureStorage.Cryptography; using Purview.EventSourcing.AzureStorage.Subscriptions; +using Purview.EventSourcing.Cryptography; using Purview.EventSourcing.Internal; using Purview.EventSourcing.Subscriptions; @@ -117,5 +119,38 @@ public IServiceCollection AddAzureStorageSubscriptionCheckpoints() return services; } + + /// + /// Registers crypto-shredding backed by a durable Azure Table Storage key store. + /// + /// Optional configuration. + /// The for chaining. + /// + /// Keys are scoped to the current tenant and survive a restart, so this is what makes + /// crypto-shredding usable in a deployed application. Note that restoring the key store from a + /// backup brings shredded keys back; see docs/wiki/Crypto-Key-Management-Design.md. + /// + public IServiceCollection AddAzureStorageEventCryptoShredding(Action? configure = null) + { + services.AddEventCryptoShredding(configure); + + services + .AddOptions() + .Configure( + (options, configuration) => + configuration + .GetSection(AzureStorageEventCryptoKeyStoreOptions.AzureStorageCryptography) + .Bind(options) + ); + + services.TryAddEnumerable( + ServiceDescriptor.Singleton< + IValidateOptions, + AzureStorageEventCryptoKeyStoreOptionsValidator + >() + ); + + return services; + } } } diff --git a/src/src/AzureStorage/Subscriptions/AzureStorageSubscriptionCheckpointStore.cs b/src/src/AzureStorage/Subscriptions/AzureStorageSubscriptionCheckpointStore.cs index 8d388777..0e298fa0 100644 --- a/src/src/AzureStorage/Subscriptions/AzureStorageSubscriptionCheckpointStore.cs +++ b/src/src/AzureStorage/Subscriptions/AzureStorageSubscriptionCheckpointStore.cs @@ -1,4 +1,3 @@ -using System.Text; using Azure; using Azure.Data.Tables; using Microsoft.Extensions.Options; @@ -135,16 +134,10 @@ async Task EnsureTableAsync(CancellationToken cancellationToken) } } - // Azure table keys cannot contain '/', '\', '#' or '?', and a delimited key would be ambiguous if - // any segment contained the delimiter. Base64Url uses only characters that are legal in a key and - // never produces the '|' separator, so the composed key is both legal and unambiguous. static string PartitionKeyFor(SubscriptionCheckpointKey key) => - $"{Encode(key.SubscriptionName)}|{Encode(TenantColumn.Encode(key.Scope))}"; + $"{AzureTableKeyEncoding.Encode(key.SubscriptionName)}{AzureTableKeyEncoding.SegmentSeparator}{AzureTableKeyEncoding.Encode(TenantColumn.Encode(key.Scope))}"; - static string RowKeyFor(SubscriptionCheckpointKey key) => Encode(key.AggregateId); - - static string Encode(string value) => - Convert.ToBase64String(Encoding.UTF8.GetBytes(value)).TrimEnd('=').Replace('+', '-').Replace('/', '_'); + static string RowKeyFor(SubscriptionCheckpointKey key) => AzureTableKeyEncoding.Encode(key.AggregateId); /// public void Dispose() => _tableLock.Dispose(); diff --git a/src/src/MongoDB/Cryptography/MongoDBEventCryptoKeyStore.cs b/src/src/MongoDB/Cryptography/MongoDBEventCryptoKeyStore.cs new file mode 100644 index 00000000..49bbcdc7 --- /dev/null +++ b/src/src/MongoDB/Cryptography/MongoDBEventCryptoKeyStore.cs @@ -0,0 +1,120 @@ +using Microsoft.Extensions.Options; +using MongoDB.Bson; +using MongoDB.Driver; +using Purview.EventSourcing.Cryptography; +using Purview.EventSourcing.MongoDB.Events; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.MongoDB.Cryptography; + +/// +/// A durable backed by a MongoDB collection. +/// +/// +/// +/// Keys are scoped to the current tenant: the same data-subject identifier in two tenants is two +/// different people, so they get two different keys, and neither tenant can read or erase the +/// other's. +/// +/// +/// Erasure is only as irreversible as the least-irreversible copy of the key. +/// Restoring this collection from a backup, or a replica that has not yet applied the delete, +/// brings shredded keys back. +/// +/// +public sealed class MongoDBEventCryptoKeyStore : IEventCryptoKeyStore, IDisposable +{ + const string KeyMaterialField = "k"; + const string CreatedUtcField = "c"; + + readonly MongoClient _client; + readonly IMongoCollection _collection; + readonly ICurrentTenant _currentTenant; + + /// Creates the store. + /// The key-store options. + /// The event-store options, used for any value not overridden. + /// The tenant scope keys are read and written under. + public MongoDBEventCryptoKeyStore( + IOptions keyStoreOptions, + IOptions eventStoreOptions, + ICurrentTenant? currentTenant = null + ) + { + ArgumentNullException.ThrowIfNull(keyStoreOptions); + ArgumentNullException.ThrowIfNull(eventStoreOptions); + + var options = keyStoreOptions.Value; + var connectionString = + options.ConnectionString + ?? eventStoreOptions.Value.ConnectionString + ?? throw new InvalidOperationException( + "MongoDBEventCryptoKeyStore requires a connection string. Configure 'EventStore:MongoDB:Cryptography:ConnectionString' or 'EventStore:MongoDB:ConnectionString'." + ); + + var database = + options.Database + ?? eventStoreOptions.Value.Database + ?? throw new InvalidOperationException( + "MongoDBEventCryptoKeyStore requires a database. Configure 'EventStore:MongoDB:Cryptography:Database' or 'EventStore:MongoDB:Database'." + ); + + _currentTenant = currentTenant ?? new SystemCurrentTenant(); + _client = new(connectionString); + _collection = _client.GetDatabase(database).GetCollection(options.CollectionName); + } + + /// + public async Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + // $setOnInsert with an upsert is atomic get-or-create: concurrent callers converge on one + // key rather than each generating their own, which would make payloads written by the loser + // unreadable. ReturnDocument.After yields the stored key whether it was just created or + // already there. + var update = Builders + .Update.SetOnInsert(KeyMaterialField, AesGcmEventPayloadProtector.CreateKey()) + .SetOnInsert(CreatedUtcField, DateTimeOffset.UtcNow.UtcDateTime); + + var document = await _collection.FindOneAndUpdateAsync( + Filter(dataSubjectId), + update, + new FindOneAndUpdateOptions { IsUpsert = true, ReturnDocument = ReturnDocument.After }, + cancellationToken + ); + + return document[KeyMaterialField].AsByteArray; + } + + /// + public async Task TryGetAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + var document = await _collection.Find(Filter(dataSubjectId)).FirstOrDefaultAsync(cancellationToken); + + return document is not null && document.TryGetValue(KeyMaterialField, out var key) ? key.AsByteArray : null; + } + + /// + public async Task ShredAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + var result = await _collection.DeleteOneAsync(Filter(dataSubjectId), cancellationToken); + + return result.DeletedCount > 0; + } + + // A compound _id rather than a delimited string: it is unique by construction and cannot be made + // ambiguous by a tenant or subject identifier that happens to contain the delimiter. + FilterDefinition Filter(string dataSubjectId) => + Builders.Filter.Eq( + "_id", + new BsonDocument { ["t"] = TenantColumn.Encode(_currentTenant.Current), ["s"] = dataSubjectId } + ); + + /// + public void Dispose() => _client.Dispose(); +} diff --git a/src/src/MongoDB/Cryptography/MongoDBEventCryptoKeyStoreOptions.cs b/src/src/MongoDB/Cryptography/MongoDBEventCryptoKeyStoreOptions.cs new file mode 100644 index 00000000..9c2f9e64 --- /dev/null +++ b/src/src/MongoDB/Cryptography/MongoDBEventCryptoKeyStoreOptions.cs @@ -0,0 +1,36 @@ +using System.ComponentModel.DataAnnotations; + +namespace Purview.EventSourcing.MongoDB.Cryptography; + +/// +/// Options that configure the MongoDB crypto key store. +/// +/// +/// Bound from the EventStore:MongoDB:Cryptography configuration section. When +/// or are not supplied, the event-store values +/// are used. +/// +public sealed class MongoDBEventCryptoKeyStoreOptions +{ + /// The configuration section name used to bind these options. + public const string MongoDBCryptography = "EventStore:MongoDB:Cryptography"; + + /// The default collection name used to persist per-subject keys. + public const string DefaultCollectionName = "EventStoreCryptoKeys"; + + /// + /// The MongoDB connection string. When null, the event-store connection string is used. + /// + public string? ConnectionString { get; set; } + + /// + /// The database that holds the checkpoint collection. When null, the event-store database is used. + /// + [RegularExpression(@"^[\w\-.]+$")] + public string? Database { get; set; } + + /// The name of the collection that stores per-subject keys. + [Required(AllowEmptyStrings = false)] + [RegularExpression(@"^[\w\-.]+$")] + public string CollectionName { get; set; } = DefaultCollectionName; +} diff --git a/src/src/MongoDB/Cryptography/MongoDBEventCryptoKeyStoreOptionsValidator.cs b/src/src/MongoDB/Cryptography/MongoDBEventCryptoKeyStoreOptionsValidator.cs new file mode 100644 index 00000000..3ea78130 --- /dev/null +++ b/src/src/MongoDB/Cryptography/MongoDBEventCryptoKeyStoreOptionsValidator.cs @@ -0,0 +1,20 @@ +using System.ComponentModel.DataAnnotations; +using Microsoft.Extensions.Options; + +namespace Purview.EventSourcing.MongoDB.Cryptography; + +sealed class MongoDBEventCryptoKeyStoreOptionsValidator : IValidateOptions +{ + public ValidateOptionsResult Validate(string? name, MongoDBEventCryptoKeyStoreOptions options) + { + ArgumentNullException.ThrowIfNull(options); + ValidationContext validationContext = new(options); + List validationResults = []; + if (!Validator.TryValidateObject(options, validationContext, validationResults, validateAllProperties: true)) + return ValidateOptionsResult.Fail( + validationResults.Select(static x => x.ErrorMessage ?? "Options validation failed.") + ); + + return ValidateOptionsResult.Success; + } +} diff --git a/src/src/MongoDB/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/MongoDB/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs index e326b39f..7f92a487 100644 --- a/src/src/MongoDB/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs +++ b/src/src/MongoDB/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -6,7 +6,9 @@ using Microsoft.Extensions.DependencyInjection.Extensions; using Microsoft.Extensions.Options; using MongoDB.Driver; +using Purview.EventSourcing.Cryptography; using Purview.EventSourcing.Internal; +using Purview.EventSourcing.MongoDB.Cryptography; using Purview.EventSourcing.MongoDB.Events; using Purview.EventSourcing.MongoDB.Snapshots; using Purview.EventSourcing.MongoDB.Subscriptions; @@ -254,5 +256,36 @@ public IServiceCollection AddMongoDBSubscriptionCheckpoints() return services; } + + /// + /// Registers crypto-shredding backed by a durable MongoDB key store. + /// + /// Optional configuration. + /// The for chaining. + /// + /// Keys are scoped to the current tenant and survive a restart, so this is what makes + /// crypto-shredding usable in a deployed application. Note that restoring the key store from a + /// backup brings shredded keys back; see docs/wiki/Crypto-Key-Management-Design.md. + /// + public IServiceCollection AddMongoDBEventCryptoShredding(Action? configure = null) + { + services.AddEventCryptoShredding(configure); + + services + .AddOptions() + .Configure( + (options, configuration) => + configuration.GetSection(MongoDBEventCryptoKeyStoreOptions.MongoDBCryptography).Bind(options) + ); + + services.TryAddEnumerable( + ServiceDescriptor.Singleton< + IValidateOptions, + MongoDBEventCryptoKeyStoreOptionsValidator + >() + ); + + return services; + } } } diff --git a/src/tests/AzureStorage.IntegrationTests/Cryptography/AzureStorageEventCryptoKeyStoreTests.cs b/src/tests/AzureStorage.IntegrationTests/Cryptography/AzureStorageEventCryptoKeyStoreTests.cs new file mode 100644 index 00000000..5a40d058 --- /dev/null +++ b/src/tests/AzureStorage.IntegrationTests/Cryptography/AzureStorageEventCryptoKeyStoreTests.cs @@ -0,0 +1,157 @@ +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Cryptography; +using Purview.EventSourcing.Fixtures.AzureStorage; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.AzureStorage.Cryptography; + +/// +/// The durable crypto key store against real Azure Table Storage. +/// +/// +/// Tenant separation comes first. A key is the most sensitive row in the system: reading another +/// tenant's key reads all of their protected events, and erasing it destroys their data +/// irreversibly. The same data-subject identifier in two tenants is two different people. +/// +[ClassDataSource(Shared = SharedType.PerTestSession)] +public sealed class AzureStorageEventCryptoKeyStoreTests(TableEventStoreFixture fixture) +{ + [Test] + public async Task TryGetAsync_GivenAnotherTenantsSubject_DoesNotReturnTheKey(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + + var other = await AsTenantAsync("globex", () => store.TryGetAsync(subject, cancellationToken)); + + await Assert.That(other).IsNull(); + } + + [Test] + public async Task GetOrCreateAsync_GivenTheSameSubjectInTwoTenants_CreatesDifferentKeys( + CancellationToken cancellationToken + ) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var acme = await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + var globex = await AsTenantAsync("globex", () => store.GetOrCreateAsync(subject, cancellationToken)); + + await Assert.That(acme).IsNotEquivalentTo(globex); + } + + // Erasing one tenant's subject must not erase another tenant's subject of the same name. + [Test] + public async Task ShredAsync_GivenAnotherTenantsSubject_LeavesTheOwnersKeyIntact( + CancellationToken cancellationToken + ) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var owner = await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + var shredded = await AsTenantAsync("globex", () => store.ShredAsync(subject, cancellationToken)); + var stillThere = await AsTenantAsync("acme", () => store.TryGetAsync(subject, cancellationToken)); + + await Assert.That(shredded).IsFalse(); + await Assert.That(stillThere).IsEquivalentTo(owner); + } + + [Test] + public async Task GetOrCreateAsync_CalledTwice_ReturnsTheSameKey(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var first = await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + var second = await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + + await Assert.That(first).IsEquivalentTo(second); + } + + // Concurrent first-use must converge on one key. If two callers each created their own, whichever + // lost would have written payloads nothing can decrypt. + [Test] + public async Task GetOrCreateAsync_GivenConcurrentFirstUse_ConvergesOnOneKey(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var keys = await AsTenantAsync( + "acme", + async () => + await Task.WhenAll( + Enumerable.Range(0, 8).Select(_ => store.GetOrCreateAsync(subject, cancellationToken)) + ) + ); + + await Assert.That(keys.Select(Convert.ToBase64String).Distinct().Count()).IsEqualTo(1); + } + + [Test] + public async Task ShredAsync_GivenAnExistingKey_RemovesItPermanently(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + var shredded = await AsTenantAsync("acme", () => store.ShredAsync(subject, cancellationToken)); + var afterwards = await AsTenantAsync("acme", () => store.TryGetAsync(subject, cancellationToken)); + + await Assert.That(shredded).IsTrue(); + await Assert.That(afterwards).IsNull(); + } + + [Test] + public async Task ShredAsync_GivenNoKey_ReportsThatNothingWasErased(CancellationToken cancellationToken) + { + using var store = CreateStore(); + + var shredded = await AsTenantAsync("acme", () => store.ShredAsync($"{Guid.NewGuid():N}", cancellationToken)); + + await Assert.That(shredded).IsFalse(); + } + + // End to end: the key store is only useful if shredding actually makes a payload unreadable. + [Test] + public async Task UnprotectAsync_AfterTheKeyIsShredded_ReportsErasure(CancellationToken cancellationToken) + { + using var store = CreateStore(); + AesGcmEventPayloadProtector protector = new(store); + var subject = $"{Guid.NewGuid():N}"; + + var protectedPayload = await AsTenantAsync( + "acme", + () => protector.ProtectAsync("""{"name":"a-distinctive-value"}""", subject, cancellationToken) + ); + + var before = await AsTenantAsync("acme", () => protector.UnprotectAsync(protectedPayload, cancellationToken)); + await AsTenantAsync("acme", () => store.ShredAsync(subject, cancellationToken)); + var after = await AsTenantAsync("acme", () => protector.UnprotectAsync(protectedPayload, cancellationToken)); + + await Assert.That(before).IsEqualTo("""{"name":"a-distinctive-value"}"""); + await Assert.That(after).IsNull(); + } + + static async Task AsTenantAsync(string tenant, Func> operation) + { + using (AmbientCurrentTenant.BeginScope(TenantScope.For(tenant))) + return await operation(); + } + + AzureStorageEventCryptoKeyStore CreateStore() => + new( + Options.Create( + new AzureStorageEventCryptoKeyStoreOptions + { + ConnectionString = fixture.ConnectionString, + TableName = $"CryptoKeys{Guid.NewGuid():N}", + } + ), + Options.Create(new AzureStorageEventStoreOptions { ConnectionString = fixture.ConnectionString }), + new AmbientCurrentTenant() + ); +} diff --git a/src/tests/MongoDB.IntegrationTests/Cryptography/MongoDBEventCryptoKeyStoreTests.cs b/src/tests/MongoDB.IntegrationTests/Cryptography/MongoDBEventCryptoKeyStoreTests.cs new file mode 100644 index 00000000..bc61fca1 --- /dev/null +++ b/src/tests/MongoDB.IntegrationTests/Cryptography/MongoDBEventCryptoKeyStoreTests.cs @@ -0,0 +1,161 @@ +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Cryptography; +using Purview.EventSourcing.Fixtures.MongoDB; +using Purview.EventSourcing.MongoDB.Events; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.MongoDB.Cryptography; + +/// +/// The durable crypto key store against real MongoDB. +/// +/// +/// Tenant separation comes first. A key is the most sensitive row in the system: reading another +/// tenant's key reads all of their protected events, and erasing it destroys their data +/// irreversibly. The same data-subject identifier in two tenants is two different people. +/// +[ClassDataSource(Shared = SharedType.PerTestSession)] +public sealed class MongoDBEventCryptoKeyStoreTests(MongoDBEventStoreFixture fixture) +{ + [Test] + public async Task TryGetAsync_GivenAnotherTenantsSubject_DoesNotReturnTheKey(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + + var other = await AsTenantAsync("globex", () => store.TryGetAsync(subject, cancellationToken)); + + await Assert.That(other).IsNull(); + } + + [Test] + public async Task GetOrCreateAsync_GivenTheSameSubjectInTwoTenants_CreatesDifferentKeys( + CancellationToken cancellationToken + ) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var acme = await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + var globex = await AsTenantAsync("globex", () => store.GetOrCreateAsync(subject, cancellationToken)); + + await Assert.That(acme).IsNotEquivalentTo(globex); + } + + // Erasing one tenant's subject must not erase another tenant's subject of the same name. + [Test] + public async Task ShredAsync_GivenAnotherTenantsSubject_LeavesTheOwnersKeyIntact( + CancellationToken cancellationToken + ) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var owner = await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + var shredded = await AsTenantAsync("globex", () => store.ShredAsync(subject, cancellationToken)); + var stillThere = await AsTenantAsync("acme", () => store.TryGetAsync(subject, cancellationToken)); + + await Assert.That(shredded).IsFalse(); + await Assert.That(stillThere).IsEquivalentTo(owner); + } + + [Test] + public async Task GetOrCreateAsync_CalledTwice_ReturnsTheSameKey(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var first = await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + var second = await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + + await Assert.That(first).IsEquivalentTo(second); + } + + // Concurrent first-use must converge on one key. If two callers each created their own, whichever + // lost would have written payloads nothing can decrypt. + [Test] + public async Task GetOrCreateAsync_GivenConcurrentFirstUse_ConvergesOnOneKey(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var keys = await AsTenantAsync( + "acme", + async () => + await Task.WhenAll( + Enumerable.Range(0, 8).Select(_ => store.GetOrCreateAsync(subject, cancellationToken)) + ) + ); + + await Assert.That(keys.Select(Convert.ToBase64String).Distinct().Count()).IsEqualTo(1); + } + + [Test] + public async Task ShredAsync_GivenAnExistingKey_RemovesItPermanently(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + await AsTenantAsync("acme", () => store.GetOrCreateAsync(subject, cancellationToken)); + var shredded = await AsTenantAsync("acme", () => store.ShredAsync(subject, cancellationToken)); + var afterwards = await AsTenantAsync("acme", () => store.TryGetAsync(subject, cancellationToken)); + + await Assert.That(shredded).IsTrue(); + await Assert.That(afterwards).IsNull(); + } + + [Test] + public async Task ShredAsync_GivenNoKey_ReportsThatNothingWasErased(CancellationToken cancellationToken) + { + using var store = CreateStore(); + + var shredded = await AsTenantAsync("acme", () => store.ShredAsync($"{Guid.NewGuid():N}", cancellationToken)); + + await Assert.That(shredded).IsFalse(); + } + + // End to end: the key store is only useful if shredding actually makes a payload unreadable. + [Test] + public async Task UnprotectAsync_AfterTheKeyIsShredded_ReportsErasure(CancellationToken cancellationToken) + { + using var store = CreateStore(); + AesGcmEventPayloadProtector protector = new(store); + var subject = $"{Guid.NewGuid():N}"; + + var protectedPayload = await AsTenantAsync( + "acme", + () => protector.ProtectAsync("""{"name":"a-distinctive-value"}""", subject, cancellationToken) + ); + + var before = await AsTenantAsync("acme", () => protector.UnprotectAsync(protectedPayload, cancellationToken)); + await AsTenantAsync("acme", () => store.ShredAsync(subject, cancellationToken)); + var after = await AsTenantAsync("acme", () => protector.UnprotectAsync(protectedPayload, cancellationToken)); + + await Assert.That(before).IsEqualTo("""{"name":"a-distinctive-value"}"""); + await Assert.That(after).IsNull(); + } + + static async Task AsTenantAsync(string tenant, Func> operation) + { + using (AmbientCurrentTenant.BeginScope(TenantScope.For(tenant))) + return await operation(); + } + + MongoDBEventCryptoKeyStore CreateStore() => + new( + Options.Create( + new MongoDBEventCryptoKeyStoreOptions + { + ConnectionString = fixture.ConnectionString, + Database = $"crypto{Guid.NewGuid():N}", + CollectionName = "CryptoKeys", + } + ), + Options.Create( + new MongoDBEventStoreOptions { ConnectionString = fixture.ConnectionString, Database = "unused" } + ), + new AmbientCurrentTenant() + ); +} From aa7175f2a9ecc2b427df2c15d0625491806d1c17 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Mon, 26 Oct 2026 11:39:35 +0000 Subject: [PATCH 20/41] feat: Azure Key Vault crypto key store, secret per data subject Model A of the two described in the key-management plan: one vault secret per subject, so erasure is a vault operation inheriting its access control and audit trail. Ships as a new provider-neutral package, Purview.EventSourcing.AzureKeyVault. Purge protection is the part worth knowing about. A soft-delete vault keeps a deleted secret recoverable for its retention period, so deleting alone is not erasure - the store purges by default to complete it. Purge protection forbids purging outright, which is a reasonable safeguard and incompatible with erasing on request; rather than let a shred appear to have worked, the store raises and explains the conflict. Opting out is possible but has to be deliberate. Secret names are a SHA-256 of tenant and subject rather than either value in clear. A vault name appears in portal listings and diagnostics visible far more widely than the key itself, and the tenant and subject are recorded as tags for when an operator legitimately needs them. SecretClient could not be substituted in tests - its public methods route through a non-virtual overload and the stub was never called - so the store depends on a narrow IKeyVaultSecretOperations seam with a thin SecretClient adapter. That also keeps the decisions worth testing in the store rather than behind an SDK call. Pins Azure.Identity and the Key Vault packages to the versions Aspire already requires transitively; lower central versions were a downgrade error. --- .config/purview-build.json | 6 + Directory.Packages.props | 3 + src/EventSourcing.slnx | 1 + src/src/AzureKeyVault/AzureKeyVault.csproj | 19 ++ .../AzureKeyVaultEventCryptoKeyStore.cs | 134 ++++++++++++ ...AzureKeyVaultEventCryptoKeyStoreOptions.cs | 53 +++++ ...aultEventCryptoKeyStoreOptionsValidator.cs | 21 ++ .../ServiceCollectionExtensions.cs | 93 ++++++++ .../IKeyVaultSecretOperations.cs | 54 +++++ src/src/AzureKeyVault/KeyVaultSecretNaming.cs | 45 ++++ src/src/AzureKeyVault/Sdk/README.md | 56 +++++ .../AzureKeyVault/SecretClientOperations.cs | 67 ++++++ .../AzureKeyVaultEventCryptoKeyStoreTests.cs | 204 ++++++++++++++++++ .../EventSourcing.UnitTests.csproj | 3 +- 14 files changed, 758 insertions(+), 1 deletion(-) create mode 100644 src/src/AzureKeyVault/AzureKeyVault.csproj create mode 100644 src/src/AzureKeyVault/AzureKeyVaultEventCryptoKeyStore.cs create mode 100644 src/src/AzureKeyVault/AzureKeyVaultEventCryptoKeyStoreOptions.cs create mode 100644 src/src/AzureKeyVault/AzureKeyVaultEventCryptoKeyStoreOptionsValidator.cs create mode 100644 src/src/AzureKeyVault/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs create mode 100644 src/src/AzureKeyVault/IKeyVaultSecretOperations.cs create mode 100644 src/src/AzureKeyVault/KeyVaultSecretNaming.cs create mode 100644 src/src/AzureKeyVault/Sdk/README.md create mode 100644 src/src/AzureKeyVault/SecretClientOperations.cs create mode 100644 src/tests/EventSourcing.UnitTests/AzureKeyVault/AzureKeyVaultEventCryptoKeyStoreTests.cs diff --git a/.config/purview-build.json b/.config/purview-build.json index 99532c27..d9138a72 100644 --- a/.config/purview-build.json +++ b/.config/purview-build.json @@ -78,6 +78,12 @@ "purview-logo-light.png", "README.md" ], + "purview.eventsourcing.azurekeyvault": [ + "lib/$(TFM)/Purview.EventSourcing.AzureKeyVault.dll", + "lib/$(TFM)/Purview.EventSourcing.AzureKeyVault.xml", + "purview-logo-light.png", + "README.md" + ], "purview.eventsourcing.azurestorage": [ "lib/$(TFM)/Purview.EventSourcing.AzureStorage.dll", "lib/$(TFM)/Purview.EventSourcing.AzureStorage.xml", diff --git a/Directory.Packages.props b/Directory.Packages.props index 565e1d91..c33c67db 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -71,7 +71,10 @@ + + + diff --git a/src/EventSourcing.slnx b/src/EventSourcing.slnx index 0039aa52..f2cbe54e 100644 --- a/src/EventSourcing.slnx +++ b/src/EventSourcing.slnx @@ -29,6 +29,7 @@ + diff --git a/src/src/AzureKeyVault/AzureKeyVault.csproj b/src/src/AzureKeyVault/AzureKeyVault.csproj new file mode 100644 index 00000000..84917793 --- /dev/null +++ b/src/src/AzureKeyVault/AzureKeyVault.csproj @@ -0,0 +1,19 @@ + + + true + Purview Event Sourcing Key Store for Azure Key Vault + Azure Key Vault backed crypto-shredding key stores for Purview EventSourcing, holding one secret per data subject or wrapping per-subject keys with a vault-held key. + $(PackageTags);purview;dotnet;event-sourcing;event-store;crypto-shredding;gdpr;azure-key-vault;key-vault;encryption; + + + + + + + + + + + + + diff --git a/src/src/AzureKeyVault/AzureKeyVaultEventCryptoKeyStore.cs b/src/src/AzureKeyVault/AzureKeyVaultEventCryptoKeyStore.cs new file mode 100644 index 00000000..491f1646 --- /dev/null +++ b/src/src/AzureKeyVault/AzureKeyVaultEventCryptoKeyStore.cs @@ -0,0 +1,134 @@ +using Azure; +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Cryptography; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.AzureKeyVault; + +/// +/// An holding one Key Vault secret per data subject. +/// +/// +/// +/// Erasure maps directly onto the vault: deleting the secret is the irreversible act, and it +/// inherits the vault's own access control and audit trail. That makes this the right choice when +/// erasure itself must be a vault-audited event. +/// +/// +/// It does not scale to large subject populations. A vault is not designed to hold +/// millions of secrets: throughput is throttled per vault, and every read is a network call. For a +/// large population use , which keeps one +/// wrapping key in the vault instead. +/// +/// +/// Keys are scoped to the current tenant: the same data-subject identifier in two tenants is two +/// different people, and the tenant is part of the derived secret name. +/// +/// +public sealed class AzureKeyVaultEventCryptoKeyStore : IEventCryptoKeyStore +{ + readonly IKeyVaultSecretOperations _secrets; + readonly AzureKeyVaultEventCryptoKeyStoreOptions _options; + readonly ICurrentTenant _currentTenant; + + /// Creates the store. + /// The vault secret operations. + /// The key-store options. + /// The tenant scope keys are read and written under. + public AzureKeyVaultEventCryptoKeyStore( + IKeyVaultSecretOperations secrets, + IOptions options, + ICurrentTenant? currentTenant = null + ) + { + ArgumentNullException.ThrowIfNull(secrets); + ArgumentNullException.ThrowIfNull(options); + + _secrets = secrets; + _options = options.Value; + _currentTenant = currentTenant ?? new SystemCurrentTenant(); + } + + /// + public async Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + var existing = await TryGetAsync(dataSubjectId, cancellationToken); + if (existing is not null) + return existing; + + var key = AesGcmEventPayloadProtector.CreateKey(); + Dictionary tags = new(StringComparer.Ordinal) + { + [KeyVaultSecretNaming.TenantTag] = TenantColumn.Encode(_currentTenant.Current), + [KeyVaultSecretNaming.DataSubjectTag] = dataSubjectId, + }; + + await _secrets.SetAsync(NameFor(dataSubjectId), Convert.ToBase64String(key), tags, cancellationToken); + + // Re-read rather than trusting the local value: a concurrent caller may have set a different + // one, and both must end up with whichever the vault now holds, or payloads written by the + // loser become unreadable. + return await TryGetAsync(dataSubjectId, cancellationToken) + ?? throw new InvalidOperationException( + $"The key for data subject '{dataSubjectId}' could not be read back immediately after being created." + ); + } + + /// + public async Task TryGetAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + // A missing secret means never created, or erased. Both are expected during replay - erasure + // is what this looks like from the inside - so it is a null rather than a throw. + var value = await _secrets.TryGetAsync(NameFor(dataSubjectId), cancellationToken); + + return value is null ? null : Convert.FromBase64String(value); + } + + /// + public async Task ShredAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + var name = NameFor(dataSubjectId); + + if (!await _secrets.DeleteAsync(name, cancellationToken)) + return false; + + if (!_options.PurgeOnShred) + return true; + + // Soft-delete alone leaves the secret recoverable for the vault's retention period, so the + // subject is not actually erased yet. Purging completes it. + try + { + await _secrets.PurgeAsync(name, cancellationToken); + } + catch (RequestFailedException ex) when (ex.Status is 403 or 400) + { + // Purge protection forbids purging outright. Reporting success here would be a lie: the + // key is still recoverable, so the subject is not erased. + throw new InvalidOperationException( + $"The key for data subject '{dataSubjectId}' was soft-deleted but could not be purged, so it remains " + + "recoverable for the vault's retention period and the subject is not yet erased. This vault has purge " + + "protection enabled, which is incompatible with erasure on request. Either disable purge protection, " + + $"or set '{AzureKeyVaultEventCryptoKeyStoreOptions.AzureKeyVaultCryptography}:" + + $"{nameof(AzureKeyVaultEventCryptoKeyStoreOptions.PurgeOnShred)}' to false and accept that erasure " + + "completes when the retention window elapses.", + ex + ); + } + + return true; + } + + string NameFor(string dataSubjectId) => + KeyVaultSecretNaming.NameFor( + _options.SecretNamePrefix, + TenantColumn.Encode(_currentTenant.Current), + dataSubjectId + ); +} diff --git a/src/src/AzureKeyVault/AzureKeyVaultEventCryptoKeyStoreOptions.cs b/src/src/AzureKeyVault/AzureKeyVaultEventCryptoKeyStoreOptions.cs new file mode 100644 index 00000000..918d0792 --- /dev/null +++ b/src/src/AzureKeyVault/AzureKeyVaultEventCryptoKeyStoreOptions.cs @@ -0,0 +1,53 @@ +using System.ComponentModel.DataAnnotations; + +namespace Purview.EventSourcing.AzureKeyVault; + +/// +/// Options that configure the Azure Key Vault crypto key stores. +/// +/// +/// Bound from the EventStore:AzureKeyVault:Cryptography configuration section. +/// +public sealed class AzureKeyVaultEventCryptoKeyStoreOptions +{ + /// The configuration section name used to bind these options. + public const string AzureKeyVaultCryptography = "EventStore:AzureKeyVault:Cryptography"; + + /// The vault URI, for example https://my-vault.vault.azure.net/. + [Required(AllowEmptyStrings = false)] + public string VaultUri { get; set; } = default!; + + /// + /// The prefix applied to every secret name, so one vault can serve several deployments. + /// + [Required(AllowEmptyStrings = false)] + [RegularExpression("^[0-9a-zA-Z-]{1,32}$")] + public string SecretNamePrefix { get; set; } = "purview-es"; + + /// + /// Purges a secret after deleting it, so erasure is immediate rather than deferred. + /// + /// + /// + /// A vault with soft-delete keeps a deleted secret recoverable for its retention period, so a + /// subject is not actually erased until that window expires. Purging completes the erasure now. + /// + /// + /// Purging fails on a vault with purge protection enabled, which forbids it entirely. + /// That is a legitimate configuration - it is a safeguard against malicious deletion - but it is + /// incompatible with erasure on request, so the store reports the conflict rather than letting a + /// shred appear to succeed. Set this to only if you have accepted that + /// erasure completes when the retention window elapses. + /// + /// + public bool PurgeOnShred { get; set; } = true; + + /// + /// The name of the vault key used to wrap per-subject keys in the envelope store. + /// + /// + /// Only used by the envelope store, where the vault holds one wrapping key rather than a secret + /// per subject. Ignored by the secret-per-subject store. + /// + public string? WrappingKeyName { get; set; } +} diff --git a/src/src/AzureKeyVault/AzureKeyVaultEventCryptoKeyStoreOptionsValidator.cs b/src/src/AzureKeyVault/AzureKeyVaultEventCryptoKeyStoreOptionsValidator.cs new file mode 100644 index 00000000..9bab201a --- /dev/null +++ b/src/src/AzureKeyVault/AzureKeyVaultEventCryptoKeyStoreOptionsValidator.cs @@ -0,0 +1,21 @@ +using System.ComponentModel.DataAnnotations; +using Microsoft.Extensions.Options; + +namespace Purview.EventSourcing.AzureKeyVault; + +sealed class AzureKeyVaultEventCryptoKeyStoreOptionsValidator + : IValidateOptions +{ + public ValidateOptionsResult Validate(string? name, AzureKeyVaultEventCryptoKeyStoreOptions options) + { + ArgumentNullException.ThrowIfNull(options); + ValidationContext validationContext = new(options); + List validationResults = []; + if (!Validator.TryValidateObject(options, validationContext, validationResults, validateAllProperties: true)) + return ValidateOptionsResult.Fail( + validationResults.Select(static x => x.ErrorMessage ?? "Options validation failed.") + ); + + return ValidateOptionsResult.Success; + } +} diff --git a/src/src/AzureKeyVault/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/AzureKeyVault/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs new file mode 100644 index 00000000..a2da5c9f --- /dev/null +++ b/src/src/AzureKeyVault/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -0,0 +1,93 @@ +using System.ComponentModel; +using Azure.Core; +using Azure.Identity; +using Azure.Security.KeyVault.Secrets; +using Microsoft.Extensions.Configuration; +using Microsoft.Extensions.DependencyInjection.Extensions; +using Microsoft.Extensions.Options; +using Purview.EventSourcing.AzureKeyVault; +using Purview.EventSourcing.Cryptography; + +namespace Microsoft.Extensions.DependencyInjection; + +/// +/// Registers the Azure Key Vault crypto key stores. +/// +/// +/// The members of this type are hidden from IntelliSense as the type is only intended to be consumed +/// through the using for the Microsoft.Extensions.DependencyInjection namespace. +/// +[EditorBrowsable(EditorBrowsableState.Never)] +public static class ServiceCollectionExtensions +{ + extension(IServiceCollection services) + { + /// + /// Registers crypto-shredding with one Key Vault secret per data subject. + /// + /// Optional configuration. + /// The credential used to reach the vault; defaults to . + /// The for chaining. + /// + /// + /// Erasure is a vault operation, so it inherits the vault's access control and audit trail. + /// That is the reason to choose this over the envelope store. + /// + /// + /// It does not scale to large subject populations - a vault is throttled per + /// vault and holds one secret per subject. Prefer + /// AddAzureKeyVaultEnvelopeEventCryptoShredding beyond a few thousand subjects. + /// + /// + public IServiceCollection AddAzureKeyVaultEventCryptoShredding( + Action? configure = null, + TokenCredential? credential = null + ) + { + services.AddAzureKeyVaultCryptoOptions(configure); + + services.TryAddSingleton(provider => + { + var options = provider.GetRequiredService>().Value; + + return new SecretClient(new Uri(options.VaultUri), credential ?? new DefaultAzureCredential()); + }); + services.TryAddSingleton(); + + services.AddEventCryptoShredding(); + + return services; + } + + /// + /// Binds and validates the Key Vault key-store options. + /// + /// Optional configuration callback. + /// The for chaining. + internal IServiceCollection AddAzureKeyVaultCryptoOptions( + Action? configure + ) + { + services + .AddOptions() + .Configure( + (options, configuration) => + { + configuration + .GetSection(AzureKeyVaultEventCryptoKeyStoreOptions.AzureKeyVaultCryptography) + .Bind(options); + configure?.Invoke(options); + } + ); + + services.TryAddEnumerable( + ServiceDescriptor.Singleton< + IValidateOptions, + AzureKeyVaultEventCryptoKeyStoreOptionsValidator + >() + ); + + return services; + } + } +} diff --git a/src/src/AzureKeyVault/IKeyVaultSecretOperations.cs b/src/src/AzureKeyVault/IKeyVaultSecretOperations.cs new file mode 100644 index 00000000..fca91c46 --- /dev/null +++ b/src/src/AzureKeyVault/IKeyVaultSecretOperations.cs @@ -0,0 +1,54 @@ +using Azure; + +namespace Purview.EventSourcing.AzureKeyVault; + +/// +/// The vault secret operations the key store depends on. +/// +/// +/// A seam over SecretClient, whose public methods are not all virtual and so cannot be +/// substituted directly. Keeping it narrow puts the decisions worth testing - tenant scoping, what +/// a missing secret means, and whether a shred actually erased anything - in the store rather than +/// behind an SDK call. +/// +public interface IKeyVaultSecretOperations +{ + /// Gets a secret's value, or when it does not exist. + /// The secret name. + /// A token that can be used to cancel the operation. + Task TryGetAsync(string name, CancellationToken cancellationToken); + + /// Creates or replaces a secret. + /// The secret name. + /// The secret value. + /// Tags recorded alongside the secret. + /// A token that can be used to cancel the operation. + Task SetAsync( + string name, + string value, + IReadOnlyDictionary tags, + CancellationToken cancellationToken + ); + + /// + /// Deletes a secret, returning when there was nothing to delete. + /// + /// The secret name. + /// A token that can be used to cancel the operation. + /// + /// On a soft-delete vault this leaves the secret recoverable for the retention period, so it is + /// not on its own an erasure. + /// + Task DeleteAsync(string name, CancellationToken cancellationToken); + + /// + /// Purges a soft-deleted secret, completing the erasure. + /// + /// The secret name. + /// A token that can be used to cancel the operation. + /// + /// Thrown with status 403 or 400 when the vault has purge protection enabled, which forbids + /// purging outright. + /// + Task PurgeAsync(string name, CancellationToken cancellationToken); +} diff --git a/src/src/AzureKeyVault/KeyVaultSecretNaming.cs b/src/src/AzureKeyVault/KeyVaultSecretNaming.cs new file mode 100644 index 00000000..a5db48c7 --- /dev/null +++ b/src/src/AzureKeyVault/KeyVaultSecretNaming.cs @@ -0,0 +1,45 @@ +using System.Security.Cryptography; +using System.Text; + +namespace Purview.EventSourcing.AzureKeyVault; + +/// +/// Derives the Key Vault secret name that holds a tenant's key for one data subject. +/// +/// +/// +/// A vault secret name may contain only 0-9, a-z, A-Z and -, and is +/// limited to 127 characters. That rules out Base64Url, which uses _, and rules out simply +/// concatenating a tenant and a subject identifier, which can exceed the limit. +/// +/// +/// The name is a SHA-256 of the tenant and subject instead: always legal, always the same length, +/// and collision-free in practice. It also keeps the subject identifier out of the vault's name, +/// which appears in portal listings and diagnostic logs that are visible far more widely than the +/// key itself. The tenant and subject are written to the secret's tags, so an operator can still +/// identify a secret when they legitimately need to. +/// +/// +static class KeyVaultSecretNaming +{ + /// The tag recording the owning tenant, or empty for the system scope. + public const string TenantTag = "purview-tenant"; + + /// The tag recording the data subject. + public const string DataSubjectTag = "purview-data-subject"; + + /// + /// Builds the secret name for a tenant and subject. + /// + /// The configured name prefix, letting one vault serve several deployments. + /// The encoded tenant, empty for the system scope. + /// The data subject. + public static string NameFor(string prefix, string tenantId, string dataSubjectId) + { + // The separator is inside the hashed input so a tenant ending in it cannot produce the same + // name as a subject starting with it. + var hash = SHA256.HashData(Encoding.UTF8.GetBytes($"{tenantId}\u001f{dataSubjectId}")); + + return $"{prefix}-{Convert.ToHexStringLower(hash)}"; + } +} diff --git a/src/src/AzureKeyVault/Sdk/README.md b/src/src/AzureKeyVault/Sdk/README.md new file mode 100644 index 00000000..d0d5b7b9 --- /dev/null +++ b/src/src/AzureKeyVault/Sdk/README.md @@ -0,0 +1,56 @@ +# Purview.EventSourcing.AzureKeyVault + +Azure Key Vault backed crypto-shredding key stores for +[Purview.EventSourcing](https://www.nuget.org/packages/Purview.EventSourcing). + +Crypto-shredding encrypts an event payload under a key belonging to one data subject. Erasing that +key erases their data everywhere it appears, without rewriting or deleting a single event. The key +store is therefore the erasure mechanism, and where it lives decides who can perform an erasure and +whether it can be undone. + +## Two models + +```csharp +// One vault secret per data subject. +builder.Services.AddAzureKeyVaultEventCryptoShredding(options => +{ + options.VaultUri = "https://my-vault.vault.azure.net/"; +}); +``` + +Erasure is a vault operation, inheriting the vault's own access control and audit trail. **It does +not scale to large subject populations** — a vault is throttled per vault and every read is a +network call. + +```csharp +// One wrapping key in the vault; per-subject keys held wrapped in a durable store. +builder.Services.AddSqlServerEventCryptoShredding(); +builder.Services.AddAzureKeyVaultEnvelopeEventCryptoShredding(options => +{ + options.VaultUri = "https://my-vault.vault.azure.net/"; + options.WrappingKeyName = "event-sourcing-kek"; +}); +``` + +Scales to any number of subjects, and a stolen database is still unreadable without the vault. +Erasure deletes the wrapped key from the durable store rather than calling the vault. + +## Purge protection is incompatible with erasure on request + +A vault with soft-delete keeps a deleted secret recoverable for its retention period, so a subject +is not actually erased until that window expires. The secret-per-subject store therefore purges +after deleting, by default. + +**Purge protection forbids purging outright.** It is a reasonable safeguard against malicious +deletion, and it is incompatible with erasing on request. Rather than let a shred appear to succeed, +the store raises an error explaining the conflict. Either disable purge protection on the vault that +holds these secrets, or set `PurgeOnShred` to `false` and accept that erasure completes when the +retention window elapses. + +## Erasure is only as irreversible as the least-irreversible copy + +The same caveat applies to the envelope model, where the wrapped keys live in a database: a +point-in-time restore brings them back. Exclude the key table from long-retention backups, or accept +the delay. This is an operational control the framework cannot enforce. + +See `docs/wiki/Crypto-Key-Management-Design.md` and the `event-sourcing-crypto-shredding` skill. diff --git a/src/src/AzureKeyVault/SecretClientOperations.cs b/src/src/AzureKeyVault/SecretClientOperations.cs new file mode 100644 index 00000000..21713a40 --- /dev/null +++ b/src/src/AzureKeyVault/SecretClientOperations.cs @@ -0,0 +1,67 @@ +using Azure; +using Azure.Security.KeyVault.Secrets; + +namespace Purview.EventSourcing.AzureKeyVault; + +/// +/// over the Key Vault . +/// +/// +/// Deliberately thin: it translates "absent" into a null or false and otherwise lets the SDK's +/// exceptions through, so the behaviour worth testing stays in the key store. +/// +/// The vault secret client. +public sealed class SecretClientOperations(SecretClient client) : IKeyVaultSecretOperations +{ + /// + public async Task TryGetAsync(string name, CancellationToken cancellationToken) + { + try + { + var secret = await client.GetSecretAsync(name, cancellationToken: cancellationToken); + + return secret.Value.Value; + } + catch (RequestFailedException ex) when (ex.Status == 404) + { + return null; + } + } + + /// + public async Task SetAsync( + string name, + string value, + IReadOnlyDictionary tags, + CancellationToken cancellationToken + ) + { + ArgumentNullException.ThrowIfNull(tags); + + KeyVaultSecret secret = new(name, value); + foreach (var tag in tags) + secret.Properties.Tags[tag.Key] = tag.Value; + + await client.SetSecretAsync(secret, cancellationToken); + } + + /// + public async Task DeleteAsync(string name, CancellationToken cancellationToken) + { + try + { + var operation = await client.StartDeleteSecretAsync(name, cancellationToken); + await operation.WaitForCompletionAsync(cancellationToken); + + return true; + } + catch (RequestFailedException ex) when (ex.Status == 404) + { + return false; + } + } + + /// + public Task PurgeAsync(string name, CancellationToken cancellationToken) => + client.PurgeDeletedSecretAsync(name, cancellationToken); +} diff --git a/src/tests/EventSourcing.UnitTests/AzureKeyVault/AzureKeyVaultEventCryptoKeyStoreTests.cs b/src/tests/EventSourcing.UnitTests/AzureKeyVault/AzureKeyVaultEventCryptoKeyStoreTests.cs new file mode 100644 index 00000000..d98ee2db --- /dev/null +++ b/src/tests/EventSourcing.UnitTests/AzureKeyVault/AzureKeyVaultEventCryptoKeyStoreTests.cs @@ -0,0 +1,204 @@ +using System.Collections.Concurrent; +using Azure; +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.AzureKeyVault; + +/// +/// The secret-per-subject Key Vault key store, against a stubbed vault. +/// +/// +/// Key Vault has no emulator, so the vault is stubbed through +/// . That covers what is worth asserting here: tenant +/// scoping, the missing-secret-means-erased contract, and the purge behaviour that decides whether +/// an erasure is real or merely deferred. +/// +public sealed class AzureKeyVaultEventCryptoKeyStoreTests +{ + [Test] + public async Task TryGetAsync_GivenAnotherTenantsSubject_DoesNotReturnTheKey() + { + var store = CreateStore(new VaultStub()); + + await AsTenantAsync("acme", () => store.GetOrCreateAsync("subject-1", CancellationToken.None)); + var other = await AsTenantAsync("globex", () => store.TryGetAsync("subject-1", CancellationToken.None)); + + await Assert.That(other).IsNull(); + } + + [Test] + public async Task GetOrCreateAsync_GivenTheSameSubjectInTwoTenants_CreatesDifferentKeys() + { + var store = CreateStore(new VaultStub()); + + var acme = await AsTenantAsync("acme", () => store.GetOrCreateAsync("subject-1", CancellationToken.None)); + var globex = await AsTenantAsync("globex", () => store.GetOrCreateAsync("subject-1", CancellationToken.None)); + + await Assert.That(acme).IsNotEquivalentTo(globex); + } + + [Test] + public async Task ShredAsync_GivenAnotherTenantsSubject_LeavesTheOwnersKeyIntact() + { + var store = CreateStore(new VaultStub()); + + var owner = await AsTenantAsync("acme", () => store.GetOrCreateAsync("s", CancellationToken.None)); + var shredded = await AsTenantAsync("globex", () => store.ShredAsync("s", CancellationToken.None)); + var stillThere = await AsTenantAsync("acme", () => store.TryGetAsync("s", CancellationToken.None)); + + await Assert.That(shredded).IsFalse(); + await Assert.That(stillThere).IsEquivalentTo(owner); + } + + [Test] + public async Task GetOrCreateAsync_CalledTwice_ReturnsTheSameKey() + { + var store = CreateStore(new VaultStub()); + + var first = await AsTenantAsync("acme", () => store.GetOrCreateAsync("s", CancellationToken.None)); + var second = await AsTenantAsync("acme", () => store.GetOrCreateAsync("s", CancellationToken.None)); + + await Assert.That(first).IsEquivalentTo(second); + } + + // A missing secret is what erasure looks like from the inside, so it must not throw. + [Test] + public async Task TryGetAsync_GivenNoSecret_ReturnsNull() + { + var store = CreateStore(new VaultStub()); + + var key = await AsTenantAsync("acme", () => store.TryGetAsync("never-created", CancellationToken.None)); + + await Assert.That(key).IsNull(); + } + + [Test] + public async Task ShredAsync_GivenAnExistingKey_DeletesAndPurgesIt() + { + VaultStub vault = new(); + var store = CreateStore(vault); + + await AsTenantAsync("acme", () => store.GetOrCreateAsync("s", CancellationToken.None)); + var shredded = await AsTenantAsync("acme", () => store.ShredAsync("s", CancellationToken.None)); + var afterwards = await AsTenantAsync("acme", () => store.TryGetAsync("s", CancellationToken.None)); + + await Assert.That(shredded).IsTrue(); + await Assert.That(afterwards).IsNull(); + await Assert.That(vault.Purged).IsNotEmpty(); + } + + [Test] + public async Task ShredAsync_GivenNoKey_ReportsThatNothingWasErased() + { + var store = CreateStore(new VaultStub()); + + var shredded = await AsTenantAsync("acme", () => store.ShredAsync("absent", CancellationToken.None)); + + await Assert.That(shredded).IsFalse(); + } + + // Soft-delete without purge leaves the key recoverable, so the subject is not erased. Reporting + // success would be a lie, so the store raises instead. + [Test] + public async Task ShredAsync_WhenPurgeIsForbidden_RefusesToReportSuccess() + { + var store = CreateStore(new VaultStub { PurgeForbidden = true }); + + await AsTenantAsync("acme", () => store.GetOrCreateAsync("s", CancellationToken.None)); + + var exception = await Assert + .That(async () => await AsTenantAsync("acme", () => store.ShredAsync("s", CancellationToken.None))) + .Throws(); + + await Assert.That(exception!.Message).Contains("purge protection"); + await Assert.That(exception.Message).Contains(nameof(AzureKeyVaultEventCryptoKeyStoreOptions.PurgeOnShred)); + } + + // Opting out is allowed, but only deliberately: the key stays recoverable until the retention + // window elapses. + [Test] + public async Task ShredAsync_WithPurgeDisabled_SoftDeletesWithoutPurging() + { + VaultStub vault = new() { PurgeForbidden = true }; + var store = CreateStore(vault, purgeOnShred: false); + + await AsTenantAsync("acme", () => store.GetOrCreateAsync("s", CancellationToken.None)); + var shredded = await AsTenantAsync("acme", () => store.ShredAsync("s", CancellationToken.None)); + + await Assert.That(shredded).IsTrue(); + await Assert.That(vault.Purged).IsEmpty(); + } + + // The subject identifier must not appear in the secret name: a vault name shows up in portal + // listings and diagnostics that are visible far more widely than the key itself. + [Test] + public async Task SecretNames_DoNotContainTheSubjectOrTenant() + { + VaultStub vault = new(); + var store = CreateStore(vault); + + await AsTenantAsync("acme", () => store.GetOrCreateAsync("subject-1", CancellationToken.None)); + + await Assert.That(vault.Names.Single()).DoesNotContain("subject-1"); + await Assert.That(vault.Names.Single()).DoesNotContain("acme"); + } + + static async Task AsTenantAsync(string tenant, Func> operation) + { + using (AmbientCurrentTenant.BeginScope(TenantScope.For(tenant))) + return await operation(); + } + + static AzureKeyVaultEventCryptoKeyStore CreateStore(IKeyVaultSecretOperations vault, bool purgeOnShred = true) => + new( + vault, + Options.Create( + new AzureKeyVaultEventCryptoKeyStoreOptions + { + VaultUri = "https://stub.vault.azure.net/", + PurgeOnShred = purgeOnShred, + } + ), + new AmbientCurrentTenant() + ); + + sealed class VaultStub : IKeyVaultSecretOperations + { + readonly ConcurrentDictionary _secrets = new(StringComparer.Ordinal); + + public bool PurgeForbidden { get; init; } + + public List Purged { get; } = []; + + public IReadOnlyCollection Names => [.. _secrets.Keys]; + + public Task TryGetAsync(string name, CancellationToken cancellationToken) => + Task.FromResult(_secrets.TryGetValue(name, out var value) ? value : null); + + public Task SetAsync( + string name, + string value, + IReadOnlyDictionary tags, + CancellationToken cancellationToken + ) + { + _secrets[name] = value; + + return Task.CompletedTask; + } + + public Task DeleteAsync(string name, CancellationToken cancellationToken) => + Task.FromResult(_secrets.TryRemove(name, out _)); + + public Task PurgeAsync(string name, CancellationToken cancellationToken) + { + if (PurgeForbidden) + throw new RequestFailedException(403, "Purge is not allowed on this vault."); + + Purged.Add(name); + + return Task.CompletedTask; + } + } +} diff --git a/src/tests/EventSourcing.UnitTests/EventSourcing.UnitTests.csproj b/src/tests/EventSourcing.UnitTests/EventSourcing.UnitTests.csproj index ac2b7764..f37b1edc 100644 --- a/src/tests/EventSourcing.UnitTests/EventSourcing.UnitTests.csproj +++ b/src/tests/EventSourcing.UnitTests/EventSourcing.UnitTests.csproj @@ -1,8 +1,9 @@ - + + From 941a84f89128f81f591801de8a315ffffc9f8a90 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Mon, 26 Oct 2026 11:51:18 +0000 Subject: [PATCH 21/41] feat: Azure Key Vault envelope crypto key store Model B: a per-subject key generated locally, stored wrapped in a durable store, with the wrapping key held in the vault and never leaving it. The vault holds one key rather than one per subject, so this scales to any subject population and a stolen copy of the durable store is unreadable. The trade against Model A is stated in the docs rather than left implicit: erasure here deletes a row, so it does not appear in the vault's audit trail. Storing a wrapped key needs the durable store to persist bytes it was given rather than generate its own, which the existing contract could not express. ISuppliedKeyEventCryptoKeyStore adds get-or-add; all four durable stores now implement it, their existing GetOrCreateAsync becoming a call to it with a freshly generated key. No behaviour change. The first version of the test for "the durable store never holds a usable key" did not work. The wrapping stub reversed bytes, which is its own inverse, so a store that skipped wrapping entirely and wrote the plaintext key still passed - the sabotage check caught it. The stub now prefixes a marker and unwrapping demands it, so unwrapping something never wrapped fails loudly; the same sabotage now fails four tests. Also replaces IsEquivalentTo with base64 comparison for key material, since it is order-insensitive and would have accepted a reversed key as equal. --- docs/wiki/Crypto-Key-Management-Design.md | 10 +- docs/wiki/Guarantees-and-Limitations.md | 3 +- .../event-sourcing-crypto-shredding/SKILL.md | 16 +- ...zureKeyVaultEnvelopeEventCryptoKeyStore.cs | 71 ++++++++ .../CryptographyClientKeyWrapping.cs | 31 ++++ .../ServiceCollectionExtensions.cs | 55 ++++++ src/src/AzureKeyVault/IKeyVaultKeyWrapping.cs | 23 +++ .../AzureStorageEventCryptoKeyStore.cs | 16 +- .../ISuppliedKeyEventCryptoKeyStore.cs | 33 ++++ .../MongoDBEventCryptoKeyStore.cs | 16 +- .../PostgresEventCryptoKeyStore.cs | 16 +- .../SqlServerEventCryptoKeyStore.cs | 17 +- ...eyVaultEnvelopeEventCryptoKeyStoreTests.cs | 159 ++++++++++++++++++ 13 files changed, 443 insertions(+), 23 deletions(-) create mode 100644 src/src/AzureKeyVault/AzureKeyVaultEnvelopeEventCryptoKeyStore.cs create mode 100644 src/src/AzureKeyVault/CryptographyClientKeyWrapping.cs create mode 100644 src/src/AzureKeyVault/IKeyVaultKeyWrapping.cs create mode 100644 src/src/EventSourcing/Cryptography/ISuppliedKeyEventCryptoKeyStore.cs create mode 100644 src/tests/EventSourcing.UnitTests/AzureKeyVault/AzureKeyVaultEnvelopeEventCryptoKeyStoreTests.cs diff --git a/docs/wiki/Crypto-Key-Management-Design.md b/docs/wiki/Crypto-Key-Management-Design.md index 04db645d..5e371462 100644 --- a/docs/wiki/Crypto-Key-Management-Design.md +++ b/docs/wiki/Crypto-Key-Management-Design.md @@ -1,10 +1,12 @@ # Crypto Key Management — Design -> **Status: partly implemented.** +> **Status: mostly implemented.** > -> Phase 1 (the start-up guard) and Phase 2 (SQL Server and PostgreSQL key stores) have shipped — see -> [Guarantees and Limitations](Guarantees-and-Limitations.md#key-stores). Caching, the Key Vault -> store and rotation remain proposals. +> Phase 1 (the start-up guard), Phase 2 (SQL Server, PostgreSQL, Azure Storage and MongoDB key +> stores) and Phase 4 (both Key Vault models) have shipped — see +> [Guarantees and Limitations](Guarantees-and-Limitations.md#key-stores). **Caching (Phase 3) and +> rotation (Phase 5) remain proposals**, and caching is the one that matters before Key Vault is +> used at volume: every protect and unprotect is currently a vault round trip. ## The problem diff --git a/docs/wiki/Guarantees-and-Limitations.md b/docs/wiki/Guarantees-and-Limitations.md index 656be5b9..3180cbe4 100644 --- a/docs/wiki/Guarantees-and-Limitations.md +++ b/docs/wiki/Guarantees-and-Limitations.md @@ -107,7 +107,8 @@ they get two different keys, and neither tenant can read or erase the other's. | PostgreSQL | `AddPostgresEventCryptoShredding()` | Yes | | Azure Storage | `AddAzureStorageEventCryptoShredding()` | Yes | | MongoDB | `AddMongoDBEventCryptoShredding()` | Yes | -| Key Vault | Not provided yet | - | +| Azure Key Vault (secret per subject) | `AddAzureKeyVaultEventCryptoShredding()` | Yes | +| Azure Key Vault (envelope) | `AddAzureKeyVaultEnvelopeEventCryptoShredding()` | Yes | **The host refuses to start with a non-durable key store outside Development.** Losing the keys is indistinguishable from erasing every data subject at once, and nothing reports that it happened, so the diff --git a/skills/event-sourcing-crypto-shredding/SKILL.md b/skills/event-sourcing-crypto-shredding/SKILL.md index e036dddd..78cce63f 100644 --- a/skills/event-sourcing-crypto-shredding/SKILL.md +++ b/skills/event-sourcing-crypto-shredding/SKILL.md @@ -52,7 +52,8 @@ configured. | PostgreSQL | `AddPostgresEventCryptoShredding()` | Yes | | Azure Storage | `AddAzureStorageEventCryptoShredding()` | Yes | | MongoDB | `AddMongoDBEventCryptoShredding()` | Yes | -| Key Vault | not provided yet | - | +| Azure Key Vault, secret per subject | `AddAzureKeyVaultEventCryptoShredding()` | Yes | +| Azure Key Vault, envelope | `AddAzureKeyVaultEnvelopeEventCryptoShredding()` | Yes | **The host refuses to start with a non-durable key store outside Development.** Keys that die with the process make every protected payload unreadable - the same outcome as erasing every subject at @@ -63,6 +64,19 @@ Writing your own store? Implement `INonDurableEventCryptoKeyStore` on any test d recognises it, and scope keys by the current tenant - the same subject id in two tenants is two different people. +### Choosing between the two Key Vault stores + +| | Secret per subject | Envelope | +| -- | -- | -- | +| Erasure is | a vault operation, in the vault's audit trail | a row deleted from a durable store | +| Scales to | a few thousand subjects | any number | +| Vault holds | one secret per subject | one wrapping key | +| Needs a durable store | no | yes - pass it as `TInner` | + +Pick secret-per-subject when erasure itself must be vault-audited; pick envelope when the subject +population makes that impractical. The envelope store never writes a usable key to the durable +store, so a stolen database is unreadable without the vault. + **Erasure is only as irreversible as the least-irreversible copy of the key.** This is the thing that fails an audit: diff --git a/src/src/AzureKeyVault/AzureKeyVaultEnvelopeEventCryptoKeyStore.cs b/src/src/AzureKeyVault/AzureKeyVaultEnvelopeEventCryptoKeyStore.cs new file mode 100644 index 00000000..6b46af44 --- /dev/null +++ b/src/src/AzureKeyVault/AzureKeyVaultEnvelopeEventCryptoKeyStore.cs @@ -0,0 +1,71 @@ +using Purview.EventSourcing.Cryptography; + +namespace Purview.EventSourcing.AzureKeyVault; + +/// +/// An holding per-subject keys wrapped by a key in Azure Key +/// Vault. +/// +/// +/// +/// Envelope encryption: a per-subject key is generated locally and stored wrapped in a +/// durable store, with the wrapping key held in the vault. The vault holds one key rather than one +/// per subject, so this scales to any subject population, and a stolen copy of the durable store is +/// unreadable without the vault. +/// +/// +/// The trade against : erasure here is a row deleted +/// from the durable store, not a vault operation, so it does not appear in the vault's audit trail. +/// Choose the secret-per-subject store when erasure itself must be vault-audited, and this one when +/// the subject population makes that impractical. +/// +/// +/// Erasure is only as irreversible as the least-irreversible copy of the wrapped key. +/// Restoring the durable store from a backup brings shredded subjects back - the vault cannot +/// prevent that, because the wrapping key is still perfectly valid. +/// +/// +/// The durable store holding wrapped keys. +/// The vault-held wrapping key. +public sealed class AzureKeyVaultEnvelopeEventCryptoKeyStore( + ISuppliedKeyEventCryptoKeyStore innerStore, + IKeyVaultKeyWrapping wrapping +) : IEventCryptoKeyStore +{ + /// + public async Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + var existing = await TryGetAsync(dataSubjectId, cancellationToken); + if (existing is not null) + return existing; + + // Wrap before storing, so the plaintext key is never written down. The inner store's + // get-or-add decides the winner of a concurrent create, and the value it returns is the one + // to unwrap - not the candidate just generated, which may have lost. + var candidate = AesGcmEventPayloadProtector.CreateKey(); + var wrapped = await wrapping.WrapAsync(candidate, cancellationToken); + var stored = await innerStore.GetOrAddAsync(dataSubjectId, wrapped, cancellationToken); + + return await wrapping.UnwrapAsync(stored, cancellationToken); + } + + /// + public async Task TryGetAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + var wrapped = await innerStore.TryGetAsync(dataSubjectId, cancellationToken); + + return wrapped is null ? null : await wrapping.UnwrapAsync(wrapped, cancellationToken); + } + + /// + /// + /// Deletes the wrapped key from the durable store. The vault's wrapping key is untouched, as it + /// protects every other subject too. + /// + public Task ShredAsync(string dataSubjectId, CancellationToken cancellationToken) => + innerStore.ShredAsync(dataSubjectId, cancellationToken); +} diff --git a/src/src/AzureKeyVault/CryptographyClientKeyWrapping.cs b/src/src/AzureKeyVault/CryptographyClientKeyWrapping.cs new file mode 100644 index 00000000..33d84847 --- /dev/null +++ b/src/src/AzureKeyVault/CryptographyClientKeyWrapping.cs @@ -0,0 +1,31 @@ +using Azure.Security.KeyVault.Keys.Cryptography; + +namespace Purview.EventSourcing.AzureKeyVault; + +/// +/// over the Key Vault . +/// +/// +/// Uses RSA-OAEP with SHA-256, which a standard vault key supports. The algorithm is recorded +/// nowhere in the stored bytes, so changing it makes existing wrapped keys unreadable - treat it as +/// part of the persisted format rather than a tunable. +/// +/// The vault cryptography client, bound to the wrapping key. +public sealed class CryptographyClientKeyWrapping(CryptographyClient client) : IKeyVaultKeyWrapping +{ + /// + public async Task WrapAsync(byte[] key, CancellationToken cancellationToken) + { + var result = await client.WrapKeyAsync(KeyWrapAlgorithm.RsaOaep256, key, cancellationToken); + + return result.EncryptedKey; + } + + /// + public async Task UnwrapAsync(byte[] wrappedKey, CancellationToken cancellationToken) + { + var result = await client.UnwrapKeyAsync(KeyWrapAlgorithm.RsaOaep256, wrappedKey, cancellationToken); + + return result.Key; + } +} diff --git a/src/src/AzureKeyVault/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/AzureKeyVault/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs index a2da5c9f..ededbfe0 100644 --- a/src/src/AzureKeyVault/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs +++ b/src/src/AzureKeyVault/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -1,6 +1,8 @@ using System.ComponentModel; using Azure.Core; using Azure.Identity; +using Azure.Security.KeyVault.Keys; +using Azure.Security.KeyVault.Keys.Cryptography; using Azure.Security.KeyVault.Secrets; using Microsoft.Extensions.Configuration; using Microsoft.Extensions.DependencyInjection.Extensions; @@ -59,6 +61,59 @@ public IServiceCollection AddAzureKeyVaultEventCryptoShredding( return services; } + /// + /// Registers crypto-shredding with per-subject keys wrapped by a Key Vault key and held in a + /// durable store. + /// + /// The durable store holding wrapped keys. + /// Optional configuration. + /// The credential used to reach the vault; defaults to . + /// The for chaining. + /// + /// + /// The vault holds one wrapping key rather than one secret per subject, so this scales to any + /// subject population, and a stolen copy of the durable store is unreadable without the vault. + /// + /// + /// Erasure deletes the wrapped key from the durable store, so it does **not** appear in the + /// vault's audit trail. Use AddAzureKeyVaultEventCryptoShredding when erasure itself must + /// be vault-audited. + /// + /// + public IServiceCollection AddAzureKeyVaultEnvelopeEventCryptoShredding( + Action? configure = null, + TokenCredential? credential = null + ) + where TInnerStore : class, ISuppliedKeyEventCryptoKeyStore + { + services.AddAzureKeyVaultCryptoOptions(configure); + + services.TryAddSingleton(); + + services.TryAddSingleton(provider => + { + var options = provider.GetRequiredService>().Value; + if (string.IsNullOrWhiteSpace(options.WrappingKeyName)) + { + throw new InvalidOperationException( + $"Envelope crypto-shredding requires a wrapping key. Configure '{AzureKeyVaultEventCryptoKeyStoreOptions.AzureKeyVaultCryptography}:" + + $"{nameof(AzureKeyVaultEventCryptoKeyStoreOptions.WrappingKeyName)}'." + ); + } + + KeyClient keyClient = new(new Uri(options.VaultUri), credential ?? new DefaultAzureCredential()); + var key = keyClient.GetKey(options.WrappingKeyName); + + return new CryptographyClientKeyWrapping( + new CryptographyClient(key.Value.Id, credential ?? new DefaultAzureCredential()) + ); + }); + + services.AddEventCryptoShredding(); + + return services; + } + /// /// Binds and validates the Key Vault key-store options. /// diff --git a/src/src/AzureKeyVault/IKeyVaultKeyWrapping.cs b/src/src/AzureKeyVault/IKeyVaultKeyWrapping.cs new file mode 100644 index 00000000..0df28d41 --- /dev/null +++ b/src/src/AzureKeyVault/IKeyVaultKeyWrapping.cs @@ -0,0 +1,23 @@ +namespace Purview.EventSourcing.AzureKeyVault; + +/// +/// Wraps and unwraps per-subject keys with a key held in Azure Key Vault. +/// +/// +/// The wrapping key never leaves the vault - the vault performs the operation - so a stolen copy of +/// the durable key store is unreadable without access to the vault. A seam rather than a direct +/// dependency on CryptographyClient, for the same reason as +/// : the SDK client is not substitutable in tests. +/// +public interface IKeyVaultKeyWrapping +{ + /// Wraps a key. + /// The plaintext key. + /// A token that can be used to cancel the operation. + Task WrapAsync(byte[] key, CancellationToken cancellationToken); + + /// Unwraps a key. + /// The wrapped key. + /// A token that can be used to cancel the operation. + Task UnwrapAsync(byte[] wrappedKey, CancellationToken cancellationToken); +} diff --git a/src/src/AzureStorage/Cryptography/AzureStorageEventCryptoKeyStore.cs b/src/src/AzureStorage/Cryptography/AzureStorageEventCryptoKeyStore.cs index a599f17d..47f6f030 100644 --- a/src/src/AzureStorage/Cryptography/AzureStorageEventCryptoKeyStore.cs +++ b/src/src/AzureStorage/Cryptography/AzureStorageEventCryptoKeyStore.cs @@ -23,7 +23,7 @@ namespace Purview.EventSourcing.AzureStorage.Cryptography; /// expires. Disable those on the key table, or accept the delay. /// /// -public sealed class AzureStorageEventCryptoKeyStore : IEventCryptoKeyStore, IDisposable +public sealed class AzureStorageEventCryptoKeyStore : ISuppliedKeyEventCryptoKeyStore, IDisposable { readonly TableClient _tableClient; readonly ICurrentTenant _currentTenant; @@ -55,10 +55,18 @@ public AzureStorageEventCryptoKeyStore( } /// - public async Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) + public Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) => + GetOrAddAsync(dataSubjectId, AesGcmEventPayloadProtector.CreateKey(), cancellationToken); + + /// + public async Task GetOrAddAsync( + string dataSubjectId, + byte[] candidateKey, + CancellationToken cancellationToken + ) { ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); - + ArgumentNullException.ThrowIfNull(candidateKey); await EnsureTableAsync(cancellationToken); var existing = await TryGetAsync(dataSubjectId, cancellationToken); @@ -69,7 +77,7 @@ public async Task GetOrCreateAsync(string dataSubjectId, CancellationTok { PartitionKey = PartitionKeyFor(), RowKey = RowKeyFor(dataSubjectId), - KeyMaterial = AesGcmEventPayloadProtector.CreateKey(), + KeyMaterial = candidateKey, CreatedUtc = DateTimeOffset.UtcNow, }; diff --git a/src/src/EventSourcing/Cryptography/ISuppliedKeyEventCryptoKeyStore.cs b/src/src/EventSourcing/Cryptography/ISuppliedKeyEventCryptoKeyStore.cs new file mode 100644 index 00000000..5b17eaf2 --- /dev/null +++ b/src/src/EventSourcing/Cryptography/ISuppliedKeyEventCryptoKeyStore.cs @@ -0,0 +1,33 @@ +namespace Purview.EventSourcing.Cryptography; + +/// +/// An that can persist key material supplied by the caller, +/// rather than generating its own. +/// +/// +/// +/// Needed for envelope encryption, where the bytes stored are a wrapped key: the store must +/// persist exactly what it is given, because it cannot produce a wrapped key itself and must never +/// hold the plaintext one. +/// +/// +/// The contract is get-or-add, not set: concurrent callers must converge on one stored value. +/// Whichever caller wins, both must end up using what the store holds - if two callers each kept +/// their own key, payloads written by the loser could never be decrypted. +/// +/// +public interface ISuppliedKeyEventCryptoKeyStore : IEventCryptoKeyStore +{ + /// + /// Returns the stored key material for a subject, storing first + /// if there is none. + /// + /// The subject the key belongs to. + /// The material to store when the subject has none. + /// A token that can be used to cancel the operation. + /// + /// The stored material, which is only when this caller won the + /// race to create it. + /// + Task GetOrAddAsync(string dataSubjectId, byte[] candidateKey, CancellationToken cancellationToken); +} diff --git a/src/src/MongoDB/Cryptography/MongoDBEventCryptoKeyStore.cs b/src/src/MongoDB/Cryptography/MongoDBEventCryptoKeyStore.cs index 49bbcdc7..45e01546 100644 --- a/src/src/MongoDB/Cryptography/MongoDBEventCryptoKeyStore.cs +++ b/src/src/MongoDB/Cryptography/MongoDBEventCryptoKeyStore.cs @@ -22,7 +22,7 @@ namespace Purview.EventSourcing.MongoDB.Cryptography; /// brings shredded keys back. /// /// -public sealed class MongoDBEventCryptoKeyStore : IEventCryptoKeyStore, IDisposable +public sealed class MongoDBEventCryptoKeyStore : ISuppliedKeyEventCryptoKeyStore, IDisposable { const string KeyMaterialField = "k"; const string CreatedUtcField = "c"; @@ -65,16 +65,24 @@ public MongoDBEventCryptoKeyStore( } /// - public async Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) + public Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) => + GetOrAddAsync(dataSubjectId, AesGcmEventPayloadProtector.CreateKey(), cancellationToken); + + /// + public async Task GetOrAddAsync( + string dataSubjectId, + byte[] candidateKey, + CancellationToken cancellationToken + ) { ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); - + ArgumentNullException.ThrowIfNull(candidateKey); // $setOnInsert with an upsert is atomic get-or-create: concurrent callers converge on one // key rather than each generating their own, which would make payloads written by the loser // unreadable. ReturnDocument.After yields the stored key whether it was just created or // already there. var update = Builders - .Update.SetOnInsert(KeyMaterialField, AesGcmEventPayloadProtector.CreateKey()) + .Update.SetOnInsert(KeyMaterialField, candidateKey) .SetOnInsert(CreatedUtcField, DateTimeOffset.UtcNow.UtcDateTime); var document = await _collection.FindOneAndUpdateAsync( diff --git a/src/src/Postgres/Cryptography/PostgresEventCryptoKeyStore.cs b/src/src/Postgres/Cryptography/PostgresEventCryptoKeyStore.cs index f3ecbe7c..e851266a 100644 --- a/src/src/Postgres/Cryptography/PostgresEventCryptoKeyStore.cs +++ b/src/src/Postgres/Cryptography/PostgresEventCryptoKeyStore.cs @@ -26,7 +26,7 @@ namespace Purview.EventSourcing.Postgres.Cryptography; /// when the last backup containing the key ages out. /// /// -public sealed partial class PostgresEventCryptoKeyStore : IEventCryptoKeyStore, IDisposable +public sealed partial class PostgresEventCryptoKeyStore : ISuppliedKeyEventCryptoKeyStore, IDisposable { [GeneratedRegex("^[\\w\\-.]+$", RegexOptions.Compiled)] private static partial Regex ValidIdentifier(); @@ -60,10 +60,18 @@ public PostgresEventCryptoKeyStore( } /// - public async Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) + public Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) => + GetOrAddAsync(dataSubjectId, AesGcmEventPayloadProtector.CreateKey(), cancellationToken); + + /// + public async Task GetOrAddAsync( + string dataSubjectId, + byte[] candidateKey, + CancellationToken cancellationToken + ) { ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); - + ArgumentNullException.ThrowIfNull(candidateKey); await EnsureSchemaAsync(cancellationToken); await using NpgsqlConnection connection = new(_connectionString); @@ -87,7 +95,7 @@ ON CONFLICT ("TenantId", "DataSubjectId") DO UPDATE connection ); AddKeyParameters(command, dataSubjectId); - command.Parameters.AddWithValue("@key", AesGcmEventPayloadProtector.CreateKey()); + command.Parameters.AddWithValue("@key", candidateKey); command.Parameters.AddWithValue("@now", DateTimeOffset.UtcNow); var result = await command.ExecuteScalarAsync(cancellationToken); diff --git a/src/src/SqlServer/Cryptography/SqlServerEventCryptoKeyStore.cs b/src/src/SqlServer/Cryptography/SqlServerEventCryptoKeyStore.cs index 18634015..72bb198c 100644 --- a/src/src/SqlServer/Cryptography/SqlServerEventCryptoKeyStore.cs +++ b/src/src/SqlServer/Cryptography/SqlServerEventCryptoKeyStore.cs @@ -26,7 +26,7 @@ namespace Purview.EventSourcing.SqlServer.Cryptography; /// when the last backup containing the key ages out. /// /// -public sealed partial class SqlServerEventCryptoKeyStore : IEventCryptoKeyStore, IDisposable +public sealed partial class SqlServerEventCryptoKeyStore : ISuppliedKeyEventCryptoKeyStore, IDisposable { [GeneratedRegex("^[\\w\\-.]+$", RegexOptions.Compiled)] private static partial Regex ValidIdentifier(); @@ -60,16 +60,23 @@ public SqlServerEventCryptoKeyStore( } /// - public async Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) + public Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) => + GetOrAddAsync(dataSubjectId, AesGcmEventPayloadProtector.CreateKey(), cancellationToken); + + /// + public async Task GetOrAddAsync( + string dataSubjectId, + byte[] candidateKey, + CancellationToken cancellationToken + ) { ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + ArgumentNullException.ThrowIfNull(candidateKey); var existing = await TryGetAsync(dataSubjectId, cancellationToken); if (existing is not null) return existing; - var key = AesGcmEventPayloadProtector.CreateKey(); - await using SqlConnection connection = new(_connectionString); await connection.OpenAsync(cancellationToken); @@ -93,7 +100,7 @@ END CATCH connection ); AddKeyParameters(command, dataSubjectId); - command.Parameters.AddWithValue("@key", key); + command.Parameters.AddWithValue("@key", candidateKey); command.Parameters.AddWithValue("@now", DateTimeOffset.UtcNow); await command.ExecuteNonQueryAsync(cancellationToken); diff --git a/src/tests/EventSourcing.UnitTests/AzureKeyVault/AzureKeyVaultEnvelopeEventCryptoKeyStoreTests.cs b/src/tests/EventSourcing.UnitTests/AzureKeyVault/AzureKeyVaultEnvelopeEventCryptoKeyStoreTests.cs new file mode 100644 index 00000000..20b64df6 --- /dev/null +++ b/src/tests/EventSourcing.UnitTests/AzureKeyVault/AzureKeyVaultEnvelopeEventCryptoKeyStoreTests.cs @@ -0,0 +1,159 @@ +using System.Collections.Concurrent; +using Purview.EventSourcing.Cryptography; + +namespace Purview.EventSourcing.AzureKeyVault; + +/// +/// The envelope key store: per-subject keys wrapped by a vault-held key. +/// +/// +/// Byte arrays are compared as base64 rather than with IsEquivalentTo, which is order-insensitive: +/// the wrapping stub reverses its input, so an equivalence check would pass even if the store never +/// unwrapped anything. +/// The property that matters is that the durable store never holds a usable key. If it did, the +/// whole model would be pointless - a stolen database would be readable without the vault. +/// +public sealed class AzureKeyVaultEnvelopeEventCryptoKeyStoreTests +{ + [Test] + public async Task GetOrCreateAsync_StoresTheKeyWrapped_NeverInPlaintext() + { + SuppliedKeyStoreStub inner = new(); + AzureKeyVaultEnvelopeEventCryptoKeyStore store = new(inner, new MarkingWrappingStub()); + + var key = await store.GetOrCreateAsync("subject-1", CancellationToken.None); + var stored = await inner.TryGetAsync("subject-1", CancellationToken.None); + + await Assert.That(stored).IsNotNull(); + await Assert.That(Convert.ToBase64String(stored!)).IsNotEqualTo(Convert.ToBase64String(key)); + await Assert.That(stored!.Take(MarkingWrappingStub.Marker.Length)).IsEquivalentTo(MarkingWrappingStub.Marker); + } + + [Test] + public async Task TryGetAsync_UnwrapsWhatWasStored() + { + SuppliedKeyStoreStub inner = new(); + AzureKeyVaultEnvelopeEventCryptoKeyStore store = new(inner, new MarkingWrappingStub()); + + var created = await store.GetOrCreateAsync("subject-1", CancellationToken.None); + var read = await store.TryGetAsync("subject-1", CancellationToken.None); + + await Assert.That(Convert.ToBase64String(read!)).IsEqualTo(Convert.ToBase64String(created)); + } + + [Test] + public async Task GetOrCreateAsync_CalledTwice_ReturnsTheSameKey() + { + SuppliedKeyStoreStub inner = new(); + AzureKeyVaultEnvelopeEventCryptoKeyStore store = new(inner, new MarkingWrappingStub()); + + var first = await store.GetOrCreateAsync("s", CancellationToken.None); + var second = await store.GetOrCreateAsync("s", CancellationToken.None); + + await Assert.That(Convert.ToBase64String(first)).IsEqualTo(Convert.ToBase64String(second)); + } + + // The loser of a concurrent create must use the winner's key, not the one it generated: payloads + // encrypted under a key that was never stored could never be decrypted. + [Test] + public async Task GetOrCreateAsync_WhenAnotherCallerWonTheCreate_UsesTheStoredKey() + { + SuppliedKeyStoreStub inner = new(); + MarkingWrappingStub wrapping = new(); + AzureKeyVaultEnvelopeEventCryptoKeyStore store = new(inner, wrapping); + + // Seed the store as if another caller got there first. + var winner = AesGcmEventPayloadProtector.CreateKey(); + await inner.GetOrAddAsync( + "s", + await wrapping.WrapAsync(winner, CancellationToken.None), + CancellationToken.None + ); + + var key = await store.GetOrCreateAsync("s", CancellationToken.None); + + await Assert.That(Convert.ToBase64String(key)).IsEqualTo(Convert.ToBase64String(winner)); + } + + [Test] + public async Task TryGetAsync_GivenNoKey_ReturnsNullWithoutUnwrapping() + { + SuppliedKeyStoreStub inner = new(); + MarkingWrappingStub wrapping = new(); + AzureKeyVaultEnvelopeEventCryptoKeyStore store = new(inner, wrapping); + + var key = await store.TryGetAsync("never-created", CancellationToken.None); + + await Assert.That(key).IsNull(); + await Assert.That(wrapping.UnwrapCount).IsEqualTo(0); + } + + // Erasure deletes the wrapped key. The vault's wrapping key protects every other subject, so it + // must survive. + [Test] + public async Task ShredAsync_RemovesTheWrappedKey() + { + SuppliedKeyStoreStub inner = new(); + AzureKeyVaultEnvelopeEventCryptoKeyStore store = new(inner, new MarkingWrappingStub()); + + await store.GetOrCreateAsync("s", CancellationToken.None); + var shredded = await store.ShredAsync("s", CancellationToken.None); + var afterwards = await store.TryGetAsync("s", CancellationToken.None); + + await Assert.That(shredded).IsTrue(); + await Assert.That(afterwards).IsNull(); + } + + [Test] + public async Task ShredAsync_GivenNoKey_ReportsThatNothingWasErased() + { + SuppliedKeyStoreStub inner = new(); + AzureKeyVaultEnvelopeEventCryptoKeyStore store = new(inner, new MarkingWrappingStub()); + + await Assert.That(await store.ShredAsync("absent", CancellationToken.None)).IsFalse(); + } + + // Stands in for the vault. Wrapping prefixes a marker and unwrapping demands it, so unwrapping + // something that was never wrapped fails loudly. A symmetric stand-in - byte reversal, say - is + // its own inverse, which makes storing the plaintext key indistinguishable from wrapping it and + // lets the test pass when the store never wraps at all. + sealed class MarkingWrappingStub : IKeyVaultKeyWrapping + { + public static readonly byte[] Marker = [0xAB, 0xCD]; + + public int UnwrapCount { get; private set; } + + public Task WrapAsync(byte[] key, CancellationToken cancellationToken) => + Task.FromResult([.. Marker, .. key]); + + public Task UnwrapAsync(byte[] wrappedKey, CancellationToken cancellationToken) + { + UnwrapCount++; + + if (wrappedKey.Length < Marker.Length || !wrappedKey.Take(Marker.Length).SequenceEqual(Marker)) + throw new InvalidOperationException("Asked to unwrap something that was never wrapped."); + + return Task.FromResult(wrappedKey[Marker.Length..]); + } + } + + sealed class SuppliedKeyStoreStub : ISuppliedKeyEventCryptoKeyStore + { + readonly ConcurrentDictionary _keys = new(StringComparer.Ordinal); + + public Task GetOrAddAsync( + string dataSubjectId, + byte[] candidateKey, + CancellationToken cancellationToken + ) => Task.FromResult(_keys.GetOrAdd(dataSubjectId, candidateKey)); + + public Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) => + GetOrAddAsync(dataSubjectId, AesGcmEventPayloadProtector.CreateKey(), cancellationToken); + + public Task TryGetAsync(string dataSubjectId, CancellationToken cancellationToken) => + Task.FromResult(_keys.TryGetValue(dataSubjectId, out var key) ? key : null); + + public Task ShredAsync(string dataSubjectId, CancellationToken cancellationToken) => + Task.FromResult(_keys.TryRemove(dataSubjectId, out _)); + } +} From 303c7967212263fe7c74da5cf5b416365e8ca6e1 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Mon, 26 Oct 2026 12:33:40 +0000 Subject: [PATCH 22/41] feat: cache crypto keys in process, with evict-before-delete An uncached key store makes every protect and unprotect a round trip. Against a database that is wasteful; against Key Vault, where reads are throttled and billed, it is impractical - which is what made caching the blocker for using a vault at volume. The rule that makes it safe is that a cached key must never outlive its erasure. ShredAsync evicts, deletes, then evicts again: a reader racing the delete can repopulate the entry between the first eviction and the delete landing, and only the second eviction removes it. Writing that test was itself the interesting part. The first version invoked the racing reader after the inner store had already removed the key, so there was nothing live to repopulate with and the test passed even with the second eviction deleted. Inverting the stub's ordering makes the race real, and the same sabotage now fails. Caching also broke the non-durable start-up guard, which resolves IEventCryptoKeyStore and would now have found the cache wrapper rather than the in-memory store underneath - silently disabling the guard that exists to stop exactly that configuration. IEventCryptoKeyStoreDecorator lets the check unwrap to the real store, and a test asserts it still bites through the cache. The cache is per process, so KeyCacheDuration is the upper bound on how long an erasure takes to take effect across a cluster. Documented as a compliance parameter rather than a tuning one. Key material is never written to a distributed cache. --- Directory.Packages.props | 1 + docs/wiki/Crypto-Key-Management-Design.md | 5 +- docs/wiki/Guarantees-and-Limitations.md | 11 + .../event-sourcing-crypto-shredding/SKILL.md | 14 ++ .../CachingEventCryptoKeyStore.cs | 126 ++++++++++++ .../Cryptography/EventCryptoOptions.cs | 37 ++++ .../IEventCryptoKeyStoreDecorator.cs | 16 ++ .../NonDurableKeyStoreStartupCheck.cs | 9 +- src/src/EventSourcing/EventSourcing.csproj | 1 + .../ServiceCollectionExtensions.cs | 22 +- .../CachingEventCryptoKeyStoreTests.cs | 191 ++++++++++++++++++ 11 files changed, 426 insertions(+), 7 deletions(-) create mode 100644 src/src/EventSourcing/Cryptography/CachingEventCryptoKeyStore.cs create mode 100644 src/src/EventSourcing/Cryptography/IEventCryptoKeyStoreDecorator.cs create mode 100644 src/tests/EventSourcing.UnitTests/Cryptography/CachingEventCryptoKeyStoreTests.cs diff --git a/Directory.Packages.props b/Directory.Packages.props index c33c67db..a496534c 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -35,6 +35,7 @@ + diff --git a/docs/wiki/Crypto-Key-Management-Design.md b/docs/wiki/Crypto-Key-Management-Design.md index 5e371462..18ce249e 100644 --- a/docs/wiki/Crypto-Key-Management-Design.md +++ b/docs/wiki/Crypto-Key-Management-Design.md @@ -4,9 +4,8 @@ > > Phase 1 (the start-up guard), Phase 2 (SQL Server, PostgreSQL, Azure Storage and MongoDB key > stores) and Phase 4 (both Key Vault models) have shipped — see -> [Guarantees and Limitations](Guarantees-and-Limitations.md#key-stores). **Caching (Phase 3) and -> rotation (Phase 5) remain proposals**, and caching is the one that matters before Key Vault is -> used at volume: every protect and unprotect is currently a vault round trip. +> [Guarantees and Limitations](Guarantees-and-Limitations.md#key-stores). **Rotation (Phase 5) remains a proposal.** Caching +> (Phase 3) has shipped, including the evict-before-delete rule. ## The problem diff --git a/docs/wiki/Guarantees-and-Limitations.md b/docs/wiki/Guarantees-and-Limitations.md index 3180cbe4..0f63e8d5 100644 --- a/docs/wiki/Guarantees-and-Limitations.md +++ b/docs/wiki/Guarantees-and-Limitations.md @@ -122,6 +122,17 @@ of the key table brings shredded keys back. A deployment that must erase on requ key table from long-retention backups, or accept that erasure completes only when the last backup containing the key ages out. This is an operational control, not something the framework can enforce. +Keys are **cached in process memory** by default (`EventStore:Cryptography:CacheKeys`), because an +uncached store makes every protect and unprotect a round trip - impractical against a throttled vault. +`ShredAsync` evicts before deleting and again afterwards, so a reader racing the delete cannot leave a +stale entry behind. + +**The cache is per process**, so `KeyCacheDuration` (default 5 minutes) is the upper bound on how long +an erasure takes to take effect across a cluster: another instance holding the key keeps serving it +until its own entry expires. Treat that duration as a compliance parameter rather than a tuning one, or +turn caching off where an erasure must be immediate everywhere. Key material is never written to a +distributed cache. + Key rotation is **not** implemented: `ProtectedPayload` records no key identifier, so there is no way to tell which key a payload used. See [Crypto Key Management](Crypto-Key-Management-Design.md). diff --git a/skills/event-sourcing-crypto-shredding/SKILL.md b/skills/event-sourcing-crypto-shredding/SKILL.md index 78cce63f..33ccd45a 100644 --- a/skills/event-sourcing-crypto-shredding/SKILL.md +++ b/skills/event-sourcing-crypto-shredding/SKILL.md @@ -77,6 +77,20 @@ Pick secret-per-subject when erasure itself must be vault-audited; pick envelope population makes that impractical. The envelope store never writes a usable key to the durable store, so a stolen database is unreadable without the vault. +### Caching bounds how fast an erasure takes effect + +Keys are cached in process by default - an uncached store makes every protect and unprotect a round +trip, which a throttled vault will not tolerate. `ShredAsync` evicts before deleting *and again +afterwards*, because a reader racing the delete can repopulate the entry in between. + +**The cache is per process**, so `KeyCacheDuration` (default 5 minutes) is the upper bound on how +long a shredded subject stays readable on another instance. That makes it a compliance parameter, +not a tuning one. Set `CacheKeys = false` where an erasure must be immediate everywhere. + +If you write a decorator around a key store, implement `IEventCryptoKeyStoreDecorator` - the +start-up guard unwraps decorators to find the real store, and a decorator that hides it silently +stops the guard working. + **Erasure is only as irreversible as the least-irreversible copy of the key.** This is the thing that fails an audit: diff --git a/src/src/EventSourcing/Cryptography/CachingEventCryptoKeyStore.cs b/src/src/EventSourcing/Cryptography/CachingEventCryptoKeyStore.cs new file mode 100644 index 00000000..60aa8624 --- /dev/null +++ b/src/src/EventSourcing/Cryptography/CachingEventCryptoKeyStore.cs @@ -0,0 +1,126 @@ +using Microsoft.Extensions.Caching.Memory; +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.Cryptography; + +/// +/// Caches another in process memory. +/// +/// +/// +/// Without this, every protect and unprotect is a round trip to the key store. Against a database +/// that is wasteful; against Azure Key Vault it is both slow and throttled, so caching is what makes +/// an external key store usable at volume. +/// +/// +/// A cached key outliving its erasure is a compliance failure, not a performance quirk. +/// therefore evicts before deleting and again afterwards: a concurrent read +/// can repopulate the entry between the two, and the second eviction is what removes it. +/// +/// +/// The cache is per process. Another instance that has the key cached keeps serving +/// it until its own entry expires, so is the upper +/// bound on how long an erasure takes to take effect across a cluster. Keep it short, and treat the +/// duration as a compliance parameter rather than a tuning one. +/// +/// +/// Misses are not cached. A negative entry would keep a subject unreadable after their key was +/// legitimately created, which looks exactly like erasure and is far harder to diagnose. +/// +/// +public sealed class CachingEventCryptoKeyStore : IEventCryptoKeyStore, IEventCryptoKeyStoreDecorator, IDisposable +{ + readonly IEventCryptoKeyStore _inner; + readonly ICurrentTenant _currentTenant; + readonly MemoryCache _cache; + readonly TimeSpan _duration; + + /// Creates the caching store. + /// The store to cache. + /// The crypto options carrying the cache duration and size. + /// The tenant scope, which forms part of the cache key. + public CachingEventCryptoKeyStore( + IEventCryptoKeyStore inner, + IOptions options, + ICurrentTenant? currentTenant = null + ) + { + ArgumentNullException.ThrowIfNull(inner); + ArgumentNullException.ThrowIfNull(options); + + _inner = inner; + _currentTenant = currentTenant ?? new SystemCurrentTenant(); + _duration = options.Value.KeyCacheDuration; + _cache = new(new MemoryCacheOptions { SizeLimit = options.Value.KeyCacheSizeLimit }); + } + + /// + public IEventCryptoKeyStore Inner => _inner; + + /// + public async Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + var key = CacheKeyFor(dataSubjectId); + if (_cache.TryGetValue(key, out byte[]? cached) && cached is not null) + return cached; + + var created = await _inner.GetOrCreateAsync(dataSubjectId, cancellationToken); + Store(key, created); + + return created; + } + + /// + public async Task TryGetAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + var key = CacheKeyFor(dataSubjectId); + if (_cache.TryGetValue(key, out byte[]? cached) && cached is not null) + return cached; + + var fetched = await _inner.TryGetAsync(dataSubjectId, cancellationToken); + if (fetched is not null) + Store(key, fetched); + + return fetched; + } + + /// + public async Task ShredAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + var key = CacheKeyFor(dataSubjectId); + + // Evict first so no reader can take a fresh copy while the delete is in flight, delete, then + // evict again to remove anything a concurrent reader repopulated in between. + _cache.Remove(key); + try + { + return await _inner.ShredAsync(dataSubjectId, cancellationToken); + } + finally + { + _cache.Remove(key); + } + } + + void Store(object key, byte[] value) => + _cache.Set( + key, + value, + new MemoryCacheEntryOptions { AbsoluteExpirationRelativeToNow = _duration, Size = value.Length } + ); + + // The tenant is part of the key because the same subject identifier in two tenants is two + // different people with two different keys. + (string Tenant, string Subject) CacheKeyFor(string dataSubjectId) => + (TenantColumn.Encode(_currentTenant.Current), dataSubjectId); + + /// + public void Dispose() => _cache.Dispose(); +} diff --git a/src/src/EventSourcing/Cryptography/EventCryptoOptions.cs b/src/src/EventSourcing/Cryptography/EventCryptoOptions.cs index d65d30ce..f8b1ea53 100644 --- a/src/src/EventSourcing/Cryptography/EventCryptoOptions.cs +++ b/src/src/EventSourcing/Cryptography/EventCryptoOptions.cs @@ -24,4 +24,41 @@ public sealed class EventCryptoOptions /// /// public bool AllowNonDurableKeyStore { get; set; } + + /// + /// Caches keys in process memory, so a protect or unprotect is not a round trip every time. + /// + /// + /// On by default. Against a database the saving is modest; against Azure Key Vault, where reads + /// are throttled and billed, an uncached store is impractical at volume. Turn it off only where + /// an erasure must take effect immediately everywhere, accepting the cost - see + /// . + /// + public bool CacheKeys { get; set; } = true; + + /// + /// How long a key is held in the process-local cache. + /// + /// + /// + /// This is a compliance parameter, not a tuning one. The cache is per process, so another + /// instance holding a key keeps serving it until its own entry expires: this value is the upper + /// bound on how long an erasure takes to take effect across a cluster. + /// + /// + /// Longer means fewer round trips to the key store - which matters most against a vault, where + /// reads are throttled - and a longer window in which a shredded subject is still readable + /// somewhere. + /// + /// + public TimeSpan KeyCacheDuration { get; set; } = TimeSpan.FromMinutes(5); + + /// + /// The cache's size limit, measured in bytes of key material. + /// + /// + /// Bounded so a large subject population cannot exhaust memory. At the default, roughly thirty + /// thousand 32-byte keys are held before the cache starts evicting. + /// + public long KeyCacheSizeLimit { get; set; } = 1024 * 1024; } diff --git a/src/src/EventSourcing/Cryptography/IEventCryptoKeyStoreDecorator.cs b/src/src/EventSourcing/Cryptography/IEventCryptoKeyStoreDecorator.cs new file mode 100644 index 00000000..07ce1c5f --- /dev/null +++ b/src/src/EventSourcing/Cryptography/IEventCryptoKeyStoreDecorator.cs @@ -0,0 +1,16 @@ +namespace Purview.EventSourcing.Cryptography; + +/// +/// An that wraps another. +/// +/// +/// Lets a check that cares about the real store - such as the one refusing a key store that cannot +/// survive a restart - see through a decorator rather than inspecting the outermost wrapper and +/// drawing the wrong conclusion. Implement it on any decorator, or the guard silently stops +/// protecting whatever is underneath. +/// +public interface IEventCryptoKeyStoreDecorator +{ + /// The store being wrapped. + IEventCryptoKeyStore Inner { get; } +} diff --git a/src/src/EventSourcing/Cryptography/NonDurableKeyStoreStartupCheck.cs b/src/src/EventSourcing/Cryptography/NonDurableKeyStoreStartupCheck.cs index d1dd9e24..7df17602 100644 --- a/src/src/EventSourcing/Cryptography/NonDurableKeyStoreStartupCheck.cs +++ b/src/src/EventSourcing/Cryptography/NonDurableKeyStoreStartupCheck.cs @@ -24,14 +24,19 @@ IOptions options /// public Task StartAsync(CancellationToken cancellationToken) { - if (keyStore is not INonDurableEventCryptoKeyStore) + // Unwrap decorators - the cache wraps the real store - so the check is made against whatever + // actually holds the keys rather than the outermost object. + var store = keyStore; + while (store is IEventCryptoKeyStoreDecorator decorator) + store = decorator.Inner; + if (store is not INonDurableEventCryptoKeyStore) return Task.CompletedTask; if (environment.IsDevelopment() || options.Value.AllowNonDurableKeyStore) return Task.CompletedTask; throw new InvalidOperationException( - $"Crypto-shredding is configured with '{keyStore.GetType().Name}', which does not persist keys across a restart, " + $"Crypto-shredding is configured with '{store.GetType().Name}', which does not persist keys across a restart, " + $"in the '{environment.EnvironmentName}' environment. Every protected event would become permanently " + "unreadable when this process restarts, which is indistinguishable from erasing every data subject. " + "Register a durable key store, or set " diff --git a/src/src/EventSourcing/EventSourcing.csproj b/src/src/EventSourcing/EventSourcing.csproj index 9746c5e9..6e8e723d 100644 --- a/src/src/EventSourcing/EventSourcing.csproj +++ b/src/src/EventSourcing/EventSourcing.csproj @@ -38,6 +38,7 @@ + diff --git a/src/src/EventSourcing/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/EventSourcing/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs index 16055e42..d2b90af0 100644 --- a/src/src/EventSourcing/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs +++ b/src/src/EventSourcing/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -1,6 +1,7 @@ using System.ComponentModel; using System.Diagnostics; using Microsoft.Extensions.DependencyInjection.Extensions; +using Microsoft.Extensions.Options; using Purview.EventSourcing.Aggregates; using Purview.EventSourcing.Aggregates.Events; using Purview.EventSourcing.Aggregates.Events.Upcasting; @@ -111,9 +112,26 @@ public IServiceCollection AddEventCryptoShredding(Action(); - services.TryAddSingleton(static provider => provider.GetRequiredService()); - services.TryAddSingleton(); services.AddOptions().Configure(options => configure?.Invoke(options)); + + // The cache wraps the real store, so IEventCryptoKeyStore resolves to whichever the + // options asked for. The start-up check resolves the same registration, so it still sees + // through to a non-durable store underneath. + services.TryAddSingleton(static provider => + { + var keyStore = provider.GetRequiredService(); + var options = provider.GetRequiredService>(); + if (!options.Value.CacheKeys) + return keyStore; + + return new CachingEventCryptoKeyStore( + keyStore, + options, + provider.GetService() + ); + }); + + services.TryAddSingleton(); services.AddHostedService(); return services; diff --git a/src/tests/EventSourcing.UnitTests/Cryptography/CachingEventCryptoKeyStoreTests.cs b/src/tests/EventSourcing.UnitTests/Cryptography/CachingEventCryptoKeyStoreTests.cs new file mode 100644 index 00000000..f8f04ee8 --- /dev/null +++ b/src/tests/EventSourcing.UnitTests/Cryptography/CachingEventCryptoKeyStoreTests.cs @@ -0,0 +1,191 @@ +using System.Collections.Concurrent; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.Cryptography; + +/// +/// The process-local key cache. +/// +/// +/// The behaviour worth protecting is that a cached key never outlives its erasure. Everything else +/// here is a performance concern; that one is a compliance failure. +/// +public sealed class CachingEventCryptoKeyStoreTests +{ + [Test] + public async Task TryGetAsync_WhenCached_DoesNotAskTheInnerStoreAgain() + { + CountingKeyStoreStub inner = new(); + using var store = CreateStore(inner); + + await store.GetOrCreateAsync("s", CancellationToken.None); + await store.TryGetAsync("s", CancellationToken.None); + await store.TryGetAsync("s", CancellationToken.None); + + await Assert.That(inner.TryGetCount).IsEqualTo(0); + } + + [Test] + public async Task TryGetAsync_ReturnsTheSameKeyAsTheInnerStore() + { + CountingKeyStoreStub inner = new(); + using var store = CreateStore(inner); + + var created = await store.GetOrCreateAsync("s", CancellationToken.None); + var direct = await inner.TryGetAsync("s", CancellationToken.None); + + await Assert.That(Convert.ToBase64String(created)).IsEqualTo(Convert.ToBase64String(direct!)); + } + + // The whole point. A key served from cache after it was erased is a subject who was told their + // data was deleted and whose data is still readable. + [Test] + public async Task ShredAsync_EvictsTheCachedKey() + { + CountingKeyStoreStub inner = new(); + using var store = CreateStore(inner); + + await store.GetOrCreateAsync("s", CancellationToken.None); + await store.ShredAsync("s", CancellationToken.None); + var afterwards = await store.TryGetAsync("s", CancellationToken.None); + + await Assert.That(afterwards).IsNull(); + } + + // A reader racing the shred can repopulate the entry after the first eviction, which is why the + // store evicts again once the delete has happened. + [Test] + public async Task ShredAsync_WhenAReaderRepopulatesDuringTheDelete_StillEvicts() + { + CountingKeyStoreStub inner = new(); + using var store = CreateStore(inner); + + await store.GetOrCreateAsync("s", CancellationToken.None); + + // Simulate the race: the inner store repopulates the cache from inside the delete. + inner.OnShred = () => store.TryGetAsync("s", CancellationToken.None).GetAwaiter().GetResult(); + + await store.ShredAsync("s", CancellationToken.None); + var afterwards = await store.TryGetAsync("s", CancellationToken.None); + + await Assert.That(afterwards).IsNull(); + } + + [Test] + public async Task TryGetAsync_GivenAMiss_DoesNotCacheTheAbsence() + { + CountingKeyStoreStub inner = new(); + using var store = CreateStore(inner); + + await store.TryGetAsync("s", CancellationToken.None); + var created = await store.GetOrCreateAsync("s", CancellationToken.None); + var read = await store.TryGetAsync("s", CancellationToken.None); + + await Assert.That(read).IsNotNull(); + await Assert.That(Convert.ToBase64String(read!)).IsEqualTo(Convert.ToBase64String(created)); + } + + // Two tenants with the same subject id are two different people, so the cache must not hand one + // tenant's key to the other. + [Test] + public async Task Cache_IsScopedByTenant() + { + TenantAwareKeyStoreStub inner = new(); + using var store = CreateStore(inner, new AmbientCurrentTenant()); + + var acme = await AsTenantAsync("acme", () => store.GetOrCreateAsync("s", CancellationToken.None)); + var globex = await AsTenantAsync("globex", () => store.GetOrCreateAsync("s", CancellationToken.None)); + + await Assert.That(Convert.ToBase64String(acme)).IsNotEqualTo(Convert.ToBase64String(globex)); + } + + // The cache wraps the real store, so a check made against the outermost object would stop seeing + // a non-durable one underneath. + [Test] + public async Task StartupCheck_SeesThroughTheCacheToANonDurableStore() + { + ServiceCollection services = new(); + services.AddLogging(); + services.AddSingleton(new ProductionEnvironment()); + services.AddEventSourcing().AddInMemoryEventCryptoShredding(); + + await using var provider = services.BuildServiceProvider(); + var check = provider.GetServices().OfType().Single(); + + await Assert.That(provider.GetRequiredService()).IsTypeOf(); + await Assert + .That(async () => await check.StartAsync(CancellationToken.None)) + .Throws(); + } + + static async Task AsTenantAsync(string tenant, Func> operation) + { + using (AmbientCurrentTenant.BeginScope(TenantScope.For(tenant))) + return await operation(); + } + + static CachingEventCryptoKeyStore CreateStore(IEventCryptoKeyStore inner, ICurrentTenant? currentTenant = null) => + new(inner, Options.Create(new EventCryptoOptions()), currentTenant); + + sealed class CountingKeyStoreStub : IEventCryptoKeyStore + { + readonly ConcurrentDictionary _keys = new(StringComparer.Ordinal); + + public int TryGetCount { get; private set; } + + public Action? OnShred { get; set; } + + public Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) => + Task.FromResult(_keys.GetOrAdd(dataSubjectId, _ => AesGcmEventPayloadProtector.CreateKey())); + + public Task TryGetAsync(string dataSubjectId, CancellationToken cancellationToken) + { + TryGetCount++; + + return Task.FromResult(_keys.TryGetValue(dataSubjectId, out var key) ? key : null); + } + + public Task ShredAsync(string dataSubjectId, CancellationToken cancellationToken) + { + // Invoked before the removal, so the reader sees a live key and repopulates the cache - + // which is the race the second eviction exists for. Invoking it after would find nothing + // to cache and the test would prove nothing. + OnShred?.Invoke(); + var removed = _keys.TryRemove(dataSubjectId, out _); + + return Task.FromResult(removed); + } + } + + sealed class TenantAwareKeyStoreStub : IEventCryptoKeyStore + { + readonly ConcurrentDictionary _keys = new(StringComparer.Ordinal); + + static string KeyFor(string dataSubjectId) => + $"{TenantColumn.Encode(new AmbientCurrentTenant().Current)}|{dataSubjectId}"; + + public Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) => + Task.FromResult(_keys.GetOrAdd(KeyFor(dataSubjectId), _ => AesGcmEventPayloadProtector.CreateKey())); + + public Task TryGetAsync(string dataSubjectId, CancellationToken cancellationToken) => + Task.FromResult(_keys.TryGetValue(KeyFor(dataSubjectId), out var key) ? key : null); + + public Task ShredAsync(string dataSubjectId, CancellationToken cancellationToken) => + Task.FromResult(_keys.TryRemove(KeyFor(dataSubjectId), out _)); + } + + sealed class ProductionEnvironment : IHostEnvironment + { + public string EnvironmentName { get; set; } = "Production"; + + public string ApplicationName { get; set; } = "Tests"; + + public string ContentRootPath { get; set; } = AppContext.BaseDirectory; + + public Microsoft.Extensions.FileProviders.IFileProvider ContentRootFileProvider { get; set; } = + new Microsoft.Extensions.FileProviders.NullFileProvider(); + } +} From 0ad632b52082fdaf756f2c40ae3c3b0b7c89b75d Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Mon, 26 Oct 2026 12:58:08 +0000 Subject: [PATCH 23/41] feat: crypto key rotation for SQL Server and PostgreSQL Completes the key-management plan. A subject can hold several key generations; the highest is current and encrypts new payloads, and ProtectedPayload records which one was used, so rotating never makes existing events unreadable. Earlier generations are retained deliberately - rotation limits what a future compromise exposes, it does not re-encrypt history. Two deliberate narrowings against the plan. Rotation is an optional IRotatingEventCryptoKeyStore rather than a change to IEventCryptoKeyStore, so stores adopt it independently and nothing breaks for anyone who has implemented the interface; and it ships for the two SQL providers only, with the rest documented as not supporting it. The kid field is absent on every payload written so far, which a reader treats as "the subject's only key" - backward compatible, no upcaster. Rotation and erasure stay distinct: ShredAsync removes every generation, because one left behind would mean the subject's older events were still readable. There is a test for exactly that. The capability flag matters more than it looks. The cache decorates the key store, so a protector testing for the interface alone would have missed rotation behind it, or cast the decorator and thrown. SupportsRotation lets the decorator report what the store it wraps can do, and the cache passes rotation through - evicting the cached current generation around a rotate for the same reason a shred evicts twice. --- docs/wiki/Crypto-Key-Management-Design.md | 11 +- docs/wiki/Guarantees-and-Limitations.md | 19 +- docs/wiki/Provider-Feature-Matrix.md | 1 + .../event-sourcing-crypto-shredding/SKILL.md | 20 +++ .../AesGcmEventPayloadProtector.cs | 25 ++- .../CachingEventCryptoKeyStore.cs | 84 ++++++++- .../IRotatingEventCryptoKeyStore.cs | 58 ++++++ .../Cryptography/ProtectedPayload.cs | 12 ++ .../PostgresEventCryptoKeyStore.cs | 131 +++++++++++++- .../SqlServerEventCryptoKeyStore.cs | 150 ++++++++++++++-- .../PostgresEventCryptoKeyRotationTests.cs | 166 ++++++++++++++++++ .../SqlServerEventCryptoKeyRotationTests.cs | 166 ++++++++++++++++++ 12 files changed, 816 insertions(+), 27 deletions(-) create mode 100644 src/src/EventSourcing/Cryptography/IRotatingEventCryptoKeyStore.cs create mode 100644 src/tests/Postgres.IntegrationTests/Cryptography/PostgresEventCryptoKeyRotationTests.cs create mode 100644 src/tests/SqlServer.IntegrationTests/Cryptography/SqlServerEventCryptoKeyRotationTests.cs diff --git a/docs/wiki/Crypto-Key-Management-Design.md b/docs/wiki/Crypto-Key-Management-Design.md index 18ce249e..07c84ce4 100644 --- a/docs/wiki/Crypto-Key-Management-Design.md +++ b/docs/wiki/Crypto-Key-Management-Design.md @@ -1,11 +1,12 @@ # Crypto Key Management — Design -> **Status: mostly implemented.** +> **Status: implemented.** > -> Phase 1 (the start-up guard), Phase 2 (SQL Server, PostgreSQL, Azure Storage and MongoDB key -> stores) and Phase 4 (both Key Vault models) have shipped — see -> [Guarantees and Limitations](Guarantees-and-Limitations.md#key-stores). **Rotation (Phase 5) remains a proposal.** Caching -> (Phase 3) has shipped, including the evict-before-delete rule. +> All five phases have shipped — see +> [Guarantees and Limitations](Guarantees-and-Limitations.md#key-stores). Two deliberate narrowings +> against the plan below: rotation is an optional `IRotatingEventCryptoKeyStore` rather than a +> change to `IEventCryptoKeyStore`, so stores adopt it independently and nothing breaks for an +> existing implementer; and it ships for SQL Server and PostgreSQL only. ## The problem diff --git a/docs/wiki/Guarantees-and-Limitations.md b/docs/wiki/Guarantees-and-Limitations.md index 0f63e8d5..7a3da89b 100644 --- a/docs/wiki/Guarantees-and-Limitations.md +++ b/docs/wiki/Guarantees-and-Limitations.md @@ -133,8 +133,23 @@ until its own entry expires. Treat that duration as a compliance parameter rathe turn caching off where an erasure must be immediate everywhere. Key material is never written to a distributed cache. -Key rotation is **not** implemented: `ProtectedPayload` records no key identifier, so there is no way to -tell which key a payload used. See [Crypto Key Management](Crypto-Key-Management-Design.md). +### Rotation + +**SQL Server and PostgreSQL only.** A subject can hold several key generations; the highest is +current and is used for new payloads. `ProtectedPayload` records which generation it was encrypted +under (`kid`), so **rotation never makes existing events unreadable** - earlier generations are +retained deliberately. + +Rotation limits the blast radius of a future key compromise. It does **not** re-encrypt history, and +it is distinct from erasure: `ShredAsync` removes *every* generation, because one left behind would +mean the subject's older events were still readable. + +A payload written before rotation existed carries no `kid`, which a reader treats as "the subject's +only key" - so the field is backward compatible and needs no upcaster. + +A store that cannot hold multiple generations - Azure Storage, MongoDB, both Key Vault stores, and +the in-memory one - simply does not implement `IRotatingEventCryptoKeyStore`, and payloads are +written without a key identifier exactly as before. ## Multi-tenancy diff --git a/docs/wiki/Provider-Feature-Matrix.md b/docs/wiki/Provider-Feature-Matrix.md index 51b77001..a69f043e 100644 --- a/docs/wiki/Provider-Feature-Matrix.md +++ b/docs/wiki/Provider-Feature-Matrix.md @@ -19,6 +19,7 @@ per-registration values. | [Subscriptions](Subscriptions.md) (catch-up over the event stream) | Contracts + `AddEventSubscription` | Yes | Yes | Yes | Yes | No (no event stream) | | Durable subscription checkpoints | In-memory only (replays after restart) | `AddSqlServerSubscriptionCheckpoints()` | `AddPostgresSubscriptionCheckpoints()` | `AddAzureStorageSubscriptionCheckpoints()` | `AddMongoDBSubscriptionCheckpoints()` | n/a | | Durable crypto-shredding key store | In-memory only (refused outside Development) | `AddSqlServerEventCryptoShredding()` | `AddPostgresEventCryptoShredding()` | `AddAzureStorageEventCryptoShredding()` | `AddMongoDBEventCryptoShredding()` | n/a | +| Crypto key rotation | `IRotatingEventCryptoKeyStore` | Yes | Yes | No | No | n/a | | Event-stream retention / pruning | No | No | No | No | No | n/a | | Provider-specific native transaction factory | No | `ISqlServerEventStoreTransactionFactory` | `IPostgresEventStoreTransactionFactory` | No | No | No | | Runtime-configured JSON payload indexes | No | Yes (event + snapshot stores, auto-create path) | Yes (GIN + expression indexes on event + snapshot stores) | No | No | Yes (container indexing policy, including composite and spatial paths) | diff --git a/skills/event-sourcing-crypto-shredding/SKILL.md b/skills/event-sourcing-crypto-shredding/SKILL.md index 33ccd45a..ea606459 100644 --- a/skills/event-sourcing-crypto-shredding/SKILL.md +++ b/skills/event-sourcing-crypto-shredding/SKILL.md @@ -77,6 +77,26 @@ Pick secret-per-subject when erasure itself must be vault-audited; pick envelope population makes that impractical. The envelope store never writes a usable key to the durable store, so a stolen database is unreadable without the vault. +### Rotation, where the store supports it + +SQL Server and PostgreSQL hold multiple key generations per subject. `ProtectedPayload` records +which one encrypted it, so rotating never makes existing events unreadable - old generations are +kept on purpose. + +```csharp +var keyId = await rotatingStore.RotateAsync(dataSubjectId, cancellationToken); +``` + +Two things to keep straight: + +- **Rotation is not erasure.** `ShredAsync` deletes every generation; rotation adds one. A shred + that left an older generation behind would not be an erasure. +- **Rotation does not re-encrypt history.** It limits what a future key compromise exposes; it does + nothing about what an attacker already has. + +Elsewhere - Azure Storage, MongoDB, Key Vault, in-memory - the store does not implement +`IRotatingEventCryptoKeyStore` and payloads carry no key identifier, exactly as before. + ### Caching bounds how fast an erasure takes effect Keys are cached in process by default - an uncached store makes every protect and unprotect a round diff --git a/src/src/EventSourcing/Cryptography/AesGcmEventPayloadProtector.cs b/src/src/EventSourcing/Cryptography/AesGcmEventPayloadProtector.cs index 5eae831f..2d4900e6 100644 --- a/src/src/EventSourcing/Cryptography/AesGcmEventPayloadProtector.cs +++ b/src/src/EventSourcing/Cryptography/AesGcmEventPayloadProtector.cs @@ -35,7 +35,16 @@ public async Task ProtectAsync( ArgumentNullException.ThrowIfNull(payload); ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); - var key = await keyStore.GetOrCreateAsync(dataSubjectId, cancellationToken); + // A rotating store records which generation was used, so a later rotation does not make this + // payload unreadable. A store without rotation writes no identifier, which is exactly what + // every payload written before rotation existed looks like. + string? keyId = null; + byte[] key; + if (Rotating is { } rotating) + (keyId, key) = await rotating.GetCurrentAsync(dataSubjectId, cancellationToken); + else + key = await keyStore.GetOrCreateAsync(dataSubjectId, cancellationToken); + var plaintext = Encoding.UTF8.GetBytes(payload); var nonce = new byte[AesGcm.NonceByteSizes.MaxSize]; @@ -51,6 +60,7 @@ public async Task ProtectAsync( new ProtectedPayload { DataSubjectId = dataSubjectId, + KeyId = keyId, Nonce = Convert.ToBase64String(nonce), Tag = Convert.ToBase64String(tag), CipherText = Convert.ToBase64String(cipherText), @@ -70,7 +80,12 @@ public async Task ProtectAsync( EventStoreSerializationHelpers.Deserialize(payload) ?? throw new InvalidOperationException("The payload is marked as protected but could not be read."); - var key = await keyStore.TryGetAsync(envelope.DataSubjectId, cancellationToken); + // A payload carrying a generation must be decrypted with that generation, not the current + // one - otherwise every rotation would silently break everything written before it. + var key = + envelope.KeyId is { } writtenWith && Rotating is { } rotating + ? await rotating.TryGetAsync(envelope.DataSubjectId, writtenWith, cancellationToken) + : await keyStore.TryGetAsync(envelope.DataSubjectId, cancellationToken); if (key is null) // The subject has been erased. Expected, not exceptional: the caller turns this into a // skipped event so replay continues and the gap stays visible. @@ -87,6 +102,12 @@ public async Task ProtectAsync( return Encoding.UTF8.GetString(plaintext); } + // No unwrapping here: a decorator implements the interface and reports whether the store it wraps + // actually supports rotation, which is what SupportsRotation is for. Unwrapping would find the + // real store and then have to call through the decorator anyway, losing its caching. + IRotatingEventCryptoKeyStore? Rotating => + keyStore is IRotatingEventCryptoKeyStore { SupportsRotation: true } rotating ? rotating : null; + /// public bool IsProtected(string payload) => payload is not null && payload.Contains(ProtectedPayload.MarkerPropertyName, StringComparison.Ordinal); diff --git a/src/src/EventSourcing/Cryptography/CachingEventCryptoKeyStore.cs b/src/src/EventSourcing/Cryptography/CachingEventCryptoKeyStore.cs index 60aa8624..d4c85037 100644 --- a/src/src/EventSourcing/Cryptography/CachingEventCryptoKeyStore.cs +++ b/src/src/EventSourcing/Cryptography/CachingEventCryptoKeyStore.cs @@ -29,7 +29,10 @@ namespace Purview.EventSourcing.Cryptography; /// legitimately created, which looks exactly like erasure and is far harder to diagnose. /// /// -public sealed class CachingEventCryptoKeyStore : IEventCryptoKeyStore, IEventCryptoKeyStoreDecorator, IDisposable +public sealed class CachingEventCryptoKeyStore + : IRotatingEventCryptoKeyStore, + IEventCryptoKeyStoreDecorator, + IDisposable { readonly IEventCryptoKeyStore _inner; readonly ICurrentTenant _currentTenant; @@ -58,6 +61,85 @@ public CachingEventCryptoKeyStore( /// public IEventCryptoKeyStore Inner => _inner; + /// + public bool SupportsRotation => _inner is IRotatingEventCryptoKeyStore { SupportsRotation: true }; + + /// + /// + /// The current generation is cached like any other key, so a rotation on another instance takes + /// up to to be picked up here. That delays the + /// benefit of rotating; it does not break anything, because payloads written under the previous + /// generation stay readable. + /// + public async Task<(string KeyId, byte[] Key)> GetCurrentAsync( + string dataSubjectId, + CancellationToken cancellationToken + ) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + var cacheKey = CurrentCacheKeyFor(dataSubjectId); + if (_cache.TryGetValue(cacheKey, out (string KeyId, byte[] Key) cached) && cached.Key is not null) + return cached; + + var current = await RotatingInner.GetCurrentAsync(dataSubjectId, cancellationToken); + _cache.Set( + cacheKey, + current, + new MemoryCacheEntryOptions { AbsoluteExpirationRelativeToNow = _duration, Size = current.Key.Length } + ); + + return current; + } + + /// + public async Task TryGetAsync(string dataSubjectId, string keyId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + ArgumentException.ThrowIfNullOrWhiteSpace(keyId); + + var cacheKey = GenerationCacheKeyFor(dataSubjectId, keyId); + if (_cache.TryGetValue(cacheKey, out byte[]? cached) && cached is not null) + return cached; + + var fetched = await RotatingInner.TryGetAsync(dataSubjectId, keyId, cancellationToken); + if (fetched is not null) + Store(cacheKey, fetched); + + return fetched; + } + + /// + public async Task RotateAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + // Evict the cached current generation before and after, for the same reason as a shred: a + // reader racing the rotation can put the previous one back. + _cache.Remove(CurrentCacheKeyFor(dataSubjectId)); + try + { + return await RotatingInner.RotateAsync(dataSubjectId, cancellationToken); + } + finally + { + _cache.Remove(CurrentCacheKeyFor(dataSubjectId)); + _cache.Remove(CacheKeyFor(dataSubjectId)); + } + } + + IRotatingEventCryptoKeyStore RotatingInner => + _inner as IRotatingEventCryptoKeyStore + ?? throw new NotSupportedException( + $"The configured key store '{_inner.GetType().Name}' does not support key rotation." + ); + + (string Tenant, string Subject, string Marker) CurrentCacheKeyFor(string dataSubjectId) => + (TenantColumn.Encode(_currentTenant.Current), dataSubjectId, "current"); + + (string Tenant, string Subject, string KeyId) GenerationCacheKeyFor(string dataSubjectId, string keyId) => + (TenantColumn.Encode(_currentTenant.Current), dataSubjectId, keyId); + /// public async Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) { diff --git a/src/src/EventSourcing/Cryptography/IRotatingEventCryptoKeyStore.cs b/src/src/EventSourcing/Cryptography/IRotatingEventCryptoKeyStore.cs new file mode 100644 index 00000000..7f11d269 --- /dev/null +++ b/src/src/EventSourcing/Cryptography/IRotatingEventCryptoKeyStore.cs @@ -0,0 +1,58 @@ +namespace Purview.EventSourcing.Cryptography; + +/// +/// An that can hold more than one key generation per data +/// subject, so a key can be rotated without rewriting history. +/// +/// +/// +/// Rotation limits the blast radius of a future key compromise: payloads written after it use the +/// new key. It does not re-encrypt existing events, so older generations must be +/// retained or everything written under them becomes unreadable. +/// +/// +/// Rotation and erasure stay distinct. removes +/// every generation for a subject - a shred that left an older key behind would not be an +/// erasure at all. +/// +/// +/// Optional: a store that cannot hold multiple generations simply does not implement this, and +/// payloads are written without a key identifier exactly as before. +/// +/// +public interface IRotatingEventCryptoKeyStore : IEventCryptoKeyStore +{ + /// + /// Whether rotation is actually available. + /// + /// + /// A decorator implements this interface to pass rotation through, but can only support it when + /// the store it wraps does. Check this rather than the interface alone. + /// + bool SupportsRotation { get; } + + /// + /// Gets the subject's current key, creating the first generation when there is none. + /// + /// The subject the key belongs to. + /// A token that can be used to cancel the operation. + /// The current key and the identifier recorded alongside payloads encrypted with it. + Task<(string KeyId, byte[] Key)> GetCurrentAsync(string dataSubjectId, CancellationToken cancellationToken); + + /// + /// Gets a specific generation of a subject's key, or when it has been + /// erased or never existed. + /// + /// The subject the key belongs to. + /// The generation recorded on the payload. + /// A token that can be used to cancel the operation. + Task TryGetAsync(string dataSubjectId, string keyId, CancellationToken cancellationToken); + + /// + /// Creates a new current generation for the subject, retaining the previous ones. + /// + /// The subject to rotate. + /// A token that can be used to cancel the operation. + /// The identifier of the new current key. + Task RotateAsync(string dataSubjectId, CancellationToken cancellationToken); +} diff --git a/src/src/EventSourcing/Cryptography/ProtectedPayload.cs b/src/src/EventSourcing/Cryptography/ProtectedPayload.cs index 1907710b..812eaddf 100644 --- a/src/src/EventSourcing/Cryptography/ProtectedPayload.cs +++ b/src/src/EventSourcing/Cryptography/ProtectedPayload.cs @@ -33,6 +33,18 @@ public sealed record ProtectedPayload [JsonPropertyName("sub")] public string DataSubjectId { get; init; } = default!; + /// + /// The generation of the subject's key the payload was encrypted with. + /// + /// + /// Absent when the key store does not hold multiple generations, which is what every payload + /// written before rotation existed looks like. A reader treats a missing identifier as "the + /// subject's only key", so the addition is backward compatible and needs no upcaster. + /// + [JsonPropertyName("kid")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string? KeyId { get; init; } + /// The base64 nonce. [JsonPropertyName("n")] public string Nonce { get; init; } = default!; diff --git a/src/src/Postgres/Cryptography/PostgresEventCryptoKeyStore.cs b/src/src/Postgres/Cryptography/PostgresEventCryptoKeyStore.cs index e851266a..a13a811d 100644 --- a/src/src/Postgres/Cryptography/PostgresEventCryptoKeyStore.cs +++ b/src/src/Postgres/Cryptography/PostgresEventCryptoKeyStore.cs @@ -1,3 +1,4 @@ +using System.Globalization; using System.Text.RegularExpressions; using Microsoft.Extensions.Options; using Npgsql; @@ -26,7 +27,10 @@ namespace Purview.EventSourcing.Postgres.Cryptography; /// when the last backup containing the key ages out. /// /// -public sealed partial class PostgresEventCryptoKeyStore : ISuppliedKeyEventCryptoKeyStore, IDisposable +public sealed partial class PostgresEventCryptoKeyStore + : ISuppliedKeyEventCryptoKeyStore, + IRotatingEventCryptoKeyStore, + IDisposable { [GeneratedRegex("^[\\w\\-.]+$", RegexOptions.Compiled)] private static partial Regex ValidIdentifier(); @@ -59,6 +63,9 @@ public PostgresEventCryptoKeyStore( _table = QuoteIdentifier(keyStoreOptions.Value.TableName); } + /// + public bool SupportsRotation => true; + /// public Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) => GetOrAddAsync(dataSubjectId, AesGcmEventPayloadProtector.CreateKey(), cancellationToken); @@ -86,9 +93,9 @@ CancellationToken cancellationToken // returns the stored row either way, which is the point. await using NpgsqlCommand command = new( $""" - INSERT INTO {_schema}.{_table} ("TenantId", "DataSubjectId", "KeyMaterial", "CreatedUtc") - VALUES (@tenantId, @subject, @key, @now) - ON CONFLICT ("TenantId", "DataSubjectId") DO UPDATE + INSERT INTO {_schema}.{_table} ("TenantId", "DataSubjectId", "Generation", "KeyMaterial", "CreatedUtc") + VALUES (@tenantId, @subject, 1, @key, @now) + ON CONFLICT ("TenantId", "DataSubjectId", "Generation") DO UPDATE SET "KeyMaterial" = {_table}."KeyMaterial" RETURNING "KeyMaterial" """, @@ -108,8 +115,40 @@ ON CONFLICT ("TenantId", "DataSubjectId") DO UPDATE /// public async Task TryGetAsync(string dataSubjectId, CancellationToken cancellationToken) + { + var current = await TryGetCurrentAsync(dataSubjectId, cancellationToken); + + return current?.Key; + } + + /// + public async Task<(string KeyId, byte[] Key)> GetCurrentAsync( + string dataSubjectId, + CancellationToken cancellationToken + ) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + var current = await TryGetCurrentAsync(dataSubjectId, cancellationToken); + if (current is not null) + return current.Value; + + await GetOrAddAsync(dataSubjectId, AesGcmEventPayloadProtector.CreateKey(), cancellationToken); + + return await TryGetCurrentAsync(dataSubjectId, cancellationToken) + ?? throw new InvalidOperationException( + $"The key for data subject '{dataSubjectId}' could not be read back immediately after being created." + ); + } + + /// + public async Task TryGetAsync(string dataSubjectId, string keyId, CancellationToken cancellationToken) { ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + ArgumentException.ThrowIfNullOrWhiteSpace(keyId); + + if (!int.TryParse(keyId, NumberStyles.None, CultureInfo.InvariantCulture, out var generation)) + return null; await EnsureSchemaAsync(cancellationToken); @@ -119,15 +158,92 @@ ON CONFLICT ("TenantId", "DataSubjectId") DO UPDATE await using NpgsqlCommand command = new( $""" SELECT "KeyMaterial" FROM {_schema}.{_table} + WHERE "TenantId" = @tenantId AND "DataSubjectId" = @subject AND "Generation" = @generation + """, + connection + ); + AddKeyParameters(command, dataSubjectId); + command.Parameters.AddWithValue("@generation", generation); + + return await command.ExecuteScalarAsync(cancellationToken) as byte[]; + } + + /// + public async Task RotateAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + await EnsureSchemaAsync(cancellationToken); + + // Retried because two concurrent rotations compute the same next generation and one loses on + // the primary key. Losing is harmless - the winner's generation becomes current - but the + // loser must observe that rather than report a generation it did not create. + for (var attempt = 0; attempt < 5; attempt++) + { + await using NpgsqlConnection connection = new(_connectionString); + await connection.OpenAsync(cancellationToken); + + await using NpgsqlCommand command = new( + $""" + INSERT INTO {_schema}.{_table} ("TenantId", "DataSubjectId", "Generation", "KeyMaterial", "CreatedUtc") + SELECT @tenantId, @subject, COALESCE(MAX("Generation"), 0) + 1, @key, @now + FROM {_schema}.{_table} + WHERE "TenantId" = @tenantId AND "DataSubjectId" = @subject + RETURNING "Generation" + """, + connection + ); + AddKeyParameters(command, dataSubjectId); + command.Parameters.AddWithValue("@key", AesGcmEventPayloadProtector.CreateKey()); + command.Parameters.AddWithValue("@now", DateTimeOffset.UtcNow); + + try + { + var next = await command.ExecuteScalarAsync(cancellationToken); + + return Convert.ToInt32(next, CultureInfo.InvariantCulture).ToString(CultureInfo.InvariantCulture); + } + catch (PostgresException ex) when (ex.SqlState == "23505") + { + // Another rotation took this generation; recompute and try again. + } + } + + throw new InvalidOperationException( + $"The key for data subject '{dataSubjectId}' could not be rotated after repeated contention." + ); + } + + async Task<(string KeyId, byte[] Key)?> TryGetCurrentAsync( + string dataSubjectId, + CancellationToken cancellationToken + ) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + await EnsureSchemaAsync(cancellationToken); + + await using NpgsqlConnection connection = new(_connectionString); + await connection.OpenAsync(cancellationToken); + + await using NpgsqlCommand command = new( + $""" + SELECT "Generation", "KeyMaterial" FROM {_schema}.{_table} WHERE "TenantId" = @tenantId AND "DataSubjectId" = @subject + ORDER BY "Generation" DESC + LIMIT 1 """, connection ); AddKeyParameters(command, dataSubjectId); - var result = await command.ExecuteScalarAsync(cancellationToken); + await using var reader = await command.ExecuteReaderAsync(cancellationToken); + if (!await reader.ReadAsync(cancellationToken)) + return null; + + var generation = reader.GetInt32(0); - return result as byte[]; + return (generation.ToString(CultureInfo.InvariantCulture), (byte[])reader[1]); } /// @@ -178,9 +294,10 @@ async Task EnsureSchemaAsync(CancellationToken cancellationToken) CREATE TABLE IF NOT EXISTS {_schema}.{_table} ( "TenantId" VARCHAR(256) NOT NULL, "DataSubjectId" VARCHAR(256) NOT NULL, + "Generation" INTEGER NOT NULL, "KeyMaterial" BYTEA NOT NULL, "CreatedUtc" TIMESTAMPTZ NOT NULL, - PRIMARY KEY ("TenantId", "DataSubjectId") + PRIMARY KEY ("TenantId", "DataSubjectId", "Generation") ); """, connection diff --git a/src/src/SqlServer/Cryptography/SqlServerEventCryptoKeyStore.cs b/src/src/SqlServer/Cryptography/SqlServerEventCryptoKeyStore.cs index 72bb198c..e2ccfe11 100644 --- a/src/src/SqlServer/Cryptography/SqlServerEventCryptoKeyStore.cs +++ b/src/src/SqlServer/Cryptography/SqlServerEventCryptoKeyStore.cs @@ -1,3 +1,4 @@ +using System.Globalization; using System.Text.RegularExpressions; using Microsoft.Data.SqlClient; using Microsoft.Extensions.Options; @@ -11,7 +12,7 @@ namespace Purview.EventSourcing.SqlServer.Cryptography; #pragma warning disable CA2100 /// -/// A durable backed by a SQL Server table. +/// A durable, rotating backed by a SQL Server table. /// /// /// @@ -20,13 +21,21 @@ namespace Purview.EventSourcing.SqlServer.Cryptography; /// other's. /// /// +/// A subject can hold several key generations. The highest is current and is used for new payloads; +/// earlier ones are retained because the events written under them would otherwise be unreadable. +/// Erasure removes every generation - a shred that left one behind would not be an erasure. +/// +/// /// Erasure is only as irreversible as the least-irreversible copy of the key. A /// point-in-time restore of this table brings shredded keys back, so a deployment that must erase /// on request has to exclude it from long-retention backups, or accept that erasure completes only /// when the last backup containing the key ages out. /// /// -public sealed partial class SqlServerEventCryptoKeyStore : ISuppliedKeyEventCryptoKeyStore, IDisposable +public sealed partial class SqlServerEventCryptoKeyStore + : ISuppliedKeyEventCryptoKeyStore, + IRotatingEventCryptoKeyStore, + IDisposable { [GeneratedRegex("^[\\w\\-.]+$", RegexOptions.Compiled)] private static partial Regex ValidIdentifier(); @@ -59,10 +68,33 @@ public SqlServerEventCryptoKeyStore( _table = QuoteIdentifier(keyStoreOptions.Value.TableName); } + /// + public bool SupportsRotation => true; + /// public Task GetOrCreateAsync(string dataSubjectId, CancellationToken cancellationToken) => GetOrAddAsync(dataSubjectId, AesGcmEventPayloadProtector.CreateKey(), cancellationToken); + /// + public async Task<(string KeyId, byte[] Key)> GetCurrentAsync( + string dataSubjectId, + CancellationToken cancellationToken + ) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + var current = await TryGetCurrentAsync(dataSubjectId, cancellationToken); + if (current is not null) + return current.Value; + + await GetOrAddAsync(dataSubjectId, AesGcmEventPayloadProtector.CreateKey(), cancellationToken); + + return await TryGetCurrentAsync(dataSubjectId, cancellationToken) + ?? throw new InvalidOperationException( + $"The key for data subject '{dataSubjectId}' could not be read back immediately after being created." + ); + } + /// public async Task GetOrAddAsync( string dataSubjectId, @@ -80,8 +112,9 @@ CancellationToken cancellationToken await using SqlConnection connection = new(_connectionString); await connection.OpenAsync(cancellationToken); - // Insert-if-absent, then re-read: two callers racing to create the first key for a subject - // must end up with the same key, or payloads written by the loser become unreadable. + // Insert the first generation only if the subject has none. Two callers racing to create it + // must end up with the same key, or payloads written by the loser become unreadable, so the + // duplicate-key failure is swallowed and the stored value re-read. await using SqlCommand command = new( $""" IF NOT EXISTS ( @@ -89,8 +122,9 @@ IF NOT EXISTS ( ) BEGIN BEGIN TRY - INSERT INTO {_schema}.{_table} ([TenantId], [DataSubjectId], [KeyMaterial], [CreatedUtc]) - VALUES (@tenantId, @subject, @key, @now); + INSERT INTO {_schema}.{_table} + ([TenantId], [DataSubjectId], [Generation], [KeyMaterial], [CreatedUtc]) + VALUES (@tenantId, @subject, 1, @key, @now); END TRY BEGIN CATCH IF ERROR_NUMBER() NOT IN (2601, 2627) THROW; @@ -113,8 +147,20 @@ END CATCH /// public async Task TryGetAsync(string dataSubjectId, CancellationToken cancellationToken) + { + var current = await TryGetCurrentAsync(dataSubjectId, cancellationToken); + + return current?.Key; + } + + /// + public async Task TryGetAsync(string dataSubjectId, string keyId, CancellationToken cancellationToken) { ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + ArgumentException.ThrowIfNullOrWhiteSpace(keyId); + + if (!int.TryParse(keyId, NumberStyles.None, CultureInfo.InvariantCulture, out var generation)) + return null; await EnsureSchemaAsync(cancellationToken); @@ -124,18 +170,69 @@ END CATCH await using SqlCommand command = new( $""" SELECT [KeyMaterial] FROM {_schema}.{_table} - WHERE [TenantId] = @tenantId AND [DataSubjectId] = @subject + WHERE [TenantId] = @tenantId AND [DataSubjectId] = @subject AND [Generation] = @generation """, connection ); AddKeyParameters(command, dataSubjectId); + command.Parameters.AddWithValue("@generation", generation); - var result = await command.ExecuteScalarAsync(cancellationToken); + return await command.ExecuteScalarAsync(cancellationToken) as byte[]; + } - return result as byte[]; + /// + public async Task RotateAsync(string dataSubjectId, CancellationToken cancellationToken) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + await EnsureSchemaAsync(cancellationToken); + + // Retried because two concurrent rotations compute the same next generation and one loses on + // the unique index. Losing is harmless - the winner's generation becomes current - but the + // loser must observe that rather than report a generation it did not create. + for (var attempt = 0; attempt < 5; attempt++) + { + await using SqlConnection connection = new(_connectionString); + await connection.OpenAsync(cancellationToken); + + await using SqlCommand command = new( + $""" + DECLARE @next INT = ( + SELECT ISNULL(MAX([Generation]), 0) + 1 FROM {_schema}.{_table} + WHERE [TenantId] = @tenantId AND [DataSubjectId] = @subject + ); + + INSERT INTO {_schema}.{_table} + ([TenantId], [DataSubjectId], [Generation], [KeyMaterial], [CreatedUtc]) + VALUES (@tenantId, @subject, @next, @key, @now); + + SELECT @next; + """, + connection + ); + AddKeyParameters(command, dataSubjectId); + command.Parameters.AddWithValue("@key", AesGcmEventPayloadProtector.CreateKey()); + command.Parameters.AddWithValue("@now", DateTimeOffset.UtcNow); + + try + { + var next = await command.ExecuteScalarAsync(cancellationToken); + + return Convert.ToInt32(next, CultureInfo.InvariantCulture).ToString(CultureInfo.InvariantCulture); + } + catch (SqlException ex) when (ex.Number is 2601 or 2627) + { + // Another rotation took this generation; recompute and try again. + } + } + + throw new InvalidOperationException( + $"The key for data subject '{dataSubjectId}' could not be rotated after repeated contention." + ); } /// + /// Removes every generation: an erasure that left one behind would not be an erasure. public async Task ShredAsync(string dataSubjectId, CancellationToken cancellationToken) { ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); @@ -154,6 +251,37 @@ public async Task ShredAsync(string dataSubjectId, CancellationToken cance return await command.ExecuteNonQueryAsync(cancellationToken) > 0; } + async Task<(string KeyId, byte[] Key)?> TryGetCurrentAsync( + string dataSubjectId, + CancellationToken cancellationToken + ) + { + ArgumentException.ThrowIfNullOrWhiteSpace(dataSubjectId); + + await EnsureSchemaAsync(cancellationToken); + + await using SqlConnection connection = new(_connectionString); + await connection.OpenAsync(cancellationToken); + + await using SqlCommand command = new( + $""" + SELECT TOP 1 [Generation], [KeyMaterial] FROM {_schema}.{_table} + WHERE [TenantId] = @tenantId AND [DataSubjectId] = @subject + ORDER BY [Generation] DESC + """, + connection + ); + AddKeyParameters(command, dataSubjectId); + + await using var reader = await command.ExecuteReaderAsync(cancellationToken); + if (!await reader.ReadAsync(cancellationToken)) + return null; + + var generation = reader.GetInt32(0); + + return (generation.ToString(CultureInfo.InvariantCulture), (byte[])reader[1]); + } + void AddKeyParameters(SqlCommand command, string dataSubjectId) { command.Parameters.AddWithValue("@tenantId", TenantColumn.Encode(_currentTenant.Current)); @@ -201,10 +329,12 @@ IF OBJECT_ID(N'{_schema}.{_table}', N'U') IS NULL CREATE TABLE {_schema}.{_table} ( [TenantId] NVARCHAR(256) NOT NULL, [DataSubjectId] NVARCHAR(256) NOT NULL, + [Generation] INT NOT NULL, [KeyMaterial] VARBINARY(256) NOT NULL, [CreatedUtc] DATETIMEOFFSET NOT NULL ); - CREATE UNIQUE INDEX {indexName} ON {_schema}.{_table} ([TenantId], [DataSubjectId]); + CREATE UNIQUE INDEX {indexName} ON {_schema}.{_table} + ([TenantId], [DataSubjectId], [Generation]); END END TRY BEGIN CATCH diff --git a/src/tests/Postgres.IntegrationTests/Cryptography/PostgresEventCryptoKeyRotationTests.cs b/src/tests/Postgres.IntegrationTests/Cryptography/PostgresEventCryptoKeyRotationTests.cs new file mode 100644 index 00000000..6fdfc9b6 --- /dev/null +++ b/src/tests/Postgres.IntegrationTests/Cryptography/PostgresEventCryptoKeyRotationTests.cs @@ -0,0 +1,166 @@ +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Cryptography; +using Purview.EventSourcing.Fixtures.Postgres; +using Purview.EventSourcing.Postgres.Events; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.Postgres.Cryptography; + +/// +/// Key rotation against real PostgreSQL. +/// +/// +/// Rotation limits the blast radius of a future key compromise. It does not re-encrypt history, so +/// the property that matters is that everything written under an earlier generation stays readable - +/// a rotation that quietly broke old events would be far worse than not rotating at all. +/// +[ClassDataSource(Shared = SharedType.PerTestSession)] +public sealed class PostgresEventCryptoKeyRotationTests(PostgresEventStoreFixture fixture) +{ + [Test] + public async Task RotateAsync_ProducesANewCurrentGeneration(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var before = await AsTenantAsync("acme", () => store.GetCurrentAsync(subject, cancellationToken)); + var rotated = await AsTenantAsync("acme", () => store.RotateAsync(subject, cancellationToken)); + var after = await AsTenantAsync("acme", () => store.GetCurrentAsync(subject, cancellationToken)); + + await Assert.That(rotated).IsNotEqualTo(before.KeyId); + await Assert.That(after.KeyId).IsEqualTo(rotated); + await Assert.That(Convert.ToBase64String(after.Key)).IsNotEqualTo(Convert.ToBase64String(before.Key)); + } + + [Test] + public async Task TryGetAsync_AfterRotation_StillReturnsTheEarlierGeneration(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var before = await AsTenantAsync("acme", () => store.GetCurrentAsync(subject, cancellationToken)); + await AsTenantAsync("acme", () => store.RotateAsync(subject, cancellationToken)); + + var earlier = await AsTenantAsync("acme", () => store.TryGetAsync(subject, before.KeyId, cancellationToken)); + + await Assert.That(Convert.ToBase64String(earlier!)).IsEqualTo(Convert.ToBase64String(before.Key)); + } + + // The whole point of retaining generations: a payload written before a rotation must still be + // readable afterwards. + [Test] + public async Task UnprotectAsync_ReadsAPayloadWrittenBeforeRotation(CancellationToken cancellationToken) + { + using var store = CreateStore(); + AesGcmEventPayloadProtector protector = new(store); + var subject = $"{Guid.NewGuid():N}"; + + var before = await AsTenantAsync( + "acme", + () => protector.ProtectAsync("""{"value":"written-before"}""", subject, cancellationToken) + ); + + await AsTenantAsync("acme", () => store.RotateAsync(subject, cancellationToken)); + + var after = await AsTenantAsync( + "acme", + () => protector.ProtectAsync("""{"value":"written-after"}""", subject, cancellationToken) + ); + + var readBefore = await AsTenantAsync("acme", () => protector.UnprotectAsync(before, cancellationToken)); + var readAfter = await AsTenantAsync("acme", () => protector.UnprotectAsync(after, cancellationToken)); + + await Assert.That(readBefore).IsEqualTo("""{"value":"written-before"}"""); + await Assert.That(readAfter).IsEqualTo("""{"value":"written-after"}"""); + } + + // Erasure must remove every generation. One left behind would mean the subject's older events + // were still readable, which is not an erasure. + [Test] + public async Task ShredAsync_RemovesEveryGeneration(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var first = await AsTenantAsync("acme", () => store.GetCurrentAsync(subject, cancellationToken)); + var second = await AsTenantAsync("acme", () => store.RotateAsync(subject, cancellationToken)); + + await AsTenantAsync("acme", () => store.ShredAsync(subject, cancellationToken)); + + var firstAfter = await AsTenantAsync("acme", () => store.TryGetAsync(subject, first.KeyId, cancellationToken)); + var secondAfter = await AsTenantAsync("acme", () => store.TryGetAsync(subject, second, cancellationToken)); + + await Assert.That(firstAfter).IsNull(); + await Assert.That(secondAfter).IsNull(); + } + + // Rotating one tenant's subject must not touch another tenant's subject of the same name. + [Test] + public async Task RotateAsync_IsScopedToTheTenant(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var globexBefore = await AsTenantAsync("globex", () => store.GetCurrentAsync(subject, cancellationToken)); + await AsTenantAsync("acme", () => store.RotateAsync(subject, cancellationToken)); + var globexAfter = await AsTenantAsync("globex", () => store.GetCurrentAsync(subject, cancellationToken)); + + await Assert.That(globexAfter.KeyId).IsEqualTo(globexBefore.KeyId); + await Assert.That(Convert.ToBase64String(globexAfter.Key)).IsEqualTo(Convert.ToBase64String(globexBefore.Key)); + } + + [Test] + public async Task TryGetAsync_GivenAnUnknownGeneration_ReturnsNull(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + await AsTenantAsync("acme", () => store.GetCurrentAsync(subject, cancellationToken)); + + var missing = await AsTenantAsync("acme", () => store.TryGetAsync(subject, "99", cancellationToken)); + var nonsense = await AsTenantAsync( + "acme", + () => store.TryGetAsync(subject, "not-a-generation", cancellationToken) + ); + + await Assert.That(missing).IsNull(); + await Assert.That(nonsense).IsNull(); + } + + // Concurrent rotations collide on the generation index; the loser must retry rather than fail. + [Test] + public async Task RotateAsync_UnderContention_ProducesDistinctGenerations(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + await AsTenantAsync("acme", () => store.GetCurrentAsync(subject, cancellationToken)); + + var generations = await AsTenantAsync( + "acme", + async () => + await Task.WhenAll(Enumerable.Range(0, 4).Select(_ => store.RotateAsync(subject, cancellationToken))) + ); + + await Assert.That(generations.Distinct().Count()).IsEqualTo(generations.Length); + } + + static async Task AsTenantAsync(string tenant, Func> operation) + { + using (AmbientCurrentTenant.BeginScope(TenantScope.For(tenant))) + return await operation(); + } + + PostgresEventCryptoKeyStore CreateStore() => + new( + Options.Create( + new PostgresEventCryptoKeyStoreOptions + { + ConnectionString = fixture.ConnectionString, + TableName = $"CryptoKeys_{Guid.NewGuid():N}", + } + ), + Options.Create(new PostgresEventStoreOptions { ConnectionString = fixture.ConnectionString }), + new AmbientCurrentTenant() + ); +} diff --git a/src/tests/SqlServer.IntegrationTests/Cryptography/SqlServerEventCryptoKeyRotationTests.cs b/src/tests/SqlServer.IntegrationTests/Cryptography/SqlServerEventCryptoKeyRotationTests.cs new file mode 100644 index 00000000..0b00ddec --- /dev/null +++ b/src/tests/SqlServer.IntegrationTests/Cryptography/SqlServerEventCryptoKeyRotationTests.cs @@ -0,0 +1,166 @@ +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Cryptography; +using Purview.EventSourcing.Fixtures.SqlServer; +using Purview.EventSourcing.SqlServer.Events; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.SqlServer.Cryptography; + +/// +/// Key rotation against real SQL Server. +/// +/// +/// Rotation limits the blast radius of a future key compromise. It does not re-encrypt history, so +/// the property that matters is that everything written under an earlier generation stays readable - +/// a rotation that quietly broke old events would be far worse than not rotating at all. +/// +[ClassDataSource(Shared = SharedType.PerTestSession)] +public sealed class SqlServerEventCryptoKeyRotationTests(SqlServerEventStoreFixture fixture) +{ + [Test] + public async Task RotateAsync_ProducesANewCurrentGeneration(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var before = await AsTenantAsync("acme", () => store.GetCurrentAsync(subject, cancellationToken)); + var rotated = await AsTenantAsync("acme", () => store.RotateAsync(subject, cancellationToken)); + var after = await AsTenantAsync("acme", () => store.GetCurrentAsync(subject, cancellationToken)); + + await Assert.That(rotated).IsNotEqualTo(before.KeyId); + await Assert.That(after.KeyId).IsEqualTo(rotated); + await Assert.That(Convert.ToBase64String(after.Key)).IsNotEqualTo(Convert.ToBase64String(before.Key)); + } + + [Test] + public async Task TryGetAsync_AfterRotation_StillReturnsTheEarlierGeneration(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var before = await AsTenantAsync("acme", () => store.GetCurrentAsync(subject, cancellationToken)); + await AsTenantAsync("acme", () => store.RotateAsync(subject, cancellationToken)); + + var earlier = await AsTenantAsync("acme", () => store.TryGetAsync(subject, before.KeyId, cancellationToken)); + + await Assert.That(Convert.ToBase64String(earlier!)).IsEqualTo(Convert.ToBase64String(before.Key)); + } + + // The whole point of retaining generations: a payload written before a rotation must still be + // readable afterwards. + [Test] + public async Task UnprotectAsync_ReadsAPayloadWrittenBeforeRotation(CancellationToken cancellationToken) + { + using var store = CreateStore(); + AesGcmEventPayloadProtector protector = new(store); + var subject = $"{Guid.NewGuid():N}"; + + var before = await AsTenantAsync( + "acme", + () => protector.ProtectAsync("""{"value":"written-before"}""", subject, cancellationToken) + ); + + await AsTenantAsync("acme", () => store.RotateAsync(subject, cancellationToken)); + + var after = await AsTenantAsync( + "acme", + () => protector.ProtectAsync("""{"value":"written-after"}""", subject, cancellationToken) + ); + + var readBefore = await AsTenantAsync("acme", () => protector.UnprotectAsync(before, cancellationToken)); + var readAfter = await AsTenantAsync("acme", () => protector.UnprotectAsync(after, cancellationToken)); + + await Assert.That(readBefore).IsEqualTo("""{"value":"written-before"}"""); + await Assert.That(readAfter).IsEqualTo("""{"value":"written-after"}"""); + } + + // Erasure must remove every generation. One left behind would mean the subject's older events + // were still readable, which is not an erasure. + [Test] + public async Task ShredAsync_RemovesEveryGeneration(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var first = await AsTenantAsync("acme", () => store.GetCurrentAsync(subject, cancellationToken)); + var second = await AsTenantAsync("acme", () => store.RotateAsync(subject, cancellationToken)); + + await AsTenantAsync("acme", () => store.ShredAsync(subject, cancellationToken)); + + var firstAfter = await AsTenantAsync("acme", () => store.TryGetAsync(subject, first.KeyId, cancellationToken)); + var secondAfter = await AsTenantAsync("acme", () => store.TryGetAsync(subject, second, cancellationToken)); + + await Assert.That(firstAfter).IsNull(); + await Assert.That(secondAfter).IsNull(); + } + + // Rotating one tenant's subject must not touch another tenant's subject of the same name. + [Test] + public async Task RotateAsync_IsScopedToTheTenant(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + var globexBefore = await AsTenantAsync("globex", () => store.GetCurrentAsync(subject, cancellationToken)); + await AsTenantAsync("acme", () => store.RotateAsync(subject, cancellationToken)); + var globexAfter = await AsTenantAsync("globex", () => store.GetCurrentAsync(subject, cancellationToken)); + + await Assert.That(globexAfter.KeyId).IsEqualTo(globexBefore.KeyId); + await Assert.That(Convert.ToBase64String(globexAfter.Key)).IsEqualTo(Convert.ToBase64String(globexBefore.Key)); + } + + [Test] + public async Task TryGetAsync_GivenAnUnknownGeneration_ReturnsNull(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + await AsTenantAsync("acme", () => store.GetCurrentAsync(subject, cancellationToken)); + + var missing = await AsTenantAsync("acme", () => store.TryGetAsync(subject, "99", cancellationToken)); + var nonsense = await AsTenantAsync( + "acme", + () => store.TryGetAsync(subject, "not-a-generation", cancellationToken) + ); + + await Assert.That(missing).IsNull(); + await Assert.That(nonsense).IsNull(); + } + + // Concurrent rotations collide on the generation index; the loser must retry rather than fail. + [Test] + public async Task RotateAsync_UnderContention_ProducesDistinctGenerations(CancellationToken cancellationToken) + { + using var store = CreateStore(); + var subject = $"{Guid.NewGuid():N}"; + + await AsTenantAsync("acme", () => store.GetCurrentAsync(subject, cancellationToken)); + + var generations = await AsTenantAsync( + "acme", + async () => + await Task.WhenAll(Enumerable.Range(0, 4).Select(_ => store.RotateAsync(subject, cancellationToken))) + ); + + await Assert.That(generations.Distinct().Count()).IsEqualTo(generations.Length); + } + + static async Task AsTenantAsync(string tenant, Func> operation) + { + using (AmbientCurrentTenant.BeginScope(TenantScope.For(tenant))) + return await operation(); + } + + SqlServerEventCryptoKeyStore CreateStore() => + new( + Options.Create( + new SqlServerEventCryptoKeyStoreOptions + { + ConnectionString = fixture.ConnectionString, + TableName = $"CryptoKeys_{Guid.NewGuid():N}", + } + ), + Options.Create(new SqlServerEventStoreOptions { ConnectionString = fixture.ConnectionString }), + new AmbientCurrentTenant() + ); +} From 1baf0336532962e401c079d3c0a8d3674e4a973f Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Mon, 26 Oct 2026 13:50:33 +0000 Subject: [PATCH 24/41] feat: distributed tracing on every provider Tracing existed on SQL Server and PostgreSQL only, while the documentation implied parity. Azure Storage, MongoDB and Cosmos DB now emit spans too, and Azure and Cosmos gained the meter and logger they were missing. Span names match the existing SQL Server contract deliberately: a trace query built against one provider has to keep working when a service moves to another, so span names are a compatibility contract in the same way instrument names already are. Cosmos DB gets snapshot and query spans rather than the aggregate ones. It persists no event stream and delegates aggregate reads and writes to an inner event store that already emits those, so repeating them would double-count every operation in a trace. Two things I set out to do and did not. I had recommended putting aggregate ids behind an option defaulting to off; they are already recorded by the two SQL providers, so suppressing them only on the new ones would have swapped one inconsistency for another. Making it optional should change every provider together, and is noted rather than half-done. And the span assertions do not exist. I added them to the shared contract suite, where a new provider could not omit them, and they failed everywhere - the fixtures inject mocked telemetry, so nothing real is ever started. Rather than leave assertions that cannot fail, they are removed and the gap is recorded in the plan and the guarantees page: the wiring is covered by compilation and by the provider suites exercising those paths, which is weaker than it should be. --- docs/wiki/Guarantees-and-Limitations.md | 23 +++++ docs/wiki/Observability-Parity-Design.md | 17 ++-- docs/wiki/Provider-Feature-Matrix.md | 1 + .../AzureStorage/ITableEventStoreTelemetry.cs | 87 +++++++++++++++++++ .../TableEventStore.DeleteAsync.cs | 2 + .../AzureStorage/TableEventStore.GetAsync.cs | 10 +++ .../TableEventStore.GetAtAsync.cs | 1 + .../TableEventStore.SaveOperation.cs | 3 + src/src/AzureStorage/TableEventStore.cs | 4 + .../CosmosDbSnapshotEventStore.Query.cs | 10 ++- .../Snapshots/CosmosDbSnapshotEventStore.cs | 2 + .../ICosmosDbSnapshotEventStoreTelemetry.cs | 29 ++++++- .../Events/IMongoDBEventStoreTelemetry.cs | 86 ++++++++++++++++++ .../Events/MongoDBEventStore.DeleteAsync.cs | 2 + .../Events/MongoDBEventStore.GetAsync.cs | 10 +++ .../Events/MongoDBEventStore.GetAtAsync.cs | 1 + .../Events/MongoDBEventStore.SaveAsync.cs | 4 + 17 files changed, 284 insertions(+), 8 deletions(-) diff --git a/docs/wiki/Guarantees-and-Limitations.md b/docs/wiki/Guarantees-and-Limitations.md index 7a3da89b..2b0a48e0 100644 --- a/docs/wiki/Guarantees-and-Limitations.md +++ b/docs/wiki/Guarantees-and-Limitations.md @@ -238,6 +238,29 @@ store, so a capability flag could not report it truthfully. Event-stream **retention** is not implemented. Streams grow without bound; nothing removes an event. +## Tracing + +Every provider that persists an event stream emits the same spans - `GetAggregate`, +`GetAggregateAtVersion`, `SaveAggregate`, `DeleteAggregate` - with the aggregate id and type. **Span +names are a compatibility contract**, like instrument names: a trace query built against one provider +keeps working when a service moves to another. + +Cosmos DB emits `SnapshotAggregate` and `QuerySnapshots` instead. It persists no event stream and +delegates aggregate reads and writes to an inner event store, which emits the aggregate-level spans; +emitting them here as well would double-count every operation in a trace. + +The in-memory store emits nothing, deliberately - it exists for tests, and instrumenting it adds noise +to every test run for no diagnostic value. + +Aggregate ids appear in spans on every provider. That has always been true of SQL Server and +PostgreSQL; the other providers now match rather than diverge. If an aggregate id is sensitive in your +domain, note that it reaches whatever trace backend you export to, which usually has different +retention and access rules from the database. + +**No test asserts that spans are emitted.** The provider fixtures inject mocked telemetry, so a test +listening for activities records nothing; the wiring is covered by compilation and by the provider +suites exercising those paths. See [Observability Parity](Observability-Parity-Design.md). + ## Metrics Every storage provider records the same instruments on the `Purview.EventSourcing` meter, so a dashboard diff --git a/docs/wiki/Observability-Parity-Design.md b/docs/wiki/Observability-Parity-Design.md index e8d6e7a1..6b8736e0 100644 --- a/docs/wiki/Observability-Parity-Design.md +++ b/docs/wiki/Observability-Parity-Design.md @@ -1,6 +1,12 @@ # Observability Parity — Design -> **Status: proposal. Nothing on this page is implemented.** +> **Status: implemented, with one gap.** +> +> Tracing now exists on every provider. **Span emission is not asserted by any test**: the provider +> fixtures inject mocked telemetry, so a test listening for real activities records nothing. The +> wiring is covered only by compilation and by the provider suites exercising the code paths, which +> is weaker than it should be. Closing it needs a fixture that uses the generated telemetry rather +> than a mock. ## The problem @@ -11,11 +17,10 @@ exists. Measured from the telemetry interfaces in each provider: | --- | --- | --- | --- | | SQL Server | Yes | Yes | Yes | | PostgreSQL | Yes | Yes | Yes | -| MongoDB | **No** | Yes | Yes | -| Azure Storage | **No** | Yes | **No** | -| Cosmos DB | **No** | **No** | Yes | -| InMemory | **No** | **No** | **No** | - +| MongoDB | Yes | Yes | Yes | +| Azure Storage | Yes | Yes | Yes | +| Cosmos DB | Yes (snapshot and query spans) | Yes | Yes | +| InMemory | No, deliberately | No | No | The cross-provider `IEventStoreMetrics` — `save.duration`, `get.duration`, `events.appended` — *is* uniform, and [Guarantees and Limitations](Guarantees-and-Limitations.md) correctly says so. The gap is **distributed tracing**, which exists on two providers of five. diff --git a/docs/wiki/Provider-Feature-Matrix.md b/docs/wiki/Provider-Feature-Matrix.md index a69f043e..a83e4e16 100644 --- a/docs/wiki/Provider-Feature-Matrix.md +++ b/docs/wiki/Provider-Feature-Matrix.md @@ -20,6 +20,7 @@ per-registration values. | Durable subscription checkpoints | In-memory only (replays after restart) | `AddSqlServerSubscriptionCheckpoints()` | `AddPostgresSubscriptionCheckpoints()` | `AddAzureStorageSubscriptionCheckpoints()` | `AddMongoDBSubscriptionCheckpoints()` | n/a | | Durable crypto-shredding key store | In-memory only (refused outside Development) | `AddSqlServerEventCryptoShredding()` | `AddPostgresEventCryptoShredding()` | `AddAzureStorageEventCryptoShredding()` | `AddMongoDBEventCryptoShredding()` | n/a | | Crypto key rotation | `IRotatingEventCryptoKeyStore` | Yes | Yes | No | No | n/a | +| Distributed tracing spans | Span names are a contract | Yes | Yes | Yes | Yes | Snapshot/query spans | | Event-stream retention / pruning | No | No | No | No | No | n/a | | Provider-specific native transaction factory | No | `ISqlServerEventStoreTransactionFactory` | `IPostgresEventStoreTransactionFactory` | No | No | No | | Runtime-configured JSON payload indexes | No | Yes (event + snapshot stores, auto-create path) | Yes (GIN + expression indexes on event + snapshot stores) | No | No | Yes (container indexing policy, including composite and spatial paths) | diff --git a/src/src/AzureStorage/ITableEventStoreTelemetry.cs b/src/src/AzureStorage/ITableEventStoreTelemetry.cs index 4b8ad875..b18601f8 100644 --- a/src/src/AzureStorage/ITableEventStoreTelemetry.cs +++ b/src/src/AzureStorage/ITableEventStoreTelemetry.cs @@ -1,3 +1,4 @@ +using System.Diagnostics; using Microsoft.Extensions.Logging; using Purview.Telemetry; @@ -11,9 +12,95 @@ namespace Purview.EventSourcing.AzureStorage; /// and annotations. Each method describes a single /// event-store operation or failure for observability and diagnostics. /// +[ActivitySource] [Logger] +[Meter] public interface ITableEventStoreTelemetry { + // Activities (distributed tracing) + // + // Names and parameters match the SQL Server and PostgreSQL contracts deliberately: a dashboard or + // trace query built against one provider has to keep working when the same service moves to + // another, so span names are a compatibility contract in the same way instrument names are. + + /// + /// Starts an activity representing a get-aggregate operation. + /// + /// The id of the aggregate being retrieved. + /// The full name of the aggregate type. + /// The activity, or when tracing is not enabled. + [Activity] + Activity? GetAggregate(string aggregateId, [Baggage] string aggregateTypeFullName); + + /// + /// Starts an activity representing a get-aggregate-at-version operation. + /// + /// The id of the aggregate being retrieved. + /// The version of the aggregate being retrieved. + /// The full name of the aggregate type. + /// The activity, or when tracing is not enabled. + [Activity] + Activity? GetAggregateAtVersion(string aggregateId, long version, [Baggage] string aggregateTypeFullName); + + /// + /// Starts an activity representing a save-aggregate operation. + /// + /// The id of the aggregate being saved. + /// The full name of the aggregate type. + /// The activity, or when tracing is not enabled. + [Activity] + Activity? SaveAggregate(string aggregateId, [Baggage] string aggregateTypeFullName); + + /// + /// Starts an activity representing a delete-aggregate operation. + /// + /// The id of the aggregate being deleted. + /// The full name of the aggregate type. + /// The activity, or when tracing is not enabled. + [Activity] + Activity? DeleteAggregate(string aggregateId, [Baggage] string aggregateTypeFullName); + + /// + /// Records the number of events reconstituted when loading an aggregate. + /// + /// The activity to attach the event to. + /// The number of events applied. + /// The resulting aggregate version. + [Event] + void EventsReconstituted(Activity? activity, int eventCount, long version); + + /// + /// Records the completion of a save operation. + /// + /// The activity to attach the event to. + /// The number of events saved. + [Event] + void SaveCompleted(Activity? activity, int eventCount); + + // Metrics (counters) + + /// + /// Increments the counter tracking loaded aggregates. + /// + /// The short name of the aggregate type. + [AutoCounter] + void AggregateLoaded(string aggregateType); + + /// + /// Increments the counter tracking saved aggregates. + /// + /// The short name of the aggregate type. + [AutoCounter] + void AggregateSaved(string aggregateType); + + /// + /// Increments the counter tracking deleted aggregates. + /// + /// The short name of the aggregate type. + [AutoCounter] + void AggregateDeletedCounter(string aggregateType); + + // Logging /// /// Logs that the aggregate was retrieved from the distributed cache. /// diff --git a/src/src/AzureStorage/TableEventStore.DeleteAsync.cs b/src/src/AzureStorage/TableEventStore.DeleteAsync.cs index bf780099..a469d547 100644 --- a/src/src/AzureStorage/TableEventStore.DeleteAsync.cs +++ b/src/src/AzureStorage/TableEventStore.DeleteAsync.cs @@ -20,6 +20,8 @@ public async Task, AggregateDeleteFailure>> DeleteAsync( if (aggregate == null) throw NullAggregate(aggregate); + using var activity = _eventStoreTelemetry.DeleteAggregate(aggregate.Id(), _aggregateTypeFullName); + if (aggregate.Details.IsDeleted) { return AggregateDeleteFailure.Failure>( diff --git a/src/src/AzureStorage/TableEventStore.GetAsync.cs b/src/src/AzureStorage/TableEventStore.GetAsync.cs index 937ea026..9ac105a3 100644 --- a/src/src/AzureStorage/TableEventStore.GetAsync.cs +++ b/src/src/AzureStorage/TableEventStore.GetAsync.cs @@ -28,6 +28,7 @@ async Task> GetCoreAsync( operationContext ??= EventStoreOperationContext.DefaultContext(); + using var activity = _eventStoreTelemetry.GetAggregate(aggregateId, _aggregateTypeFullName); _eventStoreTelemetry.GetAggregateStart(aggregateId, _aggregateTypeFullName); var getStopwatch = System.Diagnostics.Stopwatch.StartNew(); try @@ -226,6 +227,15 @@ CancellationToken cancellationToken AggregateVersionData.Create(aggregate) ); + // Activity.Current rather than a parameter: the activity is started by the public operation + // and this runs inside it, so threading it through every helper would add nothing. + _eventStoreTelemetry.EventsReconstituted( + System.Diagnostics.Activity.Current, + eventCount, + aggregate.Details.CurrentVersion + ); + _eventStoreTelemetry.AggregateLoaded(aggregate.AggregateType); + aggregate.Details.SavedVersion = aggregate.Details.CurrentVersion; aggregate.Details.Etag = streamVersion.ETag.ToString(); diff --git a/src/src/AzureStorage/TableEventStore.GetAtAsync.cs b/src/src/AzureStorage/TableEventStore.GetAtAsync.cs index 28840a13..e67857af 100644 --- a/src/src/AzureStorage/TableEventStore.GetAtAsync.cs +++ b/src/src/AzureStorage/TableEventStore.GetAtAsync.cs @@ -18,6 +18,7 @@ public async Task> GetAtAsync( operationContext ??= EventStoreOperationContext.DefaultContext(); + using var activity = _eventStoreTelemetry.GetAggregateAtVersion(aggregateId, version, _aggregateTypeFullName); _eventStoreTelemetry.GetAggregateAtSpecificVersionStart(aggregateId, version, _aggregateTypeFullName); var getStopwatch = Stopwatch.StartNew(); try diff --git a/src/src/AzureStorage/TableEventStore.SaveOperation.cs b/src/src/AzureStorage/TableEventStore.SaveOperation.cs index 67c9ed19..537f6622 100644 --- a/src/src/AzureStorage/TableEventStore.SaveOperation.cs +++ b/src/src/AzureStorage/TableEventStore.SaveOperation.cs @@ -56,6 +56,7 @@ internal async Task, AggregateSaveFailure>> SaveCoreAsync( params EventRecord[] additionalEvents ) { + using var activity = store.EventStoreTelemetry.SaveAggregate(aggregate.Id(), store.AggregateTypeFullName); var saveStopwatch = System.Diagnostics.Stopwatch.StartNew(); var (saveResult, preparedAggregate, preparedOperationContext, idempotencyId, changeEvents, isNew, marker) = await PrepareSaveAsync(aggregate, operationContext, additionalEvents, cancellationToken); @@ -78,6 +79,8 @@ params EventRecord[] additionalEvents // Only a write actually appended events; a no-op or an idempotent replay appended none. if (result.IsSuccess && result.Value.Kind is SaveOutcomeKind.Written) metrics.EventsAppended(changeEvents.Length, store.AggregateTypeShortName); + store.EventStoreTelemetry.SaveCompleted(activity, changeEvents.Length); + store.EventStoreTelemetry.AggregateSaved(preparedAggregate.AggregateType); return result; } diff --git a/src/src/AzureStorage/TableEventStore.cs b/src/src/AzureStorage/TableEventStore.cs index aa678002..b0885236 100644 --- a/src/src/AzureStorage/TableEventStore.cs +++ b/src/src/AzureStorage/TableEventStore.cs @@ -62,6 +62,10 @@ public sealed partial class TableEventStore : ITableEventStore, IAsyncDisp // Exposed so the save operation tags metrics with the same value every other provider uses. internal string AggregateTypeShortName => _aggregateTypeShortName; + + internal string AggregateTypeFullName => _aggregateTypeFullName; + + internal ITableEventStoreTelemetry EventStoreTelemetry => _eventStoreTelemetry; readonly TableSaveOperation _saveOperation; static readonly ConcurrentDictionary EventTypeCache = new(StringComparer.Ordinal); diff --git a/src/src/CosmosDb/Snapshots/CosmosDbSnapshotEventStore.Query.cs b/src/src/CosmosDb/Snapshots/CosmosDbSnapshotEventStore.Query.cs index b45901ff..4b52be98 100644 --- a/src/src/CosmosDb/Snapshots/CosmosDbSnapshotEventStore.Query.cs +++ b/src/src/CosmosDb/Snapshots/CosmosDbSnapshotEventStore.Query.cs @@ -1,4 +1,4 @@ -using System.Linq.Expressions; +using System.Linq.Expressions; using System.Runtime.CompilerServices; namespace Purview.EventSourcing.CosmosDb.Snapshot; @@ -43,6 +43,8 @@ public async Task> QueryAsync( ArgumentNullException.ThrowIfNull(whereClause, nameof(whereClause)); ArgumentNullException.ThrowIfNull(request, nameof(request)); + using var activity = _telemetry.QuerySnapshots("Query", typeof(T).FullName ?? typeof(T).Name); + return await ExecuteQueryAsync(whereClause, orderByClause, request, cancellationToken); } @@ -53,6 +55,8 @@ public async Task> ListAsync( CancellationToken cancellationToken = default ) { + using var activity = _telemetry.QuerySnapshots("List", typeof(T).FullName ?? typeof(T).Name); + ArgumentNullException.ThrowIfNull(request, nameof(request)); return await ExecuteQueryAsync(null, orderByClause, request, cancellationToken); @@ -64,6 +68,8 @@ public async Task> ListAsync( CancellationToken cancellationToken = default ) { + using var activity = _telemetry.QuerySnapshots("SingleOrDefault", typeof(T).FullName ?? typeof(T).Name); + // Leave as 2 as it'll throw when expected. var query = await GetSpecificNumberAsync(whereClause, null, 2, cancellationToken: cancellationToken); return query.SingleOrDefault(); @@ -76,6 +82,8 @@ public async Task> ListAsync( CancellationToken cancellationToken = default ) { + using var activity = _telemetry.QuerySnapshots("FirstOrDefault", typeof(T).FullName ?? typeof(T).Name); + var query = await GetSpecificNumberAsync(whereClause, orderByClause, 1, cancellationToken: cancellationToken); return query.FirstOrDefault(); } diff --git a/src/src/CosmosDb/Snapshots/CosmosDbSnapshotEventStore.cs b/src/src/CosmosDb/Snapshots/CosmosDbSnapshotEventStore.cs index 90da7caf..0f85df16 100644 --- a/src/src/CosmosDb/Snapshots/CosmosDbSnapshotEventStore.cs +++ b/src/src/CosmosDb/Snapshots/CosmosDbSnapshotEventStore.cs @@ -78,6 +78,8 @@ public CosmosDbSnapshotEventStore( /// A token that can be used to cancel the operation. public async Task SnapshotAsync(T aggregate, CancellationToken cancellationToken = default) { + using var activity = _telemetry.SnapshotAggregate(aggregate.Id(), typeof(T).FullName ?? typeof(T).Name); + ArgumentNullException.ThrowIfNull(aggregate, nameof(aggregate)); var result = await _cosmosDbClient.UpsertAsync(aggregate, aggregate.Details.Id, cancellationToken); diff --git a/src/src/CosmosDb/Snapshots/ICosmosDbSnapshotEventStoreTelemetry.cs b/src/src/CosmosDb/Snapshots/ICosmosDbSnapshotEventStoreTelemetry.cs index 9921c72d..ec361af8 100644 --- a/src/src/CosmosDb/Snapshots/ICosmosDbSnapshotEventStoreTelemetry.cs +++ b/src/src/CosmosDb/Snapshots/ICosmosDbSnapshotEventStoreTelemetry.cs @@ -1,4 +1,5 @@ -using Purview.Telemetry; +using System.Diagnostics; +using Purview.Telemetry; namespace Purview.EventSourcing.CosmosDb.Snapshots; @@ -9,9 +10,35 @@ namespace Purview.EventSourcing.CosmosDb.Snapshots; /// Implementations are generated by the Purview telemetry source generator from the /// attribute on this interface. /// +[ActivitySource] +[Logger] [Meter] public interface ICosmosDbSnapshotEventStoreTelemetry { + // Activities (distributed tracing) + // + // Snapshot and query spans only. Cosmos DB persists no event stream - it delegates aggregate + // reads and writes to an inner event store, which emits the aggregate-level spans. Adding them + // here too would double-count every operation in a trace. + + /// + /// Starts an activity representing writing an aggregate snapshot. + /// + /// The id of the aggregate being snapshotted. + /// The full name of the aggregate type. + /// The activity, or when tracing is not enabled. + [Activity] + Activity? SnapshotAggregate(string aggregateId, [Baggage] string aggregateTypeFullName); + + /// + /// Starts an activity representing a snapshot query. + /// + /// The query shape, for example Query, List or Count. + /// The full name of the aggregate type. + /// The activity, or when tracing is not enabled. + [Activity] + Activity? QuerySnapshots(string operation, [Baggage] string aggregateTypeFullName); + /// /// Records that a snapshot was created for the given aggregate type. /// diff --git a/src/src/MongoDB/Events/IMongoDBEventStoreTelemetry.cs b/src/src/MongoDB/Events/IMongoDBEventStoreTelemetry.cs index 4e8ef321..3e8035bc 100644 --- a/src/src/MongoDB/Events/IMongoDBEventStoreTelemetry.cs +++ b/src/src/MongoDB/Events/IMongoDBEventStoreTelemetry.cs @@ -1,3 +1,4 @@ +using System.Diagnostics; using Purview.Telemetry; namespace Purview.EventSourcing.MongoDB.Events; @@ -10,9 +11,94 @@ namespace Purview.EventSourcing.MongoDB.Events; /// cache operations, as well as to report failures such as deserialization errors, storage commit failures /// and missing event types. /// +[ActivitySource] [Logger] +[Meter] public interface IMongoDBEventStoreTelemetry { + // Activities (distributed tracing) + // + // Names and parameters match the SQL Server and PostgreSQL contracts deliberately: a dashboard or + // trace query built against one provider has to keep working when the same service moves to + // another, so span names are a compatibility contract in the same way instrument names are. + + /// + /// Starts an activity representing a get-aggregate operation. + /// + /// The id of the aggregate being retrieved. + /// The full name of the aggregate type. + /// The activity, or when tracing is not enabled. + [Activity] + Activity? GetAggregate(string aggregateId, [Baggage] string aggregateTypeFullName); + + /// + /// Starts an activity representing a get-aggregate-at-version operation. + /// + /// The id of the aggregate being retrieved. + /// The version of the aggregate being retrieved. + /// The full name of the aggregate type. + /// The activity, or when tracing is not enabled. + [Activity] + Activity? GetAggregateAtVersion(string aggregateId, long version, [Baggage] string aggregateTypeFullName); + + /// + /// Starts an activity representing a save-aggregate operation. + /// + /// The id of the aggregate being saved. + /// The full name of the aggregate type. + /// The activity, or when tracing is not enabled. + [Activity] + Activity? SaveAggregate(string aggregateId, [Baggage] string aggregateTypeFullName); + + /// + /// Starts an activity representing a delete-aggregate operation. + /// + /// The id of the aggregate being deleted. + /// The full name of the aggregate type. + /// The activity, or when tracing is not enabled. + [Activity] + Activity? DeleteAggregate(string aggregateId, [Baggage] string aggregateTypeFullName); + + /// + /// Records the number of events reconstituted when loading an aggregate. + /// + /// The activity to attach the event to. + /// The number of events applied. + /// The resulting aggregate version. + [Event] + void EventsReconstituted(Activity? activity, int eventCount, long version); + + /// + /// Records the completion of a save operation. + /// + /// The activity to attach the event to. + /// The number of events saved. + [Event] + void SaveCompleted(Activity? activity, int eventCount); + + // Metrics (counters) + + /// + /// Increments the counter tracking loaded aggregates. + /// + /// The short name of the aggregate type. + [AutoCounter] + void AggregateLoaded(string aggregateType); + + /// + /// Increments the counter tracking saved aggregates. + /// + /// The short name of the aggregate type. + [AutoCounter] + void AggregateSaved(string aggregateType); + + /// + /// Increments the counter tracking deleted aggregates. + /// + /// The short name of the aggregate type. + [AutoCounter] + void AggregateDeletedCounter(string aggregateType); + /// /// Logs that an aggregate was retrieved from the distributed cache. /// diff --git a/src/src/MongoDB/Events/MongoDBEventStore.DeleteAsync.cs b/src/src/MongoDB/Events/MongoDBEventStore.DeleteAsync.cs index fcffa3d7..0b51d1cf 100644 --- a/src/src/MongoDB/Events/MongoDBEventStore.DeleteAsync.cs +++ b/src/src/MongoDB/Events/MongoDBEventStore.DeleteAsync.cs @@ -15,6 +15,8 @@ public async Task, AggregateDeleteFailure>> DeleteAsync( CancellationToken cancellationToken = default ) { + using var activity = _eventStoreTelemetry.DeleteAggregate(aggregate.Id(), _aggregateTypeFullName); + if (aggregate == null) throw NullAggregate(aggregate); diff --git a/src/src/MongoDB/Events/MongoDBEventStore.GetAsync.cs b/src/src/MongoDB/Events/MongoDBEventStore.GetAsync.cs index 4cffe088..a32a3fc8 100644 --- a/src/src/MongoDB/Events/MongoDBEventStore.GetAsync.cs +++ b/src/src/MongoDB/Events/MongoDBEventStore.GetAsync.cs @@ -29,6 +29,7 @@ async Task> GetCoreAsync( operationContext ??= EventStoreOperationContext.DefaultContext(); + using var activity = _eventStoreTelemetry.GetAggregate(aggregateId, _aggregateTypeFullName); _eventStoreTelemetry.GetAggregateStart(aggregateId, _aggregateTypeFullName); var getStopwatch = System.Diagnostics.Stopwatch.StartNew(); try @@ -227,6 +228,15 @@ CancellationToken cancellationToken AggregateVersionData.Create(aggregate) ); + // Activity.Current rather than a parameter: the activity is started by the public operation + // and this runs inside it. + _eventStoreTelemetry.EventsReconstituted( + System.Diagnostics.Activity.Current, + eventCount, + aggregate.Details.CurrentVersion + ); + _eventStoreTelemetry.AggregateLoaded(aggregate.AggregateType); + aggregate.Details.SavedVersion = aggregate.Details.CurrentVersion; aggregate.Details.Etag = streamVersion.Version.ToString(CultureInfo.InvariantCulture); diff --git a/src/src/MongoDB/Events/MongoDBEventStore.GetAtAsync.cs b/src/src/MongoDB/Events/MongoDBEventStore.GetAtAsync.cs index add824ae..a3d3206e 100644 --- a/src/src/MongoDB/Events/MongoDBEventStore.GetAtAsync.cs +++ b/src/src/MongoDB/Events/MongoDBEventStore.GetAtAsync.cs @@ -18,6 +18,7 @@ public async Task> GetAtAsync( operationContext ??= EventStoreOperationContext.DefaultContext(); + using var activity = _eventStoreTelemetry.GetAggregateAtVersion(aggregateId, version, _aggregateTypeFullName); _eventStoreTelemetry.GetAggregateAtSpecificVersionStart(aggregateId, version, _aggregateTypeFullName); var getStopwatch = Stopwatch.StartNew(); try diff --git a/src/src/MongoDB/Events/MongoDBEventStore.SaveAsync.cs b/src/src/MongoDB/Events/MongoDBEventStore.SaveAsync.cs index a09df1f3..d014a341 100644 --- a/src/src/MongoDB/Events/MongoDBEventStore.SaveAsync.cs +++ b/src/src/MongoDB/Events/MongoDBEventStore.SaveAsync.cs @@ -31,6 +31,8 @@ async Task, AggregateSaveFailure>> SaveCoreAsync( params EventRecord[] additionalEvents ) { + using var activity = _eventStoreTelemetry.SaveAggregate(aggregate.Id(), _aggregateTypeFullName); + var saveStopwatch = System.Diagnostics.Stopwatch.StartNew(); var preparation = await PrepareSaveAsync(aggregate, operationContext, additionalEvents, cancellationToken); var result = preparation.Terminal ?? await PersistAndNotifyAsync(preparation, cancellationToken); @@ -41,6 +43,8 @@ params EventRecord[] additionalEvents // Only a write actually appended events; a no-op or an idempotent replay appended none. if (result.IsSuccess && result.Value.Kind is SaveOutcomeKind.Written) _metrics.EventsAppended(preparation.ChangeEvents.Length, _aggregateTypeShortName); + _eventStoreTelemetry.SaveCompleted(activity, preparation.ChangeEvents.Length); + _eventStoreTelemetry.AggregateSaved(aggregate.AggregateType); return result; } From 9ab416eb80411997ace263706a5cbc4bb433cc2c Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Mon, 26 Oct 2026 14:51:35 +0000 Subject: [PATCH 25/41] feat: durable admin audit for SQL Server and PostgreSQL The audit trail died with the process - InMemoryAdminAuditLogger was the only implementation - so the record of who read which payload or triggered which rebuild was lost on restart. In a regulated deployment the audit trail is the control, which made that unusable. Entries now carry the tenant the operation acted on and a correlation identifier. Both were missing from AdminAuditEntry: "who did this" is incomplete without "to which tenant" when one administrator may be entitled to several, and an entry that cannot be tied to the events it caused answers very little. They are stamped centrally so an endpoint added later cannot omit them. Audit writes default to refusing the operation when they fail. Both answers are defensible, so the choice is an explicit option rather than an assumption, but the default is that an action nobody can prove happened is worse than an action that did not happen. My first attempt at the stamping wired it by decorating whatever was registered at the time, which broke both ways and took 49 unit tests with it: called before the logger there was nothing to decorate, and a durable logger registered afterwards replaced the decorator outright, losing the stamping silently. A keyed sink registration removes the ordering question entirely. The decorator also resolves the tenant and correlation services leniently - an Admin-only host need not have registered the event store, and audit stamping must not be what stops it starting. Append-only is enforced by the absence of an update or delete path; the framework cannot grant database permissions, so that is documented as a deployment control. A PreviousHash column is reserved for hash chaining. No read side, no Azure or MongoDB logger, and no audit retention yet. --- docs/wiki/Admin-Audit-Durability-Design.md | 11 +- docs/wiki/Guarantees-and-Limitations.md | 27 +++ docs/wiki/Provider-Feature-Matrix.md | 1 + .../AdminAuditServiceCollectionExtensions.cs | 46 ++++ .../ContextStampingAdminAuditLogger.cs | 47 ++++ .../HostApplicationBuilderExtensions.cs | 6 + .../Models/AdminAuditEntry.cs | 22 +- .../Models/AdminAuditFailureMode.cs | 22 ++ .../Services/AdminAuditKeys.cs | 21 ++ .../HostApplicationBuilderExtensions.cs | 39 ++++ .../PostgresAdminAuditLogger.cs | 198 +++++++++++++++++ .../PostgresAdminAuditLoggerOptions.cs | 53 +++++ .../ServiceCollectionExtensions.cs | 6 +- .../HostApplicationBuilderExtensions.cs | 38 ++++ .../SqlServerAdminAuditLogger.cs | 201 ++++++++++++++++++ .../SqlServerAdminAuditLoggerOptions.cs | 53 +++++ .../Api/AdminOperationalEndpointsTests.cs | 6 +- .../ContextStampingAdminAuditLoggerTests.cs | 153 +++++++++++++ .../SqlServerAdminAuditLoggerTests.cs | 158 ++++++++++++++ .../SqlServer.IntegrationTests.csproj | 3 +- 20 files changed, 1103 insertions(+), 8 deletions(-) create mode 100644 src/src/Admin.API/Auditing/AdminAuditServiceCollectionExtensions.cs create mode 100644 src/src/Admin.API/Auditing/ContextStampingAdminAuditLogger.cs create mode 100644 src/src/Admin.Abstractions/Models/AdminAuditFailureMode.cs create mode 100644 src/src/Admin.Abstractions/Services/AdminAuditKeys.cs create mode 100644 src/src/Admin.Postgres/PostgresAdminAuditLogger.cs create mode 100644 src/src/Admin.Postgres/PostgresAdminAuditLoggerOptions.cs create mode 100644 src/src/Admin.SqlServer/SqlServerAdminAuditLogger.cs create mode 100644 src/src/Admin.SqlServer/SqlServerAdminAuditLoggerOptions.cs create mode 100644 src/tests/Admin.UnitTests/Auditing/ContextStampingAdminAuditLoggerTests.cs create mode 100644 src/tests/SqlServer.IntegrationTests/Auditing/SqlServerAdminAuditLoggerTests.cs diff --git a/docs/wiki/Admin-Audit-Durability-Design.md b/docs/wiki/Admin-Audit-Durability-Design.md index 4e83298d..dd245b9d 100644 --- a/docs/wiki/Admin-Audit-Durability-Design.md +++ b/docs/wiki/Admin-Audit-Durability-Design.md @@ -1,8 +1,15 @@ # Durable Admin Audit — Design -> **Status: proposal. Nothing on this page is implemented.** +> **Status: partly implemented.** > -> `InMemoryAdminAuditLogger` is the only `IAdminAuditLogger` that ships. +> Phase 1 (tenant and correlation on the entry, stamped centrally) and Phase 2 (SQL Server and +> PostgreSQL durable loggers with the failure-mode option) have shipped — see +> [Guarantees and Limitations](Guarantees-and-Limitations.md#admin-audit). **Phases 3 to 5 remain +> proposals**: there is still no read side, no Azure Storage or MongoDB logger, and no retention. +> +> One design change against the plan below: the stamping decorator is wired through a keyed +> registration (`AdminAuditKeys.Sink`) rather than by decorating whatever happens to be registered. +> Decoration depended on the order an application calls the helpers in, and broke both ways. ## The problem diff --git a/docs/wiki/Guarantees-and-Limitations.md b/docs/wiki/Guarantees-and-Limitations.md index 2b0a48e0..a4e3260e 100644 --- a/docs/wiki/Guarantees-and-Limitations.md +++ b/docs/wiki/Guarantees-and-Limitations.md @@ -317,6 +317,33 @@ preserved metadata, query support, idempotency, concurrency, and operational lim registered stores. The [Provider Feature Matrix](Provider-Feature-Matrix.md) summarizes the same facts for package selection. +## Admin audit + +Every privileged Admin operation is recorded as an `AdminAuditEntry`. Entries carry the tenant the +operation **acted on** and a correlation identifier, both stamped centrally rather than at each call +site, so an endpoint added later cannot omit them. + +| Store | Registration | Durable | +| --- | --- | --- | +| In-memory | the default | **No** - entries die with the process | +| SQL Server | `AddPurviewEventSourcingAdminSqlServerAudit()` | Yes | +| PostgreSQL | `AddPurviewEventSourcingAdminPostgresAudit()` | Yes | +| Azure Storage, MongoDB | Not provided | - | + +**Audit writes default to refusing the operation when they fail** (`AdminAuditFailureMode.Fail`): an +action nobody can prove happened is worse than an action that did not happen. Set the failure mode to +`Continue` where availability matters more; the failure is then logged and the operation proceeds +unaudited. + +The durable tables are append-only by contract - there is no update or delete path - but the framework +cannot grant or revoke database permissions. A deployment that needs tamper-evidence should also limit +the application principal to `INSERT` and `SELECT` on the audit table. A `PreviousHash` column is +reserved so hash chaining can be added later without a migration. + +**There is no read side.** `IAdminAuditLogger` writes only, so the trail is queried through the +database rather than the Admin API. Audit retention is also not implemented - entries accumulate +indefinitely. See [Durable Admin Audit](Admin-Audit-Durability-Design.md). + ## Admin security, metadata/payload separation, and deny-by-default - Admin endpoints are denied by default and authorized per feature diff --git a/docs/wiki/Provider-Feature-Matrix.md b/docs/wiki/Provider-Feature-Matrix.md index a83e4e16..7f92d97b 100644 --- a/docs/wiki/Provider-Feature-Matrix.md +++ b/docs/wiki/Provider-Feature-Matrix.md @@ -21,6 +21,7 @@ per-registration values. | Durable crypto-shredding key store | In-memory only (refused outside Development) | `AddSqlServerEventCryptoShredding()` | `AddPostgresEventCryptoShredding()` | `AddAzureStorageEventCryptoShredding()` | `AddMongoDBEventCryptoShredding()` | n/a | | Crypto key rotation | `IRotatingEventCryptoKeyStore` | Yes | Yes | No | No | n/a | | Distributed tracing spans | Span names are a contract | Yes | Yes | Yes | Yes | Snapshot/query spans | +| Durable admin audit log | Contract + in-memory default | `AddPurviewEventSourcingAdminSqlServerAudit()` | `AddPurviewEventSourcingAdminPostgresAudit()` | Not provided | Not provided | n/a | | Event-stream retention / pruning | No | No | No | No | No | n/a | | Provider-specific native transaction factory | No | `ISqlServerEventStoreTransactionFactory` | `IPostgresEventStoreTransactionFactory` | No | No | No | | Runtime-configured JSON payload indexes | No | Yes (event + snapshot stores, auto-create path) | Yes (GIN + expression indexes on event + snapshot stores) | No | No | Yes (container indexing policy, including composite and spatial paths) | diff --git a/src/src/Admin.API/Auditing/AdminAuditServiceCollectionExtensions.cs b/src/src/Admin.API/Auditing/AdminAuditServiceCollectionExtensions.cs new file mode 100644 index 00000000..85f217ce --- /dev/null +++ b/src/src/Admin.API/Auditing/AdminAuditServiceCollectionExtensions.cs @@ -0,0 +1,46 @@ +using System.ComponentModel; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.DependencyInjection.Extensions; +using Purview.EventSourcing.Admin.Security; +using Purview.EventSourcing.Admin.Services; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.Admin.API.Auditing; + +/// +/// Wires the audit logger so every entry carries its tenant and correlation identifier. +/// +[EditorBrowsable(EditorBrowsableState.Never)] +public static class AdminAuditServiceCollectionExtensions +{ + /// + /// Registers as the , + /// in front of whichever recording logger is registered under + /// . + /// + /// The service collection. + /// The for chaining. + /// + /// Order-independent by design. An earlier version decorated whatever was registered at the time, + /// which broke both ways: called before the logger there was nothing to decorate, and a durable + /// logger registered afterwards replaced the decorator entirely and lost the stamping silently. + /// The sink key removes the question. + /// + public static IServiceCollection AddAdminAuditContextStamping(this IServiceCollection services) + { + ArgumentNullException.ThrowIfNull(services); + + // The in-memory sink is the default only if nothing else claimed the key. + services.TryAddKeyedSingleton(AdminAuditKeys.Sink); + + services.TryAddSingleton(provider => new ContextStampingAdminAuditLogger( + provider.GetRequiredKeyedService(AdminAuditKeys.Sink), + // Resolved leniently: an Admin-only host need not have registered the event-store + // services, and audit stamping must not be the thing that stops it starting. + provider.GetService() ?? new SystemCurrentTenant(), + provider.GetService() + )); + + return services; + } +} diff --git a/src/src/Admin.API/Auditing/ContextStampingAdminAuditLogger.cs b/src/src/Admin.API/Auditing/ContextStampingAdminAuditLogger.cs new file mode 100644 index 00000000..557296cc --- /dev/null +++ b/src/src/Admin.API/Auditing/ContextStampingAdminAuditLogger.cs @@ -0,0 +1,47 @@ +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Services; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.Admin.API.Auditing; + +/// +/// Fills in the tenant and correlation identifier on an audit entry before passing it on. +/// +/// +/// +/// Stamped centrally rather than at each call site, for the same reason a tenant filter belongs in +/// one place: an endpoint added later cannot forget it. An entry that already carries either value +/// is left alone, so a caller that knows better still wins. +/// +/// +/// The tenant comes from the scope establishes for +/// the request, so it records the tenant the operation acted on - the question an +/// investigation asks - rather than every tenant the administrator happens to be entitled to. +/// +/// +/// The logger that records the entry. +/// The tenant scope the request is running under. +/// The ambient correlation identifier. +public sealed class ContextStampingAdminAuditLogger( + IAdminAuditLogger inner, + ICurrentTenant currentTenant, + IEventStoreCorrelationIdProvider? correlationIdProvider +) : IAdminAuditLogger +{ + /// + public Task LogAsync(AdminAuditEntry entry, CancellationToken cancellationToken) + { + ArgumentNullException.ThrowIfNull(entry); + + var scope = currentTenant.Current; + + return inner.LogAsync( + entry with + { + TenantId = entry.TenantId ?? (scope.IsSystem ? null : scope.TenantId), + CorrelationId = entry.CorrelationId ?? correlationIdProvider?.GetCorrelationId(), + }, + cancellationToken + ); + } +} diff --git a/src/src/Admin.API/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs b/src/src/Admin.API/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs index 812d91d6..0593d7eb 100644 --- a/src/src/Admin.API/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs +++ b/src/src/Admin.API/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs @@ -3,6 +3,7 @@ using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Options; using Microsoft.OpenApi; +using Purview.EventSourcing.Admin.API.Auditing; using Purview.EventSourcing.Admin.API.Contracts; using ZodSharp.AspNetCore; @@ -36,6 +37,11 @@ public TBuilder AddPurviewEventSourcingAdminAPI(Action? conf // request contracts and options so endpoint filters and option validation can resolve them by type. builder.Services.AddZodSharp(options => options.ScanAssemblies.Add(typeof(EventRangeRequest).Assembly)); + // Stamps the tenant and correlation identifier onto every audit entry. Added here, after + // the application has registered whichever logger it wants, so a durable provider logger + // is decorated just as the in-memory default is. + builder.Services.AddAdminAuditContextStamping(); + return builder; } diff --git a/src/src/Admin.Abstractions/Models/AdminAuditEntry.cs b/src/src/Admin.Abstractions/Models/AdminAuditEntry.cs index c5a928e0..4021749c 100644 --- a/src/src/Admin.Abstractions/Models/AdminAuditEntry.cs +++ b/src/src/Admin.Abstractions/Models/AdminAuditEntry.cs @@ -18,4 +18,24 @@ public sealed record AdminAuditEntry( string? Target, bool Succeeded, string? Details -); +) +{ + /// + /// The tenant the operation acted on, or in a single-tenant deployment. + /// + /// + /// "Who did this" is incomplete without "to which tenant" - the same administrator may be + /// entitled to several. Stamped centrally from the request's tenant scope rather than at each + /// call site, so an endpoint cannot forget it. + /// + public string? TenantId { get; init; } + + /// + /// Correlates the entry with the request and with any events the operation produced. + /// + /// + /// Without it an audit entry and the events it caused cannot be tied together after the fact, + /// which is most of what an investigation needs. + /// + public string? CorrelationId { get; init; } +} diff --git a/src/src/Admin.Abstractions/Models/AdminAuditFailureMode.cs b/src/src/Admin.Abstractions/Models/AdminAuditFailureMode.cs new file mode 100644 index 00000000..d3f6eacc --- /dev/null +++ b/src/src/Admin.Abstractions/Models/AdminAuditFailureMode.cs @@ -0,0 +1,22 @@ +namespace Purview.EventSourcing.Admin.Models; + +/// +/// What happens when an audit entry cannot be written. +/// +/// +/// Both answers are defensible and the choice belongs to the deployment, so it is explicit rather +/// than assumed. In a regulated deployment the audit trail is the control, and an operation +/// nobody can prove happened is worse than an operation that did not happen. +/// +public enum AdminAuditFailureMode +{ + /// + /// The operation proceeds and the audit failure is logged. Availability over evidence. + /// + Continue = 0, + + /// + /// The operation is refused. Evidence over availability. + /// + Fail = 1, +} diff --git a/src/src/Admin.Abstractions/Services/AdminAuditKeys.cs b/src/src/Admin.Abstractions/Services/AdminAuditKeys.cs new file mode 100644 index 00000000..62ff4078 --- /dev/null +++ b/src/src/Admin.Abstractions/Services/AdminAuditKeys.cs @@ -0,0 +1,21 @@ +namespace Purview.EventSourcing.Admin.Services; + +/// +/// The dependency-injection keys used to wire the audit logger. +/// +/// +/// The logger that actually records entries is registered under , and the +/// unkeyed is a decorator that stamps the tenant and correlation +/// identifier onto every entry before passing it on. +/// +/// Keyed rather than decorating whatever happens to be registered, because that depends on the +/// order an application calls the registration helpers in: register the Admin API before the +/// durable logger and the decoration is missed, register it after and there is nothing to decorate +/// yet. A key removes the ordering question entirely. +/// +/// +public static class AdminAuditKeys +{ + /// The key the recording logger is registered under. + public const string Sink = "purview-admin-audit-sink"; +} diff --git a/src/src/Admin.Postgres/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs b/src/src/Admin.Postgres/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs index a0b4fede..c66323ec 100644 --- a/src/src/Admin.Postgres/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs +++ b/src/src/Admin.Postgres/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs @@ -1,4 +1,7 @@ +using Microsoft.Extensions.Configuration; +using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.DependencyInjection.Extensions; +using Purview.EventSourcing.Admin.Postgres; using Purview.EventSourcing.Admin.Services; namespace Microsoft.Extensions.Hosting; @@ -22,5 +25,41 @@ public TBuilder AddPurviewEventSourcingAdminPostgres() return builder; } + + /// + /// Replaces the in-memory audit logger with a durable PostgreSQL one. + /// + /// Optional configuration. + /// The configured builder, allowing further chaining. + /// + /// + /// The default audit logger keeps entries in memory, so the record of who read which payload or + /// triggered which rebuild dies with the process. In a regulated deployment the audit trail is + /// the control, which makes that unusable. + /// + /// + /// Audit writes default to AdminAuditFailureMode.Fail: if the entry cannot be written the + /// operation is refused, because an action nobody can prove happened is worse than an action + /// that did not happen. Set the failure mode to Continue where availability matters more. + /// + /// + public TBuilder AddPurviewEventSourcingAdminPostgresAudit( + Action? configure = null + ) + { + builder.Services.AddKeyedSingleton(AdminAuditKeys.Sink); + + builder + .Services.AddOptions() + .Configure( + (options, configuration) => + { + configuration.GetSection(PostgresAdminAuditLoggerOptions.PostgresAudit).Bind(options); + configure?.Invoke(options); + } + ); + + return builder; + } } } diff --git a/src/src/Admin.Postgres/PostgresAdminAuditLogger.cs b/src/src/Admin.Postgres/PostgresAdminAuditLogger.cs new file mode 100644 index 00000000..61528c82 --- /dev/null +++ b/src/src/Admin.Postgres/PostgresAdminAuditLogger.cs @@ -0,0 +1,198 @@ +using System.Text.RegularExpressions; +using Microsoft.Extensions.Logging; +using Microsoft.Extensions.Options; +using Npgsql; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Services; +using Purview.EventSourcing.Postgres.Events; + +namespace Purview.EventSourcing.Admin.Postgres; + +// SQL strings are built from validated identifiers at construction time, not from user input. +#pragma warning disable CA2100 + +/// +/// A durable backed by an append-only PostgreSQL table. +/// +/// +/// +/// In a regulated deployment the audit trail is the control, so losing it with the process - which +/// is what the in-memory logger does - is not an option. This writes every privileged Admin +/// operation to a table that survives a restart. +/// +/// +/// Append-only is enforced by what this type does not offer: there is no update and +/// no delete. The framework cannot grant or revoke database permissions, so a deployment that needs +/// tamper-evidence should also give the application principal INSERT and SELECT on +/// this table and nothing more. A PreviousHash column is reserved so hash chaining can be +/// added later without a migration. +/// +/// +public sealed partial class PostgresAdminAuditLogger : IAdminAuditLogger, IDisposable +{ + [GeneratedRegex("^[\\w\\-.]+$", RegexOptions.Compiled)] + private static partial Regex ValidIdentifier(); + + readonly IOptions _options; + readonly ILogger _logger; + readonly string _connectionString; + readonly string _schema; + readonly string _table; + readonly SemaphoreSlim _schemaLock = new(1, 1); + bool _schemaEnsured; + + /// Creates the logger. + /// The audit options. + /// The event-store options, used for any value not overridden. + /// Used to report an audit write failure under the Continue failure mode. + public PostgresAdminAuditLogger( + IOptions auditOptions, + IOptions eventStoreOptions, + ILogger logger + ) + { + ArgumentNullException.ThrowIfNull(auditOptions); + ArgumentNullException.ThrowIfNull(eventStoreOptions); + + _options = auditOptions; + _logger = logger; + _connectionString = ResolveConnectionString(auditOptions.Value, eventStoreOptions.Value); + _schema = QuoteIdentifier(auditOptions.Value.SchemaName); + _table = QuoteIdentifier(auditOptions.Value.TableName); + } + + /// + public async Task LogAsync(AdminAuditEntry entry, CancellationToken cancellationToken) + { + ArgumentNullException.ThrowIfNull(entry); + + try + { + await EnsureSchemaAsync(cancellationToken); + + await using NpgsqlConnection connection = new(_connectionString); + await connection.OpenAsync(cancellationToken); + + await using NpgsqlCommand command = new( + $""" + INSERT INTO {_schema}.{_table} + ("TimestampUtc", "Feature", "Action", "Principal", "TenantId", "Target", + "Succeeded", "Details", "CorrelationId") + VALUES (@timestamp, @feature, @action, @principal, @tenantId, @target, + @succeeded, @details, @correlationId); + """, + connection + ); + command.Parameters.AddWithValue("@timestamp", entry.TimestampUtc); + command.Parameters.AddWithValue("@feature", entry.Feature.ToString()); + command.Parameters.AddWithValue("@action", entry.Action); + command.Parameters.AddWithValue("@principal", (object?)entry.Principal ?? DBNull.Value); + command.Parameters.AddWithValue("@tenantId", (object?)entry.TenantId ?? DBNull.Value); + command.Parameters.AddWithValue("@target", (object?)entry.Target ?? DBNull.Value); + command.Parameters.AddWithValue("@succeeded", entry.Succeeded); + command.Parameters.AddWithValue("@details", (object?)entry.Details ?? DBNull.Value); + command.Parameters.AddWithValue("@correlationId", (object?)entry.CorrelationId ?? DBNull.Value); + + await command.ExecuteNonQueryAsync(cancellationToken); + } + catch (Exception ex) + when (_options.Value.FailureMode == AdminAuditFailureMode.Continue && ex is not OperationCanceledException) + { + // Continue was chosen deliberately: the operation proceeds unaudited, and the gap is + // reported here rather than swallowed entirely. + LogAuditWriteFailed(_logger, entry.Feature.ToString(), entry.Action, ex); + } + } + + [LoggerMessage( + EventId = 1, + Level = LogLevel.Error, + Message = "Failed to write an admin audit entry for {Feature}/{Action}. The operation proceeded unaudited because the configured failure mode is Continue." + )] + static partial void LogAuditWriteFailed(ILogger logger, string feature, string action, Exception exception); + + async Task EnsureSchemaAsync(CancellationToken cancellationToken) + { + if (_schemaEnsured) + return; + + if (_options.Value.AutoCreateTable) + { + await _schemaLock.WaitAsync(cancellationToken); + try + { + if (_schemaEnsured) + return; + + await EnsureSchemaCoreAsync(cancellationToken); + } + finally + { + _schemaLock.Release(); + } + } + + _schemaEnsured = true; + } + + async Task EnsureSchemaCoreAsync(CancellationToken cancellationToken) + { + await using NpgsqlConnection connection = new(_connectionString); + await connection.OpenAsync(cancellationToken); + + // CREATE TABLE IF NOT EXISTS is not safe to run concurrently: PostgreSQL still races on the + // table's implicit row type and raises 23505. + // + // "PreviousHash" is reserved, not used: hash chaining can be added later without a migration. + await using NpgsqlCommand command = new( + $""" + CREATE TABLE IF NOT EXISTS {_schema}.{_table} ( + "Id" BIGSERIAL PRIMARY KEY, + "TimestampUtc" TIMESTAMPTZ NOT NULL, + "Feature" VARCHAR(128) NOT NULL, + "Action" VARCHAR(128) NOT NULL, + "Principal" VARCHAR(256) NULL, + "TenantId" VARCHAR(256) NULL, + "Target" VARCHAR(512) NULL, + "Succeeded" BOOLEAN NOT NULL, + "Details" TEXT NULL, + "CorrelationId" VARCHAR(128) NULL, + "PreviousHash" BYTEA NULL + ); + """, + connection + ); + + try + { + await command.ExecuteNonQueryAsync(cancellationToken); + } + catch (PostgresException ex) when (ex.SqlState is "23505" or "42P07") + { + // Another writer created it first, which is the outcome we wanted anyway. + } + } + + /// + public void Dispose() => _schemaLock.Dispose(); + + static string ResolveConnectionString( + PostgresAdminAuditLoggerOptions auditOptions, + PostgresEventStoreOptions eventStoreOptions + ) => + auditOptions.ConnectionString + ?? eventStoreOptions.ConnectionString + ?? throw new InvalidOperationException( + "PostgresAdminAuditLogger requires a connection string. Configure 'Admin:Postgres:Audit:ConnectionString' or 'EventStore:Postgres:ConnectionString'." + ); + + static string QuoteIdentifier(string identifier) + { + if (!ValidIdentifier().IsMatch(identifier)) + throw new InvalidOperationException( + $"The admin audit table identifier '{identifier}' is invalid. Identifiers may only contain letters, digits, underscores, dots, and hyphens." + ); + + return $"\"{identifier}\""; + } +} diff --git a/src/src/Admin.Postgres/PostgresAdminAuditLoggerOptions.cs b/src/src/Admin.Postgres/PostgresAdminAuditLoggerOptions.cs new file mode 100644 index 00000000..460383fb --- /dev/null +++ b/src/src/Admin.Postgres/PostgresAdminAuditLoggerOptions.cs @@ -0,0 +1,53 @@ +using System.ComponentModel.DataAnnotations; +using Purview.EventSourcing.Admin.Models; + +namespace Purview.EventSourcing.Admin.Postgres; + +/// +/// Options that configure the PostgreSQL admin audit logger. +/// +/// +/// Bound from the Admin:Postgres:Audit configuration section. When +/// is not supplied, the event-store connection string is used. +/// +public sealed class PostgresAdminAuditLoggerOptions +{ + /// The configuration section name used to bind these options. + public const string PostgresAudit = "Admin:Postgres:Audit"; + + /// The default table name used to persist audit entries. + public const string DefaultTableName = "AdminAuditLog"; + + /// + /// The connection string used to access the PostgreSQL database. When null, the event-store + /// connection string is used. + /// + /// + /// A separate database is worth considering: an audit trail usually wants different retention, + /// different backup policy, and narrower write permissions than the data it describes. + /// + public string? ConnectionString { get; set; } + + /// The schema that owns the audit table. + [Required(AllowEmptyStrings = false)] + [RegularExpression(@"^[\w\-.]+$")] + public string SchemaName { get; set; } = "public"; + + /// The name of the table that stores audit entries. + [Required(AllowEmptyStrings = false)] + [RegularExpression(@"^[\w\-.]+$")] + public string TableName { get; set; } = DefaultTableName; + + /// When true, the audit table is created if it does not exist. + public bool AutoCreateTable { get; set; } = true; + + /// + /// What happens when an audit entry cannot be written. + /// + /// + /// Defaults to . The Admin portal exposes event payloads + /// and mutating operations, so an action nobody can prove happened is the outcome worth avoiding. + /// Set to where availability matters more. + /// + public AdminAuditFailureMode FailureMode { get; set; } = AdminAuditFailureMode.Fail; +} diff --git a/src/src/Admin.Security/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs b/src/src/Admin.Security/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs index 48a9f7a3..f588d19a 100644 --- a/src/src/Admin.Security/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs +++ b/src/src/Admin.Security/Extensions/Microsoft/Extensions/DependencyInjection/ServiceCollectionExtensions.cs @@ -30,8 +30,10 @@ public IServiceCollection AddPurviewEventSourcingAdminSecurity( services.AddScoped(); services.AddScoped(); - // Default in-memory audit logger; applications may replace it with a durable implementation. - services.TryAddSingleton(); + // Registered under the sink key: the unkeyed IAdminAuditLogger is a decorator that stamps + // the tenant and correlation identifier, so a durable logger replaces this sink rather + // than the decorator in front of it. Applications may replace it with a durable one. + services.TryAddKeyedSingleton(AdminAuditKeys.Sink); // TryAdd: a host entitling administrators differently registers its own resolver first. services.TryAddSingleton(new ClaimsAdminTenantResolver()); diff --git a/src/src/Admin.SqlServer/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs b/src/src/Admin.SqlServer/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs index 3fa6a56c..f45b478a 100644 --- a/src/src/Admin.SqlServer/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs +++ b/src/src/Admin.SqlServer/Extensions/Microsoft/Extensions/Hosting/HostApplicationBuilderExtensions.cs @@ -1,3 +1,5 @@ +using Microsoft.Extensions.Configuration; +using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.DependencyInjection.Extensions; using Purview.EventSourcing.Admin.Services; using Purview.EventSourcing.Admin.SQLServer; @@ -23,5 +25,41 @@ public TBuilder AddPurviewEventSourcingAdminSqlServer() return builder; } + + /// + /// Replaces the in-memory audit logger with a durable SQL Server one. + /// + /// Optional configuration. + /// The configured builder, allowing further chaining. + /// + /// + /// The default audit logger keeps entries in memory, so the record of who read which payload or + /// triggered which rebuild dies with the process. In a regulated deployment the audit trail is + /// the control, which makes that unusable. + /// + /// + /// Audit writes default to AdminAuditFailureMode.Fail: if the entry cannot be written the + /// operation is refused, because an action nobody can prove happened is worse than an action + /// that did not happen. Set the failure mode to Continue where availability matters more. + /// + /// + public TBuilder AddPurviewEventSourcingAdminSqlServerAudit( + Action? configure = null + ) + { + builder.Services.AddKeyedSingleton(AdminAuditKeys.Sink); + + builder + .Services.AddOptions() + .Configure( + (options, configuration) => + { + configuration.GetSection(SqlServerAdminAuditLoggerOptions.SqlServerAudit).Bind(options); + configure?.Invoke(options); + } + ); + + return builder; + } } } diff --git a/src/src/Admin.SqlServer/SqlServerAdminAuditLogger.cs b/src/src/Admin.SqlServer/SqlServerAdminAuditLogger.cs new file mode 100644 index 00000000..1342228f --- /dev/null +++ b/src/src/Admin.SqlServer/SqlServerAdminAuditLogger.cs @@ -0,0 +1,201 @@ +using System.Text.RegularExpressions; +using Microsoft.Data.SqlClient; +using Microsoft.Extensions.Logging; +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Services; +using Purview.EventSourcing.SqlServer.Events; + +namespace Purview.EventSourcing.Admin.SqlServer; + +// SQL strings are built from validated identifiers at construction time, not from user input. +#pragma warning disable CA2100 + +/// +/// A durable backed by an append-only SQL Server table. +/// +/// +/// +/// In a regulated deployment the audit trail is the control, so losing it with the process - which +/// is what the in-memory logger does - is not an option. This writes every privileged Admin +/// operation to a table that survives a restart. +/// +/// +/// Append-only is enforced by what this type does not offer: there is no update and +/// no delete. The framework cannot grant or revoke database permissions, so a deployment that needs +/// tamper-evidence should also give the application principal INSERT and SELECT on +/// this table and nothing more. A PreviousHash column is reserved so hash chaining can be +/// added later without a migration. +/// +/// +public sealed partial class SqlServerAdminAuditLogger : IAdminAuditLogger, IDisposable +{ + [GeneratedRegex("^[\\w\\-.]+$", RegexOptions.Compiled)] + private static partial Regex ValidIdentifier(); + + readonly IOptions _options; + readonly ILogger _logger; + readonly string _connectionString; + readonly string _schema; + readonly string _table; + readonly SemaphoreSlim _schemaLock = new(1, 1); + bool _schemaEnsured; + + /// Creates the logger. + /// The audit options. + /// The event-store options, used for any value not overridden. + /// Used to report an audit write failure under the Continue failure mode. + public SqlServerAdminAuditLogger( + IOptions auditOptions, + IOptions eventStoreOptions, + ILogger logger + ) + { + ArgumentNullException.ThrowIfNull(auditOptions); + ArgumentNullException.ThrowIfNull(eventStoreOptions); + + _options = auditOptions; + _logger = logger; + _connectionString = ResolveConnectionString(auditOptions.Value, eventStoreOptions.Value); + _schema = QuoteIdentifier(auditOptions.Value.SchemaName); + _table = QuoteIdentifier(auditOptions.Value.TableName); + } + + /// + public async Task LogAsync(AdminAuditEntry entry, CancellationToken cancellationToken) + { + ArgumentNullException.ThrowIfNull(entry); + + try + { + await EnsureSchemaAsync(cancellationToken); + + await using SqlConnection connection = new(_connectionString); + await connection.OpenAsync(cancellationToken); + + await using SqlCommand command = new( + $""" + INSERT INTO {_schema}.{_table} + ([TimestampUtc], [Feature], [Action], [Principal], [TenantId], [Target], + [Succeeded], [Details], [CorrelationId]) + VALUES (@timestamp, @feature, @action, @principal, @tenantId, @target, + @succeeded, @details, @correlationId); + """, + connection + ); + command.Parameters.AddWithValue("@timestamp", entry.TimestampUtc); + command.Parameters.AddWithValue("@feature", entry.Feature.ToString()); + command.Parameters.AddWithValue("@action", entry.Action); + command.Parameters.AddWithValue("@principal", (object?)entry.Principal ?? DBNull.Value); + command.Parameters.AddWithValue("@tenantId", (object?)entry.TenantId ?? DBNull.Value); + command.Parameters.AddWithValue("@target", (object?)entry.Target ?? DBNull.Value); + command.Parameters.AddWithValue("@succeeded", entry.Succeeded); + command.Parameters.AddWithValue("@details", (object?)entry.Details ?? DBNull.Value); + command.Parameters.AddWithValue("@correlationId", (object?)entry.CorrelationId ?? DBNull.Value); + + await command.ExecuteNonQueryAsync(cancellationToken); + } + catch (Exception ex) + when (_options.Value.FailureMode == AdminAuditFailureMode.Continue && ex is not OperationCanceledException) + { + // Continue was chosen deliberately: the operation proceeds unaudited, and the gap is + // reported here rather than swallowed entirely. + LogAuditWriteFailed(_logger, entry.Feature.ToString(), entry.Action, ex); + } + } + + [LoggerMessage( + EventId = 1, + Level = LogLevel.Error, + Message = "Failed to write an admin audit entry for {Feature}/{Action}. The operation proceeded unaudited because the configured failure mode is Continue." + )] + static partial void LogAuditWriteFailed(ILogger logger, string feature, string action, Exception exception); + + async Task EnsureSchemaAsync(CancellationToken cancellationToken) + { + if (_schemaEnsured) + return; + + if (_options.Value.AutoCreateTable) + { + await _schemaLock.WaitAsync(cancellationToken); + try + { + if (_schemaEnsured) + return; + + await EnsureSchemaCoreAsync(cancellationToken); + } + finally + { + _schemaLock.Release(); + } + } + + _schemaEnsured = true; + } + + async Task EnsureSchemaCoreAsync(CancellationToken cancellationToken) + { + await using SqlConnection connection = new(_connectionString); + await connection.OpenAsync(cancellationToken); + + var indexName = QuoteIdentifier($"IX_{_options.Value.TableName}_Timestamp"); + + // 2714 is "object already exists": another process won the race between the OBJECT_ID check + // and the CREATE, which is the outcome we wanted anyway. + // + // [PreviousHash] is reserved, not used: hash chaining can be added later without a migration. + await using SqlCommand command = new( + $""" + BEGIN TRY + IF OBJECT_ID(N'{_schema}.{_table}', N'U') IS NULL + BEGIN + CREATE TABLE {_schema}.{_table} ( + [Id] BIGINT IDENTITY(1,1) NOT NULL PRIMARY KEY, + [TimestampUtc] DATETIMEOFFSET NOT NULL, + [Feature] NVARCHAR(128) NOT NULL, + [Action] NVARCHAR(128) NOT NULL, + [Principal] NVARCHAR(256) NULL, + [TenantId] NVARCHAR(256) NULL, + [Target] NVARCHAR(512) NULL, + [Succeeded] BIT NOT NULL, + [Details] NVARCHAR(MAX) NULL, + [CorrelationId] NVARCHAR(128) NULL, + [PreviousHash] VARBINARY(32) NULL + ); + CREATE INDEX {indexName} ON {_schema}.{_table} ([TenantId], [TimestampUtc] DESC); + END + END TRY + BEGIN CATCH + IF ERROR_NUMBER() <> 2714 THROW; + END CATCH + """, + connection + ); + await command.ExecuteNonQueryAsync(cancellationToken); + } + + /// + public void Dispose() => _schemaLock.Dispose(); + + static string ResolveConnectionString( + SqlServerAdminAuditLoggerOptions auditOptions, + SqlServerEventStoreOptions eventStoreOptions + ) => + auditOptions.ConnectionString + ?? eventStoreOptions.ConnectionString + ?? throw new InvalidOperationException( + "SqlServerAdminAuditLogger requires a connection string. Configure 'Admin:SqlServer:Audit:ConnectionString' or 'EventStore:SqlServer:ConnectionString'." + ); + + static string QuoteIdentifier(string identifier) + { + if (!ValidIdentifier().IsMatch(identifier)) + throw new InvalidOperationException( + $"The admin audit table identifier '{identifier}' is invalid. Identifiers may only contain letters, digits, underscores, dots, and hyphens." + ); + + return $"[{identifier}]"; + } +} diff --git a/src/src/Admin.SqlServer/SqlServerAdminAuditLoggerOptions.cs b/src/src/Admin.SqlServer/SqlServerAdminAuditLoggerOptions.cs new file mode 100644 index 00000000..b0b5f609 --- /dev/null +++ b/src/src/Admin.SqlServer/SqlServerAdminAuditLoggerOptions.cs @@ -0,0 +1,53 @@ +using System.ComponentModel.DataAnnotations; +using Purview.EventSourcing.Admin.Models; + +namespace Purview.EventSourcing.Admin.SqlServer; + +/// +/// Options that configure the SQL Server admin audit logger. +/// +/// +/// Bound from the Admin:SqlServer:Audit configuration section. When +/// is not supplied, the event-store connection string is used. +/// +public sealed class SqlServerAdminAuditLoggerOptions +{ + /// The configuration section name used to bind these options. + public const string SqlServerAudit = "Admin:SqlServer:Audit"; + + /// The default table name used to persist audit entries. + public const string DefaultTableName = "AdminAuditLog"; + + /// + /// The connection string used to access the SQL Server database. When null, the event-store + /// connection string is used. + /// + /// + /// A separate database is worth considering: an audit trail usually wants different retention, + /// different backup policy, and narrower write permissions than the data it describes. + /// + public string? ConnectionString { get; set; } + + /// The schema that owns the audit table. + [Required(AllowEmptyStrings = false)] + [RegularExpression(@"^[\w\-.]+$")] + public string SchemaName { get; set; } = "dbo"; + + /// The name of the table that stores audit entries. + [Required(AllowEmptyStrings = false)] + [RegularExpression(@"^[\w\-.]+$")] + public string TableName { get; set; } = DefaultTableName; + + /// When true, the audit table is created if it does not exist. + public bool AutoCreateTable { get; set; } = true; + + /// + /// What happens when an audit entry cannot be written. + /// + /// + /// Defaults to . The Admin portal exposes event payloads + /// and mutating operations, so an action nobody can prove happened is the outcome worth avoiding. + /// Set to where availability matters more. + /// + public AdminAuditFailureMode FailureMode { get; set; } = AdminAuditFailureMode.Fail; +} diff --git a/src/tests/Admin.UnitTests/Api/AdminOperationalEndpointsTests.cs b/src/tests/Admin.UnitTests/Api/AdminOperationalEndpointsTests.cs index 06a66df1..f983c4e6 100644 --- a/src/tests/Admin.UnitTests/Api/AdminOperationalEndpointsTests.cs +++ b/src/tests/Admin.UnitTests/Api/AdminOperationalEndpointsTests.cs @@ -133,8 +133,10 @@ public async Task Capabilities_GivenEnabledFeature_AuditsPrivilegedRead(Cancella await client.GetAsync("/admin/api/capabilities", cancellationToken); await client.GetAsync("/admin/api/health", cancellationToken); - var auditLogger = host.App.Services.GetRequiredService(); - var audit = (InMemoryAdminAuditLogger)auditLogger; + // The unkeyed registration is the context-stamping decorator; the recording logger sits + // behind the sink key. + var audit = (InMemoryAdminAuditLogger) + host.App.Services.GetRequiredKeyedService(AdminAuditKeys.Sink); await Assert.That(audit.Entries.Count).IsEqualTo(2); await Assert.That(audit.Entries.All(static entry => entry.Feature == AdminFeature.ViewCapabilities)).IsTrue(); await Assert.That(audit.Entries.All(static entry => entry.Succeeded)).IsTrue(); diff --git a/src/tests/Admin.UnitTests/Auditing/ContextStampingAdminAuditLoggerTests.cs b/src/tests/Admin.UnitTests/Auditing/ContextStampingAdminAuditLoggerTests.cs new file mode 100644 index 00000000..9ab9e217 --- /dev/null +++ b/src/tests/Admin.UnitTests/Auditing/ContextStampingAdminAuditLoggerTests.cs @@ -0,0 +1,153 @@ +using System.Collections.Concurrent; +using Microsoft.Extensions.DependencyInjection; +using Purview.EventSourcing.Admin.API.Auditing; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.Services; +using Purview.EventSourcing.Tenancy; + +namespace Purview.EventSourcing.Admin.Auditing; + +/// +/// Stamping the tenant and correlation identifier onto audit entries. +/// +/// +/// "Who did this" is incomplete without "to which tenant", and an entry that cannot be tied to the +/// events it caused answers very little. Both are stamped centrally so an endpoint added later +/// cannot forget them. +/// +public sealed class ContextStampingAdminAuditLoggerTests +{ + [Test] + public async Task LogAsync_StampsTheTenantTheOperationActedOn() + { + RecordingAuditLogger inner = new(); + var logger = CreateLogger(inner, correlationId: "corr-1"); + + using (AmbientCurrentTenant.BeginScope(TenantScope.For("acme"))) + await logger.LogAsync(Entry(), CancellationToken.None); + + await Assert.That(inner.Entries.Single().TenantId).IsEqualTo("acme"); + } + + [Test] + public async Task LogAsync_StampsTheCorrelationIdentifier() + { + RecordingAuditLogger inner = new(); + var logger = CreateLogger(inner, correlationId: "corr-1"); + + await logger.LogAsync(Entry(), CancellationToken.None); + + await Assert.That(inner.Entries.Single().CorrelationId).IsEqualTo("corr-1"); + } + + // A single-tenant deployment has no tenant to record, and the system scope is infrastructure + // rather than a tenant - neither should invent one. + [Test] + public async Task LogAsync_GivenTheSystemScope_LeavesTheTenantUnset() + { + RecordingAuditLogger inner = new(); + var logger = CreateLogger(inner, correlationId: null); + + using (AmbientCurrentTenant.BeginScope(TenantScope.System)) + await logger.LogAsync(Entry(), CancellationToken.None); + + await Assert.That(inner.Entries.Single().TenantId).IsNull(); + } + + // A caller that already knows better wins: stamping fills gaps, it does not overwrite. + [Test] + public async Task LogAsync_GivenAnEntryThatAlreadyCarriesContext_DoesNotOverwriteIt() + { + RecordingAuditLogger inner = new(); + var logger = CreateLogger(inner, correlationId: "ambient"); + + using (AmbientCurrentTenant.BeginScope(TenantScope.For("acme"))) + await logger.LogAsync( + Entry() with + { + TenantId = "explicit-tenant", + CorrelationId = "explicit-correlation", + }, + CancellationToken.None + ); + + var recorded = inner.Entries.Single(); + + await Assert.That(recorded.TenantId).IsEqualTo("explicit-tenant"); + await Assert.That(recorded.CorrelationId).IsEqualTo("explicit-correlation"); + } + + // The decorator has to apply to whichever logger the application registered, not just the + // default - otherwise a deployment with a durable logger silently loses the stamping. + [Test] + public async Task AddAdminAuditContextStamping_DecoratesTheRegisteredLogger() + { + ServiceCollection services = new(); + services.AddLogging(); + services.AddEventSourcing(); + RecordingAuditLogger inner = new(); + services.AddKeyedSingleton(AdminAuditKeys.Sink, inner); + services.AddAdminAuditContextStamping(); + + await using var provider = services.BuildServiceProvider(); + var resolved = provider.GetRequiredService(); + + await Assert.That(resolved).IsTypeOf(); + + using (AmbientCurrentTenant.BeginScope(TenantScope.For("globex"))) + await resolved.LogAsync(Entry(), CancellationToken.None); + + await Assert.That(inner.Entries.Single().TenantId).IsEqualTo("globex"); + } + + // No sink registered: the in-memory one is the default, so stamping still works rather than + // failing at start-up. Ordering is no longer a question. + [Test] + public async Task AddAdminAuditContextStamping_GivenNoRegisteredSink_FallsBackToInMemory() + { + ServiceCollection services = new(); + services.AddLogging(); + services.AddEventSourcing(); + services.AddAdminAuditContextStamping(); + + await using var provider = services.BuildServiceProvider(); + + await Assert.That(provider.GetRequiredService()).IsTypeOf(); + await Assert + .That(provider.GetRequiredKeyedService(AdminAuditKeys.Sink)) + .IsTypeOf(); + } + + static ContextStampingAdminAuditLogger CreateLogger(IAdminAuditLogger inner, string? correlationId) => + new(inner, new AmbientCurrentTenant(), new FixedCorrelationIdProvider(correlationId)); + + static AdminAuditEntry Entry() => + new( + DateTimeOffset.UtcNow, + AdminFeature.ViewCapabilities, + "Read", + "an-administrator", + Target: null, + Succeeded: true, + Details: null + ); + + sealed class RecordingAuditLogger : IAdminAuditLogger + { + readonly ConcurrentQueue _entries = new(); + + public IReadOnlyList Entries => [.. _entries]; + + public Task LogAsync(AdminAuditEntry entry, CancellationToken cancellationToken) + { + _entries.Enqueue(entry); + + return Task.CompletedTask; + } + } + + sealed class FixedCorrelationIdProvider(string? correlationId) : IEventStoreCorrelationIdProvider + { + public string? GetCorrelationId() => correlationId; + } +} diff --git a/src/tests/SqlServer.IntegrationTests/Auditing/SqlServerAdminAuditLoggerTests.cs b/src/tests/SqlServer.IntegrationTests/Auditing/SqlServerAdminAuditLoggerTests.cs new file mode 100644 index 00000000..25f354b0 --- /dev/null +++ b/src/tests/SqlServer.IntegrationTests/Auditing/SqlServerAdminAuditLoggerTests.cs @@ -0,0 +1,158 @@ +using Microsoft.Extensions.Logging.Abstractions; +using Microsoft.Extensions.Options; +using Purview.EventSourcing.Admin.Models; +using Purview.EventSourcing.Admin.SqlServer; +using Purview.EventSourcing.Fixtures.SqlServer; +using Purview.EventSourcing.SqlServer.Events; + +namespace Purview.EventSourcing.SqlServer.Auditing; + +/// +/// The durable admin audit logger against real SQL Server. +/// +/// +/// In a regulated deployment the audit trail is the control, so the behaviour worth protecting is +/// that an entry is actually written - and that a deployment which cannot write one finds out, +/// rather than proceeding unaudited by accident. +/// +[ClassDataSource(Shared = SharedType.PerTestSession)] +public sealed class SqlServerAdminAuditLoggerTests(SqlServerEventStoreFixture fixture) +{ + [Test] + public async Task LogAsync_WritesTheEntry(CancellationToken cancellationToken) + { + var table = $"AuditLog_{Guid.NewGuid():N}"; + using var logger = CreateLogger(table); + + await logger.LogAsync(Entry(target: "aggregate-1"), cancellationToken); + + var rows = await ReadAllAsync(table, cancellationToken); + + await Assert.That(rows.Count).IsEqualTo(1); + await Assert.That(rows[0].Target).IsEqualTo("aggregate-1"); + await Assert.That(rows[0].Feature).IsEqualTo(nameof(AdminFeature.ViewCapabilities)); + } + + [Test] + public async Task LogAsync_RecordsTheTenantAndCorrelation(CancellationToken cancellationToken) + { + var table = $"AuditLog_{Guid.NewGuid():N}"; + using var logger = CreateLogger(table); + + await logger.LogAsync(Entry() with { TenantId = "acme", CorrelationId = "corr-1" }, cancellationToken); + + var rows = await ReadAllAsync(table, cancellationToken); + + await Assert.That(rows[0].TenantId).IsEqualTo("acme"); + await Assert.That(rows[0].CorrelationId).IsEqualTo("corr-1"); + } + + // A refused operation is the one most worth recording, so failure must be audited too. + [Test] + public async Task LogAsync_RecordsAFailedOperation(CancellationToken cancellationToken) + { + var table = $"AuditLog_{Guid.NewGuid():N}"; + using var logger = CreateLogger(table); + + await logger.LogAsync(Entry() with { Succeeded = false, Details = "denied" }, cancellationToken); + + var rows = await ReadAllAsync(table, cancellationToken); + + await Assert.That(rows[0].Succeeded).IsFalse(); + await Assert.That(rows[0].Details).IsEqualTo("denied"); + } + + // Fail is the default: an action nobody can prove happened is worse than an action that did not. + [Test] + public async Task LogAsync_WhenTheEntryCannotBeWritten_FailsByDefault(CancellationToken cancellationToken) + { + using var logger = CreateLogger( + $"AuditLog_{Guid.NewGuid():N}", + connectionString: "Server=127.0.0.1,1;Database=absent;User Id=sa;Password=no;Encrypt=False;Connect Timeout=1" + ); + + await Assert.That(async () => await logger.LogAsync(Entry(), cancellationToken)).ThrowsException(); + } + + // Continue is a deliberate choice: the operation proceeds unaudited and the gap is logged. + [Test] + public async Task LogAsync_WhenConfiguredToContinue_DoesNotThrow(CancellationToken cancellationToken) + { + using var logger = CreateLogger( + $"AuditLog_{Guid.NewGuid():N}", + connectionString: "Server=127.0.0.1,1;Database=absent;User Id=sa;Password=no;Encrypt=False;Connect Timeout=1", + failureMode: AdminAuditFailureMode.Continue + ); + + await Assert.That(async () => await logger.LogAsync(Entry(), cancellationToken)).ThrowsNothing(); + } + + static AdminAuditEntry Entry(string? target = null) => + new( + DateTimeOffset.UtcNow, + AdminFeature.ViewCapabilities, + "Read", + "an-administrator", + target, + Succeeded: true, + Details: null + ); + + SqlServerAdminAuditLogger CreateLogger( + string tableName, + string? connectionString = null, + AdminAuditFailureMode failureMode = AdminAuditFailureMode.Fail + ) => + new( + Options.Create( + new SqlServerAdminAuditLoggerOptions + { + ConnectionString = connectionString ?? fixture.ConnectionString, + TableName = tableName, + FailureMode = failureMode, + } + ), + Options.Create(new SqlServerEventStoreOptions { ConnectionString = fixture.ConnectionString }), + NullLogger.Instance + ); + + async Task> ReadAllAsync(string tableName, CancellationToken cancellationToken) + { + await using Microsoft.Data.SqlClient.SqlConnection connection = new(fixture.ConnectionString); + await connection.OpenAsync(cancellationToken); + +#pragma warning disable CA2100 + await using Microsoft.Data.SqlClient.SqlCommand command = new( + $"SELECT [Feature], [TenantId], [Target], [Succeeded], [Details], [CorrelationId] FROM [dbo].[{tableName}] ORDER BY [Id]", + connection + ); +#pragma warning restore CA2100 + + List rows = []; + await using var reader = await command.ExecuteReaderAsync(cancellationToken); + while (await reader.ReadAsync(cancellationToken)) + { + rows.Add( + new( + reader.GetString(0), + await reader.IsDBNullAsync(1, cancellationToken) ? null : reader.GetString(1), + await reader.IsDBNullAsync(2, cancellationToken) ? null : reader.GetString(2), + reader.GetBoolean(3), + await reader.IsDBNullAsync(4, cancellationToken) ? null : reader.GetString(4), + await reader.IsDBNullAsync(5, cancellationToken) ? null : reader.GetString(5) + ) + ); + } + + return rows; + } + + sealed record AuditRow( + string Feature, + string? TenantId, + string? Target, + bool Succeeded, + string? Details, + string? CorrelationId + ); +} diff --git a/src/tests/SqlServer.IntegrationTests/SqlServer.IntegrationTests.csproj b/src/tests/SqlServer.IntegrationTests/SqlServer.IntegrationTests.csproj index 1730a050..10f0c7a8 100644 --- a/src/tests/SqlServer.IntegrationTests/SqlServer.IntegrationTests.csproj +++ b/src/tests/SqlServer.IntegrationTests/SqlServer.IntegrationTests.csproj @@ -1,4 +1,4 @@ - + + + + +