camel_api/
recipient_list.rs

1use crate::error::CamelError;
2use crate::filter::RecipientSource;
3
4/// Default cap on the number of recipients an expression may yield.
5/// A million-token expression like `"a,b,c,…"` is truncated to this size
6/// before any endpoint resolution. The cap is per-call; the operator may
7/// override per-component. The H13 audit finding was that the recipient
8/// list had no count cap; a malicious expression yielded millions of URIs
9/// and exhausted memory.
10pub const DEFAULT_MAX_RECIPIENTS: usize = 1_000;
11
12#[derive(Clone)]
13pub struct RecipientListConfig {
14    pub expression: RecipientSource,
15    pub delimiter: String,
16    pub parallel: bool,
17    pub parallel_limit: Option<usize>,
18    pub stop_on_exception: bool,
19    pub strategy: crate::MulticastStrategy,
20    /// Maximum number of URIs the expression may produce. A larger list
21    /// is truncated to `max_recipients` before endpoint resolution.
22    /// Defaults to `DEFAULT_MAX_RECIPIENTS` (1_000). The processor MUST
23    /// consult this cap, not the DSL author.
24    pub max_recipients: usize,
25}
26
27impl RecipientListConfig {
28    pub fn new(expression: impl Into<RecipientSource>) -> Self {
29        Self {
30            expression: expression.into(),
31            delimiter: ",".to_string(),
32            parallel: false,
33            parallel_limit: None,
34            stop_on_exception: false,
35            strategy: crate::MulticastStrategy::default(),
36            max_recipients: DEFAULT_MAX_RECIPIENTS,
37        }
38    }
39
40    pub fn delimiter(mut self, d: impl Into<String>) -> Self {
41        self.delimiter = d.into();
42        self
43    }
44
45    pub fn parallel(mut self, parallel: bool) -> Self {
46        self.parallel = parallel;
47        self
48    }
49
50    pub fn parallel_limit(mut self, limit: usize) -> Self {
51        self.parallel_limit = Some(limit);
52        self
53    }
54
55    pub fn stop_on_exception(mut self, stop: bool) -> Self {
56        self.stop_on_exception = stop;
57        self
58    }
59
60    pub fn strategy(mut self, strategy: crate::MulticastStrategy) -> Self {
61        self.strategy = strategy;
62        self
63    }
64
65    /// Override the per-call recipient count cap. Pass a value larger than
66    /// `DEFAULT_MAX_RECIPIENTS` only when the operator has a real reason;
67    /// the value is a hard ceiling, not a soft target.
68    pub fn max_recipients(mut self, cap: usize) -> Self {
69        self.max_recipients = cap;
70        self
71    }
72
73    /// Validates the configuration.
74    ///
75    /// Returns `Err(CamelError::Config)` if:
76    ///   - `parallel` is set with `parallel_limit == 0` (would deadlock / no progress)
77    ///   - `max_recipients == 0` (denies every call; reject at config time)
78    pub fn validate(&self) -> Result<(), CamelError> {
79        if self.parallel && self.parallel_limit == Some(0) {
80            return Err(CamelError::Config(
81                "recipient_list parallel_limit must be > 0".to_string(),
82            ));
83        }
84        if self.max_recipients == 0 {
85            return Err(CamelError::Config(
86                "recipient_list max_recipients must be > 0".to_string(),
87            ));
88        }
89        Ok(())
90    }
91}
92
93impl std::fmt::Debug for RecipientListConfig {
94    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
95        f.debug_struct("RecipientListConfig")
96            .field("delimiter", &self.delimiter)
97            .field("parallel", &self.parallel)
98            .field("parallel_limit", &self.parallel_limit)
99            .field("stop_on_exception", &self.stop_on_exception)
100            .field("max_recipients", &self.max_recipients)
101            .finish()
102    }
103}
104
105#[cfg(test)]
106mod tests {
107    use std::sync::Arc;
108
109    use super::*;
110
111    fn noop_expr() -> RecipientSource {
112        RecipientSource::Sync(Arc::new(|_| String::new()))
113    }
114
115    #[test]
116    fn new_has_defaults() {
117        let cfg = RecipientListConfig::new(noop_expr());
118        assert_eq!(cfg.delimiter, ",");
119        assert!(!cfg.parallel);
120        assert!(cfg.parallel_limit.is_none());
121        assert!(!cfg.stop_on_exception);
122    }
123
124    #[test]
125    fn builder_chaining() {
126        let cfg = RecipientListConfig::new(noop_expr())
127            .delimiter(";")
128            .parallel(true)
129            .parallel_limit(4)
130            .stop_on_exception(true)
131            .strategy(crate::MulticastStrategy::CollectAll);
132        assert_eq!(cfg.delimiter, ";");
133        assert!(cfg.parallel);
134        assert_eq!(cfg.parallel_limit, Some(4));
135        assert!(cfg.stop_on_exception);
136    }
137
138    #[test]
139    fn clone_preserves_values() {
140        let cfg = RecipientListConfig::new(noop_expr())
141            .delimiter("|")
142            .parallel(true);
143        let cloned = cfg.clone();
144        assert_eq!(cloned.delimiter, "|");
145        assert!(cloned.parallel);
146    }
147
148    #[test]
149    fn debug_format() {
150        let cfg = RecipientListConfig::new(noop_expr());
151        let debug = format!("{cfg:?}");
152        assert!(debug.contains("RecipientListConfig"));
153        assert!(debug.contains("delimiter"));
154    }
155
156    /// H13: `RecipientListConfig` carries a `max_recipients` field with a
157    /// sensible default. The default is 1_000 — a malicious expression
158    /// yielding millions of URIs must be capped before it materializes a
159    /// million endpoint resolutions.
160    #[test]
161    fn test_recipient_list_max_recipients_default() {
162        let cfg = RecipientListConfig::new(noop_expr());
163        assert_eq!(cfg.max_recipients, 1_000);
164    }
165
166    /// `validate` rejects a zero cap (would deny every call). The default
167    /// and any positive override pass; zero fails closed.
168    #[test]
169    fn test_recipient_list_validate_rejects_zero_cap() {
170        let cfg = RecipientListConfig::new(noop_expr()).max_recipients(0);
171        assert!(cfg.validate().is_err());
172    }
173}
camel_api/recipient_list.rs

camel_api/
recipient_list.rs
