graphql-stitching 1.6.2 → 1.7.1

data/lib/graphql/stitching/supergraph/from_definition.rb

@@ -10,17 +10,29 @@ module GraphQL::Stitching
       end
 
       def from_definition(schema, executables:)
-        schema = GraphQL::Schema.from_definition(schema) if schema.is_a?(String)
+        if schema.is_a?(String)
+          schema = if GraphQL::Stitching.supports_visibility?
+            GraphQL::Schema.from_definition(schema, base_types: BASE_TYPES)
+          else
+            GraphQL::Schema.from_definition(schema)
+          end
+        end
+
         field_map = {}
         resolver_map = {}
         possible_locations = {}
+        visibility_profiles = if (visibility_def = schema.directives[GraphQL::Stitching.visibility_directive])
+          visibility_def.get_argument("profiles").default_value
+        else
+          []
+        end
 
         schema.types.each do |type_name, type|
           next if type.introspection?
 
           # Collect/build key definitions for each type
           locations_by_key = type.directives.each_with_object({}) do |directive, memo|
-            next unless directive.graphql_name == Composer::KeyDirective.graphql_name
+            next unless directive.graphql_name == Directives::SupergraphKey.graphql_name
 
             kwargs = directive.arguments.keyword_arguments
             memo[kwargs[:key]] ||= []
@@ -32,10 +44,10 @@ module GraphQL::Stitching
           end
 
           # Collect/build resolver definitions for each type
-          type.directives.each do |directive|
-            next unless directive.graphql_name == Composer::ResolverDirective.graphql_name
+          type.directives.each do |d|
+            next unless d.graphql_name == Directives::SupergraphResolver.graphql_name
 
-            kwargs = directive.arguments.keyword_arguments
+            kwargs = d.arguments.keyword_arguments
             resolver_map[type_name] ||= []
             resolver_map[type_name] << TypeResolver.new(
               location: kwargs[:location],
@@ -52,8 +64,8 @@ module GraphQL::Stitching
           type.fields.each do |field_name, field|
             # Collection locations for each field definition
             field.directives.each do |d|
-              next unless d.graphql_name == Composer::SourceDirective.graphql_name
-
+              next unless d.graphql_name == Directives::SupergraphSource.graphql_name
+              
               location = d.arguments.keyword_arguments[:location]
               field_map[type_name] ||= {}
               field_map[type_name][field_name] ||= []
@@ -74,6 +86,7 @@ module GraphQL::Stitching
           schema: schema,
           fields: field_map,
           resolvers: resolver_map,
+          visibility_profiles: visibility_profiles,
           executables: executables,
         )
       end

data/lib/graphql/stitching/supergraph/types.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module GraphQL::Stitching
+  class Supergraph
+    module Visibility
+      def visible?(ctx)
+        profile = ctx[:visibility_profile]
+        return true if profile.nil?
+
+        directive = directives.find { _1.graphql_name == GraphQL::Stitching.visibility_directive }
+        return true if directive.nil?
+
+        profiles = directive.arguments.keyword_arguments[:profiles]
+        return true if profiles.nil?
+
+        profiles.include?(profile)
+      end
+    end
+    
+    class ArgumentType < GraphQL::Schema::Argument
+      include Visibility
+    end
+
+    class FieldType < GraphQL::Schema::Field
+      include Visibility
+      argument_class(ArgumentType)
+    end
+
+    class InputObjectType < GraphQL::Schema::InputObject
+      extend Visibility
+      argument_class(ArgumentType)
+    end
+
+    module InterfaceType
+      include GraphQL::Schema::Interface
+      field_class(FieldType)
+
+      definition_methods do
+        include Visibility
+      end
+    end
+
+    class ObjectType < GraphQL::Schema::Object
+      extend Visibility
+      field_class(FieldType)
+    end
+
+    class EnumValueType < GraphQL::Schema::EnumValue
+      include Visibility
+    end
+
+    class EnumType < GraphQL::Schema::Enum
+      extend Visibility
+      enum_value_class(EnumValueType)
+    end
+    
+    class ScalarType < GraphQL::Schema::Scalar
+      extend Visibility
+    end
+
+    class UnionType < GraphQL::Schema::Union
+      extend Visibility
+    end
+
+    BASE_TYPES = {
+      enum: EnumType,
+      input_object: InputObjectType,
+      interface: InterfaceType,
+      object: ObjectType,
+      scalar: ScalarType,
+      union: UnionType,
+    }.freeze
+  end
+end

data/lib/graphql/stitching/supergraph.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "supergraph/types"
 require_relative "supergraph/from_definition"
 
 module GraphQL
@@ -21,7 +22,7 @@ module GraphQL
       attr_reader :memoized_introspection_types
       attr_reader :locations_by_type_and_field
 
-      def initialize(schema:, fields: {}, resolvers: {}, executables: {})
+      def initialize(schema:, fields: {}, resolvers: {}, visibility_profiles: [], executables: {})
         @schema = schema
         @resolvers = resolvers
         @resolvers_by_version = nil
@@ -49,11 +50,18 @@ module GraphQL
           end
         end.freeze
 
-        @schema.use(GraphQL::Schema::AlwaysVisible)
+        if visibility_profiles.any?
+          profiles = visibility_profiles.each_with_object({ nil => {} }) { |p, m| m[p.to_s] = {} }
+          @schema.use(GraphQL::Schema::Visibility, profiles: profiles)
+        else
+          @schema.use(GraphQL::Schema::AlwaysVisible)
+        end
       end
 
-      def to_definition
-        @schema.to_definition
+      def to_definition(visibility_profile: nil)
+        @schema.to_definition(context: { 
+          visibility_profile: visibility_profile,
+        }.tap(&:compact!))
       end
 
       def resolvers_by_version

data/lib/graphql/stitching/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Stitching
-    VERSION = "1.6.2"
+    VERSION = "1.7.1"
   end
 end

data/lib/graphql/stitching.rb

@@ -32,8 +32,6 @@ module GraphQL
     end
 
     class << self
-      attr_writer :stitch_directive
-
       # Proc used to compute digests; uses SHA2 by default.
       # @returns [Proc] proc used to compute digests.
       def digest(&block)
@@ -49,10 +47,31 @@ module GraphQL
       def stitch_directive
         @stitch_directive ||= "stitch"
       end
+
+      attr_writer :stitch_directive
+
+      # Name of the directive used to denote member visibilities.
+      # @returns [String] name of the visibility directive.
+      def visibility_directive
+        @visibility_directive ||= "visibility"
+      end
+
+      attr_writer :visibility_directive
+
+      MIN_VISIBILITY_VERSION = "2.5.3"
+
+      # @returns Boolean true if GraphQL::Schema::Visibility is fully supported
+      def supports_visibility?
+        return @supports_visibility if defined?(@supports_visibility)
+
+        # Requires `Visibility` (v2.4) with nil profile support (v2.5.3)
+        @supports_visibility = Gem::Version.new(GraphQL::VERSION) >= Gem::Version.new(MIN_VISIBILITY_VERSION)
+      end
     end
   end
 end
 
+require_relative "stitching/directives"
 require_relative "stitching/supergraph"
 require_relative "stitching/client"
 require_relative "stitching/composer"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-stitching
 version: !ruby/object:Gem::Version
-  version: 1.6.2
+  version: 1.7.1
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-26 00:00:00.000000000 Z
+date: 2025-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -79,19 +79,20 @@ files:
 - LICENSE
 - README.md
 - Rakefile
-- docs/README.md
-- docs/client.md
-- docs/composer.md
-- docs/federation_entities.md
-- docs/http_executable.md
+- docs/composing_a_supergraph.md
+- docs/error_handling.md
+- docs/executables.md
 - docs/images/library.png
 - docs/images/merging.png
 - docs/images/stitching.png
-- docs/mechanics.md
-- docs/request.md
+- docs/introduction.md
+- docs/merged_types.md
+- docs/merged_types_apollo.md
+- docs/performance.md
+- docs/query_planning.md
+- docs/serving_a_supergraph.md
 - docs/subscriptions.md
-- docs/supergraph.md
-- docs/type_resolver.md
+- docs/visibility.md
 - examples/file_uploads/Gemfile
 - examples/file_uploads/Procfile
 - examples/file_uploads/README.md
