document disabling subgraph validations. (#184)

Author: gmac

README.md

@@ -21,7 +21,7 @@ This Ruby implementation is designed as a generic library to join basic spec-com
 
 ## Documentation
 
-1. [Introduction](./docs/introduction.md)
+1. [Introduction](./docs/README.md)
 1. [Composing a supergraph](./docs/composing_a_supergraph.md)
 1. [Merged types](./docs/merged_types.md)
 1. [Executables & file uploads](./docs/executables.md)

docs/introduction.md renamed to docs/README.md

@@ -57,6 +57,34 @@ query($id: ID!) {
 # variables: { "id" => "1" }
 ```
 
+### Subgraph validations
+
+Requests are validated by the supergraph, and should always divide into valid subgraph documents. Therefore, you can skip redundant subgraph validations for requests sent by the supergraph, ex:
+
+```ruby
+exe = GraphQL::Stitching::HttpExecutable.new(
+  url: "http://localhost:3001",
+  headers: { 
+    "Authorization" => "...",
+    "X-Supergraph-Secret" => "<shared-secret>",
+  },
+)
+```
+
+A shared secret allows a subgraph location to trust the supergraph origin, at which time it can disable validations:
+
+```ruby
+def query
+  sg_header = request.headers["X-Supergraph-Secret"]
+  MySchema.execute(
+    query: params[:query],
+    variables: params[:variables],
+    operation_name: params[:operationName],
+    validate: sg_header.nil? || sg_header != Rails.env.credentials.supergraph,
+  )
+end
+```
+
 ### Digests
 
 All computed digests use SHA2 hashing by default. You can swap in [a faster algorithm](https://github.com/Shopify/blake3-rb) and/or add base state by reconfiguring `Stitching.digest`: