debounced 1.0.8 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 221e144d2900e1237f3f06e9b9ef347eb2703f7c3b5d33242272ab5d1115c582
-  data.tar.gz: 7757b7afd63ade6894f5dd62ac9a2855197f0ba14229bed563e3d4a3662ad2d1
+  metadata.gz: f40aa8391039a8a5639ba8e5b77c64d38a07c0208eb158939df97770ae40b240
+  data.tar.gz: 05c33de396be8333e1945880ee7518b67d361d23aa01f68936a4740e6776acee
 SHA512:
-  metadata.gz: f1e65faa3339ae66dce491120890d923213b8bbe49048525fc70ea022f6040ca9f2ab1fc78d28aa2905d0044bf8c78cffeb9811a6bfab6d01172334eb9273a0a
-  data.tar.gz: 53c8676a30eba9f9ed493055e00a0fe9d72f760240626cc999c185d6ab57a3d2823cacc64da1d885b92425862b2e86a342934ef6ba185e109631601af05fb1ad
+  metadata.gz: b3b7aa2939222ef134b925b70a7d9bb4e535876bd317901cb3d022c880f5c397d2fc4b2a9666db9674ca1e1a6112761da664fdc4c2841f157c38010c4de929e9
+  data.tar.gz: 2dc3ae74b658a1ab57bbabd8cef240629102700d49a7980ddd7694c458af36dd7c91e7a55e472a75acdf2188eab511c2612dc6a8f215d3124b08a711e685ae2c

data/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Security
+
+- Callbacks are only dispatched to public methods defined by the application, never to core Ruby methods
+- The server creates its socket owner-only, and the proxy refuses a socket owned by another user
+
+### Changed
+
+- Requires Node.js 22 or later; Node.js 18 and 20 are past end of life
+
+### Fixed
+
+- A second server no longer takes over the socket of a running one, and only removes a socket it created
+- The server exits non-zero when it cannot listen
+- Multi-byte characters split across socket reads are no longer corrupted
+- The server serves any number of connected processes and publishes each callback to the process that requested it
+- The listener no longer adds an extra idle timeout before delivering a callback
+- Requests larger than the socket buffer are no longer truncated
+- A failed send falls back to invoking the callback instead of raising
+- `ServiceProxy#stop` works before `listen`
+
 ## [1.0.7](https://github.com/Flytedesk/debounced/compare/v1.0.6...v1.0.7) (2026-04-15)
 
 

data/README.md

@@ -27,7 +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 >= 20.0.0
+- Node.js >= 22.0.0
 
 ## Usage
 

data/lib/debounced/callback.rb

@@ -3,54 +3,96 @@ module Debounced
   ###
   # Represents a callback to be executed by the debounce service
   class Callback
-    attr_accessor :class_name, :method_name, :args, :kwargs
+    CORE_RUBY_OWNERS = [BasicObject, Kernel, Object, Module, Class].freeze
+
+    attr_accessor :class_name, :method_name, :args, :kwargs, :method_args, :method_kwargs
 
     ###
     # @param [String] class_name the name of the class that will receive the callback
     # @param [String] method_name the name of the method that will be called
-    # @param [Array] args the positional arguments to be passed to the method (optional)
-    # @param [Hash] kwargs the keyword arguments to be passed to the method (optional)
+    # @param [Array] args positional arguments passed to the static method, or to the initializer for instance methods (optional)
+    # @param [Hash] kwargs keyword arguments passed to the static method, or to the initializer for instance methods (optional)
+    # @param [Array] method_args positional arguments passed to the instance method (optional, ignored for static methods)
+    # @param [Hash] method_kwargs keyword arguments passed to the instance method (optional, ignored for static methods)
+    #
+    # @note if the class implements the method_name as a class method, the message will be sent to the class with args and kwargs.
+    # otherwise, an instance of the class will be created using args and kwargs, and the message will be sent to the instance
+    # with method_args and method_kwargs.
     #
-    # @note if the class implements the method_name, the message will be sent to the class with the args and kwargs.
-    # otherwise, an instance of the class will be created and the message will be sent to the instance. in this case,
-    # the args and kwargs will be passed to the initializer.
-    def initialize(class_name:, method_name:, args: [], kwargs: {})
+    # @note args and kwargs values must be JSON-native types (String, Numeric, Boolean, Array, Hash, nil).
+    # Symbol values, Date, Time, and other Ruby-specific types will not survive JSON round-trip serialization
+    # through the debounce server. Hash keys are deep-symbolized on parse, but values are preserved as-is.
+    def initialize(class_name:, method_name:, args: [], kwargs: {}, method_args: [], method_kwargs: {})
       @class_name = class_name.to_s
       @method_name = method_name.to_s
       @args = args
       @kwargs = kwargs
+      @method_args = method_args
+      @method_kwargs = method_kwargs
     end
 
     def self.parse(data)
       new(
         class_name: data['class_name'],
         method_name: data['method_name'],
-        args: data['args'],
-        kwargs: data['kwargs'].transform_keys(&:to_sym),
+        args: data['args'] || [],
+        kwargs: deep_symbolize_keys(data['kwargs'] || {}),
+        method_args: data['method_args'] || [],
+        method_kwargs: deep_symbolize_keys(data['method_kwargs'] || {}),
       )
     end
 
+    def self.deep_symbolize_keys(object)
+      case object
+      when Hash
+        object.to_h { |key, value| [key.to_sym, deep_symbolize_keys(value)] }
+      when Array
+        object.map { |item| deep_symbolize_keys(item) }
+      else
+        object
+      end
+    end
+    private_class_method :deep_symbolize_keys
+
     def as_json
       {
         class_name:,
         method_name:,
         args:,
         kwargs:,
+        method_args:,
+        method_kwargs:,
       }
     end
 
     def call
       Debounced.configuration.logger.debug("Invoking callback #{method_name}")
-      klass = Object.const_get(class_name)
+      klass = callback_class
       if klass.respond_to?(method_name)
-        klass.send(method_name, *args, **kwargs)
+        ensure_application_method(klass.method(method_name))
+        klass.public_send(method_name, *args, **kwargs)
       else
-        instance = klass.new(*args, **kwargs)
-        instance.send(method_name)
+        ensure_application_method(klass.public_instance_method(method_name))
+        klass.new(*args, **kwargs).public_send(method_name, *method_args, **method_kwargs)
       end
     rescue StandardError => e
       Debounced.configuration.logger.warn("Unable to invoke callback #{as_json}: #{e.message}")
       Debounced.configuration.logger.warn(e.backtrace.join("\n"))
     end
+
+    private
+
+    def callback_class
+      klass = Object.const_get(class_name)
+      return klass if klass.ancestors.include?(Debounced::Callbackable)
+
+      raise ArgumentError, "#{class_name} is not an allowed Debounced callback target. Include Debounced::Callbackable in the class."
+    end
+
+    def ensure_application_method(method)
+      return unless CORE_RUBY_OWNERS.include?(method.owner)
+
+      raise ArgumentError, "#{method_name} is a core Ruby method and not an allowed Debounced callback"
+    end
   end
 end

data/lib/debounced/callbackable.rb

@@ -0,0 +1,4 @@
+module Debounced
+  module Callbackable
+  end
+end

data/lib/debounced/javascript/service.mjs

