Как написать плагин для rust

The code written in this article is available on GitHub. Feel free to
browse through and steal code or inspiration.

If you found this useful or spotted a bug, let me know on the blog’s
issue tracker!

#include <stdio.h>
#include <stdlib.h>
#include <dlfcn.h>
// Defines LIBM_SO (which will be a string such as "libm.so.6")
#include <gnu/lib-names.h>

// the type signature used by our cosine function
typedef double (*trig_func)(double);

int main() {
    char *error;

    // load the libm library into memory
    void *handle = dlopen(LIBM_SO, RTLD_LAZY);

    // handle loading failures
    if (!handle) {
        fprintf(stderr, "unable to load libm: %sn", dlerror());
        return EXIT_FAILURE;
    }

    // Clear any existing errors
    dlerror();

    // get a pointer to the "cos" symbol and cast it to the right type
    trig_func cosine = (trig_func) dlsym(handle, "cos");

    // were we able to find the symbol?
    error = dlerror();
    if (error != NULL) {
        fprintf(stderr, "cos not found: %sn", error);
        return EXIT_FAILURE;
    }

    // use our cosine function
    printf("cos(2.0) = %fn", (*cosine)(2.0));

    // cleanup and exit
    dlclose(handle);
    return EXIT_SUCCESS;
}

// core/src/lib.rs

pub trait Function {
    fn call(&self, args: &[f64]) -> Result<f64, InvocationError>;

    /// Help text that may be used to display information about this function.
    fn help(&self) -> Option<&str> {
        None
    }
}

pub enum InvocationError {
    InvalidArgumentCount { expected: usize, found: usize },
    Other { msg: String },
}

// core/src/lib.rs

pub struct PluginDeclaration {
    pub rustc_version: &'static str,
    pub core_version: &'static str,
    pub register: unsafe extern "C" fn(&mut dyn PluginRegistrar),
}

// core/src/lib.rs

pub trait PluginRegistrar {
    fn register_function(&mut self, name: &str, function: Box<dyn Function>);
}

// core/build.rs

fn main() {
    let version = rustc_version::version().unwrap();
    println!("cargo:rustc-env=RUSTC_VERSION={}", version);
}

$ cd core
$ cargo add rustc_version
    Updating 'https://github.com/rust-lang/crates.io-index' index
      Adding rustc_version v0.2.3 to build-dependencies

// core/src/lib.rs

pub static CORE_VERSION: &str = env!("CARGO_PKG_VERSION");
pub static RUSTC_VERSION: &str = env!("RUSTC_VERSION");

// core/src/lib.rs

#[macro_export]
macro_rules! export_plugin {
    ($register:expr) => {
        #[doc(hidden)]
        #[no_mangle]
        pub static plugin_declaration: $crate::PluginDeclaration = $crate::PluginDeclaration {
            rustc_version: $crate::RUSTC_VERSION,
            core_version: $crate::CORE_VERSION,
            register: $register,
        };
    };
}

$ cargo new --lib random --name plugins_random
     Created library `plugins_random` package
$ cat Cargo.toml
[workspace]
members = ["core", "random"]

$ cd random
$ cargo add ../core
    Updating 'https://github.com/rust-lang/crates.io-index' index
      Adding plugins_core (unknown version) to dependencies

# random/Cargo.toml

[package]
name = "plugins_random"
version = "0.1.0"
authors = ["Michael Bryan <michaelfbryan@gmail.com>"]
edition = "2018"

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

[dependencies]
plugins_core = { path = "../core" }

$ cargo build --all
   Compiling semver-parser v0.7.0
   Compiling semver v0.9.0
   Compiling rustc_version v0.2.3
   Compiling plugins_core v0.1.0 (/home/michael/Documents/plugins/core)
   Compiling plugins_random v0.1.0 (/home/michael/Documents/plugins/random)
    Finished dev [unoptimized + debuginfo] target(s) in 1.32s
$ ls ../target/debug
build deps examples incremental libplugins_core.d libplugins_core.rlib
libplugins_random.d libplugins_random.so

$ curl 'https://www.random.org/integers/?num=10&min=1&max=6&col=1&base=10&format=plain'
5
2
6
4
5
2
1
4
1
3

// random/src/lib.rs

struct RequestInfo {
    min: i32,
    max: i32,
}

impl RequestInfo {
    pub fn format(&self) -> String {
        format!(
            "https://www.random.org/integers/?num=1&min={}&max={}&col=1&base=10&format=plain",
            self.min, self.max
        )
    }
}

// random/src/lib.rs

