graphql-stitching 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5090330cd8b46c9d7dbfc7bbc68f5840e97f8bcbc5ec710de219441237fb61e5
-  data.tar.gz: 846a15ccc2734024dec751d61d456aa05d4b7c396d6789d629da21e11c182100
+  metadata.gz: 05c82abfcbec2db513d097c21424916bea46ebb0e4b434db0dc10a92ddfc2f9b
+  data.tar.gz: 79e4184f4ed237e2132f67389bb838fbbf18a8141b1d2ab30f8c5b710f47cb8f
 SHA512:
-  metadata.gz: 1c0c16a9bb49b3fad30057958d79fe92737bb659bf7135dd03ef716597f013249c99d9372478e20619f54e1e77f68f3b7f746b92e9e220b80be9ecaf88b656de
-  data.tar.gz: f370e520552f3e8be141073dd7ca06f68a463824c946b9cd03357b33ad5c9fc928893e846314f08941e2590d24202081450677fbfca480474be9833d341209a1
+  metadata.gz: e6c6ccb67c95df19b01bbeea1c0ed731a7153c3e4a184dab7dad6c2c52a22e22183075d123bf2dc78f431e73ff1fb4d31f0a21100072adb4f05bff2813ff9294
+  data.tar.gz: 2b9257ed86bdac5cb2403e527fc90893c961637d14bda2c4e5a16be7c8dc23206f860bdb596cc26f35ea704156b7443c5ef013efcc4c8cde251c9a865777e3ad

data/README.md

@@ -7,12 +7,12 @@ GraphQL stitching composes a single schema from multiple underlying GraphQL reso
 **Supports:**
 - Merged object and interface types.
 - Multiple keys per merged type.
-- Shared objects, enums, and inputs across locations.
+- Shared objects, fields, enums, and inputs across locations.
 - Combining local and remote schemas.
 
 **NOT Supported:**
-- Computed fields (ie: federation-style `@requires`)
-- Subscriptions
+- Computed fields (ie: federation-style `@requires`).
+- Subscriptions, defer/stream.
 
 This Ruby implementation is a sibling to [GraphQL Tools](https://the-guild.dev/graphql/stitching) (JS) and [Bramble](https://movio.github.io/bramble/) (Go), and its capabilities fall somewhere in between them. GraphQL stitching is similar in concept to [Apollo Federation](https://www.apollographql.com/docs/federation/), though more generic. While Ruby is not the fastest language for a high-throughput API gateway, the opportunity here is for a Ruby application to stitch its local schema onto a remote schema (making itself a superset of the remote) without requiring an additional gateway service.
 
@@ -70,13 +70,13 @@ result = gateway.execute(
 )
 ```
 
-Schemas provided to the `Gateway` constructor may be class-based schemas with local resolvers (locally-executable schemas), or schemas built from SDL strings (schema definition language parsed using `GraphQL::Schema.from_definition`) and mapped to remote locations.
+Schemas provided to the `Gateway` constructor may be class-based schemas with local resolvers (locally-executable schemas), or schemas built from SDL strings (schema definition language parsed using `GraphQL::Schema.from_definition`) and mapped to remote locations. See [composer docs](./docs/composer.md) for more information on how schemas get merged.
 
 While the [`Gateway`](./docs/gateway.md) constructor is an easy quick start, the library also has several discrete components that can be assembled into custom workflows:
 
 - [Composer](./docs/composer.md) - merges and validates many schemas into one graph.
 - [Supergraph](./docs/supergraph.md) - manages the combined schema and location routing maps. Can be exported, cached, and rehydrated.
-- [Document](./docs/document.md) - manages a parsed GraphQL request document.
+- [Request](./docs/request.md) - prepares a requested GraphQL document and variables for stitching.
 - [Planner](./docs/planner.md) - builds a cacheable query plan for a request document.
 - [Executor](./docs/executor.md) - executes a query plan with given request variables.
 
@@ -121,7 +121,7 @@ shipping_schema = <<~GRAPHQL
   }
 GRAPHQL
 
-supergraph = GraphQL::Stitching::Composer.new({
+supergraph = GraphQL::Stitching::Composer.new(schemas: {
   "products" => GraphQL::Schema.from_definition(products_schema),
   "shipping" => GraphQL::Schema.from_definition(shipping_schema),
 })
@@ -146,7 +146,7 @@ type Query {
 }
 ```
 
-* The `@stitch` directive is applied to a root query where the merged type may be accessed. The merged type is inferred from the field return.
+* The `@stitch` directive is applied to a root query where the merged type may be accessed. The merged type identity is inferred from the field return.
 * The `key: "id"` parameter indicates that an `{ id }` must be selected from prior locations so it may be submitted as an argument to this query. The query argument used to send the key is inferred when possible (more on arguments later).
 
 Each location that provides a unique variant of a type must provide _exactly one_ stitching query per possible key (more on multiple keys later). The exception to this requirement are types that contain only a single key field:
@@ -261,29 +261,29 @@ GraphQL::Stitching.stitch_directive = "merge"
 
 ## Executables
 
-A [Supergraph](./docs/supergraph.md) will delegate requests to the individual `GraphQL::Schema` classes that composed it. You may change this behavior by assigning new executables: these may be `GraphQL::Schema` classes, or objects that respond to `.call` with the following arguments...
+An executable resource performs location-specific GraphQL requests. Executables may be `GraphQL::Schema` classes, or objects that respond to `.call` with the following arguments...
 
 ```ruby
 class MyExecutable
-  def call(location, query_string, variables)
+  def call(location, query_string, variables, context)
     # process a GraphQL request...
   end
 end
 ```
 
-Executables are assigned to a supergraph using `assign_executable`:
+By default, a [Supergraph](./docs/supergraph.md) will use the individual `GraphQL::Schema` classes that composed it as executable resources for each location. You may assign new executables using `assign_executable`:
 
 ```ruby
 supergraph = GraphQL::Stitching::Composer.new(...)
 
 supergraph.assign_executable("location1", MyExecutable.new)
-supergraph.assign_executable("location2", ->(loc, query, vars) { ... })
-supergraph.assign_executable("location3") do |loc, query vars|
+supergraph.assign_executable("location2", ->(loc, query, vars, ctx) { ... })
+supergraph.assign_executable("location3") do |loc, query vars, ctx|
   # ...
 end
 ```
 
-The `GraphQL::Stitching::RemoteClient` class is provided as a simple executable wrapper around `Net::HTTP.post`. You should build your own executables to leverage your existing libraries and to add instrumentation. Note that you _must_ manually assign all executables to a `Supergraph` instance when rehydrating it from cache ([see docs](./docs/supergraph.md)).
+The `GraphQL::Stitching::RemoteClient` class is provided as a simple executable wrapper around `Net::HTTP.post`. You should build your own executables to leverage your existing libraries and to add instrumentation. Note that you must manually assign all executables to a `Supergraph` when rehydrating it from cache ([see docs](./docs/supergraph.md)).
 
 ## Concurrency
 
@@ -291,7 +291,7 @@ The [Executor](./docs/executor.md) component builds atop the Ruby fiber-based im
 
 ## Example
 
-This repo includes a working example of several stitched schemas running across Rack servers. Try running it:
+This repo includes a working example of several stitched schemas running across small Rack servers. Try running it:
 
 ```shell
 bundle install

data/docs/README.md

@@ -9,6 +9,6 @@ Major components include:
 - [Gateway](./gateway.md) - an out-of-the-box stitching configuration.
 - [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.
-- [Document](./document.md) - manages a parsed GraphQL request document.
+- [Request](./request.md) - prepares a requested GraphQL document and variables for stitching.
 - [Planner](./planner.md) - builds a cacheable query plan for a request document.
 - [Executor](./executor.md) - executes a query plan with given request variables.

data/docs/composer.md

@@ -1,6 +1,6 @@
 ## GraphQL::Stitching::Composer
 
-The `Composer` receives many individual `GraphQL:Schema` instances for various graph locations and _composes_ them into a combined [`Supergraph`](./supergraph.md) that is validated for integrity. The resulting context provides a combined GraphQL schema and delegation maps used to route incoming requests:
+The `Composer` receives many individual `GraphQL:Schema` instances for various graph locations and _composes_ them into a combined [`Supergraph`](./supergraph.md) that is validated for integrity. The resulting supergraph provides a combined GraphQL schema and delegation maps used to route incoming requests:
 
 ```ruby
 storefronts_sdl = <<~GRAPHQL
@@ -33,7 +33,7 @@ products_sdl = <<~GRAPHQL
   }
 GRAPHQL
 
