graph_weaver 0.7.4 → 0.7.6

data/lib/graph_weaver/internal.rb

@@ -18,6 +18,11 @@ module GraphWeaver
   # lexical scope, so a private constant would be unreachable from exactly
   # the files that need it. The name and the surface lock carry the rule.
   module Internal
+    # The wire value the member register_enum fallback: true adds to a
+    # generated enum serializes to. The GraphQL spec reserves a leading `__`,
+    # so no schema can declare a value that collides with it.
+    ENUM_FALLBACK_WIRE = "__other__"
+
     # Odds and ends several files share. Each is here because more than one
     # caller needs it, not because it belongs together with the others.
     module Util
@@ -50,6 +55,18 @@ module GraphWeaver
         # "a" or "an" for a word an error message is about to name.
         def article(word) = word.downcase.start_with?(/[aeiou]/) ? "an" : "a"
 
+        # how many entries a message names before it says "and N more"
+        SAMPLE = 5
+        private_constant :SAMPLE
+
+        # A list a message names inline, held to a readable length — a wall
+        # of schema coordinates says less than the first few and a count.
+        def sample(list)
+          return list.join(", ") if list.size <= SAMPLE
+
+          "#{list.first(SAMPLE).join(", ")} and #{list.size - SAMPLE} more"
+        end
+
         # The module a .graphql file generates, and the basename of the file
         # it generates into: the camelized file name plus the operation's own
         # word. Every run of non-alphanumerics in the name is a word boundary,
@@ -226,14 +243,14 @@ module GraphWeaver
             "or cache one: GraphWeaver.new(url, cache: true).schema"
         end
 
-        # The graphql-ruby schema class the app default executes against,
-        # when it runs in-process — a Client wrapping one, or the class in
-        # the slot bare. nil for every network client. Not memoized: in dev
-        # the class object is replaced on reload.
-        def live_schema
+        # The graphql-ruby schema class a client executes against, when it
+        # runs in-process — a Client wrapping one, or the class in the slot
+        # bare. nil for every network client. Defaults to the app's own, and
+        # a graph passes its client. Not memoized: in dev the class object is
+        # replaced on reload.
+        def live_schema(client = GraphWeaver.client)
           # through #transport, not #schema: a url client's #schema
           # introspects, so asking it would answer over the network
-          client = GraphWeaver.client
           target = client.is_a?(Client) ? client.transport : client
           target = target.schema if target.is_a?(InProcess)
           target if target.is_a?(Class) && target <= GraphQL::Schema

data/lib/graph_weaver/log_subscriber.rb

@@ -14,17 +14,20 @@ module GraphWeaver
   #      GraphWeaver PersonQuery (12.3ms) ok
   #      GraphWeaver PersonQuery (8.1ms) errors [THROTTLED]
   #      GraphWeaver PersonQuery (31.2ms) failed GraphWeaver::TransportError
+  #      GraphWeaver PersonQuery (44.0ms) failed GraphWeaver::CastError
   #      GraphWeaver billing/InvoicesQuery (12.3ms) ok
   #
   # Attached by the railtie wherever ActiveSupport is, and fed by the
   # instrumenter it sets. Requires ActiveSupport — `require` this yourself
   # only if you subscribe by hand.
   #
-  # **One rule decides which line you get: the summary is info, the wire is
-  # debug.** This is the only GraphWeaver line at info, so a production log
-  # gets one per operation and nothing that could carry PII; turning
-  # GraphWeaver.logger up to debug adds the query, the variables and the
-  # response *beneath* it rather than repeating it.
+  # **One rule decides which line you get: the operation is info, the
+  # attempt is debug.** The info line is one CALL of a generated module, so
+  # it says what the caller got — a cast that raised reads `failed`, and a
+  # test mode's stand-in gets a line like every other client. A production
+  # log gets one per operation and nothing that could carry PII; turning
+  # GraphWeaver.logger up to debug adds each attempt, with the url, the HTTP
+  # status and which retry it was, beneath it.
   #
   # It writes through GraphWeaver.logger rather than Rails.logger, so
   # `GraphWeaver.logger = nil` — the documented way to silence the gem —
