DKNet.AspCore.Idempotency 10.1.17

DKNet.AspCore.Idempotency

An ASP.NET Core minimal-API endpoint filter that makes mutating endpoints safe to retry: requests carrying the same idempotency key are processed once, with duplicates either rejected with 409 Conflict or replayed from cache.

Features

• Endpoint filter (RequiredIdempotentKey()) that enforces an idempotency key on any minimal API route
• Group-level declaration — the same RequiredIdempotentKey() on a RouteGroupBuilder covers every POST endpoint in the group (verb set overridable), nested groups and later-added endpoints included
• Composite key validation (presence, length, format) with automatic 400 Bad Request responses
• Two duplicate-request strategies: 409 Conflict (default) or transparent cached-response replay
• Caller scope isolation (authenticated user, HMAC'd Authorization header, or client IP) so the same key from different callers never collides — or supply your own resolver
• Pluggable storage via IIdempotencyKeyStore, with a built-in IDistributedCache-backed store out of the box
• Configurable which HTTP status codes get cached, cache key prefix, and result expiration

Installation

dotnet add package DKNet.AspCore.Idempotency

Quick Start

using DKNet.AspCore.Idempotency;

var builder = WebApplication.CreateBuilder(args);

// This package supplies the endpoint filter and options; it does not ship a usable store.
// Reference one of the store packages and call its registration extension:
//   DKNet.AspCore.Idempotency.MsSqlStore   -> AddIdempotencyWithMsSqlStore(connectionString)
//   DKNet.AspCore.Idempotency.NpgsqlStore  -> AddIdempotencyWithNpgsqlStore(connectionString)
//   DKNet.AspCore.Idempotency.RedisStore   -> AddIdempotencyWithRedisStore(connectionString)
// All three reserve the key atomically. To use a store of your own, implement
// IIdempotencyKeyStore and register it with AddIdempotentKey<TStore>().
builder.Services.AddIdempotencyWithMsSqlStore(
    builder.Configuration.GetConnectionString("Idempotency")!);

var app = builder.Build();

app.MapPost("/orders", CreateOrder)
    .RequiredIdempotentKey();

await app.RunAsync();

Clients call POST /orders with an X-Idempotency-Key header; a retried request with the same key never re-executes CreateOrder.

For multi-instance production traffic, swap the built-in store for an atomic one from the ecosystem — DKNet.AspCore.Idempotency.MsSqlStore, DKNet.AspCore.Idempotency.NpgsqlStore, or DKNet.AspCore.Idempotency.RedisStore — each of which ships its own AddIdempotencyWithXxxStore(...) registration. AddIdempotentKey<TStore>(...) is for a public IIdempotencyKeyStore you write yourself; every shipped store type is internal.

Group-level declaration

RequiredIdempotentKey() also extends RouteGroupBuilder, so a single declaration on a group protects every matching endpoint in it — including endpoints added to that group later, and endpoints of groups nested under it:

var orders = app.MapGroup("/api/orders").RequiredIdempotentKey();                 // POST endpoints only
var admin  = app.MapGroup("/api/admin").RequiredIdempotentKey("POST", "DELETE");  // explicit verb set

orders.MapPost("/", CreateOrder);            // protected — no per-endpoint call needed
orders.MapGet("/{id}", GetOrder);            // untouched: no header required, no duplicate lookup
orders.MapGroup("/{id}/lines")               // nested group inherits the same verb selection
      .MapPost("/", AddOrderLine);           // protected

The default covered set is POST only — PUT and DELETE are already idempotent by HTTP semantics, so they are opt-in through the verb arguments. Verbs are matched case-insensitively against each endpoint's routed verb, and coverage is decided once at application start: nothing the caller sends (an X-HTTP-Method-Override header included) can move an endpoint into or out of coverage.

An endpoint whose verb falls outside the set is left completely alone — no header requirement, no rejection, no duplicate lookup, nothing retained — so reads keep working for clients that never send a key. A covered endpoint behaves exactly like an individually declared one: same header name, key validation, duplicate handling and retention, all still driven by IdempotencyOptions. The per-endpoint overload is unchanged, and an endpoint covered both ways is still protected exactly once.

Two limits worth knowing:

• An endpoint registered without a verb constraint (app.Map(...), which also serves GET) has no routed verb to match and is not covered. Declare explicit verbs (MapPost, MapPut, ...) on endpoints you want protected.
• A verb set that omits a state-changing endpoint leaves that endpoint unprotected. That is an explicit choice — a group protects only the verbs you name.

Customisation reference

All configuration lives on IdempotencyOptions, passed as the Action<IdempotencyOptions> on AddIdempotentKey<TStore>() (and on every store package's AddIdempotencyWithXxxStore(...)). Values are validated eagerly at registration — an empty header key or cache prefix, a non-positive expiration, a status-code window outside 100–599 or with min above max, a null JsonSerializerOptions, a MaxIdempotencyKeyLength below 1, an empty key pattern, or a whitespace ScopeHmacSecret each throw ArgumentException immediately rather than failing at request time.

The default caller-scope chain, used when KeyScopeResolver is null: authenticated user's ClaimTypes.NameIdentifier → user:{id}; else HMAC of the Authorization header when ScopeHmacSecret is set → auth:{hex}; else the remote IP when IncludeClientIpInScope is true → ip:{address}; else the empty string.

Extension point — IIdempotencyKeyStore

public interface IIdempotencyKeyStore
{
    ValueTask<(bool processed, CachedResponse? response)> IsKeyProcessedAsync(IdempotentKeyInfo keyInfo);
    ValueTask MarkKeyAsProcessedAsync(IdempotentKeyInfo keyInfo, CachedResponse cachedResponse);
}

IsKeyProcessedAsync must check and reserve atomically: returning (false, null) has to have already recorded the key as in flight, so no concurrent caller for the same key can also observe (false, null). The reservation must be distinguishable from a completed response (every shipped store uses HTTP 102 as the sentinel) and must expire after InFlightReservationTimeout so a crashed handler cannot block the key forever. Get that wrong and duplicate requests both run the handler, which is the one thing this package exists to prevent.

Migration — namespace changes in this release

Root types were grouped into concern folders; the namespace of each moved type now ends with its folder name. This is an import-only source break: no type was renamed, removed, resignatured, or had its behaviour changed — update the using line and you're done.

IdempotencySetup (registration point) and IdempotencyOptions/IdempotentConflictHandling (the configuration surface) stay at DKNet.AspCore.Idempotency.

Documentation

Full feature guide, configuration reference, and store comparison: https://github.com/baoduy/DKNet/blob/main/docs/AspNetCore/DKNet.AspCore.Idempotency.md

License

MIT — see LICENSE.

About

Developed by Steven Hoang.