Version: v0.8.3 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Apr 26, 2016 License: Apache-2.0 Imports: 17 Imported by: 0



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.



This section is empty.


This section is empty.


func DefaultErrorFunc added in v0.7.2

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 added in v0.8.0

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.


type Config added in v0.6.0

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
	Middleware []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 added in v0.6.0

func (c Config) Address() string

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

type ListenerFile added in v0.8.0

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

ListenerFile represents a listener.

type OptionalCallback added in v0.8.1

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 {
	HTTP2 bool // whether to enable HTTP/2

	OnDemandTLS bool // whether this server supports on-demand TLS (load certs at handshake-time)

	ReqCallback OptionalCallback // if non-nil, is executed at the beginning of every request
	SNICallback func(clientHello *tls.ClientHelloInfo) (*tls.Certificate, error)
	// 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 added in v0.8.0

func (s *Server) ListenAndServe() error

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

func (*Server) ListenerFd added in v0.8.0

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 added in v0.8.0

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 added in v0.8.0

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 added in v0.8.0

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 added in v0.6.0

type TLSConfig struct {
	Enabled                  bool // will be set to true if TLS is enabled
	LetsEncryptEmail         string
	Manual                   bool // will be set to true if user provides own certs and keys
	Managed                  bool // will be set to true if config qualifies for implicit automatic/managed HTTPS
	OnDemand                 bool // will be set to true if user enables on-demand TLS (obtain certs during handshakes)
	Ciphers                  []uint16
	ProtocolMinVersion       uint16
	ProtocolMaxVersion       uint16
	PreferServerCipherSuites bool
	ClientCerts              []string
	ClientAuth               tls.ClientAuthType

TLSConfig describes how TLS should be configured and used.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL