refactor(cache)!: move the interface forwarders to extension methods

[cosmin-staicu]

Summary

Stacked on #144 — base branch is feat/conditional-add-tryaddasync, so review that one first and this diff shows only the refactor on top.

Six partials across the cache interfaces held 101 default interface methods that were pure forwarders — no behavior of their own, each delegating to a real member. They are now extension methods, which is where such forwarders belong: the interfaces shrink to the operations an implementation actually has to implement, and an implementor writes one member per operation instead of one plus an inherited forwarder they could accidentally override.

• 42 pre-CachePolicy convenience overloads (ICache.Compat.cs, IHashCache.Compat.cs, ISetCache.Compat.cs), each forwarding to the policy-bearing member with policy: null.
• 59 blocking sync forwarders (ICacheOfT.Sync.cs, IHashCacheOfT.Sync.cs, ISetCacheOfT.Sync.cs), each blocking on the async member via .AsTask().GetAwaiter().GetResult().

No call site in the repo needed an edit.

Changes

• CacheExtensions, HashCacheExtensions (UiPath.Caching.Abstractions) and SetCacheExtensions (UiPath.Caching.Queue) — the 42 forwarders, same UiPath.Caching namespace as the interfaces so no new using is required. [ExcludeFromCodeCoverage] on the class, matching what the Compat files carried per-member.
• ICache.Compat.cs, IHashCache.Compat.cs, ISetCache.Compat.cs — deleted. partial comes off ICache / IHashCache / ISetCache, which nothing else extends now. The ICache<T> / IHashCache<T> / ISetCache<T> partials stay — their .Sync.cs halves are unaffected.
• CachePolicy? policy is now required on every member that takes one, along with the expiration / setOption parameters that precede it (C# forbids an optional parameter before a required one).
• Implementations — MultilayerCache, RedisCache, MultilayerHashCache, RedisHashCache, MultilayerSetCache, RedisSetCache, NullCache, NullHashCache, NullSetCache, plus the DictionaryCache test fake, all drop the defaults so behavior is identical through the interface or the concrete type. The policy ??= DefaultPolicy bodies are untouched: passing null still resolves the default exactly as before.
• CacheSyncExtensions, HashCacheSyncExtensions, SetCacheSyncExtensions — the 59 blocking forwarders off the three *.Sync.cs partials. Blocking behavior is unchanged; T becomes a method type parameter inferred from the receiver, so call sites are unchanged and the forwarders stay reachable through the concrete Cache<T> / HashCache<T> / SetCache<T> as well as the interfaces. partial comes off ICache<T> / IHashCache<T> / ISetCache<T>, leaving all three as pure async contracts. This half needed no signature change — the forwarders are distinct names (Get, not GetAsync) rather than overloads of what they forward to, so no instance member shadows them.
• Docs — interfaces.md code blocks track the new signatures, all four surfaces gain a note on their extension surface; the stale ICache.Compat.cs reference in the multi-key GetOrAddAsync note and the "every parameter after the generator is optional" line in batch-get-or-add.md are corrected.

Why policy had to become required

This is the part worth a second opinion. Making policy required is not cosmetic — it is what makes the extensions reachable at all.

Instance members always beat extension members in overload resolution. While the interfaces still declared policy = null, an applicable interface overload existed for every short call, so cache.GetAsync<T>(key, token) kept binding to the interface and the extension methods were unreachable dead code. I built that intermediate state and it compiled clean, which is exactly the problem — nothing tells you the extensions are never called.

With policy required, no interface overload is applicable to the short forms and there is exactly one way to spell each call. Two follow-on benefits: an implementation no longer gets to declare its own default for "no policy", and the interface stops carrying two spellings of the same operation.

What no longer compiles is an interface call that leaned on the defaults to skip the policy slot positionally. Named arguments (policy:, token:) and the short forms are unaffected.

Compatibility

Source-compatible for callers; binary-breaking for external implementors of any of these interfaces, which is what the 183 entries leaving PublicAPI.Shipped.txt record (142 in Abstractions, 41 in Queue). Three **BREAKING:** CHANGELOG entries under Unreleased.

One call shape does not compile, before or after: Set(pairs) with a single argument, where the KeyValuePair[] overloads carrying TimeSpan? expiration = null and DateTimeOffset? expiration = null tie with the token-only overload. I verified that ambiguity is pre-existing by reproducing the old shape as default interface methods — it fails identically there. No call site uses it, and the async twin SetAsync(pairs) on ICache<T> has the same wart, so I left both alone rather than widen the break.

Test plan

• dotnet test — 1503 passed / 0 failed, net8.0 and net10.0, Debug and Release (rebased onto 63794f7).
• Debug and Release builds clean; the only warnings are the 8 pre-existing CS0618 StackExchange.Redis obsoletions. Every build error at any point in this refactor was RS0016/RS0017 API-baseline bookkeeping — never a CS error, which is the evidence that call sites are genuinely unchanged.
• Compile-probed all 82 affected call shapes against the new surface — 23 short policy-free shapes (11 cache, 12 set) and 59 sync shapes, the latter including calls through the concrete Cache<T> and SetCache<T> — to confirm they bind to the extensions rather than silently resolving elsewhere. Probes removed afterwards.
• Forced GenerateDocumentationFile=true to check the <inheritdoc cref> targets in all six new files — zero CS1574/CS1580. Doc generation is off in this repo, so a bad cref would otherwise fail silently.
• PublicAPI.Shipped.txt / PublicAPI.Unshipped.txt updated in both packages.
• CHANGELOG.md updated.

Also in this PR: two test de-flakes (first commit)

Running the Release suite repeatedly surfaced two pre-existing non-determinisms on net10.0 — 2 failures in 5 runs, a different test each time. Both are unrelated to the refactor and are fixed in 7b72bd9, separated so they can be reviewed or cherry-picked on their own:

• ResiliencePipelineFactoryTest.Pipeline_works_as_expected checked that the breaker closes within a fixed 250ms + 4x100ms budget against a DurationOfBreak of 500ms — 150ms of slack, measured from wherever the preceding exception loop happened to finish. Under parallel load the breaker is still open on the fourth probe. Now polls at 20ms under a 30s ceiling, the shape ConnectionStateMonitorTests.WaitUntilAsync already uses.
• The four tests asserting ThrowAsync<TimeoutException> passed the ambient xunit token as the caller token, but FactoryTimeout.RunAsync only converts cancellation to TimeoutException while that token is uncancelled (when (linkedCts.IsCancellationRequested && !token.IsCancellationRequested)). If the runner cancels it, a raw TaskCanceledException escapes. Each now uses a CancellationTokenSource it owns, matching GetOrAdd_FactoryTimeout_does_not_swallow_caller_cancellation next door. All four are fixed, not just the one observed failing.

Verified with three consecutive full Release runs, green on both TFMs, two of them at 3m35s–3m59s against a 1m25s baseline — i.e. heavier load than the runs that originally flaked.

One caveat stated plainly: I never captured the original assertion message for the Redis FactoryTimeout failure, so that diagnosis comes from reading the catch filter rather than from the failure text. The filter is a genuine non-determinism either way and the change is a strict improvement, but I would rather flag that than overstate it.

An unresolved third flake (f198c1f)

A third intermittent net10.0 failure showed up while working on this — RedisStreamSubjectWriterTests.Unknown_command_quarantine_is_lifted_when_the_connection_reconnects, ~21s against 352ms in isolation, recovered false after its 10s budget. It has no contact with anything this PR changes.

f198c1f closes a real data race found while investigating it: the test flips a captured fail bool from the test thread while the writer's fetch loop reads it from its own, with no barrier — and the neighbouring test in the same file already reads its attempts counter through Interlocked/Volatile, so this flag was the outlier.

That did not fix the flake, and the commit message says so. The test was still seen failing after the change. Two hypotheses are ruled out: the wake is not lost (the retry gate is a SemaphoreSlim, so a Release preceding WaitAsync is preserved — and ReleaseRetryGate deliberately swallows SemaphoreFullException for exactly that case), and it is not this data race. The failure then declined to reproduce across five subsequent loaded runs, so I could not capture the assertion message and the root cause is still open. The race fix stands on its own merits; the flake needs a separate look.

Linked issues

Fixes #

Contributor declaration

• I signed off my commits per the DCO (git commit -s).
• I am contributing on behalf of my employer, or in the course of employment / using employer resources. _{(If checked, your employer may hold IP rights in this work, which can require a signed CLA — a maintainer will follow up. See CONTRIBUTING.md.)}

Note

Both commits carry a Signed-off-by trailer. The employer box is left for the author to confirm.

🤖 Generated with Claude Code

https://claude.ai/code/session_015RLSnsYiZsqeaHHYYybXW1

[github-actions]

🔎 Maintainer heads-up: automated triage flagged this PR as potentially material, so it may need a signed CLA in addition to the DCO sign-off.

Strong signals

• adds public API surface (PublicAPI.Unshipped.txt in src/UiPath.Caching.Abstractions, src/UiPath.Caching.Queue, src/UiPath.Caching)
• changes shipped public API — possible removal/breaking change (PublicAPI.Shipped.txt in src/UiPath.Caching.Abstractions, src/UiPath.Caching.Queue)

Other signals

• large production change (+618 lines under src/)

This is advisory only — the bot does not decide. Please judge against the CLA criteria (material, product-critical, patent-sensitive, corporate contributor, broad commercial use). Note that thresholds can be gamed by splitting PRs, so use your judgement.

• If a CLA is needed → add the cla-required label (a contributor comment with signing steps is posted automatically).
• If it is not needed → replace needs-cla-review with cla-not-required so later pushes don't re-flag it.