fix: validate debounce delay to ensure non-negative values in cache options

Mykyta Zotov · Mykyta Zotov · commit 511bbab58bfe · 2026-03-04T00:49:20.000+01:00
diff --git a/src/SlidingWindowCache/Core/State/RuntimeCacheOptions.cs b/src/SlidingWindowCache/Core/State/RuntimeCacheOptions.cs
@@ -40,10 +40,10 @@ internal sealed class RuntimeCacheOptions
     /// <param name="rightCacheSize">The coefficient for the right cache size. Must be ≥ 0.</param>
     /// <param name="leftThreshold">The left no-rebalance threshold percentage. Must be in [0, 1] when not null.</param>
     /// <param name="rightThreshold">The right no-rebalance threshold percentage. Must be in [0, 1] when not null.</param>
-    /// <param name="debounceDelay">The debounce delay applied before executing a rebalance.</param>
+    /// <param name="debounceDelay">The debounce delay applied before executing a rebalance. Must be non-negative.</param>
     /// <exception cref="ArgumentOutOfRangeException">
     /// Thrown when <paramref name="leftCacheSize"/> or <paramref name="rightCacheSize"/> is less than 0,
-    /// or when a threshold value is outside [0, 1].
+    /// when a threshold value is outside [0, 1], or when <paramref name="debounceDelay"/> is negative.
     /// </exception>
     /// <exception cref="ArgumentException">
     /// Thrown when both thresholds are specified and their sum exceeds 1.0.
@@ -58,6 +58,12 @@ public RuntimeCacheOptions(
         RuntimeOptionsValidator.ValidateCacheSizesAndThresholds(
             leftCacheSize, rightCacheSize, leftThreshold, rightThreshold);
 
+        if (debounceDelay < TimeSpan.Zero)
+        {
+            throw new ArgumentOutOfRangeException(nameof(debounceDelay),
+                "DebounceDelay must be non-negative.");
+        }
+
         LeftCacheSize = leftCacheSize;
         RightCacheSize = rightCacheSize;
         LeftThreshold = leftThreshold;
diff --git a/src/SlidingWindowCache/Public/Configuration/RuntimeOptionsUpdateBuilder.cs b/src/SlidingWindowCache/Public/Configuration/RuntimeOptionsUpdateBuilder.cs
@@ -130,6 +130,12 @@ public RuntimeOptionsUpdateBuilder ClearRightThreshold()
     /// <returns>This builder, for fluent chaining.</returns>
     public RuntimeOptionsUpdateBuilder WithDebounceDelay(TimeSpan value)
     {
+        if (value < TimeSpan.Zero)
+        {
+            throw new ArgumentOutOfRangeException(nameof(value),
+                "DebounceDelay must be non-negative.");
+        }
+
         _debounceDelay = value;
         return this;
     }
diff --git a/src/SlidingWindowCache/Public/Configuration/WindowCacheOptions.cs b/src/SlidingWindowCache/Public/Configuration/WindowCacheOptions.cs
@@ -41,7 +41,7 @@ public sealed class WindowCacheOptions : IEquatable<WindowCacheOptions>
     /// </param>
     /// <exception cref="ArgumentOutOfRangeException">
     /// Thrown when LeftCacheSize, RightCacheSize, LeftThreshold, RightThreshold is less than 0,
-    /// or when RebalanceQueueCapacity is less than or equal to 0.
+    /// when DebounceDelay is negative, or when RebalanceQueueCapacity is less than or equal to 0.
     /// </exception>
     /// <exception cref="ArgumentException">
     /// Thrown when the sum of LeftThreshold and RightThreshold exceeds 1.0.
@@ -65,6 +65,12 @@ public WindowCacheOptions(
                 "RebalanceQueueCapacity must be greater than 0 or null.");
         }
 
+        if (debounceDelay.HasValue && debounceDelay.Value < TimeSpan.Zero)
+        {
+            throw new ArgumentOutOfRangeException(nameof(debounceDelay),
+                "DebounceDelay must be non-negative.");
+        }
+
         LeftCacheSize = leftCacheSize;
         RightCacheSize = rightCacheSize;
         ReadMode = readMode;
