RPC Framework on Apache Dubbo

Streaming Communication

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

Sample source: dubbo-go-samples/streaming.

A unary RPC has one request and one response. Triple streaming allows a single RPC to carry a sequence of messages, which is useful for chunked data, server push, and real-time communication.

Streaming types

In a .proto method, the side marked with stream can send more than one message:

Type	Requests	Responses	Definition
Server streaming	1	N	`rpc Method(Request) returns (stream Response)`
Client streaming	N	1	`rpc Method(stream Request) returns (Response)`
Bidirectional streaming	N	N	`rpc Method(stream Request) returns (stream Response)`

Server streaming works well for event push and large downloads. Client streaming is commonly used for chunked uploads or server-side aggregation. In a bidirectional stream, sending and receiving are independent, making it suitable for chat and real-time control. The sample echoes each request immediately, but that is an application choice rather than a protocol requirement.

Timeout Duration

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

1. Introduction

This example demonstrates how to set the request timeout duration when initiating a call from the Dubbo-go client. You can view the complete example source code here.

2. How to Set the Request Timeout Duration

When creating a client, you can set a global timeout using the client.WithRequestTimeout() method (shared by all service proxies using this client).

 cli, err := client.NewClient(
 client.WithClientURL("tri://127.0.0.1:20000"),
 client.WithClientRequestTimeout(3 * time.Second),
 )

You can also create service-level timeout using client.WithRequestTimeout() (all method calls initiated from the following service proxy svc will use this timeout).

Communication Protocol

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

The Dubbo-go framework provides two built-in protocols: triple and dubbo. In addition, the framework offers various ways to extend protocol access.

triple, a high-performance communication protocol based on HTTP/1 and HTTP/2, 100% compatible with gRPC, supports Unary, Streaming, and other communication modes; supports publishing REST-style HTTP services.
dubbo, a high-performance private communication protocol based on TCP, with the disadvantage of poor universality, more suitable for use between Dubbo SDKs;
Any protocol extension, by extending the protocol, it can support any RPC protocol. The official ecosystem provides support for JsonRPC, thrift, etc.

Related samples:

Exception Type Return Values

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

1. Introduction

This document demonstrates how to handle error type responses during RPC calls. You can view the complete example source code here.

2. Example Details

2.1 Server

Server proto file

Source file path: dubbo-go-sample/error/proto/greet.proto

syntax = "proto3";

package greet;

option go_package = "github.com/apache/dubbo-go-samples/error/proto;greet";

message GreetRequest {
 string name = 1;
}

message GreetResponse {
 string greeting = 1;
}

service GreetService {
 rpc Greet(GreetRequest) returns (GreetResponse) {}
}

Server handler file

Note that in this program design, the Greet method will only consider the request valid if it receives name="right name"; otherwise, it will return an error.

Health Check

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

Background

Dubbo-go has a built-in health check service based on the triple protocol to help users manage and monitor the health status of services. You can view the complete example source code here.

Usage

The framework automatically registers the health check service grpc.health.v1.Health into the framework after starting via instance, which records and exposes the health status of each triple service.
The health check service can check the status of services in the framework by making an HTTP request or through client calls to the health check service. The interface called is grpc.health.v1.Health, and the method is check.

1. Call the health check service through the client

Start the service in dubbo-go-samples/healthcheck/go-server, and the status of greet.GreetService can be viewed through the client below.

Request Retry

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

When a service call fails, we can allow the framework to automatically retry a few times, which can improve the success rate of requests seen by users. In failover cluster mode, dubbo-go supports automatic retries.

1. Introduction

This example demonstrates how to configure the retry function when a client-side call fails. Full example source code

2. How to Use the Retry Feature

When creating a client using client.NewClient(), you can set the retry count using client.WithClientRetries() method.

Passing Additional Parameters

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

Dubbo-go provides two related ways to pass metadata outside the RPC request and response body:

Attachments are Dubbo RPC implicit parameters. They are stored in context under constant.AttachmentKey and are commonly used by filters, routing, tracing, or business code that needs request-scoped key-value data. For Triple calls, request attachments are carried as HTTP metadata headers. For Dubbo protocol calls, attachments are encoded in a fixed location in the protocol body.
Triple metadata headers and trailers are Triple protocol metadata APIs exposed as http.Header. They are useful when application code needs direct access to request metadata or response header/trailer data.

Sample source code:

Startup check

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

The Dubbo framework, by default, checks the availability of dependent services at startup (whether the registry has available addresses). If not available, it throws an exception to prevent the application from completing initialization, allowing early detection of problems during deployment. The default is check=“true” and waits for 3 seconds.

You can disable the check with check=“false”. For example, during testing, some services may not be of concern, or there may be circular dependencies, requiring one party to start first.

OpenAPI Documentation Generation & Management

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

Dubbo-go provides built-in OpenAPI support that automatically generates OpenAPI 3.0-compliant API documentation for Triple protocol services, with Swagger UI and ReDoc for visual API browsing and debugging.

Sample source: dubbo-go-samples/rpc/triple/openapi.

Feature Overview

Automatic Documentation Generation: Automatically generates OpenAPI 3.0.1 API documentation based on service interface definitions (protobuf IDL or non-IDL mode)
Swagger UI: Built-in Swagger UI interface for online API browsing and debugging
ReDoc: Built-in ReDoc interface for clean API documentation presentation
Multiple Output Formats: Supports both JSON and YAML output formats
Group Management: Supports organizing services into OpenAPI Groups for managing multiple API versions
Static Documentation Generation: Generate static OpenAPI documentation files at compile time from .proto files using the protoc-gen-triple-openapi plugin

Quick Start

1. Enable OpenAPI

Enable OpenAPI through the Triple protocol options when creating a Server:

Filter Interceptor

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

Sample source: dubbo-go-samples/filter.

Filters dynamically intercept requests or responses to transform or utilize the information contained in them. A filter does not usually create a response by itself. Instead, it provides reusable logic that can be attached to RPC calls. Dubbo filters are pluggable, so you can compose multiple filters into one consumer or provider invocation chain.

The working principle of filters is illustrated in the diagram below:

Usage

1. Concept of Filter Interceptor

Filter is defined as follows: