server

Documentation

Overview

Package server defines an HTTP server that helps build a production-ready, hardened Go http server with optional graceful shutdown and automatic TLS certificates.

Index

• type Certs
• type GracefulShutdownConfig
• type Server
  • func (s *Server) Build() error
  • func (s *Server) HTTPServer() (*http.Server, error)
  • func (s *Server) ListenAndServe(ctx context.Context) error
• type ServerState
  • func (s ServerState) String() string

Types

type Certs

type Certs struct {
	// AutoCert indicates if the TLS certificate should be automatically
	// generated and renewed.
	AutoCert bool

	// AutoCertCacheDir is the directory path where auto-generated
	// certificates are stored. This should be a secure directory,
	// not exposed to the internet, but the process running the server
	// must have write access to it. If the directory does not exist,
	// it will be created with 0700 permissions.
	AutoCertCacheDir string

	// AutoCertExactHosts is the list of host names that will be allowed
	// by the generated certificate. Only exact matches are supported,
	// no wildcards.
	AutoCertExactHosts []string

	// AutoCertContactEmail is an optional email address that CAs should use
	// to notify about issues with certificates.
	AutoCertContactEmail string

	// If AutoCert is false, CertFile and KeyFile are used as
	// certificate files.
	CertFile string
	KeyFile  string
	// contains filtered or unexported fields
}

Certs configures the TLS certificates of the server.

type GracefulShutdownConfig

type GracefulShutdownConfig struct {
	// Timeout indicates the time allowed for graceful shutdown
	// to proceed.
	Timeout time.Duration

	// ShutdownContext is an optional function that can be used to control
	// cancellation of the shutdown process, in addition to the Timeout field. If
	// set, it is called with the initial shutdown context (which is
	// context.Background or a context with the specified Timeout if it is set).
	// The returned context must not be nil, and it is the context used to call
	// Server.Shutdown.
	ShutdownContext func(ctx context.Context) context.Context

	// Signals is the list of OS signals that initiate a
	// graceful shutdown when caught.
	Signals []os.Signal
	// contains filtered or unexported fields
}

GracefulShutdownConfig configures the graceful shutdown of the server.

type Server

type Server struct {
	// Addr is the TCP address to listen on, <addr>:<port>.
	Addr string

	// Timeouts are transferred as-is to the corresponding
	// http.Server fields, see that type's fields documentation
	// for details.
	ReadTimeout       time.Duration
	ReadHeaderTimeout time.Duration
	WriteTimeout      time.Duration
	IdleTimeout       time.Duration

	// MaxHeaderBytes is transferred as-is to the corresponding
	// http.Server field, see that field's documentation for
	// details.
	MaxHeaderBytes int

	// Protocols is the set of protocols accepted by the server.
	// It is transferred as-is to the corresponding http.Server
	// field, see that field's documentation for details.
	Protocols *http.Protocols

	// Handler is transferred as-is to the corresponding http.Server field, see
	// that field's documentation for details.
	Handler http.Handler

	// HTTP2Config configures the HTTP2 support. It is transferred
	// as-is to the corresponding http.Server fields, see that type's
	// fields documentation for details.
	HTTP2Config *http.HTTP2Config

	// Certs configure TLS certificates for the server.
	Certs *Certs

	// GracefulShutdown enables the graceful shutdown of the
	// server on configured signals, or when the context passed
	// to ListenAndServe is canceled. If nil, there is no automatic
	// graceful shutdown.
	GracefulShutdown *GracefulShutdownConfig

	// ConnStateHook and ServerStateHook are optional function
	// callbacks that get called when the connection or the
	// server (respectively) transition from one state to the
	// next. ConnStateHook is transferred as-is to the
	// http.Server.ConnState field. See the ServerState type
	// and associated constants for details about the
	// ServerStateHook.
	ConnStateHook   func(net.Conn, http.ConnState)
	ServerStateHook func(*http.Server, ServerState)

	// BaseContext and ConnContext are optional functions that get called to
	// generate the base context of the server, or the initial context for
	// a connection. They are both transferred as-is to the http.Server's
	// corresponding fields.
	BaseContext func(net.Listener) context.Context
	ConnContext func(ctx context.Context, c net.Conn) context.Context

	// ErrorLog is the logger used to log errors that may occur
	// while serving connections. It uses the standard library's
	// logger as this is what is supported by the http.Server,
	// but many popular logging packages provide adapters for
	// that logger.
	ErrorLog *log.Logger
	// contains filtered or unexported fields
}

A Server defines parameters for running an HTTP server. Its fields must be set prior to calling Build, HTTPServer or ListenAndServe, and should not be modified afterwards, but further configuration of the built *http.Server can be done by calling HTTPServer before calling ListenAndServe. Once closed, a Server cannot be restarted.

func (*Server) Build

func (s *Server) Build() error

Build generates the properly configured http.Server.

func (*Server) HTTPServer

func (s *Server) HTTPServer() (*http.Server, error)

HTTPServer returns the generated http.Server. It calls Build if it hasn't been called yet.

func (*Server) ListenAndServe

func (s *Server) ListenAndServe(ctx context.Context) error

ListenAndServe calls Build if the Server hasn't been generated yet, and then starts listening and serving connections. It returns the error returned from http.Server.ListenAndServe[TLS], which is always non-nil but is http.ErrServerClosed if the server was closed explicitly.

If GracefulShutdown is configured, the server is shutdown gracefully when the ctx is cancelled or the configured signals are caught, otherwise the server is closed when the ctx is cancelled.

type ServerState

type ServerState int32

ServerState defines the various states the Server may be in.

const (
	// StateNew represents a new Server that is expected to start
	// listening and serving immediately. Servers start at this
	// state and transition to StateListening or StateClosed.
	StateNew ServerState = iota

	// StateListening represents a Server that will start listening
	// and serving connections. From that state, it may transition
	// to StateShutdown or StateClosed.
	StateListening

	// StateShutdown represents a Server that started a graceful
	// shutdown. It may only transition to StateClosed.
	StateShutdown

	// StateClosed represents a closed Server. This is a terminal
	// state.
	StateClosed
)

func (ServerState) String

func (s ServerState) String() string