Merge pull request #206 from ronaldbarendse/feature/cachekey-abstraction

Abstract cache key creation to ICacheKey

Author: JimBobSquarePants

samples/ImageSharp.Web.Sample/Startup.cs

@@ -54,6 +54,7 @@ public void ConfigureServices(IServiceCollection services)
                                 provider.GetRequiredService<IOptions<ImageSharpMiddlewareOptions>>(),
                                 provider.GetRequiredService<FormatUtilities>());
                 })
+                .SetCacheKey<UriRelativeLowerInvariantCacheKey>()
                 .SetCacheHash<CacheHash>()
                 .AddProvider<PhysicalFileSystemProvider>()
                 .AddProcessor<ResizeWebProcessor>()
@@ -129,6 +130,7 @@ private void ConfigureCustomServicesAndCustomOptions(IServiceCollection services
                         provider.GetRequiredService<IOptions<ImageSharpMiddlewareOptions>>(),
                         provider.GetRequiredService<FormatUtilities>());
                 })
+                .SetCacheKey<UriRelativeLowerInvariantCacheKey>()
                 .SetCacheHash<CacheHash>()
                 .ClearProviders()
                 .AddProvider<PhysicalFileSystemProvider>()

src/ImageSharp.Web/Caching/CacheKeyHelper.cs

@@ -0,0 +1,150 @@
+// Copyright (c) Six Labors.
+// Licensed under the Apache License, Version 2.0.
+
+using System;
+using System.Buffers;
+using System.Runtime.CompilerServices;
+using Microsoft.AspNetCore.Http;
+
+namespace SixLabors.ImageSharp.Web.Caching
+{
+    /// <summary>
+    /// Optimized helper methods for generating cache keys from URI components. Much of this code has been adapted from the MIT licensed .NET runtime.
+    /// </summary>
+    internal static class CacheKeyHelper
+    {
+        private static readonly SpanAction<char, (bool LowerInvariant, string Host, string PathBase, string Path, string Query)> InitializeAbsoluteUriStringSpanAction = new(InitializeAbsoluteUriString);
+
+        public enum CaseHandling
+        {
+            None,
+            LowerInvariant
+        }
+
+        /// <summary>
+        /// Combines the given URI components into a string that is properly encoded for use in HTTP headers.
+        /// </summary>
+        /// <param name="handling">Determines case handling for the result. <paramref name="query"/> is always converted to invariant lowercase.</param>
+        /// <param name="pathBase">The first portion of the request path associated with application root.</param>
+        /// <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(
+            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);
+
+        /// <summary>
+        /// Combines the given URI components into a string that is properly encoded for use in HTTP headers.
+        /// Note that unicode in the HostString will be encoded as punycode.
+        /// </summary>
+        /// <param name="handling">Determines case handling for the result. <paramref name="query"/> is always converted to invariant lowercase.</param>
+        /// <param name="host">The host portion of the uri normally included in the Host header. This may include the port.</param>
+        /// <param name="pathBase">The first portion of the request path associated with application root.</param>
+        /// <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(
+            CaseHandling handling,
+            HostString host,
+            PathString pathBase = default,
+            PathString path = default,
+            QueryString query = default)
+        {
+            string hostText = host.ToString();
+            string pathBaseText = pathBase.ToString();
+            string pathText = path.ToString();
+            string queryText = query.ToString();
+
+            // PERF: Calculate string length to allocate correct buffer size for string.Create.
+            int length =
+                hostText.Length +
+                pathBaseText.Length +
+                pathText.Length +
+                queryText.Length;
+
+            if (string.IsNullOrEmpty(pathText))
+            {
+                if (string.IsNullOrEmpty(pathBaseText))
+                {
+                    pathText = "/";
+                    length++;
+                }
+            }
+            else if (pathBaseText.EndsWith('/'))
+            {
+                // If the path string has a trailing slash and the other string has a leading slash, we need
+                // to trim one of them.
+                // Just decrement the total length, for now.
+                length--;
+            }
+
+            return string.Create(length, (handling == CaseHandling.LowerInvariant, hostText, pathBaseText, pathText, queryText), InitializeAbsoluteUriStringSpanAction);
+        }
+
+        /// <summary>
+        /// Copies the specified <paramref name="text"/> to the specified <paramref name="buffer"/> starting at the specified <paramref name="index"/>.
+        /// </summary>
+        /// <param name="buffer">The buffer to copy text to.</param>
+        /// <param name="index">The buffer start index.</param>
+        /// <param name="text">The text to copy.</param>
+        /// <returns>The <see cref="int"/> representing the combined text length.</returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        private static int CopyTextToBuffer(Span<char> buffer, int index, ReadOnlySpan<char> text)
+        {
+            text.CopyTo(buffer.Slice(index, text.Length));
+            return index + text.Length;
+        }
+
+        /// <summary>
+        /// Copies the specified <paramref name="text"/> to the specified <paramref name="buffer"/> starting at the specified <paramref name="index"/>
+        /// converting each character to lowercase, using the casing rules of the invariant culture.
+        /// </summary>
+        /// <param name="buffer">The buffer to copy text to.</param>
+        /// <param name="index">The buffer start index.</param>
+        /// <param name="text">The text to copy.</param>
+        /// <returns>The <see cref="int"/> representing the combined text length.</returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        private static int CopyTextToBufferLowerInvariant(Span<char> buffer, int index, ReadOnlySpan<char> text)
+            => index + text.ToLowerInvariant(buffer.Slice(index, text.Length));
+
+        /// <summary>
+        /// Initializes the URI <see cref="string"/> for <see cref="BuildAbsoluteKey(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>
+        private static void InitializeAbsoluteUriString(Span<char> buffer, (bool Lower, string Host, string PathBase, string Path, string Query) uriParts)
+        {
+            int index = 0;
+            ReadOnlySpan<char> pathBaseSpan = uriParts.PathBase.AsSpan();
+
+            if (uriParts.Path.Length > 0 && pathBaseSpan.Length > 0 && pathBaseSpan[pathBaseSpan.Length - 1] == '/')
+            {
+                // If the path string has a trailing slash and the other string has a leading slash, we need
+                // to trim one of them.
+                // Trim the last slash from pathBase. The total length was decremented before the call to string.Create.
+                pathBaseSpan = pathBaseSpan.Slice(0, pathBaseSpan.Length - 1);
+            }
+
+            if (uriParts.Lower)
+            {
+                index = CopyTextToBufferLowerInvariant(buffer, index, uriParts.Host.AsSpan());
+                index = CopyTextToBufferLowerInvariant(buffer, index, pathBaseSpan);
+                index = CopyTextToBufferLowerInvariant(buffer, index, uriParts.Path.AsSpan());
+            }
+            else
+            {
+                index = CopyTextToBuffer(buffer, index, uriParts.Host.AsSpan());
+                index = CopyTextToBuffer(buffer, index, pathBaseSpan);
+                index = CopyTextToBuffer(buffer, index, uriParts.Path.AsSpan());
+            }
+
+            // Querystring is always copied as lower invariant.
+            _ = CopyTextToBufferLowerInvariant(buffer, index, uriParts.Query.AsSpan());
+        }
+    }
+}

