rocketjob 3.3.4 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d6c4cf70983793dd982cefbc5b58b7ae33d6b8f1
-  data.tar.gz: 2c593219205c7ff16dbd02dce31c57b8c67dcfa9
+  metadata.gz: faa325cab5ef48e8da02dc8310ab2a2098670b7b
+  data.tar.gz: 273ee417e36f6e69123c345d967d92e1efd77c1c
 SHA512:
-  metadata.gz: 6dd940e8008cc81dd36085bc12f705c87a12a348e1edf29c3dbf34c1b6000bcfaf3ed085505968c35f94072f862cd13f524371836b5fe0eb7b0697da7181ca47
-  data.tar.gz: b2e616a1ef53886ea4a5c2fef6c097d3fc640ce9a71971f1ebdb9ee4d1fc1bcd57372773af8e81003d873b4e30eb2497c2708755067b51d3994d8d74104cc288
+  metadata.gz: c833153f3eb38d8e7c5bcdb1c691dc5edc51fbde013e07a0f7a5c488cee848c77b573218c4cb1f04da2b06a6feadb8e30bd435dcbc3516e0291330eff459cd2a
+  data.tar.gz: 70cfc47e8b4383d2d61fc6ed99d4672784a4128ebb03f270a7ef667a1f6217a754d2a6a937e92caf909e9850ca78c85f4bb688aa89e970b3b32369abcfc68863

data/lib/rocket_job/cli.rb

@@ -158,7 +158,7 @@ module RocketJob
           warn '-t and --threads are deprecated, use -w or --workers'
           @workers = arg.to_i
         end
-        o.on('-F', '--filter REGEXP', 'Limit this worker to only those job classes that match this regular expression (case-insensitive)') do |arg|
+        o.on('-F', '--filter REGEXP', 'Limit this worker to only those job classes that match this regular expression (case-insensitive). Example: "DirmonJob|WeeklyReportJob"') do |arg|
           @filter = Regexp.new(arg, true)
         end
         o.on('-q', '--quiet', 'Do not write to stdout, only to logfile. Necessary when running as a daemon') do

data/lib/rocket_job/plugins/cron.rb

@@ -28,14 +28,21 @@ module RocketJob
     # will only run once those jobs have completed, or their priority lowered. Additionally, while the
     # job is queued no additional instances will be enqueued, even if the next cron interval has been reached.
     #
-    # Note:
+    # Notes:
     # - The job will not be restarted if:
     #   - A validation fails after cloning this job.
     #   - The job has expired.
     # - Any time the `cron_schedule` is changed, the `run_at` is automatically set before saving the changes.
-    #   - However, if the `run_at` is explicitly set then it will not be overriden.
+    #   - However, if the `run_at` is explicitly set then it will not be overridden.
+    # - `cron_schedule` is not a required field so that the same job class
+    #   - can be scheduled to run at regular intervals,
+    #   - and run on an ad-hoc basis with custom values.
+    # - On job failure
+    #   - a new future instance is created immediately.
+    #   - the current instance is marked as failed and its cron schedule is set to nil.
+    #     - Prevents the failed instance from creating a new future instance when it completes.
     #
-    # Example:
+    # Example, schedule the job to run at regular intervals:
     #
     # class MyCronJob < RocketJob::Job
     #   include RocketJob::Plugins::Cron
@@ -48,19 +55,41 @@ module RocketJob
     #   end
     # end
     #
-    # # Queue the job for processing using the default cron_schedule specified above
+    # # Queue the job for processing using the default cron_schedule specified above.
     # MyCronJob.create!
     #
-    # # Set the cron schedule:
-    # MyCronJob.create!(cron_schedule: '* 1 * * * America/New_York')
     #
+    # Example, a job that can run at regular intervals, and can be run for ad-hoc reporting etc.:
+    #
+    # class ReportJob < RocketJob::Job
+    #   # Do not set a default cron_schedule so that the job can also be used for ad-hoc work.
+    #   include RocketJob::Plugins::Cron
+    #
+    #   field :start_date, type: Date
+    #   field :end_date,   type: Date
+    #
+    #   def perform
+    #     # Uses `scheduled_at` to take into account any possible delays.
+    #     self.start_at ||= scheduled_at.beginning_of_week.to_date
+    #     self.end_at   ||= scheduled_at.end_of_week.to_date
+    #
+    #     puts "Running report, starting at #{start_date}, ending at #{end_date}"
+    #   end
+    # end
+    #
+    # # Queue the job for processing using a cron_schedule.
+    # # On completion the job will create a new instance to run at a future date.
+    # ReportJob.create!(cron_schedule: '* 1 * * * America/New_York')
+    #
+    # # Queue the job for processing outside of the above cron schedule.
+    # # On completion the job will _not_ create a new instance to run at a future date.
+    # job = ReportJob.create!(start_date: 30.days.ago, end_date: 10.days.ago)
     #
-    # Note:
     #
