cron_swanson 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f5b92fde06c654c2a37b0162a87e0d1701db2d24f28ae707bbfa174d168d73aa
+  data.tar.gz: 33d169cfefdb9e1ab75aca3b93f2aedfc2f6c0d6634df1f9a536115b5a964bc9
+SHA512:
+  metadata.gz: abd309004421dc9cf12886a4e9df6a58717ab51dc74c2cee0ab4fbdbbb4cb4248b462d4d684f6113a0103a8999559eac2cb51580467c6c5ed18b9ac14d73a1b6
+  data.tar.gz: af381bd1b0054755f8a08248962f546db9ce82ea0706657ace6f47fc5c9aa0425266de8295ee39bfe523bfc2b78e3d3243aa94c1eb8a49edd40ac355f7296557

data/.gitignore

@@ -0,0 +1,12 @@
+Gemfile.lock
+/.bundle/
+/.byebug_history
+/.rubocop-http*
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/examples.txt
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,3 @@
+inherit_from:
+  - https://raw.githubusercontent.com/tedconf/code-style-guides/master/linters/rubocop/rubocop.yml
+

data/.ruby-version

@@ -0,0 +1 @@
+2.5.5

data/Gemfile

@@ -0,0 +1,10 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem 'byebug'
+gem 'guard', '~> 2.13'
+gem 'guard-rspec', '~> 4.6'
+gem 'rspec', '~> 3.9'
+gem 'rubocop', '~> 0.67.0'
+gem 'whenever'

data/Guardfile

@@ -0,0 +1,16 @@
+guard :rspec, cmd: "bundle exec rspec" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+end

data/README.md

