tramway 4.0.2 → 4.1

data/app/views/tramway/plugins/solid_queue/jobs/show.html.haml

@@ -0,0 +1,90 @@
+= tramway_container do
+  .flex.justify-between.items-center
+    = tramway_title do
+      = "#{@job.class_name} ##{@job.id}"
+
+  #tramway-solid-queue-job-details{ data: { controller: 'tramway--auto-refresh',
+    'tramway--auto-refresh-target': 'refreshable' } }
+    = component 'tramway/actions_buttons_container' do
+      = tramway_button tag: :a, text: t('tramway.actions.cancel'), path: jobs_path, type: :inverse
+
+      - if @job.status == :failed
+        = tramway_button text: t('tramway.actions.retry'), path: retry_job_path(@job.id), method: :post,
+          type: :will
+
+      - if @job.status != :finished
+        = tramway_button text: t('tramway.actions.discard'), path: discard_job_path(@job.id), method: :post,
+          type: :warning
+
+      = tramway_button text: t('tramway.actions.destroy'), path: job_path(@job.id), method: :delete, type: :rage
+
+    = tramway_table class: 'mt-4' do
+      = tramway_row do
+        = tramway_cell do
+          = t('tramway.plugins.solid_queue.jobs.status', default: 'Status')
+        = tramway_cell do
+          = tramway_badge text: solid_queue_status_label(@job.status),
+            type: solid_queue_status_badge_type(@job.status)
+
+      = tramway_row do
+        = tramway_cell do
+          = t('tramway.plugins.solid_queue.jobs.queue_name', default: 'Queue')
+        = tramway_cell do
+          = @job.queue_name
+
+      = tramway_row do
+        = tramway_cell do
+          = t('tramway.plugins.solid_queue.jobs.active_job_id', default: 'Active Job ID')
+        = tramway_cell do
+          = @job.active_job_id
+
+      = tramway_row do
+        = tramway_cell do
+          = t('tramway.plugins.solid_queue.jobs.priority', default: 'Priority')
+        = tramway_cell do
+          = @job.priority
+
+      = tramway_row do
+        = tramway_cell do
+          = t('tramway.plugins.solid_queue.jobs.concurrency_key', default: 'Concurrency key')
+        = tramway_cell do
+          = @job.concurrency_key
+
+      = tramway_row do
+        = tramway_cell do
+          = t('tramway.plugins.solid_queue.jobs.scheduled_at', default: 'Scheduled at')
+        = tramway_cell do
+          = @job.scheduled_at
+
+      = tramway_row do
+        = tramway_cell do
+          = t('tramway.plugins.solid_queue.jobs.finished_at', default: 'Finished at')
+        = tramway_cell do
+          = @job.finished_at
+
+      = tramway_row do
+        = tramway_cell do
+          = t('tramway.plugins.solid_queue.jobs.arguments', default: 'Arguments')
+        = tramway_cell do
+          = @job.arguments.inspect
+
+    - if @job.status == :failed
+      .mt-8
+        %h3.text-2xl.font-bold.text-white
+          = t('tramway.plugins.solid_queue.jobs.error', default: 'Error')
+
+        = tramway_table class: 'mt-4' do
+          = tramway_row do
+            = tramway_cell do
+              = t('tramway.plugins.solid_queue.jobs.exception_class', default: 'Exception class')
+            = tramway_cell do
+              = @job.failed_execution.exception_class
+
+          = tramway_row do
+            = tramway_cell do
+              = t('tramway.plugins.solid_queue.jobs.message', default: 'Message')
+            = tramway_cell do
+              = @job.failed_execution.message
+
+        %pre.mt-4.overflow-x-auto.text-sm.text-zinc-400
+          = Array(@job.failed_execution.backtrace).join("\n")

data/app/views/tramway/plugins/solid_queue/queues/index.html.haml

@@ -0,0 +1,46 @@
+- content_for :title, t('tramway.plugins.solid_queue.queues.title', default: 'Queues')
+
+= tramway_container do
+  .flex.justify-between.items-center
+    = tramway_title do
+      = content_for :title
+
+  = render 'tramway/plugins/solid_queue/subnav'
+
+  %div#tramway-solid-queue-queues-table{ data: { controller: 'tramway--auto-refresh',
+    'tramway--auto-refresh-target': 'refreshable' } }
+    = tramway_table class: 'mt-4' do
+      = tramway_header headers: [t('tramway.plugins.solid_queue.queues.name', default: 'Name'),
+        t('tramway.plugins.solid_queue.queues.size', default: 'Size'),
+        t('tramway.plugins.solid_queue.queues.running', default: 'Running'),
+        t('tramway.plugins.solid_queue.queues.latency', default: 'Latency'),
+        t('tramway.plugins.solid_queue.queues.throughput', default: 'Throughput'),
+        t('tramway.plugins.solid_queue.queues.status', default: 'Status'),
+        t('tramway.table.actions_header')]
+      - @queues.each do |queue|
+        = tramway_row do
+          = tramway_cell do
+            = queue.name
+          = tramway_cell do
+            = queue.size
+          = tramway_cell do
+            = solid_queue_running_count(queue)
+          = tramway_cell do
+            = queue.human_latency
+          = tramway_cell do
+            = solid_queue_throughput_label(queue)
+          = tramway_cell do
+            - if queue.paused?
+              = tramway_badge text: t('tramway.plugins.solid_queue.queues.paused', default: 'Paused'), type: :warning
+            - else
+              = tramway_badge text: t('tramway.plugins.solid_queue.queues.active', default: 'Active'), type: :will
+          = tramway_cell do
+            .flex.gap-2
+              - if queue.paused?
+                = tramway_button text: t('tramway.actions.resume'), path: resume_queue_path(queue.name),
+                  method: :post, type: :will, size: :small
+              - else
+                = tramway_button text: t('tramway.actions.pause'), path: pause_queue_path(queue.name),
+                  method: :post, type: :warning, size: :small
+              = tramway_button text: t('tramway.actions.clear'), path: clear_queue_path(queue.name),
+                method: :post, type: :rage, size: :small

data/app/views/tramway/plugins/solid_queue/recurring_tasks/index.html.haml

@@ -0,0 +1,33 @@
+- content_for :title, t('tramway.plugins.solid_queue.recurring_tasks.title', default: 'Recurring Tasks')
+
+= tramway_container do
+  .flex.justify-between.items-center
+    = tramway_title do
+      = content_for :title
+
+  = render 'tramway/plugins/solid_queue/subnav'
+
+  %div#tramway-solid-queue-recurring-tasks-table{ data: { controller: 'tramway--auto-refresh',
+    'tramway--auto-refresh-target': 'refreshable' } }
+    = tramway_table class: 'mt-4' do
+      = tramway_header headers: [t('tramway.plugins.solid_queue.recurring_tasks.key', default: 'Key'),
+        t('tramway.plugins.solid_queue.recurring_tasks.schedule', default: 'Schedule'),
+        t('tramway.plugins.solid_queue.recurring_tasks.class_name', default: 'Class'),
+        t('tramway.plugins.solid_queue.recurring_tasks.queue_name', default: 'Queue'),
+        t('tramway.plugins.solid_queue.recurring_tasks.next_time', default: 'Next run'),
+        t('tramway.table.actions_header')]
+      - @recurring_tasks.each do |task|
+        = tramway_row do
+          = tramway_cell do
+            = task.key
+          = tramway_cell do
+            = task.schedule
+          = tramway_cell do
+            = task.class_name
+          = tramway_cell do
+            = task.queue_name
+          = tramway_cell do
+            = task.next_time
+          = tramway_cell do
+            = tramway_button text: t('tramway.actions.enqueue_now'), path: enqueue_recurring_task_path(task.key),
+              method: :post, type: :will, size: :small

data/config/locales/en.yml

@@ -11,11 +11,18 @@ en:
       new: "New"
       edit: "Edit"
       destroy: "Destroy"
+      destroy_all: "Destroy all"
       save: "Save"
       cancel: "Cancel"
       search: "Search"
       filters: "Filters"
       clear_filter: "Clear filter"
+      retry: "Retry"
+      discard: "Discard"
+      pause: "Pause"
+      resume: "Resume"
+      clear: "Clear"
+      enqueue_now: "Run now"
     notices:
       created: "The record is created"
       updated: "The record is updated"
@@ -24,3 +31,58 @@ en:
       placeholders:
         waiting: "Waiting for an answer..."
         type: "Type your message..."
+    plugins:
+      solid_queue:
+        statuses:
+          ready: "Ready"
+          claimed: "Claimed"
+          scheduled: "Scheduled"
+          blocked: "Blocked"
+          failed: "Failed"
+          finished: "Finished"
+        notices:
+          destroyed: "The job is destroyed"
+          retried: "The job is scheduled to retry"
+          discarded: "The job is discarded"
+          paused: "The queue is paused"
+          resumed: "The queue is resumed"
+          cleared: "The queue is cleared"
+          enqueued: "The recurring task is enqueued"
+          bulk_retry_enqueued: "Retrying the selected jobs in the background"
+          bulk_discard_enqueued: "Discarding the selected jobs in the background"
+          bulk_destroy_enqueued: "Destroying the selected jobs in the background"
+          destroy_all_enqueued: "Destroying all matching jobs in the background"
+        jobs:
+          title: "Background Jobs"
+          class_name: "Class"
+          queue_name: "Queue"
+          status: "Status"
+          scheduled_at: "Scheduled at"
+          finished_at: "Finished at"
+          active_job_id: "Active Job ID"
+          priority: "Priority"
+          concurrency_key: "Concurrency key"
+          arguments: "Arguments"
+          error: "Error"
+          exception_class: "Exception class"
+          message: "Message"
+          all_queues: "All queues"
+          all_classes: "All classes"
+        queues:
+          title: "Queues"
+          name: "Name"
+          size: "Size"
+          running: "Running"
+          latency: "Latency"
+          throughput: "Throughput"
+          throughput_value: "%<rate>s/min"
+          status: "Status"
+          paused: "Paused"
+          active: "Active"
+        recurring_tasks:
+          title: "Recurring Tasks"
+          key: "Key"
+          schedule: "Schedule"
+          class_name: "Class"
+          queue_name: "Queue"
+          next_time: "Next run"

data/config/routes.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'tramway/helpers/routes_helper'
+require 'tramway/plugins'
 
 # rubocop:disable-next Metrics/BlockLength
 Tramway::Engine.routes.draw do
@@ -54,6 +55,15 @@ Tramway::Engine.routes.draw do
       nest.call(segments)
     end
   end
+
+  Tramway.config.plugins.each do |plugin_name|
+    plugin = Tramway::Plugins.fetch(plugin_name)
+    plugin_config = Tramway.config.plugins.public_send(plugin_name)
+
+    scope path: plugin_config.path do
+      plugin.draw_routes(self, plugin_config)
+    end
+  end
 end
 
 Tramway::Engine.routes.routes.map(&:name).compact.each do |route_name|

data/config/tailwind.config.js

@@ -282,6 +282,7 @@ module.exports = {
     // === Visibility and typography helpers ===
     'hidden',
     'text-xl',
+    'text-2xl',
     'font-bold',
     'prose',
     'prose-invert',

data/lib/generators/tramway/install/install_generator.rb

@@ -4,6 +4,7 @@ require 'rails/generators'
 require 'fileutils'
 require_relative 'font_awesome_helpers'
 require_relative 'layout_helpers'
+require_relative 'solid_queue_helpers'
 
 module Tramway
   module Generators
@@ -345,6 +346,7 @@ module Tramway
       include InstallGeneratorHelpers
       include InstallGeneratorFontAwesomeHelpers
       include InstallGeneratorLayoutHelpers
+      include InstallGeneratorSolidQueueHelpers
 
       desc 'Installs Tramway dependencies and Tailwind safelist configuration.'
 
@@ -442,6 +444,16 @@ module Tramway
       def ensure_navbar_sidebar_offset_in_application_layout
         ensure_navbar_sidebar_offset
       end
+
+      def ensure_solid_queue_bulk_actions_queue
+        return unless File.exist?(queue_yml_path)
+
+        content = File.read(queue_yml_path)
+        return if content.include?(TRAMWAY_SOLID_QUEUE_BULK_ACTIONS_QUEUE)
+
+        updated = insert_tramway_solid_queue_worker(content)
+        File.write(queue_yml_path, updated) if updated != content
+      end
     end
   end
 end

data/lib/generators/tramway/install/solid_queue_helpers.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Tramway
+  module Generators
+    # nodoc
+    module InstallGeneratorSolidQueueHelpers
+      TRAMWAY_SOLID_QUEUE_BULK_ACTIONS_QUEUE = 'tramway_solid_queue_bulk_actions'
+      TRAMWAY_SOLID_QUEUE_BULK_ACTIONS_CONCURRENCY = 20
+
+      private
+
+      def queue_yml_path
+        @queue_yml_path ||= File.join(destination_root, 'config/queue.yml')
+      end
+
+      def insert_tramway_solid_queue_worker(content)
+        insertion_index, item_indent = workers_list_insertion_point(content)
+        return content unless insertion_index
+
+        content.dup.insert(insertion_index, tramway_solid_queue_worker_entry(item_indent))
+      end
+
+      # Finds where the `workers:` YAML list ends, so a new worker entry can be appended
+      # right after the existing ones, matching their indentation. This is line-based
+      # (rather than a full YAML parse) so ERB tags, comments, and anchors/aliases already
+      # present in the host app's queue.yml are left untouched.
+      def workers_list_insertion_point(content)
+        lines = content.each_line.to_a
+        workers_line_index = lines.find_index { |line| line.match?(/^[ \t]*workers:[ \t]*\n?\z/) }
+        return [nil, nil] unless workers_line_index
+
+        item_indent = lines[workers_line_index + 1]&.[](/^[ \t]*(?=- )/)
+        return [nil, nil] unless item_indent
+
+        search_range = (workers_line_index + 1)...lines.length
+        end_index = search_range.find { |index| !lines[index].start_with?(item_indent) }
+        end_index ||= lines.length
+
+        [lines[0...end_index].join.length, item_indent]
+      end
+
+      def tramway_solid_queue_worker_entry(indentation)
+        sub_indentation = "#{indentation}  "
+
+        <<~YAML
+          #{indentation}- queues: #{TRAMWAY_SOLID_QUEUE_BULK_ACTIONS_QUEUE}
+          #{sub_indentation}threads: #{TRAMWAY_SOLID_QUEUE_BULK_ACTIONS_CONCURRENCY}
+          #{sub_indentation}processes: 1
+          #{sub_indentation}polling_interval: 1
+        YAML
+      end
+    end
+  end
+end

data/lib/tramway/config.rb

@@ -3,6 +3,7 @@
 require 'anyway'
 require 'singleton'
 require 'tramway/configs/entity'
+require 'tramway/configs/plugins'
 
 module Tramway
   # Basic configuration of Tramway
@@ -13,7 +14,8 @@ module Tramway
     attr_config(
       entities: [],
       application_controller: 'ActionController::Base',
-      theme: :classic
+      theme: :classic,
+      plugins: []
     )
 
     def entities=(collection)
@@ -23,5 +25,9 @@ module Tramway
         Tramway::Configs::Entity.new(**entity_options)
       end)
     end
+
+    def plugins=(names)
+      super(Tramway::Configs::Plugins.new(names))
+    end
   end
 end

data/lib/tramway/configs/plugins.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'tramway/plugins'
+
+module Tramway
+  module Configs
+    # Value object stored at `Tramway.config.plugins`. It behaves like an array of
+    # enabled plugin names (`config.plugins = [:solid_queue]`, `config.plugins.include?`,
+    # `config.plugins.each`) while also exposing per-plugin configuration as attributes
+    # (`config.plugins.solid_queue = { path: '/jobs' }`, `config.plugins.solid_queue`).
+    class Plugins
+      include Enumerable
+
+      def initialize(names = [])
+        @names = Array(names).map(&:to_sym)
+        @configs = {}
+      end
+
+      def each(&block)
+        return to_enum(:each) unless block
+
+        @names.each(&block)
+      end
+
+      def include?(name)
+        @names.include?(name.to_sym)
+      end
+      alias enabled? include?
+
+      def to_a
+        @names.dup
+      end
+
+      def method_missing(method_name, *args)
+        plugin_name = plugin_name_from(method_name)
+
+        return super unless plugin_name
+
+        assignment?(method_name) ? assign_plugin_config(plugin_name, args.first) : plugin_config(plugin_name)
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        plugin_name_from(method_name).present? || super
+      end
+
+      private
+
+      def plugin_name_from(method_name)
+        name = method_name.to_s.delete_suffix('=').to_sym
+        name if Tramway::Plugins.registered?(name)
+      end
+
+      def assignment?(method_name)
+        method_name.to_s.end_with?('=')
+      end
+
+      def plugin_config(name)
+        @configs[name] ||= Tramway::Plugins.fetch(name).config_class.new
+      end
+
+      def assign_plugin_config(name, options)
+        @configs[name] = Tramway::Plugins.fetch(name).config_class.new(**(options || {}).symbolize_keys)
+      end
+    end
+  end
+end

data/lib/tramway/errors.rb

@@ -61,5 +61,41 @@ module Tramway
         MESSAGE
       end
     end
