activejob-trackable 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 594ced411f40c4d5be3910a94c4ee0bb0700ac1801f64f8504649205cafb4c06
+  data.tar.gz: 8012522f364548559eedc0d2893f47b6b22db70833609fe0f6ea33032dc07430
+SHA512:
+  metadata.gz: ac3b3c478e2fba992514ee479363224cd552c75af1f1cbd377b78042b32cad14ebf26c57e206704b990e3e96c16a333a525573e4bb837d9d9e99e7feee71237a
+  data.tar.gz: 1ab6df8a2f86e0eec8f26245403e555cabb2dcb29ccb822681c999c3823624dae68a6d964e9700ba9e0950673913c06b6742c05aad8e4b2a47f4924fe4ae0b2c

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2019 Ignatius Reza
+
+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,65 @@
+# ActiveJob::Trackable
+
+[![Gem Version](https://badge.fury.io/rb/activejob-trackable.svg)](https://badge.fury.io/rb/activejob-trackable)
+[![CircleCI](https://circleci.com/gh/ignatiusreza/activejob-trackable.svg?style=svg)](https://circleci.com/gh/ignatiusreza/activejob-trackable)
+[![Maintainability](https://api.codeclimate.com/v1/badges/871ec3dbca5f74174fb4/maintainability)](https://codeclimate.com/github/ignatiusreza/activejob-trackable/maintainability)
+
+`include ActiveJob::Trackable` into any jobs you want to track. Tracking jobs will grant you
+access into the lifetime of each jobs and give you the ability to throttle and debounce similar jobs.
+
+This is useful for cases where you want to make sure that certain jobs are only done at most once
+per certain period or when you want to reschedule/reconfigure previously scheduled jobs
+
+## Usage
+
+This gem is build with composition over inheritance in mind, and so to benefit from it
+you can start by adding `include ActiveJob::Trackable` into any jobs you want to track, e.g.
+
+```ruby
+class SampleJob < ApplicationJob
+  include ActiveJob::Trackable
+
+  trackable debounced: true, throttled: 1.day
+
+  def perform(one, two, three); end
+end
+```
+
+Calling `trackable` configures the trackers behavior, which defaulted to doing nothing.
+Using this, you can tell the trackers to either `:debounced`, `:throttled`, or both.
+
+`ActiveJob::Trackable::Debounced` and `ActiveJob::Trackable::Throttled` is also available as syntactic sugar
+
+## Compatibility
+
+For now, this gem only support `delayed_job` with `activerecord` backend,
+but support for other delayed job backend and other queue adapters are desired.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'activejob-trackable'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install activejob-trackable
+```
+
+## Contributing
+
+Any and all kind of help are welcomed! Especially interested in:
+
+- support for other delayed job backend
+- support for other queue adapters officially supported by `activejob` itself
+
+feel free to file an issue/PR!
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ActiveJob::Trackable'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/lib/activejob/trackable.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'activejob/trackable/railtie'
+require_relative './trackable/tracker'
+require_relative './trackable/core'
+require_relative './trackable/debounced'
+require_relative './trackable/throttled'
+
+module ActiveJob
+  # Extend `ActiveJob::Base` with the ability to track (cancel, reschedule, etc) jobs
+  module Trackable
+    extend ActiveSupport::Concern
+
+    included do
+      include Core
+    end
+  end
+end

data/lib/activejob/trackable/core.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Trackable
+    ##
+    # Extend `ActiveJob::Base` to automatically create a tracker for every enqueued jobs
+    #
+    # Tracker is only created if jobs is registered with a schedule (e.g by setting :wait options)
+    #
+    # Every Tracker will have their own `key`, which will be automatically generated from the
+    # related job class name and the arguments passed in to #perform_later. Trackers are expected
+    # to be unique by `key`.
+    #
+    # The default behaviour for generating key is quite minimalistic, so you might want to override
+    # it if you're passing non-simple-value arguments
+    #
+    # Example:
+    #
+    #   ```
+    #   class DefaultKeyJob < ActiveJob::Base
+    #     include ActiveJob::Trackable
+    #
+    #     def perform(one, two, three); end
+    #   end
+    #
+    #   # will generate tracker whose key = sample_job/foo/bar/1
+    #   DefaultKeyJob.set(wait: 1.day).perform_later('foo', 'bar', 1)
+    #
+    #   class CustomKeyJob < ActiveJob::Base
+    #     include ActiveJob::Trackable
+    #
+    #     def perform(one, two, three, four); end
+    #
+    #     private
+    #
+    #       def key(one, two, three, four)
+    #         "and-a-#{one}-and-a-#{two}-and-a-#{one}-#{two}-#{three}-#{four}"
+    #       end
+    #   end
+    #
+    #   # will generate tracker whose key = "and-a-1-and-a-2-and-a-1-2-3-4"
+    #   CustomKeyJob.set(wait: 1.day).perform_later(1, 2, 3, 4)
+    #   ```
+    #
+    module Core
+      extend ActiveSupport::Concern
+
+      included do
+        mattr_accessor :trackable_options, default: { debounced: false }
+
+        around_enqueue do |_job, block|
+          throttle do
+            block.call
+          end
+        end
+
+        before_enqueue do
+          @tracker = nil
+        end
+
+        after_enqueue do
+          next unless trackable?
+
+          tracker.track_job! self
+        end
+
+        after_perform do
+          tracker&.destroy
+        end
+      end
+
+      ##
+      # Provide `.trackable` class method which can be used to configure tracker behavior
+      #
+      module ClassMethods
+        ##
+        # Configure trackable, supported options:
+        #
+        #   - debounced: boolean (default: false)
+        #   - throttled: duration (default: nil)
+        #
+        def trackable(options)
+          trackable_options.merge! options
+        end
+      end
+
+      def tracker
+        @tracker ||= reuse_tracker? ?
+          Tracker.find_or_initialize_by(key: key(*arguments)) :
+          Tracker.new(key: key(*arguments))
+      end
+
+      private
+
+        def key(*arguments)
+          ([self.class.to_s.underscore] + arguments.map(&:to_s)).join('/')
+        end
+
+        def trackable?
+          if reuse_tracker?
+            tracker.persisted? || (scheduled_at && provider_job_id)
+          else
+            scheduled_at && provider_job_id
+          end
+        end
+
+        def reuse_tracker?
+          debounced? || throttled?
+        end
+
+        def debounced?
+          trackable_options[:debounced]
+        end
+
+        def throttled?
+          trackable_options[:throttled]
+        end
+
+        def throttle
+          return yield unless throttled?
+
+          expires_in = trackable_options[:throttled] + (scheduled_at - Time.current.to_f)
+
+          debounced_throttle(expires_in) { yield } || Rails.cache.fetch(key(*arguments), expires_in: expires_in) do
+            yield
+
+            true # put true into cache instead of serializing the job
+          end
+        end
+
+        def debounced_throttle(expires_in)
+          return unless debounced? && tracker.persisted?
+
+          Rails.cache.write key(*arguments), true, expires_in: expires_in
+
+          yield
+        end
+    end
+  end
+end

data/lib/activejob/trackable/debounced.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Trackable
+    ##
+    # Include `ActiveJob::Trackable::Debounced` to allow debouncing job when multiple jobs with identical keys
+    # are scheduled before it get performed
+    #
+    # Example:
+    #
+    #   ```
+    #   class SampleJob < ActiveJob::Base
+    #     include ActiveJob::Trackable::Debounced
+    #
+    #     def perform(foo, bar)
+    #       # do something
+    #     end
+    #
+    #     private
+    #
+    #       def key(foo, bar)
+    #         foo
+    #       end
+    #   end
+    #
+    #   # schedule a job to run 1.day.from_now
+    #   SampleJob.set(wait: 1.day).perform_later('foo', 'bar')
+    #
+    #   # less than 1 day later, reschedule with updated options & arguments
+    #   SampleJob.set(wait: 2.day).perform_later('foo', 'baz')
+    #   ```
+    #
+    module Debounced
+      extend ActiveSupport::Concern
+
+      included do
+        include Core
+
+        trackable debounced: true
+      end
+    end
+  end
+end

data/lib/activejob/trackable/railtie.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Trackable
+    class Railtie < ::Rails::Railtie
+    end
+  end
+end

data/lib/activejob/trackable/throttled.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Trackable
+    ##
+    # Include `ActiveJob::Trackable::Throttled` to throttle scheduling job when multiple jobs
+    # with identical keys tried to be scheduled before it get performed
+    #
+    # Throtlling period are counted in relative to when the job is scheduled to run.
+    # For example, is a job is configured to throttled every 1 day, and it is scheduled
+    # to run in 5 hours; the throttling will be active for the full duration of 1 day and 5 hours
+    #
+    # Example:
+    #
+    #   ```
+    #   class SampleJob < ActiveJob::Base
+    #     include ActiveJob::Trackable::Throttled
+    #
+    #     trackable throttled: 1.day
+    #
+    #     def perform(one, two, three); end
+    #   end
+    #
+    #   # schedule a job to run 1.hour.from_now
+    #   SampleJob.set(wait: 1.hour).perform_later('foo', 'bar')
+    #
+    #   # less than 1 day later, trying to schedule the same job will silently fail
+    #   SampleJob.set(wait: 2.hour).perform_later('foo', 'bar')
+    #   ```
+    #
+    module Throttled
+      extend ActiveSupport::Concern
+
+      included do
+        include Core
+      end
+    end
+  end
+end

data/lib/activejob/trackable/tracker.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Trackable
+    class Tracker < ActiveRecord::Base # :nodoc:
+      self.table_name = 'active_job_trackers'
+
+      validates :provider_job_id, :key, presence: true
+
+      def track_job!(job)
+        self.class.transaction do
+          job.tracker.provider_job&.destroy!
+          self.provider_job_id = job.provider_job_id
+          save!
+          dememoized!
+        end
+      end
+
+      def job
+        @job ||= ActiveJob::Base.deserialize(job_data).tap do |job|
+          job.provider_job_id = provider_job_id.to_i
+
+          # this sux, but can't find other way around it
+          job.send :deserialize_arguments_if_needed
+          job.scheduled_at = provider_job.run_at.to_f
+        end
+      end
+
+      def reload
+        dememoized!
+        super
+      end
+
+      protected
+
+        def provider_job
+          @provider_job ||= provider_job_id.presence && Delayed::Job.find(provider_job_id)
+        end
+
+      private
+
+        def dememoized!
+          @job = nil
+          @provider_job = nil
+        end
+
+        def job_data
+          provider_job.payload_object.job_data
+        end
+    end
+  end
+end

data/lib/activejob/trackable/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Trackable
+    VERSION = '0.1.1'
+  end
+end

data/lib/generators/active_job/trackable/USAGE

@@ -0,0 +1,8 @@
+Description:
+  Generate activerecord migration for the table related to ActiveJob::Trackable::Tracker
+
+Example:
+  rails generate active_job:trackable
+
+  will create:
+    db/migrate/*_create_active_job_trackers.rb

data/lib/generators/active_job/trackable/templates/migration.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class CreateActiveJobTrackers < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :active_job_trackers, force: true do |t|
+      t.string :provider_job_id, index: true
+      t.string :key, index: { unique: true }
+
+      t.timestamps
+    end
+  end
+end

data/lib/generators/active_job/trackable/trackable_generator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  ##
+  #
+  # Generator for generating activerecord migration for the table related to ActiveJob::Trackable::Tracker
+  #
+  # invoke with `rails generate active_job:trackable`
+  #
+  class TrackableGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+
+    source_root File.expand_path('templates', __dir__)
+
+    def self.next_migration_number(dirname)
+      next_migration_number = current_migration_number(dirname) + 1
+
+      if ActiveRecord::Base.timestamped_migrations
+        [Time.now.utc.strftime('%Y%m%d%H%M%S'), format('%.14d', next_migration_number)].max
+      else
+        format('%.3d', next_migration_number)
+      end
+    end
+
+    def create_migration_file
+      migration_template 'migration.rb', migration_destination, migration_version: migration_version
+    end
+
+    private
+
+      def migration_destination
+        'db/migrate/create_active_job_trackers.rb'
+      end
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]" if ActiveRecord::VERSION::MAJOR >= 5
+      end
+  end
+end

data/lib/tasks/activejob/trackable_tasks.rake

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# desc "Explaining what the task does"
+# task :activejob_trackable do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: activejob-trackable
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Ignatius Reza
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-02-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.2.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.2.2
+- !ruby/object:Gem::Dependency
+  name: minitest-ci
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.6
+description: Get more control into your jobs with the ability to track (debounce,
+  throttle) jobs
+email:
+- lyoneil.de.sire@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/activejob/trackable.rb
+- lib/activejob/trackable/core.rb
+- lib/activejob/trackable/debounced.rb
+- lib/activejob/trackable/railtie.rb
+- lib/activejob/trackable/throttled.rb
+- lib/activejob/trackable/tracker.rb
+- lib/activejob/trackable/version.rb
+- lib/generators/active_job/trackable/USAGE
+- lib/generators/active_job/trackable/templates/migration.rb
+- lib/generators/active_job/trackable/trackable_generator.rb
+- lib/tasks/activejob/trackable_tasks.rake
+homepage: https://github.com/ignatiusreza/activejob-trackable
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.2
+signing_key: 
+specification_version: 4
+summary: Extend ActiveJob with the ability to track (debounce, throttle) jobs
+test_files: []