Refactoring, documentation

Still working on the layered cache tests next...

Author: jjxtra

DigitalRuby.SimpleCache.Sandbox/appsettings.json

@@ -9,26 +9,32 @@
   },
   "DigitalRuby.SimpleCache":
   {
-    /* redis connection string */
+    /*
+    optional, cache key prefix, by default the entry assembly name is used
+    you can set this to an empty string to share keys between services that are using the same redis cluster
+    */
+    "KeyPrefix": "sandbox",
+
+    /* optional, override max memory size (in megabytes). Default is 1024. */
+    "MaxMemorySize": 2048,
+
+    /* redis connection string, required */
     "RedisConnectionString": "localhost:6379",
 
     /*
-    file cache directory, set to empty to not use file cache (recommended if not on SSD)
+    opptional, override file cache directory, set to empty to not use file cache (recommended if not on SSD)
     the default is %temp% which means to use the temp directory
     this example assumes running on Windows, for production, use an environment variable or just leave off for default of %temp%.
     */
     "FileCacheDirectory": "c:/temp",
 
-    /* override the file cache cleanup threshold (0-100 percent). default is 15 */
+    /* optional, override the file cache cleanup threshold (0-100 percent). default is 15 */
     "FileCacheFreeSpaceThreshold": 10,
 
-    /* optional override the default json-lz4 serializer with your own class that implements DigitalRuby.SimpleCache.ISerializer */
-    "SerializerType": "DigitalRuby.SimpleCache.Sandbox.JsonSerializer, DigitalRuby.SimpleCache.Sandbox",
-
-    /* optional key prefix, by default the entry assembly name is used */
-    "KeyPrefix": "sandbox",
-
-    /* optional, set max memory size (in megabytes). Default is 1024. */
-    "MaxMemorySize": 2048
+    /*
+    optional, override the default json-lz4 serializer with your own class that implements DigitalRuby.SimpleCache.ISerializer
+    the serializer is used to convert objects to bytes for the file and redis caches
+    */
+    "SerializerType": "DigitalRuby.SimpleCache.JsonSerializer, DigitalRuby.SimpleCache"
   }
 }

DigitalRuby.SimpleCache.Tests/FileCacheTests.cs

@@ -3,13 +3,15 @@ namespace DigitalRuby.SimpleCache.Tests;
 /// <summary>
 /// File cache tests
 /// </summary>
