jpie 2.0.0 → 2.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a598f58a7c0f80730e852f069276ea9d3066d3c7622a8faec599f1b58039f0e
-  data.tar.gz: 33292a3d2e2b98c09fb9868972b2936738ebf00b6ec0a1b7baf46ec51b017369
+  metadata.gz: 1477d2959b9a77a44758b503d4ef674cc72c8bc024fc533673ed699768e2e5a7
+  data.tar.gz: 0db30ba17f5bc3d70f1a531062fc0162ba3bcfe9347c5ec48aebcc1b796ba3a9
 SHA512:
-  metadata.gz: 5b3830b35c1fc6690c755c5f90ad7568ffc6c57d7b8ad0516fdf368f476a15223a0489694acb5ac288d2c5f8f9f8889c154f5e0f09915dfac276b876ed437858
-  data.tar.gz: 0cdc51e099411e4f27342783e3e47bf5e34ff983308758fa904819009df8f23364521a7d1b32a634827fdcba7f4302501202ef4f0c193d119e97b9f9daaf7990
+  metadata.gz: d927ad5ed8efe663829590f423b7f940578afa76a15d0e4ac64cbef89b615a57a6eaa8d4d46140cffe399e4b7c1a067f8e7d1d8a19981b037f0d9bee9f29f050
+  data.tar.gz: 1d9ca2c4e17a36c220a78d92bbdd9014cd924add0c3d194378fabdb5037bdc0be54461f05ca9a33bf5163ea6b68d7e36b052a6221c20cc9aed6b74d2445e15b1

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 (2.0.0)
-      actionpack (~> 8.0, >= 8.0.0)
-      rails (~> 8.0, >= 8.0.0)
+    jpie (2.0.2)
+      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

@@ -25,7 +25,7 @@ bundle add jpie
 ## Requirements
 
 - Ruby >= 3.4.0
-- Rails >= 8.0.0
+- Rails >= 8.1.0
 
 ## Routing
 
@@ -659,26 +659,152 @@ JSONAPI.configure do |config|
 end
 ```
 
-### N+1 Query Warning
+### N+1 Detection (Rails 8.1+)
 
-When clients omit the `include` parameter for nested relationships, the API may execute N+1 queries. The gem detects high query counts and:
+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.
 
-1. **Logs** a warning to `Rails.logger` with path, include param, and query count
-2. **Adds response headers** so clients can detect and fix their requests:
-   - `X-JPie-Query-Count` – number of DB queries executed
-   - `Server-Timing` – W3C standard header with query count in `desc`
-   - `X-JPie-Performance-Warning` – when count exceeds threshold, suggests adding `include` param
+**Event:** `jpie.n1_detected`
 
-Configure in an initializer:
+**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.n1_query_threshold = 20   # Warn when queries exceed this (default: 20)
-  config.n1_warning_enabled = true # Set false to disable (default: true)
+  config.jpie_headers_enabled = true  # Override: default is !Rails.env.production?
 end
 ```
 
-Clients can read `X-JPie-Query-Count` or `Server-Timing` to monitor performance and add appropriate `include` values when the warning header appears.
+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
 

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

@@ -5,7 +5,12 @@ module JSONAPI
     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,
-                  :n1_query_threshold, :n1_warning_enabled
+                  :n1_detection_enabled,
+                  :query_tracking_enabled, :query_count_threshold, :slow_query_threshold_ms,
+                  :query_tracking_queries_cap,
+                  :jpie_headers_enabled,
+                  :correlation_id_resolver,
+                  :variant_failure_fallback
 
     def initialize
       set_defaults
@@ -46,7 +51,8 @@ module JSONAPI
 
     def set_defaults
       set_pagination_defaults
-      set_n1_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"
@@ -58,15 +64,24 @@ module JSONAPI
       @max_page_size = 100
     end
 
-    def set_n1_defaults
-      @n1_query_threshold = 20
-      @n1_warning_enabled = true
+    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
+      @variant_failure_fallback = :original
     end
 
     def set_namespace_defaults

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/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

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

@@ -4,6 +4,7 @@ module JSONAPI
   module ResourceActions
     module Serialization
       extend ActiveSupport::Concern
+      include IncludePreloading
 
       def serialize_resource(resource)
         JSONAPI::Serializer.new(resource).to_hash(
@@ -19,6 +20,8 @@ module JSONAPI
         resources = scope_with_includes(resources)
         resources_array = resources.to_a
 
+        preload_included_resource_associations(resources_array, includes)
+
         data, all_included = serialize_resources_with_includes(resources_array, includes, fields)
         build_collection_response(data, all_included)
       end
@@ -56,43 +59,6 @@ module JSONAPI
         processed.add(key)
       end
 
-      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 build_collection_response(data, all_included)
         result = { jsonapi: JSONAPI::Serializer.jsonapi_object, data: }
         result[:included] = all_included if all_included.any?

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

@@ -2,6 +2,8 @@
 
 require_relative "resource_actions/filter_validation"
 require_relative "resource_actions/field_validation"
+require_relative "resource_actions/include_validation"
+require_relative "resource_actions/include_preloading"
 require_relative "resource_actions/serialization"
 require_relative "resource_actions/pagination"
 require_relative "resource_actions/type_validation"
@@ -14,6 +16,7 @@ module JSONAPI
     include ActiveStorageSupport
     include FilterValidation
     include FieldValidation
+    include IncludeValidation
     include Serialization
     include Pagination
     include TypeValidation

data/lib/json_api/rack/n1_detection.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "prosopite"
+
+module JSONAPI
+  module Rack
+    class N1Detection
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        return @app.call(env) unless JSONAPI.configuration.n1_detection_enabled
+        return @app.call(env) unless jsonapi_request?(env)
+        return @app.call(env) unless postgres?
+
+        Thread.current[:jpie_request_env] = env
+        Prosopite.custom_logger = JSONAPI::Support::ProsopiteInstrumentationLogger.new
+
+        result = Prosopite.scan { @app.call(env) }
+        result
+      ensure
+        Prosopite.finish
+        Thread.current[:jpie_request_env] = nil
+      end
+
+      private
+
+      def jsonapi_request?(env)
+        env["HTTP_ACCEPT"].to_s.include?("application/vnd.api+json")
+      end
+
+      def postgres?
+        return false unless defined?(ActiveRecord) && ActiveRecord::Base.connection_db_config
+
+        adapter = ActiveRecord::Base.connection_db_config.adapter
+        adapter.to_s.include?("postgresql")
+      end
+    end
+  end
+end

data/lib/json_api/rack/query_tracking.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Rack
+    class QueryTracking
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        return @app.call(env) unless JSONAPI.configuration.query_tracking_enabled
+        return @app.call(env) unless jsonapi_request?(env)
+
+        call_with_tracking(env)
+      ensure
+        emit_excessive_queries_if_needed
+        Thread.current[:jpie_query_tracking] = nil
+        Thread.current[:jpie_warnings] = nil
+      end
+
+      private
+
+      def call_with_tracking(env)
+        Thread.current[:jpie_query_tracking] = { count: 0, queries: [], env: env }
+        Thread.current[:jpie_warnings] = [] if JSONAPI.configuration.jpie_headers_enabled
+
+        status, headers, body = @app.call(env)
+        add_jpie_headers(headers) if JSONAPI.configuration.jpie_headers_enabled
+
+        [status, headers, body]
+      end
+
+      def jsonapi_request?(env)
+        env["HTTP_ACCEPT"].to_s.include?("application/vnd.api+json")
+      end
+
+      def emit_excessive_queries_if_needed
+        tracking = Thread.current[:jpie_query_tracking]
+        return if tracking.nil?
+
+        count = tracking[:count]
+        threshold = JSONAPI.configuration.query_count_threshold
+        return if count <= threshold
+        return unless defined?(Rails) && Rails.respond_to?(:event)
+
+        notify_excessive_queries(tracking, count, threshold)
+      end
+
+      def notify_excessive_queries(tracking, count, threshold)
+        cap = JSONAPI.configuration.query_tracking_queries_cap
+        queries = tracking[:queries].first(cap)
+        payload = build_excessive_queries_payload(tracking[:env], count, threshold, queries)
+
+        Rails.event.tagged("jsonapi", "excessive_queries") do
+          Rails.event.notify("jpie.excessive_queries_detected", payload)
+        end
+      end
+
+      def build_excessive_queries_payload(env, count, threshold, queries)
+        build_payload(env).merge(
+          query_count: count,
+          threshold: threshold,
+          queries: queries,
+        )
+      end
+
+      def build_payload(env)
+        base = env.nil? ? {} : request_payload_from_env(env)
+        base.merge(correlation_id: JSONAPI::Support::CorrelationId.resolve)
+      end
+
+      def request_payload_from_env(env)
+        req = ActionDispatch::Request.new(env)
+        params = req.params
+        {
+          path: req.path,
+          method: req.request_method,
+          include: params[:include],
+          resource_type: params[:resource_type],
+          resource_id: params[:id],
+        }
+      end
+
+      def add_jpie_headers(headers)
+        tracking = Thread.current[:jpie_query_tracking]
+        return if tracking.nil?
+
+        count = tracking[:count]
+        headers["X-JPie-Query-Count"] = count.to_s
+
+        warning_str = build_performance_warning_header(count)
+        headers["X-JPie-Performance-Warning"] = warning_str if warning_str.present?
+      end
+
+      def build_performance_warning_header(count)
+        warnings = (Thread.current[:jpie_warnings] || []).dup
+        warnings << "excessive_queries" if count > JSONAPI.configuration.query_count_threshold
+        warnings.uniq.join(",").presence
+      end
+    end
+  end
+end

data/lib/json_api/railtie.rb

@@ -16,14 +16,40 @@ module JSONAPI
       Mime::Type.register "application/vnd.api+json", :jsonapi
     end
 
-    initializer "json_api.n1_warning_middleware", after: "action_dispatch.configure" do |app|
+    initializer "json_api.n1_log_subscriber", after: "action_dispatch.configure" do
+      if Rails.respond_to?(:event) && JSONAPI.configuration.n1_detection_enabled
+        Rails.event.subscribe(JSONAPI::Support::N1LogSubscriber.new)
+      end
+    end
+
+    initializer "json_api.n1_detection_middleware", after: "action_dispatch.configure" do |app|
       if app.config.respond_to?(:server_timing) && app.config.server_timing
-        app.config.middleware.insert_after ActionDispatch::ServerTiming, JSONAPI::Rack::N1Warning
+        app.config.middleware.insert_after ActionDispatch::ServerTiming, JSONAPI::Rack::N1Detection
       else
-        app.config.middleware.use JSONAPI::Rack::N1Warning
+        app.config.middleware.use JSONAPI::Rack::N1Detection
       end
     end
 
+    initializer "json_api.query_tracking_subscriber", after: "action_dispatch.configure" do
+      ActiveSupport::Notifications.subscribe("sql.active_record", JSONAPI::Support::QueryTrackingSubscriber.new)
+    end
+
+    initializer "json_api.query_tracking_log_subscriber", after: "action_dispatch.configure" do
+      if Rails.respond_to?(:event) && JSONAPI.configuration.query_tracking_enabled
+        Rails.event.subscribe(JSONAPI::Support::QueryTrackingLogSubscriber.new)
+      end
+    end
+
+    initializer "json_api.header_warning_subscriber", after: "action_dispatch.configure" do
+      if Rails.respond_to?(:event) && JSONAPI.configuration.jpie_headers_enabled
+        Rails.event.subscribe(JSONAPI::Support::HeaderWarningSubscriber.new)
+      end
+    end
+
+    initializer "json_api.query_tracking_middleware", after: "json_api.n1_detection_middleware" do |app|
+      app.config.middleware.insert_after JSONAPI::Rack::N1Detection, JSONAPI::Rack::QueryTracking
+    end
+
     initializer "json_api.routes" do |_app|
       require "json_api/routing"
       ActionDispatch::Routing::Mapper.include JSONAPI::Routing

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

@@ -17,8 +17,15 @@ module JSONAPI
 
       def add_active_storage_download_link(links)
         links[:download] = variant_or_blob_path || fallback_blob_path
-      rescue StandardError
-        links[:download] = fallback_blob_path
+      rescue StandardError => e
+        case JSONAPI.configuration.variant_failure_fallback
+        when :original
+          links[:download] = fallback_blob_path
+        when :none
+          # omit download link
+        when :exception
+          raise e
+        end
       end
 
       def variant_or_blob_path

data/lib/json_api/support/correlation_id.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Support
+    module CorrelationId
+      def self.resolve
+        resolver = JSONAPI.configuration.correlation_id_resolver
+        return nil unless resolver.respond_to?(:call)
+
+        resolver.call
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/json_api/support/header_warning_subscriber.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Support
+    class HeaderWarningSubscriber
+      HEADER_EVENTS = %w[jpie.n1_detected jpie.slow_query_detected].freeze
+
+      def emit(event)
+        ev = event.is_a?(Hash) ? event : event.to_h
+        return unless HEADER_EVENTS.include?(ev[:name])
+
+        Thread.current[:jpie_warnings] ||= []
+        Thread.current[:jpie_warnings] << (ev[:name] == "jpie.n1_detected" ? "n1" : "slow_query")
+      end
+    end
+  end
+end

data/lib/json_api/support/n1_log_subscriber.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Support
+    class N1LogSubscriber
+      def emit(event)
+        ev = event.is_a?(Hash) ? event : event.to_h
+        return unless ev[:name] == "jpie.n1_detected"
+
+        payload = ev[:payload] || {}
+        log_warn(build_message(payload), payload[:correlation_id])
+      end
+
+      private
+
+      def log_warn(msg, cid)
+        if cid.present?
+          Rails.logger.tagged("JPie", "CID(#{cid})") { Rails.logger.warn(msg) }
+        else
+          Rails.logger.warn("[JPie] #{msg}")
+        end
+      end
+
+      def build_message(payload)
+        msg = "N+1 detected #{payload[:method]} #{payload[:path]}"
+        if payload[:resource_type].present?
+          rt = payload[:resource_type]
+          rid = payload[:resource_id]
+          resource = rid.present? ? "#{rt}/#{rid}" : rt
+          msg += " resource=#{resource}"
+        end
+        msg += " include=#{payload[:include]}" if payload[:include].present?
+        msg += " query=#{payload[:n1_query]}" if payload[:n1_query].present?
+        msg
+      end
+    end
+  end
+end

data/lib/json_api/support/prosopite_instrumentation_logger.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Support
+    class ProsopiteInstrumentationLogger
+      def warn(progname = nil, &)
+        n1_details = block_given? ? yield : progname.to_s
+        return if n1_details.nil? || n1_details.empty?
+
+        env = Thread.current[:jpie_request_env]
+        payload = build_payload(env, n1_details)
+
+        return unless defined?(Rails) && Rails.respond_to?(:event)
+
+        Rails.event.tagged("jsonapi", "n1") do
+          Rails.event.notify("jpie.n1_detected", payload)
+        end
+      end
+
+      private
+
+      def build_payload(env, n1_details)
+        base = { n1_details: n1_details, n1_query: extract_first_query(n1_details) }
+        result = if env.nil?
+                   base
+                 else
+                   request_payload(ActionDispatch::Request.new(env), n1_details).merge(n1_query: base[:n1_query])
+                 end
+        result.merge(correlation_id: JSONAPI::Support::CorrelationId.resolve)
+      end
+
+      def extract_first_query(n1_details)
+        return nil if n1_details.nil? || n1_details.empty?
+
+        parts = n1_details.split("Call stack:")
+        return nil if parts.size < 2
+
+        query_section = parts[0].sub(/\AN\+1 queries detected:\n?/, "")
+        first_line = query_section.each_line.map(&:strip).reject(&:empty?).first
+        first_line.presence
+      end
+
+      def request_payload(req, n1_details)
+        params = req.params
+        {
+          path: req.path,
+          method: req.request_method,
+          include: params[:include],
+          resource_type: params[:resource_type],
+          resource_id: params[:id],
+          n1_details: n1_details,
+        }
+      end
+    end
+  end
+end

data/lib/json_api/support/query_tracking_log_subscriber.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Support
+    class QueryTrackingLogSubscriber
+      QUERY_TRACKING_EVENTS = %w[jpie.slow_query_detected jpie.excessive_queries_detected].freeze
+
+      def emit(event)
+        ev = event.is_a?(Hash) ? event : event.to_h
+        name = ev[:name]
+        return unless QUERY_TRACKING_EVENTS.include?(name)
+
+        payload = ev[:payload] || {}
+        msg = if name == "jpie.slow_query_detected"
+                build_slow_query_message(payload)
+              else
+                build_excessive_queries_message(payload)
+              end
+        log_warn(msg, payload[:correlation_id])
+      end
+
+      private
+
+      def log_warn(msg, cid)
+        if cid.present?
+          Rails.logger.tagged("JPie", "CID(#{cid})") { Rails.logger.warn(msg) }
+        else
+          Rails.logger.warn("[JPie] #{msg}")
+        end
+      end
+
+      def build_slow_query_message(payload)
+        msg = "Slow query detected #{payload[:method]} #{payload[:path]}"
+        msg += " resource=#{resource_str(payload)}" if payload[:resource_type].present?
+        msg += " include=#{payload[:include]}" if payload[:include].present?
+        msg += " duration_ms=#{payload[:duration_ms]}" if payload[:duration_ms].present?
+        msg += " sql=#{payload[:sql]}" if payload[:sql].present?
+        msg
+      end
+
+      def build_excessive_queries_message(payload)
+        msg = "Excessive queries detected #{payload[:method]} #{payload[:path]}"
+        msg += " resource=#{resource_str(payload)}" if payload[:resource_type].present?
+        msg += " include=#{payload[:include]}" if payload[:include].present?
+        msg += " query_count=#{payload[:query_count]}" if payload[:query_count].present?
+        msg += " queries=#{payload[:queries].inspect}" if payload[:queries].present?
+        msg
+      end
+
+      def resource_str(payload)
+        rt = payload[:resource_type]
+        rid = payload[:resource_id]
+        rid.present? ? "#{rt}/#{rid}" : rt
+      end
+    end
+  end
+end

data/lib/json_api/support/query_tracking_subscriber.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Support
+    class QueryTrackingSubscriber
+      SKIP_PATTERNS = [
+        /\A\s*(BEGIN|COMMIT|ROLLBACK|SAVEPOINT|RELEASE\s+SAVEPOINT)\b/i,
+        /\A\s*(CREATE|ALTER|DROP)\s+(TABLE|INDEX|DATABASE)/i,
+        /\APRAGMA\b/i,
+        /sqlite_master|sqlite_temp_master/i,
+        /\bFROM\s+pg_/i,
+        /\A\s*(SET|SHOW)\s/i,
+      ].freeze
+
+      def call(name, start, finish, id, payload)
+        tracking = Thread.current[:jpie_query_tracking]
+        return if tracking.nil?
+
+        sql = payload[:sql]
+        return unless count_query?(sql)
+
+        tracking[:count] += 1
+        tracking[:queries] << sql
+
+        maybe_emit_slow_query(tracking, sql, name, start, finish, id, payload)
+      end
+
+      private
+
+      def count_query?(sql)
+        return false if sql.nil?
+
+        SKIP_PATTERNS.none? { |pattern| pattern.match?(sql) }
+      end
+
+      def maybe_emit_slow_query(tracking, sql, name, start, finish, id, payload) # rubocop:disable Metrics/ParameterLists
+        return unless defined?(Rails) && Rails.respond_to?(:event)
+
+        duration_ms = ActiveSupport::Notifications::Event.new(name, start, finish, id, payload).duration
+        threshold_ms = JSONAPI.configuration.slow_query_threshold_ms
+        return if duration_ms < threshold_ms
+
+        emit_slow_query_detected(tracking, sql, duration_ms, threshold_ms)
+      end
+
+      def emit_slow_query_detected(tracking, sql, duration_ms, threshold_ms)
+        event_payload = build_payload(tracking[:env]).merge(
+          sql: sql,
+          duration_ms: duration_ms,
+          threshold_ms: threshold_ms,
+        )
+
+        Rails.event.tagged("jsonapi", "slow_query") do
+          Rails.event.notify("jpie.slow_query_detected", event_payload)
+        end
+      end
+
+      def build_payload(env)
+        base = env.nil? ? {} : request_payload_from_env(env)
+        base.merge(correlation_id: JSONAPI::Support::CorrelationId.resolve)
+      end
+
+      def request_payload_from_env(env)
+        req = ActionDispatch::Request.new(env)
+        params = req.params
+        {
+          path: req.path,
+          method: req.request_method,
+          include: params[:include],
+          resource_type: params[:resource_type],
+          resource_id: params[:id],
+        }
+      end
+    end
+  end
+end

data/lib/json_api/version.rb

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

data/lib/json_api.rb

@@ -29,14 +29,20 @@ require "json_api/support/sort_parsing"
 require "json_api/support/resource_identifier"
 require "json_api/support/relationship_helpers"
 require "json_api/support/param_helpers"
+require "json_api/support/correlation_id"
 require "json_api/active_storage/detection"
 require "json_api/active_storage/serialization"
 require "json_api/active_storage/deserialization"
 require "json_api/support/active_storage_support"
 require "json_api/support/filter_parsing"
 require "json_api/support/collection_query"
-require "json_api/support/query_counter"
-require "json_api/rack/n1_warning"
+require "json_api/support/prosopite_instrumentation_logger"
+require "json_api/support/n1_log_subscriber"
+require "json_api/support/header_warning_subscriber"
+require "json_api/rack/n1_detection"
+require "json_api/support/query_tracking_subscriber"
+require "json_api/support/query_tracking_log_subscriber"
+require "json_api/rack/query_tracking"
 require "json_api/routing"
 require "json_api/support/responders"
 require "json_api/support/instrumentation"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jpie
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.0.2
 platform: ruby
 authors:
 - Emil Kampp
@@ -15,40 +15,68 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.0.0
+        version: 8.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.0.0
+        version: 8.1.0
+- !ruby/object:Gem::Dependency
+  name: pg_query
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: prosopite
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1'
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.0.0
+        version: 8.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.0.0
+        version: 8.1.0
 description: A Rails 8+ gem that provides jsonapi_resources routing DSL and generic
   JSON:API controllers
 email:
@@ -94,6 +122,8 @@ files:
 - lib/json_api/controllers/concerns/resource_actions/crud_helpers.rb
 - lib/json_api/controllers/concerns/resource_actions/field_validation.rb
 - lib/json_api/controllers/concerns/resource_actions/filter_validation.rb
+- lib/json_api/controllers/concerns/resource_actions/include_preloading.rb
+- lib/json_api/controllers/concerns/resource_actions/include_validation.rb
 - lib/json_api/controllers/concerns/resource_actions/pagination.rb
 - lib/json_api/controllers/concerns/resource_actions/resource_loading.rb
 - lib/json_api/controllers/concerns/resource_actions/serialization.rb
@@ -101,7 +131,8 @@ files:
 - lib/json_api/controllers/relationships_controller.rb
 - lib/json_api/controllers/resources_controller.rb
 - lib/json_api/errors/parameter_not_allowed.rb
-- lib/json_api/rack/n1_warning.rb
+- lib/json_api/rack/n1_detection.rb
+- lib/json_api/rack/query_tracking.rb
 - lib/json_api/railtie.rb
 - lib/json_api/resources/active_storage_blob_resource.rb
 - lib/json_api/resources/concerns/attributes_dsl.rb
@@ -135,10 +166,15 @@ files:
 - lib/json_api/support/concerns/polymorphic_filters.rb
 - lib/json_api/support/concerns/regular_filters.rb
 - lib/json_api/support/concerns/sorting.rb
+- lib/json_api/support/correlation_id.rb
 - lib/json_api/support/filter_parsing.rb
+- lib/json_api/support/header_warning_subscriber.rb
 - lib/json_api/support/instrumentation.rb
+- lib/json_api/support/n1_log_subscriber.rb
 - lib/json_api/support/param_helpers.rb
-- lib/json_api/support/query_counter.rb
+- lib/json_api/support/prosopite_instrumentation_logger.rb
+- lib/json_api/support/query_tracking_log_subscriber.rb
+- lib/json_api/support/query_tracking_subscriber.rb
 - lib/json_api/support/relationship_guard.rb
 - lib/json_api/support/relationship_helpers.rb
 - lib/json_api/support/resource_identifier.rb

data/lib/json_api/rack/n1_warning.rb

@@ -1,72 +0,0 @@
-# frozen_string_literal: true
-
-module JSONAPI
-  module Rack
-    class N1Warning
-      def initialize(app)
-        @app = app
-      end
-
-      def call(env)
-        return @app.call(env) unless JSONAPI.configuration.n1_warning_enabled
-        return @app.call(env) unless jsonapi_request?(env)
-
-        result = nil
-        query_count = JSONAPI::QueryCounter.count_queries { result = @app.call(env) }
-        status, headers, body = result
-        headers = add_n1_headers(headers, query_count, env)
-        [status, headers, body]
-      end
-
-      private
-
-      def add_n1_headers(headers, query_count, env)
-        headers = headers.dup
-        headers["X-JPie-Query-Count"] = query_count.to_s
-        headers["Server-Timing"] = append_server_timing(headers["Server-Timing"].to_s, query_count)
-        add_perf_warning_if_needed!(headers, query_count, env)
-        headers
-      end
-
-      def add_perf_warning_if_needed!(headers, query_count, env)
-        threshold = JSONAPI.configuration.n1_query_threshold
-        return unless query_count > threshold
-
-        warning_msg = n1_warning_message(query_count, threshold)
-        headers["X-JPie-Performance-Warning"] = warning_msg
-        headers["Server-Timing"] = [headers["Server-Timing"], perf_warning_metric(warning_msg)].join(", ")
-        log_n1_warning(env, query_count, threshold)
-      end
-
-      def append_server_timing(existing, query_count)
-        db_metric = "db;desc=\"#{query_count} queries\""
-        [existing, db_metric].reject(&:empty?).join(", ")
-      end
-
-      def n1_warning_message(query_count, threshold)
-        "N+1 possible (#{query_count} queries, threshold #{threshold}) - " \
-          "add include param for nested relationships"
-      end
-
-      def perf_warning_metric(warning_msg)
-        safe_desc = warning_msg.tr('"', "'")
-        "perf-warning;desc=\"#{safe_desc}\""
-      end
-
-      def jsonapi_request?(env)
-        env["HTTP_ACCEPT"].to_s.include?("application/vnd.api+json")
-      end
-
-      def log_n1_warning(env, count, threshold)
-        return unless defined?(Rails) && Rails.logger
-
-        req = ActionDispatch::Request.new(env)
-        Rails.logger.warn(
-          "[JPie] N+1 query warning: #{count} queries (threshold #{threshold}) " \
-          "path=#{req.path} include=#{req.params[:include].inspect} " \
-          "resource=#{req.params[:resource_type]}",
-        )
-      end
-    end
-  end
-end

data/lib/json_api/support/query_counter.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module JSONAPI
-  module QueryCounter
-    SKIP_PATTERN = /\A(\s*(BEGIN|COMMIT|ROLLBACK|SAVEPOINT|RELEASE\s+SAVEPOINT)\b)/i
-    SCHEMA_PATTERN = /\A(\s*(CREATE|ALTER|DROP)\s+(TABLE|INDEX|DATABASE))/i
-    PRAGMA_PATTERN = /\APRAGMA\b/i
-    SQLITE_MASTER_PATTERN = /sqlite_master|sqlite_temp_master/i
-
-    def self.count(&)
-      queries = []
-      counter = ->(_name, _start, _finish, _id, payload) { count_sql(queries, payload) }
-      ActiveSupport::Notifications.subscribed(counter, "sql.active_record", &)
-      queries
-    end
-
-    def self.count_queries(&)
-      count(&).size
-    end
-
-    def self.count_sql(queries, payload)
-      sql = payload[:sql]
-      return if sql.nil?
-      return if SKIP_PATTERN.match?(sql)
-      return if SCHEMA_PATTERN.match?(sql)
-      return if PRAGMA_PATTERN.match?(sql)
-      return if SQLITE_MASTER_PATTERN.match?(sql)
-
-      queries << sql
-    end
-  end
-end