waterdrop 2.8.8 → 2.8.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d646a05ccb9842fdd341c1fe114eeb1e98e091056f4f3a9d8cf02da0e6d166cd
-  data.tar.gz: 7f0f8df74fe994d1747e7ef64508d7c62635b1401b4aa34b69b63c4e41c76fad
+  metadata.gz: 8ed8d57d7b79987870f918e97b3ffeee07c6c68b75a506bd11f29abe8778f21f
+  data.tar.gz: 86fe1bdb3d1963ef3783a254dbf0c7ae3ad61dc5608eeca5a41dcc2bbd454c1b
 SHA512:
-  metadata.gz: dc5e3653a4fba7c1e5e3c8cf4325449210cd692a646d14b44dd6c01203515f0aa58aa9c1ad5fd86e9df3e6b881f2157dd0cdfd5db7b48f4b28a200f9013f5f98
-  data.tar.gz: dcd0b58e6019ea7fdef647f43339bf68148d1255011145e3e23f1f4ccc91d9cbbc4ba89087fa515a7b9d32dfb9a2ad947e5d0771d2bf8cb645bad6f8456d44f0
+  metadata.gz: 22949a9ec65e4e6c0532ad469747989c4971de5320c705cf704371440b2d21b6edd83504eb77e56192ec0043c04334c91892813f3b1d01418e88d1f996064949
+  data.tar.gz: 9cecd0e2e56209d14eac2c896d9f2086973874de78e478e758404eb31d17e1b9abcf66e54011a1e9341dad215bac5de8fdafcc29ef38e0a6c8f43ca8eb82a301

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # WaterDrop changelog
 
+## 2.8.10 (2025-09-25)
+- [Enhancement] Add `#close` alias for `WaterDrop::ConnectionPool#shutdown` to align with producer API for consistent interface across both individual producers and connection pools.
+- [Enhancement] Add `WaterDrop.monitor` method as the preferred alias for `WaterDrop.instrumentation` to align with per-producer API naming convention. The `instrumentation` method remains available as a deprecated alias for backward compatibility.
+
+## 2.8.9 (2025-09-23)
+- [Enhancement] Add connection pool lifecycle events to global instrumentation for improved observability. Events include `connection_pool.created`, `connection_pool.setup`, `connection_pool.shutdown`, `connection_pool.reload`, and `connection_pool.reloaded`.
+- [Enhancement] Add default connection pool transactional direct API.
+
 ## 2.8.8 (2025-09-23)
 - [Feature] Add `WaterDrop::ConnectionPool` for efficient connection pooling using the proven `connection_pool` gem.
 - [Feature] Add `WaterDrop.instrumentation` class-level instrumentation for producer lifecycle events. This allows external libraries to subscribe to `producer.created` and `producer.configured` events without needing producer instance references, enabling middleware injection and configuration by libraries like Datadog tracing.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    waterdrop (2.8.8)
+    waterdrop (2.8.10)
       karafka-core (>= 2.4.9, < 3.0.0)
       karafka-rdkafka (>= 0.20.0)
       zeitwerk (~> 2.3)

data/lib/waterdrop/connection_pool.rb

@@ -70,6 +70,16 @@ module WaterDrop
         ensure_connection_pool_gem!
 
         @default_pool = new(size: size, timeout: timeout, &producer_config)
+
+        # Emit global event for pool setup
+        WaterDrop.instrumentation.instrument(
+          'connection_pool.setup',
+          pool: @default_pool,
+          size: size,
+          timeout: timeout
+        )
+
+        @default_pool
       end
 
       # Executes a block with a producer from the global pool
@@ -105,13 +115,33 @@ module WaterDrop
       def shutdown
         return unless @default_pool
 
+        pool = @default_pool
         @default_pool.shutdown
         @default_pool = nil
+
+        # Emit global event for pool shutdown
+        WaterDrop.instrumentation.instrument(
+          'connection_pool.shutdown',
+          pool: pool
+        )
       end
 
+      # Alias for shutdown to align with producer API
+      # WaterDrop producers use #close, so we alias connection pool #shutdown to #close
+      # for API consistency across both individual producers and connection pools
+      alias close shutdown
+
       # Reload the global connection pool
       def reload
-        @default_pool&.reload
+        return unless @default_pool
+
+        @default_pool.reload
+
+        # Emit global event for pool reload
+        WaterDrop.instrumentation.instrument(
+          'connection_pool.reload',
+          pool: @default_pool
+        )
       end
 
       # Check if the global connection pool is active (configured)
@@ -121,6 +151,25 @@ module WaterDrop
         !@default_pool.nil?
       end
 
+      # Execute a transaction with a producer from the global connection pool
+      # Only available when connection pool is configured
+      #
+      # @param block [Proc] Block to execute within a transaction
+      # @yield [producer] Producer from the global pool with an active transaction
+      # @return [Object] Result of the block
+      # @raise [RuntimeError] If no global pool is configured
+      #
+      # @example
+      #   WaterDrop::ConnectionPool.transaction do |producer|
+      #     producer.produce(topic: 'events', payload: 'data1')
+      #     producer.produce(topic: 'events', payload: 'data2')
+      #   end
+      def transaction(&block)
+        raise 'No global connection pool configured. Call setup first.' unless @default_pool
+
+        @default_pool.transaction(&block)
+      end
+
       private
 
       # Ensures the connection_pool gem is available (class method)
@@ -167,6 +216,14 @@ module WaterDrop
           end
         end
       end
+
+      # Emit event when a connection pool is created
+      WaterDrop.instrumentation.instrument(
+        'connection_pool.created',
+        pool: self,
+        size: size,
+        timeout: timeout
+      )
     end
 
     # Get pool statistics
@@ -184,14 +241,49 @@ module WaterDrop
       @pool.shutdown do |producer|
         producer.close! if producer&.status&.active?
       end
+
+      # Emit event after pool is shut down
+      WaterDrop.instrumentation.instrument(
+        'connection_pool.shutdown',
+        pool: self
+      )
     end
 
+    # Alias for shutdown to align with producer API
+    # WaterDrop producers use #close, so we alias connection pool #shutdown to #close
+    # for API consistency across both individual producers and connection pools
+    alias close shutdown
+
     # Reload all connections in the pool
     # Useful for configuration changes or error recovery
     def reload
       @pool.reload do |producer|
         producer.close! if producer&.status&.active?
       end
+
+      # Emit event after pool is reloaded
+      WaterDrop.instrumentation.instrument(
+        'connection_pool.reloaded',
+        pool: self
+      )
+    end
+
+    # Execute a transaction with a producer from this connection pool
+    #
+    # @yield [producer] Producer from the pool with an active transaction
+    # @return [Object] Result of the block
+    #
+    # @example
+    #   pool.transaction do |producer|
+    #     producer.produce(topic: 'events', payload: 'data1')
+    #     producer.produce(topic: 'events', payload: 'data2')
+    #   end
+    def transaction
+      with do |producer|
+        producer.transaction do
+          yield(producer)
+        end
+      end
     end
 
     # Returns the underlying connection_pool instance
@@ -218,6 +310,22 @@ module WaterDrop
       ConnectionPool.with(&block)
     end
 
+    # Execute a transaction with a producer from the global connection pool
+    # Only available when connection pool is configured
+    #
+    # @param block [Proc] Block to execute within a transaction
+    # @yield [producer] Producer from the global pool with an active transaction
+    # @return [Object] Result of the block
+    #
+    # @example
+    #   WaterDrop.transaction do |producer|
+    #     producer.produce(topic: 'events', payload: 'data1')
+    #     producer.produce(topic: 'events', payload: 'data2')
+    #   end
+    def transaction(&block)
+      ConnectionPool.transaction(&block)
+    end
+
     # Access the global connection pool
     #
     # @return [WaterDrop::ConnectionPool] The global pool

data/lib/waterdrop/instrumentation/class_notifications.rb

@@ -7,9 +7,16 @@ module WaterDrop
     class ClassNotifications < ::Karafka::Core::Monitoring::Notifications
       # List of events that are available at the class level via WaterDrop.instrumentation
       # These are lifecycle events for producer creation and configuration
+      # and connection pool lifecycle events
       EVENTS = %w[
         producer.created
         producer.configured
+
+        connection_pool.created
+        connection_pool.setup
+        connection_pool.shutdown
+        connection_pool.reload
+        connection_pool.reloaded
       ].freeze
 
       # @return [WaterDrop::Instrumentation::ClassNotifications] class-level notification instance

data/lib/waterdrop/version.rb

@@ -3,5 +3,5 @@
 # WaterDrop library
 module WaterDrop
   # Current WaterDrop version
-  VERSION = '2.8.8'
+  VERSION = '2.8.10'
 end

data/lib/waterdrop.rb

@@ -17,7 +17,7 @@ module WaterDrop
       Pathname.new(File.expand_path('..', __dir__))
     end
 
-    # @return [WaterDrop::Instrumentation::ClassMonitor] global instrumentation monitor for
+    # @return [WaterDrop::Instrumentation::ClassMonitor] global monitor for
     #   class-level event subscriptions. This allows external libraries to subscribe to WaterDrop
     #   lifecycle events without needing producer instance references.
     #
@@ -25,13 +25,16 @@ module WaterDrop
     #   instance events
     #
     # @example Subscribe to producer creation events
-    #   WaterDrop.instrumentation.subscribe('producer.created') do |event|
+    #   WaterDrop.monitor.subscribe('producer.created') do |event|
     #     producer = event[:producer]
     #     # Configure producer or add middleware
     #   end
-    def instrumentation
+    def monitor
       @instrumentation ||= Instrumentation::ClassMonitor.new
     end
+
+    # @deprecated Use #monitor instead. This method is provided for backward compatibility only.
+    alias instrumentation monitor
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: waterdrop
 version: !ruby/object:Gem::Version
-  version: 2.8.8
+  version: 2.8.10
 platform: ruby
 authors:
 - Maciej Mensfeld