README
¶
go-vhost
go-vhost is a simple library that lets you implement virtual hosting functionality for different protocols (HTTP and TLS so far). go-vhost has a high-level and a low-level interface. The high-level interface lets you wrap existing net.Listeners with "muxer" objects. You can then Listen() on a muxer for a particular virtual host name of interest which will return to you a net.Listener for just connections with the virtual hostname of interest.
The lower-level go-vhost interface are just functions which extract the name/routing information for the given protocol and return an object implementing net.Conn which works as if no bytes had been consumed.
API Documentation
Usage
l, _ := net.Listen("tcp", *listen)
// start multiplexing on it
mux, _ := vhost.NewHTTPMuxer(l, muxTimeout)
// listen for connections to different domains
for _, v := range virtualHosts {
vhost := v
// vhost.Name is a virtual hostname like "foo.example.com"
muxListener, _ := mux.Listen(vhost.Name())
go func(vh virtualHost, ml net.Listener) {
for {
conn, _ := ml.Accept()
go vh.Handle(conn)
}
}(vhost, muxListener)
}
for {
conn, err := mux.NextError()
switch err.(type) {
case vhost.BadRequest:
log.Printf("got a bad request!")
conn.Write([]byte("bad request"))
case vhost.NotFound:
log.Printf("got a connection for an unknown vhost")
conn.Write([]byte("vhost not found"))
case vhost.Closed:
log.Printf("closed conn: %s", err)
default:
if conn != nil {
conn.Write([]byte("server error"))
}
}
if conn != nil {
conn.Close()
}
}
Low-level API usage
// accept a new connection
conn, _ := listener.Accept()
// parse out the HTTP request and the Host header
if vhostConn, err = vhost.HTTP(conn); err != nil {
panic("Not a valid http connection!")
}
fmt.Printf("Target Host: ", vhostConn.Host())
// Target Host: example.com
// vhostConn contains the entire request as if no bytes had been consumed
bytes, _ := ioutil.ReadAll(vhostConn)
fmt.Printf("%s", bytes)
// GET / HTTP/1.1
// Host: example.com
// User-Agent: ...
// ...
Advanced introspection
The entire HTTP request headers are available for inspection in case you want to mux on something besides the Host header:
// parse out the HTTP request and the Host header
if vhostConn, err = vhost.HTTP(conn); err != nil {
panic("Not a valid http connection!")
}
httpVersion := vhost.Request.MinorVersion
customRouting := vhost.Request.Header["X-Custom-Routing-Header"]
Likewise for TLS, you can look at detailed information about the ClientHello message:
if vhostConn, err = vhost.TLS(conn); err != nil {
panic("Not a valid TLS connection!")
}
cipherSuites := vhost.ClientHelloMsg.CipherSuites
sessionId := vhost.ClientHelloMsg.SessionId
After you're done muxing, you probably don't need to inspect the header data anymore, so you can make it available for garbage collection:
// look up the upstream host
upstreamHost := hostMapping[vhostConn.Host()]
// free up the muxing data
vhostConn.Free()
// vhostConn.Host() == ""
// vhostConn.Request == nil (HTTP)
// vhostConn.ClientHelloMsg == nil (TLS)
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BadRequest ¶
type BadRequest struct {
// contains filtered or unexported fields
}
BadRequest is returned when extraction of the vhost name fails
type ClientHelloMsg ¶
type Closed ¶
type Closed struct {
// contains filtered or unexported fields
}
Closed is returned when the underlying connection is closed
type HTTPConn ¶
func HTTP ¶
HTTP parses the head of the first HTTP request on conn and returns a new, unread connection with metadata for virtual host muxing
type HTTPMuxer ¶
type HTTPMuxer struct {
*VhostMuxer
}
func NewHTTPMuxer ¶
NewHTTPMuxer begins muxing HTTP connections on the given listener by inspecting the HTTP Host header in new connections.
func (*HTTPMuxer) HandleErrors ¶
func (m *HTTPMuxer) HandleErrors()
HandleErrors handles muxing errors by calling .NextError(). You must invoke this function if you do not want to handle the errors yourself.
type Listener ¶
type Listener struct {
// contains filtered or unexported fields
}
Listener is returned by a call to Listen() on a muxer. A Listener only receives connections that were made to the name passed into the muxer's Listen call.
Listener implements the net.Listener interface, so you can Accept() new connections and Close() it when finished. When you Close() a Listener, the parent muxer will stop listening for connections to the Listener's name.
func (*Listener) Accept ¶
Accept returns the next mux'd connection for this listener and blocks until one is available.
type NotFound ¶
type NotFound struct {
// contains filtered or unexported fields
}
NotFound is returned when a vhost is not found
type TLSConn ¶
type TLSConn struct {
ClientHelloMsg *ClientHelloMsg
// contains filtered or unexported fields
}
A Conn represents a secured connection. It implements the net.Conn interface.
type TLSMuxer ¶
type TLSMuxer struct {
*VhostMuxer
}
func NewTLSMuxer ¶
NewTLSMuxer begins muxing TLS connections by inspecting the SNI extension.
func (*TLSMuxer) HandleErrors ¶
func (m *TLSMuxer) HandleErrors()
HandleErrors is the default error handler for TLS muxers. At the moment, it simply closes connections which are invalid or destined for virtual host names that it is not listening for. You must invoke this function if you do not want to handle the errors yourself.
type VhostMuxer ¶
type VhostMuxer struct {
sync.RWMutex // protects the registry
// contains filtered or unexported fields
}
Source Files