@@ -10,7 +10,7 @@ export default class DebounceService {
   constructor(socketDescriptor) {
     this._socketDescriptor = socketDescriptor;
     this._timers = {};
-    this._client = null;
+    this._clients = new Set();
     this.publishEvent = this.publishEvent.bind(this);
     this.debounceEvent = this.debounceEvent.bind(this);
     this.reset = this.reset.bind(this);
@@ -18,28 +18,25 @@ export default class DebounceService {
     this.handleError = this.handleError.bind(this);
     this.sendMessage = this.sendMessage.bind(this);
     this.onClientConnected = this.onClientConnected.bind(this);
-    this.onClientDisconnected = this.onClientDisconnected.bind(this);
-    this.onConnectionError = this.onConnectionError.bind(this);
     this.handleMessage = this.handleMessage.bind(this);
     this.configureServer();
   }
 
   onConnectionError(err) {
     log('DebounceService client connection error');
-    this._client = null
     this.handleError(err);
   }
 
-  onClientDisconnected() {
+  onClientDisconnected(socket) {
     log('DebounceService client disconnected');
-    this._client = null
+    this._clients.delete(socket);
   }
 
-  handleMessage(message) {
+  handleMessage(message, socket) {
     try {
       const object = JSON.parse(message);
       if (object.type === 'debounceEvent') {
-        this.debounceEvent(object.data);
+        this.debounceEvent(object.data, socket);
       } else if (object.type === 'reset') {
         this.reset();
       } else {
@@ -51,68 +48,80 @@ export default class DebounceService {
   }
 
   onClientConnected(socket) {
-    if (this._client) {
-      log('DebounceService rejecting connection: client already connected');
-      this.sendMessage(socket, JSON.stringify({ type: 'rejectClient'}));
-      socket.destroy();
-      return;
-    }
-
     log('DebounceService client connected');
     let connectionBuffer = '';
-    this._client = socket;
-    socket.on('end', this.onClientDisconnected)
-    socket.on('error', this.onConnectionError)
+    this._clients.add(socket);
+    socket.on('close', () => this.onClientDisconnected(socket));
+    socket.on('error', this.onConnectionError);
+    socket.setEncoding('utf8');
     socket.on('data', data => {
-      log('DebounceService data received', data.toString());
-      connectionBuffer += data.toString();
+      log('DebounceService data received', data);
+      connectionBuffer += data;
       const messages = connectionBuffer.split('\f');
-      connectionBuffer = ''
-      if (!connectionBuffer.endsWith('\f')) {
-        connectionBuffer = messages.pop();
-      }
-      messages.forEach(this.handleMessage);
+      connectionBuffer = messages.pop();
+      messages.forEach(message => this.handleMessage(message, socket));
     })
   }
 
   configureServer() {
     this.server = net.createServer(this.onClientConnected)
-    this.server.on('error', this.handleError);
+    this.server.on('error', (err) => {
+      this.handleError(err);
+      process.exit(1);
+    });
   }
 
   cleanupDescriptor() {
     if (fs.existsSync(this._socketDescriptor)) {
-      log('DebounceEventService removing stale socket file ', this._socketDescriptor);
+      log('DebounceEventService removing socket file ', this._socketDescriptor);
       fs.unlinkSync(this._socketDescriptor);
     }
   }
 
   listen() {
-    // Remove the existing socket file if it exists
-    this.cleanupDescriptor()
+    if (!fs.existsSync(this._socketDescriptor)) {
+      this.bind();
+      return;
+    }
 
-    process.on('exit', (code) => {
-      log(`Process exiting with code: ${code}`);
-      this.server.close();
-      this.cleanupDescriptor()
+    const probe = net.connect(this._socketDescriptor);
+    probe.on('connect', () => {
+      probe.destroy();
+      log('DebounceEventService another server is listening on', this._socketDescriptor);
+      process.exit(1);
+    });
+    probe.on('error', (err) => {
+      if (err.code !== 'ECONNREFUSED') {
+        this.handleError(err);
+        process.exit(1);
+      }
+      log('DebounceEventService removing stale socket file ', this._socketDescriptor);
+      fs.unlinkSync(this._socketDescriptor);
+      this.bind();
     });
+  }
 
-    process.on('SIGTERM', () => {
-      log('Process received SIGTERM');
-      this.server.close();
-      this.cleanupDescriptor()
-      process.exit(0);
+  bind() {
+    const previousUmask = process.umask(0o177);
+    this.server.listen(this._socketDescriptor, () => {
+      log('DebounceService listening on', this._socketDescriptor);
+      this.cleanupOnExit();
     });
+    process.umask(previousUmask);
+  }
 
-    process.on('SIGINT', () => {
-      log('Process received SIGINT');
+  cleanupOnExit() {
+    process.on('exit', (code) => {
+      log(`Process exiting with code: ${code}`);
       this.server.close();
-      this.cleanupDescriptor()
-      process.exit(0);
+      this.cleanupDescriptor();
     });
 
-    this.server.listen(this._socketDescriptor, () => {
-      log('DebounceService listening on', this._socketDescriptor);
+    ['SIGTERM', 'SIGINT'].forEach((signal) => {
+      process.on(signal, () => {
+        log(`Process received ${signal}`);
+        process.exit(0);
+      });
     });
   }
 
@@ -125,16 +134,21 @@ export default class DebounceService {
     }
   }
 
-  publishEvent(descriptor, callback) {
+  publishEvent(descriptor, callback, socket) {
+    if (!this._clients.has(socket)) {
+      log(`Debounce period expired for ${descriptor} - client disconnected, dropping`);
+      return;
+    }
+
     log(`Debounce period expired for ${descriptor} - sending to client`);
     const message = JSON.stringify({
       type: 'publishEvent',
       callback: callback
     });
-    this.sendMessage(this._client, message);
+    this.sendMessage(socket, message);
   }
 
-  debounceEvent({ descriptor, timeout, callback }) {
+  debounceEvent({ descriptor, timeout, callback }, socket) {
     if (this._timers[descriptor]) {
       clearTimeout(this._timers[descriptor]);
     }
@@ -142,7 +156,7 @@ export default class DebounceService {
     log("Debouncing", descriptor);
     this._timers[descriptor] = setTimeout(() => {
       delete this._timers[descriptor];
-      this.publishEvent(descriptor, callback);
+      this.publishEvent(descriptor, callback, socket);
     }, timeout * 1000);
   }
 

data/lib/debounced/service_proxy.rb

@@ -48,6 +48,10 @@ module Debounced
           transmit(build_request(activity_descriptor, timeout, callback))
         end
       end
+    rescue IOError, SystemCallError, NoServerError => e
+      logger.warn("Unable to send #{activity_descriptor} to #{server_name} (#{e.message}); skipping debounce step.")
+      close
+      callback.call
     end
 
     ###
@@ -65,7 +69,6 @@ module Debounced
           next unless message
 
           payload = deserialize_message(message)
-          raise SocketConflictError if payload['type'] == 'rejectClient'
 
           instantiate_callback(payload['callback']).call
         rescue Debounced::NoServerError => e
@@ -75,7 +78,7 @@ module Debounced
 
         close
       end
-    rescue SocketConflictError, StandardError => e
+    rescue StandardError => e
       logger.warn("Unable to listen for messages from #{server_name}: #{e.message}")
       logger.warn(e.backtrace.join("\n"))
     ensure
@@ -83,17 +86,19 @@ module Debounced
     end
 
     def stop
-      @abort_signal.make_true
+      @abort_signal&.make_true
     end
 
     private
 
     def close
-      return unless @socket
+      @mutex.synchronize do
+        return unless @socket
 
-      logger.debug("Closing connection to #{server_name}")
-      @socket.close
-      @socket = nil
+        logger.debug("Closing connection to #{server_name}")
+        @socket.close
+        @socket = nil
+      end
     end
 
     def receive_message_from_server
@@ -108,7 +113,6 @@ module Debounced
       message
     rescue IO::TimeoutError
       logger_trace { "Timeout waiting for data" }
-      sleep wait_timeout
       nil
     rescue Errno::EPIPE, IOError, Errno::ECONNRESET
       close
@@ -127,7 +131,8 @@ module Debounced
     end
 
     def transmit(message)
-      socket.send serialize_message(message), 0
+      connection = socket or raise NoServerError, "#{server_name} at #{socket_descriptor} not running"
+      connection.write(serialize_message(message))
     end
 
     def server_name
@@ -154,6 +159,7 @@ module Debounced
     def socket
       @mutex.synchronize do
         return @socket if @socket
+        return unless File.owned?(socket_descriptor)
 
         logger_trace { "Connecting to #{server_name} at #{socket_descriptor}" }
         @socket = UNIXSocket.new(socket_descriptor).tap { |s| s.timeout = wait_timeout }

data/lib/debounced/version.rb

@@ -1,3 +1,3 @@
 module Debounced
-  VERSION = "1.0.8"
+  VERSION = "2.1.0"
 end

data/lib/debounced.rb

@@ -3,6 +3,7 @@ require 'debounced/railtie' if defined?(Rails)
 require 'debounced/no_server_error'
 require 'debounced/socket_conflict_error'
 require 'debounced/service_proxy'
+require 'debounced/callbackable'
 require 'debounced/callback'
 require 'semantic_logger'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: debounced
 version: !ruby/object:Gem::Version
-  version: 1.0.8
+  version: 2.1.0
 platform: ruby
 authors:
 - Gary Passero
@@ -96,6 +96,7 @@ files:
 - README.md
 - lib/debounced.rb
 - lib/debounced/callback.rb
+- lib/debounced/callbackable.rb
 - lib/debounced/javascript/server.mjs
 - lib/debounced/javascript/service.mjs
 - lib/debounced/no_server_error.rb
@@ -117,14 +118,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Efficient event debouncing in Ruby
 test_files: []