Bridge WebSocket messages and Redux actions

Inspired by redux-websocket.

This bridge middleware will:

• Dispatch WebSocket messages into Redux store
• Lift Redux actions to WebSocket

Introduction

WebSocket provides a full duplex connection. On top of request-response model, the server can watch-and-push to the browser continuously. But comparing coding effort between REST and WebSocket, fetching data using REST is much simpler.

We want to reduce the effort to consume APIs exposed thru WebSocket.

By combining WebSocket and Flux architecture (Redux), we found that the coding effort can be dramatically lowered to a level comparable to traditional REST APIs.

Thus, we made Redux WebSocket bridge. It promotes WebSocket messages to a first-class citizen in Flux architecture, enabling front end developers with less knowledge on WebSocket to work with new collaborative and reactive services.

How to use

• Add middleware to your store
• Handle incoming messages in reducer
• Send WebSocket messages thru action

Store: adding middleware

import { applyMiddleware, createStore } from 'redux';
import ReduxWebSocketBridge from 'redux-websocket-bridge';

const createStoreWithMiddleware = applyMiddleware(
  ReduxWebSocketBridge('ws://localhost:4000/')
)(createStore);

export default createStoreWithMiddleware(...);

Tips: you can use namespace to add multiple ReduxWebSocketBridge

Reducer: handling incoming messages

When you receive any WebSocket messages that resembles a Flux Standard Action (FSA) in JSON, it will automatically parsed and dispatched to the store. We call this "unfold".

Server code

When the server send a JSON message that looks like a FSA, it will be automatically unfolded and dispatch to the store.

app.on('connection', socket => {
  socket.write(JSON.stringify({
    type: 'SERVER/GREETING',
    payload: { version: '1.0.0' }
  }));
});

Client code

function reducer(state = {}, action) {
  switch (action.type) {
  case 'SERVER/GREETING':
    // action.meta.webSocket reference to the WebSocket object
    return { ...state, ...action.payload, connected: true };

  default: break;
  }
}

Handling WebSocket events

For WebSocket events, they will be dispatched thru @@websocket/*.

import { OPEN, CLOSE, MESSAGE } from 'redux-websocket-bridge';

function serverConnectivity(state = {}, action) {
  switch (action.type) {
  case `@@websocket/${ OPEN }`:
    state = { ...state, connected: true };
    break;

  case `@@websocket/${ CLOSE }`:
    state = { ...state, connected: false };
    break;

  case `@@websocket/${ MESSAGE }`:
    // Process the raw message here, either string, ArrayBuffer, or Blob
    break;

  default: break;
  }

  return state;
}

Action: sending WebSocket messages

There are two ways to send WebSocket messages:

• Send raw WebSocket message
• Send action as JSON

Sending raw WebSocket message

Payload will be send as-is without modifications. Depends on your WebSocket implementation, you may also send ArrayBuffer or Blob.

For example, to send a message thru Slack RTM API.

import { SEND } from 'redux-websocket-bridge';

function sendHelloWorld() {
  return {
    type: `@@websocket/${ SEND }`,
    payload: JSON.stringify({
      id: 1,
      type: 'message',
      channel: 'C024BE91L',
      text: 'Hello world'
    })
  };
}

Sending action as JSON

You can also opt-in to send any action dispatched to your store thru WebSocket. On the action object, set meta.send to true (or your namespace). When you dispatch the action, the bridge will also JSON.stringify and send a copy of the action to WebSocket.

this.props.dispatch({
  type: 'CLIENT/SIGN_IN',
  meta: { send: true } // or '@@websocket', or a WebSocket object,
  payload: { token: 'my very secret token' }
});

The action dispatched will be sent thru WebSocket similar to the following code. Note the meta.send property is stripped from the message and is not send across the wire.

ws.send(JSON.stringify({
  type: 'CLIENT/SIGN_IN',
  payload: { token: 'my very secret token' }
}));

Tips: you can also use the bridge on server-side to unfold messages back into a Redux store

What-if: if your action is not a FSA-compliant, we will still send it thru. This behavior may change in the future.

Advanced topics

• Use SockJS or other implementations
  • WebSocket APIs used by the bridge
• Prefer ArrayBuffer
• Reconnection logic
• Unfolding actions from multiple bridges
• Delayed connection setup

Use SockJS or other implementations

The bridge supports any libraries that adheres to WebSocket standard, for example, SockJS, which provides fallback for browser/proxy that does not support WebSocket.

const createStoreWithMiddleware = applyMiddleware(
  WebSocketBridge(
    () => new SockJS('http://localhost:3000/ws/')
  )
)(createStore);

WebSocket APIs used by the bridge

Your WebSocket implementation will work on the bridge if they implemented the interface below:

interface WebSocket {
  onopen();
  onclose();
  onmessage(event: { data: string });
  send(data: string);
}

We currently do not process onerror, we might add it in near future.

Prefer ArrayBuffer

This feature is for browser only, it requires FileReader API

WebSocket support binary message. But receiving binary data means you might be receiving either ArrayBuffer or Blob, depends on your WebSocket implementation.

For your convenience, if you set binaryType to arraybuffer in options, we will convert all Blob to ArrayBuffer before dispatching it to Redux store. Because the conversion is an asynchronous operation (using FileReader), it is easier for the bridge to convert it for you.

Vice versa, if you set binaryType to blob, we will convert all ArrayBuffer into Blob.

Reconnection logic

For simplicity, the bridge does not have any reconnection mechanism. But it is easy to implement one, thanks to simple WebSocket API.

To implement your own reconnection logic, you can create a new WebSocket-alike. When disconnected, your implementation will recreate a new WebSocket object, which reconnect to your server. You will be managing the lifetime of WebSocket objects, event subscriptions, and resend backlog.

Although you are recommended to fully implement the WebSocket API, you can check out the subset required by the bridge.

Unfolding actions from multiple bridges

We support multiple bridges. In rare cases, you may want to tag unfolded actions from multiple bridges. You can write a middleware between bridges to tag actions.

const createStoreWithMiddleware = applyMiddleware(
  ReduxWebSocketBridge('ws://localhost:4000/'),
  store => next => action => {
    if (action === 'SERVER/GREETING') {
      action = { ...action, meta: { from: 'server1', ...action.meta } };
    }

    next(action);
  },
  ReduxWebSocketBridge('ws://localhost:4001/'),
  store => next => action => {
    if (action === 'SERVER/GREETING') {
      action = { ...action, meta: { from: 'server2', ...action.meta } };
    }

    next(action);
  },
)(createStore);

For clarity, we did not refactor the sample code.

In this example, we added two middleware to tag all SERVER/GREETING action, adding a meta.from property indicate where the action was from. Note the order of spread/rest property matters, we will not overriding meta.from if it was already defined.

You can refactor the code out and use RegExp for pattern-matching action types.

If this sample does not works for you, please do let us know.

Delayed connection setup

Some services requires calling their REST API before setting up a WebSocket connection, for example, Slack requires a handshake call rtm.connect to get the endpoint for their WebSocket RTM API.

You can create a WebSocket-alike to do the REST API handshake. Once your handshake is done, you can then establish the WebSocket connection. You will need to proxy events before the connection is made. But since the bridge prefer onopen than addEventListener, the effort is minimal.

Options

| Name | Description | Default | | - | - | - | | binaryType | Convert binary to "arraybuffer" or "blob" | null | | namespace | Action prefix for all system messages | "@@websocket/" | | unfold | Unfold messages as actions if they are JSON and look like a Flux Standard Action | true |

Contributions

Like us? Star us.

Something not right? File us an issue.