Skip to main content

Crate rustbridge

Crate rustbridge 

Source
Expand description

§rustbridge

A framework for developing Rust shared libraries callable from other languages.

rustbridge uses C ABI under the hood but abstracts the complexity, providing:

  • OSGI-like lifecycle management
  • Mandatory async (Tokio) runtime
  • Logging callbacks to host language
  • JSON-based data transport with optional binary transport

§Quick Start

Add to your Cargo.toml:

[lib]
crate-type = ["cdylib"]

[dependencies]
rustbridge = "0.6"

§Creating a Plugin

ⓘ
use rustbridge::prelude::*;

#[derive(Debug, Serialize, Deserialize, Message)]
#[message(tag = "echo")]
pub struct EchoRequest {
    pub message: String,
}

#[derive(Debug, Serialize, Deserialize)]
pub struct EchoResponse {
    pub message: String,
}

#[derive(Default)]
pub struct MyPlugin;

#[async_trait]
impl Plugin for MyPlugin {
    async fn on_start(&self, _ctx: &PluginContext) -> PluginResult<()> {
        tracing::info!("Plugin started");
        Ok(())
    }

    async fn handle_request(
        &self,
        _ctx: &PluginContext,
        type_tag: &str,
        payload: &[u8],
    ) -> PluginResult<Vec<u8>> {
        match type_tag {
            "echo" => {
                let req: EchoRequest = serde_json::from_slice(payload)?;
                Ok(serde_json::to_vec(&EchoResponse { message: req.message })?)
            }
            _ => Err(PluginError::UnknownMessageType(type_tag.to_string())),
        }
    }

    async fn on_stop(&self, _ctx: &PluginContext) -> PluginResult<()> {
        tracing::info!("Plugin stopped");
        Ok(())
    }
}

// Generate FFI entry point
rustbridge_entry!(MyPlugin::default);

// Re-export FFI functions for the shared library
pub use rustbridge::ffi_exports::*;

§Crate Structure

This is a facade crate that re-exports from:

Re-exports§

pub use serde;
pub use serde_json;
pub use tokio;
pub use tracing;

Modules§

ffi_exports
FFI function exports that plugins must re-export.
prelude
Prelude module for convenient imports.

Macros§

impl_plugin
Macro to implement the Plugin trait with handler dispatch
rustbridge_entry
Generate the FFI entry point for a plugin

Structs§

FfiBuffer
Buffer for passing data across FFI boundary
PluginConfig
Plugin configuration passed during initialization
PluginContext
Context provided to plugin operations
PluginHandle
Handle to an initialized plugin instance
PluginHandleManager
Manages plugin handles
PluginMetadata
Plugin metadata from bundle manifest
RequestContext
Context for an incoming request
ResponseBuilder
Builder for constructing responses

Enums§

LifecycleState
Plugin lifecycle states following OSGI-inspired model
LogLevel
Log levels for FFI callbacks
PluginError
Error type for plugin operations

Traits§

Plugin
Main trait for implementing rustbridge plugins
PluginFactory
Factory trait for creating plugins with optional configuration.

Functions§

register_binary_handler
Register a binary message handler

Type Aliases§

PluginResult
Result type alias for plugin operations

Attribute Macros§

async_trait
rustbridge_handler
Attribute for marking a method as a message handler
rustbridge_plugin
Attribute for marking a struct as a rustbridge plugin

Derive Macros§

Message
Derive macro for message types