feat(cache): add TryAddAsync conditional add (Redis When.NotExists)

[CalinMPopa]

Summary

Adds TryAddAsync — a create-if-absent member on ICache / ICache<T> that maps to StackExchange.Redis When.NotExists (SET key value EX … NX). Until now the library had no conditional-write path at all: every Redis write hardcoded When.Always, and the only NX primitive was IDistributedLock, which is a lease rather than a value store. This gives callers at-most-once semantics keyed by something — idempotency keys, dedup markers whose TTL is the dedup window, electing which replica runs a job.

Changes

• ICache.TryAddAsync<T> / ICache<T>.TryAddAsync (+ blocking ICache<T>.TryAdd) — three overloads each (policy / TimeSpan? / DateTimeOffset?), mirroring the existing SetAsync shape. Added as default interface methods so existing implementations keep compiling, per the convention set for the 1.3.0 ICache additions.
• RedisCache — one SET … NX command, no probe, TTL applied by the same write so a won key is never briefly immortal between the write and a follow-up EXPIRE.
• MultilayerCache — the L2 arbitrates; L1 population and the invalidation broadcast happen after the win, best-effort. With the L2 disconnected the call returns false rather than granting a local-only claim every node would also be granted. The memory-only provider (NullCache as L2) has no L2 to arbitrate, so the local tier does, serialized by the local lock — which a conditional add takes regardless of Lock.LocalLockEnabled, because here it is the guarantee; a caller that cannot acquire it within Lock.LocalLockTimeout is told it lost.
• Cache<T>, NullCache — implementations; NullCache returns false. It is the one member where that type does not degrade to "caching is off, carry on": it cannot complete the write, which is exactly what a fail-closed false means, and true there would hand every caller a claim of exclusive ownership. It is also reached by accident, being what ICacheFactory.CreateCache resolves to when the requested provider is absent or has Enabled=false. NullSetCache.AddAsync in UiPath.Caching.Queue — SADD, the same question — already answered false.
• MultilayerCacheBase.AcquireLocalLockAsync — private protected helper resolving local-lock enablement/timeout the same way RunUnderLocksAsync does.
• Docs — new recipe docs/recipes/conditional-add.md; interfaces.md gains the contract plus a per-provider table of who arbitrates; concepts.md places it next to the two lock abstractions.
• Drive-by fix — interfaces.md described the IHashCache<T>.SetAsync(…, HashCacheEntryOptions, …) overload as offering "conditional set, individual field TTL". It offers neither: HashCacheSetOption selects write scope (HashReplace merges fields, KeyReplace drops the key first), and there is no per-field TTL. Corrected, since it pointed readers at the wrong place for NX.

Contract decisions worth reviewing

• false is fail-closed and deliberately ambiguous — the key already existed, or the write could not be completed (disconnected, threw, or a null/default the cache cannot represent). A caller treating true as "I own this key" is never wrongly told it won. Same conflation IDistributedLock.TryAcquireAsync already documents.
• It never deletes. Where SetAsync removes the key when handed a null with CacheNullValues off, TryAddAsync reports false and leaves it untouched.
• A win is never downgraded. If the L2 add succeeds but the broadcast or L1 write fails, the call still returns true — reporting a loss would strand the entry with no owner until its TTL. Those failures are logged.
• The default interface body throws NotSupportedException rather than emulating the operation with a probe followed by a write, which would not be atomic and would silently void the only guarantee the method makes. All in-box implementations override it.
• No multi-key overload — Redis has no atomic multi-key NX, and all-or-nothing vs. per-key would be a guess. No hash-surface member — HSETNX is per-field and a different shape. The set/queue surface already reports add-vs-already-present from AddAsync.

Test plan

• Unit tests added/updated — 36 new cases across four files: RedisCacheTryAddTests (single NX command, never When.Always/When.Exists, lost race, fail-closed on disconnect and on throw, expiration in the same command, cached-null sentinel, never deletes, telemetry scope, cancellation), MultilayerCacheTryAddTests (L2 arbitrates, never probes L1 to decide, no broadcast on a loss, win survives broadcast failure, fails closed when disconnected), InMemoryCacheTryAddTests (a real MultilayerCache over NullCache with a live AsyncKeyedLocalLock — 32 concurrent callers yield exactly one winner), CacheOfTTryAddTests (key strategy and policy snapshot forwarding, blocking facade).
• Integration tests pass locally (dotnet test) — 1327 passed / 0 failed on both net8.0 and net10.0.
• CHANGELOG.md updated
• PublicAPI.Unshipped.txt updated (15 entries)

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.)}

Important

The commit on this branch has no Signed-off-by trailer, so the DCO check will fail. A sign-off is a certification made by the contributor, so it was left for the author rather than added automatically. To fix: git commit -s --amend --no-edit && git push --force-with-lease. The two declaration boxes above are likewise left unchecked for the author to confirm.

