Documentation
¶
Overview ¶
Package server provides a configurable HTTP server with TLS support.
Use this package to create and run an HTTP server that handles requests using registered endpoint handlers. The server supports configuration through environment variables and options, including timeouts, TLS modes, and keep-alive settings.
The server supports three TLS modes: OFF for plain HTTP, TLS for server-side TLS, and MUTUAL_TLS for client certificate verification. Endpoint handlers are registered using the api.HTTPEndpointHandler interface, and common middleware can be applied to all routes.
The server provides graceful shutdown capabilities and notifies when the network listener is bound through an optional callback.
Index ¶
- type Config
- type Option
- func WithBoundCallback(callback func(tcpAddr *net.TCPAddr)) Option
- func WithCommonMiddleware(commonMiddleware ...middleware.Middleware) Option
- func WithConfigProvider(provider func() (*Config, error)) Option
- func WithEndpoints(endpointHandlers ...endpoints.EndpointHandler) Option
- func WithListenerProvider(provider func(bindIP string, bindPort uint16) (*net.TCPListener, error)) Option
- type Server
- type TLSMode
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// HTTPServerBindIP is the IP address the server listens on.
HTTPServerBindIP string `config:"ENV" config_default:"::1" validate:"required,ip_addr"`
// HTTPServerBindPort is the port number the server listens on.
HTTPServerBindPort uint16 `config:"ENV" config_default:"0" validate:"gte=0"`
// HTTPServerReadTimeoutMillis is the maximum time (in milliseconds) to read the request.
// Zero or negative means no timeout.
HTTPServerReadTimeoutMillis int `config:"ENV" config_default:"120000" validate:"gte=0"`
// HTTPServerWriteTimeoutMillis is the maximum time (in milliseconds) to write the response.
// Zero or negative means no timeout.
HTTPServerWriteTimeoutMillis int `config:"ENV" config_default:"120000" validate:"gte=0"`
// HTTPServerIdleTimeoutMillis sets the max idle time (in milliseconds) between requests when
// keep-alives are enabled. If zero, ReadTimeout is used. If both are zero, it means no timeout.
HTTPServerIdleTimeoutMillis int `config:"ENV" config_default:"0" validate:"gte=0"`
// HTTPServerHeaderReadTimeoutMillis is the maximum time (in milliseconds) to read request headers.
// If zero, ReadTimeout is used. If both are zero, it means no timeout.
HTTPServerHeaderReadTimeoutMillis int `config:"ENV" config_default:"0" validate:"gte=0"`
// HTTPServerTLSMode specifies the TLS mode of the server: OFF, TLS, or MUTUAL_TLS.
HTTPServerTLSMode TLSMode `config:"ENV" config_default:"TLS" validate:"oneof=OFF TLS MUTUAL_TLS"`
// HTTPServerCert is the path to the TLS certificate file.
HTTPServerCert string `config:"ENV" config_default:"" validate:"http_server_tls_file_path"`
// HTTPServerKey is the path to the TLS private key file.
HTTPServerKey string `config:"ENV" config_default:"" validate:"http_server_tls_file_path"`
// HTTPServerClientCACerts is a list of paths to client CA certificate files (used in mutual TLS).
HTTPServerClientCACerts []string `config:"ENV" config_default:"[]" validate:"http_server_mutual_tls_file_paths"`
// HTTPServerMaxHeaderBytes sets the maximum size in bytes of request headers.
// It doesn't limit the request body size.
HTTPServerMaxHeaderBytes int `config:"ENV" config_default:"1048576" validate:"gte=4096,lte=1073741824"`
// HTTPServerKeepAlive controls whether HTTP keep-alives are enabled.
// By default, keep-alives are always enabled.
HTTPServerKeepAlive bool `config:"ENV" config_default:"true"`
}
Config holds configuration parameters for an HTTP server.
type Option ¶
type Option func(srvOpts *serverOptions)
Option is used to configure the HTTP server.
func WithBoundCallback ¶
WithBoundCallback sets the bound callback for the server. The callback is invoked when the network listener is bound to the configured IP and port.
func WithCommonMiddleware ¶
func WithCommonMiddleware(commonMiddleware ...middleware.Middleware) Option
WithCommonMiddleware adds common middleware for the server. The middleware gets executed on every request to the server.
func WithConfigProvider ¶
WithConfigProvider sets the provider for the config.Config.
func WithEndpoints ¶
func WithEndpoints(endpointHandlers ...endpoints.EndpointHandler) Option
WithEndpoints adds endpoint handlers to the server.
func WithListenerProvider ¶
func WithListenerProvider(provider func(bindIP string, bindPort uint16) (*net.TCPListener, error)) Option
WithListenerProvider sets the provider for the tcp.Listener.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server handles requests via the Hypertext Transfer Protocol (HTTP) and sends back responses. The Server must be allocated using New since the zero value for Server is not valid configuration.
Source Files