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,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();
}
}
}
}