graph_weaver 0.4.6 → 0.5.0

data/docs/testing.md

@@ -1,22 +1,162 @@
 # 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.
+One line in your spec helper:
 
-`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
+require "graph_weaver/rspec"
+```
+
+(In Rails, put it **above** the `spec/support` glob in `rails_helper.rb` —
+rspec-rails requires those partway through, and a support file mentioning
+`GraphWeaver::Testing` before this line dies on `NameError`.)
+
+Then **one tag says what an example runs against** — on the example, or on
+the group it belongs to, since rspec metadata inherits:
 
 ```ruby
-fake = GraphWeaver::Testing::FakeClient.new(schema:)
+describe "checkout", graphql: :router do
+  it "stitches the dashboard" do … end     # every example here, too
+end
+
+it "renders the empty state", graphql: :fake do … end
+it "authorizes drafts",       graphql: :in_process do … end
+```
+
+| mode | reach for it when | what it costs |
+|---|---|---|
+| `graphql: :fake` | most unit tests — you need *a* well-shaped response | no resolver code runs |
+| `graphql: :in_process` | the point of the test is that your resolver logic works | slower; needs a live schema class |
+| `graphql: :router` | the same, across a federated graph | needs a composed supergraph; [refuses](federation.md#what-it-refuses) shapes it can't plan faithfully |
+| [cassettes](cassettes.md) | pinning a real server's exact response | must be re-recorded when the query changes |
+
+The tag installs its client as `GraphWeaver.client` for that example, so
+generated modules run against it with zero per-test setup. (Generate them
+*without* a baked `client:` — a module that has one never consults
+`GraphWeaver.client`.) `rspec --tag graphql:router` runs one mode's
+examples; an untagged example is left alone unless you set
+`config.default_mode`, and **`graphql: false` opts one back out** of that
+default.
+
+`GraphWeaver.client` is **snapshotted before every example and restored
+after** — tagged, untagged or opted out, and whatever the example did to
+it. So building your own client is a plain assignment, cleaned up like a
+tagged one:
+
+```ruby
+before { GraphWeaver.client = GraphWeaver::Testing::Failure.throttled }
+```
+
+Everything here is a *client* — the one interface queries run through:
+anything with `execute(query, variables:, operation_name:)` returning
+`{"data" => ..., "errors" => ...}` (see [transports](transports.md)). Fakes,
+the router, failures, and cassettes all slot in wherever a real transport
+would, so they work outside rspec too (`require "graph_weaver/testing"` —
+never from production code). Outside the tags there's no `GraphWeaver.client`
+to lean on, so parse from the fake or the router itself — anything holding a
+schema parses against it, and the module runs on what parsed it:
+
+```ruby
+router = GraphWeaver::Testing::Router.new(supergraph: "app/graphql/supergraph.graphql")
+DashboardQuery = router.parse("query Dashboard { me { username } }")
+DashboardQuery.execute!.me.username
+```
+
+All three modes, tagged and running end to end, are
+[`spec/rspec_spec.rb`](../spec/rspec_spec.rb) — the reference for anything
+this page leaves out.
+
+## Nothing to configure
+
+Each mode works out what to run against, and **refuses — naming what it
+looked for — rather than guessing**:
+
+- **the schema** is `config.schema` if you set one, else the committed dump
+  at `GraphWeaver.schema_path`, else the schema `GraphWeaver.client` talks to.
+  (`config.schema` refuses a federation *subgraph* class: fakes are fabricated
+  against it too, so one subgraph would be a fraction of the graph. A
+  federated graph has no one schema class — that's what `:router` is.)
+- **`:in_process`** needs the live schema *class*, since only that has
+  resolvers: the one your client already runs in-process, else the loaded
+  class that defines everything the schema declares — the same
+  derive-verify-refuse rule that
+  [maps subgraphs](federation.md#which-schema-serves-which-subgraph).
+- **`:router`** plans against the composed supergraph. If your committed dump
+  *is* one (it carries `@join__*` markers), that's it — no config at all. A
+  client can't stand in for it: 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. Subgraphs are derived either way.
+
+So configure only to override a derivation, or to tune fabricated values:
+
+```ruby
+GraphWeaver::Testing.configure do |config|
+  # config.schema = MySchema         # the live class, rather than the dump
+  # config.router = { supergraph: Rails.root.join("supergraph.graphql") }
+  # config.router = { subgraphs: { "reviews" => :fake } }   # either key alone
+  # config.context = { tenant: }     # baseline context every example starts from
+  # config.default_mode = :fake      # what an UNtagged example runs against
+  #                                  # (graphql: false opts one back out)
+  # 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
+```
+
+## The context your resolvers see
+
+`graphql_context` is available in every example. It **merges** onto
+`config.context` — the baseline survives unless you override a key — and is
+**reset before the next example**, so one example running as somebody else
+can't leak into the one after it.
+
+Context is setup, so it usually belongs in a `before` block — a group of
+examples sharing one identity says who they are once:
+
+```ruby
+describe "as the owner", graphql: :in_process do
+  before { graphql_context(current_user: alice) }
+
+  it "shows the drafts" do
+    expect(DraftsQuery.execute!.drafts.size).to eq 2
+  end
+
+  it "counts them" do … end
+end
+```
+
+The reset runs ahead of any group hook, so each example re-applies that
+`before` from the same baseline rather than stacking onto the last one's
+context. Set it inline for the one-off:
+
+```ruby
+it "shows the owner's drafts", graphql: :in_process do
+  graphql_context(current_user: alice)
+  expect(DraftsQuery.execute!.drafts.size).to eq 2
+end
+```
+
+Pass a block to scope it, for the example that needs two identities:
+
+```ruby
+graphql_context(admin: true) { expect(SettingsQuery.execute!.settings).to be_present }
+```
 
-person = PersonQuery.execute!(fake, id: "1").person
+Called with nothing it reads the context back. Under `graphql: :fake` it
+refuses: there are no resolvers to receive a context, and silently ignoring
+one would leave an example asserting on data nothing scoped. Pin the data
+itself instead — `graphql_fake(overrides: …)`, below.
+
+## Fabricated data — `graphql: :fake`
+
+`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: falls back to Testing.config
+
+person = PersonQuery.execute!(client: fake, id: "1").person
 person.name       # => "Eliza Kertzmann" (faker-matched on field name, when faker is loaded)
 person.birthday   # => a real Date
 ```
@@ -31,52 +171,120 @@ GraphWeaver::Testing::FakeClient.new(schema:, overrides: {
 })
 ```
 
-With rspec, the setup is two lines in `spec/support/graph_weaver.rb` —
-the require, plus an explicit opt-in to per-example fakes (deliberately
-not a default: silently swapping every example onto a fake would be
-surprising). The schema auto-locates from the committed dump at
-`GraphWeaver.schema_path`:
+Keys are checked against the schema, spellchecked — `"Person.nmae"` raises
+rather than quietly pinning nothing and leaving the example green against
+random data.
+
+### The example that's *about* the data
+
+Fabricated data answers "does this render", not "does it render Ada's two
+orders". `graphql_fake` is the tag with options — same client, built where
+the example can say what it needs:
 
 ```ruby
-require "graph_weaver/rspec"   # seed follows --seed
+it "shows the two paid orders", graphql: :fake do
+  graphql_fake(overrides: {
+    "Reader.name" => "Ada",
+    "Reader.orders" => [{ "status" => "PAID" }, {}],
+  })
 
-GraphWeaver::Testing.configure do |config|
-  config.auto_fake = true              # every example runs against a fresh fake
-  # config.schema = MySchema           # optional: an in-process class instead of the dump
-  # 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
+  expect(DashboardQuery.execute!.reader.orders.size).to eq 2
+end
+```
+
+An override pins a **subtree** as readily as a leaf, and **merges**: name
+the fields the example is about and everything else in the selection is
+still fabricated. A pinned list is exactly as long as you write it — `{}`
+means "another one, all fabricated". Inside a subtree the keys are
+*response* keys, as they come back on the wire (`priceCents`, or an alias
+you selected); one the query doesn't select is refused and spellchecked,
+same as a typo'd coordinate. At a union or interface, name the member with
+`"__typename"`.
+
+`graphql_fake` returns the client, which records what it was asked:
+
+```ruby
+fake = graphql_fake
+2.times { Dashboard.load }
+expect(fake.requests.size).to eq 1                      # memoized
+expect(fake.requests.first[:variables]).to eq({ "id" => "1" })
+```
+
+It works in a `before` block, an example body, or a shared context — and
+with no tag at all, since it installs the client itself. The tag is
+`graphql_fake` with no options.
+
+One thing to know: **two identical queries fabricate different data**, so
+assert a memoization with `requests.size`, not by comparing two responses.
+
+### Naming the schema your resolvers run on
+
+`graphql_in_process` is the same idea for real resolvers. The tag runs
+`config.schema` when that's a live class, which is the whole story for an app
+that serves the API it calls:
+
+```ruby
+it "hides another reader's drafts", graphql: :in_process do
+  expect(DraftsQuery.execute!.drafts.map(&:id)).to eq %w[d3]
+end
+```
+
+A federated app has no one live class, so the example says which subgraph it
+means — testing one subgraph's resolvers directly is a different question from
+`graphql: :router`, which plans across the whole graph and stitches. Both are
+worth asking, and a suite asks them of different subgraphs:
+
+```ruby
+it "rejects a review from a blocked reader" do
+  graphql_in_process(Reviews::Schema)
+  …
 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.
+Like `graphql_fake`, it needs no tag, works in a `before` block, and is
+restored after the example. Set the GraphQL context with `graphql_context`
+rather than the helper's `context:` — the helper's is a baseline, and
+`graphql_context` is what merges onto it per example.
+
+`rspec --seed 1234` reproduces fake data along with test order. `config.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.
+
+Need the schema itself inside an example — to sample a field, or build a
+query on the fly? The client in play exposes it as
+`GraphWeaver.client.schema`, and `GraphWeaver::Testing.config.schema` reads
+back what `config.schema =` set, falling back to the committed dump.
 
-Test-only queries don't have to live in `app/` — the conventional paths
-are appendable lists, so the same support file can register a
-spec-local set that `load_generated!` (and the Railtie) pick up:
+Test-only generated modules don't have to live in `app/` — `generated_paths` is
+an appendable list, so a support file can register a spec-local set:
 
 ```ruby
-GraphWeaver.generated_paths << "spec/support/graphql/generated"
-GraphWeaver.queries_paths << "spec/support/graphql/queries"
+# spec/support/graph_weaver.rb
+GraphWeaver.generated_paths << "spec/graphql/generated"
+GraphWeaver.load_generated!   # the appended path needs this call
 ```
 
-**Simulating failures** — every failure mode is just a client, so
+Both lines matter. In Rails the Railtie loads generated modules during boot,
+which is finished before `spec/support/*.rb` runs — so a path appended here is
+never loaded unless you load it. And keep the directory *outside*
+`spec/support/`: rspec-rails requires every `spec/support/**/*.rb` itself, in
+sorted order, so a generated module gets required before the shared `types.rb`
+it needs and dies on `LoadError`.
+
+## 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
+PersonQuery.execute(client: Failure.transport, id: "1")            # TransportError (cause preserved)
+PersonQuery.execute(client: Failure.server(status: 502), id: "1")  # ServerError
+PersonQuery.execute(client: Failure.throttled, id: "1")            # QueryError, code THROTTLED
+PersonQuery.execute(client: Failure.stale_schema, id: "1")         # schema_stale? => true
+PersonQuery.execute(client: Failure.graphql("boom"), id: "1")      # partial failure
 
 # retries: clients run in sequence (the last repeats) — here, two
 # transport failures and then a FakeClient serving good responses
@@ -87,24 +295,63 @@ GraphWeaver::Testing::Sequence.new(Failure.transport, Failure.transport, fake)
 # 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
+## 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)
+client = GraphWeaver::Testing.cassette("github", client: live)
+```
+
+Re-record with `GRAPHWEAVER_RECORD=1`, and set `config.anonymize = true` so
+real data never lands in a committed file — the full workflow guide is
+**[cassettes](cassettes.md)**.
+
+## Real resolvers, one schema — `graphql: :in_process`
+
+Your actual resolvers, your actual `context`, in the same process — no
+socket, no serialization, and a resolver's real backtrace when it raises.
+
+```ruby
+it "hides other people's drafts", graphql: :in_process do
+  graphql_context(current_user: alice)
+  expect(DraftsQuery.execute!.drafts.map(&:owner)).to all(eq alice.name)
+end
+```
+
+The live schema *class* is found for you (a schema dump has no resolvers,
+so it won't do). If two loaded classes match, or none does, it says so and
+asks for `config.schema = MySchema` — and in Rails, remember that an
+autoloaded schema isn't loaded until something references it.
+
+## A federated graph — `graphql: :router`
+
+Same thing across a federated graph: the tag builds a
+[`Testing::Router`](federation.md#the-local-router), which plans the query
+across your subgraphs and runs it against those **real resolvers** — no
+gateway, no node, no sockets.
+
+```ruby
+describe "the dashboard", graphql: :router do
+  it "stitches a user's reviews" do
+    graphql_context(current_user: user)
+    expect(DashboardQuery.execute!.me.reviews.size).to eq 2
+  end
+end
 ```
 
-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)**.
+The router is built once for the suite (parsing a supergraph per example
+would be real time) and installed as `GraphWeaver.client` for each; its
+context is reset from `config.context` every time, so an example that runs
+as someone else can't leak into the next.
 
+What it plans, what it **refuses** and why, how subgraphs are matched to your
+schema classes, and what to do about a supergraph only partly local:
+**[federation → the local router](federation.md#the-local-router)**.

data/docs/transports.md

@@ -1,10 +1,18 @@
 # Transports
 
-A *client* is anything with `execute(query, variables:)` whose result
+A *client* is anything with `execute(query, variables:, operation_name:)` 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.
+`GraphWeaver::Client` down to a schema class
+([in-process execution](getting_started.md#your-apps-own-schema-in-process) —
+typed access to your own app's API, no socket), a [FakeClient](testing.md), or
+anything you write. Every slot that takes a client accepts any of them.
+
+**Anything holding a schema parses against it.** `client.parse(query)`, and
+the same on `InProcess`, `FakeClient` and `Testing::Router` — a typed module
+bound to that schema, running on that object, without naming either. It sits
+on top of the contract rather than in it: `Retry` wraps a client and holds no
+schema, so it has no `parse`, and a bare schema class fills the client slot
+without one. `load_queries!` is the same rule over a directory.
 
 A *transport* is the network end of that contract — GraphQL-over-HTTP. The bundled
 two — `Transport::HTTP` (net/http, zero dependencies, loaded by default)
@@ -22,31 +30,31 @@ Most apps need one line:
 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.
+`GraphWeaver.new` builds a [`Client`](real_world.md): a transport with
+auth applied (exposed as `client.transport`), the schema introspected
+lazily, and `parse`/`run` bound to both. A `Client` answers the client
+contract itself, so it goes anywhere a transport does — `Retry.new(client)`,
+`subgraphs:`, a cassette recorder.
 
 - `auth:` — a token; "Bearer" is assumed unless the string carries its own
   scheme (`"Basic dXNlcjpwYXNz..."`)
+- `transport:` — `:http` (the default) or `:faraday`
 - `headers:` — anything else (API keys, custom headers)
 - `retries:` — off by default; `true` for a `Retry` with defaults,
   or a Hash of its options
+- `open_timeout:` / `read_timeout:` — seconds, defaulting to 10 and 30 on
+  either transport
 - `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)
 
+What you pass is what you get; the client logs which transport it built at
+`info`.
+
 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.
+contract works there — testing's `graphql:` tag swaps in a client per example.
 
 ## Building blocks
 
@@ -54,16 +62,29 @@ 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
+# zero-dependency Net::HTTP — a pool of persistent (keep-alive)
+# connections; 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
+  pool_size: 5,                        # concurrent requests in flight
+                                       # (default: RAILS_MAX_THREADS, else 5)
+
+  # TLS, forwarded to Net::HTTP.start — a private CA, or mTLS, without
+  # reaching for Faraday. Passing any of these to an http:// url raises
+  # rather than quietly doing nothing.
+  ca_file: "/etc/ssl/private-ca.pem",  # or ca_path: for a directory
+  cert: OpenSSL::X509::Certificate.new(File.read("client.crt")),
+  key: OpenSSL::PKey::RSA.new(File.read("client.key")),
+  verify_mode: OpenSSL::SSL::VERIFY_PEER,  # the default; VERIFY_NONE to skip
 )
 
-# Faraday: a url (+ optional middleware block), or a ready connection
+# Faraday: a url (+ optional middleware block), or a ready connection.
+# Timeouts default to the same 10/30 as Transport::HTTP — without them
+# Faraday inherits net/http's 60s/60s.
+GraphWeaver::Transport::Faraday.new(url, open_timeout: 10, read_timeout: 30)
 GraphWeaver::Transport::Faraday.new(url) do |conn|
   conn.request :authorization, "Bearer", -> { Tokens.fetch }  # dynamic tokens
   conn.response :logger
@@ -71,23 +92,83 @@ 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:
+# socket keep-alive depends on the ADAPTER (see below) — the transport
+# logs the one it ended up with at :info:
 GraphWeaver::Transport::Faraday.new(url) do |conn|
-  conn.adapter :net_http_persistent   # gem "net-http-persistent"
+  conn.adapter :net_http_persistent
 end
 
+# In-process: a live graphql-ruby schema class, no socket — typed access
+# to your own app's API. The class alone works in any client slot; the
+# wrapper adds a request context, the same debug logging the network
+# transports emit, and errors branded under GraphWeaver::Error (a resolver
+# raise becomes a ServerError, status 500, with the original as #cause).
+GraphWeaver::InProcess.new(MySchema, context: { current_user: user })
+GraphWeaver.new(MySchema, context: { current_user: user })   # same, via a client
+
 GraphWeaver.client = ...   # the app default (a Client or any of the above)
 ```
 
+**Keeping Faraday's sockets alive.** Faraday's default `net_http` adapter
+opens a fresh connection per request — 10 TCP connections for 10 requests,
+and over HTTPS a TLS handshake each time. `:net_http_persistent` is the
+adapter that gets Faraday the connection reuse and thread-safe pooling
+`Transport::HTTP` has by default. It needs two gems, and the version
+pairing matters — **Faraday 2.x requires `faraday-net_http_persistent`
+2.x**; the Faraday-1.x-era 1.2.0 raises `NoMethodError: undefined method
+'dependency' for class Faraday::Adapter::NetHttpPersistent` at load:
+
+```ruby
+gem "net-http-persistent"                      # the HTTP client
+gem "faraday-net_http_persistent", "~> 2.0"    # the Faraday adapter for it
+```
+
+graph_weaver depends on neither and never selects an adapter for you.
+
+**Headers.** Both transports send `Content-Type: application/json`,
+`Accept: application/graphql-response+json, application/json;q=0.9` (the
+media type [GraphQL-over-HTTP](https://graphql.github.io/graphql-over-http/draft/)
+requires a conforming client to accept, with the legacy type as
+fallback), and `User-Agent: graph_weaver/<version>` so a server operator
+can attribute the traffic. Anything you pass in `headers:` wins over
+these. A prebuilt `Faraday::Connection` owns its own headers; only the
+ones it leaves unset are filled in.
+
+**Request body.** `{"query": ..., "variables": ...}`, plus
+`"operationName"` when the operation has a name — the field Apollo Studio,
+Hasura and most APMs key traces, rate limits and slow-query reports on.
+Generated modules always send one — an anonymous document is named after its
+module at generation, so the name is declared in the query too. A raw query
+string handed straight to a transport falls back to the name in the document,
+and a genuinely anonymous one sends no `operationName` key at all.
+
+**Concurrency.** One transport is normally the whole app's transport
+(`GraphWeaver.client = api`), so it has to serve every thread.
+`Transport::HTTP` opens up to `pool_size:` sockets lazily and reuses the
+warmest one; requests beyond that queue for a free slot rather than
+opening unbounded connections. A socket that errors is closed and its slot
+left empty, so the next call reconnects.
+
+`pool_size:` defaults to `RAILS_MAX_THREADS` (else 5) — the same variable
+Rails sizes its own connection pool from, because it is the same question:
+how many requests this process can have in flight at once. Lower it for a
+server that counts connections.
+
+Under a fiber scheduler (`async`, Falcon) everything here works unchanged —
+`SizedQueue`, `Mutex`, `net/http` and `Kernel#sleep` are all scheduler-aware,
+so requests multiplex on one thread at thread-equivalent throughput. But
+`pool_size:` is the same hard ceiling there, and nothing sets
+`RAILS_MAX_THREADS` for you, so set it to the concurrency you expect.
+Saturation is not silent: the first request that has to queue logs a warning
+naming how long it waited and what to raise.
+
 ## 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
+1. per call: `execute(client: some_client, ...)` — a kwarg like the
+   variables, and a name no GraphQL variable is allowed to take
 2. per module: `MyQuery.client = something`
 3. baked constant: `Codegen.generate(..., client: MyApi::CLIENT)`
 4. the app default: `GraphWeaver.client=`
@@ -112,11 +193,29 @@ GraphWeaver::Retry.new(
 ```
 
 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).
+`ServerError` on 5xx plus **408 and 429** — the rest of 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).
+
+**`Retry-After` wins over the backoff.** When the server names a delay
+(seconds or an HTTP-date), that's the wait — the server is the only
+party that knows when its window reopens. It's clamped to `max:` so a
+"come back in an hour" can't park a thread for an hour, and not
+jittered, since it's an instruction rather than a guess.
+
+`ServerError` carries the response `#headers` (names downcased), so the
+rate-limit budget and request id are in hand without monkey-patching a
+transport:
+
+```ruby
+rescue GraphWeaver::ServerError => e
+  e.throttled?                          # 429, or 503 + Retry-After
+  e.retry_after                         # seconds, or nil
+  e.headers["x-ratelimit-remaining"]
+end
+```
 
 Or via the client: `GraphWeaver.new(url, retries: { tries: 5, retry_codes: ["THROTTLED"] })`.