graph_weaver 0.6.0 → 0.7.0

data/docs/transports.md

@@ -21,11 +21,14 @@ 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)
-and `Transport::Faraday` (opt-in) — subclass `GraphWeaver::Transport`,
+and `Transport::Faraday` (opt-in: naming it loads faraday, so an app that
+doesn't needs no faraday) — 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.
+the whole recipe for bringing your own HTTP client. Return the response
+headers as a third element, downcased, and `ServerError#headers` carries
+them; two elements is still a complete answer.
 
 ## One-shot setup: a client
 
@@ -41,20 +44,32 @@ 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..."`)
+- `auth:` — a token, or something answering `#call` that returns one per
+  request; "Bearer" is assumed unless it carries its own scheme
+  (`"Basic dXNlcjpwYXNz..."`)
 - `transport:` — `:http` (the default) or `:faraday`
 - `headers:` — anything else (API keys, custom headers)
-- `retries:` — off by default; a count (`retries: 3`), or `true` for the
-  default count. Every other [`Retry`](#retries) option sits beside it
-  (`backoff:`, `retry_codes:`, ...)
+- `retries:` — off by default; every other [`Retry`](#retries) option sits
+  beside it (`backoff:`, `retry_codes:`, ...)
 - `open_timeout:` / `read_timeout:` — seconds, defaulting to 10 and 30 on
   either transport
+- `pool_size:` — how many sockets the bundled HTTP transport keeps open,
+  defaulting to `RAILS_MAX_THREADS` (else 5). Refused with
+  `transport: :faraday`, whose adapter owns its own connections — a ceiling
+  here would be a number nothing reads
 - `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)
 
+They combine, so the whole thing is still one call:
+
+```ruby
+GraphWeaver.new(url, transport: :faraday, retries: 2) do |conn|
+  conn.response :logger
+end
+```
+
 What you pass is what you get; the client logs which transport it built at
 `info`.
 
@@ -138,7 +153,55 @@ 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.
+ones it leaves unset are filled in — and Faraday's stock
+`User-Agent: Faraday v…`, which it fills in for every connection whether
+you asked or not, counts as unset.
+
+**Who the graph thinks is calling.** Both transports also send
+`apollographql-client-name` and `apollographql-client-version`, which is
+what an Apollo Router or GraphOS keys client attribution on — per-client
+SLOs and rate limits, and "who still asks for this deprecated field". The
+name is your Rails application's (`Storefront`), or `graph_weaver` outside
+Rails, since Apollo means the consuming *application*; the version is the
+gem's, because graph_weaver can't know what your app calls its releases.
+Both are plain headers, so `headers:` overrides them — which is how one app
+names its several clients apart:
+
+```ruby
+GraphWeaver::Transport::HTTP.new(url, headers: {
+  "apollographql-client-name" => "storefront-checkout",
+  "apollographql-client-version" => ENV.fetch("GIT_SHA"),
+})
+```
+
+**A header that expires.** A header *value* may be anything answering `#call`,
+on either transport, resolved per request rather than captured when the
+transport was built — the same way a graph's [`schema`](federation.md) takes a
+lambda. A value (or a call) of `nil` sends no such header; anything else is
+sent as its `to_s`, so a numeric tenant id needs no ceremony:
+
+```ruby
+GraphWeaver::Transport::HTTP.new(url, headers: {
+  "Authorization" => -> { "Bearer #{Tokens.fetch}" },   # rotating token
+  "X-Tenant" => -> { Current.tenant&.id },              # nil ⇒ header omitted
+})
+```
+
+`auth:` is that header under a shorter name, so a rotating credential is
+`GraphWeaver.new(url, auth: -> { Tokens.fetch })`. A prebuilt
+`Faraday::Connection` owns its own headers, so a rotating credential there is
+Faraday's middleware (`conn.request :authorization, "Bearer", -> { ... }`).
+
+**Compression and proxies** need no configuration on either transport.
+`net/http` — which both use underneath — asks for `gzip`/`deflate` on every
+request and decodes what comes back, and it reads `http_proxy` / `HTTPS_PROXY`
+and `no_proxy` from the environment. A proxy is never used for a loopback
+address, which is Ruby's rule, not ours.
+
+**The endpoint an error names** is the url with its userinfo and any secret
+query parameter folded to `[FILTERED]` — see [errors](errors.md). `#url` on a
+transport stays the real endpoint; `#safe_url` is the one that goes in a log
+line, an exception or an APM payload.
 
 **Request body.** `{"query": ..., "variables": ...}`, plus
 `"operationName"` when the operation has a name — the field Apollo Studio,
@@ -148,6 +211,40 @@ 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.
 
+**Variables have to be JSON.** The body is one `application/json` document, so
+every variable value, at any depth, must be something JSON carries: a string,
+a number, a boolean, null, a list, an object — or a value with an honest
+string form, which is how a `Date`, a `Time`, a `BigDecimal` or a `Symbol`
+travels. A `File`, an `IO`, a `Pathname` or a plain object is refused before
+the body is built, naming the variable: JSON would otherwise render it as its
+`#to_s`, so `$file` reaches the server as `"#<File:0x00007f…>"` and is stored
+as if it meant something. graph_weaver does not implement the [GraphQL
+multipart request
+spec](https://github.com/jaydenseric/graphql-multipart-request-spec), so an
+`Upload!` argument needs your own transport or a separate upload endpoint —
+registering a scalar can't help, because multipart restructures the whole
+request rather than one value.
+
+**No persisted-query id goes with it**, so a gateway safelist configured with
+`require_id` refuses every request this client makes; automatic persisted
+queries (APQ) are an optimization, so those just never kick in. Until the gem
+sends one, `post` is the seam — it sees the encoded body and can put the hash
+beside it:
+
+```ruby
+class APQ < GraphWeaver::Transport::HTTP
+  def post(body)
+    request = JSON.parse(body)
+    sha = Digest::SHA256.hexdigest(request.fetch("query"))
+    extensions = { "persistedQuery" => { "version" => 1, "sha256Hash" => sha } }
+    status, response, headers = super(JSON.generate(request.except("query").merge("extensions" => extensions)))
+    return [status, response, headers] unless response.to_s.include?("PersistedQueryNotFound")
+
+    super(JSON.generate(request.merge("extensions" => extensions))) # register on miss
+  end
+end
+```
+
 **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
@@ -165,6 +262,16 @@ 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.
 
+**The pool is fork-safe**, which is what a Puma or Unicorn worker under
+`preload_app!` needs. A socket warmed before the fork — an initializer that
+introspects the schema is enough — is otherwise inherited by every worker, and
+nothing in a round trip says which process opened it, so two workers
+interleaving on one fd hand each other's answers back. A child notices the pid
+changed and starts over: the inherited sockets are **abandoned rather than
+closed** (closing would take down the fd the parent is still using) and
+reconnect on first use, and the permits are rebuilt, since any held at fork time
+went with the threads that held them. There is no `after_fork` hook to write.
+
 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
@@ -181,8 +288,14 @@ takes a `Client` or any bare transport/fake):
 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=`
+3. a test mode's stand-in: under `graphql: :fake` / `:in_process` /
+   `:router`, built from the graph this module was generated from
+4. baked constant: `Codegen.generate(..., client: "MyApi::CLIENT")` — the
+   constant's *name*, not the object, because generated source spells it
+5. the app default: `GraphWeaver.client=`
+
+The mode replaces what codegen baked in, not what your example said — 1 and 2
+still win.
 
 Nothing set anywhere raises, naming the two you'd usually reach for:
 `no client configured — set GraphWeaver.client= or pass a client`.
@@ -209,12 +322,29 @@ GraphWeaver.new(
 `GraphWeaver::Retry.new(inner_transport, ...)` takes the same options and
 wraps any client/transport directly — the client just passes them along.
 
-Defaults: transport failures always retry; `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 the retries re-raises the last error (or
-returns the last code-matched response).
+Defaults: transport failures always retry; a response retries when its
+status is 5xx or **408 or 429** — the rest of 4xx is a bug in the request,
+retrying won't fix it. That's one rule for both shapes a failure arrives
+in: raised as a `ServerError`, or returned in the envelope because the
+server sent GraphQL errors alongside the status. Apollo Router does the
+latter for everything it decides itself — rate limiting is `503` with a
+`REQUEST_RATE_LIMITED` body — so a policy that read only the raised half
+made exactly one attempt behind a router. `retry_codes:` adds the other
+signal: error codes, at any status (off by default — pass the codes your
+API uses, or `GraphWeaver::GraphQLError::THROTTLE_CODES`). Exhausting the
+retries re-raises the last error (or returns the last response).
+
+A `200` is never retried on its status, whatever it carries. A router that
+gives up on a slow subgraph answers `200` with partial data and a
+`GATEWAY_TIMEOUT` error: the caller already has an answer, and whether a
+partial one is worth repeating is a judgment only the caller can make —
+`retry_codes: ["GATEWAY_TIMEOUT"]` is how they say yes.
+
+**Nothing else retries**, which is the half a script author needs: a `200`
+the server stands behind, and an `InputError` (the variables never left the
+process), are permanent by construction — the identical request gets the
+identical answer. Only a failure the server itself marked transient, by
+status or by code, is worth repeating.
 
 `retries:` counts the attempts *after* the first, so
 `GraphWeaver.new(url, retries: 3)` makes up to four and `retries: 0` never
@@ -229,20 +359,35 @@ it, and a second `charge` is worse than a failed one.
 `retry_mutations: true` opts an idempotent API back in; the skipped
 retry says so on the logger.
 
+The cap is on **attempts**, not on a kind of failure: a mutation gets its one
+attempt whatever `retry_on:` says, so a `ServerError` is not retried either —
+not a 500, not a 429 that named a `Retry-After`. `retry_mutations: true` puts
+the mutation back on the same budget as a query, for every one of them.
+
+**Idempotency is the server's.** GraphWeaver never reads an `idempotencyKey`
+input: it is an argument like any other, and nothing in the client
+deduplicates on it. So before turning `retry_mutations: true` on for a
+checkout, the *server* has to dedupe on that key. And either way a failed
+response does not mean nothing happened — the request that timed out was
+still delivered, so the order may exist behind the error your controller
+rendered. Reconcile; don't assume.
+
 **`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_delay:` 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:
+`ServerError` carries the response `#headers`, so the rate-limit budget and
+request id are in hand without monkey-patching a transport. Look one up in
+whatever casing the server used — field names are case-insensitive; iterating
+them yields the downcased spelling:
 
 ```ruby
 rescue GraphWeaver::ServerError => e
   e.throttled?                          # 429, or 503 + Retry-After
   e.retry_after                         # seconds, or nil
+  e.headers["Retry-After"]              # == e.headers["retry-after"]
   e.headers["x-ratelimit-remaining"]
 end
 ```

data/docs/upgrading.md

@@ -1,5 +1,10 @@
 # Upgrading
 
+[Regenerate](#regenerate-on-every-upgrade) whichever version you're on, then
+read the one section that is yours: from [0.6.1](#upgrading-from-061), from
+[0.5.1](#upgrading-from-051), or [to 0.5.0](#upgrading-to-050) from anything
+older.
+
 ## Regenerate on every upgrade
 
 **Any release can change what codegen emits.** Patch releases included — most of
@@ -19,6 +24,326 @@ moved. That's the reminder working, not a false alarm.
 Generation is deterministic, so the diff is exactly what the new version emits
 differently and nothing else — worth reading rather than rubber-stamping.
 
+## Upgrading from 0.6.1
+
+Mostly mechanical. Everything that wants your hands, or changes under you, is
+one row below; read the left column and skip what isn't yours. A typical app
+ticks two or three.
+
+| applies if you… | what changed |
+|---|---|
+| run a Rails app that configures no logger or instrumenter | **you start logging one info line per GraphQL call** — a production log-volume change, [first bullet below](#behavior-that-changed-under-you) |
+| wrap a gateway in `Retry` | **a 5xx/429 that arrives with an errors body retries now** — real traffic, [below](#behavior-that-changed-under-you); `retries: 0` opts out |
+| commit a schema dump introspected through a url carrying a token | **refresh it, and rotate the token if that file was pushed** — the dump recorded the url verbatim |
+| keep a schema dump deliberately behind your own schema class | `verify` fails on it now |
+| check in a composed supergraph as your dump | `schema:refresh` refuses it rather than overwriting it with the API schema — recompose instead |
+| use `@oneOf` input types and commit a `.json` dump | `@oneOf` starts being enforced client-side once you regenerate |
+| call `result.to_json`, or `render json: result` | it is the wire shape now, not `#inspect` or your prop names |
+| send a `File`, `IO` or `Pathname` as a variable | refused at the wire, where `JSON.generate` used to ship its `#to_s` |
+| pin a lowercase type name in `graphql_fake` | it works now; a near-miss *keyword* raises `ArgumentError` |
+| tag specs `graphql: false`, or set `config.default_mode = nil` | both refused — [renames](#renames) |
+| `rescue GraphWeaver::TypeError` or `GraphWeaver::ValidationError` | both constants are gone, with no alias — [renames](#renames) |
+| subscribe to `"graph_weaver.execute"` | the event is `"execute.graph_weaver"` — [renames](#renames) |
+| index a hash by an `InputError`'s `#field` | it names the input field now, not the variable — **nothing raises** |
+| read an `InputError`'s `#details[:type]` | it is the GraphQL type now, never a Ruby class — **nothing raises** |
+| read `payload[:status]` in an instrumentation subscriber | it is a Symbol; the HTTP status moved to `:http_status` — **nothing raises** |
+| call `respond_to?` on a result struct | it stopped answering true for props that don't exist — **nothing raises** |
+| generate a module with a baked `client:` | a `graphql:` tag now reaches it |
+| set `config.context`, `config.schema` or `config.router` from a `before` hook | all three refused — they are suite setup |
+| pass a `DateTime` where the schema says `Date` | refused — pass `.to_date` |
+| register a scalar with your own `cast:`/`serialize:` | the same guard as the built-ins, and a proc that returns a value is refused |
+| have a field named `class`, `hash`, `display`, `to_json`, `each` or `supplied` | the prop takes a trailing underscore |
+| have an entity `@key` that selects through a list | the kwarg is a list now, not one hash — regenerate |
+| build a type helper with `extend_type("Widget") { … }` | its constant is named for its graph and its type — regenerate |
+| adopt `GraphWeaver.graph` | every queries directory then needs one |
+| write `config.graph_weaver.<anything but watch>` | refused at boot |
+| pass `SUPERGRAPH=` to any task but `federation:*` | refused, where it was ignored — a CI step that did it goes red |
+| compare a `Testing::Router` error hash whole in a spec | a subgraph error carries `extensions: {"service" => …}` now |
+| pass `seed:` to `graphql_router(fake: …)` | refused |
+| require `graph_weaver/rspec` from `spec/support/` | check the glob is uncommented — rspec-rails ships it commented out |
+| adopt `graphql: :wire` | it needs `require "webmock/rspec"`, not just the gem |
+
+Then five commands, in order:
+
+```sh
+# 1. the two renames your own code holds
+grep -rn "GraphWeaver::TypeError\|GraphWeaver::ValidationError" app lib spec
+grep -rn "graph_weaver.execute" app lib config spec   # the old event name
+
+# 2. rewrite the dump: it drops a credential the url carried, and picks up
+#    isOneOf. Skip only if your dump is SDL and records no source url — and
+#    a composed supergraph refuses, since introspection can't rebuild one:
+#    `rover supergraph compose` is what rewrites that.
+rake graph_weaver:schema:refresh
+
+# 3. regenerate — also the graph name in every module, the underscored
+#    reserved props, as_json, and the client: and cast:/serialize: refusals
+rake graph_weaver:generate
+
+# 4. the renamed tag, the deleted nil, the seed: refusal
+bundle exec rspec
+
+# 5. the gate: red while any checked-in file is still what 0.6.1 wrote
+rake graph_weaver:verify
+```
+
+**Two kinds of file answer that first grep, and only one needs your hands.**
+Hits under your generated directory (`app/graphql/generated/` by default) are the
+old names in machine-written code — step 3 rewrites them. Hits anywhere else are
+yours: `CastError` and `QueryValidationError`, renamed by hand.
+
+### Renames
+
+| before | after |
+|---|---|
+| `graphql: false` (rspec tag) | `graphql: :live` — the opt-out is your own client, which is a mode like the other four; `false` is refused, naming it |
+| `config.default_mode = nil` | `config.default_mode = :live`, which is now the **default** — every example has exactly one mode, and `nil` is no longer a value it reads back |
+| `GraphWeaver::TypeError` | `GraphWeaver::CastError` — the response wouldn't cast into the generated structs; the old name shadowed a core class it doesn't descend from. No alias: the old constant is gone, so a stale `rescue` is a `NameError` |
+| `GraphWeaver::ValidationError` | `GraphWeaver::QueryValidationError` — build time, the *query* against the schema. Your input's validation is `InputError`. No alias here either |
+| `"graph_weaver.execute"` | `"execute.graph_weaver"` — `<event>.<namespace>`, the way every notification in this ecosystem is spelled, and what `LogSubscriber.attach_to` and an APM's namespace routing key on. Subscribe through `GraphWeaver::EXECUTE_EVENT` and there is nothing to rename; a hardcoded string silently stops matching |
+
+### Behavior that changed under you
+
+The first one reaches every Rails app that never configured logging, and it is
+the only one here that shows up in production rather than in your code.
+
+- **A Rails app logs one line per GraphQL call, and emits one notification.**
+  The railtie now sets `GraphWeaver.instrumenter` to the
+  `ActiveSupport::Notifications` adapter and attaches
+  `GraphWeaver::LogSubscriber`, so an app that configured neither gets
+  `GraphWeaver billing/InvoicesQuery (12.3ms) ok` at **info** — one line per
+  operation, carrying nothing that can hold PII; the query and variables stay
+  at debug. An instrumenter you set yourself is never replaced, and **to opt
+  out, set `GraphWeaver.logger = nil` or `GraphWeaver.instrumenter = nil` in
+  `config/initializers`** — which now takes effect, so an app that worked
+  around it with `config.after_initialize { GraphWeaver.logger = nil }` can
+  drop that. In-process calls are in scope too: a bare schema class in a client
+  slot (`GraphWeaver.client = MyApp::Schema`, `execute!(client: MyApp::Schema)`,
+  a graph's `client "Billing::Schema"`) goes through the same wrapper
+  `GraphWeaver.new(MyApp::Schema)` always used, so it produces events and log
+  lines where it produced none. See [logging](logging.md).
+- **A `Retry` in front of a gateway starts actually retrying.** It read only
+  the failures that *raised*, and Apollo Router answers everything it decides
+  itself with a GraphQL errors body — rate limiting is `503` plus
+  `REQUEST_RATE_LIMITED`, its own faults are `500` plus a code — so the body
+  won over the status and `retries: 3` made one attempt. A response retries now
+  when its status is one a `ServerError` retries on (5xx, 408, 429), or when
+  its error codes are named in `retry_codes:`. A `200` is never retried on
+  status, and a mutation still gets one attempt unless `retry_mutations:
+  true`. **This is real traffic you weren't sending** — if the inert policy was
+  what you wanted, `retries: 0`. `#throttled?` answers
+  `REQUEST_RATE_LIMITED` too.
+- **A task that can't honour `SUPERGRAPH=` refuses instead of ignoring it.**
+  The flag reaches the `federation:*` tasks and nothing else, so
+  `SUPERGRAPH=public.graphql rake graph_weaver:queries:check` reported every
+  query valid against a supergraph missing a field they select — the wrong
+  answer wearing a green tick. **A CI step that passes it to `generate`,
+  `verify` or `queries:check` goes red**; drop the flag, or declare the
+  supergraph on a graph so every run finds it.
+- **`InputError#field` names the input field, not the variable.** It is now
+  `#path`'s last *named* segment — the slot that actually held the bad value,
+  which is the one a form highlights — where it used to be re-branded on the
+  way out with the *variable* name. Nothing raises; the value just differs once
+  a refusal happens inside an input object. **Read `error.path.first` wherever
+  you wanted the variable**, and `#field` wherever you wanted the field. On a
+  refusal that never got past the variable the two are the same, which is why
+  this can pass unnoticed until the first nested input fails. An index is a
+  position rather than a field, so it never becomes one: `execute(ids: [1, 2,
+  "x"])` reports `#path` `["ids", 2]` and `#field` `"ids"`. **Self-check:**
+  `grep -rn "\.field" app lib` — every hit that indexes or compares an
+  `InputError`'s `#field` is a place to decide which of the two you meant.
+- **The instrumentation payload's `:status` is a Symbol, and the HTTP status
+  moved to `:http_status`.** `:status` is now `:ok`, `:errors` (the response
+  came back carrying GraphQL errors) or `:failed` (it raised) — a 200 carrying
+  errors is not a success, and only a symbol says that on both sides of the
+  seam. Nothing raises: a subscriber comparing it to an Integer just stops
+  matching. **A subscriber that branched on `payload[:status] == 200`, or on a
+  4xx/5xx, reads `:http_status` now** — which is nil in-process, where
+  `:status` used to be a fabricated 200 so one subscriber could read both
+  sides. The whole payload is a documented contract now; see
+  [logging](logging.md#the-payload). **Self-check:** nothing subscribing to
+  `execute.graph_weaver` means nothing to change — this reaches subscribers
+  only.
+- **`respond_to?` on a result struct no longer answers true for a name that
+  doesn't exist.** It used to say true for any near miss, which broke the
+  standard duck-typing guard — `obj.pet if obj.respond_to?(:pet)` raised the
+  very `NoMethodError` the hint exists to explain. **A branch that read the old
+  answer now takes the other path**, and `struct.method(:nmae)` raises Ruby's
+  bare `NameError` rather than a hinted one; `struct.nmae` still hints.
+- **A `graphql:` tag reaches a module generated with `client:`.** The baked
+  client used to sit above the slot a tag swaps, so a bound module ran against
+  its real endpoint under `graphql: :fake`. **If a spec relied on that**, it now
+  runs against the fake — pass `client:` on the call, set `MyQuery.client =`, or
+  tag the example `graphql: :live`.
+- **`config.context`, `config.schema` and `config.router` are suite setup.**
+  Setting any of the three once an example is running refuses, naming the
+  per-example helper (`graphql_context`, `graphql_fake(schema:)`,
+  `graphql_router(fake:)`). The tag builds an example's clients in a `before`
+  hook of its own, which rspec runs ahead of any group `before`, so a set there
+  was read too late and silently changed nothing — a `config.context` that
+  never reached a resolver, a `config.schema` the fake never saw. The refusal
+  replaces a line that wasn't working. **Move it to an `around`, or to
+  `GraphWeaver::Testing.configure` in the spec helper**; `configure` and
+  `around` are unchanged.
+- **`result.to_json` is real JSON, and it is the wire shape.** It used to be
+  Ruby's `Object#to_json` — the `#inspect` string, quoted — so a log line or a
+  cache write stored nothing, with no exception and no warning; under Rails
+  `render json: result` instead shipped the *Ruby* prop names, trailing
+  underscores included. Both now produce the response keys, each leaf back
+  through its scalar registration's `serialize:`, so
+  `Result.from_h(JSON.parse(result.to_json)) == result`. `#to_h` is unchanged
+  and still the Ruby view. **Anything that parsed the old output, or diffed a
+  cached copy of it, is reading something different now** — and `as_json` is
+  emitted code, so a struct generated by 0.6.1 raises `GraphWeaver::Error`
+  naming this until you regenerate.
+- **A schema dump introspected through a credentialed url still holds the
+  token.** The provenance stamp wrote the transport's url verbatim, so a url
+  carrying userinfo or an `?access_token=` landed in a file that gets
+  committed. It records the endpoint bare now — userinfo and any query
+  parameter `filter_parameters` filters are dropped — and re-introspection
+  still authenticates from the dump's `auth_env`. **Run `rake
+  graph_weaver:schema:refresh` once, and rotate the token if that file was ever
+  pushed.**
+- **`verify` fails when the dump has fallen behind the schema class it was
+  built from.** For an app that serves its own schema the dump is an artifact
+  derived from code in the same repo, and everything downstream reads it, so
+  `generate` and `verify` both called a tree up to date while the live
+  resolvers had already moved. **A dump you deliberately keep behind your own
+  schema is a red gate now** — `rake graph_weaver:schema:refresh`, or ask about
+  no dump at all with `verify_generated!(schema:)`. It costs one in-process
+  introspection per graph and never a network call.
+- **`@oneOf` starts being enforced if your dump is `.json`.** graphql-ruby's
+  introspection query omits `isOneOf` unless asked, and its loader drops the
+  field even when it is there, so every dump this gem has written said "not
+  @oneOf" for every input object and the enforcing struct was never generated.
+  **Regenerate (`rake graph_weaver:schema:refresh && rake
+  graph_weaver:generate`) and the emitted `ONE_OF` starts refusing calls that
+  set two fields** — which your server was refusing all along, so the failure
+  moves from the wire into `execute`. SDL dumps, inline SDL and a live class
+  were always correct.
+- **A fake pin is told from an option by a schema lookup, not by casing.** The
+  rule was "a dot or a leading capital is a pin", so a lowercase type could not
+  be pinned at all: `graphql_fake("pokemon_v2_pokemon" => …)` against a Hasura
+  API came back as `a fake doesn't take pokemon_v2_pokemon:`. Those pins work
+  now. The other side of it: **a keyword that is a near-miss for a pin
+  (`Persn: "Ada"`) raises `ArgumentError` from the fake** rather than
+  `GraphWeaver::Error` from the override check — the same key written in the
+  leading positional hash is unchanged, and is the spelling for a schema whose
+  vocabulary collides with an option name.
+- **Regenerate**, as ever — generated modules carry a private `GRAPH` naming the
+  graph they were generated from, and a [multi-schema](getting_started.md#more-than-one-schema)
+  app whose modules predate it refuses rather than guessing which schema a
+  module belongs to. A generated `execute` also makes its request through the
+  gem now (`from_response(dispatch(variables, client:))`), which is what lets
+  an event name the graph; 0.6.1's modules keep working as they are, but `rake
+  graph_weaver:verify` reports the tree out of date until you regenerate.
+  Result structs also gained `==`/`eql?`/`hash`, `deconstruct_keys`, `#to_h`
+  and `#as_json`, and the emitted guard in front of a `cast:` changed (below).
+- **Check that your `require "graph_weaver/rspec"` actually runs.** The old
+  setup put it in `spec/support/graph_weaver.rb`, and rspec-rails ships the
+  `spec/support` glob **commented out** — so if you never uncommented it, the
+  tag did nothing and every `graphql: :fake` example has been hitting the real
+  client. `rails g graph_weaver:install` now writes the line into
+  `spec/rails_helper.rb` instead; **move yours there** if the glob isn't live.
+- **`graphql: :wire`, if you adopt it, needs webmock *enabled*** — `require
+  "webmock/rspec"` in the spec helper. Having it in the Gemfile is not enough:
+  `Bundler.require` loads webmock without installing its adapters, and the tag
+  refuses before the first request rather than letting it leave the suite.
+- **A `DateTime` given for a `Date` variable is refused.** `DateTime` is a
+  `Date` to Ruby, so it used to pass the cast untouched and go on the wire as
+  `"2024-01-15T10:20:30+00:00"` where the schema said `ISO8601Date` — a lenient
+  server truncated it, a strict one refused it. Truncating it here would be the
+  same guess made silently, so it now raises an `InputError` naming the class
+  and the fix: `$d of On: expected a Date, got a DateTime — pass .to_date if
+  dropping the time of day is what you meant`. **Pass `.to_date` where a
+  `DateTime` reaches a `Date` variable.** The pairings that already raised —
+  a `Time` for a date, a `Date` for a timestamp — now raise that branded
+  `InputError` rather than Ruby's *"no implicit conversion of Time into
+  String"*, and a `DateTime` or `Time.zone.now` for a *timestamp* converts
+  losslessly where it used to raise.
+- **A `cast:` of your own gets the same guard and the same verdict.** A
+  registration like `register_scalar("Date", Date, cast: :iso8601, serialize:
+  :iso8601)` emitted a bare `value.is_a?(Date)` pass-through, so a `DateTime`
+  went by untouched and your `serialize:` wrote a full timestamp into a date
+  field — **pass `.to_date` there too**. Anything else wrong used to arrive as
+  Ruby's own sentence about an argument you never wrote (`no implicit
+  conversion of Integer into String`) under `kind: :unparseable`; the verdict
+  is the library's now and splits the way Ruby does — a `TypeError` from a
+  codec reads `expected a Date, got 5` under `kind: :type_mismatch`, an
+  `ArgumentError` keeps the parser's words under `:unparseable`.
+  **`#details[:type]` is the GraphQL type now, never a Ruby class** — a
+  `register_scalar("Money", BigDecimal)` field reads `"Money"`, not
+  `"BigDecimal"`, and an input object reads its schema name rather than the
+  class generated for it; the *message* still names the Ruby you may pass.
+  **A spec matching the old
+  message, or branching on `:unparseable` for a wrong class, needs updating**
+  — and the guard is emitted into your generated files, so a checked-in one
+  keeps the old behavior until you regenerate.
+- **A field whose name a struct already answers to now generates as `name_`.**
+  `class` becomes the prop `class_`, `hash` becomes `hash_`, and so on for
+  `display`, `to_json`, `each` and (on an input) `supplied`. Nothing that used
+  to work stops working: a key you aliased in the query to get past the old
+  *"alias it in the query"* refusal still generates from that alias — **drop
+  the alias and regenerate** if you want the field's own name back. Only the
+  Ruby name moves; the wire keeps the schema's spelling in both directions, so
+  `result.class` is still Ruby's `class` and `result.class_` is the field. The
+  prop is the field's one Ruby name, so `.coerce({ class_: … })` and a result's
+  `#to_h` and pattern matching all use it. An `InputError`'s structured half is
+  the wire's throughout, so a refusal on that field reports `#path` `["class"]`
+  and `#coordinate` `"Tricky.class"`. An **input** struct's `#to_h`
+  is the wire hash it would send, `{"class" => …}`, and input structs don't
+  pattern-match. Input types had no way past the old refusal at all, so a
+  schema with a `class` column — a Hasura `bool_exp` has one input field per
+  column — generates for the first time. The names that take an underscore are
+  a list the gem owns, rather than whatever `T::Struct` answered to in the
+  generating process: deriving them made generation depend on require order, so
+  with ActiveSupport loaded first a key named `asJson` was refused and loaded
+  second it became a prop that shadowed the real `#as_json`. The list is what a
+  struct answers — `T::Struct` and `Object`'s public instance methods, the
+  hooks Ruby and Rails call on an object that doesn't define one (`initialize`,
+  `to_ary`, `to_hash`, `to_json`, `as_json`, `to_param`, `try`, `presence`,
+  `each`, `deconstruct_keys`), and the methods the gem's own mixins define — so
+  a few more names move than 0.6.1 touched. Kernel's *private* methods are not
+  on it: `format`, `select`, `test`, `open`, `load` and `pp` are ordinary
+  column names, and the gem's mixins qualify their own calls (`Kernel.raise`)
+  so a prop may take one. A federation `@key` on such a field follows the same
+  rule instead of being refused: the kwarg takes the underscore
+  (`Representations.room(class_: …)`) and `"class"` still goes on the wire, so
+  **regenerate if a `@key` of yours names one**. Generated source marks each
+  rename on the line above the prop — `# wire: class — reserved as a prop
+  name` — so **read the regenerate diff** rather than grepping for the names
+  yourself.
+- **If you adopt `GraphWeaver.graph`, every queries directory needs a graph.**
+  Declaring one replaces the implicit graph your top-level settings describe,
+  so an app that declares a graph beside its existing `app/graphql/queries`
+  leaves that directory unread — `generate` skipping it, `verify` calling the
+  tree up to date. `generate!`, `verify_generated!` and `check_queries` refuse
+  instead, naming the stray files. **Name the directory in a graph
+  (`queries`/`output`), declare a graph for it, or delete it.** An app that
+  declares no graph is unaffected.
+- **A `client` that isn't a constant is refused at generation.** Its value is
+  spelled into every module the graph generates, so `client` given an endpoint
+  url emitted a file that doesn't parse, from a run that reported success.
+  Declare the constant and name it — `CLIENT = GraphWeaver.new(url)`, then
+  `client "CLIENT"` — which is what the message says.
+- **A `cast:` or `serialize:` proc that returns a value is refused at
+  registration.** A proc there builds *source* for the generated file, so
+  `cast: ->(v) { v.to_sym }` interpolated to nothing and every response failed
+  far from the registration, blaming the codec. It is probed once when
+  registered now: return the source (`cast: ->(v) { "Money.parse(#{v})" }`) or
+  name a method instead (`cast: :parse`).
+- **`config.graph_weaver` refuses a key the railtie doesn't read**, at boot. It
+  takes `watch`; `config.graph_weaver.queries_paths = …` was taken silently and
+  did nothing, so the refusal replaces a line that wasn't working — in every
+  spelling of that write, `config.graph_weaver[:queries_paths] = …` included.
+  **Move it to `GraphWeaver.queries_paths =`**, which is what the message says.
+- **A router's `fake:` refuses `seed:`**, as `graphql_fake` already did. A
+  router is built once for the suite, so a seed inside
+  `graphql_router(fake: …)` would pin every example to one run — `rspec --seed
+  1234` reproduces the fabricated data along with the test order, and
+  `GraphWeaver::Testing.config.seed` is the override for a harness that isn't
+  rspec.
+
 ## Upgrading from 0.5.1
 
 Much smaller than 0.5.0, and mostly mechanical. Three commands find most of it:
@@ -157,14 +482,14 @@ are emitted `private_constant`, so **regenerate**.
   for the type** — `Testing.config.overrides = { "Money" => "12.00" }`, or the
   same key on one example's `graphql_fake`. Without one, `FakeClient` and
   cassette anonymization refuse rather than feeding your cast a `"Money-1"`
-  placeholder. Scalars registered as `Time`, `Date`, `Integer`, `Float`,
-  `String` or `T::Boolean` need nothing.
+  placeholder. Scalars registered as `BigDecimal`, `Time`, `Date`, `Integer`,
+  `Float`, `String` or `T::Boolean` need nothing.
 - **Re-run `rake graph_weaver:cassettes:anonymize`** on any committed cassette
   holding a registered custom scalar: the anonymizer used to write a value the
   generated codec couldn't read back.
 - **Generation refuses four more things**, each naming its fix — a
-  `register_scalar` whose Ruby type nothing can build out of JSON (`BigDecimal`,
-  classically: give it a `cast:`), a result key that would shadow a constant the
+  `register_scalar` whose Ruby type nothing can build out of JSON (a value
+  object of your own: give it a `cast:`), a result key that would shadow a constant the
   file uses, an enum value that camelizes to nothing, and a narrowed fragment
   whose `__typename` sits behind `@skip`/`@include`.
 
@@ -283,7 +608,7 @@ carries it — `SearchQuery::Result::Search::Species` is `GraphQLTypes::Species`
 |---|---|
 | `Testing.config.auto_fake = true` | `Testing.config.default_mode = :fake` |
 | a mutation's `…Query` module | `…Mutation` |
-| `graphql: :none` (rspec tag) | `graphql: false` |
+| `graphql: :none` (rspec tag) | `graphql: :live` |
 
 **The shared types module was three, and is now one.** `GraphQLInputs`,
 `GraphQLEnums` and `GraphQLUnions` are all `GraphQLTypes`, and the files move

data/graph_weaver.gemspec

@@ -40,12 +40,19 @@ Gem::Specification.new do |s|
   s.add_development_dependency "debug"
   s.add_development_dependency "faker"
   s.add_development_dependency "faraday"
+  s.add_development_dependency "rack" # WebMock's to_rack needs it; webmock doesn't depend on it
   s.add_development_dependency "rake"
+  # spec/railtie_spec.rb boots a real Rails application: the railtie's bug of
+  # record was Rails' initializer TSort putting graph_weaver.logger after
+  # config/initializers, which a stand-in cannot model. Brings activesupport,
+  # which LogSubscriber is checked against for the same reason.
+  s.add_development_dependency "railties"
   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 "webmock" # graphql: :wire serves its Rack app through it
   s.add_development_dependency "webrick"
   s.add_development_dependency "yard"
 end