graph_weaver 0.0.1 → 0.2.0

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.0.1"
+  VERSION = "0.2.0"
 end

data/lib/graph_weaver.rb

@@ -1,11 +1,275 @@
 require "graphql"
 require "sorbet-runtime"
 
+require_relative "graph_weaver/logging"
+require_relative "graph_weaver/errors"
+require_relative "graph_weaver/hints"
+require_relative "graph_weaver/response"
+require_relative "graph_weaver/inflect"
 require_relative "graph_weaver/codegen"
-require_relative "graph_weaver/http_executor"
+require_relative "graph_weaver/client"
+require_relative "graph_weaver/transport/http"
+require_relative "graph_weaver/retry"
 require_relative "graph_weaver/schema_loader"
 require_relative "graph_weaver/version"
+require_relative "graph_weaver/railtie" if defined?(::Rails::Railtie)
 
-# opt-in: require "graph_weaver/directive_defaults_patch" to fix
-# graphql-ruby dropping directive argument defaults when loading SDL
-# (needed for Apollo supergraph SDL until rmosolgo/graphql-ruby#5659 ships)
+# opt-in extras:
+#      require "graph_weaver/transport/faraday"        # Faraday transport
+#      require "graph_weaver/directive_defaults_patch" # fix graphql-ruby
+#        dropping directive argument defaults when loading SDL (needed for
+#        Apollo supergraph SDL until rmosolgo/graphql-ruby#5659 ships)
+module GraphWeaver
+  class << self
+    # A client for one GraphQL server — transport, schema, and scoped
+    # scalars in one object (see Client):
+    #
+    #      github = GraphWeaver.new("https://api.github.com/graphql", auth: token, cache: true)
+    #      RepoQuery = github.parse("queries/repo.graphql")
+    #
+    # The first argument is a url or any schema source (a live schema
+    # class, or a path/SDL/introspection dump).
+    def new(source, **options, &middleware)
+      Client.new(source, **options, &middleware)
+    end
+
+    # The app's default client — how generated modules find their server:
+    #
+    #      GraphWeaver.client = GraphWeaver.new(url, auth: token)
+    #
+    # Accepts a Client or anything satisfying the execute contract (a
+    # schema class, a fake — testing's auto_fake swaps one in per
+    # example). Generated modules resolve per call -> per module
+    # (MyQuery.client=) -> baked constant -> here.
+    attr_accessor :client
+
+    # the default client, when one is required
+    def client!
+      @client or raise Error, "no client configured — set GraphWeaver.client= or pass a client"
+    end
+
+    # The transport behind a client-or-transport value: a Client resolves
+    # to its own transport, anything else already speaks execute.
+    # Generated modules call this on every execute, so any slot in the
+    # resolution chain can hold either kind.
+    def resolve_transport(target)
+      target.is_a?(Client) ? target.transport! : target
+    end
+
+    # Conventional locations, factory_bot-style: used as defaults by
+    # generate!, verify_generated!, load_generated!, and the rake tasks;
+    # override the accessors or pass paths.
+    attr_writer :queries_path, :generated_path, :schema_path
+
+    def queries_path = @queries_path || "app/graphql/queries"
+    def generated_path = @generated_path || "app/graphql/generated"
+    def schema_path = @schema_path || "app/graphql/schema.json"
+
+    # Generate every .graphql query in a directory into checked-in Ruby
+    # files. Paths default to the conventions above; schema: defaults to
+    # the dump at schema_path (any supported extension):
+    #
+    #      GraphWeaver.generate!   # queries_path -> generated_path
+    #
+    # person.graphql => person_query.rb defining PersonQuery. Returns the
+    # written paths. Pair with a freshness spec (docs/generated_modules.md).
+    def generate!(schema: nil, queries: queries_path, output: generated_path, client: nil)
+      schema ||= locate_schema!
+      FileUtils.mkdir_p(output)
+
+      each_query(queries, schema:, client:).map do |base, source|
+        target = File.join(output, "#{base}_query.rb")
+        File.write(target, source)
+        log(:info) { "generated #{target}" }
+        target
+      end
+    end
+
+    # The freshness guard: raise unless every generated file matches what
+    # the current schema + queries + scalar registrations would produce.
+    # One line in a spec, or `rake graph_weaver:verify` in CI:
+    #
+    #      it "generated queries are current" do
+    #        GraphWeaver.verify_generated!
+    #      end
+    def verify_generated!(schema: nil, queries: queries_path, output: generated_path, client: nil)
+      schema ||= locate_schema!
+      stale = each_query(queries, schema:, client:).filter_map do |base, source|
+        target = File.join(output, "#{base}_query.rb")
+        target unless File.exist?(target) && File.read(target) == source
+      end
+
+      unless stale.empty?
+        raise Error, "stale generated queries — regenerate (rake graph_weaver:generate): #{stale.join(", ")}"
+      end
+
+      true
+    end
+
+    # Load the generated modules — one line in an initializer or spec
+    # helper (loading happens only when you call this; skip it and
+    # require files yourself if you'd rather):
+    #
+    #      GraphWeaver.load_generated!
+    #
+    # In Rails, prefer this over autoloading: Zeitwerk would expect
+    # Generated::PersonQuery from generated/person_query.rb, and
+    # generated code only changes on regeneration anyway (restart, like
+    # a schema migration).
+    def load_generated!(path = generated_path)
+      files = Dir[File.join(path, "**/*.rb")].sort
+      files.each { |file| require File.expand_path(file) }
+      log(:info) { "loaded #{files.size} generated module(s) from #{path}" }
+      files
+    end
+
+    # the conventional schema dump, required
+    def locate_schema!
+      SchemaLoader.locate or raise Error,
+        "no schema dump at #{schema_path} (.json/.graphql/.gql) — pass schema:, or cache one: GraphWeaver.new(url, cache: true).schema"
+    end
+    private :locate_schema!
+
+    # (base, generated_source) per .graphql file in a directory
+    def each_query(queries, schema:, client:)
+      Dir[File.join(queries, "*.graphql")].sort.map do |path|
+        base = File.basename(path, ".graphql")
+        source = Codegen.generate(
+          schema:,
+          query: File.read(path),
+          module_name: "#{Inflect.camelize(base)}Query",
+          client:,
+        )
+        [base, source]
+      end
+    end
+    private :each_query
+
+    # Default input coercion for scalars that don't say coerce: themselves,
+    # resolved lazily at generation time (so set it any time before you
+    # generate — no reset_scalars! ordering dance):
+    #
+    #      GraphWeaver.auto_coerce = true
+    #
+    # Convertible built-ins take their conversion (Int accepts 5/"5"),
+    # and any scalar with a full cast/serialize pair (Date, your Money)
+    # accepts its raw wire form. An explicit coerce: true/false/Symbol on
+    # a registration always wins.
+    attr_accessor :auto_coerce
+
+    # Teach the generator how a GraphQL custom scalar deserializes into a
+    # rich Ruby object (and serializes back onto the wire when used as a
+    # variable):
+    #
+    #      GraphWeaver.register_scalar("Money", Money, requires: "bigdecimal")
+    #
+    # A field typed `Money` then generates `const :price, T.nilable(Money)`
+    # and casts with `Money.parse(...)` in from_h. Pass a real class as
+    # type: and cast:/serialize: are inferred from it — .parse/#to_s, or
+    # .load/.dump — by probing the deserialize side (see ScalarType::CODECS).
+    # Override with a Symbol method name (safest — no string to misspell), a
+    # Proc(expr) => code string, or :itself to force pass-through. requires:
+    # (a String or Array) names files the generated code needs — validated,
+    # and actually required to confirm it resolves when type: is a real class.
+    # coerce: true makes a variable of this scalar accept the value OR its
+    # raw input (e.g. "12.00"), running the latter through the cast before
+    # serializing — it raises on bad input, so some safety survives. Built-in
+    # scalars are pre-registered the same way, so this also overrides them.
+    # Call before generating.
+    def register_scalar(graphql_name, type, cast: nil, serialize: nil, requires: nil, coerce: nil)
+      Codegen.register_scalar(graphql_name, type, cast:, serialize:, requires:, coerce:)
+    end
+
+    # Map a GraphQL enum onto an app-owned T::Enum, so generated code
+    # speaks YOUR enum — casting wire values in, serializing members out:
+    #
+    #      GraphWeaver.register_enum("Species", PetKind)
+    #
+    # The mapping is inferred by name ("CAT" <-> PetKind::Cat); map: pins
+    # renames, fallback: absorbs unknown wire values on cast (inputs stay
+    # strict), requires: names files the generated code should require.
+    # Generation fails naming any schema value that doesn't resolve —
+    # exhaustiveness checked ahead of runtime. Global; client.register_enum
+    # scopes to one client.
+    def register_enum(graphql_name, type, map: nil, fallback: nil, requires: nil)
+      Codegen.register_enum(graphql_name, type, map:, fallback:, requires:)
+    end
+
+    # Bulk, inference-only form: register_enums("Species" => PetKind, ...)
+    def register_enums(mappings)
+      Codegen.register_enums(mappings)
+    end
+
+    # Include app-owned helper modules into every struct generated from a
+    # GraphQL type — derived values live as methods next to the honest
+    # wire data, and srb tc checks them against each query's selection:
+    #
+    #      GraphWeaver.register_type("Pet", PetHelpers)
+    #
+    # Or build the mixin inline with a block (module_eval'd into an
+    # auto-named module — quick, but invisible to srb tc):
+    #
+    #      GraphWeaver.register_type("Pet") do
+    #        def display_name = "#{name} the pet"
+    #      end
+    #
+    # Additive (repeated and client-scoped registrations stack). Global;
+    # client.register_type scopes to one client.
+    def register_type(graphql_name, *mixins, requires: nil, &block)
+      Codegen.register_type(graphql_name, *mixins, requires:, &block)
+    end
+
+    # Restore the built-in scalars, dropping every custom registration —
+    # the clean slate to reach for between tests or to undo overrides.
+    # (Coercible built-ins are auto_coerce's job, not a reset flavor.)
+    def reset_scalars!
+      Codegen.reset_scalars!
+    end
+
+    # Empty the scalar registry entirely, built-ins included (see
+    # reset_scalars! to restore the defaults).
+    def clear_scalars!
+      Codegen.clear_scalars!
+    end
+
+    # Parse a query into a typed query module:
+    #
+    #      PersonQuery = GraphWeaver.parse(schema:, query: "queries/person.graphql")
+    #
+    # query is a .graphql/.gql path (module name derived from the file
+    # name) or a raw query string (name derived from the operation name,
+    # falling back to "Query" for anonymous operations — collisions are
+    # impossible since each parse gets its own container). Pass name: to
+    # override, client: to bake the module's default client/transport.
+    def parse(schema:, query:, name: nil, client: nil, scalars: nil, enums: nil, types: nil)
+      if query.end_with?(".graphql", ".gql")
+        name ||= "#{Inflect.camelize(File.basename(query, ".*"))}Query"
+        query = File.read(query)
+      end
+
+      Codegen.parse(schema:, query:, module_name: name, client:, scalars:, enums:, types:)
+    end
+
+    # One-shot dynamic execution — a throwaway client, no build step:
+    #
+    #      GraphWeaver.execute(schema, "query($id: ID!) { ... }", id: "1")   # => Response
+    #      GraphWeaver.execute!(url, "query { viewer { login } }")           # => Result (or raise)
+    #
+    # The first argument is a url or schema source, exactly as
+    # GraphWeaver.new; this is Client#execute on a client you don't keep.
+    # (A url source introspects the schema on every call — keep a client
+    # for more than one query.) Variables are plain kwargs, as on a
+    # generated module (nothing reserved). execute returns the
+    # Response envelope, execute! the typed result, raising QueryError on
+    # top-level errors.
+    def execute(source, query, **variables)
+      client = source.is_a?(Client) ? source : Client.new(source)
+      client.execute(query, **variables)
+    end
+
+    # execute + data! — the typed result, or a raised QueryError. See execute.
+    def execute!(source, query, **variables)
+      execute(source, query, **variables).data!
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graph_weaver
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Daniel Pepper
@@ -37,6 +37,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: apollo-federation
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: debug
   requirement: !ruby/object:Gem::Requirement
