http

README

Package http

Provide common utilities when deploying a production HTTP(S) service. The main element of the package is the "Server" type. Use it to easily create and manage an HTTP(S) server instance.

// Server options
options := []Option{
  WithPort(8080),
  WithIdleTimeout(5 * time.Second),
  WithHandler(mux),
}

// Create and start the server in the background
server, _ := NewServer(options...)
go func() {
  _ = server.Start()
}()

// When no longer required, gracefully stop the server
_ = server.Stop(true)

Documentation

Overview

Package http provide common utilities when deploying a production HTTP(S) service.

The main element of the package is the "Server" type. Use it to easily create and manage an HTTP(S) server instance.

// Server options
options := []Option{
	WithPort(8080),
	WithIdleTimeout(5 * time.Second),
	WithHandler(mux),
}

// Create and start the server in the background
server, _ := NewServer(options...)
go func() {
	_ = server.Start()
}()

// When no longer required, gracefully stop the server
_ = server.Stop(true)

Index

• type Option
  • func WithHandler(handler lib.Handler) Option
  • func WithIdleTimeout(timeout time.Duration) Option
  • func WithMiddleware(md ...func(lib.Handler) lib.Handler) Option
  • func WithPort(port int) Option
  • func WithTLS(settings TLS) Option
• type Server
  • func NewServer(options ...Option) (*Server, error)
  • func (srv *Server) Start() error
  • func (srv *Server) Stop(graceful bool) error
• type TLS
  • func (t TLS) Expand() (*tls.Config, error)

Examples

• NewServer

Types

type Option

type Option func(srv *Server) error

Option allows adjusting server settings following a functional pattern.

func WithHandler

func WithHandler(handler lib.Handler) Option

WithHandler sets the HTTP handler used by the server.

func WithIdleTimeout

func WithIdleTimeout(timeout time.Duration) Option

WithIdleTimeout sets the maximum amount of time to wait for the next request when "keep-alive" is enabled. You can use `0` to disable all the server's timeouts.

func WithMiddleware

func WithMiddleware(md ...func(lib.Handler) lib.Handler) Option

WithMiddleware register the provided middleware to customize/extend the processing of HTTP requests. When applying middleware the ordering is very important, in this case it will be applied in the same order provided. For example:

Use(foo bar baz)

Will be applied as:

baz( bar( foo(handler) ) )

func WithPort

func WithPort(port int) Option

WithPort sets the TCP port to handle requests.

func WithTLS

func WithTLS(settings TLS) Option

WithTLS enable secure communications with server using HTTPS connections.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server provides the main HTTP(S) service provider.

func NewServer

func NewServer(options ...Option) (*Server, error)

NewServer returns a new read-to-use server instance adjusted with the provided configuration options.

Example

// Server options
options := []Option{
	WithHandler(mux),
	WithPort(8080),
	WithIdleTimeout(5 * time.Second),
	WithMiddleware(
		mwRecover.Handler(),
		mwProxy.Handler(),
		mwGzip.Handler(9),
	),
}

// Create and start the server in the background
server, _ := NewServer(options...)
go func() {
	_ = server.Start()
}()

// When no longer required, gracefully stop the server
_ = server.Stop(true)

func (*Server) Start

func (srv *Server) Start() error

Start the server instance and start receiving and handling requests.

func (*Server) Stop

func (srv *Server) Stop(graceful bool) error

Stop the server instance. If graceful is set, the server closes without interrupting any active connections by first closing all open listeners, then closing all idle connections, and then waiting indefinitely for connections to return to idle.

type TLS

type TLS struct {
	// Server certificate, PEM-encoded.
	Cert []byte

	// Server private key, PEM-encoded.
	PrivateKey []byte

	// List of ciphers to allow.
	SupportedCiphers []uint16

	// Server preferred curves configuration.
	PreferredCurves []tls.CurveID

	// Whether to include system CAs.
	IncludeSystemCAs bool

	// Custom certificate authorities to include when accepting TLS connections.
	CustomCAs [][]byte
}

TLS defines available settings when enabling secure TLS communications.

func (TLS) Expand

func (t TLS) Expand() (*tls.Config, error)

Expand returns a TLS configuration instance based on the provided settings.