rack-idempotency_key 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9358732d434938ba1444636f644cb3d8a161e95aa913e2c60e62f77b74cc635c
-  data.tar.gz: 9862a6bcb70d4bb24bcb85ae6eaf07265116ecdddcdede65ba6b8effcbb2155a
+  metadata.gz: e373df67d62807148650baff69ae771992a755e3188e1ed7cc073ab1a96f4752
+  data.tar.gz: d03656ab0464a9daa8773964de916fbc8f65cabed93449a79b39eedd854f044d
 SHA512:
-  metadata.gz: 78e77d1c68c3df1f39edd5df9e2a53e169e6dd4057fcc8cb1f01ec659d16e33a7c59c290596828ab98159ee2e90f8168986f9aaf668f99b547bc4bced6bf4949
-  data.tar.gz: 3c5c345ccd361084b39d86b7ec4458240aaa9b02f399e53bad9e4fe06296ed7d4718ddd262c60adb00096f285a8540ecc493606a703a1257332ecccb349067aa
+  metadata.gz: 99c992fa0e6d742aac0d4b310034df7e329baf13dbb890b5adde181e433bbafccf2baa4d5d53ac9a3b99382d49592b094a67ccd8f624a5cd89006365a500890e
+  data.tar.gz: 4d2ed1c9827cca08f177ccc09d5af6e717213d705ccf95d712772d91f0be21ab769f13b0dc373e09762d30d7b5a0538a766fd4b5d4320789aecf5901617eda2d

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 install
       - run: bundle exec rake
+  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
+      - 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 rake
+          debug: true

data/.gitignore

@@ -1,10 +1,13 @@
 *.rbc
 *.swp
+**/.DS_Store
 /_yardoc/
 /.bundle/
 /.byebug_history
+/.DS_Store
 /.yardoc
 /.ruby-version
+/.tool-versions
 /coverage/
 /doc/
 /dump.rdb

data/.rubocop.yml

@@ -5,7 +5,7 @@ require:
   - rubocop-rspec
 
 AllCops:
-  TargetRubyVersion: 2.5
+  TargetRubyVersion: 2.6
 
 Bundler/OrderedGems:
   Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## [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)
+
+
+### Bug Fixes
+
+* check size of path segments against each configured route ([#3](https://github.com/matteoredz/rack-idempotency_key/issues/3)) ([248d6ca](https://github.com/matteoredz/rack-idempotency_key/commit/248d6cafbcb875781b0a3673db8561d31db464f7))
+
 ## 0.1.0 (2023-01-20)
 
 

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,11 +53,7 @@ module MyApp
 
     config.middleware.use(
       Rack::IdempotencyKey,
-      store: Rack::IdempotencyKey::MemoryStore.new,
-      routes: [
-        { path: "/posts",   method: "POST" },
-        { path: "/posts/*", method: "PATCH" }
-      ]
+      store: Rack::IdempotencyKey::MemoryStore.new
     )
   end
 end
@@ -68,8 +70,8 @@ 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
@@ -79,27 +81,57 @@ This one is the suggested store to use in production. It relies on the [redis ge
 ```ruby
 Rack::IdempotencyKey::RedisStore.new(Redis.current)
 
-# 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.current, 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:
@@ -112,21 +144,6 @@ 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" }
-]
-```
-
-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.

data/Rakefile

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

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"
@@ -24,4 +24,6 @@ Gem::Specification.new do |spec|
   spec.bindir = "exe"
   spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "redis", "~> 5.2"
 end

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,67 @@
 # frozen_string_literal: true
 
+require "redis"
+
 module Rack
   class IdempotencyKey
     class RedisStore
-      KEY_NAMESPACE = "idempotency_key"
+      DEFAULT_EXPIRATION = 300 # 5 minutes in seconds
 
-      def initialize(store, expires_in: 86_400)
+      def initialize(store, expires_in: DEFAULT_EXPIRATION)
         @store      = store
         @expires_in = expires_in
       end
 
       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)
+      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
+
+      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.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/rack/idempotency_key.rb

@@ -1,42 +1,44 @@
 # 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"
 
 # 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,30 @@
 --- !ruby/object:Gem::Specification
 name: rack-idempotency_key
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Matteo Rossi
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-01-20 00:00:00.000000000 Z
-dependencies: []
-description: 
+date: 2025-01-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+description:
 email:
 - mttrss5@gmail.com
 executables: []
@@ -18,13 +32,13 @@ 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"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -35,9 +49,11 @@ files:
 - bin/setup
 - 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 +62,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 +70,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/lib/rack/idempotency_key/idempotent_request.rb

@@ -1,80 +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)
-          same_segments? segments(route_path)
-        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