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//! # A child calls its service back (NEST-11)
53//!
54//! While a call is open into the child, the child may call the service back
55//! on the same connection — `_host.call {method, params, under}`, `under`
56//! the forwarded call's `hop.call` (plexus-wire spec/14). The service routes
57//! it through its own routing and gate as that call's caller, within that
58//! call's reach, and ends it when that call ends; outside a live call it
59//! answers a schema only (`upcall.rs`). The far side in Rust calls back
60//! through [`host()`], a `Transport` a generated client takes.
61
62// RETURNS-47: the far side in Rust — an activation served as a child, each
63// call in its hop's context.
64mod host;
65mod link;
66// NEST-6: one dynamic instance's schema, kept per name.
67mod names;
68// RETURNS-36: a peer on plexus-wire's spec as main wrote it, read as 0.8.
69mod peer;
70mod spec;
71// NEST-11: a child calls its service back, under a call it serves.
72mod upcall;
73// KEEL-19: a principal a verifier proved, as a type.
74mod proven;
75#[cfg(feature = "child-ws")]
76mod ws;
77#[cfg(feature = "clap")]
78mod args;
79// VISION-5 (LOCAL-5): dial-in peers (the accepting side) and dial-out (the
80// side with no listening port).
81mod dial_in;
82#[cfg(feature = "child-ws")]
83mod dial_out;
84// NEST-25: first contact — the pairing code, the node's known hosts.
85pub mod pairing;
86
87use std::pin::Pin;
88use std::sync::atomic::Ordering;
89use std::sync::Arc;
90use std::task::{Context, Poll};
91use std::time::Instant;
92
93use async_trait::async_trait;
94use futures::Stream;
95use plexus_auth_core::grants::{GrantsGeneration, Reach};
96use serde_json::{json, Value};
97use tokio::sync::mpsc;
98
99pub use host::{host, serve_child, serve_child_on, serve_child_proven, serve_child_stdio, serve_child_with, ChildPeer, HostTransport, ServeChild};
100pub use upcall::{Consented, HOST_CALL, HOST_CALL_UNSUB};
101pub use link::{MountTimings, KEYED_MOUNT_NEEDS_A_KEY};
102pub use spec::{check_ws_url, is_insecure_ws, is_loopback_host, parse_duration, Backoff, ChildError, ChildOptions, ChildSpec, INSECURE_TRANSPORT};
103#[cfg(feature = "clap")]
104pub use args::ChildArgs;
105pub use dial_in::{possession_input, Admission, Decision, Offer, OfferRefused, PeerEvent, PeerInfo, PeerRoles, PeerSocket, Peers, PeersMethods, OFFER_PENDING};
106#[cfg(feature = "child-ws")]
107pub use dial_out::{key_principal, DialOut, DialState, Exposed, FirstContact};
108#[cfg(feature = "child-ws")]
109pub use ws::serve_child_ws;
110pub use proven::{dial_proof, KeyedUpgrade, Proven, CHILD_DIAL_AGENT, UPGRADE_LEDGER_MAX};
111
112use link::{meta, too_many, unavailable, Conn, Counters, Shared, SubKey};
113
114use super::auth::AuthContext;
115use super::method_enum::MethodEnumSchema;
116use super::plexus::{Activation, ChildRouter, PlexusError};
117use super::schema::{MethodRole, PluginSchema};
118use super::streaming::PlexusStream;
119use super::types::PlexusStreamItem;
120
121/// DYNAUTH-8 (TM-3): who a child proved it was at its mount — what a
122/// restart is held to. Its `_info`'s `backend`, and on `wss://` the key its
123/// certificate holds (sha256 of the SubjectPublicKeyInfo, hex): a renewed
124/// certificate over the same key is the same peer; a new key is not. A
125/// peer's own Ed25519 key, proved at `_info` over a nonce, joins it
126/// (DYNAUTH-5): a restart proving another key is refused as one proving
127/// another certificate key is.
128#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
129pub struct PeerIdentity {
130    /// The backend its `_info` names.
131    pub backend: String,
132    /// On `wss://`: sha256 of its certificate's public key, hex.
133    #[serde(default, skip_serializing_if = "Option::is_none")]
134    pub tls_key: Option<String>,
135    /// DYNAUTH-5: the Ed25519 key it proved at `_info` (`key:<hex>`), if it
136    /// proved one — what a peer token is addressed and bound to.
137    #[serde(default, skip_serializing_if = "Option::is_none")]
138    pub key: Option<String>,
139}
140
141impl PeerIdentity {
142    fn of(conn: &Conn) -> Self {
143        Self { backend: conn.ns().to_string(), tls_key: conn.tls_key.get().cloned(), key: conn.peer_key.get().cloned() }
144    }
145}
146
147impl std::fmt::Display for PeerIdentity {
148    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
149        write!(f, "backend `{}`", self.backend)?;
150        match &self.tls_key {
151            Some(k) => write!(f, ", TLS key {}", &k[..k.len().min(16)]),
152            None => write!(f, ", no TLS key"),
153        }?;
154        match &self.key {
155            Some(k) => write!(f, ", key {}", &k[..k.len().min(20)]),
156            None => Ok(()),
157        }
158    }
159}
160
161/// What the seam has seen of one child.
162#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
163pub struct ChildStats {
164    /// Calls open now.
165    pub open: usize,
166    /// Items the child sent for a call it was not given (dropped).
167    pub unasked: u64,
168    /// Times the child was started (or dialed) again after it went.
169    pub restarts: u64,
170    /// Calls forwarded, in all.
171    pub calls: u64,
172    /// NEST-6: a dynamic instance's schema asked across the hop
173    /// (`<mount>.<path>.<name>.schema`, once per name while it is kept).
174    pub name_schemas: u64,
175    /// NEST-6: a dynamic instance's schema answered from what the mount kept.
176    pub name_schema_hits: u64,
177    /// NEST-6: dynamic instances whose schema is kept now
178    /// (at most `--child-schema-cache`).
179    pub names_kept: usize,
180    /// NEST-11: calls the child made back into its service, in all.
181    pub calls_back: u64,
182    /// NEST-12: whether a live connection to the child is up now.
183    pub up: bool,
184}
185
186/// A child's methods are data — its schema, asked at mount — not a Rust
187/// enum: the [`Activation::Methods`] of a [`RemoteChild`].
188#[derive(Debug, Clone, Copy)]
189pub enum ChildMethods {}
190
191impl schemars::JsonSchema for ChildMethods {
192    fn schema_name() -> std::borrow::Cow<'static, str> {
193        "ChildMethods".into()
194    }
195
196    fn json_schema(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
197        schemars::json_schema!({
198            "description": "A child service's methods are data: its schema, asked when it was mounted (`<mount>.schema`)."
199        })
200    }
201}
202
203impl MethodEnumSchema for ChildMethods {
204    fn method_names() -> &'static [&'static str] {
205        &[]
206    }
207
208    fn schema_with_consts() -> Value {
209        serde_json::to_value(schemars::schema_for!(ChildMethods)).unwrap_or(Value::Null)
210    }
211}
212
213struct Inner {
214    shared: Arc<Shared>,
215    schema: PluginSchema,
216    /// NEST-4: every static child below the mount, by dotted path relative
217    /// to it (`a`, `a.b`), each schema as the child published it — its own
218    /// namespace, its grants and roles relative to it, as an in-process
219    /// child's ([`Activation::static_child_schemas`]).
220    nodes: Vec<(String, PluginSchema)>,
221    timings: MountTimings,
222    /// NEST-6: each dynamic instance's schema, asked once per name.
223    names: names::Names,
224    /// NEST-16: what the child needs of its service: its own schema's
225    /// `needs` and every static child's, as one list (`None`: none declares).
226    needs: Option<Vec<crate::plexus::schema::Need>>,
227}
228
229impl Inner {
230    pub(super) fn new(shared: Arc<Shared>, schema: PluginSchema, nodes: Vec<(String, PluginSchema)>, timings: MountTimings) -> Self {
231        let names = names::Names::new(shared.opts.schema_cache);
232        let declared = schema.needs.is_some() || nodes.iter().any(|(_, n)| n.needs.is_some());
233        let mut needs: Vec<crate::plexus::schema::Need> = schema.needs.iter().chain(nodes.iter().filter_map(|(_, n)| n.needs.as_ref())).flatten().cloned().collect();
234        needs.sort();
235        needs.dedup_by(|a, b| a.method == b.method);
236        let needs = declared.then_some(needs);
237        Self { shared, schema, nodes, timings, names, needs }
238    }
239}
240
241/// An activation in another process (or behind a WebSocket), mounted under
242/// its [`ChildSpec`]'s name. Cheap to clone; the child stops when the last
243/// clone is dropped.
244#[derive(Clone)]
245pub struct RemoteChild {
246    inner: Arc<Inner>,
247}
248
249impl std::fmt::Debug for RemoteChild {
250    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
251        f.debug_struct("RemoteChild").field("spec", &self.inner.shared.spec.to_string()).field("insecure", &self.insecure()).field("stats", &self.stats()).finish()
252    }
253}
254
255/// One schema as a child published it, read into 0.8's shape.
256fn read_schema(raw: Value) -> Result<PluginSchema, String> {
257    serde_json::from_value(peer::schema(raw)?).map_err(|e| format!("its schema does not read: {e}"))
258}
259
260/// A static child's schema as the mount keeps it (NEST-4): as published,
261/// its grants relative to it — the host qualifies them by the path
262/// ([`super::children::qualified`]), as it does an in-process child's.
263pub(super) fn node_schema(path: &str, raw: Value) -> Result<PluginSchema, String> {
264    read_schema(raw).map_err(|e| format!("its child `{path}`: {e}"))
265}
266
267/// The child's schema as the service keeps it: under the mount name, its
268/// roles' grants and its methods' own grants requalified (`{ns}.m` →
269/// `<mount>.m`). Its static children are kept beside it ([`node_schema`]);
270/// a dynamic child's role (and a peer slot's) stays on it with the slot's
271/// type: the slot a call into it is forwarded through (NEST-6).
272fn mount_schema(name: &str, raw: Value) -> Result<PluginSchema, String> {
273    let mut schema = read_schema(raw)?;
274    if schema.namespace != name {
275        tracing::info!(target: "plexus::child", child = %name, declared = %schema.namespace, "mounted under its mount name, not the namespace it declares");
276    }
277    let prefix = format!("{}.", schema.namespace);
278    let requalify = |g: &String| match g.strip_prefix(&prefix) {
279        Some(m) => format!("{name}.{m}"),
280        None => format!("{name}.{g}"),
281    };
282    schema.roles = schema.roles.iter().map(|(r, gs)| (r.clone(), gs.iter().map(requalify).collect())).collect();
283    for m in schema.methods.iter_mut() {
284        if let Some(g) = m.grant.as_ref() {
285            m.grant = Some(requalify(g));
286        }
287    }
288    schema.namespace = name.to_string();
289    Ok(schema)
290}
291
292impl RemoteChild {
293    /// Start (or dial) the child, ask its `_info` and its schema within
294    /// `opts.timeout`, and keep the connection. Fails naming the child and
295    /// why: it did not start, did not answer, or published a schema the
296    /// service will not mount.
297    pub async fn connect(spec: ChildSpec, opts: ChildOptions) -> Result<Self, ChildError> {
298        let name = spec.name().to_string();
299        let start = |why: String| ChildError::Start(name.clone(), why);
300        if opts.max_calls == 0 || opts.buffer == 0 {
301            return Err(start("max_calls and buffer are at least 1".into()));
302        }
303        let principal = Self::principal_for(&spec, &opts).map_err(start)?;
304        let shared = Shared::new(spec, opts, principal);
305        let (conn, kept, mut timings) = shared.connect_once().await.map_err(start)?;
306        let t = Instant::now();
307        let hash = kept.hash();
308        let read = mount_schema(&name, kept.top).and_then(|schema| {
309            let nodes = kept.nodes.into_iter().map(|(path, raw)| node_schema(&path, raw).map(|s| (path, s))).collect::<Result<Vec<_>, _>>()?;
310            Ok((schema, nodes))
311        });
312        let (schema, nodes) = match read {
313            Ok(s) => s,
314            Err(why) => {
315                conn.shutdown.notify_one();
316                return Err(start(why));
317            }
318        };
319        let _ = shared.mounted_hash.set(hash);
320        let _ = shared.identity.set(PeerIdentity::of(&conn));
321        shared.install(conn);
322        timings.merge_ms = t.elapsed().as_secs_f64() * 1e3;
323        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");
324        if let ChildSpec::Ws { url, .. } = &shared.spec {
325            if is_insecure_ws(url) {
326                tracing::warn!(target: "plexus::child", child = %name, %url, "insecure: mounted over plain ws:// beyond loopback (transport.insecure_ws); its hops and key proof cross in clear");
327            }
328        }
329        let inner = Inner::new(shared, schema, nodes, timings);
330        // NEST-16: the child's calls back are held to what it needs.
331        inner.shared.upcalls.set_needs(inner.needs.as_deref());
332        Ok(Self { inner: Arc::new(inner) })
333    }
334
335    #[allow(unused_variables)]
336    fn principal_for(spec: &ChildSpec, opts: &ChildOptions) -> Result<String, String> {
337        #[cfg(feature = "child-ws")]
338        if let (ChildSpec::Ws { .. }, Some(path)) = (spec, &opts.key) {
339            return Ok(ws::principal_of(&ws::read_seed(path)?));
340        }
341        Ok(opts.principal.clone())
342    }
343
344    /// What the seam has seen.
345    pub fn stats(&self) -> ChildStats {
346        let c: &Counters = &self.inner.shared.counters;
347        ChildStats {
348            open: c.open.load(Ordering::Relaxed),
349            unasked: c.unasked.load(Ordering::Relaxed),
350            restarts: c.restarts.load(Ordering::Relaxed),
351            calls: c.calls.load(Ordering::Relaxed),
352            name_schemas: self.inner.names.hops.load(Ordering::Relaxed),
353            name_schema_hits: self.inner.names.hits.load(Ordering::Relaxed),
354            names_kept: self.inner.names.len(c.restarts.load(Ordering::Relaxed)),
355            calls_back: self.inner.shared.upcalls.made.load(Ordering::Relaxed),
356            up: self.inner.shared.is_up(),
357        }
358    }
359
360    /// DYNAUTH-8 (TM-3): who the child proved it was when it was mounted —
361    /// pinned for the life of this mount: a restart (or redial) that proves
362    /// another is refused for good ([`RemoteChild::dead`]).
363    pub fn identity(&self) -> Option<&PeerIdentity> {
364        self.inner.shared.identity.get()
365    }
366
367    /// DYNAUTH-5: hold the child's calls back to the needs an admin
368    /// consented to, each on its scopes (`None`: no consent kept — every
369    /// declared need, as NEST-16 has it). A declared need not consented is
370    /// refused `forbidden` (`not_needed`), saying so.
371    pub fn set_consent(&self, consent: Option<Vec<Consented>>) {
372        self.inner.shared.upcalls.set_consent(consent);
373    }
374
375    /// DYNAUTH-5: the consent this mount holds its child's calls back to.
376    pub fn consent(&self) -> Option<Vec<Consented>> {
377        self.inner.shared.upcalls.consent().map(|c| c.to_vec())
378    }
379
380    /// DYNAUTH-7: revoke the child: from now no call is forwarded to it (so
381    /// no token is minted for it), and every call it is making back ends
382    /// with one error item saying `why`. A token already in its hand lives
383    /// out its `exp` (≤ 60 s) at a peer that verifies without asking.
384    ///
385    /// KEEL-59: and every call open into it ends with one `child_unavailable`
386    /// item, `revoked: <why>`, the child told to stop each (`call_unsub`), as
387    /// a dialed-in node's and an in-process peer's do.
388    pub fn revoke(&self, why: &str) {
389        self.inner.shared.upcalls.revoke(why);
390        self.inner.shared.stop(&format!("revoked: {why}"));
391        tracing::warn!(target: "plexus::audit", child = %self.name(), %why, "child revoked");
392    }
393
394    /// KEEL-59: cut the child off (`dyn.disconnect`): every call open into
395    /// it ends with one `child_unavailable` item saying `why`, the child is
396    /// told to stop each (`call_unsub`), every call it is making back under
397    /// them ends, and nothing more is forwarded to it. The first `why`
398    /// stands; a revoke after it is still recorded.
399    pub fn stop(&self, why: &str) {
400        let shared = &self.inner.shared;
401        shared.stop(why);
402        shared.upcalls.end_all(why);
403        tracing::info!(target: "plexus::child", child = %self.name(), %why, "child cut off: its calls ended");
404    }
405
406    /// KEEL-59: why the child was cut off ([`RemoteChild::stop`],
407    /// [`RemoteChild::revoke`]), if it was.
408    pub fn stopped(&self) -> Option<String> {
409        self.inner.shared.stopped().map(str::to_string)
410    }
411
412    /// DYNAUTH-7: why the child is revoked, if it is.
413    pub fn revoked(&self) -> Option<String> {
414        self.inner.shared.upcalls.revoked()
415    }
416
417    /// KEEL-19: may this child, presenting `presented` (a token minted for a
418    /// call into it), have it exchanged for one that reaches `need` — a path
419    /// of its service (`dyn.peer.b.forecast`), presented to the audience as
420    /// `forwarded` (the method in the audience's own terms)? Decided by the
421    /// one function its calls back are decided by (`Upcalls::decide`):
422    /// not revoked, `need` declared and consented, and held by the token.
423    /// Answers the exchanged token's scope: `forwarded` on each scope both
424    /// the token holds `need`'s grant on and the consent holds.
425    pub fn may_exchange(&self, need: &str, forwarded: &str, presented: &crate::plexus::peer_token::PeerClaims) -> Result<Vec<String>, String> {
426        if self.peer_key() != Some(presented.aud.as_str()) {
427            return Err(format!("the token presented is not `{}`'s", self.name()));
428        }
429        let up = &self.inner.shared.upcalls;
430        let svc = up.host().and_then(|h| h.upgrade()).ok_or_else(|| format!("`{}`'s service is not known yet", self.name()))?;
431        let decided = up.decide(need, Some((&svc, presented))).map_err(|(_, said)| said)?;
432        let Some(upcall::Decided { held: Some(held), .. }) = decided else {
433            return Err(format!("`{need}` is not among `{}`'s needs", self.name()));
434        };
435        Ok(held.iter().map(|s| format!("{forwarded}@{s}")).collect())
436    }
437
438    /// DYNAUTH-5: the Ed25519 key the child proved at its mount
439    /// (`key:<hex>`), if it proved one; pinned with [`Self::identity`].
440    pub fn peer_key(&self) -> Option<&str> {
441        self.identity().and_then(|i| i.key.as_deref())
442    }
443
444    /// NEST-12: whether a live connection to the child is up now.
445    pub fn is_up(&self) -> bool {
446        self.inner.shared.is_up()
447    }
448
449    /// NEST-12: why the child will never be mounted again under this
450    /// mount, if it will not — a restart published another schema
451    /// (`"schema changed; restart the service"`): a fresh
452    /// [`RemoteChild::connect`] mounts the new one.
453    pub fn dead(&self) -> Option<String> {
454        self.inner.shared.dead()
455    }
456
457    /// NEST-12: why the child is down, when it is — its last connection's
458    /// end, the last start that failed, or why it will never be mounted
459    /// again; `None` while it is up.
460    pub fn why_down(&self) -> Option<String> {
461        self.inner.shared.why_down()
462    }
463
464    /// NEST-12: bring the child up now if it is down — start (or redial) it
465    /// within its [`Backoff`], as the next call would. `Err`: why it is not
466    /// up (and [`RemoteChild::dead`] says whether it never will be).
467    pub async fn up(&self) -> Result<(), String> {
468        match self.inner.shared.ensure().await {
469            Ok(_) => Ok(()),
470            Err(PlexusStreamItem::Error { message, error, .. }) => Err(match error {
471                plexus_client::RemoteError::ChildUnavailable { reason, .. } => reason,
472                _ => message,
473            }),
474            Err(other) => Err(format!("{other:?}")),
475        }
476    }
477
478    /// NEST-16: what the child's schema says it needs of the service it is
479    /// mounted in (`None`: it declares nothing).
480    pub fn needs(&self) -> Option<&[crate::plexus::schema::Need]> {
481        self.inner.needs.as_deref()
482    }
483
484    /// NEST-11: forwarded calls open now that the child may call back under.
485    pub fn calls_open_back(&self) -> usize {
486        self.inner.shared.upcalls.open_now()
487    }
488
489    /// The schema hash this mount took, as the child published it (its
490    /// whole tree's, NEST-4).
491    pub fn mounted_hash(&self) -> &str {
492        self.inner.shared.mounted_hash.get().map(String::as_str).unwrap_or_default()
493    }
494
495    /// The process now serving (a stdio child), if one is up.
496    pub fn pid(&self) -> Option<u32> {
497        self.inner.shared.current().and_then(|c| c.pid)
498    }
499
500    /// The mount's name.
501    pub fn name(&self) -> &str {
502        &self.inner.shared.name
503    }
504
505    /// KEEL-7: whether the mount is plain `ws://` beyond loopback — dialed
506    /// only because `transport.insecure_ws` allowed it, every hop and proof
507    /// on it in clear. Said wherever the mount is listed.
508    pub fn insecure(&self) -> bool {
509        matches!(&self.inner.shared.spec, ChildSpec::Ws { url, .. } if is_insecure_ws(url))
510    }
511
512    /// The spec it was mounted from.
513    pub fn spec(&self) -> &ChildSpec {
514        &self.inner.shared.spec
515    }
516
517    /// The hop's `principal`: the service acting, as this child is told.
518    pub fn principal(&self) -> &str {
519        &self.inner.shared.principal
520    }
521
522    /// How long the mount took.
523    pub fn mount_timings(&self) -> MountTimings {
524        self.inner.timings
525    }
526
527    /// Subscriptions routed on the live connection (0 when none is up).
528    pub fn routed(&self) -> usize {
529        self.inner.shared.current().map_or(0, |c| c.routed())
530    }
531
532    /// The hop (spec/12) for a call by `auth`, decided as `reach`: the
533    /// service acts, the caller is named `for`, the verdict is the limit.
534    /// Nothing of the caller's credential.
535    ///
536    /// ONE-7: a call the service's gate admitted at a door — an address
537    /// scope, not `*` ([`super::grant_gate::is_door`]) — carries it as
538    /// `limit.door`: the address scope of exactly the call the child serves,
539    /// in its terms (`/{ns}.{method}`), for `limit.grant` alone. Never as
540    /// `held_on: ["*"]`: `held_on` stays the data scopes the caller holds the
541    /// grant on (`[]` for one holding only addresses).
542    ///
543    /// Review M1: `limit.door_own: true` beside it when the door was the
544    /// method's own grant at its address ([`crate::call::CallContext`]'s
545    /// recorded door) — what lets the far side run a whole-activation method
546    /// on it; absent when a slot's whole grant (`dyn.{peer}`) opened it.
547    fn hop(&self, conn: &Conn, auth: Option<&AuthContext>, reach: &Reach, method: &str, door: Option<bool>) -> (Value, String) {
548        let for_: Vec<String> = auth.and_then(|a| a.principal()).map(|p| p.to_string()).into_iter().collect();
549        let limit = reach.grant().map(|g| {
550            let grant = match g.as_str().strip_prefix(&format!("{}.", self.name())) {
551                Some(m) => format!("{}.{m}", conn.ns()),
552                // NEST-12: a grant decided above the mount — the mount is a
553                // peer reached through a slot of its service (`dyn.{peer}`,
554                // or a literal `dyn.peer.<name>.<method>`): the verdict
555                // covers this method, said in the child's terms.
556                None => format!("{}.{method}", conn.ns()),
557            };
558            let held_on: Vec<String> = reach.held_on().iter().map(|s| s.to_string()).collect();
559            match door {
560                Some(true) => json!({ "grant": grant, "held_on": held_on, "door": format!("/{}.{method}", conn.ns()), "door_own": true }),
561                Some(false) => json!({ "grant": grant, "held_on": held_on, "door": format!("/{}.{method}", conn.ns()) }),
562                None => json!({ "grant": grant, "held_on": held_on }),
563            }
564        });
565        let call = uuid::Uuid::new_v4().to_string();
566        (json!({ "principal": self.inner.shared.principal, "for": for_, "limit": limit, "call": call }), call)
567    }
568
569    /// ONE-7: the call the service's gate admitted this forward at a door
570    /// — the activation held at an address, not on `*`
571    /// ([`super::grant_gate::is_door`]) — when that call is this one: its
572    /// grant the reach's, its path this mount's `method` (`{name}.{method}`,
573    /// or, through a slot, ending `.{name}.{method}`). A door is one call's:
574    /// a forward made inside another call (a method's body reaching a child
575    /// itself) carries none, and is decided across by its data alone.
576    fn door_of(&self, reach: &Reach, method: &str) -> Option<plexus_auth_core::grants::DispatchedCall> {
577        if !super::grant_gate::is_door(reach) {
578            return None;
579        }
580        let call = crate::call::context().ok()?.door()?.clone();
581        let own = format!("{}.{method}", self.name());
582        let path = call.at().path();
583        let this = path == own || path.ends_with(&format!(".{own}"));
584        (this && Some(call.grant()) == reach.grant()).then_some(call)
585    }
586
587    /// DYNAUTH-12: mint the token for one forwarded call — for a signed-in
588    /// caller, when the service issues tokens, to a child that proved a key
589    /// (bound to it) or one on the service's own pipe (`pipe:<name>`). A
590    /// WebSocket child that proved no key gets none.
591    fn mint(&self, auth: Option<&AuthContext>, reach: &Reach, hop: &Value, path: &str, call: &str) -> Result<Option<upcall::Minted>, String> {
592        use crate::plexus::peer_token::{mint_scope, onward_scope, MintRequest};
593        let Some(issuer) = self.inner.shared.opts.tokens.as_ref() else { return Ok(None) };
594        // KEEL-19 (KEEL-22's first row): asked again here, after the dial
595        // `forward` awaited — a revoke meanwhile mints nothing.
596        if let Some(why) = self.inner.shared.upcalls.revoked() {
597            return Err(format!("`{}` is revoked ({why})", self.name()));
598        }
599        let Some(sub) = auth.and_then(|a| a.principal()).map(|p| p.to_string()) else { return Ok(None) };
600        let peer_key = self.peer_key().map(str::to_string);
601        if peer_key.is_none() && !matches!(self.spec(), ChildSpec::Stdio { .. }) {
602            return Ok(None);
603        }
604        // KEEL-19: no key-addressed token from a service that is not a key
605        // (the mount refuses such a peer first; this holds it here too).
606        if peer_key.is_some() && crate::plexus::peer_token::key_of(&self.inner.shared.principal).is_none() {
607            return Err(format!("{KEYED_MOUNT_NEEDS_A_KEY}: this service dials as `{}`, not a key", self.inner.shared.principal));
608        }
609        let held: Vec<String> = if reach.is_everywhere() { vec!["*".into()] } else { reach.held_on().iter().map(|s| s.to_string()).collect() };
610        let needs = crate::plexus::service_scope::current()
611            .and_then(|w| w.upgrade())
612            .map(|svc| self.inner.shared.upcalls.need_grants(&svc))
613            .unwrap_or_default();
614        let forwarded = hop.get("limit").and_then(|l| l.get("grant")).and_then(Value::as_str);
615        let presented = upcall::presented();
616        // DYNAUTH-6: onward from a call back, never wider than its token.
617        let mut scope = match &presented {
618            Some(p) => onward_scope(p, reach.grant().map(|g| g.as_str()), forwarded, &held, &needs),
619            None => mint_scope(forwarded, &held, &needs),
620        };
621        // ONE-7: the door the hop carries, for the forwarded grant at this
622        // call alone (`grant@/{ns}.{method}`) — onward from a call back only
623        // where the token presented holds the grant admitted on `*`.
624        let door = hop.get("limit").and_then(|l| l.get("door")).and_then(Value::as_str);
625        if let (Some(g), Some(at)) = (forwarded, door) {
626            let admitted = reach.grant().map(|g| g.as_str());
627            let onward_held = presented.as_ref().is_none_or(|p| admitted.is_some_and(|a| p.scopes_for(a).iter().any(|s| s == "*")));
628            if onward_held {
629                scope.push(format!("{g}@{at}"));
630            }
631        }
632        let req = MintRequest { sub, peer_key, name: self.name().to_string(), scope, call: call.to_string(), method: path.to_string(), presented };
633        let (token, claims) = issuer.mint(req).map_err(|e| e.to_string())?;
634        Ok(Some(upcall::Minted { token, claims }))
635    }
636
637    /// NEST-4: the kept static child at `path` (dotted, relative to the mount).
638    fn node(&self, path: &str) -> Option<&PluginSchema> {
639        self.inner.nodes.iter().find(|(p, _)| p == path).map(|(_, s)| s)
640    }
641
642    /// NEST-6: where a path below the mount enters a slot, if it does: the
643    /// slot (`<mount>.<parent>.{<slot>}`) and the instance's path below the
644    /// mount (`<parent>.<name>`; through a peer slot, which the path names,
645    /// `<parent>.<slot>.<name>`). The deepest kept level the path starts with
646    /// is the parent: a static child, which the walk kept, wins over a slot.
647    fn slot_of(&self, path: &str) -> Option<(String, String)> {
648        let segs: Vec<&str> = path.split('.').collect();
649        let (n, schema) = (1..segs.len())
650            .rev()
651            .find_map(|n| self.node(&segs[..n].join(".")).map(|s| (n, s)))
652            .unwrap_or((0, &self.inner.schema));
653        let parent = std::iter::once(self.name()).chain(segs[..n].iter().copied()).collect::<Vec<_>>().join(".");
654        let next = segs[n];
655        // NEST-7: a peer slot is named in the path, then the peer's name.
656        if schema.methods.iter().any(|m| m.name == next && matches!(m.role, MethodRole::Peer { .. })) {
657            return Some((crate::plexus::slots::slot_path(&parent, next), segs[..(n + 2).min(segs.len())].join(".")));
658        }
659        let slot = schema.methods.iter().find(|m| matches!(m.role, MethodRole::DynamicChild { .. }))?;
660        Some((crate::plexus::slots::slot_path(&parent, &slot.name), segs[..=n].join(".")))
661    }
662
663    /// A path no kept level answers and no slot is on the way of.
664    fn unreached(&self, method: &str) -> PlexusError {
665        PlexusError::MethodNotFound { activation: self.name().to_string(), method: method.to_string() }
666    }
667
668    /// NEST-6: `<mount>.<path>.schema` where `path` is in a dynamic slot
669    /// (`instance` its name's path): from the kept names, else asked of the
670    /// child once (`{ns}.<path>.schema`, with the caller's hop), kept under
671    /// its path and the `plexus_hash` it came with, and answered from that.
672    /// What the child answers instead of a schema (an unknown name's
673    /// not-found) comes back unchanged and is not kept.
674    async fn name_schema(&self, path: &str, params: &Value, auth: Option<&AuthContext>) -> PlexusStream {
675        let epoch = self.inner.shared.counters.restarts.load(Ordering::Relaxed);
676        if let Some(s) = self.inner.names.get(path, epoch) {
677            return self.schema_stream_of(&s, &s.namespace, params);
678        }
679        self.inner.names.crossed();
680        let items: Vec<PlexusStreamItem> = futures::StreamExt::collect(self.forward(&format!("{path}.schema"), json!({}), auth, None).await).await;
681        let kept = items.iter().find_map(|i| match i {
682            PlexusStreamItem::Data { metadata, content, .. } => Some((metadata.plexus_hash.clone(), content.clone().into_value())),
683            _ => None,
684        });
685        let Some((seen, raw)) = kept else {
686            return Box::pin(futures::stream::iter(items));
687        };
688        match read_schema(raw) {
689            Ok(schema) => {
690                // A restart while it crossed: what came is the new child's.
691                let epoch = self.inner.shared.counters.restarts.load(Ordering::Relaxed);
692                self.inner.names.put(path, schema.clone(), seen, epoch);
693                self.schema_stream_of(&schema, &schema.namespace, params)
694            }
695            Err(_) => Box::pin(futures::stream::iter(items)),
696        }
697    }
698
699    fn schema_stream(&self, params: &Value) -> PlexusStream {
700        self.schema_stream_of(&self.inner.schema, self.name(), params)
701    }
702
703    /// `schema` answered from what the mount kept: nothing crosses the hop
704    /// (spec/12 rule 7). `label` is the content type's namespace.
705    fn schema_stream_of(&self, schema: &PluginSchema, label: &str, params: &Value) -> PlexusStream {
706        let ns = label.to_string();
707        let content = match params.get("method").and_then(Value::as_str) {
708            Some(m) => match schema.methods.iter().find(|x| x.name == m) {
709                Some(ms) => serde_json::to_value(ms).unwrap_or_default(),
710                None => {
711                    let error = plexus_client::RemoteError::MethodNotFound { activation: ns.clone(), method: m.to_string() };
712                    let mut e = PlexusStreamItem::error(meta(&ns), error, false);
713                    if let PlexusStreamItem::Error { message, code, .. } = &mut e {
714                        *message = format!("Method '{m}' not found");
715                        *code = Some("-32602".into());
716                    }
717                    return Box::pin(futures::stream::iter([e]));
718                }
719            },
720            None => serde_json::to_value(schema).unwrap_or_default(),
721        };
722        Box::pin(futures::stream::iter([
723            PlexusStreamItem::Data { metadata: meta(&ns).into(), content_type: format!("{ns}.schema").into(), content: content.into() },
724            PlexusStreamItem::Done { metadata: meta(&ns) },
725        ]))
726    }
727
728    /// `instance`: the path of the dynamic instance the call goes through
729    /// (NEST-6), whose kept schema an item with another `plexus_hash` drops.
730    async fn forward(&self, method: &str, params: Value, auth: Option<&AuthContext>, instance: Option<String>) -> PlexusStream {
731        let shared = &self.inner.shared;
732        let one = |item: PlexusStreamItem| -> PlexusStream { Box::pin(futures::stream::iter([item])) };
733        // DYNAUTH-7: a revoked child is forwarded nothing.
734        if let Some(why) = shared.upcalls.revoked() {
735            let e = PlexusError::Unauthenticated(format!("`{}` is revoked ({why}): no call is forwarded to it", self.name()));
736            return one(PlexusStreamItem::from_plexus_error(meta(self.name()), &e, false));
737        }
738        // KEEL-59: nor one cut off.
739        if let Some(why) = shared.stopped() {
740            return one(unavailable(self.name(), why));
741        }
742        // RETURNS-47: the verdict is the call's; outside one (a forward no
743        // dispatch admitted) nothing crosses — fail closed, never everywhere.
744        let reach = match super::grant_gate::current_reach() {
745            Ok(reach) => reach,
746            Err(e) => return one(PlexusStreamItem::from_plexus_error(meta(self.name()), &e, false)),
747        };
748        let max = shared.opts.max_calls;
749        if shared.counters.open.fetch_add(1, Ordering::AcqRel) >= max {
750            shared.counters.open.fetch_sub(1, Ordering::AcqRel);
751            return one(too_many(self.name(), max));
752        }
753        let guard = OpenGuard(Arc::clone(&shared.counters));
754        let conn = match shared.ensure().await {
755            Ok(c) => c,
756            Err(item) => return one(item),
757        };
758        shared.counters.calls.fetch_add(1, Ordering::Relaxed);
759        // ONE-7: the door this call was admitted at, if it is this call's.
760        let door = self.door_of(&reach, method);
761        let own = door.is_some() && crate::call::context().is_ok_and(|c| c.door_own());
762        let (mut hop, call_id) = self.hop(&conn, auth, &reach, method, door.as_ref().map(|_| own));
763        let path = format!("{}.{method}", conn.ns());
764        // DYNAUTH-12: the token for this one call, when the service issues.
765        let minted = match self.mint(auth, &reach, &hop, &path, &call_id) {
766            Ok(m) => m,
767            Err(why) => {
768                let e = PlexusError::Unauthenticated(format!("no token could be minted for `{}`: {why}", self.name()));
769                return one(PlexusStreamItem::from_plexus_error(meta(self.name()), &e, false));
770            }
771        };
772        if let Some(m) = &minted {
773            hop["token"] = json!(m.token);
774            // KEEL-19: and the service's proof that it sends it, by the key
775            // that signed it — checked by the child against the JWKS it
776            // trusts, on a pipe and a connection alike.
777            if let Some(issuer) = shared.opts.tokens.as_ref() {
778                match issuer.prove_forward(&m.token, &m.claims) {
779                    Ok(p) => hop["proof"] = json!(p),
780                    Err(why) => {
781                        let e = PlexusError::Unauthenticated(format!("no proof could be signed for `{}`'s token: {why}", self.name()));
782                        return one(PlexusStreamItem::from_plexus_error(meta(self.name()), &e, false));
783                    }
784                }
785            }
786        }
787        // NEST-11: the child may call back under this call while it is open.
788        // ONE-7: a call a door admitted is called back under that door only.
789        let under = shared.upcalls.open(&call_id, auth, &reach, minted, door);
790        // KEEL-19: a revoke since the top of `forward` (the dial awaited)
791        // opens nothing.
792        if let Some(why) = shared.upcalls.revoked() {
793            drop(under);
794            let e = PlexusError::Unauthenticated(format!("`{}` is revoked ({why}): no call is forwarded to it", self.name()));
795            return one(PlexusStreamItem::from_plexus_error(meta(self.name()), &e, false));
796        }
797        if let Some(why) = shared.stopped() {
798            drop(under);
799            return one(unavailable(self.name(), why));
800        }
801        let call = json!({ "method": path, "params": params, "hop": hop });
802        let mark = link::PeerMark::here();
803        match conn.open(&format!("{}.call", conn.ns()), call, shared.opts.timeout, Some(mark.clone())).await {
804            Ok((sid, rx)) => {
805                let generation = reach.generation().cloned();
806                let seen = generation.as_ref().map_or(0, GrantsGeneration::current);
807                let instance = instance.map(|path| (Arc::clone(&self.inner), path));
808                Box::pin(CallStream { rx, sid, conn, over: false, _guard: guard, reach, generation, seen, name: self.name().to_string(), instance, under, mark })
809            }
810            Err(item) => one(item),
811        }
812    }
813}
814
815/// One open call, counted until its stream ends or is dropped.
816struct OpenGuard(Arc<Counters>);
817
818impl Drop for OpenGuard {
819    fn drop(&mut self) {
820        self.0.open.fetch_sub(1, Ordering::AcqRel);
821    }
822}
823
824/// The stream the service hands its caller: the child's items, in order,
825/// until the first terminal one; dropped before it, the child is told.
826struct CallStream {
827    rx: mpsc::Receiver<PlexusStreamItem>,
828    sid: SubKey,
829    conn: Arc<Conn>,
830    over: bool,
831    _guard: OpenGuard,
832    /// The gate's verdict at the open, asked again when the grants
833    /// generation moves (BIDIR-1 `regate = generation`, BIDIR-8).
834    reach: Reach,
835    generation: Option<GrantsGeneration>,
836    seen: u64,
837    name: String,
838    /// NEST-6: the dynamic instance the call goes through, and the mount
839    /// whose kept schema of it an item with another `plexus_hash` drops.
840    instance: Option<(Arc<Inner>, String)>,
841    /// NEST-11: the child's standing to call back under this call; ended
842    /// with it.
843    under: Option<upcall::UnderGuard>,
844    /// KEEL-59 (N3): taken when this call into the peer is let go.
845    mark: Arc<link::PeerMark>,
846}
847
848impl CallStream {
849    /// The call is over: what the child made under it ends too.
850    fn finish(&mut self, why: &str) {
851        self.over = true;
852        if let Some(u) = self.under.take() {
853            u.end(why);
854        }
855    }
856
857    /// The grant revoked mid-stream: the caller's last item.
858    fn revoked(&self) -> PlexusStreamItem {
859        let grant = self.reach.grant().map(|g| g.as_str().to_string()).unwrap_or_default();
860        let error = plexus_client::RemoteError::Forbidden {
861            reason: plexus_client::DenyReason::MissingGrant {
862                grant: grant.clone(),
863                scope: "*".into(),
864                roles: Vec::new(),
865                held_on: Vec::new(),
866            },
867        };
868        let mut item = PlexusStreamItem::error(meta(&self.name), error, false);
869        if let PlexusStreamItem::Error { message, .. } = &mut item {
870            *message = format!("Forbidden: `{grant}` is no longer held — the call's grant moved while it ran");
871        }
872        item
873    }
874}
875
876impl Stream for CallStream {
877    type Item = PlexusStreamItem;
878
879    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
880        if self.over {
881            return Poll::Ready(None);
882        }
883        // KEEL-59: cut off (a revoke, a disconnect): ends now, ahead of
884        // anything the child sent before (the child was told to stop).
885        if let Some(why) = self.conn.stopped() {
886            let item = unavailable(&self.name, why);
887            let why = why.to_string();
888            self.finish(&why);
889            return Poll::Ready(Some(item));
890        }
891        match self.rx.poll_recv(cx) {
892            Poll::Ready(Some(item)) => {
893                if let (Some((inner, path)), Some(m)) = (&self.instance, item.metadata()) {
894                    inner.names.observe(path, &m.plexus_hash);
895                }
896                let terminal = matches!(item, PlexusStreamItem::Done { .. } | PlexusStreamItem::Error { .. });
897                let moved = self.generation.as_ref().map(GrantsGeneration::current).filter(|g| *g != self.seen);
898                if let (false, Some(g)) = (terminal, moved) {
899                    self.seen = g;
900                    if self.reach.current().is_none() {
901                        let sid = self.sid.clone();
902                        self.conn.unsubscribe(&sid);
903                        self.finish("its grant was revoked");
904                        return Poll::Ready(Some(self.revoked()));
905                    }
906                }
907                if terminal {
908                    self.finish("it ended");
909                }
910                Poll::Ready(Some(item))
911            }
912            Poll::Ready(None) => {
913                // The channel closed with no terminal item: the link went.
914                self.finish("the connection closed");
915                Poll::Ready(Some(unavailable(&self.name, "the connection closed")))
916            }
917            Poll::Pending => Poll::Pending,
918        }
919    }
920}
921
922impl Drop for CallStream {
923    fn drop(&mut self) {
924        self.mark.taken();
925        if !self.over {
926            self.conn.unsubscribe(&self.sid);
927        }
928    }
929}
930
931#[async_trait]
932impl Activation for RemoteChild {
933    type Methods = ChildMethods;
934
935    fn needs(&self) -> Option<Vec<crate::plexus::schema::Need>> {
936        self.inner.needs.clone()
937    }
938
939    fn namespace(&self) -> &str {
940        self.name()
941    }
942
943    fn version(&self) -> &str {
944        &self.inner.schema.version
945    }
946
947    fn description(&self) -> &str {
948        &self.inner.schema.description
949    }
950
951    fn long_description(&self) -> Option<&str> {
952        self.inner.schema.long_description.as_deref()
953    }
954
955    fn methods(&self) -> Vec<&str> {
956        self.inner.schema.methods.iter().map(|m| m.name.as_str()).collect()
957    }
958
959    fn method_help(&self, method: &str) -> Option<String> {
960        self.inner.schema.methods.iter().find(|m| m.name == method).map(|m| m.description.clone())
961    }
962
963    async fn call(&self, method: &str, params: Value, auth: Option<&AuthContext>, _raw: Option<&crate::request::RawRequestContext>) -> Result<PlexusStream, PlexusError> {
964        if method == "schema" {
965            return Ok(self.schema_stream(&params));
966        }
967        // NEST-4: a static child's schema, from the kept tree.
968        if let Some(path) = method.strip_suffix(".schema") {
969            if let Some(s) = self.node(path) {
970                return Ok(self.schema_stream_of(s, &s.namespace, &params));
971            }
972            // NEST-6: an instance in a dynamic slot: the one schema that
973            // crosses the hop, once per name (spec/12 rule 7's exception).
974            return match self.slot_of(path) {
975                Some(_) => Ok(self.name_schema(path, &params, auth).await),
976                None => Err(self.unreached(method)),
977            };
978        }
979        let found = match method.rsplit_once('.') {
980            // NEST-4: a static child's method, by its path.
981            Some((path, name)) => match self.node(path) {
982                Some(s) => s.methods.iter().find(|m| m.name == name && m.role == MethodRole::Rpc),
983                // NEST-6: a method of an instance in a dynamic slot: the
984                // host's gate decided it on the slot grant; forwarded as
985                // any call, the child deciding again and answering an
986                // unknown name with its own not-found.
987                None => match self.slot_of(path) {
988                    Some((_, instance)) => return Ok(self.forward(method, params, auth, Some(instance)).await),
989                    None => return Err(self.unreached(method)),
990                },
991            },
992            None => self.inner.schema.methods.iter().find(|m| m.name == method && m.role == MethodRole::Rpc),
993        };
994        let Some(m) = found else {
995            return Err(PlexusError::MethodNotFound { activation: self.name().to_string(), method: method.to_string() });
996        };
997        // KEEL-31 (host side): a method the child's kept schema marks
998        // `everywhere` is forwarded only for a call admitted on `*` — a far
999        // side built before the rule would not decide it again.
1000        if m.everywhere {
1001            crate::call::admits_everywhere(&format!("{}.{method}", self.name()))?;
1002        }
1003        // BIDIR-6: a hop forwards no input half yet; the far side would wait
1004        // for items that never come.
1005        if m.input.is_some() {
1006            return Err(PlexusError::ExecutionError(format!(
1007                "`{}.{method}` takes an input stream, and a hop to a remote child does not forward one yet",
1008                self.name()
1009            )));
1010        }
1011        Ok(self.forward(method, params, auth, None).await)
1012    }
1013
1014    /// Nothing of its own on the socket: a child is reached through the
1015    /// service's `{service}.call`, behind its gate.
1016    fn into_rpc_methods(self) -> jsonrpsee::Methods {
1017        jsonrpsee::Methods::new()
1018    }
1019
1020    fn plugin_schema(&self) -> PluginSchema {
1021        self.inner.schema.clone()
1022    }
1023
1024    /// NEST-4: the kept tree — the host gates, lists and describes a mounted
1025    /// child's children by their whole path, as it does an in-process
1026    /// child's (MACRO-20, [`super::children`]).
1027    fn static_child_schemas(&self) -> Vec<(String, PluginSchema)> {
1028        self.inner.nodes.clone()
1029    }
1030}
1031
1032#[async_trait]
1033impl ChildRouter for RemoteChild {
1034    fn router_namespace(&self) -> &str {
1035        self.name()
1036    }
1037
1038    async fn router_call(&self, method: &str, params: Value, auth: Option<&AuthContext>, raw: Option<&crate::request::RawRequestContext>) -> Result<PlexusStream, PlexusError> {
1039        Activation::call(self, method, params, auth, raw).await
1040    }
1041
1042    async fn get_child(&self, _name: &str) -> Option<Box<dyn ChildRouter>> {
1043        None
1044    }
1045
1046    fn router_schema(&self) -> Option<PluginSchema> {
1047        Some(self.inner.schema.clone())
1048    }
1049
1050    fn router_static_child_schemas(&self) -> Vec<(String, PluginSchema)> {
1051        self.inner.nodes.clone()
1052    }
1053}
1054
1055#[cfg(test)]
1056mod tests {
1057    use super::*;
1058
1059    fn raw(methods: Value, roles: Value) -> Value {
1060        json!({ "namespace": "stub", "version": "0.1.0", "description": "d", "self_hash": "h", "hash": "h", "methods": methods, "roles": roles })
1061    }
1062
1063    fn m(name: &str) -> Value {
1064        json!({ "name": name, "description": "", "hash": "x", "streaming": false, "bidirectional": false })
1065    }
1066
1067    /// RETURNS-36 (review #6): no guessing — a method that states neither
1068    /// `cardinality` (0.8) nor `streaming` (0.7.0) is refused, naming it, as
1069    /// plexus-protocol's `cardinalityOf` refuses it.
1070    #[test]
1071    fn a_method_stating_neither_cardinality_nor_streaming_is_refused() {
1072        let silent = json!({ "name": "quiet", "description": "", "hash": "x" });
1073        let e = mount_schema("echo", raw(json!([m("echo"), silent]), json!({}))).unwrap_err();
1074        assert!(e.contains("`quiet`") && e.contains("neither cardinality"), "{e}");
1075    }
1076
1077    #[test]
1078    fn the_mount_name_wins_and_roles_are_requalified() {
1079        let s = mount_schema("echo", raw(json!([m("echo"), m("shout")]), json!({ "viewer": ["stub.echo"], "editor": ["stub.echo", "stub.shout"] }))).unwrap();
1080        assert_eq!(s.namespace, "echo");
1081        assert_eq!(s.roles["viewer"], vec!["echo.echo".to_string()]);
1082        assert_eq!(s.roles["editor"], vec!["echo.echo".to_string(), "echo.shout".to_string()]);
1083    }
1084
1085    /// NEST-4: a child with children mounts; its child roles stay on it.
1086    #[test]
1087    fn a_child_with_children_mounts_and_its_method_grants_are_requalified() {
1088        let mut inner = m("inner");
1089        inner["role"] = json!({ "kind": "static_child" });
1090        let mut own = m("echo");
1091        own["grant"] = json!("stub.echo");
1092        let s = mount_schema("echo", raw(json!([own, inner]), json!({}))).unwrap();
1093        assert_eq!(s.methods[0].grant.as_deref(), Some("echo.echo"));
1094        assert_eq!(s.methods[1].role, MethodRole::StaticChild);
1095        let mut slot = m("item");
1096        slot["role"] = json!({ "kind": "dynamic_child", "list_method": "names" });
1097        let nested = raw(json!([m("echo"), s_inner(), slot]), json!({}));
1098        assert_eq!(link::static_children(&nested), vec!["inner".to_string()], "a dynamic child is a slot, not walked");
1099        // A service's root says its activations in `children` alone.
1100        let mut root = raw(json!([m("call")]), json!({}));
1101        root["children"] = json!([{ "namespace": "greeter", "description": "", "hash": "g" }]);
1102        assert_eq!(link::static_children(&root), vec!["greeter".to_string()]);
1103    }
1104
1105    fn s_inner() -> Value {
1106        let mut inner = m("inner");
1107        inner["role"] = json!({ "kind": "static_child" });
1108        inner
1109    }
1110
1111    /// NEST-4: the tree's hash moves with a grandchild's.
1112    #[test]
1113    fn the_tree_hash_covers_every_level() {
1114        let top = raw(json!([m("echo")]), json!({}));
1115        let flat = link::Kept { top: top.clone(), nodes: vec![] };
1116        assert_eq!(flat.hash(), link::schema_hash(&top), "a flat child's hash is its schema's, as before");
1117        let mut c = raw(json!([m("m")]), json!({}));
1118        let one = link::Kept { top: top.clone(), nodes: vec![("a.b".into(), c.clone())] }.hash();
1119        c["hash"] = json!("other");
1120        let two = link::Kept { top, nodes: vec![("a.b".into(), c)] }.hash();
1121        assert_ne!(one, two);
1122    }
1123
1124    #[test]
1125    fn typed_error_fields_cross_whole() {
1126        let item = unavailable("echo", "gone");
1127        let v = serde_json::to_value(&item).unwrap();
1128        assert_eq!(v["error_kind"], "child_unavailable");
1129        assert_eq!(v["code"], "child_unavailable");
1130        assert_eq!(v["child"], "echo");
1131        let back: PlexusStreamItem = serde_json::from_value(v.clone()).unwrap();
1132        assert_eq!(back.error_kind(), Some("child_unavailable"));
1133        assert_eq!(serde_json::to_value(&back).unwrap(), v);
1134        // An error spec/05 gives no kind carries no `error_kind`: its keys
1135        // are spec/05's four and RETURNS-6's typed `error` (RETURNS-36).
1136        let plain = PlexusStreamItem::error(meta("x"), plexus_client::RemoteError::Execution { message: "m".into() }, false);
1137        let pv = serde_json::to_value(&plain).unwrap();
1138        let keys: Vec<_> = pv.as_object().unwrap().keys().cloned().collect();
1139        assert_eq!(keys, ["code", "error", "message", "metadata", "recoverable", "type"]);
1140    }
1141}