tramway 4.0.1.4 → 4.1

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

@@ -41,5 +41,61 @@ module Tramway
         MESSAGE
       end
     end
+
+    # Raised when `params[:filter]` on an entities#index page does not match any of the
+    # filters declared for that page in the Tramway config, so the developer (or the user
+    # following a crafted link) gets a clear explanation instead of a raw NoMethodError from
+    # calling an arbitrary, possibly non-existent scope.
+    class InvalidFilterError < StandardError
+      def initialize(filter:, available_filters:, model_class:)
+        super(<<~MESSAGE)
+          Tramway received an unknown filter "#{filter}" for #{model_class} on the \
+          entities#index page.
+
+          Available filters: #{available_filters.join(', ')}.
+
+          To fix this:
+            - pass one of the available filters above in `params[:filter]`, or
+            - add `:#{filter}` to this entity's `filters:` list for the `:index` page in your \
+          Tramway config if it should be selectable.
+        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

data/lib/tramway/plugins/solid_queue.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require 'tramway/plugins/solid_queue/config'
+require 'tramway/plugins/solid_queue/routes'
+require 'tramway/plugins/solid_queue/plugin'
+
+Tramway::Plugins.register(Tramway::Plugins::SolidQueue::Plugin)

data/lib/tramway/plugins.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'tramway/errors'
+require 'tramway/plugins/base'
+
+module Tramway
+  # Registry for Tramway plugins. A plugin is a class implementing the
+  # `Tramway::Plugins::Base` interface, registered via `Tramway::Plugins.register`,
+  # and referenced by name from `Tramway.config.plugins`.
+  module Plugins
+    module_function
+
+    def registry
+      @registry ||= {}
+    end
+
+    def register(plugin_class)
+      registry[plugin_class.plugin_name.to_sym] = plugin_class
+    end
+
+    def registered?(name)
+      registry.key?(name.to_sym)
+    end
+
+    def fetch(name)
+      registry.fetch(name.to_sym) do
+        raise Tramway::Errors::UnknownPluginError.new(name:, available: registry.keys)
+      end
+    end
+
+    def each(&)
+      registry.each(&)
+    end
+  end
+end
+
+require 'tramway/plugins/solid_queue'

data/lib/tramway/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tramway
-  VERSION = '4.0.1.4'
+  VERSION = '4.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tramway
 version: !ruby/object:Gem::Version
-  version: 4.0.1.4
+  version: '4.1'
 platform: ruby
 authors:
 - kalashnikovisme
@@ -279,7 +279,19 @@ files:
 - app/components/tramway/tooltip_component.html.haml
 - app/components/tramway/tooltip_component.rb
 - app/controllers/tramway/entities_controller.rb
+- app/controllers/tramway/plugins/solid_queue/application_controller.rb
+- app/controllers/tramway/plugins/solid_queue/jobs_controller.rb
+- app/controllers/tramway/plugins/solid_queue/queues_controller.rb
+- app/controllers/tramway/plugins/solid_queue/recurring_tasks_controller.rb
 - app/helpers/tramway/application_helper.rb
+- app/helpers/tramway/plugins/solid_queue/jobs_helper.rb
+- app/helpers/tramway/plugins/solid_queue/queues_helper.rb
+- app/jobs/tramway/solid_queue/application_job.rb
+- app/jobs/tramway/solid_queue/bulk_destroy_job.rb
+- app/jobs/tramway/solid_queue/bulk_discard_job.rb
+- app/jobs/tramway/solid_queue/bulk_retry_job.rb
+- app/jobs/tramway/solid_queue/destroy_all_job.rb
+- app/models/tramway/solid_queue/jobs_filter.rb
 - app/views/kaminari/_first_page.html.haml
 - app/views/kaminari/_gap.html.haml
 - app/views/kaminari/_last_page.html.haml
@@ -289,6 +301,7 @@ files:
 - app/views/kaminari/_prev_page.html.haml
 - app/views/tramway/chats/_message.html.haml
 - app/views/tramway/chats/_messages.html.haml
+- app/views/tramway/entities/_filters.html.haml
 - app/views/tramway/entities/_form.html.haml
 - app/views/tramway/entities/_list.html.haml
 - app/views/tramway/entities/edit.html.haml
@@ -296,6 +309,11 @@ files:
 - app/views/tramway/entities/new.html.haml
 - app/views/tramway/entities/show.html.haml
 - app/views/tramway/layouts/application.html.haml
+- app/views/tramway/plugins/solid_queue/_subnav.html.haml
+- app/views/tramway/plugins/solid_queue/jobs/index.html.haml
+- app/views/tramway/plugins/solid_queue/jobs/show.html.haml
+- app/views/tramway/plugins/solid_queue/queues/index.html.haml
+- app/views/tramway/plugins/solid_queue/recurring_tasks/index.html.haml
 - config/locales/en.yml
 - config/routes.rb
 - config/tailwind.config.js
@@ -303,6 +321,7 @@ files:
 - lib/generators/tramway/install/font_awesome_helpers.rb
 - lib/generators/tramway/install/install_generator.rb
 - lib/generators/tramway/install/layout_helpers.rb
+- lib/generators/tramway/install/solid_queue_helpers.rb
 - lib/kaminari/helpers/tag.rb
 - lib/rules/turbo_html_attributes_rules.rb
 - lib/tasks/tramway_tasks.rake
@@ -314,6 +333,7 @@ files:
 - lib/tramway/configs/entities/page.rb
 - lib/tramway/configs/entities/route.rb
 - lib/tramway/configs/entity.rb
+- lib/tramway/configs/plugins.rb
 - lib/tramway/decorators/association.rb
 - lib/tramway/decorators/class_helper.rb
 - lib/tramway/decorators/collection_decorator.rb
@@ -337,6 +357,12 @@ files:
 - lib/tramway/helpers/views_helper.rb
 - lib/tramway/navbar.rb
 - lib/tramway/pg_searchable.rb
+- lib/tramway/plugins.rb
+- lib/tramway/plugins/base.rb
+- lib/tramway/plugins/solid_queue.rb
+- lib/tramway/plugins/solid_queue/config.rb
+- lib/tramway/plugins/solid_queue/plugin.rb
+- lib/tramway/plugins/solid_queue/routes.rb
 - lib/tramway/searchable.rb
 - lib/tramway/utils/field.rb
 - lib/tramway/utils/render.rb