Files

7.1 KiB

Phase 3: the library becomes the truth, the old Hero tables and the switches go

Status (2026-11-18): steps 3a and 3b are BUILT on feature/media-library-phase2 (3b behind a switch that is off by default); step 3c (dropping the old table and the switches) is NOT built and NOT run. Rules from Bryan, relayed by SLS-Main: build it only after phase 2 is verified on test; dropping the old tables only on TEST, with a back-up and rollback plan and a notice to SLS-Main first; never on production without a separate go from Bryan; no PR for the phase-2/3 branch before #22 is merged.

Where phase 2 leaves us

  • The Hero tables (HeroImages, HeroSlides) are the truth. The library tables (MediaAssets, MediaUses) mirror them (write-through, DualWrite) and the library screen can read them (ReadFromLibrary).
  • The library tables do not hold what the Hero needs to publish: the variants of a set (Variants), the set hash of the photo, and the slide crops and sets as columns. So the Hero admin and the public hero still read the Hero tables.

What phase 3 does

Step What Reversible?
3a Expand Add to the library tables what the Hero needs: MediaAssets.SetHash, MediaAssets.Variants (JSON), the photo's crops as columns (not only the default focus), MediaUses.Variants (the use's own set) and its crop columns (today only the JSON in Crops). Additive migration of the Media module. The write-through fills them; a verified backfill copies existing rows. Yes: drop the new columns; nothing reads them yet.
3b Switch The Hero reads and writes its photos and slides through a library store (IMediaLibraryStore, Core interface, implemented by the Media module) instead of HeroImages/HeroSlides: upload, crops, renderer, trash, restore, purge, public mapping, clean-up. Behind a setting (Media:Library:HeroUsesLibrary, default off) with the old code path kept for one release; compare mode first (both paths run, differences are logged). Yes: switch off; the old tables are still complete as long as the write-through to them (the reverse mirror) is on.
3c Contract A separate migration drops HeroImages, the photo columns of HeroSlides and HeroRetiredFiles (or moves it), and the code removes the three switches (CopyOnStartup, DualWrite, ReadFromLibrary), the copier and the mirror. Only from a back-up. TEST only until Bryan gives a separate go.

Public addresses (/media/hero/<setHash>/...), ids and hashes stay as they are in every step; the golden files must not change.

Prerequisites (the gate before 3b and 3c)

  1. Phase 2 verified on test by Bryan: GET media-library/read-check says matches: true, the library screen with ReadFromLibrary=on looks the same, crops per slide work (assumptions 47-50).
  2. A restore point of the test sites taken right before each step (the script of Pi-Main, test-herstelpunt.sh; path recorded in phase2-design.md), plus the row counts and a sample of ten public addresses before and after.
  3. SLS-Main is told before every deploy of 3a, 3b and 3c.

Tests to write before building 3b (can be written now against the current code)

  • The Hero service tests run through an IHeroPhotoStore abstraction twice, once on the Hero tables and once on an in-memory library store, and must give the same answers (upload, same photo twice, crop per slide, trash, restore, purge, clean-up, public mapping, golden files).
  • A migration test on MariaDB for 3a (additive, backfill verified, rollback with Down).
  • A contract test for 3c on MariaDB: after the drop, every Hero endpoint still answers the same (smoke test of the public hero and the admin).

Rollback per step

Step Rollback
3a Down of the Media migration (drops the new columns).
3b HeroUsesLibrary=off; the old tables are complete because the old path was kept in sync.
3c Restore the database dump of the restore point, then deploy the previous release; the media directory is never changed destructively (retired sets stay for the retention time).

Open points for Bryan (assumed until he says otherwise)

  • 3c is a separate release after a quiet period on test (assumption: at least a week), not part of the first rollout of phase 2.
  • The clean-up job of the Hero (HeroMediaCleanup) moves to the library in 3b, so other modules can use the same retention rules.

As built: 3a and 3b (2026-11-18)

3a, expand (Media migration AddHeroPhotoColumns, additive): MediaAssets gets SetHash, Variants (the hero's own JSON), WideFocusX/Y/Zoom, TallFocusX/Y/Zoom; MediaUses gets Variants. The verified copy, the write-through and the read check fill and compare them (a difference in the set or variants shows in the library check).

3b, the switch (Hero migration DropSlideImageForeignKey + switch Media__Library__HeroPhotosInLibrary, default off):

  • The migration drops only the foreign key FK_HeroSlides_HeroImages_ImageId (a slide may point at a photo that is only in MediaAssets). It has a Down that puts it back. The model snapshot is deliberately unchanged. The service layer already checks that a photo exists and is not removed while a slide uses it.
  • With the switch on, the Hero's photo entity is mapped to the library table: rows of MediaAssets with module hero (columns DefaultFocusX/Y/Zoom, a Module column set to hero, a query filter on it). Everything else in the hero (services, renderer, public mapping, clean-up) is unchanged and runs on those rows. The library owns that table and its migrations; the hero's context excludes it from its own.
  • HeroImages stays a complete copy while the switch is on (HeroLegacyImageMirror after every saved change), so switching back loses nothing.
  • Start-up guard: with the switch on, the application refuses to start (clear message in the log) unless the library holds every photo of HeroImages with the same hash, set and variants. So the order is fixed: copy first, library check, then the switch.
  • Public addresses, ids and hashes are unchanged; the golden files are untouched.

Order on test (each step a deploy, SLS-Main tells Bryan):

  1. Deploy with media_library_copy=on (and media_library_dual_write=on): the migrations run and the copy fills the new columns for the existing photos. Open "Controle bibliotheek": it must say that the library matches the hero (it now also compares set and variants).
  2. Deploy with media_library_hero_photos=on. If the guard refuses to start, the log says why; set the switch back to off.
  3. Check the hero admin (upload, crop a slide, save, trash and restore) and the public site; the library check still matches.
  4. Rollback at any time: media_library_hero_photos=off (the application reads HeroImages again, a complete copy). To undo the foreign-key migration too: the Down of DropSlideImageForeignKey. Last resort: the restore point of the test sites.

Step 3c (not built): drop HeroImages and the legacy mirror, remove the three media switches and the copier, make the library table the only home. Needs: Bryan's verification of 3b on test, a notice to SLS-Main with the exact migration, a fresh restore point; test only.