ruby-clock 1.0.0 → 2.0.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb7709e5cb45330de5b30adb906cc15e847207894a2ad71b3afd706ea0235f09
-  data.tar.gz: 9ab66e406ada9646d83f28806c07018641953b7b56f8824b49e14b3bd2ad2b7c
+  metadata.gz: 9fdfa3656f0ffbdf60b162a594809e29e9f0579cf3f5f52e98ffd857a811c348
+  data.tar.gz: f63dd579f2cd258f89f17666338ec9d433a63e2b93d0a400975ee6c1e61886fa
 SHA512:
-  metadata.gz: d14858bb6c936e07e66527c9f670d68e236d56ccce407da9c5472334748a3b3f07012f82ff827fb314557b318a555a0e50ff9914b36330fe9cbd7c271da76532
-  data.tar.gz: '033369b93174cdba782d21fa150f63f521bf058d9ef6a654fbb54fd53e2b529f753350b5e086aa2b7e5df2cd0647cf9f932aceb6aaeabba892727dfb978ed1a8'
+  metadata.gz: 938ec658ba3837be8a90c49fdd8d2d6a050b1b6a19486bc2b10479e81370ed3fe5c0e4501293b02a2c8efcfe82d67974e887c2069270986f3398b89762c04707
+  data.tar.gz: c3376b79456a66c2b3c1eb5492b9a0429e69ece7b5207a73d2792c8830c33355c14dc622c2a37e8b6b8e2b9b27cdaaa4d0c83449e6e9c8aca3ae2538e2a90af0

data/CHANGELOG.md

@@ -1,3 +1,26 @@
+## 2.0.0 beta
+
+* 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`)
+
+### Migrating from ruby-clock version 1 to version 2
+
+* 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
+
+      bundle exec rails runner bin/clock
+  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
 
 * make terrapin and posix-spawn gems optional

data/README.md

@@ -1,9 +1,17 @@
+THESE ARE THE DOCS FOR VERSION 2.0.0.beta2
+
+See version 1 docs here: https://github.com/jjb/ruby-clock/tree/v1.0.0
+
 # ruby-clock
 
 ruby-clock is a [job scheduler](https://en.wikipedia.org/wiki/Job_scheduler),
 known by heroku as a [clock process](https://devcenter.heroku.com/articles/scheduled-jobs-custom-clock-processes).
 In many cases it can replace the use of cron.
 
+Why another ruby scheduler project? See
+[this feature matrix of the space](https://docs.google.com/spreadsheets/d/148VMKY9iyOyUASYytSGiUJKvH0-O5Ri-3Cwr3S6DRPU/edit?usp=sharing).
+Feel free to leave a comment with suggestions for changes or additions.
+
 This gem is very small with very few lines of code. For all its scheduling capabilities,
 it relies on the venerable [rufus-scheduler](https://github.com/jmettraux/rufus-scheduler/).
 rufus-scheduler
@@ -20,6 +28,8 @@ You can change this number with `RUBY_CLOCK_SHUTDOWN_WAIT_SECONDS` in the enviro
 
 ## Installation
 
+ruby >= 2.7 is required.
+
 Add these lines to your application's Gemfile:
 
 ```ruby
@@ -37,17 +47,15 @@ Or install it yourself as:
 ## Usage
 
 Create a file named Clockfile. This will hold your job definitions.
