About

Corrade implements an RFC6455 compatible WebSockets server via which notifications can be received and commands sent. Activating the WebSockets server can be done using Nucleus or by editing the configuration file Configuration.xml.

WebSockets provide a lightweight alternative to the TCP server and fills the technology gap between MQTT and HTTP by providing a client-side solution for stateful connections. WebSockets allow the user to interact with Corrade directly from a web browser without having to run a standalone program such as node.js or script using PHP.

Interacting with Corrade via WebSockets

The functionality is rather simple to comprehend:

Corrade starts a WebSockets server listening on a configurable URL (by default: ws://0.0.0.0:8088/)
a browser opens a connection to the Corrade WebSockets URL postfixed with the group name, the group password and a list of notifications to receive (ie: ws://corrade.local/My SL Group/mypassword/local,message)
if the authentication is successful, the browser can then receive the desired notifications (in this example, the local and message notification) and also send commands.

An example script which consists in just a HTML page is the following:

<!DOCTYPE HTML>
 
<html>
   <head>
 
      <script type = "text/javascript">
         function WebSocketTest() {
 
            if ("WebSocket" in window) {
               alert("WebSocket is supported by your Browser!");
 
               // Let us open a web socket
               var ws = new WebSocket("ws://localhost:8088/My SL Group/mypassword/local,message");
 
               ws.onopen = function() {
 
                  // Web Socket is connected, send data using send()
                  ws.send("command=version&group=My SL Group&group=mypassword");
                  alert("Message is sent...");
               };
 
               ws.onmessage = function (evt) { 
                  var received_msg = evt.data;
                  alert("Message is received: " + received_msg);
               };
 
               ws.onclose = function() { 
 
                  // websocket is closed.
                  alert("Connection is closed..."); 
               };
            } else {
 
               // The browser doesn't support WebSocket
               alert("WebSocket NOT supported by your Browser!");
            }
         }
      </script>
 
   </head>
 
   <body>
      <div id = "sse">
         <a href = "javascript:WebSocketTest()">Run WebSocket</a>
      </div>
 
   </body>
</html>

Upon clicking the Run WebSocket text, the JavaScript code will establish a connection to ws://localhost:8088/My SL Group/mypassword/local,message. Once the connection is established, the command command=version&group=My SL Group&group=mypassword is sent to Corrade. Upon receiving the command, Corrade will respond with the current bot version. Similarly, whenever local chat occurs or an instant message is received by Corrade, the JavaScript code will popup a window with the notification data.

Using Node.JS

The following node.js script is a test harness that connects to Corrade's WebSocket server and subscribes to the local and message notifications. The script also emulates a CLI such that commands can be written on the command line depending on whatever language Corrade is set to use (ie: WAS or JSON).

To use the template, save the script to a file and issue the commands:

npm install websocket readline

to install the necessary packages.

Finally, edit the script to change the group, password and URL to Corrade's WebSocket server.

#!/usr/bin/env node
const os = require('os')
const WebSocketClient = require('websocket').client
const readline = require('readline')
const rl = readline.createInterface(process.stdin, process.stdout)
 
var client = new WebSocketClient()
 
client.on('connectFailed', function (error) {
    console.log('Connect Error: ' + error.toString())
})
 
client.on('connect', function (connection) {
    console.log('Good day!')
    connection.on('error', function (error) {
        console.log("Connection Error: " + error.toString())
    })
    connection.on('close', function () {
        console.log('Connection Closed')
    })
    connection.on('message', function (message) {
        if (message.type === 'utf8') {
            console.log(os.EOL + message.utf8Data)
        }
    })
 
    rl.setPrompt('Command> ')
    rl.prompt()
    rl.on('line', (line) => {
        if (!connection.connected) {
            return
        }
        connection.sendUTF(line)
        rl.prompt()
    }).on('close', () => {
        console.log('Be vigilant!')
        process.exit(0)
    })
})
 
client.connect('ws://localhost:8088/My Group/mypassword/local,message')

Security

Since private data is exchanged between Corrade and the browser, the built-in Corrade WebSockets server allows a certificate to be used. The certificate setup is similar to the certificate for the TCP server and the path to the certificate can changed in the configuration file Configuration.xml. With a certificate added, the protocol URL prefix can be changed to wss:// in order to establish a secure WebSockets connection.

Table of Contents

About

Interacting with Corrade via WebSockets

Using Node.JS

Security

Index