Rust SDK Manual on Apache Dubbo

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

View the complete example here.

1 Prerequisites

Install the Rust development environment
Install the protoc tool

2 Define Dubbo Services Using IDL

The Greeter service is defined as follows, including a Dubbo service with a Unary (request-response) model.

// ./proto/greeter.proto
syntax = "proto3";

option java_multiple_files = true;

package org.apache.dubbo.sample.tri;


// The request message containing the user's name.
message GreeterRequest {
 string name = 1;
}

// The response message containing the greetings
message GreeterReply {
 string message = 1;
}

service Greeter{
 // unary
 rpc greet(GreeterRequest) returns (GreeterReply);
}

# ./Cargo.toml
[package]
name = "example-greeter"
version = "0.1.0"
edition = "2021"

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

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

[dependencies]
http = "0.2"
http-body = "0.4.4"
futures-util = {version = "0.3", default-features = false}
tokio = { version = "1.0", features = [ "rt-multi-thread", "time", "fs", "macros", "net", "signal"] }
prost-derive = {version = "0.10", optional = true}
prost = "0.10.4"
async-trait = "0.1.56"
tokio-stream = "0.1"

dubbo = "0.1.0"
dubbo-config = "0.1.0"

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

4 Configure dubbo-build to Compile IDL

Create a build.rs file in the project root directory (not /src) and add the following content:

Interoperability between Rust and Java

Mon, 01 Jan 0001 00:00:00 +0000

1 Prerequisites

Install the Rust development environment
Install the protoc tool
Install the Java development environment

2 Run the Example Java Version of Dubbo Provider

The source code for the Java version of the Dubbo provider can be found at https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple.

Clone the source code, compile, and run the provider:

$ # clone the source code
$ git clone https://github.com/apache/dubbo-samples.git
$ cd dubbo-samples/dubbo-samples-triple/

$ # build
$ mvn clean compile package -DskipTests

$ # run the provider
$ java -Dprovider.port=8888 -jar ./target/dubbo-samples-triple-1.0-SNAPSHOT.jar
# … omitted part of the logs
Dubbo triple stub server started, port=8888

Interface definition on the Java side

Service Discovery

Mon, 01 Jan 0001 00:00:00 +0000

Introduction to Dubbo Rust Service Discovery

Dubbo Rust provides a client-based service discovery mechanism that relies on third-party registry components to coordinate the service discovery process. Supported registries: Nacos, Zookeeper.

The following is a basic working principle diagram of the Dubbo Rust service discovery mechanism:

Service discovery involves three participant roles: provider, consumer, and registry. The Dubbo provider instance registers its URL with the registry, which is responsible for aggregating the data. The Dubbo consumer reads the address list from the registry and subscribes to changes. Whenever the address list changes, the registry notifies all subscribed consumer instances with the latest list.

Service Routing Rules

Mon, 01 Jan 0001 00:00:00 +0000

Conditional Routing

The usage pattern is similar to the Conditional Routing Documentation, but the configuration format is slightly different. Below is an example of conditional routing rules.

Based on the following example rule, all calls to the greet method of the org.apache.dubbo.sample.tri.Greeter service will be forwarded to a subset of addresses marked with port=8888.

configVersion: v1.0
scope: "service"
force: false
enabled: true
key: "org.apache.dubbo.sample.tri.Greeter"
conditions:
 - method=greet => port=8888

Note:
The Dubbo Rust currently does not distinguish at the application level, and cannot differentiate the origin of the service.
Therefore, for tag routing and conditional routing, only one application-level configuration can be specified.
For application-level configuration, the default key is set to application, and this configuration will affect all services.
For example:

Communication using Unix Socket Connector

Mon, 01 Jan 0001 00:00:00 +0000

This article focuses on using the Dubbo Rust Triple protocol with Unix sockets. Please refer to the Quick Start for basic usage of Dubbo Rust, and you can see the complete example here.

1 Explanation of Using Unix Socket Connector

#[cfg(any(target_os = “macos”, target_os=“unix”))] The unix module will be compiled for use when the operating system meets the cfg configuration, otherwise it cannot be used.

2 Logic for Using Unix Socket Connector with client/connection

2.1 Writing the Client Side

// examples/echo/src/echo/client.rs
// Initialize Client using ClientBuilder
let builder = ClientBuilder::new().with_connector("unix").with_host("unix://127.0.0.1:8888");
let mut cli = EchoClient::build(builder);

2.2 Writing the Server Side

// examples/echo/src/echo/server.rs
// Initialize Server using serverbuilder
let builder = ServerBuilder::new()
 .with_listener("unix".to_string())
 .with_service_names(vec!["grpc.examples.echo.Echo".to_string()])
 .with_addr("127.0.0.1:8888");
builder.build().serve().await.unwrap();

3 Running Example

Compile

Run cargo build to compile the server and client.

Streaming Communication Model

Mon, 01 Jan 0001 00:00:00 +0000

This article focuses on the Dubbo Rust Streaming communication pattern. Please refer to the Quick Start to understand the basic usage of Dubbo Rust and view the complete example for this article.

1 Adding Streaming Model Definitions in IDL

The complete Greeter service definition is as follows, which includes a Unary, Client stream, Server stream, and Bidirectional stream model for Dubbo services.

// ./proto/greeter.proto
syntax = "proto3";

option java_multiple_files = true;

package org.apache.dubbo.sample.tri;


// The request message containing the user's name.
message GreeterRequest {
 string name = 1;
}

// The response message containing the greetings
message GreeterReply {
 string message = 1;
}

service Greeter{

 // unary
 rpc greet(GreeterRequest) returns (GreeterReply);

 // clientStream
 rpc greetClientStream(stream GreeterRequest) returns (GreeterReply);

 // serverStream
 rpc greetServerStream(GreeterRequest) returns (stream GreeterReply);

 // bi streaming
 rpc greetStream(stream GreeterRequest) returns (stream GreeterReply);

}

2 Writing Logic with Streaming Model Definitions

2.1 Writing the Streaming Server

// ./src/greeter/server.rs
pub mod protos {
 include!(concat!(env!("OUT_DIR"), "/org.apache.dubbo.sample.tri.rs"));
}

use futures_util::StreamExt;
use protos::{
 greeter_server::{register_server, Greeter},
 GreeterReply, GreeterRequest,
};

use std::{io::ErrorKind, pin::Pin};

use async_trait::async_trait;
use futures_util::Stream;
use tokio::sync::mpsc;
use tokio_stream::wrappers::ReceiverStream;

use dubbo_config::RootConfig;
use dubbo::{codegen::*, Dubbo};

type ResponseStream =
 Pin<Box<dyn Stream<Item = Result<GreeterReply, dubbo::status::Status>> + Send>>;

#[tokio::main]
async fn main() {
 register_server(GreeterServerImpl {
 name: "greeter".to_string(),
 });

 // Dubbo::new().start().await;
 Dubbo::new()
 .with_config({
 let r = RootConfig::new();
 match r.load() {
 Ok(config) => config,
 Err(_err) => panic!("err: {:?}", _err), // response was dropped
 }
 })
 .start()
 .await;
}

#[allow(dead_code)]
#[derive(Default, Clone)]
struct GreeterServerImpl {
 name: String,
}

// #[async_trait]
#[async_trait]
impl Greeter for GreeterServerImpl {
 async fn greet(
 &self,
 request: Request<GreeterRequest>,
 ) -> Result<Response<GreeterReply>, dubbo::status::Status> {
 println!("GreeterServer::greet {:?}", request.metadata);

 Ok(Response::new(GreeterReply {
 message: "hello, dubbo-rust".to_string(),
 }))
 }

 async fn greet_client_stream(
 &self,
 request: Request<Decoding<GreeterRequest>>,
 ) -> Result<Response<GreeterReply>, dubbo::status::Status> {
 let mut s = request.into_inner();
 loop {
 let result = s.next().await;
 match result {
 Some(Ok(val)) => println!("result: {:?}", val),
 Some(Err(val)) => println!("err: {:?}", val),
 None => break,
 }
 }
 Ok(Response::new(GreeterReply {
 message: "hello client streaming".to_string(),
 }))
 }

 type greetServerStreamStream = ResponseStream;
 async fn greet_server_stream(
 &self,
 request: Request<GreeterRequest>,
 ) -> Result<Response<Self::greetServerStreamStream>, dubbo::status::Status> {
 println!("greet_server_stream: {:?}", request.into_inner());

 let data = vec![
 Result::<_, dubbo::status::Status>::Ok(GreeterReply {
 message: "msg1 from server".to_string(),
 }),
 Result::<_, dubbo::status::Status>::Ok(GreeterReply {
 message: "msg2 from server".to_string(),
 }),
 Result::<_, dubbo::status::Status>::Ok(GreeterReply {
 message: "msg3 from server".to_string(),
 }),
 ];
 let resp = futures_util::stream::iter(data);

 Ok(Response::new(Box::pin(resp)))
 }

 type greetStreamStream = ResponseStream;
 async fn greet_stream(
 &self,
 request: Request<Decoding<GreeterRequest>>,
 ) -> Result<Response<Self::greetStreamStream>, dubbo::status::Status> {
 println!(
 "GreeterServer::greet_stream, grpc header: {:?}",
 request.metadata
 );

 let mut in_stream = request.into_inner();
 let (tx, rx) = mpsc::channel(128);

 tokio::spawn(async move {
 while let Some(result) = in_stream.next().await {
 match result {
 Ok(v) => {
 tx.send(Ok(GreeterReply {
 message: format!("server reply: {:?}", v.name),
 }))
 .await
 .expect("working rx")
 }
 Err(err) => {
 if let Some(io_err) = match_for_io_error(&err) {
 if io_err.kind() == ErrorKind::BrokenPipe {
 eprintln!("\tclient disconnected: broken pipe");
 break;
 }
 }

 match tx.send(Err(err)).await {
 Ok(_) => (),
 Err(_err) => break,
 }
 }
 }
 }
 println!("\tstream ended");
 });

 let out_stream = ReceiverStream::new(rx);

 Ok(Response::new(
 Box::pin(out_stream) as Self::greetStreamStream
 ))
 }
}

fn match_for_io_error(err_status: &dubbo::status::Status) -> Option<&std::io::Error> {
 let mut err: &(dyn std::error::Error + 'static) = err_status;

 loop {
 if let Some(io_err) = err.downcast_ref::<std::io::Error>() {
 return Some(io_err);
 }

 err = match err.source() {
 Some(err) => err,
 None => return None,
 };
 }
}

2.2 Writing the Streaming Client

// ./src/greeter/client.rs
pub mod protos {
 include!(concat!(env!("OUT_DIR"), "/org.apache.dubbo.sample.tri.rs"));
}

use dubbo::codegen::*;
use futures_util::StreamExt;
use protos::{greeter_client::GreeterClient, GreeterRequest};

#[tokio::main]
async fn main() {
 let mut cli = GreeterClient::new().with_uri("http://127.0.0.1:8888".to_string());

 println!("# unary call");
 let resp = cli
 .greet(Request::new(GreeterRequest {
 name: "message from client".to_string(),
 }))
 .await;
 let resp = match resp {
 Ok(resp) => resp,
 Err(err) => return println!("{:?}", err),
 };
 let (_parts, body) = resp.into_parts();
 println!("Response: {:?}", body);

 println!("# client stream");
 let data = vec![
 GreeterRequest {
 name: "msg1 from client streaming".to_string(),
 },
 GreeterRequest {
 name: "msg2 from client streaming".to_string(),
 },
 GreeterRequest {
 name: "msg3 from client streaming".to_string(),
 },
 ];
 let req = futures_util::stream::iter(data);
 let resp = cli.greet_client_stream(req).await;
 let client_streaming_resp = match resp {
 Ok(resp) => resp,
 Err(err) => return println!("{:?}", err),
 };
 let (_parts, resp_body) = client_streaming_resp.into_parts();
 println!("client streaming, Response: {:?}", resp_body);

 println!("# bi stream");
 let data = vec![
 GreeterRequest {
 name: "msg1 from client".to_string(),
 },
 GreeterRequest {
 name: "msg2 from client".to_string(),
 },
 GreeterRequest {
 name: "msg3 from client".to_string(),
 },
 ];
 let req = futures_util::stream::iter(data);

 let bidi_resp = cli.greet_stream(req).await.unwrap();

 let (parts, mut body) = bidi_resp.into_parts();
 println!("parts: {:?}", parts);
 while let Some(item) = body.next().await {
 match item {
 Ok(v) => {
 println!("reply: {:?}", v);
 }
 Err(err) => {
 println!("err: {:?}", err);
 }
 }
 }
 let trailer = body.trailer().await.unwrap();
 println!("trailer: {:?}", trailer);

 println!("# server stream");
 let resp = cli
 .greet_server_stream(Request::new(GreeterRequest {
 name: "server streaming req".to_string(),
 }))
 .await
 .unwrap();

 let (parts, mut body) = resp.into_parts();
 println!("parts: {:?}", parts);
 while let Some(item) = body.next().await {
 match item {
 Ok(v) => {
 println!("reply: {:?}", v);
 }
 Err(err) => {
 println!("err: {:?}", err);
 }
 }
 }
 let trailer = body.trailer().await.unwrap();
 println!("trailer: {:?}", trailer);
}

3 Running the Example

Build

Run cargo build to compile the server and client.

Rust SDK Manual on Apache Dubbo

Quick Start

1 Prerequisites

2 Define Dubbo Services Using IDL

3 Add Dubbo-rust and Related Dependencies to the Project

4 Configure dubbo-build to Compile IDL

Interoperability between Rust and Java

1 Prerequisites

2 Run the Example Java Version of Dubbo Provider

Service Discovery

Introduction to Dubbo Rust Service Discovery

Service Routing Rules

Conditional Routing

Communication using Unix Socket Connector

1 Explanation of Using Unix Socket Connector

2 Logic for Using Unix Socket Connector with client/connection

2.1 Writing the Client Side

2.2 Writing the Server Side

3 Running Example

Streaming Communication Model

1 Adding Streaming Model Definitions in IDL

2 Writing Logic with Streaming Model Definitions

2.1 Writing the Streaming Server

2.2 Writing the Streaming Client

3 Running the Example