graph_weaver 0.6.1 → 0.7.1

data/lib/graph_weaver/internal/headers.rb

@@ -0,0 +1,70 @@
+# typed: true
+# frozen_string_literal: true
+
+require "time" # Time.httpdate, for Retry-After
+
+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
+
+      # 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; a date
+      # already past clamps to 0. See RFC 9110 §10.2.3.
+      #
+      # Here rather than on ServerError because a rate limit reaches a caller
+      # two ways — raised, and returned as the envelope a 4xx/5xx WITH a
+      # GraphQL errors body makes — and both have to read the one rule.
+      def retry_after
+        value = self["retry-after"]&.strip
+        return if value.nil? || value.empty?
+        return value.to_f if value.match?(/\A\d+(\.\d+)?\z/)
+
+        [Time.httpdate(value) - Time.now, 0.0].max
+      rescue ArgumentError
+        nil
+      end
+
+      def key?(name) = super(Headers.fold(name))
+      alias_method :has_key?, :key?
+      alias_method :include?, :key?
+      alias_method :member?, :key?
+    end
+  end
+end

data/lib/graph_weaver/internal/overrides.rb

@@ -10,6 +10,10 @@ module GraphWeaver
     # suite-wide ones while the block that set them is still on the stack,
     # and a fake built with its own checks them then.
     module Overrides
+      # The key a Hash `list_size:` says its fallback under — every list it
+      # doesn't name.
+      LIST_SIZE_DEFAULT = "default"
+
       class << self
         # A pin key names something in the schema: a type ("Money",
         # "Person"), a "Type.field" coordinate, or a bare field name
@@ -22,6 +26,44 @@ module GraphWeaver
           end
         end
 
+        # Whether `key` reads as a reference into the schema rather than a
+        # plain word — what tells a pin from an option at a fake's door, where
+        # both arrive as the same keywords. A "Type.field" coordinate can only
+        # be a pin; a bare word is one when the schema knows it. Whether the
+        # reference RESOLVES is validate!'s question, so a coordinate naming
+        # no type is still a pin and gets that refusal rather than "unknown
+        # option".
+        #
+        # Casing can't decide it: Hasura's types are lowercase, and
+        # `pokemon_v2_pokemon` read as a misspelled option.
+        def schema_reference?(schema, key)
+          key = key.to_s
+          return true if key.include?(".") || key.start_with?("__")
+
+          !schema.get_type(key).nil? || field_names(schema).include?(key)
+        end
+
+        # Every name a pin may be keyed by — the dictionary a refusal guesses
+        # from when a key is neither a pin nor an option.
+        def pin_names(schema) = schema.types.keys + field_names(schema)
+
+        # A Hash `list_size:` sizes one list at a time, keyed the way a pin is
+        # minus the bare type name: a type says nothing about how long any one
+        # of its fields is.
+        def validate_list_size!(schema, list_size)
+          return unless list_size.is_a?(Hash)
+
+          list_size.each do |key, value|
+            unless value.is_a?(Integer) || value.is_a?(Range)
+              raise GraphWeaver::Error, "list_size: #{key.to_s.inspect} must be an Integer or a " \
+                "Range — how long an unbounded list is — got #{value.inspect}"
+            end
+            next if key.to_s == LIST_SIZE_DEFAULT
+
+            validate_field_key!(schema, key.to_s, "list_size: key")
+          end
+        end
+
         # A pin that's a proc is handed the seeded Random when it takes one
         # and called bare when it doesn't, so a varying pin still reproduces
         # under `rspec --seed`.
@@ -55,16 +97,36 @@ module GraphWeaver
 
             # a leading capital names a type, as it does wherever a pin is written
             dictionary = type_name.match?(/\A[A-Z]/) ? schema.types.keys : known
-            bad!(key, "matches no type or field in this schema", dictionary, type_name)
+            bad!("override key", key, "matches no type or field in this schema", dictionary, type_name)
+          end
+
+          coordinate!(schema, "override key", key, type_name, field_name)
+        end
+
+        # A key naming one FIELD — a "Type.field" coordinate, or a bare field
+        # name matching that field on any type.
+        def validate_field_key!(schema, key, label)
+          type_name, field_name = key.split(".", 2)
+          return if (field_name || type_name).start_with?("__")
+
+          if field_name.nil?
+            known = field_names(schema)
+            return if known.include?(type_name)
+
+            bad!(label, key, "matches no field in this schema", known, type_name)
           end
 
