rhino-rails 4.8.1 → 4.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c77838e9b0818c083a66439097840287fdfadcd94fe17f7e403b9a1c00e08322
-  data.tar.gz: 698536e45e86aed2abd48ba646c0ebc4e821511838c79db07e6525413ace80c5
+  metadata.gz: f33582b9aac75614096047f46227c443f63a31634c40cf8825a92d5fb064f583
+  data.tar.gz: 94f626caf29a1e66132524f649b8b4dd6f2aeb52c88b48eca5f20479af653316
 SHA512:
-  metadata.gz: 52ec8339ccd944fcb4b3c071bc4829acaf37c1d401abfce18bec28648eac3005d7ca18c407ad3784bc541dcd16cf3238144c8ebd7bbc58ada65b8537f64e0515
-  data.tar.gz: '096db647db3f380fe23621e6fc31496321e857a80ce22911bc2133a7877a7e607a49be3e60cb08f88594030c784b9b3a6d3e8f9415969ed0188bfb11569e3ffc'
+  metadata.gz: 27865b6bb3173908f8990a908f87aae8222f7237d691b83dd1fa2607fc1bb86eb88791a37a1b1de44db0d0f4e1d3b4a731ac4d89441775f2b77ce92f9d0ec2b8
+  data.tar.gz: 51bd6475c50215ff50bfede53d09bc627e86d19033cc45a5e4e7a3035dd6050430efc61a4b13b77c4d3461185edb519f093f9855f8cb50b98fdb35621a682aee

data/lib/rhino/argument_binder.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Rhino
+  # Binds the arguments a client sent in the bracket query form
+  # (<tt>?scope[name][param]=value</tt>, <tt>?attributes[name][param]=value</tt>)
+  # to the parameters a model declared, in declared order.
+  #
+  # The algorithm is shared by named scopes and computed attributes so the two
+  # features cannot drift. Everything that differs between them is passed in:
+  #
+  # * +subject+ is the noun used in every error message ("Scope",
+  #   "Computed attribute"), so each feature keeps its own wording;
+  # * +error_class+ is the exception raised, so each feature keeps its own
+  #   controller +rescue_from+;
+  # * +underscore_keys+ reproduces the scope binder's wire-name translation.
+  #   Computed attributes match parameter names verbatim, exactly as Laravel and
+  #   NestJS do, so they leave it off.
+  #
+  # Nothing here decides whether a name may be used: callers MUST run the
+  # declared-check and the policy-check BEFORE binding, so an argument error can
+  # only ever be seen for a name the caller was already allowed to use.
+  module ArgumentBinder
+    module_function
+
+    # Clean a declared parameter list: stringify the names, and drop any
+    # +optional+ entry that is not actually a declared parameter.
+    def normalize_params(params, optional = [])
+      params = Array(params).map(&:to_s)
+
+      { params: params, optional: Array(optional).map(&:to_s) & params }
+    end
+
+    # Bind the raw value a client sent for one name to positional arguments,
+    # in the order the model declared them.
+    #
+    # +raw+ is whatever the query string produced for the bracket key: nil or ""
+    # (no arguments), a scalar (the single parameter), or a hash of parameter
+    # name => value.
+    def bind(subject:, name:, spec:, raw:, error_class:, underscore_keys: false)
+      params = Array(spec[:params]).map(&:to_s)
+      optional = Array(spec[:optional]).map(&:to_s)
+
+      given = normalize_raw_arguments(
+        subject: subject, name: name, params: params, raw: raw,
+        error_class: error_class, underscore_keys: underscore_keys
+      )
+
+      given.each_key do |key|
+        unless params.include?(key)
+          raise error_class, "#{subject} '#{name}' does not accept parameter '#{key}'"
+        end
+      end
+
+      args = params.map do |param|
+        if given.key?(param)
+          coerce(given[param])
+        elsif optional.include?(param)
+          nil
+        else
+          raise error_class, "#{subject} '#{name}' requires parameter '#{param}'"
+        end
+      end
+
+      # Drop trailing nils so an omitted optional parameter falls back to the
+      # default in the callable's own signature.
+      #
+      # NOTE: `args.empty?` rather than `args.any?` — Array#any? without a block
+      # is false for [nil], so the old form skipped the drop entirely when EVERY
+      # argument was nil (an all-optional declaration with nothing sent), passing
+      # [nil] where Laravel and NestJS pass []. Every other case is unchanged.
+      args.pop until args.empty? || !args.last.nil?
+      args
+    end
+
+    # Turn the raw query-string value into a parameter name => value hash.
+    def normalize_raw_arguments(subject:, name:, params:, raw:, error_class:, underscore_keys: false)
+      # ?scope[archived]= (or a bare ?scope[archived]): no arguments. A name
+      # with required parameters still fails, in bind, naming them.
+      return {} if raw.nil? || raw == ""
+
+      raw = raw.to_unsafe_h if raw.respond_to?(:to_unsafe_h)
+
+      if raw.is_a?(Array)
+        # A positional list (scope[between][]=a) names nothing.
+        raise error_class, "#{subject} '#{name}' requires named parameters"
+      end
+
+      unless raw.is_a?(Hash)
+        raise error_class, "#{subject} '#{name}' does not accept arguments" if params.empty?
+
+        # A bare value binds to the single declared parameter. Two parameters can
+        # never be guessed at from one value.
+        if params.length > 1
+          raise error_class, "#{subject} '#{name}' requires named parameters"
+        end
+
+        return { params.first => raw }
+      end
+
+      raise error_class, "#{subject} '#{name}' does not accept arguments" if params.empty?
+
+      raw.each_with_object({}) do |(key, value), out|
+        unless value.is_a?(String) || value.is_a?(Numeric) || value.is_a?(TrueClass) ||
+               value.is_a?(FalseClass) || value.nil?
+          raise error_class, "#{subject} '#{name}' requires named parameters"
+        end
+
+        key = key.to_s
+        out[underscore_keys ? key.underscore : key] = value
+      end
+    end
+
+    # Query-string values always arrive as strings; hand callables real booleans
+    # so a check cannot be fooled by the string "false".
+    def coerce(value)
+      return value unless value.is_a?(String)
+
+      case value.downcase
+      when "true" then true
+      when "false" then false
+      else value
+      end
+    end
+  end
+end

data/lib/rhino/commands/export_postman_command.rb

@@ -175,15 +175,42 @@ module Rhino
           allowed_fields: model_class.try(:allowed_fields) || [],
           allowed_includes: model_class.try(:allowed_includes) || [],
           allowed_search: model_class.try(:allowed_search) || [],
-          # Computed attributes: names only (the callables never leave the server).
-          collection_computed_attributes: computed_names(model_class.try(:rhino_collection_computed_attributes)),
-          record_computed_attributes: computed_names(record_computed_declaration(model_class)),
+          # Computed attributes: names and parameter specs only — the callables
+          # never leave the server. The spec is what lets the collection show a
+          # parameterised attribute the way a client must actually send it.
+          collection_computed_attributes: computed_specs(model_class.try(:rhino_collection_computed_attributes)),
+          record_computed_attributes: computed_specs(record_computed_declaration(model_class)),
           default_sort: model_class.try(:default_sort_field)
         }
       end
 
-      def computed_names(declared)
-        declared.is_a?(Hash) ? declared.keys.map(&:to_s) : []
+      # name => { params:, optional: } — the same shape as a scope's spec, for
+      # the same reason.
+      def computed_specs(declared)
+        Rhino::ComputedAttributeSpec.normalize(declared).transform_values do |spec|
+          { params: spec[:params], optional: spec[:optional] }
+        end
+      end
+
+      # The query parameters that select one computed attribute, in whichever
+      # form its declaration requires: the plain list when it takes no
+      # parameters, the bracket form when it does.
+      def computed_attribute_query(key, attribute, spec)
+        params = Array(spec[:params])
+
+        return { key.to_sym => attribute } if params.empty?
+        return { "#{key}[#{attribute}]" => "example" } if params.size == 1
+
+        params.each_with_object({}) do |param, out|
+          out["#{key}[#{attribute}][#{param}]"] = "example"
+        end
+      end
+
+      # The attribute names that can be requested without arguments — the only
+      # ones a combined "give me everything" request may name, since a required
+      # parameter left out is a guaranteed 403.
+      def argument_free_computed_attributes(specs)
+        specs.reject { |_, spec| Rhino::ComputedAttributeSpec.requires_arguments?(spec) }.keys
       end
 
       # Instantiating is safe (no DB round trip) and is the only way to read an
@@ -206,7 +233,7 @@ module Rhino
         folders << { name: "Update", item: build_update_requests(base) } unless except.include?("update")
         folders << { name: "Destroy", item: build_destroy_requests(base) } unless except.include?("destroy")
 
-        if Array(meta[:collection_computed_attributes]).any? && !except.include?("computed")
+        if (meta[:collection_computed_attributes] || {}).any? && !except.include?("computed")
           folders << { name: "Computed Attributes", item: build_computed_requests(base, meta) }
         end
 
@@ -251,9 +278,9 @@ module Rhino
                                    { "fields[#{slug}]" => meta[:allowed_fields].first(5).join(",") }, headers)
         end
 
-        Array(meta[:record_computed_attributes]).each do |attribute|
+        (meta[:record_computed_attributes] || {}).each do |attribute, spec|
           requests << request_item("With computed attribute #{attribute}", "GET", base,
-                                   { computed_attributes: attribute }, headers)
+                                   computed_attribute_query("computed_attributes", attribute, spec), headers)
         end
 
         unless meta[:allowed_search].empty?
@@ -274,9 +301,9 @@ module Rhino
           requests << request_item("Show with include", "GET", path, { include: meta[:allowed_includes].first.to_s }, headers)
         end
 
-        Array(meta[:record_computed_attributes]).each do |attribute|
+        (meta[:record_computed_attributes] || {}).each do |attribute, spec|
           requests << request_item("Show with computed attribute #{attribute}", "GET", path,
-                                   { computed_attributes: attribute }, headers)
+                                   computed_attribute_query("computed_attributes", attribute, spec), headers)
         end
 
         requests
@@ -302,17 +329,22 @@ module Rhino
       def build_computed_requests(base, meta)
         headers = default_headers
         path = "#{base}/computed"
-        attributes = Array(meta[:collection_computed_attributes])
+        attributes = meta[:collection_computed_attributes] || {}
 
+        # A bare /computed skips required-parameter attributes server-side, so
+        # this stays a valid request.
         requests = [request_item("All computed attributes", "GET", path, {}, headers)]
 
-        attributes.each do |attribute|
-          requests << request_item("Computed: #{attribute}", "GET", path, { attributes: attribute }, headers)
+        attributes.each do |attribute, spec|
+          requests << request_item("Computed: #{attribute}", "GET", path,
+                                   computed_attribute_query("attributes", attribute, spec), headers)
         end
 
-        if attributes.size > 1
+        combinable = argument_free_computed_attributes(attributes)
+
+        if combinable.size > 1
           requests << request_item("Computed: multiple attributes", "GET", path,
-                                   { attributes: attributes.join(",") }, headers)
+                                   { attributes: combinable.join(",") }, headers)
         end
 
         requests

data/lib/rhino/computed_attribute_spec.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Rhino
+  # Parses a model's computed-attribute declarations
+  # (+rhino_record_computed_attributes+ / +rhino_collection_computed_attributes+)
+  # and binds the arguments a client sent for <tt>?attributes[name][param]=value</tt>
+  # (and <tt>?computed_attributes[name][param]=value</tt>) to the declared
+  # parameters.
+  #
+  # Declaration forms (both may be mixed in one hash):
+  #
+  #   {
+  #     # Legacy: anything that is not an extended spec is used as-is — a
+  #     # callable is called, any other value is serialized literally.
+  #     'active_users_count' => ->(scope, _user) { scope.count },
+  #     'schema_version'     => 3,
+  #
+  #     # Extended: a hash carrying at least one of params/optional/with.
+  #     'revenue' => {
+  #       params: %i[from to], optional: [:to],
+  #       with: ->(scope, _user, from, to = nil) { ... }
+  #     }
+  #   }
+  #
+  # Unlike named scopes, there is deliberately NO symbol or bare-list shorthand:
+  # <tt>'version' => 'v3'</tt> and <tt>'tags' => %w[a b]</tt> are valid *literal*
+  # value declarations today, and reinterpreting them as parameter lists would
+  # silently change what a shipped model returns. A declaration is an extended
+  # spec if and only if it is a hash carrying +params+, +optional+ or +with+ —
+  # those three keys are reserved inside a computed-attribute declaration.
+  module ComputedAttributeSpec
+    # The noun every computed-attribute argument error message starts with.
+    SUBJECT = "Computed attribute"
+
+    # The keys whose presence marks a declaration hash as an extended spec.
+    SPEC_KEYS = %i[params optional with].freeze
+
+    module_function
+
+    # Normalize a raw declaration hash into
+    # <tt>name => { params:, optional:, target: }</tt>.
+    #
+    # +target+ is the callable (or the literal value) that produces the
+    # attribute; for a legacy declaration it is the declared value itself.
+    def normalize(declared)
+      return {} unless declared.is_a?(Hash)
+
+      declared.each_with_object({}) do |(name, value), out|
+        out[name.to_s] = normalize_entry(value)
+      end
+    end
+
+    def normalize_entry(value)
+      return { params: [], optional: [], target: value } unless spec?(value)
+
+      spec = value.symbolize_keys
+
+      Rhino::ArgumentBinder
+        .normalize_params(spec[:params], spec[:optional])
+        .merge(target: spec[:with])
+    end
+
+    # Whether a declared value is an extended spec rather than a legacy
+    # callable/literal declaration.
+    def spec?(value)
+      return false unless value.is_a?(Hash)
+
+      SPEC_KEYS.any? { |key| value.key?(key) || value.key?(key.to_s) }
+    end
+
+    # The declared attribute names only.
+    def names(declared)
+      normalize(declared).keys
+    end
+
+    # Whether the attribute declares at least one parameter that the client MUST
+    # supply. Such attributes are skipped — never 403'd — when no selection was
+    # made (a bare <tt>GET /computed</tt>) and when a direct serialization call
+    # passes no arguments for them.
+    def requires_arguments?(spec)
+      (Array(spec[:params]).map(&:to_s) - Array(spec[:optional]).map(&:to_s)).any?
+    end
+
+    # Whether an entry is parameterised, and therefore must be called strictly
+    # with the bound arguments rather than through the tolerant arity branch a
+    # parameterless declaration keeps.
+    def parameterised?(spec)
+      Array(spec[:params]).any?
+    end
+
+    # Bind the raw value a client sent for one attribute to positional
+    # arguments, in the order the model declared them.
+    #
+    # Callers MUST have already checked that the attribute is declared and
+    # policy-visible: the messages raised here name the attribute.
+    def bind(name, spec, raw)
+      Rhino::ArgumentBinder.bind(
+        subject: SUBJECT,
+        name: name,
+        spec: spec,
+        raw: raw,
+        error_class: Rhino::InvalidComputedAttributeArgumentsError
+      )
+    end
+  end
+end

data/lib/rhino/concerns/hidable_columns.rb

@@ -72,15 +72,27 @@ module Rhino
       # Declaring at least one attribute here is what registers the
       # <tt>/computed</tt> route for the model.
       #
+      # An attribute may also declare PARAMETERS the client supplies as
+      # <tt>?attributes[name][param]=value</tt>. Use the extended form — a hash
+      # carrying +params+ (and optionally +optional+ and +with+) — and the bound
+      # arguments are appended after +user+, in declared order. An attribute
+      # with a REQUIRED parameter is skipped by a bare <tt>GET /computed</tt>
+      # rather than 403'd, so adding one never breaks a client that asks for
+      # everything.
+      #
       # @example
       #   def self.rhino_collection_computed_attributes
       #     {
       #       'active_users_count' => ->(scope, _user) { scope.where(status: 'active').count },
-      #       'blocked_users_count' => ->(scope, _user) { scope.where(status: 'blocked').count }
+      #       'blocked_users_count' => ->(scope, _user) { scope.where(status: 'blocked').count },
+      #       'revenue' => {
+      #         params: %i[from to],
+      #         with: ->(scope, _user, from, to) { scope.where(created_at: from..to).sum(:total) }
+      #       }
       #     }
       #   end
       #
-      # @return [Hash{String => #call}]
+      # @return [Hash{String => Object}]
       def rhino_collection_computed_attributes
         {}
       end
@@ -108,8 +120,14 @@ module Rhino
     # Do NOT override this method. Override +rhino_computed_attributes+ instead
     # to add computed/virtual attributes to the JSON response.
     #
+    # @param computed_attributes [Array<String>] opt-in record-level computed
+    #   attributes to evaluate, selected via <tt>?computed_attributes=</tt>.
+    # @param computed_arguments [Hash{String => Array}] positional arguments per
+    #   attribute name. An attribute with required parameters and no entry here
+    #   is skipped rather than called with too few arguments, so an existing
+    #   direct caller that passes only names keeps working.
     # @return [Hash]
-    def as_rhino_json(computed_attributes: [])
+    def as_rhino_json(computed_attributes: [], computed_arguments: {})
       user = rhino_current_user
       hidden = hidden_columns_for(user)
       result = as_json(except: hidden)
@@ -123,7 +141,9 @@ module Rhino
       # by name, so declaring an expensive attribute costs nothing on requests
       # that don't want it. Merged before policy filtering, so the blacklist and
       # whitelist below still govern them.
-      result.merge!(rhino_resolve_record_computed_attributes(computed_attributes, user))
+      result.merge!(
+        rhino_resolve_record_computed_attributes(computed_attributes, user, computed_arguments)
+      )
 
       # Apply blacklist to the final hash (covers DB columns from as_json
       # overrides AND computed attributes from rhino_computed_attributes)
@@ -173,15 +193,27 @@ module Rhino
     # Return a hash of attribute name => callable. The callable may accept
     # zero, one (record) or two (record, user) arguments.
     #
+    # An attribute may also declare PARAMETERS the client supplies as
+    # <tt>?computed_attributes[name][param]=value</tt>. Use the extended form —
+    # a hash carrying +params+ (and optionally +optional+ and +with+) — and the
+    # bound arguments are appended after +user+, in declared order. A
+    # parameterised entry is always called as <tt>call(record, user, *args)</tt>.
+    # Any other declared value (a callable, a scalar, a plain array) keeps its
+    # current meaning.
+    #
     # @example
     #   def rhino_record_computed_attributes
     #     {
     #       'open_tickets_count' => ->(record, _user) { record.tickets.where(closed_at: nil).count },
-    #       'full_name' => ->(record, _user) { "#{record.first_name} #{record.last_name}" }
+    #       'full_name' => ->(record, _user) { "#{record.first_name} #{record.last_name}" },
+    #       'tickets_since' => {
+    #         params: [:since],
+    #         with: ->(record, _user, since) { record.tickets.where("created_at >= ?", since).count }
+    #       }
     #     }
     #   end
     #
-    # @return [Hash{String => #call}]
+    # @return [Hash{String => Object}]
     def rhino_record_computed_attributes
       {}
     end
@@ -193,26 +225,49 @@ module Rhino
     # Names that are not declared are silently skipped — the controller has
     # already rejected unknown/forbidden names with a 403, and a direct
     # +as_rhino_json+ caller must not be able to force an arbitrary call.
-    def rhino_resolve_record_computed_attributes(names, user)
+    #
+    # An attribute that declares a required parameter is likewise skipped when
+    # +arguments+ carries no entry for it, so a custom controller calling
+    # <tt>as_rhino_json(computed_attributes: ['tickets_since'])</tt> gets a
+    # missing key rather than an ArgumentError.
+    def rhino_resolve_record_computed_attributes(names, user, arguments = {})
       return {} if names.blank?
 
-      declared = rhino_record_computed_attributes
-      return {} unless declared.is_a?(Hash) && declared.any?
+      specs = Rhino::ComputedAttributeSpec.normalize(rhino_record_computed_attributes)
+      return {} if specs.empty?
+
+      arguments = (arguments || {}).transform_keys(&:to_s)
 
       Array(names).each_with_object({}) do |name, memo|
         key = name.to_s
-        next unless declared.key?(key)
+        spec = specs[key]
+        next if spec.nil?
 
-        memo[key] = rhino_call_computed(declared[key], self, user)
+        if arguments.key?(key)
+          args = Array(arguments[key])
+        elsif Rhino::ComputedAttributeSpec.requires_arguments?(spec)
+          next
+        else
+          args = []
+        end
+
+        memo[key] = rhino_call_computed(spec, self, user, args)
       end
     end
 
-    # Invoke a declared callable, tolerating lambdas of arity 0, 1 or 2.
-    # Ruby lambdas are strict about arity, so the arity is honoured rather than
-    # forcing every declaration to accept both arguments.
-    def rhino_call_computed(entry, record, user)
+    # Invoke a declared entry.
+    #
+    # A PARAMETERISED entry is always called as `call(record, user, *args)` —
+    # the declaration is the contract. A parameterless entry keeps today's
+    # tolerant arity 0/1/2 branch: Ruby lambdas are strict about arity, so the
+    # arity is honoured rather than forcing every declaration to accept both
+    # arguments.
+    def rhino_call_computed(spec, record, user, args = [])
+      entry = spec[:target]
       return entry unless entry.respond_to?(:call)
 
+      return entry.call(record, user, *args) if Rhino::ComputedAttributeSpec.parameterised?(spec)
+
       case entry.try(:arity)
       when 0 then entry.call
       when 1 then entry.call(record)

data/lib/rhino/controllers/resources_controller.rb

@@ -27,6 +27,10 @@ module Rhino
       render json: { message: e.message }, status: :forbidden
     end
 
+    rescue_from Rhino::InvalidComputedAttributeArgumentsError do |e|
+      render json: { message: e.message }, status: :forbidden
+    end
+
     rescue_from Rhino::QueryAttributeNotAllowedError do |e|
       render json: { message: e.message }, status: :forbidden
     end
@@ -53,7 +57,7 @@ module Rhino
     def index
       authorize model_class, :index?, policy_class: policy_for(model_class)
 
-      computed = resolve_requested_computed_attributes
+      computed, computed_args = resolve_requested_computed_attributes
       return if performed?
 
       builder = QueryBuilder.new(model_class, params: params, named_scopes: true)
@@ -66,9 +70,9 @@ module Rhino
       if per_page.present? || pagination_enabled
         result = builder.paginate
         set_pagination_headers(result[:pagination])
-        render json: { data: serialize_collection(result[:items], computed) }
+        render json: { data: serialize_collection(result[:items], computed, computed_args) }
       else
-        render json: { data: serialize_collection(builder.to_scope, computed) }
+        render json: { data: serialize_collection(builder.to_scope, computed, computed_args) }
       end
     end
 
@@ -112,7 +116,7 @@ module Rhino
       record = find_record
       authorize record, :show?, policy_class: policy_for(record)
 
-      computed = resolve_requested_computed_attributes
+      computed, computed_args = resolve_requested_computed_attributes
       return if performed?
 
       # Apply includes if requested
@@ -128,7 +132,7 @@ module Rhino
         record = builder.to_scope.first!
       end
 
-      render json: serialize_record(record, computed)
+      render json: serialize_record(record, computed, computed_args)
     end
 
     # PUT /api/{slug}/:id
@@ -192,7 +196,7 @@ module Rhino
     def trashed
       authorize model_class, :view_trashed?, policy_class: policy_for(model_class)
 
-      computed = resolve_requested_computed_attributes
+      computed, computed_args = resolve_requested_computed_attributes
       return if performed?
 
       builder = QueryBuilder.new(model_class.discarded, params: params, named_scopes: true)
@@ -205,9 +209,9 @@ module Rhino
       if per_page.present? || pagination_enabled
         result = builder.paginate
         set_pagination_headers(result[:pagination])
-        render json: { data: serialize_collection(result[:items], computed) }
+        render json: { data: serialize_collection(result[:items], computed, computed_args) }
       else
-        render json: { data: serialize_collection(builder.to_scope, computed) }
+        render json: { data: serialize_collection(builder.to_scope, computed, computed_args) }
       end
     end
 
@@ -223,12 +227,18 @@ module Rhino
     # listed. Sorting, sparse fieldsets, includes and pagination are
     # deliberately NOT applied.
     #
-    # Omitting `?attributes=` returns every declared attribute the policy allows.
+    # Omitting `?attributes=` returns every declared attribute the policy allows,
+    # minus any that declares a required parameter — those are skipped silently
+    # so adding a parameterised attribute never breaks a bare `/computed` call.
+    #
+    # Attributes that declare parameters take them in the bracket form:
+    #
+    #   ?attributes[revenue][from]=2026-01-01&attributes[revenue][to]=2026-02-01
     def computed
       authorize model_class, :index?, policy_class: policy_for(model_class)
 
-      declared = collection_computed_attributes
-      names = resolve_requested_collection_attributes(declared)
+      specs = Rhino::ComputedAttributeSpec.normalize(collection_computed_attributes)
+      names, arguments = resolve_requested_collection_attributes(collection_computed_attributes)
       return if performed?
 
       builder = QueryBuilder.new(model_class, params: params, named_scopes: true)
