graphql-stitching 1.6.2 → 1.7.1

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

@@ -0,0 +1,178 @@
+# 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, and provides a flexible analog to Apollo Federation's `@inaccessible` rule.
+
+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
+
+Schemas may include a `@visibility` directive that defines element _profiles_. A profile is just a label describing an API distribution (public, private, etc). When a request is assigned a visibility profile, it can only access elements belonging to that profile. Elements without an explicit `@visibility` constraint belong to all profiles. For example:
+
+_schemas/product_info.graphql_
+```graphql
+directive @stitch(key: String!) on FIELD_DEFINITION
+directive @visibility(profiles: [String!]!) on OBJECT | INTERFACE | UNION | INPUT_OBJECT | ENUM | SCALAR | FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE
+
+type Product {
+  id: ID!
+  title: String!
+  description: String!
+}
+
+type Query {
+  featuredProduct: Product
+  product(id: ID!): Product @stitch(key: "id") @visibility(profiles: ["private"])
+}
+```
+
+_schemas/product_prices.graphql_
+```graphql
+directive @stitch(key: String!) on FIELD_DEFINITION
+directive @visibility(profiles: [String!]!) on OBJECT | INTERFACE | UNION | INPUT_OBJECT | ENUM | SCALAR | FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE
+
+type Product {
+  id: ID! @visibility(profiles: [])
+  msrp: Float! @visibility(profiles: ["private"])
+  price: Float!
+}
+
+type Query {
+  products(ids: [ID!]!): [Product]! @stitch(key: "id") @visibility(profiles: ["private"])
+}
+```
+
+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(
+  composer_options: {
+    visibility_profiles: ["public", "private"],
+  },
+  locations: {
+    info: {
+      schema: GraphQL::Schema.from_definition(File.read("schemas/product_info.graphql")),
+      executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3001"),
+    },
+    prices: {
+      schema: GraphQL::Schema.from_definition(File.read("schemas/product_prices.graphql")),
+      executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3002"),
+    },
+  }
+)
+```
+
+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 "private" or without profile
+    id     # only visible without profile
+  }
+}|
+
+result = client.execute(query, context: { 
+  visibility_profile: "public", # << or "private"
+})
+```
+
+The `visibility_profile` parameter will select which visibility distribution to use while introspecting and validating the request. For example:
+
+- 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. 
+- 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 use by the stitching implementation.
+
+## Adding visibility directives
+
+Add the `@visibility` directive into schemas using the library definition:
+
+```ruby
+class QueryType < GraphQL::Schema::Object
+  field :my_field, String, null: true do |f|
+    f.directive(GraphQL::Stitching::Directives::Visibility, profiles: ["private"])
+  end
+end
+
+class MySchema < GraphQL::Schema
+  directive(GraphQL::Stitching::Directives::Visibility)
+  query(QueryType)
+end
+```
+
+## Merging visibilities
+
+Visibility directives merge across schemas into the narrowest constraint possible. Profiles for an element will intersect into its merged supergraph constraint:
+
+```graphql
+# location 1
+myField: String @visibility(profiles: ["a", "c"])
+
+# location 2
+myField: String @visibility(profiles: ["b", "c"])
+
+# merged supergraph
+myField: String @visibility(profiles: ["c"])
+```
+
+This may cause an element's profiles to intersect into an empty set, which means the element belongs to no profiles and will be hidden from all named distributions:
+
+```graphql
+# location 1
+myField: String @visibility(profiles: ["a"])
+
+# location 2
+myField: String @visibility(profiles: ["b"])
+
+# merged supergraph
+myField: String @visibility(profiles: [])
+```
+
+Locations may omit visibility information to give other locations full control. Remember that elements without a `@visibility` constraint belong to all profiles, which also applies while merging:
+
+```graphql
+# location 1
+myField: String
+
+# location 2
+myField: String @visibility(profiles: ["b"])
+
+# merged supergraph
+myField: String @visibility(profiles: ["b"])
+```
+
+## Type controls
+
+Visibility controls can be applied to almost all GraphQL schema elements, including:
+
+- Types (Object, Interface, Union, Enum, Scalar, InputObject)
+- Fields (of Object and Interface)
+- Arguments (of Field and InputObject)
+- Enum values
+
+While the visibility of type members (fields, arguments, and enum values) are pretty intuitive, the visibility of parent types is far more nuanced as constraints start to cascade:
+
+```graphql
+type Widget @visibility(profiles: ["private"]) {
+  title: String
+}
+
+type Query {
+  widget: Widget # << GETS HIDDEN
+}
+```
+
+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,22 +7,30 @@ 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
 
       # Builds a new client instance. Either `supergraph` or `locations` configuration is required.
       # @param supergraph [Supergraph] optional, a pre-composed supergraph that bypasses composer setup.
       # @param locations [Hash<Symbol, Hash<Symbol, untyped>>] optional, composer configurations for each graph location.
-      # @param composer [Composer] optional, a pre-configured composer instance for use with `locations` configuration.
-      def initialize(locations: nil, supergraph: nil, composer: nil)
+      # @param composer_options [Hash] optional, composer options for configuring composition.
+      def initialize(locations: nil, supergraph: nil, composer_options: {})
         @supergraph = if locations && supergraph
           raise ArgumentError, "Cannot provide both locations and a supergraph."
         elsif supergraph && !supergraph.is_a?(Supergraph)
           raise ArgumentError, "Provided supergraph must be a GraphQL::Stitching::Supergraph instance."
+        elsif supergraph && composer_options.any?
+          raise ArgumentError, "Cannot provide composer options with a pre-built supergraph."
         elsif supergraph
           supergraph
         else
-          composer ||= Composer.new
+          composer = Composer.new(**composer_options)
           composer.perform(locations)
         end
 

data/lib/graphql/stitching/composer.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require_relative "composer/base_validator"
-require_relative "composer/supergraph_directives"
 require_relative "composer/validate_interfaces"
 require_relative "composer/validate_type_resolvers"
 require_relative "composer/type_resolver_config"
@@ -23,9 +22,9 @@ module GraphQL
 
       # @api private
       BASIC_VALUE_MERGER = ->(values_by_location, _info) { values_by_location.values.find { !_1.nil? } }
-
+      
       # @api private
-      BASIC_ROOT_FIELD_LOCATION_SELECTOR = ->(locations, _info) { locations.last }
+      VISIBILITY_PROFILES_MERGER = ->(values_by_location, _info) { values_by_location.values.reduce(:&) }
 
       # @api private
       COMPOSITION_VALIDATORS = [
@@ -52,11 +51,13 @@ module GraphQL
         query_name: "Query",
         mutation_name: "Mutation",
         subscription_name: "Subscription",
+        visibility_profiles: [],
         description_merger: nil,
         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
@@ -65,12 +66,14 @@ 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 = {}
         @resolver_configs = {}
         @mapped_type_names = {}
+        @visibility_profiles = Set.new(visibility_profiles)
         @subgraph_directives_by_name_and_location = nil
         @subgraph_types_by_name_and_location = nil
         @schema_directives = nil
@@ -85,9 +88,9 @@ module GraphQL
 
         directives_to_omit = [
           GraphQL::Stitching.stitch_directive,
-          KeyDirective.graphql_name,
-          ResolverDirective.graphql_name,
-          SourceDirective.graphql_name,
+          Directives::SupergraphKey.graphql_name,
+          Directives::SupergraphResolver.graphql_name,
+          Directives::SupergraphSource.graphql_name,
         ]
 
         # "directive_name" => "location" => subgraph_directive
@@ -181,6 +184,10 @@ module GraphQL
         expand_abstract_resolvers(schema, schemas)
         apply_supergraph_directives(schema, @resolver_map, @field_map)
 
+        if (visibility_def = schema.directives[GraphQL::Stitching.visibility_directive])
+          visibility_def.get_argument("profiles").default_value(@visibility_profiles.to_a.sort)
+        end
+
         supergraph = Supergraph.from_definition(schema, executables: executables)
 
         COMPOSITION_VALIDATORS.each do |validator_class|
@@ -237,7 +244,7 @@ module GraphQL
 
         builder = self
 
-        Class.new(GraphQL::Schema::Scalar) do
+        Class.new(GraphQL::Stitching::Supergraph::ScalarType) do
           graphql_name(type_name)
           description(builder.merge_descriptions(type_name, types_by_location))
           builder.build_merged_directives(type_name, types_by_location, self)
@@ -264,7 +271,7 @@ module GraphQL
           end
         end
 
-        Class.new(GraphQL::Schema::Enum) do
+        Class.new(GraphQL::Stitching::Supergraph::EnumType) do
           graphql_name(type_name)
           description(builder.merge_descriptions(type_name, types_by_location))
           builder.build_merged_directives(type_name, types_by_location, self)
@@ -286,7 +293,7 @@ module GraphQL
       def build_object_type(type_name, types_by_location)
         builder = self
 
-        Class.new(GraphQL::Schema::Object) do
+        Class.new(GraphQL::Stitching::Supergraph::ObjectType) do
           graphql_name(type_name)
           description(builder.merge_descriptions(type_name, types_by_location))
 
@@ -306,7 +313,7 @@ module GraphQL
         builder = self
 
         Module.new do
-          include GraphQL::Schema::Interface
+          include GraphQL::Stitching::Supergraph::InterfaceType
           graphql_name(type_name)
           description(builder.merge_descriptions(type_name, types_by_location))
 
@@ -325,7 +332,7 @@ module GraphQL
       def build_union_type(type_name, types_by_location)
         builder = self
 
-        Class.new(GraphQL::Schema::Union) do
+        Class.new(GraphQL::Stitching::Supergraph::UnionType) do
           graphql_name(type_name)
           description(builder.merge_descriptions(type_name, types_by_location))
 
@@ -340,7 +347,7 @@ module GraphQL
       def build_input_object_type(type_name, types_by_location)
         builder = self
 
-        Class.new(GraphQL::Schema::InputObject) do
+        Class.new(GraphQL::Stitching::Supergraph::InputObjectType) do
           graphql_name(type_name)
           description(builder.merge_descriptions(type_name, types_by_location))
           builder.build_merged_arguments(type_name, types_by_location, self)
@@ -451,6 +458,7 @@ module GraphQL
         end
 
         directives_by_name_location.each do |directive_name, directives_by_location|
+          kwarg_merger = @directive_kwarg_merger
           directive_class = @schema_directives[directive_name]
           next unless directive_class
 
@@ -467,8 +475,20 @@ module GraphQL
             end
           end
 
+          if directive_class.graphql_name == GraphQL::Stitching.visibility_directive
+            unless GraphQL::Stitching.supports_visibility?
+              raise CompositionError, "Using `@#{GraphQL::Stitching.visibility_directive}` directive " \
+                "for schema visibility controls requires GraphQL Ruby v#{GraphQL::Stitching::MIN_VISIBILITY_VERSION} or later."
+            end
+
+            if (profiles = kwarg_values_by_name_location["profiles"])
+              @visibility_profiles.merge(profiles.each_value.reduce(&:|))
+              kwarg_merger = VISIBILITY_PROFILES_MERGER
+            end
+          end
+
           kwargs = kwarg_values_by_name_location.each_with_object({}) do |(kwarg_name, kwarg_values_by_location), memo|
-            memo[kwarg_name.to_sym] = @directive_kwarg_merger.call(kwarg_values_by_location, {
+            memo[kwarg_name.to_sym] = kwarg_merger.call(kwarg_values_by_location, {
               type_name: type_name,
               field_name: field_name,
               argument_name: argument_name,
@@ -610,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)
@@ -693,8 +722,8 @@ module GraphQL
   
             keys_for_type.each do |key, locations|
               locations.each do |location|
-                schema_directives[KeyDirective.graphql_name] ||= KeyDirective
-                type.directive(KeyDirective, key: key, location: location)
+                schema_directives[Directives::SupergraphKey.graphql_name] ||= Directives::SupergraphKey
+                type.directive(Directives::SupergraphKey, key: key, location: location)
               end
             end
   
@@ -710,8 +739,8 @@ module GraphQL
                 type_name: (resolver.type_name if resolver.type_name != type_name),
               }
   
-              schema_directives[ResolverDirective.graphql_name] ||= ResolverDirective
-              type.directive(ResolverDirective, **params.tap(&:compact!))
+              schema_directives[Directives::SupergraphResolver.graphql_name] ||= Directives::SupergraphResolver
+              type.directive(Directives::SupergraphResolver, **params.tap(&:compact!))
             end
           end
   
@@ -737,8 +766,8 @@ module GraphQL
   
             # Apply source directives to annotate the possible locations of each field
             locations_for_field.each do |location|
-              schema_directives[SourceDirective.graphql_name] ||= SourceDirective
-              field.directive(SourceDirective, location: location)
+              schema_directives[Directives::SupergraphSource.graphql_name] ||= Directives::SupergraphSource
+              field.directive(Directives::SupergraphSource, location: location)
             end
           end
         end

data/lib/graphql/stitching/{composer/supergraph_directives.rb → directives.rb}

@@ -1,8 +1,26 @@
 # frozen_string_literal: true
 
 module GraphQL::Stitching
-  class Composer
-    class KeyDirective < GraphQL::Schema::Directive
+  module Directives
+    class Stitch < GraphQL::Schema::Directive
+      graphql_name "stitch"
+      locations FIELD_DEFINITION
+      argument :key, String, required: true
+      argument :arguments, String, required: false
+      argument :type_name, String, required: false
+      repeatable true
+    end
+
+    class Visibility < GraphQL::Schema::Directive
+      graphql_name "visibility"
+      locations(
+        OBJECT, INTERFACE, UNION, INPUT_OBJECT, ENUM, SCALAR, 
+        FIELD_DEFINITION, ARGUMENT_DEFINITION, INPUT_FIELD_DEFINITION, ENUM_VALUE
+      )
+      argument :profiles, [String, null: false], required: true
+    end
+
+    class SupergraphKey < GraphQL::Schema::Directive
       graphql_name "key"
       locations OBJECT, INTERFACE, UNION
       argument :key, String, required: true
@@ -10,7 +28,7 @@ module GraphQL::Stitching
       repeatable true
     end
 
-    class ResolverDirective < GraphQL::Schema::Directive
+    class SupergraphResolver < GraphQL::Schema::Directive
       graphql_name "resolver"
       locations OBJECT, INTERFACE, UNION
       argument :location, String, required: true
@@ -23,7 +41,7 @@ module GraphQL::Stitching
       repeatable true
     end
     
-    class SourceDirective < GraphQL::Schema::Directive
+    class SupergraphSource < GraphQL::Schema::Directive
       graphql_name "source"
       locations FIELD_DEFINITION
       argument :location, String, required: true

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 }