drop with schema

Author: enisdenjo

.changeset/drop_with_schema_from_on_graphql_validation_plugin_hook.md

@@ -0,0 +1,24 @@
+---
+hive-router-plan-executor: major
+hive-router: patch
+---
+
+# Drop `with_schema` from the `on_graphql_validation` plugin hook
+
+Remove `OnGraphQLValidationStartHookPayload::with_schema`. Method was broken by design, it replaced the schema only for validation while parsing, introspection, normalization, planning, and execution continued using the request's original schema state. This could make a field disappear during validation while remaining visible through introspection, and it could leave schema-derived caches and planning state inconsistent with the schema used to validate the operation.
+
+Plugins that need a request-specific schema should now build and retain a stable `Arc<Document>` for each schema variant and select it in `on_http_request`:
+
+```rust
+fn on_http_request<'req>(
+    &'req self,
+    payload: OnHttpRequestHookPayload<'req>,
+) -> OnHttpRequestHookResult<'req> {
+    payload.set_schema_document(self.document_for_request(&payload).clone());
+    payload.proceed()
+}
+```
+
+The router resolves the selected supergraph document into an internally owned `SchemaState` and reuses it for later requests that provide the same `Arc<Document>`. The selected schema then applies consistently to the entire request pipeline, including validation, introspection, normalization, planning, and execution.
+
+Documents should be created when the plugin initializes or when the supergraph reloads, not per request. Creating a new `Arc<Document>` for every request defeats the router's schema-state cache and forces the schema state and query planner to be rebuilt.

lib/executor/src/plugins/hooks/on_graphql_validation.rs

@@ -1,7 +1,7 @@
 use std::sync::Arc;
 
 use graphql_tools::{
-    static_graphql::{query::Document as QueryDocument, schema::Document as SchemaDocument},
+    static_graphql::query::Document as QueryDocument,
     validation::{rules::ValidationRule, utils::ValidationError, validate::ValidationPlan},
 };
 use hive_router_query_planner::consumer_schema::ConsumerSchema;
@@ -32,12 +32,8 @@ pub struct OnGraphQLValidationStartHookPayload<'exec> {
     /// [Learn more about the context data sharing in the docs](https://the-guild.dev/graphql/hive/docs/router/extensibility/plugin_system#context-data-sharing)
     pub context: &'exec PluginContext,
     pub request_context: RequestContextApi,
-    /// The GraphQL Schema that the document will be validated against.
-    /// This is not the same with the supergraph. This is the public schema exposed by the router to the clients, which is generated from the supergraph and can be modified by the plugins.
-    /// The plugins can replace the input schema to be used for validation
-    /// and the new schema will be used in the validation process instead of the original one.
-    ///
-    /// [See an example to see when to override the schema](https://github.com/graphql-hive/router/blob/main/plugin_examples/feature_flags/src/plugin.rs)
+    /// The GraphQL schema that the document will be validated against.
+    /// This is the public schema exposed by the router, not the supergraph.
     pub schema: Arc<ConsumerSchema>,
     /// Parsed GraphQL document from the query string in the GraphQL parameters.
     /// It contains the Abstract Syntax Tree (AST) representation of the GraphQL query, mutation, or subscription
@@ -70,14 +66,6 @@ impl OnGraphQLValidationStartHookPayload<'_> {
         self.validation_plan = Arc::new(validation_plan.into());
         self
     }
-    /// Override the GraphQL Schema that the document will be validated against.
-    /// [See an example to see when to override the schema](https://github.com/graphql-hive/router/blob/main/plugin_examples/feature_flags/src/plugin.rs)
-    pub fn with_schema<TSchema: Into<Arc<SchemaDocument>>>(mut self, schema: TSchema) -> Self {
-        let schema: Arc<SchemaDocument> = schema.into();
-        let new_consumer_schema = ConsumerSchema::from(schema);
-        self.schema = new_consumer_schema.into();
-        self
-    }
 }
 
 impl<'exec> StartHookPayload<OnGraphQLValidationEndHookPayload, Response>