graphql-stitching 1.7.0 → 1.7.1

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.