@twin.org/api-server-fastify 0.0.1-next.12 → 0.0.1-next.13

package/dist/cjs/index.cjs

@@ -7,6 +7,19 @@ var core = require('@twin.org/core');
 var loggingModels = require('@twin.org/logging-models');
 var web = require('@twin.org/web');
 var Fastify = require('fastify');
+var fp = require('fastify-plugin');
+var socket_io = require('socket.io');
+
+// This is a clone of fastify-socket.io which runs with recent fastify versions.
+const fastifySocketIO = fp(async (fastify, opts) => {
+    const ioServer = new socket_io.Server(fastify.server, opts);
+    fastify.decorate("io", ioServer);
+    fastify.addHook("preClose", done => {
+        ioServer.disconnectSockets();
+        ioServer.close();
+        done();
+    });
+}, { fastify: ">=5.x.x", name: "socket.io" });
 
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
@@ -48,6 +61,11 @@ class FastifyWebServer {
      * @internal
      */
     _fastify;
+    /**
+     * The options for the socket server.
+     * @internal
+     */
+    _socketConfig;
     /**
      * Whether the server has been started.
      * @internal
@@ -58,20 +76,33 @@ class FastifyWebServer {
      * @internal
      */
     _mimeTypeProcessors;
+    /**
+     * Include the stack with errors.
+     * @internal
+     */
+    _includeErrorStack;
     /**
      * Create a new instance of FastifyWebServer.
      * @param options The options for the server.
      * @param options.loggingConnectorType The type of the logging connector to use, if undefined, no logging will happen.
-     * @param options.config Additional options for the Fastify server.
      * @param options.mimeTypeProcessors Additional MIME type processors.
+     * @param options.config Additional configuration for the server.
      */
     constructor(options) {
         this._loggingConnector = core.Is.stringValue(options?.loggingConnectorType)
             ? loggingModels.LoggingConnectorFactory.get(options.loggingConnectorType)
             : undefined;
-        this._fastify = Fastify({ maxParamLength: 2000, ...options?.config });
+        this._fastify = Fastify({
+            maxParamLength: 2000,
+            ...options?.config?.web
+        });
+        this._socketConfig = {
+            path: "/socket",
+            ...options?.config?.socket
+        };
         this._started = false;
         this._mimeTypeProcessors = options?.mimeTypeProcessors ?? [];
+        this._includeErrorStack = options?.config?.includeErrorStack ?? false;
     }
     /**
      * Get the web server instance.
@@ -82,14 +113,19 @@ class FastifyWebServer {
     }
     /**
      * Build the server.
-     * @param restRouteProcessors The hooks to process the incoming requests.
+     * @param restRouteProcessors The processors for incoming requests over REST.
      * @param restRoutes The REST routes.
+     * @param socketRouteProcessors The processors for incoming requests over Sockets.
+     * @param socketRoutes The socket routes.
      * @param options Options for building the server.
      * @returns Nothing.
      */
-    async build(restRouteProcessors, restRoutes, options) {
-        if (!core.Is.arrayValue(restRouteProcessors)) {
-            throw new core.GeneralError(this.CLASS_NAME, "noProcessors");
+    async build(restRouteProcessors, restRoutes, socketRouteProcessors, socketRoutes, options) {
+        if (core.Is.arrayValue(restRoutes) && !core.Is.arrayValue(restRouteProcessors)) {
+            throw new core.GeneralError(this.CLASS_NAME, "noRestProcessors");
+        }
+        if (core.Is.arrayValue(socketRoutes) && !core.Is.arrayValue(socketRouteProcessors)) {
+            throw new core.GeneralError(this.CLASS_NAME, "noSocketProcessors");
         }
         await this._loggingConnector?.log({
             level: "info",
@@ -99,6 +135,9 @@ class FastifyWebServer {
         });
         this._options = options;
         await this._fastify.register(FastifyCompress);
+        if (core.Is.arrayValue(socketRoutes)) {
+            await this._fastify.register(fastifySocketIO, this._socketConfig);
+        }
         if (core.Is.arrayValue(this._mimeTypeProcessors)) {
             for (const contentTypeHandler of this._mimeTypeProcessors) {
                 this._fastify.addContentTypeParser(contentTypeHandler.getTypes(), { parseAs: "buffer" }, async (request, body, done) => {
@@ -113,7 +152,7 @@ class FastifyWebServer {
             }
         }
         await this.initCors(options);
-        this._fastify.setNotFoundHandler({}, async (request, reply) => this.handleRequest(restRouteProcessors, request, reply));
+        this._fastify.setNotFoundHandler({}, async (request, reply) => this.handleRequestRest(restRouteProcessors ?? [], request, reply));
         this._fastify.setErrorHandler(async (error, request, reply) => {
             // If code property is set this is a fastify error
             // otherwise it's from our framework
@@ -143,22 +182,8 @@ class FastifyWebServer {
                 error: err
             });
         });
-        // Add the routes to the server.
-        for (const restRoute of restRoutes) {
-            let path = core.StringHelper.trimTrailingSlashes(restRoute.path);
-            if (!path.startsWith("/")) {
-                path = `/${path}`;
-            }
-            await this._loggingConnector?.log({
-                level: "info",
-                ts: Date.now(),
-                source: this.CLASS_NAME,
-                message: `${FastifyWebServer._CLASS_NAME_CAMEL_CASE}.restRouteAdded`,
-                data: { route: path, method: restRoute.method }
-            });
-            const method = restRoute.method.toLowerCase();
-            this._fastify[method](path, async (request, reply) => this.handleRequest(restRouteProcessors, request, reply, restRoute));
-        }
+        await this.addRoutesRest(restRouteProcessors, restRoutes);
+        await this.addRoutesSocket(socketRouteProcessors, socketRoutes);
     }
     /**
      * Start the server.
@@ -223,14 +248,109 @@ class FastifyWebServer {
         }
     }
     /**
-     * Handle the incoming request.
+     * Add the REST routes to the server.
+     * @param restRouteProcessors The processors for the incoming requests.
+     * @param restRoutes The REST routes to add.
+     * @internal
+     */
+    async addRoutesRest(restRouteProcessors, restRoutes) {
+        if (core.Is.arrayValue(restRouteProcessors) && core.Is.arrayValue(restRoutes)) {
+            for (const restRoute of restRoutes) {
+                let path = core.StringHelper.trimTrailingSlashes(restRoute.path);
+                if (!path.startsWith("/")) {
+                    path = `/${path}`;
+                }
+                await this._loggingConnector?.log({
+                    level: "info",
+                    ts: Date.now(),
+                    source: this.CLASS_NAME,
+                    message: `${FastifyWebServer._CLASS_NAME_CAMEL_CASE}.restRouteAdded`,
+                    data: { route: path, method: restRoute.method }
+                });
+                const method = restRoute.method.toLowerCase();
+                this._fastify[method](path, async (request, reply) => this.handleRequestRest(restRouteProcessors, request, reply, restRoute));
+            }
+        }
+    }
+    /**
+     * Add the socket routes to the server.
+     * @param socketRouteProcessors The processors for the incoming requests.
+     * @param socketRoutes The socket routes to add.
+     * @internal
+     */
+    async addRoutesSocket(socketRouteProcessors, socketRoutes) {
+        if (core.Is.arrayValue(socketRouteProcessors) && core.Is.arrayValue(socketRoutes)) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const io = this._fastify.io;
+            for (const socketRoute of socketRoutes) {
+                const path = core.StringHelper.trimLeadingSlashes(core.StringHelper.trimTrailingSlashes(socketRoute.path));
+                const pathParts = path.split("/");
+                await this._loggingConnector?.log({
+                    level: "info",
+                    ts: Date.now(),
+                    source: this.CLASS_NAME,
+                    message: `${FastifyWebServer._CLASS_NAME_CAMEL_CASE}.socketRouteAdded`,
+                    data: { route: path }
+                });
+                const socketNamespace = io.of(`/${pathParts[0]}`);
+                const topic = pathParts.slice(1).join("/");
+                socketNamespace.on("connection", async (socket) => {
+                    const httpServerRequest = {
+                        method: web.HttpMethod.GET,
+                        url: socket.handshake.url,
+                        query: socket.handshake.query,
+                        headers: socket.handshake.headers
+                    };
+                    // Pass the connected information on to any processors
+                    try {
+                        const processorState = {
+                            socketId: socket.id
+                        };
+                        for (const socketRouteProcessor of socketRouteProcessors) {
+                            if (core.Is.function(socketRouteProcessor.connected)) {
+                                await socketRouteProcessor.connected(httpServerRequest, socketRoute, processorState);
+                            }
+                        }
+                    }
+                    catch (err) {
+                        const { error, httpStatusCode } = apiModels.HttpErrorHelper.processError(err, this._includeErrorStack);
+                        const response = {};
+                        apiModels.HttpErrorHelper.buildResponse(response, error, httpStatusCode);
+                        socket.emit(topic, response);
+                    }
+                    socket.on("disconnect", async () => {
+                        try {
+                            const processorState = {
+                                socketId: socket.id
+                            };
+                            // The socket disconnected so notify any processors
+                            for (const socketRouteProcessor of socketRouteProcessors) {
+                                if (core.Is.function(socketRouteProcessor.disconnected)) {
+                                    await socketRouteProcessor.disconnected(httpServerRequest, socketRoute, processorState);
+                                }
+                            }
+                        }
+                        catch {
+                            // If something fails on a disconnect there is not much we can do with it
+                        }
+                    });
+                    // Handle any incoming messages
+                    socket.on(topic, async (data) => {
+                        await this.handleRequestSocket(socketRouteProcessors, socketRoute, socket, `/${pathParts.join("/")}`, topic, data);
+                    });
+                });
+            }
+        }
+    }
+    /**
+     * Handle the incoming REST request.
      * @param restRouteProcessors The hooks to process the incoming requests.
      * @param request The incoming request.
      * @param reply The outgoing response.
      * @param restRoute The REST route to handle.
      * @internal
      */
-    async handleRequest(restRouteProcessors, request, reply, restRoute) {
+    async handleRequestRest(restRouteProcessors, request, reply, restRoute) {
         const httpServerRequest = {
             method: request.method.toUpperCase(),
             url: `${request.protocol}://${request.hostname}${request.url}`,
@@ -242,21 +362,7 @@ class FastifyWebServer {
         const httpResponse = {};
         const httpRequestIdentity = {};
         const processorState = {};
-        for (const restRouteProcessor of restRouteProcessors) {
-            if (core.Is.function(restRouteProcessor.pre)) {
-                await restRouteProcessor.pre(httpServerRequest, httpResponse, restRoute, httpRequestIdentity, processorState);
-            }
-        }
-        for (const restRouteProcessor of restRouteProcessors) {
-            if (core.Is.function(restRouteProcessor.process)) {
-                await restRouteProcessor.process(httpServerRequest, httpResponse, restRoute, httpRequestIdentity, processorState);
-            }
-        }
-        for (const restRouteProcessor of restRouteProcessors) {
-            if (core.Is.function(restRouteProcessor.post)) {
-                await restRouteProcessor.post(httpServerRequest, httpResponse, restRoute, httpRequestIdentity, processorState);
-            }
-        }
+        await this.runProcessorsRest(restRouteProcessors, restRoute, httpServerRequest, httpResponse, httpRequestIdentity, processorState);
         if (!core.Is.empty(httpResponse.headers)) {
             for (const header of Object.keys(httpResponse.headers)) {
                 reply.header(header, httpResponse.headers[header]);
@@ -266,6 +372,119 @@ class FastifyWebServer {
             .status((httpResponse.statusCode ?? web.HttpStatusCode.ok))
             .send(httpResponse.body);
     }
+    /**
+     * Run the REST processors for the route.
+     * @param restRouteProcessors The processors to run.
+     * @param restRoute The route to process.
+     * @param httpServerRequest The incoming request.
+     * @param httpResponse The outgoing response.
+     * @param httpRequestIdentity The identity context for the request.
+     * @internal
+     */
+    async runProcessorsRest(restRouteProcessors, restRoute, httpServerRequest, httpResponse, httpRequestIdentity, processorState) {
+        try {
+            for (const routeProcessor of restRouteProcessors) {
+                if (core.Is.function(routeProcessor.pre)) {
+                    await routeProcessor.pre(httpServerRequest, httpResponse, restRoute, httpRequestIdentity, processorState);
+                }
+            }
+            for (const routeProcessor of restRouteProcessors) {
+                if (core.Is.function(routeProcessor.process)) {
+                    await routeProcessor.process(httpServerRequest, httpResponse, restRoute, httpRequestIdentity, processorState);
+                }
+            }
+            for (const routeProcessor of restRouteProcessors) {
+                if (core.Is.function(routeProcessor.post)) {
+                    await routeProcessor.post(httpServerRequest, httpResponse, restRoute, httpRequestIdentity, processorState);
+                }
+            }
+        }
+        catch (err) {
+            const { error, httpStatusCode } = apiModels.HttpErrorHelper.processError(err, this._includeErrorStack);
+            apiModels.HttpErrorHelper.buildResponse(httpResponse, error, httpStatusCode);
+        }
+    }
+    /**
+     * Handle the incoming socket request.
+     * @param socketRouteProcessors The hooks to process the incoming requests.
+     * @param socketRoute The socket route to handle.
+     * @param socket The socket to handle.
+     * @param fullPath The full path of the socket route.
+     * @param emitTopic The topic to emit the response on.
+     * @param data The incoming data.
+     * @internal
+     */
+    async handleRequestSocket(socketRouteProcessors, socketRoute, socket, fullPath, emitTopic, data) {
+        const httpServerRequest = {
+            method: web.HttpMethod.GET,
+            url: fullPath,
+            query: socket.handshake.query,
+            headers: socket.handshake.headers
+        };
+        const httpResponse = {};
+        const httpRequestIdentity = {};
+        const processorState = {
+            socketId: socket.id
+        };
+        delete httpServerRequest.query?.EIO;
+        delete httpServerRequest.query?.transport;
+        httpServerRequest.body = data;
+        await this.runProcessorsSocket(socketRouteProcessors, socketRoute, httpServerRequest, httpResponse, httpRequestIdentity, processorState, async () => {
+            await socket.emit(emitTopic, httpResponse);
+        });
+    }
+    /**
+     * Run the socket processors for the route.
+     * @param socketRouteProcessors The processors to run.
+     * @param socketRoute The route to process.
+     * @param httpServerRequest The incoming request.
+     * @param httpResponse The outgoing response.
+     * @param httpRequestIdentity The identity context for the request.
+     * @internal
+     */
+    async runProcessorsSocket(socketRouteProcessors, socketRoute, httpServerRequest, httpResponse, httpRequestIdentity, processorState, responseEmitter) {
+        // Custom emit method which will also call the post processors
+        const postProcessEmit = async (response, responseProcessorState) => {
+            await responseEmitter(response);
+            // The post processors are called after the response has been emitted
+            for (const postSocketRouteProcessor of socketRouteProcessors) {
+                if (core.Is.function(postSocketRouteProcessor.post)) {
+                    await postSocketRouteProcessor.post(httpServerRequest, response, socketRoute, httpRequestIdentity, responseProcessorState);
+                }
+            }
+        };
+        try {
+            for (const socketRouteProcessor of socketRouteProcessors) {
+                if (core.Is.function(socketRouteProcessor.pre)) {
+                    await socketRouteProcessor.pre(httpServerRequest, httpResponse, socketRoute, httpRequestIdentity, processorState);
+                }
+            }
+            // We always call all the processors regardless of any response set by a previous processor.
+            // But if a pre processor sets a status code, we will emit the response manually, as the pre
+            // and post processors do not receive the emit method, they just populate the response object.
+            if (!core.Is.empty(httpResponse.statusCode)) {
+                await postProcessEmit(httpResponse, processorState);
+            }
+            for (const socketRouteProcessor of socketRouteProcessors) {
+                if (core.Is.function(socketRouteProcessor.process)) {
+                    await socketRouteProcessor.process(httpServerRequest, httpResponse, socketRoute, httpRequestIdentity, processorState, async (processResponse) => {
+                        await postProcessEmit(processResponse, processorState);
+                    });
+                }
+            }
+            // If the processors set the status to any kind of error then we should emit this manually
+            if (core.Is.integer(httpResponse.statusCode) &&
+                httpResponse.statusCode >= web.HttpStatusCode.badRequest) {
+                await postProcessEmit(httpResponse, processorState);
+            }
+        }
+        catch (err) {
+            // Emit any unhandled errors manually
+            const { error, httpStatusCode } = apiModels.HttpErrorHelper.processError(err, this._includeErrorStack);
+            apiModels.HttpErrorHelper.buildResponse(httpResponse, error, httpStatusCode);
+            await postProcessEmit(httpResponse, processorState);
+        }
+    }
     /**
      * Initialize the cors options.
      * @param options The web server options.

package/dist/esm/index.mjs

@@ -5,6 +5,19 @@ import { StringHelper, Is, GeneralError, BaseError } from '@twin.org/core';
 import { LoggingConnectorFactory } from '@twin.org/logging-models';
 import { HttpStatusCode, HttpMethod, HeaderTypes } from '@twin.org/web';
 import Fastify from 'fastify';
+import fp from 'fastify-plugin';
+import { Server } from 'socket.io';
+
+// This is a clone of fastify-socket.io which runs with recent fastify versions.
+const fastifySocketIO = fp(async (fastify, opts) => {
+    const ioServer = new Server(fastify.server, opts);
+    fastify.decorate("io", ioServer);
+    fastify.addHook("preClose", done => {
+        ioServer.disconnectSockets();
+        ioServer.close();
+        done();
+    });
+}, { fastify: ">=5.x.x", name: "socket.io" });
 
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
@@ -46,6 +59,11 @@ class FastifyWebServer {
      * @internal
      */
     _fastify;
+    /**
+     * The options for the socket server.
+     * @internal
+     */
+    _socketConfig;
     /**
      * Whether the server has been started.
      * @internal
@@ -56,20 +74,33 @@ class FastifyWebServer {
      * @internal
      */
     _mimeTypeProcessors;
+    /**
+     * Include the stack with errors.
+     * @internal
+     */
+    _includeErrorStack;
     /**
      * Create a new instance of FastifyWebServer.
      * @param options The options for the server.
      * @param options.loggingConnectorType The type of the logging connector to use, if undefined, no logging will happen.
-     * @param options.config Additional options for the Fastify server.
      * @param options.mimeTypeProcessors Additional MIME type processors.
+     * @param options.config Additional configuration for the server.
      */
     constructor(options) {
         this._loggingConnector = Is.stringValue(options?.loggingConnectorType)
             ? LoggingConnectorFactory.get(options.loggingConnectorType)
             : undefined;
-        this._fastify = Fastify({ maxParamLength: 2000, ...options?.config });
+        this._fastify = Fastify({
+            maxParamLength: 2000,
+            ...options?.config?.web
+        });
+        this._socketConfig = {
+            path: "/socket",
+            ...options?.config?.socket
+        };
         this._started = false;
         this._mimeTypeProcessors = options?.mimeTypeProcessors ?? [];
+        this._includeErrorStack = options?.config?.includeErrorStack ?? false;
     }
     /**
      * Get the web server instance.
@@ -80,14 +111,19 @@ class FastifyWebServer {
     }
     /**
      * Build the server.
-     * @param restRouteProcessors The hooks to process the incoming requests.
+     * @param restRouteProcessors The processors for incoming requests over REST.
      * @param restRoutes The REST routes.
+     * @param socketRouteProcessors The processors for incoming requests over Sockets.
+     * @param socketRoutes The socket routes.
      * @param options Options for building the server.
      * @returns Nothing.
      */
-    async build(restRouteProcessors, restRoutes, options) {
-        if (!Is.arrayValue(restRouteProcessors)) {
-            throw new GeneralError(this.CLASS_NAME, "noProcessors");
+    async build(restRouteProcessors, restRoutes, socketRouteProcessors, socketRoutes, options) {
+        if (Is.arrayValue(restRoutes) && !Is.arrayValue(restRouteProcessors)) {
+            throw new GeneralError(this.CLASS_NAME, "noRestProcessors");
+        }
+        if (Is.arrayValue(socketRoutes) && !Is.arrayValue(socketRouteProcessors)) {
+            throw new GeneralError(this.CLASS_NAME, "noSocketProcessors");
         }
         await this._loggingConnector?.log({
             level: "info",
@@ -97,6 +133,9 @@ class FastifyWebServer {
         });
         this._options = options;
         await this._fastify.register(FastifyCompress);
+        if (Is.arrayValue(socketRoutes)) {
+            await this._fastify.register(fastifySocketIO, this._socketConfig);
+        }
         if (Is.arrayValue(this._mimeTypeProcessors)) {
             for (const contentTypeHandler of this._mimeTypeProcessors) {
                 this._fastify.addContentTypeParser(contentTypeHandler.getTypes(), { parseAs: "buffer" }, async (request, body, done) => {
@@ -111,7 +150,7 @@ class FastifyWebServer {
             }
         }
         await this.initCors(options);
-        this._fastify.setNotFoundHandler({}, async (request, reply) => this.handleRequest(restRouteProcessors, request, reply));
+        this._fastify.setNotFoundHandler({}, async (request, reply) => this.handleRequestRest(restRouteProcessors ?? [], request, reply));
         this._fastify.setErrorHandler(async (error, request, reply) => {
             // If code property is set this is a fastify error
             // otherwise it's from our framework
@@ -141,22 +180,8 @@ class FastifyWebServer {
                 error: err
             });
         });
-        // Add the routes to the server.
-        for (const restRoute of restRoutes) {
-            let path = StringHelper.trimTrailingSlashes(restRoute.path);
-            if (!path.startsWith("/")) {
-                path = `/${path}`;
-            }
-            await this._loggingConnector?.log({
-                level: "info",
-                ts: Date.now(),
-                source: this.CLASS_NAME,
-                message: `${FastifyWebServer._CLASS_NAME_CAMEL_CASE}.restRouteAdded`,
-                data: { route: path, method: restRoute.method }
-            });
-            const method = restRoute.method.toLowerCase();
-            this._fastify[method](path, async (request, reply) => this.handleRequest(restRouteProcessors, request, reply, restRoute));
-        }
+        await this.addRoutesRest(restRouteProcessors, restRoutes);
+        await this.addRoutesSocket(socketRouteProcessors, socketRoutes);
     }
     /**
      * Start the server.
@@ -221,14 +246,109 @@ class FastifyWebServer {
         }
     }
     /**
-     * Handle the incoming request.
+     * Add the REST routes to the server.
+     * @param restRouteProcessors The processors for the incoming requests.
+     * @param restRoutes The REST routes to add.
+     * @internal
+     */
+    async addRoutesRest(restRouteProcessors, restRoutes) {
+        if (Is.arrayValue(restRouteProcessors) && Is.arrayValue(restRoutes)) {
+            for (const restRoute of restRoutes) {
+                let path = StringHelper.trimTrailingSlashes(restRoute.path);
+                if (!path.startsWith("/")) {
+                    path = `/${path}`;
+                }
+                await this._loggingConnector?.log({
+                    level: "info",
+                    ts: Date.now(),
+                    source: this.CLASS_NAME,
+                    message: `${FastifyWebServer._CLASS_NAME_CAMEL_CASE}.restRouteAdded`,
+                    data: { route: path, method: restRoute.method }
+                });
+                const method = restRoute.method.toLowerCase();
+                this._fastify[method](path, async (request, reply) => this.handleRequestRest(restRouteProcessors, request, reply, restRoute));
+            }
+        }
+    }
+    /**
+     * Add the socket routes to the server.
+     * @param socketRouteProcessors The processors for the incoming requests.
+     * @param socketRoutes The socket routes to add.
+     * @internal
+     */
+    async addRoutesSocket(socketRouteProcessors, socketRoutes) {
+        if (Is.arrayValue(socketRouteProcessors) && Is.arrayValue(socketRoutes)) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const io = this._fastify.io;
+            for (const socketRoute of socketRoutes) {
+                const path = StringHelper.trimLeadingSlashes(StringHelper.trimTrailingSlashes(socketRoute.path));
+                const pathParts = path.split("/");
+                await this._loggingConnector?.log({
+                    level: "info",
+                    ts: Date.now(),
+                    source: this.CLASS_NAME,
+                    message: `${FastifyWebServer._CLASS_NAME_CAMEL_CASE}.socketRouteAdded`,
+                    data: { route: path }
+                });
+                const socketNamespace = io.of(`/${pathParts[0]}`);
+                const topic = pathParts.slice(1).join("/");
+                socketNamespace.on("connection", async (socket) => {
+                    const httpServerRequest = {
+                        method: HttpMethod.GET,
+                        url: socket.handshake.url,
+                        query: socket.handshake.query,
+                        headers: socket.handshake.headers
+                    };
+                    // Pass the connected information on to any processors
+                    try {
+                        const processorState = {
+                            socketId: socket.id
+                        };
+                        for (const socketRouteProcessor of socketRouteProcessors) {
+                            if (Is.function(socketRouteProcessor.connected)) {
+                                await socketRouteProcessor.connected(httpServerRequest, socketRoute, processorState);
+                            }
+                        }
+                    }
+                    catch (err) {
+                        const { error, httpStatusCode } = HttpErrorHelper.processError(err, this._includeErrorStack);
+                        const response = {};
+                        HttpErrorHelper.buildResponse(response, error, httpStatusCode);
+                        socket.emit(topic, response);
+                    }
+                    socket.on("disconnect", async () => {
+                        try {
+                            const processorState = {
+                                socketId: socket.id
+                            };
+                            // The socket disconnected so notify any processors
+                            for (const socketRouteProcessor of socketRouteProcessors) {
+                                if (Is.function(socketRouteProcessor.disconnected)) {
+                                    await socketRouteProcessor.disconnected(httpServerRequest, socketRoute, processorState);
+                                }
+                            }
+                        }
+                        catch {
+                            // If something fails on a disconnect there is not much we can do with it
+                        }
+                    });
+                    // Handle any incoming messages
+                    socket.on(topic, async (data) => {
+                        await this.handleRequestSocket(socketRouteProcessors, socketRoute, socket, `/${pathParts.join("/")}`, topic, data);
+                    });
+                });
+            }
+        }
+    }
+    /**
+     * Handle the incoming REST request.
      * @param restRouteProcessors The hooks to process the incoming requests.
      * @param request The incoming request.
      * @param reply The outgoing response.
      * @param restRoute The REST route to handle.
      * @internal
      */
-    async handleRequest(restRouteProcessors, request, reply, restRoute) {
+    async handleRequestRest(restRouteProcessors, request, reply, restRoute) {
         const httpServerRequest = {
             method: request.method.toUpperCase(),
             url: `${request.protocol}://${request.hostname}${request.url}`,
@@ -240,21 +360,7 @@ class FastifyWebServer {
         const httpResponse = {};
         const httpRequestIdentity = {};
         const processorState = {};
-        for (const restRouteProcessor of restRouteProcessors) {
-            if (Is.function(restRouteProcessor.pre)) {
-                await restRouteProcessor.pre(httpServerRequest, httpResponse, restRoute, httpRequestIdentity, processorState);
-            }
-        }
-        for (const restRouteProcessor of restRouteProcessors) {
-            if (Is.function(restRouteProcessor.process)) {
-                await restRouteProcessor.process(httpServerRequest, httpResponse, restRoute, httpRequestIdentity, processorState);
-            }
-        }
-        for (const restRouteProcessor of restRouteProcessors) {
-            if (Is.function(restRouteProcessor.post)) {
-                await restRouteProcessor.post(httpServerRequest, httpResponse, restRoute, httpRequestIdentity, processorState);
-            }
-        }
+        await this.runProcessorsRest(restRouteProcessors, restRoute, httpServerRequest, httpResponse, httpRequestIdentity, processorState);
         if (!Is.empty(httpResponse.headers)) {
             for (const header of Object.keys(httpResponse.headers)) {
                 reply.header(header, httpResponse.headers[header]);
@@ -264,6 +370,119 @@ class FastifyWebServer {
             .status((httpResponse.statusCode ?? HttpStatusCode.ok))
             .send(httpResponse.body);
     }
+    /**
+     * Run the REST processors for the route.
+     * @param restRouteProcessors The processors to run.
+     * @param restRoute The route to process.
+     * @param httpServerRequest The incoming request.
+     * @param httpResponse The outgoing response.
+     * @param httpRequestIdentity The identity context for the request.
+     * @internal
+     */
+    async runProcessorsRest(restRouteProcessors, restRoute, httpServerRequest, httpResponse, httpRequestIdentity, processorState) {
+        try {
+            for (const routeProcessor of restRouteProcessors) {
+                if (Is.function(routeProcessor.pre)) {
+                    await routeProcessor.pre(httpServerRequest, httpResponse, restRoute, httpRequestIdentity, processorState);
+                }
+            }
+            for (const routeProcessor of restRouteProcessors) {
+                if (Is.function(routeProcessor.process)) {
+                    await routeProcessor.process(httpServerRequest, httpResponse, restRoute, httpRequestIdentity, processorState);
+                }
+            }
+            for (const routeProcessor of restRouteProcessors) {
+                if (Is.function(routeProcessor.post)) {
+                    await routeProcessor.post(httpServerRequest, httpResponse, restRoute, httpRequestIdentity, processorState);
+                }
+            }
+        }
+        catch (err) {
+            const { error, httpStatusCode } = HttpErrorHelper.processError(err, this._includeErrorStack);
+            HttpErrorHelper.buildResponse(httpResponse, error, httpStatusCode);
+        }
+    }
+    /**
+     * Handle the incoming socket request.
+     * @param socketRouteProcessors The hooks to process the incoming requests.
+     * @param socketRoute The socket route to handle.
+     * @param socket The socket to handle.
+     * @param fullPath The full path of the socket route.
+     * @param emitTopic The topic to emit the response on.
+     * @param data The incoming data.
+     * @internal
+     */
+    async handleRequestSocket(socketRouteProcessors, socketRoute, socket, fullPath, emitTopic, data) {
+        const httpServerRequest = {
+            method: HttpMethod.GET,
+            url: fullPath,
+            query: socket.handshake.query,
+            headers: socket.handshake.headers
+        };
+        const httpResponse = {};
+        const httpRequestIdentity = {};
+        const processorState = {
+            socketId: socket.id
+        };
+        delete httpServerRequest.query?.EIO;
+        delete httpServerRequest.query?.transport;
+        httpServerRequest.body = data;
+        await this.runProcessorsSocket(socketRouteProcessors, socketRoute, httpServerRequest, httpResponse, httpRequestIdentity, processorState, async () => {
+            await socket.emit(emitTopic, httpResponse);
+        });
+    }
+    /**
+     * Run the socket processors for the route.
+     * @param socketRouteProcessors The processors to run.
+     * @param socketRoute The route to process.
+     * @param httpServerRequest The incoming request.
+     * @param httpResponse The outgoing response.
+     * @param httpRequestIdentity The identity context for the request.
+     * @internal
+     */
+    async runProcessorsSocket(socketRouteProcessors, socketRoute, httpServerRequest, httpResponse, httpRequestIdentity, processorState, responseEmitter) {
+        // Custom emit method which will also call the post processors
+        const postProcessEmit = async (response, responseProcessorState) => {
+            await responseEmitter(response);
+            // The post processors are called after the response has been emitted
+            for (const postSocketRouteProcessor of socketRouteProcessors) {
+                if (Is.function(postSocketRouteProcessor.post)) {
+                    await postSocketRouteProcessor.post(httpServerRequest, response, socketRoute, httpRequestIdentity, responseProcessorState);
+                }
+            }
+        };
+        try {
+            for (const socketRouteProcessor of socketRouteProcessors) {
+                if (Is.function(socketRouteProcessor.pre)) {
+                    await socketRouteProcessor.pre(httpServerRequest, httpResponse, socketRoute, httpRequestIdentity, processorState);
+                }
+            }
+            // We always call all the processors regardless of any response set by a previous processor.
+            // But if a pre processor sets a status code, we will emit the response manually, as the pre
+            // and post processors do not receive the emit method, they just populate the response object.
+            if (!Is.empty(httpResponse.statusCode)) {
+                await postProcessEmit(httpResponse, processorState);
+            }
+            for (const socketRouteProcessor of socketRouteProcessors) {
+                if (Is.function(socketRouteProcessor.process)) {
+                    await socketRouteProcessor.process(httpServerRequest, httpResponse, socketRoute, httpRequestIdentity, processorState, async (processResponse) => {
+                        await postProcessEmit(processResponse, processorState);
+                    });
+                }
+            }
+            // If the processors set the status to any kind of error then we should emit this manually
+            if (Is.integer(httpResponse.statusCode) &&
+                httpResponse.statusCode >= HttpStatusCode.badRequest) {
+                await postProcessEmit(httpResponse, processorState);
+            }
+        }
+        catch (err) {
+            // Emit any unhandled errors manually
+            const { error, httpStatusCode } = HttpErrorHelper.processError(err, this._includeErrorStack);
+            HttpErrorHelper.buildResponse(httpResponse, error, httpStatusCode);
+            await postProcessEmit(httpResponse, processorState);
+        }
+    }
     /**
      * Initialize the cors options.
      * @param options The web server options.

package/dist/types/fastifySocketIo.d.ts

@@ -0,0 +1,4 @@
+import type { FastifyPluginAsync } from "fastify";
+import { type ServerOptions } from "socket.io";
+declare const fastifySocketIO: FastifyPluginAsync<Partial<ServerOptions>>;
+export default fastifySocketIO;

package/dist/types/fastifyWebServer.d.ts

@@ -1,5 +1,6 @@
-import { type IHttpRestRouteProcessor, type IMimeTypeProcessor, type IRestRoute, type IWebServer, type IWebServerOptions } from "@twin.org/api-models";
-import { type FastifyInstance, type FastifyServerOptions } from "fastify";
+import { type IMimeTypeProcessor, type IRestRoute, type IRestRouteProcessor, type ISocketRoute, type ISocketRouteProcessor, type IWebServer, type IWebServerOptions } from "@twin.org/api-models";
+import { type FastifyInstance } from "fastify";
+import type { IFastifyWebServerConfig } from "./models/IFastifyWebServerConfig";
 /**
  * Implementation of the web server using Fastify.
  */
@@ -12,12 +13,12 @@ export declare class FastifyWebServer implements IWebServer<FastifyInstance> {
      * Create a new instance of FastifyWebServer.
      * @param options The options for the server.
      * @param options.loggingConnectorType The type of the logging connector to use, if undefined, no logging will happen.
-     * @param options.config Additional options for the Fastify server.
      * @param options.mimeTypeProcessors Additional MIME type processors.
+     * @param options.config Additional configuration for the server.
      */
     constructor(options?: {
         loggingConnectorType?: string;
-        config?: FastifyServerOptions;
+        config?: IFastifyWebServerConfig;
         mimeTypeProcessors?: IMimeTypeProcessor[];
     });
     /**
@@ -27,12 +28,14 @@ export declare class FastifyWebServer implements IWebServer<FastifyInstance> {
     getInstance(): FastifyInstance;
     /**
      * Build the server.
-     * @param restRouteProcessors The hooks to process the incoming requests.
+     * @param restRouteProcessors The processors for incoming requests over REST.
      * @param restRoutes The REST routes.
+     * @param socketRouteProcessors The processors for incoming requests over Sockets.
+     * @param socketRoutes The socket routes.
      * @param options Options for building the server.
      * @returns Nothing.
      */
-    build(restRouteProcessors: IHttpRestRouteProcessor[], restRoutes: IRestRoute[], options?: IWebServerOptions): Promise<void>;
+    build(restRouteProcessors?: IRestRouteProcessor[], restRoutes?: IRestRoute[], socketRouteProcessors?: ISocketRouteProcessor[], socketRoutes?: ISocketRoute[], options?: IWebServerOptions): Promise<void>;
     /**
      * Start the server.
      * @returns Nothing.

package/dist/types/index.d.ts

@@ -1 +1,2 @@
 export * from "./fastifyWebServer";
+export * from "./models/IFastifyWebServerConfig";

package/dist/types/models/IFastifyWebServerConfig.d.ts

@@ -0,0 +1,19 @@
+import type { FastifyServerOptions } from "fastify";
+import type { ServerOptions } from "socket.io";
+/**
+ * The configuration for the Fastify web server.
+ */
+export interface IFastifyWebServerConfig {
+    /**
+     * The web server options.
+     */
+    web?: Partial<FastifyServerOptions>;
+    /**
+     * The socket server options.
+     */
+    socket?: Partial<ServerOptions>;
+    /**
+     * Include the stack with errors.
+     */
+    includeErrorStack?: boolean;
+}

package/docs/changelog.md

@@ -1,5 +1,5 @@
 # @twin.org/api-server-fastify - Changelog
 
-## v0.0.1-next.12
+## v0.0.1-next.13
 
 - Initial Release

package/docs/reference/classes/FastifyWebServer.md

@@ -24,9 +24,9 @@ The options for the server.
 
 The type of the logging connector to use, if undefined, no logging will happen.
 
-• **options.config?**: `FastifyServerOptions`
+• **options.config?**: [`IFastifyWebServerConfig`](../interfaces/IFastifyWebServerConfig.md)
 
-Additional options for the Fastify server.
+Additional configuration for the server.
 
 • **options.mimeTypeProcessors?**: `IMimeTypeProcessor`[]
 
@@ -66,20 +66,28 @@ The web server instance.
 
 ### build()
 
-> **build**(`restRouteProcessors`, `restRoutes`, `options`?): `Promise`\<`void`\>
+> **build**(`restRouteProcessors`?, `restRoutes`?, `socketRouteProcessors`?, `socketRoutes`?, `options`?): `Promise`\<`void`\>
 
 Build the server.
 
 #### Parameters
 
-• **restRouteProcessors**: `IHttpRestRouteProcessor`[]
+• **restRouteProcessors?**: `IRestRouteProcessor`[]
 
-The hooks to process the incoming requests.
+The processors for incoming requests over REST.
 
-• **restRoutes**: `IRestRoute`\<`any`, `any`\>[]
+• **restRoutes?**: `IRestRoute`\<`any`, `any`\>[]
 
 The REST routes.
 
+• **socketRouteProcessors?**: `ISocketRouteProcessor`[]
+
+The processors for incoming requests over Sockets.
+
+• **socketRoutes?**: `ISocketRoute`\<`any`, `any`\>[]
+
+The socket routes.
+
 • **options?**: `IWebServerOptions`
 
 Options for building the server.

package/docs/reference/index.md

@@ -3,3 +3,7 @@
 ## Classes
 
 - [FastifyWebServer](classes/FastifyWebServer.md)
+
+## Interfaces
+
+- [IFastifyWebServerConfig](interfaces/IFastifyWebServerConfig.md)

package/docs/reference/interfaces/IFastifyWebServerConfig.md

@@ -0,0 +1,27 @@
+# Interface: IFastifyWebServerConfig
+
+The configuration for the Fastify web server.
+
+## Properties
+
+### web?
+
+> `optional` **web**: `Partial`\<`FastifyServerOptions`\>
+
+The web server options.
+
+***
+
+### socket?
+
+> `optional` **socket**: `Partial`\<`ServerOptions`\>
+
+The socket server options.
+
+***
+
+### includeErrorStack?
+
+> `optional` **includeErrorStack**: `boolean`
+
+Include the stack with errors.

package/locales/en.json

@@ -7,6 +7,8 @@
 		"stopped": "The Web Server was stopped",
 		"badRequest": "The web server could not handle the request",
 		"restRouteAdded": "Added REST route \"{route}\" \"{method}\"",
-		"noProcessors": "You must configure at least one processor"
+		"socketRouteAdded": "Added socket route \"{route}\"",
+		"noRestProcessors": "You must configure at least one REST processor",
+		"noSocketProcessors": "You must configure at least one socket processor"
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/api-server-fastify",
-	"version": "0.0.1-next.12",
+	"version": "0.0.1-next.13",
 	"description": "Use Fastify as the core web server for APIs",
 	"repository": {
 		"type": "git",
@@ -16,13 +16,14 @@
 	"dependencies": {
 		"@fastify/compress": "8.0.1",
 		"@fastify/cors": "10.0.1",
-		"@twin.org/api-core": "0.0.1-next.12",
-		"@twin.org/api-models": "0.0.1-next.12",
+		"@twin.org/api-core": "0.0.1-next.13",
+		"@twin.org/api-models": "0.0.1-next.13",
 		"@twin.org/core": "next",
 		"@twin.org/logging-models": "next",
 		"@twin.org/nameof": "next",
 		"@twin.org/web": "next",
-		"fastify": "5.0.0"
+		"fastify": "5.1.0",
+		"socket.io": "4.8.1"
 	},
 	"main": "./dist/cjs/index.cjs",
 	"module": "./dist/esm/index.mjs",