HTTP WebSockets

HTTP WebSockets enable two-way communication with HTTP clients

Websockets

Websocket support allows a service to act as a websocket channel that you can connect to from a web-browser.

A get method must be implemented to handle initialization of the websocket. It can supply data object that will be available via event.data.

// Create a websocket if websocket request.
exports.get = function (req) {

  if (!req.webSocket) {
    return {
      status: 404
    };
  }

  return {
    webSocket: {
      data: {
        user: "test"
      },
      subProtocols: ["text"]
    }
  };
};

A websocket event handler named webSocketEvent is required. It will be called for every websocket event from a client. See example below.

// Listen to a websocket event
exports.webSocketEvent = function (event) {

  if (event.type == 'open' && event.data.user == 'test') {
    // Do something on open
  }

  if (event.type == 'message') {
    // Do something on message recieved
  }

  if (event.type == 'close') {
    // Do something on close
  }

};

Event object example:

  {
    "type": "message",  (1)
    "session": {
      "id": "7",   (2)
      "path": "/",   (3)
      "params": {},   (4)
      "user": {   (5)
        "key": "user:system:user",
        "displayName": "User",
        "modifiedTime": "1970-01-01T00:00:00Z",
        "disabled": false,
        "login": "usr",
        "idProvider": "system",
        "email": "email@example.com"
      }
    },
    "data": {   (6)
      "field": "value"
    },
    "error": "",   (7)
    "closeReason":  1000,   (8)
    "message": "Hello World"   (9)
  }

1	Event type. Can be one of `OPEN`, `CLOSE`, `ERROR`, `MESSAGE`.
2	WebSocket session id.
3	Path of the request when WebSocket was opened.
4	Name/value pairs of the query/form parameters from the request when WebSocket was opened.
5	Authenticated user data when WebSocket was opened, if available.
6	Data returned from WebSocket `get` controller.
7	Error message, if available.
8	WebSocket Close reason code, if available.
9	WebSocket message, if available.

Below is an example of a simple chat using the Websocket JS api for sending messages back and adding/removing clients in groups. Adding to groups allows for multicast message sending.

// Lib that contains websocket functions.
var webSocketLib = require('/lib/xp/websocket');

// Listen to a websocket event
exports.webSocketEvent = function (event) {

  if (event.type == 'open') {
    // Send message back to client
    webSocketLib.send(event.session.id, 'Welcome to our chat ' + event.session.user ? event.session.user.displayName : 'anonymous' );

    // Add client into a group
    webSocketLib.addToGroup('chat', event.session.id);

    log.info(`New group size ${webSocketLib.getGroupSize('chat')}`);
  }

  if (event.type == 'message') {
    // Propegate message to group
    webSocketLib.sendToGroup('chat', event.message);
  }

  if (event.type == 'close') {
    log.info(`User left the chat`);
  }

};

HTTP WebSockets

Contents

Websockets

Contents

Contents