rhino-rails 4.9.0 → 4.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f33582b9aac75614096047f46227c443f63a31634c40cf8825a92d5fb064f583
-  data.tar.gz: 94f626caf29a1e66132524f649b8b4dd6f2aeb52c88b48eca5f20479af653316
+  metadata.gz: 7940c1894a48b568ac853c65c73597adc6e56128b3a4d5958c003c6bc0ab03e9
+  data.tar.gz: 4214c47df8a3caaa7bb7ef81957a77935b795d67c057b1797bf4945e66c677cb
 SHA512:
-  metadata.gz: 27865b6bb3173908f8990a908f87aae8222f7237d691b83dd1fa2607fc1bb86eb88791a37a1b1de44db0d0f4e1d3b4a731ac4d89441775f2b77ce92f9d0ec2b8
-  data.tar.gz: 51bd6475c50215ff50bfede53d09bc627e86d19033cc45a5e4e7a3035dd6050430efc61a4b13b77c4d3461185edb519f093f9855f8cb50b98fdb35621a682aee
+  metadata.gz: 0f8235a208d9e2b23be8e6a33f2ad0623d56f43fa2443ed0727c19aa8888e888ea88778ea4885bb8d38abc2d3d3de030e500767f9e372b0986d0ebfb6037bd76
+  data.tar.gz: d373f8eed1679caef1d7f2f6a9f516161eb8eb6bfae9e6e536add126cf8a3f923ed849fe3713865810cd2d9e943905bf3befbc0201d599bbb0ab8455808fb4f2

data/lib/rhino/commands/generate_command.rb

@@ -15,6 +15,7 @@ module Rhino
           menu.choice "Model (with migration and factory)", "model"
           menu.choice "Policy (extends ResourcePolicy)", "policy"
           menu.choice "Scope (for ScopedDB)", "scope"
+          menu.choice "Request (validation for store/update)", "request"
         end
 
         name = ask("What is the resource name? (PascalCase singular, e.g., Post):")
@@ -32,6 +33,8 @@ module Rhino
           generate_policy(name)
         when "scope"
           generate_scope(name)
+        when "request"
+          generate_request(name)
         end
       end
 
@@ -198,6 +201,50 @@ module Rhino
         say ""
       end
 
+      # ----------------------------------------------------------------
+      # Request generation
+      # ----------------------------------------------------------------
+
+      # Generates {Model}StoreRequest / {Model}UpdateRequest into app/requests/,
+      # which Zeitwerk autoloads like every other app/* directory — no
+      # initializer and no eager_load_paths entry is needed for the naming
+      # convention to find them.
+      def generate_request(name)
+        model_name = name.sub(/(Store|Update)?Request\z/, "")
+        model_name = name if model_name.blank?
+
+        which = select("Which request classes should be generated?") do |menu|
+          menu.choice "Store (POST /{resource})", "store"
+          menu.choice "Update (PUT /{resource}/:id)", "update"
+          menu.choice "Both", "both"
+        end
+
+        actions = which == "both" ? %w[store update] : [which]
+        created = []
+
+        actions.each do |request_action|
+          class_name = request_class_name(model_name, request_action)
+          task("Generating #{class_name}") do
+            created << write_request_file(model_name, request_action)
+          end
+        end
+
+        say ""
+        say "#{created.length == 1 ? 'Request' : 'Requests'} generated successfully!", :green
+        say ""
+        created.each { |path| say "  Created: #{path}" }
+        say ""
+        say "  Next steps:", :yellow
+        say "    1. Declare an `attribute` for EVERY field the action may write —"
+        say "       an undeclared field is dropped, not persisted."
+        say "    2. Add validations, and override authorize?/prepare if needed."
+        say ""
+      end
+
+      def request_class_name(model_name, request_action)
+        "#{model_name}#{request_action == 'update' ? 'Update' : 'Store'}Request"
+      end
+
       # ----------------------------------------------------------------
       # Column collection
       # ----------------------------------------------------------------
@@ -389,6 +436,23 @@ module Rhino
         File.write(dest, content)
       end
 
+      def write_request_file(name, request_action)
+        template = File.expand_path("../../templates/generate/request.rb.erb", __FILE__)
+        class_name = request_class_name(name, request_action)
+        relative = "app/requests/#{class_name.underscore}.rb"
+        dest = Rails.root.join(relative)
+        FileUtils.mkdir_p(File.dirname(dest))
+
+        content = ERB.new(File.read(template), trim_mode: "-").result_with_hash(
+          name: name,
+          class_name: class_name,
+          action: request_action
+        )
+
+        File.write(dest, content)
+        relative
+      end
+
       def register_model_in_config(name)
         config_path = Rails.root.join("config/initializers/rhino.rb")
         return unless File.exist?(config_path)

data/lib/rhino/concerns/has_validation.rb

@@ -33,6 +33,11 @@ module Rhino
     # Filters to only permitted fields, then runs ActiveModel validations
     # and cross-tenant FK validation.
     #
+    # @deprecated Model-level validation is superseded by request classes
+    #   ({Model}StoreRequest / {Model}UpdateRequest, see Rhino::ResourceRequest).
+    #   It still works unchanged for every model that has no request class for
+    #   the action and will be removed in 5.0.
+    #
     # @param params [Hash] The request data
     # @param permitted_fields [Array<String>] Fields the user is allowed to set (['*'] for all)
     # @param organization [Object, nil] Current organization for FK scoping (optional)
@@ -80,6 +85,25 @@ module Rhino
       end
     end
 
+    # Public entry point for cross-tenant FK validation.
+    #
+    # The request-class path (Rhino::ResourceRequest) runs its own validations
+    # and therefore never calls validate_for_action, but it still needs the
+    # cross-tenant FK check — including the indirect case, where the referenced
+    # table reaches the organization through a FK chain rather than an
+    # organization_id column. This wraps the existing private implementation so
+    # the chain walk and its class-level caches stay in one place.
+    #
+    # @param data [Hash] the write payload (string-keyed)
+    # @param organization [Object, nil]
+    # @return [Hash<String, Array<String>>] {} when there is no organization
+    def rhino_validate_foreign_keys(data, organization)
+      return {} unless organization
+      return {} unless data.is_a?(Hash)
+
+      validate_foreign_keys_for_organization(data, organization)
+    end
+
     private
 
     # Cache for FK chain lookups (class-level)

data/lib/rhino/configuration.rb

@@ -16,9 +16,14 @@ module Rhino
     # Default 3 — a base scope, a window, and one more predicate.
     attr_reader :max_scopes_per_request
     attr_reader :auth
+    # Explicit per-model request-class registrations, kept OUT of @models so its
+    # `slug => "ClassName"` shape (read all over the library) is untouched.
+    # Shape: { slug_sym => { store: "ClassName" | nil, update: "ClassName" | nil } }
+    attr_reader :model_requests
 
     def initialize
       @models = {}
+      @model_requests = {}
       @route_groups = {}
       @multi_tenant = {
         organization_identifier_column: "id"
@@ -63,9 +68,58 @@ module Rhino
 
     # Register a model with its slug
     # Usage: config.model :posts, 'Post'
-    def model(slug, klass_name)
-      @models[slug.to_sym] = klass_name.to_s
+    #
+    # The optional `store_request:` / `update_request:` keywords override the
+    # `{Model}StoreRequest` / `{Model}UpdateRequest` naming convention for that
+    # model's POST / PUT action:
+    #
+    #   config.model :tasks, "Task", store_request: "CreateTask", update_request: "EditTask"
+    #
+    # Class NAMES (strings) are stored, never constants, so a dev-mode Zeitwerk
+    # reload never hands back an unloaded class. A registration that cannot be
+    # constantized at request time raises Rhino::ConfigurationError rather than
+    # silently skipping validation.
+    def model(slug, klass_name, store_request: nil, update_request: nil)
+      key = slug.to_sym
+      @models[key] = klass_name.to_s
+
+      requests = {
+        store: normalize_request_class_name(store_request),
+        update: normalize_request_class_name(update_request)
+      }
+
+      if requests[:store].nil? && requests[:update].nil?
+        @model_requests.delete(key)
+      else
+        @model_requests[key] = requests
+      end
+    end
+
+    # The explicitly registered request class NAME for a model slug + action,
+    # or nil when the model relies on the naming convention.
+    #
+    # @param slug [String, Symbol, nil]
+    # @param action [String, Symbol] "store" or "update"
+    # @return [String, nil]
+    def request_class_for(slug, action)
+      return nil if slug.nil? || slug.to_s.empty?
+
+      entry = @model_requests[slug.to_sym]
+      return nil unless entry
+
+      entry[action.to_s == "update" ? :update : :store]
+    end
+
+    # Coerce a request-class registration to a String class name. A Class is
+    # accepted for convenience but stored by name (reloader safety); blank
+    # values register nothing.
+    def normalize_request_class_name(value)
+      return nil if value.nil?
+
+      name = value.is_a?(Class) ? value.name.to_s : value.to_s
+      name.strip.empty? ? nil : name.strip
     end
+    private :normalize_request_class_name
 
     # Register a route group with its configuration
     # Usage: config.route_group :tenant, prefix: ':organization', middleware: [Rhino::Middleware::ResolveOrganizationFromRoute], models: :all

data/lib/rhino/configuration_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Rhino
+  # Raised when Rhino is configured with something it cannot resolve at
+  # request time — today only an explicit request-class registration
+  # (`config.model :tasks, "Task", store_request: "..."`) whose class name
+  # cannot be constantized, or which does not inherit from
+  # Rhino::ResourceRequest.
+  #
+  # This is deliberately NOT rescued into a JSON response: a silently ignored
+  # validation class is a security hole, so a misconfigured app must fail
+  # loudly (500) on first use rather than quietly skipping validation.
+  class ConfigurationError < StandardError; end
+end

data/lib/rhino/controllers/resources_controller.rb

@@ -95,6 +95,34 @@ module Rhino
         }, status: :forbidden
       end
 
+      # Request class (Rhino::ResourceRequest) for this model + action, if any.
+      # Resolved AFTER the forbidden-field gate so `prepare` can never launder a
+      # field past the policy, and BEFORE the legacy model rules, which are not
+      # consulted at all when a request class is present for this action.
+      if (request_class = request_class_for("store"))
+        status, payload = run_resource_request(request_class, data, "store", nil, model_class)
+        return render_request_class_forbidden if status == :forbidden
+        return render json: { errors: payload }, status: :unprocessable_entity if status == :invalid
+
+        add_organization_to_data(payload)
+
+        begin
+          created = model_class.create!(payload)
+        rescue ActiveRecord::RecordInvalid => e
+          # A model-level `validates` rule the request class did not reproduce
+          # still runs inside create!. Render it in the same envelope the
+          # request class's own failures use instead of letting it escape as a
+          # 500. The legacy path cannot reach here — it ran those very rules up
+          # front — so this rescue is confined to the request-class branch.
+          return render json: { errors: record_validation_errors(e.record) },
+                        status: :unprocessable_entity
+        end
+
+        return render json: serialize_record(created), status: :created
+      end
+
+      # @deprecated Legacy model-level validation path. Byte-for-byte unchanged;
+      #   reached only when no request class exists for this model + action.
       model_instance = model_class.new
       validation = model_instance.validate_for_action(
         data, permitted_fields: permitted_fields, organization: current_organization
@@ -159,6 +187,29 @@ module Rhino
         }, status: :forbidden
       end
 
+      # Request class for this model + action, if any. `record` is the already
+      # loaded, ORGANIZATION-SCOPED row (never re-fetched by bare id), so a
+      # record-dependent rule can never see another tenant's state.
+      if (request_class = request_class_for("update"))
+        status, payload = run_resource_request(request_class, data, "update", record, model_class)
+        return render_request_class_forbidden if status == :forbidden
+        return render json: { errors: payload }, status: :unprocessable_entity if status == :invalid
+
+        begin
+          record.update!(payload)
+        rescue ActiveRecord::RecordInvalid => e
+          # See the note in `store`: a model rule stricter than the request
+          # class must surface as the standard 422, not a 500.
+          return render json: { errors: record_validation_errors(e.record) },
+                        status: :unprocessable_entity
+        end
+
+        record.reload
+        return render json: serialize_record(record)
+      end
+
+      # @deprecated Legacy model-level validation path. Byte-for-byte unchanged;
+      #   reached only when no request class exists for this model + action.
       model_instance = model_class.new
       validation = model_instance.validate_for_action(
         data, permitted_fields: permitted_fields, organization: current_organization
@@ -329,6 +380,10 @@ module Rhino
 
       # Execute all operations in a transaction
       results = execute_nested_operations(operations, validated_per_op, auth_results)
+      # execute_nested_operations renders (and rolls back) when a model-level
+      # rule fails at save time on the request-class path.
+      return if performed?
+
       render json: { results: results }
     end
 
@@ -968,6 +1023,39 @@ module Rhino
         return nil
       end
 
+      # Request class for this operation. `action` maps to the request-class
+      # vocabulary: a nested "create" op is the "store" action.
+      request_action = action == "create" ? "store" : "update"
+      if (request_class = request_class_for(request_action, op_model_class, slug))
+        # Non-failing, organization-scoped lookup: `nil` on a miss so the
+        # existing authorize_nested_operation step still produces today's
+        # 403/404 in today's order.
+        op_record = request_action == "update" ? find_nested_operation_record(op_model_class, operation["id"]) : nil
+
+        status, payload = run_resource_request(
+          request_class, operation["data"], request_action, op_record, op_model_class
+        )
+
+        if status == :forbidden
+          render json: { message: "This action is unauthorized." }, status: :forbidden
+          return nil
+        end
+
+        if status == :invalid
+          errors = {}
+          payload.each do |key, messages|
+            errors["operations.#{index}.data.#{key}"] = messages
+          end
+          render json: { message: "Validation failed.", errors: errors }, status: :unprocessable_entity
+          return nil
+        end
+
+        return payload
+      end
+
+      # @deprecated Legacy model-level validation path for nested operations.
+      #   Unchanged; reached only when no request class exists for this
+      #   operation's model + action.
       model_instance = op_model_class.new
       validation = model_instance.validate_for_action(operation["data"], permitted_fields: permitted_fields)
 
@@ -995,7 +1083,20 @@ module Rhino
         end
         nil
       else
-        record = op_model_class.find(operation["id"])
+        # ORGANIZATION-SCOPED lookup. A bare `op_model_class.find` let org B
+        # update org A's rows through POST /nested: only models including
+        # Rhino::BelongsToOrganization were protected, and then only by that
+        # concern's default_scope, so a plain organization_id column, a
+        # for_organization scope and every indirect belongs_to chain
+        # (task -> project -> org) leaked on the WRITE path while the member
+        # endpoints 404'd. Uses the same lenient mechanism find_record and
+        # index use, so a model with no org mechanism stays reachable and a
+        # request with no org context is unscoped exactly as before. A
+        # cross-org id now raises RecordNotFound, indistinguishable from an id
+        # that does not exist.
+        record = Rhino::ScopesToOrganization.scope_to_organization(
+          op_model_class.all, op_model_class, current_organization
+        ).find(operation["id"])
         unless policy.new(current_user, record).update?
           render json: { message: "This action is unauthorized." }, status: :forbidden
           return nil
@@ -1006,39 +1107,74 @@ module Rhino
 
     def execute_nested_operations(operations, validated_per_op, auth_results)
       results = []
+      # [index, record] for an operation whose MODEL rules failed at save time
+      # on the request-class path. Set inside the transaction, rendered after it
+      # has rolled back.
+      save_failure = nil
 
       ActiveRecord::Base.transaction do
         operations.each_with_index do |op, index|
           validated = validated_per_op[index]
           model_or_nil = auth_results[index]
 
-          if op["action"] == "create"
-            op_model_class = Rhino.config.resolve_model(op["model"])
-            data = validated.dup
-            add_organization_to_data(data)
-            record = op_model_class.create!(data)
-            results << {
-              model: op["model"],
-              action: "create",
-              id: record.id,
-              data: serialize_record(record)
-            }
-          else
-            model_or_nil.update!(validated)
-            model_or_nil.reload
-            results << {
-              model: op["model"],
-              action: "update",
-              id: model_or_nil.id,
-              data: serialize_record(model_or_nil)
-            }
+          begin
+            if op["action"] == "create"
+              op_model_class = Rhino.config.resolve_model(op["model"])
+              data = validated.dup
+              add_organization_to_data(data)
+              record = op_model_class.create!(data)
+              results << {
+                model: op["model"],
+                action: "create",
+                id: record.id,
+                data: serialize_record(record)
+              }
+            else
+              model_or_nil.update!(validated)
+              model_or_nil.reload
+              results << {
+                model: op["model"],
+                action: "update",
+                id: model_or_nil.id,
+                data: serialize_record(model_or_nil)
+              }
+            end
+          rescue ActiveRecord::RecordInvalid => e
+            # Only the request-class path converts a save-time model-rule
+            # failure into a 422. The legacy path ran those same rules in
+            # validate_for_action before getting here, so it keeps raising
+            # exactly as it does today.
+            raise unless nested_operation_uses_request_class?(op)
+
+            save_failure = [index, e.record]
+            raise ActiveRecord::Rollback
           end
         end
       end
 
+      if save_failure
+        index, invalid_record = save_failure
+        errors = {}
+        record_validation_errors(invalid_record).each do |key, messages|
+          errors["operations.#{index}.data.#{key}"] = messages
+        end
+        render json: { message: "Validation failed.", errors: errors }, status: :unprocessable_entity
+        return nil
+      end
+
       results
     end
 
+    # Whether a nested operation was validated by a request class. Re-resolved
+    # (never memoized) rather than threaded through, and only ever called from
+    # the RecordInvalid rescue, so the happy path pays nothing.
+    def nested_operation_uses_request_class?(operation)
+      op_model_class = Rhino.config.resolve_model(operation["model"])
+      request_action = operation["action"] == "create" ? "store" : "update"
+
+      !request_class_for(request_action, op_model_class, operation["model"]).nil?
+    end
+
     # ------------------------------------------------------------------
     # Permitted fields resolution
     # ------------------------------------------------------------------
@@ -1059,6 +1195,140 @@ module Rhino
       end
     end
 
+    # ------------------------------------------------------------------
+    # Request classes (Rhino::ResourceRequest)
+    # ------------------------------------------------------------------
+
+    # Resolve the request class for a model + action, or nil.
+    #
+    # Precedence: explicit registration (config.model ..., store_request:) →
+    # "{ModelBasename}StoreRequest" / "{ModelBasename}UpdateRequest" → none.
+    #
+    # Resolution happens on EVERY request and is never memoized: caching the
+    # constant would hand back a stale, unloaded class after a dev-mode Zeitwerk
+    # reload.
+    #
+    # An EXPLICIT registration that cannot be resolved — missing constant, or a
+    # constant that is not a Rhino::ResourceRequest — raises. A silently ignored
+    # validation class the developer asked for by name is a security hole.
+    #
+    # A CONVENTION hit that is not a Rhino::ResourceRequest is LOGGED and
+    # ignored, falling through to the legacy path exactly as if no class
+    # existed. The convention is a guess: an app upgrading from 4.9.0 that
+    # happens to own an unrelated top-level `PostStoreRequest` must keep
+    # working, not start returning 500s. A convention miss falls through
+    # silently; that is what "convention" means.
+    #
+    # @param action [String] "store" or "update"
+    # @return [Class, nil]
+    def request_class_for(action, klass = model_class, slug = model_slug)
+      explicit = Rhino.config.request_class_for(slug, action)
+
+      if explicit.present?
+        const = explicit.safe_constantize
+        raise_request_class_configuration_error(explicit, slug, action) unless const
+        unless resource_request_class?(const)
+          raise_request_class_configuration_error(explicit, slug, action)
+        end
+
+        return const
+      end
+
+      return nil unless klass.respond_to?(:name) && klass.name.present?
+
+      suffix = action.to_s == "update" ? "UpdateRequest" : "StoreRequest"
+      name = "#{klass.name.demodulize}#{suffix}"
+      const = name.safe_constantize
+      return nil unless const
+      return const if resource_request_class?(const)
+
+      warn_ignored_request_class(name, slug, action)
+      nil
+    end
+
+    def resource_request_class?(const)
+      const.is_a?(Class) && const < Rhino::ResourceRequest
+    end
+
+    def warn_ignored_request_class(name, slug, action)
+      return unless defined?(Rails) && Rails.respond_to?(:logger)
+
+      Rails.logger&.warn(
+        "Rhino: ignoring #{name} for [#{slug}.#{action}]: " \
+        "it does not inherit from Rhino::ResourceRequest"
+      )
+    end
+
+    def raise_request_class_configuration_error(label, slug, action)
+      raise Rhino::ConfigurationError,
+            "Rhino: request class [#{label}] configured for [#{slug}.#{action}] does not exist."
+    end
+
+    # Instantiate and run a resolved request class.
+    #
+    # @return [Array] [:ok, validated_hash] | [:forbidden, nil] | [:invalid, errors_hash]
+    def run_resource_request(request_class, data, action, record, fk_model_class)
+      request = request_class.new(
+        input: data,
+        user: current_user,
+        organization: current_organization,
+        route_group: current_route_group,
+        action: action,
+        record: record
+      )
+
+      return [:forbidden, nil] unless request.authorize?
+
+      result = request.run
+      errors = result[:errors] || {}
+
+      # Cross-tenant FK validation runs ON TOP of the request class's own rules,
+      # through the same (direct + indirect FK chain) implementation the legacy
+      # path uses. Errors merge into the same 422 body.
+      if current_organization
+        fk_instance = fk_model_class.new
+        if fk_instance.respond_to?(:rhino_validate_foreign_keys)
+          errors = errors.merge(
+            fk_instance.rhino_validate_foreign_keys(result[:validated], current_organization)
+          )
+        end
+      end
+
+      return [:invalid, errors] if errors.any?
+
+      [:ok, result[:validated]]
+    end
+
+    # Model-level validations still run inside create!/update!. On the
+    # request-class path a rule the request class did not reproduce would
+    # otherwise escape as ActiveRecord::RecordInvalid (a 500), so it is rendered
+    # in the same shape the request class's own failures use: String keys,
+    # arrays of messages.
+    def record_validation_errors(record)
+      return {} unless record.respond_to?(:errors)
+
+      record.errors.to_hash.each_with_object({}) do |(attribute, messages), memo|
+        memo[attribute.to_s] = Array(messages)
+      end
+    end
+
+    # Byte-identical to a policy denial on purpose: a client must not be able to
+    # tell an `authorize?` refusal from a policy refusal.
+    def render_request_class_forbidden
+      render json: { message: "This action is unauthorized." }, status: :forbidden
+    end
+
+    # Organization-scoped, non-failing primary-key lookup used to populate
+    # `record` for a nested update operation.
+    def find_nested_operation_record(op_model_class, id)
+      return nil if id.nil?
+
+      scope = Rhino::ScopesToOrganization.scope_to_organization(
+        op_model_class.all, op_model_class, current_organization
+      )
+      scope.find_by(op_model_class.primary_key => id)
+    end
+
     def find_forbidden_fields(params_data, permitted_fields)
       return [] if permitted_fields == ["*"]
 

data/lib/rhino/resource_request.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "active_model"
+require "active_support/core_ext/object/deep_dup"
+
+module Rhino
+  # Base class for per-model, per-action request classes.
+  #
+  # A request class owns the entire shape/format contract for ONE action of ONE
+  # model. Unlike model-level validations it receives the full request context —
+  # the authenticated user, the resolved organization, the matched route group,
+  # the action, and (on update) the pre-update record — so a rule can branch on
+  # any of them.
+  #
+  # Discovery is by convention: `{Model}StoreRequest` / `{Model}UpdateRequest`,
+  # autoloaded from `app/requests/` (Zeitwerk autoloads every `app/*`
+  # directory, so no initializer or eager_load_paths entry is required). An
+  # explicit registration overrides the convention:
+  #
+  #   Rhino.configure do |config|
+  #     config.model :tasks, "Task", store_request: "CreateTask", update_request: "EditTask"
+  #   end
+  #
+  # Usage:
+  #
+  #   # app/requests/task_store_request.rb
+  #   class TaskStoreRequest < Rhino::ResourceRequest
+  #     attribute :title, :string
+  #     attribute :status, :string
+  #     attribute :project_id, :integer
+  #
+  #     validates :title, presence: true, length: { maximum: 255 }
+  #     validates :status, inclusion: { in: %w[todo doing] }, unless: -> { user&.admin? }
+  #
+  #     def authorize?
+  #       route_group != "public"
+  #     end
+  #
+  #     def prepare(input)
+  #       input.merge("title" => input["title"].to_s.strip)
+  #     end
+  #   end
+  #
+  # Rules are ordinary ActiveModel declarations. There is no `rules` method and
+  # no `messages` method: dynamic rules use `validate :method_name` or
+  # `validates ..., if: -> { ... }` with the context readers in scope, and
+  # messages use the standard `message:` option / i18n.
+  #
+  # THE WRITE PAYLOAD IS `validated`. Only DECLARED attributes that are PRESENT
+  # in the prepared input are persisted, with their cast values. A field with no
+  # `attribute` declaration is silently dropped — including a field added by
+  # `prepare` that no `attribute` covers. This fails closed: when a policy
+  # permits `['*']`, the request class is the only field filter left.
+  class ResourceRequest
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+    include ActiveModel::Validations
+
+    # The request context. All six values are available to `authorize?`,
+    # `prepare` and every validation.
+    #
+    # @return [Object, nil] the authenticated user, nil when unauthenticated
+    attr_reader :user
+    # @return [Object, nil] the resolved organization, nil outside a tenant context
+    attr_reader :organization
+    # @return [String, nil] the matched route's route group ("tenant", "public", ...)
+    attr_reader :route_group
+    # @return [String] "store" or "update"
+    attr_reader :action
+    # @return [Object, nil] the PRE-UPDATE record on update, nil on store
+    attr_reader :record
+    # @return [Hash] the prepared input, string-keyed
+    attr_reader :input
+
+    # @param input [Hash] the raw request data, AFTER the policy forbidden-field
+    #   gate has run (so `prepare` can never launder a field past the policy)
+    # @param user [Object, nil]
+    # @param organization [Object, nil]
+    # @param route_group [String, nil]
+    # @param action [String] "store" or "update"
+    # @param record [Object, nil]
+    def initialize(input:, user: nil, organization: nil, route_group: nil, action: "store", record: nil)
+      @user = user
+      @organization = organization
+      @route_group = route_group.nil? ? nil : route_group.to_s
+      @action = action.to_s
+      @record = record
+
+      # ActiveModel::Attributes defaults must exist before anything reads or
+      # writes an attribute — including a `prepare` override that touches one.
+      super()
+
+      raw = self.class.normalize_input_keys(input)
+      prepared = prepare(raw.deep_dup)
+      # A `prepare` that returns a non-Hash (or nil) is treated as "no change".
+      @input = prepared.is_a?(Hash) ? self.class.normalize_input_keys(prepared) : raw
+
+      assign_declared_attributes
+    end
+
+    # Override point: return false to refuse the request with a 403 whose body
+    # is byte-identical to a policy denial, so `authorize?` cannot be used to
+    # enumerate anything about the model.
+    #
+    # @return [Boolean]
+    def authorize?
+      true
+    end
+
+    # Override point: normalize the input before validation. Runs BEFORE
+    # `authorize?`, so `authorize?` sees normalized input.
+    #
+    # Fields added here are SERVER-AUTHORED and are not re-checked against the
+    # policy's permitted attributes — the forbidden-field gate already ran on
+    # exactly what the client sent. Never copy a client value into a different
+    # key here; that writes a field the policy denied.
+    #
+    # A return value that is not a Hash is ignored.
+    #
+    # @param input [Hash] string-keyed copy of the raw input
+    # @return [Hash]
+    def prepare(input)
+      input
+    end
+
+    # Run the validations.
+    #
+    # @return [Hash] { valid: Boolean, errors: Hash<String, Array<String>>, validated: Hash }
+    def run
+      ok = valid?
+
+      { valid: ok, errors: error_messages, validated: validated }
+    end
+
+    # The write payload: declared attribute names that are present in the
+    # prepared input, mapped to their CAST values.
+    #
+    # @return [Hash<String, Object>]
+    def validated
+      attributes.select { |name, _| @input.key?(name) }
+    end
+
+    # Errors in the shape Rhino renders at 422:
+    #   { "title" => ["can't be blank"], ... }
+    #
+    # Built exactly the way HasValidation#validate_for_action builds it, but
+    # WITHOUT its "only report errors on fields the client sent" guard — on a
+    # request class an error on an absent-but-required field is the point.
+    #
+    # @return [Hash<String, Array<String>>]
+    def error_messages
+      messages = {}
+      errors.each do |error|
+        field_name = error.attribute.to_s
+        messages[field_name] ||= []
+        messages[field_name] << error.message
+      end
+      messages
+    end
+
+    # Stringify top-level keys so `input["title"]` works regardless of whether
+    # the caller handed us a Hash, a HashWithIndifferentAccess or symbol keys.
+    #
+    # @api private
+    def self.normalize_input_keys(hash)
+      return {} unless hash.is_a?(Hash)
+
+      hash.each_with_object({}) { |(key, value), memo| memo[key.to_s] = value }
+    end
+
+    private
+
+    # Assign ONLY declared attributes, and only those actually present in the
+    # prepared input, so an absent attribute keeps its declared default rather
+    # than being overwritten with nil.
+    def assign_declared_attributes
+      self.class.attribute_names.each do |name|
+        next unless @input.key?(name)
+
+        public_send("#{name}=", @input[name])
+      end
+    end
+  end
+end

data/lib/rhino/templates/generate/request.rb.erb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+# Validation for <%= action == "update" ? "PUT /{resource}/:id" : "POST /{resource}" %> on <%= name %>.
+#
+# Found by convention — Rhino looks for <%= class_name %> whenever
+# <%= name %> handles its <%= action %> action, and falls back to the model's own
+# validations when no request class exists. Override the convention with:
+#
+#   config.model :<%= name.underscore.pluralize %>, "<%= name %>", <%= action %>_request: "My<%= action == "update" ? "Update" : "Store" %>Class"
+#
+# Context available to every method below:
+#   user          — the authenticated user (or nil)
+#   organization  — the resolved organization (or nil outside a tenant context)
+#   route_group   — the matched route's group ("tenant", "public", ...)
+#   action        — "<%= action %>"
+#   record        — <%= action == "update" ? "the PRE-UPDATE record" : "nil (there is no record yet on store)" %>
+#   input         — the prepared, string-keyed request data
+class <%= class_name %> < Rhino::ResourceRequest
+  # Declare an attribute for EVERY field this action may write.
+  #
+  # The declared attributes present in the input ARE the write payload: a field
+  # with no `attribute` here is silently dropped, never persisted — even if the
+  # policy permits it, and even if `prepare` added it.
+  #
+  # attribute :title, :string
+  # attribute :status, :string
+  # attribute :project_id, :integer
+  # attribute :due_date, :date
+
+  # Ordinary ActiveModel validations. Unlike the model-level path, these are NOT
+  # relaxed for partial updates — declare what is optional yourself.
+  #
+  # validates :title, presence: true, length: { maximum: 255 }
+  # validates :status, inclusion: { in: %w[todo doing done] }, allow_nil: true
+
+  # Rules that depend on WHO is asking: branch on `user` instead of keeping a
+  # role-keyed map on the model. Remember that the policy already decided which
+  # fields the role may write — this decides what a valid value looks like.
+  #
+  # validates :status,
+  #           inclusion: { in: %w[todo doing] },
+  #           if: -> { user.nil? || user.role_slug_for_validation(organization) != "admin" }
+
+  # Rules that depend on WHERE the request came from.
+  #
+  # validates :assignee_id, presence: true, if: -> { route_group == "tenant" }
+
+<% if action == "update" -%>
+  # Rules that depend on the record's CURRENT state. `record` is the
+  # organization-scoped row as it exists BEFORE this update is applied.
+  #
+  # validate :status_may_not_move_backwards
+
+<% end -%>
+  # Refuse the request outright. Returning false renders 403 with exactly the
+  # body a policy denial renders, so it leaks nothing about this model.
+  #
+  # def authorize?
+  #   route_group != "public"
+  # end
+
+  # Normalize the input before validation. Runs BEFORE authorize?, and AFTER the
+  # policy's forbidden-field check — so anything added here is server-authored
+  # and trusted. Never copy a client value into a different key here; that would
+  # write a field the policy denied. A field added here still needs an
+  # `attribute` above to be persisted. A non-Hash return value is ignored.
+  #
+  # Because it runs before the validations, `prepare` sees RAW client input: a
+  # client can send {"title": ["x"]} or {"title": 5}. Guard every string
+  # operation with is_a?(String) and leave anything else untouched, so a
+  # validation rejects it with a 422 instead of prepare blowing up (or silently
+  # stringifying it into something that passes).
+  #
+  # def prepare(input)
+  #   title = input["title"]
+  #   input.merge("title" => title.is_a?(String) ? title.strip : title)
+  # end
+
+  # An `attribute :title, :string` casts ANY value to a String, so ["x"] becomes
+  # '["x"]' and would sail past presence/length. When the shape matters, check
+  # the RAW input rather than the cast value.
+  #
+  # validate :title_must_be_text
+<% if action != "update" -%>
+
+  # private
+
+  # def title_must_be_text
+  #   return if input["title"].nil? || input["title"].is_a?(String)
+  #
+  #   errors.add(:title, "must be a string")
+  # end
+<% end -%>
+<% if action == "update" -%>
+
+  # private
+
+  # def title_must_be_text
+  #   return if input["title"].nil? || input["title"].is_a?(String)
+  #
+  #   errors.add(:title, "must be a string")
+  # end
+
+  # def status_may_not_move_backwards
+  #   return if record.nil? || status.nil?
+  #   return unless record.status == "done" && status != "done"
+  #
+  #   errors.add(:status, "cannot be reopened once the task is done")
+  # end
+<% end -%>
+end

data/lib/rhino/version.rb

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

data/lib/rhino.rb

@@ -6,6 +6,7 @@ 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/configuration_error"
 require "rhino/argument_binder"
 require "rhino/scope_spec"
 require "rhino/computed_attribute_spec"
@@ -14,6 +15,7 @@ require "rhino/auth_hooks"
 require "rhino/group_membership"
 require "rhino/resource_scope"
 require "rhino/scopes_to_organization"
+require "rhino/resource_request"
 require "rhino/context"
 require "rhino/query"
 require "rhino/routing/domain_constraint"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rhino-rails
 version: !ruby/object:Gem::Version
-  version: 4.9.0
+  version: 4.10.0
 platform: ruby
 authors:
 - Bruno Cipolla
@@ -219,6 +219,7 @@ files:
 - lib/rhino/concerns/hidable_columns.rb
 - lib/rhino/concerns/route_group_context.rb
 - lib/rhino/configuration.rb
+- lib/rhino/configuration_error.rb
 - lib/rhino/context.rb
 - lib/rhino/controllers/auth_controller.rb
 - lib/rhino/controllers/invitations_controller.rb
@@ -239,6 +240,7 @@ files:
 - lib/rhino/query.rb
 - lib/rhino/query_builder.rb
 - lib/rhino/railtie.rb
+- lib/rhino/resource_request.rb
 - lib/rhino/resource_scope.rb
 - lib/rhino/routes.rb
 - lib/rhino/routing/domain_constraint.rb
@@ -252,6 +254,7 @@ files:
 - lib/rhino/templates/generate/migration.rb.erb
 - lib/rhino/templates/generate/model.rb.erb
 - lib/rhino/templates/generate/policy.rb.erb
+- lib/rhino/templates/generate/request.rb.erb
 - lib/rhino/templates/generate/scope.rb.erb
 - lib/rhino/templates/multi_tenant/factories/organizations.rb.erb
 - lib/rhino/templates/multi_tenant/factories/roles.rb.erb