Updating readme, types documentation and moving to release version (#40)

Author: artmasa

.build/release.props

@@ -2,11 +2,11 @@
 
   <PropertyGroup>
     <PackageId>$(AssmeblyName)</PackageId>
-    <Authors>Arturo Martinez</Authors>
+    <Authors>DarkLoop</Authors>
     <Company>DarkLoop</Company>
     <Copyright>DarkLoop - All rights reserved</Copyright>
     <Product>DarkLoop's Azure Functions Authorization</Product>
-    <IsPreview>true</IsPreview>
+    <IsPreview>false</IsPreview>
     <AssemblyVersion>4.0.0.0</AssemblyVersion>
     <Version>4.0.0</Version>
     <FileVersion>$(Version).0</FileVersion>
@@ -20,6 +20,7 @@
     <AssemblyOriginatorKeyFile>../dl-sftwr-sn-key.snk</AssemblyOriginatorKeyFile>
     <PublicKey>0024000004800000940000000602000000240000525341310004000001000100791e7f618a12452d7ced5310f6203d0d227f9d26b146555e7e67a1801695dcf7c552421620a662f54b072f7be1efa885c074d4b9c76a4d6d154721d1c3b1f39164cfaf9ebdf9b7672ff320c89c5a64c90e25330f90a12bf42a1c57b70523e785167dbbfb7a0fdc9eb8d15112f758b89bab51953b08cfb2218095bc45171c99c5</PublicKey>
     <IsPackable>true</IsPackable>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageReadmeFile>README.md</PackageReadmeFile>
   </PropertyGroup>
 

README.md

@@ -21,7 +21,23 @@ This projects is open source and may be redistributed under the terms of the [Ap
 Adding change log starting with version 3.1.3
 
 ### 4.0.0
-Information will be added soon.
+Starting from 4.0.0, support for Azure Functions V4 Isolated mode with ASPNET Core integration is added.
+The package is now split into two separate packages, one for each mode. 
+
+The package for Azure Functions V3+ In-Proc mode is now called `DarkLoop.Azure.Functions.Authorization.InProcess` and the package for Azure Functions V4 Isolated mode with ASPNET Core integration is called `DarkLoop.Azure.Functions.Authorize.Isolated`.
+
+- #### .NET 6 support
+  Starting with version 4.0.0, the package is now targeting .NET 6.0. This means that the package is no longer compatible with .NET 5 or lower. If you are using .NET 5 or lower, you should use version 3.1.3 of the package.
+  
+- #### DarkLoop.Azure.Functions.Authorize v4.0.0
+  This package is published but is now deprecated in favor of `DarkLoop.Azure.Functions.Authorization.InProcess`. All it's functionality remains the same. It's just a way to keep package naming in sync.
+
+- #### Introducing IFunctionsAuthorizationProvider interface
+  The `IFunctionsAuthorizationProvider` interface is introduced to allow for custom authorization filter provisioning to the framework.
+  By default the framework relies on decorating the function or type with `[FunctionAuthorize]`. You could skip this decoration and provide the middleware with an authorization filter sourced from your own mechanism, for example a database.
+  At this moment this can be done only with Isolated mode even when the interface is defined in the shared package.<br/>
+  Support for In-Process will be added in a future version, once source generators are introduced, as the in-process framework relies on Invocation Filters to enable authorization.
+  Replacing the service in the application services would break the authorization for in-process mode at this point.
 
 ### 3.1.3
 3.1.3 and lower versions only support Azure Functions V3 In-Proc mode. Starting from 4.0.0, support for Azure Functions V4 Isolated mode with ASPNET Core integration is added.

src/abstractions/Cache/FunctionsAuthorizationFilterCache.cs

@@ -7,7 +7,7 @@
 namespace DarkLoop.Azure.Functions.Authorization.Cache
 {
     /// <inheritdoc cref="IFunctionsAuthorizationFilterCache{TIdentifier}"/>
-    internal class FunctionsAuthorizationFilterCache<TIdentifier> : IFunctionsAuthorizationFilterCache<TIdentifier>
+    internal sealed class FunctionsAuthorizationFilterCache<TIdentifier> : IFunctionsAuthorizationFilterCache<TIdentifier>
         where TIdentifier : notnull
     {
         private readonly ConcurrentDictionary<TIdentifier, FunctionAuthorizationFilter> _filters = new();

src/abstractions/Cache/IFunctionsAuthorizationFilterCache.cs

@@ -18,7 +18,7 @@ public interface IFunctionsAuthorizationFilterCache<TIdentifier>
         /// Sets the authorization filter for the specified function.
         /// </summary>
         /// <param name="functionIdentifier">The function unique identifier</param>
-        /// <param name="builder"></param>
+        /// <param name="filter">The filter to cache.</param>
         /// <returns></returns>
         bool SetFilter(TIdentifier functionIdentifier, FunctionAuthorizationFilter filter);
     }

src/abstractions/FunctionAuthorizationMetadata.cs

@@ -10,7 +10,10 @@
 
 namespace DarkLoop.Azure.Functions.Authorization
 {
-    public class FunctionAuthorizationMetadata
+    /// <summary>
+    /// Authorization metadata for a function or type.
+    /// </summary>
+    public sealed class FunctionAuthorizationMetadata
     {
         private readonly int _key;
         private readonly string? _functionName;
@@ -68,7 +71,7 @@ internal FunctionAuthorizationMetadata(Type declaringType) : this()
         /// Gets the name of the type declaring the function method.
         /// </summary>
         /// <remarks>The returned value is never <see langword="null"/>. Only for <see cref="Empty"/></remarks>
-        public virtual Type? DeclaringType => _declaringType;
+        public Type? DeclaringType => _declaringType;
 
         /// <summary>
         /// Gets a value indicating whether the function allows anonymous access.

src/abstractions/FunctionAuthorizationMetadataCollection.cs

@@ -23,6 +23,7 @@ internal sealed class FunctionAuthorizationMetadataCollection
 
         /// <summary>
         /// Gets the number of authorization metadata items in the collection.
+        /// </summary>
         internal int Count => _items.Count;
 
         /// <summary>
@@ -41,15 +42,11 @@ internal FunctionAuthorizationMetadata Add(Type declaringType, out bool existing
         /// </summary>
         /// <param name="functionName">The name of the function.</param>
         /// <param name="declaringType">The type declaring the function method.</param>
-
         /// <returns>An instance of <see cref="FunctionAuthorizationMetadata"/></returns>
-        /// <exception cref="InvalidOperationException">
-        /// When a rule already exists and defines a different value than the one specified in <paramref name="allowAnonymous"/>
-        /// </exception>
         internal FunctionAuthorizationMetadata Add(string functionName, Type declaringType)
         {
             this.RegisterFunctionDeclaringType(functionName, declaringType);
-            
+
             return this.GetOrAdd(functionName, declaringType, out _);
         }
 

src/abstractions/FunctionsAuthorizationOptions.cs

@@ -12,7 +12,7 @@ namespace DarkLoop.Azure.Functions.Authorization
     /// </summary>
     [ExcludeFromCodeCoverage]
     // Important to keep this class POCO, any special functionality should be done with extension methods.
-    public class FunctionsAuthorizationOptions
+    public sealed class FunctionsAuthorizationOptions
     {
         internal readonly FunctionAuthorizationMetadataCollection AuthorizationMetadata = new();
 

src/abstractions/FunctionsAuthorizationProvider.cs

@@ -31,8 +31,11 @@ internal class FunctionsAuthorizationProvider : IFunctionsAuthorizationProvider
         /// <summary>
         /// Initializes a new instance of the <see cref="FunctionsAuthorizationProvider"/> class.
         /// </summary>
-        /// <param name="cache"></param>
-        /// <param name="schemeProvider"></param>
+        /// <param name="schemeProvider">ASP.NET Core's scheme provider.</param>
+        /// <param name="cache">The function filter cache.</param>
+        /// <param name="options">The options object serving metadata. This doesn't change through the life of the application.</param>
+        /// <param name="configOptions">The options object to manage configuration settings that might change from config source.</param>
+        /// <param name="logger">Logger for class.</param>
         public FunctionsAuthorizationProvider(
             IAuthenticationSchemeProvider schemeProvider,
             IFunctionsAuthorizationFilterCache<int> cache,
@@ -62,6 +65,7 @@ public async Task<FunctionAuthorizationFilter> GetAuthorizationAsync(string func
 
             if (_filterCache.TryGetFilter(key, out var filter))
             {
+                _logger.LogDebug("Found cached filter for function.");
                 return filter!;
             }
 
@@ -73,9 +77,11 @@ public async Task<FunctionAuthorizationFilter> GetAuthorizationAsync(string func
             {
                 if (_filterCache.TryGetFilter(key, out filter))
                 {
+                    _logger.LogDebug("Found cached filter for function while trying to generate one.");
                     return filter!;
                 }
 
+                _logger.LogDebug("Generating filter for function.");
                 var functionMetadata = _metadataStore.GetMetadata(functionName);
 
                 if (functionMetadata == FunctionAuthorizationMetadata.Empty)
@@ -97,7 +103,7 @@ public async Task<FunctionAuthorizationFilter> GetAuthorizationAsync(string func
                 if (policyProvider.AllowsCachingPolicies)
                 {
 #endif
-                _filterCache.SetFilter(key, filter);
+                    _filterCache.SetFilter(key, filter);
 #if NET7_0_OR_GREATER
                 }
 #endif
@@ -124,10 +130,12 @@ public async Task<FunctionAuthorizationFilter> GetAuthorizationAsync(string func
 
             if (!needsScheme)
             {
+                _logger.LogDebug("Using provided authentication schemes.");
                 return await AuthorizationPolicy.CombineAsync(policyProvider, authorizationData);
             }
             else
             {
+                _logger.LogDebug("Using empty scheme strategy to assign schemes for policy.");
                 var strategy = _options.CurrentValue.EmptySchemeStrategy;
 
                 if (strategy is EmptySchemeStrategy.UseDefaultScheme && defaultScheme is null)
@@ -146,10 +154,12 @@ public async Task<FunctionAuthorizationFilter> GetAuthorizationAsync(string func
 
                 if (strategy is EmptySchemeStrategy.UseDefaultScheme)
                 {
+                    _logger.LogDebug("Using default authentication scheme.");
                     copy[0].AuthenticationSchemes = defaultScheme!.Name;
                 }
                 else
                 {
+                    _logger.LogDebug("Using all available authentication schemes.");
                     var schemes = (await _schemeProvider.GetRequestHandlerSchemesAsync()).Select(s => s.Name).ToList();
                     schemes = schemes.Count > 0 ? schemes : (await _schemeProvider.GetAllSchemesAsync()).Select(s => s.Name).ToList();
 

src/abstractions/FunctionsAuthorizationResultHandler.cs

@@ -17,7 +17,7 @@
 namespace DarkLoop.Azure.Functions.Authorization
 {
     /// <inheritdoc cref="IFunctionsAuthorizationResultHandler"/>
-    internal class FunctionsAuthorizationResultHandler : IFunctionsAuthorizationResultHandler
+    internal sealed class FunctionsAuthorizationResultHandler : IFunctionsAuthorizationResultHandler
     {
         private readonly IOptionsMonitor<FunctionsAuthorizationOptions> _options;
 

src/abstractions/Internal/FunctionsAuthorizationOptionsExtensions.cs

@@ -17,6 +17,7 @@ internal static class FunctionsAuthorizationOptionsExtensions
         /// <summary>
         /// Registers all the functions in the specified <paramref name="declaringType"/>.
         /// </summary>
+        /// <param name="options">The current options.</param>
         /// <param name="declaringType">The type containing the functions.</param>
         /// <param name="existing">A value indicating whether the function declaring type is already registered.</param>
         /// <returns>Return a <see cref="FunctionAuthorizationMetadata"/> to keep configuring.</returns>
@@ -32,6 +33,7 @@ internal static FunctionAuthorizationMetadata SetTypeAuthorizationInfo(
         /// Registers the function with the specified name in <paramref name="functionName"/> 
         /// in the type specified in <paramref name="declaringType"/>.
         /// </summary>
+        /// <param name="options">The current options.</param>
         /// <param name="functionName">The name of the function.</param>
         /// <param name="declaringType">The type declaring the function.</param>
         /// <returns>Return a <see cref="FunctionAuthorizationMetadata"/> to keep configuring.</returns>
@@ -54,7 +56,7 @@ internal static bool IsFunctionRegistered(this FunctionsAuthorizationOptions opt
         /// Registers the authorization metadata for the function extracted from attribute.
         /// </summary>
         /// <typeparam name="TAuthAttribute">The type of authorization attribute to lookup.</typeparam>
-        /// <param name="options">The current options object</param>
+        /// <param name="options">The current options.</param>
         /// <param name="functionName">The name of the function.</param>
         /// <param name="declaringType">The type declaring the function.</param>
         /// <param name="functionMethod">The entry point method for the function.</param>