1mod link;
32mod peer;
34mod spec;
35#[cfg(feature = "child-ws")]
36mod ws;
37#[cfg(feature = "clap")]
38mod args;
39
40use std::pin::Pin;
41use std::sync::atomic::Ordering;
42use std::sync::Arc;
43use std::task::{Context, Poll};
44use std::time::Instant;
45
46use async_trait::async_trait;
47use futures::Stream;
48use plexus_auth_core::grants::{GrantsGeneration, Reach};
49use serde_json::{json, Value};
50use tokio::sync::mpsc;
51
52pub use link::MountTimings;
53pub use spec::{parse_duration, Backoff, ChildError, ChildOptions, ChildSpec};
54#[cfg(feature = "clap")]
55pub use args::ChildArgs;
56
57use link::{meta, too_many, unavailable, Conn, Counters, Shared, SubKey};
58
59use super::auth::AuthContext;
60use super::method_enum::MethodEnumSchema;
61use super::plexus::{Activation, ChildRouter, PlexusError};
62use super::schema::{MethodRole, PluginSchema};
63use super::streaming::PlexusStream;
64use super::types::PlexusStreamItem;
65
66#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
68pub struct ChildStats {
69 pub open: usize,
71 pub unasked: u64,
73 pub restarts: u64,
75 pub calls: u64,
77}
78
79#[derive(Debug, Clone, Copy)]
82pub enum ChildMethods {}
83
84impl schemars::JsonSchema for ChildMethods {
85 fn schema_name() -> std::borrow::Cow<'static, str> {
86 "ChildMethods".into()
87 }
88
89 fn json_schema(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
90 schemars::json_schema!({
91 "description": "A child service's methods are data: its schema, asked when it was mounted (`<mount>.schema`)."
92 })
93 }
94}
95
96impl MethodEnumSchema for ChildMethods {
97 fn method_names() -> &'static [&'static str] {
98 &[]
99 }
100
101 fn schema_with_consts() -> Value {
102 serde_json::to_value(schemars::schema_for!(ChildMethods)).unwrap_or(Value::Null)
103 }
104}
105
106struct Inner {
107 shared: Arc<Shared>,
108 schema: PluginSchema,
109 timings: MountTimings,
110}
111
112#[derive(Clone)]
116pub struct RemoteChild {
117 inner: Arc<Inner>,
118}
119
120impl std::fmt::Debug for RemoteChild {
121 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
122 f.debug_struct("RemoteChild").field("spec", &self.inner.shared.spec.to_string()).field("stats", &self.stats()).finish()
123 }
124}
125
126fn mount_schema(name: &str, raw: Value) -> Result<PluginSchema, String> {
130 let mut schema: PluginSchema = serde_json::from_value(peer::schema(raw)?).map_err(|e| format!("its schema does not read: {e}"))?;
131 if let Some(m) = schema.methods.iter().find(|m| m.role != MethodRole::Rpc) {
132 return Err(format!("its method `{}` is a child ({:?}): a child mounting children is not served", m.name, m.role));
133 }
134 #[allow(deprecated)] if schema.children.as_ref().is_some_and(|c| !c.is_empty()) {
136 return Err("its schema lists children: a child mounting children is not served".into());
137 }
138 if schema.namespace != name {
139 tracing::info!(target: "plexus::child", child = %name, declared = %schema.namespace, "mounted under its mount name, not the namespace it declares");
140 }
141 let prefix = format!("{}.", schema.namespace);
142 let requalify = |g: &String| match g.strip_prefix(&prefix) {
143 Some(m) => format!("{name}.{m}"),
144 None => format!("{name}.{g}"),
145 };
146 schema.roles = schema.roles.iter().map(|(r, gs)| (r.clone(), gs.iter().map(requalify).collect())).collect();
147 schema.namespace = name.to_string();
148 Ok(schema)
149}
150
151impl RemoteChild {
152 pub async fn connect(spec: ChildSpec, opts: ChildOptions) -> Result<Self, ChildError> {
157 let name = spec.name().to_string();
158 let start = |why: String| ChildError::Start(name.clone(), why);
159 if opts.max_calls == 0 || opts.buffer == 0 {
160 return Err(start("max_calls and buffer are at least 1".into()));
161 }
162 let principal = Self::principal_for(&spec, &opts).map_err(start)?;
163 let shared = Shared::new(spec, opts, principal);
164 let (conn, raw, mut timings) = shared.connect_once().await.map_err(start)?;
165 let t = Instant::now();
166 let hash = link::schema_hash(&raw);
167 let schema = match mount_schema(&name, raw) {
168 Ok(s) => s,
169 Err(why) => {
170 conn.shutdown.notify_one();
171 return Err(start(why));
172 }
173 };
174 let _ = shared.mounted_hash.set(hash);
175 shared.install(conn);
176 timings.merge_ms = t.elapsed().as_secs_f64() * 1e3;
177 tracing::info!(target: "plexus::child", child = %name, spawn_ms = timings.spawn_ms, schema_ms = timings.schema_ms, merge_ms = timings.merge_ms, methods = schema.methods.len(), "child mounted");
178 Ok(Self { inner: Arc::new(Inner { shared, schema, timings }) })
179 }
180
181 #[allow(unused_variables)]
182 fn principal_for(spec: &ChildSpec, opts: &ChildOptions) -> Result<String, String> {
183 #[cfg(feature = "child-ws")]
184 if let (ChildSpec::Ws { .. }, Some(path)) = (spec, &opts.key) {
185 return Ok(ws::principal_of(&ws::read_seed(path)?));
186 }
187 Ok(opts.principal.clone())
188 }
189
190 pub fn stats(&self) -> ChildStats {
192 let c: &Counters = &self.inner.shared.counters;
193 ChildStats {
194 open: c.open.load(Ordering::Relaxed),
195 unasked: c.unasked.load(Ordering::Relaxed),
196 restarts: c.restarts.load(Ordering::Relaxed),
197 calls: c.calls.load(Ordering::Relaxed),
198 }
199 }
200
201 pub fn pid(&self) -> Option<u32> {
203 self.inner.shared.current().and_then(|c| c.pid)
204 }
205
206 pub fn name(&self) -> &str {
208 &self.inner.shared.name
209 }
210
211 pub fn spec(&self) -> &ChildSpec {
213 &self.inner.shared.spec
214 }
215
216 pub fn principal(&self) -> &str {
218 &self.inner.shared.principal
219 }
220
221 pub fn mount_timings(&self) -> MountTimings {
223 self.inner.timings
224 }
225
226 pub fn routed(&self) -> usize {
228 self.inner.shared.current().map_or(0, |c| c.routed())
229 }
230
231 fn hop(&self, conn: &Conn, auth: Option<&AuthContext>, reach: &Reach) -> Value {
235 let for_: Vec<String> = auth.and_then(|a| a.principal()).map(|p| p.to_string()).into_iter().collect();
236 let limit = reach.grant().map(|g| {
237 let grant = match g.as_str().strip_prefix(&format!("{}.", self.name())) {
238 Some(m) => format!("{}.{m}", conn.ns()),
239 None => g.as_str().to_string(),
240 };
241 let held_on: Vec<String> = reach.held_on().iter().map(|s| s.to_string()).collect();
242 json!({ "grant": grant, "held_on": held_on })
243 });
244 json!({ "principal": self.inner.shared.principal, "for": for_, "limit": limit, "call": uuid::Uuid::new_v4().to_string() })
245 }
246
247 fn schema_stream(&self, params: &Value) -> PlexusStream {
248 let ns = self.name().to_string();
249 let content = match params.get("method").and_then(Value::as_str) {
250 Some(m) => match self.inner.schema.methods.iter().find(|x| x.name == m) {
251 Some(ms) => serde_json::to_value(ms).unwrap_or_default(),
252 None => {
253 let error = plexus_client::RemoteError::MethodNotFound { activation: ns.clone(), method: m.to_string() };
254 let mut e = PlexusStreamItem::error(meta(&ns), error, false);
255 if let PlexusStreamItem::Error { message, code, .. } = &mut e {
256 *message = format!("Method '{m}' not found");
257 *code = Some("-32602".into());
258 }
259 return Box::pin(futures::stream::iter([e]));
260 }
261 },
262 None => serde_json::to_value(&self.inner.schema).unwrap_or_default(),
263 };
264 Box::pin(futures::stream::iter([
265 PlexusStreamItem::Data { metadata: meta(&ns).into(), content_type: format!("{ns}.schema").into(), content: content.into() },
266 PlexusStreamItem::Done { metadata: meta(&ns) },
267 ]))
268 }
269
270 async fn forward(&self, method: &str, params: Value, auth: Option<&AuthContext>) -> PlexusStream {
271 let reach = super::grant_gate::current_reach();
272 let shared = &self.inner.shared;
273 let one = |item: PlexusStreamItem| -> PlexusStream { Box::pin(futures::stream::iter([item])) };
274 let max = shared.opts.max_calls;
275 if shared.counters.open.fetch_add(1, Ordering::AcqRel) >= max {
276 shared.counters.open.fetch_sub(1, Ordering::AcqRel);
277 return one(too_many(self.name(), max));
278 }
279 let guard = OpenGuard(Arc::clone(&shared.counters));
280 let conn = match shared.ensure().await {
281 Ok(c) => c,
282 Err(item) => return one(item),
283 };
284 shared.counters.calls.fetch_add(1, Ordering::Relaxed);
285 let hop = self.hop(&conn, auth, &reach);
286 let path = format!("{}.{method}", conn.ns());
287 let call = json!({ "method": path, "params": params, "hop": hop });
288 match conn.open(&format!("{}.call", conn.ns()), call, shared.opts.timeout).await {
289 Ok((sid, rx)) => {
290 let generation = reach.generation().cloned();
291 let seen = generation.as_ref().map_or(0, GrantsGeneration::current);
292 Box::pin(CallStream { rx, sid, conn, over: false, _guard: guard, reach, generation, seen, name: self.name().to_string() })
293 }
294 Err(item) => one(item),
295 }
296 }
297}
298
299struct OpenGuard(Arc<Counters>);
301
302impl Drop for OpenGuard {
303 fn drop(&mut self) {
304 self.0.open.fetch_sub(1, Ordering::AcqRel);
305 }
306}
307
308struct CallStream {
311 rx: mpsc::Receiver<PlexusStreamItem>,
312 sid: SubKey,
313 conn: Arc<Conn>,
314 over: bool,
315 _guard: OpenGuard,
316 reach: Reach,
319 generation: Option<GrantsGeneration>,
320 seen: u64,
321 name: String,
322}
323
324impl CallStream {
325 fn revoked(&self) -> PlexusStreamItem {
327 let grant = self.reach.grant().map(|g| g.as_str().to_string()).unwrap_or_default();
328 let error = plexus_client::RemoteError::Forbidden {
329 reason: plexus_client::DenyReason::MissingGrant {
330 grant: grant.clone(),
331 scope: "*".into(),
332 roles: Vec::new(),
333 held_on: Vec::new(),
334 },
335 };
336 let mut item = PlexusStreamItem::error(meta(&self.name), error, false);
337 if let PlexusStreamItem::Error { message, .. } = &mut item {
338 *message = format!("Forbidden: `{grant}` is no longer held — the call's grant moved while it ran");
339 }
340 item
341 }
342}
343
344impl Stream for CallStream {
345 type Item = PlexusStreamItem;
346
347 fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
348 if self.over {
349 return Poll::Ready(None);
350 }
351 match self.rx.poll_recv(cx) {
352 Poll::Ready(Some(item)) => {
353 let terminal = matches!(item, PlexusStreamItem::Done { .. } | PlexusStreamItem::Error { .. });
354 let moved = self.generation.as_ref().map(GrantsGeneration::current).filter(|g| *g != self.seen);
355 if let (false, Some(g)) = (terminal, moved) {
356 self.seen = g;
357 if self.reach.current().is_none() {
358 let sid = self.sid.clone();
359 self.conn.unsubscribe(&sid);
360 self.over = true;
361 return Poll::Ready(Some(self.revoked()));
362 }
363 }
364 if terminal {
365 self.over = true;
366 }
367 Poll::Ready(Some(item))
368 }
369 Poll::Ready(None) => {
370 self.over = true;
372 Poll::Ready(Some(unavailable(&self.name, "the connection closed")))
373 }
374 Poll::Pending => Poll::Pending,
375 }
376 }
377}
378
379impl Drop for CallStream {
380 fn drop(&mut self) {
381 if !self.over {
382 self.conn.unsubscribe(&self.sid);
383 }
384 }
385}
386
387#[async_trait]
388impl Activation for RemoteChild {
389 type Methods = ChildMethods;
390
391 fn namespace(&self) -> &str {
392 self.name()
393 }
394
395 fn version(&self) -> &str {
396 &self.inner.schema.version
397 }
398
399 fn description(&self) -> &str {
400 &self.inner.schema.description
401 }
402
403 fn long_description(&self) -> Option<&str> {
404 self.inner.schema.long_description.as_deref()
405 }
406
407 fn methods(&self) -> Vec<&str> {
408 self.inner.schema.methods.iter().map(|m| m.name.as_str()).collect()
409 }
410
411 fn method_help(&self, method: &str) -> Option<String> {
412 self.inner.schema.methods.iter().find(|m| m.name == method).map(|m| m.description.clone())
413 }
414
415 async fn call(&self, method: &str, params: Value, auth: Option<&AuthContext>, _raw: Option<&crate::request::RawRequestContext>) -> Result<PlexusStream, PlexusError> {
416 if method == "schema" {
417 return Ok(self.schema_stream(¶ms));
418 }
419 let Some(m) = self.inner.schema.methods.iter().find(|m| m.name == method) else {
420 return Err(PlexusError::MethodNotFound { activation: self.name().to_string(), method: method.to_string() });
421 };
422 if m.input.is_some() {
425 return Err(PlexusError::ExecutionError(format!(
426 "`{}.{method}` takes an input stream, and a hop to a remote child does not forward one yet",
427 self.name()
428 )));
429 }
430 Ok(self.forward(method, params, auth).await)
431 }
432
433 fn into_rpc_methods(self) -> jsonrpsee::Methods {
436 jsonrpsee::Methods::new()
437 }
438
439 fn plugin_schema(&self) -> PluginSchema {
440 self.inner.schema.clone()
441 }
442}
443
444#[async_trait]
445impl ChildRouter for RemoteChild {
446 fn router_namespace(&self) -> &str {
447 self.name()
448 }
449
450 async fn router_call(&self, method: &str, params: Value, auth: Option<&AuthContext>, raw: Option<&crate::request::RawRequestContext>) -> Result<PlexusStream, PlexusError> {
451 Activation::call(self, method, params, auth, raw).await
452 }
453
454 async fn get_child(&self, _name: &str) -> Option<Box<dyn ChildRouter>> {
455 None
456 }
457
458 fn router_schema(&self) -> Option<PluginSchema> {
459 Some(self.inner.schema.clone())
460 }
461}
462
463#[cfg(test)]
464mod tests {
465 use super::*;
466
467 fn raw(methods: Value, roles: Value) -> Value {
468 json!({ "namespace": "stub", "version": "0.1.0", "description": "d", "self_hash": "h", "hash": "h", "methods": methods, "roles": roles })
469 }
470
471 fn m(name: &str) -> Value {
472 json!({ "name": name, "description": "", "hash": "x", "streaming": false, "bidirectional": false })
473 }
474
475 #[test]
479 fn a_method_stating_neither_cardinality_nor_streaming_is_refused() {
480 let silent = json!({ "name": "quiet", "description": "", "hash": "x" });
481 let e = mount_schema("echo", raw(json!([m("echo"), silent]), json!({}))).unwrap_err();
482 assert!(e.contains("`quiet`") && e.contains("neither cardinality"), "{e}");
483 }
484
485 #[test]
486 fn the_mount_name_wins_and_roles_are_requalified() {
487 let s = mount_schema("echo", raw(json!([m("echo"), m("shout")]), json!({ "viewer": ["stub.echo"], "editor": ["stub.echo", "stub.shout"] }))).unwrap();
488 assert_eq!(s.namespace, "echo");
489 assert_eq!(s.roles["viewer"], vec!["echo.echo".to_string()]);
490 assert_eq!(s.roles["editor"], vec!["echo.echo".to_string(), "echo.shout".to_string()]);
491 }
492
493 #[test]
494 fn a_child_with_children_is_refused_naming_the_method() {
495 let mut inner = m("inner");
496 inner["role"] = json!({ "kind": "static_child" });
497 let e = mount_schema("echo", raw(json!([m("echo"), inner]), json!({}))).unwrap_err();
498 assert!(e.contains("`inner`"), "{e}");
499 }
500
501 #[test]
502 fn typed_error_fields_cross_whole() {
503 let item = unavailable("echo", "gone");
504 let v = serde_json::to_value(&item).unwrap();
505 assert_eq!(v["error_kind"], "child_unavailable");
506 assert_eq!(v["code"], "child_unavailable");
507 assert_eq!(v["child"], "echo");
508 let back: PlexusStreamItem = serde_json::from_value(v.clone()).unwrap();
509 assert_eq!(back.error_kind(), Some("child_unavailable"));
510 assert_eq!(serde_json::to_value(&back).unwrap(), v);
511 let plain = PlexusStreamItem::error(meta("x"), plexus_client::RemoteError::Execution { message: "m".into() }, false);
514 let pv = serde_json::to_value(&plain).unwrap();
515 let keys: Vec<_> = pv.as_object().unwrap().keys().cloned().collect();
516 assert_eq!(keys, ["code", "error", "message", "metadata", "recoverable", "type"]);
517 }
518}