graph_weaver 0.6.0 → 0.7.0

data/lib/graph_weaver/hints.rb

@@ -27,19 +27,25 @@ module GraphWeaver
       unknown = hash.keys.map(&:to_s) - known
       return if unknown.empty?
 
-      hints = unknown.map do |key|
-        prop = GraphWeaver::Inflect.underscore(key)
-        suggestion = if known.include?(prop)
-          prop # a wire-cased key — the exact snake_case prop exists
-        else
-          GraphWeaver::Internal::Util.did_you_mean(known, prop)
-        end
-        suggestion ? "#{key} (did you mean '#{suggestion}'?)" : key
+      suggestions = unknown.to_h do |key|
+        prop = GraphWeaver::Codegen.prop_name(key)
+        # a wire-cased key — the exact snake_case prop exists
+        [key, known.include?(prop) ? prop : GraphWeaver::Internal::Util.did_you_mean(known, prop)]
       end
+      hints = suggestions.map { |key, s| s ? "#{key} (did you mean '#{s}'?)" : key }
+
+      # the message lists every unknown key; #path names the first, because a
+      # path that points at two fields points at neither. No coordinate: the
+      # input type defines no such field, so the schema has no name for it.
+      # No value either — and not only because the key owns no slot to hold
+      # one: filter_parameters can only match the key the caller supplied, and
+      # a typo is by definition not the key they meant, so `passwrod` dodges
+      # the `password` filter in the one error that names it as the suggestion.
+      first = unknown.first
       raise GraphWeaver::InputError.new(
         "unknown key(s) for #{struct}: #{hints.join(", ")}",
-        field: unknown.join(", "),
-        struct: struct,
+        kind: :unknown, path: [first],
+        details: { suggestion: suggestions[first] }.compact, struct: struct,
       )
     end
 
@@ -54,7 +60,7 @@ module GraphWeaver
     rescue GraphWeaver::Error
       raise # a nested struct already named its own field
     rescue StandardError => e
-      raise GraphWeaver::TypeError.new(struct:, message: "#{key}: #{e.message}")
+      raise GraphWeaver::CastError.new(struct:, message: "#{key}: #{e.message}")
     end
 
     # A wire value the generated enum doesn't have — the response-side twin
@@ -73,7 +79,7 @@ module GraphWeaver
     end
 
     def self.drifted!(type, value, values)
-      raise KeyError, "#{value.inspect} is not a #{type} — expected one of: " \
+      raise KeyError, "#{GraphWeaver::Internal::Redact.shown(value)} is not a #{type} — expected one of: " \
         "#{values.sort.join(", ")}; a value the server added since you generated " \
         "needs a regenerate, or register_enum fallback: to absorb them"
     end
@@ -84,7 +90,13 @@ module GraphWeaver
     # its raw integer primary key is the case that keeps happening — so
     # say that GraphQL requires the quotes, and how to take it anyway.
     def self.cast_message(struct, data, error)
-      message = error.message.sub(GraphWeaver::TypeError::SORBET_CALLER, "")
+      # Shape drift first, because sorbet's account of it is wrong: see
+      # drifted_shape. Otherwise sorbet's message is the better one — it names
+      # the prop and the value.
+      drift = drifted_shape(struct, data)
+      return drift if drift
+
+      message = error.message.sub(GraphWeaver::CastError::SORBET_CALLER, "")
       keys = unquoted_keys(struct, data)
       return message if keys.empty?
 
@@ -93,6 +105,67 @@ module GraphWeaver
         'register the scalar loosely: GraphWeaver.register_scalar("ID", "T.untyped")'
     end
 
+    # A response value whose SHAPE its prop can never hold — an object where a
+    # list belongs, a scalar inside a list of objects. sorbet catches these in
+    # the CALLER's frame, since it is the child's `data` parameter that fails:
+    # the parent brands the error, so the struct named is the parent and the
+    # key is named nowhere. Worse, a parent mapping over an object has already
+    # let Hash#map turn it into [key, value] pairs, so sorbet reports a list of
+    # strings the server never sent.
+    #
+    # Returns the located message, or nil when nothing is out of shape.
+    def self.drifted_shape(struct, data)
+      return unless data.is_a?(Hash) && struct.respond_to?(:props)
+
+      props = struct.props
+      data.filter_map do |key, value|
+        prop = props[GraphWeaver::Codegen.prop_name(key.to_s).to_sym]
+        # :type_object keeps the nilable-ness :type strips — a null where the
+        # schema allows one is not drift, and must not be blamed for a sibling's
+        prop && shape_drift(T::Utils.coerce(prop[:type_object]), value, key.to_s)
+      end.first
+    end
+    private_class_method :drifted_shape
+
+    # Only the two shapes a server can get wrong are modelled: a nested struct
+    # arrives as an object, a list of them as a list. A scalar prop says
+    # nothing here — one that casts already names itself through Hints.field,
+    # and T.untyped holds anything.
+    def self.shape_drift(type, value, path)
+      return if value.nil? && type.valid?(nil)
+
+      core = type.is_a?(T::Types::Union) ? type.types.find { |t| !t.valid?(nil) } : type
+      want =
+        if core.is_a?(T::Types::TypedArray) then :list
+        elsif core.is_a?(T::Types::Simple) && core.raw_type < T::Struct then :object
+        end
+      return if want.nil?
+
+      unless want == :list ? value.is_a?(Array) : value.is_a?(Hash)
+        return "#{path}: expected #{want == :list ? "a list" : "an object"}, " \
+          "but the server sent #{wire_kind(value)}"
+      end
+      return unless want == :list
+
+      value.each_with_index.filter_map { |element, i| shape_drift(core.type, element, "#{path}.#{i}") }.first
+    end
+    private_class_method :shape_drift
+
+    # What arrived, named as JSON names it. sorbet reports the Ruby type of
+    # whatever the cast had half-built by then, which is a different thing.
+    def self.wire_kind(value)
+      case value
+      when nil then "null"
+      when Hash then "an object"
+      when Array then "a list"
+      when String then "a string"
+      when Numeric then "a number"
+      when true, false then "a boolean"
+      else "a #{value.class}"
+      end
+    end
+    private_class_method :wire_kind
+
     # Response keys whose prop would take a String but whose value is
     # another JSON scalar. Narrow on purpose: a prop that casts (a Date, an
     # enum) legitimately arrives as some other type, so only the
@@ -104,7 +177,7 @@ module GraphWeaver
       data.filter_map do |key, value|
         next unless value.is_a?(Numeric) || value == true || value == false
 
-        prop = props[GraphWeaver::Inflect.underscore(key.to_s).to_sym]
+        prop = props[GraphWeaver::Codegen.prop_name(key.to_s).to_sym]
         next unless prop
 
         # :type is a raw Class for a bare-class prop, a T::Types::Base otherwise
@@ -114,26 +187,29 @@ module GraphWeaver
     end
     private_class_method :unquoted_keys
 
+    # No matching respond_to_missing?. The hint is an answer about a call that
+    # was actually made; respond_to? is a question about the object's shape,
+    # and a near miss is not a method this struct has. Answering true broke the
+    # standard guard — `obj.pet if obj.respond_to?(:pet)` raised on the very
+    # typo the hint exists for — which costs more than `#method(:nmae)` raising
+    # Ruby's own bare NameError.
+    # Kernel.raise, not bare raise: this module is mixed into every generated
+    # struct, so a prop named `raise` would shadow it with a zero-arity reader.
+    # Codegen reserves the name; qualifying it here needs no such rule to hold.
     def method_missing(name, *args, &block)
       if args.empty? && (hint = prop_hint(name.to_s))
-        raise NoMethodError, "undefined method '#{name}' for #{self.class} — #{hint}"
+        Kernel.raise NoMethodError, "undefined method '#{name}' for #{self.class} — #{hint}"
       end
 
       super
     end
 
-    # keeps #method and #respond_to? agreeing with method_missing — without
-    # it `struct.method(:nmae)` raises a bare NameError while `struct.nmae`
-    # gets the hint
-    def respond_to_missing?(name, include_private = false)
-      !!prop_hint(name.to_s) || super
-    end
-
     private
 
     def prop_hint(name)
-      prop = GraphWeaver::Inflect.underscore(name)
-      # method_defined?, not respond_to? — respond_to_missing? lands back here
+      prop = GraphWeaver::Codegen.prop_name(name)
+      # method_defined? rather than respond_to?, which a host's own
+      # respond_to_missing? could answer for a method it doesn't define
       if prop != name && T.unsafe(self.class).method_defined?(prop)
         return "GraphQL fields generate snake_case props; use '#{prop}'"
       end

data/lib/graph_weaver/in_process.rb

@@ -36,6 +36,10 @@ class GraphWeaver::InProcess
   # the schema queries run against, and the context handed to every one
   attr_reader :schema, :context
 
+  # settable so Testing::Endpoint can answer a `context:` proc from the
+  # request's headers and put it back — the same seam Router#context= is
+  attr_writer :context
+
   def initialize(schema, context: {})
     unless schema.respond_to?(:execute)
       raise ArgumentError, "expected a graphql-ruby schema class, got #{schema.inspect}"
@@ -47,35 +51,32 @@ class GraphWeaver::InProcess
 
   def execute(query, variables: {}, operation_name: nil)
     operation_name ||= GraphWeaver::Internal::Wire.operation_name(query)
-    payload = { url: nil, schema: @schema.to_s, operation: operation_name }
+    payload = { url: nil, schema: schema_label, operation: operation_name, client: self.class }
 
     GraphWeaver::Internal::Log.instrument(GraphWeaver::EXECUTE_EVENT, payload) do
-      perform(query, variables, operation_name, payload)
+      perform(query, variables, operation_name)
     end
   end
 
   # The query itself. Separate from execute so the instrumenter wraps a
   # call rather than a block this method returns out of.
-  private def perform(query, variables, operation_name, payload)
+  private def perform(query, variables, operation_name)
     # same tag/truncation as the network transports, so one log reads the
     # same whichever side of the seam a query ran on
     tag = GraphWeaver.logger && GraphWeaver::Internal::Wire.log_tag(operation_name)
 
     GraphWeaver::Internal::Log.log(:debug) do
-      "in-process #{@schema} #{tag} variables=#{JSON.generate(GraphWeaver::Internal::Log.filter_variables(variables))}\n" \
+      "in-process #{schema_label} #{tag} variables=#{GraphWeaver::Internal::Log.variables_for_log(variables)}\n" \
         "#{GraphWeaver::Internal::Wire.truncate_for_log(query)}"
     end
 
-    result = GraphWeaver::Internal::Log.log_timed(:debug, "in-process #{@schema} #{tag} completed") do
+    result = GraphWeaver::Internal::Log.log_timed(:debug, "in-process #{schema_label} #{tag} completed") do
       # a copy per query: graphql-ruby writes a resolver's `context[...] =`
       # into the hash it is handed, and one client serves every request
-      @schema.execute(query, variables:, operation_name:, context: @context.dup)
+      @schema.execute(query, variables:, operation_name:,
+        context: GraphWeaver::Internal::Util.context!(@context).dup)
     end
 
-    # the same key the network transports set, so one instrumenter
-    # subscriber reads both sides of the seam without branching — a
-    # resolver raise rides the ServerError(500) the hook already sees
-    payload[:status] = 200
     result
   rescue GraphWeaver::Error
     raise
@@ -88,6 +89,11 @@ class GraphWeaver::InProcess
 
   # never leak the context (session tokens, current_user) through logs or
   # exceptions — an in-process client inspects as its schema, nothing more
-  def inspect = "#<#{self.class.name} schema=#{@schema}>"
+  def inspect = "#<#{self.class.name} schema=#{schema_label}>"
   alias to_s inspect
+
+  # What to call this schema in a log line or an instrumentation payload. A
+  # schema built from SDL is an anonymous class, whose #to_s is its object
+  # address — a new value every boot, and unbounded cardinality as an APM tag.
+  private def schema_label = @schema.name || "anonymous"
 end

data/lib/graph_weaver/input_struct.rb

@@ -20,8 +20,10 @@ module GraphWeaver
     include Kernel # for sorbet: hosts are T::Structs
 
     # serializer/coercer are code-as-data from the generated file; nil
-    # means identity (the wire value passes through untouched)
-    Field = Data.define(:prop, :wire, :required, :serializer, :coercer)
+    # means identity (the wire value passes through untouched). coordinate
+    # is the schema's name for the slot ("PetFilter.species"), so a refusal
+    # can say where it happened without reflecting at runtime.
+    Field = Data.define(:prop, :wire, :required, :serializer, :coercer, :coordinate)
 
     # An enum reaching the library as input — an execute kwarg or an input
     # field — as the member or its wire value. Generated code calls these
@@ -34,6 +36,26 @@ module GraphWeaver
       type.try_deserialize(value) || invalid_enum!(type, value, type.values.map(&:serialize))
     end
 
+    # A list element's index, prepended when something inside it refused —
+    # `where._and.0._not.species` needs the 0 to name one form field.
+    #
+    # A nested input's coercer raises an InputError that already holds a path;
+    # every LEAF coercer (Coerce.*, .enum) raises a branded plain error instead,
+    # so without the second branch the index was dropped for every list of
+    # leaves — and an element that wasn't a list at all reached the caller as a
+    # raw NoMethodError from the inner `.map`.
+    # `value` is the element itself, so a refused leaf carries what was refused
+    def self.element(index, value = nil)
+      yield
+    rescue GraphWeaver::InputError => e
+      raise e.within(index)
+    rescue StandardError => e
+      raise GraphWeaver::InputError.new(
+        e.message, kind: GraphWeaver::Internal::Refusal.kind_of(e), path: [index], value:,
+        details: GraphWeaver::Internal::Refusal.details_of(e),
+      )
+    end
+
     # the same, for an enum mapped onto an app-owned T::Enum (register_enum),
     # where the wire table rather than the type knows the accepted values
     def self.mapped_enum(type, table, value)
@@ -44,28 +66,44 @@ module GraphWeaver
 
     # Names the input field a coercion refused — a scalar's coercer, an
     # enum's, or a nested input's — since the complaint underneath is about
-    # the value alone. A nested error that already named a field keeps it:
-    # the innermost input is the one that actually held the bad value.
-    def self.field(struct, prop)
+    # the value alone. A nested error that already named a field keeps its
+    # sentence, and only grows a path segment: the innermost input is the one
+    # that actually held the bad value.
+    def self.field(struct, field, raw)
+      prop = field.prop
       yield
     rescue GraphWeaver::InputError => e
-      raise if e.field && !GraphWeaver::Internal::Redact.filtered?(prop)
+      redact = GraphWeaver::Internal::Redact
+      raise e.within(field.wire, prop:) if e.field && !redact.filtered?(prop)
 
       raise GraphWeaver::InputError.new(
-        "#{prop}: #{GraphWeaver::Internal::Redact.detail(prop, e.message)}",
-        field: e.field || prop.to_s, struct: e.struct || struct,
+        "#{prop}: #{redact.detail(prop, e.message)}",
+        kind: e.kind, path: [field.wire, *e.path], coordinate: e.coordinate || field.coordinate,
+        # #value is the value AT #path: this layer owns it only when nothing
+        # inner named a field (so a missing one stays valueless, as it is)
+        value: redact.value(prop, e.path.empty? ? raw : e.value),
+        details: e.details, struct: e.struct || struct,
       )
     rescue StandardError => e
+      redact = GraphWeaver::Internal::Redact
       raise GraphWeaver::InputError.new(
-        "#{prop}: #{GraphWeaver::Internal::Redact.detail(prop, e.message)}", field: prop.to_s, struct:,
+        "#{prop}: #{redact.detail(prop, e.message)}",
+        kind: GraphWeaver::Internal::Refusal.kind_of(e), path: [field.wire],
+        coordinate: field.coordinate, value: redact.value(prop, raw),
+        details: GraphWeaver::Internal::Refusal.details_of(e), struct:,
       )
     end
 
     # Raised bare, like Hints.drifted!: the enclosing .field or Coerce.variable
     # knows the key, and so is the only layer that can decide whether this
-    # value may be named.
+    # value may be named. The verdict rides along, since nothing outside here
+    # can tell an out-of-range enum from any other KeyError.
     def self.invalid_enum!(type, value, values)
