fix(router): include persisted document hash in usage reports (#1377)

Co-authored-by: Mikhail Davydov <davydov@devlab.co>

Author: azproduction

.changeset/usage-report-persisted-document-hash.md

@@ -0,0 +1,11 @@
+---
+hive-router: patch
+---
+
+# Report `persistedDocumentHash` in usage reports
+
+Usage reports now include the resolved persisted document id, so Hive Console can match
+requests to app deployments and populate their "Last used" data. Previously the router
+resolved the document id but always omitted it from the usage report.
+
+Closes https://github.com/graphql-hive/router/issues/1343

bin/router/src/pipeline/mod.rs

@@ -509,6 +509,7 @@ pub async fn graphql_request_handler(
                 hive_usage_agent,
                 shared_response.error_count(),
                 Some(usage_reporting::request_details_from_ntex_request(req)),
+                prepared_operation.resolved_document_id.as_deref(),
             )
             .await;
         }

bin/router/src/pipeline/usage_reporting.rs

@@ -118,6 +118,7 @@ pub async fn collect_usage_report<'a>(
     hive_usage_agent: &UsageAgent,
     error_count: usize,
     request_details: Option<RequestDetails>,
+    persisted_document_hash: Option<&str>,
 ) {
     let timestamp = SystemTime::now()
         .duration_since(UNIX_EPOCH)
@@ -138,7 +139,7 @@ pub async fn collect_usage_report<'a>(
             OperationKind::Subscription => OperationType::Subscription,
         }),
         operation_name: operation_name.map(|s| s.to_owned()),
-        persisted_document_hash: None,
+        persisted_document_hash: persisted_document_hash.map(|hash| hash.to_owned()),
     };
 
     if let Err(err) = hive_usage_agent

bin/router/src/pipeline/websocket_server.rs

@@ -633,6 +633,9 @@ async fn handle_text_frame(
                           hive_usage_agent,
                           shared_response.error_count(),
                           Some(request_details),
+                          // The graphql-transport-ws Subscribe payload carries no document id
+                          // and this path never invokes the document id resolver.
+                          None,
                       )
                       .await;
                   }

e2e/src/telemetry/usage_reporting.rs

@@ -892,3 +892,93 @@ async fn usage_reporting_exclude_runs_before_at_least_once() {
     let total_ops = mock.total_operations_count().await;
     assert_eq!(total_ops, 2);
 }
+
+/// Test that an operation resolved from a persisted document reports the resolved
+/// document id as `persistedDocumentHash`, while a plain query reports none.
+/// https://github.com/graphql-hive/router/issues/1343
+#[ntex::test]
+async fn usage_reporting_includes_persisted_document_hash() {
+    let supergraph_path =
+        std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("supergraph.graphql");
+    let supergraph_path = supergraph_path.to_str().unwrap();
+
+    let mock = MockUsageEndpoint::start();
+    let usage_endpoint = &mock.address;
+
+    let doc_id = "app~1.0.0~sha256:usage123";
+    let manifest = tempfile::NamedTempFile::new().expect("failed to create manifest file");
+    std::fs::write(
+        manifest.path(),
+        sonic_rs::to_string(&sonic_rs::json!({ doc_id: "{ users { id } }" }))
+            .expect("failed to serialize manifest"),
+    )
+    .expect("failed to write manifest");
+
+    let subgraphs = TestSubgraphs::builder().build().start().await;
+
+    let router = TestRouter::builder()
+        .inline_config(format!(
+            r#"
+            supergraph:
+              source: file
+              path: {supergraph_path}
+
+            persisted_documents:
+              enabled: true
+              storage:
+                type: file
+                path: "{manifest_path}"
+
+            telemetry:
+              hive:
+                token: test-token
+                usage_reporting:
+                  enabled: true
+                  endpoint: {usage_endpoint}
+                  buffer_size: 1
+                  flush_interval: 100ms
+            "#,
+            manifest_path = manifest.path().display(),
+        ))
+        .with_subgraphs(&subgraphs)
+        .build()
+        .start()
+        .await;
+
+    // Resolved from the persisted document manifest.
+    let res = router
+        .send_post_request("/graphql", sonic_rs::json!({ "documentId": doc_id }), None)
+        .await;
+    assert!(res.status().is_success());
+
+    mock.wait_for_reports(1).await;
+    let reports = mock.reports().await;
+    let operations = reports[0]["operations"]
+        .as_array()
+        .expect("report should contain operations");
+    assert_eq!(operations.len(), 1);
+    assert_eq!(
+        operations[0]["persistedDocumentHash"].as_str(),
+        Some(doc_id),
+        "operation should carry the resolved persisted document id: {}",
+        reports[0]
+    );
+
+    // A plain query (allowed since require_id is off) must not carry a hash.
+    let res = router
+        .send_graphql_request("{ users { id } }", None, None)
+        .await;
+    assert!(res.status().is_success());
+
+    mock.wait_for_reports(2).await;
+    let reports = mock.reports().await;
+    let operations = reports[1]["operations"]
+        .as_array()
+        .expect("report should contain operations");
+    assert_eq!(operations.len(), 1);
+    assert!(
+        operations[0]["persistedDocumentHash"].is_null(),
+        "plain query must not report a persisted document hash: {}",
+        reports[1]
+    );
+}