exorelay

Exosphere Communication Relay for JavaScript

Communication relay between JavaScript code bases and the Exosphere environment

This library allows you to add Exosphere communication to any Node.js codebase. It is intended to be used in your web or API server. If you want to write a micro-service in Node, please use ExoService-JS, which uses this library internally.

Add an ExoRelay to your application

Each code base should have only one ExoRelay instance. ExoRelay instances emit events to signal state changes:

• online: the instance is completely online now. Provides the port it listens on.
• offline: the instance is offline now
• error: an error has occurred. The instance is in an invalid state, your application should crash.

ExoRelay = require 'exorelay'

exoRelay = new ExoRelay()
exoRelay.on 'online', (port) ->  # yay, we are online!
exoRelay.on 'error', (err) ->    # examine, print, or log the error here
exoRelay.listen()

More details and how to customize the port is described in the spec.

Handle incoming commands

Register a handler for incoming commands:

exoRelay.registerHandler 'hello', (name) ->
  console.log "Hello #{name}"

More details on how to define command listeners are here. If you are implementing services, you want to send outgoing replies to incoming commands:

exoRelay.registerHandler 'users.create', (userData, {reply}) ->
  # on this line we would create a user database record with the attributes given in userData
  reply 'users.created', id: 456, name: userData.name

More details and a working example of how to send replies is here.

Send outgoing commands

Send a command to Exosphere:

exoRelay.send 'hello', name: 'world'

Sending a command is fire-and-forget, i.e. you don't have to wait for the sending process to finish before you can do the next thing. More details on how to send various data are here.

You can handle the incoming replies to your outgoing commands:

exoRelay.send 'users.create', name: 'Will Riker', (createdUser) ->
  print "created user #{createdUser.id}"

More examples for handling incoming replies are here. Command handlers also provide a shortcut to send commands:

exoRelay.registerHandler 'users.create', (userData, {send, reply}) ->
  send 'passwords.encrypt' userData.password, (encryptedPassword) ->
    userData.encryptedPassword = encryptedPassword
    # on this line we would create a user database record with the attributes given in userData
    reply 'users.created', id: 456, name: userData.name

More details and a working example of how to send commands from within command handlers is here.