#40 Inject TimeProvider

[matthewdevenny]

Closes #40

Problem

NatsCache used DateTimeOffset.Now throughout its expiration logic (TTL computation, entry creation, absolute-expiration checks, sliding-window updates). That relies on the local wall clock and makes expiration behavior impossible to unit-test without real delays.

Change

Route every clock read through an injected TimeProvider (default TimeProvider.System), resolved from DI. This is the .NET 8+ idiom and enables deterministic, instant expiration unit tests via FakeTimeProvider.

Library (src/NatsDistributedCache)

• NatsCache.cs: replaced all DateTimeOffset.Now usages with TimeProvider.GetUtcNow(). The clock is exposed as an internal init-only TimeProvider property (default TimeProvider.System) rather than a constructor parameter, so the public constructor is unchanged and there is no ABI break. The absolute-expiration read check was extracted into IsAbsolutelyExpired, and the shared relative-vs-absolute resolution into ResolveAbsoluteExpiration.
• NatsDistributedCacheExtensions.cs: the DI registration resolves an optional TimeProvider via sp.GetService<TimeProvider>() and sets the property, falling back to TimeProvider.System when none is registered.
• README.md: documents overriding the clock by registering a TimeProvider in DI.

Switching from local-time DateTimeOffset.Now to UTC GetUtcNow() is behavior-preserving: every use is either an instant comparison or a duration, and DateTimeOffset operations are offset-aware. The one deliberate behavior change is that IsAbsolutelyExpired uses an inclusive >= boundary, matching GetTtl (which already treats an absolute expiration at "now" as elapsed) and BCL MemoryCache.

Tests (test/UnitTests)

• Added the Microsoft.Extensions.TimeProvider.Testing package and regenerated the RID lock files.
• TestBase injects a FakeTimeProvider (exposed as a property) via the init property and exposes the concrete NatsCache.
• The existing absolute-expiration validation tests now drive time from TimeProvider.GetUtcNow().
• New TimeProviderExpirationUnitTests: instant, no-delay tests for TTL computation, CreateCacheEntry, and absolute expiration flipping with FakeTimeProvider.Advance (including the exact-boundary case).
• New DI tests proving a registered TimeProvider is used, and that resolution falls back to TimeProvider.System (verified against the real UTC clock) when none is registered.

The integration time-expiration tests (TimeExpirationTests/TimeExpirationAsyncTests) are intentionally left with real delays — they exercise NATS's server-side TTL, whose clock a FakeTimeProvider can't drive.

Acceptance criteria

• ✅ No DateTimeOffset.Now remains in the library.
• ✅ Time-expiration unit tests drive time with FakeTimeProvider (no real delays).
• ✅ DI wiring resolves an optional TimeProvider, defaulting to TimeProvider.System.

Note on API surface

Injecting via the internal init property (instead of a constructor parameter) keeps the change purely additive — consumers compiled against 0.3.0 keep working without recompiling. The idiomatic way to override the clock is to register a TimeProvider in DI; consumers resolve IDistributedCache, so no public surface on the concrete NatsCache type is required.

Verification

• dotnet build -p TreatWarningsAsErrors=true → 0 warnings (net8.0 + net10.0); the public constructor is byte-identical to main.
• dotnet test test/UnitTests → 46/46 passing on both frameworks.
• NuGet lock files regenerated and confirmed in sync (CI drift check passes).

🤖 Generated with Claude Code

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

[mtmk]

LGTM