graphql-stitching 0.3.6 → 1.0.1

data/lib/graphql/stitching/supergraph.rb

@@ -21,10 +21,14 @@ module GraphQL
           end
         end
 
+        boundaries = delegation_map["boundaries"].map do |k, b|
+          [k, b.map { Boundary.new(**_1) }]
+        end
+
         new(
           schema: schema,
           fields: delegation_map["fields"],
-          boundaries: delegation_map["boundaries"],
+          boundaries: boundaries.to_h,
           executables: executables,
         )
       end
@@ -68,7 +72,7 @@ module GraphQL
         return GraphQL::Schema::Printer.print_schema(@schema), {
           "locations" => locations,
           "fields" => fields,
-          "boundaries" => @boundaries,
+          "boundaries" => @boundaries.map { |k, b| [k, b.map(&:as_json)] }.to_h,
         }
       end
 
@@ -144,7 +148,7 @@ module GraphQL
       # ("Type") => ["id", ...]
       def possible_keys_for_type(type_name)
         @possible_keys_by_type[type_name] ||= begin
-          @boundaries[type_name].map { _1["key"] }.tap(&:uniq!)
+          @boundaries[type_name].map(&:key).tap(&:uniq!)
         end
       end
 
@@ -162,74 +166,76 @@ module GraphQL
       # used to connect a partial type across locations via boundary queries
       def route_type_to_locations(type_name, start_location, goal_locations)
         if possible_keys_for_type(type_name).length > 1
-          # multiple keys use an a-star search to traverse intermediary locations
+          # multiple keys use an A* search to traverse intermediary locations
           return route_type_to_locations_via_search(type_name, start_location, goal_locations)
         end
 
         # types with a single key attribute must all be within a single hop of each other,
         # so can use a simple match to collect boundaries for the goal locations.
         @boundaries[type_name].each_with_object({}) do |boundary, memo|
-          if goal_locations.include?(boundary["location"])
-            memo[boundary["location"]] = [boundary]
+          if goal_locations.include?(boundary.location)
+            memo[boundary.location] = [boundary]
           end
         end
       end
 
       private
 
-      # tunes a-star search to favor paths with fewest joining locations, ie:
+      PathNode = Struct.new(:location, :key, :cost, :boundary, keyword_init: true)
+
+      # tunes A* search to favor paths with fewest joining locations, ie:
       # favor longer paths through target locations over shorter paths with additional locations.
       def route_type_to_locations_via_search(type_name, start_location, goal_locations)
         results = {}
         costs = {}
 
         paths = possible_keys_for_type_and_location(type_name, start_location).map do |possible_key|
-          [{ location: start_location, key: possible_key, cost: 0 }]
+          [PathNode.new(location: start_location, key: possible_key, cost: 0)]
         end
 
         while paths.any?
           path = paths.pop
-          current_location = path.last[:location]
-          current_key = path.last[:key]
-          current_cost = path.last[:cost]
+          current_location = path.last.location
+          current_key = path.last.key
+          current_cost = path.last.cost
 
           @boundaries[type_name].each do |boundary|
-            forward_location = boundary["location"]
-            next if current_key != boundary["key"]
-            next if path.any? { _1[:location] == forward_location }
+            forward_location = boundary.location
+            next if current_key != boundary.key
+            next if path.any? { _1.location == forward_location }
 
             best_cost = costs[forward_location] || Float::INFINITY
             next if best_cost < current_cost
 
             path.pop
-            path << {
+            path << PathNode.new(
               location: current_location,
               key: current_key,
               cost: current_cost,
               boundary: boundary,
-            }
+            )
 
             if goal_locations.include?(forward_location)
               current_result = results[forward_location]
               if current_result.nil? || current_cost < best_cost || (current_cost == best_cost && path.length < current_result.length)
-                results[forward_location] = path.map { _1[:boundary] }
+                results[forward_location] = path.map(&:boundary)
               end
             else
-              path.last[:cost] += 1
+              path.last.cost += 1
             end
 
-            forward_cost = path.last[:cost]
+            forward_cost = path.last.cost
             costs[forward_location] = forward_cost if forward_cost < best_cost
 
             possible_keys_for_type_and_location(type_name, forward_location).each do |possible_key|
-              paths << [*path, { location: forward_location, key: possible_key, cost: forward_cost }]
+              paths << [*path, PathNode.new(location: forward_location, key: possible_key, cost: forward_cost)]
             end
           end
 
           paths.sort! do |a, b|
-            cost_diff = a.last[:cost] - b.last[:cost]
-            cost_diff.zero? ? a.length - b.length : cost_diff
-          end.reverse!
+            cost_diff = b.last.cost - a.last.cost
+            cost_diff.zero? ? b.length - a.length : cost_diff
+          end
         end
 
         results

data/lib/graphql/stitching/util.rb

@@ -3,54 +3,65 @@
 module GraphQL
   module Stitching
     class Util
-      # specifies if a type is a primitive leaf value
-      def self.is_leaf_type?(type)
-        type.kind.scalar? || type.kind.enum?
-      end
+      TypeStructure = Struct.new(:list, :null, :name, keyword_init: true) do
+        alias_method :list?, :list
+        alias_method :null?, :null
 
-      # strips non-null wrappers from a type
-      def self.unwrap_non_null(type)
-        type = type.of_type while type.non_null?
-        type
+        def non_null?
+          !null
+        end
       end
 
-      # builds a single-dimensional representation of a wrapped type structure
-      def self.flatten_type_structure(type)
-        structure = []
+      class << self
+        # specifies if a type is a primitive leaf value
+        def is_leaf_type?(type)
+          type.kind.scalar? || type.kind.enum?
+        end
+
+        # strips non-null wrappers from a type
+        def unwrap_non_null(type)
+          type = type.of_type while type.non_null?
+          type
+        end
+
+        # builds a single-dimensional representation of a wrapped type structure
+        def flatten_type_structure(type)
+          structure = []
+
+          while type.list?
+            structure << TypeStructure.new(
+              list: true,
+              null: !type.non_null?,
+              name: nil,
+            )
+
+            type = unwrap_non_null(type).of_type
+          end
 
-        while type.list?
-          structure << {
-            list: true,
+          structure << TypeStructure.new(
+            list: false,
             null: !type.non_null?,
-            name: nil,
-          }
+            name: type.unwrap.graphql_name,
+          )
 
-          type = unwrap_non_null(type).of_type
+          structure
         end
 
-        structure << {
-          list: false,
-          null: !type.non_null?,
-          name: type.unwrap.graphql_name,
-        }
-
-        structure
-      end
+        # expands interfaces and unions to an array of their memberships
+        # like `schema.possible_types`, but includes child interfaces
+        def expand_abstract_type(schema, parent_type)
+          return [] unless parent_type.kind.abstract?
+          return parent_type.possible_types if parent_type.kind.union?
 
-      # expands interfaces and unions to an array of their memberships
-      # like `schema.possible_types`, but includes child interfaces
-      def self.expand_abstract_type(schema, parent_type)
-        return [] unless parent_type.kind.abstract?
-        return parent_type.possible_types if parent_type.kind.union?
-
-        result = []
-        schema.types.values.each do |type|
-          next unless type <= GraphQL::Schema::Interface && type != parent_type
-          next unless type.interfaces.include?(parent_type)
-          result << type
-          result.push(*expand_abstract_type(schema, type)) if type.kind.interface?
+          result = []
+          schema.types.values.each do |type|
+            next unless type <= GraphQL::Schema::Interface && type != parent_type
+            next unless type.interfaces.include?(parent_type)
+            result << type
+            result.push(*expand_abstract_type(schema, type)) if type.kind.interface?
+          end
+          result.uniq
         end
-        result.uniq
       end
     end
   end

data/lib/graphql/stitching/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Stitching
-    VERSION = "0.3.6"
+    VERSION = "1.0.1"
   end
 end

data/lib/graphql/stitching.rb

@@ -5,11 +5,11 @@ require "graphql"
 module GraphQL
   module Stitching
     EMPTY_OBJECT = {}.freeze
+    EMPTY_ARRAY = [].freeze
 
     class StitchingError < StandardError; end
 
     class << self
-
       def stitch_directive
         @stitch_directive ||= "stitch"
       end
@@ -23,14 +23,18 @@ module GraphQL
   end
 end
 