@@ -33,17 +36,10 @@ module GraphWeaver
   class LogSubscriber < ActiveSupport::LogSubscriber
     # attach_to(:graph_weaver) subscribes "#{method}.graph_weaver" and
     # ActiveSupport::Subscriber#call dispatches on the name up to the first
-    # dot — so this method name is EXECUTE_EVENT's first half, both ways.
-    def execute(event)
-      payload = event.payload
+    # dot — so these method names are the events' first halves, both ways.
+    def operation(event) = write(:info, event)
 
-      GraphWeaver::Internal::Log.log(:info) do
-        # duration_ms is the instrumenter's own measurement; event.duration
-        # covers a subscriber attached to something that didn't set it
-        ms = payload[:duration_ms] || event.duration
-        "GraphWeaver #{subject(payload)} (#{format("%.1f", ms)}ms) #{outcome(payload)}"
-      end
-    end
+    def execute(event) = write(:debug, event)
 
     # GraphWeaver's logger, not Rails' — LogSubscriber#call skips a
     # subscriber whose logger is nil, which is what makes the gem's own
@@ -52,7 +48,20 @@ module GraphWeaver
 
     private
 
-    # What ran: the operation, prefixed by its graph when the request carried
+    # One shape for both, so the attempt beneath an operation reads as the
+    # same line rather than a second format to learn.
+    def write(level, event)
+      payload = event.payload
+
+      GraphWeaver::Internal::Log.log(level) do
+        # duration_ms is the instrumenter's own measurement; event.duration
+        # covers a subscriber attached to something that didn't set it
+        ms = payload[:duration_ms] || event.duration
+        "GraphWeaver #{subject(payload)} (#{format("%.1f", ms)}ms) #{outcome(payload)}"
+      end
+    end
+
+    # What ran: the operation, prefixed by its graph when the payload names
     # one — an app with several graphs reads `billing/InvoicesQuery` without
     # a second line shape to learn, and one with a single graph never sees it.
     def subject(payload)
@@ -61,7 +70,8 @@ module GraphWeaver
     end
 
     # status, then whatever narrows it: the error class, the reason an alert
-    # groups by, and which attempt this was when a Retry is in the stack.
+    # groups by, and — on a debug attempt line — which try this was. The last
+    # two are attempt facts, so only the debug line ever carries them.
     def outcome(payload)
       parts = [payload[:status], payload[:error]]
       # the GraphQL code, or the HTTP status where the request never got one

data/lib/graph_weaver/logging.rb

@@ -43,19 +43,22 @@ module GraphWeaver
       @filter_parameters = filters
     end
 
-    # One callable wrapping every request GraphWeaver makes — over the
-    # wire or in-process — so an APM can time it and count errors. A
-    # no-op until you set one (Rails sets this one for you):
+    # One callable wrapping every call GraphWeaver makes — one generated
+    # module's execute, and every request under it, over the wire or
+    # in-process — so an APM can time it and count errors. A no-op until
+    # you set one (Rails sets this one for you):
     #
     #      GraphWeaver.instrumenter = lambda do |event, payload, &block|
     #        ActiveSupport::Notifications.instrument(event, payload, &block)
     #      end
     #
