Morioh
Login
Tamia Walter

Tamia Walter

3 years ago

How to Build a Deno Plugin using Rust

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:

  • Why write Deno plugins in Rust?
  • Deno plugin project structure
  • Building a Rust project
  • Adding Rust code
  • Creating the optimizer function
  • Loading a Rust plugin in Deno
  • Writing async plugins

Why write Deno plugins in Rust?

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.

Deno plugin project structure

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.

Building a Rust project

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.

Adding Rust code

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);
}

Creating the optimizer function

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.

Loading a Rust plugin 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.

Writing async plugins

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);

Conclusion

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

How to Build a Deno Plugin using Rust
7.10 GEEK