scheddy 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7f3ff142fb2059d543a17e05efa0e607e1a762419a1e14bd6c79c82eb4806872
+  data.tar.gz: a3a1a9a1975148811f85bdc36a92df7d83bada860e2ca9ad7a1f06eabacac40e
+SHA512:
+  metadata.gz: 95d9325b4fa7985dc777b0d722a0a4b5a81ac13a382e0d73e1547c16182442d6f5a073bd17f16d81332876f85c344e2a4180108546fee39f383fcd3dd8d3b03b
+  data.tar.gz: 16cff8b03fc9d4c608f61d41db7d624e532e4e77d92d1e9bb6233c0603b627f38ad2964a5fee39dd4a136679f0b7f38bf1ba34708f1f70925f872ca5596fc54f

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright 2023 thomas morgan
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,266 @@
+# Scheddy
+
+Scheddy is a batteries-included task scheduler for Rails. It is intended as a replacement for cron and cron-like functionality (including job queue specific schedulers), with some useful differences.
+
+* Flexible scheduling. Handles fixed times (Monday at 9am), intervals (every 15 minutes), and tiny intervals (every 5 seconds).
+* Tiny intervals are great for scheduling workload specific jobs (database field `next_run_at`).
+* Catch up missed tasks. Designed for environments with frequent deploys. Also useful in dev where the scheduler isn't always running.
+* Job-queue agnostic. Works great with various ActiveJob adapters and non-ActiveJob queues too.
+* Minimal dependencies. Uses your existing database; doesn't require Redis.
+* Tasks and their schedules are versioned as part of your code.
+
+
+
+## Installation
+Add to your application's `Gemfile`:
+
+```ruby
+gem "scheddy"
+```
+
+After running `bundle install`, add the migration to your app:
+```bash
+bin/rails scheddy:install:migrations
+bin/rails db:migrate
+```
+
+FYI, if all tasks set `track_runs false`, the migration can be skipped.
+
+
+
+## Usage
+
+Scheddy is configured with a straightforward DSL.
+
+For clarity, Scheddy's units of work are referred to as Tasks. This is to differentiate them from background queue Jobs, like those run via ActiveJob. Scheddy's tasks have no relation to rake tasks.
+
+
+Start by creating `config/initializers/scheddy.rb`:
+
+```ruby
+Scheddy.config do
+
+  ## Fixed times
+  task 'monday reports' do
+    run_at '0 9 * * mon'  # cron syntax
+    # run_at 'monday 9am' # use fugit's natural language parsing
+    # track_runs false    # defaults to true for run_at() jobs
+    perform do
+      ReportJob.perform_later
+    end
+  end
+
+  task 'tuesday reports' do
+    run_when day: :tue, hour: 9..16, minute: [0,30]
+      # a native ruby syntax is also supported
+      #   :day    - day of week
+      #   :month
+      #   :date   - day of month
+      #   :hour
+      #   :minute
+      #   :second
+      # all values default to '*' (except second, which defaults to 0)
+    # track_runs false    # defaults to true for run_when() jobs
+    perform do
+      AnotherReportJob.perform_later
+    end
+  end
+
+  ## Intervals
+  task 'send welcome emails' do
+    run_every 30.minutes
+    # track_runs false    # when run_every is >= 15.minutes, defaults to true; else to false
+    perform do
+      User.where(welcome_email_at: nil).find_each(batch_size: 100) do |user|
+        WelcomeMailer.welcome_email.with(user: user).deliver_later
+      end
+    end
+  end
+
+  task 'heartbeat' do
+    run_every 300  # seconds may be used instead
+    perform 'HeartbeatJob.perform_later'  # a string to eval may be used too
+  end
+
+  # Use tiny intervals for lightweight scanning for ready-to-work records
+  task 'disable expired accounts' do
+    run_every 15.seconds
+    logger_tag 'expired-scan'  # tag log lines with an alternate value; nil disables tagging
+    perform do
+      Subscription.expired.pluck(:id).each do |id|
+        DisableAccountJob.perform_later id
+      end
+    end
+  end
+
+end
+```
+
+
+#### Fixed times: `run_at` and `run_when`
+
+Fixed time tasks are comparable to cron-style scheduling. Times will be interpreted according to the Rails default TZ.
+
+By default `run_at` and `run_when` will automatically catch up missed tasks. Scheddy does this by maintaining a record of the last run. If one or more runs was missed, it will run _once_ immediately. Multiple misses will still only be run once. Set `track_runs false` to disable catch-ups.
+
+
+#### Intervals: `run_every`
+
+Intervals are similar to cron style `*/5` syntax, but one key difference is the cycle is calculated based on Scheddy's startup time.
+
+To avoid all tasks running at once, interval tasks are given an initial random delay of no more than the interval length itself. For example, a task running at 15 second intervals will be randomly delayed 0-14 seconds for first run. It will then continue running every 15 seconds.
+
+By default, tiny interval tasks (those under 15 minutes) do not track last run or perform catch-ups, but longer interval tasks (>= 15 minutes) do. This is because tiny intervals will re-run soon anyway and it reduces database activity. Set `track_runs true|false` to override.
+
+
+
+### Additional notes
+
+#### Units of work
+
+Notice that all these examples delegate the actual work to an external job. This is the recommended approach, but is not strictly required.
+
+In general, bite-sized bits of work are fine in Scheddy, but bigger chunks of work usually belong in a background queue. In general, when timeliness is key (running right on time) or scheduling a background job is more costly than doing the work directly, then performing work inside the Scheddy task may be appropriate.
+
+Database transactions are valid. These can increase use of database connections from the pool. Ensure Rails is configured appropriately.
+
+
+#### Threading and execution
+
+Each task runs in its own thread which helps ensure all tasks perform on time. However, Scheddy is not intended as a job executor and doesn't have a robust mechanism for retrying failed jobs--that belongs to your background job queue.
+
+A given task will only ever be executed once at a time. Mostly relevant when using tiny intervals, if a prior execution is still going when the next execution is scheduled, Scheddy will skip the next execution and log an error message to that effect.
+
+
+#### Task context
+
+Tasks may receive an optional context to check if they need to stop for pending shutdown or to know the deadline for completing work before the next cycle would begin.
+
+Deadlines (`finish_before`) are mostly useful if there is occasionally a large block of work combined with tiny intervals. The deadline is calculated with a near 2 second buffer. Only if that's inadequate do you need to adjust further. As already mentioned, Scheddy is smart enough to skip the next cycle if the prior cycle is still running, so handling deadlines is entirely optional.
+
+```ruby
+task 'iterating task' do
+  run_every 15.seconds
+  perform do |context|
+    Model.where(...).find_each do |model|
+      SomeJob.perform_later model.id if model.run_job?
+      break if context.stop? # the scheduler has requested to shutdown
+      break if context.finish_before < Time.now # the next cycle is imminent
+    end
+  end
+end
+```
+
+
+#### Rails reloader
+
+Each task's block is run inside the Rails reloader. In development mode, any classes referenced inside the block will be reloaded automatically to your latest code, just like the Rails dev-server itself.
+
+It's possible to also make the task work reloadable by using a proxy class for the task itself. If your tasks are a bit bigger, organizing them into `app/tasks/` might be worthwhile anyway.
+
+```ruby
+# config/initializers/scheddy.rb
+Scheddy.config do
+  task 'weekly report' do
+    run_at 'friday 9am'
+    perform 'WeeklyReportTask.perform'
+  end
+end
+
+# app/tasks/weekly_report_task.rb
+class WeeklyReportTask
+  def self.perform
+    ReportJob.perform_later
+  end
+end
+```
+
+
+
+## Running Scheddy
+
+Depending on your ruby setup, one of the following should do:
+```bash
+  scheddy start
+  # OR
+  bundle exec scheddy start
+```
+
+You can also check your tasks configuration with:
+```bash
+  scheddy tasks
+  # OR
+  bundle exec scheddy tasks
+```
+
+
+### In production
+
+Scheddy runs as its own process. It is intended to be run only once. Because Scheddy has the ability to catch up missed tasks, redundancy should be achieved through automatic restarts via `systemd`, `dockerd`, Kubernetes, or whatever supervisory system you use.
+
+During deployment, shutdown the old instance before starting the new one. In Kubernetes this might look like:
+```yaml
+kind: Deployment
+spec:
+  replicas: 1
+  strategy:
+    rollingUpdate:
+      maxSurge: 0
+      maxUnavailable: 1
+  template:
+    spec:
+      terminationGracePeriodSeconds: 60
+```
+
+
+### In development (and `Procfile` in production)
+
+Assuming you're using `Procfile.dev` or `Procfile` for development, add:
+```bash
+scheddy: bundle exec scheddy start
+```
+
+
+### Signals and shutdown
+
+Scheddy will shutdown upon receiving an `INT`, `QUIT`, or `TERM` signal.
+
+There is a default 45 second wait for tasks to complete, which should be more than enough for the tiny types of tasks at hand. Tasks may also check for when to stop work part way through. This may be useful in iterators processing large numbers of items. See Task Context above.
+
+
+### Error handling
+
+Scheddy's default error handler uses the Rails Errors API introduced in Rails 7. If your exception tracker of choice doesn't implement this API, or if using Rails 6.x, set your own error handler.
+
+Note that the default handler is responsible for exception logging, so you must perform your own logging if wanted. If the handler is set to `nil`, exceptions will be silenced.
+
+```ruby
+Scheddy.config do
+  error_handler do |exception, task|
+    # displaying task.name is the most likely use of task
+    name = "task '#{task.name}'" if task  # task might be nil
+    logger.error "Exception in Scheddy #{name}: #{e.inspect}"
+    # report the exception here
+  end
+
+  error_handler ->(exception){
+    # passing a proc instead of a block is also allowed
+    # the task arg can be left out if it won't be used
+  }
+
+  error_handler nil  # silence & don't report
+end
+```
+
+
+
+## Compatibility
+Used in production on Rails 7.0+. Gemspec is set to Rails 6.0+, but such is not well tested.
+
+
+## Contributing
+Pull requests are welcomed.
+
+
+## License
+MIT licensed.

data/Rakefile

@@ -0,0 +1,16 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"
+
+require "rake/testtask"
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+task default: :test

data/app/models/scheddy/application_record.rb

@@ -0,0 +1,5 @@
+module Scheddy
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/scheddy/task_history.rb

@@ -0,0 +1,4 @@
+module Scheddy
+  class TaskHistory < ApplicationRecord
+  end
+end

data/db/migrate/20230607201527_create_scheddy_task_histories.rb

@@ -0,0 +1,10 @@
+class CreateScheddyTaskHistories < ActiveRecord::Migration[6.0]
+  def change
+    # feel free to modify to  id: :uuid  or another :id format if you prefer
+    create_table :scheddy_task_histories do |t|
+      t.string     :name,        null: false, index: {unique: true}
+      t.datetime   :last_run_at
+      t.timestamps
+    end
+  end
+end

data/exe/scheddy

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+require 'scheddy/cli'
+Scheddy::CLI.start(ARGV)

data/lib/scheddy/cli.rb

@@ -0,0 +1,49 @@
+require 'thor'
+
+module Scheddy
+  class CLI < Thor
+
+    class << self
+      def exit_on_failure?
+        true
+      end
+    end
+
+
+    desc :start, "Run Scheddy's scheduler"
+    def start
+      load_app!
+      Scheddy.run
+    end
+
+
+    desc :tasks, 'Show configured tasks'
+    def tasks
+      load_app!
+
+      Scheddy.tasks.map do |t|
+        OpenStruct.new t.to_h
+      end.each do |t|
+        puts <<~TASK.gsub(/$\s+$/m,'')
+          #{t.type.to_s.humanize} task: #{t.name}
+            #{"Interval:       #{t.interval&.inspect}" if t.interval}
+            #{"Initial delay:  #{t.initial_delay&.inspect}" if t.initial_delay}
+            #{"Cron rule:      #{t.cron}" if t.cron}
+            Track runs?     #{t.track_runs}
+            Next cycle:     #{t.next_cycle} (if run now)
+            Tag:            #{t.tag.present? ? "[#{t.tag}]" : 'nil'}
+        TASK
+        puts ''
+      end
+    end
+
+
+    no_commands do
+
+      def load_app!
+        require File.expand_path('config/environment.rb')
+      end
+
+    end
+  end
+end

data/lib/scheddy/config.rb

@@ -0,0 +1,142 @@
+module Scheddy
+  # default task list for when running standalone
+  mattr_accessor :tasks, default: []
+
+  # called from within task's execution thread; must be multi-thread safe
+  # task is allowed to be nil
+  mattr_accessor :error_handler, default: lambda {|e, task|
+    logger.error "Exception in Scheddy task '#{task&.name}': #{e.inspect}\n  #{e.backtrace.join("\n  ")}"
+    Rails.error.report(e, handled: true, severity: :error)
+  }
+
+  def self.config(&block)
+    Config.new(tasks, &block)
+  end
+
+
+  class Config
+    attr_reader :tasks
+
+    delegate :logger, to: :Scheddy
+
+    def initialize(tasks, &block)
+      @tasks = tasks
+      instance_eval(&block)
+    end
+
+    def error_handler(block1=nil, &block2)
+      Scheddy.error_handler = block1 || block2
+    end
+
+    def task(name, &block)
+      raise ArgumentError, "Duplicate task name '#{name}'" if tasks.any?{|t| t.name == name}
+      tasks.push TaskDefinition.new(name, &block).to_task
+    end
+
+    # shortcut syntax
+    def run_at(cron, name:, tag: :auto, track: :auto, &task)
+      task(name) do
+        run_at     cron
+        logger_tag tag if tag!=:auto
+        track_runs track if track!=:auto
+        perform(&task)
+      end
+    end
+
+    # shortcut syntax
+    def run_every(interval, name:, delay: nil, tag: :auto, track: :auto, &task)
+      task(name) do
+        run_every     interval
+        initial_delay delay if delay
+        logger_tag    tag if tag!=:auto
+        track_runs    track if track!=:auto
+        perform(&task)
+      end
+    end
+
+  end
+
+
+  class TaskDefinition
+    delegate :logger, to: :Scheddy
+
+    # block  - task to perform
+    # string - task to perform as evalable code, eg: 'SomeJob.perform_later'
+    def perform(string=nil, &block)
+      raise ArgumentError, 'Must provide string or block to perform' unless string.is_a?(String) ^ block
+      block ||= lambda { eval(string) }
+      task[:task] = block
+    end
+
+    # cron - String("min hour dom mon dow"), eg "0 4 * * *"
+    def run_at(cron)
+      task[:cron] =
+        Fugit.parse_cronish(cron) ||
+        Fugit.parse_cronish("every #{cron}") ||
+        raise(ArgumentError, "Unable to parse '#{cron}'")
+    end
+
+    # duration - Duration or Integer
+    def run_every(duration)
+      task[:interval] = duration.to_i
+    end
+
+    # day    - day of week as Symbol (:monday, :mon) or Integer (both 0 and 7 are sunday)
+    # month  - month as Symbol (:january, :jan) or Integer 1-12
+    # date   - day of month, 1-31
+    # hour   - 0-23
+    # minute - 0-59
+    # second - 0-59
+    def run_when(day: '*', month: '*', date: '*', hour: '*', minute: '*', second: '0')
+      day   = day.to_s[0,3]   if day.to_s =~ /[a-z]/
+      month = month.to_s[0,3] if month.to_s =~ /[a-z]/
+      run_at [second, minute, hour, date, month, day].map{normalize_val _1}.join(' ')
+    end
+
+    # duration - Duration or Integer (nil = random delay)
+    def initial_delay(duration)
+      task[:initial_delay] = duration&.to_i
+    end
+
+    # tag - String or false/nil; defaults to :name
+    def logger_tag(tag)
+      task[:tag] = tag
+    end
+
+    def track_runs(bool)
+      task[:track_runs] = bool
+    end
+
+
+    # private api
+    def to_task
+      Task.new(**as_args)
+    end
+
+    private
+
+    attr_accessor :task
+
+    def initialize(name, &block)
+      self.task = {name: name}
+      instance_eval(&block)
+    end
+
+    def as_args
+      raise ArgumentError, 'Must call run_at, run_every, or run_when' unless task[:cron] || task[:interval]
+      task
+    end
+
+    def normalize_val(val)
+      case val
+      when Array
+        val.join(',')
+      when Range
+        "#{val.min}-#{val.max}"
+      else
+        val
+      end
+    end
+
+  end
+end