-    # It must call the block and return its value. The only event today is
-    # EXECUTE_EVENT; its payload is the contract in docs/logging.md —
-    # :operation, :client, :kind, :status, :duration_ms, :graph always;
-    # :url/:http_status over the wire, :schema in-process, :error/:code on a
-    # failure, :retries when a Retry wrapped it. Never the query text or the
+    # It must call the block and return its value. Two events, and their
+    # payloads are the contract in docs/logging.md: OPERATION_EVENT is one
+    # call of a generated module (:operation, :module, :graph, :kind,
+    # :client, :status, :duration_ms), and EXECUTE_EVENT is one request
+    # inside it (:url/:http_status over the wire, :schema in-process,
+    # :retries under a Retry). Both add :error on a raise and :code on a
+    # response that carried GraphQL errors. Never the query text or the
     # variables: the payload fans out to subscribers that know none of the
     # filtering rules, so PII belongs at debug on the logger, where the
     # level gates it and filter_parameters scrubs it.
@@ -101,7 +104,11 @@ module GraphWeaver
         # about the key the value arrived under, so it reads a filtered key one
         # level in as safe; this scrubs at every depth, like #value. The key is
         # optional because a coercer refusing a value hasn't been told one.
-        def shown(raw, key = nil) = filtered?(key) ? FILTERED : cap(value(key, raw).inspect)
+        def shown(raw, key = nil) = filtered?(key) ? FILTERED : cap(spell(value(key, raw)))
+
+        # How a value reads inside a sentence. inspect, except that
+        # BigDecimal#inspect is scientific ("0.25e1" for the 2.5 a caller wrote).
+        def spell(value) = defined?(BigDecimal) && value.is_a?(BigDecimal) ? value.to_s("F") : value.inspect
 
         # A short server-chosen string the library republishes inside its own
         # text — the APM's :code, the [CODE] in the one line info writes, a
@@ -133,14 +140,24 @@ module GraphWeaver
 
   self.filter_parameters = DEFAULT_FILTER_PARAMETERS
 
-  # The one instrumentation event: a single GraphQL request, start to
-  # parsed response, whichever client slot served it. `<event>.<namespace>`
-  # is how every notification in this ecosystem is spelled
-  # (sql.active_record, execute_multiplex.graphql) — it's what
-  # ActiveSupport::LogSubscriber.attach_to and an APM's namespace routing
-  # key on, so a backwards name made both of them a puzzle.
+  # One GraphQL REQUEST, start to parsed response, whichever client slot
+  # served it — one attempt, so a call a Retry made three goes at is three
+  # of these. `<event>.<namespace>` is how every notification in this
+  # ecosystem is spelled (sql.active_record, execute_multiplex.graphql) —
+  # it's what ActiveSupport::LogSubscriber.attach_to and an APM's namespace
+  # routing key on, so a backwards name made both of them a puzzle.
   EXECUTE_EVENT = "execute.graph_weaver"
 
+  # One CALL of a generated module's execute/execute!: the request it makes,
+  # every retry and backoff beneath it, and the cast into the typed structs.
+  # One or more EXECUTE_EVENTs nest inside it.
+  #
+  # It says what the CALLER got, which a request can't: a CastError is raised
+  # after the response is back, so the request closed :ok while the app saw a
+  # failure. And it fires at the module seam, which every client slot passes
+  # through — a fake, the test router and a cassette report here too.
+  OPERATION_EVENT = "operation.graph_weaver"
+
   module Internal
     # The emitting half of the narration the three accessors above
     # configure. Setting a logger is API; writing to it is not, and the
@@ -170,81 +187,39 @@ module GraphWeaver
           result
         end
 
-        # Wrap the block in the instrumenter, if one is set. The caller
-        # supplies what only it knows (:url, :schema, :client); this fills
-        # in the half every path shares — how it ended, how long it took,
-        # what a Retry had already spent — so one subscriber reads one
-        # shape whichever client slot served the request.
-        def instrument(event, payload)
-          hook = GraphWeaver.instrumenter
-          return yield unless hook
+        # Wrap one REQUEST in the instrumenter, if one is set. The caller
+        # supplies what only it knows (:url, :schema, :client); this adds the
+        # attempt facts — the graph in scope, what a Retry had already spent —
+        # so one subscriber reads one shape whichever client slot served it.
+        def instrument_request(payload, &block)
+          return yield unless GraphWeaver.instrumenter
 