-      raise KeyError, "#{value.inspect} is not a valid #{type} — expected one of: #{values.sort.join(", ")}"
+      shown = GraphWeaver::Internal::Redact.shown(value)
+      raise GraphWeaver::Internal::Refusal.brand(
+        KeyError.new("#{shown} is not a valid #{type} — expected one of: #{values.sort.join(", ")}"),
+        :not_a_member, members: values.sort,
+      )
     end
     private_class_method :invalid_enum!
 
@@ -87,24 +125,51 @@ module GraphWeaver
         value = public_send(field.prop)
         next if value.nil? && !field.required && !given&.include?(field.prop)
 
-        out[field.wire] = field.serializer && !value.nil? ? field.serializer.call(value) : value
+        out[field.wire] =
+          begin
+            field.serializer && !value.nil? ? field.serializer.call(value) : value
+          rescue GraphWeaver::InputError => e
+            # a nested input's own refusal (@oneOf, a custom serialize:) —
+            # every layer prepends the segment that led to it. Kernel.raise,
+            # since this module is mixed into the struct and a prop named
+            # `raise` would shadow a bare one with a zero-arity reader.
+            Kernel.raise e.within(field.wire, prop: field.prop)
+          end
       end
 
       # @oneOf declares "exactly one of these, and not null", but every field
       # is nullable, so nothing before here can enforce it — not the struct's
       # types, not the server until the round trip
-      if self.class.const_defined?(:ONE_OF, false) && (wire.size != 1 || wire.values.first.nil?)
-        supplied_names = wire.empty? ? "none" : wire.keys.sort.join(", ")
-        raise GraphWeaver::InputError.new(
-          "#{self.class} is @oneOf — supply exactly one field, non-null, got #{supplied_names}",
-          struct: self.class,
-        )
-      end
+      one_of!(wire) if self.class.const_defined?(:ONE_OF, false)
 
       wire
     end
     alias_method :to_h, :serialize
 
+    # Two different mistakes, and "supply exactly one field" is the wrong
+    # sentence for the second: the caller who wrote `{ id: nil }` supplied
+    # exactly one field. That one is a missing value, so it says so and names
+    # the slot — a form has something to highlight, which the count case
+    # (nothing, or several) has no single field to give.
+    private def one_of!(wire)
+      if wire.size == 1 && wire.values.first.nil?
+        name = wire.keys.first
+        field = self.class.const_get(:FIELDS).find { |candidate| candidate.wire == name }
+        Kernel.raise GraphWeaver::InputError.new(
+          "#{self.class} is @oneOf and #{name} was null — supply a value for it, or a different field",
+          kind: :missing, path: [field.wire], coordinate: field.coordinate, struct: self.class,
+        )
+      end
+
+      return if wire.size == 1
+
+      Kernel.raise GraphWeaver::InputError.new(
+        "#{self.class} is @oneOf — supply exactly one field, non-null, got " \
+          "#{wire.empty? ? "none" : wire.keys.sort.join(", ")}",
+        struct: self.class,
+      )
+    end
+
     module ClassMethods
       include Kernel
 
@@ -119,7 +184,12 @@ module GraphWeaver
         # list was expected) is bad input — surface a branded 422, not a raw
         # NoMethodError from validate_keys!'s `.keys`
         unless value.is_a?(Hash)
-          raise GraphWeaver::InputError.new("expected a Hash or #{self}, got #{value.class}", struct: self)
+          # the message names the Ruby you may pass; #details is what an app
+          # translates for a user, so it speaks the schema's vocabulary
+          raise GraphWeaver::InputError.new(
+            "expected a Hash or #{self}, got #{value.class}",
+            kind: :type_mismatch, details: { type: graphql_name }, struct: self,
+          )
         end
 
         # a typo'd key must not silently drop off the wire
@@ -133,17 +203,20 @@ module GraphWeaver
 
           # a coercer is arbitrary Ruby — Coerce.integer, Date.iso8601, a
           # nested .coerce — and its complaint is about the value alone
-          [field.prop, GraphWeaver::InputStruct.field(self, field.prop) { field.coercer.call(raw) }]
+          [field.prop, GraphWeaver::InputStruct.field(self, field, raw) { field.coercer.call(raw) }]
         end
 
         # FIELDS knows which are required, so say what is missing — sorbet's
         # own complaint describes the symptom ("Can't set .name to nil") and
         # names only the first one it reaches
-        missing = fields.select { |field| field.required && supplied[field.prop].nil? }.map(&:prop)
+        missing = fields.select { |field| field.required && supplied[field.prop].nil? }
         unless missing.empty?
+          # the message lists every one; #path names the first, because a
+          # path that points at two fields points at neither
           raise GraphWeaver::InputError.new(
-            "missing required key(s) for #{self}: #{missing.join(", ")}",
-            field: missing.join(", "), struct: self,
+            "missing required key(s) for #{self}: #{missing.map(&:prop).join(", ")}",
+            kind: :missing, path: [missing.first.wire],
+            coordinate: missing.first.coordinate, struct: self,
           )
         end
 
@@ -152,14 +225,19 @@ module GraphWeaver
         raise # already contextualized by a nested input / enum coercion
       rescue ::TypeError, ::ArgumentError, KeyError => e
         # a wrong-typed field, a missing required field, or an out-of-range
-        # enum — surface one branded, structured error for a 422. (`::` so the
-        # rescue catches Ruby's TypeError, not GraphWeaver::TypeError.)
+        # enum — surface one branded, structured error for a 422.
         raise mistyped(supplied) ||
-          GraphWeaver::InputError.new("invalid input for #{self}: #{e.message}", struct: self)
+          GraphWeaver::InputError.new(
+            "invalid input for #{self}: #{e.message}",
+            kind: GraphWeaver::Internal::Refusal.kind_of(e),
+            details: GraphWeaver::Internal::Refusal.details_of(e), struct: self,
+          )
       end
 
       private
 
+      def graphql_name = T.unsafe(self).const_get(:GRAPHQL_NAME)
+
       # The prop whose value its own type refuses, reported the way every
       # other input failure is. Only sorbet stands between a field with no
       # coercer and the struct, and it names the prop and the value inside
@@ -173,13 +251,22 @@ module GraphWeaver
           # :type_object carries the nilable-ness the prop was declared with;
           # :type is that unwrapped, which is the half worth naming — an
           # absent optional field is nil and legal, and a missing required
-          # one was reported by name before we got here
-          next if T::Utils.coerce(info[:type_object]).valid?(value)
+          # one was reported by name before we got here.
+          #
+          # recursively_valid?, which is the predicate the SETTER enforces:
+          # #valid? stops at the outermost type, so `[1, 2, 3]` for a
+          # T::Array[Float] (a type-string registration, so no coercer ran)
+          # passed here while the setter refused it — and the refusal came
+          # out blaming the list that held the struct, in sorbet's words.
+          next if T::Utils.coerce(info[:type_object]).recursively_valid?(value)
 
+          type = T::Utils.coerce(info[:type]).to_s
           return GraphWeaver::InputError.new(
-            "#{prop}: expected #{T::Utils.coerce(info[:type])}, " \
-              "got #{GraphWeaver::Internal::Redact.detail(prop, value.inspect)}",
-            field: prop.to_s, struct: self,
+            "#{prop}: expected #{type}, got #{GraphWeaver::Internal::Redact.shown(value, prop)}",
+            kind: :type_mismatch, path: [prop.to_s],
+            coordinate: T.unsafe(self).const_get(:FIELDS).find { |f| f.prop == prop }&.coordinate,
+            value: GraphWeaver::Internal::Redact.value(prop, value),
+            details: { type: }, struct: self,
           )
         end
         nil

data/lib/graph_weaver/internal/endpoint.rb

