graph_weaver 0.7.0 → 0.7.1

data/lib/graph_weaver/log_subscriber.rb

@@ -1,6 +1,12 @@
 # typed: ignore — ActiveSupport::LogSubscriber, which sorbet can't resolve here
 # frozen_string_literal: true
 
+# The superclass, so this file stands alone: requiring it by hand is the
+# documented way to subscribe outside Rails, and there is no railtie out there
+# to have loaded ActiveSupport first. Skipped when the constant already
+# exists, which is how a stand-in can take its place.
+require "active_support/log_subscriber" unless defined?(ActiveSupport::LogSubscriber)
+
 module GraphWeaver
   # One line per GraphQL operation in a Rails log, the shape ActiveRecord
   # uses for a query:
@@ -54,11 +60,13 @@ module GraphWeaver
       payload[:graph] ? "#{payload[:graph]}/#{operation}" : operation
     end
 
-    # status, then whatever narrows it: the error class, the code an alert
+    # 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.
     def outcome(payload)
       parts = [payload[:status], payload[:error]]
-      parts << "[#{payload[:code]}]" if payload[:code]
+      # the GraphQL code, or the HTTP status where the request never got one
+      reason = payload[:code] || (payload[:http_status] if payload[:status] == :failed)
+      parts << "[#{reason}]" if reason
       parts << "(retry #{payload[:retries]})" if payload[:retries].to_i.positive?
       parts.compact.join(" ")
     end

data/lib/graph_weaver/logging.rb

@@ -53,7 +53,7 @@ module GraphWeaver
     #
     # 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, :status, :duration_ms, :graph always;
+    # :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
     # variables: the payload fans out to subscribers that know none of the
@@ -77,6 +77,15 @@ module GraphWeaver
           !key.nil? && Log.filter_variables({ key.to_s => nil })[key.to_s] == FILTERED
         end
 
+        # True when this key names a credential — asked of a url's query
+        # parameters, which are scrubbed whatever the app's logging appetite.
+        # filter_parameters is a knob about log verbosity; emptying it must
+        # not un-scrub a token in an endpoint, any more than it un-scrubs the
+        # url's userinfo. The app's list widens this; it can't narrow it.
+        def credential?(key)
+          filtered?(key) || Log.filtered?(key, GraphWeaver::DEFAULT_FILTER_PARAMETERS)
+        end
+
         # `detail` unless the key is filtered — free text a coercer or sorbet
         # wrote can spell a value any way, so for a filtered key none of it
         # survives, not the parts that would have been safe.
@@ -94,12 +103,18 @@ module GraphWeaver
         # 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)
 
+        # 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
+        # redirect's destination. Control characters are stripped because it
+        # lands where the log's own framing lives: a newline in
+        # extensions.code forges a second, complete-looking line.
+        def tag(value) = value.is_a?(String) ? cap(value.gsub(/[[:cntrl:]]+/, " ")) : value
+
         # Text the library didn't author — a value a caller sent, a sentence a
         # server wrote — cut to what an error may carry. The number lives on
         # InputError, which is the class that documents it and the one every
         # capped string reaches.
-        def cap(text)
-          limit = GraphWeaver::InputError::VALUE_LIMIT
+        def cap(text, limit = GraphWeaver::InputError::VALUE_LIMIT)
           return text if text.bytesize <= limit
 
           # byteslice can land mid-character; scrub drops the partial tail
@@ -183,13 +198,15 @@ module GraphWeaver
                 payload[:status] = :ok
               else
                 payload[:status] = :errors
-                payload[:code] = errors.grep(Hash).filter_map { |e| GraphWeaver::GraphQLError.from_h(e).code }.first
+                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
-              # the one key an alert groups by, whichever kind of failure it was
-              payload[:code] = e.status if e.is_a?(GraphWeaver::ServerError)
+              # :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)
@@ -249,6 +266,16 @@ module GraphWeaver
           filters.nil? ? variables : filters.filter(variables)
         end
 