@@ -51,6 +79,62 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: faker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -121,12 +205,27 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A typed GraphQL client for Ruby — generate Sorbet T::Structs from queries,
   with federation, extensibility, and testing in mind
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock
@@ -135,12 +234,43 @@ files:
 - NOTES.md
 - PLAN.md
 - README.md
+- docs/cassettes.md
+- docs/errors.md
+- docs/generated_modules.md
+- docs/getting_started.md
+- docs/logging.md
+- docs/real_world.md
+- docs/scalars.md
+- docs/testing.md
+- docs/transports.md
 - graph_weaver.gemspec
 - lib/graph_weaver.rb
+- lib/graph_weaver/client.rb
 - lib/graph_weaver/codegen.rb
+- lib/graph_weaver/codegen/emit.rb
+- lib/graph_weaver/codegen/enum_type.rb
+- lib/graph_weaver/codegen/nodes.rb
+- lib/graph_weaver/codegen/scalar_type.rb
 - lib/graph_weaver/directive_defaults_patch.rb
-- lib/graph_weaver/http_executor.rb
+- lib/graph_weaver/errors.rb
+- lib/graph_weaver/hints.rb
+- lib/graph_weaver/inflect.rb
+- lib/graph_weaver/logging.rb
+- lib/graph_weaver/railtie.rb
+- lib/graph_weaver/response.rb
+- lib/graph_weaver/retry.rb
+- lib/graph_weaver/rspec.rb
 - lib/graph_weaver/schema_loader.rb
