webrtc-signalling-middleware v0.9.0
webrtc-signalling-middleware
This package provides mountable middleware for single server express apps, which provides everything you need server side to do signalling for p2p webrtc experiments. The goal is to make it easier to play with webrtc on glitch.com. Take a look at the webrtc-signal-client package for a simple client to this service.
Usage:
const express = require('express')
const app = express()
const signalling = require('webrtc-signalling-middleware')
const peers = signalling()
app.use('/webrtc', peers)
// listen for requests :)
const listener = app.listen(process.env.PORT, () => {
console.log(`Your app is listening on port ${listener.address().port}`)
})
Constructor options
- presence: boolean, (default true) should the signalling service tell clients which other nodes are connected?
- idLength: integer, (default 16) how many characters should the client ID numbers contain? each character adds around 6 bits of randomness to the ID. Should be long enough to statistically avoid collisions. At 16 digits it's a 96 bit number.
- timeout: integer, (default 10000 = 10s) milliseconds service should wait before deciding a client has expired and disconnected
API
The middleware exposes several potentially useful features:
peers.getPeerList()
Returns an array of peer ID strings currently considered to be connected to the service. This also expires any peers that have timed out. If you need to clean up the list manually, you might call this at an interval.
peers.sendRaw(peerID, object)
Sends a message to the client over event-stream. This probably shouldn't be used unless you're building a custom client
peers.sendData(peerID, object)
Sends a data message to the client over event-stream. This is recommended for sending extra messages to your clients. With the webrtc-signal-client
package this causes the client.onData
callback to be called, and passed the JSON deserialized object.
peers.broadcastRaw(object)
Sends a message to all connected clients over event-stream. Probably don't use this, use the next one
peers.broadcastData(object)
Sends a data message to all connected clients over event-stream. As with peers.sendData
this will execute an onData
callback if used with the webrtc-signal-client
package.
Web API
Connecting to this middleware with a custom client is pretty simple. Here's the basic flow:
- GET
/path/to/middleware/connect
- returns json{"id":"some random ID","key":"some secret key"}
- connect EventSource to
/path/to/middleware/events?id=[id from connect response]&key=[key from connect response]
the EventSource will emit message
events containing JSON, which may contain the following properties:
presence
: an array of peerIDs that are currently connected to the serviceconnect
: an array of new peerIDs that have connecteddisconnect
: an array of peerIDs that were connected but have just disconnected or expireddata
: an object supplied topeer.sendData
orpeer.broadcastData
server sidesignal
: an object sent in by another client using the/send-signal/:to
endpoint described below
To send webrtc signalling information, HTTP POST to /path/to/middleware/send-signal/[destination peerID]
The post body must contain a JSON object:
{
"id": "id number supplied by /connect endpoint",
"key": "key supplied by /connect endpoint",
"signal": <json serializable object>
}
the signal will be passed to the destination peer. If they're temporarily disconnected from the service it will be queued and delivered once they reconnect to /events
or dropped if their connection is expired by timeout. Delivery is not guarenteed.
If your client application is in javascript, make sure to check out the webrtc-signal-client
package for an easy way to hook this up.
4 years ago