@@ -241,8 +251,11 @@ module Rhino
       data = names.each_with_object({}) do |name, memo|
         # Each attribute gets the base relation; ActiveRecord relations are
         # immutable under chaining, so one callable's constraints can never
-        # leak into the next one's result.
-        memo[name] = call_computed_attribute(declared[name], scope, user)
+        # leak into the next one's result. The relation is already
+        # organization-scoped, filtered and searched, and no argument can
+        # widen it.
+        spec = specs[name] || { params: [], optional: [], target: nil }
+        memo[name] = call_computed_attribute(spec, scope, user, arguments[name] || [])
       end
 
       render json: { data: data }
@@ -666,67 +679,108 @@ module Rhino
       declared.is_a?(Hash) ? declared.transform_keys(&:to_s) : {}
     end
 
-    # Parse and authorize `?attributes=a,b` for the /computed endpoint.
+    # Parse and authorize `?attributes=` for the /computed endpoint, in every
+    # accepted form:
+    #
+    #   ?attributes=a,b                       legacy comma list, no arguments
+    #   ?attributes[revenue]=                 one name, no arguments
+    #   ?attributes[since]=2026-01-01         binds to the single declared param
+    #   ?attributes[revenue][from]=a&...      named arguments
     #
-    # Renders a 403 and returns [] on a bad/denied name. An undeclared name and
-    # a policy-denied name produce the SAME error, so the endpoint never reveals
-    # which attributes a model declares.
+    # Returns <tt>[names, arguments]</tt> — arguments keyed by attribute name —
+    # or renders a 403 and returns <tt>[[], {}]</tt>. An undeclared name and a
+    # policy-denied name produce the SAME error, so the endpoint never reveals
+    # which attributes a model declares; both checks run BEFORE any argument
+    # binding, so the more specific argument messages can only ever be seen for
+    # a name the caller was already allowed to use.
     def resolve_requested_collection_attributes(declared)
+      specs = Rhino::ComputedAttributeSpec.normalize(declared)
       raw = params[:attributes]
+      user = current_user
 
-      # Reject non-scalar input (?attributes[]=x) before any lookup.
-      if raw.present? && !raw.is_a?(String)
-        render json: { message: "Computed attributes are not allowed" }, status: :forbidden
-        return []
+      if raw.nil? || (raw.is_a?(String) && raw.strip.empty?)
+        # No selection: every declared attribute the policy allows, minus the
+        # ones that cannot run without client arguments.
+        names = specs.reject { |_, spec| Rhino::ComputedAttributeSpec.requires_arguments?(spec) }
+                     .keys
+                     .select { |name| computed_attribute_allowed?(name, user) }
+
+        return [names, {}]
       end
 
-      user = current_user
+      requested = parse_attribute_selection(raw)
+      return [[], {}] if performed?
 
-      if raw.blank?
-        # No selection: every declared attribute the policy allows.
-        return declared.keys.select { |name| computed_attribute_allowed?(name, user) }
-      end
+      bind_attribute_selection(requested, specs, user)
+    end
 
-      names = parse_attribute_list(raw)
+    # Parse and authorize `?computed_attributes=` for index/show/trashed — the
+    # OPT-IN record-level computed attributes. Accepts the same four forms as
+    # `?attributes=` (see resolve_requested_collection_attributes).
+    #
+    # Absent or blank means "none", which is byte-for-byte the pre-feature
+    # behavior.
+    def resolve_requested_computed_attributes
+      raw = params[:computed_attributes]
+      return [[], {}] if raw.nil? || raw == ""
 
-      names.each do |name|
-        next if declared.key?(name) && computed_attribute_allowed?(name, user)
+      requested = parse_attribute_selection(raw)
+      return [[], {}] if performed? || requested.empty?
 
-        render json: { message: "Computed attribute '#{name}' is not allowed" }, status: :forbidden
-        return []
-      end
+      declared = model_class.new.try(:rhino_record_computed_attributes)
 
-      names
+      bind_attribute_selection(
+        requested,
+        Rhino::ComputedAttributeSpec.normalize(declared),
+        current_user
+      )
     end
 
-    # Parse and authorize `?computed_attributes=a,b` for index/show/trashed —
-    # the OPT-IN record-level computed attributes. Absent or blank means "none",
-    # which is byte-for-byte the pre-feature behavior.
-    def resolve_requested_computed_attributes
-      raw = params[:computed_attributes]
-      return [] if raw.nil? || raw == ""
+    # Turn the raw query value into an ordered list of
+    # <tt>[name, raw_arguments]</tt> pairs.
+    def parse_attribute_selection(raw)
+      return parse_attribute_list(raw).map { |name| [name, ""] } if raw.is_a?(String)
 
-      unless raw.is_a?(String)
+      raw = raw.to_unsafe_h if raw.respond_to?(:to_unsafe_h)
+
+      unless raw.is_a?(Hash)
         render json: { message: "Computed attributes are not allowed" }, status: :forbidden
         return []
       end
 
-      names = parse_attribute_list(raw)
-      return [] if names.empty?
+      pairs = []
+      raw.each do |key, value|
+        # A positional list (?attributes[]=x) or a blank key names nothing:
+        # reject before any lookup.
+        if key.to_s.empty?
+          render json: { message: "Computed attributes are not allowed" }, status: :forbidden
+          return []
+        end
 