-          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           retries = Thread.current[RETRIES]
           payload[:retries] = retries if retries
           payload[:graph] = Thread.current[GRAPH]
-          # pessimistic, so :status is set even for what a rescue can't
-          # see — an Interrupt, a killed thread — and never silently absent
-          payload[:status] = :failed
 
           # One dispatch labels one request. Whatever THIS request reaches —
           # a resolver serving it that calls out — is a request of its own,
           # and the caller's graph would be a wrong label on it.
-          with_graph(nil) do
-            hook.call(event, payload) do
-              result = yield
-              errors = response_errors(result)
-              if errors.empty?
-                payload[:status] = :ok
-              else
-                payload[:status] = :errors
-                code = errors.grep(Hash).filter_map { |e| GraphWeaver::GraphQLError.from_h(e).code }.first
-                payload[:code] = Redact.tag(code)
-              end
-              result
-            rescue => e
-              payload[:error] = e.class.name
-              # :code stays the GraphQL error code and nothing else — it used
-              # to hold a ServerError's status here, so one tag carried two
-              # dimensions ("THROTTLED" and 429). The number is :http_status.
-              raise
-            ensure
-              payload[:duration_ms] = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(2)
-            end
-          end
+          with_graph(nil) { measure(GraphWeaver::EXECUTE_EVENT, payload, &block) }
         end
 
-        # What a Retry has already spent, read by the attempt it is about
-        # to make. A dynamic extent rather than a global: the count is only
-        # visible while the call it describes is on the stack, so a client
-        # that never reaches instrument can't leave a stale one behind.
-        def with_retries(count)
-          return yield unless GraphWeaver.instrumenter
-
-          previous = Thread.current[RETRIES]
-          Thread.current[RETRIES] = count
-          begin
-            yield
-          ensure
-            Thread.current[RETRIES] = previous
-          end
+        # Wrap one CALL of a generated module: the request under it and the
+        # cast that follows. The caller names :graph here rather than reading
+        # it out of the fiber-local, because it IS the module that set it —
+        # and it stays set, so the request below wears the same label.
+        def instrument_operation(payload, &block)
+          measure(GraphWeaver::OPERATION_EVENT, payload, &block)
         end
 
-        # The graph a generated module is dispatching, read by the request it
-        # is about to make. Same dynamic extent as with_retries, for the same
-        # reason — and instrument clears it for the duration of the request it
-        # labels, so exactly one request wears the label.
-        def with_graph(name)
-          return yield unless GraphWeaver.instrumenter
+        # What a Retry has already spent, read by the attempt it is about
+        # to make.
+        def with_retries(count, &block) = during(RETRIES, count, &block)
 
-          previous = Thread.current[GRAPH]
-          Thread.current[GRAPH] = name
-          begin
-            yield
-          ensure
-            Thread.current[GRAPH] = previous
-          end
-        end
+        # The graph a generated module is dispatching, read by the request it
+        # is about to make — and instrument clears it for the duration of the
+        # request it labels, so exactly one request wears the label.
+        def with_graph(name, &block) = during(GRAPH, name, &block)
 
         # The variables as one JSON line for a log: filtered, and unable to
         # raise. A value with no JSON form (NaN, binary) is the caller's bug
@@ -278,13 +253,71 @@ module GraphWeaver
 
         private
 
