ankit-iiita2006 / koa-websocket

Light wrapper around Koa providing a websocket middleware handler that is koa-route compatible.

koa-websocket

Installation

npm install koa-websocket

Usage

Server:

const koa = require('koa'),
  route = require('koa-route'),
  websockify = require('koa-websocket');

const app = websockify(koa());

/**
 * We define a route handler for when a new connection is made.
 * The endpoint can be anything you want the client to connect to.
 * If our WebSocket server address is `ws://localhost:3000` and our route is `/`,
 * this will handle any new WebSocket connections to `ws://localhost:3000/`.
 * If our route was `/test`, the handler would fire only when
 * a connection was made to `ws://localhost:3000/test`.
 */
app.ws.use(route.all('/', function* (next) {
  /**
   *`this` refers to the context in the `app.ws` instance, not `app`. `app` and `app.ws` use separate middleware/contexts.
   * to access a middleware's context here, you must pass the middleware to `app.ws.use()`.
   */
   
   // the websocket is added to the context as `this.websocket`.
  this.websocket.on('message', function(message) {
    // print message from the client
    console.log(message);
  });
  
  // send a message to our client
  this.websocket.send('Hello Client!');

  // yielding `next` will pass the context (this) on to the next ws middleware
  yield next;
}));

app.listen(3000);

Client: Here is a simple client using the WebSockets API, which is built-in to the browser. (Make sure you check that your browser version supports it.)

/**
 * See "Writing WebSocket client applications" on MDN for more:
 * https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications
 */
const socket = new WebSocket('ws://localhost:3000/');
socket.onopen = function (event) {
  // send a message to the server
  socket.send('Hello server!');
};

socket.onmessage = function (event) {
  // print message from server
  console.log(event.data);
};

Sharing middleware between Koa and WebSockets

To use middleware in WebSockets, the middleware must be passed in to app.ws.use(). Passing your middleware only to app.use() will not make it available in WebSockets. You can share your middleware between Koa and WebSockets by passing an instance of the middleware to both app.use() and app.ws.use().

The following example shows how to share a session store with WebSockets.

Example: Sharing a session store

const koa = require('koa'),
  route = require('koa-route'),
  session = require('koa-session'),
  websockify = require('koa-websocket');

const app = websockify(koa());

var sessionStore = session(app);

// pass the session store middleware to both the app and app.ws
// to share it between Koa and websockets
app.use(sessionStore);
app.ws.use(sessionStore);

app.ws.use(route.all('/', function* (next) {
  // `this` context now contains `this.session`
  console.log(this.session); // prints the Koa session object
  yield next;
}));

app.listen(3000);

Accessing the this.websocket instance in the Koa app

If you'd like to access the WebSocket instance from Koa using this.websocket, we need to add the this.websocket context to our Koa app from inside our WebSockets handler.

app.ws.use(route.all('/', function* (next) {
  // access the main Koa app's context via `app.context`.
  // Here we add `this.websocket` from our WebSockets context to the main Koa app's context.
  // It will then be available in Koa's context via `this.websocket`.
  app.context.websocket = this.websocket;
  yield next;
}));