diff --git a/src/SlidingWindowCache/Public/Configuration/WindowCacheOptionsBuilder.cs b/src/SlidingWindowCache/Public/Configuration/WindowCacheOptionsBuilder.cs
@@ -182,6 +182,12 @@ public WindowCacheOptionsBuilder WithThresholds(double value)
     /// <returns>This builder instance, for fluent chaining.</returns>
     public WindowCacheOptionsBuilder WithDebounceDelay(TimeSpan value)
     {
+        if (value < TimeSpan.Zero)
+        {
+            throw new ArgumentOutOfRangeException(nameof(value),
+                "DebounceDelay must be non-negative.");
+        }
+
         _debounceDelay = value;
         return this;
     }
diff --git a/tests/SlidingWindowCache.Unit.Tests/Public/Configuration/RuntimeOptionsUpdateBuilderTests.cs b/tests/SlidingWindowCache.Unit.Tests/Public/Configuration/RuntimeOptionsUpdateBuilderTests.cs
@@ -11,27 +11,15 @@ public class RuntimeOptionsUpdateBuilderTests
 {
     private static RuntimeCacheOptions BaseOptions() => new(1.0, 2.0, 0.1, 0.2, TimeSpan.FromMilliseconds(50));
 
-    // Helper to create an internal builder via WindowCache (public API) isn't needed here
-    // because we can test ApplyTo directly via internal access.
-    // However, RuntimeOptionsUpdateBuilder's ctor is internal, so we access it via WindowCache.
-    // Instead we test the builder indirectly through WindowCache.UpdateRuntimeOptions.
-    // For pure unit tests of the builder logic, we use InternalsVisibleTo.
-
-    // Since RuntimeOptionsUpdateBuilder constructor is internal but the tests are in a separate
-    // assembly, we verify builder behaviour through ApplyTo by instantiating via reflection,
-    // or test the full behaviour through WindowCache integration tests.
-    // Here we use the WindowCache public API to exercise each builder method.
-
     #region Builder Method Tests — WithLeftCacheSize
 
     [Fact]
     public void ApplyTo_WithLeftCacheSizeSet_ChangesOnlyLeftCacheSize()
     {
-        // We test ApplyTo indirectly: create builder through internal constructor via reflection.
-        var builder = CreateBuilder();
+        var builder = new RuntimeOptionsUpdateBuilder();
         builder.WithLeftCacheSize(5.0);
 
-        var result = InvokeApplyTo(builder, BaseOptions());
+        var result = builder.ApplyTo(BaseOptions());
 
         Assert.Equal(5.0, result.LeftCacheSize);
         Assert.Equal(2.0, result.RightCacheSize);     // unchanged
@@ -47,10 +35,10 @@ public void ApplyTo_WithLeftCacheSizeSet_ChangesOnlyLeftCacheSize()
     [Fact]
     public void ApplyTo_WithRightCacheSizeSet_ChangesOnlyRightCacheSize()
     {
-        var builder = CreateBuilder();
+        var builder = new RuntimeOptionsUpdateBuilder();
         builder.WithRightCacheSize(7.0);
 
-        var result = InvokeApplyTo(builder, BaseOptions());
+        var result = builder.ApplyTo(BaseOptions());
 
         Assert.Equal(1.0, result.LeftCacheSize);      // unchanged
         Assert.Equal(7.0, result.RightCacheSize);
@@ -66,10 +54,10 @@ public void ApplyTo_WithRightCacheSizeSet_ChangesOnlyRightCacheSize()
     [Fact]
     public void ApplyTo_WithLeftThresholdSet_UpdatesLeftThreshold()
     {
-        var builder = CreateBuilder();
+        var builder = new RuntimeOptionsUpdateBuilder();
         builder.WithLeftThreshold(0.3);
 
-        var result = InvokeApplyTo(builder, BaseOptions());
+        var result = builder.ApplyTo(BaseOptions());
 
         Assert.Equal(0.3, result.LeftThreshold);
         Assert.Equal(0.2, result.RightThreshold); // unchanged
@@ -78,10 +66,10 @@ public void ApplyTo_WithLeftThresholdSet_UpdatesLeftThreshold()
     [Fact]
     public void ApplyTo_ClearLeftThreshold_SetsLeftThresholdToNull()
     {
-        var builder = CreateBuilder();
+        var builder = new RuntimeOptionsUpdateBuilder();
         builder.ClearLeftThreshold();
 
-        var result = InvokeApplyTo(builder, BaseOptions());
+        var result = builder.ApplyTo(BaseOptions());
 
         Assert.Null(result.LeftThreshold);
         Assert.Equal(0.2, result.RightThreshold); // unchanged
@@ -91,10 +79,10 @@ public void ApplyTo_ClearLeftThreshold_SetsLeftThresholdToNull()
     public void ApplyTo_LeftThresholdNotSet_KeepsCurrentValue()
     {
         // No threshold method called on builder
-        var builder = CreateBuilder();
+        var builder = new RuntimeOptionsUpdateBuilder();
         builder.WithLeftCacheSize(3.0); // only set left cache size
 
-        var result = InvokeApplyTo(builder, BaseOptions());
+        var result = builder.ApplyTo(BaseOptions());
 
         Assert.Equal(0.1, result.LeftThreshold); // unchanged from base
     }
@@ -106,10 +94,10 @@ public void ApplyTo_LeftThresholdNotSet_KeepsCurrentValue()
     [Fact]
     public void ApplyTo_WithRightThresholdSet_UpdatesRightThreshold()
     {
-        var builder = CreateBuilder();
+        var builder = new RuntimeOptionsUpdateBuilder();
         builder.WithRightThreshold(0.35);
 
-        var result = InvokeApplyTo(builder, BaseOptions());
+        var result = builder.ApplyTo(BaseOptions());
 
         Assert.Equal(0.35, result.RightThreshold);
         Assert.Equal(0.1, result.LeftThreshold); // unchanged
@@ -118,10 +106,10 @@ public void ApplyTo_WithRightThresholdSet_UpdatesRightThreshold()
     [Fact]
     public void ApplyTo_ClearRightThreshold_SetsRightThresholdToNull()
     {
-        var builder = CreateBuilder();
+        var builder = new RuntimeOptionsUpdateBuilder();
         builder.ClearRightThreshold();
 
-        var result = InvokeApplyTo(builder, BaseOptions());
+        var result = builder.ApplyTo(BaseOptions());
 
         Assert.Null(result.RightThreshold);
         Assert.Equal(0.1, result.LeftThreshold); // unchanged
@@ -130,11 +118,11 @@ public void ApplyTo_ClearRightThreshold_SetsRightThresholdToNull()
     [Fact]
     public void ApplyTo_RightThresholdNotSet_KeepsCurrentValue()
     {
-        var builder = CreateBuilder();
+        var builder = new RuntimeOptionsUpdateBuilder();
         // Only change debounce
         builder.WithDebounceDelay(TimeSpan.Zero);
 
-        var result = InvokeApplyTo(builder, BaseOptions());
+        var result = builder.ApplyTo(BaseOptions());
 
         Assert.Equal(0.2, result.RightThreshold); // unchanged from base
     }
@@ -146,10 +134,10 @@ public void ApplyTo_RightThresholdNotSet_KeepsCurrentValue()
     [Fact]
     public void ApplyTo_WithDebounceDelaySet_ChangesOnlyDebounceDelay()
     {
-        var builder = CreateBuilder();
+        var builder = new RuntimeOptionsUpdateBuilder();
         builder.WithDebounceDelay(TimeSpan.FromSeconds(1));
 
-        var result = InvokeApplyTo(builder, BaseOptions());
+        var result = builder.ApplyTo(BaseOptions());
 
         Assert.Equal(TimeSpan.FromSeconds(1), result.DebounceDelay);
         Assert.Equal(1.0, result.LeftCacheSize);  // unchanged
@@ -164,15 +152,15 @@ public void ApplyTo_WithDebounceDelaySet_ChangesOnlyDebounceDelay()
     public void ApplyTo_FluentChain_AppliesAllChanges()
     {
         var base_ = new RuntimeCacheOptions(1.0, 1.0, null, null, TimeSpan.Zero);
-        var builder = CreateBuilder();
+        var builder = new RuntimeOptionsUpdateBuilder();
         builder
             .WithLeftCacheSize(2.0)
             .WithRightCacheSize(3.0)
             .WithLeftThreshold(0.1)
             .WithRightThreshold(0.15)
             .WithDebounceDelay(TimeSpan.FromMilliseconds(75));
 
-        var result = InvokeApplyTo(builder, base_);
+        var result = builder.ApplyTo(base_);
 
         Assert.Equal(2.0, result.LeftCacheSize);
         Assert.Equal(3.0, result.RightCacheSize);
@@ -185,9 +173,9 @@ public void ApplyTo_FluentChain_AppliesAllChanges()
     public void ApplyTo_EmptyBuilder_ReturnsSnapshotWithAllCurrentValues()
     {
         var base_ = BaseOptions();
-        var builder = CreateBuilder();
+        var builder = new RuntimeOptionsUpdateBuilder();
 
-        var result = InvokeApplyTo(builder, base_);
+        var result = builder.ApplyTo(base_);
 
         Assert.Equal(base_.LeftCacheSize, result.LeftCacheSize);
         Assert.Equal(base_.RightCacheSize, result.RightCacheSize);
@@ -203,10 +191,10 @@ public void ApplyTo_EmptyBuilder_ReturnsSnapshotWithAllCurrentValues()
     [Fact]
     public void ApplyTo_WithInvalidMergedCacheSize_ThrowsArgumentOutOfRangeException()
     {
-        var builder = CreateBuilder();
+        var builder = new RuntimeOptionsUpdateBuilder();
         builder.WithLeftCacheSize(-1.0);
 
-        var exception = Record.Exception(() => InvokeApplyTo(builder, BaseOptions()));
+        var exception = Record.Exception(() => builder.ApplyTo(BaseOptions()));
 
         Assert.NotNull(exception);
         Assert.IsType<ArgumentOutOfRangeException>(exception);
@@ -216,43 +204,28 @@ public void ApplyTo_WithInvalidMergedCacheSize_ThrowsArgumentOutOfRangeException
     public void ApplyTo_WithThresholdSumExceedingOne_ThrowsArgumentException()
     {
         // Base has leftThreshold=0.1; set right=0.95 → sum=1.05
-        var builder = CreateBuilder();
+        var builder = new RuntimeOptionsUpdateBuilder();
         builder.WithRightThreshold(0.95);
 
-        var exception = Record.Exception(() => InvokeApplyTo(builder, BaseOptions()));
+        var exception = Record.Exception(() => builder.ApplyTo(BaseOptions()));
 
         Assert.NotNull(exception);
         Assert.IsType<ArgumentException>(exception);
     }
 
-    #endregion
-
-    // Helpers — create builder via internal constructor using reflection,
-    // and invoke the internal ApplyTo method.
-    private static RuntimeOptionsUpdateBuilder CreateBuilder()
+    [Fact]
+    public void WithDebounceDelay_WithNegativeValue_ThrowsArgumentOutOfRangeException()
     {
-        var ctor = typeof(RuntimeOptionsUpdateBuilder)
-            .GetConstructor(
-                System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance,
-                null, Type.EmptyTypes, null)!;
-        return (RuntimeOptionsUpdateBuilder)ctor.Invoke(null);
-    }
+        // ARRANGE
+        var builder = new RuntimeOptionsUpdateBuilder();
 
-    private static RuntimeCacheOptions InvokeApplyTo(
-        RuntimeOptionsUpdateBuilder builder,
-        RuntimeCacheOptions current)
-    {
-        var method = typeof(RuntimeOptionsUpdateBuilder)
-            .GetMethod("ApplyTo",
-                System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance)!;
-        try
-        {
-            return (RuntimeCacheOptions)method.Invoke(builder, [current])!;
-        }
-        catch (System.Reflection.TargetInvocationException ex) when (ex.InnerException is not null)
-        {
-            System.Runtime.ExceptionServices.ExceptionDispatchInfo.Capture(ex.InnerException).Throw();
-            throw; // unreachable, satisfies compiler
-        }
+        // ACT
+        var exception = Record.Exception(() => builder.WithDebounceDelay(TimeSpan.FromMilliseconds(-1)));
+
+        // ASSERT
+        Assert.NotNull(exception);
+        Assert.IsType<ArgumentOutOfRangeException>(exception);
     }
+
+    #endregion
 }
diff --git a/tests/SlidingWindowCache.Unit.Tests/Public/Configuration/WindowCacheOptionsBuilderTests.cs b/tests/SlidingWindowCache.Unit.Tests/Public/Configuration/WindowCacheOptionsBuilderTests.cs
@@ -354,6 +354,20 @@ public void Build_WithZeroDebounceDelay_SetsZero()
         Assert.Equal(TimeSpan.Zero, options.DebounceDelay);
     }
 
+    [Fact]
+    public void WithDebounceDelay_WithNegativeValue_ThrowsArgumentOutOfRangeException()
+    {
+        // ARRANGE
+        var builder = new WindowCacheOptionsBuilder().WithCacheSize(1.0);
+
+        // ACT
+        var exception = Record.Exception(() => builder.WithDebounceDelay(TimeSpan.FromMilliseconds(-1)));
+
+        // ASSERT
+        Assert.NotNull(exception);
+        Assert.IsType<ArgumentOutOfRangeException>(exception);
+    }
+
     #endregion
 
     #region WithRebalanceQueueCapacity Tests
diff --git a/tests/SlidingWindowCache.Unit.Tests/Public/Configuration/WindowCacheOptionsTests.cs b/tests/SlidingWindowCache.Unit.Tests/Public/Configuration/WindowCacheOptionsTests.cs
@@ -324,6 +324,25 @@ public void Constructor_WithVerySmallNegativeRightCacheSize_ThrowsArgumentOutOfR
         Assert.Equal("rightCacheSize", exception.ParamName);
     }
 
+    [Fact]
+    public void Constructor_WithNegativeDebounceDelay_ThrowsArgumentOutOfRangeException()
+    {
+        // ARRANGE, ACT & ASSERT
+        var exception = Record.Exception(() =>
+            new WindowCacheOptions(
+                leftCacheSize: 1.0,
+                rightCacheSize: 1.0,
+                readMode: UserCacheReadMode.Snapshot,
+                debounceDelay: TimeSpan.FromMilliseconds(-1)
+            )
+        );
+
+        Assert.NotNull(exception);
+        Assert.IsType<ArgumentOutOfRangeException>(exception);
+        var argException = (ArgumentOutOfRangeException)exception;
+        Assert.Equal("debounceDelay", argException.ParamName);
+    }
+
     #endregion
 
     #region Constructor - Threshold Sum Validation Tests
@@ -690,26 +709,6 @@ public void GetHashCode_WithSameValues_ReturnsSameHashCode()
         Assert.Equal(options1.GetHashCode(), options2.GetHashCode());
     }
 
-    [Fact]
-    public void GetHashCode_WithDifferentValues_ReturnsDifferentHashCode()
-    {
-        // ARRANGE
-        var options1 = new WindowCacheOptions(
-            leftCacheSize: 1.0,
-            rightCacheSize: 1.0,
-            readMode: UserCacheReadMode.Snapshot
-        );
-
-        var options2 = new WindowCacheOptions(
-            leftCacheSize: 2.0,
-            rightCacheSize: 1.0,
-            readMode: UserCacheReadMode.Snapshot
-        );
-
-        // ACT & ASSERT — hash codes should differ (not guaranteed but expected for distinct values)
-        Assert.NotEqual(options1.GetHashCode(), options2.GetHashCode());
-    }
-
     #endregion
 
     #region Edge Cases and Boundary Tests

Original file line number	Diff line number	Diff line change
`@@ -130,6 +130,12 @@ public RuntimeOptionsUpdateBuilder ClearRightThreshold()`
`130`	`130`	`/// <returns>This builder, for fluent chaining.</returns>`
`131`	`131`	`public RuntimeOptionsUpdateBuilder WithDebounceDelay(TimeSpan value)`
`132`	`132`	`{`
	`133`	`+ if (value < TimeSpan.Zero)`
	`134`	`+ {`
	`135`	`+ throw new ArgumentOutOfRangeException(nameof(value),`
	`136`	`+ "DebounceDelay must be non-negative.");`
	`137`	`+ }`
	`138`	`+`
`133`	`139`	`_debounceDelay = value;`
`134`	`140`	`return this;`
`135`	`141`	`}`
Original file line number	Diff line number	Diff line change
`@@ -182,6 +182,12 @@ public WindowCacheOptionsBuilder WithThresholds(double value)`
`182`	`182`	`/// <returns>This builder instance, for fluent chaining.</returns>`
`183`	`183`	`public WindowCacheOptionsBuilder WithDebounceDelay(TimeSpan value)`
`184`	`184`	`{`
	`185`	`+ if (value < TimeSpan.Zero)`
	`186`	`+ {`
	`187`	`+ throw new ArgumentOutOfRangeException(nameof(value),`
	`188`	`+ "DebounceDelay must be non-negative.");`
	`189`	`+ }`
	`190`	`+`
`185`	`191`	`_debounceDelay = value;`
`186`	`192`	`return this;`
`187`	`193`	`}`