-        # The GraphQL errors a response carries, whatever answered it — a
-        # Hash from a transport, a graphql-ruby Result in-process, a fake.
-        # Never raises: an instrumenter that decides which exception a
-        # caller sees is worse than a missing tag.
+        # One fiber-local, set for the length of one call. A dynamic extent
+        # rather than a global: the value is only visible while the call it
+        # describes is on the stack, so a client that never reaches instrument
+        # can't leave a stale one behind.
+        def during(key, value)
+          return yield unless GraphWeaver.instrumenter
+
+          previous = Thread.current[key]
+          Thread.current[key] = value
+          begin
+            yield
+          ensure
+            Thread.current[key] = previous
+          end
+        end
+
+        # The half both events share: run the block inside the hook, and
+        # record how it ended, the code an alert groups by, and how long it
+        # took — every one of them before the hook's block returns, so a
+        # subscriber reads a complete payload.
+        def measure(event, payload)
+          hook = GraphWeaver.instrumenter
+          return yield unless hook
+
+          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          # pessimistic, so :status is set even for what a rescue can't
+          # see — an Interrupt, a killed thread — and never silently absent
+          payload[:status] = :failed
+
+          hook.call(event, payload) do
+            result = yield
+            errors = response_errors(result)
+            if errors.empty?
+              payload[:status] = :ok
+            else
+              payload[:status] = :errors
+              code = errors.grep(GraphWeaver::GraphQLError).filter_map(&:code).first
+              payload[:code] = Redact.tag(code)
+            end
+            result
+          rescue => e
+            payload[:error] = e.class.name
+            # :code stays the GraphQL error code and nothing else — it used
+            # to hold a ServerError's status here, so one tag carried two
+            # dimensions ("THROTTLED" and 429). The number is :http_status.
+            raise
+          ensure
+            payload[:duration_ms] = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(2)
+          end
+        end
+
+        # The GraphQL errors a result carries, whatever answered it — a Hash
+        # from a transport, a graphql-ruby Result in-process, a fake, or the
+        # typed Response a generated cast built. A Hash becomes a GraphQLError
+        # so one reading answers for :code whichever arrived; anything else in
+        # the list is left as it came, since its presence alone already means
+        # the response carried errors. Never raises: an instrumenter that
+        # decides which exception a caller sees is worse than a missing tag.
         def response_errors(result)
+          return result.errors if result.is_a?(GraphWeaver::Response)
+
           errors = result.to_h["errors"] if result.respond_to?(:to_h)
-          errors.is_a?(Array) ? errors : []
+          return [] unless errors.is_a?(Array)
+
+          errors.map { |e| e.is_a?(Hash) ? GraphWeaver::GraphQLError.from_h(e) : e }
         rescue StandardError
           []
         end

data/lib/graph_weaver/parsing.rb

@@ -7,9 +7,9 @@ require_relative "codegen"
 require_relative "internal"
 
 module GraphWeaver
-  # Anything that holds a schema parses against it. That's a Client, an
-  # InProcess wrapper, a FakeClient, and the test Router — each of which
-  # already has the two things parsing needs, a schema to check the query
+  # Anything that holds a schema parses and checks against it. That's a
+  # Client, an InProcess wrapper, a FakeClient, and the test Router — each of
+  # which already has the two things parsing needs, a schema to check the query
   # against and a client for the module to run on:
   #
   #      DashboardQuery = router.parse("query { me { username } }")
@@ -31,6 +31,35 @@ module GraphWeaver
       GraphWeaver.parse(schema: T.unsafe(self).schema, query:, name:, client: self)
     end
 
+    # Does this query validate? The string form of GraphWeaver.check_queries,
+    # answering with the same JSON-ready hashes — `message`, `line`, `column`,
+    # plus `subgraphs` where a supergraph brands them — so an empty array means
+    # it validates:
+    #
+    #      client.check_query("query { viewer { login } }")   # => []
+    #      client.check_query("query { viewer { lgoin } }")
+    #      # => [{ "message" => "Field 'lgoin' doesn't exist on type 'User'",
+    #      #      "line" => 1, "column" => 17 }]
+    #
+    # Checked against this object's own schema — what `execute` would run
+    # against — so a url client introspects on first use as it always does, and
+    # nothing re-introspects the way check_queries defaults to. That is why it
+    # lives here: inside an example `GraphWeaver.client` is a fake, an InProcess
+    # or the test router, and each of those holds the schema the question is
+    # about. An unparseable source is an entry like any other; nothing here
+    # raises for a bad query. Shared fragments are inlined from fragments: the
+    # same way every other door inlines them.
+    def check_query(source, fragments: GraphWeaver.fragments_paths)
+      # a dump-backed Client can brand each error with the subgraph it is
+      # about; nothing else in the slot has a file behind its schema
+      holder = T.unsafe(self)
+      dump = holder.schema_source if holder.respond_to?(:schema_source)
+      GraphWeaver::Internal::QueryCheck.errors(
+        holder.schema, source, GraphWeaver::Codegen.load_fragments(fragments),
+        GraphWeaver::Internal::QueryCheck.routing_table_for(dump),
+      )
+    end
+
     # Parse every query in a directory (subdirectories included) into typed
     # modules, named like generation would name them — the no-build-step
     # analog of generate! + load_generated!:

data/lib/graph_weaver/query_module.rb

@@ -7,8 +7,6 @@ require_relative "internal"
 require_relative "internal/test_clients"
 
 module GraphWeaver
-  # Called by generated code — not semver'd for direct use.
-  #
   # Runtime for generated query modules: the client plumbing, which is the
   # one part of a generated module that carries no per-query type
   # information — every module's copy was identical. `extend
@@ -16,6 +14,13 @@ module GraphWeaver
   # stay generated, since their sigs are the query's types and those are the
   # point.
   #
+  # It is also the type every generated module satisfies, so code that takes
+  # any of them says `GraphWeaver::QueryModule` and reads `query_string` /
+  # `operation_name` with a sig behind each — rather than `const_get(:QUERY)`
+  # on a Module, which is what rubocop-sorbet forbids (ConstantsFromStrings,
+  # and ForbidTUnsafe for the T.unsafe that gets around it). Those readers
+  # and `client` are the supported surface; the rest is generated code's.
+  #
   # Resolution order, per the docs: per call → a test mode's stand-in
   # (Internal::TestClients) → the client the module's graph names →
   # `GraphWeaver.client`. A module has no fifth slot you can set: a parsed
@@ -32,6 +37,18 @@ module GraphWeaver
       @client || default_client
     end
 
+    # The operation, verbatim — what goes on the wire as `query`.
+    sig { returns(String) }
+    def query_string
+      T.unsafe(self).const_get(:QUERY)
+    end
+
+    # What goes on the wire as `operationName`; nil for an anonymous operation.
+    sig { returns(T.nilable(String)) }
+    def operation_name
+      T.unsafe(self).const_get(:OPERATION_NAME)
+    end
+
     private
 
     # Bound by GraphWeaver.parse, which is the only caller: a parsed module
@@ -42,32 +59,69 @@ module GraphWeaver
     attr_writer :client
 
     # The one call a generated `execute` makes: resolve the client, run this
-    # module's own operation, hand the raw response back for from_response to
-    # wrap. Here rather than emitted, so what has to BRACKET a request — the
-    # graph label today — costs nothing in every generated file, and one
-    # reading of it covers every module in the app.
+    # module's own operation, and cast the raw response with the block the
+    # caller hands over — under one OPERATION_EVENT, which is the only seam
+    # that sees what the caller actually GOT. Here rather than emitted, so
+    # what has to bracket a call — the graph label, the event — costs nothing
+    # in every generated file, and one reading of it covers every module.
+    #
+    # Without a block it is the request alone, unreported: that is a module
+    # generated before the operation event existed, and an event closing :ok
+    # over half a call is worse than no event, since the cast it can't see is
+    # exactly where a CastError comes from.
     #
     # The constants come off the module rather than the caller: a generated
     # `execute` already knows them, but reading them here is what makes this
     # the whole of the call instead of three arguments' worth of it.
-    sig { params(variables: T::Hash[String, T.untyped], client: T.untyped).returns(T.untyped) }
-    def dispatch(variables, client:)
+    sig do
+      params(
+        variables: T::Hash[String, T.untyped],
+        client: T.untyped,
+        cast: T.nilable(T.proc.params(raw: T.untyped).returns(T.untyped)),
+      ).returns(T.untyped)
+    end
+    def dispatch(variables, client:, &cast)
       # A value with no JSON form is a bug in the call, not in the client that
       # would have carried it — so it is refused here, where every mode passes,
       # rather than in the transport, which :in_process and :fake never reach.
       # (A transport asks the same question of a raw query string, which never
       # comes through here.)
       GraphWeaver::Internal::Wire.check_variables!(variables)
+      target = client_for(client)
 
-      mod = T.unsafe(self)
       # the graph codegen baked in, never one inferred from the client — a
       # wrong label on a request is worse than no label
       GraphWeaver::Internal::Log.with_graph(graph_name) do
-        client_for(client).execute(mod.const_get(:QUERY), variables:,
-          operation_name: mod.const_get(:OPERATION_NAME))
+        next request(target, variables) unless cast
+
+        GraphWeaver::Internal::Log.instrument_operation(operation_payload(target)) do
+          cast.call(request(target, variables))
+        end
       end
     end
 
+    # This module's own operation, through the client this call resolved to.
+    sig { params(target: T.untyped, variables: T::Hash[String, T.untyped]).returns(T.untyped) }
+    def request(target, variables)
+      target.execute(query_string, variables:, operation_name:)
+    end
+
+    # What one call of this module is, for an APM. :module is the fact this
+    # seam has and the request below it doesn't — two graphs can name the same
+    # operation, and a trace that is slow wants the file. :client is what the
+    # module RESOLVED to, so a test mode's stand-in names itself; the request
+    # event underneath names the transport that carried it.
+    sig { params(target: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
+    def operation_payload(target)
+      {
+        operation: operation_name,
+        module: T.unsafe(self).name,
+        graph: graph_name,
+        kind: GraphWeaver::Internal::Wire.kind(query_string),
+        client: target.class,
+      }
+    end
+
     # The client one execute runs through: the per-call `client:`, else the
     # module's, else the app default. Checked here so a wrong one names the
     # contract and the module, rather than surfacing as a NoMethodError from
@@ -81,7 +135,8 @@ module GraphWeaver
       # Kernel.raise: this module is extended into another, so sorbet can't
       # see that its host is an Object
       Kernel.raise GraphWeaver::Error,
-        "#{self}: client must respond to #execute(query, variables:), got #{target.class}"
+        "#{self}: client must respond to #execute(query, variables:, operation_name:), " \
+        "got #{target.class}"
     end
 
     # A module knows which graph it belongs to, and the graph knows how to

data/lib/graph_weaver/railtie.rb

@@ -35,7 +35,7 @@ class GraphWeaver::Railtie < Rails::Railtie
     KEYS = %i[watch].freeze
 
     def method_missing(name, *args)
-      key = name.to_s.delete_suffix("=").delete_suffix("?").delete_suffix("!").to_sym
+      key = setting(name)
       return super if KEYS.include?(key)
 
       raise ArgumentError, refusal(key)
@@ -53,11 +53,16 @@ class GraphWeaver::Railtie < Rails::Railtie
     alias_method :store, :[]=
 
     def respond_to_missing?(name, _private = false)
-      KEYS.include?(name.to_s.delete_suffix("=").delete_suffix("?").delete_suffix("!").to_sym)
+      KEYS.include?(setting(name))
     end
 
     private
 
+    # the setting a reader, writer or predicate is about
+    def setting(name)
+      name.to_s.delete_suffix("=").delete_suffix("?").delete_suffix("!").to_sym
+    end
+
     def refusal(key)
       near = GraphWeaver::Internal::Util.did_you_mean(KEYS.map(&:to_s), key.to_s)
       fix =