Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion ARCHITECTURE-SLICES.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ the two disagreed the code won — §10 lists what changed on contact with the c
written while the work sat on `feat/vertical-slices-cqrs` and still argues with itself about
whether to merge it; §11.3 says how that ended.

The solution builds clean on `net8.0` and `net10.0` with `TreatWarningsAsErrors`, and all 163 tests
The solution builds clean on `net8.0` and `net10.0` with `TreatWarningsAsErrors`, and all 172 tests
pass, including the integration suite that boots the real `Program.cs` against a throwaway
PostgreSQL and drives every route over HTTP. No endpoint's URL, status code or JSON shape changed.

Expand Down
63 changes: 36 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -385,8 +385,7 @@ accepted.

### 6. MultiLingual's row is not in the trail

`src/DotNetBoostSample.Infrastructure/DependencyInjection.cs` — one line, `.IgnoreEntity<Translation>()`
— plus HiLo keys on `Category` and `Product`.
`src/DotNetBoostSample.Infrastructure/DependencyInjection.cs` — one line, `.IgnoreEntity<Translation>()`.

`UseAuditing(sp)` attaches DotNetBoost.Auditing's `SaveChangesInterceptor`, which records every
create, update and delete in the same `SaveChanges` as the change, with no application code. On
Expand Down Expand Up @@ -423,24 +422,30 @@ services.AddAuditing()
Neither library learned the other's name: the fix was an ignore-list on one builder, not a package
pairing the two.

**Keys are assigned before the save.** For a database-generated key, the interceptor writes the
`Created` entry in a second, nested `SaveChanges`. Up to MultiLingual `1.0.0-preview.2` that nested
save also restarted MultiLingual's interceptor mid-save, dropping the outer save's pending work and
committing its transaction from the inside. `1.0.0-preview.3` fixed that: a nested save now joins
the outer one, and only the outermost writes, commits or rolls back. Auditing `1.0.0-preview.3`
fixed its own side the same way, so with either library registered first, the entity, its
translations and its `Created` entry commit or roll back together. The catalogue's entities keep
their HiLo keys anyway, because a creation in one save is simpler than a creation in two, and
dropping them would need a data migration:

```csharp
category.Property(c => c.Id).UseHiLo("CategoryIds");
product.Property(p => p.Id).UseHiLo("ProductIds");
```

The id is assigned at `AddAsync`, so a creation's entry goes into the caller's own save. The costs:
ids have gaps, and an older database needs the sequences created past its existing ids, which
`DatabaseInitialiser` does and `SchemaUpgradeTests` checks.
**Keys are generated by the INSERT.** For a database-generated key, the interceptor writes the
`Created` entry in a second, nested `SaveChanges`, in a transaction it opens to cover both. Up to
MultiLingual `1.0.0-preview.2` that nested save also restarted MultiLingual's interceptor mid-save,
dropping the outer save's pending work and committing its transaction from the inside.
`1.0.0-preview.3` fixed that: a nested save now joins the outer one, and only the outermost writes,
commits or rolls back. Auditing `1.0.0-preview.3` fixed its own side the same way, so with either
library registered first, the entity, its translations and its `Created` entry commit or roll back
together.

Until then `Category` and `Product` took HiLo keys, so the id existed at `AddAsync` and no nested
save was needed. They are identity columns again, which leaves one cost: a volume from the HiLo
builds has key columns with no identity, or an identity counter behind the ids HiLo handed out.
`DatabaseInitialiser` gives the columns their identity back and moves each counter past the rows
already there, and past the last block each HiLo sequence handed out, so the id of a row deleted
during those builds, whose audit trail outlives it, is never handed out again. `SchemaUpgradeTests`
checks both kinds of volume. Stop the older build first: while
it runs it keeps handing out ids from the HiLo block it holds.

**Retries, and atomicity checked.** The context runs under Npgsql's `EnableRetryOnFailure`.
MultiLingual replays a save under a retrying strategy, and before Auditing `1.0.0-preview.3` that
recorded every change twice, and again on each retry; now a replayed save is recorded once. The
test host also sets `Auditing:OnLostAtomicity` to `Throw` (the application reads it in
`Program.cs`, and defaults to `Report`), so a composition in which another interceptor commits the
transaction before a creation's entry is written fails a test instead of logging an error.

**What the trail holds:** everything this `DbContext` saves except `Translation` and `Setting` —
`MediaFile`, `MediaAttachment` and `Language` as well as the catalogue, and the seed's first run with
Expand Down Expand Up @@ -575,7 +580,7 @@ as `""` where the default mode answers `null`, because the column is a non-nulla

`dotnet test` boots the sample twice, in two hosts against two schemas.

**The whole integration suite runs in both modes**: fifty-eight tests against each, the same
**The whole integration suite runs in both modes**: sixty-two tests against each, the same
assertions, unchanged — and between them they call **every one of the API's 48 published routes**.
`OpenApiShapeTests` asserts that inventory by name, so a route added by this application or a new
library version fails the suite rather than going uncalled.
Expand All @@ -596,7 +601,7 @@ three languages.

| | |
|---|---|
| **Glue per app** | Every application writes the join itself: here, 49 lines of code across `MediaText.cs`, `MultiLingualSchemaContributor.cs` and `MediaTextCleanup.cs`, plus `.IgnoreEntity<Translation>()` and two HiLo keys. |
| **Glue per app** | Every application writes the join itself: here, 49 lines of code across `MediaText.cs`, `MultiLingualSchemaContributor.cs` and `MediaTextCleanup.cs`, plus `.IgnoreEntity<Translation>()`. |
| **Cascade is opt-in** | Deleting a `MediaFile` does not know its alt text exists. One `IMediaFilesDeletedHandler` connects them, but knowing the two records are about one thing is still the application's job. |
| **Magic strings** | `"MediaFile"` has no compile-time link to the type. Mitigated with one `const`, asserted against `MediaEntityNames.For(typeof(MediaFile))`. |
| **Agreement by published spec** | Three libraries must address an entity identically. All implement *DotNetBoost Entity Addressing v1* and publish `EntityKey.AddressingVersion`, and `KeyFormatAgreementTests` spells the agreement out. For Auditing a silent mismatch would not break a join — it would write a trail no read can find. |
Expand Down Expand Up @@ -660,15 +665,19 @@ abstract class holds the assertions and two sealed subclasses bind it to each fi
- **`RemainingRouteTests`** — the six routes nothing else called.
- **`AuditTrailTests`** — a product's life in the trail and the history that outlives it; a change
made straight through `AppDbContext` recorded all the same; no `Translation` entry; settings saves
as one entry, committed in the settings save, and none at all when that save fails; the right actor on each entry; and **a refused write records nothing**.
as one entry, committed in the settings save, and none at all when that save fails; the right actor on each entry; **a refused write records nothing**; a creation whose translation
write fails leaves no product, text or entry, and one retried after a transient failure is
recorded once; and the suite itself runs under a retrying strategy and fails any save that
loses atomicity.
- **`AuditRetentionTests`** — retention is off by default, and once switched on,
`AuditRetentionService` deletes old entries and keeps new ones.
- **`SchemaUpgradeTests`** — a database from before the HiLo keys still boots and creates rows.
- **`SchemaUpgradeTests`** — a database from the HiLo builds, of either kind, gets identity keys
back, counting past its existing rows.
- **`BaseLanguageTests`** — what only base-language mode can be asked.
Sixteen tests, beside the fifty-eight the suite runs in each mode.
Sixteen tests, beside the sixty-two the suite runs in each mode.

**Without a container runtime these skip rather than fail** — `dotnet test` still runs the 30 fast
tests and reports the other 133 as skipped, with the reason.
tests and reports the other 142 as skipped, with the reason.

### And the dashboard's own

Expand Down Expand Up @@ -811,7 +820,7 @@ src/DotNetBoostSample.Application/
Settings/ Branding, Catalog and Auditing settings groups
src/DotNetBoostSample.Infrastructure/
Persistence/AppDbContext.cs one database, four Apply* calls
Persistence/Configurations/ one per entity: unique indexes and HiLo keys
Persistence/Configurations/ one per entity: tables and unique indexes
Persistence/DatabaseInitialiser.cs schema and seed on first run, and upgrades for old volumes
Persistence/SettingGroupAuditParticipant.cs
Persistence/PostgresErrorTranslator.cs
Expand Down
12 changes: 11 additions & 1 deletion src/DotNetBoostSample.Api/Program.cs
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
using DotNetBoost.Auditing.API;
using DotNetBoost.Auditing.Core.Models;
using DotNetBoost.Media.API;
using DotNetBoost.MultiLingual.API;
using DotNetBoostSample.Api.Auditing;
Expand Down Expand Up @@ -73,6 +74,14 @@
//
// UseHttpContextActor puts the signed-in user on every entry. UseLoggingObserver logs what the
// engine chose not to record, so a skipped change can be told apart from one nobody made.
//
// OnLostAtomicity says what happens when another SaveChanges interceptor commits the transaction
// before Auditing has written a creation's entry, so the entry can no longer commit with its
// change. Report — logged as an error by UseLoggingObserver — unless configured otherwise. The
// test host sets Auditing:OnLostAtomicity to Throw, so a composition that loses atomicity fails a
// test instead of leaving a line in a log nobody reads.
var lostAtomicity = builder.Configuration.GetValue("Auditing:OnLostAtomicity", LostAtomicity.Report);

builder.Services.AddInfrastructure(
connectionString,
Path.GetFullPath(mediaRoot),
Expand All @@ -82,7 +91,8 @@
.Allow<BrandingSettings>()), // the settings group's translated StoreName
audit => audit
.UseHttpContextActor()
.UseLoggingObserver());
.UseLoggingObserver()
.OnLostAtomicity(lostAtomicity));

// ── The dispatcher, the eleven slices, the behaviors, the composition ────────
builder.Services.AddApplication();
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -45,11 +45,12 @@ public async Task<CategoryCreated> HandleAsync(Command request, CancellationToke
{
var category = new Category { Slug = request.Slug };

// AddAsync, because adding is what assigns the HiLo id — see CategoryConfiguration.
await db.Categories.AddAsync(category, ct);

// One SaveChanges for the row, every language's text and its audit entry. CreateAsync
// rather than SaveAsync, so a create under any language names every base-language value.
// One SaveChanges call for the row, every language's text and its audit entry — the
// entry in a save Auditing nests inside it once the INSERT has given the row its id, in
// one transaction. CreateAsync rather than SaveAsync, so a create under any language
// names every base-language value.
await translatedText.CreateAsync(db, category, request.Translations, ct);

return new CategoryCreated(category.Id, category.Slug);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -62,11 +62,12 @@ public async Task<Result<ProductCreated>> HandleAsync(Command request, Cancellat
CategoryId = request.CategoryId
};

// AddAsync, because adding is what assigns the HiLo id — see ProductConfiguration.
await db.Products.AddAsync(product, ct);

// One SaveChanges for the row, every language's text and its audit entry. CreateAsync
// rather than SaveAsync, so a create under any language names every base-language value.
// One SaveChanges call for the row, every language's text and its audit entry — the
// entry in a save Auditing nests inside it once the INSERT has given the row its id, in
// one transaction. CreateAsync rather than SaveAsync, so a create under any language
// names every base-language value.
await translatedText.CreateAsync(db, product, request.Translations, ct);

return new ProductCreated(product.Id, product.Sku);
Expand Down
20 changes: 13 additions & 7 deletions src/DotNetBoostSample.Infrastructure/DependencyInjection.cs
Original file line number Diff line number Diff line change
Expand Up @@ -64,10 +64,17 @@ public static IServiceCollection AddInfrastructure(
// handler mentions auditing. The two know nothing of each other; what it took for them to
// share this context is in the Auditing block below.
//
// EnableRetryOnFailure, so a dropped connection or a failover is retried rather than
// answered with a 500. Since MultiLingual 1.0.0-preview.3 and Auditing 1.0.0-preview.3 that
// is safe with both interceptors on the context: MultiLingual replays a save under the
// retrying strategy, and Auditing records a replayed save once. Before, every change in
// the trail was recorded twice — and again on each retry. The two interceptors may also be
// registered in either order; this one is the order the sample has always used.
//
// ReplaceService, because the model depends on the base language and EF's own cache key
// does not. See MultiLingualModelCacheKeyFactory.
services.AddDbContext<AppDbContext>((sp, options) =>
options.UseNpgsql(connectionString)
options.UseNpgsql(connectionString, npgsql => npgsql.EnableRetryOnFailure())
.UseMultiLingual(sp)
.UseAuditing(sp)
.ReplaceService<IModelCacheKeyFactory, MultiLingualModelCacheKeyFactory>());
Expand Down Expand Up @@ -155,12 +162,11 @@ public static IServiceCollection AddInfrastructure(
// is that attribute applied from outside. Translated text is out of the trail anyway.
//
// 2. Keys. For a database-generated key, the interceptor writes a Created entry in a
// second, nested SaveChanges. Since MultiLingual 1.0.0-preview.3 and Auditing
// 1.0.0-preview.3 both libraries count nested saves, so that save is safe beside
// MultiLingual's interceptor in either registration order. Category and Product keep
// HiLo keys anyway (see their configurations): the id exists when the entity is added,
// so a creation's entry goes into the caller's own save, with no second save and no
// transaction opened to cover one.
// second, nested SaveChanges, in a transaction it opens to cover both. Since
// MultiLingual 1.0.0-preview.3 and Auditing 1.0.0-preview.3 both libraries count nested
// saves, so that save is safe beside MultiLingual's interceptor in either registration
// order. Category and Product took HiLo keys to avoid it until then; they are identity
// columns again (see their configurations).
//
// 3. Settings. The library stores a group one row per property. IgnoreEntity<Setting>()
// keeps those rows out, and SettingGroupAuditParticipant records the save as one entry
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,9 @@ namespace DotNetBoostSample.Infrastructure.Persistence;
/// tables are mapped here like any other library's, and its capture is attached to this context in
/// <c>DependencyInjection.cs</c> — beside MultiLingual's, on the same save. Two things had to be
/// true for that: MultiLingual's <c>Translation</c>, keyed on four columns, is kept out of the
/// trail with <c>IgnoreEntity&lt;Translation&gt;()</c>, and the two entities here take HiLo keys
/// so that a creation's entry is written in the save that creates the row. That file has both.
/// trail with <c>IgnoreEntity&lt;Translation&gt;()</c>, and a creation's entry, written in a save
/// nested inside the one that creates the row, has to be safe beside MultiLingual's interceptor —
/// which both libraries' 1.0.0-preview.3 made it. That file has both.
/// </para>
/// <para>
/// It is also one of only <b>three</b> of the nine composition files that are infrastructure; the
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -32,19 +32,13 @@ public void Configure(EntityTypeBuilder<Category> category)
category.ToTable("Categories");
category.HasKey(c => c.Id);

// The id comes from a HiLo sequence rather than an identity column: EF reserves a block of
// ids from "CategoryIds" and hands one out when the entity is ADDED, before anything is saved.
// That is what keeps a creation's audit entry in the same SaveChanges as the row: for a key
// the INSERT has yet to generate, DotNetBoost.Auditing defers the entry to a second save
// nested inside the first, and opens a transaction to cover both. Since 1.0.0-preview.3 of
// both libraries that nested save is safe beside MultiLingual's interceptor, so HiLo is no
// longer what keeps the two apart; it keeps a creation to one save — see
// Infrastructure/DependencyInjection.cs. DatabaseInitialiser creates the sequence on a
// database made before it existed.
//
// Add with AddAsync for the same reason: a block that has run out is refilled from the
// database, and AddAsync is the overload that does that without blocking.
category.Property(c => c.Id).UseHiLo("CategoryIds");
// The id is an identity column, Npgsql's default, so nothing is configured for it. The INSERT
// generates it, which means DotNetBoost.Auditing cannot write a creation's entry until the
// row is in: it defers the entry to a second save nested inside the first, in a transaction
// it opens to cover both. Since 1.0.0-preview.3 of Auditing and MultiLingual that nested
// save is safe beside MultiLingual's interceptor, in either order and under a retrying
// strategy — see Infrastructure/DependencyInjection.cs. This took its ids from a HiLo
// sequence until then; DatabaseInitialiser moves a database from that era back to identity.
category.Property(c => c.Slug).HasMaxLength(128).IsRequired();
category.HasIndex(c => c.Slug).IsUnique().HasDatabaseName(SlugIndex);
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,7 @@ public void Configure(EntityTypeBuilder<Product> product)
product.ToTable("Products");
product.HasKey(p => p.Id);

// HiLo, from a sequence of its own — see CategoryConfiguration for why a key assigned
// before the save is what keeps a creation's audit entry in that save, without Auditing's
// nested second save.
product.Property(p => p.Id).UseHiLo("ProductIds");
// An identity column, like Category's — see CategoryConfiguration.
product.Property(p => p.Sku).HasMaxLength(64).IsRequired();
product.Property(p => p.Price).HasPrecision(18, 2);
product.HasIndex(p => p.Sku).IsUnique().HasDatabaseName(SkuIndex);
Expand Down
Loading
Loading