-public class FileCacheTests : IDateTimeProvider, IDiskSpace
+public sealed class FileCacheTests : IClockHandler, IDiskSpace
 {
+	private DateTimeOffset utcNow;
+
 	/// <inheritdoc />
-	public DateTimeOffset UtcNow { get; set; }
+	DateTimeOffset ISystemClock.UtcNow => utcNow;
 
 	/// <inheritdoc />
-	public Task DelayAsync(TimeSpan interval, CancellationToken cancelToken = default)
+	Task IClockHandler.DelayAsync(TimeSpan interval, CancellationToken cancelToken)
 	{
 		return Task.CompletedTask;
 	}
@@ -39,6 +41,8 @@ public async Task TestFileCache()
 	{
 		const int testCount = 10;
 		const string data = "74956375-DD97-4857-816E-188BC8D4090F74956375-DD97-4857-816E-188BC8D4090F74956375-DD97-4857-816E-188BC8D4090F74956375-DD97-4857-816E-188BC8D4090F74956375-DD97-4857-816E-188BC8D4090F74956375-DD97-4857-816E-188BC8D4090F74956375-DD97-4857-816E-188BC8D4090F74956375-DD97-4857-816E-188BC8D4090F74956375-DD97-4857-816E-188BC8D4090F74956375-DD97-4857-816E-188BC8D4090F";
+
+		utcNow = new DateTimeOffset(2022, 1, 1, 1, 1, 1, TimeSpan.Zero);
 		using FileCache fileCache = new(new() { FreeSpaceThreshold = 20 }, new JsonLZ4Serializer(), this, this, new NullLogger<FileCache>());
 
 		var item = await fileCache.GetAsync<string>("key1");
@@ -50,7 +54,7 @@ public async Task TestFileCache()
 		Assert.That(item.Item, Is.EqualTo(data));
 
 		// step time, item should expire out
-		UtcNow += TimeSpan.FromSeconds(6.0);
+		utcNow += TimeSpan.FromSeconds(6.0);
 		await fileCache.CleanupFreeSpaceAsync();
 		item = await fileCache.GetAsync<string>("key1");
 		Assert.That(item, Is.Null);
@@ -98,7 +102,7 @@ public async Task TestFileCache()
 		sw.Restart();
 
 		// step time, item should expire out
-		UtcNow += TimeSpan.FromSeconds(6.0);
+		utcNow += TimeSpan.FromSeconds(6.0);
 
 		for (int i = 0; i < testCount; i++)
 		{

DigitalRuby.SimpleCache.Tests/GlobalUsings.cs

@@ -1,7 +1,12 @@
 global using System.Diagnostics;
 
+global using Microsoft.Extensions.Caching.Memory;
+global using Microsoft.Extensions.Internal;
 global using Microsoft.Extensions.Logging.Abstractions;
+global using Microsoft.Extensions.Options;
 
 global using DigitalRuby.SimpleCache;
 
+global using NUnit.Framework;
+
 namespace DigitalRuby.SimpleCache;

DigitalRuby.SimpleCache.Tests/LayeredCacheTests.cs

@@ -0,0 +1,51 @@
+namespace DigitalRuby.SimpleCache.Tests;
+
+/// <summary>
+/// Tests for layered cache
+/// </summary>
+[TestFixture]
+public sealed class LayeredCacheTests : IDiskSpace, IClockHandler, IOptions<MemoryCacheOptions>, ISystemClock
+{
+    private ISerializer serializer = new JsonSerializer();
+    private Dictionary<string, long> fileSpaces = new();
+    private MemoryCache memoryCache;
+    private FileCache fileCache;
+    private DistributedMemoryCache distributedCache;
+    private LayeredCache layeredCache;
+    private long freeSpace;
+    private long totalSpace;
+    private DateTimeOffset utcNow;
+
+    [SetUp]
+    public void Setup()
+    {
+        fileSpaces.Clear();
+        memoryCache = new(this);
+        freeSpace = 10000;
+        totalSpace = 100000;
+        utcNow = new DateTimeOffset(2022, 1, 1, 1, 1, 1, TimeSpan.Zero);
+        fileCache = new FileCache(new FileCacheOptions(), serializer, this, this, new NullLogger<FileCache>());
+        distributedCache = new DistributedMemoryCache(this);
+        layeredCache = new LayeredCache(new LayeredCacheOptions { KeyPrefix = "test" }, serializer,
+            memoryCache, fileCache, distributedCache, new NullLogger<LayeredCache>());
+    }
+
+    MemoryCacheOptions IOptions<MemoryCacheOptions>.Value => new() { Clock = this };
+
+    DateTimeOffset ISystemClock.UtcNow => utcNow;
+
+    Task IClockHandler.DelayAsync(System.TimeSpan interval, System.Threading.CancellationToken cancelToken) => Task.Delay(0, cancelToken);
+
+    long IDiskSpace.GetFileSize(string fileName)
+    {
+        fileSpaces.TryGetValue(fileName, out long space);
+        return space;
+    }
+
+    double IDiskSpace.GetPercentFreeSpace(string path, out long availableFreeSpace, out long totalSpace)
+    {
+        availableFreeSpace = this.freeSpace;
+        totalSpace = this.totalSpace;
+        return (double)availableFreeSpace / (double)totalSpace;
+    }
+}

DigitalRuby.SimpleCache.Tests/Usings.cs

@@ -5,9 +5,17 @@ VisualStudioVersion = 17.2.32519.379
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "DigitalRuby.SimpleCache", "DigitalRuby.SimpleCache\DigitalRuby.SimpleCache.csproj", "{20A96010-CAEF-4ADF-A076-9434261916BE}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DigitalRuby.SimpleCache.Tests", "DigitalRuby.SimpleCache.Tests\DigitalRuby.SimpleCache.Tests.csproj", "{A82855AE-B0FD-4B77-8839-A29A094F706A}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "DigitalRuby.SimpleCache.Tests", "DigitalRuby.SimpleCache.Tests\DigitalRuby.SimpleCache.Tests.csproj", "{A82855AE-B0FD-4B77-8839-A29A094F706A}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DigitalRuby.SimpleCache.Sandbox", "DigitalRuby.SimpleCache.Sandbox\DigitalRuby.SimpleCache.Sandbox.csproj", "{CB0257DD-3D4A-4C42-B7C0-EC626C662CFA}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "DigitalRuby.SimpleCache.Sandbox", "DigitalRuby.SimpleCache.Sandbox\DigitalRuby.SimpleCache.Sandbox.csproj", "{CB0257DD-3D4A-4C42-B7C0-EC626C662CFA}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "SolutionItems", "SolutionItems", "{96B77B60-6CDC-47A9-8861-B55FC991CA5C}"
+	ProjectSection(SolutionItems) = preProject
+		.gitignore = .gitignore
+		icon.png = icon.png
+		LICENSE = LICENSE
+		README.md = README.md
+	EndProjectSection
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution

DigitalRuby.SimpleCache.sln

@@ -19,21 +19,31 @@ public struct CacheParameters
 	/// Constructor
 	/// </summary>
 	/// <param name="duration">Duration</param>
-	public CacheParameters(TimeSpan duration)
+	/// <param name="jitterDuration">Whether to jitter the duration</param>
+	public CacheParameters(TimeSpan duration, bool jitterDuration = true)
 	{
 		Duration = duration;
 		Size = DefaultSize;
+		if (jitterDuration)
+		{
+			JitterDuration();
+		}
 	}
 
 	/// <summary>
 	/// Constructor
 	/// </summary>
 	/// <param name="duration">Duration</param>
 	/// <param name="size">Size</param>
-	public CacheParameters(TimeSpan duration, int size)
+	/// <param name="jitterDuration">Whether to jitter the duration</param>
+	public CacheParameters(TimeSpan duration, int size, bool jitterDuration = true)
 	{
 		Duration = duration;
-		Size = size;
+		Size = size <= 0 ? DefaultSize : size;
+		if (jitterDuration)
+		{
+			JitterDuration();
+		}
 	}
 
 	/// <summary>
@@ -53,33 +63,32 @@ internal static void AssignDefaultIfNeeded(ref CacheParameters cacheParameters)
 	private static readonly ThreadLocal<Random> jitter = new(() => new Random());
 
 	/// <summary>
-	/// Jitter the cache duration, ensure that we don't have a bunch of stuff expiring right at the same time
+	/// Wiggle the cache duration slightly to avoid having multiple cache items expire all at once
 	/// </summary>
-	/// <param name="cacheParameters">Cache parameters</param>
-	internal static void JitterDuration(ref CacheParameters cacheParameters)
+	private void JitterDuration()
 	{
 		double upperJitter;
-		if (cacheParameters.Duration.TotalMinutes <= 1.0)
+		if (Duration.TotalMinutes <= 1.0)
 		{
 			// don't jitter cache times 1 minute or less
 			return;
 		}
-		else if (cacheParameters.Duration.TotalMinutes <= 15.0)
+		else if (Duration.TotalMinutes <= 15.0)
 		{
 			// up to 15 min
 			upperJitter = 1.2;
 		}
-		else if (cacheParameters.Duration.TotalMinutes <= 60.0)
+		else if (Duration.TotalMinutes <= 60.0)
 		{
 			// up to 1 hour
 			upperJitter = 1.15;
 		}
-		else if (cacheParameters.Duration.TotalMinutes <= 360.0)
+		else if (Duration.TotalMinutes <= 360.0)
 		{
 			// up to 6 hours
 			upperJitter = 1.1;
 		}
-		else if (cacheParameters.Duration.TotalMinutes <= 1440.0)
+		else if (Duration.TotalMinutes <= 1440.0)
 		{
 			// up to 24 hours
 			upperJitter = 1.05;
@@ -92,8 +101,8 @@ internal static void JitterDuration(ref CacheParameters cacheParameters)
 
 		double randomDouble = jitter.Value!.NextDouble();
 		double multiplier = 1.0 + (randomDouble * upperJitter);
-		long jitteredTicks = (long)(cacheParameters.Duration.Ticks * multiplier);
-		cacheParameters.Duration = TimeSpan.FromTicks(jitteredTicks);
+		long jitteredTicks = (long)(Duration.Ticks * multiplier);
+		Duration = TimeSpan.FromTicks(jitteredTicks);
 	}
 
 	/// <summary>

DigitalRuby.SimpleCache/CacheParameters.cs

@@ -3,13 +3,8 @@
 /// <summary>
 /// Allows mocking current date/time and delays
 /// </summary>
-public interface IDateTimeProvider
+public interface IClockHandler : ISystemClock
 {
-	/// <summary>
-	/// Current date/time
-	/// </summary>
-	DateTimeOffset UtcNow { get; }
-
 	/// <summary>
 	/// Delay for a set amount of time
 	/// </summary>
@@ -20,9 +15,9 @@ public interface IDateTimeProvider
 }
 
 /// <summary>
-/// Piggy back on IDateTimeProvider interface
+/// Implement IClockHandler
 /// </summary>
-public sealed class DateTimeProvider : IDateTimeProvider
+public sealed class ClockHandler : IClockHandler
 {
 	/// <inheritdoc />
 	public DateTimeOffset UtcNow => DateTimeOffset.UtcNow;

DigitalRuby.SimpleCache/DateTimeProvider.cs renamed to DigitalRuby.SimpleCache/ClockHandler.cs

@@ -17,10 +17,4 @@
 		<PackageReference Include="SauceControl.Blake2Fast" Version="2.0.0" />
 	</ItemGroup>
 
-	<ItemGroup>
-		<AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleToAttribute">
-			<_Parameter1>$(AssemblyName).Tests</_Parameter1>
-		</AssemblyAttribute>
-	</ItemGroup>
-
 </Project>

DigitalRuby.SimpleCache/DigitalRuby.SimpleCache.csproj

@@ -69,7 +69,11 @@ public interface IDistributedCache
 /// </summary>
 public sealed class DistributedMemoryCache : IDistributedCache, IDistributedLockFactory
 {
-    private sealed class FakeDistributedLock : IAsyncDisposable
+	private readonly ISystemClock clock;
+
+	public DistributedMemoryCache(ISystemClock clock) => this.clock = clock;
+
+	private sealed class FakeDistributedLock : IAsyncDisposable
     {
         public ValueTask DisposeAsync()
         {
@@ -328,7 +332,7 @@ public interface IDistributedLockFactory
 	/// Attempt to acquire a distributed lock
 	/// </summary>
 	/// <param name="key">Lock key</param>
-	/// <param name="lockTime">Duration to acquire the lock before it auto-expires</param>
+	/// <param name="lockTime">Duration to hold the lock before it auto-expires. Set this to the maximum possible duration you think your code might hold the lock.</param>
 	/// <param name="timeout">Time out to acquire the lock or default to only make one attempt to acquire the lock</param>
 	/// <returns>The lock or null if the lock could not be acquired</returns>
 	Task<IAsyncDisposable?> TryAcquireLockAsync(string key, TimeSpan lockTime, TimeSpan timeout = default);