🤖 Generated with Claude Code

---

Follow-up commit: fix(cache): close the fail-open paths in TryAddAsync

A review pass found several paths where a caller could be told true without owning the key. What changed on top of the original commit:

• The memory-only tier no longer runs unserialized. AcquireLocalLockAsync returned null both when Lock.LocalLockEnabled was off and when the acquire timed out, and the probe-then-write proceeded anyway — measured 11 of 32 concurrent callers winning with the lock disabled, 20 of 32 with a contended acquire. The lock is now always taken for a conditional add, and a caller that cannot get it is told it lost.
• NullCache.TryAddAsync returns false (see above).
• A non-positive expiration reports false on both tiers. IMemoryCache evicts such an entry on arrival, so the memory tier reported success while retaining nothing and the next caller won too, while Redis answered false for the same call.
• A local win publishes the invalidation broadcast, as SetAsync does.
• An inner cache's NotSupportedException surfaces instead of becoming a permanent false indistinguishable from contention.
• In-flight cancellation propagates on both tiers instead of being reported as false.
• The L2 gate no longer uses GetInnerCacheDisconnected, whose state aggregates the broadcast transport: a dead topic was stopping a healthy Redis from arbitrating. The L2 is asked and fails closed on its own.
• ICache.Compat.cs gains the three token-positional TryAddAsync forwarders — the only public API this follow-up adds.
• The docs no longer offer IConnectionState as a way to tell an outage from a lost race, because it is not one: a serialization or command failure returns false with the connection snapshot still healthy. The ambiguity is documented as unrecoverable, and the recipe's worked example is a daily digest rather than a payment capture — a claim marker records that someone started, never that anyone finished.

The SET … NX write stays on the shared Write resilience pipeline. Retrying it is harmless: an attempt whose reply was lost is refused by the key it just wrote and reports the same false the un-retried exception would have, while an attempt that never reached Redis is recovered as the true it should have been. (SPOP is the opposite, which is why RedisSetCacheOptions.ResilienceKeyName exists.)

[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)

Other signals

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

Context

