verse/verse-javascript

Websocket support for Verse protocol

Verse 2.0

Verse 2.0 is network protocol for real-time sharing of 3D data. It is successor of old Verse protocol developed at KTH. Verse 2.0 is still in alpha version.

License

The source code of Verse library is licensed under BSD license. This library could be used for implementation of Verse client. The source code of Verse server is licensed under GNU GPL 2.0 license. For details look at files BSD-LICENSE and GPL-LICENSE.

Important links

• http://verse.github.io/
• https://github.com/verse/verse

Compile

Compilation of Verse 2.0 is tested only on Linux now. Some libraries and development tools are required. Porting to other UNIX like OS should be possible. Support for Mac OS X and other BSD like UNIXese is only experimental.

Requirements

• GCC http://gcc.gnu.org/ or Clang http://clang.llvm.org/
• CMake http://www.cmake.org/
• OpenSSL (optional) http://www.openssl.org/
• IniParser (optional) http://ndevilla.free.fr/iniparser/
• Check (optional) http://check.sourceforge.net/
• Spin (optional) http://spinroot.com/
• Python3.4 (optional) http://www.python.org/
• Python2.x (optional) http://www.python.org/
• WSLay (optional) https://github.com/jirihnidek/wslay
• MongoDB (optional) https://github.com/mongodb/mongo-c-driver (version 0.81)

Building

To compile Verse server, libverse.so and example of Verse client open terminal, go to root of verse source code and type:

$ mkdir ./build
$ cd ./build
$ cmake ../
$ make
$ sudo make install

If you want to build debug version, then you have to run cmake with following parameter:

$ cmake -DCMAKE_BUILD_TYPE=Debug ../

If you want to build Verse with Clang, then you have to do more

$ export CC=/usr/bin/clang
$ export CXX=/usr/bin/clang++
$ mkdir ./build
$ cd ./build
$ cmake ../
$ make
$ sudo make install

Folders

• ./config is directory with example of users.csv file
• ./doc contains doxyfile for generated doxygen documentation
• ./example contains source code of example Verse clients
• ./include contains all .h files
• ./pki contains example of certificate and private key
• ./src contains source code
• ./lib source code for library (used by client as well by server)
• ./lib/api source code of API
• ./lib/client source code specific for Verse clients
• ./lib/common source code shared with Verse server and Verse client
• ./server source code specified for Verse server
• ./server/mongodb source code used for saving and loading data from MongoDB
• ./python contains source code for Python module implemented in C
• ./unittests contains source code of unit tests

Installation

The verse server and example of verse client is not necessary to install to the system. Before you want to run Verse server you should edit your "database" of users. Go to the ./config folder and edit users.csv:

$ cd ./config

and edit user.csv with your favorite text editor, e.g. vim:

$ vim users.csv

Using

The Verse server can be executed from build directory:

$ ./bin/verse_server

Example of Verse client could be executed from this directory too:

$ ./bin/verse_client localhost

The example of Verse client and Verse server can be started with several arguments. For more details run programs with '-h' option.

When you want to try test Verse client implemented Python, then you have to set up system variable PYTHONPATH to include directory containing Python module "verse.so" :

$ export PYTHONPATH=/path/to/directory/with/verse/module

Then it is possible to run this client:

$ python3 verse_client.py

MongoDB

It is possible to use Verse server without support of MongoDB, but all data are stored only in memory and when server is stopped, then all data are lost. For production purpose it is recommended to configure using MongoDB in server.ini file. Implementation of MongoDB is currently limited, because Verse server load all data to memory during start and saves all data to MongoDB, when server is stopped.

Firewalls

If you use firewall and you want to connect on Verse server, then you will need to open several ports. The Verse server listen on TCP port 12345 and it negotiate new UDP ports in range: 20000 - 20009 (this port numbers and port ranges will be possible to change in configuration files in the future).

When you use Linux OS, then you can use iptables for it. You should be familiar with iptables. If not, then read some documentation about iptables first. To open TCP port use something like this:

$ iptables -I INPUT 10 \ # this add this rule before 10th rule (change this!)
  -m state --state NEW \ # use this rule only for the first packet (optional)
  -s 1.2.3.4/16 \        # allow connection only from some subnet (optional)
  -p tcp --dport 12345 \ # own opening of TCP port 12345
  -j ACCEPT              # accept this packet

To open UDP port in range 50000 - 50009 use something like this:

$ iptables -I INPUT 11 \
  -m state --state NEW \
  -s 1.2.3.4/16 \
  -p udp --dport 50000:50009 \ # open UDP ports in range: 50000 - 50009
  -j ACCEPT

Verse server and all verse client can use IPv6. Configuration of ip6tables is very similar:

$ ip6tables -I INPUT 10 \
  -m state --state NEW \
  -p tcp --dport 12345 \
  -j ACCEPT

$ ip6tables -I INPUT 11 \
  -m state --state NEW \
  -p udp --dport 50000:50009
  -j ACCEPT

Verification

Main parts of Verse protocol were verified using Promela programming language and tool called Spin. For more details go to the directory ./misc/promela.

Testing

If you want to test Verse library, then you have to compile Verse with support for unit test framework called Check and then you can perform several unit tests. To run unit tests you have to go to the build directory and run make with target test:

$ cd ./build
$ make test

Contacts

• IRC: irc.freenode.net in channel #verse
• Mailing list: [email protected]
• Main developer: Jiri Hnidek
• E-mail: [email protected]
• Phone: [phone]
• Address: Studentska 2, 461 17, Liberec 1, Czech Republic

verse-javascript's Issues

Error in Tag Set String

Command tag_set_string8 doesn't work properly, because I can see only first letter of string value on console:

Object { CMD: "TAG_SET_STRING8", SHARE: 0, NODE_ID: 65541, TAG_GROUP_ID: 0, TAG_ID: 0, VALUE: "S" },

but server prints this and it sends whole string:

Tag_Set_String8, Node_ID: 65541, TagGroup_ID: 0, Tag_ID: 0, Value: Scene

Add Support for Sending Tag Commands

Add support for sending all tag commands: https://github.com/verse/verse/wiki/Specification-of-Tag-Commands without compression:

• Tag Create
• Tag Destroy
• Tag Set Value

Send More Commands in One Message

Each command is sent in separate Message. It is not effective. Period of sending message should be dependent of FPS of client web application.

Add Support for Prioritization of Commands

When issue #7 will be finished, then it will be feasible to add support for prioritization of commands.

Implement Support for Node Commands

Implement support for node commands. Specification of Node commands is described in this document:

• https://github.com/verse/verse/wiki/Specification-of-Node-Commands

It is not necessary to add support for command compression.

Add Support for Sending TagGroup Commands

Add support for sending all tag group commands: https://github.com/verse/verse/wiki/Specification-of-Tag-Group-Commands without compression:

• TagGroup Create
• TagGroup Destroy
• TagGroup Subscribe
• TagGroup UnSubscribe

Add Support for Command Compression

• Add support for negotation of command compression.
• Add suppport for receiving compressed commands
• Add support for sending compressed commands. It is related to issue: #7

Add Support for Sending Layer Commands

Add support for sending all layer commands: https://github.com/verse/verse/wiki/Specification-of-Layer-Commands without compression:

• Layer Create
• Layer Destroy
• Layer Subscribe
• Layer UnSubscribe
• Layer UnSet Data
• Layer Set Data

Issues with connection errors

When client tries to connect and connection can not be established or connection is terminated, then no callback function is called. Thus developer of client can not provide any feedback to user, what is wrong. Try to handle following situations:

• Verse server is not running, but client tries to connect to this server.
• Client sent wrong username or password.
• Server was terminated.

Finish Handshake of Connection

Finish implementation of handshake of connection as is described in specification:

https://github.com/verse/verse/wiki/WebSocket-Variant

Javascript & Unittests & Travis CI & Coveralls

Javascript unittest should be executed at Travis CI and coverage of unittest could be uploaded to Coveralls.

• Travis CI and Javascript: http://docs.travis-ci.com/user/gui-and-headless-browsers/
• Coveralls and Javascript https://coveralls.io/docs/javascript

I can help with cmake/make stuff, but I need to know, what commands should be executed.

Add Support for Sending Node Commands

Add support for sending all node commands: https://github.com/verse/verse/wiki/Specification-of-Node-Commands without compression:

• Node Create
• Node Destroy
• Node Subscribe
• Node UnSubscribe
• Node Link
• Node Perm
• Node Umask
• Node Owner
• Node Lock
• Node UnLock
• Node Prio