doc: conn type and transport protocols (#822)

Author: ppzqh

content/en/docs/kitex/Tutorials/basic-feature/connection_type.md

@@ -1,25 +1,24 @@
 ---
 title: "Connection Type"
-date: 2021-09-28
+date: 2023-10-16
 weight: 5
 keywords: ["Kitex", "Short Connection", "Long Connection", "Connection Multiplexing"]
 description: "Kitex supports short connections, long connection pool, connection multiplexing and connection pool status monitoring."
 ---
 
 Kitex provides **Short Connection**,  **Long Connection Pool** and **Connection Multiplexing** for different business scenarios. 
-Kitex uses Long Connection Pool by default after v0.0.2, but adjusting the Pool Config according to your need is suggested.
+Kitex uses **Long Connection Pool by default** after v0.0.2, but adjusting the Pool Config according to your need is suggested.
 
 ## Short Connection
 
-Every request needs to create a connection, the performance is bad, so it is not suggested normally.
-
-Enable Short Connection：
+Every request needs to create a connection. The performance is bad, so it is not suggested in most cases. However, short connections should be used in some scenarios. For example, if there are too many instances on the caller side, it will increase the burden on callee services. Please choose according to the situation.
+To enable short connection：
 
 ```go
 xxxCli := xxxservice.NewClient("destServiceName", client.WithShortConnection())
 ```
 
-## Long Connection Pool
+## Long Connection Pool (Default)
 
 Kitex enable Long Connection Pool after >= v0.0.2, default config params are as below：
 
@@ -51,14 +50,14 @@ Parameter description:
 Each downstream address corresponds to a connection pool, the connection pool is a ring composed of connections, and the size of the ring is `MaxIdlePerAddress`.
 
 When getting a connection of downstream address, proceed as follows:
-1. Try to fetch a connection from the ring, if fetching failed (no idle connections remained), then try to establish a new connection. In other words, the number of connections may exceed `MaxIdlePerAddress`
+1. Try to fetch a connection from the pool, if fetching failed (no idle connections remained), then try to establish a new connection. In other words, the number of connections may exceed `MaxIdlePerAddress`
 2. If fetching succeed, then check whether the idle time of the connection (since the last time it was placed in the connection pool) has exceeded MaxIdleTimeout. If yes, this connection will be closed and a new connection will be created.
 
 When the connection is ready to be returned after used, proceed as follows:
 
 1. Check whether the connection is normal, if not, close it directly
 2. Check whether the idle connection number exceeds  `MaxIdleGlobal`, and if yes, close it directly
-3. Check whether free space remained in the ring of the target connection pool, if yes, put it into the pool, otherwise close it directly
+3. Check whether free space remained in the pool of the target connection pool. If yes, put it into the pool, otherwise close it directly
 
 ### Parameter Setting Suggestion
 
@@ -68,12 +67,13 @@ The setting of parameters is suggested as follows:
   - For example, the cost of each request is 100ms, and the request spread to each downstream address is 100QPS, the value is suggested to set to 10, because each connection handles 10 requests per second, 100QPS requires 10 connections to handle
   - In the actual scenario, the fluctuation of traffic is also necessary to be considered. Pay attention, the connection within MaxIdleTimeout will be recycled if it is not used
   - Summary: this value be set too large or too small would lead to degenerating to the short connection
-- `MinIdlePerAddress`: Assuming that there are periodic requests and the period is greater than `MaxIdleTimeout`, setting this parameter can avoid creating a new connection every time.
-  - The parameter consideration is similar to `MaxIdlePerAddress` and can be set according to the average latency of requests and the throughput.
-  - For example, if `MinIdlePerAddress` is set to 5 and the response time of each request is 100ms. 50 requests can be processed per second (50QPS) without creating a new connection.
 - `MaxIdleGlobal`: should be larger than the total number of `downstream targets number * MaxIdlePerAddress`
   - Notice: this value is not very valuable, it is suggested to set it to a super large value. In subsequent versions, considers discarding this parameter and providing a new interface
+  - Since v0.7.2, no limit for `MaxIdleGlobal` if not set. 
 - `MaxIdleTimeout`: since the server will clean up inactive connections within 10min, the client also needs to clean up long-idle connections in time to avoid using invalid connections. This value cannot exceed 10min when the downstream is also a Kitex service
+- `MinIdlePerAddress` (Kitex >= v0.4.3): Assuming that there are periodic requests and the period is greater than `MaxIdleTimeout`, setting this parameter can avoid creating a new connection every time.
+  - The parameter consideration is similar to `MaxIdlePerAddress` and can be set according to the average latency of requests and the throughput.
+  - For example, if `MinIdlePerAddress` is set to 5 and the response time of each request is 100ms. 50 requests can be processed per second (50QPS) without creating a new connection.
 
 ## Connection Multiplexing
 

content/en/docs/kitex/Tutorials/basic-feature/transport_protocol.md

@@ -1,6 +1,6 @@
 ---
 title: "Transport Protocol"
-date: 2022-07-20
+date: 2023-10-16
 weight: 3
 keywords: ["Kitex", "TTHeader", "HTTP2"]
 description: Kitex supports transport protocols of TTHeader、HTTP2.
@@ -29,46 +29,52 @@ Here are the available combination options of transport protocols and message pr
 If you want to use custom implementations for the message or transport protocol, you can find help here [Extension of Codec](/docs/kitex/tutorials/framework-exten/codec/).
 
 ## Configuration
-
-You can configure the transport protocol when initializing the client:
-
+### Client
+#### Thrift
+1. Buffered: PurePayload (by default)
+2. configure Framed: prepend a 4-byte (int32) length before the Thrift pure payload
 ```go
-// client option
-client.WithTransportProtocol(transport.XXX)
+cli := xxx.NewClient("service_name", client.WithTransportProtocol(transport.Framed))
 ```
-
-Kitex Server supports protocol detection for all supported protocols and doesn't require explicit configuration.
-
-## Usage
-
-### Thrift + TTHeader
-
+3. configure TTHeader: the protocol for Byted Mesh (Service Mesh 协议 )
 ```go
-// client side
 var opts []client.Option
 opts = append(opts, client.WithTransportProtocol(transport.TTHeader))
 opts = append(opts, client.WithMetaHandler(transmeta.ClientTTHeaderHandler))
-cli, err := xxxservice.NewClient(targetService, opts...)
 
-// server side no need to config transport protocol
-var opts []server.Option
-opts = append(opts, server.WithMetaHandler(transmeta.ServerTTHeaderHandler))
-cli, err := xxxservice.NewServer(handler, opts...)
+cli := xxx.NewClient("service_name", opts)
+```
+4. configure TTHeaderFramed: TTHeader | Framed (Bit OR)
+```go
+var opts []client.Option
+opts = append(opts, client.WithTransportProtocol(transport.TTHeaderFramed))
+opts = append(opts, client.WithMetaHandler(transmeta.ClientTTHeaderHandler))
+cli := xxx.NewClient("service_name", opts)
 ```
 
-### gRPC
-
+#### gRPC
+client configures gRPC protocol：
 ```go
-// client side
 var opts []client.Option
 opts = append(opts, client.WithTransportProtocol(transport.GRPC))
 opts = append(opts, client.WithMetaHandler(transmeta.ClientHTTP2Handler))
-cli, err := xxxservice.NewClient(targetService, opts...)
+cli := xxx.NewClient("service_name", client.WithTransportProtocol(transport.GRPC))
+```
+NOTE: if there's no streaming API in the IDL, this option is needed for enabling gRPC protocol, otherwise kitex will only send protobuf binary (not gRPC).
 
+### Server
+Multi-protocol is supported by default. Metahandlers should be configured to enable transparent information transmission.
 
-// server side no need to config transport protocol
+#### Thrift (TTHeader)
+```go
+var opts []server.Option
+opts = append(opts, server.WithMetaHandler(transmeta.ServerTTHeaderHandler))
+svr, err := xxxservice.NewServer(handler, opts...)
+```
+#### gRPC
+```go
 var opts []server.Option
 opts = append(opts, server.WithMetaHandler(transmeta.ServerHTTP2Handler))
-cli, err := xxxservice.NewServer(handler, opts...)
-
+svr, err := xxxservice.NewServer(handler, opts...)
 ```
+

content/zh/docs/kitex/Tutorials/basic-feature/connection_type.md

@@ -1,6 +1,6 @@
 ---
 title: "连接类型"
-date: 2021-09-28
+date: 2023-10-16
 weight: 5
 keywords: ["Kitex", "短连接", "长连接", "连接多路复用"]
 description: "Kitex 支持短连接、长连接池、连接多路复用以及连接池状态监控。"
@@ -18,7 +18,7 @@ description: "Kitex 支持短连接、长连接池、连接多路复用以及连
 xxxCli := xxxservice.NewClient("destServiceName", client.WithShortConnection())
 ```
 
-## 长连接池
+## 长连接池（默认）
 
 Kitex >= v0.0.2 默认配置了连接池，配置参数如下：
 
@@ -41,25 +41,26 @@ xxxCli := xxxservice.NewClient("destServiceName", client.WithLongConnection(conn
 
 - `MaxIdlePerAddress` 表示每个后端实例可允许的最大闲置连接数
 - `MaxIdleGlobal` 表示全局最大闲置连接数
+  - 从 v0.7.2 开始, 如果未设置 `MaxIdleGlobal`，默认没有限制.
 - `MaxIdleTimeout` 表示连接的闲置时长，超过这个时长的连接会被关闭（最小值 3s，默认值 30s ）
 - `MinIdlePerAddress`(Kitex >= v0.4.3)
   - 表示对每个后端实例维护的最小空闲连接数，这部分连接即使空闲时间超过 `MaxIdleTimeout` 也不会被清理。
   - 当前版本的`MinIdlePerAddress`的值不能超过5。
 ### 实现
 
-长连接池的实现方案是每个 address 对应一个连接池，这个连接池是一个由连接构成的 ring，ring 的大小为 MaxIdlePerAddress。
+长连接池的实现方案是每个 address 对应一个连接池，池的大小为 `MaxIdlePerAddress`。
 
 当选择好目标地址并需要获取一个连接时，按以下步骤处理 :
 
-1. 首先尝试从这个 ring 中获取，如果获取失败（没有空闲连接），则发起新的连接建立请求，即连接数量可能会超过 MaxIdlePerAddress
-2. 如果从 ring 中获取成功，则检查该连接的空闲时间（自上次放入连接池后）是否超过了 MaxIdleTimeout，如果超过则关闭该连接并新建
+1. 首先尝试从连接池中获取，如果获取失败(没有空闲连接)，则发起新的连接建立请求，即连接数量可能会超过 `MaxIdlePerAddress`
+2. 如果获取成功，则检查该连接的空闲时间(自上次放入连接池后)是否超过了 `MaxIdleTimeout`, 如果超过则关闭该连接并新建
 3. 全部成功后返回给上层使用
 
 在连接使用完毕准备归还时，按以下步骤依次处理：
 
 1. 检查连接是否正常，如果不正常则直接关闭
-2. 查看空闲连接是否超过全局的 MaxIdleGlobal，如果超过则直接关闭
-3. 待归还到的连接池的 ring 中是否还有空闲空间，如果有则直接放入，否则直接关闭
+2. 查看空闲连接是否超过全局的 `MaxIdleGlobal`，如果超过则直接关闭
+3. 待归还到的连接池是否还有空闲空间，如果有则直接放入，否则直接关闭
 
 ### 参数设置建议
 

content/zh/docs/kitex/Tutorials/basic-feature/transport_protocol.md

@@ -1,6 +1,6 @@
 ---
 title: "传输协议"
-date: 2022-06-17
+date: 2023-10-16
 weight: 3
 keywords: ["Kitex", "TTHeader", "HTTP2"]
 description: Kitex 支持 TTHeader、HTTP2 传输协议。
@@ -14,60 +14,64 @@ description: Kitex 支持 TTHeader、HTTP2 传输协议。
 Kitex 目前支持两种传输协议：[TTHeader](../../../reference/transport_protocol_ttheader/)、HTTP2，但实际提供配置的 Transport Protocol 是：TTHeader、GRPC、Framed、TTHeaderFramed、PurePayload。
 
 这里做一些说明：
-
 - 因为 Kitex 对 Protobuf 的支持有 Kitex Protobuf 和 gRPC，为方便区分将 gRPC 作为传输协议的分类，框架会根据是否有配置 gRPC 决定使用哪个协议；
 - Framed 严格意义上并不是传输协议，只是标记 Payload Size 额外增加的 4 字节头，但消息协议对是否有 Framed 头并不是强制的，PurePayload 即没有任何头部的，所以将 Framed 也作为传输协议的分类；
 - Framed 和 TTHeader 也可以结合使用，所以有 TTHeaderFramed 。
 
 消息协议可选的传输协议组合如下：
 
-* Thrift: **TTHeader**(建议)、Framed、TTHeaderFramed
-* KitexProtobuf: **TTHeader**(建议)、Framed、TTHeaderFramed
+* Thrift: **TTHeader** (建议)、Framed、TTHeaderFramed
+* KitexProtobuf: **TTHeader** (建议)、Framed、TTHeaderFramed
 * gRPC: HTTP2
 
 如果想自定义消息协议和传输协议参考：[编解码(协议)扩展](../../framework-exten/codec)
 
-## 配置项
-
-Client 初始化时通过 `WithTransportProtocol` 配置传输协议：
+## 配置方式
+### Client
+#### Thrift
 
+1. 默认 Buffered：PurePayload
+2. 指定 Framed：PurePayload前增加 4 个字节（int32）指定 Payload Size
 ```go
-// client option
-client.WithTransportProtocol(transport.XXX)
+cli := xxx.NewClient("service_name", client.WithTransportProtocol(transport.Framed))
 ```
-
-Server 支持协议探测（在 Kitex 默认支持的协议内），无需配置传输协议。
-
-## 使用示例
-
-### Thrift + TTHeader
-
+3. 指定TTHeader：
 ```go
-// client side
 var opts []client.Option
 opts = append(opts, client.WithTransportProtocol(transport.TTHeader))
 opts = append(opts, client.WithMetaHandler(transmeta.ClientTTHeaderHandler))
-cli, err := xxxservice.NewClient(targetService, opts...)
 
-// server side no need to config transport protocol
-var opts []server.Option
-opts = append(opts, server.WithMetaHandler(transmeta.ServerTTHeaderHandler))
-cli, err := xxxservice.NewServer(handler, opts...)
+cli := xxx.NewClient("service_name", opts)
+```
+4. 指定 TTHeaderFramed：TTHeader | Framed (Bit OR)
+```go
+var opts []client.Option
+opts = append(opts, client.WithTransportProtocol(transport.TTHeaderFramed))
+opts = append(opts, client.WithMetaHandler(transmeta.ClientTTHeaderHandler))
+cli := xxx.NewClient("service_name", opts)
 ```
-
 
 ### gRPC
-
+client 指定 gRPC 协议：
 ```go
-// client side
 var opts []client.Option
 opts = append(opts, client.WithTransportProtocol(transport.GRPC))
 opts = append(opts, client.WithMetaHandler(transmeta.ClientHTTP2Handler))
-cli, err := xxxservice.NewClient(targetService, opts...)
-
+cli := xxx.NewClient("service_name", client.WithTransportProtocol(transport.GRPC))
+```
+注意: 如果 IDL 中没有 Streaming API，则需要此选项来启用 gRPC 协议，否则 kitex 将仅发送 protobuf binary（而不是 gRPC）。
 
-// server side no need to config transport protocol
+### Server 
+支持协议探测（在 Kitex 默认支持的协议内），无需配置传输协议。为了支持基于 header 的信息透传，需要配置 metaHandler
+#### Thrift (TTHeader)
+```go
+var opts []server.Option
+opts = append(opts, server.WithMetaHandler(transmeta.ServerTTHeaderHandler))
+svr, err := xxxservice.NewServer(handler, opts...)
+```
+#### gRPC
+```go
 var opts []server.Option
 opts = append(opts, server.WithMetaHandler(transmeta.ServerHTTP2Handler))
-cli, err := xxxservice.NewServer(handler, opts...)
+svr, err := xxxservice.NewServer(handler, opts...)
 ```