-The DSL and capabilities
-are the same as those of [rufus-scheduler](https://github.com/jmettraux/rufus-scheduler/).
-Read the rufus-scheduler documentation to see what you can do.
+Define jobs like this:
 
 ```ruby
-schedule.every('5 minutes') do
+every('5 minutes') do
   UserDataReports.generate
 end
 
 # do something every day, five minutes after midnight
-schedule.cron '5 0 * * *' do
+cron '5 0 * * *' do
   DailyActivitySummary.generate_and_send
 end
 ```
@@ -63,13 +71,9 @@ This will ignore Clockfile and only read jobs from clocks/MyClockfile:
 
 ### Rails
 
-Install the `clock` binstub and commit to your repo.
-
-    bundle binstubs ruby-clock
-
 To run your clock process in your app's environment:
 
-    bundle exec rails runner bin/clock
+    bundle exec 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),
@@ -78,6 +82,7 @@ jobs are automatically wrapped in the
 This [may incur a performance impact for certain jobs](https://github.com/rails/rails/issues/43504),
 I'm still exploring this.
 
+
 #### ActiveRecord Query Cache
 
 You may wish to
@@ -98,7 +103,7 @@ Require your app's code at the top of Clockfile:
 
 ```ruby
 require_relative './lib/app.rb'
-schedule.every('5 minutes') do
+every('5 minutes') do
 ...
 ```
 
@@ -107,7 +112,7 @@ schedule.every('5 minutes') do
 Add this line to your Procfile
 
 ```
-clock: bundle exec rails runner bin/clock
+clock: bundle exec clock
 ```
 
 You might have a main clock for general scheduled jobs, and then standalone ones
@@ -116,9 +121,9 @@ 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
+clock: bundle exec clock
+thing_checker: bundle exec clock clocks/thing_checker.rb
+thing_reporter: bundle exec clock clocks/thing_reporter.rb
 ```
 
 Because of this feature, do I regret using "Clockfile" instead of, say, "clock.rb"? Maybe.
@@ -140,7 +145,7 @@ You can catch and report errors raised in your jobs by defining an error catcher
 the top of your Clockfile like this:
 
 ```ruby
-def schedule.on_error(job, error)
+on_error do |job, error|
   ErrorReporter.track_exception(error)
 end
 ```
@@ -156,7 +161,7 @@ to learn how to do this. Where the documentation references `s`, you should use
 You can run shell commands in your jobs.
 
 ```ruby
-schedule.every '1 day' do
+every '1 day' do
   shell('sh scripts/process_stuff.sh')
 end
 ```
@@ -171,7 +176,7 @@ If you want to use other terrapin features, you can skip the `shell` command
 and use terrapin directly:
 
 ```ruby
-schedule.every '1 day' do
+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)
@@ -191,8 +196,8 @@ Until this is figured out, if you are concerned about jobs exiting inelegantly,
 you may want to run your shell jobs in their own separate clock process.
 
 ```
-bundle exec rails runner bin/clock clocks/main_jobs.rb
-bundle exec rails runner bin/clock clocks/shell_jobs.rb
+bundle exec clock clocks/main_jobs.rb
+bundle exec clock clocks/shell_jobs.rb
 ```
 
 
@@ -202,7 +207,7 @@ 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
+every '1 day' do
   rake('reports:daily')
 end
 ```
@@ -221,12 +226,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
+every '1 second', name: 'my job' do
   Foo.bar
 end
 # => my job
 
-schedule.every '1 day' do
+every '1 day' do
   daily_things = Foo.setup_daily
   daily_things.process
   # TODO: figure out best time of day
@@ -234,7 +239,7 @@ end
 # => daily_things.process
 
 # n.b. ruby-clock isn't yet smart enough to remove trailing comments
-schedule.every '1 week' do
+every '1 week' do
   weekly_things = Foo.setup_weekly
   weekly_things.process # does this work???!1~
 end
@@ -252,7 +257,7 @@ def schedule.on_post_trigger(job, trigger_time)
   StatsTracker.increment('Clock: Job Executions')
 end
 
-schedule.every '10 seconds', name: 'thread stats' do
+every '10 seconds', name: 'thread stats' do
   thread_usage = Hash.new(0)
   schedule.work_threads(:active).each do |t|
     thread_usage[t[:rufus_scheduler_job].identifier] += 1
@@ -267,14 +272,17 @@ schedule.every '10 seconds', name: 'thread stats' do
 end
 ```
 
-### other rufus-scheduler Options
+### Other rufus-scheduler Options
 
