graphql-stitching 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a228b0fe5779d625285182f885a7d65b5f66541f275a5313602e68a4c9eb209d
+  data.tar.gz: f6efcaeafd7c417db07f007641f84c800c0ebb32c99ad19c5004aa2bb9ac8685
+SHA512:
+  metadata.gz: 1d484e39db0ac919e68477e8733fa6f0ca31ffde74b2bfebc4e13ba6b55d7973dc793c6df4251ae7b912c450bdc38ab4478e300c350d7be67555a635687b04a9
+  data.tar.gz: 6354381e960a922453cd38ae5c513b60f2d2ae4585ec2a53a1ab7b405c2da6ca6d01bce9999794f9c8b6df7fe0d49176a4f944ab0efabfcb8ff252393a60f88e

data/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['3.1.1']
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Setup Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: |
+        gem install bundler
+        bundle install --jobs 4 --retry 3
+        bundle exec rake test

data/.gitignore

@@ -0,0 +1,59 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+.envrc
+
+# Used by dotenv library to load environment variables.
+# .env
+/example/env.json
+
+# Ignore Byebug command history file.
+.byebug_history
+.DS_Store
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+# .rubocop-https?--*

data/.ruby-version

@@ -0,0 +1 @@
+3.1.1

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
+
+gem 'rack'
+gem 'rackup'
+gem 'foreman'
+gem 'pry'
+gem 'pry-byebug'
+gem 'warning'

data/Gemfile.lock

@@ -0,0 +1,49 @@
+PATH
+  remote: .
+  specs:
+    graphql-stitching (0.0.1)
+      graphql (~> 2.0.16)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    byebug (11.1.3)
+    coderay (1.1.3)
+    foreman (0.87.2)
+    graphql (2.0.16)
+    method_source (1.0.0)
+    minitest (5.17.0)
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.10.1)
+      byebug (~> 11.0)
+      pry (>= 0.13, < 0.15)
+    rack (3.0.4.1)
+    rackup (2.1.0)
+      rack (>= 3)
+      webrick (~> 1.8)
+    rake (12.3.3)
+    warning (1.3.0)
+    webrick (1.8.1)
+
+PLATFORMS
+  arm64-darwin-21
+  ruby
+  x86_64-darwin-21
+  x86_64-linux
+
+DEPENDENCIES
+  bundler (~> 2.0)
+  foreman
+  graphql-stitching!
+  minitest (~> 5.12)
+  pry
+  pry-byebug
+  rack
+  rackup
+  rake (~> 12.0)
+  warning
+
+BUNDLED WITH
+   2.4.1

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Greg MacWilliam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/Procfile

@@ -0,0 +1,3 @@
+gateway: bundle exec ruby example/gateway.rb
+remote1: bundle exec ruby example/remote1.rb
+remote2: bundle exec ruby example/remote2.rb

data/README.md

@@ -0,0 +1,329 @@
+## GraphQL Stitching for Ruby
+
+GraphQL stitching composes a single schema from multiple underlying GraphQL resources, then smartly delegates portions of incoming requests to their respective service locations in dependency order and returns the merged results. This allows an entire location graph to be queried through one combined GraphQL surface area.
+
+![Stitched graph](./docs/images/stitching.png)
+
+**Supports:**
+- Merged object and interface types.
+- Multiple keys per merged type.
+- Shared objects, enums, and inputs across locations.
+- Combining local and remote schemas.
+
+**NOT Supported:**
+- Computed fields (ie: federation-style `@requires`)
+- Subscriptions
+
+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.
+
+## Getting started
+
+Add to your Gemfile:
+
+```ruby
+gem "graphql-stitching"
+```
+
+Run `bundle install`, then require unless running an autoloading framework (Rails, etc):
+
+```ruby
+require "graphql/stitching"
+```
+
+## Usage
+
+The quickest way to start is to use the provided [`Gateway`](./docs/gateway.md) component that assembles a stitched graph ready to execute requests:
+
+```ruby
+movies_schema = <<~GRAPHQL
+  type Movie { id: ID! name: String! }
+  type Query { movie(id: ID!): Movie }
+GRAPHQL
+
+showtimes_schema = <<~GRAPHQL
+  type Showtime { id: ID! time: String! }
+  type Query { showtime(id: ID!): Showtime }
+GRAPHQL
+
+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,
+  },
+})
+
+result = gateway.execute(
+  query: "query FetchFromAll($movieId:ID!, $showtimeId:ID!){
+    movie(id:$movieId) { name }
+    showtime(id:$showtimeId): { time }
+    myLocalField
+  }",
+  variables: { "movieId" => "1", "showtimeId" => "2" },
+  operation_name: "FetchFromAll"
+)
+```
+
+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.
+
+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.
+- [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.
+- [Shaper](./docs/shaper.md) - takes the raw output of the executor and prepares it for delivery.
+
+## Merged types
+
+`Object` and `Interface` types may exist with different fields in different graph locations, and will get merged together in the combined schema.
+
+![Merging types](./docs/images/merging.png)
+
+To facilitate this merging of types, stitching must know how to cross-reference and fetch each variant of a type from its source location. This is done using the `@stitch` directive:
+
+```graphql
+directive @stitch(key: String!) repeatable on FIELD_DEFINITION
+```
+
+This directive is applied to root queries where a merged type may be accessed in each location, and a `key` argument specifies a field needed from other locations to be used as a query argument.
+
+```ruby
+products_schema = <<~GRAPHQL
+  directive @stitch(key: String!) repeatable on FIELD_DEFINITION
+
+  type Product {
+    id: ID!
+    name: String!
+  }
+
+  type Query {
+    product(id: ID!): Product @stitch(key: "id")
+  }
+GRAPHQL
+
+shipping_schema = <<~GRAPHQL
+  directive @stitch(key: String!) repeatable on FIELD_DEFINITION
+
+  type Product {
+    id: ID!
+    weight: Float!
+  }
+
+  type Query {
+    products(ids: [ID!]!): [Product]! @stitch(key: "id")
+  }
+GRAPHQL
+
+supergraph = GraphQL::Stitching::Composer.new({
+  "products" => GraphQL::Schema.from_definition(products_schema),
+  "shipping" => GraphQL::Schema.from_definition(shipping_schema),
+})
+
+supergraph.assign_executable("products",
+  GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3001")
+)
+supergraph.assign_executable("shipping",
+  GraphQL::Stitching::RemoteClient.new(url: "http://localhost:3002")
+)
+```
+
+Focusing on the `@stitch` directive usage:
+
+```graphql
+type Product {
+  id: ID!
+  name: String!
+}
+type Query {
+  product(id: ID!): Product @stitch(key: "id")
+}
+```
+
+* 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 `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:
+
+```graphql
+type Product {
+  id: ID!
+}
+```
+
+The above representation of a `Product` type provides no unique data beyond a key that is available in other locations. Thus, this representation will never require an inbound request to fetch it, and its stitching query may be omitted. This pattern of providing key-only types is very common in stitching: it allows a foreign key to be represented as an object stub that may be enriched by data collected from other locations.
+
+#### 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.
+
+```graphql
+type Query {
+  products(ids: [ID!]!): [Product]! @stitch(key: "id")
+}
+```
+
+#### Abstract queries
+
+It's okay for stitching queries to be implemented through abstract types. An abstract query will provide access to all of its possible types. For interfaces, the key selection should match a field within the interface. For unions, all possible types must implement the key selection individually.
+
+```graphql
+interface Node {
+  id: ID!
+}
+type Product implements Node {
+  id: ID!
+  name: String!
+}
+type Query {
+  nodes(ids: [ID!]!): [Node]! @stitch(key: "id")
+}
+```
+
+#### Multiple query arguments
+
+Stitching infers which argument to use for queries with a single argument. For queries that accept multiple arguments, the key must provide an argument mapping specified as `"<arg>:<key>"`. Note the `"id:id"` key:
+
+```graphql
+type Query {
+  product(id: ID, upc: ID): Product @stitch(key: "id:id")
+}
+```
+
+#### Multiple type keys
+
+A type may exist in multiple locations across the graph using different keys, for example:
+
+```graphql
+type Product { id:ID! }          # storefronts location
+type Product { id:ID! upc:ID! }  # products location
+type Product { upc:ID! }         # catelog location
+```
+
+In the above graph, the `storefronts` and `catelog` locations have different keys that join through an intermediary. This pattern is perfectly valid and resolvable as long as the intermediary provides stitching queries for each possible key:
+
+```graphql
+type Product {
+  id: ID!
+  upc: ID!
+}
+type Query {
+  productById(id: ID): Product @stitch(key: "id")
+  productByUpc(upc: ID): Product @stitch(key: "upc")
+}
+```
+
+The `@stitch` directive is also repeatable, allowing a single query to associate with multiple keys:
+
+```graphql
+type Product {
+  id: ID!
+  upc: ID!
+}
+type Query {
+  product(id: ID, upc: ID): Product @stitch(key: "id:id") @stitch(key: "upc:upc")
+}
+```
+
+#### Class-based schemas
+
+The `@stitch` directive can be added to class-based schemas with a directive class:
+
+```ruby
+class StitchField < GraphQL::Schema::Directive
+  graphql_name "stitch"
+  locations FIELD_DEFINITION
+  repeatable true
+  argument :key, String, required: true
+end
+
+class Query < GraphQL::Schema::Object
+  field :product, Product, null: false do
+    directive StitchField, key: "id"
+    argument :id, ID, required: true
+  end
+end
+```
+
+#### Custom directive names
+
+The library is configured to use a `@stitch` directive by default. You may customize this by setting a new name during initialization:
+
+```ruby
+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...
+
+```ruby
+class MyExecutable
+  def call(location, query_string, variables)
+    # process a GraphQL request...
+  end
+end
+```
+
+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
+```
+
+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)).
+
+## Concurrency
+
+The [Executor](./docs/executor.md) component builds atop the Ruby fiber-based implementation of `GraphQL::Dataloader`. Non-blocking concurrency requires setting a fiber scheduler via `Fiber.set_scheduler`, see [graphql-ruby docs](https://graphql-ruby.org/dataloader/nonblocking.html). You may also need to build your own remote clients using corresponding HTTP libraries.
+
+## Example
+
+This repo includes a working example of several stitched schemas running across Rack servers. Try running it:
+
+```shell
+bundle install
+foreman start
+```
+
+Then visit the gateway service at `http://localhost:3000` and try this query:
+
+```graphql
+query {
+  storefront(id: "1") {
+    id
+    products {
+      upc
+      name
+      price
+      manufacturer {
+        name
+        address
+        products { upc name }
+      }
+    }
+  }
+}
+```
+
+The above query collects data from all locations, two of which are remote schemas and the third a local schema. The combined graph schema is also stitched in to provide introspection capabilities.
+
+## Tests
+
+```shell
+bundle install
+bundle exec rake test [TEST=path/to/test.rb]
+```

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t, args|
+  puts args
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test

data/docs/README.md

@@ -0,0 +1,14 @@
+## GraphQL::Stitching
+
+This module provides a collection of components that may be composed into a stitched schema.
+
+![Library flow](./images/library.png)
+
+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.
+- [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

@@ -0,0 +1,69 @@
+## 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:
+
+```ruby
+storefronts_sdl = <<~GRAPHQL
+  type Storefront {
+    id:ID!
+    name: String!
+    products: [Product]
+  }
+
+  type Product {
+    id:ID!
+  }
+
+  type Query {
+    storefront(id: ID!): Storefront
+  }
+GRAPHQL
+
+products_sdl = <<~GRAPHQL
+  directive @stitch(key: String!) repeatable on FIELD_DEFINITION
+
+  type Product {
+    id:ID!
+    name: String
+    price: Int
+  }
+
+  type Query {
+    product(id: ID!): Product @stitch(key: "id")
+  }
+GRAPHQL
+
+supergraph = GraphQL::Stitching::Composer.new({
+  "storefronts" => GraphQL::Schema.from_definition(storefronts_sdl),
+  "products" => GraphQL::Schema.from_definition(products_sdl),
+}).perform
+
+combined_schema = supergraph.schema
+```
+
+The individual schemas provided to the composer are assigned a location name based on their input key. These source schemas may be built from SDL (Schema Definition Language) strings using `GraphQL::Schema.from_definition`, or may be structured Ruby classes that inherit from `GraphQL::Schema`. The source schemas are used exclusively for type reference and do NOT need any real data resolvers. Likewise, the resulting combined schema is only used for type reference and resolving introspections.
+
+### Merge patterns
+
+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:
+  - Common fields across locations must share a value type, and the weakest nullability is used.
+  - Field 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.
+
+- `InputObject` types intersect arguments from across locations (arguments must appear in all locations):
+  - Arguments must share a value type, and the strictest nullability across locations is used.
+  - Composition fails if argument intersection would eliminate a non-null argument.
+
+- `Enum` types merge their values based on how the enum is used:
+  - Enums used anywhere as an argument will intersect their values (common values across all locations).
+  - Enums used exclusively in read contexts will provide a union of values (all values across all locations).
+
+- `Union` types merge all possible types from across all locations.
+
+- `Scalar` types are added for all scalar names across all locations.
+
+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.

data/docs/document.md

@@ -0,0 +1,15 @@
+## 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/docs/executor.md

@@ -0,0 +1,29 @@
+## GraphQL::Stitching::Executor
+
+An `Executor` accepts a [`Supergraph`](./supergraph.md), a [query plan hash](./planner.md), and optional request variables. It handles executing requests and merging results collected from across graph locations.
+
+```ruby
+query = <<~GRAPHQL
+  query MyQuery($id: ID!) {
+    product(id:$id) {
+      title
+      brands { name }
+    }
+  }
+GRAPHQL
+
+variables = { "id" => "123" }
+
+document = GraphQL::Stitching::Document.new(query, operation_name: "MyQuery")
+
+plan = GraphQL::Stitching::Planner.new(
+  supergraph: supergraph,
+  document: document,
+).perform
+
+raw_result = GraphQL::Stitching::Executor.new(
+  supergraph: supergraph,
+  plan: plan.to_h,
+  variables: variables,
+).perform
+```