@fastify/websocket

WebSocket route handlers must attach event handlers (like socket.on('message', ...) ) synchronously during the handler's execution. If you perform asynchronous work (like database lookups or authentication) before attaching the handler, incoming messages might arrive while the async work is pending, causing them to be silently dropped because no listener is yet active.

Best Practice:

1. Initiate the async work synchronously (e.g., call a function that returns a Promise).
2. Attach the socket.on('message', ...) handler immediately.
3. Inside the message handler, await the previously initiated Promise to access the required data.

fastify.get('/*', { websocket: true }, (socket, request) => {
  // 1. Start async work synchronously, returning a promise
  const sessionPromise = request.getSession()

  // 2. Attach handler synchronously
  socket.on('message', async (message) => {
    // 3. Await the data inside the handler
    const session = await sessionPromise()
    // do something with the message and session
  })
})

WebSocket routes respect Fastify's plugin encapsulation and lifecycle hooks, but with specific limitations:

• Supported Hooks: Hooks that run before the connection is established (upgraded) will work. This includes onRequest, preParsing, preValidation, and preHandler. These are ideal for authentication.
• Unsupported Hooks: Hooks related to response serialization and transmission (preSerialization, onSend) do not run for WebSocket routes because message handling occurs outside the standard HTTP lifecycle once the connection is upgraded.

To transform outgoing messages, you must implement that logic manually within your handler before calling socket.send().

fastify.addHook('preValidation', async (request, reply) => {
  // This works for authentication
  if (!request.isAuthenticated()) {
    await reply.code(401).send("not authenticated");
  }
})

fastify.get('/', { websocket: true }, (socket, req) => {
  // The connection only opens if preValidation passes
  socket.on('message', message => {
    // ...
  })
})

To enable WebSocket support on a specific route, register the @fastify/websocket plugin and add the websocket: true property to the routeOptions of a .get route. The handler will receive two arguments: the socket (the WebSocket connection) and the req (the FastifyRequest object).

Note: If you do not register a route with websocket: true, the server will respond with a 404 error for incoming upgrade requests on that path. You can use a wildcard route (e.g., /*) to provide a default WebSocket handler.

'use strict'

const fastify = require('fastify')()
fastify.register(require('@fastify/websocket'))
fastify.register(async function (fastify) {
  fastify.get('/', { websocket: true }, (socket /* WebSocket */, req /* FastifyRequest */) => {
    socket.on('message', message => {
      socket.send('hi from server')
    })
  })
})

fastify.listen({ port: 3000 }, err => {
  if (err) {
    fastify.log.error(err)
    process.exit(1)
  }
})

The @fastify/websocket plugin decorates the Fastify instance with injectWS, which simplifies testing WebSocket endpoints.

Usage:

• Call fastify.injectWS(path, [upgradeContext]).
• fastify.ready() must be awaited before calling injectWS to ensure decorations are applied.
• You must manually close/terminate the WebSocket at the end of your test.
• Register your event listeners (e.g., ws.on('message', ...)) before sending messages to ensure you can capture the response.

'use strict'
const { test } = require('node:test')
const fastify = require('./app.js')

test('connect to /', async (t) => {
  t.plan(1)

  t.after(() => fastify.close())
  await fastify.ready()

  // Inject WebSocket connection
  const ws = await fastify.injectWS('/', {headers: { "api-key" : "some-random-key" }})

  let resolve;
  const promise = new Promise(r => { resolve = r })

  ws.on('message', (data) => {
    resolve(data.toString());
  })
  
  ws.send('hi from client')

  t.assert.deepStrictEqual(await promise, 'hi from server')
  
  // Manual cleanup
  ws.terminate()
})

You can provide a custom errorHandler when registering the @fastify/websocket plugin. This handler is called when:

1. An error is thrown by your WebSocket route handler after the connection is established.
2. An error event is emitted by the WebSocket connection itself (e.g., an unclean client disconnect).

Important Notes:

• This errorHandler is not the same as Fastify's setErrorHandler or onError hook. Fastify's standard error handlers only work for errors encountered before the connection is upgraded (e.g., in onRequest or preValidation).
• Neither the plugin's errorHandler nor Fastify's onError will catch errors thrown inside your socket.on('message', ...) handlers. You must use try/catch blocks within your message handlers to manage those errors.

const fastify = require('fastify')()

fastify.register(require('@fastify/websocket'), {
  errorHandler: function (error, socket /* WebSocket */, req /* FastifyRequest */, reply /* FastifyReply */) {
    // Handle cleanup or connection termination
    socket.terminate()
  },
  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 }, (socket, req) => {
  socket.on('message', message => {
    socket.send('hi from server')
  })
})

fastify.listen({ port: 3000 })

If you need a single route to handle both standard HTTP requests and WebSocket connections, use the Fastify full declaration syntax by providing both a handler and a wsHandler property in the route configuration.

'use strict'

const fastify = require('fastify')()

function handle (socket, req) {
  socket.on('message', (data) => socket.send(data))
}

fastify.register(require('@fastify/websocket'), {
  handle,
  options: { maxPayload: 1048576 }
})

fastify.register(async function () {
  fastify.route({
    method: 'GET',
    url: '/hello',
    handler: (req, reply) => {
      // Handles HTTP requests
      reply.send({ hello: 'world' })
    },
    wsHandler: (socket, req) => {
      // Handles WebSocket connections
      socket.send('hello client')

      socket.once('message', chunk => {
        socket.close()
      })
    }
  })
})

fastify.listen({ port: 3000 }, err => {
  if (err) {
    fastify.log.error(err)
    process.exit(1)
  }
})