Hero-module: hero beheren vanuit het CMS #17

Merged
Sluijsens merged 48 commits from feature/hero-module into master 2026-11-17 12:55:14 +01:00
2 changed files with 40 additions and 0 deletions
Showing only changes of commit caa7dad6c7 - Show all commits
+12
View File
@@ -107,3 +107,15 @@
**Context**: Units Generation planning; waiting for answers.
---
## Units answered; image library proof
**Timestamp**: 2026-11-16T00:00:00Z
**User Input**: "Bryans antwoorden op de 4 Units-vragen (2026-11-16): alle vier de aanbevelingen. (1) Eén PR voor H1 t/m H6, pas gemerged na Bryans acceptatie op de testhosts. (2) Eerste test-deploy na H1 t/m H4, zodat ASF en SLS kunnen integreren terwijl H5 nog volgt. (3) Bibliotheekproef lokaal op win-x64 en in een linux-arm64-container, de echte Pi bevestigt het bij de eerste test-deploy. (4) Master-Api en beide sites verwijzen vanaf H2 naar de Hero-module, de Slave niet. Maak de unit-documenten en ga door met Functional Design en NFR Requirements; begin met de bibliotheekproef." (relayed by SLP Software - SLS - Main)
**AI Response**: Wrote the three unit documents. Ran the library proof on win-x64 and linux-x64 (container); the arm64 emulation could not be set up (privileged binfmt container refused by the tooling, nothing changed), so arm64 stays to be confirmed on the Pi. Result: Magick.NET-Q8 recommended, NetVips fallback, ImageSharp (paid licence key required to build) and SkiaSharp excluded. Documented in construction/h1-image-pipeline/nfr-requirements/library-proof.md.
**Context**: Construction, NFR Requirements input for H1.
---
@@ -0,0 +1,28 @@
# Image library proof (H1), 2026-11-16
Question: which library behind `IImageProcessor` decodes the widest set of input formats, writes WebP (required) and AVIF (when possible), keeps memory bounded for a 10 MB upload, has a licence that suits a commercial site, and works on win-x64 (IIS production), linux-x64 (CI) and linux-arm64 (Pi test hosts)?
Method: a throw-away console project (not in the repository; sources in the session scratchpad) with the candidates; input is the ASF photo `hero-1.jpg` (2560x1702), converted by Magick to PNG, WebP, GIF, BMP, TIFF and AVIF as decode samples; per library: decode of every sample, crop for `wide` 3:2 and `tall` 4:5 around a focus point, resize to 960/1600 and 640/960 wide, WebP quality 80, metadata stripped, AVIF encode at 960 wide. A 24 MP stress image (6000x4000, 30 MB, noisy) measured peak memory.
## Candidates and findings
| Library | Licence | Result |
|---|---|---|
| **SixLabors.ImageSharp 4.1.3** | Six Labors Split License | **Excluded.** The package fails the build without a paid licence key (`No Six Labors license found ... obtain a licence from sixlabors.com/pricing`). A commercial closed-source site needs the paid licence, and CI would need the key as a secret. No AVIF or HEIC types in the assembly either. |
| **SkiaSharp 4.156.1** | MIT | **Excluded.** Cannot decode TIFF or AVIF (decode returns null), no HEIC, WebP only; on slim Linux images the native library failed to initialise without extra system libraries. |
| **NetVips 3.2.0** (libvips 8.18.7) | wrapper MIT; native `NetVips.Native` LGPL-3.0-or-later | Works on win-x64 and linux-x64. Decodes PNG, WebP, GIF, TIFF, AVIF, JPEG; **no BMP** (needs ImageMagick loader). Writes WebP and AVIF (`heifsave`). Fast (about 330 to 490 ms for four WebP variants). Peak memory 303 MB for the 24 MP stress image. Native libraries for linux-arm64 are in the package (`libvips.so.42`, 18 MB) but could not be executed here. HEIC is unverified (no sample). |
| **Magick.NET-Q8-AnyCPU 15.1.0** (ImageMagick) | wrapper Apache-2.0 | Works on win-x64 and linux-x64. Reports readable and writable: AVIF, BMP, GIF, JXL, TIFF, WebP; **HEIC and HEIF readable**. Decodes every sample (PNG, WebP, GIF, BMP, TIFF, AVIF, JPEG). Writes WebP and AVIF. Slower (about 0.7 to 1.3 s for four WebP variants, 1.5 to 2 times NetVips), but peak memory only 128 MB for the 24 MP stress image. A native arm64 build is in the package (`Magick.Native-Q8-arm64.dll.so`, 35 MB), not executed here. Has resource limits (`ResourceLimits`: width, height, area, memory, time) that fit decompression-bomb protection. |
Output equality: WebP at quality 80 gave the same sizes in NetVips and Magick.NET (wide 960 about 38 KB, wide 1600 about 74 KB, tall 640 about 37 KB, tall 960 about 64 KB), against 220 to 440 KB for the ASF JPEGs today. AVIF at 960 wide: about 22 to 23 KB.
## What could not be verified
1. **linux-arm64 (Pi) was not executed.** Running an arm64 container on this machine needs an emulator registration (a privileged binfmt container) that the tooling refused; no change was made. The packages do contain native arm64 libraries for both candidates. The real Pi confirms at the first test deploy (agreed). To make that quick the host will run an image-library self-test at start-up (decode and encode a tiny embedded image in every supported format; log the capabilities; refuse uploads when it fails; public reads unaffected).
2. **HEIC** was verified only as a declared capability of Magick.NET (`Heic:r`), not with a real HEIC file.
3. The `AnyCPU` Magick package carries natives for several platforms; a self-contained win-x64 publish keeps only the matching one (to be checked in the H1 publish test).
## Recommendation
**Magick.NET-Q8 (Apache-2.0) behind `IImageProcessor`**: the widest input list (incl. BMP, TIFF, HEIC read, AVIF read and write), WebP and AVIF output, bounded memory with built-in resource limits, a licence without keys or LGPL obligations, native builds for all three platforms. NetVips stays the documented fallback (faster, lower licence friction on the wrapper, but no BMP and LGPL natives) and the interface makes switching small. ImageSharp and SkiaSharp are out.
Residual risks: ImageMagick has a history of CVEs, so the package is kept current and covered by the CI vulnerability scan (SECURITY-10); only the allow-listed formats are decoded (our own signature check first, then the library with an explicit format); the process gets pixel, memory and time limits.