Skip to content

Commit 072c527

Browse files
jayantxiejayantxie
committed
feat: kitex proxy docs
1 parent b4c925d commit 072c527

4 files changed

Lines changed: 166 additions & 0 deletions

File tree

‎content/en/docs/kitex/Tutorials/advanced-feature/grpcproxy.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,14 @@ keywords: ["Kitex", "gRPC", "Proxy"]
66
description: Kitex supports custom Proxy routing for unregistered gRPC method calls.
77
---
88

9+
> **⚠️ Deprecated**
10+
>
11+
> This document has been deprecated. Please refer to the new comprehensive [Proxy Application Development Guide](./proxy_application_development/) for more up-to-date and complete proxy development documentation.
12+
>
13+
> The new guide covers all proxy scenarios including gRPC, TTHeader, and other protocols with better examples and best practices.
14+
15+
---
16+
917
Kitex provides the `WithGRPCUnknownServiceHandler` function when transport is using gRPC. When the server receives a request from an unknown gRPC method, it will execute the unknown service handler:
1018

1119
```go

‎content/en/docs/kitex/Tutorials/advanced-feature/proxy_application_development.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
title: "Proxy Application Development"
3+
date: 2024-09-28
4+
weight: 15
5+
keywords: ["Proxy", "Generic Call", "Advanced Feature"]
6+
description: "A comprehensive guide for developing proxy applications using Kitex generic calls, including server initialization, client setup, and traffic forwarding."
7+
---
8+
9+
## Prerequisites
10+
11+
Ensure you are using **cloudwego/kitex >= v0.15.1**.
12+
13+
For protocol consistency, if your business scenarios require proxying different streaming protocols simultaneously (such as gRPC and ttstream), it is recommended to divide business operations by cluster for different protocols. For example, ttstream clusters should only handle ttstream protocol requests, while gRPC clusters should only handle gRPC protocol requests. Ping-pong methods like ttheader/framed are recommended to go through the ttstream cluster.
14+
15+
## Initialize Server
16+
17+
Kitex proxy receives upstream traffic through a kitex server, which is identical to the binary generic server used in the [Kitex Generic Call Guide](../generic-call/).
18+
19+
```go
20+
import (
21+
"github.com/cloudwego/kitex/server"
22+
)
23+
24+
opts = append(opts, server.WithListener(ln),
25+
server.WithMetaHandler(transmeta.ServerTTHeaderHandler),
26+
server.WithMetaHandler(transmeta.ServerHTTP2Handler))
27+
28+
svr := server.NewServer(opts...)
29+
err := genericserver.RegisterUnknownServiceOrMethodHandler(svr, &genericserver.UnknownServiceOrMethodHandler{
30+
DefaultHandler: defaultUnknownHandler,
31+
StreamingHandler: streamingUnknownHandler,
32+
})
33+
```
34+
35+
If the server only receives ttheader/framed/buffered traffic, you only need to pass in the DefaultHandler. Otherwise, for traffic involving grpc/ttstream protocols, you must also specify the StreamingHandler.
36+
37+
**Note**: For non-streaming methods defined in IDL, if the upstream access is through gRPC protocol, the traffic will be routed to the StreamingHandler. This is because gRPC can only obtain the actual defined streaming mode through IDL. In unknown service scenarios, it cannot obtain IDL Info, so all traffic is treated as bidirectional streaming by default. Therefore, the method signature of StreamingHandler provides generic.BidiStreamingServer type input parameter.
38+
39+
## Initialize Client
40+
41+
After determining the protocol, when receiving RPC requests, you can forward them to specific kitex generic call clients. Kitex client and IDL Service have a one-to-one correspondence, so you can usually dynamically create clients to implement traffic forwarding.
42+
43+
```go
44+
import (
45+
"github.com/cloudwego/kitex/client/genericclient"
46+
)
47+
48+
options := []client.Option{
49+
client.WithHostPorts(addr.String()),
50+
client.WithTransportProtocol(transport.TTHeader | transport.TTHeaderStreaming),
51+
client.WithMetaHandler(transmeta.ClientTTHeaderHandler),
52+
client.WithMetaHandler(transmeta.ClientHTTP2Handler),
53+
}
54+
55+
// thrift binary
56+
cli, err := genericclient.NewClient(downstreamService, generic.BinaryThriftGenericV2(serviceName), options...)
57+
// protobuf binary
58+
cli, err := genericclient.NewClient(downstreamService, generic.BinaryPbGeneric(serviceName, packageName), options...)
59+
```
60+
61+
If the client needs to support streaming generic calls, you need to confirm the streaming call protocol. By default, the generic client generated through the above method uses TTHeaderStreaming for streaming protocols, while non-streaming messages use Framed or TTHeaderFramed. If you need to configure streaming methods to use GRPC protocol without changing the protocol of non-streaming methods, add the following client options:
62+
63+
```go
64+
client.WithTransportProtocol(transport.GRPCStreaming)
65+
```
66+
67+
## Traffic Forwarding
68+
69+
### Ping-pong Traffic Forwarding
70+
71+
**Recommended Best Practice**: [Proxy Implementation Example](https://github.com/cloudwego/kitex-tests/blob/main/generic/proxy/proxy.go#L136)
72+
73+
### Streaming Traffic Forwarding
74+
75+
**Recommended Best Practice**: [Streaming Proxy Implementation](https://github.com/cloudwego/kitex-tests/blob/main/generic/proxy/proxy.go#L150)

‎content/zh/docs/kitex/Tutorials/advanced-feature/grpcproxy.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,14 @@ keywords: ["Kitex", "gRPC", "Proxy"]
66
description: Kitex 支持对未注册的 gRPC 方法调用进行自定义 Proxy 路由处理。
77
---
88

9+
> **⚠️ 已废弃**
10+
>
11+
> 本文档已废弃，请参考新的综合版 [Proxy 应用开发指南](./proxy_application_development/) 获取更完整和最新的 Proxy 开发文档。
12+
>
13+
> 新指南涵盖了所有代理场景，包括 gRPC、TTHeader 等协议，并提供更好的示例和最佳实践。
14+
15+
---
16+
917
Kitex 对 gRPC 场景提供了 `WithGRPCUnknownServiceHandler` 功能，当服务器接收到未注册的 gRPC 方法调用的请求时，将执行自定义的 Unknown Service Handler 函数进行处理：
1018

1119
```go

‎content/zh/docs/kitex/Tutorials/advanced-feature/proxy_application_development.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
title: "Proxy 应用开发指南"
3+
date: 2024-09-28
4+
weight: 15
5+
keywords: ["Proxy", "泛化调用", "高级特性"]
6+
description: "使用 Kitex 泛化调用开发 Proxy 应用的完整指南，包括服务端初始化、客户端设置和流量转发。"
7+
---
8+
9+
## 前置环境
10+
11+
请确保使用 **cloudwego/kitex >= v0.15.1**。
12+
13+
为确保协议一致性，如果业务场景中有不同的流式协议需要同时代理，如 gRPC 和 ttstream，建议按集群对不同协议的 proxy 进行业务划分。如 ttstream 集群只处理 ttstream 协议的请求，gRPC 集群只处理 gRPC 协议的请求。ttheader/framed 这类 pingpong 方法建议走 ttstream 集群。
14+
15+
## 初始化服务端
16+
17+
Kitex proxy 接收上游流量是通过 kitex server 实现，它与 [Kitex 泛化调用指南](../generic-call/) 中二进制泛化的 server 使用别无二致。
18+
19+
```go
20+
import (
21+
"github.com/cloudwego/kitex/server"
22+
)
23+
24+
opts = append(opts, server.WithListener(ln),
25+
server.WithMetaHandler(transmeta.ServerTTHeaderHandler),
26+
server.WithMetaHandler(transmeta.ServerHTTP2Handler))
27+
28+
svr := server.NewServer(opts...)
29+
err := genericserver.RegisterUnknownServiceOrMethodHandler(svr, &genericserver.UnknownServiceOrMethodHandler{
30+
DefaultHandler: defaultUnknownHandler,
31+
StreamingHandler: streamingUnknownHandler,
32+
})
33+
```
34+
35+
如果 server 仅接收 ttheader/framed/buffered 流量，则只需传入 DefaultHandler 即可。否则，涉及 grpc/ttstream 协议的流量，还需指定 StreamingHandler。
36+
37+
**注意**：IDL 中定义的非流式方法，如果上游是通过 grpc 协议访问的，则流量会被路由到 StreamingHandler。这是由于 grpc 仅能通过 IDL 获取实际定义的流模式，unknown service 场景下，没法获取 IDL Info，只能将所有流量都默认视作双向流，所以 StreamingHandler 的方法签名提供的是 generic.BidiStreamingServer 类型入参。
38+
39+
## 初始化客户端
40+
41+
明确协议后，接收到 rpc 请求时，就可以转发到特定的 kitex 泛化调用 client 上了。Kitex client 和 IDL Service 是一一对应的，所以通常可以动态创建 client 来实现流量转发。
42+
43+
```go
44+
import (
45+
"github.com/cloudwego/kitex/client/genericclient"
46+
)
47+
48+
options := []client.Option{
49+
client.WithHostPorts(addr.String()),
50+
client.WithTransportProtocol(transport.TTHeader | transport.TTHeaderStreaming),
51+
client.WithMetaHandler(transmeta.ClientTTHeaderHandler),
52+
client.WithMetaHandler(transmeta.ClientHTTP2Handler),
53+
}
54+
55+
// thrift binary
56+
cli, err := genericclient.NewClient(downstreamService, generic.BinaryThriftGenericV2(serviceName), options...)
57+
// protobuf binary
58+
cli, err := genericclient.NewClient(downstreamService, generic.BinaryPbGeneric(serviceName, packageName), options...)
59+
```
60+
61+
如果 client 要支持流式泛化调用，需要确认流式调用的协议，默认情况下，通过上述方式生成的泛化 client 的流协议是 TTHeaderStreaming，非流式消息则是 Framed 或 TTHeaderFramed。如果需要配置流式方法走 GRPC 协议，而不改变非流式方法的协议，则添加以下 client options：
62+
63+
```go
64+
client.WithTransportProtocol(transport.GRPCStreaming)
65+
```
66+
67+
## 流量转发
68+
69+
### Ping-pong 流量转发
70+
71+
**推荐最佳实践**：[Proxy 实现示例](https://github.com/cloudwego/kitex-tests/blob/main/generic/proxy/proxy.go#L136)
72+
73+
### 流式流量转发
74+
75+
**推荐最佳实践**：[流式 Proxy 实现](https://github.com/cloudwego/kitex-tests/blob/main/generic/proxy/proxy.go#L150)

0 commit comments

Comments
 (0)