grape-idempotency 0.1.3 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f9a4d3d3a6e885bfa07afd8f0d51dfbfe930853d3919934016e9173f9d418a0
-  data.tar.gz: 81e8817b09d72d35bb71746a3451e66aed12af38888b169abc0297bb2c3f7481
+  metadata.gz: 115100d8cd1141c7c801a1501ede2db9eff3419a5b2974de93c4b79e7c812fd2
+  data.tar.gz: 567472c4ab8ad2aae2561d7af0e808c803a025caae34f75492c2b889b6468d7e
 SHA512:
-  metadata.gz: 20a9654e3b1086a7dfa77379129f7bc46d18df4eadfa85ee13e7027dd91ffc6f68b83843f0d41212695287b472ebcb6e7c9b68ac322bb46f8ddadbdb9294a6ad
-  data.tar.gz: 60fc291bbc9558e19b2816614f0584812e08b6846b17b68af7395d15665439cad756034ff4f64d59592f56626d4fa0d5381f8dbcfc91b91294e5d223c8d4a8da
+  metadata.gz: fde07abe226552ba88086f20fcece9778ef13ee04c17c27376aea2d13386955944caea65ae28ff1d2abdda72bc501600a9afb107229e6da47b4dd02a56b2e5f5
+  data.tar.gz: 3a9a9fcd8f30d5f1deab9da2c719c54c1a0cbecafb5ce3b1196301bc60983bd3271153f4b02fed795d49d4188255507e0a8445d1fdd37cad1bbe0a0851b32e48

data/CHANGELOG.md

@@ -4,31 +4,59 @@ All changes to `grape-idempotency` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.3] - 2023-01-07
+## [1.1.0] - (Next)
 
 ### Fix
 
-- Second calls were returning `null` when the first response was generated inside a `rescue_from`.
-- Conflict response had invalid format.
+* Your contribution here.
 
