graph_weaver 0.4.6 → 0.5.1

data/docs/errors.md

@@ -11,6 +11,7 @@ response = PersonQuery.execute(id: "1")   # => GraphWeaver::Response[Result]
 response.data           # T.nilable(Result) — typed, present even on partial success
 response.errors         # Array[GraphWeaver::GraphQLError]
 response.errors?        # any top-level errors?
+response.success?       # the same question the other way round
 response.extensions     # { "cost" => … } — rides on success too
 response.data!          # the Result, or raise GraphWeaver::QueryError
 ```
@@ -22,17 +23,29 @@ Every `GraphQLError` exposes `#message`, `#locations`, `#path`, `#extensions`,
 and `#code` (`extensions["code"]`) — match on the **code**, not the message
 string (`response.errors.first.code == "THROTTLED"`).
 
-Everything GraphWeaver raises descends from `GraphWeaver::Error`, split by where
-it failed:
+Everything GraphWeaver *concludes* descends from `GraphWeaver::Error` — a
+transport failure, a rejected query, a response that wouldn't cast, a plan the
+[local router](federation.md) refused, a subgraph map that doesn't add up. The
+subclass says where it failed:
 
 | Class | When |
 |-------|------|
 | `TransportError` | never reached the server — DNS, connection refused, TLS, timeout |
-| `ServerError` | reached it, non-2xx HTTP — `#status`, `#body` |
-| `QueryError` | 200 body with top-level GraphQL errors — `#errors`, `#data`, `#extensions`, `#codes` |
+| `ServerError` | reached it, non-2xx HTTP — `#status`, `#body`, `#headers`, `#retry_after`, `#throttled?` |
+| `QueryError` | 200 body with top-level GraphQL errors — `#errors`, `#data`, `#extensions`, `#codes`, `#throttled?` |
 | `TypeError` | the response wouldn't cast into the generated structs — `#struct`, `#cause` |
-| `InputError` | the variables wouldn't build into the generated input structs — unknown/typo'd key, missing required field, out-of-range enum, wrong-typed field — `#field`, `#struct` |
+| `InputError` | the variables wouldn't build into the generated input structs — unknown/typo'd key, missing required field, out-of-range enum, wrong-typed field, wrong number of @oneOf fields — `#field`, `#struct` |
 | `ValidationError` | build time: the query didn't validate against the schema |
+| `Codegen::Aliases::UnknownSegment` | build time: an [`alias:`](generated_modules.md#flat-accessors-with-alias) path names a field no type here has — a typo, so `optional: true` won't skip it |
+| `ConfigurationError` | setup judged against your schema — which Ruby schema serves which subgraph (`Testing::Router`, `federation:diff`) |
+| `Testing::Unplannable` | the local test router won't plan this operation — `#category`, `#detail` |
+| `Testing::MissingRecording` | a [cassette](cassettes.md) holds no entry for this request — the message prints the variables, and the ones it did record |
+
+An argument that is wrong *on its face* raises a plain `ArgumentError` instead
+(`pool_size: must be >= 1`, `cast: must be a Symbol, Proc, :itself, or nil`),
+like any Ruby method — a bug at the call site, not a condition to rescue. The
+line is whether the library had to read your schema to reach the verdict: it
+did for `ConfigurationError`, which is why a spec helper can rescue that one.
 
 ```ruby
 begin
@@ -40,30 +53,22 @@ begin
 rescue GraphWeaver::TransportError
   retry                                   # network blip
 rescue GraphWeaver::ServerError => e
-  e.status >= 500 ? backoff : raise       # retry 5xx; a 4xx is our bug
+  e.throttled? || e.status >= 500 ? backoff : raise  # a plain 4xx is our bug
 rescue GraphWeaver::QueryError => e
-  e.codes.include?("THROTTLED") ? backoff : raise
+  e.throttled? ? backoff : raise          # the same question, asked of the errors array
 end
 ```
 
-Or skip the hand-rolling — `Retry` wraps any transport with
-configurable retries:
-
-```ruby
-transport = GraphWeaver::Retry.new(
-  GraphWeaver::Transport::HTTP.new(url),
-  tries: 5,                        # total attempts
-  backoff: :exponential,           # or :linear, or ->(attempt) { seconds }
-  base: 0.5, max: 30,              # seconds, clamped at max:
-  jitter: true,                    # randomize each delay by 50-100%
-  retry_codes: ["THROTTLED"],      # also retry GraphQL errors by code
-)
-```
+`#throttled?` deliberately spells the same on both: an API may say "slow
+down" with a 429 or with a `THROTTLED` error in a 200 body, and a caller
+shouldn't have to know which. It recognizes the codes the big graphs
+actually send (`GraphWeaver::GraphQLError::THROTTLE_CODES` — Shopify's
+`THROTTLED`, GitHub's `RATE_LIMITED`, and friends); pass that constant to
+`Retry`'s `retry_codes:` instead of hand-writing the strings.
 
-Defaults match the rescue block above: transport failures always retry,
-`ServerError` only on 5xx (a 4xx is your bug — retrying won't fix it;
-override with `retry_if:`), and GraphQL-level codes only when listed in
-`retry_codes:`. Exhausting `tries:` re-raises the last error.
+Or skip the hand-rolling: [`Retry`](transports.md#retries) wraps any client and
+already defaults to exactly the policy above — transport failures always,
+`ServerError` on 5xx plus 408/429, and GraphQL error codes you name.
 
 **Top-level scalar variables** fail like any Ruby method call, *outside* the
 hierarchy on purpose — passing the wrong Ruby type for a scalar kwarg is a
@@ -73,10 +78,9 @@ String"), a missing required one a plain `ArgumentError` ("missing keyword: :id"
 
 **Input-object variables** are the caller-input case, so they're *inside* the
 hierarchy. When you pass an input object as a hash (or struct) it's built
-through the generated `coerce`, and any problem there — an unknown/typo'd key, a
-missing required field, an out-of-range enum, a wrong-typed field — raises
-`GraphWeaver::InputError`. That's one rescue point for turning invalid input
-into a 422:
+through the generated `coerce`, and anything wrong in there raises
+`GraphWeaver::InputError` — one rescue point for turning invalid input into a
+422:
 
 ```ruby
 rescue GraphWeaver::InputError => e
@@ -94,8 +98,8 @@ Business/validation failures returned *as data* (Shopify-style `userErrors { fie
 message code }`) aren't errors here — they're just fields you selected, so they
 deserialize onto `response.data` like anything else and you inspect them there.
 
-The one-shot `GraphWeaver.execute` / `execute!` mirror this: `execute` returns
-the envelope, `execute!` the result-or-raise.
+The one-shot `GraphWeaver.run` / `run!` mirror this: `run` returns
+the envelope, `run!` the result-or-raise.
 
 ## Extending TransportError