Persisted Documents

.changeset/negative_cache_single_flight.md

@@ -0,0 +1,10 @@
+---
+hive-console-sdk: minor
+hive-router: patch
+---
+
+# Negative Cache and Single-Flight
+
+Introduced single-flight resolution of documents in the SDK.
+
+Added a negative cache to store non 2XX requests for 5s (configurable, but in SDK it's disabled by default). It's meant to not keep repeating the same requests that eventually give errors or 404s.

.changeset/persisted_documents.md

@@ -0,0 +1,35 @@
+---
+hive-router-plan-executor: minor
+hive-router-config: minor
+hive-router: minor
+hive-router-internal: minor
+hive-console-sdk: minor
+---
+
+# Persisted Documents
+
+Introduces persisted documents support in Hive Router with configurable extraction and storage backends.
+
+Supports extracting persisted document IDs from:
+- `documentId` in request body (default)
+- `documentId` in URL query params (default)
+- Apollo-style `extensions.persistedQuery.sha256Hash` (default)
+- custom `json_path` (for example `doc_id` or `extensions.anything.id`)
+- custom `url_query_param` (for example `?doc_id=123`)
+- custom `url_path_param` (for example `/graphql/:id`)
+
+Order is configurable and evaluated top-to-bottom.
+
+Supports persisted document resolution from:
+- file manifests (Apollo and Relay KV styles)
+- Hive CDN (via `hive-console-sdk`)
+
+File storage includes watch mode by default (with 150ms debounce) to reload manifests after file changes.
+Hive storage validates document ID syntax before generating CDN paths to avoid silent invalid-path behavior.
+
+Adds persisted-documents metrics:
+
+- `hive.router.persisted_documents.extract.missing_id_total`
+- `hive.router.persisted_documents.storage.failures_total`
+
+These help track migration progress and resolution failures in production

.github/workflows/ci.yaml

@@ -188,6 +188,12 @@ jobs:
             binary: "hive_router_with_plugin"
             config: "bench/configs/plugins.config.yaml"
             compare_with_default: true
+          - name: "persisted-documents"
+            args: ""
+            package: "hive-router"
+            binary: "hive_router"
+            config: "bench/configs/persisted-documents.config.yaml"
+            compare_with_default: true
     name: benchmark / router / ${{ matrix.name }}
     runs-on: ubuntu-latest
     env:
@@ -220,7 +226,12 @@ jobs:
           ROUTER_CONFIG_FILE_PATH: ${{matrix.config}}
       - name: Run k6 benchmark for ${{ github.ref }}
         if: github.event_name == 'pull_request'
-        run: k6 run -e SUMMARY_PATH=./bench/results/pr bench/k6.js
+        run: |
+          if [ "${{ matrix.name }}" = "persisted-documents" ]; then
+            k6 run -e SUMMARY_PATH=./bench/results/pr -e BENCH_PERSISTED_MODE=true -e BENCH_DOCUMENT_ID=bench_test_query bench/k6.js
+          else
+            k6 run -e SUMMARY_PATH=./bench/results/pr bench/k6.js
+          fi
       - name: Checkout main branch in a separate directory
         if: github.event_name == 'pull_request'
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

Cargo.toml

@@ -87,6 +87,7 @@ strum = { version = "0.28.0", features = ["derive"] }
 mockito = "1.7.0"
 futures-util = "0.3.31"
 axum = "0.8.4"
+notify = "8.2.0"
 
 # Telemetry
 opentelemetry = "0.31.0"

bench/configs/persisted-documents.config.yaml

@@ -0,0 +1,15 @@
+# yaml-language-server: $schema=../../router-config.schema.json
+supergraph:
+  source: file
+  path: ../supergraph.graphql
+
+persisted_documents:
+  enabled: true
+  require_id: true
+  storage:
+    type: file
+    path: ../persisted-documents.json
+    watch: false
+
+log:
+  level: info

bench/k6.js

@@ -5,6 +5,8 @@ import { textSummary } from "https://jslib.k6.io/k6-summary/0.0.1/index.js";
 const endpoint = __ENV.ROUTER_ENDPOINT || "http://0.0.0.0:4000/graphql";
 const vus = __ENV.BENCH_VUS ? parseInt(__ENV.BENCH_VUS) : 50;
 const duration = __ENV.BENCH_OVER_TIME || "30s";
+const persistedMode = __ENV.BENCH_PERSISTED_MODE === "true";
+const documentId = __ENV.BENCH_DOCUMENT_ID || "bench_test_query";
 
 export const options = {
   vus,
@@ -42,9 +44,7 @@ function runOnce(identifier, cb) {
   return cb();
 }
 
-const graphqlRequest = {
-  payload: JSON.stringify({
-    query: `fragment User on User {
+const graphqlQuery = `fragment User on User {
       id
       username
       name
@@ -101,8 +101,12 @@ const graphqlRequest = {
           }
         }
       }
-    }`,
-  }),
+    }`;
+
+const graphqlRequest = {
+  payload: JSON.stringify(
+    persistedMode ? { documentId } : { query: graphqlQuery },
+  ),
   params: {
     headers: {
       "Content-Type": "application/json",

bench/persisted-documents.json

@@ -0,0 +1,3 @@
+{
+  "bench_test_query": "fragment User on User { id username name } fragment Review on Review { id body } fragment Product on Product { inStock name price shippingEstimate upc weight } query TestQuery { users { ...User reviews { ...Review product { ...Product reviews { ...Review author { ...User reviews { ...Review product { ...Product } } } } } } } topProducts { ...Product reviews { ...Review author { ...User reviews { ...Review product { ...Product } } } } } }"
+}

bin/router/Cargo.toml

@@ -58,6 +58,10 @@ ahash = { workspace = true }
 rustls = { workspace = true, features = ["aws-lc-rs"] }
 hyper-rustls = { workspace = true, features = ["aws-lc-rs"]}
 dashmap = { workspace = true }
+notify = { workspace = true }
+memchr = "2.8.0"
+percent-encoding = "2.3.2"
+matchit = "0.9.1"
 
 moka = { workspace = true }
 ulid = "1.2.1"
@@ -85,5 +89,5 @@ criterion = { workspace = true }
 insta = { workspace = true }
 
 [[bench]]
-name = "router_benches"
+name = "persisted_documents_matcher_benches"
 harness = false