rustbridge/
lib.rs

1//! # rustbridge
2//!
3//! A framework for developing Rust shared libraries callable from other languages.
4//!
5//! rustbridge uses C ABI under the hood but abstracts the complexity, providing:
6//! - OSGI-like lifecycle management
7//! - Mandatory async (Tokio) runtime
8//! - Logging callbacks to host language
9//! - JSON-based data transport with optional binary transport
10//!
11//! ## Quick Start
12//!
13//! Add to your `Cargo.toml`:
14//!
15//! ```toml
16//! [lib]
17//! crate-type = ["cdylib"]
18//!
19//! [dependencies]
20//! rustbridge = "0.6"
21//! ```
22//!
23//! ## Creating a Plugin
24//!
25//! ```ignore
26//! use rustbridge::prelude::*;
27//!
28//! #[derive(Debug, Serialize, Deserialize, Message)]
29//! #[message(tag = "echo")]
30//! pub struct EchoRequest {
31//!     pub message: String,
32//! }
33//!
34//! #[derive(Debug, Serialize, Deserialize)]
35//! pub struct EchoResponse {
36//!     pub message: String,
37//! }
38//!
39//! #[derive(Default)]
40//! pub struct MyPlugin;
41//!
42//! #[async_trait]
43//! impl Plugin for MyPlugin {
44//!     async fn on_start(&self, _ctx: &PluginContext) -> PluginResult<()> {
45//!         tracing::info!("Plugin started");
46//!         Ok(())
47//!     }
48//!
49//!     async fn handle_request(
50//!         &self,
51//!         _ctx: &PluginContext,
52//!         type_tag: &str,
53//!         payload: &[u8],
54//!     ) -> PluginResult<Vec<u8>> {
55//!         match type_tag {
56//!             "echo" => {
57//!                 let req: EchoRequest = serde_json::from_slice(payload)?;
58//!                 Ok(serde_json::to_vec(&EchoResponse { message: req.message })?)
59//!             }
60//!             _ => Err(PluginError::UnknownMessageType(type_tag.to_string())),
61//!         }
62//!     }
63//!
64//!     async fn on_stop(&self, _ctx: &PluginContext) -> PluginResult<()> {
65//!         tracing::info!("Plugin stopped");
66//!         Ok(())
67//!     }
68//! }
69//!
70//! // Generate FFI entry point
71//! rustbridge_entry!(MyPlugin::default);
72//!
73//! // Re-export FFI functions for the shared library
74//! pub use rustbridge::ffi_exports::*;
75//! ```
76//!
77//! ## Crate Structure
78//!
79//! This is a facade crate that re-exports from:
80//! - [`rustbridge_core`] - Core traits, types, and lifecycle
81//! - [`rustbridge_macros`] - Procedural macros (`Message`, `rustbridge_entry!`)
82//! - [`rustbridge_ffi`] - FFI exports and buffer management
83
84// Re-export core types
85pub use rustbridge_core::{
86    LifecycleState, LogLevel, Plugin, PluginConfig, PluginContext, PluginError, PluginFactory,
87    PluginMetadata, PluginResult, RequestContext, ResponseBuilder,
88};
89
90// Re-export macros
91pub use rustbridge_macros::{
92    Message, impl_plugin, rustbridge_entry, rustbridge_handler, rustbridge_plugin,
93};
94
95// Re-export FFI types
96pub use rustbridge_ffi::{FfiBuffer, PluginHandle, PluginHandleManager, register_binary_handler};
97
98// Re-export common dependencies that plugin authors need
99pub use async_trait::async_trait;
100pub use serde;
101pub use serde_json;
102pub use tokio;
103pub use tracing;
104
105/// FFI function exports that plugins must re-export.
106///
107/// Add `pub use rustbridge::ffi_exports::*;` at the end of your plugin's lib.rs
108/// to expose the required FFI functions for the shared library.
109pub mod ffi_exports {
110    pub use rustbridge_ffi::{
111        plugin_call, plugin_call_async, plugin_call_raw, plugin_cancel_async, plugin_free_buffer,
112        plugin_get_rejected_count, plugin_get_state, plugin_init, plugin_set_log_level,
113        plugin_shutdown, rb_response_free,
114    };
115}
116
117/// Prelude module for convenient imports.
118///
119/// Use `use rustbridge::prelude::*;` to import commonly used types.
120///
121/// This includes:
122/// - Core traits: `Plugin`, `PluginFactory`
123/// - Core types: `PluginConfig`, `PluginContext`, `PluginError`, `PluginResult`
124/// - Lifecycle: `LifecycleState`, `LogLevel`
125/// - Macros: `Message`, `rustbridge_entry!`, `rustbridge_plugin`, `rustbridge_handler`
126/// - Common deps: `async_trait`, `Serialize`, `Deserialize`
127pub mod prelude {
128    // Core traits and types
129    pub use crate::{
130        LifecycleState, LogLevel, Plugin, PluginConfig, PluginContext, PluginError, PluginFactory,
131        PluginResult, async_trait,
132    };
133
134    // Macros
135    pub use rustbridge_macros::{Message, rustbridge_entry, rustbridge_handler, rustbridge_plugin};
136
137    // Serde derives (commonly needed for message types)
138    pub use serde::{Deserialize, Serialize};
139}
rustbridge/lib.rs

rustbridge/
lib.rs
