idempotency 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59512a5938bf9884bd46436ff18078a74c9ed2aafb45ca0c491d1f51fa2f42d7
-  data.tar.gz: 4965a8b09bc2fa3d2627f79c90f4241ec192a05e7119f2003de8b55f67d394bf
+  metadata.gz: '00195248b99a69659167bae866e907aec9f44421d918bef44722ee79619692e7'
+  data.tar.gz: 17855572f61d3c2edca50a49b316dcd6a6dc5deaeb9067edeaf3005cb150b8bd
 SHA512:
-  metadata.gz: 025e20c6912c741e0994d9119d76f67d261a39c4ea8864eb0840e78dc23baf9e0b6454c0dbac31e459f5530465e79fd4823352ee0a717228d3d09386e04d889f
-  data.tar.gz: 55151ebed4cf89c7ac6e3444439d8c371d31b366e209fe6d17a87ac74ac1bad76921a0dc24f6502b7c5fa7be0e6679f8c22e67e836db5673249ffe7417675216
+  metadata.gz: 96fd4a1711a56f0a1dd2e3397e35eadc3b205bec1fa6e1dc9bf07a51258c5e511d262832fa13f364759394e16f9eb40cf4a63f73ecc8b30f247cf4e30ff6b2e6
+  data.tar.gz: 4eb3cba2a688b36aae230a8a024d12626556829ad3959264fd19abd29b10cf7a181bdbcc3906b67e30938a470c633ab00ebb1d31b3eb114076f8771a43985fef

data/.github/workflows/release.yml

@@ -8,10 +8,16 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
+
+    permissions:
+      id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
+      contents: write # IMPORTANT: this permission is required for `rake release` to push the release tag
+
     steps:
-      - uses: actions/checkout@v3
-      - name: Release Gem
-        uses: cadwallion/publish-rubygems-action@master
-        env:
-          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
-          RUBYGEMS_API_KEY: ${{secrets.RUBYGEMS_API_KEY}}
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+          ruby-version: '3.4'
+      - uses: rubygems/release-gem@v1

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Change Log]
 
+## [0.1.4] - 2025-01-14
+
+- Support metrics logging via StatsdListener
+
+## [0.1.3] - 2025-01-14
+
+- Support testing by mocking MockRedis#evalsha
+
+## [0.1.2] - 2025-01-07
+
+- Support auto-releasing gem
+
+## [0.1.1] - 2025-01-07
+
+- Allow configuring idempotent methods instead of hardcoding POST
+
 ## [0.1.0] - 2024-11-13
 
 - Initial release

data/Gemfile

@@ -9,6 +9,7 @@ gem 'mock_redis'
 gem 'rspec', '~> 3.0'
 
 gem 'connection_pool'
+gem 'dry-monitor'
 gem 'hanami-controller', '~> 1.3'
 gem 'pry-byebug'
 gem 'rubocop', '~> 1.21'

data/Gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: .
   specs:
-    idempotency (0.1.2)
+    idempotency (0.1.4)
       base64
       dry-configurable
+      dry-monitor
       msgpack
       redis
 
@@ -24,6 +25,13 @@ GEM
       concurrent-ruby (~> 1.0)
       logger
       zeitwerk (~> 2.6)
+    dry-events (1.0.1)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.0, < 2)
+    dry-monitor (1.0.1)
+      dry-configurable (~> 1.0, < 2)
+      dry-core (~> 1.0, < 2)
+      dry-events (~> 1.0, < 2)
     hanami-controller (1.3.3)
       hanami-utils (~> 1.3)
       rack (~> 2.0)
@@ -90,6 +98,7 @@ PLATFORMS
 
 DEPENDENCIES
   connection_pool
+  dry-monitor
   hanami-controller (~> 1.3)
   idempotency!
   mock_redis

data/README.md

@@ -28,7 +28,14 @@ Idempotency.configure do |config|
   }
 
   config.idempotent_methods = %w[POST PUT PATCH]
-  config.idempotent_statuses = (200..299).to_a
+  config.idempotent_statuses = (200..299).to_a + (400..499).to_a
+
+  # Metrics configuration
+  config.metrics.statsd_client = statsd_client # Your StatsD client instance
+  config.metrics.namespace = 'my_service_name' # Optional namespace for metrics
+
+  # Custom instrumentation listeners (optional)
+  config.instrumentation_listeners = [my_custom_listener] # Array of custom listeners
 end
 ```
 
@@ -89,3 +96,36 @@ end
 
 # Render your response
 ```
