graphql-stitching 1.6.1 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da2c14565c38d14e4e49f51ff2027f89a2ee4c0313102083c9ea3baadbcd02d4
-  data.tar.gz: eec311845ed143af3f8d598c22f2b6026a46d34868fd7546abfb585a8fed6ebc
+  metadata.gz: 63b137317e57972e09c9926447c53ab26ac99a146557258e94b62abff305d096
+  data.tar.gz: e3a2217f5c04cc1a8a8412f15bb0ee5e6c4340869f945758735468c0903840f6
 SHA512:
-  metadata.gz: 87608b9f5391ec190e0d0f534e1a58447f056b37e37c3f569d908b2c7043d40ef38732b3bff6e4975d81d34b04bb84cd88f809b364d73aeade68675f8c35f35f
-  data.tar.gz: eb1e085ad36c36b52b0c871d9d8f3ff0ca5b6d29ff51c1ea6cd9564c0cdba8e554381615099a331426f4857b82049290287c79cc1338388a36027cb451aa3bb9
+  metadata.gz: 63ccfdcf28c02490946d2b7b9fef5dbe726cc47a214887010dc7dfa7f066d266bb7b2e5d899b13ad705060b8f7981904f47029a119c73c1aa582181d97ec6bec
+  data.tar.gz: d72baafd4419199658afbdba8a70a109a84da1e48e712344f568a5d4f75f5d0b2da3f3549a50370e528357fd003d9f8cbae825a490b2b0eed86c84528471855f

data/README.md

@@ -9,6 +9,7 @@ GraphQL stitching composes a single schema from multiple underlying GraphQL reso
 - Merged object and abstract types joining though multiple keys.
 - Shared objects, fields, enums, and inputs across locations.
 - Combining local and remote schemas.
+- [Visibility controls](./docs/visibility.md) for hiding schema elements.
 - [File uploads](./docs/http_executable.md) via multipart forms.
 - Tested with all minor versions of `graphql-ruby`.
 
@@ -171,11 +172,11 @@ GRAPHQL
 client = GraphQL::Stitching::Client.new(locations: {
   products: {
     schema: GraphQL::Schema.from_definition(products_schema),
-    executable:  GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3001"),
+    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3001"),
   },
   catalog: {
     schema: GraphQL::Schema.from_definition(catalog_schema),
-    executable:  GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3002"),
+    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3002"),
   },
 })
 ```
@@ -358,20 +359,12 @@ type Query {
 
 #### Class-based schemas
 
-The `@stitch` directive can be added to class-based schemas with a directive class:
+The `@stitch` directive can be added to class-based schemas with a directive definition provided by the library:
 
 ```ruby
-class StitchingResolver < GraphQL::Schema::Directive
-  graphql_name "stitch"
-  locations FIELD_DEFINITION
-  repeatable true
-  argument :key, String, required: true
-  argument :arguments, String, required: false
-end
-
 class Query < GraphQL::Schema::Object
   field :product, Product, null: false do
-    directive StitchingResolver, key: "id"
+    directive GraphQL::Stitching::Directives::Stitch, key: "id"
     argument :id, ID, required: true
   end
 end
@@ -485,6 +478,7 @@ The [Executor](./docs/executor.md) component builds atop the Ruby fiber-based im
 
 - [Deploying a stitched schema](./docs/mechanics.md#deploying-a-stitched-schema)
 - [Schema composition merge patterns](./docs/composer.md#merge-patterns)
+- [Visibility controls](./docs/visibility.md)
 - [Subscriptions tutorial](./docs/subscriptions.md)
 - [Field selection routing](./docs/mechanics.md#field-selection-routing)
 - [Root selection routing](./docs/mechanics.md#root-selection-routing)

data/docs/visibility.md

@@ -0,0 +1,168 @@
+# Visibility
+
+Visibility controls can hide parts of a supergraph from select audiences without compromising stitching operations. Restricted schema elements are hidden from introspection and validate as though they do not exist (which is different from traditional authorization where an element is acknowledged as restricted). Visibility is useful for managing multiple distributions of a schema for different audiences.
+
+Under the hood, this system wraps `GraphQL::Schema::Visibility` (with nil profile support) and requires at least GraphQL Ruby v2.5.3.
+
+## Example
+
+Schemas may include a `@visibility` directive that defines element _profiles_. A profile is just a label describing an API distribution (public, private, etc). When a request is assigned a visibility profile, it can only access elements belonging to that profile. Elements without an explicit `@visibility` constraint belong to all profiles. For example:
+
+_schemas/product_info.graphql_
+```graphql
+directive @stitch(key: String!) on FIELD_DEFINITION
+directive @visibility(profiles: [String!]!) on OBJECT | INTERFACE | UNION | INPUT_OBJECT | ENUM | SCALAR | FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE
+
+type Product {
+  id: ID!
+  title: String!
+  description: String!
+}
+
+type Query {
+  featuredProduct: Product
+  product(id: ID!): Product @stitch(key: "id") @visibility(profiles: ["private"])
+}
+```
+
+_schemas/product_prices.graphql_
+```graphql
+directive @stitch(key: String!) on FIELD_DEFINITION
+directive @visibility(profiles: [String!]!) on OBJECT | INTERFACE | UNION | INPUT_OBJECT | ENUM | SCALAR | FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE
+
+type Product {
+  id: ID! @visibility(profiles: [])
+  msrp: Float! @visibility(profiles: ["private"])
+  price: Float!
+}
+
+type Query {
+  products(ids: [ID!]!): [Product]! @stitch(key: "id") @visibility(profiles: ["private"])
+}
+```
+
+When composing a stitching client, the names of all possible visibility profiles that the supergraph responds to should be specified in composer options:
+
+```ruby
+client = GraphQL::Stitching::Client.new(
+  composer_options: {
+    visibility_profiles: ["public", "private"],
+  },
+  locations: {
+    info: {
+      schema: GraphQL::Schema.from_definition(File.read("schemas/product_info.graphql")),
+      executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3001"),
+    },
+    prices: {
+      schema: GraphQL::Schema.from_definition(File.read("schemas/product_prices.graphql")),
+      executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3002"),
+    },
+  }
+)
+```
+
+The client can then execute requests with a `visibility_profile` parameter in context that specifies the name of any profile the supergraph was composed with, or nil:
+
+```ruby
+query = %|{
+  featuredProduct {
+    title  # always visible
+    price  # always visible
+    msrp   # only visible to internal and nil profiles
+    id     # only visible to nil profile
+  }
+}|
+
+result = client.execute(query, context: { 
+  visibility_profile: "public", # << or private, or nil
+})
+```
+
+The `visibility_profile` parameter will select which visibility distribution to use while introspecting and validating the request. For example:
+
+- Using `visibility_profile: "public"` will say the `msrp` field does not exist (because it is restricted to "private").
+- Using `visibility_profile: "private"` will accesses the `msrp` field as usual. 
+- Using `visibility_profile: nil` will access the entire graph without any visibility constraints.
+
+The full potential of visibility comes when hiding stitching implementation details, such as the `id` field (which is the stitching key for the Product type). While the `id` field is hidden from all named profiles, it remains operational for the stitching implementation.
+
+## Adding visibility directives
+
+Add the `@visibility` directive into schemas using the library definition:
+
+```ruby
+class QueryType < GraphQL::Schema::Object
+  field :my_field, String, null: true do |f|
+    f.directive(GraphQL::Stitching::Directives::Visibility, profiles: ["private"])
+  end
+end
+
+class MySchema < GraphQL::Schema
+  directive(GraphQL::Stitching::Directives::Visibility)
+  query(QueryType)
+end
+```
+
+## Merging visibilities
+
+Visibility directives merge across schemas into the narrowest constraint possible. Profile sets for an element will intersect into its supergraph constraint:
+
+```graphql
+# location 1
+myField: String @visibility(profiles: ["a", "c"])
+
+# location 2
+myField: String @visibility(profiles: ["b", "c"])
+
+# merged supergraph
+myField: String @visibility(profiles: ["c"])
+```
+
+This may cause an element's profiles to intersect into an empty set, which means the element belongs to no profiles and will be hidden from all named distributions:
+
+```graphql
+# location 1
+myField: String @visibility(profiles: ["a"])
+
+# location 2
+myField: String @visibility(profiles: ["b"])
+
+# merged supergraph
+myField: String @visibility(profiles: [])
+```
+
+Locations may omit visibility information to give other locations full control. Remember that elements without a `@visibility` constraint belong to all profiles, which also applies while merging:
+
+```graphql
+# location 1
+myField: String
+
+# location 2
+myField: String @visibility(profiles: ["b"])
+
+# merged supergraph
+myField: String @visibility(profiles: ["b"])
+```
+
+## Type controls
+
+Visibility controls can be applied to almost all GraphQL schema elements, including:
+
+- Types (Object, Interface, Union, Enum, Scalar, InputObject)
+- Fields (of Object and Interface)
+- Arguments (of Field and InputObject)
+- Enum values
+
+While the visibility of type members (fields, arguments, and enum values) are pretty intuitive, the visibility of parent types is far more nuanced as constraints start to cascade:
+
+```graphql
+type Widget @visibility(profiles: ["private"]) {
+  title: String
+}
+
+type Query {
+  widget: Widget # << GETS HIDDEN
+}
+```
+
+In this example, hiding the `Widget` type will also hide the `Query.widget` field that returns it.

data/lib/graphql/stitching/client.rb

@@ -13,16 +13,18 @@ module GraphQL
       # Builds a new client instance. Either `supergraph` or `locations` configuration is required.
       # @param supergraph [Supergraph] optional, a pre-composed supergraph that bypasses composer setup.
       # @param locations [Hash<Symbol, Hash<Symbol, untyped>>] optional, composer configurations for each graph location.
-      # @param composer [Composer] optional, a pre-configured composer instance for use with `locations` configuration.
-      def initialize(locations: nil, supergraph: nil, composer: nil)
+      # @param composer_options [Hash] optional, composer options for configuring composition.
+      def initialize(locations: nil, supergraph: nil, composer_options: {})
         @supergraph = if locations && supergraph
           raise ArgumentError, "Cannot provide both locations and a supergraph."
         elsif supergraph && !supergraph.is_a?(Supergraph)
           raise ArgumentError, "Provided supergraph must be a GraphQL::Stitching::Supergraph instance."
+        elsif supergraph && composer_options.any?
+          raise ArgumentError, "Cannot provide composer options with a pre-built supergraph."
         elsif supergraph
           supergraph
         else
-          composer ||= Composer.new
+          composer = Composer.new(**composer_options)
           composer.perform(locations)
         end
 

data/lib/graphql/stitching/composer.rb

@@ -22,6 +22,9 @@ module GraphQL
 
       # @api private
       BASIC_VALUE_MERGER = ->(values_by_location, _info) { values_by_location.values.find { !_1.nil? } }
+      
+      # @api private
+      VISIBILITY_PROFILES_MERGER = ->(values_by_location, _info) { values_by_location.values.reduce(:&) }
 
       # @api private
       BASIC_ROOT_FIELD_LOCATION_SELECTOR = ->(locations, _info) { locations.last }
@@ -51,6 +54,7 @@ module GraphQL
         query_name: "Query",
         mutation_name: "Mutation",
         subscription_name: "Subscription",
+        visibility_profiles: [],
         description_merger: nil,
         deprecation_merger: nil,
         default_value_merger: nil,
@@ -70,6 +74,7 @@ module GraphQL
         @resolver_map = {}
         @resolver_configs = {}
         @mapped_type_names = {}
+        @visibility_profiles = Set.new(visibility_profiles)
         @subgraph_directives_by_name_and_location = nil
         @subgraph_types_by_name_and_location = nil
         @schema_directives = nil
@@ -82,9 +87,16 @@ module GraphQL
 
         schemas, executables = prepare_locations_input(locations_input)
 
+        directives_to_omit = [
+          GraphQL::Stitching.stitch_directive,
+          Directives::SupergraphKey.graphql_name,
+          Directives::SupergraphResolver.graphql_name,
+          Directives::SupergraphSource.graphql_name,
+        ]
+
         # "directive_name" => "location" => subgraph_directive
         @subgraph_directives_by_name_and_location = schemas.each_with_object({}) do |(location, schema), memo|
-          (schema.directives.keys - schema.default_directives.keys - GraphQL::Stitching.stitching_directive_names).each do |directive_name|
+          (schema.directives.keys - schema.default_directives.keys - directives_to_omit).each do |directive_name|
             memo[directive_name] ||= {}
             memo[directive_name][location] = schema.directives[directive_name]
           end
@@ -154,25 +166,30 @@ module GraphQL
 
         builder = self
         schema = Class.new(GraphQL::Schema) do
+          object_types = schema_types.values.select { |t| t.respond_to?(:kind) && t.kind.object? }
           add_type_and_traverse(schema_types.values, root: false)
-          orphan_types(schema_types.values.select { |t| t.respond_to?(:kind) && t.kind.object? })
+          orphan_types(object_types)
           query schema_types[builder.query_name]
           mutation schema_types[builder.mutation_name]
           subscription schema_types[builder.subscription_name]
           directives builder.schema_directives.values
 
+          object_types.each do |t|
+            t.interfaces.each { _1.orphan_types(t) }
+          end
+
           own_orphan_types.clear
         end
 
         select_root_field_locations(schema)
         expand_abstract_resolvers(schema, schemas)
+        apply_supergraph_directives(schema, @resolver_map, @field_map)
 
-        supergraph = Supergraph.new(
-          schema: schema,
-          fields: @field_map,
-          resolvers: @resolver_map,
-          executables: executables,
-        )
+        if (visibility_def = schema.directives[GraphQL::Stitching.visibility_directive])
+          visibility_def.get_argument("profiles").default_value(@visibility_profiles.to_a.sort)
+        end
+
+        supergraph = Supergraph.from_definition(schema, executables: executables)
 
         COMPOSITION_VALIDATORS.each do |validator_class|
           validator_class.new.perform(supergraph, self)
@@ -228,7 +245,7 @@ module GraphQL
 
         builder = self
 
-        Class.new(GraphQL::Schema::Scalar) do
+        Class.new(GraphQL::Stitching::Supergraph::ScalarType) do
           graphql_name(type_name)
           description(builder.merge_descriptions(type_name, types_by_location))
           builder.build_merged_directives(type_name, types_by_location, self)
@@ -255,7 +272,7 @@ module GraphQL
           end
         end
 
-        Class.new(GraphQL::Schema::Enum) do
+        Class.new(GraphQL::Stitching::Supergraph::EnumType) do
           graphql_name(type_name)
           description(builder.merge_descriptions(type_name, types_by_location))
           builder.build_merged_directives(type_name, types_by_location, self)
@@ -277,7 +294,7 @@ module GraphQL
       def build_object_type(type_name, types_by_location)
         builder = self
 
-        Class.new(GraphQL::Schema::Object) do
+        Class.new(GraphQL::Stitching::Supergraph::ObjectType) do
           graphql_name(type_name)
           description(builder.merge_descriptions(type_name, types_by_location))
 
@@ -297,7 +314,7 @@ module GraphQL
         builder = self
 
         Module.new do
-          include GraphQL::Schema::Interface
+          include GraphQL::Stitching::Supergraph::InterfaceType
           graphql_name(type_name)
           description(builder.merge_descriptions(type_name, types_by_location))
 
@@ -316,7 +333,7 @@ module GraphQL
       def build_union_type(type_name, types_by_location)
         builder = self
 
-        Class.new(GraphQL::Schema::Union) do
+        Class.new(GraphQL::Stitching::Supergraph::UnionType) do
           graphql_name(type_name)
           description(builder.merge_descriptions(type_name, types_by_location))
 
@@ -331,7 +348,7 @@ module GraphQL
       def build_input_object_type(type_name, types_by_location)
         builder = self
 
-        Class.new(GraphQL::Schema::InputObject) do
+        Class.new(GraphQL::Stitching::Supergraph::InputObjectType) do
           graphql_name(type_name)
           description(builder.merge_descriptions(type_name, types_by_location))
           builder.build_merged_arguments(type_name, types_by_location, self)
@@ -442,6 +459,7 @@ module GraphQL
         end
 
         directives_by_name_location.each do |directive_name, directives_by_location|
+          kwarg_merger = @directive_kwarg_merger
           directive_class = @schema_directives[directive_name]
           next unless directive_class
 
@@ -458,8 +476,20 @@ module GraphQL
             end
           end
 
+          if directive_class.graphql_name == GraphQL::Stitching.visibility_directive
+            unless GraphQL::Stitching.supports_visibility?
+              raise CompositionError, "Using `@#{GraphQL::Stitching.visibility_directive}` directive " \
+                "for schema visibility controls requires GraphQL Ruby v#{GraphQL::Stitching::MIN_VISIBILITY_VERSION} or later."
+            end
+
+            if (profiles = kwarg_values_by_name_location["profiles"])
+              @visibility_profiles.merge(profiles.each_value.reduce(&:|))
+              kwarg_merger = VISIBILITY_PROFILES_MERGER
+            end
+          end
+
           kwargs = kwarg_values_by_name_location.each_with_object({}) do |(kwarg_name, kwarg_values_by_location), memo|
-            memo[kwarg_name.to_sym] = @directive_kwarg_merger.call(kwarg_values_by_location, {
+            memo[kwarg_name.to_sym] = kwarg_merger.call(kwarg_values_by_location, {
               type_name: type_name,
               field_name: field_name,
               argument_name: argument_name,
@@ -670,6 +700,72 @@ module GraphQL
           memo[enum_name] << :write
         end
       end
+
+      def apply_supergraph_directives(schema, resolvers_by_type_name, locations_by_type_and_field)
+        schema_directives = {}
+        schema.types.each do |type_name, type|
+          if resolvers_for_type = resolvers_by_type_name.dig(type_name)
+            # Apply key directives for each unique type/key/location
+            # (this allows keys to be composite selections and/or omitted from the supergraph schema)
+            keys_for_type = resolvers_for_type.each_with_object({}) do |resolver, memo|
+              memo[resolver.key.to_definition] ||= Set.new
+              memo[resolver.key.to_definition].merge(resolver.key.locations)
+            end
+  
+            keys_for_type.each do |key, locations|
+              locations.each do |location|
+                schema_directives[Directives::SupergraphKey.graphql_name] ||= Directives::SupergraphKey
+                type.directive(Directives::SupergraphKey, key: key, location: location)
+              end
+            end
+  
+            # Apply resolver directives for each unique query resolver
+            resolvers_for_type.each do |resolver|
+              params = {
+                location: resolver.location,
+                field: resolver.field,
+                list: resolver.list? || nil,
+                key: resolver.key.to_definition,
+                arguments: resolver.arguments.map(&:to_definition).join(", "),
+                argument_types: resolver.arguments.map(&:to_type_definition).join(", "),
+                type_name: (resolver.type_name if resolver.type_name != type_name),
+              }
+  
+              schema_directives[Directives::SupergraphResolver.graphql_name] ||= Directives::SupergraphResolver
+              type.directive(Directives::SupergraphResolver, **params.tap(&:compact!))
+            end
+          end
+  
+          next unless type.kind.fields? && !type.introspection?
+  
+          type.fields.each do |field_name, field|
+            if field.owner != type
+              # make a local copy of fields inherited from an interface
+              # to assure that source attributions reflect the object, not the interface.
+              field = type.field(
+                field.graphql_name,
+                description: field.description,
+                deprecation_reason: field.deprecation_reason,
+                type: Util.unwrap_non_null(field.type),
+                null: !field.type.non_null?,
+                connection: false,
+                camelize: false,
+              )
+            end
+            
+            locations_for_field = locations_by_type_and_field.dig(type_name, field_name)
+            next if locations_for_field.nil?
+  
+            # Apply source directives to annotate the possible locations of each field
+            locations_for_field.each do |location|
+              schema_directives[Directives::SupergraphSource.graphql_name] ||= Directives::SupergraphSource
+              field.directive(Directives::SupergraphSource, location: location)
+            end
+          end
+        end
+        
+        schema_directives.each_value { |directive_class| schema.directive(directive_class) }
+      end
     end
   end
 end

data/lib/graphql/stitching/directives.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module GraphQL::Stitching
+  module Directives
+    class Stitch < GraphQL::Schema::Directive
+      graphql_name "stitch"
+      locations FIELD_DEFINITION
+      argument :key, String, required: true
+      argument :arguments, String, required: false
+      argument :type_name, String, required: false
+      repeatable true
+    end
+
+    class Visibility < GraphQL::Schema::Directive
+      graphql_name "visibility"
+      locations(
+        OBJECT, INTERFACE, UNION, INPUT_OBJECT, ENUM, SCALAR, 
+        FIELD_DEFINITION, ARGUMENT_DEFINITION, INPUT_FIELD_DEFINITION, ENUM_VALUE
+      )
+      argument :profiles, [String, null: false], required: true
+    end
+
+    class SupergraphKey < GraphQL::Schema::Directive
+      graphql_name "key"
+      locations OBJECT, INTERFACE, UNION
+      argument :key, String, required: true
+      argument :location, String, required: true
+      repeatable true
+    end
+
+    class SupergraphResolver < GraphQL::Schema::Directive
+      graphql_name "resolver"
+      locations OBJECT, INTERFACE, UNION
+      argument :location, String, required: true
+      argument :list, Boolean, required: false
+      argument :key, String, required: true
+      argument :field, String, required: true
+      argument :arguments, String, required: true
+      argument :argument_types, String, required: true
+      argument :type_name, String, required: false
+      repeatable true
+    end
+    
+    class SupergraphSource < GraphQL::Schema::Directive
+      graphql_name "source"
+      locations FIELD_DEFINITION
+      argument :location, String, required: true
+      repeatable true
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module GraphQL::Stitching
+  class Supergraph
+    class << self
+      def validate_executable!(location, executable)
+        return true if executable.is_a?(Class) && executable <= GraphQL::Schema
+        return true if executable && executable.respond_to?(:call)
+        raise StitchingError, "Invalid executable provided for location `#{location}`."
+      end
+
+      def from_definition(schema, executables:)
+        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 == Directives::SupergraphKey.graphql_name
+
+            kwargs = directive.arguments.keyword_arguments
+            memo[kwargs[:key]] ||= []
+            memo[kwargs[:key]] << kwargs[:location]
+          end
+
+          key_definitions = locations_by_key.each_with_object({}) do |(key, locations), memo|
+            memo[key] = TypeResolver.parse_key(key, locations)
+          end
+
+          # Collect/build resolver definitions for each type
+          type.directives.each do |d|
+            next unless d.graphql_name == Directives::SupergraphResolver.graphql_name
+
+            kwargs = d.arguments.keyword_arguments
+            resolver_map[type_name] ||= []
+            resolver_map[type_name] << TypeResolver.new(
+              location: kwargs[:location],
+              type_name: kwargs.fetch(:type_name, type_name),
+              field: kwargs[:field],
+              list: kwargs[:list] || false,
+              key: key_definitions[kwargs[:key]],
+              arguments: TypeResolver.parse_arguments_with_type_defs(kwargs[:arguments], kwargs[:argument_types]),
+            )
+          end
+
+          next unless type.kind.fields?
+
+          type.fields.each do |field_name, field|
+            # Collection locations for each field definition
+            field.directives.each do |d|
+              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] ||= []
+              field_map[type_name][field_name] << location
+              possible_locations[location] = true
+            end
+          end
+        end
+
+        executables = possible_locations.keys.each_with_object({}) do |location, memo|
+          executable = executables[location] || executables[location.to_sym]
+          if validate_executable!(location, executable)
+            memo[location] = executable
+          end
+        end
+
+        new(
+          schema: schema,
+          fields: field_map,
+          resolvers: resolver_map,
+          visibility_profiles: visibility_profiles,
+          executables: executables,
+        )
+      end
+    end
+  end
+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,6 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "supergraph/to_definition"
+require_relative "supergraph/types"
+require_relative "supergraph/from_definition"
 
 module GraphQL
   module Stitching
@@ -16,23 +17,25 @@ module GraphQL
       # @return [Hash<String, Executable>] a map of executable resources by location.
       attr_reader :executables
 
-      attr_reader :resolvers, :locations_by_type_and_field
+      attr_reader :resolvers
+      attr_reader :memoized_schema_types
+      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
         @fields_by_type_and_location = nil
         @locations_by_type = nil
-        @memoized_introspection_types = nil
+        @memoized_introspection_types = @schema.introspection_system.types
+        @memoized_schema_types = @schema.types
         @memoized_schema_fields = {}
-        @memoized_schema_types = nil
         @possible_keys_by_type = {}
         @possible_keys_by_type_and_location = {}
-        @static_validator = nil
 
         # add introspection types into the fields mapping
-        @locations_by_type_and_field = memoized_introspection_types.each_with_object(fields) do |(type_name, type), memo|
+        @locations_by_type_and_field = @memoized_introspection_types.each_with_object(fields) do |(type_name, type), memo|
           next unless type.kind.fields?
 
           memo[type_name] = type.fields.keys.each_with_object({}) do |field_name, m|
@@ -46,6 +49,17 @@ module GraphQL
             memo[location.to_s] = executable
           end
         end.freeze
+
+        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
       end
 
       def resolvers_by_version
@@ -62,17 +76,9 @@ module GraphQL
         @executables.keys.reject { _1 == SUPERGRAPH_LOCATION }
       end
 
-      def memoized_introspection_types
-        @memoized_introspection_types ||= schema.introspection_system.types
-      end
-
-      def memoized_schema_types
-        @memoized_schema_types ||= @schema.types
-      end
-
       def memoized_schema_fields(type_name)
         @memoized_schema_fields[type_name] ||= begin
-          fields = memoized_schema_types[type_name].fields
+          fields = @memoized_schema_types[type_name].fields
           @schema.introspection_system.dynamic_fields.each do |field|
             fields[field.name] ||= field # adds __typename
           end

data/lib/graphql/stitching/type_resolver.rb

@@ -65,6 +65,10 @@ module GraphQL
           argument_types: arguments.map(&:to_type_definition).join(", "),
         }.tap(&:compact!)
       end
+
+      def inspect
+        as_json.to_json
+      end
     end
   end
 end

data/lib/graphql/stitching/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Stitching
-    VERSION = "1.6.1"
+    VERSION = "1.7.0"
   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)
@@ -50,15 +48,30 @@ module GraphQL
         @stitch_directive ||= "stitch"
       end
 
-      # Names of stitching directives to omit from the composed supergraph.
-      # @returns [Array<String>] list of stitching directive names.
-      def stitching_directive_names
-        [stitch_directive]
+      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.1
+  version: 1.7.0
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-22 00:00:00.000000000 Z
+date: 2025-05-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -92,6 +92,7 @@ files:
 - 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
@@ -164,6 +165,7 @@ files:
 - 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
@@ -175,10 +177,8 @@ files:
 - lib/graphql/stitching/request.rb
 - lib/graphql/stitching/request/skip_include.rb
 - lib/graphql/stitching/supergraph.rb
-- lib/graphql/stitching/supergraph/key_directive.rb
-- lib/graphql/stitching/supergraph/resolver_directive.rb
-- lib/graphql/stitching/supergraph/source_directive.rb
-- lib/graphql/stitching/supergraph/to_definition.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/lib/graphql/stitching/supergraph/key_directive.rb

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-module GraphQL::Stitching
-  class Supergraph
-    class KeyDirective < GraphQL::Schema::Directive
-      graphql_name "key"
-      locations OBJECT, INTERFACE, UNION
-      argument :key, String, required: true
-      argument :location, String, required: true
-      repeatable true
-    end
-  end
-end

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

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-module GraphQL::Stitching
-  class Supergraph
-    class ResolverDirective < GraphQL::Schema::Directive
-      graphql_name "resolver"
-      locations OBJECT, INTERFACE, UNION
-      argument :location, String, required: true
-      argument :list, Boolean, required: false
-      argument :key, String, required: true
-      argument :field, String, required: true
-      argument :arguments, String, required: true
-      argument :argument_types, String, required: true
-      argument :type_name, String, required: false
-      repeatable true
-    end
-  end
-end

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

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-module GraphQL::Stitching
-  class Supergraph
-    class SourceDirective < GraphQL::Schema::Directive
-      graphql_name "source"
-      locations FIELD_DEFINITION
-      argument :location, String, required: true
-      repeatable true
-    end
-  end
-end

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

@@ -1,164 +0,0 @@
-# frozen_string_literal: true
-require_relative "./key_directive"
-require_relative "./resolver_directive"
-require_relative "./source_directive"
-
-module GraphQL::Stitching
-  class Supergraph
-    class << self
-      def validate_executable!(location, executable)
-        return true if executable.is_a?(Class) && executable <= GraphQL::Schema
-        return true if executable && executable.respond_to?(:call)
-        raise StitchingError, "Invalid executable provided for location `#{location}`."
-      end
-
-      def from_definition(schema, executables:)
-        schema = GraphQL::Schema.from_definition(schema) if schema.is_a?(String)
-        field_map = {}
-        resolver_map = {}
-        possible_locations = {}
-
-        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 == KeyDirective.graphql_name
-
-            kwargs = directive.arguments.keyword_arguments
-            memo[kwargs[:key]] ||= []
-            memo[kwargs[:key]] << kwargs[:location]
-          end
-
-          key_definitions = locations_by_key.each_with_object({}) do |(key, locations), memo|
-            memo[key] = TypeResolver.parse_key(key, locations)
-          end
-
-          # Collect/build resolver definitions for each type
-          type.directives.each do |directive|
-            next unless directive.graphql_name == ResolverDirective.graphql_name
-
-            kwargs = directive.arguments.keyword_arguments
-            resolver_map[type_name] ||= []
-            resolver_map[type_name] << TypeResolver.new(
-              location: kwargs[:location],
-              type_name: kwargs.fetch(:type_name, type_name),
-              field: kwargs[:field],
-              list: kwargs[:list] || false,
-              key: key_definitions[kwargs[:key]],
-              arguments: TypeResolver.parse_arguments_with_type_defs(kwargs[:arguments], kwargs[:argument_types]),
-            )
-          end
-
-          next unless type.kind.fields?
-
-          type.fields.each do |field_name, field|
-            # Collection locations for each field definition
-            field.directives.each do |d|
-              next unless d.graphql_name == SourceDirective.graphql_name
-
-              location = d.arguments.keyword_arguments[:location]
-              field_map[type_name] ||= {}
-              field_map[type_name][field_name] ||= []
-              field_map[type_name][field_name] << location
-              possible_locations[location] = true
-            end
-          end
-        end
-
-        executables = possible_locations.keys.each_with_object({}) do |location, memo|
-          executable = executables[location] || executables[location.to_sym]
-          if validate_executable!(location, executable)
-            memo[location] = executable
-          end
-        end
-
-        new(
-          schema: schema,
-          fields: field_map,
-          resolvers: resolver_map,
-          executables: executables,
-        )
-      end
-    end
-
-    def to_definition
-      if @schema.directives[KeyDirective.graphql_name].nil?
-        @schema.directive(KeyDirective)
-      end
-      if @schema.directives[ResolverDirective.graphql_name].nil?
-        @schema.directive(ResolverDirective)
-      end
-      if @schema.directives[SourceDirective.graphql_name].nil?
-        @schema.directive(SourceDirective)
-      end
-
-      @schema.types.each do |type_name, type|
-        if resolvers_for_type = @resolvers.dig(type_name)
-          # Apply key directives for each unique type/key/location
-          # (this allows keys to be composite selections and/or omitted from the supergraph schema)
-          keys_for_type = resolvers_for_type.each_with_object({}) do |resolver, memo|
-            memo[resolver.key.to_definition] ||= Set.new
-            memo[resolver.key.to_definition].merge(resolver.key.locations)
-          end
-
-          keys_for_type.each do |key, locations|
-            locations.each do |location|
-              params = { key: key, location: location }
-
-              unless has_directive?(type, KeyDirective.graphql_name, params)
-                type.directive(KeyDirective, **params)
-              end
-            end
-          end
-
-          # Apply resolver directives for each unique query resolver
-          resolvers_for_type.each do |resolver|
-            params = {
-              location: resolver.location,
-              field: resolver.field,
-              list: resolver.list? || nil,
-              key: resolver.key.to_definition,
-              arguments: resolver.arguments.map(&:to_definition).join(", "),
-              argument_types: resolver.arguments.map(&:to_type_definition).join(", "),
-              type_name: (resolver.type_name if resolver.type_name != type_name),
-            }
-
-            unless has_directive?(type, ResolverDirective.graphql_name, params)
-              type.directive(ResolverDirective, **params.tap(&:compact!))
-            end
-          end
-        end
-
-        next unless type.kind.fields?
-
-        type.fields.each do |field_name, field|
-          locations_for_field = @locations_by_type_and_field.dig(type_name, field_name)
-          next if locations_for_field.nil?
-
-          # Apply source directives to annotate the possible locations of each field
-          locations_for_field.each do |location|
-            params = { location: location }
-
-            unless has_directive?(field, SourceDirective.graphql_name, params)
-              field.directive(SourceDirective, **params)
-            end
-          end
-        end
-      end
-
-      @schema.to_definition
-    end
-
-    private
-
-    def has_directive?(element, directive_name, params)
-      existing = element.directives.find do |d|
-        kwargs = d.arguments.keyword_arguments
-        d.graphql_name == directive_name && params.all? { |k, v| kwargs[k] == v }
-      end
-
-      !existing.nil?
-    end
-  end
-end