+          coordinate!(schema, label, key, type_name, field_name)
+        end
+
+        def coordinate!(schema, label, key, type_name, field_name)
           type = schema.get_type(type_name)
           unless type.respond_to?(:fields)
-            bad!(key, "names no object type in this schema", schema.types.keys, type_name)
+            bad!(label, key, "names no object type in this schema", schema.types.keys, type_name)
           end
           return if type.fields.key?(field_name)
 
-          bad!(key, "is not a field of #{type_name}", type.fields.keys, field_name)
+          bad!(label, key, "is not a field of #{type_name}", type.fields.keys, field_name)
         end
 
         # A type pin says what every value of that type is, and the fake only
@@ -84,10 +146,10 @@ module GraphWeaver
             "#{type.graphql_name}, and a pin fabricates a scalar, enum or object: #{advice}"
         end
 
-        def bad!(key, problem, dictionary, term)
+        def bad!(label, key, problem, dictionary, term)
           suggestion = Util.did_you_mean(dictionary, term)
           hint = suggestion ? " — did you mean '#{suggestion}'?" : ""
-          raise GraphWeaver::Error, "override key #{key.inspect} #{problem}#{hint}"
+          raise GraphWeaver::Error, "#{label} #{key.inspect} #{problem}#{hint}"
         end
 
         # Every output field name in the schema — walked only when a bare key

data/lib/graph_weaver/internal/planner.rb

@@ -3,6 +3,7 @@
 
 require "graphql"
 
+require_relative "selection"
 require_relative "subgraphs"
 
 module GraphWeaver
@@ -155,7 +156,20 @@ module GraphWeaver
           .map { |error| Wire.graphql_error(error.message, "GRAPHQL_VALIDATION_FAILED") }
       end
 
+      # @defer/@stream send the rest of the answer in later payloads over a
+      # multipart body; this router answers in one. Public and document-wide
+      # because the caller has to ask it BEFORE validation — the composed API
+      # schema usually doesn't declare the directives, so graphql-ruby's
+      # "Directive @defer is not defined" fires first and shadows this.
+      def refuse_incremental!(document)
+        node = Selection.incremental_directive(document) or return
+
+        refuse :incremental_delivery,
+          "this operation carries @#{node.name}, and the answer would arrive in more than one payload"
+      end
+
       def plan(document, operation_name: nil)
+        refuse_incremental!(document)
         operation = pick_operation(document, operation_name)
         refuse(:operation_type, "this document is a subscription") if
           operation.operation_type == "subscription"
@@ -178,7 +192,7 @@ module GraphWeaver
           return plan
         end
 
-        check_interface_objects!(root.graphql_name, selections, fragments) if @interface_objects.any?
+        check_reachable!(root.graphql_name, selections, fragments)
 
         entry = single_subgraph(root.graphql_name, selections, fragments)
         if entry
@@ -223,13 +237,14 @@ module GraphWeaver
 
       private
 
-      # Every type these selections reach, refused if one of them is an
-      # @interfaceObject: a subgraph resolves the whole interface there, so
-      # the supergraph records no per-field routing for it and every fetch
-      # planned against it would be a guess. Asked per query rather than at
-      # construction — one such directive shouldn't cost you the queries
-      # that never touch the type.
-      def check_interface_objects!(type_name, selections, fragments, depth = 0)
+      # Every position this operation reaches, refused if the supergraph says
+      # something about it no plan can honour — whatever plan it gets. It runs
+      # here, above the verbatim shortcut, because that is the only place
+      # every plan passes: a check that lives in {#plan_step} silently skips
+      # the query one subgraph answers whole. Asked per query rather than at
+      # construction — one such directive shouldn't cost you the queries that
+      # never touch it.
+      def check_reachable!(type_name, selections, fragments, depth = 0)
         return if depth > MAX_DEPTH
 
         selections.each do |node|
