FGutierrez.Core.Idempotency 1.1.9

.NET 8.0

dotnet add package FGutierrez.Core.Idempotency --version 1.1.9

NuGet\Install-Package FGutierrez.Core.Idempotency -Version 1.1.9

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="FGutierrez.Core.Idempotency" Version="1.1.9" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="FGutierrez.Core.Idempotency" Version="1.1.9" />
                    

                            Directory.Packages.props

<PackageReference Include="FGutierrez.Core.Idempotency" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add FGutierrez.Core.Idempotency --version 1.1.9

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: FGutierrez.Core.Idempotency, 1.1.9"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package FGutierrez.Core.Idempotency@1.1.9

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=FGutierrez.Core.Idempotency&version=1.1.9
                    

                            Install as a Cake Addin

#tool nuget:?package=FGutierrez.Core.Idempotency&version=1.1.9
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

⚡ FGutierrez.Core.Idempotency

📖 Overview

FGutierrez.Core.Idempotency is a high-performance .NET 8 library designed to guarantee that critical operations such as payments, order creation, and transactional workflows are executed exactly once, even in scenarios involving retries, duplicated requests, or network failures.

The library provides a distributed idempotency engine with multi-provider persistence support and built-in observability integrations.

🎯 Why This Library?

Implementing idempotency manually often introduces:

Boilerplate middleware
Duplicate business execution
Inconsistent storage logic
Poor traceability
Lack of metrics and diagnostics

This library solves those challenges through a unified and extensible architecture.

✨ Features

Feature	Description
⚡ High Performance	Optimized request interception pipeline
🗄 Multi-Provider	Redis or PostgreSQL support
📊 Observability	OpenTelemetry metrics & tracing
♻ Response Caching	Stores and replays original responses
🔒 Duplicate Prevention	Prevents re-execution of business operations
🧩 Extensible	Provider-based architecture
🏗 Auto Schema	Automatic PostgreSQL schema generation

🧠 Architecture

🏗️ Architecture & Workflow

Idempotency Flow

📦 Supported Providers

Provider	Technology
PostgreSQL	Dapper
Redis	StackExchange.Redis

📊 Observability

The library exposes native OpenTelemetry instrumentation for:

Request duration
Cache hits/misses
Duplicate detection
Storage latency
Exception tracking

Compatible with:

Jaeger
Prometheus
Grafana
OTLP Collectors

📦 Installation

dotnet add package FGutierrez.Core.Idempotency

⚙️ Configuration

🛠️ Infrastructure Setup (PostgreSQL)

Database Provisioning: The library automatically creates the required table (idempotency_keys) and indexes, but it requires the physical database to exist in the server.

Before running the application, ensure the database specified in your connection string is created:

CREATE DATABASE idempotency_db; -- or the name in your connection string (ConnectionStrings.Idempotency)

🕒 Expiration Format (`TimeSpan`)

The Expiration field follows the standard .NET TimeSpan string format: [d.]hh:mm:ss.

Hour Overflow: In .NET, the hour component must be between 0 and 23. If you specify 24:00:00, the system will interpret it as 24 days instead of 24 hours.

To avoid misconfigurations, use the following guide:

Desired Duration	Config Value	Explanation
1 Hour	`01:00:00`	Standard `hh:mm:ss`
23 Hours	`23:00:00`	Maximum hour value
24 Hours (1 Day)	`1.00:00:00`	Use `d.hh:mm:ss` (note the dot)
30 Hours	`1.06:00:00`	1 Day + 6 Hours
7 Days	`7.00:00:00`	7 Days

appsettings.json

{
  "ConnectionStrings": {
    "Idempotency": "Host=localhost;Port=5432;Database=idempotency_db;Username=admin;Password=admin"
  },
  "Idempotency": {
    "Enabled": true,
    "Provider": "PostgreSQL",
    "AllowedMethods": [ "POST", "PUT", "DELETE" ],
    "HeaderName": "X-Idempotency-Key",
    "Expiration": "06:00:00",
    "MeterName": "FGutierrez.Core.Idempotency"
  }
}

🚀 Quick Start

Register Services

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddIdempotencyProvider(builder.Configuration);

var app = builder.Build();

Enable Middleware

app.UseIdempotency();

app.Run();

⚙️ Request Lifecycle

Client sends a request with X-Idempotency-Key
Middleware checks storage provider
If the key exists:
- Cached response is returned
If the key does not exist:
- Business logic executes normally
- Response is persisted
- Response is returned to the client
Telemetry is exported automatically

🛠 Requirements

.NET 8 SDK
PostgreSQL 16+ or Redis 7+
Optional OpenTelemetry Collector

🧪 Future Roadmap

SQL Server Provider
MongoDB Provider

🤝 Contributing

Contributions are welcome.

To contribute:

Fork the repository
Create a feature branch
Commit your changes
Open a Pull Request

📄 License

⭐ Support

If this project helped you, consider giving it a star on GitHub.

Product	Compatible and additional computed target framework versions.
.NET	net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.

Product

.NET

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net8.0
- Dapper (>= 2.1.79)
- Microsoft.AspNetCore.Http.Abstractions (>= 2.3.10)
- Microsoft.Extensions.Configuration (>= 8.0.0)
- Microsoft.Extensions.Configuration.Binder (>= 8.0.2)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.2)
- Microsoft.Extensions.Options (>= 8.0.2)
- Npgsql (>= 8.0.3)
- OpenTelemetry.Api (>= 1.15.3)
- StackExchange.Redis (>= 2.13.1)

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
1.1.9	99	5/27/2026
1.1.8	98	5/26/2026
1.1.7	96	5/26/2026
1.1.6	112	5/26/2026

# Release Notes - 1.1.3

- Refactor: Migrated agnostic registration to Core.
- Fix: Downgraded Npgsql to 8.0.3 to resolve TypeLoadException.
- Feature: Added AddIdempotencyProvider(IConfiguration) extension.
- Clean: Removed deprecated Http.Abstractions dependencies.

## [1.1.6] - 2026-05-26
### Fixed
- Correct Error: Fixed comparison error in AddIdempotencyProvider where ToUpperInvariant() did not match switch cases.