graph_weaver 0.5.1 → 0.6.1

data/docs/upgrading.md

@@ -1,4 +1,174 @@
-# Upgrading to 0.5.0
+# Upgrading
+
+## Regenerate on every upgrade
+
+**Any release can change what codegen emits.** Patch releases included — most of
+them are fixes to a generated type, and a fix to a type is a change to the bytes.
+0.5.1 was a patch and moved three of them.
+
+So `rake graph_weaver:generate` is part of upgrading the gem, every time, and
+`rake graph_weaver:verify` is the detector: it fails when the checked-in Ruby
+isn't what this version would write. Nothing beyond that is promised — there is
+no "generated output is stable within a minor" rule to lean on. What each release
+changed, and whether it needs a regenerate, is in the changelog.
+
+A generated file's header names the release that wrote it, so the first `verify`
+after an upgrade reports the tree as stale whether or not codegen actually
+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.5.1
+
+Much smaller than 0.5.0, and mostly mechanical. Three commands find most of it:
+
+```sh
+rake graph_weaver:generate   # 1. what codegen emits moved in several places
+srb tc                       # 2. kwargs that got narrower are call-site errors
+bundle exec rspec            # 3. every deleted knob raises where it's still set
+```
+
+The rest of this section is what those three don't catch.
+
+### Loose input coerces, so `coerce:` and `auto_coerce` are gone
+
+`execute(first: params[:first])` converts the String to an `Integer` — for every
+variable and every input-object field, with nothing to switch on. The old way of
+buying that was `GraphWeaver.auto_coerce` or `register_scalar(…, coerce: true)`,
+and both paid for it by **widening the emitted kwarg**, which switched off the
+static check at every call site. Delete them:
+
+```ruby
+GraphWeaver.auto_coerce = true                             # gone
+GraphWeaver.register_scalar("Money", Money, coerce: true)  # drop the coerce:
+```
+
+Behavior is unchanged; the kwarg is not. It is now typed exactly as the schema
+types it, so a call site passing a **literal** of the wrong type is a new
+`srb tc` error — which is the point, since a literal is one you can just spell
+right:
+
+```ruby
+StargazersQuery.execute(first: "10")            # srb tc error now
+StargazersQuery.execute(first: params[:first])  # fine, and "10" becomes 10
+```
+
+`cast:` is what a loose value converts through, so a custom scalar needs nothing
+beyond the registration it already has. Bad input raises
+`GraphWeaver::InputError` naming the variable, the operation and the value.
+
+Two conversions got **stricter** at the same time, and either can bite an app
+that was passing. A numeric string is now read as a wire format rather than as
+Ruby source, so `"010"` is ten rather than eight and `"0x1f"` and `"1_0"` are
+refused. And a `Boolean` refuses a String outright — every rule for `"0"` and
+`"off"` is somebody's convention, so convert at the call site.
+
+### `nil` sends `null`
+
+A variable passed `nil` now sends an explicit `null`; one left out is still left
+out. That's what lets a mutation clear a field — and it changes what a kwarg fed
+a possibly-missing value means:
+
+```ruby
+UpdateProfile.execute!(bio: params[:bio])   # a missing param used to omit; now it clears the bio
+```
+
+**Grep for kwargs fed straight from `params` or an optional attribute**, and
+pass the keyword only when you mean it:
+
+```ruby
+UpdateProfile.execute!(**(params[:bio] ? { bio: params[:bio] } : {}))
+```
+
+Non-null variables are unaffected: they can't carry `null`, so `nil` there still
+omits and the schema default applies. Input objects get the distinction only
+where a Hash can express it — `coerce({nickname: nil})` sends null, `coerce({})`
+omits, and a struct built with `.new` can't tell the two apart, so `nil` there
+still means omit.
+
+### Renames
+
+| before | after |
+|---|---|
+| `Retry.new(tries: n)`, `retries: { tries: n }` | `retries: n - 1` — one word everywhere, counting the attempts *after* the first, so `retries: 0` is one attempt and `GraphWeaver.new(url, retries: 3)` is four |
+| `GraphWeaver.new(url, retries: { retries: 5, retry_codes: […] })` | `GraphWeaver.new(url, retries: 5, retry_codes: […])` — the other retry options sit beside the count; the Hash form read as a key nested in itself |
+| `Retry.new(t, on: […])` | `Retry.new(t, retry_on: […])` |
+| `Retry.new(t, base: 0.5, max: 30)` | `Retry.new(t, base_delay: 0.5, max_delay: 30)` — beside a count, `max: 30` read as a second, larger attempt count |
+| `Codegen.generate(module_name:)` | `name:` — the spelling `GraphWeaver.parse` already used; `module_name:` now raises, naming its replacement |
+| `Testing.config.null_chance = 0.3` | `graphql_fake(null_chance: 0.3)`, on the example that wants it |
+| `Testing.config.mode = :literal` | `graphql_fake(values: :literal)`, likewise |
+| `Testing::MODES` | `Testing::VALUE_STYLES` |
+| `SchemaLoader.stale?(path)` | `SchemaLoader.diff(path).empty?` — and `diff` also names what moved |
+
+The two `Testing.config` deletions are the ones worth a sentence. A suite-wide
+`null_chance` answers a per-example question, so it nils an unrelated field one
+run in ten, on a seed the failure doesn't name; move it onto the examples that
+are *about* an empty state. (`config.default_mode` and the `graphql: :fake` tag
+are untouched — the per-fake `mode:` became `values:` so the two can't be
+confused for each other.) Every retry misspelling raises rather than being
+ignored: the Hash form names its flat replacement, and a retry option passed
+without `retries:` says so.
+
+### The internals moved behind `Internal`
+
+The public surface is now what the docs name, what generated code calls, and the
+`execute` slot; everything else sits under `GraphWeaver::Internal` or went
+`private`, and a spec diffs the two so the next accidental promotion fails CI.
+Nothing documented moved — skip this section unless `srb tc` or a
+`NoMethodError` says otherwise.
+
+What a suite might plausibly have reached for: the federation query planner and
+its IR (`Internal::Planner`), the fake-value engine (`Internal::Values`), the
+selection walk (`Internal::Selection` — so `FakeClient` no longer answers
+`each_field` or `gather`), the cassette matching rules (`Internal::RequestKey`),
+subgraph detection (was `Testing::Subgraphs`), `GraphWeaver.log` /
+`.instrument` / `.filter_variables` (`Internal::Log` — `logger=`,
+`instrumenter=` and `filter_parameters=` are unchanged), and
+`Transport.operation_name` / `.mutation?` / `.log_tag`, which left the class you
+subclass for `Internal::Wire`.
+
+Two smaller edges. `SchemaDiff::Change`, `Cassette::Check`, `Coverage::Result`
+and `InputStruct::Field` are `Data` now rather than `Struct`, so they hand out
+no writers — read one, build a new one to change a field. And generated modules
+keep their own plumbing to themselves: `DEFAULT_CLIENT`, `FIELDS` and `ONE_OF`
+are emitted `private_constant`, so **regenerate**.
+
+### Behavior that changed under you
+
+- **A mutation is no longer retried.** A timeout doesn't say whether the server
+  applied it, and a second `charge` is worse than a failed one. Pass
+  `retry_mutations: true` for an API whose mutations are idempotent.
+- **A registration this schema can't match warns instead of failing
+  generation.** One registry serves a whole federated graph, so a name the
+  schema in hand doesn't declare may belong to the subgraph next door — see
+  [federation](federation.md#generating-for-a-federated-graph). Your typo is now
+  in the list `rake graph_weaver:generate` prints after the files, so read it.
+- **`verify_generated!` fails when it finds no query documents.** A mistyped
+  `queries_paths` used to leave a CI gate green forever.
+- **The local router refuses a `@fromContext` argument** rather than fetching
+  the field with it unset. Federation 2.8's `@context` machinery was on the
+  routing table's known list, so the argument was read and dropped. Per query,
+  like `@interfaceObject`: a subtree one subgraph answers whole still runs.
+- **A `#trace` assertion may see one entry fewer.** Two `@requires` field sets
+  crossing into the same subgraph on the same `@key` now ride one entity fetch,
+  the way Apollo's do.
+- **Fabricating a custom scalar registered as a class of your own needs a pin
+  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.
+- **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 (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`.
+
+## Upgrading to 0.5.0
 
 0.5.0 is one large breaking release. Almost all of it is caught mechanically,
 in this order:
@@ -6,7 +176,7 @@ in this order:
 ```sh
 # 1. rename the path settings first — generate won't load without them
 #    (queries_path -> queries_paths, generated_path -> generated_paths,
-#     fragments_path -> fragments_paths; see "One plurality rule" below)
+#     fragments_path -> fragments_paths; see "Path settings are lists" below)
 
 bundle exec tapioca gem graph_weaver   # 2. regenerate the RBI
 rake graph_weaver:generate             # 3. the emitted call shape changed
@@ -23,7 +193,7 @@ Regenerate the RBI and what remains is only your own call sites.
 Generated code is `# typed: strict`, so step 4 finds those for you. The rest of
 this page is what a typechecker can't see.
 
-## `execute` means one thing now
+### `execute` means one thing now
 
 Every client answers the same call — `execute(query, variables:, operation_name:)`,
 returning the raw response hash. `Client` used to spell something else under
@@ -55,7 +225,7 @@ PersonQuery.execute(client: some_client, id: "1")  # after
 
 `GraphWeaver.resolve_transport` is gone; nothing needs unwrapping any more.
 
-## Path settings are lists
+### Path settings are lists
 
 `queries_paths`, `generated_paths`, `fragments_paths` — every entry is read.
 Assigning a String still works, so the change is the name:
@@ -67,9 +237,10 @@ GraphWeaver.queries_paths = "app/graphql/queries"   # after
 
 `schema_path` stays singular: one run reads one schema.
 
-## One reset
+### One reset
 
-`GraphWeaver.reset_registrations!` is the clean slate between tests. The four
+`GraphWeaver.reset_registrations!` is the clean slate between tests, or between
+generations for different schemas. The four
 narrow ones moved to where they live:
 
 ```ruby
@@ -78,12 +249,39 @@ GraphWeaver::Codegen.reset_scalars!   # after   (also reset_enums!, clear_scalar
                                       #          reset_type_helpers!)
 ```
 
-## Smaller renames
+### Generated names come from the response key, not the type
+
+Nested structs used to be named for the GraphQL *type* they were cast from;
+they are now named for the **response key that selects them**, camelized, and
+the constant path reads like the query. The typechecker finds the call sites in
+a `# typed: true` file (an unresolved constant is an `srb tc` error); in a
+`# typed: false` file it is `uninitialized constant` at runtime, so grep for
+`::Result::` there.
+
+| selection | before (type) | after (key) |
+|---|---|---|
+| `person { pets { name } }` | `PersonQuery::Result::Person::Pet` | `PersonQuery::Result::Person::Pets` |
+| `payrollRisk { score }` | `…::Result::RiskAssessment` | `…::Result::PayrollRisk` |
+| `_entities(…) { ... on Product { … } }` | `…::Result::Product` | `…::Result::Entities::Product` |
+
+The key is used verbatim — no pluralization, so a list field `pets` is `Pets`.
+To pick the name yourself, alias the field: `pet: pets { name }` generates
+`Pet`. Union and interface members keep their type-condition names, nested in
+the container the field names. The payoff is that adding, removing or
+reordering an unrelated selection can never rename a struct you reference.
+
+**Enums moved out of the result tree.** Every schema enum a query touches is one
+Ruby type in the shared module, `GraphQLTypes::Species`, so a value read from
+one query hands straight into another's variable. A query module aliases the
+enums its *variables* use (`AddPetMutation::Species` still works); an enum
+reached only through a result is no longer nested under the struct that
+carries it — `SearchQuery::Result::Search::Species` is `GraphQLTypes::Species`.
+
+### Smaller renames
 
 | before | after |
 |---|---|
 | `Testing.config.auto_fake = true` | `Testing.config.default_mode = :fake` |
-| `register_scalar(…, coerce: :to_s)` | `coerce: true`, or a `cast:`/`serialize:` pair |
 | a mutation's `…Query` module | `…Mutation` |
 | `graphql: :none` (rspec tag) | `graphql: false` |
 
@@ -103,7 +301,7 @@ graphql_in_process(MySchema)                     # in the example
 GraphWeaver::Testing.config.schema = MySchema    # or once, for the whole suite
 ```
 
-## Registering from Rails
+### Registering from Rails
 
 A registration naming one of your own constants belongs in a `to_prepare` block
 — the same place the in-process client goes, and for the same reason:
@@ -117,9 +315,10 @@ end
 ```
 
 Generation depends on `:environment`, which runs `to_prepare` too, so the
-registration is in place before it emits.
+registration is in place before it emits — and at boot the generated files
+load from a `to_prepare` block of their own, after yours.
 
-## If you use the federation router
+### If you use the federation router
 
 Detection only sees *loaded* schema classes, and Rails does not eager load for
 rake or in the default test environment. Both are one line:

data/lib/generators/graph_weaver/install_generator.rb

@@ -56,8 +56,11 @@ module GraphWeaver
         create_file "config/initializers/graph_weaver.rb", initializer
       end
 
+      # fragments too: the editor config below globs it, and a shared fragment
+      # then has an obvious home rather than being invented later
       def create_layout
         create_file File.join(GraphWeaver.queries_paths.first, ".keep"), ""
+        create_file File.join(GraphWeaver.fragments_paths.first, ".keep"), ""
         create_file File.join(GraphWeaver.generated_paths.first, ".keep"), ""
       end
 
@@ -85,10 +88,18 @@ module GraphWeaver
       rescue StandardError => e
         # the files above are the valuable part — don't lose them to a bad
         # token or an unreachable host
+        @schema_failed = true
         say_status :failed, "#{e.message} — retry with `#{refresh_command}`", :red
       end
 
       def next_steps
+        # generation reads the dump, so without one the step below can't run —
+        # say that next to it rather than leaving the red line above to be
+        # scrolled past. A re-run that already has a dump is not blocked.
+        if @schema_failed && !GraphWeaver::SchemaLoader.locate_path
+          say "\nThere's no schema dump yet, so `rake graph_weaver:generate` has nothing to read."
+        end
+
         say <<~TEXT
 
           Write a query in #{GraphWeaver.queries_paths.first}, then:
@@ -175,8 +186,12 @@ module GraphWeaver
 
       def auth_var = options[:auth] || GraphWeaver::SchemaLoader::DEFAULT_AUTH_ENV
 
+      # The command just typed, retyped. One rule for every source form, and
+      # the only one that always works: the files already written come back
+      # "identical", and --auth rides along — where schema:refresh has no flag
+      # for it, and with no dump written has no url to read either.
       def refresh_command
-        (form == :url) ? "rake graph_weaver:schema:refresh" : "rails g graph_weaver:install #{source}"
+        "rails g graph_weaver:install #{source}#{" --auth #{options[:auth]}" if options[:auth]}"
       end
 
       def initializer

data/lib/graph_weaver/client.rb

@@ -40,17 +40,28 @@ class GraphWeaver::Client
   # nothing to hand a context to — so the two can't word it differently
   CONTEXT_IN_PROCESS = "context: applies to a schema class executing in-process"
 
-  def initialize(source, auth: nil, headers: {}, retries: false, transport: nil, cache: nil, ttl: nil,
-    open_timeout: nil, read_timeout: nil, context: nil, &middleware)
+  # the whole rule, said wherever a retry option is refused
+  RETRY_RULE = "retries: is how many attempts follow the first; the other retry options sit beside it"
+  private_constant :CONTEXT_IN_PROCESS, :RETRY_RULE
+
+  def initialize(source, auth: nil, headers: {}, transport: nil, cache: nil, ttl: nil,
+    open_timeout: nil, read_timeout: nil, context: nil,
+    retries: false, backoff: nil, base_delay: nil, max_delay: nil, jitter: nil, retry_on: nil,
+    retry_if: nil, retry_codes: nil, retry_mutations: nil, sleeper: nil, &middleware)
     check_source!(source)
 
+    # Retry's options, spelled the same and passed straight through; nil
+    # is "not given", so their defaults stay in Retry alone
+    retry_options = { backoff:, base_delay:, max_delay:, jitter:, retry_on:, retry_if:,
+                      retry_codes:, retry_mutations:, sleeper: }.compact
+
     if source.is_a?(String) && source.match?(URL)
       raise ArgumentError, CONTEXT_IN_PROCESS if context
 
       built = build_transport(source, auth:, headers:, kind: transport, open_timeout:, read_timeout:, &middleware)
-      @transport = wrap_retries(built, retries)
+      @transport = wrap_retries(built, retries, retry_options)
     else
-      if auth || middleware || retries || open_timeout || read_timeout
+      if auth || middleware || retries || open_timeout || read_timeout || !retry_options.empty?
         raise ArgumentError, "auth:/retries:/timeouts/middleware apply to a url — got a schema source"
       end
       if transport.is_a?(Symbol)
@@ -80,6 +91,7 @@ class GraphWeaver::Client
 
     @cache = cache
     @ttl = ttl
+    @schema_lock = Mutex.new
   end
 
   # The transport queries run through: a url-built transport, an
@@ -89,15 +101,21 @@ class GraphWeaver::Client
   attr_reader :transport
 
   # transport, when this client must be able to execute
-  def transport!
+  private def transport!
     transport or raise GraphWeaver::Error,
       "this client has no transport (built from a schema dump) — pass a url or transport:"
   end
 
   # The schema, introspecting through the transport on first use (cached
   # per the client's cache:/ttl:) unless one was given up front.
+  #
+  # Locked because a cold Puma process serves its first requests
+  # concurrently: a bare ||= there is one full introspection round trip per
+  # in-flight thread, each of them also writing the cache file.
   def schema
-    @schema ||= GraphWeaver::SchemaLoader.introspect(transport!, cache: @cache, ttl: @ttl)
+    @schema_lock.synchronize do
+      @schema ||= GraphWeaver::SchemaLoader.introspect(transport!, cache: @cache, ttl: @ttl)
+    end
   end
 
   # The client contract, same as every transport: a query and its
@@ -150,6 +168,11 @@ class GraphWeaver::Client
   def build_transport(url, auth:, headers:, kind:, open_timeout: nil, read_timeout: nil, &middleware)
     headers = headers.dup
     if auth
+      unless auth.is_a?(String)
+        raise ArgumentError, "auth: takes a token string, got #{auth.class} — other headers go in " \
+          "headers:, and a token that rotates goes in the Faraday middleware block"
+      end
+
       headers["Authorization"] ||= auth.include?(" ") ? auth : "Bearer #{auth}"
     end
 
@@ -163,7 +186,7 @@ class GraphWeaver::Client
         GraphWeaver::Transport::HTTP.new(url, headers:, **timeouts)
       end
 
-    GraphWeaver.log(:info) { "transport: #{transport.class} -> #{url}" }
+    GraphWeaver::Internal::Log.log(:info) { "transport: #{transport.class} -> #{url}" }
     transport
   end
 
@@ -198,13 +221,23 @@ class GraphWeaver::Client
     GraphWeaver::Transport::Faraday.new(url, headers:, **timeouts, &middleware)
   end
 
-  # retries: is off by default — true for Retry defaults, or a
-  # Hash of its options
-  def wrap_retries(transport, retries)
+  # retries: is off by default — a count, or true for Retry's default
+  # count. Without it nothing wraps the transport, so a retry option on
+  # its own would quietly do nothing.
+  def wrap_retries(transport, retries, options)
     case retries
-    when true then GraphWeaver::Retry.new(transport)
-    when false, nil then transport
-    else GraphWeaver::Retry.new(transport, **retries)
+    when Integer then GraphWeaver::Retry.new(transport, retries:, **options)
+    when true then GraphWeaver::Retry.new(transport, **options)
+    when false, nil
+      raise ArgumentError, "#{options.keys.first}: needs retries: — #{RETRY_RULE}" if options.any?
+
+      transport
+    when Hash
+      # it used to take a Hash of Retry options, which read as a key nested in itself
+      flat = retries.map { |key, value| "#{key}: #{value.inspect}" }.join(", ")
+      raise ArgumentError, "retries: no longer takes a Hash — pass GraphWeaver.new(url, #{flat})"
+    else
+      raise ArgumentError, "#{RETRY_RULE} — got #{retries.inspect}"
     end
   end
 end

data/lib/graph_weaver/codegen/aliases.rb

@@ -51,9 +51,9 @@ class GraphWeaver::Codegen
     # since a module and the type it queries can share a name (module Query
     # on type Query would otherwise stutter).
     def qualify(node, message)
-      return message if @module_name.nil? || @module_name == node.graphql_type
+      return message if @name.nil? || @name == node.graphql_type
 
-      "#{@module_name}: #{message}"
+      "#{@name}: #{message}"
     end
 
     # An alias emits a plain instance method, so it is held to the same bar
@@ -86,6 +86,7 @@ class GraphWeaver::Codegen
     # ever satisfy it, so it's a typo (or a wire-cased name), not a path that
     # doesn't fit this query. optional: skips the latter, never this.
     UnknownSegment = Class.new(GraphWeaver::Error)
+    private_constant :ALIAS_RESERVED, :LIST_SELECTORS, :UnknownSegment
 
     # Walk a dotted path through this struct's selected shape, building the
     # delegator expression (`meta&.tag`, `_entities.first&.name`) and its return
@@ -137,7 +138,7 @@ class GraphWeaver::Codegen
           unless field
             check_segment_exists!(node, name, obj, seg)
             props = obj.fields.map(&:prop)
-            suggestion = GraphWeaver.did_you_mean(props, seg)
+            suggestion = GraphWeaver::Internal::Util.did_you_mean(props, seg)
             hint = suggestion ? " — did you mean '#{suggestion}'?" : " (have: #{props.join(", ")})"
             raise GraphWeaver::Error,
               "alias #{name.inspect} on #{node.graphql_type}: '#{seg}' is not a selected field#{hint}"
@@ -169,7 +170,7 @@ class GraphWeaver::Codegen
       hint = if prop != seg && known.include?(prop)
         # paths are the Ruby prop chain, not the GraphQL one — the classic miss
         " — GraphQL fields generate snake_case props; use '#{prop}'"
-      elsif (suggestion = GraphWeaver.did_you_mean(known, prop))
+      elsif (suggestion = GraphWeaver::Internal::Util.did_you_mean(known, prop))
         " — did you mean '#{suggestion}'?"
       else
         " (has: #{known.sort.join(", ")})"