ecoportal-api-graphql 2.0.0 → 3.0.0

data/lib/ecoportal/api/common/graphql/hash_helpers.rb

@@ -1,105 +1,105 @@
-module Ecoportal
-  module API
-    module Common
-      module GraphQL
-        module HashHelpers
-          class << self
-            def included(base)
-              base.send(:include, InstanceMethods)
-            end
-          end
-
-          module InstanceMethods
-            def keys_to_sym_deep(value)
-              transform_keys_deep(value, &:to_sym)
-            end
-
-            def keys_to_s_deep(value)
-              transform_keys_deep(value, &:to_s)
-            end
-
-            def except_keys(value, *keys)
-              return value unless value.is_a?(Hash)
-
-              deep_dup(value).tap do |out|
-                keys.each {|key| out.delete(key)}
-              end
-            end
-
-            # Targetted removal of keys in `target` that are `nil`
-            def remove_nil_keys_deep(value, target: [])
-              remove_keys_deep_if(value, target: target, &:nil?)
-            end
-
-            # Based on Rails support.
-            def deep_dup(data)
-              case data
-              when Hash
-                data.each_with_object({}) do |(k, v), copy|
-                  if k.is_a?(::String) || k.is_a?(::Symbol)
-                    copy[k] = deep_dup(v)
-                  else
-                    copy.delete(k)
-                    copy[deep_dup(k)] = deep_dup(v)
-                  end
-                end
-              when Enumerable
-                data.map {|d| deep_dup(d)}
-              else
-                data.dup
-              end
-            end
-
-            private
-
-            # Iterator
-            # @param value [Variadic]
-            # @return [value.class]
-            def transform_keys_deep(value, &block)
-              case value
-              when Hash
-                value.dup.each_with_object({}) do |(k, v), out|
-                  k_val      = block_given?? yield(k) : k
-                  out[k_val] = transform_keys_deep(v, &block)
-                end
-              when Enumerable
-                value.map {|v| transform_keys_deep(v, &block)}
-              else
-                value
-              end
-            end
-
-            # Targetted removal of keys in `target` that meet
-            # the `block` condition.
-            # @param value [Variadic]
-            # @param target [Array<String>, Array<Symbol>] the target
-            #   `keys` to yield `block` onto.
-            # @return [value.class]
-            def remove_keys_deep_if(value, target: [], &block)
-              msg = 'Expected block. None given.'
-              raise ArgumentError, msg unless block_given?
-
-              target = [target].flatten.compact
-              return value if target.empty?
-
-              case value
-              when Hash
-                value.dup.each_with_object({}) do |(k, v), out|
-                  next if yield(v) && target.include?(k) # skip
-
-                  out[k] = remove_nil_keys_deep(v, target: target, &block)
-                end
-              when Enumerable
-                value.map {|v| remove_nil_keys_deep(v, target: target, &block)}
-              else
-                value
-              end
-            end
-          end
-
-          extend InstanceMethods
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    module Common
+      module GraphQL
+        module HashHelpers
+          class << self
+            def included(base)
+              base.send(:include, InstanceMethods)
+            end
+          end
+
+          module InstanceMethods
+            def keys_to_sym_deep(value)
+              transform_keys_deep(value, &:to_sym)
+            end
+
+            def keys_to_s_deep(value)
+              transform_keys_deep(value, &:to_s)
+            end
+
+            def except_keys(value, *keys)
+              return value unless value.is_a?(Hash)
+
+              deep_dup(value).tap do |out|
+                keys.each {|key| out.delete(key)}
+              end
+            end
+
+            # Targetted removal of keys in `target` that are `nil`
+            def remove_nil_keys_deep(value, target: [])
+              remove_keys_deep_if(value, target: target, &:nil?)
+            end
+
+            # Based on Rails support.
+            def deep_dup(data)
+              case data
+              when Hash
+                data.each_with_object({}) do |(k, v), copy|
+                  if k.is_a?(::String) || k.is_a?(::Symbol)
+                    copy[k] = deep_dup(v)
+                  else
+                    copy.delete(k)
+                    copy[deep_dup(k)] = deep_dup(v)
+                  end
+                end
+              when Enumerable
+                data.map {|d| deep_dup(d)}
+              else
+                data.dup
+              end
+            end
+
+            private
+
+            # Iterator
+            # @param value [Variadic]
+            # @return [value.class]
+            def transform_keys_deep(value, &block)
+              case value
+              when Hash
+                value.dup.each_with_object({}) do |(k, v), out|
+                  k_val      = block_given?? yield(k) : k
+                  out[k_val] = transform_keys_deep(v, &block)
+                end
+              when Enumerable
+                value.map {|v| transform_keys_deep(v, &block)}
+              else
+                value
+              end
+            end
+
+            # Targetted removal of keys in `target` that meet
+            # the `block` condition.
+            # @param value [Variadic]
+            # @param target [Array<String>, Array<Symbol>] the target
+            #   `keys` to yield `block` onto.
+            # @return [value.class]
+            def remove_keys_deep_if(value, target: [], &block)
+              msg = 'Expected block. None given.'
+              raise ArgumentError, msg unless block_given?
+
+              target = [target].flatten.compact
+              return value if target.empty?
+
+              case value
+              when Hash
+                value.dup.each_with_object({}) do |(k, v), out|
+                  next if yield(v) && target.include?(k) # skip
+
+                  out[k] = remove_nil_keys_deep(v, target: target, &block)
+                end
+              when Enumerable
+                value.map {|v| remove_nil_keys_deep(v, target: target, &block)}
+              else
+                value
+              end
+            end
+          end
+
+          extend InstanceMethods
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/common/graphql/http_client.rb

