ruby-clock 0.6.0 → 0.8.0.rc3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0fec8d8c66e1783260e73fad69f39572677871d722d1c62437c94741452340e
-  data.tar.gz: 03e5b84ef4cd5277da5623173ca70887dc3aac0296445e573459050341376b78
+  metadata.gz: 7e8d972bb2c2468f53d943f233e4e799df71a449b6f7b8c00a1ddbea33c54c92
+  data.tar.gz: fc97259d0575bd220f79dd25206128001eece56ec51eda06d95f28d718b65080
 SHA512:
-  metadata.gz: 70134452766d69a5dbebc795cc31babb56ac14b6363aa6416379600fb6fa0546ccc9b131a17342b1376a101acc89ae746a1f9f19795274224a72e9291f9f6eba
-  data.tar.gz: 4aeb5e68d8108f40e10c11b4ea9fe4a3ad390ba4652afcc4e71cbc11c8c49b36be3f4c8b762f17eda1cffc488f1d5b803388bfb5f3e219962c289dd581549f81
+  metadata.gz: 6dcf79cbebb137a9f04e920b8d6ff0f910bd61536e3e666297217aef8d9942c656fca0d67d794c753ab42a9e035be364bcf3d3b6e465058ebfe7e8683fa94fea
+  data.tar.gz: a3ca20e788af53d77d5526aaacb3b7ff4b07e8852e7586fe181e1681985b32b5bce3a9f0a305507be335dfeee7399567a6cd31afe8262b6e0b84db9cd2d9a75a

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+## 0.8.0 RC3
+
+* make terrapin and posix-spawn gems optional
+
+## 0.8.0 RC2
+
+* fix detection of Rails constant, for non-rails apps
+
+## 0.8.0 RC1
+
+* automatically wrap jobs with rails reloader
+* ability to run rake tasks
+* ability to run shell commands
+* nicer shutdown logging, indicating when shutdown process begins and ends
+* fix approach for error fallbacks when when calculating job identifier (probably never encountered)
+
+## 0.7.0
+
+* ability to specify the name of the file with job definitions, e.g. `bundle exec clock clocks/MyClockfile`
+* ability to specify the amount of time ruby-clock will wait before forcing threads to shut down
+
+## 0.6.0
+
+* job identifiers

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ruby-clock (0.6.0)
+    ruby-clock (0.8.0.rc2)
       method_source
       rufus-scheduler (~> 3.8)
 
@@ -9,9 +9,9 @@ GEM
   remote: https://rubygems.org/
   specs:
     concurrent-ruby (1.1.9)
-    et-orbi (1.2.4)
+    et-orbi (1.2.5)
       tzinfo
-    fugit (1.5.0)
+    fugit (1.5.2)
       et-orbi (~> 1.1, >= 1.1.8)
       raabro (~> 1.4)
     method_source (1.0.0)
@@ -30,4 +30,4 @@ DEPENDENCIES
   ruby-clock!
 
 BUNDLED WITH
-   2.1.4
+   2.2.23

data/README.md

@@ -16,6 +16,7 @@ The clock process will respond to signals INT (^c at the command line) and
 TERM (signal sent by environments such as Heroku and other PaaS's when shutting down).
 In both cases, the clock will stop running jobs and give existing jobs 29 seconds
 to stop before killing them.
+You can change this number with `RUBY_CLOCK_SHUTDOWN_WAIT_SECONDS` in the environment.
 
 ## Installation
 
@@ -55,6 +56,11 @@ To start your clock process:
 
     bundle exec clock
 
+To use a file other than Clockfile for job definitions, specify it.
+This will ignore Clockfile and only read jobs from clocks/MyClockfile:
+
+    bundle exec clock clocks/MyClockfile
+
 ### Rails
 
 Install the `clock` binstub and commit to your repo.
@@ -65,6 +71,12 @@ To run your clock process in your app's environment:
 
     bundle exec rails runner bin/clock
 
+To get smarter database connection management (such as in the case of a database restart or upgrade,
+and maybe other benefits) and code reloading in dev (app code, not the code in Clockfile itself),
+jobs are automatically wrapped in the
+[rails app reloader](https://guides.rubyonrails.org/threading_and_code_execution.html).
+
+
 ### Non-Rails
 
 Require your app's code at the top of Clockfile:
@@ -83,6 +95,28 @@ Add this line to your Procfile
 clock: bundle exec rails runner bin/clock
 ```
 
+You might have a main clock for general scheduled jobs, and then standalone ones
+if your system has something where you want to monitor and adjust resources
+for that work more precisely. Here, maybe the main clock needs a 2GB instance,
+and the others each need 1GB all to themselves:
+
+```
+clock: bundle exec rails runner bin/clock
+thing_checker: bundle exec rails runner bin/clock clocks/thing_checker.rb
+thing_reporter: bundle exec rails runner bin/clock clocks/thing_reporter.rb
+```
+
+Because of this feature, do I regret using "Clockfile" instead of, say, "clock.rb"? Maybe.
+
+#### Observing logs
+
+Because STDOUT does not flush until a certain amount of data has gone into it,
+you might not immediately see the ruby-clock startup message or job output if
+viewing logs in a deployed environment such as Heroku where the logs are redirected
+to another process or file. To change this behavior and have logs flush immediately,
+add `$stdout.sync = true` to the top of your Clockfile.
+
+
 ## More Config and Capabilities
 
 ### Error Handling
@@ -102,6 +136,49 @@ You can define before, after, and around callbacks which will run for all jobs.
 Read [the rufus-scheduler documentation](https://github.com/jmettraux/rufus-scheduler/#callbacks)
 to learn how to do this. Where the documentation references `s`, you should use `schedule`.
 
+### Shell commands
+
+You can run shell commands in your jobs.
+
+```ruby
+schedule.every '1 day' do
+  shell('sh scripts/process_stuff.sh')
+end
+```
+
+By default they will be run with
+[ruby backticks](https://livebook.manning.com/concept/ruby/backtick).
+For better performance, install the [terrapin](https://github.com/thoughtbot/terrapin)
+and [posix-spawn](https://github.com/rtomayko/posix-spawn) gems.
+
+`shell` is a convenience method which just passes the string on.
+If you want to use other terrapin features, you can skip the `shell` command
+and use terrapin directly:
+
+```ruby
+schedule.every '1 day' do
+  line = Terrapin::CommandLine.new('optimize_png', ":file")
+  Organization.with_new_logos.find_each do |o|
+    line.run(file: o.logo_file_path)
+    o.update!(logo_optimized: true)
+  end
+end
+```
+
+### Rake tasks
+
+You can run tasks from within the persistent runtime of ruby-clock, without
+needing to shell out and start another process.
+
+```ruby
+schedule.every '1 day' do
+  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)
+and [this article](https://code.jjb.cc/running-rake-tasks-from-within-ruby-on-rails-code) for more info.
+
 ### Job Identifier
 
 ruby-clock adds the `identifier` method to `Rufus::Scheduler::Job`. This method will return the job's
@@ -113,12 +190,12 @@ fallback is the line number of the job in Clockfile.
 Some examples of jobs and their identifiers:
 
 ```ruby
-schedule.every '1 second', name: 'my job' do |variable|
+schedule.every '1 second', name: 'my job' do
   Foo.bar
 end
 # => my job
 
-schedule.every '1 day', name: 'my job' do |variable|
+schedule.every '1 day' do
   daily_things = Foo.setup_daily
   daily_things.process
   # TODO: figure out best time of day
@@ -126,7 +203,7 @@ end
 # => daily_things.process
 
 # n.b. ruby-clock isn't yet smart enough to remove trailing comments
-schedule.every '1 week', name: 'my job' do |variable|
+schedule.every '1 week' do
   weekly_things = Foo.setup_weekly
   weekly_things.process # does this work???!1~
 end
@@ -168,6 +245,14 @@ so anything you can do on this instance, you can do in your Clockfile.
 Perhaps in the future ruby-clock will add some easier specific configuration
 capabilities for some things. Let me know if you have a request!
 
+## Syntax highlighting for Clockfile
+
+To tell github and maybe other systems to syntax highlight Clockfile, put this in a .gitattributes file:
+
+```gitattributes
+Clockfile linguist-language=Ruby
+```
+
 
 ## License
 

data/example-app/.gitattributes

@@ -0,0 +1 @@
+Clockfile linguist-language=Ruby

data/example-app/Clockfile

@@ -0,0 +1,11 @@
+def schedule.on_error(job, error)
+  raise error
+end
+
+schedule.every('2 seconds') do
+  puts "hello from a ruby-clock job"
+end
+
+schedule.every('2 seconds') do
+  shell 'say hello'
+end

data/example-app/Gemfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem 'ruby-clock', path: '../'
+# gem 'terrapin'
+# gem 'posix-spawn'

data/example-app/Gemfile.lock

@@ -0,0 +1,31 @@
+PATH
+  remote: ..
+  specs:
+    ruby-clock (0.8.0.rc2)
+      method_source
+      rufus-scheduler (~> 3.8)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    concurrent-ruby (1.1.9)
+    et-orbi (1.2.5)
+      tzinfo
+    fugit (1.5.2)
+      et-orbi (~> 1.1, >= 1.1.8)
+      raabro (~> 1.4)
+    method_source (1.0.0)
+    raabro (1.4.0)
+    rufus-scheduler (3.8.0)
+      fugit (~> 1.1, >= 1.1.6)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+
+PLATFORMS
+  arm64-darwin-20
+
+DEPENDENCIES
+  ruby-clock!
+
+BUNDLED WITH
+   2.2.28

data/example-app/README.md

@@ -0,0 +1,9 @@
+This is a bare-bones example non-rails app to
+help with dev and also as an example for users.
+
+To run:
+
+```
+bundle
+bundle exe clock
+```

data/exe/clock

@@ -8,9 +8,11 @@ class Rufus::Scheduler::Job
     @identifier ||= begin
       name || handler.source.split("\n").reject(&:empty?).grep_v(/#.*/)[-2].strip
     rescue
-      source_location.join('-')
-    rescue
-      'error-calculating-job-identifier'
+      begin
+        source_location.join('-')
+      rescue
+        'error-calculating-job-identifier'
+      end
     end
   end
 end
@@ -18,7 +20,20 @@ end
 include RubyClock
 
 listen_to_signals
+prepare_rake
+schedule.pause
+
+load ARGV[0] || 'Clockfile'
 
-load 'Clockfile'
+if defined?(::Rails)
+  schedule.instance_eval do
+    @old_around_trigger = method :around_trigger
+    def around_trigger(job)
+      ::Rails.application.reloader.wrap do
+        @old_around_trigger.call(job){ yield }
+      end
+    end
+  end
+end
 
 run_jobs

data/lib/ruby-clock/version.rb

@@ -1,3 +1,3 @@
 module RubyClock
-  VERSION = "0.6.0"
+  VERSION = "0.8.0.rc3"
 end

data/lib/ruby-clock.rb

@@ -3,8 +3,10 @@ require 'rufus-scheduler'
 
 module RubyClock
   def shutdown
-    puts "Shutting down ruby-clock 🐈️ 👋"
-    Rufus::Scheduler.singleton.shutdown(wait: 29)
+    wait_seconds = ENV['RUBY_CLOCK_SHUTDOWN_WAIT_SECONDS']&.to_i || 29
+    puts "Shutting down ruby-clock. Waiting #{wait_seconds} seconds for jobs to finish..."
+    schedule.shutdown(wait: wait_seconds)
+    puts "...done 🐈️ 👋"
   end
 
   def listen_to_signals
@@ -27,6 +29,81 @@ module RubyClock
 
   def run_jobs
     puts "Starting ruby-clock with #{schedule.jobs.size} jobs"
-    Rufus::Scheduler.singleton.join
+    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-cron.
+      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
+
 end

data/release.md

@@ -0,0 +1,4 @@
+1. update lib/ruby-clock/version.rb
+2. update CHANGELOG.md
+3. commit and push to github
+3. `rake release`

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-clock
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0.rc3
 platform: ruby
 authors:
 - John Bachir
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-07-14 00:00:00.000000000 Z
+date: 2021-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rufus-scheduler
@@ -47,6 +47,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
@@ -54,9 +55,15 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- example-app/.gitattributes
+- example-app/Clockfile
+- example-app/Gemfile
+- example-app/Gemfile.lock
+- example-app/README.md
 - exe/clock
 - lib/ruby-clock.rb
 - lib/ruby-clock/version.rb
+- release.md
 - ruby-clock.gemspec
 homepage: https://github.com/jjb/ruby-clock
 licenses:
@@ -75,11 +82,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.2.22
 signing_key:
 specification_version: 4
 summary: A "clock" process for invoking ruby code within a persistent runtime