data/lib/scheddy/context.rb

@@ -0,0 +1,13 @@
+module Scheddy
+  class Context
+
+    def initialize(scheduler, finish_before)
+      @scheduler = scheduler
+      @finish_before = finish_before
+    end
+
+    delegate :stop?, to: :@scheduler
+    attr_reader :finish_before
+
+  end
+end

data/lib/scheddy/engine.rb

@@ -0,0 +1,5 @@
+module Scheddy
+  class Engine < ::Rails::Engine
+    isolate_namespace Scheddy
+  end
+end

data/lib/scheddy/logger.rb

@@ -0,0 +1,11 @@
+module Scheddy
+  class << self
+
+    attr_writer :logger
+
+    def logger
+      @logger ||= Rails.logger
+    end
+
+  end
+end

data/lib/scheddy/scheduler.rb

@@ -0,0 +1,85 @@
+module Scheddy
+
+  def self.run
+    Scheduler.new(tasks).run
+  end
+
+  class Scheduler
+
+    def run
+      puts "[Scheddy] Starting scheduler with #{tasks.size} #{'task'.pluralize tasks.size}"
+      trap_signals!
+      cleanup_task_history
+
+      until stop?
+        next_cycle = run_once
+        wait_until next_cycle unless stop?
+      end
+
+      running = tasks.select(&:running?).count
+      if running > 0
+        puts "[Scheddy] Waiting for #{running} tasks to complete"
+        wait_until(45.seconds.from_now) do
+          tasks.none?(&:running?)
+        end
+        tasks.select(&:running?).each do |task|
+          $stderr.puts "[Scheddy] Killing task #{task.name}"
+          task.kill
+        end
+      end
+
+      puts '[Scheddy] Done'
+    end
+
+    # return : Time of next cycle
+    def run_once
+      tasks.flat_map do |task|
+        task.perform(self) unless stop?
+      end.min
+    end
+
+    def stop? ; @stop ; end
+
+
+    private
+
+    attr_reader :tasks
+    attr_writer :stop
+
+    def initialize(tasks)
+      @tasks = tasks
+    end
+
+    def cleanup_task_history
+      known_tasks = tasks.select(&:track_runs).map(&:name)
+      return if known_tasks.empty?  # table doesn't have to exist if track_runs always disabled
+      Scheddy::TaskHistory.find_each do |r|
+        r.destroy if known_tasks.exclude? r.name
+      end
+    rescue ActiveRecord::StatementInvalid => e
+      return if e.message =~ /relation "scheddy_task_histories" does not exist/
+      raise
+    end
+
+    def stop!(sig=nil)
+      puts '[Scheddy] Stopping'
+      self.stop = true
+    end
+
+    def trap_signals!
+      trap 'INT', &method(:stop!)
+      trap 'QUIT', &method(:stop!)
+      trap 'TERM', &method(:stop!)
+    end
+
+    # &block - optional block - return truthy to end prematurely
+    def wait_until(time)
+      while (now = Time.current) < time
+        return if stop?
+        return if block_given? && yield
+        sleep [time-now, 1].min
+      end
+    end
+
+  end
+end

