sslmgr

README

Simple Secure Server

Prerequisites:

• Your server must be reachable through the provided domain name, this is how LetsEncrypt verifies domain ownership and grants your server a trusted certificate

With Default Values:

ss, err := sslmgr.NewSecureServer(handler, "yourhostname.com")
if err != nil {
	log.Fatal(err)
}
ss.ListenAndServe()

Note: This option uses the file system as the certificate cache. If your use case does not have a persistent file system, you should provide a value for CertCache in the ServerConfig as shown below.

With Optional Values:

(Using the certcache library to define a cache)

ss, err := sslmgr.NewServer(sslmgr.ServerConfig{
	Hostnames: []string{os.Getenv("CN_FOR_CERTIFICATE")},
	HTTPPort:  ":80",
	HTTPSPort: ":443",
	Handler:   h,
	ServeSSLFunc: func() bool {
		return strings.ToLower(os.Getenv("PROD")) == "true"
	},
	CertCache: certcache.NewLayered(
		certcache.NewLogger(),
		autocert.DirCache("."),
	),
	ReadTimeout:         5 * time.Second,
	WriteTimeout:        5 * time.Second,
	IdleTimeout:         25 * time.Second,
	GracefulnessTimeout: 5 * time.Second,
	GracefulShutdownErrHandler: func(e error) {
		log.Fatal(e)
	},
})
if err != nil {
	log.Fatal(err)
}

ss.ListenAndServe()

Documentation

Index

• Variables
• type SecureServer
  • func NewSecureServer(h http.Handler, hostnames ...string) (*SecureServer, error)
  • func NewServer(c ServerConfig) (*SecureServer, error)
  • func (ss *SecureServer) ListenAndServe()
• type ServerConfig

Variables

var (
	// ErrNoHostname is returned whenever a user calls NewSecureServer
	// without any hostnames in the config
	ErrNoHostname = errors.New("no hostnames provided")

	// ErrNoHandler is returned whenever a user calls NewSecureServer
	// with a nil http.Handler in the config
	ErrNoHandler = errors.New("server handler cannot be nil")

	// ErrNotAnInteger is returned whenever a user calls NewSecureServer with
	// port definitions which do not correspont to integers. i.e. "not a number"
	ErrNotAnInteger = errors.New("port number must be a numerical string")
)

Types

type SecureServer

type SecureServer struct {
	// contains filtered or unexported fields
}

SecureServer is a server which abstracts away acme/autocert's certificate manager and server configuration

func NewSecureServer

func NewSecureServer(h http.Handler, hostnames ...string) (*SecureServer, error)

NewSecureServer returns a SecureServer with default configuration

func NewServer

func NewServer(c ServerConfig) (*SecureServer, error)

NewServer returns a SecureServer with the given config applied

func (*SecureServer) ListenAndServe

func (ss *SecureServer) ListenAndServe()

ListenAndServe starts the secure server

type ServerConfig

type ServerConfig struct {
	// Hostnames for which the server is allowed to serve HTTPS.
	// If the server receives an https request through a DNS name or IP
	// not contained in this list, the request will be denied
	// (REQUIRED)
	Hostnames []string

	// The server's http handler
	// (REQUIRED)
	Handler http.Handler

	// ServeSSLFunc is called to determine whether to serve HTTPS
	// or not. This function's enables users to purpusely disable
	// HTTPS i.e. for local development.
	// Default behavior is to serve HTTPS
	ServeSSLFunc func() bool

	// An implementation of the autocert.Cache interface, which autocert
	// will use to store and manage certificates. It is strongly recommended
	// to provide this field.
	// Default behavior is to store at "." in the file system
	CertCache autocert.Cache

	// Default value is ":443"
	HTTPSPort string

	// Default value is ":80"
	HTTPPort string

	// Default value is 5 seconds
	ReadTimeout time.Duration

	// Default value is 5 seconds
	WriteTimeout time.Duration

	// Default value is 25 seconds
	IdleTimeout time.Duration

	// Default value is 5 seconds
	GracefulnessTimeout time.Duration

	// GracefulShutdownErrHandler is called to handle the event of an error during
	// a graceful shutdown (accept no more connections, and wait for existing
	// ones to finish within the GracefulnessTimeout)
	// Default value is a NOP
	GracefulShutdownErrHandler func(error)
}

ServerConfig holds configuration to initialize a SecureServer. Requied Fields: Hostnames and Handler Note that it is strongly recommended not to use the default CertCache