BuildingBlocks.Idempotency 1.0.1

BuildingBlocks.Idempotency

ASP.NET Core Idempotency-Key for MVC and Minimal API. Host-owned IDistributedCache, optional Redis lock, opt-in request fingerprint, RFC 9457 ProblemDetails on conflicts, optional ActivitySource.

Requires .NET 8, .NET 9, or .NET 10.

What's new in 1.0.1

• Package icon for NuGet listing parity with other BuildingBlocks
• System.Text.Json for the cache envelope and MVC ObjectResult body capture (dropped Newtonsoft.Json). Minimal API already used STJ. No public API change from 1.0.0.

Install

dotnet add package BuildingBlocks.Idempotency

Features

• Shared gate for MVC ([Idempotent]) and Minimal API (WithIdempotency)
• Cache HTTP 2xx envelopes (status, content-type, body) and replay them
• Processing lease (ProcessingTtl) with abandoned recovery; Completed window (EntryTtl)
• Per-endpoint TTL overrides (ProcessingTtlSeconds / EntryTtlSeconds)
• Optional Redis SET NX lock around GetOrCreate (.UseRedisLock())
• Opt-in fingerprint: SHA-256(method + "\n" + path + "\n" + body)
• Key validation (ULID by default, MaxKeyLength, reject empty / control characters)
• DuplicateCompletedBehavior: Replay (default) or Conflict
• ProblemDetails errors with stable type URIs
• Optional telemetry (.UseTelemetry()); host AddSource("BuildingBlocks.Idempotency")
• System.Text.Json only (cache + MVC + Minimal API)

Quick start

// Host must already register IDistributedCache.
// For UseLock, also register IConnectionMultiplexer.
builder.Services.AddBuildingBlocksIdempotency(o =>
{
    o.ProcessingTtl = TimeSpan.FromMinutes(2); // keep longer than worst-case handler
    // o.EnableRequestFingerprint = true;
    // o.UserIdFallback = "anonymous"; // when NameIdentifier is missing
})
.UseRedisLock()      // optional
.UseTelemetry();     // optional

// MVC
[HttpPost]
[Idempotent(useLock: true)]
public async Task<ActionResult<OrderResponse>> Create([FromBody] CreateOrder request) { ... }

// Minimal API
app.MapPost("/orders", CreateAsync).WithIdempotency(useLock: true);

Aliases still work: AddRedisIdempotencyLock(), AddIdempotencyTelemetry().

Behavior

Cache key: {KeyPrefix}_{optionalScopeClaims}_{userId}_{key} (default prefix Idempotency).

Replay header name is configurable (CachedResponseHeader, default X-Idempotent-Response).

ProblemDetails

Conflicts and validation failures return application/problem+json. Stable type values:

Base: https://buildingblocks.dev/errors/idempotency/.

TTL

After ProcessingTtl expires, another request with the same key may run while a slow first request is still in flight. The optional lock covers GetOrCreate only.

Fingerprint

Off by default (same key replays even if the body changes). When EnableRequestFingerprint is true, the hash includes HTTP method, path, and raw body bytes (not canonical JSON).

Options (common)

Telemetry

.UseTelemetry() registers ActivitySource BuildingBlocks.Idempotency. Outcomes: executed, replayed, processing_conflict, fingerprint_conflict, duplicate_conflict, bad_key, unauthorized, lock_failure. Cache keys are not tagged unless IncludeCacheKeyInTelemetry is true.

This package does not depend on BuildingBlocks.Telemetry — add AddSource("BuildingBlocks.Idempotency") on the host.

Host requirements

• IDistributedCache (required)
• IConnectionMultiplexer when using .UseRedisLock() / UseLock: true
• No references to BuildingBlocks.Mcp, Mediator, Telemetry, or EventBus

Not this package

MCP tool write idempotency (UseMemoryIdempotency / IMcpIdempotencyStore) is part of BuildingBlocks.Mcp.