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 (s *Gateway) Add(vhost string, uri *url.URL) error
  • func (s *Gateway) Close() error
  • func (s *Gateway) List() []Host
  • func (s *Gateway) Remove(vhost string) error
  • func (s *Gateway) Wait()
• type Host
• type Option
  • func WithHosts(hs []Host) Option
  • func WithTimeout(d time.Duration) Option

Variables

var ErrNotFound = errors.New("vhost not found")

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 (s *Gateway) Add(vhost string, uri *url.URL) error

Add adds the virtual host to the server.

func (*Gateway) Close

func (s *Gateway) Close() error

func (*Gateway) List

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

func (*Gateway) Remove

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

Remove removes the virtual host from the server.

func (*Gateway) Wait

func (s *Gateway) Wait()

Wait blocks until the server is closed.

type Host

type Host struct {
	// Name is the name of the Virtual Host.
	Name string
	// URI is the URI of the target HTTP server.
	URI *url.URL
}

Host is a single Virtual Host.

type Option

type Option func(*options)

Option is a functional option for the server.

func WithHosts

func WithHosts(hs []Host) Option

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the connection timeout to the virtual hosts.