feat(smith) Backport configurable response generation

When we built the Rust subgraph mock server, we started with
apollo-smith's response generation code as our foundation. Over time,
we've added more configuration flexibility and GraphQL spec-compliant
behavior to that code, diverging from this source. This change backports
those improvements and fixes and exposes configuration options that will
allow the subgraph mock to just take a dependency on this code rather
than remaining a fork of it.

Author: SharkBaitDLS

crates/apollo-smith/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "apollo-smith"
-version = "0.15.2" # When bumping, also update README.md
+version = "0.16.0" # When bumping, also update README.md
 edition = "2021"
 authors = ["Benjamin Coenen <benjamin.coenen@apollographql.com>"]
 license = "MIT OR Apache-2.0"
@@ -27,9 +27,9 @@ apollo-parser = { path = "../apollo-parser", version = "0.8.0" }
 arbitrary = { version = "1.4.0", features = ["derive"] }
 indexmap = "2.0.0"
 once_cell = "1.9.0"
+rand = "0.10.0"
 serde_json_bytes = "0.2.5"
 thiserror = "2.0.0"
 
 [dev-dependencies]
 expect-test = "1.4"
-rand = "0.10.0"

crates/apollo-smith/README.md

@@ -50,7 +50,7 @@ and add `apollo-smith` to your Cargo.toml:
 ## fuzz/Cargo.toml
 
 [dependencies]
-apollo-smith = "0.15.2"
+apollo-smith = "0.16.0"
 ```
 
 It can then be used in a `fuzz_target` along with the [`arbitrary`] crate,
@@ -120,20 +120,25 @@ If you have a GraphQL operation in the form of an `ExecutableDocument` and its
 accompanying `Schema`, you can generate a response matching the shape of the
 operation with `apollo_smith::ResponseBuilder`.
 
+`ResponseBuilder` is generic over its randomness source via the `RandomProvider`
+trait. This allows it to be used with `arbitrary::Unstructured` for fuzz testing,
+with `RandProvider` for standard random generation, or with any custom implementation.
+
+### Using `Unstructured` (for fuzz testing)
+
 ```rust
 use apollo_compiler::validation::Valid;
 use apollo_compiler::ExecutableDocument;
 use apollo_compiler::Schema;
-use apollo_smith::ResponseBuilder;
-use arbitrary::Result;
+use apollo_smith::{ResponseBuilder, ResponseError};
 use arbitrary::Unstructured;
 use rand::RngExt as _;
 use serde_json_bytes::Value;
 
 pub fn generate_valid_response(
     doc: &Valid<ExecutableDocument>,
     schema: &Valid<Schema>,
-) -> Result<Value> {
+) -> Result<Value, ResponseError> {
     let mut buf = [0u8; 2048];
     rand::rng().fill(&mut buf);
     let mut u = Unstructured::new(&buf);
@@ -142,6 +147,48 @@ pub fn generate_valid_response(
 }
 ```
 
+### Using `RandProvider`
+
+Use `RandProvider` to wrap any `rand::Rng`:
+
+```rust,ignore
+use apollo_smith::{RandProvider, ResponseBuilder};
+
+let mut rng = RandProvider(rand::rng());
+let response = ResponseBuilder::new(&mut rng, &doc, &schema)
+    .with_min_list_size(1)
+    .with_max_list_size(5)
+    .with_null_ratio(1, 4)
+    .build()?;
+```
+
+### Configuring scalar generation
+
+Use `with_scalar_config` to override how values are generated for specific scalar types:
+
+```rust,ignore
+use apollo_smith::{ResponseBuilder, ScalarConfig};
+use apollo_compiler::Name;
+
+let response = ResponseBuilder::new(&mut rng, &doc, &schema)
+    .with_scalar_config(
+        Name::new_unchecked("ID".into()),
+        ScalarConfig::String { min_len: 8, max_len: 8 },
+    )
+    .build()?;
+```
+
+### Federation support
+
+For Apollo Federation subgraphs, you can use `override_sdl` to provide correct `_service { sdl }`
+responses instead of including the full schema (and all the generated federation types) in the response:
+
+```rust,ignore
+let response = ResponseBuilder::new(&mut rng, &doc, &schema)
+    .override_sdl(&original_sdl_string)
+    .build()?;
+```
+
 ## Limitations
 
 - Recursive object type not yet supported (example : `myType { inner: myType }`)

crates/apollo-smith/examples/generate_response.rs

@@ -2,7 +2,7 @@ use apollo_compiler::validation::Valid;
 use apollo_compiler::ExecutableDocument;
 use apollo_compiler::Schema;
 use apollo_smith::ResponseBuilder;
-use arbitrary::Result;
+use apollo_smith::ResponseError;
 use arbitrary::Unstructured;
 use rand::RngExt as _;
 use serde_json_bytes::Value;
@@ -11,7 +11,7 @@ use std::fs;
 pub fn generate_valid_response(
     doc: &Valid<ExecutableDocument>,
     schema: &Valid<Schema>,
-) -> Result<Value> {
+) -> Result<Value, ResponseError> {
     let mut buf = [0u8; 2048];
     rand::rng().fill(&mut buf);
     let mut u = Unstructured::new(&buf);

crates/apollo-smith/src/lib.rs

@@ -13,6 +13,7 @@ pub(crate) mod interface;
 pub(crate) mod name;
 pub(crate) mod object;
 pub(crate) mod operation;
+pub mod random;
 pub(crate) mod response;
 pub(crate) mod scalar;
 pub(crate) mod schema;
@@ -51,7 +52,10 @@ pub use interface::InterfaceTypeDef;
 use name::Name;
 pub use object::ObjectTypeDef;
 pub use operation::OperationDef;
-pub use response::Generator;
+pub use random::RandProvider;
+pub use random::RandomProvider;
+pub use random::ResponseError;
+pub use random::ScalarConfig;
 pub use response::ResponseBuilder;
 pub use scalar::ScalarTypeDef;
 pub use schema::SchemaDef;

crates/apollo-smith/src/random.rs

@@ -0,0 +1,230 @@
+use apollo_compiler::Name;
+use arbitrary::Unstructured;
+use rand::RngExt;
+use serde_json_bytes::serde_json::Number;
+use serde_json_bytes::Value;
+use std::collections::HashMap;
+
+/// Error type for response generation.
+#[derive(Debug, thiserror::Error)]
+pub enum ResponseError {
+    /// The randomness source was exhausted or produced invalid data.
+    #[error("randomness source exhausted or produced invalid data")]
+    Exhausted,
+    /// The randomness source produced data that could not be converted to the expected format.
+    #[error("invalid format: {0}")]
+    InvalidFormat(String),
+}
+
+/// Abstraction over a source of randomness for response generation.
+///
+/// Implementations are provided for [`Unstructured`] (for fuzz testing) and
+/// for any type implementing [`rand::Rng`] via the [`RandProvider`] newtype.
+pub trait RandomProvider {
+    /// Generate a random boolean.
+    fn gen_bool(&mut self) -> Result<bool, ResponseError>;
+
+    /// Generate a random `i32` within the inclusive range `[min, max]`.
+    fn gen_i32_range(&mut self, min: i32, max: i32) -> Result<i32, ResponseError>;
+
+    /// Generate a random `usize` within the inclusive range `[min, max]`.
+    fn gen_usize_range(&mut self, min: usize, max: usize) -> Result<usize, ResponseError>;
+
+    /// Generate a random `f64` within the inclusive range `[min, max]`.
+    fn gen_f64_range(&mut self, min: f64, max: f64) -> Result<f64, ResponseError>;
+
+    /// Generate a random alphanumeric character (`[0-9a-zA-Z]`).
+    fn gen_alphanumeric_char(&mut self) -> Result<char, ResponseError>;
+
+    /// Choose a random index in `0..len`. Returns an error if `len == 0`.
+    fn choose_index(&mut self, len: usize) -> Result<usize, ResponseError>;
+
+    /// Return `true` with probability `numerator / denominator`.
+    fn ratio(&mut self, numerator: u32, denominator: u32) -> Result<bool, ResponseError>;
+}
+
+impl RandomProvider for Unstructured<'_> {
+    fn gen_bool(&mut self) -> Result<bool, ResponseError> {
+        self.arbitrary::<bool>()
+            .map_err(|_| ResponseError::Exhausted)
+    }
+
+    fn gen_i32_range(&mut self, min: i32, max: i32) -> Result<i32, ResponseError> {
+        self.int_in_range(min..=max)
+            .map_err(|_| ResponseError::Exhausted)
+    }
+
+    fn gen_usize_range(&mut self, min: usize, max: usize) -> Result<usize, ResponseError> {
+        self.int_in_range(min..=max)
+            .map_err(|_| ResponseError::Exhausted)
+    }
+
+    fn gen_f64_range(&mut self, min: f64, max: f64) -> Result<f64, ResponseError> {
+        // Unstructured doesn't support float ranges, so we generate a raw f64
+        // and map it into [min, max].
+        let raw: u32 = self.arbitrary().map_err(|_| ResponseError::Exhausted)?;
+        let fraction = (raw as f64) / (u32::MAX as f64); // [0.0, 1.0]
+        Ok(min + fraction * (max - min))
+    }
+
+    fn gen_alphanumeric_char(&mut self) -> Result<char, ResponseError> {
+        let idx: u8 = self
+            .int_in_range(0..=61)
+            .map_err(|_| ResponseError::Exhausted)?;
+        Ok(match idx {
+            0..=9 => (b'0' + idx) as char,
+            10..=35 => (b'a' + idx - 10) as char,
+            _ => (b'A' + idx - 36) as char,
+        })
+    }
+
+    fn choose_index(&mut self, len: usize) -> Result<usize, ResponseError> {
+        if len == 0 {
+            return Err(ResponseError::InvalidFormat(
+                "cannot choose from empty collection".into(),
+            ));
+        }
+        self.int_in_range(0..=(len - 1))
+            .map_err(|_| ResponseError::Exhausted)
+    }
+
+    fn ratio(&mut self, numerator: u32, denominator: u32) -> Result<bool, ResponseError> {
+        // Unstructured::ratio takes u8, so we scale down if needed.
+        // For ratios that fit in u8, use directly; otherwise approximate.
+        let (n, d) = if numerator <= u8::MAX as u32 && denominator <= u8::MAX as u32 {
+            (numerator as u8, denominator as u8)
+        } else {
+            // Scale to fit in u8
+            let scale = denominator.max(1) as f64 / 255.0;
+            let n = (numerator as f64 / scale).round() as u8;
+            let d = ((denominator as f64 / scale).round() as u8).max(1);
+            (n, d)
+        };
+        self.ratio(n, d).map_err(|_| ResponseError::Exhausted)
+    }
+}
+
+/// Newtype wrapper that implements [`RandomProvider`] for any [`rand::Rng`].
+///
+/// # Example
+///
+/// ```ignore
+/// use apollo_smith::RandProvider;
+///
+/// let mut rng = RandProvider(rand::rng());
+/// let response = ResponseBuilder::new(&mut rng, &doc, &schema).build()?;
+/// ```
+pub struct RandProvider<R>(pub R);
+
+impl<R: rand::Rng> RandomProvider for RandProvider<R> {
+    fn gen_bool(&mut self) -> Result<bool, ResponseError> {
+        Ok(self.0.random_bool(0.5))
+    }
+
+    fn gen_i32_range(&mut self, min: i32, max: i32) -> Result<i32, ResponseError> {
+        Ok(self.0.random_range(min..=max))
+    }
+
+    fn gen_usize_range(&mut self, min: usize, max: usize) -> Result<usize, ResponseError> {
+        Ok(self.0.random_range(min..=max))
+    }
+
+    fn gen_f64_range(&mut self, min: f64, max: f64) -> Result<f64, ResponseError> {
+        Ok(self.0.random_range(min..=max))
+    }
+
+    fn gen_alphanumeric_char(&mut self) -> Result<char, ResponseError> {
+        Ok(self.0.sample(rand::distr::Alphanumeric) as char)
+    }
+
+    fn choose_index(&mut self, len: usize) -> Result<usize, ResponseError> {
+        if len == 0 {
+            return Err(ResponseError::InvalidFormat(
+                "cannot choose from empty collection".into(),
+            ));
+        }
+        Ok(self.0.random_range(0..len))
+    }
+
+    fn ratio(&mut self, numerator: u32, denominator: u32) -> Result<bool, ResponseError> {
+        Ok(self.0.random_ratio(numerator, denominator))
+    }
+}
+
+/// Configuration for generating scalar values.
+///
+/// Each variant describes how to generate a value of a particular type using
+/// a [`RandomProvider`]. Register custom scalar configs via
+/// [`ResponseBuilder::with_scalar_config`][crate::ResponseBuilder::with_scalar_config].
+#[derive(Debug, Clone)]
+pub enum ScalarConfig {
+    /// Generate a random boolean.
+    Bool,
+    /// Generate a random integer in the given inclusive range.
+    Int { min: i32, max: i32 },
+    /// Generate a random float in the given inclusive range.
+    Float { min: f64, max: f64 },
+    /// Generate a random alphanumeric string with length in the given inclusive range.
+    String { min_len: usize, max_len: usize },
+}
+
+impl ScalarConfig {
+    /// The default configuration used for unknown or custom scalars: an
+    /// alphanumeric string of length 1–10.
+    pub const DEFAULT: Self = Self::String {
+        min_len: 1,
+        max_len: 10,
+    };
+
+    /// Generate a random value according to this configuration.
+    pub fn generate<R: RandomProvider>(&self, rng: &mut R) -> Result<Value, ResponseError> {
+        match *self {
+            Self::Bool => Ok(Value::Bool(rng.gen_bool()?)),
+            Self::Int { min, max } => Ok(Value::Number(rng.gen_i32_range(min, max)?.into())),
+            Self::Float { min, max } => {
+                let f = rng.gen_f64_range(min, max)?;
+                let num = Number::from_f64(f).ok_or_else(|| {
+                    ResponseError::InvalidFormat("generated non-finite float".into())
+                })?;
+                Ok(Value::Number(num))
+            }
+            Self::String { min_len, max_len } => {
+                let len = rng.gen_usize_range(min_len, max_len)?;
+                let s: Result<std::string::String, _> =
+                    (0..len).map(|_| rng.gen_alphanumeric_char()).collect();
+                Ok(Value::String(s?.into()))
+            }
+        }
+    }
+}
+
+/// Returns the default scalar configurations for the built-in GraphQL scalar types.
+pub fn default_scalar_configs() -> HashMap<Name, ScalarConfig> {
+    [
+        (Name::new_unchecked("Boolean"), ScalarConfig::Bool),
+        (
+            Name::new_unchecked("Int"),
+            ScalarConfig::Int { min: 0, max: 100 },
+        ),
+        (
+            Name::new_unchecked("ID"),
+            ScalarConfig::Int { min: 0, max: 100 },
+        ),
+        (
+            Name::new_unchecked("Float"),
+            ScalarConfig::Float {
+                min: -1.0,
+                max: 1.0,
+            },
+        ),
+        (
+            Name::new_unchecked("String"),
+            ScalarConfig::String {
+                min_len: 1,
+                max_len: 10,
+            },
+        ),
+    ]
+    .into_iter()
+    .collect()
+}