A Rust Extension for Neutralino >= 5.0.0

This extension adds a Rust backend to Neutralino with the following features:

• Requires only a few lines of code on both ends.
• Read all events from the Neutralino app in your Rust code.
• Run Rust functions from Neutralino.
• Run Neutralino functions from Rust.
• All communication between Neutralino and Rust runs asynchronously.
• All events are queued, so none will be missed during processing.
• Track the data flow between Neutralino and Rust in realtime.
• Works in Window- and headless Cloud-Mode.
• Terminates the Rust Runtime when the Neutralino app quits.

The demo opens a Neutralino app. Clicking on the blue link sends a Ping to Rust, which replies with Pong. This illustrates the data-flow in both directions.

Before running the demo, the Rust extension needs to be compiled with Rust. Make this folder the project root for your Rust-compiler:

/extensions/rust

Then build with:

cargo build --release

The demo is configured to launch the Rust-extension binary directly from its build-target's release folder.

After this, run these commands in the ext-rust folder:

neu update
neu run

Follow these steps:

• Adapt the Rust code in extensions/rust/main.rs to your needs.
• Build the Rust-binary.
• Create an empty /extensions/rust folder, used by your installer.
• Copy the Rust-binary to /extensions/rust
• Copy this /extensions folder to your project.
• Copy resources/js/rust-extension.js to resources/js.
• Add <script src="js/rust-extension.js"></script> to your index.html
• Add const RUST = new RustExtension(true) to your main.js
• Add RUST.run(function_name, data) to main.js to run Rust-functions from Neutralino.
• Add event listeners to main.js, to fetch result data from Rust.
• Modify neutralino.config.json (see below).

Make sure that neutralino.config.json contains this, adapted to your environment:

"extensions": [
  {
    "id": "extRust",
    "commandDarwin": "${NL_PATH}/extensions/rust/target/release/ext-rust ${NL_PATH}",
    "commandWindows": "${NL_PATH}/extensions/rust/target/release/ext-rust.exe ${NL_PATH}"
  }
],

mod neutralino;

const DEBUG_EXT_RUST: bool = true;

fn process_app_event(ext: &mut neutralino::Extension, d: &mut serde_json::Value) {

    if ext.is_event(d, "runRust") {
        let data = ext.get_data(d);

        if data["function"].as_str().unwrap() == "ping" {
            let p = data["parameter"].as_str().unwrap();

            let msg = format!("Rust says PONG in reply to '{}'", &p);
            ext.send_message("pingResult", &msg);
        }
    }
}

fn main() {
    let mut ext = neutralino::Extension::new();
    ext.run(process_app_event);
}

The extension is activated in main(). process_app_event is a callback function, which is triggered with each event coming from the Neutralino app.

In the callback function, you can process the incoming events by their name. In this case we react to the "runRust" event. data["function"] holds the requested Rust-function and data["parameter"] its data payload as JSON.

If the requested function is named ping, we send back a message to the Neutralino frontend.

send_message() requires the following parameters:

• An event name, here "pingResult"
• The data package to send, which can be a string or stringified JSON.

The DEBUG_EXT_RUST constant tells the NeutralinoExtension to report each event to the console. Incoming and outgoing messages are printed in different colors.

This makes debugging easier, since you can track the data flow between Neutralino and Rust:

async function onPingResult(e) {
...
}

// Init Neutralino
//
Neutralino.init();
...
Neutralino.events.on("pingResult", onPingResult);
...
// Init Bun Extension
const RUST = new RustExtension(true)

The last line initializes the JavaScript part of the Rust-extension. It's important to place this after Neutralino.init() and after all event handlers have been installed. Put it in the last line of your code and you are good to go. The const RUST is accessible globally and must not be renamed to something else.

The RustExtension class takes only 1 argument which instructs it to run in debug mode (here true). In this mode, all data coming from the extension is printed to the dev-console:

The pingResult event handler listens to messages with the same name, sent by send_message() on Rust's side.

In index.html, you can see how to send data from Neutralino to Rust, which is dead simple:

<a href="#" onclick="RUST.run('ping', 'Neutralino says PING!');">Send PING to Rust</a><br>

RUST.run() takes 2 arguments:

• The Bun function to call, here "ping"
• The data package to submit, either as string or JSON.

For details how to start a long-running background task in Rust and how to poll its progress, see the comments in extensions/rust/main.rsand resources/js/main.js.

Before a new task is spawned, Rust sends a startPolling-message to the frontend. As a result, the frontend sends a poll-message every 500 ms.

All progress-messages of the long-running task are stored in a queue. Before the task ends, it pushes a stopPolling-message to the queue:

graph LR;
  id[stopPolling]-->id2[Progress 3/3];
  id2[Progress 3/3]-->id3[Progress 2/3];
  id3[Progress 2/3]-->id4[Progress 1/3];
 

Each incoming poll-message forces Rust to stop listening on the WebSocket and processing the queue instead. When the stopPolling-message is sent back, the frontend stops polling.

Extension Module:

Events sent from the extension to the frontend:

RustExtension Class:

Events, sent from the frontend to the extension:

• NeutralinoJS Home

• Neutralino Build Automation for macOS, Windows, Linux

• Neutralino related blog posts at marketmix.com