fastify-websocket
![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)
WebSocket support for Fastify.
Built upon ws.
Install
npm install fastify-websocket --save
Usage
After registering this plugin, you can choose on which routes the WS server will respond. This can be achieved by adding websocket: true
property to routeOptions
on a fastify's .get
route. In this case two arguments will be passed to the handler, the socket connection, and the fastify
request object:
'use strict'
const fastify = require('fastify')()
fastify.register(require('fastify-websocket'))
fastify.get('/', { websocket: true }, (connection , req ) => {
connection.socket.on('message', message => {
connection.socket.send('hi from server')
})
})
fastify.listen(3000, err => {
if (err) {
fastify.log.error(err)
process.exit(1)
}
})
In this case, it will respond with a 404 error on every unregistered route, closing the incoming upgrade connection requests.
However, you can still define a wildcard route, that will be used as default handler:
'use strict'
const fastify = require('fastify')()
fastify.register(require('fastify-websocket'), {
options: { maxPayload: 1048576 }
})
fastify.get('/*', { websocket: true }, (connection , req ) => {
connection.socket.on('message', message => {
connection.socket.send('hi from wildcard route')
})
})
fastify.get('/', { websocket: true }, (connection , req ) => {
connection.socket.on('message', message => {
connection.socket.send('hi from server')
})
})
fastify.listen(3000, err => {
if (err) {
fastify.log.error(err)
process.exit(1)
}
})
Attaching event handlers
It is important that websocket route handlers attach event handlers synchronously during handler execution to avoid accidentally dropping messages. If you want to do any async work in your websocket handler, say to authenticate a user or load data from a datastore, ensure you attach any on('message')
handlers before you trigger this async work. Otherwise, messages might arrive whilst this async work is underway, and if there is no handler listening for this data it will be silently dropped.
Here is an example of how to attach message handlers synchronously while still accessing asynchronous resources. We store a promise for the async thing in a local variable, attach the message handler synchronously, and then make the message handler itself asynchronous to grab the async data and do some processing:
fastify.get('/*', { websocket: true }, (connection, request) => {
const sessionPromise = request.getSession()
connection.socket.on('message', async (message) => {
const session = await sessionPromise()
})
})
NB
This plugin uses the same router as the fastify
instance, this has a few implications to take into account:
- Websocket route handlers follow the usual
fastify
request lifecycle. - You can access the fastify server via
this
in your handlers - You can access the fastify request decorations via the
req
object your handlers - When using
fastify-websocket
, it needs to be registered before all routes in order to be able to intercept websocket connections to existing routes and close the connection on non-websocket routes.
'use strict'
const fastify = require('fastify')()
fastify.register(require('fastify-websocket'))
fastify.get('/', { websocket: true }, function wsHandler (connection, req) {
this.myDecoration.someFunc()
connection.socket.on('message', message => {
connection.socket.send('hi from server')
})
})
fastify.listen(3000, err => {
if (err) {
fastify.log.error(err)
process.exit(1)
}
})
If you need to handle both HTTP requests and incoming socket connections on the same route, you can still do it using the full declaration syntax, adding a wsHandler
property.
'use strict'
const fastify = require('fastify')()
function handle (conn, req) {
conn.pipe(conn)
}
fastify.register(require('fastify-websocket'), {
handle,
options: { maxPayload: 1048576 }
})
fastify.route({
method: 'GET',
url: '/hello',
handler: (req, reply) => {
reply.send({ hello: 'world' })
},
wsHandler: (conn, req) => {
conn.setEncoding('utf8')
conn.write('hello client')
conn.once('data', chunk => {
conn.end()
})
}
})
fastify.listen(3000, err => {
if (err) {
fastify.log.error(err)
process.exit(1)
}
})
Custom error handler:
You can optionally provide a custom errorHandler that will be used to handle any cleaning up:
'use strict'
const fastify = require('fastify')()
fastify.register(require('fastify-websocket'), {
errorHandler: function (error, conn , req , reply ) {
conn.destroy(error)
},
options: {
maxPayload: 1048576,
verifyClient: function (info, next) {
if (info.req.headers['x-fastify-header'] !== 'fastify is awesome !') {
return next(false)
}
next(true)
}
}
})
fastify.get('/', { websocket: true }, (connection , req ) => {
connection.socket.on('message', message => {
connection.socket.send('hi from server')
})
})
fastify.listen(3000, err => {
if (err) {
fastify.log.error(err)
process.exit(1)
}
})
Options
fastify-websocket
accept these options for ws
:
objectMode
- Send each chunk on its own, and do not try to pack them in a single websocket frame.host
- The hostname where to bind the server.port
- The port where to bind the server.backlog
- The maximum length of the queue of pending connections.server
- A pre-created Node.js HTTP/S server.verifyClient
- A function which can be used to validate incoming connections.handleProtocols
- A function which can be used to handle the WebSocket subprotocols.clientTracking
- Specifies whether or not to track clients.perMessageDeflate
- Enable/disable permessage-deflate.maxPayload
- The maximum allowed message size in bytes.
For more information, you can check ws
options documentation.
NB By default if you do not provide a server
option fastify-websocket
will bind your websocket server instance to the scoped fastify
instance.
NB The path
option from ws
should not be provided since the routing is handled by fastify itself
NB The noServer
option from ws
should not be provided since the point of fastify-websocket is to listen on the fastify server. If you want a custom server, you can use the server
option, and if you want more control, you can use the ws
library directly
Acknowledgements
This project is kindly sponsored by nearForm.
License
Licensed under MIT.