graph_weaver 0.0.1 → 0.1.0

data/lib/graph_weaver/errors.rb

@@ -0,0 +1,310 @@
+# typed: true
+# frozen_string_literal: true
+
+require "set"
+require "sorbet-runtime"
+require_relative "inflect"
+
+module GraphWeaver
+  # Base for every error GraphWeaver raises — rescue this to catch them
+  # all. #message is the human-friendly side; #to_h is the machine side —
+  # a JSON-ready Hash (string keys) for logging, agents, or surfacing
+  # structured failures to users. Subclasses merge in their specifics.
+  class Error < StandardError
+    def to_h
+      { "error" => self.class.name, "message" => message }
+    end
+  end
+
+  # The request never reached the server: connection refused, DNS failure,
+  # TLS handshake, timeout. The original exception is preserved as #cause.
+  # Generally retriable.
+  class TransportError < Error
+    def to_h
+      super.merge("cause" => cause&.class&.name)
+    end
+  end
+
+  class << self
+    # The exception classes the bundled executors reclassify as
+    # TransportError — network-level failures where the request never
+    # reached the server. A mutable Set: each transport contributes its own
+    # on load (net/http adds Timeout/SSL, Faraday adds its ConnectionFailed,
+    # …), and you can add more so they get the same handling:
+    #
+    #   GraphWeaver.transport_errors << MyPool::TimeoutError
+    #   GraphWeaver.register_transport_error(Adapter::ResetError)
+    #
+    # SystemCallError covers every Errno::* (connection refused/reset, host
+    # unreachable); SocketError covers DNS.
+    def transport_errors
+      @transport_errors ||= Set[SocketError, SystemCallError, IOError]
+    end
+
+    # Add one or more exception classes to the transport-error set.
+    def register_transport_error(*classes)
+      transport_errors.merge(classes)
+      classes
+    end
+  end
+
+  # The request reached the server but it returned a non-2xx status — a 500
+  # that exploded, a 502 from a proxy, a 401, etc. Distinct from a GraphQL
+  # error: we got an HTTP response, it just wasn't success.
+  class ServerError < Error
+    attr_reader :status, :body
+
+    def initialize(status:, body: nil)
+      @status = status
+      @body = body
+      snippet = body.to_s.empty? ? "" : ": #{body.to_s[0, 500]}"
+      super("HTTP #{status}#{snippet}")
+    end
+
+    def to_h
+      super.merge("status" => status)
+    end
+  end
+
+  # One entry from a GraphQL response's top-level `errors` array. A value
+  # object (not raised) — the response envelope and QueryError carry these.
+  # Match on #code (extensions["code"]) rather than the message string.
+  class GraphQLError
+    attr_reader :message, :locations, :path, :extensions
+
+    def initialize(message:, locations: [], path: nil, extensions: {})
+      @message = message
+      @locations = locations
+      @path = path
+      @extensions = extensions
+    end
+
+    def self.from_h(hash)
+      new(
+        message: hash["message"] || "(no message)",
+        locations: hash["locations"] || [],
+        path: hash["path"],
+        extensions: hash["extensions"] || {},
+      )
+    end
+
+    # The machine-readable error code, e.g. "THROTTLED" — the thing to
+    # branch on. nil when the server didn't set extensions.code.
+    def code
+      extensions["code"]
+    end
+
+    # Message shapes servers use when they reject the *shape* of a query
+    # (unknown field/type/argument). Heuristic by necessity: only Apollo
+    # sets a standard code (GRAPHQL_VALIDATION_FAILED); graphql-ruby and
+    # GitHub speak in messages.
+    VALIDATION_MESSAGE = /doesn't exist|Cannot query field|Unknown (field|type|argument)|isn't defined|undefined (field|type)/i
+
+    # True when this error looks like the server rejected the query's
+    # shape — for a generated module that usually means the schema
+    # changed after generation.
+    def validation?
+      code == "GRAPHQL_VALIDATION_FAILED" || VALIDATION_MESSAGE.match?(message)
+    end
+
+    # The field the error points at, as a stable dotted path with list
+    # indices stripped — ["people", 3, "email"] => "people.email". The
+    # parseable key for grouping/reporting (the raw #path keeps indices).
+    # nil for global errors with no path.
+    def field
+      return unless path
+
+      named = path.reject { |seg| seg.is_a?(Integer) || seg.to_s.match?(/\A\d+\z/) }
+      named.join(".") unless named.empty?
+    end
+
+    def to_s
+      loc = locations&.first
+      at = loc ? " at #{loc["line"]}:#{loc["column"]}" : ""
+      where = path ? " (path: #{path.join(".")})" : ""
+      tag = code ? " [#{code}]" : ""
+      "#{message}#{at}#{where}#{tag}"
+    end
+
+    # JSON-ready: the problematic field (both forms — #field for grouping,
+    # #path with indices for exact location), the machine code, and the
+    # server's full extensions.
+    def to_h
+      {
+        "message" => message,
+        "code" => code,
+        "field" => field,
+        "path" => path,
+        "locations" => locations,
+        "extensions" => extensions,
+        "validation" => validation?,
+      }
+    end
+  end
+
+  # Shared filtering over a collection of GraphQLErrors, for surfacing
+  # field-level failures programmatically. Host must define #errors.
+  module ErrorFiltering
+    include Kernel # for sorbet: hosts are Objects
+
+    # the host's interface, overridden by its attr_readers
+    def errors
+      raise NotImplementedError, "#{self.class} must define #errors"
+    end
+
+    def data
+      raise NotImplementedError, "#{self.class} must define #data"
+    end
+
+    # Errors touching a field path — "user.email" or ["user", "email"];
+    # prefix match, so deeper errors count too. List indices appear as
+    # path segments ("people.0.email").
+    def errors_at(path)
+      want = (path.is_a?(String) ? path.split(".") : path).map(&:to_s)
+      errors.select { |error| error.path && error.path.map(&:to_s).first(want.size) == want }
+    end
+
+    # True when any error looks like the server rejected the query's
+    # shape — the schema has likely changed since the module was
+    # generated. Regenerate (bin/generate) and/or refresh the schema
+    # cache (delete the cache: file, or wait out its ttl).
+    def schema_stale?
+      errors.any?(&:validation?)
+    end
+
+    # Errors grouped by the field they point at (index-stripped dotted
+    # path; nil key for global errors) — iterate with each_error:
+    #
+    #   response.each_error do |field, errors|
+    #     form.add_error(field, errors.map(&:message))
+    #   end
+    def errors_by_field
+      errors.group_by(&:field)
+    end
+
+    def each_error(&block)
+      errors_by_field.each(&block)
+    end
+
+    # The id of the record an error points into, resolved by walking the
+    # error's path through the (partial) typed data: an error at
+    # ["people", 3, "email"] resolves to people[3].id. nil when the data
+    # is missing, the path doesn't walk, or the record has no id field.
+    def entity_id(error)
+      # untyped by nature: the walk traverses whatever structs this query
+      # generated, reassigning across types at each step
+      node = T.let(data, T.untyped)
+      return unless node && error.path
+
+      error.path[0..-2].each do |segment|
+        node = if segment.is_a?(Integer) || segment.to_s.match?(/\A\d+\z/)
+          node.is_a?(Array) ? node[segment.to_i] : nil
+        else
+          prop = GraphWeaver::Inflect.underscore(segment.to_s).to_sym
+          node.respond_to?(prop) ? node.public_send(prop) : nil
+        end
+        return if node.nil?
+      end
+
+      node.respond_to?(:id) ? node.id : nil
+    end
+
+    # The user-facing rollup: errors keyed by field, with the ids of the
+    # actual records that failed inlined — "the 3 in people.3.email is
+    # useless to a user; people.email plus which people is the answer".
+    #
+    #   { "people.email" => { "messages" => [...], "codes" => [...],
+    #     "entity_ids" => ["7", "9"], "errors" => [full to_h...] } }
+    def report
+      errors_by_field.to_h do |field, field_errors|
+        [field, {
+          "messages" => field_errors.map(&:message),
+          "codes" => field_errors.filter_map(&:code).uniq,
+          "entity_ids" => field_errors.filter_map { |e| entity_id(e) }.uniq,
+          "errors" => field_errors.map(&:to_h),
+        }]
+      end
+    end
+  end
+
+  # Raised when a GraphQL response carried top-level errors and the caller
+  # demanded data (Response#data!, or the one-shot GraphWeaver.execute).
+  # Carries the structured errors, any partial data, and top-level
+  # extensions (cost/throttle metadata).
+  class QueryError < Error
+    include ErrorFiltering
+
+    attr_reader :errors, :data, :extensions
+
+    def initialize(errors, data: nil, extensions: {})
+      @errors = errors
+      @data = data
+      @extensions = extensions
+      super(summary)
+    end
+
+    # All non-nil error codes — handy for `codes.include?("THROTTLED")`.
+    def codes
+      errors.map(&:code).compact
+    end
+
+    # The machine side: every error with its path/code/extensions, plus
+    # the drift verdict — nest this straight into a JSON response.
+    def to_h
+      super.merge(
+        "schema_stale" => schema_stale?,
+        "codes" => codes,
+        "errors" => errors.map(&:to_h),
+        "extensions" => extensions,
+      )
+    end
+
+    private
+
+    def summary
+      first = errors.first
+      more = errors.size > 1 ? " (and #{errors.size - 1} more)" : ""
+      drift = schema_stale? ? " — the server rejected the query shape: the schema may have changed since generation; regenerate modules (bin/generate) and/or refresh the schema cache" : ""
+      "GraphQL query failed: #{first}#{more}#{drift}"
+    end
+  end
+
+  # Raised when a response can't be cast into the generated structs — the
+  # wire data disagreed with the types the schema promised at generation
+  # time (a nil where non-null was declared, a malformed scalar, an
+  # unknown enum value). #struct names the generated type that failed;
+  # #cause carries the original TypeError/KeyError with the offending
+  # prop in its message.
+  class TypeError < Error
+    attr_reader :struct
+
+    def initialize(struct:, error: nil, message: nil)
+      @struct = struct
+      super("failed to cast response into #{struct}: #{message || error&.message}")
+    end
+
+    def to_h
+      super.merge("struct" => struct.to_s, "cause" => cause&.message)
+    end
+  end
+
+  # Build-time: the query didn't validate against the schema. Kept an
+  # ArgumentError for source compatibility, but carries the structured
+  # validation errors (message + line/column) rather than a joined string.
+  class ValidationError < ArgumentError
+    attr_reader :errors
+
+    def initialize(errors)
+      @errors = errors
+      super("invalid query: #{errors.map { |e| e[:message] }.join("; ")}")
+    end
+
+    def to_h
+      {
+        "error" => self.class.name,
+        "message" => message,
+        "errors" => errors.map { |e| e.transform_keys(&:to_s) },
+      }
+    end
+  end
+end

data/lib/graph_weaver/faraday_executor.rb

@@ -0,0 +1,61 @@
+# typed: true
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+require_relative "errors"
+
+# Faraday-backed transport. Opt-in (faraday is not a hard dependency):
+#
+#   require "graph_weaver/faraday_executor"
+#
+#   # simplest: build a default connection from a url
+#   GraphWeaver::FaradayExecutor.new("https://api.example.com/graphql")
+#
+#   # customize middleware while building
+#   GraphWeaver::FaradayExecutor.new(url) do |conn|
+#     conn.request :authorization, "Bearer", -> { Tokens.fetch }
+#     conn.response :logger
+#   end
+#
+#   # or bring a fully configured connection
+#   GraphWeaver::FaradayExecutor.new(Faraday.new(url:) { |conn| ... })
+class GraphWeaver::FaradayExecutor
+  # 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
+  end
+
+  def execute(query, variables: {})
+    response = begin
+      @connection.post do |request|
+        request.headers["Content-Type"] = "application/json"
+        request.body = JSON.generate(query:, variables:)
+      end
+    rescue *GraphWeaver.transport_errors.to_a => e
+      # never got a response — connection refused/reset, TLS, timeout
+      raise GraphWeaver::TransportError, "#{e.class}: #{e.message}"
+    end
+
+    # reached the server, but it returned a non-2xx status
+    unless response.success?
+      raise GraphWeaver::ServerError.new(status: response.status, body: response.body.to_s)
+    end
+
+    body = response.body
+    # a caller's connection may already parse json via middleware
+    body.is_a?(String) ? JSON.parse(body) : body
+  end
+end

data/lib/graph_weaver/http_executor.rb

@@ -4,11 +4,18 @@
 require "json"
 require "sorbet-runtime"
 require "net/http"
+require "openssl"
 require "uri"
 
+require_relative "errors"
+
 # Minimal HTTP transport satisfying the generated modules' executor
 # interface: execute(query, variables:) => {"data" => ..., "errors" => ...}
 class GraphWeaver::HttpExecutor
+  # 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: {})
     @uri = URI(url)
     @headers = headers
@@ -18,12 +25,18 @@ class GraphWeaver::HttpExecutor
     request = Net::HTTP::Post.new(@uri, { "Content-Type" => "application/json" }.merge(@headers))
     request.body = JSON.generate(query:, variables:)
 
-    response = Net::HTTP.start(@uri.hostname, @uri.port, use_ssl: @uri.scheme == "https") do |http|
-      http.request(request)
+    response = begin
+      Net::HTTP.start(@uri.hostname, @uri.port, use_ssl: @uri.scheme == "https") do |http|
+        http.request(request)
+      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
 
+    # reached the server, but it returned a non-2xx status
     unless response.is_a?(Net::HTTPSuccess)
-      raise "HTTP #{response.code}: #{response.body}"
+      raise GraphWeaver::ServerError.new(status: response.code.to_i, body: response.body)
     end
 
     JSON.parse(T.must(response.body))

data/lib/graph_weaver/inflect.rb

@@ -0,0 +1,18 @@
+# typed: true
+# frozen_string_literal: true
+
+module GraphWeaver
+  # GraphQL names are plain camelCase/SCREAMING_SNAKE — no acronym edge
+  # cases, so minimal inflection beats an activesupport dependency
+  module Inflect
+    module_function
+
+    def underscore(name)
+      name.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+    end
+
+    def camelize(name)
+      name.split("_").map { |part| "#{part[0].upcase}#{part[1..]}" }.join
+    end
+  end
+end

data/lib/graph_weaver/response.rb

@@ -0,0 +1,55 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require_relative "errors"
+
+module GraphWeaver
+  # The envelope every generated #execute returns: the typed data (nil on a
+  # total failure), the top-level GraphQL errors, and top-level extensions
+  # (cost/throttle metadata). Generic over the query's Result type so
+  # response.data stays fully typed — the generated code instantiates it as
+  # GraphWeaver::Response[SomeQuery::Result]. #data! is the strict accessor:
+  # the result, or a raised QueryError.
+  class Response
+    extend T::Sig
+    extend T::Generic
+    include ErrorFiltering
+
+    Data = type_member
+
+    sig { returns(T.nilable(Data)) }
+    attr_reader :data
+
+    sig { returns(T::Array[GraphWeaver::GraphQLError]) }
+    attr_reader :errors
+
+    sig { returns(T::Hash[String, T.untyped]) }
+    attr_reader :extensions
+
+    sig do
+      params(
+        data: T.nilable(Data),
+        errors: T::Array[GraphWeaver::GraphQLError],
+        extensions: T::Hash[String, T.untyped],
+      ).void
+    end
+    def initialize(data:, errors: [], extensions: {})
+      @data = data
+      @errors = errors
+      @extensions = extensions
+    end
+
+    sig { returns(T::Boolean) }
+    def errors? = !errors.empty?
+
+    # The typed result, or raise QueryError if the response carried top-level
+    # errors (partial data and extensions ride along on the error).
+    sig { returns(Data) }
+    def data!
+      raise GraphWeaver::QueryError.new(errors, data: data, extensions: extensions) unless errors.empty?
+      T.must(data)
+    end
+  end
+end

data/lib/graph_weaver/rspec.rb

@@ -0,0 +1,54 @@
+# typed: true
+# frozen_string_literal: true
+
+require_relative "testing"
+
+# RSpec integration — require from your spec helper instead of
+# "graph_weaver/testing":
+#
+#   require "graph_weaver/rspec"
+#
+#   GraphWeaver::Testing.configure do |config|
+#     config.schema = MySchema
+#     config.auto_fake = true   # every example runs against a FakeExecutor
+#   end
+#
+# What it wires up:
+#   - seed: defaults to rspec's --seed, so `rspec --seed 1234` reproduces
+#     fake data along with test order
+#   - auto_fake: when on (and schema is set), each example gets a fresh
+#     seeded FakeExecutor installed as GraphWeaver.executor — generated
+#     modules run in test mode with zero per-test setup. The prior
+#     executor is restored after each example.
+#
+# note: modules generated with a baked-in executor: constant don't consult
+# GraphWeaver.executor — generate without executor: to make them fakeable.
+module GraphWeaver
+  module Testing
+    module RSpecIntegration
+      def self.install(rspec_config)
+        rspec_config.before(:suite) do
+          config = GraphWeaver::Testing.config
+          config.seed ||= RSpec.configuration.seed
+        end
+
+        rspec_config.before(:each) do
+          config = GraphWeaver::Testing.config
+          next unless config.auto_fake && config.schema
+
+          @__graph_weaver_prior_executor = GraphWeaver.instance_variable_get(:@executor)
+          GraphWeaver.executor = FakeExecutor.new(schema: config.schema)
+        end
+
+        rspec_config.after(:each) do
+          config = GraphWeaver::Testing.config
+          next unless config.auto_fake && config.schema
+
+          GraphWeaver.executor = @__graph_weaver_prior_executor
+        end
+      end
+    end
+  end
+end
+
+RSpec.configure { |config| GraphWeaver::Testing::RSpecIntegration.install(config) } if defined?(RSpec)

data/lib/graph_weaver/schema_loader.rb

@@ -1,20 +1,84 @@
 # typed: true
 # frozen_string_literal: true
 
+require "fileutils"
 require "graphql"
 require "json"
+require_relative "errors"
 
 # Load a schema for codegen from either format a remote service can hand
-# you: an introspection dump (.json) or SDL (.graphql/.gql).
+# you — introspection JSON or SDL, as a file path or the content itself —
+# or fetch one straight from a live endpoint via introspect.
 module GraphWeaver::SchemaLoader
-  def self.load(path)
-    case File.extname(path)
-    when ".json"
-      GraphQL::Schema.from_introspection(JSON.parse(File.read(path)))
-    when ".graphql", ".gql"
-      GraphQL::Schema.from_definition(File.read(path))
-    else
-      raise ArgumentError, "unsupported schema format: #{path}"
+  # Accepts, and detects:
+  #   - a Hash (a parsed introspection result)
+  #   - a file path — .json (introspection) or .graphql/.gql (SDL)
+  #   - raw content — introspection JSON (starts with "{") or SDL
+  # so a cache round-trip is symmetrical with introspect:
+  #   SchemaLoader.load(cached_json)  # from Rails.cache/redis/...
+  def self.load(source)
+    return GraphQL::Schema.from_introspection(source) if source.is_a?(Hash)
+
+    if source.lstrip.start_with?("{") # introspection JSON content
+      GraphQL::Schema.from_introspection(JSON.parse(source))
+    elsif source.include?("\n") # multi-line: SDL content
+      unless source.match?(/^\s*(schema|type|interface|union|enum|scalar|directive|input|")/)
+        raise ArgumentError, "unsupported schema content: #{source.lstrip[0, 80].inspect}"
+      end
+
+      GraphQL::Schema.from_definition(source)
+    else # a file path
+      case File.extname(source)
+      when ".json"
+        GraphQL::Schema.from_introspection(JSON.parse(File.read(source)))
+      when ".graphql", ".gql"
+        GraphQL::Schema.from_definition(File.read(source))
+      else
+        raise ArgumentError, "unsupported schema format: #{source}"
+      end
+    end
+  end
+
+  # Run the standard introspection query through an executor and build a
+  # schema from the result:
+  #
+  #   executor = GraphWeaver::HttpExecutor.new(url, headers: { ... })
+  #   schema = GraphWeaver::SchemaLoader.introspect(executor)
+  #
+  # Introspecting a large API takes seconds, so cache: (a file path)
+  # stores the raw introspection JSON and reuses it until ttl: seconds
+  # elapse (no ttl = until the file is deleted). GraphQL has no standard
+  # schema-version signal to invalidate on — a stale cache surfaces as
+  # server-side validation errors (see QueryError#schema_stale?), so pick
+  # a ttl that matches how fast the API moves, or delete the file.
+  #
+  # To cache anywhere else (Rails.cache, redis, ...), serialize the schema
+  # itself — schemas round-trip through their introspection JSON:
+  #
+  #   json = Rails.cache.fetch("gh_schema", expires_in: 12.hours) do
+  #     GraphWeaver::SchemaLoader.introspect(executor).to_json
+  #   end
+  #   schema = GraphWeaver::SchemaLoader.load(json)
+  def self.introspect(executor, cache: nil, ttl: nil)
+    if cache && fresh?(cache, ttl)
+      return GraphQL::Schema.from_introspection(JSON.parse(File.read(cache)))
+    end
+
+    result = executor.execute(GraphQL::Introspection.query, variables: {}).to_h
+    if (errors = result["errors"])
+      raise GraphWeaver::Error, "introspection failed: #{errors.inspect}"
+    end
+
+    if cache
+      FileUtils.mkdir_p(File.dirname(cache))
+      File.write(cache, JSON.generate(result))
     end
+
+    GraphQL::Schema.from_introspection(result)
+  end
+
+  def self.fresh?(path, ttl)
+    File.exist?(path) && (ttl.nil? || Time.now - File.mtime(path) < ttl)
   end
+  private_class_method :fresh?
 end