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
4 changes: 2 additions & 2 deletions 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 172 tests
The solution builds clean on `net8.0` and `net10.0` with `TreatWarningsAsErrors`, and all 178 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 Expand Up @@ -56,7 +56,7 @@ compile against DotNetBoost's own `net8.0` TFM.

This repo was **1,788 lines of C# in 13 files** when this was written, and the README's thesis is
that the integration between three independent libraries is *five files, none of them large*. A
fourth library has since been installed, and that count is now nine files — see the README; the
fourth library has since been installed, and that count is now ten files — see the README; the
reasoning below is unaffected. The one new file it would have changed its mind about,
`Composition/CreationTrail.cs` — a creation's audit entry, written by hand in a scope of its own —
is gone again: DotNetBoost.Auditing 1.0.0-preview.2 added `IgnoreEntity<T>()`, its capture is now
Expand Down
11 changes: 6 additions & 5 deletions Directory.Packages.props
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,8 @@
Nothing aligns their numbers. Auditing reached preview.2 a release after the other
three, for a fix of its own (IgnoreEntity<T>(), below); Settings and MultiLingual then
moved to preview.3 for fixes this sample's composition turned up, and Auditing followed
for its own side of them, while Media stayed on preview.2. Four independently versioned
for its own side of them. Media stayed on preview.2 until it too reached preview.3, for
the write participants this sample's media audit trail is built on. Four independently versioned
libraries are four release cadences, which is the other half of what "no shared kernel"
means.
────────────────────────────────────────────────────────────────────────── -->
Expand All @@ -29,10 +30,10 @@
</ItemGroup>

<ItemGroup Label="DotNetBoost — Media">
<PackageVersion Include="DotNetBoost.Media.Core" Version="1.0.0-preview.2" />
<PackageVersion Include="DotNetBoost.Media.EntityFrameworkCore" Version="1.0.0-preview.2" />
<PackageVersion Include="DotNetBoost.Media.FileSystem" Version="1.0.0-preview.2" />
<PackageVersion Include="DotNetBoost.Media.API" Version="1.0.0-preview.2" />
<PackageVersion Include="DotNetBoost.Media.Core" Version="1.0.0-preview.3" />
<PackageVersion Include="DotNetBoost.Media.EntityFrameworkCore" Version="1.0.0-preview.3" />
<PackageVersion Include="DotNetBoost.Media.FileSystem" Version="1.0.0-preview.3" />
<PackageVersion Include="DotNetBoost.Media.API" Version="1.0.0-preview.3" />
</ItemGroup>

<ItemGroup Label="DotNetBoost — MultiLingual">
Expand Down
78 changes: 66 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ What it demonstrates is as much what is *absent* as what is present:
- no integration package pairing any two libraries

Each library is installed and configured on its own. Everything that joins them is this
application's code, in nine files, [listed below](#where-the-composition-happens). `tests/` asserts
application's code, in ten files, [listed below](#where-the-composition-happens). `tests/` asserts
that no library references another, so the claim cannot quietly stop being true.

**Auditing was added last, to a solution the other three were already in** — the one measure of
Expand Down Expand Up @@ -190,9 +190,9 @@ are `npm run lint`, `npm run typecheck`, `npm test` and `npm run test:e2e`.

## Where the composition happens

Nine files of this application's own code. Each is a place where it says two libraries are talking
Ten files of this application's own code. Each is a place where it says two libraries are talking
about the same thing — the only way they ever find out, since none references another — or, for the
last three, where one library's data has no place in another's in the shape it is stored in:
last four, where one library's data has no place in another's in the shape it is stored in:

| | File | Joins | What it says |
|---|---|---|---|
Expand All @@ -204,9 +204,10 @@ last three, where one library's data has no place in another's in the shape it i
| 6 | `Infrastructure/DependencyInjection.cs` — one line | Auditing → MultiLingual | MultiLingual's translation row is not in the trail: `.IgnoreEntity<Translation>()` |
| 7 | `Domain/Catalog/Category.cs` and `Product.cs` | MultiLingual → Auditing | a translated property is not in the trail: `[AuditIgnore]` beside `[MultiLingual]` |
| 8 | `Infrastructure/Persistence/SettingGroupAuditParticipant.cs` | Settings → Auditing | a settings save is one entry for the group, not one per row, committed with it |
| 9 | `Infrastructure/Persistence/MediaAuditParticipant.cs` | Media → Auditing | attaching a file is a change to the product it is attached to, and is recorded there, committed with it |

Nine files in eight entries, because the seventh is one sentence said once per entity. It was five
before Auditing arrived. Three of these exist because two libraries **disagree**, which is a worse
Ten files in nine entries, because the seventh is one sentence said once per entity. It was five
before Auditing arrived. Four of these exist because two libraries **disagree**, which is a worse
kind of glue than "these two tables are about one thing" — and the reason the count is kept honest
rather than tidy.

Expand All @@ -217,9 +218,9 @@ it to Media is the string `"MediaFile"`, not a type. A join is an identity asser
string, an attribute or a type both sides must agree on, which is why `BrandingOwnerTests`,
`KeyFormatAgreementTests` and `AuditRuleTests` exist.

**Six of the nine name only `DotNetBoost.*.Core`**, so they live in the application and domain
layers beside the code that uses them. Only `AppDbContext`, the `IgnoreEntity` line and
`SettingGroupAuditParticipant` are infrastructure, and all three are there because four libraries share
**Six of the ten name only `DotNetBoost.*.Core`**, so they live in the application and domain
layers beside the code that uses them. Only `AppDbContext`, the `IgnoreEntity` lines,
`SettingGroupAuditParticipant` and `MediaAuditParticipant` are infrastructure, and all four are there because four libraries share
**one `DbContext`**. Joining two libraries is not a persistence concern; joining them in one
database is.

Expand Down Expand Up @@ -513,6 +514,58 @@ Up to Settings `1.0.0-preview.2` this was an `ISettingWriteObserver`, which runs
and whose failures the library logs and swallows. This was then the one entry that did not commit
with its change.

### 9. A media change is recorded where people look for it — `src/.../Infrastructure/Persistence/MediaAuditParticipant.cs`

DotNetBoost.Media stores a file as a `MediaFile` row and each use of it as a `MediaAttachment` row,
so the interceptor alone recorded attaching a photo to a product as a `MediaAttachment` entry
addressed by the link's own GUID, and a soft delete as a `MediaFile` change to `DeletedAt`. Product
42's own history said nothing. The media library knows what each write means, and lets code take
part in it through `IMediaWriteParticipant`, which runs inside the write, before the store saves:

```csharp
// Media block
.UseWriteParticipant<MediaAuditParticipant>()

// Auditing block
.IgnoreEntity<MediaFile>()
.IgnoreEntity<MediaAttachment>();
```

Media reports each operation once — an attach, a detach, a replacement, a reorder, a delete — and
the participant files it where a reader would look for it. A change to which files an entity uses
is an `Updated` entry **on that entity**, with one row named after the role, file names as its
values, and the operation in the entry's `Metadata`:

| Operation | Entry | Row | Metadata |
|---|---|---|---|
| attach | Category 4 | `Banner: — → photo.png` | `{"media":"Attach","fileId":"…"}` |
| detach | Category 4 | `Banner: photo.png → —` | `{"media":"Detach","fileId":"…"}` |
| replace | Category 4 | `Banner: photo.png → new.png` | `{"media":"Replace","fileId":"…","previousFileId":"…"}` |
| reorder | Product 42 | `Gallery: a.png, b.png → b.png, a.png` | `{"media":"Reorder"}` |

An upload, an edit and a delete are about the file itself: `Created`, `Updated` and `Deleted` on
`("Media", <file id>)`, with its name, type, size, category and tags — only the ones it has. A
delete also writes a detach on every entity that still used the file, marked
`"reason":"FileDeleted"`, so a product's history says why its image went, and lists those entities
on the file's own entry as one `Attachments` row (`Category 4 as banner, Product 42 as gallery`),
so the file's history is complete on its own. All of them share one correlation id.

An attach can be filed under the product because Media's owner address and Auditing's entity
address are the same `(entityName, entityId)` — Entity Addressing v1, which
`KeyFormatAgreementTests` pins. The file's id is in the metadata rather than the row, which keeps
the row readable and still tells two files with the same name apart. The file entries are filed as
`"Media"` rather than `"MediaFile"` with `MediaFileInfo` as their type, because Auditing honours
`IgnoreEntity<MediaFile>()` by name when an entry has no type.

**It commits with the change**, exactly as the settings participant does: Media's EF Core store,
Auditing's and the participant share the request's `AppDbContext`, the entry and its change rows
are enlisted with `EfCoreMediaWriteScope.Add`, and the media store's own save carries them. A
participant that throws aborts the media write and everything enlisted is detached again.
`AuditTrailTests` checks both halves, the second with a test-only participant that fails the write
after the entry is enlisted.

