diff --git a/content/en/blog/releases/Kitex/release-v0_16_2.md b/content/en/blog/releases/Kitex/release-v0_16_2.md index 1b8f2b5ecf..bdf45692d9 100644 --- a/content/en/blog/releases/Kitex/release-v0_16_2.md +++ b/content/en/blog/releases/Kitex/release-v0_16_2.md @@ -19,11 +19,7 @@ description: > In previous versions, binary generic clients were bound to an IDL Service, requiring maintenance of a large number of clients. This version supports dynamically specifying the IDL Service Name per call, via the newly added `callopt.WithBinaryGenericIDLService(svcName)` / `streamcall.WithBinaryGenericIDLService(svcName)` call options, and the per-call configuration takes precedence over the configuration set at client initialization. Both Ping-Pong and streaming calls are supported. For details, see [Per-Call IDL Service Name](/docs/kitex/tutorials/advanced-feature/generic-call/basic_usage#per-call-idl-service-name). -2. **New In-Process LocalCaller: Supports Unary Local Invocation** - - Added `server.LocalCaller` and `server.NewLocalCaller(caller string, svr Server) (LocalCaller, error)`, which can directly invoke unary methods registered on the Server within the same process. It reuses the Server's Middleware and Tracer, keeping behavior consistent with remote invocations. Streaming methods and generic services that rely on `ServiceInfo.GenericMethod` are rejected. The legacy `server.InvokeCaller` is deprecated. - -3. **Recv Timeout Control for Streaming** +2. **Recv Timeout Control for Streaming** Added `streaming.TimeoutConfig` for fine-grained Recv timeout control on streaming APIs. A dedicated timeout can be configured, and the new `DisableCancelRemote` flag controls whether the remote stream is cascaded-cancelled after timeout. Two configuration entry points are provided: - Per-client: `client.WithStreamRecvTimeoutConfig(streaming.TimeoutConfig)` @@ -31,7 +27,7 @@ description: > When a Recv times out, a new error code `codes.RecvDeadlineExceeded` (value `17`) is returned together with the sentinel error `kerrors.ErrStreamingTimeout`, making timeout classification easier. -4. **Fine-Grained Streaming Event Tracing - StreamEventHandler** +3. **Fine-Grained Streaming Event Tracing - StreamEventHandler** A new event-callback mechanism, independent of the Tracer, can observe the core events of the streaming protocol layer (Stream start, Recv, Send, Recv Header, Stream finish), making it easy to build custom fine-grained streaming monitoring: - Client: `client.WithStreamEventHandler(rpcinfo.ClientStreamEventHandler)` @@ -39,7 +35,7 @@ description: > New event types `stats.StreamStart`, `stats.StreamRecvHeader`, and `stats.StreamFinish` are also added. For details, see [StreamX Detailed Stream Event Tracing](/docs/kitex/tutorials/basic-feature/streamx/streamx_event_handler). -### **Feature/Experience Optimization** +### **Feature/Performance Optimization** 1. **Kitex gRPC: Memory Optimization and Connection Leak Fixes** - **HTTP/2 Write Buffer Reuse and Framer-Level Pooling**: Supports per-connection pooling and reuse of write buffers, reducing memory usage for idle connections, suitable for scenarios where the service needs to directly handle a large number of gRPC connections. Use `client.WithGRPCReuseWriteBuffer` / `server.WithGRPCReuseWriteBuffer` to enable it, and further enable framer-level pooling via `ReuseWriteBufferConfig.EnableReuseHTTP2FramerBuffer`. - **Client-Side Cancel Object Allocation Optimization**: Reduces object allocations for unified cancel on the gRPC client side, avoiding excessive allocations in gateway scenarios where cancel operations are frequent. @@ -55,11 +51,7 @@ description: > 4. **RPCInfo Field Inlining** - Added `rpcinfo.NewRPCInfoWithInlineFields() RPCInfo`, which returns an RPCInfo with inlined sub-objects, reducing per-request pool gets and allocations. Server hot paths and LocalCaller both adopt this inlining approach. - -5. **Load Balance: Consistent-Hash Switched to maphash** - - The consistent-hash key/node hashing in `consistBalancer` replaces `github.com/bytedance/gopkg/util/xxhash3` with `hash/maphash`. Note that `hash/maphash` uses a per-process random seed, so hash values differ across client replicas and restarts. + Added `rpcinfo.NewRPCInfoWithInlineFields() RPCInfo`, which returns an RPCInfo with inlined sub-objects, reducing per-request pool gets and allocations. Server hot paths adopt this inlining approach, improving request handling performance. ### **Bug Fixes** 1. **Streaming-Related Fixes** @@ -68,7 +60,7 @@ description: > 2. **Other Fixes** - **rpcTimeout Ticker Leak Fix** (extremely rare): Closed the ticker in the `rpcTimeout` pool to prevent resource leaks. Most online scenarios are unaffected; this issue is only noticeable in scenarios with extremely low QPS and short processing time for the API. - - **Panic Caused by Writing Elements of Different Types into Container Fields in Generic Calls** (very rare): Writing elements of different types into the same container field could cause a panic. For example, if the field itself is `[]uint8`, the first input may be `uint8` while the second input may be `string`. After the fix, the writer is resolved per element instead of caching the first element's writer, and a type mismatch now returns an error. + - **Panic Caused by Writing Elements of Different Types into Container Fields in Generic Calls** (very rare): Writing elements of different types into the same container field could cause a panic. For example, if the field itself is `[]uint8`, the first input may be `uint8` while the second input may be `string`. After the fix, an error is returned instead of panic. ### **Special Changes - May Affect a Small Number of Services** > Mainly Breaking Changes and API deprecations. No impact on the vast majority of users; users with special dependencies should pay attention. @@ -83,6 +75,10 @@ description: > The `onClose` / `onGoAway` callbacks now fire after the transport transitions to closing/draining and after `http2Client.mu` is released. Callers relying on the old ordering should migrate to `grpc.NewClientTransportWithConfig`. +3. **`consistBalancer` Consistent-Hash Algorithm Switched** (#1924) + + The consistent-hash key/node hashing in `consistBalancer` replaces `github.com/bytedance/gopkg/util/xxhash3` with `hash/maphash`. Because `hash/maphash` uses a per-process random seed, hash values **differ across client replicas and restarts**. + #### Deprecations > APIs are only marked as deprecated in this version; they still work, but please migrate to the new APIs at your earliest convenience. @@ -93,23 +89,13 @@ description: > See [Connection Multiplexing](/docs/kitex/tutorials/basic-feature/connection_type#connection-multiplexing) for the rationale. -2. **`server.InvokeCaller` Deprecated** (#1930) - - Use the newly added `server.LocalCaller` instead. - -3. **`grpc.NewClientTransport` Deprecated** (#1945) - - Use `grpc.NewClientTransportWithConfig(ctx, conn, opts, grpc.ClientConfig)` instead. The new entry's `OnClose` / `OnGoAway` callbacks receive context and transport parameters. - -4. **`kerrors.ErrRPCFinish` Restored as Deprecated Symbol** (#1953) +2. **`kerrors.ErrRPCFinish` Restored as Deprecated Symbol** (#1953) - v0.16.2 restores this API as a deprecated symbol for backward compatibility with pre-v0.15 code. + This API was removed in v0.15.0. v0.16.2 restores it as a deprecated symbol for backward compatibility with pre-v0.15 code. -5. **Streaming-Related API Deprecations** +3. **Streaming-Related API Deprecations** - `client.WithStreamRecvTimeout` is deprecated; use `client.WithStreamRecvTimeoutConfig` instead (#1911) - `streamcall.WithRecvTimeout` is deprecated; use `streamcall.WithRecvTimeoutConfig` instead (#1911) - - `rpcinfo.TraceController.GetStreamEventHandler()` is deprecated; use `TraceController.Handle*` methods instead (#1905) - - `internal/stream.StreamEventHandler` is deprecated; use `rpcinfo.ClientStreamEventHandler` / `rpcinfo.ServerStreamEventHandler` instead (#1905) ## **Full Change** diff --git a/content/zh/blog/releases/Kitex/release-v0_16_2.md b/content/zh/blog/releases/Kitex/release-v0_16_2.md index 55791e9ba4..f8310034d6 100644 --- a/content/zh/blog/releases/Kitex/release-v0_16_2.md +++ b/content/zh/blog/releases/Kitex/release-v0_16_2.md @@ -19,11 +19,7 @@ description: > 旧版二进制泛化 Client 与 IDL Service 绑定，需要维护大量 Client。本版本支持请求时动态指定 IDL Service Name，通过新增的 `callopt.WithBinaryGenericIDLService(svcName)` / `streamcall.WithBinaryGenericIDLService(svcName)` 调用选项指定，且调用维度的配置优先级更高。Ping-Pong 和流式调用均支持，详见 [动态指定 IDL Service Name](/zh/docs/kitex/tutorials/advanced-feature/generic-call/basic_usage#动态指定-idl-service-name)。 -2. **新增进程内 LocalCaller：支持 unary 本地调用** - - 新增 `server.LocalCaller` 与 `server.NewLocalCaller(caller string, svr Server) (LocalCaller, error)`，可在进程内直接调用 Server 注册的 unary 方法。复用 Server 的 Middleware、Tracer，行为与远程调用一致；流式方法和依赖 `ServiceInfo.GenericMethod` 的 generic service 会被拒绝。旧的 `server.InvokeCaller` 标记为废弃。 - -3. **流式接口 Recv 超时控制** +2. **流式接口 Recv 超时控制** 新增 `streaming.TimeoutConfig`，支持对流式接口 Recv 进行细粒度超时控制，可单独配置超时时间，并通过 `DisableCancelRemote` 控制超时后是否级联取消远端流。提供两种配置入口： - Client 维度：`client.WithStreamRecvTimeoutConfig(streaming.TimeoutConfig)` @@ -31,7 +27,7 @@ description: > Recv 超时返回新错误码 `codes.RecvDeadlineExceeded`（值为 `17`）以及哨兵错误 `kerrors.ErrStreamingTimeout`，便于区分超时类型。 -4. **流式细粒度事件追踪 - StreamEventHandler** +3. **流式细粒度事件追踪 - StreamEventHandler** 新增独立于 Tracer 的流式事件回调机制，可以感知流式协议层面的核心 Event（Stream 开始、Recv、Send、Recv Header、Stream 结束），便于定制细粒度的流式监控： - Client：`client.WithStreamEventHandler(rpcinfo.ClientStreamEventHandler)` @@ -39,7 +35,7 @@ description: > 同时新增 `stats.StreamStart`、`stats.StreamRecvHeader`、`stats.StreamFinish` 事件类型。详见 [StreamX 流式细粒度事件追踪](/zh/docs/kitex/tutorials/basic-feature/streamx/streamx_event_handler)。 -### **功能/体验优化** +### **功能/性能优化** 1. **Kitex gRPC：内存优化与连接泄漏修复** - **HTTP/2 write buffer 复用与 framer 池化**：支持连接维度的 write buffer 池化复用，降低空闲连接内存占用，适用于直接承接大量 gRPC 连接的场景。通过 `client.WithGRPCReuseWriteBuffer` / `server.WithGRPCReuseWriteBuffer` 启用，并在 `ReuseWriteBufferConfig.EnableReuseHTTP2FramerBuffer` 中进一步启用 framer 层的池化。 - **Client 侧 cancel 对象分配优化**：减少 gRPC client 在统一 cancel 场景下的对象分配，避免网关等需要频繁 cancel 的场景分配大量对象。 @@ -55,11 +51,7 @@ description: > 4. **RPCInfo 字段内联** - 新增 `rpcinfo.NewRPCInfoWithInlineFields() RPCInfo`，返回带内联子对象的 RPCInfo，减少每次请求的 pool get 与对象分配；server 热点路径与 LocalCaller 均采用该内联方式。 - -5. **loadbalance：consistent-hash 使用 maphash** - - `consistBalancer` 的 consistent-hash key/node 哈希将 `github.com/bytedance/gopkg/util/xxhash3` 替换为 `hash/maphash`。注意 `hash/maphash` 在每个进程使用随机种子，hash 值会在不同 client 副本和重启之间不同。 + 新增 `rpcinfo.NewRPCInfoWithInlineFields() RPCInfo`，返回带内联子对象的 RPCInfo，减少每次请求的 pool get 与对象分配；server 热点路径采用该内联方式，提升请求处理性能。 ### **问题修复** 1. **流式相关问题修复** @@ -68,7 +60,7 @@ description: > 2. **其他问题修复** - **rpcTimeout ticker 泄漏修复**（极小概率）：关闭 rpcTimeout pool 中的 ticker，防止资源泄漏。线上绝大部分场景无问题，只在 QPS 极低且接口处理时间较短的场景会感知到。 - - **泛化调用容器字段写入不同类型元素 panic**（小概率）：当某个容器字段被写入了不同类型的元素时会 panic（例如字段本身是 `[]uint8`，第一个传入 `uint8`，第二个却传入 `string`）。修复后按元素逐个解析 writer 而非缓存第一个 writer，并对类型不匹配返回错误。 + - **泛化调用容器字段写入不同类型元素 panic**（小概率）：当某个容器字段被写入了不同类型的元素时会 panic（例如字段本身是 `[]uint8`，第一个传入 `uint8`，第二个却传入 `string`）。修复后返回错误而不是直接 panic。 ### **特殊变更 - 少数服务可能会有影响** > 主要为 Breaking Changes 与接口废弃，对绝大部分用户无影响，请有特殊依赖的用户关注。 @@ -83,6 +75,10 @@ description: > `onClose` / `onGoAway` 回调改为在 transport 状态转换为 closing/draining 并释放 `http2Client.mu` 之后触发。依赖旧时序的调用方请迁移至 `grpc.NewClientTransportWithConfig`。 +3. **`consistBalancer` 一致性哈希算法替换**（#1924） + + `consistBalancer` 的 consistent-hash key/node 哈希将 `github.com/bytedance/gopkg/util/xxhash3` 替换为 `hash/maphash`。`hash/maphash` 在每个进程使用随机种子，hash 值会在**不同 client 副本和重启之间不同**。 + #### 接口废弃 > 当前版本仅标记废弃，仍保留可用，请及时迁移到新接口。 @@ -93,23 +89,13 @@ description: > 废弃原因详见 [连接多路复用](/zh/docs/kitex/tutorials/basic-feature/connection_type#连接多路复用)。 -2. **`server.InvokeCaller` 废弃**（#1930） - - 使用本版本新增的 `server.LocalCaller` 替代。 - -3. **`grpc.NewClientTransport` 废弃**（#1945） - - 使用 `grpc.NewClientTransportWithConfig(ctx, conn, opts, grpc.ClientConfig)` 替代。新入口的 `OnClose` / `OnGoAway` 回调接收 context 与 transport 参数。 - -4. **`kerrors.ErrRPCFinish` 恢复为废弃符号**（#1953） +2. **`kerrors.ErrRPCFinish` 恢复为废弃符号**（#1953） - v0.16.2 重新加回该 API 作为废弃符号，便于 pre-v0.15 代码继续编译。 + 该 API 在 v0.15.0 被移除，v0.16.2 重新加回作为废弃符号，便于 pre-v0.15 代码继续编译。 -5. **流式相关接口废弃** +3. **流式相关接口废弃** - `client.WithStreamRecvTimeout` 废弃，使用 `client.WithStreamRecvTimeoutConfig` 替代（#1911） - `streamcall.WithRecvTimeout` 废弃，使用 `streamcall.WithRecvTimeoutConfig` 替代（#1911） - - `rpcinfo.TraceController.GetStreamEventHandler()` 废弃，使用 `TraceController.Handle*` 方法替代（#1905） - - `internal/stream.StreamEventHandler` 类型废弃，使用 `rpcinfo.ClientStreamEventHandler` / `rpcinfo.ServerStreamEventHandler` 替代（#1905） ## **详细变更**