Mediabibliotheek: gebruiksdefinities per module (gestapeld op #23) #24
@@ -6,7 +6,7 @@ Kept while Bryan is away (2026-11-17): no questions to him, a most probable assu
|
||||
|---|---|---|---|---|
|
||||
| 1 | Which **uses** (places and ratios) exist? | Hero `wide` (3:2) and `tall` (2:3), ASF shoot-page **mosaic** tiles (a small fixed set of ratios per page, to be listed by the ASF session), **masonry** (natural ratio, no crop), **thumb** (library thumbnails, 1:1 or natural). A use is `(module, place, ratio set)`. | Other ratios only add rows to the use definitions; a free-form ratio per tile would need a ratio editor and more variants per photo. | Application design section 4 (`MediaUseDefinition`) |
|
||||
| 2 | **Several formats/variants per photo**: who decides the set? | The **use** decides the ratios and widths (as `VariantPlanner` does for Hero); the library never cuts a fixed set per photo. Formats stay WebP and AVIF as today. | A fixed set per photo costs more disk and CPU on the Pi and cuts variants nobody uses. | `VariantPlanner`, application design section 4 |
|
||||
| 3 | The **7-day automatic clean-up** of unattached Hero images until the library is built. | Switch it off behind a setting (`Media:AutoCleanupUnattached`, default `true` until the library screen exists, then default `false`), so nothing is lost silently once the library can show and delete photos. Retired-file removal (after a replaced set) stays: that is housekeeping of generated files, not a person's photos. | Keep it on until phase C; or switch off now (risk: unused uploads pile up with no screen to remove them). | `HeroMediaCleanup`, `MediaOptions` |
|
||||
| 3 | The **7-day automatic clean-up** of unattached Hero images until the library is built. | **Built (2026-11-17, safe: default unchanged)**: the setting `Media:AutoCleanupUnattached` exists, default `true` (today's behaviour); set `Media__AutoCleanupUnattached=false` per host to keep every upload. Plan: switch it off (default `false`) once the library screen and delete are accepted by Bryan. Switch it off behind a setting (`Media:AutoCleanupUnattached`, default `true` until the library screen exists, then default `false`), so nothing is lost silently once the library can show and delete photos. Retired-file removal (after a replaced set) stays: that is housekeeping of generated files, not a person's photos. | Keep it on until phase C; or switch off now (risk: unused uploads pile up with no screen to remove them). | `HeroMediaCleanup`, `MediaOptions` |
|
||||
| 4 | **Rights per module**: who may see, use and delete which photos? | One shared library for Owner and Administrator (like Hero and Offerings). No per-module visibility yet. | Per-module visibility needs an owner field on a photo and a filter; the contract has room for it (`ModuleKey` on a use). | `[Authorize(Policy = "AdminOnly")]`, `MediaUse.Module` |
|
||||
| 5 | **Public addresses**: per module (`/media/<module>/...`) or a shared path? | Keep `/media/{area}/{setHash}/{name}`; `area` stays the module (`hero`; a gallery would use `gallery`). The set hash still comes from the original's hash plus the crops of that **use**. A photo used in two modules is two sets (two addresses), cached separately. | A shared path would change addresses and golden files: not allowed without alignment. | `MediaPaths`, `MediaEndpoint` |
|
||||
| 6 | **Usage register**: do modules report, or does the library keep it centrally? | Modules report: `IMediaUsageProvider` per module answers "where is this photo used" and "detach this photo" from the module's own data. Computed, never copied, so it cannot go stale. The library warns when a module has no provider. | A central register table keeps the answer fast but must be kept in step on every module save (risk of drift); can be added later as a cache. | Application design section 3, `IMediaUsageProvider` |
|
||||
@@ -28,3 +28,4 @@ Kept while Bryan is away (2026-11-17): no questions to him, a most probable assu
|
||||
| 22 | **Select all** and ranges with photos that cannot be selected (in use during a clean-up). | They are skipped by "select all" and by shift-ranges; the header box shows "some" when only part is selected. | Include them but refuse at confirmation. | `PhotoSelectionList`, `selection.ts` |
|
||||
| 23 | Where does Hero **list all photos** (performance)? | In memory, newest first, as the rest of the Hero repository does (a few dozen photos; the MySQL provider has limits with Guid lists). Paging comes with the screen when the count grows. | Server-side paging by `CreatedAt` (needs an index). | `HeroRepository.GetAllImagesReadOnlyAsync` |
|
||||
| 24 | **Tile ratios of the ASF mosaic** (assumption 1). | **Answered by the ASF session (2026-11-17, from its code)**: the mosaic shows at most 4 tiles per shoot page, from 2 photos up (layouts for 2, 3, 4). The tile shape is fixed per page by the photo count and order, not chosen per photo: **large** (photo 1) 2x2, desktop about 1:1 (max about 656x632), phone 4:3; **wide** (photo 2 with 3 or 4 photos) 2x1, desktop about 2.2:1 (max about 656x300), phone 3:2; **small** (photos 3 and 4 with 4 photos) 1x1, about 1.04:1 (max about 312x300), phone 1:1. With 2 photos: two large side by side. All object-fit cover (a crop). Widths: large and wide up to about 656 px, small about 312 px; phone half width about 175-300, full width about 350-600; retina variants 480, 640, 960, 1280. **Masonry** (portfolio): natural ratio only, no crop (rounding below half a row of 1/40 of the column width); 1, 2 or 3 columns, column width up to about 427 px; thumb now 800 px wide with the height following the ratio, variants about 480 and 800; the lightbox uses a separate `full`. Used in the design as uses `mosaic-large`, `mosaic-wide`, `mosaic-small` (each with a focus point and a desktop and phone shape) and `masonry` (no crop). | Each answer only adds use definitions. A ratio per photo (not per tile shape) would need a ratio editor. | Application design section 4 |
|
||||
| 25 | **Use definitions in code** (built 2026-11-17, pure data, nothing consumes them yet). | `MediaUseDefinition` (ratios with widths, or natural) and `GalleryUses` for the ASF needs: `mosaic-large` (`tilelarge` 1:1, `tilelargem` 4:3), `mosaic-wide` (`tilewide` 11:5, `tilewidem` 3:2), `mosaic-small` (`tilesmall` 26:25, `tilesmallm` 1:1), `masonry` (`natural`, no crop). Ratio names are letters only (2 to 10) to fit the address allow-list, so a phone shape is a name with an `m` suffix. Widths: large and wide 480, 640, 960, 1280 (retina set from the ASF answer); small 312, 480, 640; masonry 480 and 800. The set hash uses the shared `MediaPaths.SetHash` formula (a test shows it equals the Hero's). Hero's own `wide` (3:2) and `tall` (4:5, not the 2:3 the first design sketch said) stay as built in `VariantPlanner`. | Other widths or ratio values change only the definitions; the ASF `full` (lightbox) variant is not defined yet (it is the full-frame preview ratio). | `Core/Media/Library/MediaUseDefinition.cs` |
|
||||
|
||||
+1
-1
@@ -26,7 +26,7 @@ De admin toont alleen een badge Live of Niet live.
|
||||
| Instelling | Betekenis |
|
||||
|---|---|
|
||||
| `Media__Directory` | De map voor de afbeeldingen, **buiten de release** en buiten de webroot. Zonder deze instelling (of als de map niet beschrijfbaar is) staan uploads uit; bestaande bestanden en de publieke hero blijven werken. Niet in een committed appsettings-bestand. |
|
||||
| `Media__MaxUploadBytes` (10 MB), `Media__MaxPixels` (64 miljoen), `Media__MaxParallelJobs` (2), `Media__DecodeTimeoutSeconds` (20), `Media__MaxTotalBytes` (2 GB), `Media__RetentionDays` (7) | Grenzen en bewaartijd; standaardwaarden zijn bedoeld om te blijven. |
|
||||
| `Media__MaxUploadBytes` (10 MB), `Media__MaxPixels` (64 miljoen), `Media__MaxParallelJobs` (2), `Media__DecodeTimeoutSeconds` (20), `Media__MaxTotalBytes` (2 GB), `Media__RetentionDays` (7), `Media__AutoCleanupUnattached` (standaard `true`; `false` bewaart ongebruikte uploads tot iemand ze verwijdert, voor de mediabibliotheek) | Grenzen en bewaartijd; standaardwaarden zijn bedoeld om te blijven. |
|
||||
| `Hero__TextOnlyRegion` | `true` voor een site waarvan de hero geen afbeeldingen heeft (SLP Software; staat in de committed instellingen van die site): een hero zonder slides wordt dan als tekst (titelregels, lead, knoppen) in de eerste HTML geschreven. Uit (standaard, ook voor ASF): een hero zonder slides laat de pagina ongemoeid. |
|
||||
| `Hero__TitlePrefix` | Merktekst die in de tekst-only-regio als eerste, visueel te verbergen deel van de h1 wordt geschreven (`<span class="cms-hero-title-prefix">`), zodat crawlers en schermlezers de volledige titel lezen. SLP Software: `"SLP Software: "` (committed instelling); leeg (standaard, ook ASF) schrijft niets. De site verbergt de klasse zelf visueel. |
|
||||
| `Media__RenderSetTimeoutSeconds` (600), `Media__StripTimeoutSeconds` (60) | De tijd die het knippen van alle varianten van één foto in de achtergrond mag duren, en het verwijderen van metadata bij een upload. Ruim gekozen: een grote foto op een Raspberry Pi kost minuten. |
|
||||
|
||||
@@ -0,0 +1,72 @@
|
||||
using FluentAssertions;
|
||||
using SlpModularCms.Core.Media;
|
||||
using SlpModularCms.Core.Media.Library;
|
||||
using Xunit;
|
||||
|
||||
namespace SlpModularCms.Core.Tests.Media;
|
||||
|
||||
public class MediaUseDefinitionTests
|
||||
{
|
||||
private const string Sha = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
|
||||
|
||||
[Fact]
|
||||
public void Every_ratio_name_and_width_fits_the_media_address_scheme()
|
||||
{
|
||||
foreach (var use in GalleryUses.All)
|
||||
{
|
||||
var plans = use.PlansFor(4000, 3000);
|
||||
var specs = VariantPlanner.Plan(4000, 3000, plans, new HashSet<ImageFormat> { ImageFormat.WebP });
|
||||
specs.Should().NotBeEmpty(use.Key);
|
||||
foreach (var spec in specs)
|
||||
{
|
||||
var name = MediaPaths.FileName(spec.Ratio.Name, spec.Width, spec.Format);
|
||||
MediaPaths.TryParse($"{use.Module}/{use.SetHash(Sha)}/{name}", out _).Should().BeTrue($"{use.Key}: {name}");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void The_keys_are_unique() => GalleryUses.All.Select(u => u.Key).Should().OnlyHaveUniqueItems();
|
||||
|
||||
[Fact]
|
||||
public void A_mosaic_use_has_a_desktop_and_a_phone_shape_and_a_masonry_use_has_none_of_its_own()
|
||||
{
|
||||
GalleryUses.MosaicLarge.Ratios.Select(r => r.Name).Should().Equal("tilelarge", "tilelargem");
|
||||
GalleryUses.Masonry.Natural.Should().BeTrue();
|
||||
GalleryUses.Masonry.PlansFor(3000, 2000).Should().ContainSingle().Which.Ratio.Should().Be(new Ratio("natural", 3000, 2000));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void A_natural_use_keeps_the_photos_own_shape_without_a_crop()
|
||||
{
|
||||
var spec = VariantPlanner.Plan(3000, 2000, GalleryUses.Masonry.PlansFor(3000, 2000), new HashSet<ImageFormat> { ImageFormat.WebP })
|
||||
.Single(s => s.Width == 800);
|
||||
|
||||
(spec.Crop.Width, spec.Crop.Height).Should().Be((3000, 2000));
|
||||
spec.Height.Should().Be(533);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void The_crop_of_a_use_changes_its_set_hash_but_not_the_set_hash_of_another_use()
|
||||
{
|
||||
var focus = new Dictionary<string, FocusSetting> { ["tilelarge"] = new(0.2, 0.3, 1.5) };
|
||||
|
||||
GalleryUses.MosaicLarge.SetHash(Sha, focus).Should().NotBe(GalleryUses.MosaicLarge.SetHash(Sha));
|
||||
GalleryUses.MosaicWide.SetHash(Sha, focus).Should().Be(GalleryUses.MosaicWide.SetHash(Sha));
|
||||
GalleryUses.MosaicLarge.SetHash(Sha, focus).Should().Be(GalleryUses.MosaicLarge.SetHash(Sha, focus));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void A_natural_use_does_not_depend_on_a_crop()
|
||||
=> GalleryUses.Masonry.SetHash(Sha, new Dictionary<string, FocusSetting> { ["natural"] = new(0.1, 0.1, 2) }).Should().Be(GalleryUses.Masonry.SetHash(Sha));
|
||||
|
||||
[Fact]
|
||||
public void The_set_hash_formula_is_the_one_the_hero_uses_today()
|
||||
{
|
||||
// Same inputs through the shared function the hero calls: the library does not invent a second scheme.
|
||||
var hero = new MediaUseDefinition("hero", "hero", [new("wide", 3, 2, [640]), new("tall", 4, 5, [480])]);
|
||||
var focus = new Dictionary<string, FocusSetting> { ["wide"] = new(0.3, 0.4, 1.2) };
|
||||
|
||||
hero.SetHash(Sha, focus).Should().Be(MediaPaths.SetHash(Sha, [("wide", new FocusSetting(0.3, 0.4, 1.2)), ("tall", FocusSetting.Centre)]));
|
||||
}
|
||||
}
|
||||
@@ -65,6 +65,14 @@ public sealed class MediaOptions
|
||||
public long MaxTotalBytes { get; set; } = 2L * 1024 * 1024 * 1024;
|
||||
|
||||
public int RetentionDays { get; set; } = 7;
|
||||
|
||||
/// <summary>
|
||||
/// Whether photos that were uploaded but never used are removed automatically after <see cref="RetentionDays"/>.
|
||||
/// The media library keeps everything until a person removes it, so set this to <c>false</c> (<c>Media__AutoCleanupUnattached=false</c>)
|
||||
/// once the library can show and delete photos. Retired files of photos a person removed stay housekeeping either way.
|
||||
/// Default <c>true</c> keeps today's behaviour (assumption 3 of the media-library list).
|
||||
/// </summary>
|
||||
public bool AutoCleanupUnattached { get; set; } = true;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
|
||||
@@ -0,0 +1,72 @@
|
||||
namespace SlpModularCms.Core.Media.Library;
|
||||
|
||||
/// <summary>One ratio of a use: its name (part of the file name), its shape and the widths cut for it.</summary>
|
||||
public sealed record UseRatio(string Name, int Numerator, int Denominator, IReadOnlyList<int> Widths);
|
||||
|
||||
/// <summary>
|
||||
/// What a USE of a photo needs (a place on a page, not the photo itself): the ratios with their widths, or the natural
|
||||
/// shape of the photo without a crop. A photo can have several uses; each use has its own crop (focus per ratio) and so
|
||||
/// its own set. Pure data, no behaviour that moves anything.
|
||||
/// </summary>
|
||||
/// <param name="Key">For example <c>mosaic-large</c>; unique.</param>
|
||||
/// <param name="Module">The module whose pages show it (also its media area).</param>
|
||||
/// <param name="Ratios">Empty for a natural-ratio use.</param>
|
||||
/// <param name="Natural">The photo is shown in its own shape: no crop, one ratio taken from the photo itself.</param>
|
||||
public sealed record MediaUseDefinition(string Key, string Module, IReadOnlyList<UseRatio> Ratios, bool Natural = false)
|
||||
{
|
||||
public const string NaturalRatioName = "natural";
|
||||
|
||||
/// <summary>The ratio plans for a photo, given the focus per ratio name (centre when none is given).</summary>
|
||||
public IReadOnlyList<RatioPlan> PlansFor(int sourceWidth, int sourceHeight, IReadOnlyDictionary<string, FocusSetting>? focus = null)
|
||||
{
|
||||
if (Natural)
|
||||
{
|
||||
var widths = Ratios.Count > 0 ? Ratios[0].Widths : [];
|
||||
return [new RatioPlan(new Ratio(NaturalRatioName, sourceWidth, sourceHeight), FocusSetting.Centre, widths)];
|
||||
}
|
||||
|
||||
return Ratios
|
||||
.Select(r => new RatioPlan(new Ratio(r.Name, r.Numerator, r.Denominator), focus is not null && focus.TryGetValue(r.Name, out var f) ? f : FocusSetting.Centre, r.Widths))
|
||||
.ToList();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The set hash of this use for a photo: the existing formula over the photo's hash and the crops of this use, so a
|
||||
/// photo gets the same address for the same use and crops, and another use never shares a set by accident.
|
||||
/// A natural-ratio use has no crop, so its set depends on the photo alone (and the use key).
|
||||
/// </summary>
|
||||
public string SetHash(string originalSha256, IReadOnlyDictionary<string, FocusSetting>? focus = null)
|
||||
{
|
||||
var crops = Natural
|
||||
? [(NaturalRatioName, FocusSetting.Centre)]
|
||||
: Ratios.Select(r => (r.Name, focus is not null && focus.TryGetValue(r.Name, out var f) ? f : FocusSetting.Centre)).ToList();
|
||||
return MediaPaths.SetHash(originalSha256, crops);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The uses of the gallery that the Andrea Slop Fotografie site needs (answer of the ASF session, 2026-11-17): the
|
||||
/// mosaic tiles (a shape fixed per page by the number and order of the photos, a desktop and a phone shape each) and the
|
||||
/// masonry portfolio (natural shape). Ratio names are letters only, 2 to 10 long, so they fit the address allow-list.
|
||||
/// </summary>
|
||||
public static class GalleryUses
|
||||
{
|
||||
public const string Module = "gallery";
|
||||
|
||||
private static readonly int[] Large = [480, 640, 960, 1280];
|
||||
private static readonly int[] Small = [312, 480, 640];
|
||||
|
||||
/// <summary>Photo 1 of 2 to 4: about 1:1 on desktop (max about 656 wide), 4:3 on a phone.</summary>
|
||||
public static readonly MediaUseDefinition MosaicLarge = new("mosaic-large", Module, [new("tilelarge", 1, 1, Large), new("tilelargem", 4, 3, Large)]);
|
||||
|
||||
/// <summary>Photo 2 of 3 or 4: about 2.2:1 on desktop, 3:2 on a phone.</summary>
|
||||
public static readonly MediaUseDefinition MosaicWide = new("mosaic-wide", Module, [new("tilewide", 11, 5, Large), new("tilewidem", 3, 2, Large)]);
|
||||
|
||||
/// <summary>Photos 3 and 4 of 4: about 1.04:1 on desktop (max about 312 wide), 1:1 on a phone.</summary>
|
||||
public static readonly MediaUseDefinition MosaicSmall = new("mosaic-small", Module, [new("tilesmall", 26, 25, Small), new("tilesmallm", 1, 1, Small)]);
|
||||
|
||||
/// <summary>The portfolio: the photo's own shape, no crop; thumbnail widths about 480 and 800.</summary>
|
||||
public static readonly MediaUseDefinition Masonry = new("masonry", Module, [new(MediaUseDefinition.NaturalRatioName, 1, 1, [480, 800])], Natural: true);
|
||||
|
||||
public static IReadOnlyList<MediaUseDefinition> All { get; } = [MosaicLarge, MosaicWide, MosaicSmall, Masonry];
|
||||
}
|
||||
@@ -412,6 +412,37 @@ public class HeroMediaCleanupTests
|
||||
again.Variants.Should().OnlyContain(v => v.Url.Contains(set));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task AnImageNobodyUsed_IsKept_WhenAutomaticCleanupIsOff()
|
||||
{
|
||||
using var rig = new HeroTestRig();
|
||||
rig.Media.AutoCleanupUnattached = false;
|
||||
await rig.Upload(HeroTestRig.Photo());
|
||||
|
||||
rig.Time.Now = rig.Time.Now.AddDays(400);
|
||||
await rig.Cleanup.RunOnceAsync(CancellationToken.None);
|
||||
rig.Time.Now = rig.Time.Now.AddDays(400);
|
||||
await rig.Cleanup.RunOnceAsync(CancellationToken.None);
|
||||
|
||||
rig.Db.HeroImages.Should().HaveCount(1);
|
||||
(await rig.Store.ListSetsAsync("hero", CancellationToken.None)).Should().HaveCount(1);
|
||||
rig.Db.HeroRetiredFiles.Should().BeEmpty();
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task APhotoAPersonRemoved_StillLeavesAfterTheRetentionTime_WhenAutomaticCleanupIsOff()
|
||||
{
|
||||
using var rig = new HeroTestRig();
|
||||
rig.Media.AutoCleanupUnattached = false;
|
||||
var (set, original) = await RetireAnImage(rig);
|
||||
|
||||
rig.Time.Now = rig.Time.Now.AddDays(8);
|
||||
await rig.Cleanup.RunOnceAsync(CancellationToken.None);
|
||||
|
||||
(await rig.Store.ListSetsAsync("hero", CancellationToken.None)).Should().NotContain(s => s.SetHash == set);
|
||||
(await rig.Store.ExistsAsync(original, CancellationToken.None)).Should().BeFalse();
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task AnImageNobodyUsed_IsRetiredAndRemoved_AfterTheRetentionTime()
|
||||
{
|
||||
|
||||
@@ -29,7 +29,11 @@ public class HeroMediaCleanup(
|
||||
var removed = 0;
|
||||
|
||||
// 1. Images that were uploaded but never used by a slide: retire them (their files go on a later run).
|
||||
foreach (var image in await repository.GetUnattachedImagesCreatedBeforeAsync(cutoff, cancellationToken))
|
||||
// Skipped when the media library keeps every upload until a person removes it (Media:AutoCleanupUnattached = false).
|
||||
var unattached = options.Value.AutoCleanupUnattached
|
||||
? await repository.GetUnattachedImagesCreatedBeforeAsync(cutoff, cancellationToken)
|
||||
: [];
|
||||
foreach (var image in unattached)
|
||||
{
|
||||
repository.AddRetired(new HeroRetiredFile { Id = Guid.NewGuid(), Kind = "set", Key = image.SetHash, RetiredAt = cutoff.AddSeconds(-1) });
|
||||
repository.AddRetired(new HeroRetiredFile { Id = Guid.NewGuid(), Kind = "original", Key = image.OriginalKey, RetiredAt = cutoff.AddSeconds(-1) });
|
||||
|
||||
Reference in New Issue
Block a user