plutonium 0.67.0 → 0.69.0

data/lib/plutonium/dashboard/controller.rb

@@ -31,6 +31,7 @@ module Plutonium
       # GET the mount — the full page.
       def show
         authorize_dashboard!
+        ensure_filters_clear_of_path_params!
         set_page_title(current_dashboard_class.label)
         render Plutonium::UI::Page::Dashboard.new(dashboard: current_dashboard)
       end
@@ -38,6 +39,7 @@ module Plutonium
       # GET <mount>/cards/:card — one card, wrapped in its turbo frame.
       def card
         authorize_dashboard!
+        ensure_filters_clear_of_path_params!
         card = current_dashboard.visible_card!(params[:card])
         render Plutonium::UI::Dashboard::Frame.new(dashboard: current_dashboard, card:)
       end
@@ -77,24 +79,40 @@ module Plutonium
         )
       end
 
+      # A path segment of the mount (the tenant on a path-scoped portal, a
+      # `(:locale)` scope) belongs to the route, so it cannot be refused when
+      # the filter is declared. A filter under that key would read the
+      # segment's value and overwrite it on every card's frame URL. The card
+      # route's own segments count even when optional and absent from this
+      # request, since its URL helper would fill them.
+      def ensure_filters_clear_of_path_params!
+        segments = (request.path_parameters.keys.map(&:to_sym) | dashboard_card_route.parts) - %i[controller action]
+        collision = current_dashboard_class.filters.map(&:key) & segments
+        return if collision.empty?
+
+        raise ArgumentError,
+          "#{current_dashboard_class.name} filter #{collision.first.inspect} collides with a path segment of the dashboard's route, pick another name"
+      end
+
       # The card endpoint's path, threading the entity scope segment through so
-      # the frame stays inside the tenant. Resolved by the route's
-      # `dashboard_class` default, so `at:` / `as:` and a scope prefix are honoured.
+      # the frame stays inside the tenant, and the dashboard's filter values
+      # through as query parameters so the card reads what the page read.
+      # Resolved by the route's `dashboard_class` default, so `at:` / `as:` and
+      # a scope prefix are honoured.
       def dashboard_card_path(card)
-        options = {card: card.key}
+        options = current_dashboard.filter_values.merge(card: card.key)
         options[scoped_entity_param_key] = params[scoped_entity_param_key] if scoped_to_entity?
         current_engine.routes.url_helpers.public_send(dashboard_card_route_helper, **options)
       end
 
       def dashboard_card_route_helper
-        @dashboard_card_route_helper ||= begin
-          name = Plutonium::Dashboard::RouteResolution.route_name(
-            current_engine.routes, current_dashboard_class, action: "card"
-          )
-          raise "no register_dashboard route found for #{current_dashboard_class.name}" unless name
+        :"#{dashboard_card_route.name}_path"
+      end
 
-          :"#{name}_path"
-        end
+      def dashboard_card_route
+        @dashboard_card_route ||=
+          Plutonium::Dashboard::RouteResolution.route(current_engine.routes, current_dashboard_class, action: "card") ||
+          raise("no register_dashboard route found for #{current_dashboard_class.name}")
       end
     end
   end

data/lib/plutonium/dashboard/dsl.rb

@@ -2,8 +2,8 @@
 
 module Plutonium
   module Dashboard
-    # The author-facing class macros: `metric`, `chart`, `card`, `refresh`
-    # and `width`. Mixed into {Base}.
+    # The author-facing class macros: `metric`, `chart`, `card`, `filter`,
+    # `link`, `refresh` and `width`. Mixed into {Base}.
     module DSL
       extend ActiveSupport::Concern
 
@@ -47,6 +47,61 @@ module Plutonium
           add_card(key, kind: :custom, options:, block:)
         end
 
