Skip to main content

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}