nserv

README

nserv

nserv (nice server) Go package provides a variation of standard http.Server enhanced with graceful exit, throttling and zero downtime restarts. Throttling makes it easier to build a DOS-attack-resistant server and graceful exit feature makes it easy to write a stoppable server with proper clean-up (e.g., closing database connections). Zero downtime restarts feature enables you to perform updates to the server without interrupting active clients. Nserv has been inspired by the manners package.

The package is in its early stages of development (in the sense that hasn't been tested extensively yet). API of the v0 version might change without warning, v0 should be considered as an unstable/development version.

See gopkg.in on versioning scheme.

For up-to-date changelog and features list see README.

Features

• Full functionality of the standard http.Server.
• Limiting number of simultaneous connections. The limit can be dynamically changed while the server is running.
• Graceful exit.
• Zero downtime restarts (version v0). You can stop running server and hand off responsibility of serving new clients to a different program (e.g., an updated version of the server). All without interrupting active clients.

Usage

go get -u gopkg.in/kornel661/nserv.v0

or

import "gopkg.in/kornel661/nserv.v0"

Replace v0 by the version you need, see package import site and gopkg.in for import path convention.

Versions

• Bleeding-edge development version (github.com/kornel661/nserv)
• Development version (v0)
• Initial version with stable API (v1)

Goals

• This package is intended as a light extension of Go's standard http server implementation.
• Performance is important but not by overcomplicating the code.

Changelog

• 2014.11.16 (version v0): Initial implementation of zero downtime restarts.
• 2014.08.18 (version v1): Created version v1 - its API should be stable, though it isn't well-tested yet. Methods & fields can be added to the Server struct.
• 2014.08.16 (version v0): Testing & bug hunting season opened.

Documentation

Overview

Package nserv (nice server) provides a variation of the standard http.Server implementation enhanced with graceful exit, throttling and zero downtime restarts.

Throttling enables you to limit number of simultaneous connections the server accepts. This limit can be changed even after the server had been started.

Graceful exit means you can signal the server to stop and at that point the server stops accepting new connections. Active connections run their natural course and only after all connections are closed the server shuts down.

Zero downtime restarts allow the server to hand off responsibility of handling incoming connections to another program (e.g., updated version of the server) without interrupting the clients.

Usage:

import "gopkg.in/kornel661/nserv.v0"

or

go get gopkg.in/kornel661/nserv.v0

Replace v0 by the version you need (v0 is a development version, with no API stability guarantees).

For up-to-date changelog and features list see [README] (https://github.com/kornel661/nserv/blob/master/README.md).

Index

• Variables
• func CanResume() bool
• func InitializeZeroDowntime()
• type Server
  • func (srv *Server) CopyListenerFD() (fd *os.File, err error)
  • func (srv *Server) ListenAndServe() error
  • func (srv *Server) ListenAndServeTLS(certFile, keyFile string) error
  • func (srv *Server) MaxConns(n int) (free int)
  • func (srv *Server) OperateOnListener(fun func(limitnet.ThrottledListener) error) error
  • func (srv *Server) ResumeAndServe() error
  • func (srv *Server) Serve(listn net.Listener) error
  • func (srv *Server) Stop() bool
  • func (srv *Server) Wait()
  • func (srv *Server) ZeroDowntimeRestart(args ...string) error
• type TCPKeepAliveListener
  • func (ln *TCPKeepAliveListener) Accept() (c net.Conn, err error)

Examples

• Server

Variables

var (
	DefaultReadTimeout  = 60 * time.Second // default ReadTimeout set by the ListenAndServe methods
	DefaultWriteTimeout = 60 * time.Second // default WriteTimeout set by the ListenAndServe methods
	DefaultMaxConns     = 1000             // default MaxConns set by the ListenAndServe methods
)

Some default values set by the ListenAndServe method family. Feel free to modify these variables, e.g.,

nserv.DefaultMaxConns = 100
srv.ListenAndServe()

Or, alternatively (arguably a better solution if you're writing a 'serious' server), use srv.Listen directly or reimplement ListenAndServe.

Functions

func CanResume

func CanResume() bool

CanResume tells if it seems possible to resume serving.

func InitializeZeroDowntime

func InitializeZeroDowntime()

InitializeZeroDowntime sets up the command-line flags used by this package for supporting zero-downtime restarts. See also: limitnet.InitializeZeroDowntime(). You need to execute flag.Parse() after InitializeZeroDowntime() for it to work. See "gopkg.in/kornel661/limitnet.v0/ZeroDowntime-example" how to use this feature.

Types

type Server

type Server struct {
	http.Server         // standard net.Server functionality
	InitialMaxConns int // initial limit on simultaneous connections
	// contains filtered or unexported fields
}

Server with graceful exit and throttling.

Server is an extension of http.Server from the standard library (its API is a superset of that of http.Server).

Example

// initialize database, etc.
defer func() {
	// do clean-up (close DB connections, etc.)
}()
// set-up server:
srv := &nserv.Server{}
srv.Addr = "localhost:12345"
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintf(w, "Hello, %q", html.EscapeString(r.URL.Path))
})
// catch signals:
signals := make(chan os.Signal, 1)
signal.Notify(signals, os.Interrupt, os.Kill)
go func() {
	<-signals
	log.Println("Caught signal. Shutting down gracefully.")
	srv.Stop()
}()
// start serving:
log.Printf("Serving at http://%s\n", srv.Addr)
if err := srv.ListenAndServe(); err != nil {
	log.Println(err)
}

func (*Server) CopyListenerFD

func (srv *Server) CopyListenerFD() (fd *os.File, err error)

CopyListenerFD returns DUP of the file descriptor associated with the listener. If the server isn't running the behavior is as in Server.OperateOnListener.

func (*Server) ListenAndServe

func (srv *Server) ListenAndServe() error

ListenAndServe listens on the TCP network address srv.Addr and then calls Serve to handle requests on incoming connections. If srv.Addr is blank, ":http" is used.

If either of srv.ReadTimeout, srv.WriteTimeout or srv.MaxConns is 0, it's going to be set to a 'sane' default value, see the corresponding Default... variables.

func (*Server) ListenAndServeTLS

func (srv *Server) ListenAndServeTLS(certFile, keyFile string) error

ListenAndServeTLS listens on the TCP network address srv.Addr and then calls Serve to handle requests on incoming TLS connections.

Filenames containing a certificate and matching private key for the server must be provided. If the certificate is signed by a certificate authority, the certFile should be the concatenation of the server's certificate followed by the CA's certificate.

If srv.Addr is blank, ":https" is used.

If either of ReadTimeout, WriteTimeout or MaxConns is 0, it's going to be set to a 'sane' default value, see the corresponding Default... variable.

func (*Server) MaxConns

func (srv *Server) MaxConns(n int) (free int)

MaxConns sets new throttling limit (max number of simultaneous connections), returns number of free slots for incoming connections. For n < 0 doesn't change the limit. See limitnet.ThrottledListener for more detailed description.

Won't return until srv.Serve is called.

func (*Server) OperateOnListener

func (srv *Server) OperateOnListener(fun func(limitnet.ThrottledListener) error) error

OperateOnListener applies function fun to the server's listener. It ensures the server is running during execution of fun (returns an error if stopped or hangs if it hasn't been started).

