Skip to content


Subversion checkout URL

You can clone with
Download ZIP
semver service registry for clusters
JavaScript Shell

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.



service registry and port assignment for clusters

build status

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.



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':


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');


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


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

ports.get('web@1.2.x', function (ps) {
    var u = 'http://' + ps[0].host + ':' + ps[0].port;


$ 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()

var bouncy = require('bouncy');
bouncy(function (req, bounce) {
    var domains = ( || '').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)]);

Now we can register different versions of the http process:


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');



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');


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

command-line usage


  seaport listen PORT OPTIONS

    Create a seaport server on PORT.


      --authorize KEY.json    Load authorized keys from KEY.json.

  seaport show HOST:PORT

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

  seaport query HOST:PORT PATTERN

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

  seaport register NAME@VERSION -- [COMMAND...]

    Register a service. COMMAND will get an assigned port to use as
    its last argument. If COMMAND exits it will be restarted.


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.

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.

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.


Create a duplex stream of the underlying crdt object.

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.

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.,

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


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


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


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.


To get the seaport library, with npm do:

npm install seaport

To get the seaport command, do:

npm install -g seaport



Something went wrong with that request. Please try again.