rack-idempotency_key 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52baa32ae332842d9bcdf5d7ae8a2d3e4f4597c619313dee041213051bbeec43
-  data.tar.gz: a83d88e91d0814bcbb4f3808fc1eb8c03a09294e44537f32238c15649c95afb7
+  metadata.gz: 157af590e24f6928fc61715b006c746296b9a9b0192d42bf14975b1722117dc7
+  data.tar.gz: 41f8668647cf15a010732444f5c8071f93dc1434e9be5e0edbd3a45c403854bb
 SHA512:
-  metadata.gz: 4632d51f766b18bf459a126a3fb8a759cdd7bdad116c0395ef0ed8df8d874076a247f7d01372c55a30f394de2674c866bd5396d583de2694f2dd4b7faee177b6
-  data.tar.gz: f2be7f25e92145490bd328dae4d36a1714fa24b74e4ca9affa038fea9b052ddedfe2e3e2867eac70be554dc4a16f490b07ab18c4d4ef51d682388eb685662674
+  metadata.gz: e3b80b32393b26f2ef685948a39b95c0acbcf549a2b6d3bc08b3e654faacd866aa707d5d412e5a80b76d388dbfe417778d484fdbc1bda7c773ed6236d7adbe8f
+  data.tar.gz: c9b2b228020e64ce63c4aa0f19a9216a84812a48be30be15701d0eda01fd5d9e46d1c5d841b19cf3848e9168332bdcc907d1906ccfa96acc0d679b7f96f31409

data/.github/workflows/conventional-pr-title.yml

@@ -0,0 +1,35 @@
+name: Conventional Commits PR title
+
+on:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - reopened
+      - synchronize
+
+concurrency:
+  group: ${{github.workflow}}-${{github.ref}}
+  cancel-in-progress: true
+
+jobs:
+  conventional-pr-title:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+        with:
+          types: |
+            build
+            ci
+            chore
+            docs
+            feat
+            fix
+            perf
+            revert
+            refactor
+            style
+            test
+          requireScope: false

data/.github/workflows/lint.yml

@@ -6,15 +6,16 @@ on:
       - opened
       - reopened
       - synchronize
+  workflow_call:
 
 jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - uses: ruby/setup-ruby@v1
         with:
           bundler-cache: true
-          ruby-version: 2.5.0
+          ruby-version: 2.6
       - run: bundle install
       - run: bundle exec rubocop

data/.github/workflows/release.yml

@@ -6,7 +6,19 @@ on:
       - main
 
 jobs:
+  lint:
+    uses: ./.github/workflows/lint.yml
+  test:
+    uses: ./.github/workflows/test.yml
+    secrets:
+      CC_TEST_REPORTER_ID: ${{secrets.CC_TEST_REPORTER_ID}}
   release-please:
+    needs:
+      - lint
+      - test
+    permissions:
+      contents: write
+      pull-requests: write
     runs-on: ubuntu-latest
     steps:
       - uses: google-github-actions/release-please-action@v3
@@ -16,12 +28,26 @@ jobs:
           release-type: ruby
           token: ${{secrets.GITHUB_TOKEN}}
           version-file: "lib/rack/idempotency_key/version.rb"
-      - uses: actions/checkout@v3
+          changelog-types: >
+            [
+              { "type": "build", "section": "Build System", "hidden": false },
+              { "type": "ci", "section": "Continuous Integration", "hidden": false },
+              { "type": "chore", "section": "Miscellaneous Chores", "hidden": false },
+              { "type": "docs", "section": "Documentation", "hidden": false },
+              { "type": "feat", "section": "Features", "hidden": false },
+              { "type": "fix", "section": "Bug Fixes", "hidden": false },
+              { "type": "perf", "section": "Performance Improvements", "hidden": false },
+              { "type": "revert", "section": "Reverts", "hidden": false },
+              { "type": "refactor", "section": "Code Refactoring", "hidden": false },
+              { "type": "style", "section": "Styles", "hidden": false },
+              { "type": "test", "section": "Tests", "hidden": false }
+            ]
+      - uses: actions/checkout@v4
         if: ${{steps.release.outputs.release_created}}
       - uses: ruby/setup-ruby@v1
         with:
           bundler-cache: true
-          ruby-version: 2.7.0
+          ruby-version: 2.6
         if: ${{steps.release.outputs.release_created}}
       - run: bundle install
         if: ${{steps.release.outputs.release_created}}

data/.github/workflows/test.yml

@@ -6,6 +6,10 @@ on:
       - opened
       - reopened
       - synchronize
+  workflow_call:
+    secrets:
+      CC_TEST_REPORTER_ID:
+        required: true
 
 jobs:
   test:
