rack-idempotency_key 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9358732d434938ba1444636f644cb3d8a161e95aa913e2c60e62f77b74cc635c
+  data.tar.gz: 9862a6bcb70d4bb24bcb85ae6eaf07265116ecdddcdede65ba6b8effcbb2155a
+SHA512:
+  metadata.gz: 78e77d1c68c3df1f39edd5df9e2a53e169e6dd4057fcc8cb1f01ec659d16e33a7c59c290596828ab98159ee2e90f8168986f9aaf668f99b547bc4bced6bf4949
+  data.tar.gz: 3c5c345ccd361084b39d86b7ec4458240aaa9b02f399e53bad9e4fe06296ed7d4718ddd262c60adb00096f285a8540ecc493606a703a1257332ecccb349067aa

data/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @matteoredz

data/.github/workflows/lint.yml

@@ -0,0 +1,20 @@
+name: Lint
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+          ruby-version: 2.5.0
+      - run: bundle install
+      - run: bundle exec rubocop

data/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: google-github-actions/release-please-action@v3
+        id: release
+        with:
+          package-name: rack-idempotency_key
+          release-type: ruby
+          token: ${{secrets.GITHUB_TOKEN}}
+          version-file: "lib/rack/idempotency_key/version.rb"
+      - uses: actions/checkout@v3
+        if: ${{steps.release.outputs.release_created}}
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+          ruby-version: 2.7.0
+        if: ${{steps.release.outputs.release_created}}
+      - run: bundle install
+        if: ${{steps.release.outputs.release_created}}
+      - run: ./bin/release
+        env:
+          RUBYGEMS_API_KEY: ${{secrets.RUBYGEMS_API_KEY}}
+        if: ${{steps.release.outputs.release_created}}

data/.github/workflows/test.yml

@@ -0,0 +1,25 @@
+name: Test
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    continue-on-error: ${{ endsWith(matrix.ruby, 'head') || matrix.ruby == 'debug' }}
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [2.5, 2.6, 2.7, '3.0', 3.1, head]
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+          ruby-version: ${{ matrix.ruby }}
+      - run: bundle install
+      - run: bundle exec rake

data/.gitignore

@@ -0,0 +1,15 @@
+*.rbc
+*.swp
+/_yardoc/
+/.bundle/
+/.byebug_history
+/.yardoc
+/.ruby-version
+/coverage/
+/doc/
+/dump.rdb
+/Gemfile.lock
+/pkg/
+/rack-idempotency_key-*.gem
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,51 @@
+---
+require:
+  - rubocop-performance
+  - rubocop-rake
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 2.5
+
+Bundler/OrderedGems:
+  Enabled: false
+
+Layout/EmptyLineBetweenDefs:
+  Enabled: true
+  AllowAdjacentOneLineDefs: true
+
+Layout/IndentationConsistency:
+  Enabled: true
+  EnforcedStyle: indented_internal_methods
+
+Layout/LineLength:
+  Enabled: true
+  Max: 100
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: true
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/ClassLength:
+  Enabled: true
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/MethodLength:
+  Enabled: true
+  CountAsOne: ['array', 'hash']
+
+RSpec/MultipleMemoizedHelpers:
+  Max: 10
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+...