-    # To prevent multiple instances of the job from running at the same time,
-    # add: "include RocketJob::Plugins::Singleton"
+    # To prevent multiple instances of the job from running at the same time, add the singleton plug-in:
+    #   include RocketJob::Plugins::Singleton
     #
-    # Example: Only allow one instance of the cron job to run at a time:
+    # Example: Only allow one instance of this job to be active at the same time (running, queued, scheduled, or failed):
     #
     # class MyCronJob < RocketJob::Job
     #   # Add `cron_schedule`
@@ -106,14 +135,45 @@ module RocketJob
 
         before_save :rocket_job_set_run_at
 
-        validates_presence_of :cron_schedule
         validates_each :cron_schedule do |record, attr, value|
           begin
-            RocketJob::Plugins::Rufus::CronLine.new(value)
+            RocketJob::Plugins::Rufus::CronLine.new(value) if value
           rescue ArgumentError => exc
             record.errors.add(attr, exc.message)
           end
         end
+
+        private
+
+        # Prevent auto restart if this job does not have a cron schedule.
+        # Overrides: RocketJob::Plugins::Restart#rocket_job_restart_new_instance
+        def rocket_job_restart_new_instance
+          return unless cron_schedule
+          super
+        end
+
+        # On failure:
+        # - create a new instance scheduled to run in the future.
+        # - clear out the `cron_schedule` so this instance will not schedule another instance to run on completion.
+        # Overrides: RocketJob::Plugins::Restart#rocket_job_restart_abort
+        def rocket_job_restart_abort
+          return unless cron_schedule
+          rocket_job_restart_new_instance
+          self.cron_schedule = nil
+        end
+      end
+
+      # Returns [Time] at which this job was intended to run at.
+      #
+      # Takes into account any delays that could occur.
+      # Recommended to use this Time instead of Time.now in the `#perform` since the job could run outside its
+      # intended window. Especially if a failed job is only retried quite sometime later.
+      #
+      # Notes:
+      # * When `cron_schedule` is set, this would be the `run_at` time, otherwise it is the `created_at` time
+      #   since that would be the intended time for which this job is running.
+      def scheduled_at
+        run_at || created_at
       end
 
       # Returns [Time] the next time this job will be scheduled to run at.
@@ -129,6 +189,7 @@ module RocketJob
       private
 
       def rocket_job_set_run_at
+        return unless cron_schedule
         self.run_at = rocket_job_cron_next_time if cron_schedule_changed? && !run_at_changed?
       end
 

data/lib/rocket_job/plugins/job/logger.rb

@@ -21,7 +21,7 @@ module RocketJob
           logger.info('Start #perform')
           logger.measure_info(
             'Completed #perform',
-            metric:             "RocketJob/#{self.class.name}/perform",
+            metric:             "#{self.class.name}/perform",
             log_exception:      :full,
             on_exception_level: :error,
             silence:            log_level,

data/lib/rocket_job/version.rb

@@ -1,3 +1,3 @@
 module RocketJob #:nodoc
-  VERSION = '3.3.4'
+  VERSION = '3.4.0'
 end

data/test/plugins/cron_test.rb

@@ -71,10 +71,9 @@ module Plugins
       end
 
       describe '#valid?' do
-        it 'fails on missing cron schedule' do
+        it 'allows missing cron schedule' do
           @job = CronJob.new
-          refute @job.valid?
-          assert_equal "can't be blank", @job.errors.messages[:cron_schedule].first
+          assert @job.valid?
         end
 
         it 'fails on bad cron schedule' do
@@ -89,6 +88,61 @@ module Plugins
         end
       end
 
+      describe '#fail' do
+        describe 'with cron_schedule' do
+          let :job do
+            job = CronJob.create!(cron_schedule: '* 1 * * *')
+            job.start
+            job.fail
+            job
+          end
+
+          it 'allows current cron job instance to fail' do
+            assert job.failed?
+          end
+
+          it 'clears out cron_schedule' do
+            refute job.cron_schedule
+          end
+
+          it 'retains run_at' do
+            assert job.run_at
+          end
+
+          it 'schedules a new instance' do
+            assert_equal 0, CronJob.count
+            job
+            assert_equal 2, CronJob.count
+            assert scheduled_job = CronJob.last
+            assert scheduled_job.queued?
+            assert_equal '* 1 * * *', scheduled_job.cron_schedule
+          end
+        end
+
+        describe 'without cron_schedule' do
+          let :job do
+            job = CronJob.create!
+            job.start
+            job.fail
+            job
+          end
+
+          it 'allows current cron job instance to fail' do
+            assert job.failed?
+          end
+
+          it 'has no cron_schedule' do
+            refute job.cron_schedule
+          end
+
+          it 'does not schedule a new instance' do
+            assert_equal 0, CronJob.count
+            job
+            assert_equal 1, CronJob.count
+          end
+        end
+      end
+
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rocketjob
 version: !ruby/object:Gem::Version
-  version: 3.3.4
+  version: 3.4.0
 platform: ruby
 authors:
 - Reid Morrison
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-06-30 00:00:00.000000000 Z
+date: 2017-07-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby