hyperbahn.md

Hyperbahn client

To be able to make requests to a hyperbahn router it's recommended that you use the hyperbahn client.

The hyperbahn client makes it easy to make requests to any service that hyperbahn knows about and makes it easy to advertise your service with hyperbahn.

The hyperbahn client has a few important methods

• hyperbahnClient.advertise();
• hyperbahnClient.getClientChannel({ serviceName: '...' });

Stability: stable

var hyperbahnClient = HyperbahnClient(options)

var hyperbahnSeedList = [...];
var HyperbahnClient = require('tchannel/hyperbahn/');

var hyperbahnClient = HyperbahnClient({
    tchannel: tchannel,
    serviceName: 'my-service',
    hostPortList: hyperbahnSeedList,
    logger: logger,
    statsd: statsd,
    hardFail: true
});

hyperbahnClient.advertise();
hyperbahnClient.once('advertised', onAdvertised);

function onAdvertised() {
    /* hooray! */
}

The hyperbahnClient is used to advertise() with the hyperbahn router which will advertise your serviceName.

It's also used to get a subchannel when making out going requests through the hyperbahn router

options.tchannel

The root channel that hyperbahnClient will use to advertise to hyperbahn with.

options.serviceName

The serviceName of your service. This is what you will advertise to hyperbahn. Other services will use this serviceName to make calls to you.

options.hostPortList

The hostPortList is the seed list for the hyperbahn network. For you to be able to bootstrap onto the hyperbahn router you need to know where hyperbahn is.

It's recommended that this is stored on disk in a JSON file on every host in your datacenter. You should read it off disk and pass it to the hyperbahn client so that it can reach the hyperbahn router.

options.logger

A logger that hyperbahn client uses to log information about advertisements

options.statsd

A statsd client hyperbahn client uses to count information about advertisement.

Counters:

• hyperbahn-client.{serviceName}.advertisement.success
• hyperbahn-client.{serviceName}.advertisement.failure

options.advertisementTimeout

If set; hyperbahn client advertisemnt will timeout.

This defaults to 5000 if hardFail is true and defaults to Infinity (no timeout) if hardFail is false.

options.hardFail

The hyperbahnClient by default runs in a hybrid mode. This means that hardFail is set to false and it will advertise() forever.

This is recommended for services that are both a HTTP server and a tchannel server.

Any services that a pure tchannel server should set hardFail to true. This means that if hyperbahnClient cannot advertise after the advertisementTimeout (default 5 seconds) it will emit an error event.

Not being able to advertise with hyperbahn is a fatal exception.

hyperbahnClient.advertise()

You must call advertise() to start the advertisement loop with the hyperbahn router.

hyperbahnClient.getClientChannel(opts)

You can call getClientChannel() to get the client sub channel for a particular serviceName.

• opts.serviceName the serviceName of the sub channel

This sub channel is pre-configured with the correct peers list and callerName so you can make requests to it without configuring it.

hyperbahnClient.once('advertised', listener)

This event gets emitted every time hyperbahn router confirms your advertisement. This means the hyperbahn router will start routing requests to you.

Hyperbahn client will advertise every minute with the hyperbahn routers. This event should get emitted every minute.

hyperbahnClient.once('error', listener)

This event gets emitted if there's a failure with hyperbahn advertisement. This only gets emitted if hardFail is true.