+        # Whether a key matches one of `filters` — the same matching the
+        # variables line uses, asked about a list other than the app's so
+        # Redact.credential? can hold url parameters to the default names.
+        def filtered?(key, filters)
+          name = key.to_s
+          filters.any? do |filter|
+            filter.is_a?(Regexp) ? name.match?(filter) : name.downcase.include?(filter.to_s.downcase)
+          end
+        end
+
         private
 
         # The GraphQL errors a response carries, whatever answered it — a
@@ -269,13 +296,6 @@ module GraphWeaver
           else value
           end
         end
-
-        def filtered?(key, filters)
-          name = key.to_s
-          filters.any? do |filter|
-            filter.is_a?(Regexp) ? name.match?(filter) : name.downcase.include?(filter.to_s.downcase)
-          end
-        end
       end
     end
   end

data/lib/graph_weaver/query_module.rb

@@ -3,6 +3,7 @@
 
 require "sorbet-runtime"
 
+require_relative "internal"
 require_relative "internal/test_clients"
 
 module GraphWeaver
@@ -44,6 +45,13 @@ module GraphWeaver
     # 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:)
+      # 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)
+
       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

data/lib/graph_weaver/retry.rb

@@ -38,7 +38,8 @@ require_relative "transport"
 #     default — pass the codes your API uses for transient failures)
 #
 # A server that answers with Retry-After sets the delay itself (clamped
-# to max_delay:); otherwise the configured backoff decides.
+# to max_delay:) — whether that answer raised or came back as a response
+# carrying GraphQL errors; otherwise the configured backoff decides.
 #
 # Exhausting the retries re-raises the last error (or returns the last
 # code-matched response).
@@ -105,10 +106,10 @@ class GraphWeaver::Retry
   def execute(query, variables: {}, operation_name: nil)
     attempts = mutation?(query) ? 1 : @retries + 1
     attempt = 0
-    failure = T.let(nil, T.nilable(Exception))
 
     loop do
       attempt += 1
+      failure = nil
       begin
         # each attempt is its own EXECUTE_EVENT; :retries says which one,
         # so "slow" and "slow after two 502s" don't read the same in an APM
@@ -116,6 +117,8 @@ class GraphWeaver::Retry
           @client.execute(query, variables:, operation_name:)
         end
         return response unless attempt < attempts && retryable_response?(response)
+
+        failure = response
       rescue *@retry_on => e
         if attempt >= attempts || !@retry_if.call(e)
           GraphWeaver::Internal::Log.log(:warn) { MUTATION_HINT } if attempts == 1 && @retries.positive?
@@ -132,7 +135,6 @@ class GraphWeaver::Retry
         "retrying #{operation_name || "query"} in #{seconds.round(2)}s (attempt #{attempt + 1} of #{attempts})"
       end
       @sleeper.call(seconds)
-      failure = nil
     end
   end
 
@@ -163,11 +165,13 @@ class GraphWeaver::Retry
   end
 
   def delay(attempt, failure)
-    # A Retry-After wins over our backoff: the server is the only party
-    # that knows when its window reopens, and it isn't guessing. Still
-    # clamped to max_delay:, so "come back in an hour" can't park a thread for
-    # an hour — and not jittered, since it's an instruction, not a guess.
-    after = failure.retry_after if failure.is_a?(GraphWeaver::ServerError)
+    # A Retry-After wins over our backoff, however the failure arrived — a
+    # raised ServerError, or the envelope a rate limit that came back with an
+    # errors body makes. The server is the only party that knows when its
+    # window reopens, and it isn't guessing. Still clamped to max_delay:, so
+    # "come back in an hour" can't park a thread for an hour — and not
+    # jittered, since it's an instruction, not a guess.
+    after = failure.retry_after if failure.respond_to?(:retry_after)
     return [after, @max_delay].min.to_f if after
 
     # floored at 0: a custom backoff: is the caller's arithmetic, and a

