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>
@@ -0,0 +1,235 @@
using FluentAssertions;
using ImageMagick;
using ImageMagick.Formats;
using Microsoft.Extensions.Logging.Abstractions;
using Microsoft.Extensions.Options;
using SlpModularCms.Core.Media;
using SlpModularCms.Core.Media.Magick;
namespace SlpModularCms.Core.Tests.Media;
/// <summary>The real image library on small generated fixtures (no files from disk, so they run the same everywhere).</summary>
public class MagickImageProcessorTests
{
private static readonly MagickImageProcessor Processor = new(Options.Create(new MediaOptions()), NullLogger<MagickImageProcessor>.Instance);
private static byte[] Encode(MagickImage image, MagickFormat format)
{
using var stream = new MemoryStream();
image.Write(stream, format);
return stream.ToArray();
}
/// <summary>Left half red, right half blue: lets a test see which part of the picture a crop kept.</summary>
private static MagickImage TwoColours(int width, int height)
{
var image = new MagickImage(MagickColors.Red, (uint)width, (uint)height);
using var blue = new MagickImage(MagickColors.Blue, (uint)(width / 2), (uint)height);
image.Composite(blue, width - width / 2, 0, CompositeOperator.Over);
return image;
}
private static VariantSpec Spec(int w, int h, int x, int y, int cw, int ch, ImageFormat format = ImageFormat.WebP, Ratio? ratio = null)
=> new(ratio ?? Ratio.Wide, w, h, format, 80, new CropRect(x, y, cw, ch));
[Fact]
public void TheCapabilities_CoverTheCommonFormats()
{
Processor.SupportedInput.Should().Contain([ImageFormat.Jpeg, ImageFormat.Png, ImageFormat.Gif, ImageFormat.Bmp, ImageFormat.Tiff, ImageFormat.WebP, ImageFormat.Avif]);
Processor.SupportedOutput.Should().Contain([ImageFormat.WebP, ImageFormat.Jpeg]);
}
[Fact]
public async Task TheSelfTest_Passes() => await Processor.Invoking(p => p.SelfTestAsync(CancellationToken.None)).Should().NotThrowAsync();
[Theory]
[InlineData(MagickFormat.Jpeg, ImageFormat.Jpeg)]
[InlineData(MagickFormat.Png, ImageFormat.Png)]
[InlineData(MagickFormat.Gif, ImageFormat.Gif)]
[InlineData(MagickFormat.Bmp, ImageFormat.Bmp)]
[InlineData(MagickFormat.Tiff, ImageFormat.Tiff)]
[InlineData(MagickFormat.WebP, ImageFormat.WebP)]
[InlineData(MagickFormat.Avif, ImageFormat.Avif)]
public async Task EveryCommonFormat_IsRecognisedAndInspected(MagickFormat magick, ImageFormat expected)
{
using var image = TwoColours(120, 80);
var bytes = Encode(image, magick);
var detected = ImageSignature.Detect(bytes);
detected.Should().Be(expected == ImageFormat.Avif ? ImageFormat.Avif : expected);
var info = await Processor.InspectAsync(bytes, detected, CancellationToken.None);
info.Width.Should().Be(120);
info.Height.Should().Be(80);
info.FrameCount.Should().Be(1);
}
[Fact]
public async Task ARotatedPhoto_IsReportedInItsOrientedSize()
{
using var image = new MagickImage(MagickColors.Green, 400, 200);
var exif = new ExifProfile();
image.Orientation = Orientation.RightTop; // rotate 90 degrees clockwise on display
exif.SetValue(ExifTag.Orientation, (ushort)6);
image.SetProfile(exif);
var bytes = Encode(image, MagickFormat.Jpeg);
var info = await Processor.InspectAsync(bytes, ImageFormat.Jpeg, CancellationToken.None);
(info.Width, info.Height).Should().Be((200, 400));
info.HasMetadata.Should().BeTrue();
}
[Fact]
public async Task AnAnimatedGif_ReportsItsFrames_AndRendersTheFirst()
{
using var frames = new MagickImageCollection();
frames.Add(new MagickImage(MagickColors.Red, 60, 40) { AnimationDelay = 10 });
frames.Add(new MagickImage(MagickColors.Blue, 60, 40) { AnimationDelay = 10 });
using var stream = new MemoryStream();
frames.Write(stream, MagickFormat.Gif);
var bytes = stream.ToArray();
var info = await Processor.InspectAsync(bytes, ImageFormat.Gif, CancellationToken.None);
var rendered = await Processor.RenderAsync(bytes, ImageFormat.Gif, Spec(60, 40, 0, 0, 60, 40, ImageFormat.Png), CancellationToken.None);
info.FrameCount.Should().Be(2);
using var back = new MagickImage(rendered.Bytes);
back.GetPixels().GetPixel(5, 5).ToColor()!.ToString().Should().StartWith("#FF0000");
}
[Fact]
public async Task ARender_HasTheRequestedSize_AndNoMetadata()
{
using var image = TwoColours(1600, 1067);
var exif = new ExifProfile();
exif.SetValue(ExifTag.Software, "camera firmware");
exif.SetValue(ExifTag.GPSLatitudeRef, "N");
image.SetProfile(exif);
var bytes = Encode(image, MagickFormat.Jpeg);
var rendered = await Processor.RenderAsync(bytes, ImageFormat.Jpeg, Spec(960, 640, 0, 0, 1600, 1067), CancellationToken.None);
rendered.Format.Should().Be(ImageFormat.WebP);
(rendered.Width, rendered.Height).Should().Be((960, 640));
ImageSignature.Detect(rendered.Bytes).Should().Be(ImageFormat.WebP);
using var back = new MagickImage();
back.Ping(rendered.Bytes);
back.GetExifProfile().Should().BeNull();
back.GetXmpProfile().Should().BeNull();
}
[Fact]
public async Task TheCrop_KeepsTheChosenPartOfThePicture()
{
using var image = TwoColours(1000, 500);
var bytes = Encode(image, MagickFormat.Png);
var left = FocusMath.CropFor(1000, 500, Ratio.Tall, new FocusSetting(0.0, 0.5, 1));
var right = FocusMath.CropFor(1000, 500, Ratio.Tall, new FocusSetting(1.0, 0.5, 1));
var leftImage = await Processor.RenderAsync(bytes, ImageFormat.Png, Spec(200, 250, left.X, left.Y, left.Width, left.Height, ImageFormat.Png, Ratio.Tall), CancellationToken.None);
var rightImage = await Processor.RenderAsync(bytes, ImageFormat.Png, Spec(200, 250, right.X, right.Y, right.Width, right.Height, ImageFormat.Png, Ratio.Tall), CancellationToken.None);
using var l = new MagickImage(leftImage.Bytes);
using var r = new MagickImage(rightImage.Bytes);
l.GetPixels().GetPixel(100, 125).ToColor()!.ToString().Should().StartWith("#FF0000"); // red
r.GetPixels().GetPixel(100, 125).ToColor()!.ToString().Should().StartWith("#0000FF"); // blue
}
[Fact]
public async Task ARotatedPhoto_IsCroppedInItsOrientedSize()
{
using var image = TwoColours(400, 200);
var exif = new ExifProfile();
image.Orientation = Orientation.RightTop;
exif.SetValue(ExifTag.Orientation, (ushort)6);
image.SetProfile(exif);
var bytes = Encode(image, MagickFormat.Jpeg);
var rendered = await Processor.RenderAsync(bytes, ImageFormat.Jpeg, Spec(100, 200, 0, 0, 200, 400, ImageFormat.Jpeg, Ratio.Tall), CancellationToken.None);
(rendered.Width, rendered.Height).Should().Be((100, 200));
}
[Fact]
public async Task AvifOutput_IsWrittenWhenSupported()
{
Processor.SupportedOutput.Should().Contain(ImageFormat.Avif);
using var image = TwoColours(640, 427);
var bytes = Encode(image, MagickFormat.Png);
var rendered = await Processor.RenderAsync(bytes, ImageFormat.Png, Spec(320, 213, 0, 0, 640, 427, ImageFormat.Avif), CancellationToken.None);
ImageSignature.Detect(rendered.Bytes).Should().Be(ImageFormat.Avif);
}
[Fact]
public async Task ATruncatedFile_IsRejectedAsCorrupt()
{
using var image = TwoColours(800, 600);
var bytes = Encode(image, MagickFormat.Jpeg);
var truncated = bytes.AsMemory(0, bytes.Length / 3);
var act = async () => await Processor.RenderAsync(truncated, ImageFormat.Jpeg, Spec(100, 67, 0, 0, 800, 534), CancellationToken.None);
(await act.Should().ThrowAsync<ImageRejectedException>()).Which.Reason.Should().Be(ImageRejection.Corrupt);
}
[Fact]
public async Task AFileWithAJpegHeaderAndGarbage_IsRejectedAsCorrupt()
{
var garbage = new byte[2000];
new Random(7).NextBytes(garbage);
garbage[0] = 0xFF;
garbage[1] = 0xD8;
garbage[2] = 0xFF;
var act = async () => await Processor.InspectAsync(garbage, ImageFormat.Jpeg, CancellationToken.None);
(await act.Should().ThrowAsync<ImageRejectedException>()).Which.Reason.Should().Be(ImageRejection.Corrupt);
}
[Fact]
public async Task AFileThatClaimsAnotherFormat_IsRejected()
{
using var image = TwoColours(50, 50);
var png = Encode(image, MagickFormat.Png);
var act = async () => await Processor.InspectAsync(png, ImageFormat.Tiff, CancellationToken.None);
await act.Should().ThrowAsync<ImageRejectedException>();
}
[Fact]
public async Task StrippingMetadata_RemovesTheProfiles_AndKeepsTheSize()
{
using var image = TwoColours(300, 200);
var exif = new ExifProfile();
exif.SetValue(ExifTag.Software, "camera");
image.SetProfile(exif);
var withExif = Encode(image, MagickFormat.Jpeg);
using var plain = TwoColours(300, 200);
var withoutExif = Encode(plain, MagickFormat.Jpeg);
var stripped = await Processor.StripMetadataAsync(withExif, ImageFormat.Jpeg, CancellationToken.None);
var untouched = await Processor.StripMetadataAsync(withoutExif, ImageFormat.Jpeg, CancellationToken.None);
untouched.Should().BeNull();
stripped.Should().NotBeNull();
using var back = new MagickImage();
back.Ping(stripped!);
back.GetExifProfile().Should().BeNull();
(back.Width, back.Height).Should().Be((300u, 200u));
}
[Fact]
public async Task APlannedCrop_ThatDoesNotFit_IsRefused()
{
using var image = TwoColours(100, 100);
var bytes = Encode(image, MagickFormat.Png);
var act = async () => await Processor.RenderAsync(bytes, ImageFormat.Png, Spec(50, 33, 50, 50, 100, 100), CancellationToken.None);
await act.Should().ThrowAsync<ImageRejectedException>();
}
}
@@ -0,0 +1,290 @@
using FluentAssertions;
using FsCheck;
using FsCheck.Fluent;
using SlpModularCms.Core.Media;
namespace SlpModularCms.Core.Tests.Media;
public class FocusMathTests
{
private static Arbitrary<(int W, int H, FocusSetting Focus, Ratio Ratio)> Cases() =>
(from w in Gen.Choose(1, 9000)
from h in Gen.Choose(1, 9000)
from fx in Gen.Choose(0, 1000)
from fy in Gen.Choose(0, 1000)
from zoom in Gen.Choose(1000, 4000)
from tall in Gen.Elements(true, false)
select (w, h, new FocusSetting(fx / 1000.0, fy / 1000.0, zoom / 1000.0), tall ? Ratio.Tall : Ratio.Wide)).ToArbitrary();
private static void ForAllCases(Action<(int W, int H, FocusSetting Focus, Ratio Ratio)> check) =>
Prop.ForAll(Cases(), c => { check(c); return true; }).Check(Config.QuickThrowOnFailure.WithMaxTest(2000));
[Fact]
public void TheCrop_IsAlwaysInsideTheImage() => ForAllCases(c =>
{
var crop = FocusMath.CropFor(c.W, c.H, c.Ratio, c.Focus);
crop.Width.Should().BeInRange(1, c.W);
crop.Height.Should().BeInRange(1, c.H);
crop.X.Should().BeGreaterThanOrEqualTo(0);
crop.Y.Should().BeGreaterThanOrEqualTo(0);
(crop.X + crop.Width).Should().BeLessThanOrEqualTo(c.W);
(crop.Y + crop.Height).Should().BeLessThanOrEqualTo(c.H);
});
[Fact]
public void TheFocusPoint_IsInsideTheCrop() => ForAllCases(c =>
{
var crop = FocusMath.CropFor(c.W, c.H, c.Ratio, c.Focus);
var px = c.Focus.X * c.W;
var py = c.Focus.Y * c.H;
px.Should().BeInRange(crop.X - 1, crop.X + crop.Width + 1);
py.Should().BeInRange(crop.Y - 1, crop.Y + crop.Height + 1);
});
[Fact]
public void TheCrop_HasTheRatio_WithinOnePixel() => ForAllCases(c =>
{
// Only meaningful when the crop is big enough for one pixel not to matter.
var crop = FocusMath.CropFor(c.W, c.H, c.Ratio, c.Focus);
if (crop.Width >= 50 && crop.Height >= 50)
{
var expectedHeight = crop.Width * (double)c.Ratio.Denominator / c.Ratio.Numerator;
Math.Abs(crop.Height - expectedHeight).Should().BeLessThanOrEqualTo(1.0);
}
});
[Fact]
public void MoreZoom_NeverGivesABiggerCrop() => ForAllCases(c =>
{
var plain = FocusMath.CropFor(c.W, c.H, c.Ratio, c.Focus with { Zoom = 1 });
var zoomed = FocusMath.CropFor(c.W, c.H, c.Ratio, c.Focus);
zoomed.Width.Should().BeLessThanOrEqualTo(plain.Width);
});
[Fact]
public void InvalidFocusValues_AreClamped_NotFatal()
{
var crop = FocusMath.CropFor(1600, 1067, Ratio.Tall, new FocusSetting(double.NaN, double.PositiveInfinity, double.NegativeInfinity));
crop.X.Should().BeGreaterThanOrEqualTo(0);
(crop.X + crop.Width).Should().BeLessThanOrEqualTo(1600);
}
// Shared vectors: the admin's TypeScript twin has the same cases (frontend/src/features/hero/focusMath.test.ts).
[Theory]
[InlineData(1600, 1067, "wide", 0.5, 0.5, 1.0, 0, 0, 1600, 1067)]
[InlineData(1600, 1067, "tall", 0.5, 0.5, 1.0, 374, 1, 853, 1066)]
[InlineData(1600, 1067, "tall", 0.0, 0.5, 1.0, 0, 1, 853, 1066)]
[InlineData(1600, 1067, "tall", 1.0, 0.5, 1.0, 747, 1, 853, 1066)]
[InlineData(1600, 1067, "wide", 0.45, 0.35, 2.0, 320, 107, 800, 533)]
[InlineData(2560, 1702, "tall", 0.55, 0.6, 1.0, 728, 1, 1361, 1701)]
[InlineData(1000, 2000, "wide", 0.5, 0.5, 1.0, 0, 667, 1000, 667)]
public void KnownVectors(int w, int h, string ratio, double fx, double fy, double zoom, int x, int y, int cw, int ch)
{
var crop = FocusMath.CropFor(w, h, ratio == "tall" ? Ratio.Tall : Ratio.Wide, new FocusSetting(fx, fy, zoom));
crop.Should().Be(new CropRect(x, y, cw, ch));
}
}
public class VariantPlannerTests
{
private static readonly IReadOnlySet<ImageFormat> WebPAndAvif = new HashSet<ImageFormat> { ImageFormat.WebP, ImageFormat.Avif };
private static readonly IReadOnlySet<ImageFormat> WebPOnly = new HashSet<ImageFormat> { ImageFormat.WebP };
private static RatioPlan[] Plans() =>
[
new(Ratio.Wide, FocusSetting.Centre, VariantPlanner.DefaultWidths(Ratio.Wide)),
new(Ratio.Tall, FocusSetting.Centre, VariantPlanner.DefaultWidths(Ratio.Tall)),
];
[Fact]
public void ASmallSource_IsNeverScaledUp()
{
var plan = VariantPlanner.Plan(1600, 1067, Plans(), WebPAndAvif);
plan.Should().OnlyContain(v => v.Width <= v.Crop.Width);
plan.Where(v => v.Ratio.Name == "wide").Select(v => v.Width).Distinct().Should().Equal(640, 960, 1280, 1600);
plan.Where(v => v.Ratio.Name == "tall").Select(v => v.Width).Distinct().Should().Equal(480, 640); // the tall crop of a 1600x1067 image is 853 wide
}
[Fact]
public void ALargeSource_GetsTheWholeLadder()
{
var plan = VariantPlanner.Plan(6000, 4000, Plans(), WebPAndAvif);
plan.Where(v => v.Ratio.Name == "wide").Select(v => v.Width).Distinct().Should().Equal(640, 960, 1280, 1600, 2560);
plan.Where(v => v.Ratio.Name == "tall").Select(v => v.Width).Distinct().Should().Equal(480, 640, 960, 1280);
}
[Fact]
public void ATinySource_StillGetsOneVariantPerRatio()
{
var plan = VariantPlanner.Plan(300, 200, Plans(), WebPOnly);
plan.Where(v => v.Ratio.Name == "wide").Should().ContainSingle().Which.Width.Should().Be(300);
plan.Where(v => v.Ratio.Name == "tall").Should().ContainSingle().Which.Width.Should().Be(160);
}
[Fact]
public void WebPIsAlwaysPlanned_AvifOnlyWhenTheProcessorCan()
{
VariantPlanner.Plan(2000, 1500, Plans(), WebPOnly).Select(v => v.Format).Distinct().Should().Equal(ImageFormat.WebP);
VariantPlanner.Plan(2000, 1500, Plans(), WebPAndAvif).Select(v => v.Format).Distinct().Should().BeEquivalentTo([ImageFormat.WebP, ImageFormat.Avif]);
}
[Fact]
public void WithoutAWebPEncoder_TheFallbackIsJpeg()
{
var onlyAvif = new HashSet<ImageFormat> { ImageFormat.Avif };
VariantPlanner.Plan(2000, 1500, Plans(), onlyAvif).Select(v => v.Format).Distinct().Should().BeEquivalentTo([ImageFormat.Jpeg, ImageFormat.Avif]);
}
[Fact]
public void Widths_AreAscendingPerRatio_AndHeightsKeepTheRatio()
{
Prop.ForAll(Gen.Choose(50, 9000).SelectMany(w => Gen.Choose(50, 9000).Select(h => (w, h))).ToArbitrary(), size =>
{
var plan = VariantPlanner.Plan(size.w, size.h, Plans(), WebPAndAvif);
foreach (var group in plan.GroupBy(v => v.Ratio.Name))
{
var widths = group.Where(v => v.Format == ImageFormat.WebP).Select(v => v.Width).ToList();
widths.Should().BeInAscendingOrder().And.OnlyHaveUniqueItems();
widths.Should().NotBeEmpty();
foreach (var v in group)
{
Math.Abs(v.Height - v.Width * (double)v.Ratio.Denominator / v.Ratio.Numerator).Should().BeLessThanOrEqualTo(0.5);
}
}
return true;
}).Check(Config.QuickThrowOnFailure.WithMaxTest(500));
}
}
public class MediaPathsTests
{
private const string Sha = "0f8c6d3e2a1b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5";
[Fact]
public void TheSetHash_IsStable_AndChangesWhenTheFocusChanges()
{
var a = MediaPaths.SetHash(Sha, [("wide", FocusSetting.Centre), ("tall", FocusSetting.Centre)]);
var again = MediaPaths.SetHash(Sha, [("tall", FocusSetting.Centre), ("wide", FocusSetting.Centre)]);
var moved = MediaPaths.SetHash(Sha, [("wide", FocusSetting.Centre), ("tall", new FocusSetting(0.4, 0.5, 1))]);
var other = MediaPaths.SetHash(Sha.Replace('0', '1'), [("wide", FocusSetting.Centre), ("tall", FocusSetting.Centre)]);
a.Should().MatchRegex("^[0-9a-f]{16}$");
again.Should().Be(a);
moved.Should().NotBe(a);
other.Should().NotBe(a);
}
[Fact]
public void SmallDifferences_BelowTheCanonicalPrecision_GiveTheSameSet()
=> MediaPaths.SetHash(Sha, [("wide", new FocusSetting(0.50001, 0.5, 1))])
.Should().Be(MediaPaths.SetHash(Sha, [("wide", new FocusSetting(0.5, 0.5, 1))]));
[Fact]
public void AnAddress_RoundTrips()
{
var hash = MediaPaths.SetHash(Sha, [("wide", FocusSetting.Centre)]);
var name = MediaPaths.FileName("wide", 1600, ImageFormat.WebP);
var url = MediaPaths.Url("hero", hash, name);
url.Should().Be($"/media/hero/{hash}/wide-1600.webp");
MediaPaths.TryParse(url[MediaPaths.UrlPrefix.Length..], out var address).Should().BeTrue();
address.Should().Be(new MediaAddress("hero", hash, "wide-1600.webp"));
MediaPaths.TryParseName(name, out var ratio, out var width, out var format).Should().BeTrue();
(ratio, width, format).Should().Be(("wide", 1600, ImageFormat.WebP));
}
[Theory]
[InlineData("")]
[InlineData("hero/0123456789abcdef/wide-1600.png")]
[InlineData("hero/0123456789abcde/wide-1600.webp")]
[InlineData("hero/0123456789ABCDEF/wide-1600.webp")]
[InlineData("hero/0123456789abcdef/../wide-1600.webp")]
[InlineData("../hero/0123456789abcdef/wide-1600.webp")]
[InlineData("hero//0123456789abcdef/wide-1600.webp")]
[InlineData("hero/0123456789abcdef/wide-1600.webp/")]
[InlineData("hero\\0123456789abcdef\\wide-1600.webp")]
[InlineData("hero/0123456789abcdef/wide-16.webp ")]
[InlineData("hero/0123456789abcdef/WIDE-1600.webp")]
[InlineData("hero/0123456789abcdef/original.jpg")]
[InlineData("originals/0123456789abcdef/wide-1600.webp.exe")]
public void AnythingElse_IsNotAnAddress(string path) => MediaPaths.TryParse(path, out _).Should().BeFalse();
}
public class ImageSignatureTests
{
private static byte[] Padded(params byte[] head) => head.Concat(new byte[32 - head.Length]).ToArray();
[Fact]
public void KnownSignatures_AreRecognised()
{
ImageSignature.Detect(Padded(0xFF, 0xD8, 0xFF, 0xE0)).Should().Be(ImageFormat.Jpeg);
ImageSignature.Detect(Padded(0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A)).Should().Be(ImageFormat.Png);
ImageSignature.Detect("GIF89a"u8.ToArray().Concat(new byte[26]).ToArray()).Should().Be(ImageFormat.Gif);
ImageSignature.Detect(Padded(0x49, 0x49, 0x2A, 0x00)).Should().Be(ImageFormat.Tiff);
ImageSignature.Detect(Padded(0x4D, 0x4D, 0x00, 0x2A)).Should().Be(ImageFormat.Tiff);
ImageSignature.Detect(Riff("WEBP")).Should().Be(ImageFormat.WebP);
ImageSignature.Detect(Ftyp("avif")).Should().Be(ImageFormat.Avif);
ImageSignature.Detect(Ftyp("heic")).Should().Be(ImageFormat.Heic);
ImageSignature.Detect(Bmp(40)).Should().Be(ImageFormat.Bmp);
}
[Theory]
[InlineData("<svg xmlns=\"http://www.w3.org/2000/svg\"></svg>")]
[InlineData("<?xml version=\"1.0\"?><svg/>")]
[InlineData("%PDF-1.7 and more text here to fill")]
[InlineData("MZ\u0090\u0000\u0003 an executable header")]
[InlineData("<html><script>alert(1)</script></html>")]
[InlineData("PK\u0003\u0004 a zip archive of something")]
[InlineData("")]
public void NotAnImage_IsUnknown(string text)
=> ImageSignature.Detect(System.Text.Encoding.Latin1.GetBytes(text)).Should().Be(ImageFormat.Unknown);
[Fact]
public void ARiffThatIsNotWebP_IsUnknown() => ImageSignature.Detect(Riff("WAVE")).Should().Be(ImageFormat.Unknown);
[Fact]
public void AnIsoFileWithAnotherBrand_IsUnknown() => ImageSignature.Detect(Ftyp("mp42")).Should().Be(ImageFormat.Unknown);
[Fact]
public void ABmThatIsNoBitmap_IsUnknown() => ImageSignature.Detect(Bmp(7)).Should().Be(ImageFormat.Unknown);
[Fact]
public void ARandomHead_NeverThrows()
=> Prop.ForAll(Gen.Choose(0, 255).Select(i => (byte)i).ArrayOf().ToArbitrary(), bytes =>
{
var act = () => ImageSignature.Detect(bytes);
act.Should().NotThrow();
return true;
}).Check(Config.QuickThrowOnFailure.WithMaxTest(1000));
private static byte[] Riff(string kind)
{
var b = new byte[32];
"RIFF"u8.CopyTo(b);
System.Text.Encoding.ASCII.GetBytes(kind).CopyTo(b, 8);
return b;
}
private static byte[] Ftyp(string brand)
{
var b = new byte[32];
b[3] = 0x1C;
"ftyp"u8.CopyTo(b.AsSpan(4));
System.Text.Encoding.ASCII.GetBytes(brand).CopyTo(b, 8);
return b;
}
private static byte[] Bmp(int headerSize)
{
var b = new byte[32];
b[0] = (byte)'B';
b[1] = (byte)'M';
b[14] = (byte)headerSize;
return b;
}
}
@@ -0,0 +1,157 @@
using FluentAssertions;
using Microsoft.Extensions.Options;
using NSubstitute;
using SlpModularCms.Core.Media;
namespace SlpModularCms.Core.Tests.Media;
public class MediaUploadGuardTests
{
private static readonly byte[] Png = [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 1, 2, 3, 4, 5, 6, 7, 8];
private sealed class Rig
{
public MediaOptions Options { get; } = new() { MaxUploadBytes = 1000, MaxPixels = 1_000_000, MaxSide = 5000, MaxParallelJobs = 1, BusyWaitSeconds = 0 };
public IImageProcessor Processor { get; } = Substitute.For<IImageProcessor>();
public MediaStatus Status { get; } = new();
public MediaProcessingGate Gate { get; }
public MediaUploadGuard Guard { get; }
public Rig(bool available = true)
{
Gate = new MediaProcessingGate(Microsoft.Extensions.Options.Options.Create(Options));
Processor.SupportedInput.Returns(new HashSet<ImageFormat> { ImageFormat.Jpeg, ImageFormat.Png, ImageFormat.WebP });
Processor.InspectAsync(default, default, default).ReturnsForAnyArgs(new ImageInfo(ImageFormat.Png, 800, 600, 1, false));
Status.SetProcessor(available, Processor.SupportedInput, new HashSet<ImageFormat> { ImageFormat.WebP });
Status.SetDirectory(true);
Guard = new MediaUploadGuard(Processor, Gate, Status, Microsoft.Extensions.Options.Options.Create(Options));
}
}
private static MemoryStream Stream(byte[] bytes) => new(bytes);
[Fact]
public async Task AValidImage_IsAdmitted_WithItsInfo()
{
var rig = new Rig();
using var upload = await rig.Guard.AdmitAsync(Stream(Png), Png.Length, CancellationToken.None);
upload.Bytes.Should().Equal(Png);
upload.Info.Width.Should().Be(800);
}
[Fact]
public async Task ADeclaredLength_AboveTheLimit_IsRefusedBeforeReading()
{
var rig = new Rig();
var act = async () => await rig.Guard.AdmitAsync(Stream(Png), 5000, CancellationToken.None);
(await act.Should().ThrowAsync<ImageRejectedException>()).Which.Code.Should().Be("too_large");
}
[Fact]
public async Task AnUpload_LongerThanItsDeclaredLength_IsStillStopped()
{
var rig = new Rig();
var big = new byte[2000];
Png.CopyTo(big, 0);
var act = async () => await rig.Guard.AdmitAsync(Stream(big), 10, CancellationToken.None);
(await act.Should().ThrowAsync<ImageRejectedException>()).Which.Code.Should().Be("too_large");
}
[Theory]
[InlineData("<svg xmlns=\"http://www.w3.org/2000/svg\"><script>alert(1)</script></svg>")]
[InlineData("%PDF-1.4 not an image")]
[InlineData("GIF89a is not in the accepted list of this rig but the processor lacks it")]
public async Task NotAnAcceptedImage_IsRefused(string text)
{
var rig = new Rig();
var bytes = System.Text.Encoding.ASCII.GetBytes(text);
var act = async () => await rig.Guard.AdmitAsync(Stream(bytes), bytes.Length, CancellationToken.None);
(await act.Should().ThrowAsync<ImageRejectedException>()).Which.Code.Should().Be("unsupported_format");
}
[Fact]
public async Task AnEmptyUpload_IsCorrupt()
{
var rig = new Rig();
var act = async () => await rig.Guard.AdmitAsync(Stream([]), 0, CancellationToken.None);
(await act.Should().ThrowAsync<ImageRejectedException>()).Which.Code.Should().Be("corrupt");
}
[Theory]
[InlineData(2000, 2000)] // 4 MP, above the 1 MP ceiling
[InlineData(6000, 10)] // a side above the limit
public async Task ATooBigPicture_IsRefused(int width, int height)
{
var rig = new Rig();
rig.Processor.InspectAsync(default, default, default).ReturnsForAnyArgs(new ImageInfo(ImageFormat.Png, width, height, 1, false));
var act = async () => await rig.Guard.AdmitAsync(Stream(Png), Png.Length, CancellationToken.None);
(await act.Should().ThrowAsync<ImageRejectedException>()).Which.Code.Should().Be("too_many_pixels");
}
[Fact]
public async Task WhenTheLibraryIsNotAvailable_NothingIsAccepted()
{
var rig = new Rig(available: false);
var act = async () => await rig.Guard.AdmitAsync(Stream(Png), Png.Length, CancellationToken.None);
(await act.Should().ThrowAsync<ImageRejectedException>()).Which.Code.Should().Be("unavailable");
}
[Fact]
public async Task WhenTheDirectoryIsNotWritable_NothingIsAccepted()
{
var rig = new Rig();
rig.Status.SetDirectory(false);
var act = async () => await rig.Guard.AdmitAsync(Stream(Png), Png.Length, CancellationToken.None);
(await act.Should().ThrowAsync<ImageRejectedException>()).Which.Code.Should().Be("unavailable");
}
[Fact]
public async Task WhenAllSlotsAreTaken_TheAnswerIsBusy_AndAFreedSlotWorksAgain()
{
var rig = new Rig();
var first = await rig.Guard.AdmitAsync(Stream(Png), Png.Length, CancellationToken.None);
var act = async () => await rig.Guard.AdmitAsync(Stream(Png), Png.Length, CancellationToken.None);
(await act.Should().ThrowAsync<ImageRejectedException>()).Which.Code.Should().Be("busy");
first.Dispose();
using var second = await rig.Guard.AdmitAsync(Stream(Png), Png.Length, CancellationToken.None);
second.Info.Should().NotBeNull();
}
[Fact]
public async Task ARefusal_ReleasesTheSlot()
{
var rig = new Rig();
var bad = System.Text.Encoding.ASCII.GetBytes("not an image at all");
for (var i = 0; i < 3; i++)
{
var act = async () => await rig.Guard.AdmitAsync(Stream(bad), bad.Length, CancellationToken.None);
await act.Should().ThrowAsync<ImageRejectedException>();
}
using var ok = await rig.Guard.AdmitAsync(Stream(Png), Png.Length, CancellationToken.None);
ok.Should().NotBeNull();
}
}
@@ -36,6 +36,7 @@
<ItemGroup>
<ProjectReference Include="..\SlpModularCms.Core\SlpModularCms.Core.csproj" />
<ProjectReference Include="..\SlpModularCms.Core.Media.Magick\SlpModularCms.Core.Media.Magick.csproj" />
</ItemGroup>
<!--
+55
View File
@@ -0,0 +1,55 @@
namespace SlpModularCms.Core.Media;
/// <summary>
/// The crop for a ratio around a focus point. Pure and deterministic; the admin's TypeScript twin uses the same
/// steps and the same test vectors so the preview matches what the host cuts.
/// </summary>
public static class FocusMath
{
/// <summary>
/// The largest rectangle of the ratio that fits the image, shrunk by the zoom, centred on the focus point and
/// moved the smallest amount needed to stay inside the image. The focus point is therefore always inside the crop.
/// </summary>
public static CropRect CropFor(int imageWidth, int imageHeight, Ratio ratio, FocusSetting focus)
{
if (imageWidth <= 0 || imageHeight <= 0)
{
throw new ArgumentOutOfRangeException(nameof(imageWidth), "The image must have a size.");
}
var f = focus.Normalize();
// Largest crop of the ratio inside the image (width:height = numerator:denominator).
double cw0, ch0;
if ((long)imageWidth * ratio.Denominator > (long)imageHeight * ratio.Numerator)
{
ch0 = imageHeight;
cw0 = ch0 * ratio.Numerator / ratio.Denominator;
}
else
{
cw0 = imageWidth;
ch0 = cw0 * ratio.Denominator / ratio.Numerator;
}
var cw = Math.Clamp((int)Math.Floor(cw0 / f.Zoom), 1, imageWidth);
var ch = Math.Max(1, RoundHalfUp(cw * (double)ratio.Denominator / ratio.Numerator));
// The height follows from the width; when rounding pushed it past the image, derive the width from the height.
if (ch > imageHeight)
{
ch = imageHeight;
cw = Math.Clamp((int)Math.Floor(ch * (double)ratio.Numerator / ratio.Denominator), 1, imageWidth);
}
var x = RoundHalfUp(f.X * imageWidth - cw / 2.0);
var y = RoundHalfUp(f.Y * imageHeight - ch / 2.0);
x = Math.Clamp(x, 0, imageWidth - cw);
y = Math.Clamp(y, 0, imageHeight - ch);
return new CropRect(x, y, cw, ch);
}
/// <summary>Rounds .5 up (like JavaScript's Math.round), so the admin's TypeScript twin gives the same numbers.</summary>
public static int RoundHalfUp(double value) => (int)Math.Floor(value + 0.5);
}
@@ -0,0 +1,148 @@
using Microsoft.Extensions.Options;
namespace SlpModularCms.Core.Media;
/// <summary>Why an upload was refused. The names are the stable codes the API returns (see <see cref="ImageRejectedException.Code"/>).</summary>
public enum ImageRejection
{
TooLarge,
UnsupportedFormat,
Corrupt,
TooManyPixels,
Timeout,
Busy,
Unavailable,
}
/// <summary>A refused image. The message is technical English for logs; users see a text from the language files.</summary>
public sealed class ImageRejectedException(ImageRejection reason, string message) : Exception(message)
{
public ImageRejection Reason { get; } = reason;
/// <summary>A stable code for the API: <c>too_large</c>, <c>unsupported_format</c>, <c>corrupt</c>, <c>too_many_pixels</c>, <c>timeout</c>, <c>busy</c>, <c>unavailable</c>.</summary>
public string Code => Reason switch
{
ImageRejection.TooLarge => "too_large",
ImageRejection.UnsupportedFormat => "unsupported_format",
ImageRejection.Corrupt => "corrupt",
ImageRejection.TooManyPixels => "too_many_pixels",
ImageRejection.Timeout => "timeout",
ImageRejection.Busy => "busy",
_ => "unavailable",
};
}
/// <summary>Settings of the media service (<c>Media:*</c>).</summary>
public sealed class MediaOptions
{
public const string SectionName = "Media";
/// <summary>The directory outside the release where files are stored. Empty = uploads are unavailable.</summary>
public string? Directory { get; set; }
public long MaxUploadBytes { get; set; } = 10 * 1024 * 1024;
public long MaxPixels { get; set; } = 64_000_000;
public int MaxSide { get; set; } = 16_384;
public int MaxParallelJobs { get; set; } = 2;
public int DecodeTimeoutSeconds { get; set; } = 20;
/// <summary>How long a free processing slot is awaited before the answer is "busy".</summary>
public int BusyWaitSeconds { get; set; } = 3;
public long MaxTotalBytes { get; set; } = 2L * 1024 * 1024 * 1024;
public int RetentionDays { get; set; } = 7;
}
/// <summary>
/// The image library behind one small interface. Implementations must apply the resource limits of
/// <see cref="MediaOptions"/>, decode only the format the caller names (decided from the signature), never use a
/// client file name and never write metadata into an output.
/// </summary>
public interface IImageProcessor
{
/// <summary>The formats it can decode.</summary>
IReadOnlySet<ImageFormat> SupportedInput { get; }
/// <summary>The formats it can write (WebP always; AVIF when the platform can).</summary>
IReadOnlySet<ImageFormat> SupportedOutput { get; }
/// <summary>Reads size (after orientation), frame count and whether metadata is present, without decoding the pixels.</summary>
/// <exception cref="ImageRejectedException">The data is not a decodable image of that format.</exception>
Task<ImageInfo> InspectAsync(ReadOnlyMemory<byte> data, ImageFormat declared, CancellationToken cancellationToken);
/// <summary>
/// Decodes the first frame, applies the orientation, cuts the crop, resizes to the variant size (never above the
/// crop), strips metadata and encodes in the variant's format and quality.
/// </summary>
Task<RenderedImage> RenderAsync(ReadOnlyMemory<byte> data, ImageFormat declared, VariantSpec variant, CancellationToken cancellationToken);
/// <summary>
/// Removes metadata from an original that carries any, keeping the pixels as they are as far as the format
/// allows. Returns null when there is nothing to remove (the original is stored as received).
/// </summary>
Task<byte[]?> StripMetadataAsync(ReadOnlyMemory<byte> data, ImageFormat declared, CancellationToken cancellationToken);
/// <summary>Encodes and decodes a tiny image in every supported format. Throws when the library does not work here.</summary>
Task SelfTestAsync(CancellationToken cancellationToken);
}
/// <summary>What the start-up self-test found; uploads are refused while the processor is not available.</summary>
public sealed class MediaStatus
{
private volatile bool _processorAvailable;
private volatile bool _directoryWritable;
public bool ProcessorAvailable => _processorAvailable;
public bool DirectoryWritable => _directoryWritable;
public bool UploadsAvailable => _processorAvailable && _directoryWritable;
public IReadOnlySet<ImageFormat> AcceptedInput { get; private set; } = new HashSet<ImageFormat>();
public IReadOnlySet<ImageFormat> Output { get; private set; } = new HashSet<ImageFormat>();
public void SetProcessor(bool available, IReadOnlySet<ImageFormat> input, IReadOnlySet<ImageFormat> output)
{
AcceptedInput = input;
Output = output;
_processorAvailable = available;
}
public void SetDirectory(bool writable) => _directoryWritable = writable;
}
/// <summary>Limits how many images are processed at once; a full gate answers "busy" after a short wait.</summary>
public sealed class MediaProcessingGate(IOptions<MediaOptions> options)
{
private readonly SemaphoreSlim _slots = new(Math.Max(1, options.Value.MaxParallelJobs));
private readonly TimeSpan _wait = TimeSpan.FromSeconds(Math.Max(0, options.Value.BusyWaitSeconds));
public async Task<IDisposable> EnterAsync(CancellationToken cancellationToken)
{
if (!await _slots.WaitAsync(_wait, cancellationToken))
{
throw new ImageRejectedException(ImageRejection.Busy, "All image processing slots are in use.");
}
return new Releaser(_slots);
}
private sealed class Releaser(SemaphoreSlim slots) : IDisposable
{
private int _released;
public void Dispose()
{
if (Interlocked.Exchange(ref _released, 1) == 0)
{
slots.Release();
}
}
}
}
@@ -0,0 +1,89 @@
namespace SlpModularCms.Core.Media;
/// <summary>
/// Decides an image format from the first bytes of a file, never from a name or a declared content type. The check is
/// deliberately strict and small: a file that is not one of these is rejected before any library touches it. SVG,
/// PDF, scripts and archives are never recognised.
/// </summary>
public static class ImageSignature
{
/// <summary>How many bytes <see cref="Detect"/> needs at most.</summary>
public const int HeaderLength = 32;
private static readonly string[] AvifBrands = ["avif", "avis"];
private static readonly string[] HeicBrands = ["heic", "heix", "hevc", "hevx", "heim", "heis", "mif1", "msf1"];
public static ImageFormat Detect(ReadOnlySpan<byte> head)
{
if (head.Length >= 3 && head[0] == 0xFF && head[1] == 0xD8 && head[2] == 0xFF)
{
return ImageFormat.Jpeg;
}
if (head.Length >= 8 && head[..8].SequenceEqual((ReadOnlySpan<byte>)[0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]))
{
return ImageFormat.Png;
}
if (head.Length >= 6 && (Ascii(head, 0, "GIF87a") || Ascii(head, 0, "GIF89a")))
{
return ImageFormat.Gif;
}
if (head.Length >= 4 && ((head[0] == 0x49 && head[1] == 0x49 && head[2] == 0x2A && head[3] == 0x00)
|| (head[0] == 0x4D && head[1] == 0x4D && head[2] == 0x00 && head[3] == 0x2A)))
{
return ImageFormat.Tiff;
}
if (head.Length >= 12 && Ascii(head, 0, "RIFF") && Ascii(head, 8, "WEBP"))
{
return ImageFormat.WebP;
}
if (head.Length >= 12 && Ascii(head, 4, "ftyp"))
{
var brand = System.Text.Encoding.ASCII.GetString(head.Slice(8, 4));
if (AvifBrands.Contains(brand))
{
return ImageFormat.Avif;
}
if (HeicBrands.Contains(brand))
{
return ImageFormat.Heic;
}
}
if (head.Length >= 18 && head[0] == (byte)'B' && head[1] == (byte)'M'
&& head[6] == 0 && head[7] == 0 && head[8] == 0 && head[9] == 0)
{
// BITMAPCOREHEADER 12, BITMAPINFOHEADER 40, and the 52, 56, 64, 108, 124 byte variants.
var headerSize = head[14] | (head[15] << 8) | (head[16] << 16) | (head[17] << 24);
if (headerSize is 12 or 40 or 52 or 56 or 64 or 108 or 124)
{
return ImageFormat.Bmp;
}
}
return ImageFormat.Unknown;
}
private static bool Ascii(ReadOnlySpan<byte> data, int offset, string text)
{
if (data.Length < offset + text.Length)
{
return false;
}
for (var i = 0; i < text.Length; i++)
{
if (data[offset + i] != (byte)text[i])
{
return false;
}
}
return true;
}
}
@@ -0,0 +1,78 @@
using System.Security.Cryptography;
using System.Text;
using System.Text.RegularExpressions;
namespace SlpModularCms.Core.Media;
/// <summary>
/// The address scheme of stored media: <c>/media/{area}/{setHash}/{ratio}-{width}.{ext}</c>. The set hash contains the
/// content hash of the original and the crop parameters, so a changed focus gives a new address and the files can be
/// cached for a long time. Parsing is a strict allow-list: anything else is not an address.
/// </summary>
public static partial class MediaPaths
{
public const string UrlPrefix = "/media/";
[GeneratedRegex(@"^(?<area>[a-z]{2,20})/(?<hash>[0-9a-f]{16})/(?<name>[a-z]{2,10}-[0-9]{2,5}\.(?:webp|avif|jpg))$", RegexOptions.CultureInvariant)]
private static partial Regex AddressPattern();
/// <summary>
/// 16 hex characters of SHA-256 over the original's hash and the crops (ratio name and canonical focus, ordered by
/// ratio name), so the same photo with the same focus always gives the same set.
/// </summary>
public static string SetHash(string originalSha256, IEnumerable<(string Ratio, FocusSetting Focus)> crops)
{
var text = new StringBuilder(originalSha256.ToLowerInvariant());
foreach (var (ratio, focus) in crops.OrderBy(c => c.Ratio, StringComparer.Ordinal))
{
text.Append('|').Append(ratio).Append(':').Append(focus.Normalize().Canonical());
}
var hash = SHA256.HashData(Encoding.UTF8.GetBytes(text.ToString()));
return Convert.ToHexStringLower(hash)[..16];
}
/// <summary>The file name of a variant, for example <c>wide-1600.webp</c>.</summary>
public static string FileName(string ratioName, int width, ImageFormat format)
=> $"{ratioName}-{width}.{format.Extension()}";
/// <summary>The public address, for example <c>/media/hero/0123456789abcdef/wide-1600.webp</c>.</summary>
public static string Url(string area, string setHash, string name) => $"{UrlPrefix}{area}/{setHash}/{name}";
/// <summary>Parses the part after <c>/media/</c>; false for anything that is not exactly an address of this scheme.</summary>
public static bool TryParse(string? path, out MediaAddress address)
{
address = null!;
if (string.IsNullOrEmpty(path) || path.Length > 100)
{
return false;
}
var match = AddressPattern().Match(path);
if (!match.Success)
{
return false;
}
address = new MediaAddress(match.Groups["area"].Value, match.Groups["hash"].Value, match.Groups["name"].Value);
return true;
}
/// <summary>The ratio name, width and format of a variant file name; false when it is not one.</summary>
public static bool TryParseName(string name, out string ratio, out int width, out ImageFormat format)
{
ratio = string.Empty;
width = 0;
format = ImageFormat.Unknown;
var dash = name.IndexOf('-');
var dot = name.LastIndexOf('.');
if (dash <= 0 || dot <= dash + 1 || !int.TryParse(name.AsSpan(dash + 1, dot - dash - 1), out width))
{
return false;
}
ratio = name[..dash];
format = ImageFormatExtensions.FromExtension(name[(dot + 1)..]);
return format != ImageFormat.Unknown;
}
}
@@ -0,0 +1,61 @@
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
namespace SlpModularCms.Core.Media;
public static class MediaServiceCollectionExtensions
{
/// <summary>
/// The general media service: options (<c>Media:*</c>), the processing gate, the status the admin reads, the upload
/// guard and the start-up self-test. Safe to call from every module that needs it. An <see cref="IImageProcessor"/>
/// has to be registered separately (the Magick project does that); without one the status stays "unavailable".
/// </summary>
public static IServiceCollection AddCmsMedia(this IServiceCollection services, IConfiguration configuration)
{
services.AddOptions<MediaOptions>().Bind(configuration.GetSection(MediaOptions.SectionName));
services.TryAddSingleton<MediaProcessingGate>();
services.TryAddSingleton<MediaStatus>();
services.TryAddSingleton<IMediaUploadGuard, MediaUploadGuard>();
if (!services.Any(d => d.ImplementationType == typeof(ImageProcessorSelfTest)))
{
services.AddHostedService<ImageProcessorSelfTest>();
}
return services;
}
}
/// <summary>
/// At start-up, proves the image library works on this host (encodes and decodes a tiny image in every supported
/// format) and publishes what it found. A failure only turns image uploads off: nothing else depends on it, and
/// reading pages and media keeps working.
/// </summary>
public sealed class ImageProcessorSelfTest(IServiceProvider services, MediaStatus status, ILogger<ImageProcessorSelfTest> logger) : IHostedService
{
public async Task StartAsync(CancellationToken cancellationToken)
{
var processor = services.GetService<IImageProcessor>();
if (processor is null)
{
status.SetProcessor(false, new HashSet<ImageFormat>(), new HashSet<ImageFormat>());
logger.LogWarning("No image processor is registered: image uploads are unavailable.");
return;
}
try
{
await processor.SelfTestAsync(cancellationToken);
status.SetProcessor(true, processor.SupportedInput, processor.SupportedOutput);
}
catch (Exception exception) when (exception is not OperationCanceledException)
{
status.SetProcessor(false, new HashSet<ImageFormat>(), new HashSet<ImageFormat>());
logger.LogError(exception, "The image library self-test failed: image uploads are unavailable on this host.");
}
}
public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask;
}
+118
View File
@@ -0,0 +1,118 @@
using System.Globalization;
namespace SlpModularCms.Core.Media;
/// <summary>The image formats the media service knows. <see cref="Unknown"/> is never accepted.</summary>
public enum ImageFormat
{
Unknown = 0,
Jpeg,
Png,
Gif,
Bmp,
Tiff,
WebP,
Avif,
Heic,
}
public static class ImageFormatExtensions
{
public static string MimeType(this ImageFormat format) => format switch
{
ImageFormat.Jpeg => "image/jpeg",
ImageFormat.Png => "image/png",
ImageFormat.Gif => "image/gif",
ImageFormat.Bmp => "image/bmp",
ImageFormat.Tiff => "image/tiff",
ImageFormat.WebP => "image/webp",
ImageFormat.Avif => "image/avif",
ImageFormat.Heic => "image/heic",
_ => "application/octet-stream",
};
/// <summary>The file extension without a dot, as used in stored keys and media addresses.</summary>
public static string Extension(this ImageFormat format) => format switch
{
ImageFormat.Jpeg => "jpg",
ImageFormat.Png => "png",
ImageFormat.Gif => "gif",
ImageFormat.Bmp => "bmp",
ImageFormat.Tiff => "tif",
ImageFormat.WebP => "webp",
ImageFormat.Avif => "avif",
ImageFormat.Heic => "heic",
_ => "bin",
};
public static ImageFormat FromExtension(string extension) => extension.ToLowerInvariant() switch
{
"jpg" => ImageFormat.Jpeg,
"png" => ImageFormat.Png,
"gif" => ImageFormat.Gif,
"bmp" => ImageFormat.Bmp,
"tif" => ImageFormat.Tiff,
"webp" => ImageFormat.WebP,
"avif" => ImageFormat.Avif,
"heic" => ImageFormat.Heic,
_ => ImageFormat.Unknown,
};
}
/// <summary>What an image is, after orientation is applied. <paramref name="FrameCount"/> is 1 for a still image.</summary>
public sealed record ImageInfo(ImageFormat Format, int Width, int Height, int FrameCount, bool HasMetadata);
/// <summary>A named aspect ratio such as <c>wide</c> 3:2 (width:height).</summary>
public sealed record Ratio(string Name, int Numerator, int Denominator)
{
public static readonly Ratio Wide = new("wide", 3, 2);
public static readonly Ratio Tall = new("tall", 4, 5);
public double Value => (double)Numerator / Denominator;
}
/// <summary>
/// Where the subject is and how far to zoom: <see cref="X"/> and <see cref="Y"/> are fractions of the image width and
/// height (0 to 1, the centre is 0.5), <see cref="Zoom"/> is 1 to <see cref="MaxZoom"/>.
/// </summary>
public sealed record FocusSetting(double X, double Y, double Zoom)
{
public const double MaxZoom = 4.0;
public static readonly FocusSetting Centre = new(0.5, 0.5, 1.0);
public bool IsValid =>
X is >= 0 and <= 1 && Y is >= 0 and <= 1 && Zoom is >= 1 and <= MaxZoom
&& !double.IsNaN(X) && !double.IsNaN(Y) && !double.IsNaN(Zoom);
/// <summary>Clamps every value into its valid range (NaN becomes the default).</summary>
public FocusSetting Normalize() => new(
double.IsNaN(X) ? 0.5 : Math.Clamp(X, 0, 1),
double.IsNaN(Y) ? 0.5 : Math.Clamp(Y, 0, 1),
double.IsNaN(Zoom) ? 1.0 : Math.Clamp(Zoom, 1, MaxZoom));
/// <summary>The canonical text used inside the set hash: four decimals, invariant culture.</summary>
public string Canonical()
=> string.Create(CultureInfo.InvariantCulture, $"{Round(X)},{Round(Y)},{Round(Zoom)}");
private static string Round(double value) => Math.Round(value, 4).ToString("0.####", CultureInfo.InvariantCulture);
}
/// <summary>A rectangle in pixels of the oriented source image.</summary>
public readonly record struct CropRect(int X, int Y, int Width, int Height);
/// <summary>One output file to make: a ratio and width (and the height that follows), in one format, from one crop.</summary>
public sealed record VariantSpec(Ratio Ratio, int Width, int Height, ImageFormat Format, int Quality, CropRect Crop);
/// <summary>What to render for one ratio: the focus to cut around and the widths wanted when the source allows them.</summary>
public sealed record RatioPlan(Ratio Ratio, FocusSetting Focus, IReadOnlyList<int> Widths);
public sealed record RenderRequest(VariantSpec Variant);
public sealed record RenderedImage(byte[] Bytes, int Width, int Height, ImageFormat Format);
/// <summary>A parsed media address: <c>/media/{area}/{setHash}/{name}</c>.</summary>
public sealed record MediaAddress(string Area, string SetHash, string Name)
{
public string Key => $"{Area}/{SetHash}/{Name}";
}
@@ -0,0 +1,95 @@
using Microsoft.Extensions.Options;
namespace SlpModularCms.Core.Media;
/// <summary>An admitted upload: the bytes, what they are, and the processing slot, which is released on dispose.</summary>
public sealed class GuardedUpload(byte[] bytes, ImageInfo info, IDisposable slot) : IDisposable
{
public byte[] Bytes { get; } = bytes;
public ImageInfo Info { get; } = info;
public void Dispose() => slot.Dispose();
}
public interface IMediaUploadGuard
{
/// <summary>
/// The checks every image upload passes before anything is stored: availability, byte limit (counted while
/// reading, whatever the declared length says), format from the signature, library inspection with pixel and side
/// limits, and a free processing slot.
/// </summary>
/// <exception cref="ImageRejectedException">The upload is refused; see <see cref="ImageRejectedException.Code"/>.</exception>
Task<GuardedUpload> AdmitAsync(Stream upload, long declaredLength, CancellationToken cancellationToken);
}
public sealed class MediaUploadGuard(
IImageProcessor processor,
MediaProcessingGate gate,
MediaStatus status,
IOptions<MediaOptions> options) : IMediaUploadGuard
{
public async Task<GuardedUpload> AdmitAsync(Stream upload, long declaredLength, CancellationToken cancellationToken)
{
var limits = options.Value;
if (!status.UploadsAvailable)
{
throw new ImageRejectedException(ImageRejection.Unavailable, "Image uploads are not available on this host.");
}
if (declaredLength > limits.MaxUploadBytes)
{
throw new ImageRejectedException(ImageRejection.TooLarge, "The declared length is above the upload limit.");
}
var slot = await gate.EnterAsync(cancellationToken);
try
{
var bytes = await ReadLimitedAsync(upload, limits.MaxUploadBytes, cancellationToken);
var format = ImageSignature.Detect(bytes.AsSpan(0, Math.Min(bytes.Length, ImageSignature.HeaderLength)));
if (format == ImageFormat.Unknown || !processor.SupportedInput.Contains(format))
{
throw new ImageRejectedException(ImageRejection.UnsupportedFormat, "The file is not a supported image format.");
}
var info = await processor.InspectAsync(bytes, format, cancellationToken);
if (info.Width <= 0 || info.Height <= 0
|| info.Width > limits.MaxSide || info.Height > limits.MaxSide
|| (long)info.Width * info.Height > limits.MaxPixels)
{
throw new ImageRejectedException(ImageRejection.TooManyPixels, "The image is larger than the pixel limit.");
}
return new GuardedUpload(bytes, info, slot);
}
catch
{
slot.Dispose();
throw;
}
}
private static async Task<byte[]> ReadLimitedAsync(Stream upload, long limit, CancellationToken cancellationToken)
{
using var buffer = new MemoryStream();
var chunk = new byte[81920];
int read;
while ((read = await upload.ReadAsync(chunk, cancellationToken)) > 0)
{
if (buffer.Length + read > limit)
{
throw new ImageRejectedException(ImageRejection.TooLarge, "The upload is above the size limit.");
}
buffer.Write(chunk, 0, read);
}
if (buffer.Length == 0)
{
throw new ImageRejectedException(ImageRejection.Corrupt, "The upload is empty.");
}
return buffer.ToArray();
}
}
@@ -0,0 +1,67 @@
namespace SlpModularCms.Core.Media;
/// <summary>Decides which files to make from an image: per ratio the crop and the widths, per width the formats. Pure.</summary>
public static class VariantPlanner
{
public const int WebPQuality = 80;
public const int AvifQuality = 50;
public const int JpegQuality = 82;
/// <summary>The widths per ratio of the first version of the hero (never above the source: see <see cref="Plan"/>).</summary>
public static IReadOnlyList<int> DefaultWidths(Ratio ratio) => ratio.Name switch
{
"wide" => [640, 960, 1280, 1600, 2560],
"tall" => [480, 640, 960, 1280],
_ => [640, 960, 1280],
};
/// <summary>
/// For every ratio: the crop around the focus, then the widths that are not wider than the crop (an image is never
/// scaled up); when the crop is narrower than the smallest wanted width, one variant at the crop width. Each width is
/// planned in WebP, and in AVIF when <paramref name="outputs"/> contains it. WebP is required: without WebP the
/// plan falls back to JPEG so a platform without a WebP encoder still publishes something.
/// </summary>
public static IReadOnlyList<VariantSpec> Plan(
int sourceWidth,
int sourceHeight,
IReadOnlyList<RatioPlan> ratios,
IReadOnlySet<ImageFormat> outputs)
{
var formats = new List<(ImageFormat Format, int Quality)>();
if (outputs.Contains(ImageFormat.WebP))
{
formats.Add((ImageFormat.WebP, WebPQuality));
}
else
{
formats.Add((ImageFormat.Jpeg, JpegQuality));
}
if (outputs.Contains(ImageFormat.Avif))
{
formats.Add((ImageFormat.Avif, AvifQuality));
}
var result = new List<VariantSpec>();
foreach (var plan in ratios)
{
var crop = FocusMath.CropFor(sourceWidth, sourceHeight, plan.Ratio, plan.Focus);
var widths = plan.Widths.Where(w => w > 0 && w <= crop.Width).Distinct().OrderBy(w => w).ToList();
if (widths.Count == 0)
{
widths.Add(crop.Width);
}
foreach (var width in widths)
{
var height = Math.Max(1, (int)Math.Round(width * (double)plan.Ratio.Denominator / plan.Ratio.Numerator));
foreach (var (format, quality) in formats)
{
result.Add(new VariantSpec(plan.Ratio, width, height, format, quality, crop));
}
}
}
return result;
}
}