MSE protocol

version: 1.0

This protocol is used by media server engine (MSE) and clients for communication. Protocol is based on JSON RPC 2.0.

Example usage

• Install package using NPM:

npm i --save mse-proto

const WebSocket = require('ws')
const proto = require('mse-proto')
const RequestFactory = proto.RequestFactory
const ResponseAdapter = proto.ResponseAdapter

const wss = new WebSocket(`wss://mse:443/`)

wss.on('open', (ws) => {
  wss.send(RequestFactory.ping())
})
wss.on('message', (response) => {
  if (ResponseAdaptor.ping(response)) {
    console.log(response)
  }
})

Messages

• ping
• authentication
• star
• whoami
• iceCandidate
• sdpOffer
• disconnect

Errors

• Invalid json object
• Method not found
• Invalid method parameter
• Invalid json rpc 2.0 object
• Authentication failure
• Unauthorized access
• Invalid call order

ping

• ping server. Method can be used as heartbeat.

ping request (client)

{
  "id": 1,
  "method": "ping",
  "jsonrpc": "2.0"
}

ping success response (server)

{
  "id": 1,
  "result": "pong",
  "jsonrpc": "2.0"
}

authentication

authentication request (client)

• A JWT token is used for authentication. Subsequent calls do NOT need the token.

{
  "id": 2,
  "method": "auth",
  "jsonrpc": "2.0",
  "params": {
    "token": "appropriate jwt token",
    "version": "1.0"
  }
}

authentication success response (server)

{
  "id": 2,
  "jsonrpc": "2.0",
  "result": "authenticated"
}

start

start request (client)

• This method is available only to authorized clients.
• Starts video service.

{
  "id": 3,
  "method": "start",
  "jsonrpc": "2.0"
}

start success response (server)

{
  "id": 3,
  "jsonrpc": "2.0",
  "result": "started"
}

whoami

whoami request (client)

• Available in development environment only.
• This method is available only to authorized clients.

{
  "id": 4,
  "method": "whoami",
  "jsonrpc": "2.0"
}

whoami success response (server)

{
  "id": 4,
  "jsonrpc": "2.0",
  "result": {
    "domain": "domain",
    "agent": "web or mobile",
    "role": "user - admin or super",
    "userId": "random string",
    "roomId": "random string",
    "ipAddress": "client ip address",
    "tokenIssued": "date the token is issued",
    "validFrom": "token is valid from date",
    "validTo": "token is valid to date"
  }
}

iceCandidate

iceCandidate request (client & server)

• This method is available only to authorized clients.
• This method is a notification. Server does NOT respond to it and client should not too.

{
  "id": null,
  "method": "iceCandidate",
  "jsonrpc": "2.0",
  "params": {
    "candidate": "ice candidate value"
  }
}

sdpOffer

sdpOffer request (client & server)

• This method is available only to authorized clients.
• This method is a notification. Server does NOT respond to it and client should not too.

{
  "id": null,
  "method": "sdpOffer",
  "jsonrpc": "2.0",
  "params": {
    "offer": "sdp offer value"
  }
}

disconnect

disconnect request (client)

• This method is available only to authorized clients.
• This method is a notification. Server does NOT respond to it.

{
  "id": null,
  "method": "disconnect",
  "jsonrpc": "2.0"
}

Chat message (client & server)

• NOT IMPLEMENTED
• This method is available only to authorized clients.
• This method is a notification. Server does NOT respond to it and client should not too.

{
  "id": null,
  "method": "chat",
  "jsonrpc": "2.0",
  "params": {
    "to": [],
    "message": "message",
    "attachment": "object"
  }
}

Errors

Invalid json object

{
  "id": null
  "jsonrpc": "2.0",
  "error": {
    "code": -32700,
    "message": "Parse error"
  }
}

Invalid json rpc 2.0 object

{
  "id": null
  "jsonrpc": "2.0",
  "error": {
    "code": -1001,
    "message": "Invalid json rpc 2.0 object"
  }
}

Method not found

{
  "id": "related request id",
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

Invalid method parameter

{
  "id": "related request id",
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params"
  }
}

Authentication failure

{
  "id": "related request id",
  "jsonrpc": "2.0",
  "error": {
    "code": -4001,
    "message": "Authorization Failed"
  }
}

Unauthorized access

• Accessing a protected method before authorization.

• Available methods before authentication:

  • ping
  • auth

{
  "id": "related request id",
  "jsonrpc": "2.0",
  "error": {
    "code": -5001,
    "message": "Unauthorized Access"
  }
}

Invalid call order

• Calling a method before calling required methods before it.

{
  "id": 3,
  "jsonrpc": "2.0",
  "error": {
    "code": -6001,
    "message": "Invalid Call Order",
    "data": {
      "required": "Required Method"
    }
  }
}