graphql-stitching 1.7.0 → 1.7.1

data/docs/composing_a_supergraph.md

@@ -0,0 +1,215 @@
+## Composing a Supergraph
+
+A stitching client is constructed with many subgraph schemas, and must first _compose_ them into one unified schema that can introspect and validate supergraph requests. Composition only happens once upon initialization.
+
+### Location settings
+
+When building a client, pass a `locations` hash with named definitions for each subgraph location:
+
+```ruby
+client = GraphQL::Stitching::Client.new(locations: {
+  products: {
+    schema: GraphQL::Schema.from_definition(File.read("schemas/products.graphql")),
+    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3001"),
+  },
+  users: {
+    schema: GraphQL::Schema.from_definition(File.read("schemas/users.graphql")),
+    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3002"),
+    stitch: [{ field_name: "users", key: "id" }],
+  },
+  my_local: {
+    schema: MyLocalSchema,
+  },
+})
+```
+
+Location settings have top-level keys that specify arbitrary location name keywords, 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's also used as the location's executable, see below).
+
+- **`executable:`**, provides an executable resource to be called when delegating a request to this location, see [documentation](./executables.md). Omitting the executable option will use the location's provided `schema` as the executable resource.
+
+- **`stitch:`**, an array of static configs used to dynamically apply [`@stitch` directives](./merged_types.md#merged-type-resolver-queries) to root fields while composing. Each config may specify `field_name`, `key`, `arguments`, and `type_name`.
+
+### Composer options
+
+When building a client, you may pass `composer_options` to tune how it builds a supergraph. All settings are optional:
+
+```ruby
+client = GraphQL::Stitching::Client.new(
+  composer_options: {
+    query_name: "Query",
+    mutation_name: "Mutation",
+    subscription_name: "Subscription",
+    visibility_profiles: nil, # ["public", "private", ...]
+    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_entrypoints: {},
+  },
+  locations: {
+    # ...
+  }
+)
+```
+
+- **`query_name:`**, 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:`**, 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:`**, 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.
+
+- **`visibility_profiles:`**, an array of [visibility profiles](./visibility.md) that the supergraph responds to.
+
+- **`description_merger:`**, a [value merger function](#value-merger-functions) for merging element description strings from across locations.
+
+- **`deprecation_merger:`**, a [value merger function](#value-merger-functions) for merging element deprecation strings from across locations.
+
+- **`default_value_merger:`**, a [value merger function](#value-merger-functions) for merging argument default values from across locations.
+
+- **`directive_kwarg_merger:`**, a [value merger function](#value-merger-functions) for merging directive keyword arguments from across locations.
+
+- **`root_entrypoints:`**, a hash of root field names mapped to their entrypoint locations, see [overlapping root fields](#overlapping-root-fields) below.
+
+#### 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
+join_values_merger = ->(values_by_location, info) { values_by_location.values.compact.join("\n") }
+
+client = GraphQL::Stitching::Client.new(
+  composer_options: {
+    description_merger: join_values_merger,
+    deprecation_merger: join_values_merger,
+    default_value_merger: join_values_merger,
+    directive_kwarg_merger: join_values_merger,
+  },
+)
+```
+
+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 = {
+  "users" => "A fabulous data type.",
+  "products" => "An excellent data type.",
+}
+
+info = {
+  type_name: "Product",
+  # field_name: ...,
+  # argument_name: ...,
+  # directive_name: ...,
+}
+```
+
+### Cached supergraphs
+
+Composition is a nuanced process with a high potential for validation failures. While performing composition at runtime is fine in development mode, it becomes an unnecessary risk in production. It's much safer to compose your supergraph in development mode, cache the composition, and then rehydrate the supergraph from cache in production.
+
+First, compose your supergraph in development mode and write it to file:
+
+```ruby
+client = GraphQL::Stitching::Client.new(locations: {
+  products: {
+    schema: GraphQL::Schema.from_definition(File.read("schemas/products.graphql")),
+    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3001"),
+  },
+  users: {
+    schema: GraphQL::Schema.from_definition(File.read("schemas/users.graphql")),
+    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3002"),
+  },
+  my_local: {
+    schema: MyLocalSchema,
+  },
+})
+
+File.write("schemas/supergraph.graphql", client.supergraph.to_definition)
+```
+
+Then in production, rehydrate the client using the cached supergraph and its production-appropriate executables:
+
+```ruby
+client = GraphQL::Stitching::Client.from_definition(
+  File.read("schemas/supergraph.graphql"),
+  executables: {
+    products: GraphQL::Stitching::HttpExecutable.new(url: "https://products.myapp.com/graphql"),
+    users: GraphQL::Stitching::HttpExecutable.new(url: "http://users.myapp.com/graphql"),
+    my_local: MyLocalSchema,
+  }
+)
+```
+
+### Overlapping root fields
+
+Some subgraph schemas may have overlapping root fields, such as the `product` field below. You may specify a `root_entrypoints` composer option to map overlapping root fields to a preferred location:
+
+```ruby
+infos_schema = %|
+  type Product {
+    id: ID!
+    title: String!
+  }
+  type Query {
+    product(id: ID!): Product @stitch(key: "id")
+  }
+|
+
+prices_schema = %|
+  type Product {
+    id: ID!
+    price: Float!
+  }
+  type Query {
+    product(id: ID!): Product @stitch(key: "id")
+  }
+|
+
+client = GraphQL::Stitching::Client.new(
+  composer_options: {
+    root_entrypoints: {
+      "Query.product" => "infos",
+    }
+  },
+  locations: {
+    infos: {
+      schema: GraphQL::Schema.from_definition(infos_schema),
+      executable: #... ,
+    },
+    prices: {
+      schema: GraphQL::Schema.from_definition(prices_schema),
+      executable: #... ,
+    },
+  }
+)
+```
+
+In the above, selecting the root `product` field will route to the "infos" schema by default. You should bias root fields to their most general-purpose location. This option _only_ applies to root fields where the query planner has no starting location bias (learn more about [query planning](./query_planning.md)). Note that [type resolver queries](./merged_types.md#type-resolver-queries) are unaffected by entrypoint bias; a type resolver will always be accessed directly for a location when needed.
+
+### Schema merge patterns
+
+The strategy used to merge subgraph schemas into the combined supergraph 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](./merged_types.md).
+  - 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:
+  - `@visibility` directives intersect their profiles, see [documentation](./visibility.md).
+  - `@stitch` directives (both definitions and assignments) are omitted.

data/docs/error_handling.md

@@ -0,0 +1,69 @@
+## Error handling
+
+Failed stitching requests can be tricky to debug because it's not always obvious where the actual error occured. Error handling helps surface issues and make them easier to locate.
+
+### Supergraph errors
+
+When exceptions happen while executing requests within the stitching layer, they will be rescued by the stitching client and trigger an `on_error` hook. You should add your stack's error reporting here and return a formatted error message to appear in [GraphQL errors](https://spec.graphql.org/June2018/#sec-Errors) for the request.
+
+```ruby
+client = GraphQL::Stitching::Client.new(locations: { ... })
+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
+
+# Result:
+# { "errors" => [{ "message" => "Whoops, please contact support abount request '12345'" }] }
+```
+
+### Subgraph errors
+
+When subgraph resources produce errors, it's very important that each error provides a proper `path` indicating the field associated with the error. Most major GraphQL implementations, including GraphQL Ruby, [do this automatically](https://graphql-ruby.org/errors/overview.html):
+
+```json
+{
+  "data": { "shop": { "product": null } },
+  "errors": [{
+    "message": "Record not found.",
+    "path": ["shop", "product"]
+  }]
+}
+```
+
+Be careful when resolving lists, particularly for merged type resolvers. Lists should only error out specific array positions rather than the entire array result whenever possible, for example:
+
+```ruby
+def products
+  [
+    { id: "1" },
+    GraphQL::ExecutionError.new("Not found"),
+    { id: "3" },
+  ]
+end
+```
+
+These cases should report corresponding errors pathed down to the list index without affecting other successful results in the list:
+
+```json
+{
+  "data": {
+    "products": [{ "id": "1" }, null, { "id": "3" }]
+  },
+  "errors": [{
+    "message": "Record not found.",
+    "path": ["products", 1]
+  }]
+}
+```
+
+### Merging subgraph errors
+
+All [spec GraphQL errors](https://spec.graphql.org/June2018/#sec-Errors) returned from subgraph queries will flow through the stitched request and into the final result. Formatting these errors follows one of two strategies:
+
+1. **Direct passthrough**, where subgraph errors are returned directly in the merged response without modification. This strategy is used for errors without a `path` (ie: "base" errors), and errors pathed to root fields.
+
+2. **Mapped passthrough**, where the `path` attribute of a subgraph error is remapped to an insertion point in the supergraph request. This strategy is used when a merged type resolver returns an error for an object in a lower-level position of the supergraph document.

data/docs/executables.md

@@ -0,0 +1,112 @@
+## 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:
+
+```ruby
+class MyExecutable
+  def call(request, source, variables)
+    # process a GraphQL request...
+    return {
+      "data" => { ... },
+      "errors" => [ ... ],
+    }
+  end
+end
+```
+
+A supergraph is composed with executable resources provided for each location. Any location that omits the `executable` option will use the provided `schema` as its default executable:
+
+```ruby
+client = GraphQL::Stitching::Client.new(locations: {
+  first: {
+    schema: FirstSchema,
+    # executable:^^^^^^ delegates to FirstSchema,
+  },
+  second: {
+    schema: SecondSchema,
+    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3001", headers: { ... }),
+  },
+  third: {
+    schema: ThirdSchema,
+    executable: MyExecutable.new,
+  },
+  fourth: {
+    schema: FourthSchema,
+    executable: ->(req, query, vars) { ... },
+  },
+})
+```
+
+## HttpExecutable
+
+The `GraphQL::Stitching` library provides one default executable: `HttpExecutable`. This is an out-of-the-box convenience for sending HTTP post requests to a remote location, or a base class for your own implementation with [file uploads](#file-uploads).
+
+```ruby
+executable = GraphQL::Stitching::HttpExecutable.new(
+  url: "http://localhost:3001",
+  headers: { "Authorization" => "..." },
+  upload_types: #...
+)
+```
+
+- **`url:`**, the URL of an endpoint to post GraphQL requests to.
+- **`headers:`**, a hash of headers to encode into post requests.
+- **`upload_types:`**, an array of scalar names to process as [file uploads](#file-uploads), see below.
+
+Extend this class to reimplement HTTP transmit behaviors using your own libraries. Specifically, override the following methods:
+
+- **`send(request, document, variables)`**, transmits a basic HTTP request.
+- **`send_multipart_form(request, form_data)`**, transmits multipart form data.
+
+### The `Stitching::Request` object
+
+HttpExecutable methods recieve the supergraph's `request` object, which contains all information about the supergraph request being processed. This includes useful caching information:
+
+- `req.variables`: a hash of user-submitted variables.
+- `req.original_document`: the original validated request document, before skip/include.
+- `req.string`: the prepared GraphQL source string being executed, after skip/include.
+- `req.digest`: digest of the prepared string, hashed by the [`Stitching.digest`](./performance.md#digests) implementation.
+- `req.normalized_string`: printed source string with consistent whitespace.
+- `req.normalized_digest`: a digest of the normalized string, hashed by the [`Stitching.digest`](./performance.md#digests) implementation.
+- `req.operation`: the operation definition selected for the request.
+- `req.variable_definitions`: a mapping of variable names to their type definitions.
+- `req.fragment_definitions`: a mapping of fragment names to their fragment definitions.
+
+## 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. These can proxy through a supergraph with the following steps:
+
+### 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 supergraph as standard GraphQL variables with `Tempfile` values cast as a dedicated upload scalar type. The simplest way to recieve this input is to install [apollo_upload_server](https://github.com/jetruby/apollo_upload_server-ruby) into your app's middleware so that multipart form submissions automatically unpack into tempfile 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:3001",
+      upload_types: ["Upload"], # << extract `Upload` scalars into multipart forms
+    ),
+  },
+  bravo: {
+    schema: GraphQL::Schema.from_definition(...),
+    executable: GraphQL::Stitching::HttpExecutable.new(
+      url: "http://localhost:3002",
+    ),
+  },
+})
+```
+
+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 what scalar names require form extraction. Enabling `upload_types` adds 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 the supergraph that can again be unpacked using [apollo_upload_server](https://github.com/jetruby/apollo_upload_server-ruby) or similar.

data/docs/introduction.md

@@ -0,0 +1,17 @@
+## What is Stitching?
+
+You've probably done this: fetch some objects from an endpoint; then map those into a collection of keys that gets sent to another endpoint for more data; then hook all the results together in your client. This is stitching. GraphQL stitching simply automates this process so that one large _supergraph_ schema can transparently query from many _subgraph_ locations.
+
+## Stitching vs. Federation
+
+Stitching encompasses the raw mechanics of combining GraphQL schemas with cross-referenced objects, and is the underpinning mechanics for major federation frameworks such as [Apollo Federation](https://www.apollographql.com/federation) and [Wundergraph](https://wundergraph.com/). Stitching is generic library behavior that plugs into your server, while federation ecosystems _give you_ a server, a schema deployment pipeline, a control plane, and opinionated management workflows.
+
+If you're scaling a large distributed architecture with heavy throughput demands, then you'll probably benefit from growing atop a major federation framework. However, if you just have an existing Ruby app and want to hook a few external schemas into its GraphQL API, then incorporating an entire federation framework is probably overkill. Stitching offers good middleground.
+
+## The `GraphQL::Stitching` library
+
+This library contains the component parts for assembling a stitched schema, and rolls the entire workflow up into a `GraphQL::Stitching::Client` class.
+
+![Library flow](./images/library.png)
+
+For the most part, this entire library can be driven using just a `Client`. First [compose a supergraph](./composing_a_supergraph.md) with [executables](./executables.md) for each location, configure its [merged types](./merged_types.md), and then [serve the client](./serving_a_supergraph.md) in your app's GraphQL controller.