Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -92,11 +92,11 @@ pub use keyword::{
ObjectKeyword, RelationshipKeyword, ResolutionKeyword, SchemaKeyword, StorageKeyword,
StringKeyword,
};
pub use validate::DocumentSchemaValidator;
/// Registration's native schema checks compare values and read list uniqueness as the
/// document validator does.
#[cfg(feature = "validation")]
pub(crate) use validate::{equal_json, is_unique};
pub use validate::{DocumentSchemaValidator, EnumViolationListing};

/// A JSON Schema simple type.
#[derive(
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -376,7 +376,17 @@ pub(super) fn generated_schema(
insert("multipleOf", cases.pick(&divisors));
}
if cases.chance(10) {
insert("enum", json!([cases.pick(values), cases.pick(values)]));
// Now and then an enum long enough to be looked up rather than scanned
let members: Vec<serde_json::Value> = if cases.chance(30) {
values
.iter()
.filter(|_| cases.chance(70))
.cloned()
.collect()
} else {
vec![cases.pick(values), cases.pick(values)]
};
insert("enum", serde_json::Value::Array(members));
}
if cases.chance(8) {
insert("const", cases.pick(values));
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,19 @@ use pattern::PatternCell;
#[cfg(feature = "validation")]
pub(crate) use v0::{equal_json, is_unique};

/// How much of an `enum`'s allowed values a violation lists, in its parameters and its
/// message: the longest run of them, from the first the schema writes, of at most
/// `max_values` values, each `null`, a boolean, a number or a string, whose JSON takes at most
/// `max_bytes` bytes together. The others are counted, not listed, so the error stays small
/// whatever the enum holds.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct EnumViolationListing {
/// The most allowed values listed.
pub max_values: usize,
/// The most bytes the listed values' JSON takes together.
pub max_bytes: usize,
}

/// A document type's validation schema ready to check document values: each of its patterns
/// checked to parse, and compiled the first time a value reaches it, and the generation of
/// `validation_schema` that built it, which checks them. The schema is shared, so a clone, or
Expand Down Expand Up @@ -103,14 +116,16 @@ impl DocumentSchemaValidator {
/// validator's depth check gives a too-deep value. That check, which runs before the
/// walk, is what bounds a document's own value depth; this bound guards the walk's
/// recursion for a caller that reaches it another way. The generation that built the
/// validator checks it.
/// validator checks it. An `enum` violation lists the first `max_enum_listed_values` of
/// the allowed values and counts the others (`None` lists them all).
Comment on lines +119 to +120

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Suggestion: Document the enum listing bounds using the actual public API

The public DocumentSchemaValidator::validate documentation refers to a nonexistent max_enum_listed_values parameter and describes only a count bound. The actual third argument is enum_listing: Option<EnumViolationListing>, whose max_bytes bound and array/object stop condition also affect the reported error; correcting the rustdoc will keep callers aligned with the implementation.

Suggested change
/// validator checks it. An `enum` violation lists the first `max_enum_listed_values` of
/// the allowed values and counts the others (`None` lists them all).
/// validator checks it. With `Some(enum_listing)`, an `enum` violation lists the longest
/// leading run that stays within `max_values` and `max_bytes`, stopping before an array or
/// object, and counts the rest; `None` lists every allowed value.

source: muse-spark-1.3-contributor (phase1-reviewer: general, rust-quality); gpt-6.1-sol (phase2-reviewer: general, architecture-layering, platform-versioning, rust-quality, security-auditor)

pub fn validate(
&self,
instance: &JsonValue,
max_value_depth: Option<usize>,
enum_listing: Option<EnumViolationListing>,
) -> Result<Option<ConsensusError>, ProtocolError> {
Comment thread
QuantumExplorer marked this conversation as resolved.
Resolved
match self.generation {
0 => self.validate_v0(instance, max_value_depth),
0 => self.validate_v0(instance, max_value_depth, enum_listing),
version => Err(ProtocolError::UnknownVersionMismatch {
method: "DocumentSchemaValidator::validate".to_string(),
known_versions: vec![0],
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ use super::super::{
NumberConstraints, ObjectConstraints, SchemaNode, StringConstraints, ValidationSchema,
ValidatorFormat,
};
use super::{DocumentSchemaValidator, PatternCell};
use super::{DocumentSchemaValidator, EnumViolationListing, PatternCell};
use crate::consensus::basic::json_schema_error::JsonSchemaError;
use crate::consensus::basic::value_error::ValueError;
use crate::consensus::basic::BasicError;
Expand All @@ -47,7 +47,7 @@ use regex::Regex;
use serde_json::{json, Map as JsonMap, Number as JsonNumber, Value as JsonValue};
use std::cell::RefCell;
use std::collections::hash_map::DefaultHasher;
use std::collections::{BTreeMap, BTreeSet, HashSet};
use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet};
use std::hash::{Hash, Hasher};
use std::marker::PhantomData;
use std::net::IpAddr;
Expand All @@ -65,6 +65,11 @@ mod tests;
/// JSON value instead.
const UNIQUE_ITEMS_PAIRWISE_LIMIT: usize = 15;

/// The `enum` length up to which the walk compares a value with each allowed value in turn;
/// it looks a value up among a longer enum's values by [`MemberKey`] instead, which reaches
/// the same verdict.
const ENUM_SCAN_LIMIT: usize = 16;

/// A date's digits, as the JSON Schema validator requires them besides the date parse,
/// which ignores missing zero padding.
static DATE: Lazy<Regex> =
Expand Down Expand Up @@ -202,8 +207,10 @@ impl DocumentSchemaValidator {
&self,
instance: &JsonValue,
max_value_depth: Option<usize>,
enum_listing: Option<EnumViolationListing>,
) -> Result<Option<ConsensusError>, ProtocolError> {
let mut walk = Walk::new(self, false, max_value_depth);
walk.enum_listing = enum_listing;
walk.node(&self.schema.root, instance, 0, 0)?;
if let Some(depth) = *walk.too_deep.borrow() {
// Guarded only when a limit is set, so one is
Expand Down Expand Up @@ -260,6 +267,14 @@ struct Walk<'v, 'i> {
/// The value-nesting depth at which the walk first went past `max_value_depth`, shared
/// with the walks a `contains` spawns so one going too deep refuses the whole value.
too_deep: Rc<RefCell<Option<usize>>>,
/// The allowed values of each `enum` longer than [`ENUM_SCAN_LIMIT`] the walk has met, by
/// the address of the schema's list, as the keys it looks a value up by: built the first
/// time the walk checks a value against the list, and shared with the walks a `contains`
/// spawns, so each value costs one lookup however many values the list holds. Each list's
/// keys are held with the deepest nesting any of them has.
enum_members: Rc<RefCell<HashMap<usize, EnumMembers>>>,
/// How much of an `enum`'s allowed values a violation lists, or `None` for all of them.
enum_listing: Option<EnumViolationListing>,
/// Ties the walk to the checked value's lifetime `'i`, so the borrow checker refuses a
/// value that does not outlive the walk: every address in `held` stays valid while it is
/// held, and a temporary can never be checked against the cache.
Expand Down Expand Up @@ -291,6 +306,8 @@ impl<'v, 'i> Walk<'v, 'i> {
held: Rc::new(RefCell::new(HashSet::new())),
max_value_depth,
too_deep: Rc::new(RefCell::new(None)),
enum_members: Rc::new(RefCell::new(HashMap::new())),
enum_listing: None,
instance: PhantomData,
}
}
Expand All @@ -310,6 +327,8 @@ impl<'v, 'i> Walk<'v, 'i> {
held: Rc::clone(&self.held),
max_value_depth: self.max_value_depth,
too_deep: Rc::clone(&self.too_deep),
enum_members: Rc::clone(&self.enum_members),
enum_listing: None,
instance: PhantomData,
}
}
Expand Down Expand Up @@ -477,10 +496,16 @@ impl<'v, 'i> Walk<'v, 'i> {
return Ok(());
}
if let Some(values) = &node.enum_values {
if !values.iter().any(|value| equal_value(instance, value)) {
if !self.enum_admits(values, instance) {
let listing = self.enum_listing;
self.fail("enum", "", || {
let options = json_of_values(values);
let message = format!("{instance} is not one of {options}");
let (options, unlisted) = listed_values(values, listing);
let message = match unlisted {
0 => format!("{instance} is not one of {options}"),
unlisted => {
format!("{instance} is not one of {options} or {unlisted} more")
}
};
(json!({ "enum": options }), message)
Comment thread
QuantumExplorer marked this conversation as resolved.
Resolved
});
}
Expand Down Expand Up @@ -546,6 +571,23 @@ impl<'v, 'i> Walk<'v, 'i> {
Ok(())
}

/// Whether `instance` equals one of `values`, an `enum`'s allowed values, as
/// [`equal_value`] compares them: by a scan of a short list, and by a lookup of the
/// value's [`MemberKey`] among a longer list's, whose keys are built once per walk.
fn enum_admits(&self, values: &'v [Value], instance: &JsonValue) -> bool {
if values.len() <= ENUM_SCAN_LIMIT {
return values.iter().any(|value| equal_value(instance, value));
}
let mut members = self.enum_members.borrow_mut();
let (keys, depth) = members.entry(values.as_ptr() as usize).or_insert_with(|| {
let keys: HashSet<MemberKey> = values.iter().filter_map(MemberKey::of_value).collect();
let depth = keys.iter().map(MemberKey::depth).max().unwrap_or(0);
(keys, depth)
});
// A value nested deeper than every allowed value equals none, and is not read further
MemberKey::of_json(instance, *depth).is_some_and(|key| keys.contains(&key))
}

fn object(
&mut self,
object: &'v ObjectConstraints,
Expand Down Expand Up @@ -1286,3 +1328,132 @@ fn json_of_value(value: &Value) -> JsonValue {
fn json_of_values(values: &[Value]) -> JsonValue {
JsonValue::Array(values.iter().map(json_of_value).collect())
}

/// `values`, an `enum`'s allowed values, as JSON for a violation to list: those `listing`
/// admits, the longest run from the first that holds no array or object and fits its count
/// and its bytes, or all of them when there is no listing, and how many are left out.
fn listed_values(values: &[Value], listing: Option<EnumViolationListing>) -> (JsonValue, usize) {
let Some(listing) = listing else {
return (json_of_values(values), 0);
};
let mut listed = Vec::new();
let mut bytes = 0;
for value in values.iter().take(listing.max_values) {
let json = json_of_value(value);
if json.is_array() || json.is_object() {
break;
}
bytes += json.to_string().len();
if bytes > listing.max_bytes {
break;
}
listed.push(json);
}
let unlisted = values.len() - listed.len();
(JsonValue::Array(listed), unlisted)
Comment on lines +1341 to +1353

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Suggestion: Align the short-enum compatibility promise with bounded error listings

listed_values applies the count, byte, and array/object bounds whenever enum_listing is present, not only when the enum exceeds ENUM_SCAN_LIMIT. Protocol 15 passes Some(enum_listing) for every native document validation, so an enum with 16 or fewer members can now report an empty or truncated params.enum when its first member is a large string, array, or object, contrary to the PR description's claim that enums of 16 or fewer values report exactly as before. The bounds are appropriate for keeping client errors readable, so either narrow the stated compatibility guarantee and add regression tests for short enums with large or compound members, or change the implementation only if preserving the stronger promise is required.

source: gpt-6.1-sol (phase2-reviewer: general, architecture-layering, platform-versioning, rust-quality, security-auditor)

}

/// The keys of an `enum`'s allowed values, with the deepest nesting any of them has.
type EnumMembers = (HashSet<MemberKey>, usize);

/// A value as [`equal_value`] compares it with an `enum`'s allowed value: two values are
/// equal exactly when their keys are. A number is keyed by its value whatever its reading
/// (an integral float as the integer it is), an array element by element, and an object
/// entry by entry in the order it holds them, as [`equal_value`] pairs them.
#[derive(PartialEq, Eq, Hash)]
enum MemberKey {
Null,
Bool(bool),
/// A number with an integral value within `i128`, whatever its reading.
Integer(i128),
/// Any other number, by its f64 bits.
Float(u64),
Text(String),
Array(Vec<MemberKey>),
Object(Vec<(String, MemberKey)>),
}

impl MemberKey {
/// The key of a number: `None` for NaN, which equals no number.
fn of_num(number: Num) -> Option<Self> {
Some(match number {
Num::U(number) => MemberKey::Integer(i128::from(number)),
Num::I(number) => MemberKey::Integer(i128::from(number)),
Num::F(number) if number.is_nan() => return None,
// Exact: an integral f64 below 2^127 in magnitude is an `i128`
Num::F(number) if number.fract() == 0. && number.abs() < i128::MAX as f64 => {
MemberKey::Integer(number as i128)
}
// -0.0 is integral, so a float keyed by its bits is never zero
Num::F(number) => MemberKey::Float(number.to_bits()),
})
}

/// The key of a value of the document, read at most `depth` arrays or objects deep:
/// `None` for one nested deeper, or holding a number that equals no number, which equals
/// no allowed value nested at most `depth` deep.
fn of_json(value: &JsonValue, depth: usize) -> Option<Self> {
Some(match value {
JsonValue::Null => MemberKey::Null,
JsonValue::Bool(value) => MemberKey::Bool(*value),
JsonValue::Number(number) => return MemberKey::of_num(Num::of_json(number)),
JsonValue::String(value) => MemberKey::Text(value.clone()),
JsonValue::Array(values) => MemberKey::Array(
values
.iter()
.map(|value| MemberKey::of_json(value, depth.checked_sub(1)?))
.collect::<Option<_>>()?,
),
JsonValue::Object(map) => MemberKey::Object(
map.iter()
.map(|(name, value)| {
Some((
name.clone(),
MemberKey::of_json(value, depth.checked_sub(1)?)?,
))
})
.collect::<Option<_>>()?,
),
})
}

/// How many arrays or objects deep the key nests: 0 for a key of neither.
fn depth(&self) -> usize {
match self {
MemberKey::Array(keys) => 1 + keys.iter().map(MemberKey::depth).max().unwrap_or(0),
MemberKey::Object(entries) => {
1 + entries
.iter()
.map(|(_, key)| key.depth())
.max()
.unwrap_or(0)
}
_ => 0,
}
}

/// The key of an `enum`'s allowed value: `None` for one no value of the document
/// equals, such as bytes or a map with a key that is not text.
fn of_value(value: &Value) -> Option<Self> {
Some(match value {
Value::Null => MemberKey::Null,
Value::Bool(value) => MemberKey::Bool(*value),
Value::Text(value) => MemberKey::Text(value.clone()),
Value::Array(values) => MemberKey::Array(
values
.iter()
.map(MemberKey::of_value)
.collect::<Option<_>>()?,
),
Value::Map(entries) => MemberKey::Object(
entries
.iter()
.map(|(name, value)| {
Some((name.as_text()?.to_string(), MemberKey::of_value(value)?))
})
.collect::<Option<_>>()?,
),
value => return MemberKey::of_num(Num::of_value(value)?),
})
}
}
Loading
Loading