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
+1
View File
@@ -4,6 +4,7 @@
"projects": [
"src\\SlpModularCms.Api\\SlpModularCms.Api.csproj",
"src\\SlpModularCms.Core\\SlpModularCms.Core.csproj",
"src\\SlpModularCms.Core.Media.Magick\\SlpModularCms.Core.Media.Magick.csproj",
"src\\SlpModularCms.Core.Tests\\SlpModularCms.Core.Tests.csproj",
"src\\SlpModularCms.Modules.Availability\\SlpModularCms.Modules.Availability.csproj",
"src\\SlpModularCms.Modules.Availability.Tests\\SlpModularCms.Modules.Availability.Tests.csproj",
+15
View File
@@ -44,6 +44,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SlpModularCms.Modules.Conta
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SlpModularCms.Modules.Contact.Tests", "src\SlpModularCms.Modules.Contact.Tests\SlpModularCms.Modules.Contact.Tests.csproj", "{06C25AF5-D63F-4007-8796-C4BA27940EBA}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SlpModularCms.Core.Media.Magick", "src\SlpModularCms.Core.Media.Magick\SlpModularCms.Core.Media.Magick.csproj", "{9EAC8A27-8DB0-4E3B-B144-280882828DE8}"
EndProject
Global
GlobalSection(SolutionConfigurationPlatforms) = preSolution
Debug|Any CPU = Debug|Any CPU
@@ -258,6 +260,18 @@ Global
{06C25AF5-D63F-4007-8796-C4BA27940EBA}.Release|x64.Build.0 = Release|Any CPU
{06C25AF5-D63F-4007-8796-C4BA27940EBA}.Release|x86.ActiveCfg = Release|Any CPU
{06C25AF5-D63F-4007-8796-C4BA27940EBA}.Release|x86.Build.0 = Release|Any CPU
{9EAC8A27-8DB0-4E3B-B144-280882828DE8}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{9EAC8A27-8DB0-4E3B-B144-280882828DE8}.Debug|Any CPU.Build.0 = Debug|Any CPU
{9EAC8A27-8DB0-4E3B-B144-280882828DE8}.Debug|x64.ActiveCfg = Debug|Any CPU
{9EAC8A27-8DB0-4E3B-B144-280882828DE8}.Debug|x64.Build.0 = Debug|Any CPU
{9EAC8A27-8DB0-4E3B-B144-280882828DE8}.Debug|x86.ActiveCfg = Debug|Any CPU
{9EAC8A27-8DB0-4E3B-B144-280882828DE8}.Debug|x86.Build.0 = Debug|Any CPU
{9EAC8A27-8DB0-4E3B-B144-280882828DE8}.Release|Any CPU.ActiveCfg = Release|Any CPU
{9EAC8A27-8DB0-4E3B-B144-280882828DE8}.Release|Any CPU.Build.0 = Release|Any CPU
{9EAC8A27-8DB0-4E3B-B144-280882828DE8}.Release|x64.ActiveCfg = Release|Any CPU
{9EAC8A27-8DB0-4E3B-B144-280882828DE8}.Release|x64.Build.0 = Release|Any CPU
{9EAC8A27-8DB0-4E3B-B144-280882828DE8}.Release|x86.ActiveCfg = Release|Any CPU
{9EAC8A27-8DB0-4E3B-B144-280882828DE8}.Release|x86.Build.0 = Release|Any CPU
EndGlobalSection
GlobalSection(SolutionProperties) = preSolution
HideSolutionNode = FALSE
@@ -282,5 +296,6 @@ Global
{759EE53D-EECA-4054-A17F-4172B0EC2015} = {D72703E6-B021-4360-B1EE-0E99999B5899}
{59F64DD2-DF30-4F78-A3B7-2AB6A769ED6C} = {30D8F44D-4B6E-4980-8D1F-29D1A64F438C}
{06C25AF5-D63F-4007-8796-C4BA27940EBA} = {77DF6642-7863-4D67-BAEE-217EC2D99894}
{9EAC8A27-8DB0-4E3B-B144-280882828DE8} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
EndGlobalSection
EndGlobal
@@ -53,7 +53,7 @@
- [x] NFR Requirements (construction/nfr-requirements/)
- [x] NFR Design (construction/nfr-design/)
- [x] Infrastructure Design (media directory; construction/infrastructure-design/)
- [ ] Code Generation - EXECUTE (per unit H0 to H6)
- [ ] Code Generation - per unit: H0 done, H1 done (image pipeline), H2 to H6 open
- [ ] Build and Test - EXECUTE
### 🟡 OPERATIONS PHASE
- [ ] SKIP (Q19 = B; points go into the joint production checklist)
@@ -0,0 +1,26 @@
# H1 Image pipeline: code summary
Built 2026-11-16 on `feature/hero-module`. Build and tests of the unit run green (Core tests 876 of 876, of which 79 are new; the CI solution filter builds).
## What was built
| Area | Files |
|---|---|
| Types, options, rejection | `Core/Media/MediaTypes.cs` (`ImageFormat`, `ImageInfo`, `Ratio` wide 3:2 and tall 4:5, `FocusSetting`, `CropRect`, `VariantSpec`, `RatioPlan`, `RenderedImage`, `MediaAddress`), `Core/Media/ImageProcessing.cs` (`ImageRejection`, `ImageRejectedException` with stable codes, `MediaOptions`, `IImageProcessor`, `MediaStatus`, `MediaProcessingGate`) |
| Pure functions | `ImageSignature` (format from the first bytes; SVG, PDF, executables never recognised), `FocusMath` (crop around the focus, round-half-up so the TypeScript twin matches), `VariantPlanner` (widths never above the crop, WebP always, AVIF when possible, JPEG when WebP is missing), `MediaPaths` (set hash, address, strict allow-listed parser) |
| Guard | `MediaUploadGuard` (availability, counted byte limit, signature, library inspection with pixel and side limits, processing slot), `GuardedUpload` |
| Registration and self-test | `MediaServiceCollectionExtensions.AddCmsMedia`, `ImageProcessorSelfTest` (hosted; a failed self-test only turns uploads off) |
| Library | new project `SlpModularCms.Core.Media.Magick` (`MagickImageProcessor`, `AddMagickImageProcessor`), Magick.NET-Q8-AnyCPU 15.1.0. Deviation from the design text: the library lives in its own project so that hosts that never process images (the slave) do not carry the 35 MB native library; the abstractions stay in Core |
| Tests | `Core.Tests/Media/`: pure functions with FsCheck properties (crop inside the image, focus inside the crop, ratio kept, zoom monotonic, planner never upscales, ladder ascending, signature never throws on random input), known vectors shared with the future TypeScript twin, address tests (including path tricks), signature tests, guard tests (limits, busy, unavailable), Magick processor tests on generated fixtures (formats, orientation, animated GIF, metadata stripped, crop keeps the chosen side, AVIF output, truncated and garbage files, mismatched format, strip of metadata) |
| Solution | project added to `SlpModularCms.sln` (folder Application) and `SlpModularCms.Ci.slnf` |
## Decisions made while building
- Truncated or damaged files are rejected as `corrupt`: the library returns a partly decoded picture with a warning for them, so decode warnings that mean damage (premature end, truncated, corrupt, ...) are turned into a rejection.
- The orientation is applied before cropping and `InspectAsync` reports the oriented size, so the plan and the crop always use the same numbers.
- HEIC stays a declared capability only; no real HEIC test photo yet (to add when one is available, per Bryan).
- The original is stored as received unless it carries metadata: `StripMetadataAsync` removes it (the pixels are re-encoded at quality 92 or the source quality, whichever is higher).
## Not done in this unit (planned elsewhere)
Media store, endpoint and directory check (H3); the `Hero:*` options and the rate-limit policies (H2/H3); the self-contained publish check of the native library (done with the first project that references it, H2).
@@ -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;
}
}