Visibility controls (#173)

Author: gmac

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"),
   },
 })
 ```
@@ -477,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)

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.

lib/graphql/stitching.rb

@@ -32,8 +32,6 @@ def initialize(element)
     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,6 +47,26 @@ def digest(&block)
       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

lib/graphql/stitching/client.rb

@@ -13,16 +13,18 @@ class Client
       # 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