Reference
Table of Contents
Specification
The protocol is still under active development and it's not easy to maintain both reference implementation and specification document. Accordingly for now the reference implementation takes the place of the specification document.
The current blocks build the protocol.
- Handshaking - A process to negotiate the protocol.
- Transport - A full-duplex message channel.
ws
- Based on WebSocket.sse
- Based on Server-Sent Events.streamxhr
- Based on Streaming using XMLHttpRequest.streamxdr
- Based on Streaming using XDomainRequest.streamiframe
- Based on Streaming using iframe and DOM manipulation.longpollajax
- Based on Long polling using Ajax.longpollxdr
- Based on Long polling using XDomainRequest.longpolljsonp
- Based on Long polling using JSONP.
- Extension - An additional feature built on protocol.
reply
- Allows for the sender to attach callbacks in sending event and for the receiver to call them with the result of the event processing in receiving event.
Nevertheless, if you need big picture of the protocol, see Anatomy of Protocol. However note that it covers future features on the roadmap and may be different with this version.
Reference Implementation
To help understand and implement the protocol, reference implementation is provided. It is written in easy-to-read JavaScript with a lot of detailed notes you should be aware of. Also you can use it to verify your implementation casually and as the counterpart in your examples. See annotated source codes:
Note
- They are not for production use.
Installation
First you need to install Node.js. Then type the following to install the reference implementation:
npm install vibe-protocol
Interactive Mode
JavaScript is a dynamic language so you can deal with both client and server in an interactive mode. Open two Node console, copy the following scripts and paste into the each console.
Client
var vibe = require("vibe-protocol");
var client = vibe.client();
var socket = client.open("http://localhost:8080");
socket.on("open", function() {
console.log("socket");
});
Once socket
have been logged, you can access the opened socket by socket
in the console.
socket.on("greeting", function(data) {
console.log("greetings from the server:", data);
});
Server
var vibe = require("vibe-protocol");
var server = vibe.server();
var httpServer = require("http").createServer();
var sockets = [];
httpServer.on("request", server.handleRequest);
httpServer.on("upgrade", server.handleUpgrade);
httpServer.listen(8080);
server.on("socket", function(socket) {
console.log("sockets[", (sockets.push(socket) - 1), "]");
});
Once sockets[ 0 ]
have been logged, you can access the opened socket by sockets[0]
in the console.
sockets[0].send("greeting", "Hello World");
Test Suite
Test suite is provided to help write and verify implementation. Tests are written in JavaScript with the help of reference implementation and runs by Mocha, JavaScript test framework, in Node.js.
Testee
To run the test suite, you need to write a testee, a web server which brokers between test and your implementation to be tested. Because through writing testee, you will use most API of your implementation, showing your testee is good for explaining how to use your implementation.
Server Testee
A testee to test server implementation should listen on port 8000
. Here is an example for testing server reference implementation.
Handling HTTP Request
According to the request path:
/alive
- Write
true
orfalse
to the response according to whether a socket specified by the request paramid
is opened and end the response.
- Write
/setup
- According to the request param:
transports
,heartbeat
and_heartbeat
, set up the implementation and end the response.
- According to the request param:
/vibe
- Delegate an exchange of request and response to the implementation without touching it.
Handling Socket
According to the socket event:
echo
- Send
echo
event attaching the given data.
- Send
Testing Extension
According to the extension:
Reply
This extension uses two socket events:
/reply/inbound
- According to the event data's
type
property, execute a resolved callback if that type isresolved
and a rejected callback if that type isrejected
withdata
property of the given data as returning value.
- According to the event data's
/reply/outbound
- According to the event data's
type
property, send atest
event withdata
property of the given data as data attaching a resolved callback if that type isresolved
and a rejected callback if that type isrejected
. In both callbacks, when the value is returned, it should send adone
event with that value as data.
- According to the event data's
Client Testee
A testee to test client implementation should listen on port 9000
. Here is an example for testing client reference implementation.
Handling HTTP Request
According to the request path:
/alive
- Write
true
orfalse
to the response according to whether a socket specified by the request paramid
is opened and end the response.
- Write
/open
- Make the implementation connect to the server setting URI to the request param
uri
, transport to the request paramtransport
, heartbeat to the request paramheartbeat
orfalse
if not exists and _heartbeat to the request param_heartbeat
orfalse
if not exists.
- Make the implementation connect to the server setting URI to the request param
Handling Socket
According to the socket event:
abort
- Close the socket.
echo
- Send
echo
event attaching the given data.
- Send
Testing Extension
According to the extension:
Reply
This extension uses two socket events:
/reply/inbound
- According to the event data's
type
property, execute a resolved callback if that type isresolved
and a rejected callback if that type isrejected
withdata
property of the given data as returning value.
- According to the event data's
/reply/outbound
- According to the event data's
type
property, send atest
event withdata
property of the given data as data attaching a resolved callback if that type isresolved
and a rejected callback if that type isrejected
. In both callbacks, when the value is returned, it should send adone
event with that value as data.
- According to the event data's
Running Test
First you need to install Node.js. Then create a package.json
in an empty directory:
{
"devDependencies": {
"vibe-protocol": "3.0.0-Alpha3",
"mocha": "2.0.1",
"chai": "1.9.2",
"minimist": "1.1.0"
}
}
And type npm install
to install modules locally and npm install mocha -g
to install Mocha globally for convenience. Then, run your testee and execute mocha
passing the following arguments:
--vibe.transports
- A set of transport to be tested in a comma-separated value.
--vibe.extension
- A set of extension to be tested in a comma-separated value.
Testing a client which implements ws
, sse
and longpollajax
transports.
mocha ./node_modules/vibe-protocol/test/client.js --vibe.transports ws,sse,longpollajax
Testing a server which implements ws
transport and reply
extension.
mocha ./node_modules/vibe-protocol/test/server.js --vibe.transports ws --vibe.extension reply
Note
- Because Node.js is small and can be installed locally, you can automate the protocol test programmatically by downloading and installing Node.js, installing modules through npm, running tests through spawning a process and checking that process' exit code that is the number of failed tests.