enslavism

    0.9.0 • Public • Published

    Enslavism

    npm version

    A framework to manage distributed WebRTC servers that communicate with browser clients.

    It has been created to be used by JumpSuit. It is generally great for web-based games, but I am sure you will find other uses.

    Basically, you have:

    • a master server (Node.js)
      • knows all slaves and all clients
      • synchronises the slave list across all clients
    • slaves (Node.js)
      • where you handle the business logic of your application (ex: game server)
      • gets WebRTC connection requests from client
    • clients (browser)
      • may request a WebRTC connection to a slave in the slave list

    I recommend reading this blog article to understand the motivation behind Enslavism.

    The point

    • transmitting encrypted data without having to register a SSL certificate (unlike secure WebSockets)
    • configurable reliability (unreliable is fast!)
    • configurable delivery ordering (unordered is fast!)
    • an architecture that allows browser clients to choose which independent server to connect to (useful for games)

    Try the examples

    $ yarn install # or npm install 
    $ yarn watch # or npm run watch 
    $ node examples/master.js # in a second terminal 
    $ node examples/slave.js # in a third terminal 

    Now open your browser at http://localhost:8081/.

    Contributing

    If you modify server code, you have to run node bundler.js to bundle your changes. If you modify client code, the master takes care of re-bundling for you in development environment. In production (i.e. $NODE_ENV is set to production) you have to restart the master.

    Browser API

    You need to include /enslavism/client.js in your HTML document like so:

    <script src="/enslavism/client.js"></script>

    Class: MasterConnection

    new MasterConnection(masterWsUrl)

    let masterCon = new MasterConnection('ws://localhost:8081');

    masterConnection.slaves

    An array of received slaves.

    Event: 'slaveadded'

    • slaveCo: SlaveConnection

    Triggered when a new slave is received. The slave will be available in the slave list.

    masterCon.addEventListener('slaveadded', slaveCo => {
        console.log('new slave', slaveCo);
    });

    Event: 'slaveremoved'

    • slaveCo: SlaveConnection

    Triggered when a slave is removed from the slave list. Calling any of slaveCo's methods won't work.

    masterCon.addEventListener('slaveremoved', slaveCo => {
        console.log('slave has been removed', slaveCo);
        console.log('here was its id', slaveCo.id);
        console.log('here was its userData', slaveCo.userData);
    });

    Class: SlaveConnection

    Event: 'rejected'

    Triggered when a slave the client attempted to connect to rejected the connection.

    slaveCo.addEventListener('rejected', () => {
        console.log('The slave has rejected the connection :-(');
    });

    slaveConnection.connect()

    Connect to a slave.

    slaveConnection.close()

    Close the connection. It can be reopened by calling slaveConnection.connect() again. Note that all the DataChannels that were opened from this SlaveConnection will be closed.

    slaveConnection.createDataChannel(dataChannelName, [dcOptions])

    Create a new data channel. Returns a Promise that resolves with the data channel. Will connect the client if it isn't yet. As connecting takes time, if you are able to anticipate a connection but not which data channel to open, you can call slaveConnection.connect() before.

    slaveCo.createDataChannel('test').then(dc => {
        dc.addEventListener('message', msg => {
            console.log(msg);
        });
        dc.send('What have I wrought!');
    });

    dcOptions is an Object which can contain the following properties. The ordered property is known to work. You might want to check out this upstream issue regarding the other properties.

    Node.js API

    Class: enslavism.Master

    new enslavism.Master(port | httpServer)

    Create an Enslavism master.

    const Master = require('enslavism').Master;
     
    let myMaster = new Master(8080); // creates master listening on port 8080
    const Master = require('enslavism').Master,
        http = require('http');
     
    let myServer = http.createServer((req, res) => {
        res.end('Hello world');
    });
    myServer.listen(8081);
     
    let myMaster = new Master(myServer);

    Event: 'slaveauth'

    • authData: Object
    • reject: Function

    Triggered when a slave wants to connect. By default, the connection is accepted. If reject is called, the connection will be rejected. reject accepts a string as an optional argument which is the reason the connection was rejected.

    authData is the data provided in the slave constructor.

    myMaster.on('slaveauth', (authData, reject) => {
        if (authData.username !== 'getkey' || authData.password !== 'secret') reject('Invalid credentials!');
    });

    Event: 'clientauth'

    • authData: Object
    • reject: Function

    Triggered when a client wants to connect. By default, the connection is accepted. If reject is called, the connection will be rejected. reject accepts a string as an optional argument which is the reason the connection was rejected.

    authData is an object containing the cookies set by the client.

    myMaster.on('clientauth', (authData, reject) => {
        if (authData.username !== undefined) console.log(authData.username + " wants to connect!");
    });

    Event: 'slaveconnection'

    Triggered once a slave is connected.

    myMaster.on('slaveconnection', ws => {
        console.log('Slave connected @', ws._socket.remoteAddress);
    });

    Event: 'clientconnection'

    Triggered once a client is connected.

    myMaster.on('clientconnection', ws => {
        console.log('Client connected @', ws._socket.remoteAddress);
    });

    Event: 'error'

    • err: Error

    Triggered when an error occurs on the underlying server.

    myMaster.on('error', err => {
        console.log(err);
    });

    Class: enslavism.Slave

    new enslavism.Slave(masterWsUrl, userData, [authData])

    Returns a promise that resolves with an enslavism.Slave.

    userData will be available to all clients and can contain any JavaScript value. The optional argument authData in an object containing strings. It may be used to authenticate slaves.

    new enslavism.Slave('ws://localhost:8081', {
        name: 'my slave server',
        connectedAmount: 16
    }).then(slave => {
        console.log('Succesfully connected to the master:', slave);
    }).catch(err => {
        console.log('Couldn\'t connect to the master:', err);
    });

    Event: 'offer'

    • reject: Function

    Triggered each time a client wants to connect. If reject is called, the connection will be rejected.

    slave.on('offer', reject => {
        if (connectedClientAmount > 10) reject();
    });

    Event: 'connection'

    • clientCo: enslavism.ClientConnection

    Triggered each time a client connects.

    slave.on('connection', clientCo => { 
        console.log(clientCo);
    });

    Class: enslavism.ClientConnection

    Event: 'datachannel'

    • dc: DataChannel

    Triggered each time a client creates a datachannel.

    clientCo.on('datachannel', dc => {
        console.log('new dataChannel', dc);
     
        dc.on('open', ev => { // triggered once the datachannel is open
            console.log('data channel open', ev);
            dc.send('hallo welt');
        });
        dc.on('message', msg => { // triggered when receiving a message from a client
            console.log(msg);
        });
    });

    Install

    npm i enslavism

    DownloadsWeekly Downloads

    20

    Version

    0.9.0

    License

    MPL-2.0

    Unpacked Size

    85 kB

    Total Files

    28

    Last publish

    Collaborators

    • getki