Skip to content
Service discovery and routing for large scale microservice operations
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
benchmarks enable cheat configurations Jan 27, 2016
bin remove obsolete debug log Dec 8, 2015
clients Ease the connection stale period to 10s (#314) Oct 24, 2016
config In case of emergecy, raise ping req timeout (#313) Oct 8, 2016
docs Create Aug 5, 2016
endpoints rps_counters_v1 endpoint Aug 10, 2016
lib lib/local_ip: stop caching interfaces list Jan 21, 2016
scripts staging: use cross platform script for getting IP Jan 6, 2016
test really stupid undefined oops, dont tell anyone Aug 10, 2016
.eslintrc Migrate away from uber-standard Nov 1, 2015
.gitignore more work Sep 11, 2015
.istanbul.yml add some config files Aug 21, 2015
.npmrc upgrade tchannel@2.7.4 Aug 31, 2015
.travis.yml fix travis to run tests with and without lazy Dec 1, 2015
LICENSE add a licence Aug 21, 2015
Makefile staging: use cross platform script for getting IP Jan 6, 2016 No longer under active development (#303) Sep 2, 2016
app.js Application: add destroy event Dec 1, 2015
egress-nodes.js Support individual shard repositioning (#298) Aug 5, 2016
entry.js add the required licence file to everything Aug 21, 2015
exit.js add the required licence file to everything Aug 21, 2015
handler.js fiddle with to make less flaky Jun 13, 2016 staging: use cross platform script for getting IP Jan 6, 2016
hyperbahn.thrift discover: add a termination discoverAffine endpoint Jan 6, 2016
mkdocs.yaml Create mkdocs.yaml Nov 5, 2015
package.json 2.20.1 Oct 24, 2016
peer-info.js expose initHeaders on exit_connections_v1 Dec 5, 2015 publish: build package from HEAD Nov 5, 2015
rate_limiter.js Thread remote config for default rate limit (#311) Oct 5, 2016
server.js make hookupSignals() less silly Oct 5, 2015
service-proxy.js Add subchannel update damper (#307) Oct 1, 2016
stat-tags.js Make hyperbahn compatible with batchStats Nov 2, 2015 chmod +x Oct 21, 2015

Hyperbahn [Build Status] (

(This project is no longer under active development.)

Service discovery and routing for large-scale microservice operations


Hyperbahn enables service discovery and routing for large-scale systems comprised of many microservices. Distributed, fault tolerant, and highly available, it lets one service find and communicate with others simply and reliably without having to know where those services run.

Hyperbahn is an overlay network of routers designed to support the TChannel RPC protocol. Hyperbahn itself is based on Ringpop. Its router nodes dynamically converge and gossip known services onto a consistent hash ring topology, forming a mesh of services that can send requests to each other without human intervention or knowledge of specific ports and addresses.

Hyperbahn and TChannel clients are currently supported in Go, Python, and Node.js.

Hyperbahn Features

Whether you're making your service available to others or you're a service consumer, Hyperbahn comes with many features to make application development easier:

  • Configuration Discovery - Free yourself from managing host/port files or configurations.
  • Timeouts - Transitively enforce services' SLAs. Every request must specify a timeout, moving towards a fast failure model.
  • Retries - Eliminate transient failures within a request timeout window.
  • Load Balancing - Spread calls evenly across a service, and distribute outgoing requests evenly over connected Hyperbahn nodes.
  • Rate Limiting - Shield services from excessive calls.
  • Circuit Breaking - Prevent cascading failure and cut off broken clients. Build fast failure into all layers of the network.
  • Distributed Tracing - Understand the entire call flow using Zipkin.

Advertise on a Hyperbahn Cluster

Register a service on Hyperbahn in just three steps:

  1. Instantiate Hyperbahn client
  2. Listen on an arbitrary (could be random) port
  3. Connect to and advertise on Hyperbahn

Or use a service over Hyperbahn in only two steps:

  1. Instantiate Hyperbahn client (if the client is also a service, you reuse the one you've already setup and registered over)
  2. Send a request to the desired service and endpoint name

Local Quick Start

Hyperbahn is designed for large-scale microservice operations. However, you might want to develop and test (or just try it out) locally. To get started with Hyperbahn, set up a Hyperbahn cluster on your local machine.

  1. git clone
  2. cd hyperbahn
  3. ./

You'll now have a two-node Hyperbahn cluster running. In one of the tmux windows, you should see the health checks of both nodes. Double check that the Hyperbahn cluster is healthy. If not, troubleshoot or report your issue.

To exit, run tmux kill-session -t hyperbahn in a seperate shell.

Getting Your App on Hyperbahn

The open source quick start template for Node.js (below) will start a "Hello, world!" TChannel app in Node.js that registers with Hyperbahn.

  • npm install tchannel-gen --global
  • cd ~/projects
  • tchannel-gen my-hyperbahn-app "A new hyperbahn app"
  • cd my-hyperbahn-app
  • npm install
  • make start
  • tcurl -p localhost:9000 my-service MyService::health_v1 -t ./thrift/service.thrift
  • tcurl -p my-service MyService::health_v1 -t ./thrift/service.thrift

You can tcurl it directly at localhost:9000 or tcurl it through Hyperbahn at If you're unfamiliar with tcurl, the command-line tool to call TChannel servers, learn about it here.

Once a service is available on Hyperbahn, any other service on that Hyperbahn cluster can talk to it.


  • npm install hyperbahn

Running the tests

  • git clone
  • cd hyperbahn
  • npm install
  • npm test

MIT Licensed

You can’t perform that action at this time.