rutis_bridge/lib.rs
1//! Connect rutis to other processes, languages and machines.
2//!
3//! - [`runtime`]: plugins written in other languages, run by language
4//! runtimes (started with [`runtime::Launcher::start`] on this machine,
5//! each the far end of a session); rutis-loader manages them as rows.
6//! - [`Session`]: the far end of a [`Channel`] (a runtime, an app, a node)
7//! as plugins of this kernel.
8//! A far rutis kernel is a session's far end too: the services of both
9//! are seen on both sides, events are one bus, and each runs the other's
10//! plugins from its [`PluginCatalog`].
11//! - [`events`]: the logical event bus across runtimes and nodes.
12//! - What sessions run over: [`pipe`] (local processes),
13//! [`memory`] (in-process channels) and `websocket` (feature
14//! `websocket`), each giving a [`Channel`] directly ([`pipe::spawn`],
15//! [`memory::pair`], `websocket::dial`, `websocket::listen`).
16//! - [`session`]: the protocol all of these speak, over any
17//! [`channel::Channel`].
18//! - [`cordis`] (feature `cordis`): Cordis plugins mounted in a Rust
19//! application with Rust bindings generated at build time.
20//!
21//! Design: `docs/design-protocol-channel-decoupling-2026-10-03.md`,
22//! `docs/design-remote-session-2026-10-28.md`.
23
24pub mod channel;
25#[cfg(feature = "cordis")]
26pub mod cordis;
27pub mod events;
28pub mod exports;
29pub mod memory;
30pub mod pipe;
31pub mod report;
32pub mod runtime;
33pub mod session;
34#[cfg(feature = "websocket")]
35pub mod websocket;
36
37// The fuzz targets' entry points (`fuzz/`, #179): only in a build by
38// cargo-fuzz, which sets `--cfg fuzzing`. `session_frames` is left out
39// without `testing` (the session fixture it drives, `fuzzing.rs`).
40#[cfg(fuzzing)]
41#[doc(hidden)]
42pub mod fuzzing;
43
44mod catalog;
45mod identity;
46mod marked;
47mod peer;
48mod services;
49mod sync;
50
51pub use catalog::{Installed, PluginCatalog, StaticCatalog};
52pub use channel::{Channel, Close, ConnectError, PeerId};
53pub use identity::fingerprint;
54pub use session::plugin::{
55 catalog_key, session_key, Greeted, LocalId, RowHandle, Session, SessionHandle,
56};
57
58/// The error another language threw, inside a rutis error: a row that
59/// failed, a call to a plugin's service that failed. Gives its name, code,
60/// data, stack and site (`docs/design-diagnostics-2026-10-26.md` ยง4.2), so
61/// a host can say it in its own words by code instead of matching text.
62/// `None` for errors rutis or Rust code raised. Takes a `rutis::Error`
63/// (`&error`) or the `ErrorKind` a row's state keeps.
64pub fn thrown(error: &rutis::host::ErrorKind) -> Option<&session::Error> {
65 fn within<'a>(error: &'a (dyn std::error::Error + 'static)) -> Option<&'a session::Error> {
66 if let Some(remote) = error.downcast_ref::<session::Error>() {
67 return matches!(remote, session::Error::Remote { .. }).then_some(remote);
68 }
69 if let Some(call) = error.downcast_ref::<rutis::host::CallError>() {
70 if let Some(remote) = call
71 .raw()
72 .and_then(|raw| raw.downcast_ref::<session::Error>())
73 {
74 return matches!(remote, session::Error::Remote { .. }).then_some(remote);
75 }
76 }
77 if let Some(kind) = error.downcast_ref::<rutis::host::ErrorKind>() {
78 return of_kind(kind);
79 }
80 error.source().and_then(within)
81 }
82 fn of_kind(kind: &rutis::host::ErrorKind) -> Option<&session::Error> {
83 match kind {
84 rutis::host::ErrorKind::PluginFailed(source) => within(source.as_ref()),
85 _ => None,
86 }
87 }
88 of_kind(error)
89}