plutonium 0.68.0 → 0.69.0

data/config/locales/en/async.yml

@@ -7,8 +7,11 @@ en:
     async:
       run:
         label: "%{name} #%{id}"
+        interaction: "Action"
+        progress: "%{done} / %{total}"
         target_type: "Target type"
         enqueue_failed: "could not be enqueued for execution"
+        reject_outside_pre_check: "%{run_class}#reject is only available inside pre_check"
       executor:
         target_missing: "Target %{id} is no longer available"
         target_unauthorized: "Target %{id} is no longer permitted by %{action}"
@@ -17,6 +20,12 @@ en:
           one: "stopped at the first target failure (%{policy} policy); %{count} target was not attempted"
           other: "stopped at the first target failure (%{policy} policy); %{count} targets were not attempted"
         partial_batch_refused: "%{unresolved} of %{total} targets could not be resolved; a %{policy} run does not apply a partial batch"
+        pre_check_arity:
+          targeted: "%{run_class}#pre_check must take the records: define pre_check(records) on a run with perform_on"
+          opaque: "%{run_class}#pre_check must take no arguments: define pre_check on a run with perform"
+        rejections_truncated:
+          one: "and %{count} more problem was found"
+          other: "and %{count} more problems were found"
       context:
         initiator_missing: "run %{run} has no initiator (%{type}#%{id} no longer exists)"
         tenant_missing: "run %{run} was scoped to %{type}#%{id}, which no longer exists; refusing to resolve targets without a tenant"
@@ -25,10 +34,11 @@ en:
         targets: "%{done} of %{total} targets (%{percent}%)"
         working: "Working…"
         no_total: "No progress total was recorded"
-        failures: "Failures"
         error_count:
           one: "%{count} error"
           other: "%{count} errors"
         target_failure: "#%{target_id}: %{message}"
+        rejected: "Nothing was processed"
       banner:
         view_progress: "View progress"
+        view_run: "View run"

data/docs/reference/behavior/async-interactions.md

@@ -26,6 +26,8 @@ Plutonium.configure do |config|
   config.async_interactions.enabled = true
   config.async_interactions.queue = :default        # ActiveJob queue for run jobs
   config.async_interactions.stall_after = 1.hour     # see Stalled runs, below
+  config.async_interactions.max_rejections = 100     # pre_check problems stored per run
+  config.async_interactions.recent_runs_window = 10.minutes  # finished runs stay in your banner this long
 end
 ```
 
@@ -123,6 +125,58 @@ Validating means staging first, since Shrine validates an assigned cached file,
 
 Where no `backend:` is declared: `config.async_interactions.attachment_backend`, then `config.attachment_backend`, then auto-detection (active_shrine loaded → Shrine, else ActiveStorage). Same layering wizards use.
 
+### Checking input before processing
+
+Validations on the interaction run in the request, so they suit cheap checks (an uploader's size and type rules already fail the form there). A check too slow for a request, like reading every row of a large file, goes in the run's `pre_check`. It runs in the job, before any work, and refuses the input with `reject`:
+
+```ruby
+require "csv"
+
+class ImportTasks < ResourceInteraction
+  attribute :import_file
+  input :import_file, as: :file
+
+  async do
+    def pre_check
+      each_row do |row, line|
+        reject "line #{line}: title is missing" if row["title"].blank?
+      end
+    rescue CSV::MalformedCSVError => e
+      reject "the file is not valid CSV: #{e.message}"
+    end
+
+    # One transaction: an opaque run restarts from scratch after a reap, so a
+    # partial import would otherwise be imported twice.
+    def perform
+      Task.transaction { each_row { |row, _line| Task.create!(title: row["title"]) } }
+    end
+
+    private
+
+    # Read whole, as UTF-8 without Excel's byte-order mark: the stored file
+    # comes back as binary, and a BOM would become part of the first header.
+    def each_row
+      text = attachment(:import_file).download.force_encoding(Encoding::UTF_8).delete_prefix("\uFEFF")
+      CSV.parse(text, headers: true).each.with_index(2) do |row, line|
+        yield row, line unless row.fields.all?(&:blank?)
+      end
+    end
+  end
+end
+```
+
+Rows are numbered from 2 so a message matches the line a spreadsheet shows (the header is line 1), and blank lines are skipped without shifting the numbers after them. The dummy app's `ImportTasksInteraction` is the full version, with a column check, an empty-file check and status validation.
+
+- `reject` records a problem and returns, so one pass reports every bad row. It does not stop the check: `return` explicitly where nothing after it would make sense, such as a missing column.
+- If anything was rejected, the run ends `failed` with `outcome == "rejected"`, the problems listed on its progress page, and `perform` / `perform_on` never runs. The page shows a warning "Rejected" badge and "Nothing was processed". On a `:continue` run, targets that had gone missing or lost permission are recorded before the check runs, so they still appear in the list (and count toward `progress_done`) even though nothing was performed.
+- A run with `perform_on` declares `pre_check(records)` and receives the resolved, authorized records the loop is about to process. A `pre_check` with the wrong arity fails the run with a message naming the signature it expects.
+- An exception raised inside `pre_check` fails the run the ordinary way (`outcome == "failed"`): the check broke, the input was not judged.
+- `reject` called outside `pre_check` raises.
+- Only the first `config.async_interactions.max_rejections` problems (default 100) are stored, followed by one "and N more problems were found" entry.
+- The check runs again when a stalled run is resumed, so it must only read. An opaque run always re-checks. A resumed targeted run checks the records it has left, unless an earlier pass already applied a target (that pass's check passed, so it is not repeated).
+- A targeted check receives the records as loaded when the run resolved its targets. `perform_on` gets each record re-read just before it runs, so a verdict based on record state can be stale by then; re-check anything that must hold at the moment of the work inside `perform_on`.
+- A long check must call `heartbeat!` (see [Long work must say it is alive](#long-work-must-say-it-is-alive)).
+
 ### Sharing one run across interactions
 
 Pass a class instead of a block when several interactions do the same kind of work:
@@ -175,7 +229,9 @@ run.state    # "completed"
 run.outcome  # "completed_with_errors"   (state == "completed" && errors_log.any?)
 ```
 
-The progress page, the table's `outcome` column, and the running banner all render `outcome`, never bare `state`.
+A run whose `pre_check` rejected its input reads `outcome == "rejected"` (its `state` is `"failed"`, and nothing was processed). A run that failed while working reads `"failed"`.
+
+The progress page, the table's `outcome` column, and the running banner's entries for finished runs render `outcome`, never bare `state`.
 
 ## Registering the Run resource
 
@@ -207,17 +263,18 @@ A registered run resource gets, for free:
 
 - **A progress page.** The show page IS the progress page. It self-refreshes via polling (not ActionCable) while `state` is `pending`/`running`, and stops carrying the poll once the run settles, so a finished run is a static page, not a background request per viewer.
 - **A self-refreshing index.** The runs index polls on the same terms as the progress page: one frame around the whole collection, armed only while some run is still working, disarmed the moment none is. One request per interval regardless of page size, and it re-fetches the URL you are on, so filters, sort and page survive the refresh. A frame per row is not an option: `turbo-frame` is not in the content model of `tr`, so the parser hoists it out of the table before Turbo sees it.
-- **A running banner.** Any OTHER resource's index page lists runs currently in progress against it, above the collection, so a user who dispatched a bulk action and navigated away can find it again. Scoped through the same `authorized_resource_scope` every cross-resource read goes through, so a run in another tenant can never surface. If a resource_class is registered in a portal that never registered `Run`, the banner is skipped there instead of raising while trying to build a link to a route that doesn't exist.
+- **A running banner.** Any OTHER resource's index page lists runs currently in progress against it, above the collection, so a user who dispatched a bulk action and navigated away can find it again. It also lists the viewer's own runs that finished within `config.async_interactions.recent_runs_window` (default 10 minutes, newest first, at most 5), with their outcome and a "View run" link. A dispatch sends the user back to this index, and a short run, or one its `pre_check` rejected, has often finished before the page renders. Scoped through the same `authorized_resource_scope` every cross-resource read goes through, so a run in another tenant can never surface. If a resource_class is registered in a portal that never registered `Run`, the banner is skipped there instead of raising while trying to build a link to a route that doesn't exist.
 - **Tenant scoping.** A run's `associated_with` scope filters on the tenant it was dispatched in (recorded on the row), not on walking the object graph, since the two polymorphic tenant columns make the generic scope unusable.
+- **Runs named by their interaction.** A run declared with an `async` block is titled by its interaction's label ("Archive all (async) #19"), from `presents label:` or, without one, the class name minus its `Interaction` suffix. A standalone run class passed to `async` can be shared by several interactions, so it is named after its own class. Only `presents label:` reaches the run: a `label:` on the `action` declaration, or a `plutonium.actions.<model>.<action>` translation, renames the button but not the runs it starts, so put the label on the interaction when both should match.
 - **A humanized target label.** `run.target_label` reads the target class through `model_name.human` ("Post", not "Blogging::Post"), falling back to the raw string if that class has since been renamed or removed.
 
 The progress page, mid-run:
 
-![A run's progress page showing a Running badge, a progress bar at 27 of 50 targets, and the run's type, target type, initiator and timestamps](/images/reference/async-progress-page.png)
+![A run's progress page showing a Running badge, a progress bar at 27 of 50 targets, and the run's action, target type, initiator and timestamps](/images/reference/async-progress-page.png)
 
 And the banner it leaves on the target resource's index while it is still going:
 
-![A Task index with a banner above the collection reading "Archive Tasks Async Interaction Run #19 Running", with a View progress link](/images/reference/async-running-banner.png)
+![A Task index with a banner above the collection reading "Archive all (async) #19 Running", with a View progress link](/images/reference/async-running-banner.png)
 
 ## Stalled runs and ReapJob
 
@@ -255,7 +312,7 @@ What bounds that is `lock_version`. Both the reaper's resume and the executor's
 
 `stall_after` is a **silence** threshold, not a runtime limit. Every write the executor makes refreshes the clock, so a targeted run with quick targets heartbeats once per target for free. Two shapes get nothing, and both are exactly the "long-running task" case:
 
-- **Opaque work.** Between the claim and `finish!` the executor writes nothing, because there is nothing to count. A `perform` that outlives `stall_after` is reaped mid-flight and, having no `handled_target_ids` to resume from, re-runs **from scratch**.
+- **Opaque work, and any `pre_check`.** Between the claim and `finish!` the executor writes nothing, because there is nothing to count. A `perform` that outlives `stall_after` is reaped mid-flight and, having no `handled_target_ids` to resume from, re-runs **from scratch**.
 - **A single `perform_on`** that outlives `stall_after` on its own.
 
 Call `heartbeat!` from inside such work:

data/docs/reference/generators/lite.md

@@ -36,19 +36,43 @@ another environment is left untouched.
 
 ## `pu:lite:maintenance`
 
-Installs `app/jobs/sqlite_maintenance_job.rb` and (when `solid_queue` is present)
-schedules it in `config/recurring.yml`.
+Installs `app/jobs/sqlite_maintenance_job.rb` and, when `solid_queue` is present,
+schedules it in `config/recurring.yml` along with SolidQueue's finished-job cleanup.
 
 ```bash
 rails g pu:lite:maintenance
-# custom schedule:
-rails g pu:lite:maintenance --schedule="every day at 4am"
+# custom schedules:
+rails g pu:lite:maintenance --schedule="every day at 4am" \
+  --clear-finished-schedule="every 30 minutes"
 ```
 
 The job runs `PRAGMA optimize` on every configured SQLite database and `VACUUM`
 only on databases without live 24/7 writers (`primary`, `errors`, `rails_pulse`
 by default; edit `VACUUM_DBS` in the generated job to suit your app).
 
+Even on those databases, `VACUUM` is skipped unless at least 10% of the file's
+pages are free (`VACUUM_MIN_FREE_RATIO`). The rewrite holds its exclusive lock for
+as long as it takes, which on a large `primary` can be long enough for requests to
+time out, and WAL reuses free pages anyway. In practice it runs after a bulk delete
+and is skipped (with a log line) the rest of the time.
+
+### Clearing finished SolidQueue jobs
+
+SolidQueue keeps finished jobs by default (`preserve_finished_jobs`) and never
+deletes them on its own, so the queue database grows without bound. The generator
+adds this task:
+
+```yaml
+clear_solid_queue_finished_jobs:
+  command: "SolidQueue::Job.clear_finished_in_batches(sleep_between_batches: 0.3)"
+  schedule: "every hour at minute 12"
+```
+
+It deletes jobs finished longer ago than `clear_finished_jobs_after` (one day by
+default) in batches, sleeping between them so the scheduler and workers keep their
+turn at the write lock. New Rails 8 apps already ship this task; the generator
+detects any existing `clear_finished_in_batches` entry and skips.
+
 **Why VACUUM only some databases?** SolidQueue, Solid Cache and Solid Cable write
 to their databases constantly. `VACUUM` takes a global *exclusive* lock for its
 whole duration, which stalls and errors those processes (e.g. SolidQueue process
@@ -61,5 +85,5 @@ Databases listed in the job that don't exist in `config/database.yml` are skippe
 at runtime, so the same job is safe regardless of which `pu:lite:*` generators you
 have run.
 
-If `solid_queue` is not installed, the job file is still created but not scheduled:
-add a `sqlite_maintenance` entry to whatever scheduler you use.
+If `solid_queue` is not installed, the job file is still created but nothing is
+scheduled: add a `sqlite_maintenance` entry to whatever scheduler you use.

data/docs/reference/i18n.md

@@ -145,7 +145,7 @@ end
 
 ## Derived labels
 
-Actions, scopes, filters, kanban columns and wizard steps default to a humanized version of their key. Each has a convention key that takes precedence over that fallback, and a `label:` option that takes precedence over both. For an action backed by an interaction, the interaction's explicit `presents label:` also counts as declared and wins over the convention; only the class-name default yields to it.
+Scopes, filters, kanban columns and wizard steps default to a humanized version of their key. An action backed by an interaction defaults to the interaction's class name without its `Interaction` suffix (`ArchivePostsInteraction` reads "Archive Posts"). Each has a convention key that takes precedence over that fallback, and a `label:` option that takes precedence over both. For an action backed by an interaction, the interaction's explicit `presents label:` also counts as declared and wins over the convention; only the class-name default yields to it.
 
 ```yaml
 en: