rhino-rails 4.4.0 → 4.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0155b30eedf93061b38295ed96254194529de0abf03aad309becc312a512c5ba
-  data.tar.gz: 5e1ce1624bab2a77f8603ebdf6984a43e4bd71d277f51900ae533465e4fd0881
+  metadata.gz: 3c800a5e70d40849b886fdd638cc4214fa4bd782965de5a94394a6fa0319cb38
+  data.tar.gz: e967104d44d640b9645f579022f14831d36150e763497e25ecfbd2b391ec76b1
 SHA512:
-  metadata.gz: 975f1ee3efc83423ae775131eace5689a7b09269541848da21e286f2f55cedd71b265a8e3c5c448a85cc7b9c8ecdde2e27dd615ef1a26719732a7d958cbfb8da
-  data.tar.gz: 3a32ccaf04ad8f351828752a83efac31503d53afbd4c3239d0f38e836c8e151dd4681f2a650a853e9d6d728e6477f34e72023680c6bbd36dc63369ad6ca6d10c
+  metadata.gz: 717d3ad2ef05fe9ead1918baa1d52d61e865f0b3cd95925173df147ae41ba66786a88971eeed21ef5729103d07312c4b3fdb0ffd5ed2a398e140e3abeebca670
+  data.tar.gz: 0e20f9f6ee200c2643c691c4bac35a6acc6eb091103539b3271133c67f4093bae017bc5ce3b0955b2966ef1be1c688e30c4c17e28dd16566116e9beab5bee34e

data/README.md

@@ -41,6 +41,7 @@ Register a model, get a full REST API instantly.
 | 27 | **Postman Export** | Auto-generated Postman Collection v2.1 with all endpoints. |
 | 28 | **Blueprint System** | YAML-to-code generation for models, migrations, factories, policies, tests, and seeders. |
 | 29 | **Named Scopes** | `?scope=availableForDrivers` client-selectable scopes (whitelisted via `rhino_scopes`), plus a `rhino_default_scope` applied when none is requested. Unknown scopes return 403. Applies to `index`/`trashed` only. |
+| 30 | **Configurable Route Key** | Match the `:id` URL segment against any column (`rhino_route_key :hash_id` per model, or global `config.route_key`). Member endpoints only — payload FKs and nested-operation ids stay primary-key based. |
 
 ## Quick Start
 

data/lib/rhino/blueprint/blueprint_parser.rb

@@ -96,7 +96,8 @@ module Rhino
           owner: options.fetch("owner", nil),
           except_actions: options.fetch("except_actions", []),
           pagination: options.fetch("pagination", false),
-          per_page: options.fetch("per_page", 25)
+          per_page: options.fetch("per_page", 25),
+          route_key: options.fetch("route_key", nil)
         }
       end
 

data/lib/rhino/blueprint/blueprint_validator.rb

@@ -65,7 +65,8 @@ module Rhino
         warnings.concat(perm_result[:warnings])
 
         # Options
-        errors.concat(validate_options(blueprint[:options]))
+        errors.concat(validate_options(blueprint[:options], column_names))
+        warnings.concat(route_key_warnings(blueprint[:options], blueprint[:columns]))
 
         # Relationships
         errors.concat(validate_relationships(blueprint[:relationships]))
@@ -156,8 +157,9 @@ module Rhino
         { errors: errors, warnings: warnings }
       end
 
-      # Validate options.
-      def validate_options(options)
+      # Validate options. When +column_names+ is provided, also validates that
+      # a configured route_key references a declared column (or 'id').
+      def validate_options(options, column_names = nil)
         errors = []
 
         if options[:except_actions]
@@ -168,6 +170,11 @@ module Rhino
           end
         end
 
+        route_key = options[:route_key]
+        if route_key && column_names && !(["id"] + column_names).include?(route_key.to_s)
+          errors << "route_key '#{route_key}' does not match any declared column"
+        end
+
         errors
       end
 
@@ -193,6 +200,21 @@ module Rhino
         errors
       end
 
+      # Warn when the route_key column is not marked unique — non-unique route
+      # keys make member-endpoint lookups ambiguous.
+      def route_key_warnings(options, columns)
+        warnings = []
+        route_key = options[:route_key]
+        return warnings unless route_key
+
+        column = columns.find { |c| c[:name] == route_key.to_s }
+        if column && !column[:unique]
+          warnings << "route_key column '#{route_key}' is not marked unique — member lookups may be ambiguous"
+        end
+
+        warnings
+      end
+
       private
 
       def check_field_references(fields, column_names, role, field_key, warnings)

data/lib/rhino/blueprint/generators/test_generator.rb

@@ -23,9 +23,12 @@ module Rhino
           slug = blueprint[:slug]
           permissions = blueprint[:permissions]
           columns = blueprint[:columns]
+          # URL segment attribute for member endpoints: the configured route
+          # key, or the primary key (id) when none is set.
+          route_key = (blueprint[:options] || {})[:route_key] || "id"
           factory_name = model_to_factory(model)
 
-          role_contexts = build_role_contexts(slug, factory_name, permissions, columns, is_multi_tenant, org_identifier)
+          role_contexts = build_role_contexts(slug, factory_name, permissions, columns, is_multi_tenant, org_identifier, route_key)
 
           if is_multi_tenant
             wrap_multi_tenant(model, slug, role_contexts, org_identifier)
