puffin/
agent.rs

1//! [`Agent`]s represent communication participants like Alice, Bob or Eve.
2//!
3//! Note that attackers are usually not represented by these [`Agent`]s but instead through a recipe
4//! term (see [`crate::trace::InputAction`]).
5//!
6//! Each [`Agent`] has an *inbound* and an *outbound* channel (see [`crate::stream`])
7
8use core::fmt;
9use std::fmt::Debug;
10use std::hash::Hash;
11
12use comparable::Comparable;
13use serde::{Deserialize, Serialize};
14
15use crate::algebra::ConcreteMessage;
16use crate::error::Error;
17use crate::protocol::{ProtocolBehavior, ProtocolTypes};
18use crate::put::Put;
19use crate::stream::Stream;
20
21/// Copyable reference to an [`Agent`]. It identifies exactly one agent.
22#[derive(
23    Serialize, Deserialize, Copy, Clone, Debug, Eq, PartialEq, Hash, Comparable, Ord, PartialOrd,
24)]
25pub struct AgentName(u8);
26
27impl AgentName {
28    #[must_use]
29    pub const fn new() -> Self {
30        const FIRST: AgentName = AgentName(0u8);
31        FIRST
32    }
33
34    #[must_use]
35    pub const fn next(&self) -> Self {
36        Self(self.0 + 1)
37    }
38
39    #[must_use]
40    pub const fn first() -> Self {
41        Self::new()
42    }
43}
44
45impl Default for AgentName {
46    fn default() -> Self {
47        Self::new()
48    }
49}
50
51impl fmt::Display for AgentName {
52    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
53        write!(f, "{}", self.0)
54    }
55}
56
57impl From<AgentName> for u8 {
58    fn from(value: AgentName) -> Self {
59        value.0
60    }
61}
62
63/// Contains the protocol specific configuration of an agent
64pub trait ProtocolDescriptorConfig:
65    Default + Debug + Clone + Serialize + Hash + for<'a> Deserialize<'a>
66{
67    /// Indicates wheter a agent is reusable, ie. it's configuration is compatible with the new
68    /// agent to spawn
69    fn is_reusable_with(&self, other: &Self) -> bool;
70}
71
72/// [`AgentDescriptor`]s act like a blueprint to spawn [`Agent`]s with a corresponding server or
73/// client role and a specific TLs version. Essentially they are an [`Agent`] without a stream.
74///
75/// The difference between an [`AgentDescriptor`] and a [`crate::put::PutDescriptor`] is that
76/// values of the [`AgentDescriptor`] are required for seed traces to succeed. They are the same for
77/// every invocation of the seed. Values in the [`crate::put::PutDescriptor`] are supposed to
78/// differ between invocations.
79#[derive(Debug, Clone, Deserialize, Serialize, Eq, PartialEq, Hash)]
80#[serde(bound = "C: ProtocolDescriptorConfig")]
81pub struct AgentDescriptor<C: ProtocolDescriptorConfig> {
82    pub name: AgentName,
83
84    /// Contains the protocol specific configuration of the Agent
85    pub protocol_config: C,
86}
87
88impl<C: ProtocolDescriptorConfig> AgentDescriptor<C> {
89    pub fn from_config(name: AgentName, put_config: C) -> Self {
90        Self {
91            name,
92            protocol_config: put_config,
93        }
94    }
95
96    pub fn from_name(name: AgentName) -> Self {
97        Self {
98            name,
99            protocol_config: C::default(),
100        }
101    }
102}
103
104impl<C: ProtocolDescriptorConfig> Default for AgentDescriptor<C> {
105    fn default() -> Self {
106        Self {
107            name: AgentName::first(),
108            protocol_config: C::default(),
109        }
110    }
111}
112
113/// An [`Agent`] holds a non-cloneable reference to a Stream.
114pub struct Agent<PB: ProtocolBehavior> {
115    descriptor:
116        AgentDescriptor<<<PB as ProtocolBehavior>::ProtocolTypes as ProtocolTypes>::PUTConfig>,
117    put: Box<dyn Put<PB>>,
118}
119
120impl<PB: ProtocolBehavior> fmt::Debug for Agent<PB> {
121    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
122        f.debug_struct("Agent")
123            .field("descriptor", &self.descriptor)
124            .field("put", &self.put.describe_state())
125            .finish()
126    }
127}
128
129impl<PB: ProtocolBehavior> PartialEq for Agent<PB> {
130    fn eq(&self, other: &Self) -> bool {
131        self.descriptor.name.eq(&other.descriptor.name)
132            && self.put.describe_state() == other.put.describe_state()
133    }
134}
135
136impl<PB: ProtocolBehavior> Agent<PB> {
137    #[must_use]
138    pub fn new(
139        descriptor: AgentDescriptor<<PB::ProtocolTypes as ProtocolTypes>::PUTConfig>,
140        put: Box<dyn Put<PB>>,
141    ) -> Self {
142        Self { descriptor, put }
143    }
144
145    pub fn progress(&mut self) -> Result<(), Error> {
146        self.put.progress()
147    }
148
149    pub fn reset(&mut self, new_name: AgentName) -> Result<(), Error> {
150        self.descriptor.name = new_name;
151        self.put.reset(new_name)
152    }
153
154    /// Shut down the agent by consuming it and returning a string that summarizes the execution.
155    pub fn shutdown(&mut self) -> String {
156        self.put.shutdown()
157    }
158
159    /// Checks whether the agent is in a good state.
160    #[must_use]
161    pub fn is_state_successful(&self) -> bool {
162        self.put.is_state_successful()
163    }
164
165    /// Checks whether the agent is reusable with the descriptor.
166    #[must_use]
167    pub fn is_reusable_with(
168        &self,
169        other: &AgentDescriptor<<PB::ProtocolTypes as ProtocolTypes>::PUTConfig>,
170    ) -> bool {
171        self.descriptor
172            .protocol_config
173            .is_reusable_with(&other.protocol_config)
174    }
175
176    #[must_use]
177    pub const fn name(&self) -> AgentName {
178        self.descriptor.name
179    }
180
181    #[must_use]
182    pub fn put(&self) -> &dyn Put<PB> {
183        self.put.as_ref()
184    }
185
186    pub fn put_mut(&mut self) -> &mut dyn Put<PB> {
187        self.put.as_mut()
188    }
189}
190
191impl<PB: ProtocolBehavior> Stream<PB> for Agent<PB> {
192    fn add_to_inbound(&mut self, message: &ConcreteMessage) {
193        self.put.add_to_inbound(message);
194    }
195
196    fn take_message_from_outbound(
197        &mut self,
198        output_flight: &mut Option<PB::OpaqueProtocolMessageFlight>,
199    ) -> Result<(), Error> {
200        self.put.take_message_from_outbound(output_flight)
201    }
202}