ruby-clock 2.0.0.beta3 → 2.0.0.beta4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17d680fbe8df5efadea1cfa9123682fd2557828515fabfafad6825476669b368
-  data.tar.gz: d68673fdc64e3985a170d129b6642b00f323256904e4e54c07660bf1d73cd4e3
+  metadata.gz: 8900519602f68a1eb7e0a5b49aa1752c5a42ffb65a16b409b8f12c003237c568
+  data.tar.gz: bb9d30d35bafa38b970f061faa0416bffb66197f5fddd5d46a691c05e04fe82b
 SHA512:
-  metadata.gz: 789d4ba0e97036cf12473ba5d0c6b190ce164e81573738c3f284910fb6de39fb13ae9a1e3342d6c621ede962b105923a05cc7c226c0294aea26dbb3d160c64f8
-  data.tar.gz: 381e0a04c4d0dc0425176d8414939658b669caaa0b1f2c2253c511506800ce01788eac2f4ef8cac9ebbdaac31031171917a8fac1965b4f3098f8f8c7a5b2cc8d
+  metadata.gz: 50482fd2178c9098bd8e2eb1218f56c56596d5983d82571246d5516cd977227a344598f056019027f2b97222ffc8a628eed503ed2d10defea116bfe5d6b953f1
+  data.tar.gz: 5eb78d5f6dffb1d09d09e9d1ada59a0bae9646253f789affec38311237b74b937192b1f7a414b2a5ff3e8fc2b34a3beb6fe1e8fda8a6aeffedfac80941e8a5a5

data/CHANGELOG.md

@@ -1,19 +1,34 @@
 ## 2.0.0 beta
 
+### Features
 * The way the [rails app reloader](https://guides.rubyonrails.org/threading_and_code_execution.html)
   is implemented is now compatible with both rails 6 and 7
-* The setup for rails is now less complicated
 * RUBY_CLOCK_SHUTDOWN_WAIT_SECONDS value is logged when starting
-* Code reorganization so there are no unnecessary methods in top-level Kernel namespace
 * DSL methods are now at the top-level namespace (`schedule.every` → `every`, `schedule.cron` → `cron`)
-* error handler definition is now at the top-level namespace (`def schedule.on_error` → `on_error do`)
-* around callbacks now have a top-level namespace method, which is different from the above in that...
-* multiple around callbacks can be consecutively assigned
+* Error handler definition is now at the top-level namespace (`def schedule.on_error` → `on_error do`)
+* Around callbacks now have a top-level namespace method. `def schedule.around_trigger` → `around_action` - see readme
+* Multiple around callbacks can be consecutively assigned - no need to put all behavior into one action
+* Errors encountered when loading Clockfile (such as incorrect cron syntaxt)
+  will be reported to the error handler
+
+### Anti-Features
+* rake and shell runners are no longer top-level (`shell` → `RubyClock::Runners.shell`, `rake` → `RubyClock::Runners.rake`)
+
+### Code Improvements
+* The code which implements the rails reloader/executor is now less complicated
+* Code reorganization so there are no unnecessary methods in top-level Kernel namespace
+
 
 ### Migrating from ruby-clock version 1 to version 2
 
-* if you have and existing `def schedule.around_trigger`, you will need to change it to use the new
-  `around_action` method. see readme.
+* The top of every Clockfile must begin with `using RubyClock::DSL`
+* rake and shell runners must be invoked like so: `RubyClock::Runners.rake`, `RubyClock::Runners.shell`, etc.
+* If you have an existing `def schedule.around_trigger`, you will need to change it to use the new
+  `around_action` method. Failure to change this will silently appear to keep working,
+  but will break the rails reloader/executor implementation.
+* Your existing Clockfile will still work, but you now have the option to use
+  `every`, `cron`, and `on_error` at the top-level, without referencing `schedule`.
+  See the readme for examples.
 * There is no longer a need to have a binstub in rails. You can delete bin/clock from your app.
 * The invocations (in Procfile, or wherever else you start ruby-clock) should change from
 
@@ -21,9 +36,6 @@
   to
 
       bundle exec clock
-* Your existing Clockfile will still work, but you now have the option to use
-  `every`, `cron`, and `on_error` at the top-level, without referencing `schedule`.
-  See the readme for examples.
 
 ## 1.0.0
 

data/README.md

@@ -50,6 +50,8 @@ Create a file named Clockfile. This will hold your job definitions.
 Define jobs like this:
 
 ```ruby
+using RubyClock::DSL
+
 every('5 minutes') do
   UserDataReports.generate
 end
@@ -90,9 +92,9 @@ You may wish to
 for your jobs. You can do so with the around trigger:
 
 ```ruby
-def schedule.around_trigger(job)
+around_action(job_proc)
   ActiveRecord::Base.uncached do
-    yield
+    job_proc.call
   end
 end
 ```
@@ -142,11 +144,17 @@ add `$stdout.sync = true` to the top of your Clockfile.
 ### Error Handling
 
 You can catch and report errors raised in your jobs by defining an error catcher at
-the top of your Clockfile like this:
+the top of your Clockfile like this. You should handle these two cases so that you can get
+error reports about problems while loading the Clockfile:
 
 ```ruby
 on_error do |job, error|
-  ErrorReporter.track_exception(error)
+  case job
+  when String # this means there was a problem parsing the Clockfile while starting
+    ErrorReporter.track_exception(error, tag: 'clock', severity: 'high')
+  else
+    ErrorReporter.track_exception(error, tag: 'clock', custom_attribute: {job_name: job.identifier})
+  end
 end
 ```
 
@@ -198,7 +206,7 @@ You can run shell commands in your jobs.
 
 ```ruby
 every '1 day' do
-  shell('sh scripts/process_stuff.sh')
+  RubyClock::Runners.shell('sh scripts/process_stuff.sh')
 end
 ```
 
@@ -244,11 +252,12 @@ needing to shell out and start another process.
 
 ```ruby
 every '1 day' do
-  rake('reports:daily')
+  RubyClock::Runners.rake('reports:daily')
 end
 ```
 
-There is also `rake_execute` and `rake_async`. See [the code](https://github.com/jjb/ruby-clock/blob/main/lib/ruby-clock.rb)
+There is also `RubyClock::Runners.rake_execute` and `RubyClock::Runners.rake_async`.
+See [the code](https://github.com/jjb/ruby-clock/blob/main/lib/rake.rb)
 and [this article](https://code.jjb.cc/running-rake-tasks-from-within-ruby-on-rails-code) for more info.
 
 ### Job Identifier
@@ -286,10 +295,12 @@ This can be used for keeping track of job behavior in logs or a
 stats tracker. For example:
 
 ```ruby
-def schedule.on_post_trigger(job, trigger_time)
+around_action(job_proc, job_info)
+  trigger_time = Time.now
+  job_proc.call
   duration = Time.now-trigger_time.to_t
   StatsTracker.value('Clock: Job Execution Time', duration.round(2))
-  StatsTracker.value("Clock: Job #{job.identifier} Execution Time", duration.round(2))
+  StatsTracker.value("Clock: Job #{job_info.identifier} Execution Time", duration.round(2))
   StatsTracker.increment('Clock: Job Executions')
 end
 

data/example-app/Clockfile

@@ -1,6 +1,14 @@
+using RubyClock::DSL
+
 on_error do |job, error|
-  puts "An error has occurred with job #{job.identifier}: #{error.class}: #{error.message}"
+  case job
+  when String
+    puts "#{job}: #{error.class}: #{error.message}"
+  else
+    puts "An error has occurred with job #{job.identifier}: #{error.class}: #{error.message}"
+  end
 end
+
 # on_error do |job, error|
 #   raise error
 # end
@@ -17,24 +25,30 @@ around_action do |job_proc|
   puts "after2"
 end
 
-around_action do |job_proc, job_info|
-  puts "before3 #{job_info.class}"
-  job_proc.call
-  puts "after3"
-end
-
 every('2 seconds') do
   puts "hello from a ruby-clock job"
 end
 
 every('2 seconds') do
-  shell 'say hello'
+  RubyClock::Runners.shell 'say hello'
 end
 
 every('2 seconds') do
-  raise "An error."
+  raise "🐈️ this error is expected, to test the error catcher"
 end
 
 cron('*/10 * * * * *') do
   puts "cron running on every 10th second #{Time.now}"
 end
+
+every('2 seconds') do
+  if defined?(schedule)
+    raise "💥 we do not expect the ruby-clock DSL to be available inside a job, but it is"
+  end
+end
+
+every('2 seconds') do
+  if defined?(shell) || defined?(rake)
+    puts "💥 we do not expect runners to be available inside a job, but it is"
+  end
+end

data/example-app/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    ruby-clock (2.0.0.beta2)
+    ruby-clock (2.0.0.beta4)
       method_source
       rufus-scheduler (~> 3.8)
 

data/example-rails-app/Clockfile

@@ -1,5 +1,19 @@
+using RubyClock::DSL
+
 load '../example-app/Clockfile'
 
 every('2 seconds') do
   puts Example.count
 end
+
+every('2 seconds') do
+  puts Example.check_for_global_method
+end
+
+every('2 seconds') do
+  puts Example.check_for_runner
+end
+
+every('2 seconds') do
+  RubyClock::Runners.rake 'about'
+end

data/example-rails-app/app/models/example.rb

@@ -1,2 +1,18 @@
 class Example < ApplicationRecord
+  def self.check_for_global_method
+    if defined?(schedule)
+      raise "💥 Oh no, the ruby-clock DSL is in the global environment! 💥"
+    else
+      "🦝"
+    end
+  end
+
+  def self.check_for_runner
+    if defined?(shell) || defined?(rake)
+      raise "💥 Oh no, the runners got included in the global environment! 💥"
+    else
+      "🐅"
+    end
+  end
+
 end

data/exe/clock

@@ -1,72 +1,22 @@
 #!/usr/bin/env ruby
 
-begin
-  require './config/environment.rb'
-  puts "Detected rails app has been loaded."
-rescue LoadError
-end
-
 require 'ruby-clock'
-require 'method_source'
-
-class Rufus::Scheduler::Job
-  def identifier
-    @identifier ||= begin
-      name || handler.source.split("\n").reject(&:empty?).grep_v(/#.*/)[-2].strip
-    rescue
-      begin
-        source_location.join('-')
-      rescue
-        'error-calculating-job-identifier'
-      end
-    end
-  end
-end
-
+RubyClock.detect_and_load_rails_app
+require 'rufus_monkeypatch'
 RubyClock.instance.listen_to_signals
 RubyClock.instance.prepare_rake
 RubyClock.instance.schedule.pause
+RubyClock.instance.add_rails_executor_to_around_actions
 
-
-
-## Add methods to top-level namespace
-def schedule
-  RubyClock.instance.schedule
-end
-
-def on_error(&on_error_block)
-  RubyClock.instance.on_error = on_error_block
-  def schedule.on_error(job, error)
-    RubyClock.instance.on_error.call(job, error)
+begin
+  load ARGV[0] || 'Clockfile'
+rescue => clockfile_error
+  if RubyClock.instance.on_error
+    RubyClock.instance.on_error.call("An error has occured while parsing the clockfile", clockfile_error)
   end
-end
-
-def around_action(&b)
-  RubyClock.instance.around_actions << b
-end
-
-def cron(...)
-  RubyClock.instance.schedule.cron(...)
-end
-
-def every(...)
-  RubyClock.instance.schedule.every(...)
-end
-
-def shell(string)
-  RubyClock.instance.shell(string)
-end
-#####################################
 
-
-load ARGV[0] || 'Clockfile'
-
-if defined?(::Rails)
-  around_action do |job_proc|
-    ::Rails.application.reloader.wrap do
-      job_proc.call
-    end
-  end
+  raise
 end
 
+RubyClock.instance.freeze_around_actions
 RubyClock.instance.run_jobs

data/lib/ruby-clock/around_actions.rb

@@ -0,0 +1,33 @@
+module RubyClock::AroundActions
+
+  attr_accessor :around_actions
+
+  def freeze_around_actions
+    @around_actions.freeze
+  end
+
+  def set_up_around_actions
+    @around_actions = []
+    def schedule.around_trigger(job_info, &job_proc)
+      RubyClock.instance.call_with_around_action_stack(
+        RubyClock.instance.around_actions.reverse,
+        job_proc,
+        job_info
+      )
+    end
+  end
+
+  def call_with_around_action_stack(wrappers, job_proc, job_info)
+    case wrappers.count
+    when 0
+      job_proc.call(job_info)
+    else
+      call_with_around_action_stack(
+        wrappers[1..],
+        Proc.new{ wrappers.first.call(job_proc, job_info) },
+        job_info
+      )
+    end
+  end
+
+end

data/lib/ruby-clock/dsl.rb

@@ -0,0 +1,26 @@
+module RubyClock::DSL
+  refine ::Kernel do
+    def schedule
+      RubyClock.instance.schedule
+    end
+
+    def on_error(&on_error_block)
+      RubyClock.instance.on_error = on_error_block
+      def schedule.on_error(job, error)
+        RubyClock.instance.on_error.call(job, error)
+      end
+    end
+
+    def around_action(&b)
+      RubyClock.instance.around_actions << b
+    end
+
+    def cron(...)
+      RubyClock.instance.schedule.cron(...)
+    end
+
+    def every(...)
+      RubyClock.instance.schedule.every(...)
+    end
+  end
+end

data/lib/ruby-clock/rails.rb

@@ -0,0 +1,24 @@
+# There is also rails-relevant code in rake.rb
+module RubyClock::Rails
+  module ClassMethods
+    def detect_and_load_rails_app
+      begin
+        require './config/environment.rb'
+        puts "Detected rails app has been loaded."
+      rescue LoadError
+      end
+    end
+  end
+
+  module InstanceMethods
+    def add_rails_executor_to_around_actions
+      if defined?(::Rails)
+        RubyClock.instance.around_actions << Proc.new do |job_proc|
+          ::Rails.application.executor.wrap do
+            job_proc.call
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby-clock/rake.rb

@@ -0,0 +1,37 @@
+# See https://code.jjb.cc/running-rake-tasks-from-within-ruby-on-rails-code
+module RubyClock::Rake
+  def prepare_rake
+    if defined?(::Rails) && Rails.application
+      Rails.application.load_tasks
+      Rake::Task.tasks.each{|t| t.prerequisites.delete 'environment' }
+      @rake_mutex = Mutex.new
+    else
+      puts <<~MESSAGE
+        Because this is not a rails application, we do not know how to load your
+        rake tasks. You can do this yourself at the top of your Clockfile if you want
+        to run rake tasks from ruby-clock.
+      MESSAGE
+    end
+  end
+
+  # for tasks that don't have dependencies
+  def rake_execute(task)
+    Rake::Task[task].execute
+  end
+
+  # If the task doesn't share dependencies with another task,
+  # or if it does and you know you'll never run tasks such that any overlap
+  def rake_async(task)
+    Rake::Task[task].invoke
+  ensure
+    Rake::Task[task].reenable
+    Rake::Task[task].all_prerequisite_tasks.each(&:reenable)
+  end
+
+  # If the task has shared dependencies and you might run more than one at the same time
+  # This is the safest option and hence the default.
+  def rake(task)
+    @rake_mutex.synchronize { rake_async(task) }
+  end
+
+end

data/lib/ruby-clock/runners.rb

@@ -0,0 +1,23 @@
+# if we ever want to make these available at the top-level using refinements,
+# like we do with the DSL, it doesn't work in Rails because Rails prepends Kernel after
+# we use the refinment. Initial tests show that prepending ActiveSupport::ForkTracker::CoreExtPrivate
+# works, but maybe that's not reliable or has unknown side effects
+# https://stackoverflow.com/questions/74119178/
+
+module RubyClock::Runners
+  def self.shell(string)
+    RubyClock.instance.shell(string)
+  end
+
+  def self.rake(string)
+    RubyClock.instance.rake(string)
+  end
+
+  def self.rake_execute(string)
+    RubyClock.instance.rake_execute(string)
+  end
+
+  def self.rake_async(string)
+    RubyClock.instance.rake_async(string)
+  end
+end

data/lib/ruby-clock/shell.rb

@@ -0,0 +1,38 @@
+module RubyClock::Shell
+  def shell_runner
+    @shell_runner ||= begin
+      require 'terrapin'
+      require 'posix-spawn'
+
+      unless Terrapin::CommandLine.runner.class == Terrapin::CommandLine::PosixRunner
+        puts <<~MESSAGE
+
+          🤷 terrapin and posix-spawn are installed, but for some reason terrapin is
+             not using posix-spawn as its runner.
+
+        MESSAGE
+      end
+
+      puts '🐆 Using terrapin for shell commands.'
+      :terrapin
+    rescue LoadError
+      puts <<~MESSAGE
+
+        🦥 Using ruby backticks for shell commands.
+           For better performance, install the terrapin and posix-spawn gems.
+           See README.md for more info.
+
+      MESSAGE
+      :backticks
+    end
+  end
+
+  def shell(command)
+    case shell_runner
+    when :terrapin
+      Terrapin::CommandLine.new(command).run
+    when :backticks
+      `#{command}`
+    end
+  end
+end

data/lib/ruby-clock/version.rb

@@ -1,3 +1,3 @@
 class RubyClock
-  VERSION = "2.0.0.beta3"
+  VERSION = "2.0.0.beta4"
 end

data/lib/ruby-clock.rb

@@ -1,23 +1,26 @@
+require "ruby-clock/dsl"
 require "ruby-clock/version"
+require "ruby-clock/rake"
+require "ruby-clock/shell"
+require "ruby-clock/around_actions"
+require "ruby-clock/dsl"
+require "ruby-clock/runners"
+require "ruby-clock/rails"
 require 'rufus-scheduler'
 require 'singleton'
 
 class RubyClock
-
   include Singleton
+  include RubyClock::Rails::InstanceMethods
+  extend RubyClock::Rails::ClassMethods
+  include RubyClock::Rake
+  include RubyClock::Shell
+  include RubyClock::AroundActions
 
-  attr_accessor :on_error, :around_actions
+  attr_accessor :on_error
 
   def initialize
-    @around_actions = []
-
-    def schedule.around_trigger(job_info, &job_proc)
-      RubyClock.instance.call_with_around_action_stack(
-        RubyClock.instance.around_actions.reverse,
-        job_proc,
-        job_info
-      )
-    end
+    set_up_around_actions
   end
 
   def wait_seconds
@@ -54,91 +57,4 @@ class RubyClock
     schedule.resume
     schedule.join
   end
-
-  def prepare_rake
-    if defined?(::Rails) && Rails.application
-      Rails.application.load_tasks
-      Rake::Task.tasks.each{|t| t.prerequisites.delete 'environment' }
-      @rake_mutex = Mutex.new
-    else
-      puts <<~MESSAGE
-        Because this is not a rails application, we do not know how to load your
-        rake tasks. You can do this yourself at the top of your Clockfile if you want
-        to run rake tasks from ruby-clock.
-      MESSAGE
-    end
-  end
-
-  # See https://code.jjb.cc/running-rake-tasks-from-within-ruby-on-rails-code
-
-  # for tasks that don't have dependencies
-  def rake_execute(task)
-    Rake::Task[task].execute
-  end
-
-  # If the task doesn't share dependencies with another task,
-  # or if it does and you know you'll never run tasks such that any overlap
-  def rake_async(task)
-    Rake::Task[task].invoke
-  ensure
-    Rake::Task[task].reenable
-    Rake::Task[task].all_prerequisite_tasks.each(&:reenable)
-  end
-
-  # If the task has shared dependencies and you might run more than one at the same time
-  # This is the safest option and hence the default.
-  def rake(task)
-    @rake_mutex.synchronize { rake_async(task) }
-  end
-
-  def shell_runner
-    @shell_runner ||= begin
-      require 'terrapin'
-      require 'posix-spawn'
-
-      unless Terrapin::CommandLine.runner.class == Terrapin::CommandLine::PosixRunner
-        puts <<~MESSAGE
-
-          🤷 terrapin and posix-spawn are installed, but for some reason terrapin is
-             not using posix-spawn as its runner.
-
-        MESSAGE
-      end
-
-      puts '🐆 Using terrapin for shell commands.'
-      :terrapin
-    rescue LoadError
-      puts <<~MESSAGE
-
-        🦥 Using ruby backticks for shell commands.
-           For better performance, install the terrapin and posix-spawn gems.
-           See README.md for more info.
-
-      MESSAGE
-      :backticks
-    end
-  end
-
-  def shell(command)
-    case shell_runner
-    when :terrapin
-      Terrapin::CommandLine.new(command).run
-    when :backticks
-      `#{command}`
-    end
-  end
-
-  def call_with_around_action_stack(wrappers, job_proc, job_info)
-    case wrappers.count
-    when 0
-      job_proc.call(job_info)
-    else
-      call_with_around_action_stack(
-        wrappers[1..],
-        Proc.new{ wrappers.first.call(job_proc, job_info) },
-        job_info
-      )
-    end
-  end
-
 end

data/lib/rufus_monkeypatch.rb

@@ -0,0 +1,14 @@
+require 'method_source'
+class Rufus::Scheduler::Job
+  def identifier
+    @identifier ||= begin
+      name || handler.source.split("\n").reject(&:empty?).grep_v(/#.*/)[-2].strip
+    rescue
+      begin
+        source_location.join('-')
+      rescue
+        'error-calculating-job-identifier'
+      end
+    end
+  end
+end

data/ruby-clock.gemspec

@@ -6,8 +6,17 @@ Gem::Specification.new do |spec|
   spec.authors       = ["John Bachir"]
   spec.email         = ["j@jjb.cc"]
 
-  spec.summary       = 'A "clock" process for invoking ruby code within a persistent runtime'
+  spec.summary       = 'A job scheduler which runs jobs each in their own thread in a persistent process.'
   # spec.description   = %q{TODO: Write a longer description or delete this line.}
+  spec.post_install_message = <<~MESSAGE
+
+    If you are updating ruby-clock from 1→2, there are a few things you need to change in your Clockfile.
+
+    It's quick, easy, and fun! See instructions here:
+    https://github.com/jjb/ruby-clock/blob/main/CHANGELOG.md#migrating-from-ruby-clock-version-1-to-version-2
+
+  MESSAGE
+
   spec.homepage      = "https://github.com/jjb/ruby-clock"
   spec.license       = "MIT"
   spec.required_ruby_version = Gem::Requirement.new(">= 2.7.0")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-clock
 version: !ruby/object:Gem::Version
-  version: 2.0.0.beta3
+  version: 2.0.0.beta4
 platform: ruby
 authors:
 - John Bachir
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-10-16 00:00:00.000000000 Z
+date: 2022-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rufus-scheduler
@@ -142,7 +142,14 @@ files:
 - example-rails-app/vendor/javascript/.keep
 - exe/clock
 - lib/ruby-clock.rb
+- lib/ruby-clock/around_actions.rb
+- lib/ruby-clock/dsl.rb
+- lib/ruby-clock/rails.rb
+- lib/ruby-clock/rake.rb
+- lib/ruby-clock/runners.rb
+- lib/ruby-clock/shell.rb
 - lib/ruby-clock/version.rb
+- lib/rufus_monkeypatch.rb
 - release.md
 - ruby-clock.gemspec
 homepage: https://github.com/jjb/ruby-clock
@@ -151,7 +158,13 @@ licenses:
 metadata:
   homepage_uri: https://github.com/jjb/ruby-clock
   source_code_uri: https://github.com/jjb/ruby-clock
-post_install_message:
+post_install_message: |2+
+
+  If you are updating ruby-clock from 1→2, there are a few things you need to change in your Clockfile.
+
+  It's quick, easy, and fun! See instructions here:
+  https://github.com/jjb/ruby-clock/blob/main/CHANGELOG.md#migrating-from-ruby-clock-version-1-to-version-2
+
 rdoc_options: []
 require_paths:
 - lib
@@ -169,5 +182,7 @@ requirements: []
 rubygems_version: 3.1.6
 signing_key:
 specification_version: 4
-summary: A "clock" process for invoking ruby code within a persistent runtime
+summary: A job scheduler which runs jobs each in their own thread in a persistent
+  process.
 test_files: []
+...