Rack Idempotency Kit

Stripe-style idempotency for Rack and Rails APIs.

Rack Idempotency Kit ensures that repeated requests with the same idempotency key replay the original response instead of executing the action twice. It protects against retries, network timeouts, and client-side duplications.

The middleware stores a fingerprint of the request and a completed response. If the same key is used with different request parameters, it returns a conflict.

• Payment, checkout, and webhook endpoints with retries
• API clients with timeouts and automatic replays
• Protecting side-effecting endpoints from duplicate writes
• Reducing p99 spikes caused by retry storms

• Ruby 3.0+
• Rack 2.2+
• Works with Rails middleware stack

Also check out these related gems:

• Cache Coalescer: https://github.com/Elysium-Arc/cache-coalescer
• Cache SWR: https://github.com/Elysium-Arc/cache-swr
• Faraday Hedge: https://github.com/Elysium-Arc/faraday-hedge
• Env Contract: https://github.com/Elysium-Arc/env-contract

# Gemfile

gem "rack-idempotency-kit"

# config/application.rb
config.middleware.use Rack::Idempotency::Kit,
  store: Rails.cache,
  ttl: 86_400,
  header: "Idempotency-Key"

use Rack::Idempotency::Kit,
  store: MyStore.new,
  ttl: 86_400,
  header: "Idempotency-Key"

• store storage backend
• ttl (Integer) response retention in seconds
• header (String) idempotency header name
• methods (Array) HTTP methods to protect
• wait_timeout (Float) wait time for in-flight requests
• lock_ttl (Integer) in-flight lock TTL in seconds
• max_body_bytes (Integer) maximum body size to store

• ActiveSupport cache stores (read/write)
• Redis-style stores (get/set)

• Replays stored responses for repeated idempotency keys
• Returns 409 if the same key is reused with a different request fingerprint
• Returns 409 if a request is still in flight after wait_timeout

bundle exec rake release