jpie 3.10.1 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aee1da20dd3c81baafa8bcb78801d128f2b59f76be85b12216f96bf35b822344
-  data.tar.gz: 7de107c0fd9ea459ad0f7015d7b0a6877e88462f81b9900cdf022d14788a8118
+  metadata.gz: fd3d3cf0f731b0a5d47d2e0ae3b4fc405d7b49ae775da39baf04a3f862b06d3b
+  data.tar.gz: 2d305cd5e41bb20cc5ef36fdf0321407425e503fee2a7424f40035cb9fda0059
 SHA512:
-  metadata.gz: 6639e6a66ac7c37cbf50372b433f9b1be772d6e1bda28cd76edbfb4a15612c6307bb9412894e0c6eede135aa6e0de321c2726cf3eda493381f746153ff6dd4fc
-  data.tar.gz: 1998a903147f3737344b172459656dbb2638525d0371aac16c6951a8c519334ee4ddae641a7a260d200cd41d1c4ea480202bfd476bb930a1f55a8165d1ce4a07
+  metadata.gz: beeb386f1743ca01b78a5532925d16115b66ca94ae00f31b1b94118c7b0bdf63367e00242593b78e62cd891c7e497cc00b722ee17d6fa37b724f2de5aa40d178
+  data.tar.gz: e6362ed9996bec7dedabf0891e9a50a4ff80f240829cf6f7e08decf4b4ddf5d29c139f6e71eb88de1a53648449c416907a81c7f73dee1134e49a4b8704ca5063

data/CHANGELOG.md

@@ -7,6 +7,161 @@ at release time.
 
 ## [Unreleased]
 
