graphql-stitching 1.7.0 → 1.7.2

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.

data/docs/mechanics.md

@@ -1,306 +0,0 @@
-## Schema Stitching, mechanics
-
-### Deploying a stitched schema
-
-Among the simplest and most effective ways to manage a stitched schema is to compose it locally, write the composed SDL as a `.graphql` file in your repo, and then load the composed schema into a stitching client at runtime. For example, setup a `rake` task that loads/fetches subgraph schemas, composes them, and then writes the composed schema definition as a file committed to the repo:
-
-```ruby
-task :compose_graphql do
-  schema1_sdl = ... # load schema 1
-  schema2_sdl = ... # load schema 2
-
-  supergraph = GraphQL::Stitching::Composer.new.perform({
-    schema1: {
-      schema: GraphQL::Schema.from_definition(schema1_sdl)
-    },
-    schema2: {
-      schema: GraphQL::Schema.from_definition(schema2_sdl)
-    }
-  })
-
-  File.write("schema/supergraph.graphql", supergraph.to_definition)
-  puts "Schema composition was successful."
-end
-
-# bundle exec rake compose-graphql
-```
-
-Then at runtime, load the composed schema into a stitching client:
-
-```ruby
-class GraphQlController
-  class < self
-    def client
-      @client ||= begin
-        supergraph_sdl = File.read("schema/supergraph.graphql")
-        supergraph = GraphQL::Stitching::Supergraph.from_definition(supergraph_sdl, executables: {
-          schema1: GraphQL::Stitching::HttpExecutable.new("http://localhost:3001/graphql"),
-          schema2: GraphQL::Stitching::HttpExecutable.new("http://localhost:3002/graphql"),
-        })
-        GraphQL::Stitching::Client.new(supergraph: supergraph)
-      end
-    end
-  end
-
-  def exec
-    self.class.client.execute(
-      params[:query],
-      variables: params[:variables],
-      operation_name: params[:operation_name]
-    )
-  end
-end
-```
-
-This process assures that composition always happens before deployment where failures can be detected. Use CI to verify that the repo's supergraph output is always up to date. Hot reloading of the supergraph can also be accommodated by uploading the composed schema to a sync location (cloud storage, etc) that is polled by the application runtime. When the schema changes, load it into a new stitching client and swap that into the application.
-
-### Field selection routing
-
-Fields of a merged type may exist in multiple locations. For example, the `title` field below is provided by both locations:
-
-```graphql
-# -- Location A
-
-type Movie {
-  id: String!
-  title: String! # shared
-  rating: Int!
-}
-
-type Query {
-  movieA(id: ID!): Movie @stitch(key: "id")
-}
-
-# -- Location B
-
-type Movie {
-  id: String!
-  title: String! # shared
-  reviews: [String!]!
-}
-
-type Query {
-  movieB(id: ID!): Movie @stitch(key: "id")
-}
-```
-
-When planning a request, field selections always attempt to use the current routing location that originates from the selection root, for example:
-
-```graphql
-query GetTitleFromA {
-  movieA(id: "23") { # <- enter via Location A
-    title            # <- source from Location A
-  }
-}
-
-query GetTitleFromB {
-  movieB(id: "23") { # <- enter via Location B
-    title            # <- source from Location B
-  }
-}
-```
-
-Field selections that are NOT available in the current routing location delegate to new locations as follows:
-
-1. Fields with only one location automatically use that location.
-2. Fields with multiple locations attempt to use a location added during step-1.
-3. Any remaining fields pick a location based on their highest availability among locations.
-
-### Root selection routing
-
-Root fields should route to the primary locations of their provided types. This assures that the most common data for a type can be resolved via root access and thus avoid unnecessary stitching. Root fields can select their primary locations using the `root_field_location_selector` option in [composer configuration](./composer.md#configuring-composition):
-
-```ruby
-supergraph = GraphQL::Stitching::Composer.new(
-  root_field_location_selector: ->(locations) { locations.find { _1 == "a" } || locations.last },
-).perform({ ... })
-```
-
-It's okay if root field names are repeated across locations. The primary location will be used when routing root selections:
-
-```graphql
-# -- Location A
-
-type Movie {
-  id: String!
-  rating: Int!
-}
-
-type Query {
-  movie(id: ID!): Movie @stitch(key: "id") # shared, primary
-}
-
-# -- Location B
-
-type Movie {
-  id: String!
-  reviews: [String!]!
-}
-
-type Query {
-  movie(id: ID!): Movie @stitch(key: "id") # shared
-}
-
-# -- Request
-
-query {
-  movie(id: "23") { id } # routes to Location A
-}
-```
-
-Note that primary location routing _only_ applies to selections in the root scope. If the `Query` type appears again lower in the graph, then its fields are resolved as normal object fields outside of root context, for example:
-
-```graphql
-schema {
-  query: Query # << root query, uses primary locations
-}
-
-type Query {
-  subquery: Query # << subquery, acts as a normal object type
-}
-```
-
-Also note that stitching queries (denoted by the `@stitch` directive) are completely separate from field routing concerns. A `@stitch` directive establishes a contract for resolving a given type in a given location. This contract is always used to collect stitching data, regardless of how request routing selected the location for use.
-
-### Stitched errors
-
-Any [spec GraphQL errors](https://spec.graphql.org/June2018/#sec-Errors) returned by a stitching query will flow through the request. Stitching has two strategies for passing errors through to the final result:
-
-1. **Direct passthrough**, where subgraph errors are returned directly 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 stitched request. This strategy is used when merging stitching queries into the composed result.
-
-In either strategy, it's important that subgraphs provide properly pathed errors (GraphQL Ruby [can do this automatically](https://graphql-ruby.org/errors/overview.html)). For example:
-
-```json
-{
-  "data": { "shop": { "product": null } },
-  "errors": [{
-    "message": "Record not found.",
-    "path": ["shop", "product"]
-  }]
-}
-```
-
-When resolving [stitching list queries](../README.md#list-queries), it's important to only error out specific array positions rather than the entire array result, for example:
-
-```ruby
-def products
-  [
-    { id: "1" },
-    GraphQL::ExecutionError.new("Not found"),
-    { id: "3" },
-  ]
-end
-```
-
-Stitching expects list queries to pad their missing elements with null, and to report corresponding errors pathed down to list position:
-
-```json
-{
-  "data": {
-    "products": [{ "id": "1" }, null, { "id": "3" }]
-  },
-  "errors": [{
-    "message": "Record not found.",
-    "path": ["products", 1]
-  }]
-}
-```
-
-### Null results
-
-It's okay for a stitching query to return `null` for a merged type as long as all unique fields of the type allow null. For example, the following merge works:
-
-```graphql
-# -- Request
-
-query {
-  movieA(id: "23") {
-    id
-    title
-    rating
-  }
-}
-
-# -- Location A
-
-type Movie {
-  id: String!
-  title: String!
-}
-
-type Query {
-  movieA(id: ID!): Movie @stitch(key: "id")
-      # (id: "23") -> { id: "23", title: "Jurassic Park" }
-}
-
-# -- Location B
-
-type Movie {
-  id: String!
-  rating: Int
-}
-
-type Query {
-  movieB(id: ID!): Movie @stitch(key: "id")
-      # (id: "23") -> null
-}
-```
-
-And produces this result:
-
-```json
-{
-  "data": {
-    "id": "23",
-    "title": "Jurassic Park",
-    "rating": null
-  }
-}
-```
-
-Location B is allowed to return `null` here because its one unique field, `rating`, is nullable (the `id` field can be provided by Location A). If `rating` were non-null, then null bubbling would invalidate the response data.
-
-### Outbound-only merged types
-
-Merged types do not always require a resolver query. For example:
-
-```graphql
-# -- Location A
-
-type Widget {
-  id: ID!
-  name: String
-  price: Float
-}
-
-type Query {
-  widgetA(id: ID!): Widget @stitch(key: "id")
-}
-
-# -- Location B
-
-type Widget {
-  id: ID!
-  size: Float
-}
-
-type Query {
-  widgetB(id: ID!): Widget @stitch(key: "id")
-}
-
-# -- Location C
-
-type Widget {
-  id: ID!
-  name: String
-  size: Float
-}
-
-type Query {
-  featuredWidget: Widget
-}
-```
-
-In this graph, `Widget` is a merged type without a resolver query in location C. This works because all of its fields are resolvable in other locations; that means location C can provide outbound representations of this type without ever needing to resolve inbound requests for it. Outbound types do still require a shared key field (such as `id` above) that allow them to join with data in other resolver locations (such as `price` above). Support for this pattern is limited to single-field keys, [composite keys](../README.md#composite-type-keys) require a resolver definition.

data/docs/request.md

@@ -1,34 +0,0 @@
-## GraphQL::Stitching::Request
-
-A `Request` contains a parsed GraphQL document and variables, and handles the logistics of extracting the appropriate operation, variable definitions, and fragments. A `Request` should be built once per server request and passed through to other stitching components that utilize request information.
-
-```ruby
-source = "query FetchMovie($id: ID!) { movie(id:$id) { id genre } }"
-request = GraphQL::Stitching::Request.new(
-  supergraph,
-  source,
-  variables: { "id" => "1" },
-  operation_name: "FetchMovie",
-  context: { ... },
-)
-```
-
-A `Request` provides the following information:
-
-- `req.variables`: a hash of user-submitted variables.
-- `req.string`: the original GraphQL source string, or printed document.
-- `req.digest`: a digest of the request string, hashed by the `Stitching.digest` implementation.
-- `req.normalized_string`: printed document string with consistent whitespace.
-- `req.normalized_digest`: a digest of the normalized string, hashed by the `Stitching.digest` 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.
-
-### Request lifecycle
-
-A request manages the flow of stitching behaviors. These are sequenced by the `Client`
-component, or you may invoke them manually:
-
-1. `request.validate`: runs static validations on the request using the combined schema.
-2. `request.plan`: builds a plan for the request. May act as a setter for plans pulled from cache.
-3. `request.execute`: executes the request, and returns the resulting data.

data/docs/supergraph.md

@@ -1,31 +0,0 @@
-## GraphQL::Stitching::Supergraph
-
-A `Supergraph` is the singuar representation of a stitched graph. `Supergraph` is composed from many locations, and provides a combined GraphQL schema and delegation maps used to route incoming requests.
-
-### Export and caching
-
-A Supergraph is designed to be composed, cached, and restored. Calling `to_definition` will return an SDL (Schema Definition Language) print of the combined graph schema with delegation mapping directives. This pre-composed schema can be persisted in any raw format that suits your stack:
-
-```ruby
-supergraph_sdl = supergraph.to_definition
-
-# write the composed schema as a file into your repo...
-File.write("supergraph/schema.graphql", supergraph_sdl)
-
-# or, stash this composed schema in a cache...
-$cache.set("cached_supergraph_sdl", supergraph_sdl)
-```
-
-To restore a Supergraph, call `from_definition` providing the cached SDL string and a hash of executables keyed by their location names:
-
-```ruby
-supergraph_sdl = File.read("supergraph/schema.graphql")
-
-supergraph = GraphQL::Stitching::Supergraph.from_definition(
-  supergraph_sdl,
-  executables: {
-    my_remote: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3000"),
-    my_local: MyLocalSchema,
-  }
-)
-```

data/docs/type_resolver.md

@@ -1,101 +0,0 @@
-## GraphQL::Stitching::TypeResolver
-
-A `TypeResolver` contains all information about a root query used by stitching to fetch location-specific variants of a merged type. Specifically, resolvers manage parsed keys and argument structures.
-
-### Arguments
-
-Type resolvers configure arguments through a template string of [GraphQL argument literal syntax](https://spec.graphql.org/October2021/#sec-Language.Arguments). This allows sending multiple arguments that intermix stitching keys with complex object shapes and other static values.
-
-#### Key insertions
-
-Key values fetched from previous locations may be inserted into arguments. Key insertions are prefixed by `$` and specify a dot-notation path to any selections made by the resolver `key`, or `__typename`.
-
-```graphql
-type Query {
-  entity(id: ID!, type: String!): [Entity]!
-    @stitch(key: "owner { id }", arguments: "id: $.owner.id, type: $.__typename")
-}
-```
-
-Key insertions are _not_ quoted to differentiate them from other literal values.
-
-#### Lists
-
-List arguments may specify input just like non-list arguments, and [GraphQL list input coercion](https://spec.graphql.org/October2021/#sec-List.Input-Coercion) will assume the shape represents a list item:
-
-```graphql
-type Query {
-  product(ids: [ID!]!, source: DataSource!): [Product]!
-    @stitch(key: "id", arguments: "ids: $.id, source: CACHE")
-}
-```
-
-List resolvers (that return list types) may _only_ insert keys into repeatable list arguments, while non-list arguments may only contain static values. Nested list inputs are neither common nor practical, so are not supported.
-
-#### Built-in scalars
-
-Built-in scalars are written as normal literal values. For convenience, string literals may be enclosed in single quotes rather than escaped double-quotes:
-
-```graphql
-type Query {
-  product(id: ID!, source: String!): Product
-    @stitch(key: "id", arguments: "id: $.id, source: 'cache'")
-
-  variant(id: ID!, limit: Int!): Variant
-    @stitch(key: "id", arguments: "id: $.id, limit: 100")
-}
-```
-
-All scalar usage must be legal to the resolver field's arguments schema.
-
-#### Enums
-
-Enum literals may be provided anywhere in the input structure. They are _not_ quoted:
-
-```graphql
-enum DataSource {
-  CACHE
-}
-type Query {
-  product(id: ID!, source: DataSource!): [Product]!
-    @stitch(key: "id", arguments: "id: $.id, source: CACHE")
-}
-```
-
-All enum usage must be legal to the resolver field's arguments schema.
-
-#### Input Objects
-
-Input objects may be provided anywhere in the input, even as nested structures. The stitching resolver will build the specified object shape:
-
-```graphql
-input ComplexKey {
-  id: ID
-  nested: ComplexKey
-}
-type Query {
-  product(key: ComplexKey!): [Product]!
-    @stitch(key: "id", arguments: "key: { nested: { id: $.id } }")
-}
-```
-
-Input object shapes must conform to their respective schema definitions based on their placement within resolver arguments.
-
-#### Custom scalars
-
-Custom scalar keys allow any input shape to be submitted, from primitive scalars to complex object structures. These values will be sent and recieved as untyped JSON input:
-
-```graphql
-type Product {
-  id: ID!
-}
-union Entity = Product
-scalar Key
-
-type Query {
-  entities(representations: [Key!]!): [Entity]!
-    @stitch(key: "id", arguments: "representations: { id: $.id, __typename: $.__typename }")
-}
-```
-
-Custom scalar arguments have no structured schema definition to validate against. This makes them flexible but quite lax, for better or worse.