data/lib/graph_weaver/schema_loader.rb

@@ -1,6 +1,7 @@
 # typed: true
 # frozen_string_literal: true
 
+require "digest"
 require "fileutils"
 require "graphql"
 require "json"
@@ -682,7 +683,7 @@ module GraphWeaver::SchemaLoader
   #      end
   #      schema = GraphWeaver::SchemaLoader.load(json)
   def self.introspect(transport, cache: nil, ttl: nil, auth_env: nil)
-    cache = cache_path(cache)
+    cache = cache_path(cache, (transport.url if transport.respond_to?(:url)))
 
     if cache
       # reuse whatever fresh dump is present, regardless of format —
@@ -749,16 +750,20 @@ module GraphWeaver::SchemaLoader
     schema
   end
 
-  # The introspection result, asking for isOneOf and falling back without it.
+  # The introspection result, asking for the newer fields and falling back
+  # without them.
   #
   # isOneOf is the only thing that says an input object is @oneOf, and
-  # graphql-ruby leaves it out unless asked — but it is newer than plenty of
-  # servers, and one that doesn't define it REFUSES the query outright
-  # (Hasura: "field 'isOneOf' not found in type: '__Type'"). So ask, and ask
-  # the baseline query rather than give up. The second request costs one round
-  # trip on exactly the servers whose answer was going to be an error anyway.
+  # specifiedByURL the only thing that says what a scalar's format is;
+  # graphql-ruby leaves both out unless asked — but they are newer than
+  # plenty of servers, and one that doesn't define them REFUSES the query
+  # outright (Hasura: "field 'isOneOf' not found in type: '__Type'"). So ask,
+  # and ask the baseline query rather than give up. The second request costs
+  # one round trip on exactly the servers whose answer was going to be an
+  # error anyway.
   def self.ask(transport)
-    result = transport.execute(GraphQL::Introspection.query(include_is_one_of: true), variables: {}).to_h
+    query = GraphQL::Introspection.query(include_is_one_of: true, include_specified_by_url: true)
+    result = transport.execute(query, variables: {}).to_h
     return result if result["errors"].nil? && result.dig("data", "__schema")
 
     transport.execute(GraphQL::Introspection.query, variables: {}).to_h
@@ -948,23 +953,24 @@ module GraphWeaver::SchemaLoader
   private_constant :CACHE_EXTENSIONS
 
   # cache: true / :json / :graphql / :gql / a path => the file to write
-  # (nil for no caching). Symbols and true anchor at GraphWeaver.schema_path —
-  # the schema dump the generation workflow reads, so one file serves both
-  # (introspect caches it, rake generate loads it).
-  def self.cache_path(cache)
+  # (nil for no caching). A path is taken as given. Symbols and true anchor at
+  # GraphWeaver.schema_path — the schema dump the generation workflow reads,
+  # so one file serves both (introspect caches it, rake generate loads it) —
+  # unless that dump belongs to a different endpoint; see {conventional_dump}.
+  def self.cache_path(cache, url = nil)
     # Rails.root.join(...) hands you a Pathname, as schema: and query: already take
     cache = cache.to_path if cache.respond_to?(:to_path)
     path = case cache
     when nil, false
       nil
     when true
-      GraphWeaver.schema_path
+      conventional_dump(File.extname(GraphWeaver.schema_path), url)
     when Symbol
       unless CACHE_EXTENSIONS.include?(".#{cache}")
         raise ArgumentError, "cache: format must be :json, :graphql, or :gql, got #{cache.inspect}"
       end
 
-      "#{strip_extension(GraphWeaver.schema_path)}.#{cache}"
+      conventional_dump(".#{cache}", url)
     else
       unless cache.end_with?(*CACHE_EXTENSIONS)
         raise ArgumentError, "cache: must be a .json or .graphql/.gql path, got #{cache}"
@@ -976,6 +982,38 @@ module GraphWeaver::SchemaLoader
   end
   private_class_method :cache_path
 
+  # Where an unnamed `cache:` lands. One rule: **the conventional dump, unless
+  # the dump there came from a different endpoint** — then a file of this
+  # client's own, named by a digest of its url and sitting beside it. A dump
+  # records the url it was introspected from, so this is answerable; without
+  # it, two clients at two origins both saying `cache: true` read and
+  # overwrote one file, and each was silently served the other's schema.
+  #
+  # A dump that records no url is nobody's in particular — hand-written, or
+  # committed by an older version — so it stays a hit for whoever asks.
+  def self.conventional_dump(extension, url)
+    base = strip_extension(GraphWeaver.schema_path)
+    conventional = base + extension
+    url = url && GraphWeaver::Internal::Endpoint.bare(url) # what a dump records
+    return conventional if url.nil? || !someone_elses?(conventional, url)
+
+    "#{base}-#{Digest::SHA256.hexdigest(url)[0, 8]}#{extension}"
+  end
+  private_class_method :conventional_dump
+
+  # Whether a dump already at `path` (or a sibling format) says it came from
+  # somewhere other than `url`. Nothing there yet is nobody's, so a cold
+  # client still writes the conventional dump — which is what the documented
+  # bootstrap does, and what an app with one client wants.
+  def self.someone_elses?(path, url)
+    existing = cache_candidates(path).find { |candidate| File.exist?(candidate) }
+    return false unless existing
+
+    recorded = provenance(existing)&.dig("url")
+    !recorded.nil? && recorded != url
+  end
+  private_class_method :someone_elses?
+
   # the requested path first, then its siblings in the other formats
   def self.cache_candidates(path)
     path = GraphWeaver::Internal::Util.resolve(path)

data/lib/graph_weaver/testing/cassette.rb

@@ -115,11 +115,8 @@ module GraphWeaver
 
       def initialize(path)
         @path = Testing.cassette_path(path)
-        @entries = File.exist?(@path) ? YAML.safe_load_file(@path, aliases: true) : []
+        @entries = read_entries
         @flagged = []
-        # record is read-modify-write; two threads recording through one
-        # cassette (a parallel spec run) would each save a snapshot missing
-        # the other's entry — atomic_write keeps the file whole, not complete
         @lock = Mutex.new
       end
 
@@ -147,7 +144,13 @@ module GraphWeaver
         entry["response"] = response
 
         wanted = Internal::RequestKey.for(query, variables, operation_name)
-        @lock.synchronize do
+        # Recording rewrites the whole file, and parallel_tests points several
+        # processes at one cassette — so the read-modify-write happens under a
+        # lock every recorder shares, re-reading inside it. The snapshot taken
+        # at construction is already missing whatever another process recorded
+        # since, and saving it would throw those entries away.
+        locked do
+          @entries = read_entries
           @entries.reject! { |existing| Internal::RequestKey.for_entry(existing) == wanted }
           @entries << entry
           save
@@ -198,6 +201,26 @@ module GraphWeaver
 
       private
 
+      def read_entries = File.exist?(@path) ? YAML.safe_load_file(@path, aliases: true) : []
+
+      # Serialize a read-modify-write against every other recorder, in this
+      # process and any other. The Mutex is the threads; the flock is the
+      # processes. Both, because flock is held per open file, so one process's
+      # two threads would each take their own.
+      def locked
+        @lock.synchronize do
+          FileUtils.mkdir_p(File.dirname(@path))
+          File.open(lock_path, File::RDWR | File::CREAT, 0o644) do |lock|
+            lock.flock(File::LOCK_EX)
+            yield
+          end
+        end
+      end
+
+      # A sidecar, not the cassette itself: save renames a fresh file into
+      # place, so a lock held on the replaced inode guards nothing.
+      def lock_path = "#{@path}.lock"
+
       def save
         yaml = YAML.dump(@entries)
         FileUtils.mkdir_p(File.dirname(@path))

data/lib/graph_weaver/testing/endpoint.rb