-supergraph = GraphQL::Stitching::Composer.new({
+supergraph = GraphQL::Stitching::Composer.new(schemas: {
   "storefronts" => GraphQL::Schema.from_definition(storefronts_sdl),
   "products" => GraphQL::Schema.from_definition(products_sdl),
 }).perform
@@ -47,9 +47,9 @@ The individual schemas provided to the composer are assigned a location name bas
 
 The strategy used to merge source schemas into the combined schema is based on each element type:
 
-- `Object` and `Interface` types merge their fields together:
+- `Object` and `Interface` types merge their fields and directives together:
   - Common fields across locations must share a value type, and the weakest nullability is used.
-  - Field arguments merge using the same rules as `InputObject`.
+  - Field and directive arguments merge using the same rules as `InputObject`.
   - Objects with unique fields across locations must implement [`@stitch` accessors](../README.md#merged-types).
   - Shared object types without `@stitch` accessors must contain identical fields.
   - Merged interfaces must remain compatible with all underlying implementations.
@@ -66,4 +66,45 @@ The strategy used to merge source schemas into the combined schema is based on e
 
 - `Scalar` types are added for all scalar names across all locations.
 
+- `Directive` definitions are added for all distinct names across locations:
+  - Arguments merge using the same rules as `InputObject`.
+  - Stitching directives (both definitions and assignments) are omitted.
+
 Note that the structure of a composed schema may change based on new schema additions and/or element usage (ie: changing input object arguments in one service may cause the intersection of arguments to change). Therefore, it's highly recommended that you use a [schema comparator](https://github.com/xuorig/graphql-schema_comparator) to flag regressions across composed schema versions.
+
+### Value merger functions
+
+The composer has no way of intelligently merging static data values that are embedded into a schema. These include:
+
+- Element descriptions
+- Element deprecations
+- Directive keyword argument values
+
+By default, the first non-null value encountered across locations is used to fill these data slots. You may customize this aggregation process by providing value merger functions:
+
+
+```ruby
+supergraph = GraphQL::Stitching::Composer.new(
+  schemas: { ... },
+  description_merger: ->(values_by_location, info) { values_by_location.values.last },
+  deprecation_merger: ->(values_by_location, info) { values_by_location.values.last },
+  directive_kwarg_merger: ->(values_by_location, info) { values_by_location.values.last },
+).perform
+```
+
+Each merger accepts a `values_by_location` and an `info` argument; these provide the values found across locations and info about where in schema they were encountered:
+
+```ruby
+values_by_location = {
+  "storefronts" => "A fabulous data type.",
+  "products" => "An excellent data type.",
+}
+
+info = {
+  type_name: "Product",
+  # field_name: ...,
+  # argument_name: ...,
+}
+```
+
+The function should then select a value (or compute a new one) and return that for use in the combined schema.

data/docs/executor.md

@@ -12,28 +12,29 @@ query = <<~GRAPHQL
   }
 GRAPHQL
 
-variables = { "id" => "123" }
-
-document = GraphQL::Stitching::Document.new(query, operation_name: "MyQuery")
+request = GraphQL::Stitching::Request.new(query, variables: { "id" => "123" }, operation_name: "MyQuery")
 
 plan = GraphQL::Stitching::Planner.new(
   supergraph: supergraph,
-  document: document,
+  request: request,
 ).perform
 
-# get the raw result without shaping
-raw_result = GraphQL::Stitching::Executor.new(
+result = GraphQL::Stitching::Executor.new(
   supergraph: supergraph,
   plan: plan.to_h,
-  variables: variables,
+  request: request,
 ).perform
+```
+
+### Raw results
 
-# get the final result with shaping
-final_result = GraphQL::Stitching::Executor.new(
+By default, execution results are always returned with document shaping (stitching additions removed, missing fields added, null bubbling applied). You may access the raw execution result by calling the `perform` method with a `raw: true` argument:
+
+```ruby
+# get the raw result without shaping
+raw_result = GraphQL::Stitching::Executor.new(
   supergraph: supergraph,
   plan: plan.to_h,
-  variables: variables,
-).perform(document)
+  request: request,
+).perform(raw: true)
 ```
-
-Note that an executor's `perform` method accepts a document argument. When provided, the raw execution result will be shaped for delivery to match the document. Without a document, the raw result will be returned with stitching inclusions and no null bubbling applied.

data/docs/planner.md

@@ -1,9 +1,9 @@
 ## GraphQL::Stitching::Planner
 
-A `Planner` generates a query plan for a given [`Supergraph`](./supergraph.md) and request [`Document`](./document.md). The generated plan breaks down all the discrete GraphQL operations that must be delegated across locations and their sequencing.
+A `Planner` generates a query plan for a given [`Supergraph`](./supergraph.md) and [`Request`](./request.md). The generated plan breaks down all the discrete GraphQL operations that must be delegated across locations and their sequencing.
 
 ```ruby
-request = <<~GRAPHQL
+document = <<~GRAPHQL
   query MyQuery($id: ID!) {
     product(id:$id) {
       title
@@ -12,11 +12,11 @@ request = <<~GRAPHQL
   }
 GRAPHQL
 
-document = GraphQL::Stitching::Document.new(request, operation_name: "MyQuery")
+request = GraphQL::Stitching::Request.new(document, operation_name: "MyQuery").prepare!
 
 plan = GraphQL::Stitching::Planner.new(
   supergraph: supergraph,
-  document: document,
+  request: request,
 ).perform
 ```
 
@@ -25,17 +25,17 @@ plan = GraphQL::Stitching::Planner.new(
 Plans are designed to be cacheable. This is very useful for redundant GraphQL documents (commonly sent by frontend clients) where there's no sense in planning every request individually. It's far more efficient to generate a plan once and cache it, then simply retreive the plan and execute it for future requests.
 
 ```ruby
-cached_plan = $redis.get(document.digest)
+cached_plan = $redis.get(request.digest)
 
 plan = if cached_plan
   JSON.parse(cached_plan)
 else
   plan_hash = GraphQL::Stitching::Planner.new(
     supergraph: supergraph,
-    document: document,
+    request: request,
   ).perform.to_h
 
-  $redis.set(document.digest, JSON.generate(plan_hash))
+  $redis.set(request.digest, JSON.generate(plan_hash))
   plan_hash
 end
 

data/docs/request.md

@@ -0,0 +1,47 @@
+## GraphQL::Stitching::Request
+
+A `Request` contains a parsed GraphQL document and variables, and handles the logistics of extracting the appropriate operation, variable definitions, and fragments. A `Request` should be built once per server request and passed through to other stitching components that utilize request information.
+
+```ruby
+document = "query FetchMovie($id: ID!) { movie(id:$id) { id genre } }"
+request = GraphQL::Stitching::Request.new(document, variables: { "id" => "1" }, operation_name: "FetchMovie")
+
+request.document # parsed AST via GraphQL.parse
+request.variables # user-submitted variables
+request.string # normalized printed document string
+request.digest # SHA digest of the normalized document string
+
+request.variable_definitions # a mapping of variable names to their type definitions
+request.fragment_definitions # a mapping of fragment names to their fragment definitions
+```
+
+### Preparing requests
+
+A request should be prepared using the `prepare!` method before using it:
+
+```ruby
+document = <<~GRAPHQL
+  query FetchMovie($id: ID!, $lang: String = "en", $withShowtimes: Boolean = true) {
+    movie(id:$id) {
+      id
+      title(lang: $lang)
+      showtimes @include(if: $withShowtimes) {
+        time
+      }
+    }
+  }
+GRAPHQL
+
+request = GraphQL::Stitching::Request.new(
+  document,
+  variables: { "id" => "1" },
+  operation_name: "FetchMovie",
+)
+
+request.prepare!
+```
+
+Preparing a request will apply several destructive transformations:
+
+- Default values from variable definitions will be added to request variables.
+- The document will be pre-shaped based on `@skip` and `@include` directives.

data/docs/supergraph.md

@@ -6,7 +6,7 @@ A `Supergraph` is the singuar representation of a stitched graph. `Supergraph` i
 storefronts_sdl = "type Query { storefront(id: ID!): Storefront } ..."
 products_sdl = "type Query { product(id: ID!): Product } ..."
 
-supergraph = GraphQL::Stitching::Composer.new({
+supergraph = GraphQL::Stitching::Composer.new(schemas: {
   "storefronts" => GraphQL::Schema.from_definition(storefronts_sdl),
   "products" => GraphQL::Schema.from_definition(products_sdl),
 }).perform

data/lib/graphql/stitching/composer.rb

@@ -6,9 +6,9 @@ module GraphQL
       class ComposerError < StitchingError; end
       class ValidationError < ComposerError; end
 
-      attr_reader :query_name, :mutation_name, :subschema_types_by_name_and_location
+      attr_reader :query_name, :mutation_name, :subschema_types_by_name_and_location, :schema_directives
 
-      DEFAULT_STRING_MERGER = ->(str_by_location, _info) { str_by_location.values.find { !_1.nil? } }
+      DEFAULT_VALUE_MERGER = ->(values_by_location, _info) { values_by_location.values.find { !_1.nil? } }
 
       VALIDATORS = [
         "ValidateInterfaces",
@@ -20,7 +20,8 @@ module GraphQL
         query_name: "Query",
         mutation_name: "Mutation",
         description_merger: nil,
-        deprecation_merger: nil
+        deprecation_merger: nil,
+        directive_kwarg_merger: nil
       )
         @schemas = schemas
         @query_name = query_name
@@ -29,11 +30,27 @@ module GraphQL
         @boundary_map = {}
         @mapped_type_names = {}
 
-        @description_merger = description_merger || DEFAULT_STRING_MERGER
-        @deprecation_merger = deprecation_merger || DEFAULT_STRING_MERGER
+        @description_merger = description_merger || DEFAULT_VALUE_MERGER
+        @deprecation_merger = deprecation_merger || DEFAULT_VALUE_MERGER
+        @directive_kwarg_merger = directive_kwarg_merger || DEFAULT_VALUE_MERGER
       end
 
       def perform
+        # "directive_name" => "location" => candidate_directive
+        @subschema_directives_by_name_and_location = @schemas.each_with_object({}) do |(location, schema), memo|
+          (schema.directives.keys - schema.default_directives.keys - GraphQL::Stitching.stitching_directive_names).each do |directive_name|
+            memo[directive_name] ||= {}
+            memo[directive_name][location] = schema.directives[directive_name]
+          end
+        end
+
+        # "Typename" => merged_directive
+        @schema_directives = @subschema_directives_by_name_and_location.each_with_object({}) do |(directive_name, directives_by_location), memo|
+          memo[directive_name] = build_directive(directive_name, directives_by_location)
+        end
+
+        @schema_directives.merge!(GraphQL::Schema.default_directives)
+
         # "Typename" => "location" => candidate_type
         @subschema_types_by_name_and_location = @schemas.each_with_object({}) do |(location, schema), memo|
           raise ComposerError, "Location keys must be strings" unless location.is_a?(String)
@@ -91,6 +108,7 @@ module GraphQL
           orphan_types schema_types.values
           query schema_types[builder.query_name]
           mutation schema_types[builder.mutation_name]
+          directives builder.schema_directives.values
 
           own_orphan_types.clear
         end
@@ -112,6 +130,18 @@ module GraphQL
         supergraph
       end
 
+      def build_directive(directive_name, directives_by_location)
+        builder = self
+
+        Class.new(GraphQL::Schema::Directive) do
+          graphql_name(directive_name)
+          description(builder.merge_descriptions(directive_name, directives_by_location))
+          repeatable(directives_by_location.values.any?(&:repeatable?))
+          locations(*directives_by_location.values.flat_map(&:locations).uniq)
+          builder.build_merged_arguments(directive_name, directives_by_location, self)
+        end
+      end
+
       def build_scalar_type(type_name, types_by_location)
         built_in_type = GraphQL::Schema::BUILT_IN_TYPES[type_name]
         return built_in_type if built_in_type
@@ -121,6 +151,7 @@ module GraphQL
         Class.new(GraphQL::Schema::Scalar) do
           graphql_name(type_name)
           description(builder.merge_descriptions(type_name, types_by_location))
+          builder.build_merged_directives(type_name, types_by_location, self)
         end
       end
 
@@ -146,13 +177,16 @@ module GraphQL
         Class.new(GraphQL::Schema::Enum) do
           graphql_name(type_name)
           description(builder.merge_descriptions(type_name, types_by_location))
+          builder.build_merged_directives(type_name, types_by_location, self)
 
           enum_values_by_value_location.each do |value, enum_values_by_location|
-            value(value,
+            enum_value = value(value,
               value: value,
               description: builder.merge_descriptions(type_name, enum_values_by_location, enum_value: value),
               deprecation_reason: builder.merge_deprecations(type_name, enum_values_by_location, enum_value: value),
             )
+
+            builder.build_merged_directives(type_name, enum_values_by_location, enum_value, enum_value: value)
           end
         end
       end
@@ -170,6 +204,7 @@ module GraphQL
           end
 
           builder.build_merged_fields(type_name, types_by_location, self)
+          builder.build_merged_directives(type_name, types_by_location, self)
         end
       end
 
@@ -187,6 +222,7 @@ module GraphQL
           end
 
           builder.build_merged_fields(type_name, types_by_location, self)
+          builder.build_merged_directives(type_name, types_by_location, self)
         end
       end
 
@@ -199,6 +235,7 @@ module GraphQL
 
           possible_names = types_by_location.values.flat_map { _1.possible_types.map(&:graphql_name) }.uniq
           possible_types(*possible_names.map { builder.build_type_binding(_1) })
+          builder.build_merged_directives(type_name, types_by_location, self)
         end
       end
 
@@ -209,6 +246,7 @@ module GraphQL
           graphql_name(type_name)
           description(builder.merge_descriptions(type_name, types_by_location))
           builder.build_merged_arguments(type_name, types_by_location, self)
+          builder.build_merged_directives(type_name, types_by_location, self)
         end
       end
 
@@ -243,6 +281,7 @@ module GraphQL
           )
 
           build_merged_arguments(type_name, fields_by_location, schema_field, field_name: field_name)
+          build_merged_directives(type_name, fields_by_location, schema_field, field_name: field_name)
         end
       end
 
@@ -270,7 +309,7 @@ module GraphQL
           # Getting double args sometimes... why?
           return if owner.arguments.any? { _1.first == argument_name }
 
-          owner.argument(
+          schema_argument = owner.argument(
             argument_name,
             description: merge_descriptions(type_name, arguments_by_location, argument_name: argument_name, field_name: field_name),
             deprecation_reason: merge_deprecations(type_name, arguments_by_location, argument_name: argument_name, field_name: field_name),
@@ -278,6 +317,49 @@ module GraphQL
             required: value_types.any?(&:non_null?),
             camelize: false,
           )
+
+          build_merged_directives(type_name, arguments_by_location, schema_argument, field_name: field_name, argument_name: argument_name)
+        end
+      end
+
+      def build_merged_directives(type_name, members_by_location, owner, field_name: nil, argument_name: nil, enum_value: nil)
+        directives_by_name_location = members_by_location.each_with_object({}) do |(location, member_candidate), memo|
+          member_candidate.directives.each do |directive|
+            memo[directive.graphql_name] ||= {}
+            memo[directive.graphql_name][location] ||= {}
+            memo[directive.graphql_name][location] = directive
+          end
+        end
+
+        directives_by_name_location.each do |directive_name, directives_by_location|
+          directive_class = @schema_directives[directive_name]
+          next unless directive_class
+
+          # handled by deprecation_reason merger...
+          next if directive_class.graphql_name == "deprecated"
+
+          kwarg_values_by_name_location = directives_by_location.each_with_object({}) do |(location, directive), memo|
+            directive.arguments.keyword_arguments.each do |key, value|
+              key = key.to_s
+              next unless directive_class.arguments[key]
+
+              memo[key] ||= {}
+              memo[key][location] = value
+            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, {
+              type_name: type_name,
+              field_name: field_name,
+              argument_name: argument_name,
+              enum_value: enum_value,
+              directive_name: directive_name,
+              kwarg_name: kwarg_name,
+            }.compact!)
+          end
+
+          owner.directive(directive_class, **kwargs)
         end
       end
 

data/lib/graphql/stitching/executor.rb

@@ -7,16 +7,17 @@ module GraphQL
     class Executor
 
       class RootSource < GraphQL::Dataloader::Source
-        def initialize(executor)
+        def initialize(executor, location)
           @executor = executor
+          @location = location
         end
 
         def fetch(ops)
           op = ops.first # There should only ever be one per location at a time
 
           query_document = build_query(op)
-          query_variables = @executor.variables.slice(*op["variables"].keys)
-          result = @executor.supergraph.execute_at_location(op["location"], query_document, query_variables)
+          query_variables = @executor.request.variables.slice(*op["variables"].keys)
+          result = @executor.supergraph.execute_at_location(op["location"], query_document, query_variables, @executor.request.context)
           @executor.query_count += 1
 
           @executor.data.merge!(result["data"]) if result["data"]
@@ -24,7 +25,8 @@ module GraphQL
             result["errors"].each { _1.delete("locations") }
             @executor.errors.concat(result["errors"])
           end
-          op["key"]
+
+          ops.map { op["key"] }
         end
 
         def build_query(op)
@@ -61,8 +63,8 @@ module GraphQL
 
           if origin_sets_by_operation.any?
             query_document, variable_names = build_query(origin_sets_by_operation)
-            variables = @executor.variables.slice(*variable_names)
-            raw_result = @executor.supergraph.execute_at_location(@location, query_document, variables)
+            variables = @executor.request.variables.slice(*variable_names)
+            raw_result = @executor.supergraph.execute_at_location(@location, query_document, variables, @executor.request.context)
             @executor.query_count += 1
 
             merge_results!(origin_sets_by_operation, raw_result.dig("data"))
@@ -165,23 +167,26 @@ module GraphQL
 
         private
 
-        # traverses forward through origin data, expanding arrays to follow all paths
+        # traverse forward through origin data, expanding arrays to follow all paths
         # any errors found for an origin object_id have their path prefixed by the object path
         def repath_errors!(pathed_errors_by_object_id, forward_path, current_path=[], root=@executor.data)
-          current_path << forward_path.first
-          forward_path = forward_path[1..-1]
+          current_path.push(forward_path.shift)
           scope = root[current_path.last]
 
           if forward_path.any? && scope.is_a?(Array)
             scope.each_with_index do |element, index|
               inner_elements = element.is_a?(Array) ? element.flatten : [element]
               inner_elements.each do |inner_element|
-                repath_errors!(pathed_errors_by_object_id, forward_path, [*current_path, index], inner_element)
+                current_path << index
+                repath_errors!(pathed_errors_by_object_id, forward_path, current_path, inner_element)
+                current_path.pop
               end
             end
 
           elsif forward_path.any?
-            repath_errors!(pathed_errors_by_object_id, forward_path, [*current_path, index], scope)
+            current_path << index
+            repath_errors!(pathed_errors_by_object_id, forward_path, current_path, scope)
+            current_path.pop
 
           elsif scope.is_a?(Array)
             scope.each_with_index do |element, index|
@@ -196,61 +201,72 @@ module GraphQL
             errors = pathed_errors_by_object_id[scope.object_id]
             errors.each { _1["path"] = [*current_path, *_1["path"]] } if errors
           end
+
+          forward_path.unshift(current_path.pop)
         end
       end
 
-      attr_reader :supergraph, :data, :errors, :variables
+      attr_reader :supergraph, :request, :data, :errors
       attr_accessor :query_count
 
-      def initialize(supergraph:, plan:, variables: {}, nonblocking: false)
+      def initialize(supergraph:, request:, plan:, nonblocking: false)
         @supergraph = supergraph
-        @variables = variables
+        @request = request
         @queue = plan["ops"]
         @data = {}
         @errors = []
         @query_count = 0
+        @exec_cycles = 0
         @dataloader = GraphQL::Dataloader.new(nonblocking: nonblocking)
       end
 
-      def perform(document=nil)
+      def perform(raw: false)
         exec!
-
         result = {}
-        result["data"] = @data if @data && @data.length > 0
-        result["errors"] = @errors if @errors.length > 0
 
-        if document && result["data"]
-          GraphQL::Stitching::Shaper.new(
+        if @data && @data.length > 0
+          result["data"] = raw ? @data : GraphQL::Stitching::Shaper.new(
             schema: @supergraph.schema,
-            document: document,
-          ).perform!(result)
-        else
-          result
+            request: @request,
+          ).perform!(@data)
         end
+
+        if @errors.length > 0
+          result["errors"] = @errors
+        end
+
+        result
       end
 
       private
 
       def exec!(after_keys = [0])
+        if @exec_cycles > @queue.length
+          # sanity check... if we've exceeded queue size, then something went wrong.
+          raise StitchingError, "Too many execution requests attempted."
+        end
+
         @dataloader.append_job do
-          requests = @queue
+          tasks = @queue
             .select { after_keys.include?(_1["after_key"]) }
-            .group_by { _1["location"] }
-            .map do |location, ops|
-              if ops.first["after_key"].zero?
-                @dataloader.with(RootSource, self).request_all(ops)
+            .group_by { [_1["location"], _1["boundary"].nil?] }
+            .map do |(location, root_source), ops|
+              if root_source
+                @dataloader.with(RootSource, self, location).request_all(ops)
               else
                 @dataloader.with(BoundarySource, self, location).request_all(ops)
               end
             end
 
-          requests.each(&method(:exec_request))
+          tasks.each(&method(:exec_task))
         end
+
+        @exec_cycles += 1
         @dataloader.run
       end
 
-      def exec_request(request)
-        next_keys = request.load
+      def exec_task(task)
+        next_keys = task.load
         next_keys.compact!
         exec!(next_keys) if next_keys.any?
       end

data/lib/graphql/stitching/gateway.rb

@@ -7,8 +7,6 @@ module GraphQL
     class Gateway
       class GatewayError < StitchingError; end
 
-      EMPTY_CONTEXT = {}.freeze
-
       attr_reader :supergraph
 
       def initialize(locations: nil, supergraph: nil)
@@ -25,29 +23,36 @@ module GraphQL
         end
       end
 
-      def execute(query:, variables: nil, operation_name: nil, context: EMPTY_CONTEXT, validate: true)
-        document = GraphQL::Stitching::Document.new(query, operation_name: operation_name)
+      def execute(query:, variables: nil, operation_name: nil, context: nil, validate: true)
+        request = GraphQL::Stitching::Request.new(
+          query,
+          operation_name: operation_name,
+          variables: variables,
+          context: context,
+        )
 
         if validate
-          validation_errors = @supergraph.schema.validate(document.ast)
+          validation_errors = @supergraph.schema.validate(request.document)
           return error_result(validation_errors) if validation_errors.any?
         end
 
+        request.prepare!
+
         begin
-          plan = fetch_plan(document, context) do
+          plan = fetch_plan(request) do
             GraphQL::Stitching::Planner.new(
               supergraph: @supergraph,
-              document: document,
+              request: request,
             ).perform.to_h
           end
 
           GraphQL::Stitching::Executor.new(
             supergraph: @supergraph,
+            request: request,
             plan: plan,
-            variables: variables || {},
-          ).perform(document)
+          ).perform
         rescue StandardError => e
-          custom_message = @on_error.call(e, context) if @on_error
+          custom_message = @on_error.call(e, request.context) if @on_error
           error_result([{ "message" => custom_message || "An unexpected error occured." }])
         end
       end
@@ -91,16 +96,16 @@ module GraphQL
         supergraph
       end
 
-      def fetch_plan(document, context)
+      def fetch_plan(request)
         if @on_cache_read
-          cached_plan = @on_cache_read.call(document.digest, context)
+          cached_plan = @on_cache_read.call(request.digest, request.context)
           return JSON.parse(cached_plan) if cached_plan
         end
 
         plan_json = yield
 
         if @on_cache_write
-          @on_cache_write.call(document.digest, JSON.generate(plan_json), context)
+          @on_cache_write.call(request.digest, JSON.generate(plan_json), request.context)
         end
 
         plan_json

data/lib/graphql/stitching/planner.rb

@@ -6,9 +6,9 @@ module GraphQL
       SUPERGRAPH_LOCATIONS = [Supergraph::LOCATION].freeze
       TYPENAME_NODE = GraphQL::Language::Nodes::Field.new(alias: "_STITCH_typename", name: "__typename")
 
-      def initialize(supergraph:, document:)
+      def initialize(supergraph:, request:)
         @supergraph = supergraph
-        @document = document
+        @request = request
         @sequence_key = 0
         @operations_by_grouping = {}
       end
@@ -37,7 +37,11 @@ module GraphQL
           extract_locale_selections(location, parent_type, selections, insertion_path, parent_key)
         end
 
-        grouping = [after_key, location, parent_type.graphql_name, *insertion_path].join("/")
+        grouping = String.new
+        grouping << after_key.to_s << "/" << location << "/" << parent_type.graphql_name
+        grouping = insertion_path.reduce(grouping) do |memo, segment|
+          memo << "/" << segment
+        end
 
         if op = @operations_by_grouping[grouping]
           op.selections += selection_set if selection_set
@@ -62,12 +66,12 @@ module GraphQL
       end
 
       def build_root_operations
-        case @document.operation.operation_type
+        case @request.operation.operation_type
         when "query"
           # plan steps grouping all fields by location for async execution
           parent_type = @supergraph.schema.query
 
-          selections_by_location = @document.operation.selections.each_with_object({}) do |node, memo|
+          selections_by_location = @request.operation.selections.each_with_object({}) do |node, memo|
             locations = @supergraph.locations_by_type_and_field[parent_type.graphql_name][node.name] || SUPERGRAPH_LOCATIONS
             memo[locations.last] ||= []
             memo[locations.last] << node
@@ -82,7 +86,7 @@ module GraphQL
           parent_type = @supergraph.schema.mutation
           location_groups = []
 
-          @document.operation.selections.reduce(nil) do |last_location, node|
+          @request.operation.selections.reduce(nil) do |last_location, node|
             location = @supergraph.locations_by_type_and_field[parent_type.graphql_name][node.name].last
             if location != last_location
               location_groups << {
@@ -161,8 +165,10 @@ module GraphQL
             if Util.is_leaf_type?(field_type)
               selections_result << node
             else
-              expanded_path = [*insertion_path, node.alias || node.name]
-              selection_set, variables = extract_locale_selections(current_location, field_type, node.selections, expanded_path, after_key)
+              insertion_path.push(node.alias || node.name)
+              selection_set, variables = extract_locale_selections(current_location, field_type, node.selections, insertion_path, after_key)
+              insertion_path.pop
+
               selections_result << node.merge(selections: selection_set)
               variables_result.merge!(variables)
             end
@@ -177,7 +183,7 @@ module GraphQL
             implements_fragments = true
 
           when GraphQL::Language::Nodes::FragmentSpread
-            fragment = @document.fragment_definitions[node.name]
+            fragment = @request.fragment_definitions[node.name]
             next unless @supergraph.locations_by_type[fragment.type.name].include?(current_location)
 
             fragment_type = @supergraph.schema.types[fragment.type.name]
@@ -260,7 +266,7 @@ module GraphQL
               location: location,
               selections: selections_by_location[location],
               parent_type: parent_type,
-              insertion_path: insertion_path,
+              insertion_path: insertion_path.dup,
               boundary: boundary,
               after_key: after_key,
             )
@@ -289,7 +295,7 @@ module GraphQL
           when GraphQL::Language::Nodes::InputObject
             extract_node_variables!(argument.value, memo)
           when GraphQL::Language::Nodes::VariableIdentifier
-            memo[argument.value.name] ||= @document.variable_definitions[argument.value.name]
+            memo[argument.value.name] ||= @request.variable_definitions[argument.value.name]
           end
         end
       end

data/lib/graphql/stitching/remote_client.rb

@@ -9,14 +9,14 @@ module GraphQL
     class RemoteClient
       def initialize(url:, headers:{})
         @url = url
-        @headers = headers
+        @headers = { "Content-Type" => "application/json" }.merge!(headers)
       end
 
-      def call(location, document, variables)
+      def call(_location, document, variables, _context)
         response = Net::HTTP.post(
           URI(@url),
-          { "query" => document, "variables" => variables }.to_json,
-          { "Content-Type" => "application/json" }.merge!(@headers)
+          JSON.generate({ "query" => document, "variables" => variables }),
+          @headers,
         )
         JSON.parse(response.body)
       end

data/lib/graphql/stitching/request.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Stitching
+    class Request
+      SUPPORTED_OPERATIONS = ["query", "mutation"].freeze
+      EMPTY_CONTEXT = {}.freeze
+
+      class ApplyRuntimeDirectives < GraphQL::Language::Visitor
+        def initialize(document, variables)
+          @changed = false
+          @variables = variables
+          super(document)
+        end
+
+        def changed?
+          @changed
+        end
+
+        def on_field(node, parent)
+          delete_node = false
+          filtered_directives = if node.directives.any?
+            node.directives.select do |directive|
+              if directive.name == "skip"
+                delete_node = assess_argument_value(directive.arguments.first)
+                false
+              elsif directive.name == "include"
+                delete_node = !assess_argument_value(directive.arguments.first)
+                false
+              else
+                true
+              end
+            end
+          end
+
+          if delete_node
+            @changed = true
+            super(DELETE_NODE, parent)
+          elsif filtered_directives && filtered_directives.length != node.directives.length
+            @changed = true
+            super(node.merge(directives: filtered_directives), parent)
+          else
+            super
+          end
+        end
+
+        private
+
+        def assess_argument_value(arg)
+          if arg.value.is_a?(GraphQL::Language::Nodes::VariableIdentifier)
+            return @variables[arg.value.name]
+          end
+          arg.value
+        end
+      end
+
+      attr_reader :document, :variables, :operation_name, :context
+
+      def initialize(document, operation_name: nil, variables: nil, context: nil)
+        @may_contain_runtime_directives = true
+
+        @document = if document.is_a?(String)
+          @may_contain_runtime_directives = document.include?("@")
+          GraphQL.parse(document)
+        else
+          document
+        end
+
+        @operation_name = operation_name
+        @variables = variables || {}
+        @context = context || EMPTY_CONTEXT
+      end
+
+      def string
+        @string ||= @document.to_query_string
+      end
+
+      def digest
+        @digest ||= Digest::SHA2.hexdigest(string)
+      end
+
+      def operation
+        @operation ||= begin
+          operation_defs = @document.definitions.select do |d|
+            next unless d.is_a?(GraphQL::Language::Nodes::OperationDefinition)
+            next unless SUPPORTED_OPERATIONS.include?(d.operation_type)
+            @operation_name ? d.name == @operation_name : true
+          end
+
+          if operation_defs.length < 1
+            raise GraphQL::ExecutionError, "Invalid root operation."
+          elsif operation_defs.length > 1
+            raise GraphQL::ExecutionError, "An operation name is required when sending multiple operations."
+          end
+
+          operation_defs.first
+        end
+      end
+
+      def variable_definitions
+        @variable_definitions ||= operation.variables.each_with_object({}) do |v, memo|
+          memo[v.name] = v.type
+        end
+      end
+
+      def fragment_definitions
+        @fragment_definitions ||= @document.definitions.each_with_object({}) do |d, memo|
+          memo[d.name] = d if d.is_a?(GraphQL::Language::Nodes::FragmentDefinition)
+        end
+      end
+
+      def prepare!
+        operation.variables.each do |v|
+          @variables[v.name] ||= v.default_value
+        end
+
+        return self unless @may_contain_runtime_directives
+
+        visitor = ApplyRuntimeDirectives.new(@document, @variables)
+        @document = visitor.visit
+
+        if visitor.changed?
+          @string = nil
+          @digest = nil
+          @operation = nil
+          @variable_definitions = nil
+          @fragment_definitions = nil
+        end
+        self
+      end
+    end
+  end
+end

data/lib/graphql/stitching/shaper.rb

@@ -4,14 +4,14 @@
 module GraphQL
   module Stitching
     class Shaper
-      def initialize(schema:, document:)
+      def initialize(schema:, request:)
         @schema = schema
-        @document = document
+        @request = request
       end
 
       def perform!(raw)
-        raw["data"] = resolve_object_scope(raw["data"], @schema.query, @document.operation.selections)
-        raw
+        root_type = @schema.public_send(@request.operation.operation_type)
+        resolve_object_scope(raw, root_type, @request.operation.selections)
       end
 
       private
@@ -48,7 +48,7 @@ module GraphQL
             return nil if result.nil?
 
           when GraphQL::Language::Nodes::FragmentSpread
-            fragment = @document.fragment_definitions[node.name]
+            fragment = @request.fragment_definitions[node.name]
             fragment_type = @schema.types[fragment.type.name]
             next unless typename == fragment_type.graphql_name
 

data/lib/graphql/stitching/supergraph.rb

@@ -57,27 +57,28 @@ module GraphQL
       def assign_executable(location, executable = nil, &block)
         executable ||= block
         unless executable.is_a?(Class) && executable <= GraphQL::Schema
-          raise "A client or block handler must be provided." unless executable
-          raise "A client must be callable" unless executable.respond_to?(:call)
+          raise StitchingError, "A client or block handler must be provided." unless executable
+          raise StitchingError, "A client must be callable" unless executable.respond_to?(:call)
         end
         @executables[location] = executable
       end
 
-      def execute_at_location(location, query, variables)
+      def execute_at_location(location, query, variables, context)
         executable = executables[location]
 
         if executable.nil?
-          raise "No executable assigned for #{location} location."
+          raise StitchingError, "No executable assigned for #{location} location."
         elsif executable.is_a?(Class) && executable <= GraphQL::Schema
           executable.execute(
             query: query,
             variables: variables,
+            context: context,
             validate: false,
           )
         elsif executable.respond_to?(:call)
-          executable.call(location, query, variables)
+          executable.call(location, query, variables, context)
         else
-          raise "Missing valid executable for #{location} location."
+          raise StitchingError, "Missing valid executable for #{location} location."
         end
       end
 

data/lib/graphql/stitching/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Stitching
-    VERSION = "0.1.0"
+    VERSION = "0.2.1"
   end
 end

data/lib/graphql/stitching.rb

@@ -13,6 +13,10 @@ module GraphQL
       end
 
       attr_writer :stitch_directive
+
+      def stitching_directive_names
+        [stitch_directive]
+      end
     end
   end
 end
@@ -20,11 +24,11 @@ end
 require_relative "stitching/gateway"
 require_relative "stitching/supergraph"
 require_relative "stitching/composer"
-require_relative "stitching/document"
 require_relative "stitching/executor"
 require_relative "stitching/planner_operation"
 require_relative "stitching/planner"
 require_relative "stitching/remote_client"
+require_relative "stitching/request"
 require_relative "stitching/shaper"
 require_relative "stitching/util"
 require_relative "stitching/version"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-stitching
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-02-11 00:00:00.000000000 Z
+date: 2023-02-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -81,13 +81,13 @@ files:
 - Rakefile
 - docs/README.md
 - docs/composer.md
-- docs/document.md
 - docs/executor.md
 - docs/gateway.md
 - docs/images/library.png
 - docs/images/merging.png
 - docs/images/stitching.png
 - docs/planner.md
+- docs/request.md
 - docs/supergraph.md
 - example/gateway.rb
 - example/graphiql.html
@@ -99,12 +99,12 @@ files:
 - lib/graphql/stitching/composer/base_validator.rb
 - lib/graphql/stitching/composer/validate_boundaries.rb
 - lib/graphql/stitching/composer/validate_interfaces.rb
-- lib/graphql/stitching/document.rb
 - lib/graphql/stitching/executor.rb
 - lib/graphql/stitching/gateway.rb
 - lib/graphql/stitching/planner.rb
 - lib/graphql/stitching/planner_operation.rb
 - lib/graphql/stitching/remote_client.rb
+- lib/graphql/stitching/request.rb
 - lib/graphql/stitching/shaper.rb
 - lib/graphql/stitching/supergraph.rb
 - lib/graphql/stitching/util.rb

data/docs/document.md

@@ -1,15 +0,0 @@
-## GraphQL::Stitching::Document
-
-A `Document` wraps a parsed GraphQL request, and handles the logistics of extracting its appropriate operation, variable definitions, and fragments. A `Document` should be built once for a request and passed through to other stitching components that utilize document information.
-
-```ruby
-query = "query FetchMovie($id: ID!) { movie(id:$id) { id genre } }"
-document = GraphQL::Stitching::Document.new(query, operation_name: "FetchMovie")
-
-document.ast # parsed AST via GraphQL.parse
-document.string # normalized printed string
-document.digest # SHA digest of the normalized string
-
-document.variables # mapping of variable names to type definitions
-document.fragments # mapping of fragment names to fragment definitions
-```

data/lib/graphql/stitching/document.rb

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-module GraphQL
-  module Stitching
-    class Document
-      SUPPORTED_OPERATIONS = ["query", "mutation"].freeze
-
-      attr_reader :ast, :operation_name
-
-      def initialize(string_or_ast, operation_name: nil)
-        @ast = if string_or_ast.is_a?(String)
-          GraphQL.parse(string_or_ast)
-        else
-          string_or_ast
-        end
-
-        @operation_name = operation_name
-      end
-
-      def string
-        @string ||= GraphQL::Language::Printer.new.print(@ast)
-      end
-
-      def digest
-        @digest ||= Digest::SHA2.hexdigest(string)
-      end
-
-      def operation
-        @operation ||= begin
-          operation_defs = @ast.definitions.select do |d|
-            next unless d.is_a?(GraphQL::Language::Nodes::OperationDefinition)
-            next unless SUPPORTED_OPERATIONS.include?(d.operation_type)
-            @operation_name ? d.name == @operation_name : true
-          end
-
-          if operation_defs.length < 1
-            raise GraphQL::ExecutionError, "Invalid root operation."
-          elsif operation_defs.length > 1
-            raise GraphQL::ExecutionError, "An operation name is required when sending multiple operations."
-          end
-
-          operation_defs.first
-        end
-      end
-
-      def variable_definitions
-        @variable_definitions ||= operation.variables.each_with_object({}) do |v, memo|
-          memo[v.name] = v.type
-        end
-      end
-
-      def fragment_definitions
-        @fragment_definitions ||= @ast.definitions.each_with_object({}) do |d, memo|
-          memo[d.name] = d if d.is_a?(GraphQL::Language::Nodes::FragmentDefinition)
-        end
-      end
-    end
-  end
-end