1use std::any::{Any, TypeId};
2use std::fmt::{Debug, Display};
3use std::hash::Hash;
4
5use comparable::Comparable;
6use serde::de::DeserializeOwned;
7use serde::Serialize;
8
9use crate::agent::{AgentDescriptor, ProtocolDescriptorConfig};
10use crate::algebra::signature::Signature;
11use crate::algebra::{Matcher, TermType};
12use crate::claims::{Claim, SecurityViolationPolicy};
13use crate::codec;
14use crate::differential::TraceDifference;
15use crate::error::Error;
16use crate::fuzzer::term_zoo;
17use crate::fuzzer::utils::TermConstraints;
18use crate::put::PutDescriptor;
19use crate::put_registry::{Factory, PutRegistry};
20use crate::trace::{Action, Knowledge, Source, Trace};
21
22pub trait AsAny {
23 fn as_any(&self) -> &dyn Any;
24}
25
26impl<T: 'static> AsAny for T {
27 fn as_any(&self) -> &dyn Any {
28 self
29 }
30}
31
32pub trait CompareKnowledge<PT> {
33 fn find_differences(
39 &self,
40 other: &dyn EvaluatedTerm<PT>,
41 diffs: &mut Vec<TraceDifference>,
42 knowledge_num: usize,
43 self_source: &Source,
44 other_source: &Source,
45 );
46}
47
48impl<T, PT: ProtocolTypes> CompareKnowledge<PT> for T
49where
50 T: Clone + Debug + 'static + Comparable,
51{
52 fn find_differences(
53 &self,
54 other: &dyn EvaluatedTerm<PT>,
55 diffs: &mut Vec<TraceDifference>,
56 knowledge_num: usize,
57 self_source: &Source,
58 other_source: &Source,
59 ) {
60 match other.as_any().downcast_ref::<T>() {
61 Some(casted_other) => {
62 if let comparable::Changed::Changed(changes) = self.comparison(casted_other) {
64 diffs.push(TraceDifference::Knowledges(
65 crate::differential::KnowledgeDiff::InnerDifference {
66 index: knowledge_num,
67 type_name: other.type_name().into(),
68 diff: format!("{:?}", changes),
69 source: self_source.to_owned(),
70 },
71 ))
72 }
73 }
74 None => diffs.push(TraceDifference::Knowledges(
75 crate::differential::KnowledgeDiff::DifferentTypes {
76 index: knowledge_num,
77 first_type: std::any::type_name::<Self>().into(),
78 second_type: other.type_name().into(),
79 first_source: self_source.to_owned(),
80 second_source: other_source.to_owned(),
81 },
82 )),
83 };
84 }
85}
86
87pub trait Extractable<PT: ProtocolTypes>: std::fmt::Debug + AsAny
91where
92 Self: 'static,
93{
94 fn extract_knowledge<'a>(
99 &'a self,
100 knowledges: &mut Vec<Knowledge<'a, PT>>,
101 matcher: Option<PT::Matcher>,
102 source: &'a Source,
103 ) -> Result<(), Error>;
104}
105
106impl<PT: ProtocolTypes, T: EvaluatedTerm<PT> + Clone + codec::Codec + Comparable + 'static>
108 Extractable<PT> for Vec<T>
109where
110 Vec<T>: codec::Codec + Comparable,
111{
112 fn extract_knowledge<'a>(
113 &'a self,
114 knowledges: &mut Vec<Knowledge<'a, PT>>,
115 matcher: Option<<PT as ProtocolTypes>::Matcher>,
116 source: &'a Source,
117 ) -> Result<(), Error> {
118 knowledges.push(Knowledge {
119 source,
120 matcher: matcher.clone(),
121 data: self,
122 });
123
124 for k in self {
125 k.extract_knowledge(knowledges, matcher.clone(), source)?;
126 }
127 Ok(())
128 }
129}
130
131impl<PT: ProtocolTypes, T: Extractable<PT> + Clone + Comparable + 'static> Extractable<PT>
133 for Option<T>
134where
135 Option<T>: codec::Codec,
136{
137 fn extract_knowledge<'a>(
138 &'a self,
139 knowledges: &mut Vec<Knowledge<'a, PT>>,
140 matcher: Option<<PT as ProtocolTypes>::Matcher>,
141 source: &'a Source,
142 ) -> Result<(), Error> {
143 knowledges.push(Knowledge {
144 source,
145 matcher: matcher.clone(),
146 data: self,
147 });
148
149 if let Some(x) = self {
150 x.extract_knowledge(knowledges, matcher, source)?
151 }
152 Ok(())
153 }
154}
155
156pub trait EvaluatedTerm<PT: ProtocolTypes>:
159 codec::CodecP + Extractable<PT> + CompareKnowledge<PT> + Debug + AsAny + 'static
160where
161 Self: 'static,
162{
163 fn type_id(&self) -> TypeId {
164 Any::type_id(self)
165 }
166
167 fn type_name(&self) -> &'static str {
168 std::any::type_name::<Self>()
169 }
170
171 fn boxed(&self) -> Box<dyn EvaluatedTerm<PT>>;
172}
173
174impl<T, PT: ProtocolTypes> EvaluatedTerm<PT> for T
175where
176 T: codec::CodecP + Extractable<PT> + CompareKnowledge<PT> + 'static + Clone,
177{
178 fn boxed(&self) -> Box<dyn EvaluatedTerm<PT>> {
179 Box::new(self.clone())
180 }
181}
182
183pub trait ProtocolMessageFlight<
185 PT: ProtocolTypes,
186 M: ProtocolMessage<PT, O>,
187 O: OpaqueProtocolMessage<PT>,
188 OF: OpaqueProtocolMessageFlight<PT, O>,
189>: Clone + Debug + From<M> + TryFrom<OF> + Into<OF> + EvaluatedTerm<PT>
190{
191 fn new() -> Self;
192 fn push(&mut self, msg: M);
193 fn debug(&self, info: &str);
194}
195
196pub trait OpaqueProtocolMessageFlight<PT: ProtocolTypes, O: OpaqueProtocolMessage<PT>>:
200 Clone + Debug + codec::Codec + From<O> + EvaluatedTerm<PT>
201{
202 fn new() -> Self;
203 fn debug(&self, info: &str);
204 fn push(&mut self, msg: O);
205}
206
207pub trait ProtocolMessage<PT: ProtocolTypes, O: OpaqueProtocolMessage<PT>>:
210 Clone + Debug + EvaluatedTerm<PT>
211{
212 fn create_opaque(&self) -> O;
213 fn debug(&self, info: &str);
214}
215
216pub trait OpaqueProtocolMessage<PT: ProtocolTypes>: Clone + Debug + EvaluatedTerm<PT> {
219 fn debug(&self, info: &str);
220}
221
222pub trait ProtocolMessageDeframer<PT: ProtocolTypes> {
227 type OpaqueProtocolMessage: OpaqueProtocolMessage<PT>;
228
229 fn pop_frame(&mut self) -> Option<Self::OpaqueProtocolMessage>;
230 fn read(&mut self, rd: &mut dyn std::io::Read) -> std::io::Result<usize>;
231}
232
233pub trait ProtocolTypes:
235 'static + Clone + PartialEq + Eq + Hash + Display + Debug + Serialize + DeserializeOwned
236{
237 type Matcher: Matcher;
238 type PUTConfig: ProtocolDescriptorConfig;
239
240 fn signature() -> &'static Signature<Self>;
242
243 fn differential_fuzzing_whitelist() -> Option<Vec<TypeId>>;
245
246 fn differential_fuzzing_claims_blacklist() -> Option<Vec<TypeId>>;
248
249 fn differential_fuzzing_terms_to_eval(
252 agents: &Vec<AgentDescriptor<Self::PUTConfig>>,
253 ) -> Vec<crate::algebra::Term<Self>>;
254
255 fn differential_fuzzing_uniformise_put_config(trace: Trace<Self>) -> Trace<Self>;
258
259 fn differential_fuzzing_filter_diff(diff: &TraceDifference) -> bool;
264}
265
266pub type CorpusBuilder<PB> =
272 fn(&dyn Factory<PB>) -> Vec<(Trace<<PB as ProtocolBehavior>::ProtocolTypes>, &'static str)>;
273
274pub const ALL_CORPORA: &str = "all";
277
278pub fn build_corpus<PB: ProtocolBehavior>(
289 put_registry: &PutRegistry<PB>,
290 puts: &[PutDescriptor],
291 corpus_list: &[String],
292) -> Vec<(Trace<PB::ProtocolTypes>, &'static str)> {
293 build_corpus_with(&PB::corpus_registry(), put_registry, puts, corpus_list)
294}
295
296fn oversized_step<PT: ProtocolTypes>(
299 trace: &Trace<PT>,
300 max_result_term_size: usize,
301) -> Option<(usize, usize)> {
302 trace
303 .steps
304 .iter()
305 .enumerate()
306 .find_map(|(i, step)| match &step.action {
307 Action::Input(input) => {
308 let size = input.recipe.size();
309 (size >= max_result_term_size).then_some((i, size))
310 }
311 Action::Output(_) => None,
312 })
313}
314
315fn build_corpus_with<PB: ProtocolBehavior>(
319 builders: &[(&'static str, CorpusBuilder<PB>)],
320 put_registry: &PutRegistry<PB>,
321 puts: &[PutDescriptor],
322 corpus_list: &[String],
323) -> Vec<(Trace<PB::ProtocolTypes>, &'static str)> {
324 let factories: Vec<&dyn Factory<PB>> = puts
325 .iter()
326 .map(|put| {
327 put_registry
328 .find_by_id(&put.factory)
329 .unwrap_or_else(|| panic!("PUT {} not found in registry", put.factory))
330 })
331 .collect();
332
333 let expanded_corpus_list: Vec<&str> = corpus_list
334 .iter()
335 .flat_map(|name| {
336 if name == ALL_CORPORA {
337 builders.iter().map(|(n, _)| *n).collect::<Vec<_>>()
338 } else {
339 vec![name.as_str()]
340 }
341 })
342 .collect();
343
344 let max_result_term_size = TermConstraints::default().max_result_term_size;
345 let mut seen = std::collections::HashSet::new();
346 let mut corpus = Vec::new();
347 for name in expanded_corpus_list {
348 let Some(builder) = builders.iter().find(|(n, _)| *n == name).map(|(_, b)| *b) else {
349 log::warn!("unknown corpus '{name}', skipping");
350 continue;
351 };
352
353 let per_put: Vec<_> = factories.iter().map(|factory| builder(*factory)).collect();
354 let Some((first, rest)) = per_put.split_first() else {
355 continue; };
357 for (trace, seed_name) in first {
358 let supported_by_all = rest
359 .iter()
360 .all(|seeds| seeds.iter().any(|(_, n)| n == seed_name));
361 if supported_by_all && seen.insert(*seed_name) {
362 if let Some((step, size)) = oversized_step(trace, max_result_term_size) {
363 log::warn!(
366 "seed '{seed_name}' is above the max term size: step {step} has {size} \
367 nodes (max_result_term_size = {max_result_term_size})"
368 );
369 }
370 corpus.push((trace.clone(), *seed_name));
371 }
372 }
373 }
374 corpus
375}
376
377pub trait ProtocolBehavior: 'static {
389 type ProtocolTypes: ProtocolTypes;
390 type Claim: Claim<PT = Self::ProtocolTypes>;
391 type SecurityViolationPolicy: SecurityViolationPolicy<C = Self::Claim>;
392 type ProtocolMessage: ProtocolMessage<Self::ProtocolTypes, Self::OpaqueProtocolMessage>;
393 type OpaqueProtocolMessage: OpaqueProtocolMessage<Self::ProtocolTypes>;
394 type ProtocolMessageFlight: ProtocolMessageFlight<
395 Self::ProtocolTypes,
396 Self::ProtocolMessage,
397 Self::OpaqueProtocolMessage,
398 Self::OpaqueProtocolMessageFlight,
399 >;
400 type OpaqueProtocolMessageFlight: OpaqueProtocolMessageFlight<Self::ProtocolTypes, Self::OpaqueProtocolMessage>
401 + From<Self::ProtocolMessageFlight>;
402
403 const ZOO_MAX_DEPTH: u16 = term_zoo::DEFAULT_MAX_DEPTH;
407 const ZOO_MAX_SIZE: usize = term_zoo::DEFAULT_MAX_SIZE;
408 const ZOO_MAX_TRIES: usize = term_zoo::DEFAULT_MAX_TRIES;
409
410 fn corpus_registry() -> Vec<(&'static str, CorpusBuilder<Self>)> {
417 vec![]
418 }
419
420 fn any_get_encoding(message: &dyn EvaluatedTerm<Self::ProtocolTypes>) -> Vec<u8> {
423 codec::CodecP::get_encoding(message)
425 }
426
427 fn try_read_bytes(
430 bitstring: &[u8],
431 ty: TypeId,
432 ) -> Result<Box<dyn EvaluatedTerm<Self::ProtocolTypes>>, Error>;
433}
434
435impl<T: ProtocolTypes> Extractable<T> for () {
436 fn extract_knowledge<'a>(
437 &'a self,
438 _knowledges: &mut Vec<Knowledge<'a, T>>,
439 _matcher: Option<<T as ProtocolTypes>::Matcher>,
440 _source: &'a Source,
441 ) -> Result<(), Error> {
442 Ok(())
443 }
444}
445
446impl codec::CodecP for () {
447 fn encode(&self, _bytes: &mut Vec<u8>) {}
448
449 fn read(&mut self, _r: &mut codec::Reader) -> Result<(), Error> {
450 Ok(())
451 }
452}
453
454#[macro_export]
456macro_rules! dummy_extract_knowledge {
457 ($protocol_type:ty, $extract_type:ty) => {
458 impl Extractable<$protocol_type> for $extract_type {
459 fn extract_knowledge<'a>(
460 &'a self,
461 _knowledges: &mut Vec<Knowledge<'a, $protocol_type>>,
462 _matcher: Option<<$protocol_type as ProtocolTypes>::Matcher>,
463 _source: &'a Source,
464 ) -> Result<(), Error> {
465 log::warn!(
466 "Trying to extract a dummy type: {}",
467 stringify!($extract_type)
468 );
469 Ok(())
470 }
471 }
472 };
473}
474
475#[macro_export]
476macro_rules! dummy_codec {
477 ($protocol_type:ty, $extract_type:ty) => {
478 impl codec::CodecP for $extract_type {
479 fn encode(&self, _bytes: &mut Vec<u8>) {
480 log::warn!(
481 "Trying to encode a dummy type: {}",
482 stringify!($extract_type)
483 );
484 }
485
486 fn read(&mut self, _r: &mut codec::Reader) -> Result<(), Error> {
487 log::warn!("Trying to read a dummy type: {}", stringify!($extract_type));
488 Ok(())
489 }
490 }
491 };
492}
493
494#[macro_export]
495macro_rules! dummy_extract_knowledge_codec {
496 ($protocol_type:ty, $extract_type:ty) => {
497 dummy_extract_knowledge!($protocol_type, $extract_type);
498 dummy_codec!($protocol_type, $extract_type);
499 };
500}
501
502#[macro_export]
503macro_rules! atom_extract_knowledge {
504 ($protocol_type:ty, $extract_type:ty) => {
505 impl Extractable<$protocol_type> for $extract_type {
506 fn extract_knowledge<'a>(
507 &'a self,
508 knowledges: &mut Vec<Knowledge<'a, $protocol_type>>,
509 matcher: Option<<$protocol_type as ProtocolTypes>::Matcher>,
510 source: &'a Source,
511 ) -> Result<(), Error> {
512 log::trace!("Extract atom: {}", stringify!($extract_type));
513 knowledges.push(Knowledge {
514 source,
515 matcher,
516 data: self,
517 });
518 Ok(())
519 }
520 }
521 };
522}
523
524#[cfg(test)]
525mod tests {
526 use super::*;
527 use crate::agent::AgentDescriptor;
528 use crate::algebra::test_signature::{TestProtocolBehavior, TestProtocolTypes};
529 use crate::claims::GlobalClaimList;
530 use crate::error::Error;
531 use crate::put::{Put, PutOptions};
532 use crate::put_registry::Factory;
533
534 struct CapFactory {
537 name: String,
538 capabilities: Vec<&'static str>,
539 }
540
541 impl Factory<TestProtocolBehavior> for CapFactory {
542 fn create(
543 &self,
544 _agent_descriptor: &AgentDescriptor<<TestProtocolTypes as ProtocolTypes>::PUTConfig>,
545 _claims: &GlobalClaimList<<TestProtocolBehavior as ProtocolBehavior>::Claim>,
546 _options: &PutOptions,
547 ) -> Result<Box<dyn Put<TestProtocolBehavior>>, Error> {
548 panic!("CapFactory cannot create a PUT")
549 }
550
551 fn name(&self) -> String {
552 self.name.clone()
553 }
554
555 fn versions(&self) -> Vec<(String, String)> {
556 vec![]
557 }
558
559 fn supports(&self, capability: &str) -> bool {
560 self.capabilities.iter().any(|c| *c == capability)
561 }
562
563 fn clone_factory(&self) -> Box<dyn Factory<TestProtocolBehavior>> {
564 Box::new(CapFactory {
565 name: self.name.clone(),
566 capabilities: self.capabilities.clone(),
567 })
568 }
569 }
570
571 fn corpus_alpha(
574 put: &dyn Factory<TestProtocolBehavior>,
575 ) -> Vec<(Trace<TestProtocolTypes>, &'static str)> {
576 let mut seeds = vec![(Trace::default(), "common_seed")];
577 if put.supports("cap_alpha") {
578 seeds.push((Trace::default(), "alpha_seed"));
579 }
580 seeds
581 }
582
583 fn corpus_beta(
585 _put: &dyn Factory<TestProtocolBehavior>,
586 ) -> Vec<(Trace<TestProtocolTypes>, &'static str)> {
587 vec![
588 (Trace::default(), "common_seed"),
589 (Trace::default(), "beta_seed"),
590 ]
591 }
592
593 const BUILDERS: &[(&str, CorpusBuilder<TestProtocolBehavior>)] = &[
594 ("alpha", corpus_alpha as CorpusBuilder<TestProtocolBehavior>),
595 ("beta", corpus_beta as CorpusBuilder<TestProtocolBehavior>),
596 ];
597
598 fn registry(factories: Vec<CapFactory>) -> PutRegistry<TestProtocolBehavior> {
599 let default = factories[0].name.clone();
600 let puts: Vec<(String, Box<dyn Factory<TestProtocolBehavior>>)> = factories
601 .into_iter()
602 .map(|f| {
603 (
604 f.name.clone(),
605 Box::new(f) as Box<dyn Factory<TestProtocolBehavior>>,
606 )
607 })
608 .collect();
609 PutRegistry::new(puts, PutDescriptor::new(default, PutOptions::default()))
610 }
611
612 fn descriptors(names: &[&str]) -> Vec<PutDescriptor> {
613 names
614 .iter()
615 .map(|n| PutDescriptor::new(*n, PutOptions::default()))
616 .collect()
617 }
618
619 fn seed_names(corpus: &[(Trace<TestProtocolTypes>, &'static str)]) -> Vec<&'static str> {
620 corpus.iter().map(|(_, name)| *name).collect()
621 }
622
623 #[test]
624 fn build_corpus_unions_and_dedups_first_wins() {
625 let reg = registry(vec![CapFactory {
626 name: "put_with_alpha".into(),
627 capabilities: vec!["cap_alpha"],
628 }]);
629 let corpus = build_corpus_with(
630 BUILDERS,
631 ®,
632 &descriptors(&["put_with_alpha"]),
633 &["alpha".to_string(), "beta".to_string()],
634 );
635 assert_eq!(
637 seed_names(&corpus),
638 vec!["common_seed", "alpha_seed", "beta_seed"]
639 );
640 }
641
642 #[test]
643 fn build_corpus_intersects_across_puts() {
644 let reg = registry(vec![
645 CapFactory {
646 name: "put_with_alpha".into(),
647 capabilities: vec!["cap_alpha"],
648 },
649 CapFactory {
650 name: "put_without_alpha".into(),
651 capabilities: vec![],
652 },
653 ]);
654 let corpus = build_corpus_with(
655 BUILDERS,
656 ®,
657 &descriptors(&["put_with_alpha", "put_without_alpha"]),
658 &["alpha".to_string()],
659 );
660 assert_eq!(seed_names(&corpus), vec!["common_seed"]);
662 }
663
664 #[test]
665 fn build_corpus_skips_unknown_corpus() {
666 let reg = registry(vec![CapFactory {
667 name: "put".into(),
668 capabilities: vec![],
669 }]);
670 let corpus = build_corpus_with(
671 BUILDERS,
672 ®,
673 &descriptors(&["put"]),
674 &["does_not_exist".to_string()],
675 );
676 assert!(corpus.is_empty());
677 }
678
679 #[test]
680 fn build_corpus_all_expands_to_every_registered_corpus() {
681 let reg = registry(vec![CapFactory {
682 name: "put_with_alpha".into(),
683 capabilities: vec!["cap_alpha"],
684 }]);
685 let corpus = build_corpus_with(
686 BUILDERS,
687 ®,
688 &descriptors(&["put_with_alpha"]),
689 &[ALL_CORPORA.to_string()],
690 );
691 assert_eq!(
693 seed_names(&corpus),
694 vec!["common_seed", "alpha_seed", "beta_seed"]
695 );
696 }
697}