FastIdempotency.Storage.Postgres 2.0.1

FastIdempotency

⚡ High-Performance, Distributed Idempotency Middleware for ASP.NET Core (.NET 10).

When network timeouts, client retries, or duplicate webhooks hit your API, duplicate processing can cause critical bugs (such as double-charging a customer or duplicating inventory orders).

FastIdempotency guarantees that no matter how many retries arrive with the same Idempotency-Key header:

• The operation executes exactly once.
• Subsequent duplicate requests receive the cached response immediately.
• Payloads are validated against a SIMD-accelerated XxHash3 fingerprint to reject malicious/accidental key reuse (HTTP 422 Unprocessable Content).
• Distributed concurrency is safely handled using atomic Lua scripts in Redis or row-level locking in PostgreSQL.

📦 Package Ecosystem

FastIdempotency is organized into modular packages so you only install what you need:

📊 End-to-End Performance Benchmarks

Hardware: 11th Gen Intel Core i7-11800H @ 2.30GHz (8 cores / 16 threads), .NET 10.0 RyuJIT x64, Windows 11
Benchmarks executed via BenchmarkDotNet

1. Redis End-to-End & Store Benchmarks (Live Docker Redis 7)

Tested against a live Redis container with atomic Lua distributed locking and pipelined batch response storage.

Key takeaway: FastIdempotency adds sub-millisecond overhead for atomic Redis distributed locking, and short-circuits cache hit replays in ~0.65 ms total pipeline time with single-digit KB memory allocations.

2. ASP.NET Core Middleware Pipeline Overhead (In-Memory Baseline)

Measures pure middleware overhead excluding network and disk I/O.

3. Request Fingerprinting (XxHash3 vs Cryptographic Hashes)

FastIdempotency uses SIMD-accelerated XxHash3 (System.IO.Hashing) for zero-allocation, ultra-fast request fingerprinting:

4. Memory Stream Buffering (RecyclableMemoryStream vs Naive MemoryStream)

FastIdempotency uses Microsoft.IO.RecyclableMemoryStream to eliminate Large Object Heap (LOH) fragmentation on captured response bodies:

🚀 Quick Start

1. Install via NuGet

# Core Middleware (Required)
dotnet add package FastIdempotency.AspNetCore

# Choose your Storage Backend:
dotnet add package FastIdempotency.Storage.Redis     # Option A: Redis
# OR
dotnet add package FastIdempotency.Storage.Postgres  # Option B: PostgreSQL

2. Register Services in Program.cs

Option A: With Redis

using FastIdempotency.AspNetCore;
using FastIdempotency.Storage.Redis;

var builder = WebApplication.CreateBuilder(args);

// Register FastIdempotency with Redis
builder.Services.AddFastIdempotency(options =>
{
    options.HeaderName = "Idempotency-Key";
    options.RetentionWindow = TimeSpan.FromHours(24);
    options.LockTimeout = TimeSpan.FromSeconds(30);
    options.MaxPayloadSizeBytes = 10 * 1024 * 1024; // 10 MB
})
.AddFastIdempotencyRedis(builder.Configuration.GetConnectionString("Redis") ?? "localhost:6379");

var app = builder.Build();

app.UseFastIdempotency();
app.MapControllers();
app.Run();

Option B: With PostgreSQL

using FastIdempotency.AspNetCore;
using FastIdempotency.Storage.Postgres;

var builder = WebApplication.CreateBuilder(args);

// Register FastIdempotency with PostgreSQL (auto-migrates schema on startup)
builder.Services.AddFastIdempotency(options =>
{
    options.HeaderName = "Idempotency-Key";
    options.RetentionWindow = TimeSpan.FromHours(24);
})
.AddFastIdempotencyPostgres(builder.Configuration.GetConnectionString("Postgres")!);

var app = builder.Build();

app.UseFastIdempotency();
app.MapControllers();
app.Run();

⚙️ Configuration Options

🛠️ Architecture & Features

flowchart TD
    Client[Client Request with Idempotency-Key] --> MW[IdempotencyMiddleware]
    MW --> Hash[Compute XxHash3 Payload Fingerprint]
    MW --> Check{Record Exists in Store?}
    Check -->|Completed & Hash Matches| Replay[Replay Cached Response 200/201]
    Check -->|Completed & Hash Mismatch| Reject[422 Unprocessable Content: Payload Mismatch]
    Check -->|InFlight| LockHeld[Smart Polling / 409 Conflict]
    Check -->|Not Found| Lock[Acquire Distributed Lock]
    Lock --> Downstream[Execute Controller / Business Logic]
    Downstream --> Capture[Capture Response via Recyclable Stream]
    Save --> ClientResponse[Return Response to Client]
    Capture --> Save[Batch Save Response & Set TTL]

• Atomic Distributed Locking: Redis Lua scripts and PostgreSQL row-level locks prevent race conditions across replica instances.
• Payload Verification: SIMD XxHash3 hashing rejects duplicate keys reused with different payloads (422 Unprocessable Content).
• Zero LOH Allocations: Microsoft.IO.RecyclableMemoryStream pool prevents memory leaks on large response payloads.
• Pluggable Architecture: Clear separation of concerns with standalone storage providers.

🧪 Running Benchmarks & Tests Locally

Start Redis

docker run -d --name fastidempotency-redis -p 6379:6379 redis:7-alpine

Run Tests

dotnet test

Run Benchmarks

# Run all benchmarks
dotnet run -c Release --project tests/FastIdempotency.Benchmarks -- --filter *

# Run specific suite
dotnet run -c Release --project tests/FastIdempotency.Benchmarks -- --filter *RedisStore*
dotnet run -c Release --project tests/FastIdempotency.Benchmarks -- --filter *Hashing*
dotnet run -c Release --project tests/FastIdempotency.Benchmarks -- --filter *BodyCapture*