rhino-rails 4.6.1 → 4.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec046eac08bcbf895ec331091f9204e4abba36bf712dc2d283b2c91a02f36671
-  data.tar.gz: 9b72423cd739ed788cf2554b08aa7ba5f5d1dcbc4739689058bf6566b940f0f4
+  metadata.gz: 3da378b6f647733a88cb598ff3b23e06462f6c61494ebbc322fed024e9ba33a9
+  data.tar.gz: e3dec4fcb82201e652e76e01ff7b5d8fa25c1ec61dde9d3b58f688f9a0d4ceb2
 SHA512:
-  metadata.gz: adc4639f14af9208841959882a089595573f910a67168551eca6c1cd6eb9d73e3f29523ad8ec49b0ce91e95692ca43b08c29a7d2b121605193c2e51d13b9a686
-  data.tar.gz: 7e6eb9a292a199dbf2f1c42b1e6970c3f99b7bc0df49d1b5318f5987ef1a5b5b070dc4cf01b613bbf035d40d001c8bfd8bf0c3dd1e27141f008da37b48689807
+  metadata.gz: a37303c3543f0e140bc5f00371c1d8d8d310a30645a0ef2c3b9bd218d5cebe74e83c3f500f413792ce7496b764832219044739422f4a13f7be1b3dd1fe63bdec
+  data.tar.gz: fc60726be3e23b1da9ddcccc4fc884857608fb412125211b48cad5bfb51596d4986f6db13ed2728b70644f1d2c3a4be2e2e9a5fac5093ba6746783923fc01681

data/lib/rhino/commands/export_postman_command.rb

@@ -175,10 +175,26 @@ 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)),
           default_sort: model_class.try(:default_sort_field)
         }
       end
 
+      def computed_names(declared)
+        declared.is_a?(Hash) ? declared.keys.map(&:to_s) : []
+      end
+
+      # Instantiating is safe (no DB round trip) and is the only way to read an
+      # instance-level declaration; a model that cannot be instantiated simply
+      # exports no record-level examples.
+      def record_computed_declaration(model_class)
+        model_class.new.try(:rhino_record_computed_attributes)
+      rescue StandardError
+        {}
+      end
+
       def build_action_folders(slug, meta, group_prefix)
         folders = []
         base = base_path(slug, group_prefix)
@@ -190,6 +206,10 @@ 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")
+          folders << { name: "Computed Attributes", item: build_computed_requests(base, meta) }
+        end
+
         if meta[:uses_soft_deletes]
           folders << { name: "Trashed", item: build_trashed_requests(base) } unless except.include?("trashed")
           folders << { name: "Restore", item: build_restore_requests(base) } unless except.include?("restore")
@@ -231,6 +251,11 @@ module Rhino
                                    { "fields[#{slug}]" => meta[:allowed_fields].first(5).join(",") }, headers)
         end
 
+        Array(meta[:record_computed_attributes]).each do |attribute|
+          requests << request_item("With computed attribute #{attribute}", "GET", base,
+                                   { computed_attributes: attribute }, headers)
+        end
+
         unless meta[:allowed_search].empty?
           requests << request_item("Search", "GET", base, { search: "example" }, headers)
         end
@@ -249,6 +274,11 @@ 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|
+          requests << request_item("Show with computed attribute #{attribute}", "GET", path,
+                                   { computed_attributes: attribute }, headers)
+        end
+
         requests
       end
 
@@ -268,6 +298,26 @@ module Rhino
         [request_item("Delete by ID", "DELETE", path, {}, default_headers)]
       end
 
+      # Requests for GET {resource}/computed — the collection-level aggregates.
+      def build_computed_requests(base, meta)
+        headers = default_headers
+        path = "#{base}/computed"
+        attributes = Array(meta[:collection_computed_attributes])
+
+        requests = [request_item("All computed attributes", "GET", path, {}, headers)]
+
+        attributes.each do |attribute|
+          requests << request_item("Computed: #{attribute}", "GET", path, { attributes: attribute }, headers)
+        end
+
+        if attributes.size > 1
+          requests << request_item("Computed: multiple attributes", "GET", path,
+                                   { attributes: attributes.join(",") }, headers)
+        end
+
+        requests
+      end
+
       def build_trashed_requests(base)
         [request_item("List trashed", "GET", "#{base}/trashed", {}, default_headers)]
       end

data/lib/rhino/concerns/has_rhino.rb