@@ -2,7 +2,88 @@ module Ecoportal
   module API
     module Common
       module GraphQL
-        class ResponseError < StandardError; end
+        # Raised when a 200 response carries a top-level `errors[]` array.
+        #
+        # ★ Carries the RAW error entries, so `extensions` survives. Before this, the
+        # class collapsed the response into the joined `message` text and threw the rest
+        # away — which made it impossible for Ruby tooling to tell a permission problem
+        # from a request problem, the exact diagnosis we tell customers to perform.
+        # Tracked as Q-27 in `docs/open-questions.md`.
+        #
+        # The backend's error contract (`app/graphql/eco_portal_schema.rb`, verified
+        # 2026-09-01) puts these keys under `extensions`:
+        #
+        # | key            | when                     | shape |
+        # |----------------|--------------------------|-------|
+        # | `code`         | always                   | string: `unauthorized`, `document_not_found`, `unprocessable_entity`, `write_conflict`, `internal_server_error`, … |
+        # | `fullMessages` | `unauthorized`           | array of human strings (`exp.result.reasons.full_messages`) |
+        # | `details`      | `unauthorized`           | ActionPolicy `reasons.details` — usually a Hash whose **key names the failing policy** and whose value lists the rules |
+        # | `problems`     | validation, and only when the server runs with `SHOW_GRAPHQL_EXCEPTION` | record errors |
+        #
+        # ⚠ `details` is NOT reliably a Hash. Two call sites emit an Array instead
+        # (`mutations/pages/send_as_email.rb` sends inaccessible ids;
+        # `queries/pages/templates/fetcher.rb` sends `[msg]`). Accessors here therefore
+        # return whatever the server sent, unwrapped but uncoerced — callers must not
+        # assume a shape.
+        class ResponseError < StandardError
+          # @return [Array<Hash>] the raw `errors[]` entries, exactly as received.
+          attr_reader :errors
+
+          # @param msg [String, nil] explicit message; defaults to the joined error messages.
+          # @param errors [Array<Hash>] raw top-level `errors[]` entries.
+          def initialize(msg = nil, errors: [])
+            @errors = Array(errors)
+            super(msg || build_message)
+          end
+
+          # @return [Array<Hash>] the `extensions` object of each error that carried one.
+          def extensions
+            errors.filter_map { |err| err['extensions'] }
+          end
+
+          # @return [Array<String>] every `extensions.code` present, in order.
+          def codes
+            extensions.filter_map { |ext| ext['code'] }
+          end
+
+          # ★ The fastest way to tell a permission problem from a request problem.
+          # @return [Array] every `extensions.details` present. Shape is the server's —
+          #   typically a Hash keyed by the failing policy, but sometimes an Array.
+          def details
+            extensions.filter_map { |ext| ext['details'] }
+          end
+
+          # @return [Array<String>] flattened `extensions.fullMessages`.
+          def full_messages
+            extensions.flat_map { |ext| Array(ext['fullMessages']) }
+          end
+
+          # @return [Boolean] whether ANY error was an authorization refusal. Use this to
+          #   branch on "you cannot" vs "that request was wrong" — do not pattern-match
+          #   the message text, which is prose and drifts.
+          def unauthorized?
+            codes.include?('unauthorized')
+          end
+
+          private
+
+          # The joined messages stay FIRST and unchanged, so existing callers matching on
+          # the message text keep working; the diagnosis is appended after them.
+          def build_message
+            base = errors.filter_map { |err| err['message'] }.join('; ')
+            base = 'GraphQL request failed' if base.empty?
+            [base, diagnosis].compact.join(' | ')
+          end
+
+          def diagnosis
+            parts = []
+            parts << "code: #{codes.uniq.join(', ')}" if codes.any?
+            parts << "details: #{details.inspect}"    if details.any?
+            return if parts.empty?
+
+            parts.join(' | ')
+          end
+        end
 
         class HttpClient < Common::Client
           class << self
@@ -15,9 +96,11 @@ module Ecoportal
             end
           end
 
-          ENDPOINT_PATH = 'external/graphql'.freeze
-          READ_TIMEOUT  = 90
-          WRITE_TIMEOUT = 90
+          ENDPOINT_PATH      = 'external/graphql'.freeze
+          CONNECT_TIMEOUT    = 30
+          READ_TIMEOUT       = 90
+          WRITE_TIMEOUT      = 90
+          KEEP_ALIVE_TIMEOUT = 5
 
           attr_reader :host, :version
 
@@ -56,6 +139,36 @@ module Ecoportal
 
           # Creates a HTTP object adding the `X-ApiKey` or `X-ECOPORTAL-API-KEY` param to the header, depending on the API version.
           # @note It configures HTTP so it only allows body data in json format.
+          # @note This is the ONLY place in the gem's dependency chain that talks to the
+          #   server via http.rb (`require 'http'`, pulled in by `Ecoportal::API::Common::Client`
+          #   from the `ecoportal-api` gem) -- every live GraphQL query goes through `#execute`
+          #   below, called from `Logic::BaseQuery#graphql_query` via `client.http_client.execute`,
+          #   and `AuthService#auth_http_client` (`version: 'http'`) reuses this same
+          #   `base_request` for the OAuth token POST. `Common::GraphQL::Client` (graphlient) is a
+          #   separate, unrelated path: it never reaches http.rb at all.
+          #
+          #   Without an explicit `connect:`, http.rb's `HTTP::Timeout::PerOperation` falls back
+          #   to its own default of 0.25s for CONNECT even though read/write were already given
+          #   explicitly (per_operation.rb: `options.fetch(:connect_timeout, CONNECT_TIMEOUT)`,
+          #   `CONNECT_TIMEOUT = 0.25`). `connect_ssl` (`http/timeout/per_operation.rb`) uses
+          #   that same `@connect_timeout` for the TLS handshake via `rescue_readable`/
+          #   `rescue_writable` (`http/timeout/null.rb`) -- whose error text is unconditionally
+          #   "Read timed out after #{@read_timeout} seconds", so a slow TLS handshake on the EU
+          #   instance surfaced as `HTTP::TimeoutError: Read timed out after 0.25 seconds`
+          #   even though `@read_timeout` itself was correctly 90 the whole time. Live-confirmed
+          #   2026-09-08 via backtrace: `connect_ssl` -> `start_tls` (`http/connection.rb`) ->
+          #   `Common::Client#post` -> `AuthService#session_token_data` ->
+          #   `Common::GraphQL::Client#initialize`. Read/write were never the problem; only
+          #   connect was missing.
+          # @note The client is made PERSISTENT (`HTTP.persistent`) to `base_url`, not a
+          #   plain one-shot client. Confirmed live 2026-09-08: eu.live.ecoportal.com
+          #   closes an HTTP/1.1 request carrying `Connection: close` -- what a
+          #   non-persistent http.rb client always sends -- without ever responding. A
+          #   persistent client sends `Connection: keep-alive` and reuses the TCP/TLS
+          #   connection instead, which the SAME Ruby stack proved fine against EU. This
+          #   also matches Cloudflare keep-alive hygiene; Sydney is fine either way. One
+          #   `HttpClient` is bound to one `host`, so `HTTP::StateError` (raised only on a
+          #   cross-origin request against a persistent client) cannot occur here.
           # @return [HTTP] HTTP object.
           def base_request
             @base_request ||=
@@ -70,9 +183,10 @@ module Ecoportal
                 HTTP.headers('Authorization' => "Bearer #{session_token(host: host)}")
               end.then do |request|
                 request ||= HTTP
-                request.accept(:json).timeout(
-                  read:  READ_TIMEOUT,
-                  write: WRITE_TIMEOUT
+                request.persistent(base_url, timeout: KEEP_ALIVE_TIMEOUT).accept(:json).timeout(
+                  connect: CONNECT_TIMEOUT,
+                  read:    READ_TIMEOUT,
+                  write:   WRITE_TIMEOUT
                 )
               end
           end
@@ -184,7 +298,9 @@ module Ecoportal
 
             parsed = response.body
             errors = parsed && parsed['errors']
-            raise ResponseError, errors.map { |e| e['message'] }.join('; ') if errors&.any?
+            # Pass the raw entries through: `extensions` (and therefore the failing
+            # policy under `extensions.details`) is the whole point — see Q-27.
+            raise ResponseError.new(errors: errors) if errors&.any?
 
             parsed
           end

data/lib/ecoportal/api/common/graphql/model/as_input.rb

@@ -1,54 +1,54 @@
-module Ecoportal
-  module API
-    module Common
-      module GraphQL
-        class Model
-          # @todo
-          #   1. `#as_input` vs `#to_input` **or** named argument `klass`
-          #     One gets the `input` to be already used in a mutation query.
-          #     The other gets the `Input` class object out of the `Base/Model`.
-          #     - To figure out when `as_update` should be called.
-          #   2. Each Base/Model should have its `Input` class counterpart.
-          #     This could be auto-inflected (via namespace constant lookup)
-          #     at some point.
-          #   3. Think if a service class can be used to this purpose
-          #     (i.e. decorator of DiffService).
-          module AsInput
-            class << self
-              def included(base)
-                super
-
-                base.send(:include, Model::Diffable)
-                base.extend ClassMethods
-              end
-            end
-
-            module ClassMethods
-              def as_input(hash, clientMutationId: '')
-                hash_input = Ecoportal::API::Common::GraphQL::HashHelpers.
-                  keys_to_sym_deep(hash)
-
-                hash_input.merge!(clientMutationId: clientMutationId)
-
-                Ecoportal::API::Common::GraphQL::HashHelpers.
-                  remove_nil_keys_deep(hash_input, target: :id)
-              end
-            end
-
-            # INSTANCE METHODS
-
-            def as_input(target_class: nil, clientMutationId: '')
-              return target_class.from_model(self, client_mutation_id: clientMutationId) if target_class
-
-              diff = as_update
-              return nil if diff.nil?
-
-              diff[:patchVer] = patchVer if respond_to?(:patchVer) && !patchVer.nil?
-              self.class.as_input(diff, clientMutationId: clientMutationId)
-            end
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    module Common
+      module GraphQL
+        class Model
+          # @todo
+          #   1. `#as_input` vs `#to_input` **or** named argument `klass`
+          #     One gets the `input` to be already used in a mutation query.
+          #     The other gets the `Input` class object out of the `Base/Model`.
+          #     - To figure out when `as_update` should be called.
+          #   2. Each Base/Model should have its `Input` class counterpart.
+          #     This could be auto-inflected (via namespace constant lookup)
+          #     at some point.
+          #   3. Think if a service class can be used to this purpose
+          #     (i.e. decorator of DiffService).
+          module AsInput
+            class << self
+              def included(base)
+                super
+
+                base.send(:include, Model::Diffable)
+                base.extend ClassMethods
+              end
+            end
+
+            module ClassMethods
+              def as_input(hash, clientMutationId: '')
+                hash_input = Ecoportal::API::Common::GraphQL::HashHelpers.
+                  keys_to_sym_deep(hash)
+
+                hash_input.merge!(clientMutationId: clientMutationId)
+
+                Ecoportal::API::Common::GraphQL::HashHelpers.
+                  remove_nil_keys_deep(hash_input, target: :id)
+              end
+            end
+
+            # INSTANCE METHODS
+
+            def as_input(target_class: nil, clientMutationId: '')
+              return target_class.from_model(self, client_mutation_id: clientMutationId) if target_class
+
+              diff = as_update
+              return nil if diff.nil?
+
+              diff[:patchVer] = patchVer if respond_to?(:patchVer) && !patchVer.nil?
+              self.class.as_input(diff, clientMutationId: clientMutationId)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/common/graphql/model/diffable/classic_diff_service.rb

@@ -1,49 +1,49 @@
-module Ecoportal::API::Common::GraphQL::Model::Diffable
-  class ClassicDiffService
-    include Ecoportal::API::Common::GraphQL::Model::Diffable::HashDiffNesting
-
-    attr_reader :subject
-
-    def initialize(subject, ignore: [])
-      msg  = 'Expecting Ecoportal::API::Common::Content::DoubleModel. '
-      msg << "Given: #{subject.class}"
-      raise ArgumentError, msg unless subject.is_a?(Ecoportal::API::Common::Content::DoubleModel)
-
-      @subject  = subject
-      @ignored  = to_a(ignore)
-    end
-
-    def diff(ignore: [])
-      classic_diff(ignore: ignore)
-    end
-
-    protected
-
-    def classic_diff(ignore: [])
-      change_diff(
-        curr_doc,
-        prev_doc,
-        ignore: to_a(ignored, ignore)
-      )
-    end
-
-    private
-
-    attr_reader :ignored
-
-    def curr_doc(target = subject)
-      return target.as_json if target.respond_to?(:as_json)
-      return target.doc     if target.respond_to?(:doc)
-
-      raise "Can't fetch underlying document for instance of #{target.class}."
-    end
-
-    def prev_doc(target = subject)
-      return target.original_doc if target.respond_to?(:original_doc)
-
-      raise "Can't fetch original underlying model for instance of #{target.class}."
-    rescue NoMethodError
-      nil
-    end
-  end
-end
+module Ecoportal::API::Common::GraphQL::Model::Diffable
+  class ClassicDiffService
+    include Ecoportal::API::Common::GraphQL::Model::Diffable::HashDiffNesting
+
+    attr_reader :subject
+
+    def initialize(subject, ignore: [])
+      msg  = 'Expecting Ecoportal::API::Common::Content::DoubleModel. '
+      msg << "Given: #{subject.class}"
+      raise ArgumentError, msg unless subject.is_a?(Ecoportal::API::Common::Content::DoubleModel)
+
+      @subject  = subject
+      @ignored  = to_a(ignore)
+    end
+
+    def diff(ignore: [])
+      classic_diff(ignore: ignore)
+    end
+
+    protected
+
+    def classic_diff(ignore: [])
+      change_diff(
+        curr_doc,
+        prev_doc,
+        ignore: to_a(ignored, ignore)
+      )
+    end
+
+    private
+
+    attr_reader :ignored
+
+    def curr_doc(target = subject)
+      return target.as_json if target.respond_to?(:as_json)
+      return target.doc     if target.respond_to?(:doc)
+
+      raise "Can't fetch underlying document for instance of #{target.class}."
+    end
+
+    def prev_doc(target = subject)
+      return target.original_doc if target.respond_to?(:original_doc)
+
+      raise "Can't fetch original underlying model for instance of #{target.class}."
+    rescue NoMethodError
+      nil
+    end
+  end
+end