README

httpdown Build Status

Documentation: https://godoc.org/github.com/facebookgo/httpdown

Package httpdown provides a library that makes it easy to build a HTTP server that can be shutdown gracefully (that is, without dropping any connections).

If you want graceful restart and not just graceful shutdown, look at the grace package which uses this package underneath but also provides graceful restart.

Usage

Demo HTTP Server with graceful termination: https://github.com/facebookgo/httpdown/blob/master/httpdown_example/main.go

  1. Install the demo application

     go get github.com/facebookgo/httpdown/httpdown_example
    
  2. Start it in the first terminal

     httpdown_example
    

    This will output something like:

     2014/11/18 21:57:50 serving on http://127.0.0.1:8080/ with pid 17
    
  3. In a second terminal start a slow HTTP request

     curl 'http://localhost:8080/?duration=20s'
    
  4. In a third terminal trigger a graceful shutdown (using the pid from your output):

     kill -TERM 17
    

This will demonstrate that the slow request was served before the server was shutdown. You could also have used Ctrl-C instead of kill as the example application triggers graceful shutdown on TERM or INT signals.

Documentation

Overview

    Package httpdown provides http.ConnState enabled graceful termination of http.Server.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func ListenAndServe

    func ListenAndServe(s *http.Server, hd *HTTP) error

      ListenAndServe is a convenience function to serve and wait for a SIGTERM or SIGINT before shutting down.

      Types

      type HTTP

      type HTTP struct {
      	// StopTimeout is the duration before we begin force closing connections.
      	// Defaults to 1 minute.
      	StopTimeout time.Duration
      
      	// KillTimeout is the duration before which we completely give up and abort
      	// even though we still have connected clients. This is useful when a large
      	// number of client connections exist and closing them can take a long time.
      	// Note, this is in addition to the StopTimeout. Defaults to 1 minute.
      	KillTimeout time.Duration
      
      	// Stats is optional. If provided, it will be used to record various metrics.
      	Stats stats.Client
      
      	// Clock allows for testing timing related functionality. Do not specify this
      	// in production code.
      	Clock clock.Clock
      }

        HTTP defines the configuration for serving a http.Server. Multiple calls to Serve or ListenAndServe can be made on the same HTTP instance. The default timeouts of 1 minute each result in a maximum of 2 minutes before a Stop() returns.

        func (HTTP) ListenAndServe

        func (h HTTP) ListenAndServe(s *http.Server) (Server, error)

          ListenAndServe returns a Server for the given http.Server. It is equivalent to ListenAndServe from the standard library, but returns immediately. Requests will be accepted in a background goroutine. If the http.Server has a non-nil TLSConfig, a TLS enabled listener will be setup.

          func (HTTP) Serve

          func (h HTTP) Serve(s *http.Server, l net.Listener) Server

            Serve provides the low-level API which is useful if you're creating your own net.Listener.

            type Server

            type Server interface {
            	// Wait waits for the serving loop to finish. This will happen when Stop is
            	// called, at which point it returns no error, or if there is an error in the
            	// serving loop. You must call Wait after calling Serve or ListenAndServe.
            	Wait() error
            
            	// Stop stops the listener. It will block until all connections have been
            	// closed.
            	Stop() error
            }

              A Server allows encapsulates the process of accepting new connections and serving them, and gracefully shutting down the listener without dropping active connections.

              Source Files

              Directories

              Path Synopsis