Roto is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install roto

It will make the roto command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall roto uninstalls.

Adding `roto` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add roto

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

roto = "0.9.0"

The roto library will be automatically available globally. Read the roto library documentation.

Back to the crate overview.

Readme

Roto

Roto is an embedded scripting language for Rust applications that is fast, safe and easy to use.

The language is primarily used by Rotonda, the composable, programmable routing BGP engine. It is made to integrate especially well with Rotonda, so that writing filters is as simple as possible. In addition, Roto can be easily embedded into any Rust application for general purpose scripting.

Read more about it in the documentation.

Example

# A function that returns true if an IP address is equal to 0.0.0.0
fn is_zero(x: IpAddr) -> bool {
    x == 0.0.0.0
}

# A filtermap that only accepts IP addresses of 0.0.0.0
filtermap main(x: IpAddr) {
    if is_zero(x) {
        accept
    } else {
        reject
    }
}

More examples can be found in the examples folder in this repository. They can be run with

cargo run --example <example name>

Features

Roto can be embedded into any Rust application. Rust types and functions can be registered for use in Roto.
Roto is strongly and statically-typed, ensuring that type errors are caught at compile-time. This does not mean that the user has to specify types everywhere, most types can be inferred by the Roto compiler. When the compiler detects a mistake in your script, it will emit a friendly message.
Scripts are compiled to machine code before they are executed. This means that they run quickly and introduce minimal latency into your system.
Roto scripts are hot-reloadable. The host application can recompile scripts at any time.

Limitations

These limitations are fundamental to the design of Roto. They stem from the fact that Roto is a scripting language and that Rust's reflection system is limited.

All registered Rust types must implement Clone or Copy. Rust types that don't implement these traits should be wrapped in an Rc or Arc. The reason for this limitation is that Roto does not have references and freely clones values.
It is not possible to register types that are not concrete. For example, Vec<u32> is possible, but Vec<T> is not. We plan to support registering generic via some form of type erasure.
The parameter and return types of functions exported to the host application must have a 'static lifetime.

Pending features

Some limitations are only present because we haven't come around to implementing them yet. Most limitations can be found in the issue tracker, but we've summarized some important missing features here.

Lists are not supported yet. (#102)
It's not yet possible to declare your own enum types. (#188)
It's not yet possible to declare types with generics and write generic functions. (#189 and #190)

Memory safety

Roto fundamentally relies on unsafe code, after all, we are generating machine code at runtime. However, we treat every unsoundness stemming from use of Roto with safe Rust as a bug of high priority. Please report any issues you find to the GitHub repository.

We run our extensive test suite under Valgrind in CI to ensure that at least most common use cases are correctly implemented.

Security considerations

If you allow users to submit untrusted Roto scripts to your application, you need to be aware that malicious (or erroneous) Roto scripts can do the following:

crash your process by running out of memory with infinite recursion,
loop indefinitely with a while loop, or
be so big that compiling it will slow down your application.

Therefore, we make the following recommendations:

Impose a maximum size on scripts.
Compile and run the untrusted script in a separate process with a timeout and proper handling of unexpected crashes of that process.

Finally, Roto scripts have access to all functions you provide and are therefore as contained as you want them to be. Be careful not to expose information or functionality that compromises the security of your application.

Learn more

To learn how to use and embed Roto, you can read the documentation.
The API docs for the latest version are available on docs.rs
Some examples are available in the examples folder of the Roto repository.

Contributing

If you have comments, proposed changes, or would like to contribute, please open an issue in the GitHub repository. In particular, if you would like to use the crate but it is missing functionality for your use case, we would love to hear from you!

License

Roto is distributed under the terms of the BSD-3-clause license. See LICENSE for details.

Installing the command-line executable

Adding roto library as a dependency

Adding `roto` library as a dependency