jpie 3.8.2 → 3.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d78efd83c17a8d1e0b9c7e13966c083de82d95d92463dd5b945a4478d981c30
-  data.tar.gz: 71594c1b5687a4d20268d79b4e83e3760d399f3467029b8f0787329b6cf599fa
+  metadata.gz: 4f3af561d7afa748d2a1095a6b3c83fe8ab42b12a6fb88655f67c023e72779ba
+  data.tar.gz: ea3c315885d7b2ae18f328bb6659c796e64e82b62b87ae479fd7d3faa0ef4f09
 SHA512:
-  metadata.gz: e1bdbd01c0c181b59be183a8d72decb7d3e13f254c92cd477285f69a909953d4bfe58f6dff6001ddbc437036888e30b6ab9e921675fd65a70003206f714f37ac
-  data.tar.gz: 6bdadef777e82f021a67b820e77e61a7c2051dbb5cddc037447b0c42c26c3142cc738f8a6aa864ef26b2cfb19a3a0f5e6f6a42afd5ec483b1049bd15d24acf52
+  metadata.gz: edd52e432cec91efbd1487ebb8ad340fbe560879415ae6af400290b68e5c5bfa3db6f7afd967077bbf6a5509992329b412f865af88db19f80accadb8903f44e5
+  data.tar.gz: 1f9854c359c421410f19645ae03659137059e92f8bc88a1b52b3e79ac2906abe5747c859a46ed02a312ba8ab37e7f661fbce1c16e42a2a29e73e5446122889b1

data/.claude/skills/root-cause-analysis/SKILL.md

@@ -42,6 +42,12 @@ Gather facts before concluding. Prefer:
 
 Do not rely on assumptions. Evidence supports or refutes hypotheses.
 
+**Bind the error to the incident by identity, not by proximity.** An error in the same account, the same minute, the same job class, or the same feature area is NOT evidence that it caused the reported failure. Busy systems fire several unrelated errors in one window. Prove the link with a record identity that both sides share — the job arguments, the record GID, the message id, the request id. Sentry event details carry `job_arguments` and `extra`; open them and read the ids. If no shared id ties the error to the records the user named, you have a co-occurring error, not the cause.
+
+Search the failure's exact time window for EVERY error, not just the ones that match your first idea. Then pick the one whose arguments name the user's records. A narrow search that starts from a suspected culprit returns that culprit and hides the real one.
+
+**When the user's evidence contradicts your diagnosis, re-run the search.** Do not restate the theory in better words. Their report of what actually happened outranks your reading of the code. Treat the contradiction as a failed hypothesis and go back to evidence gathering.
+
 ## Methodology and verification
 
 - **5 Whys:** State the problem; ask "why?" repeatedly until you reach a cause you can fix. **Verify:** Would fixing this prevent the issue? If not, keep investigating.
@@ -55,6 +61,10 @@ Do not rely on assumptions. Evidence supports or refutes hypotheses.
 | "Let me try this quick fix" | You do not understand the cause |
 | "Maybe if I add a guard here" | Guessing, not debugging |
 | "Let me try a few things" | Random changes waste time |
+| "This error is in the same account and the same minute, so it is the one" | Co-occurrence is not causation; match a record id before you believe it |
+| "The related error is in the same job class / feature, close enough" | Same area is not same incident; open the event's arguments and match the ids |
+| "The user says it still fails, let me explain why my fix is right" | Their evidence beat your theory; re-run the search instead of defending |
+| "I found an error that fits my theory, stop searching" | Search the whole time window; a narrow search only confirms what you assumed |
 
 When you notice these, stop and run through problem definition, evidence, and one hypothesis at a time.
 

data/.cursor/agents/systematic-debugging.md

@@ -20,6 +20,7 @@ Do not recommend changing code just to pass specs, or changing specs just to mak
 - Review recent changes (git log, options, caller expectations).
 - Gather evidence (params, include, serializer path, input data).
 - Trace backwards from the failure to where correct behaviour diverges.
+- Bind each error you find to the reported incident by a shared record id (job arguments, record GID, message id, request id) — same account, same minute, or same feature is proximity, not proof. Search the whole failure window, not only what matches your first idea.
 
 ### Phase 2: Pattern analysis
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jpie (3.8.2)
+    jpie (3.9.0)
       actionpack (~> 8.1, >= 8.1.0)
       pg_query (>= 4)
       prosopite (>= 1)

data/README.md

@@ -875,6 +875,13 @@ This will:
 - Load `API::V1::WidgetResource` (falls back to `WidgetResource` if `namespace_fallback: true`)
 - 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.
+
 #### Namespaced Resources
 
 Define resources within namespaces that match your route structure:

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

@@ -147,7 +147,7 @@ module JSONAPI
         return if records.empty?
 
         klass = records.first.class
-        resource_scope = ResourceLoader.find_for_model(klass).records
+        resource_scope = ResourceLoader.find_for_model(klass, namespace: jsonapi_namespace).records
         preload_values = resource_scope.preload_values + resource_scope.includes_values
         return if preload_values.empty?
 

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

@@ -9,11 +9,9 @@ module JSONAPI
       def serialize_resource(resource)
         includes = parse_include_param
         cache = build_include_filter_cache([resource], includes)
-        JSONAPI::Serializer.new(resource, authorization_context: self, include_filter_cache: cache).to_hash(
-          include: includes,
-          fields: parse_fields_param,
-          document_meta: jsonapi_document_meta,
-        )
+        serializer = JSONAPI::Serializer.new(resource, authorization_context: self, include_filter_cache: cache,
+                                                       namespace: jsonapi_namespace,)
+        serializer.to_hash(include: includes, fields: parse_fields_param, document_meta: jsonapi_document_meta)
       end
 
       def serialize_collection(resources)
@@ -48,7 +46,8 @@ module JSONAPI
       end
 
       def serialize_single(resource, includes, fields, include_context = nil, cache = nil)
-        JSONAPI::Serializer.new(resource, authorization_context: self, include_filter_cache: cache)
+        JSONAPI::Serializer.new(resource, authorization_context: self, include_filter_cache: cache,
+                                          namespace: jsonapi_namespace,)
           .to_hash(include: includes, fields:, document_meta: nil, include_context:)
       end
 
@@ -56,7 +55,8 @@ module JSONAPI
       # every included record gets its scope verdict in one query per class,
       # and the serializers answer their per-visit checks from memory.
       def build_include_filter_cache(resources, includes)
-        cache = JSONAPI::Serialization::IncludeFilterCache.new(authorization_context: self)
+        cache = JSONAPI::Serialization::IncludeFilterCache.new(authorization_context: self,
+                                                               namespace: jsonapi_namespace,)
         includes.each do |path|
           current = resources
           path.split(".").each do |part|

data/lib/json_api/resources/resource_loader.rb

@@ -59,20 +59,42 @@ module JSONAPI
     def self.find_for_model(model_class, namespace: nil)
       return ActiveStorageBlobResource if active_storage_blob?(model_class)
 
-      # Key format "::ModelName" is public-ish: applications pre-populate
-      # @model_cache with these keys to pin STI subclass resources.
-      key = namespace ? "#{namespace}|::#{model_class.name}" : "::#{model_class.name}"
+      key = model_cache_key(model_class, namespace)
       cached = @model_cache[key]
       return cached if cached
 
-      effective_namespace = namespace || extract_namespace_from_model(model_class)
-      candidates = model_candidates(model_class, effective_namespace)
-
-      klass = resolve(candidates) ||
-              raise(MissingResourceClass.new(model_class.name, namespace: effective_namespace))
+      model_namespace = extract_namespace_from_model(model_class)
+      klass = resolve(find_for_model_candidates(model_class, namespace, model_namespace)) ||
+              raise(MissingResourceClass.new(model_class.name, namespace: namespace || model_namespace))
       @model_cache[key] = klass
     end
 
+    def self.find_for_model_candidates(model_class, namespace, model_namespace)
+      return model_candidates(model_class, model_namespace) unless namespace
+
+      request_namespace_candidates(model_class, namespace, model_namespace)
+    end
+
+    # Key format "::ModelName" is public-ish: applications pre-populate
+    # @model_cache with these keys to pin STI subclass resources.
+    def self.model_cache_key(model_class, namespace)
+      return "::#{model_class.name}" unless namespace
+
+      "#{namespace}|::#{model_class.name}|#{JSONAPI.configuration.namespace_fallback ? 1 : 0}"
+    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.
+    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 |= model_candidates(model_class, model_namespace)
+      return candidates if JSONAPI.configuration.namespace_fallback
+
+      candidates - [build_resource_class_name(resource_type, nil)]
+    end
+
     def self.build_resource_class_name(resource_type, namespace)
       base = "#{resource_type.singularize.classify}Resource"
       return base unless namespace.present?

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