@@ -49,7 +52,7 @@ module Rhino
           model.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
         end
 
-        def build_role_contexts(slug, factory_name, permissions, columns, is_multi_tenant, org_identifier)
+        def build_role_contexts(slug, factory_name, permissions, columns, is_multi_tenant, org_identifier, route_key = "id")
           return "" if permissions.empty?
 
           all_defined_actions = permissions.values.flat_map { |p| p[:actions] }.uniq & ALL_ACTIONS
@@ -66,18 +69,18 @@ module Rhino
 
             # Individual allowed action tests
             allowed.each do |action|
-              lines << build_single_action_test(slug, action, is_multi_tenant, org_identifier, true)
+              lines << build_single_action_test(slug, action, is_multi_tenant, org_identifier, true, route_key)
               lines << ""
             end
 
             # Individual blocked action tests
             blocked.each do |action|
-              lines << build_single_action_test(slug, action, is_multi_tenant, org_identifier, false)
+              lines << build_single_action_test(slug, action, is_multi_tenant, org_identifier, false, route_key)
               lines << ""
             end
 
             # Field visibility tests
-            field_test = build_field_visibility_test(slug, role, perm, columns, is_multi_tenant, org_identifier)
+            field_test = build_field_visibility_test(slug, role, perm, columns, is_multi_tenant, org_identifier, route_key)
             if field_test
               lines << field_test
               lines << ""
@@ -114,7 +117,7 @@ module Rhino
           end
         end
 
-        def build_single_action_test(slug, action, is_multi_tenant, org_identifier, expect_success)
+        def build_single_action_test(slug, action, is_multi_tenant, org_identifier, expect_success, route_key = "id")
           id_actions = %w[show update destroy restore forceDelete]
           needs_id = id_actions.include?(action)
           needs_discard = %w[restore forceDelete].include?(action)
@@ -126,10 +129,10 @@ module Rhino
           }
 
           action_path_suffix = {
-            "index" => "", "show" => "/\#{record.id}", "store" => "",
-            "update" => "/\#{record.id}", "destroy" => "/\#{record.id}",
-            "trashed" => "/trashed", "restore" => "/\#{record.id}/restore",
-            "forceDelete" => "/\#{record.id}/force-delete"
+            "index" => "", "show" => "/\#{record.#{route_key}}", "store" => "",
+            "update" => "/\#{record.#{route_key}}", "destroy" => "/\#{record.#{route_key}}",
+            "trashed" => "/trashed", "restore" => "/\#{record.#{route_key}}/restore",
+            "forceDelete" => "/\#{record.#{route_key}}/force-delete"
           }
 
           success_codes = { "store" => ":created", "destroy" => ":no_content", "forceDelete" => ":no_content" }
@@ -168,7 +171,7 @@ module Rhino
           lines.join("\n")
         end
 
-        def build_field_visibility_test(slug, role, perm, columns, is_multi_tenant, org_identifier)
+        def build_field_visibility_test(slug, role, perm, columns, is_multi_tenant, org_identifier, route_key = "id")
           return nil unless perm[:actions].include?("show")
           return nil if perm[:show_fields] == ["*"]
           return nil if perm[:show_fields].empty?
@@ -184,9 +187,9 @@ module Rhino
           lines << "      it 'shows only permitted fields' do"
 
           if is_multi_tenant
-            lines << "        get \"/api/\#{org.#{org_identifier}}/#{slug}/\#{record.id}\", headers: auth_headers(user)"
+            lines << "        get \"/api/\#{org.#{org_identifier}}/#{slug}/\#{record.#{route_key}}\", headers: auth_headers(user)"
           else
-            lines << "        get \"/api/#{slug}/\#{record.id}\", headers: auth_headers(user)"
+            lines << "        get \"/api/#{slug}/\#{record.#{route_key}}\", headers: auth_headers(user)"
           end
 
           lines << "        expect(response).to have_http_status(:ok)"

data/lib/rhino/commands/blueprint_command.rb

@@ -278,6 +278,7 @@ module Rhino
         content += "  rhino_sorts #{sort_cols.map { |c| ":#{c}" }.join(', ')}\n" unless sort_cols.empty?
         content += "  rhino_fields #{field_cols.map { |c| ":#{c}" }.join(', ')}\n" unless field_cols.empty?
         content += "  rhino_includes #{include_cols.map { |c| ":#{c}" }.join(', ')}\n" unless include_cols.empty?
+        content += "  rhino_route_key :#{blueprint[:options][:route_key]}\n" if blueprint[:options][:route_key]
 
         # Validations
 

data/lib/rhino/concerns/has_rhino.rb

@@ -20,6 +20,7 @@ module Rhino
   #     rhino_middleware 'throttle:60,1'
   #     rhino_middleware_actions store: ['verified'], update: ['verified']
   #     rhino_except_actions :destroy
+  #     rhino_route_key :hash_id
   #   end
   module HasRhino
     extend ActiveSupport::Concern
@@ -39,6 +40,7 @@ module Rhino
       class_attribute :rhino_middleware_actions_map, default: {}
       class_attribute :rhino_except_actions_list, default: []
       class_attribute :rhino_owner_path, default: nil
+      class_attribute :rhino_route_key_column, default: nil
     end
 
     class_methods do
@@ -103,6 +105,36 @@ module Rhino
         self.rhino_except_actions_list = actions.map(&:to_s)
       end
 
+      # Column matched against the :id URL segment on member endpoints
+      # (show/update/destroy/restore/force_delete).
+      #   rhino_route_key :hash_id   # GET /api/jobs/{hash_id}
+      # Affects ONLY the URL-segment lookup — FK values in payloads, nested
+      # operation ids and audit references stay primary-key based.
+      def rhino_route_key(column)
+        self.rhino_route_key_column = column.to_s
+      end
+
+      # Resolve the effective route key for this model. Precedence:
+      # model-level +rhino_route_key+ → global +Rhino.config.route_key+ →
+      # primary key. O(1): class_attribute + config read; the column presence
+      # check uses ActiveRecord's cached +column_names+ (no queries).
+      #
+      # Raises ArgumentError when a configured key names a column that does
+      # not exist on the model — a clear failure instead of a silent 404.
+      def rhino_resolved_route_key
+        key = rhino_route_key_column.presence || Rhino.config.route_key.presence || primary_key
+        key = key.to_s
+
+        if key != primary_key.to_s && !column_names.include?(key)
+          raise ArgumentError,
+                "Invalid route key for #{name}: column '#{key}' does not exist on table " \
+                "'#{table_name}'. Check `rhino_route_key` on the model or the global " \
+                "`Rhino.config.route_key` setting."
+        end
+
+        key
+      end
+
       # Check if model uses soft deletes (Discard gem)
       def uses_soft_deletes?
         column_names.include?("discarded_at") || column_names.include?("deleted_at")

data/lib/rhino/concerns/hidable_columns.rb

@@ -103,6 +103,10 @@ module Rhino
       if permitted && permitted != ['*']
         permitted_set = Set.new(permitted.map(&:to_s))
         permitted_set.add('id') # id is always allowed
+        # The route key column is always allowed too — responses must stay
+        # routable even when a policy whitelist omits it.
+        route_key = self.class.try(:rhino_resolved_route_key)
+        permitted_set.add(route_key.to_s) if route_key
         result.select! { |key, _| permitted_set.include?(key) }
       end
 
@@ -168,6 +172,13 @@ module Rhino
         if permitted != ['*']
           all_columns = self.class.column_names
           not_permitted = all_columns - permitted.map(&:to_s)
+          # A configured route key is never hidden by a policy whitelist —
+          # responses must stay routable. Default path (route key == primary
+          # key) is intentionally untouched for backward compatibility.
+          route_key = self.class.try(:rhino_resolved_route_key)
+          if route_key && route_key.to_s != self.class.primary_key.to_s
+            not_permitted -= [route_key.to_s]
+          end
           hidden.concat(not_permitted)
         end
       end

data/lib/rhino/configuration.rb

@@ -4,6 +4,11 @@ module Rhino
   class Configuration
     attr_accessor :models, :route_groups, :multi_tenant, :invitations, :nested, :test_framework,
                   :client_path, :mobile_path
+    # Global default route key: the column matched against the :id URL segment
+    # on member endpoints (show/update/destroy/restore/force_delete) for every
+    # model that does not declare its own +rhino_route_key+. Default nil =
+    # primary key (today's behavior, fully backward compatible).
+    attr_accessor :route_key
     attr_reader :auth
 
     def initialize
@@ -27,6 +32,7 @@ module Rhino
       @test_framework = "rspec"
       @client_path = nil
       @mobile_path = nil
+      @route_key = nil
     end
 
     # Auth configuration accessor. Merges supplied keys over defaults so a host

data/lib/rhino/context.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Rhino
+  # Ambient tenant context resolver.
+  #
+  # Reads the current user/organization from RequestStore by default (request-time
+  # context set by the controller before_actions), but can be overridden for the
+  # duration of a block via +with+ — used by the explicit query builder so jobs,
+  # rake tasks, and tests can query without a route.
+  module Context
+    module_function
+
+    # The active organization: the explicit override if one is in effect, else the
+    # request-time organization from RequestStore.
+    def organization
+      if store.key?(:rhino_organization)
+        store[:rhino_organization]
+      elsif defined?(RequestStore)
+        RequestStore.store[:rhino_organization]
+      end
+    end
+
+    # The active user: the explicit override if one is in effect, else the
+    # request-time user from RequestStore.
+    def user
+      if store.key?(:rhino_current_user)
+        store[:rhino_current_user]
+      elsif defined?(RequestStore)
+        RequestStore.store[:rhino_current_user]
+      end
+    end
+
+    # Run +block+ with the given user/organization installed into RequestStore.
+    # Snapshots the prior RequestStore user+org, sets the new ones, yields, and
+    # restores the snapshot in an ensure. Returns the block's value.
+    def with(user:, organization:)
+      return yield unless defined?(RequestStore)
+
+      had_user = RequestStore.store.key?(:rhino_current_user)
+      had_org  = RequestStore.store.key?(:rhino_organization)
+      prev_user = RequestStore.store[:rhino_current_user]
+      prev_org  = RequestStore.store[:rhino_organization]
+
+      # Track the active override so Context.user/organization prefer it even when
+      # the passed value is nil (distinguishing "explicitly nil" from "absent").
+      had_override_user = store.key?(:rhino_current_user)
+      had_override_org  = store.key?(:rhino_organization)
+      prev_override_user = store[:rhino_current_user]
+      prev_override_org  = store[:rhino_organization]
+
+      RequestStore.store[:rhino_current_user] = user
+      RequestStore.store[:rhino_organization] = organization
+      store[:rhino_current_user] = user
+      store[:rhino_organization] = organization
+
+      begin
+        yield
+      ensure
+        if had_user
+          RequestStore.store[:rhino_current_user] = prev_user
+        else
+          RequestStore.store.delete(:rhino_current_user)
+        end
+        if had_org
+          RequestStore.store[:rhino_organization] = prev_org
+        else
+          RequestStore.store.delete(:rhino_organization)
+        end
+
+        if had_override_user
+          store[:rhino_current_user] = prev_override_user
+        else
+          store.delete(:rhino_current_user)
+        end
+        if had_override_org
+          store[:rhino_organization] = prev_override_org
+        else
+          store.delete(:rhino_organization)
+        end
+      end
+    end
+
+    # Fiber-local override store for the active explicit context.
+    def store
+      Thread.current[:rhino_context_override] ||= {}
+    end
+  end
+end