@@ -0,0 +1,106 @@
+# CronSwanson
+
+CronSwanson can help if you have many systems running the same cron job, but you
+don't want them all to start at exactly the same time. (To prevent daily load
+spikes at midnight, as every single app starts its maintenance cron jobs.)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'cron_swanson'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install cron_swanson
+
+## Usage
+
+### schedule
+
+Use `schedule` to build a cron schedule. The supplied string is hashed to determine
+the run time of the job.
+
+```ruby
+CronSwanson.schedule 'whiskey'
+#=> "33 18 * * *"
+```
+
+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
+#=> "26 2,6,10,14,18,22 * * *"
+```
+
+### Whenever Integration
+
+`CronSwanson` is built to integrate with the fantastic [whenever](https://github.com/javan/whenever) gem.
+
+#### Daily
+
+```ruby
+# in the config/schedule.rb file
+CronSwanson::Whenever.add(self) do
+  rake 'sample:job'
+end
+```
+
+This will result in `rake sample:job` being scheduled once per day, at a time
+determined by `CronSwanson`.
+
+#### Multiple times/day
+
+```ruby
+# in the config/schedule.rb file
+
+# with ActiveSupport
+CronSwanson::Whenever.add(self, interval: 4.hours) do
+  rake 'sample:job'
+end
+
+# without ActiveSupport
+CronSwanson::Whenever.add(self, interval: 60 * 60 * 4) do
+  rake 'sample:job'
+end
+```
+
+#### job types
+
+The block is evaluated by `whenever`, so any custom job types will work.
+
+```ruby
+# in config/schedule.rb
+job_type :ron, '/usr/bin/ron :task'
+
+CronSwanson::Whenever.add(self) do
+  ron 'bacon whiskey'
+end
+```
+
+#### Limitation
+
+The whenever integration code currently derives a scheduled time from the source
+location of the `add` call. This means that moving the `.add` 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
+the contents of a block at runtime. If a way to do this can be found, I
+would prefer to calculate the time based on the block's contents.
+
+## 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.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/alexdean/cron_swanson.

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+task default: :spec

data/bin/_guard-core

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application '_guard-core' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("guard", "_guard-core")

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "cron_swanson"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/guard

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'guard' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("guard", "guard")

data/bin/rspec

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/cron_swanson.gemspec

@@ -0,0 +1,27 @@
+# lib = File.expand_path("../lib", __FILE__)
+# $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+$:.push File.expand_path('../lib', __FILE__)
+require "cron_swanson/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "cron_swanson"
+  spec.version       = CronSwanson::VERSION
+  spec.authors       = ["Alex Dean"]
+  spec.email         = ["github@mostlyalex.com"]
+
+  spec.summary       = "distribute common cron jobs so they don't all start at the same moment"
+  spec.description   = "easily schedule multiple apps to run the same job at different times"
+  spec.homepage      = "https://github.com/alexdean/cron_swanson"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.17"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

data/lib/cron_swanson.rb

@@ -0,0 +1,63 @@
+require "cron_swanson/version"
+require "cron_swanson/whenever"
+require 'digest/sha2'
+
+# CronSwanson is a utility to generate run times for cron jobs which are
+# regular, but which vary per job.
+module CronSwanson
+  SECONDS_PER_HOUR = 60 * 60
+  SECONDS_PER_DAY = SECONDS_PER_HOUR * 24
+
+  def self.default_interval
+    SECONDS_PER_DAY
+  end
+
+  # offset within a time period
+  #
+  # if the interval is 6 hours, the returned offset will be some number of seconds
+  # from 0 to 6 hours.
+  #
+  # @param [String] job_identifier
+  #   if nil, method will determine this on its own
+  # @param [Integer] interval how often will the job be run?
+  # @return [Integer] number of seconds to offset this job
+  def self.offset(job_identifier, interval: default_interval)
+    sha = Digest::SHA256.hexdigest(job_identifier.to_s)
+
+    # largest possible hex sha256 value
+    max_sha256_value = (16**64).to_f
+
+    # what % of the max sha256 is the current app?
+    sha_pct_of_max_sha256 = sha.to_i(16) / max_sha256_value
+
+    # apply that same % to the desired interval to get an offset
+    offset_seconds = (sha_pct_of_max_sha256 * interval).round
+
+    offset_seconds
+  end
+
+  def self.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
+
+    if SECONDS_PER_DAY % interval != 0
+      raise ArgumentError, "A day (#{SECONDS_PER_DAY} seconds) must be evenly " \
+        "divisible by the given interval."
+    end
+
+    # figure out how many times job will happen in a day
+    runs_per_day = SECONDS_PER_DAY / interval
+
+    # raise if runs_per_day has a decimal component.
+
+    run_at = Time.at(offset(job_identifier, interval: interval)).utc
+
+    hours = []
+    runs_per_day.times do |i|
+      hours << run_at.hour + (i * interval / SECONDS_PER_HOUR)
+    end
+
+    "#{run_at.min} #{hours.join(',')} * * *"
+  end
+end

data/lib/cron_swanson/version.rb

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

data/lib/cron_swanson/whenever.rb

@@ -0,0 +1,51 @@
+module CronSwanson
+  # integration for the whenever gem: https://github.com/javan/whenever
+  module Whenever
+    # 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
+    # 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
+    # the contents of a block at runtime. If a way to do this can be found, I
+    # would prefer to calculate the time based on the block's contents.
+    #
+    # @example run a job once/day
+    #   # in the config/schedule.rb file
+    #   CronSwanson::Whenever.add(self) do
+    #     rake 'job'
+    #   end
+    #
+    # @example run a job four times daily
+    #   # in the config/schedule.rb file
+    #
+    #   # with ActiveSupport
+    #   CronSwanson::Whenever.add(self, interval: 4.hours) do
+    #     rake 'job'
+    #   end
+    #
+    #   # without ActiveSupport
+    #   CronSwanson::Whenever.add(self, interval: 60 * 60 * 4) do
+    #     rake 'job'
+    #   end
+    #
+    # @param [Whenever::JobList] whenever_job_list For code in `config/schedule.rb`
+    #   this can be referred to as `self`.
+    # @param [Integer] interval how many seconds do you want between runs of this job
+    def self.add(whenever_job_list, interval: CronSwanson.default_interval, &block)
+      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?
+
+      # TODO: ideally we'd hash the contents of the block, not the location it was defined at
+      schedule = CronSwanson.schedule(block.source_location, interval: interval)
+      whenever_job_list.every(schedule, &Proc.new)
+    end
+  end
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: cron_swanson
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alex Dean
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2019-11-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: easily schedule multiple apps to run the same job at different times
+email:
+- github@mostlyalex.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- Gemfile
+- Guardfile
+- README.md
+- Rakefile
+- bin/_guard-core
+- bin/console
+- bin/guard
+- bin/rspec
+- bin/setup
+- cron_swanson.gemspec
+- lib/cron_swanson.rb
+- lib/cron_swanson/version.rb
+- lib/cron_swanson/whenever.rb
+homepage: https://github.com/alexdean/cron_swanson
+licenses: []
+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: []
+rubyforge_project: 
+rubygems_version: 2.7.6.2
+signing_key: 
+specification_version: 4
+summary: distribute common cron jobs so they don't all start at the same moment
+test_files: []