WebSocket-Agent
WebSocket-agent is a server to server secured communication tunnel based on socket.io websocket. It allows seamless messaging using Promise semantics and syntax.
install:
javascript npm install websocket-agent --save
Quick example
The module contain both server constructor and client
Server
var AgentServer = ; var serverInstance = protocol: AgentServerWS port: 7788 secret: "my secure shared secret"; serverInstance; serverInstance;
Client
var Agent = ; // conf can be loaded asynchronouslyvar conf = Promise; Agent Agent
Documentation
Usage
The module returns two objects - client and server, though there is no reason to require them both.
*note: the module doesn't use any Promise library and count on the basic Promise global object. If you use and old node/iojs version either use a polyfill or upgrade your engine
var websocket-agent = ;// server objectvar AgentServer = websocketAgentServer;// client objectvar Agent = websocketAgent; // or require directlyvar AgentServer = ;var Agent = ;
AgentServer (server constructor)
start a server instance that starts to listen immediately
Options:
secret
- {string} secret key to validate incoming messages (required)port
- {number} websocket port. default: ws:80, wss:443protocol
- websocket protocol. default: wswssOptions
- (wss only) {object} additional options to pass to thehttps.createServer
methodprivateKey
- (wss only) {string|Buffer} added to wssOptionscertificate
- (wss only) {string|Buffer} added to wssOptionsagentNameFormat
- {string} agents naming format (defaultA#
) - use#
to indicate an auto incremented digit. multiple#
will be filled with 0.A###
- >A001
debug
- {boolean} be verbose (don't do it to yourself). default: false
var AgentServer = ; // plain wsvar serverInstance = protocol: AgentServerWS port: 7788 secret: "my secure shared secret"; var fs = // secured wssvar serverInstance = protocol: AgentServerWSS secret: "my secure shared secret" port: 7788 privateKey: fs certificate: fs;
Connected agent
Every connected agent is represented by an agent object with this format.
the agent is passed to every hook message.
If you want to add data to the object please use agent.data
namespace
*note - if an agent disconnects and reconnects the object will be recreated from scratch
agent = name: 'A1' socket: Object // reference to the actual socket object firstTime: true data: undefined // reserved namespace for your own use
serverInstance
AgentServer#onHook
Respond to an event from an Agent.
- action specific handler
AgentServer#onHook({string} action, {function} handler(message, socket, agent))
- multiple actions
AgentServer#onHook({object} actions) actions = {"action": {function} handler}
- catch all (receives action as first argument)
AgentServer#onHook({function} catchAllHandler(action, message, socket, agent))
The handler follows Promise syntax and sends the eventual return value to the client
Throwing error will stop message processing and will trigger the catch
handler on client side
Call onHook
as many times as you need.
In case of multiple handlers for one command, they will run by declaration order
note: if a generic catch all handler is defined, it will run before any action specific handlers regardless to declaration order
Example:
// catch all syntaxserverInstance // same asserverInstance // same asserverInstance
AgentServer#sendTo
Agent.sendTo({object|string} agent, {string} command [, {*} message])
Send command to the given Agent
Example:
serverInstance // or use agentName (string)serverInstance
sendTo errors:
- TIMEOUT - message timeout (the Agent may have received the message)
- UNKNOWN_ACTION - the Agent doesn't have any handlers for the given action
- UNKNOWN_AGENT - the Agent doesn't have any handlers for the given action
- AGENT_NOT_CONNECTED - the Agent doesn't have any handlers for the given action
AgentServer#sendAll
Agent.sendAll({string} command [, {*} message])
Send command to all of the connected Agents
Example:
serverInstance
sendAll errors:
- All errors from
AgentServer#command
- NO_CONNECTED_AGENTS - message timeout (the Agent may have received the message)
server events
agentConnected
- emitted whenever an agent is connected and verified. agent object is the payloadagentDisconnected
- emitted whenever an agent is disconnected. agent object is the payload
Agent (client constructor)
Create a client instance
Options:
host
- {string} socket.io host to connect to (required).secret
- {string} secret key to validate incoming messages (required)dataStore
- {object} data store for persistent data. (see DataStores section bellow)debug
- {boolean} be verbose (don't do it to yourself). default: false
var Agent = ; var agent = host: 'http://localhost:7788' secret: "my secure shared secret" dataStore: agent
Agent#send
agent.send({string} action [,{object} message [, {number} timeout]])
Send an event request in Promise syntax
Example:
agent
send errors:
- OFFLINE - happens when trying to send tunnel and agent is offline
- TIMEOUT - message timeout (the server may have received the message)
- UNKNOWN_ACTION - the server doesn't have any handlers for the given action
Agent#onHook
Respond to an event from the server.
- action specific handler
Agent#onHook({string} action, {function} handler(message, socket))
- multiple actions
Agent#onHook({object} actions) {"action": {function} handler}
- catch all (receives action as first argument)
Agent#onHook({function} catchAllHandler(action, message, socket))
The handler follows Promise syntax and sends the eventual return value to the client
Throwing error will stop message processing and will trigger the catch
handler on client side
Call on
as many times as you need.
In case of multiple handlers for one command, they will run by declaration order
note: if a generic catch all handler is defined, it will run before any action specific handlers regardless to declaration order
Example:
// catch all syntaxagent // same asagent // same asagent
Agent events
ready
- emitted once a connection to the server has been established and a validation message successfully traveled to the server and backconnected
- emitted once when the socket connects to the serverdisconnected
- emitted every time the connection to the server is disconnectedreconnected
- similar to ready event but emitted after a successful reconnection
Error handling
Server:
serverInstance ``` General Errors:- WRONG_SECRET - the provided secret does not match the secret on the server- DUPLICATE_ID - two agents with the same id tried to connect to the server (only the first one is accepted) Client: ```javascriptAgent
Data Stores
Enable data store to save persistent client names.
data stores must be an object with two methods save
and load
that returns a promise
You can use any backend that you want
here is a simple example for a json file storage:
var fs = ; var { conf = conf || {}; return { return { fs }; } { return { fs }; } }; # Servervar serverInstance = port: 7788 secret: "my secure shared secret" agentNameFormat: 'A####' dataStore: ; # Clientvar agent = host: 'http://localhost:7788' secret: "my secure shared secret" dataStore: ;