@@ -61,7 +61,7 @@ module JSONAPI
       end
 
       def valid_include_association?(current_record, association_name)
-        current_definition = ResourceLoader.find_for_model(current_record.class)
+        current_definition = ResourceLoader.find_for_model(current_record.class, namespace:)
         relationship_def = RelationshipHelpers.find_relationship_definition(current_definition, association_name)
         return false unless relationship_def
         return true if self.class.active_storage_attachment?(association_name, current_record.class)
@@ -91,7 +91,7 @@ module JSONAPI
       end
 
       def build_scoped_relation(related_klass, association)
-        related_base_scope = ResourceLoader.find_for_model(related_klass).records
+        related_base_scope = ResourceLoader.find_for_model(related_klass, namespace:).records
         association.scope.merge(apply_include_authorization(related_base_scope, related_klass))
       end
 
@@ -119,12 +119,19 @@ module JSONAPI
         return if ctx.processed.include?(build_record_key(related_record))
 
         requested = include_paths_to_relationship_names(ctx.all_includes, path_to_record)
-        serializer = self.class.new(related_record, parent_record:, association_name:,
-                                                    authorization_context:, include_filter_cache:,)
+        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
+      # parent: the authorization context, the filter cache, and the namespace
+      # that selects the resource class.
+      def child_serializer(related_record, parent_record:, association_name:)
+        self.class.new(related_record, parent_record:, association_name:,
+                                       authorization_context:, include_filter_cache:, namespace:,)
+      end
+
       def build_record_key(related_record)
         "#{related_record.class.name}-#{related_record.id}"
       end

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

@@ -43,7 +43,7 @@ module JSONAPI
       end
 
       def variant_options_for_parent_association
-        parent_definition = ResourceLoader.find_for_model(parent_record.class)
+        parent_definition = ResourceLoader.find_for_model(parent_record.class, namespace:)
         rel_def = RelationshipHelpers.find_relationship_definition(parent_definition, association_name)
         rel_def&.dig(:options, :variant)
       end

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

@@ -61,26 +61,29 @@ module JSONAPI
 
       def process_to_many_relationship(attrs, association_name, param_name, data)
         ids = data.map { |r| extract_id(r) }
-        types = data.map { |r| extract_type(r) }
 
-        if types.any? && self.class.active_storage_blob_type?(types.first)
+        # An attachment must take the attachment path whether or not the client sends a
+        # `type`. JSON:API requires a resource identifier to carry `type` and `id`, so
+        # routing on the association itself keeps the spec-compliant payload working
+        # instead of falling through to the `<rel>_ids=` setter, which an attachment lacks.
+        if active_storage_attachment?(association_name)
           process_active_storage_attachment(attrs, association_name, ids, singular: false)
           return
         end
 
+        types = data.map { |r| extract_type(r) }
         validate_relationship_type(association_name, types.first) unless polymorphic_association?(association_name)
         attrs["#{param_name.singularize}_ids"] = ids
       end
 
       def process_to_one_relationship(attrs, association_name, param_name, data)
         id = extract_id(data)
-        type = extract_type(data)
 
-        if self.class.active_storage_blob_type?(type)
+        if active_storage_attachment?(association_name)
           return process_active_storage_attachment(attrs, association_name, id, singular: true)
         end
 
-        process_regular_to_one_relationship(attrs, association_name, param_name, id, type)
+        process_regular_to_one_relationship(attrs, association_name, param_name, id, extract_type(data))
       end
 
       def process_regular_to_one_relationship(attrs, association_name, param_name, id, type)

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

@@ -45,14 +45,19 @@ module JSONAPI
         relationships[association_name] = result
       end
 
+      # Linkage carries a type and an id, so reading the association directly
+      # leaks the identity of a record the related endpoint denies — the same
+      # bypass the `included` section closes, with a narrower payload. Both
+      # sections resolve through one authorized read, so they always describe
+      # the same set, and the request-scoped filter cache means the second
+      # reader vets nothing the first already vetted.
       def serialize_relationship_data(association)
-        related = record.public_send(association.name)
+        related = get_association_records(record, association.name)
 
-        if association.collection?
-          serialize_collection_relationship(related, association)
-        elsif related
-          serialize_single_relationship(related, association)
-        end
+        return serialize_collection_relationship(related, association) if association.collection?
+
+        first = related.first
+        serialize_single_relationship(first, association) if first
       end
 
       def serialize_collection_relationship(related, association)
