graph_weaver 0.6.1 → 0.7.1

data/lib/graph_weaver/transport/http.rb

@@ -20,8 +20,16 @@ module GraphWeaver
     class HTTP < Transport
       # net/http's own network-level failures (Errno/SocketError/IOError
       # are already seeded) — added to the shared, extensible
-      # transport-error set.
-      GraphWeaver.register_transport_error(Timeout::Error, OpenSSL::SSL::SSLError)
+      # transport-error set. A garbage status line and a mangled compressed
+      # body are as much "never got a usable response" as a reset socket is,
+      # and both recover on a fresh connection when the cause was a desynced
+      # keep-alive socket; Faraday's transport classifies them the same way.
+      GraphWeaver.register_transport_error(
+        Timeout::Error, OpenSSL::SSL::SSLError, Net::HTTPBadResponse, Net::ProtocolError
+      )
+      # net/http gunzips through zlib, so a build without it can't receive a
+      # compressed body in the first place
+      GraphWeaver.register_transport_error(Zlib::Error) if defined?(Zlib::Error)
 
       # How many requests this process can have in flight at once. Rails sizes
       # its own connection pool from RAILS_MAX_THREADS and this is the same
@@ -47,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
@@ -61,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
@@ -74,14 +82,15 @@ module GraphWeaver
         # live connections, LIFO — a warm socket beats opening a cold one,
         # so a single-threaded caller keeps reusing the same one
         @idle = []
-        @lock = Mutex.new # guards @idle and @saturated
+        @pid = Process.pid
+        @lock = Mutex.new # guards @idle, @pid and @saturated
       end
 
       private
 
       sig { override.params(body: String).returns(T::Array[T.untyped]) }
       def post(body)
-        request = Net::HTTP::Post.new(@uri, DEFAULT_HEADERS.merge(@headers))
+        request = Net::HTTP::Post.new(@uri, request_headers)
         request.body = body
 
         response = with_connection { |http| http.request(request) }
@@ -90,10 +99,25 @@ module GraphWeaver
         [response.code.to_i, response.body, response.each_header.to_h]
       end
 
+      # What this request sends. A value answering #call is resolved here
+      # rather than at construction, so a header that expires — a rotating
+      # token — is asked for per request; nil drops the header, which is how
+      # an optional one says "not this time". Everything else ships as its
+      # #to_s: net/http calls #strip on the value, so the documented
+      # `-> { Current.tenant&.id }` was a bare NoMethodError in any app whose
+      # ids are Integers.
+      def request_headers
+        Transport.default_headers.merge(@headers).filter_map do |name, value|
+          value = value.call if value.respond_to?(:call)
+          [name, value.to_s] unless value.nil?
+        end.to_h
+      end
+
       # Lease a connection for one round trip. The permit is held across
       # the whole trip — opening the socket included — so pool_size really
       # is the concurrency ceiling.
       def with_connection
+        @lock.synchronize { reset_after_fork }
         acquire_permit
         # nothing between acquiring the permit and the ensure that returns it:
         # an async interrupt (Rack::Timeout, a fiber cancel) landing in that
@@ -116,6 +140,24 @@ module GraphWeaver
         end
       end
 
+      # A pool belongs to the process that built it. A socket idle at fork
+      # time is inherited by every child — and nothing in a round trip says
+      # which process opened it, so workers interleave requests on one fd and
+      # a caller receives a well-formed answer to another process's query.
+      # The inherited sockets are dropped WITHOUT #finish (closing would take
+      # down the fd the parent is still using; they go with the child when it
+      # exits), and the permits are rebuilt, since any held at fork time went
+      # with the threads that held them.
+      def reset_after_fork
+        return if @pid == Process.pid
+
+        @idle.clear
+        @permits = SizedQueue.new(@pool_size)
+        @pool_size.times { @permits.push(true) }
+        @saturated = false
+        @pid = Process.pid
+      end
+
       # A fresh persistent connection. net/http proactively reconnects
       # when idle past keep_alive_timeout, so a server-closed keep-alive
       # socket doesn't produce spurious failures.

data/lib/graph_weaver/transport.rb

@@ -6,6 +6,7 @@ require "sorbet-runtime"
 
 require_relative "errors"
 require_relative "internal"
+require_relative "internal/endpoint"
 require_relative "version"
 
 # Base class for the bundled network transports — Transport::HTTP
@@ -23,8 +24,14 @@ 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
+  # Opt-in without the require: naming the constant loads the file, which is
+  # where `require "faraday"` lives — so an initializer can write
+  # Transport::Faraday.new(url) as the docs show, and an app that never names
+  # it never loads faraday. Without the gem the LoadError names it.
+  autoload :Faraday, "graph_weaver/transport/faraday"
+
+  # The fixed half of what every request sends — see .default_headers for
+  # all of it. 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.
@@ -34,6 +41,37 @@ class GraphWeaver::Transport
     "User-Agent" => "graph_weaver/#{GraphWeaver::VERSION}",
   }.freeze
 
