expose fastify server in websocket handlers (#67)

* expose fastify server in websocket handlers

* test exposed server type in handlers

Author: einnjo

README.md

@@ -119,6 +119,33 @@ fastify.listen(3000, err => {
 })
 ```
 
+_**NB:** Websocket handlers don't follow the usual `fastify` request lifecycle, they are handled by an independent router. You can still access the fastify server's decorations via `this` in both global and per route handlers_
+
+```js
+'use strict'
+
+const fastify = require('fastify')()
+
+fastify.register(require('fastify-websocket'))
+
+fastify.get('/', { websocket: true }, function wsHandler (connection, req) {
+  // bound to fastify server
+  this.myDecoration.someFunc()
+
+  connection.socket.on('message', message => {
+    // message === 'hi from client'
+    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](https://www.fastify.io/docs/latest/Routes/#full-declaration), adding a `wsHandler` property.
 
 ```js

index.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="node" />
 import { IncomingMessage, ServerResponse, Server } from 'http';
-import { FastifyPlugin, FastifyRequest, RawServerBase, RawServerDefault, RawRequestDefaultExpression, RawReplyDefaultExpression, RequestGenericInterface, ContextConfigDefault } from 'fastify';
+import { FastifyPlugin, FastifyRequest, RawServerBase, RawServerDefault, RawRequestDefaultExpression, RawReplyDefaultExpression, RequestGenericInterface, ContextConfigDefault, FastifyInstance } from 'fastify';
 import * as WebSocket from 'ws';
 import { Duplex } from 'stream';
 
@@ -41,7 +41,7 @@ export interface SocketStream extends Duplex {
 }
 
 export interface WebsocketPluginOptions {
-  handle?: (connection: SocketStream) => void;
+  handle?: (this: FastifyInstance, connection: SocketStream) => void;
   options?: WebSocket.ServerOptions;
 }
 

index.js

@@ -12,7 +12,7 @@ function fastifyWebsocket (fastify, opts, next) {
     return next(new Error('invalid handle function'))
   }
   const handle = opts.handle
-    ? (req, res) => opts.handle(req[kWs], req)
+    ? (req, res) => opts.handle.call(fastify, req[kWs], req)
     : (req, res) => {
       req[kWs].socket.close()
     }
@@ -53,7 +53,7 @@ function fastifyWebsocket (fastify, opts, next) {
       }
 
       router.on('GET', routeOptions.path, (req, _, params) => {
-        const result = wsHandler(req[kWs], req, params)
+        const result = wsHandler.call(fastify, req[kWs], req, params)
 
         if (result && typeof result.catch === 'function') {
           result.catch(err => req[kWs].destroy(err))

test/router.js

@@ -371,3 +371,65 @@ test('Should not thow error when register empgy get with prefix', t => {
     })
   })
 })
+
+test('Should expose fastify instance to websocket global handler', t => {
+  const fastify = Fastify()
+
+  t.tearDown(() => fastify.close())
+
+  fastify.register(fastifyWebsocket, {
+    handle: function wsHandler (conn, req) {
+      t.equal(this, fastify, 'this is bound to fastify server')
+      conn.write('empty')
+      conn.end()
+    },
+    options: { path: '/ws' }
+  })
+
+  fastify.listen(0, err => {
+    t.error(err)
+    const ws = new WebSocket(
+      'ws://localhost:' + (fastify.server.address()).port + '/ws'
+    )
+    const client = WebSocket.createWebSocketStream(ws, { encoding: 'utf8' })
+    t.tearDown(client.destroy.bind(client))
+
+    client.setEncoding('utf8')
+
+    client.once('data', chunk => {
+      t.equal(chunk, 'empty')
+      client.end()
+      t.end()
+    })
+  })
+})
+
+test('Should expose fastify instance to websocket per-route handler', t => {
+  const fastify = Fastify()
+
+  t.tearDown(() => fastify.close())
+
+  fastify.register(fastifyWebsocket)
+  fastify.get('/ws', { websocket: true }, function wsHandler (conn, req) {
+    t.equal(this, fastify, 'this is bound to fastify server')
+    conn.write('empty')
+    conn.end()
+  })
+
+  fastify.listen(0, err => {
+    t.error(err)
+    const ws = new WebSocket(
+      'ws://localhost:' + (fastify.server.address()).port + '/ws'
+    )
+    const client = WebSocket.createWebSocketStream(ws, { encoding: 'utf8' })
+    t.tearDown(client.destroy.bind(client))
+
+    client.setEncoding('utf8')
+
+    client.once('data', chunk => {
+      t.equal(chunk, 'empty')
+      client.end()
+      t.end()
+    })
+  })
+})

test/types/index.test-d.ts

@@ -4,25 +4,25 @@ import { expectType } from 'tsd';
 import { Server as HttpServer, IncomingMessage } from 'http'
 import { Server } from 'ws';
 
-const handler: WebsocketHandler = (
+const app: FastifyInstance = fastify();
+app.register(wsPlugin);
+app.register(wsPlugin, {});
+app.register(wsPlugin, {
+  handle: function globalHandler(connection: SocketStream): void {
+    expectType<FastifyInstance>(this);
+    expectType<SocketStream>(connection)
+  }
+});
+app.register(wsPlugin, { options: { perMessageDeflate: true } });
+
+app.get('/', { websocket: true }, function perRouteHandler(
   connection: SocketStream,
   req: IncomingMessage,
   params
-) => {
+) {
+  expectType<FastifyInstance>(this);
   expectType<SocketStream>(connection);
   expectType<Server>(app.websocketServer);
   expectType<IncomingMessage>(req)
   expectType<{ [key: string]: any } | undefined>(params);
-};
-
-const handle = (connection: SocketStream): void => {
-  expectType<SocketStream>(connection)
-}
-
-const app: FastifyInstance = fastify();
-app.register(wsPlugin);
-app.register(wsPlugin, {});
-app.register(wsPlugin, { handle } );
-app.register(wsPlugin, { options: { perMessageDeflate: true } });
-
-app.get('/', { websocket: true }, handler);
+});