src/ImageSharp.Web/Caching/ICacheKey.cs

@@ -0,0 +1,24 @@
+// Copyright (c) Six Labors.
+// Licensed under the Apache License, Version 2.0.
+
+using Microsoft.AspNetCore.Http;
+using SixLabors.ImageSharp.Web.Commands;
+
+namespace SixLabors.ImageSharp.Web.Caching
+{
+    /// <summary>
+    /// Defines a contract that allows the creation of cache keys (used by <see cref="ICacheHash"/> to create hashed file names for storing cached images).
+    /// </summary>
+    public interface ICacheKey
+    {
+        /// <summary>
+        /// Creates the cache key based on the specified context and commands.
+        /// </summary>
+        /// <param name="context">The HTTP context.</param>
+        /// <param name="commands">The commands.</param>
+        /// <returns>
+        /// The cache key.
+        /// </returns>
+        string Create(HttpContext context, CommandCollection commands);
+    }
+}

src/ImageSharp.Web/Caching/LegacyV1CacheKey.cs

@@ -0,0 +1,38 @@
+// Copyright (c) Six Labors.
+// Licensed under the Apache License, Version 2.0.
+
+using System.Text;
+using Microsoft.AspNetCore.Http;
+using SixLabors.ImageSharp.Web.Commands;
+
+namespace SixLabors.ImageSharp.Web.Caching
+{
+    /// <summary>
+    /// Maintained for compatibility purposes only this cache key implementation generates the same
+    /// out as the V1 middleware. If possible, it is recommended to use the <see cref="UriRelativeCacheKey"/>.
+    /// </summary>
+    public class LegacyV1CacheKey : ICacheKey
+    {
+        /// <inheritdoc/>
+        public string Create(HttpContext context, CommandCollection commands)
+        {
+            var sb = new StringBuilder(context.Request.Host.ToString());
+
+            string pathBase = context.Request.PathBase.ToString();
+            if (!string.IsNullOrWhiteSpace(pathBase))
+            {
+                sb.AppendFormat("{0}/", pathBase);
+            }
+
+            string path = context.Request.Path.ToString();
+            if (!string.IsNullOrWhiteSpace(path))
+            {
+                sb.Append(path);
+            }
+
+            sb.Append(QueryString.Create(commands));
+
+            return sb.ToString().ToLowerInvariant();
+        }
+    }
+}

