1mod host;
65mod link;
66mod names;
68mod peer;
70mod spec;
71mod upcall;
73#[cfg(feature = "child-ws")]
74mod ws;
75#[cfg(feature = "clap")]
76mod args;
77mod dial_in;
80#[cfg(feature = "child-ws")]
81mod dial_out;
82
83use std::pin::Pin;
84use std::sync::atomic::Ordering;
85use std::sync::Arc;
86use std::task::{Context, Poll};
87use std::time::Instant;
88
89use async_trait::async_trait;
90use futures::Stream;
91use plexus_auth_core::grants::{GrantsGeneration, Reach};
92use serde_json::{json, Value};
93use tokio::sync::mpsc;
94
95pub use host::{host, serve_child, serve_child_on, serve_child_stdio, serve_child_with, ChildPeer, HostTransport, ServeChild};
96pub use upcall::{Consented, HOST_CALL, HOST_CALL_UNSUB};
97pub use link::MountTimings;
98pub use spec::{check_ws_url, is_insecure_ws, is_loopback_host, parse_duration, Backoff, ChildError, ChildOptions, ChildSpec, INSECURE_TRANSPORT};
99#[cfg(feature = "clap")]
100pub use args::ChildArgs;
101pub use dial_in::{PeerEvent, PeerInfo, PeerRoles, PeerSocket, Peers, PeersMethods};
102#[cfg(feature = "child-ws")]
103pub use dial_out::{key_principal, DialOut, DialState, Exposed};
104
105use link::{meta, too_many, unavailable, Conn, Counters, Shared, SubKey};
106
107use super::auth::AuthContext;
108use super::method_enum::MethodEnumSchema;
109use super::plexus::{Activation, ChildRouter, PlexusError};
110use super::schema::{MethodRole, PluginSchema};
111use super::streaming::PlexusStream;
112use super::types::PlexusStreamItem;
113
114#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
122pub struct PeerIdentity {
123 pub backend: String,
125 #[serde(default, skip_serializing_if = "Option::is_none")]
127 pub tls_key: Option<String>,
128 #[serde(default, skip_serializing_if = "Option::is_none")]
131 pub key: Option<String>,
132}
133
134impl PeerIdentity {
135 fn of(conn: &Conn) -> Self {
136 Self { backend: conn.ns().to_string(), tls_key: conn.tls_key.get().cloned(), key: conn.peer_key.get().cloned() }
137 }
138}
139
140impl std::fmt::Display for PeerIdentity {
141 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
142 write!(f, "backend `{}`", self.backend)?;
143 match &self.tls_key {
144 Some(k) => write!(f, ", TLS key {}", &k[..k.len().min(16)]),
145 None => write!(f, ", no TLS key"),
146 }?;
147 match &self.key {
148 Some(k) => write!(f, ", key {}", &k[..k.len().min(20)]),
149 None => Ok(()),
150 }
151 }
152}
153
154#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
156pub struct ChildStats {
157 pub open: usize,
159 pub unasked: u64,
161 pub restarts: u64,
163 pub calls: u64,
165 pub name_schemas: u64,
168 pub name_schema_hits: u64,
170 pub names_kept: usize,
173 pub calls_back: u64,
175 pub up: bool,
177}
178
179#[derive(Debug, Clone, Copy)]
182pub enum ChildMethods {}
183
184impl schemars::JsonSchema for ChildMethods {
185 fn schema_name() -> std::borrow::Cow<'static, str> {
186 "ChildMethods".into()
187 }
188
189 fn json_schema(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
190 schemars::json_schema!({
191 "description": "A child service's methods are data: its schema, asked when it was mounted (`<mount>.schema`)."
192 })
193 }
194}
195
196impl MethodEnumSchema for ChildMethods {
197 fn method_names() -> &'static [&'static str] {
198 &[]
199 }
200
201 fn schema_with_consts() -> Value {
202 serde_json::to_value(schemars::schema_for!(ChildMethods)).unwrap_or(Value::Null)
203 }
204}
205
206struct Inner {
207 shared: Arc<Shared>,
208 schema: PluginSchema,
209 nodes: Vec<(String, PluginSchema)>,
214 timings: MountTimings,
215 names: names::Names,
217 needs: Option<Vec<crate::plexus::schema::Need>>,
220}
221
222impl Inner {
223 pub(super) fn new(shared: Arc<Shared>, schema: PluginSchema, nodes: Vec<(String, PluginSchema)>, timings: MountTimings) -> Self {
224 let names = names::Names::new(shared.opts.schema_cache);
225 let declared = schema.needs.is_some() || nodes.iter().any(|(_, n)| n.needs.is_some());
226 let mut needs: Vec<crate::plexus::schema::Need> = schema.needs.iter().chain(nodes.iter().filter_map(|(_, n)| n.needs.as_ref())).flatten().cloned().collect();
227 needs.sort();
228 needs.dedup_by(|a, b| a.method == b.method);
229 let needs = declared.then_some(needs);
230 Self { shared, schema, nodes, timings, names, needs }
231 }
232}
233
234#[derive(Clone)]
238pub struct RemoteChild {
239 inner: Arc<Inner>,
240}
241
242impl std::fmt::Debug for RemoteChild {
243 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
244 f.debug_struct("RemoteChild").field("spec", &self.inner.shared.spec.to_string()).field("insecure", &self.insecure()).field("stats", &self.stats()).finish()
245 }
246}
247
248fn read_schema(raw: Value) -> Result<PluginSchema, String> {
250 serde_json::from_value(peer::schema(raw)?).map_err(|e| format!("its schema does not read: {e}"))
251}
252
253pub(super) fn node_schema(path: &str, raw: Value) -> Result<PluginSchema, String> {
257 read_schema(raw).map_err(|e| format!("its child `{path}`: {e}"))
258}
259
260fn mount_schema(name: &str, raw: Value) -> Result<PluginSchema, String> {
266 let mut schema = read_schema(raw)?;
267 if schema.namespace != name {
268 tracing::info!(target: "plexus::child", child = %name, declared = %schema.namespace, "mounted under its mount name, not the namespace it declares");
269 }
270 let prefix = format!("{}.", schema.namespace);
271 let requalify = |g: &String| match g.strip_prefix(&prefix) {
272 Some(m) => format!("{name}.{m}"),
273 None => format!("{name}.{g}"),
274 };
275 schema.roles = schema.roles.iter().map(|(r, gs)| (r.clone(), gs.iter().map(requalify).collect())).collect();
276 for m in schema.methods.iter_mut() {
277 if let Some(g) = m.grant.as_ref() {
278 m.grant = Some(requalify(g));
279 }
280 }
281 schema.namespace = name.to_string();
282 Ok(schema)
283}
284
285impl RemoteChild {
286 pub async fn connect(spec: ChildSpec, opts: ChildOptions) -> Result<Self, ChildError> {
291 let name = spec.name().to_string();
292 let start = |why: String| ChildError::Start(name.clone(), why);
293 if opts.max_calls == 0 || opts.buffer == 0 {
294 return Err(start("max_calls and buffer are at least 1".into()));
295 }
296 let principal = Self::principal_for(&spec, &opts).map_err(start)?;
297 let shared = Shared::new(spec, opts, principal);
298 let (conn, kept, mut timings) = shared.connect_once().await.map_err(start)?;
299 let t = Instant::now();
300 let hash = kept.hash();
301 let read = mount_schema(&name, kept.top).and_then(|schema| {
302 let nodes = kept.nodes.into_iter().map(|(path, raw)| node_schema(&path, raw).map(|s| (path, s))).collect::<Result<Vec<_>, _>>()?;
303 Ok((schema, nodes))
304 });
305 let (schema, nodes) = match read {
306 Ok(s) => s,
307 Err(why) => {
308 conn.shutdown.notify_one();
309 return Err(start(why));
310 }
311 };
312 let _ = shared.mounted_hash.set(hash);
313 let _ = shared.identity.set(PeerIdentity::of(&conn));
314 shared.install(conn);
315 timings.merge_ms = t.elapsed().as_secs_f64() * 1e3;
316 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");
317 if let ChildSpec::Ws { url, .. } = &shared.spec {
318 if is_insecure_ws(url) {
319 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");
320 }
321 }
322 let inner = Inner::new(shared, schema, nodes, timings);
323 inner.shared.upcalls.set_needs(inner.needs.as_deref());
325 Ok(Self { inner: Arc::new(inner) })
326 }
327
328 #[allow(unused_variables)]
329 fn principal_for(spec: &ChildSpec, opts: &ChildOptions) -> Result<String, String> {
330 #[cfg(feature = "child-ws")]
331 if let (ChildSpec::Ws { .. }, Some(path)) = (spec, &opts.key) {
332 return Ok(ws::principal_of(&ws::read_seed(path)?));
333 }
334 Ok(opts.principal.clone())
335 }
336
337 pub fn stats(&self) -> ChildStats {
339 let c: &Counters = &self.inner.shared.counters;
340 ChildStats {
341 open: c.open.load(Ordering::Relaxed),
342 unasked: c.unasked.load(Ordering::Relaxed),
343 restarts: c.restarts.load(Ordering::Relaxed),
344 calls: c.calls.load(Ordering::Relaxed),
345 name_schemas: self.inner.names.hops.load(Ordering::Relaxed),
346 name_schema_hits: self.inner.names.hits.load(Ordering::Relaxed),
347 names_kept: self.inner.names.len(c.restarts.load(Ordering::Relaxed)),
348 calls_back: self.inner.shared.upcalls.made.load(Ordering::Relaxed),
349 up: self.inner.shared.is_up(),
350 }
351 }
352
353 pub fn identity(&self) -> Option<&PeerIdentity> {
357 self.inner.shared.identity.get()
358 }
359
360 pub fn set_consent(&self, consent: Option<Vec<Consented>>) {
365 self.inner.shared.upcalls.set_consent(consent);
366 }
367
368 pub fn consent(&self) -> Option<Vec<Consented>> {
370 self.inner.shared.upcalls.consent().map(|c| c.to_vec())
371 }
372
373 pub fn revoke(&self, why: &str) {
378 *self.inner.shared.revoked.lock().unwrap() = Some(why.to_string());
379 self.inner.shared.upcalls.end_all(&format!("revoked: {why}"));
380 tracing::warn!(target: "plexus::audit", child = %self.name(), %why, "child revoked");
381 }
382
383 pub fn revoked(&self) -> Option<String> {
385 self.inner.shared.revoked.lock().unwrap().clone()
386 }
387
388 pub fn peer_key(&self) -> Option<&str> {
391 self.identity().and_then(|i| i.key.as_deref())
392 }
393
394 pub fn is_up(&self) -> bool {
396 self.inner.shared.is_up()
397 }
398
399 pub fn dead(&self) -> Option<String> {
404 self.inner.shared.dead()
405 }
406
407 pub fn why_down(&self) -> Option<String> {
411 self.inner.shared.why_down()
412 }
413
414 pub async fn up(&self) -> Result<(), String> {
418 match self.inner.shared.ensure().await {
419 Ok(_) => Ok(()),
420 Err(PlexusStreamItem::Error { message, error, .. }) => Err(match error {
421 plexus_client::RemoteError::ChildUnavailable { reason, .. } => reason,
422 _ => message,
423 }),
424 Err(other) => Err(format!("{other:?}")),
425 }
426 }
427
428 pub fn needs(&self) -> Option<&[crate::plexus::schema::Need]> {
431 self.inner.needs.as_deref()
432 }
433
434 pub fn calls_open_back(&self) -> usize {
436 self.inner.shared.upcalls.open_now()
437 }
438
439 pub fn mounted_hash(&self) -> &str {
442 self.inner.shared.mounted_hash.get().map(String::as_str).unwrap_or_default()
443 }
444
445 pub fn pid(&self) -> Option<u32> {
447 self.inner.shared.current().and_then(|c| c.pid)
448 }
449
450 pub fn name(&self) -> &str {
452 &self.inner.shared.name
453 }
454
455 pub fn insecure(&self) -> bool {
459 matches!(&self.inner.shared.spec, ChildSpec::Ws { url, .. } if is_insecure_ws(url))
460 }
461
462 pub fn spec(&self) -> &ChildSpec {
464 &self.inner.shared.spec
465 }
466
467 pub fn principal(&self) -> &str {
469 &self.inner.shared.principal
470 }
471
472 pub fn mount_timings(&self) -> MountTimings {
474 self.inner.timings
475 }
476
477 pub fn routed(&self) -> usize {
479 self.inner.shared.current().map_or(0, |c| c.routed())
480 }
481
482 fn hop(&self, conn: &Conn, auth: Option<&AuthContext>, reach: &Reach, method: &str) -> (Value, String) {
486 let for_: Vec<String> = auth.and_then(|a| a.principal()).map(|p| p.to_string()).into_iter().collect();
487 let limit = reach.grant().map(|g| {
488 let grant = match g.as_str().strip_prefix(&format!("{}.", self.name())) {
489 Some(m) => format!("{}.{m}", conn.ns()),
490 None => format!("{}.{method}", conn.ns()),
495 };
496 let held_on: Vec<String> = reach.held_on().iter().map(|s| s.to_string()).collect();
497 json!({ "grant": grant, "held_on": held_on })
498 });
499 let call = uuid::Uuid::new_v4().to_string();
500 (json!({ "principal": self.inner.shared.principal, "for": for_, "limit": limit, "call": call }), call)
501 }
502
503 fn mint(&self, auth: Option<&AuthContext>, reach: &Reach, hop: &Value, path: &str, call: &str) -> Result<Option<upcall::Minted>, String> {
508 use crate::plexus::peer_token::{mint_scope, onward_scope, MintRequest};
509 let Some(issuer) = self.inner.shared.opts.tokens.as_ref() else { return Ok(None) };
510 let Some(sub) = auth.and_then(|a| a.principal()).map(|p| p.to_string()) else { return Ok(None) };
511 let peer_key = self.peer_key().map(str::to_string);
512 if peer_key.is_none() && !matches!(self.spec(), ChildSpec::Stdio { .. }) {
513 return Ok(None);
514 }
515 let held: Vec<String> = if reach.is_everywhere() { vec!["*".into()] } else { reach.held_on().iter().map(|s| s.to_string()).collect() };
516 let needs = crate::plexus::service_scope::current()
517 .and_then(|w| w.upgrade())
518 .map(|svc| self.inner.shared.upcalls.need_grants(&svc))
519 .unwrap_or_default();
520 let forwarded = hop.get("limit").and_then(|l| l.get("grant")).and_then(Value::as_str);
521 let presented = upcall::presented();
522 let scope = match &presented {
524 Some(p) => onward_scope(p, reach.grant().map(|g| g.as_str()), forwarded, &held, &needs),
525 None => mint_scope(forwarded, &held, &needs),
526 };
527 let req = MintRequest { sub, peer_key, name: self.name().to_string(), scope, call: call.to_string(), method: path.to_string(), presented };
528 let (token, claims) = issuer.mint(req).map_err(|e| e.to_string())?;
529 Ok(Some(upcall::Minted { token, claims }))
530 }
531
532 fn node(&self, path: &str) -> Option<&PluginSchema> {
534 self.inner.nodes.iter().find(|(p, _)| p == path).map(|(_, s)| s)
535 }
536
537 fn slot_of(&self, path: &str) -> Option<(String, String)> {
543 let segs: Vec<&str> = path.split('.').collect();
544 let (n, schema) = (1..segs.len())
545 .rev()
546 .find_map(|n| self.node(&segs[..n].join(".")).map(|s| (n, s)))
547 .unwrap_or((0, &self.inner.schema));
548 let parent = std::iter::once(self.name()).chain(segs[..n].iter().copied()).collect::<Vec<_>>().join(".");
549 let next = segs[n];
550 if schema.methods.iter().any(|m| m.name == next && matches!(m.role, MethodRole::Peer { .. })) {
552 return Some((crate::plexus::slots::slot_path(&parent, next), segs[..(n + 2).min(segs.len())].join(".")));
553 }
554 let slot = schema.methods.iter().find(|m| matches!(m.role, MethodRole::DynamicChild { .. }))?;
555 Some((crate::plexus::slots::slot_path(&parent, &slot.name), segs[..=n].join(".")))
556 }
557
558 fn unreached(&self, method: &str) -> PlexusError {
560 PlexusError::MethodNotFound { activation: self.name().to_string(), method: method.to_string() }
561 }
562
563 async fn name_schema(&self, path: &str, params: &Value, auth: Option<&AuthContext>) -> PlexusStream {
570 let epoch = self.inner.shared.counters.restarts.load(Ordering::Relaxed);
571 if let Some(s) = self.inner.names.get(path, epoch) {
572 return self.schema_stream_of(&s, &s.namespace, params);
573 }
574 self.inner.names.crossed();
575 let items: Vec<PlexusStreamItem> = futures::StreamExt::collect(self.forward(&format!("{path}.schema"), json!({}), auth, None).await).await;
576 let kept = items.iter().find_map(|i| match i {
577 PlexusStreamItem::Data { metadata, content, .. } => Some((metadata.plexus_hash.clone(), content.clone().into_value())),
578 _ => None,
579 });
580 let Some((seen, raw)) = kept else {
581 return Box::pin(futures::stream::iter(items));
582 };
583 match read_schema(raw) {
584 Ok(schema) => {
585 let epoch = self.inner.shared.counters.restarts.load(Ordering::Relaxed);
587 self.inner.names.put(path, schema.clone(), seen, epoch);
588 self.schema_stream_of(&schema, &schema.namespace, params)
589 }
590 Err(_) => Box::pin(futures::stream::iter(items)),
591 }
592 }
593
594 fn schema_stream(&self, params: &Value) -> PlexusStream {
595 self.schema_stream_of(&self.inner.schema, self.name(), params)
596 }
597
598 fn schema_stream_of(&self, schema: &PluginSchema, label: &str, params: &Value) -> PlexusStream {
601 let ns = label.to_string();
602 let content = match params.get("method").and_then(Value::as_str) {
603 Some(m) => match schema.methods.iter().find(|x| x.name == m) {
604 Some(ms) => serde_json::to_value(ms).unwrap_or_default(),
605 None => {
606 let error = plexus_client::RemoteError::MethodNotFound { activation: ns.clone(), method: m.to_string() };
607 let mut e = PlexusStreamItem::error(meta(&ns), error, false);
608 if let PlexusStreamItem::Error { message, code, .. } = &mut e {
609 *message = format!("Method '{m}' not found");
610 *code = Some("-32602".into());
611 }
612 return Box::pin(futures::stream::iter([e]));
613 }
614 },
615 None => serde_json::to_value(schema).unwrap_or_default(),
616 };
617 Box::pin(futures::stream::iter([
618 PlexusStreamItem::Data { metadata: meta(&ns).into(), content_type: format!("{ns}.schema").into(), content: content.into() },
619 PlexusStreamItem::Done { metadata: meta(&ns) },
620 ]))
621 }
622
623 async fn forward(&self, method: &str, params: Value, auth: Option<&AuthContext>, instance: Option<String>) -> PlexusStream {
626 let shared = &self.inner.shared;
627 let one = |item: PlexusStreamItem| -> PlexusStream { Box::pin(futures::stream::iter([item])) };
628 if let Some(why) = shared.revoked.lock().unwrap().clone() {
630 let e = PlexusError::Unauthenticated(format!("`{}` is revoked ({why}): no call is forwarded to it", self.name()));
631 return one(PlexusStreamItem::from_plexus_error(meta(self.name()), &e, false));
632 }
633 let reach = match super::grant_gate::current_reach() {
636 Ok(reach) => reach,
637 Err(e) => return one(PlexusStreamItem::from_plexus_error(meta(self.name()), &e, false)),
638 };
639 let max = shared.opts.max_calls;
640 if shared.counters.open.fetch_add(1, Ordering::AcqRel) >= max {
641 shared.counters.open.fetch_sub(1, Ordering::AcqRel);
642 return one(too_many(self.name(), max));
643 }
644 let guard = OpenGuard(Arc::clone(&shared.counters));
645 let conn = match shared.ensure().await {
646 Ok(c) => c,
647 Err(item) => return one(item),
648 };
649 shared.counters.calls.fetch_add(1, Ordering::Relaxed);
650 let (mut hop, call_id) = self.hop(&conn, auth, &reach, method);
651 let path = format!("{}.{method}", conn.ns());
652 let minted = match self.mint(auth, &reach, &hop, &path, &call_id) {
654 Ok(m) => m,
655 Err(why) => {
656 let e = PlexusError::Unauthenticated(format!("no token could be minted for `{}`: {why}", self.name()));
657 return one(PlexusStreamItem::from_plexus_error(meta(self.name()), &e, false));
658 }
659 };
660 if let Some(m) = &minted {
661 hop["token"] = json!(m.token);
662 }
663 let under = shared.upcalls.open(&call_id, auth, &reach, minted);
665 let call = json!({ "method": path, "params": params, "hop": hop });
666 match conn.open(&format!("{}.call", conn.ns()), call, shared.opts.timeout).await {
667 Ok((sid, rx)) => {
668 let generation = reach.generation().cloned();
669 let seen = generation.as_ref().map_or(0, GrantsGeneration::current);
670 let instance = instance.map(|path| (Arc::clone(&self.inner), path));
671 Box::pin(CallStream { rx, sid, conn, over: false, _guard: guard, reach, generation, seen, name: self.name().to_string(), instance, under })
672 }
673 Err(item) => one(item),
674 }
675 }
676}
677
678struct OpenGuard(Arc<Counters>);
680
681impl Drop for OpenGuard {
682 fn drop(&mut self) {
683 self.0.open.fetch_sub(1, Ordering::AcqRel);
684 }
685}
686
687struct CallStream {
690 rx: mpsc::Receiver<PlexusStreamItem>,
691 sid: SubKey,
692 conn: Arc<Conn>,
693 over: bool,
694 _guard: OpenGuard,
695 reach: Reach,
698 generation: Option<GrantsGeneration>,
699 seen: u64,
700 name: String,
701 instance: Option<(Arc<Inner>, String)>,
704 under: Option<upcall::UnderGuard>,
707}
708
709impl CallStream {
710 fn finish(&mut self, why: &str) {
712 self.over = true;
713 if let Some(u) = self.under.take() {
714 u.end(why);
715 }
716 }
717
718 fn revoked(&self) -> PlexusStreamItem {
720 let grant = self.reach.grant().map(|g| g.as_str().to_string()).unwrap_or_default();
721 let error = plexus_client::RemoteError::Forbidden {
722 reason: plexus_client::DenyReason::MissingGrant {
723 grant: grant.clone(),
724 scope: "*".into(),
725 roles: Vec::new(),
726 held_on: Vec::new(),
727 },
728 };
729 let mut item = PlexusStreamItem::error(meta(&self.name), error, false);
730 if let PlexusStreamItem::Error { message, .. } = &mut item {
731 *message = format!("Forbidden: `{grant}` is no longer held — the call's grant moved while it ran");
732 }
733 item
734 }
735}
736
737impl Stream for CallStream {
738 type Item = PlexusStreamItem;
739
740 fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
741 if self.over {
742 return Poll::Ready(None);
743 }
744 match self.rx.poll_recv(cx) {
745 Poll::Ready(Some(item)) => {
746 if let (Some((inner, path)), Some(m)) = (&self.instance, item.metadata()) {
747 inner.names.observe(path, &m.plexus_hash);
748 }
749 let terminal = matches!(item, PlexusStreamItem::Done { .. } | PlexusStreamItem::Error { .. });
750 let moved = self.generation.as_ref().map(GrantsGeneration::current).filter(|g| *g != self.seen);
751 if let (false, Some(g)) = (terminal, moved) {
752 self.seen = g;
753 if self.reach.current().is_none() {
754 let sid = self.sid.clone();
755 self.conn.unsubscribe(&sid);
756 self.finish("its grant was revoked");
757 return Poll::Ready(Some(self.revoked()));
758 }
759 }
760 if terminal {
761 self.finish("it ended");
762 }
763 Poll::Ready(Some(item))
764 }
765 Poll::Ready(None) => {
766 self.finish("the connection closed");
768 Poll::Ready(Some(unavailable(&self.name, "the connection closed")))
769 }
770 Poll::Pending => Poll::Pending,
771 }
772 }
773}
774
775impl Drop for CallStream {
776 fn drop(&mut self) {
777 if !self.over {
778 self.conn.unsubscribe(&self.sid);
779 }
780 }
781}
782
783#[async_trait]
784impl Activation for RemoteChild {
785 type Methods = ChildMethods;
786
787 fn needs(&self) -> Option<Vec<crate::plexus::schema::Need>> {
788 self.inner.needs.clone()
789 }
790
791 fn namespace(&self) -> &str {
792 self.name()
793 }
794
795 fn version(&self) -> &str {
796 &self.inner.schema.version
797 }
798
799 fn description(&self) -> &str {
800 &self.inner.schema.description
801 }
802
803 fn long_description(&self) -> Option<&str> {
804 self.inner.schema.long_description.as_deref()
805 }
806
807 fn methods(&self) -> Vec<&str> {
808 self.inner.schema.methods.iter().map(|m| m.name.as_str()).collect()
809 }
810
811 fn method_help(&self, method: &str) -> Option<String> {
812 self.inner.schema.methods.iter().find(|m| m.name == method).map(|m| m.description.clone())
813 }
814
815 async fn call(&self, method: &str, params: Value, auth: Option<&AuthContext>, _raw: Option<&crate::request::RawRequestContext>) -> Result<PlexusStream, PlexusError> {
816 if method == "schema" {
817 return Ok(self.schema_stream(¶ms));
818 }
819 if let Some(path) = method.strip_suffix(".schema") {
821 if let Some(s) = self.node(path) {
822 return Ok(self.schema_stream_of(s, &s.namespace, ¶ms));
823 }
824 return match self.slot_of(path) {
827 Some(_) => Ok(self.name_schema(path, ¶ms, auth).await),
828 None => Err(self.unreached(method)),
829 };
830 }
831 let found = match method.rsplit_once('.') {
832 Some((path, name)) => match self.node(path) {
834 Some(s) => s.methods.iter().find(|m| m.name == name && m.role == MethodRole::Rpc),
835 None => match self.slot_of(path) {
840 Some((_, instance)) => return Ok(self.forward(method, params, auth, Some(instance)).await),
841 None => return Err(self.unreached(method)),
842 },
843 },
844 None => self.inner.schema.methods.iter().find(|m| m.name == method && m.role == MethodRole::Rpc),
845 };
846 let Some(m) = found else {
847 return Err(PlexusError::MethodNotFound { activation: self.name().to_string(), method: method.to_string() });
848 };
849 if m.input.is_some() {
852 return Err(PlexusError::ExecutionError(format!(
853 "`{}.{method}` takes an input stream, and a hop to a remote child does not forward one yet",
854 self.name()
855 )));
856 }
857 Ok(self.forward(method, params, auth, None).await)
858 }
859
860 fn into_rpc_methods(self) -> jsonrpsee::Methods {
863 jsonrpsee::Methods::new()
864 }
865
866 fn plugin_schema(&self) -> PluginSchema {
867 self.inner.schema.clone()
868 }
869
870 fn static_child_schemas(&self) -> Vec<(String, PluginSchema)> {
874 self.inner.nodes.clone()
875 }
876}
877
878#[async_trait]
879impl ChildRouter for RemoteChild {
880 fn router_namespace(&self) -> &str {
881 self.name()
882 }
883
884 async fn router_call(&self, method: &str, params: Value, auth: Option<&AuthContext>, raw: Option<&crate::request::RawRequestContext>) -> Result<PlexusStream, PlexusError> {
885 Activation::call(self, method, params, auth, raw).await
886 }
887
888 async fn get_child(&self, _name: &str) -> Option<Box<dyn ChildRouter>> {
889 None
890 }
891
892 fn router_schema(&self) -> Option<PluginSchema> {
893 Some(self.inner.schema.clone())
894 }
895
896 fn router_static_child_schemas(&self) -> Vec<(String, PluginSchema)> {
897 self.inner.nodes.clone()
898 }
899}
900
901#[cfg(test)]
902mod tests {
903 use super::*;
904
905 fn raw(methods: Value, roles: Value) -> Value {
906 json!({ "namespace": "stub", "version": "0.1.0", "description": "d", "self_hash": "h", "hash": "h", "methods": methods, "roles": roles })
907 }
908
909 fn m(name: &str) -> Value {
910 json!({ "name": name, "description": "", "hash": "x", "streaming": false, "bidirectional": false })
911 }
912
913 #[test]
917 fn a_method_stating_neither_cardinality_nor_streaming_is_refused() {
918 let silent = json!({ "name": "quiet", "description": "", "hash": "x" });
919 let e = mount_schema("echo", raw(json!([m("echo"), silent]), json!({}))).unwrap_err();
920 assert!(e.contains("`quiet`") && e.contains("neither cardinality"), "{e}");
921 }
922
923 #[test]
924 fn the_mount_name_wins_and_roles_are_requalified() {
925 let s = mount_schema("echo", raw(json!([m("echo"), m("shout")]), json!({ "viewer": ["stub.echo"], "editor": ["stub.echo", "stub.shout"] }))).unwrap();
926 assert_eq!(s.namespace, "echo");
927 assert_eq!(s.roles["viewer"], vec!["echo.echo".to_string()]);
928 assert_eq!(s.roles["editor"], vec!["echo.echo".to_string(), "echo.shout".to_string()]);
929 }
930
931 #[test]
933 fn a_child_with_children_mounts_and_its_method_grants_are_requalified() {
934 let mut inner = m("inner");
935 inner["role"] = json!({ "kind": "static_child" });
936 let mut own = m("echo");
937 own["grant"] = json!("stub.echo");
938 let s = mount_schema("echo", raw(json!([own, inner]), json!({}))).unwrap();
939 assert_eq!(s.methods[0].grant.as_deref(), Some("echo.echo"));
940 assert_eq!(s.methods[1].role, MethodRole::StaticChild);
941 let mut slot = m("item");
942 slot["role"] = json!({ "kind": "dynamic_child", "list_method": "names" });
943 let nested = raw(json!([m("echo"), s_inner(), slot]), json!({}));
944 assert_eq!(link::static_children(&nested), vec!["inner".to_string()], "a dynamic child is a slot, not walked");
945 let mut root = raw(json!([m("call")]), json!({}));
947 root["children"] = json!([{ "namespace": "greeter", "description": "", "hash": "g" }]);
948 assert_eq!(link::static_children(&root), vec!["greeter".to_string()]);
949 }
950
951 fn s_inner() -> Value {
952 let mut inner = m("inner");
953 inner["role"] = json!({ "kind": "static_child" });
954 inner
955 }
956
957 #[test]
959 fn the_tree_hash_covers_every_level() {
960 let top = raw(json!([m("echo")]), json!({}));
961 let flat = link::Kept { top: top.clone(), nodes: vec![] };
962 assert_eq!(flat.hash(), link::schema_hash(&top), "a flat child's hash is its schema's, as before");
963 let mut c = raw(json!([m("m")]), json!({}));
964 let one = link::Kept { top: top.clone(), nodes: vec![("a.b".into(), c.clone())] }.hash();
965 c["hash"] = json!("other");
966 let two = link::Kept { top, nodes: vec![("a.b".into(), c)] }.hash();
967 assert_ne!(one, two);
968 }
969
970 #[test]
971 fn typed_error_fields_cross_whole() {
972 let item = unavailable("echo", "gone");
973 let v = serde_json::to_value(&item).unwrap();
974 assert_eq!(v["error_kind"], "child_unavailable");
975 assert_eq!(v["code"], "child_unavailable");
976 assert_eq!(v["child"], "echo");
977 let back: PlexusStreamItem = serde_json::from_value(v.clone()).unwrap();
978 assert_eq!(back.error_kind(), Some("child_unavailable"));
979 assert_eq!(serde_json::to_value(&back).unwrap(), v);
980 let plain = PlexusStreamItem::error(meta("x"), plexus_client::RemoteError::Execution { message: "m".into() }, false);
983 let pv = serde_json::to_value(&plain).unwrap();
984 let keys: Vec<_> = pv.as_object().unwrap().keys().cloned().collect();
985 assert_eq!(keys, ["code", "error", "message", "metadata", "recoverable", "type"]);
986 }
987}