Neon Frame

一个高度定制的框架，用于构建基于 Neon 的 Rust 库以供 Node 使用。 Neon Frame 为 Rust 库提供一个标准的接口，以便响应 JavaScript。它负责处理错误并将响应转换回 JS。

Neon Frame 通过统一处理和转换结果和错误的方式简化了处理器的逻辑。现在您只需编写一个返回 Result<T, E> 的常规方法，它就会自动转换为 Node 并返回。

您可以选择使用通道，在这种情况下，Neon Frame 的 JavaScript 端会包装这些调用以获得一个普通的 Promise<T>。

安装

.Cargo.toml [来源，toml]

[dependencies]
neon-frame = "0.1"
neon-frame-macro = "0.1"

.package.json [来源，json]

"dependencies": {
    "@emeraldpay/neon-frame": "^0.1.1"
}

.JS 导入 [来源，typescript]

import {neonFrameCall} from "@emeraldpay/neon-frame";

关于其用法的简要介绍

Rust 端

.现在您可以使用 #[neon_frame_fn] 宏标记一个函数：[来源，rust]

#[macro_use]
extern crate neon_frame_macro;

#[neon_frame_fn]
pub fn function_hello_world(_cx: &mut FunctionContext) -> Result<String, Errors> {
    Ok("Hello World".to_string())
}

该宏会自动将 Rust 类型转换为 Node 类型。除了 String 之外，它可以是任何 Serializable 结构。内部它只是将其包装成一个 JSON，这可以在 Node 端轻松处理。

JavaScript 端

[来源，typescript]

import {neonFrameDirectCall} from "@emeraldpay/neon-frame";

// eslint-disable-next-line @typescript-eslint/no-var-requires
const addon = require('path/to/index.node');

export function helloWorld(): string {
    return neonFrameDirectCall<string>(addon, "function_hello_world", []);
}

如果您想在单独的线程中处理某些内容怎么办？例如，在 JavaScript 中异步地作为 Promise 获取它？

Rust 端使用通道

.使用 #[neon_frame_fn) 宏，它为您提供了一个回调函数：[来源，rust]

#[neon_frame_fn(channel)]
pub fn function_default_channel<H>(_cx: &mut FunctionContext, handler: H) -> Result<(), Errors>
    where
        H: FnOnce(Result<String, Errors>) + Send + 'static {

    std::thread::spawn(move || {
        let result = "Hello World".to_string();
        handler(Ok(result));
    });

    Ok(())
}

JavaScript 端使用 Promise

[来源，typescript]

import {neonFrameHandlerCall} from "@emeraldpay/neon-frame";

// eslint-disable-next-line @typescript-eslint/no-var-requires
const addon = require('path/to/index.node');

export function default_channel(): Promise<string> {
    return neonFrameHandlerCall<string>(addon, "function_default_channel", []);
}

示例

在 /integration-tests 目录中，您可以找到交互测试，这些测试也可以作为实现示例。

如何工作及细节

作为响应，它使用类似于 JSON 的格式：[来源，json]

{
  "succeeded": true,
  "result": {
    "foo": "bar"
  }
}

其中 {"foo": "bar"} 表示实际结果。

如果方法失败，则返回类似的内容。

[source, json]

{
  "succeeded": false,
  "error": {
    "code": 100,
    "message": "Invalid input value for #0"
  }
}

作为一个 TypeScript 类型，它是

[来源，typescript]

type Status<T> = {
    succeeded: boolean,
    result: T | undefined,
    error: {
        code: number,
        message: string
    } | undefined
}

要使用 Neon Frame，只需在方法上添加注解 #[neon_frame_fn]

[source, rust]

#[neon_frame_fn]
pub fn hello_world(cx: &mut FunctionContext) -> Result<String, MyError> {
    Ok("Hello World".to_string())
}

注意：该方法预期使用 cx: &mut FunctionContext 而不是 mut cx: FunctionContext。

此外，您需要编写一个从 MyError 到 (usize, String) 的转换器。即实现以下 trait：impl From<MyError> for (usize, String)

impl From<MyError> for (usize, String) {
    fn from(err: MyError) -> Self {
        todo!()
    }
}

// function called from JS as:
//
// hello_world((x) => { ... });
//
#[neon_frame_fn(channel)]
pub fn hello_world<H>(cx: &mut FunctionContext, handler: H) -> Result<(), MyError>
    where
        H: FnOnce(Result<String, MyError>) + Send + 'static {

    std::thread::spawn(move || {
        handler(Ok("Hello World".to_string()));
    });
    Ok(())
}

// function called from JS as:
//
// hello_world("hi", "there", (x) => { ... });
//
// i.e. with handler at the 3rd position, which is 2 starting from zero
//
#[neon_frame_fn(channel=2)]
pub fn hello_world<H>(cx: &mut FunctionContext, handler: H) -> Result<(), MyError>
    where
        H: FnOnce(Result<String, MyError>) + Send + 'static {

    todo!()
}