README
¶
graceful 
Graceful is a Go 1.3+ package enabling graceful shutdown of http.Handler servers.
Installation
To install, simply execute:
go get gopkg.in/tylerb/graceful.v1
I am using gopkg.in to control releases.
Usage
Using Graceful is easy. Simply create your http.Handler and pass it to the Run function:
package main
import (
"github.com/tylerb/graceful"
"net/http"
"fmt"
"time"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
fmt.Fprintf(w, "Welcome to the home page!")
})
graceful.Run(":3001",10*time.Second,mux)
}
Another example, using Negroni, functions in much the same manner:
package main
import (
"github.com/codegangsta/negroni"
"github.com/tylerb/graceful"
"net/http"
"fmt"
"time"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
fmt.Fprintf(w, "Welcome to the home page!")
})
n := negroni.Classic()
n.UseHandler(mux)
//n.Run(":3000")
graceful.Run(":3001",10*time.Second,n)
}
In addition to Run there are the http.Server counterparts ListenAndServe, ListenAndServeTLS and Serve, which allow you to configure HTTPS, custom timeouts and error handling. Graceful may also be used by instantiating its Server type directly, which embeds an http.Server:
mux := // ...
srv := &graceful.Server{
Timeout: 10 * time.Second,
Server: &http.Server{
Addr: ":1234",
Handler: mux,
},
}
srv.ListenAndServe()
This form allows you to set the ConnState callback, which works in the same way as in http.Server:
mux := // ...
srv := &graceful.Server{
Timeout: 10 * time.Second,
ConnState: func(conn net.Conn, state http.ConnState) {
// conn has a new state
},
Server: &http.Server{
Addr: ":1234",
Handler: mux,
},
}
srv.ListenAndServe()
Behaviour
When Graceful is sent a SIGINT or SIGTERM (possibly from ^C or a kill command), it:
- Disables keepalive connections.
- Closes the listening socket, allowing another process to listen on that port immediately.
- Starts a timer of
timeoutduration to give active requests a chance to finish. - When timeout expires, closes all active connections.
- Closes the
stopChan, waking up any blocking goroutines. - Returns from the function, allowing the server to terminate.
Notes
If the timeout argument to Run is 0, the server never times out, allowing all active requests to complete.
If you wish to stop the server in some way other than an OS signal, you may call the Stop() function.
This function stops the server, gracefully, using the new timeout value you provide. The StopChan() function
returns a channel on which you can block while waiting for the server to stop. This channel will be closed when
the server is stopped, allowing your execution to proceed. Multiple goroutines can block on this channel at the
same time and all will be signalled when stopping is complete.
Contributing
If you would like to contribute, please:
- Create a GitHub issue regarding the contribution. Features and bugs should be discussed beforehand.
- Fork the repository.
- Create a pull request with your solution. This pull request should reference and close the issues (Fix #2).
All pull requests should:
- Pass gometalinter -t . with no warnings.
- Be
go fmtformatted.
Documentation
¶
Index ¶
- func ListenAndServe(server *http.Server, timeout time.Duration) error
- func ListenAndServeTLS(server *http.Server, certFile, keyFile string, timeout time.Duration) error
- func Run(addr string, timeout time.Duration, n http.Handler)
- func Serve(server *http.Server, l net.Listener, timeout time.Duration) error
- type Server
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ListenAndServe ¶
ListenAndServe is equivalent to http.Server.ListenAndServe with graceful shutdown enabled.
timeout is the duration to wait until killing active requests and stopping the server. If timeout is 0, the server never times out. It waits for all active requests to finish.
func ListenAndServeTLS ¶
ListenAndServeTLS is equivalent to http.Server.ListenAndServeTLS with graceful shutdown enabled.
timeout is the duration to wait until killing active requests and stopping the server. If timeout is 0, the server never times out. It waits for all active requests to finish.
func Run ¶
Run serves the http.Handler with graceful shutdown enabled.
timeout is the duration to wait until killing active requests and stopping the server. If timeout is 0, the server never times out. It waits for all active requests to finish.
Types ¶
type Server ¶
type Server struct {
*http.Server
// Timeout is the duration to allow outstanding requests to survive
// before forcefully terminating them.
Timeout time.Duration
// Limit the number of outstanding requests
ListenLimit int
// ConnState specifies an optional callback function that is
// called when a client connection changes state. This is a proxy
// to the underlying http.Server's ConnState, and the original
// must not be set directly.
ConnState func(net.Conn, http.ConnState)
// ShutdownInitiated is an optional callback function that is called
// when shutdown is initiated. It can be used to notify the client
// side of long lived connections (e.g. websockets) to reconnect.
ShutdownInitiated func()
// NoSignalHandling prevents graceful from automatically shutting down
// on SIGINT and SIGTERM. If set to true, you must shut down the server
// manually with Stop().
NoSignalHandling bool
// contains filtered or unexported fields
}
Server wraps an http.Server with graceful connection handling. It may be used directly in the same way as http.Server, or may be constructed with the global functions in this package.
Example:
srv := &graceful.Server{
Timeout: 5 * time.Second,
Server: &http.Server{Addr: ":1234", Handler: handler},
}
srv.ListenAndServe()
func (*Server) ListenAndServe ¶
ListenAndServe is equivalent to http.Server.ListenAndServe with graceful shutdown enabled.
func (*Server) ListenAndServeTLS ¶
ListenAndServeTLS is equivalent to http.Server.ListenAndServeTLS with graceful shutdown enabled.
func (*Server) Stop ¶
Stop instructs the type to halt operations and close the stop channel when it is finished.
timeout is grace period for which to wait before shutting down the server. The timeout value passed here will override the timeout given when constructing the server, as this is an explicit command to stop the server.
Source Files
Directories