@@ -161,10 +162,10 @@ files:
 - lib/graphql/stitching/client.rb
 - lib/graphql/stitching/composer.rb
 - lib/graphql/stitching/composer/base_validator.rb
-- lib/graphql/stitching/composer/supergraph_directives.rb
 - lib/graphql/stitching/composer/type_resolver_config.rb
 - lib/graphql/stitching/composer/validate_interfaces.rb
 - lib/graphql/stitching/composer/validate_type_resolvers.rb
+- lib/graphql/stitching/directives.rb
 - lib/graphql/stitching/executor.rb
 - lib/graphql/stitching/executor/root_source.rb
 - lib/graphql/stitching/executor/shaper.rb
@@ -177,6 +178,7 @@ files:
 - lib/graphql/stitching/request/skip_include.rb
 - lib/graphql/stitching/supergraph.rb
 - lib/graphql/stitching/supergraph/from_definition.rb
+- lib/graphql/stitching/supergraph/types.rb
 - lib/graphql/stitching/type_resolver.rb
 - lib/graphql/stitching/type_resolver/arguments.rb
 - lib/graphql/stitching/type_resolver/keys.rb

data/docs/README.md

@@ -1,19 +0,0 @@
-## 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:
-
-- [Client](./client.md) - an out-of-the-box setup for performing stitched requests.
-- [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.
-- [Request](./request.md) - prepares a requested GraphQL document and variables for stitching.
-- [HttpExecutable](./http_executable.md) - proxies requests to remotes with multipart file upload support.
-
-Additional topics:
-
-- [Stitching mechanics](./mechanics.md) - more about building for stitching and how it operates.
-- [Subscriptions](./subscriptions.md) - explore how to stitch realtime event subscriptions.
-- [Federation entities](./federation_entities.md) - more about Apollo Federation compatibility.

data/docs/client.md

@@ -1,107 +0,0 @@
-## GraphQL::Stitching::Client
-
-The `Client` is an out-of-the-box convenience with all stitching components assembled into a default workflow. A client is designed to work for most common needs, though you're welcome to assemble the component parts into your own configuration (see the [client source](../lib/graphql/stitching/client.rb) for an example). A client 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 { ..."
-
-client = GraphQL::Stitching::Client.new(locations: {
-  products: {
-    schema: GraphQL::Schema.from_definition(movies_schema),
-    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3000"),
-    stitch: [{ field_name: "products", key: "id" }],
-  },
-  showtimes: {
-    schema: GraphQL::Schema.from_definition(showtimes_schema),
-    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3001"),
-  },
-  my_local: {
-    schema: MyLocal::GraphQL::Schema,
-  },
-})
-```
-
-Alternatively, you may pass a prebuilt `Supergraph` instance to the `Client` constructor. This is useful when [exporting and rehydrating](./supergraph.md#export-and-caching) supergraph instances, which bypasses the need for runtime composition:
-
-```ruby
-supergraph_sdl = File.read("precomposed_schema.graphql")
-supergraph = GraphQL::Stitching::Supergraph.from_definition(
-  supergraph_sdl,
-  executables: { ... },
-)
-
-client = GraphQL::Stitching::Client.new(supergraph: supergraph)
-```
-
-### Execution
-
-A client 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 stitching client becomes mostly a drop-in replacement to executing on a `GraphQL::Schema` instance:
-
-```ruby
-result = client.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 client hooks.
-
-### Cache hooks
-
-The client provides cache hooks to enable caching query plans across requests. Without caching, every request made to the client 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
-client.on_cache_read do |request|
-  $cache.get(request.digest) # << 3P code
-end
-
-client.on_cache_write do |request, payload|
-  $cache.set(request.digest, payload) # << 3P code
-end
-```
-
-All request digests use SHA2 by default. You can swap in [a faster algorithm](https://github.com/Shopify/blake3-rb) and/or add base scoping by reconfiguring the stitching library:
-
-```ruby
-GraphQL::Stitching.digest { |str| Digest::MD5.hexdigest("v2/#{str}") }
-```
-
-Note that inlined input data works against caching, so you should _avoid_ these input literals when possible:
-
-```graphql
-query {
-  product(id: "1") { name }
-}
-```
-
-Instead, leverage query variables so that the document body remains consistent across requests:
-
-```graphql
-query($id: ID!) {
-  product(id: $id) { name }
-}
-
-# variables: { "id" => "1" }
-```
-
-### Error hooks
-
-The client 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 client to add to the [GraphQL errors](https://spec.graphql.org/June2018/#sec-Errors) result.
-
-```ruby
-client.on_error do |request, err|
-  # log the error
-  Bugsnag.notify(err)
-
-  # return a formatted message for the public response
-  "Whoops, please contact support abount request '#{request.context[:request_id]}'"
-end
-```

data/docs/composer.md

@@ -1,125 +0,0 @@
-## GraphQL::Stitching::Composer
-
-A `Composer` receives many individual `GraphQL::Schema` instances representing various graph locations and _composes_ them into one combined [`Supergraph`](./supergraph.md) that is validated for integrity.
-
-### Configuring composition
-
-A `Composer` may be constructed with optional settings that tune how it builds a schema:
-
-```ruby
-composer = GraphQL::Stitching::Composer.new(
-  query_name: "Query",
-  mutation_name: "Mutation",
-  subscription_name: "Subscription",
-  description_merger: ->(values_by_location, info) { values_by_location.values.join("\n") },
-  deprecation_merger: ->(values_by_location, info) { values_by_location.values.first },
-  default_value_merger: ->(values_by_location, info) { values_by_location.values.first },
-  directive_kwarg_merger: ->(values_by_location, info) { values_by_location.values.last },
-  root_field_location_selector: ->(locations, info) { locations.last },
-)
-```
-
-Constructor arguments:
-
-- **`query_name:`** _optional_, the name of the root query type in the composed schema; `Query` by default. The root query types from all location schemas will be merged into this type, regardless of their local names.
-
-- **`mutation_name:`** _optional_, the name of the root mutation type in the composed schema; `Mutation` by default. The root mutation types from all location schemas will be merged into this type, regardless of their local names.
-
-- **`subscription_name:`** _optional_, the name of the root subscription type in the composed schema; `Subscription` by default. The root subscription types from all location schemas will be merged into this type, regardless of their local names.
-
-- **`description_merger:`** _optional_, a [value merger function](#value-merger-functions) for merging element description strings from across locations.
-
-- **`deprecation_merger:`** _optional_, a [value merger function](#value-merger-functions) for merging element deprecation strings from across locations.
-
-- **`default_value_merger:`** _optional_, a [value merger function](#value-merger-functions) for merging argument default values from across locations.
-
-- **`directive_kwarg_merger:`** _optional_, a [value merger function](#value-merger-functions) for merging directive keyword arguments from across locations.
-
-- **`root_field_location_selector:`** _optional_, selects a default routing location for root fields with multiple locations. Use this to prioritize sending root fields to their primary data sources (only applies while routing the root operation scope). This handler receives an array of possible locations and an info object with field information, and should return the prioritized location. The last location is used by default.
-
-#### Value merger functions
-
-Static data values such as element descriptions and directive arguments must also merge across locations. By default, the first non-null value encountered for a given element attribute is used. A value merger function may customize this process by selecting a different value or computing a new one:
-
-```ruby
-composer = GraphQL::Stitching::Composer.new(
-  description_merger: ->(values_by_location, info) { values_by_location.values.compact.join("\n") },
-)
-```
-
-A merger function receives `values_by_location` and `info` arguments; these provide possible values keyed by location and info about where in the schema these values were encountered:
-
-```ruby
-values_by_location = {
-  "storefronts" => "A fabulous data type.",
-  "products" => "An excellent data type.",
-}
-
-info = {
-  type_name: "Product",
-  # field_name: ...,
-  # argument_name: ...,
-  # directive_name: ...,
-}
-```
-
-### Performing composition
-
-Construct a `Composer` and call its `perform` method with location settings to compose a supergraph:
-
-```ruby
-storefronts_sdl = "type Query { ..."
-products_sdl = "type Query { ..."
-
-supergraph = GraphQL::Stitching::Composer.new.perform({
-  storefronts: {
-    schema: GraphQL::Schema.from_definition(storefronts_sdl),
-    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3001"),
-    stitch: [{ field_name: "storefront", key: "id" }],
-  },
-  products: {
-    schema: GraphQL::Schema.from_definition(products_sdl),
-    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3002"),
-  },
-  my_local: {
-    schema: MyLocalSchema,
-  },
-})
-
-combined_schema = supergraph.schema
-```
-
-Location settings have top-level keys that specify arbitrary location names, each of which provide:
-
-- **`schema:`** _required_, provides a `GraphQL::Schema` class for the location. This may be a class-based schema that inherits from `GraphQL::Schema`, or built from SDL (Schema Definition Language) string using `GraphQL::Schema.from_definition` and mapped to a remote location. The provided schema is only used for type reference and does not require any real data resolvers (unless it is also used as the location's executable, see below).
-
-- **`executable:`** _optional_, provides an executable resource to be called when delegating a request to this location. Executables are `GraphQL::Schema` classes or any object with a `.call(request, source, variables)` method that returns a GraphQL response. Omitting the executable option will use the location's provided `schema` as the executable resource.
-
-- **`stitch:`** _optional_, an array of configs used to dynamically apply `@stitch` directives to select root fields prior to composing. This is useful when you can't easily render stitching directives into a location's source schema.
-
-### Merge patterns
-
-The strategy used to merge source schemas into the combined schema is based on each element type:
-
-- Arguments of fields, directives, and `InputObject` types intersect for each parent element across locations (an element's 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.
-
-- `Object` and `Interface` types merge their fields and directives together:
-  - Common fields across locations must share a value type, and the weakest nullability is used.
-  - 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.
-
-- `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.
-
-- `Directive` definitions are added for all distinct names across locations:
-  - Stitching directives (both definitions and assignments) are omitted.
-
-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/http_executable.md

@@ -1,51 +0,0 @@
-## GraphQL::Stitching::HttpExecutable
-
-A `HttpExecutable` provides an out-of-the-box convenience for sending HTTP post requests to a remote location, or a base class for your own implementation with [GraphQL multipart uploads](https://github.com/jaydenseric/graphql-multipart-request-spec).
-
-```ruby
-exe = GraphQL::Stitching::HttpExecutable.new(
-  url: "http://localhost:3001",
-  headers: {
-    "Authorization" => "..."
-  }
-)
-```
-
-### GraphQL file uploads
-
-The [GraphQL Upload Spec](https://github.com/jaydenseric/graphql-multipart-request-spec) defines a multipart form structure for submitting GraphQL requests with file upload attachments. It's possible to pass these requests through stitched schemas using the following:
-
-#### 1. Input file uploads as Tempfile variables
-
-```ruby
-client.execute(
-  "mutation($file: Upload) { upload(file: $file) }",
-  variables: { "file" => Tempfile.new(...) }
-)
-```
-
-File uploads must enter the stitched schema as standard GraphQL variables with `Tempfile` values. The simplest way to recieve this input is to install [apollo_upload_server](https://github.com/jetruby/apollo_upload_server-ruby) into your stitching app's middleware so that multipart form submissions automatically unpack into standard variables.
-
-#### 2. Enable `HttpExecutable.upload_types`
-
-```ruby
-client = GraphQL::Stitching::Client.new(locations: {
-  alpha: {
-    schema: GraphQL::Schema.from_definition(...),
-    executable: GraphQL::Stitching::HttpExecutable.new(
-      url: "http://localhost:3000",
-      upload_types: ["Upload"], # << extract `Upload` scalars into multipart forms
-    ),
-  },
-  bravo: {
-    schema: GraphQL::Schema.from_definition(...),
-    executable: GraphQL::Stitching::HttpExecutable.new(
-      url: "http://localhost:3001"
-    ),
-  },
-})
-```
-
-A location's `HttpExecutable` can then re-package `Tempfile` variables into multipart forms before sending them upstream. This is enabled with an `upload_types` parameter that specifies which scalar names require form extraction. Enabling `upload_types` does add some additional subgraph request processing, so it should only be enabled for locations that will actually recieve file uploads.
-
-The upstream location will recieve a multipart form submission from stitching that can again be unpacked using [apollo_upload_server](https://github.com/jetruby/apollo_upload_server-ruby) or similar.