graphql-stitching 0.0.1

data/docs/gateway.md

@@ -0,0 +1,106 @@
+## 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.
+
+### Building
+
+The Gateway constructor accepts configuration to build a [`Supergraph`](./supergraph.md) for you. Location names are root keys, and each location config provides a `schema` and an optional [executable](../README.md#executables).
+
+```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"),
+  },
+  showtimes: {
+    schema: GraphQL::Schema.from_definition(showtimes_schema),
+    executable: GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3001"),
+  },
+  my_local: {
+    schema: MyLocal::GraphQL::Schema,
+  },
+})
+```
+
+Locations provided with only a `schema` will assign the schema as the location executable (these are locally-executable schemas, and must have locally-implemented resolvers). Locations that provide an `executable` will perform requests using the executable.
+
+#### From exported supergraph
+
+It's possible to [export and rehydrate](./supergraph.md#export-and-caching) `Supergraph` instances, allowing a supergraph to be cached as static artifacts and then rehydrated quickly at runtime without going through composition. To setup a gateway with a prebuilt supergraph, you may pass it as a `supergraph` argument:
+
+```ruby
+exported_schema = "..."
+exported_mapping = JSON.parse("{ ... }")
+supergraph = GraphQL::Stitching::Supergraph.from_export(exported_schema, exported_mapping)
+
+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 to a stitched gateway becomes mostly a drop-in replacement to executing 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 that gets passed through to gateway caching and error 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/docs/planner.md

@@ -0,0 +1,43 @@
+## 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.
+
+```ruby
+request = <<~GRAPHQL
+  query MyQuery($id: ID!) {
+    product(id:$id) {
+      title
+      brands { name }
+    }
+  }
+GRAPHQL
+
+document = GraphQL::Stitching::Document.new(request, operation_name: "MyQuery")
+
+plan = GraphQL::Stitching::Planner.new(
+  supergraph: supergraph,
+  document: document,
+).perform
+```
+
+### Caching
+
+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)
+
+plan = if cached_plan
+  JSON.parse(cached_plan)
+else
+  plan_hash = GraphQL::Stitching::Planner.new(
+    supergraph: supergraph,
+    document: document,
+  ).perform.to_h
+
+  $redis.set(document.digest, JSON.generate(plan_hash))
+  plan_hash
+end
+
+# execute the plan...
+```

data/docs/shaper.md

@@ -0,0 +1,20 @@
+## GraphQL::Stitching::Shaper
+
+The `Shaper` takes the raw output generated by the `GraphQL::Stitching::Executor` and does the final shaping and
+cleaning. It removes data that was added while building the result, it also handles cleaning up violations that can
+only occur at the end, such as bubbling up null violoations.
+
+See the [Executor](./docs/executor.md)
+
+```ruby
+raw_result = GraphQL::Stitching::Executor.new(
+  supergraph: supergraph,
+  plan: plan.to_h,
+  variables: variables,
+).perform(document)
+
+final_result = GraphQL::Stitching::Shaper.new(
+  supergraph: supergraph,
+  document: document,
+  raw: raw_result).perform!
+```

data/docs/supergraph.md

@@ -0,0 +1,65 @@
+## GraphQL::Stitching::Supergraph
+
+A `Supergraph` is the singuar representation of a stitched graph. `Supergraph` is generated by a [`Composer`](./composer.md), and contains the combined schema and delegation map for location routing.
+
+```ruby
+storefronts_sdl = "type Query { storefront(id: ID!): Storefront } ..."
+products_sdl = "type Query { product(id: ID!): Product } ..."
+
+supergraph = GraphQL::Stitching::Composer.new({
+  "storefronts" => GraphQL::Schema.from_definition(storefronts_sdl),
+  "products" => GraphQL::Schema.from_definition(products_sdl),
+}).perform
+
+combined_schema = supergraph.schema
+```
+
+### Assigning executables
+
+A Supergraph also manages executable resources assigned for each location (ie: the objects that perform GraphQL requests for each location). An executable is a `GraphQL::Schema` class or any object that implements a `.call(location, query_string, variables)` method and returns a raw GraphQL response. Executables are assigned to a supergraph 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|
+  # ...
+end
+```
+
+### Export and caching
+
+A Supergraph is designed to be composed, cached, and restored. Calling the `export` method will return an SDL (Schema Definition Language) print of the combined graph schema and a deletation mapping hash. These can be persisted in any raw format that suits your stack:
+
+```ruby
+supergraph_sdl, delegation_map = supergraph.export
+
+# stash these resources in Redis...
+$redis.set("cached_supergraph_sdl", supergraph_sdl)
+$redis.set("cached_delegation_map", JSON.generate(delegation_map))
+
+# or, write the resources as files and commit them to your repo...
+File.write("supergraph/schema.graphql", supergraph_sdl)
+File.write("supergraph/delegation_map.json", JSON.generate(delegation_map))
+```
+
+To restore a cached Supergraph, collect the cached SDL and delegation mapping then recreate the Supergraph using `from_export`:
+
+```ruby
+supergraph_sdl = $redis.get("cached_supergraph_sdl")
+delegation_map = JSON.parse($redis.get("cached_delegation_map"))
+
+supergraph = GraphQL::Stitching::Supergraph.from_export(supergraph_sdl, delegation_map)
+```
+
+Note that a supergraph built from cache will not have _any_ executables assigned to it, so you'll need to manually reassign executables for each location:
+
+```ruby
+remote_client = GraphQL::Stitching::RemoteClient.new(
+  url: "http:localhost:3000",
+  headers: { "Authorization" => "Bearer 12345" }
+)
+supergraph.assign_executable("my_remote", remote_client)
+supergraph.assign_executable("my_local", MyLocal::Schema)
+```

data/example/gateway.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'rackup'
+require 'json'
+require 'byebug'
+require 'graphql'
+require 'graphql/stitching'
+require_relative '../test/schemas/example'
+
+class StitchedApp
+  def initialize
+    file = File.open("#{__dir__}/graphiql.html")
+    @graphiql = file.read
+    file.close
+
+    @gateway = GraphQL::Stitching::Gateway.new(locations: {
+      products: {
+        schema: Schemas::Example::Products,
+      },
+      storefronts: {
+        schema: Schemas::Example::Storefronts,
+        executable: GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3001/graphql"),
+      },
+      manufacturers: {
+        schema: Schemas::Example::Manufacturers,
+        executable: GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3002/graphql"),
+      }
+    })
+  end
+
+  def call(env)
+    req = Rack::Request.new(env)
+    case req.path_info
+    when /graphql/
+      params = JSON.parse(req.body.read)
+
+      result = @gateway.execute(
+        query: params["query"],
+        variables: params["variables"],
+        operation_name: params["operationName"],
+      )
+
+      [200, {"content-type" => "application/json"}, [JSON.generate(result)]]
+    else
+      [200, {"content-type" => "text/html"}, [@graphiql]]
+    end
+  end
+end
+
+Rackup::Handler.default.run(StitchedApp.new, :Port => 3000)

data/example/graphiql.html

@@ -0,0 +1,153 @@
+<!--
+ *  Copyright (c) Facebook, Inc.
+ *  All rights reserved.
+ *
+ *
+ *  This source code is licensed under the license found in the
+ *  LICENSE file in the root directory of this source tree.
+-->
+
+<!-- original source: https://github.com/graphql/graphiql/blob/master/example/index.html -->
+
+<!DOCTYPE html>
+<html>
+<head>
+    <style>
+        body {
+            height: 100%;
+            margin: 0;
+            width: 100%;
+            overflow: hidden;
+        }
+        #graphiql {
+            height: 100vh;
+        }
+    </style>
+
+    <!--
+      This GraphiQL example depends on Promise and fetch, which are available in
+      modern browsers, but can be "polyfilled" for older browsers.
+      GraphiQL itself depends on React DOM.
+      If you do not want to rely on a CDN, you can host these files locally or
+      include them directly in your favored resource bunder.
+    -->
+    <script src="https://cdn.jsdelivr.net/es6-promise/4.0.5/es6-promise.auto.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/fetch/0.9.0/fetch.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/react/15.4.2/react.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/react/15.4.2/react-dom.min.js"></script>
+
+    <!--
+      These two files can be found in the npm module, however you may wish to
+      copy them directly into your environment, or perhaps include them in your
+      favored resource bundler.
+     -->
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/graphiql/0.10.2/graphiql.css" />
+    <script src="https://cdn.jsdelivr.net/graphiql/0.10.2/graphiql.min.js"></script>
+
+</head>
+<body>
+<div id="graphiql">Loading...</div>
+<script>
+
+    /**
+     * This GraphiQL example illustrates how to use some of GraphiQL's props
+     * in order to enable reading and updating the URL parameters, making
+     * link sharing of queries a little bit easier.
+     *
+     * This is only one example of this kind of feature, GraphiQL exposes
+     * various React params to enable interesting integrations.
+     */
+
+      // Parse the search string to get url parameters.
+    var search = window.location.search;
+    var parameters = {};
+    search.substr(1).split('&').forEach(function (entry) {
+        var eq = entry.indexOf('=');
+        if (eq >= 0) {
+            parameters[decodeURIComponent(entry.slice(0, eq))] =
+              decodeURIComponent(entry.slice(eq + 1));
+        }
+    });
+
+    // if variables was provided, try to format it.
+    if (parameters.variables) {
+        try {
+            parameters.variables =
+              JSON.stringify(JSON.parse(parameters.variables), null, 2);
+        } catch (e) {
+            // Do nothing, we want to display the invalid JSON as a string, rather
+            // than present an error.
+        }
+    }
+
+    // When the query and variables string is edited, update the URL bar so
+    // that it can be easily shared
+    function onEditQuery(newQuery) {
+        parameters.query = newQuery;
+        updateURL();
+    }
+
+    function onEditVariables(newVariables) {
+        parameters.variables = newVariables;
+        updateURL();
+    }
+
+    function onEditOperationName(newOperationName) {
+        parameters.operationName = newOperationName;
+        updateURL();
+    }
+
+    function updateURL() {
+        var newSearch = '?' + Object.keys(parameters).filter(function (key) {
+              return Boolean(parameters[key]);
+          }).map(function (key) {
+              return encodeURIComponent(key) + '=' +
+                encodeURIComponent(parameters[key]);
+          }).join('&');
+        history.replaceState(null, null, newSearch);
+    }
+
+    // Defines a GraphQL fetcher using the fetch API. You're not required to
+    // use fetch, and could instead implement graphQLFetcher however you like,
+    // as long as it returns a Promise or Observable.
+    function graphQLFetcher(graphQLParams) {
+        // This example expects a GraphQL server at the path /graphql.
+        // Change this to point wherever you host your GraphQL server.
+        return fetch('/graphql', {
+            method: 'post',
+            headers: {
+                'Accept': 'application/json',
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(graphQLParams),
+            credentials: 'include',
+        }).then(function (response) {
+            return response.text();
+        }).then(function (responseBody) {
+            try {
+                return JSON.parse(responseBody);
+            } catch (error) {
+                return responseBody;
+            }
+        });
+    }
+
+    // Render <GraphiQL /> into the body.
+    // See the README in the top level of this module to learn more about
+    // how you can customize GraphiQL by providing different values or
+    // additional child elements.
+    ReactDOM.render(
+      React.createElement(GraphiQL, {
+          fetcher: graphQLFetcher,
+          query: parameters.query,
+          variables: parameters.variables,
+          operationName: parameters.operationName,
+          onEditQuery: onEditQuery,
+          onEditVariables: onEditVariables,
+          onEditOperationName: onEditOperationName
+      }),
+      document.getElementById('graphiql')
+    );
+</script>
+</body>
+</html>

data/example/remote1.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'rackup'
+require 'json'
+require 'graphql'
+require_relative '../test/schemas/example'
+
+class FirstRemoteApp
+  def call(env)
+    req = Rack::Request.new(env)
+    case req.path_info
+    when /graphql/
+      params = JSON.parse(req.body.read)
+      result = Schemas::Example::Storefronts.execute(
+        query: params["query"],
+        variables: params["variables"],
+        operation_name: params["operationName"],
+      )
+      [200, {"content-type" => "application/json"}, [JSON.generate(result)]]
+    else
+      [404, {"content-type" => "text/html"}, ["not found"]]
+    end
+  end
+end
+
+Rackup::Handler.default.run(FirstRemoteApp.new, :Port => 3001)

data/example/remote2.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'rackup'
+require 'json'
+require 'graphql'
+require_relative '../test/schemas/example'
+
+class SecondRemoteApp
+  def call(env)
+    req = Rack::Request.new(env)
+    case req.path_info
+    when /graphql/
+      params = JSON.parse(req.body.read)
+      result = Schemas::Example::Manufacturers.execute(
+        query: params["query"],
+        variables: params["variables"],
+        operation_name: params["operationName"],
+      )
+      [200, {"content-type" => "application/json"}, [JSON.generate(result)]]
+    else
+      [404, {"content-type" => "text/html"}, ["not found"]]
+    end
+  end
+end
+
+Rackup::Handler.default.run(SecondRemoteApp.new, :Port => 3002)

data/graphql-stitching.gemspec

@@ -0,0 +1,34 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'graphql/stitching/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'graphql-stitching'
+  spec.version       = GraphQL::Stitching::VERSION
+  spec.authors       = ['Greg MacWilliam']
+  spec.summary       = 'GraphQL schema stitching for Ruby'
+  spec.description   = spec.summary
+  spec.homepage      = 'https://github.com/gmac/graphql-stitching-ruby'
+  spec.license       = 'MIT'
+
+  spec.required_ruby_version = '>= 3.1.1'
+
+  spec.metadata    = {
+    'homepage_uri' => 'https://github.com/gmac/graphql-stitching-ruby',
+    'changelog_uri' => 'https://github.com/gmac/graphql-stitching-ruby/releases',
+    'source_code_uri' => 'https://github.com/gmac/graphql-stitching-ruby',
+    'bug_tracker_uri' => 'https://github.com/gmac/graphql-stitching-ruby/issues',
+  }
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^test/})
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency 'graphql', '~> 2.0.16'
+
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'rake', '~> 12.0'
+  spec.add_development_dependency 'minitest', '~> 5.12'
+end

data/lib/graphql/stitching/composer/base_validator.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Stitching
+    class Composer::BaseValidator
+      def perform(ctx, composer)
+        raise "not implemented"
+      end
+    end
+  end
+end

data/lib/graphql/stitching/composer/validate_boundaries.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Stitching
+    class Composer::ValidateBoundaries < Composer::BaseValidator
+
+      def perform(ctx, composer)
+        ctx.schema.types.each do |type_name, type|
+          # objects and interfaces that are not the root operation types
+          next unless type.kind.object? || type.kind.interface?
+          next if ctx.schema.query == type || ctx.schema.mutation == type
+          next if type.graphql_name.start_with?("__")
+
+          # multiple subschemas implement the type
+          subschema_types_by_location = composer.subschema_types_by_name_and_location[type_name]
+          next unless subschema_types_by_location.length > 1
+
+          boundaries = ctx.boundaries[type_name]
+          if boundaries&.any?
+            validate_as_boundary(ctx, type, subschema_types_by_location, boundaries)
+          elsif type.kind.object?
+            validate_as_shared(ctx, type, subschema_types_by_location)
+          end
+        end
+      end
+
+      private
+
+      def validate_as_boundary(ctx, type, subschema_types_by_location, boundaries)
+        # abstract boundaries are expanded with their concrete implementations, which each get validated. Ignore the abstract itself.
+        return if type.kind.abstract?
+
+        # only one boundary allowed per type/location/key
+        boundaries_by_location_and_key = boundaries.each_with_object({}) do |boundary, memo|
+          if memo.dig(boundary["location"], boundary["selection"])
+            raise Composer::ValidationError, "Multiple boundary queries for `#{type.graphql_name}.#{boundary["selection"]}` found in #{boundary["location"]}.
+            Limit one boundary query per type and key in each location. Abstract boundaries provide all possible types."
+          end
+          memo[boundary["location"]] ||= {}
+          memo[boundary["location"]][boundary["selection"]] = boundary
+        end
+
+        boundary_keys = boundaries.map { _1["selection"] }.uniq
+        key_only_types_by_location = subschema_types_by_location.select do |location, subschema_type|
+          subschema_type.fields.keys.length == 1 && boundary_keys.include?(subschema_type.fields.keys.first)
+        end
+
+        # all locations have a boundary, or else are key-only
+        subschema_types_by_location.each do |location, subschema_type|
+          unless boundaries_by_location_and_key[location] || key_only_types_by_location[location]
+            raise Composer::ValidationError, "A boundary query is required for `#{type.graphql_name}` in #{location} because it provides unique fields."
+          end
+        end
+
+        outbound_access_locations = key_only_types_by_location.keys
+        bidirectional_access_locations = subschema_types_by_location.keys - outbound_access_locations
+
+        # verify that all outbound locations can access all inbound locations
+        (outbound_access_locations + bidirectional_access_locations).each do |location|
+          remote_locations = bidirectional_access_locations.reject { _1 == location }
+          paths = ctx.route_type_to_locations(type.graphql_name, location, remote_locations)
+          if paths.length != remote_locations.length || paths.any? { |_loc, path| path.nil? }
+            raise Composer::ValidationError, "Cannot route `#{type.graphql_name}` boundaries in #{location} to all other locations.
+            All locations must provide a boundary accessor that uses a conjoining key."
+          end
+        end
+      end
+
+      def validate_as_shared(ctx, type, subschema_types_by_location)
+        expected_fields = type.fields.keys.sort
+        subschema_types_by_location.each do |location, subschema_type|
+          if subschema_type.fields.keys.sort != expected_fields
+            raise Composer::ValidationError, "Shared type `#{type.graphql_name}` must have consistent fields across locations,
+            or else define boundary queries so that its unique fields may be accessed remotely."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/stitching/composer/validate_interfaces.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Stitching
+    class Composer::ValidateInterfaces < Composer::BaseValidator
+
+      def perform(supergraph, composer)
+        # @todo
+        # Validate all supergraph interface fields
+        # match possible types in all locations...
+        # - Traverse supergraph types (supergraph.types)
+        # - For each interface (.kind.interface?), get possible types (Util.get_possible_types)
+        # - For each possible type, traverse type candidates (composer.subschema_types_by_name_and_location)
+        # - For each type candidate, compare interface fields to type candidate fields
+        # - For each type candidate field that matches an interface field...
+        #   - Named types must match
+        #   - List structures must match
+        #   - Nullabilities must be >= interface field
+        # - It's OKAY if a type candidate does not implement the full interface
+      end
+
+    end
+  end
+end