+- lib/graph_weaver/selection.rb
+- lib/graph_weaver/tasks.rb
+- lib/graph_weaver/testing.rb
+- lib/graph_weaver/testing/cassette.rb
+- lib/graph_weaver/testing/failure.rb
+- lib/graph_weaver/testing/fake_client.rb
+- lib/graph_weaver/testing/values.rb
+- lib/graph_weaver/transport.rb
+- lib/graph_weaver/transport/faraday.rb
+- lib/graph_weaver/transport/http.rb
 - lib/graph_weaver/version.rb
 homepage: https://github.com/dpep/graph_weaver
 licenses:

data/lib/graph_weaver/http_executor.rb

@@ -1,31 +0,0 @@
-# typed: true
-# frozen_string_literal: true
-
-require "json"
-require "sorbet-runtime"
-require "net/http"
-require "uri"
-
-# Minimal HTTP transport satisfying the generated modules' executor
-# interface: execute(query, variables:) => {"data" => ..., "errors" => ...}
-class GraphWeaver::HttpExecutor
-  def initialize(url, headers: {})
-    @uri = URI(url)
-    @headers = headers
-  end
-
-  def execute(query, variables: {})
-    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)
-    end
-
-    unless response.is_a?(Net::HTTPSuccess)
-      raise "HTTP #{response.code}: #{response.body}"
-    end
-
-    JSON.parse(T.must(response.body))
-  end
-end