ecoportal-api-graphql 1.3.16 → 2.2.0

data/lib/ecoportal/api/graphql/logic/base_query.rb

@@ -1,193 +1,260 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Logic
-        class BaseQuery
-          include Ecoportal::API::Common::GraphQL::ClassHelpers
-
-          inheritable_attrs :accepted_params, :param_defaults
-
-          DETAIL_ERRORS = [
-            Ecoportal::API::Common::GraphQL::ResponseError,
-            Ecoportal::API::Common::Client::Error::UnexpectedServerError,
-            Faraday::ParsingError,
-            Graphlient::Errors::FaradayServerError,
-            Graphlient::Errors::GraphQLError,
-            Graphlient::Errors::ClientError
-          ].freeze
-
-          class << self
-            def param_defaults
-              @param_defaults ||= {}
-            end
-
-            def accepted_params(*keys, default: :unused)
-              @accepted_params ||= []
-              return @accepted_params if keys.empty?
-
-              keys.map(&:to_sym).uniq.each do |key|
-                @accepted_params   |= [key]
-                param_defaults[key] = default unless default == :unused
-              end
-
-              @accepted_params.push(*keys).tap(&:uniq!)
-              @accepted_params
-            end
-
-            def clear_accepted_params
-              @param_defaults  = {}
-              @accepted_params = []
-            end
-
-            def slice_params(kargs)
-              kargs.slice(*accepted_params)
-            end
-
-            # Used to obtain the full `path` in the GraphQL query by using `base_path`
-            # @note it is meant for reusability of queries from different end-points
-            def field_name(str = nil)
-              return @field_name unless str
-
-              @field_name = nil
-              @field_name = str.to_s if str
-              @field_name
-            end
-
-            def base_path(path = :unused)
-              return @base_path if path == :unused
-
-              path ||= []
-              path   = path.to_s.split('.') if path.is_a?(String)
-              path   = path.map(&:to_s).compact
-
-              @base_path = path
-            end
-          end
-
-          include Ecoportal::API::Common::Concerns::Benchmarkable
-
-          attr_reader :client, :base_path
-
-          def initialize(client, path: nil, base_path: self.class.base_path)
-            @path      = path
-            @base_path = base_path
-            @client    = client
-          end
-
-          # Resolves the `path` by using `path` or `base_path` + `class.field_name`.
-          def path(field_name = self.class.field_name)
-            result   = @path
-            result ||= default_path if respond_to?(:default_path, true)
-            result ||= (base_path + [field_name]) if base_path && field_name
-            result ||= [field_name]
-            result
-          end
-
-          # Query rely that manages the different blocks.
-          # @return [Class] an object of `response_class` with the results hanging from `path`.
-          def query(path: self.path, raw_response: {}, **kargs, &block)
-            print = !is_a?(Mutation)
-
-            benchmarking("#{self.class}##{__method__}", print: print) do
-              graphql_query(
-                path:         path,
-                raw_response: raw_response,
-                **kargs,
-                &basic_block(&block)
-              )
-            end
-          end
-
-          def response_class
-            raise "You should override this method in #{self.class}"
-          end
-
-          def access_point(path = [])
-            path.last
-          end
-
-          private
-
-          def basic_block
-            raise "This method should be implemented in the child class #{self.class}"
-          end
-
-          # Types that should be passed through as-is as GraphQL variable values.
-          # Anything else that responds to to_h is treated as a serialisable value object.
-          VARIABLE_PRIMITIVES = [
-            ::NilClass, ::TrueClass, ::FalseClass,
-            ::Integer, ::Float, ::String, ::Symbol,
-            ::Hash, ::Array
-          ].freeze
-          private_constant :VARIABLE_PRIMITIVES
-
-          def normalize_variables(kargs)
-            kargs.transform_values do |v|
-              VARIABLE_PRIMITIVES.any? { |t| v.is_a?(t) } || !v.respond_to?(:to_h) ? v : v.to_h
-            end
-          end
-
-          def graphql_query(path: self.path, raw_response: {}, **kargs, &block)
-            default_params = self.class.param_defaults.dup
-            query_params   = self.class.slice_params(normalize_variables(default_params.merge(kargs)))
-
-            query_str    = client.to_query_string(&block)
-            fragment_str = assemble_fragments(query_str)
-            full_query   = fragment_str.empty? ? query_str : "#{query_str}\n\n#{fragment_str}"
-
-            request(*path) do
-              client.http_client.execute(full_query, variables: query_params).tap do |response|
-                raw_response[:data] = response
-              end
-            end
-          rescue *DETAIL_ERRORS => _err
-            pp kargs
-            puts "Internal Error with these params:\n"
-            pp query_params
-            pp block
-            raise
-          end
-
-          def request(*path)
-            response = yield
-            wrap_response(response, path)
-          end
-
-          # Resolves all fragment spreads in query_str, recursively following
-          # spreads inside assembled fragment bodies until no new names are found.
-          # Names that don't resolve to a registered fragment are skipped safely.
-          def assemble_fragments(query_str)
-            tried     = {}
-            assembled = {}
-            pending   = query_str.scan(/\.\.\.(\w+)/).flatten.map(&:to_sym).uniq
-
-            until (unresolved = pending.reject { |n| tried.key?(n) }).empty?
-              unresolved.each do |name|
-                tried[name] = true
-                frag        = Ecoportal::API::GraphQL::Fragment.assemble(name)
-                next if frag.empty?
-
-                assembled[name] = frag
-                pending |= frag.scan(/\.\.\.(\w+)/).flatten.map(&:to_sym)
-              end
-            end
-
-            assembled.values.join("\n\n")
-          end
-
-          def wrap_response(response, path = [])
-            # we use the Hash, because fragments are persmissioned
-            # see Use of Fragments at https://github.com/ashkan18/graphlient/tree/master?tab=readme-ov-file#use-of-fragments
-            unless (res = response.to_h.dig(*path.dup.unshift('data')))
-              msg = "Complete failure on request. Path: #{path}\n#{response.to_h.pretty_inspect}"
-              raise msg
-            end
-
-            data = Ecoportal::API::Common::GraphQL::HashHelpers.deep_dup(res)
-            response_class.new(data)
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Logic
+        class BaseQuery
+          include Ecoportal::API::Common::GraphQL::ClassHelpers
+
+          inheritable_attrs :accepted_params, :param_defaults
+
+          DETAIL_ERRORS = [
+            Ecoportal::API::Common::GraphQL::ResponseError,
+            Ecoportal::API::Common::Client::Error::UnexpectedServerError,
+            Faraday::ParsingError,
+            Graphlient::Errors::FaradayServerError,
+            Graphlient::Errors::GraphQLError,
+            Graphlient::Errors::ClientError
+          ].freeze
+
+          class << self
+            def param_defaults
+              @param_defaults ||= {}
+            end
+
+            def accepted_params(*keys, default: :unused)
+              @accepted_params ||= []
+              return @accepted_params if keys.empty?
+
+              keys.map(&:to_sym).uniq.each do |key|
+                @accepted_params   |= [key]
+                param_defaults[key] = default unless default == :unused
+              end
+
+              @accepted_params.push(*keys).tap(&:uniq!)
+              @accepted_params
+            end
+
+            def clear_accepted_params
+              @param_defaults  = {}
+              @accepted_params = []
+            end
+
+            def slice_params(kargs)
+              kargs.slice(*accepted_params)
+            end
+
+            # Used to obtain the full `path` in the GraphQL query by using `base_path`
+            # @note it is meant for reusability of queries from different end-points
+            def field_name(str = nil)
+              return @field_name unless str
+
+              @field_name = nil
+              @field_name = str.to_s if str
+              @field_name
+            end
+
+            def base_path(path = :unused)
+              return @base_path if path == :unused
+
+              path ||= []
+              path   = path.to_s.split('.') if path.is_a?(String)
+              path   = path.map(&:to_s).compact
+
+              @base_path = path
+            end
+          end
+
+          include Ecoportal::API::Common::Concerns::Benchmarkable
+
+          attr_reader :client, :base_path
+
+          def initialize(client, path: nil, base_path: self.class.base_path)
+            @path      = path
+            @base_path = base_path
+            @client    = client
+          end
+
+          # Resolves the `path` by using `path` or `base_path` + `class.field_name`.
+          def path(field_name = self.class.field_name)
+            result   = @path
+            result ||= default_path if respond_to?(:default_path, true)
+            result ||= (base_path + [field_name]) if base_path && field_name
+            result ||= [field_name]
+            result
+          end
+
+          # Query rely that manages the different blocks.
+          # @return [Class] an object of `response_class` with the results hanging from `path`.
+          def query(path: self.path, raw_response: {}, **kargs, &block)
+            print = !is_a?(Mutation)
+
+            benchmarking("#{self.class}##{__method__}", print: print) do
+              graphql_query(
+                path:         path,
+                raw_response: raw_response,
+                **kargs,
+                &basic_block(&block)
+              )
+            end
+          end
+
+          def response_class
+            raise "You should override this method in #{self.class}"
+          end
+
+          def access_point(path = [])
+            path.last
+          end
+
+          private
+
+          def basic_block
+            raise "This method should be implemented in the child class #{self.class}"
+          end
+
+          # Types that should be passed through as-is as GraphQL variable values.
+          # Anything else that responds to to_h is treated as a serialisable value object.
+          VARIABLE_PRIMITIVES = [
+            ::NilClass, ::TrueClass, ::FalseClass,
+            ::Integer, ::Float, ::String, ::Symbol,
+            ::Hash, ::Array
+          ].freeze
+          private_constant :VARIABLE_PRIMITIVES
+
+          def normalize_variables(kargs)
+            kargs.transform_values do |v|
+              VARIABLE_PRIMITIVES.any? { |t| v.is_a?(t) } || !v.respond_to?(:to_h) ? v : v.to_h
+            end
+          end
+
+          def graphql_query(path: self.path, raw_response: {}, **kargs, &block)
+            default_params = self.class.param_defaults.dup
+            query_params   = self.class.slice_params(normalize_variables(default_params.merge(kargs)))
+
+            query_str    = client.to_query_string(&block)
+            fragment_str = assemble_fragments(query_str)
+            full_query   = fragment_str.empty? ? query_str : "#{query_str}\n\n#{fragment_str}"
+
+            request(*path) do
+              client.http_client.execute(full_query, variables: query_params).tap do |response|
+                raw_response[:data] = response
+              end
+            end
+          rescue *DETAIL_ERRORS => err
+            report_query_failure(err, query_params)
+            raise
+          end
+
+          # Reports WHERE a query failed, on stderr, and re-raises untouched.
+          #
+          # ★ This replaces an unconditional `pp kargs` / `pp query_params` / `pp block`
+          # to STDOUT. That dump was NOT debug litter — it existed because graphlient
+          # masks the origin of a failure: `Client#parse`/`#execute` do
+          # `raise Graphlient::Errors::ClientError, e.message`, which leaves graphlient's
+          # own `inner_exception` nil AND replaces the backtrace, discarding the source
+          # location `graphql-client` deliberately sets via
+          # `set_backtrace(["#{filename}:#{line}"])`. With that gone there was no other
+          # way to see which query blew up. (Tracked upstream; see
+          # `.ai-assistance/code/refactoring/opportunities.md`.)
+          #
+          # But the location was never actually destroyed. Ruby populates `.cause`
+          # automatically when you raise inside a rescue, so the original error — with the
+          # location intact — is one hop away. Verified by execution:
+          #
+          #   err.inner_exception        => nil                    (graphlient's api, broken)
+          #   err.backtrace.first        => ".../client.rb:20"     (the raise site, useless)
+          #   err.cause.backtrace.first  => "app/queries/x.rb:198" (the QUERY site)
+          #
+          # So this reports MORE of what the dump was for (the failing query's own source
+          # location) and LESS of what it should never have emitted: `query_params` holds
+          # GraphQL variables — page ids, emails, field values — and printing them to
+          # stdout put customer data into CI logs. Variables are now shown only when the
+          # client's existing `deep_logging` flag is on (see `dump_variables?` for why NOT
+          # the logger level). `pp block` is dropped outright: inspecting a Proc never
+          # identified anything.
+          #
+          # Emitted with `warn` (stderr, and suppressible via the Warning module) rather than
+          # `puts`, so tools that pipe query results keep a clean stdout. Tracked as Q-43.
+          def report_query_failure(err, query_params = nil)
+            origin = err.cause
+            lines  = ["[#{self.class.name || self.class}] #{err.class}: #{failure_message(err)}"]
+            lines << "  origin: #{origin.class}" if origin
+            lines << "  at:     #{origin.backtrace.first}" if origin&.backtrace&.first
+            lines << "  params: #{query_params.inspect}" if dump_variables?
+
+            warn(lines.join("\n"))
+          end
+
+          # graphlient's `GraphQLError#to_s` / `ExecutionError#to_s` format from
+          # `errors.details` and render an EMPTY string when that is empty — and because
+          # they override `to_s`, the fallback text their constructors pass to `super` is
+          # unreachable. An exception with a blank message is invisible in a log, so say
+          # so rather than printing nothing.
+          def failure_message(err)
+            msg = err.message.to_s
+            return msg unless msg.empty?
+
+            "(blank — #{err.class} renders its message from errors.details, which was empty)"
+          end
+
+          # Opt-in via the client's EXISTING `deep_logging` flag ("whether or not batch
+          # responses should be logged") — the same class of thing as dumping variables,
+          # and it defaults to false. No new env var and no new config knob.
+          #
+          # ⚠ Do NOT gate this on `logger.debug?`, which is the obvious-looking choice and
+          # is wrong: `HttpClient`'s default logger is `::Logger.new(IO::NULL)`, and a
+          # fresh Logger's level is DEBUG (0) — so `logger.debug?` is `true` out of the
+          # box and variables would leak by default, which is the whole thing being fixed.
+          # A spec pins this.
+          def dump_variables?
+            http = client&.http_client
+            return false unless http.respond_to?(:deep_logging?, true)
+
+            !!http.send(:deep_logging?)
+          rescue StandardError
+            false
+          end
+
+          def request(*path)
+            response = yield
+            wrap_response(response, path)
+          end
+
+          # Resolves all fragment spreads in query_str, recursively following
+          # spreads inside assembled fragment bodies until no new names are found.
+          # Names that don't resolve to a registered fragment are skipped safely.
+          def assemble_fragments(query_str)
+            tried     = {}
+            assembled = {}
+            pending   = query_str.scan(/\.\.\.(\w+)/).flatten.map(&:to_sym).uniq
+
+            until (unresolved = pending.reject { |n| tried.key?(n) }).empty?
+              unresolved.each do |name|
+                tried[name] = true
+                frag        = Ecoportal::API::GraphQL::Fragment.assemble(name)
+                next if frag.empty?
+
+                assembled[name] = frag
+                pending |= frag.scan(/\.\.\.(\w+)/).flatten.map(&:to_sym)
+              end
+            end
+
+            assembled.values.join("\n\n")
+          end
+
+          def wrap_response(response, path = [])
+            # we use the Hash, because fragments are persmissioned
+            # see Use of Fragments at https://github.com/ashkan18/graphlient/tree/master?tab=readme-ov-file#use-of-fragments
+            unless (res = response.to_h.dig(*path.dup.unshift('data')))
+              msg = "Complete failure on request. Path: #{path}\n#{response.to_h.pretty_inspect}"
+              raise msg
+            end
+
+            data = Ecoportal::API::Common::GraphQL::HashHelpers.deep_dup(res)
+            response_class.new(data)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/logic/connection.rb

@@ -18,6 +18,23 @@ module Ecoportal
           embeds_many :nodes, klass: :node_class
           embeds_one :pageInfo, klass: Base::PageInfo
 
+          # Bind a connection subclass to its concrete node type.
+          #
+          # The base `embeds_many :nodes, klass: :node_class` builds a SINGLE dynamic
+          # `CollectionModel` ("nodes::node_class") that every subclass inherits and shares.
+          # The v2 collection layer memoizes the resolved class on that shared collection
+          # (items_klass.rb:62-63), so the FIRST connection instantiated in a process poisons
+          # every other connection's instance `nodes` typing (e.g. a MinimalDashboard connection
+          # returning AuthLog nodes). Declaring `embeds_many :nodes` per subclass with the concrete
+          # class gives each subclass its OWN collection ("nodes::Model::X") bound to a real Class —
+          # no shared symbol, nothing to memoize wrongly.
+          #
+          # Use `nodes_of Model::X` in a subclass instead of `class_resolver :node_class, Model::X`.
+          def self.nodes_of(klass)
+            class_resolver :node_class, klass
+            embeds_many :nodes, klass: klass
+          end
+
           def empty?
             count < 1
           end

data/lib/ecoportal/api/graphql/logic/input.rb

@@ -5,6 +5,133 @@ module Ecoportal
         class Input < Logic::BaseModel
           passthrough :clientMutationId
 
+          # Declarative set-diff macro for id-list fields that the schema exposes as
+          # `IdDiffInput { additions: [ID!], removals: [ID!] }` on the *update* mutation.
+          #
+          # Mixed into any Input class (whether it inherits from {Logic::Input} or from a
+          # `Base::` data model) via `extend`. {Logic::Input} extends it for its own subclasses;
+          # data-model Input classes call `extend Logic::Input::IdDiffFields` explicitly.
+          #
+          # Usage:
+          #   class Update < Base::ContractorEntity
+          #     extend Logic::Input::IdDiffFields
+          #     id_diff_fields :associatedPeopleIds, :leadContractorIds
+          #   end
+          #
+          # It installs (or augments) a `from_model` that, for each declared field, computes the
+          # delta DIRECTLY from the READ model's `doc[key]` vs `original_doc[key]` arrays:
+          #   additions = current - original
+          #   removals  = original - current
+          # A field is omitted when unchanged. The delta is computed directly (NOT via the
+          # cascaded DiffService) because these array fields are dropped from the flat diff and
+          # the read model is `root!` (so its doc/original_doc resolve without cascade side effects).
+          module IdDiffFields
+            # @return [Array<Symbol>] the fields declared for set-diff on this class.
+            def id_diff_fields_list
+              @id_diff_fields_list ||= []
+            end
+
+            # Declares the id-list fields that must be reshaped into IdDiff `{ additions:, removals: }`.
+            # @param fields [Array<Symbol>] field names (as they appear in the read model's doc).
+            # @return [void]
+            def id_diff_fields(*fields)
+              id_diff_fields_list.concat(fields.flatten.map(&:to_sym)).uniq!
+            end
+
+            # Computes the IdDiff-shaped deltas for the declared fields and merges them into +diff+.
+            # @param model [Common::GraphQL::Model] the subject (read) model.
+            # @param diff [Hash, nil] the base mutation input hash to augment (may be nil).
+            # @return [Hash, nil] +diff+ with per-field `{ additions:, removals: }` merged in,
+            #   or the original value when nothing changed.
+            def merge_id_diffs(model, diff)
+              id_diff_fields_list.each do |field|
+                key      = field.to_s
+                current  = Array(model.doc[key])
+                original = Array(model.original_doc[key])
+                next if current == original
+
+                diff        ||= {}
+                diff[:id]   ||= model.id if model.respond_to?(:id)
+                diff[field]   = { additions: current - original, removals: original - current }
+              end
+              diff
+            end
+
+            # Reshaping `from_model`: base diff (via {Logic::Input.from_model}) + set-diff deltas.
+            # @param model [Common::GraphQL::Model] the subject model.
+            # @return [Hash, nil] the mutation input hash, or nil when there are no changes.
+            def from_model(model, **kargs)
+              diff = Logic::Input.from_model(model, **kargs)
+              merge_id_diffs(model, diff)
+            end
+          end
+
+          # Declarative FULL-ARRAY macro for id-list fields that the schema exposes as a plain
+          # `[ID!]` on the *update* mutation (NOT `IdDiffInput`). The server expects the COMPLETE
+          # current array, replacing the stored value wholesale — there is no additions/removals
+          # delta shape. This is the counterpart to {IdDiffFields}.
+          #
+          # Mixed into any Input class via `extend`, exactly like {IdDiffFields}. Data-model Input
+          # classes call `extend Logic::Input::FullArrayFields` explicitly.
+          #
+          # Usage:
+          #   class Update < Base::Action
+          #     extend Logic::Input::FullArrayFields
+          #     full_array_fields :assignedPersonMemberIds, :locationIds, :fileContainerIds
+          #   end
+          #
+          # It installs (or augments) a `from_model` that, for each declared field, emits the FULL
+          # current array taken DIRECTLY from the READ model's `doc[key]` whenever it differs from
+          # `original_doc[key]`. A field is omitted when unchanged. The value is read directly (NOT
+          # via the cascaded DiffService) because these array fields are dropped from the flat diff
+          # and the read model is `root!`.
+          #
+          # Schema evidence (live introspection 20260605, UpdateActionInput):
+          #   assignedPersonMemberIds : [ID!]
+          #   locationIds             : [ID!]
+          #   fileContainerIds        : [ID!]
+          # None are `IdDiffInput` — hence full-array, not delta.
+          module FullArrayFields
+            # @return [Array<Symbol>] the fields declared for full-array emission on this class.
+            def full_array_fields_list
+              @full_array_fields_list ||= []
+            end
+
+            # Declares the id-list fields that must be emitted as their COMPLETE current array.
+            # @param fields [Array<Symbol>] field names (as they appear in the read model's doc).
+            # @return [void]
+            def full_array_fields(*fields)
+              full_array_fields_list.concat(fields.flatten.map(&:to_sym)).uniq!
+            end
+
+            # Emits the full current array for each changed declared field and merges it into +diff+.
+            # @param model [Common::GraphQL::Model] the subject (read) model.
+            # @param diff [Hash, nil] the base mutation input hash to augment (may be nil).
+            # @return [Hash, nil] +diff+ with per-field full arrays merged in, or the original
+            #   value when nothing changed.
+            def merge_full_arrays(model, diff)
+              full_array_fields_list.each do |field|
+                key      = field.to_s
+                current  = Array(model.doc[key])
+                original = Array(model.original_doc[key])
+                next if current == original
+
+                diff        ||= {}
+                diff[:id]   ||= model.id if model.respond_to?(:id)
+                diff[field]   = current
+              end
+              diff
+            end
+
+            # Reshaping `from_model`: base diff (via {Logic::Input.from_model}) + full arrays.
+            # @param model [Common::GraphQL::Model] the subject model.
+            # @return [Hash, nil] the mutation input hash, or nil when there are no changes.
+            def from_model(model, **kargs)
+              diff = Logic::Input.from_model(model, **kargs)
+              merge_full_arrays(model, diff)
+            end
+          end
+
           class << self
             # Builds a mutation input hash from a model's diff.
             # Subclasses override this to reshape fields (e.g. array → IdDiffInput).