docs(idempotency): rewrite for the corrected replay behaviour (#1333) - #240
Open
marcelo-maciel wants to merge 5 commits into
Open
docs(idempotency): rewrite for the corrected replay behaviour (#1333)#240marcelo-maciel wants to merge 5 commits into
marcelo-maciel wants to merge 5 commits into
Conversation
Tracks fullstackhero/dotnet-starter-kit#1333. The concept page described a HybridCache-backed store, a key scoped to the tenant only, and a replay of "status + body" - none of which is what the filter does now. Rewrites the flow section around the same-store/same-key symmetry, what is captured (wire body, real status, allow-listed Location/ETag), the 2xx-only rule, the store happening before the client write on an uncancellable token, and the in-flight reservation with its 409 and the new ReservationTtl option. Replaces the "the cache key does NOT include the route" gotcha, which is no longer true, with the body and anonymous-tenant caveats that are. Adds the changelog entry and the ReservationTtl mention on the Web building-block page.
… chosen The key follows the resolved tenant (a root operator's target included), the claim is only a fallback and an unresolved `tenant` header is never used. Both reservation branches expire on `ReservationTtl`, and releasing is a compare-and-delete so a request that failed open frees nothing.
…s new scopes The handler runs with the abort token detached, the probe fails open like the rest, a handler that writes the response itself is passed through, and the key covers the caller and the resolved route values. Adds the `Retry-After` on the 409, the startup validation of the options, and the ceilings worth knowing: buffered responses, and cross-instance dedup depending on the cache being on Valkey rather than on the reservation.
The page framed the shared "anon" caller bucket as a caveat to work around with fresh UUIDs. It is a defect: two self-registrations on one tenant with the same low-entropy key made the second replay the first registrant's 201, and no account was created. Documents the fix instead - the endpoint dropped .WithIdempotency(), and an integration test now fails the build if an anonymous endpoint carries it.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents the corrected idempotency filter from fullstackhero/dotnet-starter-kit#1333. Please merge this alongside that PR: the current page describes behaviour the code no longer has, and in a few places behaviour it never had.
Why the page needed a rewrite, not an edit
.WithIdempotency()probed the response cache throughIDistributedCacheon the raw key but stored throughHybridCache, which keys its backing entries under its own scheme. The probe never found what the store wrote, so replay silently never engaged, in production as much as in the test suite. Everything the page said about replay was therefore aspirational, and several details it promised were wrong once replay started working: the cached payload was the serializedOk<T>/Created<T>wrapper rather than the wire DTO, a201replayed as200, andLocation/ETagwere dropped.What changed on the page
tenantclaim, so a root operator acting on two tenants no longer shares one bucket), plus the caller, the HTTP method, the route pattern and the resolved route values.PUT /tickets/1andPUT /tickets/2are no longer one operation, and two users of one tenant reusing a low-entropy key no longer receive each other's response bodies.HttpContext.RequestAborteddetached, and the page states the trade-off plainly: on an idempotent endpoint a disconnect no longer aborts the handler. Without that, a client hanging up right after the side effect committed cancelled whatever the handler awaited next and the filter had nothing to store, so the retry re-executed the side effect, the exact duplicate the feature exists to absorb.409 ConflictwithRetry-After: 1, andIdempotencyOptions.ReservationTtl(new, default 1 minute) are documented, including why the lock TTL is deliberately decoupled from the 24 h response TTL..WithIdempotency()must not go on a streaming or large-file endpoint; there is no lease renewal, so a handler slower thanReservationTtlcan let a duplicate through; cross-instance deduplication depends on the cache being on Valkey/Redis, not on the reservation. Previously the page implied none of these.IdempotencyOptionsis validated on start. A zeroDefaultTtlused to throw inside the best-effort store, log a warning and carry on, so nothing was ever cached.building-blocks/web.mdxgets the one-line summary corrected to match, andchangelog/index.mdxgains the entry for the fix.Verification
npm run build, exit 0, 92 pages indexed, no broken internal links.