@@ -101,6 +101,9 @@ module Rhino
         self.rhino_middleware_actions_map = actions_hash.transform_keys(&:to_s)
       end
 
+      # CRUD actions to exclude from route registration.
+      # Valid values: :index, :show, :store, :update, :destroy, :trashed,
+      # :restore, :forceDelete, :computed.
       def rhino_except_actions(*actions)
         self.rhino_except_actions_list = actions.map(&:to_s)
       end

data/lib/rhino/concerns/hidable_columns.rb

@@ -59,6 +59,31 @@ module Rhino
       def rhino_additional_hidden(*columns)
         self.additional_hidden_columns = columns.map(&:to_s)
       end
+
+      # Override this method to declare COLLECTION-level computed attributes,
+      # served by <tt>GET /api/{resource}/computed?attributes=a,b</tt>.
+      #
+      # Each callable receives the fully scoped relation (organization scope,
+      # default/global scopes, <tt>?scope=</tt>, <tt>?filter[]=</tt> and
+      # <tt>?search=</tt> already applied) plus the current user, and is
+      # evaluated ONCE for the whole collection — not once per row. This is the
+      # cheap way to expose aggregates such as counts.
+      #
+      # Declaring at least one attribute here is what registers the
+      # <tt>/computed</tt> route for the model.
+      #
+      # @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 }
+      #     }
+      #   end
+      #
+      # @return [Hash{String => #call}]
+      def rhino_collection_computed_attributes
+        {}
+      end
     end
 
     # Get the list of columns to hide for the current user.
@@ -84,7 +109,7 @@ module Rhino
     # to add computed/virtual attributes to the JSON response.
     #
     # @return [Hash]
-    def as_rhino_json
+    def as_rhino_json(computed_attributes: [])
       user = rhino_current_user
       hidden = hidden_columns_for(user)
       result = as_json(except: hidden)
@@ -93,6 +118,13 @@ module Rhino
       computed = rhino_computed_attributes
       result.merge!(computed) if computed.is_a?(Hash) && computed.any?
 
+      # Merge the OPT-IN record-level computed attributes the client selected via
+      # ?computed_attributes=. Nothing here is evaluated unless it was asked for
+      # 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))
+
       # Apply blacklist to the final hash (covers DB columns from as_json
       # overrides AND computed attributes from rhino_computed_attributes)
       hidden_set = Set.new(hidden)
@@ -132,8 +164,62 @@ module Rhino
       {}
     end
 
+    # Override this method to declare OPT-IN record-level computed attributes.
+    #
+    # Unlike +rhino_computed_attributes+, nothing here is evaluated unless the
+    # client names it in <tt>?computed_attributes=a,b</tt> on index/show/trashed
+    # — so expensive per-row work is only paid for when it is actually wanted.
+    #
+    # Return a hash of attribute name => callable. The callable may accept
+    # zero, one (record) or two (record, user) arguments.
+    #
+    # @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}" }
+    #     }
+    #   end
+    #
+    # @return [Hash{String => #call}]
+    def rhino_record_computed_attributes
+      {}
+    end
+
     private
 
+    # Evaluate the selected opt-in record-level computed attributes.
+    #
+    # 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)
+      return {} if names.blank?
+
+      declared = rhino_record_computed_attributes
+      return {} unless declared.is_a?(Hash) && declared.any?
+
+      Array(names).each_with_object({}) do |name, memo|
+        key = name.to_s
+        next unless declared.key?(key)
+
+        memo[key] = rhino_call_computed(declared[key], self, user)
+      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)
+      return entry unless entry.respond_to?(:call)
+
+      case entry.try(:arity)
+      when 0 then entry.call
+      when 1 then entry.call(record)
+      else entry.call(record, user)
+      end
+    end
+
     # Resolves the current user from RequestStore.
     # @return [Object, nil]
     def rhino_current_user

data/lib/rhino/controllers/resources_controller.rb

@@ -42,6 +42,9 @@ module Rhino
     def index
       authorize model_class, :index?, policy_class: policy_for(model_class)
 
+      computed = resolve_requested_computed_attributes
+      return if performed?
+
       builder = QueryBuilder.new(model_class, params: params, named_scopes: true)
       apply_organization_scope(builder)
       builder.build
@@ -52,9 +55,9 @@ module Rhino
       if per_page.present? || pagination_enabled
         result = builder.paginate
         set_pagination_headers(result[:pagination])
-        render json: { data: serialize_collection(result[:items]) }
+        render json: { data: serialize_collection(result[:items], computed) }
       else
