Configuration instruction

Hertz configuration instruction.

Server

The configuration items on the Server side all use server.xxx when initializing the Server, such as:

package main

import "github.com/cloudwego/hertz/pkg/app/server"

func main() {
	h := server.New(server.WithXXXX())
	...
}
Configuration Name Type Description
WithTransport network.NewTransporter Replace the transport. Default:netpoll.NewTransporter
WithHostPorts string Specify the listening address and port
WithKeepAliveTimeout time.Duration Set the keep-alive time of tcp persistent connection, generally no need to modify it, you should more pay attention to idleTimeout rather than modifying it. Default: 1min.
WithReadTimeout time.Duration The timeout of data reading. Default:3min.
WithIdleTimeout time.Duration The free timeout of the request link for persistent connection. Default: 3min.
WithMaxRequestBodySize int Max body size of a request. Default: 4M (the corresponding value of 4M is 4*1024*1024).
WithRedirectTrailingSlash bool Whether to redirect with the / which is at the end of the router automatically. For example: If there is only /foo/ in the router, /foo will be redirected to /foo/. And if there is only /foo in the router, /foo/ will be redirected to /foo. Default: true.
WithRemoveExtraSlash bool RemoveExtraSlash makes the parameter still valid when it contains an extra /. For example, if WithRemoveExtraSlash is true user//xiaoming can match the user/:name router. Default: false.
WithUnescapePathValues bool If true, the request path will be escaped automatically (eg. ‘%2F’ -> ‘/'). If UseRawPath is false (the default), UnescapePathValues is true, because URI().Path() will be used and it is already escaped. To set WithUnescapePathValues to false, you need to set WithUseRawPath to true. Default (true).
WithUseRawPath bool If true, the original path will be used to match the route. Default: false.
WithHandleMethodNotAllowed bool If true when the current path cannot match any method, the server will check whether other methods are registered with the route of the current path, and if exist other methods, it will respond “Method Not Allowed” and return the status code 405; if not, it will use the handler of NotFound to handle it. Default: false.
WithDisablePreParseMultipartForm bool If true, the multipart form will not be preprocessed. The body can be obtained via ctx.Request.Body() and then can be processed by user. Default: false.
WithStreamBody bool If true, the body will be handled by stream processing. Default: false.
WithNetwork string Set the network protocol, optional: tcp,udp,unix(unix domain socket). Default: tcp.
ContinueHandler func(header *RequestHeader) bool Call the ContinueHandler after receiving the Expect 100 Continue header. With ContinueHandler, the server can decide whether to read the potentially large request body based on the header.
PanicHandler HandlerFunc Handle panic used to generate error pages and return error code 500.
NotFound HandlerFunc The handler to be called when the route does not match.
WithExitWaitTime time.Duration Set the graceful exit time. the Server will stop connection establishment for new requests and set the Connection: Close header for each request after closing. When the set time is reached, Server will to be closed. the Server can be closed early when all connections have been closed. Default: 5s.
WithTLS tls.Config Configuring server tls capabilities.
WithListenConfig net.ListenConfig Set the listener configuration. Can be used to set whether to allow reuse ports, etc.
WithALPN bool Whether to enable ALPN. Default: false.
WithTracer tracer.Tracer Inject tracer implementation, if not inject Tracer. Default: close.
WithTraceLevel stats.Level Set trace level, Default: LevelDetailed.
WithWriteTimeout time.Duration The timeout of data writing. Default:infinite.
WithRedirectFixedPath bool If enabled, if the current request path does not match, the server will try to repair the request path and re-match, if the match is successful and the request is a GET request, it will return status code 301 for redirect, other requests will return 308 for redirect. Disabled by default
WithBasePath string Set the base path, which must be prefixed and suffixed with /. The default is /
WithMaxKeepBodySize int Sets the maximum size of the request body and response body to be retained during reclaim. Unit: Byte. Default value: 4 * 1024 * 1024
WithGetOnly bool If enabled, only GET requests are accepted. Disabled by default
WithKeepAlive bool If enabled, use HTTP keepalive. Enabled by default
WithAltTransport network.NewTransporter Set up the alternate transport. Default value: netpoll.NewTransporter
WithH2C bool Sets whether H2C is enabled. Disabled by default
WithReadBufferSize int Set the read buffer size while limiting the HTTP header size. Default value: 4 * 1024
WithRegistry registry.Registry, *registry.Info Setup registry configuration, service registration information. Default value: registry.NoopRegistry, nil
WithAutoReloadRender bool, time.Duration Set up the automatic reload rendering configuration. Default value: false, 0
WithDisablePrintRoute bool Sets whether debugPrintRoute is disabled. Default disable
WithOnAccept func(conn net.Conn) context.Context Set the callback function when a new connection is accepted but cannot receive data in netpoll. In go net, it will be called before converting tls connection. Default value: nil
WithOnConnect func(ctx context.Context, conn network.Conn) context.Context Set the onConnect function. It can received data from connection in netpoll. In go net, it will be called after converting tls connection. Default value: nil
WithDisableHeaderNamesNormalizing bool Sets whether or not to disable Request and Response Header name normalization (capitalization of the first letter and the first letter after a dash)

Server Connection limitation:

  • If you are using the standard network library, there is no such restriction.
  • If netpoll is used, the maximum number of connections is 10000 (this is the gopool) used at the bottom of netpoll. Yes, the modification method is also very simple, just call the function provided by gopool: gopool.SetCap(xxx) (you can call it once in main.go).

Client

The configuration items on the Client side all use client.xxx when initializing the Client, such as:

package main

import "github.com/cloudwego/hertz/pkg/app/client"

func main() {
	c, err := client.NewClient(client.WithXxx())
	...
}
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.
WithMaxConnDuration time.Duration Set the maximum keep-alive time of the connection, when the timeout expired, the connection will be closed after the current request is completed. Default: infinite.
WithMaxConnWaitTimeout time.Duration Set the maximum time to wait for an idle connection. Default: no wait.
WithKeepAlive bool Whether to use persistent connection. Default: true.
WithRetryConfig …retry.Option Set the retry config of client. Hertz version >= v0.4.0.
WithMaxIdempotentCallAttempts int Set the maximum number of calls. If a call fails, it will be retried. Default: 1 (That is no retry). v0.4.0 is obsolete. Only available before v0.4.0. It is recommended to upgrade Hertz version >= v0.4.0 and use WithRetryConfig instead.
WithClientReadTimeout time.Duration Set the maximum time to read the response. Default: infinite.
WithTLSConfig *tls.Config Set the client’s TLS config for mutual TLS authentication.
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.
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.

Last modified January 18, 2024 : Upload volo blog (#936) (1fc8abb)