graph_weaver 0.6.1 → 0.7.0

data/lib/graph_weaver/testing/router.rb

@@ -50,6 +50,20 @@ module GraphWeaver
             "ancestor, and only the gateway that planned the fetch knows what to put there. Run " \
             "this one against a real router.",
         ],
+        incremental_delivery: [
+          "a response delivered in more than one payload",
+          "@defer/@stream stream the rest of the answer over a multipart body after the first " \
+            "payload, and this router answers in one. Run this one against a real router — the " \
+            "Apollo Router supports @defer behind an Accept header; @apollo/gateway doesn't " \
+            "know the directive at all.",
+        ],
+        progressive_override: [
+          "a progressive @override still rolling out",
+          "federation 2.7's @override(label:) leaves both subgraphs resolving the field and " \
+            "splits traffic between them by a rule only the gateway evaluates — a local router " \
+            "would pick one and answer from it every time. Run this one against a real router, " \
+            "or finish the rollout (drop the label) first.",
+        ],
         chained_requires: [
           "a @requires whose field set names another @requires field",
           "the router satisfies a @requires with one fetch, so it can't first satisfy that " \
@@ -214,8 +228,11 @@ module GraphWeaver
       # subgraphs answered with fabricated data instead of that refusal
       attr_reader :faked
 
-      # the context handed to every subgraph — settable, so one example can
-      # run as a different user without rebuilding the router
+      # The context handed to every subgraph — settable, so one example can
+      # run as a different user without rebuilding the router. A proc is
+      # answered from the request's headers, which only a wire supplies:
+      # `context: ->(headers) { { current_user: User.find_by(token:
+      # headers["Authorization"]) } }` served through {Endpoint}.
       attr_accessor :context
 
       # The planner injects key fields under this prefix, and the concrete
@@ -292,6 +309,12 @@ module GraphWeaver
           return { "data" => nil, "errors" => [Internal::Wire.graphql_error(e.message, "GRAPHQL_PARSE_FAILED")] }
         end
 
+        # above validation, which would otherwise answer "Directive @defer is
+        # not defined" — an accident of the composed schema, not this router's
+        # decision, and one that stops refusing the day a supergraph @links
+        # the defer spec
+        @planner.refuse_incremental!(document)
+
         # validate the way a router does, so a stale query fails as it fails
         # in production rather than somewhere inside the planner
         errors = @planner.validate(document)
@@ -326,6 +349,12 @@ module GraphWeaver
       # green — the same silent pass a typo'd override key is refused for.
       def check_fake!(options)
         options = options.to_h
+        # rspec's --seed already drives the fake, and a router is built once
+        # for the suite — a seed here would pin every example to one run
+        if options.key?(:seed) || options.key?("seed")
+          raise GraphWeaver::ConfigurationError, "seed: isn't a fake: option — `rspec --seed 1234` " \
+            "reproduces a run, and GraphWeaver::Testing.config.seed sets one for a harness that isn't rspec"
+        end
         return options.freeze if options.empty? || @faked.any?
 
         raise GraphWeaver::ConfigurationError, "fake: says how faked subgraphs fabricate, and this " \
@@ -352,7 +381,7 @@ module GraphWeaver
 
         plan.steps.each do |step|
           result = fetch_step(step, plan.operation, given)
-          Array(result["errors"]).each { |error| errors << rewrite(error) }
+          Array(result["errors"]).each { |error| errors << rewrite(error, step.subgraph) }
           payload = result["data"]
           if payload.nil?
             # the subgraph nulled its whole response, so every field it was
@@ -433,10 +462,12 @@ module GraphWeaver
         # plan is built once and reused, so only here are the variables known.
         wanted = step.deferrals.select { |d| included?(d.node, variables) }
 
-        # a @requires fetch and a plain one need different node sets, so they
-        # can't share a call even into the same subgraph — which is the split
-        # a real router makes too
-        wanted.group_by { |d| [d.subgraph, d.requires.any?] }.each do |(target, chained), deferrals|
+        # Everything crossing into one subgraph from this level rides one
+        # call, @requires and plain together, as Apollo's does. The exception
+        # is a prefetch that didn't answer for some node: the @requires half
+        # then runs over fewer nodes than the plain half, and two node sets
+        # can't share a fetch.
+        wanted.group_by { |d| [d.subgraph, d.requires.any? && blocked.any?] }.each do |(target, chained), deferrals|
           fetched = chained ? nodes.reject { |(node, _)| blocked.include?(node.object_id) } : nodes
           tree = Internal::Planner.field_tree(deferrals.flat_map(&:representation).uniq)
           representations = fetched.map { |(node, _)| representation(node, tree, step.type_name) }
@@ -445,7 +476,7 @@ module GraphWeaver
           if fetched.any?
             result = entities_fetch(target, step.type_name, deferrals.map(&:node), representations, operation, variables)
             entities = result.dig("data", "_entities") || []
-            Array(result["errors"]).each { |error| errors << rewrite(error, fetched) }
+            Array(result["errors"]).each { |error| errors << rewrite(error, target, fetched) }
           end
 
           fetched.each_with_index do |(node, _), index|
@@ -500,7 +531,7 @@ module GraphWeaver
 
           result = entities_fetch(subgraph, step.type_name, selections, representations, operation, variables)
           entities = result.dig("data", "_entities") || []
-          Array(result["errors"]).each { |error| errors << rewrite(error, nodes) }
+          Array(result["errors"]).each { |error| errors << rewrite(error, subgraph, nodes) }
 
           nodes.each_with_index do |(node, _), index|
             entity = entities[index]
@@ -556,7 +587,8 @@ module GraphWeaver
       # is a path into the fetch, and `locations` a position in it. Re-path
       # what can be re-pathed and drop what can't, rather than hand back a
       # line number pointing into a document that doesn't exist.
-      def rewrite(error, nodes = nil)
+      def rewrite(error, subgraph, nodes = nil)
+        error = stamp(error, subgraph)
         path = error["path"]
         return error.except("locations") unless path.is_a?(Array)
 
@@ -565,6 +597,20 @@ module GraphWeaver
         error.except("locations").merge("path" => prefix + unalias(stitched ? path[2..] : path))
       end
 
+      # Which subgraph a bubbled error came from. Every real transport stamps
+      # this and a client branches on it to tell a downstream failure from an
+      # ordinary business error, so a test written against an unstamped one
+      # passes here and breaks in front of a gateway. Apollo Router's spelling
+      # (`extensions.service`); the deprecated JS gateway says `serviceName`
+      # and adds a DOWNSTREAM_SERVICE_ERROR code, which isn't ours to invent.
+      # Whatever the subgraph's own resolver set is left alone.
+      def stamp(error, subgraph)
+        extensions = error["extensions"].is_a?(Hash) ? error["extensions"] : {}
+        return error if extensions.key?("service") || extensions.key?("serviceName")
+
+        error.merge("extensions" => extensions.merge("service" => subgraph))
+      end
+
       # The @key/@requires fields we inject are ours; an error path naming one
       # points the caller at a field no schema has.
       def unalias(path)
@@ -657,7 +703,8 @@ module GraphWeaver
         end
 
         GraphWeaver::Internal::Log.log_timed(:debug, "router -> #{name} #{tag} completed") do
-          @subgraphs.fetch(name).execute(query, variables:, operation_name:, context: @context).to_h
+          @subgraphs.fetch(name).execute(query, variables:, operation_name:,
+            context: Internal::Util.context!(@context)).to_h
         end
       end
 

data/lib/graph_weaver/testing.rb

@@ -22,7 +22,8 @@ end
 #                                                  # when it isn't the dump, or
 #                                                  # fake: for how those fabricate
 #        config.context = { current_user: }        # baseline GraphQL context
-#        config.default_mode = :fake               # untagged examples (graph_weaver/rspec)
+#        config.default_mode = :fake               # untagged examples; :live (the
+#                                                  # default) leaves your client alone
 #        config.seed = 42                          # reproducible fakes
 #        config.overrides = { "Person.name" => "Daniel" }
 #        config.list_size = 2..4
@@ -49,33 +50,43 @@ module GraphWeaver
     # What an example can run against, named by the rspec tag that selects
     # it — `it "…", graphql: :in_process` (see graph_weaver/rspec):
     #
+    #      :live        your app's own client, exactly as it is — the
+    #                   default, and how one example steps back out of
+    #                   config.default_mode
     #      :fake        fabricated, schema-correct data; no resolvers run
     #      :in_process  your resolvers, one live schema class, in-process
     #      :router      your resolvers, across a federated graph
-    CLIENT_MODES = %i[fake in_process router].freeze
+    #      :wire        your schema, served at your client's endpoint so
+    #                   your real transport runs
+    CLIENT_MODES = %i[live fake in_process router wire].freeze
 
     class Config
-      attr_accessor :overrides, :seed, :list_size, :cassette_dir, :context,
-        :record, :anonymize
-      # #schema is written plainly and read with a fallback (below), the way
-      # #router and #default_mode are read plainly and written with a check
-      attr_writer :schema
+      # How long an unbounded list fabricates when nothing names it — the
+      # starting #list_size, and the fallback under a Hash one with no
+      # `default:`.
+      DEFAULT_LIST_SIZE = (1..3).freeze
+
+      attr_accessor :overrides, :seed, :list_size, :cassette_dir, :record, :anonymize
+      attr_reader :context
+      # #schema is read with a fallback (below), the way #router and
+      # #default_mode are read plainly and written with a check
       attr_reader :router, :default_mode
 
       def initialize
         @overrides = {}
         @seed = nil
-        @list_size = 1..3
+        @list_size = DEFAULT_LIST_SIZE
         @schema = nil
         @located = nil # the committed dump, once located
+        @located_path = nil # and the path it was located at
         # not under spec/fixtures: `fixtures :all` globs that path for
         # `{**,*}/*.yml` and would try to load cassettes as ActiveRecord
         # fixtures, a subdirectory included
         @cassette_dir = "spec/cassettes"
-        # what an example with no `graphql:` tag runs against. nil leaves
+        # what an example with no `graphql:` tag runs against. :live leaves
         # GraphWeaver.client alone: swapping every example onto something
         # else is too surprising to be a default.
-        @default_mode = nil
+        @default_mode = :live
         # the GraphQL context every :in_process / :router example starts
         # from; graphql_context merges onto it
         @context = {}
@@ -95,7 +106,26 @@ module GraphWeaver
         # the dump memoizes separately: explicit_schema has to stay honest
         # about whether anyone set one, since :in_process won't run a dump's
         # resolver-less types as if they were the live class
-        @schema || (@located ||= GraphWeaver::SchemaLoader.locate)
+        return @schema if @schema
+
+        # keyed on the path it came from, so schema_path= and root= aren't
+        # invisible — a memo that outlived them faked the previous schema's
+        # shapes with nothing said. Worth keeping: loading a real
+        # introspection dump is ~100ms and every fake asks.
+        path = GraphWeaver::SchemaLoader.locate_path
+        return unless path
+
+        @located = GraphWeaver::SchemaLoader.load(path) unless @located_path == path
+        @located_path = path
+        @located
+      end
+
+      # What every mode derives from — suite setup, like #context and for the
+      # same reason: an example's clients are built before any group `before`
+      # runs, so one set there is read too late (see {refuse_late!}).
+      def schema=(schema)
+        refuse_late!("config.schema", "graphql_in_process(MySchema) / graphql_fake(schema: MySchema)")
+        @schema = schema
       end
 
       # What's been set, without falling back to the dump — so validating
@@ -103,11 +133,28 @@ module GraphWeaver
       # that never asks for one.
       def explicit_schema = @schema
 
+      # The baseline every example starts from — suite setup, not something an
+      # example changes out from under itself: an example's clients are built
+      # before any group hook runs (a :wire example's, before its endpoints
+      # are stubbed), so a `before { config.context = … }` used to be read too
+      # late and silently never reach a resolver.
+      def context=(values)
+        if GraphWeaver::Internal::TestClients.installed?
+          raise GraphWeaver::Error, "config.context is the baseline every example starts from, " \
+            "read when that example's clients are built — so setting it from inside an example " \
+            "would never reach a resolver. Say it for this example with " \
+            "graphql_context(current_user: …), or for the suite in GraphWeaver::Testing.configure " \
+            "(an around hook works too — it wraps the setup a tag does)."
+        end
+
+        @context = values
+      end
+
       def default_mode=(mode)
-        unless mode.nil? || CLIENT_MODES.include?(mode)
+        unless CLIENT_MODES.include?(mode)
           raise ArgumentError,
-            "default_mode: must be one of #{CLIENT_MODES.inspect} (or nil to leave " \
-            "GraphWeaver.client alone), got #{mode.inspect}"
+            "default_mode: must be one of #{CLIENT_MODES.inspect}, got #{mode.inspect} — " \
+            ":live leaves GraphWeaver.client exactly as it is, and is the default"
         end
 
         @default_mode = mode
@@ -122,6 +169,7 @@ module GraphWeaver
       # have to restate where the supergraph is. `fake:` says how those
       # fabricate; graphql_router(fake: …) says it for one example.
       def router=(arguments)
+        refuse_late!("config.router", "graphql_router(fake: …)")
         unless arguments.nil? || arguments.is_a?(Hash)
           raise ArgumentError, "router: must be the arguments to build one, e.g. " \
             "{ supergraph: \"supergraph.graphql\" } or { subgraphs: { \"reviews\" => :fake } }, " \
@@ -137,56 +185,113 @@ module GraphWeaver
         raise ArgumentError, "router: doesn't take #{unknown.join(", ")}" if unknown.any?
 
         @router = arguments
-        @built_router = nil
+        @built_routers = nil
       end
 
-      # Built once: parsing the supergraph is setup, not per-example work.
-      # #context is settable, so an example that runs as someone else sets
-      # that rather than rebuilding — the rspec hook resets it each time.
-      def built_router
-        @built_router ||= Router.new(
-          supergraph: supergraph!,
+      # The router `graph` plans against, built once per supergraph: parsing
+      # one is setup, not per-example work, and two graphs naming the same
+      # supergraph are one plan. #context is settable, so an example that runs
+      # as someone else sets that rather than rebuilding.
+      def built_router(graph = nil)
+        source = supergraph!(graph)
+        @built_routers ||= {}
+        @built_routers[source] ||= Router.new(
+          supergraph: source,
           subgraphs: @router && @router[:subgraphs],
           fake: (@router && @router[:fake]) || {},
         )
       end
 
-      # The composed supergraph :router plans against — named, or the
-      # conventional dump when that's what it is. A client can't supply
-      # one: its schema is the API schema a router serves, with the
+      # Whether `graph` has a composed supergraph to plan against — what
+      # decides whether :wire serves the router or the live schema class,
+      # the same question :router and :in_process each answer for themselves.
+      def supergraph?(graph = nil) = !supergraph_for(graph).nil?
+
+      # The composed supergraph `graph` plans against, or the refusal saying
+      # what was looked for. Per graph, because a graph that is in no
+      # supergraph must be refused by name rather than routed into someone
+      # else's.
+      private def supergraph!(graph = nil)
+        supergraph_for(graph) ||
+          raise(GraphWeaver::Error, supergraph_advice(graph, GraphWeaver::SchemaLoader.locate_path))
+      end
+
+      # The lookup on its own, nil when there is none — so asking the
+      # question doesn't build an error. Every GraphWeaver::Error writes a
+      # warn line as it is constructed, and a predicate that raised to say
+      # "no" put a refusal that never happened in the log of every :wire
+      # example. The one that graph names, else config.router[:supergraph],
+      # else the conventional dump when that's what it is. A client can't
+      # supply one — its schema is the API schema a router serves, with the
       # @join__* routing table stripped out.
-      private def supergraph!
+      private def supergraph_for(graph)
+        # named_schema?, so a graph that declared no schema of its own falls
+        # through to config.router rather than past it to the conventional dump
+        named = (graph.supergraph if graph&.named_schema?)
+        return named if named
         return @router[:supergraph] if @router&.key?(:supergraph)
 
         path = GraphWeaver::SchemaLoader.locate_path
-        return path if path && supergraph?(path)
+        path if path && GraphWeaver::Internal::Util.composed?(path)
+      end
 
-        raise GraphWeaver::Error, ":router needs the composed supergraph SDL — a client's schema " \
-          "is the API schema the router serves, with the @join__* routing table stripped out, so " \
-          "the supergraph has to be named. #{path ? "#{path} carries no @join__* markers" : "Nothing on disk at #{GraphWeaver.schema_path}"}. " \
-          "Set GraphWeaver::Testing.config.router = { supergraph: \"supergraph.graphql\" }."
+      # what to do about it, which differs by who asked: a graph in no
+      # supergraph is one schema, so the tag for one schema is the answer;
+      # the app-wide ask is told the two app-wide places to name one
+      private def supergraph_advice(graph, path)
+        if graph&.name
+          ":router plans a query across a composed supergraph, and graph #{graph.name.inspect} " \
+            "is in none — tag the example graphql: :in_process, which runs one schema class's " \
+            "resolvers, or name the supergraph where the graph is declared: " \
+            "GraphWeaver.graph(#{graph.name.inspect}) { schema \"supergraph.graphql\" }."
+        else
+          ":router needs the composed supergraph SDL — a client's schema is the API schema the " \
+            "router serves, with the @join__* routing table stripped out, so the supergraph has " \
+            "to be named. #{path ? "#{path} carries no @join__* markers" : "Nothing on disk at #{GraphWeaver.schema_path}"}. " \
+            "Set GraphWeaver::Testing.config.router = { supergraph: \"supergraph.graphql\" }, or " \
+            "name it where the graph is declared: GraphWeaver.graph(:api) { schema \"supergraph.graphql\" }."
+        end
       end
 
       # The live schema class :in_process runs when the example didn't name
-      # one — config.schema if that is a class, else whatever the app's own
-      # client already runs in-process. Only a live class has resolvers, so
-      # there is nothing else to fall back to: a dump is type information.
-      def schema_class!
-        # explicit_schema, not schema: the latter falls back to the committed
-        # dump, which loads as an anonymous GraphQL::Schema subclass — runnable
-        # by every test that matters, and holding not one resolver.
-        runnable(explicit_schema) || GraphWeaver::Internal::Util.live_schema ||
-          raise(GraphWeaver::Error, ":in_process runs your resolvers, so it needs the live " \
-            "GraphQL::Schema class — and 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.")
-      end
-
-      # The schema everything else derives from: the one you set, else the
-      # committed dump, else the schema the app's client talks to.
-      def reference_schema!
-        found = schema || (GraphWeaver.client.schema if GraphWeaver.client.respond_to?(:schema))
+      # one — config.schema if that is a class, else the one `graph` names,
+      # else whatever the app's own client already runs in-process. Only a
+      # live class has resolvers, so there is nothing else to fall back to:
+      # a dump is type information.
+      def schema_class!(graph = nil)
+        # a named graph is told how to name its own class; the app-wide answer
+        # is told the two app-wide ways to say it
+        schema_class_for(graph) || raise(GraphWeaver::Error, ":in_process runs your resolvers, " \
+          "so it needs the live GraphQL::Schema class — and #{schema_class_advice(graph)}")
+      end
+
+      # Whether `graph` has a live schema class at all — what decides, with
+      # #supergraph?, which of the three things :wire serves. Asked without
+      # building an error, for the reason {supergraph_for} gives.
+      def schema_class?(graph = nil) = !schema_class_for(graph).nil?
+
+      # The schema everything else derives from: the one you set, else the one
+      # `graph` names — the schema its generated code was checked against —
+      # else the one this app's single graph names, else the committed dump,
+      # else the schema the app's client talks to.
+      def reference_schema!(graph = nil)
+        return explicit_schema if explicit_schema
+        return graph.schema if graph&.named_schema?
+
+        declared = GraphWeaver.graphs
+        # more than one graph and nothing named: the honest answer varies per
+        # example, and picking the first would fake one schema's shapes at
+        # another's module — a wrong answer that looks authoritative
+        if declared.size > 1
+          raise GraphWeaver::Error, "this app has #{declared.size} graphs " \
+            "(#{declared.map { |graph| graph.name.inspect }.join(", ")}), so which schema to fake " \
+            "against varies per example — name it: graphql_fake(schema: MySchema) or " \
+            "graphql_in_process(MySchema). Set GraphWeaver::Testing.config.schema only if the whole " \
+            "suite means one of them."
+        end
+
+        found = (declared.first.schema if declared.first.named_schema?)
+        found ||= schema || (GraphWeaver.client.schema if GraphWeaver.client.respond_to?(:schema))
         return found if found
 
         raise GraphWeaver::Error, "no schema to run against — GraphWeaver.client isn't set, " \
@@ -196,18 +301,50 @@ module GraphWeaver
 
       private
 
+      # explicit_schema, not schema: the latter falls back to the committed
+      # dump, which loads as an anonymous GraphQL::Schema subclass — runnable
+      # by every test that matters, and holding not one resolver.
+      def schema_class_for(graph)
+        runnable(explicit_schema) || graph&.live_schema || GraphWeaver::Internal::Util.live_schema
+      end
+
+      # One rule for every suite-setup setting: say it at load, or in an
+      # `around` — a plain `before` is too late, because the tag builds (and
+      # under :wire serves) this example's clients in a `before` of its own,
+      # and rspec runs that one first. Silence there is the expensive
+      # outcome: the example passes against whatever the tag already picked.
+      def refuse_late!(setting, per_example)
+        return unless GraphWeaver::Internal::TestClients.built?
+
+        raise GraphWeaver::Error, "#{setting} is read when this example's clients are built, and " \
+          "the graphql: tag already built them — it does that in a `before` hook of its own, which " \
+          "rspec runs before yours, so setting it now reaches nothing. Say it for the suite in " \
+          "GraphWeaver::Testing.configure, or in an `around` hook, which wraps the tag's setup; " \
+          "say it for one example in the helper (#{per_example})."
+      end
+
+      # what to do about it, which differs by who asked: a graph names its
+      # own class where it is declared, the app names one for the suite
+      def schema_class_advice(graph)
+        if graph&.name
+          "graph #{graph.name.inspect} names " \
+            "#{graph.named_schema? ? "type information, not a class" : "no schema of its own"}. " \
+            "Declare it with the class: GraphWeaver.graph(#{graph.name.inspect}) " \
+            "{ schema -> { MySchema } }."
+        else
+          "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."
+        end
+      end
+
       # config.schema doubles as the :in_process class when it is one — but a
       # dump has no resolvers, so it can only ever be type information.
       def runnable(schema)
         schema if schema.is_a?(Class) && schema <= GraphQL::Schema
       end
 
-      def supergraph?(source)
-        GraphWeaver::SchemaLoader.routing_table(source)
-        true
-      rescue GraphWeaver::Error
-        false
-      end
     end
 
     class << self
@@ -217,9 +354,13 @@ module GraphWeaver
 
       def configure
         yield config
-        # a typo'd override key pins nothing and the test still passes, so
-        # catch it here — while the block that set it is still on the stack
-        Internal::Overrides.validate!(config.explicit_schema, config.overrides) if config.explicit_schema
+        # a typo'd override or list_size key names nothing and the test still
+        # passes, so catch it here — while the block that set it is still on
+        # the stack
+        if (schema = config.explicit_schema)
+          Internal::Overrides.validate!(schema, config.overrides)
+          Internal::Overrides.validate_list_size!(schema, config.list_size)
+        end
         config
       end
 
@@ -249,5 +390,6 @@ require_relative "testing/fake_client"
 require_relative "testing/fake_subgraph"
 require_relative "testing/failure"
 require_relative "testing/cassette"
+require_relative "testing/endpoint"
 require_relative "testing/router"
 require_relative "testing/coverage"

data/lib/graph_weaver/transport/faraday.rb

@@ -7,9 +7,9 @@ require_relative "../transport"
 
 module GraphWeaver
   class Transport
-    # Faraday-backed transport. Opt-in (faraday is not a hard dependency):
-    #
-    #      require "graph_weaver/transport/faraday"
+    # Faraday-backed transport. Opt-in — faraday is not a hard dependency, and
+    # naming this constant is what loads it (Transport autoloads this file), so
+    # an app that never mentions it never pays for it:
     #
     #      # simplest: build a default connection from a url
     #      GraphWeaver::Transport::Faraday.new("https://api.example.com/graphql")
@@ -30,6 +30,7 @@ module GraphWeaver
       )
 
       def initialize(url_or_connection, headers: {}, open_timeout: nil, read_timeout: nil, &block)
+        @dynamic = {} # a prebuilt connection owns its headers; nothing is held back
         @connection = case url_or_connection
         when ::Faraday::Connection
           # a prebuilt connection carries its own headers/middleware/
@@ -41,6 +42,13 @@ module GraphWeaver
 
           url_or_connection
         else
+          # Faraday sets connection headers once, stringifying as it goes, so
+          # a callable there would ship as "#<Proc:0x…>". Held back and
+          # resolved per request in #post instead — a rotating token has to
+          # mean the same thing on both bundled transports.
+          @dynamic = headers.select { |_, value| value.respond_to?(:call) }
+          headers = headers.reject { |name, _| @dynamic.key?(name) }
+
           # Faraday appends the default adapter when the block doesn't set
           # one. Our defaults go on the connection so ours is the
           # User-Agent, not Faraday's stock one; caller headers still win.
@@ -48,7 +56,10 @@ module GraphWeaver
           # otherwise inherit net/http's 60s/60s.
           ::Faraday.new(
             url: url_or_connection,
-            headers: DEFAULT_HEADERS.merge(headers),
+            # to_s for the same reason Transport::HTTP does it — net/http calls
+            # #strip on a header value, so an Integer id raised from inside the
+            # adapter, naming neither graph_weaver nor the header
+            headers: Transport.default_headers.merge(headers).transform_values(&:to_s),
             request: {
               open_timeout: open_timeout || DEFAULT_OPEN_TIMEOUT,
               read_timeout: read_timeout || DEFAULT_READ_TIMEOUT,
@@ -56,21 +67,43 @@ module GraphWeaver
             &block
           )
         end
-        @url = @connection.url_prefix.to_s
+        @url = endpoint_url(@connection)
 
         # which adapter got picked decides socket reuse — Faraday's
         # default net_http one opens a connection per request. Naming it
         # is the cheapest way to make that discoverable.
-        GraphWeaver::Internal::Log.log(:info) { "faraday transport #{@url} (adapter: #{@connection.builder.adapter})" }
+        GraphWeaver::Internal::Log.log(:info) { "faraday transport #{safe_url} (adapter: #{@connection.builder.adapter})" }
       end
 
       private
 
+      # Where requests actually go. Faraday moves a url's query string into
+      # the connection's default params and strips it from url_prefix, so
+      # url_prefix alone names an endpoint nothing posts to — and #url is what
+      # `graphql: :wire` stubs and what the boot log line prints. Faraday's own
+      # encoder, not URI.encode_www_form: only it spells an Array a[]=1&a[]=2
+      # and a Hash a[b]=c the way the request will.
+      def endpoint_url(connection)
+        connection.build_exclusive_url(nil, connection.params).to_s
+      end
+
       sig { override.params(body: String).returns(T::Array[T.untyped]) }
       def post(body)
         response = @connection.post do |request|
-          # a prebuilt connection owns its headers — only fill the blanks
-          DEFAULT_HEADERS.each { |name, value| request.headers[name] ||= value }
+          # a prebuilt connection owns its headers — only fill the blanks.
+          # Faraday pre-fills its stock User-Agent, so that one is never blank
+          # and graph_weaver's traffic attributed to Faraday; a connection that
+          # never chose one isn't expressing a preference.
+          request.headers.delete("User-Agent") if request.headers["User-Agent"] == ::Faraday::Connection::USER_AGENT
+          Transport.default_headers.each { |name, value| request.headers[name] ||= value }
+
+          # asked per request, so a token that expires is fetched now; nil
+          # drops the header, which is how an optional one says "not this time"
+          @dynamic.each do |name, value|
+            resolved = value.call
+            resolved.nil? ? request.headers.delete(name) : request.headers[name] = resolved.to_s
+          end
+
           request.body = body
         end