Hero-module: hero beheren vanuit het CMS #17

Merged
Sluijsens merged 48 commits from feature/hero-module into master 2026-11-17 12:55:14 +01:00
7 changed files with 819 additions and 2 deletions
Showing only changes of commit 43925cbf37 - Show all commits
@@ -0,0 +1,13 @@
# H3 Media store and serving: code summary
Built 2026-11-16. Core tests green (Core.Tests, Media area 115 tests; the whole Core suite passes).
| Area | What |
|---|---|
| Store | `IMediaStore` and `FileSystemMediaStore` (`Core/Media/MediaStore.cs`): atomic set writes (temp directory, then one move; a failed write leaves nothing visible), plain file writes for originals, strict key allow-list (segments of lower-case letters, digits, dot, underscore and dash; at most four; the result must stay inside the root), list and delete of sets, total bytes, free space, writable probe. A database store can replace it later |
| Serving | `MediaEndpoint.MapCmsMedia` (`GET` and `HEAD /media/{**path}`): anonymous and marked as a public-site endpoint, rate-limit policy `media-public`, only addresses of the exact scheme in a registered area, immutable cache header, strong ETag and 304, `nosniff`; every other case is the same empty 404; originals are never reachable |
| Registration | `AddCmsMedia` (options bound from `Media:*`, store, gate, status, guard, self-test and directory check) and `AddCmsMediaArea("hero")`; `MediaDirectoryCheck` probes the directory at start-up (uploads off when missing or not writable) and warns above 80 percent of `Media:MaxTotalBytes`; wired into `CmsHost` (after `MapControllers`) |
| Rate limits | policies `hero-public` (120 per 60 s), `media-public` (600 per 60 s) and `hero-upload` (20 per hour per signed-in user) added next to `offerings-public` |
| Tests | store (atomicity, traversal and bad keys, replace, list, count, probe, free space), endpoint (headers, avif type, 304, HEAD, ten kinds of 404 including encoded traversal, method not allowed, no endpoint without a registered area), directory check |
Not in this unit: the retire-and-clean-up service (needs the Hero tables, built with H2), the free-space and total-size checks at upload time (H2, `HeroImageService`).
@@ -0,0 +1,317 @@
using FluentAssertions;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.TestHost;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging.Abstractions;
using Microsoft.Extensions.Options;
using NSubstitute;
using SlpModularCms.Core.Media;
namespace SlpModularCms.Core.Tests.Media;
public sealed class TempMedia : IDisposable
{
public string Directory { get; } = Path.Combine(Path.GetTempPath(), "slp-media-tests-" + Guid.NewGuid().ToString("N"));
public FileSystemMediaStore Store { get; }
public TempMedia() => Store = new FileSystemMediaStore(Options.Create(new MediaOptions { Directory = Directory }));
public void Dispose()
{
if (System.IO.Directory.Exists(Directory))
{
System.IO.Directory.Delete(Directory, recursive: true);
}
}
}
public class FileSystemMediaStoreTests
{
private const string Hash = "0123456789abcdef";
[Fact]
public async Task ASet_IsWrittenAtOnce_AndCanBeReadBack()
{
using var media = new TempMedia();
await media.Store.PutSetAsync("hero", Hash, new Dictionary<string, byte[]> { ["wide-960.webp"] = [1, 2, 3], ["tall-640.webp"] = [4, 5] }, CancellationToken.None);
await using var file = (await media.Store.OpenReadAsync($"hero/{Hash}/wide-960.webp", CancellationToken.None))!.Content;
var bytes = new MemoryStream();
await file.CopyToAsync(bytes);
bytes.ToArray().Should().Equal(1, 2, 3);
(await media.Store.ExistsAsync($"hero/{Hash}/tall-640.webp", CancellationToken.None)).Should().BeTrue();
System.IO.Directory.Exists(Path.Combine(media.Directory, ".tmp")).Should().BeTrue();
System.IO.Directory.GetDirectories(Path.Combine(media.Directory, ".tmp")).Should().BeEmpty("no temporary set is left behind");
}
[Fact]
public async Task WritingTheSameSetTwice_KeepsTheFirst()
{
using var media = new TempMedia();
await media.Store.PutSetAsync("hero", Hash, new Dictionary<string, byte[]> { ["wide-960.webp"] = [1] }, CancellationToken.None);
await media.Store.PutSetAsync("hero", Hash, new Dictionary<string, byte[]> { ["wide-960.webp"] = [9, 9] }, CancellationToken.None);
await using var file = (await media.Store.OpenReadAsync($"hero/{Hash}/wide-960.webp", CancellationToken.None))!.Content;
file.Length.Should().Be(1);
}
[Fact]
public async Task AFailedWrite_LeavesNothingVisible()
{
using var media = new TempMedia();
var act = async () => await media.Store.PutSetAsync("hero", Hash, new Dictionary<string, byte[]> { ["ok-960.webp"] = [1], ["../evil.webp"] = [2] }, CancellationToken.None);
await act.Should().ThrowAsync<ArgumentException>();
(await media.Store.ListSetsAsync("hero", CancellationToken.None)).Should().BeEmpty();
}
[Theory]
[InlineData("../secret")]
[InlineData("hero/../../secret")]
[InlineData("/etc/passwd")]
[InlineData("hero\\0123456789abcdef\\wide-960.webp")]
[InlineData("HERO/0123456789abcdef/wide-960.webp")]
[InlineData("hero/0123456789abcdef/wide 960.webp")]
[InlineData("hero/0123456789abcdef/.hidden")]
[InlineData("a/b/c/d/e")]
[InlineData("")]
public async Task AKeyOutsideTheAllowList_IsRefused(string key)
{
using var media = new TempMedia();
var act = async () => await media.Store.OpenReadAsync(key, CancellationToken.None);
await act.Should().ThrowAsync<ArgumentException>();
}
[Fact]
public async Task APlainFile_CanBeReplaced_AndDeleted()
{
using var media = new TempMedia();
await media.Store.PutAsync("originals/abc.jpg", new byte[] { 1 }, CancellationToken.None);
await media.Store.PutAsync("originals/abc.jpg", new byte[] { 1, 2 }, CancellationToken.None);
(await media.Store.OpenReadAsync("originals/abc.jpg", CancellationToken.None))!.Length.Should().Be(2);
await media.Store.DeleteAsync("originals/abc.jpg", CancellationToken.None);
(await media.Store.ExistsAsync("originals/abc.jpg", CancellationToken.None)).Should().BeFalse();
}
[Fact]
public async Task SetsAreListed_AndRemoved_AndCounted()
{
using var media = new TempMedia();
await media.Store.PutSetAsync("hero", Hash, new Dictionary<string, byte[]> { ["wide-960.webp"] = new byte[10] }, CancellationToken.None);
await media.Store.PutSetAsync("hero", "fedcba9876543210", new Dictionary<string, byte[]> { ["wide-960.webp"] = new byte[5] }, CancellationToken.None);
(await media.Store.ListSetsAsync("hero", CancellationToken.None)).Select(s => s.SetHash).Should().BeEquivalentTo(Hash, "fedcba9876543210");
(await media.Store.GetTotalBytesAsync(CancellationToken.None)).Should().Be(15);
await media.Store.DeleteSetAsync("hero", Hash, CancellationToken.None);
(await media.Store.ListSetsAsync("hero", CancellationToken.None)).Select(s => s.SetHash).Should().Equal("fedcba9876543210");
}
[Fact]
public async Task TheProbe_CreatesTheDirectory_WhenItIsMissing()
{
using var media = new TempMedia();
(await media.Store.ProbeAsync(CancellationToken.None)).Should().BeTrue();
System.IO.Directory.Exists(media.Directory).Should().BeTrue();
}
[Fact]
public async Task WithoutADirectory_NothingIsAvailable()
{
var store = new FileSystemMediaStore(Options.Create(new MediaOptions()));
(await store.ProbeAsync(CancellationToken.None)).Should().BeFalse();
(await store.OpenReadAsync("hero/0123456789abcdef/wide-960.webp", CancellationToken.None)).Should().BeNull();
store.GetFreeBytes().Should().BeNull();
}
[Fact]
public async Task TheFreeSpace_IsReportedForAnExistingVolume()
{
using var media = new TempMedia();
await media.Store.ProbeAsync(CancellationToken.None);
media.Store.GetFreeBytes().Should().BeGreaterThan(0);
}
}
public class MediaEndpointTests : IAsyncLifetime
{
private const string Hash = "0123456789abcdef";
private readonly TempMedia _media = new();
private IHost _host = null!;
private HttpClient _client = null!;
public async Task InitializeAsync()
{
await _media.Store.PutSetAsync("hero", Hash, new Dictionary<string, byte[]> { ["wide-960.webp"] = [1, 2, 3, 4], ["tall-640.avif"] = [9] }, CancellationToken.None);
await _media.Store.PutAsync("originals/secret.jpg", new byte[] { 7 }, CancellationToken.None);
_host = await new HostBuilder().ConfigureWebHost(web => web
.UseTestServer()
.ConfigureServices(services =>
{
services.AddRouting();
services.AddSingleton<IMediaStore>(_media.Store);
services.AddSingleton(new MediaAreaRegistry());
services.AddSingleton(new MediaAreaRegistration("hero"));
})
.Configure(app =>
{
app.UseRouting();
app.UseEndpoints(endpoints => endpoints.MapCmsMedia());
})).StartAsync();
_client = _host.GetTestClient();
}
public async Task DisposeAsync()
{
_client.Dispose();
await _host.StopAsync();
_host.Dispose();
_media.Dispose();
}
[Fact]
public async Task AStoredFile_IsServed_WithTheImmutableHeaders()
{
var response = await _client.GetAsync($"/media/hero/{Hash}/wide-960.webp");
response.StatusCode.Should().Be(System.Net.HttpStatusCode.OK);
response.Content.Headers.ContentType!.MediaType.Should().Be("image/webp");
response.Headers.CacheControl!.ToString().Should().Be("public, max-age=31536000, immutable");
response.Headers.ETag!.Tag.Should().Be($"\"{Hash}-wide-960.webp\"");
response.Headers.GetValues("X-Content-Type-Options").Should().Equal("nosniff");
(await response.Content.ReadAsByteArrayAsync()).Should().Equal(1, 2, 3, 4);
}
[Fact]
public async Task AnAvifFile_HasItsOwnContentType()
{
var response = await _client.GetAsync($"/media/hero/{Hash}/tall-640.avif");
response.Content.Headers.ContentType!.MediaType.Should().Be("image/avif");
}
[Fact]
public async Task AMatchingEtag_GivesNotModified()
{
var request = new HttpRequestMessage(HttpMethod.Get, $"/media/hero/{Hash}/wide-960.webp");
request.Headers.IfNoneMatch.ParseAdd($"\"{Hash}-wide-960.webp\"");
var response = await _client.SendAsync(request);
response.StatusCode.Should().Be(System.Net.HttpStatusCode.NotModified);
}
[Fact]
public async Task Head_HasTheHeadersAndNoBody()
{
var response = await _client.SendAsync(new HttpRequestMessage(HttpMethod.Head, $"/media/hero/{Hash}/wide-960.webp"));
response.StatusCode.Should().Be(System.Net.HttpStatusCode.OK);
response.Content.Headers.ContentLength.Should().Be(4);
(await response.Content.ReadAsByteArrayAsync()).Should().BeEmpty();
}
[Theory]
[InlineData("/media/hero/0123456789abcdef/missing-960.webp")]
[InlineData("/media/hero/0123456789abcdef/wide-960.png")]
[InlineData("/media/other/0123456789abcdef/wide-960.webp")]
[InlineData("/media/originals/secret.jpg")]
[InlineData("/media/hero/0123456789abcdef/")]
[InlineData("/media/hero/")]
[InlineData("/media/")]
[InlineData("/media/hero/0123456789abcdef/..%2f..%2fsecret.jpg")]
[InlineData("/media/hero/..%5c..%5cwide-960.webp")]
[InlineData("/media/%2e%2e/%2e%2e/etc/passwd")]
public async Task EverythingElse_IsAPlain404(string url)
{
var response = await _client.GetAsync(url);
response.StatusCode.Should().Be(System.Net.HttpStatusCode.NotFound);
(await response.Content.ReadAsStringAsync()).Should().BeEmpty();
}
[Fact]
public async Task OtherMethods_AreNotAllowed()
{
var response = await _client.PostAsync($"/media/hero/{Hash}/wide-960.webp", new ByteArrayContent([1]));
response.StatusCode.Should().Be(System.Net.HttpStatusCode.MethodNotAllowed);
}
[Fact]
public async Task WithoutARegisteredArea_NoEndpointExists()
{
using var host = await new HostBuilder().ConfigureWebHost(web => web
.UseTestServer()
.ConfigureServices(services =>
{
services.AddRouting();
services.AddSingleton<IMediaStore>(_media.Store);
services.AddSingleton(new MediaAreaRegistry());
})
.Configure(app =>
{
app.UseRouting();
app.UseEndpoints(endpoints => endpoints.MapCmsMedia());
})).StartAsync();
var response = await host.GetTestClient().GetAsync($"/media/hero/{Hash}/wide-960.webp");
response.StatusCode.Should().Be(System.Net.HttpStatusCode.NotFound);
}
}
public class MediaDirectoryCheckTests
{
private static MediaDirectoryCheck Check(IMediaStore store, MediaStatus status, MediaAreaRegistry areas, string? directory, params string[] registered)
=> new(store, status, areas, registered.Select(a => new MediaAreaRegistration(a)), Options.Create(new MediaOptions { Directory = directory }), NullLogger<MediaDirectoryCheck>.Instance);
[Fact]
public async Task AWritableDirectory_TurnsUploadsOn_AndRegistersTheAreas()
{
using var media = new TempMedia();
var status = new MediaStatus();
var areas = new MediaAreaRegistry();
await Check(media.Store, status, areas, media.Directory, "hero").StartAsync(CancellationToken.None);
status.DirectoryWritable.Should().BeTrue();
areas.Contains("hero").Should().BeTrue();
}
[Fact]
public async Task AMissingConfiguration_TurnsUploadsOff()
{
var status = new MediaStatus();
status.SetDirectory(true);
await Check(Substitute.For<IMediaStore>(), status, new MediaAreaRegistry(), null).StartAsync(CancellationToken.None);
status.DirectoryWritable.Should().BeFalse();
}
[Fact]
public async Task AnUnwritableDirectory_TurnsUploadsOff()
{
var store = Substitute.For<IMediaStore>();
store.ProbeAsync(default).ReturnsForAnyArgs(false);
var status = new MediaStatus();
await Check(store, status, new MediaAreaRegistry(), "/somewhere").StartAsync(CancellationToken.None);
status.DirectoryWritable.Should().BeFalse();
}
}
@@ -3,6 +3,7 @@ using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using SlpModularCms.Core.Media;
using SlpModularCms.Core.Hosting.Health;
using SlpModularCms.Core.Hosting.Observability;
using SlpModularCms.Core.Hosting.Proxy;
@@ -165,6 +166,9 @@ public static class CmsHost
app.MapControllers();
// Stored media (hero images and other modules with a media area): anonymous, immutable, only registered areas.
app.MapCmsMedia();
// Infrastructure liveness. Deliberately outside /api/v1 and on the availability gate's bypass
// list: this reports whether the process is alive, which is a different question from whether
// the CMS is switched on (/api/v1/Availability/status) or which modules it carries
@@ -279,6 +279,42 @@ public static class ServiceCollectionExtensions
QueueLimit = 0
});
});
// The public hero read, the media files the pages load, and image uploads (per signed-in user, a few per hour).
options.AddPolicy("hero-public", context =>
{
var settings = configuration.GetSection("RateLimiting:HeroPublic");
return RateLimitPartition.GetFixedWindowLimiter(ClientPartitionKey.For(context), _ => new FixedWindowRateLimiterOptions
{
PermitLimit = settings.GetValue<int>("PermitLimit", 120),
Window = TimeSpan.FromSeconds(settings.GetValue<int>("WindowSeconds", 60)),
QueueLimit = 0
});
});
options.AddPolicy("media-public", context =>
{
var settings = configuration.GetSection("RateLimiting:MediaPublic");
return RateLimitPartition.GetFixedWindowLimiter(ClientPartitionKey.For(context), _ => new FixedWindowRateLimiterOptions
{
PermitLimit = settings.GetValue<int>("PermitLimit", 600),
Window = TimeSpan.FromSeconds(settings.GetValue<int>("WindowSeconds", 60)),
QueueLimit = 0
});
});
options.AddPolicy("hero-upload", context =>
{
var settings = configuration.GetSection("RateLimiting:HeroUpload");
var user = context.User.Identity?.Name;
var key = string.IsNullOrEmpty(user) ? ClientPartitionKey.For(context) : "user:" + user;
return RateLimitPartition.GetFixedWindowLimiter(key, _ => new FixedWindowRateLimiterOptions
{
PermitLimit = settings.GetValue<int>("PermitLimit", 20),
Window = TimeSpan.FromSeconds(settings.GetValue<int>("WindowSeconds", 3600)),
QueueLimit = 0
});
});
});
return services;
@@ -0,0 +1,78 @@
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Routing;
using Microsoft.Extensions.DependencyInjection;
using SlpModularCms.Core.Availability;
namespace SlpModularCms.Core.Media;
public static class MediaEndpoint
{
public const string RateLimiterName = "media-public";
/// <summary>
/// <c>GET|HEAD /media/{area}/{setHash}/{name}</c>: anonymous, same origin, immutable. Only addresses of the exact
/// scheme in a registered area are served; everything else (a bad path, an unknown area, a missing file) is the same
/// plain 404. No directory is ever listed and no processing happens on this path.
/// </summary>
public static IEndpointRouteBuilder MapCmsMedia(this IEndpointRouteBuilder endpoints)
{
// The areas are known from the modules' registrations at the time the routes are mapped (before the hosted
// services run), so they are copied into the registry here.
var registrations = endpoints.ServiceProvider.GetServices<MediaAreaRegistration>().ToList();
if (registrations.Count == 0 || endpoints.ServiceProvider.GetService<MediaAreaRegistry>() is not { } registry)
{
return endpoints;
}
foreach (var registration in registrations)
{
registry.Add(registration.Area);
}
endpoints.MapMethods("/media/{**path}", ["GET", "HEAD"], ServeAsync)
.WithMetadata(new PublicSiteEndpointAttribute())
.RequireRateLimiting(RateLimiterName)
.ExcludeFromDescription();
return endpoints;
}
private static async Task<IResult> ServeAsync(string? path, HttpContext context, IMediaStore store, MediaAreaRegistry areas)
{
if (!MediaPaths.TryParse(path, out var address)
|| !areas.Contains(address.Area)
|| !MediaPaths.TryParseName(address.Name, out _, out _, out var format))
{
return Results.NotFound();
}
var file = await store.OpenReadAsync(address.Key, context.RequestAborted);
if (file is null)
{
return Results.NotFound();
}
var response = context.Response;
var etag = $"\"{address.SetHash}-{address.Name}\"";
response.Headers.CacheControl = "public, max-age=31536000, immutable";
response.Headers.ETag = etag;
response.Headers["X-Content-Type-Options"] = "nosniff";
var ifNoneMatch = context.Request.Headers.IfNoneMatch.ToString();
if (ifNoneMatch.Split(',').Select(t => t.Trim()).Contains(etag))
{
await file.Content.DisposeAsync();
return Results.StatusCode(StatusCodes.Status304NotModified);
}
response.ContentType = format.MimeType();
response.ContentLength = file.Length;
if (HttpMethods.IsHead(context.Request.Method))
{
await file.Content.DisposeAsync();
return Results.Empty;
}
return Results.Stream(file.Content, format.MimeType(), enableRangeProcessing: false);
}
}
@@ -13,19 +13,79 @@ public static class MediaServiceCollectionExtensions
/// 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)
public static IServiceCollection AddCmsMedia(this IServiceCollection services)
{
services.AddOptions<MediaOptions>().Bind(configuration.GetSection(MediaOptions.SectionName));
services.AddOptions<MediaOptions>().Configure<IConfiguration>((options, configuration) =>
configuration.GetSection(MediaOptions.SectionName).Bind(options));
services.TryAddSingleton<MediaProcessingGate>();
services.TryAddSingleton<MediaStatus>();
services.TryAddSingleton<MediaAreaRegistry>();
services.TryAddSingleton<IMediaStore, FileSystemMediaStore>();
services.TryAddSingleton<IMediaUploadGuard, MediaUploadGuard>();
if (!services.Any(d => d.ImplementationType == typeof(ImageProcessorSelfTest)))
{
services.AddHostedService<ImageProcessorSelfTest>();
services.AddHostedService<MediaDirectoryCheck>();
}
return services;
}
/// <summary>Lets the <c>/media</c> endpoint serve the given area (for example <c>hero</c>).</summary>
public static IServiceCollection AddCmsMediaArea(this IServiceCollection services, string area)
{
services.AddCmsMedia();
services.AddSingleton(new MediaAreaRegistration(area));
return services;
}
}
/// <summary>A module declares the media area it owns; the host adds all of them to the <see cref="MediaAreaRegistry"/> at start-up.</summary>
public sealed record MediaAreaRegistration(string Area);
/// <summary>
/// At start-up, proves that the media directory exists (creating it when needed) and is writable, fills the area
/// registry and warns when the directory fills up. A failure only turns image uploads off; files that are already
/// stored keep being served.
/// </summary>
public sealed class MediaDirectoryCheck(
IMediaStore store,
MediaStatus status,
MediaAreaRegistry areas,
IEnumerable<MediaAreaRegistration> registrations,
Microsoft.Extensions.Options.IOptions<MediaOptions> options,
ILogger<MediaDirectoryCheck> logger) : IHostedService
{
public async Task StartAsync(CancellationToken cancellationToken)
{
foreach (var registration in registrations)
{
areas.Add(registration.Area);
}
if (string.IsNullOrWhiteSpace(options.Value.Directory))
{
status.SetDirectory(false);
logger.LogWarning("Media:Directory is not configured: image uploads are unavailable on this host.");
return;
}
var writable = await store.ProbeAsync(cancellationToken);
status.SetDirectory(writable);
if (!writable)
{
logger.LogError("The media directory is missing or not writable: image uploads are unavailable until it is fixed.");
return;
}
var total = await store.GetTotalBytesAsync(cancellationToken);
if (options.Value.MaxTotalBytes > 0 && total > options.Value.MaxTotalBytes * 8 / 10)
{
logger.LogError("The media directory is over 80 percent of its safety limit ({Bytes} bytes).", total);
}
}
public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask;
}
/// <summary>
+309
View File
@@ -0,0 +1,309 @@
using System.Text.RegularExpressions;
using Microsoft.Extensions.Options;
namespace SlpModularCms.Core.Media;
/// <summary>An opened stored file. The caller disposes <see cref="Content"/>.</summary>
public sealed record MediaFile(Stream Content, long Length, DateTimeOffset LastModified);
/// <summary>A stored set of files (one directory under an area) and when it was written.</summary>
public sealed record MediaSetInfo(string Area, string SetHash, DateTimeOffset CreatedUtc);
/// <summary>
/// Where media files live. Keys are relative, lower-case, slash-separated paths made by the code (never from a client
/// file name). The file-system implementation keeps them in a directory outside the release; a database
/// implementation can replace it without touching the modules.
/// </summary>
public interface IMediaStore
{
/// <summary>Writes a whole set (all the files of one set hash) so that it appears at once or not at all. Writing a set that already exists is a no-op: sets are content addressed.</summary>
Task PutSetAsync(string area, string setHash, IReadOnlyDictionary<string, byte[]> files, CancellationToken cancellationToken);
/// <summary>Writes one file (used for originals). An existing file with the same key is replaced.</summary>
Task PutAsync(string key, ReadOnlyMemory<byte> content, CancellationToken cancellationToken);
Task<MediaFile?> OpenReadAsync(string key, CancellationToken cancellationToken);
Task<bool> ExistsAsync(string key, CancellationToken cancellationToken);
Task DeleteAsync(string key, CancellationToken cancellationToken);
/// <summary>Removes a whole set directory.</summary>
Task DeleteSetAsync(string area, string setHash, CancellationToken cancellationToken);
Task<IReadOnlyList<MediaSetInfo>> ListSetsAsync(string area, CancellationToken cancellationToken);
Task<long> GetTotalBytesAsync(CancellationToken cancellationToken);
/// <summary>Free space on the volume, or null when it cannot be determined.</summary>
long? GetFreeBytes();
/// <summary>Creates the directory when needed and proves it is writable. False when it is not configured or not writable.</summary>
Task<bool> ProbeAsync(CancellationToken cancellationToken);
}
/// <summary>The areas the <c>/media</c> endpoint serves (for example <c>hero</c>); any other area is a 404.</summary>
public sealed class MediaAreaRegistry
{
private readonly HashSet<string> _areas = new(StringComparer.Ordinal);
public void Add(string area)
{
lock (_areas)
{
_areas.Add(area);
}
}
public bool Contains(string area)
{
lock (_areas)
{
return _areas.Contains(area);
}
}
public bool Any
{
get
{
lock (_areas)
{
return _areas.Count > 0;
}
}
}
}
public sealed partial class FileSystemMediaStore(IOptions<MediaOptions> options) : IMediaStore
{
[GeneratedRegex("^[a-z0-9][a-z0-9._-]{0,79}$", RegexOptions.CultureInvariant)]
private static partial Regex SegmentPattern();
private string? Root
{
get
{
var directory = options.Value.Directory;
return string.IsNullOrWhiteSpace(directory) ? null : Path.GetFullPath(directory);
}
}
public async Task PutSetAsync(string area, string setHash, IReadOnlyDictionary<string, byte[]> files, CancellationToken cancellationToken)
{
var root = RequireRoot();
var target = PathFor(root, area, setHash);
if (Directory.Exists(target))
{
return;
}
var temp = Path.Combine(root, ".tmp", Guid.NewGuid().ToString("N"));
Directory.CreateDirectory(temp);
try
{
foreach (var (name, bytes) in files)
{
await File.WriteAllBytesAsync(PathFor(temp, name), bytes, cancellationToken);
}
Directory.CreateDirectory(Path.GetDirectoryName(target)!);
try
{
Directory.Move(temp, target);
}
catch (IOException) when (Directory.Exists(target))
{
// A parallel upload of the same photo and focus produced the same set first: identical content.
}
}
finally
{
if (Directory.Exists(temp))
{
Directory.Delete(temp, recursive: true);
}
}
}
public async Task PutAsync(string key, ReadOnlyMemory<byte> content, CancellationToken cancellationToken)
{
var root = RequireRoot();
var path = PathFor(root, key);
Directory.CreateDirectory(Path.GetDirectoryName(path)!);
var temp = Path.Combine(root, ".tmp", Guid.NewGuid().ToString("N"));
Directory.CreateDirectory(Path.GetDirectoryName(temp)!);
try
{
await File.WriteAllBytesAsync(temp, content.ToArray(), cancellationToken);
File.Move(temp, path, overwrite: true);
}
finally
{
if (File.Exists(temp))
{
File.Delete(temp);
}
}
}
public Task<MediaFile?> OpenReadAsync(string key, CancellationToken cancellationToken)
{
var root = Root;
if (root is null)
{
return Task.FromResult<MediaFile?>(null);
}
var path = PathFor(root, key);
if (!File.Exists(path))
{
return Task.FromResult<MediaFile?>(null);
}
try
{
var info = new FileInfo(path);
var stream = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.ReadWrite | FileShare.Delete, 4096, FileOptions.Asynchronous | FileOptions.SequentialScan);
return Task.FromResult<MediaFile?>(new MediaFile(stream, info.Length, info.LastWriteTimeUtc));
}
catch (Exception exception) when (exception is IOException or UnauthorizedAccessException)
{
return Task.FromResult<MediaFile?>(null);
}
}
public Task<bool> ExistsAsync(string key, CancellationToken cancellationToken)
{
var root = Root;
return Task.FromResult(root is not null && File.Exists(PathFor(root, key)));
}
public Task DeleteAsync(string key, CancellationToken cancellationToken)
{
var root = Root;
if (root is not null)
{
var path = PathFor(root, key);
if (File.Exists(path))
{
File.Delete(path);
}
}
return Task.CompletedTask;
}
public Task DeleteSetAsync(string area, string setHash, CancellationToken cancellationToken)
{
var root = Root;
if (root is not null)
{
var path = PathFor(root, area, setHash);
if (Directory.Exists(path))
{
Directory.Delete(path, recursive: true);
}
}
return Task.CompletedTask;
}
public Task<IReadOnlyList<MediaSetInfo>> ListSetsAsync(string area, CancellationToken cancellationToken)
{
var root = Root;
var result = new List<MediaSetInfo>();
if (root is not null)
{
var areaPath = PathFor(root, area);
if (Directory.Exists(areaPath))
{
foreach (var directory in new DirectoryInfo(areaPath).EnumerateDirectories())
{
result.Add(new MediaSetInfo(area, directory.Name, directory.CreationTimeUtc));
}
}
}
return Task.FromResult<IReadOnlyList<MediaSetInfo>>(result);
}
public Task<long> GetTotalBytesAsync(CancellationToken cancellationToken)
{
var root = Root;
if (root is null || !Directory.Exists(root))
{
return Task.FromResult(0L);
}
return Task.FromResult(new DirectoryInfo(root).EnumerateFiles("*", SearchOption.AllDirectories).Sum(f => f.Length));
}
public long? GetFreeBytes()
{
var root = Root;
if (root is null)
{
return null;
}
try
{
var existing = root;
while (!Directory.Exists(existing) && Path.GetDirectoryName(existing) is { } parent)
{
existing = parent;
}
return new DriveInfo(Path.GetPathRoot(existing)!).AvailableFreeSpace;
}
catch (Exception exception) when (exception is IOException or ArgumentException or UnauthorizedAccessException)
{
return null;
}
}
public async Task<bool> ProbeAsync(CancellationToken cancellationToken)
{
var root = Root;
if (root is null)
{
return false;
}
try
{
var temp = Path.Combine(root, ".tmp");
Directory.CreateDirectory(temp);
var probe = Path.Combine(temp, "probe-" + Guid.NewGuid().ToString("N"));
await File.WriteAllBytesAsync(probe, [1, 2, 3], cancellationToken);
File.Delete(probe);
return true;
}
catch (Exception exception) when (exception is IOException or UnauthorizedAccessException)
{
return false;
}
}
private string RequireRoot()
=> Root ?? throw new InvalidOperationException("Media:Directory is not configured.");
/// <summary>Builds a path below the root from key segments; every segment is checked against a strict allow-list and the result must stay inside the root.</summary>
private static string PathFor(string root, params string[] keys)
{
var segments = keys.SelectMany(k => k.Split('/')).ToArray();
if (segments.Length is 0 or > 4 || segments.Any(s => !SegmentPattern().IsMatch(s) || s.Contains("..", StringComparison.Ordinal)))
{
throw new ArgumentException("Not a valid media key.", nameof(keys));
}
var full = Path.GetFullPath(Path.Combine([root, .. segments]));
if (!full.StartsWith(root + Path.DirectorySeparatorChar, StringComparison.Ordinal))
{
throw new ArgumentException("Not a valid media key.", nameof(keys));
}
return full;
}
}