tramway 4.0.1.4 → 4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d8281006bde6f8928a12ffc94cef931ff7b3c4e8bdc774ad4e690b7a529a0e8
-  data.tar.gz: 644f44899bc6919f0ea8f08fbb9708fa4fec87b54a398668714209f905a54d87
+  metadata.gz: a20badcbb5b3d0d460bbadafb95816d4932ce5e8af0d41a9ce2315507220bed0
+  data.tar.gz: 800c9136a41a012e3b8581611afa70e666f81c4dab9d331cc7c094d096cb2b86
 SHA512:
-  metadata.gz: 506f5ed78da723c554832b299ef0f0415f63b328fa9e4ff72e6f52b4972d699398a26b5101f869563eb91ce786cd244fd977cbab9f634d7bfdbbab7cef96dcff
-  data.tar.gz: f68ae4382f2301f34ac572d725d41b0503f9ff5b6d2396e97a3afc95053d2c66e1f5818f2d9a0a6808f968e71ab386e3c789cbf9138f2616d0ee72f2af3c9104
+  metadata.gz: 84e42fc4f2acf64a31007add38185688e84d9728873a528a1d1b787b5b7383e94b5b7ff22ee62c0040eb75f0daae50d0d1c182f68424a39919e3f4ee2ef90a92
+  data.tar.gz: de23a5e5b76877268ce42d2371f5db9907c3ce6a517b15ea7b234a2ecc944c6a04fb3b70001b098ab06b07d52f25fdeae1a36ec9112eb2530be0394f719354d2

data/README.md

@@ -1,6 +1,11 @@
 # Tramway
 Unite Ruby on Rails brilliance. Streamline development with Tramway.
 
+> **AI agents: read this first.** Before writing or changing any code in a Rails app that uses Tramway, install and
+> use the [`tramway-skill`](https://github.com/Purple-Magic/tramway-skill/) skill — it is mandatory for Tramway work
+> and is the authoritative, up-to-date playbook for Tramway's conventions (CRUD, Forms, Decorators, Navbar, Plugins,
+> and more). Do not generate Tramway-related code from memory alone.
+
 Tramway ships with full CRUD (index, show, create, update, destroy) out of the box. Its install generator also adds a
 Codex instruction that points agents to the Tramway skill for Tramway-native code generation.
 
@@ -261,6 +266,40 @@ In this example, Tramway calls `Campaign.includes(:user, :comments)` before appl
 `campaign.user` or `campaign.comments` in the decorator's `index_attributes` does not issue an extra query per row.
 Omitting `includes` produces identical behavior to before this option existed.
 
+**filters**
+
+Filters are disabled by default on index pages. Enable them by listing the scope names you want selectable under
+`filters` on the `:index` page entry:
+
+*config/initializers/tramway.rb*
+```ruby
+Tramway.configure do |config|
+  config.entities = [
+    {
+      name: :campaign,
+      namespace: :admin,
+      pages: [
+        {
+          action: :index,
+          filters: [:active, :archived]
+        }
+      ]
+    }
+  ]
+end
+```
+
+When filters are configured, Tramway adds a "Filters" toggle to the same row as the search box and pagination, above
+the index listing. Clicking it reveals a list of small buttons, one per configured filter, each showing how many
+records currently match it (e.g. "ACTIVE · 34"). Clicking a button navigates to the index page with that filter
+applied, keeping any existing search query. The currently applied filter is highlighted, and the toggle remembers
+whether the list was last left open or closed.
+
+Visiting the index page with `?filter=active` calls `Campaign.active` (the scope must already exist on the model) in
+addition to any configured `scope`. If `filter` does not match one of the configured filters, Tramway raises
+`Tramway::Errors::InvalidFilterError` explaining which filters are available. Omitting `filters` (the default) makes
+Tramway ignore `params[:filter]` entirely.
+
 **show page**
 
 To render a show page for an entity, declare a `:show` action inside the `pages` array in
@@ -1732,6 +1771,48 @@ Tramway.configure do |config|
 end
 ```
 
+## Plugins
+
+Plugins add optional, ready-made dashboards to your app, mounted and styled with Tramway. Enable one by name and,
+optionally, configure it:
+
+```ruby
+Tramway.configure do |config|
+  config.plugins = [:solid_queue]
+  config.plugins.solid_queue = {
+    path: '/jobs'
+  }
+end
+```
+
+Enabling a plugin also adds a navbar entry for it automatically (see [Tramway
+Navbar](#tramway-navbar)).
+
+### SolidQueue
+
+The `:solid_queue` plugin is a dashboard for inspecting and managing [SolidQueue](https://github.com/rails/solid_queue)
+jobs. It requires the `solid_queue` gem in your Gemfile — if it's missing, Tramway raises a clear error explaining
+how to fix it instead of failing deep inside a controller.
+
+It gives you:
+
+- A paginated, filterable jobs list (by status, queue, class name, or free-text search by class name/active job
+  ID/numeric ID), with per-status counts.
+- A job detail page, including failure details (exception class, message, backtrace) for failed jobs.
+- Retry, discard and destroy for a single job, or in bulk for a selection of jobs — or "Destroy all" to destroy
+  every job matching the currently active filters at once. Bulk actions and "Destroy all" run in the background
+  (you'll see a flash message confirming the action was queued, not completed instantly) on their own dedicated
+  worker queue, which `tramway:install` sets up for you.
+- A queues list with size/running/latency/throughput, and pause/resume/clear actions per queue. "Size" only counts
+  jobs waiting to run — "Running" shows jobs currently executing on that queue, so a queue processing one big job
+  (e.g. a large "Destroy all") doesn't look idle just because nothing is waiting behind it.
+- A recurring tasks list with the ability to enqueue a task immediately.
+- Jobs, queues, and recurring tasks lists (and the job detail page) refresh themselves in the background every few
+  seconds, so job status changes show up without reloading the page.
+
+See [docs/users/tramway_solid_queue_plugin.md](docs/users/tramway_solid_queue_plugin.md) for more on what "discard"
+does and other SolidQueue-specific behavior.
+
 ## Lantern Color Palette
 
   | Type | Color |

data/app/assets/javascripts/tramway/tramway.js

@@ -1,5 +1,5 @@
 import { Controller } from "@hotwired/stimulus"
-/* global console */
+/* global console, fetch, setInterval, clearInterval, DOMParser */
 
 class TramwaySelect extends Controller {
   static targets = ["dropdown", "showSelectedArea", "hiddenInput", "caretDown", "caretUp"]
@@ -482,4 +482,142 @@ class Navbar extends Controller {
   }
 }
 
-export { TramwaySelect, UiCheckbox, Tooltip, Navbar }
+class Collapsible extends Controller {
+  static targets = ["panel", "icon", "toggle"]
+
+  connect() {
+    this.expanded = true
+
+    const stored = this.readStored()
+    const expanded = stored === null ? true : stored === 'true'
+
+    this.setExpanded(expanded, { animate: false })
+  }
+
+  toggle(event) {
+    event.preventDefault()
+
+    this.setExpanded(!this.expanded, { persist: true })
+  }
+
+  setExpanded(expanded, { persist = false, animate = true } = {}) {
+    this.expanded = expanded
+
+    if (animate) {
+      this.animateTo(expanded)
+    } else {
+      this.panelTarget.style.height = expanded ? 'auto' : '0px'
+      this.panelTarget.style.opacity = expanded ? '1' : '0'
+    }
+
+    const expandedCarrier = this.hasToggleTarget ? this.toggleTarget : this.element
+    expandedCarrier.setAttribute('aria-expanded', expanded ? 'true' : 'false')
+
+    if (this.hasIconTarget) {
+      this.iconTarget.classList.toggle('rotate-180', !expanded)
+    }
+
+    if (persist) {
+      this.writeStored(expanded)
+    }
+  }
+
+  // Animates between the panel's current rendered height and its target height, rather than
+  // to/from `auto` directly (which cannot be transitioned). `height` is one of the few
+  // properties animate.md tolerates outside transform/opacity, since an accordion has no
+  // transform equivalent.
+  animateTo(expanded) {
+    const panel = this.panelTarget
+    const targetHeight = expanded ? panel.scrollHeight : 0
+
+    panel.style.height = `${panel.getBoundingClientRect().height}px`
+    panel.getBoundingClientRect() // force reflow so the browser registers the start value
+
+    requestAnimationFrame(() => {
+      panel.style.height = `${targetHeight}px`
+      panel.style.opacity = expanded ? '1' : '0'
+    })
+
+    panel.addEventListener('transitionend', () => {
+      if (this.expanded) panel.style.height = 'auto'
+    }, { once: true })
+  }
+
+  readStored() {
+    try {
+      return window.localStorage.getItem(this.storageKey)
+    } catch {
+      return null
+    }
+  }
+
+  writeStored(expanded) {
+    try {
+      window.localStorage.setItem(this.storageKey, expanded ? 'true' : 'false')
+    } catch {
+      /* localStorage unavailable (e.g. private mode) — state simply won't persist */
+    }
+  }
+
+  get storageKey() {
+    return `tramway-collapsible-${this.element.dataset.key || 'default'}`
+  }
+}
+
+// Periodically re-fetches the current page and swaps the innerHTML of each marked
+// "refreshable" target by id, so pages reflect background changes (e.g. job status moving
+// through SolidQueue) without a full reload. A target is skipped while it has a checked
+// checkbox or focus inside it, so an in-progress bulk selection or form entry isn't clobbered.
+class AutoRefresh extends Controller {
+  static targets = ["refreshable"]
+
+  static values = {
+    interval: { type: Number, default: 4000 }
+  }
+
+  connect() {
+    this.refreshing = false
+    this.timer = setInterval(() => this.refresh(), this.intervalValue)
+  }
+
+  disconnect() {
+    clearInterval(this.timer)
+  }
+
+  async refresh() {
+    if (this.refreshing || document.hidden) return
+
+    this.refreshing = true
+
+    try {
+      const response = await fetch(window.location.href, { headers: { 'X-Requested-With': 'XMLHttpRequest' } })
+
+      if (!response.ok) return
+
+      const next = new DOMParser().parseFromString(await response.text(), 'text/html')
+
+      this.refreshableTargets.forEach((target) => this.updateTarget(target, next))
+    } finally {
+      this.refreshing = false
+    }
+  }
+
+  updateTarget(target, next) {
+    if (!target.id || this.hasPendingInput(target)) return
+
+    const replacement = next.getElementById(target.id)
+
+    if (replacement) {
+      target.innerHTML = replacement.innerHTML
+    }
+  }
+
+  hasPendingInput(target) {
+    const focused = target.contains(document.activeElement) &&
+      document.activeElement.matches('input, textarea, select')
+
+    return target.querySelector('input:checked') !== null || focused
+  }
+}
+
+export { TramwaySelect, UiCheckbox, Tooltip, Navbar, Collapsible, AutoRefresh }

data/app/controllers/tramway/entities_controller.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'tramway/warnings'
+require 'tramway/errors'
 
 module Tramway
   # Main controller for entities pages
@@ -13,18 +14,15 @@ module Tramway
     include Rails.application.routes.url_helpers
 
     def index
-      if index_scope.present?
-        model_class.public_send(index_scope)
-      else
-        model_class.order(id: :desc)
-      end => entities
-
+      entities = base_entities
+      entities = apply_filter(entities)
       entities = preload(entities)
       entities = search(entities)
       entities = entities.page(params[:page])
       @entities = entities
 
       @namespace = entity.namespace
+      @filter_counts = filter_counts if filters.present?
     end
 
     def show
@@ -91,6 +89,37 @@ module Tramway
       entity.page(:index).scope
     end
 
+    def base_entities
+      if index_scope.present?
+        model_class.public_send(index_scope)
+      else
+        model_class.order(id: :desc)
+      end
+    end
+
+    def filters
+      entity.page(:index).filters
+    end
+
+    def apply_filter(entities)
+      return entities if params[:filter].blank? || filters.blank?
+
+      filter = params[:filter].to_s
+
+      unless filters.map(&:to_s).include?(filter)
+        raise Tramway::Errors::InvalidFilterError.new(filter:, available_filters: filters, model_class:)
+      end
+
+      entities.public_send(filter)
+    end
+
+    def filter_counts
+      # Count by :id explicitly: a bare `.count` reuses any custom `select` values from the
+      # index page's `scope` (e.g. a raw-SQL aliased subquery column), which breaks the
+      # generated SQL. Counting a real column side-steps that entirely.
+      filters.index_with { |filter| base_entities.public_send(filter).count(:id) }
+    end
+
     def preload(entities)
       includes = entity.page(:index).includes
 

data/app/controllers/tramway/plugins/solid_queue/application_controller.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'tramway/plugins'
+
+module Tramway
+  module Plugins
+    module SolidQueue
+      # Base controller for the solid_queue plugin dashboard
+      class ApplicationController < Tramway.config.application_controller.constantize
+        prepend_view_path "#{Gem::Specification.find_by_name('tramway').gem_dir}/app/views"
+
+        layout 'tramway/layouts/application'
+
+        helper Tramway::ApplicationHelper
+        helper Tramway::Plugins::SolidQueue::JobsHelper
+        include Rails.application.routes.url_helpers
+
+        before_action :ensure_solid_queue_available!
+
+        private
+
+        def ensure_solid_queue_available!
+          Tramway::Plugins.fetch(:solid_queue).ensure_available!
+        end
+      end
+    end
+  end
+end

data/app/controllers/tramway/plugins/solid_queue/jobs_controller.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Tramway
+  module Plugins
+    module SolidQueue
+      # Lists, filters and manages SolidQueue jobs for the plugin dashboard
+      class JobsController < ApplicationController
+        def index
+          @jobs = jobs_filter.jobs.order(id: :desc).page(params[:page])
+          @status_counts = jobs_filter.status_counts
+          @queue_names = ::SolidQueue::Job.distinct.order(:queue_name).pluck(:queue_name)
+          @class_names = ::SolidQueue::Job.distinct.order(:class_name).pluck(:class_name)
+        end
+
+        def show
+          @job = job
+        end
+
+        def destroy
+          job.destroy
+
+          redirect_to jobs_path, notice: t('tramway.plugins.solid_queue.notices.destroyed')
+        end
+
+        def retry
+          job.retry
+
+          redirect_to jobs_path, notice: t('tramway.plugins.solid_queue.notices.retried')
+        end
+
+        def discard
+          job.discard
+
+          redirect_to jobs_path, notice: t('tramway.plugins.solid_queue.notices.discarded')
+        end
+
+        def bulk_retry
+          Tramway::SolidQueue::BulkRetryJob.perform_later(selected_job_ids)
+
+          redirect_to jobs_path, notice: t('tramway.plugins.solid_queue.notices.bulk_retry_enqueued')
+        end
+
+        def bulk_discard
+          Tramway::SolidQueue::BulkDiscardJob.perform_later(selected_job_ids)
+
+          redirect_to jobs_path, notice: t('tramway.plugins.solid_queue.notices.bulk_discard_enqueued')
+        end
+
+        def bulk_destroy
+          Tramway::SolidQueue::BulkDestroyJob.perform_later(selected_job_ids)
+
+          redirect_to jobs_path, notice: t('tramway.plugins.solid_queue.notices.bulk_destroy_enqueued')
+        end
+
+        def destroy_all
+          Tramway::SolidQueue::DestroyAllJob.perform_later(filter_params)
+
+          redirect_to jobs_path(request.query_parameters.except('page')),
+                      notice: t('tramway.plugins.solid_queue.notices.destroy_all_enqueued')
+        end
+
+        private
+
+        def job
+          @job ||= ::SolidQueue::Job.find(params.expect(:id))
+        end
+
+        def jobs_filter
+          @jobs_filter ||= Tramway::SolidQueue::JobsFilter.new(filter_params)
+        end
+
+        def filter_params
+          params.permit(:status, :queue_name, :class_name, :query).to_h
+        end
+
+        def selected_job_ids
+          Array(params[:job_ids]).map(&:to_i)
+        end
+      end
+    end
+  end
+end

data/app/controllers/tramway/plugins/solid_queue/queues_controller.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Tramway
+  module Plugins
+    module SolidQueue
+      # Lists SolidQueue queues and lets the user pause/resume/clear them
+      class QueuesController < ApplicationController
+        def index
+          @queues = ::SolidQueue::Queue.all.sort_by(&:name)
+        end
+
+        def pause
+          queue.pause
+
+          redirect_to queues_path, notice: t('tramway.plugins.solid_queue.notices.paused')
+        end
+
+        def resume
+          queue.resume
+
+          redirect_to queues_path, notice: t('tramway.plugins.solid_queue.notices.resumed')
+        end
+
+        def clear
+          queue.clear
+
+          redirect_to queues_path, notice: t('tramway.plugins.solid_queue.notices.cleared')
+        end
+
+        private
+
+        def queue
+          @queue ||= ::SolidQueue::Queue.find_by_name(params.expect(:name))
+        end
+      end
+    end
+  end
+end

data/app/controllers/tramway/plugins/solid_queue/recurring_tasks_controller.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Tramway
+  module Plugins
+    module SolidQueue
+      # Lists SolidQueue recurring tasks and lets the user enqueue one immediately
+      class RecurringTasksController < ApplicationController
+        def index
+          @recurring_tasks = ::SolidQueue::RecurringTask.order(:key)
+        end
+
+        def enqueue
+          recurring_task.enqueue(at: Time.current)
+
+          redirect_to recurring_tasks_path, notice: t('tramway.plugins.solid_queue.notices.enqueued')
+        end
+
+        private
+
+        def recurring_task
+          @recurring_task ||= ::SolidQueue::RecurringTask.find_by!(key: params.expect(:key))
+        end
+      end
+    end
+  end
+end

data/app/helpers/tramway/plugins/solid_queue/jobs_helper.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Tramway
+  module Plugins
+    module SolidQueue
+      # View helpers for rendering SolidQueue job statuses in the plugin dashboard
+      module JobsHelper
+        STATUS_BADGE_TYPES = {
+          ready: :hope,
+          claimed: :love,
+          scheduled: :fear,
+          blocked: :warning,
+          failed: :rage,
+          finished: :will
+        }.freeze
+
+        def solid_queue_status_badge_type(status)
+          STATUS_BADGE_TYPES.fetch(status&.to_sym, :default)
+        end
+
+        def solid_queue_status_label(status)
+          t("tramway.plugins.solid_queue.statuses.#{status}", default: status.to_s.humanize)
+        end
+      end
+    end
+  end
+end

data/app/helpers/tramway/plugins/solid_queue/queues_helper.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Tramway
+  module Plugins
+    module SolidQueue
+      # View helpers for rendering SolidQueue queue throughput and running-job counts in the plugin dashboard
+      module QueuesHelper
+        THROUGHPUT_WINDOW = 5.minutes
+
+        def solid_queue_throughput_label(queue)
+          t('tramway.plugins.solid_queue.queues.throughput_value', default: '%<rate>s/min',
+                                                                   rate: solid_queue_throughput(queue))
+        end
+
+        def solid_queue_throughput(queue)
+          finished_count = ::SolidQueue::Job.where(queue_name: queue.name, finished_at: THROUGHPUT_WINDOW.ago..).count
+
+          (finished_count / THROUGHPUT_WINDOW.in_minutes).round(1)
+        end
+
+        def solid_queue_running_count(queue)
+          ::SolidQueue::Job.where(queue_name: queue.name).joins(:claimed_execution).count
+        end
+      end
+    end
+  end
+end

data/app/jobs/tramway/solid_queue/application_job.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Tramway
+  module SolidQueue
+    # Base job for the plugin's bulk jobs actions (retry/discard/destroy), routed to their
+    # own dedicated worker queue so a large bulk action can't starve other application jobs.
+    # The `tramway:install` generator configures this queue with 20 worker threads.
+    class ApplicationJob < ActiveJob::Base
+      BATCH_SIZE = 1000
+
+      queue_as :tramway_solid_queue_bulk_actions
+    end
+  end
+end

data/app/jobs/tramway/solid_queue/bulk_destroy_job.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Tramway
+  module SolidQueue
+    # Destroys the given jobs, in batches so a large selection doesn't load/destroy
+    # everything in a single pass.
+    class BulkDestroyJob < ApplicationJob
+      def perform(job_ids)
+        ::SolidQueue::Job.where(id: job_ids).in_batches(of: BATCH_SIZE, &:destroy_all)
+      end
+    end
+  end
+end

data/app/jobs/tramway/solid_queue/bulk_discard_job.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Tramway
+  module SolidQueue
+    # Discards the given jobs, in batches so a large selection doesn't load everything
+    # in a single pass. `discard` is a per-record SolidQueue operation, not a bulk SQL one.
+    class BulkDiscardJob < ApplicationJob
+      def perform(job_ids)
+        ::SolidQueue::Job.where(id: job_ids).find_each(batch_size: BATCH_SIZE, &:discard)
+      end
+    end
+  end
+end

data/app/jobs/tramway/solid_queue/bulk_retry_job.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Tramway
+  module SolidQueue
+    # Retries the given jobs, in batches so a large selection doesn't load everything
+    # in a single pass. `retry` is a per-record SolidQueue operation, not a bulk SQL one.
+    class BulkRetryJob < ApplicationJob
+      def perform(job_ids)
+        ::SolidQueue::Job.where(id: job_ids).find_each(batch_size: BATCH_SIZE, &:retry)
+      end
+    end
+  end
+end

data/app/jobs/tramway/solid_queue/destroy_all_job.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Tramway
+  module SolidQueue
+    # Destroys every job matching the given filters, in batches so a large match set
+    # doesn't load/destroy everything in a single pass.
+    class DestroyAllJob < ApplicationJob
+      def perform(filters = {})
+        Tramway::SolidQueue::JobsFilter.new(filters).jobs.in_batches(of: BATCH_SIZE, &:destroy_all)
+      end
+    end
+  end
+end