graph_weaver 0.6.1 → 0.7.1

data/lib/graph_weaver/errors.rb

@@ -5,6 +5,8 @@ require "sorbet-runtime"
 require "time" # Time.httpdate, for Retry-After
 
 require_relative "inflect"
+require_relative "internal/endpoint"
+require_relative "internal/headers"
 require_relative "logging"
 
 module GraphWeaver
@@ -13,8 +15,8 @@ module GraphWeaver
   # a JSON-ready Hash (string keys) for logging, agents, or surfacing
   # structured failures to users. One subclass per failure site —
   # {TransportError} (no response came back), {ServerError} (non-2xx),
-  # {QueryError} (GraphQL-level errors), {TypeError} (response wouldn't
-  # cast), {InputError} (bad variables), {ValidationError} (build time),
+  # {QueryError} (GraphQL-level errors), {CastError} (response wouldn't
+  # cast), {InputError} (bad variables), {QueryValidationError} (build time),
   # {ConfigurationError} (setup judged against your schema) — each merging
   # its specifics into #to_h.
   class Error < StandardError
@@ -25,9 +27,15 @@ module GraphWeaver
     sig { params(args: T.untyped).void }
     def initialize(*args)
       super
-      GraphWeaver::Internal::Log.log(:warn) { "#{self.class.name}: #{message}" }
+      GraphWeaver::Internal::Log.log(:warn) { "#{self.class.name}: #{message}" } if raised?
     end
 
+    # Every error here is raised where it is built — except an InputError read
+    # back off a response, which is a value. A warn line there would claim a
+    # raise that never happened.
+    sig { overridable.returns(T::Boolean) }
+    private def raised? = true
+
     sig { overridable.returns(T::Hash[String, T.untyped]) }
     def to_h
       { "error" => self.class.name, "message" => message }
@@ -42,9 +50,23 @@ module GraphWeaver
   class TransportError < Error
     extend T::Sig
 
+    # The endpoint the request never reached, as it is safe to say — userinfo
+    # and secret query parameters folded out (see Internal::Endpoint). nil
+    # when there is no endpoint: a `Testing::Failure` client, a fake.
+    sig { returns(T.nilable(String)) }
+    attr_reader :url
+
+    sig { params(message: T.untyped, url: T.nilable(String)).void }
+    def initialize(message = nil, url: nil)
+      @url = url
+      super("#{message}#{" — POST #{url}" if url}")
+    end
+
     sig { override.returns(T::Hash[String, T.untyped]) }
     def to_h
-      super.merge("cause" => cause&.class&.name)
+      # url only when there is one — a fake client has no endpoint, and a key
+      # spelled nil reads as "we lost it"
+      super.merge("cause" => cause&.class&.name).merge({ "url" => url }.compact)
     end
   end
 
@@ -90,19 +112,40 @@ module GraphWeaver
     sig { returns(T.untyped) }
     attr_reader :body
 
-    # The response headers, names downcased — the rate-limit budget
-    # (x-ratelimit-remaining), the request id your provider wants in a
-    # support ticket, Retry-After. Empty when the transport had none.
+    # The response headers — the rate-limit budget (x-ratelimit-remaining),
+    # the request id your provider wants in a support ticket, Retry-After.
+    # Looked up in any casing, iterated downcased. Empty when the transport
+    # had none.
     sig { returns(T::Hash[String, String]) }
     attr_reader :headers
 
-    sig { params(status: Integer, body: T.untyped, headers: T::Hash[String, String]).void }
-    def initialize(status:, body: nil, headers: {})
+    # The endpoint that answered, as it is safe to say — userinfo and secret
+    # query parameters folded out (see Internal::Endpoint). nil when there is
+    # no endpoint: an in-process schema, a `Testing::Failure` client.
+    sig { returns(T.nilable(String)) }
+    attr_reader :url
+
+    sig do
+      params(
+        status: Integer,
+        body: T.untyped,
+        headers: T::Hash[String, String],
+        url: T.nilable(String),
+        detail: T.nilable(String),
+      ).void
+    end
+    def initialize(status:, body: nil, headers: {}, url: nil, detail: nil)
       @status = status
       @body = body
-      @headers = headers
-      snippet = body.to_s.empty? ? "" : ": #{body.to_s[0, 500]}"
-      super("HTTP #{status}#{snippet}#{" — #{hint}" if hint}")
+      @url = url
+      @headers = T.let(GraphWeaver::Internal::Headers.wrap(headers), T::Hash[String, String])
+      # A message never carries a body. `detail` is what WE say went wrong; the
+      # bytes the server sent stay on #body, the way #to_h already keeps the
+      # headers off — an error page that echoes the request (Rails' own dev
+      # page, many proxies) carries the caller's variables and our own
+      # Authorization header, and every raised error writes its message to the
+      # log at warn.
+      super("HTTP #{status}#{" — #{detail}" if detail}#{" — #{hint}" if hint}#{" — POST #{url}" if url}")
     end
 
     # What to do about this status, where the status says it. A redirect is
@@ -114,26 +157,22 @@ module GraphWeaver
     sig { returns(T.nilable(String)) }
     def hint
       if REDIRECTS.include?(status)
+        # the destination is a url the SERVER chose — said the way we say our
+        # own, and without the framing a header value could smuggle in
         location = headers["location"]
+        location &&= GraphWeaver::Internal::Redact.tag(GraphWeaver::Internal::Endpoint.safe(location))
         "redirects are not followed#{" — point the client at #{location}" if location}"
       elsif [401, 403].include?(status)
         "the server rejected the credentials — check auth: (the token, and its scopes)"
       end
     end
 
-    # Seconds to wait per the server's Retry-After, which is either a
-    # delay in seconds or an HTTP-date. nil when absent or unparseable;
-    # negative dates (already past) clamp to 0. See RFC 9110 §10.2.3.
+    # Seconds to wait per the server's Retry-After, or nil. Parsed off the
+    # headers, which is also where a returned envelope reads it — so one rule
+    # answers a rate limit however it arrived.
     sig { returns(T.nilable(Float)) }
     def retry_after
-      value = headers["retry-after"]&.strip
-      return if value.nil? || value.empty?
-      return value.to_f if value.match?(/\A\d+(\.\d+)?\z/)
-
-      seconds = Time.httpdate(value) - Time.now
-      [seconds, 0.0].max
-    rescue ArgumentError
-      nil
+      GraphWeaver::Internal::Headers.wrap(headers).retry_after
     end
 
     # True when the server said "you're going too fast" — 429, or the
@@ -148,7 +187,7 @@ module GraphWeaver
     def to_h
       # the raw headers stay off the machine side — Set-Cookie and
       # friends don't belong in a log line; read #headers for those
-      super.merge("status" => status, "retry_after" => retry_after).compact
+      super.merge("status" => status, "retry_after" => retry_after, "url" => url).compact
     end
   end
 
@@ -247,10 +286,14 @@ module GraphWeaver
 
     # The codes servers use to say "you're going too fast". No standard
     # exists, so this is the union of what the big graphs actually send:
-    # Shopify THROTTLED, GitHub RATE_LIMITED, Apollo/Hasura the rest.
+    # Shopify THROTTLED, GitHub RATE_LIMITED, Apollo Router
+    # REQUEST_RATE_LIMITED (measured against v2.17.0), Hasura the rest.
     # Pass it to Retry (retry_codes:) rather than hand-writing strings.
     THROTTLE_CODES = T.let(
-      %w[THROTTLED RATE_LIMITED RATE_LIMIT_EXCEEDED TOO_MANY_REQUESTS REQUEST_LIMIT_EXCEEDED].freeze,
+      %w[
+        THROTTLED RATE_LIMITED RATE_LIMIT_EXCEEDED TOO_MANY_REQUESTS
+        REQUEST_LIMIT_EXCEEDED REQUEST_RATE_LIMITED
+      ].freeze,
       T::Array[String],
     )
 
@@ -262,6 +305,31 @@ module GraphWeaver
       THROTTLE_CODES.include?(code)
     end
 
+    # Codes that say "this error is about the input you sent", and what each
+    # one means. `BAD_USER_INPUT` is the ecosystem's coarse bucket (Apollo's,
+    # and what docs/errors.md asks a server to stamp); the rest are
+    # graphql-ruby's own rule names, measured against 2.6.10. Nothing else is
+    # claimed: a `validates:` failure reaches the wire as a bare sentence
+    # with no extensions at all, indistinguishable from "the database is
+    # down", and attaching that to a form field is worse than missing it.
+    INPUT_CODES = T.let({
+      "BAD_USER_INPUT" => :refused,
+      "argumentLiteralsIncompatible" => :type_mismatch,
+      "variableMismatch" => :type_mismatch,
+      "missingRequiredInputObjectAttribute" => :missing,
+      "argumentNotAccepted" => :unknown,
+    }.freeze, T::Hash[String, Symbol])
+
+    # This error as input problems — [] when it isn't about the input at all.
+    # Plural because one variable-coercion error genuinely carries N of them,
+    # and dropping all but the first is the quiet loss this library refuses.
+    # See docs/errors.md ("What your server can send") for the three shapes
+    # read here, and docs/i18n.md for the vocabulary.
+    sig { returns(T::Array[InputError]) }
+    def input_errors
+      @input_errors ||= T.let(GraphWeaver::Internal::ServerInput.read(self), T.nilable(T::Array[InputError]))
+    end
+
     # The field the error points at, as a stable dotted path with list
     # indices stripped — ["people", 3, "email"] => "people.email". The
     # parseable key for grouping/reporting (the raw #path keeps indices).
@@ -349,6 +417,20 @@ module GraphWeaver
       errors.any?(&:throttled?)
     end
 
+    # Every error here that is about the input we sent, as InputError values
+    # — the same object a client-side refusal raises, so one renderer serves
+    # both halves. [] when the server rejected nothing about the input, or
+    # said nothing that identifies it as input (see GraphQLError::INPUT_CODES).
+    #
+    # #field is nil where the server stated no input path, so a form needs
+    # the :base branch:
+    #
+    #      response.input_errors.each { |e| form.errors.add(e.field&.underscore || :base, e.message) }
+    sig { returns(T::Array[InputError]) }
+    def input_errors
+      errors.flat_map(&:input_errors)
+    end
+
     # Errors grouped by the field they point at (index-stripped dotted
     # path; nil key for global errors) — iterate with each_error:
     #
@@ -383,13 +465,34 @@ module GraphWeaver
         node = if segment.is_a?(Integer) || segment.to_s.match?(/\A\d+\z/)
           node.is_a?(Array) ? node[segment.to_i] : nil
         else
-          prop = GraphWeaver::Inflect.underscore(segment.to_s).to_sym
-          node.respond_to?(prop) ? node.public_send(prop) : nil
+          field_value(node, segment)
         end
         return if node.nil?
       end
 
-      node.respond_to?(:id) ? node.id : nil
+      field_value(node, "id")
+    end
+
+    # The value of the field a path segment names, or nil when this struct
+    # hasn't got one. Read off the struct's own props, never `respond_to?` —
+    # the path comes from the SERVER, and every Object method answers that:
+    # a segment named `freeze` froze the caller's result and then reported an
+    # id for a field that doesn't exist, `display` printed the struct to
+    # stdout, and `tap`/`send`/`method` raised out of error handling.
+    #
+    # Two candidates, because a prop that would shadow a method the struct
+    # answers is emitted with a trailing underscore (`class` -> `class_`).
+    # Asking the struct rather than re-deriving the emitter's reserved list
+    # also survives the skew: a file generated by an older version was
+    # renamed by that version's list, not this one's.
+    sig { params(node: T.untyped, segment: T.untyped).returns(T.untyped) }
+    private def field_value(node, segment)
+      props = node.class.props if node.class.respond_to?(:props)
+      return unless props.is_a?(Hash)
+
+      name = GraphWeaver::Inflect.underscore(segment.to_s)
+      prop = [name.to_sym, :"#{name}_"].find { |candidate| props.key?(candidate) }
+      node.public_send(prop) if prop
     end
 
     # The user-facing rollup: errors keyed by field, with the ids of the
@@ -486,7 +589,7 @@ module GraphWeaver
   # unknown enum value). #struct names the generated type that failed;
   # #cause carries the original TypeError/KeyError with the offending
   # prop in its message.
-  class TypeError < Error
+  class CastError < Error
     extend T::Sig
 
     sig { returns(T.untyped) }
@@ -510,18 +613,74 @@ module GraphWeaver
     end
   end
 
-  # Raised when the variables passed to a query or mutation can't be built
-  # into the generated input structs — an unknown or typo'd input key, a
-  # missing required input field, an out-of-range enum, or a wrong-typed
-  # field. This is the "the caller's input was invalid" error: rescue it at
-  # an API boundary to return a 422. #field names the offending input field
-  # when known, #struct the input type being built; the underlying
-  # TypeError/KeyError/ArgumentError is preserved as #cause.
+  # The caller's input was invalid — an unknown or typo'd input key, a
+  # missing required input field, an out-of-range enum, a wrong-typed field.
+  # Raised before the request leaves, so rescue it at an API boundary to
+  # return a 422; it is ALSO the value a server's rejection becomes
+  # (GraphQLError#input_errors, Response#input_errors), because "which input
+  # was wrong, and how" is one question whichever side answered it.
+  #
+  # The machine side is #kind (one of KINDS), #path (rooted at the variable),
+  # #coordinate (the schema's name for the slot), #value and #details — see
+  # docs/i18n.md for translating them. #message is the developer's English
+  # line and is not API. The underlying TypeError/KeyError/ArgumentError is
+  # preserved as #cause.
   class InputError < Error
     extend T::Sig
 
+    # The closed vocabulary #kind draws from — one key an app can translate,
+    # rather than a sentence it has to parse. Additive only: a new kind
+    # arrives in a MINOR release and :refused is the honest home for
+    # everything that fits none of them. docs/i18n.md has what each means.
+    KINDS = T.let(
+      %i[type_mismatch unparseable not_a_member missing unknown out_of_range invalid_format refused].to_set.freeze,
+      T::Set[Symbol],
+    )
+
+    # The detail keys a kind may carry. Closed, so `I18n.t(..., **details)`
+    # never gets a key the app's locale file has no slot for — and so a
+    # server can't smuggle arbitrary data in under extensions.input. None of
+    # them may be an I18n::RESERVED_KEYS name (`:format` was, which raised
+    # I18n::ReservedInterpolationKey on that very splat) — held by a spec.
+    DETAILS = T.let(%i[type members min max pattern suggestion].freeze, T::Array[Symbol])
+
+    # The most of any one value this error will hold or spell — per String, at
+    # every depth, and per sentence a server wrote. Past it the rest is
+    # dropped for "…(N more bytes)". An InputError is built for whatever a
+    # caller sent and whatever a server echoed back, either of which can be
+    # megabytes, and every raised one writes a warn line as well as landing in
+    # #to_h. A kilobyte is far more than a diagnosis needs and far less than a
+    # log line can't take.
+    VALUE_LIMIT = 1024
+
+    sig { returns(Symbol) }
+    attr_reader :kind
+
+    # Rooted at the variable and down through input fields and list indices:
+    # ["where", "_and", 0, "_not", "species"]. Every named segment is the
+    # SCHEMA's spelling, whichever side refused — a server can produce no
+    # other, so one rule covers both halves. Empty when nothing named a slot.
+    # #field is its last named segment — the one a form highlights.
+    sig { returns(T::Array[T.untyped]) }
+    attr_reader :path
+
+    # The GraphQL schema coordinate for the slot — "PetFilter.species". nil
+    # where there isn't one: a variable ($count names no schema element), a
+    # key the input type doesn't define, or a server that didn't say.
     sig { returns(T.nilable(String)) }
-    attr_reader :field
+    attr_reader :coordinate
+
+    # The rejected value, through filter_parameters exactly as the message
+    # is. nil where it was never known (a missing field has no value, and an
+    # unknown key owns no slot to hold one). Always JSON-representable — see
+    # json_safe.
+    sig { returns(T.untyped) }
+    attr_reader :value
+
+    # Kind-specific facts, never pre-formatted: members stays an Array,
+    # because joining it is a language decision. Keys are drawn from DETAILS.
+    sig { returns(T::Hash[Symbol, T.untyped]) }
+    attr_reader :details
 
     # The generated input struct class where generation produced one, and
     # the GraphQL type name where it didn't — a federation representation
@@ -530,18 +689,93 @@ module GraphWeaver
     sig { returns(T.untyped) }
     attr_reader :struct
 
-    sig { params(message: String, field: T.nilable(String), struct: T.untyped).void }
-    def initialize(message, field: nil, struct: nil)
-      @field = field
+    sig do
+      params(
+        message: String,
+        kind: Symbol,
+        path: T::Array[T.untyped],
+        coordinate: T.nilable(String),
+        value: T.untyped,
+        details: T::Hash[Symbol, T.untyped],
+        struct: T.untyped,
+        raised: T::Boolean,
+      ).void
+    end
+    def initialize(message, kind: :refused, path: [], coordinate: nil, value: nil,
+      details: {}, struct: nil, raised: true)
+      unless KINDS.include?(kind)
+        raise ArgumentError, "kind: #{kind.inspect} is not an input kind — one of #{KINDS.to_a.join(", ")}"
+      end
+
+      @kind = kind
+      @path = T.let(path.dup, T::Array[T.untyped])
+      @coordinate = coordinate
+      @value = T.let(json_safe(value), T.untyped)
+      @details = T.let(json_safe(details), T::Hash[Symbol, T.untyped])
       @struct = struct
-      # the message often IS a sorbet prop error — drop its frame, as TypeError does
-      super(message.sub(TypeError::SORBET_CALLER, ""))
+      @raised = raised
+      # the message often IS a sorbet prop error — drop its frame, as CastError does
+      super(message.sub(CastError::SORBET_CALLER, ""))
+    end
+
+    # `render json: e.to_h` is the documented idiom, and JSON has no spelling
+    # for NaN or Infinity — so the crash landed inside the app's error handler,
+    # losing the diagnosis and turning a 422 into a 500. The values that get
+    # there are precisely the ones Coerce.finite/whole exist to refuse, plus
+    # whatever a lenient parser read off a response, so a non-finite Float
+    # travels as its to_s and everything else passes through untouched.
+    sig { params(value: T.untyped).returns(T.untyped) }
+    private def json_safe(value)
+      case value
+      when Float then value.finite? ? value : value.to_s
+      when String then GraphWeaver::Internal::Redact.cap(value)
+      when Array then value.map { |element| json_safe(element) }
+      when Hash then value.transform_values { |element| json_safe(element) }
+      else value
+      end
+    end
+
+    # The input field the value actually landed on — #path's last *named*
+    # segment, which is the coordinate a form can act on. A trailing list
+    # index is a position rather than a field, so `["ids", 2]` is still the
+    # `ids` field. nil when nothing named a slot.
+    sig { returns(T.nilable(String)) }
+    def field = T.cast(path.reverse.find { |segment| segment.is_a?(String) }, T.nilable(String))
+
+    # The same refusal one level out: prepend the segment that led here.
+    # Every enclosing layer — a list index, an input field, the variable —
+    # adds its own on the way out, so the innermost refusal (which wrote the
+    # message) ends up holding the whole route. Mutates and returns self:
+    # the failure happened once, and a fresh error per layer would write a
+    # warn line per layer for it.
+    #
+    # `prop:` is the same field in Ruby spelling, where it differs: the
+    # segment is the schema's name, but filter_parameters is a list the app
+    # writes in Ruby, so `api_key` must still match what `apiKey` holds.
+    sig { params(segment: T.any(String, Integer), prop: T.any(String, Integer, Symbol)).returns(InputError) }
+    def within(segment, prop: segment)
+      @path.unshift(segment)
+      # a list element has no key of its own — the list's key is the first it
+      # meets, and it decides whether the value may be shown
+      @value = GraphWeaver::Internal::Redact.value(prop, @value) if segment.is_a?(String)
+      self
     end
 
     sig { override.returns(T::Hash[String, T.untyped]) }
     def to_h
-      super.merge("field" => field, "struct" => struct&.to_s).compact
+      super.merge(
+        "kind" => kind.to_s,
+        "path" => path,
+        "coordinate" => coordinate,
+        "field" => field,
+        "value" => value,
+        "details" => details.transform_keys(&:to_s),
+        "struct" => struct&.to_s,
+      ).compact
     end
+
+    sig { override.returns(T::Boolean) }
+    private def raised? = @raised
   end
 
   # The setup doesn't add up — judged against your schema, not against the
@@ -557,7 +791,7 @@ module GraphWeaver
   # structured validation errors (message + line/column) rather than a
   # joined string. Under the Error umbrella like everything else raised
   # here (through 0.1.0 it was an ArgumentError instead).
-  class ValidationError < Error
+  class QueryValidationError < Error
     extend T::Sig
 
     sig { returns(T::Array[T::Hash[Symbol, T.untyped]]) }
@@ -595,7 +829,7 @@ module GraphWeaver
     # line — thirty typos on one joined line is a wall nobody reads.
     sig { params(errors: T::Array[T::Hash[Symbol, T.untyped]]).returns(String) }
     def render(errors)
-      entries = errors.map { |error| ValidationError.split(error) }
+      entries = errors.map { |error| QueryValidationError.split(error) }
       paths = entries.map(&:first).compact.uniq
       hoisted = paths.one?
 
@@ -607,3 +841,7 @@ module GraphWeaver
     end
   end
 end
+
+# reads a server rejection back into InputError values (GraphQLError#input_errors);
+# below the classes, since it needs both of them defined
+require_relative "internal/server_input"