From aa17e9727ca7d1ade42c8c7009cda6de7b15dac4 Mon Sep 17 00:00:00 2001
From: Greg MacWilliam <gmacwill77@gmail.com>
Date: Thu, 5 Jun 2025 08:29:26 -0400
Subject: [PATCH] document disabling subgraph validations.

---
 README.md                           |  2 +-
 docs/{introduction.md => README.md} |  0
 docs/performance.md                 | 28 ++++++++++++++++++++++++++++
 3 files changed, 29 insertions(+), 1 deletion(-)
 rename docs/{introduction.md => README.md} (100%)

diff --git a/README.md b/README.md
index 7bc9dcbb..fc1d3711 100644
--- a/README.md
+++ b/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)
diff --git a/docs/introduction.md b/docs/README.md
similarity index 100%
rename from docs/introduction.md
rename to docs/README.md
diff --git a/docs/performance.md b/docs/performance.md
index f514e541..41f73b5a 100644
--- a/docs/performance.md
+++ b/docs/performance.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`: