use crate::digest::ManifestDigest;
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ComponentType {
Server,
Agent,
Team,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PinnedRef {
pub name: String,
pub component_type: ComponentType,
pub version: semver::Version,
pub digest: ManifestDigest,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub resolved_from: Option<semver::VersionReq>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum ComponentRef {
Range {
name: String,
range: semver::VersionReq,
component_type: ComponentType,
},
Pinned(PinnedRef),
}
impl ComponentRef {
pub fn name(&self) -> &str {
match self {
ComponentRef::Range { name, .. } => name,
ComponentRef::Pinned(pinned) => &pinned.name,
}
}
pub fn component_type(&self) -> ComponentType {
match self {
ComponentRef::Range { component_type, .. } => *component_type,
ComponentRef::Pinned(pinned) => pinned.component_type,
}
}
pub fn is_pinned(&self) -> bool {
matches!(self, ComponentRef::Pinned(_))
}
pub fn as_pinned(&self) -> Option<&PinnedRef> {
match self {
ComponentRef::Pinned(pinned) => Some(pinned),
ComponentRef::Range { .. } => None,
}
}
}
#[cfg(test)]
mod tests {
use super::*;
fn sample_digest() -> ManifestDigest {
ManifestDigest::from_bytes(b"fixture-bytes")
}
#[test]
fn range_round_trips_with_kind_discriminator() {
let r = ComponentRef::Range {
name: "london-tube".to_string(),
range: semver::VersionReq::parse("^1.2").unwrap(),
component_type: ComponentType::Server,
};
let json = serde_json::to_value(&r).unwrap();
assert_eq!(json.get("kind").and_then(|v| v.as_str()), Some("range"));
assert_eq!(
json.get("name").and_then(|v| v.as_str()),
Some("london-tube")
);
assert_eq!(
json.get("component_type").and_then(|v| v.as_str()),
Some("server")
);
let back: ComponentRef = serde_json::from_value(json).unwrap();
assert_eq!(back, r);
}
#[test]
fn pinned_round_trips_flat_with_kind_discriminator() {
let pinned = PinnedRef {
name: "london-tube".to_string(),
component_type: ComponentType::Server,
version: semver::Version::parse("1.2.3").unwrap(),
digest: sample_digest(),
resolved_from: None,
};
let r = ComponentRef::Pinned(pinned.clone());
let json = serde_json::to_value(&r).unwrap();
let obj = json.as_object().expect("must serialize as a flat object");
let mut keys: Vec<&str> = obj.keys().map(|k| k.as_str()).collect();
keys.sort_unstable();
assert_eq!(
keys,
vec!["component_type", "digest", "kind", "name", "version"]
);
assert_eq!(obj.get("kind").and_then(|v| v.as_str()), Some("pinned"));
assert_eq!(
obj.get("name").and_then(|v| v.as_str()),
Some("london-tube")
);
assert_eq!(obj.get("version").and_then(|v| v.as_str()), Some("1.2.3"));
assert_eq!(
obj.get("component_type").and_then(|v| v.as_str()),
Some("server")
);
assert!(obj
.get("digest")
.and_then(|v| v.as_str())
.unwrap()
.starts_with("sha256:"));
let back: ComponentRef = serde_json::from_value(json).unwrap();
assert_eq!(back, r);
}
#[test]
fn pinned_ref_always_carries_version_and_digest() {
let pinned = PinnedRef {
name: "x".to_string(),
component_type: ComponentType::Server,
version: semver::Version::parse("0.1.0").unwrap(),
digest: sample_digest(),
resolved_from: None,
};
assert_eq!(pinned.version.to_string(), "0.1.0");
assert!(pinned.digest.as_str().starts_with("sha256:"));
}
#[test]
fn name_accessor_works_for_both_variants() {
let range = ComponentRef::Range {
name: "a".to_string(),
range: semver::VersionReq::parse("^1").unwrap(),
component_type: ComponentType::Server,
};
assert_eq!(range.name(), "a");
assert!(!range.is_pinned());
assert!(range.as_pinned().is_none());
let pinned = ComponentRef::Pinned(PinnedRef {
name: "b".to_string(),
component_type: ComponentType::Agent,
version: semver::Version::parse("2.0.0").unwrap(),
digest: sample_digest(),
resolved_from: None,
});
assert_eq!(pinned.name(), "b");
assert!(pinned.is_pinned());
assert!(pinned.as_pinned().is_some());
}
#[test]
fn component_type_orders_server_before_agent_before_team() {
assert!(ComponentType::Server < ComponentType::Agent);
assert!(ComponentType::Agent < ComponentType::Team);
assert!(ComponentType::Server < ComponentType::Team);
}
#[test]
fn a_pin_with_no_resolved_range_emits_exactly_the_original_five_keys() {
let r = ComponentRef::Pinned(PinnedRef {
name: "london-tube".to_string(),
component_type: ComponentType::Server,
version: semver::Version::parse("1.2.3").unwrap(),
digest: sample_digest(),
resolved_from: None,
});
let json = serde_json::to_value(&r).unwrap();
let obj = json.as_object().expect("must serialize as a flat object");
let mut keys: Vec<&str> = obj.keys().map(|k| k.as_str()).collect();
keys.sort_unstable();
assert_eq!(
keys,
vec!["component_type", "digest", "kind", "name", "version"],
"a `None` resolved_from must emit no key at all — `skip_serializing_if` is what \
keeps every checked-in fixture and every pinned digest constant unmoved"
);
assert!(
!obj.contains_key("resolved_from"),
"not even a null: a null would move the canonical bytes"
);
let back: ComponentRef = serde_json::from_value(json).unwrap();
assert_eq!(back, r);
}
#[test]
fn a_pin_carrying_the_range_it_resolved_emits_it_and_round_trips() {
let declared = semver::VersionReq::parse("^1.2").unwrap();
let r = ComponentRef::Pinned(PinnedRef {
name: "london-tube".to_string(),
component_type: ComponentType::Server,
version: semver::Version::parse("1.3.0").unwrap(),
digest: sample_digest(),
resolved_from: Some(declared.clone()),
});
let json = serde_json::to_value(&r).unwrap();
let obj = json.as_object().expect("must serialize as a flat object");
let mut keys: Vec<&str> = obj.keys().map(|k| k.as_str()).collect();
keys.sort_unstable();
assert_eq!(
keys,
vec![
"component_type",
"digest",
"kind",
"name",
"resolved_from",
"version"
]
);
assert_eq!(
obj.get("resolved_from").and_then(|v| v.as_str()),
Some("^1.2"),
"the declared range is recorded verbatim, not collapsed into the resolution"
);
assert_eq!(obj.get("version").and_then(|v| v.as_str()), Some("1.3.0"));
let back: ComponentRef = serde_json::from_value(json).unwrap();
assert_eq!(back, r);
assert_eq!(back.as_pinned().unwrap().resolved_from, Some(declared));
}
#[test]
fn pin_json_written_before_resolved_from_existed_deserializes_to_none() {
let legacy = serde_json::json!({
"kind": "pinned",
"name": "london-tube",
"component_type": "server",
"version": "1.2.3",
"digest": sample_digest().as_str(),
});
let back: ComponentRef =
serde_json::from_value(legacy).expect("five-key pin JSON must still deserialize");
let pin = back.as_pinned().expect("must deserialize as a pin");
assert_eq!(
pin.resolved_from, None,
"an absent key must degrade to a defined value, never a decode failure"
);
assert_eq!(pin.version.to_string(), "1.2.3");
}
#[test]
fn component_type_accessor_works_for_both_variants() {
let range = ComponentRef::Range {
name: "x".to_string(),
range: semver::VersionReq::parse("^1").unwrap(),
component_type: ComponentType::Team,
};
assert_eq!(range.component_type(), ComponentType::Team);
let pinned = ComponentRef::Pinned(PinnedRef {
name: "x".to_string(),
component_type: ComponentType::Agent,
version: semver::Version::parse("1.0.0").unwrap(),
digest: sample_digest(),
resolved_from: None,
});
assert_eq!(pinned.component_type(), ComponentType::Agent);
}
}