func (*Server) ResumeAndServe

func (srv *Server) ResumeAndServe() error

ResumeAndServe tries to resume serving. Typically you execute InitializeZeroDowntime() and flag.Parse() first.

First, limitnet.RetrieveListeners() is called to retrieve a listener. Next, if either of srv.ReadTimeout, srv.WriteTimeout or srv.MaxConns is 0, it's going to be set to a 'sane' default value, see the corresponding Default... variables. Finally, srv.Serve method is invoked with the retrieved listener as its argument.

func (*Server) Serve

func (srv *Server) Serve(listn net.Listener) error

Serve accepts incoming connections on the Listener listn (wrapped with ThrottledListener from the gopkg.in/kornel661/limitnet.v0 package), creating a new service goroutine for each. The service goroutines read requests and then call srv.Handler to reply to them. Don't close listn. Rather use srv.Stop() method to exit gracefully. Serve returns on unrecoverable errors and when the server is explicitly stopped by srv.Stop(). By the time Serve returns the listener listn is closed.

func (*Server) Stop

func (srv *Server) Stop() bool

Stop gracefully stops a running server. Returns false if server had already been stopped before. Can return before the server is actually shut down.

Fragile if you tinker with the server's listener.

func (*Server) Wait

func (srv *Server) Wait()

Wait returns only when the server is closed and all connections terminated.

func (*Server) ZeroDowntimeRestart

func (srv *Server) ZeroDowntimeRestart(args ...string) error

ZeroDowntimeRestart shuts down the server and launches binary named the same as currently executing program with command line arguments args. The newly executed program inherits the file descriptor the srv server used.

Error behavior similar to Server.OperateOnListener or due to command execution error.

type TCPKeepAliveListener

type TCPKeepAliveListener struct {
	*net.TCPListener
}

TCPKeepAliveListener sets TCP keep-alive timeouts on accepted connections. It's used by ListenAndServe and ListenAndServeTLS so dead TCP connections (e.g. closing laptop mid-download) eventually go away.

func (*TCPKeepAliveListener) Accept

func (ln *TCPKeepAliveListener) Accept() (c net.Conn, err error)

Accept accepts the next incoming call and returns the new connection. KeepAlivePeriod is set properly.