restme_rails 0.1.0

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module RestmeRails
+  module Core
+    module Scope
+      module Paginate
+        # Provides pagination capabilities for scoped queries.
+        #
+        # Supported query parameters:
+        #
+        #   ?page=2
+        #   ?per_page=20
+        #
+        # Configuration defaults:
+        #
+        # - RestmeRails::Configuration.pagination_default_page
+        # - RestmeRails::Configuration.pagination_default_per_page
+        # - RestmeRails::Configuration.pagination_max_per_page
+        #
+        # Pagination is applied using:
+        # - limit
+        # - offset
+        #
+        class Rules
+          attr_reader :context, :scope_error_instance
+
+          def initialize(context:, scope_error_instance:)
+            @context = context
+            @scope_error_instance = scope_error_instance
+          end
+
+          # Applies limit and offset to the given scope.
+          #
+          # @param user_scope [ActiveRecord::Relation]
+          # @return [ActiveRecord::Relation]
+          def process(user_scope)
+            user_scope.limit(per_page).offset(paginate_offset)
+          end
+
+          # Returns current page number.
+          #
+          # Defaults to configured default page if not provided.
+          #
+          # @return [Integer]
+          def page_no
+            context.params[:page]&.to_i || ::RestmeRails::Configuration.pagination_default_page
+          end
+
+          # Calculates total number of pages.
+          #
+          # @param user_scope [ActiveRecord::Relation]
+          # @return [Integer]
+          def pages(user_scope)
+            (total_items(user_scope) / per_page.to_f).ceil
+          end
+
+          # Returns total number of items in the unpaginated scope.
+          #
+          # Memoized per request.
+          #
+          # @param user_scope [ActiveRecord::Relation]
+          # @return [Integer]
+          def total_items(user_scope)
+            @total_items ||= user_scope.size
+          end
+
+          # Validates per_page against maximum allowed value.
+          #
+          # If per_page exceeds:
+          #   pagination_max_per_page
+          #
+          # Registers:
+          # - Error message
+          # - HTTP status :bad_request
+          #
+          # @return [Boolean, nil]
+          def errors
+            return if per_page <= ::RestmeRails::Configuration.pagination_max_per_page
+
+            add_per_page_errors
+
+            true
+          end
+
+          private
+
+          # Returns number of items per page.
+          #
+          # Defaults to configured default if not provided.
+          #
+          # @return [Integer]
+          def per_page
+            context.params[:per_page]&.to_i || ::RestmeRails::Configuration.pagination_default_per_page
+          end
+
+          # Calculates offset based on page and per_page.
+          #
+          # Formula:
+          #   (page - 1) * per_page
+          #
+          # @return [Integer]
+          def paginate_offset
+            (page_no - 1) * per_page
+          end
+
+          def add_per_page_errors
+            scope_error_instance.add_error(
+              {
+                message: "Invalid per page value",
+                body: {
+                  per_page_max_value: ::RestmeRails::Configuration.pagination_max_per_page
+                }
+              }
+            )
+
+            scope_error_instance.add_status(:bad_request)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/restme_rails/core/scope/pipeline.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module RestmeRails
+  module Core
+    module Scope
+      # Executes a sequential pipeline of scope processing steps.
+      #
+      # Each step in the pipeline must respond to:
+      #
+      #   process(scope)
+      #
+      # and return a new ActiveRecord::Relation that will be passed
+      # to the next step in the pipeline.
+      #
+      # Typical pipeline steps include:
+      #
+      # - filtering
+      # - sorting
+      # - pagination
+      # - field selection
+      #
+      # The output of one step becomes the input of the next.
+      #
+      # Example:
+      #
+      #   pipeline = Pipeline.new([
+      #     FilterRules.new(...),
+      #     SortRules.new(...),
+      #     PaginateRules.new(...)
+      #   ])
+      #
+      #   pipeline.call(Product.all)
+      #
+      # @example Pipeline flow
+      #
+      #   initial_scope
+      #     -> filter
+      #     -> sort
+      #     -> paginate
+      #     -> fields
+      #
+      class Pipeline
+        # Initializes the pipeline with a list of processing steps.
+        #
+        # Each step must implement:
+        #
+        #   process(scope)
+        #
+        # @param steps [Array<Object>]
+        #   List of rule instances that will be executed sequentially.
+        def initialize(steps)
+          @steps = steps
+        end
+
+        # Executes the pipeline.
+        #
+        # Each step receives the result of the previous step.
+        #
+        # @param initial_scope [ActiveRecord::Relation]
+        #   The starting relation that will be processed.
+        #
+        # @return [ActiveRecord::Relation]
+        #   The final scope after all steps have been applied.
+        def call(initial_scope)
+          @steps.reduce(initial_scope) do |scope, step|
+            step.process(scope)
+          end
+        end
+
+        # Executes error checks for every pipeline step.
+        #
+        # Each step is expected to expose an `errors` method
+        # that validates parameters or scope rules and registers
+        # errors internally if necessary.
+        #
+        # This method ensures that all validation logic is triggered
+        # before executing the pipeline.
+        #
+        # @return [Array<Object>]
+        #   The list of steps after their error checks have been executed.
+        def check_scope_errors
+          @check_scope_errors ||= @steps.each(&:errors)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+require_relative "filter/rules"
+require_relative "sort/rules"
+require_relative "paginate/rules"
+require_relative "field/rules"
+require_relative "pipeline"
+require_relative "../../rules_find"
+require_relative "../../scope_error"
+
+module RestmeRails
+  module Core
+    module Scope
+      # Provides a complete query scoping pipeline for index/show actions.
+      #
+      # Responsibilities:
+      #
+      # - Role-based user scope resolution
+      # - Filtering
+      # - Sorting
+      # - Pagination
+      # - Field selection
+      # - Error aggregation
+      #
+      # Expected convention:
+      #
+      # A Rules class may exist following the pattern:
+      #   "#{ControllerName}Restme::Scope::Rules"
+      #
+      # Scope methods inside that class must follow:
+      #   "#{role}_scope"
+      #
+      # Example:
+      #   admin_scope
+      #   manager_scope
+      #
+      # Each method must return an ActiveRecord::Relation.
+      #
+      class Rules
+        attr_reader :context, :scope_error_instance
+
+        # Ordered list of rule processors used to build the final scope pipeline.
+        #
+        # The order of these processors is critical because each step
+        # receives the result of the previous one.
+        #
+        # Pipeline order:
+        #
+        # 1. Filter
+        # 2. Sort
+        # 3. Paginate
+        # 4. Field selection
+        #
+        # Changing this order may break expected query behavior.
+        #
+        # @return [Array<Symbol>]
+        PIPELINE_STEPS = [
+          {
+            identifier: :filter_rules,
+            klass: ::RestmeRails::Core::Scope::Filter::Rules
+          },
+          {
+            identifier: :sorte_rules,
+            klass: ::RestmeRails::Core::Scope::Sort::Rules
+          },
+          {
+            identifier: :paginate_rules,
+            klass: ::RestmeRails::Core::Scope::Paginate::Rules
+          },
+          {
+            identifier: :field_rules,
+            klass: ::RestmeRails::Core::Scope::Field::Rules
+          }
+        ].freeze
+
+        def initialize(context:)
+          @context = context
+          @scope_error_instance = RestmeRails::ScopeError.new
+
+          check_scope_errors
+        end
+
+        # Returns paginated response structure.
+        #
+        # Output:
+        # {
+        #   objects: [...],
+        #   pagination: { page:, pages:, total_items: }
+        # }
+        #
+        # If any scope error occurs, returns the error payload instead.
+        #
+        # @return [Hash]
+        def pagination_response
+          @pagination_response ||= (pagination_response_object if scope_errors.blank?)
+        end
+
+        # Returns a single scoped object (first record).
+        #
+        # Used for show-like behavior.
+        #
+        # If any scope error occurs, returns the error payload instead.
+        #
+        # @return [ActiveRecord::Base, Hash, nil]
+        def model_scope_object
+          @model_scope_object ||= (model_scope&.first if scope_errors.blank?)
+        end
+
+        # Returns the HTTP-like status derived from scope errors.
+        #
+        # Delegates to ScopeError instance.
+        #
+        # Example:
+        #   200 -> success
+        #   400 -> invalid query parameters
+        #   403 -> forbidden access
+        #
+        # @return [Integer]
+        def scope_status
+          scope_error_instance.scope_status
+        end
+
+        # Returns the aggregated scope errors collected during rule execution.
+        #
+        # Errors may originate from:
+        #
+        # - filtering
+        # - sorting
+        # - pagination
+        # - field selection
+        #
+        # @return [Array<Hash>]
+        def scope_errors
+          scope_error_instance.scope_errors
+        end
+
+        private
+
+        # Builds paginated response structure.
+        def pagination_response_object
+          {
+            objects: model_scope,
+            pagination: pagination
+          }
+        end
+
+        # Executes all error-checking methods and aggregates errors.
+        #
+        # @return [Array, nil]
+        def check_scope_errors
+          @check_scope_errors ||= pipeline.check_scope_errors
+        end
+
+        # Final composed ActiveRecord::Relation.
+        #
+        # @return [ActiveRecord::Relation]
+        def model_scope
+          @model_scope ||= final_scope
+        end
+
+        # Pagination metadata.
+        #
+        # @return [Hash]
+        def pagination
+          {
+            page: @paginate_rules.page_no,
+            pages: @paginate_rules.pages(@filter_rules.scope),
+            total_items: @paginate_rules.total_items(@filter_rules.scope)
+          }
+        end
+
+        # Complete query pipeline:
+        #
+        # 1. Resolve user scope
+        # 2. Apply filtering
+        # 3. Apply sorting
+        # 4. Apply pagination
+        # 5. Apply field selection
+        #
+        # @return [ActiveRecord::Relation]
+        def final_scope
+          @final_scope ||= pipeline.call(user_scope)
+        end
+
+        def pipeline
+          @pipeline ||= begin
+            steps = PIPELINE_STEPS.map do |pipeline|
+              instance = pipeline[:klass].new(context: context, scope_error_instance: scope_error_instance)
+
+              instance_variable_name = pipeline[:identifier]
+
+              instance_variable_set(:"@#{instance_variable_name}", instance)
+            end
+
+            Pipeline.new(steps)
+          end
+        end
+
+        # Resolves base scope based on user roles.
+        #
+        # Strategy:
+        #
+        # - If no user: returns all records
+        # - If role scope methods exist: combine them using OR
+        # - If multiple scopes: ensures distinct results
+        # - If no matching scope: returns none
+        #
+        # @return [ActiveRecord::Relation]
+        def user_scope
+          @user_scope ||= none_user_scope || process_user_scope || none_scope
+        end
+
+        # Executes all matching role scope methods
+        # and combines them using `or`.
+        #
+        # @return [ActiveRecord::Relation, nil]
+        def process_user_scope
+          scopes = user_scope_methods.map { |m| scope_rules_class_instance.try(m) }
+
+          processed_scope = scopes.reduce { |combined, s| combined.or(s) }
+
+          user_scope_methods.many? ? processed_scope&.distinct : processed_scope
+        end
+
+        # Returns valid scope methods based on user roles.
+        #
+        # Example:
+        #   admin_scope
+        #   manager_scope
+        #
+        # @return [Array<Symbol>]
+        def user_scope_methods
+          @user_scope_methods ||=
+            methods_scopes.select do |method_scope|
+              scope_rules_class_instance.respond_to?(method_scope)
+            end
+        end
+
+        # If no user is present, returns full dataset.
+        #
+        # @return [ActiveRecord::Relation, nil]
+        def none_user_scope
+          context.model_class.all if context.current_user.blank?
+        end
+
+        # Fallback when no role scope matches.
+        #
+        # @return [ActiveRecord::Relation]
+        def none_scope
+          context.model_class.none
+        end
+
+        # Builds scope method names from roles.
+        #
+        # Example:
+        #   :admin -> "admin_scope"
+        #
+        # @return [Array<String>]
+        def methods_scopes
+          @methods_scopes ||= context.current_user_roles.map do |role|
+            "#{role}_scope"
+          end
+        end
+
+        # Lazily instantiates the dynamic Scope Rules class.
+        #
+        # The class is resolved using the Restme convention system
+        # and initialized with:
+        #
+        #   (model_class, current_user, params)
+        #
+        # This class is responsible for defining role-based scopes,
+        # such as:
+        #
+        #   admin_scope
+        #   manager_scope
+        #
+        # @return [Object, nil]
+        def scope_rules_class_instance
+          @scope_rules_class_instance ||= scope_rules_class&.new(
+            context.model_class,
+            context.current_user,
+            context.params
+          )
+        end
+
+        # Instantiates the Scope Rules class dynamically.
+        #
+        # Naming convention:
+        #   "#{ControllerName}Restme::Scope::Rules"
+        #
+        # Initialized with:
+        #   (model_class, current_user, params)
+        #
+        # @return [Object]
+        def scope_rules_class
+          @scope_rules_class ||=
+            RestmeRails::RulesFind.new(klass: context.model_class, rule_context: "Scope").rule_class
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module RestmeRails
+  module Core
+    module Scope
+      module Sort
+        # Provides sorting capabilities based on query string parameters.
+        #
+        # Expected query format:
+        #
+        #   GET /products?name_sort=asc&price_sort=desc
+        #
+        # Pattern:
+        #   "#{field}_sort" => "asc" | "desc"
+        #
+        # Rules:
+        #
+        # - Sorting is applied only for GET requests.
+        # - Direction defaults to "asc" if invalid.
+        # - Only fields declared in `klass::SORTABLE_FIELDS` are allowed.
+        # - :id is always allowed.
+        #
+        class Rules
+          ID = :id
+          SORT_KEY = "sort"
+          SORTABLE_TYPES = %w[asc desc].freeze
+
+          attr_reader :context, :scope_error_instance
+
+          def initialize(context:, scope_error_instance:)
+            @context = context
+            @scope_error_instance = scope_error_instance
+          end
+
+          # Applies ordering to the given scope if sorting is valid.
+          #
+          # @param user_scope [ActiveRecord::Relation]
+          # @return [ActiveRecord::Relation]
+          def process(user_scope)
+            return user_scope unless sortable_scope?
+
+            user_scope.order(serialize_sort_params)
+          end
+
+          # Registers error if unknown sortable fields are detected.
+          #
+          # Sets:
+          # - Error message
+          # - HTTP status :bad_request
+          #
+          # @return [Boolean, nil]
+          def errors
+            return unless unknown_sortable_fields.present?
+
+            scope_error_instance.add_error(
+              {
+                message: "Unknown Sort",
+                body: unknown_sortable_fields
+              }
+            )
+
+            scope_error_instance.add_status(:bad_request)
+
+            true
+          end
+
+          private
+
+          # Determines whether sorting should be applied.
+          #
+          # Sorting is applied only if:
+          # - HTTP method is GET
+          # - At least one sortable field is present
+          #
+          # @return [Boolean]
+          def sortable_scope?
+            context.request.get? && controller_params_sortable_fields.present?
+          end
+
+          # Converts query parameters into an ActiveRecord-compatible
+          # order structure.
+          #
+          # Example:
+          #   { "name_sort" => "asc" }
+          # becomes:
+          #   { name: "asc" }
+          #
+          # Invalid directions default to "asc".
+          #
+          # @return [Array<Hash>]
+          def serialize_sort_params
+            @serialize_sort_params ||= controller_params_sortable_fields.map do |key, value|
+              key = key.to_s.gsub("_#{SORT_KEY}", "")
+
+              value = "asc" unless SORTABLE_TYPES.include?(value&.downcase)
+
+              { key.to_sym => value&.downcase }
+            end
+          end
+
+          # Extracts sortable parameters from query string.
+          #
+          # Only keys ending with "_sort" are considered.
+          #
+          # @return [Hash]
+          def controller_params_sortable_fields
+            @controller_params_sortable_fields ||= context.query_params.select do |key, _|
+              key.to_s.end_with?(SORT_KEY)
+            end
+          end
+
+          # Returns fields requested for sorting that are not allowed.
+          #
+          # @return [Array<Symbol>]
+          def unknown_sortable_fields
+            @unknown_sortable_fields ||=
+              serialize_sort_params.map { |sort_param| sort_param.first.first } - sortable_fields
+          end
+
+          # Returns allowed sortable fields.
+          #
+          # Reads from:
+          #   klass::SORTABLE_FIELDS
+          #
+          # :id is always allowed.
+          #
+          # If constant is not defined, defaults to [:id].
+          #
+          # @return [Array<Symbol>]
+          def sortable_fields
+            @sortable_fields ||=
+              if context.model_class.const_defined?(:SORTABLE_FIELDS)
+                Array.new(context.model_class::SORTABLE_FIELDS).push(ID)
+              else
+                [ID]
+              end
+          end
+        end
+      end
+    end
+  end
+end