1use std::fmt;
5use std::path::PathBuf;
6use std::str::FromStr;
7use std::time::Duration;
8
9#[derive(Debug, Clone, PartialEq, Eq)]
16pub enum ChildSpec {
17 Stdio { name: String, argv: Vec<String> },
19 Ws { name: String, url: String },
21}
22
23impl ChildSpec {
24 pub fn name(&self) -> &str {
26 match self {
27 Self::Stdio { name, .. } | Self::Ws { name, .. } => name,
28 }
29 }
30}
31
32impl fmt::Display for ChildSpec {
33 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
34 match self {
35 Self::Stdio { name, argv } => write!(f, "{name}=stdio:{}", shell_words::join(argv)),
36 Self::Ws { name, url } => write!(f, "{name}={url}"),
37 }
38 }
39}
40
41fn spec_err(s: &str, why: impl fmt::Display) -> ChildError {
42 ChildError::Spec(format!("`{s}`: {why}"))
43}
44
45impl FromStr for ChildSpec {
46 type Err = ChildError;
47
48 fn from_str(s: &str) -> Result<Self, ChildError> {
49 let (name, rest) = s.split_once('=').ok_or_else(|| spec_err(s, "no `=`: a child is NAME=stdio:CMD or NAME=ws://HOST:PORT"))?;
50 let name = name.trim();
51 if name.is_empty() {
52 return Err(spec_err(s, "an empty mount name"));
53 }
54 if name.contains('.') {
55 return Err(spec_err(s, format!("the mount name `{name}` is dotted: it is one segment (a method's path is `{name}.<method>`)")));
56 }
57 if let Some(bad) = name.chars().find(|c| !(c.is_ascii_alphanumeric() || *c == '_' || *c == '-')) {
58 return Err(spec_err(s, format!("the mount name `{name}` holds `{bad}`: only letters, digits, `_` and `-`")));
59 }
60 let name = name.to_string();
61 if let Some(cmd) = rest.strip_prefix("stdio:") {
62 let mut argv = shell_words::split(cmd).map_err(|e| spec_err(s, format!("its command does not split: {e}")))?;
63 if argv.len() == 1 && argv[0].contains(char::is_whitespace) {
66 argv = shell_words::split(&argv[0]).map_err(|e| spec_err(s, format!("its command does not split: {e}")))?;
67 }
68 if argv.is_empty() {
69 return Err(spec_err(s, "no command after `stdio:`"));
70 }
71 return Ok(Self::Stdio { name, argv });
72 }
73 if rest.starts_with("ws://") || rest.starts_with("wss://") {
74 let host = rest.split_once("://").map(|(_, h)| h).unwrap_or("");
75 let host = host.split(['/', '?', '#']).next().unwrap_or("");
76 if host.is_empty() || host.starts_with(':') {
77 return Err(spec_err(s, "a WebSocket child names its host: ws://HOST:PORT"));
78 }
79 return Ok(Self::Ws { name, url: rest.to_string() });
80 }
81 let scheme = rest.split_once(':').map(|(a, _)| a).unwrap_or(rest);
82 Err(spec_err(s, format!("unknown scheme `{scheme}`: a child is reached by `stdio:CMD`, `ws://…` or `wss://…`")))
83 }
84}
85
86pub const INSECURE_TRANSPORT: &str = "insecure_transport";
89
90pub fn check_ws_url(url: &str, insecure_ws: bool) -> Result<(), String> {
97 let rest = if let Some(r) = url.strip_prefix("wss://") {
98 return match url_host(r) {
99 Some(_) => Ok(()),
100 None => Err(format!("`{url}` names no host")),
101 };
102 } else if let Some(r) = url.strip_prefix("ws://") {
103 r
104 } else {
105 return Err(format!("`{url}`: a peer is reached by ws:// or wss://"));
106 };
107 let Some(host) = url_host(rest) else { return Err(format!("`{url}` names no host")) };
108 if is_loopback_host(&host) || insecure_ws {
109 return Ok(());
110 }
111 Err(format!(
112 "`{url}`: plain ws:// only to loopback (127.0.0.0/8, ::1, localhost); a peer beyond it is reached by wss://, its hop (who calls, under what ceiling) never in clear (`transport.insecure_ws` allows it, a test network's)"
113 ))
114}
115
116pub fn is_insecure_ws(url: &str) -> bool {
120 url.starts_with("ws://") && check_ws_url(url, false).is_err() && check_ws_url(url, true).is_ok()
121}
122
123fn url_host(rest: &str) -> Option<String> {
126 let authority = rest.split(['/', '?', '#']).next().unwrap_or("");
127 let authority = authority.rsplit_once('@').map_or(authority, |(_, h)| h);
128 let host = if let Some(v6) = authority.strip_prefix('[') {
129 v6.split_once(']')?.0
130 } else {
131 authority.split(':').next().unwrap_or("")
132 };
133 (!host.is_empty()).then(|| host.to_ascii_lowercase())
134}
135
136pub fn is_loopback_host(host: &str) -> bool {
140 let host = host.trim_end_matches('.');
141 if host.eq_ignore_ascii_case("localhost") {
142 return true;
143 }
144 match host.parse::<std::net::IpAddr>() {
145 Ok(std::net::IpAddr::V4(a)) => a.is_loopback(),
146 Ok(std::net::IpAddr::V6(a)) => a.is_loopback() || a.to_ipv4_mapped().is_some_and(|v4| v4.is_loopback()),
147 Err(_) => false,
148 }
149}
150
151#[derive(Debug, Clone, Copy, PartialEq, Eq)]
156pub struct Backoff {
157 pub initial: Duration,
158 pub max: Duration,
159 pub per_minute: usize,
160}
161
162impl Default for Backoff {
163 fn default() -> Self {
165 Self { initial: Duration::from_millis(500), max: Duration::from_secs(30), per_minute: 5 }
166 }
167}
168
169impl Backoff {
170 pub fn delay(&self, n: usize) -> Duration {
172 let factor = 1u32.checked_shl(n.min(31) as u32).unwrap_or(u32::MAX);
173 self.initial.saturating_mul(factor).min(self.max)
174 }
175}
176
177#[derive(Debug, Clone)]
179pub struct ChildOptions {
180 pub principal: String,
184 pub key: Option<PathBuf>,
188 pub agent: String,
190 pub timeout: Duration,
192 pub max_calls: usize,
194 pub buffer: usize,
197 pub env: Vec<String>,
200 pub backoff: Backoff,
202 pub max_depth: usize,
205 pub schema_cache: usize,
209 pub host: Option<crate::plexus::service_scope::WeakService>,
214 pub ping: Option<Duration>,
218 pub legacy_upcalls: bool,
225 pub tls_roots: Option<PathBuf>,
230 pub insecure_ws: bool,
235 pub tokens: Option<std::sync::Arc<crate::plexus::peer_token::TokenIssuer>>,
243 pub schemas: Vec<String>,
249 pub consent_required: bool,
255 pub revoked: Option<String>,
258}
259
260impl Default for ChildOptions {
261 fn default() -> Self {
262 Self {
263 principal: "service:service".into(),
264 key: None,
265 agent: "service".into(),
266 timeout: Duration::from_secs(5),
267 max_calls: 1024,
268 buffer: 1024,
269 env: Vec::new(),
270 backoff: Backoff::default(),
271 max_depth: 8,
272 schema_cache: 1024,
273 host: None,
274 ping: None,
275 legacy_upcalls: false,
276 tls_roots: None,
277 insecure_ws: false,
278 tokens: None,
279 schemas: Vec::new(),
280 consent_required: false,
281 revoked: None,
282 }
283 }
284}
285
286impl ChildOptions {
287 pub fn for_service(service: &str) -> Self {
290 Self { principal: format!("service:{service}"), agent: service.to_string(), ..Self::default() }
291 }
292
293 pub fn with_legacy_upcalls(mut self, on: bool) -> Self {
298 self.legacy_upcalls = on;
299 self
300 }
301
302 pub fn with_schemas<I: IntoIterator<Item = S>, S: Into<String>>(mut self, paths: I) -> Self {
305 self.schemas = paths.into_iter().map(Into::into).collect();
306 self
307 }
308
309 pub fn with_consent_required(mut self, on: bool) -> Self {
312 self.consent_required = on;
313 self
314 }
315
316 pub fn with_revoked(mut self, why: Option<String>) -> Self {
318 self.revoked = why;
319 self
320 }
321
322 pub fn with_host(mut self, service: &crate::plexus::DynamicHub) -> Self {
323 self.host = Some(service.downgrade());
324 self
325 }
326}
327
328#[derive(Debug, Clone, thiserror::Error, PartialEq, Eq)]
330pub enum ChildError {
331 #[error("child spec {0}")]
333 Spec(String),
334 #[error("child {0}: {1}")]
337 Start(String, String),
338}
339
340pub fn parse_duration(s: &str) -> Result<Duration, String> {
342 let s = s.trim();
343 let (num, unit) = match s.find(|c: char| !(c.is_ascii_digit() || c == '.')) {
344 Some(i) => (&s[..i], s[i..].trim()),
345 None => (s, "s"),
346 };
347 let n: f64 = num.parse().map_err(|_| format!("`{s}` is not a duration (5s, 500ms, 2m)"))?;
348 let secs = match unit {
349 "ms" => n / 1e3,
350 "s" | "" => n,
351 "m" => n * 60.0,
352 _ => return Err(format!("`{s}`: the unit is ms, s or m")),
353 };
354 if !secs.is_finite() || secs <= 0.0 {
355 return Err(format!("`{s}` is not a positive duration"));
356 }
357 Ok(Duration::from_secs_f64(secs))
358}
359
360#[cfg(test)]
361mod tests {
362 use super::*;
363
364 #[test]
365 fn child_spec_parses() {
366 let s: ChildSpec = r#"echo=stdio:python -I -m echo --x "a b""#.parse().unwrap();
367 assert_eq!(s, ChildSpec::Stdio { name: "echo".into(), argv: vec!["python".into(), "-I".into(), "-m".into(), "echo".into(), "--x".into(), "a b".into()] });
368 let s: ChildSpec = r#"echo=stdio:"python3 -I stub.py --stdio""#.parse().unwrap();
369 assert_eq!(s, ChildSpec::Stdio { name: "echo".into(), argv: vec!["python3".into(), "-I".into(), "stub.py".into(), "--stdio".into()] });
370 assert_eq!("echo=ws://h:1".parse::<ChildSpec>().unwrap(), ChildSpec::Ws { name: "echo".into(), url: "ws://h:1".into() });
371 assert_eq!("e-2=wss://h/ws".parse::<ChildSpec>().unwrap(), ChildSpec::Ws { name: "e-2".into(), url: "wss://h/ws".into() });
372 let refused = |s: &str, why: &str| {
373 let e = s.parse::<ChildSpec>().unwrap_err().to_string();
374 assert!(e.contains(why), "{s}: {e}");
375 };
376 refused("echo", "no `=`");
377 refused("=stdio:x", "empty mount name");
378 refused("a.b=stdio:x", "dotted");
379 refused("a b=stdio:x", "holds ` `");
380 refused("echo=tcp://h:1", "unknown scheme `tcp`");
381 refused("echo=stdio:", "no command");
382 refused(r#"echo=stdio:python "unclosed"#, "does not split");
383 refused("echo=ws://:1", "names its host");
384 }
385
386 #[test]
387 fn child_spec_round_trips() {
388 for s in [r#"echo=stdio:python -I "a b""#, "echo=ws://127.0.0.1:4480"] {
389 let spec: ChildSpec = s.parse().unwrap();
390 assert_eq!(spec.to_string().parse::<ChildSpec>().unwrap(), spec);
391 }
392 }
393
394 #[test]
395 fn backoff_doubles_to_its_cap() {
396 let b = Backoff::default();
397 let ms: Vec<u128> = (0..8).map(|n| b.delay(n).as_millis()).collect();
398 assert_eq!(ms, [500, 1000, 2000, 4000, 8000, 16000, 30000, 30000]);
399 }
400
401 #[test]
402 fn durations_read() {
403 assert_eq!(parse_duration("5s").unwrap(), Duration::from_secs(5));
404 assert_eq!(parse_duration("250ms").unwrap(), Duration::from_millis(250));
405 assert_eq!(parse_duration("2").unwrap(), Duration::from_secs(2));
406 assert_eq!(parse_duration("1m").unwrap(), Duration::from_secs(60));
407 assert!(parse_duration("0s").is_err() && parse_duration("x").is_err() && parse_duration("3h").is_err());
408 }
409}