This tutorial covers how to build a Deno plugin using Rust and create an async plugin using Rust futures and the deno_core crate.
Deno is a new JavaScript runtime built with Rust and V8 that enables you to run JavaScript outside the browser. Deno is more secure than Node.js because it limits network and file system access by default.
One of the cool things about Deno is that you can write plugins in Rust and use them within Deno code. In this tutorial, we’ll show you how to create Deno plugins in Rust.
Originally published by Anshul Goyal on https://blog.logrocket.com
We’ll cover the following:
Plugins in Deno generally improve performance and provide access to a wider range of tools.
Due to their performant nature, plugins are often used in calculations for heavy tasks such as image processing. Plugins also give you access to a variety of libraries written in other languages, including high-quality Rust crates.
The plugin project structure is the same as any Deno module. For the purpose of this tutorial, you can use this boilerplate:
git clone https://github.com/anshulrgoyal/deno-rust-starter.git my_module
First, build the Rust boilerplate for the plugin:
cd my_module/native
cargo build
Next, run a test to verify that Deno is picking up the correct library:
cd my_module/native
deno test --unstable --allow-plugin
The boilerplate includes a Rust project in the native
directory and a Deno module in the root.
The Rust project compiles a dynamic library that is loaded by the Deno runtime. The file type and name of the library depend on the operating system. The Rust project may compile to a so
file — dylib
or dll
— and the name of the compiled file may also be different. The boilerplate can handle three major platforms: Linux, macOS, and Windows.
[package]
name = "native"
version = "0.1.0"
authors = ["anshul <anshulgoel151999@gmail.com>"]
edition = "2018"
[lib]
name = "native"
crate-type = ["cdylib"]
[dependencies]
deno_core = "0.75.0"
├── README.md
├── deps.ts
├── mod.ts
├── mod_test.ts
├── native
│ ├── Cargo.lock
│ ├── Cargo.toml
│ ├── src
│ └── lib.rs
├── test.ts
├── test_deps.ts
└── tsconfig.json
The mod.ts
file is the main file imported by another application using your module.
For this tutorial, we’ll show you how to build a PNG optimizer using an oxipng
crate. Every Deno plugin must export the deno_plugin_init
function and register all the methods that the plugin exports.
The #[no_mangle]
attribute tells the compiler not to change the name of the function:
#[no_mangle]
pub fn deno_plugin_init(interface: &mut dyn Interface) {
// register the function. Pass name and function to register method
interface.register_op("hello_world",hello_world);
}
Each exported function has the same signature. Deno plugins can only export functions. These functions can be sync or async, depending on the return type.
fn optimise(_interface: &mut dyn Interface,
zero_copy: &mut [ZeroCopyBuf],
) -> Op {
// get first argument
let first=zero_copy.first().unwrap();
let opts: oxipng::Options = Default::default();
// convert vector
let result = oxipng::optimize_from_memory(&first.to_vec(), &opts).unwrap();
// move to heap so that deno can use it
Op::Sync(Box::from(result))
}
The second argument of the function contains an array of buffers. Each buffer in the array represents the argument passed to the exported function when called. These buffers are serialized to strings or other data types based on requirements.
The above code takes the first element of zero_copy
and passes it to optimize_from_memory
. The first element of the array is the file passed to the optimize
function when called from the Deno code. The file is passed as bytes. The function processes the file and returns the result as a Box
. The return type is Op
enum with two variants sync
and async
.
Build the code using the cargo build
command. Now this plugin can be used in Deno.
Now that the plugin is compiled, let’s load it using Deno.
The plugin is still in development and is a part of unstable APIs, so the --unstable
flag is required, as is --allow-plugin
.
let path = ""
// check the type of OS to load correct file
if (Deno.build.os === "linux") {
// linux file emited by rust compiler
path = "./native/target/debug/libnative.so"
} else if (Deno.build.os === "windows") {
// windows file emited by rust compiler
path = "./native/target/debug/native.dll"
} else if (Deno.build.os === "darwin") {
// macos file emited by rust comipler
path = "./native/target/debug/libnative.dylib"
}
// load plugin from file system
const rid = Deno.openPlugin(path);
// Get available methods on plugin
//@ts-Expect-Error
const { optimise:optimise_native } = (Deno as any).core.ops();
export async function optimise(fileName: string): Promise<Uint8Array> {
// reading a file
const file = await Deno.open(fileName);
// getting content
const value = await Deno.readAll(file)
// closing file
await Deno.close(file.rid)
// running the native plugin method using Deno dispatch method
return (Deno as any).core.dispatch(optimise_native, value)
}
Each plugin is loaded using the openPlugin
method. Then, the ops
method is used to get the method identifier, which executes the code exported by the plugin.
dispatch
is used to run code exported by the native plugin. The first argument is the method identifier; the rest are passed for the native function. In this case, the file is passed.
Since Deno is single-threaded, it’s not wise to block the main thread. Deno allows you to return a future from the native function, which you can use with OS threads to write a function that doesn’t block the main thread.
fn optimise_async(_interface: &mut dyn Interface,
zero_copy: &mut [ZeroCopyBuf],
) -> Op {
// get first argument
let first=zero_copy.first().unwrap();
let opts: oxipng::Options = Default::default();
let arg=first.to_vec();
// create a new future
let fut = async move {
// create a channel to send result once done to main thread
let (tx, rx) = futures::channel::oneshot::channel::<oxipng::PngResult<Vec<u8>>>();
// create a new thread
std::thread::spawn(move || {
// perform work
let result = oxipng::optimize_from_memory(&arg, &opts);
// send result to main thread
tx.send(result).unwrap();
});
// receive the result
let result=rx.await;
// create a boxed slice
let result_box = result.unwrap().unwrap().into_boxed_slice();
// return boxed slice from the future
result_box
};
// return the future
Op::Async(fut.boxed())
}
A future is created using the async
block and returned as a boxed future. Deno handles the completion of the future and informs the Deno side of the plugin. A channel is used to communicate between the new thread and the main thread.
The Deno code doesn’t need much updating — just a new asyncHandler
to handle the completion of the task:
let path = ""
if (Deno.build.os === "linux") {
path = "./native/target/debug/libnative.so"
} else if (Deno.build.os === "windows") {
path = "./native/target/debug/native.dll"
} else if (Deno.build.os === "darwin") {
path = "./native/target/debug/libnative.dylib"
}
const rid = Deno.openPlugin(path);
const { optimise_async } = (Deno as any).core.ops();
export async function optimise(fileName: string){
const file = await Deno.open(fileName);
const value = await Deno.readAll(file);
await Deno.close(file.rid);
// new handler
(Deno as any).core.setAsyncHandler(optimise_async, (response:any) => {
Deno.writeFile("l.png",response)
});
// executing the native code.
(Deno as any).core.dispatch(optimise_async,value);
}
await optimise("t.png")
await Deno.close(rid);
In this tutorial, we covered how to build a simple Deno plugin using Rust as well as how to create an async plugin using Rust futures and the deno_core
crate.
Rust has a large ecosystem with high-quality crates. You can use all these crates in Deno by creating plugins. Whether it’s an image processing plugin, database connector, etc., access to Rust plugins helps to expand the Deno ecosystem.
#rust #deno #typescript #javascript