data/lib/rhino/controllers/resources_controller.rb

@@ -104,7 +104,8 @@ module Rhino
         return auth_response if auth_response
 
         builder = QueryBuilder.new(model_class, params: params)
-        builder.instance_variable_set(:@scope, model_class.where(id: record.id))
+        # record is already resolved via the route key; re-query by primary key
+        builder.instance_variable_set(:@scope, model_class.where(model_class.primary_key => record.id))
         apply_organization_scope(builder)
         builder.build
         record = builder.to_scope.first!
@@ -192,7 +193,7 @@ module Rhino
 
     # POST /api/{slug}/:id/restore
     def restore
-      record = model_class.discarded.find(params[:id])
+      record = find_by_route_key(model_class.discarded)
       authorize record, :restore?, policy_class: policy_for(record)
 
       record.undiscard!
@@ -203,7 +204,7 @@ module Rhino
 
     # DELETE /api/{slug}/:id/force-delete
     def force_delete
-      record = model_class.discarded.find(params[:id])
+      record = find_by_route_key(model_class.discarded)
       authorize record, :force_delete?, policy_class: policy_for(record)
 
       record.destroy!
@@ -446,61 +447,10 @@ module Rhino
       org = current_organization
       return unless org
 
-      # When the resource IS the Organization model
-      if org.class == model_class
-        builder.instance_variable_set(
-          :@scope,
-          builder.scope.where(model_class.primary_key => org.send(model_class.primary_key))
-        )
-        return
-      end
-
-      # Check for scopeForOrganization
-      if model_class.respond_to?(:for_organization)
-        builder.instance_variable_set(:@scope, model_class.for_organization(org))
-        return
-      end
-
-      # Check for organization_id column
-      if model_class.column_names.include?("organization_id")
-        builder.instance_variable_set(
-          :@scope,
-          builder.scope.where(organization_id: org.id)
-        )
-        return
-      end
-
-      # Auto-detect from belongs_to relationships
-      detected_path = discover_organization_path(model_class)
-      if detected_path.present?
-        apply_organization_scope_through_relationship(builder, org, detected_path)
-      end
-    end
-
-    def apply_organization_scope_through_relationship(builder, organization, relationship_path)
-      if relationship_path.include?(".")
-        # Nested path: 'post.blog' -> joins(post: :blog).where(blogs: { organization_id: org.id })
-        parts = relationship_path.split(".")
-        join_chain = parts.reverse.inject(:organization) { |inner, outer| { outer.to_sym => inner } }
-
-        builder.instance_variable_set(
-          :@scope,
-          builder.scope.joins(join_chain.is_a?(Symbol) ? join_chain : parts.first.to_sym => join_chain)
-                       .where(organizations: { id: organization.id })
-        )
-      else
-        # Single relationship
-        assoc = model_class.reflect_on_association(relationship_path.to_sym)
-        return unless assoc
-
-        if assoc.klass.column_names.include?("organization_id")
-          builder.instance_variable_set(
-            :@scope,
-            builder.scope.joins(relationship_path.to_sym)
-                         .where(assoc.klass.table_name => { organization_id: organization.id })
-          )
-        end
-      end
+      builder.instance_variable_set(
+        :@scope,
+        Rhino::ScopesToOrganization.scope_to_organization(builder.scope, model_class, org)
+      )
     end
 
     def add_organization_to_data(data)
@@ -515,9 +465,10 @@ module Rhino
     # Recursively discover the relationship path from a model to Organization
     # by introspecting BelongsTo associations. Returns dot-notation path or nil.
     #
-    # Results are cached per model class to avoid repeated reflection.
+    # The recursion itself lives in Rhino::ScopesToOrganization (the extracted,
+    # pure implementation) so the controller and the custom-query resolver share
+    # one code path. The controller keeps its own per-class cache for back-compat.
     def discover_organization_path(klass, visited = [], max_depth = 3)
-      # Return cached result (including nil)
       if @@organization_path_cache.key?(klass.name)
         return @@organization_path_cache[klass.name]
       end
@@ -528,65 +479,7 @@ module Rhino
     end
 
     def _discover_organization_path_recursive(klass, visited, max_depth)
-      return nil if max_depth <= 0 || visited.include?(klass.name)
-
-      visited = visited + [klass.name]
-
-      begin
-        associations = klass.reflect_on_all_associations(:belongs_to)
-      rescue StandardError
-        return nil
-      end
-
-      matching_paths = []
-
-      associations.each do |assoc|
-        begin
-          related_class = assoc.klass
-        rescue StandardError
-          next
-        end
-
-        # Direct match: related model IS Organization
-        if related_class.name == "Organization"
-          matching_paths << assoc.name.to_s
-          next
-        end
-
-        # Related model has organization_id column
-        begin
-          if related_class.column_names.include?("organization_id")
-            matching_paths << assoc.name.to_s
-            next
-          end
-        rescue StandardError
-          # Table may not exist yet
-        end
-
-        # Related model includes BelongsToOrganization concern
-        if related_class.include?(Rhino::BelongsToOrganization)
-          matching_paths << assoc.name.to_s
-          next
-        end
-
-        # Recurse into related model's BelongsTo associations
-        sub_path = _discover_organization_path_recursive(related_class, visited, max_depth - 1)
-        if sub_path.present?
-          matching_paths << "#{assoc.name}.#{sub_path}"
-        end
-      end
-
-      return nil if matching_paths.empty?
-
-      if matching_paths.length > 1
-        Rails.logger&.debug(
-          "Rhino: Model #{klass.name} has multiple BelongsTo paths to Organization. " \
-          "Using '#{matching_paths[0]}'. " \
-          "Paths found: #{matching_paths.inspect}"
-        )
-      end
-
-      matching_paths[0]
+      Rhino::ScopesToOrganization._discover_organization_path_recursive(klass, visited, max_depth)
     end
 
     # ------------------------------------------------------------------
@@ -601,7 +494,32 @@ module Rhino
         scope = scope.where(organization_id: org.id)
       end
 
-      scope.find(params[:id])
+      find_by_route_key(scope)
+    end
+
+    # Column matched against the :id URL segment. Resolution chain:
+    # model's rhino_route_key → Rhino.config.route_key → primary key.
+    # O(1) — class_attribute + config read, no queries.
+    def route_key_for(model_class)
+      if model_class.respond_to?(:rhino_resolved_route_key)
+        model_class.rhino_resolved_route_key
+      else
+        model_class.primary_key
+      end
+    end
+
+    # Look up params[:id] within +scope+ using the resolved route key.
+    # Default path (route key == primary key) uses .find — byte-identical to
+    # the historical behavior. Configured path uses .find_by!, which raises
+    # ActiveRecord::RecordNotFound with the same 404 semantics.
+    def find_by_route_key(scope)
+      key = route_key_for(model_class)
+
+      if key.to_s == model_class.primary_key.to_s
+        scope.find(params[:id])
+      else
+        scope.find_by!(key => params[:id])
+      end
     end
 
     # ------------------------------------------------------------------

data/lib/rhino/missing_tenant_context.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Rhino
+  # Raised by Rhino.query (and the explicit builder) when an organization-scopable
+  # model is queried with no organization context available. Fail-closed: the
+  # resolver never returns an unscoped relation for a tenant-scopable model.
+  class MissingTenantContext < StandardError; end
+end

data/lib/rhino/models/rhino_model.rb

@@ -293,6 +293,30 @@ module Rhino
     #     rhino_except_actions :store, :update, :destroy
     self.rhino_except_actions_list = []
 
+    # =========================================================================
+    # ROUTE KEY
+    # =========================================================================
+
+    # @!attribute [rw] rhino_route_key_column
+    #   Column matched against the +:id+ URL segment on member endpoints
+    #   (show, update, destroy, restore, force-delete).
+    #
+    #   Default +nil+ = fall back to the global +Rhino.config.route_key+, then
+    #   the primary key (today's behavior). Affects ONLY the URL-segment
+    #   lookup — foreign keys in payloads, nested-operation ids and audit
+    #   references stay primary-key based.
+    #
+    #   Set via DSL: +rhino_route_key :hash_id+
+    #
+    #   Query: +GET /api/jobs/{hash_id}+
+    #
+    #   @return [String, nil]
+    #   @example
+    #     rhino_route_key :hash_id
+    #   @example Direct assignment
+    #     self.rhino_route_key_column = 'hash_id'
+    self.rhino_route_key_column = nil
+
     # =========================================================================
     # OWNERSHIP / MULTI-TENANCY
     # =========================================================================