@@ -237,18 +252,20 @@ module GraphWeaver
           when GraphQL::Language::Nodes::Field
             next if node.name.start_with?("__")
 
+            contextual!(type_name, node)
+            progressive_override!(type_name, node)
             child = raw_child_type(type_name, node.name) or next
             interface_object!(child, "#{type_name}.#{node.name} returns #{child}")
-            check_interface_objects!(child, node.selections, fragments, depth + 1)
+            check_reachable!(child, node.selections, fragments, depth + 1)
           when GraphQL::Language::Nodes::InlineFragment
             condition = node.type&.name || type_name
             interface_object!(condition, "this operation selects ... on #{condition}")
-            check_interface_objects!(condition, node.selections, fragments, depth + 1)
+            check_reachable!(condition, node.selections, fragments, depth + 1)
           when GraphQL::Language::Nodes::FragmentSpread
             fragment = fragments[node.name] or next
             condition = fragment.type.name
             interface_object!(condition, "...#{node.name} is on #{condition}")
-            check_interface_objects!(condition, fragment.selections, fragments, depth + 1)
+            check_reachable!(condition, fragment.selections, fragments, depth + 1)
           end
         end
       end
@@ -352,7 +369,6 @@ module GraphWeaver
 
         here = step(subgraph, type_name)
         selections.each do |node|
-          contextual!(type_name, node)
           # a subtree that never leaves this subgraph goes over as written:
           # the boundary rules govern stitching, so they have no business
           # applying to a query that was never going to cross one
@@ -388,9 +404,9 @@ module GraphWeaver
 
       # A @fromContext argument is filled by the GATEWAY, out of a selection on
       # an ancestor — so a fetch this planner writes leaves it unset and the
-      # field resolves from nothing. Asked only of a field the planner routes
-      # itself: a subtree handed to one subgraph whole carries its own context,
-      # which is why the verbatim path never reaches here.
+      # field resolves from nothing. A subgraph's own resolver never fills one
+      # either, so handing it the subtree whole doesn't help: this is asked of
+      # every field the operation reaches, on every path.
       def contextual!(type_name, node)
         names = @table.field(type_name, node.name)&.contextual
         return if names.nil? || names.empty?
@@ -400,6 +416,20 @@ module GraphWeaver
           "on its own"
       end
 
+      # A progressive @override(label:) leaves BOTH subgraphs resolving the
+      # field — the label is the rollout rule the gateway evaluates per
+      # request to pick between them. A plain @override drops the losing copy
+      # at composition, so there is nothing to decide and nothing to refuse;
+      # a labelled one is a coin only the gateway can toss.
+      def progressive_override!(type_name, node)
+        field = @table.field(type_name, node.name)
+        label = field&.override_label or return
+
+        refuse :progressive_override, "#{type_name}.#{node.name} is mid-rollout under " \
+          "@override(label: #{label.inspect}) — #{field.graphs.join(" and ")} both resolve it, " \
+          "and a local router can't evaluate a rollout percentage"
+      end
+
       # The keys a fetch injects are stripped from the answer, so a caller's
       # alias spelling one is stripped with it — silently, since the two are
       # then indistinguishable. Asked of what this fetch actually injects

data/lib/graph_weaver/internal/refusal.rb

@@ -0,0 +1,49 @@
+# typed: true
+# frozen_string_literal: true
+
+module GraphWeaver
+  module Internal
+    # The verdict a coercion refusal already reached, riding on the plain
+    # ::TypeError / ::ArgumentError Coerce raises rather than on a class of
+    # its own — so `rescue ::TypeError` still catches it and Coerce keeps
+    # complaining the way Kernel#Integer does.
+    #
+    # The layers that brand a failure (InputStruct.field, Coerce.variable)
+    # read it off the exception instead of deriving a kind from the message.
+    # A message is prose; reading a verdict back out of one would be a guess,
+    # and a wrong `kind` is worse than none — the app will have translated it
+    # into a confident sentence.
+    module Refusal
+      attr_accessor :graph_weaver_kind, :graph_weaver_details
+
+      class << self
+        # Tag an exception with its verdict; returns it, ready to raise.
+        def brand(error, kind, **details)
+          error.extend(Refusal)
+          error.graph_weaver_kind = kind
+          error.graph_weaver_details = details
+          error
+        end
+
+        # What a raised exception says went wrong, as an InputError kind.
+        # Coerce's own refusals carry their verdict; an app's `cast:` or
+        # `serialize:` raises whatever it likes, and Ruby's own convention
+        # splits the two it raises for a value it can't use: TypeError means
+        # the CLASS was wrong, ArgumentError the CONTENT — which is the
+        # difference between "send something else" and "fix the text".
+        # Anything else is :refused rather than a guess at what it meant.
+        def kind_of(error)
+          return error.graph_weaver_kind if error.is_a?(Refusal)
+
+          case error
+          when ::TypeError then :type_mismatch
+          when ::ArgumentError then :unparseable
+          else :refused
+          end
+        end
+
+        def details_of(error) = error.is_a?(Refusal) ? error.graph_weaver_details : {}
+      end
+    end
+  end
+end

data/lib/graph_weaver/internal/schemas.rb

@@ -27,20 +27,34 @@ module GraphWeaver
         end
 
         # Does this schema carry the coordinate — "Type", or "Type.field"?
-        def defines?(schema, coordinate)
-          type_name, field_name = coordinate.split(".", 2)
-          type = schema.get_type(type_name) or return false
-          return true unless field_name
-
-          return type.fields.key?(field_name) if type.respond_to?(:fields)
-          # an input object's members are arguments, not fields
-          return type.arguments.key?(field_name) if type.respond_to?(:arguments)
+        def defines?(schema, coordinate) = !member(schema, coordinate).nil?
 
-          false
+        # The type this schema gives "Type.field", printed the way SDL prints
+        # it — so it compares directly against a supergraph's own spelling.
+        # Presence is the cheaper question and answers a different one: a
+        # field that is still *there* can have been retyped underneath the
+        # composition, which reads as a match until the types are compared.
+        def signature(schema, coordinate)
+          member = member(schema, coordinate)
+          member.type.to_type_signature if member.respond_to?(:type)
         end
 
         private
 
+        # The field (or, on an input object, the argument — its members are
+        # arguments, not fields) at "Type.field", or the type itself for a
+        # bare coordinate.
+        def member(schema, coordinate)
+          type_name, field_name = coordinate.split(".", 2)
+          type = schema.get_type(type_name) or return
+          return type unless field_name
+
+          return type.fields[field_name] if type.respond_to?(:fields)
+          return type.arguments[field_name] if type.respond_to?(:arguments)
+
+          nil
+        end
+
         def descendants(klass)
           klass.subclasses.flat_map { |subclass| [subclass] + descendants(subclass) }
         end

data/lib/graph_weaver/internal/selection.rb

@@ -12,6 +12,40 @@ module GraphWeaver
     module Selection
       include Kernel # for sorbet: hosts are Objects
 
+      # The directives that ask for the answer in instalments. Neither the
+      # generated code nor the local router reads a multipart body, and both
+      # have to say so BY NAME: whether the schema in hand declares @defer is
+      # graphql-ruby's business, so "Directive @defer is not defined" is an
+      # accident that happens to refuse — and it stops happening the day a
+      # supergraph @links the defer spec.
+      INCREMENTAL = %w[defer stream].freeze
+
+      # The first @defer/@stream node anywhere in a parsed document, or nil.
+      # A module function rather than part of the walk below: the callers ask
+      # before they have a schema, an operation, or a host to walk with.
+      def self.incremental_directive(node)
+        if node.respond_to?(:directives)
+          # a spread carries directives and no selections (`...Frag @defer`),
+          # so this is asked of every node rather than only of the ones below
+          applied = node.directives.find { |d| INCREMENTAL.include?(d.name) }
+          return applied if applied
+        end
+
+        children = if node.is_a?(GraphQL::Language::Nodes::Document)
+          node.definitions
+        elsif node.respond_to?(:selections)
+          node.selections
+        else
+          []
+        end
+
+        children.each do |child|
+          nested = incremental_directive(child)
+          return nested if nested
+        end
+        nil
+      end
+
       # Every method here becomes an instance method of its host (Codegen,
       # FakeClient, the cassette Anonymizer) — private so the walk stays the
       # host's own business rather than part of its API.