-All rufus-scheduler options are set to defaults. The `schedule` variable
-available in your Clockfile is an instance of `Rufus::Scheduler`,
-so anything you can do on this instance, you can do in your Clockfile.
+All [rufus-scheduler](https://github.com/jmettraux/rufus-scheduler/) options are set to defaults.
+There is a `schedule` variable available in your Clockfile, which is the singleton instance of `Rufus::Scheduler`.
+ruby-clock methods such as `every` and `cron` are convenience methods which invoke `schedule.every`
+and `schedule.cron`.
+Anything you can do on this instance, you can do in your Clockfile.
+See the rufus-scheduler documentation to see what you can do.
 
-Perhaps in the future ruby-clock will add some easier specific configuration
-capabilities for some things. Let me know if you have a request!
+If you have ideas for rufus-scheduler features that can be brought in as
+more abstract or default ruby-clock behavior, let me know!
 
 ## Syntax highlighting for Clockfile
 

data/example-app/Clockfile

@@ -1,11 +1,15 @@
-def schedule.on_error(job, error)
+on_error do |job, error|
   raise error
 end
 
-schedule.every('2 seconds') do
+every('2 seconds') do
   puts "hello from a ruby-clock job"
 end
 
-schedule.every('2 seconds') do
+every('2 seconds') do
   shell 'say hello'
 end
+
+cron('*/10 * * * * *') do
+  puts "cron running on every 10th second #{Time.now}"
+end

data/example-rails-app/.gitattributes

@@ -0,0 +1,9 @@
+# See https://git-scm.com/docs/gitattributes for more about git attribute files.
+
+# Mark the database schema as having been generated.
+db/schema.rb linguist-generated
+
+# Mark any vendored files as having been vendored.
+vendor/* linguist-vendored
+
+Clockfile linguist-language=Ruby

data/example-rails-app/.gitignore

@@ -0,0 +1,35 @@
+# See https://help.github.com/articles/ignoring-files for more about ignoring files.
+#
+# If you find yourself ignoring temporary files generated by your text editor
+# or operating system, you probably want to add a global ignore instead:
+#   git config --global core.excludesfile '~/.gitignore_global'
+
+# Ignore bundler config.
+/.bundle
+
+# Ignore the default SQLite database.
+/db/*.sqlite3
+/db/*.sqlite3-*
+
+# Ignore all logfiles and tempfiles.
+/log/*
+/tmp/*
+!/log/.keep
+!/tmp/.keep
+
+# Ignore pidfiles, but keep the directory.
+/tmp/pids/*
+!/tmp/pids/
+!/tmp/pids/.keep
+
+# Ignore uploaded files in development.
+/storage/*
+!/storage/.keep
+/tmp/storage/*
+!/tmp/storage/
+!/tmp/storage/.keep
+
+/public/assets
+
+# Ignore master key for decrypting credentials and more.
+/config/master.key

data/example-rails-app/.ruby-version

@@ -0,0 +1 @@
+2.7.5

data/example-rails-app/Clockfile

@@ -0,0 +1,23 @@
+on_error do |job, error|
+  puts "An error has occurred: #{error.class}: #{error.message}"
+end
+
+every('2 seconds') do
+  puts "hello from a ruby-clock job"
+end
+
+every('2 seconds') do
+  shell 'say hello'
+end
+
+every('2 seconds') do
+  puts Example.count
+end
+
+every('2 seconds') do
+  raise "An error."
+end
+
+cron('*/10 * * * * *') do
+  puts "cron running on every 10th second #{Time.now}"
+end

data/example-rails-app/Gemfile

@@ -0,0 +1,74 @@
+source "https://rubygems.org"
+git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
+ruby "2.7.5"
+
+gem 'ruby-clock', path: '../'
+
+# Bundle edge Rails instead: gem "rails", github: "rails/rails", branch: "main"
+gem "rails", "~> 7.0.4"
+
+# The original asset pipeline for Rails [https://github.com/rails/sprockets-rails]
+gem "sprockets-rails"
+
+# Use sqlite3 as the database for Active Record
+gem "sqlite3", "~> 1.4"
+
+# Use the Puma web server [https://github.com/puma/puma]
+gem "puma", "~> 5.0"
+
+# Use JavaScript with ESM import maps [https://github.com/rails/importmap-rails]
+gem "importmap-rails"
+
+# Hotwire's SPA-like page accelerator [https://turbo.hotwired.dev]
+gem "turbo-rails"
+
+# Hotwire's modest JavaScript framework [https://stimulus.hotwired.dev]
+gem "stimulus-rails"
+
+# Build JSON APIs with ease [https://github.com/rails/jbuilder]
+gem "jbuilder"
+
+# Use Redis adapter to run Action Cable in production
+gem "redis", "~> 4.0"
+
+# Use Kredis to get higher-level data types in Redis [https://github.com/rails/kredis]
+# gem "kredis"
+
+# Use Active Model has_secure_password [https://guides.rubyonrails.org/active_model_basics.html#securepassword]
+# gem "bcrypt", "~> 3.1.7"
+
+# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
+gem "tzinfo-data", platforms: %i[ mingw mswin x64_mingw jruby ]
+
+# Reduces boot times through caching; required in config/boot.rb
+gem "bootsnap", require: false
+
+# Use Sass to process CSS
+# gem "sassc-rails"
+
+# Use Active Storage variants [https://guides.rubyonrails.org/active_storage_overview.html#transforming-images]
+# gem "image_processing", "~> 1.2"
+
+group :development, :test do
+  # See https://guides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem
+  gem "debug", platforms: %i[ mri mingw x64_mingw ]
+end
+
+group :development do
+  # Use console on exceptions pages [https://github.com/rails/web-console]
+  gem "web-console"
+
+  # Add speed badges [https://github.com/MiniProfiler/rack-mini-profiler]
+  # gem "rack-mini-profiler"
+
+  # Speed up commands on slow machines / big apps [https://github.com/rails/spring]
+  # gem "spring"
+end
+
+group :test do
+  # Use system testing [https://guides.rubyonrails.org/testing.html#system-testing]
+  gem "capybara"
+  gem "selenium-webdriver"
+  gem "webdrivers"
+end

data/example-rails-app/README.md

@@ -0,0 +1,12 @@
+This is a bare-bones example rails 7 app to
+help with dev and also as an example for users.
+
+The only interesting thing is in Clockfile
+
+To run:
+
+```
+bundle
+bundle exec rails db:migrate
+bundle exec rails runner bin/clock
+```

data/example-rails-app/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require_relative "config/application"
+
+Rails.application.load_tasks

data/example-rails-app/app/assets/config/manifest.js

@@ -0,0 +1,4 @@
+//= link_tree ../images
+//= link_directory ../stylesheets .css
+//= link_tree ../../javascript .js
+//= link_tree ../../../vendor/javascript .js

data/example-rails-app/app/assets/stylesheets/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS (and SCSS, if configured) file within this directory, lib/assets/stylesheets, or any plugin's
+ * vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/example-rails-app/app/channels/application_cable/channel.rb

@@ -0,0 +1,4 @@
+module ApplicationCable
+  class Channel < ActionCable::Channel::Base
+  end
+end

data/example-rails-app/app/channels/application_cable/connection.rb

@@ -0,0 +1,4 @@
+module ApplicationCable
+  class Connection < ActionCable::Connection::Base
+  end
+end

data/example-rails-app/app/controllers/application_controller.rb

@@ -0,0 +1,2 @@
+class ApplicationController < ActionController::Base
+end

data/example-rails-app/app/helpers/application_helper.rb

@@ -0,0 +1,2 @@
+module ApplicationHelper
+end

data/example-rails-app/app/javascript/application.js

@@ -0,0 +1,3 @@
+// Configure your import map in config/importmap.rb. Read more: https://github.com/rails/importmap-rails
+import "@hotwired/turbo-rails"
+import "controllers"

data/example-rails-app/app/javascript/controllers/application.js

@@ -0,0 +1,9 @@
+import { Application } from "@hotwired/stimulus"
+
+const application = Application.start()
+
+// Configure Stimulus development experience
+application.debug = false
+window.Stimulus   = application
+
+export { application }

data/example-rails-app/app/javascript/controllers/hello_controller.js

@@ -0,0 +1,7 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  connect() {
+    this.element.textContent = "Hello World!"
+  }
+}

data/example-rails-app/app/javascript/controllers/index.js

@@ -0,0 +1,11 @@
+// Import and register all your controllers from the importmap under controllers/*
+
+import { application } from "controllers/application"
+
+// Eager load all controllers defined in the import map under controllers/**/*_controller
+import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
+eagerLoadControllersFrom("controllers", application)
+
+// Lazy load controllers as they appear in the DOM (remember not to preload controllers in import map!)
+// import { lazyLoadControllersFrom } from "@hotwired/stimulus-loading"
+// lazyLoadControllersFrom("controllers", application)

data/example-rails-app/app/jobs/application_job.rb

@@ -0,0 +1,7 @@
+class ApplicationJob < ActiveJob::Base
+  # Automatically retry jobs that encountered a deadlock
+  # retry_on ActiveRecord::Deadlocked
+
+  # Most jobs are safe to ignore if the underlying records are no longer available
+  # discard_on ActiveJob::DeserializationError
+end

data/example-rails-app/app/mailers/application_mailer.rb

@@ -0,0 +1,4 @@
+class ApplicationMailer < ActionMailer::Base
+  default from: "from@example.com"
+  layout "mailer"
+end

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

@@ -0,0 +1,3 @@
+class ApplicationRecord < ActiveRecord::Base
+  primary_abstract_class
+end

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

@@ -0,0 +1,2 @@
+class Example < ApplicationRecord
+end

data/example-rails-app/app/views/layouts/application.html.erb

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>ExampleRailsApp</title>
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+
+    <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
+    <%= javascript_importmap_tags %>
+  </head>
+
+  <body>
+    <%= yield %>
+  </body>
+</html>

data/example-rails-app/app/views/layouts/mailer.html.erb

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <style>
+      /* Email styles need to be inline */
+    </style>
+  </head>
+
+  <body>
+    <%= yield %>
+  </body>
+</html>

data/example-rails-app/app/views/layouts/mailer.text.erb

@@ -0,0 +1 @@
+<%= yield %>