jpie 1.5.1 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be60282bbba362a7ac36dca3370a4733981bce7a949352513244879bc76546a7
-  data.tar.gz: 6c391beea011b7fd348f8a2439130ba174dd31fa7b8f9f4ea6eaef5c9fd916ee
+  metadata.gz: 48369caaf5706cefe367cf5450398a4620741a09193d1ad37e4b42738eb33cc3
+  data.tar.gz: 767a5a640a1e0ba22902d7d6d850bcf1c1491ec3903c041845a09d5db9eb60fa
 SHA512:
-  metadata.gz: 13f21d51760a269d54d1bcd46a9be3916506bae8c25af82eaabea8dc7a214d2f3d39b29437ca0703141a794444d13b7ab20ba26ac4f35f4fe3a8ca15207d1630
-  data.tar.gz: 35e11173e5942bc01059217acf3a5028f5980108b2c76e88b33fe03c9c2ae00a4a6a9c0051328e491a257d83700f02f6a206c7a34406cde968af1a6698ac63fd
+  metadata.gz: 73f3dd657b1efa1eda908b32fe45e189ce355a159e8d48b805ebc1b2cf7afdbca2633e31fe93e56d9cf298956561f993db87c9acbe9cf13c12f8d72f8f82e717
+  data.tar.gz: d2f3c7e883efe3a27cadf78287903c26ae6fde6c411f84b553e6fe85fd0e4433eac589dfa42ce43886dccb5ead4828205e1b34139dc5fc0d18792adc8dcc4ca4

data/.rubocop.yml

@@ -107,3 +107,4 @@ RSpec/NestedGroups:
 # Allow more memoized helpers in complex specs
 RSpec/MultipleMemoizedHelpers:
   Max: 8
+

data/Gemfile.lock

@@ -1,9 +1,11 @@
 PATH
   remote: .
   specs:
-    jpie (1.5.1)
-      actionpack (~> 8.0, >= 8.0.0)
-      rails (~> 8.0, >= 8.0.0)
+    jpie (2.0.1)
+      actionpack (~> 8.1, >= 8.1.0)
+      pg_query (>= 4)
+      prosopite (>= 1)
+      rails (~> 8.1, >= 8.1.0)
 
 GEM
   remote: https://rubygems.org/
@@ -101,6 +103,27 @@ GEM
     erubi (1.13.1)
     globalid (1.3.0)
       activesupport (>= 6.1)
+    google-protobuf (4.33.5)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.33.5-aarch64-linux-gnu)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.33.5-aarch64-linux-musl)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.33.5-arm64-darwin)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.33.5-x86_64-darwin)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.33.5-x86_64-linux-gnu)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.33.5-x86_64-linux-musl)
+      bigdecimal
+      rake (>= 13)
     hana (1.3.7)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
@@ -160,10 +183,13 @@ GEM
     parser (3.3.10.0)
       ast (~> 2.4.1)
       racc
+    pg_query (6.2.2)
+      google-protobuf (>= 3.25.3)
     pp (0.6.3)
       prettyprint
     prettyprint (0.2.0)
     prism (1.6.0)
+    prosopite (2.1.2)
     psych (5.2.6)
       date
       stringio

data/README.md

@@ -1,4 +1,4 @@
-# JSONAPI
+# JPie
 
 A Rails 8+ gem that provides JSON:API compliant routing DSL and generic JSON:API controllers for producing and consuming JSON:API resources.
 
@@ -25,7 +25,7 @@ bundle add jpie
 ## Requirements
 
 - Ruby >= 3.4.0
-- Rails >= 8.0.0
+- Rails >= 8.1.0
 
 ## Routing
 
@@ -659,6 +659,153 @@ JSONAPI.configure do |config|
 end
 ```
 
+### N+1 Detection (Rails 8.1+)
+
+The gem uses [Prosopite](https://github.com/charkost/prosopite) to detect real N+1 query patterns on JSON:API requests. When N+1 is detected, it emits a `jpie.n1_detected` event via `Rails.event.notify`. When `n1_detection_enabled` is true, a built-in subscriber logs to `Rails.logger.warn` automatically—no setup required.
+
+**Event:** `jpie.n1_detected`
+
+**Payload:**
+
+```ruby
+{
+  path: "/users",
+  method: "GET",
+  include: nil,
+  resource_type: "users",
+  resource_id: nil,
+  n1_details: "N+1 queries detected:\n  SELECT ... FROM users WHERE id = ?\nCall stack:\n  app/...",
+  n1_query: "SELECT \"users\".* FROM \"users\" WHERE \"users\".\"id\" = 1 LIMIT 1",  # First duplicate query
+  correlation_id: Current.cid  # When config.correlation_id_resolver = -> { Current.cid }
+}
+```
+
+**Custom subscriber (e.g. for APM):**
+
+```ruby
+if Rails.respond_to?(:event)
+  Rails.event.subscribe(Class.new do
+    def emit(event)
+      ev = event.is_a?(Hash) ? event : event.to_h
+      return unless ev[:name] == "jpie.n1_detected"
+
+      payload = ev[:payload] || {}
+      # Forward to Datadog, AppSignal, New Relic, etc.
+    end
+  end.new)
+end
+```
+
+**Configuration:**
+
+```ruby
+JSONAPI.configure do |config|
+  config.n1_detection_enabled = true  # Override: default is !Rails.env.production?
+end
+```
+
+Default: enabled in development and test, disabled in production. Prosopite options (e.g. `Prosopite.rails_logger`, `Prosopite.raise`) remain under app control; the gem only sets `custom_logger` for instrumentation.
+
+### Query Tracking (Slow Query & Excessive Count) (Rails 8.1+)
+
+The gem detects slow SQL queries and excessive query count per JSON:API request. When a single query exceeds the duration threshold or total queries exceed the count threshold, it emits `jpie.slow_query_detected` or `jpie.excessive_queries_detected` via `Rails.event.notify`. When `query_tracking_enabled` is true, a built-in subscriber logs to `Rails.logger.warn` automatically—no setup required.
+
+**Events:** `jpie.slow_query_detected`, `jpie.excessive_queries_detected`
+
+**Payloads:**
+
+```ruby
+# jpie.slow_query_detected
+{
+  path: "/users",
+  method: "GET",
+  include: nil,
+  resource_type: "users",
+  resource_id: nil,
+  sql: "SELECT \"users\".* FROM \"users\" WHERE ...",
+  duration_ms: 523.4,
+  threshold_ms: 200,
+  correlation_id: Current.cid  # When config.correlation_id_resolver = -> { Current.cid }
+}
+
+# jpie.excessive_queries_detected
+{
+  path: "/users",
+  method: "GET",
+  include: nil,
+  resource_type: "users",
+  resource_id: nil,
+  query_count: 127,
+  threshold: 10,
+  queries: ["SELECT ...", "SELECT ...", ...],  # up to query_tracking_queries_cap
+  correlation_id: Current.cid  # When config.correlation_id_resolver = -> { Current.cid }
+}
+```
+
+**Custom subscriber (e.g. for APM):**
+
+```ruby
+if Rails.respond_to?(:event)
+  Rails.event.subscribe(Class.new do
+    def emit(event)
+      ev = event.is_a?(Hash) ? event : event.to_h
+      return unless %w[jpie.slow_query_detected jpie.excessive_queries_detected].include?(ev[:name])
+
+      payload = ev[:payload] || {}
+      # Forward to Datadog, AppSignal, New Relic, etc.
+    end
+  end.new)
+end
+```
+
+**Configuration:**
+
+```ruby
+JSONAPI.configure do |config|
+  config.query_tracking_enabled = true
+  config.query_count_threshold = 10
+  config.slow_query_threshold_ms = 200
+  config.query_tracking_queries_cap = 100
+end
+```
+
+Default: enabled in development and test, disabled in production. Thresholds are configurable.
+
+### Correlation ID
+
+When set, `correlation_id_resolver` is a proc that returns the current request's correlation ID (string or nil). The gem adds `correlation_id` to all JPie event payloads (`jpie.n1_detected`, `jpie.slow_query_detected`, `jpie.excessive_queries_detected`) and tags JPie log output with `CID(...)` when present.
+
+**Configuration:**
+
+```ruby
+JSONAPI.configure do |config|
+  config.correlation_id_resolver = -> { Current.cid }
+end
+```
+
+Default: `nil` (no correlation ID in payloads or logs).
+
+### Response Headers (Development)
+
+When `jpie_headers_enabled` is true (default: development and test only), the gem adds performance headers to JSON:API responses so frontends can surface warnings in dev tools.
+
+**Headers:**
+
+| Header | When Set | Example |
+|--------|----------|---------|
+| `X-JPie-Query-Count` | Always (when query tracking + headers enabled) | `42` |
+| `X-JPie-Performance-Warning` | Only when any event fired (n1, excessive_queries, slow_query) | `n1,excessive_queries` |
+
+**Configuration:**
+
+```ruby
+JSONAPI.configure do |config|
+  config.jpie_headers_enabled = true  # Override: default is !Rails.env.production?
+end
+```
+
+Default: enabled in development and test, disabled in production. Ensure CORS exposes these headers if your frontend runs on a different origin.
+
 ### Base Controller Class
 
 By default, `JSONAPI::BaseController` inherits from `ActionController::API`. You can configure it to inherit from a different base class (e.g., `ActionController::Base` or a custom base controller):

data/jpie.gemspec

@@ -24,8 +24,10 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = ">= 3.4.0"
 
-  spec.add_dependency "actionpack", "~> 8.0", ">= 8.0.0"
-  spec.add_dependency "rails", "~> 8.0", ">= 8.0.0"
+  spec.add_dependency "actionpack", "~> 8.1", ">= 8.1.0"
+  spec.add_dependency "pg_query", ">= 4"
+  spec.add_dependency "prosopite", ">= 1"
+  spec.add_dependency "rails", "~> 8.1", ">= 8.1.0"
 
   spec.metadata["rubygems_mfa_required"] = "true"
 end

data/lib/json_api/configuration.rb

@@ -4,19 +4,15 @@ 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, :namespace_fallback,
+                  :n1_detection_enabled,
+                  :query_tracking_enabled, :query_count_threshold, :slow_query_threshold_ms,
+                  :query_tracking_queries_cap,
+                  :jpie_headers_enabled,
+                  :correlation_id_resolver
 
     def initialize
-      @default_page_size = 25
-      @max_page_size = 100
-      @jsonapi_meta = nil
-      @authorization_handler = nil
-      @authorization_scope = nil
-      @document_meta_resolver = ->(controller:) { {} } # rubocop:disable Lint/UnusedBlockArgument
-      @base_controller_class = "ActionController::API"
-      @namespace_type_format = :flat
-      @namespace_model_mapping = :same_namespace
-      @namespace_fallback = true
+      set_defaults
     end
 
     def base_controller_class=(value)
@@ -49,6 +45,48 @@ module JSONAPI
     def base_controller_overridden?
       @base_controller_class != "ActionController::API"
     end
+
+    private
+
+    def set_defaults
+      set_pagination_defaults
+      set_n1_detection_defaults
+      set_query_tracking_defaults
+      set_nil_defaults
+      @document_meta_resolver = ->(controller:) { {} } # rubocop:disable Lint/UnusedBlockArgument
+      @base_controller_class = "ActionController::API"
+      set_namespace_defaults
+    end
+
+    def set_pagination_defaults
+      @default_page_size = 25
+      @max_page_size = 100
+    end
+
+    def set_n1_detection_defaults
+      @n1_detection_enabled = !defined?(Rails) || !Rails.env.production?
+    end
+
+    def set_query_tracking_defaults
+      @query_tracking_enabled = !defined?(Rails) || !Rails.env.production?
+      @query_count_threshold = 10
+      @slow_query_threshold_ms = 200
+      @query_tracking_queries_cap = 100
+      @jpie_headers_enabled = !defined?(Rails) || !Rails.env.production?
+    end
+
+    def set_nil_defaults
+      @jsonapi_meta = nil
+      @authorization_handler = nil
+      @authorization_scope = nil
+      @correlation_id_resolver = nil
+    end
+
+    def set_namespace_defaults
+      @namespace_type_format = :flat
+      @namespace_model_mapping = :same_namespace
+      @namespace_fallback = true
+    end
   end
 
   def self.configuration

data/lib/json_api/controllers/concerns/controller_helpers/error_rendering.rb

@@ -7,17 +7,16 @@ module JSONAPI
 
       protected
 
+      def render_not_found_error(title:, detail:)
+        render_jsonapi_error(status: 404, title:, detail:)
+      end
+
       def render_resource_not_found_error(message)
-        render_jsonapi_error(
-          status: 404,
-          title: "Resource Not Found",
-          detail: message,
-        )
+        render_not_found_error(title: "Resource Not Found", detail: message)
       end
 
       def render_model_not_found_error(error)
-        render_jsonapi_error(
-          status: 404,
+        render_not_found_error(
           title: "Resource Not Found",
           detail: "Model class for '#{@resource_name}' not found: #{error.message}",
         )

data/lib/json_api/controllers/concerns/controller_helpers/resource_setup.rb

@@ -30,10 +30,9 @@ module JSONAPI
       end
 
       def set_resource
-        @resource = @preloaded_resource || model_class.find(params[:id])
+        @resource = @resource_class.records.find(params[:id])
       rescue ActiveRecord::RecordNotFound
-        render_jsonapi_error(
-          status: 404,
+        render_not_found_error(
           title: "Record Not Found",
           detail: "Could not find #{@resource_name} with id '#{params[:id]}'",
         )

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

@@ -16,12 +16,53 @@ module JSONAPI
       end
 
       def fetch_related_data(association)
-        related = @resource.public_send(@relationship_name)
+        related = fetch_related_through_resource_records(association)
         return related unless association.collection? && related.respond_to?(:order)
 
         apply_sorting_to_relationship(related, association)
       end
 
+      def fetch_related_through_resource_records(association)
+        if association.polymorphic?
+          fetch_polymorphic_related_through_resource_records(association)
+        else
+          fetch_non_polymorphic_related_through_resource_records(association)
+        end
+      end
+
+      def fetch_polymorphic_related_through_resource_records(association)
+        type_value = @resource.read_attribute(association.foreign_type)
+        id_value = @resource.read_attribute(association.foreign_key)
+
+        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)
+        record = related_resource_class.records.find(id_value)
+
+        association.collection? ? Array(record) : record
+      end
+
+      def fetch_blank_polymorphic(association)
+        return nil unless association.collection?
+
+        fetch_polymorphic_has_many_through_resource_records(association)
+      end
+
+      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.records.merge(association_instance.scope)
+      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)
+        scope = related_resource_class.records.merge(association_instance.scope)
+
+        association.collection? ? scope : scope.first
+      end
+
       def serialize_related(related, association)
         return serialize_collection_relationship(related, association) if association.collection?
 

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

@@ -24,7 +24,7 @@ module JSONAPI
       end
 
       def update_to_many_relationship(association, relationship_data)
-        if relationship_data.nil? || empty_array?(relationship_data)
+        if relationship_data.nil? || ParamHelpers.empty_array?(relationship_data)
           @resource.public_send("#{@relationship_name}=", [])
           return
         end
@@ -35,10 +35,6 @@ module JSONAPI
         @resource.public_send("#{@relationship_name}=", related_resources)
       end
 
-      def empty_array?(data)
-        data.is_a?(Array) && data.empty?
-      end
-
       def resolve_related_resources(relationship_data, association)
         relationship_data.map { |identifier| find_related_resource(identifier, association) }
       end

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

@@ -61,14 +61,6 @@ module JSONAPI
         end
       end
 
-      def render_update_error(error)
-        if error.is_a?(ActiveSupport::MessageVerifier::InvalidSignature)
-          render_signed_id_error(error)
-        else
-          render_invalid_relationship_error(error)
-        end
-      end
-
       def render_signed_id_error(error)
         render_jsonapi_error(
           status: 400,

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

@@ -22,15 +22,6 @@ module JSONAPI
         render_sort_errors(invalid) if invalid.any?
       end
 
-      def validate_include_param
-        includes = parse_include_param
-        return if includes.empty?
-
-        permitted = @resource_class.relationship_names.map(&:to_s)
-        invalid = includes.reject { |p| include_path_valid?(p, permitted) }
-        render_include_errors(invalid) if invalid.any?
-      end
-
       private
 
       def first_invalid_field(fields)
@@ -62,27 +53,6 @@ module JSONAPI
         invalid.any? ? { type: resource_type.to_s, invalid: } : nil
       end
 
-      def include_path_valid?(path, permitted)
-        parts = path.split(".")
-        return false unless permitted.include?(parts.first)
-
-        nested_path_valid?(parts)
-      end
-
-      def nested_path_valid?(parts)
-        current = model_class
-        parts.each do |name|
-          return true if self.class.active_storage_attachment?(name, current)
-
-          assoc = current.reflect_on_association(name.to_sym)
-          return false unless assoc
-          break if assoc.polymorphic?
-
-          current = assoc.klass
-        end
-        true
-      end
-
       def render_field_error(error)
         render_parameter_errors(
           error[:invalid],
@@ -100,15 +70,6 @@ module JSONAPI
           source_proc: ->(_) { { parameter: "sort" } },
         )
       end
-
-      def render_include_errors(invalid)
-        render_parameter_errors(
-          invalid,
-          title: "Invalid Include Path",
-          detail_proc: ->(p) { "Invalid include path requested: #{p}" },
-          source_proc: ->(_) { { parameter: "include" } },
-        )
-      end
     end
   end
 end

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

@@ -4,6 +4,7 @@ module JSONAPI
   module ResourceActions
     module FilterValidation
       extend ActiveSupport::Concern
+      include JSONAPI::Support::FilterParsing
 
       def validate_filter_param
         filters = parse_filter_param
@@ -69,13 +70,8 @@ module JSONAPI
       def polymorphic_filter_valid?(parts)
         return false if parts.empty? || parts.length > 1
 
-        m = parts.first.match(/\A(.+)_(eq|match|lt|lte|gt|gte)\z/)
-        %w[id type].include?(m ? m[1] : parts.first)
-      end
-
-      def parse_column_filter(name)
-        m = name.match(/\A(.+)_(eq|match|lt|lte|gt|gte)\z/)
-        m ? { column: m[1], operator: m[2].to_sym } : nil
+        col_filter = parse_column_filter(parts.first)
+        %w[id type].include?(col_filter ? col_filter[:column] : parts.first)
       end
 
       def render_filter_errors(invalid)

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module ResourceActions
+    module IncludePreloading
+      extend ActiveSupport::Concern
+
+      private
+
+      def includes_to_hash(paths)
+        hash = paths.each_with_object({}) do |path, h|
+          path.split(".").reduce(h) { |cur, part| cur[part.to_sym] ||= {} }
+        end
+        filter_includable(hash, model_class)
+      end
+
+      # Preloads associations from the include param so the serializer avoids N+1 queries
+      # when walking include paths (association.loaded? is true). Used by both show and index.
+      def scope_with_includes(scope)
+        includes = parse_include_param
+        return scope unless includes.any?
+
+        inc_hash = includes_to_hash(includes)
+        hash_contains_polymorphic?(inc_hash, model_class) ? scope.preload(inc_hash) : scope.includes(inc_hash)
+      end
+
+      def filter_includable(hash, klass)
+        hash.each_with_object({}) do |(key, value), filtered|
+          assoc = klass.reflect_on_association(key)
+          next unless assoc
+
+          filtered[key] = value.empty? || assoc.polymorphic? ? value : filter_includable(value, assoc.klass)
+        end
+      end
+
+      def hash_contains_polymorphic?(hash, klass)
+        hash.any? { |key, value| polymorphic_in_hash_entry?(key, value, klass) }
+      end
+
+      def polymorphic_in_hash_entry?(key, value, klass)
+        assoc = klass.reflect_on_association(key)
+        return false unless assoc
+
+        assoc.polymorphic? || (value.present? && hash_contains_polymorphic?(value, assoc.klass))
+      end
+
+      def preload_included_resource_associations(resources, includes)
+        return if includes.empty? || resources.empty?
+
+        includes.each do |include_path|
+          association_name = include_path.split(".").first.to_sym
+          assoc_reflection = model_class.reflect_on_association(association_name)
+          next unless assoc_reflection
+
+          targets = collect_include_targets(resources, association_name)
+          next if targets.empty?
+
+          apply_preloads_for_targets(targets, assoc_reflection.polymorphic?)
+        end
+      end
+
+      def apply_preloads_for_targets(targets, polymorphic)
+        if polymorphic
+          targets.group_by(&:class).each_value { |recs| apply_resource_preloads(recs) }
+        else
+          apply_resource_preloads(targets)
+        end
+      end
+
+      def collect_include_targets(resources, association_name)
+        resources.flat_map do |r|
+          target = r.association(association_name).target
+          target.respond_to?(:to_a) ? target.to_a : Array(target)
+        end.compact.uniq
+      end
+
+      def apply_resource_preloads(records)
+        return if records.empty?
+
+        klass = records.first.class
+        resource_scope = ResourceLoader.find_for_model(klass).records
+        preload_values = resource_scope.preload_values + resource_scope.includes_values
+        return if preload_values.empty?
+
+        ActiveRecord::Associations::Preloader.new(records:, associations: preload_values).call
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module ResourceActions
+    module IncludeValidation
+      extend ActiveSupport::Concern
+
+      def validate_include_param
+        includes = parse_include_param
+        return if includes.empty?
+
+        permitted = @resource_class.relationship_names.map(&:to_s)
+        invalid = includes.reject { |p| include_path_valid?(p, permitted) }
+        render_include_errors(invalid) if invalid.any?
+      end
+
+      private
+
+      def include_path_valid?(path, permitted)
+        parts = path.split(".")
+        return false unless permitted.include?(parts.first)
+
+        nested_path_valid?(parts)
+      end
+
+      def nested_path_valid?(parts)
+        current = model_class
+        parts.each do |name|
+          return true if self.class.active_storage_attachment?(name, current)
+
+          assoc = current.reflect_on_association(name.to_sym)
+          return false unless assoc
+          break if assoc.polymorphic?
+
+          current = assoc.klass
+        end
+        true
+      end
+
+      def render_include_errors(invalid)
+        render_parameter_errors(
+          invalid,
+          title: "Invalid Include Path",
+          detail_proc: ->(p) { "Invalid include path requested: #{p}" },
+          source_proc: ->(_) { { parameter: "include" } },
+        )
+      end
+    end
+  end
+end