graph_weaver 0.1.0 → 0.2.1

data/lib/graph_weaver/testing.rb

@@ -14,29 +14,31 @@ end
 # Opt-in test tooling: require "graph_weaver/testing" from your spec
 # helper (never from production code). Configure once, initializer-style:
 #
-#   GraphWeaver::Testing.configure do |config|
-#     config.schema = MySchema                  # for auto_fake / cassettes
-#     config.seed = 42                          # reproducible fakes
-#     config.mode = :faker                      # or :literal; nil = auto
-#     config.overrides = { "Person.name" => "Daniel" }
-#     config.list_size = 2..4
-#     config.null_chance = 0.1                  # nullable fields go nil sometimes
-#     config.cassette_dir = "spec/cassettes"
-#   end
+#      GraphWeaver::Testing.configure do |config|
+#        config.schema = MySchema                  # for auto_fake / cassettes
+#        config.seed = 42                          # reproducible fakes
+#        config.mode = :faker                      # or :literal; nil = auto
+#        config.overrides = { "Person.name" => "Daniel" }
+#        config.list_size = 2..4
+#        config.null_chance = 0.1                  # nullable fields go nil sometimes
+#        config.cassette_dir = "spec/cassettes"
+#      end
 #
 # mode picks how values are fabricated:
-#   :faker   — semantic, field-name matched (requires the faker gem)
-#   :literal — plain type-derived values ("name-1", seeded numbers)
-#   nil      — auto: :faker when the gem is loaded, else :literal
+#      :faker   — semantic, field-name matched (requires the faker gem)
+#      :literal — plain type-derived values ("name-1", seeded numbers)
+#      nil      — auto: :faker when the gem is loaded, else :literal
 #
 # rspec users: require "graph_weaver/rspec" instead — it hooks the suite
-# (seed from rspec, optional auto-faked executor per example).
+# (seed from rspec, optional auto-faked client per example).
 module GraphWeaver
   module Testing
     MODES = [:faker, :literal].freeze
 
     class Config
-      attr_accessor :overrides, :seed, :list_size, :null_chance, :schema, :cassette_dir, :auto_fake
+      attr_accessor :overrides, :seed, :list_size, :null_chance, :cassette_dir, :auto_fake,
+        :record, :anonymize
+      attr_writer :schema
       attr_reader :mode
 
       def initialize
@@ -47,7 +49,21 @@ module GraphWeaver
         @mode = nil # auto
         @schema = nil
         @cassette_dir = "spec/cassettes"
+        # explicit opt-in: swapping every example onto a fake is too
+        # surprising to be a default — a little friction beats unexpected
+        # behavior (the schema still auto-locates once you opt in)
         @auto_fake = false
+        # GRAPHWEAVER_RECORD=1 rspec ...  -> Cassette.use re-records
+        @record = !ENV["GRAPHWEAVER_RECORD"].to_s.empty?
+        # anonymize responses as they're recorded (needs config.schema)
+        @anonymize = false
+      end
+
+      # the explicitly configured schema, else the conventional dump
+      # (SchemaLoader.locate at GraphWeaver.schema_path) — nil when
+      # neither exists, which quietly disables auto_fake
+      def schema
+        @schema ||= GraphWeaver::SchemaLoader.locate
       end
 
       def mode=(mode)
@@ -85,6 +101,6 @@ module GraphWeaver
 end
 
 require_relative "testing/values"
-require_relative "testing/fake_executor"
+require_relative "testing/fake_client"
 require_relative "testing/failure"
 require_relative "testing/cassette"

data/lib/graph_weaver/transport/faraday.rb

@@ -0,0 +1,56 @@
+# typed: true
+# frozen_string_literal: true
+
+require "faraday"
+
+require_relative "../transport"
+
+module GraphWeaver
+  class Transport
+    # Faraday-backed transport. Opt-in (faraday is not a hard dependency):
+    #
+    #      require "graph_weaver/transport/faraday"
+    #
+    #      # simplest: build a default connection from a url
+    #      GraphWeaver::Transport::Faraday.new("https://api.example.com/graphql")
+    #
+    #      # customize middleware while building
+    #      GraphWeaver::Transport::Faraday.new(url) do |conn|
+    #        conn.request :authorization, "Bearer", -> { Tokens.fetch }
+    #        conn.response :logger
+    #      end
+    #
+    #      # or bring a fully configured connection
+    #      GraphWeaver::Transport::Faraday.new(Faraday.new(url:) { |conn| ... })
+    class Faraday < Transport
+      # Faraday's network-level failures — added to the shared, extensible
+      # transport-error set.
+      GraphWeaver.register_transport_error(
+        ::Faraday::ConnectionFailed, ::Faraday::TimeoutError, ::Faraday::SSLError
+      )
+
+      def initialize(url_or_connection, headers: {}, &block)
+        @connection = case url_or_connection
+        when ::Faraday::Connection
+          url_or_connection
+        else
+          # Faraday appends the default adapter when the block doesn't set one
+          ::Faraday.new(url: url_or_connection, headers:, &block)
+        end
+        @url = @connection.url_prefix.to_s
+      end
+
+      private
+
+      sig { override.params(body: String).returns([Integer, T.untyped]) }
+      def post(body)
+        response = @connection.post do |request|
+          request.headers["Content-Type"] = "application/json"
+          request.body = body
+        end
+
+        [response.status, response.body]
+      end
+    end
+  end
+end

data/lib/graph_weaver/transport/http.rb

