rustbridge

[!CAUTION] Beta Software — This project is under active development and not yet recommended for production use.

• Bundle format (.rbp) should be stable, but may require additional extensions before the 1.0 release
• JSON transport is also approaching stability
• Binary transport is experimental
• Installed locally from source: Not yet published to package registries (Maven Central, NuGet, PyPI)
• API documentation is incomplete

rustbridge lets you write plugins in Rust that can be called from Java, Kotlin, C#, or Python—without dealing with the C ABI directly.

The Problem

flowchart LR
    subgraph chasm["🕳️ The C ABI Chasm"]
        direction TB
        ub["Undefined Behavior"]
        seg["Segfaults"]
        ptr["Raw Pointers"]
        align["Memory Alignment"]
        leak["Memory Leaks"]
        types["Primitive C Types"]
        style chasm fill: #1a1a1a, stroke: #ff4444, color: #ff6666
    end

Calling Rust from other languages typically means writing C bindings. That means dealing with:

• Undefined behavior from incorrect memory handling
• Segfaults from null pointers or use-after-free
• Memory leaks from forgotten deallocations
• Type mismatches between languages
• No error handling (C has no exceptions or Result types)
• Manual serialization of complex data structures

A Solution

With rustbridge, you can write a plugin once, and call it from various languages without needing to cross the C ABI chasm yourself:

flowchart LR
    subgraph safe_rust["🦀 Rust"]
        plugin["Your Plugin<br/><code>impl Plugin</code>"]
    end

subgraph crossing[" "]
direction TB
bridge["🌉 rustbridge"]
chasm["🕳️ C ABI"]
end

subgraph safe_host["☕ Host Language"]
java["Java / Kotlin"]
csharp["C#"]
python["Python"]
end

plugin -- " .rbp bundle " --> bridge
bridge --> java
bridge --> csharp
bridge --> python

style chasm fill: #1a1a1a, stroke:#ff4444, color: #ff6666
style bridge fill:#22aa22, stroke: #44ff44, color: #ffffff
style crossing fill: none, stroke: none
style safe_rust fill: #f5a623, stroke: #ff8c00,color: #000000
style safe_host fill: #4a90d9,stroke: #2e6cb5, color: #ffffff

rustbridge handles the messy bits for you. You write a simple Rust trait implementation, and rustbridge provides:

• Safe memory management across the FFI boundary
• JSON serialization for request/response data
• Structured error handling with typed error codes
• Plugin lifecycle management (startup, shutdown, health checks)
• Logging callbacks that integrate with your host language
• Portable bundles (.rbp files) that work on multiple platforms

Get Started

The fastest way to understand rustbridge is to build something:

📖 Getting Started Guide — Create your first plugin and call it from Java

Or dive into the tutorials (more to come):

Quick Example

Rust plugin:

use rustbridge::prelude::*;

#[derive(Default)]
pub struct EchoPlugin;

#[async_trait]
impl Plugin for EchoPlugin {
    async fn handle_request(&self, _ctx: &PluginContext, type_tag: &str, payload: &[u8]) -> PluginResult<Vec<u8>> {
        match type_tag {
            "echo" => Ok(payload.to_vec()),  // Echo back the input
            _ => Err(PluginError::UnknownMessageType(type_tag.to_string())),
        }
    }
}

rustbridge_entry!(EchoPlugin::default);

Java consumer:

try (Plugin plugin = FfmPluginLoader.load("libecho.so")) {
    String response = plugin.call("echo", "{\"message\": \"Hello!\"}");
    System.out.println(response);  // {"message": "Hello!"}
}

Kotlin, C#, and Python are just as simple. See the language guides below.

The .rbp Bundle

Plugins are distributed as .rbp bundles—portable ZIP files containing libraries for multiple platforms:

# Create a multi-platform bundle
rustbridge bundle create \
  --name my-plugin --version 1.0.0 \
  --lib linux-x86_64:target/release/libmyplugin.so \
  --lib darwin-aarch64:target/release/libmyplugin.dylib \
  --lib windows-x86_64:target/release/myplugin.dll \
  --output my-plugin-1.0.0.rbp

Load from any language—rustbridge auto-detects the platform:

Plugin plugin = BundleLoader.load("my-plugin-1.0.0.rbp");

Language Guides

Building from Source

rustbridge is not yet published to package registries. Build from source:

Rust CLI (for creating plugins and bundles):

git clone https://github.com/jrobhoward/rustbridge.git
cd rustbridge
cargo install --path crates/rustbridge-cli

Java/Kotlin (build and publish to local Maven):

cd rustbridge-java
./gradlew publishToMavenLocal

Then in your project's build.gradle.kts:

repositories {
    mavenLocal()
}
dependencies {
    implementation("com.rustbridge:rustbridge-ffm:0.7.0")  // Java 21+
    // or
    implementation("com.rustbridge:rustbridge-jni:0.7.0")  // Java 17+
}

C# (build and reference locally):

cd rustbridge-csharp
dotnet build

Reference the built DLLs in your project, or use a local NuGet source.

Python (install in development mode):

cd rustbridge-python
pip install -e .

Project Status

Here are the components planned for a 1.0 release:

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick start:

1. Check docs/TASKS.md for open tasks
2. Read docs/SKILLS.md for coding conventions
3. Read docs/TESTING.md for testing guidelines

Technical Documentation

For those who want to understand the internals:

• Architecture — System design and component overview
• Bundle Format — .rbp specification
• Transport Layer — JSON and binary protocols
• Memory Model — Ownership patterns across FFI
• Error Handling — Error codes and patterns
• Plugin Lifecycle — State machine details

Changelog

See CHANGELOG.md for version history.

License

MIT OR Apache-2.0

Attribution

This project includes software licensed under the Unicode License. See NOTICES for details.