+        # The declared filters, in declaration order.
+        def filters
+          @filters ||= []
+        end
+
+        # The declared toolbar links, in declaration order.
+        def links
+          @links ||= []
+        end
+
+        # A page-level control every card reads, such as a period or a region.
+        # The chosen value comes from the query string, is carried onto every
+        # lazy card's frame URL so each card sees what the page saw, and is
+        # read in a card block with `filter_value(key)`. The page renders the
+        # filters as a segmented control above the cards.
+        #
+        #   filter :period, choices: {"7" => "Last 7 days", "30" => "Last 30 days"}, default: "30"
+        #   metric(:orders) { orders.where(created_at: filter_value(:period).to_i.days.ago..).count }
+        #
+        # `scopes:` takes a resource instead of choices: "All" plus the scopes
+        # its definition declares. `filtered(Post)` then counts what the index
+        # would list, and `filtered_url(Post)` opens that list.
+        #
+        #   filter :status, scopes: Post
+        #   metric(:posts, href: -> { filtered_url(Post) }) { filtered(Post).count }
+        def filter(key, choices: nil, scopes: nil, default: nil, label: nil)
+          key = key.to_sym
+          raise ArgumentError, "#{name || "dashboard"} already declares a filter #{key.inspect}" if find_filter(key)
+          if scopes && filters.any? { |filter| filter.resource_class == scopes }
+            raise ArgumentError, "#{name || "dashboard"} already declares a scope filter for #{scopes}"
+          end
+
+          filters << Filter.new(key, choices:, scopes:, default:, label:)
+          filters.last
+        end
+
+        # A link in the toolbar above the cards, such as the dashboard's
+        # settings or a full report. `href:` and `condition:` are evaluated on
+        # the dashboard instance, like a card's.
+        #
+        #   link :settings, href: -> { resource_url_for(Setting) }, icon: Phlex::TablerIcons::Settings
+        def link(key, href:, label: nil, icon: nil, condition: nil)
+          key = key.to_sym
+          raise ArgumentError, "#{name || "dashboard"} already declares a link #{key.inspect}" if links.any? { |link| link.key == key }
+
+          links << Link.new(key, href:, label:, icon:, condition:)
+          links.last
+        end
+
+        # @return [Filter, nil]
+        def find_filter(key)
+          key = key.to_sym
+          filters.find { |filter| filter.key == key }
+        end
+
         # Default refresh interval (seconds) for every lazy card. A card's own
         # `refresh:` overrides it; `refresh: false` on a card opts out.
         def refresh(seconds = UNSET)
@@ -95,6 +150,8 @@ module Plutonium
         def inherited(subclass)
           super
           subclass.instance_variable_set(:@cards, cards.dup)
+          subclass.instance_variable_set(:@filters, filters.dup)
+          subclass.instance_variable_set(:@links, links.dup)
           subclass.instance_variable_set(:@refresh, @refresh)
           subclass.instance_variable_set(:@width, @width)
         end

data/lib/plutonium/dashboard/evaluation.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Dashboard
+    # How a card or toolbar link runs its author-supplied procs and
+    # `condition:` against the dashboard instance, so both accept the same
+    # forms.
+    module Evaluation
+      private
+
+      # A zero-arity proc runs on the dashboard instance; a proc taking an
+      # argument also receives the dashboard.
+      def evaluate_on(dashboard, callable)
+        callable.arity.zero? ? dashboard.instance_exec(&callable) : dashboard.instance_exec(dashboard, &callable)
+      end
+
+      # `condition:` is nil (always), a proc (see {#evaluate_on}), a symbol
+      # naming a dashboard method, or a plain value.
+      def condition_passes?(dashboard, condition)
+        result = case condition
+        when nil then true
+        when Symbol then dashboard.send(condition)
+        when Proc then evaluate_on(dashboard, condition)
+        else condition
+        end
+        result ? true : false
+      end
+    end
+  end
+end

data/lib/plutonium/dashboard/filter.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Dashboard
+    # A page-level control every card reads, declared with `filter`. Its value
+    # comes from the request's query string under the filter's key, and a value
+    # that is not one of the choices reads as the default, so a hand-edited URL
+    # can never reach a card block.
+    #
+    # The choices are either given (`choices:`) or are a resource's scopes
+    # (`scopes: Post`): "All" plus every scope the resource's definition
+    # declares, labelled and gated the way the index's scope pills are.
+    class Filter
+      # Keys a filter cannot take: the card route's own params and the options
+      # `url_for` reads, all of which the filter values are merged into when
+      # building each card's frame URL. A key that is a path segment of the
+      # mount (an entity scope, a `(:locale)` scope) is refused per request,
+      # since only the route knows it.
+      RESERVED_KEYS = %i[
+        card dashboard_class controller action format anchor params path_params
+        host protocol port subdomain domain tld_length user password
+        script_name original_script_name only_path trailing_slash
+        use_route _recall
+      ].freeze
+
+      # The value of a scope filter's "All" choice.
+      ALL = "all"
+
+      attr_reader :key, :resource_class
+
+      # @param choices [Hash{#to_s => String, Proc}, nil] value => label, in display order
+      # @param scopes [Class, nil] a resource whose definition's scopes are the choices
+      # @param default [#to_s, nil] one of the choices; the first (or, for
+      #   scopes, the definition's `default_scope`, else "All") when nil
+      def initialize(key, choices: nil, scopes: nil, default: nil, label: nil)
+        @key = key.to_sym
+        if RESERVED_KEYS.include?(@key)
+          raise ArgumentError, "filter #{@key.inspect}: the name is reserved by the card route, pick another"
+        end
+        unless choices.nil? ^ scopes.nil?
+          raise ArgumentError, "filter #{@key.inspect}: pass exactly one of choices: or scopes:"
+        end
+
+        @label = label
+        @default = default&.to_s
+
+        if scopes
+          raise ArgumentError, "filter #{@key.inspect}: scopes: takes a resource class, got #{scopes.inspect}" unless scopes.is_a?(Class)
+
+          @resource_class = scopes
+        else
+          @choices = choices.to_h.transform_keys(&:to_s).freeze
+          raise ArgumentError, "filter #{@key.inspect}: choices must not be empty" if @choices.empty?
+
+          @default ||= @choices.keys.first
+          validate_default!
+        end
+      end
+
+      def scopes? = !@resource_class.nil?
+
+      # The control's accessible name.
+      def label
+        Plutonium::Translation.resolve(@label) || key.to_s.humanize
+      end
+
+      # value => label for this request. Labels may be lazy `t` procs. Read it
+      # through {Base#filter_choices}, which builds it once per request.
+      def choices_for(dashboard)
+        scopes? ? scope_choices(dashboard) : @choices
+      end
+
+      # An explicit `default:` must be one of the definition's scopes. A
+      # default (explicit or the definition's `default_scope`) whose
+      # `condition:` hides it from this user reads as "All", as does a
+      # `default_scope` the definition never declares as a scope.
+      def default_for(dashboard)
+        return @default unless scopes?
+
+        if @default && !dashboard.scope_query_for(resource_class).scope_definitions.key?(@default)
+          raise ArgumentError, "filter #{key.inspect}: default #{@default.inspect} is not a scope of #{resource_class}'s definition"
+        end
+
+        default = @default || dashboard.resource_definition_for(resource_class).default_scope&.to_s
+        dashboard.filter_choices(self).key?(default) ? default : ALL
+      end
+
+      # The chosen value for this request.
+      def value_from(dashboard)
+        value = dashboard.params[key].to_s
+        dashboard.filter_choices(self).key?(value) ? value : default_for(dashboard)
+      end
+
+      private
+
+      def scope_choices(dashboard)
+        query = dashboard.scope_query_for(resource_class)
+        if query.scope_definitions.key?(ALL)
+          raise ArgumentError, "filter #{key.inspect}: #{resource_class}'s definition declares a scope named :#{ALL}, which is the filter's \"All\" choice"
+        end
+
+        visible = query.scope_definitions.keys.select { |name| query.scope_visible?(name, dashboard.view_context) }
+        {ALL => -> { Plutonium::Translation.t("plutonium.ui.table.all") }}
+          .merge(visible.to_h { |name| [name, query.scope_label(name)] })
+      end
+
+      def validate_default!
+        return if @choices.key?(@default)
+
+        raise ArgumentError, "filter #{key.inspect}: default #{@default.inspect} is not one of #{@choices.keys.inspect}"
+      end
+    end
+  end
+end

data/lib/plutonium/dashboard/link.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Dashboard
+    # A link in the dashboard's toolbar, declared with `link`: the way to a
+    # related page such as the dashboard's settings or a full report.
+    class Link
+      include Evaluation
+
+      attr_reader :key, :icon
+
+      def initialize(key, href:, label: nil, icon: nil, condition: nil)
+        @key = key.to_sym
+        @href = href
+        @label = label
+        @icon = icon
+        @condition = condition
+      end
+
+      def label
+        Plutonium::Translation.resolve(@label) || key.to_s.humanize
+      end
+
+      # Evaluated like a card's `href:`.
+      def href_for(dashboard)
+        @href.is_a?(Proc) ? evaluate_on(dashboard, @href) : @href
+      end
+
+      # Evaluated like a card's `condition:`.
+      def visible?(dashboard)
+        condition_passes?(dashboard, @condition)
+      end
+    end
+  end
+end

data/lib/plutonium/dashboard/route_resolution.rb

@@ -17,13 +17,17 @@ module Plutonium
       # @param action [String, Symbol] "show" or "card"
       # @return [Symbol, nil] the route name (e.g. :sales_dashboard_card)
       def route_name(route_set, dashboard_class, action:)
-        route = route_set.routes.find do |r|
+        route(route_set, dashboard_class, action:)&.name&.to_sym
+      end
+
+      # @return [ActionDispatch::Journey::Route, nil] the named route itself
+      def route(route_set, dashboard_class, action:)
+        route_set.routes.find do |r|
           d = r.defaults
           r.name.present? &&
             d[:action].to_s == action.to_s &&
             d[:dashboard_class].to_s == dashboard_class.name
         end
-        route&.name&.to_sym
       end
     end
   end

data/lib/plutonium/definition/presentable.rb

@@ -36,8 +36,11 @@ module Plutonium
         # Returns the label for the interaction.
         #
         # @return [String] The label defined in the presentation metadata or a default generated from the class name.
+        #   The conventional "Interaction" suffix is dropped: ImportPostsInteraction reads "Import Posts".
+        #   Only a suffix: a class named just Interaction keeps its name rather than going blank.
         def label
-          Plutonium::Translation.resolve(presentation_metadata[:label]) || name.demodulize.titleize
+          Plutonium::Translation.resolve(presentation_metadata[:label]) ||
+            name.demodulize.sub(/(?<=.)Interaction\z/, "").titleize
         end
 
         # Returns the icon for the interaction.

data/lib/plutonium/interaction/async/configuration.rb

@@ -27,10 +27,25 @@ module Plutonium
         #   This is the knob for which backend does that, for runs alone.
         attr_accessor :attachment_backend
 
+        # @return [Integer] how many pre_check rejections a run stores. The rest
+        #   are counted and reported as one "and N more" entry, so a file that is
+        #   bad on every row cannot write tens of thousands of entries into the
+        #   errors_log column (and onto the progress page). Must be a positive Integer.
+        attr_accessor :max_rejections
+
+        # @return [ActiveSupport::Duration] how long a run stays in the running
+        #   banner after it finishes, for the user who started it. A dispatch
+        #   sends that user back to the index, and a short run (or one its
+        #   pre_check rejected) settles before the page loads; without this it
+        #   would never show there at all.
+        attr_accessor :recent_runs_window
+
         def initialize
           @enabled = false
           @queue = :default
           @stall_after = 1.hour
+          @max_rejections = 100
+          @recent_runs_window = 10.minutes
         end
       end
     end

data/lib/plutonium/interaction/async/context.rb

@@ -225,9 +225,14 @@ module Plutonium
         #
         # @return [Targets]
         def targets
+          unless run.targeted?
+            raise UnresolvableError,
+              "run #{run.id} (#{run.class}) is not a targeted run; it has no targets to resolve"
+          end
+
           unless run.target_type
             raise UnresolvableError,
-              "run #{run.id} (#{run.class}) has no target_type; it is not a targeted run"
+              "run #{run.id} (#{run.class}) has no target_type; it cannot resolve its targets"
           end
 
           key = target_class.primary_key
@@ -380,8 +385,13 @@ module Plutonium
         #
         # Only meaningful for a targeted run — untargeted work has no target
         # resource and therefore no policy to pin.
+        #
+        # Keyed on Run#targeted?, not on target_type: an opaque run dispatched
+        # from a resource still records target_type (it is what puts the run in
+        # that resource's banner), but it resolves no targets, so it pins no
+        # policy and there is nothing here to verify.
         def verify_policy!
-          return if run.target_type.nil?
+          return unless run.targeted? && run.target_type
 
           # A targeted run with no recorded policy is not "unasserted", it is
           # unverifiable: there is nothing to compare today's lookup against, and

data/lib/plutonium/interaction/async/executor.rb

@@ -190,6 +190,8 @@ module Plutonium
         # the framework is meant to call, and it must not change what the
         # executor does with it.
         def perform_opaque
+          return unless pre_check_passed?
+
           run.send(:perform)
           run.finish!
         end
@@ -200,6 +202,17 @@ module Plutonium
 
           return refuse_partial_batch(resolved) if unresolved?(resolved) && !continue?
 
+          # A resumed run whose earlier pass already applied a target was
+          # approved by that pass's check: targets are only performed after it
+          # passes. Re-checking the remainder could reject a run that is
+          # half-applied and report "nothing was processed". Opaque runs restart
+          # from scratch, so they re-check.
+          #
+          # After record_unresolved, so a rejected :continue run still reports
+          # the targets that had gone; those count toward progress_done, though
+          # nothing was performed.
+          return unless run.any_target_applied? || pre_check_passed?(resolved.records)
+
           if transactional?
             perform_all_or_nothing(resolved.records)
             run.finish!
@@ -217,6 +230,47 @@ module Plutonium
           end
         end
 
+        # Runs the run's pre_check with #reject live, and fails the run with
+        # whatever it rejected. Before any work: a rejected run touches no
+        # target. Outside the :transactional batch, which never opens for a
+        # rejected run.
+        #
+        # An exception from the check is NOT a rejection. It propagates to #call
+        # and fails the run the ordinary way, so "your input is wrong" and "the
+        # check itself broke" stay distinguishable (Run#outcome).
+        #
+        # send, for the reason #perform_opaque gives.
+        #
+        # @return [Boolean] whether the work may go ahead
+        def pre_check_passed?(*args)
+          verify_pre_check_arity!(args.size)
+
+          messages, overflow = run.collect_rejections { run.send(:pre_check, *args) }
+          return true if messages.empty? && overflow.zero?
+
+          run.reject_run!(messages, overflow: overflow)
+          false
+        end
+
+        # A targeted check declared opaque-style (or the reverse) would raise a
+        # bare "wrong number of arguments" from inside the executor, naming
+        # neither the class nor the fix.
+        #
+        # Raised as NotImplementedError ("the run class is written wrong"), which
+        # #call records like any other failure.
+        def verify_pre_check_arity!(given)
+          params = run.method(:pre_check).parameters.group_by(&:first)
+          required = params.fetch(:req, []).size
+          positional = required + params.fetch(:opt, []).size
+          fits = params[:keyreq].nil? && required <= given && (params.key?(:rest) || positional >= given)
+          return if fits
+
+          raise NotImplementedError, I18n.t(
+            "plutonium.async.executor.pre_check_arity.#{run.targeted? ? "targeted" : "opaque"}",
+            run_class: run.class
+          )
+        end
+
         # @return [Integer, nil] how many records were never attempted, if the
         #   failure policy stopped the loop early — nil if it ran to the end
         def perform_each(records)