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//! # A child's children (NEST-4) and its dynamic children (NEST-6)
33//!
34//! The mount walks the child's static tree once and keeps it: every level's
35//! schema is answered from it and nothing crosses (spec/12 rule 7). A
36//! dynamic child's slot (`#[child] fn planet(&self, name)`, or a
37//! `#[peer]` slot) stays on its parent's kept schema with its type, so the
38//! host's gate decides `<mount>.solar.earth.info` on the slot grant
39//! `<mount>.solar.{planet}.info` (an untyped slot whole, on
40//! `<mount>.solar.{planet}`) and the mount forwards it as `{ns}.call
41//! {method: "{ns}.solar.earth.info", hop}`, `hop.limit.grant` the slot grant
42//! in the child's terms; the child checks the slot ([`serve_child_on`]) and
43//! answers an unknown name with its own not-found. A slot's list and search
44//! methods are ordinary methods, forwarded. The one schema that crosses is
45//! an instance's (`<mount>.solar.earth.schema`): once per name, kept under
46//! the name and the `plexus_hash` it came with — at most
47//! `--child-schema-cache` names, the least recently used out
48//! ([`ChildStats::name_schemas`], [`ChildStats::name_schema_hits`]); an item
49//! through the name with another `plexus_hash` drops it, and a restart drops
50//! every name.
51
52// RETURNS-47: the far side in Rust — an activation served as a child, each
53// call in its hop's context.
54mod host;
55mod link;
56// NEST-6: one dynamic instance's schema, kept per name.
57mod names;
58// RETURNS-36: a peer on plexus-wire's spec as main wrote it, read as 0.8.
59mod peer;
60mod spec;
61#[cfg(feature = "child-ws")]
62mod ws;
63#[cfg(feature = "clap")]
64mod args;
65// VISION-5 (LOCAL-5): dial-in peers (the accepting side) and dial-out (the
66// side with no listening port).
67mod dial_in;
68#[cfg(feature = "child-ws")]
69mod dial_out;
70
71use std::pin::Pin;
72use std::sync::atomic::Ordering;
73use std::sync::Arc;
74use std::task::{Context, Poll};
75use std::time::Instant;
76
77use async_trait::async_trait;
78use futures::Stream;
79use plexus_auth_core::grants::{GrantsGeneration, Reach};
80use serde_json::{json, Value};
81use tokio::sync::mpsc;
82
83pub use host::{serve_child, serve_child_on, serve_child_stdio, ChildPeer};
84pub use link::MountTimings;
85pub use spec::{parse_duration, Backoff, ChildError, ChildOptions, ChildSpec};
86#[cfg(feature = "clap")]
87pub use args::ChildArgs;
88pub use dial_in::{PeerEvent, PeerInfo, PeerRoles, PeerSocket, Peers, PeersMethods};
89#[cfg(feature = "child-ws")]
90pub use dial_out::{key_principal, DialOut, DialState, Exposed};
91
92use link::{meta, too_many, unavailable, Conn, Counters, Shared, SubKey};
93
94use super::auth::AuthContext;
95use super::method_enum::MethodEnumSchema;
96use super::plexus::{Activation, ChildRouter, PlexusError};
97use super::schema::{MethodRole, PluginSchema};
98use super::streaming::PlexusStream;
99use super::types::PlexusStreamItem;
100
101/// What the seam has seen of one child.
102#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
103pub struct ChildStats {
104    /// Calls open now.
105    pub open: usize,
106    /// Items the child sent for a call it was not given (dropped).
107    pub unasked: u64,
108    /// Times the child was started (or dialed) again after it went.
109    pub restarts: u64,
110    /// Calls forwarded, in all.
111    pub calls: u64,
112    /// NEST-6: a dynamic instance's schema asked across the hop
113    /// (`<mount>.<path>.<name>.schema`, once per name while it is kept).
114    pub name_schemas: u64,
115    /// NEST-6: a dynamic instance's schema answered from what the mount kept.
116    pub name_schema_hits: u64,
117    /// NEST-6: dynamic instances whose schema is kept now
118    /// (at most `--child-schema-cache`).
119    pub names_kept: usize,
120}
121
122/// A child's methods are data — its schema, asked at mount — not a Rust
123/// enum: the [`Activation::Methods`] of a [`RemoteChild`].
124#[derive(Debug, Clone, Copy)]
125pub enum ChildMethods {}
126
127impl schemars::JsonSchema for ChildMethods {
128    fn schema_name() -> std::borrow::Cow<'static, str> {
129        "ChildMethods".into()
130    }
131
132    fn json_schema(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
133        schemars::json_schema!({
134            "description": "A child service's methods are data: its schema, asked when it was mounted (`<mount>.schema`)."
135        })
136    }
137}
138
139impl MethodEnumSchema for ChildMethods {
140    fn method_names() -> &'static [&'static str] {
141        &[]
142    }
143
144    fn schema_with_consts() -> Value {
145        serde_json::to_value(schemars::schema_for!(ChildMethods)).unwrap_or(Value::Null)
146    }
147}
148
149struct Inner {
150    shared: Arc<Shared>,
151    schema: PluginSchema,
152    /// NEST-4: every static child below the mount, by dotted path relative
153    /// to it (`a`, `a.b`), each schema as the child published it — its own
154    /// namespace, its grants and roles relative to it, as an in-process
155    /// child's ([`Activation::static_child_schemas`]).
156    nodes: Vec<(String, PluginSchema)>,
157    timings: MountTimings,
158    /// NEST-6: each dynamic instance's schema, asked once per name.
159    names: names::Names,
160}
161
162impl Inner {
163    pub(super) fn new(shared: Arc<Shared>, schema: PluginSchema, nodes: Vec<(String, PluginSchema)>, timings: MountTimings) -> Self {
164        let names = names::Names::new(shared.opts.schema_cache);
165        Self { shared, schema, nodes, timings, names }
166    }
167}
168
169/// An activation in another process (or behind a WebSocket), mounted under
170/// its [`ChildSpec`]'s name. Cheap to clone; the child stops when the last
171/// clone is dropped.
172#[derive(Clone)]
173pub struct RemoteChild {
174    inner: Arc<Inner>,
175}
176
177impl std::fmt::Debug for RemoteChild {
178    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
179        f.debug_struct("RemoteChild").field("spec", &self.inner.shared.spec.to_string()).field("stats", &self.stats()).finish()
180    }
181}
182
183/// One schema as a child published it, read into 0.8's shape.
184fn read_schema(raw: Value) -> Result<PluginSchema, String> {
185    serde_json::from_value(peer::schema(raw)?).map_err(|e| format!("its schema does not read: {e}"))
186}
187
188/// A static child's schema as the mount keeps it (NEST-4): as published,
189/// its grants relative to it — the host qualifies them by the path
190/// ([`super::children::qualified`]), as it does an in-process child's.
191pub(super) fn node_schema(path: &str, raw: Value) -> Result<PluginSchema, String> {
192    read_schema(raw).map_err(|e| format!("its child `{path}`: {e}"))
193}
194
195/// The child's schema as the service keeps it: under the mount name, its
196/// roles' grants and its methods' own grants requalified (`{ns}.m` →
197/// `<mount>.m`). Its static children are kept beside it ([`node_schema`]);
198/// a dynamic child's role (and a peer slot's) stays on it with the slot's
199/// type: the slot a call into it is forwarded through (NEST-6).
200fn mount_schema(name: &str, raw: Value) -> Result<PluginSchema, String> {
201    let mut schema = read_schema(raw)?;
202    if schema.namespace != name {
203        tracing::info!(target: "plexus::child", child = %name, declared = %schema.namespace, "mounted under its mount name, not the namespace it declares");
204    }
205    let prefix = format!("{}.", schema.namespace);
206    let requalify = |g: &String| match g.strip_prefix(&prefix) {
207        Some(m) => format!("{name}.{m}"),
208        None => format!("{name}.{g}"),
209    };
210    schema.roles = schema.roles.iter().map(|(r, gs)| (r.clone(), gs.iter().map(requalify).collect())).collect();
211    for m in schema.methods.iter_mut() {
212        if let Some(g) = m.grant.as_ref() {
213            m.grant = Some(requalify(g));
214        }
215    }
216    schema.namespace = name.to_string();
217    Ok(schema)
218}
219
220impl RemoteChild {
221    /// Start (or dial) the child, ask its `_info` and its schema within
222    /// `opts.timeout`, and keep the connection. Fails naming the child and
223    /// why: it did not start, did not answer, or published a schema the
224    /// service will not mount.
225    pub async fn connect(spec: ChildSpec, opts: ChildOptions) -> Result<Self, ChildError> {
226        let name = spec.name().to_string();
227        let start = |why: String| ChildError::Start(name.clone(), why);
228        if opts.max_calls == 0 || opts.buffer == 0 {
229            return Err(start("max_calls and buffer are at least 1".into()));
230        }
231        let principal = Self::principal_for(&spec, &opts).map_err(start)?;
232        let shared = Shared::new(spec, opts, principal);
233        let (conn, kept, mut timings) = shared.connect_once().await.map_err(start)?;
234        let t = Instant::now();
235        let hash = kept.hash();
236        let read = mount_schema(&name, kept.top).and_then(|schema| {
237            let nodes = kept.nodes.into_iter().map(|(path, raw)| node_schema(&path, raw).map(|s| (path, s))).collect::<Result<Vec<_>, _>>()?;
238            Ok((schema, nodes))
239        });
240        let (schema, nodes) = match read {
241            Ok(s) => s,
242            Err(why) => {
243                conn.shutdown.notify_one();
244                return Err(start(why));
245            }
246        };
247        let _ = shared.mounted_hash.set(hash);
248        shared.install(conn);
249        timings.merge_ms = t.elapsed().as_secs_f64() * 1e3;
250        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(), children = nodes.len(), "child mounted");
251        Ok(Self { inner: Arc::new(Inner::new(shared, schema, nodes, timings)) })
252    }
253
254    #[allow(unused_variables)]
255    fn principal_for(spec: &ChildSpec, opts: &ChildOptions) -> Result<String, String> {
256        #[cfg(feature = "child-ws")]
257        if let (ChildSpec::Ws { .. }, Some(path)) = (spec, &opts.key) {
258            return Ok(ws::principal_of(&ws::read_seed(path)?));
259        }
260        Ok(opts.principal.clone())
261    }
262
263    /// What the seam has seen.
264    pub fn stats(&self) -> ChildStats {
265        let c: &Counters = &self.inner.shared.counters;
266        ChildStats {
267            open: c.open.load(Ordering::Relaxed),
268            unasked: c.unasked.load(Ordering::Relaxed),
269            restarts: c.restarts.load(Ordering::Relaxed),
270            calls: c.calls.load(Ordering::Relaxed),
271            name_schemas: self.inner.names.hops.load(Ordering::Relaxed),
272            name_schema_hits: self.inner.names.hits.load(Ordering::Relaxed),
273            names_kept: self.inner.names.len(c.restarts.load(Ordering::Relaxed)),
274        }
275    }
276
277    /// The process now serving (a stdio child), if one is up.
278    pub fn pid(&self) -> Option<u32> {
279        self.inner.shared.current().and_then(|c| c.pid)
280    }
281
282    /// The mount's name.
283    pub fn name(&self) -> &str {
284        &self.inner.shared.name
285    }
286
287    /// The spec it was mounted from.
288    pub fn spec(&self) -> &ChildSpec {
289        &self.inner.shared.spec
290    }
291
292    /// The hop's `principal`: the service acting, as this child is told.
293    pub fn principal(&self) -> &str {
294        &self.inner.shared.principal
295    }
296
297    /// How long the mount took.
298    pub fn mount_timings(&self) -> MountTimings {
299        self.inner.timings
300    }
301
302    /// Subscriptions routed on the live connection (0 when none is up).
303    pub fn routed(&self) -> usize {
304        self.inner.shared.current().map_or(0, |c| c.routed())
305    }
306
307    /// The hop (spec/12) for a call by `auth`, decided as `reach`: the
308    /// service acts, the caller is named `for`, the verdict is the limit.
309    /// Nothing of the caller's credential.
310    fn hop(&self, conn: &Conn, auth: Option<&AuthContext>, reach: &Reach) -> Value {
311        let for_: Vec<String> = auth.and_then(|a| a.principal()).map(|p| p.to_string()).into_iter().collect();
312        let limit = reach.grant().map(|g| {
313            let grant = match g.as_str().strip_prefix(&format!("{}.", self.name())) {
314                Some(m) => format!("{}.{m}", conn.ns()),
315                None => g.as_str().to_string(),
316            };
317            let held_on: Vec<String> = reach.held_on().iter().map(|s| s.to_string()).collect();
318            json!({ "grant": grant, "held_on": held_on })
319        });
320        json!({ "principal": self.inner.shared.principal, "for": for_, "limit": limit, "call": uuid::Uuid::new_v4().to_string() })
321    }
322
323    /// NEST-4: the kept static child at `path` (dotted, relative to the mount).
324    fn node(&self, path: &str) -> Option<&PluginSchema> {
325        self.inner.nodes.iter().find(|(p, _)| p == path).map(|(_, s)| s)
326    }
327
328    /// NEST-6: where a path below the mount enters a slot, if it does: the
329    /// slot (`<mount>.<parent>.{<slot>}`) and the instance's path below the
330    /// mount (`<parent>.<name>`; through a peer slot, which the path names,
331    /// `<parent>.<slot>.<name>`). The deepest kept level the path starts with
332    /// is the parent: a static child, which the walk kept, wins over a slot.
333    fn slot_of(&self, path: &str) -> Option<(String, String)> {
334        let segs: Vec<&str> = path.split('.').collect();
335        let (n, schema) = (1..segs.len())
336            .rev()
337            .find_map(|n| self.node(&segs[..n].join(".")).map(|s| (n, s)))
338            .unwrap_or((0, &self.inner.schema));
339        let parent = std::iter::once(self.name()).chain(segs[..n].iter().copied()).collect::<Vec<_>>().join(".");
340        let next = segs[n];
341        // NEST-7: a peer slot is named in the path, then the peer's name.
342        if schema.methods.iter().any(|m| m.name == next && matches!(m.role, MethodRole::Peer { .. })) {
343            return Some((crate::plexus::slots::slot_path(&parent, next), segs[..(n + 2).min(segs.len())].join(".")));
344        }
345        let slot = schema.methods.iter().find(|m| matches!(m.role, MethodRole::DynamicChild { .. }))?;
346        Some((crate::plexus::slots::slot_path(&parent, &slot.name), segs[..=n].join(".")))
347    }
348
349    /// A path no kept level answers and no slot is on the way of.
350    fn unreached(&self, method: &str) -> PlexusError {
351        PlexusError::MethodNotFound { activation: self.name().to_string(), method: method.to_string() }
352    }
353
354    /// NEST-6: `<mount>.<path>.schema` where `path` is in a dynamic slot
355    /// (`instance` its name's path): from the kept names, else asked of the
356    /// child once (`{ns}.<path>.schema`, with the caller's hop), kept under
357    /// its path and the `plexus_hash` it came with, and answered from that.
358    /// What the child answers instead of a schema (an unknown name's
359    /// not-found) comes back unchanged and is not kept.
360    async fn name_schema(&self, path: &str, params: &Value, auth: Option<&AuthContext>) -> PlexusStream {
361        let epoch = self.inner.shared.counters.restarts.load(Ordering::Relaxed);
362        if let Some(s) = self.inner.names.get(path, epoch) {
363            return self.schema_stream_of(&s, &s.namespace, params);
364        }
365        self.inner.names.crossed();
366        let items: Vec<PlexusStreamItem> = futures::StreamExt::collect(self.forward(&format!("{path}.schema"), json!({}), auth, None).await).await;
367        let kept = items.iter().find_map(|i| match i {
368            PlexusStreamItem::Data { metadata, content, .. } => Some((metadata.plexus_hash.clone(), content.clone().into_value())),
369            _ => None,
370        });
371        let Some((seen, raw)) = kept else {
372            return Box::pin(futures::stream::iter(items));
373        };
374        match read_schema(raw) {
375            Ok(schema) => {
376                // A restart while it crossed: what came is the new child's.
377                let epoch = self.inner.shared.counters.restarts.load(Ordering::Relaxed);
378                self.inner.names.put(path, schema.clone(), seen, epoch);
379                self.schema_stream_of(&schema, &schema.namespace, params)
380            }
381            Err(_) => Box::pin(futures::stream::iter(items)),
382        }
383    }
384
385    fn schema_stream(&self, params: &Value) -> PlexusStream {
386        self.schema_stream_of(&self.inner.schema, self.name(), params)
387    }
388
389    /// `schema` answered from what the mount kept: nothing crosses the hop
390    /// (spec/12 rule 7). `label` is the content type's namespace.
391    fn schema_stream_of(&self, schema: &PluginSchema, label: &str, params: &Value) -> PlexusStream {
392        let ns = label.to_string();
393        let content = match params.get("method").and_then(Value::as_str) {
394            Some(m) => match schema.methods.iter().find(|x| x.name == m) {
395                Some(ms) => serde_json::to_value(ms).unwrap_or_default(),
396                None => {
397                    let error = plexus_client::RemoteError::MethodNotFound { activation: ns.clone(), method: m.to_string() };
398                    let mut e = PlexusStreamItem::error(meta(&ns), error, false);
399                    if let PlexusStreamItem::Error { message, code, .. } = &mut e {
400                        *message = format!("Method '{m}' not found");
401                        *code = Some("-32602".into());
402                    }
403                    return Box::pin(futures::stream::iter([e]));
404                }
405            },
406            None => serde_json::to_value(schema).unwrap_or_default(),
407        };
408        Box::pin(futures::stream::iter([
409            PlexusStreamItem::Data { metadata: meta(&ns).into(), content_type: format!("{ns}.schema").into(), content: content.into() },
410            PlexusStreamItem::Done { metadata: meta(&ns) },
411        ]))
412    }
413
414    /// `instance`: the path of the dynamic instance the call goes through
415    /// (NEST-6), whose kept schema an item with another `plexus_hash` drops.
416    async fn forward(&self, method: &str, params: Value, auth: Option<&AuthContext>, instance: Option<String>) -> PlexusStream {
417        let shared = &self.inner.shared;
418        let one = |item: PlexusStreamItem| -> PlexusStream { Box::pin(futures::stream::iter([item])) };
419        // RETURNS-47: the verdict is the call's; outside one (a forward no
420        // dispatch admitted) nothing crosses — fail closed, never everywhere.
421        let reach = match super::grant_gate::current_reach() {
422            Ok(reach) => reach,
423            Err(e) => return one(PlexusStreamItem::from_plexus_error(meta(self.name()), &e, false)),
424        };
425        let max = shared.opts.max_calls;
426        if shared.counters.open.fetch_add(1, Ordering::AcqRel) >= max {
427            shared.counters.open.fetch_sub(1, Ordering::AcqRel);
428            return one(too_many(self.name(), max));
429        }
430        let guard = OpenGuard(Arc::clone(&shared.counters));
431        let conn = match shared.ensure().await {
432            Ok(c) => c,
433            Err(item) => return one(item),
434        };
435        shared.counters.calls.fetch_add(1, Ordering::Relaxed);
436        let hop = self.hop(&conn, auth, &reach);
437        let path = format!("{}.{method}", conn.ns());
438        let call = json!({ "method": path, "params": params, "hop": hop });
439        match conn.open(&format!("{}.call", conn.ns()), call, shared.opts.timeout).await {
440            Ok((sid, rx)) => {
441                let generation = reach.generation().cloned();
442                let seen = generation.as_ref().map_or(0, GrantsGeneration::current);
443                let instance = instance.map(|path| (Arc::clone(&self.inner), path));
444                Box::pin(CallStream { rx, sid, conn, over: false, _guard: guard, reach, generation, seen, name: self.name().to_string(), instance })
445            }
446            Err(item) => one(item),
447        }
448    }
449}
450
451/// One open call, counted until its stream ends or is dropped.
452struct OpenGuard(Arc<Counters>);
453
454impl Drop for OpenGuard {
455    fn drop(&mut self) {
456        self.0.open.fetch_sub(1, Ordering::AcqRel);
457    }
458}
459
460/// The stream the service hands its caller: the child's items, in order,
461/// until the first terminal one; dropped before it, the child is told.
462struct CallStream {
463    rx: mpsc::Receiver<PlexusStreamItem>,
464    sid: SubKey,
465    conn: Arc<Conn>,
466    over: bool,
467    _guard: OpenGuard,
468    /// The gate's verdict at the open, asked again when the grants
469    /// generation moves (BIDIR-1 `regate = generation`, BIDIR-8).
470    reach: Reach,
471    generation: Option<GrantsGeneration>,
472    seen: u64,
473    name: String,
474    /// NEST-6: the dynamic instance the call goes through, and the mount
475    /// whose kept schema of it an item with another `plexus_hash` drops.
476    instance: Option<(Arc<Inner>, String)>,
477}
478
479impl CallStream {
480    /// The grant revoked mid-stream: the caller's last item.
481    fn revoked(&self) -> PlexusStreamItem {
482        let grant = self.reach.grant().map(|g| g.as_str().to_string()).unwrap_or_default();
483        let error = plexus_client::RemoteError::Forbidden {
484            reason: plexus_client::DenyReason::MissingGrant {
485                grant: grant.clone(),
486                scope: "*".into(),
487                roles: Vec::new(),
488                held_on: Vec::new(),
489            },
490        };
491        let mut item = PlexusStreamItem::error(meta(&self.name), error, false);
492        if let PlexusStreamItem::Error { message, .. } = &mut item {
493            *message = format!("Forbidden: `{grant}` is no longer held — the call's grant moved while it ran");
494        }
495        item
496    }
497}
498
499impl Stream for CallStream {
500    type Item = PlexusStreamItem;
501
502    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
503        if self.over {
504            return Poll::Ready(None);
505        }
506        match self.rx.poll_recv(cx) {
507            Poll::Ready(Some(item)) => {
508                if let (Some((inner, path)), Some(m)) = (&self.instance, item.metadata()) {
509                    inner.names.observe(path, &m.plexus_hash);
510                }
511                let terminal = matches!(item, PlexusStreamItem::Done { .. } | PlexusStreamItem::Error { .. });
512                let moved = self.generation.as_ref().map(GrantsGeneration::current).filter(|g| *g != self.seen);
513                if let (false, Some(g)) = (terminal, moved) {
514                    self.seen = g;
515                    if self.reach.current().is_none() {
516                        let sid = self.sid.clone();
517                        self.conn.unsubscribe(&sid);
518                        self.over = true;
519                        return Poll::Ready(Some(self.revoked()));
520                    }
521                }
522                if terminal {
523                    self.over = true;
524                }
525                Poll::Ready(Some(item))
526            }
527            Poll::Ready(None) => {
528                // The channel closed with no terminal item: the link went.
529                self.over = true;
530                Poll::Ready(Some(unavailable(&self.name, "the connection closed")))
531            }
532            Poll::Pending => Poll::Pending,
533        }
534    }
535}
536
537impl Drop for CallStream {
538    fn drop(&mut self) {
539        if !self.over {
540            self.conn.unsubscribe(&self.sid);
541        }
542    }
543}
544
545#[async_trait]
546impl Activation for RemoteChild {
547    type Methods = ChildMethods;
548
549    fn namespace(&self) -> &str {
550        self.name()
551    }
552
553    fn version(&self) -> &str {
554        &self.inner.schema.version
555    }
556
557    fn description(&self) -> &str {
558        &self.inner.schema.description
559    }
560
561    fn long_description(&self) -> Option<&str> {
562        self.inner.schema.long_description.as_deref()
563    }
564
565    fn methods(&self) -> Vec<&str> {
566        self.inner.schema.methods.iter().map(|m| m.name.as_str()).collect()
567    }
568
569    fn method_help(&self, method: &str) -> Option<String> {
570        self.inner.schema.methods.iter().find(|m| m.name == method).map(|m| m.description.clone())
571    }
572
573    async fn call(&self, method: &str, params: Value, auth: Option<&AuthContext>, _raw: Option<&crate::request::RawRequestContext>) -> Result<PlexusStream, PlexusError> {
574        if method == "schema" {
575            return Ok(self.schema_stream(&params));
576        }
577        // NEST-4: a static child's schema, from the kept tree.
578        if let Some(path) = method.strip_suffix(".schema") {
579            if let Some(s) = self.node(path) {
580                return Ok(self.schema_stream_of(s, &s.namespace, &params));
581            }
582            // NEST-6: an instance in a dynamic slot: the one schema that
583            // crosses the hop, once per name (spec/12 rule 7's exception).
584            return match self.slot_of(path) {
585                Some(_) => Ok(self.name_schema(path, &params, auth).await),
586                None => Err(self.unreached(method)),
587            };
588        }
589        let found = match method.rsplit_once('.') {
590            // NEST-4: a static child's method, by its path.
591            Some((path, name)) => match self.node(path) {
592                Some(s) => s.methods.iter().find(|m| m.name == name && m.role == MethodRole::Rpc),
593                // NEST-6: a method of an instance in a dynamic slot: the
594                // host's gate decided it on the slot grant; forwarded as
595                // any call, the child deciding again and answering an
596                // unknown name with its own not-found.
597                None => match self.slot_of(path) {
598                    Some((_, instance)) => return Ok(self.forward(method, params, auth, Some(instance)).await),
599                    None => return Err(self.unreached(method)),
600                },
601            },
602            None => self.inner.schema.methods.iter().find(|m| m.name == method && m.role == MethodRole::Rpc),
603        };
604        let Some(m) = found else {
605            return Err(PlexusError::MethodNotFound { activation: self.name().to_string(), method: method.to_string() });
606        };
607        // BIDIR-6: a hop forwards no input half yet; the far side would wait
608        // for items that never come.
609        if m.input.is_some() {
610            return Err(PlexusError::ExecutionError(format!(
611                "`{}.{method}` takes an input stream, and a hop to a remote child does not forward one yet",
612                self.name()
613            )));
614        }
615        Ok(self.forward(method, params, auth, None).await)
616    }
617
618    /// Nothing of its own on the socket: a child is reached through the
619    /// service's `{service}.call`, behind its gate.
620    fn into_rpc_methods(self) -> jsonrpsee::Methods {
621        jsonrpsee::Methods::new()
622    }
623
624    fn plugin_schema(&self) -> PluginSchema {
625        self.inner.schema.clone()
626    }
627
628    /// NEST-4: the kept tree — the host gates, lists and describes a mounted
629    /// child's children by their whole path, as it does an in-process
630    /// child's (MACRO-20, [`super::children`]).
631    fn static_child_schemas(&self) -> Vec<(String, PluginSchema)> {
632        self.inner.nodes.clone()
633    }
634}
635
636#[async_trait]
637impl ChildRouter for RemoteChild {
638    fn router_namespace(&self) -> &str {
639        self.name()
640    }
641
642    async fn router_call(&self, method: &str, params: Value, auth: Option<&AuthContext>, raw: Option<&crate::request::RawRequestContext>) -> Result<PlexusStream, PlexusError> {
643        Activation::call(self, method, params, auth, raw).await
644    }
645
646    async fn get_child(&self, _name: &str) -> Option<Box<dyn ChildRouter>> {
647        None
648    }
649
650    fn router_schema(&self) -> Option<PluginSchema> {
651        Some(self.inner.schema.clone())
652    }
653
654    fn router_static_child_schemas(&self) -> Vec<(String, PluginSchema)> {
655        self.inner.nodes.clone()
656    }
657}
658
659#[cfg(test)]
660mod tests {
661    use super::*;
662
663    fn raw(methods: Value, roles: Value) -> Value {
664        json!({ "namespace": "stub", "version": "0.1.0", "description": "d", "self_hash": "h", "hash": "h", "methods": methods, "roles": roles })
665    }
666
667    fn m(name: &str) -> Value {
668        json!({ "name": name, "description": "", "hash": "x", "streaming": false, "bidirectional": false })
669    }
670
671    /// RETURNS-36 (review #6): no guessing — a method that states neither
672    /// `cardinality` (0.8) nor `streaming` (0.7.0) is refused, naming it, as
673    /// plexus-protocol's `cardinalityOf` refuses it.
674    #[test]
675    fn a_method_stating_neither_cardinality_nor_streaming_is_refused() {
676        let silent = json!({ "name": "quiet", "description": "", "hash": "x" });
677        let e = mount_schema("echo", raw(json!([m("echo"), silent]), json!({}))).unwrap_err();
678        assert!(e.contains("`quiet`") && e.contains("neither cardinality"), "{e}");
679    }
680
681    #[test]
682    fn the_mount_name_wins_and_roles_are_requalified() {
683        let s = mount_schema("echo", raw(json!([m("echo"), m("shout")]), json!({ "viewer": ["stub.echo"], "editor": ["stub.echo", "stub.shout"] }))).unwrap();
684        assert_eq!(s.namespace, "echo");
685        assert_eq!(s.roles["viewer"], vec!["echo.echo".to_string()]);
686        assert_eq!(s.roles["editor"], vec!["echo.echo".to_string(), "echo.shout".to_string()]);
687    }
688
689    /// NEST-4: a child with children mounts; its child roles stay on it.
690    #[test]
691    fn a_child_with_children_mounts_and_its_method_grants_are_requalified() {
692        let mut inner = m("inner");
693        inner["role"] = json!({ "kind": "static_child" });
694        let mut own = m("echo");
695        own["grant"] = json!("stub.echo");
696        let s = mount_schema("echo", raw(json!([own, inner]), json!({}))).unwrap();
697        assert_eq!(s.methods[0].grant.as_deref(), Some("echo.echo"));
698        assert_eq!(s.methods[1].role, MethodRole::StaticChild);
699        let mut slot = m("item");
700        slot["role"] = json!({ "kind": "dynamic_child", "list_method": "names" });
701        let nested = raw(json!([m("echo"), s_inner(), slot]), json!({}));
702        assert_eq!(link::static_children(&nested), vec!["inner".to_string()], "a dynamic child is a slot, not walked");
703        // A service's root says its activations in `children` alone.
704        let mut root = raw(json!([m("call")]), json!({}));
705        root["children"] = json!([{ "namespace": "greeter", "description": "", "hash": "g" }]);
706        assert_eq!(link::static_children(&root), vec!["greeter".to_string()]);
707    }
708
709    fn s_inner() -> Value {
710        let mut inner = m("inner");
711        inner["role"] = json!({ "kind": "static_child" });
712        inner
713    }
714
715    /// NEST-4: the tree's hash moves with a grandchild's.
716    #[test]
717    fn the_tree_hash_covers_every_level() {
718        let top = raw(json!([m("echo")]), json!({}));
719        let flat = link::Kept { top: top.clone(), nodes: vec![] };
720        assert_eq!(flat.hash(), link::schema_hash(&top), "a flat child's hash is its schema's, as before");
721        let mut c = raw(json!([m("m")]), json!({}));
722        let one = link::Kept { top: top.clone(), nodes: vec![("a.b".into(), c.clone())] }.hash();
723        c["hash"] = json!("other");
724        let two = link::Kept { top, nodes: vec![("a.b".into(), c)] }.hash();
725        assert_ne!(one, two);
726    }
727
728    #[test]
729    fn typed_error_fields_cross_whole() {
730        let item = unavailable("echo", "gone");
731        let v = serde_json::to_value(&item).unwrap();
732        assert_eq!(v["error_kind"], "child_unavailable");
733        assert_eq!(v["code"], "child_unavailable");
734        assert_eq!(v["child"], "echo");
735        let back: PlexusStreamItem = serde_json::from_value(v.clone()).unwrap();
736        assert_eq!(back.error_kind(), Some("child_unavailable"));
737        assert_eq!(serde_json::to_value(&back).unwrap(), v);
738        // An error spec/05 gives no kind carries no `error_kind`: its keys
739        // are spec/05's four and RETURNS-6's typed `error` (RETURNS-36).
740        let plain = PlexusStreamItem::error(meta("x"), plexus_client::RemoteError::Execution { message: "m".into() }, false);
741        let pv = serde_json::to_value(&plain).unwrap();
742        let keys: Vec<_> = pv.as_object().unwrap().keys().cloned().collect();
743        assert_eq!(keys, ["code", "error", "message", "metadata", "recoverable", "type"]);
744    }
745}