@@ -27,6 +27,12 @@ module GraphWeaver
     # one thing an in-process client can't test.
     #
     #      Router.new(supergraph:, context: ->(headers) { { current_user: User.find_by(token: headers["Authorization"]) } })
+    #
+    # Answering that proc means writing the client's context for the length
+    # of one dispatch, so the client is what resolves it: any client
+    # answering `with_request_context(headers) { }` gets the seam, which
+    # {InProcess} and {Router} take from {GraphWeaver::ContextSeam}. A client
+    # without it is served untouched, and concurrently.
     class Endpoint
       JSON_HEADERS = { "content-type" => "application/json" }.freeze
       TEXT_HEADERS = { "content-type" => "text/plain" }.freeze
@@ -67,20 +73,15 @@ module GraphWeaver
 
       private
 
-      # A `context:` proc is answered from the request in hand, so it is
-      # resolved here and put back after — one request's identity must not
-      # leak into the next. A client with no context, or a hash one, is
-      # served untouched.
-      def with_context(headers)
-        context = @client.context if @client.respond_to?(:context) && @client.respond_to?(:context=)
-        return yield unless context.respond_to?(:call)
+      # A `context:` proc is answered from the request in hand, and the
+      # client's context is what gets written to answer it — so the client
+      # does it, under its own lock. This endpoint is built per request by
+      # `graphql: :wire`; a lock held here would guard nothing the next
+      # request shares.
+      def with_context(headers, &block)
+        return yield unless @client.respond_to?(:with_request_context)
 
-        @client.context = context.call(headers)
-        begin
-          yield
-        ensure
-          @client.context = context
-        end
+        @client.with_request_context(headers, &block)
       end
 
       # Rack spells a header HTTP_X_CALLER; the proc reads "X-Caller".

data/lib/graph_weaver/testing/fake_client.rb

@@ -147,7 +147,11 @@ class GraphWeaver::Testing::FakeClient
   # `hash` or a `count`, and a Struct answers both with plausible nonsense
   # where fabricating is right.
   RUBY_OWN = [BasicObject, Kernel, Object, Comparable, Enumerable, Struct, Data].freeze
-  private_constant :OPTIONS, :WIRE, :RUBY_OWN
+
+  # The scalars the GraphQL spec serializes as JSON strings, whatever Ruby
+  # holds them.
+  STRING_SCALARS = %w[ID String].freeze
+  private_constant :OPTIONS, :WIRE, :RUBY_OWN, :STRING_SCALARS
 
   def initialize(pins = {}, **options)
     config = GraphWeaver::Testing.config
@@ -502,13 +506,31 @@ class GraphWeaver::Testing::FakeClient
     case type.kind.name
     when "NON_NULL" then wire_value(type.of_type, value, coordinate)
     when "LIST"
-      value.is_a?(Array) ? value.map { |element| wire_value(type.of_type, element, coordinate) } : value
-    when "SCALAR" then @values.wire(type.graphql_name, value, coordinate)
+      # whatever enumerates, not an Array alone: a has_many is an
+      # ActiveRecord CollectionProxy, and reading one straight onto the wire
+      # failed the cast as "the server sent a
+      # Order::ActiveRecord_Associations_CollectionProxy". A Hash is the one
+      # thing that enumerates and isn't a list.
+      return value if value.is_a?(Hash) || !value.is_a?(Enumerable)
+
+      value.map { |element| wire_value(type.of_type, element, coordinate) }
+    when "SCALAR" then scalar_wire(type.graphql_name, value, coordinate)
     when "ENUM" then value.is_a?(T::Enum) ? value.serialize : value
     else value # a composite: pinned_object reads it, one level down
     end
   end
 
