wallflower 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0414c4dd964967e59689c5e2e2b7a4fbbf7a20377c0ec440672f1fac3f9c11c5
-  data.tar.gz: c3a640201ed58af2b59f003203b95ade7fcee6394e67b00cf944503b1498e49c
+  metadata.gz: bee05b46afa4694efc995d6ab7befa843e299fe7badc2cbb3525a81c243bc585
+  data.tar.gz: 27e1317e521c02f6fe23577cea0ce20e32351e187b79882994d75c774ce56e3e
 SHA512:
-  metadata.gz: 481d9d8eee850f1b102268ff479d656424491030c32790eb13483e82d4809045e2f6f4296ed0783d988363a00fdb4f011ab6c4e3c9108766fc047d25d592b4e0
-  data.tar.gz: bc71c88ee2441cc6f002b8c6f044135c3b32fe648662f35be6660259bf4d8d303220fa9686f73d8ed7b95792a1809e8dae80a34022e31a974a5f29940164714e
+  metadata.gz: 2d356ca88a0600f1310e9997e05d79b74665cece49b6a09f40f228e0b670a46c8f11e216e605dcd7650c7a596178333237456fb2c64dde46b2feaaca8fdbc100
+  data.tar.gz: 917d6dd960077ff4ad47d478c429534e1d974a110fac430149108b0ac7b26a2332ed97b59c862a372f572b0fa7162e621cbd8bff55c5b6e3584e286228c2aa65

data/README.md

@@ -42,12 +42,12 @@ Wallflower.configure do |config|
 end
 ```
 
-## Kinds and runners
+## Task types and runners
 
-A kind is a type of task the app offers, such as an export. Register each one in an initializer with its key, its title and the name of its runner class:
+A task type is a type of task the app offers, such as an export. Register each one in an initializer with its key, its title and the name of its runner class:
 
 ```ruby
-Wallflower.register_kind :export_transactions, title: "Export transactions", runner: "ExportTransactionsRunner"
+Wallflower.register_task_type :export_transactions, title: "Export transactions", runner: "ExportTransactionsRunner"
 ```
 
 An app whose registered runner class does not exist fails to boot, with a message naming the class.
@@ -91,7 +91,7 @@ A finished task's page then offers a Download button. The file is sent through W
 ## Starting a task
 
 ```ruby
-task = Wallflower.start(kind: :export_transactions, person: current_user, account: current_account, params: { "month" => "2026-10" })
+task = Wallflower.start(task_type: :export_transactions, person: current_user, account: current_account, params: { "month" => "2026-10" })
 ```
 
 The task is returned queued and its job is enqueued. When the job runs, the task is marked running, its runner is called, and when the runner returns the task is marked finished with the time it finished.
@@ -110,7 +110,15 @@ With no `on_finish` set, tasks still run to the end.
 
 ## When a task fails
 
-A runner that raises marks its task failed. The task keeps the error's message, its page shows it beside how far the task got, the error is reported through `Rails.error`, and `on_finish` runs once with the failed task.
+A task type runs one try by default. A task type registered with `tries:` runs again after a raised error until it has used them all, waiting `retry_wait:` seconds between tries, 60 by default:
+
+```ruby
+Wallflower.register_task_type :send_price, title: "Send a price", runner: "SendPriceRunner", tries: 3, retry_wait: 60
+```
+
+Between tries the task stays running and `on_finish` does not run. Each try starts its progress and refusals over, so a runner with more than one try must be safe to run again.
+
+A runner that raises on its last try marks its task failed. The task keeps the error's message, its page shows it beside how far the task got, the error is reported through `Rails.error`, and `on_finish` runs once with the failed task.
 
 A task still running with no update for longer than `stall_after`, one hour by default, is marked failed by `Wallflower::SweepJob`, with a reason saying it stalled. Schedule the sweep the way the app schedules any recurring job, for example in Solid Queue's `config/recurring.yml`:
 
@@ -132,11 +140,11 @@ With `keep_for` set, the same sweep deletes each finished or failed task that en
 
 ## The task list
 
-The engine's root lists the tasks the signed-in person started in the current account, newest first. Each row shows the kind's title, the status as a coloured badge, the progress, the time left while it runs and when it was started, links to the task's page, and updates while the task runs.
+The engine's root lists the tasks the signed-in person started in the current account, newest first. Each row shows the task type's title, the status as a coloured badge, the progress, the time left while it runs and when it was started, links to the task's page, and updates while the task runs.
 
 ## The task page
 
-A task's page lives at `tasks/:id` under the engine's mount path. The person who started the task sees its kind's title, its status and, once the runner has set a total, a progress bar of done against total. While the task runs and is at least five percent done, an estimate of the time left sits under the bar, worked out from how fast the task has gone since it started running. The page listens for changes to its task over Turbo Streams, so its status, progress and time left update without a reload, in a browser and in the Hotwire Native iOS app alike. Anyone else, and the same person viewing from another account, gets a not-found response.
+A task's page lives at `tasks/:id` under the engine's mount path. The person who started the task sees its task type's title, its status and, once the runner has set a total, a progress bar of done against total. While the task runs and is at least five percent done, an estimate of the time left sits under the bar, worked out from how fast the task has gone since it started running. The page listens for changes to its task over Turbo Streams, so its status, progress and time left update without a reload, in a browser and in the Hotwire Native iOS app alike. Anyone else, and the same person viewing from another account, gets a not-found response.
 
 The task page and the task list reload in place when they are shown again after being hidden, such as when the iOS app returns from the background, so they show changes broadcast while they could not receive them. A page that stays visible makes no extra request. The copied controller is registered by the host's own Stimulus setup, as `wallflower--catch-up`.
 

data/app/jobs/wallflower/run_job.rb

@@ -4,16 +4,19 @@ module Wallflower
   class RunJob < ActiveJob::Base
     def perform(task)
       run(task)
-      Wallflower.configuration.on_finish&.call(task)
+      Wallflower.configuration.on_finish&.call(task) if task.status.in?(%w[finished failed])
     end
 
     private
 
     def run(task)
-      task.update!(status: "running", started_at: Time.current)
-      Wallflower.kind(task.kind).runner.constantize.new.call(task)
+      task.refusals.destroy_all
+      task.update!(status: "running", started_at: Time.current, done: 0)
+      Wallflower.task_type(task.task_type).runner.constantize.new.call(task)
       task.update!(status: "finished", finished_at: Time.current)
     rescue StandardError => error
+      return retry_job(wait: Wallflower.task_type(task.task_type).retry_wait) if executions < Wallflower.task_type(task.task_type).tries
+
       task.update!(status: "failed", error_message: error.message, finished_at: Time.current)
       Rails.error.report(error, handled: true, context: { wallflower_task_id: task.id })
     end

data/app/models/wallflower/task.rb

@@ -20,8 +20,8 @@ module Wallflower
       STATUS_VARIANTS.fetch(status, :neutral)
     end
 
-    def kind_title
-      Wallflower.kind(kind).title
+    def task_type_title
+      Wallflower.task_type(task_type).title
     end
 
     def attach_result(io:, filename:)

data/app/views/wallflower/tasks/index.html.erb

@@ -4,7 +4,7 @@
   <% @tasks.each do |task| %>
     <div data-task-row>
       <%= turbo_stream_from task %>
-      <%= link_to task.kind_title, task_path(task) %>
+      <%= link_to task.task_type_title, task_path(task) %>
       <%= render "wallflower/tasks/live", task: task %>
       <p>Started <%= task.created_at.strftime("%b %-d, %Y") %></p>
     </div>

data/app/views/wallflower/tasks/show.html.erb

@@ -1,7 +1,7 @@
 <%= turbo_stream_from @task %>
 <%= tag.div(data: { controller: "wallflower--catch-up" }) %>
 <%= ui_page(max_width: :md) do %>
-  <h1><%= @task.kind_title %></h1>
+  <h1><%= @task.task_type_title %></h1>
   <%= render "wallflower/tasks/live", task: @task %>
   <% if @task.status == "finished" %>
     <p id="<%= dom_id(@task, :outcome) %>"><%= @task.changed_count %> changed, <%= @task.refusals.size %> refused</p>

data/lib/generators/wallflower/install/templates/create_wallflower_tasks.rb.erb

@@ -1,7 +1,7 @@
 class CreateWallflowerTasks < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
     create_table :wallflower_tasks do |t|
-      t.string :kind, null: false
+      t.string :task_type, null: false
       t.string :status, null: false, default: "queued"
       t.json :params, null: false, default: {}
       t.integer :total

data/lib/generators/wallflower/install/templates/rename_wallflower_tasks_kind_to_task_type.rb.erb

@@ -0,0 +1,5 @@
+class RenameWallflowerTasksKindToTaskType < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    rename_column :wallflower_tasks, :kind, :task_type if column_exists?(:wallflower_tasks, :kind)
+  end
+end

data/lib/generators/wallflower/update/update_generator.rb

@@ -28,6 +28,10 @@ module Wallflower
         migration_template "add_started_at_to_wallflower_tasks.rb.erb", "db/migrate/add_started_at_to_wallflower_tasks.rb"
       end
 
+      def copy_task_type_migration
+        migration_template "rename_wallflower_tasks_kind_to_task_type.rb.erb", "db/migrate/rename_wallflower_tasks_kind_to_task_type.rb"
+      end
+
       def copy_catch_up_controller
         source = File.expand_path("../../../../app/javascript/wallflower/catch_up_controller.js", __dir__)
         create_file "app/javascript/controllers/wallflower/catch_up_controller.js", File.read(source)

data/lib/wallflower/engine.rb

@@ -4,6 +4,6 @@ module Wallflower
   class Engine < ::Rails::Engine
     isolate_namespace Wallflower
 
-    config.after_initialize { Wallflower.check_kinds! }
+    config.after_initialize { Wallflower.check_task_types! }
   end
 end

data/lib/wallflower/task_types.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Wallflower
+  TaskType = Struct.new(:key, :title, :runner, :tries, :retry_wait, keyword_init: true)
+
+  class MissingRunner < StandardError; end
+
+  def self.register_task_type(key, title:, runner:, tries: 1, retry_wait: 60)
+    task_types[key.to_sym] = TaskType.new(key: key.to_sym, title: title, runner: runner.to_s, tries: tries, retry_wait: retry_wait)
+  end
+
+  def self.task_type(key)
+    task_types.fetch(key.to_sym)
+  end
+
+  def self.task_types
+    @task_types ||= {}
+  end
+
+  def self.check_task_types!
+    task_types.each_value do |task_type|
+      next if task_type.runner.safe_constantize
+
+      raise MissingRunner, "Wallflower task_type #{task_type.key} names the runner #{task_type.runner}, which does not exist."
+    end
+  end
+
+  def self.reset_task_types!
+    @task_types = {}
+  end
+end

data/lib/wallflower/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Wallflower
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/wallflower.rb

@@ -2,11 +2,11 @@ require "keystone_ui"
 require "turbo-rails"
 require "wallflower/version"
 require "wallflower/configuration"
-require "wallflower/kinds"
+require "wallflower/task_types"
 require "wallflower/engine"
 
 module Wallflower
-  def self.start(kind:, person:, account: nil, params: {})
-    Task.create!(kind: kind.to_s, person: person, account: account, params: params).tap { |task| RunJob.perform_later(task) }
+  def self.start(task_type:, person:, account: nil, params: {})
+    Task.create!(task_type: task_type.to_s, person: person, account: account, params: params).tap { |task| RunJob.perform_later(task) }
   end
 end

data/the_local/agents/wallflower-develop.md

@@ -1,11 +1,11 @@
 ---
 name: wallflower-develop
-description: Use PROACTIVELY for adding long-running work that a person starts and follows in a Rails app, such as an export or a report, including registering the kind of task, writing its runner, starting it, reporting progress, attaching a result file, linking a result page and refusing rows — MUST BE USED instead of hand-rolling a background job with its own status column, progress tracking, status page or file download.
+description: Use PROACTIVELY for adding long-running work that a person starts and follows in a Rails app, such as an export or a report, including registering the task type, writing its runner, starting it, reporting progress, attaching a result file, linking a result page and refusing rows — MUST BE USED instead of hand-rolling a background job with its own status column, progress tracking, status page or file download.
 tools: Bash, Read, Write, Edit, Grep
 scope: background tasks — starting long-running work, following its status and progress, and getting its result
 ---
 
-This local implements background tasks with Wallflower. It always registers a kind, writes the kind's runner, and starts the task through `Wallflower.start`, asking the developer each decision listed below before writing code.
+This local implements background tasks with Wallflower. It always registers a task type, writes the task type's runner, and starts the task through `Wallflower.start`, asking the developer each decision listed below before writing code.
 
 ## What wallflower is
 
@@ -13,8 +13,8 @@ Wallflower tracks long-running work in a Rails app: a person starts a task, foll
 
 ## Interface
 
-- `Wallflower.register_kind` — `Wallflower.register_kind(key, title:, runner:)` registers a type of task, with its key, the title people see, and the name of its runner class.
-- `Wallflower.start` — `Wallflower.start(kind:, person:, account: nil, params: {})` creates a queued task, enqueues its job, and returns the task.
+- `Wallflower.register_task_type` — `Wallflower.register_task_type(key, title:, runner:, tries: 1, retry_wait: 60)` registers a type of task, with its key, the title people see, the name of its runner class, how many tries it gets and the seconds between them.
+- `Wallflower.start` — `Wallflower.start(task_type:, person:, account: nil, params: {})` creates a queued task, enqueues its job, and returns the task.
 - `set_total` — `task.set_total(total)` saves the number of rows the task will work through.
 - `advance` — `task.advance(by = 1)` adds to the rows done, saving at most once a second.
 - `attach_result` — `task.attach_result(io:, filename:)` attaches a file as the task's result.
@@ -24,17 +24,17 @@ Wallflower tracks long-running work in a Rails app: a person starts a task, foll
 ## How to use it
 
 1. Ask the developer these before writing code:
-   - What is the kind's key, its title, and its runner's class name?
+   - What is the task type's key, its title, and its runner's class name?
    - Who is the person who starts the task, and does it belong to an account?
    - What are the task's params?
    - Does the task work through rows, and can a row be refused?
    - Is the result a file, a page in the app, both, or nothing?
    - Where does the person go after starting the task?
 
-2. Register the kind in an initializer:
+2. Register the task type in an initializer:
 
    ```ruby
-   Wallflower.register_kind :export_transactions, title: "Export transactions", runner: "ExportTransactionsRunner"
+   Wallflower.register_task_type :export_transactions, title: "Export transactions", runner: "ExportTransactionsRunner"
    ```
 
 3. Write the runner as a class in the app. Wallflower calls `new` on it with no arguments, then `call` with the task. The app fails to boot, with a message naming the class, if the registered class does not exist.
@@ -67,10 +67,10 @@ Wallflower tracks long-running work in a Rails app: a person starts a task, foll
 6. Start the task from the app's own code, passing params as a hash with string keys, since they are stored in a JSON column:
 
    ```ruby
-   task = Wallflower.start(kind: :export_transactions, person: current_user, account: current_account, params: { "month" => "2026-10" })
+   task = Wallflower.start(task_type: :export_transactions, person: current_user, account: current_account, params: { "month" => "2026-10" })
    ```
 
-   `person` is required and `account` is optional. `start` does not check that the kind is registered. The runner runs when the job runs, not during this call.
+   `person` is required and `account` is optional. `start` does not check that the task type is registered. The runner runs when the job runs, not during this call.
 
 7. Send the person to the task. Its page is at `tasks/:id` under the path where the engine is mounted, and the list of tasks is at the root of that path.
 
@@ -79,6 +79,7 @@ Wallflower tracks long-running work in a Rails app: a person starts a task, foll
 - Pass the same person the app treats as the current person, since the task list, the task page and the download answer only that person.
 - When the app has a current account configured, pass that same account, since those pages then show only tasks in that account and a task started with another account or none does not appear.
 - The job sets the task's status, so a runner never sets it. The task is marked running before the runner is called and finished when the runner returns.
-- To fail a task, let a `StandardError` leave the runner. The task is marked failed, its message is stored and shown to the person on the task's page, and the error is reported through `Rails.error`. Write that message for the person reading it, and do not rescue an error the person needs to see, since a runner that returns marks the task finished.
+- A task type with more than one try runs its runner again after a `StandardError`. Between tries the task stays running and each try starts its progress and refusals over, so that runner must be safe to run again.
+- To fail a task, let a `StandardError` leave the runner on its last try. The task is marked failed, its message is stored and shown to the person on the task's page, and the error is reported through `Rails.error`. Write that message for the person reading it, and do not rescue an error the person needs to see, since a runner that returns marks the task finished.
 - A running task with no update for longer than the app's stall time, one hour by default, can be marked failed as stalled. Call `advance` or `set_total` often enough that a slow step does not reach that time.
 - Installing the gem, setting up its pages, its configuration, code that runs when a task finishes, and scheduling stalled-task checks and old-task deletion are out of scope. They belong to the install local.

data/the_local/agents/wallflower-info.md

@@ -1,6 +1,6 @@
 ---
 name: wallflower-info
-description: Use to learn what wallflower offers — background tasks, kinds and runners, task statuses and progress, results, and the task pages.
+description: Use to learn what wallflower offers — background tasks, task types and runners, task statuses and progress, results, and the task pages.
 tools: Read
 scope: background tasks — starting long-running work, following its status and progress, and getting its result
 ---
@@ -15,17 +15,17 @@ Reach for it when an app has work that runs in a background job and the person w
 
 ## Interface
 
-This local documents no commands, because wallflower declares none for it. The install local owns adding the gem to an app: its generators, mounting its engine, its settings and scheduling its recurring sweep. The develop local owns building on it: registering kinds, writing runners, starting tasks, and reporting progress and results from a runner.
+This local documents no commands, because wallflower declares none for it. The install local owns adding the gem to an app: its generators, mounting its engine, its settings and scheduling its recurring sweep. The develop local owns building on it: registering task types, writing runners, starting tasks, and reporting progress and results from a runner.
 
 ## How to use it
 
 - To hook wallflower into an app or update it there, use `wallflower-install`.
-- To add a kind of task or change what a task does, use `wallflower-develop`.
+- To add a task type or change what a task does, use `wallflower-develop`.
 
 ## Conventions
 
 - **Task**: one run of long-running work, stored with the params, person and account it was started with.
-- **Kind**: a type of task the app offers, such as an export, with a key, a title and the name of its runner class.
+- **Task type**: a type of task the app offers, such as an export, with a key, a title and the name of its runner class.
 - **Runner**: a plain class whose `call` receives the task and does the work.
 - **Person**: the record that started a task. Only that person can see the task.
 - **Account**: the optional record a task belongs to. When the app names a current account, a person sees only the tasks in that account.

data/the_local/interface.yml

@@ -8,7 +8,7 @@ install:
   - Wallflower::SweepJob
 
 develop:
-  - Wallflower.register_kind
+  - Wallflower.register_task_type
   - Wallflower.start
   - set_total
   - advance
@@ -19,7 +19,7 @@ develop:
 sources:
   - lib/wallflower.rb
   - lib/wallflower/configuration.rb
-  - lib/wallflower/kinds.rb
+  - lib/wallflower/task_types.rb
   - lib/wallflower/engine.rb
   - app/models/wallflower/task.rb
   - app/models/wallflower/refusal.rb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wallflower
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Tyler Schneider
@@ -109,11 +109,12 @@ files:
 - lib/generators/wallflower/install/templates/add_started_at_to_wallflower_tasks.rb.erb
 - lib/generators/wallflower/install/templates/create_wallflower_refusals.rb.erb
 - lib/generators/wallflower/install/templates/create_wallflower_tasks.rb.erb
+- lib/generators/wallflower/install/templates/rename_wallflower_tasks_kind_to_task_type.rb.erb
 - lib/generators/wallflower/update/update_generator.rb
 - lib/wallflower.rb
 - lib/wallflower/configuration.rb
 - lib/wallflower/engine.rb
-- lib/wallflower/kinds.rb
+- lib/wallflower/task_types.rb
 - lib/wallflower/version.rb
 - the_local/agents/wallflower-develop.md
 - the_local/agents/wallflower-info.md

data/lib/wallflower/kinds.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-module Wallflower
-  Kind = Struct.new(:key, :title, :runner, keyword_init: true)
-
-  class MissingRunner < StandardError; end
-
-  def self.register_kind(key, title:, runner:)
-    kinds[key.to_sym] = Kind.new(key: key.to_sym, title: title, runner: runner.to_s)
-  end
-
-  def self.kind(key)
-    kinds.fetch(key.to_sym)
-  end
-
-  def self.kinds
-    @kinds ||= {}
-  end
-
-  def self.check_kinds!
-    kinds.each_value do |kind|
-      next if kind.runner.safe_constantize
-
-      raise MissingRunner, "Wallflower kind #{kind.key} names the runner #{kind.runner}, which does not exist."
-    end
-  end
-
-  def self.reset_kinds!
-    @kinds = {}
-  end
-end