src/ImageSharp.Web/Caching/UriAbsoluteCacheKey.cs

@@ -0,0 +1,18 @@
+// Copyright (c) Six Labors.
+// Licensed under the Apache License, Version 2.0.
+
+using Microsoft.AspNetCore.Http;
+using SixLabors.ImageSharp.Web.Commands;
+
+namespace SixLabors.ImageSharp.Web.Caching
+{
+    /// <summary>
+    /// Creates a cache key based on the request host, path and commands.
+    /// </summary>
+    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));
+    }
+}

src/ImageSharp.Web/Caching/UriAbsoluteLowerInvariantCacheKey.cs

@@ -0,0 +1,18 @@
+// Copyright (c) Six Labors.
+// Licensed under the Apache License, Version 2.0.
+
+using Microsoft.AspNetCore.Http;
+using SixLabors.ImageSharp.Web.Commands;
+
+namespace SixLabors.ImageSharp.Web.Caching
+{
+    /// <summary>
+    /// Creates a case insensitive cache key based on the request host, path and commands.
+    /// </summary>
+    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));
+    }
+}

src/ImageSharp.Web/Caching/UriRelativeCacheKey.cs

@@ -0,0 +1,18 @@
+// Copyright (c) Six Labors.
+// Licensed under the Apache License, Version 2.0.
+
+using Microsoft.AspNetCore.Http;
+using SixLabors.ImageSharp.Web.Commands;
+
+namespace SixLabors.ImageSharp.Web.Caching
+{
+    /// <summary>
+    /// Creates a cache key based on the request path and commands.
+    /// </summary>
+    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));
+    }
+}

src/ImageSharp.Web/Caching/UriRelativeLowerInvariantCacheKey.cs

@@ -0,0 +1,18 @@
+// Copyright (c) Six Labors.
+// Licensed under the Apache License, Version 2.0.
+
+using Microsoft.AspNetCore.Http;
+using SixLabors.ImageSharp.Web.Commands;
+
+namespace SixLabors.ImageSharp.Web.Caching
+{
+    /// <summary>
+    /// Creates a case insensitive cache key based on the request path and commands.
+    /// </summary>
+    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));
+    }
+}

src/ImageSharp.Web/DependencyInjection/ImageSharpBuilderExtensions.cs

@@ -96,6 +96,33 @@ public static IImageSharpBuilder SetCache(this IImageSharpBuilder builder, Func<
             return builder;
         }
 
+        /// <summary>
+        /// Sets the given <see cref="ICacheKey"/> adding it to the service collection.
+        /// </summary>
+        /// <typeparam name="T">The type of class implementing <see cref="ICacheKey"/> to add.</typeparam>
+        /// <param name="builder">The core builder.</param>
+        /// <returns>The <see cref="IImageSharpBuilder"/>.</returns>
+        public static IImageSharpBuilder SetCacheKey<T>(this IImageSharpBuilder builder)
+            where T : class, ICacheKey
+        {
+            var descriptor = new ServiceDescriptor(typeof(ICacheKey), typeof(T), ServiceLifetime.Singleton);
+            builder.Services.Replace(descriptor);
+            return builder;
+        }
+
+        /// <summary>
+        /// Sets the given <see cref="ICacheKey"/> adding it to the service collection.
+        /// </summary>
+        /// <param name="builder">The core builder.</param>
+        /// <param name="implementationFactory">The factory method for returning a <see cref="ICacheKey"/>.</param>
+        /// <returns>The <see cref="IImageSharpBuilder"/>.</returns>
+        public static IImageSharpBuilder SetCacheKey(this IImageSharpBuilder builder, Func<IServiceProvider, ICacheKey> implementationFactory)
+        {
+            var descriptor = new ServiceDescriptor(typeof(ICacheKey), implementationFactory, ServiceLifetime.Singleton);
+            builder.Services.Replace(descriptor);
+            return builder;
+        }
+
         /// <summary>
         /// Sets the given <see cref="ICacheHash"/> adding it to the service collection.
         /// </summary>

src/ImageSharp.Web/DependencyInjection/ServiceCollectionExtensions.cs

@@ -64,6 +64,8 @@ private static void AddDefaultServices(
 
             builder.SetCache<PhysicalFileSystemCache>();
 
+            builder.SetCacheKey<UriRelativeLowerInvariantCacheKey>();
+
             builder.SetCacheHash<CacheHash>();
 
             builder.AddProvider<PhysicalFileSystemProvider>();