From f13c6e06ad1205f3fb9b2a2da77d51739f2c37c7 Mon Sep 17 00:00:00 2001 From: lim-yoona <44336448+lim-yoona@users.noreply.github.com> Date: Sun, 8 Oct 2023 12:38:55 +0800 Subject: [PATCH] docs: update hostclient config hook (#792) Co-authored-by: Jiun Lee --- content/en/docs/hertz/reference/config.md | 9 +++++---- .../docs/hertz/tutorials/basic-feature/client.md | 12 ++++++++++-- content/zh/docs/hertz/reference/config.md | 7 ++++--- .../docs/hertz/tutorials/basic-feature/client.md | 15 +++++++++++---- 4 files changed, 30 insertions(+), 13 deletions(-) diff --git a/content/en/docs/hertz/reference/config.md b/content/en/docs/hertz/reference/config.md index 595a977830..99e915f31e 100644 --- a/content/en/docs/hertz/reference/config.md +++ b/content/en/docs/hertz/reference/config.md @@ -73,7 +73,7 @@ Server Connection limitation: ## Client -The configuration items on the Client side all use `server.xxx` when initializing the Server, such as: +The configuration items on the Client side all use `client.xxx` when initializing the Client, such as: ```go package main @@ -86,8 +86,8 @@ func main() { } ``` -| Configuration Name | Type | Description | -| :---- | :---- | :---- | +| Configuration Name | Type | Description | +| :---- | :---- |:----| | WithDialTimeout | time.Duration | Connection establishment timeout. Default: 1s. | | WithMaxConnsPerHost | int | Set the maximum number of connections for every host. Default: 512. | | WithMaxIdleConnDuration | time.Duration | Set the idle connection timeout, which will close the connection after the timeout Default: 10s. | @@ -101,4 +101,5 @@ func main() { | WithDialer | network.Dialer | Set the network library used by the client. Default: netpoll. | | WithResponseBodyStream | bool | Set whether to use stream processing. Default: false. | | WithDialFunc | client.DialFunc | Set Dial Function. | -| WithWriteTimeout | time.Duration | The timeout of data writing. Default：infinite.| +| WithWriteTimeout | time.Duration | The timeout of data writing. Default：infinite. | +| WithHostClientConfigHook | func(hc interface{}) error | Set the function hook for re-configure the host client. The function needs to assert the parameter hc as the required struct, such as http1.HostClient, and then perform specific processing. | diff --git a/content/en/docs/hertz/tutorials/basic-feature/client.md b/content/en/docs/hertz/tutorials/basic-feature/client.md index 7c55773820..b31c7aa6e2 100644 --- a/content/en/docs/hertz/tutorials/basic-feature/client.md +++ b/content/en/docs/hertz/tutorials/basic-feature/client.md @@ -59,13 +59,15 @@ func main() { | WithDialer | network.Dialer | specific dialer. | | WithResponseBodyStream | false | determine whether read body in stream or not, default not read in stream. | | WithDisableHeaderNamesNormalizing | false | whether disable header names normalizing, default not disabled, for example, cONTENT-lenGTH -> Content-Length. | -| WithName | "" | client name which used in User-Agent Header. | -| WithNoDefaultUserAgentHeader | false | whether no default User-Agent header, default with User-Agent header. | +| WithName | "" | set client name which used in User-Agent Header. | +| WithNoDefaultUserAgentHeader | false | whether default no User-Agent header, default with User-Agent header. | | WithDisablePathNormalizing | false | whether disable path normalizing, default specification path, for example, http://localhost:8080/hello/../ hello -> http://localhost:8080/hello. | | WithRetryConfig | nil | retry configuration, for specific configuration information, please refer to [retry](/docs/hertz/tutorials/basic-feature/retry/). | | WithWriteTimeout | 0s | write timeout. | | WithConnStateObserve | nil, 5s | set function to observe and record the connection status of HTTP client, as well as observe execution intervals. | | WithDialFunc | network.Dialer | set dialer function. | +| WithHostClientConfigHook | nil | Set the hook function for re-configure the host client. | + Sample Code: @@ -102,6 +104,12 @@ func main() { client.WithWriteTimeout(10*time.Second), client.WithConnStateObserve(stateFunc, observeInterval), client.WithDialFunc(customDialFunc, netpoll.NewDialer()), + client.WithHostClientConfigHook(func(hc interface{}) error { + if hct, ok := hc.(*http1.HostClient); ok { + hct.Addr = "FOO.BAR:443" + } + return nil + }) ) if err != nil { return diff --git a/content/zh/docs/hertz/reference/config.md b/content/zh/docs/hertz/reference/config.md index c3f4eac488..0fbe81c9c7 100644 --- a/content/zh/docs/hertz/reference/config.md +++ b/content/zh/docs/hertz/reference/config.md @@ -85,15 +85,15 @@ func main() { } ``` -| 配置名称 | 类型 | 说明 | -| :---- | :---- | :---- | +| 配置名称 | 类型 | 说明 | +| :---- | :---- |:---| | WithDialTimeout | time.Duration | 连接建立超时时间，默认 1s | | WithMaxConnsPerHost | int | 设置为每个 host 建立的最大连接数，默认 512 | | WithMaxIdleConnDuration | time.Duration | 设置空闲连接超时时间，当超时后会关闭该连接，默认 10s | | WithMaxConnDuration | time.Duration | 设置连接存活的最大时长，超过这个时间的连接在完成当前请求后会被关闭，默认无限长 | | WithMaxConnWaitTimeout | time.Duration | 设置等待空闲连接的最大时间，默认不等待 | | WithKeepAlive | bool | 是否使用长连接，默认开启 | -| WithRetryConfig | ...retry.Option | 设置 client 的 retry config。Hertz 版本需 >= v0.4.0| +| WithRetryConfig | ...retry.Option | 设置 client 的 retry config。Hertz 版本需 >= v0.4.0 | | ~~WithMaxIdempotentCallAttempts~~ | int | 设置最大调用次数，调用失败则会重试。默认 1 次即不重试。v0.4.0 版本废止，该版本之前可用，建议升级 Hertz 版本 >= v0.4.0 并使用 WithRetryConfig 替代 | | WithClientReadTimeout | time.Duration | 设置读取 response 的最长时间，默认无限长 | | WithTLSConfig | *tls.Config | 双向 TLS 认证时，设置 client 的 TLS config | @@ -101,3 +101,4 @@ func main() { | WithResponseBodyStream | bool | 设置是否使用流式处理，默认关闭 | | WithDialFunc | client.DialFunc | 设置 Dial Function | | WithWriteTimeout | time.Duration | 写入数据超时时间，默认值：无限长 | +| WithHostClientConfigHook | func(hc interface{}) error | 设置 hook 函数来重新配置 host client，传入的 func 需要将参数 hc 断言为需要的结构体，比如 http1.HostClient ，再进行具体处理 | diff --git a/content/zh/docs/hertz/tutorials/basic-feature/client.md b/content/zh/docs/hertz/tutorials/basic-feature/client.md index d4bb755869..c10665bee8 100644 --- a/content/zh/docs/hertz/tutorials/basic-feature/client.md +++ b/content/zh/docs/hertz/tutorials/basic-feature/client.md @@ -44,8 +44,8 @@ func main() { ## Client 配置 -| 配置项 | 默认值 | 描述 | -|------------------------------------| -------------- | ---- | +| 配置项 | 默认值 | 描述 | +|------------------------------------|----------------|----| | WithDialTimeout | 1s | 拨号超时时间 | | WithMaxConnsPerHost | 512 | 每个主机可能建立的最大连接数 | | WithMaxIdleConnDuration | 10s | 最大的空闲连接持续时间，空闲的连接在此持续时间后被关闭 | @@ -57,13 +57,14 @@ func main() { | WithDialer | network.Dialer | 设置指定的拨号器 | | WithResponseBodyStream | false | 是否在流中读取 body，默认不在流中读取 | | WithDisableHeaderNamesNormalizing | false | 是否禁用头名称规范化，默认不禁用，如 cONTENT-lenGTH -> Content-Length | -| WithName | "" | 用户代理头中使用的客户端名称 | -| WithNoDefaultUserAgentHeader | false | 是否没有默认的 User-Agent 头，默认有 User-Agent 头 | +| WithName | "" | 设置用户代理头中使用的客户端名称 | +| WithNoDefaultUserAgentHeader | false | 设置是否应该在请求中包含默认的 User-Agent 头, 默认包含 User-Agent 头 | | WithDisablePathNormalizing | false | 是否禁用路径规范化，默认规范路径，如 http://localhost:8080/hello/../ hello -> http://localhost:8080/hello | | WithRetryConfig | nil | HTTP 客户端的重试配置，重试配置详细说明请看 [重试](/zh/docs/hertz/tutorials/basic-feature/retry/) | | WithWriteTimeout | 0s | HTTP 客户端的写入超时时间 | | WithConnStateObserve | nil, 5s | 设置观察和记录 HTTP 客户端的连接状态的函数以及观察执行间隔 | | WithDialFunc | network.Dialer | 设置 HTTP 客户端拨号器函数，会覆盖自定义拨号器 | +| WithHostClientConfigHook | nil | 设置 hook 函数来重新配置 host client | 示例代码： @@ -100,6 +101,12 @@ func main() { client.WithWriteTimeout(10*time.Second), client.WithConnStateObserve(stateFunc, observeInterval), client.WithDialFunc(customDialFunc, netpoll.NewDialer()), + client.WithHostClientConfigHook(func(hc interface{}) error { + if hct, ok := hc.(*http1.HostClient); ok { + hct.Addr = "FOO.BAR:443" + } + return nil + }) ) if err != nil { return