Idempotent.NET.Http 1.0.0

Idempotent.NET

Idempotent.NET gives ASP.NET Core APIs a Stripe-style idempotency layer: a client sends one Idempotency-Key, the first request executes, and safe retries receive the stored result instead of running the side effect again.

It is built for the messy part of real systems: mobile retries, load balancers, client timeouts, queue redelivery, double-clicks, and services that must not create the same payment, order, booking, or command twice.

Install

dotnet add package Idempotent.NET

Add a durable store when the app runs on more than one node:

dotnet add package Idempotent.NET.Stores.Redis
dotnet add package Idempotent.NET.Stores.Sql
dotnet add package Idempotent.NET.Stores.EntityFrameworkCore

Minimal API

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddIdempotency()
    .AddMemoryStore();

var app = builder.Build();

app.UseIdempotency();

app.MapPost("/orders", (CreateOrder request) =>
        Results.Created($"/orders/{request.Id}", request))
    .RequireIdempotency();

app.Run();

Send an Idempotency-Key header with unsafe requests:

POST /orders HTTP/1.1
Idempotency-Key: 7f36df0d-a8e8-4b9f-a673-cbc90f11b9f4
Content-Type: application/json

{ "sku": "coffee", "quantity": 2 }

The first request claims the key and stores the status code, headers, body, and fingerprint. A retry with the same key and same request fingerprint gets the cached response. A retry with the same key but different request content is rejected as a conflict.

Controllers

[ApiController]
[Route("orders")]
public sealed class OrdersController : ControllerBase
{
    [HttpPost]
    [Idempotent]
    public IActionResult Create(CreateOrder request) =>
        Created($"/orders/{request.Id}", request);
}

Register the middleware once:

builder.Services.AddIdempotency().AddMemoryStore();
app.UseIdempotency();

Stores

Redis

builder.Services
    .AddIdempotency()
    .AddRedisStore(options =>
    {
        options.Configuration = builder.Configuration.GetConnectionString("Redis")!;
        options.KeyPrefix = "orders-api:";
    });

SQL

Supports PostgreSQL, SQL Server, and SQLite. The store auto-creates the idempotency_keys table on first startup (AutoMigrate = true by default) — no manual DDL or migration script needed.

builder.Services
    .AddIdempotency()
    .AddSqlStore(options =>
    {
        options.Provider = SqlProvider.PostgreSql;   // PostgreSql | SqlServer | Sqlite
        options.ConnectionString = builder.Configuration.GetConnectionString("Postgres")!;
        // options.AutoMigrate = false;  // opt out if you manage schema yourself
        // options.TableName = "idempotency_keys";  // override table name
    });

<details> <summary>Table schema (all providers)</summary>

Storage keys are SHA-256 hashes — the raw client Idempotency-Key value never appears in the database.

</details>

EF Core

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.AddIdempotencyKeys();
    // optionally: modelBuilder.Entity<IdempotencyKeyEntity>().ToTable("my_keys");
}

How It Works

new key
  -> claim as InFlight
  -> execute handler
  -> store response + fingerprint + TTL
  -> replay later identical requests

duplicate in-flight key
  -> return conflict or wait, based on options

duplicate completed key with a different fingerprint
  -> reject as fingerprint mismatch

Storage keys are SHA-256 hashes of the client key, scope, HTTP method, and path. The raw client key is never interpolated into SQL and is not used directly as a Redis key.

Beyond HTTP

MediatR pipeline behavior

builder.Services.AddIdempotentBehavior();

Implement IIdempotentRequest<TResponse> on any MediatR request to make it idempotent end-to-end, including through message queues and retry loops.

Outbound HTTP key injection

builder.Services.AddHttpClient("payments")
    .AddIdempotencyKeyHandler();

Propagates the current request's idempotency key to outbound HttpClient calls automatically, so downstream services deduplicate on the same key without extra code.

Wolverine inbox pattern

See samples/InboxWithMassTransit/ for an end-to-end inbox example using Wolverine.

Source Generator and Analyzers

The Idempotent.NET.SourceGenerators package (automatically included with Idempotent.NET) ships three Roslyn analyzers and a compile-time registry generator.

Analyzers

Registry generator

At compile time the generator discovers every IIdempotentRequest<T> implementation in your assembly and emits:

// auto-generated — do not edit
public static partial class IdempotencyEndpointRegistry
{
    public static readonly FrozenSet<string> RequestTypes = FrozenSet.ToFrozenSet(new[]
    {
        "MyApp.Commands.CreateOrderCommand",
        // ...
    });
}

This lets tooling and middleware inspect registered idempotent request types at zero runtime cost.

vs IdempotentAPI

IdempotentAPI is the established library in this space. Here is a direct comparison:

The core difference in scope: IdempotentAPI is an HTTP filter for controller APIs. Idempotent.NET covers the full lifecycle — HTTP layer, message bus, outbound clients, and raw query infrastructure.

Benchmarks

BenchmarkDotNet ShortRun on Windows 11, .NET SDK 10.0.103, runtime .NET 10.0.7, x64 RyuJIT AVX2.

Run them locally:

dotnet run -c Release --project benchmarks/Idempotent.NET.Benchmarks

Packages

Samples

The samples/ folder includes runnable Minimal API, controller, MediatR, Wolverine, outbound HTTP, and inbox examples.

License

MIT