+
+### Testing
+
+For those using `mock_redis` gem, some methods that `idempotency` gem uses are not implemented (e.g. eval, evalsha), and this could cause test cases to fail. To get around this, the gem has a monkeypatch over `mock_redis` gem to override the missing methods. To use it, simply add following lines to your `spec_helper.rb`:
+
+```ruby
+RSpec.configure do |config|
+  config.include Idempotency::Testing::Helpers
+end
+```
+
+### Instrumentation
+
+The gem supports instrumentation through StatsD out of the box. When you configure a StatsD client in the configuration, the StatsdListener will be automatically set up. It tracks the following metrics:
+
+- `idempotency_cache_hit_count` - Incremented when a cached response is found
+- `idempotency_cache_miss_count` - Incremented when no cached response exists
+- `idempotency_lock_conflict_count` - Incremented when concurrent requests conflict
+- `idempotency_cache_duration_seconds` - Histogram of operation duration
+
+Each metric includes tags:
+- `action` - Either the specified action name or `"{HTTP_METHOD}:{PATH}"`
+- `namespace` - Your configured namespace (if provided)
+- `metric` - The metric name (for duration histogram only)
+
+To enable StatsD instrumentation, simply configure the metrics settings:
+
+```ruby
+Idempotency.configure do |config|
+  config.metrics.statsd_client = Datadog::Statsd.new
+  config.metrics.namespace = 'my_service_name'
+end
+```

data/idempotency.gemspec

@@ -36,6 +36,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency 'base64'
   spec.add_dependency 'dry-configurable'
+  spec.add_dependency 'dry-monitor'
   spec.add_dependency 'msgpack'
   spec.add_dependency 'redis'
 end

data/lib/idempotency/constants.rb

@@ -5,4 +5,12 @@ class Idempotency
     RACK_HEADER_KEY = 'HTTP_IDEMPOTENCY_KEY'
     HEADER_KEY = 'Idempotency-Key'
   end
+
+  module Events
+    ALL_EVENTS = [
+      CACHE_HIT = :cache_hit,
+      CACHE_MISS = :cache_miss,
+      LOCK_CONFLICT = :lock_conflict
+    ].freeze
+  end
 end

data/lib/idempotency/hanami.rb

@@ -4,9 +4,9 @@ require_relative '../idempotency'
 
 class Idempotency
   module Hanami
-    def use_cache(request_identifiers = [], lock_duration: nil)
+    def use_cache(request_identifiers = [], lock_duration: nil, action: self.class.name)
       response_status, response_headers, response_body = Idempotency.use_cache(
-        request, request_identifiers, lock_duration:
+        request, request_identifiers, lock_duration:, action:
       ) do
         yield
 

data/lib/idempotency/instrumentation/statsd_listener.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative '../../idempotency'
+
+class Idempotency
+  module Instrumentation
+    class StatsdListener
+      EVENT_NAME_TO_METRIC_MAPPINGS = {
+        Events::CACHE_HIT => 'idempotency_cache_hit_count',
+        Events::CACHE_MISS => 'idempotency_cache_miss_count',
+        Events::LOCK_CONFLICT => 'idempotency_lock_conflict_count'
+      }.freeze
+
+      def initialize(statsd_client, namespace = nil)
+        @statsd_client = statsd_client
+        @namespace = namespace
+      end
+
+      def setup_subscriptions
+        EVENT_NAME_TO_METRIC_MAPPINGS.each do |event_name, metric|
+          Idempotency.notifier.subscribe(event_name) do |event|
+            send_metric(metric, event.payload)
+          end
+        end
+      end
+
+      private
+
+      attr_reader :namespace, :statsd_client
+
+      def send_metric(metric_name, event_data)
+        action = event_data[:action] || "#{event_data[:request].request_method}:#{event_data[:request].path}"
+        tags = ["action:#{action}"]
+        tags << "namespace:#{@namespace}" if @namespace
+
+        @statsd_client.increment(metric_name, tags:)
+        @statsd_client.histogram(
+          'idempotency_cache_duration_seconds', event_data[:duration], tags: tags + ["metric:#{metric_name}"]
+        )
+      end
+    end
+  end
+end

data/lib/idempotency/rails.rb

@@ -4,9 +4,9 @@ require_relative '../idempotency'
 
 class Idempotency
   module Rails
-    def use_cache(request_identifiers = [], lock_duration: nil)
+    def use_cache(request_identifiers = [], lock_duration: nil, action: "#{controller_name}##{action_name}")
       response_status, response_headers, response_body = Idempotency.use_cache(
-        request, request_identifiers, lock_duration:
+        request, request_identifiers, lock_duration:, action:
       ) do
         yield
 

data/lib/idempotency/testing/helpers.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'idempotency/cache'
+
+class Idempotency
+  module Testing
+    module Helpers
+      def self.included(_base)
+        return unless defined?(MockRedis)
+
+        MockRedis.class_eval do
+          def evalsha(sha, keys:, argv:)
+            return unless sha == Idempotency::Cache::COMPARE_AND_DEL_SCRIPT_SHA
+
+            value = argv[0]
+            cached_value = get(keys[0])
+
+            if value == cached_value
+              del(keys[0])
+              value
+            else
+              cached_value
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/idempotency/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Idempotency
-  VERSION = '0.1.2'
+  VERSION = '0.1.4'
 end

data/lib/idempotency.rb

@@ -5,12 +5,29 @@ require 'json'
 require 'base64'
 require_relative 'idempotency/cache'
 require_relative 'idempotency/constants'
+require_relative 'idempotency/instrumentation/statsd_listener'
+require 'dry-monitor'
 
 class Idempotency
   extend Dry::Configurable
+  @monitor = Monitor.new
+
+  def self.notifier
+    @monitor.synchronize do
+      @notifier ||= Dry::Monitor::Notifications.new(:idempotency_gem).tap do |n|
+        Events::ALL_EVENTS.each { |event| n.register_event(event) }
+      end
+    end
+  end
 
   setting :redis_pool
   setting :logger
+  setting :instrumentation_listeners, default: []
+  setting :metrics do
+    setting :namespace
+    setting :statsd_client
+  end
+
   setting :default_lock_expiry, default: 300 # 5 minutes
   setting :idempotent_methods, default: %w[POST PUT PATCH DELETE]
   setting :idempotent_statuses, default: (200..299).to_a + (400..499).to_a
@@ -21,16 +38,31 @@ class Idempotency
     }.to_json
   end
 
+  def self.configure
+    super
+
+    if config.metrics.statsd_client
+      config.instrumentation_listeners << Idempotency::Instrumentation::StatsdListener.new(
+        config.metrics.statsd_client,
+        config.metrics.namespace
+      )
+    end
+
+    config.instrumentation_listeners.each(&:setup_subscriptions)
+  end
+
   def initialize(config: Idempotency.config, cache: Cache.new(config:))
     @config = config
     @cache = cache
   end
 
-  def self.use_cache(request, request_identifiers, lock_duration: nil, &blk)
-    new.use_cache(request, request_identifiers, lock_duration:, &blk)
+  def self.use_cache(request, request_identifiers, lock_duration: nil, action: nil, &blk)
+    new.use_cache(request, request_identifiers, lock_duration:, action:, &blk)
   end
 
-  def use_cache(request, request_identifiers, lock_duration:) # rubocop:disable Metrics/AbcSize
+  def use_cache(request, request_identifiers, lock_duration: nil, action: nil) # rubocop:disable Metrics/AbcSize
+    duration_start = Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+
     return yield unless cache_request?(request)
 
     request_headers = request.env
@@ -42,6 +74,8 @@ class Idempotency
 
     if (cached_status, cached_headers, cached_body = cached_response)
       cached_headers.merge!(Constants::HEADER_KEY => idempotency_key)
+      instrument(Events::CACHE_HIT, request:, action:, duration: calculate_duration(duration_start))
+
       return [cached_status, cached_headers, cached_body]
     end
 
@@ -55,8 +89,10 @@ class Idempotency
       response_headers.merge!({ Constants::HEADER_KEY => idempotency_key })
     end
 
+    instrument(Events::CACHE_MISS, request:, action:, duration: calculate_duration(duration_start))
     [response_status, response_headers, response_body]
   rescue Idempotency::Cache::LockConflict
+    instrument(Events::LOCK_CONFLICT, request:, action:, duration: calculate_duration(duration_start))
     [409, {}, config.response_body.concurrent_error]
   end
 
@@ -64,6 +100,14 @@ class Idempotency
 
   attr_reader :config, :cache
 
+  def instrument(event_name, **metadata)
+    Idempotency.notifier.instrument(event_name, **metadata)
+  end
+
+  def calculate_duration(start_time)
+    Process.clock_gettime(::Process::CLOCK_MONOTONIC) - start_time
+  end
+
   def calculate_fingerprint(request, idempotency_key, request_identifiers)
     d = Digest::SHA256.new
     d << idempotency_key

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: idempotency
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - Vu Hoang
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-01-07 00:00:00.000000000 Z
+date: 2025-01-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -38,6 +38,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: dry-monitor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: msgpack
   requirement: !ruby/object:Gem::Requirement
@@ -90,7 +104,9 @@ files:
 - lib/idempotency/cache.rb
 - lib/idempotency/constants.rb
 - lib/idempotency/hanami.rb
+- lib/idempotency/instrumentation/statsd_listener.rb
 - lib/idempotency/rails.rb
+- lib/idempotency/testing/helpers.rb
 - lib/idempotency/version.rb
 homepage: https://www.ascenda.com
 licenses: