puffin/
put.rs

1use std::hash::Hash;
2
3use serde::{Deserialize, Serialize};
4
5use crate::agent::{AgentDescriptor, AgentName};
6use crate::error::Error;
7use crate::protocol::{ProtocolBehavior, ProtocolTypes};
8use crate::stream::Stream;
9
10/// Put options to set when creating a put descriptor
11/// Set the key in the cli or tests and get it from the put descriptor wherever needed
12/// (ex:`use_clear` : use clear method instead of free on Agents in between traces of some Input)
13#[derive(Debug, Clone, Deserialize, Serialize, Eq, PartialEq, Hash)]
14pub struct PutOptions {
15    options: Vec<(String, String)>,
16}
17
18impl PutOptions {
19    #[must_use]
20    pub const fn new(options: Vec<(String, String)>) -> Self {
21        Self { options }
22    }
23
24    pub const fn empty() -> Self {
25        Self {
26            options: Vec::new(),
27        }
28    }
29}
30
31impl Default for PutOptions {
32    fn default() -> Self {
33        Self::empty()
34    }
35}
36
37impl PutOptions {
38    #[must_use]
39    pub fn get_option(&self, key: &str) -> Option<&str> {
40        self.options
41            .iter()
42            .find(|(found_key, _value)| -> bool { found_key == key })
43            .map(|(_key, value)| value.as_str())
44    }
45
46    pub fn add_option(&mut self, key: &str, value: &str) {
47        if self
48            .options
49            .iter()
50            .any(|(found_key, _value)| -> bool { found_key == key })
51        {
52            panic!("Option {} already exists", key);
53        }
54        self.options.push((key.into(), value.into()));
55    }
56
57    pub fn is_empty(&self) -> bool {
58        self.options.is_empty()
59    }
60
61    pub fn iter(&self) -> impl Iterator<Item = (&str, &str)> {
62        self.options
63            .iter()
64            .map(|(key, value)| (key.as_str(), value.as_str()))
65    }
66}
67
68impl<S> From<Vec<(S, S)>> for PutOptions
69where
70    S: Into<String>,
71{
72    fn from(value: Vec<(S, S)>) -> Self {
73        Self {
74            options: value
75                .into_iter()
76                .map(|(key, value)| (key.into(), value.into()))
77                .collect(),
78        }
79    }
80}
81
82#[derive(Debug, Clone, Deserialize, Serialize, Eq, PartialEq, Hash)]
83pub struct PutDescriptor {
84    pub factory: String,
85    pub options: PutOptions,
86}
87
88impl PutDescriptor {
89    pub fn new(factory: impl Into<String>, options: impl Into<PutOptions>) -> Self {
90        Self {
91            factory: factory.into(),
92            options: options.into(),
93        }
94    }
95}
96
97/// Generic trait used to define the interface with a concrete library
98/// implementing the protocol.
99pub trait Put<PB: ProtocolBehavior>: Stream<PB> + 'static {
100    /// Process incoming buffer, internal progress, can fill in the output buffer
101    fn progress(&mut self) -> Result<(), Error>;
102
103    /// In-place reset of the state
104    fn reset(&mut self, new_name: AgentName) -> Result<(), Error>;
105
106    fn descriptor(
107        &self,
108    ) -> &AgentDescriptor<<<PB as ProtocolBehavior>::ProtocolTypes as ProtocolTypes>::PUTConfig>;
109
110    /// Returns a textual representation of the state in which self is
111    fn describe_state(&self) -> String;
112
113    /// Checks whether the Put is in a good state
114    fn is_state_successful(&self) -> bool;
115
116    /// Shut down the PUT by consuming it and returning a string that summarizes the execution.
117    fn shutdown(&mut self) -> String;
118
119    /// Returns a textual representation of the version of the PUT used by self
120    fn version() -> String
121    where
122        Self: Sized;
123}