vhoster

README

Vhoster

Vhoster is a library for creating virtual hosts in a Go server. It is intended to be used as a library, but it also includes a gateway that can be used to create and delete vhosts dynamically.

The gateway can also be used as a central point of entry for all requests, and it can be used to load balance requests to multiple servers.

Quick Start

Locally

1. Start the server listening on port 8082

   go run cmd/server/main.go
   

2. Start the gateway listening on port 8083

   go run cmd/gateway/main.go
   

3. Create the vhost in the gateway

   curl -X POST -H "Content-Type: application/json" -d '{"host_prefix": "test", "target": "http://localhost:8082"}' http://localhost:8083/vhost/
   

   then, to test, run curl test.localhost:8081, and you'll get the "Hello, World!"

4. Delete the vhost in the gateway

   curl -X DELETE localhost:8083/vhost/test
   

In docker compose

1. Run docker compose up, it will build and start two container: (a) the gateway on port 8080 and vhost api on port 8083, and (b) the test server on port 8082, but the testserver is unreachable from the local machine directly. We will set up a virtual host to access it.

   If you want to verify that testserver is not accessible, try running curl localhost:8082 and you'll get an error.

2. It comes with preconfigured vhost "test.localhost:8080" that routes to "http://testserver:8082". You can verify that it works by running curl test.localhost:8080, and you'll get the "Hello, World!"

3. Run the following command to instruct gateway to route all requests to "hello.localhost:8080" to "http://testserver:8082":

   curl -X POST -H "Content-Type: application/json" -d '{"host_prefix": "hello", "target": "http://testserver:8082"}' http://localhost:8083/vhost/
   

   This will instruct the gateway to route all requests that arrive at "test.localhost:8080" to "http://testserver:8082".

4. Now, you can access the test server by running curl hello.localhost:8080, and you'll get the "Hello, World!"

   At this point, both "test.localhost:8080" and "hello.localhost:8080" will route to the test server.

5. To list existing routes, and verify that, run:

   curl -X GET localhost:8083/vhost/
   

   (-X GET is optional and instructs curl to use GET method, which is the default method for curl, so you can omit it: curl localhost:8083/vhost/)

   The API server will respond on this GET request with JSON that lists all existing vhosts.

6. You can delete the route now, by running:

   curl -X DELETE localhost:8083/vhost/hello
   

Documentation

Index

• Variables
• type Gateway
  • func Listen(addr string, opts ...Option) (*Gateway, error)
  • func (g *Gateway) Add(vhost string, uri *url.URL) error
  • func (g *Gateway) Close() error
  • func (g *Gateway) Exists(vhost string) bool
  • func (s *Gateway) List() []Host
  • func (g *Gateway) Remove(vhost string) error
  • func (g *Gateway) RemoveByURI(uri *URI) error
  • func (g *Gateway) Replace(vhost string, uri *url.URL) error
  • func (g *Gateway) Wait()
• type Host
  • func (h Host) Validate() error
• type Option
  • func WithHosts(hs []Host) Option
  • func WithTimeout(d time.Duration) Option
• type URI
  • func Must(u *URI, err error) *URI
  • func Parse(s string) (*URI, error)
  • func ToURI(u *url.URL) *URI
  • func (u *URI) MarshalJSON() ([]byte, error)
  • func (u *URI) String() string
  • func (u *URI) URL() *url.URL
  • func (u *URI) UnmarshalJSON(b []byte) error

Variables

var (
	// ErrNotFound is returned when a virtual host is not found.
	ErrNotFound = errors.New("vhost not found")
	// ErrAlreadyExists is returned when a virtual host already exists.
	ErrAlreadyExists = errors.New("vhost address already in use")
)

Types

type Gateway

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

Gateway is a virtual host reverse proxy server. Zero value is not usable.

func Listen

func Listen(addr string, opts ...Option) (*Gateway, error)

Listen initialises the server and starts listening on the given address.

func (*Gateway) Add

func (g *Gateway) Add(vhost string, uri *url.URL) error

Add adds the virtual host to the server.

func (*Gateway) Close

func (g *Gateway) Close() error

func (*Gateway) Exists

func (g *Gateway) Exists(vhost string) bool

Exists returns true if the virtual host exists.

func (*Gateway) List

func (s *Gateway) List() []Host

List returns the list of virtual hosts.

func (*Gateway) Remove

func (g *Gateway) Remove(vhost string) error

Remove removes the virtual host from the server.

func (*Gateway) RemoveByURI

func (g *Gateway) RemoveByURI(uri *URI) error

RemoveByURI removes the virtual host from the server by URI.

func (*Gateway) Replace

func (g *Gateway) Replace(vhost string, uri *url.URL) error

Replace replaces the virtual host with the new one. If the virtual host does not exist, it will be added.

func (*Gateway) Wait

func (g *Gateway) Wait()

Wait blocks until the server is closed.

type Host

type Host struct {
	// Name is the name of the Virtual Host.
	Name string `json:"name"`
	// URI is the URI of the target HTTP server.
	URI *URI `json:"uri"`
}

Host is a single Virtual Host.

func (Host) Validate

func (h Host) Validate() error

type Option

type Option func(*options)

Option is a functional option for the server.

func WithHosts

func WithHosts(hs []Host) Option

WithHosts sets the preconfigured hosts.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the connection timeout to the virtual hosts.

type URI

type URI url.URL

URI is a wrapper around pkg/net/url.URL that implements custom json.Marshaler and json.Unmarshaler.

func Must

func Must(u *URI, err error) *URI

Must panics if err is not nil.

func Parse

func Parse(s string) (*URI, error)

Parse is a wrapper around pkg/url.Parse.

func ToURI

func ToURI(u *url.URL) *URI

func (*URI) MarshalJSON

func (u *URI) MarshalJSON() ([]byte, error)

func (*URI) String

func (u *URI) String() string

func (*URI) URL

func (u *URI) URL() *url.URL

convenience functions

func (*URI) UnmarshalJSON

func (u *URI) UnmarshalJSON(b []byte) error