fn fetch(request: RequestInfo) -> Result<f64, InvocationError> {
    let url = request.format();
    let response_body = reqwest::get(&url)?.text()?;
    response_body.trim().parse().map_err(Into::into)
}

// core/src/lib.rs

impl<S: ToString> From<S> for InvocationError {
    fn from(other: S) -> InvocationError {
        InvocationError::Other {
            msg: other.to_string(),
        }
    }
}

// random/src/lib.rs

pub struct Random;

impl Function for Random {
    fn call(&self, _args: &[f64]) -> Result<f64, InvocationError> {
        fetch(RequestInfo { min: 0, max: 100 })
    }
}

// get a random number between 0 and 100
fn random() -> f64;
// get a random number between 0 and max
fn random(max: f64) -> f64;
// get a random number between min and max
fn random(min: f64, max: f64) -> f64;

// random/src/lib.rs

fn parse_args(args: &[f64]) -> Result<RequestInfo, InvocationError> {
    match args.len() {
        0 => Ok(RequestInfo { min: 0, max: 100 }),
        1 => Ok(RequestInfo {
            min: 0,
            max: args[0].round() as i32,
        }),
        2 => Ok(RequestInfo {
            min: args[0].round() as i32,
            max: args[1].round() as i32,
        }),
        _ => Err("0, 1, or 2 arguments are required".into()),
    }
}

// random/src/lib.rs

impl Function for Random {
    fn call(&self, args: &[f64]) -> Result<f64, InvocationError> {
        parse_args(args).and_then(fetch)
    }
}

// random/src/lib.rs

plugins_core::export_plugin!(register);

extern "C" fn register(registrar: &mut dyn PluginRegistrar) {
    registrar.register_function("random", Box::new(Random));
}

$ cargo new --lib --name plugins_app app
$ cat Cargo.toml
[workspace]
members = ["core", "random", "app"]
$ cd app
$ cargo add libloading ../core
    Updating 'https://github.com/rust-lang/crates.io-index' index
      Adding libloading v0.5.2 to dependencies
      Adding plugins_core (unknown version) to dependencies

// app/src/main.rs

/// A proxy object which wraps a [`Function`] and makes sure it can't outlive
/// the library it came from.
pub struct FunctionProxy {
    function: Box<dyn Function>,
    _lib: Rc<Library>,
}

impl Function for FunctionProxy {
    fn call(&self, args: &[f64]) -> Result<f64, InvocationError> {
        self.function.call(args)
    }

    fn help(&self) -> Option<&str> {
        self.function.help()
    }
}

// app/src/main.rs

pub struct ExternalFunctions {
    functions: HashMap<String, FunctionProxy>,
    libraries: Vec<Rc<Library>>,
}

impl ExternalFunctions {
    pub fn new() -> ExternalFunctions {
        ExternalFunctions::default()
    }

    pub fn load<P: AsRef<OsStr>>(&mut self, library_path: P) -> io::Result<()> {
        unimplemented!()
    }
}

// app/src/main.rs

struct PluginRegistrar {
    functions: HashMap<String, FunctionProxy>,
    lib: Rc<Library>,
}

impl PluginRegistrar {
    fn new(lib: Rc<Library>) -> PluginRegistrar {
        PluginRegistrar {
            lib,
            functions: HashMap::default(),
        }
    }
}

impl plugins_core::PluginRegistrar for PluginRegistrar {
    fn register_function(&mut self, name: &str, function: Box<dyn Function>) {
        let proxy = FunctionProxy {
            function,
            _lib: Rc::clone(&self.lib),
        };
        self.functions.insert(name.to_string(), proxy);
    }
}

// app/src/main.rs

impl ExternalFunctions {
    ...

    /// Load a plugin library and add all contained functions to the internal
    /// function table.
    ///
    /// # Safety
    ///
    /// A plugin library **must** be implemented using the
    /// [`plugins_core::plugin_declaration!()`] macro. Trying manually implement
    /// a plugin without going through that macro will result in undefined
    /// behaviour.
    pub unsafe fn load<P: AsRef<OsStr>>(
        &mut self,
        library_path: P,
    ) -> io::Result<()> {
        // load the library into memory
        let library = Rc::new(Library::new(library_path)?);

        // get a pointer to the plugin_declaration symbol.
        let decl = library
            .get::<*mut PluginDeclaration>(b"plugin_declaration")?
            .read();

        // version checks to prevent accidental ABI incompatibilities
        if decl.rustc_version != plugins_core::RUSTC_VERSION
            || decl.core_version != plugins_core::CORE_VERSION
        {
            return Err(io::Error::new(
                io::ErrorKind::Other,
                "Version mismatch",
            ));
        }

        let mut registrar = PluginRegistrar::new(Rc::clone(&library));

        (decl.register)(&mut registrar);

        // add all loaded plugins to the functions map
        self.functions.extend(registrar.functions);
        // and make sure ExternalFunctions keeps a reference to the library
        self.libraries.push(library);

        Ok(())
    }
}

Usage: app <plugin-path> <function> <args>...

// app/src/main.rs

struct Args {
    plugin_library: PathBuf,
    function: String,
    arguments: Vec<f64>,
}

// app/src/main.rs

impl Args {
    fn parse(mut args: impl Iterator<Item = String>) -> Option<Args> {
        let plugin_library = PathBuf::from(args.next()?);
        let function = args.next()?;
        let mut arguments = Vec::new();

        for arg in args {
            arguments.push(arg.parse().ok()?);
        }

        Some(Args {
            plugin_library,
            function,
            arguments,
        })
    }
}

// app/src/main.rs

impl ExternalFunctions {
    ...

    pub fn call(&self, function: &str, arguments: &[f64]) -> Result<f64, InvocationError> {
        self.functions
            .get(function)
            .ok_or_else(|| format!(""{}" not found", function))?
            .call(arguments)
    }
}

// app/src/main.rs

use std::alloc::System;

#[global_allocator]
static ALLOCATOR: System = System;

// app/src/main.rs

fn main() {
    // parse arguments
    let args = env::args().skip(1);
    let args = Args::parse(args)
        .expect("Usage: app <plugin-path> <function> <args>...");

    // create our functions table and load the plugin
    let mut functions = ExternalFunctions::new();

    unsafe {
        functions
            .load(&args.plugin_library)
            .expect("Function loading failed");
    }

    // then call the function
    let result = functions
        .call(&args.function, &args.arguments)
        .expect("Invocation failed");

    // print out the result
    println!(
        "{}({}) = {}",
        args.function,
        args.arguments
            .iter()
            .map(ToString::to_string)
            .collect::<Vec<_>>()
            .join(", "),
        result
    );
}

$ cargo run -- ../target/release/libplugins_random.so random
random() = 40
$ cargo run -- ../target/release/libplugins_random.so random 42
random(42) = 15
$ cargo run -- ../target/release/libplugins_random.so random 42 64
random(42, 64) = 54

# Note: the function doesn't support 3 arguments
$ cargo run -- ../target/release/libplugins_random.so random 1 2 3
thread 'main' panicked at 'Invocation failed: Other { msg: "0, 1, or 2 arguments are required" }', src/libcore/result.rs:1165:5
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace.

$ cargo run -- ../target/debug/libplugins_random.so random
    Finished dev [unoptimized + debuginfo] target(s) in 0.02s
     Running `/home/michael/Documents/plugins/target/debug/plugins_app ../target/debug/libplugins_random.so random`
thread 'main' panicked at 'Function loading failed: Custom { kind: Other, error: "../target/debug/libplugins_random.so: undefined symbol: plugin_declaration" }', src/libcore/result.rs:1165:5
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace.

nm ../target/release/libplugins_random.so  | grep plugin
00000000004967b0 D plugin_declaration
0000000000056c60 t _ZN12plugins_core8Function4help17hc92b9e8d4917f964E
0000000000057f60 t _ZN14plugins_random8register17hd43ebfdd726021a4E
0000000000057f80 t _ZN65_$LT$plugins_random..Random$u20$as$u20$plugins_core..Function$GT$4call17h7434ef9b1f1ca59eE
00000000000590f0 t _ZN78_$LT$plugins_core..InvocationError$u20$as$u20$core..convert..From$LT$S$GT$$GT$4from17h3a759bcd267b48a1E

3.1. ABI unstability, it’s much worse than it seems

I recently had this very late realization about ABI stability in Rust. Up until
this point I thought that even though Rust’s ABI is unstable, one could
dynamically load a library safely as long as both the library and the main
binary were compiled with the same exact compiler/std/etc version. I had read
this many times in forums like
this
one on Reddit and in blogposts such as
«Plugins in Rust»,
so I assumed it was true.

But turns out that the ABI may not only break between compiler versions, but
also compiler runs. rustc doesn’t guarantee that a layout is going to be the
same in different executions. This is proved by
rust-lang/compiler-team#457,
the new unstable -Z randomize-layout flag. It’s pretty much self-explanatory:
it randomly reorders repr(rust) layouts for testing purposes. The same thing
could happen in the future without an explicit flag; an optimization may cause
the repr(rust) layouts to change between compilation runs. It’s briefly
mentioned in
the Rust
reference as well:

