Refactor file auth to use registry-based handler model

Introduced IUmbrellaFileAuthorizationHandlerRegistry and its default implementation to resolve file authorization handlers by directory or file info. Refactored UmbrellaFileStorageProvider and all derived providers to use the registry for authorization, removing handler lookup logic from options. Added built-in handlers for temp and dynamic image cache files. Updated DI registration for safe, idempotent handler and registry setup. Revised tests for the new model and added registry/authorization flow coverage. Added AddUmbrellaSharePointFileStorageProvider extension. All providers now require the registry in their constructors.

Author: ricardoeduardo

DynamicImage/src/Umbrella.DynamicImage.Abstractions/Caching/UmbrellaDynamicImageCacheFileAuthorizationHandler.cs

@@ -0,0 +1,26 @@
+using Umbrella.FileSystem.Abstractions;
+
+namespace Umbrella.DynamicImage.Abstractions.Caching;
+
+/// <summary>
+/// An authorization handler for files stored in the Dynamic Image cache directory.
+/// </summary>
+public sealed class UmbrellaDynamicImageCacheFileAuthorizationHandler : IUmbrellaFileAuthorizationHandler
+{
+	private readonly DynamicImageCacheCoreOptions _cacheCoreOptions;
+
+	/// <summary>
+	/// Initializes a new instance of the <see cref="UmbrellaDynamicImageCacheFileAuthorizationHandler"/> class.
+	/// </summary>
+	/// <param name="cacheCoreOptions">The cache core options.</param>
+	public UmbrellaDynamicImageCacheFileAuthorizationHandler(DynamicImageCacheCoreOptions cacheCoreOptions)
+	{
+		_cacheCoreOptions = cacheCoreOptions;
+	}
+
+	/// <inheritdoc/>
+	public string DirectoryName => _cacheCoreOptions.DirectoryName;
+
+	/// <inheritdoc/>
+	public Task<bool> AuthorizeAsync(IUmbrellaFileInfo fileInfo, UmbrellaFileOperationType operationType, CancellationToken cancellationToken = default) => Task.FromResult(true);
+}

DynamicImage/src/Umbrella.DynamicImage.Abstractions/Caching/UmbrellaDynamicImageCacheFileHandler.cs

@@ -36,7 +36,4 @@ public UmbrellaDynamicImageCacheFileHandler(
 
 	/// <inheritdoc/>
 	public override string DirectoryName => _cacheCoreOptions.DirectoryName;
-
-	/// <inheritdoc/>
-	public override Task<bool> AuthorizeAsync(IUmbrellaFileInfo fileInfo, UmbrellaFileOperationType operationType, CancellationToken cancellationToken = default) => Task.FromResult(true);
-}
+}

DynamicImage/src/Umbrella.DynamicImage.Abstractions/IServiceCollectionExtensions.cs

@@ -1,7 +1,9 @@
 
 using CommunityToolkit.Diagnostics;
+using Microsoft.Extensions.DependencyInjection.Extensions;
 using Umbrella.DynamicImage.Abstractions;
 using Umbrella.DynamicImage.Abstractions.Caching;
+using Umbrella.FileSystem.Abstractions;
 
 #pragma warning disable IDE0130
 namespace Microsoft.Extensions.DependencyInjection;
@@ -45,11 +47,12 @@ public static IServiceCollection AddUmbrellaDynamicImage(this IServiceCollection
 	{
 		Guard.IsNotNull(services);
 
-		_ = services.AddSingleton<IDynamicImageUtility, DynamicImageUtility>();
-		_ = services.AddSingleton<IDynamicImageCache, DynamicImageNoCache>();
-		_ = services.AddSingleton<IUmbrellaDynamicImageCacheFileHandler, UmbrellaDynamicImageCacheFileHandler>();
-		_ = services.AddSingleton<DynamicImageCacheCoreOptions>();
+		services.TryAddSingleton<IDynamicImageUtility, DynamicImageUtility>();
+		services.TryAddSingleton<IDynamicImageCache, DynamicImageNoCache>();
+		services.TryAddSingleton<IUmbrellaDynamicImageCacheFileHandler>(static x => ActivatorUtilities.CreateInstance<UmbrellaDynamicImageCacheFileHandler>(x));
+		services.TryAddEnumerable(ServiceDescriptor.Singleton<IUmbrellaFileAuthorizationHandler, UmbrellaDynamicImageCacheFileAuthorizationHandler>());
+		services.TryAddSingleton<DynamicImageCacheCoreOptions>();
 
 		return services;
 	}
-}
+}

DynamicImage/test/Umbrella.DynamicImage.Test/Caching/DynamicImageCacheTest.cs

@@ -1,10 +1,10 @@
 
 using CommunityToolkit.Diagnostics;
-using Microsoft.Extensions.DependencyInjection;
 using Umbrella.DynamicImage.Abstractions;
 using Umbrella.DynamicImage.Abstractions.Caching;
 using Umbrella.DynamicImage.Caching.AzureStorage;
 using Umbrella.DynamicImage.Caching.Disk;
+using Umbrella.FileSystem.Abstractions;
 using Umbrella.FileSystem.AzureStorage;
 using Umbrella.FileSystem.Disk;
 using Umbrella.Internal.Mocks;
@@ -183,12 +183,11 @@ private static DynamicImageDiskCache CreateDynamicImageDiskCache()
 			AllowUnhandledFileAuthorizationChecks = true
 		};
 
-		options.Initialize(new ServiceCollection(), new ServiceCollection().BuildServiceProvider());
-
 		var provider = new UmbrellaDiskFileStorageProvider(
 			CoreUtilitiesMocks.CreateLoggerFactory<UmbrellaDiskFileStorageProvider>(),
 			CoreUtilitiesMocks.CreateMimeTypeUtility(("png", "image/png"), ("jpg,", "image/jpg")),
-			CoreUtilitiesMocks.CreateGenericTypeConverter());
+			CoreUtilitiesMocks.CreateGenericTypeConverter(),
+			CreateAuthorizationHandlerRegistry());
 
 		provider.InitializeOptions(options);
 
@@ -216,12 +215,11 @@ private static DynamicImageAzureBlobStorageCache CreateDynamicImageAzureBlobStor
 			AllowUnhandledFileAuthorizationChecks = true
 		};
 
-		options.Initialize(new ServiceCollection(), new ServiceCollection().BuildServiceProvider());
-
 		var provider = new UmbrellaAzureBlobStorageFileProvider(
 			CoreUtilitiesMocks.CreateLoggerFactory<UmbrellaAzureBlobStorageFileProvider>(),
 			CoreUtilitiesMocks.CreateMimeTypeUtility(("png", "image/png"), ("jpg,", "image/jpg")),
-			CoreUtilitiesMocks.CreateGenericTypeConverter());
+			CoreUtilitiesMocks.CreateGenericTypeConverter(),
+			CreateAuthorizationHandlerRegistry());
 
 		provider.InitializeOptions(options);
 
@@ -235,4 +233,7 @@ private static DynamicImageAzureBlobStorageCache CreateDynamicImageAzureBlobStor
 			provider,
 			blobStorageCacheOptions);
 	}
-}
+
+	private static UmbrellaFileAuthorizationHandlerRegistry CreateAuthorizationHandlerRegistry()
+		=> new UmbrellaFileAuthorizationHandlerRegistry([]);
+}

FileSystem/src/Umbrella.FileSystem.Abstractions/IServiceCollectionExtensions.cs

@@ -1,5 +1,6 @@
 
 using CommunityToolkit.Diagnostics;
+using Microsoft.Extensions.DependencyInjection.Extensions;
 using Umbrella.FileSystem.Abstractions;
 
 #pragma warning disable IDE0130
@@ -21,9 +22,11 @@ public static IServiceCollection AddUmbrellaFileSystemCore(this IServiceCollecti
 	{
 		Guard.IsNotNull(services);
 
-		_ = services.AddSingleton<IUmbrellaFileStorageProviderFactory, UmbrellaFileStorageProviderFactory>();
-		_ = services.AddSingleton<IUmbrellaTempFileHandler, UmbrellaTempFileHandler>();
+		services.TryAddSingleton<IUmbrellaFileStorageProviderFactory, UmbrellaFileStorageProviderFactory>();
+		services.TryAddSingleton<IUmbrellaFileAuthorizationHandlerRegistry, UmbrellaFileAuthorizationHandlerRegistry>();
+		services.TryAddSingleton<IUmbrellaTempFileHandler, UmbrellaTempFileHandler>();
+		services.TryAddEnumerable(ServiceDescriptor.Singleton<IUmbrellaFileAuthorizationHandler, UmbrellaTempFileAuthorizationHandler>());
 
 		return services;
 	}
-}
+}

FileSystem/src/Umbrella.FileSystem.Abstractions/IUmbrellaFileAuthorizationHandlerRegistry.cs

@@ -0,0 +1,21 @@
+namespace Umbrella.FileSystem.Abstractions;
+
+/// <summary>
+/// Resolves <see cref="IUmbrellaFileAuthorizationHandler"/> instances for stored files.
+/// </summary>
+public interface IUmbrellaFileAuthorizationHandlerRegistry
+{
+	/// <summary>
+	/// Gets the authorization handler for the specified directory name.
+	/// </summary>
+	/// <param name="directoryName">The directory name.</param>
+	/// <returns>The authorization handler if one is registered; otherwise <see langword="null"/>.</returns>
+	IUmbrellaFileAuthorizationHandler? GetByDirectoryName(string directoryName);
+
+	/// <summary>
+	/// Gets the authorization handler for the specified file.
+	/// </summary>
+	/// <param name="fileInfo">The file information.</param>
+	/// <returns>The authorization handler if one is registered; otherwise <see langword="null"/>.</returns>
+	IUmbrellaFileAuthorizationHandler? GetByFileInfo(IUmbrellaFileInfo fileInfo);
+}

FileSystem/src/Umbrella.FileSystem.Abstractions/IUmbrellaFileHandler.cs

@@ -6,7 +6,7 @@ namespace Umbrella.FileSystem.Abstractions;
 /// A handler used to access files stored using an implementation of the <see cref="UmbrellaFileStorageProvider{TFileInfo, TOptions}"/>.
 /// </summary>
 /// <typeparam name="TGroupId">The type of the group identifier.</typeparam>
-public interface IUmbrellaFileHandler<TGroupId> : IUmbrellaFileAuthorizationHandler
+public interface IUmbrellaFileHandler<TGroupId>
 	where TGroupId : IEquatable<TGroupId>
 {
 	/// <summary>

FileSystem/src/Umbrella.FileSystem.Abstractions/IUmbrellaFileStorageProvider.cs

@@ -15,6 +15,10 @@ public interface IUmbrellaFileStorageProvider
 	/// <summary>
 	/// Creates a new file at the specified <paramref name="subpath"/>.
 	/// </summary>
+	/// <remarks>
+	/// Implementations materialize a new file instance first and then apply authorization using
+	/// <see cref="UmbrellaFileOperationType.Create"/> rather than the standard read path used for existing files.
+	/// </remarks>
 	/// <param name="subpath">The subpath.</param>
 	/// <param name="cancellationToken">The cancellation token.</param>
 	/// <returns>The created file.</returns>
@@ -23,6 +27,9 @@ public interface IUmbrellaFileStorageProvider
 	/// <summary>
 	/// Gets the file at the specified <paramref name="subpath"/>.
 	/// </summary>
+	/// <remarks>
+	/// This resolves an existing file and applies authorization using <see cref="UmbrellaFileOperationType.Read"/>.
+	/// </remarks>
 	/// <param name="subpath">The subpath.</param>
 	/// <param name="cancellationToken">The cancellation token.</param>
 	/// <returns>The file.</returns>
@@ -142,4 +149,4 @@ public interface IUmbrellaFileStorageProvider
 	/// <param name="cancellationToken">The cancellation token.</param>
 	/// <returns>A collection of the files in the directory.</returns>
 	Task<IReadOnlyCollection<IUmbrellaFileInfo>> EnumerateDirectoryAsync(string subpath, CancellationToken cancellationToken = default);
-}
+}

FileSystem/src/Umbrella.FileSystem.Abstractions/UmbrellaFileAuthorizationHandler.cs

@@ -0,0 +1,29 @@
+using Microsoft.Extensions.Logging;
+
+namespace Umbrella.FileSystem.Abstractions;
+
+/// <summary>
+/// Serves as the base class for file authorization handlers.
+/// </summary>
+public abstract class UmbrellaFileAuthorizationHandler : IUmbrellaFileAuthorizationHandler
+{
+	/// <summary>
+	/// Gets the logger.
+	/// </summary>
+	protected ILogger Logger { get; }
+
+	/// <summary>
+	/// Initializes a new instance of the <see cref="UmbrellaFileAuthorizationHandler"/> class.
+	/// </summary>
+	/// <param name="logger">The logger.</param>
+	protected UmbrellaFileAuthorizationHandler(ILogger logger)
+	{
+		Logger = logger;
+	}
+
+	/// <inheritdoc />
+	public abstract string DirectoryName { get; }
+
+	/// <inheritdoc />
+	public abstract Task<bool> AuthorizeAsync(IUmbrellaFileInfo fileInfo, UmbrellaFileOperationType operationType, CancellationToken cancellationToken = default);
+}

