graph_weaver 0.4.4 → 0.5.0

data/lib/graph_weaver/transport.rb

@@ -5,11 +5,12 @@ require "json"
 require "sorbet-runtime"
 
 require_relative "errors"
+require_relative "version"
 
 # Base class for the bundled network transports — Transport::HTTP
 # (zero-dependency net/http, loaded by default) and Transport::Faraday
-# (opt-in). A transport speaks GraphQL-over-HTTP and satisfies the
-# same execute(query, variables:) => {"data" => ..., "errors" => ...}
+# (opt-in). A transport speaks GraphQL-over-HTTP and satisfies the same
+# execute(query, variables:, operation_name:) => {"data" => ..., "errors" => ...}
 # contract as a schema class or a fake — anything in a client slot.
 #
 # The base class owns the shared flow — encode the request, reclassify
@@ -21,29 +22,68 @@ class GraphWeaver::Transport
   extend T::Helpers
   abstract!
 
+  # What every request sends unless the caller says otherwise.
+  # graphql-over-http requires a conforming client to accept
+  # application/graphql-response+json; the q=0.9 fallback keeps servers
+  # that only speak the legacy media type working. The User-Agent is what
+  # lets a server operator attribute the traffic.
+  DEFAULT_HEADERS = {
+    "Content-Type" => "application/json",
+    "Accept" => "application/graphql-response+json, application/json;q=0.9",
+    "User-Agent" => "graph_weaver/#{GraphWeaver::VERSION}",
+  }.freeze
+
+  # Timeouts, in seconds, shared by the bundled transports — a missing
+  # timeout is an outage, and net/http's own 60s/60s is far too patient
+  # for an API call.
+  DEFAULT_OPEN_TIMEOUT = 10
+  DEFAULT_READ_TIMEOUT = 30
+
   # the endpoint this transport talks to — recorded into cached schema
   # dumps as provenance (see SchemaLoader.introspect)
   attr_reader :url
 
-  def execute(query, variables: {})
+  # operation_name: names the operation to run — sent on the wire as
+  # `operationName`, which is what an APM keys its traces, rate limits and
+  # slow-query reports on. Generated modules pass their OPERATION_NAME;
+  # a raw query string falls back to the name in the document itself.
+  def execute(query, variables: {}, operation_name: nil)
+    operation_name ||= GraphWeaver::Transport.operation_name(query)
+    payload = { url:, operation: operation_name }
+
+    GraphWeaver.instrument(GraphWeaver::EXECUTE_EVENT, payload) do
+      perform(query, variables, operation_name, payload)
+    end
+  end
+
+  # The request itself. Separate from execute so the instrumenter wraps
+  # a call rather than a block this method returns out of.
+  private def perform(query, variables, operation_name, payload)
     # tag pairs this request's log lines (threads interleave), and names
     # the operation so the log says WHICH query, not just the url
-    tag = GraphWeaver.logger && GraphWeaver::Transport.log_tag(query)
+    tag = GraphWeaver.logger && GraphWeaver::Transport.log_tag(operation_name)
 
     # full query + variables at debug only — they can carry PII
     GraphWeaver.log(:debug) do
       "POST #{url} #{tag} variables=#{JSON.generate(variables)}\n#{GraphWeaver::Transport.truncate_for_log(query)}"
     end
 
+    # camelCase because it's the graphql-over-http request field, not a
+    # Ruby name; omitted rather than null when the operation is anonymous
+    request = { query:, variables: }
+    request[:operationName] = operation_name if operation_name
+
     encoded = begin
-      JSON.generate(query:, variables:)
+      JSON.generate(request)
     rescue JSON::GeneratorError => e
       # a value with no JSON form (NaN, Infinity, binary) — the caller's
       # bug, surfaced under the umbrella instead of a raw JSON:: error
       raise GraphWeaver::Error, "variables are not JSON-serializable: #{e.message}"
     end
 
-    status, body = begin
+    # headers is optional: a third-party subclass returning the
+    # documented [status, body] pair simply has none
+    status, body, headers = begin
       GraphWeaver.log_timed(:debug, "POST #{url} #{tag} completed") do
         post(encoded)
       end
@@ -52,6 +92,7 @@ class GraphWeaver::Transport
       raise GraphWeaver::TransportError, "#{e.class}: #{e.message}"
     end
 
+    payload[:status] = status
     GraphWeaver.log(:debug) { "HTTP #{status} #{tag} from #{url} (#{body.to_s.bytesize} bytes)" }
 
     parsed = parse_body(body)
@@ -62,15 +103,20 @@ class GraphWeaver::Transport
     # envelope so QueryError machinery sees the structured errors; only
     # a body that isn't GraphQL (proxy pages, HTML 500s) is a ServerError.
     unless (200..299).cover?(status)
-      return parsed if parsed.is_a?(Hash) && parsed.key?("errors")
+      # only a body carrying actual GraphQL errors flows through — a 4xx with
+      # `"errors": null` (or []) isn't a structured error response, so the
+      # status stays the signal
+      return parsed if parsed.is_a?(Hash) && parsed["errors"].is_a?(Array) && parsed["errors"].any?
 
-      raise GraphWeaver::ServerError.new(status:, body: body.to_s)
+      raise GraphWeaver::ServerError.new(status:, body: body.to_s, headers: headers || {})
     end
 
-    unless parsed
-      # a 200 that isn't GraphQL — an HTML error page from a proxy, a
-      # captive portal: the server misbehaved, classify it that way
-      raise GraphWeaver::ServerError.new(status:, body: "non-JSON response: #{body.to_s[0, 500]}")
+    unless parsed.is_a?(Hash)
+      # a 200 that isn't a GraphQL object — an HTML error page from a proxy, a
+      # captive portal, or a bare JSON array/string: the server misbehaved
+      raise GraphWeaver::ServerError.new(
+        status:, body: "non-GraphQL response: #{body.to_s[0, 500]}", headers: headers || {}
+      )
     end
 
     parsed
@@ -93,14 +139,21 @@ class GraphWeaver::Transport
   end
   alias to_s inspect
 
+  # The name of the document's FIRST operation, nil when anonymous. Only
+  # the fallback for a raw query string handed straight to a transport —
+  # generated modules pass their OPERATION_NAME, parsed properly.
+  OPERATION_NAME_PATTERN = /\A\s*(?:query|mutation|subscription)\s+([A-Za-z_]\w*)/
+  def self.operation_name(query)
+    query[OPERATION_NAME_PATTERN, 1]
+  end
+
   # "[req 3 FilteredPokemon]" — a per-process request id plus the
-  # operation name (when the document declares one)
+  # operation name, when there is one
   REQUEST_MUTEX = Mutex.new
 
-  def self.log_tag(query)
+  def self.log_tag(operation_name = nil)
     id = REQUEST_MUTEX.synchronize { @request_count = (@request_count || 0) + 1 }
-    name = query[/\A\s*(?:query|mutation|subscription)\s+([A-Za-z_]\w*)/, 1]
-    "[req #{id}#{" #{name}" if name}]"
+    "[req #{id}#{" #{operation_name}" if operation_name}]"
   end
 
   # keep debug readable: a 100-line introspection query would drown the
@@ -114,7 +167,10 @@ class GraphWeaver::Transport
 
   private
 
-  # POST the JSON body to the endpoint; return [status code, raw body].
-  sig { abstract.params(body: String).returns([Integer, T.untyped]) }
+  # POST the JSON body to the endpoint; return [status code, raw body]
+  # — optionally with a third element, the response headers as a Hash
+  # with downcased names, which ServerError then carries (Retry-After,
+  # x-ratelimit-*). Two elements remains a complete answer.
+  sig { abstract.params(body: String).returns(T::Array[T.untyped]) }
   def post(body); end
 end

data/lib/graph_weaver/version.rb

@@ -1,3 +1,3 @@
 module GraphWeaver
-  VERSION = "0.4.4"
+  VERSION = "0.5.0"
 end