graph_weaver 0.4.6 → 0.5.0

data/lib/graph_weaver/testing/subgraphs.rb

@@ -0,0 +1,130 @@
+# typed: true
+# frozen_string_literal: true
+
+require "graphql"
+
+require_relative "../schema_loader"
+require_relative "../schemas"
+
+module GraphWeaver
+  module Testing
+    # Which Ruby schema serves which subgraph — for the subgraphs this
+    # process serves at all.
+    #
+    # You can name them yourself, but the map is boilerplate you then have to
+    # keep right — so by default they're **derived from what each schema
+    # defines**. A schema serves subgraph `s` when it defines every type and
+    # field the routing table says `s` resolves. That's evidence, not a
+    # guess: matching on class names would be one (`Accounts::Schema`,
+    # `AccountsSchema`, `Subgraphs::Accounts`), and a wrong guess points a
+    # suite at the wrong resolvers and still passes.
+    #
+    # Two matches refuse, naming both — both fit the evidence, so picking
+    # either would be the guess this module exists to avoid. **No match is
+    # not a refusal**: a supergraph is routinely only partly local, the rest
+    # served by another process, so a subgraph nothing here defines is left
+    # out of the map. Only a query that reaches its fields fails, at plan
+    # time — see {Router}.
+    #
+    # `"reviews" => :fake` asks for schema-correct fabricated data instead of
+    # that refusal (see {FakeSubgraph}).
+    #
+    # The same check runs over a map you pass explicitly, which is how a
+    # swapped pair fails at construction rather than as a mystery three
+    # fetches later.
+    module Subgraphs
+      # how many coordinates a message names before it says "and N more"
+      SAMPLE = 5
+
+      # answer this subgraph with fabricated data rather than refusing
+      FAKE = :fake
+
+      class << self
+        # { "accounts" => Accounts::Schema, … } for the subgraphs this
+        # process serves — one nothing defines is absent, and left out.
+        # Names in `given` skip detection (:fake included); the rest are
+        # derived, and both go through the same check.
+        def resolve(table, given = nil, schemas: nil)
+          named = (given || {}).to_h { |name, schema| [name.to_s, schema] }
+          unknown = named.keys - table.subgraphs
+          if unknown.any?
+            raise GraphWeaver::ConfigurationError, "subgraphs: names #{unknown.join(", ")}, which " \
+              "this supergraph doesn't have (its subgraphs are #{table.subgraphs.join(", ")})"
+          end
+
+          searched = schemas || GraphWeaver::Schemas.loaded
+          table.subgraphs.filter_map do |name|
+            served = named.key?(name) ? check!(table, name, named[name]) : detect(table, name, searched)
+            [name, served] if served
+          end.to_h
+        end
+
+        # every loaded schema that defines what the table says `name` resolves
+        def candidates(table, name, schemas = GraphWeaver::Schemas.loaded)
+          schemas.select { |schema| missing(table, name, schema).empty? }
+        end
+
+        # The schema coordinates the supergraph says `name` resolves — "Type"
+        # for one it declares, "Type.field" for one it answers. This is the
+        # evidence a match is judged on.
+        def expected(table, name)
+          table.types.flat_map do |type_name|
+            next [] unless table.declared_in(type_name).include?(name)
+
+            fields = table.fields(type_name).select { |field| table.owners(type_name, field).include?(name) }
+            [type_name] + fields.map { |field| "#{type_name}.#{field}" }
+          end
+        end
+
+        # which of them `schema` doesn't define
+        def missing(table, name, schema)
+          expected(table, name).reject { |coordinate| GraphWeaver::Schemas.defines?(schema, coordinate) }
+        end
+
+        private
+
+        # The schema serving `name`, or nil when nothing here does — the
+        # subgraph is somebody else's, which is not an error until a query
+        # asks for it.
+        def detect(table, name, schemas)
+          found = candidates(table, name, schemas)
+          return found.first if found.one?
+          return if found.empty?
+
+          # by name: a dev reload leaves two class objects spelled the same,
+          # and naming one of them twice reads as a bug in the message
+          names = found.map(&:name).uniq.sort
+          raise GraphWeaver::ConfigurationError, "#{names.size} loaded schemas define everything the " \
+            "supergraph says #{name.inspect} resolves (#{names.join(", ")}) — pass subgraphs: naming " \
+            "the one you mean"
+        end
+
+        def check!(table, name, schema)
+          return FAKE if schema == FAKE
+
+          if schema.is_a?(Symbol)
+            raise GraphWeaver::ConfigurationError, "subgraphs[#{name.inspect}] is #{schema.inspect} — " \
+              "the only symbol an entry takes is #{FAKE.inspect}, which answers it with fabricated data"
+          end
+
+          verify!(table, name, schema)
+        end
+
+        def verify!(table, name, schema)
+          gaps = missing(table, name, schema)
+          return schema if gaps.empty?
+
+          raise GraphWeaver::ConfigurationError, "subgraphs[#{name.inspect}] is " \
+            "#{schema.name || schema.inspect}, which doesn't define #{sample(gaps)} — the supergraph " \
+            "says #{name} resolves them. Did two entries get swapped?"
+        end
+
+        def sample(list)
+          return list.join(", ") if list.size <= SAMPLE
+
+          "#{list.first(SAMPLE).join(", ")} and #{list.size - SAMPLE} more"
+        end
+      end
+    end
+  end
+end

data/lib/graph_weaver/testing.rb

@@ -12,10 +12,16 @@ rescue LoadError
 end
 
 # Opt-in test tooling: require "graph_weaver/testing" from your spec
-# helper (never from production code). Configure once, initializer-style:
+# helper (never from production code). Nothing here needs configuring —
+# what a mode runs against is derived (see CLIENT_MODES). Configure to
+# override a derivation, or to tune fabricated values:
 #
 #      GraphWeaver::Testing.configure do |config|
-#        config.schema = MySchema                  # for auto_fake / cassettes
+#        config.schema = MySchema                  # overrides the derived schema
+#        config.router = { subgraphs: { "reviews" => :fake } }  # or supergraph:,
+#                                                  # when it isn't the dump
+#        config.context = { current_user: }        # baseline GraphQL context
+#        config.default_mode = :fake               # untagged examples (graph_weaver/rspec)
 #        config.seed = 42                          # reproducible fakes
 #        config.mode = :faker                      # or :literal; nil = auto
 #        config.overrides = { "Person.name" => "Daniel" }
@@ -30,16 +36,23 @@ end
 #      nil      — auto: :faker when the gem is loaded, else :literal
 #
 # rspec users: require "graph_weaver/rspec" instead — it hooks the suite
-# (seed from rspec, optional auto-faked client per example).
+# (seed from rspec, a client per example from its `graphql:` tag).
 module GraphWeaver
   module Testing
     MODES = [:faker, :literal].freeze
 
+    # What an example can run against, named by the rspec tag that selects
+    # it — `it "…", graphql: :in_process` (see graph_weaver/rspec):
+    #
+    #      :fake        fabricated, schema-correct data; no resolvers run
+    #      :in_process  your resolvers, one live schema class, in-process
+    #      :router      your resolvers, across a federated graph
+    CLIENT_MODES = %i[fake in_process router].freeze
+
     class Config
-      attr_accessor :overrides, :seed, :list_size, :null_chance, :cassette_dir, :auto_fake,
+      attr_accessor :schema, :overrides, :seed, :list_size, :null_chance, :cassette_dir, :context,
         :record, :anonymize
-      attr_writer :schema
-      attr_reader :mode
+      attr_reader :mode, :router, :default_mode
 
       def initialize
         @overrides = {}
@@ -48,12 +61,22 @@ module GraphWeaver
         @null_chance = 0.0
         @mode = nil # auto
         @schema = nil
+        @located = nil # the committed dump, once located
+        # not under spec/fixtures: `fixtures :all` globs that path for
+        # `{**,*}/*.yml` and would try to load cassettes as ActiveRecord
+        # fixtures, a subdirectory included
         @cassette_dir = "spec/cassettes"
-        # explicit opt-in: swapping every example onto a fake is too
-        # surprising to be a default — a little friction beats unexpected
-        # behavior (the schema still auto-locates once you opt in)
-        @auto_fake = false
-        # GRAPHWEAVER_RECORD=1 rspec ...  -> Cassette.use re-records
+        # what an example with no `graphql:` tag runs against. nil leaves
+        # GraphWeaver.client alone: swapping every example onto something
+        # else is too surprising to be a default.
+        @default_mode = nil
+        # the GraphQL context every :in_process / :router example starts
+        # from; graphql_context merges onto it
+        @context = {}
+        # Router arguments, when the composed supergraph isn't the
+        # conventional dump — { supergraph:, subgraphs: }, subgraphs optional
+        @router = nil
+        # GRAPHWEAVER_RECORD=1 rspec ...  -> Testing.cassette re-records
         @record = !ENV["GRAPHWEAVER_RECORD"].to_s.empty?
         # anonymize responses as they're recorded (needs config.schema)
         @anonymize = false
@@ -61,11 +84,19 @@ module GraphWeaver
 
       # the explicitly configured schema, else the conventional dump
       # (SchemaLoader.locate at GraphWeaver.schema_path) — nil when
-      # neither exists, which quietly disables auto_fake
+      # neither exists
       def schema
-        @schema ||= GraphWeaver::SchemaLoader.locate
+        # the dump memoizes separately: explicit_schema has to stay honest
+        # about whether anyone set one, since :in_process won't run a dump's
+        # resolver-less types as if they were the live class
+        @schema || (@located ||= GraphWeaver::SchemaLoader.locate)
       end
 
+      # What's been set, without falling back to the dump — so validating
+      # overrides at configure time doesn't force a schema load on a suite
+      # that never asks for one.
+      def explicit_schema = @schema
+
       def mode=(mode)
         unless mode.nil? || MODES.include?(mode)
           raise ArgumentError, "mode: must be one of #{MODES.inspect} (or nil for auto), got #{mode.inspect}"
@@ -73,6 +104,104 @@ module GraphWeaver
 
         @mode = mode
       end
+
+      def default_mode=(mode)
+        unless mode.nil? || CLIENT_MODES.include?(mode)
+          raise ArgumentError,
+            "default_mode: must be one of #{CLIENT_MODES.inspect} (or nil to leave " \
+            "GraphWeaver.client alone), got #{mode.inspect}"
+        end
+
+        @default_mode = mode
+      end
+
+      # Router arguments — both keys optional, and each answers a different
+      # question. `supergraph:` is for one derivation can't find; without it
+      # the conventional dump is used, when that dump is itself a supergraph.
+      # `subgraphs:` is for what derivation can't settle, or for `"reviews"
+      # => :fake`, which fabricates a subgraph this process doesn't serve —
+      # the commonest reason to configure a router at all, and no reason to
+      # have to restate where the supergraph is.
+      def router=(arguments)
+        unless arguments.nil? || arguments.is_a?(Hash)
+          raise ArgumentError, "router: must be the arguments to build one, e.g. " \
+            "{ supergraph: \"supergraph.graphql\" } or { subgraphs: { \"reviews\" => :fake } }, " \
+            "got #{arguments.inspect}"
+        end
+        if arguments&.key?(:context)
+          # the rspec hook resets the router's context from config.context
+          # every example, so one set here would silently never be read
+          raise ArgumentError, "router: context: is set as config.context — the baseline every " \
+            ":in_process and :router example starts from"
+        end
+        unknown = (arguments&.keys || []) - %i[supergraph subgraphs]
+        raise ArgumentError, "router: doesn't take #{unknown.join(", ")}" if unknown.any?
+
+        @router = arguments
+        @built_router = nil
+      end
+
+      # Built once: parsing the supergraph is setup, not per-example work.
+      # #context is settable, so an example that runs as someone else sets
+      # that rather than rebuilding — the rspec hook resets it each time.
+      def built_router
+        @built_router ||= Router.new(supergraph: supergraph!, subgraphs: @router && @router[:subgraphs])
+      end
+
+      # The composed supergraph :router plans against — named, or the
+      # conventional dump when that's what it is. A client can't supply
+      # one: its schema is the API schema a router serves, with the
+      # @join__* routing table stripped out.
+      def supergraph!
+        return @router[:supergraph] if @router&.key?(:supergraph)
+
+        path = GraphWeaver::SchemaLoader.locate_path
+        return path if path && supergraph?(path)
+
+        raise GraphWeaver::Error, ":router needs the composed supergraph SDL — a client's schema " \
+          "is the API schema the router serves, with the @join__* routing table stripped out, so " \
+          "the supergraph has to be named. #{path ? "#{path} carries no @join__* markers" : "Nothing on disk at #{GraphWeaver.schema_path}"}. " \
+          "Set GraphWeaver::Testing.config.router = { supergraph: \"supergraph.graphql\" }."
+      end
+
+      # The live schema class :in_process runs when the example didn't name
+      # one — config.schema if that is a class, else whatever the app's own
+      # client already runs in-process. Only a live class has resolvers, so
+      # there is nothing else to fall back to: a dump is type information.
+      def schema_class!
+        runnable(schema) || GraphWeaver.live_schema ||
+          raise(GraphWeaver::Error, ":in_process runs your resolvers, so it needs the live " \
+            "GraphQL::Schema class — and GraphWeaver.client isn't running one in-process to " \
+            "borrow. Name it in the example — graphql_in_process(MySchema) — or set " \
+            "GraphWeaver::Testing.config.schema = MySchema for the whole suite. A federated app " \
+            "names the subgraph it means, per example; graphql: :router runs the graph stitched.")
+      end
+
+      # The schema everything else derives from: the one you set, else the
+      # committed dump, else the schema the app's client talks to.
+      def reference_schema!
+        found = schema || (GraphWeaver.client.schema if GraphWeaver.client.respond_to?(:schema))
+        return found if found
+
+        raise GraphWeaver::Error, "no schema to run against — GraphWeaver.client isn't set, " \
+          "there's no schema dump at #{GraphWeaver.schema_path}, and " \
+          "GraphWeaver::Testing.config.schema is unset. Set any one of them."
+      end
+
+      private
+
+      # config.schema doubles as the :in_process class when it is one — but a
+      # dump has no resolvers, so it can only ever be type information.
+      def runnable(schema)
+        schema if schema.is_a?(Class) && schema <= GraphQL::Schema
+      end
+
+      def supergraph?(source)
+        GraphWeaver::SchemaLoader.routing_table(source)
+        true
+      rescue GraphWeaver::Error
+        false
+      end
     end
 
     class << self
@@ -82,6 +211,17 @@ module GraphWeaver
 
       def configure
         yield config
+        # a typo'd override key pins nothing and the test still passes, so
+        # catch it here — while the block that set it is still on the stack
+        validate_overrides!(config.explicit_schema, config.overrides) if config.explicit_schema
+        config
+      end
+
+      # Override keys name schema coordinates: "Type.field", or a bare field
+      # name matching that field on any type. Anything else is a typo that
+      # would silently fabricate random data instead of pinning a value.
+      def validate_overrides!(schema, overrides)
+        overrides.each_key { |key| validate_override_key!(schema, key.to_s) }
       end
 
       # back to defaults — between tests, or to undo an experiment
@@ -94,7 +234,54 @@ module GraphWeaver
       def cassette_path(name)
         return name if name.include?("/") || name.end_with?(".yml", ".yaml")
 
-        File.join(config.cassette_dir, "#{name}.yml")
+        File.join(cassette_dir, "#{name}.yml")
+      end
+
+      # The configured directory, against Rails.root when there is one — a rake
+      # task runs from wherever it runs from; the cassettes don't move.
+      # const_get rather than a bare Rails: sorbet can't resolve a constant the
+      # gem doesn't depend on.
+      def cassette_dir
+        dir = config.cassette_dir
+        root = (Object.const_get(:Rails).root if Object.const_defined?(:Rails))
+        root ? File.join(root.to_s, dir) : dir
+      rescue NoMethodError
+        dir # something else named Rails
+      end
+
+      private
+
+      def validate_override_key!(schema, key)
+        type_name, field_name = key.split(".", 2)
+        # introspection fields (__typename) are real but absent from #fields
+        return if (field_name || type_name).start_with?("__")
+
+        if field_name.nil?
+          known = field_names(schema)
+          return if known.include?(type_name)
+
+          bad_override!(key, "matches no field in this schema", known, type_name)
+        end
+
+        type = schema.get_type(type_name)
+        unless type.respond_to?(:fields)
+          bad_override!(key, "names no object type in this schema", schema.types.keys, type_name)
+        end
+        return if type.fields.key?(field_name)
+
+        bad_override!(key, "is not a field of #{type_name}", type.fields.keys, field_name)
+      end
+
+      def bad_override!(key, problem, dictionary, term)
+        suggestion = GraphWeaver.did_you_mean(dictionary, term)
+        hint = suggestion ? " — did you mean '#{suggestion}'?" : ""
+        raise GraphWeaver::Error, "override key #{key.inspect} #{problem}#{hint}"
+      end
+
+      # Every output field name in the schema — walked only when a bare key
+      # asks for it.
+      def field_names(schema)
+        schema.types.each_value.flat_map { |type| type.respond_to?(:fields) ? type.fields.keys : [] }.uniq
       end
     end
   end
@@ -102,5 +289,8 @@ end
 
 require_relative "testing/values"
 require_relative "testing/fake_client"
+require_relative "testing/fake_subgraph"
 require_relative "testing/failure"
 require_relative "testing/cassette"
+require_relative "testing/router"
+require_relative "testing/coverage"

data/lib/graph_weaver/transport/faraday.rb

@@ -29,34 +29,52 @@ module GraphWeaver
         ::Faraday::ConnectionFailed, ::Faraday::TimeoutError, ::Faraday::SSLError
       )
 
-      def initialize(url_or_connection, headers: {}, &block)
+      def initialize(url_or_connection, headers: {}, open_timeout: nil, read_timeout: nil, &block)
         @connection = case url_or_connection
         when ::Faraday::Connection
-          # a prebuilt connection carries its own headers/middleware, so
-          # headers:/block would be silently dropped — fail loudly instead
-          unless headers.empty? && block.nil?
+          # a prebuilt connection carries its own headers/middleware/
+          # timeouts, so they'd be silently dropped — fail loudly instead
+          unless headers.empty? && block.nil? && open_timeout.nil? && read_timeout.nil?
             raise ArgumentError,
-              "headers:/block are ignored when passing a prebuilt Faraday::Connection — configure them on it"
+              "headers:/timeouts/block are ignored when passing a prebuilt Faraday::Connection — configure them on it"
           end
 
           url_or_connection
         else
-          # Faraday appends the default adapter when the block doesn't set one
-          ::Faraday.new(url: url_or_connection, headers:, &block)
+          # Faraday appends the default adapter when the block doesn't set
+          # one. Our defaults go on the connection so ours is the
+          # User-Agent, not Faraday's stock one; caller headers still win.
+          # Timeouts default to Transport::HTTP's — Faraday would
+          # otherwise inherit net/http's 60s/60s.
+          ::Faraday.new(
+            url: url_or_connection,
+            headers: DEFAULT_HEADERS.merge(headers),
+            request: {
+              open_timeout: open_timeout || DEFAULT_OPEN_TIMEOUT,
+              read_timeout: read_timeout || DEFAULT_READ_TIMEOUT,
+            },
+            &block
+          )
         end
         @url = @connection.url_prefix.to_s
+
+        # which adapter got picked decides socket reuse — Faraday's
+        # default net_http one opens a connection per request. Naming it
+        # is the cheapest way to make that discoverable.
+        GraphWeaver.log(:info) { "faraday transport #{@url} (adapter: #{@connection.builder.adapter})" }
       end
 
       private
 
-      sig { override.params(body: String).returns([Integer, T.untyped]) }
+      sig { override.params(body: String).returns(T::Array[T.untyped]) }
       def post(body)
         response = @connection.post do |request|
-          request.headers["Content-Type"] = "application/json"
+          # a prebuilt connection owns its headers — only fill the blanks
+          DEFAULT_HEADERS.each { |name, value| request.headers[name] ||= value }
           request.body = body
         end
 
-        [response.status, response.body]
+        [response.status, response.body, response.headers.to_h.transform_keys(&:downcase)]
       end
     end
   end

data/lib/graph_weaver/transport/http.rb

@@ -13,74 +13,137 @@ module GraphWeaver
     #
     #      GraphWeaver::Transport::HTTP.new(url, headers: { ... }, read_timeout: 10)
     #
-    # Timeouts surface as TransportError (retriable). The connection is
-    # persistent (keep-alive), serialized behind a mutex — one socket per
-    # transport, dropped on any failure so the next call starts fresh.
-    # For real connection pooling and a middleware ecosystem, use
-    # Transport::Faraday.
+    # Timeouts surface as TransportError (retriable). Connections are
+    # persistent (keep-alive) and pooled: up to pool_size: sockets, opened
+    # lazily, reused warmest-first, and dropped on any failure so the next
+    # call starts fresh. For a middleware ecosystem, use Transport::Faraday.
     class HTTP < Transport
       # net/http's own network-level failures (Errno/SocketError/IOError
       # are already seeded) — added to the shared, extensible
       # transport-error set.
       GraphWeaver.register_transport_error(Timeout::Error, OpenSSL::SSL::SSLError)
 
-      def initialize(url, headers: {}, open_timeout: 10, read_timeout: 30, keep_alive_timeout: 2)
+      # How many requests this process can have in flight at once. Rails sizes
+      # its own connection pool from RAILS_MAX_THREADS and this is the same
+      # question, so it answers both. A fiber server (Falcon) sets no such
+      # ceiling of its own — pass pool_size: there.
+      def self.default_pool_size
+        threads = ENV["RAILS_MAX_THREADS"].to_i
+        threads.positive? ? threads : 5
+      end
+
+      def initialize(url, headers: {}, open_timeout: DEFAULT_OPEN_TIMEOUT,
+        read_timeout: DEFAULT_READ_TIMEOUT, keep_alive_timeout: 2, pool_size: nil,
+        ca_file: nil, ca_path: nil, cert: nil, key: nil, verify_mode: nil)
+        pool_size ||= self.class.default_pool_size
+        raise ArgumentError, "pool_size: must be >= 1" unless pool_size >= 1
+
         @url = url
         @uri = URI(url)
         @headers = headers
         @open_timeout = open_timeout
         @read_timeout = read_timeout
         @keep_alive_timeout = keep_alive_timeout
-        @mutex = Mutex.new
-        @http = T.let(nil, T.nilable(Net::HTTP))
+
+        # TLS, forwarded verbatim to Net::HTTP.start: a private CA
+        # (ca_file:/ca_path:), a client certificate (cert:/key:), or a
+        # verify_mode: — so mTLS doesn't mean reaching for Faraday
+        @ssl = { ca_file:, ca_path:, cert:, key:, verify_mode: }.compact
+        if @ssl.any? && @uri.scheme != "https"
+          raise ArgumentError, "TLS options need an https url — got #{url}"
+        end
+
+        # One permit per allowed socket: holding a permit is the right to
+        # hold a connection, so at most pool_size requests are in flight
+        # and the rest queue rather than opening unbounded sockets.
+        @pool_size = pool_size
+        @permits = SizedQueue.new(pool_size)
+        pool_size.times { @permits.push(true) }
+
+        # live connections, LIFO — a warm socket beats opening a cold one,
+        # so a single-threaded caller keeps reusing the same one
+        @idle = []
+        @idle_lock = Mutex.new
       end
 
       private
 
-      sig { override.params(body: String).returns([Integer, T.untyped]) }
+      sig { override.params(body: String).returns(T::Array[T.untyped]) }
       def post(body)
-        request = Net::HTTP::Post.new(@uri, { "Content-Type" => "application/json" }.merge(@headers))
+        request = Net::HTTP::Post.new(@uri, DEFAULT_HEADERS.merge(@headers))
         request.body = body
 
-        response = @mutex.synchronize do
-          begin
-            connection.request(request)
-          rescue => e
-            # socket state is unknown — drop it so the next call starts
-            # fresh (retry policy belongs to Retry, not here)
-            disconnect
-            raise e
-          end
-        end
+        response = with_connection { |http| http.request(request) }
 
-        [response.code.to_i, response.body]
+        # each_header yields downcased names with repeats already joined
+        [response.code.to_i, response.body, response.each_header.to_h]
       end
 
-      # The persistent connection. net/http proactively reconnects when
-      # idle past keep_alive_timeout, so a server-closed keep-alive
+      # Lease a connection for one round trip. The permit is held across
+      # the whole trip — opening the socket included — so pool_size really
+      # is the concurrency ceiling.
+      def with_connection
+        acquire_permit
+        http = nil
+
+        begin
+          http = @idle_lock.synchronize { @idle.pop } || connect
+          result = yield http
+          @idle_lock.synchronize { @idle.push(http) }
+          result
+        rescue Exception
+          # socket state is unknown — drop it, leaving the slot empty so
+          # the next call starts fresh (retry policy belongs to Retry).
+          # Exception, not StandardError: a fiber scheduler cancels with
+          # Async::Stop, which descends from Exception.
+          disconnect(http)
+          raise
+        ensure
+          @permits.push(true)
+        end
+      end
+
+      # A fresh persistent connection. net/http proactively reconnects
+      # when idle past keep_alive_timeout, so a server-closed keep-alive
       # socket doesn't produce spurious failures.
-      def connection
-        @http ||= begin
-          GraphWeaver.log(:debug) { "connecting to #{@uri.hostname}:#{@uri.port}" }
-          Net::HTTP.start(
-            @uri.hostname, @uri.port,
-            use_ssl: @uri.scheme == "https",
-            open_timeout: @open_timeout, read_timeout: @read_timeout,
-            keep_alive_timeout: @keep_alive_timeout,
-          )
+      def connect
+        GraphWeaver.log(:debug) { "connecting to #{@uri.hostname}:#{@uri.port}" }
+        Net::HTTP.start(
+          @uri.hostname, @uri.port,
+          use_ssl: @uri.scheme == "https",
+          open_timeout: @open_timeout, read_timeout: @read_timeout,
+          keep_alive_timeout: @keep_alive_timeout,
+          **@ssl,
+        )
+      end
+
+      # Take a permit, saying so when none is free. A queued request is
+      # indistinguishable from a slow server from the outside, which is the
+      # whole problem: pool_size is a hard ceiling under fibers exactly as
+      # under threads. Warned once — a saturated pool stays saturated, and a
+      # line per request would bury it.
+      def acquire_permit
+        @permits.pop(true)
+      rescue ThreadError
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @permits.pop
+        waited = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+
+        first = !@saturated
+        @saturated = true
+        GraphWeaver.log(first ? :warn : :debug) do
+          "connection pool saturated: waited #{waited}ms for 1 of #{@pool_size} connections to " \
+            "#{@uri.hostname} — raise pool_size: to this process's concurrency"
         end
       end
 
-      def disconnect
-        http = @http
+      def disconnect(http)
         return unless http
 
         GraphWeaver.log(:debug) { "dropping connection to #{@uri.hostname}:#{@uri.port}" }
         http.finish if http.started?
       rescue IOError
         # already closed
-      ensure
-        @http = nil
       end
     end
   end