konsierge-idempotency 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 19645d6689c36335eeda896fb47d1f1e6024b96dabeb2f25de89eb8313fec296
+  data.tar.gz: 9b3d7c0f1087efea8b0d86608f0e95ca3f3e81fa2d86158b16a31a86384770ba
+SHA512:
+  metadata.gz: 43bd43515a2ec9de227b4626417d7566f4c0027a25f0976eeacc2f16fbd1317f69fe25f0e0b5fadb2efb03ba8f7cce762ab6f3ee73e59ff6f93f726a551b5133
+  data.tar.gz: d9da719592ff885131f663e06b6a1ce3a803a07299960bb1f8368530b68672ec862ab91fa357dedade95b381a52639dc0666388f31dc37ebc051a16309efe6dc

data/Appraisals

@@ -0,0 +1,49 @@
+appraise 'rails-7-0' do
+  group :test do
+    remove_gem 'rails'
+    remove_gem 'sqlite3'
+  end
+
+  gem 'rails', '~> 7.0'
+  gem 'sqlite3', '~> 1.4'
+end
+
+appraise 'rails-7-1' do
+  group :test do
+    remove_gem 'rails'
+    remove_gem 'sqlite3'
+  end
+
+  gem 'rails', '~> 7.1'
+  gem 'sqlite3', '~> 1.4'
+end
+
+appraise 'rails-7-2' do
+  group :test do
+    remove_gem 'rails'
+    remove_gem 'sqlite3'
+  end
+
+  gem 'rails', '~> 7.2'
+  gem 'sqlite3', '~> 1.4'
+end
+
+appraise 'rails-8-0' do
+  group :test do
+    remove_gem 'rails'
+    remove_gem 'sqlite3'
+  end
+
+  gem 'rails', '~> 8.0'
+  gem 'sqlite3', '~> 2.1'
+end
+
+appraise 'rails-8-1' do
+  group :test do
+    remove_gem 'rails'
+    remove_gem 'sqlite3'
+  end
+
+  gem 'rails', '~> 8.1'
+  gem 'sqlite3', '~> 2.1'
+end

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+## [Unreleased]
+
+## [0.1.1] - 2026-05-28
+
+- Switched idempotency digest from MD5 to SHA256.
+- Extracted object normalization to a dedicated `Normalizer` class.
+- Added configurable concern key column via `self.idempotency_key_column`.
+- Added top-level `Idempotentable` include alias for models.
+- Added Rails generator `rails g konsierge:idempotency Model [column_name]`:
+  - migration with conditional `add_column` and `add_index`
+  - model update with `include Idempotentable` and `self.idempotency_key_column = :column_name`
+- Added Rails `railtie` integration for generator loading.
+- Added dummy Rails app and appraisal matrix (`rails 7.0 .. 8.1`) for compatibility checks.
+- Split and expanded test coverage for core, concern, and generator behavior.
+
+## [0.1.0] - 2026-05-27
+
+- Initial release.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"konsierge-idempotency" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["i@golifox.ru"](mailto:"i@golifox.ru").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 David Rybolovlev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,66 @@
+# Konsierge::Idempotency
+
+Deterministic idempotency key builder for Ruby objects, plus ActiveRecord concern for model-level keys.
+
+## Usage
+
+```ruby
+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:
+
+```ruby
+service = Konsierge::Idempotency.new(payload)
+service.key
+```
+
+For ActiveRecord models:
+
+```ruby
+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
+
+```bash
+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](https://rubygems.org).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## 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](https://gitlab.konsierge.com/digitalbox/gem/konsierge-idempotency/-/blob/master/CODE_OF_CONDUCT.md?ref_type=heads).

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/exe/konsierge-idempotency

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+require 'konsierge-idempotency'

data/gemfiles/.bundle/config

@@ -0,0 +1,2 @@
+---
+BUNDLE_RETRY: "1"

data/gemfiles/rails_7_0.gemfile

@@ -0,0 +1,31 @@
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'rails', '~> 7.0'
+gem 'sqlite3', '~> 1.4'
+
+group :development, :test do
+  gem 'dotenv'
+  gem 'irb'
+  gem 'mutex_m'
+  gem 'oj'
+  gem 'rack-cors'
+  gem 'rake'
+end
+
+group :development do
+  gem 'appraisal'
+  gem 'rubocop'
+  gem 'rubocop-performance'
+  gem 'rubocop-rake'
+  gem 'rubocop-rspec'
+end
+
+group :test do
+  gem 'rspec-rails'
+  gem 'simplecov'
+  gem 'stub_env'
+end
+
+gemspec path: '../'

data/gemfiles/rails_7_1.gemfile

@@ -0,0 +1,31 @@
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'rails', '~> 7.1'
+gem 'sqlite3', '~> 1.4'
+
+group :development, :test do
+  gem 'dotenv'
+  gem 'irb'
+  gem 'mutex_m'
+  gem 'oj'
+  gem 'rack-cors'
+  gem 'rake'
+end
+
+group :development do
+  gem 'appraisal'
+  gem 'rubocop'
+  gem 'rubocop-performance'
+  gem 'rubocop-rake'
+  gem 'rubocop-rspec'
+end
+
+group :test do
+  gem 'rspec-rails'
+  gem 'simplecov'
+  gem 'stub_env'
+end
+
+gemspec path: '../'

data/gemfiles/rails_7_2.gemfile

@@ -0,0 +1,31 @@
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'rails', '~> 7.2'
+gem 'sqlite3', '~> 1.4'
+
+group :development, :test do
+  gem 'dotenv'
+  gem 'irb'
+  gem 'mutex_m'
+  gem 'oj'
+  gem 'rack-cors'
+  gem 'rake'
+end
+
+group :development do
+  gem 'appraisal'
+  gem 'rubocop'
+  gem 'rubocop-performance'
+  gem 'rubocop-rake'
+  gem 'rubocop-rspec'
+end
+
+group :test do
+  gem 'rspec-rails'
+  gem 'simplecov'
+  gem 'stub_env'
+end
+
+gemspec path: '../'

data/gemfiles/rails_8_0.gemfile

@@ -0,0 +1,31 @@
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'rails', '~> 8.0'
+gem 'sqlite3', '~> 2.1'
+
+group :development, :test do
+  gem 'dotenv'
+  gem 'irb'
+  gem 'mutex_m'
+  gem 'oj'
+  gem 'rack-cors'
+  gem 'rake'
+end
+
+group :development do
+  gem 'appraisal'
+  gem 'rubocop'
+  gem 'rubocop-performance'
+  gem 'rubocop-rake'
+  gem 'rubocop-rspec'
+end
+
+group :test do
+  gem 'rspec-rails'
+  gem 'simplecov'
+  gem 'stub_env'
+end
+
+gemspec path: '../'

data/gemfiles/rails_8_1.gemfile

@@ -0,0 +1,31 @@
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'rails', '~> 8.1'
+gem 'sqlite3', '~> 2.1'
+
+group :development, :test do
+  gem 'dotenv'
+  gem 'irb'
+  gem 'mutex_m'
+  gem 'oj'
+  gem 'rack-cors'
+  gem 'rake'
+end
+
+group :development do
+  gem 'appraisal'
+  gem 'rubocop'
+  gem 'rubocop-performance'
+  gem 'rubocop-rake'
+  gem 'rubocop-rspec'
+end
+
+group :test do
+  gem 'rspec-rails'
+  gem 'simplecov'
+  gem 'stub_env'
+end
+
+gemspec path: '../'

data/lib/generators/konsierge/idempotency_generator.rb

@@ -0,0 +1,70 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module Konsierge
+  module Generators
+    class IdempotencyGenerator < Rails::Generators::NamedBase
+      include Rails::Generators::Migration
+
+      DEFAULT_COLUMN_KEY = 'idempotency_key'.freeze
+
+      source_root File.expand_path('templates', __dir__)
+      desc 'Adds idempotency column + index and updates model for Idempotentable concern'
+
+      argument :column_name, type: :string, default: DEFAULT_COLUMN_KEY, banner: 'column_name'
+
+      def create_migration_file
+        migration_template 'add_idempotency_column.rb.tt', "db/migrate/add_#{column_name}_to_#{table_name}.rb"
+      end
+
+      def update_model
+        unless File.exist?(model_full_path)
+          say_status :skip, "Model file not found: #{model_path}", :yellow
+          return
+        end
+
+        source = File.read(model_full_path)
+        lines = []
+        lines << "  include Idempotentable\n" unless source.match?(/^\s*include\s+Idempotentable\s*$/)
+
+        unless default_key_column?
+          if source.match?(/^\s*self\.idempotency_key_column\s*=\s*:.+$/)
+            gsub_file model_path,
+                      /^\s*self\.idempotency_key_column\s*=\s*:.+$/,
+                      "  self.idempotency_key_column = :#{column_name}"
+          else
+            lines << "\n  self.idempotency_key_column = :#{column_name}\n"
+          end
+        end
+
+        return if lines.empty?
+
+        insert_into_file model_path, lines.join, after: /^\s*class\s+.+\n/
+      end
+
+      def self.next_migration_number(_dirname)
+        @migration_number ||= Time.now.utc.strftime('%Y%m%d%H%M%S').to_i
+        @migration_number += 1
+        @migration_number.to_s
+      end
+
+      private
+
+      def table_name(*)
+        name.to_s.underscore.pluralize.tr('/', '_')
+      end
+
+      def model_path
+        File.join('app/models', "#{file_path}.rb")
+      end
+
+      def model_full_path
+        File.join(destination_root, model_path)
+      end
+
+      def default_key_column?
+        column_name.to_s == DEFAULT_COLUMN_KEY
+      end
+    end
+  end
+end

data/lib/generators/konsierge/templates/add_idempotency_column.rb.tt

@@ -0,0 +1,11 @@
+class <%= "Add#{column_name.camelize}To#{table_name.camelize}" %> < ActiveRecord::Migration[<%= "#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}" %>]
+  def change
+    unless column_exists?(:<%= table_name %>, :<%= column_name %>)
+      add_column :<%= table_name %>, :<%= column_name %>, :string
+    end
+
+    unless index_exists?(:<%= table_name %>, :<%= column_name %>)
+      add_index :<%= table_name %>, :<%= column_name %>
+    end
+  end
+end

data/lib/idempotentable.rb

@@ -0,0 +1,3 @@
+require 'konsierge/idempotency/idempotentable'
+
+Idempotentable = Konsierge::Idempotency::Idempotentable

data/lib/konsierge/idempotency/idempotentable.rb

@@ -0,0 +1,34 @@
+require 'active_support/concern'
+
+module Konsierge
+  class Idempotency
+    module Idempotentable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :idempotency_key_column, instance_accessor: false, default: :idempotency_key
+        before_create :set_idempotency_key
+      end
+
+      def idempotent_attributes
+        attributes.slice(*self.class.idempotent_columns.map(&:to_s))
+      end
+
+      private
+
+      def set_idempotency_key
+        key_column = self.class.idempotency_key_column.to_s
+        return unless has_attribute?(key_column)
+        return unless self[key_column].to_s.empty?
+
+        self[key_column] = Konsierge::Idempotency.key(idempotent_attributes)
+      end
+
+      class_methods do
+        def idempotent_columns
+          raise Konsierge::Idempotency::Error, "Please implement #idempotent_columns method in #{name}"
+        end
+      end
+    end
+  end
+end

data/lib/konsierge/idempotency/normalizer.rb

@@ -0,0 +1,45 @@
+require 'date'
+
+module Konsierge
+  class Idempotency
+    class Normalizer
+      class << self
+        def normalize(...)
+          new(...).normalize
+        end
+      end
+
+      attr_reader :object
+
+      def initialize(object)
+        @object = object
+      end
+
+      def normalize
+        normalize_object(object)
+      end
+
+      private
+
+      def normalize_object(value)
+        case value
+        when Hash
+          normalized_object = value.each_with_object({}) do |(k, v), hash|
+            hash[k.to_s] = normalize_object(v)
+          end
+          normalized_object.sort.to_h
+        when Array
+          value.map { |item| normalize_object(item) }
+        when Symbol
+          value.to_s
+        when Time, DateTime
+          value.iso8601(6)
+        when Date
+          value.iso8601
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/konsierge/idempotency/railtie.rb

@@ -0,0 +1,11 @@
+require 'rails/railtie'
+
+module Konsierge
+  class Idempotency
+    class Railtie < ::Rails::Railtie
+      generators do
+        require_relative '../../generators/konsierge/idempotency_generator'
+      end
+    end
+  end
+end

data/lib/konsierge/idempotency/version.rb

@@ -0,0 +1,5 @@
+module Konsierge
+  class Idempotency
+    VERSION = '0.1.1'.freeze
+  end
+end

data/lib/konsierge/idempotency.rb

@@ -0,0 +1,25 @@
+require 'digest/sha2'
+require 'json'
+
+module Konsierge
+  class Idempotency
+    class Error < StandardError; end
+
+    class << self
+      def key(...)
+        new(...).key
+      end
+    end
+
+    attr_reader :object
+
+    def initialize(object)
+      @object = object
+    end
+
+    def key
+      normalized_object = Normalizer.normalize(object)
+      Digest::SHA256.hexdigest(JSON.generate(normalized_object))
+    end
+  end
+end

data/lib/konsierge-idempotency.rb

@@ -0,0 +1,15 @@
+require 'pathname'
+require 'zeitwerk'
+
+lib_root = Pathname.new(__dir__).expand_path.to_s
+
+loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
+loader.push_dir(lib_root)
+loader.ignore(__FILE__)
+loader.ignore("#{lib_root}/generators")
+loader.ignore("#{lib_root}/idempotentdable.rb")
+loader.ignore("#{lib_root}/konsierge/idempotency/{version,idempotentdable}.rb")
+loader.setup
+
+require 'konsierge/idempotency'
+require 'konsierge/idempotency/railtie' if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: konsierge-idempotency
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- David Rybolovlev
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Provides object normalization, idempotency key generation and an optional
+  ActiveRecord concern.
+email:
+- i@golifox.ru
+executables:
+- konsierge-idempotency
+extensions: []
+extra_rdoc_files: []
+files:
+- Appraisals
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/konsierge-idempotency
+- gemfiles/.bundle/config
+- gemfiles/rails_7_0.gemfile
+- gemfiles/rails_7_1.gemfile
+- gemfiles/rails_7_2.gemfile
+- gemfiles/rails_8_0.gemfile
+- gemfiles/rails_8_1.gemfile
+- lib/generators/konsierge/idempotency_generator.rb
+- lib/generators/konsierge/templates/add_idempotency_column.rb.tt
+- lib/idempotentable.rb
+- lib/konsierge-idempotency.rb
+- lib/konsierge/idempotency.rb
+- lib/konsierge/idempotency/idempotentable.rb
+- lib/konsierge/idempotency/normalizer.rb
+- lib/konsierge/idempotency/railtie.rb
+- lib/konsierge/idempotency/version.rb
+homepage: https://gitlab.konsierge.com/digitalbox/gem/konsierge-idempotency
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://gitlab.konsierge.com/digitalbox/gem/konsierge-idempotency
+  source_code_uri: https://gitlab.konsierge.com/digitalbox/gem/konsierge-idempotency/-/tree/master?ref_type=heads
+  changelog_uri: https://gitlab.konsierge.com/digitalbox/gem/konsierge-idempotency/-/blob/master/CHANGELOG.md?ref_type=heads
+  rubygems_mfa_required: 'false'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.13
+specification_version: 4
+summary: Deterministic idempotency key builder for Ruby objects.
+test_files: []