README

Simple Secure Server

Go Report Card Documentation GitHub issues license Mentioned in Awesome Go

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

Constants

This section is empty.

Variables

View Source
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")
)

Functions

This section is empty.

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

            Source Files

            Directories

            Path Synopsis