goVirtualHost: An easy way to setup HTTP virtual hosts.

Minimal required Go version is 1.14.

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 returns a service instance that manages multiple virtual hosts.

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.

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

IP and/or port the server listens on, e.g. ":80" or "127.0.0.1:80". if 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.

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.

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.

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 LoadCertificatesFromEntries(certKeyEntries [][2]string) (certs []tls.Certificate, errs []error) {

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.

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

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.

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.

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

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

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

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

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 manages related hostnames, and hold handler to deal with requests dispatched from server.