rack-idempotency_key

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:

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. Please refer to the specific application's guidelines.

Usage with Rails

# 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" },
        { path: "/posts/*/comments", method: "POST" }
      ]
    )
  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.

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.

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:

# @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, as follows:

[
  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:

routes: [
  { path: "/posts", method: "POST" },
  { path: "/posts/*", method: "PATCH" },
  { path: "/posts/*/comments", method: "POST" }
]

The * char is a placeholder representing a named parameter that will get converted to an any-chars regex.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. 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.

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.

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.