From 72b5b52fe2c215535d6ab695f1b739e27bb2a499 Mon Sep 17 00:00:00 2001 From: Felix021 Date: Wed, 13 Mar 2024 14:09:09 +0800 Subject: [PATCH] doc: Server EnableContextTimeout (#1027) --- .../Tutorials/service-governance/timeout.md | 60 ++++++++++++++++++- .../Tutorials/service-governance/timeout.md | 60 ++++++++++++++++++- 2 files changed, 117 insertions(+), 3 deletions(-) diff --git a/content/en/docs/kitex/Tutorials/service-governance/timeout.md b/content/en/docs/kitex/Tutorials/service-governance/timeout.md index 959db80e5b..7f645a8716 100644 --- a/content/en/docs/kitex/Tutorials/service-governance/timeout.md +++ b/content/en/docs/kitex/Tutorials/service-governance/timeout.md @@ -152,20 +152,78 @@ NOTE： 1. After receiving an exit signal, the server will wait for an ExitWaitTime before exit; 2. If the waiting time is exceeded, the server will forcibly terminate all requests being processed (the client will receive an error). +##### EnableContextTimeout + +> github.com/cloudwego/kitex >= v0.9.0 + +(For non-streaming API) If timeout is available in the request's TTHeader, set it into server request ctx. + +For detailed usage, please refer to the example code below. + +NOTE: +- For Streaming API requests: enabled by default via another way + - Including GRPC/Protobuf and Thrift Streaming + - Client's `ctx.Deadline()` is sent via header `grpc-timeout` to server which will be added to the server request's ctx +- For Non-streaming API requests: disabled by default + - Client should enable TTHeader Transport and ClientTTHeaderMetaHandler, and specify RPC Timeout via client/callopt `WithRPCTimeout` option + - Server should enable this Option and ServerTTHeaderMetaHandler to read the RPCTimeout from requests' TTHeader + - If there's a need in your business code to get this value, call `rpcinfo.GetRPCInfo(ctx).Config().RPCTimeout()` + #### Configuration method ##### By code - Server Option +###### WithReadWriteTimeout + Specified when initializing a server: + ```go import "github.com/cloudwego/kitex/server" svr := xxx.NewServer(handler, server.WithReadWriteTimeout(5 * time.Second), +) +``` + +###### WithExitWaitTime + +Specified when initializing a server: + +```go +import "github.com/cloudwego/kitex/server" + +svr := yourservice.NewServer(handler, server.WithExitWaitTime(5 * time.Second), ) ``` -Note: The two configuration items can be specified independently as needed. + +###### WithEnableContextTimeout + +This Option should be used with TTHeader; please refer to the example code below. + +Client +- Specify TTHeader as Transport Protocol +- Enable [transmeta.ClientTTHeaderHandler](https://github.com/cloudwego/kitex/blob/v0.9.0/pkg/transmeta/ttheader.go#L45) +- Specify an RPC timeout by client.WithRPCTimeout (or by callopt.WithRPCTimeout when sending a request) +```go +cli := yourservice.MustNewClient( + serverName, + client.WithTransportProtocol(transport.TTHeader), + client.WithMetaHandler(transmeta.ClientTTHeaderHandler), + client.WithRPCTimeout(time.Second), +) +``` + +Server +- Specify this option +- Enable [transmeta.ServerTTHeaderHandler](https://github.com/cloudwego/kitex/blob/v0.9.0/pkg/transmeta/ttheader.go#L46) +``` +svr := yourservice.NewServer(handler, + server.WithMetaHandler(transmeta.ServerTTHeaderHandler), + server.WithEnableContextTimeout(true), +) +``` + ## FAQ diff --git a/content/zh/docs/kitex/Tutorials/service-governance/timeout.md b/content/zh/docs/kitex/Tutorials/service-governance/timeout.md index 83ec2067b0..6a324269db 100644 --- a/content/zh/docs/kitex/Tutorials/service-governance/timeout.md +++ b/content/zh/docs/kitex/Tutorials/service-governance/timeout.md @@ -151,20 +151,76 @@ rpctimeout.SetBusinessTimeoutThreshold(10 * time.Millisecond) 1. Server 在收到退出信号时的等待时间； 2. 如果超过该等待时间，Server 将会强制结束所有在处理的请求（客户端会收到错误）。 +##### EnableContextTimeout + +> github.com/cloudwego/kitex >= v0.9.0 + +(针对非 Streaming API）如果从请求的 TTHeader 中读到了 timeout，则写入 server 请求的 ctx 。 + +具体用法请参考后文示例代码。 + +说明： +- Streaming API：已默认开启（通过另外的实现） + - 含 GRPC/Protobuf 和 Thrift Streaming + - client 的 `ctx.Deadline()` 会通过 `grpc_timeout` header 发送给 server，写入 server 的 ctx +- 非 Streaming API：默认未开启 + - 在 client 端需启用 TTHeader Transport 和 ClientTTHeaderMetaHandler，并通过 client/callopt `WithRPCTimeout` option 指定 RPC 超时时间 + - 在 server 端需启用此 Option 及 ServerTTHeaderMetaHandler，才能从请求的 TTHeader 中读取到 RPCTimeout + - 如果业务代码有需要，可用 `rpcinfo.GetRPCInfo(ctx).Config().RPCTimeout()` 获得这个值 + + #### 配置方式 ##### 代码配置 - Server Option +###### WithReadWriteTimeout + 在初始化 Server 时指定： ```go import "github.com/cloudwego/kitex/server" -svr := xxx.NewServer(handler, +svr := yourservice.NewServer(handler, server.WithReadWriteTimeout(5 * time.Second), +) +``` + +###### WithExitWaitTime + +在初始化 Server 时指定： +```go +import "github.com/cloudwego/kitex/server" + +svr := yourservice.NewServer(handler, server.WithExitWaitTime(5 * time.Second), ) ``` -注：两个配置项可以按需独立配置。 + +###### WithEnableContextTimeout + +该 Option 需配合 TTHeader 使用，详见下方示例代码。 + +Client +- 指定 Transport Protocol 为 TTHeader +- 启用 [transmeta.ClientTTHeaderHandler](https://github.com/cloudwego/kitex/blob/v0.9.0/pkg/transmeta/ttheader.go#L45) +- 通过 client.WithRPCTimeout （或者在请求时使用 callopt.WithRPCTimeout）指定超时 +```go +cli := yourservice.MustNewClient( + serverName, + client.WithTransportProtocol(transport.TTHeader), + client.WithMetaHandler(transmeta.ClientTTHeaderHandler), + client.WithRPCTimeout(time.Second), +) +``` + +Server +- 指定该 Option +- 启用 [transmeta.ServerTTHeaderHandler](https://github.com/cloudwego/kitex/blob/v0.9.0/pkg/transmeta/ttheader.go#L46) +``` +svr := yourservice.NewServer(handler, + server.WithMetaHandler(transmeta.ServerTTHeaderHandler), + server.WithEnableContextTimeout(true), +) +``` ## Q&A