FastIdempotency.Storage.Postgres 1.0.1

FastIdempotency

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

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.

📊 End-to-End Performance Benchmarks

Hardware: 11th Gen Intel Core i7-11800H @ 2.30GHz (8 cores / 16 threads), .NET 8.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 ~1.0 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:

🚀 Quick Start

1. Install via NuGet

# Core Middleware
dotnet add package FastIdempotency.AspNetCore

# Redis Storage Provider
dotnet add package FastIdempotency.Storage.Redis

# OR PostgreSQL Storage Provider
dotnet add package FastIdempotency.Storage.Postgres

2. Register Services

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

var builder = WebApplication.CreateBuilder(args);

// Register Redis connection
var redis = ConnectionMultiplexer.Connect(builder.Configuration.GetConnectionString("Redis") ?? "localhost:6379");

// Configure FastIdempotency
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
})
.UseRedis(redis);

var app = builder.Build();

// Add middleware to pipeline
app.UseFastIdempotency();

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

🛠️ Architecture & Features

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

• Atomic Distributed Locking: Redis Lua scripts ensure race-free distributed locking across auto-scaled replica instances.
• Payload Validation: Prevents reusing the same key with different payloads.
• Recyclable Memory Streams: Non-allocating buffer management for response capture.
• Multi-Storage Support: First-class support for Redis and PostgreSQL.

🧪 Running Benchmarks & Tests Locally

Start Redis

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

Run Tests

dotnet test

Run Benchmarks

dotnet run -c Release --project tests/FastIdempotency.Benchmarks -- --filter *RedisStore*