-require_relative "stitching/gateway"
 require_relative "stitching/supergraph"
+require_relative "stitching/boundary"
+require_relative "stitching/client"
 require_relative "stitching/composer"
 require_relative "stitching/executor"
-require_relative "stitching/planner_operation"
+require_relative "stitching/http_executable"
+require_relative "stitching/plan"
+require_relative "stitching/planner_step"
 require_relative "stitching/planner"
-require_relative "stitching/remote_client"
 require_relative "stitching/request"
+require_relative "stitching/selection_hint"
 require_relative "stitching/shaper"
+require_relative "stitching/skip_include"
 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.3.6
+  version: 1.0.1
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-04-11 00:00:00.000000000 Z
+date: 2023-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -80,9 +80,9 @@ files:
 - README.md
 - Rakefile
 - docs/README.md
+- docs/client.md
 - docs/composer.md
 - docs/executor.md
-- docs/gateway.md
 - docs/images/library.png
 - docs/images/merging.png
 - docs/images/stitching.png
@@ -97,17 +97,23 @@ files:
 - gemfiles/graphql_1.13.9.gemfile
 - graphql-stitching.gemspec
 - lib/graphql/stitching.rb
+- lib/graphql/stitching/boundary.rb
+- lib/graphql/stitching/client.rb
 - lib/graphql/stitching/composer.rb
 - lib/graphql/stitching/composer/base_validator.rb
 - lib/graphql/stitching/composer/validate_boundaries.rb
 - lib/graphql/stitching/composer/validate_interfaces.rb
 - lib/graphql/stitching/executor.rb
-- lib/graphql/stitching/gateway.rb
+- lib/graphql/stitching/executor/boundary_source.rb
+- lib/graphql/stitching/executor/root_source.rb
+- lib/graphql/stitching/http_executable.rb
+- lib/graphql/stitching/plan.rb
 - lib/graphql/stitching/planner.rb
-- lib/graphql/stitching/planner_operation.rb
-- lib/graphql/stitching/remote_client.rb
+- lib/graphql/stitching/planner_step.rb
 - lib/graphql/stitching/request.rb
+- lib/graphql/stitching/selection_hint.rb
 - lib/graphql/stitching/shaper.rb
+- lib/graphql/stitching/skip_include.rb
 - lib/graphql/stitching/supergraph.rb
 - lib/graphql/stitching/util.rb
 - lib/graphql/stitching/version.rb

data/docs/gateway.md

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

data/lib/graphql/stitching/planner_operation.rb

@@ -1,63 +0,0 @@
-# frozen_string_literal: true
-
-module GraphQL
-  module Stitching
-    class PlannerOperation
-      LANGUAGE_PRINTER = GraphQL::Language::Printer.new
-
-      attr_reader :order, :location, :parent_type, :if_type, :operation_type, :path
-      attr_accessor :after, :selections, :variables, :boundary
-
-      def initialize(
-        location:,
-        parent_type:,
-        order:,
-        after: nil,
-        operation_type: "query",
-        selections: [],
-        variables: [],
-        path: [],
-        if_type: nil,
-        boundary: nil
-      )
-        @location = location
-        @parent_type = parent_type
-        @order = order
-        @after = after
-        @operation_type = operation_type
-        @selections = selections
-        @variables = variables
-        @path = path
-        @if_type = if_type
-        @boundary = boundary
-      end
-
-      def selection_set
-        op = GraphQL::Language::Nodes::OperationDefinition.new(selections: @selections)
-        LANGUAGE_PRINTER.print(op).gsub!(/\s+/, " ").strip!
-      end
-
-      def variable_set
-        @variables.each_with_object({}) do |(variable_name, value_type), memo|
-          memo[variable_name] = LANGUAGE_PRINTER.print(value_type)
-        end
-      end
-
-      def to_h
-        data = {
-          "order" => @order,
-          "after" => @after,
-          "location" => @location,
-          "operation_type" => @operation_type,
-          "selections" => selection_set,
-          "variables" => variable_set,
-          "path" => @path,
-        }
-
-        data["if_type"] = @if_type if @if_type
-        data["boundary"] = @boundary if @boundary
-        data
-      end
-    end
-  end
-end