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 = ;var ports = seaport;var http = ;var server = http;server;
next just get()
that 'web'
service from another script!
client.js:
var seaport = ;var ports = seaport;var request = ;ports;
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 = ;var server = seaportserver;var bouncy = ;;
Now we can register different versions of the http
process:
server_a.js:
var seaport = ;var ports = seaport;var http = ;var server = http;server;
server_b.js:
var seaport = ;var ports = seaport;var http = ;var server = http;server;
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 = ;var publicKeys = fs;var seaport = ;var opts = ;optsauthorized = publicKeys;var ports = seaport;ports;
Now we can register a server with an authorized key:
var seaport = ;var ports = seaport;var http = ;var server = http;server;
No credentials are required to query the entries, only to register and update entries. Our client can just query seaport directly:
var seaport = ;var ports = seaport;var request = ;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