-      declared = model_class.new.try(:rhino_record_computed_attributes)
-      declared = declared.is_a?(Hash) ? declared.transform_keys(&:to_s) : {}
+        pairs << [key.to_s, value]
+      end
 
-      user = current_user
+      pairs
+    end
 
-      names.each do |name|
-        next if declared.key?(name) && computed_attribute_allowed?(name, user)
+    # Gate every requested attribute, then bind its arguments.
+    def bind_attribute_selection(requested, specs, user)
+      names = []
+      arguments = {}
+
+      requested.each do |(name, raw_arguments)|
+        # Gate first — declared AND policy-visible — so nothing below can
+        # distinguish an undeclared name from a forbidden one.
+        unless specs.key?(name) && computed_attribute_allowed?(name, user)
+          render json: { message: "Computed attribute '#{name}' is not allowed" }, status: :forbidden
+          return [[], {}]
+        end
 
-        render json: { message: "Computed attribute '#{name}' is not allowed" }, status: :forbidden
-        return []
+        arguments[name] = Rhino::ComputedAttributeSpec.bind(name, specs[name], raw_arguments)
+        names << name
       end
 
-      names
+      [names.uniq, arguments]
     end
 
     # Split a comma-separated attribute list, dropping blanks and duplicates.
@@ -759,10 +813,19 @@ module Rhino
       true
     end
 
-    # Invoke a declared callable, tolerating lambdas of arity 0, 1 or 2.
-    def call_computed_attribute(entry, scope, user)
+    # Invoke a declared entry.
+    #
+    # A PARAMETERISED entry is always called as `call(scope, user, *args)` — the
+    # declaration is the contract, and a mismatched lambda is a developer error,
+    # exactly as it is for a parameterised scope. A parameterless entry keeps
+    # today's tolerant arity 0/1/2 branch, so no existing lambda changes
+    # behavior.
+    def call_computed_attribute(spec, scope, user, args = [])
+      entry = spec[:target]
       return entry unless entry.respond_to?(:call)
 
+      return entry.call(scope, user, *args) if Rhino::ComputedAttributeSpec.parameterised?(spec)
+
       case entry.try(:arity)
       when 0 then entry.call
       when 1 then entry.call(scope)
@@ -770,16 +833,19 @@ module Rhino
       end
     end
 
-    def serialize_record(record, computed_attributes = [])
+    def serialize_record(record, computed_attributes = [], computed_arguments = {})
       if record.respond_to?(:as_rhino_json)
-        record.as_rhino_json(computed_attributes: computed_attributes)
+        record.as_rhino_json(
+          computed_attributes: computed_attributes,
+          computed_arguments: computed_arguments
+        )
       else
         record.as_json
       end
     end
 
-    def serialize_collection(records, computed_attributes = [])
-      records.map { |r| serialize_record(r, computed_attributes) }
+    def serialize_collection(records, computed_attributes = [], computed_arguments = {})
+      records.map { |r| serialize_record(r, computed_attributes, computed_arguments) }
     end
 
     # ------------------------------------------------------------------

data/lib/rhino/invalid_computed_attribute_arguments_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Rhino
+  # Raised when a client-requested computed attribute is given arguments that do
+  # not match the model's declared parameter spec. Rendered as 403 by
+  # ResourcesController, message and all: it is only ever raised after the
+  # attribute name itself passed the declaration check and the policy, so naming
+  # the parameters reveals nothing about attributes the user may not see.
+  class InvalidComputedAttributeArgumentsError < StandardError; end
+end

data/lib/rhino/scope_spec.rb

@@ -16,6 +16,11 @@ module Rhino
   # A scope with no declared parameters never receives arguments: sending any
   # is a 403, so a scope written without client input can never be handed some.
   module ScopeSpec
+    # The noun every scope-argument error message starts with. The binding
+    # algorithm itself lives in Rhino::ArgumentBinder and is shared with
+    # computed attributes; this constant is what keeps the scope wording its own.
+    SUBJECT = "Scope"
+
     module_function
 
     # Normalize a raw +allowed_scopes+ hash into
@@ -30,10 +35,10 @@ module Rhino
     def normalize_entry(name, value)
       if value.is_a?(Hash) || value.is_a?(ActiveSupport::HashWithIndifferentAccess)
         spec = value.symbolize_keys
-        params = Array(spec[:params]).map(&:to_s)
-        optional = Array(spec[:optional]).map(&:to_s) & params
 
-        { target: spec[:with] || name.to_sym, params: params, optional: optional }
+        Rhino::ArgumentBinder
+          .normalize_params(spec[:params], spec[:optional])
+          .merge(target: spec[:with] || name.to_sym)
       else
         { target: value, params: [], optional: [] }
       end
@@ -48,77 +53,33 @@ module Rhino
     #
     # Raises Rhino::InvalidScopeArgumentsError.
     def bind(name, spec, raw)
-      params = spec[:params]
-      given = normalize_raw_arguments(name, params, raw)
-
-      given.each_key do |key|
-        unless params.include?(key)
-          raise Rhino::InvalidScopeArgumentsError, "Scope '#{name}' does not accept parameter '#{key}'"
-        end
-      end
-
-      args = params.map do |param|
-        if given.key?(param)
-          coerce(given[param])
-        elsif spec[:optional].include?(param)
-          nil
-        else
-          raise Rhino::InvalidScopeArgumentsError, "Scope '#{name}' requires parameter '#{param}'"
-        end
-      end
-
-      # Drop trailing nils so an omitted optional parameter falls back to the
-      # default in the scope's own signature.
-      args.pop while args.any? && args.last.nil?
-      args
+      Rhino::ArgumentBinder.bind(
+        subject: SUBJECT,
+        name: name,
+        spec: spec,
+        raw: raw,
+        error_class: Rhino::InvalidScopeArgumentsError,
+        # Scope wire names are underscored (?scope[availableForDrivers]), and so
+        # are their parameter names.
+        underscore_keys: true
+      )
     end
 
     def normalize_raw_arguments(name, params, raw)
-      # ?scope[archived]= (or a bare ?scope[archived]): no arguments. A scope
-      # with required parameters still fails, in bind, naming them.
-      return {} if raw.nil? || raw == ""
-
-      raw = raw.to_unsafe_h if raw.respond_to?(:to_unsafe_h)
-
-      if raw.is_a?(Array)
-        # A positional list (scope[between][]=a) names nothing.
-        raise Rhino::InvalidScopeArgumentsError, "Scope '#{name}' requires named parameters"
-      end
-
-      unless raw.is_a?(Hash)
-        raise Rhino::InvalidScopeArgumentsError, "Scope '#{name}' does not accept arguments" if params.empty?
-
-        # A bare value binds to the single declared parameter. Two parameters can
-        # never be guessed at from one value.
-        if params.length > 1
-          raise Rhino::InvalidScopeArgumentsError, "Scope '#{name}' requires named parameters"
-        end
-
-        return { params.first => raw }
-      end
-
-      raise Rhino::InvalidScopeArgumentsError, "Scope '#{name}' does not accept arguments" if params.empty?
-
-      raw.each_with_object({}) do |(key, value), out|
-        unless value.is_a?(String) || value.is_a?(Numeric) || value.is_a?(TrueClass) ||
-               value.is_a?(FalseClass) || value.nil?
-          raise Rhino::InvalidScopeArgumentsError, "Scope '#{name}' requires named parameters"
-        end
-
-        out[key.to_s.underscore] = value
-      end
+      Rhino::ArgumentBinder.normalize_raw_arguments(
+        subject: SUBJECT,
+        name: name,
+        params: params,
+        raw: raw,
+        error_class: Rhino::InvalidScopeArgumentsError,
+        underscore_keys: true
+      )
     end
 
     # Query-string values always arrive as strings; hand scope bodies real
     # booleans so a check cannot be fooled by the string "false".
     def coerce(value)
-      return value unless value.is_a?(String)
-
-      case value.downcase
-      when "true" then true
-      when "false" then false
-      else value
-      end
+      Rhino::ArgumentBinder.coerce(value)
     end
   end
 end

data/lib/rhino/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rhino
-  VERSION = "4.8.1"
+  VERSION = "4.9.0"
 end

data/lib/rhino.rb

@@ -5,7 +5,10 @@ require "rhino/configuration"
 require "rhino/auth_rejected"
 require "rhino/scope_not_allowed_error"
 require "rhino/invalid_scope_arguments_error"
+require "rhino/invalid_computed_attribute_arguments_error"
+require "rhino/argument_binder"
 require "rhino/scope_spec"
+require "rhino/computed_attribute_spec"
 require "rhino/missing_tenant_context"
 require "rhino/auth_hooks"
 require "rhino/group_membership"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rhino-rails
 version: !ruby/object:Gem::Version
-  version: 4.8.1
+  version: 4.9.0
 platform: ruby
 authors:
 - Bruno Cipolla
@@ -190,6 +190,7 @@ files:
 - README.md
 - lib/rhino-rails.rb
 - lib/rhino.rb
+- lib/rhino/argument_binder.rb
 - lib/rhino/auth_hooks.rb
 - lib/rhino/auth_rejected.rb
 - lib/rhino/blueprint/blueprint_parser.rb
@@ -207,6 +208,7 @@ files:
 - lib/rhino/commands/generate_command.rb
 - lib/rhino/commands/install_command.rb
 - lib/rhino/commands/invitation_link_command.rb
+- lib/rhino/computed_attribute_spec.rb
 - lib/rhino/concerns/belongs_to_organization.rb
 - lib/rhino/concerns/has_audit_trail.rb
 - lib/rhino/concerns/has_auto_scope.rb
@@ -223,6 +225,7 @@ files:
 - lib/rhino/controllers/resources_controller.rb
 - lib/rhino/engine.rb
 - lib/rhino/group_membership.rb
+- lib/rhino/invalid_computed_attribute_arguments_error.rb
 - lib/rhino/invalid_scope_arguments_error.rb
 - lib/rhino/mailers/invitation_mailer.rb
 - lib/rhino/middleware/resolve_organization_from_route.rb