seaport

service registry and port assignment for clusters

Seaport stores (host,port) combos (and other metadata) for you so you won't need to spend so much effort keeping configuration files current as your architecture grows to span many processes on many machines. Just register your services with seaport and then query seaport to see where your services are running.

example

register a service

In this example we'll register a service with seaport and then elsewhere connect to it.

First spin up a seaport server:

$ seaport listen 9090

then obtain a port for a server called 'web':

server.js:

var seaport = require('seaport');
var ports = seaport.connect('localhost', 9090);
var http = require('http');

var server = http.createServer(function (req, res) {
    res.end('beep boop\r\n');
});

server.listen(ports.register('[email protected]'));

next just get() that 'web' service from another script!

client.js:

var seaport = require('seaport');
var ports = seaport.connect(9090);
var request = require('request');

ports.get('[email protected]', function (ps) {
    var u = 'http://' + ps[0].host + ':' + ps[0].port;
    request(u).pipe(process.stdout);
});

output:

$ node server.js &
[1] 6012
$ node client.js
beep boop

and if you spin up client.js before server.js then it still works because get() queues the response!

http router

In this example we'll create an http router that will route to different versions of our application based on the http host header provided.

First we'll create a seaport server and http proxy process, router.js:

var seaport = require('seaport');
var server = seaport.createServer()
server.listen(5001);

var bouncy = require('bouncy');
bouncy(function (req, bounce) {
    var domains = (req.headers.host || '').split('.');
    var service = 'http@' + ({
        unstable : '0.1.x',
        stable : '0.0.x'
    }[domains[0]] || '0.0.x');
    
    var ps = server.query(service);
    
    if (ps.length === 0) {
        var res = bounce.respond();
        res.end('service not available\n');
    }
    else {
        bounce(ps[Math.floor(Math.random() * ps.length)]);
    }
}).listen(5000);

Now we can register different versions of the http process:

server_a.js:

var seaport = require('seaport');
var ports = seaport.connect('localhost', 5001);
var http = require('http');

var server = http.createServer(function (req, res) {
    res.end('version 0.0.0\r\n');
});

server.listen(ports.register('[email protected]'));

server_b.js:

var seaport = require('seaport');
var ports = seaport.connect('localhost', 5001);
var http = require('http');

var server = http.createServer(function (req, res) {
    res.end('version 0.1.0\r\n');
});

server.listen(ports.register('[email protected]'));

Now once all these processes are running, we can query the http proxy and get back different versions of our service:

$ curl -H 'Host: stable' localhost:5000
version 0.0.0
$ curl -H 'Host: unstable' localhost:5000
version 0.1.0

authorized keys

For security you can sign messages and maintain a list of authorized public keys which are allowed to register services and make updates.

First make some PEM keypairs with rsa-json:

$ mkdir keys
$ rsa-json > keys/hub.json
$ rsa-json > keys/web.json

Now we can create a seaport with an authorized keys list:

var fs = require('fs');
var publicKeys = fs.readdirSync(__dirname + '/keys')
    .filter(function (x) { return /\.json$/.test(x) })
    .map(function (x) { return require('./keys/' + x).public })
;
var seaport = require('seaport');

var opts = require('./keys/hub.json');
opts.authorized = publicKeys;

var ports = seaport.createServer(opts);
ports.listen(9090);

Now we can register a server with an authorized key:

var seaport = require('seaport');
var ports = seaport.connect(9090, require('./keys/web.json'));

var http = require('http');
var server = http.createServer(function (req, res) {
    res.end('beep boop\n');
});
server.listen(ports.register('[email protected]'));

No credentials are required to query the entries, only to register and update entries. Our client can just query seaport directly:

var seaport = require('seaport');
var ports = seaport.connect(9090);
var request = require('request');

ports.get('[email protected]', function (ps) {
    var u = 'http://' + ps[0].host + ':' + ps[0].port;
    var r = request(u);
    
    r.pipe(process.stdout);
    r.on('end', ports.close.bind(ports));
});

---

$ node client.js
beep boop

methods

var seaport = require('seaport')

All the parameters that take a role parameter can be intelligently versioned with semvers by specifying a version in the role parameter after an '@' character.

var s = seaport(opts)

Create a new seaport instance.

To sign your messages, specify opts.private and opts.public as PEM-encoded strings.

To set an initial list of authorized keys which are allowed to make updates, pass opts.authorized as an array of PEM-encoded public key strings.

When the authorized key list is empty, all connected nodes may make updates.

Consider using rsa-json to generate the keypairs.

var s = seaport.connect(..., opts)

Create a seaport instance piped to a tcp connection at ....

If the server at ... is not available or the connection drops, the connection is retried every second. If the seaport server is down, other hubs that registered themselves with the role 'seaport' are tried in a round-robin.

var s = seaport.createServer(opts)

Create a seaport instance with an attached tcp server with .listen() and .address() methods that will set up streams in "server mode" for incoming tcp connections.

Internally seaport uses a heartbeat to help identify stale or orphaned service registrations. Use opts.heartbeat, in milliseconds, to set the interval that clients should update their heartbeat. The default heartbeat is 15000. Services will be considered stale when if they have not responded to a heartbeat in opts.timeout milliseconds. The default timeout is opts.heartbeat * 3.

s.createStream(host)

Create a duplex stream that implements the seaport protocol.

If host is specified, seaport goes into "server mode" where it stores the host value on the network for the remote endpoint's node id.

var port = s.register(role, opts)

Register the service described by the string role (name@verion, version optional). Return the port to use for the service.

Registrations are valid so long as the connection to the seaport server is still alive. When the connection to the seaport server goes down, all registrations are freed.

You can optionally store whatever other records you want on the service by putting those keys in opts.

If opts.port is specified, return and store that value for the service port. Otherwise a random available port is chosen. If you want to specify a valid range for ports to be, set opts.range (default: [ 10000, 65535 ]).

If you don't want you specify role you can also use opts.role and opts.version.

You can control what the key name will be by setting opts.id yourself. Otherwise a random hex string will be used.

var meta = s.registerMeta(role, opts)

Like s.register(), but return the entire meta object instead of just the meta.port. This is handy if you need the id to update metadata later.

var services = s.query(search)

Query the seaport entries with search as a name@semver string. The @semver part is optional and all the usual semver pattern matching applies.

Returns an array of all the matching services for search.

If search is undefined, all the records are returned.

s.get(role, cb)

Like .query(), but does cb(services) with the list of matching entries. If services is empty, cb won't fire until there is at least one match available.

s.free(service), s.free(id)

Remove a service registered with .register(). You can remove a service by the service object itself or just its id.

s.authorize(publicKey)

Authorize the PEM-encoded publicKey string to make updates. Updates include registering services and setting keys.

s.close()

Close a seaport connection or server. Cancel any pending requests.

s.set(id, value)

Update a registration value by its id, broadcasting the new registration meta value.

events

s.on('register', function (service) {})

Emitted whenever any node registers a new service.

s.on('free', function (service) {})

Emitted whenever any node frees a service that was previously registered.

s.on('host', function (host) {})

In non-server mode, the client will receive notification from the server what its host is on the network.

s.on('reject', function (key, value, timestamp, source, sig) {})

Emitted when key signing fails or when a node tries to send update but is not in the authorized key list.

s.on('connect', function () {})

Emitted when a connection is established with seaport.connect().

s.on('disconnect', function () {})

Emitted when a connection established by seaport.connect() drops.

s.on('close', function () {})

The 'close' event fires when s.close() is called.

s.on('timeout', function () {})

When the connection times out, this event fires.

command-line usage

usage:

  seaport listen PORT [KEY.json, ...]

    Create a seaport server on PORT.
    Optionally load authorized public keys from json files.
    
    Key files of arrays are expected to be PEM public key lists.
    Key files are otherwise expected to have public and private fields.

  seaport show HOST:PORT

    Show the seaport records for the server running at HOST:PORT.
 
  seaport watch HOST:PORT

    Listen for register and free events from the seaport registry.
    For even more output use `-v` or `--verbose`.

  seaport query HOST:PORT PATTERN

    Run a query for PATTERN against the server running at HOST:PORT.

  seaport register HOST:PORT NAME@VERSION {OPTIONS} -- [COMMAND...]

    Register a service. COMMAND will get an assigned port to use as
    its last argument. If COMMAND exits it will be restarted.
    
    OPTIONS:
    
    --key=key.json    Load a public/private PEM keypair from key.json.
    --meta.KEY=...    Set json metadata on the service record.
 

install

To get the seaport library, with npm do:

npm install seaport

To get the seaport command, do:

npm install -g seaport

license

MIT