H1: beeldpijplijn in Core.Media (Magick.NET achter IImageProcessor), pure functies met property-tests, uploadwacht

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-16 15:18:02 +01:00
co-authored by Claude Sonnet 5.5
parent 259d48bd9c
commit 3a50c9750e
19 changed files with 1784 additions and 1 deletions
@@ -0,0 +1,312 @@
using ImageMagick;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using SlpModularCms.Core.Media;
namespace SlpModularCms.Core.Media.Magick;
/// <summary>
/// <see cref="IImageProcessor"/> on Magick.NET (Q8). The format is always passed explicitly (it was decided from the
/// signature by the caller), only the first frame is read, the orientation is applied before cropping, and every output
/// is stripped of metadata after the colours are converted to sRGB. The resource limits of ImageMagick are process
/// wide and are set once from <see cref="MediaOptions"/>.
/// </summary>
public sealed class MagickImageProcessor : IImageProcessor
{
private static readonly object LimitsLock = new();
private static bool _limitsSet;
private readonly MediaOptions _options;
private readonly ILogger<MagickImageProcessor> _logger;
public MagickImageProcessor(IOptions<MediaOptions> options, ILogger<MagickImageProcessor> logger)
{
_options = options.Value;
_logger = logger;
SetLimits(_options);
SupportedInput = DetectInput();
SupportedOutput = DetectOutput();
}
public IReadOnlySet<ImageFormat> SupportedInput { get; }
public IReadOnlySet<ImageFormat> SupportedOutput { get; }
public Task<ImageInfo> InspectAsync(ReadOnlyMemory<byte> data, ImageFormat declared, CancellationToken cancellationToken)
=> RunAsync(() => Inspect(data, declared), cancellationToken);
public Task<RenderedImage> RenderAsync(ReadOnlyMemory<byte> data, ImageFormat declared, VariantSpec variant, CancellationToken cancellationToken)
=> RunAsync(() => Render(data, declared, variant), cancellationToken);
public Task<byte[]?> StripMetadataAsync(ReadOnlyMemory<byte> data, ImageFormat declared, CancellationToken cancellationToken)
=> RunAsync(() => StripMetadata(data, declared), cancellationToken);
public async Task SelfTestAsync(CancellationToken cancellationToken)
{
await RunAsync(() =>
{
foreach (var format in SupportedOutput)
{
using var image = new MagickImage(MagickColors.CornflowerBlue, 32, 32);
using var stream = new MemoryStream();
image.Quality = 80;
image.Write(stream, ToMagick(format));
var bytes = stream.ToArray();
var detected = ImageSignature.Detect(bytes);
if (detected != format && !(format == ImageFormat.Avif && detected == ImageFormat.Heic))
{
throw new InvalidOperationException($"The self-test wrote {format} but the signature says {detected}.");
}
using var back = new MagickImage(bytes, new MagickReadSettings { Format = ToMagick(format) });
if (back.Width != 32 || back.Height != 32)
{
throw new InvalidOperationException($"The self-test could not read back {format}.");
}
}
return true;
}, cancellationToken);
_logger.LogInformation(
"Image library Magick.NET self-test passed. Input: {Input}. Output: {Output}.",
string.Join(",", SupportedInput.Order()),
string.Join(",", SupportedOutput.Order()));
}
// ----- work done on a pool thread with a time limit (the native limit below stops a runaway decode) ------------
private async Task<T> RunAsync<T>(Func<T> work, CancellationToken cancellationToken)
{
try
{
return await Task.Run(work, cancellationToken)
.WaitAsync(TimeSpan.FromSeconds(Math.Max(1, _options.DecodeTimeoutSeconds)), cancellationToken);
}
catch (TimeoutException)
{
throw new ImageRejectedException(ImageRejection.Timeout, "Processing the image took too long.");
}
catch (ImageRejectedException)
{
throw;
}
catch (MagickResourceLimitErrorException exception)
{
_logger.LogWarning("Image refused by a resource limit: {Message}", Shorten(exception.Message));
throw new ImageRejectedException(ImageRejection.TooManyPixels, "The image exceeds a processing limit.");
}
catch (MagickException exception)
{
_logger.LogInformation("Image could not be decoded: {Message}", Shorten(exception.Message));
throw new ImageRejectedException(ImageRejection.Corrupt, "The image could not be decoded.");
}
}
private static string Shorten(string message) => message.Length <= 160 ? message : message[..160];
private ImageInfo Inspect(ReadOnlyMemory<byte> data, ImageFormat declared)
{
var settings = new MagickReadSettings { Format = ToMagick(declared) };
using var image = new MagickImage();
image.Ping(data.Span, settings);
var width = (int)image.Width;
var height = (int)image.Height;
if (image.Orientation is Orientation.LeftTop or Orientation.RightTop or Orientation.RightBottom or Orientation.LeftBottom)
{
(width, height) = (height, width);
}
var frames = 1;
try
{
frames = Math.Min(MagickImageInfo.ReadCollection(data.ToArray(), settings).Count(), 10_000);
}
catch (MagickException)
{
// A single readable frame is enough; the count is informational.
}
var hasMetadata = image.GetExifProfile() is not null || image.GetXmpProfile() is not null || image.GetIptcProfile() is not null;
return new ImageInfo(declared, width, height, Math.Max(1, frames), hasMetadata);
}
private RenderedImage Render(ReadOnlyMemory<byte> data, ImageFormat declared, VariantSpec variant)
{
var settings = new MagickReadSettings { Format = ToMagick(declared), FrameIndex = 0, FrameCount = 1 };
using var image = ReadStrict(data, settings);
image.AutoOrient();
var crop = variant.Crop;
if (crop.X < 0 || crop.Y < 0 || crop.Width < 1 || crop.Height < 1
|| crop.X + crop.Width > image.Width || crop.Y + crop.Height > image.Height)
{
throw new ImageRejectedException(ImageRejection.Corrupt, "The planned crop does not fit the decoded image.");
}
image.Crop(new MagickGeometry(crop.X, crop.Y, (uint)crop.Width, (uint)crop.Height));
image.ResetPage();
image.Resize(new MagickGeometry((uint)variant.Width, (uint)variant.Height) { IgnoreAspectRatio = true });
ToSrgb(image);
image.Strip();
image.Quality = (uint)variant.Quality;
var format = ToMagick(variant.Format);
if (variant.Format == ImageFormat.Avif)
{
image.Settings.SetDefine(MagickFormat.Avif, "speed", "6");
}
using var stream = new MemoryStream();
image.Write(stream, format);
return new RenderedImage(stream.ToArray(), (int)image.Width, (int)image.Height, variant.Format);
}
private static byte[]? StripMetadata(ReadOnlyMemory<byte> data, ImageFormat declared)
{
var settings = new MagickReadSettings { Format = ToMagick(declared), FrameIndex = 0, FrameCount = 1 };
using var probe = new MagickImage();
probe.Ping(data.Span, settings);
if (probe.GetExifProfile() is null && probe.GetXmpProfile() is null && probe.GetIptcProfile() is null)
{
return null;
}
using var image = ReadStrict(data, settings);
var colour = image.GetColorProfile();
var quality = image.Quality;
image.Strip();
if (colour is not null)
{
image.SetProfile(colour);
}
if (declared is ImageFormat.Jpeg or ImageFormat.WebP or ImageFormat.Avif or ImageFormat.Heic)
{
image.Quality = Math.Max(quality, 92u);
}
using var stream = new MemoryStream();
image.Write(stream, declared == ImageFormat.Heic ? MagickFormat.Jpeg : ToMagick(declared));
return stream.ToArray();
}
// Warnings that mean "the file is damaged": the library would hand back a partly decoded picture, but a truncated
// upload must not become a published image.
private static readonly System.Text.RegularExpressions.Regex DamageWarning = new(
"premature end|truncat|unexpected end|insufficient image data|corrupt|not enough|bad (?:huffman|data)",
System.Text.RegularExpressions.RegexOptions.IgnoreCase | System.Text.RegularExpressions.RegexOptions.CultureInvariant);
private static MagickImage ReadStrict(ReadOnlyMemory<byte> data, MagickReadSettings settings)
{
var image = new MagickImage();
string? damage = null;
image.Warning += (_, e) =>
{
if (damage is null && DamageWarning.IsMatch(e.Message))
{
damage = e.Message;
}
};
try
{
image.Read(data.Span, settings);
}
catch
{
image.Dispose();
throw;
}
if (damage is not null)
{
image.Dispose();
throw new ImageRejectedException(ImageRejection.Corrupt, "The image is damaged or incomplete.");
}
return image;
}
private static void ToSrgb(MagickImage image)
{
try
{
if (image.ColorSpace == ColorSpace.CMYK || image.GetColorProfile() is not null)
{
image.TransformColorSpace(ColorProfiles.SRGB);
}
}
catch (MagickException)
{
// An unusual profile: keep the pixels, the metadata is stripped afterwards anyway.
}
}
// ----- capabilities and limits ---------------------------------------------------------------------------------
private static void SetLimits(MediaOptions options)
{
lock (LimitsLock)
{
if (_limitsSet)
{
return;
}
ResourceLimits.Area = (ulong)Math.Max(1, options.MaxPixels);
ResourceLimits.Width = (ulong)Math.Max(1, options.MaxSide);
ResourceLimits.Height = (ulong)Math.Max(1, options.MaxSide);
ResourceLimits.Memory = 1UL * 1024 * 1024 * 1024;
ResourceLimits.Time = (ulong)Math.Max(1, options.DecodeTimeoutSeconds);
_limitsSet = true;
}
}
private static HashSet<ImageFormat> DetectInput()
{
var wanted = new Dictionary<MagickFormat, ImageFormat>
{
[MagickFormat.Jpeg] = ImageFormat.Jpeg,
[MagickFormat.Png] = ImageFormat.Png,
[MagickFormat.Gif] = ImageFormat.Gif,
[MagickFormat.Bmp] = ImageFormat.Bmp,
[MagickFormat.Tiff] = ImageFormat.Tiff,
[MagickFormat.WebP] = ImageFormat.WebP,
[MagickFormat.Avif] = ImageFormat.Avif,
[MagickFormat.Heic] = ImageFormat.Heic,
};
var supported = MagickNET.SupportedFormats.Where(f => f.SupportsReading).Select(f => f.Format).ToHashSet();
return wanted.Where(w => supported.Contains(w.Key) || (w.Key == MagickFormat.Jpeg && supported.Contains(MagickFormat.Jpg)))
.Select(w => w.Value).ToHashSet();
}
private static HashSet<ImageFormat> DetectOutput()
{
var writable = MagickNET.SupportedFormats.Where(f => f.SupportsWriting).Select(f => f.Format).ToHashSet();
var result = new HashSet<ImageFormat> { ImageFormat.Jpeg };
if (writable.Contains(MagickFormat.WebP))
{
result.Add(ImageFormat.WebP);
}
if (writable.Contains(MagickFormat.Avif))
{
result.Add(ImageFormat.Avif);
}
return result;
}
private static MagickFormat ToMagick(ImageFormat format) => format switch
{
ImageFormat.Jpeg => MagickFormat.Jpeg,
ImageFormat.Png => MagickFormat.Png,
ImageFormat.Gif => MagickFormat.Gif,
ImageFormat.Bmp => MagickFormat.Bmp,
ImageFormat.Tiff => MagickFormat.Tiff,
ImageFormat.WebP => MagickFormat.WebP,
ImageFormat.Avif => MagickFormat.Avif,
ImageFormat.Heic => MagickFormat.Heic,
_ => throw new ArgumentOutOfRangeException(nameof(format), format, "Not an image format the processor knows."),
};
}
@@ -0,0 +1,15 @@
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;
using SlpModularCms.Core.Media;
namespace SlpModularCms.Core.Media.Magick;
public static class MagickServiceCollectionExtensions
{
/// <summary>Registers the Magick.NET implementation of <see cref="IImageProcessor"/> (stateless, thread-safe).</summary>
public static IServiceCollection AddMagickImageProcessor(this IServiceCollection services)
{
services.TryAddSingleton<IImageProcessor, MagickImageProcessor>();
return services;
}
}
@@ -0,0 +1,20 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
<!-- The image library behind IImageProcessor (Apache-2.0). Chosen in the library proof of the hero-module feature
(aidlc-docs/features/hero-module/construction/h1-image-pipeline/nfr-requirements/library-proof.md). Kept in its own
project so hosts that never process images (the slave) do not carry the 35 MB native library. -->
<PackageReference Include="Magick.NET-Q8-AnyCPU" Version="15.1.0" />
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\SlpModularCms.Core\SlpModularCms.Core.csproj" />
</ItemGroup>
</Project>