graph_weaver 0.4.6 → 0.5.0

data/docs/upgrading.md

@@ -0,0 +1,112 @@
+# Upgrading to 0.5.0
+
+0.5.0 is one large breaking release. Almost all of it is caught mechanically —
+the work is running three commands and following what they tell you.
+
+```sh
+rake graph_weaver:generate   # 1. regenerate; the emitted call shape changed
+srb tc                       # 2. every call site that moved is now a type error
+rake graph_weaver:verify     # 3. fails until the tree is regenerated
+```
+
+Generated code is `# typed: strict`, so step 2 finds the call sites for you.
+The rest of this page is what a typechecker can't see.
+
+## `execute` means one thing now
+
+Every client answers the same call — `execute(query, variables:, operation_name:)`,
+returning the raw response hash. `Client` used to spell something else under
+that name, which is why `Retry.new(client)` and `Sequence.new(client, fake)`
+raised `ArgumentError`. They work now.
+
+The one-shot sugar moved to `run`:
+
+```ruby
+client.execute!("query { … }", id: "1")   # before
+client.run!("query { … }", id: "1")       # after   (and #run for the envelope)
+
+GraphWeaver.execute(source, query, **vars)   # before
+GraphWeaver.run(source, query, **vars)       # after
+```
+
+**This one is worth grepping for.** `Client#execute` still exists, so a stale
+call fails at runtime rather than at typecheck: `rg '\.execute!?\(' --type ruby`
+and check each hit is passing `variables:` rather than loose kwargs.
+
+A generated module takes its per-call client as a **keyword**:
+
+```ruby
+PersonQuery.execute(some_client, id: "1")          # before
+PersonQuery.execute(client: some_client, id: "1")  # after
+```
+
+`GraphWeaver.resolve_transport` is gone; nothing needs unwrapping any more.
+
+## Path settings are lists
+
+`queries_paths`, `generated_paths`, `fragments_paths` — every entry is read.
+Assigning a String still works, so the change is the name:
+
+```ruby
+GraphWeaver.queries_path = "app/graphql/queries"    # before
+GraphWeaver.queries_paths = "app/graphql/queries"   # after
+```
+
+`schema_path` stays singular: one run reads one schema.
+
+## One reset
+
+`GraphWeaver.reset_registrations!` is the clean slate between tests. The four
+narrow ones moved to where they live:
+
+```ruby
+GraphWeaver.reset_scalars!            # before
+GraphWeaver::Codegen.reset_scalars!   # after   (also reset_enums!, clear_scalars!,
+                                      #          reset_type_helpers!)
+```
+
+## Smaller renames
+
+| before | after |
+|---|---|
+| `response.ok?` | `response.success?` |
+| `Testing.config.auto_fake = true` | `Testing.config.default_mode = :fake` |
+| `register_scalar(…, coerce: :to_s)` | `coerce: true`, or a `cast:`/`serialize:` pair |
+| a mutation's `…Query` module | `…Mutation` |
+
+`Testing::LiveSchema` is gone. If your client points at a different API than the
+schema class your specs run in-process, name it once:
+
+```ruby
+GraphWeaver::Testing.config.schema = MySchema
+```
+
+## Registering from Rails
+
+A registration naming one of your own constants belongs in a `to_prepare` block
+— the same place the in-process client goes, and for the same reason:
+autoloading is set up after `config/initializers` run.
+
+```ruby
+Rails.application.config.to_prepare do
+  GraphWeaver.register_enum("Species", PetKind, fallback: PetKind::Unknown)
+  GraphWeaver.extend_type("Pet", PetHelpers)
+end
+```
+
+Generation depends on `:environment`, which runs `to_prepare` too, so the
+registration is in place before it emits.
+
+## If you use the federation router
+
+Detection only sees *loaded* schema classes, and Rails does not eager load for
+rake or in the default test environment. Both are one line:
+
+```ruby
+config.eager_load = true        # config/environments/test.rb
+config.rake_eager_load = true   # config/application.rb
+```
+
+Without them the `federation:*` tasks silently see nothing — and
+`federation:diff` now **fails** rather than reporting a green "matches" over
+zero subgraphs.

data/graph_weaver.gemspec

@@ -2,7 +2,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"
+  # the README tagline, verbatim — the two pitches drifted apart once already,
+  # so spec/gemspec_spec.rb pins them together
+  s.description = "Your .graphql files, compiled into Sorbet types — and the fakes to test them."
   # ".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"]

data/lib/generators/graph_weaver/install_generator.rb

@@ -0,0 +1,259 @@
+# typed: ignore — Rails::Generators DSL, only loaded by `rails g`
+# frozen_string_literal: true
+
+require "graph_weaver"
+
+# rails g graph_weaver:install https://api.example.com/graphql
+# rails g graph_weaver:install MyApp::Schema
+# rails g graph_weaver:install db/schema.graphql
+#
+# Scaffolds the conventional layout — initializer, query/generated
+# directories, editor config — and bootstraps the schema dump, so the
+# setup in docs/getting_started.md is one command.
+#
+# The argument is what you'd pass to GraphWeaver.new, and the same three
+# source forms are accepted; the initializer it writes reflects the one
+# you chose. The source arrives on the command line rather than being read
+# from config: at install time the initializer doesn't exist yet.
+module GraphWeaver
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc <<~TEXT
+        Wire up GraphWeaver: initializer, app/graphql layout, editor config, schema dump.
+
+        SOURCE is what you'd pass to GraphWeaver.new:
+
+            rails g graph_weaver:install https://api.example.com/graphql   # an endpoint
+            rails g graph_weaver:install MyApp::Schema                     # a graphql-ruby schema, in-process
+            rails g graph_weaver:install db/schema.graphql                 # a schema dump you already have
+      TEXT
+
+      argument :source, type: :string, banner: "SOURCE",
+        desc: "what you'd pass to GraphWeaver.new: an endpoint url, a graphql-ruby schema class, or a schema dump path"
+
+      class_option :auth, type: :string,
+        desc: "name of the ENV var holding the auth token (url only) — default GRAPHWEAVER_AUTH"
+      class_option :schema, type: :boolean, default: true,
+        desc: "write the schema dump codegen reads"
+
+      # a Ruby constant path names a schema class; anything that is neither
+      # this nor a url is taken as a path to a dump
+      CONSTANT = /\A[A-Z]\w*(::[A-Z]\w*)*\z/
+
+      DEFAULT_AUTH = "GRAPHWEAVER_AUTH"
+
+      # Before anything is written: a mistyped source or a flag that doesn't
+      # apply to it is a mistake in the command just typed, so say so there
+      # rather than at boot, three files later.
+      def check_source
+        if options[:auth] && form != :url
+          raise Thor::Error, "--auth applies to a url — #{source} is a #{form == :schema_class ? "schema class" : "schema dump"}"
+        end
+
+        schema_class if form == :schema_class
+      end
+
+      # Every write goes through create_file, so a re-run prompts with a
+      # diff rather than overwriting an initializer you've edited.
+      def create_initializer
+        create_file "config/initializers/graph_weaver.rb", initializer
+      end
+
+      def create_layout
+        create_file File.join(GraphWeaver.queries_paths.first, ".keep"), ""
+        create_file File.join(GraphWeaver.generated_paths.first, ".keep"), ""
+      end
+
+      # editor autocomplete + validation for .graphql files (docs/editors.md)
+      def create_editor_config
+        create_file "graphql.config.yml", editor_config
+      end
+
+      # A url is introspected and a schema class dumped; a dump the app
+      # already has is left where it is (schema_path points at it instead).
+      def fetch_schema
+        return unless options[:schema] && form != :path
+
+        if form == :url
+          # pass the var name, not just the token — it lands in the dump's
+          # provenance so schema:refresh/:diff read the same one the
+          # initializer does, instead of defaulting to GRAPHWEAVER_AUTH
+          GraphWeaver::SchemaLoader.refresh!(url: source, auth_env: auth_var)
+        else
+          # a schema class is its own introspection source; ttl: 0 so an
+          # existing dump never counts as fresh
+          GraphWeaver::SchemaLoader.introspect(schema_class, cache: schema_path, ttl: 0)
+        end
+        say_status :introspect, "#{schema_path} from #{source}"
+      rescue StandardError => e
+        # the files above are the valuable part — don't lose them to a bad
+        # token or an unreachable host
+        say_status :failed, "#{e.message} — retry with `#{refresh_command}`", :red
+      end
+
+      def next_steps
+        say <<~TEXT
+
+          Write a query in #{GraphWeaver.queries_paths.first}, then:
+
+              rake graph_weaver:generate
+
+          Docs: https://github.com/dpep/graph_weaver/blob/main/docs/getting_started.md
+        TEXT
+
+        say federated_steps if subgraphs
+      end
+
+      private
+
+      # This install run is the one moment the user is guaranteed to be
+      # reading, and a composed supergraph changes what the next steps are:
+      # the test client is the interesting one, and there's a CI gate to add.
+      def federated_steps
+        <<~TEXT
+
+          #{source} is a composed supergraph (#{subgraphs.size} subgraphs: #{subgraphs.join(", ")}), so:
+
+              rake graph_weaver:federation:diff       # CI gate: a subgraph changed, nobody recomposed
+              rake graph_weaver:federation:subgraphs  # which schema here serves which subgraph
+
+          and specs run against your real resolvers across all of them, in-process:
+
+              describe "checkout", graphql: :router do ... end   # require "graph_weaver/rspec"
+
+          Docs: https://github.com/dpep/graph_weaver/blob/main/docs/federation.md
+        TEXT
+      end
+
+      # The subgraph names this source composes, or nil when it isn't a
+      # composed supergraph. Read off the routing table rather than guessed —
+      # the same reader Testing::Router and federation:diff use.
+      def subgraphs
+        return @subgraphs if defined?(@subgraphs)
+
+        @subgraphs =
+          begin
+            (GraphWeaver::SchemaLoader.routing_table(source).subgraphs if form == :path)
+          rescue StandardError
+            # not a supergraph, or not readable — nothing to say either way
+            nil
+          end
+      end
+
+      # Which of GraphWeaver.new's source forms this is — the url test is
+      # its own, so the generator and the client can't disagree about what
+      # counts as one.
+      def form
+        @form ||=
+          if source.match?(GraphWeaver::Client::URL)
+            :url
+          elsif source.match?(CONSTANT)
+            :schema_class
+          else
+            :path
+          end
+      end
+
+      # The named schema class, resolved now: `rails g` boots the app, so a
+      # typo is catchable here rather than as a NameError at the next boot.
+      def schema_class
+        @schema_class ||= begin
+          klass = Object.const_get(source)
+          unless klass.respond_to?(:execute)
+            raise Thor::Error, "#{source} isn't a graphql-ruby schema (no .execute) — pass the class that inherits GraphQL::Schema"
+          end
+
+          klass
+        rescue NameError
+          raise Thor::Error, "uninitialized constant #{source} — pass your graphql-ruby schema class " \
+            "(rails g graphql:install writes app/graphql/<app>_schema.rb), an endpoint url, or a path to a schema dump"
+        end
+      end
+
+      # A dump the app already has stays where it is; every other form
+      # writes the conventional one.
+      def schema_path = (form == :path) ? source : GraphWeaver.schema_path
+
+      def auth_var = options[:auth] || DEFAULT_AUTH
+
+      def refresh_command
+        (form == :url) ? "rake graph_weaver:schema:refresh" : "rails g graph_weaver:install #{source}"
+      end
+
+      def initializer
+        <<~RUBY
+          # frozen_string_literal: true
+
+          #{client_setup}
+          # Custom scalars, enums and type mixins go here — `rake graph_weaver:generate`
+          # bakes them into the generated source, so they must be registered first:
+          #
+          #   GraphWeaver.register_scalar("DateTime", Time, serialize: :iso8601, requires: "time")
+          #   GraphWeaver.extend_type("Person", Greetable)
+        RUBY
+      end
+
+      # The load-bearing lines, per source form: what generated modules
+      # resolve to at execute time, and where codegen reads the schema.
+      def client_setup
+        case form
+        when :url
+          <<~RUBY
+            GraphWeaver.client = GraphWeaver.new(
+              "#{source}",
+              auth: ENV["#{auth_var}"],
+              cache: true, # reuse the committed dump; delete it to re-introspect
+            )
+          RUBY
+        when :schema_class
+          # to_prepare, not a bare assignment: the schema class is autoloaded,
+          # so it isn't resolvable this early, and a dev reload replaces it
+          # with a new class object the client would otherwise still hold.
+          <<~RUBY
+            Rails.application.config.to_prepare do
+              # queries run in-process against the app's own schema — no socket
+              GraphWeaver.client = GraphWeaver.new(#{source})
+            end
+          RUBY
+        when :path
+          if subgraphs
+            <<~RUBY
+              GraphWeaver.schema_path = "#{source}"
+
+              # A composed supergraph: your queries are generated against the whole
+              # graph, and a router serves it. Point the app default at the gateway:
+              #
+              #   GraphWeaver.client = GraphWeaver.new("https://gateway.example.com/graphql")
+              #
+              # Specs don't need one — `graphql: :router` plans against this
+              # supergraph and runs your own subgraph resolvers in-process
+              # (docs/federation.md).
+            RUBY
+          else
+            <<~RUBY
+              GraphWeaver.schema_path = "#{source}"
+
+              # A dump is type information only — it has no resolvers, so it can't
+              # execute. Point the app default at whatever serves this API:
+              #
+              #   GraphWeaver.client = GraphWeaver.new("https://api.example.com/graphql")
+            RUBY
+          end
+        end
+      end
+
+      # fragments are in documents: too — without them an editor reports
+      # `Unknown fragment` on any query that spreads a shared one
+      def editor_config
+        <<~YAML
+          # Autocomplete and validation for .graphql files in VS Code / RubyMine.
+          # https://github.com/dpep/graph_weaver/blob/main/docs/editors.md
+          schema: #{schema_path}
+          documents:
+            - #{GraphWeaver.queries_paths.first}/**/*.{graphql,gql}
+            - #{GraphWeaver.fragments_paths.first}/**/*.{graphql,gql}
+        YAML
+      end
+    end
+  end
+end

data/lib/graph_weaver/client.rb

@@ -4,6 +4,7 @@
 require_relative "codegen"
 require_relative "errors"
 require_relative "inflect"
+require_relative "parsing"
 require_relative "retry"
 require_relative "schema_loader"
 require_relative "transport/http"
@@ -12,31 +13,45 @@ require_relative "transport/http"
 # 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
+#      RepoQuery = github.parse("queries/repo.graphql")   # implicit schema + client
+#      github.run!("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.
+# source — a live schema class (which also executes in-process, through
+# an InProcess wrapper that takes context:), or a path/SDL/introspection
+# dump via SchemaLoader.
 #
-# 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.
+# transport: means "which transport" alongside a url — :http (the
+# default, always, whatever else the Gemfile loads) or :faraday — and
+# "this transport" alongside a schema source.
+#
+# Clients are independent: each has its own transport and schema, so one
+# app can talk to several GraphQL servers. Scalar/enum/type registrations
+# are a codegen concern and live in one global registry (see
+# GraphWeaver.register_scalar) — the same registry the rake tasks bake.
 class GraphWeaver::Client
+  include GraphWeaver::Parsing
+
   URL = %r{\Ahttps?://}i
 
-  def initialize(source, auth: nil, headers: {}, retries: false, transport: nil, cache: nil, ttl: nil, &middleware)
+  def initialize(source, auth: nil, headers: {}, retries: false, transport: nil, cache: nil, ttl: nil,
+    open_timeout: nil, read_timeout: nil, context: nil, &middleware)
+    check_source!(source)
+
     if source.is_a?(String) && source.match?(URL)
-      raise ArgumentError, "pass a url or transport:, not both" if transport
+      raise ArgumentError, "context: applies to a schema class executing in-process" if context
 
-      @transport = wrap_retries(build_transport(source, auth:, headers:, &middleware), retries)
+      built = build_transport(source, auth:, headers:, kind: transport, open_timeout:, read_timeout:, &middleware)
+      @transport = wrap_retries(built, retries)
     else
-      if auth || middleware || retries
-        raise ArgumentError, "auth:/retries:/middleware apply to a url — got a schema source"
+      if auth || middleware || retries || open_timeout || read_timeout
+        raise ArgumentError, "auth:/retries:/timeouts/middleware apply to a url — got a schema source"
+      end
+      if transport.is_a?(Symbol)
+        # naming a bundled transport only builds one from a url
+        raise ArgumentError, "transport: #{transport.inspect} needs a url — got a schema source; pass a built transport"
       end
       if cache || ttl
         # a schema source never introspects, so a cache would silently no-op
@@ -46,14 +61,21 @@ class GraphWeaver::Client
       # 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))
+
+      if context && !(source.is_a?(Module) && transport.nil?)
+        # nothing would ever read it — a dump has no resolvers, and an
+        # explicit transport carries its own
+        raise ArgumentError, "context: applies to a schema class executing in-process"
+      end
+
+      # InProcess adds context:, logging and branded errors to the bare
+      # schema class, which stays usable on its own everywhere else
+      @transport = transport ||
+        (GraphWeaver::InProcess.new(source, context: context || {}) if source.is_a?(Module))
     end
 
     @cache = cache
     @ttl = ttl
-    @scalars = {}
-    @enums = {}
-    @types = {}
   end
 
   # The transport queries run through: a url-built transport, an
@@ -74,123 +96,104 @@ class GraphWeaver::Client
     @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. A `Type.field` coordinate
-  # (e.g. "User.birthday") overrides just that field. 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.extend_type).
-  def extend_type(graphql_name, *mixins, requires: nil, **kw, &block)
-    validate_registration!("type", graphql_name.to_s)
-    aliases = GraphWeaver::Codegen.take_aliases(kw)
-    entry = @types[graphql_name.to_s] ||= { mixins: [], requires: [], aliases: {} }
-    GraphWeaver::Codegen.add_type_helpers(entry, graphql_name, mixins, requires, block, aliases)
-  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 = nil, namespace: Object)
-    dirs = dir ? [dir] : GraphWeaver.queries_paths
-    dirs.flat_map { |d| Dir[File.join(d, "*.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
+  # The client contract, same as every transport: a query and its
+  # variables in, the raw response hash out. (#run is the one-shot that
+  # parses and returns the typed envelope.)
+  def execute(query, variables: {}, operation_name: nil)
+    transport!.execute(query, variables:, operation_name:)
   end
 
-  # One-shot dynamic execution — parse + execute, returning the typed
-  # Response envelope (execute! returns the result or raises). Variables
+  # One-shot dynamic execution — parse + run, returning the typed
+  # Response envelope (run! 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)
+  def run(query, **variables)
     mod = parse(query)
     kwargs = variables.to_h { |key, value| [GraphWeaver::Inflect.underscore(key.to_s).to_sym, value] }
-    mod.execute(transport!, **kwargs)
+    mod.execute(**kwargs)
   end
 
-  def execute!(query, **variables)
-    execute(query, **variables).data!
+  def run!(query, **variables)
+    run(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)
+  # Anything already speaking the client contract — another Client,
+  # InProcess, Retry, a transport, a fake, the test router — carries no
+  # schema to generate from, so it can't stand in as the schema source.
+  # Without this it is handed to SchemaLoader and fails as `undefined
+  # method 'lstrip'`.
+  def check_source!(source)
+    # a graphql-ruby schema class executes too, and *is* a schema source
+    return if source.is_a?(Module) || !source.respond_to?(:execute)
+
+    raise GraphWeaver::Error, "#{source.class} is a client, not a schema source — pass the schema, and this " \
+      "as its transport: GraphWeaver.new(schema, transport: client). For a live schema class " \
+      "with a context: GraphWeaver.new(schema, context: { ... })."
   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)
+  # own scheme ("Basic dXNlcjpwYXNz...").
+  #
+  # Transport pick: always Transport::HTTP unless you ask for Faraday
+  # (transport: :faraday, or a middleware block, which is Faraday's
+  # anyway). Deliberately NOT `defined?(Faraday)`: faraday rides along
+  # transitively in most bundles (stripe, octokit, ...), so sniffing for
+  # it lets an unrelated gem swap your transport — along with its
+  # timeouts and, since Faraday's default net_http adapter reconnects
+  # per request, your connection reuse. Same code, same transport.
+  def build_transport(url, auth:, headers:, kind:, open_timeout: nil, read_timeout: nil, &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"
+    # nil means "the transport's default" — both bundled ones agree on it
+    timeouts = { open_timeout:, read_timeout: }.compact
+
+    transport =
+      if transport_kind(kind, middleware) == :faraday
+        build_faraday(url, headers:, timeouts:, &middleware)
+      else
+        GraphWeaver::Transport::HTTP.new(url, headers:, **timeouts)
+      end
+
+    GraphWeaver.log(:info) { "transport: #{transport.class} -> #{url}" }
+    transport
+  end
+
+  # Which bundled transport a url client builds: the explicit
+  # transport:, else Faraday when a middleware block asks for it.
+  def transport_kind(kind, middleware)
+    case kind
+    when nil then middleware ? :faraday : :http
+    when :faraday then :faraday
+    when :http
+      raise ArgumentError, "middleware blocks are Faraday's — pass transport: :faraday" if middleware
+
+      :http
     else
-      GraphWeaver::Transport::HTTP.new(url, headers:)
+      raise ArgumentError, "transport: takes :http or :faraday alongside a url, got #{kind.inspect}"
     end
   end
 
+  # The faraday gem is optional, so a missing one reads as a Gemfile
+  # problem rather than a stack trace out of require.
+  def build_faraday(url, headers:, timeouts:, &middleware)
+    begin
+      require_relative "transport/faraday"
+    rescue LoadError
+      nil # reported below, alongside a gem that loaded but wasn't there
+    end
+
+    unless defined?(::Faraday)
+      raise ArgumentError, "the faraday transport needs the faraday gem — add it to your Gemfile"
+    end
+
+    GraphWeaver::Transport::Faraday.new(url, headers:, **timeouts, &middleware)
+  end
+
   # retries: is off by default — true for Retry defaults, or a
   # Hash of its options
   def wrap_retries(transport, retries)