-        render json: { data: serialize_collection(builder.to_scope) }
+        render json: { data: serialize_collection(builder.to_scope, computed) }
       end
     end
 
@@ -98,6 +101,9 @@ module Rhino
       record = find_record
       authorize record, :show?, policy_class: policy_for(record)
 
+      computed = resolve_requested_computed_attributes
+      return if performed?
+
       # Apply includes if requested
       if params[:include].present?
         auth_response = authorize_includes
@@ -111,7 +117,7 @@ module Rhino
         record = builder.to_scope.first!
       end
 
-      render json: serialize_record(record)
+      render json: serialize_record(record, computed)
     end
 
     # PUT /api/{slug}/:id
@@ -175,6 +181,9 @@ module Rhino
     def trashed
       authorize model_class, :view_trashed?, policy_class: policy_for(model_class)
 
+      computed = resolve_requested_computed_attributes
+      return if performed?
+
       builder = QueryBuilder.new(model_class.discarded, params: params, named_scopes: true)
       apply_organization_scope(builder)
       builder.build
@@ -185,10 +194,47 @@ module Rhino
       if per_page.present? || pagination_enabled
         result = builder.paginate
         set_pagination_headers(result[:pagination])
-        render json: { data: serialize_collection(result[:items]) }
+        render json: { data: serialize_collection(result[:items], computed) }
       else
-        render json: { data: serialize_collection(builder.to_scope) }
+        render json: { data: serialize_collection(builder.to_scope, computed) }
+      end
+    end
+
+    # GET /api/{slug}/computed?attributes=a,b
+    #
+    # Collection-level computed attributes: each declared callable is evaluated
+    # ONCE over the whole (scoped + filtered) relation instead of once per row,
+    # which is what makes aggregates such as `active_users_count` cheap.
+    #
+    # The relation handed to each callable has the organization scope, the
+    # model's default scopes, `?scope=`, `?filter[]=` and `?search=` already
+    # applied — so the numbers describe exactly the set `index` would have
+    # listed. Sorting, sparse fieldsets, includes and pagination are
+    # deliberately NOT applied.
+    #
+    # Omitting `?attributes=` returns every declared attribute the policy allows.
+    def computed
+      authorize model_class, :index?, policy_class: policy_for(model_class)
+
+      declared = collection_computed_attributes
+      names = resolve_requested_collection_attributes(declared)
+      return if performed?
+
+      builder = QueryBuilder.new(model_class, params: params, named_scopes: true)
+      apply_organization_scope(builder)
+      builder.build_for_computed
+
+      scope = builder.to_scope
+      user = current_user
+
+      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)
       end
+
+      render json: { data: data }
     end
 
     # POST /api/{slug}/:id/restore
@@ -599,16 +645,130 @@ module Rhino
     # Serialization
     # ------------------------------------------------------------------
 
