eureca.io
Author Alaa-eddine K.
a nodejs transparent bidirectional RPC
supported transports : engine.io, sockjs, WebRTC, Faye, raw websocket ...etc
Project page https://github.com/Ezelia/eureca.io
Installation
npm install eureca.io
Usage
Base example
here we setup a server that expose hello() function.
we can call this function from a browser client or nodejs client.
Server side
express server
var express = require('express')
, app = express(app)
, server = require('http').createServer(app);
var Eureca = require('eureca.io');
var eurecaServer = new Eureca.Server();
eurecaServer.attach(server);
//functions under "exports" namespace will be exposed to client side
eurecaServer.exports.hello = function () {
console.log('Hello from client');
}
//------------------------------------------
//see browser client side code for index.html content
app.get('/', function (req, res, next) {
res.sendfile('index.html');
});
server.listen(8000);
Client side
<!doctype html>
<html>
<head>
<title>Eureca.io test</title>
<script src="/eureca.js"></script>
</head>
<body>
<script>
var client = new Eureca.Client();
client.ready(function (serverProxy) {
serverProxy.hello();
});
</script>
</body>
</html>
var Eureca = require('eureca.io');
var client = new Eureca.Client({ uri: 'http://localhost:8000/' });
client.ready(function (serverProxy) {
serverProxy.hello();
});
Calling server side functions from client and getting back result
Server side
// ... server initialisation
eurecaServer.exports.add = function (a, b) {
return a+b
}
//... other stuff
Client side
client.ready(function (serverProxy) {
//the onReady event is triggered when the remote side finishes
//executing the called function.
//returned value is stored in result argument
serverProxy.add(10, 5).onReady(function(result) {
console.log('got result from server, 10+5=', result);
});
});
Calling client side functions from server and getting the result back
in this example, client will call foo() function on the server, then the server
will call bar() function on the client side
important
client side functions need to be allowed first in the server side when creating the server object
Server side
//we need to allow bar() function first
var eurecaServer = new Eureca.Server({allow:['bar']});
// ... server initialisation
eurecaServer.exports.foo = function () {
//when a server side function is called
//we can access the client proxy
//throught this.clientProxy
var client = this.clientProxy;
//print message in server side
console.log('called foo()');
//call client side bar();
client.bar();
}
//... other stuff
Client side
client.exports.bar = function ()
{
console.log('called bar()');
}
client.ready(function (serverProxy) {
serverProxy.foo();
});
Namespaces
we can expose functions under namespaces if we want to organise them for example
Server side
// ... server initialisation
eurecaServer.exports.math = {
add = function (a, b) {
return a+b
},
sub = function (a, b) {
return a-b
}
}
//... other stuff
Client side
client.ready(function (proxy) {
proxy.math.add(10, 5).onReady(function(result) {
console.log('got result from server, 10+5=', result);
});
proxy.math.sub(10, 5).onReady(function(result) {
console.log('got result from server, 10-5=', result);
});
});
Events
Server side events
Eureca.Server exposes four events
- onConnect triggered when a new client connects to the server.
- onMessage triggered each time a messages is sent from client to server, this can be useful to debug or watch how eureca.io works.
- onDisconnect triggered when a client disconnect.
- onError if something goes wrong with underlying connection this event will be triggered
var Eureca = require('eureca.io');
var eurecaServer = new Eureca.Server();
eurecaServer.onConnect(function (connection) {
console.log('new Client', connection.id);
var client = connection.clientProxy;
//if we defined helloclient() function in the client side
//we can call it like this
client.helloclient();
});
eurecaServer.onMessage(function (msg) {
console.log('RECV', msg);
});
eurecaServer.onDisconnect(function (connection) {
console.log('client %s disconnected', connection.id);
});
eurecaServer.onError(function (e) {
console.log('an error occured', e);
});
Client side events
Eureca.Client exposes seven events
- ready this is a special event, triggered one the client is ready to call server side functions.
- onConnect triggered when a the client successfully open a connection to the server.
- onMessage triggered each time a messages is received from the server
- onDisconnect triggered when the client lost connection. this will cause the client process to terminate.
- onConnectionLost when the client lost connection, it will try to reconnect to the server, this event indicate that a question is lost and that an attempt to reconnect will be triggered.
- onConnectionRetry triggered many times after "onConnectionLost" ... if the connection cannot be re-estabilished the client stop trying and triggers "onDisconnect" event.
- onError if something goes wrong with underlying connection this event will be triggered
var Eureca = require('eureca.io');
var client = new Eureca.Client({ uri: 'http://localhost:8000/' });
//remote parameter contains the proxy able to call server side functions
client.ready(function(remote) {
remote.helloServer();
});
client.onConnect(function (connection) {
console.log('Incomming connection', connection.id);
});
client.onMessage(function (data) {
console.log('Received data', data);
});
client.onError(function (e) {
console.log('error', e);
});
client.onConnectionLost(function () {
console.log('connection lost ... will try to reconnect');
});
client.onConnectionRetry(function (socket) {
console.log('retrying ...');
});
client.onDisconnect(function (socket) {
console.log('Client disconnected ', connection.id);
});
TODO
This documentation is not complete, will be updated with more examples