api.js

// simplest api possible
http('http://localhost:5000', 'http://localhost:5001')

// same but using discovery service
http(etcd('upstreams/.*'))

// adding tls
http({
   tls: filesystem('/home/certificates/*.cert'),
   port: 443,
   services: etcd('upstreams/.*')
})

// match urls
http({
   match: urls({
      '/v2/domains': service('blackbird'),
      '/v2/(?P<domain_name>[^/]+)/(events|logs)': service('binnacle')
   }),
   services: {
      'blackbird': etcd('/blackbird/.*'),
      'binnacle': etcd('/binnacle/.*')
   }
})

// custom matcher, matches by hostname and by some other stuff
function matcher(request) {
... 
}

http({
   match: matcher,
})

// add auth by tenant id
http({
   hooks: { // hooks executed before request is proxied to the upstreams
      before: [capture('/[^/]*/(?P<tenantId>[0-9]+)/')], // captures tenantId from request uri  
   }
   auth: auth,
   services: etcd('/services/.*'),
})

function auth(request) {
  var auth_response = http.post(etcd('/auth_endpoints'), {
    'Auth-Token': request.headers['X-Auth-Token'],
    'Tenant-ID': request.captured.tenantId //use captured variable
  });
  if (auth_response.code == 200) {
    return true;
  }
  return false;
}

// add rate limiting by tenant Id
http({
   hooks: {
      before: [capture('/[^/]*/(?P<tenantId>[0-9]+)/')]
   }
   rates: {
      // dynamic rate
      '$request.ip': function(request){ 
         if(reqeuest.ip == '127.0.0.1')
           return null;
         return '100 reqs/second';
        },
      '$request.captured.tenantId': '10 reqs/second'
   }
})

// external services definition (for complex services with custom auth with caching)
service('binnacle',{
   upstreams: etcd('/binnacle/.*'),
   auth: function(request){
      if(cache.get(request.password) == null) {
         var status = http.get(etcd('/auth'), {pass: request.password});
         if(status.code != 200) {
            return status;
         }
         cache.set(request.password, status, {seconds: 60});
      }
      request.variables.accountId = cache.get(request.pasword);
      return true;
   },
   rates: {
      '$request.variables.accountId': '4000 reqs/minute',
   },
})

http({
   match: {
      '/v2/(?P<domain_name>[^/]+)/(events|logs)': service('binnacle')
   }
})

// builtin metrics such as requests/second, memory usage, upstream metrics are emitted automatically, 
// the following is a custom metrics support
http({
   metrics: {
      // sets prefix metric.tenantId for the metric emitted
      'vulcan.tenantId.${request.captured.tenantId}': ['frequency', 'duration', 'failures'], // emits requests/second for a given upstream and a request duration for a given ip
   }
})


// for more complex scenarios, custom hooks can be used, supported functions are gauge(), timer(), standard statsd
function emitMetrics(request) {
   timer('vulcan.')...
}

http({
   hooks: {
      after: [emitMetrics]
   }
})

// Setting load balancer support failover and load balancing support (use weighted round robin)
service('binnacle', {
   upstreams: {
      loadBalancer: 'weightedRoundRobin',
      upstreams: [
         {'weight': 5, 'url': 'http://localhost:5000'},
         {'weight': 3, 'url': 'http://localhost:5001'},
      ]
   }
})