data/lib/rhino/query.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Rhino
+  # Reusable tenant-safe query resolver for custom controllers (dashboards,
+  # reports, anything beyond CRUD). Mirrors the Laravel Rhino::query feature.
+  #
+  # Two ways to use it:
+  #
+  #   # Direct / ambient — org + user from the request context (RequestStore)
+  #   Rhino.query(Task)
+  #
+  #   # Explicit — works in jobs/rake/tests with NO route; org scope comes from
+  #   # the passed org, not the request:
+  #   Rhino.for_user(user).in_organization(org).query(Task)
+  #   Rhino.for_user(user).in_organization(org).run { ... }
+  class << self
+    # Build a tenant-scoped relation for +model_class+ using the ambient context.
+    #
+    # Applies the same org scoping as CRUD plus the model's default_scopes
+    # (BelongsToOrganization / HasAutoScope read RequestStore at BUILD time).
+    #
+    # Fail closed: an org-scopable model with no org context RAISES
+    # Rhino::MissingTenantContext rather than returning an unscoped relation.
+    def query(model_class)
+      org = Rhino::Context.organization
+
+      # default_scope (org via RequestStore) + auto-scope are baked here at build.
+      relation = model_class.all
+
+      if Rhino::ScopesToOrganization.organization_scoped?(model_class)
+        raise Rhino::MissingTenantContext, model_class.name unless org
+
+        relation = Rhino::ScopesToOrganization.scope_to_organization(relation, model_class, org, strict: true)
+      end
+
+      relation
+    end
+
+    # Build a tenant-scoped relation and apply a whitelisted ?scope= named scope
+    # on top of it. +scope_name+ is the wire name (camelCase accepted); nil falls
+    # back to the model's rhino_default_scope.
+    def scoped_query(model_class, scope_name = nil)
+      apply_named_scope(query(model_class), model_class, scope_name)
+    end
+
+    # Begin the fluent explicit builder for +user+.
+    def for_user(user)
+      Rhino::PendingScopedContext.new(user: user)
+    end
+
+    # The ambient context resolver.
+    def context
+      Rhino::Context
+    end
+
+    # Apply a whitelisted named scope to +relation+ for +model_class+.
+    # Shared by Rhino.scoped_query and PendingScopedContext#scoped_query. Uses the
+    # same allowed_scopes / default_rhino_scope mechanism as the QueryBuilder.
+    # @api private
+    def apply_named_scope(relation, model_class, scope_name = nil)
+      requested = scope_name.to_s.presence
+      name = requested ? requested.underscore : model_class.try(:default_rhino_scope)
+      return relation unless name
+
+      allowed = model_class.try(:allowed_scopes) || {}
+      entry = allowed[name]
+      entry ||= name.to_sym if name == model_class.try(:default_rhino_scope)
+
+      raise Rhino::ScopeNotAllowedError, (requested || name) if entry.nil?
+
+      user = defined?(RequestStore) ? RequestStore.store[:rhino_current_user] : nil
+
+      case entry
+      when Symbol
+        relation.merge(model_class.public_send(entry))
+      when Proc
+        entry.call(relation, user)
+      else
+        entry.new.apply(relation)
+      end
+    end
+  end
+
+  # Fluent explicit-context builder. Holds a user (and, once chained, an org) and
+  # resolves queries with that context installed into RequestStore at build time.
+  class PendingScopedContext
+    def initialize(user:, organization: nil)
+      @user = user
+      @organization = organization
+    end
+
+    def in_organization(organization)
+      @organization = organization
+      self
+    end
+
+    # Build a fully-baked relation for +model_class+ under this explicit context.
+    #
+    # Because Rails default_scopes bake at BUILD time, we install the user+org into
+    # RequestStore, build the relation via Rhino.query, then restore RequestStore.
+    # The org+user are baked into the returned relation — no stickiness, fully
+    # isolated: a later Rhino.query with no context still fails closed.
+    def query(model_class)
+      Rhino::Context.with(user: @user, organization: @organization) do
+        Rhino.query(model_class)
+      end
+    end
+
+    # Build a fully-baked, named-scoped relation under this explicit context.
+    def scoped_query(model_class, scope_name = nil)
+      Rhino::Context.with(user: @user, organization: @organization) do
+        Rhino.scoped_query(model_class, scope_name)
+      end
+    end
+
+    # Run +block+ with the explicit context installed into RequestStore. Queries
+    # inside the block see the context; RequestStore is restored afterward.
+    # Returns the block's value.
+    def run(&block)
+      Rhino::Context.with(user: @user, organization: @organization, &block)
+    end
+  end
+end

data/lib/rhino/query_builder.rb

@@ -232,6 +232,12 @@ module Rhino
       if valid_fields.any?
         # Always include the primary key
         valid_fields.unshift(model_class.primary_key) unless valid_fields.include?(model_class.primary_key)
+        # Also include the configured route key — sparse responses must stay
+        # routable. No-op in the default path (route key == primary key).
+        route_key = model_class.try(:rhino_resolved_route_key)
+        if route_key && route_key.to_s != model_class.primary_key.to_s && !valid_fields.include?(route_key.to_s)
+          valid_fields << route_key.to_s
+        end
         @scope = @scope.select(valid_fields.map { |f| "#{model_class.table_name}.#{f}" })
       end
     end

data/lib/rhino/scopes_to_organization.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Rhino
+  # Pure organization-scoping logic, extracted from ResourcesController so it can
+  # be reused by the custom-query resolver (Rhino.query / Rhino.for_user...).
+  #
+  # Every method takes a RELATION and RETURNS a scoped relation — it never mutates
+  # a QueryBuilder's @scope. The scoping order MUST match the controller exactly:
+  #   1. Organization-is-self (the model IS the Organization)
+  #   2. for_organization (scopeForOrganization)
+  #   3. organization_id column
+  #   4. auto-detected belongs_to relationship path (incl. nested, e.g. post.blog)
+  module ScopesToOrganization
+    # Cache for auto-detected organization paths (survives across calls, keyed by
+    # model class name). Mirrors the controller's @@organization_path_cache.
+    @organization_path_cache = {}
+
+    module_function
+
+    # Apply organization scoping to +relation+ for +model_class+, returning the
+    # scoped relation. Behavior-equivalent to the controller's
+    # apply_organization_scope, but returning instead of mutating a builder.
+    def scope_to_organization(relation, model_class, organization, strict: false)
+      return relation unless organization
+
+      # When the resource IS the Organization model
+      if organization.class == model_class
+        return relation.where(
+          model_class.primary_key => organization.send(model_class.primary_key)
+        )
+      end
+
+      # Check for scopeForOrganization
+      if model_class.respond_to?(:for_organization)
+        return model_class.for_organization(organization)
+      end
+
+      # Check for organization_id column
+      if model_class.column_names.include?("organization_id")
+        return relation.where(organization_id: organization.id)
+      end
+
+      # Auto-detect from belongs_to relationships
+      detected_path = discover_organization_path(model_class)
+      if detected_path.present?
+        return scope_through_relationship(relation, model_class, organization, detected_path, strict: strict)
+      end
+
+      # No mechanism could be applied. In strict mode (the resolver) a model that
+      # reached here after being classified organization_scoped? must NOT return
+      # unscoped — fail closed instead of leaking across tenants.
+      raise Rhino::MissingTenantContext, model_class.name if strict && organization_scoped?(model_class)
+
+      relation
+    end
+
+    # Whether +model_class+ has any organization-scoping mechanism at all. Used by
+    # the resolver to decide whether missing org context must fail closed. On an
+    # unexpected classification error we fail CLOSED (treat as scopable) so the
+    # resolver raises rather than silently returning unscoped rows.
+    def organization_scoped?(model_class)
+      return true if model_class.respond_to?(:for_organization)
+      return true if model_class.column_names.include?("organization_id")
+
+      discover_organization_path(model_class).present?
+    rescue StandardError
+      true
+    end
+
+    def scope_through_relationship(relation, model_class, organization, relationship_path, strict: false)
+      if relationship_path.include?(".")
+        # Nested path: 'post.blog' -> joins(post: :blog).where(organizations: { id: org.id })
+        parts = relationship_path.split(".")
+        join_chain = parts.reverse.inject(:organization) { |inner, outer| { outer.to_sym => inner } }
+
+        relation.joins(join_chain.is_a?(Symbol) ? join_chain : parts.first.to_sym => join_chain)
+                .where(organizations: { id: organization.id })
+      else
+        # Single relationship
+        assoc = model_class.reflect_on_association(relationship_path.to_sym)
+        if assoc.nil?
+          # Classified scopable but the association vanished — fail closed for the
+          # resolver; stay lenient for the controller's legacy path.
+          raise Rhino::MissingTenantContext, model_class.name if strict
+
+          return relation
+        end
+
+        if assoc.klass.column_names.include?("organization_id")
+          relation.joins(relationship_path.to_sym)
+                  .where(assoc.klass.table_name => { organization_id: organization.id })
+        elsif strict
+          # Path leads somewhere without an organization_id column, so no filter
+          # can be applied — fail closed rather than return every tenant's rows.
+          raise Rhino::MissingTenantContext, model_class.name
+        else
+          relation
+        end
+      end
+    end
+
+    # Recursively discover the relationship path from a model to Organization by
+    # introspecting BelongsTo associations. Returns dot-notation path or nil.
+    # Results are cached per model class to avoid repeated reflection.
+    def discover_organization_path(klass, visited = [], max_depth = 3)
+      if @organization_path_cache.key?(klass.name)
+        return @organization_path_cache[klass.name]
+      end
+
+      result = _discover_organization_path_recursive(klass, visited, max_depth)
+      # Only cache a positive result. Caching a transient nil (associations/tables
+      # not yet resolvable under Zeitwerk lazy-loading) would permanently
+      # misclassify a genuinely org-scoped model as global — a fail-open leak.
+      # Mirrors HasAutoScope's non-nil caching.
+      @organization_path_cache[klass.name] = result if result
+      result
+    end
+
+    def _discover_organization_path_recursive(klass, visited, max_depth)
+      return nil if max_depth <= 0 || visited.include?(klass.name)
+
+      visited = visited + [klass.name]
+
+      begin
+        associations = klass.reflect_on_all_associations(:belongs_to)
+      rescue StandardError
+        return nil
+      end
+
+      matching_paths = []
+
+      associations.each do |assoc|
+        begin
+          related_class = assoc.klass
+        rescue StandardError
+          next
+        end
+
+        # Direct match: related model IS Organization
+        if related_class.name == "Organization"
+          matching_paths << assoc.name.to_s
+          next
+        end
+
+        # Related model has organization_id column
+        begin
+          if related_class.column_names.include?("organization_id")
+            matching_paths << assoc.name.to_s
+            next
+          end
+        rescue StandardError
+          # Table may not exist yet
+        end
+
+        # Related model includes BelongsToOrganization concern
+        if defined?(Rhino::BelongsToOrganization) && related_class.include?(Rhino::BelongsToOrganization)
+          matching_paths << assoc.name.to_s
+          next
+        end
+
+        # Recurse into related model's BelongsTo associations
+        sub_path = _discover_organization_path_recursive(related_class, visited, max_depth - 1)
+        if sub_path.present?
+          matching_paths << "#{assoc.name}.#{sub_path}"
+        end
+      end
+
+      return nil if matching_paths.empty?
+
+      if matching_paths.length > 1
+        Rails.logger&.debug(
+          "Rhino: Model #{klass.name} has multiple BelongsTo paths to Organization. " \
+          "Using '#{matching_paths[0]}'. " \
+          "Paths found: #{matching_paths.inspect}"
+        )
+      end
+
+      matching_paths[0]
+    end
+  end
+end

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

