Merge branch 'main' into bugfix/insert-provider-idempotency

Author: JimBobSquarePants

src/Directory.Build.targets

@@ -31,5 +31,6 @@
     <PackageReference Update="Microsoft.AspNetCore.WebUtilities" Version="2.2.0" />
     <PackageReference Update="Microsoft.Extensions.Caching.Abstractions" Version="2.2.0" />
     <PackageReference Update="Microsoft.Extensions.Options.ConfigurationExtensions" Version="2.2.0" />
+    <PackageReference Update="Microsoft.Extensions.FileProviders.Physical" Version="2.2.0"/>
   </ItemGroup>
 </Project>

src/ImageSharp.Web/Caching/PhysicalFileSystemCache.cs

@@ -67,7 +67,7 @@ internal static string GetCacheRoot(PhysicalFileSystemCacheOptions cacheOptions,
             string cacheRootPath = cacheOptions.CacheRootPath ?? webRootPath;
             if (string.IsNullOrEmpty(cacheRootPath))
             {
-                throw new InvalidOperationException("The cache root path can't be determined, make sure it's explicitly configured or the webroot is set.");
+                throw new InvalidOperationException("The cache root path cannot be determined, make sure it's explicitly configured or the webroot is set.");
             }
 
             if (!Path.IsPathFullyQualified(cacheRootPath))

src/ImageSharp.Web/Caching/SHA256CacheHash.cs

@@ -33,18 +33,16 @@ public SHA256CacheHash(IOptions<ImageSharpMiddlewareOptions> options)
         public string Create(string value, uint length)
         {
             int byteCount = Encoding.ASCII.GetByteCount(value);
-
-            // Allocating a buffer from the pool is ~27% slower than stackalloc so use that for short strings
-            if (byteCount < 257)
-            {
-                return HashValue(value, length, stackalloc byte[byteCount]);
-            }
-
             byte[] buffer = null;
+
             try
             {
-                buffer = ArrayPool<byte>.Shared.Rent(byteCount);
-                return HashValue(value, length, buffer.AsSpan(0, byteCount));
+                // Allocating a buffer from the pool is ~27% slower than stackalloc so use that for short strings
+                Span<byte> bytes = byteCount <= 128
+                    ? stackalloc byte[byteCount]
+                    : (buffer = ArrayPool<byte>.Shared.Rent(byteCount)).AsSpan(0, byteCount);
+
+                return HashValue(value, length, bytes);
             }
             finally
             {

src/ImageSharp.Web/Caching/UriAbsoluteCacheKey.cs

@@ -13,6 +13,6 @@ public class UriAbsoluteCacheKey : ICacheKey
     {
         /// <inheritdoc/>
         public string Create(HttpContext context, CommandCollection commands)
-            => CacheKeyHelper.BuildAbsoluteKey(CacheKeyHelper.CaseHandling.None, context.Request.Host, context.Request.PathBase, context.Request.Path, QueryString.Create(commands));
+            => CaseHandlingUriBuilder.BuildAbsolute(CaseHandlingUriBuilder.CaseHandling.None, context.Request.Host, context.Request.PathBase, context.Request.Path, QueryString.Create(commands));
     }
 }

src/ImageSharp.Web/Caching/UriAbsoluteLowerInvariantCacheKey.cs

@@ -13,6 +13,6 @@ public class UriAbsoluteLowerInvariantCacheKey : ICacheKey
     {
         /// <inheritdoc/>
         public string Create(HttpContext context, CommandCollection commands)
-            => CacheKeyHelper.BuildAbsoluteKey(CacheKeyHelper.CaseHandling.LowerInvariant, context.Request.Host, context.Request.PathBase, context.Request.Path, QueryString.Create(commands));
+            => CaseHandlingUriBuilder.BuildAbsolute(CaseHandlingUriBuilder.CaseHandling.LowerInvariant, context.Request.Host, context.Request.PathBase, context.Request.Path, QueryString.Create(commands));
     }
 }

src/ImageSharp.Web/Caching/UriRelativeCacheKey.cs

@@ -13,6 +13,6 @@ public class UriRelativeCacheKey : ICacheKey
     {
         /// <inheritdoc/>
         public string Create(HttpContext context, CommandCollection commands)
-            => CacheKeyHelper.BuildRelativeKey(CacheKeyHelper.CaseHandling.None, context.Request.PathBase, context.Request.Path, QueryString.Create(commands));
+            => CaseHandlingUriBuilder.BuildRelative(CaseHandlingUriBuilder.CaseHandling.None, context.Request.PathBase, context.Request.Path, QueryString.Create(commands));
     }
 }

