1pub mod v2 {
13 include!(concat!(env!("OUT_DIR"), "/ridl.ir.v2.rs"));
18 #[expect(clippy::useless_borrows_in_formatting)]
32 mod serde_impls {
33 use super::*;
34
35 include!(concat!(env!("OUT_DIR"), "/ridl.ir.v2.serde.rs"));
36 }
37
38 static DESCRIPTOR_POOL: std::sync::LazyLock<prost_reflect::DescriptorPool> =
46 std::sync::LazyLock::new(|| {
47 prost_reflect::DescriptorPool::decode(
48 include_bytes!(concat!(env!("OUT_DIR"), "/ir_descriptor.binpb")).as_slice(),
49 )
50 .expect("the embedded descriptor set decodes: build.rs wrote it from the schema compilation that generated these types")
51 });
52
53 fn descriptor(name: &str) -> prost_reflect::MessageDescriptor {
56 DESCRIPTOR_POOL
57 .get_message_by_name(name)
58 .unwrap_or_else(|| panic!("{name} is declared by the compiled schema"))
59 }
60
61 pub(crate) fn package_descriptor() -> prost_reflect::MessageDescriptor {
64 descriptor("ridl.ir.v2.Package")
65 }
66
67 pub(crate) fn system_descriptor() -> prost_reflect::MessageDescriptor {
70 descriptor("ridl.ir.v2.System")
71 }
72
73 pub(crate) fn codegen_request_descriptor() -> prost_reflect::MessageDescriptor {
76 descriptor("ridl.codegen.v1.CodegenRequest")
77 }
78
79 pub(crate) fn codegen_model_descriptor() -> prost_reflect::MessageDescriptor {
83 descriptor("ridl.codegen.v1.Model")
84 }
85
86 fn transcode<M: prost::Message>(
93 descriptor: prost_reflect::MessageDescriptor,
94 message: &M,
95 ) -> Result<prost_reflect::DynamicMessage, prost::DecodeError> {
96 let mut dynamic = prost_reflect::DynamicMessage::new(descriptor);
97 dynamic.transcode_from(message)?;
98 Ok(dynamic)
99 }
100
101 pub fn fallible_transport_identity(
107 interface: &str,
108 ordinal: u32,
109 fallible: &FallibleType,
110 ) -> String {
111 format!(
112 "{interface}#{ordinal}:{ok}|{err}",
113 ok = fallible.ok,
114 err = fallible.err
115 )
116 }
117
118 #[derive(Debug)]
125 pub enum SerializeError {
126 Json(serde_json::Error),
132 Text(prost::DecodeError),
137 Class(crate::class::InteractionClassError),
140 }
141
142 impl std::fmt::Display for SerializeError {
143 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
144 match self {
145 Self::Json(source) => write!(
146 f,
147 "cannot render the package as canonical protobuf JSON: {source}; the known \
148 cause is an enum field holding a discriminant outside the schema"
149 ),
150 Self::Text(source) => write!(
151 f,
152 "cannot render the package as prototext: {source}; the known cause \
153 is composite nesting deeper than the transcoding decoder's recursion limit"
154 ),
155 Self::Class(source) => write!(f, "{source}"),
156 }
157 }
158 }
159
160 impl std::error::Error for SerializeError {
161 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
162 match self {
163 Self::Json(source) => Some(source),
164 Self::Text(source) => Some(source),
165 Self::Class(source) => Some(source),
166 }
167 }
168 }
169
170 pub fn to_json_pretty(package: &Package) -> Result<String, SerializeError> {
191 crate::class::check_package(package).map_err(SerializeError::Class)?;
192 render_json(package)
193 }
194
195 pub fn system_to_json_pretty(system: &System) -> Result<String, SerializeError> {
199 render_json(system)
200 }
201
202 pub(crate) fn render_json<M: serde::Serialize>(message: &M) -> Result<String, SerializeError> {
206 let mut buf = Vec::new();
207 let mut serializer = serde_json::Serializer::pretty(&mut buf);
208 serde::Serialize::serialize(message, &mut serializer).map_err(SerializeError::Json)?;
209 Ok(String::from_utf8(buf).expect("serde_json emits UTF-8"))
210 }
211
212 pub(crate) const MAX_JSON_NESTING: usize = 1_000;
231
232 const JSON_PARSE_STACK: usize = 16 * 1024 * 1024;
237
238 pub(crate) fn max_json_nesting(text: &str) -> usize {
246 let mut depth = 0usize;
247 let mut deepest = 0usize;
248 let mut in_string = false;
249 let mut escaped = false;
250 for byte in text.bytes() {
251 if in_string {
252 if escaped {
253 escaped = false;
254 } else if byte == b'\\' {
255 escaped = true;
256 } else if byte == b'"' {
257 in_string = false;
258 }
259 } else {
260 match byte {
261 b'"' => in_string = true,
262 b'{' | b'[' => {
263 depth += 1;
264 deepest = deepest.max(depth);
265 }
266 b'}' | b']' => depth = depth.saturating_sub(1),
267 _ => {}
268 }
269 }
270 }
271 deepest
272 }
273
274 pub fn from_json(text: &str) -> Result<Package, serde_json::Error> {
300 let package: Package = read_json(text)?;
301 crate::class::check_package(&package).map_err(serde::de::Error::custom)?;
302 Ok(package)
303 }
304
305 #[derive(Debug)]
307 pub enum LoadError {
308 Io(std::io::Error),
310 Parse(String),
312 }
313
314 impl std::fmt::Display for LoadError {
315 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
316 match self {
317 LoadError::Io(err) => write!(f, "cannot read the IR snapshot: {err}"),
318 LoadError::Parse(err) => {
319 write!(f, "the IR snapshot is not valid IR v2 JSON: {err}")
320 }
321 }
322 }
323 }
324
325 impl std::error::Error for LoadError {}
326
327 pub fn load_ir_json(path: &std::path::Path) -> Result<Package, LoadError> {
331 let text = std::fs::read_to_string(path).map_err(LoadError::Io)?;
332 from_json(&text).map_err(|err| LoadError::Parse(err.to_string()))
333 }
334
335 pub fn system_from_json(text: &str) -> Result<System, serde_json::Error> {
339 read_json(text)
340 }
341
342 pub(crate) fn read_json<M>(text: &str) -> Result<M, serde_json::Error>
345 where
346 M: serde::de::DeserializeOwned + Send,
347 {
348 check_nesting(text)?;
349 on_parse_stack(|| parse_json(text))
350 }
351
352 pub(crate) fn read_json_ignoring_unknown<M>(
370 descriptor: prost_reflect::MessageDescriptor,
371 text: &str,
372 ) -> Result<M, serde_json::Error>
373 where
374 M: serde::de::DeserializeOwned + Send,
375 {
376 use serde::de::DeserializeSeed as _;
377 check_nesting(text)?;
378 on_parse_stack(|| {
379 let mut deserializer = serde_json::Deserializer::from_str(text);
380 deserializer.disable_recursion_limit();
381 let known = JsonShape::Message(descriptor).deserialize(&mut deserializer)?;
382 deserializer.end()?;
383 serde::Deserialize::deserialize(known)
384 })
385 }
386
387 #[derive(Clone)]
390 enum JsonShape {
391 Message(prost_reflect::MessageDescriptor),
393 List(Box<JsonShape>),
395 Map(Box<JsonShape>),
397 Opaque,
399 }
400
401 impl JsonShape {
402 fn of(field: &prost_reflect::FieldDescriptor) -> JsonShape {
404 use prost_reflect::Kind;
405 if field.is_map() {
406 let Kind::Message(entry) = field.kind() else {
407 return JsonShape::Opaque;
408 };
409 return JsonShape::Map(Box::new(JsonShape::of_kind(
410 &entry.map_entry_value_field().kind(),
411 )));
412 }
413 let item = JsonShape::of_kind(&field.kind());
414 if field.is_list() {
415 JsonShape::List(Box::new(item))
416 } else {
417 item
418 }
419 }
420
421 fn of_kind(kind: &prost_reflect::Kind) -> JsonShape {
422 match kind {
423 prost_reflect::Kind::Message(message)
424 if !message.full_name().starts_with("google.protobuf.") =>
425 {
426 JsonShape::Message(message.clone())
427 }
428 _ => JsonShape::Opaque,
429 }
430 }
431 }
432
433 impl<'de> serde::de::DeserializeSeed<'de> for JsonShape {
434 type Value = serde_json::Value;
435
436 fn deserialize<D: serde::Deserializer<'de>>(
437 self,
438 deserializer: D,
439 ) -> Result<Self::Value, D::Error> {
440 match self {
441 JsonShape::Opaque => serde::Deserialize::deserialize(deserializer),
442 shape => deserializer.deserialize_any(ShapeVisitor(shape)),
443 }
444 }
445 }
446
447 struct ShapeVisitor(JsonShape);
448
449 impl<'de> serde::de::Visitor<'de> for ShapeVisitor {
450 type Value = serde_json::Value;
451
452 fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
453 formatter.write_str(match self.0 {
454 JsonShape::List(_) => "an array",
455 _ => "an object",
456 })
457 }
458
459 fn visit_unit<E>(self) -> Result<Self::Value, E> {
461 Ok(serde_json::Value::Null)
462 }
463
464 fn visit_seq<A: serde::de::SeqAccess<'de>>(
465 self,
466 mut seq: A,
467 ) -> Result<Self::Value, A::Error> {
468 let JsonShape::List(item) = self.0 else {
469 return Err(serde::de::Error::invalid_type(
470 serde::de::Unexpected::Seq,
471 &self,
472 ));
473 };
474 let mut items = Vec::new();
475 while let Some(value) = seq.next_element_seed((*item).clone())? {
476 items.push(value);
477 }
478 Ok(serde_json::Value::Array(items))
479 }
480
481 fn visit_map<A: serde::de::MapAccess<'de>>(
482 self,
483 mut map: A,
484 ) -> Result<Self::Value, A::Error> {
485 use serde::de::Error as _;
486 let mut out = serde_json::Map::new();
487 match &self.0 {
488 JsonShape::Message(descriptor) => {
489 let mut seen = std::collections::HashSet::new();
490 while let Some(key) = map.next_key::<String>()? {
491 let field = descriptor
492 .get_field_by_json_name(&key)
493 .or_else(|| descriptor.get_field_by_name(&key));
494 match field {
495 Some(field) => {
496 if !seen.insert(field.number()) {
497 return Err(A::Error::custom(format!(
498 "duplicate field `{key}`"
499 )));
500 }
501 let value = map.next_value_seed(JsonShape::of(&field))?;
502 out.insert(key, value);
503 }
504 None => {
505 map.next_value::<serde::de::IgnoredAny>()?;
506 }
507 }
508 }
509 }
510 JsonShape::Map(value_shape) => {
511 while let Some(key) = map.next_key::<String>()? {
512 let value = map.next_value_seed((**value_shape).clone())?;
513 if out.insert(key.clone(), value).is_some() {
514 return Err(A::Error::custom(format!("duplicate key `{key}`")));
515 }
516 }
517 }
518 JsonShape::List(_) | JsonShape::Opaque => {
519 return Err(A::Error::invalid_type(serde::de::Unexpected::Map, &self));
520 }
521 }
522 Ok(serde_json::Value::Object(out))
523 }
524 }
525
526 fn check_nesting(text: &str) -> Result<(), serde_json::Error> {
528 if max_json_nesting(text) > MAX_JSON_NESTING {
529 return Err(<serde_json::Error as serde::de::Error>::custom(format!(
530 "the input nests deeper than {MAX_JSON_NESTING} JSON levels, the ceiling this \
531 reader enforces (ADR-0014 decision 14); real IR nests orders of magnitude \
532 shallower"
533 )));
534 }
535 Ok(())
536 }
537
538 fn on_parse_stack<R: Send>(parse: impl FnOnce() -> R + Send) -> R {
541 if cfg!(target_family = "wasm") {
542 parse()
551 } else {
552 std::thread::scope(|scope| {
553 let handle = std::thread::Builder::new()
554 .stack_size(JSON_PARSE_STACK)
555 .spawn_scoped(scope, parse)
556 .expect("the JSON parse thread spawns");
557 match handle.join() {
558 Ok(result) => result,
559 Err(payload) => std::panic::resume_unwind(payload),
560 }
561 })
562 }
563 }
564
565 fn parse_json<M: serde::de::DeserializeOwned>(text: &str) -> Result<M, serde_json::Error> {
570 let mut deserializer = serde_json::Deserializer::from_str(text);
571 deserializer.disable_recursion_limit();
572 let message: M = serde::Deserialize::deserialize(&mut deserializer)?;
573 deserializer.end()?;
574 Ok(message)
575 }
576
577 pub fn to_text_format(package: &Package) -> Result<String, SerializeError> {
591 crate::class::check_package(package).map_err(SerializeError::Class)?;
592 render_text_for(package_descriptor(), package)
593 }
594
595 pub fn system_to_text_format(system: &System) -> Result<String, SerializeError> {
599 render_text_for(system_descriptor(), system)
600 }
601
602 pub(crate) fn render_text_for<M: prost::Message>(
605 descriptor: prost_reflect::MessageDescriptor,
606 message: &M,
607 ) -> Result<String, SerializeError> {
608 let dynamic = transcode(descriptor, message).map_err(SerializeError::Text)?;
609 Ok(dynamic.to_text_format_with_options(
610 &prost_reflect::text_format::FormatOptions::new()
611 .pretty(true)
612 .skip_default_fields(false)
613 .print_message_fields_in_index_order(true),
614 ))
615 }
616
617 #[cfg(test)]
623 #[derive(Debug)]
624 pub(crate) enum TextFormatError {
625 Parse(prost_reflect::text_format::ParseError),
627 Transcode(prost::DecodeError),
629 }
630
631 #[cfg(test)]
632 impl std::fmt::Display for TextFormatError {
633 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
634 match self {
635 Self::Parse(source) => {
636 write!(f, "cannot parse the text as an IR package: {source}")
637 }
638 Self::Transcode(source) => write!(
639 f,
640 "cannot rebuild the parsed prototext as a package: {source}; the known cause \
641 is composite nesting deeper than the transcoding decoder's recursion limit"
642 ),
643 }
644 }
645 }
646
647 #[cfg(test)]
648 impl std::error::Error for TextFormatError {
649 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
650 match self {
651 Self::Parse(source) => Some(source),
652 Self::Transcode(source) => Some(source),
653 }
654 }
655 }
656
657 #[cfg(test)]
678 pub(crate) fn from_text_format(text: &str) -> Result<Package, TextFormatError> {
679 parse_text(package_descriptor(), text)
680 }
681
682 #[cfg(test)]
686 pub(crate) fn system_from_text_format(text: &str) -> Result<System, TextFormatError> {
687 parse_text(system_descriptor(), text)
688 }
689
690 #[cfg(test)]
691 fn parse_text<M: prost::Message + Default>(
692 descriptor: prost_reflect::MessageDescriptor,
693 text: &str,
694 ) -> Result<M, TextFormatError> {
695 let dynamic = prost_reflect::DynamicMessage::parse_text_format(descriptor, text)
696 .map_err(TextFormatError::Parse)?;
697 dynamic.transcode_to().map_err(TextFormatError::Transcode)
698 }
699
700 pub fn to_binary(package: &Package) -> Vec<u8> {
707 prost::Message::encode_to_vec(package)
708 }
709
710 pub fn from_binary(bytes: &[u8]) -> Result<Package, prost::DecodeError> {
713 let package: Package = prost::Message::decode(bytes)?;
714 crate::class::check_package(&package).map_err(|err| {
715 #[allow(deprecated)]
718 prost::DecodeError::new(err.to_string())
719 })?;
720 Ok(package)
721 }
722
723 pub fn system_to_binary(system: &System) -> Vec<u8> {
726 prost::Message::encode_to_vec(system)
727 }
728
729 pub fn system_from_binary(bytes: &[u8]) -> Result<System, prost::DecodeError> {
732 prost::Message::decode(bytes)
733 }
734
735 fn qualified(package: &str, name: &str) -> String {
740 if package.is_empty() {
741 name.to_string()
742 } else {
743 format!("{package}.{name}")
744 }
745 }
746
747 impl System {
748 pub fn qualified_name(&self) -> String {
751 qualified(&self.package, &self.name)
752 }
753 }
754
755 impl Component {
756 pub fn qualified_name(&self) -> String {
759 qualified(&self.package, &self.name)
760 }
761 }
762
763 impl Distribution {
764 pub fn qualified_name(&self) -> String {
767 qualified(&self.package, &self.name)
768 }
769 }
770
771 #[derive(Debug, Clone, Copy, PartialEq)]
802 pub struct InterfaceShape<'a> {
803 pub name: &'a str,
807 pub interface: &'a Interface,
809 pub service: Option<&'a Service>,
812 }
813
814 impl InterfaceShape<'_> {
815 pub fn visibility(&self) -> i32 {
820 match self.service {
821 Some(service) => service.visibility,
822 None => self.interface.visibility,
823 }
824 }
825
826 pub fn is_inline(&self) -> bool {
828 self.service.is_some()
829 }
830 }
831
832 impl Package {
833 pub fn shapes(&self) -> impl Iterator<Item = InterfaceShape<'_>> {
848 let named = self.interfaces.iter().map(|interface| InterfaceShape {
849 name: &interface.name,
850 interface,
851 service: None,
852 });
853 let inline = self.services.iter().flat_map(|service| {
854 service
855 .shapes
856 .iter()
857 .filter_map(move |slot| match slot.kind.as_ref()? {
858 service_shape::Kind::Inline(interface) => Some(InterfaceShape {
859 name: &service.name,
860 interface,
861 service: Some(service),
862 }),
863 service_shape::Kind::InterfaceRef(_) => None,
864 })
865 });
866 named.chain(inline)
867 }
868 }
869
870 pub fn unit_of(package: &Package) -> &str {
875 if package.unit.is_empty() {
876 &package.name
877 } else {
878 &package.unit
879 }
880 }
881
882 pub fn packages_of_unit<'a>(
884 unit: &str,
885 packages: &'a [Package],
886 ) -> impl Iterator<Item = &'a Package> {
887 select_unit(unit, packages.iter())
888 }
889
890 pub fn members_of_unit<'a>(
893 unit: &str,
894 packages: &[&'a Package],
895 ) -> impl Iterator<Item = &'a Package> {
896 select_unit(unit, packages.iter().copied())
897 }
898
899 fn select_unit<'a>(
902 unit: &str,
903 packages: impl Iterator<Item = &'a Package>,
904 ) -> impl Iterator<Item = &'a Package> {
905 let unit = unit.to_owned();
906 packages.filter(move |p| unit_of(p) == unit)
907 }
908
909 pub fn relative_name(unit: &str, package: &str, name: &str) -> String {
913 if package == unit {
914 return name.to_owned();
915 }
916 match package
920 .strip_prefix(unit)
921 .and_then(|rest| rest.strip_prefix('.'))
922 {
923 Some(below) => format!("{below}.{name}"),
924 None => format!("{package}.{name}"),
925 }
926 }
927
928 impl Package {
929 pub fn catalog_name(&self, shape: &InterfaceShape<'_>) -> String {
933 if shape.is_inline() {
934 shape.name.to_owned()
935 } else {
936 relative_name(unit_of(self), &self.name, shape.name)
937 }
938 }
939 }
940
941 pub fn unit_retired(unit: &str, packages: &[&Package]) -> Vec<RetiredInterface> {
948 let mut seen: Vec<&str> = Vec::new();
949 let mut retired: Vec<RetiredInterface> = members_of_unit(unit, packages)
950 .filter(|package| {
951 let first = !seen.contains(&package.name.as_str());
952 if first {
953 seen.push(&package.name);
954 }
955 first
956 })
957 .flat_map(|package| package.retired.iter().cloned())
958 .collect();
959 retired.sort_by_key(|entry| entry.number);
960 retired
961 }
962
963 pub fn referenced_packages(package: &Package) -> std::collections::BTreeSet<String> {
976 let mut found = std::collections::BTreeSet::new();
977 for decl in &package.decls {
978 walk_decl(decl, &mut found);
979 }
980 for interface in &package.interfaces {
981 for interaction in &interface.interactions {
982 walk_decl(interaction, &mut found);
983 }
984 }
985 for service in &package.services {
986 for slot in &service.shapes {
987 match &slot.kind {
988 Some(service_shape::Kind::InterfaceRef(reference)) => {
989 qualifier(reference, &mut found);
990 }
991 Some(service_shape::Kind::Inline(interface)) => {
992 for interaction in &interface.interactions {
993 walk_decl(interaction, &mut found);
994 }
995 }
996 None => {}
997 }
998 }
999 }
1000 found
1001 }
1002
1003 fn qualifier(reference: &str, found: &mut std::collections::BTreeSet<String>) {
1006 if let Some((package, _)) = reference.rsplit_once('.') {
1007 found.insert(package.to_string());
1008 }
1009 }
1010
1011 fn walk_decl(decl: &Decl, found: &mut std::collections::BTreeSet<String>) {
1014 match &decl.kind {
1015 Some(decl::Kind::TypeDef(type_def)) => walk_type_def(type_def, found),
1016 Some(decl::Kind::ConstDef(const_def)) => {
1017 if let Some(reference) = &const_def.type_ref {
1018 qualifier(reference, found);
1019 }
1020 }
1021 Some(decl::Kind::StructDef(struct_def)) => {
1022 for member in &struct_def.members {
1023 match &member.member {
1024 Some(struct_member::Member::Field(field)) => {
1025 if let Some(field_type) = &field.r#type {
1026 walk_field_type(field_type, found);
1027 }
1028 }
1029 Some(struct_member::Member::Reserved(_)) | None => {}
1031 }
1032 }
1033 }
1034 Some(decl::Kind::EnumDef(_)) => {}
1036 Some(decl::Kind::EnumSetDef(enum_set)) => {
1037 if let Some(reference) = &enum_set.backing_enum {
1038 qualifier(reference, found);
1039 }
1040 }
1041 Some(decl::Kind::UnionDef(union_def)) => {
1042 for arm in &union_def.arms {
1043 qualifier(&arm.type_ref, found);
1044 }
1045 }
1046 Some(decl::Kind::SignalDef(signal)) => qualifier(&signal.payload, found),
1047 Some(decl::Kind::EventDef(event)) => qualifier(&event.payload, found),
1048 Some(decl::Kind::CommandDef(command)) => {
1049 for param in &command.params {
1050 if let Some(field_type) = ¶m.r#type {
1051 walk_field_type(field_type, found);
1052 }
1053 }
1054 }
1055 Some(decl::Kind::QueryDef(query)) => {
1056 for param in &query.params {
1057 if let Some(field_type) = ¶m.r#type {
1058 walk_field_type(field_type, found);
1059 }
1060 }
1061 if let Some(return_type) = &query.return_type {
1062 walk_return_type(return_type, found);
1063 }
1064 }
1065 Some(decl::Kind::FixedDef(fixed)) => {
1066 if let Some(field_type) = &fixed.payload {
1067 walk_field_type(field_type, found);
1068 }
1069 }
1070 Some(decl::Kind::ReservedSlot(_)) | None => {}
1072 }
1073 }
1074
1075 fn walk_field_type(field_type: &FieldType, found: &mut std::collections::BTreeSet<String>) {
1078 match &field_type.kind {
1079 Some(field_type::Kind::Named(reference)) => qualifier(reference, found),
1080 Some(field_type::Kind::Primitive(_)) => {}
1082 Some(field_type::Kind::InlineScalar(type_def)) => walk_type_def(type_def, found),
1083 Some(field_type::Kind::Tuple(tuple)) => {
1084 for field in &tuple.fields {
1085 if let Some(inner) = &field.r#type {
1086 walk_field_type(inner, found);
1087 }
1088 }
1089 }
1090 Some(field_type::Kind::Array(array)) => {
1091 if let Some(element) = &array.element {
1092 walk_field_type(element, found);
1093 }
1094 }
1095 Some(field_type::Kind::Map(map)) => {
1096 if let Some(key) = &map.key {
1097 walk_field_type(key, found);
1098 }
1099 if let Some(value) = &map.value {
1100 walk_field_type(value, found);
1101 }
1102 }
1103 Some(field_type::Kind::Stream(stream)) => match &stream.element {
1104 Some(stream_type::Element::Named(reference)) => qualifier(reference, found),
1105 Some(stream_type::Element::Primitive(_)) | None => {}
1107 },
1108 None => {}
1109 }
1110 }
1111
1112 fn walk_type_def(type_def: &TypeDef, found: &mut std::collections::BTreeSet<String>) {
1114 if let Some(constraint) = &type_def.constraint
1115 && let Some(reference) = &constraint.pattern_const
1116 {
1117 qualifier(reference, found);
1118 }
1119 }
1120
1121 fn walk_return_type(return_type: &ReturnType, found: &mut std::collections::BTreeSet<String>) {
1122 match &return_type.kind {
1123 Some(return_type::Kind::Value(field_type)) => walk_field_type(field_type, found),
1124 Some(return_type::Kind::Fallible(fallible)) => {
1125 qualifier(&fallible.ok, found);
1126 qualifier(&fallible.err, found);
1127 }
1128 None => {}
1129 }
1130 }
1131
1132 pub fn constraint_is_vacuous(constraint: Option<&Constraint>) -> bool {
1148 let Some(c) = constraint else { return true };
1149 c.min.is_none()
1150 && c.max.is_none()
1151 && c.step.is_none()
1152 && c.len_min.is_none()
1153 && c.len_max.is_none()
1154 && c.pattern.is_none()
1155 && c.pattern_const.is_none()
1156 }
1157}
1158
1159pub mod artifact;
1160pub mod catalog_hash;
1161pub mod class;
1162pub mod codegen;
1163pub mod name;
1164pub mod projection;
1165pub mod rules;
1166pub mod step;
1167pub mod zero;
1168
1169#[cfg(test)]
1170mod v2_round_trip {
1171 use crate::v2;
1172
1173 fn interaction(name: &str, ordinal: u32, kind: v2::decl::Kind) -> v2::Decl {
1178 v2::Decl {
1179 limit: None,
1180 name: name.to_string(),
1181 visibility: v2::Visibility::Unspecified as i32,
1182 is_error: false,
1183 doc: String::new(),
1184 labels: Vec::new(),
1185 deprecated: None,
1186 ordinal,
1187 kind: Some(kind),
1188 links: Vec::new(),
1189 see: Vec::new(),
1190 since: Vec::new(),
1191 }
1192 }
1193
1194 fn named_type(name: &str) -> v2::FieldType {
1195 v2::FieldType {
1196 optional: false,
1197 kind: Some(v2::field_type::Kind::Named(name.to_string())),
1198 }
1199 }
1200
1201 fn stream_of(element: v2::stream_type::Element) -> v2::FieldType {
1202 v2::FieldType {
1203 optional: false,
1204 kind: Some(v2::field_type::Kind::Stream(v2::StreamType {
1205 element: Some(element),
1206 })),
1207 }
1208 }
1209
1210 fn fixture() -> v2::Package {
1216 let speed = v2::SignalDef {
1219 payload: "Speed".to_string(),
1220 declared_init: None,
1221 init: Some(v2::InitValue {
1222 derivable: true,
1223 value: Some("0.0".to_string()),
1224 }),
1225 timing: Some(v2::Timing {
1226 mode: v2::TimingMode::StrictPeriodic as i32,
1227 min_us: Some("10000".to_string()),
1228 max_us: Some("10000".to_string()),
1229 default_applied: false,
1230 }),
1231 family: v2::Family::Dispatch as i32,
1232 };
1233
1234 let door_opened = v2::EventDef {
1237 payload: "DoorEvent".to_string(),
1238 timing: Some(v2::Timing {
1239 mode: v2::TimingMode::Range as i32,
1240 min_us: Some("20000".to_string()),
1241 max_us: Some("500000".to_string()),
1242 default_applied: true,
1243 }),
1244 family: v2::Family::Dispatch as i32,
1245 };
1246
1247 let set_target = v2::CommandDef {
1249 params: vec![v2::Param {
1250 name: "target".to_string(),
1251 r#type: Some(named_type("Speed")),
1252 doc: String::new(),
1253 links: Vec::new(),
1254 see: Vec::new(),
1255 since: Vec::new(),
1256 }],
1257 contracts: vec![v2::Contract {
1258 kind: v2::ContractKind::Require as i32,
1259 source: "target >= speed".to_string(),
1260 signal_refs: vec!["speed".to_string()],
1261 param_refs: vec!["target".to_string()],
1262 uses_result: false,
1263 observer_id: "VehicleStatus.setTarget.require[0]".to_string(),
1264 }],
1265 timing: None,
1266 family: v2::Family::Dispatch as i32,
1267 shape: v2::Shape::None as i32,
1268 };
1269
1270 let fetch_faults = v2::QueryDef {
1273 params: vec![v2::Param {
1274 name: "page".to_string(),
1275 r#type: Some(named_type("PageSpec")),
1276 doc: String::new(),
1277 links: Vec::new(),
1278 see: Vec::new(),
1279 since: Vec::new(),
1280 }],
1281 return_type: Some(v2::ReturnType {
1282 kind: Some(v2::return_type::Kind::Fallible(v2::FallibleType {
1283 ok: "FaultPage".to_string(),
1284 err: "DiagError".to_string(),
1285 })),
1286 }),
1287 contracts: vec![v2::Contract {
1288 kind: v2::ContractKind::Ensure as i32,
1289 source: "result.count <= page.limit".to_string(),
1290 signal_refs: Vec::new(),
1291 param_refs: vec!["page".to_string()],
1292 uses_result: true,
1293 observer_id: "VehicleStatus.fetchFaults.ensure[0]".to_string(),
1294 }],
1295 timing: None,
1296 family: v2::Family::Dispatch as i32,
1297 };
1298
1299 let vin = v2::FixedDef {
1301 payload: Some(named_type("Vin")),
1302 };
1303
1304 let vehicle_status = v2::Interface {
1305 name: "VehicleStatus".to_string(),
1306 visibility: v2::Visibility::Public as i32,
1307 doc: "Vehicle status contract".to_string(),
1308 labels: Vec::new(),
1309 deprecated: None,
1310 interactions: vec![
1311 interaction("speed", 1, v2::decl::Kind::SignalDef(speed)),
1312 interaction("doorOpened", 2, v2::decl::Kind::EventDef(door_opened)),
1313 v2::Decl {
1316 ordinal: 3,
1317 kind: Some(v2::decl::Kind::ReservedSlot(v2::Reserved {
1318 ordinal: 3,
1319 name: Some("legacyMode".to_string()),
1320 value: None,
1321 })),
1322 ..interaction("", 3, v2::decl::Kind::ReservedSlot(v2::Reserved::default()))
1323 },
1324 interaction("setTarget", 4, v2::decl::Kind::CommandDef(set_target)),
1325 interaction("fetchFaults", 5, v2::decl::Kind::QueryDef(fetch_faults)),
1326 interaction("vin", 6, v2::decl::Kind::FixedDef(vin)),
1327 ],
1328 number: 0,
1329 provisional: false,
1330 links: Vec::new(),
1331 see: Vec::new(),
1332 since: Vec::new(),
1333 };
1334
1335 let tail_logs = v2::QueryDef {
1338 params: vec![v2::Param {
1339 name: "pattern".to_string(),
1340 r#type: Some(stream_of(v2::stream_type::Element::Primitive(
1341 v2::PrimitiveType::String as i32,
1342 ))),
1343 doc: String::new(),
1344 links: Vec::new(),
1345 see: Vec::new(),
1346 since: Vec::new(),
1347 }],
1348 return_type: Some(v2::ReturnType {
1349 kind: Some(v2::return_type::Kind::Value(stream_of(
1350 v2::stream_type::Element::Named("LogLine".to_string()),
1351 ))),
1352 }),
1353 contracts: Vec::new(),
1354 timing: None,
1355 family: v2::Family::Dispatch as i32,
1356 };
1357
1358 let status_service = v2::Service {
1361 name: "veh.adas.status".to_string(),
1362 visibility: v2::Visibility::Public as i32,
1363 doc: String::new(),
1364 labels: Vec::new(),
1365 deprecated: None,
1366 shapes: vec![v2::ServiceShape {
1367 kind: Some(v2::service_shape::Kind::InterfaceRef(
1368 "VehicleStatus".to_string(),
1369 )),
1370 }],
1371 links: Vec::new(),
1372 see: Vec::new(),
1373 since: Vec::new(),
1374 };
1375 let logs_service = v2::Service {
1378 name: "veh.adas.logs".to_string(),
1379 visibility: v2::Visibility::Public as i32,
1380 doc: String::new(),
1381 labels: Vec::new(),
1382 deprecated: None,
1383 shapes: vec![v2::ServiceShape {
1384 kind: Some(v2::service_shape::Kind::Inline(v2::Interface {
1385 name: String::new(),
1386 visibility: v2::Visibility::Unspecified as i32,
1387 doc: String::new(),
1388 labels: Vec::new(),
1389 deprecated: None,
1390 interactions: vec![interaction(
1391 "tailLogs",
1392 1,
1393 v2::decl::Kind::QueryDef(tail_logs),
1394 )],
1395 number: 0,
1396 provisional: false,
1397 links: Vec::new(),
1398 see: Vec::new(),
1399 since: Vec::new(),
1400 })),
1401 }],
1402 links: Vec::new(),
1403 see: Vec::new(),
1404 since: Vec::new(),
1405 };
1406
1407 v2::Package {
1408 name: "veh.adas".to_string(),
1409 decls: vec![v2::Decl {
1413 limit: None,
1414 name: "Speed".to_string(),
1415 visibility: v2::Visibility::Public as i32,
1416 is_error: false,
1417 doc: String::new(),
1418 labels: Vec::new(),
1419 deprecated: None,
1420 ordinal: 0,
1421 kind: Some(v2::decl::Kind::TypeDef(v2::TypeDef {
1422 backing: Some(v2::Backing {
1423 kind: Some(v2::backing::Kind::Unit("km/h".to_string())),
1424 }),
1425 constraint: None,
1426 declared_init: None,
1427 init: None,
1428 width: Some(v2::type_def::Width::FloatWidth(v2::FloatWidth::F32 as i32)),
1429 })),
1430 links: Vec::new(),
1431 see: Vec::new(),
1432 since: Vec::new(),
1433 }],
1434 interfaces: vec![vehicle_status],
1435 services: vec![status_service, logs_service],
1436 retired: Vec::new(),
1437 unit: "veh.adas".to_string(),
1438 }
1439 }
1440
1441 fn vocabulary_fixture() -> v2::Package {
1448 fn decl(name: &str, kind: v2::decl::Kind) -> v2::Decl {
1449 v2::Decl {
1450 limit: None,
1451 name: name.to_string(),
1452 visibility: v2::Visibility::Public as i32,
1453 is_error: false,
1454 doc: String::new(),
1455 labels: Vec::new(),
1456 deprecated: None,
1457 ordinal: 0,
1458 kind: Some(kind),
1459 links: Vec::new(),
1460 see: Vec::new(),
1461 since: Vec::new(),
1462 }
1463 }
1464
1465 fn field(name: &str, ordinal: u32, field_type: v2::FieldType) -> v2::Field {
1466 v2::Field {
1467 name: name.to_string(),
1468 ordinal,
1469 r#type: Some(field_type),
1470 declared_init: None,
1471 init: None,
1472 doc: String::new(),
1473 labels: Vec::new(),
1474 deprecated: None,
1475 links: Vec::new(),
1476 see: Vec::new(),
1477 since: Vec::new(),
1478 }
1479 }
1480
1481 let max_retry = v2::ConstDef {
1483 type_ref: Some("integer".to_string()),
1484 value: "24".to_string(),
1485 regex: None,
1486 };
1487
1488 let gear = v2::EnumDef {
1491 values: vec![
1492 v2::EnumValue {
1493 name: "PARK".to_string(),
1494 value: 1,
1495 doc: String::new(),
1496 links: Vec::new(),
1497 see: Vec::new(),
1498 since: Vec::new(),
1499 },
1500 v2::EnumValue {
1501 name: "DRIVE".to_string(),
1502 value: 2,
1503 doc: String::new(),
1504 links: Vec::new(),
1505 see: Vec::new(),
1506 since: Vec::new(),
1507 },
1508 ],
1509 reserved: vec![v2::Reserved {
1510 ordinal: 0,
1511 name: None,
1512 value: Some(7),
1513 }],
1514 open: false,
1515 };
1516
1517 let warnings = v2::EnumSetDef {
1520 backing_enum: None,
1521 bits: vec![
1522 v2::EnumValue {
1523 name: "LOW_FUEL".to_string(),
1524 value: 0,
1525 doc: String::new(),
1526 links: Vec::new(),
1527 see: Vec::new(),
1528 since: Vec::new(),
1529 },
1530 v2::EnumValue {
1531 name: "ICE_RISK".to_string(),
1532 value: 33,
1533 doc: String::new(),
1534 links: Vec::new(),
1535 see: Vec::new(),
1536 since: Vec::new(),
1537 },
1538 ],
1539 width: v2::IntWidth::U64 as i32,
1540 open: false,
1541 };
1542
1543 let plate_text = v2::TypeDef {
1546 backing: Some(v2::Backing {
1547 kind: Some(v2::backing::Kind::Primitive(
1548 v2::PrimitiveType::String as i32,
1549 )),
1550 }),
1551 constraint: Some(v2::Constraint {
1552 min: None,
1553 max: None,
1554 step: None,
1555 len_min: Some(1),
1556 len_max: Some(86),
1557 pattern: None,
1558 pattern_const: None,
1559 }),
1560 declared_init: None,
1561 init: None,
1562 width: None,
1563 };
1564
1565 let sample = v2::UnionDef {
1567 arms: vec![
1568 v2::UnionArm {
1569 name: "speed".to_string(),
1570 ordinal: 1,
1571 type_ref: "Speed".to_string(),
1572 doc: String::new(),
1573 links: Vec::new(),
1574 see: Vec::new(),
1575 since: Vec::new(),
1576 },
1577 v2::UnionArm {
1578 name: "gear".to_string(),
1579 ordinal: 2,
1580 type_ref: "Gear".to_string(),
1581 doc: String::new(),
1582 links: Vec::new(),
1583 see: Vec::new(),
1584 since: Vec::new(),
1585 },
1586 ],
1587 is_result: false,
1588 reserved: Vec::new(),
1589 };
1590
1591 let retries = v2::Field {
1597 declared_init: Some("3".to_string()),
1598 init: Some(v2::InitValue {
1599 derivable: true,
1600 value: Some("3".to_string()),
1601 }),
1602 ..field(
1603 "retries",
1604 1,
1605 v2::FieldType {
1606 optional: false,
1607 kind: Some(v2::field_type::Kind::InlineScalar(Box::new(v2::TypeDef {
1608 backing: Some(v2::Backing {
1609 kind: Some(v2::backing::Kind::Primitive(
1610 v2::PrimitiveType::Integer as i32,
1611 )),
1612 }),
1613 constraint: Some(v2::Constraint {
1614 min: Some("0".to_string()),
1615 max: Some("24".to_string()),
1616 step: None,
1617 len_min: None,
1618 len_max: None,
1619 pattern: None,
1620 pattern_const: None,
1621 }),
1622 declared_init: None,
1623 init: None,
1624 width: Some(v2::type_def::Width::IntWidth(v2::IntWidth::U8 as i32)),
1625 }))),
1626 },
1627 )
1628 };
1629
1630 let position = field(
1633 "position",
1634 2,
1635 v2::FieldType {
1636 optional: false,
1637 kind: Some(v2::field_type::Kind::Tuple(v2::TupleType {
1638 fields: vec![
1639 v2::TupleField {
1640 name: "x".to_string(),
1641 r#type: Some(named_type("Speed")),
1642 },
1643 v2::TupleField {
1644 name: "y".to_string(),
1645 r#type: Some(named_type("Speed")),
1646 },
1647 ],
1648 })),
1649 },
1650 );
1651
1652 let gears = field(
1654 "gears",
1655 3,
1656 v2::FieldType {
1657 optional: false,
1658 kind: Some(v2::field_type::Kind::Array(Box::new(v2::ArrayType {
1659 element: Some(Box::new(named_type("Gear"))),
1660 min: 1,
1661 max: 4096,
1662 }))),
1663 },
1664 );
1665
1666 let plates = v2::Field {
1670 deprecated: Some("superseded by gears".to_string()),
1671 ..field(
1672 "plates",
1673 4,
1674 v2::FieldType {
1675 optional: false,
1676 kind: Some(v2::field_type::Kind::Map(Box::new(v2::MapType {
1677 key: Some(Box::new(named_type("PlateText"))),
1678 value: Some(Box::new(named_type("Gear"))),
1679 min: 0,
1680 max: 53,
1681 }))),
1682 },
1683 )
1684 };
1685
1686 let snapshot = v2::StructDef {
1687 members: [retries, position, gears, plates]
1688 .into_iter()
1689 .map(|field| v2::StructMember {
1690 member: Some(v2::struct_member::Member::Field(Box::new(field))),
1691 })
1692 .collect(),
1693 fixed_layout: false,
1694 };
1695
1696 v2::Package {
1697 name: "veh.vocab".to_string(),
1698 decls: vec![
1699 decl("MAX_RETRY", v2::decl::Kind::ConstDef(max_retry)),
1700 decl("Gear", v2::decl::Kind::EnumDef(gear)),
1701 decl("Warnings", v2::decl::Kind::EnumSetDef(warnings)),
1702 decl("PlateText", v2::decl::Kind::TypeDef(plate_text)),
1703 v2::Decl {
1706 deprecated: Some("use Snapshot".to_string()),
1707 ..decl("Sample", v2::decl::Kind::UnionDef(sample))
1708 },
1709 decl("Snapshot", v2::decl::Kind::StructDef(snapshot)),
1710 ],
1711 interfaces: Vec::new(),
1712 services: Vec::new(),
1713 retired: Vec::new(),
1714 unit: String::new(),
1715 }
1716 }
1717
1718 #[test]
1719 fn protobuf_round_trip_preserves_package() {
1720 let package = fixture();
1721
1722 let buf = v2::to_binary(&package);
1723 let decoded = v2::from_binary(buf.as_slice()).expect("decode must succeed");
1724
1725 assert_eq!(package, decoded);
1726
1727 let vocabulary = vocabulary_fixture();
1729 let decoded_vocabulary =
1730 v2::from_binary(v2::to_binary(&vocabulary).as_slice()).expect("decode must succeed");
1731 assert_eq!(vocabulary, decoded_vocabulary);
1732
1733 let interface = &decoded.interfaces[0];
1734 let ordinals: Vec<u32> = interface.interactions.iter().map(|d| d.ordinal).collect();
1735 assert_eq!(
1736 ordinals,
1737 [1, 2, 3, 4, 5, 6],
1738 "one ordinal sequence, tombstone counted (ridl §11)"
1739 );
1740 let Some(v2::decl::Kind::ReservedSlot(tombstone)) = &interface.interactions[2].kind else {
1741 panic!("ordinal 3 must decode as a reserved tombstone");
1742 };
1743 assert_eq!(tombstone.name.as_deref(), Some("legacyMode"));
1744 let Some(v2::service_shape::Kind::Inline(inline)) = decoded.services[1]
1745 .shapes
1746 .first()
1747 .and_then(|slot| slot.kind.as_ref())
1748 else {
1749 panic!("veh.adas.logs must decode as an inline shape");
1750 };
1751 assert_eq!(inline.name, "", "an inline shape carries no name");
1752 let references: Vec<&str> = decoded.services[0]
1753 .shapes
1754 .iter()
1755 .filter_map(|slot| match &slot.kind {
1756 Some(v2::service_shape::Kind::InterfaceRef(reference)) => Some(reference.as_str()),
1757 _ => None,
1758 })
1759 .collect();
1760 assert_eq!(
1761 references,
1762 ["VehicleStatus"],
1763 "a service's set carries its references and nothing else"
1764 );
1765 }
1766
1767 fn package_with_command(family: v2::Family, shape: v2::Shape) -> v2::Package {
1770 v2::Package {
1771 name: "app".to_string(),
1772 interfaces: vec![v2::Interface {
1773 name: "I".to_string(),
1774 visibility: v2::Visibility::Public as i32,
1775 interactions: vec![v2::Decl {
1776 name: "c".to_string(),
1777 visibility: v2::Visibility::Public as i32,
1778 ordinal: 1,
1779 kind: Some(v2::decl::Kind::CommandDef(v2::CommandDef {
1780 family: family as i32,
1781 shape: shape as i32,
1782 ..Default::default()
1783 })),
1784 ..Default::default()
1785 }],
1786 ..Default::default()
1787 }],
1788 ..Default::default()
1789 }
1790 }
1791
1792 #[test]
1795 fn the_readers_reject_an_invalid_interaction_class() {
1796 let package = package_with_command(v2::Family::Intent, v2::Shape::None);
1797 let json = v2::render_json(&package).expect("the raw writer renders it");
1798 let err = v2::from_json(&json).expect_err("the JSON reader must refuse it");
1799 assert!(
1800 err.to_string().contains("invalid interaction class"),
1801 "{err}"
1802 );
1803 let bytes = prost::Message::encode_to_vec(&package);
1804 let err = v2::from_binary(&bytes).expect_err("the binary reader must refuse it");
1805 assert!(
1806 err.to_string().contains("invalid interaction class"),
1807 "{err}"
1808 );
1809 }
1810
1811 #[test]
1812 fn the_json_writer_refuses_an_invalid_interaction_class() {
1813 let package = package_with_command(v2::Family::Intent, v2::Shape::None);
1814 let err = v2::to_json_pretty(&package).expect_err("the writer must refuse it");
1815 assert!(matches!(err, v2::SerializeError::Class(_)), "{err}");
1816 }
1817
1818 #[test]
1819 fn a_valid_class_round_trips_through_both_readers() {
1820 let package = package_with_command(v2::Family::Intent, v2::Shape::Toggle);
1821 let json = v2::to_json_pretty(&package).expect("the writer renders it");
1822 assert_eq!(v2::from_json(&json).expect("the JSON parses"), package);
1823 assert_eq!(
1824 v2::from_binary(&v2::to_binary(&package)).expect("the binary decodes"),
1825 package
1826 );
1827 }
1828
1829 #[test]
1832 fn a_snapshot_without_family_reads_as_dispatch() {
1833 let package = package_with_command(v2::Family::Dispatch, v2::Shape::None);
1834 let json = v2::to_json_pretty(&package).expect("the writer renders it");
1835 let mut value: serde_json::Value =
1836 serde_json::from_str(&json).expect("the rendering is JSON");
1837 let command = value["interfaces"][0]["interactions"][0]["commandDef"]
1838 .as_object_mut()
1839 .expect("the command object");
1840 assert!(command.remove("family").is_some(), "`family` was rendered");
1841 assert!(command.remove("shape").is_some(), "`shape` was rendered");
1842 let stripped = serde_json::to_string(&value).expect("the stripped value renders");
1843 let read = v2::from_json(&stripped).expect("a 0.9 snapshot reads");
1844 assert_eq!(read, package);
1845 }
1846
1847 #[test]
1848 fn json_round_trip_preserves_package() {
1849 for package in [fixture(), vocabulary_fixture()] {
1850 let json = v2::to_json_pretty(&package).expect("the fixture serializes as IR JSON");
1851 let decoded = v2::from_json(&json).expect("json deserialization must succeed");
1852
1853 assert_eq!(package, decoded);
1854 }
1855 }
1856
1857 #[test]
1864 fn number_provisional_and_retired_round_trip_through_json_text_and_binary() {
1865 let mut package = fixture();
1866 package.interfaces[0].number = 4;
1867 package.interfaces[0].provisional = true;
1868 let Some(v2::service_shape::Kind::Inline(inline)) =
1869 package.services[1].shapes[0].kind.as_mut()
1870 else {
1871 panic!("veh.adas.logs holds an inline shape in slot 1");
1872 };
1873 inline.number = 5;
1874 package.retired = vec![
1875 v2::RetiredInterface {
1876 name: "LaneAssist".to_string(),
1877 number: 2,
1878 },
1879 v2::RetiredInterface {
1880 name: "service:veh.hvac.cabin".to_string(),
1881 number: 3,
1882 },
1883 ];
1884
1885 let json = v2::to_json_pretty(&package).expect("the package serializes as IR JSON");
1886 assert_eq!(v2::from_json(&json).expect("the JSON parses back"), package);
1887 let text = v2::to_text_format(&package).expect("the package serializes as prototext");
1888 assert_eq!(
1889 v2::from_text_format(&text).expect("the prototext parses back"),
1890 package
1891 );
1892 assert_eq!(
1893 v2::from_binary(v2::to_binary(&package).as_slice()).expect("the binary decodes"),
1894 package
1895 );
1896
1897 for needle in [
1898 r#""number": 4"#,
1899 r#""provisional": true"#,
1900 r#""number": 5"#,
1901 r#""name": "LaneAssist""#,
1902 r#""name": "service:veh.hvac.cabin""#,
1903 ] {
1904 assert!(
1905 json.contains(needle),
1906 "the JSON must carry {needle}, got: {json}"
1907 );
1908 }
1909
1910 let unnumbered = v2::to_json_pretty(&fixture()).expect("the fixture serializes as IR JSON");
1914 for needle in [
1915 r#""number": 0"#,
1916 r#""provisional": false"#,
1917 r#""retired": []"#,
1918 ] {
1919 assert!(
1920 unnumbered.contains(needle),
1921 "a default field must still be written, expected {needle} in: {unnumbered}"
1922 );
1923 }
1924 }
1925
1926 #[test]
1932 fn a_snapshot_lacking_the_number_fields_still_loads() {
1933 let package = v2::from_json(
1934 r#"{"name": "veh.x", "interfaces": [{"name": "LaneKeeping"}], "services": [{"name": "veh.x.s", "shapes": [{"inline": {"name": ""}}]}]}"#,
1935 )
1936 .expect("a pre-lock snapshot loads");
1937
1938 assert_eq!(package.interfaces[0].number, 0);
1939 assert!(!package.interfaces[0].provisional);
1940 let Some(v2::service_shape::Kind::Inline(inline)) =
1941 package.services[0].shapes[0].kind.as_ref()
1942 else {
1943 panic!("the service holds an inline shape");
1944 };
1945 assert_eq!(inline.number, 0);
1946 assert!(!inline.provisional);
1947 assert_eq!(package.retired, Vec::new());
1948 }
1949
1950 #[test]
1955 fn text_format_round_trip_preserves_package() {
1956 for package in [fixture(), vocabulary_fixture()] {
1957 let text = v2::to_text_format(&package).expect("the fixture serializes as prototext");
1958 let decoded = v2::from_text_format(&text).expect("prototext parsing must succeed");
1959
1960 assert_eq!(package, decoded);
1961 }
1962 }
1963
1964 #[test]
1979 fn text_format_is_pretty_with_defaults_in_index_order() {
1980 let text = v2::to_text_format(&fixture()).expect("the fixture serializes as prototext");
1981
1982 assert!(
1984 text.contains("\n "),
1985 "pretty printing must indent nested fields, got: {text}"
1986 );
1987 assert!(
1990 text.contains("is_error: false"),
1991 "a field holding its default must be emitted, got: {text}"
1992 );
1993 assert!(
1996 text.starts_with("name:"),
1997 "fields must print in schema index order, got: {text}"
1998 );
1999 }
2000
2001 fn strict_parse(json: &str) -> v2::Package {
2008 let mut deserializer = serde_json::Deserializer::from_str(json);
2009 let package = <v2::Package as serde::Deserialize>::deserialize(&mut deserializer)
2010 .expect("a strict conformant parser must accept the emitted JSON");
2011 deserializer.end().expect("no trailing input");
2012 package
2013 }
2014
2015 #[test]
2020 fn emitted_json_survives_a_strict_conformant_parse() {
2021 for package in [fixture(), vocabulary_fixture()] {
2022 let json = v2::to_json_pretty(&package).expect("the fixture serializes as IR JSON");
2023 assert_eq!(package, strict_parse(&json));
2024 }
2025 }
2026
2027 #[test]
2028 fn json_renders_timing_bounds_and_fallible_arms_exactly() {
2029 let json = v2::to_json_pretty(&fixture()).expect("the fixture serializes as IR JSON");
2030
2031 assert!(
2035 json.contains(r#""minUs": "10000""#),
2036 "the timing bound must be a JSON string, got: {json}"
2037 );
2038 assert!(
2040 json.contains(r#""ok": "FaultPage""#),
2041 "the ok arm must render, got: {json}"
2042 );
2043 assert!(
2044 json.contains(r#""err": "DiagError""#),
2045 "the err arm must render, got: {json}"
2046 );
2047 }
2048
2049 #[test]
2054 fn json_renders_64_bit_integer_fields_as_strings() {
2055 let json = v2::to_json_pretty(&vocabulary_fixture())
2056 .expect("the vocabulary fixture serializes as IR JSON");
2057
2058 assert!(
2060 json.contains(r#""max": "4096""#),
2061 "an array bound must be a JSON string, got: {json}"
2062 );
2063 assert!(
2065 json.contains(r#""lenMax": "86""#),
2066 "a length bound must be a JSON string, got: {json}"
2067 );
2068 assert!(
2070 json.contains(r#""value": "7""#),
2071 "a retired enum value must be a JSON string, got: {json}"
2072 );
2073 assert!(
2074 json.contains(r#""value": "33""#),
2075 "an enum-set bit position must be a JSON string, got: {json}"
2076 );
2077 }
2078
2079 #[test]
2080 fn fallible_transport_identity_follows_the_derivation_rule() {
2081 let fallible = v2::FallibleType {
2084 ok: "FaultPage".to_string(),
2085 err: "DiagError".to_string(),
2086 };
2087 assert_eq!(
2088 v2::fallible_transport_identity("VehicleStatus", 9, &fallible),
2089 "VehicleStatus#9:FaultPage|DiagError"
2090 );
2091
2092 let package = fixture();
2094 let interface = &package.interfaces[0];
2095 let query_decl = &interface.interactions[4];
2096 let Some(v2::decl::Kind::QueryDef(query)) = &query_decl.kind else {
2097 panic!("ordinal 5 must be the fallible query");
2098 };
2099 let Some(v2::return_type::Kind::Fallible(arms)) = &query.return_type.as_ref().unwrap().kind
2100 else {
2101 panic!("fetchFaults must return a fallible type");
2102 };
2103 assert_eq!(
2104 v2::fallible_transport_identity(&interface.name, query_decl.ordinal, arms),
2105 "VehicleStatus#5:FaultPage|DiagError"
2106 );
2107 }
2108
2109 #[test]
2116 fn shapes_walks_named_interfaces_and_inline_service_shapes() {
2117 let package = fixture();
2118 let walk: Vec<(&str, bool, usize)> = package
2119 .shapes()
2120 .map(|shape| {
2121 (
2122 shape.name,
2123 shape.is_inline(),
2124 shape.interface.interactions.len(),
2125 )
2126 })
2127 .collect();
2128 assert_eq!(
2129 walk,
2130 [("VehicleStatus", false, 6), ("veh.adas.logs", true, 1)],
2131 "the named interface, then the inline shape under the service's \
2132 dotted name",
2133 );
2134
2135 assert_eq!(package.services.len(), 2, "one reference form, one inline");
2139 assert!(
2140 !package
2141 .shapes()
2142 .any(|shape| shape.name == "veh.adas.status"),
2143 "a service naming an interface contributes no shape of its own",
2144 );
2145 }
2146
2147 #[test]
2148 fn relative_name_strips_the_unit_prefix() {
2149 assert_eq!(v2::relative_name("u", "u", "Session"), "Session");
2150 assert_eq!(
2151 v2::relative_name("u", "u.cluster", "Speed"),
2152 "cluster.Speed"
2153 );
2154 assert_eq!(
2155 v2::relative_name("com.example.hmi", "com.example.hmi.cluster.front", "A"),
2156 "cluster.front.A"
2157 );
2158 }
2159
2160 #[test]
2163 fn relative_name_keeps_the_full_name_of_a_package_outside_the_unit() {
2164 assert_eq!(
2165 v2::relative_name("u", "w.cluster", "Speed"),
2166 "w.cluster.Speed"
2167 );
2168 assert_eq!(v2::relative_name("u", "ux", "A"), "ux.A");
2169 assert_eq!(v2::relative_name("u.cluster", "u", "Session"), "u.Session");
2170 }
2171
2172 #[test]
2176 fn unit_retired_reads_a_package_named_twice_once() {
2177 let first = v2::Package {
2178 name: "u.cluster".to_string(),
2179 unit: "u".to_string(),
2180 retired: vec![v2::RetiredInterface {
2181 name: "cluster.Old".to_string(),
2182 number: 3,
2183 }],
2184 ..Default::default()
2185 };
2186 let second = v2::Package {
2187 retired: vec![v2::RetiredInterface {
2188 name: "cluster.Older".to_string(),
2189 number: 4,
2190 }],
2191 ..first.clone()
2192 };
2193 assert_eq!(
2194 v2::unit_retired("u", &[&first, &second]),
2195 first.retired,
2196 "the first package of a name is the one read"
2197 );
2198 }
2199
2200 #[test]
2201 fn an_inline_shape_keeps_its_global_name() {
2202 let mut package = fixture();
2203 package.name = "u.cluster".to_string();
2204 package.unit = "u".to_string();
2205 let inline = package
2206 .shapes()
2207 .find(|shape| shape.is_inline())
2208 .expect("the fixture has an inline shape");
2209 assert_eq!(package.catalog_name(&inline), "veh.adas.logs");
2210 let named = package
2211 .shapes()
2212 .find(|shape| !shape.is_inline())
2213 .expect("the fixture has a declared interface");
2214 assert_eq!(package.catalog_name(&named), "cluster.VehicleStatus");
2215 }
2216
2217 #[test]
2218 fn catalog_name_treats_an_empty_unit_as_the_package_name() {
2219 let mut package = fixture();
2220 package.unit = String::new();
2221 let named = package
2222 .shapes()
2223 .find(|shape| !shape.is_inline())
2224 .expect("the fixture has a declared interface");
2225 assert_eq!(package.catalog_name(&named), "VehicleStatus");
2226 }
2227
2228 #[test]
2229 fn unit_of_falls_back_to_the_name() {
2230 let bare = v2::Package {
2231 name: "p".to_string(),
2232 ..Default::default()
2233 };
2234 assert_eq!(v2::unit_of(&bare), "p");
2235 let member = v2::Package {
2236 name: "u.a".to_string(),
2237 unit: "u".to_string(),
2238 ..Default::default()
2239 };
2240 assert_eq!(v2::unit_of(&member), "u");
2241 }
2242
2243 #[test]
2244 fn packages_of_unit_selects_by_unit_of() {
2245 let package = |name: &str, unit: &str| v2::Package {
2246 name: name.to_string(),
2247 unit: unit.to_string(),
2248 ..Default::default()
2249 };
2250 let packages = [
2251 package("u", "u"),
2252 package("u.a", "u"),
2253 package("w", ""),
2254 package("other.b", "other"),
2255 ];
2256 let names: Vec<&str> = v2::packages_of_unit("u", &packages)
2257 .map(|p| p.name.as_str())
2258 .collect();
2259 assert_eq!(names, ["u", "u.a"]);
2260 let legacy: Vec<&str> = v2::packages_of_unit("w", &packages)
2261 .map(|p| p.name.as_str())
2262 .collect();
2263 assert_eq!(legacy, ["w"]);
2264 }
2265
2266 #[test]
2271 fn shape_visibility_reads_the_owning_service_for_an_inline_shape() {
2272 let package = fixture();
2273 let shapes: Vec<v2::InterfaceShape<'_>> = package.shapes().collect();
2274
2275 let named = shapes[0];
2276 assert!(named.service.is_none());
2277 assert_eq!(named.visibility(), v2::Visibility::Public as i32);
2278 assert_eq!(named.visibility(), named.interface.visibility);
2279
2280 let inline = shapes[1];
2281 assert_eq!(
2282 inline.interface.visibility,
2283 v2::Visibility::Unspecified as i32,
2284 "the trap: an inline shape's own visibility field is unset",
2285 );
2286 assert_eq!(
2287 inline.service.expect("an inline shape has an owner").name,
2288 "veh.adas.logs",
2289 );
2290 assert_eq!(
2291 inline.visibility(),
2292 v2::Visibility::Public as i32,
2293 "the accessor reads the owning service's, never the unset field",
2294 );
2295 }
2296
2297 #[test]
2301 fn shapes_is_empty_only_when_the_package_declares_no_shape() {
2302 let mut package = fixture();
2303 package.services.clear();
2304 assert_eq!(package.shapes().count(), 1);
2305
2306 package.interfaces.clear();
2307 assert_eq!(package.shapes().count(), 0);
2308 }
2309
2310 #[test]
2317 fn referenced_packages_finds_qualifiers_at_depth() {
2318 fn named(reference: &str) -> v2::FieldType {
2319 v2::FieldType {
2320 kind: Some(v2::field_type::Kind::Named(reference.to_string())),
2321 ..Default::default()
2322 }
2323 }
2324
2325 fn fixed(payload: v2::FieldType) -> v2::decl::Kind {
2326 v2::decl::Kind::FixedDef(v2::FixedDef {
2327 payload: Some(payload),
2328 })
2329 }
2330
2331 let package = v2::Package {
2332 name: "veh.cluster".to_string(),
2333 decls: vec![
2334 v2::Decl {
2335 name: "Local".to_string(),
2336 kind: Some(v2::decl::Kind::SignalDef(v2::SignalDef {
2337 payload: "Speed".to_string(),
2338 ..Default::default()
2339 })),
2340 ..Default::default()
2341 },
2342 v2::Decl {
2343 name: "Stamped".to_string(),
2344 kind: Some(v2::decl::Kind::SignalDef(v2::SignalDef {
2345 payload: "ridl.std.Timestamp".to_string(),
2346 ..Default::default()
2347 })),
2348 ..Default::default()
2349 },
2350 v2::Decl {
2351 name: "ArrLabels".to_string(),
2352 kind: Some(fixed(v2::FieldType {
2353 kind: Some(v2::field_type::Kind::Array(Box::new(v2::ArrayType {
2354 element: Some(Box::new(named("veh.arr.Label"))),
2355 min: 0,
2356 max: 32,
2357 }))),
2358 ..Default::default()
2359 })),
2360 ..Default::default()
2361 },
2362 v2::Decl {
2363 name: "TupThing".to_string(),
2364 kind: Some(fixed(v2::FieldType {
2365 kind: Some(v2::field_type::Kind::Tuple(v2::TupleType {
2366 fields: vec![v2::TupleField {
2367 name: "x".to_string(),
2368 r#type: Some(named("veh.tup.X")),
2369 }],
2370 })),
2371 ..Default::default()
2372 })),
2373 ..Default::default()
2374 },
2375 v2::Decl {
2376 name: "MapThing".to_string(),
2377 kind: Some(fixed(v2::FieldType {
2378 kind: Some(v2::field_type::Kind::Map(Box::new(v2::MapType {
2379 key: Some(Box::new(named("veh.key.X"))),
2380 value: Some(Box::new(named("veh.val.X"))),
2381 min: 0,
2382 max: 8,
2383 }))),
2384 ..Default::default()
2385 })),
2386 ..Default::default()
2387 },
2388 v2::Decl {
2389 name: "StreamThing".to_string(),
2390 kind: Some(fixed(v2::FieldType {
2391 kind: Some(v2::field_type::Kind::Stream(v2::StreamType {
2392 element: Some(v2::stream_type::Element::Named(
2393 "veh.strm.X".to_string(),
2394 )),
2395 })),
2396 ..Default::default()
2397 })),
2398 ..Default::default()
2399 },
2400 ],
2401 ..Default::default()
2402 };
2403
2404 let found = v2::referenced_packages(&package);
2405 let expected: std::collections::BTreeSet<String> = [
2406 "ridl.std", "veh.arr", "veh.tup", "veh.key", "veh.val", "veh.strm",
2407 ]
2408 .into_iter()
2409 .map(str::to_string)
2410 .collect();
2411 assert_eq!(
2412 found, expected,
2413 "each recursive path must contribute its own distinct qualifier"
2414 );
2415 assert!(
2416 !found.contains("Speed") && !found.contains("veh.cluster"),
2417 "a bare reference contributes no package: {found:?}",
2418 );
2419 }
2420
2421 #[test]
2424 fn referenced_packages_is_empty_without_references() {
2425 let package = v2::Package {
2426 name: "veh.solo".to_string(),
2427 ..Default::default()
2428 };
2429 assert!(v2::referenced_packages(&package).is_empty());
2430 }
2431
2432 const NESTING_BELOW_LIMIT: usize = 45;
2438 const NESTING_PAST_LIMIT: usize = 60;
2442
2443 fn nested_package(depth: usize) -> v2::Package {
2448 let mut payload = v2::FieldType {
2449 optional: false,
2450 kind: Some(v2::field_type::Kind::Primitive(
2451 v2::PrimitiveType::Integer as i32,
2452 )),
2453 };
2454 for _ in 0..depth {
2455 payload = v2::FieldType {
2456 optional: false,
2457 kind: Some(v2::field_type::Kind::Array(Box::new(v2::ArrayType {
2458 element: Some(Box::new(payload)),
2459 min: 1,
2460 max: 1,
2461 }))),
2462 };
2463 }
2464 v2::Package {
2465 name: "veh.deep".to_string(),
2466 decls: vec![v2::Decl {
2467 name: "deep".to_string(),
2468 kind: Some(v2::decl::Kind::FixedDef(v2::FixedDef {
2469 payload: Some(payload),
2470 })),
2471 ..Default::default()
2472 }],
2473 ..Default::default()
2474 }
2475 }
2476
2477 fn package_at_message_depth(levels: usize) -> v2::Package {
2489 assert!(levels >= 3, "the chain costs three levels before nesting");
2490 let (arrays, tuple) = if levels % 2 == 1 {
2491 ((levels - 3) / 2, false)
2492 } else {
2493 assert!(levels >= 6, "one tuple level costs three");
2494 ((levels - 6) / 2, true)
2495 };
2496
2497 let mut payload = v2::FieldType {
2498 optional: false,
2499 kind: Some(v2::field_type::Kind::Primitive(
2500 v2::PrimitiveType::Integer as i32,
2501 )),
2502 };
2503 for _ in 0..arrays {
2504 payload = v2::FieldType {
2505 optional: false,
2506 kind: Some(v2::field_type::Kind::Array(Box::new(v2::ArrayType {
2507 element: Some(Box::new(payload)),
2508 min: 1,
2509 max: 1,
2510 }))),
2511 };
2512 }
2513 if tuple {
2514 payload = v2::FieldType {
2515 optional: false,
2516 kind: Some(v2::field_type::Kind::Tuple(v2::TupleType {
2517 fields: vec![v2::TupleField {
2518 name: "f0".to_string(),
2519 r#type: Some(payload),
2520 }],
2521 })),
2522 };
2523 }
2524 v2::Package {
2525 name: "veh.deep".to_string(),
2526 decls: vec![v2::Decl {
2527 name: "deep".to_string(),
2528 kind: Some(v2::decl::Kind::FixedDef(v2::FixedDef {
2529 payload: Some(payload),
2530 })),
2531 ..Default::default()
2532 }],
2533 ..Default::default()
2534 }
2535 }
2536
2537 fn message_nesting(json: &str) -> usize {
2544 let (mut depth, mut max) = (0usize, 0usize);
2545 let (mut in_string, mut escaped) = (false, false);
2546 for byte in json.bytes() {
2547 if in_string {
2548 if escaped {
2549 escaped = false;
2550 } else if byte == b'\\' {
2551 escaped = true;
2552 } else if byte == b'"' {
2553 in_string = false;
2554 }
2555 continue;
2556 }
2557 match byte {
2558 b'"' => in_string = true,
2559 b'{' => {
2560 depth += 1;
2561 max = max.max(depth);
2562 }
2563 b'}' => depth = depth.saturating_sub(1),
2564 _ => {}
2565 }
2566 }
2567 max
2568 }
2569
2570 #[test]
2574 fn package_at_message_depth_builds_the_depth_it_names() {
2575 with_sized_stack(|| {
2576 for levels in [3, 6, 7, 99, 100, 101] {
2577 let json = v2::to_json_pretty(&package_at_message_depth(levels))
2578 .expect("the writer is unrestricted at these depths");
2579 assert_eq!(
2580 message_nesting(&json) - 1,
2581 levels,
2582 "the chain must nest {levels} message levels below the root"
2583 );
2584 }
2585 });
2586 }
2587
2588 #[test]
2597 fn binary_round_trip_at_100_message_levels_succeeds() {
2598 let package = package_at_message_depth(100);
2599 let bytes = v2::to_binary(&package);
2600 let decoded = v2::from_binary(&bytes).expect("100 message levels decode");
2601 assert_eq!(package, decoded);
2602 }
2603
2604 #[test]
2609 fn binary_decode_at_101_message_levels_returns_an_error() {
2610 let package = package_at_message_depth(101);
2611 let bytes = v2::to_binary(&package);
2612 let error = v2::from_binary(&bytes).expect_err("101 message levels must fail, not panic");
2613 assert!(
2614 error.to_string().contains("recursion limit reached"),
2615 "the error must name the limit, got: {error}"
2616 );
2617
2618 let json = v2::to_json_pretty(&package).expect("the canonical encoding has no such bound");
2619 assert_eq!(
2620 package,
2621 v2::from_json(&json).expect("the canonical encoding round-trips the same package")
2622 );
2623 }
2624
2625 #[test]
2634 fn json_round_trip_at_400_nested_levels_succeeds() {
2635 with_sized_stack(|| {
2636 let package = nested_package(400);
2637 let json = v2::to_json_pretty(&package).expect("the writer has no message-level limit");
2638 let decoded = v2::from_json(&json).expect("the reader parses within its ceiling");
2639 assert_eq!(package, decoded);
2640 });
2641 }
2642
2643 #[test]
2651 fn json_serialization_of_an_out_of_schema_discriminant_returns_an_error() {
2652 let mut package = fixture();
2653 package.decls[0].visibility = 999;
2654 let err = v2::to_json_pretty(&package)
2655 .expect_err("an out-of-schema discriminant must fail, not panic");
2656 let message = err.to_string();
2657 assert!(
2658 message.contains("canonical protobuf JSON"),
2659 "the error must name the encoding that failed, got: {message}"
2660 );
2661 assert!(
2662 message.contains("discriminant outside the schema"),
2663 "the error must name the known cause, got: {message}"
2664 );
2665 }
2666
2667 #[test]
2672 fn json_parse_rejects_an_unknown_field() {
2673 let error = v2::from_json(r#"{"name": "veh.deep", "notAField": 1}"#)
2674 .expect_err("an unknown field must be rejected");
2675 assert!(
2676 error.to_string().contains("unknown field"),
2677 "the error must name the defect, got: {error}"
2678 );
2679 }
2680
2681 #[test]
2690 fn json_parse_rejects_an_out_of_range_numeric_enum_value() {
2691 let with_visibility =
2692 |value: &str| format!(r#"{{"name": "veh.x", "decls": [{{"visibility": {value}}}]}}"#);
2693 v2::from_json(&with_visibility("1"))
2694 .expect("an in-range numeric enum value parses, as the mapping expects");
2695 let error = v2::from_json(&with_visibility("77"))
2696 .expect_err("an out-of-range numeric enum value must be rejected");
2697 assert!(
2698 error.to_string().contains("invalid value: integer `77`"),
2699 "the error must name the value, got: {error}"
2700 );
2701 }
2702
2703 #[test]
2709 fn json_parse_rejects_a_float_form_integer() {
2710 for spelling in ["1.0", "1e0"] {
2711 let error = v2::from_json(&format!(
2712 r#"{{"name": "veh.x", "decls": [{{"fixedDef": {{"payload": {{"array": {{"min": {spelling}}}}}}}}}]}}"#,
2713 ))
2714 .expect_err("a float-form integer must be rejected");
2715 assert!(
2716 error.to_string().contains("did not match any variant"),
2717 "the integer field's deserializer must be the one refusing `{spelling}`, \
2718 got: {error}"
2719 );
2720 }
2721 }
2722
2723 #[test]
2730 fn json_parse_rejects_null_for_a_repeated_field() {
2731 let error = v2::from_json(r#"{"name": "veh.x", "decls": null}"#)
2732 .expect_err("null for a repeated field must be rejected");
2733 assert!(
2734 error.to_string().contains("invalid type: null"),
2735 "the error must name the null, got: {error}"
2736 );
2737 v2::from_json(r#"{"name": "veh.x", "decls": [{"deprecated": null}]}"#)
2738 .expect("null for an optional scalar field still parses");
2739 }
2740
2741 #[test]
2745 fn json_parse_rejects_a_duplicate_key() {
2746 let error = v2::from_json(r#"{"name": "a", "name": "b"}"#)
2747 .expect_err("a duplicate key must be rejected");
2748 assert!(
2749 error.to_string().contains("duplicate field `name`"),
2750 "the error must name the duplicated field, got: {error}"
2751 );
2752 }
2753
2754 #[test]
2761 fn json_parse_past_the_nesting_ceiling_returns_an_error() {
2762 with_sized_stack(|| {
2763 let json = v2::to_json_pretty(&nested_package(500))
2764 .expect("the writer is unrestricted at this depth");
2765 let error = v2::from_json(&json).expect_err("the reader must refuse past its ceiling");
2766 assert!(
2767 error.to_string().contains("1000 JSON levels"),
2768 "the error must name the ceiling, got: {error}"
2769 );
2770 });
2771 }
2772
2773 #[test]
2778 fn json_nesting_ceiling_binds_exactly_at_1000() {
2779 let at = v2::from_json(&"[".repeat(1_000)).expect_err("an array is not a package");
2780 assert!(
2781 !at.to_string().contains("JSON levels"),
2782 "at the ceiling the parser, not the scan, must be the one refusing, got: {at}"
2783 );
2784
2785 let past = v2::from_json(&"[".repeat(1_001)).expect_err("past the ceiling, the scan");
2786 assert!(
2787 past.to_string().contains("1000 JSON levels"),
2788 "past the ceiling the error must name it, got: {past}"
2789 );
2790 }
2791
2792 #[test]
2797 fn nesting_scan_counts_brackets_outside_string_literals_only() {
2798 assert_eq!(v2::max_json_nesting(r#"{"a": [{"b": []}]}"#), 4);
2800 assert_eq!(v2::max_json_nesting(r#"{"doc": "{[[[{"}"#), 1);
2802 assert_eq!(v2::max_json_nesting(r#"{"doc": "a\"[[[", "x": []}"#), 2);
2805 assert_eq!(v2::max_json_nesting(r#"{"doc": "a\\", "x": [[]]}"#), 3);
2808 assert_eq!(v2::max_json_nesting("]]]{"), 1);
2810 }
2811
2812 fn nested_text(depth: usize) -> String {
2816 let mut payload = "primitive: PRIMITIVE_TYPE_INTEGER".to_string();
2817 for _ in 0..depth {
2818 payload = format!("array {{ element {{ {payload} }} min: 1 max: 1 }}");
2819 }
2820 format!(
2821 r#"name: "veh.deep" decls {{ name: "deep" fixed_def {{ payload {{ {payload} }} }} }}"#
2822 )
2823 }
2824
2825 #[test]
2829 fn text_serialization_past_the_nesting_limit_returns_an_error() {
2830 let err = v2::to_text_format(&nested_package(NESTING_PAST_LIMIT))
2831 .expect_err("serialization past the recursion limit must fail, not panic");
2832 let message = err.to_string();
2833 assert!(
2834 message.contains("recursion limit"),
2835 "the error must name the nesting limit as the known cause, got: {message}"
2836 );
2837 assert!(
2838 message.contains("prototext"),
2839 "the error must name the encoding that failed, got: {message}"
2840 );
2841 }
2842
2843 fn with_sized_stack(test: impl FnOnce() + Send + 'static) {
2856 let outcome = std::thread::Builder::new()
2857 .stack_size(16 * 1024 * 1024)
2858 .spawn(test)
2859 .expect("spawn the large-stack test thread")
2860 .join();
2861 if let Err(payload) = outcome {
2862 std::panic::resume_unwind(payload);
2863 }
2864 }
2865
2866 #[test]
2870 fn text_parse_past_the_nesting_limit_returns_an_error() {
2871 with_sized_stack(|| {
2872 let error = v2::from_text_format(&nested_text(NESTING_PAST_LIMIT))
2873 .expect_err("parsing past the recursion limit must fail, not panic");
2874
2875 let message = error.to_string();
2879 assert!(
2880 message.contains("recursion limit reached"),
2881 "the transcode out of the dynamic message must be the failing \
2882 stage, got: {message}"
2883 );
2884 });
2885 }
2886
2887 #[test]
2890 fn text_round_trip_below_the_nesting_limit_succeeds() {
2891 with_sized_stack(|| {
2892 let package = nested_package(NESTING_BELOW_LIMIT);
2893 let text = v2::to_text_format(&package)
2894 .expect("below the recursion limit, serialization succeeds");
2895 let decoded =
2896 v2::from_text_format(&text).expect("below the recursion limit, parsing succeeds");
2897 assert_eq!(package, decoded);
2898 });
2899 }
2900}
2901
2902#[cfg(test)]
2903mod vacuous_constraint {
2904 use crate::v2;
2905
2906 fn constraint() -> v2::Constraint {
2909 v2::Constraint {
2910 min: None,
2911 max: None,
2912 step: None,
2913 len_min: None,
2914 len_max: None,
2915 pattern: None,
2916 pattern_const: None,
2917 }
2918 }
2919
2920 #[test]
2921 fn an_absent_or_empty_constraint_is_vacuous() {
2922 assert!(v2::constraint_is_vacuous(None));
2923 assert!(v2::constraint_is_vacuous(Some(&constraint())));
2924 }
2925
2926 #[test]
2927 fn a_step_constraint_is_non_vacuous() {
2928 let stepped = v2::Constraint {
2929 step: Some("0.5".to_string()),
2930 ..constraint()
2931 };
2932 assert!(!v2::constraint_is_vacuous(Some(&stepped)));
2933 }
2934
2935 #[test]
2942 fn any_single_constrained_field_is_non_vacuous() {
2943 let cases = [
2944 (
2945 "min",
2946 v2::Constraint {
2947 min: Some("0.0".to_string()),
2948 ..constraint()
2949 },
2950 ),
2951 (
2952 "max",
2953 v2::Constraint {
2954 max: Some("250.0".to_string()),
2955 ..constraint()
2956 },
2957 ),
2958 (
2959 "len_min",
2960 v2::Constraint {
2961 len_min: Some(1),
2962 ..constraint()
2963 },
2964 ),
2965 (
2966 "len_max",
2967 v2::Constraint {
2968 len_max: Some(256),
2969 ..constraint()
2970 },
2971 ),
2972 (
2973 "pattern",
2974 v2::Constraint {
2975 pattern: Some("^[a-z]+$".to_string()),
2976 ..constraint()
2977 },
2978 ),
2979 (
2980 "pattern_const",
2981 v2::Constraint {
2982 pattern_const: Some("NAME_PATTERN".to_string()),
2983 ..constraint()
2984 },
2985 ),
2986 ];
2987 for (field, case) in cases {
2988 assert!(
2989 !v2::constraint_is_vacuous(Some(&case)),
2990 "`{field}` alone must be non-vacuous"
2991 );
2992 }
2993 }
2994
2995 #[test]
3004 fn a_bound_pair_set_together_is_non_vacuous() {
3005 let ranged = v2::Constraint {
3006 min: Some("0.0".to_string()),
3007 max: Some("250.0".to_string()),
3008 ..constraint()
3009 };
3010 assert!(!v2::constraint_is_vacuous(Some(&ranged)));
3011
3012 let default_length = v2::Constraint {
3013 len_min: Some(0),
3014 len_max: Some(256),
3015 ..constraint()
3016 };
3017 assert!(!v2::constraint_is_vacuous(Some(&default_length)));
3018 }
3019}
3020
3021#[cfg(test)]
3022mod system_round_trip {
3023 use crate::v2;
3024
3025 fn attribute(namespace: &str, key: &str, value: Option<v2::AttributeValue>) -> v2::Attribute {
3026 v2::Attribute {
3027 namespace: namespace.to_string(),
3028 key: key.to_string(),
3029 value,
3030 }
3031 }
3032
3033 fn scalar(text: &str) -> v2::AttributeValue {
3034 v2::AttributeValue {
3035 kind: Some(v2::attribute_value::Kind::Scalar(text.to_string())),
3036 }
3037 }
3038
3039 fn list(items: Vec<v2::AttributeValue>) -> v2::AttributeValue {
3040 v2::AttributeValue {
3041 kind: Some(v2::attribute_value::Kind::List(v2::AttributeList { items })),
3042 }
3043 }
3044
3045 fn interface(catalog: &str, name: &str, inline: bool) -> Option<v2::InterfaceRef> {
3046 Some(v2::InterfaceRef {
3047 catalog: catalog.to_string(),
3048 name: name.to_string(),
3049 inline,
3050 })
3051 }
3052
3053 fn endpoint(component: &str, instance: &str, machine: &str) -> v2::Endpoint {
3054 v2::Endpoint {
3055 component: component.to_string(),
3056 instance: instance.to_string(),
3057 machine: machine.to_string(),
3058 }
3059 }
3060
3061 fn doc_link() -> v2::DocLink {
3069 v2::DocLink {
3070 text: "Cruise".to_string(),
3071 offset: 16,
3072 len: 6,
3073 target: "veh.topology.Cruise".to_string(),
3074 }
3075 }
3076
3077 fn fixture() -> v2::System {
3078 let link = v2::Link {
3079 interface: interface("veh.diag", "veh.diag.access", true),
3080 service: "veh.diag.access".to_string(),
3081 consumer: Some(endpoint("veh.topology.Backend", "Unit", "Cloud")),
3082 producer: Some(endpoint("veh.diag.access", "Unit", "AdasHpc")),
3083 crossing: v2::Crossing::OffBoard as i32,
3084 };
3085 v2::System {
3086 name: "Vehicle".to_string(),
3087 package: "veh.topology".to_string(),
3088 labels: vec!["ASIL_B".to_string()],
3089 attributes: vec![attribute("rust", "crate", Some(scalar("\"vehicle\"")))],
3090 members: vec![
3091 v2::MemberLine {
3092 component: "veh.topology.Cruise".to_string(),
3093 attributes: vec![attribute("linux", "pinned", None)],
3094 doc: "Documented, see [Cruise].".to_string(),
3095 links: vec![doc_link()],
3096 see: vec![doc_link()],
3097 since: vec!["1.2".to_string()],
3098 },
3099 v2::MemberLine {
3100 component: "veh.diag.access".to_string(),
3101 attributes: vec![],
3102 doc: "Documented, see [Cruise].".to_string(),
3103 links: vec![doc_link()],
3104 see: vec![doc_link()],
3105 since: vec!["1.2".to_string()],
3106 },
3107 ],
3108 components: vec![
3109 v2::Component {
3110 name: "Cruise".to_string(),
3111 package: "veh.topology".to_string(),
3112 implicit: false,
3113 external: true,
3114 instances: vec!["primary".to_string(), "backup".to_string()],
3115 numbers: vec![
3116 v2::InstanceNumber {
3117 instance: "primary".to_string(),
3118 number: 1,
3119 provisional: false,
3120 },
3121 v2::InstanceNumber {
3122 instance: "backup".to_string(),
3123 number: 2,
3124 provisional: true,
3125 },
3126 ],
3127 offers: vec![v2::Offer {
3128 service: "veh.adas.cruise".to_string(),
3129 attributes: vec![attribute("someip", "serviceId", Some(scalar("4097")))],
3130 doc: "Documented, see [Cruise].".to_string(),
3131 links: vec![doc_link()],
3132 see: vec![doc_link()],
3133 since: vec!["1.2".to_string()],
3134 }],
3135 requires: vec![v2::Require {
3136 interface: interface("veh.adas", "LaneAssist", false),
3137 service: "veh.adas.lane".to_string(),
3138 producer: "veh.topology.Lane".to_string(),
3139 attributes: vec![attribute(
3140 "linux",
3141 "cpuset",
3142 Some(list(vec![scalar("2"), list(vec![scalar("3")])])),
3143 )],
3144 doc: "Documented, see [Cruise].".to_string(),
3145 links: vec![doc_link()],
3146 see: vec![doc_link()],
3147 since: vec!["1.2".to_string()],
3148 }],
3149 labels: vec!["ASIL_B".to_string()],
3150 attributes: vec![attribute("rust", "crate", None)],
3151 doc: "Documented, see [Cruise].".to_string(),
3152 links: vec![doc_link()],
3153 see: vec![doc_link()],
3154 since: vec!["1.2".to_string()],
3155 deprecated: Some("superseded".to_string()),
3156 },
3157 v2::Component {
3158 name: "veh.diag.access".to_string(),
3159 package: String::new(),
3160 implicit: true,
3161 external: false,
3162 instances: vec!["Unit".to_string()],
3163 numbers: vec![v2::InstanceNumber {
3164 instance: "Unit".to_string(),
3165 number: 3,
3166 provisional: false,
3167 }],
3168 offers: vec![v2::Offer {
3169 service: "veh.diag.access".to_string(),
3170 attributes: vec![],
3171 doc: "Documented, see [Cruise].".to_string(),
3172 links: vec![doc_link()],
3173 see: vec![doc_link()],
3174 since: vec!["1.2".to_string()],
3175 }],
3176 requires: vec![],
3177 labels: vec![],
3178 attributes: vec![],
3179 doc: "Documented, see [Cruise].".to_string(),
3180 links: vec![doc_link()],
3181 see: vec![doc_link()],
3182 since: vec!["1.2".to_string()],
3183 deprecated: Some("superseded".to_string()),
3184 },
3185 ],
3186 producers: vec![v2::Producer {
3187 service: "veh.adas.cruise".to_string(),
3188 component: "veh.topology.Cruise".to_string(),
3189 instances: vec!["primary".to_string(), "backup".to_string()],
3190 not_yet_realizable: true,
3191 }],
3192 grants: vec![v2::Grant {
3193 component: "veh.topology.Backend".to_string(),
3194 external: true,
3195 regions: vec!["veh.adas".to_string(), "veh.diag".to_string()],
3196 }],
3197 regions: vec![v2::Region {
3198 catalog: "veh.diag".to_string(),
3199 hash: vec![0xab; 32],
3200 interfaces: vec![v2::RegionInterface {
3201 name: "veh.diag.access".to_string(),
3202 inline: true,
3203 number: 2,
3204 provisional: true,
3205 service: "veh.diag.access".to_string(),
3206 }],
3207 }],
3208 distributions: vec![v2::Distribution {
3209 name: "Adas".to_string(),
3210 package: "veh.topology".to_string(),
3211 members: vec![v2::MemberLine {
3212 component: "veh.topology.Cruise".to_string(),
3213 attributes: vec![],
3214 doc: "Documented, see [Cruise].".to_string(),
3215 links: vec![doc_link()],
3216 see: vec![doc_link()],
3217 since: vec!["1.2".to_string()],
3218 }],
3219 depends_on: vec!["veh.topology.Base".to_string()],
3220 labels: vec!["PLATFORM_BUNDLE".to_string()],
3221 attributes: vec![attribute("deb", "section", Some(scalar("net")))],
3222 doc: "Documented, see [Cruise].".to_string(),
3223 links: vec![doc_link()],
3224 see: vec![doc_link()],
3225 since: vec!["1.2".to_string()],
3226 tier: v2::Tier::Platform as i32,
3227 deprecated: Some("superseded".to_string()),
3228 }],
3229 deployments: vec![v2::Deployment {
3230 name: "Production".to_string(),
3231 package: "veh.topology".to_string(),
3232 labels: vec!["FLEET".to_string()],
3233 attributes: vec![attribute("ota", "channel", Some(scalar("stable")))],
3234 machines: vec![v2::Machine {
3235 name: "Cloud".to_string(),
3236 external: true,
3237 labels: vec!["OFF_BOARD".to_string()],
3238 attributes: vec![attribute("net", "zone", Some(scalar("wan")))],
3239 doc: "Documented, see [Cruise].".to_string(),
3240 links: vec![doc_link()],
3241 see: vec![doc_link()],
3242 since: vec!["1.2".to_string()],
3243 deprecated: Some("superseded".to_string()),
3244 }],
3245 placements: vec![v2::Placement {
3246 component: "veh.topology.Cruise".to_string(),
3247 instance: "backup".to_string(),
3248 machine: "Cockpit".to_string(),
3249 attributes: vec![attribute("linux", "cpuset", Some(list(vec![])))],
3250 sizing: Some(v2::Sizing {
3251 depth: Some(4_294_967_295),
3252 slots: Some(65_536),
3253 budget: Some(18_446_744_073_709_551_615),
3254 }),
3255 }],
3256 links: vec![link.clone()],
3257 routes: vec![v2::Route {
3258 catalog: "veh.adas".to_string(),
3259 interface_number: 2,
3260 member_ordinal: 1,
3261 interface: "LaneAssist".to_string(),
3262 member: "active".to_string(),
3263 service: "veh.adas.lane".to_string(),
3264 producers: vec![endpoint("veh.topology.Lane", "Unit", "AdasHpc")],
3265 }],
3266 surface: vec![v2::Surface {
3267 link: Some(link),
3268 direction: v2::SurfaceDirection::ExternalConsumes as i32,
3269 }],
3270 installations: vec![v2::Installation {
3271 distribution: "veh.topology.Adas".to_string(),
3272 machines: vec!["AdasHpc".to_string(), "Cockpit".to_string()],
3273 }],
3274 doc: "Documented, see [Cruise].".to_string(),
3275 doc_links: vec![doc_link()],
3276 see: vec![doc_link()],
3277 since: vec!["1.2".to_string()],
3278 sizing: Some(v2::Sizing {
3279 depth: Some(3),
3280 slots: Some(8),
3281 budget: Some(4096),
3282 }),
3283 deprecated: Some("superseded".to_string()),
3284 file: Some("veh-production".to_string()),
3285 }],
3286 doc: "Documented, see [Cruise].".to_string(),
3287 see: vec![doc_link()],
3288 since: vec!["1.2".to_string()],
3289 links: vec![doc_link()],
3290 deprecated: Some("superseded".to_string()),
3291 }
3292 }
3293
3294 #[test]
3295 fn system_binary_round_trip_preserves_system() {
3296 let system = fixture();
3297 let decoded = v2::system_from_binary(v2::system_to_binary(&system).as_slice())
3298 .expect("decode must succeed");
3299 assert_eq!(system, decoded);
3300 }
3301
3302 #[test]
3307 fn system_json_round_trip_preserves_system() {
3308 let system = fixture();
3309 let json = v2::system_to_json_pretty(&system).expect("the fixture serializes as JSON");
3310 assert!(
3311 json.contains("\"hash\": \"q6urq6urq6urq6urq6urq6urq6urq6urq6urq6urq6s=\""),
3312 "bytes render as base64, got:\n{json}"
3313 );
3314 assert!(
3315 json.contains("\"crossing\": \"CROSSING_OFF_BOARD\""),
3316 "enums render by name, got:\n{json}"
3317 );
3318 assert!(
3319 json.contains("\"notYetRealizable\": true"),
3320 "fields render in lowerCamelCase, got:\n{json}"
3321 );
3322 assert!(
3323 json.contains("\"budget\": \"18446744073709551615\""),
3324 "a 64-bit value renders as a string, got:\n{json}"
3325 );
3326 assert_eq!(
3327 system,
3328 v2::system_from_json(&json).expect("the JSON parses")
3329 );
3330 assert!(
3331 v2::system_from_json(&json.replacen("\"name\"", "\"nam\"", 1)).is_err(),
3332 "an unknown field is rejected"
3333 );
3334 }
3335
3336 #[test]
3340 fn an_absent_sizing_and_an_empty_one_stay_distinct_through_the_encodings() {
3341 let mut absent = fixture();
3342 absent.deployments[0].sizing = None;
3343 absent.deployments[0].placements[0].sizing = None;
3344 let mut empty = absent.clone();
3345 empty.deployments[0].sizing = Some(v2::Sizing::default());
3346 empty.deployments[0].placements[0].sizing = Some(v2::Sizing::default());
3347 for system in [&absent, &empty] {
3348 let binary = v2::system_from_binary(v2::system_to_binary(system).as_slice())
3349 .expect("decode must succeed");
3350 assert_eq!(system, &binary);
3351 let json = v2::system_to_json_pretty(system).expect("serializes as JSON");
3352 assert_eq!(
3353 system,
3354 &v2::system_from_json(&json).expect("the JSON parses")
3355 );
3356 }
3357 assert_ne!(
3358 v2::system_to_binary(&absent),
3359 v2::system_to_binary(&empty),
3360 "the binary encodings differ"
3361 );
3362 }
3363
3364 #[test]
3365 fn system_text_format_round_trip_preserves_system() {
3366 let system = fixture();
3367 let text = v2::system_to_text_format(&system).expect("the fixture serializes as prototext");
3368 assert!(
3369 text.starts_with("name:"),
3370 "fields print in schema index order, got: {text}"
3371 );
3372 assert_eq!(
3373 system,
3374 v2::system_from_text_format(&text).expect("prototext parsing must succeed")
3375 );
3376 }
3377
3378 #[test]
3381 fn qualified_names_follow_the_one_derivation() {
3382 let system = fixture();
3383 assert_eq!(system.qualified_name(), "veh.topology.Vehicle");
3384 assert_eq!(system.components[0].qualified_name(), "veh.topology.Cruise");
3385 assert_eq!(system.components[1].qualified_name(), "veh.diag.access");
3386 assert_eq!(
3387 system.distributions[0].qualified_name(),
3388 "veh.topology.Adas"
3389 );
3390 }
3391}
3392
3393#[cfg(test)]
3394mod load_ir_json {
3395 use crate::v2::{self, LoadError, MAX_JSON_NESTING, load_ir_json};
3396
3397 #[test]
3399 fn a_snapshot_file_loads() {
3400 let dir = tempfile::tempdir().unwrap();
3401 let package = v2::Package {
3402 name: "veh.cabin".to_string(),
3403 ..v2::Package::default()
3404 };
3405 let path = dir.path().join("cabin.ir.json");
3406 std::fs::write(&path, v2::to_json_pretty(&package).unwrap()).unwrap();
3407 assert_eq!(load_ir_json(&path).unwrap(), package);
3408 }
3409
3410 #[test]
3414 fn a_missing_file_is_io_and_bad_json_is_parse() {
3415 let dir = tempfile::tempdir().unwrap();
3416
3417 let missing = dir.path().join("missing.ir.json");
3418 let io = std::fs::read_to_string(&missing).unwrap_err();
3419 let error = load_ir_json(&missing).unwrap_err();
3420 assert!(matches!(error, LoadError::Io(_)), "{error:?}");
3421 assert_eq!(
3422 error.to_string(),
3423 format!("cannot read the IR snapshot: {io}")
3424 );
3425
3426 let bad = dir.path().join("bad.ir.json");
3429 std::fs::write(&bad, "\n{").unwrap();
3430 let parse = v2::from_json("\n{").unwrap_err();
3431 let error = load_ir_json(&bad).unwrap_err();
3432 assert!(matches!(error, LoadError::Parse(_)), "{error:?}");
3433 assert_eq!(
3434 error.to_string(),
3435 format!("the IR snapshot is not valid IR v2 JSON: {parse}")
3436 );
3437 }
3438
3439 #[test]
3442 fn input_past_the_nesting_cap_draws_from_json_s_refusal() {
3443 let dir = tempfile::tempdir().unwrap();
3444 let deep = format!(
3445 "{}{}",
3446 "[".repeat(MAX_JSON_NESTING + 1),
3447 "]".repeat(MAX_JSON_NESTING + 1)
3448 );
3449 let path = dir.path().join("deep.ir.json");
3450 std::fs::write(&path, &deep).unwrap();
3451 let refusal = v2::from_json(&deep).unwrap_err().to_string();
3452 assert!(
3453 refusal.contains("the ceiling this reader enforces"),
3454 "{refusal}"
3455 );
3456 let error = load_ir_json(&path).unwrap_err();
3457 assert!(matches!(error, LoadError::Parse(_)), "{error:?}");
3458 assert_eq!(
3459 error.to_string(),
3460 format!("the IR snapshot is not valid IR v2 JSON: {refusal}")
3461 );
3462 }
3463}