H3: mediaopslag in een map buiten de release, /media-endpoint (immutable, 404 voor al het andere), mapcontrole en snelheidsbeleid

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-16 15:21:08 +01:00
co-authored by Claude Sonnet 5.5
parent 3a50c9750e
commit 43925cbf37
7 changed files with 819 additions and 2 deletions
@@ -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;
}
}