src/ImageSharp.Web/Caching/UriRelativeLowerInvariantCacheKey.cs

@@ -13,6 +13,6 @@ public class UriRelativeLowerInvariantCacheKey : ICacheKey
     {
         /// <inheritdoc/>
         public string Create(HttpContext context, CommandCollection commands)
-            => CacheKeyHelper.BuildRelativeKey(CacheKeyHelper.CaseHandling.LowerInvariant, context.Request.PathBase, context.Request.Path, QueryString.Create(commands));
+            => CaseHandlingUriBuilder.BuildRelative(CaseHandlingUriBuilder.CaseHandling.LowerInvariant, context.Request.PathBase, context.Request.Path, QueryString.Create(commands));
     }
 }

…ImageSharp.Web/Caching/CacheKeyHelper.cs …ImageSharp.Web/CaseHandlingUriBuilder.cssrc/ImageSharp.Web/Caching/CacheKeyHelper.cs renamed to src/ImageSharp.Web/CaseHandlingUriBuilder.cs src/ImageSharp.Web/Caching/CacheKeyHelper.cs renamed to src/ImageSharp.Web/CaseHandlingUriBuilder.cs

@@ -6,18 +6,29 @@
 using System.Runtime.CompilerServices;
 using Microsoft.AspNetCore.Http;
 
