Simple, easy to use, composable middleware for websocket handling in Koa

Usage

1const Koa = require('koa')
2const websocket = require('koa-easy-ws')
3
4const app = new Koa()
5
6app.use(websocket())
7app.use(async (ctx, next) => {
8  // check if the current request is websocket
9  if (ctx.ws) {
10    const ws = await ctx.ws() // retrieve socket
11
12    // now you have a ws instance, you can use it as you see fit
13    return ws.send('hello there')
14  }
15  
16  // we're back to regular old http here
17  ctx.body = 'general kenobi'
18})

First, you need to pass the koa-easy-ws middleware before the one handling your request. Remember to call it as a function, app.use(websocket()), not app.use(websocket). This sets up on-demand websocket handling for the rest of the middleware chain.

The middleware adds the ctx.ws() function whenever it detects an upgrade request, calling which handles the websocket and returns a ws instance. If not called, regular Koa flow continues, likely resulting in a client-side error.

Features

• No magic. This is a middleware, it doesn't turn your Koa app into a KoaMagicWebSocketServer. It knows its place.
• Integrates ws, one of the fastest and most popular websocket libraries.
• Full composability. Since this is just a middleware, it's not picky on what other libraries you use.
• Minimal, unopinionated 40 SLOC codebase. Seriously, this readme alone contains more code than what's imported into your project. (sorry about the tests though)
• Two dependencies only, and it's the ws library and debug (because apparently logs are not a bad idea). No need for more clutter in your node_modules.

Examples and advanced configuration

You can easily compose koa-easy-ws with a routing library:

1const Koa = require('koa')
2const Router = require('koa-router')
3const websocket = require('koa-easy-ws')
4
5const app = new Koa()
6const router = new Router()
7
8app
9  .use(websocket())
10  .use(router.routes())
11  .use(router.allowedMethods())
12
13router.get('/pow/obi', async (ctx, next) => {
14  if (ctx.ws) {
15    const ws = await ctx.ws()
16    ws.send('chancellor palpatine is evil')
17  }
18})
19
20router.get('/pow/ani', async (ctx, next) => {
21  if (ctx.ws) {
22    const ws = await ctx.ws()
23    ws.send('the jedi are evil')
24    ws.send('404')
25  }
26})

If ctx.ws() isn't enough for you, the websocket server instance is also exposed:

1const Koa = require('koa')
2const websocket = require('koa-easy-ws')
3
4const app = new Koa()
5const websocketMiddleware = websocket()
6const websocketServer = websocketMiddleware.server // this is where the fun begins
7
8app.use(websocketMiddleware) // we already have the instance here
9
10// <insert rest of the app>

This gives you access to the ws server object, allowing to pass down custom listeners, connection validators, etc.

In case ctx.ws conflicts with something else in your code, koa-easy-ws doesn't mind changing the property name, just pass it as a property. This also lets you use multiple websocket middlewares if you ever find a reason to do so:

1const Koa = require('koa')
2const websocket = require('koa-easy-ws')
3
4const app = new Koa()
5
6app.use(websocket('sidious')) // we just renamed ctx.ws to ctx.sidious
7app.use(websocket('maul')) // attach another one for no good reason
8
9app.use(async (ctx, next) => {
10  // the first middleware detected an upgrade request
11  if (ctx.sidious) {
12    const socket = await ctx.sidious()
13    return socket.send('this is getting out of hand')
14  }
15
16  // the second middleware detected the same upgrade request
17  if (ctx.maul) {
18    const socket = await ctx.maul()
19    return socket.send('now there are two of them')
20  }
21})

Note: in this example ctx.maul is never used because there is no limit on the authority of ctx.sidious. However, if you define custom logic this technique could sort incoming requests to separate websocket servers.

From here, the sky is the limit, unless you work for SpaceX.

Special usage for Node 9 or earlier

Node's HTTP server doesn't send upgrade requests through the normal callback (and thus your Koa middleware chain) prior to version 10, preventing koa-easy-ws from handling them. Because of this, if you target Node 9 or earlier, you must pass your HTTP server to the middleware which handles the workaround:

1const server = http.createServer(app.callback())
2
3app.use(websocket('ws', server))
4
5// alternatively, you can pass it as part of the options object:
6app.use(websocket('ws2', {
7  server: server
8}))
9
10server.listen(process.env.PORT) // use this function instead of your app.listen() call

koa-easy-ws then automatically feeds any upgrade request into your regular middleware chain. If you wish to opt out and do this yourself, use the noServerWorkaround option:

1app.use(websocket('ws', {
2  noServerWorkaround: true
3}))

Contributing

Pull requests are welcome. As always, be respectful towards each other and maybe run or create tests, as appropriate. It's on npm test, as usual.

koa-easy-ws uses the MIT license. Was considering the WTFPL, but I like the "no warranty" clause.