@@ -27,6 +27,8 @@ class <%= name %> < Rhino::RhinoModel
 <% unless include_cols.empty? -%>
   rhino_includes <%= include_cols.map { |c| ":#{c}" }.join(", ") %>
 <% end -%>
+  # Match the :id URL segment against another column (default: primary key):
+  # rhino_route_key :hash_id
 
   # ---------------------------------------------------------------
   # Validation (ActiveModel — use allow_nil: true for all validators)

data/lib/rhino/templates/rhino.rb

@@ -79,6 +79,17 @@ Rhino.configure do |config|
   # Permissions then resolve from that matching membership row.
   # config.auth = { enforce_group_membership: false }
 
+  # ---------------------------------------------------------------
+  # Route Key
+  # ---------------------------------------------------------------
+  # Global default for which column matches the :id URL segment on member
+  # endpoints (show, update, destroy, restore, force-delete). Default nil =
+  # primary key. Individual models can override with `rhino_route_key :column`.
+  # Affects only URL lookups — foreign keys in payloads and nested-operation
+  # ids stay primary-key based.
+  #
+  # config.route_key = 'hash_id'  # GET /api/jobs/{hash_id}
+
   # ---------------------------------------------------------------
   # Invitations
   # ---------------------------------------------------------------

data/lib/rhino/templates/rhino_model.rb

@@ -66,6 +66,15 @@ class RhinoModel < Rhino::RhinoModel
   # rhino_includes :user, :comments, :tags
   # rhino_search  :title, :content, :excerpt
 
+  # -----------------------------------------------------------------
+  # Route Key
+  # -----------------------------------------------------------------
+  #
+  # Match the :id URL segment against a column other than the primary key
+  # on member endpoints (show/update/destroy/restore/force-delete):
+  #
+  # rhino_route_key :hash_id   # GET /api/jobs/{hash_id}
+
   # -----------------------------------------------------------------
   # Pagination
   # -----------------------------------------------------------------

data/lib/rhino/version.rb

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

data/lib/rhino.rb

@@ -4,9 +4,13 @@ require "rhino/version"
 require "rhino/configuration"
 require "rhino/auth_rejected"
 require "rhino/scope_not_allowed_error"
+require "rhino/missing_tenant_context"
 require "rhino/auth_hooks"
 require "rhino/group_membership"
 require "rhino/resource_scope"
+require "rhino/scopes_to_organization"
+require "rhino/context"
+require "rhino/query"
 require "rhino/routing/domain_constraint"
 require "rhino/routing/route_group_validator"
 require "rhino/middleware/resolve_organization_from_route"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rhino-rails
 version: !ruby/object:Gem::Version
-  version: 4.4.0
+  version: 4.6.0
 platform: ruby
 authors:
 - Bruno Cipolla
@@ -216,6 +216,7 @@ files:
 - lib/rhino/concerns/has_validation.rb
 - lib/rhino/concerns/hidable_columns.rb
 - lib/rhino/configuration.rb
+- lib/rhino/context.rb
 - lib/rhino/controllers/auth_controller.rb
 - lib/rhino/controllers/invitations_controller.rb
 - lib/rhino/controllers/resources_controller.rb
@@ -223,12 +224,14 @@ files:
 - lib/rhino/group_membership.rb
 - lib/rhino/mailers/invitation_mailer.rb
 - lib/rhino/middleware/resolve_organization_from_route.rb
+- lib/rhino/missing_tenant_context.rb
 - lib/rhino/models/audit_log.rb
 - lib/rhino/models/organization_invitation.rb
 - lib/rhino/models/rhino_model.rb
 - lib/rhino/permissions_migrator.rb
 - lib/rhino/policies/invitation_policy.rb
 - lib/rhino/policies/resource_policy.rb
+- lib/rhino/query.rb
 - lib/rhino/query_builder.rb
 - lib/rhino/railtie.rb
 - lib/rhino/resource_scope.rb
@@ -236,6 +239,7 @@ files:
 - lib/rhino/routing/domain_constraint.rb
 - lib/rhino/routing/route_group_validator.rb
 - lib/rhino/scope_not_allowed_error.rb
+- lib/rhino/scopes_to_organization.rb
 - lib/rhino/tasks/rhino.rake
 - lib/rhino/templates/audit_trail/create_audit_logs.rb.erb
 - lib/rhino/templates/generate/factory.rb.erb