goVirtualHost

README

goVirtualHost

goVirtualHost: An easy way to setup HTTP virtual hosts.

Minimal required Go version is 1.14.

Quick Example

Two virtual hosts listen on both :8080, but with different hostname, serve for different directories:

svc := goVirtualHost.NewService()

// virtual host: localhost
svc.Add(&goVirtualHost.HostInfo{
    Listens:   []string{":8080"},
    HostNames: []string{"localhost"},
    Handler:   http.FileServer(http.Dir(".")),
})

// virtual host: default host
svc.Add(&goVirtualHost.HostInfo{
    Listens: []string{":8080"},
    Handler: http.FileServer(http.Dir("/tmp")),
})

// start server
svc.Open()

NewService() *Service

NewService returns a service instance that manages multiple virtual hosts.

(*Service) Add(*HostInfo) (errs, warns []error)

Adding a new virtual host information to the Service. You can use errors.Is() to test possible errors:

• error CertificateNotFound

Intent to work on TLS mode, but certificate is not provided.

• error ConflictIPAddress

One Virtual host tries to listen on a specific IP:port, while another virtual host tries to listen on a wildcard IP of port(e.g. ":port"). Or one virtual host tries to listen on a specific version of wildcard IP of port(e.g. "0.0.0.0:port" or "[::]:port"), while another virtual host tries to listen on a wildcard IP of port(e.g. ":port").

• error ConflictTLSMode

For a specific listening endpoint(IP:port or socket), one virtual host works on plain mode, while another virtual host works on TLS mode.

• warning DuplicatedAddressHostname

Two virtual hosts listen on same endpoint, they use the same hostname.

HostInfo

the HostInfo is the initial virtual host information, with the properties:

Listens []string

IP and/or port the server listens on, e.g. ":80" or "127.0.0.1:80". if CertKeyPaths or Certs available, Serve for TLS HTTP, otherwise Serve for plain HTTP. If port is not specified, use "80" as default for Plain HTTP mode, "443" for TLS mode. If value contains "/" then treat it as a unix socket file.

ListensPlain []string

IP and/or port the server listens on, e.g. ":80" or "127.0.0.1:80". Serve for plain HTTP. If port is not specified, use "80" as default. If value contains "/" then treat it as a unix socket file.

ListensTLS []string

IP and/or port the server listens on, e.g. ":443" or "127.0.0.1:443". Serve for TLS HTTP. If port is not specified, use "443" as default. If value contains "/" then treat it as a unix socket file.

CertKeyPaths [][2]string

List of TLS certificate file path with each element [2]string{certPath, keyPath}.

Certs []tls.Certificate

TLS certificates supplied for TLS mode. Several helper functions can be used to load from external PEM files:

// load certificate from cert file and key file
func LoadCertificate(certFile, keyFile string) (cert *tls.Certificate, err error)

// load certificates from cert file list and key file list
func LoadCertificates(certFiles, keyFiles []string) (certs []*tls.Certificate, errs []error)

