grape-idempotency 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e458d533c1b108959144d42615dcfbd9b85f741811a3150e0fd64a103469a734
+  data.tar.gz: 55a8de15e2332ff805edd7992dab11ff4bb14576b980ee71e7f699d83fcc6f11
+SHA512:
+  metadata.gz: 720d6987f1007f27656a769ef7cc945d04fbbe2355dac226a2dd38c801d935f674ab11c80409a6c850817ce8f641ecf2fc9d3ed5b7dc6fbe66ee61e664843ded
+  data.tar.gz: a4fe4ca95116844195429b7d54908aee357c59076095749420cce607dd87da005039e1096a436d85b82e7eaa58944c158910a41ec44780238915bbd22b9ab9cd

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+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.0] - 2023-01-03
+
+- Initial version

data/README.md

@@ -0,0 +1,196 @@
+# grape-idempotency 🍇🔁
+
+[![Gem Version](https://badge.fury.io/rb/grape-idempotency.svg)](https://badge.fury.io/rb/grape-idempotency)
+
+Gem for supporting idempotency in your [Grape](https://github.com/ruby-grape/grape) APIs.
+
+
+Topics covered in this README:
+
+- [Installation](#installation-)
+- [Basic Usage](#basic-usage-)
+- [How it works](#how-it-works-)
+- [Configuration](#configuration-)
+- [Changelog](#changelog)
+- [Contributing](#contributing)
+
+
+## Installation 🧗
+
+Ruby 2.6 or newer is required.
+[Grape](https://github.com/ruby-grape/grape) 1 or newer is required.
+
+`grape-idempotency` is available as a gem, to install it run:
+
+```bash
+gem install grape-idempotency
+```
+
+## Basic Usage 📖
+
+Configure the `Grape::Idempotency` class with a `Redis` instance.
+
+```ruby
+require 'redis'
+require 'grape-idempotency'
+
+redis = Redis.new(host: 'localhost', port: 6379)
+Grape::Idempotency.configure do |c|
+  c.storage = redis
+end
+```
+
+Now you can wrap your code inside the `idempotent` method:
+
+```ruby
+require 'grape'
+require 'grape-idempotency'
+
+class API < Grape::API
+    post '/payments' do
+      idempotent do
+        status 201
+        Payment.create!({
+          amount: params[:amount]
+        })
+      end
+    end
+  end
+end
+```
+
+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.
+
+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.
+
+To execute an idempotent request, simply request your user to include an extra `Idempotency-Key: <key>` header as part of his request.
+
+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.
+
+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 to your API's response, enabling you to trace back to the initial request that generated that specific response.
+
+## 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.
+
+### expires_in
+
+As we have mentioned in the [How it works](#how-it-works-) section, keys are automatically removed from the system if they are at least 24 hours old. However, a 24-hour timeframe may not be suitable for your project. To accommodate your specific needs, you can adjust this duration by using the `expires_in` parameter for configuration:
+
+```ruby
+Grape::Idempotency.configure do |c|
+  c.storage = @storage
+  c.expires_in = 1800
+end
+```
+
+So with the cofiguration above, the keys will expire in 30 minutes.
+
+### idempotency_key_header
+
+As outlined in the [How it works](#how-it-works-) section, in order to perform an idempotent request, you need to instruct your users to include an additional `Idempotency-Key: <key>` header with their request. However, if this header format doesn't align with your project requirements, you have the flexibility to configure the specific header that the gem will examine to determine idempotent behavior:
+
+```ruby
+Grape::Idempotency.configure do |c|
+  c.storage = @storage
+  c.idempotency_key_header = "x-custom-idempotency-key"
+end
+```
+
+Given the previous configuration, the gem will examine the `X-Custom-Idempotency-Key: <key>` for determine the idempotent behavior.
+
+### request_id_header
+
+By default, this gem stores a random hex value as identifier when storing the original request and returns it in all the subsequent requests that use the same idempotency-key as `Original-Request` header in the response.
+
+This value can be also provided by your consumer using the `X-Request-Id: <request-id>` header when performing the request to your API.
+
+However, if you prefer to use a different format for getting the request identifier, you can configure the header to check using the `request_id_header` parameter:
+
+```ruby
+Grape::Idempotency.configure do |c|
+  c.storage = @storage
+  c.request_id_header = "x-trace-id"
+end
+```
+
+In the case above, you request your consumers to use the `X-Trace-Id: <trace-id>` header when requesting your API.
+
+### 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:
+
+```json
+{
+
+  "error": "You are using the same idempotent key for two different requests"
+}
+```
+
+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.conflict_error_response = {
+    "type": "about:blank",
+    "status": 409,
+    "title": "Conflict",
+    "detail": "You are using the same idempotent key for two different requests"
+}
+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).
+
+## Contributing
+
+We welcome and appreciate contributions from the open-source community. Before you get started, please take a moment to review the guidelines below.
+
+### How to Contribute
+
+1. Fork the repository.
+2. Clone the repository to your local machine.
+3. Create a new branch for your contribution.
+4. Make your changes and ensure they meet project standards.
+5. Commit your changes with clear messages.
+6. Push your branch to your GitHub repository.
+7. Open a pull request in our repository.
+8. Participate in code review and address feedback.
+9. Once approved, your changes will be merged.
+
+### Development
+
+This project is dockerized, so be sure you have docker installed in your machine.
+
+Once you clone the repository, you can use the `Make` commands to build the project.
+
+```shell
+make build
+```
+
+You can pass the tests running:
+
+```shell
+make test
+```
+
+### Issue Tracker
+
+Open issues on the GitHub issue tracker with clear information.
+
+### Contributors
+
+*   Juan Carlos García - Creator - https://github.com/jcagarcia

data/Rakefile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/grape-idempotency.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.push File.expand_path('lib', __dir__)
+require 'grape/idempotency/version'
+
+Gem::Specification.new do |spec|
+  spec.name        = 'grape-idempotency'
+  spec.version     = Grape::Idempotency::VERSION
+  spec.authors     = ['Juan Carlos García']
+  spec.email       = ['jugade92@gmail.com']
+  spec.description = 'Add idempotency support to your Grape APIs for safely retrying requests without accidentally performing the same operation twice. When creating or updating an object, use an idempotency key. Then, if a connection error occurs, you can safely repeat the request without risk of creating a second object or performing the update twice.'
+  spec.summary     = 'Gem for supporting idempotency in your Grape APIs'
+  spec.homepage    = 'https://github.com/jcagarcia/grape-idempotency'
+  spec.license     = 'MIT'
+
+  files = Dir["lib/**/*.rb"]
+  rootfiles = ["CHANGELOG.md", "grape-idempotency.gemspec", "Rakefile", "README.md"]
+
+  spec.files = rootfiles + files
+  spec.executables = []
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = '>= 2.6'
+
+  spec.add_runtime_dependency 'grape', '>= 1'
+  
+  spec.add_development_dependency 'bundler', '>= 2.4'
+  spec.add_development_dependency 'rspec', '~> 3.12'
+  spec.add_development_dependency 'rack-test'
+  spec.add_development_dependency 'mock_redis', '~> 0.38'
+end

data/lib/grape/idempotency/helpers.rb

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

data/lib/grape/idempotency/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Grape
+  module Idempotency
+    VERSION = '0.1.0'
+  end
+end

data/lib/grape/idempotency.rb

@@ -0,0 +1,127 @@
+require 'grape'
+require 'securerandom'
+require 'grape/idempotency/version'
+
+module Grape
+  module Idempotency
+    autoload :Helpers, 'grape/idempotency/helpers'
+    Grape::Endpoint.send :include, Grape::Idempotency::Helpers
+
+    class << self
+      ORIGINAL_REQUEST_HEADER = "Original-Request".freeze
+
+      def configure(&block)
+        yield(configuration)
+      end
+
+      def restore_configuration
+        clean_configuration = Configuration.new
+        clean_configuration.storage = storage
+        @configuration = clean_configuration
+      end
+
+      def idempotent(grape, &block)
+        validate_config!
+
+        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
+          grape.status 409
+          return configuration.conflict_error_response.to_json
+        elsif cached_request
+          grape.status cached_request["status"]
+          grape.header(ORIGINAL_REQUEST_HEADER, cached_request["original_request"])
+          return cached_request["response"]
+        end
+
+        response = catch(:error) do
+          block.call
+        end
+
+        if response.is_a?(Hash)
+          response = response[:message].to_json
+        end
+
+        original_request_id = get_request_id(grape.request.headers)
+        grape.header(ORIGINAL_REQUEST_HEADER, original_request_id)
+        response
+      ensure
+        validate_config!
+        store_in_cache(idempotency_key, grape.request.params, grape.status, original_request_id, response) unless cached_request
+      end
+
+      private
+
+      def validate_config!
+        storage = configuration.storage
+
+        if storage.nil? || !storage.respond_to?(:set)
+          raise Configuration::Error.new("A Redis instance must be configured as cache storage")
+        end
+      end
+
+      def get_idempotency_key(headers)
+        idempotency_key = nil
+        headers.each do |key, value|
+          idempotency_key = value if key.downcase == configuration.idempotency_key_header.downcase
+        end
+        idempotency_key
+      end
+
+      def get_request_id(headers)
+        request_id = nil
+        headers.each do |key, value|
+          request_id = value if key.downcase == configuration.request_id_header.downcase
+        end
+        request_id || "req_#{SecureRandom.hex}"
+      end
+
+      def get_from_cache(idempotency_key)
+        value = storage.get(key(idempotency_key))
+        return unless value
+
+        JSON.parse(value)
+      end
+
+      def store_in_cache(idempotency_key, params, status, request_id, response)
+        body = {
+          params: params,
+          status: status,
+          original_request: request_id,
+          response: response
+        }.to_json
+        storage.set(key(idempotency_key), body, ex: configuration.expires_in)
+      end
+
+      def key(idempotency_key)
+        "grape:idempotency:#{idempotency_key}"
+      end
+
+      def storage
+        configuration.storage
+      end
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+    end
+
+    class Configuration
+      attr_accessor :storage, :expires_in, :idempotency_key_header, :request_id_header, :conflict_error_response
+
+      class Error < StandardError; end
+
+      def initialize
+        @storage = nil
+        @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"
+        }
+      end
+    end
+  end
+end

data/lib/grape-idempotency.rb

@@ -0,0 +1 @@
+require 'grape/idempotency'

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: grape-idempotency
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Juan Carlos García
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2023-11-03 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: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mock_redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.38'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.38'
+description: Add idempotency support to your Grape APIs for safely retrying requests
+  without accidentally performing the same operation twice. When creating or updating
+  an object, use an idempotency key. Then, if a connection error occurs, you can safely
+  repeat the request without risk of creating a second object or performing the update
+  twice.
+email:
+- jugade92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- Rakefile
+- grape-idempotency.gemspec
+- lib/grape-idempotency.rb
+- lib/grape/idempotency.rb
+- lib/grape/idempotency/helpers.rb
+- lib/grape/idempotency/version.rb
+homepage: https://github.com/jcagarcia/grape-idempotency
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key: 
+specification_version: 4
+summary: Gem for supporting idempotency in your Grape APIs
+test_files: []