graphql-stitching 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66c85693da3a07eb7b3ab81fe76b69ce095aaffa8b9cab68a1f34b86e20963ba
-  data.tar.gz: f1e8bbbe3ffdaf23189f219cad6fe604203527e12911a0609fb1711375effe58
+  metadata.gz: 9cdcb3361e391ba9b6dd78aa38c308c08ddb6fde2720d15208e8dfb96c3006ea
+  data.tar.gz: 9f64b024bda3987d1c523cf52b49f0ca2dfd688ac4c89bbf18de30c88c098156
 SHA512:
-  metadata.gz: a86ac6f20dda8dc5ae68d548d85d9c4482856c56e86a07cee9ff5689ba95cf73f19dadd80d6f711a55a0b9e25796522b1b1feb4c7d70f7fa499a0f38beb0d24a
-  data.tar.gz: 61b2d6f21dc8001fab5e6d8c27d3cc04582fc506daa17f45354475cb9ef6812a355ec5819257d9d582d7f4a312b85b10b539322e3fa14b73a255376a75687658
+  metadata.gz: b51bcfeaa20e9cdea6c2d4b4e472e8c23e13ec8af36e1b23852603d0329045af064e3ae738467a0823be0c9f545105acba001b708c207eb7f08d51ebf0791e1f
+  data.tar.gz: c529e74c88fc7193d7823d8c92a488b3e459b5ba9f88e8d62355ae2bd5e9eb0ed2b0d6f7fd14b6b8ed13ab1bb53a93bc5da49dcecd5deb92ee180fa70604c80b

data/.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
             ruby: 3.2
           - gemfile: Gemfile
             ruby: 3.1
-          - gemfile: gemfiles/graphql_1.13.gemfile
+          - gemfile: gemfiles/graphql_1.13.9.gemfile
             ruby: 3.1
           - gemfile: Gemfile
             ruby: 2.7
@@ -30,6 +30,6 @@ jobs:
         bundler-cache: true # runs 'bundle install' and caches installed gems automatically
     - name: Run tests
       run: |
-        gem install bundler
+        gem install bundler -v 2.4.22
         bundle install --jobs 4 --retry 3
         bundle exec rake test

data/README.md

@@ -113,12 +113,12 @@ products_schema = <<~GRAPHQL
   }
 GRAPHQL
 