@@ -14,12 +18,28 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: [2.5, 2.6, 2.7, '3.0', 3.1, head]
+        ruby: [2.6, 2.7, '3.0', 3.1, 3.2, 3.3, 3.4, head]
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - uses: ruby/setup-ruby@v1
         with:
           bundler-cache: true
           ruby-version: ${{ matrix.ruby }}
+      - run: bundle exec appraisal install
+      - run: bundle exec appraisal rspec
+  coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+          ruby-version: 2.6
       - run: bundle install
-      - run: bundle exec rake
+      - name: Test & publish code coverage
+        uses: paambaati/codeclimate-action@v6.0.0
+        env:
+          CC_TEST_REPORTER_ID: ${{secrets.CC_TEST_REPORTER_ID}}
+        with:
+          coverageCommand: bundle exec rspec
+          debug: true

data/.gitignore

@@ -1,14 +1,18 @@
 *.rbc
 *.swp
+**/.DS_Store
 /_yardoc/
 /.bundle/
 /.byebug_history
+/.DS_Store
 /.yardoc
 /.ruby-version
+/.tool-versions
 /coverage/
 /doc/
 /dump.rdb
 /Gemfile.lock
+/gemfiles/*.lock
 /pkg/
 /rack-idempotency_key-*.gem
 /spec/reports/

data/.rubocop.yml

@@ -1,11 +1,10 @@
 ---
 require:
   - rubocop-performance
-  - rubocop-rake
   - rubocop-rspec
 
 AllCops:
-  TargetRubyVersion: 2.5
+  TargetRubyVersion: 2.6
 
 Bundler/OrderedGems:
   Enabled: false
@@ -45,6 +44,11 @@ RSpec/MultipleMemoizedHelpers:
 Style/Documentation:
   Enabled: false
 
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  Exclude:
+    - 'gemfiles/*'
+
 Style/StringLiterals:
   Enabled: true
   EnforcedStyle: double_quotes

data/Appraisals

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+appraise "rack-2" do
+  gem "rack", "~> 2.0"
+end
+
+appraise "rack-3" do
+  gem "rack", "~> 3.0"
+end

data/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## [0.2.1](https://github.com/matteoredz/rack-idempotency_key/compare/v0.2.0...v0.2.1) (2025-01-31)
+
+
+### Continuous Integration
+
+* add rack 2 and 3 via appraisal gem ([#21](https://github.com/matteoredz/rack-idempotency_key/issues/21)) ([b603427](https://github.com/matteoredz/rack-idempotency_key/commit/b603427915422dabf658dcaad5a2af5199f64d44))
+
+
+### Code Refactoring
+
+* remove direct dependency on redis-rb ([#19](https://github.com/matteoredz/rack-idempotency_key/issues/19)) ([08d7a48](https://github.com/matteoredz/rack-idempotency_key/commit/08d7a488876c2029c8f8b80ce54ff1ad0086532e))
+
+## [0.2.0](https://github.com/matteoredz/rack-idempotency_key/compare/v0.1.1...v0.2.0) (2025-01-30)
+
+
+### Continuous Integration
+
+* add code climate coverage sync ([#6](https://github.com/matteoredz/rack-idempotency_key/issues/6)) ([4196edf](https://github.com/matteoredz/rack-idempotency_key/commit/4196edf2194668084d15ca3414ab3dd3d01551d4))
+* trigger lint and test before release ([#8](https://github.com/matteoredz/rack-idempotency_key/issues/8)) ([033aedd](https://github.com/matteoredz/rack-idempotency_key/commit/033aedd29ff24308ebdf6f4ea0d162374dd399af))
+* update gh workflows ([#5](https://github.com/matteoredz/rack-idempotency_key/issues/5)) ([84aa493](https://github.com/matteoredz/rack-idempotency_key/commit/84aa49341cf74e057efb48e2e68b5901d9843226))
+
+
+### Miscellaneous Chores
+
+* update Rakefile to use rspec ([#7](https://github.com/matteoredz/rack-idempotency_key/issues/7)) ([eb866ee](https://github.com/matteoredz/rack-idempotency_key/commit/eb866eea6d5ba9dac599a9c3b2cd239b0471b853))
+
+
+### Documentation
+
+* add quality badges ([#18](https://github.com/matteoredz/rack-idempotency_key/issues/18)) ([f8bcc96](https://github.com/matteoredz/rack-idempotency_key/commit/f8bcc96421b6b167a578728ff0d1eeb9c5eccff3))
+* add warning to readme ([#11](https://github.com/matteoredz/rack-idempotency_key/issues/11)) ([e0333c8](https://github.com/matteoredz/rack-idempotency_key/commit/e0333c813aaf2969bebad9ea72056a9d36e9489f))
+
+
+### Features
+
+* add request hashing ([#16](https://github.com/matteoredz/rack-idempotency_key/issues/16)) ([f0169fe](https://github.com/matteoredz/rack-idempotency_key/commit/f0169feb088c09c24d68c13a4f640fb41204e4e4))
+* allow redis store to receive a connection pool ([#13](https://github.com/matteoredz/rack-idempotency_key/issues/13)) ([adafc66](https://github.com/matteoredz/rack-idempotency_key/commit/adafc66cee442cc7521c559f2b4fc46651f9c0f9))
+* properly handle concurrent requests from Memory and Redis stores ([#15](https://github.com/matteoredz/rack-idempotency_key/issues/15)) ([d7fbbcc](https://github.com/matteoredz/rack-idempotency_key/commit/d7fbbccce3211e4ff2ce0b0d4ac0e7df4bbd5a10))
+
+
+### Bug Fixes
+
+* **docs:** document the correct default expiration time ([#17](https://github.com/matteoredz/rack-idempotency_key/issues/17)) ([ac0ea44](https://github.com/matteoredz/rack-idempotency_key/commit/ac0ea44ad5a7ecd450a2b8be11a192a19b7222cb))
+
+
+### Code Refactoring
+
+* better organise the idempotent request public interface ([#10](https://github.com/matteoredz/rack-idempotency_key/issues/10)) ([0f07fb2](https://github.com/matteoredz/rack-idempotency_key/commit/0f07fb2f55c62b0f08f2b8b96e040b494db48a6e))
+* change default store duration to 5 minutes ([#14](https://github.com/matteoredz/rack-idempotency_key/issues/14)) ([6fa2537](https://github.com/matteoredz/rack-idempotency_key/commit/6fa2537cd43d32b159e82064a938d9195f42ab7b))
+* remove configurable routes ([#12](https://github.com/matteoredz/rack-idempotency_key/issues/12)) ([2463b55](https://github.com/matteoredz/rack-idempotency_key/commit/2463b555188b5c4fee436ff6f96f3144a66c16fa))
+
 ## [0.1.1](https://github.com/matteoredz/rack-idempotency_key/compare/v0.1.0...v0.1.1) (2023-03-31)
 
 

data/Gemfile

@@ -4,14 +4,15 @@ source "https://rubygems.org"
 
 gemspec
 
+gem "appraisal", "~> 2.5"
 gem "byebug"
 gem "mock_redis"
+gem "rack", "~> 3.1", ">= 3.1.9"
 gem "rack-test"
-gem "rake"
-gem "rspec"
+gem "redis", "~> 5.3"
+gem "rspec", "~> 3.13"
 gem "rubocop"
 gem "rubocop-performance"
-gem "rubocop-rake"
 gem "rubocop-rspec"
 gem "simplecov"
 gem "timecop"

data/README.md

@@ -1,5 +1,11 @@
 # `Rack::IdempotencyKey`
 
+[![Gem Version](https://badge.fury.io/rb/rack-idempotency_key.svg)](https://badge.fury.io/rb/rack-idempotency_key) [![Maintainability](https://api.codeclimate.com/v1/badges/26b3ad3d3af3b2377037/maintainability)](https://codeclimate.com/github/matteoredz/rack-idempotency_key/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/26b3ad3d3af3b2377037/test_coverage)](https://codeclimate.com/github/matteoredz/rack-idempotency_key/test_coverage)
+
+> [!WARNING]
+> This gem is in its pre-1.0 release phase, which means it may contain bugs and the API is subject to change.
+> Proceed with caution and use it at your own risk.
+
 A Rack Middleware implementing the idempotency design principle using the `Idempotency-Key` HTTP header. A cached response, generated by an idempotent request, can be recognized by checking for the presence of the `Idempotent-Replayed` response header.
 
 ## What is idempotency?
@@ -13,7 +19,7 @@ To be idempotent, only the state of the server is considered. The response retur
 ## Under the hood
 
 - A valid idempotent request is cached on the server, using the `store` of choice
-- A cached response expires out of the system after `24 hours`
+- A cached response expires out of the system after `5 minutes` by default
 - A response with a `400` (BadRequest) HTTP status code isn't cached
 
 ## Installation
@@ -47,12 +53,7 @@ module MyApp
 
     config.middleware.use(
       Rack::IdempotencyKey,
-      store: Rack::IdempotencyKey::MemoryStore.new,
-      routes: [
-        { path: "/posts", method: "POST" },
-        { path: "/posts/*", method: "PATCH" },
-        { path: "/posts/*/comments", method: "POST" }
-      ]
+      store: Rack::IdempotencyKey::MemoryStore.new
     )
   end
 end
