Konsierge::Idempotency

Deterministic idempotency key builder for Ruby objects, plus ActiveRecord concern for model-level keys.

Usage

Konsierge::Idempotency.key(
  amount: 100,
  currency: :usd,
  issued_at: Time.utc(2026, 5, 27, 10, 0, 0, 123_456)
)
# => "sha256 hash string"

Instance API is also available:

service = Konsierge::Idempotency.new(payload)
service.key

For ActiveRecord models:

class Payment < ApplicationRecord
  include Idempotentable
  self.idempotency_key_column = :idempotency_key

  def self.idempotent_columns
    %i[external_id amount currency]
  end
end

# before_create assigns `idempotency_key`

If model has no idempotency_key column, concern does not assign anything.

Rails Generator

rails g konsierge:idempotency Order
rails g konsierge:idempotency order request_fingerprint

Generator behavior:

• creates migration that adds string column (default idempotency_key) if it does not exist
• adds index for that column if it does not exist
• updates model with include Idempotentable
• sets self.idempotency_key_column = :column_name only for custom column names

Development

After checking out the repo, run bin/setup to install dependencies. Then run bundle exec rspec to run tests. For Rails matrix validation, run bundle exec appraisal install and bundle exec appraisal rspec.

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 the created tag, and push the .gem file to rubygems.org.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Konsierge::Idempotency project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.