-namespace SixLabors.ImageSharp.Web.Caching
+namespace SixLabors.ImageSharp.Web
 {
     /// <summary>
-    /// Optimized helper methods for generating cache keys from URI components. Much of this code has been adapted from the MIT licensed .NET runtime.
+    /// Optimized helper methods for generating encoded Uris from URI components.
+    /// Much of this code has been adapted from the MIT licensed .NET runtime.
     /// </summary>
-    internal static class CacheKeyHelper
+    public static class CaseHandlingUriBuilder
     {
         private static readonly SpanAction<char, (bool LowerInvariant, string Host, string PathBase, string Path, string Query)> InitializeAbsoluteUriStringSpanAction = new(InitializeAbsoluteUriString);
 
+        /// <summary>
+        /// Provides Uri case handling options.
+        /// </summary>
         public enum CaseHandling
         {
+            /// <summary>
+            /// No adjustments to casing are made.
+            /// </summary>
             None,
+
+            /// <summary>
+            /// All URI components are converted to lower case using the invariant culture before combining.
+            /// </summary>
             LowerInvariant
         }
 
@@ -29,14 +40,14 @@ public enum CaseHandling
         /// <param name="path">The portion of the request path that identifies the requested resource.</param>
         /// <param name="query">The query, if any.</param>
         /// <returns>The combined URI components, properly encoded for use in HTTP headers.</returns>
-        public static string BuildRelativeKey(
+        public static string BuildRelative(
             CaseHandling handling,
             PathString pathBase = default,
             PathString path = default,
             QueryString query = default)
 
             // Take any potential performance hit vs concatination for code reading sanity.
-            => BuildAbsoluteKey(handling, default, pathBase, path, query);
+            => BuildAbsolute(handling, default, pathBase, path, query);
 
         /// <summary>
         /// Combines the given URI components into a string that is properly encoded for use in HTTP headers.
@@ -48,7 +59,7 @@ public static string BuildRelativeKey(
         /// <param name="path">The portion of the request path that identifies the requested resource.</param>
         /// <param name="query">The query, if any.</param>
         /// <returns>The combined URI components, properly encoded for use in HTTP headers.</returns>
-        public static string BuildAbsoluteKey(
+        public static string BuildAbsolute(
             CaseHandling handling,
             HostString host,
             PathString pathBase = default,
@@ -113,7 +124,7 @@ private static int CopyTextToBufferLowerInvariant(Span<char> buffer, int index,
             => index + text.ToLowerInvariant(buffer.Slice(index, text.Length));
 
         /// <summary>
-        /// Initializes the URI <see cref="string"/> for <see cref="BuildAbsoluteKey(CaseHandling, HostString, PathString, PathString, QueryString)"/>.
+        /// Initializes the URI <see cref="string"/> for <see cref="BuildAbsolute(CaseHandling, HostString, PathString, PathString, QueryString)"/>.
         /// </summary>
         /// <param name="buffer">The URI <see cref="string"/>'s <see cref="char"/> buffer.</param>
         /// <param name="uriParts">The URI parts.</param>

src/ImageSharp.Web/Commands/Converters/SimpleCommandConverter{T}.cs

@@ -11,7 +11,7 @@ namespace SixLabors.ImageSharp.Web.Commands.Converters
     /// The generic converter for simple types that implement <see cref="IConvertible"/>.
     /// </summary>
     /// <typeparam name="T">The type of object to convert to.</typeparam>
-    internal sealed class SimpleCommandConverter<T> : ICommandConverter<T>
+    public sealed class SimpleCommandConverter<T> : ICommandConverter<T>
         where T : IConvertible
     {
         /// <inheritdoc/>

src/ImageSharp.Web/HMACUtilities.cs

@@ -0,0 +1,100 @@
+// Copyright (c) Six Labors.
+// Licensed under the Apache License, Version 2.0.
+
+using System;
+using System.Buffers;
+using System.Runtime.CompilerServices;
+using System.Security.Cryptography;
+using System.Text;
+using SixLabors.ImageSharp.Web.Caching;
+
+namespace SixLabors.ImageSharp.Web
+{
+    /// <summary>
+    /// Provides methods to compute a Hash-based Message Authentication Code (HMAC).
+    /// </summary>
+    public static class HMACUtilities
+    {
+        /// <summary>
+        /// The command used by image requests for transporting Hash-based Message Authentication Code (HMAC) tokens.
+        /// </summary>
+        public const string TokenCommand = "hmac";
+
+        /// <summary>
+        /// Computes a Hash-based Message Authentication Code (HMAC) by using the SHA256 hash function.
+        /// </summary>
+        /// <param name="value">The value to hash</param>
+        /// <param name="secret">
+        /// The secret key for <see cref="HMACSHA256"/> encryption.
+        /// The key can be any length. However, the recommended size is 64 bytes.
+        /// </param>
+        /// <returns>The hashed <see cref="string"/>.</returns>
+        public static unsafe string ComputeHMACSHA256(string value, byte[] secret)
+        {
+            // TODO: In .NET 6 we can use single instance versions
+            using var hmac = new HMACSHA256(secret);
+            return CreateHMAC(value, hmac);
+        }
+
+        /// <summary>
+        /// Computes a Hash-based Message Authentication Code (HMAC) by using the SHA384 hash function.
+        /// </summary>
+        /// <param name="value">The value to hash</param>
+        /// <param name="secret">
+        /// The secret key for <see cref="HMACSHA256"/> encryption.
+        /// The key can be any length. However, the recommended size is 128 bytes.
+        /// </param>
+        /// <returns>The hashed <see cref="string"/>.</returns>
+        public static unsafe string ComputeHMACSHA384(string value, byte[] secret)
+        {
+            using var hmac = new HMACSHA384(secret);
+            return CreateHMAC(value, hmac);
+        }
+
+        /// <summary>
+        /// Computes a Hash-based Message Authentication Code (HMAC) by using the SHA512 hash function.
+        /// </summary>
+        /// <param name="value">The value to hash</param>
+        /// <param name="secret">
+        /// The secret key for <see cref="HMACSHA256"/> encryption.
+        /// The key can be any length. However, the recommended size is 128 bytes.
+        /// </param>
+        /// <returns>The hashed <see cref="string"/>.</returns>
+        public static unsafe string ComputeHMACSHA512(string value, byte[] secret)
+        {
+            using var hmac = new HMACSHA512(secret);
+            return CreateHMAC(value, hmac);
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        private static unsafe string CreateHMAC(string value, HMAC hmac)
+        {
+            int byteCount = Encoding.ASCII.GetByteCount(value);
+            byte[] buffer = null;
+
+            try
+            {
+                // Allocating a buffer from the pool is ~27% slower than stackalloc so use that for short strings
+                Span<byte> bytes = byteCount <= 128
+                    ? stackalloc byte[byteCount]
+                    : (buffer = ArrayPool<byte>.Shared.Rent(byteCount)).AsSpan(0, byteCount);
+
+                Encoding.ASCII.GetBytes(value, bytes);
+
+                // Safe to always stackalloc here. We max out at 64 bytes.
+                Span<byte> hash = stackalloc byte[hmac.HashSize / 8];
+                hmac.TryComputeHash(bytes, hash, out int _);
+
+                // Finally encode the hash to make it web safe.
+                return HexEncoder.Encode(hash);
+            }
+            finally
+            {
+                if (buffer is not null)
+                {
+                    ArrayPool<byte>.Shared.Return(buffer);
+                }
+            }
+        }
+    }
+}