brpc-rs: Apache BRPC 库的 Rust 实现

Apache BRPC 是一个工业级 RPC 框架，用于构建可靠和高性能的服务。 brpc-rs 允许使用 Rust 编程语言实现 BRPC 客户端和服务器。

状态

此项目目前处于积极开发中的原型阶段。许多 API 都缺失；提供的 API 在 1.0 之前不会保证稳定。

仓库结构

• 项目根目录
  • brpc-build
    • brpc-build 包，编译时代码生成器
  • brpc-protoc-plugin
    • brpc-protoc-plugin 包，Google Protobuf 编译器的插件
  • brpc-sys
    • brpc-sys 包，Apache BRPC 的 FFI 绑定
  • 示例
    • 示例
  • src
    • brpc-rs 包，Rust 对 brpc-rs 的 API

此图说明了这些包如何协同工作

快速入门

先决条件

首先 构建 并 安装 Apache BRPC。请参阅 getting_started.md 中的说明。

或者，您可以使用 Apache BRPC 0.9.6 的预构建 deb 软件包为 Ubuntu 16.04/18.04。这些不是官方软件包。

确保已安装这些依赖项

$ sudo apt-get install libprotobuf-dev libprotoc-dev protobuf-compiler
$ sudo apt-get install libssl-dev libgflags-dev libleveldb-dev

从 crates.io 安装 brpc-protoc-plugin。

$ cargo install brpc-protoc-plugin --version 0.1.0-alpha4

现在我们可以开始一个 brpc-rs 项目了。

Cargo.toml

让我们创建一个小的包，echo_service，它包含一个 echo_client 和一个 echo_server。

$ cargo new echo_service && cd echo_service

在 Cargo.toml 中，将 brpc-rs、prost 和 bytes 添加到 [dependencies] 部分；将 brpc-build 添加到 [build-dependencies] 部分。例如：

[build-dependencies]
brpc-build = "0.1.0"

[dependencies]
brpc-rs = "0.1.0"
prost = "0.5.0"
bytes = "0.4.12"

在 Cargo.toml 中定义两个二进制文件：echo_client 和 echo_server

[[bin]]
name = "echo_client"
path = "src/client.rs"

[[bin]]
name = "echo_server"
path = "src/server.rs"

build.rs

将 protobuf 文件 echo.proto 放入 src 目录。该文件定义了 EchoRequest、EchoResponse 和 EchoService。

syntax="proto2";
package example;
message EchoRequest {
      required string message = 1;
};
message EchoResponse {
      required string message = 1;
};
service EchoService {
      rpc echo(EchoRequest) returns (EchoResponse);
};

在 Cargo.toml 中的 [package] 部分添加一行 build = "build.rs"。然后，创建一个名为 build.rs 的文件，从 src/echo.proto 生成绑定。

fn main() {
    brpc_build::compile_protos(&["src/echo.proto"],
                               &["src"]).unwrap();
}

注意 echo.proto 中的 package 名称是 example。因此，build.rs 会生成两个名为 example.rs 和 example.brpc.rs 的文件。

src/server.rs

接下来让我们实现 echo 服务器。创建 src/server.rs 如下：

use brpc_rs::{Server, ServerOptions, ServiceOwnership};

pub mod echo {
    include!(concat!(env!("OUT_DIR"), "/example.rs"));
    include!(concat!(env!("OUT_DIR"), "/example.brpc.rs"));
}

fn main() {
    let mut service = echo::EchoService::new();
    service.set_echo_handler(&mut move |request, mut response| {
        response.message = request.message.clone();
        Ok(())
    });

    let mut server = Server::new();
    let mut options = ServerOptions::new();
    options.set_idle_timeout_ms(1000);
    server
        .add_service(&service, ServiceOwnership::ServerDoesntOwnService)
        .expect("Failed to add service");
    server.start(50000, &options).expect("Failed to start service");
    server.run(); // Run until CTRL-C
}

因为 EchoService 在 echo.proto 中定义了一个名为 echo() 的函数，所以 brpc-protoc-plugin 为 EchoService 生成了 set_echo_handler() 的 Rust 定义。函数 set_echo_handler() 接受一个闭包，该闭包处理来自客户端的 EchoRequest 并返回一个包含相同消息的 EchoResponse。其余行创建一个监听在 0.0.0.0:50000 的服务器。

src/client.rs

use brpc_rs::{Channel, ChannelOptions};

pub mod echo {
    include!(concat!(env!("OUT_DIR"), "/example.rs"));
    include!(concat!(env!("OUT_DIR"), "/example.brpc.rs"));
}

fn main() {
    let mut options = ChannelOptions::new();
    options.set_timeout_ms(100);
    let addr = "127.0.0.1:50000".parse().expect("Invalid socket address");
    let ch = Channel::with_options(&addr, &options);
    let client = echo::EchoServiceStub::with_channel(&ch);
    let request = echo::EchoRequest {
        message: "hello".to_owned(),
    };
    match client.echo(&request) {
        Ok(r) => println!("Response: {:?}", r),
        Err(e) => eprintln!("Error: {:?}", e),
    }
}

客户端首先创建一个 Channel 并使用该通道初始化一个 service_stub。然后，客户端调用 service_stub.echo() 来发送一个请求。

运行客户端和服务器

$ cargo run --bin echo_server &
$ cargo run --bin echo_client
Response: EchoResponse { message: "hello" }

维护者

• Jing Yiming <jingyiming@baidu.com> @kevinis

许可证

brpc-rs 根据 Apache License，版本 2.0 提供。复制请参阅 LICENSE 文件。