Idempo 0.1.0

Idempo

ASP.NET Core middleware for HTTP Idempotency-Key support — Stripe-style. Prevents duplicate processing of POST/PATCH requests when clients retry after network failures.

Packages

Quick start — Controllers

// Program.cs
builder.Services.AddIdempotency(options =>
{
    options.RequireIdempotencyKey = false; // global default
    options.Expiration = TimeSpan.FromHours(24);
})
.AddIdempotencyInMemoryStore(); // single-node; use .AddIdempotencyRedisStore() in production

// ...

app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseIdempotency(); // after UseRouting, before endpoints
app.MapControllers();

// PaymentsController.cs
[HttpPost]
[Idempotent(Required = true)] // 400 if Idempotency-Key header is absent
public async Task<IActionResult> CreatePayment([FromBody] CreatePaymentRequest request)
{
    // ...
}

Clients include the header on every request:

POST /payments
Idempotency-Key: 7f3d4e2a-1b9c-4f5e-8a7b-3c2d1e0f9a8b
Content-Type: application/json

{"amount": 100, "currency": "USD"}

Retries with the same key and body receive the stored response. A different body returns 422 Unprocessable Entity.

Quick start — Minimal API

app.MapPost("/orders", CreateOrder)
   .WithIdempotency(required: true);

Using Redis (distributed / multi-node)

builder.Services.AddIdempotency()
    .AddIdempotencyRedisStore(options =>
    {
        options.Configuration = "redis-host:6379";
        options.KeyPrefix = "myapp:idempo:";
    });

// Or supply an existing IConnectionMultiplexer:
builder.Services.AddIdempotency()
    .AddIdempotencyRedisStore(options =>
        options.ConnectionMultiplexer = existingMultiplexer);

How it works

1. Request arrives for a configured method (POST/PATCH by default).
2. Middleware reads the Idempotency-Key header.
3. Computes StorageKey = hex(SHA-256(method + ":" + routePath + ":" + tenant? + ":" + clientKey)).
4. TryAcquire against the store (atomic write-if-absent).
   • Acquired — wraps the response stream, calls the handler, stores the response on success.
   • Existing (InProgress) — polls until the original request completes (up to InProgressTimeout), then replays.
   • Existing (Completed) — validates body hash, replays stored response immediately.
5. Adds Idempo-Result: executing or Idempo-Result: replayed header to every idempotency-handled response.

Cacheable vs non-cacheable status codes

Only 2xx, 400, 404, 409, 410, and 422 responses are stored by default (configured via CacheableStatusCodes). 5xx responses are never stored — the key is released so the next retry re-executes the handler.

FailOpen vs FailClosed

Use FailClosed for payment and financial flows where processing a charge twice is unacceptable:

builder.Services.AddIdempotency(options =>
{
    options.StoreFailurePolicy = StoreFailureBehavior.FailClosed;
});

In-memory store warning

The built-in InMemoryIdempotencyStore stores all state in the current process's memory.

• Single-node deployments only. In a load-balanced or multi-instance deployment, two requests with the same Idempotency-Key can land on different nodes and both execute.
• Not persistent. State is lost on restart; duplicate protection does not survive a process recycle.

For production multi-instance deployments, use Idempo.Redis.

Options reference

builder.Services.AddIdempotency(options =>
{
    options.HeaderName = "Idempotency-Key";        // default
    options.Methods = new HashSet<string> { "POST", "PATCH" }; // default
    options.Expiration = TimeSpan.FromHours(24);   // default
    options.RequireIdempotencyKey = false;          // default
    options.ValidateBodyHash = true;               // default; 422 on body mismatch
    options.MaxBodyHashSizeBytes = 262_144;        // 256 KiB default
    options.LargeBodyPolicy = LargeBodyBehavior.SkipHash; // or Reject
    options.CacheableStatusCodes = new HashSet<int> { 200, 201, 202, 204, 400, 404, 409, 410, 422 };
    options.StoreFailurePolicy = StoreFailureBehavior.FailOpen; // or FailClosed
    options.InProgressTimeout = TimeSpan.FromSeconds(10);       // zombie protection
    options.InProgressPollInterval = TimeSpan.FromMilliseconds(200);
    options.TenantKeyExtractor = ctx => ctx.User.FindFirstValue("tid"); // optional: scope per tenant
});

Observability

• Logging: structured via ILogger<IdempotencyMiddleware>. The raw Idempotency-Key header value is never logged — only the StorageKey hash.
• Distributed tracing: ActivitySource named "Idempo" with spans idempotency.check, idempotency.acquire, idempotency.replay and tag idempo.result.

License

MIT