Skip to content

Commit

Permalink
fix: fix link error (#756)
Browse files Browse the repository at this point in the history
Signed-off-by: rogrogers <rogers@rogerogers.com>
  • Loading branch information
rogerogers committed Aug 8, 2023
1 parent 96c442f commit ce346f0
Show file tree
Hide file tree
Showing 13 changed files with 206 additions and 209 deletions.
27 changes: 21 additions & 6 deletions content/en/blog/news/open_source_volo/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,23 +7,29 @@ keywords: ["CloudWeGo", "RPC framework", "Volo", "Rust", "ByteDance Open Source"
description: "This article introduces ByteDance's official open source Rust RPC framework — Volo, and focuses on the project's origin, main features and related ecosystem."
author: <a href="https://github.com/cloudwego" target="_blank">CloudWeGo Team</a>
---

[Volo](https://github.com/cloudwego/volo) is a lightweight, high-performance, scalable, and user-friendly Rust RPC framework developed by the ByteDance service framework team. It leverages the latest GAT and TAIT features of Rust to deliver exceptional performance and efficiency.
Within ByteDance, Volo has been extensively used, implementing multiple business and foundational components. It has exceeded performance expectations, showcasing its superiority compared to the Go version. As with other CloudWeGo open-source projects, Volo maintains a consistent codebase internally and externally, ensuring robustness and reliability for open-source users.
While observing the relatively weak Rust open-source community in terms of RPC frameworks, Volo's open-source release aims to contribute to community improvement. It also strengthens the CloudWeGo ecosystem, advancing performance, security, and the adoption of the latest technologies. Volo provides robust support for developers, enterprises, and Rustaceans in developing RPC microservices and building cloud-native distributed systems.
This article will provide a brief introduction to Volo and its related ecosystem, offering suggestions for choosing between Rust and Go.

## Origin of the project

The founding members of [Volo](https://github.com/cloudwego/volo) originally came from the [Kitex](https://github.com/cloudwego/kitex) team, the open-source Go RPC framework developed by CloudWeGo. Through deep performance optimizations in Go, they encountered challenges that motivated their exploration of Rust. Rust proved to be a suitable choice for businesses requiring exceptional performance, safety, and low-level control capabilities. The birth of Volo was driven by the need for a robust RPC framework as a vital component of distributed systems.

## Features

Key features of Volo include:

### High performance

Rust's reputation for high performance and safety guides the design and implementation of Volo. Every aspect of the framework is optimized to minimize overhead and maximize performance.
It is important to note that directly comparing the performance of Volo and Kitex would be unfair, and the performance data provided should be viewed as a reference. We aim to avoid unnecessary controversy, especially since there is no mature Async version of a Thrift RPC framework in the Rust open-source community. Instead, we focus on sharing our own limit QPS (queries per second) data.
Under the same test conditions as [Kitex](https://github.com/cloudwego/kitex) (limited to 4 cores), Volo achieves a limit QPS of 350,000 (35W). Furthermore, we are internally validating a version based on [Monoio](https://github.com/bytedance/monoio) (CloudWeGo's open-source Rust Async Runtime), which can achieve a limit QPS of 440,000 (44W).
Under the same test conditions as [Kitex](https://github.com/cloudwego/kitex) (limited to 4 cores), Volo achieves a limit QPS of 350,000 (35W). Furthermore, we are internally validating a version based on [Monoio](https://github.com/bytedance/monoio) (CloudWeGo's open-source Rust Async Runtime), which can achieve a limit QPS of 440,000 (44W).
Judging from the flame graph of our online business, thanks to Rust's static distribution and excellent compilation optimization, the overhead of the framework part is basically negligible (excluding syscall overhead).

### Based on GAT design

Volo embraces the latest technologies and utilizes Rust's GAT feature as the core abstraction. Additionally, we draw inspiration from Tower, a well-designed abstraction layer suitable for non-GAT scenarios. We extend our gratitude to the [Tower](https://github.com/tower-rs/tower) team for their contribution.

Through the use of GAT, Volo eliminates unnecessary Box memory allocations, enhances usability, and offers users a more intuitive programming interface and a more ergonomic programming paradigm.
Expand All @@ -35,6 +41,7 @@ Thanks to the use of Rust's GAT feature, they address the lifecycle challenges a
![image](/img/blog/opensource_volo/2.png)

### Easy to use

Rust is renowned for its learning curve and perceived difficulty. We recognize the importance of reducing the barriers for users to adopt the Volo framework and develop microservices in the Rust language. Our goal is to provide the most intuitive and simple coding experience possible.

To achieve this, we offer the Volo command-line tool, which facilitates project initialization and IDL management. Additionally, we have separated Thrift and gRPC into two independent frameworks (although they share some components) to cater to the specific programming paradigms and interfaces that align with each protocol's semantics.
Expand All @@ -45,28 +52,36 @@ This macro simplifies the implementation of Service middleware, as demonstrated
![image](/img/blog/opensource_volo/3.png)

### Strong scalability

Benefiting from Rust's powerful expression and abstraction capabilities, developers can process RPC meta-information, requests, and responses in a unified manner through flexible middleware 'Service' abstraction.
For example, service governance functions such as service discovery and load balancing can be implemented in the form of services without the need to implement Trait independently.
We encourage everyone to contribute their own extensions to volo-rs, which will be hosted under the [github.com/volo-rs](http://github.com/volo-rs) organization

## Ecosystem

Volo is the RPC framework at the core, accompanied by the following open-source projects:

1. [Volo-rs](https://github.com/volo-rs): The volo ecosystem which contains a lot of useful components.
2. [Pilota](https://github.com/cloudwego/pilota): A thrift and protobuf implementation in pure rust with high performance and extensibility.
3. [Motore](https://github.com/cloudwego/motore): Middleware abstraction layer designed by Tower, leveraging GAT and TAIT.
4. [Metainfo](https://github.com/cloudwego/metainfo): A Volo component for transparent transmission of meta information, aimed at defining a set of standards for such transmission.

## Choosing Between Rust and Go

The question of when to use Rust or Go is a classic one. From the perspective of the Volo team, Rust and Go are not opposing choices but rather complementary options that can learn from each other.
- For performance-insensitive, IO-heavy, and rapidly developing applications that prioritize stability, Go is recommended. Rust does not bring significant benefits in such scenarios.
- However, for applications requiring extreme performance, heavy calculations, and a need for stability, even if it comes at the expense of development speed, Rust is recommended. Rust's advantages in extreme performance optimization and security are valuable in these cases.

- For performance-insensitive, IO-heavy, and rapidly developing applications that prioritize stability, Go is recommended. Rust does not bring significant benefits in such scenarios.
- However, for applications requiring extreme performance, heavy calculations, and a need for stability, even if it comes at the expense of development speed, Rust is recommended. Rust's advantages in extreme performance optimization and security are valuable in these cases.
- Additionally, the team's existing technology stack and talent pool are crucial factors to consider.

## Summary
We hope this article has provided you with a basic understanding of [Volo](https://github.com/cloudwego/volo) and its related ecosystem. Volo is still in its early stages, and we welcome interested developers to join us in building the CloudWeGo and Rust open-source communities. We encourage you to submit [Issues](https://github.com/cloudwego/volo/issues) and [PRs](https://github.com/cloudwego/volo/pulls) to Volo, as we look forward to collective development. We sincerely hope to see more developers join us, and we aspire for Volo to assist more enterprises in swiftly building cloud-native architectures. If enterprise customers wish to explore Volo internally, we can schedule dedicated technical support and communication for their needs.

We hope this article has provided you with a basic understanding of [Volo](https://github.com/cloudwego/volo) and its related ecosystem. Volo is still in its early stages, and we welcome interested developers to join us in building the CloudWeGo and Rust open-source communities. We encourage you to submit [Issues](https://github.com/cloudwego/volo/issues) and [PRs](https://github.com/cloudwego/volo/pulls) to Volo, as we look forward to collective development. We sincerely hope to see more developers join us, and we aspire for Volo to assist more enterprises in swiftly building cloud-native architectures. If enterprise customers wish to explore Volo internally, we can schedule dedicated technical support and communication for their needs.

### References

- Volo overview: https://github.com/cloudwego/volo
- Volo Tutorial: https://www.cloudwego.io/en/docs/volo/
- Volo Tutorial: https://www.cloudwego.io/docs/volo/
- Volo Documentation: https://docs.rs/volo
- Volo-rs organization: https://github.com/volo-rs
- Volo-rs organization: https://github.com/volo-rs

2 changes: 1 addition & 1 deletion content/en/docs/cwgo/getting-started/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ libprotoc x.x.x

## Precautions

The bottom layer of cwgo uses [kitex](https://www.cloudwego.io/docs/kitex/tutorials/code-gen/code_generation/), [hz](https://www.cloudwego.io/docs/hertz/tutorials/toolkit/), [gen](https://gorm.io/gen/index.html) tools, so the corresponding tool specifications also need to be followed, such as [kitex precautions](https://www.cloudwego.io/docs/kitex/tutorials/code-gen/code_generation/#notes-for-using-protobuf-idls) and [Notes for hz](https://www.cloudwego.io/docs/hertz/tutorials/toolkit/usage/cautions/).
The bottom layer of cwgo uses [kitex](https://www.cloudwego.io/docs/kitex/tutorials/code-gen/code_generation/), [hz](https://www.cloudwego.io/docs/hertz/tutorials/toolkit/), [gen](https://gorm.io/gen/index.html) tools, so the corresponding tool specifications also need to be followed, such as [kitex precautions](https://www.cloudwego.io/docs/kitex/tutorials/code-gen/code_generation/#notes-for-using-protobuf-idls) and [Notes for hz](https://www.cloudwego.io/docs/hertz/tutorials/toolkit/cautions/).

## Using

Expand Down
6 changes: 3 additions & 3 deletions content/en/docs/cwgo/tutorials/cli/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ cwgo

```

Therefore, the precautions of corresponding tools also need to be followed, such as [kitex precautions](https://www.cloudwego.io/docs/kitex/tutorials/code-gen/code_generation/#notes-for-using-protobuf-idls) and generate HTTP code [Notes on hz](https://www.cloudwego.io/docs/hertz/tutorials/toolkit/usage/cautions/).
Therefore, the precautions of corresponding tools also need to be followed, such as [kitex precautions](https://www.cloudwego.io/docs/kitex/tutorials/code-gen/code_generation/#notes-for-using-protobuf-idls) and generate HTTP code [Notes on hz](https://www.cloudwego.io/docs/hertz/tutorials/toolkit/cautions/).

## Using

Expand Down Expand Up @@ -62,7 +62,7 @@ The information requested by db is:
1. Enter the database DSN. required
1. Choose whether to use the default configuration to generate the project. If you choose No, you will be asked to enter the parameters to pass to the build tool

For parameters passed to the tool, refer to [documentation](https://www.cloudwego.io/docs/hertz/tutorials/toolkit/usage/command/) for hz and [documentation](https://www.cloudwego.io/docs/kitex/tutorials/code-gen/code_generation/) for kitex.
For parameters passed to the tool, refer to [documentation](https://www.cloudwego.io/docs/hertz/tutorials/toolkit/command/) for hz and [documentation](https://www.cloudwego.io/docs/kitex/tutorials/code-gen/code_generation/) for kitex.

## Static command line

Expand Down Expand Up @@ -107,7 +107,7 @@ pass parameter description:
To pass the `handler_dir' parameter of `hz`, you should enter --pass "--handler_dir ./handler"

Parameters passed to the tool
hz refer to [Documentation](https://www.cloudwego.io/docs/hertz/tutorials/toolkit/usage/command/),
hz refer to [Documentation](https://www.cloudwego.io/docs/hertz/tutorials/toolkit/command/),
Kitex reference [documentation](https://www.cloudwego.io/docs/kitex/tutorials/code-gen/code_generation/).

### Model commands
Expand Down
105 changes: 53 additions & 52 deletions content/en/docs/hertz/getting-started/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ description: >
2. We recommend that you use the latest version of Golang, or make sure it's >= v1.15. You can choose to use the earlier versions, but the compatibility and stability are not guaranteed.
3. Make sure the go mod support is enabled (for Golang versions >= v1.15, it is enabled by default).

>Currently, Hertz supports Linux, macOS, and Windows systems.
> Currently, Hertz supports Linux, macOS, and Windows systems.
## Quick Start

Expand All @@ -21,65 +21,65 @@ After completing the environment preparation, you can quickly start the Hertz Se
2. Create the `main.go` file.
3. Add the following code to the `main.go` file.

```go
package main
```go
package main

import (
"context"
import (
"context"

"github.com/cloudwego/hertz/pkg/app"
"github.com/cloudwego/hertz/pkg/app/server"
"github.com/cloudwego/hertz/pkg/common/utils"
"github.com/cloudwego/hertz/pkg/protocol/consts"
)
"github.com/cloudwego/hertz/pkg/app"
"github.com/cloudwego/hertz/pkg/app/server"
"github.com/cloudwego/hertz/pkg/common/utils"
"github.com/cloudwego/hertz/pkg/protocol/consts"
)

func main() {
h := server.Default()
func main() {
h := server.Default()

h.GET("/ping", func(c context.Context, ctx *app.RequestContext) {
ctx.JSON(consts.StatusOK, utils.H{"message": "pong"})
})
h.GET("/ping", func(c context.Context, ctx *app.RequestContext) {
ctx.JSON(consts.StatusOK, utils.H{"message": "pong"})
})

h.Spin()
}
```
h.Spin()
}
```

4. Generate the `go.mod` file.

```bash
go mod init hertz_demo
```
```bash
go mod init hertz_demo
```

5. Tidy & get dependencies.

```bash
go mod tidy
```
```bash
go mod tidy
```

6. Run the Sample Code

```bash
go run hertz_demo
```
```bash
go run hertz_demo
```

If the server is launched successfully, you will see following message:
If the server is launched successfully, you will see following message:

```bash
2022/05/17 21:47:09.626332 engine.go:567: [Debug] HERTZ: Method=GET absolutePath=/ping --> handlerName=main.main.func1 (num=2 handlers)
2022/05/17 21:47:09.629874 transport.go:84: [Info] HERTZ: HTTP server listening on address=[::]:8888
```
```bash
2022/05/17 21:47:09.626332 engine.go:567: [Debug] HERTZ: Method=GET absolutePath=/ping --> handlerName=main.main.func1 (num=2 handlers)
2022/05/17 21:47:09.629874 transport.go:84: [Info] HERTZ: HTTP server listening on address=[::]:8888
```

Then, we can test the interface:
Then, we can test the interface:

```bash
curl http://127.0.0.1:8888/ping
```
```bash
curl http://127.0.0.1:8888/ping
```

If nothing goes wrong, we can see the following output:
If nothing goes wrong, we can see the following output:

```bash
{"message":"pong"}
```
```bash
{"message":"pong"}
```

## Code Generation Tool hz

Expand All @@ -90,8 +90,8 @@ Hz is a command-line tool provided by the Hertz framework for generating code, w
First, you need to install the command tool hz which is used in this chapter:

1. Confirm the `GOPATH` environment has been defined correctly (For example `export GOPATH=~/go`)
and the `$GOPATH/bin` has been added to `PATH` environment (For example `export PATH=$GOPATH/bin:$PATH`);
Attention, do not set `GOPATH` to a directory that the current user does not have read/write access to.
and the `$GOPATH/bin` has been added to `PATH` environment (For example `export PATH=$GOPATH/bin:$PATH`);
Attention, do not set `GOPATH` to a directory that the current user does not have read/write access to.
2. Install hz: `go install github.com/cloudwego/hertz/cmd/hz@latest`.

For more information on how to use hz, please refer to: [hz](https://www.cloudwego.io/zh/docs/hertz/tutorials/toolkit/usage/).
Expand All @@ -100,23 +100,23 @@ For more information on how to use hz, please refer to: [hz](https://www.cloudwe

1. If your codes are located in `$GOPATH/src`, you will need to create an additional dictionary in `$GOPATH/src` and retrieve your code from that dictionary.

```bash
mkdir -p $(go env GOPATH)/src/github.com/cloudwego
cd $(go env GOPATH)/src/github.com/cloudwego
```
```bash
mkdir -p $(go env GOPATH)/src/github.com/cloudwego
cd $(go env GOPATH)/src/github.com/cloudwego
```

2. If your codes are not placed under `GOPATH`, you can retrieve them directly.

### Generate/Complete the Sample Code

1. Create the hertz_demo folder in the current directory and go to that directory.
2. Generate code `hz new`. If your codes are not placed under `GOPATH`, you need to refer [here](https://www.cloudwego.io/docs/hertz/tutorials/toolkit/usage/usage/) and add `-module` (or `-mod`) flag to name your custom module.
2. Generate code `hz new`. If your codes are not placed under `GOPATH`, you need to refer [here](https://www.cloudwego.io/docs/hertz/tutorials/toolkit/usage/) and add `-module` (or `-mod`) flag to name your custom module.
3. Tidy & get dependencies.

```bash
go mod init # If your codes are not placed under `GOPATH`, you can skip `go mod init`.
go mod tidy
```
```bash
go mod init # If your codes are not placed under `GOPATH`, you can skip `go mod init`.
go mod tidy
```

### Run the Sample Code

Expand Down Expand Up @@ -145,7 +145,8 @@ If nothing goes wrong, we can see the following output:
{"message":"pong"}
```

You have now successfully launched Hertz Server successfully and completed an API call.
You have now successfully launched Hertz Server successfully and completed an API call.

## More examples

Please refer:[Example code](/docs/hertz/tutorials/example/)
5 changes: 2 additions & 3 deletions content/en/docs/hertz/tutorials/framework-exten/protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@ title: "Protocol extension"
linkTitle: "Protocol extension"
weight: 5
description: >
---

## Overview
Expand All @@ -16,7 +15,7 @@ Thanks to the layered design of Hertz, in addition to the HTTP1/HTTP2/HTTP3 prot

This interface can be used to implement protocol servers based on byte stream transmission, such as HTTP1/HTTP2.

>Note: If using this interface, the underlying network library needs to implement the [network.Conn](/docs/hertz/tutorials/framework-exten/advanced-exten/network-lib/#networkconn) interface.
> Note: If using this interface, the underlying network library needs to implement the [network.Conn](/docs/hertz/tutorials/framework-exten/network-lib/#networkconn) interface.
```go
type Server interface {
Expand Down Expand Up @@ -46,7 +45,7 @@ type Core interface {

This interface can be used to implement streaming based protocol servers, such as HTTP3.

>Note: If using this interface, the underlying network library needs to implement the [network.streamConn](/docs/hertz/tutorials/framework-exten/advanced-exten/network-lib/#networkstreamconn) interface.
> Note: If using this interface, the underlying network library needs to implement the [network.streamConn](/docs/hertz/tutorials/framework-exten/network-lib/#networkstreamconn) interface.
```go
type StreamServer interface {
Expand Down
Loading

1 comment on commit ce346f0

@vercel
Copy link

@vercel vercel bot commented on ce346f0 Aug 8, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.