Adds support for local FastCGI and logging

README.md

@@ -23,6 +23,47 @@ Manners ensures that all requests are served by incrementing a WaitGroup when a
 
 If your request handler spawns Goroutines that are not guaranteed to finish with the request, you can ensure they are also completed with the `StartRoutine` and `FinishRoutine` functions on the server.
 
+### HTTP, HTTPS and FCGI
+
+Manners supports three protocols: HTTP, HTTPS and FCGI. HTTP is illustrated above. 
+For HTTPS, Manners can likewise act as a drop-in replacement for the standard library's 
+[http.ListenAndServeTLS](http://golang.org/pkg/net/http/#ListenAndServeTLS) function:
+
+```go
+func main() {
+  handler  := MyHTTPHandler()
+  certFile := MyCertificate()
+  keyFile  := MyKeyFile()
+  manners.ListenAndServeTLS(":https", certFile, keyFile, handler)
+}
+```
+
+In Manners, FCGI only operates via local a Unix socket connected to a co-hosted proxy, such as Apache or Nginx. 
+
+```go
+func main() {
+  handler := MyHTTPHandler()
+  manners.ListenAndServe("/var/run/goserver.sock", handler)
+}
+```
+
+To use FCGI, the port string must specify the Unix socket and start with a slash or dot, as in the example above. In this case, Manners will use [fcgi.Serve](http://golang.org/pkg/net/http/fcgi/#Serve).
+
+In each of the protocols, Manners drains down the connections cleanly when `manners.Close()` is called.
+
+### Handling signals
+
+It's good to close down the server cleanly when OS signals are received. This is easy: just add
+
+```go
+manners.CloseOnInterrupt()
+```
+before the `ListenAndServe` call. This kicks off a separate goroutine to wait for an OS signal, upon which it simply calls `manners.Close()` for you. Optionally, you can pass in a list of the particular signals you care about and you can find out which signal was received, if any, afterwards.
+
+### Known Issues
+
+Manners does not correctly shut down long-lived keepalive connections when issued a shutdown command. Clients on an idle keepalive connection may see a connection reset error rather than a close. See https://github.com/braintree/manners/issues/13 for details.
+
 ### Compatability
 
 Manners 0.3.0 and above uses standard library functionality introduced in Go 1.3.

helpers_test.go

@@ -9,21 +9,21 @@ import (
 	"testing"
 )
 
-func newServer() *GracefulServer {
-	return NewWithServer(new(http.Server))
-}
-
 // a simple step-controllable http client
 type client struct {
 	tls         bool
 	addr        net.Addr
 	connected   chan error
 	sendrequest chan bool
-	idle        chan error
-	idlerelease chan bool
+	response    chan *rawResponse
 	closed      chan bool
 }
 
+type rawResponse struct {
+	body []string
+	err  error
+}
+
 func (c *client) Run() {
 	go func() {
 		var err error
@@ -39,19 +39,21 @@ func (c *client) Run() {
 		for <-c.sendrequest {
 			_, err = conn.Write([]byte("GET / HTTP/1.1\nHost: localhost:8000\n\n"))
 			if err != nil {
-				c.idle <- err
+				c.response <- &rawResponse{err: err}
 			}
 			// Read response; no content
 			scanner := bufio.NewScanner(conn)
+			var lines []string
 			for scanner.Scan() {
 				// our null handler doesn't send a body, so we know the request is
 				// done when we reach the blank line after the headers
-				if scanner.Text() == "" {
+				line := scanner.Text()
+				if line == "" {
 					break
 				}
+				lines = append(lines, line)
 			}
-			c.idle <- scanner.Err()
-			<-c.idlerelease
+			c.response <- &rawResponse{lines, scanner.Err()}
 		}
 		conn.Close()
 		ioutil.ReadAll(conn)
@@ -65,8 +67,7 @@ func newClient(addr net.Addr, tls bool) *client {
 		tls:         tls,
 		connected:   make(chan error),
 		sendrequest: make(chan bool),
-		idle:        make(chan error),
-		idlerelease: make(chan bool),
+		response:    make(chan *rawResponse),
 		closed:      make(chan bool),
 	}
 }
@@ -81,7 +82,7 @@ func startGenericServer(t *testing.T, server *GracefulServer, statechanged chan
 		// Wrap the ConnState handler with something that will notify
 		// the statechanged channel when a state change happens
 		server.ConnState = func(conn net.Conn, newState http.ConnState) {
-			statechanged <- newState
+			statechanged <- conn.LocalAddr().(*gracefulAddr).gconn.lastHTTPState
 		}
 	}
 

listener.go

@@ -0,0 +1,190 @@
+package manners
+
+import (
+	"crypto/tls"
+	"fmt"
+	"net"
+	"net/http"
+	"os"
+	"sync"
+	"time"
+)
+
+// NewListener wraps an existing listener for use with
+// GracefulServer.
+//
+// Note that you generally don't need to use this directly as
+// GracefulServer will automatically wrap any non-graceful listeners
+// supplied to it.
+func NewListener(l net.Listener) *GracefulListener {
+	return &GracefulListener{
+		listener: l,
+		mutex:    &sync.RWMutex{},
+		open:     true,
+	}
+}
+
+// A gracefulCon wraps a normal net.Conn and tracks the last known http state.
+type gracefulConn struct {
+	net.Conn
+	lastHTTPState http.ConnState
+	// protected tells whether the connection is going to defer server shutdown
+	// until the current HTTP request is completed.
+	protected bool
+}
+
+type gracefulAddr struct {
+	net.Addr
+	gconn *gracefulConn
+}
+
+func (g *gracefulConn) LocalAddr() net.Addr {
+	return &gracefulAddr{g.Conn.LocalAddr(), g}
+}
+
+// retrieveGracefulConn retrieves a concrete gracefulConn instance from an
+// interface value that can either refer to it directly or refer to a tls.Conn
+// instance wrapping around a gracefulConn one.
+func retrieveGracefulConn(conn net.Conn) *gracefulConn {
+	return conn.LocalAddr().(*gracefulAddr).gconn
+}
+
+// A GracefulListener differs from a standard net.Listener in one way: if
+// Accept() is called after it is gracefully closed, it returns a
+// listenerAlreadyClosed error. The GracefulServer will ignore this error.
+type GracefulListener struct {
+	listener net.Listener
+	open     bool
+	mutex    *sync.RWMutex
+}
+
+func (l *GracefulListener) isClosed() bool {
+	l.mutex.RLock()
+	defer l.mutex.RUnlock()
+	return !l.open
+}
+
+func (l *GracefulListener) Addr() net.Addr {
+	return l.listener.Addr()
+}
+
+// Accept implements the Accept method in the Listener interface.
+func (l *GracefulListener) Accept() (net.Conn, error) {
+	conn, err := l.listener.Accept()
+	if err != nil {
+		if l.isClosed() {
+			err = listenerAlreadyClosed{err}
+		}
+		return nil, err
+	}
+
+	// don't wrap connection if it's tls so we won't break
+	// http server internal logic that relies on the type
+	if _, ok := conn.(*tls.Conn); ok {
+		return conn, nil
+	}
+	return &gracefulConn{Conn: conn}, nil
+}
+
+// Close tells the wrapped listener to stop listening.  It is idempotent.
+func (l *GracefulListener) Close() error {
+	l.mutex.Lock()
+	defer l.mutex.Unlock()
+	if !l.open {
+		return nil
+	}
+	l.open = false
+	return l.listener.Close()
+}
+
+func (l *GracefulListener) GetFile() (*os.File, error) {
+	return getListenerFile(l.listener)
+}
+
+func (l *GracefulListener) Clone() (net.Listener, error) {
+	l.mutex.Lock()
+	defer l.mutex.Unlock()
+
+	if !l.open {
+		return nil, fmt.Errorf("listener is already closed")
+	}
+
+	file, err := l.GetFile()
+	if err != nil {
+		return nil, err
+	}
+	defer file.Close()
+
+	fl, err := net.FileListener(file)
+	if nil != err {
+		return nil, err
+	}
+	return fl, nil
+}
+
+// A listener implements a network listener (net.Listener) for TLS connections.
+// direct lift from crypto/tls.go
+type TLSListener struct {
+	net.Listener
+	config *tls.Config
+}
+
+// Accept waits for and returns the next incoming TLS connection.
+// The returned connection c is a *tls.Conn.
+func (l *TLSListener) Accept() (c net.Conn, err error) {
+	c, err = l.Listener.Accept()
+	if err != nil {
+		return
+	}
+	c = tls.Server(&gracefulConn{Conn: c}, l.config)
+	return
+}
+
+// NewListener creates a Listener which accepts connections from an inner
+// Listener and wraps each connection with Server.
+// The configuration config must be non-nil and must have
+// at least one certificate.
+func NewTLSListener(inner net.Listener, config *tls.Config) net.Listener {
+	l := new(TLSListener)
+	l.Listener = inner
+	l.config = config
+	return l
+}
+
+type listenerAlreadyClosed struct {
+	error
+}
+
+// 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.
+//
+// direct lift from net/http/server.go
+type TCPKeepAliveListener struct {
+	*net.TCPListener
+}
+
+func (ln TCPKeepAliveListener) Accept() (c net.Conn, err error) {
+	tc, err := ln.AcceptTCP()
+	if err != nil {
+		return
+	}
+	tc.SetKeepAlive(true)
+	tc.SetKeepAlivePeriod(3 * time.Minute)
+	return tc, nil
+}
+
+func getListenerFile(listener net.Listener) (*os.File, error) {
+	switch t := listener.(type) {
+	case *net.TCPListener:
+		return t.File()
+	case *net.UnixListener:
+		return t.File()
+	case TCPKeepAliveListener:
+		return t.TCPListener.File()
+	case *TLSListener:
+		return getListenerFile(t.Listener)
+	}
+	return nil, fmt.Errorf("Unsupported listener: %T", listener)
+}

logger.go

@@ -0,0 +1,17 @@
+package manners
+
+import (
+	"io/ioutil"
+	"log"
+)
+
+var logger = log.New(ioutil.Discard, "", 0)
+
+// SetLogger changes the logger used for the startup and shutdown messages
+// generated by Manners. By default, no log messages are emitted.
+// To make Manners logging behave the same as per the standard
+// log package, i.e. to stderr, use
+// `SetLogger(log.New(os.Stderr, "", log.LstdFlags))`
+func SetLogger(l *log.Logger) {
+	logger = l
+}