graphql-stitching 1.7.0 → 1.7.2

data/docs/serving_a_supergraph.md

@@ -0,0 +1,152 @@
+## Serving a supergraph
+
+Serving a stitched schema should be optimized by environment. In `production` we favor speed and stability over flexibility, while in `development` we favor the reverse. Among the simplest ways to deploy a stitched schema is to compose it locally, write the composed schema as a `.graphql` file in your repo, and then load the pre-composed schema into a stitching client at runtime. This assures that composition always happens before deployment where failures can be detected.
+
+### Exporting a production schema
+
+1. Make a helper class for building your supergraph and exporting it as an SDL string:
+
+```ruby
+class SupergraphHelper
+  def self.export
+    client = GraphQL::Stitching::Client.new({
+      remote: {
+        schema: GraphQL::Schema.from_definition(File.read("db/schema/remote.graphql"))
+      },
+      local: {
+        schema: MyLocalSchema
+      }
+    })
+
+    client.supergraph.to_definition
+  end
+end
+```
+
+2. Setup a `rake` task for writing the export to a repo file:
+
+```ruby
+task :compose_supergraph do
+  File.write("db/schema/supergraph.graphql", SupergraphHelper.export)
+  puts "Schema composition was successful."
+end
+
+# bundle exec rake compose-supergraph
+```
+
+3. Also as part of the export Rake task, it's advisable to run a [schema comparator](https://github.com/xuorig/graphql-schema_comparator) across the `main` version and the current compilation to catch breaking change regressions that may arise [during composition](./composing_a_supergraph.md#schema-merge-patterns):
+
+```ruby
+task :compose_supergraph do
+  # ...
+
+  supergraph_file = "db/schema/supergraph.graphql"
+  head_commit = %x(git merge-base HEAD origin/main).strip!
+  head_source = %x(git show #{head_commit}:#{supergraph_file})
+
+  old_schema = GraphQL::Schema.from_definition(head_source)
+  new_schema = GraphQL::Schema.from_definition(File.read(supergraph_file))
+  diff = GraphQL::SchemaComparator.compare(old_schema, new_schema)
+  raise "Breaking changes found:\n-#{diff.breaking_changes.join("\n-")}" if diff.breaking?
+
+  # ...
+end
+```
+
+4. As a CI safeguard, be sure to write a test that compares the supergraph export against the current repo file. This assures the latest schema is always expored before deploying:
+
+```ruby
+test "supergraph export is up to date." do
+  assert_equal SupergraphHelper.export, File.read("db/schema/supergraph.graphql")
+end
+```
+
+### Supergraph controller
+
+Then at runtime, execute requests using a client built for the environment. The `production` client should load the pre-composed export schema, while the `development` client can live reload using runtime composition. Be sure to memoize any static schemas that the development client uses to minimize reloading overhead:
+
+```ruby
+class SupergraphController < ApplicationController
+  protect_from_forgery with: :null_session, prepend: true
+
+  def execute
+    # see visibility docs...
+    visibility_profile = select_visibility_profile_for_audience(current_user)
+    
+    client.execute(
+      query: params[:query],
+      variables: params[:variables],
+      operation_name: params[:operation_name],
+      context: { visibility_profile: visibility_profile },
+    )
+  end
+
+  private
+
+  # select which client to use based on the environment...
+  def client
+    Rails.env.production? ? production_client : development_client
+  end
+
+  # production uses a pre-composed supergraph read from the repo...
+  def production_client
+    @production_client ||= begin
+      supergraph_sdl = File.read("db/schema/supergraph.graphql")
+
+      GraphQL::Stitching::Client.from_definition(supergraph_sdl, executables: {
+        remote: GraphQL::Stitching::HttpExecutable.new("https://api.remote.com/graphql"),
+        local: MyLocalSchema,
+      }).tap do |client|
+        # see performance and error handling docs...
+        client.on_cache_read { ... }
+        client.on_cache_write { ... }
+        client.on_error { ... }
+      end
+    end
+  end
+
+  # development uses a supergraph composed on the fly...
+  def development_client
+    GraphQL::Stitching::Client.new(locations: {
+      remote: {
+        schema: remote_schema,
+        executable: GraphQL::Stitching::HttpExecutable.new("https://localhost:3001/graphql"),
+      },
+      local: {
+        schema: MyLocalSchema,
+      },
+    })
+  end
+
+  # other flat schemas used in development should be 
+  # cached in memory to avoid as much runtime overhead as possible
+  def remote_schema
+    @remote_schema ||= GraphQL::Schema.from_definition(File.read("db/schema/remote.graphql"))
+  end
+end
+```
+
+### Client execution
+
+The `Client.execute` method provides a mostly drop-in replacement for [`GraphQL::Schema.execute`](https://graphql-ruby.org/queries/executing_queries):
+
+```ruby
+client.execute(
+  query: params[:query],
+  variables: params[:variables],
+  operation_name: params[:operation_name],
+  context: { visibility_profile: visibility_profile },
+)
+```
+
+It provides a subset of the standard `execute` arguments:
+
+* `query`: a query (or mutation) as a string or parsed AST.
+* `variables`: a hash of variables for the request.
+* `operation_name`: the name of the operation to execute (when multiple are provided).
+* `validate`: true if static validation should run on the supergraph schema before execution.
+* `context`: an object passed through to executable calls and client hooks.
+
+### Production reloading
+
+It is possible to "hot" reload a production supergraph (ie: update the graph without a server deployment) using a background process to poll a remote supergraph file for changes and then build it into a new client for the controller at runtime. This works fine as long as locations and their executables don't change. If locations will change, the runtime _must_ be prepared to dynamically generate appropraite location executables.

data/docs/subscriptions.md

@@ -1,4 +1,4 @@
-## Stitching subscriptions
+## Subscriptions
 
 Stitching is an interesting prospect for subscriptions because socket-based interactions can be isolated to their own schema/server with very little implementation beyond resolving entity keys. Then, entity data can be stitched onto subscription payloads from other locations.
 

data/docs/visibility.md

@@ -1,8 +1,8 @@
 # Visibility
 
-Visibility controls can hide parts of a supergraph from select audiences without compromising stitching operations. Restricted schema elements are hidden from introspection and validate as though they do not exist (which is different from traditional authorization where an element is acknowledged as restricted). Visibility is useful for managing multiple distributions of a schema for different audiences.
+Visibility controls can hide parts of a supergraph from select audiences without compromising stitching operations. Restricted schema elements are hidden from introspection and validate as though they do not exist (which is different from traditional authorization where an element is acknowledged as restricted). Visibility is useful for managing multiple distributions of a schema for different audiences, and provides a flexible analog to Apollo Federation's `@inaccessible` rule.
 
-Under the hood, this system wraps `GraphQL::Schema::Visibility` (with nil profile support) and requires at least GraphQL Ruby v2.5.3.
+Under the hood, this system wraps [GraphQL visibility](https://graphql-ruby.org/authorization/visibility) (specifically, the newer `GraphQL::Schema::Visibility` with nil profile support) and requires at least GraphQL Ruby v2.5.3.
 
 ## Example
 
@@ -41,7 +41,7 @@ type Query {
 }
 ```
 
-When composing a stitching client, the names of all possible visibility profiles that the supergraph responds to should be specified in composer options:
+When composing a stitching client, the names of all possible visibility profiles that the supergraph should respond to are specified in composer options:
 
 ```ruby
 client = GraphQL::Stitching::Client.new(
@@ -61,20 +61,20 @@ client = GraphQL::Stitching::Client.new(
 )
 ```
 
-The client can then execute requests with a `visibility_profile` parameter in context that specifies the name of any profile the supergraph was composed with, or nil:
+The client can then execute requests with a `visibility_profile` parameter in context that specifies one of these names:
 
 ```ruby
 query = %|{
   featuredProduct {
     title  # always visible
     price  # always visible
-    msrp   # only visible to internal and nil profiles
-    id     # only visible to nil profile
+    msrp   # only visible to "private" or without profile
+    id     # only visible without profile
   }
 }|
 
 result = client.execute(query, context: { 
-  visibility_profile: "public", # << or private, or nil
+  visibility_profile: "public", # << or "private"
 })
 ```
 
@@ -82,9 +82,9 @@ The `visibility_profile` parameter will select which visibility distribution to
 
 - Using `visibility_profile: "public"` will say the `msrp` field does not exist (because it is restricted to "private").
 - Using `visibility_profile: "private"` will accesses the `msrp` field as usual. 
-- Using `visibility_profile: nil` will access the entire graph without any visibility constraints.
+- Providing no profile parameter (or `visibility_profile: nil`) will access the entire graph without any visibility constraints.
 
-The full potential of visibility comes when hiding stitching implementation details, such as the `id` field (which is the stitching key for the Product type). While the `id` field is hidden from all named profiles, it remains operational for the stitching implementation.
+The full potential of visibility comes when hiding stitching implementation details, such as the `id` field (which is the stitching key for the Product type). While the `id` field is hidden from all named profiles, it remains operational for use by the stitching implementation.
 
 ## Adding visibility directives
 
@@ -105,7 +105,7 @@ end
 
 ## Merging visibilities
 
-Visibility directives merge across schemas into the narrowest constraint possible. Profile sets for an element will intersect into its supergraph constraint:
+Visibility directives merge across schemas into the narrowest constraint possible. Profiles for an element will intersect into its merged supergraph constraint:
 
 ```graphql
 # location 1
@@ -165,4 +165,14 @@ type Query {
 }
 ```
 
-In this example, hiding the `Widget` type will also hide the `Query.widget` field that returns it.
+In this example, hiding the `Widget` type will also hide the `Query.widget` field that returns it. You can review materialized visibility profiles by printing their respective schemas:
+
+```ruby
+public_schema = client.supergraph.to_definition(visibility_profile: "public")
+File.write("schemas/supergraph_public.graphql", public_schema)
+
+private_schema = client.supergraph.to_definition(visibility_profile: "private")
+File.write("schemas/supergraph_private.graphql", private_schema)
+```
+
+It's helpful to commit these outputs to your repo where you can monitor their diffs during the PR process.

data/lib/graphql/stitching/client.rb

@@ -7,6 +7,12 @@ module GraphQL
     # Client is an out-of-the-box helper that assembles all 
     # stitching components into a workflow that executes requests.
     class Client
+      class << self
+        def from_definition(schema, executables:)
+          new(supergraph: Supergraph.from_definition(schema, executables: executables))
+        end
+      end
+      
       # @return [Supergraph] composed supergraph that services incoming requests.
       attr_reader :supergraph
 

data/lib/graphql/stitching/composer.rb

@@ -26,9 +26,6 @@ module GraphQL
       # @api private
       VISIBILITY_PROFILES_MERGER = ->(values_by_location, _info) { values_by_location.values.reduce(:&) }
 
-      # @api private
-      BASIC_ROOT_FIELD_LOCATION_SELECTOR = ->(locations, _info) { locations.last }
-
       # @api private
       COMPOSITION_VALIDATORS = [
         ValidateInterfaces,
@@ -59,7 +56,8 @@ module GraphQL
         deprecation_merger: nil,
         default_value_merger: nil,
         directive_kwarg_merger: nil,
-        root_field_location_selector: nil
+        root_field_location_selector: nil,
+        root_entrypoints: nil
       )
         @query_name = query_name
         @mutation_name = mutation_name
@@ -68,7 +66,8 @@ module GraphQL
         @deprecation_merger = deprecation_merger || BASIC_VALUE_MERGER
         @default_value_merger = default_value_merger || BASIC_VALUE_MERGER
         @directive_kwarg_merger = directive_kwarg_merger || BASIC_VALUE_MERGER
-        @root_field_location_selector = root_field_location_selector || BASIC_ROOT_FIELD_LOCATION_SELECTOR
+        @root_field_location_selector = root_field_location_selector
+        @root_entrypoints = root_entrypoints || {}
         
         @field_map = {}
         @resolver_map = {}
@@ -631,11 +630,20 @@ module GraphQL
             root_field_locations = @field_map[root_type.graphql_name][root_field_name]
             next unless root_field_locations.length > 1
 
-            target_location = @root_field_location_selector.call(root_field_locations, {
-              type_name: root_type.graphql_name,
-              field_name: root_field_name,
-            })
-            next unless root_field_locations.include?(target_location)
+            root_field_path = "#{root_type.graphql_name}.#{root_field_name}"
+            target_location = if @root_field_location_selector && @root_entrypoints.empty?
+              Warning.warn("Composer option `root_field_location_selector` is deprecated and will be removed.")
+              @root_field_location_selector.call(root_field_locations, {
+                type_name: root_type.graphql_name,
+                field_name: root_field_name,
+              })
+            else
+              @root_entrypoints[root_field_path] || root_field_locations.last
+            end
+
+            unless root_field_locations.include?(target_location)
+              raise CompositionError, "Invalid `root_entrypoints` configuration: `#{root_field_path}` has no `#{target_location}` location."
+            end
 
             root_field_locations.reject! { _1 == target_location }
             root_field_locations.unshift(target_location)

data/lib/graphql/stitching/executor/root_source.rb

@@ -16,7 +16,7 @@ module GraphQL::Stitching
           @executor.request.operation_name,
           @executor.request.operation_directives,
         )
-        query_variables = @executor.request.variables.slice(*op.variables.keys)
+        query_variables = @executor.request.variables.slice(*op.variables.each_key)
         result = @executor.request.supergraph.execute_at_location(op.location, query_document, query_variables, @executor.request)
         @executor.query_count += 1
 

data/lib/graphql/stitching/executor/shaper.rb

@@ -32,7 +32,7 @@ module GraphQL::Stitching
             field_name = node.alias || node.name
 
             if @request.query.get_field(parent_type, node.name).introspection?
-              if node.name == TYPENAME && parent_type == @root_type
+              if node.name == TYPENAME && parent_type == @root_type && node != TypeResolver::TYPENAME_EXPORT_NODE
                 raw_object[field_name] = @root_type.graphql_name
               end
               next

data/lib/graphql/stitching/executor/type_resolver_source.rb

@@ -165,7 +165,7 @@ module GraphQL::Stitching
         if pathed_errors_by_op_index_and_object_id.any?
           pathed_errors_by_op_index_and_object_id.each do |op_index, pathed_errors_by_object_id|
             repath_errors!(pathed_errors_by_object_id, ops.dig(op_index, "path"))
-            errors_result.concat(pathed_errors_by_object_id.values)
+            errors_result.push(*pathed_errors_by_object_id.each_value)
           end
         end
 

data/lib/graphql/stitching/planner.rb

@@ -213,7 +213,7 @@ module GraphQL
         input_selections.each do |node|
           case node
           when GraphQL::Language::Nodes::Field
-            if node.alias&.start_with?(TypeResolver::EXPORT_PREFIX)
+            if node.alias&.start_with?(TypeResolver::EXPORT_PREFIX) && node != TypeResolver::TYPENAME_EXPORT_NODE
               raise StitchingError, %(Alias "#{node.alias}" is not allowed because "#{TypeResolver::EXPORT_PREFIX}" is a reserved prefix.)
             elsif node.name == TYPENAME
               locale_selections << node
@@ -284,7 +284,7 @@ module GraphQL
           remote_selections_by_location = delegate_remote_selections(parent_type, remote_selections)
 
           # D) Create paths routing to new entrypoint locations via resolver queries.
-          routes = @supergraph.route_type_to_locations(parent_type.graphql_name, current_location, remote_selections_by_location.keys)
+          routes = @supergraph.route_type_to_locations(parent_type.graphql_name, current_location, remote_selections_by_location.each_key)
 
           # E) Translate resolver pathways into new entrypoints.
           routes.each_value do |route|

data/lib/graphql/stitching/request.rb

@@ -57,6 +57,10 @@ module GraphQL
         @context[:request] = self
       end
 
+      def original_document
+        @query.document
+      end
+
       # @return [String] the original document string, or a print of the parsed AST document.
       def string
         with_prepared_document { @string || normalized_string }
@@ -143,6 +147,11 @@ module GraphQL
         @query.static_errors
       end
 
+      # @return [Boolean] is the request valid?
+      def valid?
+        validate.empty?
+      end
+
       # Gets and sets the query plan for the request. Assigned query plans may pull from a cache,
       # which is useful for redundant GraphQL documents (commonly sent by frontend clients).
       # ```ruby

data/lib/graphql/stitching/supergraph/from_definition.rb

@@ -21,11 +21,8 @@ module GraphQL::Stitching
         field_map = {}
         resolver_map = {}
         possible_locations = {}
-        visibility_profiles = if (visibility_def = schema.directives[GraphQL::Stitching.visibility_directive])
-          visibility_def.get_argument("profiles").default_value
-        else
-          []
-        end
+        visibility_definition = schema.directives[GraphQL::Stitching.visibility_directive]
+        visibility_profiles = visibility_definition&.get_argument("profiles")&.default_value || EMPTY_ARRAY
 
         schema.types.each do |type_name, type|
           next if type.introspection?
@@ -75,7 +72,7 @@ module GraphQL::Stitching
           end
         end
 
-        executables = possible_locations.keys.each_with_object({}) do |location, memo|
+        executables = possible_locations.each_key.each_with_object({}) do |location, memo|
           executable = executables[location] || executables[location.to_sym]
           if validate_executable!(location, executable)
             memo[location] = executable

data/lib/graphql/stitching/supergraph.rb

@@ -38,7 +38,7 @@ module GraphQL
         @locations_by_type_and_field = @memoized_introspection_types.each_with_object(fields) do |(type_name, type), memo|
           next unless type.kind.fields?
 
-          memo[type_name] = type.fields.keys.each_with_object({}) do |field_name, m|
+          memo[type_name] = type.fields.each_key.each_with_object({}) do |field_name, m|
             m[field_name] = [SUPERGRAPH_LOCATION]
           end
         end.freeze
@@ -58,8 +58,10 @@ module GraphQL
         end
       end
 
-      def to_definition
-        @schema.to_definition
+      def to_definition(visibility_profile: nil)
+        @schema.to_definition(context: { 
+          visibility_profile: visibility_profile,
+        }.tap(&:compact!))
       end
 
       def resolvers_by_version
@@ -73,7 +75,7 @@ module GraphQL
       end
 
       def locations
-        @executables.keys.reject { _1 == SUPERGRAPH_LOCATION }
+        @executables.each_key.reject { _1 == SUPERGRAPH_LOCATION }
       end
 
       def memoized_schema_fields(type_name)
@@ -128,7 +130,7 @@ module GraphQL
       # "Type" => ["location1", "location2", ...]
       def locations_by_type
         @locations_by_type ||= @locations_by_type_and_field.each_with_object({}) do |(type_name, fields), memo|
-          memo[type_name] = fields.values.flatten.uniq
+          memo[type_name] = fields.values.tap(&:flatten!).tap(&:uniq!)
         end
       end
 

data/lib/graphql/stitching/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Stitching
-    VERSION = "1.7.0"
+    VERSION = "1.7.2"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-stitching
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.7.2
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-01 00:00:00.000000000 Z
+date: 2025-05-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -79,19 +79,19 @@ files:
 - LICENSE
 - README.md
 - Rakefile
-- docs/README.md
-- docs/client.md
-- docs/composer.md
-- docs/federation_entities.md
-- docs/http_executable.md
+- docs/composing_a_supergraph.md
+- docs/error_handling.md
+- docs/executables.md
 - docs/images/library.png
 - docs/images/merging.png
 - docs/images/stitching.png
-- docs/mechanics.md
-- docs/request.md
+- docs/introduction.md
+- docs/merged_types.md
+- docs/merged_types_apollo.md
+- docs/performance.md
+- docs/query_planning.md
+- docs/serving_a_supergraph.md
 - docs/subscriptions.md
-- docs/supergraph.md
-- docs/type_resolver.md
 - docs/visibility.md
 - examples/file_uploads/Gemfile
 - examples/file_uploads/Procfile

data/docs/README.md

@@ -1,19 +0,0 @@
-## GraphQL::Stitching
-
-This module provides a collection of components that may be composed into a stitched schema.
-
-![Library flow](./images/library.png)
-
-Major components include:
-
-- [Client](./client.md) - an out-of-the-box setup for performing stitched requests.
-- [Composer](./composer.md) - merges and validates many schemas into one graph.
-- [Supergraph](./supergraph.md) - manages the combined schema and location routing maps. Can be exported, cached, and rehydrated.
-- [Request](./request.md) - prepares a requested GraphQL document and variables for stitching.
-- [HttpExecutable](./http_executable.md) - proxies requests to remotes with multipart file upload support.
-
-Additional topics:
-
-- [Stitching mechanics](./mechanics.md) - more about building for stitching and how it operates.
-- [Subscriptions](./subscriptions.md) - explore how to stitch realtime event subscriptions.
-- [Federation entities](./federation_entities.md) - more about Apollo Federation compatibility.

data/docs/client.md

@@ -1,107 +0,0 @@
-## GraphQL::Stitching::Client
-
-The `Client` is an out-of-the-box convenience with all stitching components assembled into a default workflow. A client is designed to work for most common needs, though you're welcome to assemble the component parts into your own configuration (see the [client source](../lib/graphql/stitching/client.rb) for an example). A client is constructed with the same [location settings](./composer.md#performing-composition) used to perform supergraph composition:
-
-```ruby
-movies_schema = "type Query { ..."
-showtimes_schema = "type Query { ..."
-
-client = GraphQL::Stitching::Client.new(locations: {
-  products: {
-    schema: GraphQL::Schema.from_definition(movies_schema),
-    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3000"),
-    stitch: [{ field_name: "products", key: "id" }],
-  },
-  showtimes: {
-    schema: GraphQL::Schema.from_definition(showtimes_schema),
-    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3001"),
-  },
-  my_local: {
-    schema: MyLocal::GraphQL::Schema,
-  },
-})
-```
-
-Alternatively, you may pass a prebuilt `Supergraph` instance to the `Client` constructor. This is useful when [exporting and rehydrating](./supergraph.md#export-and-caching) supergraph instances, which bypasses the need for runtime composition:
-
-```ruby
-supergraph_sdl = File.read("precomposed_schema.graphql")
-supergraph = GraphQL::Stitching::Supergraph.from_definition(
-  supergraph_sdl,
-  executables: { ... },
-)
-
-client = GraphQL::Stitching::Client.new(supergraph: supergraph)
-```
-
-### Execution
-
-A client provides an `execute` method with a subset of arguments provided by [`GraphQL::Schema.execute`](https://graphql-ruby.org/queries/executing_queries). Executing requests on a stitching client becomes mostly a drop-in replacement to executing on a `GraphQL::Schema` instance:
-
-```ruby
-result = client.execute(
-  query: "query MyProduct($id: ID!) { product(id: $id) { name } }",
-  variables: { "id" => "1" },
-  operation_name: "MyProduct",
-)
-```
-
-Arguments for the `execute` method include:
-
-* `query`: a query (or mutation) as a string or parsed AST.
-* `variables`: a hash of variables for the request.
-* `operation_name`: the name of the operation to execute (when multiple are provided).
-* `validate`: true if static validation should run on the supergraph schema before execution.
-* `context`: an object passed through to executable calls and client hooks.
-
-### Cache hooks
-
-The client provides cache hooks to enable caching query plans across requests. Without caching, every request made to the client will be planned individually. With caching, a query may be planned once, cached, and then executed from cache for subsequent requests. Cache keys are a normalized digest of each query string.
-
-```ruby
-client.on_cache_read do |request|
-  $cache.get(request.digest) # << 3P code
-end
-
-client.on_cache_write do |request, payload|
-  $cache.set(request.digest, payload) # << 3P code
-end
-```
-
-All request digests use SHA2 by default. You can swap in [a faster algorithm](https://github.com/Shopify/blake3-rb) and/or add base scoping by reconfiguring the stitching library:
-
-```ruby
-GraphQL::Stitching.digest { |str| Digest::MD5.hexdigest("v2/#{str}") }
-```
-
-Note that inlined input data works against caching, so you should _avoid_ these input literals when possible:
-
-```graphql
-query {
-  product(id: "1") { name }
-}
-```
-
-Instead, leverage query variables so that the document body remains consistent across requests:
-
-```graphql
-query($id: ID!) {
-  product(id: $id) { name }
-}
-
-# variables: { "id" => "1" }
-```
-
-### Error hooks
-
-The client also provides an error hook. Any program errors rescued during execution will be passed to the `on_error` handler, which can report on the error as needed and return a formatted error message for the client to add to the [GraphQL errors](https://spec.graphql.org/June2018/#sec-Errors) result.
-
-```ruby
-client.on_error do |request, err|
-  # log the error
-  Bugsnag.notify(err)
-
-  # return a formatted message for the public response
-  "Whoops, please contact support abount request '#{request.context[:request_id]}'"
-end
-```