data/.travis.yml

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

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 (2023-01-20)
+
+
+### Miscellaneous Chores
+
+* release as 0.1.0 ([13a2d30](https://github.com/matteoredz/rack-idempotency_key/commit/13a2d30f0ed0de82a8e94b0526c70adb6411e79e))

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at mttrss5@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [https://contributor-covenant.org/version/1/4][version]
+
+[homepage]: https://contributor-covenant.org
+[version]: https://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "byebug"
+gem "mock_redis"
+gem "rack-test"
+gem "rake"
+gem "rspec"
+gem "rubocop"
+gem "rubocop-performance"
+gem "rubocop-rake"
+gem "rubocop-rspec"
+gem "simplecov"
+gem "timecop"

data/README.md

@@ -0,0 +1,150 @@
+# `Rack::IdempotencyKey`
+
+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?
+
+Idempotency is a design principle that allows a client to safely retry API requests that might have failed due to connection issues, without causing duplication or conflicts. In other words, no matter how many times you perform an idempotent operation, the end result will always be the same.
+
+To be idempotent, only the state of the server is considered. The response returned by each request may differ: for example, the first call of a `DELETE` will likely return a `200`, while successive ones will likely return a `404`.
+
+`POST`, `PATCH` and `CONNECT` are the non-idempotent methods, and this gem exists to make them so.
+
+## 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 response with a `400` (BadRequest) HTTP status code isn't cached
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "rack-idempotency_key"
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install rack-idempotency_key
+
+## General usage
+
+You may use this Rack Middleware in any application that conforms to the [Rack Specification](https://github.com/rack/rack/blob/main/SPEC.rdoc). Please refer to the specific application's guidelines.
+
+## Usage with Rails
+
+```ruby
+# config/application.rb
+
+module MyApp
+  class Application < Rails::Application
+    # ...
+
+    config.middleware.use(
+      Rack::IdempotencyKey,
+      store: Rack::IdempotencyKey::MemoryStore.new,
+      routes: [
+        { path: "/posts",   method: "POST" },
+        { path: "/posts/*", method: "PATCH" }
+      ]
+    )
+  end
+end
+```
+
+## Available Stores
+
+The Store is responsible for getting and setting the response from a cache of a given idempotent request.
+
+### MemoryStore
+
+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)
+```
+
+### RedisStore
+
+This one is the suggested store to use in production. It relies on the [redis gem](https://github.com/redis/redis-rb).
+
+```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)
+```
+
+Every key written to Redis will get prefixed with `idempotency_key` to avoid conflicts on shared instances.
+
+### Custom Store
+
+Any object that conforms to the following interface can be used as a custom Store:
+
+```ruby
+# @param [String] key
+#
+# @return [Array]
+def get(key)
+
+# @param [String] key
+# @param [Array]  value
+#
+# @return [Array]
+def set(key, value)
+```
+
+The Array returned must conform to the [Rack Specification](https://github.com/rack/rack/blob/main/SPEC.rdoc), as follows:
+
+```ruby
+[
+  200, # Response code
+  {},  # Response headers
+  []   # Response body
+]
+```
+
+## 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.
+Then, run `rake test` 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.
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected
+to adhere to the [code of conduct](https://github.com/matteoredz/rack-idempotency_key/blob/master/CODE_OF_CONDUCT.md).
+
+## Code of Conduct
+
+Everyone interacting in the `Rack::IdempotencyKey` project's codebases, issue trackers,
+chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/matteoredz/rack-idempotency_key/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# 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/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "rack/idempotency_key"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/release

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+
+# Setup gem credentials
+mkdir -p ~/.gem
+touch ~/.gem/credentials
+chmod 0600 ~/.gem/credentials
+
+cat << EOF > ~/.gem/credentials
+---
+:rubygems_api_key: ${RUBYGEMS_API_KEY}
+EOF
+
+# Build and Push
+gem build *.gemspec
+gem push *.gem

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/idempotency_key.gemspec

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "lib/rack/idempotency_key/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "rack-idempotency_key"
+  spec.version = Rack::IdempotencyKey::VERSION
+  spec.licenses = ["MIT"]
+  spec.authors = ["Matteo Rossi"]
+  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.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"
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features)/})
+    end
+  end
+
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+end

data/lib/rack/idempotency_key/idempotent_request.rb

@@ -0,0 +1,80 @@
+# 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

data/lib/rack/idempotency_key/memory_store.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Rack
+  class IdempotencyKey
+    class MemoryStore
+      def initialize(expires_in: 86_400)
+        @store      = {}
+        @expires_in = expires_in
+      end
+
+      def get(key)
+        value = store[key]
+        return if value.nil?
+
+        if expired?(value[:added_at])
+          store.delete(key)
+          return
+        end
+
+        value[:value]
+      end
+
+      def set(key, value)
+        store[key] ||= { value: value, added_at: Time.now.utc }
+        get(key)
+      end
+
+      private
+
+        attr_reader :store, :expires_in
+
+        def expired?(added_at)
+          Time.now.utc - added_at > expires_in
+        end
+    end
+  end
+end

data/lib/rack/idempotency_key/redis_store.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Rack
+  class IdempotencyKey
+    class RedisStore
+      KEY_NAMESPACE = "idempotency_key"
+
+      def initialize(store, expires_in: 86_400)
+        @store      = store
+        @expires_in = expires_in
+      end
+
+      def get(key)
+        value = store.get(namespaced_key(key))
+        JSON.parse(value) unless value.nil?
+      end
+
+      def set(key, value)
+        store.set(namespaced_key(key), value, nx: true, ex: expires_in)
+        get(key)
+      end
+
+      private
+
+        attr_reader :store, :expires_in
+
+        def namespaced_key(key)
+          "#{KEY_NAMESPACE}:#{key.split.join}"
+        end
+    end
+  end
+end

data/lib/rack/idempotency_key/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Rack
+  class IdempotencyKey
+    VERSION = "0.1.0"
+  end
+end

data/lib/rack/idempotency_key.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "rack/idempotency_key/version"
+
+# Stores
+require "rack/idempotency_key/memory_store"
+require "rack/idempotency_key/redis_store"
+
+# Collaborators
+require "rack/idempotency_key/idempotent_request"
+
+module Rack
+  class IdempotencyKey
+    Error = Class.new(StandardError)
+
+    def initialize(app, routes: [], store: MemoryStore.new)
+      @app    = app
+      @routes = routes
+      @store  = store
+    end
+
+    def call(env)
+      request = IdempotentRequest.new(Rack::Request.new(env), routes)
+      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
+    end
+
+    private
+
+      attr_reader :app, :store, :routes
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: rack-idempotency_key
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matteo Rossi
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2023-01-20 00:00:00.000000000 Z
+dependencies: []
+description: 
+email:
+- mttrss5@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/CODEOWNERS"
+- ".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
+- README.md
+- Rakefile
+- bin/console
+- bin/release
+- bin/setup
+- idempotency_key.gemspec
+- lib/rack/idempotency_key.rb
+- lib/rack/idempotency_key/idempotent_request.rb
+- lib/rack/idempotency_key/memory_store.rb
+- lib/rack/idempotency_key/redis_store.rb
+- lib/rack/idempotency_key/version.rb
+homepage: https://github.com/matteoredz/rack-idempotency_key
+licenses:
+- MIT
+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: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: A Rack Middleware implementing the idempotency principle
+test_files: []