graph_weaver 0.7.4 → 0.7.6

data/lib/graph_weaver/testing/router.rb

@@ -326,11 +326,14 @@ module GraphWeaver
 
         plan = @planner.plan(document, operation_name:)
         return introspect(query, variables, plan.operation_name) if plan.introspection
+        # read once, so every hop runs as the identity the query started
+        # with, whatever writes #context= while it is in flight
+        context = Internal::Util.context!(@context)
         # one subgraph answers the whole thing: hand it the document as
         # written, so nothing is rewritten that didn't have to be
-        return fetch(plan.entry, query, variables, plan.operation_name) if plan.verbatim
+        return fetch(plan.entry, query, variables, plan.operation_name, context) if plan.verbatim
 
-        run(plan, variables)
+        run(plan, variables, context)
       end
 
       # never leak the context (tokens, current_user) through logs or errors
@@ -374,7 +377,7 @@ module GraphWeaver
 
       # ---- execution ----------------------------------------------------
 
-      def run(plan, variables)
+      def run(plan, variables, context)
         errors = []
         data = {}
         # An operation's declared defaults are part of the variables, and
@@ -384,7 +387,7 @@ module GraphWeaver
           .merge(variables.to_h { |name, value| [name.to_s, value] })
 
         plan.steps.each do |step|
-          result = fetch_step(step, plan.operation, given)
+          result = fetch_step(step, plan.operation, given, context)
           Array(result["errors"]).each { |error| errors << rewrite(error, step.subgraph) }
           payload = result["data"]
           if payload.nil?
@@ -397,7 +400,7 @@ module GraphWeaver
           end
         end
 
-        plan.steps.each { |step| stitch(step, [[data, []]], plan.operation, given, errors) }
+        plan.steps.each { |step| stitch(step, [[data, []]], plan.operation, given, context, errors) }
 
         # A stitched fetch can leave a null where the composed schema says
         # non-null, and nothing re-applies GraphQL's propagation rules over a
@@ -443,7 +446,7 @@ module GraphWeaver
       # Everything the plan applies at this level: one _entities fetch per
       # subgraph the level defers to (all nodes at once — _entities answers
       # in representation order), then the same again one level down.
-      def stitch(step, nodes, operation, variables, errors)
+      def stitch(step, nodes, operation, variables, context, errors)
         return if nodes.empty?
 
         # An abstract position: the plan holds one branch per concrete type
@@ -454,12 +457,12 @@ module GraphWeaver
         if step.is_a?(Internal::Planner::Branches)
           step.steps.each do |type_name, branch|
             stitch(branch, nodes.select { |(node, _)| node[TYPENAME] == type_name },
-              operation, variables, errors)
+              operation, variables, context, errors)
           end
           return
         end
 
-        blocked = prefetch(step, nodes, operation, variables, errors)
+        blocked = prefetch(step, nodes, operation, variables, context, errors)
 
         # A fetch for a selection the operation excluded is a fetch a real
         # router never makes, and `trace` is something specs assert on. The
@@ -478,7 +481,8 @@ module GraphWeaver
 
           entities = []
           if fetched.any?
-            result = entities_fetch(target, step.type_name, deferrals.map(&:node), representations, operation, variables)
+            result = entities_fetch(target, step.type_name, deferrals.map(&:node), representations, operation,
+              variables, context)
             entities = result.dig("data", "_entities") || []
             Array(result["errors"]).each { |error| errors << rewrite(error, target, fetched) }
           end
@@ -502,12 +506,12 @@ module GraphWeaver
           deferrals.each do |deferral|
             next unless deferral.step
 
-            stitch(deferral.step, descend(nodes, deferral.response_key), operation, variables, errors)
+            stitch(deferral.step, descend(nodes, deferral.response_key), operation, variables, context, errors)
           end
         end
 
         step.children.each do |key, child|
-          stitch(child, descend(nodes, key), operation, variables, errors)
+          stitch(child, descend(nodes, key), operation, variables, context, errors)
         end
 
         nodes.each { |(node, _)| strip!(node, step) }
@@ -517,7 +521,7 @@ module GraphWeaver
       # keys before the fetch whose representation carries them. Returns the
       # nodes the holding subgraph didn't recognize: their required fields
       # don't exist, so nothing depending on them can resolve.
-      def prefetch(step, nodes, operation, variables, errors)
+      def prefetch(step, nodes, operation, variables, context, errors)
         blocked = []
         # the field it feeds was excluded, so this is a fetch a real router
         # never makes — and a test double that runs a resolver production
@@ -533,7 +537,7 @@ module GraphWeaver
           selections = Internal::Planner.injected_selections(group.flat_map(&:paths).uniq)
           roots = selections.map(&:alias)
 
-          result = entities_fetch(subgraph, step.type_name, selections, representations, operation, variables)
+          result = entities_fetch(subgraph, step.type_name, selections, representations, operation, variables, context)
           entities = result.dig("data", "_entities") || []
           Array(result["errors"]).each { |error| errors << rewrite(error, subgraph, nodes) }
 
@@ -621,16 +625,16 @@ module GraphWeaver
         Array(path).map { |segment| segment.is_a?(String) ? segment.delete_prefix(PREFIX) : segment }
       end
 
-      def fetch_step(step, operation, variables)
+      def fetch_step(step, operation, variables, context)
         document = GraphQL::Language::Nodes::OperationDefinition.new(
           operation_type: operation.operation_type || "query",
           variables: used_variables(step.selections, operation),
           selections: step.selections,
         )
-        run_subgraph(step.subgraph, document, variables)
+        run_subgraph(step.subgraph, document, variables, context)
       end
 
-      def entities_fetch(subgraph, type_name, nodes, representations, operation, variables)
+      def entities_fetch(subgraph, type_name, nodes, representations, operation, variables, context)
         entities = GraphQL::Language::Nodes::Field.new(
           name: "_entities",
           arguments: [GraphQL::Language::Nodes::Argument.new(
@@ -647,7 +651,7 @@ module GraphWeaver
           variables: [REPRESENTATIONS_DEFINITION] + used_variables(nodes, operation),
           selections: [entities],
         )
-        run_subgraph(subgraph, document, variables.merge(REPRESENTATIONS => representations))
+        run_subgraph(subgraph, document, variables.merge(REPRESENTATIONS => representations), context)
       end
 
       REPRESENTATIONS = "representations"
@@ -682,12 +686,12 @@ module GraphWeaver
         end
       end
 
-      def run_subgraph(subgraph, document, variables)
+      def run_subgraph(subgraph, document, variables, context)
         declared = document.variables.map(&:name)
-        fetch(subgraph, document.to_query_string, variables.slice(*declared), nil)
+        fetch(subgraph, document.to_query_string, variables.slice(*declared), nil, context)
       end
 
-      def fetch(name, query, variables, operation_name)
+      def fetch(name, query, variables, operation_name, context)
         faked = @faked.include?(name)
         entry = { subgraph: name, query:, variables: variables.to_h }
         entry[:faked] = true if faked
@@ -701,14 +705,12 @@ module GraphWeaver
         end
 
         GraphWeaver::Internal::Log.log(:debug) do
-          "router -> #{name} #{tag} variables=#{JSON.generate(GraphWeaver::Internal::Log.filter_variables(variables))}
-" \
+          "router -> #{name} #{tag} variables=#{JSON.generate(GraphWeaver::Internal::Log.filter_variables(variables))}\n" \
             "#{GraphWeaver::Internal::Wire.truncate_for_log(query)}"
         end
 
         GraphWeaver::Internal::Log.log_timed(:debug, "router -> #{name} #{tag} completed") do
-          @subgraphs.fetch(name).execute(query, variables:, operation_name:,
-            context: Internal::Util.context!(@context)).to_h
+          @subgraphs.fetch(name).execute(query, variables:, operation_name:, context:).to_h
         end
       end
 
@@ -783,7 +785,6 @@ module GraphWeaver
         end
         ordered
       end
-
     end
   end
 end

data/lib/graph_weaver/testing.rb

@@ -340,10 +340,14 @@ module GraphWeaver
             "Declare it with the class: GraphWeaver.graph(#{graph.name.inspect}) " \
             "{ schema -> { MySchema } }."
         else
+          # the helper needs no tag, which is what makes it reachable from
+          # BOTH paths into here: a tagged example is already past its own
+          # before hook, so "name it in the example" only works if the tag goes
           "GraphWeaver.client isn't running one in-process to borrow. Name it in the example — " \
-            "graphql_in_process(MySchema) — or set GraphWeaver::Testing.config.schema = MySchema " \
-            "for the whole suite. A federated app names the subgraph it means, per example; " \
-            "graphql: :router runs the graph stitched."
+            "graphql_in_process(MySchema) — instead of the graphql: :in_process tag, which " \
+            "builds this client in a `before` hook of its own and so is already past. Or set " \
+            "GraphWeaver::Testing.config.schema = MySchema for the whole suite. A federated app " \
+            "names the subgraph it means, per example; graphql: :router runs the graph stitched."
         end
       end
 
@@ -352,7 +356,6 @@ module GraphWeaver
       def runnable(schema)
         schema if schema.is_a?(Class) && schema <= GraphQL::Schema
       end
-
     end
 
     class << self
@@ -412,7 +415,7 @@ module GraphWeaver
       # the precision case gets exercised at all.
       def check_scalars!(schema)
         registry = Internal::Util.registry_for(schema)
-        values = Internal::Values.new(seed: 0, schema:, registry:)
+        values = Internal::Values.new(seed: 0, schema:, registry:, pin_advice: method(:pin_for_check))
         context = GraphQL::Query.new(schema, "{ __typename }").context
 
         disagreed = schema.types.values.sort_by(&:graphql_name).filter_map do |type|
@@ -432,6 +435,14 @@ module GraphWeaver
 
       private
 
+      # check_scalars! takes the schema and nothing else, and runs outside
+      # every fake — so of the doors onto a pin only the suite-wide one is a
+      # door here. graphql_fake is a no-op, and there is no second argument.
+      def pin_for_check(name)
+        "Pin the form this server sends: GraphWeaver::Testing.config.overrides = " \
+          "{ #{name.inspect} => ... }."
+      end
+
       # One scalar's verdict, or nil when the two halves agree. Each step is
       # a different mistake, so each says which.
       def disagreement(scalar, type, values, context)
@@ -449,8 +460,8 @@ module GraphWeaver
         begin
           sample = cast.call(wire)
         rescue StandardError => e
-          return "#{name}: cast: can't read #{wire.inspect}, the value fabricated for it (#{e.message}) " \
-            "— pin the form this server sends: overrides: { #{name.inspect} => ... }"
+          return "#{name}: cast: can't read #{wire.inspect}, the value fabricated for it " \
+            "(#{e.message}). #{pin_for_check(name)}"
         end
 
         if scalar.serialize? && !scalar.serialize_value?
@@ -476,7 +487,15 @@ module GraphWeaver
         end
         return if back == sample
 
-        "#{name}: round-trips lossily — sent #{sample.inspect}, got back #{back.inspect}"
+        sent = Internal::Redact.spell(sample)
+        got = Internal::Redact.spell(back)
+        return "#{name}: round-trips lossily — sent #{sent}, got back #{got}" unless sent == got
+
+        # two identical spellings for two unequal values: the class inherits
+        # Object#==, which is identity, so this can't tell a lossy round trip
+        # from a faithful one and must not claim either
+        "#{name}: #{sample.class} defines no ==, so a round trip can't be checked — sent " \
+          "#{sent} and got back #{got}, and nothing here can tell those apart"
       end
 
       # The registration's `cast:`, RUN rather than emitted. A cast builds

data/lib/graph_weaver/transport.rb

@@ -99,7 +99,7 @@ class GraphWeaver::Transport
     payload = { url: safe_url, operation: operation_name, client: self.class,
                 kind: GraphWeaver::Internal::Wire.kind(query) }
 
-    GraphWeaver::Internal::Log.instrument(GraphWeaver::EXECUTE_EVENT, payload) do
+    GraphWeaver::Internal::Log.instrument_request(payload) do
       perform(query, variables, operation_name, payload)
     end
   end

data/lib/graph_weaver/version.rb

@@ -1,3 +1,3 @@
 module GraphWeaver
-  VERSION = "0.7.4"
+  VERSION = "0.7.6"
 end

data/lib/graph_weaver.rb

@@ -214,7 +214,7 @@ module GraphWeaver
     attr_accessor :skip_generated_load
 
     # The name of the shared module — the types that live once per schema
-    # (input types, enums, unions hoisted from shared fragments) and are
+    # (input types, enums, the types hoisted from shared fragments) and are
     # aliased into every query module that touches them. Constant, not derived
     # from where you put the files: set it globally, or pass types_module: per
     # generate!. A multi-schema layout names it in the same initializer that
@@ -614,8 +614,8 @@ module GraphWeaver
     #      #         "line" => 4, "column" => 5 }] }
     #
     # Empty means every query validates. schema: defaults to the server as
-    # it is now — a FRESH introspection of the url the dump records, or the
-    # live schema class when the app default runs in-process — and the dump
+    # it is now — a FRESH introspection of the source behind each graph's
+    # dump, or the live schema class where that source IS one — and the dump
     # is left alone; pass schema: and nothing touches the network.
     #
     # When that dump is a composed supergraph, an error naming a type is
@@ -623,17 +623,25 @@ module GraphWeaver
     # (products, reviews)", plus a "subgraphs" key — since knowing whose
     # code to look at is half the answer. A plain schema is unaffected.
     #
-    # One query you have as a *string* is Client#check_query — the same
-    # entries, against that client's own schema.
+    # One query you have as a *string* is #check_query, which every client
+    # holding a schema answers — the same entries, against that schema.
     #
     # A different question from verify_generated!, which asks whether the
     # committed Ruby matches the committed schema. `rake
     # graph_weaver:queries:check` prints this and exits non-zero.
     def check_queries(schema: nil, queries: nil, fragments: fragments_paths)
       shared = Codegen.load_fragments(fragments)
-
-      graphs_for(schema:, queries:).each_with_object({}) do |graph, failures|
-        checked = checked_schema(graph)
+      # one graph's server being down is that graph's verdict: every graph is
+      # attempted, so a run names every server it couldn't reach rather than
+      # ending at the first
+      unreachable = []
+
+      failures = graphs_for(schema:, queries:).each_with_object({}) do |graph, failures|
+        begin
+          checked = checked_schema(graph)
+        rescue Error => e
+          next unreachable << unreachable_source(graph, e)
+        end
         table = checked_routing_table(graph)
         Internal::Util.query_files(graph.queries).each do |path|
           errors = Internal::QueryCheck.errors(checked, File.read(path), shared, table)
@@ -646,13 +654,39 @@ module GraphWeaver
           failures[key] = failures.key?(key) ? failures[key] | errors : errors
         end
       end
+
+      raise Error, unreachable.join("\n") unless unreachable.empty?
+
+      failures
     end
 
-    # What this graph is checked against. A graph that names its schema is
-    # checked against exactly that, so nothing touches the network; the default
-    # graph names none, so its dump is re-introspected first (see
-    # refreshed_schema).
-    def checked_schema(graph) = graph.named_schema? ? graph.schema : refreshed_schema
+    # Which graph couldn't be checked, and against what. The bare socket error
+    # named neither — in a multi-graph app it was the entire output, and the
+    # reader could not tell which of their servers was down.
+    def unreachable_source(graph, error)
+      whose = graph.name ? "graph #{graph.name.inspect}" : "this app"
+      dump = graph.dump_path || graph.named_dump_path
+      subject = dump ? Internal::Util.relative(dump) : "these queries"
+      "#{whose}: couldn't reach the schema behind #{subject} — #{error.message}"
+    end
+    private :unreachable_source
+
+    # What this graph is checked against: Graph#source, the rule `schema:refresh`
+    # and `schema:diff` follow too. A live class is asked directly — for an app
+    # that IS the server, a dump is a snapshot of its own code, and checking
+    # against it reports phantom errors about a field just added. A url is
+    # re-introspected, so no refresh step (and no rewritten dump) is needed
+    # first. A graph with neither — hand-written SDL nothing serves, a composed
+    # supergraph — has nothing to re-read, so it is checked as committed.
+    def checked_schema(graph)
+      source = graph.source
+      return source if source.is_a?(Module)
+      # Internal::Util.locate_schema! raises the conventional "no schema dump"
+      # message when the default graph has no dump either
+      return graph.schema unless source
+
+      SchemaLoader.introspect(graph.source_transport)
+    end
     private :checked_schema
 
     # The routing table behind the schema check_queries is about to use, when
@@ -663,28 +697,6 @@ module GraphWeaver
     end
     private :checked_routing_table
 
-    # The schema check_queries defaults to: the server as it is now. Over a
-    # socket that's a fresh introspection of the url the local dump recorded,
-    # so no refresh step (and no rewritten dump) is needed first. In-process
-    # it's the live schema class — for an app that IS the server, a dump is a
-    # snapshot of its own code, and checking against it reports phantom
-    # errors about a field you just added. Dumps with no url and no live
-    # class — hand-written SDL, a composed supergraph — have nothing to
-    # re-read, so they're checked as they are.
-    def refreshed_schema
-      live = Internal::Util.live_schema
-      return live if live
-
-      # Internal::Util.locate_schema! raises the conventional "no schema dump" message
-      path = SchemaLoader.locate_path or Internal::Util.locate_schema!
-      return SchemaLoader.load(path) unless SchemaLoader.provenance(path)&.key?("url")
-
-      # source_transport rather than one built here: it reads the auth ENV var
-      # the dump named, so `--auth MY_TOKEN` reaches this path too
-      SchemaLoader.introspect(SchemaLoader.source_transport(path))
-    end
-    private :refreshed_schema
-
     # Load the generated modules — one line in an initializer or spec
     # helper (loading happens only when you call this; skip it and
     # require files yourself if you'd rather):
@@ -795,7 +807,7 @@ module GraphWeaver
 
     # (filename, source) per artifact. Types a schema shares across queries —
     # input types, schema enums, and each named shared fragment spread as a
-    # whole-union field — are emitted once into the shared module, with query
+    # whole field — are emitted once into the shared module, with query
     # modules aliasing what they use. That's the difference between hundreds of
     # duplicated bool_exp structs (or one Ruby class per query for the same
     # schema enum) and one copy per schema. (Single-query parse inlines
@@ -814,7 +826,7 @@ module GraphWeaver
       @unmatched_registrations |= registry.unmatched_registrations(schema)
 
       used = { inputs: [], enums: [], mapped: [] }
-      used_unions = []
+      hoisted = []
       helpers = []
       shared = Codegen.load_fragments(fragments)
 
@@ -831,30 +843,30 @@ module GraphWeaver
           name:,
           graph_name: graph.name,
           types_namespace: graph.types_module,
-          hoistable_unions: Codegen.shared_fragment_spreads(source, shared, path),
+          hoistable_fragments: Codegen.shared_fragment_spreads(source, shared, path),
           path:,
           registry:,
         )
         out = codegen.generate
         codegen.variable_type_names.each { |kind, names| used[kind] |= names }
         found.concat(codegen.untyped_scalars).uniq!
-        used_unions |= codegen.used_union_names
+        hoisted |= codegen.used_fragment_names
         helpers |= codegen.block_helpers
         [filename, out]
       rescue GraphWeaver::Error => e
         # collected, not raised: nothing is written either way, and an adopter
         # aiming generate! at an existing query directory wants the list
-        refusals << e
+        refusals << name_query_file(e, path)
         nil
       end
       refuse_all!(refusals, paths.size)
 
-      if used_unions.any? || used.values.any?(&:any?)
+      if hoisted.any? || used.values.any?(&:any?)
         refuse_duplicate_types!(seen, graph)
         codegen = Codegen.new(schema:, query: "", name: graph.types_module, registry:)
         types = codegen.generate_types(
           inputs: used[:inputs], enums: used[:enums] + used[:mapped],
-          unions: used_unions, fragments: shared,
+          hoisted:, fragments: shared,
         )
         found.concat(codegen.untyped_scalars).uniq!
         helpers |= codegen.block_helpers
@@ -907,6 +919,18 @@ module GraphWeaver
     # itself, so a single bad file reads exactly as it always has — class,
     # message and all; several become one list, because clearing them a file
     # per run is the slowest way there is to adopt this.
+    # Almost every codegen refusal is about the query in front of it and never
+    # says which file that was — so a list of them named nothing, which is the
+    # one thing a list is for. This rescue is the only place holding both.
+    # #exception keeps the class and its fields and swaps only the message.
+    def name_query_file(error, path)
+      reported = Internal::Util.relative(path)
+      return error if error.message.include?(reported)
+
+      error.exception("#{reported}: #{error.message}")
+    end
+    private :name_query_file
+
     def refuse_all!(refusals, considered)
       return if refusals.empty?
       raise refusals.first if refusals.one?
@@ -1051,6 +1075,12 @@ module GraphWeaver
     # mid-rename needs:
     #
     #      GraphWeaver.register_enum("Status", alias: { "legacy_mode" => "LEGACY_MODE" })
+    #
+    # fallback: true is the type-less form of forward-compat: the generated
+    # enum gains an Other member and casts every value the schema doesn't
+    # declare to it, so a server adding one doesn't take the client down.
+    #
+    #      GraphWeaver.register_enum("Species", fallback: true)
     def register_enum(graphql_name, type = nil, positional_map = nil, map: nil, fallback: nil, requires: nil,
       alias: nil)
       # `alias` is a Ruby keyword, so the parameter is only readable through binding

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graph_weaver
 version: !ruby/object:Gem::Version
-  version: 0.7.4
+  version: 0.7.6
 platform: ruby
 authors:
 - Daniel Pepper
@@ -281,6 +281,7 @@ files:
 - docs/getting_started.md
 - docs/i18n.md
 - docs/logging.md
+- docs/migrating.md
 - docs/real_world.md
 - docs/scalars.md
 - docs/testing.md
@@ -363,7 +364,7 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/dpep/graph_weaver/issues
-  changelog_uri: https://github.com/dpep/graph_weaver/blob/v0.7.4/CHANGELOG.md
+  changelog_uri: https://github.com/dpep/graph_weaver/blob/v0.7.6/CHANGELOG.md
   documentation_uri: https://github.com/dpep/graph_weaver/tree/main/docs
   rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/dpep/graph_weaver