cron_swanson 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d117286d60628186a24607e387fb3b51eb4b915d8e75a96d92ebfce8ea51a9ed
-  data.tar.gz: 7d8fb576c1aead5cbe16c2ccd81f1acda7f96149fb725bd780359a4ba8d2360c
+  metadata.gz: 9c4d87324b0351bbf60e5cc586833282618dba613694fd57b22e0e9a7afce9a5
+  data.tar.gz: f64d0020a6be996393b40040d506d880ad5d2a0315a530205ec8d834abdeb273
 SHA512:
-  metadata.gz: 99a782ff24a871fe8f5ea77f5a4e26c06b0af27519f03873dd62d4e2a5e9a2cd7da478230d3283fcb6b9af28ae03b69d7c3ea64f650683bba7d5f6786017abed
-  data.tar.gz: e054da7a55fd73c7a0f8c00e4912f13572467840984b45cb7a1d3041a4c13efdbc9ab965fd13748f26a16eea94afcdad86dba227cf1e2c487d52b97dacd199c8
+  metadata.gz: 13473ea070dfe8f19fde8f9e0439ab571abbc0eb8274499df442fa21c43da86e5bd26942510156250ac8d474aed73725f1ac510c437da92e9cf855ccf95a6a94
+  data.tar.gz: 990e1e3eb6fb5027111646583ecda830c45a38117b1035f748dd553161b8f3bdfacee1bad1e9e5b21d68baf69bc39db4d47fbe4b6599a664f1e90c1711b4c607

data/CHANGELOG.md

@@ -1,6 +1,18 @@
 # Changelog
 
-## 0.2.0 : "Under my utelage, you will grow from boys to men." : November 3, 2019
+## 0.3.0 : "Any dog under 50 pounds is a cat and cats are useless." : November 4, 2019
+
+New feature:
+
+  * Support for seed strings, to allow the same job to have distinct schedules
+    in various apps.
+
+Breaking changes:
+
+  * `whenever` integration changed from class methods to instance methods.
+  * Some methods were renamed.
+
+## 0.2.0 : "Under my tutelage, you will grow from boys to men." : November 3, 2019
 
 Improvements in whenever integration.
 

data/README.md

@@ -1,6 +1,6 @@
 # CronSwanson
 
-`CronSwanson` helps schedule cron jobs.
+`CronSwanson` helps distribute schedule cron jobs.
 
 ![Never half-ass two things.](whole-ass.jpg)
 
@@ -32,24 +32,24 @@ Or install it yourself as:
 
 ## Usage
 
-### schedule
+### build_schedule
 
-Use `schedule` to build a cron schedule. The supplied string is hashed to determine
-the run time of the job.
+Use `build_schedule` to build a cron schedule string. The supplied string is hashed
+to determine the run time of the job.
 
 ```ruby
-CronSwanson.schedule 'whiskey'
+CronSwanson.build_schedule 'whiskey'
 #=> "33 18 * * *"
 ```
 
 **To keep two applications running the same job from executing at once**, make the
-application name part of the schedule key.
+application name part of the build_schedule key.
 
 ```ruby
-CronSwanson.schedule 'application-a whiskey'
+CronSwanson.build_schedule 'application-a whiskey'
 #=> "4 19 * * *"
 
-CronSwanson.schedule 'application-b whiskey'
+CronSwanson.build_schedule 'application-b whiskey'
 #=> "11 7 * * *"
 ```
 
@@ -57,14 +57,14 @@ An `interval` (in seconds) can be supplied if you want a job to be run more than
 once/day. This `interval` must be a factor of 24 hours.
 
 ```ruby
-CronSwanson.schedule 'bacon', interval: 60 * 60 * 4
+CronSwanson.build_schedule 'bacon', interval: 60 * 60 * 4
 #=> "26 2,6,10,14,18,22 * * *"
 ```
 
 You can also use `ActiveSupport::Duration` instances.
 
 ```ruby
-CronSwanson.schedule 'bacon', interval: 4.hours
+CronSwanson.build_schedule 'bacon', interval: 4.hours
 #=> "26 2,6,10,14,18,22 * * *"
 ```
 
