jsongle-server v2.0.1

JSONgle-Server

JSONgle-Server is a WebRTC signaling server allowing users to have WebRTC calls. The signaling protocol used is based on JSONgle which uses JSON to describe the messages exchanged.

JSONgle-Server allows to

• Connect clients to a dedicated room
• Handle room 'joined' and 'left' events
• Handle WebRTC signaling protocol between members of a room
• Handle custom JSON messages between members of a room
• Handle chat messages between members of a room
• Handle audio & video conference (planned)

Install

JSONgle-Server is a Node.JS server that can be installed by cloning the repository.

$ git clone https://github.com/oanguenot/JSONgle-Server

Then you need to install the dependencies

$ yarn install

or

$ npm install

Configuration

JSONgle-Server reads its configuration from an .env file or directly from any environments variables set. See file .env.defaults for the default values used.

The following variables can be set

Note: appToken value is sent by the client and verified by JSONgle-Server when initiating the connection.

Start JSONgle-Server

For testing purpose or in your development/integration environment, you can launch the following command:

$ yarn dev

or 

$ npm run dev

The server will be automatically restarted thanks to nodemon.

Main principles

JSONgle-Server has two 'end-points':

• A REST API used to monitor the server

• A WebSocket server that listens to incoming WebSocket connections and handle the signaling part

Monitoring JSONgle-Server

Basically, JSONgle-Server offers the following APIs:

• GET /about: This API returns a JSON description of the server containing the version used and a description

• GET /ping: This API returns the code HTTP 200OK if the server is up

• PUT /logs/levels: This API expects a JSON object containing a level property for updating the log level. Expected values are as usual: debug, info, etc...

• GET /metrics: This API returns a Prometheus metrics when requested.

• GET /stats: This API returns the statistics (Prometheus) in JSON

• GET /tests: This API does a self-check and returns the code 200OK in case of success

These APIs allow to monitor the JSONgle-Server in real-time.

Serving the signaling part

For exchanging the signaling part, client should be connected to the WebSocket and exchange formatted messages that follow the JSONgle protocol.

Here are the messages handled by the server in some specific situations.

Websocket connection

JSONgle-Server uses Socket.IO for handling the connection coming from the client.

To be accepted, connections should contain an appToken that is checked by JSONgle-Server.

// Somewhere in your client application
import {io} from "socket.io-client";

const SERVER_URL = "...";

socketIO = io(SERVER_URL, {
  auth: {
    appToken: "d371db...733b384"
  }
});

session-hello message

When a connection is set to the WebSocket server, JSONgle-Server sends back to the client the following query

{
  "id": "...",
  "from": "jsongle-server", 
  "to": "8e784de9-ba76-4b0f-bedf-e21cac593f75",
  "jsongle": {
    "action": "iq-get",
    "query": "session-hello",
    "transaction": "8c4feab5-71a0-41c6-8bcd-e21cac593f75",
    "description": {
      "version": "1.1.4",
      "sn": "jsongle-server",
      "info": "Easy signaling using JSONgle-Server"
    }
  }
}

to is the user identity.

The client should answer by the following message

{
  "id": "...",
  "from": "8e784de9-ba76-4b0f-bedf-e21cac593f75", 
  "to": "jsongle-server",
  "jsongle": {
    "action": "iq-result",
    "query": "session-hello",
    "transaction": "8c4feab5-71a0-41c6-8bcd-e21cac593f75",
    "description": {
      "uid": "user_7000",     
      "dn": "Jon Doe"         
    }
  }
}

uid should be the unique identifier of the user. dn is optional.

An ack message is then sent to the client to inform him that the answer has been received and handled. A status success or failed is contained in that message to have a result if needed. In case of error, an additional session-error message is sent too that describes the error.

Note: Next client requests will be treated only if client has sent this iq-result response.

Join a room for a P2P call or a P2P instant messaging conversation

To join a room for having a call or an instant messaging conversation, the client should send the following message

{
  "id": "9b2feab5-71a0-41c6-8bcd-de67b819fdca",
  "from": "8e784de9-ba76-4b0f-bedf-e21cac593f75", 
  "to": "jsongle-server",  
  "jsongle": {
    "action": "iq-set",
    "query": "session-join",
    "namespace": "room",
    "description": {
      "rid": "43784dd3-cb76-4e5f-b4df-354cac5df777" 
    }
  }
}

Where rid is an arbitrary uniq room id known by clients who want to have a call or conversation.

The server answers by an iq_result or an iq_error depending on the result of the operation.

The iq_result contains the list of users already in the room.

All existing members of that room receive a session-event message to inform them about the new member.

Leaving a room

In the same manner, a user can leave a room by sending the following message

{
  "id": "9b2feab5-71a0-41c6-8bcd-de67b819fdca",
  "from": "8e784de9-ba76-4b0f-bedf-e21cac593f75", 
  "to": "jsongle-server",
  "jsongle": {
    "action": "iq-set",
    "query": "session-leave",
    "description": {
      "rid": "43784dd3-cb76-4e5f-b4df-354cac5df777"
    },
  },
}

Join a MUC room

In the same way, joining a MUC room could be done by sending a IQ

{
  "id": "9b2feab5-71a0-41c6-8bcd-de67b819fdca",
  "from": "8e784de9-ba76-4b0f-bedf-e21cac593f75", 
  "to": "jsongle-server",  
  "jsongle": {
    "action": "iq-set",
    "query": "muc-join",
    "namespace": "muc",
    "description": {
      "rid": "43784dd3-cb76-4e5f-b4df-354cac5df777" 
    }
  }
}

Where rid is the id of the MUC room to join.

An iq_result or an iq_error message is sent depending on the result.

All remaining members of that room receive a session-event message to inform them of the leaving of a member.

Handling signalization

Any messages sent to the room is then dispatched to all members (except the emitter) on behalf of the room.

At this time of writing, only P2P room can have video calls (limited to 2 participants), muc rooms could only have messaging conversation.

See JSONgle for the client API.

Prometheus Metrics

JSONgle-Server computes the following metrics:

These metrics are available in the REST API GET /metrics for Prometheus and in API GET /stats in JSON.