+
+    # Raised when `Tramway.config.plugins` references a plugin name that was never registered
+    # via `Tramway::Plugins.register`, so the developer gets a clear explanation instead of a
+    # raw NoMethodError/KeyError deep inside the plugin config collection.
+    class UnknownPluginError < StandardError
+      def initialize(name:, available:)
+        super(<<~MESSAGE)
+          Tramway received an unknown plugin "#{name}".
+
+          Available plugins: #{available.any? ? available.join(', ') : '(none registered)'}.
+
+          To fix this:
+            - use one of the available plugins above in `Tramway.config.plugins`, or
+            - register a custom plugin via `Tramway::Plugins.register(YourPluginClass)` before \
+          referencing it in the config.
+        MESSAGE
+      end
+    end
+
+    # Raised when a Tramway plugin depends on a gem that is not installed in the host
+    # application, so the developer gets a precise, actionable fix instead of a raw
+    # LoadError/NameError deep inside the plugin's controllers.
+    class MissingPluginDependencyError < StandardError
+      def initialize(plugin:, gem_name:, original_error:)
+        super(<<~MESSAGE)
+          The Tramway "#{plugin}" plugin requires the `#{gem_name}` gem, but it could not be \
+          loaded (#{original_error.class}: #{original_error.message}).
+
+          To fix this:
+            - add `gem "#{gem_name}"` to your Gemfile and run `bundle install`, then restart \
+          your server, or
+            - remove `:#{plugin}` from `Tramway.config.plugins` if you do not want to use this \
+          plugin.
+        MESSAGE
+      end
+    end
   end
 end

data/lib/tramway/navbar.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'tramway/plugins'
+
 module Tramway
   # Navbar object provides left and right elements
   class Navbar
@@ -10,6 +12,8 @@ module Tramway
       @items = { left: [], right: [] }
       @filling = nil
 
+      preset_plugins
+
       return unless with_entities
 
       entities = Tramway.config.entities
@@ -61,6 +65,25 @@ module Tramway
       reset_filling
     end
 
+    def preset_plugins
+      plugins = Tramway.config.plugins
+
+      return unless plugins.any?
+
+      filling_side :left
+
+      plugins.each do |name|
+        plugin = Tramway::Plugins.fetch(name)
+        nav_item = plugin.nav_item(plugins.public_send(name))
+
+        next if nav_item.blank?
+
+        item nav_item[:text], nav_item[:path], icon: nav_item[:icon]
+      end
+
+      reset_filling
+    end
+
     def provided_url_and_block?(url)
       url.present? && block_given?
     end

data/lib/tramway/plugins/base.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Tramway
+  module Plugins
+    # Interface every Tramway plugin must implement to register itself with
+    # `Tramway::Plugins.register` and be referenced from `Tramway.config.plugins`.
+    class Base
+      class << self
+        def plugin_name
+          raise NotImplementedError, "#{self} must implement .plugin_name"
+        end
+
+        def config_class
+          raise NotImplementedError, "#{self} must implement .config_class"
+        end
+
+        def draw_routes(_mapper, _config)
+          raise NotImplementedError, "#{self} must implement .draw_routes"
+        end
+
+        # Returns a Hash with :text, :path and :icon keys used to render a navbar entry
+        # for this plugin, or nil to not render one.
+        def nav_item(_config)
+          nil
+        end
+
+        # Raises a clear, actionable error when the plugin's required infrastructure
+        # (typically a gem) is missing. No-op by default.
+        def ensure_available!; end
+      end
+    end
+  end
+end

data/lib/tramway/plugins/solid_queue/config.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Tramway
+  module Plugins
+    module SolidQueue
+      # Per-plugin configuration for the `:solid_queue` plugin, set via
+      # `Tramway.config.plugins.solid_queue = { path: '/jobs' }`.
+      class Config < Dry::Struct
+        attribute? :path, Types::Coercible::String.default('/jobs')
+      end
+    end
+  end
+end

data/lib/tramway/plugins/solid_queue/plugin.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Tramway
+  module Plugins
+    module SolidQueue
+      # Registry entry for the `:solid_queue` plugin — a Tramway-based dashboard for
+      # SolidQueue jobs, queues and recurring tasks.
+      class Plugin < Tramway::Plugins::Base
+        class << self
+          def plugin_name
+            :solid_queue
+          end
+
+          def config_class
+            Tramway::Plugins::SolidQueue::Config
+          end
+
+          def draw_routes(mapper, config)
+            Tramway::Plugins::SolidQueue::Routes.draw(mapper, config)
+          end
+
+          def nav_item(config)
+            { text: 'Background Jobs', path: config.path, icon: 'fa-tasks' }
+          end
+
+          def ensure_available!
+            require 'solid_queue'
+          rescue LoadError => e
+            raise Tramway::Errors::MissingPluginDependencyError.new(
+              plugin: plugin_name, gem_name: 'solid_queue', original_error: e
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tramway/plugins/solid_queue/routes.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Tramway
+  module Plugins
+    module SolidQueue
+      # Draws the routes for the solid_queue dashboard plugin, mounted at the
+      # plugin's configured `path` (defaults to `/jobs`).
+      module Routes
+        module_function
+
+        def draw(mapper, _config)
+          draw_queues(mapper)
+          draw_recurring_tasks(mapper)
+          draw_jobs(mapper)
+        end
+
+        def draw_queues(mapper)
+          mapper.instance_exec do
+            resources :queues, only: %i[index], param: :name, module: 'plugins/solid_queue' do
+              post :pause, on: :member
+              post :resume, on: :member
+              post :clear, on: :member
+            end
+          end
+        end
+
+        def draw_recurring_tasks(mapper)
+          mapper.instance_exec do
+            resources :recurring_tasks, only: %i[index], param: :key, module: 'plugins/solid_queue' do
+              post :enqueue, on: :member
+            end
+          end
+        end
+
+        def draw_jobs(mapper)
+          mapper.instance_exec do
+            resources :jobs, path: '', only: %i[index show destroy], module: 'plugins/solid_queue' do
+              post :retry, on: :member
+              post :discard, on: :member
+              post :bulk_retry, on: :collection
+              post :bulk_discard, on: :collection
+              post :bulk_destroy, on: :collection
+              post :destroy_all, on: :collection
+            end
+          end
+        end
+      end
+    end
+  end
+end