UNISYS Architecture

UNISYS Communication Concepts

This document describes the technical implementation details behind the UNISYS remote message invocation system.

UNISYS Capabilities

UNISYS was made to simplify the programming for passing data between javascript modules and remote webapps. UNISYS handles the messy parts, allowing users to define and issue "calls" based on a message string. A UNISYS call handler can return data asynchronously, whether it is defined in a local module or in another webapp on the network (a "remote method"). In UNISYS, the message is the address, and you can dynamically register/unregister messages as needed. With this approach, it is possible to pass data between independent code modules in the same webapp without coupling them directly through object references. The same mechanism works seamlessly across the network.

Network Conventions

The SERVER runs on a single machine on the LAN. It functions as:

• HTTP APPSERVER: distribute WEBAPPs from route /
• HTTP MEDIASERVER: distribute static media files from route /media
• UNISYS NETWORK: accept and relay user message packets from devices on the LAN

Services are implemented using the UNISYS protocol, which is implemented on two dedicated ports for messaging and control purposes.

Control Protocol

(1) The SERVER address and detected IP is passed to the WEBAPP when it's loaded.

(2) The WEBAPP makes a socket connection to the SERVER and activates its message handler, awaiting U_ADDR assignment.

(3) SERVER detects socket connection, and then:

• assigns a unique U_ADDR to socket
• sends a 'NET_CONNECTED' message on socket with U_ADDR

When WEBAPP receives NET_CONNECTED, it can fully participate in UNISYS network communications through the UDATA connection object.

(1) WEBAPP-SERVER CONNECTION

A WEBAPP connecting to UNISYS does so after it has be loaded from SERVER. UNISYS client connection is made immediately on UNISYS.Initialize(), sending IPv4 and scope. There is a single WebSocket from WEBAPP to SERVER.

    SERVER creates WebSocketServer
    ...
    WEBAPP loads, gathers IP and SCOPE
    WEBAPP creates WebSocket and connects to SERVER
        WS.connect(server_addr, unisyscontrol_port)
    ...
    SERVER.WSS.on('connect') ...
    SERVER tags each connecting WEBAPP socket with a unique sockID.
*** socket 'connecting'
    -> SOCKETS.set(sockID,socket)
    ...
    WEBAPP.WS.on('open') ...
    WEBAPP message '_NET_APP_HI', { IPv4, SCOPE }
    ...
    SERVER.WSS.on('message') ...
        sock.U_lastTS = currentTime
        switch (message, packet)
        '_NET_APP_READY' : update sock.U_origin
*** socket 'connected'
        broadcast '_NET_LIST' message

At this point, the regular UNISYS messaging system is running

WEBAPP CONTROL MESSAGES

'_NET_APP_MESSAGES' { list:[], add:[], del:[] }
'_NET_APP_CONTROL' { param:'on'||'off', ... }

SERVER CONTROL MESSAGES

'_NET_LIST' { list:[], add:[], del:[] }

DATA STRUCTURES

/// OBJECTS
    class UAddress    = { sockID, modID, modIDx }; 
    class UMessage    = { mesg, data, mesgID, options }
    // options can enable returns, transactions, etc
    class UCallReturn = { mesgID, seq, returnCall }
    class UCall       = { mesg, handlerFunc, syntax, info }
    
/// SERVER SIDE UNISYS
    var SOCKETS       = new Map(); // key by U_sockID => socket
    var SUBBERS       = new Array; // who gets alerted to control events?
    var MHANDLERS     = new Map(); // key by message => [ UAddress, ... ]
/// CLIENT SIDE UNISYS
    var PENDING       = new Map(); // key by message => 

TRANSACTION DIAGRAM

calling remote method with return value through callback

1. Create UMessage packet with mesg, data
2. Set transaction sequence to 1
3. Create UMessage identifier based on UMessage packet ID
4. Save callback in map, key by UMessage identifier
5. Send packet to SERVER
6. SERVER retrieves list of sockets that implement message
7. SERVER sends data to REMOTE implementors over sockets
8. REMOTE receives packet, and dispatches to local handler
9. local handler handles message, and returns packet
10. SERVER receives returned packet and sends to originating caller
11. caller receives returned packet, looks up UMessage identifier to get the original callback handler, and sends it the new data.