server

Documentation

Overview

Package server implements a configurable, general-purpose web server. It relies on configurations obtained from the adjacent config package and can execute middleware as defined by the adjacent middleware package.

Index

• func DefaultErrorFunc(w http.ResponseWriter, r *http.Request, status int)
• func ShutdownCallbacks(servers []*Server) []error
• type Config
  • func (c Config) Address() string
• type ListenerFile
• type OptionalCallback
• type Server
  • func New(addr string, configs []Config, gracefulTimeout time.Duration) (*Server, error)
  • func (s *Server) ListenAndServe() error
  • func (s *Server) ListenerFd() *os.File
  • func (s *Server) RunFirstStartupFuncs() error
  • func (s *Server) Serve(ln ListenerFile) error
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (s *Server) Stop() (err error)
  • func (s *Server) WaitUntilStarted()
• type TLSConfig

Functions

func DefaultErrorFunc

func DefaultErrorFunc(w http.ResponseWriter, r *http.Request, status int)

DefaultErrorFunc responds to an HTTP request with a simple description of the specified HTTP status code.

func ShutdownCallbacks

func ShutdownCallbacks(servers []*Server) []error

ShutdownCallbacks executes all the shutdown callbacks for all the virtualhosts in servers, and returns all the errors generated during their execution. In other words, an error executing one shutdown callback does not stop execution of others. Only one shutdown callback is executed at a time. You must protect the servers that are passed in if they are shared across threads.

Types

type Config

type Config struct {
	// The hostname or IP on which to serve
	Host string

	// The host address to bind on - defaults to (virtual) Host if empty
	BindHost string

	// The port to listen on
	Port string

	// The protocol (http/https) to serve with this config; only set if user explicitly specifies it
	Scheme string

	// The directory from which to serve files
	Root string

	// HTTPS configuration
	TLS TLSConfig

	// Middleware stack; map of path scope to middleware -- TODO: Support path scope?
	Middleware map[string][]middleware.Middleware

	// Startup is a list of functions (or methods) to execute at
	// server startup and restart; these are executed before any
	// parts of the server are configured, and the functions are
	// blocking. These are good for setting up middlewares and
	// starting goroutines.
	Startup []func() error

	// FirstStartup is like Startup but these functions only execute
	// during the initial startup, not on subsequent restarts.
	//
	// (Note: The server does not ever run these on its own; it is up
	// to the calling application to do so, and do so only once, as the
	// server itself has no notion whether it's a restart or not.)
	FirstStartup []func() error

	// Functions (or methods) to execute when the server quits;
	// these are executed in response to SIGINT and are blocking
	Shutdown []func() error

	// The path to the configuration file from which this was loaded
	ConfigFile string

	// The name of the application
	AppName string

	// The application's version
	AppVersion string
}

Config configuration for a single server.

func (Config) Address

func (c Config) Address() string

Address returns the host:port of c as a string.

type ListenerFile

type ListenerFile interface {
	net.Listener
	File() (*os.File, error)
}

ListenerFile represents a listener.

type OptionalCallback

type OptionalCallback func(http.ResponseWriter, *http.Request) bool

OptionalCallback is a function that may or may not handle a request. It returns whether or not it handled the request. If it handled the request, it is presumed that no further request handling should occur.

type Server

type Server struct {
	*http.Server
	HTTP2 bool // temporary while http2 is not in std lib (TODO: remove flag when part of std lib)

	ReqCallback OptionalCallback // if non-nil, is executed at the beginning of every request
	// contains filtered or unexported fields
}

Server represents an instance of a server, which serves HTTP requests at a particular address (host and port). A server is capable of serving numerous virtual hosts on the same address and the listener may be stopped for graceful termination (POSIX only).

func New

func New(addr string, configs []Config, gracefulTimeout time.Duration) (*Server, error)

New creates a new Server which will bind to addr and serve the sites/hosts configured in configs. Its listener will gracefully close when the server is stopped which will take no longer than gracefulTimeout.

This function does not start serving.

Do not re-use a server (start, stop, then start again). We could probably add more locking to make this possible, but as it stands, you should dispose of a server after stopping it. The behavior of serving with a spent server is undefined.

func (*Server) ListenAndServe

func (s *Server) ListenAndServe() error

ListenAndServe starts the server with a new listener. It blocks until the server stops.

func (*Server) ListenerFd

func (s *Server) ListenerFd() *os.File

ListenerFd gets a dup'ed file of the listener. If there is no underlying file, the return value will be nil. It is the caller's responsibility to close the file.

func (*Server) RunFirstStartupFuncs

func (s *Server) RunFirstStartupFuncs() error

RunFirstStartupFuncs runs all of the server's FirstStartup callback functions unless one of them returns an error first. It is the caller's responsibility to call this only once and at the correct time. The functions here should not be executed at restarts or where the user does not explicitly start a new instance of the server.

func (*Server) Serve

func (s *Server) Serve(ln ListenerFile) error

Serve starts the server with an existing listener. It blocks until the server stops.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP is the entry point for every request to the address that s is bound to. It acts as a multiplexer for the requests hostname as defined in the Host header so that the correct virtualhost (configuration and middleware stack) will handle the request.

func (*Server) Stop

func (s *Server) Stop() (err error)

Stop stops the server. It blocks until the server is totally stopped. On POSIX systems, it will wait for connections to close (up to a max timeout of a few seconds); on Windows it will close the listener immediately.

func (*Server) WaitUntilStarted

func (s *Server) WaitUntilStarted()

WaitUntilStarted blocks until the server s is started, meaning that practically the next instruction is to start the server loop. It also unblocks if the server encounters an error during startup.

type TLSConfig

type TLSConfig struct {
	Enabled          bool
	Certificate      string
	Key              string
	LetsEncryptEmail string
	Managed          bool // will be set to true if config qualifies for automatic, managed TLS
	//DisableHTTPRedir         bool // TODO: not a good idea - should we really allow it?
	OCSPStaple               []byte
	Ciphers                  []uint16
	ProtocolMinVersion       uint16
	ProtocolMaxVersion       uint16
	PreferServerCipherSuites bool
	ClientCerts              []string
}

TLSConfig describes how TLS should be configured and used.