#49 Support MaxValue "never expire" sentinels; polish range errors and logs

Address review feedback from mtmk:
- Treat DateTimeOffset.MaxValue / TimeSpan.MaxValue expirations as "cache
  forever" (no TTL) instead of rejecting them as out-of-range — a common
  "never expire" idiom, normalized to no expiration in GetTtl/CreateCacheEntry.
- Include the maximum window in the range-check exception messages.
- Use PascalCase structured log property names ({Key}).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Matthew DeVenny <matt@codecargo.com>

Author: matthewdevenny

src/NatsDistributedCache/CacheEntryBinarySerializer.cs

@@ -37,6 +37,11 @@ internal sealed class CacheEntryBinarySerializer : INatsSerialize<CacheEntry>, I
     /// </summary>
     internal const long MaxTtlTicks = int.MaxValue * TimeSpan.TicksPerSecond;
 
+    /// <summary>
+    /// <see cref="MaxTtlTicks"/> as a <see cref="TimeSpan"/>, for range-check exception messages.
+    /// </summary>
+    internal static readonly TimeSpan MaxTtl = TimeSpan.FromTicks(MaxTtlTicks);
+
     private const byte HasAbsoluteExpiration = 0b0000_0001;
     private const byte HasSlidingExpiration = 0b0000_0010;
     private const byte KnownFlags = HasAbsoluteExpiration | HasSlidingExpiration;

src/NatsDistributedCache/NatsCache.Log.cs

@@ -16,7 +16,7 @@ private void LogSwallowedException(Exception exception) =>
     private void LogUndeserializableEntry(string key) =>
         _logger.LogDebug(
             EventIds.UndeserializableEntry,
-            "Cache entry for key {key} could not be deserialized (legacy or corrupt format); returning a cache miss",
+            "Cache entry for key {Key} could not be deserialized (legacy or corrupt format); returning a cache miss",
             key);
 
     private static class EventIds

src/NatsDistributedCache/NatsCache.cs

@@ -206,50 +206,56 @@ public async ValueTask<bool> TryGetAsync(
 
     internal TimeSpan? GetTtl(DistributedCacheEntryOptions options)
     {
-        if (options.AbsoluteExpiration.HasValue && options.AbsoluteExpiration.Value <= TimeProvider.GetUtcNow())
+        // Maximum-value sentinels mean "never expire": normalize them to no expiration so they are not
+        // rejected as out-of-range below. Callers commonly use DateTimeOffset.MaxValue / TimeSpan.MaxValue
+        // as a "cache forever" idiom, which is equivalent to omitting expiration entirely.
+        var absoluteExpiration = EffectiveAbsoluteExpiration(options);
+        var relativeToNow = EffectiveRelativeToNow(options);
+        var slidingExpiration = EffectiveSlidingExpiration(options);
+
+        if (absoluteExpiration.HasValue && absoluteExpiration.Value <= TimeProvider.GetUtcNow())
         {
             throw new ArgumentOutOfRangeException(
                 nameof(DistributedCacheEntryOptions.AbsoluteExpiration),
-                options.AbsoluteExpiration.Value,
+                absoluteExpiration.Value,
                 "The absolute expiration value must be in the future.");
         }
 
-        if (options.AbsoluteExpirationRelativeToNow.HasValue &&
-            options.AbsoluteExpirationRelativeToNow.Value <= TimeSpan.Zero)
+        if (relativeToNow.HasValue && relativeToNow.Value <= TimeSpan.Zero)
         {
             throw new ArgumentOutOfRangeException(
                 nameof(DistributedCacheEntryOptions.AbsoluteExpirationRelativeToNow),
-                options.AbsoluteExpirationRelativeToNow.Value,
+                relativeToNow.Value,
                 "The relative expiration value must be positive.");
         }
 
-        if (options.SlidingExpiration.HasValue && options.SlidingExpiration.Value <= TimeSpan.Zero)
+        if (slidingExpiration.HasValue && slidingExpiration.Value <= TimeSpan.Zero)
         {
             throw new ArgumentOutOfRangeException(
                 nameof(DistributedCacheEntryOptions.SlidingExpiration),
-                options.SlidingExpiration.Value,
+                slidingExpiration.Value,
                 "The sliding expiration value must be positive.");
         }
 
         // Reject sliding windows the serializer/TTL encoding could not round-trip. The read path fails
         // closed above MaxTtlTicks, so accepting a larger value here would silently store an entry that
         // later reads back as an undeserializable cache miss.
-        if (options.SlidingExpiration.HasValue &&
-            options.SlidingExpiration.Value.Ticks > CacheEntryBinarySerializer.MaxTtlTicks)
+        if (slidingExpiration.HasValue &&
+            slidingExpiration.Value.Ticks > CacheEntryBinarySerializer.MaxTtlTicks)
         {
             throw new ArgumentOutOfRangeException(
                 nameof(DistributedCacheEntryOptions.SlidingExpiration),
-                options.SlidingExpiration.Value,
-                "The sliding expiration value is too large.");
+                slidingExpiration.Value,
+                $"The sliding expiration value is too large. The maximum is {CacheEntryBinarySerializer.MaxTtl}.");
         }
 
-        var absoluteExpiration = ResolveAbsoluteExpiration(options);
-        if (!absoluteExpiration.HasValue)
+        var resolvedAbsolute = ResolveAbsoluteExpiration(options);
+        if (!resolvedAbsolute.HasValue)
         {
-            return options.SlidingExpiration;
+            return slidingExpiration;
         }
 
-        var ttl = absoluteExpiration.Value - TimeProvider.GetUtcNow();
+        var ttl = resolvedAbsolute.Value - TimeProvider.GetUtcNow();
         if (ttl.TotalMilliseconds <= 0)
         {
             // Value is in the past, remove it
@@ -258,28 +264,28 @@ public async ValueTask<bool> TryGetAsync(
 
         // If there's also a sliding expiration, use the minimum of the two. Sliding is bounded to
         // MaxTtlTicks above, so the minimum is always within the encodable range.
-        if (options.SlidingExpiration.HasValue)
+        if (slidingExpiration.HasValue)
         {
-            return TimeSpan.FromTicks(Math.Min(ttl.Ticks, options.SlidingExpiration.Value.Ticks));
+            return TimeSpan.FromTicks(Math.Min(ttl.Ticks, slidingExpiration.Value.Ticks));
         }
 
         // Absolute-only: the TTL spans the full window to the absolute instant. Reject windows the NATS
         // TTL encoding cannot represent (see CacheEntryBinarySerializer.MaxTtlTicks) rather than emitting
         // an overflowed header.
         if (ttl.Ticks > CacheEntryBinarySerializer.MaxTtlTicks)
         {
-            if (options.AbsoluteExpirationRelativeToNow.HasValue)
+            if (relativeToNow.HasValue)
             {
                 throw new ArgumentOutOfRangeException(
                     nameof(DistributedCacheEntryOptions.AbsoluteExpirationRelativeToNow),
-                    options.AbsoluteExpirationRelativeToNow.Value,
-                    "The relative expiration value is too large.");
+                    relativeToNow.Value,
+                    $"The relative expiration value is too large. The maximum is {CacheEntryBinarySerializer.MaxTtl}.");
             }
 
             throw new ArgumentOutOfRangeException(
                 nameof(DistributedCacheEntryOptions.AbsoluteExpiration),
-                options.AbsoluteExpiration!.Value,
-                "The absolute expiration is too far in the future.");
+                absoluteExpiration!.Value,
+                $"The absolute expiration is too far in the future. The maximum window is {CacheEntryBinarySerializer.MaxTtl}.");
         }
 
         return ttl;
@@ -290,7 +296,7 @@ internal CacheEntry CreateCacheEntry(byte[] value, DistributedCacheEntryOptions
         {
             Data = value,
             AbsoluteExpiration = ResolveAbsoluteExpiration(options),
-            SlidingExpirationTicks = options.SlidingExpiration?.Ticks
+            SlidingExpirationTicks = EffectiveSlidingExpiration(options)?.Ticks
         };
 
     // An entry is absolutely expired once the clock reaches its absolute expiration instant. The
@@ -326,12 +332,27 @@ internal NatsKVConfig BuildBucketConfig()
         return config;
     }
 
+    // "Never expire" sentinels: a DateTimeOffset.MaxValue absolute instant or a TimeSpan.MaxValue window
+    // is normalized to no expiration, so it is not rejected as out-of-range and the entry lives forever.
+    private static DateTimeOffset? EffectiveAbsoluteExpiration(DistributedCacheEntryOptions options) =>
+        options.AbsoluteExpiration == DateTimeOffset.MaxValue ? null : options.AbsoluteExpiration;
+
+    private static TimeSpan? EffectiveRelativeToNow(DistributedCacheEntryOptions options) =>
+        options.AbsoluteExpirationRelativeToNow == TimeSpan.MaxValue ? null : options.AbsoluteExpirationRelativeToNow;
+
+    private static TimeSpan? EffectiveSlidingExpiration(DistributedCacheEntryOptions options) =>
+        options.SlidingExpiration == TimeSpan.MaxValue ? null : options.SlidingExpiration;
+
     // Resolves the effective absolute expiration instant: a relative expiration (offset from the
     // current clock) takes precedence over an explicit absolute expiration when both are set.
-    private DateTimeOffset? ResolveAbsoluteExpiration(DistributedCacheEntryOptions options) =>
-        options.AbsoluteExpirationRelativeToNow.HasValue
-            ? TimeProvider.GetUtcNow().Add(options.AbsoluteExpirationRelativeToNow.Value)
-            : options.AbsoluteExpiration;
+    // Maximum-value sentinels are treated as "no expiration" (see the Effective* helpers).
+    private DateTimeOffset? ResolveAbsoluteExpiration(DistributedCacheEntryOptions options)
+    {
+        var relativeToNow = EffectiveRelativeToNow(options);
+        return relativeToNow.HasValue
+            ? TimeProvider.GetUtcNow().Add(relativeToNow.Value)
+            : EffectiveAbsoluteExpiration(options);
+    }
 
     private string GetEncodedKey(string key) =>
         string.IsNullOrEmpty(_keyPrefix)

test/UnitTests/Cache/TimeExpirationUnitTests.cs

@@ -98,17 +98,18 @@ public void TooLargeSlidingExpirationThrows()
         var key = MethodKey();
         var value = new byte[1];
 
-        // TimeSpan.MaxValue is far beyond the ceiling the NATS TTL encoding supports (int.MaxValue
-        // seconds), so the write path must reject it rather than store an entry that later reads back
+        // A window beyond the NATS TTL encoding ceiling (~68 years) but short of the TimeSpan.MaxValue
+        // "never expire" sentinel must be rejected rather than stored as an entry that later reads back
         // as an undeserializable miss or emits an overflowed TTL header.
+        var sliding = TimeSpan.FromDays(365 * 100);
         ExceptionAssert.ThrowsArgumentOutOfRange(
             () =>
             {
-                Cache.Set(key, value, new DistributedCacheEntryOptions().SetSlidingExpiration(TimeSpan.MaxValue));
+                Cache.Set(key, value, new DistributedCacheEntryOptions().SetSlidingExpiration(sliding));
             },
             nameof(DistributedCacheEntryOptions.SlidingExpiration),
             "The sliding expiration value is too large.",
-            TimeSpan.MaxValue);
+            sliding);
     }
 
     [Fact]

test/UnitTests/Cache/TimeProviderExpirationUnitTests.cs

@@ -119,4 +119,39 @@ public void GetTtlWithFarAbsoluteAndSlidingReturnsSliding()
 
         Assert.Equal(TimeSpan.FromMinutes(10), ttl);
     }
+
+    // DateTimeOffset.MaxValue / TimeSpan.MaxValue mean "cache forever": no TTL, not an out-of-range throw.
+    [Fact]
+    public void GetTtlTreatsMaxAbsoluteInstantAsNoExpiration() =>
+        Assert.Null(Cache.GetTtl(new DistributedCacheEntryOptions().SetAbsoluteExpiration(DateTimeOffset.MaxValue)));
+
+    [Fact]
+    public void GetTtlTreatsMaxRelativeExpirationAsNoExpiration() =>
+        Assert.Null(Cache.GetTtl(new DistributedCacheEntryOptions().SetAbsoluteExpiration(TimeSpan.MaxValue)));
+
+    [Fact]
+    public void GetTtlTreatsMaxSlidingExpirationAsNoExpiration() =>
+        Assert.Null(Cache.GetTtl(new DistributedCacheEntryOptions().SetSlidingExpiration(TimeSpan.MaxValue)));
+
+    [Fact]
+    public void CreateCacheEntryTreatsMaxValueSlidingAsNoExpiration()
+    {
+        var entry = Cache.CreateCacheEntry(
+            new byte[1],
+            new DistributedCacheEntryOptions().SetSlidingExpiration(TimeSpan.MaxValue));
+
+        Assert.Null(entry.SlidingExpirationTicks);
+        Assert.Null(entry.AbsoluteExpiration);
+    }
+
+    [Fact]
+    public void CreateCacheEntryTreatsMaxValueAbsoluteAsNoExpiration()
+    {
+        var entry = Cache.CreateCacheEntry(
+            new byte[1],
+            new DistributedCacheEntryOptions().SetAbsoluteExpiration(DateTimeOffset.MaxValue));
+
+        Assert.Null(entry.AbsoluteExpiration);
+        Assert.Null(entry.SlidingExpirationTicks);
+    }
 }