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