puffin/
protocol.rs

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    /// Compare an `EvaluatedTerm<PT>` with another `EvaluatedTerm<PT>` and add identified
34    /// difference to `diff`. If both types are different, it creates a
35    /// `KnowledgeDiff::DifferentTypes` differences if both types are the same, the objects are
36    /// compared recursively using `Compare` crate and their differences as registered as
37    /// `KnowledgeDiff::InnerDifference`
38    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                // For later
63                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
87/// Fill `knowledges` with new knowledge gathered form the type implementing EvaluatedTerm
88/// by recursively calling extract_knowledge on all contained element
89/// Knowledges can be extracted from using `extract_knowledge`
90pub trait Extractable<PT: ProtocolTypes>: std::fmt::Debug + AsAny
91where
92    Self: 'static,
93{
94    /// Fill `knowledges` with new knowledge gathered form the type implementing `EvaluatedTerm`
95    /// by recursively calling `extract_knowledge` on all contained element
96    /// This will put source as the source of all the produced knowledge, matcher is also passed
97    /// recursively but might be overwritten by a type with a more specific matcher
98    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
106/// Implement Extractable for all Vec of types implementing Extractable
107impl<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
131/// Implement Extractable for all Option of types implementing Extractable
132impl<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
156/// `EvaluatedTerm`: have both Codec and a way to extract knowledge out of a Message/OpaqueMessage
157/// or any type that might be used in a precomputation
158pub 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
183/// Store a message flight, a vec of all the messages sent by the PUT between two steps
184pub 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
196/// Store a flight of opaque messages, a vec of all the messages sent by the PUT between two steps
197// We require codec::Codec to be able to read a bitstring and produce an owned
198// `OpaqueProtocolMessageFlight<PT>` so we use the `Sized` version of `Codec`
199pub 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
207/// A structured message. This type defines how all possible messages of a protocol.
208/// Usually this is implemented using an `enum`.
209pub 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
216/// A non-structured version of [`ProtocolMessage`]. This can be used for example for encrypted
217/// messages which do not have a structure.
218pub trait OpaqueProtocolMessage<PT: ProtocolTypes>: Clone + Debug + EvaluatedTerm<PT> {
219    fn debug(&self, info: &str);
220}
221
222/// Deframes a stream of bytes into distinct [`OpaqueProtocolMessages`](OpaqueProtocolMessage).
223///
224/// A deframer is usually state-ful. This means it produces as many messages from the input bytes
225/// and stores them.
226pub 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
233/// Defines the types used to manipulate and concretize Terms
234pub trait ProtocolTypes:
235    'static + Clone + PartialEq + Eq + Hash + Display + Debug + Serialize + DeserializeOwned
236{
237    type Matcher: Matcher;
238    type PUTConfig: ProtocolDescriptorConfig;
239
240    /// Get the signature that is used in the protocol
241    fn signature() -> &'static Signature<Self>;
242
243    /// Allowed Knowlege's TypeIds when comparing knowledges stores
244    fn differential_fuzzing_whitelist() -> Option<Vec<TypeId>>;
245
246    /// Claims' TypeIds to blacklist when comparing knowledges stores
247    fn differential_fuzzing_claims_blacklist() -> Option<Vec<TypeId>>;
248
249    /// Terms to evaluate and compare during differential fuzzing
250    /// eg. decryption recipes
251    fn differential_fuzzing_terms_to_eval(
252        agents: &Vec<AgentDescriptor<Self::PUTConfig>>,
253    ) -> Vec<crate::algebra::Term<Self>>;
254
255    /// Replace trace's agent protocol config with a set of parameters
256    /// that should be supported by all PUTs
257    fn differential_fuzzing_uniformise_put_config(trace: Trace<Self>) -> Trace<Self>;
258
259    /// Check whether a difference should be kept
260    /// Use this to remove specific false positive without altering the capabilities of the
261    /// differential fuzzer
262    /// Return `true` to keep the difference
263    fn differential_fuzzing_filter_diff(diff: &TraceDifference) -> bool;
264}
265
266/// A function producing the seeds of one named corpus for a single PUT factory.
267///
268/// It returns the `(trace, name)` seeds that the given PUT supports (a PUT that
269/// lacks the capabilities a seed needs should simply omit it). Registered per
270/// protocol through [`ProtocolBehavior::corpus_registry`].
271pub type CorpusBuilder<PB> =
272    fn(&dyn Factory<PB>) -> Vec<(Trace<<PB as ProtocolBehavior>::ProtocolTypes>, &'static str)>;
273
274/// Name of the pseudo-corpus that expands to every corpus registered for the
275/// protocol (see [`build_corpus`]).
276pub const ALL_CORPORA: &str = "all";
277
278/// Build the seeds for the requested `corpus_list`, restricted to the
279/// intersection of what every PUT in `puts` supports.
280///
281/// Each named corpus is produced per PUT via its [`CorpusBuilder`]; a seed is
282/// kept only if it is present for *every* requested PUT (matched by name). When
283/// the same seed name appears in more than one requested corpus, the first
284/// occurrence (in `corpus_list` order) wins. Traces are PUT-independent, so the
285/// trace built for the first PUT is used. [`ALL_CORPORA`] (`"all"`) expands to
286/// every corpus registered via [`ProtocolBehavior::corpus_registry`], in
287/// registry order.
288pub 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
296/// First input step of `trace` whose recipe reaches `max_result_term_size` nodes, as
297/// `(step index, size)`.
298fn 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
315/// Core of [`build_corpus`], parameterized on the corpus `builders` so the
316/// selection/intersection/dedup logic can be unit-tested with synthetic
317/// corpuses independently of any concrete [`ProtocolBehavior::corpus_registry`].
318fn 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; // no PUTs selected
356        };
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                    // Warn that we are generating a seed that has a step that exceeds the max term
364                    // size
365                    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
377/// Defines the protocol which is being tested.
378///
379/// The fuzzer is generally abstract over the used protocol. We assume that protocols have
380/// [opaque messages](ProtocolBehavior::OpaqueProtocolMessage), [structured
381/// messages](ProtocolBehavior::ProtocolMessage), and a way to [deframe](ProtocolMessageDeframer) an
382/// arbitrary stream of bytes into messages.
383///
384/// Also the library allows the definition of a type for [claims](Claim) and a
385/// (security policy)[`SecurityViolationPolicy`] over
386/// sequences of them. Finally, there is a [matcher](Matcher) which allows traces to include
387/// queries for [knowledge](crate::trace::Knowledge).
388pub 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    /// Budgets the term zoo generates with, see [`crate::fuzzer::term_zoo`]. The defaults are the
404    /// values tuned for tlspuffin; what they depend on is a property of the protocol, so every
405    /// protocol is expected to revisit them.
406    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    /// Named corpus builders offered by this protocol.
411    ///
412    /// Each entry maps a corpus name (as accepted by the `seed --corpus` CLI
413    /// flag) to a [`CorpusBuilder`] producing that corpus' seeds for a single
414    /// PUT. Registering a new corpus is a matter of adding one line here. The
415    /// list is ordered; the default is no corpus at all.
416    fn corpus_registry() -> Vec<(&'static str, CorpusBuilder<Self>)> {
417        vec![]
418    }
419
420    /// Downcast from `Box<dyn Any>` and encode as bitstring any message as per the PB's internal
421    /// structure
422    fn any_get_encoding(message: &dyn EvaluatedTerm<Self::ProtocolTypes>) -> Vec<u8> {
423        /// Use the `codecP::get_encoding` method to encode any `EvaluatedTerm<PT>`
424        codec::CodecP::get_encoding(message)
425    }
426
427    /// Try to read a bitstring and interpret it as the `TypeShape`, which is the type of a message
428    /// as per the PB's internal structure This is expected to fail for many types of messages!
429    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// -- Macros --
455#[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    /// A minimal factory whose `supports()` answers come from a fixed capability
535    /// list, so tests can vary which seeds each PUT supports.
536    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    /// Corpus "alpha": always yields `common_seed`, plus `alpha_seed` when the
572    /// PUT supports the `cap_alpha` capability.
573    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    /// Corpus "beta": yields `common_seed` (same name as alpha) and `beta_seed`.
584    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            &reg,
632            &descriptors(&["put_with_alpha"]),
633            &["alpha".to_string(), "beta".to_string()],
634        );
635        // `common_seed` comes from alpha (listed first) and is not duplicated by beta.
636        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            &reg,
657            &descriptors(&["put_with_alpha", "put_without_alpha"]),
658            &["alpha".to_string()],
659        );
660        // `alpha_seed` is only supported by `put_with_alpha`, so the intersection drops it.
661        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            &reg,
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            &reg,
688            &descriptors(&["put_with_alpha"]),
689            &[ALL_CORPORA.to_string()],
690        );
691        // Same result as explicitly listing every registered corpus.
692        assert_eq!(
693            seed_names(&corpus),
694            vec!["common_seed", "alpha_seed", "beta_seed"]
695        );
696    }
697}