@@ -0,0 +1,87 @@
+# typed: true
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+require_relative "../transport"
+
+module GraphWeaver
+  class Transport
+    # Minimal net/http transport — zero dependencies, loaded by default:
+    #
+    #      GraphWeaver::Transport::HTTP.new(url, headers: { ... }, read_timeout: 10)
+    #
+    # Timeouts surface as TransportError (retriable). The connection is
+    # persistent (keep-alive), serialized behind a mutex — one socket per
+    # transport, dropped on any failure so the next call starts fresh.
+    # For real connection pooling and a middleware ecosystem, use
+    # Transport::Faraday.
+    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)
+
+      def initialize(url, headers: {}, open_timeout: 10, read_timeout: 30, keep_alive_timeout: 2)
+        @url = url
+        @uri = URI(url)
+        @headers = headers
+        @open_timeout = open_timeout
+        @read_timeout = read_timeout
+        @keep_alive_timeout = keep_alive_timeout
+        @mutex = Mutex.new
+        @http = T.let(nil, T.nilable(Net::HTTP))
+      end
+
+      private
+
+      sig { override.params(body: String).returns([Integer, T.untyped]) }
+      def post(body)
+        request = Net::HTTP::Post.new(@uri, { "Content-Type" => "application/json" }.merge(@headers))
+        request.body = body
+
+        response = @mutex.synchronize do
+          begin
+            connection.request(request)
+          rescue => e
+            # socket state is unknown — drop it so the next call starts
+            # fresh (retry policy belongs to Retry, not here)
+            disconnect
+            raise e
+          end
+        end
+
+        [response.code.to_i, response.body]
+      end
+
+      # The persistent connection. net/http proactively reconnects when
+      # idle past keep_alive_timeout, so a server-closed keep-alive
+      # socket doesn't produce spurious failures.
+      def connection
+        @http ||= begin
+          GraphWeaver.log(:debug) { "connecting to #{@uri.hostname}:#{@uri.port}" }
+          Net::HTTP.start(
+            @uri.hostname, @uri.port,
+            use_ssl: @uri.scheme == "https",
+            open_timeout: @open_timeout, read_timeout: @read_timeout,
+            keep_alive_timeout: @keep_alive_timeout,
+          )
+        end
+      end
+
+      def disconnect
+        http = @http
+        return unless http
+
+        GraphWeaver.log(:debug) { "dropping connection to #{@uri.hostname}:#{@uri.port}" }
+        http.finish if http.started?
+      rescue IOError
+        # already closed
+      ensure
+        @http = nil
+      end
+    end
+  end
+end

data/lib/graph_weaver/transport.rb

@@ -0,0 +1,120 @@
+# typed: true
+# frozen_string_literal: true
+
+require "json"
+require "sorbet-runtime"
+
+require_relative "errors"
+
+# 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" => ...}
+# contract as a schema class or a fake — anything in a client slot.
+#
+# The base class owns the shared flow — encode the request, reclassify
+# network-level failures as TransportError, raise ServerError on a
+# non-2xx status, parse the body — so a subclass only implements post:
+# take the request body, return [status, body].
+class GraphWeaver::Transport
+  extend T::Sig
+  extend T::Helpers
+  abstract!
+
+  # the endpoint this transport talks to — recorded into cached schema
+  # dumps as provenance (see SchemaLoader.introspect)
+  attr_reader :url
+
+  def execute(query, variables: {})
+    # 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)
+
+    # 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
+
+    encoded = begin
+      JSON.generate(query:, variables:)
+    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
+      GraphWeaver.log_timed(:debug, "POST #{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}"
+    end
+
+    GraphWeaver.log(:debug) { "HTTP #{status} #{tag} from #{url} (#{body.to_s.bytesize} bytes)" }
+
+    parsed = parse_body(body)
+
+    # reached the server, but it returned a non-2xx status. Per
+    # graphql-over-http, routers (Apollo Server/Router) send request
+    # errors as 4xx WITH a GraphQL errors body — those flow into the
+    # 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")
+
+      raise GraphWeaver::ServerError.new(status:, body: body.to_s)
+    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]}")
+    end
+
+    parsed
+  end
+
+  # the parsed body, or nil when it isn't JSON (a caller's connection may
+  # already parse via middleware — pass that through)
+  private def parse_body(body)
+    return body unless body.is_a?(String)
+
+    JSON.parse(body)
+  rescue JSON::ParserError
+    nil
+  end
+
+  # never leak Authorization headers through logs/exceptions — a
+  # transport inspects as its class + endpoint, nothing more
+  def inspect
+    "#<#{self.class.name} url=#{url.inspect}>"
+  end
+  alias to_s inspect
+
+  # "[req 3 FilteredPokemon]" — a per-process request id plus the
+  # operation name (when the document declares one)
+  REQUEST_MUTEX = Mutex.new
+
+  def self.log_tag(query)
+    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}]"
+  end
+
+  # keep debug readable: a 100-line introspection query would drown the
+  # log — the INFO introspection line already carries the timing
+  LOG_QUERY_LIMIT = 600
+  def self.truncate_for_log(query)
+    return query if query.length <= LOG_QUERY_LIMIT
+
+    "#{query[0, LOG_QUERY_LIMIT]}... (truncated, #{query.bytesize} bytes total)"
+  end
+
+  private
+
+  # POST the JSON body to the endpoint; return [status code, raw body].
+  sig { abstract.params(body: String).returns([Integer, T.untyped]) }
+  def post(body); end
+end

data/lib/graph_weaver/version.rb

@@ -1,3 +1,3 @@
 module GraphWeaver
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end