-    def serialize_record(record)
+    # ------------------------------------------------------------------
+    # Computed attributes
+    # ------------------------------------------------------------------
+
+    # The model's declared collection-level computed attributes (name => callable).
+    def collection_computed_attributes
+      declared = model_class.try(:rhino_collection_computed_attributes)
+      declared.is_a?(Hash) ? declared.transform_keys(&:to_s) : {}
+    end
+
+    # Parse and authorize `?attributes=a,b` for the /computed endpoint.
+    #
+    # 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.
+    def resolve_requested_collection_attributes(declared)
+      raw = params[:attributes]
+
+      # 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 []
+      end
+
+      user = current_user
+
+      if raw.blank?
+        # No selection: every declared attribute the policy allows.
+        return declared.keys.select { |name| computed_attribute_allowed?(name, user) }
+      end
+
+      names = parse_attribute_list(raw)
+
+      names.each do |name|
+        next if declared.key?(name) && computed_attribute_allowed?(name, user)
+
+        render json: { message: "Computed attribute '#{name}' is not allowed" }, status: :forbidden
+        return []
+      end
+
+      names
+    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 == ""
+
+      unless raw.is_a?(String)
+        render json: { message: "Computed attributes are not allowed" }, status: :forbidden
+        return []
+      end
+
+      names = parse_attribute_list(raw)
+      return [] if names.empty?
+
+      declared = model_class.new.try(:rhino_record_computed_attributes)
+      declared = declared.is_a?(Hash) ? declared.transform_keys(&:to_s) : {}
+
+      user = current_user
+
+      names.each do |name|
+        next if declared.key?(name) && computed_attribute_allowed?(name, user)
+
+        render json: { message: "Computed attribute '#{name}' is not allowed" }, status: :forbidden
+        return []
+      end
+
+      names
+    end
+
+    # Split a comma-separated attribute list, dropping blanks and duplicates.
+    def parse_attribute_list(raw)
+      raw.to_s.split(",").map(&:strip).reject(&:empty?).uniq
+    end
+
+    # Whether the policy lets this user see a computed attribute.
+    #
+    # Computed attributes go through the SAME gate as columns:
+    # +hidden_attributes_for_show+ blacklists, and +permitted_attributes_for_show+
+    # whitelists unless it returns the ['*'] default.
+    def computed_attribute_allowed?(name, user)
+      policy = policy_for(model_class).new(user, model_class)
+
+      if policy.respond_to?(:hidden_attributes_for_show)
+        hidden = Array(policy.hidden_attributes_for_show(user)).map(&:to_s)
+        return false if hidden.include?(name)
+      end
+
+      return true unless policy.respond_to?(:permitted_attributes_for_show)
+
+      permitted = policy.permitted_attributes_for_show(user)
+      return true if permitted.nil? || permitted == ["*"]
+
+      Array(permitted).map(&:to_s).include?(name)
+    rescue StandardError
+      # Policy resolution failed — serialization applies the same filters again
+      # downstream, so nothing can leak through this fallback.
+      true
+    end
+
+    # Invoke a declared callable, tolerating lambdas of arity 0, 1 or 2.
+    def call_computed_attribute(entry, scope, user)
+      return entry unless entry.respond_to?(:call)
+
+      case entry.try(:arity)
+      when 0 then entry.call
+      when 1 then entry.call(scope)
+      else entry.call(scope, user)
+      end
+    end
+
+    def serialize_record(record, computed_attributes = [])
       if record.respond_to?(:as_rhino_json)
-        record.as_rhino_json
+        record.as_rhino_json(computed_attributes: computed_attributes)
       else
         record.as_json
       end
     end
 
-    def serialize_collection(records)
-      records.map { |r| serialize_record(r) }
+    def serialize_collection(records, computed_attributes = [])
+      records.map { |r| serialize_record(r, computed_attributes) }
     end
 
     # ------------------------------------------------------------------

data/lib/rhino/query_builder.rb

@@ -33,6 +33,17 @@ module Rhino
       self
     end
 
+    # Apply only the modifications that define WHICH rows are in the set:
+    # named scope, filters and search. Sorting, sparse fieldsets, includes and
+    # pagination are irrelevant to an aggregate over the collection and are
+    # deliberately skipped — a `select` in particular would break `count`.
+    def build_for_computed
+      apply_named_scope if @named_scopes
+      apply_filters
+      apply_search
+      self
+    end
+
     # Get the final ActiveRecord relation.
     def to_scope
       @scope

data/lib/rhino/routes.rb

@@ -187,6 +187,14 @@ module Rhino
 
                 except_actions = model_class.try(:rhino_except_actions_list) || []
 
+                # The /computed endpoint exists only for models that actually
+                # declare collection-level computed attributes. Models that
+                # don't are byte-for-byte unchanged — in particular
+                # `/{slug}/computed` keeps resolving to show() for a record
+                # whose route key is literally "computed".
+                declared_computed = model_class.try(:rhino_collection_computed_attributes)
+                has_computed = declared_computed.is_a?(Hash) && declared_computed.any?
+
                 route_prefix = [group_prefix, slug.to_s].reject(&:blank?).join("/")
 
                 # Each model's CRUD routes live inside a path scope. When the
@@ -202,6 +210,11 @@ module Rhino
                     post "/", to: "rhino/resources#store", as: "rhino_#{group_name}_#{slug}_store"
                   end
 
+                  # Registered BEFORE the :id routes so the literal segment wins.
+                  if has_computed && !except_actions.include?("computed")
+                    get "computed", to: "rhino/resources#computed", as: "rhino_#{group_name}_#{slug}_computed"
+                  end
+
                   if model_class.try(:uses_soft_deletes?)
                     unless except_actions.include?("trashed")
                       get "trashed", to: "rhino/resources#trashed", as: "rhino_#{group_name}_#{slug}_trashed"

data/lib/rhino/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rhino-rails
 version: !ruby/object:Gem::Version
-  version: 4.6.1
+  version: 4.7.0
 platform: ruby
 authors:
 - Bruno Cipolla