@@ -72,17 +72,18 @@ CronSwanson.schedule 'bacon', interval: 4.hours
 
 `CronSwanson` is built to integrate with the fantastic [whenever](https://github.com/javan/whenever) gem.
 
-`CronSwanson::Whenever.add` will calculate a run time for jobs by hashing the text
-of the job definitions in the given block.
+`#schedule` will calculate a run time for jobs by hashing the text of the job
+definitions in the given block. (Plus an optional seed string if one is supplied.)
 
-**NOTE**: This means that if you change the jobs in the block, you will also change the schedule time
-for these jobs.
+**NOTE**: This means that if you change the jobs in the block, or the seed, you will also
+change the schedule time for these jobs.
 
 #### Daily
 
 ```ruby
-# in config/schedule.rb
-CronSwanson::Whenever.add(self) do
+# in config/build_schedule.rb
+swanson = CronSwanson::Whenever.new(self, seed: 'application-name')
+swanson.schedule do
   rake 'sample:job'
 end
 ```
@@ -93,15 +94,17 @@ determined by `CronSwanson`.
 #### Multiple times/day
 
 ```ruby
-# in config/schedule.rb
+# in config/build_schedule.rb
 
 # with ActiveSupport
-CronSwanson::Whenever.add(self, interval: 4.hours) do
+swanson = CronSwanson::Whenever.new(self, seed: 'application-name')
+swanson.schedule(interval: 4.hours) do
   rake 'sample:job'
 end
 
 # without ActiveSupport
-CronSwanson::Whenever.add(self, interval: 60 * 60 * 4) do
+swanson = CronSwanson::Whenever.new(self, seed: 'application-name')
+swanson.schedule(interval: 60 * 60 * 4) do
   rake 'sample:job'
 end
 ```
@@ -111,10 +114,11 @@ end
 Any custom job types which have been defined will work.
 
 ```ruby
-# in config/schedule.rb
+# in config/build_schedule.rb
 job_type :ron, '/usr/bin/ron :task'
 
-CronSwanson::Whenever.add(self) do
+swanson = CronSwanson::Whenever.new(self, seed: 'application-name')
+swanson.schedule do
   ron 'bacon whiskey'
 end
 ```
@@ -125,16 +129,36 @@ Roles are supported. See the [whenever documentation](https://github.com/javan/w
 for more information on this.
 
 ```ruby
-CronSwanson::Whenever.add(self) do
+swanson = CronSwanson::Whenever.new(self, seed: 'application-name')
+swanson.schedule do
   rake 'will_run_on_all_roles'
 end
 
-# will only be added to servers with the :restricted role
-CronSwanson::Whenever.add(self, roles: [:restricted]) do
+# Added to servers with the :restricted role
+swanson.schedule(roles: [:restricted]) do
   rake 'restricted_only'
 end
 ```
 
+#### seeds
+
+Varying the seed string affects all jobs scheduled by that instance.
+
+```ruby
+swanson = CronSwanson::Whenever.new(self, seed: 'application-a')
+swanson.schedule do
+  rake 'job'
+end
+
+swanson = CronSwanson::Whenever.new(self, seed: 'application-b')
+swanson.schedule do
+  rake 'job'
+end
+```
+
+In this example, the job being scheduled is the same, but the schedule times will
+be different because the seed string is different.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/cron_swanson.rb

@@ -36,7 +36,15 @@ module CronSwanson
     offset_seconds
   end
 
-  def self.schedule(job_identifier, interval: default_interval)
+  # generate a cron schedule string
+  #
+  # the same input will always produce the same output.
+  #
+  # @param [String] job_identifier a job to generate a schedule for
+  # @param [Integer, ActiveSupport::Duration] interval how often should the job
+  #   be scheduled to run?
+  # @return [String] a schedule string like '38 4 * * *'
+  def self.build_schedule(job_identifier, interval: default_interval)
     if interval > SECONDS_PER_DAY
       raise ArgumentError, "interval must be less than 1 day (#{SECONDS_PER_DAY} seconds)."
     end

data/lib/cron_swanson/version.rb

@@ -1,3 +1,3 @@
 module CronSwanson
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/cron_swanson/whenever.rb

@@ -1,13 +1,30 @@
 module CronSwanson
   # integration for the whenever gem: https://github.com/javan/whenever
   class Whenever
+    # a seed string which should be unique per application
+    #
+    # causes unique hashes (ie: schedules) to be generated by multiple apps all
+    # scheduling the same job.
+    attr_reader :seed
+
+    def initialize(whenever_job_list, seed: '')
+      if !whenever_job_list.is_a?(::Whenever::JobList)
+        raise ArgumentError, "supply a Whenever::JobList. (In schedule.rb code, use `self`.)"
+      end
+
+      @whenever_job_list = whenever_job_list
+      @seed = seed
+      @in_schedule_method = false
+      @whenever_jobs = []
+    end
+
     # CronSwanson integration for whenever
     #
     # The given block can use any job types understood by your whenever configuration.
     # See https://github.com/javan/whenever#define-your-own-job-types.
     #
     # CronSwanson currently uses the location it is invoked from in schedule.rb
-    # to calculate a job time. This means that moving the `.add` invocation to
+    # to calculate a job time. This means that moving the `.schedule` invocation to
     # a different line in schedule.rb will cause it to be run at a different time.
     #
     # This limitation exists because I (currently) don't know of a way to inspect
@@ -16,7 +33,7 @@ module CronSwanson
     #
     # @example run a job once/day
     #   # in config/schedule.rb
-    #   CronSwanson::Whenever.add(self) do
+    #   CronSwanson::Whenever.schedule(self) do
     #     rake 'job'
     #   end
     #
@@ -24,18 +41,18 @@ module CronSwanson
     #   # in config/schedule.rb
     #
     #   # with ActiveSupport
-    #   CronSwanson::Whenever.add(self, interval: 4.hours) do
+    #   CronSwanson::Whenever.schedule(self, interval: 4.hours) do
     #     rake 'job'
     #   end
     #
     #   # without ActiveSupport
-    #   CronSwanson::Whenever.add(self, interval: 60 * 60 * 4) do
+    #   CronSwanson::Whenever.schedule(self, interval: 60 * 60 * 4) do
     #     rake 'job'
     #   end
     #
     # @example run a job only on servers with a given role
     #   # in config/schedule.rb
-    #   CronSwanson::Whenever.add(self, roles: [:app]) do
+    #   CronSwanson::Whenever.schedule(self, roles: [:app]) do
     #     rake 'job'
     #   end
     #
@@ -44,13 +61,9 @@ module CronSwanson
     # @param [Integer, ActiveSupport::Duration] interval how many seconds do you want between runs
     #   of this job
     # @param [Array<Symbol>] roles capistrano roles that jobs in this block should be deployed to
-    def self.add(whenever_job_list, interval: CronSwanson.default_interval, roles: [], &block)
+    def schedule(interval: CronSwanson.default_interval, roles: [], &block)
+      @in_schedule_method = true
       @whenever_jobs = []
-      @whenever_job_list = whenever_job_list
-
-      if !whenever_job_list.is_a?(::Whenever::JobList)
-        raise ArgumentError, "supply a Whenever::JobList. (In schedule.rb code, use `self`.)"
-      end
 
       raise ArgumentError, "provide a block containing jobs to schedule." if !block_given?
 
@@ -64,23 +77,23 @@ module CronSwanson
         m, args, _block = *job_config
         "#{m} #{args.join}"
       end
-      schedule = CronSwanson.schedule(schedule_seed, interval: interval)
+      schedule = CronSwanson.build_schedule(@seed + schedule_seed.join, interval: interval)
 
       # now that we know when to schedule the jobs, actually pass the block to Whenever
       if roles.size > 0
-        whenever_job_list.every(schedule, roles: roles, &Proc.new)
+        @whenever_job_list.every(schedule, roles: roles, &Proc.new)
       else
-        whenever_job_list.every(schedule, &Proc.new)
+        @whenever_job_list.every(schedule, &Proc.new)
       end
 
-      @whenever_job_list = nil
+      @in_schedule_method = false
     end
 
-    # during .add, we accumulate calls to whenever job types
+    # during .schedule, we accumulate calls to whenever job types
     # this allows us to make a schedule hash from the actual jobs which are defined.
-    def self.method_missing(m, *args, &block)
-      if @whenever_job_list.nil? || @whenever_jobs.nil?
-        raise "#{self.name}.method_missing invoked outside of #{self.name}.add"
+    def method_missing(m, *args, &block)
+      if !@in_schedule_method
+        raise "#{self.class.name}#method_missing invoked outside of #{self.class.name}#schedule"
       end
 
       if @whenever_job_list.respond_to?(m)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cron_swanson
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Alex Dean
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-11-03 00:00:00.000000000 Z
+date: 2019-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -83,8 +83,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6.2
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: distribute common cron jobs so they don't all start at the same moment