Skip to content

Commit 5280ad3

Browse files
authored
Parse and validate variant metadata (#22512)
Implement `variants.json` parsing following [PEP 825](https://peps.python.org/pep-0825/). Invalid variant metadata is treat like other invalid package metadata, backtracking on the version (instead of failing). The parsed data isn't used yet. <!-- codex-thread: 01a134db-3dd5-7680-8370-0444d37c9576 -->
1 parent 8d16266 commit 5280ad3

16 files changed

Lines changed: 623 additions & 20 deletions

File tree

‎.config/nextest.toml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,12 @@ test-group = 'serial'
3737
filter = 'package(uv-keyring)'
3838
test-group = 'serial'
3939

40+
# Managed Python tests may download several interpreter archives.
41+
[[profile.ci-macos.overrides]]
42+
platform = 'cfg(target_os = "macos")'
43+
filter = 'test(/^python_(find|install|upgrade)::/)'
44+
slow-timeout = { period = "10s", terminate-after = 24 }
45+
4046
[[profile.ci-windows.overrides]]
4147
platform = 'cfg(target_os = "windows")'
4248
filter = 'test(/^python_install::/) + test(/^python_update::/) + test(/^python_find::/)'

‎Cargo.lock‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎crates/uv-distribution-filename/src/variant_label.rs‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
use std::fmt::{Display, Formatter};
22
use std::str::FromStr;
33

4+
use serde::{Deserialize, Deserializer};
5+
46
use uv_small_str::SmallString;
57

68
/// An invalid wheel variant label.
@@ -23,13 +25,21 @@ pub enum InvalidVariantLabel {
2325
Hash,
2426
Ord,
2527
PartialOrd,
28+
serde::Serialize,
2629
rkyv::Archive,
2730
rkyv::Deserialize,
2831
rkyv::Serialize,
2932
)]
3033
#[rkyv(derive(Debug))]
34+
#[serde(transparent)]
3135
pub struct VariantLabel(SmallString);
3236

37+
impl VariantLabel {
38+
pub fn as_str(&self) -> &str {
39+
&self.0
40+
}
41+
}
42+
3343
impl FromStr for VariantLabel {
3444
type Err = InvalidVariantLabel;
3545

@@ -47,6 +57,16 @@ impl FromStr for VariantLabel {
4757
}
4858
}
4959

60+
impl<'de> Deserialize<'de> for VariantLabel {
61+
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
62+
where
63+
D: Deserializer<'de>,
64+
{
65+
let label = String::deserialize(deserializer)?;
66+
Self::from_str(&label).map_err(serde::de::Error::custom)
67+
}
68+
}
69+
5070
impl Display for VariantLabel {
5171
fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
5272
Display::fmt(&self.0, f)

‎crates/uv-distribution-types/Cargo.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@ version-ranges = { workspace = true }
5959

6060
[dev-dependencies]
6161
indoc = { workspace = true }
62+
insta = { workspace = true }
6263
toml = { workspace = true }
6364

6465
[features]

‎crates/uv-distribution-types/src/lib.rs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,7 @@ pub use crate::specified_requirement::*;
9696
pub use crate::status_code_strategy::*;
9797
pub use crate::traits::*;
9898
pub use crate::variant_json::*;
99+
pub use crate::variants_json::*;
99100

100101
mod annotation;
101102
mod any;
@@ -131,6 +132,7 @@ mod specified_requirement;
131132
mod status_code_strategy;
132133
mod traits;
133134
mod variant_json;
135+
mod variants_json;
134136

135137
#[derive(Debug, Clone)]
136138
pub enum VersionOrUrlRef<'a, T: Pep508Url = VerbatimUrl> {
Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
use std::collections::{BTreeMap, HashSet};
2+
3+
use serde::{Deserialize, Serialize};
4+
use tracing::debug;
5+
6+
use uv_distribution_filename::VariantLabel;
7+
8+
// TODO(konsti): Update the schema URL once PEP 825 is finalized.
9+
/// The schema for the PEP 825 draft.
10+
const VARIANT_SCHEMA: &str = "https://variants-schema.wheelnext.dev/peps/825/v0.1.1.json";
11+
12+
/// An error parsing a variant metadata file.
13+
#[derive(Debug, thiserror::Error)]
14+
pub enum VariantsJsonParseError {
15+
/// The metadata could not be parsed and uses an unknown schema.
16+
#[error("Unknown variant metadata schema:\n `{schema}`:\n {source}")]
17+
UnknownSchema {
18+
schema: String,
19+
#[source]
20+
source: serde_json::Error,
21+
},
22+
/// The metadata is not valid JSON or cannot be deserialized.
23+
#[error(transparent)]
24+
Json(#[from] serde_json::Error),
25+
}
26+
27+
/// Variant properties, grouped by namespace and feature.
28+
type VariantProperties = BTreeMap<VariantNamespace, BTreeMap<VariantFeature, Vec<VariantValue>>>;
29+
30+
/// Index-level metadata for wheel variants, as defined by PEP 825.
31+
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
32+
#[serde(rename_all = "kebab-case", try_from = "VariantsJsonWire")]
33+
pub struct VariantsJsonContent {
34+
#[serde(rename = "$schema")]
35+
schema: String,
36+
default_priorities: DefaultPriorities,
37+
variants: BTreeMap<VariantLabel, VariantProperties>,
38+
}
39+
40+
impl VariantsJsonContent {
41+
/// Parse and validate the contents of a variant metadata file.
42+
pub fn from_slice(contents: &[u8]) -> Result<Self, VariantsJsonParseError> {
43+
match serde_json::from_slice(contents) {
44+
Ok(metadata) => Ok(metadata),
45+
Err(source) => {
46+
if let Ok(metadata) = serde_json::from_slice::<VariantsJsonSchema>(contents)
47+
&& metadata.schema != VARIANT_SCHEMA
48+
{
49+
debug!("Unknown variant metadata schema `{}`", metadata.schema);
50+
return Err(VariantsJsonParseError::UnknownSchema {
51+
schema: metadata.schema,
52+
source,
53+
});
54+
}
55+
Err(VariantsJsonParseError::Json(source))
56+
}
57+
}
58+
}
59+
}
60+
61+
/// Default priorities for the namespaces used by a release's variants.
62+
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
63+
#[serde(deny_unknown_fields)]
64+
struct DefaultPriorities {
65+
namespace: Vec<VariantNamespace>,
66+
}
67+
68+
#[derive(Deserialize)]
69+
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
70+
struct VariantsJsonWire {
71+
#[serde(rename = "$schema")]
72+
schema: String,
73+
default_priorities: DefaultPriorities,
74+
variants: BTreeMap<VariantLabel, VariantProperties>,
75+
}
76+
77+
#[derive(Debug, thiserror::Error)]
78+
enum VariantMetadataError {
79+
#[error("Invalid variant namespace: `{0}`")]
80+
InvalidNamespace(String),
81+
#[error("Invalid variant feature: `{0}`")]
82+
InvalidFeature(String),
83+
#[error("Invalid variant value: `{0}`")]
84+
InvalidValue(String),
85+
#[error("Variant namespace priorities must be non-empty and unique")]
86+
NamespacePriorities,
87+
#[error("Variant namespace `{0}` is missing from default-priorities.namespace")]
88+
MissingNamespace(String),
89+
#[error("Variant feature `{0} :: {1}` must have at least one value")]
90+
EmptyValues(String, String),
91+
#[error("Variant feature `{0} :: {1}` must not contain duplicate values")]
92+
DuplicateValues(String, String),
93+
#[error("The null variant must not have properties")]
94+
NullProperties,
95+
}
96+
97+
impl TryFrom<VariantsJsonWire> for VariantsJsonContent {
98+
type Error = VariantMetadataError;
99+
100+
fn try_from(mut wire: VariantsJsonWire) -> Result<Self, Self::Error> {
101+
let namespaces = &wire.default_priorities.namespace;
102+
let namespace_set: HashSet<_> = namespaces.iter().collect();
103+
if namespaces.is_empty() || namespace_set.len() != namespaces.len() {
104+
return Err(VariantMetadataError::NamespacePriorities);
105+
}
106+
107+
for (label, properties) in &mut wire.variants {
108+
for (namespace, features) in properties.iter_mut() {
109+
if !features.is_empty() && !namespace_set.contains(namespace) {
110+
return Err(VariantMetadataError::MissingNamespace(namespace.0.clone()));
111+
}
112+
for (feature, values) in features {
113+
if values.is_empty() {
114+
return Err(VariantMetadataError::EmptyValues(
115+
namespace.0.clone(),
116+
feature.0.clone(),
117+
));
118+
}
119+
if values.iter().collect::<HashSet<_>>().len() != values.len() {
120+
return Err(VariantMetadataError::DuplicateValues(
121+
namespace.0.clone(),
122+
feature.0.clone(),
123+
));
124+
}
125+
if label.as_str() == "null" {
126+
return Err(VariantMetadataError::NullProperties);
127+
}
128+
}
129+
}
130+
properties.retain(|_, features| !features.is_empty());
131+
}
132+
133+
// Parse leniently for forward compatibility: accept unknown schema versions when their
134+
// contents pass validation.
135+
if wire.schema != VARIANT_SCHEMA {
136+
debug!("Unknown variant metadata schema `{}`", wire.schema);
137+
}
138+
139+
Ok(Self {
140+
schema: wire.schema,
141+
default_priorities: wire.default_priorities,
142+
variants: wire.variants,
143+
})
144+
}
145+
}
146+
147+
/// The schema field alone, used to identify unknown schemas when parsing fails.
148+
#[derive(Deserialize)]
149+
struct VariantsJsonSchema {
150+
#[serde(rename = "$schema")]
151+
schema: String,
152+
}
153+
154+
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
155+
#[serde(try_from = "String")]
156+
struct VariantNamespace(String);
157+
158+
impl TryFrom<String> for VariantNamespace {
159+
type Error = VariantMetadataError;
160+
161+
fn try_from(value: String) -> Result<Self, Self::Error> {
162+
if valid_component(&value, false) {
163+
Ok(Self(value))
164+
} else {
165+
Err(VariantMetadataError::InvalidNamespace(value))
166+
}
167+
}
168+
}
169+
170+
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
171+
#[serde(try_from = "String")]
172+
struct VariantFeature(String);
173+
174+
impl TryFrom<String> for VariantFeature {
175+
type Error = VariantMetadataError;
176+
177+
fn try_from(value: String) -> Result<Self, Self::Error> {
178+
if valid_component(&value, false) {
179+
Ok(Self(value))
180+
} else {
181+
Err(VariantMetadataError::InvalidFeature(value))
182+
}
183+
}
184+
}
185+
186+
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
187+
#[serde(try_from = "String")]
188+
struct VariantValue(String);
189+
190+
impl TryFrom<String> for VariantValue {
191+
type Error = VariantMetadataError;
192+
193+
fn try_from(value: String) -> Result<Self, Self::Error> {
194+
if valid_component(&value, true) {
195+
Ok(Self(value))
196+
} else {
197+
Err(VariantMetadataError::InvalidValue(value))
198+
}
199+
}
200+
}
201+
202+
fn valid_component(value: &str, allow_period: bool) -> bool {
203+
!value.is_empty()
204+
&& value.bytes().all(|character| {
205+
character.is_ascii_lowercase()
206+
|| character.is_ascii_digit()
207+
|| character == b'_'
208+
|| (allow_period && character == b'.')
209+
})
210+
}

0 commit comments

Comments
 (0)