-shipping_schema = <<~GRAPHQL
+catalog_schema = <<~GRAPHQL
   directive @stitch(key: String!) repeatable on FIELD_DEFINITION
 
   type Product {
     id: ID!
-    weight: Float!
+    price: Float!
   }
 
   type Query {
@@ -131,7 +131,7 @@ client = GraphQL::Stitching::Client.new(locations: {
     schema: GraphQL::Schema.from_definition(products_schema),
     executable:  GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3001"),
   },
-  shipping: {
+  catalog: {
     schema: GraphQL::Schema.from_definition(shipping_schema),
     executable:  GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3002"),
   },
@@ -151,9 +151,9 @@ type Query {
 ```
 
 * 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).
+* 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](#multiple-query-arguments) later).
 
-Each location that provides a unique variant of a type must provide one stitching query per key. The exception to this requirement are types that contain only a single key field:
+Each location that provides a unique variant of a type must provide at least one stitching query. The exception to this requirement are types that contain only a single key field:
 
 ```graphql
 type Product {
@@ -165,7 +165,7 @@ The above representation of a `Product` type provides no unique data beyond a ke
 
 #### List queries
 
-It's okay ([even preferable](https://www.youtube.com/watch?v=VmK0KBHTcWs) in many circumstances) to provide a list accessor as a stitching query. The only requirement is that both the field argument and return type must be lists, and the query results are expected to be a mapped set with `null` holding the position of missing results.
+It's okay ([even preferable](#batching) in most circumstances) to provide a list accessor as a stitching query. The only requirement is that both the field argument and return type must be lists, and the query results are expected to be a mapped set with `null` holding the position of missing results.
 
 ```graphql
 type Query {
@@ -228,7 +228,7 @@ type Query {
 }
 ```
 
-The `@stitch` directive is also repeatable (_requires graphql-ruby >= v2.0.15_), allowing a single query to associate with multiple keys:
+The `@stitch` directive is also repeatable, allowing a single query to associate with multiple keys:
 
 ```graphql
 type Product {
@@ -311,16 +311,15 @@ The [Apollo Federation specification](https://www.apollographql.com/docs/federat
 The composer will automatcially detect and stitch schemas with an `_entities` query, for example:
 
 ```ruby
-accounts_schema = <<~GRAPHQL
+products_schema = <<~GRAPHQL
   directive @key(fields: String!) repeatable on OBJECT
 
-  type User @key(fields: "id") {
+  type Product @key(fields: "id") {
     id: ID!
     name: String!
-    address: String!
   }
 
-  union _Entity = User
+  union _Entity = Product
   scalar _Any
 
   type Query {
@@ -329,15 +328,15 @@ accounts_schema = <<~GRAPHQL
   }
 GRAPHQL
 
-comments_schema = <<~GRAPHQL
+catalog_schema = <<~GRAPHQL
   directive @key(fields: String!) repeatable on OBJECT
 
-  type User @key(fields: "id") {
+  type Product @key(fields: "id") {
     id: ID!
-    comments: [String!]!
+    price: Float!
   }
 
-  union _Entity = User
+  union _Entity = Product
   scalar _Any
 
   type Query {
@@ -346,12 +345,12 @@ comments_schema = <<~GRAPHQL
 GRAPHQL
 
 client = GraphQL::Stitching::Client.new(locations: {
-  accounts: {
-    schema: GraphQL::Schema.from_definition(accounts_schema),
+  products: {
+    schema: GraphQL::Schema.from_definition(products_schema),
     executable: ...,
   },
-  comments: {
-    schema: GraphQL::Schema.from_definition(comments_schema),
+  catalog: {
+    schema: GraphQL::Schema.from_definition(catalog_schema),
     executable: ...,
   },
 })
@@ -426,6 +425,7 @@ The [Executor](./docs/executor.md) component builds atop the Ruby fiber-based im
 
 ## Additional topics
 
+- [Deploying a stitched schema](./docs/mechanics.md#deploying-a-stitched-schema)
 - [Field selection routing](./docs/mechanics.md#field-selection-routing)
 - [Root selection routing](./docs/mechanics.md#root-selection-routing)
 - [Stitched errors](./docs/mechanics.md#stitched-errors)

data/docs/executor.md

@@ -16,6 +16,7 @@ request = GraphQL::Stitching::Request.new(
   query,
   variables: { "id" => "123" },
   operation_name: "MyQuery",
+  context: { ... },
 )
 
 plan = GraphQL::Stitching::Planner.new(
@@ -26,7 +27,7 @@ plan = GraphQL::Stitching::Planner.new(
 result = GraphQL::Stitching::Executor.new(
   supergraph: supergraph,
   request: request,
-  plan: plan.to_h,
+  plan: plan,
 ).perform
 ```
 
@@ -39,7 +40,7 @@ By default, execution results are always returned with document shaping (stitchi
 raw_result = GraphQL::Stitching::Executor.new(
   supergraph: supergraph,
   request: request,
-  plan: plan.to_h,
+  plan: plan,
 ).perform(raw: true)
 ```
 

data/docs/mechanics.md

@@ -1,5 +1,59 @@
 ## Schema Stitching, mechanics
 
+### Deploying a stitched schema
+
+Among the simplest and most effective ways to manage a stitched schema is to compose it locally, write the composed SDL as a `.graphql` file in your repo, and then load the composed schema into a stitching client at runtime. For example, setup a `rake` task that loads/fetches subgraph schemas, composes them, and then writes the composed schema definition as a file committed to the repo:
+
+```ruby
+task :compose_graphql do
+  schema1_sdl = ... # load schema 1
+  schema2_sdl = ... # load schema 2
+
+  supergraph = GraphQL::Stitching::Composer.new.perform({
+    schema1: {
+      schema: GraphQL::Schema.from_definition(schema1_sdl)
+    },
+    schema2: {
+      schema: GraphQL::Schema.from_definition(schema2_sdl)
+    }
+  })
+
+  File.write("schema/supergraph.graphql", supergraph.to_definition)
+  puts "Schema composition was successful."
+end
+
+# bundle exec rake compose-graphql
+```
+
+Then at runtime, load the composed schema into a stitching client:
+
+```ruby
+class GraphQlController
+  class < self
+    def client
+      @client ||= begin
+        supergraph_sdl = File.read("schema/supergraph.graphql")
+        supergraph = GraphQL::Stitching::Supergraph.from_definition(supergraph_sdl, executables: {
+          schema1: GraphQL::Stitching::HttpExecutable.new("http://localhost:3001/graphql"),
+          schema2: GraphQL::Stitching::HttpExecutable.new("http://localhost:3002/graphql"),
+        })
+        GraphQL::Stitching::Client.new(supergraph: supergraph)
+      end
+    end
+  end
+
+  def exec
+    self.class.client.execute(
+      params[:query],
+      variables: params[:variables],
+      operation_name: params[:operation_name]
+    )
+  end 
+end
+```
+
+This process assures that composition always happens before deployment where failures can be detected. Hot reloading of the supergraph can also be accommodated by uploading the composed schema to a sync location (cloud storage, etc) that is polled by the application runtime. When the schema changes, load it into a new stitching client and swap that into the application.
+
 ### Field selection routing
 
 Fields of a merged type may exist in multiple locations. For example, the `title` field below is provided by both locations:

data/docs/planner.md

@@ -32,15 +32,15 @@ Plans are designed to be cacheable. This is very useful for redundant GraphQL do
 cached_plan = $redis.get(request.digest)
 
 plan = if cached_plan
-  JSON.parse(cached_plan)
+  GraphQL::Stitching::Plan.from_json(JSON.parse(cached_plan))
 else
-  plan_hash = GraphQL::Stitching::Planner.new(
+  plan = GraphQL::Stitching::Planner.new(
     supergraph: supergraph,
     request: request,
-  ).perform.to_h
+  ).perform
 
-  $redis.set(request.digest, JSON.generate(plan_hash))
-  plan_hash
+  $redis.set(request.digest, JSON.generate(plan.as_json))
+  plan
 end
 
 # execute the plan...

data/docs/request.md

@@ -4,7 +4,12 @@ A `Request` contains a parsed GraphQL document and variables, and handles the lo
 
 ```ruby
 source = "query FetchMovie($id: ID!) { movie(id:$id) { id genre } }"
-request = GraphQL::Stitching::Request.new(source, variables: { "id" => "1" }, operation_name: "FetchMovie")
+request = GraphQL::Stitching::Request.new(
+  source,
+  variables: { "id" => "1" },
+  operation_name: "FetchMovie",
+  context: { ... },
+)
 ```
 
 A `Request` provides the following information:

data/lib/graphql/stitching/client.rb

@@ -20,6 +20,10 @@ module GraphQL
           composer ||= GraphQL::Stitching::Composer.new
           composer.perform(locations)
         end
+
+        @on_cache_read = nil
+        @on_cache_write = nil
+        @on_error = nil
       end
 
       def execute(query:, variables: nil, operation_name: nil, context: nil, validate: true)

data/lib/graphql/stitching/composer.rb

@@ -39,6 +39,12 @@ module GraphQL
         @directive_kwarg_merger = directive_kwarg_merger || BASIC_VALUE_MERGER
         @root_field_location_selector = root_field_location_selector || BASIC_ROOT_FIELD_LOCATION_SELECTOR
         @stitch_directives = {}
+
+        @field_map = nil
+        @boundary_map = nil
+        @mapped_type_names = nil
+        @candidate_directives_by_name_and_location = nil
+        @schema_directives = nil
       end
 
       def perform(locations_input)

data/lib/graphql/stitching/export_selection.rb

@@ -8,6 +8,8 @@ module GraphQL
       EXPORT_PREFIX = "_export_"
 
       class << self
+        @typename_node = nil
+
         def key?(name)
           return false unless name
 
@@ -19,7 +21,11 @@ module GraphQL
         end
 
         def key_node(field_name)
-          GraphQL::Language::Nodes::Field.new(alias: key(field_name), name: field_name)
+          if Util.graphql_version?(2, 2)
+            GraphQL::Language::Nodes::Field.new(field_alias: key(field_name), name: field_name)
+          else
+            GraphQL::Language::Nodes::Field.new(alias: key(field_name), name: field_name)
+          end
         end
 
         def typename_node

data/lib/graphql/stitching/request.rb

@@ -9,6 +9,15 @@ module GraphQL
       attr_reader :document, :variables, :operation_name, :context
 
       def initialize(document, operation_name: nil, variables: nil, context: nil)
+        @string = nil
+        @digest = nil
+        @normalized_string = nil
+        @normalized_digest = nil
+        @operation = nil
+        @operation_directives = nil
+        @variable_definitions = nil
+        @fragment_definitions = nil
+
         @document = if document.is_a?(String)
           @string = document
           GraphQL.parse(document)

data/lib/graphql/stitching/shaper.rb

@@ -9,6 +9,7 @@ module GraphQL
       def initialize(supergraph:, request:)
         @supergraph = supergraph
         @request = request
+        @root_type = nil
       end
 
       def perform!(raw)

data/lib/graphql/stitching/supergraph.rb

@@ -97,6 +97,10 @@ module GraphQL
         @possible_keys_by_type_and_location = {}
         @memoized_schema_possible_types = {}
         @memoized_schema_fields = {}
+        @memoized_introspection_types = nil
+        @memoized_schema_types = nil
+        @fields_by_type_and_location = nil
+        @locations_by_type = nil
 
         # add introspection types into the fields mapping
         @locations_by_type_and_field = memoized_introspection_types.each_with_object(fields) do |(type_name, type), memo|

data/lib/graphql/stitching/util.rb

@@ -12,7 +12,16 @@ module GraphQL
         end
       end
 
+      GRAPHQL_VERSION = GraphQL::VERSION.split(".").map(&:to_i).freeze
+
       class << self
+        def graphql_version?(major, minor = nil, patch = nil)
+          result = GRAPHQL_VERSION[0] >= major
+          result &&= GRAPHQL_VERSION[1] >= minor if minor
+          result &&= GRAPHQL_VERSION[2] >= patch if patch
+          result
+        end
+
         # specifies if a type is a primitive leaf value
         def is_leaf_type?(type)
           type.kind.scalar? || type.kind.enum?

data/lib/graphql/stitching/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Stitching
-    VERSION = "1.1.0"
+    VERSION = "1.1.1"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-stitching
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-12-02 00:00:00.000000000 Z
+date: 2023-12-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql