Crate roto 

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.

• It’s not yet possible to write generic functions. (#190)
• It’s not yet possible to create global constants. (#344)
• Functions are not yet first-class, meaning that they cannot be passed around as values. (#122)
• Roto does not have maps/dictionaries yet. (#345)

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.
• If you have questions, you can ask them on the community forum.
• 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 thread on the community forum. 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!

See CONTRIBUTING.md for more information.

License

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

Modules

__internal

Items exported only for use in macros

tools

Some tools for working with Roto scripts (currently only printing it)

Macros

library

Create a list of items to be registered.

location

Rust source code location

Structs

Constant

A constant value

ContextDescription

Description of Context type

Ctx

A type indicating that a context type T is being used.

FileTree

A set of files loaded and ready to be parsed

Function

A function that can be registered.

Impl

An impl block, which adds methods to a type.

Library

A collection of registerable items.

List

A Roto list

Location

A source file location

Module

A module containing other items

NoCtx

A type indicating that no context type is being used.

Package

The final compiled package of script.

RegistrationError

An error that arose while registering items from a library

RotoReport

An error report containing a set of Roto errors.

Runtime

Provides the types and functions that Roto can access via FFI

SourceFile

A filename with its contents

Type

A Roto type

TypedFunc

A function extracted from Roto

Use

A use item, representing an import of items.

Val

A wrapper type that makes a registered type safe to pass to and from Roto.

Enums

FileSpec

Directory structure that makes up a Roto script

Item

A registerable item

Verdict

A Verdict is the output of a filtermap

Traits

Context

The context or environment that a Roto script runs in

Registerable

Trait implemented by items that can be registered into the Runtime.

RegisterableFn

Trait implemented by functions that can be registered in a runtime.

RotoFunc

Parameters of a Roto function

Value

A type that can be passed to Roto.

Functions

cli

Run a basic CLI for a given runtime

Attribute Macros

roto_function

roto_method

roto_static_method

Derive Macros

Context