data/lib/scheddy/task.rb

@@ -0,0 +1,173 @@
+module Scheddy
+  class Task
+    attr_reader :cron, :delay, :interval, :name, :task, :tag, :track_runs, :type
+
+    delegate :logger, to: :Scheddy
+
+
+    def perform(scheduler, now: false)
+      return next_cycle if Time.current < next_cycle && !now
+      record_this_run
+      if running?
+        logger.error "Scheddy task '#{name}' already running; skipping this cycle"
+        return next_cycle!
+      end
+      context = Context.new(scheduler, finish_before)
+      self.thread =
+        Thread.new do
+          logger.tagged tag do
+            Rails.application.reloader.wrap do
+              task.call(*[context].take(task.arity.abs))
+            rescue Exception => e
+              if h = Scheddy.error_handler
+                h.call(*[e, self].take(h.arity.abs))
+              end
+            end
+          end
+        ensure
+          self.thread = nil
+        end
+      next_cycle!
+    end
+
+    def kill
+      thread&.kill
+    end
+
+    def running?
+      !!thread
+    end
+
+    def next_cycle
+      initial_cycle! if @next_cycle == :initial
+      @next_cycle
+    end
+
+
+    def to_h
+      attrs = {
+        name:       name,
+        next_cycle: next_cycle.utc,
+        type:       type,
+        tag:        tag,
+        task:       task,
+        track_runs: track_runs,
+      }
+      case type
+      when :interval
+        attrs[:initial_delay] = ActiveSupport::Duration.build(delay) unless track_runs
+        attrs[:interval] = ActiveSupport::Duration.build(interval)
+      when :cron
+        attrs[:cron] = cron.original
+      end
+      attrs.to_a.sort_by!{_1.to_s}.to_h
+    end
+
+    def inspect
+      attrs = to_h.map{|k,v| "#{k}: #{v.inspect}"}
+      %Q{#<#{self.class} #{attrs.join(', ')}>}
+    end
+
+
+    private
+
+    attr_accessor :thread
+    attr_writer :next_cycle, :track_runs
+
+    # :cron            - cron definition
+    # :interval        - interval period
+    #   :initial_delay - delay of first run; nil = randomize; ignored if track_runs
+    # :name            - task name
+    # :tag             - logger tag; defaults to :name; false = no tag
+    # :task            - proc/lambda to execute on each cycle
+    # :track_runs      - whether to track last runs for catchup; defaults true except intervals < 15min
+    def initialize(**args)
+      @task = args[:task]
+      @name = args[:name]
+      @tag  = args.key?(:tag) ? args[:tag] : self.name
+      if args[:interval]
+        @type       = :interval
+        @interval   = args[:interval]
+        @delay      = args[:initial_delay] || rand(self.interval)
+        @track_runs = args.key?(:track_runs) ? args[:track_runs] : self.interval >= 15.minutes
+      else
+        @type       = :cron
+        @cron       = args[:cron]
+        @track_runs = args.key?(:track_runs) ? args[:track_runs] : true
+      end
+
+      self.next_cycle = :initial
+    end
+
+
+    def initial_cycle!
+      self.next_cycle =
+        case type
+        when :interval
+          if last_run
+            last_run + interval
+          else
+            Time.current + delay
+          end
+        when :cron
+          prev_t = cron.previous_time.to_utc_time
+          if last_run && last_run < prev_t
+            prev_t
+          else
+            cron.next_time.to_utc_time
+          end
+        end
+    end
+
+    def next_cycle!
+      self.next_cycle =
+        case type
+        when :interval
+          Time.current + interval
+        when :cron
+          cron.next_time.to_utc_time
+        end
+    end
+
+    def finish_before
+      case type
+      when :interval
+        Time.current + interval - 2.seconds
+      when :cron
+        cron.next_time.to_utc_time - 2.seconds
+      end
+    end
+
+
+    def last_run
+      track_runs && task_history.last_run_at
+    rescue ActiveRecord::StatementInvalid => e
+      if e.message =~ /relation "scheddy_task_histories" does not exist/
+        logger.error <<~MSG
+          [Scheddy] ERROR in task '#{name}': Missing DB table for Scheddy::TaskHistory.
+            Either set  track_runs(false)  or run:
+              bin/rails scheddy:install:migrations
+              bin/rails db:migrate
+            For now, disabling track_runs and continuing.
+        MSG
+        self.track_runs = false
+      else
+        raise
+      end
+    end
+
+    def record_this_run
+      return unless track_runs
+      Scheddy::TaskHistory.logger.silence(Logger::INFO) do
+        task_history.update last_run_at: Time.current
+      end
+    rescue ActiveRecord::ActiveRecordError => e
+      logger.error "Error updating task history for Scheddy task '#{name}': #{e.inspect}"
+    end
+
+    def task_history
+      @task_history ||= Scheddy::TaskHistory.find_or_create_by! name: name
+    end
+
+  end
+end

data/lib/scheddy/version.rb

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

data/lib/scheddy.rb

@@ -0,0 +1,16 @@
+require 'fugit'
+
+module Scheddy
+end
+
+%w(
+  config
+  context
+  logger
+  scheduler
+  task
+  version
+  engine
+).each do |f|
+  require_relative "scheddy/#{f}"
+end

data/lib/tasks/scheddy_tasks.rake

@@ -0,0 +1,16 @@
+namespace :scheddy do
+
+  desc 'Run Scheddy'
+  task run: :environment do
+    Scheddy.run
+  end
+
+  task :migrate do
+    `bin/rails db:migrate SCOPE=scheddy`
+  end
+
+  task :rollback do
+    `bin/rails db:migrate SCOPE=scheddy VERSION=0`
+  end
+
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: scheddy
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- thomas morgan
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-06-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fugit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Scheddy is a batteries-included task scheduler for Rails. It is intended
+  as a replacement for cron and cron-like functionality (including job queue specific
+  schedulers). It is job-queue agnostic and can catch up missed tasks.
+email:
+- tm@iprog.com
+executables:
+- scheddy
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/models/scheddy/application_record.rb
+- app/models/scheddy/task_history.rb
+- db/migrate/20230607201527_create_scheddy_task_histories.rb
+- exe/scheddy
+- lib/scheddy.rb
+- lib/scheddy/cli.rb
+- lib/scheddy/config.rb
+- lib/scheddy/context.rb
+- lib/scheddy/engine.rb
+- lib/scheddy/logger.rb
+- lib/scheddy/scheduler.rb
+- lib/scheddy/task.rb
+- lib/scheddy/version.rb
+- lib/tasks/scheddy_tasks.rake
+homepage: https://github.com/zarqman/scheddy
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/zarqman/scheddy
+  source_code_uri: https://github.com/zarqman/scheddy
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Job-queue agnostic, cron-like task scheduler for Rails apps, with missed
+  task catch-ups and other features.
+test_files: []