debounced 0.1.17 → 0.1.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: beb111cd5043d97b903d9e89278437564f65fd5794f4531d6e5c6e57dca79859
-  data.tar.gz: b872450de202d28e51d32eac774b27238a328972a7b3363c0ca77d5b137897f4
+  metadata.gz: f0b2a5d98cbf80bf222866ad69db51d71b000ea1e13a7bf16d7ddc638aa91923
+  data.tar.gz: f031cae66cd65f40da805111ac8b31140de3e901f19f742bffe1ab593627bb27
 SHA512:
-  metadata.gz: f70040e9197b72f7e8b91b6bae9d736a3f840c6da34817722949f23a4d82c6b798a9a0011345ca623ba7bd4fc2bab48fa498d41cebf70dd59a9d7459d277416d
-  data.tar.gz: af31341ddf36fa276c5ad79db3cecdf975795bd1ac130005f18b9cbbab880b157645aa7e2d5c63199a98b999eae1b85e9daee061a2717162c27567d1d11c2564
+  metadata.gz: d498b7e15fb3aef46c5789d1df43d143970daf40a48bd9f71d5f0664330cda646d9d6d36e8936a334acefdb62d40c3e966ccff7b5fcfeaabf2ea47cf41edada9
+  data.tar.gz: 05ec409dbede721aab6457c29b564a8d8565d87208b3816ec37f1e8a4e3aa2049a4f663e8612e3969ab4e0023058e52f14351529f27f6e8eb710969d9be7b130

data/README.md

@@ -1,6 +1,7 @@
 # Debounced
 
-A Ruby gem that provides a NodeJS-based event debouncing service for Ruby applications. It uses the JavaScript micro event loop to efficiently debounce events.
+Efficient debouncing mechanism for Ruby events. Use it for rate limiting, deduplication, or other 
+scenarios where you want to wait for a certain amount of time before processing a given event.
 
 ## Installation
 
@@ -26,15 +27,7 @@ $ gem install debounced
 
 This gem requires Node.js to be installed on your system, as it uses a Node.js server to handle the debouncing logic. You'll need:
 
-- Node.js >= 14.0.0
-- npm (to install the required node packages)
-
-After installing the gem, run:
-
-```bash
-$ cd $(bundle show debounced)
-$ npm install
-```
+- Node.js >= 20.0.0
 
 ## Usage
 
@@ -44,51 +37,70 @@ $ npm install
 # config/initializers/debounced.rb
 Debounced.configure do |config|
   config.socket_descriptor = '/tmp/my_app.debounceEvents'
+  config.wait_timeout = 3 # idle timeout in seconds for a given activity descriptor
 end
 ```
 
 ### Starting the server
 
-You can start the debounce server with:
+Start the nodeJS debounce server with:
 
 ```bash
-$ bundle exec debounced-server
+$ bundle exec debounced:server
 ```
 
-Or in your application code:
+In your Ruby application code:
 
 ```ruby
 require 'debounced'
 
-# Start the listener thread
+# Start a background thread to receive notification that events are ready to be handled after debounce wait is complete
 proxy = Debounced::ServiceProxy.new
-listener_thread = proxy.listen
+proxy.listen
 
-# Debounce an event
+# Define your event class; create a helper method that will produce a Debounced::Callback object, which 
+# is used to notify the server that the event is ready to be handled
 class MyEvent
-  attr_reader :attributes
+  attr_reader :test_id
 
-  def initialize(data)
-    @attributes = data
+  def initialize(test_id:)
+    @test_id = test_id
   end
 
-  def self.publish(data)
-    # Publish logic here
-    puts "Publishing event with data: #{data.inspect}"
+  def publish
+    # put logic here to publish the event after debouncing
+    puts "Publishing event: #{inspect}"
+  end
+  
+  def debounce_callback
+    Debounced::Callback.new(
+      class_name: self.class.name,
+      params: { test_id: },
+      method_name: 'publish',
+      method_params: []
+    )
   end
 end
 
