debounced 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e4b64c7302b08f7d4134cfad294a0dc7b39203ef2f860691ce09838a8e56cc1c
+  data.tar.gz: 78006a905bcab3220c6968d66b244670d96a40095f212261421e46965b612799
+SHA512:
+  metadata.gz: 954ab3aaa0b3bc092a3119c53414be10a44ce576b5f195f18ccab33786514468d9e3febe4407130bd22a87ed4de50f8897f8f7bb7c7f57da145ae6d1ba4ce8e4
+  data.tar.gz: a47d2fbe9fd86cf486ad79088039c9503f6c2d56cfea2d1d1e982b960635232f0bcfe44a9ced45537ad305c5ed595cd7053da068bf5a048f9dad75cc9e2e9146

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+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).
+
+## [0.1.0] - 2025-03-16
+
+### Added
+- Initial release
+- Core functionality extracted from supply-side-platform
+- Ruby wrapper for Node.js event debouncing service
+- Configuration options for socket descriptor
+- Rails integration via Railtie

data/README.md

@@ -0,0 +1,95 @@
+# 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.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'debounced'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install debounced
+```
+
+## Dependencies
+
+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
+```
+
+## Usage
+
+### Configuration
+
+```ruby
+# config/initializers/debounced.rb
+Debounced.configure do |config|
+  config.socket_descriptor = '/tmp/my_app.debounceEvents'
+end
+```
+
+### Starting the server
+
+You can start the debounce server with:
+
+```bash
+$ bundle exec debounced-server
+```
+
+Or in your application code:
+
+```ruby
+require 'debounced'
+
+# Start the listener thread
+proxy = Debounced::EventServiceProxy.new
+listener_thread = proxy.listen
+
+# Debounce an event
+class MyEvent
+  attr_reader :attributes
+  
+  def initialize(data)
+    @attributes = data
+  end
+  
+  def self.publish(data)
+    # Publish logic here
+    puts "Publishing event with data: #{data.inspect}"
+  end
+end
+
+event = MyEvent.new({ id: 1, message: "Hello World" })
+proxy.debounce_event("my-event-123", event, 5) # Debounce for 5 seconds
+```
+
+## 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
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/exe/debounced-server

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import DebounceEventService from '../lib/assets/javascript/debounced/event_service.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Default socket path
+let socketDescriptor = process.env.DEBOUNCED_SOCKET || '/tmp/app.debounceEvents';
+
+// If test environment is specified
+if (process.env.NODE_ENV === 'test') {
+  socketDescriptor = process.env.DEBOUNCED_TEST_SOCKET || '/tmp/app.debounceEvents.test';
+}
+
+// Allow socket path to be specified as command line argument
+if (process.argv.length > 2) {
+  socketDescriptor = process.argv[2];
+}
+
+new DebounceEventService(socketDescriptor).listen();

data/lib/assets/javascript/debounced/event_service.mjs

@@ -0,0 +1,68 @@
+import ipc from 'node-ipc';
+import fs from 'fs';
+
+const logLevel = process.env.LOG_LEVEL || 'info';
+
+export default class DebounceEventService {
+  constructor(socketDescriptor) {
+    this._socketDescriptor = socketDescriptor;
+    this._timers = {};
+    this.publishEvent = this.publishEvent.bind(this);
+    this.debounceEvent = this.debounceEvent.bind(this);
+    this.reset = this.reset.bind(this);
+    this.listen = this.listen.bind(this);
+    this.handleError = this.handleError.bind(this);
+    this.configureServer();
+    this.registerMessageTypes();
+  }
+
+  registerMessageTypes() {
+    ipc.server.on('debounceEvent', this.debounceEvent);
+    ipc.server.on('reset', this.reset);
+    ipc.server.on('error', this.handleError);
+  }
+
+  configureServer() {
+    // Remove the existing socket file if it exists
+    if (fs.existsSync(this._socketDescriptor)) {
+      console.log('DebounceEventService removing stale socket file ', this._socketDescriptor);
+      fs.unlinkSync(this._socketDescriptor);
+    }
+
+    ipc.config.delimiter = '\f'; // incoming messages are terminated by a form feed character
+    ipc.config.encoding = 'utf8';
+    ipc.config.silent = (logLevel !== 'debug');
+
+    ipc.serve(this._socketDescriptor);
+  }
+
+  listen() {
+    console.log('DebounceEventService listening on', this._socketDescriptor);
+    ipc.server.start();
+  }
+
+  publishEvent(descriptor, data) {
+    console.log(`Debounce period expired for ${descriptor}, publishing ${data.klass} event`);
+    ipc.server.broadcast("publishEvent", data);
+  }
+
+  debounceEvent({ descriptor, attributes, klass, timeout }) {
+    if (this._timers[descriptor]) {
+      clearTimeout(this._timers[descriptor]);
+    }
+
+    this._timers[descriptor] = setTimeout(() => {
+      delete this._timers[descriptor];
+      this.publishEvent(descriptor, { attributes, klass });
+    }, timeout * 1000);
+  }
+
+  reset() {
+    Object.values(this._timers).forEach(timerID => clearTimeout(timerID));
+    this._timers = {};
+  }
+
+  handleError(err) {
+    console.log('\n\n######\nERROR: ', err);
+  }
+}

data/lib/debounced/event_service_proxy.rb

@@ -0,0 +1,174 @@
+require 'socket'
+require 'active_support/json'
+
+module Debounced
+  class EventServiceProxy
+    DELIMITER = "\f".freeze
+    WAIT_TIMEOUT = 3
+
+    def listen(abort_signal = nil)
+      Thread.new do
+        if defined?(Rails)
+          Rails.application.executor.wrap do
+            receive(abort_signal)
+          end
+        else
+          receive(abort_signal)
+        end
+      end
+    end
+
+    def reset
+      if socket.nil?
+        log_debug("No connection to #{server_name}; unable to reset server.")
+      else
+        log_debug("Resetting #{server_name}")
+        transmit({ type: 'reset' })
+      end
+    end
+
+    def debounce_event(descriptor, event, timeout)
+      if socket.nil?
+        log_debug("No connection to #{server_name}; publishing event immediately.")
+        event.publish if event.respond_to?(:publish)
+      else
+        log_debug("Sending #{event_name(event)} event to #{server_name}")
+        transmit(debounce_request(descriptor, event, timeout))
+      end
+    end
+
+    def receive(abort_signal = nil)
+      log_debug("Listening for messages from #{server_name}...")
+
+      loop do
+        break if abort_signal&.set?
+
+        if socket.nil?
+          log_debug("Waiting for #{server_name}...")
+          sleep(WAIT_TIMEOUT)
+          next
+        end
+
+        message = socket.gets(DELIMITER, chomp: true)
+
+        # gets => nil when server crashed.... try to reconnect
+        if message.nil?
+          close
+          next
+        end
+
+        payload = deserialize_payload(message)
+        next unless payload['type'] == 'publishEvent'
+
+        publish_event(payload['data'])
+      rescue IO::TimeoutError
+        # Ignored
+      end
+    rescue StandardError => e
+      log_warn("Unable to listen for messages from #{server_name}: #{e.message}")
+    end
+
+    private
+
+    def close
+      return unless @socket
+
+      log_info("Closing connection to #{server_name}")
+      @socket.close
+      @socket = nil
+    end
+
+    def publish_event(data)
+      event_klass = data['klass'].constantize
+      event_data = data['attributes']
+      event_klass.publish(event_data)
+    end
+
+    def debounce_request(descriptor, event, timeout)
+      {
+        type: 'debounceEvent',
+        data: {
+          timeout: timeout,
+          descriptor: descriptor,
+          klass: event.class.name,
+          attributes: event_attributes(event)
+        }
+      }
+    end
+
+    def event_attributes(event)
+      if event.respond_to?(:attributes)
+        event.attributes
+      else
+        event.instance_variables.each_with_object({}) do |var, hash|
+          hash[var.to_s.delete('@')] = event.instance_variable_get(var)
+        end
+      end
+    end
+    
+    def event_name(event)
+      if event.respond_to?(:event_name)
+        event.event_name
+      else
+        event.class.name
+      end
+    end
+
+    def transmit(request)
+      socket.send serialize_payload(request), 0
+    end
+
+    def server_name
+      'DebounceEventServer'
+    end
+
+    def serialize_payload(payload)
+      "#{ActiveSupport::JSON.encode(payload)}#{DELIMITER}" # inject EOM delimiter (form feed character)
+    end
+
+    def deserialize_payload(payload)
+      ActiveSupport::JSON.decode(payload)
+    end
+
+    def socket_descriptor
+      Debounced.configuration.socket_descriptor
+    end
+
+    def socket
+      @socket ||= UNIXSocket.new(socket_descriptor)
+                          .tap do |socket|
+        socket.timeout = WAIT_TIMEOUT
+      end
+    ###
+    # Errno::ENOENT is raised if the socket file does not exist.
+    # Errno::ECONNREFUSED is raised if the socket file exists but no process is listening on it.
+    rescue Errno::ECONNREFUSED, Errno::ENOENT
+      log_debug("#{server_name} is not running")
+      nil
+    end
+    
+    def log_debug(message)
+      if defined?(Rails)
+        Rails.logger.debug { message }
+      else
+        puts "[DEBUG] #{message}" if ENV['DEBUG']
+      end
+    end
+    
+    def log_info(message)
+      if defined?(Rails)
+        Rails.logger.info(message)
+      else
+        puts "[INFO] #{message}"
+      end
+    end
+    
+    def log_warn(message)
+      if defined?(Rails)
+        Rails.logger.warn(message)
+      else
+        puts "[WARNING] #{message}"
+      end
+    end
+  end
+end

data/lib/debounced/version.rb

@@ -0,0 +1,3 @@
+module Debounced
+  VERSION = "0.1.0"
+end

data/lib/debounced.rb

@@ -0,0 +1,24 @@
+require "debounced/version"
+require "debounced/railtie" if defined?(Rails)
+require "debounced/event_service_proxy"
+
+module Debounced
+  class Error < StandardError; end
+  
+  class << self
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration) if block_given?
+    end
+  end
+
+  class Configuration
+    attr_accessor :socket_descriptor
+
+    def initialize
+      @socket_descriptor = ENV['DEBOUNCED_SOCKET'] || '/tmp/app.debounceEvents'
+    end
+  end
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: debounced
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Gary Passero
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2025-03-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+description: A Ruby wrapper for a NodeJS server that uses the JavaScript micro event
+  loop to debounce events in Ruby applications
+email:
+- gary@flytedesk.com
+executables:
+- debounced-server
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- exe/debounced-server
+- lib/assets/javascript/debounced/event_service.mjs
+- lib/debounced.rb
+- lib/debounced/event_service_proxy.rb
+- lib/debounced/version.rb
+homepage: https://github.com/flytedesk/debounced
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/flytedesk/debounced
+  source_code_uri: https://github.com/flytedesk/debounced
+  changelog_uri: https://github.com/flytedesk/debounced/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Efficient event debouncing in Ruby
+test_files: []