FileSystem/src/Umbrella.FileSystem.Abstractions/UmbrellaFileAuthorizationHandlerRegistry.cs

@@ -0,0 +1,96 @@
+using CommunityToolkit.Diagnostics;
+
+namespace Umbrella.FileSystem.Abstractions;
+
+/// <summary>
+/// The default <see cref="IUmbrellaFileAuthorizationHandlerRegistry"/> implementation.
+/// </summary>
+public class UmbrellaFileAuthorizationHandlerRegistry : IUmbrellaFileAuthorizationHandlerRegistry
+{
+	private readonly Dictionary<string, IUmbrellaFileAuthorizationHandler> _handlerMappings;
+
+	/// <summary>
+	/// Initializes a new instance of the <see cref="UmbrellaFileAuthorizationHandlerRegistry"/> class.
+	/// </summary>
+	/// <param name="authorizationHandlers">The registered authorization handlers.</param>
+	/// <exception cref="UmbrellaFileSystemException">
+	/// Multiple <see cref="IUmbrellaFileAuthorizationHandler"/> instances were registered for the same normalized directory name.
+	/// </exception>
+	public UmbrellaFileAuthorizationHandlerRegistry(IEnumerable<IUmbrellaFileAuthorizationHandler> authorizationHandlers)
+	{
+		Guard.IsNotNull(authorizationHandlers);
+
+		var handlerMappings = new Dictionary<string, IUmbrellaFileAuthorizationHandler>(StringComparer.Ordinal);
+
+		foreach (IUmbrellaFileAuthorizationHandler authorizationHandler in authorizationHandlers)
+		{
+			string normalizedDirectoryName = NormalizeDirectoryName(authorizationHandler.DirectoryName);
+
+			if (handlerMappings.ContainsKey(normalizedDirectoryName))
+			{
+				throw new UmbrellaFileSystemException(
+					$"Multiple {nameof(IUmbrellaFileAuthorizationHandler)} instances were registered for the normalized directory name '{normalizedDirectoryName}'. Directory names must be unique.");
+			}
+
+			handlerMappings.Add(normalizedDirectoryName, authorizationHandler);
+		}
+
+		_handlerMappings = handlerMappings;
+	}
+
+	/// <inheritdoc />
+	public IUmbrellaFileAuthorizationHandler? GetByDirectoryName(string directoryName)
+	{
+		Guard.IsNotNullOrWhiteSpace(directoryName);
+
+		string normalizedDirectoryName = NormalizeDirectoryName(directoryName);
+
+		return _handlerMappings.TryGetValue(normalizedDirectoryName, out IUmbrellaFileAuthorizationHandler? authorizationHandler)
+			? authorizationHandler
+			: null;
+	}
+
+	/// <inheritdoc />
+	public IUmbrellaFileAuthorizationHandler? GetByFileInfo(IUmbrellaFileInfo fileInfo)
+	{
+		Guard.IsNotNull(fileInfo);
+
+		string? directoryName = GetTopLevelDirectoryName(fileInfo.SubPath);
+
+		if (string.IsNullOrWhiteSpace(directoryName))
+			return null;
+
+		return GetByDirectoryName(directoryName!);
+	}
+
+	private static string? GetTopLevelDirectoryName(string subPath)
+	{
+		if (string.IsNullOrWhiteSpace(subPath))
+			return null;
+
+		string normalizedSubPath = subPath.Trim().Replace('\\', '/').Trim('/');
+
+		if (string.IsNullOrWhiteSpace(normalizedSubPath))
+			return null;
+
+#if NETSTANDARD2_0
+		int firstSeparatorIndex = normalizedSubPath.IndexOf('/');
+#else
+		int firstSeparatorIndex = normalizedSubPath.IndexOf('/', StringComparison.Ordinal);
+#endif
+
+		return firstSeparatorIndex >= 0
+			? normalizedSubPath[..firstSeparatorIndex]
+			: normalizedSubPath;
+	}
+
+	private static string NormalizeDirectoryName(string directoryName)
+	{
+		string normalizedDirectoryName = directoryName.Trim().Replace('\\', '/').Trim('/');
+
+		if (string.IsNullOrWhiteSpace(normalizedDirectoryName))
+			throw new UmbrellaFileSystemException($"The {nameof(IUmbrellaFileAuthorizationHandler.DirectoryName)} value cannot be empty.");
+
+		return normalizedDirectoryName.ToLowerInvariant();
+	}
+}