vulcan

README

Status

Don't use it in production, early adopters and hackers are welcome

Proxy for HTTP services

Vulcan is a proxy built for APi's specific needs that are usually different from website's needs. It is a proxy that you program in JavaScript.

function handle(request){
    return {upstreams: ["http://localhost:5000", "http://localhost:5001"]}
}

How slow can your proxy be?

One wants proxies to be fast, but in case of services proxy is rarely a bottleneck, whereas DB and filesystem are. Vulcan supports rate limiting using memory, Cassandra or Redis backends, so your service can introduce proper account-specific rates and expectations right from the start.

function handle(request){
    return {
        failover: true,
        upstreams: ["http://localhost:5000", "http://localhost:5001"],
        rates: {request.ip: ["10 requests/second", "1000 KB/second"]}
    }
}

Discover FTW!

Storing upstreams in files is ok up to a certain extent. On the other hand, keeping upstreams in a discovery service simplifies deployment and configuration management. Vulcan supports Etcd or Zookeeper:

function handle(request){
    return {
        upstreams: discover("/upstreams"),
        rates: {request.ip: ["10 requests/second", "1000 KB/second"]}
    }
}

Caching and Auth

Auth is hard and you don't want every endpoint to implement auth. It's better to implement auth endpoint once, and make proxy deal with it. As a bonus you can cache results using memory, Redis or Cassandra, reducing load on the databases holding account creds.

function handle(request){
    response = get(discover("/auth-endpoints"), {auth: request.auth}, {cache: true})
    if(!response.code == 200) {
        return response
    }
    return {
        upstreams: discover("/upstreams"),
        rates: {request.ip: ["10 requests/second", "1000 KB/second"]}
    }
}

And many more advanced features you'd need when writing APIs, like Metrics and Failure detection. Read on!

Development setup

Mailing list: https://groups.google.com/forum/#!forum/vulcan-proxy

Install go

(http://golang.org/doc/install)

Get vulcan and install deps

# set your GOPATH to something reasonable.
export GOPATH=~/projects/vulcan
cd $GOPATH
go get github.com/mailgun/vulcan

make -C ./src/github.com/mailgun/vulcan deps
cd ./src/github.com/mailgun/vulcan

Run in devmode

make run

Cassandra

Cassandra-based throttling is a generally good idea, as it provides reliable distributed counters that can be shared between multiple instances of vulcan. Vulcan provides auto garbage collection and cleanup of the counters.

Tested on versions >= 1.2.5

Usage

vulcan \
       -h=0.0.0.0\                  # interface to bind to
       -p=4000\                     # port to listen on
       -c=http://localhost:5000 \   # control server url#1
       -c=http://localhost:5001 \   # control server url#2, for redundancy
       -stderrthreshold=INFO \      # log info, from glog
       -logtostderr=true \          # log to stderror
       -logcleanup=24h \            # clean up logs every 24 hours
       -log_dir=/var/log/           # keep log files in this folder
       -pid=/var/run/vulcan.pid     # create pid file
       -lb=roundrobin \             # use round robin load balancer
       -b=cassandra \               # use cassandra for throttling
       -cscleanup=true \            # cleanup old counters
       -cscleanuptime=19:05 \       # cleanup counters 19:05 UTC every day
       -csnode=localhost  \         # cassandra node, can be multiple
       -cskeyspace=vulcan_dev       # cassandra keyspace

Development

To run server in development mode:

make run

To run tests

make test

To run tests with coverage:

make coverage

To cleanup temp folders

make clean

Status

Initial development done, loadtesting at the moment and fixing quirks.

Documentation

Overview

This package contains the proxy core - the main proxy function that accepts and modifies request, forwards or denies it.

Index

• Constants
• type Buffer
  • func (*Buffer) Close() error
• type ProxySettings
• type ReverseProxy
  • func NewReverseProxy(metrics *metrics.ProxyMetrics, s *ProxySettings) (*ReverseProxy, error)
  • func (p *ReverseProxy) Get(w http.ResponseWriter, hosts []string, query client.MultiDict, ...) error
  • func (p *ReverseProxy) ServeHTTP(w http.ResponseWriter, req *http.Request)

Constants

const (
	DefaultHttpReadTimeout = time.Duration(10) * time.Second
	DefaultHttpDialTimeout = time.Duration(10) * time.Second
)

Standard dial and read timeouts, can be overriden when supplying proxy settings

const TRUST_FORWARD_HEADER = false

Types

type Buffer

type Buffer struct {
	*bytes.Reader
}

We need this struct to add a Close method and comply with io.ReadCloser

func (*Buffer) Close

func (*Buffer) Close() error

type ProxySettings

type ProxySettings struct {
	// Controlller tells proxy what to do with each request
	Controller control.Controller
	// MemoryBackend or CassandraBackend
	ThrottlerBackend backend.Backend
	// Load balancing algo, e.g. RandomLoadBalancer
	LoadBalancer loadbalance.Balancer
	// How long would proxy wait for server response
	HttpReadTimeout time.Duration
	// How long would proxy try to dial server
	HttpDialTimeout time.Duration
}

Reverse proxy settings, what loadbalancing algo to use, timeouts, rate limiting backend

type ReverseProxy

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

This is a reverse proxy, not meant to be created directly, use NewReverseProxy function instead

func NewReverseProxy

func NewReverseProxy(metrics *metrics.ProxyMetrics, s *ProxySettings) (*ReverseProxy, error)

Creates reverse proxy that acts like http server.

func (*ReverseProxy) Get

func (p *ReverseProxy) Get(w http.ResponseWriter, hosts []string, query client.MultiDict, auth *netutils.BasicAuth) error

Vulcan implements Getter interface that is used by controllers to issue concurrent get requests with failover

func (*ReverseProxy) ServeHTTP

func (p *ReverseProxy) ServeHTTP(w http.ResponseWriter, req *http.Request)

Main request handler, accepts requests, round trips it to the upstream proxies back the response.