-event = MyEvent.new({ id: 1, message: "Hello World" })
-proxy.debounce_event("my-event-123", event, 5) # Debounce for 5 seconds
+event = MyEvent.new({ test_id: "Hello World" })
+
+# request the server to debounce the event, ignoring it if another event with the 
+# same descriptor arrives before the timeout
+proxy.debounce_activity("my-event-123", 5, event.debounce_callback)
+# 2 seconds later
+proxy.debounce_activity("my-event-123", 5, event.debounce_callback)
+# 4 seconds later
+proxy.debounce_activity("my-event-123", 5, event.debounce_callback)
+# 5 seconds later the event is published!
+# > Publishing event: #<MyEvent:0x00007f9b1b8b3b40 @test_id="Hello World">
 ```
 
 ## How It Works
 
 1. The gem creates a Unix socket for communication between Ruby and Node.js
-2. When you call `debounce_event`, it sends the event to the Node.js server
-3. The Node.js server keeps track of events with the same descriptor
-4. If another event with the same descriptor arrives before the timeout, it resets the timer
-5. When the timeout expires, it sends the event back to Ruby to be published
+2. When you call `debounce_activity`, it sends the event to the Node.js server
+3. The Node.js server restarts a timer every time an event with a given activity_descriptor is received
+4. When the timeout expires, it sends the event back to Ruby to be published
 
 ## License
 

data/lib/debounced/callback.rb

@@ -0,0 +1,38 @@
+require 'debug'
+
+module Debounced
+  class Callback
+
+    attr_reader :class_name, :params, :method_name, :method_params
+    def initialize(class_name:, params:, method_name:, method_params:)
+      @class_name = class_name.to_s
+      @params = params || {}
+      @method_name = method_name.to_s
+      @method_params = method_params || []
+    end
+
+    def self.json_create(data)
+      new(
+        class_name: data['class_name'],
+        params: data['params'],
+        method_name: data['method_name'],
+        method_params: data['method_params']
+      )
+    end
+
+    def as_json
+      {
+        class_name:,
+        params:,
+        method_name:,
+        method_params:
+      }
+    end
+
+    def call
+      Object.const_get(class_name)
+            .new(**params.transform_keys(&:to_sym))
+            .send(method_name, *method_params)
+    end
+  end
+end

data/lib/debounced/javascript/service.mjs

@@ -102,11 +102,11 @@ export default class DebounceService {
     });
   }
 
-  publishEvent(descriptor, data) {
-    console.log(`Debounce period expired for ${descriptor}, publishing ${data.klass} event`);
+  publishEvent(descriptor, callback) {
+    console.log(`Debounce period expired for ${descriptor}`);
     const message = JSON.stringify({
       type: 'publishEvent',
-      data: data
+      callback: callback
     });
 
     try {
@@ -117,7 +117,7 @@ export default class DebounceService {
     }
   }
 
-  debounceEvent({ descriptor, attributes, klass, timeout }) {
+  debounceEvent({ descriptor, timeout, callback }) {
     if (this._timers[descriptor]) {
       clearTimeout(this._timers[descriptor]);
     }
@@ -125,7 +125,7 @@ export default class DebounceService {
     console.log("Debouncing", descriptor);
     this._timers[descriptor] = setTimeout(() => {
       delete this._timers[descriptor];
-      this.publishEvent(descriptor, { attributes, klass });
+      this.publishEvent(descriptor, callback);
     }, timeout * 1000);
   }
 

data/lib/debounced/service_proxy.rb

@@ -33,13 +33,13 @@ module Debounced
       end
     end
 
-    def debounce_activity(activity_descriptor, object, timeout)
+    def debounce_activity(activity_descriptor, timeout, callback)
       if socket.nil?
         log_debug("No connection to #{server_name}; skipping debounce step.")
-        trigger_callback(object)
+        callback.call
       else
-        log_debug("Sending #{object.inspect} to #{server_name}")
-        transmit(build_request(activity_descriptor, object, timeout))
+        log_debug("Debouncing #{activity_descriptor} to #{server_name}")
+        transmit(build_request(activity_descriptor, timeout, callback))
       end
     end
 
@@ -68,12 +68,14 @@ module Debounced
         log_debug("Parsed #{payload}")
         next unless payload['type'] == 'publishEvent'
 
-        trigger_callback(instantiate_debounced_object(payload['data']))
+        instantiate_callback(payload['callback']).call
       rescue IO::TimeoutError
         # Ignored - normal flow of loop: check abort_signal (L48), get data (L56), timeout waiting for data (69)
       end
     rescue StandardError => e
       log_warn("Unable to listen for messages from #{server_name}: #{e.message}")
+      log_warn(e.backtrace.join("\n"))
+    ensure
     end
 
     private
@@ -86,28 +88,17 @@ module Debounced
       @socket = nil
     end
 
-    def build_request(descriptor, object, timeout)
+    def build_request(descriptor, timeout, callback)
       {
         type: 'debounceEvent',
         data: {
-          timeout:,
           descriptor:,
-          klass: object.class.name,
-          attributes: extract_attributes(object)
+          timeout:,
+          callback: callback.as_json
         }
       }
     end
 
-    def extract_attributes(object)
-      if object.respond_to?(:attributes)
-        object.attributes
-      else
-        object.instance_variables.each_with_object({}) do |var, hash|
-          hash[var.to_s.delete('@')] = object.instance_variable_get(var)
-        end
-      end
-    end
-
     def transmit(request)
       socket.send serialize_payload(request), 0
     end
@@ -124,14 +115,8 @@ module Debounced
       JSON.parse(payload)
     end
 
-    def trigger_callback(object)
-      object.send(Debounced.configuration.callback_method)
-    end
-
-    def instantiate_debounced_object(data)
-      klass = Object.const_get(data['klass'])
-      data = data['attributes'].transform_keys(&:to_sym)
-      klass.new(**data)
+    def instantiate_callback(data)
+      Callback.json_create(data)
     end
 
     def socket_descriptor
@@ -141,7 +126,7 @@ module Debounced
     def socket
       @socket ||= begin
         log_debug("Connecting to #{server_name} at #{socket_descriptor}")
-        UNIXSocket.new(socket_descriptor).tap { it.timeout = @wait_timeout }
+        UNIXSocket.new(socket_descriptor).tap { |s| s.timeout = @wait_timeout }
       end
     rescue Errno::ECONNREFUSED, Errno::ENOENT
       ###

data/lib/debounced/version.rb

@@ -1,3 +1,3 @@
 module Debounced
-  VERSION = "0.1.17"
+  VERSION = "0.1.20"
 end

data/lib/debounced.rb

@@ -1,6 +1,7 @@
 require 'debounced/version'
 require 'debounced/railtie' if defined?(Rails)
 require 'debounced/service_proxy'
+require 'debounced/callback'
 require 'semantic_logger'
 
 module Debounced
@@ -17,12 +18,11 @@ module Debounced
   end
 
   class Configuration
-    attr_accessor :socket_descriptor, :wait_timeout, :callback_method, :logger
+    attr_accessor :socket_descriptor, :wait_timeout, :logger
 
     def initialize
       @socket_descriptor = ENV['DEBOUNCED_SOCKET'] || '/tmp/app.debounceEvents'
       @wait_timeout = ENV['DEBOUNCED_TIMEOUT']&.to_i || 3
-      @callback_method = :publish
       SemanticLogger.add_appender(file_name: 'debounced_proxy.log', formatter: :color)
       SemanticLogger.default_level = ENV.fetch('LOG_LEVEL', 'info')
       @logger = SemanticLogger['ServiceProxy']

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: debounced
 version: !ruby/object:Gem::Version
-  version: 0.1.17
+  version: 0.1.20
 platform: ruby
 authors:
 - Gary Passero
 bindir: bin
 cert_chain: []
-date: 2025-03-21 00:00:00.000000000 Z
+date: 2025-03-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -82,6 +82,7 @@ files:
 - README.md
 - lib/debounced.rb
 - lib/debounced/abort_signal.rb
+- lib/debounced/callback.rb
 - lib/debounced/javascript/server.mjs
 - lib/debounced/javascript/service.mjs
 - lib/debounced/railtie.rb