server

README

go-server

This should probably be considered depreciated in favor of go-webserver.

An easy to use HTTP/HTTPS server written in Go. It uses the standard library, and provides some benefits over using the standard library directly:

• Can gracefully shut down active connections.
• Can detach and reattach listeners, which allows for low (zero?) downtime restarts.

Usage is simple:

import (
	"github.com/timewasted/go-server"
	...
)

// Create a few listeners.
httpServer := server.New()
if err := httpServer.Listen("127.0.0.1:80"); err != nil {
	log.Fatal("Listen error:", err)
}
if err := httpServer.Listen("127.0.0.1:8080"); err != nil {
	log.Fatal("Listen error:", err)
}
// Start serving connections.
httpServer.Serve()
// Shutdown the server.
httpServer.Shutdown()

// Create a few listeners.
httpsServer := server.New()
if err := httpsServer.Listen("127.0.0.1:443"); err != nil {
	log.Fatal("Listen error:", err)
}
if err := httpsServer.Listen("127.0.0.1:44380"); err != nil {
	log.Fatal("Listen error:", err)
}
// Enable TLS
if err := httpsServer.AddTLSCertificateFromFile("/path/to/server.cert", "/path/to/server.key"); err != nil {
	log.Fatal("TLS error:", err)
}
// Start serving connections.
httpsServer.Serve()
// Shutdown the server.
httpsServer.Shutdown()

Current limitations:

• It is only possible to enable TLS on listeners that are detached or not currently serving connections.
• Once TLS has been enabled, it is only possible to disable it by detaching and reattaching listeners.

License:

Copyright (c) 2013, Ryan Rogers
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met: 

1. Redistributions of source code must retain the above copyright notice, this
   list of conditions and the following disclaimer. 
2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution. 

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Documentation

Overview

Package server provides an easy to use HTTP/HTTPS server. It provides some benefits over using the standard library directly, such as the ability to gracefully shut down active connections, and to do low (zero?) downtime restarts.

Index

• Constants
• type DetachedListeners
• type Server
  • func New() *Server
  • func (s *Server) AddTLSCertificate(certPEMBlock, keyPEMBlock []byte) error
  • func (s *Server) AddTLSCertificateFromFile(certFile, keyFile string) error
  • func (s *Server) Detach() DetachedListeners
  • func (s *Server) ForceShutdown()
  • func (s *Server) Listen(addr string) error
  • func (s *Server) ReuseListeners(listeners DetachedListeners)
  • func (s *Server) Serve()
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (s *Server) Shutdown()

Constants

const (
	TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA       uint16 = 0x0016
	TLS_DHE_RSA_WITH_AES_128_CBC_SHA        uint16 = 0x0033
	TLS_DHE_RSA_WITH_AES_256_CBC_SHA        uint16 = 0x0039
	TLS_RSA_WITH_AES_128_CBC_SHA256         uint16 = 0x003c
	TLS_RSA_WITH_AES_256_CBC_SHA256         uint16 = 0x003d
	TLS_DHE_RSA_WITH_AES_128_CBC_SHA256     uint16 = 0x0067
	TLS_DHE_RSA_WITH_AES_256_CBC_SHA256     uint16 = 0x006b
	TLS_RSA_WITH_AES_128_GCM_SHA256         uint16 = 0x009c
	TLS_RSA_WITH_AES_256_GCM_SHA384         uint16 = 0x009d
	TLS_DHE_RSA_WITH_AES_128_GCM_SHA256     uint16 = 0x009e
	TLS_DHE_RSA_WITH_AES_256_GCM_SHA384     uint16 = 0x009f
	TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA   uint16 = 0xc008
	TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 uint16 = 0xc023
	TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 uint16 = 0xc024
	TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256   uint16 = 0xc027
	TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384   uint16 = 0xc028
	TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 uint16 = 0xc02c
	TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384   uint16 = 0xc030
)

A list of strong cipher suite IDs that are not defined by the crypto/tls package in the current stable version of Go. Values taken from http://www.iana.org/assignments/tls-parameters/tls-parameters.xml

Note that the reason they are not defined by the crypto/tls package is because they are not (yet?) supported by Go. Defining them here allows us to immediately start using them, should Go support them in the future.

Types

type DetachedListeners

type DetachedListeners map[string]uintptr

DetachedListeners is an address to file descriptor mapping of listeners that have been detached.

type Server

type Server struct {
	*http.ServeMux
	TLS *tls.Config
	// contains filtered or unexported fields
}

Server is a simple HTTP/HTTPS server.

func New

func New() *Server

New creates a new Server.

func (*Server) AddTLSCertificate

func (s *Server) AddTLSCertificate(certPEMBlock, keyPEMBlock []byte) error

AddTLSCertificate reads the certificate and private key from the provided PEM blocks, and adds the certificate to the list of certificates that the server can use.

func (*Server) AddTLSCertificateFromFile

func (s *Server) AddTLSCertificateFromFile(certFile, keyFile string) error

AddTLSCertificateFromFile reads the certificate and private key from the provided file paths, and adds the certificate to the list of certificates that the server can use.

func (*Server) Detach

func (s *Server) Detach() DetachedListeners

Detach returns an address to file descriptor mapping for all listeners.

func (*Server) ForceShutdown

func (s *Server) ForceShutdown()

ForceShutdown forcefully closes all currently active connections. Little care is shown in making sure things are cleaned up, so this should generally only be used as a last resort.

func (*Server) Listen

func (s *Server) Listen(addr string) error

Listen will begin listening on the given address, either by reusing an existing listener, or by creating a new one.

func (*Server) ReuseListeners

func (s *Server) ReuseListeners(listeners DetachedListeners)

ReuseListeners provides an address to file descriptor mapping of listeners that the server can reuse instead of creating a new listener.

func (*Server) Serve

func (s *Server) Serve()

Serve begins serving connections.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements the ServeHTTP() method of the http.Handler interface.

func (*Server) Shutdown

func (s *Server) Shutdown()

Shutdown gracefully shuts down the server, allowing any currently active connections to finish before doing so.