graceful

README

graceful

Graceful is a Go package enabling graceful shutdown of http.Handler servers.

If you would like to discuss Graceful, or any of our other open source projects, please join our HipChat Open Source Channel

Usage

Usage of Graceful is simple. Create your http.Handler and pass it to the Run function:

import (
  "github.com/stretchr/graceful"
  "net/http"
  "fmt"
)

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/stretchr/graceful"
  "net/http"
  "fmt"
)

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, these allow to configure https, custom timeouts and error handling.

When Graceful is sent a SIGINT (ctrl+c), it:

1. Disables keepalive connections.
2. Closes the listening socket, allowing another process to listen on that port immediately.
3. Starts a timer of timeout duration to give active requests a chance to finish.
4. When timeout expires, closes all active connections.
5. 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.

Graceful relies on functionality in Go 1.3 which has not yet been released. If you wish to use it, you must install the beta of Go 1.3. Once 1.3 is released, this note will be removed.

Documentation

Index

• func ListenAndServe(srv *http.Server, timeout time.Duration) error
• func ListenAndServeTLS(srv *http.Server, certFile, keyFile string, timeout time.Duration) error
• func Run(addr string, timeout time.Duration, n http.Handler)
• func Serve(srv *http.Server, l net.Listener, timeout time.Duration) error

Functions

func ListenAndServe

func ListenAndServe(srv *http.Server, timeout time.Duration) error

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

func ListenAndServeTLS(srv *http.Server, certFile, keyFile string, timeout time.Duration) error

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

func Run(addr string, timeout time.Duration, n http.Handler)

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.

func Serve

func Serve(srv *http.Server, l net.Listener, timeout time.Duration) error

Serve is equivalent to http.Server.Serve 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.