// load certificates from a list, each element is an array that contains certificate file and key file
func LoadCertificatesFromPairs(certKeyFilePairs [][2]string) (certs []*tls.Certificate, errs []error) {

HostNames []string

Specify hostnames associated with the virtual host. If hostname starts with ".", treat it as a suffix, to match all levels of sub domains, e.g. ".example.com". If hostname ends with ".", treat it as a prefix, to match all levels of suffix domains, e.g. "192.168.1.". If request host name does not match any virtual host, server will try to use first virtual host that has no hostname, otherwise use the first virtual host.

Handler http.Handler

http.Handler to handle requests. Could be an instance of http.ServeMux, httputil.ReverseProxy, or any other type that implements http.Handler.

(*Service) GetAccessibleURLs(includeLoopback bool) [][]string

Get possible access URLs. For the returned type [][]string, the first dimension is virtual host index, the second dimension is the index of URL in that virtual host.

(*Service) Open() []error

Start listening on network ports, and serve for http requests. The method will not return until all servers are closed. e.g. call Close method on another goroutine.

(*Service) ReloadCertificates() []error

Reload TLS certificates from CertKeyPaths.

(*Service) Close()

Stop serving. To restart serving, a new Service must be created.

(*Service) Shutdown()

Similar to *Service.Close(), but close server gracefully. It invokes http.Server's Shutdown() method internally.

Architecture & Internals

Service
    |  manages
    v
    +---------+---------+---------+---------+
    | handler | handler | handler | handler |
    +---------+---------+---------+---------+
    |  vhost  |  vhost  |  vhost  |  vhost  |
    +---------+--+------+-----+---+---------+
    | serveable  | serveable  |  serveable  |
    +------------+------------+-------------+
    | listenable | listenable | listenable  |
    +------------+------------+-------------+

listenable

listenable is a wrapper for net.Listener, which open ports or sockets and listen.

serveable

serveable is a wrapper for http.Server. It's handler does not serve for end user, but dispatching requests to related virtual host according to the Host header.

vhost

vhost manages related hostnames, and hold handler to deal with requests dispatched from server.

Documentation

Index

• Variables
• func CertsKeysToPairs(certFiles, keyFiles []string) (certKeyFilePairs [][2]string, errs []error)
• func LoadCertificate(certFile, keyFile string) (cert *tls.Certificate, err error)
• func LoadCertificates(certFiles, keyFiles []string) (certs []*tls.Certificate, errs []error)
• func LoadCertificatesFromPairs(certKeyFilePairs [][2]string) (certs []*tls.Certificate, errs []error)
• type HostInfo
• type Service
  • func NewService() *Service
  • func (svc *Service) Add(info *HostInfo) (errs, warns []error)
  • func (svc *Service) Close()
  • func (svc *Service) GetAccessibleURLs(includeLoopback bool) [][]string
  • func (svc *Service) Open() (errs []error)
  • func (svc *Service) ReloadCertificates() (errs []error)
  • func (svc *Service) Shutdown(ctx context.Context)

Variables

var CertKeyFileCountNotMatch = errors.New("certificate file count and key file count not match")

var CertificateNotFound = errors.New("certificate not found for TLS listens")

var ConflictIPAddress = errors.New("conflict IP address")

var ConflictTLSMode = errors.New("cannot serve for both Plain and TLS mode")

var DuplicatedAddressHostname = errors.New("duplicated address and hostname")

var MissingCertFile = errors.New("missing certificate file")

var MissingCertFileAndKeyFile = errors.New("missing certificate file and key file")

var MissingKeyFile = errors.New("missing key file")

Functions

func CertsKeysToPairs

func CertsKeysToPairs(certFiles, keyFiles []string) (certKeyFilePairs [][2]string, errs []error)

func LoadCertificate

func LoadCertificate(certFile, keyFile string) (cert *tls.Certificate, err error)

func LoadCertificates

func LoadCertificates(certFiles, keyFiles []string) (certs []*tls.Certificate, errs []error)

func LoadCertificatesFromPairs

func LoadCertificatesFromPairs(certKeyFilePairs [][2]string) (certs []*tls.Certificate, errs []error)

Types

type HostInfo

type HostInfo struct {
	Listens      []string
	ListensPlain []string
	ListensTLS   []string
	CertKeyPaths [][2]string // []{ {certFile, keyFile}, ... }
	Certs        []*tls.Certificate
	HostNames    []string
	Handler      http.Handler
}

init host info

type Service

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

func NewService

func NewService() *Service

func (*Service) Add

func (svc *Service) Add(info *HostInfo) (errs, warns []error)

func (*Service) Close

func (svc *Service) Close()

func (*Service) GetAccessibleURLs

func (svc *Service) GetAccessibleURLs(includeLoopback bool) [][]string

func (*Service) Open

func (svc *Service) Open() (errs []error)

func (*Service) ReloadCertificates

func (svc *Service) ReloadCertificates() (errs []error)

func (*Service) Shutdown

func (svc *Service) Shutdown(ctx context.Context)