+  # ID and String are JSON strings on every real wire, whatever Ruby type the
+  # object's column holds — an Integer primary key read straight through
+  # failed the cast with the advice for a server that sends ids unquoted,
+  # which is advice about a server that isn't there.
+  def scalar_wire(name, value, coordinate)
+    wired = @values.wire(name, value, coordinate)
+    return wired unless STRING_SCALARS.include?(name) && !wired.nil? && !wired.is_a?(String)
+
+    wired.to_s
+  end
+
   # The concrete type a pinned object is fabricated as. At a union or
   # interface the pin has to say: picking a member at random would fabricate
   # a shape the pinned keys don't fit, in whichever fraction of runs the
@@ -594,12 +616,20 @@ class GraphWeaver::Testing::FakeClient
     # Array.new(-1) is "negative array size" out of the fabricator's guts; a
     # cap below zero asks for nothing, which is what a page of none is
     return [capped, 0].max if capped.is_a?(Integer)
+    return 0 if errors_list?(node.name)
 
     size = list_size_for(coordinate, node.name)
     # an Integer list_size means exactly that many; a Range randomizes within it
     size.is_a?(Range) ? rng.rand(size) : size
   end
 
+  # A list field whose name ends in `errors` fabricates empty. The Relay and
+  # Shopify payload convention — `placeOrder { order userErrors }` — otherwise
+  # comes back with a fabricated order AND a fabricated failure, which is a
+  # response no server can send, so the natural happy-path assertion is flaky
+  # until it is pinned. Pin it to fabricate the failure path.
+  def errors_list?(name) = name.downcase.end_with?("errors")
+
   # How long an unbounded list is. A Hash says it per list, read most
   # specific first like a pin — which is what keeps nested lists from
   # multiplying: every list the walk reaches re-reads this, so one number

data/lib/graph_weaver/testing/router.rb

@@ -11,6 +11,7 @@ require_relative "../internal"
 require_relative "../transport"
 require_relative "../internal/planner"
 require_relative "../internal/subgraphs"
+require_relative "../context_seam"
 
 module GraphWeaver
   module Testing
@@ -203,6 +204,8 @@ module GraphWeaver
     # reset it yourself around the code path you're measuring.
     class Router
       include GraphWeaver::Parsing
+      # #context/#context= plus the lock over them — see the accessor below
+      include GraphWeaver::ContextSeam
 
       # the schema the router serves — the supergraph with its composition
       # machinery stripped, exactly what a real router exposes
@@ -232,8 +235,9 @@ module GraphWeaver
       # 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
+      # headers["Authorization"]) } }` served through {Endpoint}. The
+      # accessors, and the lock guarding them, come from
+      # {GraphWeaver::ContextSeam}.
 
       # The planner injects key fields under this prefix, and the concrete
       # __typename under that key; reading an answer back means stripping
@@ -252,7 +256,7 @@ module GraphWeaver
         source = supergraph.to_s # a path, or the SDL itself — Pathname included
         @schema = GraphWeaver::SchemaLoader.load(source)
         @table = GraphWeaver::SchemaLoader.routing_table(source)
-        @context = context
+        init_context_seam(context)
         @trace = []
 
         Unplannable.unsupported!(@table)

data/lib/graph_weaver/transport/http.rb

@@ -55,7 +55,7 @@ module GraphWeaver
           nil
         end
         unless uri && %w[http https].include?(uri.scheme)
-          raise ArgumentError, "expected an http(s) url, got #{url.inspect}"
+          raise ArgumentError, "expected an http(s) url, got #{GraphWeaver::Internal::Endpoint.safe(url).inspect}"
         end
 
         @uri = uri
@@ -69,7 +69,7 @@ module GraphWeaver
         # verify_mode: — so mTLS doesn't mean reaching for Faraday
         @ssl = { ca_file:, ca_path:, cert:, key:, verify_mode: }.compact
         if @ssl.any? && @uri.scheme != "https"
-          raise ArgumentError, "TLS options need an https url — got #{url}"
+          raise ArgumentError, "TLS options need an https url — got #{GraphWeaver::Internal::Endpoint.safe(url)}"
         end
 
         # One permit per allowed socket: holding a permit is the right to