servers

README

Examples

HTTPS listener using Let's Encrypt, with HTTP->HTTPS redirector & http challenge on :80 for Let's Encrypt

This is useful for Cloudflare, Nginx, and other servers in front, because they do not respond to ALPN challenges.

cfg, killChan, err := servers.Start(servers.New(router, logger, servers.WithLetsEncrypt(true, "domain.com")))
if err != nil {
...
}

err = servers.Start(cfg)

HTTPS listener using Let's Encrypt, with HTTP->HTTPS redirector & alpn challenge on :443 for Let's Encrypt

cfg, killChan, err := servers.Start(servers.New(router, logger, servers.WithHTTP(":80"), servers.WithLetsEncrypt(false, "domain.com")))
if err != nil { ... }
err = servers.Start(cfg)

HTTPS listener using Let's Encrypt, with no redirector & alpn challenge on :443 for Let's Encrypt

cfg, killChan, err := servers.New(router, logger, servers.WithLetsEncrypt(false, "domain.com")))
if err != nil { ... }
err = servers.Start(cfg)

Documentation

Index

• func NewBasicAutocertManager(domains ...string) *autocert.Manager
• type Builder
  • func WithHTTP(bind string) Builder
  • func WithHTTPS(bind string, key string, cert string) Builder
  • func WithLetsEncrypt(httpChallenge bool, domains ...string) Builder
  • func WithLetsEncryptManager(manager *autocert.Manager, cfg *tls.Config, httpChallenge bool) Builder
  • func WithTLS(bind string, key string, cert string, config *tls.Config) Builder
  • func WithTimeouts(read, readHeader, write, idle time.Duration) Builder
• type Config
  • func New(router http.Handler, logger zerolog.Logger, builders ...Builder) (*Config, error)
  • func (cfg *Config) Start() error
  • func (cfg *Config) Stop()

Functions

func NewBasicAutocertManager

func NewBasicAutocertManager(domains ...string) *autocert.Manager

NewBasicAutocertManager creates a autocert manager with sane default values.

Types

type Builder

type Builder func(*Config) error

Builder is a configuration builder function.

func WithHTTP

func WithHTTP(bind string) Builder

WithHTTP allows you to create a server listener for HTTP connections. If New is also called with WithHTTPS or WithLetsEncrypt/WithLetsEncryptManager then this listener will function as a redirect listener and redirect traffic to HTTPS.

If used with WithLetsEncrypt/WithLetsEncryptManager you must bind to :80 - as other ports are not supported.

func WithHTTPS

func WithHTTPS(bind string, key string, cert string) Builder

WithHTTPS allows you to create a server listener for HTTPS connections. If you want a custom TLS config, use WithTLS. Otherwise, WithHTTPS will use a sane default tls config.

func WithLetsEncrypt

func WithLetsEncrypt(httpChallenge bool, domains ...string) Builder

WithLetsEncrypt allows you to tell the server to use Let's Encrypt with auto-renewal for https certs. This version uses defaults for the autocert Manager & tls config. If you want more control, use WithLetsEncrypt. Bind is not configurable for let's encrypt and will always bind to :443.

If httpChallenge is true, we will create a http -> https redirector that responds to let's encrypt HTTP challenges. This is required for Nginx, CloudFlare, and others because they do not support ALPN challenges. If you want to create a redirector that does not respond to HTTP challenges, and wish to use ALPN instead, you can use WithLetsEncrypt in conjunction with WithHTTP. Otherwise, you don't need to use WithHTTP.

func WithLetsEncryptManager

func WithLetsEncryptManager(manager *autocert.Manager, cfg *tls.Config, httpChallenge bool) Builder

WithLetsEncryptManager allows you to tell the server to use Let's Encrypt with auto-renewal for https certs. If you'd like to use a default autocert Manager you can get one from NewBasicAutocertManager to provide here. If tls config is nil we will use a default tls config. If not-nil, the GetCertificate and NextProtos values will be replaced by values from the autocert manager's default TLS config, obtained via manager.TLSConfig(). Bind is not configurable for let's encrypt and will always bind to :443.

If httpChallenge is true, we will create a http -> https redirector that responds to let's encrypt HTTP challenges. This is required for Nginx, CloudFlare, and others because they do not support ALPN challenges. If you want to create a redirector that does not respond to HTTP challenges, and wish to use ALPN instead, you can use WithLetsEncryptManager in conjunction with WithHTTP. Otherwise, you don't need to use WithHTTP.

func WithTLS

func WithTLS(bind string, key string, cert string, config *tls.Config) Builder

WithTLS allows you to create a server listener for HTTPS connections with a custom TLS config. If you want a simple HTTPS listener using a sane default TLS config, use WithHTTPS.

func WithTimeouts

func WithTimeouts(read, readHeader, write, idle time.Duration) Builder

WithTimeouts allows you to specify your own listener timeout values. Timeout docs can be found here: https://golang.org/pkg/net/http/

type Config

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

func New

func New(router http.Handler, logger zerolog.Logger, builders ...Builder) (*Config, error)

New returns a new config to be supplied to Start to start the server. Writing to the returned kill chan will gracefully shutdown the server. Returns an error and a nil config if there are conflicting configuration entries.

The most basic way to get started is: New(router, logger, servers.WithLetsEncrypt(true, "domain.com")) This creates a lets encrypt listener on :443, with a redirector on :80 that responds to let's encrypt http challenges.

If WithHTTP is used alongside WithHTTPS/LetsEncrypt/TLS then the bind port (usually :80) will act as a redirector to the SSL port. You can also specify custom timeouts using WithTimeouts.

func (*Config) Start

func (cfg *Config) Start() error

Start a server with proper shutdown mechanics (os.Interrupt/Kill handlers). Use the New function with the "With" functions for setting up the Config to give to Start.

func (*Config) Stop

func (cfg *Config) Stop()

Stop uses the killChan to gracefully shutdown any active listeners.