-## [0.1.2] - 2023-01-06
+### Changed
+
+* Your contribution here.
+
+### Feature
+
+* [#20](https://github.com/jcagarcia/grape-idempotency/pull/20): Manage `Redis` exceptions by default and allow the gem's consumer to manage them by itself - [@jcagarcia](https://github.com/jcagarcia).
+* Your contribution here.
+
+## [1.0.0] - 2023-11-23
+
+### Changed
+
+* [#11](https://github.com/jcagarcia/grape-idempotency/pull/11): Changing error response formats - [@Flip120](https://github.com/Flip120).
+* [#16](https://github.com/jcagarcia/grape-idempotency/pull/16): Changing error response code to 422 for conflict - [@Flip120](https://github.com/Flip120).
+
+### Feature
+
+* [#11](https://github.com/jcagarcia/grape-idempotency/pull/11): Return 409 conflict when a request is still being processed - [@Flip120](https://github.com/Flip120).
+* [#15](https://github.com/jcagarcia/grape-idempotency/pull/15): Allow to mark the idempotent header as required - [@jcagarcia](https://github.com/jcagarcia).
+* [#17](https://github.com/jcagarcia/grape-idempotency/pull/17): Allow to configure logger - [@jcagarcia](https://github.com/jcagarcia).
+
+## [0.1.3] - 2023-11-07
+
+### Fix
+
+* [#9](https://github.com/jcagarcia/grape-idempotency/pull/9): Second calls were returning `null` when the first response was generated inside a `rescue_from`. - [@jcagarcia](https://github.com/jcagarcia).
+- [#9](https://github.com/jcagarcia/grape-idempotency/pull/9): Conflict response had invalid format. - [@jcagarcia](https://github.com/jcagarcia).
+
+## [0.1.2] - 2023-11-06
 
 ### Fix
 
-- Return correct original response when the endpoint returns a hash in the body
+* [#5](https://github.com/jcagarcia/grape-idempotency/pull/5): Return correct original response when the endpoint returns a hash in the body - [@jcagarcia](https://github.com/jcagarcia).
 
-## [0.1.1] - 2023-01-06
+## [0.1.1] - 2023-11-06
 
 ### Fix
 
-- Return `409 - Conflict` response if idempotency key is provided for same query and body parameters BUT different endpoints.
-- Use `nx: true` when storing the original request in the Redis storage for only setting the key if it does not already exist.
+* [#4](https://github.com/jcagarcia/grape-idempotency/pull/4): Return `409 - Conflict` response if idempotency key is provided for same query and body parameters BUT different endpoints. - [@jcagarcia](https://github.com/jcagarcia).
+* [#4](https://github.com/jcagarcia/grape-idempotency/pull/4): Use `nx: true` when storing the original request in the Redis storage for only setting the key if it does not already exist. - [@jcagarcia](https://github.com/jcagarcia).
 
 ### Changed
 
-- Include `idempotency-key` in the response headers
-  - In the case of a concurrency error when storing the request into the redis storage (because now `nx: true`), a new idempotency key will be generated, so the consumer can check the new one seeing the headers.
+* [#4](https://github.com/jcagarcia/grape-idempotency/pull/4): Include `idempotency-key` in the response headers - [@jcagarcia](https://github.com/jcagarcia).
+  * In the case of a concurrency error when storing the request into the redis storage (because now `nx: true`), a new idempotency key will be generated, so the consumer can check the new one seeing the headers.
 
-## [0.1.0] - 2023-01-03
+## [0.1.0] - 2023-11-03
 
-- Initial version
+* [#1](https://github.com/jcagarcia/grape-idempotency/pull/1): Initial version - [@jcagarcia](https://github.com/jcagarcia).

data/README.md

@@ -5,11 +5,15 @@
 
 Gem for supporting idempotency in your [Grape](https://github.com/ruby-grape/grape) APIs.
 
+Implementation based on the Active Internet-Draft [draft-ietf-httpapi-idempotency-key-header-04](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/04/)
+
 Topics covered in this README:
 
 - [Installation](#installation-)
 - [Basic Usage](#basic-usage-)
 - [How it works](#how-it-works-)
+  - [Making idempotency key header mandatory](#making-idempotency-key-header-mandatory-)
+  - [Redis Storage Connectivity Issue](#redis-storage-connectivity-issue)
 - [Configuration](#configuration-)
 - [Changelog](#changelog)
 - [Contributing](#contributing)
@@ -63,7 +67,7 @@ That's all! 🚀
 
 ## How it works 🤔
 
-Once you've set up the gem and enclosed your endpoint code within the `idempotent` method, your endpoint will exhibit idempotent behavior, but this will only occur if the consumer of the endpoint includes an idempotency key in their request.
+Once you've set up the gem and enclosed your endpoint code within the `idempotent` method, your endpoint will exhibit idempotent behavior, but this will only occur if the consumer of the endpoint includes an idempotency key in their request. (If you want to make the idempotency key header mandatory for your endpoint, check [How to make idempotency key header mandatory](#making-idempotency-key-header-mandatory-) section)
 
 This key allows your consumer to make the same request again in case of a connection error, without the risk of creating a duplicate object or executing the update twice.
 
@@ -71,12 +75,76 @@ To execute an idempotent request, simply request your user to include an extra `
 
 This gem operates by storing the initial request's status code and response body, regardless of whether the request succeeded or failed, using a specific idempotency key. Subsequent requests with the same key will consistently yield the same result, even if there were 500 errors.
 
-Keys are automatically removed from the system if they are at least 24 hours old, and a new request is generated when a key is reused after the original has been removed. The idempotency layer compares incoming parameters to those of the original request and returns a `409 - Conflict` status code if they don't match, preventing accidental misuse.
+Keys are automatically removed from the system if they are at least 24 hours old, and a new request is generated when a key is reused after the original has been removed. The idempotency layer compares incoming parameters to those of the original request and returns a `422 - Unprocessable Entity` status code if they don't match, preventing accidental misuse.
+If a request is received while another one with the same idempotency key is still being processed the idempotency layer returns a `409 - Conflict` status
 
 Results are only saved if an API endpoint begins its execution. If incoming parameters fail validation or if the request conflicts with another one executing concurrently, no idempotent result is stored because no API endpoint has initiated execution. In such cases, retrying these requests is safe.
 
 Additionally, this gem automatically appends the `Original-Request` header and the `Idempotency-Key` header to your API's response, enabling you to trace back to the initial request that generated that specific response.
 
+### Making idempotency key header mandatory ⚠️
+
+For some endpoints, you want to enforce your consumers to provide idempotency key. So, when wrapping the code inside the `idempotent` method, you can mark it as `required`:
+
+```ruby
+require 'grape'
+require 'grape-idempotency'
+
+class API < Grape::API
+    post '/payments' do
+      idempotent(required: true) do
+        status 201
+        Payment.create!({
+          amount: params[:amount]
+        })
+      end
+    end
+  end
+end
+```
+
+If the Idempotency-Key request header is missing for a idempotent operation requiring this header, the gem will reply with an HTTP 400 status code with the following body:
+
+```json
+{
+  "title": "Idempotency-Key is missing",
+  "detail": "This operation is idempotent and it requires correct usage of Idempotency Key.",
+}
+```
+
+If you want to change the error message returned in this scenario, check [How to configure idempotency key missing error message](#mandatory_header_response) section.
+
+### Redis Storage Connectivity Issue
+
+By default, `Redis` exceptions are not handled by the `grape-idempotency` gem.
+
+Therefore, if an exception arises while attempting to read, write or delete data from the `Redis` storage, the gem will re-raise the identical exception to your application. Thus, you will be responsible for handling it within your own code, such as:
+
+```ruby
+require 'grape'
+require 'grape-idempotency'
+
+class API < Grape::API
+    post '/payments' do
+      begin
+        idempotent do
+          status 201
+          Payment.create!({
+            amount: params[:amount]
+          })
+        end
+      rescue Redis::BaseError => e
+        error!("Redis error! Idempotency is very important here and we cannot continue.", 500)
+      end
+    end
+  end
+end
+```
+
+If you want to avoid this functionality, and you want the gem handles the potential `Redis` exceptions, you have the option to configure the gem for handling these `Redis` exceptions. Please refer to the [manage_redis_exceptions](#manage_redis_exceptions) configuration property.
+
+🚨 WARNING: If a `Redis` exception appears AFTER performing the wrapped code, nothing will be re-raised. The process will continue working and the response will be returned to the consumer of your API. However, a `409 Conflict` response can be returned to your consumer if it retried the same call with the same idempotency key. This is because the gem was not able to associate the response of the original request to the original idempotency key because those connectivity issues.
+
 ## Configuration 🪚
 
 In addition to the storage aspect, you have the option to supply additional configuration details to tailor the gem to the specific requirements of your project.
@@ -124,6 +192,56 @@ end
 
 In the case above, you request your consumers to use the `X-Trace-Id: <trace-id>` header when requesting your API.
 
+### logger, logger_level and logger_prefix
+
+By default, the logger used by the gem is configured like `Logger.new(STDOUT)` and `INFO` level. As this gem does not log any message with `INFO` level, only `ERROR` messages will be logged.
+
+
+If you want to provide your own logger, you want to change the level to `DEBUG` or you want to provide your own prefix, you can configure the gem like:
+
+```ruby
+Grape::Idempotency.configure do |c|
+  c.storage = @storage
+  c.logger = Infrastructure::MyLogger.new
+  c.logger_level = :debug
+  c.logger_prefix = '[my-own-prefix]'
+end
+```
+
+An example of the logged information when changing the level of the log to `DEBUG` and customizing the `logger_prefix`:
+
+```shell
+I, [2023-11-23T22:41:39.148163 #1]  DEBUG -- : [my-own-prefix] Performing endpoint "/payments" with idempotency.
+I, [2023-11-23T22:41:39.148176 #1]  DEBUG -- : [my-own-prefix] Idempotency key is NOT mandatory for this endpoint.
+I, [2023-11-23T22:41:39.148192 #1]  DEBUG -- : [my-own-prefix] Idempotency key received in request header "x-custom-idempotency-key" => "fd77c9d6-b7da-4966-aac8-40ee258f24aa"
+I, [2023-11-23T22:41:39.148210 #1]  DEBUG -- : [my-own-prefix] Previous request information has NOT been found for the provided idempotency key.
+I, [2023-11-23T22:41:39.148248 #1]  DEBUG -- : [my-own-prefix] Request stored as processing.
+I, [2023-11-23T22:41:39.148261 #1]  DEBUG -- : [my-own-prefix] Performing the provided block.
+I, [2023-11-23T22:41:39.148268 #1]  DEBUG -- : [my-own-prefix] Block has been performed.
+I, [2023-11-23T22:41:39.148287 #1]  DEBUG -- : [my-own-prefix] Storing response.
+I, [2023-11-23T22:41:39.148317 #1]  DEBUG -- : [my-own-prefix] Response stored.
+I, [2023-11-23T22:41:39.148473 #1]  DEBUG -- : [my-own-prefix] Performing endpoint "/payments" with idempotency.
+I, [2023-11-23T22:41:39.148486 #1]  DEBUG -- : [my-own-prefix] Idempotency key is NOT mandatory for this endpoint.
+I, [2023-11-23T22:41:39.148502 #1]  DEBUG -- : [my-own-prefix] Idempotency key received in request header "x-custom-idempotency-key" => "fd77c9d6-b7da-4966-aac8-40ee258f24aa"
+I, [2023-11-23T22:41:39.148523 #1]  DEBUG -- : [my-own-prefix] Request has been found for the provided idempotency key => {"path"=>"/payments", "params"=>{"locale"=>"undefined", "{\"amount\":10000}"=>nil}, "status"=>500, "original_request"=>"wadus", "response"=>"{\"error\":\"Internal Server Error\"}"}
+I, [2023-11-23T22:41:39.148537 #1]  DEBUG -- : [my-own-prefix] Returning the response from the original request.
+```
+
+### manage_redis_exceptions
+
+By default, the `grape-idempotency` gem is configured to re-raise `Redis` exceptions.
+
+If you want to delegate the `Redis` exception management into the gem, you can configure it using the `manage_redis_exceptions` configuration property.
+
+```ruby
+Grape::Idempotency.configure do |c|
+  c.storage = @storage
+  c.manage_redis_exceptions = true
+end
+```
+
+However, this approach carries a certain level of risk. In the case that `Redis` experiences an outage, the idempotent functionality will be lost, the endpoint will behave as no idempotent, and this issue may go unnoticed.
+
 ### conflict_error_response
 
 When providing a `Idempotency-Key: <key>` header, this gem compares incoming parameters to those of the original request (if exists) and returns a `409 - Conflict` status code if they don't match, preventing accidental misuse. The response body returned by the gem looks like:
@@ -131,7 +249,8 @@ When providing a `Idempotency-Key: <key>` header, this gem compares incoming par
 ```json
 {
 
-  "error": "You are using the same idempotent key for two different requests"
+  "title": "Idempotency-Key is already used",
+  "detail": "This operation is idempotent and it requires correct usage of Idempotency Key. Idempotency Key MUST not be reused across different payloads of this operation."
 }
 ```
 
@@ -151,6 +270,61 @@ end
 
 In the configuration above, the error is following the [RFC-7807](https://datatracker.ietf.org/doc/html/rfc7807) format.
 
+### processing_response
+
+When a request with a `Idempotency-Key: <key>` header is performed while a previous one still on going with the same idempotency value, this gem returns a `409 - Conflict` status. The response body returned by the gem looks like:
+
+```json
+{
+
+  "title": "A request is outstanding for this Idempotency-Key",
+  "detail": "A request with the same idempotent key for the same operation is being processed or is outstanding."
+}
+```
+
+You have the option to specify the desired response body to be returned to your users when this error occurs. This allows you to align the error format with the one used in your application.
+
+```ruby
+Grape::Idempotency.configure do |c|
+  c.storage = @storage
+  c.processing_response = {
+    "type": "about:blank",
+    "status": 409,
+    "title": "A request is still being processed",
+    "detail": "A request with the same idempotent key is being procesed"
+}
+end
+```
+
+In the configuration above, the error is following the [RFC-7807](https://datatracker.ietf.org/doc/html/rfc7807) format.
+
+### mandatory_header_response
+
+If the Idempotency-Key request header is missing for a idempotent operation requiring this header, the gem will reply with an HTTP 400 status code with the following body:
+
+```json
+{
+  "title": "Idempotency-Key is missing",
+  "detail": "This operation is idempotent and it requires correct usage of Idempotency Key.",
+}
+```
+
+You have the option to specify the desired response body to be returned to your users when this error occurs. This allows you to align the error format with the one used in your application.
+
+```ruby
+Grape::Idempotency.configure do |c|
+  c.storage = @storage
+  c.mandatory_header_response = {
+    "type": "about:blank",
+    "status": 400,
+    "title": "Idempotency-Key is missing",
+    "detail": "Please, provide a valid idempotent key in the headers for performing this operation"
+}
+end
+```
+
+In the configuration above, the error is following the [RFC-7807](https://datatracker.ietf.org/doc/html/rfc7807) format.
+
 ## Changelog
 
 If you're interested in seeing the changes and bug fixes between each version of `grape-idempotency`, read the [Changelog](https://github.com/jcagarcia/grape-idempotency/blob/main/CHANGELOG.md).
@@ -193,4 +367,5 @@ Open issues on the GitHub issue tracker with clear information.
 
 ### Contributors
 
-*   Juan Carlos García - Creator - https://github.com/jcagarcia
+* Juan Carlos García - Creator - https://github.com/jcagarcia
+* Carlos Cabanero - Contributor - https://github.com/Flip120

data/grape-idempotency.gemspec

@@ -22,7 +22,8 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = '>= 2.6'
 
-  spec.add_runtime_dependency 'grape', '~> 1'
+  spec.add_runtime_dependency 'grape', '>= 1'
+  spec.add_runtime_dependency 'redis', '>= 4'
   
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rspec'

data/lib/grape/idempotency/helpers.rb

@@ -1,8 +1,8 @@
 module Grape
   module Idempotency
     module Helpers
-      def idempotent(&block)
-        Grape::Idempotency.idempotent(self) do
+      def idempotent(required: false, &block)
+        Grape::Idempotency.idempotent(self, required: required) do
           block.call
         end
       end

data/lib/grape/idempotency/middleware/error.rb

@@ -3,14 +3,18 @@ require 'grape/middleware/base'
 module Grape
   module Middleware
     class Error < Base
-      def run_rescue_handler(handler, error)
+      def run_rescue_handler(handler, error, endpoint=nil)
         if handler.instance_of?(Symbol)
           raise NoMethodError, "undefined method '#{handler}'" unless respond_to?(handler)
 
           handler = public_method(handler)
         end
 
-        response = handler.arity.zero? ? instance_exec(&handler) : instance_exec(error, &handler)
+        if endpoint
+          response = handler.arity.zero? ? endpoint.instance_exec(&handler) : endpoint.instance_exec(error, &handler)
+        else
+          response = handler.arity.zero? ? instance_exec(&handler) : instance_exec(error, &handler)
+        end
 
         if response.is_a?(Rack::Response)
           update_idempotency_error_with(error, response)

data/lib/grape/idempotency/version.rb

@@ -2,6 +2,6 @@
 
 module Grape
   module Idempotency
-    VERSION = '0.1.3'
+    VERSION = '1.1.0'
   end
 end

data/lib/grape/idempotency.rb

@@ -1,4 +1,6 @@
 require 'grape'
+require 'redis'
+require 'logger'
 require 'securerandom'
 require 'grape/idempotency/version'
 require 'grape/idempotency/middleware/error'
@@ -21,46 +23,86 @@ module Grape
         @configuration = clean_configuration
       end
 
-      def idempotent(grape, &block)
+      def idempotent(grape, required: false, &block)
         validate_config!
+        log(:debug, "Performing endpoint \"#{grape.request.path}\" with idempotency.")
+        log(:debug, "Idempotency key is #{!required ? 'NOT' : ''} mandatory for this endpoint.")
 
         idempotency_key = get_idempotency_key(grape.request.headers)
-        return block.call unless idempotency_key
-
-        cached_request = get_from_cache(idempotency_key)
-        if cached_request && (cached_request["params"] != grape.request.params || cached_request["path"] != grape.request.path)
-          grape.status 409
-          return configuration.conflict_error_response
-        elsif cached_request
-          grape.status cached_request["status"]
-          grape.header(ORIGINAL_REQUEST_HEADER, cached_request["original_request"])
+        log(:debug, "Idempotency key received in request header \"#{configuration.idempotency_key_header.downcase}\" => \"#{idempotency_key}\"") if idempotency_key
+
+        grape.error!(configuration.mandatory_header_response, 400) if required && !idempotency_key
+        return block.call if !idempotency_key
+
+        stored_request = get_from_storage(idempotency_key)
+        log(:debug, "Request has been found for the provided idempotency key => #{stored_request}") if stored_request
+        if stored_request && (stored_request["params"] != grape.request.params || stored_request["path"] != grape.request.path)
+          log(:debug, "Request has conflicts. Same params? => #{stored_request["params"] != grape.request.params}. Same path? => #{stored_request["path"] != grape.request.path}")
+          log(:debug, "Returning conflict error response.")
+          grape.error!(configuration.conflict_error_response, 422)
+        elsif stored_request && stored_request["processing"] == true
+          log(:debug, "Returning processing error response.")
+          grape.error!(configuration.processing_response, 409)
+        elsif stored_request
+          log(:debug, "Returning the response from the original request.")
+          grape.status stored_request["status"]
+          grape.header(ORIGINAL_REQUEST_HEADER, stored_request["original_request"])
           grape.header(configuration.idempotency_key_header, idempotency_key)
-          return cached_request["response"]
+          return stored_request["response"]
         end
 
+        log(:debug, "Previous request information has NOT been found for the provided idempotency key.")
+
+        original_request_id = get_request_id(grape.request.headers)
+        success = store_processing_request(idempotency_key, grape.request.path, grape.request.params, original_request_id)
+        if !success
+          log(:error, "Request NOT stored as processing. Concurrent requests for the same idempotency key appeared.")
+          grape.error!(configuration.processing_response, 409)
+        else
+          log(:debug, "Request stored as processing.")
+        end
+
+        log(:debug, "Performing the provided block.")
+
         response = catch(:error) do
           block.call
         end
 
-        response = response[:message] if is_an_error?(response)
+        log(:debug, "Block has been performed.")
+
+        if is_an_error?(response)
+          log(:debug, "An error response was returned by the performed block. => #{response}")
+          response = response[:message]
+        end
 
-        original_request_id = get_request_id(grape.request.headers)
         grape.header(ORIGINAL_REQUEST_HEADER, original_request_id)
         grape.body response
+      rescue Redis::BaseError => e
+        raise
       rescue => e
-        if !cached_request && !response
+        log(:debug, "An unexpected error was raised when performing the block.")
+        if !stored_request && !response
           validate_config!
+          log(:debug, "Storing error response.")
           original_request_id = get_request_id(grape.request.headers)
           stored_key = store_error_request(idempotency_key, grape.request.path, grape.request.params, grape.status, original_request_id, e)
-          grape.header(ORIGINAL_REQUEST_HEADER, original_request_id)
-          grape.header(configuration.idempotency_key_header, stored_key)
+          if stored_key
+            log(:debug, "Error response stored.")
+            grape.header(ORIGINAL_REQUEST_HEADER, original_request_id)
+            grape.header(configuration.idempotency_key_header, stored_key)
+          end
         end
+        log(:debug, "Re-raising the error.")
         raise
       ensure
-        if !cached_request && response
+        if !stored_request && response
           validate_config!
-          stored_key = store_request(idempotency_key, grape.request.path, grape.request.params, grape.status, original_request_id, response)
-          grape.header(configuration.idempotency_key_header, stored_key)
+          log(:debug, "Storing response.")
+          stored_key = store_request_response(idempotency_key, grape.request.path, grape.request.params, grape.status, original_request_id, response)
+          if stored_key
+            log(:debug, "Response stored.")
+            grape.header(configuration.idempotency_key_header, stored_key)
+          end
         end
       end
 
@@ -76,18 +118,24 @@ module Grape
         params = request_with_unmanaged_error["params"]
         original_request_id = request_with_unmanaged_error["original_request"]
 
-        store_request(idempotency_key, path, params, status, original_request_id, response)
+        store_request_response(idempotency_key, path, params, status, original_request_id, response)
         storage.del(stored_error[:error_key])
+      rescue Redis::BaseError => e
+        log(:error, "Storage error => #{e.message} - #{e}")
+        nil
       end
 
       private
 
       def validate_config!
-        storage = configuration.storage
+        raise Configuration::Error.new("A Redis instance must be configured as cache storage") unless valid_storage?
+      end
 
-        if storage.nil? || !storage.respond_to?(:set)
-          raise Configuration::Error.new("A Redis instance must be configured as cache storage")
-        end
+      def valid_storage?
+        configuration.storage &&
+        configuration.storage.respond_to?(:get) &&
+        configuration.storage.respond_to?(:set) &&
+        configuration.storage.respond_to?(:del)
       end
 
       def get_idempotency_key(headers)
@@ -106,29 +154,46 @@ module Grape
         request_id || "req_#{SecureRandom.hex}"
       end
 
-      def get_from_cache(idempotency_key)
+      def get_from_storage(idempotency_key)
         value = storage.get(key(idempotency_key))
         return unless value
 
         JSON.parse(value)
+      rescue Redis::BaseError => e
+        log(:error, "Storage error => #{e.message} - #{e}")
+        return if configuration.manage_redis_exceptions
+        raise
       end
 
-      def store_request(idempotency_key, path, params, status, request_id, response)
+      def store_processing_request(idempotency_key, path, params, request_id)
+        body = {
+          path: path,
+          params: params,
+          original_request: request_id,
+          processing: true
+        }
+
+        storage.set(key(idempotency_key), body.to_json, ex: configuration.expires_in, nx: true)
+      rescue Redis::BaseError => e
+        return true if configuration.manage_redis_exceptions
+        raise
+      end
+
+      def store_request_response(idempotency_key, path, params, status, request_id, response)
         body = {
           path: path,
           params: params,
           status: status,
           original_request: request_id,
           response: response
-        }.to_json
+        }
 
-        result = storage.set(key(idempotency_key), body, ex: configuration.expires_in, nx: true)
+        storage.set(key(idempotency_key), body.to_json, ex: configuration.expires_in, nx: false)
 
-        if !result
-          return store_request(random_idempotency_key, path, params, status, request_id, response)
-        else
-          return idempotency_key
-        end
+        idempotency_key
+      rescue Redis::BaseError => e
+        log(:error, "Storage error => #{e.message} - #{e}")
+        idempotency_key
       end
 
       def store_error_request(idempotency_key, path, params, status, request_id, error)
@@ -143,13 +208,12 @@ module Grape
           }
         }.to_json
 
-        result = storage.set(error_key(idempotency_key), body, ex: 30, nx: true)
+        storage.set(error_key(idempotency_key), body, ex: 30, nx: false)
 
-        if !result
-          return store_error_request(random_idempotency_key, path, params, status, request_id, error)
-        else
-          return idempotency_key
-        end
+        idempotency_key
+      rescue Redis::BaseError => e
+        log(:error, "Storage error => #{e.message} - #{e}")
+        idempotency_key
       end
 
       def get_error_request_for(error)
@@ -169,6 +233,9 @@ module Grape
             }
           end
         end.first
+      rescue Redis::BaseError => e
+        log(:error, "Storage error => #{e.message} - #{e}")
+        nil
       end
 
       def is_an_error?(response)
@@ -191,37 +258,54 @@ module Grape
         "grape:idempotency:"
       end
 
-      def random_idempotency_key
-        tentative_key = SecureRandom.uuid
-        already_existing_key = storage.get(key(tentative_key))
-        if already_existing_key
-          return random_idempotency_key
-        else
-          return tentative_key
-        end
-      end
-
       def storage
         configuration.storage
       end
 
+      def log(level, msg)
+        logger.send(level, "#{configuration.logger_prefix} #{msg}")
+      end
+
+      def logger
+        return @logger if @logger
+
+        @logger = configuration.logger
+        @logger.level = configuration.logger_level
+        @logger
+      end
+
       def configuration
         @configuration ||= Configuration.new
       end
     end
 
     class Configuration
-      attr_accessor :storage, :expires_in, :idempotency_key_header, :request_id_header, :conflict_error_response
+      attr_accessor :storage, :logger, :logger_level, :logger_prefix, :expires_in, :idempotency_key_header,
+        :request_id_header, :conflict_error_response, :processing_response, :mandatory_header_response,
+        :manage_redis_exceptions
 
       class Error < StandardError; end
 
       def initialize
         @storage = nil
+        @logger = Logger.new(STDOUT)
+        @logger_level = Logger::INFO
+        @logger_prefix = "[grape-idempotency]"
         @expires_in = 216_000
         @idempotency_key_header = "idempotency-key"
         @request_id_header = "x-request-id"
-        @conflict_error_response = { 
-          "error" => "You are using the same idempotent key for two different requests"
+        @manage_redis_exceptions = false
+        @conflict_error_response = {
+          "title" => "Idempotency-Key is already used",
+          "detail" => "This operation is idempotent and it requires correct usage of Idempotency Key. Idempotency Key MUST not be reused across different payloads of this operation."
+        }
+        @processing_response = {
+          "title" => "A request is outstanding for this Idempotency-Key",
+          "detail" => "A request with the same idempotent key for the same operation is being processed or is outstanding."
+        }
+        @mandatory_header_response = {
+          "title" => "Idempotency-Key is missing",
+          "detail" => "This operation is idempotent and it requires correct usage of Idempotency Key."
         }
       end
     end

metadata

@@ -1,29 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: grape-idempotency
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 1.1.0
 platform: ruby
 authors:
 - Juan Carlos García
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-11-07 00:00:00.000000000 Z
+date: 2023-12-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1'
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement