reflector

Orca Reflector and demo application

Developer manual

Contents

1. Introduction.

2. Quick start.

3. Reflector.

a. Installation and configuration.

b. Reflector protocol

4. Orca Transport Library for Reflector.

5. Demo application.

1. Introduction

Orca.js is a JavaScript API for supporting Real Time Communications (RTC) in web applications. Orca.js abstracts the implementation of RTC from the application allowing application code to be portable accross different RTC providers. For more information go to:

• www.orcajs.org
• github.com/orcajs/orca.js

This reflector project is an implementation of the Orca API for development, testing and experimentation purposes. It is designed to support 2 party calls between endpoints on a secure LAN. The reflector, as provided here, is not intended to be used on the Internet or in any other kind of real applications. It does not provide good support for security or robustness features that would be required in real deployments.

The reflector project is a complete client/server demo application highlighting the value of Orca API. It also provides a tool for testing Orca applications in a local environment. The demo application enables a 2 party audio/video calls in a browser using the Orca API.

This demo application relies on:

• a signaling server (so called Reflector) based on NodeJS,
• a transport library, which an implementation of the Orca API dedicated to the reflector protocol,
• a simple example client application, which is a basic chat UI relying on the transport library.

The Reflector can be deployed in any environment, the only constraint being to be reachable by the clients. The client application can run in any WebRTC compatible browser. It may run locally on the user’s desktop or hosted remotely on a webserver.

This manual will give a description of the 3 components and the way to get them configured and working in your environment.

2. Quick start

To setup and see the demo running before understanding the role of each component, you can run the following commands for a quick start.

Install NodeJS (pick installation package adapted to your OS at http://nodejs.org/download/

$ git clone https://github.com/orcajs/reflector

$ cd reflector

$ npm install

$ sudo npm start    (sudo is require for port below 1024, or admin privileges on other OS)

Note that if you are behind a corporate proxy, your Git or GitHub client and npm have to be configured with the proxy URL
On Windows systems, a bug on NPM requires to manually create the 'C:\Users\user_id\AppData\Roaming\npm folder if you meet the NOENT error

You can access the demo client by going to http://server IP:443/reflector.htm, where server IP is the IP address/server name where nodeJS has been installed.

3. Reflector

The Reflector server is a nodejs component. Find and install the appropriate version for your operating system from http://nodejs.org/download/

a. Installation and configuration

The reflector server can be retrieved from the dedicated GitHub project

$ git clone https://github.com/orcajs/reflector

Go to the directory containing the retrieved copy of the Reflector and install it with Node Packet Manager

$ npm install

Note that if you are behind a corporate proxy, your Git or GitHub client and npm have to be configured with the proxy URL
On Windows systems, a bug on NPM requires to manually create the 'C:\Users\user_id\AppData\Roaming\npm folder if you meet the NOENT error

You can check that be server works by starting it and ckecking the “out.log” file.

$ sudo node reflector.js

The server IP port can be configured in the config.js file. npm can also be used to start the server as daemon.

$ sudo npm start

Note that the reflector is only intended to be used in testing environments where security and scaling are not practical issues. The reflector does not provide any security features.

b. Reflector protocol

The Reflector is a minimal signaling server that uses WebSocket and JSON elements to exchange messages.

Using WebSocket, each client must register a session on the serverwith its own user id:

{'method': 'register', 'from': 'myId'}

In case of success, a 200 ok is sent back:

{'method': 'REGISTER/200/OK'}

In case of failure, an error is sent back:

{'method': 'REGISTER/400/no-from'}

Once registered, clients can setup a call through a session invitation dialog. Each message MUST have a to, from and method fields:

{'method': 'INVITE', 'from': 'myId', 'to': 'otherId', 'sdp': 'SDP stuff'}

{'method': 'INVITE/200/OK', 'from': 'otherId', 'to': 'myId', 'sdp': 'SDP stuff'}

The client is automatically unregistered if its WebSocket connection get closed (closing of the browser, connection cut by a proxy, network failure …).

4. Orca Transport Library for Reflector

Implementing the Orca API, a dedicated transport library is available implementing the Reflector protocol.

The transport library can be retrieved from the dedicated GitHub project

$ git clone https://github.com/orcajs/reflector

In order to be used, the transport library inside directory www/orca/ has to be integrated in a client application. This application first has to start the library with a configuration pointing to the reflector URL (e.g. ws://reflector.ip:port)

sessionConfig = {

            uri: <uri of the reflector>

            provider: orcaReflector,

            mediatypes: 'audio,video',

            hostilityhelper: {iceServers: [ {…}, {…} ]}

        };

session = orca.createSession(userId, 'password', sessionConfig);

It is then up to the client application to implement Orca API calls and callbacks and to map then to the client UI and user interactions

The sessionConfig contains a “hostilityhelper” parameter that may be useful to setup calls through network hostilities (NAT, firewall, …). You may need 2 different things:

- A STUN server to go through NATed networks

- A TURN server to additionally go through proxy and firewalls

The hostilityhelper parameter may then be provided this way

Hostilityhelper: { “iceServers”: [ {‘url’:’stun:mystun.com:1234’], [ ‘url’:’turn:myturn.com:5678’] }

5. Demo application

To allow developers to see the benefits of the transport library, a demo client application is provided. It offers a basic UI allowing to:

• Register a user session,
• Establish a 2-way call,
• Configure the different parameters available in the transport library.

The client application can be retrieved from the dedicated GitHub project inside the www directory.

$ git clone https://github.com/orcajs/reflector

It may be run in any WebRTC compatible browser (latest Chrome and Firefox typically). The client page may run locally from your desktop (file://reflector.htm) with Firefox or remotely hosted by a web server with Firefox and Chrome.