graphql-stitching 1.2.2 → 1.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6753e205aac88d3dd3be1c906b743cc49ae0de84ff8ab56c7e9be6e889429aa3
-  data.tar.gz: 59440f9d70cb365ef124604c42012bf655934555dfb76905328368353f5e310b
+  metadata.gz: 99acc247a0e5e227236b0261b3f975e7277f642a9d76daaf4f6a985bfc4825ea
+  data.tar.gz: ef5f01132498ca4ba1be6f8593f189645ddf8fb6b6d8ab71f9b7d0e55d6ec682
 SHA512:
-  metadata.gz: ac218d2218c14b8debff552ffb11e83e00293dfebb404d25296ed9e408232e488c44575c701ee3fd933331d84755062517f2c2da8df2db98ac7c5e8594595846
-  data.tar.gz: ec4f5051ebd511e72536c8e3246302079b2eb65ab5edab37c7c7d7de5488cdc7581318c69a0ea54047bd79ff42bf9e9c5af3434a27fc5667cf029340527c8117
+  metadata.gz: d1bd0db4c7f6d363231330222006f2bbc552a669227a38aeb7861dde843b59bc3e61b0f301f97d4a5c6b55193d01424cd9f240c0ff7a7ee483e49150686ac3da
+  data.tar.gz: 348aa663608fd8b0e5544ccf7ec500d4295a63bb9bd19a91031f927165da2a206024ce6cb17111c3ebda2c172e08072be8d01716c11f0a05c3ea8a9a4b99466e

data/.github/workflows/ci.yml

@@ -16,10 +16,16 @@ jobs:
             ruby: 3.2
           - gemfile: Gemfile
             ruby: 3.1
-          - gemfile: gemfiles/graphql_1.13.9.gemfile
-            ruby: 3.1
           - gemfile: Gemfile
             ruby: 2.7
+          - gemfile: gemfiles/graphql_2.2.0.gemfile
+            ruby: 3.1
+          - gemfile: gemfiles/graphql_2.1.0.gemfile
+            ruby: 3.1
+          - gemfile: gemfiles/graphql_2.0.0.gemfile
+            ruby: 3.1
+          - gemfile: gemfiles/graphql_1.13.9.gemfile
+            ruby: 3.1
 
     steps:
     - uses: actions/checkout@v2

data/README.md

@@ -9,14 +9,13 @@ GraphQL stitching composes a single schema from multiple underlying GraphQL reso
 - Multiple keys per merged type.
 - Shared objects, fields, enums, and inputs across locations.
 - Combining local and remote schemas.
-- Type merging via arbitrary queries or federation `_entities` protocol.
 - File uploads via [multipart form spec](https://github.com/jaydenseric/graphql-multipart-request-spec).
 
 **NOT Supported:**
 - 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 purely high-throughput API gateway, the opportunity here is for a Ruby application to stitch its local schemas together or onto remote sources without requiring an additional proxy service running in another language.
+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. The opportunity here is for a Ruby application to stitch its local schemas together or onto remote sources without requiring an additional proxy service running in another language. If your goal is to build a purely high-throughput API gateway, consider not using Ruby.
 
 ## Getting started
 
@@ -34,7 +33,7 @@ require "graphql/stitching"
 
 ## Usage
 
-The quickest way to start is to use the provided [`Client`](./docs/client.md) component that wraps a stitched graph in an executable workflow with [caching hooks](./docs/client.md#cache-hooks):
+The quickest way to start is to use the provided [`Client`](./docs/client.md) component that wraps a stitched graph in an executable workflow (with optional query plan caching hooks):
 
 ```ruby
 movies_schema = <<~GRAPHQL
@@ -72,7 +71,7 @@ result = client.execute(
 )
 ```
 
-Schemas provided in [location settings](./docs/composer.md#performing-composition) 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#merge-patterns) for more information on how schemas get merged.
+Schemas provided in [location settings](./docs/composer.md#performing-composition) 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 via [executables](#executables).
 
 While the `Client` constructor is an easy quick start, the library also has several discrete components that can be assembled into custom workflows:
 
@@ -87,11 +86,11 @@ While the `Client` constructor is an easy quick start, the library also has seve
 
 ![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 can be done using [arbitrary queries](#merged-types-via-arbitrary-queries) or [federation entities](#merged-types-via-federation-entities).
+To facilitate this merging of types, stitching must know how to cross-reference and fetch each variant of a type from its source location using [resolver queries](#merged-type-resolver-queries). For those in an Apollo ecosystem, there's also _limited_ support for merging types though a [federation `_entities` protocol](./docs/federation_entities.md).
 
-### Merged types via arbitrary queries
+### Merged type resolver queries
 
-Types can merge through arbitrary queries using the `@stitch` directive:
+Types merge through resolver queries identified by a `@stitch` directive:
 
 ```graphql
 directive @stitch(key: String!) repeatable on FIELD_DEFINITION
@@ -299,65 +298,6 @@ The library is configured to use a `@stitch` directive by default. You may custo
 GraphQL::Stitching.stitch_directive = "merge"
 ```
 
-### Merged types via Federation entities
-
-The [Apollo Federation specification](https://www.apollographql.com/docs/federation/subgraph-spec/) defines a standard interface for accessing merged type variants across locations. Stitching can utilize a _subset_ of this interface to facilitate basic type merging. The following spec is supported:
-
-- `@key(fields: "id")` (repeatable) specifies a key field for an object type. The key `fields` argument may only contain one field selection.
-- `_Entity` is a union type that must contain all types that implement a `@key`.
-- `_Any` is a scalar that recieves raw JSON objects; each object representation contains a `__typename` and the type's key field.
-- `_entities(representations: [_Any!]!): [_Entity]!` is a root query for local entity types.
-
-The composer will automatcially detect and stitch schemas with an `_entities` query, for example:
-
-```ruby
-products_schema = <<~GRAPHQL
-  directive @key(fields: String!) repeatable on OBJECT
-
-  type Product @key(fields: "id") {
-    id: ID!
-    name: String!
-  }
-
-  union _Entity = Product
-  scalar _Any
-
-  type Query {
-    user(id: ID!): User
-    _entities(representations: [_Any!]!): [_Entity]!
-  }
-GRAPHQL
-
-catalog_schema = <<~GRAPHQL
-  directive @key(fields: String!) repeatable on OBJECT
-
-  type Product @key(fields: "id") {
-    id: ID!
-    price: Float!
-  }
-
-  union _Entity = Product
-  scalar _Any
-
-  type Query {
-    _entities(representations: [_Any!]!): [_Entity]!
-  }
-GRAPHQL
-
-client = GraphQL::Stitching::Client.new(locations: {
-  products: {
-    schema: GraphQL::Schema.from_definition(products_schema),
-    executable: ...,
-  },
-  catalog: {
-    schema: GraphQL::Schema.from_definition(catalog_schema),
-    executable: ...,
-  },
-})
-```
-
-It's perfectly fine to mix and match schemas that implement an `_entities` query with schemas that implement `@stitch` directives; the protocols achieve the same result. Note that stitching is much simpler than Apollo Federation by design, and that Federation's advanced routing features (such as the `@requires` and `@external` directives) will not work with stitching.
-
 ## Executables
 
 An executable resource performs location-specific GraphQL requests. Executables may be `GraphQL::Schema` classes, or any object that responds to `.call(request, source, variables)` and returns a raw GraphQL response:
@@ -427,6 +367,7 @@ The [Executor](./docs/executor.md) component builds atop the Ruby fiber-based im
 
 - [Modeling foreign keys for stitching](./docs/mechanics.md##modeling-foreign-keys-for-stitching)
 - [Deploying a stitched schema](./docs/mechanics.md#deploying-a-stitched-schema)
+- [Schema composition merge patterns](./docs/composer.md#merge-patterns)
 - [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/federation_entities.md

@@ -0,0 +1,70 @@
+## Merged types via Apollo Federation `_entities`
+
+The [Apollo Federation specification](https://www.apollographql.com/docs/federation/subgraph-spec/) defines a standard interface for accessing merged type variants across locations. Stitching can utilize a _subset_ of this interface to facilitate basic type merging; the full spec is NOT supported and therefore is not fully interchangable with an Apollo Gateway.
+
+To avoid confusion, using [basic resolver queries](../README.md#merged-type-resolver-queries) is recommended unless you specifically need to interact with a service built for an Apollo ecosystem. Even then, be wary that it does not exceed the supported spec by [using features that will not work](#federation-features-that-will-most-definitly-break).
+
+### Supported spec
+
+The following subset of the federation spec is supported:
+
+- `@key(fields: "id")` (repeatable) specifies a key field for an object type. The key `fields` argument may only contain one field selection.
+- `_Entity` is a union type that must contain all types that implement a `@key`.
+- `_Any` is a scalar that recieves raw JSON objects; each object representation contains a `__typename` and the type's key field.
+- `_entities(representations: [_Any!]!): [_Entity]!` is a root query for local entity types.
+
+The composer will automatcially detect and stitch schemas with an `_entities` query, for example:
+
+```ruby
+products_schema = <<~GRAPHQL
+  directive @key(fields: String!) repeatable on OBJECT
+
+  type Product @key(fields: "id") {
+    id: ID!
+    name: String!
+  }
+
+  union _Entity = Product
+  scalar _Any
+
+  type Query {
+    user(id: ID!): User
+    _entities(representations: [_Any!]!): [_Entity]!
+  }
+GRAPHQL
+
+catalog_schema = <<~GRAPHQL
+  directive @key(fields: String!) repeatable on OBJECT
+
+  type Product @key(fields: "id") {
+    id: ID!
+    price: Float!
+  }
+
+  union _Entity = Product
+  scalar _Any
+
+  type Query {
+    _entities(representations: [_Any!]!): [_Entity]!
+  }
+GRAPHQL
+
+client = GraphQL::Stitching::Client.new(locations: {
+  products: {
+    schema: GraphQL::Schema.from_definition(products_schema),
+    executable: ...,
+  },
+  catalog: {
+    schema: GraphQL::Schema.from_definition(catalog_schema),
+    executable: ...,
+  },
+})
+```
+
+It's perfectly fine to mix and match schemas that implement an `_entities` query with schemas that implement `@stitch` directives; the protocols achieve the same result.
+
+### Federation features that will most definitly break
+
+- `@external` fields will confuse the stitching query planner.
+- `@requires` fields will not be sent any dependencies.
+- No support for Apollo composition directives.

data/gemfiles/graphql_1.13.9.gemfile

@@ -3,4 +3,4 @@
 source 'https://rubygems.org'
 gemspec
 
-gem 'graphql', '1.13.9'
+gem 'graphql', '~> 1.13.9'

data/gemfiles/graphql_2.0.0.gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
+
+gem 'graphql', '~> 2.0.0'

data/gemfiles/graphql_2.1.0.gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
+
+gem 'graphql', '~> 2.1.0'

data/gemfiles/graphql_2.2.0.gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
+
+gem 'graphql', '~> 2.2.0'

data/lib/graphql/stitching/composer.rb

@@ -145,7 +145,8 @@ module GraphQL
 
         builder = self
         schema = Class.new(GraphQL::Schema) do
-          orphan_types schema_types.values
+          add_type_and_traverse(schema_types.values, root: false)
+          orphan_types(schema_types.values.select { |t| t.respond_to?(:kind) && t.kind.object? })
           query schema_types[builder.query_name]
           mutation schema_types[builder.mutation_name]
           directives builder.schema_directives.values

data/lib/graphql/stitching/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Stitching
-    VERSION = "1.2.2"
+    VERSION = "1.2.3"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-stitching
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.2.3
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-11 00:00:00.000000000 Z
+date: 2024-04-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -82,6 +82,7 @@ files:
 - docs/README.md
 - docs/client.md
 - docs/composer.md
+- docs/federation_entities.md
 - docs/http_executable.md
 - docs/images/library.png
 - docs/images/merging.png
@@ -104,6 +105,9 @@ files:
 - examples/merged_types/remote1.rb
 - examples/merged_types/remote2.rb
 - gemfiles/graphql_1.13.9.gemfile
+- gemfiles/graphql_2.0.0.gemfile
+- gemfiles/graphql_2.1.0.gemfile
+- gemfiles/graphql_2.2.0.gemfile
 - graphql-stitching.gemspec
 - lib/graphql/stitching.rb
 - lib/graphql/stitching/boundary.rb