Skip to main content

plexus_core/plexus/remote_child/
mod.rs

1//! POLYGLOT-5 — the child seam opened: an activation in another process,
2//! mounted under a name.
3//!
4//! [`RemoteChild`] is the second implementation of [`ChildRouter`] (and
5//! [`Activation`]): its other end is a process on stdio or a service on a
6//! WebSocket speaking plexus-wire (spec 01–05, 07, 11 and 12, *the hop
7//! between services*). A [`DynamicHub`](super::DynamicHub) registers it like
8//! any activation — its schema and roles merged under the mount name, its
9//! methods granted, refused and listed as an in-process activation's.
10//!
11//! ```ignore
12//! let echo = RemoteChild::connect("echo=stdio:python3 -I stub_child.py".parse()?, ChildOptions::for_service("menger")).await?;
13//! let service = DynamicHub::new("menger").register(tickets).register(echo);
14//! ```
15//!
16//! # What crosses
17//!
18//! The gate decides first; a refused call never reaches the child. An
19//! admitted one is `{ns}.call {method, params, hop}` with
20//! `hop = {principal, for, limit {grant, held_on} | null, call}`: the
21//! service acting, the caller it acts for, the gate's verdict as a ceiling
22//! and a call id — built from the verified principal and
23//! [`current_reach`](super::grant_gate::current_reach) only (an error outside
24//! a call, RETURNS-47: then nothing crosses), never from the caller's
25//! credential. Items come back unchanged, in order; the child's
26//! terminal item ends the caller's stream. A caller that lets go sends
27//! `{ns}.call_unsub`. A child gone is one `child_unavailable` error — the
28//! end (spec/03: an error is terminal) — and the next call starts it again,
29//! within its [`Backoff`]. An item nobody asked for is dropped, logged and
30//! counted ([`ChildStats::unasked`]).
31
32// RETURNS-47: the far side in Rust — an activation served as a child, each
33// call in its hop's context.
34mod host;
35mod link;
36// RETURNS-36: a peer on plexus-wire's spec as main wrote it, read as 0.8.
37mod peer;
38mod spec;
39#[cfg(feature = "child-ws")]
40mod ws;
41#[cfg(feature = "clap")]
42mod args;
43
44use std::pin::Pin;
45use std::sync::atomic::Ordering;
46use std::sync::Arc;
47use std::task::{Context, Poll};
48use std::time::Instant;
49
50use async_trait::async_trait;
51use futures::Stream;
52use plexus_auth_core::grants::{GrantsGeneration, Reach};
53use serde_json::{json, Value};
54use tokio::sync::mpsc;
55
56pub use host::{serve_child, serve_child_on, serve_child_stdio, ChildPeer};
57pub use link::MountTimings;
58pub use spec::{parse_duration, Backoff, ChildError, ChildOptions, ChildSpec};
59#[cfg(feature = "clap")]
60pub use args::ChildArgs;
61
62use link::{meta, too_many, unavailable, Conn, Counters, Shared, SubKey};
63
64use super::auth::AuthContext;
65use super::method_enum::MethodEnumSchema;
66use super::plexus::{Activation, ChildRouter, PlexusError};
67use super::schema::{MethodRole, PluginSchema};
68use super::streaming::PlexusStream;
69use super::types::PlexusStreamItem;
70
71/// What the seam has seen of one child.
72#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
73pub struct ChildStats {
74    /// Calls open now.
75    pub open: usize,
76    /// Items the child sent for a call it was not given (dropped).
77    pub unasked: u64,
78    /// Times the child was started (or dialed) again after it went.
79    pub restarts: u64,
80    /// Calls forwarded, in all.
81    pub calls: u64,
82}
83
84/// A child's methods are data — its schema, asked at mount — not a Rust
85/// enum: the [`Activation::Methods`] of a [`RemoteChild`].
86#[derive(Debug, Clone, Copy)]
87pub enum ChildMethods {}
88
89impl schemars::JsonSchema for ChildMethods {
90    fn schema_name() -> std::borrow::Cow<'static, str> {
91        "ChildMethods".into()
92    }
93
94    fn json_schema(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
95        schemars::json_schema!({
96            "description": "A child service's methods are data: its schema, asked when it was mounted (`<mount>.schema`)."
97        })
98    }
99}
100
101impl MethodEnumSchema for ChildMethods {
102    fn method_names() -> &'static [&'static str] {
103        &[]
104    }
105
106    fn schema_with_consts() -> Value {
107        serde_json::to_value(schemars::schema_for!(ChildMethods)).unwrap_or(Value::Null)
108    }
109}
110
111struct Inner {
112    shared: Arc<Shared>,
113    schema: PluginSchema,
114    timings: MountTimings,
115}
116
117/// An activation in another process (or behind a WebSocket), mounted under
118/// its [`ChildSpec`]'s name. Cheap to clone; the child stops when the last
119/// clone is dropped.
120#[derive(Clone)]
121pub struct RemoteChild {
122    inner: Arc<Inner>,
123}
124
125impl std::fmt::Debug for RemoteChild {
126    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
127        f.debug_struct("RemoteChild").field("spec", &self.inner.shared.spec.to_string()).field("stats", &self.stats()).finish()
128    }
129}
130
131/// The child's schema as the service keeps it: under the mount name, its
132/// roles' grants requalified (`{ns}.m` → `<mount>.m`). A child mounting
133/// children of its own is refused, naming the method.
134fn mount_schema(name: &str, raw: Value) -> Result<PluginSchema, String> {
135    let mut schema: PluginSchema = serde_json::from_value(peer::schema(raw)?).map_err(|e| format!("its schema does not read: {e}"))?;
136    if let Some(m) = schema.methods.iter().find(|m| m.role != MethodRole::Rpc) {
137        return Err(format!("its method `{}` is a child ({:?}): a child mounting children is not served", m.name, m.role));
138    }
139    #[allow(deprecated)] // IR-4: the side-table, still on the wire
140    if schema.children.as_ref().is_some_and(|c| !c.is_empty()) {
141        return Err("its schema lists children: a child mounting children is not served".into());
142    }
143    if schema.namespace != name {
144        tracing::info!(target: "plexus::child", child = %name, declared = %schema.namespace, "mounted under its mount name, not the namespace it declares");
145    }
146    let prefix = format!("{}.", schema.namespace);
147    let requalify = |g: &String| match g.strip_prefix(&prefix) {
148        Some(m) => format!("{name}.{m}"),
149        None => format!("{name}.{g}"),
150    };
151    schema.roles = schema.roles.iter().map(|(r, gs)| (r.clone(), gs.iter().map(requalify).collect())).collect();
152    schema.namespace = name.to_string();
153    Ok(schema)
154}
155
156impl RemoteChild {
157    /// Start (or dial) the child, ask its `_info` and its schema within
158    /// `opts.timeout`, and keep the connection. Fails naming the child and
159    /// why: it did not start, did not answer, or published a schema the
160    /// service will not mount.
161    pub async fn connect(spec: ChildSpec, opts: ChildOptions) -> Result<Self, ChildError> {
162        let name = spec.name().to_string();
163        let start = |why: String| ChildError::Start(name.clone(), why);
164        if opts.max_calls == 0 || opts.buffer == 0 {
165            return Err(start("max_calls and buffer are at least 1".into()));
166        }
167        let principal = Self::principal_for(&spec, &opts).map_err(start)?;
168        let shared = Shared::new(spec, opts, principal);
169        let (conn, raw, mut timings) = shared.connect_once().await.map_err(start)?;
170        let t = Instant::now();
171        let hash = link::schema_hash(&raw);
172        let schema = match mount_schema(&name, raw) {
173            Ok(s) => s,
174            Err(why) => {
175                conn.shutdown.notify_one();
176                return Err(start(why));
177            }
178        };
179        let _ = shared.mounted_hash.set(hash);
180        shared.install(conn);
181        timings.merge_ms = t.elapsed().as_secs_f64() * 1e3;
182        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");
183        Ok(Self { inner: Arc::new(Inner { shared, schema, timings }) })
184    }
185
186    #[allow(unused_variables)]
187    fn principal_for(spec: &ChildSpec, opts: &ChildOptions) -> Result<String, String> {
188        #[cfg(feature = "child-ws")]
189        if let (ChildSpec::Ws { .. }, Some(path)) = (spec, &opts.key) {
190            return Ok(ws::principal_of(&ws::read_seed(path)?));
191        }
192        Ok(opts.principal.clone())
193    }
194
195    /// What the seam has seen.
196    pub fn stats(&self) -> ChildStats {
197        let c: &Counters = &self.inner.shared.counters;
198        ChildStats {
199            open: c.open.load(Ordering::Relaxed),
200            unasked: c.unasked.load(Ordering::Relaxed),
201            restarts: c.restarts.load(Ordering::Relaxed),
202            calls: c.calls.load(Ordering::Relaxed),
203        }
204    }
205
206    /// The process now serving (a stdio child), if one is up.
207    pub fn pid(&self) -> Option<u32> {
208        self.inner.shared.current().and_then(|c| c.pid)
209    }
210
211    /// The mount's name.
212    pub fn name(&self) -> &str {
213        &self.inner.shared.name
214    }
215
216    /// The spec it was mounted from.
217    pub fn spec(&self) -> &ChildSpec {
218        &self.inner.shared.spec
219    }
220
221    /// The hop's `principal`: the service acting, as this child is told.
222    pub fn principal(&self) -> &str {
223        &self.inner.shared.principal
224    }
225
226    /// How long the mount took.
227    pub fn mount_timings(&self) -> MountTimings {
228        self.inner.timings
229    }
230
231    /// Subscriptions routed on the live connection (0 when none is up).
232    pub fn routed(&self) -> usize {
233        self.inner.shared.current().map_or(0, |c| c.routed())
234    }
235
236    /// The hop (spec/12) for a call by `auth`, decided as `reach`: the
237    /// service acts, the caller is named `for`, the verdict is the limit.
238    /// Nothing of the caller's credential.
239    fn hop(&self, conn: &Conn, auth: Option<&AuthContext>, reach: &Reach) -> Value {
240        let for_: Vec<String> = auth.and_then(|a| a.principal()).map(|p| p.to_string()).into_iter().collect();
241        let limit = reach.grant().map(|g| {
242            let grant = match g.as_str().strip_prefix(&format!("{}.", self.name())) {
243                Some(m) => format!("{}.{m}", conn.ns()),
244                None => g.as_str().to_string(),
245            };
246            let held_on: Vec<String> = reach.held_on().iter().map(|s| s.to_string()).collect();
247            json!({ "grant": grant, "held_on": held_on })
248        });
249        json!({ "principal": self.inner.shared.principal, "for": for_, "limit": limit, "call": uuid::Uuid::new_v4().to_string() })
250    }
251
252    fn schema_stream(&self, params: &Value) -> PlexusStream {
253        let ns = self.name().to_string();
254        let content = match params.get("method").and_then(Value::as_str) {
255            Some(m) => match self.inner.schema.methods.iter().find(|x| x.name == m) {
256                Some(ms) => serde_json::to_value(ms).unwrap_or_default(),
257                None => {
258                    let error = plexus_client::RemoteError::MethodNotFound { activation: ns.clone(), method: m.to_string() };
259                    let mut e = PlexusStreamItem::error(meta(&ns), error, false);
260                    if let PlexusStreamItem::Error { message, code, .. } = &mut e {
261                        *message = format!("Method '{m}' not found");
262                        *code = Some("-32602".into());
263                    }
264                    return Box::pin(futures::stream::iter([e]));
265                }
266            },
267            None => serde_json::to_value(&self.inner.schema).unwrap_or_default(),
268        };
269        Box::pin(futures::stream::iter([
270            PlexusStreamItem::Data { metadata: meta(&ns).into(), content_type: format!("{ns}.schema").into(), content: content.into() },
271            PlexusStreamItem::Done { metadata: meta(&ns) },
272        ]))
273    }
274
275    async fn forward(&self, method: &str, params: Value, auth: Option<&AuthContext>) -> PlexusStream {
276        let shared = &self.inner.shared;
277        let one = |item: PlexusStreamItem| -> PlexusStream { Box::pin(futures::stream::iter([item])) };
278        // RETURNS-47: the verdict is the call's; outside one (a forward no
279        // dispatch admitted) nothing crosses — fail closed, never everywhere.
280        let reach = match super::grant_gate::current_reach() {
281            Ok(reach) => reach,
282            Err(e) => return one(PlexusStreamItem::from_plexus_error(meta(self.name()), &e, false)),
283        };
284        let max = shared.opts.max_calls;
285        if shared.counters.open.fetch_add(1, Ordering::AcqRel) >= max {
286            shared.counters.open.fetch_sub(1, Ordering::AcqRel);
287            return one(too_many(self.name(), max));
288        }
289        let guard = OpenGuard(Arc::clone(&shared.counters));
290        let conn = match shared.ensure().await {
291            Ok(c) => c,
292            Err(item) => return one(item),
293        };
294        shared.counters.calls.fetch_add(1, Ordering::Relaxed);
295        let hop = self.hop(&conn, auth, &reach);
296        let path = format!("{}.{method}", conn.ns());
297        let call = json!({ "method": path, "params": params, "hop": hop });
298        match conn.open(&format!("{}.call", conn.ns()), call, shared.opts.timeout).await {
299            Ok((sid, rx)) => {
300                let generation = reach.generation().cloned();
301                let seen = generation.as_ref().map_or(0, GrantsGeneration::current);
302                Box::pin(CallStream { rx, sid, conn, over: false, _guard: guard, reach, generation, seen, name: self.name().to_string() })
303            }
304            Err(item) => one(item),
305        }
306    }
307}
308
309/// One open call, counted until its stream ends or is dropped.
310struct OpenGuard(Arc<Counters>);
311
312impl Drop for OpenGuard {
313    fn drop(&mut self) {
314        self.0.open.fetch_sub(1, Ordering::AcqRel);
315    }
316}
317
318/// The stream the service hands its caller: the child's items, in order,
319/// until the first terminal one; dropped before it, the child is told.
320struct CallStream {
321    rx: mpsc::Receiver<PlexusStreamItem>,
322    sid: SubKey,
323    conn: Arc<Conn>,
324    over: bool,
325    _guard: OpenGuard,
326    /// The gate's verdict at the open, asked again when the grants
327    /// generation moves (BIDIR-1 `regate = generation`, BIDIR-8).
328    reach: Reach,
329    generation: Option<GrantsGeneration>,
330    seen: u64,
331    name: String,
332}
333
334impl CallStream {
335    /// The grant revoked mid-stream: the caller's last item.
336    fn revoked(&self) -> PlexusStreamItem {
337        let grant = self.reach.grant().map(|g| g.as_str().to_string()).unwrap_or_default();
338        let error = plexus_client::RemoteError::Forbidden {
339            reason: plexus_client::DenyReason::MissingGrant {
340                grant: grant.clone(),
341                scope: "*".into(),
342                roles: Vec::new(),
343                held_on: Vec::new(),
344            },
345        };
346        let mut item = PlexusStreamItem::error(meta(&self.name), error, false);
347        if let PlexusStreamItem::Error { message, .. } = &mut item {
348            *message = format!("Forbidden: `{grant}` is no longer held — the call's grant moved while it ran");
349        }
350        item
351    }
352}
353
354impl Stream for CallStream {
355    type Item = PlexusStreamItem;
356
357    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
358        if self.over {
359            return Poll::Ready(None);
360        }
361        match self.rx.poll_recv(cx) {
362            Poll::Ready(Some(item)) => {
363                let terminal = matches!(item, PlexusStreamItem::Done { .. } | PlexusStreamItem::Error { .. });
364                let moved = self.generation.as_ref().map(GrantsGeneration::current).filter(|g| *g != self.seen);
365                if let (false, Some(g)) = (terminal, moved) {
366                    self.seen = g;
367                    if self.reach.current().is_none() {
368                        let sid = self.sid.clone();
369                        self.conn.unsubscribe(&sid);
370                        self.over = true;
371                        return Poll::Ready(Some(self.revoked()));
372                    }
373                }
374                if terminal {
375                    self.over = true;
376                }
377                Poll::Ready(Some(item))
378            }
379            Poll::Ready(None) => {
380                // The channel closed with no terminal item: the link went.
381                self.over = true;
382                Poll::Ready(Some(unavailable(&self.name, "the connection closed")))
383            }
384            Poll::Pending => Poll::Pending,
385        }
386    }
387}
388
389impl Drop for CallStream {
390    fn drop(&mut self) {
391        if !self.over {
392            self.conn.unsubscribe(&self.sid);
393        }
394    }
395}
396
397#[async_trait]
398impl Activation for RemoteChild {
399    type Methods = ChildMethods;
400
401    fn namespace(&self) -> &str {
402        self.name()
403    }
404
405    fn version(&self) -> &str {
406        &self.inner.schema.version
407    }
408
409    fn description(&self) -> &str {
410        &self.inner.schema.description
411    }
412
413    fn long_description(&self) -> Option<&str> {
414        self.inner.schema.long_description.as_deref()
415    }
416
417    fn methods(&self) -> Vec<&str> {
418        self.inner.schema.methods.iter().map(|m| m.name.as_str()).collect()
419    }
420
421    fn method_help(&self, method: &str) -> Option<String> {
422        self.inner.schema.methods.iter().find(|m| m.name == method).map(|m| m.description.clone())
423    }
424
425    async fn call(&self, method: &str, params: Value, auth: Option<&AuthContext>, _raw: Option<&crate::request::RawRequestContext>) -> Result<PlexusStream, PlexusError> {
426        if method == "schema" {
427            return Ok(self.schema_stream(&params));
428        }
429        let Some(m) = self.inner.schema.methods.iter().find(|m| m.name == method) else {
430            return Err(PlexusError::MethodNotFound { activation: self.name().to_string(), method: method.to_string() });
431        };
432        // BIDIR-6: a hop forwards no input half yet; the far side would wait
433        // for items that never come.
434        if m.input.is_some() {
435            return Err(PlexusError::ExecutionError(format!(
436                "`{}.{method}` takes an input stream, and a hop to a remote child does not forward one yet",
437                self.name()
438            )));
439        }
440        Ok(self.forward(method, params, auth).await)
441    }
442
443    /// Nothing of its own on the socket: a child is reached through the
444    /// service's `{service}.call`, behind its gate.
445    fn into_rpc_methods(self) -> jsonrpsee::Methods {
446        jsonrpsee::Methods::new()
447    }
448
449    fn plugin_schema(&self) -> PluginSchema {
450        self.inner.schema.clone()
451    }
452}
453
454#[async_trait]
455impl ChildRouter for RemoteChild {
456    fn router_namespace(&self) -> &str {
457        self.name()
458    }
459
460    async fn router_call(&self, method: &str, params: Value, auth: Option<&AuthContext>, raw: Option<&crate::request::RawRequestContext>) -> Result<PlexusStream, PlexusError> {
461        Activation::call(self, method, params, auth, raw).await
462    }
463
464    async fn get_child(&self, _name: &str) -> Option<Box<dyn ChildRouter>> {
465        None
466    }
467
468    fn router_schema(&self) -> Option<PluginSchema> {
469        Some(self.inner.schema.clone())
470    }
471}
472
473#[cfg(test)]
474mod tests {
475    use super::*;
476
477    fn raw(methods: Value, roles: Value) -> Value {
478        json!({ "namespace": "stub", "version": "0.1.0", "description": "d", "self_hash": "h", "hash": "h", "methods": methods, "roles": roles })
479    }
480
481    fn m(name: &str) -> Value {
482        json!({ "name": name, "description": "", "hash": "x", "streaming": false, "bidirectional": false })
483    }
484
485    /// RETURNS-36 (review #6): no guessing — a method that states neither
486    /// `cardinality` (0.8) nor `streaming` (0.7.0) is refused, naming it, as
487    /// plexus-protocol's `cardinalityOf` refuses it.
488    #[test]
489    fn a_method_stating_neither_cardinality_nor_streaming_is_refused() {
490        let silent = json!({ "name": "quiet", "description": "", "hash": "x" });
491        let e = mount_schema("echo", raw(json!([m("echo"), silent]), json!({}))).unwrap_err();
492        assert!(e.contains("`quiet`") && e.contains("neither cardinality"), "{e}");
493    }
494
495    #[test]
496    fn the_mount_name_wins_and_roles_are_requalified() {
497        let s = mount_schema("echo", raw(json!([m("echo"), m("shout")]), json!({ "viewer": ["stub.echo"], "editor": ["stub.echo", "stub.shout"] }))).unwrap();
498        assert_eq!(s.namespace, "echo");
499        assert_eq!(s.roles["viewer"], vec!["echo.echo".to_string()]);
500        assert_eq!(s.roles["editor"], vec!["echo.echo".to_string(), "echo.shout".to_string()]);
501    }
502
503    #[test]
504    fn a_child_with_children_is_refused_naming_the_method() {
505        let mut inner = m("inner");
506        inner["role"] = json!({ "kind": "static_child" });
507        let e = mount_schema("echo", raw(json!([m("echo"), inner]), json!({}))).unwrap_err();
508        assert!(e.contains("`inner`"), "{e}");
509    }
510
511    #[test]
512    fn typed_error_fields_cross_whole() {
513        let item = unavailable("echo", "gone");
514        let v = serde_json::to_value(&item).unwrap();
515        assert_eq!(v["error_kind"], "child_unavailable");
516        assert_eq!(v["code"], "child_unavailable");
517        assert_eq!(v["child"], "echo");
518        let back: PlexusStreamItem = serde_json::from_value(v.clone()).unwrap();
519        assert_eq!(back.error_kind(), Some("child_unavailable"));
520        assert_eq!(serde_json::to_value(&back).unwrap(), v);
521        // An error spec/05 gives no kind carries no `error_kind`: its keys
522        // are spec/05's four and RETURNS-6's typed `error` (RETURNS-36).
523        let plain = PlexusStreamItem::error(meta("x"), plexus_client::RemoteError::Execution { message: "m".into() }, false);
524        let pv = serde_json::to_value(&plain).unwrap();
525        let keys: Vec<_> = pv.as_object().unwrap().keys().cloned().collect();
526        assert_eq!(keys, ["code", "error", "message", "metadata", "recoverable", "type"]);
527    }
528}