server

Documentation

Index

• Constants
• 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 WithEndpointHandlers(endpointHandlers ...api.HTTPEndpointHandler) Option
  • func WithListenerProvider(provider func(bindIP string, bindPort uint16) (*net.TCPListener, error)) Option
• type Server
  • func New(opts ...Option) (*Server, error)
  • func (server *Server) Run() error
  • func (server *Server) Shutdown(ctx context.Context) error
• type TLSMode

Constants

const (
	ConfigPrefix = "HTTP_SERVER"
)

Types

type Config

type Config struct {
	// BindIP is the IP address the server listens on.
	BindIP string `config_format:"snake" config_default:"::1" validate:"required,ip_addr"`

	// BindPort is the port number the server listens on.
	BindPort uint16 `config_format:"snake" config_default:"0" validate:"gte=0"`

	// ReadTimeoutMilliseconds is the maximum time (in seconds) to read the request.
	// Zero or negative means no timeout.
	ReadTimeoutMilliseconds int `config_format:"snake" config_default:"120000" validate:"gte=0"`

	// WriteTimeoutMilliseconds is the maximum time (in seconds) to write the response.
	// Zero or negative means no timeout.
	WriteTimeoutMilliseconds int `config_format:"snake" config_default:"120000" validate:"gte=0"`

	// IdleTimeoutMilliseconds sets the max idle time (in seconds) between requests when keep-alives are enabled.
	// If zero, ReadTimeout is used. If both are zero, it means no timeout.
	IdleTimeoutMilliseconds int `config_format:"snake" config_default:"0" validate:"gte=0"`

	// HeaderReadTimeoutMilliseconds is the maximum time (in seconds) to read request headers.
	// If zero, ReadTimeout is used. If both are zero, it means no timeout.
	HeaderReadTimeoutMilliseconds int `config_format:"snake" config_default:"0" validate:"gte=0"`

	// TLSMode specifies the TLS mode of the server: off, tls, or mutual_tls.
	TLSMode TLSMode `config_format:"snake" config_default:"tls" validate:"oneof=off tls mutual_tls"`

	// Cert is the path to the TLS certificate file.
	Cert string `config_format:"snake" config_default:"" validate:"required_if=TLSMode tls,required_if=TLSMode mutual_tls,omitempty,filepath"`

	// Key is the path to the TLS private key file.
	Key string `config_format:"snake" config_default:"" validate:"required_if=TLSMode tls,required_if=TLSMode mutual_tls,omitempty,filepath"`

	// ClientCACerts is a list of paths to client CA certificate files (used in mutual TLS).
	ClientCACerts []string `config_format:"snake" config_default:"[]" validate:"required_if=TLSMode mutual_tls,dive,required,filepath"`

	// MaxHeaderBytes sets the maximum size in bytes of request headers. It doesn't limit the request body size.
	MaxHeaderBytes int `config_format:"snake" config_default:"1048576" validate:"gte=4096,lte=1073741824"`

	// KeepAlive controls whether HTTP keep-alives are enabled. By default, keep-alives are always enabled.
	KeepAlive bool `config_format:"snake" 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

func WithBoundCallback(callback func(tcpAddr *net.TCPAddr)) Option

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

func WithConfigProvider(provider func() (*Config, error)) Option

WithConfigProvider sets the provider for the config.Config.

func WithEndpointHandlers

func WithEndpointHandlers(endpointHandlers ...api.HTTPEndpointHandler) Option

WithEndpointHandlers adds the 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.

func New

func New(opts ...Option) (*Server, error)

New configures an HTTP server with the provided options.

func (*Server) Run

func (server *Server) Run() error

Run starts an HTTP server. This function blocks as long as its serving HTTP requests.

func (*Server) Shutdown

func (server *Server) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the server and waits for it to finish. This function can be called concurrently, but the first will perform the shutdown action.

type TLSMode

type TLSMode string

TLSMode represents the TLS mode of the HTTP server.

const (
	// TLSModeOff represents plain HTTP without TLS.
	TLSModeOff TLSMode = "off"

	// TLSModeTLS represents HTTP over TLS.
	TLSModeTLS TLSMode = "tls"

	// TLSModeMutualTLS represents HTTP over mutual TLS.
	TLSModeMutualTLS TLSMode = "mutual_tls"
)