@@ -74,6 +79,7 @@ module JSONAPI
           resource_class: definition,
           use_instance_class:,
           base_resource_class: base_def_for_related,
+          namespace:,
         )
       end
 

data/lib/json_api/serialization/include_filter_cache.rb

@@ -15,8 +15,9 @@ module JSONAPI
       Entry = Struct.new(:base_scope, :authorized_scope, :narrowed, :where_clause_empty, :where_hash,
                          keyword_init: true,)
 
-      def initialize(authorization_context: nil)
+      def initialize(authorization_context: nil, namespace: nil)
         @authorization_context = authorization_context
+        @namespace = namespace
         @entries = {}
         @verdicts = {}
       end
@@ -53,7 +54,7 @@ module JSONAPI
       end
 
       def build_entry(klass)
-        base_scope = ResourceLoader.find_for_model(klass).records
+        base_scope = ResourceLoader.find_for_model(klass, namespace: @namespace).records
         authorized_scope = apply_authorization(base_scope, klass)
         Entry.new(
           base_scope: base_scope,

data/lib/json_api/serialization/serializer.rb

@@ -35,10 +35,16 @@ module JSONAPI
       @jsonapi_object = nil
     end
 
+    # namespace is the request's JSON:API namespace. A namespaced endpoint over
+    # a flat model (a public portal that re-exposes an internal model) resolves
+    # to its own resource only when the namespace reaches this far: resolution
+    # by model alone derives the namespace from the model, so a flat model can
+    # never reach a namespaced resource.
     def initialize(record, definition: nil, base_definition: nil, parent_record: nil, association_name: nil,
-                   authorization_context: nil, include_filter_cache: nil)
+                   authorization_context: nil, include_filter_cache: nil, namespace: nil)
       @record = record
-      @definition = definition || ResourceLoader.find_for_model(record.class)
+      @namespace = namespace
+      @definition = definition || ResourceLoader.find_for_model(record.class, namespace:)
       @base_definition = base_definition
       @parent_record = parent_record
       @association_name = association_name
@@ -75,12 +81,12 @@ module JSONAPI
 
     private
 
-    attr_reader :record, :definition, :parent_record, :association_name, :authorization_context
+    attr_reader :record, :definition, :parent_record, :association_name, :authorization_context, :namespace
 
     # 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
-      @include_filter_cache ||= Serialization::IncludeFilterCache.new(authorization_context: authorization_context)
+      @include_filter_cache ||= Serialization::IncludeFilterCache.new(authorization_context:, namespace:)
     end
 
     def base_definition

data/lib/json_api/support/relationship_helpers.rb

@@ -20,7 +20,8 @@ module JSONAPI
     # Delegate to ResourceIdentifier
     # rubocop:disable Lint/UnusedMethodArgument
     def serialize_resource_identifier(
-      record, association: nil, resource_class: nil, use_instance_class: false, base_resource_class: nil
+      record, association: nil, resource_class: nil, use_instance_class: false, base_resource_class: nil,
+      namespace: nil
     )
       # rubocop:enable Lint/UnusedMethodArgument
       ResourceIdentifier.serialize_identifier(
@@ -28,6 +29,7 @@ module JSONAPI
         association:,
         definition: resource_class,
         use_instance_class:,
+        namespace:,
       )
     end
 

data/lib/json_api/support/resource_identifier.rb

@@ -4,10 +4,10 @@ module JSONAPI
   module ResourceIdentifier
     module_function
 
-    def serialize_identifier(record, association:, definition:, use_instance_class: false)
+    def serialize_identifier(record, association:, definition:, use_instance_class: false, namespace: nil)
       model_class = determine_model_class(record, association:, definition:,
                                                   use_instance_class:,)
-      related_definition = JSONAPI::ResourceLoader.find_for_model(model_class)
+      related_definition = JSONAPI::ResourceLoader.find_for_model(model_class, namespace:)
       related_type = TypeConversion.resource_type_name(related_definition)
 
       { type: related_type, id: record.id.to_s }

data/lib/json_api/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jpie
 version: !ruby/object:Gem::Version
-  version: 3.8.2
+  version: 3.9.0
 platform: ruby
 authors:
 - Emil Kampp
@@ -222,7 +222,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.2
 specification_version: 4
 summary: JSON:API compliant Rails gem for producing and consuming JSON:API resources
 test_files: []