graph_weaver 0.0.1 → 0.2.0

data/docs/testing.md

@@ -0,0 +1,103 @@
+# Testing
+
+Everything here is a *client* — the one interface queries run
+through: anything with `execute(query, variables:)` returning
+`{"data" => ..., "errors" => ...}` (see [transports](transports.md)).
+Fakes, failures, and cassettes all slot in wherever a real transport
+would.
+
+`require "graph_weaver/rspec"` from your spec helper (or
+`graph_weaver/testing` outside rspec — never in production) for a
+zero-setup fake backend. `FakeClient` fabricates
+schema-correct responses for whatever query arrives: real enum values,
+valid `__typename` members, iso8601 date scalars — every fake casts
+cleanly through your generated structs.
+
+```ruby
+fake = GraphWeaver::Testing::FakeClient.new(schema:)
+
+person = PersonQuery.execute!(fake, id: "1").person
+person.name       # => "Eliza Kertzmann" (faker-matched on field name, when faker is loaded)
+person.birthday   # => a real Date
+```
+
+Pin what matters, keyed by GraphQL names (schema vocabulary — keys
+survive query refactors); `"Type.field"` beats `"field"`:
+
+```ruby
+GraphWeaver::Testing::FakeClient.new(schema:, overrides: {
+  "Person.name" => "Daniel",
+  "email" => -> { "test@example.com" },
+})
+```
+
+With rspec, one line in `spec/support/graph_weaver.rb` is the whole
+default setup — the schema auto-locates from the committed dump at
+`GraphWeaver.schema_path`, and `auto_fake` defaults on:
+
+```ruby
+require "graph_weaver/rspec"   # seed follows --seed; every example auto-fakes
+```
+
+Configure to override any of it:
+
+```ruby
+GraphWeaver::Testing.configure do |config|
+  config.schema = MySchema             # an in-process class instead of the located dump
+  config.auto_fake = false             # opt out of per-example fakes
+  config.mode = :faker                 # or :literal (plain typed values); nil = auto
+  config.overrides = { "Person.name" => "Daniel" }
+  config.list_size = 1..3
+  config.null_chance = 0.1             # nullable fields go nil sometimes
+end
+```
+
+With the rspec integration, `rspec --seed 1234` reproduces fake data
+along with test order, and `auto_fake` installs a seeded fake as the
+app client per example (generate modules *without* a baked `client:` so
+they consult `GraphWeaver.client`). `mode:` picks value fabrication: `:faker`
+(semantic, field-name matched — raises if the gem is missing),
+`:literal` (plain type-derived), or nil to auto-detect faker.
+
+**Simulating failures** — every failure mode is just a client, so
+error-handling paths are testable without a server that misbehaves on cue:
+
+```ruby
+Failure = GraphWeaver::Testing::Failure
+
+PersonQuery.execute(id: "1", client: Failure.transport)             # TransportError (cause preserved)
+PersonQuery.execute(id: "1", client: Failure.server(status: 502))   # ServerError
+PersonQuery.execute(id: "1", client: Failure.throttled)             # QueryError, code THROTTLED
+PersonQuery.execute(id: "1", client: Failure.stale_schema)          # schema_stale? => true
+PersonQuery.execute(id: "1", client: Failure.graphql("boom", data: {...}))  # partial failure
+
+# retries: clients run in sequence (the last repeats) — here, two
+# transport failures and then a FakeClient serving good responses
+fake = GraphWeaver::Testing::FakeClient.new(schema:)
+GraphWeaver::Testing::Sequence.new(Failure.transport, Failure.transport, fake)
+
+# type mismatch: corrupt: derives a wrong-typed wire value for the field —
+# casting raises GraphWeaver::TypeError (overrides remain the manual escape hatch)
+GraphWeaver::Testing::FakeClient.new(schema:, corrupt: "Person.birthday")
+
+# stale schema naming a real (sampled) field
+Failure.stale_schema(schema: MySchema)
+
+# field-level partial failure with real GraphQL null propagation: the error
+# lands with its concrete path and nulls bubble to the nearest nullable spot
+GraphWeaver::Testing::FakeClient.new(schema:, fail_at: { path: "person.email", code: "PRIVATE" })
+```
+
+**Capture and replay** — cassettes record real API responses and replay
+them offline, above the transport (no HTTP interception):
+
+```ruby
+# records against the live client when the file is missing, replays after
+cassette = GraphWeaver::Testing::Cassette.use("github", client: live)
+```
+
+Re-record with `GRAPHWEAVER_RECORD=1`, anonymize before committing
+(`config.anonymize = true` scrubs as recordings happen, or
+`rake graph_weaver:cassettes:anonymize` after) — the full workflow guide
+is **[cassettes](cassettes.md)**.
+