@@ -0,0 +1,78 @@
+# typed: true
+# frozen_string_literal: true
+
+require "uri"
+
+module GraphWeaver
+  module Internal
+    # The endpoint as the gem is willing to SAY it — in a log line, an
+    # exception, an APM payload. Every one of those outlives the request, and a
+    # url can carry a credential two ways: its userinfo, and a query parameter
+    # (`?access_token=…`). Transport#url stays the real endpoint — that is
+    # where requests go, and what `graphql: :wire` stubs on.
+    module Endpoint
+      class << self
+        def safe(url)
+          uri = URI(url.to_s)
+          # the overwhelmingly common case: a url with nothing to hide, said
+          # back exactly as it was configured
+          return url.to_s unless uri.userinfo || uri.query
+
+          query = uri.query
+          userinfo = uri.userinfo
+          uri.query = nil
+          uri.fragment = nil # never sent to a server; nothing to report
+
+          # URI#userinfo= is a no-op for nil, so the swap happens on the text —
+          # "//<userinfo>@" appears once, right after the scheme
+          text = uri.to_s
+          text = text.sub("//#{userinfo}@", "//#{GraphWeaver::FILTERED}@") if userinfo
+          text = "#{text}?#{scrub_query(query)}" if query
+          text
+        rescue URI::Error
+          # a url we can't take apart is one we can't promise to have scrubbed
+          GraphWeaver::FILTERED
+        end
+
+        # The endpoint with its credentials REMOVED rather than marked — for a
+        # place the url is read back from, such as a dump's provenance, where
+        # a "[FILTERED]" would be parsed as a host. Nothing is lost that
+        # belonged there: re-introspection authenticates from auth_env.
+        def bare(url)
+          uri = URI(url.to_s)
+          return url.to_s unless uri.userinfo || uri.query
+
+          uri.user = nil
+          uri.password = nil
+          uri.fragment = nil
+          uri.query = uri.query && drop_secrets(uri.query)
+          uri.to_s
+        end
+
+        private
+
+        def drop_secrets(query)
+          kept = query.split("&").reject do |pair|
+            name, value = pair.split("=", 2)
+            value && Redact.filtered?(URI.decode_www_form_component(name))
+          end
+          kept.join("&") unless kept.empty?
+        end
+
+        # Which query parameters are secret is the same question
+        # GraphWeaver.filter_parameters already answers for variables, so a
+        # scrubbed log reads the same either side of the seam. Split rather
+        # than decoded and re-encoded: every parameter that stays is printed
+        # exactly as it was sent.
+        def scrub_query(query)
+          query.split("&").map do |pair|
+            name, value = pair.split("=", 2)
+            next pair if value.nil? || !Redact.filtered?(URI.decode_www_form_component(name))
+
+            "#{name}=#{GraphWeaver::FILTERED}"
+          end.join("&")
+        end
+      end
+    end
+  end
+end

data/lib/graph_weaver/internal/headers.rb

@@ -0,0 +1,51 @@
+# typed: true
+# frozen_string_literal: true
+
+module GraphWeaver
+  module Internal
+    # Response headers, as ServerError carries them. HTTP field names are
+    # case-insensitive (RFC 9110 §5.1) and the spelling a caller reaches for
+    # is the one the server sent ("Retry-After"), while transports store them
+    # downcased — so the name is folded on the way in and on the lookups that
+    # take one: #[], #fetch, #dig, #key?. Only lookup is forgiving: iteration,
+    # #keys and #to_h stay one spelling, which is what a log line and a doc
+    # can promise.
+    class Headers < Hash
+      # tells "no default given" from a default of nil
+      MISSING = Object.new
+      private_constant :MISSING
+
+      # A Hash of any casing as one of these; already one, untouched.
+      def self.wrap(headers)
+        return headers if headers.is_a?(self)
+
+        headers.each_with_object(new) { |(name, value), out| out.store(fold(name), value) }
+      end
+
+      def self.fold(name) = name.to_s.downcase
+
+      def [](name) = super(Headers.fold(name))
+
+      # spelled out rather than forwarded: sorbet can't splat into Hash#fetch's
+      # overloads, and a block beats a default there (Ruby warns if given both)
+      def fetch(name, default = MISSING, &block)
+        folded = Headers.fold(name)
+        return super(folded, &block) if block || default.equal?(MISSING)
+
+        super(folded, default)
+      end
+
+      # Hash#dig reads the slot directly rather than through #[], so the fold
+      # has to happen here; a header value is a String, so `rest` can only error
+      def dig(name, *rest)
+        value = self[name]
+        rest.empty? ? value : value&.dig(*rest)
+      end
+
+      def key?(name) = super(Headers.fold(name))
+      alias_method :has_key?, :key?
+      alias_method :include?, :key?
+      alias_method :member?, :key?
+    end
+  end
+end