+  # What every request sends unless the caller says otherwise. Apollo Router
+  # and GraphOS key client attribution on the two apollographql-client-*
+  # headers — per-client SLOs, per-client rate limits, "who still asks for
+  # this deprecated field" — and a client that sends neither is attributed
+  # to the empty string along with everyone else. They are plain headers, so
+  # headers: overrides them: that is how one app names its several clients
+  # apart, which a default can't do for it.
+  def self.default_headers
+    DEFAULT_HEADERS.merge(
+      "apollographql-client-name" => client_name,
+      "apollographql-client-version" => GraphWeaver::VERSION,
+    )
+  end
+
+  # Apollo's client name is the consuming *application*, so a Rails app
+  # answers with its own name — asked per request, because Rails.application
+  # doesn't exist yet while the Gemfile is being required. The version stays
+  # the gem's: graph_weaver can't know what your app calls its releases.
+  def self.client_name
+    # const_get rather than the constant itself: an app that typechecks this
+    # gem without Rails in its sorbet payload can't resolve a bare ::Rails
+    rails = Object.const_get(:Rails) if defined?(::Rails)
+    app = rails.application if rails.respond_to?(:application)
+    return "graph_weaver" unless app
+
+    # Rails names the application class after the app: Storefront::Application
+    namespace = app.class.name.to_s.split("::")[0..-2].join("::")
+    namespace.empty? ? "graph_weaver" : namespace
+  end
+  private_class_method :client_name
+
   # 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.
@@ -44,13 +82,22 @@ class GraphWeaver::Transport
   # dumps as provenance (see SchemaLoader.introspect)
   attr_reader :url
 
+  # The same endpoint as this gem is willing to SAY it: a url can carry a
+  # credential in its userinfo or a query parameter, and a log line, an
+  # exception and an APM payload all outlive the request. Memoized, because
+  # every request says it at least twice.
+  def safe_url
+    @safe_url ||= GraphWeaver::Internal::Endpoint.safe(url)
+  end
+
   # 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::Internal::Wire.operation_name(query)
-    payload = { url:, operation: operation_name }
+    payload = { url: safe_url, operation: operation_name, client: self.class,
+                kind: GraphWeaver::Internal::Wire.kind(query) }
 
     GraphWeaver::Internal::Log.instrument(GraphWeaver::EXECUTE_EVENT, payload) do
       perform(query, variables, operation_name, payload)
@@ -67,8 +114,8 @@ class GraphWeaver::Transport
     # full query + variables at debug only — they can carry PII, and the
     # sensitive keys are scrubbed even there (GraphWeaver.filter_parameters)
     GraphWeaver::Internal::Log.log(:debug) do
-      filtered = JSON.generate(GraphWeaver::Internal::Log.filter_variables(variables))
-      "POST #{url} #{tag} variables=#{filtered}\n#{GraphWeaver::Internal::Wire.truncate_for_log(query)}"
+      filtered = GraphWeaver::Internal::Log.variables_for_log(variables)
+      "POST #{safe_url} #{tag} variables=#{filtered}\n#{GraphWeaver::Internal::Wire.truncate_for_log(query)}"
     end
 
     # camelCase because it's the graphql-over-http request field, not a
@@ -76,27 +123,34 @@ class GraphWeaver::Transport
     request = { query:, variables: }
     request[:operationName] = operation_name if operation_name
 
-    encoded = begin
-      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
+    GraphWeaver::Internal::Wire.check_variables!(variables)
+    encoded = GraphWeaver::Internal::Wire.json(request)
 
     # headers is optional: a third-party subclass returning the
     # documented [status, body] pair simply has none
     status, body, headers = begin
-      GraphWeaver::Internal::Log.log_timed(:debug, "POST #{url} #{tag} completed") do
+      GraphWeaver::Internal::Log.log_timed(:debug, "POST #{safe_url} #{tag} completed") do
         post(encoded)
       end
     rescue *GraphWeaver.transport_errors.to_a => e
-      # never got a response — DNS, connection refused/reset, TLS, timeout
-      raise GraphWeaver::TransportError, "#{e.class}: #{e.message}"
+      # never got a response — DNS, connection refused/reset, TLS, timeout.
+      # The adapter's sentence is its own words, capped like any text we
+      # didn't author.
+      raise GraphWeaver::TransportError.new(
+        "#{e.class}: #{GraphWeaver::Internal::Redact.cap(e.message)}", url: safe_url,
+      )
     end
 
-    payload[:status] = status
-    GraphWeaver::Internal::Log.log(:debug) { "HTTP #{status} #{tag} from #{url} (#{body.to_s.bytesize} bytes)" }
+    payload[:http_status] = status
+    # folded once: a third-party subclass's headers may come back in any
+    # casing, and a subclass that returns none says nothing
+    fields = GraphWeaver::Internal::Headers.wrap(headers || {})
+    # the content type, not the body: it is what tells a proxy's HTML page
+    # from a router's JSON without quoting bytes a server chose
+    GraphWeaver::Internal::Log.log(:debug) do
+      type = GraphWeaver::Internal::Redact.tag(fields["content-type"])
+      "HTTP #{status} #{tag} from #{safe_url} (#{body.to_s.bytesize} bytes#{", #{type}" if type})"
+    end
 
     parsed = parse_body(body)
 
@@ -109,20 +163,72 @@ class GraphWeaver::Transport
       # 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?
+      if parsed.is_a?(Hash) && parsed["errors"].is_a?(Array) && parsed["errors"].any?
+        return Envelope.new(parsed, status, fields.retry_after)
+      end
 
-      raise GraphWeaver::ServerError.new(status:, body: body.to_s, headers: headers || {})
+      refuse!(status, body, headers)
     end
 
     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 || {}
-      )
+      # captive portal, or a bare JSON array/string: the server misbehaved.
+      # A well-formed @defer stream is named rather than lumped in: it isn't
+      # non-GraphQL, it's more than one GraphQL document.
+      detail =
+        if incremental?(fields)
+          "this response is incremental delivery (@defer/@stream), which this client doesn't read"
+        elsif body.to_s.empty?
+          "empty response body"
+        else
+          "non-GraphQL response"
+        end
+      refuse!(status, body, headers, detail:)
     end
 
-    parsed
+    Envelope.new(parsed, status, fields.retry_after)
+  end
+
+  # The response wasn't one we can read. A body is never quoted — not into the
+  # message, not into a log line: it is text a server chose, and an error page
+  # that echoes the request fills it with the variables and the Authorization
+  # header we just sent. `detail` is what WE say went wrong; the bytes are on
+  # ServerError#body for whoever rescues it.
+  private def refuse!(status, body, headers, detail: nil)
+    raise GraphWeaver::ServerError.new(status:, body: body.to_s, headers: headers || {}, url: safe_url, detail:)
+  end
+
+  # The parsed envelope, plus what the HTTP response said around it — a Hash
+  # to everything that reads a GraphQL response, and more to the one caller
+  # that needs it. Retry asks both: a router answers rate limiting with a 503
+  # or 429 AND an errors body, so the body alone can't say whether to come
+  # back, and Retry-After says when. The seconds, not the headers — that is
+  # the whole of what Retry asks, and every other header stays where a
+  # ServerError already carries it.
+  class Envelope < Hash
+    attr_reader :http_status, :retry_after
+
+    def initialize(parsed, http_status, retry_after = nil)
+      super()
+      @http_status = http_status
+      @retry_after = retry_after
+      update(parsed)
+    end
+  end
+  private_constant :Envelope
+
+  # A leading UTF-8 BOM, which RFC 8259 §8.1 lets a parser ignore and Ruby's
+  # doesn't. .NET/IIS-fronted endpoints emit one, and the three bytes that
+  # break the parse are invisible in the body an error would quote back.
+  # Compared as bytes: a net/http body arrives ASCII-8BIT, a middleware's
+  # UTF-8, and those two are never == to each other.
+  BOM = "\xEF\xBB\xBF".b
+  private_constant :BOM
+
+  # A multipart/mixed body is one @defer/@stream response arriving in
+  # installments.
+  private def incremental?(fields)
+    fields["content-type"].to_s.start_with?("multipart/mixed")
   end
 
   # the parsed body, or nil when it isn't JSON (a caller's connection may
@@ -130,15 +236,16 @@ class GraphWeaver::Transport
   private def parse_body(body)
     return body unless body.is_a?(String)
 
+    body = T.must(body.byteslice(3..)) if body.byteslice(0, 3)&.b == BOM
     JSON.parse(body)
   rescue JSON::ParserError
     nil
   end
 
-  # never leak Authorization headers through logs/exceptions — a
-  # transport inspects as its class + endpoint, nothing more
+  # never leak credentials through logs/exceptions — a transport inspects as
+  # its class and the endpoint it is safe to say, nothing more
   def inspect
-    "#<#{self.class.name} url=#{url.inspect}>"
+    "#<#{self.class.name} url=#{safe_url.inspect}>"
   end
   alias to_s inspect
 

data/lib/graph_weaver/version.rb

@@ -1,3 +1,3 @@
 module GraphWeaver
-  VERSION = "0.6.1"
+  VERSION = "0.7.1"
 end