Enslavism
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:
Class: MasterConnection
new MasterConnection(masterWsUrl)
let masterCon = '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;
Event: 'slaveremoved'
slaveCo
: SlaveConnection
Triggered when a slave is removed from the slave list. Calling any of slaveCo
's methods won't work.
masterCon;
Class: SlaveConnection
Event: 'rejected'
Triggered when a slave the client attempted to connect to rejected the connection.
slaveCo;
slaveConnection.connect()
Connect to a slave.
slaveConnection.close()
Close the connection. It can be reopened by calling slaveConnection.connect()
again.
Note that all the DataChannel
s 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;
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 = Master; let myMaster = 8080; // creates master listening on port 8080
const Master = Master http = ; let myServer = http;myServer; let myMaster = myServer;
Event: 'slaveauth'
authData
: Objectreject
: 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;
Event: 'clientauth'
authData
: Objectreject
: 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;
Event: 'slaveconnection'
ws
: WebSocket
Triggered once a slave is connected.
myMaster;
Event: 'clientconnection'
ws
: WebSocket
Triggered once a client is connected.
myMaster;
Event: 'error'
err
: Error
Triggered when an error occurs on the underlying server.
myMaster;
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.
'ws://localhost:8081' name: 'my slave server' connectedAmount: 16;
Event: 'offer'
reject
: Function
Triggered each time a client wants to connect.
If reject
is called, the connection will be rejected.
slave;
Event: 'connection'
clientCo
: enslavism.ClientConnection
Triggered each time a client connects.
slave;
Class: enslavism.ClientConnection
Event: 'datachannel'
dc
: DataChannel
Triggered each time a client creates a datachannel.
clientCo;