idempotency 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f09805d7d2ec4b6d8e56f0d6ef0cc298dbe1a7df27e8cc542a45e401792b653
-  data.tar.gz: 7117efd37aed82f6e4edea29a2c7b45357262e3e31b2e1a7e348a37521c11af8
+  metadata.gz: '00195248b99a69659167bae866e907aec9f44421d918bef44722ee79619692e7'
+  data.tar.gz: 17855572f61d3c2edca50a49b316dcd6a6dc5deaeb9067edeaf3005cb150b8bd
 SHA512:
-  metadata.gz: 400b2ed412cad240f18e305c1ce57cc80a96e90f5103db11f1bcb8053734c819c976512058ee9c72eff74891b817524e86d525815b32ef50642670ddffc16a54
-  data.tar.gz: e7924c51b71ac88ec1103888f45a43e9aa77da54f84395472b3b188a4c9f443045113d97385b7416c9e1cfb8bd364ed7daf95229c28c9800caf92df83e17cace
+  metadata.gz: 96fd4a1711a56f0a1dd2e3397e35eadc3b205bec1fa6e1dc9bf07a51258c5e511d262832fa13f364759394e16f9eb40cf4a63f73ecc8b30f247cf4e30ff6b2e6
+  data.tar.gz: 4eb3cba2a688b36aae230a8a024d12626556829ad3959264fd19abd29b10cf7a181bdbcc3906b67e30938a470c633ab00ebb1d31b3eb114076f8771a43985fef

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.3)
+    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
 ```
 
@@ -100,3 +107,25 @@ RSpec.configure do |config|
 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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Idempotency
-  VERSION = '0.1.3'
+  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.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Vu Hoang
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-01-14 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,6 +104,7 @@ 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