@@ -69,38 +70,68 @@ This one is the default store. It caches the response in memory.
 ```ruby
 Rack::IdempotencyKey::MemoryStore.new
 
-# Explicitly set the key's expiration, in seconds. The default is 86_400 (24 hours)
-Rack::IdempotencyKey::MemoryStore.new(expires_in: 43_200)
+# Explicitly set the key's expiration, in seconds. The default is 300 (5 minutes)
+Rack::IdempotencyKey::MemoryStore.new(expires_in: 300)
 ```
 
 ### RedisStore
 
-This one is the suggested store to use in production. It relies on the [redis gem](https://github.com/redis/redis-rb).
+This one is the suggested store to use in production. It relies on the [redis-rb](https://github.com/redis/redis-rb) gem, so make sure you're bundling it with your application.
 
 ```ruby
-Rack::IdempotencyKey::RedisStore.new(Redis.current)
+Rack::IdempotencyKey::RedisStore.new(Redis.new)
 
-# Explicitly set the key's expiration, in seconds. The default is 86_400 (24 hours)
-Rack::IdempotencyKey::RedisStore.new(Redis.current, expires_in: 43_200)
+# Explicitly set the key's expiration, in seconds. The default is 300 (5 minutes)
+Rack::IdempotencyKey::RedisStore.new(Redis.new, expires_in: 300)
 ```
 
-Every key written to Redis will get prefixed with `idempotency_key` to avoid conflicts on shared instances.
+If you're using a [Connection Pool](https://github.com/mperham/connection_pool), you can pass it instead of the single instance:
+
+```ruby
+redis_pool = ConnectionPool.new(size: 5, timeout: 5) { Redis.new }
+Rack::IdempotencyKey::RedisStore.new(redis_pool)
+```
 
 ### Custom Store
 
+> [!IMPORTANT]
+> Ensure proper concurrency handling when implementing a custom store to prevent race conditions and data inconsistencies.
+
 Any object that conforms to the following interface can be used as a custom Store:
 
 ```ruby
-# @param [String] key
+# Gets the value by key from the store.
+#
+# @param key [String] The cache key
+#
+# @raise [Rack::IdempotencyKey::StoreError]
+#   When the underlying store doesn't work as expected.
 #
 # @return [Array]
 def get(key)
 
-# @param [String] key
-# @param [Array]  value
+# Sets the value by key to the store.
+#
+# @param key [String] The cache key
+# @param value [Array] The cache value
+#
+# @raise [Rack::IdempotencyKey::ConflictError]
+#   When a concurrent request tries to update an already-cached request.
+# @raise [Rack::IdempotencyKey::StoreError]
+#   When the underlying store doesn't work as expected.
 #
 # @return [Array]
 def set(key, value)
+
+# Unsets the key/value pair from the store.
+#
+# @param key [String] The cache key
+#
+# @raise [Rack::IdempotencyKey::StoreError]
+#   When the underlying store doesn't work as expected.
+#
+# @return [Array]
+def unset(key)
 ```
 
 The Array returned must conform to the [Rack Specification](https://github.com/rack/rack/blob/main/SPEC.rdoc), as follows:
@@ -113,33 +144,12 @@ The Array returned must conform to the [Rack Specification](https://github.com/r
 ]
 ```
 
-## Idempotent Routes
-
-To declare the routes where you want to enable idempotency, you only need to pass a `route` keyword parameter when the Middleware gets mounted.
-
-Each route entry must be compliant with what follows:
-
-```ruby
-routes: [
-  { path: "/posts", method: "POST" },
-  { path: "/posts/*", method: "PATCH" },
-  { path: "/posts/*/comments", method: "POST" }
-]
-```
-
-The `*` char is a placeholder representing a named parameter that will get converted to an any-chars regex.
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies.
-Then, run `rake test` to run the tests.
+Then, run `bundle exec rspec` to run the tests.
 You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`.
-To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`,
-which will create a git tag for the version, push git commits and tags,
-and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/matteoredz/rack-idempotency_key.

data/gemfiles/rack_2.gemfile

@@ -0,0 +1,18 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal", "~> 2.5"
+gem "byebug"
+gem "mock_redis"
+gem "rack", "~> 2.0"
+gem "rack-test"
+gem "redis", "~> 5.3"
+gem "rspec", "~> 3.13"
+gem "rubocop"
+gem "rubocop-performance"
+gem "rubocop-rspec"
+gem "simplecov"
+gem "timecop"
+
+gemspec path: "../"

data/gemfiles/rack_3.gemfile

@@ -0,0 +1,18 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal", "~> 2.5"
+gem "byebug"
+gem "mock_redis"
+gem "rack", "~> 3.0"
+gem "rack-test"
+gem "redis", "~> 5.3"
+gem "rspec", "~> 3.13"
+gem "rubocop"
+gem "rubocop-performance"
+gem "rubocop-rspec"
+gem "simplecov"
+gem "timecop"
+
+gemspec path: "../"

data/idempotency_key.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email = ["mttrss5@gmail.com"]
   spec.summary = "A Rack Middleware implementing the idempotency principle"
   spec.homepage = "https://github.com/matteoredz/rack-idempotency_key"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.5.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.6.0")
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/matteoredz/rack-idempotency_key"
   spec.metadata["changelog_uri"] = "https://github.com/matteoredz/rack-idempotency_key/CHANGELOG.md"

data/lib/rack/idempotency_key/error.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Rack
+  class IdempotencyKey
+    # Base error class for all IdempotencyKey errors
+    Error = Class.new(StandardError)
+
+    # Error raised when a conflicting idempotent request is detected
+    class ConflictError < Error
+      DEFAULT_MESSAGE = "This request is already being processed. Please retry later."
+
+      def initialize(msg = DEFAULT_MESSAGE)
+        super(msg)
+      end
+    end
+
+    # Error raised for general store failures
+    StoreError = Class.new(Error)
+  end
+end

data/lib/rack/idempotency_key/memory_store.rb

@@ -3,34 +3,47 @@
 module Rack
   class IdempotencyKey
     class MemoryStore
-      def initialize(expires_in: 86_400)
+      DEFAULT_EXPIRATION = 300 # 5 minutes in seconds
+
+      def initialize(expires_in: DEFAULT_EXPIRATION)
         @store      = {}
         @expires_in = expires_in
+        @mutex      = Mutex.new
       end
 
       def get(key)
-        value = store[key]
-        return if value.nil?
+        mutex.synchronize do
+          value = store[key]
+          return if value.nil?
 
-        if expired?(value[:added_at])
-          store.delete(key)
-          return
-        end
+          if expired?(value[:expires_at])
+            store.delete(key)
+            return
+          end
 
-        value[:value]
+          value[:value]
+        end
       end
 
-      def set(key, value)
-        store[key] ||= { value: value, added_at: Time.now.utc }
+      def set(key, value, ttl: expires_in)
+        mutex.synchronize do
+          store[key] ||= { value: value, expires_at: Time.now.utc + ttl }
+          raise Rack::IdempotencyKey::ConflictError if store[key][:value] != value
+        end
+
         get(key)
       end
 
+      def unset(key)
+        mutex.synchronize { store.delete(key) }
+      end
+
       private
 
-        attr_reader :store, :expires_in
+        attr_reader :store, :expires_in, :mutex
 
-        def expired?(added_at)
-          Time.now.utc - added_at > expires_in
+        def expired?(expires_at)
+          Time.now.utc > expires_at
         end
     end
   end

data/lib/rack/idempotency_key/redis_store.rb

@@ -1,31 +1,127 @@
 # frozen_string_literal: true
 
+require "redis"
+
 module Rack
   class IdempotencyKey
+    # Redis-based store for handling idempotency keys.
+    #
+    # This class provides methods to store, retrieve, and delete idempotency keys
+    # in a Redis database, ensuring that the same request is not processed multiple
+    # times. It supports both direct Redis instances and connection pools.
+    #
+    # @example Using a direct Redis instance
+    #   redis = Redis.new
+    #   store = Rack::IdempotencyKey::RedisStore.new(redis)
+    #
+    # @example Using a Redis connection pool
+    #   redis_pool = ConnectionPool.new(size: 5, timeout: 5) { Redis.new }
+    #   store = Rack::IdempotencyKey::RedisStore.new(redis_pool)
     class RedisStore
-      KEY_NAMESPACE = "idempotency_key"
+      DEFAULT_EXPIRATION = 300 # 5 minutes in seconds
 
-      def initialize(store, expires_in: 86_400)
+      # Initializes a new RedisStore instance.
+      #
+      # @param store [Redis, ConnectionPool] A Redis instance or a connection pool.
+      # @param expires_in [Integer] The default expiration time for stored values, in seconds.
+      #
+      # @example
+      #   redis = Redis.new
+      #   store = Rack::IdempotencyKey::RedisStore.new(redis, expires_in: 600)
+      def initialize(store, expires_in: DEFAULT_EXPIRATION)
         @store      = store
         @expires_in = expires_in
       end
 
+      # Retrieves a value from Redis by key.
+      #
+      # The stored value is expected to be JSON-encoded and is automatically parsed.
+      # If the key does not exist, `nil` is returned.
+      #
+      # @param key [String] The Redis key to retrieve.
+      # @return [Object, nil] The parsed JSON value, or `nil` if the key does not exist.
+      #
+      # @raise [Rack::IdempotencyKey::StoreError] If a Redis-related error occurs.
+      #
+      # @example Retrieve a value from Redis
+      #   store.get("key") # => "value"
       def get(key)
-        value = store.get(namespaced_key(key))
+        value = with_redis { |redis| redis.get(key) }
         JSON.parse(value) unless value.nil?
+      rescue Redis::BaseError => e
+        raise Rack::IdempotencyKey::StoreError, "#{self.class}: #{e.message}"
       end
 
-      def set(key, value)
-        store.set(namespaced_key(key), value, nx: true, ex: expires_in)
+      # Stores a value in Redis with an optional time-to-live (TTL).
+      #
+      # This method ensures that the key is only set if it does not already exist (`NX` flag).
+      # If the key is already present, a `ConflictError` is raised.
+      #
+      # @param key [String] The Redis key to set.
+      # @param value [String] The value to store.
+      # @param ttl [Integer] The expiration time in seconds (defaults to `expires_in`).
+      #
+      # @return [Object, nil] The stored value retrieved from Redis.
+      #
+      # @raise [Rack::IdempotencyKey::ConflictError] If the key already exists and is locked.
+      # @raise [Rack::IdempotencyKey::StoreError] If a Redis-related error occurs.
+      #
+      # @example Store a new idempotency key
+      #   store.set("key", "value", ttl: 600)
+      def set(key, value, ttl: expires_in)
+        with_redis do |redis|
+          result = redis.set(key, value, nx: true, ex: ttl)
+          raise Rack::IdempotencyKey::ConflictError unless result
+        end
+
         get(key)
+      rescue Redis::BaseError => e
+        raise Rack::IdempotencyKey::StoreError, "#{self.class}: #{e.message}"
+      end
+
+      # Deletes a key from Redis.
+      #
+      # This method removes the idempotency key from Redis, allowing the same request
+      # to be processed again in the future.
+      #
+      # @param key [String] The Redis key to delete.
+      #
+      # @raise [Rack::IdempotencyKey::StoreError] If a Redis-related error occurs.
+      #
+      # @example Remove an idempotency key
+      #   store.unset("key")
+      def unset(key)
+        with_redis { |redis| redis.del(key) }
+      rescue Redis::BaseError => e
+        raise Rack::IdempotencyKey::StoreError, "#{self.class}: #{e.message}"
       end
 
       private
 
         attr_reader :store, :expires_in
 
-        def namespaced_key(key)
-          "#{KEY_NAMESPACE}:#{key.split.join}"
+        # Executes the given block with a Redis connection, supporting both direct
+        # Redis instances and connection pools (https://github.com/mperham/connection_pool).
+        #
+        # If a `ConnectionPool` is detected (by responding to `with`), it will yield a Redis
+        # connection from the pool. Otherwise, it will yield the direct Redis instance.
+        #
+        # @yieldparam redis [Redis] A Redis connection instance.
+        # @return [Object] The result of the block execution.
+        #
+        # @example Using a direct Redis instance
+        #   store = RedisStore.new(Redis.new)
+        #   store.with_redis { |redis| redis.set("key", "value") }
+        #
+        # @example Using a Redis connection pool
+        #   store = RedisStore.new(ConnectionPool.new(size: 5, timeout: 5) { Redis.new })
+        #   store.with_redis { |redis| redis.set("key", "value") }
+        def with_redis(&block)
+          if store.respond_to?(:with)
+            store.with(&block)
+          else
+            yield store
+          end
         end
     end
   end

data/lib/rack/idempotency_key/request.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "rack/idempotency_key/request_hash"
+
+module Rack
+  class IdempotencyKey
+    class Request
+      DEFAULT_LOCK_TTL = 60 # seconds
+
+      # @param request [Rack::Request]
+      # @param store   [Store]
+      def initialize(request, store)
+        @request    = request
+        @request_id = Rack::IdempotencyKey::RequestHash.new(request).id
+        @store      = store
+      end
+
+      # Checks if the `Idempotency-Key` header is present, if the HTTP request method is allowed.
+      #
+      # @return [Boolean]
+      def allowed?
+        idempotency_key? && allowed_method?
+      end
+
+      def cached_response!
+        store.get(cache_key).tap do |response|
+          response[1]["Idempotent-Replayed"] = true unless response.nil?
+        end
+      end
+
+      def locked!
+        store.set(lock_key, 1, ttl: DEFAULT_LOCK_TTL)
+
+        begin
+          yield
+        ensure
+          store.unset(lock_key)
+        end
+      end
+
+      def cache!(response)
+        status, = response
+        store.set(cache_key, response) if status != 400
+      end
+
+      # Checks if the HTTP request method is non-idempotent by design.
+      #
+      # @return [Boolean]
+      def allowed_method?
+        %w[POST PATCH CONNECT].include? request.request_method
+      end
+
+      # Checks if the given request has the Idempotency-Key header
+      #
+      # @return [Boolean]
+      def idempotency_key?
+        request.has_header? "HTTP_IDEMPOTENCY_KEY"
+      end
+
+      # Fetches the Idempotency-Key header value from the request headers
+      #
+      # @return [String, nil]
+      def idempotency_key
+        request.get_header "HTTP_IDEMPOTENCY_KEY"
+      end
+
+      private
+
+        attr_reader :request, :request_id, :store
+
+        def cache_key
+          "idempotency_key:#{request_id}"
+        end
+
+        def lock_key
+          "#{cache_key}_lock"
+        end
+    end
+  end
+end

data/lib/rack/idempotency_key/request_hash.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Rack
+  class IdempotencyKey
+    class RequestHash
+      def initialize(rack_request)
+        @rack_request = rack_request
+      end
+
+      # Generates a unique SHA-256 hash to identify the request.
+      #
+      # The hash is constructed using the request method, full path, idempotency key,
+      # authorization header, and the request body (if available and rewindable).
+      #
+      # This ensures that requests with identical content produce the same fingerprint,
+      # supporting idempotency while preventing accidental collisions between different clients.
+      #
+      # @return [String] A SHA-256 hexadecimal digest representing the request fingerprint.
+      def id
+        digest = Digest::SHA256.new
+        digest.update(rack_request.request_method)
+        digest.update(rack_request.fullpath)
+        digest.update(idempotency_key_header)
+        digest.update(authorization_header)
+        update_with_request_body_chunks(digest)
+        digest.hexdigest
+      end
+
+      private
+
+        attr_reader :rack_request
+
+        # Retrieves the `Idempotency-Key` header from the request. If the header is missing,
+        # it defaults to `"no-idempotency-key"` to ensure that the request can still be processed
+        # while clearly indicating the absence of an explicit idempotency key.
+        def idempotency_key_header
+          rack_request.get_header("HTTP_IDEMPOTENCY_KEY") || "no-idempotency-key"
+        end
+
+        # Retrieves the Authorization header from the request. If the header is missing,
+        # defaults to "no-authorization" to indicate the absence of credentials.
+        def authorization_header
+          rack_request.get_header("HTTP_AUTHORIZATION") || "no-authorization"
+        end
+
+        # Updates the given digest with the request body content. If the body is non-rewindable
+        # (e.g., a streaming request), it appends a predefined "streaming-body" marker instead.
+        # Otherwise, it reads the body in 8KB chunks for efficient hashing and ensures the stream
+        # is rewound after processing.
+        #
+        # @param digest [Digest::SHA256]
+        def update_with_request_body_chunks(digest)
+          return digest.update("streaming-body") unless rack_request.body.respond_to?(:rewind)
+
+          begin
+            while (chunk = rack_request.body.read(8192))
+              digest.update(chunk)
+            end
+          ensure
+            rack_request.body.rewind
+          end
+        end
+    end
+  end
+end

data/lib/rack/idempotency_key/version.rb

@@ -2,6 +2,6 @@
 
 module Rack
   class IdempotencyKey
-    VERSION = "0.1.1"
+    VERSION = "0.2.1"
   end
 end

data/lib/rack/idempotency_key.rb

@@ -1,42 +1,50 @@
 # frozen_string_literal: true
 
 require "rack/idempotency_key/version"
+require "rack/idempotency_key/error"
 
 # Stores
 require "rack/idempotency_key/memory_store"
-require "rack/idempotency_key/redis_store"
+
+begin
+  require "rack/idempotency_key/redis_store"
+rescue LoadError => e
+  warn "RedisStore was not required: #{e.message}"
+  warn "* Add 'redis' to your bundle to use this store."
+end
 
 # Collaborators
-require "rack/idempotency_key/idempotent_request"
+require "rack/idempotency_key/request"
 
 module Rack
   class IdempotencyKey
-    Error = Class.new(StandardError)
-
-    def initialize(app, routes: [], store: MemoryStore.new)
-      @app    = app
-      @routes = routes
-      @store  = store
+    def initialize(app, store: MemoryStore.new)
+      @app   = app
+      @store = store
     end
 
     def call(env)
-      request = IdempotentRequest.new(Rack::Request.new(env), routes)
+      request = Request.new(Rack::Request.new(env), store)
       return app.call(env) unless request.allowed?
 
-      cached_response = store.get(request.idempotency_key)
-
-      if cached_response
-        cached_response[1]["Idempotent-Replayed"] = true
-        return cached_response
-      end
-
-      app.call(env).tap do |response|
-        store.set(request.idempotency_key, response) if response[0] != 400
-      end
+      handle_request!(request, env)
+    rescue ConflictError => e
+      [409, { "Content-Type" => "text/plain" }, [e.message]]
+    rescue StoreError => e
+      [503, { "Content-Type" => "text/plain" }, [e.message]]
     end
 
     private
 
-      attr_reader :app, :store, :routes
+      attr_reader :app, :store
+
+      def handle_request!(request, env)
+        request.locked! do
+          cached_response = request.cached_response!
+          return cached_response unless cached_response.nil?
+
+          app.call(env).tap { |response| request.cache!(response) }
+        end
+      end
   end
 end

metadata

@@ -1,16 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: rack-idempotency_key
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.1
 platform: ruby
 authors:
 - Matteo Rossi
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-03-31 00:00:00.000000000 Z
+date: 2025-01-31 00:00:00.000000000 Z
 dependencies: []
-description: 
+description:
 email:
 - mttrss5@gmail.com
 executables: []
@@ -18,26 +18,30 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/CODEOWNERS"
+- ".github/workflows/conventional-pr-title.yml"
 - ".github/workflows/lint.yml"
 - ".github/workflows/release.yml"
 - ".github/workflows/test.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
-- ".travis.yml"
+- Appraisals
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - README.md
-- Rakefile
 - bin/console
 - bin/release
 - bin/setup
+- gemfiles/rack_2.gemfile
+- gemfiles/rack_3.gemfile
 - idempotency_key.gemspec
 - lib/rack/idempotency_key.rb
-- lib/rack/idempotency_key/idempotent_request.rb
+- lib/rack/idempotency_key/error.rb
 - lib/rack/idempotency_key/memory_store.rb
 - lib/rack/idempotency_key/redis_store.rb
+- lib/rack/idempotency_key/request.rb
+- lib/rack/idempotency_key/request_hash.rb
 - lib/rack/idempotency_key/version.rb
 homepage: https://github.com/matteoredz/rack-idempotency_key
 licenses:
@@ -46,7 +50,7 @@ metadata:
   homepage_uri: https://github.com/matteoredz/rack-idempotency_key
   source_code_uri: https://github.com/matteoredz/rack-idempotency_key
   changelog_uri: https://github.com/matteoredz/rack-idempotency_key/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -54,15 +58,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.5.0
+      version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 3.0.3.1
+signing_key:
 specification_version: 4
 summary: A Rack Middleware implementing the idempotency principle
 test_files: []

data/.travis.yml

@@ -1,6 +0,0 @@
----
-language: ruby
-cache: bundler
-rvm:
-  - 2.7.0
-before_install: gem install bundler -v 2.1.4

data/Rakefile

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "rake/testtask"
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
-end
-
-task default: :test

data/lib/rack/idempotency_key/idempotent_request.rb

@@ -1,81 +0,0 @@
-# frozen_string_literal: true
-
-module Rack
-  class IdempotencyKey
-    class IdempotentRequest
-      # @param [Rack::Request] request
-      # @param [Array]         routes
-      def initialize(request, routes = [])
-        @request = request
-        @routes  = routes
-      end
-
-      # Check if the `Idempotency-Key` header is present, if the HTTP request method is
-      # allowed and if there is any matching route whitelisted in the `routes` array.
-      #
-      # @return [Boolean]
-      def allowed?
-        idempotency_key? && allowed_method? && any_matching_route?
-      end
-
-      # Check if the HTTP request method is non-idempotent by design.
-      #
-      # @return [Boolean]
-      def allowed_method?
-        %w[POST PATCH CONNECT].include? request.request_method
-      end
-
-      # Check if there is any matching route from the `routes` input array against
-      # the currently requested path.
-      #
-      # @return [Boolean]
-      def any_matching_route?
-        routes.any? { |route| matching_route?(route[:path]) && matching_method?(route[:method]) }
-      end
-
-      # Check if the given request has the Idempotency-Key header
-      #
-      # @return [Boolean]
-      def idempotency_key?
-        request.has_header? "HTTP_IDEMPOTENCY_KEY"
-      end
-
-      # Fetches the Idempotency-Key header value from the request headers
-      #
-      # @return [String, nil]
-      def idempotency_key
-        request.get_header "HTTP_IDEMPOTENCY_KEY"
-      end
-
-      private
-
-        attr_reader :request, :routes
-
-        def matching_route?(route_path)
-          route_segments = segments route_path
-          path_segments.size == route_segments.size && same_segments?(route_segments)
-        end
-
-        def matching_method?(route_method)
-          request.request_method.casecmp(route_method).zero?
-        end
-
-        def path_segments
-          @path_segments ||= segments(request.path_info)
-        end
-
-        def segments(path)
-          path.split("/").reject(&:empty?)
-        end
-
-        def same_segments?(route_segments)
-          path_segments.each_with_index do |path_segment, index|
-            route_segment = Regexp.new route_segments[index].gsub("*", '\w+'), Regexp::IGNORECASE
-            return false unless path_segment.match?(route_segment)
-          end
-
-          true
-        end
-    end
-  end
-end