activejob-debounce 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e1f75d298bfa0f6d3465458cfbae9b6c1e0aa478931d7239bb3165313513cef2
+  data.tar.gz: 2f5878e7ceb1d785a24084491fab650cebea2b9a477a8dac492cd1ca46ce5091
+SHA512:
+  metadata.gz: a37dad2992e3def5f3876ce2126a21f711b93ca7746d027b5099c12f070fb48c1529252f600dfcc9c638c8af2f785fc617e91f75d37bd5be146f9791c45df21b
+  data.tar.gz: f981f5b6a520b3811642c45b0dd6062ed11e69e4400fb3f9448cc82a63e5cd0c1342303f6eff72b940ca20e305f3afe03585399dc2850e9e5f796414e3d5eeeb

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# 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).
+
+## [1.0.0] - 2025-01-13
+
+### Added
+- Initial release
+- `Sidekiq::Debouncer::Concern` module for adding debounce behavior to ActiveJob classes
+- `debounce_for` class method to configure debounce duration
+- `perform_debounce` class method to queue debounced jobs
+- Global configuration for default_delay, buffer, ttl, and redis_connection
+- Support for ActiveRecord objects via GlobalID
+- Automatic Redis key cleanup after job execution
+- Comprehensive test suite

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,183 @@
+# ActiveJob::Debounce
+
+Leading-edge debounce for ActiveJob. One job per debounce window, atomic Redis gating, crash recovery.
+
+Works with **any ActiveJob backend**: Sidekiq, GoodJob, Solid Queue, Resque, etc.
+
+**The problem:** Webhooks, callbacks, and real-time triggers fire multiple times for the same entity within seconds. Without debouncing, you get duplicate jobs flooding your queue — wasted workers, inflated stats, and race conditions.
+
+**This gem** gates at dispatch time using Redis GETSET — only 1 job enters the queue per debounce window. Subsequent calls are true no-ops (nothing queued). Clean queue stats, full crash recovery.
+
+## How it works
+
+```
+Time: 0s     5s      10s     30s     35s
+      |      |       |       |       |
+      v      v       v       v       v
+    call   call    call   [executes] call
+      |______|_______|          |_____|
+           |                        |
+    These 3 calls become       This call
+    ONE execution              starts new window
+```
+
+1. First `perform_debounce` → sets Redis key, queues job with delay
+2. Subsequent calls within the window → Redis key exists, skip (nothing queued)
+3. Job executes → `after_perform` cleans up Redis key
+4. Next call → starts a new debounce window
+
+## Installation
+
+```ruby
+gem 'activejob-debounce'
+```
+
+```bash
+bundle install
+```
+
+## Requirements
+
+- Ruby >= 2.7
+- Rails >= 6.0 (ActiveJob, ActiveSupport)
+- Redis >= 4.0
+
+## Usage
+
+### Basic usage
+
+```ruby
+class SyncContactJob < ApplicationJob
+  include ActiveJob::Debounce::Concern
+
+  debounce_for 30.seconds
+
+  def perform(contact_id)
+    Contact.find(contact_id).sync_to_crm
+  end
+end
+
+# In your model:
+class Contact < ApplicationRecord
+  after_save :sync_to_crm
+
+  private
+
+  def sync_to_crm
+    # Even if called 100 times in 30 seconds, only ONE job executes
+    SyncContactJob.perform_debounce(id)
+  end
+end
+```
+
+### Multiple arguments
+
+The debouncer creates unique keys based on ALL arguments:
+
+```ruby
+class UpdateTicketJob < ApplicationJob
+  include ActiveJob::Debounce::Concern
+
+  debounce_for 1.minute
+
+  def perform(ticket_id, update_type)
+    # ...
+  end
+end
+
+# These are DIFFERENT debounce windows:
+UpdateTicketJob.perform_debounce(123, "status")   # Window 1
+UpdateTicketJob.perform_debounce(123, "priority") # Window 2
+UpdateTicketJob.perform_debounce(456, "status")   # Window 3
+```
+
+### ActiveRecord objects
+
+Pass ActiveRecord objects directly — serialized via GlobalID:
+
+```ruby
+class SyncTrainingJob < ApplicationJob
+  include ActiveJob::Debounce::Concern
+
+  debounce_for 2.minutes
+
+  def perform(training)
+    training.sync_to_external_service
+  end
+end
+
+training = Training.find(123)
+SyncTrainingJob.perform_debounce(training)
+```
+
+## Configuration
+
+```ruby
+# config/initializers/activejob_debounce.rb
+ActiveJob::Debounce.configure do |config|
+  config.default_delay = 60        # Default debounce window (seconds)
+  config.buffer = 1                # Buffer to prevent race conditions (seconds)
+  config.ttl = 60                  # Redis key TTL safety net (seconds)
+  config.redis_connection = Redis.new(url: ENV['REDIS_URL'])  # Optional
+end
+```
+
+## Crash recovery
+
+If a job crashes without cleanup (worker killed, OOM, etc.), the Redis key holds an expired timestamp. The next `perform_debounce` call detects this and re-queues:
+
+```
+T=0s   Job queued, Redis key set to T+30
+T=30s  Worker crashes — Redis key still holds T+30
+T=45s  New call → GETSET returns T+30 → T+30 <= now → crash detected → re-queue
+```
+
+## How it works internally
+
+Uses Redis `GETSET` for atomic dispatch-time gating:
+
+1. `GETSET key new_timestamp` — atomically reads old value, writes new
+2. If old value is `nil` (no job pending) or expired (crashed) → queue the job
+3. If old value is in the future → job already pending, skip
+4. `after_perform` deletes the key → opens the window for next cycle
+
+This is a **leading-edge** debounce: first event triggers execution after the delay. Subsequent events during the window are dropped.
+
+## Redis key format
+
+```
+activejob_debounce:{JobClass}:{args}
+```
+
+```ruby
+SyncContactJob.debounce_key([123])
+# => "activejob_debounce:SyncContactJob:123"
+
+UpdateTicketJob.debounce_key([user, "full"])
+# => "activejob_debounce:UpdateTicketJob:gid://app/User/456:full"
+```
+
+## Testing
+
+```ruby
+RSpec.describe SyncContactJob do
+  let(:mock_redis) { instance_double("Redis") }
+
+  before do
+    ActiveJob::Debounce.configure { |c| c.redis_connection = mock_redis }
+    allow(mock_redis).to receive(:getset, :expire, :del)
+  end
+
+  it "debounces multiple calls into one job" do
+    allow(mock_redis).to receive(:getset).and_return(nil, (Time.now.to_i + 100).to_s)
+
+    10.times { SyncContactJob.perform_debounce(123) }
+
+    expect(enqueued_jobs.size).to eq(1)
+  end
+end
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/activejob-debounce.gemspec

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "lib/activejob/debounce/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "activejob-debounce"
+  spec.version = ActiveJob::Debounce::VERSION
+  spec.authors = ["Mohamed Bouzentm"]
+  spec.email = ["bouzentoutamohamed@gmail.com"]
+
+  spec.summary = "Leading-edge debounce for ActiveJob. One job per debounce window, atomic Redis gating, crash recovery."
+  spec.description = <<~DESC
+    A zero-dependency debouncing solution for ActiveJob. Uses Redis GETSET for
+    atomic dispatch-time gating — only 1 job enters the queue per debounce window.
+    Subsequent calls are true no-ops (nothing queued). Includes crash recovery
+    via expired timestamp detection. Works with any ActiveJob backend: Sidekiq,
+    GoodJob, Solid Queue, Resque, etc.
+  DESC
+  spec.homepage = "https://github.com/m2cci-bouzentm/activejob-debounce"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activesupport", ">= 6.0"
+  spec.add_dependency "redis", ">= 4.0"
+
+  spec.add_development_dependency "activejob", ">= 6.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

data/lib/activejob/debounce/concern.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/array/wrap"
+require "active_support/core_ext/object/blank"
+
+module ActiveJob
+  module Debounce
+    # Include this concern in your ActiveJob classes to add debouncing behavior.
+    #
+    # When multiple calls to `perform_debounce` are made with the same arguments
+    # within the debounce window, only ONE job will be queued and executed.
+    #
+    # Works with any ActiveJob backend: Sidekiq, GoodJob, Solid Queue, Resque, etc.
+    #
+    # @example Basic usage
+    #   class SyncUserJob < ApplicationJob
+    #     include ActiveJob::Debounce::Concern
+    #
+    #     debounce_for 30.seconds
+    #
+    #     def perform(user_id)
+    #       User.find(user_id).sync_to_crm
+    #     end
+    #   end
+    #
+    #   # Call it multiple times - only one job executes
+    #   10.times { SyncUserJob.perform_debounce(user.id) }
+    #
+    module Concern
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :debounce_settings, default: {}
+
+        after_perform do |job|
+          if self.class.debounce_settings.present?
+            ActiveJob::Debounce.redis.del(self.class.debounce_key(job.arguments))
+          end
+        end
+      end
+
+      class_methods do
+        # Configure the debounce duration for this job class.
+        #
+        # @param duration [Integer, ActiveSupport::Duration] The debounce window
+        def debounce_for(duration)
+          self.debounce_settings = { duration: duration.to_i }
+        end
+
+        alias_method :debounce_for_seconds, :debounce_for
+
+        # Queue a debounced job. If called multiple times with the same arguments
+        # within the debounce window, only one job will be queued.
+        #
+        # @param params [Array] The arguments to pass to the job's perform method
+        def perform_debounce(*params)
+          delay = debounce_settings[:duration] || config.default_delay
+          buffer = config.buffer
+          ttl = config.ttl
+          redis_key = debounce_key(params)
+
+          # Atomic: set new timestamp, get old value
+          scheduled_at = current_timestamp + delay
+          old_timestamp = ActiveJob::Debounce.redis.getset(redis_key, scheduled_at)
+          ActiveJob::Debounce.redis.expire(redis_key, delay + buffer + ttl)
+
+          no_job_pending = old_timestamp.nil?
+          timestamp_expired = old_timestamp.to_i <= current_timestamp
+          should_queue = no_job_pending || timestamp_expired
+
+          return unless should_queue
+
+          set(wait: delay + buffer).perform_later(*params)
+        end
+
+        # Generate a unique Redis key for this job + arguments combination.
+        #
+        # @param params [Array] The job arguments
+        # @return [String] The Redis key
+        def debounce_key(params)
+          params_list = Array.wrap(params).map do |param|
+            param.respond_to?(:to_global_id) ? param.to_global_id.to_s : param.to_s
+          end
+
+          key_string = params_list.join(":")
+          "activejob_debounce:#{name}:#{key_string}"
+        end
+
+        private
+
+        def config
+          ActiveJob::Debounce.configuration
+        end
+
+        def current_timestamp
+          Time.now.to_i
+        end
+      end
+    end
+  end
+end

data/lib/activejob/debounce/configuration.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Debounce
+    class Configuration
+      # Custom Redis connection. If not set, falls back to Redis.current
+      attr_accessor :redis_connection
+
+      # Default debounce delay in seconds (can be overridden per-job)
+      attr_accessor :default_delay
+
+      # Buffer time added to delay to prevent race conditions
+      attr_accessor :buffer
+
+      # TTL for Redis keys (cleanup safety net)
+      attr_accessor :ttl
+
+      def initialize
+        @redis_connection = nil
+        @default_delay = 60
+        @buffer = 1
+        @ttl = 60
+      end
+    end
+  end
+end

data/lib/activejob/debounce/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Debounce
+    VERSION = "1.0.0"
+  end
+end

data/lib/activejob/debounce.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "debounce/version"
+require_relative "debounce/configuration"
+require_relative "debounce/concern"
+
+module ActiveJob
+  module Debounce
+    class Error < StandardError; end
+
+    class << self
+      attr_writer :configuration
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+
+      def redis
+        configuration.redis_connection || Redis.current
+      end
+    end
+  end
+end

data/lib/activejob-debounce.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "activejob/debounce"

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: activejob-debounce
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Mohamed Bouzentm
+bindir: exe
+cert_chain: []
+date: 2026-07-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !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'
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.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'
+description: |
+  A zero-dependency debouncing solution for ActiveJob. Uses Redis GETSET for
+  atomic dispatch-time gating — only 1 job enters the queue per debounce window.
+  Subsequent calls are true no-ops (nothing queued). Includes crash recovery
+  via expired timestamp detection. Works with any ActiveJob backend: Sidekiq,
+  GoodJob, Solid Queue, Resque, etc.
+email:
+- bouzentoutamohamed@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- activejob-debounce.gemspec
+- lib/activejob-debounce.rb
+- lib/activejob/debounce.rb
+- lib/activejob/debounce/concern.rb
+- lib/activejob/debounce/configuration.rb
+- lib/activejob/debounce/version.rb
+homepage: https://github.com/m2cci-bouzentm/activejob-debounce
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/m2cci-bouzentm/activejob-debounce
+  source_code_uri: https://github.com/m2cci-bouzentm/activejob-debounce
+  changelog_uri: https://github.com/m2cci-bouzentm/activejob-debounce/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Leading-edge debounce for ActiveJob. One job per debounce window, atomic
+  Redis gating, crash recovery.
+test_files: []