restme_rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7e6838473f0e4d6088c4d2b7684d3dbff5c7dc83ecaed65c72698f92b29ad603
+  data.tar.gz: 4c235119e87160cccbef952b9245f4f3794f30aa60d70bc01e60bacf92506cb0
+SHA512:
+  metadata.gz: 1958a3cfdc5a666eb565daac932e3dbaefea77446da53a49862c8a2bef071876dbc7195e286d69563911aaf789424b2c83a09f9aa12f20b93f840b0c0eccd684
+  data.tar.gz: 5e522994f16bf5f7f6211f368ed48d0a382c582ac3864772a403de6cd349210d398c521d844f43f712f27c00690d2127f525d15d632be1783b4653add91e82d1

data/README.md

@@ -0,0 +1,43 @@
+# RestmeRails
+
+TODO: Delete this and the text below, and describe your gem
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/restme_rails`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+## Installation
+
+TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/restme_rails. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/restme_rails/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the RestmeRails project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/restme_rails/blob/master/CODE_OF_CONDUCT.md).

data/lib/restme_rails/adapters/controller_adapter.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module RestmeRails
+  module Adapters
+    # Adapter responsible for abstracting a Rails controller.
+    #
+    # This class isolates direct dependencies on ActionController,
+    # allowing the rest of the gem to interact with a normalized
+    # controller interface.
+    #
+    # By using this adapter, the gem avoids tight coupling with
+    # Rails internals and makes testing significantly easier.
+    #
+    # Example usage:
+    #
+    #   adapter = RestmeRails::Rails::ControllerAdapter.new(controller)
+    #
+    #   adapter.params
+    #   adapter.query_params
+    #   adapter.action_name
+    #
+    # @note This adapter assumes an ActionController-compatible object.
+    #
+    class ControllerAdapter
+      # @return [ActionController::Base]
+      #   The underlying Rails controller instance.
+      attr_reader :controller
+
+      # @param controller [ActionController::Base]
+      #   The controller instance to be wrapped.
+      def initialize(controller)
+        @controller = controller
+      end
+
+      # Returns request parameters.
+      #
+      # @return [ActionController::Parameters]
+      def params
+        controller.params
+      end
+
+      # Returns URL query parameters as a symbolized Hash.
+      #
+      # Example:
+      #   GET /products?name=foo
+      #   => { name: "foo" }
+      #
+      # @return [Hash]
+      def query_params
+        return {} unless controller.respond_to?(:request)
+
+        controller.request.query_parameters.deep_symbolize_keys
+      end
+
+      # Returns the underlying request object.
+      #
+      # @return [ActionDispatch::Request]
+      def request
+        controller.request
+      end
+
+      # Returns the current action name.
+      #
+      # @return [String]
+      def action_name
+        controller.action_name
+      end
+
+      # Returns the controller class.
+      #
+      # @return [Class]
+      def controller_class
+        controller.class
+      end
+    end
+  end
+end

data/lib/restme_rails/configuration.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module RestmeRails
+  # Defines the initialization configuration for RestmeRails gem
+  module Configuration
+    @current_user_variable = :current_user
+    @user_role_field = :role
+    @pagination_default_per_page = 12
+    @pagination_default_page = 1
+    @pagination_max_per_page = 100
+
+    class << self
+      attr_accessor :current_user_variable,
+                    :user_role_field,
+                    :pagination_default_per_page,
+                    :pagination_default_page,
+                    :pagination_max_per_page
+    end
+  end
+end

data/lib/restme_rails/context.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative "model_finder"
+require_relative "params_serializer"
+require_relative "user_roles_resolver"
+
+module RestmeRails
+  # Context object responsible for encapsulating all request-level
+  # information required by Restme rule engines.
+  #
+  # This class acts as a boundary between Rails controllers and
+  # the internal rule system of the gem.
+  #
+  # It extracts and normalizes:
+  # - Request parameters
+  # - Query parameters
+  # - Current user
+  # - User roles
+  # - Model class
+  # - Action name
+  #
+  # The goal is to avoid tight coupling between rules and
+  # ActionController directly.
+  #
+  # @example
+  #   context = RestmeRails::Context.new(
+  #     user: current_user,
+  #     controller: ControllerAdapter.new(self)
+  #   )
+  #
+  #   context.model_class
+  #   # => Product
+  #
+  #   context.action_name
+  #   # => :create
+  #
+  class Context
+    # @return [Object]
+    #   Adapter wrapping the Rails controller.
+    attr_reader :controller_adapter
+
+    # @param user [Object, nil]
+    #   Current authenticated user.
+    #
+    # @param controller [ControllerAdapter]
+    #   Adapter object that abstracts ActionController.
+    def initialize(user:, controller:)
+      @user = user
+      @controller_adapter = controller
+    end
+
+    # Returns normalized and serialized controller params.
+    #
+    # Behavior:
+    # - Removes :controller and :action keys
+    # - Permits all parameters (no strong params enforcement here)
+    # - Extracts nested params under model key
+    #   Example:
+    #     { product: { name: "Book" } }
+    # - Deep symbolized keys
+    #
+    # @return [Hash]
+    def controller_params_serialized
+      @controller_params_serialized ||= params_serializer_instance.params_serialized
+    end
+
+    # Raw params from controller
+    #
+    # @return [ActionController::Parameters, Hash]
+    def params
+      params_serializer_instance.params
+    end
+
+    # Query string parameters only
+    #
+    # @return [Hash]
+    def query_params
+      params_serializer_instance.query_params
+    end
+
+    # Request object
+    #
+    # @return [ActionDispatch::Request]
+    def request
+      controller_adapter.request
+    end
+
+    # Controller class
+    #
+    # @return [Class]
+    def controller_class
+      controller_adapter.controller_class
+    end
+
+    # Model class inferred from controller
+    #
+    # @return [Class]
+    def model_class
+      RestmeRails::ModelFinder
+        .new(controller_class: controller_class)
+        .model_class
+    end
+
+    # Action name symbol
+    #
+    # @return [Symbol]
+    def action_name
+      controller_adapter.action_name.to_sym
+    end
+
+    # Current authenticated user
+    #
+    # @return [Object, nil]
+    def current_user
+      @user
+    end
+
+    def current_user_roles
+      ::RestmeRails::UserRolesResolver.new(current_user: current_user).current_user_roles
+    end
+
+    private
+
+    def params_serializer_instance
+      @params_serializer_instance ||= ParamsSerializer.new(controller: controller_adapter, model_class: model_class)
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "../../rules_find"
+
+module RestmeRails
+  module Core
+    module Authorize
+      # Core::Authorize::Rules
+      #
+      # Provides a lightweight role-based authorization layer.
+      #
+      # ------------------------------------------------------------
+      # Authorization Strategy
+      # ------------------------------------------------------------
+      #
+      # 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.
+      # 3. Otherwise → raises NotAuthorizedError.
+      #
+      # ------------------------------------------------------------
+      # Expected Convention
+      # ------------------------------------------------------------
+      #
+      # A rules class may exist following the naming convention:
+      #
+      #   "#{ModelName}Rules::Authorize::Rules"
+      #
+      # Example:
+      #
+      #   class ProductRules::Authorize::Rules
+      #     ALLOWED_ROLES_ACTIONS = {
+      #       index:  [:admin, :manager],
+      #       create: [:admin]
+      #     }
+      #   end
+      #
+      # Each controller action maps to an array of allowed roles.
+      #
+      class Rules
+        attr_reader :context
+
+        # @param context [RestmeRails::Context]
+        def initialize(context:)
+          @context = context
+        end
+
+        # Performs authorization check.
+        #
+        # @raise [NotAuthorizedError] if user is not authorized
+        # @return [true] if authorized
+        def authorize!
+          return true if context.current_user.blank?
+          return true if authorized?
+
+          raise RestmeRails::NotAuthorizedError, "You are not allowed to access this resource"
+        end
+
+        private
+
+        # Checks if user roles intersect allowed roles for action.
+        #
+        # @return [Boolean]
+        def authorized?
+          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.
+        #
+        # @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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require_relative "../../rules_find"
+
+module RestmeRails
+  module Core
+    module Create
+      # Provides a standardized create flow with:
+      #
+      # - Automatic model instantiation
+      # - Role-based scope validation
+      # - Optional Rules class integration
+      # - Error normalization
+      #
+      # Expected conventions:
+      #
+      # 1. A Rules class may exist following the pattern:
+      #    "#{ControllerName}Restme::Create::RestmeRules"
+      #
+      # 2. The Rules class may define:
+      #    RESTME_CREATE_ACTIONS_RULES = [:create]
+      #
+      # 3. Scope methods must follow this format:
+      #    "#{action}_#{role}_scope?"
+      #
+      # Example:
+      #   create_admin_scope?
+      #   create_manager_scope?
+      #
+      class Rules
+        attr_reader :context
+
+        def initialize(context:)
+          @context = context
+        end
+
+        # Executes create flow
+        #
+        # @param custom_params [Hash]
+        # @param auto_save [Boolean]
+        #
+        # @return [ActiveRecord::Base, Hash]
+        def create(custom_params: {})
+          build(custom_params:)
+
+          instance.save unless errors
+
+          errors || instance
+        end
+
+        def create_status
+          errors ? :unprocessable_content : :created
+        end
+
+        private
+
+        # Builds the instance without persisting
+        #
+        # @param custom_params [Hash]
+        # @return [ActiveRecord::Base]
+        def build(custom_params: {})
+          @custom_params = custom_params
+          set_current_user
+          instance
+        end
+
+        # -----------------------------
+        # Instance
+        # -----------------------------
+
+        def instance
+          @instance ||= begin
+            params = context.controller_params_serialized
+            params = params.merge(@custom_params) if @custom_params.present?
+
+            context.model_class.new(params)
+          end
+        end
+
+        # -----------------------------
+        # Current user injection
+        # -----------------------------
+
+        def set_current_user
+          return unless context.current_user
+          return unless instance.respond_to?(:current_user=)
+
+          instance.current_user = context.current_user
+        end
+
+        # -----------------------------
+        # Errors
+        # -----------------------------
+
+        def errors
+          return unless scoped_action?
+          return unscoped_errors unless scope_allowed?
+          return if instance.errors.blank?
+
+          active_record_errors
+        end
+
+        def unscoped_errors
+          { errors: ["Unscoped"] }
+        end
+
+        def active_record_errors
+          { errors: instance.errors.messages }
+        end
+
+        # -----------------------------
+        # Scope validation
+        # -----------------------------
+
+        def scope_allowed?
+          return true unless context.current_user
+
+          scope_methods.any? do |method|
+            rules_instance.respond_to?(method) &&
+              rules_instance.public_send(method)
+          end
+        end
+
+        def scope_methods
+          context.current_user_roles.map do |role|
+            "#{current_action}_#{role}_scope?"
+          end
+        end
+
+        # -----------------------------
+        # Action validation
+        # -----------------------------
+
+        def scoped_action?
+          return false unless rules_class&.const_defined?(:RESTME_CREATE_ACTIONS_RULES)
+
+          context.action_name.presence_in(
+            rules_class::RESTME_CREATE_ACTIONS_RULES
+          )
+        end
+
+        def current_action
+          context.action_name
+        end
+
+        # -----------------------------
+        # Rules resolution
+        # -----------------------------
+
+        def rules_instance
+          @rules_instance ||= rules_class&.new(instance, context.current_user)
+        end
+
+        def rules_class
+          @rules_class ||= RestmeRails::RulesFind
+                           .new(
+                             klass: context.model_class,
+                             rule_context: "Create"
+                           ).rule_class
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module RestmeRails
+  module Core
+    module Scope
+      module Field
+        # Handles attachment field selection for scoped queries.
+        #
+        # Responsibilities:
+        #
+        # - Validates selected attachment fields
+        # - Prevents unallowed attachment access
+        # - Serializes attachment URLs without mutating the model class
+        #
+        # Important:
+        # This version does NOT dynamically define methods on the model.
+        # Attachment URLs are injected directly into the serialized JSON.
+        #
+        # Expected behavior:
+        #
+        # If the request includes:
+        #   attachment_fields_select: [:avatar]
+        #
+        # The JSON response will include:
+        #   {
+        #     avatar_url: "https://..."
+        #   }
+        #
+        class Attachable
+          attr_reader :context,
+                      :attachment_fields_select,
+                      :valid_nested_fields_select,
+                      :scope_error_instance
+
+          def initialize(context:, attachment_fields_select:, valid_nested_fields_select:, scope_error_instance:)
+            @context = context
+            @attachment_fields_select = attachment_fields_select
+            @valid_nested_fields_select = valid_nested_fields_select
+            @scope_error_instance = scope_error_instance
+          end
+
+          # Applies attachment logic to a given ActiveRecord scope.
+          #
+          # Steps:
+          # 1. Validates unallowed attachment fields
+          # 2. If none selected, returns normal JSON
+          # 3. Preloads attachments
+          # 4. Injects *_url fields directly into serialized hash
+          #
+          # @param scope [ActiveRecord::Relation]
+          # @return [Array<Hash>]
+          def insert_attachments(scope)
+            unallowed_attachment_fields_errors
+
+            return scope.as_json(json_options) if attachment_fields_select.blank?
+
+            records = scope.includes(attachment_includes)
+
+            serialize_with_attachments(records)
+          end
+
+          # Registers bad_request error if client selected
+          # attachment fields that do not exist in the model.
+          #
+          # @return [void]
+          def unallowed_attachment_fields_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
+
+          # Base JSON options (without attachment methods).
+          #
+          # @return [Hash]
+          def json_options
+            {
+              include: valid_nested_fields_select
+            }
+          end
+
+          # Serializes records and injects attachment URLs.
+          #
+          # @param records [ActiveRecord::Relation]
+          # @return [Array<Hash>]
+          def serialize_with_attachments(records)
+            records.map do |record|
+              base_hash = record.as_json(json_options)
+
+              attachment_fields_select.each do |field|
+                attachment = record.public_send(field)
+
+                base_hash["#{field}_url"] =
+                  attachment&.attached? ? attachment.url : nil
+              end
+
+              base_hash
+            end
+          end
+
+          # Builds includes structure for ActiveStorage eager loading.
+          #
+          # Example:
+          #   { avatar_attachment: :blob }
+          #
+          # @return [Array<Hash>]
+          def attachment_includes
+            attachment_fields_select.map do |field|
+              { "#{field}_attachment": :blob }
+            end
+          end
+
+          # Returns all attachment names declared in the model.
+          #
+          # @return [Array<Symbol>]
+          def model_attachment_fields
+            @model_attachment_fields ||= context.model_class
+                                                .attachment_reflections
+                                                .map { |_name, reflection| reflection.name }
+          end
+
+          # Returns 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
+        end
+      end
+    end
+  end
+end