job_board 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0a2428d3806231d3051a64d1ed7f693e51341cbbc12a4a2fe8240f1f1c56d73
-  data.tar.gz: 59cb3f9a17d3ae3cc0b9ac69adb11ec5c1c27838391d559c2c6f9a23e2a65306
+  metadata.gz: bea67d509d907e2592ab52afa1b5416ddec7493cbdab455d67b9f9ac4aa3e66e
+  data.tar.gz: 38f1c58ef928b9d40253aa5f9e37f1b5bd4073899cd3a641a1d467455f8c541c
 SHA512:
-  metadata.gz: fc936decbae3e1e9457ac3a6d6643f67907e4b0314ee3368e22516040779381f549af59c7b60fffa28f026b1edb88feddfa62cdd32772b9e4571eb413ad1e46f
-  data.tar.gz: c7f69762ffd1695bb6fc3dd64d59a8248f3d445255cc8f2276d9c7ddfb3a0b2008898c8557988fe4c76455389fbe213e752b36bdf1d4ccbdf56393e5c74ef4b0
+  metadata.gz: 688e4fd719017cad90493adcfcbe9e8629c06d939a7f58d28cc9a32b119ec4a01ba90942604dbfb9fb218f6bb931dfc44ee760f0b0d6448f664a9d7eb27f2663
+  data.tar.gz: 0436d97db91c3ac1071145936ea3c41f4396fca772407324c8349369af7343da0cb4783552f9bca4d8b2786c7ce1e22a1cc9256364c05836c8a850a9e1debb0f

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.3.0
+
+- Recurring tasks page: **Run now** button to trigger a task outside its schedule
+  (recorded as a run, so "Last run" reflects it), and tasks are now sorted by next
+  run time instead of by key.
+- Hovering a cron schedule shows a plain-English description of when it runs
+  (e.g. `30 9 * * 1-5` → "At 09:30 on Monday through Friday").
+
 ## 0.2.0
 
 - Queues page: new **Last enqueued** column showing when each queue last received a job.

data/README.md

@@ -15,7 +15,9 @@ queue latency at a glance, jobs by status, failed-job management, worker health,
 - **Workers** — the supervisor → worker/dispatcher/scheduler tree with heartbeat freshness,
   stale-process badges, per-worker in-progress jobs, and a warning when claimed jobs have been
   orphaned by a dead process.
-- **Recurring tasks** — each task's cron schedule, last run, and next run.
+- **Recurring tasks** — each task's cron schedule (hover for a plain-English description),
+  last run, and next run, sorted soonest-first, with a **Run now** button to trigger any
+  task outside its schedule.
 - **Zero dependencies** — the engine serves its own CSS and ~40 lines of vanilla JS. No
   importmap, sprockets, propshaft, or Node requirement. Pages auto-refresh every few seconds.
 

data/app/controllers/job_board/recurring_tasks/runs_controller.rb

@@ -0,0 +1,18 @@
+module JobBoard
+  module RecurringTasks
+    class RunsController < ApplicationController
+      def create
+        task = SolidQueue::RecurringTask.find_by(key: params[:key])
+
+        if task.nil?
+          redirect_to recurring_tasks_path, alert: "Recurring task \"#{params[:key]}\" no longer exists."
+        elsif task.enqueue(at: Time.current)
+          redirect_to recurring_tasks_path, notice: "Enqueued \"#{task.key}\"."
+        else
+          redirect_to recurring_tasks_path,
+            alert: "\"#{task.key}\" was not enqueued — it already ran at this exact time or the enqueue failed."
+        end
+      end
+    end
+  end
+end

data/app/controllers/job_board/recurring_tasks_controller.rb

@@ -1,7 +1,8 @@
 module JobBoard
   class RecurringTasksController < ApplicationController
     def index
-      @tasks = SolidQueue::RecurringTask.order(:key)
+      # next_time is derived from the cron schedule, not stored, so sort in Ruby.
+      @tasks = SolidQueue::RecurringTask.all.sort_by { |task| [task.next_time, task.key] }
     end
   end
 end

data/app/helpers/job_board/application_helper.rb

@@ -30,6 +30,13 @@ module JobBoard
       LatencySla.threshold_for(queue_name)
     end
 
+    # <code> tag for a cron schedule, with an English description of the
+    # schedule as a hover tooltip when we can produce one.
+    def cron_schedule(schedule)
+      description = CronDescription.describe(schedule)
+      tag.code(schedule, title: description, class: ("cron" if description))
+    end
+
     def format_json(value)
       value = JSON.parse(value) if value.is_a?(String)
       JSON.pretty_generate(value)

data/app/models/job_board/cron_description.rb

@@ -0,0 +1,154 @@
+require "fugit"
+
+module JobBoard
+  # Turns a cron expression into an English frequency description,
+  # e.g. "30 9 * * 1-5" => "At 09:30 on Monday through Friday".
+  # Returns nil for anything it can't describe faithfully.
+  class CronDescription
+    DAYS = %w[Sunday Monday Tuesday Wednesday Thursday Friday Saturday].freeze
+    MONTHS = %w[January February March April May June
+                July August September October November December].freeze
+
+    def self.describe(schedule)
+      cron = Fugit.parse(schedule.to_s)
+      new(cron).to_s if cron.instance_of?(Fugit::Cron)
+    rescue StandardError
+      nil
+    end
+
+    def initialize(cron)
+      @cron = cron
+    end
+
+    def to_s
+      time = time_clause
+      return nil if time.nil?
+
+      days = day_clause
+      description =
+        if days
+          "#{time} #{days}"
+        elsif time.start_with?("At ")
+          "Every day #{time.sub(/\AAt /, "at ")}"
+        else
+          time
+        end
+      cron.zone ? "#{description} (#{cron.zone})" : description
+    end
+
+    private
+
+    attr_reader :cron
+
+    def time_clause
+      if (step = seconds_step)
+        # Sub-minute schedules only describe cleanly when nothing else is constrained.
+        return nil unless cron.minutes.nil? && cron.hours.nil?
+        "Every #{step} seconds"
+      elsif cron.seconds && cron.seconds != [0]
+        nil
+      elsif cron.minutes.nil? && cron.hours.nil?
+        "Every minute"
+      elsif (step = minutes_step) && cron.hours.nil?
+        "Every #{step} minutes"
+      elsif cron.minutes == [0] && cron.hours.nil?
+        "Every hour"
+      elsif cron.hours.nil?
+        "Every hour at #{numbers("minute", cron.minutes)}"
+      elsif (step = hours_step)
+        cron.minutes == [0] ? "Every #{step} hours" : "Every #{step} hours at #{numbers("minute", cron.minutes)}"
+      else
+        times = cron.hours.product(cron.minutes || [0]).sort
+        if times.size <= 4
+          "At #{join_and(times.map { |h, m| format("%02d:%02d", h, m) })}"
+        else
+          "At #{numbers("minute", cron.minutes)} past #{numbers("hour", cron.hours)}"
+        end
+      end
+    end
+
+    # nil when there is no day-of-week/month restriction (i.e. runs every day).
+    def day_clause
+      day_parts = [weekday_clause, monthday_clause].compact
+      # Cron treats day-of-month and day-of-week as OR when both are restricted.
+      clause = day_parts.join(" or ").presence
+      [clause, month_clause].compact.join(" ").presence
+    end
+
+    def weekday_clause
+      return nil if cron.weekdays.nil?
+
+      plain = cron.weekdays.select { |_, nth| nth.nil? }.map { |day,| day % 7 }.sort.uniq
+      nth = cron.weekdays.reject { |_, nth| nth.nil? }.map do |day, n|
+        "the #{n == -1 ? "last" : n.ordinalize} #{DAYS[day % 7]} of the month"
+      end
+
+      phrases = []
+      if plain.any?
+        phrases << if plain.size > 2 && consecutive?(plain)
+          "#{DAYS[plain.first]} through #{DAYS[plain.last]}"
+        else
+          join_and(plain.map { |day| DAYS[day] })
+        end
+      end
+      "on #{join_and(phrases + nth)}"
+    end
+
+    def monthday_clause
+      return nil if cron.monthdays.nil?
+
+      # "0 0 1 1 *" reads better as "on January 1" than "on day 1 of the month in January".
+      if cron.monthdays.size == 1 && cron.monthdays.first.positive? &&
+          cron.months&.size == 1 && cron.weekdays.nil?
+        @month_consumed = true
+        return "on #{MONTHS[cron.months.first - 1]} #{cron.monthdays.first}"
+      end
+
+      positive, negative = cron.monthdays.partition(&:positive?)
+      phrases = []
+      phrases << numbers("day", positive) if positive.any?
+      phrases += negative.sort.reverse.map do |day|
+        day == -1 ? "the last day" : "the #{(-day).ordinalize}-to-last day"
+      end
+      "on #{join_and(phrases)} of the month"
+    end
+
+    def month_clause
+      return nil if cron.months.nil? || @month_consumed
+
+      names = cron.months.sort.map { |m| MONTHS[m - 1] }
+      if names.size > 2 && consecutive?(cron.months.sort)
+        "in #{names.first} through #{names.last}"
+      else
+        "in #{join_and(names)}"
+      end
+    end
+
+    def seconds_step = step_of(cron.seconds, 60)
+    def minutes_step = step_of(cron.minutes, 60)
+    def hours_step   = step_of(cron.hours, 24)
+
+    # [0, 15, 30, 45] within 60 => 15; anything not starting at 0 or unevenly spaced => nil.
+    def step_of(values, span)
+      return nil if values.nil? || values.size < 2 || values.first != 0
+
+      gap = values[1] - values[0]
+      values == (0...span).step(gap).to_a ? gap : nil
+    end
+
+    def consecutive?(values)
+      values.each_cons(2).all? { |a, b| b == a + 1 }
+    end
+
+    def numbers(noun, values)
+      "#{noun.pluralize(values.size)} #{join_and(values.sort)}"
+    end
+
+    def join_and(items)
+      items = items.map(&:to_s)
+      return items.join(" and ") if items.size <= 2
+
+      "#{items[0..-2].join(", ")}, and #{items.last}"
+    end
+  end
+end

data/app/views/job_board/recurring_tasks/index.html.erb

@@ -15,6 +15,7 @@
           <th>Queue</th>
           <th>Last run</th>
           <th>Next run</th>
+          <th class="actions"></th>
         </tr>
       </thead>
       <tbody>
@@ -24,11 +25,15 @@
               <%= task.key %>
               <% unless task.static %><span class="badge badge--kind">dynamic</span><% end %>
             </td>
-            <td><code><%= task.schedule %></code></td>
+            <td><%= cron_schedule(task.schedule) %></td>
             <td><%= task.class_name.presence || task.command %></td>
             <td><%= task.queue_name.presence || "default" %></td>
             <td><%= time_ago(task.last_enqueued_time) %></td>
             <td><%= time_ago(task.next_time) %></td>
+            <td class="actions">
+              <%= button_to "Run now", recurring_task_run_path(task.key), class: "btn",
+                    form: { data: { confirm: "Enqueue \"#{task.key}\" now, outside its schedule?" } } %>
+            </td>
           </tr>
         <% end %>
       </tbody>

data/config/routes.rb

@@ -20,6 +20,9 @@ JobBoard::Engine.routes.draw do
 
   resources :processes, only: :index
   resources :recurring_tasks, only: :index
+  scope "recurring_tasks/:key", constraints: { key: /[^\/]+/ }, format: false do
+    post "run", to: "recurring_tasks/runs#create", as: :recurring_task_run
+  end
 
   get "assets/:name", to: "assets#show", as: :static_asset, constraints: { name: /[a-z_]+\.(css|js)/ }
 end

data/lib/job_board/assets/application.css

@@ -70,6 +70,13 @@ code {
 
 .muted { color: var(--text-muted); }
 
+/* Cron schedules with a hover description */
+code.cron {
+  cursor: help;
+  text-decoration: underline dotted var(--text-muted);
+  text-underline-offset: 2px;
+}
+
 /* Nav */
 .nav {
   display: flex;

data/lib/job_board/version.rb

@@ -1,3 +1,3 @@
 module JobBoard
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: job_board
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Mike
@@ -54,8 +54,10 @@ files:
 - app/controllers/job_board/processes_controller.rb
 - app/controllers/job_board/queues/pauses_controller.rb
 - app/controllers/job_board/queues_controller.rb
+- app/controllers/job_board/recurring_tasks/runs_controller.rb
 - app/controllers/job_board/recurring_tasks_controller.rb
 - app/helpers/job_board/application_helper.rb
+- app/models/job_board/cron_description.rb
 - app/models/job_board/job_presenter.rb
 - app/models/job_board/job_row.rb
 - app/models/job_board/jobs_query.rb