Props to the devs at the #black-magic channel in
Rust’s Discord server, who helped me understand
this. Specially Yandros and Kixiron, both of them very respectable contributors
to the Rust compiler/community.

This basically means that we are forced to stick to the C ABI with #[repr(C)],
and that we should use abi_stable
in order to have access to a
stable std library as well, instead of re-implementing everything ourselves
from scratch. On the positive side, it means that plugins could be implemented
in any language, but that wasn’t important for Tremor’s case since the beginning
anyway.

3.2. Getting a simple example running

I’ve created the
pdk-experiments repository,
where I’ll write various examples of how the plugin system might work. The first
experiment is in the
dynamic-simple
directory, with a small example of how to dynamically load plugins with Rust.

We first need a crate called common, which defines the interface shared by the
plugin and the runtime in the main binary. In this case it’s just a pointer to a
function with the C ABI. We can specify the ABI with extern "C", or simply
extern, as "C" is already its default value [1]. To keep it simple
it’ll just compute the minimum between two integers:

pub type MinFunction = unsafe extern fn(i32, i32) -> i32;

With it, the plugin crate may export its own implementation. In this case I’ll
declare a static variable, but the example showcases how extern may work as
well. Since we want to use the C ABI, we’ll have to specify crate-type as
cdylib in our Cargo.toml. Note that #[no_mangle] is necessary so that the
variable’s name isn’t mangled and
we can access it when dynamically loading the library.

#[no_mangle]
pub static with_static: MinFunction = min;

pub extern fn min(a: i32, b: i32) -> i32 {
    a.min(b)
}

Finally, the main binary can load the library with libloading
,
which requires a bit of unsafe. I was looking forward to using a different
library because of how easy it seems to end up with undefined behaviour in that
case. I found out sharedlib
was abandoned, as no commits had been
made since 2017, leaving dlopen
as the only alternative. Which was
updated two years ago as well, but their GitHub repo seemed somewhat active in
comparison.

For now, I’ll just use libloading for being the most popular crate, and
perhaps I’ll consider using dlopen in the future. In terms of relevant
features and performance they’re pretty close anyway [2]. Here’s
what the code looks like:

fn run_plugin(path: &str) -> Result<(), libloading::Error> {
    unsafe {
        let library = Library::new(path)?;
        let min = library.get::<*mut MinFunction>(b"plugin_function")?.read();
        println!("Running plugin:");
        println!("  min(1, 2): {}", min(1, 2));
        println!("  min(-10, 10): {}", min(-10, 10));
        println!("  min(2000, 2000): {}", min(2000, 2000));
    }

    Ok(())
}

We can run it with the following commands (though the Makefile in the repo
will do everything for you):

$ cd plugin-sample
$ cargo build --release
$ cd ..
$ cargo run --release -- plugin-sample/target/release/libplugin_sample.so
Running plugin:
  min(1, 2): 1
  min(-10, 10): -10
  min(2000, 2000): 2000

Cool! This raises a few questions that I should learn more about:

3.3. Generating bindings

The public interface for the plugins can be written either in Rust (thanks to
extern "C") or directly in C. There are two commonly used projects when
writing bindings:

Some examples of its usage:

Since we’re going to write the plugin system in Rust, the most appropiate choice
would be to use Rust for the interface as well. And if we wanted to make the
plugin interface available to other languages — which is not a concern right
now — it’d be as “easy” as setting up cbindgen.

3.4. crate-type values

Once again, this difference has to do with the ABIs in the dynamic library
[3]. cdylib is meant for linking into C/C++ programs (so it strips away
all functions that aren’t publicly exported), and dylib is meant for Rust
libraries.

When compiling the previous example with dylib, the resulting shared object
for the plugin has a size of 4.8Mb, whereas with cdylib it’s just 2.9Mb. So
while both of these will work for our C ABI, cdylib is clearly the more
appropiate choice.

3.5. rlib files

rlib is another value for crate-type to generate Rust static libraries,
which can then be imported with extern crate crate_name [3]. But since
rlib files are static libraries, they can’t be loaded at runtime, so they’re
of no use in a plugin system.

Here’s a crazy idea though: What if the rlib files were dynamically loaded as
plugins with the help of MIRI? I recently
learned about it, and quoting its official documentation:

Hmm. Could it possibly be used to interpret Rust code? In some way this would be
very similar to using WebAssembly, but theoretically with less friction, as MIR
is specific to Rust and plugin development would be as easy as in the case of
dynamic loading with Rust-to-Rust FFI. A few things to consider: