restme_rails 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4076bb59cd881f2ed821c909c6b3d17d121ce0f84a31f428ad75583ea8f18d9b
-  data.tar.gz: ed9fdb887e8c91055f444f2def7e1a9d08f266ca1b15a657cb483600f722c8c5
+  metadata.gz: 0ca56c1c05d82ce70341d77bc32b9ababe1330b77d00b8dff144d9fc42e3b0f8
+  data.tar.gz: 6d78d32795f8f6325b1737d91dd921949f7d890d0d69379faa49a374ffbc2c56
 SHA512:
-  metadata.gz: 2d516b60990e0d811d10739113f8a279cea2b9e09ddbc0ad53304d8c25968a47df014325fcdf6ca92f3484a08ab3e3caf4316f60992021e48e2e0500e241a524
-  data.tar.gz: 355471605a9dec6d37439587f28f7ac28f3859ca895488637e1a49f49128f21431a0ea497de7ecbd4d4c46c14e507b6e1c09399bb24095197347b87078b5a238
+  metadata.gz: a3edf6726a7c7e86739b3747e439aacf22995b5405ce305b3fd9b5b716df88c5dd53367436a212ca3fec92986cec712a000947396804bb59861d6964d67f5b57
+  data.tar.gz: cfc97baaa14c175b425f72d07117d05d1e0e85aaa08c9b9d7fc0b9881527c1aa296165ec19b78c8ee3688f6bfafc88ac4b98a237e1e804477b7ae0b162939572

data/lib/restme_rails/core/authorize/rules.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "../../rules_find"
-
 module RestmeRails
   module Core
     module Authorize
@@ -15,28 +13,23 @@ module RestmeRails
       #
       # 1. If there is no current user → access is allowed.
       # 2. If the current user's roles intersect with allowed roles
-      #    for the action → access is allowed.
+      #    declared via restme_authorize_action DSL → access is allowed.
       # 3. Otherwise → raises NotAuthorizedError.
       #
       # ------------------------------------------------------------
       # Expected Convention
       # ------------------------------------------------------------
       #
-      # A rules class may exist following the naming convention:
-      #
-      #   "#{ModelName}Rules::Authorize::Rules"
+      # Roles are declared on the controller class using the DSL:
       #
-      # Example:
+      #   class ProductsController < ApplicationController
+      #     include RestmeRails
       #
-      #   class ProductRules::Authorize::Rules
-      #     ALLOWED_ROLES_ACTIONS = {
-      #       index:  [:admin, :manager],
-      #       create: [:admin]
-      #     }
+      #     restme_authorize_action :index,  %i[admin manager]
+      #     restme_authorize_action :create, %i[admin]
+      #     restme_authorize_action %i[index show], %i[admin manager]
       #   end
       #
-      # Each controller action maps to an array of allowed roles.
-      #
       class Rules
         attr_reader :context
 
@@ -65,27 +58,11 @@ module RestmeRails
           allowed_roles_for_action.intersect?(context.current_user_roles)
         end
 
-        # Returns allowed roles for current action.
-        #
-        # If no rules class or constant exists, defaults to empty array.
+        # Returns allowed roles for current action from the controller DSL.
         #
         # @return [Array<Symbol>]
         def allowed_roles_for_action
-          return [] unless rules_class&.const_defined?(:ALLOWED_ROLES_ACTIONS)
-
-          rules_class::ALLOWED_ROLES_ACTIONS[context.action_name] || []
-        end
-
-        # Dynamically resolves authorization rules class.
-        #
-        # Uses RestmeRails::RulesFind to follow naming convention.
-        #
-        # @return [Class, nil]
-        def rules_class
-          @rules_class ||= RestmeRails::RulesFind.new(
-            klass: context.model_class,
-            rule_context: "Authorize"
-          ).rule_class
+          context.controller_class.restme_authorize_actions[context.action_name] || []
         end
       end
     end

data/lib/restme_rails/core/create/rules.rb

@@ -99,10 +99,8 @@ module RestmeRails
                       nil
                     elsif !scope_allowed?
                       unscoped_errors
-                    elsif instance.valid?
-                      nil
                     else
-                      active_record_errors
+                      instance.valid? ? nil : active_record_errors
                     end
         end
 

data/lib/restme_rails/core/scope/field/rules.rb

@@ -1,101 +1,74 @@
 # frozen_string_literal: true
 
-require_relative "attachable"
-require_relative "../../../rules_find"
+require_relative "select_fields"
+require_relative "select_nested_fields"
+require_relative "select_attachments"
 
 module RestmeRails
   module Core
     module Scope
       module Field
-        # Handles field selection logic for scoped queries.
+        # Orchestrates field selection for scoped queries.
         #
-        # Responsibilities:
+        # Delegates each concern to a focused class:
         #
-        # - Filters model attributes based on:
-        #     - fields_select
-        #     - nested_fields_select
-        #     - MODEL_FIELDS_SELECT (whitelist)
-        #     - UNALLOWED_MODEL_FIELDS_SELECT (blacklist)
-        #
-        # - Validates unallowed field selections
-        # - Applies nested preloads
-        # - Delegates attachment handling to Attachable
+        #   SelectFields        → model attribute selection (fields_select)
+        #   SelectNestedFields  → association preloading (nested_fields_select)
+        #   SelectAttachments   → attachment URL injection (attachment_fields_select)
         #
         # Query params supported:
         #
         #   ?fields_select=id,name,email
         #   ?nested_fields_select=profile,company
+        #   ?nested_fields_select[profile]=id,name&nested_fields_select[company]=id
         #   ?attachment_fields_select=avatar
         #
-        # Expected convention:
-        #
-        # A Field Rules class may exist following:
-        #
-        #   "#{ModelName}Restme::Field::Rules"
-        #
-        # It may define:
-        #
-        #   MODEL_FIELDS_SELECT = [:id, :name]
-        #   UNALLOWED_MODEL_FIELDS_SELECT = [:internal_token]
-        #   NESTED_SELECTABLE_FIELDS = { profile: {}, company: {} }
-        #
         class Rules
-          attr_reader :context, :scope_error_instance, :attachable_instance
+          attr_reader :context, :scope_error_instance
 
           # @param context [RestmeRails::Context]
           # @param scope_error_instance [ScopeError]
           def initialize(context:, scope_error_instance:)
             @context = context
             @scope_error_instance = scope_error_instance
-
-            @attachable_instance = RestmeRails::Core::Scope::Field::Attachable.new(
-              context: context,
-              attachment_fields_select: attachment_fields_select,
-              valid_nested_fields_select: valid_nested_fields_select,
-              scope_error_instance: scope_error_instance
-            )
           end
 
-          # Applies field selection rules to a given scope.
+          # Applies field selection pipeline to the given scope.
           #
           # Flow:
-          # 1. Selects allowed model attributes
-          # 2. Applies nested preloads
-          # 3. Applies attachment serialization
+          # 1. Applies SELECT clause for model attributes
+          # 2. Preloads nested associations
+          # 3. Serializes to JSON with attachment URLs injected
           #
           # @param user_scope [ActiveRecord::Relation]
-          # @return [ActiveRecord::Relation, Array<Hash>]
+          # @return [Array<Hash>]
           def process(user_scope)
-            return user_scope unless select_any_field?
-
-            scoped = user_scope
-
-            scoped = user_scope.select(model_fields_select) if model_fields_select
-            scoped = select_nested_scope(scoped) if valid_nested_fields_select
-
-            attachable_instance.insert_attachments(scoped)
+            scoped = select_fields.process(user_scope)
+            scoped = select_nested_fields.process(scoped)
+            select_attachments.process(scoped)
           rescue ActiveModel::MissingAttributeError => e
             raise RestmeRails::MissingAttributeError, e.message
           end
 
-          # Registers errors from field and field attachment
+          # Validates field selections and registers errors on scope_error_instance.
           #
           # @return [Boolean, nil]
           def errors
-            unallowed_select_fields_errors
-            unallowed_attachment_fields_errors
+            unallowed_select_fields_errors || select_attachments.errors
           end
 
           private
 
-          # Registers error if client selects invalid fields.
+          # Combines unallowed model fields and nested associations into a
+          # single error entry to preserve the original error format.
           #
           # @return [Boolean, nil]
           def unallowed_select_fields_errors
-            return if unallowed_fields_selected.blank?
+            unallowed = select_nested_fields.unallowed + select_fields.unallowed
+            return if unallowed.blank?
 
             scope_error_instance.add_error(
-              body: unallowed_fields_selected,
+              body: unallowed,
               message: "Selected not allowed fields"
             )
 
@@ -104,167 +77,20 @@ module RestmeRails
             true
           end
 
-          # Delegates attachment validation to Attachable.
-          #
-          # @return [void]
-          def unallowed_attachment_fields_errors
-            attachable_instance.unallowed_attachment_fields_errors
-          end
-
-          # Registers ActiveModel::MissingAttributeError
-          #
-          # @return [void]
-          def add_scope_error(message)
-            scope_error_instance.add_error(
-              body: model_fields_select,
-              message: message
-            )
-
-            scope_error_instance.add_status(:bad_request)
-          end
-
-          # Applies nested association preloads.
-          #
-          # @param scoped [ActiveRecord::Relation]
-          # @return [ActiveRecord::Relation]
-          def select_nested_scope(scoped)
-            scoped.preload(valid_nested_fields_select)
-          end
-
-          # Determines whether any field selection param exists.
-          #
-          # @return [Boolean]
-          def select_any_field?
-            defined_fields_select ||
-              fields_select ||
-              nested_fields_select ||
-              attachment_fields_select
-          end
-
-          # Final model fields to select.
-          #
-          # If client specifies fields_select, merge with defined whitelist.
-          # Otherwise fallback to all allowed attributes.
-          #
-          # @return [Array<String>]
-          def model_fields_select
-            @model_fields_select ||= select_selected_fields.presence || model_attributes
-          end
-
-          # Merges whitelist + client selection.
-          #
-          # @return [Array<String>]
-          def select_selected_fields
-            @select_selected_fields ||= defined_fields_select |
-                                        fields_select.split(",").map(&:to_s)
-          end
-
-          # Returns allowed model attributes excluding blacklisted ones.
-          #
-          # @return [Array<String>]
-          def model_attributes
-            @model_attributes ||= context.model_class.attribute_names -
-                                  unallowed_model_fields_select
-          end
-
-          # Fields explicitly defined via MODEL_FIELDS_SELECT.
-          #
-          # @return [Array<String>]
-          def defined_fields_select
-            return [] unless field_class_rules&.const_defined?(:MODEL_FIELDS_SELECT)
-
-            (field_class_rules::MODEL_FIELDS_SELECT || []).map(&:to_s)
-          end
-
-          # Fields blacklisted via UNALLOWED_MODEL_FIELDS_SELECT.
-          #
-          # @return [Array<String>]
-          def unallowed_model_fields_select
-            return [] unless field_class_rules&.const_defined?(:UNALLOWED_MODEL_FIELDS_SELECT)
-
-            (field_class_rules::UNALLOWED_MODEL_FIELDS_SELECT || []).map(&:to_s)
-          end
-
-          # Valid nested associations based on whitelist.
-          #
-          # @return [Array<Symbol>, nil]
-          def valid_nested_fields_select
-            @valid_nested_fields_select ||= nested_fields_select
-                                            &.split(",")
-                                            &.select { |field| nested_selectable_fields_keys.key?(field.to_sym) }
-                                            &.map(&:to_sym)
-          end
-
-          # Aggregates all invalid selections.
-          #
-          # @return [Array<Symbol>]
-          def unallowed_fields_selected
-            unallowed_nested_fields_select + unallowed_fields_select
-          end
-
-          # Nested associations not allowed.
-          #
-          # @return [Array<Symbol>]
-          def unallowed_nested_fields_select
-            return [] if nested_fields_select.blank?
-
-            nested_fields_select.split(",").map(&:to_sym) -
-              valid_nested_fields_select
-          end
-
-          # Model attributes not allowed.
-          #
-          # @return [Array<Symbol>]
-          def unallowed_fields_select
-            return [] if fields_select.blank?
-
-            fields_select.split(",").map(&:to_sym) -
-              model_attributes.map(&:to_sym)
-          end
-
-          # Query param: fields_select
-          #
-          # @return [String]
-          def fields_select
-            @fields_select ||= context.query_params[:fields_select] || ""
-          end
-
-          # Query param: nested_fields_select
-          #
-          # @return [String, nil]
-          def nested_fields_select
-            @nested_fields_select ||= context.query_params[:nested_fields_select]
+          def select_fields
+            @select_fields ||= SelectFields.new(context: context)
           end
 
-          # Query param: attachment_fields_select
-          #
-          # @return [Array<Symbol>, nil]
-          def attachment_fields_select
-            @attachment_fields_select ||= context.query_params[:attachment_fields_select]
-                                                 &.split(",")
-                                                 &.map(&:to_sym)
-          end
-
-          # Returns allowed nested associations defined in rules.
-          #
-          # @return [Hash, nil]
-          def nested_selectable_fields_keys
-            @nested_selectable_fields_keys ||= if field_class_rules&.const_defined?(:NESTED_SELECTABLE_FIELDS)
-                                                 field_class_rules::NESTED_SELECTABLE_FIELDS
-                                               end
+          def select_nested_fields
+            @select_nested_fields ||= SelectNestedFields.new(context: context)
           end
 
-          # Dynamically resolves Field Rules class.
-          #
-          # Uses:
-          #   RestmeRails::RulesFind
-          #
-          # @return [Class, nil]
-          def field_class_rules
-            @field_class_rules ||= RestmeRails::RulesFind.new(
-              klass: context.model_class,
-              rule_context: "Field"
-            ).rule_class
+          def select_attachments
+            @select_attachments ||= SelectAttachments.new(
+              context: context,
+              scope_error_instance: scope_error_instance,
+              valid_nested_fields_select: select_nested_fields.valid_nested_fields_select
+            )
           end
         end
       end

data/lib/restme_rails/core/scope/field/select_attachments.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module RestmeRails
+  module Core
+    module Scope
+      module Field
+        # Handles ActiveStorage attachment serialization for scoped queries.
+        #
+        # Responsibilities:
+        #
+        # - Validates requested attachment fields against the model
+        # - Preloads attachment blobs to avoid N+1
+        # - Injects *_url fields into the serialized JSON output
+        # - Applies nested field restrictions via as_json options
+        #
+        # Important:
+        # This class does NOT dynamically define methods on the model.
+        # Attachment URLs are injected directly into the serialized hash.
+        #
+        # Query param:
+        #
+        #   ?attachment_fields_select=avatar,cover
+        #
+        # Response:
+        #
+        #   { avatar_url: "https://...", cover_url: "https://..." }
+        #
+        class SelectAttachments
+          # @param context [RestmeRails::Context]
+          # @param scope_error_instance [RestmeRails::ScopeError]
+          # @param valid_nested_fields_select [Hash, nil]
+          def initialize(context:, scope_error_instance:, valid_nested_fields_select:)
+            @context = context
+            @scope_error_instance = scope_error_instance
+            @valid_nested_fields_select = valid_nested_fields_select
+          end
+
+          # Serializes the scope to JSON, injecting attachment URLs when requested.
+          #
+          # @param scope [ActiveRecord::Relation]
+          # @return [Array<Hash>]
+          def process(scope)
+            return scope.as_json(json_options) if attachment_fields_select.blank?
+
+            records = scope.includes(attachment_includes)
+
+            serialize_with_attachments(records)
+          end
+
+          # Registers a bad_request error for attachment fields that do not
+          # exist in the model's attachment_reflections.
+          #
+          # @return [void]
+          def errors
+            return if unallowed_attachment_fields.blank?
+
+            scope_error_instance.add_error(
+              body: unallowed_attachment_fields,
+              message: "Selected not allowed attachment fields"
+            )
+
+            scope_error_instance.add_status(:bad_request)
+          end
+
+          private
+
+          attr_reader :context, :scope_error_instance, :valid_nested_fields_select
+
+          # Base as_json options including nested field restrictions.
+          #
+          # @return [Hash]
+          def json_options
+            { include: nested_include_options }
+          end
+
+          # Builds the include: hash for as_json with optional field restriction.
+          #
+          # Examples:
+          #   { profile: nil, company: [:id, :name] }
+          #   → { profile: {}, company: { only: [:id, :name] } }
+          #
+          # @return [Hash]
+          def nested_include_options
+            return {} if valid_nested_fields_select.blank?
+
+            valid_nested_fields_select.transform_values do |fields|
+              fields ? { only: fields } : {}
+            end
+          end
+
+          # Serializes records and injects attachment URLs into each hash.
+          #
+          # Only fields present in model_attachment_fields are dispatched via
+          # public_send, regardless of pipeline call order.
+          #
+          # @param records [ActiveRecord::Relation]
+          # @return [Array<Hash>]
+          def serialize_with_attachments(records)
+            allowed_fields = attachment_fields_select & model_attachment_fields
+
+            records.map do |record|
+              base_hash = record.as_json(json_options)
+
+              allowed_fields.each do |field|
+                attachment = record.public_send(field)
+                base_hash["#{field}_url"] = attachment&.attached? ? attachment.url : nil
+              end
+
+              base_hash
+            end
+          end
+
+          # Builds the includes structure for ActiveStorage eager loading.
+          #
+          # Example: [:avatar] → [{ avatar_attachment: :blob }]
+          #
+          # @return [Array<Hash>]
+          def attachment_includes
+            attachment_fields_select.map do |field|
+              { "#{field}_attachment": :blob }
+            end
+          end
+
+          # All attachment names declared in the model via has_one_attached / has_many_attached.
+          #
+          # @return [Array<Symbol>]
+          def model_attachment_fields
+            @model_attachment_fields ||= context.model_class
+                                                .attachment_reflections
+                                                .map { |_name, reflection| reflection.name }
+          end
+
+          # Attachment fields requested but not present in the model.
+          #
+          # @return [Array<Symbol>]
+          def unallowed_attachment_fields
+            return [] if attachment_fields_select.blank?
+
+            attachment_fields_select - model_attachment_fields
+          end
+
+          # Query param: attachment_fields_select
+          #
+          # @return [Array<Symbol>, nil]
+          def attachment_fields_select
+            @attachment_fields_select ||= context.query_params[:attachment_fields_select]
+                                                 &.split(",")
+                                                 &.map(&:to_sym)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/restme_rails/core/scope/field/select_fields.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require_relative "../../../rules_find"
+
+module RestmeRails
+  module Core
+    module Scope
+      module Field
+        # Handles model attribute selection for scoped queries.
+        #
+        # Responsibilities:
+        #
+        # - Applies SELECT clause based on requested and allowed fields
+        # - Merges whitelist (MODEL_FIELDS_SELECT) with client selection
+        # - Enforces blacklist (UNALLOWED_MODEL_FIELDS_SELECT)
+        # - Exposes unallowed selections for error aggregation in Rules
+        #
+        # Query param:
+        #
+        #   ?fields_select=id,name,email
+        #
+        # Convention — optional class per model:
+        #
+        #   "#{ModelName}Restme::Field::Rules"
+        #
+        # May define:
+        #
+        #   MODEL_FIELDS_SELECT          = [:id, :name]
+        #   UNALLOWED_MODEL_FIELDS_SELECT = [:internal_token]
+        #
+        class SelectFields
+          # @param context [RestmeRails::Context]
+          def initialize(context:)
+            @context = context
+          end
+
+          # Applies SELECT clause to the scope.
+          #
+          # @param scope [ActiveRecord::Relation]
+          # @return [ActiveRecord::Relation]
+          def process(scope)
+            scope.select(model_fields_select)
+          end
+
+          # Fields that were requested but are not allowed.
+          # Used by Rules to build a single combined error.
+          #
+          # @return [Array<Symbol>]
+          def unallowed
+            return [] if fields_select.blank?
+
+            fields_select.split(",").map(&:to_sym) - model_attributes.map(&:to_sym)
+          end
+
+          # Final list of model fields to apply in SELECT.
+          #
+          # Merges whitelist with client selection, falling back to all
+          # allowed attributes when no explicit selection is made.
+          #
+          # @return [Array<String>]
+          def model_fields_select
+            @model_fields_select ||= select_selected_fields.presence || model_attributes
+          end
+
+          private
+
+          attr_reader :context
+
+          # Merges whitelist + client selection.
+          #
+          # @return [Array<String>]
+          def select_selected_fields
+            @select_selected_fields ||= defined_fields_select |
+                                        fields_select.split(",").map(&:to_s)
+          end
+
+          # All model column names excluding blacklisted fields.
+          #
+          # @return [Array<String>]
+          def model_attributes
+            @model_attributes ||= context.model_class.attribute_names -
+                                  unallowed_model_fields_select
+          end
+
+          # Fields whitelisted via MODEL_FIELDS_SELECT.
+          #
+          # @return [Array<String>]
+          def defined_fields_select
+            return [] unless field_class_rules&.const_defined?(:MODEL_FIELDS_SELECT)
+
+            (field_class_rules::MODEL_FIELDS_SELECT || []).map(&:to_s)
+          end
+
+          # Fields blacklisted via UNALLOWED_MODEL_FIELDS_SELECT.
+          #
+          # @return [Array<String>]
+          def unallowed_model_fields_select
+            return [] unless field_class_rules&.const_defined?(:UNALLOWED_MODEL_FIELDS_SELECT)
+
+            (field_class_rules::UNALLOWED_MODEL_FIELDS_SELECT || []).map(&:to_s)
+          end
+
+          # Query param: fields_select
+          #
+          # @return [String]
+          def fields_select
+            @fields_select ||= context.query_params[:fields_select] || ""
+          end
+
+          # Dynamically resolves the Field Rules class for the model.
+          #
+          # @return [Class, nil]
+          def field_class_rules
+            @field_class_rules ||= RestmeRails::RulesFind.new(
+              klass: context.model_class,
+              rule_context: "Field"
+            ).rule_class
+          end
+        end
+      end
+    end
+  end
+end