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
Examples ¶
Constants ¶
This section is empty.
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 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) }
Output:
func (*Server) CopyListenerFD ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
Directories ¶
Path | Synopsis |
---|---|
This program illustrates how to write a simple server with zero-downtime restarts using the nserv package.
|
This program illustrates how to write a simple server with zero-downtime restarts using the nserv package. |