rhino-rails 4.5.0 → 4.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecffad187ec69c47659219d1eb766247a82ce666a662be9a32c3d88afe4bd48c
-  data.tar.gz: 1ccb038bc991c74d4338b84a20280b38660f1ec959552b3546625de855f37969
+  metadata.gz: 3c800a5e70d40849b886fdd638cc4214fa4bd782965de5a94394a6fa0319cb38
+  data.tar.gz: e967104d44d640b9645f579022f14831d36150e763497e25ecfbd2b391ec76b1
 SHA512:
-  metadata.gz: 242a0d4672911f646bd9dc62dcfa6bd0641caed3ec88af8f62dea657f146e0d019f80d9cbe769fb9e7415c611e709946c1aeb01af4eeb1871ca590ea2533b866
-  data.tar.gz: ea611e79054413e6322dd44a2a141aa01a0791a8eb48d13e4dd8311c03821c8195fb7befd598840d63401355a3fd4819f7b4506afd6486d38d5a0fedef48a5e4
+  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/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!
@@ -493,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/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_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/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.5.0"
+  VERSION = "4.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rhino-rails
 version: !ruby/object:Gem::Version
-  version: 4.5.0
+  version: 4.6.0
 platform: ruby
 authors:
 - Bruno Cipolla