graph_weaver 0.7.5 → 0.7.7

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.
@@ -137,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
@@ -174,48 +187,29 @@ 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
+
+        # 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
 
         # What a Retry has already spent, read by the attempt it is about
@@ -275,13 +269,55 @@ module GraphWeaver
           end
         end
 
-        # 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.
+        # 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

@@ -59,30 +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)
 
       # 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(query_string, variables:, 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
@@ -96,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