graph_weaver 0.6.0 → 0.7.0

data/docs/i18n.md

@@ -0,0 +1,234 @@
+# Translating input errors
+
+The keys and the data an app translates "that input was wrong" from, without
+reading English sentences. See [errors](errors.md) for `InputError` itself and
+for what a server has to send.
+
+## The one idea
+
+A library that hands you a sentence has already decided what your user reads, in
+one language, in its own voice. So graph_weaver should hand you **a stable key
+and the facts**, and let the app own the sentence:
+
+- **stable** — a `kind` from a short closed vocabulary, and the key derived from
+  it, `graph_weaver.input.<kind>`. These are API: they change only with a MAJOR
+  bump, and a new one arrives only as an addition.
+- **data** — the field, the value, the enum's members, the bounds. Never baked
+  into the message only, and never pre-formatted (`members` is an Array, not
+  "CAT or DOG" — joining it is a language decision).
+- **not stable** — `#message`. It is the developer's line, in English, and it
+  will be reworded.
+
+## The vocabulary
+
+Eight kinds, each one sentence. A ninth arrives only when a real input failure
+fits none of them — `:refused` is the honest home for everything else.
+
+The last four columns are **who can say it**, which is the other half of the
+story — a `kind` is worth only as much as the producer that can state it. The
+last of them is any server at all, through the
+[convention](#what-the-server-has-to-do).
+
+| `kind` | means | `details` carries | client | graphql-ruby | Hasura | convention |
+|---|---|---|---|---|---|---|
+| `:type_mismatch` | the value is not the type the schema declares, and no conversion applies | `type` | yes | yes | **no** | yes |
+| `:unparseable` | the right kind of thing, but the text doesn't parse as that scalar | `type` | yes | yes | **no** | yes |
+| `:not_a_member` | not one of the values an enum (or an inclusion rule) allows | `members` | yes | yes | yes | yes |
+| `:missing` | a required field or argument wasn't supplied, or was null | — | yes | yes | yes | yes |
+| `:unknown` | a key the input type doesn't define — a typo | `suggestion` | yes | yes | yes | yes |
+| `:out_of_range` | a number, length or date outside the bounds the schema states | `min`, `max` | **no** | **no** | **no** | yes |
+| `:invalid_format` | parses, right type, but fails a stated semantic rule — a regex, an email | `pattern` | **no** | **no** | **no** | yes |
+| `:refused` | rejected, with nothing more than a message — the fallback, never a guess | — | yes | yes | yes | yes |
+
+Those are the servers graph_weaver reads by name. **Apollo** is `:refused` and
+the server's own sentence, nothing finer — `BAD_USER_INPUT` says the input was
+bad and not what about it. **Anything else** says nothing graph_weaver will
+claim: `#input_errors` comes back `[]`, and the rejection stays an ordinary
+error to render as the server wrote it. Hasura's two extra blanks are one
+sentence doing two jobs: the same "expected a non-negative 32-bit integer" answers
+`limit: -5` and `limit: "lots"`, so both arrive `:refused` on the right field
+rather than one of them arriving confidently wrong. Which shape each server is
+read off is in [errors](errors.md#when-the-server-rejects-the-input).
+
+`field` and `value` ride on every kind. `value` is the offending value passed
+through [`filter_parameters`](logging.md#filtered-variables), so it reads
+`"[FILTERED]"` under a sensitive key and `nil` when the producer never said what
+the value was.
+
+Two rows carry the headline: **`:out_of_range` and `:invalid_format` — the
+customer's "right type but out of range" and "bad semantic format" — cannot be
+produced from either side without the
+[server convention](errors.md#what-your-server-can-send).** The client doesn't
+know the schema's bounds, and a graphql-ruby `validates:` failure reaches the
+wire as a bare sentence with no `extensions` at all.
+
+`@oneOf` violations map to `:refused`, with one exception that isn't really
+one: exactly one field, explicitly null, is `:missing` on that field — the
+count is right and the value isn't, which is the same thing `:missing` means
+everywhere else, and it gives a form the one slot to highlight. The wrong
+*count* has no single field to name, so it stays a message ("supply exactly one
+field, non-null, got a, b"); one rule in twenty schemas doesn't earn a ninth
+kind.
+
+## The shape
+
+One class, carried by both halves. `GraphWeaver::InputError` is *raised* before
+the request leaves — rescuing it is a control-flow decision (render a 422) — and
+it is also the **value** a server's rejection becomes, which has precedent:
+`Response#errors` already holds unraised `GraphQLError`s. One class, zero new
+nouns, one renderer for both halves.
+
+```ruby
+GraphWeaver::InputError              # kind, path, coordinate, value, details, field, struct
+GraphWeaver::GraphQLError#input_errors    # [] when the error isn't about input
+GraphWeaver::Response#input_errors        # and QueryError#input_errors
+```
+
+Plural on all three: one variable-coercion error routinely carries several
+problems about different fields, and keeping only the first would lose the rest
+silently.
+
+- `path` — rooted at the **variable**: `["where", "_and", 0, "_not", "species"]`,
+  so `$where._and.0._not.species`. Every named segment is the **schema's**
+  spelling (`issuedOn`, not the `issued_on` you type in Ruby), whichever side
+  refused — [why](errors.md#which-spelling-a-path-is-in). `[]` when the
+  producer named no slot; `#field` is its last named segment.
+- `coordinate` — the GraphQL [schema coordinate](https://github.com/graphql/graphql-spec/pull/794):
+  `"PetFilter.species"`. `nil` when unknown — a variable names no schema
+  element, and a graphql-ruby coercion error rarely names the nested input type.
+
+## Translating it
+
+```ruby
+def render_input_error(error)
+  I18n.t(
+    "graph_weaver.input.#{error.kind}",
+    field: error.field,
+    value: error.value,
+    **error.details,
+    default: error.message,   # untranslated kinds fall back, never "translation missing"
+  )
+end
+```
+
+```ruby
+# before the wire
+rescue GraphWeaver::InputError => e
+  form.errors.add(e.field&.underscore || :base, render_input_error(e))
+
+# and after it, the same call
+response.input_errors.each { |e| form.errors.add(e.field&.underscore || :base, render_input_error(e)) }
+```
+
+`#field` is the schema's spelling on both sides, so one `underscore` is the
+whole mapping to a Rails form field — and the two calls above really are the
+same call. **Plan for `nil`**: nothing named a slot, which is exactly what a
+server that states no input path gives you, and that is the default until your
+server adopts [the convention](errors.md#what-your-server-can-send).
+
+**`field:` can't say which row.** A list index lives in `#path` and nowhere
+else, so every element of `lines: [LineInput!]!` translates to the same
+sentence. Where a form lists rows, label it from the path:
+
+```ruby
+# "input.lines.0.qty", where #field alone is "qty" for every line at once
+I18n.t("graph_weaver.input.#{error.kind}", field: error.path.join("."), **error.details)
+```
+
+`default:` is the load-bearing half: `:refused` is untranslatable by definition —
+it *is* whatever the message said — so every app needs the fallback, and having
+it means an app can translate the four kinds it cares about and leave the rest.
+
+Arrays stay arrays: `details[:members]` is `["CAT", "DOG"]`, so join it where you
+know the language — `members: e.details[:members].to_sentence`.
+
+`details[:type]` is the **GraphQL** name for the type — `Int`, `Money` — so a
+sentence translated from it still says "Int" in the middle of the French. Name
+the scalars your forms use, and translate the name before it is interpolated:
+`render_input_error` splats `details`, so a `type:` passed after the splat wins.
+
+```yaml
+fr:
+  types:
+    Int: "numérique"
+    String: "textuelle"
+```
+
+```ruby
+type = I18n.t("types.#{error.details[:type]}", default: error.details[:type])
+```
+
+## No locale file ships
+
+graph_weaver ships the **keys and the data, and no `en.yml`**. Three
+reasons, in order:
+
+1. The strings are app-voice, not library-voice. "Species must be one of: cat,
+   dog" belongs to whoever owns the form.
+2. A shipped default applies by merely adding the gem — behavior that follows
+   from the Gemfile rather than from the code in front of you, which is the one
+   thing this library refuses to do everywhere else.
+3. Owning a user-visible English string means every reword is a breaking change
+   for apps that translated around it.
+
+Paste this into your own `config/locales/en.yml` instead:
+
+```yaml
+en:
+  graph_weaver:
+    input:
+      type_mismatch: "%{field} must be a %{type}."
+      unparseable: "%{field} isn't a valid %{type}."
+      not_a_member: "%{field} must be one of: %{members}."
+      missing: "%{field} is required."
+      unknown: "%{field} isn't a field we recognize."
+      out_of_range: "%{field} is out of range."
+      invalid_format: "%{field} isn't in the right format."
+      refused: "%{field} was rejected."
+```
+
+## What the server has to do
+
+For the two kinds nothing can produce on its own, and for every column the
+table leaves blank, the server states it — under one key, `extensions.input`, with
+the `kind` taken from the table above. The shape, the graphql-ruby recipes for
+it, and what a server that sends none of it gets instead are in
+[errors](errors.md#what-your-server-can-send).
+
+Two rules matter to a translator. **A `kind` outside the table becomes
+`:refused`** rather than being passed through, because a wrong key is worse
+than no key: the app will have translated it into a confident sentence. And
+**a key outside `type`/`members`/`min`/`max`/`pattern`/`suggestion` is dropped**
+before it reaches `details`, so `I18n.t(..., **details)` can never be handed an
+interpolation your locale file has no slot for. None of the six is a name in
+`I18n::RESERVED_KEYS` either — `:pattern` rather than `:format` for that reason,
+since splatting a `:format` key into `I18n.t` raises
+`I18n::ReservedInterpolationKey` instead of translating.
+
+## Transport and server failures
+
+`kind` exists for input errors and nothing else. The failures beside them — the
+endpoint was unreachable, the server answered 502, the server answered 200 and
+complained — name no field and carry nothing to interpolate. Key those on the
+**exception class**:
+
+| what you rescued | what the user is told |
+|---|---|
+| `GraphWeaver::TransportError` | we couldn't reach the service — try again |
+| `GraphWeaver::ServerError` | the service is having trouble — try later (`#throttled?` earns its own sentence) |
+| `GraphWeaver::QueryError` whose `#input_errors` is empty | something went wrong with that request |
+
+One static translated sentence each, and log what the server said rather than
+showing it. The [class hierarchy](errors.md) is the only closed vocabulary on
+this side: a `code` is a per-server invention — Apollo sends `BAD_USER_INPUT`,
+graphql-js sends none — so a translation keyed on one degrades to English
+against the next server, and `#message` is the developer's line, which moves.
+
+## Where translation stops
+
+graph_weaver's own refusals are for developers and stay English, with no keys:
+`QueryValidationError` and the codegen errors (a rake task's output), the schema-drift
+hint, `ConfigurationError`, `Testing::*`. Same for `InputError#message` — it is
+the line in the log and the stack trace; the translated line is the one your app
+builds from `kind` and `details`. And a message the *server* wrote arrives in
+whatever language the server chose, passed through untouched.

data/docs/logging.md

@@ -14,8 +14,8 @@ What logs at which level — pick the level, get the story:
 | Level | What you see |
 |-------|--------------|
 | `debug` | the wire: query + variables per call (long queries truncated), response status/bytes, request timing, connection open/drop, dynamically parsed modules |
-| `info` | schema introspection (with timing) and cache hits/misses, the transport a client built, generated files written and any unregistered scalars, query modules loaded, a retry's wait and attempt number — and in development, what's being watched and what a save regenerated |
-| `warn` | every GraphWeaver error raised — `TransportError`, `ServerError`, `QueryError`, `ValidationError`, `TypeError` — registrations the schema being generated against can't match, a retry skipped because the operation was a mutation, and every fetch the test router answered with fabricated data |
+| `info` | one line per operation in Rails (see Instrumentation), schema introspection (with timing) and cache hits/misses, the transport a client built, generated files written and any unregistered scalars, query modules loaded, a retry's wait and attempt number — and in development, what's being watched and what a save regenerated |
+| `warn` | every GraphWeaver error raised — `TransportError`, `ServerError`, `QueryError`, `QueryValidationError`, `CastError` — registrations the schema being generated against can't match, a retry skipped because the operation was a mutation, and every fetch the test router answered with fabricated data |
 | `error` | development only: a `.graphql` edit that won't compile, with its file and position — the modules already loaded keep serving |
 
 Every line carries `graph_weaver` as the progname, so formatter-based
@@ -36,7 +36,9 @@ written — at any depth, including inside input objects.
 
 In Rails you configure nothing: the railtie adopts the app's own
 `config.filter_parameters`, so GraphWeaver scrubs whatever the request logs
-already scrub.
+already scrub — including Rails' own default list, which has `:email` on it, so
+an ordinary field named `email` reads `[FILTERED]` in `#value` and in the
+message the day you add the gem.
 
 Everywhere else, one list:
 
@@ -54,39 +56,173 @@ as-is, which is how the railtie hands over an
 
 The same list scrubs error messages, which reach the log at `warn` rather
 than `debug`: a variable, input field, or entity key whose name is filtered
-is rejected with `[FILTERED]` in place of the value — everything else keeps
-quoting it, since `expected an Int, got "lots"` is the whole diagnosis.
+is rejected with `[FILTERED]` in place of the value, and a value a message
+*quotes* is scrubbed at every depth, so a filtered key one level in reads
+`got {"token" => "[FILTERED]"}`. Everything else keeps quoting the value,
+since `expected an Int, got "lots"` is the whole diagnosis.
+
+**It reaches what GraphWeaver composes, and nothing else.** That is
+`InputError#message` and `#value` on both halves — a server's sentence
+included, once it has been read back into an `InputError` — plus the variables
+line at debug. A `GraphQLError#message` is the server's or a resolver's own
+words and is **passed through untouched**, in `response.errors`, in
+`QueryError`'s summary, and in the `warn` line that summary writes. A server
+that quotes a rejected password in its message has to be fixed at the server.
 
 ## Instrumentation
 
 A logger tells a human what happened; an APM needs to time it and count
 it. `GraphWeaver.instrumenter` is one callable wrapping every request —
-over the wire *and* in-process, one seam for both paths. It's a no-op
-until you set one, and `ActiveSupport::Notifications` is a two-line
-adapter:
+over the wire *and* in-process, one seam for both paths. It's a no-op until you
+set one — and **in Rails you set nothing**: the railtie installs the adapter
+below and attaches `GraphWeaver::LogSubscriber` on top of it, so the snippet is
+what the framework already did. Everywhere else, it is the line to write:
 
 ```ruby
 GraphWeaver.instrumenter = lambda do |event, payload, &block|
   ActiveSupport::Notifications.instrument(event, payload, &block)
 end
+```
+
+An instrumenter you set yourself is never replaced — including
+`GraphWeaver.instrumenter = nil` in an initializer, which opts out the
+way `GraphWeaver.logger = nil` does. Yours **must** call the block and
+return its value; a failure propagates through it, so the hook sees the
+exception and can record it.
 
+The one event is `GraphWeaver::EXECUTE_EVENT` (`"execute.graph_weaver"`)
+— one request, start to parsed response, whichever client slot served
+it, so a single subscriber covers both sides of the seam:
+
+```ruby
 ActiveSupport::Notifications.subscribe(GraphWeaver::EXECUTE_EVENT) do |*, payload|
-  StatsD.timing("graphql.#{payload[:operation] || "anonymous"}", ...)
+  StatsD.timing("graphql.#{payload[:operation] || "anonymous"}", payload[:duration_ms],
+    tags: ["status:#{payload[:status]}", "code:#{payload[:code]}"])
+end
+```
+
+**A subscriber that raises takes the request down with it** — the response was
+computed and is then thrown away. That is `ActiveSupport::Notifications`' own
+semantics, the same on `sql.active_record`, so rescue inside the block. A
+`GraphWeaver::LogSubscriber` subclass is the exception: it already rescues, and
+reports the failure instead of raising it.
+
+### The payload
+
+| Key | When | |
+|-----|------|--|
+| `:operation` | always | the operation name sent with the request, nil for an anonymous document — what a trace keys on (a generated module always has one) |
+| `:client` | always | the class that ran it: `GraphWeaver::Transport::HTTP`, `GraphWeaver::InProcess`, your own |
+| `:status` | always | `:ok`, `:errors` (a response carrying GraphQL errors), or `:failed` (it raised) |
+| `:duration_ms` | always | start to parsed response, for **this attempt** — under a [`Retry`](transports.md#retries) the backoff sleep between attempts is in none of them, so no event reports the wall clock the caller waited |
+| `:url` | over the wire | the endpoint; nil in-process |
+| `:http_status` | over the wire | what the server answered with, success or not; nil in-process |
+| `:schema` | in-process | the schema class's name, as a String, so a payload logs as it stands |
+| `:code` | on `:errors`, and on a `ServerError` | the machine-readable reason — the first `code` *any* of the errors carries, not the first error's, or a `ServerError`'s status. A code that exists beats the absence of one at position 0, which is what an alert groups by. Present and `nil` when the errors carry none |
+| `:error` | on `:failed` | the exception's class name |
+| `:retries` | under a `Retry` | how many retries this attempt follows. Each attempt is its own event, so one retried call is three events reading 0, 1, 2 — present at 0 rather than absent, so its absence means nothing was retrying |
+| `:graph` | always | the [graph](getting_started.md#more-than-one-schema) the generated module was declared under, as a Symbol — `nil` for a module that names none, and for a client called directly. Never inferred from the client: a wrong graph on a request is worse than no graph |
+
+Every key is filled in before your callable's block returns, so a
+subscriber reads a complete payload. `ActiveSupport::Notifications` adds
+`:exception` and `:exception_object` of its own when the block raises.
+
+**`:graph` labels one request.** A generated module's `execute` labels the
+request *it* makes — each of them, when a federated operation fans out to
+several subgraphs. It never labels what a *server* does while answering
+one: an in-process resolver that calls out produces an event of its own,
+carrying its own graph or `nil`. So `:graph` always reads "this request
+went to that graph", which is the only claim a dashboard can group by.
+
+One edge: the label is fiber-local, so a dispatch that crosses a `Fiber` —
+graphql-ruby's `Dataloader` does — arrives with `:graph` unset. No label
+rather than a wrong one, which is the same trade as the paragraph above.
+
+**Never the query text or the variables.** `filter_parameters` scrubs
+what reaches the log, which GraphWeaver writes itself; the payload fans
+out to subscribers that know none of those rules, so here the rule isn't
+"scrub it", it's that it was never there. Queries and variables stay at
+debug on the logger, where the level gates them.
+
+`:url` is the one thing on the payload that *is* scrubbed, because a url can
+itself be a credential: its userinfo, and any query parameter
+`filter_parameters` filters, are folded to `[FILTERED]` — the same list, the
+same spelling — before the payload, a log line or a `TransportError` says it.
+
+### One line per operation
+
+In Rails the railtie also attaches `GraphWeaver::LogSubscriber`, which
+turns each event into one line — the shape ActiveRecord uses for a query:
+
+```
+GraphWeaver PersonQuery (12.3ms) ok
+GraphWeaver PersonQuery (8.1ms) errors [THROTTLED]
+GraphWeaver PersonQuery (31.2ms) failed GraphWeaver::TransportError
+GraphWeaver PersonQuery (5.0ms) ok (retry 2)
+GraphWeaver billing/InvoicesQuery (12.3ms) ok
+```
+
+The operation is prefixed by its graph when the request carried one, so an
+app with several graphs sorts its own log and an app with one never sees
+the prefix.
+
+**One rule: the summary is info, the wire is debug.** This is the only
+GraphWeaver line at info, so a production log gets one per operation and
+nothing that can carry PII; turning the logger up to debug adds the
+query, the variables and the response *beneath* it rather than repeating
+it. It writes through `GraphWeaver.logger`, so `GraphWeaver.logger = nil`
+silences this along with everything else.
+
+Outside Rails there's no railtie to attach it, so the same line is an
+instrumenter of your own — read the payload in an `ensure`, since it is only
+complete once the block has returned:
+
+```ruby
+log = Logger.new("log/graphql.log")
+
+GraphWeaver.instrumenter = lambda do |_event, payload, &block|
+  block.call
+ensure
+  log.info { "#{payload[:operation] || "anonymous"} (#{payload[:duration_ms]}ms) #{payload[:status]}" }
+end
+```
+
+```
+I, [2026-09-12T18:40:33.032236 #97490]  INFO -- : PersonQuery (19.57ms) ok
+I, [2026-09-12T18:40:33.037186 #97490]  INFO -- : DraftsQuery (4.67ms) errors
+```
+
+### OpenTelemetry
+
+```ruby
+tracer = OpenTelemetry.tracer_provider.tracer("graph_weaver")
+
+GraphWeaver.instrumenter = lambda do |_event, payload, &block|
+  tracer.in_span("graphql #{payload[:operation] || "query"}") do |span|
+    block.call
+  ensure
+    span.add_attributes(payload.compact.transform_keys { "graphql.#{_1}" }.transform_values(&:to_s))
+  end
+end
+```
+
+`ensure` rather than after the call: the payload is only complete once
+the block has returned, and a failed span needs the attributes most.
+`in_span` records the exception and sets the span status itself.
+
+### Datadog
+
+```ruby
+GraphWeaver.instrumenter = lambda do |event, payload, &block|
+  Datadog::Tracing.trace(event, resource: payload[:operation], service: "graphql") do |span|
+    block.call
+  ensure
+    payload.compact.each { |key, value| span.set_tag("graphql.#{key}", value.to_s) }
+  end
 end
 ```
 
-The one event is `GraphWeaver::EXECUTE_EVENT`
-(`"graph_weaver.execute"`), a single request from start to parsed
-response. Its payload carries:
-
-| Key | |
-|-----|--|
-| `:url` | the endpoint — nil in-process |
-| `:schema` | the schema class's name, in-process only — a String, so a payload logs as it stands |
-| `:operation` | the operation name sent with the request (a generated module always has one) — what a trace keys on |
-| `:status` | the HTTP status, added once the response lands |
-
-Your callable **must** call the block and return its value. A failure
-propagates through it, so the hook sees the exception and can record it.
-The query text and the variables are deliberately absent: they carry
-PII, and belong at debug on the logger where the level gates them.
+Datadog's Net::HTTP and Faraday contribs already trace the transport
+layer, so with them on you have a span for the POST. This adds the span
+*above* it, named for the operation — the one that means anything, since
+every GraphQL call is a POST to the same url.

data/docs/real_world.md

@@ -19,10 +19,10 @@ require "graph_weaver"
 # in a header, so a stale dump says where it came from.
 github = GraphWeaver.new("https://api.github.com/graphql", auth: `gh auth token`.strip, cache: true)
 
-# map GitHub's DateTime scalar onto Time (cast inferred from Time.parse).
-# Registrations are global and codegen-time, so this line types your
-# console and your checked-in code identically (docs/scalars.md).
-GraphWeaver.register_scalar("DateTime", Time, serialize: :iso8601, requires: "time")
+# GitHub's DateTime needs no registration — it is one of the names the
+# registry knows (docs/scalars.md). A scalar of your own would go here;
+# registrations are global and codegen-time, so one line types your
+# console and your checked-in code identically.
 
 RepoQuery = github.parse(<<~GRAPHQL)
   query($owner: String!, $name: String!) {
@@ -48,6 +48,34 @@ is the schema `generate!` wants:
 GraphWeaver.generate!(schema: github)   # no dump on disk needed
 ```
 
+Keeping a second server's modules checked in alongside your own is a
+[graph](getting_started.md#more-than-one-schema) — its own queries, output and
+namespace, declared once and generated by the same
+`rake graph_weaver:generate` as everything else.
+
+## Browsing the schema
+
+`client.schema` is an ordinary graphql-ruby `Schema` class, so "what can I even
+ask for" is answered in the console with nothing else installed:
+
+```ruby
+schema = github.schema
+
+schema.query.fields.keys              # => ["repository", "search", ...]
+field = schema.query.fields["repository"]
+field.arguments.keys                  # => ["owner", "name", ...]
+field.type.to_type_signature          # => "Repository"
+
+repo = field.type.unwrap              # past the ! and [] wrappers
+repo.graphql_name                     # => "Repository"
+repo.fields.keys.sort                 # => ["createdAt", "description", ...]
+```
+
+`graphql_name` is the one to reach for, not `name`: a schema built from
+introspection or SDL has no Ruby class behind its types, so `.name` is `nil`
+there — and where the schema *is* a class you wrote, `.name` gives you the Ruby
+constant, never the GraphQL name.
+
 The introspection step (seconds on a big API) happens lazily on first
 `schema`/`parse` and caches per `cache:`/`ttl:`; for finer control the
 pieces are all public