• external contributor (CONTRIBUTOR) with a substantial change (+362 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.

[Copilot]

🟡 Changes recommended

Multilayer cancellation and connection handling are incorrect, and the failure-disambiguation guidance is unsafe.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds atomic conditional cache insertion via TryAddAsync, enabling create-if-absent workflows across Redis, multilayer, and typed cache APIs.

Changes:

• Adds typed, untyped, synchronous, and compatibility APIs.
• Implements Redis NX and multilayer/local arbitration.
• Adds comprehensive tests, public API declarations, and documentation.

File summaries

File	Description
tests/UiPath.Caching.Tests/Redis/RedisCacheTryAddTests.cs	Tests Redis NX behavior.
tests/UiPath.Caching.Tests/NullCacheConditionalAddTests.cs	Tests fail-closed null cache behavior.
tests/UiPath.Caching.Tests/MultilayerCacheTryAddTests.cs	Tests multilayer and in-memory arbitration.
tests/UiPath.Caching.Tests/Fakes/DictionaryCache.cs	Adds conditional-add test fake.
tests/UiPath.Caching.Tests/CacheOfTTryAddTests.cs	Tests the typed facade.
src/UiPath.Caching/Redis/RedisCacheOptions.cs	Formatting-only change.
src/UiPath.Caching/Redis/RedisCache.cs	Implements Redis SET NX.
src/UiPath.Caching/PublicAPI.Unshipped.txt	Records connection-state API additions.
src/UiPath.Caching/MultilayerCacheBase.cs	Exposes connection state and local-lock helper.
src/UiPath.Caching/MultilayerCache.cs	Implements multilayer conditional add.
src/UiPath.Caching.Abstractions/PublicAPI.Unshipped.txt	Records new public APIs.
src/UiPath.Caching.Abstractions/Policies/ResiliencePipelineNames.cs	Formatting-only change.
src/UiPath.Caching.Abstractions/NullCache.cs	Adds fail-closed implementation.
src/UiPath.Caching.Abstractions/ICacheOfT.Sync.cs	Adds blocking facade methods.
src/UiPath.Caching.Abstractions/ICacheOfT.cs	Adds typed async contract.
src/UiPath.Caching.Abstractions/ICache.cs	Adds untyped async contract.
src/UiPath.Caching.Abstractions/ICache.Compat.cs	Adds positional-token forwarders.
src/UiPath.Caching.Abstractions/ConditionalAdd.cs	Provides unsupported-operation errors.
src/UiPath.Caching.Abstractions/CacheOptions.cs	Formatting-only change.
src/UiPath.Caching.Abstractions/CacheOfT.cs	Forwards typed conditional adds.
docs/reference/interfaces.md	Documents contracts and provider behavior.
docs/recipes/conditional-add.md	Adds a conditional-add recipe.
docs/index.md	Links the new recipe.
docs/concepts.md	Compares conditional add with locking.
CHANGELOG.md	Records the feature and semantics.

Review details

• Files reviewed: 25/25 changed files
• Comments generated: 7
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Several in-memory and fallback paths can still return a successful claim without preserving the required exclusion guarantee.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (3)

src/UiPath.Caching/MultilayerCache.cs:34

• Logging this fallback does not preserve the conditional-add guarantee. If Redis is absent and the factory's default provider is InMemory, InMemoryRedisCacheProvider receives this nested MultilayerCache; TryAddAsync then delegates to its process-local arbiter and returns true independently on every node. A nested multilayer tier must fail closed for conditional adds (or the configuration must be rejected), rather than only emitting a warning.

        if (innerCache is MultilayerCache)
        {
            LogInnerCacheArbitratesInProcessOnly(cacheName, innerCache.Name);

src/UiPath.Caching/MultilayerCache.cs:763

• The expiration was checked before awaiting the local lock, so a short TTL can expire while this caller waits. After acquiring the lock, MemorySet can then report success for an already-expired entry, returning true while retaining no claim and allowing the next caller to win. Recheck the absolute expiration inside the lock before probing or writing.

            if (_memoryCache.TryGetValue(options.CacheKey, out _))

src/UiPath.Caching/MultilayerCache.cs:777

• Only options.Expiration is validated, but the memory-only write is additionally capped by policy.LocalExpiration/LocalMaxExpiration. Those settings can be zero or negative; MemoryCacheSetter.Set still returns true after inserting an immediately expired entry, so this method can report a win without retaining the key. Resolve the local cap and fail closed when it is non-positive.

            return MemorySet(options, value, policy.LocalExpiration ?? _multiLayerCacheOptions.LocalMaxExpiration);

• Files reviewed: 24/24 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

Broadcast failure can suppress L1 population, and non-positive local expiration can allow multiple in-memory callers to report wins.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 24/24 changed files
• Comments generated: 2
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

In-memory arbitration is not atomic against concurrent unconditional writes, and normal broadcast failures are silently ignored.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

src/UiPath.Caching/MultilayerCache.cs:792

• This local arbitration path also ignores a false broadcast result. The built-in Redis topic implementations return false rather than throw when disconnected or when publishing fails, so a local winner can silently leave peer caches stale. Check the result and emit the existing stale-peer warning (without changing the successful add result).

                await _eventPublisher.CacheSetAsync(options).ConfigureAwait(false);

• Files reviewed: 24/24 changed files
• Comments generated: 2
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

The in-memory propagation path publishes an event that peer change tokens explicitly ignore, so stale copies are not invalidated as promised.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 24/24 changed files
• Comments generated: 3
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

Recognized local fallback tiers can still grant cross-process claims, and capacity rejection can produce false in-memory wins.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 24/24 changed files
• Comments generated: 4
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

Absolute-expiration retries can create entries after their requested deadline.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (3)

docs/recipes/conditional-add.md:1

• “Exactly once” overstates this fail-closed primitive: an unavailable store or a failed write means nobody claims the key, and a winner can crash before guarded work completes. The recipe itself correctly describes at-most-once semantics, so use that terminology in the title.

# Claim a key exactly once with `TryAddAsync`

src/UiPath.Caching/MultilayerCache.cs:675

• This call makes TryAddAsync honor CachePolicy.DistributedExpiration and JitterMaxDuration (and the win path later honors LocalExpiration), but those public CachePolicy property docs still enumerate only SetAsync/GetOrAddAsync/RefreshAsync. Update the XML comments in CachePolicy.cs to include TryAddAsync, otherwise generated API documentation incorrectly implies these settings do not affect conditional adds.

        policy ??= _defaultPolicy;
        return TryAddAsync(cacheKey, value, ResolveWriteDuration(policy), policy, token);

tests/UiPath.Caching.Tests/Redis/RedisCacheTryAddTests.cs:188

• This comment claims telemetry separates lost races from write failures, but both paths leave ret == false and are tracked under the same Misses.Redis.TryAddAsync.* metric. Reword it to describe the separately scoped overall win/non-win rate rather than a distinction the metric cannot provide.

        // Conditional adds must be attributable on their own, not folded into the SetAsync scope,
        // so a lost-race rate is observable separately from a write-failure rate.
        _telemetry.Metrics.Should().ContainSingle(m => m.Name == expectedMetric);

• Files reviewed: 24/24 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

🔵 Needs a closer look

The multilayer warning and false-outcome documentation remain inaccurate.

Review details

Suppressed comments (8)

CHANGELOG.md:60

• The later retry description permits false after this call’s first attempt actually created the key but lost its reply. The release note’s two-way explanation (“already existed” or “write could not be completed”) excludes that unknown-success outcome. State that false means no win was confirmed, not that creation definitely did not occur.

  replica runs a job. `false` deliberately conflates "the key already existed" with "the write could
  not be completed" (disconnected, threw, or a `null`/`default` value the cache cannot represent) —
  fail-closed, so a caller treating `true` as "I own this key" is never wrongly told it won; the same

docs/recipes/conditional-add.md:103

• This omits the retry outcome described below: the same call can successfully create the marker, lose the reply, and return false when its retry sees the marker. Saying “you did not create it” is therefore inaccurate. Document false as an unconfirmed win and include this unknown-success case.

- **`false` does not mean "the key existed".** It means "you did not create it" — the key already
  existed, *or* the write could not be completed (store disconnected, write threw, or the value was a
  `null`/`default` the cache cannot represent). This is fail-closed on purpose: nobody is ever wrongly

docs/recipes/conditional-add.md:48

• The lost-reply retry case makes this dichotomy incomplete: this invocation may have created the marker even though it receives false. Phrase the branch in terms of lacking a confirmed win so the example matches the documented retry behavior.

            // Someone else claimed it, or the write could not be completed. Both mean
            // "do not send" — which is the whole reason this side effect fits the
            // primitive: skipping is the safe failure, so the ambiguity costs nothing.

docs/recipes/conditional-add.md:1

• “Exactly once” overstates the contract: the same key can be claimed again after its TTL expires or after RemoveAsync, and the recipe itself describes the marker as expiring. Name this as an atomic claim while the key is absent/retained so readers do not mistake it for durable exactly-once delivery.

# Claim a key exactly once with `TryAddAsync`

docs/reference/interfaces.md:177

• The documented retry behavior at line 202 allows this call to write the key and still return false when the reply is lost and the retry is refused. Thus false does not prove “you did not create this key” or that the write was incomplete; it means the caller has no confirmed win. Include this unknown-success case in the public contract.

- **`false` is deliberately ambiguous.** It means "you did not create this key" — either it already existed, or the write could not be completed (backing store disconnected, write threw, or the value was a `null`/`default` that the cache has no way to represent). This is fail-closed by design: a caller treating `true` as "I own this key" is never wrongly told it won. The ambiguity is not recoverable: a serialization or command failure also returns `false`, with [`IConnectionState.IsConnected`](#iconnectionstate) still reporting healthy, and [`IDistributedLock.TryAcquireAsync`](#idistributedlock) conflates backend-unavailable with already-held in the same way. Design the `false` branch so that not proceeding is safe; if the two readings must be handled differently, the caller needs a primitive with a richer result than a `bool`.

src/UiPath.Caching.Abstractions/ICache.cs:56

• The Redis retry path can return false after this call actually created the key: the first SET NX may land, its reply may be lost, and the retry then sees the key and returns false. Therefore “you did not create it” / “write could not be completed” is not the full contract. Describe false as “no win was confirmed,” including an unknown-success outcome, so consumers do not infer that another caller created the key.

    /// <c>true</c> only if this call created the key. <c>false</c> means "you did not create it" —
    /// it existed, or the write could not be completed — and the two are deliberately conflated,
    /// fail-closed. Never deletes. Not a lock: no ownership token, no release. See

src/UiPath.Caching/MultilayerCache.cs:1310

• This warning describes the recognized NullCache/nested-multilayer configuration as non-excluding, but the new branches deliberately fail closed and never return a local win. That wording can make operators diagnose this as duplicate execution instead of a permanently skipped operation; state that TryAddAsync will return false.

    [LoggerMessage(Level = LogLevel.Warning, Message = "Cache {CacheName} resolved {InnerCacheName} as its distributed tier, which cannot arbitrate a conditional add across nodes, so TryAddAsync on {CacheName} does not exclude other nodes. Check that the intended distributed provider is registered and Enabled.")]

src/UiPath.Caching/Redis/RedisCache.cs:484

• This calls every false a non-win, but the next sentence documents a counterexample: an initial attempt may create the key, lose its reply, and then return false from the refused retry. Rephrase this as an unconfirmed outcome rather than claiming the write did not win.

    /// the write. <c>false</c> for every non-win — present, disconnected, threw, or unrepresentable.
    /// Safe on the retrying write pipeline: a retry after a lost reply is refused by the key it just
    /// wrote and reports the same <c>false</c> the exception would have.

• Files reviewed: 24/24 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
84.4% Coverage on New Code
0.2% Duplication on New Code

See analysis details on SonarQube Cloud