data/docs/transports.md

@@ -0,0 +1,124 @@
+# Transports
+
+A *client* is anything with `execute(query, variables:)` whose result
+`to_h`s into `{"data" => ..., "errors" => ...}` — from a full
+`GraphWeaver::Client` down to a schema class (in-process execution), a
+[FakeClient](testing.md), or anything you write. Every slot that takes a
+client accepts any of them.
+
+A *transport* is the network end of that contract — GraphQL-over-HTTP. The bundled
+two — `Transport::HTTP` (net/http, zero dependencies, loaded by default)
+and `Transport::Faraday` (opt-in) — subclass `GraphWeaver::Transport`,
+which owns the shared flow: encode the request, reclassify network
+failures as `TransportError`, raise `ServerError` on non-2xx, parse the
+body. A subclass only implements `post(body) => [status, body]` — that's
+the whole recipe for bringing your own HTTP client.
+
+## One-shot setup: a client
+
+Most apps need one line:
+
+```ruby
+github = GraphWeaver.new("https://api.example.com/graphql", auth: ENV["API_TOKEN"])
+```
+
+`GraphWeaver.new` builds a [`Client`](real_world.md): the best transport
+with auth applied (exposed as `client.transport`), the schema
+introspected lazily, and `parse`/`execute` bound to both.
+
+- `auth:` — a token; "Bearer" is assumed unless the string carries its own
+  scheme (`"Basic dXNlcjpwYXNz..."`)
+- `headers:` — anything else (API keys, custom headers)
+- `retries:` — off by default; `true` for a `Retry` with defaults,
+  or a Hash of its options
+- `cache:` / `ttl:` — schema introspection caching (see
+  [real world](real_world.md)); url clients only — a schema source never
+  introspects, so passing them raises
+- a block customizes the Faraday connection (Faraday only — raises without it)
+
+To wire generated modules that don't bake a client, make it the app's
+default: `GraphWeaver.client = github`. Anything satisfying the execute
+contract works there — testing's auto_fake swaps in a fake per example.
+
+**Transport pick**: `Transport::Faraday` when the app already loads
+faraday (its middleware/proxy/timeout ecosystem comes along), the
+zero-dependency `Transport::HTTP` otherwise. Detection is `defined?(Faraday)` —
+deliberately *not* a require: faraday rides along transitively in most
+bundles (stripe, octokit, ...), and try-requiring would silently switch
+transports on apps that never chose it. With faraday under
+`require: false`, load it before building the client.
+
+## Building blocks
+
+The client is convenience, not the only door — construct and assign
+yourself for full control:
+
+```ruby
+# zero-dependency Net::HTTP — persistent (keep-alive) connection,
+# mutex-serialized; timeouts raise retriable TransportError
+GraphWeaver::Transport::HTTP.new(
+  url,
+  headers: { ... },
+  open_timeout: 10, read_timeout: 30,  # seconds (the defaults)
+  keep_alive_timeout: 2,               # idle window before reconnecting
+)
+
+# Faraday: a url (+ optional middleware block), or a ready connection
+GraphWeaver::Transport::Faraday.new(url) do |conn|
+  conn.request :authorization, "Bearer", -> { Tokens.fetch }  # dynamic tokens
+  conn.response :logger
+end
+GraphWeaver::Transport::Faraday.new(MyApp.faraday_connection)
+
+# One Faraday::Connection is reused for the transport's lifetime, but
+# socket keep-alive depends on the ADAPTER: Faraday's default net_http
+# adapter opens a fresh connection per request. For persistent sockets
+# (and real pooling), pick a persistent adapter:
+GraphWeaver::Transport::Faraday.new(url) do |conn|
+  conn.adapter :net_http_persistent   # gem "net-http-persistent"
+end
+
+GraphWeaver.client = ...   # the app default (a Client or any of the above)
+```
+
+## Client resolution
+
+The canonical order — how a generated module finds its client (each slot
+takes a `Client` or any bare transport/fake):
+
+1. per call: `execute(some_client, ...)` — the optional first positional
+   argument, so variables keep the entire kwarg namespace
+2. per module: `MyQuery.client = something`
+3. baked constant: `Codegen.generate(..., client: MyApi::CLIENT)`
+4. the app default: `GraphWeaver.client=`
+
+Nothing set anywhere raises with a message saying which knobs exist.
+
+## Retries
+
+`Retry` wraps any client/transport:
+
+```ruby
+GraphWeaver::Retry.new(
+  inner_transport,
+  tries: 5,                        # total attempts, first included
+  backoff: :exponential,           # or :linear, or ->(attempt) { seconds }
+  base: 0.5, max: 30,              # seconds; delays clamp at max:
+  jitter: true,                    # randomize each delay by 50-100%
+  on: [GraphWeaver::TransportError, GraphWeaver::ServerError],
+  retry_if: ->(error) { ... },     # fine-grain within on:
+  retry_codes: ["THROTTLED"],      # also retry GraphQL errors by code
+)
+```
+
+Defaults: transport failures always retry (the request never arrived);
+`ServerError` only on 5xx — a 4xx is a bug in the request, retrying won't
+fix it. `retry_codes:` re-inspects response envelopes so GraphQL-level
+throttling can retry too (off by default — pass the codes your API uses).
+Exhausting `tries:` re-raises the last error (or returns the last
+code-matched response).
+
+Or via the client: `GraphWeaver.new(url, retries: { tries: 5, retry_codes: ["THROTTLED"] })`.
+
+What classifies as a transport failure is an extensible set — see
+[errors](errors.md#extending-transporterror) (`GraphWeaver.register_transport_error`).

data/graph_weaver.gemspec

@@ -3,7 +3,9 @@ require_relative "lib/graph_weaver/version"
 Gem::Specification.new do |s|
   s.authors     = ["Daniel Pepper"]
   s.description = "A typed GraphQL client for Ruby — generate Sorbet T::Structs from queries, with federation, extensibility, and testing in mind"
-  s.files       = `git ls-files * ':!:spec' ':!:sorbet' ':!:bin'`.split("\n")
+  # ".yardopts" explicitly: `git ls-files *` skips dotfiles, and
+  # rubydoc.info needs it shipped to render docstrings as markdown
+  s.files       = `git ls-files * ':!:spec' ':!:sorbet' ':!:bin' ':!:examples'`.split("\n") + [".yardopts"]
   s.homepage    = "https://github.com/dpep/graph_weaver"
   s.license     = "MIT"
   s.name        = "graph_weaver"
@@ -15,10 +17,17 @@ Gem::Specification.new do |s|
   s.add_dependency "graphql", ">= 2"
   s.add_dependency "sorbet-runtime"
 
+  s.add_development_dependency "apollo-federation" # federation integration subgraphs
+  s.add_development_dependency "bigdecimal"
   s.add_development_dependency "debug"
+  s.add_development_dependency "faker"
+  s.add_development_dependency "faraday"
+  s.add_development_dependency "rake"
+  s.add_development_dependency "redcarpet" # yard --markup markdown
   s.add_development_dependency "rspec"
   s.add_development_dependency "simplecov"
   s.add_development_dependency "sorbet"
   s.add_development_dependency "tapioca"
   s.add_development_dependency "webrick"
+  s.add_development_dependency "yard"
 end

data/lib/graph_weaver/client.rb

@@ -0,0 +1,200 @@
+# typed: true
+# frozen_string_literal: true
+
+require_relative "codegen"
+require_relative "errors"
+require_relative "inflect"
+require_relative "retry"
+require_relative "schema_loader"
+require_relative "transport/http"
+
+# One object tying the whole flow together — transport, schema, and
+# generation:
+#
+#      github = GraphWeaver.new("https://api.github.com/graphql", auth: token, cache: true)
+#      github.register_scalar("DateTime", Time, serialize: :iso8601, requires: "time")
+#
+#      RepoQuery = github.parse("queries/repo.graphql")   # implicit schema + transport
+#      github.execute!("query { viewer { login } }")      # one-shot
+#
+# The first argument is a url (a transport is built; the schema comes
+# from introspection on first use, cached per cache:/ttl:) or a schema
+# source — a live schema class (which also executes in-process), or a
+# path/SDL/introspection dump via SchemaLoader. Pass transport: to
+# bring your own transport for a schema source.
+#
+# Clients are independent: each has its own transport, schema, and
+# scalar registrations, so one app can talk to several GraphQL servers —
+# even ones that disagree about what a "DateTime" is.
+class GraphWeaver::Client
+  URL = %r{\Ahttps?://}i
+
+  def initialize(source, auth: nil, headers: {}, retries: false, transport: nil, cache: nil, ttl: nil, &middleware)
+    if source.is_a?(String) && source.match?(URL)
+      raise ArgumentError, "pass a url or transport:, not both" if transport
+
+      @transport = wrap_retries(build_transport(source, auth:, headers:, &middleware), retries)
+    else
+      if auth || middleware || retries != false
+        raise ArgumentError, "auth:/retries:/middleware apply to a url — got a schema source"
+      end
+      if cache || ttl
+        # a schema source never introspects, so a cache would silently no-op
+        raise ArgumentError, "cache:/ttl: apply to url introspection — got a schema source"
+      end
+
+      # a live schema class doubles as an in-process transport; a loaded
+      # dump has no resolvers, so it is type information only
+      @schema = source.is_a?(Module) ? source : GraphWeaver::SchemaLoader.load(source)
+      @transport = transport || (source if source.is_a?(Module))
+    end
+
+    @cache = cache
+    @ttl = ttl
+    @scalars = {}
+    @enums = {}
+    @types = {}
+  end
+
+  # The transport queries run through: a url-built transport, an
+  # explicit transport:, or the live schema class executing in-process.
+  # Clients are self-contained — the app default never leaks in; nil for
+  # schema-dump clients (type information only).
+  attr_reader :transport
+
+  # transport, when this client must be able to execute
+  def transport!
+    transport or raise GraphWeaver::Error,
+      "this client has no transport (built from a schema dump) — pass a url or transport:"
+  end
+
+  # The schema, introspecting through the transport on first use (cached
+  # per the client's cache:/ttl:) unless one was given up front.
+  def schema
+    @schema ||= GraphWeaver::SchemaLoader.introspect(transport!, cache: @cache, ttl: @ttl)
+  end
+
+  # Client-scoped scalar registration: consulted before the global
+  # registry when this client generates code, so two clients can map the
+  # same scalar name onto different Ruby types. Same signature as
+  # GraphWeaver.register_scalar.
+  def register_scalar(graphql_name, type, cast: nil, serialize: nil, requires: nil, coerce: nil)
+    validate_registration!("scalar", graphql_name.to_s)
+    @scalars[graphql_name.to_s] =
+      GraphWeaver::Codegen::ScalarType.new(graphql_name, type, cast:, serialize:, requires:, coerce:)
+  end
+
+  # Client-scoped enum mapping: this client's generated code speaks your
+  # T::Enum for the named GraphQL enum (see Codegen::EnumType — inference
+  # by name, map: for renames, fallback: to absorb unknown wire values).
+  def register_enum(graphql_name, type, map: nil, fallback: nil, requires: nil)
+    validate_registration!("enum", graphql_name.to_s)
+    @enums[graphql_name.to_s] =
+      GraphWeaver::Codegen::EnumType.new(graphql_name, type, map:, fallback:, requires:)
+  end
+
+  # Bulk, inference-only form: register_enums("Species" => PetKind, ...)
+  def register_enums(mappings)
+    mappings.each { |graphql_name, type| register_enum(graphql_name, type) }
+  end
+
+  # Client-scoped type helpers: include app-owned modules into every
+  # struct this client generates from the named GraphQL type — pass
+  # modules, or a block to build one inline. Additive with global
+  # registrations (see GraphWeaver.register_type).
+  def register_type(graphql_name, *mixins, requires: nil, &block)
+    validate_registration!("type", graphql_name.to_s)
+    entry = @types[graphql_name.to_s] ||= { mixins: [], requires: [] }
+    GraphWeaver::Codegen.add_type_helpers(entry, graphql_name, mixins, requires, block)
+  end
+
+  # Parse a query (a .graphql path or raw string) into a typed module
+  # bound to this client's schema, scalars, enums, helpers, and transport
+  # (including a live schema class executing in-process — the module came
+  # from this client, so it runs against it; pass a client per call to
+  # override, e.g. with a fake).
+  def parse(query, name: nil)
+    GraphWeaver.parse(schema:, query:, name:, client: transport,
+      scalars: @scalars, enums: @enums, types: @types)
+  end
+
+  # Parse every .graphql query in a directory into typed modules, named
+  # like generation would name them — the no-build-step analog of
+  # generate! + load_generated!:
+  #
+  #      github.load_queries!                        # queries/person.graphql => ::PersonQuery
+  #      github.load_queries!(namespace: Github)     # => Github::PersonQuery
+  #
+  # Reloadable (constants are replaced), so it suits consoles and dev.
+  # Returns the modules.
+  def load_queries!(dir = GraphWeaver.queries_path, namespace: Object)
+    Dir[File.join(dir, "*.graphql")].sort.map do |path|
+      name = "#{GraphWeaver::Inflect.camelize(File.basename(path, ".graphql"))}Query"
+      namespace.send(:remove_const, name) if namespace.const_defined?(name, false)
+      GraphWeaver.log(:info) { "loaded #{name} from #{path}" }
+      namespace.const_set(name, parse(path))
+    end
+  end
+
+  # One-shot dynamic execution — parse + execute, returning the typed
+  # Response envelope (execute! returns the result or raises). Variables
+  # are plain kwargs, exactly as on a generated module; graphql-cased
+  # string keys work too.
+  def execute(query, **variables)
+    mod = parse(query)
+    kwargs = variables.to_h { |key, value| [GraphWeaver::Inflect.underscore(key.to_s).to_sym, value] }
+    mod.execute(transport!, **kwargs)
+  end
+
+  def execute!(query, **variables)
+    execute(query, **variables).data!
+  end
+
+  private
+
+  # Fail a typo'd registration at the call site when the schema is
+  # already in hand (a schema-source client, or a url client after first
+  # use) — immediate feedback in consoles. Lazily-introspecting clients
+  # get the same check at generation time instead; never trigger an
+  # introspection just to validate a name.
+  def validate_registration!(kind, name)
+    return unless @schema
+
+    GraphWeaver::Codegen.validate_registration!(@schema, kind, name)
+  end
+
+  # auth: is a token — "Bearer" is assumed unless the string carries its
+  # own scheme ("Basic dXNlcjpwYXNz..."). Transport pick: Faraday when
+  # the app already loads it (its middleware/proxy/timeout ecosystem
+  # comes along), the zero-dependency Transport::HTTP otherwise.
+  # Detection is `defined?(Faraday)` — deliberately NOT a require:
+  # faraday rides along transitively in most bundles (stripe, octokit,
+  # ...), and try-requiring would switch transports on apps that never
+  # chose it. With faraday under `require: false`, load it before
+  # building the client.
+  def build_transport(url, auth:, headers:, &middleware)
+    headers = headers.dup
+    if auth
+      headers["Authorization"] ||= auth.include?(" ") ? auth : "Bearer #{auth}"
+    end
+
+    if defined?(::Faraday)
+      require_relative "transport/faraday"
+      GraphWeaver::Transport::Faraday.new(url, headers:, &middleware)
+    elsif middleware
+      raise ArgumentError, "middleware blocks require the faraday gem"
+    else
+      GraphWeaver::Transport::HTTP.new(url, headers:)
+    end
+  end
+
+  # retries: is off by default — true for Retry defaults, or a
+  # Hash of its options
+  def wrap_retries(transport, retries)
+    case retries
+    when true then GraphWeaver::Retry.new(transport)
+    when false, nil then transport
+    else GraphWeaver::Retry.new(transport, **retries)
+    end
+  end
+end