Needs DotNetBoost.Media `1.0.0-preview.3`, the release that added write participants.

---

## Two places a language can live
Expand Down Expand Up @@ -580,7 +633,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**: sixty-two tests against each, the same
**The whole integration suite runs in both modes**: sixty-five 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 Down Expand Up @@ -674,10 +727,10 @@ abstract class holds the assertions and two sealed subclasses bind it to each fi
- **`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 sixty-two the suite runs in each mode.
Sixteen tests, beside the sixty-five 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 142 as skipped, with the reason.
tests and reports the other 148 as skipped, with the reason.

### And the dashboard's own

Expand Down Expand Up @@ -795,7 +848,7 @@ A duplicate slug or SKU never reaches a handler: the unique index refuses it, an
`409`. Reading a `PostgresException` cannot happen in `Application` and `IExceptionHandler` cannot
happen in `Infrastructure`, so the translator is an interface implemented on the provider's side.

### Why four projects for 47 files
### Why four projects for 48 files

It is more structure than 1,800 lines of behaviour needs, deliberately: the dependency rules above
are enforced by the build, not by a comment. The cost is that a route no longer shows what it does —
Expand Down Expand Up @@ -823,6 +876,7 @@ src/DotNetBoostSample.Infrastructure/
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/MediaAuditParticipant.cs
Persistence/PostgresErrorTranslator.cs
DependencyInjection.cs AddInfrastructure(): four independent blocks
src/DotNetBoostSample.Api/
Expand Down
14 changes: 12 additions & 2 deletions clients/dashboard/app/components/audit/EntryChanges.vue
Original file line number Diff line number Diff line change
Expand Up @@ -113,11 +113,21 @@ const showNew = computed(() => props.entry.action !== 'Deleted')
</dd>
</div>

<!-- The one thing read out of the metadata: a media operation, which this application's API
writes there because the library's three actions cannot say "attached". -->
<div v-if="mediaOperationOf(entry)" class="flex items-center gap-2">
<dt>{{ $t('audit.entry.mediaOperation') }}</dt>
<dd>
<AuditMediaOperationBadge :entry="entry" />
</dd>
</div>

<!-- Passed through as the string the application stored: the library never looked inside it,
and neither does this. -->
<div v-if="entry.metadata" class="flex items-center gap-2">
<div v-if="entry.metadata" class="flex max-w-full min-w-0 items-center gap-2">
<dt>{{ $t('audit.entry.metadata') }}</dt>
<dd dir="auto" class="text-foreground">
<!-- break-all: JSON with a GUID in it has nowhere to wrap, and would run off the row. -->
<dd dir="auto" class="min-w-0 break-all text-foreground">
{{ entry.metadata }}
</dd>
</div>
Expand Down
32 changes: 32 additions & 0 deletions clients/dashboard/app/components/audit/MediaOperationBadge.vue
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
<script setup lang="ts">
import type { AuditEntry } from '~/types'

const props = defineProps<{
entry: AuditEntry
/** On a phone, the icon alone — for the table, where the row has to fit. */
compact?: boolean
}>()

const { icon, label } = useMediaOperations()

/**
* Every media change is an `Updated` entry on its owner, because those are the only actions the
* auditing library has; the operation itself is in the entry's metadata. This draws it beside the
* action, so an attach and a reorder do not look alike.
*/
const info = computed(() => mediaOperationOf(props.entry))
</script>

<template>
<!-- In the table the short name, so the action column stays as narrow as the action's own badge;
the full one is on hover and in the entry's details. -->
<Badge
v-if="info"
variant="secondary"
class="text-muted-foreground"
:title="label(info)"
>
<component :is="icon(info)" class="text-primary" />
<span :class="{ 'max-sm:sr-only': compact }">{{ label(info, compact) }}</span>
</Badge>
</template>
5 changes: 4 additions & 1 deletion clients/dashboard/app/components/audit/TrailTable.vue
Original file line number Diff line number Diff line change
Expand Up @@ -275,7 +275,10 @@ function showEdit(correlationId: string) {
</TableCell>

<TableCell v-if="shown('action')">
<AuditActionBadge :action="row.original.action" />
<div class="flex flex-wrap items-center gap-1">
<AuditActionBadge :action="row.original.action" />
<AuditMediaOperationBadge :entry="row.original" compact />
</div>
</TableCell>

<TableCell v-if="shown('actor')" class="hidden lg:table-cell">
Expand Down
78 changes: 78 additions & 0 deletions clients/dashboard/app/composables/useMediaOperations.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
import type { Component } from 'vue'
import { ArrowUpDown, Link, Link2Off, Replace, Unlink } from '@lucide/vue'
import type { AuditEntry } from '~/types'

/** What `MediaAuditParticipant` writes as `"media"` in an entry's metadata. */
export type MediaOperation = 'Attach' | 'Detach' | 'Replace' | 'Reorder'

/** A media entry's operation, and whether its detach came from the file being deleted. */
export interface MediaOperationInfo {
operation: MediaOperation
fileDeleted: boolean
}

const operations: readonly MediaOperation[] = ['Attach', 'Detach', 'Replace', 'Reorder']

/**
* The media operation an entry records, read from its metadata — or `null` for every entry that is
* not one.
*
* The metadata is this application's own convention, not the auditing library's: the API's
* `MediaAuditParticipant` writes `{"media":"Attach","fileId":"…"}` and its kin on the owner's
* entry. Anything else — no metadata, metadata that is not JSON, JSON without a known `media` —
* is not a media entry, and is left to be shown as the string it is.
*/
export function mediaOperationOf(entry: Pick<AuditEntry, 'metadata'>): MediaOperationInfo | null {
if (!entry.metadata) return null

let parsed: unknown
try {
parsed = JSON.parse(entry.metadata)
} catch {
return null
}

if (!parsed || typeof parsed !== 'object') return null

const { media, reason } = parsed as { media?: unknown, reason?: unknown }

if (typeof media !== 'string' || !operations.includes(media as MediaOperation)) return null

return { operation: media as MediaOperation, fileDeleted: reason === 'FileDeleted' }
}

const icons: Record<MediaOperation, Component> = {
Attach: Link,
Detach: Unlink,
Replace,
Reorder: ArrowUpDown
}

/**
* How the Audit page draws a media operation: its icon and its name. The names are computed rather
* than looked up by a key built from the value, for the reason `useAuditActions` gives.
*/
export function useMediaOperations() {
const { t } = useI18n()

const labels = computed<Record<MediaOperation, string>>(() => ({
Attach: t('audit.media.attach'),
Detach: t('audit.media.detach'),
Replace: t('audit.media.replace'),
Reorder: t('audit.media.reorder')
}))

/**
* A detach because the file itself was deleted says so, rather than reading as a manual one —
* in full where there is room, and by its own icon where there is not.
*/
function label(info: MediaOperationInfo, short = false) {
return info.fileDeleted && !short ? t('audit.media.detachFileDeleted') : labels.value[info.operation]
}

function icon(info: MediaOperationInfo): Component {
return info.fileDeleted ? Link2Off : icons[info.operation]
}

return { icon, label }
}
10 changes: 9 additions & 1 deletion clients/dashboard/i18n/locales/ar.json
Original file line number Diff line number Diff line change
Expand Up @@ -350,6 +350,13 @@
"updated": "عُدِّل",
"deleted": "حُذف"
},
"media": {
"attach": "أُرفق",
"detach": "فُصل",
"detachFileDeleted": "فُصل، حُذف الملف",
"replace": "استُبدل",
"reorder": "أُعيد ترتيبه"
},
"columns": {
"occurredAt": "الوقت",
"entity": "الكيان",
Expand All @@ -367,7 +374,8 @@
"occurredAt": "سُجِّل",
"metadata": "بيانات وصفية",
"correlationId": "التعديل",
"showEdit": "بقية هذا التعديل"
"showEdit": "بقية هذا التعديل",
"mediaOperation": "الوسائط"
},
"editFilter": {
"title": "تعديل واحد",
Expand Down
10 changes: 9 additions & 1 deletion clients/dashboard/i18n/locales/en.json
Original file line number Diff line number Diff line change
Expand Up @@ -350,6 +350,13 @@
"updated": "Updated",
"deleted": "Deleted"
},
"media": {
"attach": "Attached",
"detach": "Detached",
"detachFileDeleted": "Detached, file deleted",
"replace": "Replaced",
"reorder": "Reordered"
},
"columns": {
"occurredAt": "When",
"entity": "Entity",
Expand All @@ -367,7 +374,8 @@
"occurredAt": "Recorded",
"metadata": "Metadata",
"correlationId": "Edit",
"showEdit": "The rest of this edit"
"showEdit": "The rest of this edit",
"mediaOperation": "Media"
},
"editFilter": {
"title": "One edit",
Expand Down
Loading
Loading