+## [4.0.0] - 2026-09-09
+
+### Changed
+
+- **Breaking. A namespace serves only what it declares.** A namespaced request
+  used to fall back to the flat resource when the namespaced one was missing —
+  for the primary type, and for every `?include=` hop. On a public namespace
+  that published the internal resource's records and attributes to an
+  anonymous caller, and an STI record slipped to its base class's flat
+  resource even where the namespace carried a base resource. The fallback is
+  gone, and `config.namespace_fallback` with it. A namespaced request resolves
+  the namespaced resource alone. A route whose namespace carries no resource
+  fails at draw time — the app does not boot — because `jsonapi_resources`
+  resolves the resource while routes load. An include hop the namespace
+  cannot answer is a 400 at validation, before the record loads; a
+  polymorphic hop, which validation cannot judge, answers 400 (or 404 on a
+  relationships route) when a record's class resolves nothing at
+  serialization. A namespaced model still
+  reaches the resource in its own namespace, and an STI record answers
+  through the request namespace's resource for its own class, then its base
+  class. To keep serving a flat resource inside a namespace, declare it:
+  `class API::V1::WidgetResource < WidgetResource; end`. That line is the
+  audit trail. Release this as a major version.
+
+  The relationships routes obey the same rule: the linkage and related-record
+  scopes resolve through the request namespace's resource, where they used to
+  resolve with no namespace at all. Write-path linkage lookups (deserializing
+  a relationship's resource identifiers) still resolve without a namespace;
+  a bound write surface gates those through its declared field lists.
+- Read the outer hash when neither it nor its `data` member names a `type`.
+  `JSONAPI::Deserializer.new(data: { attributes: { … } })` used to read the
+  nested member; it now reads the outer hash and finds no attributes. Such a
+  hash is neither a document nor a resource object, because JSON:API requires
+  `type` in every resource object. Name the `type` to keep the old result.
+- Answer `{}` instead of raising `TypeError` for a document whose `data` member
+  holds an array. `dig(:data, :attributes)` raised on the array.
+- Read a declared write list as the complete allow-list for relationships. jpie
+  gated a relationship only when the resource named it in `creatable_fields` or
+  `updatable_fields`. A relationship named in neither stayed writable, so a
+  resource that declared an allow-list of attributes still accepted any
+  relationship the client sent. The client re-pointed a row it did not own. A
+  resource that declares the list for an action now refuses a relationship the
+  list omits.
+
+  This refuses writes jpie used to accept. Check every resource that calls
+  `creatable_fields` or `updatable_fields` and names no relationship, and every
+  subclass of one, because a subclass that declares nothing reads its parent's
+  lists. A client that writes a relationship on such a resource now meets 403
+  Forbidden. Name the relationship in the list to keep the write.
+
+  Two shapes are unaffected. A resource that declares no list falls back to the
+  attribute list, which names no relationship, so failing closed there would
+  refuse every resource that never stated an opinion. An override of
+  `permitted_creatable_fields` or `permitted_updatable_fields` is not a
+  declaration either: an override that adjusts the inherited list, such as
+  `super - [:role]`, returns a plain array, the same as one that states a fresh
+  list, so jpie cannot tell the two apart. On both shapes, `readonly: true`
+  still stops a write.
+- **Breaking. Cut the public API.** Hold a relationship route to the `only:`
+  and `except:` the caller gives `jsonapi_resources`. Each verb stands on a
+  member action: `GET` on `:show`, and `PATCH` and `DELETE` both on
+  `:update` — a relationship `DELETE` removes members from the relationship,
+  the controller authorizes it as an update, and the primary record survives,
+  so `:destroy` plays no part. Before this, `only:` cut the member routes and
+  left all three relationship routes whole, so a caller who omitted `:update`
+  still got `PATCH /:type/:id/relationships/:relationship_name`. The
+  relationships controller authorizes the parent record alone, so the omitted
+  member action did no work there and the write landed. The base route of an
+  `sti:` set carries `only: :index`, so it now draws no relationship route.
+  The `:relationship` path helper hangs on the first verb drawn, so it
+  survives without `:show`. Release this as a major version.
+
+  An STI subtype route that states no options of its own now inherits the
+  caller's `only:`/`except:` as well — auto-drawn subtypes and bare explicit
+  entries used to draw every route whatever the caller restricted. A hash
+  subtype entry keeps its own declaration.
+
+  Regenerate the OpenAPI document with the route audit: a consumer that
+  documents relationship routes carries phantom operations for every verb
+  this removes.
+
+  Audit every `jsonapi_resources` line before the bump: a declaration without
+  `:update` loses relationship `PATCH` and `DELETE`, and one without `:show`
+  loses relationship `GET`. Measured against kiln's route table, 60 of 112
+  declarations lose at least one relationship verb — most of them read-only
+  template, suggestion, and public-portal surfaces, which is the point of the
+  change. A caller who wants a relationship verb back must name its member
+  action.
+- Skip strictly less with `skip_before_action :load_jsonapi_resource`: the
+  callback now loads the record alone, so a controller that skips it still
+  resolves the resource class and still validates `include`, `fields` and
+  `filter`. On a typed route a bad `include` answers 400 where it used to
+  raise over a nil resource class.
+- Answer 404, not a NoMethodError 500, for a hand-drawn route whose resource
+  type resolves to no class — the same answer the relationships controller
+  already gives. `jsonapi_resources` resolves the resource at draw time, so
+  only a hand-drawn route reaches this.
+- Validate `include`, `fields` and `filter` before the record loads. The loader
+  ran first and built its query from the client's `include`, so a path the gem
+  then rejected with 400 had already read the record and preloaded every hop.
+  A `show` with `include=posts.comments.invalid_association` ran three queries
+  and threw the rows away; it now runs none. On a public endpoint an anonymous
+  caller no longer reaches the database with an unchecked `include`.
+- Answer 400, not 404, when a request carries both a bad `include` and a
+  missing id. The server must understand a request before it can report the
+  record absent, and JSON:API requires 400 for an include path it cannot
+  resolve. A 404 here tells the caller the record is missing when the server
+  never asked.
+
+### Fixed
+
+- Read a declared write list through the whole ancestor chain. Only the
+  direct subclass of a declaring resource inherited its
+  `creatable_fields`/`updatable_fields`; a grandchild fell open to the
+  attribute fallback and wrote any relationship. Any ancestor's declaration
+  now counts, and resolution still reads through the superclass, so an
+  intermediate reader override keeps its say at every level.
+- Read `attributes` and `relationships` from the resource object, not from a
+  `data` member nested inside it. The deserializer took the nested pair first,
+  and the controllers hand it the resource object, which the client writes. A
+  client nested a second `data` member and wrote fields that never appeared
+  where a host application's guard reads them. `type` now decides the shape:
+  JSON:API requires it in every resource object and names no `type` among the
+  members of a document. A hash that carries `type` is the resource object, and
+  the deserializer unwraps `data` only for a hash that carries no `type` over a
+  `data` member that carries one.
+
+## [3.11.0]
+
+### Changed
+
+- Read a model-backed attribute with `has_attribute?` and `read_attribute`.
+  The serializer called `ActiveRecord#attributes` three times per attribute per
+  record, and each call builds a hash of every column. A record with a fat text
+  column paid for that column on all three.
+- Drop the per-record objects in the include walk. Each visited record
+  allocated a struct, a hash copy of the path context, and an empty keyword
+  hash; the attachment verdict now lifts out of the loop. The relationship
+  names an include path asks for are computed once per path, not once per
+  record.
+- Precompute each include path's walk once per request. The walk re-split and
+  re-joined the path strings at every level for every parent record.
+- Look a relationship definition up through a name-keyed index. The linear
+  scan converted every entry's name on every lookup, once per record per hop.
+- Memoize the ActiveStorage attachment verdict per class and name. The
+  reflection lookup allocated a string per call, per relationship per record.
+- Resolve a model's resource class and type name through identity-keyed front
+  caches. The name-keyed caches allocated their key strings on every call.
+- Serialize a record through one resource instance. The attribute reader and
+  the meta reader each built their own, so a resource's memoized reads ran
+  twice.
+- Skip the respond_to? probe on a loaded singular association target. The
+  probe walked ActiveModel's attribute matcher and allocated a string per
+  record.
+
 ## [3.10.1]
 
 ### Fixed

data/README.md

@@ -143,6 +143,42 @@ class UserResource < JSONAPI::Resource
 end
 ```
 
+A declared list is the complete allow-list. It names relationships as well as
+attributes, so the resource above lets a client write no relationship at all.
+Name a relationship in the list to let a client write it:
+
+```ruby
+class UserResource < JSONAPI::Resource
+  attributes :name, :email
+  has_many :teams
+
+  creatable_fields :name, :email, :teams
+  updatable_fields :name, :teams
+end
+```
+
+Name a relationship in one list and not the other to make it create-only or
+update-only. A client that writes a relationship the action's list omits meets
+403 Forbidden. An omitted attribute is not an error: the deserializer drops it
+and the request answers 200.
+
+`creatable_fields` and `updatable_fields` are the only way to declare a list. A
+subclass that declares nothing reads its parent's lists and closes the same
+relationships.
+
+A resource that declares no list for an action keeps every relationship
+writable, because the fallback list is the attribute list, which names no
+relationship. Mark a relationship `readonly: true` to stop a write there.
+
+An override of `permitted_creatable_fields` or `permitted_updatable_fields` is
+not a declaration, and it leaves every relationship writable. An override that
+adjusts the inherited list — `super - [:role]` — returns a plain array, the same
+as one that states a fresh list, so jpie cannot tell the two apart. Call the DSL
+to close the list.
+
+The gate never runs for an ActiveStorage attachment, so a `has_one` backed by
+`has_one_attached` needs no entry in either list.
+
 ## Relationship Endpoints
 
 Manage relationship links independently of the parent resource. This will not delete the related resource itself, but only manage the relationship.
@@ -153,6 +189,15 @@ If the relationship is `User -(has_one)-> AccountUser -(belong_to)-> Account` an
 - `PATCH /users/:id/relationships/:relationship_name` - Replace relationship linkage
 - `DELETE /users/:id/relationships/:relationship_name` - Remove relationship linkage
 
+Each verb stands on a member action, so `only:` and `except:` govern it. `GET` stands on `:show`. `PATCH` and `DELETE` both stand on `:update`, because a relationship `DELETE` removes members from the relationship — the controller authorizes it as an update, and the primary record survives — so `:destroy` plays no part. A declaration that omits the member action grants no relationship path for its verbs:
+
+```ruby
+# Draws relationship GET alone: :update is omitted, so no PATCH and no DELETE.
+jsonapi_resources :posts, only: %i[index show create destroy]
+```
+
+The `:relationship` path helper hangs on the first verb drawn, so it survives a declaration that keeps a write verb and drops `:show`.
+
 ## Filtering
 
 Declare permitted filters in your resource class:
@@ -853,10 +898,6 @@ JSONAPI.configure do |config|
   # :same_namespace -> API::V1::VendorResource maps to API::V1::Vendor
   # :flat           -> API::V1::VendorResource maps to Vendor
   config.namespace_model_mapping = :same_namespace
-
-  # Fallback behavior when namespaced resource not found: true (default) or false
-  # When true, if API::V1::VendorResource not found, try VendorResource
-  config.namespace_fallback = true
 end
 ```
 
@@ -878,15 +919,35 @@ end
 This will:
 
 - Look for `API::V1::WidgetsController` (falls back to `JSONAPI::ResourcesController` if not found)
-- Load `API::V1::WidgetResource` (falls back to `WidgetResource` if `namespace_fallback: true`)
+- Load `API::V1::WidgetResource`
 - Pass `jsonapi_namespace: "api/v1"` to the controller
 
 The request namespace also selects the resource class during serialization: for
 the attributes, the include filter, the links, and the relationship linkage.
 `GET /portal/posts` serializes with `Portal::PostResource` even when the `Post`
-model is flat. When the namespaced resource does not exist, the loader falls
-back to the model's own namespace, then to the flat resource. Set
-`config.namespace_fallback = false` to refuse the flat fallback.
+model is flat.
+
+A namespace serves only what it declares. A namespaced request never resolves a
+flat resource: a route whose namespace carries no resource fails at draw time
+(the app does not boot), and an `?include=` hop the namespace cannot answer is
+a 400 at validation, before anything loads. For a namespaced model, both name
+shapes answer — `Pub::ItemResource` and `Pub::DepotItemResource` for
+`Depot::Item` — so the class a `MissingResourceClass` message names is always
+a working declaration. To serve a flat resource inside a
+namespace, declare it:
+
+```ruby
+class API::V1::WidgetResource < WidgetResource; end
+```
+
+That one line is the review trail: the namespace's public surface is exactly
+the set of resource classes defined in it. Two shapes need no declaration — a
+namespaced model still reaches the resource in its own namespace, and an STI
+record answers through the request namespace's resource for its own class,
+then for its base class, so one base resource covers every subclass.
+ActiveStorage attachments answer through the blob resource and are exempt.
+Polymorphic include hops cannot be judged at validation; each record's class
+resolves at serialization and raises if the namespace cannot answer it.
 
 #### Namespaced Resources
 

data/lib/json_api/active_storage/detection.rb

@@ -1,17 +1,35 @@
 # frozen_string_literal: true
 
+require "concurrent/map"
+
 module JSONAPI
   module ActiveStorage
     module Detection
+      # The reflection lookup allocates a string per call, and the serializer
+      # asks per relationship per record. The verdict is a function of the
+      # class object and the name, so memoize it. Keys are class objects: the
+      # railtie clears the cache on code reload so a reloaded class cannot be
+      # retained.
+      @attachment_cache = Concurrent::Map.new
+
       module_function
 
       def attachment?(association_name, model_class)
         return false unless defined?(::ActiveStorage)
 
-        model_class.respond_to?(:reflect_on_attachment) &&
+        cache = @attachment_cache.compute_if_absent(model_class) { Concurrent::Map.new }
+        cached = cache[association_name.to_sym]
+        return cached unless cached.nil?
+
+        cache[association_name.to_sym] =
+          model_class.respond_to?(:reflect_on_attachment) &&
           model_class.reflect_on_attachment(association_name.to_sym).present?
       end
 
+      def reset_cache!
+        @attachment_cache.clear
+      end
+
       def blob_type?(type)
         return false unless defined?(::ActiveStorage)
 

data/lib/json_api/configuration.rb

@@ -4,7 +4,7 @@ module JSONAPI
   class Configuration
     attr_accessor :default_page_size, :max_page_size, :jsonapi_meta, :authorization_handler,
                   :authorization_scope, :document_meta_resolver,
-                  :namespace_type_format, :namespace_model_mapping, :namespace_fallback,
+                  :namespace_type_format, :namespace_model_mapping,
                   :n1_detection_enabled,
                   :query_tracking_enabled, :query_count_threshold, :slow_query_threshold_ms,
                   :query_tracking_queries_cap,
@@ -87,7 +87,6 @@ module JSONAPI
     def set_namespace_defaults
       @namespace_type_format = :flat
       @namespace_model_mapping = :same_namespace
-      @namespace_fallback = true
     end
   end
 

data/lib/json_api/controllers/concerns/relationships/serialization.rb

@@ -37,7 +37,8 @@ module JSONAPI
         return fetch_blank_polymorphic(association) if type_value.blank? || id_value.blank?
 
         related_model_class = type_value.constantize
-        related_resource_class = JSONAPI::ResourceLoader.find_for_model(related_model_class)
+        related_resource_class = JSONAPI::ResourceLoader.find_for_model(related_model_class,
+                                                                        namespace: jsonapi_namespace,)
         base = apply_relationship_authorization(related_resource_class.records, related_model_class)
         record = base.find(id_value)
 
@@ -52,14 +53,14 @@ module JSONAPI
 
       def fetch_polymorphic_has_many_through_resource_records(association)
         association_instance = @resource.association(@relationship_name)
-        related_resource_class = JSONAPI::ResourceLoader.find_for_model(association.klass)
+        related_resource_class = JSONAPI::ResourceLoader.find_for_model(association.klass, namespace: jsonapi_namespace)
         base = apply_relationship_authorization(related_resource_class.records, association.klass)
         association_instance.scope.merge(base)
       end
 
       def fetch_non_polymorphic_related_through_resource_records(association)
         association_instance = @resource.association(@relationship_name)
-        related_resource_class = JSONAPI::ResourceLoader.find_for_model(association.klass)
+        related_resource_class = JSONAPI::ResourceLoader.find_for_model(association.klass, namespace: jsonapi_namespace)
         base = apply_relationship_authorization(related_resource_class.records, association.klass)
         scope = association_instance.scope.merge(base)
 

data/lib/json_api/controllers/concerns/relationships/sorting.rb

@@ -13,7 +13,7 @@ module JSONAPI
         sorts = parse_sort_param
         return related if sorts.empty?
 
-        resource_class = ResourceLoader.find_for_model(association.klass)
+        resource_class = ResourceLoader.find_for_model(association.klass, namespace: jsonapi_namespace)
         Support::Sort.new(sort_params: sorts, resource_class:).apply(related)
       end
     end

data/lib/json_api/controllers/concerns/resource_actions/include_validation.rb

@@ -30,13 +30,38 @@ module JSONAPI
 
           assoc = current.reflect_on_association(name.to_sym)
           return false unless assoc
+          # A polymorphic hop has no single target class, so no static check can
+          # judge it here; each record's class resolves at serialization.
           break if assoc.polymorphic?
 
           current = assoc.klass
+          return false unless include_hop_resolvable?(current)
         end
         true
       end
 
+      # A namespaced request serves an include only where the namespace carries a
+      # resource to answer it. A hop that resolves nothing is a 400 here, not a
+      # MissingResourceClass halfway through serialization.
+      def include_hop_resolvable?(klass)
+        JSONAPI::ResourceLoader.find_for_model(klass, namespace: jsonapi_namespace)
+        true
+      rescue JSONAPI::ResourceLoader::MissingResourceClass
+        false
+      end
+
+      # Validation cannot judge a polymorphic hop, so the namespace's answer
+      # only arrives when a record's class resolves at serialization. Render
+      # the refusal validation would have given, never a raw 500.
+      def render_unanswerable_include(error)
+        render_parameter_errors(
+          [error.message],
+          title: "Invalid Include Path",
+          detail_proc: ->(m) { m },
+          source_proc: ->(_) { { parameter: "include" } },
+        )
+      end
+
       def render_include_errors(invalid)
         render_parameter_errors(
           invalid,

data/lib/json_api/controllers/concerns/resource_actions/resource_loading.rb

@@ -7,13 +7,21 @@ module JSONAPI
 
       private
 
-      def load_jsonapi_resource
+      # jsonapi_resources resolves the resource at draw time, so a typed route with no
+      # resource class is a hand-drawn misconfiguration. Answer it 404, the way the
+      # relationships controller's set_resource_class does — a nil class here surfaced
+      # later as a NoMethodError 500 in whichever action read it first.
+      def load_jsonapi_resource_class
         @resource_name = params[:resource_type]&.singularize
         @jsonapi_namespace = params[:jsonapi_namespace].presence
         load_resource_and_model_class
-        load_resource_record
-      rescue JSONAPI::ResourceLoader::MissingResourceClass
+      rescue JSONAPI::ResourceLoader::MissingResourceClass => e
         @resource_class = nil
+        render_resource_not_found_error(e.message)
+      end
+
+      def load_jsonapi_resource
+        load_resource_record
       rescue ActiveRecord::RecordNotFound
         render_record_not_found
       end

data/lib/json_api/controllers/concerns/resource_actions.rb

@@ -24,10 +24,14 @@ module JSONAPI
     include ResourceLoading
 
     included do
-      before_action :load_jsonapi_resource
+      before_action :load_jsonapi_resource_class
+      # A query parameter shapes the query the loader builds, so judge every one of them
+      # before the loader reads the database. The body members stay after the load,
+      # because a conflict with the addressed record needs that record.
       before_action :validate_fields_param, only: %i[index show]
       before_action :validate_filter_param, only: [:index]
       before_action :validate_include_param, only: %i[index show]
+      before_action :load_jsonapi_resource
       before_action :validate_resource_type!, only: %i[create update]
       before_action :validate_resource_id!, only: [:update]
     end
@@ -39,11 +43,15 @@ module JSONAPI
       @total_count = query.total_count
       @pagination_applied = query.pagination_applied
       render json: serialize_collection(query.scope), status: :ok
+    rescue JSONAPI::ResourceLoader::MissingResourceClass => e
+      render_unanswerable_include(e)
     end
 
     def show
       authorize_resource_action!(@resource, action: :show)
       render json: serialize_resource(@resource), status: :ok
+    rescue JSONAPI::ResourceLoader::MissingResourceClass => e
+      render_unanswerable_include(e)
     end
 
     def create

data/lib/json_api/controllers/relationships_controller.rb

@@ -20,6 +20,13 @@ module JSONAPI
     skip_before_action :validate_resource_type!, only: %i[update destroy]
     skip_before_action :validate_resource_id!, only: %i[update destroy]
 
+    # A polymorphic or namespaced relationship can only learn at serialization
+    # that the request namespace carries no resource for the record's class.
+    # Answer 404, the same as set_resource_class does for the primary type.
+    rescue_from JSONAPI::ResourceLoader::MissingResourceClass do |error|
+      render_resource_not_found_error(error.message)
+    end
+
     before_action :set_resource_name
     before_action :set_resource_class
     before_action :set_resource

data/lib/json_api/railtie.rb

@@ -105,8 +105,8 @@ module JSONAPI
       # that pre-populate ResourceLoader caches in their own to_prepare blocks
       # run after this and re-apply their entries.
       app.reloader.to_prepare do
-        JSONAPI::ResourceLoader.reset_cache!
-        JSONAPI::TypeConversion.reset_cache!
+        [JSONAPI::ResourceLoader, JSONAPI::TypeConversion,
+         JSONAPI::ActiveStorage::Detection,].each(&:reset_cache!)
         Railtie.setup_base_controllers
       end
 

data/lib/json_api/resources/concerns/attributes_dsl.rb

@@ -42,18 +42,44 @@ module JSONAPI
         end
 
         # Whether a relationship may be written for the given action (:create or :update).
-        # A relationship is gated by the creatable_fields/updatable_fields allow-list only when
-        # the resource opted it in by naming it in one of those lists; relationships named in
-        # neither keep the default (readonly-only) behavior. This lets a resource make a
-        # relationship create-only — name it in creatable_fields, omit it from updatable_fields —
-        # the same way it restricts attributes.
+        # A declared list is the complete allow-list. A resource that declares the action's
+        # field list names every field a client may write, and the deserializer refuses a
+        # relationship the list omits. Naming a relationship in one list and not the other
+        # still makes it create-only or update-only, the same way it restricts attributes.
+        #
+        # A resource that declares no list for the action keeps the older behavior, and only
+        # `readonly: true` stops the write. The fallback list is the attribute list, which
+        # names no relationship, so failing closed there would refuse every resource that
+        # never stated an opinion.
         def relationship_field_writable?(name, action)
           name = name.to_sym
           creatable = permitted_creatable_fields.map(&:to_sym)
           updatable = permitted_updatable_fields.map(&:to_sym)
-          return true unless creatable.include?(name) || updatable.include?(name)
+          if creatable.include?(name) || updatable.include?(name)
+            return (action == :create ? creatable : updatable).include?(name)
+          end
 
-          (action == :create ? creatable : updatable).include?(name)
+          !field_list_declared?(action)
+        end
+
+        # Whether the resource declares the action's field list, rather than falling back to
+        # the attribute list. The DSL records a declaration in the instance variable, and a
+        # subclass reads its parent's. Those are the two signals `resolve_field_list` treats
+        # as declared, and this asks the same question of the same two.
+        #
+        # An override of the reader is not a signal. An override that adjusts the inherited
+        # list — `super - [:draft] + [:owners]` — returns a plain array, the same as one that
+        # states a fresh list, so the two cannot be told apart. Reading an override as a
+        # declaration would refuse every relationship an adjusting resource does not name,
+        # and such a resource names attributes only. Call the DSL to close the list.
+        def field_list_declared?(action)
+          ivar, method = if action == :create
+                           %i[@creatable_fields permitted_creatable_fields]
+                         else
+                           %i[@updatable_fields permitted_updatable_fields]
+                         end
+
+          instance_variable_defined?(ivar) || inherits_field?(ivar, method)
         end
 
         def resolve_field_list(ivar, method)
@@ -63,10 +89,18 @@ module JSONAPI
           permitted_attributes.uniq
         end
 
+        # Any ancestor's declaration counts. Reading the immediate parent alone let a
+        # grandchild of a declaring resource fall open to the attribute fallback. The
+        # resolution still reads through `superclass.public_send`, so an intermediate
+        # reader override — the adjuster shape — keeps its say at every level.
         def inherits_field?(ivar, method)
-          superclass != JSONAPI::Resource &&
-            superclass.respond_to?(method) &&
-            superclass.instance_variable_defined?(ivar)
+          klass = superclass
+          while klass != JSONAPI::Resource && klass.respond_to?(method)
+            return true if klass.instance_variable_defined?(ivar)
+
+            klass = klass.superclass
+          end
+          false
         end
 
         def should_inherit_attributes?(declared_attributes)

data/lib/json_api/resources/concerns/relationships_dsl.rb

@@ -31,6 +31,7 @@ module JSONAPI
 
         def reset_relationship_definitions!
           remove_instance_variable(:@relationship_definitions) if defined?(@relationship_definitions)
+          remove_instance_variable(:@relationship_definition_index) if defined?(@relationship_definition_index)
         end
 
         def relationship_names
@@ -39,6 +40,20 @@ module JSONAPI
       end
 
       module RelationshipHelperMethods
+        # Name-keyed lookup over relationship_definitions. The serializer asks
+        # for one definition by name once per record per hop; a linear scan
+        # with a to_s per entry allocated thousands of strings per request.
+        # Both spellings key the same entry, so a lookup converts nothing.
+        def relationship_definition_index
+          return @relationship_definition_index if defined?(@relationship_definition_index)
+
+          index = relationship_definitions.each_with_object({}) do |r, h|
+            h[r[:name]] = r
+            h[r[:name].to_s] = r
+          end
+          @relationship_definition_index = index.freeze
+        end
+
         def register_relationship(name:, type:, meta:, options:)
           @relationships ||= []
           @relationships << { name: name.to_sym, type:, meta:, options: }

data/lib/json_api/resources/resource_loader.rb

@@ -25,14 +25,21 @@ module JSONAPI
     # caches on code reload.
     @find_cache = Concurrent::Map.new
     @model_cache = Concurrent::Map.new
+    # Identity front cache for find_for_model: the string cache key allocated
+    # on every call, and the serializer calls per record and per identifier.
+    # Nested by fallback flag and namespace so a configuration flip cannot
+    # serve a stale class. Values come through the string-keyed path, so an
+    # application that pre-populates @model_cache keeps its pins.
+    @model_identity_cache = Concurrent::Map.new
 
     def self.reset_cache!
       @find_cache.clear
       @model_cache.clear
+      @model_identity_cache.clear
     end
 
     def self.find(resource_type, namespace: nil)
-      key = "#{namespace}|#{resource_type}|#{JSONAPI.configuration.namespace_fallback ? 1 : 0}"
+      key = "#{namespace}|#{resource_type}"
       cached = @find_cache[key]
       return cached if cached
 
@@ -41,24 +48,26 @@ module JSONAPI
       @find_cache[key] = klass
     end
 
+    # A namespaced request resolves inside its namespace alone — "widgets" under
+    # "api/v1" names API::V1::WidgetResource and nothing else. A flat request
+    # names the flat resource. Nothing falls back across the boundary, so a
+    # namespace serves only what it declares.
     def self.find_candidates(resource_type, namespace)
-      candidates = []
-
-      # Namespaced resource, e.g. "widgets" with namespace "api/v1" → API::V1::WidgetResource
-      candidates << build_resource_class_name(resource_type, namespace) if namespace
-
-      # Flat resource, e.g. "widgets" → WidgetResource
-      if !namespace || JSONAPI.configuration.namespace_fallback
-        candidates << build_resource_class_name(resource_type,
-                                                nil,)
-      end
-
-      candidates
+      [build_resource_class_name(resource_type, namespace.presence)]
     end
 
     def self.find_for_model(model_class, namespace: nil)
       return ActiveStorageBlobResource if active_storage_blob?(model_class)
 
+      bucket = model_identity_bucket(namespace)
+      bucket[model_class] || (bucket[model_class] = find_for_model_uncached(model_class, namespace))
+    end
+
+    def self.model_identity_bucket(namespace)
+      @model_identity_cache.compute_if_absent(namespace) { Concurrent::Map.new }
+    end
+
+    def self.find_for_model_uncached(model_class, namespace)
       key = model_cache_key(model_class, namespace)
       cached = @model_cache[key]
       return cached if cached
@@ -80,19 +89,39 @@ module JSONAPI
     def self.model_cache_key(model_class, namespace)
       return "::#{model_class.name}" unless namespace
 
-      "#{namespace}|::#{model_class.name}|#{JSONAPI.configuration.namespace_fallback ? 1 : 0}"
+      "#{namespace}|::#{model_class.name}"
     end
 
-    # The request namespace outranks the model's own namespace, which stays a
-    # fallback so a namespaced model still reaches its own resource. The flat
-    # name comes last, and only while the configuration allows the fallback.
+    # The request namespace outranks the model's own namespace, which a
+    # namespaced model keeps so it still reaches its own resource. An STI
+    # record answers through the request namespace's resource for its own
+    # class, then for its base class, so one base resource covers every
+    # subclass. No flat name is a candidate: a flat resource is another
+    # namespace's surface, and resolving it here is what published internal
+    # fields on public portals.
     def self.request_namespace_candidates(model_class, namespace, model_namespace)
-      resource_type = model_class.name.demodulize.underscore.pluralize
-      candidates = [build_resource_class_name(resource_type, namespace)]
+      candidates = sti_resource_names(model_class, namespace)
       candidates |= model_candidates(model_class, model_namespace)
-      return candidates if JSONAPI.configuration.namespace_fallback
+      candidates - sti_resource_names(model_class, nil)
+    end
+
+    # Every name shape a class answers to, in one namespace: the demodulized
+    # name and, for a namespaced model, the flat-combined name `find` builds
+    # from the route type — so `Pub::DepotItemResource`, the class the
+    # MissingResourceClass message names, is a candidate, and the flat
+    # `DepotItemResource` is subtracted with the rest.
+    def self.sti_resource_names(model_class, namespace)
+      classes = [model_class]
+      classes << model_class.base_class if sti_subclass?(model_class)
+      classes.flat_map { class_resource_names(it, namespace) }
+    end
+
+    def self.class_resource_names(klass, namespace)
+      names = [build_resource_class_name(klass.name.demodulize.underscore.pluralize, namespace)]
+      return names unless klass.name.include?("::")
 
-      candidates - [build_resource_class_name(resource_type, nil)]
+      combined = "#{klass.name.gsub("::", "")}Resource"
+      names << (namespace ? "#{namespace.to_s.camelize}::#{combined}" : combined)
     end
 
     def self.build_resource_class_name(resource_type, namespace)

data/lib/json_api/routing.rb

@@ -2,17 +2,29 @@
 
 module JSONAPI
   module Routing
+    # The member action each relationship route stands on. A relationship
+    # route reads or writes through the parent record: GET stands on :show,
+    # and PATCH and DELETE both stand on :update, because a relationship
+    # DELETE removes members from the relationship — the controller
+    # authorizes it as an update, and the primary record survives — so
+    # :destroy plays no part.
+    RELATIONSHIP_ACTIONS = { show: :show, update: :update, destroy: :update }.freeze
+
     def jsonapi_resources(resource, controller: nil, defaults: {}, sti: false, **options, &)
       resource_name = resource.to_s
       namespace = extract_namespace_from_scope
       controller ||= detect_controller(resource_name, namespace)
       defaults = build_jsonapi_defaults(defaults, resource_name, namespace)
+      # The caller's restriction, before the STI base overwrite: a subtype route
+      # that states no options of its own inherits it, so `only:` governs the
+      # whole set rather than the base alone.
+      restriction = options.slice(:only, :except)
       options[:only] = :index if sti
       options = without_form_actions(options)
 
       JSONAPI::ResourceLoader.find(resource_name, namespace:)
       define_resource_routes(resource, controller, defaults, options, &)
-      define_sti_routes(resource, resource_name, defaults, sti, namespace)
+      define_sti_routes(resource, defaults, sti, namespace, restriction)
     end
 
     def build_jsonapi_defaults(defaults, resource_name, namespace)
@@ -50,17 +62,35 @@ module JSONAPI
     end
 
     def define_resource_routes(resource, controller, defaults, options, &block)
+      actions = permitted_relationship_actions(options)
       resources(resource, controller:, defaults:, **options) do
-        define_relationship_routes
+        define_relationship_routes(actions)
         instance_eval(&block) if block
       end
     end
 
-    def define_relationship_routes
+    # The relationships controller authorizes the parent record, never the
+    # member action the caller left out. So a caller who omitted `:update` still
+    # got the relationship PATCH, a write path they never asked for.
+    def permitted_relationship_actions(options)
+      named = options.key?(:only) ? Array(options[:only]).map(&:to_sym) : RELATIONSHIP_ACTIONS.values
+      kept = named - Array(options[:except]).map(&:to_sym)
+      RELATIONSHIP_ACTIONS.select { |_action, member| kept.include?(member) }.keys
+    end
+
+    # The :relationship helper hangs on the first verb drawn, so it survives
+    # a declaration that keeps a write verb and drops :show.
+    def define_relationship_routes(actions)
+      return if actions.empty?
+
       member do
-        get "relationships/:relationship_name", to: relationships_endpoint(:show), as: :relationship
-        patch "relationships/:relationship_name", to: relationships_endpoint(:update)
-        delete "relationships/:relationship_name", to: relationships_endpoint(:destroy)
+        path = "relationships/:relationship_name"
+        { get: :show, patch: :update, delete: :destroy }.each do |verb, action|
+          next unless actions.include?(action)
+
+          name = (:relationship if action == actions.first)
+          public_send(verb, path, to: relationships_endpoint(action), as: name)
+        end
       end
     end
 
@@ -77,29 +107,31 @@ module JSONAPI
       end
     end
 
-    def define_sti_routes(resource, resource_name, defaults, sti, namespace = nil)
+    def define_sti_routes(resource, defaults, sti, namespace, restriction)
       return unless sti
 
       if sti.is_a?(Array)
-        define_explicit_sti_routes(sti, defaults)
+        define_explicit_sti_routes(sti, defaults, restriction)
       else
-        define_auto_sti_routes(resource, resource_name, defaults, namespace)
+        define_auto_sti_routes(resource, defaults, namespace, restriction)
       end
     end
 
-    def define_explicit_sti_routes(sti_resources, defaults)
+    # A subtype entry that states its own options is a declaration and keeps it.
+    # A bare entry declares nothing, so it inherits the caller's restriction.
+    def define_explicit_sti_routes(sti_resources, defaults, restriction)
       sti_resources.each do |entry|
         case entry
         in Hash
           entry.each { |sub_resource_name, options| jsonapi_resources(sub_resource_name, defaults:, **options) }
         else
-          jsonapi_resources(entry, defaults:)
+          jsonapi_resources(entry, defaults:, **restriction)
         end
       end
     end
 
-    def define_auto_sti_routes(resource, resource_name, defaults, namespace = nil)
-      resource_class = JSONAPI::ResourceLoader.find(resource_name, namespace:)
+    def define_auto_sti_routes(resource, defaults, namespace, restriction)
+      resource_class = JSONAPI::ResourceLoader.find(resource.to_s, namespace:)
       model_class = resource_class.model_class
       return unless model_class.respond_to?(:descendants)
 
@@ -107,7 +139,7 @@ module JSONAPI
         sub_resource_name = subclass.name.demodulize.underscore.pluralize.to_sym
         next if sub_resource_name == resource.to_sym
 
-        jsonapi_resources(sub_resource_name, defaults:)
+        jsonapi_resources(sub_resource_name, defaults:, **restriction)
       rescue NameError, JSONAPI::ResourceLoader::MissingResourceClass
         next
       end

data/lib/json_api/serialization/concerns/attributes_deserialization.rb

@@ -10,7 +10,7 @@ module JSONAPI
       end
 
       def extract_attributes_from_params
-        @params.dig(:data, :attributes) || @params[:attributes] || {}
+        @params[:attributes] || {}
       end
 
       def permitted_attributes_for_action

data/lib/json_api/serialization/concerns/attributes_serialization.rb

@@ -20,9 +20,8 @@ module JSONAPI
       end
 
       def build_attributes_hash
-        permitted_attrs = definition.permitted_attributes.map(&:to_sym)
+        permitted_attrs = definition.permitted_attributes
         attributes = {}
-        definition_instance = definition.new(record, {})
 
         permitted_attrs.each do |attr_sym|
           attributes[attr_sym] = get_attribute_value(definition_instance, attr_sym)
@@ -34,16 +33,22 @@ module JSONAPI
       def get_attribute_value(definition_instance, attr_sym)
         return definition_instance.public_send(attr_sym) if definition_instance.respond_to?(attr_sym, false)
 
-        attr_name = attr_sym.to_s
-        return record.attributes[attr_name] if model_has_attribute?(attr_name)
-
-        nil
+        read_model_attribute(attr_sym.to_s)
       end
 
-      def model_has_attribute?(attr_name)
-        record.respond_to?(:attributes) &&
-          record.attributes.is_a?(Hash) &&
-          record.attributes.key?(attr_name)
+      # ActiveRecord#attributes builds a hash of every column on every call,
+      # and this reader called it three times per attribute per record: twice
+      # to ask whether the column exists, once to read it. A record with a fat
+      # text column paid for that column on all three. has_attribute? and
+      # read_attribute answer from the attribute set itself, one attribute at a
+      # time. A model that is not ActiveRecord keeps the hash route.
+      def read_model_attribute(attr_name)
+        if record.respond_to?(:has_attribute?) && record.respond_to?(:read_attribute)
+          return record.has_attribute?(attr_name) ? record.read_attribute(attr_name) : nil
+        end
+
+        attributes = record.attributes if record.respond_to?(:attributes)
+        attributes.is_a?(Hash) ? attributes[attr_name] : nil
       end
     end
   end

data/lib/json_api/serialization/concerns/include_filtering.rb

@@ -10,7 +10,15 @@ module JSONAPI
       # denies. The request-scoped cache memoizes the scopes and the per-id
       # verdicts, so each record is vetted at most once per request.
       def filter_loaded_records(association, related_klass)
-        loaded_array = association.target.respond_to?(:to_a) ? association.target.to_a : Array(association.target)
+        target = association.target
+        # A collection target is an Array; a singular target is the record or
+        # nil. A respond_to?(:to_a) probe on a record walks ActiveModel's
+        # attribute matcher and allocates a string per probe.
+        loaded_array = if target.is_a?(Array)
+                         target
+                       else
+                         target.nil? ? [] : [target]
+                       end
         return [] if loaded_array.empty?
 
         include_filter_cache.filter(loaded_array, related_klass)

data/lib/json_api/serialization/concerns/includes_serialization.rb

@@ -4,10 +4,19 @@ require_relative "include_filtering"
 
 module JSONAPI
   module Serialization
-    IncludeContext = Struct.new(:fields, :included_records, :processed, :all_includes, keyword_init: true)
-    PathContext = Struct.new(:path_parts, :path_to_related, :association_name, :current_record, keyword_init: true)
-    IncludeIteration = Struct.new(:related_record, :path_parts, :path_to_related, :association_name, :current_record,
-                                  keyword_init: true,)
+    IncludeContext = Struct.new(:fields, :included_records, :processed, :all_includes, :requested, :walks,
+                                keyword_init: true,) do
+      # Per-request memos: the relationship names each include path asks for,
+      # and the precomputed walk for each path. They default lazily, so a
+      # context built by hand (a caller outside this gem) works without
+      # naming them.
+      def requested = self[:requested] ||= {}
+
+      def walks = self[:walks] ||= {}
+    end
+    # Precomputed shape of one include path: association symbols per depth and
+    # the dotted prefix string that names each depth from the root.
+    IncludePathWalk = Struct.new(:names, :prefixes, keyword_init: true)
 
     module IncludesSerialization
       include IncludePathHelpers
@@ -19,7 +28,7 @@ module JSONAPI
 
         ctx = context || build_include_context(fields, all_includes)
         ctx.all_includes ||= all_includes
-        all_includes.each { |path| serialize_include_path(record, path, ctx, path_from_root: "") }
+        all_includes.each { |path| serialize_include_path(record, path_walk_for(path, ctx), 0, ctx) }
         ctx.included_records
       end
 
@@ -29,34 +38,45 @@ module JSONAPI
 
       private
 
-      def serialize_include_path(current_record, include_path, ctx, path_from_root: "")
-        path_parts = include_path.split(".")
-        association_name = path_parts.first.to_sym
+      # The split, the association symbols, and the prefix strings depend on
+      # the path alone, so compute them once per path instead of once per
+      # parent record. The old walk re-split and re-joined the path strings at
+      # every level for every record it passed.
+      def path_walk_for(path, ctx)
+        ctx.walks[path] ||= begin
+          names = path.split(".").map(&:to_sym)
+          prefixes = names.each_with_index.map { |_, i| names[0..i].join(".") }
+          IncludePathWalk.new(names: names, prefixes: prefixes)
+        end
+      end
+
+      def serialize_include_path(current_record, walk, depth, ctx)
+        association_name = walk.names[depth]
         return unless valid_include_association?(current_record, association_name)
 
-        path_to_related = path_from_root.blank? ? path_parts.first : "#{path_from_root}.#{path_parts.first}"
-        path_ctx = PathContext.new(path_parts:, path_to_related:, association_name:, current_record: current_record)
-        process_related_records(get_related_records(current_record, association_name), path_ctx, ctx)
+        serialize_walk_level(current_record, get_related_records(current_record, association_name),
+                             walk, depth, ctx,)
       end
 
-      def process_related_records(related_array, path_ctx, ctx)
+      # The attachment verdict holds for the whole related array: it reads the
+      # association name and the parent class, which do not change inside the
+      # loop.
+      def serialize_walk_level(current_record, related_array, walk, depth, ctx)
+        attachment = self.class.active_storage_attachment?(walk.names[depth], current_record.class)
+        nested = depth + 1 < walk.names.size
+
         related_array.each do |related_record|
-          iter = IncludeIteration.new(related_record: related_record, **path_ctx.to_h)
-          serialize_related_record(iter, ctx)
+          serialize_walk_record(related_record, current_record, walk, depth, ctx, attachment: attachment)
+          serialize_include_path(related_record, walk, depth + 1, ctx) if nested
         end
       end
 
-      def serialize_related_record(iter, ctx)
-        parent_context = parent_context_for(iter.association_name, iter.current_record)
-        serialize_and_process_record(iter.related_record, iter.path_to_related, ctx, **parent_context)
-        serialize_nested_path(iter.related_record, iter.path_parts, iter.path_to_related, ctx)
-      end
-
-      def parent_context_for(association_name, current_record)
-        if self.class.active_storage_attachment?(association_name, current_record.class)
-          { parent_record: current_record, association_name: }
+      def serialize_walk_record(related_record, current_record, walk, depth, ctx, attachment:)
+        if attachment
+          serialize_and_process_record(related_record, walk.prefixes[depth], ctx,
+                                       parent_record: current_record, association_name: walk.names[depth],)
         else
-          {}
+          serialize_and_process_record(related_record, walk.prefixes[depth], ctx)
         end
       end
 
@@ -122,12 +142,12 @@ module JSONAPI
       end
 
       def serialize_and_process_record(related_record, path_to_record, ctx, parent_record: nil, association_name: nil)
-        return if ctx.processed.include?(build_record_key(related_record))
+        return unless ctx.processed.add?(build_record_key(related_record))
 
-        requested = include_paths_to_relationship_names(ctx.all_includes, path_to_record)
+        requested = ctx.requested[path_to_record] ||=
+          include_paths_to_relationship_names(ctx.all_includes, path_to_record)
         serializer = child_serializer(related_record, parent_record:, association_name:)
         ctx.included_records << serializer.serialize_record(ctx.fields, requested_relationships: requested)
-        ctx.processed.add(build_record_key(related_record))
       end
 
       # An included record serializes with the same request context as its
@@ -138,15 +158,10 @@ module JSONAPI
                                        authorization_context:, include_filter_cache:, namespace:,)
       end
 
+      # A two-slot array beats the string key: no interpolation, no copy of
+      # the class name, and the same class-plus-id identity.
       def build_record_key(related_record)
-        "#{related_record.class.name}-#{related_record.id}"
-      end
-
-      def serialize_nested_path(related_record, path_parts, path_from_root, ctx)
-        return unless path_parts.length > 1
-
-        nested_path = path_parts[1..].join(".")
-        serialize_include_path(related_record, nested_path, ctx, path_from_root: path_from_root)
+        [related_record.class, related_record.id]
       end
     end
   end

data/lib/json_api/serialization/concerns/meta_serialization.rb

@@ -22,8 +22,7 @@ module JSONAPI
       def fetch_instance_meta
         return unless definition.method_defined?(:meta)
 
-        instance = definition.new(@record, {})
-        instance.meta
+        definition_instance.meta
       end
 
       def fetch_class_meta

data/lib/json_api/serialization/concerns/relationships_deserialization.rb

@@ -4,7 +4,7 @@ module JSONAPI
   module Serialization
     module RelationshipsDeserialization
       def relationships
-        rels = @params.dig(:data, :relationships) || @params[:relationships] || {}
+        rels = @params[:relationships] || {}
         rels = rels.to_h if rels.respond_to?(:to_h)
         rels.is_a?(Hash) ? rels : {}
       end

data/lib/json_api/serialization/deserializer.rb

@@ -17,7 +17,7 @@ module JSONAPI
     include Serialization::DeserializationHelpers
 
     def initialize(params, model_class:, action: :create, definition: nil)
-      @params = ParamHelpers.deep_symbolize_params(params)
+      @params = resource_object(ParamHelpers.deep_symbolize_params(params))
       @model_class = model_class
       # Prefer the resource the request is addressing (resolved by type/route). Resolving
       # from the model alone is ambiguous when several resources share one model
@@ -26,5 +26,21 @@ module JSONAPI
       @definition = definition || ResourceLoader.find_for_model(model_class)
       @action = action.to_sym
     end
+
+    private
+
+    # A caller passes either the whole document or the resource object inside it, and the
+    # controllers pass the resource object, which the client writes. `type` settles which one
+    # arrived: JSON:API requires it in every resource object and names no `type` among the
+    # members of a document. So a hash that carries `type` is the resource object, and only a
+    # hash that carries none, over a `data` member that carries one, is a document. Anything
+    # else is neither, and the outer hash wins. A reader that took a nested `data` first let a
+    # client hide an attribute or a relationship from a guard that reads the request body.
+    def resource_object(params)
+      return params if params.key?(:type)
+      return params unless params[:data].is_a?(Hash) && params[:data].key?(:type)
+
+      params[:data]
+    end
   end
 end

data/lib/json_api/serialization/serializer.rb

@@ -83,6 +83,14 @@ module JSONAPI
 
     attr_reader :record, :definition, :parent_record, :association_name, :authorization_context, :namespace
 
+    # One resource instance per serialized record, shared by the attribute
+    # reader and the meta reader. The two built separate instances, which
+    # doubled the instantiation and kept the resource's own memoized reads
+    # from being shared between an attribute and a meta entry.
+    def definition_instance
+      @definition_instance ||= definition.new(record)
+    end
+
     # Shared per request when the controller passes one in; a standalone
     # serializer builds its own, which still dedupes within its own walk.
     def include_filter_cache

data/lib/json_api/support/relationship_helpers.rb

@@ -63,7 +63,11 @@ module JSONAPI
     end
 
     def find_relationship_definition(definition, relationship_name)
-      definition.relationship_definitions.find { |r| r[:name].to_s == relationship_name.to_s }
+      if definition.respond_to?(:relationship_definition_index)
+        definition.relationship_definition_index[relationship_name]
+      else
+        definition.relationship_definitions.find { |r| r[:name].to_s == relationship_name.to_s }
+      end
     end
   end
 end

data/lib/json_api/support/resource_identifier.rb

@@ -73,9 +73,7 @@ module JSONAPI
     end
 
     def polymorphic_association?(definition, relationship_name)
-      relationship_def = definition.relationship_definitions.find do |r|
-        r[:name].to_s == relationship_name.to_s
-      end
+      relationship_def = RelationshipHelpers.find_relationship_definition(definition, relationship_name)
       return false unless relationship_def
 
       relationship_def[:options][:polymorphic] == true

data/lib/json_api/support/type_conversion.rb

@@ -9,15 +9,26 @@ module JSONAPI
     # relationship identifier. Cache frozen results keyed by name and format.
     # The railtie clears the cache on code reload.
     @type_name_cache = Concurrent::Map.new
+    # Identity front cache: the name-keyed cache still allocated its key
+    # string on every call. Nested by kind and format so a lookup allocates
+    # nothing; values come through the name-keyed cache, and both clear
+    # together on code reload.
+    @class_name_cache = Concurrent::Map.new
 
     def self.reset_cache!
       @type_name_cache.clear
+      @class_name_cache.clear
     end
 
     def self.type_name_cache
       @type_name_cache
     end
 
+    def self.class_name_bucket(kind, format)
+      by_kind = @class_name_cache.compute_if_absent(kind) { Concurrent::Map.new }
+      by_kind.compute_if_absent(format) { Concurrent::Map.new }
+    end
+
     module_function
 
     def type_to_class_name(type, namespace: nil)
@@ -38,8 +49,14 @@ module JSONAPI
       name = model_class.name
       return format_type_name(name.underscore.pluralize, format) if name.nil?
 
-      cache = TypeConversion.type_name_cache
-      cache["m|#{name}|#{format}"] ||= format_type_name(name.underscore.pluralize, format).freeze
+      bucket = TypeConversion.class_name_bucket(:model, format)
+      bucket[model_class] ||= named_type_name("m|#{name}|#{format}", name.underscore.pluralize, format)
+    end
+
+    # The name-keyed cache stays the source of truth so a reloaded class
+    # resolves to the same frozen string.
+    def named_type_name(key, full_name, format)
+      TypeConversion.type_name_cache[key] ||= format_type_name(full_name, format).freeze
     end
 
     def resource_type_name(definition_class, format: nil)
@@ -47,8 +64,9 @@ module JSONAPI
       name = definition_class.name
       return format_type_name(name.sub(/Resource$/, "").underscore.pluralize, format) if name.nil?
 
-      cache = TypeConversion.type_name_cache
-      cache["r|#{name}|#{format}"] ||= format_type_name(name.sub(/Resource$/, "").underscore.pluralize, format).freeze
+      bucket = TypeConversion.class_name_bucket(:resource, format)
+      bucket[definition_class] ||=
+        named_type_name("r|#{name}|#{format}", name.sub(/Resource$/, "").underscore.pluralize, format)
     end
 
     def format_type_name(full_name, format)

data/lib/json_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JSONAPI
-  VERSION = "3.10.1"
+  VERSION = "4.0.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jpie
 version: !ruby/object:Gem::Version
-  version: 3.10.1
+  version: 4.0.0
 platform: ruby
 authors:
 - Emil Kampp